diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn index f6076b5196..78cdd0e4df 100644 --- a/.acrolinx-config.edn +++ b/.acrolinx-config.edn @@ -21,7 +21,7 @@ " **More info about Acrolinx** -- [Install Acrolinx locally for VSCode](https://review.docs.microsoft.com/en-us/help/contribute/contribute-acrolinx-vscode) +- [Install Acrolinx locally for VS Code](https://review.docs.microsoft.com/en-us/help/contribute/contribute-acrolinx-vscode) - [Report false positives or issues](https://aka.ms/acrolinxbug) "} diff --git a/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md b/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md deleted file mode 100644 index 701e5a16cc..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: 'New C++ 2017 STL library documentation topic ' -about: Create a C++ 2017 doc tracking work item -title: '' -labels: C++17, STL doc work -assignees: '' - ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS 20YY major.minor diff --git a/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md b/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md deleted file mode 100644 index 766ca6ee40..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: 'New C++ 2020 STL library documentation topic ' -about: Create a C++ 2020 doc tracking work item -title: '' -labels: C++20, STL doc work -assignees: '' - ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS 20YY major.minor diff --git a/.github/ISSUE_TEMPLATE/new-c---2023-stl-library-documentation-topic.md b/.github/ISSUE_TEMPLATE/new-c---2023-stl-library-documentation-topic.md deleted file mode 100644 index 0fbcd1114a..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2023-stl-library-documentation-topic.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: New C++ 2023 STL library documentation topic -about: Create an issue to track C++ 2023 STL doc work -title: '' -labels: C++23 -assignees: '' - ---- - -ISO paper for this feature: [PaperID](http link to iso paper) -First implemented in: VS 20YY major.minor diff --git a/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md b/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md deleted file mode 100644 index 77b51776c3..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: 'New C++ STL library documentation topic ' -about: Create a C++ doc tracking work item -title: '' -labels: STL doc work -assignees: '' - ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS YYYY major.minor diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..75dc5da1e0 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,118 @@ +When writing documentation, follow these guidelines: + +## General style tips + +* Get to the point fast. Be concise and clear. +* Talk like a person. +* Simpler is better. +* Be brief. Give customers just enough information to make decisions confidently. Prune excess words. +* Break up long sentences. +* Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/). If there's a conflict between the following guidelines and the Microsoft Writing Style Guide, ask how to resolve it. + +## Grammar + +* Use present tense verbs (is, open) instead of past tense (was, opened). For example, "The method returns a value" instead of "The method will return a value." +* Write factual statements and direct commands. Avoid hypotheticals. +* Use active voice where the subject performs the action. +* Write in second person (you) to speak directly to readers. +* Use gender-neutral language. +* Avoid multiple -ing words that could create ambiguity. +* Keep prepositional phrases simple and clear. +* Place modifiers close to what they modify. +* Use a conversational tone with contractions. +* Don't use "we" or "our" to refer to the authors of the documentation. +* Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." +* Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." +* Use the Oxford comma in lists of three or more items. + +## Capitalization + +* Use sentence-style capitalization for everything except proper nouns. +* Always capitalize proper nouns. +* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun. +* Use title-style capitalization for product and service names. +* Don't use all uppercase for emphasis. + +## Numbers + +* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above. +* Spell out numbers at the beginning of a sentence. +* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers. +* Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists. + +## Punctuation + +* Use short, simple sentences. +* End all sentences with a period. +* Use one space after punctuation marks. +* After a colon, capitalize only proper nouns. +* Avoid semicolons - use separate sentences instead. +* Use question marks sparingly. +* Don't use slashes (/) - use "or" instead. + +## Text formatting + +* UI elements, like menu items, dialog names, and names of text boxes, should be in **bold** text. +* Use `code style` for: + * Code elements, like method names, property names, and language keywords. + * SQL commands. + * NuGet package names. + * Command-line commands. + * Database table and column names. + * Resource names (like virtual machine names) that shouldn't be localized. + * URLs that you don't want to be selectable. + * File names and folders, custom types, and other text that should never be localized. +* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text. + +## Headings + +* Headings should be in sentence case, not title case. Don't use gerunds in titles. +* Don't apply an inline style like italic, or bold to headings. But do use inline code style for headings that are code elements, like method names or property names. + +## Alerts + +* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: + + * `[!NOTE]` Information the user should notice even if skimming. + * `[!TIP]` Optional information to help a user be more successful. + * `[!IMPORTANT]` Essential information required for user success. + * `[!CAUTION]` Negative potential consequences of an action. + * `[!WARNING]` Dangerous certain consequences of an action. + +## Adding links + +* Add links to related topics and resources where appropriate. +* Links to other documentation articles should be relative, not absolute. Start relative links with `/docs/` and include the `.md` suffix. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link. +* Links to bookmarks within the same article should be relative and start with `#`. +* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". +* When you are going to refer to another file or an article on the web, use this format: "For more information, see [descriptive name of link](link path)." The exception to this is the See Also links at the end of an article. Those should be markdown links and contain the title of the article you link to as the descriptive portion of the link. + +## Adding new files + +* If you add a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name. +* If you're adding a new Markdown file, the following indicates where it should go the folder structure. If you aren't sure, ask. + If the new file is about Linux, put it in the docs/linux folder. + If the new file is about the C++ Standard Template Library (STL), put it in the docs/standard-library folder. + If the new file is about the C runtime, put it in the docs/c-runtime-library folder. + If the new file is about the C++ language, put it in the docs/cpp folder. + If the new file is about a C++ feature specific to the Visual Studio IDE, put it in the docs/ide folder. + If the new file is about the build process or modules, put it in the docs/build\reference folder. + If the new file is about Build Insights, put it in the docs/build-insights folder. + +## Images + +* Use images only when they add value. +* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".". +* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".". + +## Numbered steps + +* Write complete sentences with capitalization and periods +* Use imperative verbs +* Clearly indicate where actions take place (UI location) +* For single steps, use a bullet instead of a number +* When allowed, use angle brackets for menu sequences (File > Open) + +## Terminology + +* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes. \ No newline at end of file diff --git a/.gitignore b/.gitignore index 50628e8f13..10b0192bf5 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ _themes.MSDN.Modern/ _themes.VS.Modern/ # Ignore local configuration changes -.github/ +#.github/ .openpublishing.buildcore.ps1 .vscode/ diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef76202..0000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index f5a51a2a9d..296bfe4f38 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -25,14 +25,11 @@ } ], "notification_subscribers": [], - "sync_notification_subscribers": null, + "sync_notification_subscribers": [], "branches_to_filter": [], - "git_repository_url_open_to_public_contributors": "https://github.com/Microsoft/cpp-docs", - "git_repository_branch_open_to_public_contributors": "master", - "skip_source_output_uploading": false, + "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/cpp-docs", + "git_repository_branch_open_to_public_contributors": "main", "need_preview_pull_request": true, - "enable_incremental_build": true, - "contribution_branch_mappings": null, "dependent_repositories": [ { "path_to_root": "_themes", @@ -57,15 +54,16 @@ "Pdf" ] }, - "need_generate_pdf_url_template": true, "targets": { "Pdf": { "template_folder": "_themes.pdf" } }, + "docs_build_engine": {}, + "skip_source_output_uploading": false, + "enable_incremental_build": true, + "contribution_branch_mappings": null, + "need_generate_pdf_url_template": true, "need_generate_pdf": false, - "need_generate_intellisense": false, - "docs_build_engine": { - "name": "docfx_v3" - } + "need_generate_intellisense": false } \ No newline at end of file diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index d1cfe5032a..e6910b5922 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,10 @@ { "redirections": [ + { + "source_path": "docs/windows/desktop-applications-visual-cpp.md", + "redirect_url": "/cpp/windows/overview-of-windows-programming-in-cpp", + "redirect_document_id": true + }, { "source_path": "docs/cpp-conformance-improvements-2017.md", "redirect_url": "/cpp/overview/cpp-conformance-improvements", @@ -860,6 +865,21 @@ "redirect_url": "/cpp/build/reference/running-nmake", "redirect_document_id": false }, + { + "source_path": "docs/build/manifest-generation-in-visual-studio.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#manifest-generation-in-visual-studio", + "redirect_document_id": false + }, + { + "source_path": "docs/build/manifest-generation-at-the-command-line.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#manifest-generation-at-the-command-line", + "redirect_document_id": false + }, + { + "source_path": "docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#how-to-embed-a-manifest-inside-a-c-cpp-application", + "redirect_document_id": false + }, { "source_path": "docs/build/unwind-data-for-exception-handling-debugger-support.md", "redirect_url": "/cpp/build/exception-handling-x64", @@ -7730,6 +7750,21 @@ "redirect_url": "/cpp/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599", "redirect_document_id": false }, + { + "source_path": "docs/error-messages/compiler-errors-1/fatal-error-c999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, + { + "source_path": "docs/error-messages/compiler-errors-1/fatal-error-c1000-c1999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, + { + "source_path": "docs/error-messages/compiler-warnings/compiler-warning-level-1-c4999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, { "source_path": "docs/error-messages/compiler-warnings/index.md", "redirect_url": "/cpp/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199", @@ -13724,6 +13759,11 @@ "source_path": "docs/c-runtime-library/operator-new-crt.md", "redirect_url": "docs/c-runtime-library/new-operator-crt", "redirect_document_id": false + }, + { + "source_path": "docs/overview/whats-new-cpp-docs.md", + "redirect_url": "../../cpp/overview/what-s-new-for-visual-cpp-in-visual-studio", + "redirect_document_id": false } ] -} +} \ No newline at end of file diff --git a/.whatsnew.json b/.whatsnew.json index 6c3360626c..a5807f933e 100644 --- a/.whatsnew.json +++ b/.whatsnew.json @@ -1,5 +1,5 @@ { - "$schema": "https://whatsnewapi.azurewebsites.net/schema", + "$schema": "https://github.com/dotnet/docs-tools/blob/main/WhatsNew.Infrastructure/Configuration/reposettings.schema.json", "docSetProductName": "C++, C, and Assembler", "rootDirectory": "docs/", "docLinkSettings": { @@ -10,10 +10,18 @@ "minAdditionsToFile": 2, "pullRequestTitlesToIgnore": [ "^Confirm merge from FromPublicMasterBranch", - "^Repo sync for protected CLA branch" + "^Repo sync for protected CLA branch", + "^Repo sync for protected branch" ], "omitPullRequestTitles": false }, + "navigationOptions": { + "maximumNumberOfArticles": 2, + "tocParentNode": " ", + "repoTocFolder": " ", + "indexParentNode": " ", + "repoIndexFolder": " " + }, "areas": [ {"names": ["assembler", "intrinsics"], "heading": "C/C++ compiler intrinsics and assembly language"}, {"names": ["atl", "atl-mfc-shared", "mfc"], "heading": "Active Template Library (ATL), Microsoft Foundation Classes (MFC)"}, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a52d3bc599..bbfa443111 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,13 @@ Thank you for your interest in contributing to the Visual C++ documentation! -In this topic, you'll see the basic process for adding or updating content in the [Visual C++ documentation site](https://docs.microsoft.com/cpp). +In this topic, you'll see the basic process for adding or updating content in the [Visual C++ documentation site](https://learn.microsoft.com/cpp/). In this topic, we'll cover: - [Process for contributing](#process-for-contributing) - [DOs and DON'Ts](#dos-and-donts) -- [Building the docs](#building-the-docs) +- [Building the documentation](#building-the-documentation) - [Contributing to samples](#contributing-to-samples) - [Contributor license agreement](#contributor-license-agreement) @@ -44,7 +44,7 @@ docs wstring-conversion.png ``` -**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/master`. +**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/main`. If your PR is addressing an existing issue, add the `Fixes #Issue_Number` keyword to the commit message or PR description, so the issue can be automatically closed when the PR is merged. For more information, see [Closing issues via commit messages](https://help.github.com/articles/closing-issues-via-commit-messages/). @@ -52,9 +52,9 @@ The Visual Studio team will review your PR and let you know if the change looks **Step 6:** Make any necessary updates to your branch as discussed with the team. -The maintainers will merge your PR into the master branch once feedback has been applied and your change looks good. +The maintainers will merge your PR into the main branch once feedback has been applied and your change looks good. -On a certain cadence, we push all commits from master branch into the live branch and then you'll be able to see your contribution live on [docs.microsoft.com](https://docs.microsoft.com/cpp/). +On a certain cadence, we push all commits from main branch into the live branch and then you'll be able to see your contribution on [Microsoft Learn](https://learn.microsoft.com/cpp/). ## DOs and DON'Ts @@ -70,11 +70,11 @@ Below is a short list of guiding rules that you should keep in mind when you are > [!NOTE] > You might notice that some of the topics are not currently following all the guidelines specified here and on the [style guide](./styleguide/template.md) as well. We're working towards achieving consistency throughout the site. Check the list of [open issues](https://github.com/MicrosoftDocs/cpp-docs/issues?q=is%3Aissue+is%3Aopen+label%3Aguidelines-adherence) we're currently tracking for that specific goal. -## Building the docs +## Building the documentation -The documentation is written in [GitHub Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing/building tools. It is hosted at [docs.microsoft.com](https://docs.microsoft.com/). +The documentation is written in [GitHub-Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing and build tools. It's published to [Microsoft Learn](https://learn.microsoft.com/). -If you want to build the docs locally, you need to install [DocFX](https://dotnet.github.io/docfx/); latest versions are the best. +If you want to build the documentation locally, you need to install the latest version of [DocFX](https://dotnet.github.io/docfx/). There are several ways to use DocFX, and most of them are covered in the [DocFX getting started guide](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html). The following instructions use the [command-line based](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) version of the tool. If you are comfortable with other ways listed on the link above, feel free to use those. @@ -94,6 +94,6 @@ For now, include required sample code as inline code blocks in your article. The ## Contributor license agreement -You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects in docs.microsoft.com. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. +You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects on Microsoft Learn. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. You don't have to sign the agreement up-front. You can clone, fork, and submit your PR as usual. When your PR is created, it is classified by a CLA bot. If the change is trivial (for example, you fixed a typo), then the PR is labeled with CLA-not-required. Otherwise, it's classified as CLA-required. Once you signed the CLA, the current and all future pull requests are labeled as CLA-signed. diff --git a/README.md b/README.md index a02389709b..816a2293bf 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# Visual Studio documentation for Microsoft C++ +# Microsoft C++, C, and Assembler documentation -Welcome! This repository contains source files for the work-in-progress Microsoft C++ (MSVC or Visual C++) technical documentation. The articles are published on the [C++ in Visual Studio documentation site](https://docs.microsoft.com/cpp). +Welcome! This repository contains source files for the technical documentation published on [https://learn.microsoft.com/cpp](https://learn.microsoft.com/cpp). -The documentation for Visual Basic and Visual C# are located in a separate repository at [https://github.com/dotnet/core-docs](https://github.com/dotnet/core-docs), and the Visual Studio documentation is located in the repository located at [https://github.com/Microsoft/visualstudio-docs](https://github.com/Microsoft/visualstudio-docs). +The documentation for [.NET](https://github.com/dotnet/docs) and [Visual Studio](https://github.com/MicrosoftDocs/visualstudio-docs) are located in separate repositories. ## Contributing to the documentation -We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing to docs.microsoft.com, see the [Microsoft Docs contributor guide overview](https://docs.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see the [Contributing guide](CONTRIBUTING.md). +We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing, see the [Microsoft Docs contributor guide](https://learn.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see our [Contributing guidance](CONTRIBUTING.md). -Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio interactive development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. +Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio integrated development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. ## Microsoft Open Source Code of Conduct diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..675ad2a215 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ + + +## Security + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, such as [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), and [our GitHub organizations](https://opensource.microsoft.com/). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + + * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). + + diff --git a/docs/_breadcrumb/toc.yml b/docs/_breadcrumb/toc.yml index efaed4b8a9..363d1dad6b 100644 --- a/docs/_breadcrumb/toc.yml +++ b/docs/_breadcrumb/toc.yml @@ -1,129 +1,3 @@ -items: -- name: Docs - tocHref: / - topicHref: / - items: - - name: Microsoft C++, C, and Assembler - tocHref: /cpp/ - topicHref: /cpp/index - items: - - name: Compiler intrinsics and assembly language - tocHref: /cpp/intrinsics/ - topicHref: /cpp/intrinsics/index - items: - - name: Compiler intrinsics - tocHref: /cpp/intrinsics/ - topicHref: /cpp/intrinsics/compiler-intrinsics - - name: ARM and ARM64 assembler - tocHref: /cpp/assembler/arm/ - topicHref: /cpp/assembler/arm/arm-assembler-reference - - name: C/C++ x86 inline assembler - tocHref: /cpp/assembler/inline/ - topicHref: /cpp/assembler/inline/inline-assembler - - name: x86 and x64 assembler - tocHref: /cpp/assembler/masm/ - topicHref: /cpp/assembler/masm/microsoft-macro-assembler-reference - - name: ATL - tocHref: /cpp/atl/ - topicHref: /cpp/atl/atl-com-desktop-components - - name: ATL/MFC shared classes - tocHref: /cpp/atl-mfc-shared/ - topicHref: /cpp/atl-mfc-shared/atl-mfc-shared-classes - items: - - name: ATL/MFC reference - tocHref: /cpp/atl-mfc-shared/reference/ - topicHref: /cpp/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl - - name: Build C/C++ projects - tocHref: /cpp/build/ - topicHref: /cpp/build/building-c-cpp-programs - items: - - name: Build reference - tocHref: /cpp/build/reference/ - topicHref: /cpp/build/reference/c-cpp-building-reference - - name: Build insights - tocHref: /cpp/build-insights/ - topicHref: /cpp/build-insights/index - - name: C language - tocHref: /cpp/c-language/ - topicHref: /cpp/c-language/index - - name: C runtime library - tocHref: /cpp/c-runtime-library/ - topicHref: /cpp/c-runtime-library/c-run-time-library-reference - items: - - name: UCRT reference - tocHref: /cpp/c-runtime-library/reference/ - topicHref: /cpp/c-runtime-library/reference/crt-alphabetical-function-reference - - name: Cloud and web - tocHref: /cpp/cloud/ - topicHref: /cpp/cloud/cloud-and-web-programming-in-visual-cpp - - name: Code analysis - tocHref: /cpp/code-quality/ - topicHref: /cpp/code-quality/index - - name: Code sanitizers - tocHref: /cpp/sanitizers/ - topicHref: /cpp/sanitizers/index - - name: C++ language - tocHref: /cpp/cpp/ - topicHref: /cpp/cpp/index - - name: C++/CX - tocHref: /cpp/cppcx/ - topicHref: /cpp/cppcx/visual-c-language-reference-c-cx - - name: Cross-platform mobile development - tocHref: /cpp/cross-platform/ - topicHref: /cpp/cross-platform/index - - name: Data access - tocHref: /cpp/data/ - topicHref: /cpp/data/data-access-in-cpp - items: - - name: OLEDB - tocHref: /cpp/data/oledb/ - topicHref: /cpp/data/oledb/ole-db-programming - - name: ODBC - tocHref: /cpp/data/odbc/ - topicHref: /cpp/data/odbc/open-database-connectivity-odbc - - name: C++/CLI for .NET - tocHref: /cpp/dotnet/ - topicHref: /cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp - - name: Errors and warnings - tocHref: /cpp/error-messages/ - topicHref: /cpp/error-messages/compiler-errors-1/c-cpp-build-errors - - name: Edit, navigate, and refactor code - tocHref: /cpp/ide/ - topicHref: /cpp/ide/read-and-understand-code-cpp - - name: Linux - tocHref: /cpp/linux/ - topicHref: /cpp/linux/index - - name: Linux - tocHref: /cpp/build/configure-cmake-debugging-sessions - topicHref: /cpp/linux/index - - name: MFC - tocHref: /cpp/mfc/ - topicHref: /cpp/mfc/mfc-desktop-applications - items: - - name: MFC reference - tocHref: /cpp/mfc/reference/ - topicHref: /cpp/mfc/reference/mfc-classes - - name: Microsoft C/C++ - tocHref: /cpp/overview/ - topicHref: /cpp/overview/visual-cpp-in-visual-studio - - name: Parallel programming - tocHref: /cpp/parallel/ - topicHref: /cpp/parallel/parallel-programming-in-visual-cpp - - name: Porting and upgrading - tocHref: /cpp/porting/ - topicHref: /cpp/porting/visual-cpp-porting-and-upgrading-guide - - name: C/C++ preprocessor - tocHref: /cpp/preprocessor/ - topicHref: /cpp/preprocessor/c-cpp-preprocessor-reference - - name: Security - tocHref: /cpp/security/ - topicHref: /cpp/security/security-best-practices-for-cpp - - name: C++ standard library - tocHref: /cpp/standard-library/ - topicHref: /cpp/standard-library/cpp-standard-library-reference - - name: Text and strings - tocHref: /cpp/text/ - topicHref: /cpp/text/text-and-strings-in-visual-cpp - - name: Windows - tocHref: /cpp/windows/ - topicHref: /cpp/windows/overview-of-windows-programming-in-cpp +- name: C++, C, and Assembler + tocHref: /cpp/ + topicHref: /cpp/index diff --git a/docs/assembler/arm/arm-assembler-command-line-reference.md b/docs/assembler/arm/arm-assembler-command-line-reference.md index 1d38d10575..6c79ceaf15 100644 --- a/docs/assembler/arm/arm-assembler-command-line-reference.md +++ b/docs/assembler/arm/arm-assembler-command-line-reference.md @@ -1,78 +1,119 @@ --- title: "ARM Assembler command-line reference" description: "Reference guide to the Microsoft ARM assembler command-line options." -ms.date: "02/09/2020" -ms.assetid: f7b89478-1ab5-4995-8cde-a805f0462c45 +ms.date: 05/09/2022 --- # ARM Assembler command-line reference -This article provides command-line information about the Microsoft ARM assembler, **armasm**. **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The linker can link COFF code objects produced by both the ARM assembler and the C compiler. It can link either together with object libraries created by the librarian. +The Microsoft ARM assemblers, **armasm** and **armasm64**, support several command-line options. By default, **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The **armasm64** assembler creates COFF object code for ARM64 and ARM64EC targets. The linker can link COFF code objects produced by both the ARM assembler and the C/C++ compiler. It can link either together with object libraries created by the librarian. ## Syntax > **`armasm`** [*options*] *source_file* *object_file*\ -> **`armasm`** [*options*] **`-o`** *object_file* *source_file* +> **`armasm`** [*options*] *source_file* + +> **`armasm64`** [*options*] *source_file* *object_file*\ +> **`armasm64`** [*options*] *source_file* ### Parameters *options*\ A combination of zero or more of the following options: +- **`-16`**\ + Available only in **armasm**. Assemble source as 16-bit Thumb instructions. This option is the default. + +- **`-32`**\ + Available only in **armasm**. Assemble source as 32-bit ARM instructions. + +- **`-coff_thumb2_only`**\ + Available only in **armasm**. Allow only Thumb-2 code. + +- **`-errorReport:`** *option*\ + This option is deprecated. In Windows Vista and later, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. + - **`-errors`** *filename*\ - Redirect error and warning messages to *filename*. + **`-e`** *filename*\ + Redirect error and warning messages to *filename*. By default, these messages are sent to `stdout`. -- **`-i`** *dir*[**`;`**dir]\ - Add the specified directories to the include search path. +- **`-funcOverride:`** *function_name*\ + Available only in **armasm64**. Emit function overriding support for *function_name*. -- **`-predefine`** *directive*\ - Specify a SETA, SETL, or SETS directive to predefine a symbol.\ - Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ - For more information, see the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). +- **`-g`**\ + Generate debugging information. -- **`-nowarn`**\ - Disable all warning messages. +- **`-gh:SHA1`**\ + Use the SHA-1 cryptographic hash algorithm to generate a checksum of each source file in debug info. Overrides **`-gh:SHA256`**. -- **`-ignore`** *warning*\ - Disable the specified warning. For possible values, see the section about warnings. +- **`-gh:SHA256`**\ + Use the SHA-256 cryptographic hash algorithm to generate a checksum of each source file in debug info. This option is on by default in Visual Studio 2022 version 17.0 and later. + +- **`-guard:ehcont`**[**`-`**]\ + Generate a sorted list of the relative virtual addresses (RVA) of all the valid exception handling continuation targets for a binary. It's used at runtime for `NtContinue` and `SetThreadContext` instruction pointer validation. By default, **`-guard:ehcont`** is off and must be explicitly enabled. To explicitly disable this option, use **`-guard:ehcont-`**. This option is available in Visual Studio 2019 version 16.7 and later. The feature is supported for 64-bit processes on a 64-bit OS. - **`-help`**\ - Print the command-line help message. + **`-h`**\ + Print the command-line help message. + +- **`-i`** *dir*[**`;`** *dir*]\ + Add one or more specified directories to the include search path. Separate directories by using a semi-colon (`;`). + +- **`-ignore`** *warning_number*\ + Disable the specified warning number. For possible values, see [ARM Assembler diagnostic messages](arm-assembler-diagnostic-messages.md). + +- **`-list`** *list_file*\ + Create a detailed listing of the generated assembly language to *list_file*. The *list_file* parameter is optional. If it's omitted, the assembler appends *`.lst`* to the base name of *source_file* to create the listing file. - **`-machine`** *machine*\ - Specify the machine type to set in the PE header. Possible values for *machine* are:\ - **ARM**—Sets the machine type to IMAGE_FILE_MACHINE_ARMNT. This option is the default.\ - **THUMB**—Sets the machine type to IMAGE_FILE_MACHINE_THUMB. + Specify the machine type to set in the PE header. In **armasm**, possible values for *machine* are: + - **ARM**—Sets the machine type to `IMAGE_FILE_MACHINE_ARMNT`. This option is the default. + - **THUMB**—Sets the machine type to `IMAGE_FILE_MACHINE_THUMB`. -- **`-oldit`**\ - Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. + In **armasm64**, possible values are: + - **ARM64**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64`. This option is the default. + - **ARM64EC**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64EC`. -- **`-via`** *filename*\ - Read additional command-line arguments from *filename*. +- **`-noesc`**\ + **`-noe`**\ + Ignore C-style escaped special characters, such as `\n` or `\t`. -- **`-16`**\ - Assemble source as 16-bit Thumb instructions. This option is the default. +- **`-nologo`**\ + Suppress the copyright banner. -- **`-32`**\ - Assemble source as 32-bit ARM instructions. +- **`-nowarn`**\ + **`-now`**\ + Disable all warning messages. -- **`-g`**\ - Generate debugging information. +- **`-o`** *object_file*\ + Specify the name of the object (output) file. The **`-o`** option is optional; you can instead specify an object file name as the last element of the command line. -- **`-errorReport:`** *option*\ - This option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. +- **`-oldit`**\ + Available only in **armasm**. Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. + +- **`-predefine`** *directive*\ + **`-pd`** *directive*\ + Specify a SETA, SETL, or SETS directive to predefine a symbol.\ + Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ + For more information, see the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). + +- **`-sourcelink:`** *sourcelink_filename*\ + *sourcelink_filename* specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-json-schema). Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). + +- **`-via`** *filename*\ + Read extra command-line arguments from *filename*. *source_file*\ The name of the source file. *object_file*\ -The name of the object (output) file. +The last element of the command line can specify the name of the object (output) file. If it's omitted, and no **`-o`** option is specified, the assembler appends *`.obj`* to the base name of *source_file* to create the object file. ## Remarks The following example demonstrates how to use armasm in a typical scenario. First, use armasm to build an assembly language source (.asm) file to an object (.obj) file. Then, use the CL command-line C compiler to compile a source (.c) file, and also specify the linker option to link the ARM object file. ```cmd -armasm myasmcode.asm -o myasmcode.obj +armasm -o myasmcode.obj myasmcode.asm cl myccode.c /link myasmcode.obj ``` diff --git a/docs/assembler/arm/arm-assembler-diagnostic-messages.md b/docs/assembler/arm/arm-assembler-diagnostic-messages.md index 1215580189..ebe3253ac4 100644 --- a/docs/assembler/arm/arm-assembler-diagnostic-messages.md +++ b/docs/assembler/arm/arm-assembler-diagnostic-messages.md @@ -1,24 +1,24 @@ --- description: "Learn more about: ARM Assembler diagnostic messages" title: "ARM Assembler diagnostic messages" -ms.date: "08/30/2018" +ms.date: 05/09/2022 f1_keywords: ["A2193", "A2196", "A2202", "A2513", "A2557", "A4228", "A4508", "A4509"] helpviewer_keywords: ["A2193", "A2196", "A2202", "A2513", "A2557", "A4228", "A4508", "A4509"] ms.assetid: 52b38267-6023-4bdc-a0ef-863362f48eec --- # ARM Assembler diagnostic messages -The Microsoft ARM assembler (*armasm*) emits diagnostic warnings and errors when it encounters them. This article describes the most commonly-encountered messages. +The Microsoft ARM assemblers, **armasm** and **armasm64**, emit diagnostic warnings and errors when they encounter them. This article describes the most commonly encountered messages. ## Syntax -> filename**(**line-number**) :** \[**error**|**warning**] **A**number**:** *message* +> *filename* **(** *line-number* **) :** \[**error**|**warning**] **A** *number* **:** *message* ## Diagnostic messages - Errors > A2193: this instruction generates unpredictable behavior -The ARM architecture cannot guarantee what happens when this instruction is executed. For details about the well-defined forms of this instruction, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). +The ARM architecture can't guarantee what happens when this instruction is executed. For details about the well-defined forms of this instruction, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). ```asm ADD r0, r8, pc ; A2193: this instruction generates unpredictable behavior @@ -26,22 +26,22 @@ The ARM architecture cannot guarantee what happens when this instruction is exec > A2196: instruction cannot be encoded in 16 bits -The specified instruction cannot be encoded as a 16-bit Thumb instruction. Specify a 32-bit instruction, or rearrange code to bring the target label into the range of a 16-bit instruction. +The specified instruction can't be encoded as a 16-bit Thumb instruction. Specify a 32-bit instruction, or rearrange code to bring the target label into the range of a 16-bit instruction. The assembler may attempt to encode a branch in 16 bits and fail with this error, even though a 32-bit branch is encodable. You can solve this problem by using the `.W` specifier to explicitly mark the branch as 32-bit. ```asm - ADD.N r0, r1, r2 ; A2196: instruction cannot be encoded in 16 bits + ADD.N r0, r1, r2 ; A2196: instruction can't be encoded in 16 bits B.W label ; OK - B.N label ; A2196: instruction cannot be encoded in 16 bits + B.N label ; A2196: instruction can't be encoded in 16 bits SPACE 10000 label ``` > A2202: Pre-UAL instruction syntax not allowed in THUMB region -Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax is no longer accepted +Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax is no longer accepted ```asm ADDEQS r0, r1 ; A2202: Pre-UAL instruction syntax not allowed in THUMB region @@ -50,7 +50,7 @@ Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax > A2513: Rotation must be even -In ARM mode, there is an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that is obtained by rotating the value `` right by ``. When you use this syntax, you must make the value of `` even. +In ARM mode, there's an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that's obtained by rotating the value `` right by ``. When you use this syntax, you must make the value of `` even. ```asm MOV r0, #4, #2 ; OK @@ -59,7 +59,7 @@ In ARM mode, there is an alternate syntax for specifying constants. Instead of > A2557: Incorrect number of bytes to write back -On the NEON structure load and store instructions (`VLDn`, `VSTn`), there is an alternate syntax for specifying writeback to the base register. Instead of putting an exclamation point (!) after the address, you can specify an immediate value that indicates the offset to be added to the base register. If you use this syntax, you must specify the exact number of bytes that were loaded or stored by the instruction. +On the NEON structure load and store instructions (`VLDn`, `VSTn`), there's an alternate syntax for specifying writeback to the base register. Instead of putting an exclamation point (!) after the address, you can specify an immediate value that indicates the offset to be added to the base register. If you use this syntax, you must specify the exact number of bytes that were loaded or stored by the instruction. ```asm VLD1.8 {d0-d3}, [r0]! ; OK @@ -71,9 +71,9 @@ On the NEON structure load and store instructions (`VLDn`, `VSTn`), there is an > A4228: Alignment value exceeds AREA alignment; alignment not guaranteed -The alignment that is specified in an `ALIGN` directive is greater than the alignment of the enclosing `AREA`. As a result, the assembler cannot guarantee that the `ALIGN` directive will be honored. +The alignment that's specified in an `ALIGN` directive is greater than the alignment of the enclosing `AREA`. As a result, the assembler can't guarantee that the `ALIGN` directive will be honored. -To fix this, you can specify on the `AREA` directive an `ALIGN` attribute that is equal to or greater than the desired alignment. +To fix this warning, you can specify on the `AREA` directive an `ALIGN` attribute that's equal to or greater than the desired alignment. ```asm AREA |.myarea1| @@ -85,7 +85,7 @@ ALIGN 8 ; OK > A4508: Use of this rotated constant is deprecated -In ARM mode, there is an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that is obtained by rotating the value `` right by ``. In some contexts, ARM has deprecated the use of these rotated constants. In these cases, use the basic `#` syntax instead. +In ARM mode, there's an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that's obtained by rotating the value `` right by ``. In some contexts, ARM has deprecated the use of these rotated constants. In these cases, use the basic `#` syntax instead. ```asm ANDS r0, r0, #1 ; OK @@ -96,7 +96,7 @@ In ARM mode, there is an alternate syntax for specifying constants. Instead of This form of conditional instruction has been deprecated by ARM in the ARMv8 architecture. We recommend that you change the code to use conditional branches. To see which conditional instructions are still supported, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). -This warning is not emitted when the **-oldit** command-line switch is used. +This warning isn't emitted when the **`-oldit`** command-line switch is used. ```asm ADDEQ r0, r1, r8 ; A4509: This form of conditional instruction is deprecated diff --git a/docs/assembler/arm/arm-assembler-reference.md b/docs/assembler/arm/arm-assembler-reference.md index 2503bb20ca..905ab3a72a 100644 --- a/docs/assembler/arm/arm-assembler-reference.md +++ b/docs/assembler/arm/arm-assembler-reference.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: ARM Assembler Reference" -title: "ARM Assembler Reference" -ms.date: "08/28/2017" +description: "Learn more about: ARM Assembler reference" +title: "ARM Assembler reference" +ms.date: 05/09/2022 ms.assetid: f8a076cc-9627-4328-a34a-9c44f7a3aab1 --- -# ARM Assembler Reference +# ARM Assembler reference -The articles in this section of the documentation provide reference material for the Microsoft ARM assembler (armasm) and related tools. +The articles in this section of the documentation provide reference material for the Microsoft ARM assembler (**armasm** or **armasm64**) and related tools. -## Related Articles +## Related articles |Title|Description| |-----------|-----------------| -|[ARM Assembler Command-Line Reference](../../assembler/arm/arm-assembler-command-line-reference.md)|Describes the armasm command-line options.| -|[ARM Assembler Diagnostic Messages](../../assembler/arm/arm-assembler-diagnostic-messages.md)|Describes commonly seen armasm warning and error messages.| -|[ARM Assembler Directives](../../assembler/arm/arm-assembler-directives.md)|Describes the ARM directives that are different in armasm.| +|[ARM Assembler command-line reference](../../assembler/arm/arm-assembler-command-line-reference.md)|Describes the Microsoft armasm and armasm64 command-line options.| +|[ARM Assembler diagnostic messages](../../assembler/arm/arm-assembler-diagnostic-messages.md)|Describes commonly seen armasm and armasm64 warning and error messages.| +|[ARM Assembler directives](../../assembler/arm/arm-assembler-directives.md)|Describes the ARM directives that are different in Microsoft armasm and armasm64.| |[ARM Architecture Reference Manual](https://developer.arm.com/search#q=ARM%20Architecture%20Reference%20Manual) on the ARM Developer website.|Choose the relevant manual for your ARM architecture. Each contains reference sections about ARM, Thumb, NEON, and VFP, and additional information about the ARM assembly language.| |[ARM Compiler armasm User Guide](https://developer.arm.com/search#q=ARM%20Compiler%20armasm%20User%20Guide) on the ARM Developer website.|Choose a recent version to find up-to-date information about the ARM assembly language.| diff --git a/docs/assembler/inline/asm.md b/docs/assembler/inline/asm.md index edc958759c..0aa4253ef7 100644 --- a/docs/assembler/inline/asm.md +++ b/docs/assembler/inline/asm.md @@ -10,20 +10,20 @@ ms.assetid: 77ff3bc9-a492-4b5e-85e1-fa4e414e79cd **Microsoft Specific** -The **`__asm`** keyword invokes the inline assembler and can appear wherever a C or C++ statement is legal. It cannot appear by itself. It must be followed by an assembly instruction, a group of instructions enclosed in braces, or, at the very least, an empty pair of braces. The term "**`__asm`** block" here refers to any instruction or group of instructions, whether or not in braces. +The **`__asm`** keyword invokes the inline assembler and can appear wherever a C or C++ statement is legal. It can't appear by itself. It must be followed by an assembly instruction, a group of instructions enclosed in braces, or, at minimum, an empty pair of braces. The term "**`__asm`** block" here refers to any instruction or group of instructions, whether or not in braces. > [!NOTE] > Visual C++ support for the Standard C++ **`asm`** keyword is limited to the fact that the compiler will not generate an error on the keyword. However, an **`asm`** block will not generate any meaningful code. Use **`__asm`** instead of **`asm`**. ## Grammar -*asm-block*:
-    **`__asm`** *assembly-instruction* **`;`**opt
-    **`__asm {`** *assembly-instruction-list* **`}`** **`;`**opt +*asm-block*:\ + **`__asm`** *assembly-instruction* **`;`**opt\ + **`__asm {`** *assembly-instruction-list* **`}`** **`;`**opt -*assembly-instruction-list*:
-    *assembly-instruction* **`;`**opt
-    *assembly-instruction* **`;`** *assembly-instruction-list* **`;`**opt +*assembly-instruction-list*:\ + *assembly-instruction* **`;`**opt\ + *assembly-instruction* **`;`** *assembly-instruction-list* **`;`**opt ## Remarks @@ -37,7 +37,7 @@ Before Visual Studio 2005, the instruction __asm int 3 ``` -did not cause native code to be generated when compiled with **/clr**; the compiler translated the instruction to a CLR break instruction. +didn't cause native code to be generated when compiled with **/clr**; the compiler translated the instruction to a CLR break instruction. `__asm int 3` now results in native code generation for the function. If you want a function to cause a break point in your code and if you want that function compiled to MSIL, use [__debugbreak](../../intrinsics/debugbreak.md). @@ -69,9 +69,9 @@ Because the **`__asm`** keyword is a statement separator, you can also put assem __asm mov al, 2 __asm mov dx, 0xD007 __asm out dx, al ``` -All three examples generate the same code, but the first style (enclosing the **`__asm`** block in braces) has some advantages. The braces clearly separate assembly code from C or C++ code and avoid needless repetition of the **`__asm`** keyword. Braces can also prevent ambiguities. If you want to put a C or C++ statement on the same line as an **`__asm`** block, you must enclose the block in braces. Without the braces, the compiler cannot tell where assembly code stops and C or C++ statements begin. Finally, because the text in braces has the same format as ordinary MASM text, you can easily cut and paste text from existing MASM source files. +All three examples generate the same code, but the first style (enclosing the **`__asm`** block in braces) has some advantages. The braces clearly separate assembly code from C or C++ code and avoid needless repetition of the **`__asm`** keyword. Braces can also prevent ambiguities. If you want to put a C or C++ statement on the same line as an **`__asm`** block, you must enclose the block in braces. Without the braces, the compiler can't tell where assembly code stops and C or C++ statements begin. Finally, because the text in braces has the same format as ordinary MASM text, you can easily cut and paste text from existing MASM source files. -Unlike braces in C and C++, the braces enclosing an **`__asm`** block don't affect variable scope. You can also nest **`__asm`** blocks; nesting does not affect variable scope. +Unlike braces in C and C++, the braces enclosing an **`__asm`** block don't affect variable scope. You can also nest **`__asm`** blocks; nesting doesn't affect variable scope. **END Microsoft Specific** diff --git a/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md b/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md index 94f04a2e7e..364313604c 100644 --- a/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md +++ b/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md @@ -1,18 +1,22 @@ --- description: "Learn more about: Data Directives and Operators in Inline Assembly" title: "Data Directives and Operators in Inline Assembly" -ms.date: "08/30/2018" +ms.date: 06/03/2022 helpviewer_keywords: ["data directives [C++]", "__asm keyword [C++], referencing limitations", "MASM (Microsoft Macro Assembler), directives", "directives [C++], MASM", "MASM (Microsoft Macro Assembler), structures", "operators [MASM]", "inline assembly, operators", "inline assembly, data directives", "MASM (Microsoft Macro Assembler), operators", "structures [C++], MASM"] ms.assetid: fb7410c7-156a-4131-bcfc-211aa70533e3 --- -# Data Directives and Operators in Inline Assembly +# Data directives and operators in inline assembly **Microsoft Specific** -Although an **`__asm`** block can reference C or C++ data types and objects, it cannot define data objects with MASM directives or operators. Specifically, you cannot use the definition directives **DB**, `DW`, **DD**, `DQ`, `DT`, and `DF`, or the operators `DUP` or **THIS**. MASM structures and records are also unavailable. The inline assembler doesn't accept the directives `STRUC`, `RECORD`, **WIDTH**, or **MASK**. +The inline assembler doesn't support all the data directives and operators available in MASM. + +## Remarks + +Although an **`__asm`** block can reference C or C++ data types and objects, it can't define data objects with MASM directives or operators. Specifically, you can't use the definition directives **`DB`**, **`DW`**, **`DD`**, **`DQ`**, **`DT`**, and **`DF`**, or the operators **`DUP`** or **`THIS`**. MASM structures and records are also unavailable. The inline assembler doesn't accept the directives **`STRUC`**, **`RECORD`**, **`WIDTH`**, or **`MASK`**. **END Microsoft Specific** ## See also -[Using Assembly Language in __asm Blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md)
+[Using Assembly Language in `__asm` blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/defining-asm-blocks-as-c-macros.md b/docs/assembler/inline/defining-asm-blocks-as-c-macros.md index 0a5d4df127..2e5305a93c 100644 --- a/docs/assembler/inline/defining-asm-blocks-as-c-macros.md +++ b/docs/assembler/inline/defining-asm-blocks-as-c-macros.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Defining __asm Blocks as C Macros" title: "Defining __asm Blocks as C Macros" -ms.date: "08/30/2018" +description: "Learn more about: Defining __asm Blocks as C Macros" +ms.date: 08/30/2018 helpviewer_keywords: ["macros, __asm blocks", "Visual C, macros", "__asm keyword [C++], as C macros"] -ms.assetid: 677ba11c-21c8-4609-bba7-cd47312243b0 --- # Defining __asm Blocks as C Macros @@ -15,7 +14,7 @@ C macros offer a convenient way to insert assembly code into your source code, b - Put the **`__asm`** keyword in front of each assembly instruction. -- Use old-style C comments ( `/* comment */`) instead of assembly-style comments ( `; comment`) or single-line C comments ( `// comment`). +- Use old-style C comments (`/* comment */`) instead of assembly-style comments (`; comment`) or single-line C comments (`// comment`). To illustrate, the following example defines a simple macro: @@ -39,7 +38,7 @@ The third and fourth **`__asm`** keywords are needed as statement separators. Th The braces are essential as well. If you omit them, the compiler can be confused by C or C++ statements on the same line to the right of the macro invocation. Without the closing brace, the compiler cannot tell where assembly code stops, and it sees C or C++ statements after the **`__asm`** block as assembly instructions. -Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments ( `// comment`). To prevent errors, use old-style C comments ( `/* comment */`) in **`__asm`** blocks defined as macros. +Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments (`// comment`). To prevent errors, use old-style C comments (`/* comment */`) in **`__asm`** blocks defined as macros. An **`__asm`** block written as a C macro can take arguments. Unlike an ordinary C macro, however, an **`__asm`** macro cannot return a value. So you cannot use such macros in C or C++ expressions. diff --git a/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md b/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md index b2d74c12ef..323a67036e 100644 --- a/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md +++ b/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md @@ -9,10 +9,10 @@ ms.assetid: 83643a09-1699-40a8-8ef2-13502bc4ac2c **Microsoft Specific** -The inline assembler is not a macro assembler. You cannot use MASM macro directives (**MACRO**, `REPT`, **IRC**, `IRP`, and `ENDM`) or macro operators (**<>**, **!**, **&**, `%`, and `.TYPE`). An **`__asm`** block can use C preprocessor directives, however. See [Using C or C++ in __asm Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md) for more information. +The inline assembler isn't a macro assembler. You can't use MASM macro directives (`MACRO`, `REPT`, `IRC`, `IRP`, and `ENDM`) or macro operators (**`<>`**, **`!`**, **`&`**, **`%`**, and `.TYPE`). An **`__asm`** block can use C preprocessor directives, however. For more information, see [Using C or C++ in `__asm` blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md). **END Microsoft Specific** ## See also -[Using Assembly Language in __asm Blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md)
+[Using assembly language in `__asm` blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/writing-functions-with-inline-assembly.md b/docs/assembler/inline/writing-functions-with-inline-assembly.md index adef94e4ad..65e852819f 100644 --- a/docs/assembler/inline/writing-functions-with-inline-assembly.md +++ b/docs/assembler/inline/writing-functions-with-inline-assembly.md @@ -1,39 +1,46 @@ --- -description: "Learn more about: Writing Functions with Inline Assembly" -title: "Writing Functions with Inline Assembly" -ms.date: "08/30/2018" +description: "Learn more about: Writing functions with inline assembly" +title: "Writing functions with inline assembly" +ms.date: 02/11/2022 helpviewer_keywords: ["functions [C++], inline assembly", "inline assembly [C++], writing functions", "assembler [C++], writing functions", "__asm keyword [C++], in functions"] ms.assetid: b5df8a04-fdc7-4622-8c9e-e4b618927497 --- -# Writing Functions with Inline Assembly +# Writing functions with inline assembly **Microsoft Specific** -If you write a function with inline assembly code, it's easy to pass arguments to the function and return a value from it. The following examples compare a function first written for a separate assembler and then rewritten for the inline assembler. The function, called `power2`, receives two parameters, multiplying the first parameter by 2 to the power of the second parameter. Written for a separate assembler, the function might look like this: +> [!NOTE] +> Inline assembly is only available for x86 targets. For similar functionality in x64 or ARM64 code, use [compiler intrinsics](../../intrinsics/compiler-intrinsics.md). + +If you write a function with inline assembly code, it's easy to pass arguments to the function and return a value from it. The following examples compare a function first written for a separate assembler and then rewritten for the inline assembler. The function, called `power2`, receives two parameters, multiplying the first parameter by 2 to the power of the second parameter. As a separate assembler file, the function might look like this: ```asm -; POWER.ASM -; Compute the power of an integer -; - PUBLIC _power2 -_TEXT SEGMENT WORD PUBLIC 'CODE' +; power2.asm +; x86 code for C interop +; Command line: ml /c /Cx /W3 /WX power2.asm + .686P + .XMM + .MODEL flat + +PUBLIC _power2 +; int power2(int num, int power); +; computes num x 2^power +_TEXT SEGMENT _power2 PROC - - push ebp ; Save EBP - mov ebp, esp ; Move ESP into EBP so we can refer - ; to arguments on the stack - mov eax, [ebp+4] ; Get first argument - mov ecx, [ebp+6] ; Get second argument - shl eax, cl ; EAX = EAX * ( 2 ^ CL ) - pop ebp ; Restore EBP - ret ; Return with sum in EAX - + push ebp ; save EBP + mov ebp, esp ; Move ESP into EBP so we can refer + ; to arguments on the stack + mov eax, [ebp+8] ; load first argument + mov ecx, [ebp+12] ; load second argument + shl eax, cl ; compute result in EAX + pop ebp ; restore EBP + ret _power2 ENDP _TEXT ENDS - END +END ``` -Since it's written for a separate assembler, the function requires a separate source file and assembly and link steps. C and C++ function arguments are usually passed on the stack, so this version of the `power2` function accesses its arguments by their positions on the stack. (Note that the **MODEL** directive, available in MASM and some other assemblers, also allows you to access stack arguments and local stack variables by name.) +Since it's written as a separate assembler file, the function requires separate assembly and link steps. C and C++ function arguments are usually passed on the stack, so this version of the `power2` function accesses its arguments by their positions on the stack. (The **`MODEL`** directive, available in MASM and some other assemblers, also allows you to access stack arguments and local stack variables by name.) ## Example @@ -67,10 +74,10 @@ int power2( int num, int power ) The inline version of the `power2` function refers to its arguments by name and appears in the same source file as the rest of the program. This version also requires fewer assembly instructions. -Because the inline version of `power2` doesn't execute a C **`return`** statement, it causes a harmless warning if you compile at warning level 2 or higher. The function does return a value, but the compiler cannot tell that in the absence of a **`return`** statement. You can use [#pragma warning](../../preprocessor/warning.md) to disable the generation of this warning. +Because the inline version of `power2` doesn't execute a C **`return`** statement, it causes a harmless warning if you compile at warning level 2 or higher. The function does return a value, but the compiler can't tell it does in the absence of a **`return`** statement. You can use [`#pragma warning`](../../preprocessor/warning.md) to disable the generation of this warning. **END Microsoft Specific** ## See also -[Using C or C++ in __asm Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md)
+[Using C or C++ in `__asm` Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md) diff --git a/docs/assembler/masm/dot-code.md b/docs/assembler/masm/dot-code.md index c8167f89f3..9bf447e91b 100644 --- a/docs/assembler/masm/dot-code.md +++ b/docs/assembler/masm/dot-code.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: .CODE" title: ".CODE" +description: "Learn more about: .CODE" ms.date: "12/17/2019" f1_keywords: [".CODE"] helpviewer_keywords: [".CODE directive"] -ms.assetid: 2b8c882c-c0d2-4fa3-8335-e6b12717a4f4 --- # .CODE -(32-bit MASM only.) When used with [.MODEL](dot-model.md), indicates the start of a code segment. +Indicates the start of a code segment. + +When using 32-bit MASM, this should be used along with [.MODEL](dot-model.md). ## Syntax > **.CODE** ⟦*name*⟧\ > ⟦ *segmentItem* ⟧...\ -> ⟦ *codesegmentnameId* **ENDS**;;⟧\ +> ⟦ *codesegmentnameId* **ENDS**;;⟧ ### Parameters diff --git a/docs/assembler/masm/dot-data.md b/docs/assembler/masm/dot-data.md index cf080270da..c36eb3fee1 100644 --- a/docs/assembler/masm/dot-data.md +++ b/docs/assembler/masm/dot-data.md @@ -8,7 +8,9 @@ ms.assetid: 32797935-9c79-46e0-bf6f-07d0c2bf1dc1 --- # .DATA - (32-bit MASM only.) When used with [.MODEL](dot-model.md), starts a near data segment for initialized data (segment name _DATA). +Indicates the start of a data segment. + +When using 32-bit MASM, this starts a near data segment for initialized data (segment name _DATA) and should be used along with [.MODEL](dot-model.md). ## Syntax diff --git a/docs/assembler/masm/dot-nolistif.md b/docs/assembler/masm/dot-nolistif.md index bb4996f2ad..37703a53fb 100644 --- a/docs/assembler/masm/dot-nolistif.md +++ b/docs/assembler/masm/dot-nolistif.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: .NOLISTIF" title: ".NOLISTIF" +description: "Learn more about: .NOLISTIF" ms.date: "12/16/2019" f1_keywords: [".NOLISTIF"] helpviewer_keywords: [".NOLISTIF directive"] -ms.assetid: 9243af7a-7221-4531-bbc3-281b6b292bfd --- # .NOLISTIF @@ -20,5 +19,5 @@ This is the default. Same as [.SFCOND](dot-sfcond.md). ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-xmm.md b/docs/assembler/masm/dot-xmm.md index 72b1af9e0a..9c0eae78b0 100644 --- a/docs/assembler/masm/dot-xmm.md +++ b/docs/assembler/masm/dot-xmm.md @@ -8,7 +8,7 @@ ms.assetid: db3062b6-8b2f-469b-aa02-df6571eab3ba --- # .XMM (32-bit MASM) -Enables assembly of Internet Streaming SIMD Extension instructions. (32-bit MASM only.) +Enables assembly of Streaming SIMD Extension instructions. (32-bit MASM only.) ## Syntax diff --git a/docs/assembler/masm/extern-masm.md b/docs/assembler/masm/extern-masm.md index dc0325534e..d261390d68 100644 --- a/docs/assembler/masm/extern-masm.md +++ b/docs/assembler/masm/extern-masm.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: EXTERN" +description: "Learn more about the MASM directive: EXTERN" title: "EXTERN (MASM)" -ms.date: "12/06/2019" +ms.date: 1/10/2025 helpviewer_keywords: ["EXTERN directive"] -ms.assetid: 667d703d-3aaf-4139-a586-29bc5dab1aff --- # EXTERN @@ -17,7 +16,9 @@ Defines one or more external variables, labels, or symbols called *name* whose t The *language-type* argument is valid in 32-bit MASM only. -The *type* can be [ABS](operator-abs.md), which imports *name* as a constant. Same as [EXTRN](extrn.md). +The *type* can be [`ABS`](operator-abs.md), which imports *name* as a constant. Same as [`EXTRN`](extrn.md). + +The *type* can also be [`PROC`](proc.md), in which case *name* is treated as an external procedure. ## See also diff --git a/docs/assembler/masm/masm-bnf-grammar.md b/docs/assembler/masm/masm-bnf-grammar.md index d725146caf..65eea98ce0 100644 --- a/docs/assembler/masm/masm-bnf-grammar.md +++ b/docs/assembler/masm/masm-bnf-grammar.md @@ -22,7 +22,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   *`endOfLine`* | *`comment`* *`=Dir`*\ -  *`id`* = *`immExpr`* *`;;`* +  *`id`* **`=`** *`immExpr`* *`;;`* *`addOp`*\   **`+`** | **`-`** @@ -492,7 +492,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   *`immExpr`*\   | *`string`*\   | **`?`**\ -  | *`constExpr`* **`DUP`** ( *`scalarInstList`* )\ +  | *`constExpr`* **`DUP`** **`(`** *`scalarInstList`* **`)`**\   | *`floatNumber`*\   | *`bcdConst`* @@ -591,7 +591,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu *`macroCall`*\   *`id`* *`macroArgList`* *`;;`*\ -  | *`id`* ( *`macroArgList`* ) +  | *`id`* **`(`** *`macroArgList`* **`)`** *`macroDir`*\   *`id`* **`MACRO`** ⟦ *`macroParmList`* ⟧ *`;;`*\ @@ -716,7 +716,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   | **`OLDMACROS`** | **`NOOLDMACROS`**\   | **`OLDSTRUCTS`** | **`NOOLDSTRUCTS`**\   | **`PROC`** **`:`** *`oVisibility`*\ -  | **`PROLOGUE`** : *`macroId`*\ +  | **`PROLOGUE`** **`:`** *`macroId`*\   | **`READONLY`** | **`NOREADONLY`**\   | **`SCOPED`** | **`NOSCOPED`**\   | **`SEGMENT`** **`:`** *`segSize`*\ diff --git a/docs/assembler/masm/masm-for-x64-ml64-exe.md b/docs/assembler/masm/masm-for-x64-ml64-exe.md index 95c7e53149..840b002083 100644 --- a/docs/assembler/masm/masm-for-x64-ml64-exe.md +++ b/docs/assembler/masm/masm-for-x64-ml64-exe.md @@ -3,11 +3,10 @@ description: "Learn more about: Microsoft Macro Assembler (MASM) for x64 (ml64.e title: "MASM for x64 (ml64.exe)" ms.date: 09/21/2021 helpviewer_keywords: ["ml64", "ml64.exe", "masm for x64"] -ms.assetid: 89059103-f372-4968-80ea-0c7f90bb9c91 --- # MASM for x64 (ml64.exe) -Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). +Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembly language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). To use ml64.exe on the command line, start a developer command prompt for x64 targets. A developer command prompt sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md). diff --git a/docs/assembler/masm/microsoft-macro-assembler-reference.md b/docs/assembler/masm/microsoft-macro-assembler-reference.md index 5765386231..1cf7f09461 100644 --- a/docs/assembler/masm/microsoft-macro-assembler-reference.md +++ b/docs/assembler/masm/microsoft-macro-assembler-reference.md @@ -6,11 +6,11 @@ helpviewer_keywords: ["MASM (Microsoft Macro Assembler), reference", "MASM (Micr --- # Microsoft Macro Assembler reference -The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and text string processing. MASM gives you greater control over the hardware. By using MASM, you also can reduce time and memory overhead in your code. +The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and string processing. MASM gives you greater control over the hardware. By using MASM, you also can reduce time and memory overhead in your code. ## In This Section -[ML and ML64 command-line option](ml-and-ml64-command-line-reference.md)\ +[ML and ML64 command-line options](ml-and-ml64-command-line-reference.md)\ Describes the ML and ML64 command-line options. [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\ @@ -34,8 +34,7 @@ Describes fatal and nonfatal error messages and warnings. [Processor Manufacturer Programming Manuals](processor-manufacturer-programming-manuals.md)\ Provides links to programming information about processors not manufactured, sold, or supported by Microsoft. -[MASM BNF Grammar](masm-bnf-grammar.md) - +[MASM BNF Grammar](masm-bnf-grammar.md)\ Formal BNF description of MASM for x64. ## Related Sections diff --git a/docs/assembler/masm/ml-and-ml64-command-line-reference.md b/docs/assembler/masm/ml-and-ml64-command-line-reference.md index a14b954932..e4ea469e36 100644 --- a/docs/assembler/masm/ml-and-ml64-command-line-reference.md +++ b/docs/assembler/masm/ml-and-ml64-command-line-reference.md @@ -1,10 +1,9 @@ --- title: "ML and ML64 command-line reference" description: "Reference guide to the Microsoft MASM ML and ML64 assembler command-line options." -ms.date: "02/09/2020" +ms.date: 7/3/2023 f1_keywords: ["ML"] -helpviewer_keywords: ["/W* MASM compiler option", "/c MASM compiler option", "/EP MASM compiler option", "/Fe MASM compiler option", "/Zp MASM compiler option", "/AT MASM compiler option", "/Zm MASM compiler option", "/Sf MASM compiler option", "/Sp MASM compiler option", "/w MASM compiler option", "/Fl MASM compiler option", "/coff MASM compiler option", "/St MASM compiler option", "/Cx MASM compiler option", "/Sl MASM compiler option", "/Cu MASM compiler option", "MASM (Microsoft Macro Assembler), ML command-line reference", "/FPi MASM compiler option", "/Zf MASM compiler option", "ML environment variable", "/Fr MASM compiler option", "/help MASM compiler option", "/Sa MASM compiler option", "/Zd MASM compiler option", "/I MASM compiler option", "/? MASM compiler option", "/Bl MASM compiler option", "/Fm MASM compiler option", "/Fo MASM compiler option", "command-line reference [ML]", "/Sn MASM compiler option", "/Gd MASM compiler option", "/D* MASM compiler option", "environment variables, ML", "/Gc MASM compiler option", "/F* MASM compiler option", "/Sc MASM compiler option", "/H MASM compiler option", "/Zs MASM compiler option", "/omf MASM compiler option", "/Sg MASM compiler option", "/Cp MASM compiler option", "/Zi MASM compiler option", "/nologo MASM compiler option", "/Sx MASM compiler option", "/WX MASM compiler option", "/Ss MASM compiler option", "command line, reference [ML]", "/Ta MASM compiler option"] -ms.assetid: 712623c6-f77e-47ea-a945-089e57c50b40 +helpviewer_keywords: ["/W* MASM compiler option", "/c MASM compiler option", "/EP MASM compiler option", "/Fe MASM compiler option", "/Zp MASM compiler option", "/AT MASM compiler option", "/Zm MASM compiler option", "/Sf MASM compiler option", "/Sp MASM compiler option", "/w MASM compiler option", "/Fl MASM compiler option", "/coff MASM compiler option", "/St MASM compiler option", "/Cx MASM compiler option", "/Sl MASM compiler option", "/Cu MASM compiler option", "MASM (Microsoft Macro Assembler), ML command-line reference", "/FPi MASM compiler option", "/Zf MASM compiler option", "ML environment variable", "/Fr MASM compiler option", "/help MASM compiler option", "/Sa MASM compiler option", "/Zd MASM compiler option", "/I MASM compiler option", "/? MASM compiler option", "/Bl MASM compiler option", "/Fm MASM compiler option", "/Fo MASM compiler option", "command-line reference [ML]", "/Sn MASM compiler option", "/Gd MASM compiler option", "/D* MASM compiler option", "environment variables, ML", "/Gc MASM compiler option", "/F* MASM compiler option", "/Sc MASM compiler option", "/H MASM compiler option", "/Zs MASM compiler option", "/omf MASM compiler option", "/quiet MASM compiler option", "/Sg MASM compiler option", "/Cp MASM compiler option", "/Zi MASM compiler option", "/nologo MASM compiler option", "/Sx MASM compiler option", "/WX MASM compiler option", "/Ss MASM compiler option", "command line, reference [ML]", "/Ta MASM compiler option"] --- # ML and ML64 command-line reference @@ -14,74 +13,77 @@ For more information on ml64.exe, see [MASM for x64 (ml64.exe)](masm-for-x64-ml6 ## Syntax -> ML \[*options*] *filename* \[ \[*options*] *filename*] +> **`ML`** \[*`options`*] *`filename`* \[ \[*`options`*] *`filename`*] > -> ML64 \[*options*] *filename* \[ \[*options*] *filename*] ... \[/link *link_options*] +> **`ML64`** \[*`options`*] *`filename`* \[ \[*`options`*] *`filename`*] ... \[**`/link`** *`link_options`*] ### Parameters -*options*\ -The options listed in the following table. - -|Option|Action| -|------------|------------| -|**/AT**|Enables tiny-memory-model support. Enables error messages for code constructs that violate the requirements for .com format files. This option isn't equivalent to the [.MODEL](dot-model.md) **TINY** directive.

Not available in ml64.exe.| -|**/Bl** *filename*|Selects an alternate linker.| -|**/c**|Assembles only. Does no linking.| -|**/coff**|Generates common object file format (COFF) type of object module. Required for Win32 assembly language development.

Not available in ml64.exe.| -|**/Cp**|Preserves case of all user identifiers.| -|**/Cu**|Maps all identifiers to upper case (default).

Not available in ml64.exe.| -|**/Cx**|Preserves case in public and extern symbols.| -|**/D** *symbol*⟦=*value*⟧|Defines a text macro with the given name. If *value* is missing, it's blank. Multiple tokens separated by spaces must be enclosed in quotation marks.| -|**/EP**|Generates a preprocessed source listing (sent to STDOUT). See **/Sf**.| -|**/ERRORREPORT** [ **NONE** | **PROMPT** | **QUEUE** | **SEND** ]| Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -|**/F** *hexnum*|Sets stack size to *hexnum* bytes (the same as **/link /STACK**:*number*). The value must be expressed in hexadecimal notation. There must be a space between **/F** and *hexnum*.| -|**/Fe** *filename*|Names the executable file.| -|**/Fl**⟦*filename*⟧|Generates an assembled code listing. See **/Sf**.| -|**/Fm**⟦*filename*⟧|Creates a linker map file.| -|**/Fo** *filename*|Names an object file. For more information, see [Remarks](#remarks).| -|**/FPi**|Generates emulator fix-ups for floating-point arithmetic (mixed language only).

Not available in ml64.exe.| -|**/Fr**⟦*filename*⟧|Generates a source browser .sbr file.| -|**/FR**⟦*filename*⟧|Generates an extended form of a source browser .sbr file.| -|**/Gc**|Specifies use of FORTRAN- or Pascal-style function calling and naming conventions. Same as **OPTION LANGUAGE:PASCAL**.

Not available in ml64.exe.| -|**/Gd**|Specifies use of C-style function calling and naming conventions. Same as **OPTION LANGUAGE:C**.

Not available in ml64.exe.| -|**/GZ**|Specifies use of __stdcall function calling and naming conventions. Same as **OPTION LANGUAGE:STCALL**.

Not available in ml64.exe.| -|**/H** *number*|Restricts external names to number significant characters. The default is 31 characters.

Not available in ml64.exe.| -|**/help**|Calls QuickHelp for help on ML.| -|**/I** *pathname*|Sets path for include file. A maximum of 10 **/I** options is allowed.| -|**/nologo**|Suppresses messages for successful assembly.| -|**/omf**|Generates object module file format (OMF) type of object module. **/omf** implies **/c**; ML.exe doesn't support linking OMF objects.

Not available in ml64.exe.| -|**/Sa**|Turns on listing of all available information.| -|**/safeseh**|Marks the object as either containing no exception handlers or containing exception handlers that are all declared with [.SAFESEH](dot-safeseh.md).

Not available in ml64.exe.| -|**/Sf**|Adds first-pass listing to listing file.| -|**/Sl** *width*|Sets the line width of source listing in characters per line. Range is 60 to 255 or 0. Default is 0. Same as [PAGE](page.md) width.| -|**/Sn**|Turns off symbol table when producing a listing.| -|**/Sp** *length*|Sets the page length of source listing in lines per page. Range is 10 to 255 or 0. Default is 0. Same as [PAGE](page.md) length.| -|**/Ss** *text*|Specifies text for source listing. Same as [SUBTITLE](subtitle.md) text.| -|**/St** *text*|Specifies title for source listing. Same as [TITLE](title.md) text.| -|**/Sx**|Turns on false conditionals in listing.| -|**/Ta** *filename*|Assembles source file whose name doesn't end with the .asm extension.| -|**/w**|Same as **/W0/WX**.| -|**/W** *level*|Sets the warning level, where *level* = 0, 1, 2, or 3.| -|**/WX**|Returns an error code if warnings are generated.| -|**/X**|Ignore INCLUDE environment path.| -|**/Zd**|Generates line-number information in object file.| -|**/Zf**|Makes all symbols public.| -|**/Zi**|Generates CodeView information in object file.| -|**/Zm**|Enables**M510** option for maximum compatibility with MASM 5.1.

Not available in ml64.exe.| -|**/Zp**⟦*alignment*⟧|Packs structures on the specified byte boundary. The *alignment* can be 1, 2, or 4.| -|**/Zs**|Performs a syntax check only.| -|**/?**|Displays a summary of ML command-line syntax.| - -*filename*\ +*`options`*\ +The options listed in the following table: + +| Option | Action | +|--|--| +| **`/AT`** | Enables tiny-memory-model support. Enables error messages for code constructs that violate the requirements for *`.com`* format files. This option isn't equivalent to the [`.MODEL`](dot-model.md) **`TINY`** directive.
Not available in ml64.exe. | +| **`/Bl`** *`filename`* | Selects an alternate linker in *`filename`*. | +| **`/c`** | Assembles only. Does no linking. | +| **`/coff`** | Generates common object file format (COFF) type of object module. Required for Win32 assembly language development.
Not available in ml64.exe. | +| **`/Cp`** | Preserves case of all user identifiers. | +| **`/Cu`** | Maps all identifiers to upper case (default).
Not available in ml64.exe. | +| **`/Cx`** | Preserves case in public and extern symbols. | +| **`/D`** *`symbol`*⟦=*`value`*⟧ | Defines a text macro with the given name *`symbol`*. If *`value`* is missing, it's blank. Multiple tokens separated by spaces must be enclosed in quotation marks. | +| **`/EP`** | Generates a preprocessed source listing (sent to `STDOUT`). See **`/Sf`**. | +| **`/ERRORREPORT`** [ **`NONE`** \| **`PROMPT`** \| **`QUEUE`** \| **`SEND`** ] | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| **`/F`** *`hexnum`* | Sets stack size to *`hexnum`* bytes (the same as **`/link /STACK:`**). The value must be expressed in hexadecimal notation. There must be a space between **`/F`** and *`hexnum`*. | +| **`/Fe`** *`filename`* | Names the executable file. | +| **`/Fl`**⟦*`filename`*⟧ | Generates an assembled code listing. See **/Sf**. | +| **`/Fm`**⟦*`filename`*⟧ | Creates a linker map file. | +| **`/Fo`** *`filename`* | Names an object file. For more information, see [Remarks](#remarks). | +| **`/FPi`** | Generates emulator fix-ups for floating-point arithmetic (mixed language only).
Not available in ml64.exe. | +| **`/Fr`**⟦*`filename`*⟧ | Generates a source browser *`.sbr`* file. | +| **`/FR`**⟦*`filename`*⟧ | Generates an extended form of a source browser *`.sbr`* file. | +| **`/Gc`** | Specifies use of FORTRAN- or Pascal-style conventions for function calls and names. Same as **`OPTION LANGUAGE:PASCAL`**.
Not available in ml64.exe. | +| **`/Gd`** | Specifies use of C-style conventions for function calls and names. Same as **`OPTION LANGUAGE:C`**.
Not available in ml64.exe. | +| **`/Gz`** | Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.
Not available in ml64.exe. | +| **`/H`** *`number`* | Restricts external names to *`number`* significant characters. The default is 31 characters.
Not available in ml64.exe. | +| **`/help`** | Displays a summary of ML command-line syntax and options. | +| **`/I`** *`pathname`* | Sets path for include file. A maximum of 10 **`/I`** options is allowed. | +| **`/nologo`** | Suppresses messages for successful assembly. | +| **`/omf`** | Generates object module file format (OMF) type of object module. **`/omf`** implies **`/c`**. ML.exe doesn't support linking OMF objects.
Not available in ml64.exe. | +| **`/quiet`** | Suppresses 'Assembling' message. Available in Visual Studio 17.6 and later. | +| **`/Sa`** | Turns on listing of all available information. | +| **`/safeseh`** | Marks the object file: either it contains no exception handlers, or it contains exception handlers that are all declared with [`.SAFESEH`](dot-safeseh.md).
Not available in ml64.exe. | +| **`/Sf`** | Adds the first-pass listing to the listing file. | +| **`/Sl`** *`width`* | Sets the line width of source listing in characters per line to *`width`*. Range is 60-255 or 0. Default is 0. Same as [`PAGE`](page.md) *`width`*. | +| **`/Sn`** | Turns off symbol table when a listing is produced. | +| **`/Sp`** *`length`* | Sets the page length of source listing in lines per page to *`length`*. Range is 10-255 or 0. Default is 0. Same as [`PAGE`](page.md) *`length`*. | +| **`/Ss`** *`text`* | Specifies text for source listing. Same as [`SUBTITLE`](subtitle.md) text. | +| **`/St`** *`text`* | Specifies title for source listing. Same as [`TITLE`](title.md) text. | +| **`/Sx`** | Turns on false conditionals in listing. | +| **`/Ta`** *`filename`* | Assembles source file whose name doesn't end with the *`.asm`* extension. | +| **`/w`** | Same as **`/W0 /WX`**. | +| **`/W`** *`level`* | Sets the warning level, where *`level`* = 0, 1, 2, or 3. | +| **`/WX`** | If warnings are generated, returns an error code. | +| **`/X`** | Ignore `INCLUDE` environment path. | +| **`/Zd`** | Generates line-number information in object file. | +| **`/Zf`** | Makes all symbols public. | +| **`/ZH:MD5`** | Use MD5 for checksum in debug info. | +| **`/ZH:SHA_256`** | Use SHA256 for checksum in debug info (default in Visual Studio 2022 version 17.0 and later). | +| **`/Zi`** | Generates CodeView information in object file. | +| **`/Zm`** | Enables **`M510`** option for maximum compatibility with MASM 5.1.
Not available in ml64.exe. | +| **`/Zp`**⟦*`alignment`*⟧ | Packs structures on the specified byte boundary. The *`alignment`* can be 1, 2, 4, 8, or 16. | +| **`/Zs`** | Performs a syntax check only. | +| **`/?`** | Displays a summary of ML command-line syntax and options. | + +*`filename`*\ The name of the file. -*link_options*\ +*`link_options`*\ The link options. For more information, see [Linker options](../../build/reference/linker-options.md). ## Remarks -Some command-line options to ML and ML64 are placement-sensitive. For example, because ML and ML64 can accept several **/c** options, any corresponding **/Fo** options must be specified before **/c**. The following command-line example illustrates an object file specification for each assembly file specification: +Some command-line options to ML and ML64 are placement-sensitive. For example, because ML and ML64 can accept several **`/c`** options, any corresponding **`/Fo`** options must be specified before **`/c`**. The following command-line example illustrates an object file specification for each assembly file specification: ```cmd ml.exe /Fo a1.obj /c a.asm /Fo b1.obj /c b.asm @@ -89,13 +91,13 @@ ml.exe /Fo a1.obj /c a.asm /Fo b1.obj /c b.asm ## Environment Variables -|Variable|Description| -|--------------|-----------------| -|INCLUDE|Specifies search path for include files.| -|ML|Specifies default command-line options.| -|TMP|Specifies path for temporary files.| +| Variable | Description | +|--|--| +| `INCLUDE` | Specifies search path for include files. | +| `ML` | Specifies default command-line options. | +| `TMP` | Specifies path for temporary files. | ## See also -[ML Error Messages](ml-error-messages.md)\ -[Microsoft Macro Assembler Reference](microsoft-macro-assembler-reference.md) +[ML error messages](ml-error-messages.md)\ +[Microsoft Macro Assembler reference](microsoft-macro-assembler-reference.md) diff --git a/docs/assembler/masm/ml-error-messages.md b/docs/assembler/masm/ml-error-messages.md index fa05763b6c..60ef663335 100644 --- a/docs/assembler/masm/ml-error-messages.md +++ b/docs/assembler/masm/ml-error-messages.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Error Messages" title: "ML Error Messages" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["vc.errors.ml"] helpviewer_keywords: ["MASM (Microsoft Macro Assembler), ML error messages"] ms.assetid: e7e164b3-6d65-4b5b-8925-bfbebc043523 diff --git a/docs/assembler/masm/ml-fatal-error-a1000.md b/docs/assembler/masm/ml-fatal-error-a1000.md index 58b8730b20..64c18b9e37 100644 --- a/docs/assembler/masm/ml-fatal-error-a1000.md +++ b/docs/assembler/masm/ml-fatal-error-a1000.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1000" title: "ML Fatal Error A1000" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1000"] helpviewer_keywords: ["A1000"] ms.assetid: 4fc77a83-8796-4dcf-9c37-6395d635b817 diff --git a/docs/assembler/masm/ml-fatal-error-a1005.md b/docs/assembler/masm/ml-fatal-error-a1005.md index 8dbccfde31..26a5522b82 100644 --- a/docs/assembler/masm/ml-fatal-error-a1005.md +++ b/docs/assembler/masm/ml-fatal-error-a1005.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1005" title: "ML Fatal Error A1005" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1005"] helpviewer_keywords: ["A1005"] ms.assetid: 42c7a6c5-277d-417c-acc1-d84c370e8d24 diff --git a/docs/assembler/masm/ml-fatal-error-a1007.md b/docs/assembler/masm/ml-fatal-error-a1007.md index dddac87749..8f6c7940ef 100644 --- a/docs/assembler/masm/ml-fatal-error-a1007.md +++ b/docs/assembler/masm/ml-fatal-error-a1007.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1007" title: "ML Fatal Error A1007" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1007"] helpviewer_keywords: ["A1007"] ms.assetid: bcf9c826-beb3-4e93-91fe-1ffd34995fbf diff --git a/docs/assembler/masm/ml-fatal-error-a1008.md b/docs/assembler/masm/ml-fatal-error-a1008.md index 64c30f7b55..c18d2492c9 100644 --- a/docs/assembler/masm/ml-fatal-error-a1008.md +++ b/docs/assembler/masm/ml-fatal-error-a1008.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1008" title: "ML Fatal Error A1008" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1008"] helpviewer_keywords: ["A1008"] ms.assetid: fe592f9d-c37b-4cd8-a51d-e3c15ddcab83 diff --git a/docs/assembler/masm/ml-fatal-error-a1009.md b/docs/assembler/masm/ml-fatal-error-a1009.md index b3395c7b59..23fe9aee2c 100644 --- a/docs/assembler/masm/ml-fatal-error-a1009.md +++ b/docs/assembler/masm/ml-fatal-error-a1009.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1009" title: "ML Fatal Error A1009" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1009"] helpviewer_keywords: ["A1009"] ms.assetid: f7a962a6-4280-485e-95cb-2ab8922c66c2 diff --git a/docs/assembler/masm/ml-fatal-error-a1010.md b/docs/assembler/masm/ml-fatal-error-a1010.md index 7c0b1733fc..0229ad3136 100644 --- a/docs/assembler/masm/ml-fatal-error-a1010.md +++ b/docs/assembler/masm/ml-fatal-error-a1010.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1010" title: "ML Fatal Error A1010" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1010"] helpviewer_keywords: ["A1010"] ms.assetid: 9e0b5241-67f4-4740-8701-3b2d2d1ad9e4 diff --git a/docs/assembler/masm/ml-fatal-error-a1011.md b/docs/assembler/masm/ml-fatal-error-a1011.md index e64d7bef96..6a5e3ea920 100644 --- a/docs/assembler/masm/ml-fatal-error-a1011.md +++ b/docs/assembler/masm/ml-fatal-error-a1011.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1011" title: "ML Fatal Error A1011" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1011"] helpviewer_keywords: ["A1011"] ms.assetid: 7fbf092d-4189-4330-a884-dfa2268fc3dd diff --git a/docs/assembler/masm/ml-fatal-error-a1016.md b/docs/assembler/masm/ml-fatal-error-a1016.md index c0281f0d1c..193e1af425 100644 --- a/docs/assembler/masm/ml-fatal-error-a1016.md +++ b/docs/assembler/masm/ml-fatal-error-a1016.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1016" title: "ML Fatal Error A1016" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1016"] helpviewer_keywords: ["A1016"] ms.assetid: 440b3750-ba0b-44d8-b82d-d581f62c08b2 diff --git a/docs/assembler/masm/ml-fatal-error-a1017.md b/docs/assembler/masm/ml-fatal-error-a1017.md index 024e05953a..186314b280 100644 --- a/docs/assembler/masm/ml-fatal-error-a1017.md +++ b/docs/assembler/masm/ml-fatal-error-a1017.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1017" title: "ML Fatal Error A1017" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1017"] helpviewer_keywords: ["A1017"] ms.assetid: bef0b312-5431-4e5a-b637-c19919acf01b diff --git a/docs/assembler/masm/ml-nonfatal-error-a2004.md b/docs/assembler/masm/ml-nonfatal-error-a2004.md index c6b906e562..cb40f2e8d3 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2004.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2004.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2004" title: "ML Nonfatal Error A2004" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2004"] helpviewer_keywords: ["A2004"] ms.assetid: 74e219ba-4dec-467a-b121-18a76aa57230 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2006.md b/docs/assembler/masm/ml-nonfatal-error-a2006.md index 43c8f5a860..5eb17a38e6 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2006.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2006.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2006" title: "ML Nonfatal Error A2006" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2006"] helpviewer_keywords: ["A2006"] ms.assetid: b8a8f096-95df-42b5-85ed-d2530560a84c diff --git a/docs/assembler/masm/ml-nonfatal-error-a2008.md b/docs/assembler/masm/ml-nonfatal-error-a2008.md index fe1bb27488..b648e40ee5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2008.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2008.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2008" title: "ML Nonfatal Error A2008" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2008"] helpviewer_keywords: ["A2008"] ms.assetid: ca24157f-c88a-4678-ae06-3bc3cd956001 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2010.md b/docs/assembler/masm/ml-nonfatal-error-a2010.md index 9b8e63a98d..0037f31377 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2010.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2010.md @@ -2,16 +2,18 @@ description: "Learn more about: ML Nonfatal Error A2010" title: "ML Nonfatal Error A2010" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2010"] helpviewer_keywords: ["A2010"] ms.assetid: 8bcd57f4-1e3f-421f-9ef8-e702daf57fcb --- # ML Nonfatal Error A2010 -**invalid type expression** +> **invalid type expression** -The operand to [THIS](operator-this.md) or [PTR](operator-ptr.md) was not a valid type expression. +## Remarks + +The operand to [`THIS`](operator-this.md) or [`PTR`](operator-ptr.md) wasn't a valid type expression. ## See also diff --git a/docs/assembler/masm/ml-nonfatal-error-a2019.md b/docs/assembler/masm/ml-nonfatal-error-a2019.md index ba6c9f21dd..90bd405bec 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2019.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2019.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2019" title: "ML Nonfatal Error A2019" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2019"] helpviewer_keywords: ["A2019"] ms.assetid: 7dff209b-6d91-4e39-88a3-5d6329bac537 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2022.md b/docs/assembler/masm/ml-nonfatal-error-a2022.md index df9fae2891..8751e3f61e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2022.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2022.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2022" title: "ML Nonfatal Error A2022" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2022"] helpviewer_keywords: ["A2022"] ms.assetid: 3f4b1017-543e-4236-820f-61070ab58920 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2031.md b/docs/assembler/masm/ml-nonfatal-error-a2031.md index f82a717e43..ca2b604bdc 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2031.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2031.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2031" title: "ML Nonfatal Error A2031" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2031"] helpviewer_keywords: ["A2031"] ms.assetid: d5b11f58-4a00-42be-9062-8fa8728e6306 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2034.md b/docs/assembler/masm/ml-nonfatal-error-a2034.md index c1759d7f64..3f39de593f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2034.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2034.md @@ -2,30 +2,32 @@ description: "Learn more about: ML Nonfatal Error A2034" title: "ML Nonfatal Error A2034" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2034"] helpviewer_keywords: ["A2034"] ms.assetid: 6438970c-0aee-4f14-a058-5fe47d0ee216 --- # ML Nonfatal Error A2034 -**must be in segment block** +> **must be in segment block** -One of the following was found outside of a segment block: +## Remarks + +The assembler found one of the following items outside of a segment block: - An instruction - A label definition -- A [THIS](operator-this.md) operator +- A [`THIS`](operator-this.md) operator -- A [$](dollar.md) operator +- A [`$`](dollar.md) operator - A procedure definition -- An [ALIGN](align-masm.md) directive +- An [`ALIGN`](align-masm.md) directive -- An [ORG](org.md) directive +- An [`ORG`](org.md) directive ## See also diff --git a/docs/assembler/masm/ml-nonfatal-error-a2037.md b/docs/assembler/masm/ml-nonfatal-error-a2037.md index 38416a396a..8f3aa5c882 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2037.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2037.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2037" title: "ML Nonfatal Error A2037" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2037"] helpviewer_keywords: ["A2037"] ms.assetid: e7fdb98b-3ce9-4e1f-99fc-1b1ea10b6961 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2038.md b/docs/assembler/masm/ml-nonfatal-error-a2038.md index e80aebd1bb..cc8d4dc964 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2038.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2038.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2038" title: "ML Nonfatal Error A2038" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2038"] helpviewer_keywords: ["A2038"] ms.assetid: 001bf60a-58ac-4654-97eb-b734f2999f8e diff --git a/docs/assembler/masm/ml-nonfatal-error-a2039.md b/docs/assembler/masm/ml-nonfatal-error-a2039.md index f281ad154f..055cb0540a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2039.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2039.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2039" title: "ML Nonfatal Error A2039" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2039"] helpviewer_keywords: ["A2039"] ms.assetid: ad8cdaae-b20d-45f0-acb1-79880979c6b7 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2044.md b/docs/assembler/masm/ml-nonfatal-error-a2044.md index bd6b47e17f..0997887d02 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2044.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2044.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2044" title: "ML Nonfatal Error A2044" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2044"] helpviewer_keywords: ["A2044"] ms.assetid: 7cf144ac-408c-4e35-9a15-38656a4e87cd diff --git a/docs/assembler/masm/ml-nonfatal-error-a2047.md b/docs/assembler/masm/ml-nonfatal-error-a2047.md index 31611b75c2..6896fe8592 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2047.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2047.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2047" title: "ML Nonfatal Error A2047" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2047"] helpviewer_keywords: ["A2047"] ms.assetid: 7799f988-6c2e-4022-a447-c56b48473f0c diff --git a/docs/assembler/masm/ml-nonfatal-error-a2050.md b/docs/assembler/masm/ml-nonfatal-error-a2050.md index dba465efd8..924f38d3f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2050.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2050.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2050" title: "ML Nonfatal Error A2050" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2050"] helpviewer_keywords: ["A2050"] ms.assetid: 16f3a58f-4bde-48f1-b0e3-2ed9612780a5 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2054.md b/docs/assembler/masm/ml-nonfatal-error-a2054.md index d4b0d750d7..febf4f6c4e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2054.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2054.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2054" title: "ML Nonfatal Error A2054" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2054"] helpviewer_keywords: ["A2054"] ms.assetid: 878a2ced-0b88-49e5-bea5-0a014efb08b6 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2055.md b/docs/assembler/masm/ml-nonfatal-error-a2055.md index 057ed4ca3b..54e57104a9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2055.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2055.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2055" title: "ML Nonfatal Error A2055" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2055"] helpviewer_keywords: ["A2055"] ms.assetid: b4c3585f-6e55-4127-ba84-e68a41f1ada8 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2057.md b/docs/assembler/masm/ml-nonfatal-error-a2057.md index 39029959c4..98ba11536a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2057.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2057.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2057" title: "ML Nonfatal Error A2057" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2057"] helpviewer_keywords: ["A2057"] ms.assetid: 13c47848-3f4d-4145-a00c-5418ff176ba3 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2059.md b/docs/assembler/masm/ml-nonfatal-error-a2059.md index aa648c9909..4f563d54ac 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2059.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2059.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2059" title: "ML Nonfatal Error A2059" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2059"] helpviewer_keywords: ["A2059"] ms.assetid: fadabbce-3054-4758-aeae-34d8540ce410 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2060.md b/docs/assembler/masm/ml-nonfatal-error-a2060.md index eb4c2bca21..3e74b86485 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2060.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2060.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2060" title: "ML Nonfatal Error A2060" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2060"] helpviewer_keywords: ["A2060"] ms.assetid: 435d5b32-9b4f-4f4e-8142-af0ce7676e89 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2063.md b/docs/assembler/masm/ml-nonfatal-error-a2063.md index ad369aba9e..2da91f339b 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2063.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2063.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2063" title: "ML Nonfatal Error A2063" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2063"] helpviewer_keywords: ["A2063"] ms.assetid: 12976b25-2159-4e0c-9df3-dcfac61091ee diff --git a/docs/assembler/masm/ml-nonfatal-error-a2064.md b/docs/assembler/masm/ml-nonfatal-error-a2064.md index 21bf975dca..ed06a37737 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2064.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2064.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2064" title: "ML Nonfatal Error A2064" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2064"] helpviewer_keywords: ["A2064"] ms.assetid: 553a5ec5-b404-4321-ab2c-b9ccec6471fc diff --git a/docs/assembler/masm/ml-nonfatal-error-a2065.md b/docs/assembler/masm/ml-nonfatal-error-a2065.md index 336fdc4b63..316f95333e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2065.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2065.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2065" title: "ML Nonfatal Error A2065" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2065"] helpviewer_keywords: ["A2065"] ms.assetid: 836e46c7-461a-4abc-8d48-03952c5b25f4 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2066.md b/docs/assembler/masm/ml-nonfatal-error-a2066.md index 529b93d4f7..f1583f30b5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2066.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2066.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2066" title: "ML Nonfatal Error A2066" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2066"] helpviewer_keywords: ["A2066"] ms.assetid: 58220fdf-fb8f-47fc-a36d-737867361185 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2069.md b/docs/assembler/masm/ml-nonfatal-error-a2069.md index 7403f746f1..5ebda337f1 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2069.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2069.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2069" title: "ML Nonfatal Error A2069" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2069"] helpviewer_keywords: ["A2069"] ms.assetid: 57dbf072-da61-4306-8d41-a4d9c97fec1a diff --git a/docs/assembler/masm/ml-nonfatal-error-a2070.md b/docs/assembler/masm/ml-nonfatal-error-a2070.md index 0ceafc257e..2267b0ccdd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2070.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2070.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2070" title: "ML Nonfatal Error A2070" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2070"] helpviewer_keywords: ["A2070"] ms.assetid: f6025e2c-b142-426f-88c8-7160df4c1631 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2074.md b/docs/assembler/masm/ml-nonfatal-error-a2074.md index d3fd8fe842..50f575f954 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2074.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2074.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2074" title: "ML Nonfatal Error A2074" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2074"] helpviewer_keywords: ["A2074"] ms.assetid: d19600d8-785b-4afb-af77-9dbbeb6a1275 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2078.md b/docs/assembler/masm/ml-nonfatal-error-a2078.md index 636fed7832..0b287e79bd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2078.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2078.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2078" title: "ML Nonfatal Error A2078" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2078"] helpviewer_keywords: ["A2078"] ms.assetid: 42ac48fd-ac7f-4e74-a11e-20181d443faf diff --git a/docs/assembler/masm/ml-nonfatal-error-a2079.md b/docs/assembler/masm/ml-nonfatal-error-a2079.md index cc2dd601f5..f04053fcc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2079.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2079.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2079" title: "ML Nonfatal Error A2079" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2079"] helpviewer_keywords: ["A2079"] ms.assetid: 87003fa1-ce71-4572-9efc-06a4404860ab diff --git a/docs/assembler/masm/ml-nonfatal-error-a2083.md b/docs/assembler/masm/ml-nonfatal-error-a2083.md index 6d5a9e0898..0e852033cd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2083.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2083.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2083" title: "ML Nonfatal Error A2083" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2083"] helpviewer_keywords: ["A2083"] ms.assetid: d2715877-1702-44e5-ab8f-6ef1fb6069f1 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2085.md b/docs/assembler/masm/ml-nonfatal-error-a2085.md index 78664076a6..70def6928d 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2085.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2085.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2085" title: "ML Nonfatal Error A2085" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2085"] helpviewer_keywords: ["A2085"] ms.assetid: c2fef415-a32b-4249-896c-6d981fc6e327 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2096.md b/docs/assembler/masm/ml-nonfatal-error-a2096.md index 100cf67596..f670b73aca 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2096.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2096.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2096" title: "ML Nonfatal Error A2096" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2096"] helpviewer_keywords: ["A2096"] ms.assetid: bab0b5ee-b39f-4e44-a41a-3f949fab4297 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2097.md b/docs/assembler/masm/ml-nonfatal-error-a2097.md index 9f35dcdc76..abeea9f8f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2097.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2097.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2097" title: "ML Nonfatal Error A2097" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2097"] helpviewer_keywords: ["A2097"] ms.assetid: 52f6f1f8-4eb4-4264-8619-7b9ccb20c0c7 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2107.md b/docs/assembler/masm/ml-nonfatal-error-a2107.md index 5f26d5f2e6..0c7b3ad230 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2107.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2107.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2107" title: "ML Nonfatal Error A2107" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2107"] helpviewer_keywords: ["A2107"] ms.assetid: 0385b9f2-36df-4e30-a905-ab49bdc504d1 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2119.md b/docs/assembler/masm/ml-nonfatal-error-a2119.md index e487e73215..e19e92eb19 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2119.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2119.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2119" title: "ML Nonfatal Error A2119" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2119"] helpviewer_keywords: ["A2119"] ms.assetid: 4d4ee6da-3a58-495c-a1da-c3a405c4c18d diff --git a/docs/assembler/masm/ml-nonfatal-error-a2133.md b/docs/assembler/masm/ml-nonfatal-error-a2133.md index 69b444fba7..fa9872a213 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2133.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2133.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2133" title: "ML Nonfatal Error A2133" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2133"] helpviewer_keywords: ["A2133"] ms.assetid: 5ba50911-22c8-43b7-90e2-946fc612e05f diff --git a/docs/assembler/masm/ml-nonfatal-error-a2137.md b/docs/assembler/masm/ml-nonfatal-error-a2137.md index a06ef7e218..d9c908f94f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2137.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2137.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2137" title: "ML Nonfatal Error A2137" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2137"] helpviewer_keywords: ["A2137"] ms.assetid: 913172e3-866e-49c3-9502-e49d1f0df4b0 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2189.md b/docs/assembler/masm/ml-nonfatal-error-a2189.md index 4b5ed1af16..2fca4c0dc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2189.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2189.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2189" title: "ML Nonfatal Error A2189" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2189"] helpviewer_keywords: ["A2189"] ms.assetid: 39649f39-57bc-4ceb-ab16-53f9b2a8d2d5 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2206.md b/docs/assembler/masm/ml-nonfatal-error-a2206.md index 688342d02b..8a1264fe6c 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2206.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2206.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2206" title: "ML Nonfatal Error A2206" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2206"] helpviewer_keywords: ["A2206"] ms.assetid: 711846d0-5a09-4353-8857-60588c25526a diff --git a/docs/assembler/masm/ml-nonfatal-error-a2219.md b/docs/assembler/masm/ml-nonfatal-error-a2219.md index efe52667e4..7d6dc6b457 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2219.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2219.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2219" title: "ML Nonfatal Error A2219" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2219"] helpviewer_keywords: ["A2219"] ms.assetid: 5ebc2f40-e47e-4f8e-b7b9-960b9cfc9f6d diff --git a/docs/assembler/masm/ml-warning-a4004.md b/docs/assembler/masm/ml-warning-a4004.md index d1631f84d9..ee4e7df825 100644 --- a/docs/assembler/masm/ml-warning-a4004.md +++ b/docs/assembler/masm/ml-warning-a4004.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4004" title: "ML Warning A4004" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4004"] helpviewer_keywords: ["A4004"] ms.assetid: f11b13c9-fa8d-49f2-b816-a6b7871c7261 diff --git a/docs/assembler/masm/ml-warning-a4012.md b/docs/assembler/masm/ml-warning-a4012.md index bb5ff35a53..52fe3645e8 100644 --- a/docs/assembler/masm/ml-warning-a4012.md +++ b/docs/assembler/masm/ml-warning-a4012.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4012" title: "ML Warning A4012" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4012"] helpviewer_keywords: ["A4012"] ms.assetid: 842b1259-9679-4eeb-a02d-672a583a94e5 diff --git a/docs/assembler/masm/ml-warning-a4014.md b/docs/assembler/masm/ml-warning-a4014.md index 9550b5f042..dbecdeb23c 100644 --- a/docs/assembler/masm/ml-warning-a4014.md +++ b/docs/assembler/masm/ml-warning-a4014.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4014" title: "ML Warning A4014" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4014"] helpviewer_keywords: ["A4014"] ms.assetid: 11bc8920-3255-4ac8-999a-b9ea9c15bc81 diff --git a/docs/assembler/masm/operator-this.md b/docs/assembler/masm/operator-this.md index 7f6640e917..bf1695d145 100644 --- a/docs/assembler/masm/operator-this.md +++ b/docs/assembler/masm/operator-this.md @@ -6,13 +6,13 @@ f1_keywords: ["this", "operator THIS"] helpviewer_keywords: ["operator THIS", "THIS operator"] ms.assetid: d795aa0e-6c01-49b7-8c64-8ab111fd82d3 --- -# operator THIS +# operator `THIS` Returns an operand of specified *type* whose offset and segment values are equal to the current location counter value. ## Syntax -> **THIS** *type* +> **`THIS`** *type* ## See also diff --git a/docs/assembler/masm/option-avxencoding-masm.md b/docs/assembler/masm/option-avxencoding-masm.md index c019dc5f8c..806b205a3b 100644 --- a/docs/assembler/masm/option-avxencoding-masm.md +++ b/docs/assembler/masm/option-avxencoding-masm.md @@ -1,9 +1,9 @@ --- title: "OPTION AVXENCODING" +description: Describes how to select the preferred encoding of AVX instructions when more than one possibility will work ms.date: "10/06/2020" f1_keywords: ["avxencoding"] helpviewer_keywords: ["OPTION AVXENCODING directive"] -description: Describes how to select the preferred encoding of AVX instructions when more than one possibility will work --- # OPTION AVXENCODING @@ -47,7 +47,7 @@ The **`OPTION AVXENCODING`** directive is available in Visual Studio 2019 versio ### Example -This example uses `VPDPBUSD` and `VPMADDWD` instructions to illustrate how the **`AVXENCODING`** option works. `VPDPBUSD` was first defined to be encoded only with `EVEX`, and was later extended with a VEX-encoded form for platforms without AVX-512 support, while `VPMADDWD` was AVX and extended to AVX-512. The listing output from assembling the example shows how changing the **`AVXENCODING`** mode affects the object code generated for each instruction. The prefix for each instruction ends at the '/". +This example uses `VPDPBUSD` and `VPMADDWD` instructions to illustrate how the **`AVXENCODING`** option works. `VPDPBUSD` was first defined to be encoded only with `EVEX`, and was later extended with a VEX-encoded form for platforms without AVX-512 support, while `VPMADDWD` was AVX and extended to AVX-512. The listing output from assembling the example shows how changing the **`AVXENCODING`** mode affects the object code generated for each instruction. The prefix for each instruction ends at the "/". ```asm 00000000 62 F2 6D 08/ 50 vpdpbusd xmm1, xmm2, xmm3 diff --git a/docs/assembler/masm/processor-manufacturer-programming-manuals.md b/docs/assembler/masm/processor-manufacturer-programming-manuals.md index 1414153abd..4774fdeeb7 100644 --- a/docs/assembler/masm/processor-manufacturer-programming-manuals.md +++ b/docs/assembler/masm/processor-manufacturer-programming-manuals.md @@ -1,22 +1,18 @@ --- description: "Learn more about: Processor manufacturer programming manuals" title: "Processor manufacturer programming manuals" -ms.date: "05/28/2020" -ms.assetid: 61844163-de2f-419a-808e-04de39dfdddf +ms.date: "12/6/2024" --- # Processor manufacturer programming manuals -This article provides links to websites that may contain programming info about processors that aren't made, sold, or supported by Microsoft. Microsoft doesn't control the websites or their content. +This article provides links to websites that may contain programming info about processors that Microsoft doesn't make, sell, or support. Microsoft doesn't control the websites or their content. ## Processor manufacturer websites -- [AMD Developer Guides, Manuals & ISA Documents](https://developer.amd.com/resources/developer-guides-manuals/) - +- [AMD Documentation Hub](https://www.amd.com/en/search/documentation/hub.html) - [ARM Architecture Reference Manual](https://developer.arm.com/documentation/ddi0487/latest/) - -- [Intel 64 and IA-32 Architectures Software Developer Manuals](https://software.intel.com/articles/intel-sdm) - -- [Introduction to Intel Advanced Vector Extensions](https://software.intel.com/articles/introduction-to-intel-advanced-vector-extensions) +- [Intel 64 and IA-32 Architectures Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html) +- [Introducing Intel® Advanced Performance Extensions (Intel APX)](https://www.intel.com/content/www/us/en/developer/articles/technical/advanced-performance-extensions-apx.html) ## Remarks diff --git a/docs/assembler/masm/purge.md b/docs/assembler/masm/purge.md index 2e19584edd..9051b7fae9 100644 --- a/docs/assembler/masm/purge.md +++ b/docs/assembler/masm/purge.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: PURGE" title: "PURGE" +description: "Learn more about: PURGE" ms.date: "12/16/2019" f1_keywords: ["PURGE"] helpviewer_keywords: ["PURGE directive"] -ms.assetid: 1e7ec2bf-f123-4ff9-97de-28b512ade2f9 --- # PURGE @@ -16,5 +15,5 @@ Deletes the specified macros from memory. ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/subttl.md b/docs/assembler/masm/subttl.md index b59e41f224..a119b8eb14 100644 --- a/docs/assembler/masm/subttl.md +++ b/docs/assembler/masm/subttl.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: SUBTTL" title: "SUBTTL" +description: "Learn more about: SUBTTL" ms.date: "12/16/2019" f1_keywords: ["SUBTTL"] helpviewer_keywords: ["SUBTTL directive"] -ms.assetid: 927efadd-ec99-4de9-b64d-229bb2df3bf4 --- # SUBTTL @@ -16,5 +15,5 @@ See [SUBTITLE](subtitle.md). ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md index 8089fa46bc..b257f105f9 100644 --- a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md +++ b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md @@ -15,16 +15,16 @@ In general, the rules for allocating and releasing memory allocated for `BSTR`s - When you call into a function that expects a `BSTR` argument, you must allocate the memory for the `BSTR` before the call and release it afterwards. For example: [!code-cpp[NVC_ATLMFC_Utilities#192](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_1.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#193](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_2.cpp)] - When you call into a function that returns a `BSTR`, you must free the string yourself. For example: [!code-cpp[NVC_ATLMFC_Utilities#194](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_3.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#195](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_4.cpp)] -- When you implement a function that returns a `BSTR`, allocate the string but do not free it. The receiving the function releases the memory. For example: +- When you implement a function that returns a `BSTR`, allocate the string but do not free it. The receiving function releases the memory. For example: [!code-cpp[NVC_ATLMFC_Utilities#196](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_5.cpp)] diff --git a/docs/atl-mfc-shared/basic-cstring-operations.md b/docs/atl-mfc-shared/basic-cstring-operations.md index 41926fe05b..047bd978b2 100644 --- a/docs/atl-mfc-shared/basic-cstring-operations.md +++ b/docs/atl-mfc-shared/basic-cstring-operations.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Basic CString Operations" title: "Basic CString Operations" -ms.date: "11/04/2016" +description: "Learn more about: Basic CString Operations" +ms.date: 11/04/2016 helpviewer_keywords: ["CString objects, basic operations", "string literals, CString operations", "literal strings, CString operations", "CString objects", "string comparison, CString operations", "characters, accessing in CStrings"] -ms.assetid: 41db66b2-9427-4bb3-845a-9b6869159a6c --- # Basic CString Operations @@ -19,7 +18,7 @@ This topic explains the following basic [CString](../atl-mfc-shared/reference/cs - [Converting CString objects](#_core_converting_cstring_objects) -`Class CString` is based on class template [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md). `CString` is a **`typedef`** of `CStringT`. More exactly, `CString` is a **`typedef`** of an *explicit specialization* of `CStringT`, which is a common way to use a class template to define a class. Similarly defined classes are `CStringA` and `CStringW`. +`Class CString` is based on class template [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md). `CString` is a **`typedef`** of `CStringT`. More exactly, `CString` is a **`typedef`** of an *explicit specialization* of `CStringT`, which is a common way to use a class template to define a class. Similarly defined classes are `CStringA` and `CStringW`. `CString`, `CStringA`, and `CStringW` are defined in atlstr.h. `CStringT` is defined in cstringt.h. diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp index 78a3ad3444..2b6ff825fd 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp @@ -1,5 +1,5 @@ // OEM character 252 on most IBM-compatible computers in - // Western countries/regions is superscript n, as in 2^n. + // many countries/regions is superscript n, as in 2^n. // Converting it to the ANSI English charset results in a // normal character 'n', which is the closest possible // representation. @@ -14,4 +14,4 @@ // the character's value truly was. str.AnsiToOem(); ASSERT(str[0] != 252); - ASSERT(str[0] == 'n'); \ No newline at end of file + ASSERT(str[0] == 'n'); diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp index e9d808179a..2dd71b8650 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp @@ -3,6 +3,6 @@ // or an apostrophe('). // typedef CStringT>> CAtlString; - CAtlString src(_T("World Cup '98")); + CAtlString src(_T("abcdef")); _tprintf_s(_T("%s"),src.SpanExcluding(_T(";,.-'"))); \ No newline at end of file diff --git a/docs/atl-mfc-shared/cstring-argument-passing.md b/docs/atl-mfc-shared/cstring-argument-passing.md index 763e4adea7..68ff5addc6 100644 --- a/docs/atl-mfc-shared/cstring-argument-passing.md +++ b/docs/atl-mfc-shared/cstring-argument-passing.md @@ -3,21 +3,20 @@ description: "Learn more about: CString Argument Passing" title: "CString Argument Passing" ms.date: "11/04/2016" helpviewer_keywords: ["strings [C++], as function input/output", "argument passing [C++]", "arguments [C++], passing", "functions [C++], strings as input/output", "argument passing [C++], C strings", "passing arguments, C strings", "CString objects, passing arguments", "string arguments"] -ms.assetid: a67bebff-edf1-4cf4-bbff-d1cc6a901099 --- -# CString Argument Passing +# `CString` Argument Passing -This article explains how to pass [CString](../atl-mfc-shared/reference/cstringt-class.md) objects to functions and how to return `CString` objects from functions. +This article explains how to pass [`CString`](../atl-mfc-shared/reference/cstringt-class.md) objects to functions and how to return `CString` objects from functions. -## CString Argument-Passing Conventions +## `CString` Argument-Passing Conventions -When you define a class interface, you must determine the argument-passing convention for your member functions. There are some standard rules for passing and returning `CString` objects. If you follow the rules described in [Strings as Function Inputs](#_core_strings_as_function_inputs) and [Strings as Function Outputs](#_core_strings_as_function_outputs), you will have efficient, correct code. +When you define a class interface, you must determine the argument-passing convention for your member functions. There are some standard rules for passing and returning `CString` objects. If you follow the rules described in [Strings as Function Inputs](#_core_strings_as_function_inputs) and [Strings as Function Outputs](#_core_strings_as_function_outputs), you'll have efficient, correct code. ## Strings as Function Inputs -The most efficient and secure way to use a `CString` object in called functions is to pass a `CString` object to the function. Despite the name, a `CString` object does not store a string internally as a C-style string that has a null terminator. Instead, a `CString` object keeps careful track of the number of characters it has. Having `CString` provide a LPCTSTR pointer to a null-terminated string is a small amount of work that can become significant if your code has to do it constantly. The result is temporary because any change to the `CString` contents invalidates old copies of the LPCTSTR pointer. +The most efficient and secure way to use a `CString` object in called functions is to pass a `CString` object to the function. Despite the name, a `CString` object doesn't store a string internally as a C-style string that has a `NULL` terminator. Instead, a `CString` object keeps careful track of the number of characters it has. Having `CString` provide an `LPCTSTR` pointer to a `NULL`-terminated string is a small amount of work that can become significant if your code has to do it constantly. The result is temporary because any change to the `CString` contents invalidates old copies of the `LPCTSTR` pointer. -It does make sense in some cases to provide a C-style string. For example, there can be a situation where a called function is written in C and does not support objects. In this case, coerce the `CString` parameter to LPCTSTR, and the function will get a C-style null-terminated string. You can also go the other direction and create a `CString` object by using the `CString` constructor that accepts a C-style string parameter. +It does make sense in some cases to provide a C-style string. For example, there can be a situation where a called function is written in C and doesn't support objects. In this case, coerce the `CString` parameter to `LPCTSTR`, and the function will get a C-style `NULL`-terminated string. You can also go the other direction and create a `CString` object by using the `CString` constructor that accepts a C-style string parameter. If the string contents are to be changed by a function, declare the parameter as a nonconstant `CString` reference (`CString&`). @@ -26,7 +25,7 @@ If the string contents are to be changed by a function, declare the parameter as Typically you can return `CString` objects from functions because `CString` objects follow value semantics like primitive types. To return a read-only string, use a constant `CString` reference (`const CString&`). The following example illustrates the use of `CString` parameters and return types: [!code-cpp[NVC_ATLMFC_Utilities#197](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#198](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_2.cpp)] ## See also diff --git a/docs/atl-mfc-shared/date-and-time.md b/docs/atl-mfc-shared/date-and-time.md index ccc38a2767..6285d86cb2 100644 --- a/docs/atl-mfc-shared/date-and-time.md +++ b/docs/atl-mfc-shared/date-and-time.md @@ -3,33 +3,32 @@ description: "Learn more about: Date and Time" title: "Date and Time" ms.date: "08/13/2019" helpviewer_keywords: ["time, MFC programming", "time", "MFC, date and time", "dates, MFC"] -ms.assetid: ecf56dc5-d418-4603-ad3e-af7e205a6403 --- # Date and Time MFC supports several different ways of working with dates and times: -- Support for the Automation [DATE data type](../atl-mfc-shared/date-type.md). DATE supports date, time, and date/time values. The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) and [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) classes encapsulate this functionality. They work with the [COleVariant](../mfc/reference/colevariant-class.md) class using Automation support. +- Support for the Automation [`DATE` data type](../atl-mfc-shared/date-type.md). `DATE` supports date, time, and date/time values. The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) and [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) classes encapsulate this functionality. They work with the [`COleVariant`](../mfc/reference/colevariant-class.md) class using Automation support. -- General-purpose time classes. The [CTime](../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../atl-mfc-shared/reference/ctimespan-class.md) classes encapsulate most of the functionality associated with the ANSI-standard time library, which is declared in TIME.H. +- General-purpose time classes. The [`CTime`](../atl-mfc-shared/reference/ctime-class.md) and [`CTimeSpan`](../atl-mfc-shared/reference/ctimespan-class.md) classes encapsulate most of the functionality associated with the ANSI-standard time library, which is declared in `time.h`. - Support for system clock. With MFC version 3.0, support was added to `CTime` for the Win32 `SYSTEMTIME` and `FILETIME` data types. ## Date and Time: Automation Support -The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) class provides a way to represent date and time information. It provides finer granularity and a greater range than the [CTime](../atl-mfc-shared/reference/ctime-class.md) class. The [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) class represents elapsed time, such as the difference between two `COleDateTime` objects. +The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) class provides a way to represent date and time information. It provides finer granularity and a greater range than the [`CTime`](../atl-mfc-shared/reference/ctime-class.md) class. The [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) class represents elapsed time, such as the difference between two `COleDateTime` objects. -The `COleDateTime` and `COleDateTimeSpan` classes are designed for use with the `COleVariant` class. `COleDateTime` and `COleDateTimeSpan` are also useful in MFC database programming, but they can be used whenever you want to manipulate date and time values. Although the `COleDateTime` class has a greater range of values and finer granularity than the `CTime` class, it requires more storage per object than `CTime`. There are also some special considerations when working with the underlying DATE type. For more information on the implementation of DATE, see [The DATE Type](../atl-mfc-shared/date-type.md). +The `COleDateTime` and `COleDateTimeSpan` classes are designed for use with the `COleVariant` class. `COleDateTime` and `COleDateTimeSpan` are also useful in MFC database programming, but they can be used whenever you want to manipulate date and time values. Although the `COleDateTime` class has a greater range of values and finer granularity than the `CTime` class, it requires more storage per object than `CTime`. There are also some special considerations when working with the underlying DATE type. For more information on the implementation of `DATE`, see [The `DATE` Type](../atl-mfc-shared/date-type.md). -`COleDateTime` objects can be used to represent dates between January 1, 100, and December 31, 9999. `COleDateTime` objects are floating point values, with an approximate resolution of 1 millisecond. `COleDateTime` is based on the DATE data type, defined in the MFC documentation under [COleDateTime::operator DATE](../atl-mfc-shared/reference/coledatetime-class.md#operator_date). The actual implementation of DATE extends beyond these bounds. The `COleDateTime` implementation imposes these bounds to make it easier to work with the class. +`COleDateTime` objects can be used to represent dates between January 1, 100, and December 31, 9999. `COleDateTime` objects are floating point values, with an approximate resolution of 1 millisecond. `COleDateTime` is based on the `DATE` data type, defined in the MFC documentation under [`COleDateTime::operator DATE`](../atl-mfc-shared/reference/coledatetime-class.md#operator_date). The actual implementation of `DATE` extends beyond these bounds. The `COleDateTime` implementation imposes these bounds to make it easier to work with the class. `COleDateTime` doesn't support Julian dates. The Gregorian calendar is assumed to extend back in time to January 1, 100. `COleDateTime` ignores Daylight Saving Time (DST). The following code example compares two methods of calculating a time span that crosses the DST switchover date: one using the CRT, and the other using `COleDateTime`. -The first method sets two `CTime` objects, *time1* and *time2*, to April 5 and April 6 respectively, using the standard C type structures `tm` and `time_t`. The code displays *time1* and *time2* and the time span between them. +The first method sets two `CTime` objects, *`time1`* and *`time2`*, to April 5 and April 6 respectively, using the standard C type structures `tm` and `time_t`. The code displays *`time1`* and *`time2`* and the time span between them. -The second method creates two `COleDateTime` objects, `oletime1` and `oletime2`, and sets them to the same dates as *time1* and *time2*. It displays `oletime1` and `oletime2` and the time span between them. +The second method creates two `COleDateTime` objects, `oletime1` and `oletime2`, and sets them to the same dates as *`time1`* and *`time2`*. It displays `oletime1` and `oletime2` and the time span between them. The CRT correctly calculates a difference of 23 hours. `COleDateTimeSpan` calculates a difference of 24 hours. @@ -69,21 +68,21 @@ This procedure shows how to calculate the difference between two `COleDateTime` #### To format a time -Use the `Format` member function of either [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) or [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) to create a character string representing the time or elapsed time. +Use the `Format` member function of either [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) or [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) to create a character string representing the time or elapsed time. [!code-cpp[NVC_ATLMFC_Utilities#179](../atl-mfc-shared/codesnippet/cpp/formatting-time-automation-classes_1.cpp)] -For more information, see class [COleVariant](../mfc/reference/colevariant-class.md). +For more information, see class [`COleVariant`](../mfc/reference/colevariant-class.md). ## Date and Time: Database Support -Starting in version 4.0, MFC database programming uses the [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) and [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) classes to represent date and time data. These classes, also used in Automation, are derived from class [COleVariant](../mfc/reference/colevariant-class.md). They supply better support for managing date and time data than do [CTime](../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../atl-mfc-shared/reference/ctimespan-class.md). +Starting in version 4.0, MFC database programming uses the [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) and [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) classes to represent date and time data. These classes, also used in Automation, are derived from class [`COleVariant`](../mfc/reference/colevariant-class.md). They supply better support for managing date and time data than do [`CTime`](../atl-mfc-shared/reference/ctime-class.md) and [`CTimeSpan`](../atl-mfc-shared/reference/ctimespan-class.md). -## Date and Time: SYSTEMTIME Support +## Date and Time: `SYSTEMTIME` Support -The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) class has constructors that accept system and file times from Win32. +The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) class has constructors that accept system and file times from Win32. -The Win32 `FILETIME` structure represents time as a 64-bit value. It's a more convenient format for internal storage than a `SYSTEMTIME` structure, and the format used by Win32 to represent the time of file creation. For information about the SYSTEMTIME structure, see [SYSTEMTIME](/windows/desktop/api/minwinbase/ns-minwinbase-systemtime). For information about the FILETIME structure, see [FILETIME](/windows/desktop/api/minwinbase/ns-minwinbase-filetime). +The Win32 `FILETIME` structure represents time as a 64-bit value. It's a more convenient format for internal storage than a `SYSTEMTIME` structure, and the format used by Win32 to represent the time of file creation. For information about the `SYSTEMTIME` structure, see [`SYSTEMTIME`](/windows/desktop/api/minwinbase/ns-minwinbase-systemtime). For information about the `FILETIME` structure, see [`FILETIME`](/windows/desktop/api/minwinbase/ns-minwinbase-filetime). ## See also diff --git a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md index 43fae08362..3e5b794a88 100644 --- a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md +++ b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md @@ -27,7 +27,7 @@ To resolve this problem, do the following: Export `CStringA` and `CStringW` (and the necessary base classes) from MFC90.DLL. Projects that include MFC will always use the MFC DLL exported `CStringA` and `CStringW`, as in previous MFC implementations. -Then create a exportable derived class using the `CStringT` template, as `CStringT_Exported` is below, for example: +Then create an exportable derived class using the `CStringT` template, as `CStringT_Exported` is below, for example: [!code-cpp[NVC_MFC_DLL#7](../atl-mfc-shared/codesnippet/cpp/exporting-string-classes-using-cstringt_2.cpp)] diff --git a/docs/atl-mfc-shared/reference/cfixedstringt-class.md b/docs/atl-mfc-shared/reference/cfixedstringt-class.md index f550ca44b9..c236dcb8d4 100644 --- a/docs/atl-mfc-shared/reference/cfixedstringt-class.md +++ b/docs/atl-mfc-shared/reference/cfixedstringt-class.md @@ -12,7 +12,7 @@ This class represents a string object with a fixed character buffer. ## Syntax -``` +```cpp template class CFixedStringT : private CFixedStringMgr, public StringType ``` @@ -69,7 +69,7 @@ For more information on the customization of `CFixedStringT` and memory manageme Constructs a `CFixedStringT` object. -``` +```cpp CFixedStringT() throw(); explicit CFixedStringT(IAtlStringMgr* pStringMgr) throw(); CFixedStringT(const CFixedStringT& strSrc); @@ -98,7 +98,7 @@ Because the constructors copy the input data into new allocated storage, you sho Reinitializes an existing `CFixedStringT` object with new data. -``` +```cpp CFixedStringT& operator=( const CFixedStringT& strSrc); CFixedStringT& operator=(const char* pszSrc); diff --git a/docs/atl-mfc-shared/reference/cimage-class.md b/docs/atl-mfc-shared/reference/cimage-class.md index bf3f47881b..0dd7899250 100644 --- a/docs/atl-mfc-shared/reference/cimage-class.md +++ b/docs/atl-mfc-shared/reference/cimage-class.md @@ -15,7 +15,7 @@ ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 ## Syntax -``` +```cpp class CImage ``` @@ -148,7 +148,7 @@ You can use `CImage` from either MFC or ATL. Displays bitmaps that have transparent or semitransparent pixels. -``` +```cpp BOOL AlphaBlend( HDC hDestDC, int xDest, @@ -267,7 +267,7 @@ The bitmap can be either a non-DIB section bitmap or a DIB section bitmap. See [ Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL BitBlt( HDC hDestDC, int xDest, @@ -343,7 +343,7 @@ For more information, see [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) Constructs a `CImage` object. -``` +```cpp CImage() throw(); ``` @@ -359,7 +359,7 @@ Using global `CImage` objects in a DLL is not recommended. If you need to use a Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL Create( int nWidth, int nHeight, @@ -394,7 +394,7 @@ Nonzero if successful; otherwise 0. Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL CreateEx( int nWidth, int nHeight, @@ -458,7 +458,7 @@ void Destroy() throw(); Detaches a bitmap from a `CImage` object. -``` +```cpp HBITMAP Detach() throw(); ``` @@ -470,7 +470,7 @@ A handle to the bitmap detached, or `NULL` if no bitmap is attached. Copies a bitmap from the source device context to the current device context. -``` +```cpp BOOL Draw( HDC hDestDC, int xDest, @@ -579,7 +579,7 @@ Using this pointer, along with the value returned by [`GetPitch`](#getpitch), yo Retrieves the bits-per-pixel value. -``` +```cpp int GetBPP() const throw(); ``` @@ -619,7 +619,7 @@ A pointer to the array of [`RGBQUAD`](/windows/win32/api/wingdi/ns-wingdi-rgbqua Retrieves the device context that currently has the image selected into it. -``` +```cpp HDC GetDC() const throw(); ``` @@ -635,7 +635,7 @@ For each call to `GetDC`, you must have a subsequent call to [`ReleaseDC`](#rele Finds image formats available for saving images. -``` +```cpp static HRESULT GetExporterFilterString( CSimpleString& strExporters, CSimpleArray& aguidFileTypes, @@ -691,7 +691,7 @@ Set of bit flags specifying which file types to exclude from the list. Allowable - `excludeDefaultLoad` = 0 For load, all file types are included by default -- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. +- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. *`chSeparator`*
The separator used between the image formats. See **Remarks** for more information. @@ -706,19 +706,19 @@ You can pass the resulting format string to your MFC [`CFileDialog`](../../mfc/r The parameter *`strExporter`* has the format: -file description0|\*.ext0|filedescription1|\*.ext1|...file description *n*|\*.ext *n*|| +`file description 0|*.ext0|file description 1|*.ext1|...file description N|*.extN||` -where '|' is the separator character specified by `chSeparator`. For example: +where `|` is the separator character specified by `chSeparator`. For example: `"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"` -Use the default separator '|' if you pass this string to an MFC `CFileDialog` object. Use the null separator '\0' if you pass this string to a common File Save dialog box. +Use the default separator `|` if you pass this string to an MFC `CFileDialog` object. Use the null separator `'\0'` if you pass this string to a common File Save dialog box. ## `CImage::GetHeight` Retrieves the height, in pixels, of an image. -``` +```cpp int GetHeight() const throw(); ``` @@ -730,7 +730,7 @@ The height, in pixels, of an image. Finds image formats available for loading images. -``` +```cpp static HRESULT GetImporterFilterString( CSimpleString& strImporters, CSimpleArray& aguidFileTypes, @@ -786,7 +786,7 @@ Set of bit flags specifying which file types to exclude from the list. Allowable - `excludeDefaultLoad` = 0 For load, all file types are included by default -- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. +- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. *`chSeparator`*
The separator used between the image formats. See **Remarks** for more information. @@ -797,19 +797,19 @@ You can pass the resulting format string to your MFC [`CFileDialog`](../../mfc/r The parameter *`strImporter`* has the format: -file description0|\*.ext0|filedescription1|\*.ext1|...file description *n*|\*.ext *n*|| +`file description 0|*.ext0|file description 1|*.ext1|...file description N|*.extN|| -where '|' is the separator character specified by *`chSeparator`*. For example: +where `|` is the separator character specified by *`chSeparator`*. For example: `"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"` -Use the default separator '|' if you pass this string to an MFC `CFileDialog` object. Use the null separator '\0' if you pass this string to a common **File Open** dialog box. +Use the default separator `|` if you pass this string to an MFC `CFileDialog` object. Use the null separator `'\0'` if you pass this string to a common **File Open** dialog box. ## `CImage::GetMaxColorTableEntries` Retrieves the maximum number of entries in the color table. -``` +```cpp int GetMaxColorTableEntries() const throw(); ``` @@ -825,7 +825,7 @@ This method supports only DIB section bitmaps. Retrieves the pitch of an image. -``` +```cpp int GetPitch() const throw(); ``` @@ -846,7 +846,7 @@ Use `GetPitch` with [`GetBits`](#getbits) to find individual pixels of an image. Retrieves the color of the pixel at the location specified by *x* and *y*. -``` +```cpp COLORREF GetPixel(int x, int y) const throw(); ``` @@ -891,7 +891,7 @@ For formats that have less than 8 bits per pixel, this method returns the addres Retrieves the indexed location of the transparent color in the color palette. -``` +```cpp LONG GetTransparentColor() const throw(); ``` @@ -903,7 +903,7 @@ The index of the transparent color. Retrieves the width, in pixels, of an image. -``` +```cpp int GetWidth() const throw(); ``` @@ -915,7 +915,7 @@ The width of the bitmap, in pixels. Determines if the attached bitmap is a DIB section. -``` +```cpp bool IsDIBSection() const throw(); ``` @@ -945,7 +945,7 @@ If the bitmap is not a DIB section, you cannot use the following `CImage` method Determines whether a bitmap's pixels are mapped to a color palette. -``` +```cpp bool IsIndexed() const throw(); ``` @@ -964,7 +964,7 @@ This method returns `TRUE` only if the bitmap is 8-bit (256 colors) or less. Determines if a bitmap is currently loaded. -``` +```cpp bool IsNull() const throw(); ``` @@ -976,7 +976,7 @@ This method returns `TRUE` if a bitmap is not currently loaded; otherwise `FALSE Indicates whether the application supports transparent bitmaps. -``` +```cpp static BOOL IsTransparencySupported() throw(); ``` @@ -992,7 +992,7 @@ If the return value is nonzero, and transparency is supported, a call to [`Alpha Loads an image. -``` +```cpp HRESULT Load(LPCTSTR pszFileName) throw(); HRESULT Load(IStream* pStream) throw(); ``` @@ -1048,7 +1048,7 @@ The resource must be of type `BITMAP`. Combines the color data for the source and destination bitmaps using the specified mask and raster operation. -``` +```cpp BOOL MaskBlt( HDC hDestDC, int xDest, @@ -1147,7 +1147,7 @@ Use this operator to get the attached Windows GDI handle of the `CImage` object. Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context. -``` +```cpp BOOL PlgBlt( HDC hDestDC, const POINT* pPoints, @@ -1245,7 +1245,7 @@ This method must be called to free resources allocated by a global `CImage` obje Saves an image to the specified stream or file on disk. -``` +```cpp HRESULT Save( IStream* pStream, REFGUID guidFileType) const throw(); @@ -1391,7 +1391,7 @@ The red, green, and blue parameters are each represented by a number between 0 a Sets a color at a given indexed location as transparent. -``` +```cpp LONG SetTransparentColor(LONG iTransparentColor) throw(); ``` @@ -1408,7 +1408,7 @@ The index of the color previously set as transparent. Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL StretchBlt( HDC hDestDC, int xDest, @@ -1491,7 +1491,7 @@ For more information, see [`StretchBlt`](/windows/win32/api/wingdi/nf-wingdi-str Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL TransparentBlt( HDC hDestDC, int xDest, diff --git a/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md b/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md index dd93cb77f4..bbcb2af079 100644 --- a/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md +++ b/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md @@ -21,7 +21,7 @@ The following table lists the classes shared between MFC and ATL. |[CRect](../../atl-mfc-shared/reference/crect-class.md)|A class similar to a Windows [RECT](/windows/win32/api/windef/ns-windef-rect) structure that also includes member functions to manipulate `CRect` objects and Windows `RECT` structures.|atltypes.h| |[CSimpleStringT](../../atl-mfc-shared/reference/csimplestringt-class.md)|Represents a `CSimpleStringT` object.|atlsimpstr.h| |[CSize](../../atl-mfc-shared/reference/csize-class.md)|A class similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structure, which implements a relative coordinate or position.|atltypes.h| -|[CStrBufT](../../atl-mfc-shared/reference/cstrbuft-class.md)|Provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffer` calls on a existing `CStringT` object.|atlsimpstr.h| +|[CStrBufT](../../atl-mfc-shared/reference/cstrbuft-class.md)|Provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffer` calls on an existing `CStringT` object.|atlsimpstr.h| |[CStringData](../../atl-mfc-shared/reference/cstringdata-class.md)|Represents the data of a string object.|atlsimpstr.h| |[CStringT](../../atl-mfc-shared/reference/cstringt-class.md)|Represents a `CStringT` object.|cstringt.h (MFC dependent) atlstr.h (MFC independent)| |[CTime](../../atl-mfc-shared/reference/ctime-class.md)|Represents an absolute time and date.|atltime.h| diff --git a/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp b/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp index 69b8fc155d..9c7f028ed7 100644 --- a/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp +++ b/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp @@ -1,7 +1,7 @@ void CMyClass::OnFileOpen() { // szFilters is a text string that includes two file name filters: - // "*.my" for "MyType Files" and "*.*' for "All Files." + // "*.my" for "MyType Files" and "*.*" for "All Files." TCHAR szFilters[]= _T("MyType Files (*.my)|*.my|All Files (*.*)|*.*||"); // Create an Open dialog; the default file name extension is ".my". diff --git a/docs/atl-mfc-shared/reference/coledatetime-class.md b/docs/atl-mfc-shared/reference/coledatetime-class.md index 0747ec07ed..5da193d9b9 100644 --- a/docs/atl-mfc-shared/reference/coledatetime-class.md +++ b/docs/atl-mfc-shared/reference/coledatetime-class.md @@ -1,10 +1,9 @@ --- title: "COleDateTime Class" description: "API reference for the MFC COleDateTime class which Encapsulates the `DATE` data type used in OLE automation." -ms.date: "08/27/2020" +ms.date: 08/27/2020 f1_keywords: ["COleDateTime", "ATLCOMTIME/ATL::COleDateTime", "ATLCOMTIME/ATL::COleDateTime::COleDateTime", "ATLCOMTIME/ATL::COleDateTime::Format", "ATLCOMTIME/ATL::COleDateTime::GetAsDBTIMESTAMP", "ATLCOMTIME/ATL::COleDateTime::GetAsSystemTime", "ATLCOMTIME/ATL::COleDateTime::GetAsUDATE", "ATLCOMTIME/ATL::COleDateTime::GetCurrentTime", "ATLCOMTIME/ATL::COleDateTime::GetDay", "ATLCOMTIME/ATL::COleDateTime::GetDayOfWeek", "ATLCOMTIME/ATL::COleDateTime::GetDayOfYear", "ATLCOMTIME/ATL::COleDateTime::GetHour", "ATLCOMTIME/ATL::COleDateTime::GetMinute", "ATLCOMTIME/ATL::COleDateTime::GetMonth", "ATLCOMTIME/ATL::COleDateTime::GetSecond", "ATLCOMTIME/ATL::COleDateTime::GetStatus", "ATLCOMTIME/ATL::COleDateTime::GetYear", "ATLCOMTIME/ATL::COleDateTime::ParseDateTime", "ATLCOMTIME/ATL::COleDateTime::SetDate", "ATLCOMTIME/ATL::COleDateTime::SetDateTime", "ATLCOMTIME/ATL::COleDateTime::SetStatus", "ATLCOMTIME/ATL::COleDateTime::SetTime", "ATLCOMTIME/ATL::COleDateTime::m_dt", "ATLCOMTIME/ATL::COleDateTime::m_status"] helpviewer_keywords: ["shared classes, COleDateTime", "time-only values", "Date data type, MFC encapsulation of", "COleDateTime class", "dates, handling in MFC", "time, handling in MFC"] -ms.assetid: e718f294-16ec-4649-88b6-a4dbae5178fb --- # COleDateTime Class @@ -12,7 +11,7 @@ Encapsulates the `DATE` data type that is used in OLE automation. ## Syntax -``` +```cpp class COleDateTime ``` @@ -109,7 +108,7 @@ For more information about the `COleDateTime` and `COleDateTimeSpan` classes, se Comparison operators. -``` +```cpp bool operator==(const COleDateTime& date) const throw(); bool operator!=(const COleDateTime& date) const throw(); bool operator<(const COleDateTime& date) const throw(); @@ -140,7 +139,7 @@ The operators **>=**, **\<=**, **>**, and **<**, will assert if the `COleDateTim Constructs a `COleDateTime` object. -``` +```cpp COleDateTime() throw(); COleDateTime(const VARIANT& varSrc) throw(); COleDateTime(DATE dtSrc) throw(); @@ -211,7 +210,7 @@ Following is a brief description of each constructor: - `COleDateTime(` `dateSrc` **)** Constructs a `COleDateTime` object from an existing `COleDateTime` object. -- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time ( `VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. +- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time (`VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. - `COleDateTime(` `dtSrc` **)** Constructs a `COleDateTime` object from a `DATE` value. @@ -242,7 +241,7 @@ For more information about the bounds for `COleDateTime` values, see the article Creates a formatted representation of the date/time value. -``` +```cpp CString Format(DWORD dwFlags = 0, LCID lcid = LANG_USER_DEFAULT) const; CString Format(LPCTSTR lpszFormat) const; CString Format(UINT nFormatID) const; @@ -263,7 +262,7 @@ Indicates one of the following locale flags: Indicates locale ID to use for the conversion. For more information about language identifiers, see [Language Identifiers](/windows/win32/Intl/language-identifiers). *lpszFormat*
-A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent ( `%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: +A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent (`%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: - `%H` Hours in the current day @@ -303,7 +302,7 @@ This form formats the value by using the format string which contains special fo Call this method to obtain the time in the `COleDateTime` object as a `DBTIMESTAMP` data structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& timeStamp) const throw(); ``` @@ -328,7 +327,7 @@ Stores the resulting time in the referenced *timeStamp* structure. The `DBTIMEST Call this method to obtain the time in the `COleDateTime` object as a `SYSTEMTIME` data structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& sysTime) const throw(); ``` @@ -351,7 +350,7 @@ For more information on the status information held in a `COleDateTime` object, Call this method to obtain the time in the `COleDateTime` object as a `UDATE` data structure. -``` +```cpp bool GetAsUDATE(UDATE& uDate) const throw(); ``` @@ -372,7 +371,7 @@ A `UDATE` structure represents an "unpacked" date. Call this static member function to return the current date/time value. -``` +```cpp static COleDateTime WINAPI GetCurrentTime() throw(); ``` @@ -384,7 +383,7 @@ static COleDateTime WINAPI GetCurrentTime() throw(); Gets the day of the month represented by this date/time value. -``` +```cpp int GetDay() const throw(); ``` @@ -420,7 +419,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the week represented by this date/time value. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -456,7 +455,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the year represented by this date/time value. -``` +```cpp int GetDayOfYear() const throw(); ``` @@ -492,7 +491,7 @@ For information on other member functions that query the value of this `COleDate Gets the hour represented by this date/time value. -``` +```cpp int GetHour() const throw(); ``` @@ -528,7 +527,7 @@ For information on other member functions that query the value of this `COleDate Gets the minute represented by this date/time value. -``` +```cpp int GetMinute() const throw(); ``` @@ -564,7 +563,7 @@ See the example for [GetHour](#gethour). Gets the month represented by this date/time value. -``` +```cpp int GetMonth() const throw(); ``` @@ -600,7 +599,7 @@ See the example for [GetDay](#getday). Gets the second represented by this date/time value. -``` +```cpp int GetSecond() const throw(); ``` @@ -641,7 +640,7 @@ See the example for [GetHour](#gethour). Gets the status (validity) of a given `COleDateTime` object. -``` +```cpp DateTimeStatus GetStatus() const throw(); ``` @@ -653,7 +652,7 @@ Returns the status of this `COleDateTime` value. If you call `GetStatus` on a `C The return value is defined by the `DateTimeStatus` enumerated type, which is defined within the `COleDateTime` class. -``` +```cpp enum DateTimeStatus { error = -1, @@ -707,7 +706,7 @@ For more information about the bounds for `COleDateTime` values, see the article Gets the year represented by this date/time value. -``` +```cpp int GetYear() const throw(); ``` @@ -745,7 +744,7 @@ See the example for [GetDay](#getday). The underlying `DATE` structure for this `COleDateTime` object. -``` +```cpp DATE m_dt; ``` @@ -760,7 +759,7 @@ For more information about the implementation of the `DATE` object, see the arti Contains the status of this `COleDateTime` object. -``` +```cpp DateTimeStatus m_status; ``` @@ -775,7 +774,7 @@ The type of this data member is the enumerated type `DateTimeStatus`, which is d Copies a `COleDateTime` value. -``` +```cpp COleDateTime& operator=(const VARIANT& varSrc) throw(); COleDateTime& operator=(DATE dtSrc) throw(); COleDateTime& operator=(const time_t& timeSrc) throw(); @@ -815,7 +814,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract `ColeDateTime` values. -``` +```cpp COleDateTime operator+(COleDateTimeSpan dateSpan) const throw(); COleDateTime operator-(COleDateTimeSpan dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTime& date) const throw(); @@ -845,7 +844,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract a `ColeDateTime` value from this `COleDateTime` object. -``` +```cpp COleDateTime& operator+=(COleDateTimeSpan dateSpan) throw(); COleDateTime& operator-=(COleDateTimeSpan dateSpan) throw(); ``` @@ -868,7 +867,7 @@ For more information about the bounds for `COleDateTime` values, see the article Converts a `ColeDateTime` value into a `DATE`. -``` +```cpp operator DATE() const throw(); ``` @@ -882,7 +881,7 @@ The `DATE` operator will assert if the `COleDateTime` object is set to null. See Parses a string to read a date/time value. -``` +```cpp bool ParseDateTime( LPCTSTR lpszDate, DWORD dwFlags = 0, @@ -943,7 +942,7 @@ For more information about the bounds and implementation for `COleDateTime` valu Sets the date of this `COleDateTime` object. -``` +```cpp int SetDate( int nYear, int nMonth, @@ -1020,7 +1019,7 @@ For more information about the bounds for `COleDateTime` values, see the article Sets the date and time of this `COleDateTime` object. -``` +```cpp int SetDateTime( int nYear, int nMonth, @@ -1128,7 +1127,7 @@ See the example for [GetStatus](#getstatus). Sets the time of this `COleDateTime` object. -``` +```cpp int SetTime( int nHour, int nMin, diff --git a/docs/atl-mfc-shared/reference/coledatetimespan-class.md b/docs/atl-mfc-shared/reference/coledatetimespan-class.md index 41f2f693c9..491074bbae 100644 --- a/docs/atl-mfc-shared/reference/coledatetimespan-class.md +++ b/docs/atl-mfc-shared/reference/coledatetimespan-class.md @@ -12,7 +12,7 @@ Represents a relative time, a time span. ## Syntax -``` +```cpp class COleDateTimeSpan ``` @@ -76,7 +76,7 @@ For more information on the `COleDateTime` and `COleDateTimeSpan` classes, see t Comparison operators. -``` +```cpp bool operator==(const COleDateTimeSpan& dateSpan) const throw(); bool operator!=(const COleDateTimeSpan& dateSpan) const throw(); bool operator<(const COleDateTimeSpan& dateSpan) const throw(); @@ -102,14 +102,14 @@ These operators compare two date/time-span values and return TRUE if the conditi ### Example [!code-cpp[NVC_ATLMFC_Utilities#25](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#26](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_2.cpp)] ## COleDateTimeSpan::COleDateTimeSpan Constructs a `COleDateTimeSpan` object. -``` +```cpp COleDateTimeSpan() throw(); COleDateTimeSpan(double dblSpanSrc) throw(); COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw(); @@ -145,7 +145,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Generates a formatted string representation of a `COleDateTimeSpan` object. -``` +```cpp CString Format(LPCTSTR pFormat) const; CString Format(UINT nID) const; ``` @@ -194,7 +194,7 @@ This form formats the value using the format string that contains special format Retrieves the day portion of this date/time-span value. -``` +```cpp LONG GetDays() const throw(); ``` @@ -230,7 +230,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the hour portion of this date/time-span value. -``` +```cpp LONG GetHours() const throw(); ``` @@ -266,7 +266,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the minute portion of this date/time-span value. -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -302,7 +302,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the second portion of this date/time-span value. -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -338,7 +338,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Gets the status (validity) of this `COleDateTimeSpan` object. -``` +```cpp DateTimeSpanStatus GetStatus() const throw(); ``` @@ -350,7 +350,7 @@ The status of this `COleDateTimeSpan` value. The return value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -382,7 +382,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Retrieves this date/time-span value expressed in days. -``` +```cpp double GetTotalDays() const throw(); ``` @@ -418,7 +418,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves this date/time-span value expressed in hours. -``` +```cpp double GetTotalHours() const throw(); ``` @@ -454,7 +454,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in minutes. -``` +```cpp double GetTotalMinutes() const throw(); ``` @@ -490,7 +490,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in seconds. -``` +```cpp double GetTotalSeconds() const throw(); ``` @@ -526,7 +526,7 @@ See the example for [GetTotalDays](#gettotaldays). The underlying **`double`** value for this `COleDateTime` object. -``` +```cpp double m_span; ``` @@ -541,13 +541,13 @@ This value expresses the date/time-span in days. The type for this data member is the enumerated type `DateTimeSpanStatus`, which is defined within the `COleDateTimeSpan` class. -``` +```cpp DateTimeSpanStatus m_status; ``` ### Remarks -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -582,7 +582,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Copies a `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator=(double dblSpanSrc) throw(); ``` @@ -594,7 +594,7 @@ This overloaded assignment operator copies the source date/time-span value into Add, subtract, and change sign for `COleDateTimeSpan` values. -``` +```cpp COleDateTimeSpan operator+(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-() const throw(); @@ -618,7 +618,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Add and subtract a `COleDateTimeSpan` value from this `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator+=(const COleDateTimeSpan dateSpan) throw(); COleDateTimeSpan& operator-=(const COleDateTimeSpan dateSpan) throw(); ``` @@ -639,7 +639,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Converts this `COleDateTimeSpan` value to a **`double`**. -``` +```cpp operator double() const throw(); ``` @@ -701,7 +701,7 @@ The new status value for this `COleDateTimeSpan` object. The *Status* parameter value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, diff --git a/docs/atl-mfc-shared/reference/cpoint-class.md b/docs/atl-mfc-shared/reference/cpoint-class.md index 94f05597be..1636a18f6d 100644 --- a/docs/atl-mfc-shared/reference/cpoint-class.md +++ b/docs/atl-mfc-shared/reference/cpoint-class.md @@ -4,15 +4,14 @@ title: "CPoint Class" ms.date: "11/04/2016" f1_keywords: ["CPoint", "ATLTYPES/ATL::CPoint", "ATLTYPES/ATL::CPoint::CPoint", "ATLTYPES/ATL::CPoint::Offset"] helpviewer_keywords: ["LPPOINT structure", "POINT structure", "CPoint class"] -ms.assetid: a6d4db93-35cc-444d-9221-c3e160f6edaa --- -# CPoint Class +# `CPoint` Class Similar to the Windows `POINT` structure. ## Syntax -``` +```cpp class CPoint : public tagPOINT ``` @@ -22,30 +21,30 @@ class CPoint : public tagPOINT |Name|Description| |----------|-----------------| -|[CPoint::CPoint](#cpoint)|Constructs a `CPoint`.| +|[`CPoint::CPoint`](#cpoint)|Constructs a `CPoint`.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPoint::Offset](#offset)|Adds values to the `x` and `y` members of the `CPoint`.| +|[`CPoint::Offset`](#offset)|Adds values to the `x` and `y` members of the `CPoint`.| ### Public Operators |Name|Description| |----------|-----------------| -|[CPoint::operator -](#operator_-)|Returns the difference of a `CPoint` and a size, or the negation of a point, or the size difference between two points, or the offset by a negative size.| -|[CPoint::operator !=](#operator_neq)|Checks for inequality between two points.| -|[CPoint::operator +](#operator_add)|Returns the sum of a `CPoint` and a size or point, or a `CRect` offset by a size.| -|[CPoint::operator +=](#operator_add_eq)|Offsets `CPoint` by adding a size or point.| -|[CPoint::operator -=](#operator_-_eq)|Offsets `CPoint` by subtracting a size or point.| -|[CPoint::operator ==](#operator_eq_eq)|Checks for equality between two points.| +|[`CPoint::operator -`](#operator_-)|Returns the difference of a `CPoint` and a `SIZE`, or the negation of a `POINT`, or the `CSize` difference between two `POINT`s, or the offset by a negative `SIZE`.| +|[`CPoint::operator !=`](#operator_neq)|Checks for inequality between two `POINT`s.| +|[`CPoint::operator +`](#operator_add)|Returns the sum of a `CPoint` and a `SIZE` or `POINT`, or a `CRect` offset by a `SIZE`.| +|[`CPoint::operator +=`](#operator_add_eq)|Offsets `CPoint` by adding a `SIZE` or `POINT`.| +|[`CPoint::operator -=`](#operator_-_eq)|Offsets `CPoint` by subtracting a `SIZE` or `POINT`.| +|[`CPoint::operator ==`](#operator_eq_eq)|Checks for equality between two `POINT`s.| ## Remarks -It also includes member functions to manipulate `CPoint` and [POINT](/windows/win32/api/windef/ns-windef-point) structures. +It also includes member functions to manipulate `CPoint` and [`POINT`](/windows/win32/api/windef/ns-windef-point) structures. -A `CPoint` object can be used wherever a `POINT` structure is used. The operators of this class that interact with a "size" accept either [CSize](../../atl-mfc-shared/reference/csize-class.md) objects or [SIZE](/windows/win32/api/windef/ns-windef-size) structures, since the two are interchangeable. +A `CPoint` object can be used wherever a `POINT` structure is used. The operators of this class that interact with a `SIZE` accept either [`CSize`](../../atl-mfc-shared/reference/csize-class.md) objects or [`SIZE`](/windows/win32/api/windef/ns-windef-size) structures, since the two are interchangeable. > [!NOTE] > This class is derived from the `tagPOINT` structure. (The name `tagPOINT` is a less commonly used name for the `POINT` structure.) This means that the data members of the `POINT` structure, `x` and `y`, are accessible data members of `CPoint`. @@ -61,13 +60,13 @@ A `CPoint` object can be used wherever a `POINT` structure is used. The operator ## Requirements -**Header:** atltypes.h +**Header:** `atltypes.h` -## CPoint::CPoint +## `CPoint::CPoint` Constructs a `CPoint` object. -``` +```cpp CPoint() throw(); CPoint(int initX, int initY) throw(); CPoint(POINT initPt) throw(); @@ -77,20 +76,20 @@ CPoint(LPARAM dwPoint) throw(); ### Parameters -*initX*
+*`initX`*\ Specifies the value of the `x` member of `CPoint`. -*initY*
+*`initY`*\ Specifies the value of the `y` member of `CPoint`. -*initPt*
-[POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` that specifies the values used to initialize `CPoint`. +*`initPt`*\ +[`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` that specifies the values used to initialize `CPoint`. -*initSize*
-[SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) that specifies the values used to initialize `CPoint`. +*`initSize`*\ +[`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) that specifies the values used to initialize `CPoint`. -*dwPoint*
-Sets the `x` member to the low-order word of *dwPoint* and the `y` member to the high-order word of *dwPoint*. +*`dwPoint`*\ +Sets the `x` member to the low-order word of *`dwPoint`* and the `y` member to the high-order word of *`dwPoint`*. ### Remarks @@ -123,7 +122,7 @@ CPoint ptFromDouble(dwSize); ASSERT(ptFromDouble == ptMFCHere); ``` -## CPoint::Offset +## `CPoint::Offset` Adds values to the `x` and `y` members of the `CPoint`. @@ -135,46 +134,46 @@ void Offset(SIZE size) throw(); ### Parameters -*xOffset*
+*`xOffset`*\ Specifies the amount to offset the `x` member of the `CPoint`. -*yOffset*
+*`yOffset`*\ Specifies the amount to offset the `y` member of the `CPoint`. -*point*
-Specifies the amount ( [POINT](/windows/win32/api/windef/ns-windef-point) or `CPoint`) to offset the `CPoint`. +*`point`*\ +Specifies the amount ([`POINT`](/windows/win32/api/windef/ns-windef-point) or `CPoint`) to offset the `CPoint`. -*size*
-Specifies the amount ( [SIZE](/windows/win32/api/windef/ns-windef-size) or [CSize](../../atl-mfc-shared/reference/csize-class.md)) to offset the `CPoint`. +*`size`*\ +Specifies the amount ([`SIZE`](/windows/win32/api/windef/ns-windef-size) or [`CSize`](../../atl-mfc-shared/reference/csize-class.md)) to offset the `CPoint`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#28](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_1.cpp)] -## CPoint::operator == +## `CPoint::operator ==` -Checks for equality between two points. +Checks for equality between two `POINT`s. -``` +```cpp BOOL operator==(POINT point) const throw(); ``` ### Parameters -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. ### Return Value -Nonzero if the points are equal; otherwise 0. +Nonzero if the `POINT`s are equal; otherwise 0. ### Example [!code-cpp[NVC_ATLMFC_Utilities#29](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_2.cpp)] -## CPoint::operator != +## `CPoint::operator !=` -Checks for inequality between two points. +Checks for inequality between two `POINT`s. ``` BOOL operator!=(POINT point) const throw(); @@ -182,20 +181,20 @@ BOOL operator!=(POINT point) const throw(); ### Parameters -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. ### Return Value -Nonzero if the points are not equal; otherwise 0. +Nonzero if the `POINT`s aren't equal; otherwise 0. ### Example [!code-cpp[NVC_ATLMFC_Utilities#30](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_3.cpp)] -## CPoint::operator += +## `CPoint::operator +=` -The first overload adds a size to the `CPoint`. +The first overload adds a `SIZE` to the `CPoint`. ```cpp void operator+=(SIZE size) throw(); @@ -204,27 +203,27 @@ void operator+=(POINT point) throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. ### Remarks -The second overload adds a point to the `CPoint`. +The second overload adds a `POINT` to the `CPoint`. In both cases, addition is done by adding the `x` (or `cx`) member of the right-hand operand to the `x` member of the `CPoint` and adding the `y` (or `cy`) member of the right-hand operand to the `y` member of the `CPoint`. -For example, adding `CPoint(5, -7)` to a variable which contains `CPoint(30, 40)` changes the variable to `CPoint(35, 33)`. +For example, adding `CPoint(5, -7)` to a variable that contains `CPoint(30, 40)` changes the variable to `CPoint(35, 33)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#31](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_4.cpp)] -## CPoint::operator -= +## `CPoint::operator -=` -The first overload subtracts a size from the `CPoint`. +The first overload subtracts a `SIZE` from the `CPoint`. ```cpp void operator-=(SIZE size) throw(); @@ -233,29 +232,29 @@ void operator-=(POINT point) throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. ### Remarks -The second overload subtracts a point from the `CPoint`. +The second overload subtracts a `POINT` from the `CPoint`. In both cases, subtraction is done by subtracting the `x` (or `cx`) member of the right-hand operand from the `x` member of the `CPoint` and subtracting the `y` (or `cy`) member of the right-hand operand from the `y` member of the `CPoint`. -For example, subtracting `CPoint(5, -7)` from a variable which contains `CPoint(30, 40)` changes the variable to `CPoint(25, 47)`. +For example, subtracting `CPoint(5, -7)` from a variable that contains `CPoint(30, 40)` changes the variable to `CPoint(25, 47)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#32](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_5.cpp)] -## CPoint::operator + +## `CPoint::operator +` Use this operator to offset `CPoint` by a `CPoint` or `CSize` object, or to offset a `CRect` by a `CPoint`. -``` +```cpp CPoint operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -263,34 +262,34 @@ CRect operator+(const RECT* lpRect) const throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. -*lpRect*
-Contains a pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or [CRect](../../atl-mfc-shared/reference/crect-class.md) object. +*`lpRect`*\ +Contains a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. ### Return Value -A `CPoint` that is offset by a size, a `CPoint` that is offset by a point, or a `CRect` offset by a point. +A `CPoint` that is offset by a `SIZE`, a `CPoint` that is offset by a `POINT`, or a `CRect` offset by a `POINT`. ### Remarks For example, using one of the first two overloads to offset the point `CPoint(25, -19)` by a point `CPoint(15, 5)` or size `CSize(15, 5)` returns the value `CPoint(40, -14)`. -Adding a rectangle to a point returns the rectangle after being offset by the `x` and `y` values specified in the point. For example, using the last overload to offset a rectangle `CRect(125, 219, 325, 419)` by a point `CPoint(25, -19)` returns `CRect(150, 200, 350, 400)`. +Adding a `CRect` to a `POINT` returns the `CRect` after being offset by the `x` and `y` values specified in the `POINT`. For example, using the last overload to offset a rectangle `CRect(125, 219, 325, 419)` by a point `CPoint(25, -19)` returns `CRect(150, 200, 350, 400)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#33](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_6.cpp)] -## CPoint::operator - +## `CPoint::operator -` Use one of the first two overloads to subtract a `CPoint` or `CSize` object from `CPoint`. -``` +```cpp CSize operator-(POINT point) const throw(); CPoint operator-(SIZE size) const throw(); CRect operator-(const RECT* lpRect) const throw(); @@ -299,18 +298,18 @@ CPoint operator-() const throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*lpRect*
-A pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or a [CRect](../../atl-mfc-shared/reference/crect-class.md) object. +*`lpRect`*\ +A pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. ### Return Value -A `CSize` that is the difference between two points, a `CPoint` that is offset by the negation of a size, a `CRect` that is offset by the negation of a point, or a `CPoint` that is the negation of a point. +A `CSize` that is the difference between two `POINT`s, a `CPoint` that is offset by the negation of a `SIZE`, a `CRect` that is offset by the negation of a `POINT`, or a `CPoint` that is the negation of a `POINT`. ### Remarks @@ -320,9 +319,9 @@ For example, using the first overload to find the difference between two points Subtracting a `CSize` from `CPoint` does the same calculation as above but returns a `CPoint` object, not a `CSize` object. For example, using the second overload to find the difference between the point `CPoint(25, -19)` and the size `CSize(15, 5)` returns `CPoint(10, -24)`. -Subtracting a rectangle from a point returns the rectangle offset by the negatives of the `x` and `y` values specified in the point. For example, using the last overload to offset the rectangle `CRect(125, 200, 325, 400)` by the point `CPoint(25, -19)` returns `CRect(100, 219, 300, 419)`. +Subtracting a rectangle from a `POINT` returns the rectangle offset by the negatives of the `x` and `y` values specified in the `POINT`. For example, using the last overload to offset the rectangle `CRect(125, 200, 325, 400)` by the point `CPoint(25, -19)` returns `CRect(100, 219, 300, 419)`. -Use the unary operator to negate a point. For example, using the unary operator with the point `CPoint(25, -19)` returns `CPoint(-25, 19)`. +Use the unary operator to negate a `POINT`. For example, using the unary operator with the point `CPoint(25, -19)` returns `CPoint(-25, 19)`. ### Example @@ -330,8 +329,8 @@ Use the unary operator to negate a point. For example, using the unary operator ## See also -[MFC Sample MDI](../../overview/visual-cpp-samples.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[POINT Structure](/windows/win32/api/windef/ns-windef-point)
-[CRect Class](../../atl-mfc-shared/reference/crect-class.md)
-[CSize Class](../../atl-mfc-shared/reference/csize-class.md) +[MFC Sample MDI](../../overview/visual-cpp-samples.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`POINT` Structure](/windows/win32/api/windef/ns-windef-point)\ +[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)\ +[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md) diff --git a/docs/atl-mfc-shared/reference/crect-class.md b/docs/atl-mfc-shared/reference/crect-class.md index 6cadba4e4a..d05e09be56 100644 --- a/docs/atl-mfc-shared/reference/crect-class.md +++ b/docs/atl-mfc-shared/reference/crect-class.md @@ -12,7 +12,7 @@ Similar to a Windows [`RECT`](/windows/win32/api/windef/ns-windef-rect) structur ## Syntax -``` +```cpp class CRect : public tagRECT ``` @@ -428,7 +428,7 @@ ASSERT(rect1.EqualRect(&test)); Calculates the height of `CRect` by subtracting the top value from the bottom value. -``` +```cpp int Height() const throw(); ``` @@ -510,7 +510,7 @@ ASSERT(rect == CRect(-50, -200, 350, 500)); Makes a `CRect` equal to the intersection of two existing rectangles. -``` +```cpp BOOL IntersectRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` @@ -553,7 +553,7 @@ ASSERT(rectInter2 == CRect(125, 75, 150, 95)); Determines whether `CRect` is empty. -``` +```cpp BOOL IsRectEmpty() const throw(); ``` @@ -583,7 +583,7 @@ ASSERT(rectEmpty.IsRectEmpty()); Determines whether the top, left, bottom, and right values of `CRect` are all equal to 0. -``` +```cpp BOOL IsRectNull() const throw(); ``` @@ -747,7 +747,7 @@ ASSERT(rect == CRect(230, 230, 265, 265)); ## `CRect::operator LPCRECT` Converts a `CRect` to an [`LPCRECT`](../../mfc/reference/data-types-mfc.md). -``` +```cpp operator LPCRECT() const throw(); ``` @@ -759,7 +759,7 @@ When you use this function, you don't need the address-of (**`&`**) operator. Th Converts a `CRect` to an [`LPRECT`](../../mfc/reference/data-types-mfc.md). -``` +```cpp operator LPRECT() throw(); ``` @@ -798,7 +798,7 @@ ASSERT(rect2 == CRect(0, 0, 127, 168)); Determines whether `rect` is equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator==(const RECT& rect) const throw(); ``` @@ -838,7 +838,7 @@ ASSERT(rect1 == test); Determines whether *`rect`* is not equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator!=(const RECT& rect) const throw(); ``` @@ -1009,7 +1009,7 @@ ASSERT(rectResult == rect1); The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator+(POINT point) const throw(); CRect operator+(LPCRECT lpRect) const throw(); CRect operator+(SIZE size) const throw(); @@ -1052,7 +1052,7 @@ ASSERT(rectResult == rect2); The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator-(POINT point) const throw(); CRect operator-(SIZE size) const throw(); CRect operator-(LPCRECT lpRect) const throw(); @@ -1095,7 +1095,7 @@ ASSERT(rect2 == rectResult); Returns a `CRect` that is the intersection of `CRect` and *rect2*. -``` +```cpp CRect operator&(const RECT& rect2) const throw(); ``` @@ -1131,7 +1131,7 @@ ASSERT(rectResult == rect3); Returns a `CRect` that is the union of `CRect` and *`rect2`*. -``` +```cpp CRect operator|(const RECT& rect2) const throw(); ``` @@ -1168,7 +1168,7 @@ ASSERT(rectResult == rect3); Determines whether the specified point lies within `CRect`. -``` +```cpp BOOL PtInRect(POINT point) const throw(); ``` @@ -1295,7 +1295,7 @@ ASSERT(sz.cx == 40 && sz.cy == 40); Makes the dimensions of the `CRect` equal to the subtraction of `lpRectSrc2` from `lpRectSrc1`. -``` +```cpp BOOL SubtractRect(LPCRECT lpRectSrc1, LPCRECT lpRectSrc2) throw(); ``` @@ -1362,7 +1362,7 @@ ASSERT(rectResult == rectOut); The coordinates are returned as a reference to a [`CPoint`](cpoint-class.md) object that is contained in `CRect`. -``` +```cpp CPoint& TopLeft() throw(); const CPoint& TopLeft() const throw(); ``` @@ -1383,7 +1383,7 @@ See the example for [`CRect::CenterPoint`](#centerpoint). Makes the dimensions of `CRect` equal to the union of the two source rectangles. -``` +```cpp BOOL UnionRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` @@ -1424,7 +1424,7 @@ ASSERT(rectResult == rect3); Calculates the width of `CRect` by subtracting the left value from the right value. -``` +```cpp int Width() const throw(); ``` diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index 98a3d82946..b62a850efa 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: CSimpleStringT Class" title: "CSimpleStringT Class" -ms.date: 10/04/2021 +description: "Learn more about: CSimpleStringT class" +ms.date: 01/26/2024 f1_keywords: ["CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::PCXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::PXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::Append", "ATLSIMPSTR/ATL::CSimpleStringT::AppendChar", "ATLSIMPSTR/ATL::CSimpleStringT::CopyChars", "ATLSIMPSTR/ATL::CSimpleStringT::CopyCharsOverlapped", "ATLSIMPSTR/ATL::CSimpleStringT::Empty", "ATLSIMPSTR/ATL::CSimpleStringT::FreeExtra", "ATLSIMPSTR/ATL::CSimpleStringT::GetAllocLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetAt", "ATLSIMPSTR/ATL::CSimpleStringT::GetBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::GetBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetManager", "ATLSIMPSTR/ATL::CSimpleStringT::GetString", "ATLSIMPSTR/ATL::CSimpleStringT::IsEmpty", "ATLSIMPSTR/ATL::CSimpleStringT::LockBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::Preallocate", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::SetAt", "ATLSIMPSTR/ATL::CSimpleStringT::SetManager", "ATLSIMPSTR/ATL::CSimpleStringT::SetString", "ATLSIMPSTR/ATL::CSimpleStringT::StringLength", "ATLSIMPSTR/ATL::CSimpleStringT::Truncate", "ATLSIMPSTR/ATL::CSimpleStringT::UnlockBuffer"] helpviewer_keywords: ["shared classes, CSimpleStringT", "strings [C++], ATL class", "CSimpleStringT class"] --- @@ -18,7 +18,7 @@ class CSimpleStringT ### Parameters -*`BaseType`*
+*`BaseType`*\ The character type of the string class. Can be one of the following: - **`char`** (for ANSI character strings). @@ -445,7 +445,7 @@ An `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to return the buffer contents of the `CSimpleStringT` object. The returned `PXSTR` is not a constant and therefore allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by `GetBuffer` to change the string contents, you must call [`ReleaseBuffer`](#releasebuffer) before you use any other `CSimpleStringT` member methods. +If you use the pointer returned by `GetBuffer` to change the string contents, you must call [`ReleaseBuffer`](#releasebuffer) to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBuffer` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reallocated if you do not change the length of the `CSimpleStringT`. @@ -491,7 +491,7 @@ A `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to retrieve a specified length of the internal buffer of the `CSimpleStringT` object. The returned `PXSTR` pointer is not **`const`** and thus allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by [`GetBufferSetLength`](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CsimpleStringT` before you use any other `CSimpleStringT` methods. +If you use the pointer returned by [`GetBufferSetLength`](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBufferSetLength` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reassigned if you do not change the length of the `CSimpleStringT`. @@ -502,9 +502,7 @@ If you keep track of the string length yourself, do not append the terminating n For more information about reference counting, see the following articles: - [Managing Object Lifetimes through Reference Counting](/windows/win32/com/managing-object-lifetimes-through-reference-counting) in the Windows SDK. - - [Implementing Reference Counting](/windows/win32/com/implementing-reference-counting) in the Windows SDK. - - [Rules for Managing Reference Counts](/windows/win32/com/rules-for-managing-reference-counts) in the Windows SDK. ### Example @@ -517,9 +515,7 @@ LPTSTR pstr = str.GetBufferSetLength(3); pstr[0] = _T('C'); pstr[1] = _T('u'); pstr[2] = _T('p'); - -// No need for trailing zero or call to ReleaseBuffer() -// because GetBufferSetLength() set it for us. +str.ReleaseBuffer(); str += _T(" soccer is best!"); ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0); @@ -720,28 +716,6 @@ CSimpleString s(_T("abc"), pMgr); ASSERT(s[1] == _T('b')); ``` -## `CSimpleStringT::operator []` - -Call this function to access a single character of the character array. - -### Syntax - -```cpp -XCHAR operator[](int iChar) const; -``` - -### Parameters - -*`iChar`*
-Zero-based index of a character in the string. - -### Remarks - -The overloaded subscript (**`[]`**) operator returns a single character specified by the zero-based index in *`iChar`*. This operator is a convenient substitute for the [`GetAt`](#getat) member function. - -> [!NOTE] -> You can use the subscript (**`[]`**) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`. - ## `CSimpleStringT::operator +=` Joins a new string or character to the end of an existing string. @@ -1166,19 +1140,19 @@ The following example demonstrates the use of `CSimpleStringT::Truncate`. CAtlString basestr; IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str(_T("abcdefghi"), pMgr); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); str.Truncate(4); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); ``` The output from this example is: ```Output -Allocated length: 9 +String length: 9 / Allocated length: 15 Contents: abcdefghi -Allocated length: 4 +String length: 4 / Allocated length: 15 Contents: abcd ``` @@ -1214,5 +1188,5 @@ Call this method to destroy the `CSimpleStringT` object. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/csize-class.md b/docs/atl-mfc-shared/reference/csize-class.md index e807aab432..f398b5055d 100644 --- a/docs/atl-mfc-shared/reference/csize-class.md +++ b/docs/atl-mfc-shared/reference/csize-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CSize Class" title: "CSize Class" -ms.date: "10/18/2018" +description: "Learn more about: CSize Class" +ms.date: 10/18/2018 f1_keywords: ["CSize", "ATLTYPES/ATL::CSize", "ATLTYPES/ATL::CSize::CSize"] helpviewer_keywords: ["SIZE", "dimensions, MFC", "dimensions", "CSize class"] -ms.assetid: fb2cf85a-0bc1-46f8-892b-309c108b52ae --- # CSize Class @@ -12,7 +11,7 @@ Similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structur ## Syntax -``` +```cpp class CSize : public tagSIZE ``` @@ -58,7 +57,7 @@ The `cx` and `cy` members of `SIZE` (and `CSize`) are public. In addition, `CSiz Constructs a `CSize` object. -``` +```cpp CSize() throw(); CSize( int initCX, int initCY) throw(); CSize( SIZE initSize) throw(); @@ -95,13 +94,13 @@ If no arguments are given, `cx` and `cy` are initialized to zero. Checks for equality between two sizes. -``` +```cpp BOOL operator==(SIZE size) const throw(); ``` ### Remarks -Returns nonzero if the sizes are equal, otherwize 0. +Returns nonzero if the sizes are equal, otherwise 0. ### Example @@ -111,7 +110,7 @@ Returns nonzero if the sizes are equal, otherwize 0. Checks for inequality between two sizes. -``` +```cpp BOOL operator!=(SIZE size) const throw(); ``` @@ -151,7 +150,7 @@ void operator-=(SIZE size) throw(); These operators add this `CSize` value to the value of parameter. -``` +```cpp CSize operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -181,7 +180,7 @@ See the following descriptions of the individual operators: The first three of these operators subtract this `CSize` value to the value of parameter. -``` +```cpp CSize operator-(SIZE size) const throw(); CPoint operator-(POINT point) const throw(); CRect operator-(const RECT* lpRect) const throw(); diff --git a/docs/atl-mfc-shared/reference/cstrbuft-class.md b/docs/atl-mfc-shared/reference/cstrbuft-class.md index 4f6f092b91..4cc53bfee5 100644 --- a/docs/atl-mfc-shared/reference/cstrbuft-class.md +++ b/docs/atl-mfc-shared/reference/cstrbuft-class.md @@ -12,7 +12,7 @@ This class provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffe ## Syntax -``` +```cpp template class CStrBufT ``` @@ -26,7 +26,7 @@ The character type of the `CStrBufT` class. Can be one of the following: - **`wchar_t`** (for Unicode character strings) -- TCHAR (for both ANSI and Unicode character strings) +- **`TCHAR`** (for both ANSI and Unicode character strings) ## Members @@ -34,8 +34,8 @@ The character type of the `CStrBufT` class. Can be one of the following: |Name|Description| |----------|-----------------| -|PCXSTR|A pointer to a constant string.| -|PXSTR|A pointer to a string.| +|`PCXSTR`|A pointer to a constant string.| +|`PXSTR`|A pointer to a string.| |`StringType`|The string type whose buffer is to be manipulated by specializations of this class template.| ### Public Constructors @@ -78,7 +78,7 @@ Primarily designed as a helper class, `CStrBufT` provides a convenient way for a Automatically determine the new length of the string at release. -``` +```cpp static const DWORD AUTO_LENGTH = 0x01; ``` @@ -90,7 +90,7 @@ Automatically determine the new length of the string at release. The string must Constructs a buffer object. -``` +```cpp CStrBufT(StringType& str, int nMinLength, DWORD dwFlags = AUTO_LENGTH) throw(...); explicit CStrBufT(StringType& str) throw(...); ``` @@ -120,7 +120,7 @@ Note that the copy constructor is **`private`**. Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PCXSTR() const throw(); ``` @@ -136,7 +136,7 @@ Call this function to return a pointer to the character buffer of a string objec Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PXSTR() throw(); ``` @@ -152,7 +152,7 @@ Call this function to return a pointer to the character buffer of a string objec A pointer to a constant string. -``` +```cpp typedef CSimpleStringT::PCXSTR PCXSTR; ``` @@ -160,7 +160,7 @@ typedef CSimpleStringT::PCXSTR PCXSTR; A pointer to a string. -``` +```cpp typedef CSimpleStringT::PXSTR PXSTR; ``` @@ -168,7 +168,7 @@ typedef CSimpleStringT::PXSTR PXSTR; Set the length of the string object at `GetBuffer` time. -``` +```cpp static const DWORD SET_LENGTH = 0x02; ``` @@ -202,7 +202,7 @@ Call this function to set the length of the string represented by the buffer obj The string type whose buffer is to be manipulated by specializations of this class template. -``` +```cpp typedef CSimpleStringT StringType; ``` diff --git a/docs/atl-mfc-shared/reference/cstringdata-class.md b/docs/atl-mfc-shared/reference/cstringdata-class.md index 03da39cca6..2755f5e8ab 100644 --- a/docs/atl-mfc-shared/reference/cstringdata-class.md +++ b/docs/atl-mfc-shared/reference/cstringdata-class.md @@ -12,7 +12,7 @@ This class represents the data of a string object. ## Syntax -``` +```cpp struct CStringData ``` @@ -105,7 +105,7 @@ Call this function to return the current character buffer of the associated stri Determines if the character buffer is locked. -``` +```cpp bool IsLocked() const throw(); ``` @@ -121,7 +121,7 @@ Call this function to determine if the character buffer of a string object is cu Determines if the character buffer is shared. -``` +```cpp bool IsShared() const throw(); ``` @@ -152,7 +152,7 @@ Call this function to lock the character buffer of the string data object. Locki Length of the allocated character buffer. -``` +```cpp int nAllocLength; ``` @@ -164,7 +164,7 @@ Stores the length of the allocated data buffer in `XCHAR`s (not including termin Current length of the string object. -``` +```cpp int nDataLength; ``` @@ -176,7 +176,7 @@ Stores the length of currently used data in `XCHAR`s (not including terminating Reference count of the string data object. -``` +```cpp long nRefs; ``` @@ -188,7 +188,7 @@ Stores the reference count of the string data object. This count indicates the n The memory manager of the associated string object. -``` +```cpp IAtlStringMgr* pStringMgr; ``` diff --git a/docs/atl-mfc-shared/reference/cstringt-class.md b/docs/atl-mfc-shared/reference/cstringt-class.md index 6921e0fded..a47c9ad9a6 100644 --- a/docs/atl-mfc-shared/reference/cstringt-class.md +++ b/docs/atl-mfc-shared/reference/cstringt-class.md @@ -486,11 +486,11 @@ A handle for a **`CStringT`** object. Because the constructors copy the input data into new allocated storage, memory exceptions may result. Some of these constructors act as conversion functions. This allows you to substitute, for example, an **`LPTSTR`** where a **`CStringT`** object is expected. -- **`CStringT`**( `LPCSTR` `lpsz` ): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. +- **`CStringT`**(`LPCSTR` `lpsz`): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. -- `CStringT(` `LPCWSTR` `lpsz` ): Constructs a **`CStringT`** from a Unicode string. +- **`CStringT`**(`LPCWSTR` `lpsz`): Constructs a **`CStringT`** from a Unicode string. -- **`CStringT`**( `const unsigned char*` `psz` ): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. +- **`CStringT`**(`const unsigned char*` `psz`): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. > [!NOTE] > Define the `_CSTRING_DISABLE_NARROW_WIDE_CONVERSION` macro to turn off implicit string conversion between ANSI and Unicode strings. The macro excludes from compilation constructors that support conversion. @@ -725,7 +725,7 @@ Writes a formatted string and a variable list of arguments to a **`CStringT`** s ### Example [!code-cpp[NVC_ATLMFC_Utilities#119](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_14.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#120](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_15.cpp)] ## `CStringT::GetEnvironmentVariable` @@ -998,11 +998,11 @@ Concatenates two strings or a character and a string. ```cpp friend CStringT operator+(const CStringT& str1, const CStringT& str2); friend CStringT operator+(const CStringT& str1, PCXSTR psz2); -friend CStringT operator+(PCXSTR psz1, const CStringT& str2,); -friend CStringT operator+(char ch1, const CStringT& str2,); +friend CStringT operator+(PCXSTR psz1, const CStringT& str2); +friend CStringT operator+(char ch1, const CStringT& str2); friend CStringT operator+(const CStringT& str1, char ch2); friend CStringT operator+(const CStringT& str1, wchar_t ch2); -friend CStringT operator+(wchar_t ch1, const CStringT& str2,); +friend CStringT operator+(wchar_t ch1, const CStringT& str2); ``` ### Parameters @@ -1102,8 +1102,8 @@ friend bool operator==(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator==(const CStringT& str1, PCYSTR psz2) throw(); friend bool operator==(const CStringT& str1, XCHAR ch2) throw(); friend bool operator==(PCXSTR psz1, const CStringT& str2) throw(); -friend bool operator==(PCYSTR psz1, const CStringT& str2,) throw(); -friend bool operator==(XCHAR ch1, const CStringT& str2,) throw(); +friend bool operator==(PCYSTR psz1, const CStringT& str2) throw(); +friend bool operator==(XCHAR ch1, const CStringT& str2) throw(); ``` ### Parameters @@ -1144,8 +1144,8 @@ friend bool operator!=(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator!=(const CStringT& str1, PCYSTR psz2) throw(); friend bool operator!=(const CStringT& str1, XCHAR ch2) throw(); friend bool operator!=(PCXSTR psz1, const CStringT& str2) throw(); -friend bool operator!=(PCYSTR psz1, const CStringT& str2,) throw(); -friend bool operator!=(XCHAR ch1, const CStringT& str2,) throw(); +friend bool operator!=(PCYSTR psz1, const CStringT& str2) throw(); +friend bool operator!=(XCHAR ch1, const CStringT& str2) throw(); ``` ### Parameters diff --git a/docs/atl-mfc-shared/reference/ctime-class.md b/docs/atl-mfc-shared/reference/ctime-class.md index 0fbc79bb4d..067db91b52 100644 --- a/docs/atl-mfc-shared/reference/ctime-class.md +++ b/docs/atl-mfc-shared/reference/ctime-class.md @@ -12,7 +12,7 @@ Represents an absolute time and date. ## Syntax -``` +```cpp class CTime ``` @@ -82,7 +82,7 @@ For more information about using `CTime`, see the articles [Date and Time](../.. Comparison operators. -``` +```cpp bool operator==(CTime time) const throw(); bool operator!=(CTime time) const throw(); bool operator<(CTime time) const throw(); @@ -108,7 +108,7 @@ These operators compare two absolute times and return TRUE if the condition is t Creates a new `CTime` object initialized with the specified time. -``` +```cpp CTime() throw(); CTime(__time64_t time) throw(); CTime(int nYear, int nMonth, int nDay, @@ -193,7 +193,7 @@ For more information, see the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minw Call this member function to create a formatted representation of the date-time value. -``` +```cpp CString Format(LPCTSTR pszFormat) const; CString Format(UINT nFormatID) const; ``` @@ -224,7 +224,7 @@ This method throws an exception if the date-time value to format does not range Generates a formatted string that corresponds to this `CTime` object. -``` +```cpp CString FormatGmt(LPCTSTR pszFormat) const; CString FormatGmt(UINT nFormatID) const; ``` @@ -255,7 +255,7 @@ See the example for [CTime::Format](#format). Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible DBTIMESTAMP structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& dbts) const throw(); ``` @@ -280,7 +280,7 @@ Stores the resulting time in the referenced *dbts* structure. The `DBTIMESTAMP` Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& st) const throw(); ``` @@ -305,7 +305,7 @@ TRUE if successful; otherwise FALSE. Returns a `CTime` object that represents the current time. -``` +```cpp static CTime WINAPI GetCurrentTime() throw(); ``` @@ -321,7 +321,7 @@ Returns the current system date and time in Coordinated Universal Time (UTC). Returns the day represent by the `CTime` object. -``` +```cpp int GetDay() const throw(); ``` @@ -341,7 +341,7 @@ This function calls `GetLocalTm`, which uses an internal, statically allocated b Returns the day of the week represented by the `CTime` object. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -361,7 +361,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** that contains a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetGmtTm(struct tm* ptm) const; ``` @@ -388,7 +388,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the hour represented by the `CTime` object. -``` +```cpp int GetHour() const throw(); ``` @@ -408,7 +408,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** containing a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetLocalTm(struct tm* ptm) const; ``` @@ -435,7 +435,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the minute represented by the `CTime` object. -``` +```cpp int GetMinute() const throw(); ``` @@ -455,7 +455,7 @@ See the example for [GetHour](#gethour). Returns the month represented by the `CTime` object. -``` +```cpp int GetMonth() const throw(); ``` @@ -475,7 +475,7 @@ See the example for [GetDay](#getday). Returns the second represented by the `CTime` object. -``` +```cpp int GetSecond() const throw(); ``` @@ -495,7 +495,7 @@ See the example for [GetHour](#gethour). Returns a **__time64_t** value for the given `CTime` object. -``` +```cpp __time64_t GetTime() const throw(); ``` @@ -511,7 +511,7 @@ __time64_t GetTime() const throw(); Returns the year represented by the `CTime` object. -``` +```cpp int GetYear(); ``` @@ -531,7 +531,7 @@ See the example for [GetDay](#getday). The assignment operator. -``` +```cpp CTime& operator=(__time64_t time) throw(); ``` @@ -552,7 +552,7 @@ This overloaded assignment operator copies the source time into this `CTime` obj These operators add and subtract `CTimeSpan` and `CTime` objects. -``` +```cpp CTime operator+(CTimeSpan timeSpan) const throw(); CTime operator-(CTimeSpan timeSpan) const throw(); CTimeSpan operator-(CTime time) const throw(); @@ -582,7 +582,7 @@ A `CTime` or `CTimeSpan` object representing the result of the operation. These operators add and subtract a `CTimeSpan` object to and from this `CTime` object. -``` +```cpp CTime& operator+=(CTimeSpan span) throw(); CTime& operator-=(CTimeSpan span) throw(); ``` @@ -611,7 +611,7 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` diff --git a/docs/atl-mfc-shared/reference/ctimespan-class.md b/docs/atl-mfc-shared/reference/ctimespan-class.md index d00f45805e..ae10bdba1c 100644 --- a/docs/atl-mfc-shared/reference/ctimespan-class.md +++ b/docs/atl-mfc-shared/reference/ctimespan-class.md @@ -4,15 +4,14 @@ title: "CTimeSpan Class" ms.date: "10/18/2018" f1_keywords: ["CTimeSpan", "ATLTIME/ATL::CTimeSpan", "ATLTIME/ATL::CTimeSpan::CTimeSpan", "ATLTIME/ATL::CTimeSpan::Format", "ATLTIME/ATL::CTimeSpan::GetDays", "ATLTIME/ATL::CTimeSpan::GetHours", "ATLTIME/ATL::CTimeSpan::GetMinutes", "ATLTIME/ATL::CTimeSpan::GetSeconds", "ATLTIME/ATL::CTimeSpan::GetTimeSpan", "ATLTIME/ATL::CTimeSpan::GetTotalHours", "ATLTIME/ATL::CTimeSpan::GetTotalMinutes", "ATLTIME/ATL::CTimeSpan::GetTotalSeconds", "ATLTIME/ATL::CTimeSpan::Serialize64"] helpviewer_keywords: ["elapsed time, CTimeSpan object", "timespan", "time span", "CTimeSpan class", "shared classes, CTimeSpan", "time, elapsed"] -ms.assetid: ee1e42f6-1839-477a-8435-fb26ad475140 --- -# CTimeSpan Class +# `CTimeSpan` Class An amount of time, which is internally stored as the number of seconds in the time span. ## Syntax -``` +```cpp class CTimeSpan ``` @@ -22,54 +21,54 @@ class CTimeSpan |Name|Description| |----------|-----------------| -|[CTimeSpan::CTimeSpan](#ctimespan)|Constructs `CTimeSpan` objects in various ways.| +|[`CTimeSpan::CTimeSpan`](#ctimespan)|Constructs `CTimeSpan` objects in various ways.| ### Public Methods |Name|Description| |----------|-----------------| -|[CTimeSpan::Format](#format)|Converts a `CTimeSpan` into a formatted string.| -|[CTimeSpan::GetDays](#getdays)|Returns a value that represents the number of complete days in this `CTimeSpan`.| -|[CTimeSpan::GetHours](#gethours)|Returns a value that represents the number of hours in the current day (-23 through 23).| -|[CTimeSpan::GetMinutes](#getminutes)|Returns a value that represents the number of minutes in the current hour (-59 through 59).| -|[CTimeSpan::GetSeconds](#getseconds)|Returns a value that represents the number of seconds in the current minute (-59 through 59).| -|[CTimeSpan::GetTimeSpan](#gettimespan)|Returns the value of the `CTimeSpan` object.| -|[CTimeSpan::GetTotalHours](#gettotalhours)|Returns a value that represents the total number of complete hours in this `CTimeSpan`.| -|[CTimeSpan::GetTotalMinutes](#gettotalminutes)|Returns a value that represents the total number of complete minutes in this `CTimeSpan`.| -|[CTimeSpan::GetTotalSeconds](#gettotalseconds)|Returns a value that represents the total number of complete seconds in this `CTimeSpan`.| -|[CTimeSpan::Serialize64](#serialize64)|Serializes data to or from an archive.| +|[`CTimeSpan::Format`](#format)|Converts a `CTimeSpan` into a formatted string.| +|[`CTimeSpan::GetDays`](#getdays)|Returns a value that represents the number of complete days in this `CTimeSpan`.| +|[`CTimeSpan::GetHours`](#gethours)|Returns a value that represents the number of hours in the current day (-23 through 23).| +|[`CTimeSpan::GetMinutes`](#getminutes)|Returns a value that represents the number of minutes in the current hour (-59 through 59).| +|[`CTimeSpan::GetSeconds`](#getseconds)|Returns a value that represents the number of seconds in the current minute (-59 through 59).| +|[`CTimeSpan::GetTimeSpan`](#gettimespan)|Returns the value of the `CTimeSpan` object.| +|[`CTimeSpan::GetTotalHours`](#gettotalhours)|Returns a value that represents the total number of complete hours in this `CTimeSpan`.| +|[`CTimeSpan::GetTotalMinutes`](#gettotalminutes)|Returns a value that represents the total number of complete minutes in this `CTimeSpan`.| +|[`CTimeSpan::GetTotalSeconds`](#gettotalseconds)|Returns a value that represents the total number of complete seconds in this `CTimeSpan`.| +|[`CTimeSpan::Serialize64`](#serialize64)|Serializes data to or from an archive.| ### Operators |Name|Description| |-|-| -|[operator + -](#operator_add_-)|Adds and subtracts `CTimeSpan` objects.| -|[operator += -=](#operator_add_eq_-_eq)|Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`.| -|[operator == < etc.](#ctimespan_comparison_operators)|Compares two relative time values.| +|[`operator + -`](#operator_add_-)|Adds and subtracts `CTimeSpan` objects.| +|[`operator += -=`](#operator_add_eq_-_eq)|Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`.| +|[`operator == < etc.`](#ctimespan_comparison_operators)|Compares two relative time values.| ## Remarks -`CTimeSpan` does not have a base class. +`CTimeSpan` doesn't have a base class. `CTimeSpan` functions convert seconds to various combinations of days, hours, minutes, and seconds. -The `CTimeSpan` object is stored in a **__time64_t** structure, which is 8 bytes. +The `CTimeSpan` object is stored in a **`__time64_t`** structure, which is 8 bytes. -A companion class, [CTime](../../atl-mfc-shared/reference/ctime-class.md), represents an absolute time. +A companion class, [`CTime`](../../atl-mfc-shared/reference/ctime-class.md), represents an absolute time. -The `CTime` and `CTimeSpan` classes are not designed for derivation. Because there are no virtual functions, the size of both `CTime` and `CTimeSpan` objects is exactly 8 bytes. Most member functions are inline. +The `CTime` and `CTimeSpan` classes aren't designed for derivation. Because there are no virtual functions, the size of both `CTime` and `CTimeSpan` objects is exactly 8 bytes. Most member functions are inline. For more information on using `CTimeSpan`, see the articles [Date and Time](../../atl-mfc-shared/date-and-time.md), and [Time Management](../../c-runtime-library/time-management.md) in the *Run-Time Library Reference*. ## Requirements -**Header:** atltime.h +**Header:** `atltime.h` -## CTimeSpan Comparison Operators +## `CTimeSpan` Comparison Operators Comparison operators. -``` +```cpp bool operator==(CTimeSpan span) const throw(); bool operator!=(CTimeSpan span) const throw(); bool operator<(CTimeSpan span) const throw(); @@ -80,22 +79,22 @@ bool operator>=(CTimeSpan span) const throw(); ### Parameters -*span*
+*`span`*\ The object to compare. ### Return Value -These operators compare two relative time values. They return TRUE if the condition is true; otherwise FALSE. +These operators compare two relative time values. They return `TRUE` if the condition is true; otherwise `FALSE`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#169](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_1.cpp)] -## CTimeSpan::CTimeSpan +## `CTimeSpan::CTimeSpan` Constructs `CTimeSpan` objects in various ways. -``` +```cpp CTimeSpan() throw(); CTimeSpan(__time64_t time) throw(); @@ -108,13 +107,13 @@ CTimeSpan( ### Parameters -*timeSpanSrc*
+*`timeSpanSrc`*\ A `CTimeSpan` object that already exists. -*time*
-A **__time64_t** time value, which is the number of seconds in the time span. +*`time`*\ +A **`__time64_t`** time value, which is the number of seconds in the time span. -*lDays*, *nHours*, *nMins*, *nSecs*
+*`lDays`*, *`nHours`*, *`nMins`*, *`nSecs`*\ Days, hours, minutes, and seconds, respectively. ### Remarks @@ -125,7 +124,7 @@ All these constructors create a new `CTimeSpan` object initialized with the spec - `CTimeSpan( const CTimeSpan& );` Constructs a `CTimeSpan` object from another `CTimeSpan` value. -- `CTimeSpan( __time64_t );` Constructs a `CTimeSpan` object from a **__time64_t** type. +- `CTimeSpan( __time64_t );` Constructs a `CTimeSpan` object from a **`__time64_t`** type. - `CTimeSpan( LONG, int, int, int );` Constructs a `CTimeSpan` object from components with each component constrained to the following ranges: @@ -142,11 +141,11 @@ Note that the Debug version of the Microsoft Foundation Class Library asserts if [!code-cpp[NVC_ATLMFC_Utilities#162](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_2.cpp)] -## CTimeSpan::Format +## `CTimeSpan::Format` Generates a formatted string that corresponds to this `CTimeSpan`. -``` +```cpp CString Format(LPCSTR pFormat) const; CString Format(LPCTSTR pszFormat) const; CString Format(UINT nID) const; @@ -154,20 +153,20 @@ CString Format(UINT nID) const; ### Parameters -*pFormat*, *pszFormat*
+*`pFormat`*, *`pszFormat`*\ A formatting string similar to the `printf` formatting string. Formatting codes, preceded by a percent (`%`) sign, are replaced by the corresponding `CTimeSpan` component. Other characters in the formatting string are copied unchanged to the returned string. The value and meaning of the formatting codes for `Format` are listed below: -- **%D** Total days in this `CTimeSpan` +- **`%D`** Total days in this `CTimeSpan` -- **%H** Hours in the current day +- **`%H`** Hours in the current day -- **%M** Minutes in the current hour +- **`%M`** Minutes in the current hour -- **%S** Seconds in the current minute +- **`%S`** Seconds in the current minute -- **%%** Percent sign +- **`%%`** Percent sign -*nID*
+*`nID`*\ The ID of the string that identifies this format. ### Return Value @@ -176,17 +175,17 @@ A `CString` object that contains the formatted time. ### Remarks -The Debug version of the library checks the formatting codes and asserts if the code is not in the list above. +The Debug version of the library checks the formatting codes and asserts if the code isn't in the list above. ### Example [!code-cpp[NVC_ATLMFC_Utilities#163](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_3.cpp)] -## CTimeSpan::GetDays +## `CTimeSpan::GetDays` Returns a value that represents the number of complete days in this `CTimeSpan`. -``` +```cpp LONGLONG GetDays() const throw(); ``` @@ -196,17 +195,17 @@ Returns the number of complete 24-hour days in the time span. This value may be ### Remarks -Note that Daylight Savings Time can cause `GetDays` to return a potentially surprising result. For example, when DST is in effect, `GetDays` reports the number of days between April 1 and May 1 as 29, not 30, because one day in April is shortened by an hour and therefore does not count as a complete day. +Note that Daylight Savings Time (DST) can cause `GetDays` to return a potentially surprising result. For example, when DST is in effect, `GetDays` reports the number of days between April 1 and May 1 as 29, not 30, because one day in April is shortened by an hour and therefore doesn't count as a complete day. ### Example [!code-cpp[NVC_ATLMFC_Utilities#164](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_4.cpp)] -## CTimeSpan::GetHours +## `CTimeSpan::GetHours` Returns a value that represents the number of hours in the current day (-23 through 23). -``` +```cpp LONG GetHours() const throw(); ``` @@ -218,11 +217,11 @@ Returns the number of hours in the current day. The range is -23 through 23. [!code-cpp[NVC_ATLMFC_Utilities#165](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_5.cpp)] -## CTimeSpan::GetMinutes +## `CTimeSpan::GetMinutes` Returns a value that represents the number of minutes in the current hour (-59 through 59). -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -232,13 +231,13 @@ Returns the number of minutes in the current hour. The range is -59 through 59. ### Example -See the example for [GetHours](#gethours). +See the example for [`GetHours`](#gethours). -## CTimeSpan::GetSeconds +## `CTimeSpan::GetSeconds` Returns a value that represents the number of seconds in the current minute (-59 through 59). -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -248,13 +247,13 @@ Returns the number of seconds in the current minute. The range is -59 through 59 ### Example -See the example for [GetHours](#gethours). +See the example for [`GetHours`](#gethours). -## CTimeSpan::GetTimeSpan +## `CTimeSpan::GetTimeSpan` Returns the value of the `CTimeSpan` object. -``` +```cpp __ time64_t GetTimeSpan() const throw(); ``` @@ -262,11 +261,11 @@ __ time64_t GetTimeSpan() const throw(); Returns the current value of the `CTimeSpan` object. -## CTimeSpan::GetTotalHours +## `CTimeSpan::GetTotalHours` Returns a value that represents the total number of complete hours in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalHours() const throw(); ``` @@ -278,11 +277,11 @@ Returns the total number of complete hours in this `CTimeSpan`. [!code-cpp[NVC_ATLMFC_Utilities#166](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_6.cpp)] -## CTimeSpan::GetTotalMinutes +## `CTimeSpan::GetTotalMinutes` Returns a value that represents the total number of complete minutes in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalMinutes() const throw(); ``` @@ -292,13 +291,13 @@ Returns the total number of complete minutes in this `CTimeSpan`. ### Example -See the example for [GetTotalHours](#gettotalhours). +See the example for [`GetTotalHours`](#gettotalhours). -## CTimeSpan::GetTotalSeconds +## `CTimeSpan::GetTotalSeconds` Returns a value that represents the total number of complete seconds in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalSeconds() const throw(); ``` @@ -308,20 +307,20 @@ Returns the total number of complete seconds in this `CTimeSpan`. ### Example -See the example for [GetTotalHours](#gettotalhours). +See the example for [`GetTotalHours`](#gettotalhours). -## CTimeSpan::operator +, - +## `CTimeSpan::operator +`, `CTimeSpan::operator -` Adds and subtracts `CTimeSpan` objects. -``` +```cpp CTimeSpan operator+(CTimeSpan span) const throw(); CTimeSpan operator-(CTimeSpan span) const throw(); ``` ### Parameters -*span*
+*`span`*\ The value to add to the `CTimeSpan` object. ### Return Value @@ -336,18 +335,18 @@ These two operators allow you to add and subtract `CTimeSpan` objects to and fro [!code-cpp[NVC_ATLMFC_Utilities#167](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_7.cpp)] -## CTimeSpan::operator +=, -= +## `CTimeSpan::operator +=`, `CTimeSpan::operator -=` Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`. -``` +```cpp CTimeSpan& operator+=(CTimeSpan span) throw(); CTimeSpan& operator-=(CTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ The value to add to the `CTimeSpan` object. ### Return Value @@ -362,20 +361,20 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t [!code-cpp[NVC_ATLMFC_Utilities#168](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_8.cpp)] -## CTimeSpan::Serialize64 +## `CTimeSpan::Serialize64` > [!NOTE] > This method is only available in MFC projects. Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` ### Parameters -*ar*
+*`ar`*\ The `CArchive` object that you want to update. ### Return Value @@ -384,11 +383,11 @@ The updated `CArchive` object. ## See also -[asctime, _wasctime](../../c-runtime-library/reference/asctime-wasctime.md)
-[_ftime, _ftime32, _ftime64](../../c-runtime-library/reference/ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](../../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](../../c-runtime-library/reference/localtime-localtime32-localtime64.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)
-[time, _time32, _time64](../../c-runtime-library/reference/time-time32-time64.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[`asctime`, `_wasctime`](../../c-runtime-library/reference/asctime-wasctime.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](../../c-runtime-library/reference/ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](../../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](../../c-runtime-library/reference/localtime-localtime32-localtime64.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`time`, `_time32`, `_time64`](../../c-runtime-library/reference/time-time32-time64.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md index cbf301b82b..9eb991ca28 100644 --- a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md +++ b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md @@ -12,7 +12,7 @@ This class represents the interface to a `CStringT` memory manager. ## Syntax -``` +```cpp __interface IAtlStringMgr ``` @@ -42,7 +42,7 @@ You can also use this class to implement a custom memory manager for your custom Allocates a new string data structure. -``` +```cpp CStringData* Allocate(int nAllocLength,int nCharSize) throw(); ``` @@ -72,7 +72,7 @@ Call [IAtlStringMgr::Free](#free) or [IAtlStringMgr::ReAllocate](#reallocate) to Returns a pointer to a new string manager for use with another instance of `CSimpleStringT`. -``` +```cpp IAtlStringMgr* Clone() throw(); ``` @@ -113,7 +113,7 @@ Frees the specified memory block previously allocated by [Allocate](#allocate) o Returns a pointer to a string data structure for an empty string. -``` +```cpp CStringData* GetNilString() throw(); ``` @@ -135,7 +135,7 @@ Call this function to return a representation of an empty string. Reallocates a string data structure. -``` +```cpp CStringData* Reallocate( CStringData* pData, int nAllocLength, diff --git a/docs/atl-mfc-shared/string-data-management.md b/docs/atl-mfc-shared/string-data-management.md index 80640e06c2..b48c6a636d 100644 --- a/docs/atl-mfc-shared/string-data-management.md +++ b/docs/atl-mfc-shared/string-data-management.md @@ -3,19 +3,18 @@ description: "Learn more about: String Data Management" title: "String Data Management" ms.date: "11/04/2016" helpviewer_keywords: ["Unicode, string objects"] -ms.assetid: 0b53a542-eeb1-4108-9ada-6700645b6f8f --- # String Data Management Visual C++ provides several ways to manage string data: -- [String Manipulation](../c-runtime-library/string-manipulation-crt.md) for working with C-style null-terminated strings +- [String Manipulation](../c-runtime-library/string-manipulation-crt.md) for working with C-style `NULL`-terminated strings - Win32 API functions for managing strings -- MFC's class [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md), which provides flexible, resizable string objects +- MFC's class [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md), which provides flexible, resizable string objects -- Class [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md), which provides an MFC-independent string object with the same functionality as `CString` +- Class [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md), which provides an MFC-independent string object with the same functionality as `CString` Nearly all programs work with string data. MFC's `CString` class is often the best solution for flexible string handling. Starting with version 7.0, `CString` can be used in MFC or MFC-independent programs. Both the run-time library and `CString` support strings containing multibyte (wide) characters, as in Unicode or MBCS programming. @@ -23,11 +22,11 @@ This article describes the general-purpose services that the class library provi - [Unicode and MBCS Provide portability](#_core_unicode_and_mbcs_provide_portability) -- [CStrings and const char Pointers](#_core_cstrings_and_const_char_pointers) +- [`CStrings` and `const char` Pointers](#_core_cstrings_and_const_char_pointers) -- [CString Reference Counting](#_core_cstring_reference_counting) +- [`CString` Reference Counting](#_core_cstring_reference_counting) -The [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md) class provides support for manipulating strings. It is intended to replace and extend the functionality normally provided by the C run-time library string package. The `CString` class supplies member functions and operators for simplified string handling, similar to those found in Basic. The class also provides constructors and operators for constructing, assigning, and comparing `CString`s and standard C++ string data types. Because `CString` is not derived from `CObject`, you can use `CString` objects independently of most of the Microsoft Foundation Class Library (MFC). +The [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md) class provides support for manipulating strings. It's intended to replace and extend the functionality normally provided by the C run-time library string package. The `CString` class supplies member functions and operators for simplified string handling, similar to those found in Basic. The class also provides constructors and operators for constructing, assigning, and comparing `CString`s and standard C++ string data types. Because `CString` isn't derived from `CObject`, you can use `CString` objects independently of most of the Microsoft Foundation Class Library (MFC). `CString` objects follow "value semantics." A `CString` object represents a unique value. Think of a `CString` as an actual string, not as a pointer to a string. @@ -35,10 +34,10 @@ A `CString` object represents a sequence of a variable number of characters. `CS ## Unicode and MBCS Provide Portability -With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Unicode and multibyte character sets (MBCS). This support makes it easier for you to write portable applications that you can build for either Unicode or ANSI characters. To enable this portability, each character in a `CString` object is of type TCHAR, which is defined as **`wchar_t`** if you define the symbol _UNICODE when you build your application, or as **`char`** if not. A **`wchar_t`** character is 16 bits wide. MBCS is enabled if you build with the symbol _MBCS defined. MFC itself is built with either the _MBCS symbol (for the NAFX libraries) or the _UNICODE symbol (for the UAFX libraries) defined. +With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Unicode and multibyte character sets (MBCS). This support makes it easier for you to write portable applications that you can build for either Unicode or ANSI characters. To enable this portability, each character in a `CString` object is of type `TCHAR`, which is defined as **`wchar_t`** if you define the symbol `_UNICODE` when you build your application, or as **`char`** if not. A **`wchar_t`** character is 16 bits wide. MBCS is enabled if you build with the symbol `_MBCS` defined. MFC itself is built with either the `_MBCS` symbol (for the NAFX libraries) or the `_UNICODE` symbol (for the UAFX libraries) defined. > [!NOTE] -> The `CString` examples in this and the accompanying articles on strings show literal strings properly formatted for Unicode portability, using the _T macro, which translates the literal string to the form: +> The `CString` examples in this and the accompanying articles on strings show literal strings properly formatted for Unicode portability, using the `_T` macro, which translates the literal string to the form: `L"literal string"` @@ -48,34 +47,34 @@ With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Un [!code-cpp[NVC_ATLMFC_Utilities#187](../atl-mfc-shared/codesnippet/cpp/string-data-management_1.cpp)] > [!NOTE] -> is translated as a Unicode string if _UNICODE is defined or as an ANSI string if not. For more information, see the article [Unicode and Multibyte Character Set (MBCS) Support](../atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md). +> is translated as a Unicode string if `_UNICODE` is defined or as an ANSI string if not. For more information, see the article [Unicode and Multibyte Character Set (MBCS) Support](../atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md). -A `CString` object can store up to INT_MAX (2,147,483,647) characters. The TCHAR data type is used to get or set individual characters inside a `CString` object. Unlike character arrays, the `CString` class has a built-in memory allocation capability. This allows `CString` objects to automatically grow as needed (that is, you do not have to worry about growing a `CString` object to fit longer strings). +A `CString` object can store up to `INT_MAX` (2,147,483,647) characters. The `TCHAR` data type is used to get or set individual characters inside a `CString` object. Unlike character arrays, the `CString` class has a built-in memory allocation capability. This allows `CString` objects to automatically grow as needed (that is, you don't have to worry about growing a `CString` object to fit longer strings). -## CStrings and const char Pointers +## `CStrings` and `const char` Pointers -A `CString` object also can act like a literal C-style string (an `PCXSTR`, which is the same as **const char**\* if not under Unicode). The [CSimpleStringT::operator PCXSTR](../atl-mfc-shared/reference/csimplestringt-class.md#operator_pcxstr) conversion operator allows `CString` objects to be freely substituted for character pointers in function calls. The **CString( LPCWSTR** `pszSrc` **)** constructor allows character pointers to be substituted for `CString` objects. +A `CString` object also can act like a literal C-style string (an `PCXSTR`, which is the same as `const char*` if not under Unicode). The [`CSimpleStringT::operator PCXSTR`](../atl-mfc-shared/reference/csimplestringt-class.md#operator_pcxstr) conversion operator allows `CString` objects to be freely substituted for character pointers in function calls. The `CString(LPCWSTR pszSrc)` constructor allows character pointers to be substituted for `CString` objects. -No attempt is made to fold `CString` objects. If you make two `CString` objects containing `Chicago`, for example, the characters in `Chicago` are stored in two places. (This may not be true of future versions of MFC, so you should not depend on it.) +No attempt is made to fold `CString` objects. If you make two `CString` objects containing `Chicago`, for example, the characters in `Chicago` are stored in two places. (This may not be true of future versions of MFC, so you shouldn't depend on it.) > [!NOTE] -> Use the [CSimpleStringT::GetBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#getbuffer) and [CSimpleStringT::ReleaseBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#releasebuffer) member functions when you need to directly access a `CString` as a nonconstant pointer to a character. +> Use the [`CSimpleStringT::GetBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#getbuffer) and [`CSimpleStringT::ReleaseBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#releasebuffer) member functions when you need to directly access a `CString` as a nonconstant pointer to a character. > [!NOTE] -> Use the [CStringT::AllocSysString](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring) and [CStringT::SetSysString](../atl-mfc-shared/reference/cstringt-class.md#setsysstring) member functions to allocate and set BSTR objects used in Automation (formerly known as OLE Automation). +> Use the [`CStringT::AllocSysString`](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring) and [`CStringT::SetSysString`](../atl-mfc-shared/reference/cstringt-class.md#setsysstring) member functions to allocate and set `BSTR` objects used in Automation (formerly known as OLE Automation). > [!NOTE] > Where possible, allocate `CString` objects on the frame rather than on the heap. This saves memory and simplifies parameter passing. -The `CString` class is not implemented as a Microsoft Foundation Class Library collection class, though `CString` objects can certainly be stored as elements in collections. +The `CString` class isn't implemented as a Microsoft Foundation Class Library collection class, though `CString` objects can certainly be stored as elements in collections. -## CString Reference Counting +## `CString` Reference Counting -As of MFC version 4.0, when [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md) objects are copied, MFC increments a reference count rather than copying the data. This makes passing parameters by value and returning `CString` objects by value more efficient. These operations cause the copy constructor to be called, sometimes more than once. Incrementing a reference count reduces that overhead for these common operations and makes using `CString` a more attractive option. +As of MFC version 4.0, when [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md) objects are copied, MFC increments a reference count rather than copying the data. This makes passing parameters by value and returning `CString` objects by value more efficient. These operations cause the copy constructor to be called, sometimes more than once. Incrementing a reference count reduces that overhead for these common operations and makes using `CString` a more attractive option. -As each copy is destroyed, the reference count in the original object is decremented. The original `CString` object is not destroyed until its reference count is reduced to zero. +As each copy is destroyed, the reference count in the original object is decremented. The original `CString` object isn't destroyed until its reference count is reduced to zero. -You can use the `CString` member functions [CSimpleStringT::LockBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#lockbuffer) and [CSimpleStringT::UnlockBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#unlockbuffer) to disable or enable reference counting. +You can use the `CString` member functions [`CSimpleStringT::LockBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#lockbuffer) and [`CSimpleStringT::UnlockBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#unlockbuffer) to disable or enable reference counting. ## See also diff --git a/docs/atl-mfc-shared/strings-atl-mfc.md b/docs/atl-mfc-shared/strings-atl-mfc.md index db5891cc87..1c0b4515fa 100644 --- a/docs/atl-mfc-shared/strings-atl-mfc.md +++ b/docs/atl-mfc-shared/strings-atl-mfc.md @@ -3,7 +3,6 @@ description: "Learn more about: Strings (ATL/MFC)" title: "Strings (ATL-MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["const char pointers", "strings [C++], in ATL", "MFC [C++], string handling class", "MBCS [C++], CString support", "strings [C++], class CStringT", "char pointers", "reference counting [C++]", "strings [C++], string operations", "portability [C++], Unicode and ANSI string objects", "literal strings [C++], class CString", "copying string objects", "ATL, string handling class", "strings [C++], in MFC", "strings [C++]", "C-style strings", "language portability [C++]", "strings [C++], class CString", "literal strings [C++], class CStringT"] -ms.assetid: 3b33125b-1684-4542-a3a7-b00de7d0419e --- # Strings (ATL/MFC) @@ -11,18 +10,18 @@ Nearly all programs work with string data. Visual C++ provides several ways to m ## In This Section -[Using CStringT](../atl-mfc-shared/using-cstringt.md)
-Describes programming using the template class CStringT. +[Using `CStringT`](../atl-mfc-shared/using-cstringt.md)\ +Describes programming using the template class `CStringT`. -[Using CString](../atl-mfc-shared/using-cstring.md)
-Describes programming using CString, the default implementation of CStringT. +[Using `CString`](../atl-mfc-shared/using-cstring.md)\ +Describes programming using `CString`, the default implementation of `CStringT`. ## Related Sections -[CStringT Overview](../atl-mfc-shared/reference/cstringt-class.md)
+[`CStringT` Overview](../atl-mfc-shared/reference/cstringt-class.md)\ Provides reference information about the shared `CStringT` class. -[MFC Concepts](../mfc/mfc-concepts.md)
+[MFC Concepts](../mfc/mfc-concepts.md)\ Provides conceptual and task-based topics to help you program using the MFC Library. ## See also diff --git a/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md b/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md index 094c1d037a..2ba1928aa6 100644 --- a/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md +++ b/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md @@ -8,11 +8,14 @@ helpviewer_keywords: ["MFC [C++], character set support", "MBCS [C++], strings a Some languages, for example, Japanese and Chinese, have large character sets. To support programming for these markets, the Microsoft Foundation Class Library (MFC) enables two different approaches to handling large character sets: -- [Unicode](#mfc-support-for-unicode-strings), **`wchar_t`** based wide-characters and strings encoded as UTF-16. +- [Unicode](#mfc-support-for-unicode-strings), **`wchar_t`** based wide-characters, and strings encoded as UTF-16. - [Multibyte Character Sets (MBCS)](#mfc-support-for-mbcs-strings), **`char`** based single or double-byte characters and strings encoded in a locale-specific character set. -Microsoft has recommended the MFC Unicode libraries for all new development, and the MBCS libraries were deprecated in Visual Studio 2013 and Visual Studio 2015. This is no longer the case. The MBCS deprecation warnings have been removed in Visual Studio 2017. +> [!NOTE] +> Microsoft recommends the MFC Unicode libraries for all new development.\ +> The MBCS libraries were deprecated in Visual Studio 2013 and Visual Studio 2015. This is no longer the case.\ +> Starting with Visual Studio 2017, the MBCS libraries are no longer deprecated and don't generate deprecation warnings. ## MFC Support for Unicode Strings @@ -51,13 +54,13 @@ These library, debugger, and DLL files are used to support Unicode in MFC: (*version* represents the version number of the file; for example, '140' means version 14.0.) -`CString` is based on the `TCHAR` data type. If the symbol `_UNICODE` is defined for a build of your program, `TCHAR` is defined as type **`wchar_t`**, a 16-bit character encoding type. Otherwise, `TCHAR` is defined as **`char`**, the normal 8-bit character encoding. Therefore, under Unicode, a `CString` is composed of 16-bit characters. Without Unicode, it is composed of characters of type **`char`**. +`CString` is based on the `TCHAR` data type. If the symbol `_UNICODE` is defined for a build of your program, `TCHAR` is defined as type **`wchar_t`**, a 16-bit character encoding type. Otherwise, `TCHAR` is defined as **`char`**, the normal 8-bit character encoding. Therefore, under Unicode, a `CString` is composed of 16-bit characters. Without Unicode, it's composed of characters of type **`char`**. To complete Unicode programming of your application, you must also: - Use the `_T` macro to conditionally code literal strings to be portable to Unicode. -- When you pass strings, pay attention to whether function arguments require a length in characters or a length in bytes. The difference is important if you are using Unicode strings. +- When you pass strings, pay attention to whether function arguments require a length in characters or a length in bytes. The difference is important if you're using Unicode strings. - Use portable versions of the C run-time string-handling functions. @@ -77,9 +80,9 @@ The [Run-Time Library Reference](../c-runtime-library/c-run-time-library-referen The class library is also enabled for multibyte character sets, but only for double-byte character sets (DBCS). -In a multibyte character set, a character can be one or two bytes wide. If it is two bytes wide, its first byte is a special "lead byte" that is chosen from a particular range, depending on which code page is in use. Taken together, the lead and "trail bytes" specify a unique character encoding. +In a multibyte character set, a character can be one or 2 bytes wide. If it's 2 bytes wide, its first byte is a special "lead byte" that is chosen from a particular range, depending on which code page is in use. Taken together, the lead and "trail bytes" specify a unique character encoding. -If the symbol `_MBCS` is defined for a build of your program, type `TCHAR`, on which `CString` is based, maps to **`char`**. It is up to you to determine which bytes in a `CString` are lead bytes and which are trail bytes. The C run-time library supplies functions to help you determine this. +If the symbol `_MBCS` is defined for a build of your program, type `TCHAR`, on which `CString` is based, maps to **`char`**. It's up to you to determine which bytes in a `CString` are lead bytes and which are trail bytes. The C run-time library supplies functions to help you determine this. Under DBCS, a given string can contain all single-byte ANSI characters, all double-byte characters, or a combination of the two. These possibilities require special care in parsing strings. This includes `CString` objects. diff --git a/docs/atl/adding-a-control-atl-tutorial-part-2.md b/docs/atl/adding-a-control-atl-tutorial-part-2.md index bc613dd306..64913399d1 100644 --- a/docs/atl/adding-a-control-atl-tutorial-part-2.md +++ b/docs/atl/adding-a-control-atl-tutorial-part-2.md @@ -109,7 +109,7 @@ Now you can build the control to see it in action. Next, you'll add a custom property to the control. -[Back to Step 1](../atl/creating-the-project-atl-tutorial-part-1.md) | [On to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) +[Back to Step 1](../atl/creating-the-project-atl-tutorial-part-1.md) \| [On to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) ## See also diff --git a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md index 2422ad5958..77ab6f873a 100644 --- a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md +++ b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md @@ -142,7 +142,7 @@ The **Apply** button is initially disabled. Start typing a value in the **Sides* Next, you will put your control on a Web page. -[Back to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) | [On to Step 7](../atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md) +[Back to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) \| [On to Step 7](../atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md) ## See also diff --git a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md index 5ddcc5edb6..eae5f195dd 100644 --- a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md +++ b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md @@ -57,7 +57,7 @@ The `get_Sides` method returns the current value of the `Sides` property through You now have a property called `Sides`. In the next step, you will change the drawing code to use it. -[Back to Step 2](../atl/adding-a-control-atl-tutorial-part-2.md) | [On to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) +[Back to Step 2](../atl/adding-a-control-atl-tutorial-part-2.md) \| [On to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) ## See also diff --git a/docs/atl/adding-an-event-atl-tutorial-part-5.md b/docs/atl/adding-an-event-atl-tutorial-part-5.md index 7e5f75567b..18306b8df0 100644 --- a/docs/atl/adding-an-event-atl-tutorial-part-5.md +++ b/docs/atl/adding-an-event-atl-tutorial-part-5.md @@ -149,7 +149,7 @@ Now try out your events. Build the control and start the ActiveX Control Test Co Next, you will add a property page. -[Back to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) | [On to Step 6](../atl/adding-a-property-page-atl-tutorial-part-6.md) +[Back to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) \| [On to Step 6](../atl/adding-a-property-page-atl-tutorial-part-6.md) ## See also diff --git a/docs/atl/atl-control-containment-faq.yml b/docs/atl/atl-control-containment-faq.yml index 48bacac41c..51c1ecd623 100644 --- a/docs/atl/atl-control-containment-faq.yml +++ b/docs/atl/atl-control-containment-faq.yml @@ -5,7 +5,7 @@ metadata: ms.date: "11/04/2016" helpviewer_keywords: ["hosting controls using ATL", "ActiveX control containers [C++], ATL control hosting", "ATL, hosting ActiveX controls", "ActiveX controls [C++], hosting", "controls [ATL]"] ms.assetid: d4bdfbe0-82ca-4f2f-bb95-cb89bdcc9b53 - + ms.topic: faq title: ATL Control Containment FAQ summary: | @@ -119,4 +119,4 @@ additionalContent: | [AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic)
[AtlAxCreateControlLicEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)
[CAxWindow2T Class](../atl/reference/caxwindow2t-class.md)
- [IAxWinHostWindowLic Interface](../atl/reference/iaxwinhostwindowlic-interface.md) \ No newline at end of file + [IAxWinHostWindowLic Interface](../atl/reference/iaxwinhostwindowlic-interface.md) diff --git a/docs/atl/atl-utilities-reference.md b/docs/atl/atl-utilities-reference.md index 1fe2da4303..b332716189 100644 --- a/docs/atl/atl-utilities-reference.md +++ b/docs/atl/atl-utilities-reference.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: ATL utilities reference" title: "ATL utilities reference" +description: "Learn more about: ATL utilities reference" ms.date: "11/04/2016" -ms.assetid: dd8a2888-34f4-461e-9bf4-834218f9b95b --- # ATL utilities reference @@ -47,8 +46,7 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl | [AtlIsUnsafeUrlChar](../atl/reference/atl-http-utility-functions.md#atlisunsafeurlchar) | Call this function to find out whether a character is safe for use in a URL. | | [AtlUnescapeUrl](../atl/reference/atl-http-utility-functions.md#atlunescapeurl) | Call this function to convert escaped characters back to their original values. | | [SystemTimeToHttpDate](../atl/reference/atl-http-utility-functions.md#systemtimetohttpdate) | Call this function to convert a system time to a string in a format suitable for using in HTTP headers. | -| [ATLPath::AddBackslash](../atl/reference/atl-path-functions.md#addbackslash) | This function is an overloaded wrapper for [PathAddBackslash](/windows/desktop/api/shlwapi/nf-shlwapi-pathaddbackslasha | -| ). | +| [ATLPath::AddBackslash](../atl/reference/atl-path-functions.md#addbackslash) | This function is an overloaded wrapper for [PathAddBackslash](/windows/win32/api/shlwapi/nf-shlwapi-pathaddbackslasha). | | [ATLPath::AddExtension](../atl/reference/atl-path-functions.md#addextension) | This function is an overloaded wrapper for [PathAddExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathaddextensionw). | | [ATLPath::Append](../atl/reference/atl-path-functions.md#append) | This function is an overloaded wrapper for [PathAppend](/windows/win32/api/shlwapi/nf-shlwapi-pathappendw). | | [ATLPath::BuildRoot](../atl/reference/atl-path-functions.md#buildroot) | This function is an overloaded wrapper for [PathBuildRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathbuildrootw). | @@ -87,5 +85,5 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl ## See also -[Concepts](../atl/active-template-library-atl-concepts.md)
+[Concepts](../atl/active-template-library-atl-concepts.md)\ [ATL COM desktop components](../atl/atl-com-desktop-components.md) diff --git a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md index f84b417b34..ae8149664e 100644 --- a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md +++ b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md @@ -151,7 +151,7 @@ After adding `FireViewChange`, rebuild and try the control again in the ActiveX In the next step, you will add an event. -[Back to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) | [On to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) +[Back to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) \| [On to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) ## See also diff --git a/docs/atl/object-safety-classes.md b/docs/atl/object-safety-classes.md index 29b2fbdcae..8021fd778b 100644 --- a/docs/atl/object-safety-classes.md +++ b/docs/atl/object-safety-classes.md @@ -1,6 +1,6 @@ --- description: "Learn more about: Object Safety Classes" -title: "Object Safety Classes (ATL)| Microsoft Docs" +title: Object Safety Classes (ATL) ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["safety classes", "object safety classes"] diff --git a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md index 9bfba0d873..14db4bbf4c 100644 --- a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md +++ b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md @@ -15,30 +15,30 @@ In this step, you add functionality to the control and script the Web page to re ### To add control features -1. Open PolyCtl.cpp and replace the following code: - - ```cpp - if (PtInRegion(hRgn, xPos, yPos)) - Fire_ClickIn(xPos, yPos); - else - Fire_ClickOut(xPos, yPos); - ``` - - with - - ```cpp - short temp = m_nSides; - if (PtInRegion(hRgn, xPos, yPos)) - { - Fire_ClickIn(xPos, yPos); - put_Sides(++temp); - } - else - { - Fire_ClickOut(xPos, yPos); - put_Sides(--temp); - } - ``` +Open PolyCtl.cpp and replace the following code: + +```cpp +if (PtInRegion(hRgn, xPos, yPos)) + Fire_ClickIn(xPos, yPos); +else + Fire_ClickOut(xPos, yPos); +``` + +with + +```cpp +short temp = m_nSides; +if (PtInRegion(hRgn, xPos, yPos)) +{ + Fire_ClickIn(xPos, yPos); + put_Sides(++temp); +} +else +{ + Fire_ClickOut(xPos, yPos); + put_Sides(--temp); +} +``` The shape will now add or remove sides depending on where you click. diff --git a/docs/atl/reference/atl-classes.md b/docs/atl/reference/atl-classes.md index 7d62887623..36a3ed3f0d 100644 --- a/docs/atl/reference/atl-classes.md +++ b/docs/atl/reference/atl-classes.md @@ -1,9 +1,8 @@ --- description: "Learn more about: ATL classes and structs" -title: "ATL classes and structs| Microsoft Docs" +title: ATL classes and structs ms.date: "05/03/2018" helpviewer_keywords: ["classes [C++], ATL", "ATL, classes"] -ms.assetid: 7da42e2d-ac84-4506-92bd-502a86d68bdc --- # ATL classes and structs @@ -11,211 +10,211 @@ The Active Template Library (ATL) includes the following classes and structs. To |Class / struct|Description|Header file| |-----------|-----------------|-----------------| -|[ATL_DRAWINFO](../../atl/reference/atl-drawinfo-structure.md)|Contains information used for rendering to various targets, such as a printer, metafile, or ActiveX control.|atlctl.h| -|[_AtlCreateWndData](../../atl/reference/atlcreatewnddata-structure.md)|Contains class instance data in windowing code in ATL.|atlbase.h| -|[_ATL_BASE_MODULE70](../../atl/reference/atl-base-module70-structure.md)|Used by any project that uses ATL.|atlbase.h| -|[_ATL_COM_MODULE70](../../atl/reference/atl-com-module70-structure.md)|Used by COM-related code in ATL.| atlbase.h| -|[_ATL_FUNC_INFO](../../atl/reference/atl-func-info-structure.md)|Contains type information used to describe a method or property on a dispinterface.|atlcom.h| -|[_ATL_MODULE70](../../atl/reference/atl-module70-structure.md)|Contains data used by every ATL module.|atlbase.h| -|[_ATL_WIN_MODULE70](../../atl/reference/atl-win-module70-structure.md)|Used by windowing code in ATL.|atlbase.h| -|[CA2AEX](../../atl/reference/ca2aex-class.md)|This class is used by the string conversion macros CA2TEX and CT2AEX, and the typedef CA2A.|atlconv.h| -|[CA2CAEX](../../atl/reference/ca2caex-class.md)|This class is used by string conversion macros CA2CTEX and CT2CAEX, and the typedef CA2CA.|atlconv.h| -|[CA2WEX](../../atl/reference/ca2wex-class.md)|This class is used by the string conversion macros CA2TEX, CA2CTEX, CT2WEX, and CT2CWEX, and the typedef CA2W.|atlconv.h| -|[CAccessToken](../../atl/reference/caccesstoken-class.md)|This class is a wrapper for an access token.|atlsecurity.h| -|[CAcl](../../atl/reference/cacl-class.md)|This class is a wrapper for an ACL (access-control list) structure.|atlsecurity.h| -|[CAdapt](../../atl/reference/cadapt-class.md)|This template is used to wrap classes that redefine the address-of operator to return something other than the address of the object.|atlcomcli.h| -|[CAtlArray](../../atl/reference/catlarray-class.md)|This class implements an array object.|atlcoll.h| -|[CAtlAutoThreadModule](../../atl/reference/catlautothreadmodule-class.md)|This class implements a thread-pooled, apartment-model COM server.|atlbase.h| -|[CAtlAutoThreadModuleT](../../atl/reference/catlautothreadmodulet-class.md)|This class provides methods for implementing a thread-pooled, apartment-model COM server.|atlbase.h| -|[CAtlBaseModule](../../atl/reference/catlbasemodule-class.md)|This class is instantiated in every ATL project.|atlcore.h| -|[CAtlComModule](../../atl/reference/catlcommodule-class.md)|This class implements a COM server module.|atlbase.h| -|[CAtlDebugInterfacesModule](../../atl/reference/catldebuginterfacesmodule-class.md)|This class provides support for debugging interfaces.|atlbase.h| -|[CAtlDllModuleT](../../atl/reference/catldllmodulet-class.md)|This class represents the module for a DLL.|atlbase.h| -|[CAtlException](../../atl/reference/catlexception-class.md)|This class defines an ATL exception.|atlexcept.h| -|[CAtlExeModuleT](../../atl/reference/catlexemodulet-class.md)|This class represents the module for an application.|atlbase.h| -|[CAtlFile](../../atl/reference/catlfile-class.md)|This class provides a thin wrapper around the Windows file-handling API.|atlfile.h| -|[CAtlFileMapping](../../atl/reference/catlfilemapping-class.md)|This class represents a memory-mapped file, adding a cast operator to the methods of [CAtlFileMappingBase](../../atl/reference/catlfilemappingbase-class.md).|atlfile.h| -|[CAtlFileMappingBase](../../atl/reference/catlfilemappingbase-class.md)|This class represents a memory-mapped file.|atlfile.h| -|[CAtlList](../../atl/reference/catllist-class.md)|This class provides methods for creating and managing a list object.|atlcoll.h| -|[CAtlMap](../../atl/reference/catlmap-class.md)|This class provides methods for creating and managing a map object.|atlcoll.h| -|[CAtlModule](../../atl/reference/catlmodule-class.md)|This class provides methods used by several ATL module classes.|atlbase.h| -|[CAtlModuleT](../../atl/reference/catlmodulet-class.md)|This class implements an ATL module.|atlbase.h| -|[CAtlPreviewCtrlImpl](../../atl/reference/catlpreviewctrlimpl-class.md)|This class is an ATL implementation of a window that is placed on a host window provided by the Shell for Rich Preview.|atlpreviewctrlimpl.h| -|[CAtlServiceModuleT](../../atl/reference/catlservicemodulet-class.md)|This class implements a service.|atlbase.h| -|[CAtlTemporaryFile](../../atl/reference/catltemporaryfile-class.md)|This class provides methods for the creation and use of a temporary file.|atlfile.h| -|[CAtlTransactionManager](../../atl/reference/catltransactionmanager-class.md)|This class provides a wrapper to Kernel Transaction Manager (KTM) functions.|atltransactionmanager.h| -|[CAtlWinModule](../../atl/reference/catlwinmodule-class.md)|This class provides support for ATL windowing components.|atlbase.h| -|[CAutoPtr](../../atl/reference/cautoptr-class.md)|This class represents a smart pointer object.|atlbase.h| -|[CAutoPtrArray](../../atl/reference/cautoptrarray-class.md)|This class provides methods useful when constructing an array of smart pointers.|atlbase.h| -|[CAutoPtrElementTraits](../../atl/reference/cautoptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers.|atlcoll.h| -|[CAutoPtrList](../../atl/reference/cautoptrlist-class.md)|This class provides methods useful when constructing a list of smart pointers.|atlcoll.h| -|[CAutoVectorPtr](../../atl/reference/cautovectorptr-class.md)|This class represents a smart pointer object using vector new and delete operators.|atlbase.h| -|[CAutoVectorPtrElementTraits](../../atl/reference/cautovectorptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers using vector new and delete operators.|atlcoll.h| -|[CAxDialogImpl](../../atl/reference/caxdialogimpl-class.md)|This class implements a dialog box (modal or modeless) that hosts ActiveX controls.|atlwin.h| -|[CAxWindow](../../atl/reference/caxwindow-class.md)|This class provides methods for manipulating a window hosting an ActiveX control.|atlwin.h| -|[CAxWindow2T](../../atl/reference/caxwindow2t-class.md)|This class provides methods for manipulating a window that hosts an ActiveX control and also has support for hosting licensed ActiveX controls.|atlwin.h| -|[CBindStatusCallback](../../atl/reference/cbindstatuscallback-class.md)|This class implements the `IBindStatusCallback` interface.|atlctl.h| -|[CComAggObject](../../atl/reference/ccomaggobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) for an aggregated object.|atlcom.h| -|[CComAllocator](../../atl/reference/ccomallocator-class.md)|This class provides methods for managing memory using COM memory routines.|atlbase.h| -|[CComApartment](../../atl/reference/ccomapartment-class.md)|This class provides support for managing an apartment in a thread-pooled EXE module.|atlbase.h| -|[CComAutoCriticalSection](../../atl/reference/ccomautocriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|atlcore.h| -|[CComAutoThreadModule](../../atl/reference/ccomautothreadmodule-class.md)|As of ATL 7.0, `CComAutoThreadModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|atlbase.h| -|[CComBSTR](../../atl/reference/ccombstr-class.md)|This class is a wrapper for BSTRs.|atlbase.h| -|[CComCachedTearOffObject](../../atl/reference/ccomcachedtearoffobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) for a tear-off interface.|atlcom.h| -|[CComClassFactory](../../atl/reference/ccomclassfactory-class.md)|This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface.|atlcom.h| -|[CComClassFactory2](../../atl/reference/ccomclassfactory2-class.md)|This class implements the [IClassFactory2](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2) interface.|atlcom.h| -|[CComClassFactoryAutoThread](../../atl/reference/ccomclassfactoryautothread-class.md)|This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface and allows objects to be created in multiple apartments.|atlcom.h| -|[CComClassFactorySingleton](../../atl/reference/ccomclassfactorysingleton-class.md)|This class derives from [CComClassFactory](../../atl/reference/ccomclassfactory-class.md) and uses [CComObjectGlobal](../../atl/reference/ccomobjectglobal-class.md) to construct a single object.|atlcom.h| -|[CComCoClass](../../atl/reference/ccomcoclass-class.md)|This class provides methods for creating instances of a class and obtaining its properties.|atlcom.h| -|[CComCompositeControl](../../atl/reference/ccomcompositecontrol-class.md)|This class provides the methods required to implement a composite control.|atlctl.h| -|[CComContainedObject](../../atl/reference/ccomcontainedobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) by delegating to the owner object's `IUnknown`.|atlcom.h| -|[CComControl](../../atl/reference/ccomcontrol-class.md)|This class provides methods for creating and managing ATL controls.|atlctl.h| -|[CComControlBase](../../atl/reference/ccomcontrolbase-class.md)|This class provides methods for creating and managing ATL controls.|atlctl.h| -|[CComCriticalSection](../../atl/reference/ccomcriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|atlcore.h| -|[CComCritSecLock](../../atl/reference/ccomcritseclock-class.md)|This class provides methods for locking and unlocking a critical section object.|atlbase.h| -|[CComCurrency](../../atl/reference/ccomcurrency-class.md)|This class has methods and operators for creating and managing a CURRENCY object.|atlcur.h| -|[CComDynamicUnkArray](../../atl/reference/ccomdynamicunkarray-class.md)|This class stores an array of `IUnknown` pointers.|atlcom.h| -|[CComEnum](../../atl/reference/ccomenum-class.md)|This class defines a COM enumerator object based on an array.|atlcom.h| -|[CComEnumImpl](../../atl/reference/ccomenumimpl-class.md)|This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array.|atlcom.h| -|[CComEnumOnSTL](../../atl/reference/ccomenumonstl-class.md)|This class defines a COM enumerator object based on a C++ Standard Library collection.|atlcom.h| -|[CComFakeCriticalSection](../../atl/reference/ccomfakecriticalsection-class.md)|This class provides the same methods as [CComCriticalSection](../../atl/reference/ccomcriticalsection-class.md) but does not provide a critical section.|atlcore.h| -|[CComGITPtr](../../atl/reference/ccomgitptr-class.md)|This class provides methods for dealing with interface pointers and the global interface table (GIT).|atlbase.h| -|[CComHeap](../../atl/reference/ccomheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions.|ATLComMem.h| -|[CComHeapPtr](../../atl/reference/ccomheapptr-class.md)|A smart pointer class for managing heap pointers.|atlbase.h| -|[CComModule](../../atl/reference/ccommodule-class.md)|As of ATL 7.0, `CComModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|atlbase.h| -|[CComMultiThreadModel](../../atl/reference/ccommultithreadmodel-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable.|atlbase.h| -|[CComMultiThreadModelNoCS](../../atl/reference/ccommultithreadmodelnocs-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable, without critical section locking or unlocking functionality.|atlbase.h| -|[CComObject](../../atl/reference/ccomobject-class.md)|This class implements `IUnknown` for a nonaggregated object.|atlcom.h| -|[CComObjectGlobal](../../atl/reference/ccomobjectglobal-class.md)|This class manages a reference count on the module containing your `Base` object.|atlcom.h| -|[CComObjectNoLock](../../atl/reference/ccomobjectnolock-class.md)|This class implements `IUnknown` for a nonaggregated object, but does not increment the module lock count in the constructor.|atlcom.h| -|[CComObjectRoot](../../atl/reference/ccomobjectroot-class.md)|This typedef of [CComObjectRootEx](../../atl/reference/ccomobjectrootex-class.md) is templatized on the default threading model of the server.|atlcom.h| -|[CComObjectRootEx](../../atl/reference/ccomobjectrootex-class.md)|This class provides methods to handle object reference count management for both nonaggregated and aggregated objects.|atlcom.h| -|[CComObjectStack](../../atl/reference/ccomobjectstack-class.md)|This class creates a temporary COM object and provides it with a skeletal implementation of `IUnknown`.|atlcom.h| -|[CComPolyObject](../../atl/reference/ccompolyobject-class.md)|This class implements `IUnknown` for an aggregated or nonaggregated object.|atlcom.h| -|[CComPtr](../../atl/reference/ccomptr-class.md)|A smart pointer class for managing COM interface pointers.|atlcomcli.h| -|[CComPtrBase](../../atl/reference/ccomptrbase-class.md)|This class provides a basis for smart pointer classes using COM-based memory routines.|atlcomcli.h| -|[CComQIPtr](../../atl/reference/ccomqiptr-class.md)|A smart pointer class for managing COM interface pointers.|atlcomcli.h| -|[CComQIPtrElementTraits](../../atl/reference/ccomqiptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of COM interface pointers.|atlcoll.h| -|[CComSafeArray](../../atl/reference/ccomsafearray-class.md)|This class is a wrapper for the `SAFEARRAY Data Type` structure.|atlsafe.h| -|[CComSafeArrayBound](../../atl/reference/ccomsafearraybound-class.md)|This class is a wrapper for a `SAFEARRAYBOUND` structure.|atlsafe.h| -|[CComSimpleThreadAllocator](../../atl/reference/ccomsimplethreadallocator-class.md)|This class manages thread selection for the class [CComAutoThreadModule](../../atl/reference/ccomautothreadmodule-class.md).|atlbase.h| -|[CComSingleThreadModel](../../atl/reference/ccomsinglethreadmodel-class.md)|This class provides methods for incrementing and decrementing the value of a variable.|atlbase.h| -|[CComTearOffObject](../../atl/reference/ccomtearoffobject-class.md)|This class implements a tear-off interface.|atlcom.h| -|[CComUnkArray](../../atl/reference/ccomunkarray-class.md)|This class stores `IUnknown` pointers and is designed to be used as a parameter to the [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) template class.|atlcom.h| -|[CComVariant](../../atl/reference/ccomvariant-class.md)|This class wraps the VARIANT type, providing a member indicating the type of data stored.|atlcomcli.h| -|[CContainedWindowT](../../atl/reference/ccontainedwindowt-class.md)|This class implements a window contained within another object.|atlwin.h| -|[CCRTAllocator](../../atl/reference/ccrtallocator-class.md)|This class provides methods for managing memory using CRT memory routines.|atlcore.h| -|[CCRTHeap](../../atl/reference/ccrtheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the CRT heap functions.|atlmem.h| -|[CDacl](../../atl/reference/cdacl-class.md)|This class is a wrapper for a DACL (discretionary access-control list) structure.|atlsecurity.h| -|[CDebugReportHook Class](../../atl/reference/cdebugreporthook-class.md)|Use this class to send debug reports to a named pipe.|atlutil.h| -|[CDefaultCharTraits](../../atl/reference/cdefaultchartraits-class.md)|This class provides two static functions for converting characters between uppercase and lowercase.|atlcoll.h| -|[CDefaultCompareTraits](../../atl/reference/cdefaultcomparetraits-class.md)|This class provides default element comparison functions.|atlcoll.h| -|[CDefaultElementTraits](../../atl/reference/cdefaultelementtraits-class.md)|This class provides default methods and functions for a collection class.|atlcoll.h| -|[CDefaultHashTraits](../../atl/reference/cdefaulthashtraits-class.md)|This class provides a static function for calculating hash values.|atlcoll.h| -|[CDialogImpl](../../atl/reference/cdialogimpl-class.md)|This class provides methods for creating a modal or modeless dialog box.|atlwin.h| -|[CDynamicChain](../../atl/reference/cdynamicchain-class.md)|This class provides methods supporting the dynamic chaining of message maps.|atlwin.h| -|[CElementTraits](../../atl/reference/celementtraits-class.md)|This class is used by collection classes to provide methods and functions for moving, copying, comparison, and hashing operations.|atlcoll.h| -|[CElementTraitsBase](../../atl/reference/celementtraitsbase-class.md)|This class provides default copy and move methods for a collection class.|atlcoll.h| -|[CFirePropNotifyEvent](../../atl/reference/cfirepropnotifyevent-class.md)|This class provides methods for notifying the container's sink regarding control property changes.|atlctl.h| -|[CGlobalHeap](../../atl/reference/cglobalheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 global heap functions.|atlmem.h| -|[CHandle](../../atl/reference/chandle-class.md)|This class provides methods for creating and using a handle object.|atlbase.h| -|[CHeapPtr](../../atl/reference/cheapptr-class.md)|A smart pointer class for managing heap pointers.|atlcore.h| -|[CHeapPtrBase](../../atl/reference/cheapptrbase-class.md)|This class forms the basis for several smart heap pointer classes.|atlcore.h| -|[CHeapPtrElementTraits Class](../../atl/reference/cheapptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of heap pointers.|atlcoll.h| -|[CHeapPtrList](../../atl/reference/cheapptrlist-class.md)|This class provides methods useful when constructing a list of heap pointers.|atlcoll.h| -|[CImage](../../atl-mfc-shared/reference/cimage-class.md)|Provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats.|atlimage.h| -|[CInterfaceArray](../../atl/reference/cinterfacearray-class.md)|This class provides methods useful when constructing an array of COM interface pointers.|atlcoll.h| -|[CInterfaceList](../../atl/reference/cinterfacelist-class.md)|This class provides methods useful when constructing a list of COM interface pointers.|atlcoll.h| -|[CLocalHeap](../../atl/reference/clocalheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 local heap functions.|atlmem.h| -|[CMessageMap](../../atl/reference/cmessagemap-class.md)|This class allows an object's message maps to be accessed by another object.|atlwin.h| -|[CNonStatelessWorker Class](../../atl/reference/cnonstatelessworker-class.md)|Receives requests from a thread pool and passes them on to a worker object that is created and destroyed on each request.|atlutil.h| -|[CNoWorkerThread Class](../../atl/reference/cnoworkerthread-class.md)|Use this class as the argument for the `MonitorClass` template parameter cache classes if you want to disable dynamic cache maintenance.|atlutil.h| -|[CPathT Class](../../atl/reference/cpatht-class.md)|This class represents a path.|atlpath.h| -|[CPrimitiveElementTraits](../../atl/reference/cprimitiveelementtraits-class.md)|This class provides default methods and functions for a collection class composed of primitive data types.|atlcoll.h| -|[CPrivateObjectSecurityDesc](../../atl/reference/cprivateobjectsecuritydesc-class.md)|This class represents a private object security descriptor object.|atlsecurity.h| -|[CRBMap](../../atl/reference/crbmap-class.md)|This class represents a mapping structure, using a Red-Black binary tree.|atlcoll.h| -|[CRBMultiMap](../../atl/reference/crbmultimap-class.md)|This class represents a mapping structure that allows each key to be associated with more than one value, using a Red-Black binary tree.|atlcoll.h| -|[CRBTree](../../atl/reference/crbtree-class.md)|This class provides methods for creating and utilizing a Red-Black tree.|atlcoll.h| -|[CRegKey](../../atl/reference/cregkey-class.md)|This class provides methods for manipulating entries in the system registry.|atlbase.h| -|[CRTThreadTraits](../../atl/reference/crtthreadtraits-class.md)|This class provides the creation function for a CRT thread. Use this class if the thread will use CRT functions.|atlbase.h| -|[CSacl](../../atl/reference/csacl-class.md)|This class is a wrapper for a SACL (system access-control list) structure.|atlsecurity.h| -|[CSecurityAttributes](../../atl/reference/csecurityattributes-class.md)|This class is a thin wrapper for the `SECURITY_ATTRIBUTES` structure.|atlsecurity.h| -|[CSecurityDesc](../../atl/reference/csecuritydesc-class.md)|This class is a wrapper for the `SECURITY_DESCRIPTOR` structure.|atlsecurity.h| -|[CSid](../../atl/reference/csid-class.md)|This class is a wrapper for a `SID` (security identifier) structure.|atlsecurity.h| -|[CSimpleArray](../../atl/reference/csimplearray-class.md)|This class provides methods for managing a simple array.|atlsimpcoll.h| -|[CSimpleArrayEqualHelper](../../atl/reference/csimplearrayequalhelper-class.md)|This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class.|atlsimpcoll.h| -|[CSimpleArrayEqualHelperFalse](../../atl/reference/csimplearrayequalhelperfalse-class.md)|This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class.|atlsimpcoll.h| -|[CSimpleDialog](../../atl/reference/csimpledialog-class.md)|This class implements a basic modal dialog box.|atlwin.h| -|[CSimpleMap](../../atl/reference/csimplemap-class.md)|This class provides support for a simple mapping array.|atlsimpcoll.h| -|[CSimpleMapEqualHelper](../../atl/reference/csimplemapequalhelper-class.md)|This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class.|atlsimpcoll.h| -|[CSimpleMapEqualHelperFalse](../../atl/reference/csimplemapequalhelperfalse-class.md)|This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class.|atlsimpcoll.h| -|[CSnapInItemImpl](../../atl/reference/csnapinitemimpl-class.md)|This class provides methods for implementing a snap-in node object.|atlsnap.h| -|[CSnapInPropertyPageImpl](../../atl/reference/csnapinpropertypageimpl-class.md)|This class provides methods for implementing a snap-in property page object.|atlsnap.h| -|[CStockPropImpl](../../atl/reference/cstockpropimpl-class.md)|This class provides methods for supporting stock property values.|atlctl.h| -|[CStringElementTraits](../../atl/reference/cstringelementtraits-class.md)|This class provides static functions used by collection classes storing `CString` objects.|cstringt.h| -|[CStringElementTraitsI](../../atl/reference/cstringelementtraitsi-class.md)|This class provides static functions related to strings stored in collection class objects. It is similar to [CStringElementTraits](../../atl/reference/cstringelementtraits-class.md), but performs case-insensitive comparisons.|atlcoll.h| -|[CStringRefElementTraits](../../atl/reference/cstringrefelementtraits-class.md)|This class provides static functions related to strings stored in collection class objects. The string objects are dealt with as references.|atlcoll.h| -|[CThreadPool Class](../../atl/reference/cthreadpool-class.md)|This class provides a pool of worker threads that process a queue of work items.|atlutil.h| -|[CTokenGroups](../../atl/reference/ctokengroups-class.md)|This class is a wrapper for the `TOKEN_GROUPS` structure.|atlsecurity.h| -|[CTokenPrivileges](../../atl/reference/ctokenprivileges-class.md)|This class is a wrapper for the `TOKEN_PRIVILEGES` structure.|atlsecurity.h| -|[CUrl Class](../../atl/reference/curl-class.md)|This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch.|atlutil.h| -|[CW2AEX](../../atl/reference/cw2aex-class.md)|This class is used by the string conversion macros CT2AEX, CW2TEX, CW2CTEX, and CT2CAEX, and the typedef CW2A.|atlconv.h| -|[CW2CWEX](../../atl/reference/cw2cwex-class.md)|This class is used by the string conversion macros CW2CTEX and CT2CWEX, and the typedef CW2CW.|atlconv.h| -|[CW2WEX](../../atl/reference/cw2wex-class.md)|This class is used by the string conversion macros CW2TEX and CT2WEX, and the typedef CW2W.|atlconv.h| -|[CWin32Heap](../../atl/reference/cwin32heap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 heap allocation functions.|atlmem.h| -|[CWindow](../../atl/reference/cwindow-class.md)|This class provides methods for manipulating a window.|atlwin.h| -|[CWindowImpl](../../atl/reference/cwindowimpl-class.md)|This class provides methods for creating or subclassing a window.|atlwin.h| -|[CWinTraits](../../atl/reference/cwintraits-class.md)|This class provides a method for standardizing the styles used when creating a window object.|atlwin.h| -|[CWinTraitsOR](../../atl/reference/cwintraitsor-class.md)|This class provides a method for standardizing the styles used when creating a window object.|atlwin.h| -|[CWndClassInfo](../../atl/reference/cwndclassinfo-class.md)|This class provides methods for registering information for a window class.|atlwin.h| -|[CWorkerThread Class](../../atl/reference/cworkerthread-class.md)|This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled.|atlutil.h| -|[IAtlAutoThreadModule](../../atl/reference/iatlautothreadmodule-class.md)|This class represents an interface to a `CreateInstance` method.|atlbase.h| -|[IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md)|This class represents the interface to a memory manager.|atlmem.h| -|[IAxWinAmbientDispatch](../../atl/reference/iaxwinambientdispatch-interface.md)|This interface provides methods for specifying characteristics of the hosted control or container.|atlbase.h, ATLIFace.h| -|[IAxWinAmbientDispatchEx](../../atl/reference/iaxwinambientdispatchex-interface.md)|This interface implements supplemental ambient properties for a hosted control.|atlbase.h, ATLIFace.h| -|[IAxWinHostWindow](../../atl/reference/iaxwinhostwindow-interface.md)|This interface provides methods for manipulating a control and its host object.|atlbase.h, ATLIFace.h| -|[IAxWinHostWindowLic](../../atl/reference/iaxwinhostwindowlic-interface.md)|This interface provides methods for manipulating a licensed control and its host object.|atlbase.h, ATLIFace.h| -|[ICollectionOnSTLImpl](../../atl/reference/icollectiononstlimpl-class.md)|This class provides methods used by a collection class.|atlcom.h| -|[IConnectionPointContainerImpl](../../atl/reference/iconnectionpointcontainerimpl-class.md)|This class implements a connection point container to manage a collection of [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) objects.|atlcom.h| -|[IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md)|This class implements a connection point.|atlcom.h| -|[IDataObjectImpl](../../atl/reference/idataobjectimpl-class.md)|This class provides methods for supporting Uniform Data Transfer and managing connections.|atlctl.h| -|[IDispatchImpl](../../atl/reference/idispatchimpl-class.md)|This class provides a default implementation for the `IDispatch` portion of a dual interface.|atlcom.h| -|[IDispEventImpl](../../atl/reference/idispeventimpl-class.md)|This class provides implementations of the `IDispatch` methods.|atlcom.h| -|[IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md)|This class provides implementations of the `IDispatch` methods, without getting type information from a type library.|atlcom.h| -|[IDocHostUIHandlerDispatch](../../atl/reference/idochostuihandlerdispatch-interface.md)|An interface to the Microsoft HTML parsing and rendering engine.|atlbase.h, ATLIFace.h| -|[IEnumOnSTLImpl](../../atl/reference/ienumonstlimpl-class.md)|This class defines an enumerator interface based on a C++ Standard Library collection.|atlcom.h| -|[IObjectSafetyImpl](../../atl/reference/iobjectsafetyimpl-class.md)|This class provides a default implementation of the `IObjectSafety` interface to allow a client to retrieve and set an object's safety levels.|atlctl.h| -|[IObjectWithSiteImpl](../../atl/reference/iobjectwithsiteimpl-class.md)|This class provides methods allowing an object to communicate with its site.|atlcom.h| -|[IOleControlImpl](../../atl/reference/iolecontrolimpl-class.md)|This class provides a default implementation of the `IOleControl` interface and implements `IUnknown`.|atlctl.h| -|[IOleInPlaceActiveObjectImpl](../../atl/reference/ioleinplaceactiveobjectimpl-class.md)|This class provides methods for assisting communication between an in-place control and its container.|atlctl.h| -|[IOleInPlaceObjectWindowlessImpl](../../atl/reference/ioleinplaceobjectwindowlessimpl-class.md)|This class implements `IUnknown` and provides methods that enable a windowless control to receive window messages and to participate in drag-and-drop operations.|atlctl.h| -|[IOleObjectImpl](../../atl/reference/ioleobjectimpl-class.md)|This class implements `IUnknown` and is the principal interface through which a container communicates with a control.|atlctl.h| -|[IPerPropertyBrowsingImpl](../../atl/reference/iperpropertybrowsingimpl-class.md)|This class implements `IUnknown` and allows a client to access the information in an object's property pages.|atlctl.h| -|[IPersistPropertyBagImpl](../../atl/reference/ipersistpropertybagimpl-class.md)|This class implements `IUnknown` and allows an object to save its properties to a client-supplied property bag.|atlcom.h| -|[IPersistStorageImpl](../../atl/reference/ipersiststorageimpl-class.md)|This class implements the [IPersistStorage](/windows/win32/api/objidl/nn-objidl-ipersiststorage) interface.|atlcom.h| -|[IPersistStreamInitImpl](../../atl/reference/ipersiststreaminitimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface.|atlcom.h| -|[IPointerInactiveImpl](../../atl/reference/ipointerinactiveimpl-class.md)|This class implements `IUnknown` and the [IPointerInactive](/windows/win32/api/ocidl/nn-ocidl-ipointerinactive) interface methods.|atlctl.h| -|[IPropertyNotifySinkCP](../../atl/reference/ipropertynotifysinkcp-class.md)|This class exposes the [IPropertyNotifySink](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) interface as an outgoing interface on a connectable object.|atlctl.h| -|[IPropertyPage2Impl](../../atl/reference/ipropertypage2impl-class.md)|This class implements `IUnknown` and inherits the default implementation of [IPropertyPageImpl](../../atl/reference/ipropertypageimpl-class.md).|atlctl.h| -|[IPropertyPageImpl](../../atl/reference/ipropertypageimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IPropertyPage](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) interface.|atlctl.h| -|[IProvideClassInfo2Impl](../../atl/reference/iprovideclassinfo2impl-class.md)|This class provides a default implementation of the [IProvideClassInfo](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo) and [IProvideClassInfo2](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo2) methods.|atlcom.h| -|[IQuickActivateImpl](../../atl/reference/iquickactivateimpl-class.md)|This class combines containers' control initialization into a single call.|atlctl.h| -|[IRunnableObjectImpl](../../atl/reference/irunnableobjectimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IRunnableObject](/windows/win32/api/objidl/nn-objidl-irunnableobject) interface.|atlctl.h| -|[IServiceProviderImpl](../../atl/reference/iserviceproviderimpl-class.md)|This class provides a default implementation of the `IServiceProvider` interface.|atlcom.h| -|[ISpecifyPropertyPagesImpl](../../atl/reference/ispecifypropertypagesimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [ISpecifyPropertyPages](/windows/win32/api/ocidl/nn-ocidl-ispecifypropertypages) interface.|atlcom.h| -|[ISupportErrorInfoImpl](../../atl/reference/isupporterrorinfoimpl-class.md)|This class provides a default implementation of the `ISupportErrorInfo Interface` interface and can be used when only a single interface generates errors on an object.|atlcom.h| -|[IThreadPoolConfig Interface](../../atl/reference/ithreadpoolconfig-interface.md)|This interface provides methods for configuring a thread pool.|atlutil.h| -|[IViewObjectExImpl](../../atl/reference/iviewobjecteximpl-class.md)|This class implements `IUnknown` and provides default implementations of the [IViewObject](/windows/win32/api/oleidl/nn-oleidl-iviewobject), [IViewObject2](/windows/win32/api/oleidl/nn-oleidl-iviewobject2), and [IViewObjectEx](/windows/win32/api/ocidl/nn-ocidl-iviewobjectex) interfaces.|atlctl.h| -|[IWorkerThreadClient Interface](../../atl/reference/iworkerthreadclient-interface.md)|`IWorkerThreadClient` is the interface implemented by clients of the [CWorkerThread](../../atl/reference/cworkerthread-class.md) class.|atlutil.h| -|[_U_MENUorID](../../atl/reference/u-menuorid-class.md)|This class provides wrappers for `CreateWindow` and `CreateWindowEx`.|atlwin.h| -|[_U_RECT](../../atl/reference/u-rect-class.md)|This argument adapter class allows either `RECT` pointers or references to be passed to a function that is implemented in terms of pointers.|atlwin.h| -|[_U_STRINGorID](../../atl/reference/u-stringorid-class.md)|This argument adapter class allows either resource names (LPCTSTRs) or resource IDs (UINTs) to be passed to a function without requiring the caller to convert the ID to a string using the MAKEINTRESOURCE macro.|atlwin.h| -|[Win32ThreadTraits](../../atl/reference/win32threadtraits-class.md)|This class provides the creation function for a Windows thread. Use this class if the thread will not use CRT functions.|atlbase.h| +|[`ATL_DRAWINFO`](../../atl/reference/atl-drawinfo-structure.md)|Contains information used for rendering to various targets, such as a printer, metafile, or ActiveX control.|`atlctl.h`| +|[`_AtlCreateWndData`](../../atl/reference/atlcreatewnddata-structure.md)|Contains class instance data in windowing code in ATL.|`atlbase.h`| +|[`_ATL_BASE_MODULE70`](../../atl/reference/atl-base-module70-structure.md)|Used by any project that uses ATL.|`atlbase.h`| +|[`_ATL_COM_MODULE70`](../../atl/reference/atl-com-module70-structure.md)|Used by COM-related code in ATL.| `atlbase.h`| +|[`_ATL_FUNC_INFO`](../../atl/reference/atl-func-info-structure.md)|Contains type information used to describe a method or property on a dispinterface.|`atlcom.h`| +|[`_ATL_MODULE70`](../../atl/reference/atl-module70-structure.md)|Contains data used by every ATL module.|`atlbase.h`| +|[`_ATL_WIN_MODULE70`](../../atl/reference/atl-win-module70-structure.md)|Used by windowing code in ATL.|`atlbase.h`| +|[`CA2AEX`](../../atl/reference/ca2aex-class.md)|This class is used by the string conversion macros `CA2TEX` and `CT2AEX`, and the typedef `CA2A`.|`atlconv.h`| +|[`CA2CAEX`](../../atl/reference/ca2caex-class.md)|This class is used by string conversion macros `CA2CTEX` and `CT2CAEX`, and the typedef `CA2CA`.|`atlconv.h`| +|[`CA2WEX`](../../atl/reference/ca2wex-class.md)|This class is used by the string conversion macros `CA2TEX`, `CA2CTEX`, `CT2WEX`, and `CT2CWEX`, and the typedef `CA2W`.|`atlconv.h`| +|[`CAccessToken`](../../atl/reference/caccesstoken-class.md)|This class is a wrapper for an access token.|`atlsecurity.h`| +|[`CAcl`](../../atl/reference/cacl-class.md)|This class is a wrapper for an ACL (access-control list) structure.|`atlsecurity.h`| +|[`CAdapt`](../../atl/reference/cadapt-class.md)|This template is used to wrap classes that redefine the address-of operator to return something other than the address of the object.|`atlcomcli.h`| +|[`CAtlArray`](../../atl/reference/catlarray-class.md)|This class implements an array object.|`atlcoll.h`| +|[`CAtlAutoThreadModule`](../../atl/reference/catlautothreadmodule-class.md)|This class implements a thread-pooled, apartment-model COM server.|`atlbase.h`| +|[`CAtlAutoThreadModuleT`](../../atl/reference/catlautothreadmodulet-class.md)|This class provides methods for implementing a thread-pooled, apartment-model COM server.|`atlbase.h`| +|[`CAtlBaseModule`](../../atl/reference/catlbasemodule-class.md)|This class is instantiated in every ATL project.|`atlcore.h`| +|[`CAtlComModule`](../../atl/reference/catlcommodule-class.md)|This class implements a COM server module.|`atlbase.h`| +|[`CAtlDebugInterfacesModule`](../../atl/reference/catldebuginterfacesmodule-class.md)|This class provides support for debugging interfaces.|`atlbase.h`| +|[`CAtlDllModuleT`](../../atl/reference/catldllmodulet-class.md)|This class represents the module for a DLL.|`atlbase.h`| +|[`CAtlException`](../../atl/reference/catlexception-class.md)|This class defines an ATL exception.|`atlexcept.h`| +|[`CAtlExeModuleT`](../../atl/reference/catlexemodulet-class.md)|This class represents the module for an application.|`atlbase.h`| +|[`CAtlFile`](../../atl/reference/catlfile-class.md)|This class provides a thin wrapper around the Windows file-handling API.|`atlfile.h`| +|[`CAtlFileMapping`](../../atl/reference/catlfilemapping-class.md)|This class represents a memory-mapped file, adding a cast operator to the methods of [`CAtlFileMappingBase`](../../atl/reference/catlfilemappingbase-class.md).|`atlfile.h`| +|[`CAtlFileMappingBase`](../../atl/reference/catlfilemappingbase-class.md)|This class represents a memory-mapped file.|`atlfile.h`| +|[`CAtlList`](../../atl/reference/catllist-class.md)|This class provides methods for creating and managing a list object.|`atlcoll.h`| +|[`CAtlMap`](../../atl/reference/catlmap-class.md)|This class provides methods for creating and managing a map object.|`atlcoll.h`| +|[`CAtlModule`](../../atl/reference/catlmodule-class.md)|This class provides methods used by several ATL module classes.|`atlbase.h`| +|[`CAtlModuleT`](../../atl/reference/catlmodulet-class.md)|This class implements an ATL module.|`atlbase.h`| +|[`CAtlPreviewCtrlImpl`](../../atl/reference/catlpreviewctrlimpl-class.md)|This class is an ATL implementation of a window that is placed on a host window provided by the Shell for Rich Preview.|`atlpreviewctrlimpl`.h| +|[`CAtlServiceModuleT`](../../atl/reference/catlservicemodulet-class.md)|This class implements a service.|`atlbase.h`| +|[`CAtlTemporaryFile`](../../atl/reference/catltemporaryfile-class.md)|This class provides methods for the creation and use of a temporary file.|`atlfile.h`| +|[`CAtlTransactionManager`](../../atl/reference/catltransactionmanager-class.md)|This class provides a wrapper to Kernel Transaction Manager (KTM) functions.|`atltransactionmanager`.h| +|[`CAtlWinModule`](../../atl/reference/catlwinmodule-class.md)|This class provides support for ATL windowing components.|`atlbase.h`| +|[`CAutoPtr`](../../atl/reference/cautoptr-class.md)|This class represents a smart pointer object.|`atlbase.h`| +|[`CAutoPtrArray`](../../atl/reference/cautoptrarray-class.md)|This class provides methods useful when constructing an array of smart pointers.|`atlbase.h`| +|[`CAutoPtrElementTraits`](../../atl/reference/cautoptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers.|`atlcoll.h`| +|[`CAutoPtrList`](../../atl/reference/cautoptrlist-class.md)|This class provides methods useful when constructing a list of smart pointers.|`atlcoll.h`| +|[`CAutoVectorPtr`](../../atl/reference/cautovectorptr-class.md)|This class represents a smart pointer object using vector new and delete operators.|`atlbase.h`| +|[`CAutoVectorPtrElementTraits`](../../atl/reference/cautovectorptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers using vector new and delete operators.|`atlcoll.h`| +|[`CAxDialogImpl`](../../atl/reference/caxdialogimpl-class.md)|This class implements a dialog box (modal or modeless) that hosts ActiveX controls.|`atlwin.h`| +|[`CAxWindow`](../../atl/reference/caxwindow-class.md)|This class provides methods for manipulating a window hosting an ActiveX control.|`atlwin.h`| +|[`CAxWindow2T`](../../atl/reference/caxwindow2t-class.md)|This class provides methods for manipulating a window that hosts an ActiveX control and also has support for hosting licensed ActiveX controls.|`atlwin.h`| +|[`CBindStatusCallback`](../../atl/reference/cbindstatuscallback-class.md)|This class implements the `IBindStatusCallback` interface.|`atlctl.h`| +|[`CComAggObject`](../../atl/reference/ccomaggobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) for an aggregated object.|`atlcom.h`| +|[`CComAllocator`](../../atl/reference/ccomallocator-class.md)|This class provides methods for managing memory using COM memory routines.|`atlbase.h`| +|[`CComApartment`](../../atl/reference/ccomapartment-class.md)|This class provides support for managing an apartment in a thread-pooled EXE module.|`atlbase.h`| +|[`CComAutoCriticalSection`](../../atl/reference/ccomautocriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|`atlcore.h`| +|[`CComAutoThreadModule`](../../atl/reference/ccomautothreadmodule-class.md)|As of ATL 7.0, `CComAutoThreadModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|`atlbase.h`| +|[`CComBSTR`](../../atl/reference/ccombstr-class.md)|This class is a wrapper for BSTRs.|`atlbase.h`| +|[`CComCachedTearOffObject`](../../atl/reference/ccomcachedtearoffobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) for a tear-off interface.|`atlcom.h`| +|[`CComClassFactory`](../../atl/reference/ccomclassfactory-class.md)|This class implements the [`IClassFactory`](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface.|`atlcom.h`| +|[`CComClassFactory2`](../../atl/reference/ccomclassfactory2-class.md)|This class implements the [`IClassFactory2`](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2) interface.|`atlcom.h`| +|[`CComClassFactoryAutoThread`](../../atl/reference/ccomclassfactoryautothread-class.md)|This class implements the [`IClassFactory`](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface and allows objects to be created in multiple apartments.|`atlcom.h`| +|[`CComClassFactorySingleton`](../../atl/reference/ccomclassfactorysingleton-class.md)|This class derives from [`CComClassFactory`](../../atl/reference/ccomclassfactory-class.md) and uses [`CComObjectGlobal`](../../atl/reference/ccomobjectglobal-class.md) to construct a single object.|`atlcom.h`| +|[`CComCoClass`](../../atl/reference/ccomcoclass-class.md)|This class provides methods for creating instances of a class and obtaining its properties.|`atlcom.h`| +|[`CComCompositeControl`](../../atl/reference/ccomcompositecontrol-class.md)|This class provides the methods required to implement a composite control.|`atlctl.h`| +|[`CComContainedObject`](../../atl/reference/ccomcontainedobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) by delegating to the owner object's `IUnknown`.|`atlcom.h`| +|[`CComControl`](../../atl/reference/ccomcontrol-class.md)|This class provides methods for creating and managing ATL controls.|`atlctl.h`| +|[`CComControlBase`](../../atl/reference/ccomcontrolbase-class.md)|This class provides methods for creating and managing ATL controls.|`atlctl.h`| +|[`CComCriticalSection`](../../atl/reference/ccomcriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|`atlcore.h`| +|[`CComCritSecLock`](../../atl/reference/ccomcritseclock-class.md)|This class provides methods for locking and unlocking a critical section object.|`atlbase.h`| +|[`CComCurrency`](../../atl/reference/ccomcurrency-class.md)|This class has methods and operators for creating and managing a `CURRENCY` object.|`atlcur.h`| +|[`CComDynamicUnkArray`](../../atl/reference/ccomdynamicunkarray-class.md)|This class stores an array of `IUnknown` pointers.|`atlcom.h`| +|[`CComEnum`](../../atl/reference/ccomenum-class.md)|This class defines a COM enumerator object based on an array.|`atlcom.h`| +|[`CComEnumImpl`](../../atl/reference/ccomenumimpl-class.md)|This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array.|`atlcom.h`| +|[`CComEnumOnSTL`](../../atl/reference/ccomenumonstl-class.md)|This class defines a COM enumerator object based on a C++ Standard Library collection.|`atlcom.h`| +|[`CComFakeCriticalSection`](../../atl/reference/ccomfakecriticalsection-class.md)|This class provides the same methods as [`CComCriticalSection`](../../atl/reference/ccomcriticalsection-class.md) but doesn't provide a critical section.|`atlcore.h`| +|[`CComGITPtr`](../../atl/reference/ccomgitptr-class.md)|This class provides methods for dealing with interface pointers and the global interface table (GIT).|`atlbase.h`| +|[`CComHeap`](../../atl/reference/ccomheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions.|`ATLComMem.h`| +|[`CComHeapPtr`](../../atl/reference/ccomheapptr-class.md)|A smart pointer class for managing heap pointers.|`atlbase.h`| +|[`CComModule`](../../atl/reference/ccommodule-class.md)|As of ATL 7.0, `CComModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|`atlbase.h`| +|[`CComMultiThreadModel`](../../atl/reference/ccommultithreadmodel-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable.|`atlbase.h`| +|[`CComMultiThreadModelNoCS`](../../atl/reference/ccommultithreadmodelnocs-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable, without critical section locking or unlocking functionality.|`atlbase.h`| +|[`CComObject`](../../atl/reference/ccomobject-class.md)|This class implements `IUnknown` for a nonaggregated object.|`atlcom.h`| +|[`CComObjectGlobal`](../../atl/reference/ccomobjectglobal-class.md)|This class manages a reference count on the module containing your `Base` object.|`atlcom.h`| +|[`CComObjectNoLock`](../../atl/reference/ccomobjectnolock-class.md)|This class implements `IUnknown` for a nonaggregated object, but doesn't increment the module lock count in the constructor.|`atlcom.h`| +|[`CComObjectRoot`](../../atl/reference/ccomobjectroot-class.md)|This typedef of [`CComObjectRootEx`](../../atl/reference/ccomobjectrootex-class.md) is templatized on the default threading model of the server.|`atlcom.h`| +|[`CComObjectRootEx`](../../atl/reference/ccomobjectrootex-class.md)|This class provides methods to handle object reference count management for both nonaggregated and aggregated objects.|`atlcom.h`| +|[`CComObjectStack`](../../atl/reference/ccomobjectstack-class.md)|This class creates a temporary COM object and provides it with a skeletal implementation of `IUnknown`.|`atlcom.h`| +|[`CComPolyObject`](../../atl/reference/ccompolyobject-class.md)|This class implements `IUnknown` for an aggregated or nonaggregated object.|`atlcom.h`| +|[`CComPtr`](../../atl/reference/ccomptr-class.md)|A smart pointer class for managing COM interface pointers.|`atlcomcli.h`| +|[`CComPtrBase`](../../atl/reference/ccomptrbase-class.md)|This class provides a basis for smart pointer classes using COM-based memory routines.|`atlcomcli.h`| +|[`CComQIPtr`](../../atl/reference/ccomqiptr-class.md)|A smart pointer class for managing COM interface pointers.|`atlcomcli.h`| +|[`CComQIPtrElementTraits`](../../atl/reference/ccomqiptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of COM interface pointers.|`atlcoll.h`| +|[`CComSafeArray`](../../atl/reference/ccomsafearray-class.md)|This class is a wrapper for the `SAFEARRAY Data Type` structure.|`atlsafe.h`| +|[`CComSafeArrayBound`](../../atl/reference/ccomsafearraybound-class.md)|This class is a wrapper for a `SAFEARRAYBOUND` structure.|`atlsafe.h`| +|[`CComSimpleThreadAllocator`](../../atl/reference/ccomsimplethreadallocator-class.md)|This class manages thread selection for the class [`CComAutoThreadModule`](../../atl/reference/ccomautothreadmodule-class.md).|`atlbase.h`| +|[`CComSingleThreadModel`](../../atl/reference/ccomsinglethreadmodel-class.md)|This class provides methods for incrementing and decrementing the value of a variable.|`atlbase.h`| +|[`CComTearOffObject`](../../atl/reference/ccomtearoffobject-class.md)|This class implements a tear-off interface.|`atlcom.h`| +|[`CComUnkArray`](../../atl/reference/ccomunkarray-class.md)|This class stores `IUnknown` pointers and is designed to be used as a parameter to the [`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md) template class.|`atlcom.h`| +|[`CComVariant`](../../atl/reference/ccomvariant-class.md)|This class wraps the `VARIANT` type, providing a member indicating the type of data stored.|`atlcomcli.h`| +|[`CContainedWindowT`](../../atl/reference/ccontainedwindowt-class.md)|This class implements a window contained within another object.|`atlwin.h`| +|[`CCRTAllocator`](../../atl/reference/ccrtallocator-class.md)|This class provides methods for managing memory using CRT memory routines.|`atlcore.h`| +|[`CCRTHeap`](../../atl/reference/ccrtheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the CRT heap functions.|`atlmem.h`| +|[`CDacl`](../../atl/reference/cdacl-class.md)|This class is a wrapper for a DACL (discretionary access-control list) structure.|`atlsecurity.h`| +|[`CDebugReportHook` Class](../../atl/reference/cdebugreporthook-class.md)|Use this class to send debug reports to a named pipe.|`atlutil.h`| +|[`CDefaultCharTraits`](../../atl/reference/cdefaultchartraits-class.md)|This class provides two static functions for converting characters between uppercase and lowercase.|`atlcoll.h`| +|[`CDefaultCompareTraits`](../../atl/reference/cdefaultcomparetraits-class.md)|This class provides default element comparison functions.|`atlcoll.h`| +|[`CDefaultElementTraits`](../../atl/reference/cdefaultelementtraits-class.md)|This class provides default methods and functions for a collection class.|`atlcoll.h`| +|[`CDefaultHashTraits`](../../atl/reference/cdefaulthashtraits-class.md)|This class provides a static function for calculating hash values.|`atlcoll.h`| +|[`CDialogImpl`](../../atl/reference/cdialogimpl-class.md)|This class provides methods for creating a modal or modeless dialog box.|`atlwin.h`| +|[`CDynamicChain`](../../atl/reference/cdynamicchain-class.md)|This class provides methods supporting the dynamic chaining of message maps.|`atlwin.h`| +|[`CElementTraits`](../../atl/reference/celementtraits-class.md)|This class is used by collection classes to provide methods and functions for moving, copying, comparison, and hashing operations.|`atlcoll.h`| +|[`CElementTraitsBase`](../../atl/reference/celementtraitsbase-class.md)|This class provides default copy and move methods for a collection class.|`atlcoll.h`| +|[`CFirePropNotifyEvent`](../../atl/reference/cfirepropnotifyevent-class.md)|This class provides methods for notifying the container's sink regarding control property changes.|`atlctl.h`| +|[`CGlobalHeap`](../../atl/reference/cglobalheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 global heap functions.|`atlmem.h`| +|[`CHandle`](../../atl/reference/chandle-class.md)|This class provides methods for creating and using a handle object.|`atlbase.h`| +|[`CHeapPtr`](../../atl/reference/cheapptr-class.md)|A smart pointer class for managing heap pointers.|`atlcore.h`| +|[`CHeapPtrBase`](../../atl/reference/cheapptrbase-class.md)|This class forms the basis for several smart heap pointer classes.|`atlcore.h`| +|[`CHeapPtrElementTraits` Class](../../atl/reference/cheapptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of heap pointers.|`atlcoll.h`| +|[`CHeapPtrList`](../../atl/reference/cheapptrlist-class.md)|This class provides methods useful when constructing a list of heap pointers.|`atlcoll.h`| +|[`CImage`](../../atl-mfc-shared/reference/cimage-class.md)|Provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats.|`atlimage.h`| +|[`CInterfaceArray`](../../atl/reference/cinterfacearray-class.md)|This class provides methods useful when constructing an array of COM interface pointers.|`atlcoll.h`| +|[`CInterfaceList`](../../atl/reference/cinterfacelist-class.md)|This class provides methods useful when constructing a list of COM interface pointers.|`atlcoll.h`| +|[`CLocalHeap`](../../atl/reference/clocalheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 local heap functions.|`atlmem.h`| +|[`CMessageMap`](../../atl/reference/cmessagemap-class.md)|This class allows an object's message maps to be accessed by another object.|`atlwin.h`| +|[`CNonStatelessWorker` Class](../../atl/reference/cnonstatelessworker-class.md)|Receives requests from a thread pool and passes them on to a worker object that is created and destroyed on each request.|`atlutil.h`| +|[`CNoWorkerThread` Class](../../atl/reference/cnoworkerthread-class.md)|Use this class as the argument for the `MonitorClass` template parameter cache classes if you want to disable dynamic cache maintenance.|`atlutil.h`| +|[`CPathT` Class](../../atl/reference/cpatht-class.md)|This class represents a path.|`atlpath.h`| +|[`CPrimitiveElementTraits`](../../atl/reference/cprimitiveelementtraits-class.md)|This class provides default methods and functions for a collection class composed of primitive data types.|`atlcoll.h`| +|[`CPrivateObjectSecurityDesc`](../../atl/reference/cprivateobjectsecuritydesc-class.md)|This class represents a private object security descriptor object.|`atlsecurity.h`| +|[`CRBMap`](../../atl/reference/crbmap-class.md)|This class represents a mapping structure, using a Red-Black binary tree.|`atlcoll.h`| +|[`CRBMultiMap`](../../atl/reference/crbmultimap-class.md)|This class represents a mapping structure that allows each key to be associated with more than one value, using a Red-Black binary tree.|`atlcoll.h`| +|[`CRBTree`](../../atl/reference/crbtree-class.md)|This class provides methods for creating and utilizing a Red-Black tree.|`atlcoll.h`| +|[`CRegKey`](../../atl/reference/cregkey-class.md)|This class provides methods for manipulating entries in the system registry.|`atlbase.h`| +|[`CRTThreadTraits`](../../atl/reference/crtthreadtraits-class.md)|This class provides the creation function for a CRT thread. Use this class if the thread will use CRT functions.|`atlbase.h`| +|[`CSacl`](../../atl/reference/csacl-class.md)|This class is a wrapper for a SACL (system access-control list) structure.|`atlsecurity.h`| +|[`CSecurityAttributes`](../../atl/reference/csecurityattributes-class.md)|This class is a thin wrapper for the `SECURITY_ATTRIBUTES` structure.|`atlsecurity.h`| +|[`CSecurityDesc`](../../atl/reference/csecuritydesc-class.md)|This class is a wrapper for the `SECURITY_DESCRIPTOR` structure.|`atlsecurity.h`| +|[`CSid`](../../atl/reference/csid-class.md)|This class is a wrapper for a `SID` (security identifier) structure.|`atlsecurity.h`| +|[`CSimpleArray`](../../atl/reference/csimplearray-class.md)|This class provides methods for managing a simple array.|`atlsimpcoll.h`| +|[`CSimpleArrayEqualHelper`](../../atl/reference/csimplearrayequalhelper-class.md)|This class is a helper for the [`CSimpleArray`](../../atl/reference/csimplearray-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleArrayEqualHelperFalse`](../../atl/reference/csimplearrayequalhelperfalse-class.md)|This class is a helper for the [`CSimpleArray`](../../atl/reference/csimplearray-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleDialog`](../../atl/reference/csimpledialog-class.md)|This class implements a basic modal dialog box.|`atlwin.h`| +|[`CSimpleMap`](../../atl/reference/csimplemap-class.md)|This class provides support for a simple mapping array.|`atlsimpcoll.h`| +|[`CSimpleMapEqualHelper`](../../atl/reference/csimplemapequalhelper-class.md)|This class is a helper for the [`CSimpleMap`](../../atl/reference/csimplemap-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleMapEqualHelperFalse`](../../atl/reference/csimplemapequalhelperfalse-class.md)|This class is a helper for the [`CSimpleMap`](../../atl/reference/csimplemap-class.md) class.|`atlsimpcoll.h`| +|[`CSnapInItemImpl`](../../atl/reference/csnapinitemimpl-class.md)|This class provides methods for implementing a snap-in node object.|`atlsnap.h`| +|[`CSnapInPropertyPageImpl`](../../atl/reference/csnapinpropertypageimpl-class.md)|This class provides methods for implementing a snap-in property page object.|`atlsnap.h`| +|[`CStockPropImpl`](../../atl/reference/cstockpropimpl-class.md)|This class provides methods for supporting stock property values.|`atlctl.h`| +|[`CStringElementTraits`](../../atl/reference/cstringelementtraits-class.md)|This class provides static functions used by collection classes storing `CString` objects.|`cstringt`.h| +|[`CStringElementTraitsI`](../../atl/reference/cstringelementtraitsi-class.md)|This class provides static functions related to strings stored in collection class objects. It's similar to [`CStringElementTraits`](../../atl/reference/cstringelementtraits-class.md), but performs case-insensitive comparisons.|`atlcoll.h`| +|[`CStringRefElementTraits`](../../atl/reference/cstringrefelementtraits-class.md)|This class provides static functions related to strings stored in collection class objects. The string objects are dealt with as references.|`atlcoll.h`| +|[`CThreadPool` Class](../../atl/reference/cthreadpool-class.md)|This class provides a pool of worker threads that process a queue of work items.|`atlutil.h`| +|[`CTokenGroups`](../../atl/reference/ctokengroups-class.md)|This class is a wrapper for the `TOKEN_GROUPS` structure.|`atlsecurity.h`| +|[`CTokenPrivileges`](../../atl/reference/ctokenprivileges-class.md)|This class is a wrapper for the `TOKEN_PRIVILEGES` structure.|`atlsecurity.h`| +|[`CUrl` Class](../../atl/reference/curl-class.md)|This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch.|`atlutil.h`| +|[`CW2AEX`](../../atl/reference/cw2aex-class.md)|This class is used by the string conversion macros `CT2AEX`, `CW2TEX`, `CW2CTEX`, and `CT2CAEX`, and the typedef `CW2A`.|`atlconv.h`| +|[`CW2CWEX`](../../atl/reference/cw2cwex-class.md)|This class is used by the string conversion macros `CW2CTEX` and `CT2CWEX`, and the typedef `CW2CW`.|`atlconv.h`| +|[`CW2WEX`](../../atl/reference/cw2wex-class.md)|This class is used by the string conversion macros `CW2TEX` and `CT2WEX`, and the typedef `CW2W`.|`atlconv.h`| +|[`CWin32Heap`](../../atl/reference/cwin32heap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 heap allocation functions.|`atlmem.h`| +|[`CWindow`](../../atl/reference/cwindow-class.md)|This class provides methods for manipulating a window.|`atlwin.h`| +|[`CWindowImpl`](../../atl/reference/cwindowimpl-class.md)|This class provides methods for creating or subclassing a window.|`atlwin.h`| +|[`CWinTraits`](../../atl/reference/cwintraits-class.md)|This class provides a method for standardizing the styles used when creating a window object.|`atlwin.h`| +|[`CWinTraitsOR`](../../atl/reference/cwintraitsor-class.md)|This class provides a method for standardizing the styles used when creating a window object.|`atlwin.h`| +|[`CWndClassInfo`](../../atl/reference/cwndclassinfo-class.md)|This class provides methods for registering information for a window class.|`atlwin.h`| +|[`CWorkerThread` Class](../../atl/reference/cworkerthread-class.md)|This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled.|`atlutil.h`| +|[`IAtlAutoThreadModule`](../../atl/reference/iatlautothreadmodule-class.md)|This class represents an interface to a `CreateInstance` method.|`atlbase.h`| +|[`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md)|This class represents the interface to a memory manager.|`atlmem.h`| +|[`IAxWinAmbientDispatch`](../../atl/reference/iaxwinambientdispatch-interface.md)|This interface provides methods for specifying characteristics of the hosted control or container.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinAmbientDispatchEx`](../../atl/reference/iaxwinambientdispatchex-interface.md)|This interface implements supplemental ambient properties for a hosted control.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinHostWindow`](../../atl/reference/iaxwinhostwindow-interface.md)|This interface provides methods for manipulating a control and its host object.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinHostWindowLic`](../../atl/reference/iaxwinhostwindowlic-interface.md)|This interface provides methods for manipulating a licensed control and its host object.|`atlbase.h`, `ATLIFace.h`| +|[`ICollectionOnSTLImpl`](../../atl/reference/icollectiononstlimpl-class.md)|This class provides methods used by a collection class.|`atlcom.h`| +|[`IConnectionPointContainerImpl`](../../atl/reference/iconnectionpointcontainerimpl-class.md)|This class implements a connection point container to manage a collection of [`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md) objects.|`atlcom.h`| +|[`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md)|This class implements a connection point.|`atlcom.h`| +|[`IDataObjectImpl`](../../atl/reference/idataobjectimpl-class.md)|This class provides methods for supporting Uniform Data Transfer and managing connections.|`atlctl.h`| +|[`IDispatchImpl`](../../atl/reference/idispatchimpl-class.md)|This class provides a default implementation for the `IDispatch` portion of a dual interface.|`atlcom.h`| +|[`IDispEventImpl`](../../atl/reference/idispeventimpl-class.md)|This class provides implementations of the `IDispatch` methods.|`atlcom.h`| +|[`IDispEventSimpleImpl`](../../atl/reference/idispeventsimpleimpl-class.md)|This class provides implementations of the `IDispatch` methods, without getting type information from a type library.|`atlcom.h`| +|[`IDocHostUIHandlerDispatch`](../../atl/reference/idochostuihandlerdispatch-interface.md)|An interface to the Microsoft HTML parsing and rendering engine.|`atlbase.h`, `ATLIFace.h`| +|[`IEnumOnSTLImpl`](../../atl/reference/ienumonstlimpl-class.md)|This class defines an enumerator interface based on a C++ Standard Library collection.|`atlcom.h`| +|[`IObjectSafetyImpl`](../../atl/reference/iobjectsafetyimpl-class.md)|This class provides a default implementation of the `IObjectSafety` interface to allow a client to retrieve and set an object's safety levels.|`atlctl.h`| +|[`IObjectWithSiteImpl`](../../atl/reference/iobjectwithsiteimpl-class.md)|This class provides methods allowing an object to communicate with its site.|`atlcom.h`| +|[`IOleControlImpl`](../../atl/reference/iolecontrolimpl-class.md)|This class provides a default implementation of the `IOleControl` interface and implements `IUnknown`.|`atlctl.h`| +|[`IOleInPlaceActiveObjectImpl`](../../atl/reference/ioleinplaceactiveobjectimpl-class.md)|This class provides methods for assisting communication between an in-place control and its container.|`atlctl.h`| +|[`IOleInPlaceObjectWindowlessImpl`](../../atl/reference/ioleinplaceobjectwindowlessimpl-class.md)|This class implements `IUnknown` and provides methods that enable a windowless control to receive window messages and to participate in drag-and-drop operations.|`atlctl.h`| +|[`IOleObjectImpl`](../../atl/reference/ioleobjectimpl-class.md)|This class implements `IUnknown` and is the principal interface through which a container communicates with a control.|`atlctl.h`| +|[`IPerPropertyBrowsingImpl`](../../atl/reference/iperpropertybrowsingimpl-class.md)|This class implements `IUnknown` and allows a client to access the information in an object's property pages.|`atlctl.h`| +|[`IPersistPropertyBagImpl`](../../atl/reference/ipersistpropertybagimpl-class.md)|This class implements `IUnknown` and allows an object to save its properties to a client-supplied property bag.|`atlcom.h`| +|[`IPersistStorageImpl`](../../atl/reference/ipersiststorageimpl-class.md)|This class implements the [`IPersistStorage`](/windows/win32/api/objidl/nn-objidl-ipersiststorage) interface.|`atlcom.h`| +|[`IPersistStreamInitImpl`](../../atl/reference/ipersiststreaminitimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IPersistStreamInit`](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface.|`atlcom.h`| +|[`IPointerInactiveImpl`](../../atl/reference/ipointerinactiveimpl-class.md)|This class implements `IUnknown` and the [`IPointerInactive`](/windows/win32/api/ocidl/nn-ocidl-ipointerinactive) interface methods.|`atlctl.h`| +|[`IPropertyNotifySinkCP`](../../atl/reference/ipropertynotifysinkcp-class.md)|This class exposes the [`IPropertyNotifySink`](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) interface as an outgoing interface on a connectable object.|`atlctl.h`| +|[`IPropertyPage2Impl`](../../atl/reference/ipropertypage2impl-class.md)|This class implements `IUnknown` and inherits the default implementation of [`IPropertyPageImpl`](../../atl/reference/ipropertypageimpl-class.md).|`atlctl.h`| +|[`IPropertyPageImpl`](../../atl/reference/ipropertypageimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IPropertyPage`](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) interface.|`atlctl.h`| +|[`IProvideClassInfo2Impl`](../../atl/reference/iprovideclassinfo2impl-class.md)|This class provides a default implementation of the [`IProvideClassInfo`](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo) and [`IProvideClassInfo2`](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo2) methods.|`atlcom.h`| +|[`IQuickActivateImpl`](../../atl/reference/iquickactivateimpl-class.md)|This class combines containers' control initialization into a single call.|`atlctl.h`| +|[`IRunnableObjectImpl`](../../atl/reference/irunnableobjectimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IRunnableObject`](/windows/win32/api/objidl/nn-objidl-irunnableobject) interface.|`atlctl.h`| +|[`IServiceProviderImpl`](../../atl/reference/iserviceproviderimpl-class.md)|This class provides a default implementation of the `IServiceProvider` interface.|`atlcom.h`| +|[`ISpecifyPropertyPagesImpl`](../../atl/reference/ispecifypropertypagesimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`ISpecifyPropertyPages`](/windows/win32/api/ocidl/nn-ocidl-ispecifypropertypages) interface.|`atlcom.h`| +|[`ISupportErrorInfoImpl`](../../atl/reference/isupporterrorinfoimpl-class.md)|This class provides a default implementation of the `ISupportErrorInfo Interface` interface and can be used when only a single interface generates errors on an object.|`atlcom.h`| +|[`IThreadPoolConfig` Interface](../../atl/reference/ithreadpoolconfig-interface.md)|This interface provides methods for configuring a thread pool.|`atlutil.h`| +|[`IViewObjectExImpl`](../../atl/reference/iviewobjecteximpl-class.md)|This class implements `IUnknown` and provides default implementations of the [`IViewObject`](/windows/win32/api/oleidl/nn-oleidl-iviewobject), [`IViewObject2`](/windows/win32/api/oleidl/nn-oleidl-iviewobject2), and [`IViewObjectEx`](/windows/win32/api/ocidl/nn-ocidl-iviewobjectex) interfaces.|`atlctl.h`| +|[`IWorkerThreadClient` Interface](../../atl/reference/iworkerthreadclient-interface.md)|`IWorkerThreadClient` is the interface implemented by clients of the [`CWorkerThread`](../../atl/reference/cworkerthread-class.md) class.|`atlutil.h`| +|[`_U_MENUorID`](../../atl/reference/u-menuorid-class.md)|This class provides wrappers for `CreateWindow` and `CreateWindowEx`.|`atlwin.h`| +|[`_U_RECT`](../../atl/reference/u-rect-class.md)|This argument adapter class allows either `RECT` pointers or references to be passed to a function that is implemented in terms of pointers.|`atlwin.h`| +|[`_U_STRINGorID`](../../atl/reference/u-stringorid-class.md)|This argument adapter class allows either resource names (LPCTSTRs) or resource IDs (UINTs) to be passed to a function without requiring the caller to convert the ID to a string using the `MAKEINTRESOURCE` macro.|`atlwin.h`| +|[`Win32ThreadTraits`](../../atl/reference/win32threadtraits-class.md)|This class provides the creation function for a Windows thread. Use this class if the thread won't use CRT functions.|`atlbase.h`| ## See also -[ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)
-[Functions](../../atl/reference/atl-functions.md)
-[Global Variables](../../atl/reference/atl-global-variables.md)
-[Typedefs](../../atl/reference/atl-typedefs.md)
+[ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)\ +[Functions](../../atl/reference/atl-functions.md)\ +[Global Variables](../../atl/reference/atl-global-variables.md)\ +[Typedefs](../../atl/reference/atl-typedefs.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/category-macros.md b/docs/atl/reference/category-macros.md index ecb6b7b4a5..2520af5960 100644 --- a/docs/atl/reference/category-macros.md +++ b/docs/atl/reference/category-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Category Macros" title: "Category Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_CATEGORY_MAP", "atlcom/ATL::END_CATEGORY_MAP", "atlcom/ATL::IMPLEMENTED_CATEGORY", "atlcom/ATL::REQUIRED_CATEGORY"] +f1_keywords: ["ATLCOM/BEGIN_CATEGORY_MAP", "ATLCOM/END_CATEGORY_MAP", "ATLCOM/IMPLEMENTED_CATEGORY", "ATLCOM/REQUIRED_CATEGORY", "atlcom/ATL::BEGIN_CATEGORY_MAP", "atlcom/ATL::END_CATEGORY_MAP", "atlcom/ATL::IMPLEMENTED_CATEGORY", "atlcom/ATL::REQUIRED_CATEGORY"] ms.assetid: 223578cb-6180-4787-a8d8-ba3787a5d3ee --- # Category Macros diff --git a/docs/atl/reference/catltemporaryfile-class.md b/docs/atl/reference/catltemporaryfile-class.md index ac4ae6210e..9878d4a0d9 100644 --- a/docs/atl/reference/catltemporaryfile-class.md +++ b/docs/atl/reference/catltemporaryfile-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CAtlTemporaryFile Class" title: "CAtlTemporaryFile Class" -ms.date: "11/04/2016" +description: "Learn more about: CAtlTemporaryFile Class" +ms.date: 11/04/2016 f1_keywords: ["CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile::CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile::Close", "ATLFILE/ATL::CAtlTemporaryFile::Create", "ATLFILE/ATL::CAtlTemporaryFile::Flush", "ATLFILE/ATL::CAtlTemporaryFile::GetPosition", "ATLFILE/ATL::CAtlTemporaryFile::GetSize", "ATLFILE/ATL::CAtlTemporaryFile::HandsOff", "ATLFILE/ATL::CAtlTemporaryFile::HandsOn", "ATLFILE/ATL::CAtlTemporaryFile::LockRange", "ATLFILE/ATL::CAtlTemporaryFile::Read", "ATLFILE/ATL::CAtlTemporaryFile::Seek", "ATLFILE/ATL::CAtlTemporaryFile::SetSize", "ATLFILE/ATL::CAtlTemporaryFile::TempFileName", "ATLFILE/ATL::CAtlTemporaryFile::UnlockRange", "ATLFILE/ATL::CAtlTemporaryFile::Write"] helpviewer_keywords: ["CAtlTemporaryFile class"] -ms.assetid: 05f0f2a5-94f6-4594-8dae-b114292ff5f9 --- # CAtlTemporaryFile Class @@ -357,7 +356,7 @@ Returns the LPCTSTR pointing to the file name. ### Remarks -The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew)Windows SDK function. The file extension will always be "TFR" for the temporary file. +The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew) Windows SDK function. The file extension will always be "TFR" for the temporary file. ## CAtlTemporaryFile::UnlockRange diff --git a/docs/atl/reference/catltransactionmanager-class.md b/docs/atl/reference/catltransactionmanager-class.md index 9a3cf494d6..3b7a42f274 100644 --- a/docs/atl/reference/catltransactionmanager-class.md +++ b/docs/atl/reference/catltransactionmanager-class.md @@ -165,7 +165,7 @@ inline HANDLE CreateFile( The name of an object to be created or opened. *dwDesiredAccess*
-The access to the object, which can be summarized as read, write, both, or neither (zero). The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both: GENERIC_READ | GENERIC_WRITE. +The access to the object, which can be summarized as read, write, both, or neither (zero). The most commonly used values are `GENERIC_READ`, `GENERIC_WRITE`, or both: `GENERIC_READ | GENERIC_WRITE`. *dwShareMode*
The sharing mode of an object, which can be read, write, both, delete, all of these, or none: 0, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE. diff --git a/docs/atl/reference/caxwindow-class.md b/docs/atl/reference/caxwindow-class.md index 4c266ad417..1817a66fc3 100644 --- a/docs/atl/reference/caxwindow-class.md +++ b/docs/atl/reference/caxwindow-class.md @@ -5,6 +5,12 @@ ms.date: "11/04/2016" f1_keywords: ["CAxWindow", "ATLWIN/ATL::CAxWindow", "ATLWIN/ATL::AttachControl", "ATLWIN/ATL::CreateControl", "ATLWIN/ATL::CreateControlEx", "ATLWIN/ATL::GetWndClassName", "ATLWIN/ATL::QueryControl", "ATLWIN/ATL::QueryHost", "ATLWIN/ATL::SetExternalDispatch", "ATLWIN/ATL::SetExternalUIHandler"] helpviewer_keywords: ["CAxWindow class", "ATL, hosting ActiveX controls"] ms.assetid: 85e79261-43e4-4770-bde0-1ff87f222b0f +api_type: +- DllExport +api_location: +- atlhost.dll +api_name: +- CAxWindow::CreateControlEx --- # CAxWindow Class diff --git a/docs/atl/reference/ccomcoclass-class.md b/docs/atl/reference/ccomcoclass-class.md index 1cea7aa58c..2101a31f89 100644 --- a/docs/atl/reference/ccomcoclass-class.md +++ b/docs/atl/reference/ccomcoclass-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CComCoClass Class" title: "CComCoClass Class" +description: "Learn more about: CComCoClass Class" ms.date: "11/04/2016" f1_keywords: ["CComCoClass", "ATLCOM/ATL::CComCoClass", "ATLCOM/ATL::CComCoClass::CreateInstance", "ATLCOM/ATL::CComCoClass::Error", "ATLCOM/ATL::CComCoClass::GetObjectCLSID", "ATLCOM/ATL::CComCoClass::GetObjectDescription"] helpviewer_keywords: ["CComCoClass class", "aggregation [C++], aggregation models"] -ms.assetid: 67cfefa4-8df9-47fa-ad58-2d1a1ae25762 --- # CComCoClass Class @@ -12,29 +11,29 @@ This class provides methods for creating instances of a class, and obtaining its ## Syntax -``` +```cpp template class CComCoClass ``` #### Parameters -*T*
+*T*\ Your class, derived from `CComCoClass`. -*pclsid*
+*pclsid*\ A pointer to the CLSID of the object. ## Members ### Public Methods -|Name|Description| -|----------|-----------------| -|[CComCoClass::CreateInstance](#createinstance)|(Static) Creates an instance of the class and queries for an interface.| -|[CComCoClass::Error](#error)|(Static) Returns rich error information to the client.| -|[CComCoClass::GetObjectCLSID](#getobjectclsid)|(Static) Returns the object's class identifier.| -|[CComCoClass::GetObjectDescription](#getobjectdescription)|(Static) Override to return the object's description.| +| Name | Description | +| ---------------------------------------------------------- | ----------------------------------------------------------------------- | +| [CComCoClass::CreateInstance](#createinstance) | (Static) Creates an instance of the class and queries for an interface. | +| [CComCoClass::Error](#error) | (Static) Returns rich error information to the client. | +| [CComCoClass::GetObjectCLSID](#getobjectclsid) | (Static) Returns the object's class identifier. | +| [CComCoClass::GetObjectDescription](#getobjectdescription) | (Static) Override to return the object's description. | ## Remarks @@ -58,23 +57,23 @@ You can override either of these defaults by specifying another macro in your cl Use these `CreateInstance` functions to create an instance of a COM object and retrieve an interface pointer without using the COM API. -``` -template -static HRESULT CreateInstance( Q** pp); +```cpp +template +static HRESULT CreateInstance(Q** pp); -template +template static HRESULT CreateInstance(IUnknown* punkOuter, Q** pp); ``` ### Parameters -*Q*
+*Q*\ The COM interface that should be returned via *pp*. -*punkOuter*
+*punkOuter*\ [in] The outer unknown or controlling unknown of the aggregate. -*pp*
+*pp*\ [out] The address of a pointer variable that receives the requested interface pointer if creation succeeds. ### Return Value @@ -101,7 +100,7 @@ In the following example, `CDocument` is a wizard-generated ATL class derived fr This static function sets up the `IErrorInfo` interface to provide error information to the client. -``` +```cpp static HRESULT WINAPI Error( LPCOLESTR lpszDesc, const IID& iid = GUID_NULL, @@ -130,7 +129,7 @@ static HRESULT WINAPI Error( UINT nID, const IID& iid = GUID_NULL, HRESULT hRes = 0, - HINSTANCE hInst = _AtlBaseModule.GetResourceInstance ()); + HINSTANCE hInst = _AtlBaseModule.GetResourceInstance()); static HRESULT Error( UINT nID, @@ -143,25 +142,25 @@ static HRESULT Error( ### Parameters -*lpszDesc*
+*lpszDesc*\ [in] The string describing the error. The Unicode version of `Error` specifies that *lpszDesc* is of type LPCOLESTR; the ANSI version specifies a type of LPCSTR. -*iid*
+*iid*\ [in] The IID of the interface defining the error or GUID_NULL (the default value) if the error is defined by the operating system. -*hRes*
+*hRes*\ [in] The HRESULT you want returned to the caller. The default value is 0. For more details about *hRes*, see Remarks. -*nID*
+*nID*\ [in] The resource identifier where the error description string is stored. This value should lie between 0x0200 and 0xFFFF, inclusively. In debug builds, an **ASSERT** will result if *nID* does not index a valid string. In release builds, the error description string will be set to "Unknown Error." -*dwHelpID*
+*dwHelpID*\ [in] The help context identifier for the error. -*lpszHelpFile*
+*lpszHelpFile*\ [in] The path and name of the help file describing the error. -*hInst*
+*hInst*\ [in] The handle to the resource. By default, this parameter is `_AtlModule::GetResourceInstance`, where `_AtlModule` is the global instance of [CAtlModule](../../atl/reference/catlmodule-class.md). ### Return Value @@ -170,7 +169,7 @@ A standard HRESULT value. For details, see Remarks. ### Remarks -To call `Error`, your object must implement the `ISupportErrorInfo Interface` interface. +To call `Error`, your object must implement the `ISupportErrorInfo` interface. If the *hRes* parameter is nonzero, then `Error` returns the value of *hRes*. If *hRes* is zero, then the first four versions of `Error` return DISP_E_EXCEPTION. The last two versions return the result of the macro **MAKE_HRESULT( 1, FACILITY_ITF,** *nID* **)**. @@ -178,7 +177,7 @@ If the *hRes* parameter is nonzero, then `Error` returns the value of *hRes*. If Provides a consistent way of retrieving the object's CLSID. -``` +```cpp static const CLSID& WINAPI GetObjectCLSID(); ``` @@ -190,7 +189,7 @@ The object's class identifier. This static function retrieves the text description for your class object. -``` +```cpp static LPCTSTR WINAPI GetObjectDescription(); ``` diff --git a/docs/atl/reference/ccomcontrolbase-class.md b/docs/atl/reference/ccomcontrolbase-class.md index f6b457426f..f65f6c90ee 100644 --- a/docs/atl/reference/ccomcontrolbase-class.md +++ b/docs/atl/reference/ccomcontrolbase-class.md @@ -252,7 +252,7 @@ One of the standard HRESULT values. ### Example [!code-cpp[NVC_ATL_COM#19](../../atl/codesnippet/cpp/ccomcontrolbase-class_2.cpp)] - +  [!code-cpp[NVC_ATL_COM#20](../../atl/codesnippet/cpp/ccomcontrolbase-class_3.h)] ## CComControlBase::FireViewChange diff --git a/docs/atl/reference/ccomcurrency-class.md b/docs/atl/reference/ccomcurrency-class.md index b51cb2e04a..cee7bfd016 100644 --- a/docs/atl/reference/ccomcurrency-class.md +++ b/docs/atl/reference/ccomcurrency-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CComCurrency Class" title: "CComCurrency Class" -ms.date: "11/04/2016" +description: "Learn more about: CComCurrency Class" +ms.date: 11/04/2016 f1_keywords: ["CComCurrency", "ATLCUR/ATL::CComCurrency", "ATLCUR/ATL::CComCurrency::CComCurrency", "ATLCUR/ATL::CComCurrency::GetCurrencyPtr", "ATLCUR/ATL::CComCurrency::GetFraction", "ATLCUR/ATL::CComCurrency::GetInteger", "ATLCUR/ATL::CComCurrency::Round", "ATLCUR/ATL::CComCurrency::SetFraction", "ATLCUR/ATL::CComCurrency::SetInteger", "ATLCUR/ATL::CComCurrency::m_currency"] helpviewer_keywords: ["CComCurrency class"] -ms.assetid: a1c3d10a-bba6-40cc-8bcf-aed9023c8a9e --- # `CComCurrency` Class @@ -563,7 +562,7 @@ Returns a reference to a `CURRENCY` object. Call this method to round the currency to a specified number of decimal places. ```cpp -HRESULT Roundint nDecimals); +HRESULT Round(int nDecimals); ``` ### Parameters diff --git a/docs/atl/reference/ccomdynamicunkarray-class.md b/docs/atl/reference/ccomdynamicunkarray-class.md index 19adbd15a5..0c0f142ee6 100644 --- a/docs/atl/reference/ccomdynamicunkarray-class.md +++ b/docs/atl/reference/ccomdynamicunkarray-class.md @@ -35,7 +35,7 @@ class CComDynamicUnkArray |[CComDynamicUnkArray::end](#end)|Returns a pointer to one past the last `IUnknown` pointer in the collection.| |[CComDynamicUnkArray::GetAt](#getat)|Retrieves the element at the specified index.| |[CComDynamicUnkArray::GetCookie](#getcookie)|Call this method to get the cookie associated with a given `IUnknown` pointer.| -|[CComDynamicUnkArray::GetSize](#getsize)|Returns the length of an array.| +|[CComDynamicUnkArray::GetSize](#getsize)|Returns the number of elements the array can store.| |[CComDynamicUnkArray::GetUnknown](#getunknown)|Call this method to get the `IUnknown` pointer associated with a given cookie.| |[CComDynamicUnkArray::Remove](#remove)|Call this method to remove an `IUnknown` pointer from the array.| @@ -69,7 +69,12 @@ The `IUnknown` pointer to add to the array. ### Return Value -Returns the cookie associated with the newly added pointer. +Returns the cookie associated with the newly added pointer. Use this cookie to retrieve the pointer from the array with [CComDynamicUnkArray::GetAt](#getat). + +### Remarks + +The position where this item is inserted won't necessarily be directly after the last-inserted item if `Remove()` was previously called on this array. Use the returned cookie to reliably access the inserted pointer. +The array's size might be increased to accommodate more items. Use `GetSize()` to get the new size. ## CComDynamicUnkArray::begin @@ -92,7 +97,7 @@ Before using the `IUnknown` interface, you should check that it is not NULL. ## CComDynamicUnkArray::clear -Empties the array. +Empties the array. Resets the size to 0. ```cpp void clear(); @@ -124,7 +129,9 @@ Frees resources allocated by the class constructor. ## CComDynamicUnkArray::end -Returns a pointer to one past the last `IUnknown` pointer in the collection. +Returns a pointer to one-past the last element in the array's allocated buffer. + +Note: this means that the last-inserted pointer is not guaranteed to be at `end()-1` because the array may not be filled to capacity. ``` IUnknown** @@ -150,7 +157,7 @@ The index of the element to retrieve. ### Return Value -A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface. +A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface if an element was previously added and exists at this index; otherwise `NULL`. ## CComDynamicUnkArray::GetCookie @@ -175,7 +182,9 @@ If there is more than one instance of the same `IUnknown` pointer, this function ## CComDynamicUnkArray::GetSize -Returns the length of an array. +Returns the allocated capacity of the array. + +Note: this is not the same as the number of non-NULL elements currently in the array. ``` int GetSize() const; @@ -183,9 +192,9 @@ int GetSize() const; ### Return Value -The length of the array. +The number of elements the array can store. `GetSize() == end() - begin()`. -## CComDynamicUnkArray::GetUnknown +## CComDynamicUnkArray::GetUnknown Call this method to get the `IUnknown` pointer associated with a given cookie. @@ -206,6 +215,8 @@ Returns the `IUnknown` pointer, or NULL if no matching cookie is found. Call this method to remove an `IUnknown` pointer from the array. +All other elements are unchanged and retain their index and cookie. + ``` BOOL Remove(DWORD dwCookie); ``` diff --git a/docs/atl/reference/ccomenum-class.md b/docs/atl/reference/ccomenum-class.md index 8ca27ce7d6..874c02b84c 100644 --- a/docs/atl/reference/ccomenum-class.md +++ b/docs/atl/reference/ccomenum-class.md @@ -76,7 +76,7 @@ The code shown below provides a reusable function for creating and initializing [!code-cpp[NVC_ATL_COM#32](../../atl/codesnippet/cpp/ccomenum-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#33](../../atl/codesnippet/cpp/ccomenum-class_2.h)] diff --git a/docs/atl/reference/ccomenumonstl-class.md b/docs/atl/reference/ccomenumonstl-class.md index c84d245c6b..7ab682b506 100644 --- a/docs/atl/reference/ccomenumonstl-class.md +++ b/docs/atl/reference/ccomenumonstl-class.md @@ -85,7 +85,7 @@ The code shown below provides a generic function to handle the creation and init [!code-cpp[NVC_ATL_COM#34](../../atl/codesnippet/cpp/ccomenumonstl-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#35](../../atl/codesnippet/cpp/ccomenumonstl-class_2.h)] diff --git a/docs/atl/reference/ccommultithreadmodel-class.md b/docs/atl/reference/ccommultithreadmodel-class.md index 167fe9c3c7..651aa91f66 100644 --- a/docs/atl/reference/ccommultithreadmodel-class.md +++ b/docs/atl/reference/ccommultithreadmodel-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CComMultiThreadModel Class" title: "CComMultiThreadModel Class" +description: "Learn more about: CComMultiThreadModel Class" ms.date: "11/04/2016" f1_keywords: ["CComMultiThreadModel", "ATLBASE/ATL::CComMultiThreadModel", "ATLBASE/ATL::CComMultiThreadModel::AutoCriticalSection", "ATLBASE/ATL::CComMultiThreadModel::CriticalSection", "ATLBASE/ATL::CComMultiThreadModel::ThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModel::Decrement", "ATLBASE/ATL::CComMultiThreadModel::Increment"] helpviewer_keywords: ["ATL, multithreading", "CComMultiThreadModel class", "threading [ATL]"] -ms.assetid: db8f1662-2f7a-44b3-b341-ffbfb6e422a3 --- # CComMultiThreadModel Class @@ -12,7 +11,7 @@ ms.assetid: db8f1662-2f7a-44b3-b341-ffbfb6e422a3 ## Syntax -``` +```cpp class CComMultiThreadModel ``` @@ -35,7 +34,7 @@ class CComMultiThreadModel ## Remarks -Typically, you use `CComMultiThreadModel` through one of two **`typedef`** names, either [CComObjectThreadModel](atl-typedefs.md#ccomobjectthreadmodel or [CComGlobalsThreadModel](atl-typedefs.md#ccomglobalsthreadmodel. The class referenced by each **`typedef`** depends on the threading model used, as shown in the following table: +Typically, you use `CComMultiThreadModel` through one of two **`typedef`** names, either [CComObjectThreadModel](atl-typedefs.md#ccomobjectthreadmodel) or [CComGlobalsThreadModel](atl-typedefs.md#ccomglobalsthreadmodel). The class referenced by each **`typedef`** depends on the threading model used, as shown in the following table: |typedef|Single threading|Apartment threading|Free threading| |-------------|----------------------|-------------------------|--------------------| @@ -54,7 +53,7 @@ S= `CComSingleThreadModel`; M= `CComMultiThreadModel` When using `CComMultiThreadModel`, the **`typedef`** name `AutoCriticalSection` references class [CComAutoCriticalSection](ccomautocriticalsection-class.md), which provides methods for obtaining and releasing ownership of a critical section object. -``` +```cpp typedef CComAutoCriticalSection AutoCriticalSection; ``` @@ -120,7 +119,7 @@ The following tables show the results of the `InternalAddRef` and `Lock` methods When using `CComMultiThreadModel`, the **`typedef`** name `CriticalSection` references class [CComCriticalSection](ccomcriticalsection-class.md), which provides methods for obtaining and releasing ownership of a critical section object. -``` +```cpp typedef CComCriticalSection CriticalSection; ``` @@ -144,13 +143,13 @@ See [CComMultiThreadModel::AutoCriticalSection](#autocriticalsection). This static function calls the Win32 function [InterlockedDecrement](/windows/win32/api/winnt/nf-winnt-interlockeddecrement), which decrements the value of the variable pointed to by *p*. -``` +```cpp static ULONG WINAPI Decrement(LPLONG p) throw (); ``` ### Parameters -*p*
+*p*\ [in] Pointer to the variable to be decremented. ### Return Value @@ -165,13 +164,13 @@ If the result of the decrement is 0, then `Decrement` returns 0. If the result o This static function calls the Win32 function [InterlockedIncrement](/windows/win32/api/winnt/nf-winnt-interlockedincrement), which increments the value of the variable pointed to by *p*. -``` +```cpp static ULONG WINAPI Increment(LPLONG p) throw (); ``` ### Parameters -*p*
+*p*\ [in] Pointer to the variable to be incremented. ### Return Value @@ -186,7 +185,7 @@ If the result of the increment is 0, then `Increment` returns 0. If the result o When using `CComMultiThreadModel`, the **`typedef`** name `ThreadModelNoCS` references class [CComMultiThreadModelNoCS](ccommultithreadmodelnocs-class.md). -``` +```cpp typedef CComMultiThreadModelNoCS ThreadModelNoCS; ``` @@ -208,7 +207,7 @@ See [CComMultiThreadModel::AutoCriticalSection](#autocriticalsection). ## See also -[CComSingleThreadModel Class](ccomsinglethreadmodel-class.md)
-[CComAutoCriticalSection Class](ccomautocriticalsection-class.md)
-[CComCriticalSection Class](ccomcriticalsection-class.md)
+[CComSingleThreadModel Class](ccomsinglethreadmodel-class.md)\ +[CComAutoCriticalSection Class](ccomautocriticalsection-class.md)\ +[CComCriticalSection Class](ccomcriticalsection-class.md)\ [Class Overview](../atl-class-overview.md) diff --git a/docs/atl/reference/ccomobject-class.md b/docs/atl/reference/ccomobject-class.md index 7c63e2eca1..940285715a 100644 --- a/docs/atl/reference/ccomobject-class.md +++ b/docs/atl/reference/ccomobject-class.md @@ -125,7 +125,7 @@ If you do not need direct access to the object, but still want to create a new o ### Example [!code-cpp[NVC_ATL_COM#38](../../atl/codesnippet/cpp/ccomobject-class_1.h)] - +  [!code-cpp[NVC_ATL_COM#39](../../atl/codesnippet/cpp/ccomobject-class_2.cpp)] ## CComObject::QueryInterface diff --git a/docs/atl/reference/ccomptr-class.md b/docs/atl/reference/ccomptr-class.md index ab102f9213..6ccf609038 100644 --- a/docs/atl/reference/ccomptr-class.md +++ b/docs/atl/reference/ccomptr-class.md @@ -43,7 +43,7 @@ ATL uses `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) to The `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) classes can help eliminate memory leaks by performing automatic reference counting. The following functions both do the same logical operations. However, the second version may be less error-prone because it uses the `CComPtr` class: [!code-cpp[NVC_ATL_Utilities#130](../../atl/codesnippet/cpp/ccomptr-class_1.cpp)] - +  [!code-cpp[NVC_ATL_Utilities#131](../../atl/codesnippet/cpp/ccomptr-class_2.cpp)] In Debug builds, link atlsd.lib for code tracing. diff --git a/docs/atl/reference/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index df693cce9a..d9c6729e91 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -4,7 +4,6 @@ title: "CComSafeArray Class" ms.date: "05/06/2019" f1_keywords: ["CComSafeArray", "ATLSAFE/ATL::CComSafeArray", "ATLSAFE/ATL::CComSafeArray::CComSafeArray", "ATLSAFE/ATL::CComSafeArray::Add", "ATLSAFE/ATL::CComSafeArray::Attach", "ATLSAFE/ATL::CComSafeArray::CopyFrom", "ATLSAFE/ATL::CComSafeArray::CopyTo", "ATLSAFE/ATL::CComSafeArray::Create", "ATLSAFE/ATL::CComSafeArray::Destroy", "ATLSAFE/ATL::CComSafeArray::Detach", "ATLSAFE/ATL::CComSafeArray::GetAt", "ATLSAFE/ATL::CComSafeArray::GetCount", "ATLSAFE/ATL::CComSafeArray::GetDimensions", "ATLSAFE/ATL::CComSafeArray::GetLowerBound", "ATLSAFE/ATL::CComSafeArray::GetSafeArrayPtr", "ATLSAFE/ATL::CComSafeArray::GetType", "ATLSAFE/ATL::CComSafeArray::GetUpperBound", "ATLSAFE/ATL::CComSafeArray::IsSizable", "ATLSAFE/ATL::CComSafeArray::MultiDimGetAt", "ATLSAFE/ATL::CComSafeArray::MultiDimSetAt", "ATLSAFE/ATL::CComSafeArray::Resize", "ATLSAFE/ATL::CComSafeArray::SetAt", "ATLSAFE/ATL::CComSafeArray::m_psa"] helpviewer_keywords: ["CComSafeArray class"] -ms.assetid: ee349aef-33db-4c85-bd08-5d86a3c9d53a --- # `CComSafeArray` Class @@ -101,7 +100,7 @@ A `CComSafeArray` can contain the following subset of `VARIANT` data types: ## Requirements -**Header:** atlsafe.h +**Header:** `atlsafe.h` ## Example @@ -527,7 +526,7 @@ Retrieves an element from the array. ```cpp T& operator[](long lindex) const; -T& operator[]int nindex) const; +T& operator[](int nindex) const; ``` ### Parameters diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index cb97f860f4..e3b806e113 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -4,7 +4,6 @@ title: "CComVariant class" ms.date: "11/04/2016" f1_keywords: ["CComVariant", "ATLCOMCLI/ATL::CComVariant", "ATLCOMCLI/ATL::CComVariant::CComVariant", "ATLCOMCLI/ATL::CComVariant::Attach", "ATLCOMCLI/ATL::CComVariant::ChangeType", "ATLCOMCLI/ATL::CComVariant::Clear", "ATLCOMCLI/ATL::CComVariant::Copy", "ATLCOMCLI/ATL::CComVariant::CopyTo", "ATLCOMCLI/ATL::CComVariant::Detach", "ATLCOMCLI/ATL::CComVariant::GetSize", "ATLCOMCLI/ATL::CComVariant::ReadFromStream", "ATLCOMCLI/ATL::CComVariant::SetByRef", "ATLCOMCLI/ATL::CComVariant::WriteToStream"] helpviewer_keywords: ["VARIANT macro", "CComVariant class", "VARIANT macro, ATL"] -ms.assetid: 4d31149c-d005-44b5-a509-10f84afa2b61 --- # `CComVariant` class @@ -52,7 +51,7 @@ class CComVariant : public tagVARIANT ## Remarks -`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation. +`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. `VARIANT`s are typically used in Automation. `CComVariant` derives from the `VARIANT` type so it can be used wherever a `VARIANT` can be used. You can, for example, use the `V_VT` macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a `VARIANT`. @@ -63,7 +62,7 @@ class CComVariant : public tagVARIANT ## Requirements -**Header:** atlcomcli.h +**Header:** `atlcomcli.h` ## `CComVariant::Attach` @@ -183,7 +182,7 @@ HRESULT ChangeType(VARTYPE vtNew, const VARIANT* pSrc = NULL); [in] The new type for the `CComVariant` object. *`pSrc`*\ -[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is NULL, meaning the `CComVariant` object is converted in place. +[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is `NULL`, meaning the `CComVariant` object is converted in place. ### Return value @@ -270,7 +269,7 @@ The contents of the `VARIANT` referenced by *`pDest`* are automatically cleared ## `CComVariant::GetSize` -For simple-fixed size VARIANTs, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. +For simple-fixed size `VARIANT`s, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. ```cpp ULONG GetSize() const; @@ -282,9 +281,9 @@ The size in bytes of the current contents of the `CComVariant` object. ### Remarks -If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is NULL, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. +If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is `NULL`, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. -In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus `sizeof(VARTYPE)`. If the `VARIANT` cannot be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. +In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the `NULL` character plus `sizeof(VARTYPE)`. If the `VARIANT` can't be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. The size returned by this method matches the number of bytes used by [`CComVariant::WriteToStream`](#writetostream) under successful conditions. diff --git a/docs/atl/reference/ccontainedwindowt-class.md b/docs/atl/reference/ccontainedwindowt-class.md index 2324c43241..92e55f8f39 100644 --- a/docs/atl/reference/ccontainedwindowt-class.md +++ b/docs/atl/reference/ccontainedwindowt-class.md @@ -75,9 +75,9 @@ A traits class that defines styles for your window. The default is `CControlWinT When you use the **Add control based on** option in the ATL Project Wizard, the wizard will automatically add a `CContainedWindowT` data member to the class implementing the control. The following example shows how the contained window is declared: [!code-cpp[NVC_ATL_Windowing#38](../../atl/codesnippet/cpp/ccontainedwindowt-class_1.h)] - +  [!code-cpp[NVC_ATL_Windowing#39](../../atl/codesnippet/cpp/ccontainedwindowt-class_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#40](../../atl/codesnippet/cpp/ccontainedwindowt-class_3.h)] |For more information about|See| @@ -197,7 +197,7 @@ HWND Create( [in] Specifies the name of the window. The default value is NULL. *dwStyle*
-[in] The style of the window. The default value is WS_CHILD | WS_VISIBLE. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. +[in] The style of the window. The default value is `WS_CHILD | WS_VISIBLE`. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. *dwExStyle*
[in] The extended window style. The default value is 0, meaning no extended style. For a list of possible values, see [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. diff --git a/docs/atl/reference/com-map-macros.md b/docs/atl/reference/com-map-macros.md index cb755491ea..6734604721 100644 --- a/docs/atl/reference/com-map-macros.md +++ b/docs/atl/reference/com-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: COM Map Macros" title: "COM Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_COM_MAP", "atlcom/ATL::END_COM_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_COM_MAP", "atlcom/ATL::END_COM_MAP", "ATLCOM/BEGIN_COM_MAP", "ATLCOM/END_COM_MAP"] helpviewer_keywords: ["COM interfaces, COM map macros"] ms.assetid: 0f33656d-321f-4996-90cc-9a7f21ab73c3 --- diff --git a/docs/atl/reference/compiler-options-macros.md b/docs/atl/reference/compiler-options-macros.md index b88df25cda..4c80bb5d9b 100644 --- a/docs/atl/reference/compiler-options-macros.md +++ b/docs/atl/reference/compiler-options-macros.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler Options Macros" title: "Compiler Options Macros" -ms.date: "08/19/2019" -f1_keywords: ["_ATL_ALL_WARNINGS", "_ATL_APARTMENT_THREADED", "_ATL_CSTRING_EXPLICIT_CONSTRUCTORS ", "_ATL_ENABLE_PTM_WARNING", "_ATL_FREE_THREADED", "_ATL_MULTI_THREADED", "_ATL_NO_AUTOMATIC_NAMESPACE", "_ATL_NO_COM_SUPPORT", "ATL_NO_VTABLE", "ATL_NOINLINE", "_ATL_SINGLE_THREADED"] +ms.date: 02/01/2023 +f1_keywords: ["_ATL_ALL_WARNINGS", "_ATL_APARTMENT_THREADED", "_ATL_CSTRING_EXPLICIT_CONSTRUCTORS ", "_ATL_ENABLE_PTM_WARNING", "_ATL_FREE_THREADED", "_ATL_MODULES", "_ATL_MULTI_THREADED", "_ATL_NO_AUTOMATIC_NAMESPACE", "_ATL_NO_COM_SUPPORT", "ATL_NO_VTABLE", "ATL_NOINLINE", "_ATL_SINGLE_THREADED"] helpviewer_keywords: ["compiler options, macros"] -ms.assetid: a869adc6-b3de-4299-b040-9ae20b45f82c --- # Compiler Options Macros @@ -12,23 +11,24 @@ These macros control specific compiler features. |Macro|Description| |-|-| -|[_ATL_ALL_WARNINGS](#_atl_all_warnings)|A symbol that enables errors in projects converted from previous versions of ATL.| -|[_ATL_APARTMENT_THREADED](#_atl_apartment_threaded)|Define if one or more of your objects use apartment threading.| -|[_ATL_CSTRING_EXPLICIT_CONSTRUCTORS](#_atl_cstring_explicit_constructors)|Makes certain `CString` constructors explicit, preventing any unintentional conversions.| -|[_ATL_ENABLE_PTM_WARNING](#_atl_enable_ptm_warning)|Define this macro to require C++ standard syntax. It generates the C4867 compiler error when non-standard syntax is used to initialize a pointer to a member function.| -|[_ATL_FREE_THREADED](#_atl_free_threaded)|Define if one or more of your objects use free or neutral threading.| -|[_ATL_MULTI_THREADED](#_atl_multi_threaded)|A symbol that indicates the project will have objects that are marked as Both, Free or Neutral. The macro [_ATL_FREE_THREADED](#_atl_free_threaded) should be used instead.| -|[_ATL_NO_AUTOMATIC_NAMESPACE](#_atl_no_automatic_namespace)|A symbol that prevents the default use of namespace as ATL.| -|[_ATL_NO_COM_SUPPORT](#_atl_no_com_support)|A symbol that prevents COM-related code from being compiled with your project.| -|[ATL_NO_VTABLE](#atl_no_vtable)|A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor.| -|[ATL_NOINLINE](#atl_noinline)|A symbol that indicates a function shouldn't be inlined.| -|[_ATL_SINGLE_THREADED](#_atl_single_threaded)|Define if all of your objects use the single threading model.| - -## _ATL_ALL_WARNINGS +|[`_ATL_ALL_WARNINGS`](#_atl_all_warnings)|A symbol that enables errors in projects converted from previous versions of ATL.| +|[`_ATL_APARTMENT_THREADED`](#_atl_apartment_threaded)|Define if one or more of your objects use apartment threading.| +|[`_ATL_CSTRING_EXPLICIT_CONSTRUCTORS`](#_atl_cstring_explicit_constructors)|Makes certain `CString` constructors explicit, preventing any unintentional conversions.| +|[`_ATL_ENABLE_PTM_WARNING`](#_atl_enable_ptm_warning)|Define this macro to require C++ standard syntax. It generates the C4867 compiler error when nonstandard syntax is used to initialize a pointer to a member function.| +|[`_ATL_FREE_THREADED`](#_atl_free_threaded)|Define if one or more of your objects use free or neutral threading.| +|[`_ATL_MODULES`](#_ATL_MODULES)|Allows you to compile ATL projects with [permissive-](../../build/reference/permissive-standards-conformance.md) and use ATL with [C++ modules](../../cpp/modules-cpp.md).| +|[`_ATL_MULTI_THREADED`](#_atl_multi_threaded)|A symbol that indicates the project has objects marked as Both, Free or Neutral. The macro [`_ATL_FREE_THREADED`](#_atl_free_threaded) should be used instead.| +|[`_ATL_NO_AUTOMATIC_NAMESPACE`](#_atl_no_automatic_namespace)|A symbol that prevents the default use of namespace as ATL.| +|[`_ATL_NO_COM_SUPPORT`](#_atl_no_com_support)|A symbol that prevents COM-related code from being compiled with your project.| +|[`ATL_NO_VTABLE`](#atl_no_vtable)|A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor.| +|[`ATL_NOINLINE`](#atl_noinline)|A symbol that indicates a function shouldn't be inlined.| +|[`_ATL_SINGLE_THREADED`](#_atl_single_threaded)|Define if all of your objects use the single threading model.| + +## `_ATL_ALL_WARNINGS` A symbol that enables errors in projects converted from previous versions of ATL. -``` +```cpp #define _ATL_ALL_WARNINGS ``` @@ -52,7 +52,7 @@ Before Visual C++ .NET 2002, ATL disabled many warnings and left them disabled s In projects converted from previous versions, these warnings are still disabled by the libraries headers. -By adding the following line to the *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier) file before including libraries headers, this behavior can be changed. +To change this behavior, add the following line to the *`pch.h`* (*`stdafx.h`* in Visual Studio 2017 and earlier) file before including libraries headers. [!code-cpp[NVC_ATL_Utilities#97](../../atl/codesnippet/cpp/compiler-options-macros_1.h)] @@ -60,11 +60,11 @@ If this `#define` is added, the ATL headers are careful to preserve the state of New projects have this `#define` set in *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier) by default. -## _ATL_APARTMENT_THREADED +## `_ATL_APARTMENT_THREADED` Define if one or more of your objects use apartment threading. -``` +```cpp _ATL_APARTMENT_THREADED ``` @@ -72,23 +72,23 @@ _ATL_APARTMENT_THREADED Specifies apartment threading. For other options, and a description of the threading models available for an ATL object, see [Specifying the Project's Threading Model](../../atl/specifying-the-threading-model-for-a-project-atl.md) and [Options, ATL Simple Object Wizard](../../atl/reference/options-atl-simple-object-wizard.md). -## _ATL_CSTRING_EXPLICIT_CONSTRUCTORS +## `_ATL_CSTRING_EXPLICIT_CONSTRUCTORS` Makes certain `CString` constructors explicit, preventing any unintentional conversions. -```cpp +``` _ATL_CSTRING_EXPLICIT_CONSTRUCTORS ``` ### Remarks -When this constructor is defined, all CString constructors that take a single parameter are compiled with the explicit keyword, which prevents implicit conversions of input arguments. This means, for example, that when _UNICODE is defined, if you attempt to use a char* string as a CString constructor argument, a compiler error will result. Use this macro in situations where you need to prevent implicit conversions between narrow and wide string types. +When this constructor is defined, all `CString` constructors that take a single parameter are compiled with the explicit keyword, which prevents implicit conversions of input arguments. This means, for example, that when `_UNICODE` is defined, if you attempt to use a `char*` string as a `CString` constructor argument, a compiler error results. Use this macro in situations where you need to prevent implicit conversions between narrow and wide string types. -By using the _T macro on all constructor string arguments, you can define _ATL_CSTRING_EXPLICIT_CONSTRUCTORS and avoid compile errors regardless of whether _UNICODE is defined. +By using the `_T` macro on all constructor string arguments, you can define `_ATL_CSTRING_EXPLICIT_CONSTRUCTORS` and avoid compile errors regardless of whether `_UNICODE` is defined. -## _ATL_ENABLE_PTM_WARNING +## `_ATL_ENABLE_PTM_WARNING` -Define this macro in order to force the use of ANSI C++ standard-conforming syntax for pointer to member functions. Using this macro will cause the C4867 compiler error to be generated when non-standard syntax is used to initialize a pointer to a member function. +Define this macro in order to force the use of ANSI C++ standard-conforming syntax for pointer to member functions. Using this macro causes the C4867 compiler error to be generated when nonstandard syntax is used to initialize a pointer to a member function. ```cpp #define _ATL_ENABLE_PTM_WARNING @@ -98,9 +98,9 @@ Define this macro in order to force the use of ANSI C++ standard-conforming synt The ATL and MFC libraries have been changed to match the Microsoft C++ compiler's improved standard C++ conformance. According to the ANSI C++ standard, the syntax of a pointer to a class member function should be `&CMyClass::MyFunc`. -When [_ATL_ENABLE_PTM_WARNING](#_atl_enable_ptm_warning) is not defined (the default case), ATL/MFC disables the C4867 error in macro maps (notably message maps) so that code that was created in earlier versions can continue to build as before. If you define **_ATL_ENABLE_PTM_WARNING**, your code should conform to the C++ standard. +When [`_ATL_ENABLE_PTM_WARNING`](#_atl_enable_ptm_warning) isn't defined (the default case), ATL/MFC disables the C4867 error in macro maps (notably message maps) so that code that was created in earlier versions can continue to build as before. If you define `_ATL_ENABLE_PTM_WARNING`, your code should conform to the C++ standard. -However, the non-standard form has been deprecated. You need to move existing code to C++ standard syntax. For example, the following code: +However, the nonstandard form has been deprecated. You need to move existing code to C++ standard syntax. For example, the following code: [!code-cpp[NVC_MFCListView#14](../../atl/reference/codesnippet/cpp/compiler-options-macros_2.cpp)] @@ -110,7 +110,7 @@ Should be changed to: For map macros, add the ampersand '&' character. You shouldn't add the character again in your code. -## _ATL_FREE_THREADED +## `_ATL_FREE_THREADED` Define if one or more of your objects use free or neutral threading. @@ -122,9 +122,17 @@ _ATL_FREE_THREADED Specifies free threading. Free threading is equivalent to a multithread apartment model. See [Specifying the Project's Threading Model](../../atl/specifying-the-threading-model-for-a-project-atl.md) for other threading options, and [Options, ATL Simple Object Wizard](../../atl/reference/options-atl-simple-object-wizard.md) for a description of the threading models available for an ATL object. -## _ATL_MULTI_THREADED +## `_ATL_MODULES` + +Allows you to compile ATL projects with [`permissive-`](../../build/reference/permissive-standards-conformance.md) and use ATL with [C++ modules](../../cpp/modules-cpp.md). + +``` +_ATL_MODULES +``` + +## `_ATL_MULTI_THREADED` -A symbol that indicates the project will have objects that are marked as Both, Free or Neutral. +A symbol that indicates the project has objects that are marked as Both, Free or Neutral. ``` _ATL_MULTI_THREADED @@ -132,9 +140,9 @@ _ATL_MULTI_THREADED ### Remarks -If this symbol is defined, ATL will pull in code that will correctly synchronize access to global data. New code should use the equivalent macro [_ATL_FREE_THREADED](#_atl_free_threaded) instead. +If this symbol is defined, ATL pulls in code that will correctly synchronize access to global data. New code should use the equivalent macro [`_ATL_FREE_THREADED`](#_atl_free_threaded) instead. -## _ATL_NO_AUTOMATIC_NAMESPACE +## `_ATL_NO_AUTOMATIC_NAMESPACE` A symbol that prevents the default use of namespace as ATL. @@ -144,9 +152,9 @@ _ATL_NO_AUTOMATIC_NAMESPACE ### Remarks -If this symbol is not defined, including atlbase.h will perform **using namespace ATL** by default, which may lead to naming conflicts. To prevent this, define this symbol. +If this symbol isn't defined, including `atlbase.h` performs `using namespace ATL` by default, which may lead to naming conflicts. To prevent this, define this symbol. -## _ATL_NO_COM_SUPPORT +## `_ATL_NO_COM_SUPPORT` A symbol that prevents COM-related code from being compiled with your project. @@ -154,7 +162,7 @@ A symbol that prevents COM-related code from being compiled with your project. _ATL_NO_COM_SUPPORT ``` -## ATL_NO_VTABLE +## `ATL_NO_VTABLE` A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor. @@ -164,13 +172,13 @@ ATL_NO_VTABLE ### Remarks -If the vtable pointer is prevented from being initialized in the class's constructor and destructor, the linker can eliminate the vtable and all of the functions to which it points. Expands to **`__declspec(novtable)`**. +If the vtable pointer is prevented from being initialized in the class's constructor and destructor, the linker can eliminate the vtable and all of the functions to which it points. Expands to `__declspec(novtable)`. ### Example [!code-cpp[NVC_ATL_COM#53](../../atl/codesnippet/cpp/compiler-options-macros_4.h)] -## ATL_NOINLINE +## `ATL_NOINLINE` A symbol that indicates a function shouldn't be inlined. @@ -184,14 +192,14 @@ A symbol that indicates a function shouldn't be inlined. ### Parameters -*myfunction*
-The function that should not be inlined. +*`myfunction`*\ +The function that shouldn't be inlined. ### Remarks -Use this symbol if you want to ensure a function does not get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to **`__declspec(noinline)`**. +Use this symbol if you want to ensure a function doesn't get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to `__declspec(noinline)`. -## _ATL_SINGLE_THREADED +## `_ATL_SINGLE_THREADED` Define if all of your objects use the single threading model diff --git a/docs/atl/reference/composite-control-macros.md b/docs/atl/reference/composite-control-macros.md index 2d9e4e9fee..9721f16031 100644 --- a/docs/atl/reference/composite-control-macros.md +++ b/docs/atl/reference/composite-control-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Composite Control Macros" title: "Composite Control Macros" ms.date: "05/06/2019" -f1_keywords: ["atlcom/ATL::BEGIN_SINK_MAP", "atlcom/ATL::END_SINK_MAP", "atlcom/ATL::SINK_ENTRY"] +f1_keywords: ["atlcom/ATL::BEGIN_SINK_MAP", "atlcom/ATL::END_SINK_MAP", "atlcom/ATL::SINK_ENTRY", "ATLCOM/BEGIN_SINK_MAP", "ATLCOM/END_SINK_MAP", "ATLCOM/SINK_ENTRY", "ATLCOM/SINK_ENTRY_EX", "ATLCOM/SINK_ENTRY_EX_P", "ATLCOM/SINK_ENTRY_INFO", "ATLCOM/SINK_ENTRY_INFO_P", "BEGIN_SINK_MAP", "END_SINK_MAP", "SINK_ENTRY", "SINK_ENTRY_EX", "SINK_ENTRY_EX_P", "SINK_ENTRY_INFO", "SINK_ENTRY_INFO_P"] helpviewer_keywords: ["composite controls, macros"] ms.assetid: 17f2dd5e-07e6-4aa6-b965-7a361c78c45e --- @@ -15,7 +15,7 @@ These macros define event sink maps and entries. |[BEGIN_SINK_MAP](#begin_sink_map)|Marks the beginning of the event sink map for the composite control.| |[END_SINK_MAP](#end_sink_map)|Marks the end of the event sink map for the composite control.| |[SINK_ENTRY](#sink_entry)|Entry to the event sink map.| -|[SINK_ENTRY_EX](#sink_entry_ex)|Entry to the event sink map with an additional parameter.| +|[SINK_ENTRY_EX](#sink_entry_ex)|Entry to the event sink map with an extra parameter.| |[SINK_ENTRY_EX_P](#sink_entry_ex)| (Visual Studio 2017) Similar to SINK_ENTRY_EX except that it takes a pointer to iid.| |[SINK_ENTRY_INFO](#sink_entry_info)|Entry to the event sink map with manually supplied type information for use with [IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md).| |[SINK_ENTRY_INFO_P](#sink_entry_info)| (Visual Studio 2017) Similar to SINK_ENTRY_INFO except that it takes a pointer to iid.| @@ -43,7 +43,7 @@ BEGIN_SINK_MAP(_class) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## END_SINK_MAP @@ -59,7 +59,7 @@ END_SINK_MAP() ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY @@ -86,7 +86,7 @@ SINK_ENTRY( id, dispid, fn ) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY_EX and SINK_ENTRY_EX_P @@ -120,7 +120,7 @@ SINK_ENTRY_EX_P( id, piid, dispid, fn ) // (Visual Studio 2017) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY_INFO and SINK_ENTRY_INFO_P @@ -153,7 +153,7 @@ SINK_ENTRY_INFO_P( id, piid, dispid, fn, info ) // (Visual Studio 2017) ### Remarks -The first four macro parameters are the same as those for the [SINK_ENTRY_EX](#sink_entry_ex) macro. The final parameter provides type information for the event. CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +The first four macro parameters are the same as the ones for the [SINK_ENTRY_EX](#sink_entry_ex) macro. The final parameter provides type information for the event. CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## See also diff --git a/docs/atl/reference/connection-point-macros.md b/docs/atl/reference/connection-point-macros.md index 5fb40db7d0..490abb2c38 100644 --- a/docs/atl/reference/connection-point-macros.md +++ b/docs/atl/reference/connection-point-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Connection Point Macros" title: "Connection Point Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_CONNECTION_POINT_MAP", "atlcom/ATL::END_CONNECTION_POINT_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_CONNECTION_POINT_MAP", "atlcom/ATL::END_CONNECTION_POINT_MAP", "ATLCOM/BEGIN_CONNECTION_POINT_MAP", "ATLCOM/END_CONNECTION_POINT_MAP", "ATLCOM/CONNECTION_POINT_ENTRY", "ATLCOM/CONNECTION_POINT_ENTRY_P", "BEGIN_CONNECTION_POINT_MAP", "END_CONNECTION_POINT_MAP", "CONNECTION_POINT_ENTRY", "CONNECTION_POINT_ENTRY_P"] helpviewer_keywords: ["connection points [C++], macros"] ms.assetid: cc3a6dd3-5538-45df-b027-1f34963c31e5 --- diff --git a/docs/atl/reference/cregkey-class.md b/docs/atl/reference/cregkey-class.md index 6738e5cb07..175495ad2e 100644 --- a/docs/atl/reference/cregkey-class.md +++ b/docs/atl/reference/cregkey-class.md @@ -4,9 +4,8 @@ title: "CRegKey Class" ms.date: "11/04/2016" f1_keywords: ["CRegKey", "ATLBASE/ATL::CRegKey", "ATLBASE/ATL::CRegKey::CRegKey", "ATLBASE/ATL::CRegKey::Attach", "ATLBASE/ATL::CRegKey::Close", "ATLBASE/ATL::CRegKey::Create", "ATLBASE/ATL::CRegKey::DeleteSubKey", "ATLBASE/ATL::CRegKey::DeleteValue", "ATLBASE/ATL::CRegKey::Detach", "ATLBASE/ATL::CRegKey::EnumKey", "ATLBASE/ATL::CRegKey::Flush", "ATLBASE/ATL::CRegKey::GetKeySecurity", "ATLBASE/ATL::CRegKey::NotifyChangeKeyValue", "ATLBASE/ATL::CRegKey::Open", "ATLBASE/ATL::CRegKey::QueryBinaryValue", "ATLBASE/ATL::CRegKey::QueryDWORDValue", "ATLBASE/ATL::CRegKey::QueryGUIDValue", "ATLBASE/ATL::CRegKey::QueryMultiStringValue", "ATLBASE/ATL::CRegKey::QueryQWORDValue", "ATLBASE/ATL::CRegKey::QueryStringValue", "ATLBASE/ATL::CRegKey::QueryValue", "ATLBASE/ATL::CRegKey::RecurseDeleteKey", "ATLBASE/ATL::CRegKey::SetBinaryValue", "ATLBASE/ATL::CRegKey::SetDWORDValue", "ATLBASE/ATL::CRegKey::SetGUIDValue", "ATLBASE/ATL::CRegKey::SetKeySecurity", "ATLBASE/ATL::CRegKey::SetKeyValue", "ATLBASE/ATL::CRegKey::SetMultiStringValue", "ATLBASE/ATL::CRegKey::SetQWORDValue", "ATLBASE/ATL::CRegKey::SetStringValue", "ATLBASE/ATL::CRegKey::SetValue", "ATLBASE/ATL::CRegKey::m_hKey", "ATLBASE/ATL::CRegKey::m_pTM"] helpviewer_keywords: ["CRegKey class", "ATL, registry", "registry, deleting values", "registry, writing to", "registry, deleting keys"] -ms.assetid: 3afce82b-ba2c-4c1a-8404-dc969e1af74b --- -# CRegKey Class +# `CRegKey` Class This class provides methods for manipulating entries in the system registry. @@ -25,55 +24,55 @@ class CRegKey |Name|Description| |----------|-----------------| -|[CRegKey::CRegKey](#cregkey)|The constructor.| -|[CRegKey::~CRegKey](#dtor)|The destructor.| +|[`CRegKey::CRegKey`](#cregkey)|The constructor.| +|[`CRegKey::~CRegKey`](#dtor)|The destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CRegKey::Attach](#attach)|Call this method to attach an HKEY to the `CRegKey` object by setting the [m_hKey](#m_hkey) member handle to `hKey`.| -|[CRegKey::Close](#close)|Call this method to release the [m_hKey](#m_hkey) member handle and set it to NULL.| -|[CRegKey::Create](#create)|Call this method to create the specified key, if it does not exist as a subkey of `hKeyParent`.| -|[CRegKey::DeleteSubKey](#deletesubkey)|Call this method to remove the specified key from the registry.| -|[CRegKey::DeleteValue](#deletevalue)|Call this method to remove a value field from [m_hKey](#m_hkey).| -|[CRegKey::Detach](#detach)|Call this method to detach the [m_hKey](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to NULL.| -|[CRegKey::EnumKey](#enumkey)|Call this method to enumerate the subkeys of the open registry key.| -|[CRegKey::Flush](#flush)|Call this method to write all of the attributes of the open registry key into the registry.| -|[CRegKey::GetKeySecurity](#getkeysecurity)|Call this method to retrieve a copy of the security descriptor protecting the open registry key.| -|[CRegKey::NotifyChangeKeyValue](#notifychangekeyvalue)|This method notifies the caller about changes to the attributes or contents of the open registry key.| -|[CRegKey::Open](#open)|Call this method to open the specified key and set [m_hKey](#m_hkey) to the handle of this key.| -|[CRegKey::QueryBinaryValue](#querybinaryvalue)|Call this method to retrieve the binary data for a specified value name.| -|[CRegKey::QueryDWORDValue](#querydwordvalue)|Call this method to retrieve the DWORD data for a specified value name.| -|[CRegKey::QueryGUIDValue](#queryguidvalue)|Call this method to retrieve the GUID data for a specified value name.| -|[CRegKey::QueryMultiStringValue](#querymultistringvalue)|Call this method to retrieve the multistring data for a specified value name.| -|[CRegKey::QueryQWORDValue](#queryqwordvalue)|Call this method to retrieve the QWORD data for a specified value name.| -|[CRegKey::QueryStringValue](#querystringvalue)|Call this method to retrieve the string data for a specified value name.| -|[CRegKey::QueryValue](#queryvalue)|Call this method to retrieve the data for the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.| -|[CRegKey::RecurseDeleteKey](#recursedeletekey)|Call this method to remove the specified key from the registry and explicitly remove any subkeys.| -|[CRegKey::SetBinaryValue](#setbinaryvalue)|Call this method to set the binary value of the registry key.| -|[CRegKey::SetDWORDValue](#setdwordvalue)|Call this method to set the DWORD value of the registry key.| -|[CRegKey::SetGUIDValue](#setguidvalue)|Call this method to set the GUID value of the registry key.| -|[CRegKey::SetKeySecurity](#setkeysecurity)|Call this method to set the security of the registry key.| -|[CRegKey::SetKeyValue](#setkeyvalue)|Call this method to store data in a specified value field of a specified key.| -|[CRegKey::SetMultiStringValue](#setmultistringvalue)|Call this method to set the multistring value of the registry key.| -|[CRegKey::SetQWORDValue](#setqwordvalue)|Call this method to set the QWORD value of the registry key.| -|[CRegKey::SetStringValue](#setstringvalue)|Call this method to set the string value of the registry key.| -|[CRegKey::SetValue](#setvalue)|Call this method to store data in the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.| +|[`CRegKey::Attach`](#attach)|Call this method to attach an HKEY to the `CRegKey` object by setting the [`m_hKey`](#m_hkey) member handle to `hKey`.| +|[`CRegKey::Close`](#close)|Call this method to release the [`m_hKey`](#m_hkey) member handle and set it to `NULL`.| +|[`CRegKey::Create`](#create)|Call this method to create the specified key, if it doesn't exist as a subkey of `hKeyParent`.| +|[`CRegKey::DeleteSubKey`](#deletesubkey)|Call this method to remove the specified key from the registry.| +|[`CRegKey::DeleteValue`](#deletevalue)|Call this method to remove a value field from [`m_hKey`](#m_hkey).| +|[`CRegKey::Detach`](#detach)|Call this method to detach the [`m_hKey`](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to `NULL`.| +|[`CRegKey::EnumKey`](#enumkey)|Call this method to enumerate the subkeys of the open registry key.| +|[`CRegKey::Flush`](#flush)|Call this method to write all of the attributes of the open registry key into the registry.| +|[`CRegKey::GetKeySecurity`](#getkeysecurity)|Call this method to retrieve a copy of the security descriptor protecting the open registry key.| +|[`CRegKey::NotifyChangeKeyValue`](#notifychangekeyvalue)|This method notifies the caller about changes to the attributes or contents of the open registry key.| +|[`CRegKey::Open`](#open)|Call this method to open the specified key and set [`m_hKey`](#m_hkey) to the handle of this key.| +|[`CRegKey::QueryBinaryValue`](#querybinaryvalue)|Call this method to retrieve the binary data for a specified value name.| +|[`CRegKey::QueryDWORDValue`](#querydwordvalue)|Call this method to retrieve the `DWORD` data for a specified value name.| +|[`CRegKey::QueryGUIDValue`](#queryguidvalue)|Call this method to retrieve the GUID data for a specified value name.| +|[`CRegKey::QueryMultiStringValue`](#querymultistringvalue)|Call this method to retrieve the multistring data for a specified value name.| +|[`CRegKey::QueryQWORDValue`](#queryqwordvalue)|Call this method to retrieve the `QWORD` data for a specified value name.| +|[`CRegKey::QueryStringValue`](#querystringvalue)|Call this method to retrieve the string data for a specified value name.| +|[`CRegKey::QueryValue`](#queryvalue)|Call this method to retrieve the data for the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`.| +|[`CRegKey::RecurseDeleteKey`](#recursedeletekey)|Call this method to remove the specified key from the registry and explicitly remove any subkeys.| +|[`CRegKey::SetBinaryValue`](#setbinaryvalue)|Call this method to set the binary value of the registry key.| +|[`CRegKey::SetDWORDValue`](#setdwordvalue)|Call this method to set the `DWORD` value of the registry key.| +|[`CRegKey::SetGUIDValue`](#setguidvalue)|Call this method to set the GUID value of the registry key.| +|[`CRegKey::SetKeySecurity`](#setkeysecurity)|Call this method to set the security of the registry key.| +|[`CRegKey::SetKeyValue`](#setkeyvalue)|Call this method to store data in a specified value field of a specified key.| +|[`CRegKey::SetMultiStringValue`](#setmultistringvalue)|Call this method to set the multistring value of the registry key.| +|[`CRegKey::SetQWORDValue`](#setqwordvalue)|Call this method to set the `QWORD` value of the registry key.| +|[`CRegKey::SetStringValue`](#setstringvalue)|Call this method to set the string value of the registry key.| +|[`CRegKey::SetValue`](#setvalue)|Call this method to store data in the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`.| ### Public Operators |Name|Description| |----------|-----------------| -|[CRegKey::operator HKEY](#operator_hkey)|Converts a `CRegKey` object to an HKEY.| -|[CRegKey::operator =](#operator_eq)|Assignment operator.| +|[`CRegKey::operator HKEY`](#operator_hkey)|Converts a `CRegKey` object to an `HKEY`.| +|[`CRegKey::operator =`](#operator_eq)|Assignment operator.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CRegKey::m_hKey](#m_hkey)|Contains a handle of the registry key associated with the `CRegKey` object.| -|[CRegKey::m_pTM](#m_ptm)|Pointer to `CAtlTransactionManager` object| +|[`CRegKey::m_hKey`](#m_hkey)|Contains a handle of the registry key associated with the `CRegKey` object.| +|[`CRegKey::m_pTM`](#m_ptm)|Pointer to `CAtlTransactionManager` object| ## Remarks @@ -81,18 +80,18 @@ class CRegKey `CRegKey` provides a programming interface to the system registry for a given machine. For example, to open a particular registry key, call `CRegKey::Open`. To retrieve or modify a data value, call `CRegKey::QueryValue` or `CRegKey::SetValue`, respectively. To close a key, call `CRegKey::Close`. -When you close a key, its registry data is written (flushed) to the hard disk. This process may take several seconds. If your application must explicitly write registry data to the hard disk, you can call the [RegFlushKey](/windows/win32/api/winreg/nf-winreg-regflushkey) Win32 function. However, `RegFlushKey` uses many system resources and should be called only when absolutely necessary. +When you close a key, its registry data is written (flushed) to the hard disk. This process may take several seconds. If your application must explicitly write registry data to the hard disk, you can call the [`RegFlushKey`](/windows/win32/api/winreg/nf-winreg-regflushkey) Win32 function. However, `RegFlushKey` uses many system resources and should be called only when absolutely necessary. > [!IMPORTANT] -> Any methods that allow the caller to specify a registry location have the potential to read data that cannot be trusted. Methods that make use of [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) should take into consideration that this function does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> Any methods that allow the caller to specify a registry location have the potential to read data that cannot be trusted. Methods that make use of [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) should take into consideration that this function does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. ## Requirements -**Header:** atlbase.h +**Header:** `atlbase.h` -## CRegKey::Attach +## `CRegKey::Attach` -Call this method to attach an HKEY to the `CRegKey` object by setting the [m_hKey](#m_hkey) member handle to *hKey*. +Call this method to attach an `HKEY` to the `CRegKey` object by setting the [`m_hKey`](#m_hkey) member handle to *`hKey`*. ```cpp void Attach(HKEY hKey) throw(); @@ -100,16 +99,16 @@ void Attach(HKEY hKey) throw(); ### Parameters -*hKey*
+`hKey`\ The handle of a registry key. ### Remarks -`Attach` will assert if `m_hKey` is non-NULL. +`Attach` will assert if `m_hKey` is non-`NULL`. -## CRegKey::Close +## `CRegKey::Close` -Call this method to release the [m_hKey](#m_hkey) member handle and set it to NULL. +Call this method to release the [`m_hKey`](#m_hkey) member handle and set it to `NULL`. ``` LONG Close() throw(); @@ -117,11 +116,11 @@ LONG Close() throw(); ### Return Value -If successful, returns ERROR_SUCCESS; otherwise returns an error value. +If successful, returns `ERROR_SUCCESS`; otherwise returns an error value. -## CRegKey::Create +## `CRegKey::Create` -Call this method to create the specified key, if it does not exist as a subkey of *hKeyParent*. +Call this method to create the specified key, if it doesn't exist as a subkey of *`hKeyParent`*. ``` LONG Create( @@ -136,36 +135,36 @@ LONG Create( ### Parameters -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*lpszClass*
+*`lpszClass`*\ Specifies the class of the key to be created or opened. The default value is REG_NONE. -*dwOptions*
-Options for the key. The default value is REG_OPTION_NON_VOLATILE. For a list of possible values and descriptions, see [RegCreateKeyEx](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. +*`dwOptions`*\ +Options for the key. The default value is `REG_OPTION_NON_VOLATILE`. For a list of possible values and descriptions, see [`RegCreateKeyEx`](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. -*samDesired*
-The security access for the key. The default value is KEY_READ | KEY_WRITE. For a list of possible values and descriptions, see `RegCreateKeyEx`. +*`samDesired`*\ +The security access for the key. The default value is `KEY_READ | KEY_WRITE`. For a list of possible values and descriptions, see `RegCreateKeyEx`. -*lpSecAttr*
-A pointer to a [SECURITY_ATTRIBUTES](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is NULL (meaning the handle cannot be inherited). +*`lpSecAttr`*\ +A pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is `NULL` (meaning the handle can't be inherited). -*lpdwDisposition*
-[out] If non-NULL, retrieves either REG_CREATED_NEW_KEY (if the key did not exist and was created) or REG_OPENED_EXISTING_KEY (if the key existed and was opened). +*`lpdwDisposition`*\ +[out] If non-`NULL`, retrieves either `REG_CREATED_NEW_KEY` (if the key didn't exist and was created) or `REG_OPENED_EXISTING_KEY` (if the key existed and was opened). ### Return Value -If successful, returns ERROR_SUCCESS and opens the key. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS` and opens the key. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -`Create` sets the [m_hKey](#m_hkey) member to the handle of this key. +`Create` sets the [`m_hKey`](#m_hkey) member to the handle of this key. -## CRegKey::CRegKey +## `CRegKey::CRegKey` The constructor. @@ -178,20 +177,20 @@ CRegKey(CAtlTransactionManager* pTM) throw(); ### Parameters -*key*
+*`key`*\ A reference to a `CRegKey` object. -*hKey*
+`hKey`\ A handle to a registry key. -*pTM*
-Pointer to CAtlTransactionManager object +*`pTM`*\ +Pointer to `CAtlTransactionManager` object ### Remarks Creates a new `CRegKey` object. The object can be created from an existing `CRegKey` object, or from a handle to a registry key. -## CRegKey::~CRegKey +## `CRegKey::~CRegKey` The destructor. @@ -203,7 +202,7 @@ The destructor. The destructor releases `m_hKey`. -## CRegKey::DeleteSubKey +## `CRegKey::DeleteSubKey` Call this method to remove the specified key from the registry. @@ -213,20 +212,20 @@ LONG DeleteSubKey(LPCTSTR lpszSubKey) throw(); ### Parameters -*lpszSubKey*
-Specifies the name of the key to delete. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszSubKey`*\ +Specifies the name of the key to delete. This name must be a subkey of [`m_hKey`](#m_hkey). ### Return Value -If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -`DeleteSubKey` can only delete a key that has no subkeys. If the key has subkeys, call [RecurseDeleteKey](#recursedeletekey) instead. +`DeleteSubKey` can only delete a key that has no subkeys. If the key has subkeys, call [`RecurseDeleteKey`](#recursedeletekey) instead. -## CRegKey::DeleteValue +## `CRegKey::DeleteValue` -Call this method to remove a value field from [m_hKey](#m_hkey). +Call this method to remove a value field from [`m_hKey`](#m_hkey). ``` LONG DeleteValue(LPCTSTR lpszValue) throw(); @@ -234,16 +233,16 @@ LONG DeleteValue(LPCTSTR lpszValue) throw(); ### Parameters -*lpszValue*
+*`lpszValue`*\ Specifies the value field to remove. ### Return Value -If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. -## CRegKey::Detach +## `CRegKey::Detach` -Call this method to detach the [m_hKey](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to NULL. +Call this method to detach the [`m_hKey`](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to `NULL`. ``` HKEY Detach() throw(); @@ -253,7 +252,7 @@ HKEY Detach() throw(); The HKEY associated with the `CRegKey` object. -## CRegKey::EnumKey +## `CRegKey::EnumKey` Call this method to enumerate the subkeys of the open registry key. @@ -267,27 +266,27 @@ LONG EnumKey( ### Parameters -*iIndex*
+*`iIndex`*\ The subkey index. This parameter should be zero for the first call and then incremented for subsequent calls -*pszName*
+*`pszName`*\ Pointer to a buffer that receives the name of the subkey, including the terminating null character. Only the name of the subkey is copied to the buffer, not the full key hierarchy. -*pnNameLength*
-Pointer to a variable that specifies the size, in TCHARs, of the buffer specified by the *pszName* parameter. This size should include the terminating null character. When the method returns, the variable pointed to by *pnNameLength* contains the number of characters stored in the buffer. The count returned does not include the terminating null character. +*`pnNameLength`*\ +Pointer to a variable that specifies the size, in `TCHARs`, of the buffer specified by the *`pszName`* parameter. This size should include the terminating null character. When the method returns, the variable pointed to by *`pnNameLength`* contains the number of characters stored in the buffer. The count returned doesn't include the terminating null character. -*pftLastWriteTime*
+*`pftLastWriteTime`*\ Pointer to a variable that receives the time the enumerated subkey was last written to. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -To enumerate the subkeys, call `CRegKey::EnumKey` with an index of zero. Increment the index value and repeat until the method returns ERROR_NO_MORE_ITEMS. For more information, see [RegEnumKeyEx](/windows/win32/api/winreg/nf-winreg-regenumkeyexw) in the Windows SDK. +To enumerate the subkeys, call `CRegKey::EnumKey` with an index of zero. Increment the index value and repeat until the method returns `ERROR_NO_MORE_ITEMS`. For more information, see [`RegEnumKeyEx`](/windows/win32/api/winreg/nf-winreg-regenumkeyexw) in the Windows SDK. -## CRegKey::Flush +## `CRegKey::Flush` Call this method to write all of the attributes of the open registry key into the registry. @@ -297,13 +296,13 @@ LONG Flush() throw(); ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -For more information, see [RegEnumFlush](/windows/win32/api/winreg/nf-winreg-regflushkey) in the Windows SDK. +For more information, see [`RegEnumFlush`](/windows/win32/api/winreg/nf-winreg-regflushkey) in the Windows SDK. -## CRegKey::GetKeySecurity +## `CRegKey::GetKeySecurity` Call this method to retrieve a copy of the security descriptor protecting the open registry key. @@ -316,24 +315,24 @@ LONG GetKeySecurity( ### Parameters -*si*
-The [SECURITY_INFORMATION](/windows/win32/SecAuthZ/security-information) value that indicates the requested security information. +*`si`*\ +The [`SECURITY_INFORMATION`](/windows/win32/SecAuthZ/security-information) value that indicates the requested security information. -*psd*
+*`psd`*\ A pointer to a buffer that receives a copy of the requested security descriptor. -*pnBytes*
-The size, in bytes, of the buffer pointed to by *psd*. +*`pnBytes`*\ +The size, in bytes, of the buffer pointed to by *`psd`*. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code is defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code is defined in `WINERROR.H`. ### Remarks -For more information, see [RegGetKeySecurity](/windows/win32/api/winreg/nf-winreg-reggetkeysecurity). +For more information, see [`RegGetKeySecurity`](/windows/win32/api/winreg/nf-winreg-reggetkeysecurity). -## CRegKey::m_hKey +## `CRegKey::m_hKey` Contains a handle of the registry key associated with the `CRegKey` object. @@ -341,7 +340,7 @@ Contains a handle of the registry key associated with the `CRegKey` object. HKEY m_hKey; ``` -## CRegKey::m_pTM +## `CRegKey::m_pTM` Pointer to a `CAtlTransactionManager` object. @@ -351,7 +350,7 @@ CAtlTransactionManager* m_pTM; ### Remarks -## CRegKey::NotifyChangeKeyValue +## `CRegKey::NotifyChangeKeyValue` This method notifies the caller about changes to the attributes or contents of the open registry key. @@ -365,39 +364,39 @@ LONG NotifyChangeKeyValue( ### Parameters -*bWatchSubtree*
-Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the method reports changes in the key and its subkeys. If the parameter is FALSE, the method reports changes only in the key. +*`bWatchSubtree`*\ +Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is `TRUE`, the method reports changes in the key and its subkeys. If the parameter is `FALSE`, the method reports changes only in the key. -*dwNotifyFilter*
+*`dwNotifyFilter`*\ Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values: |Value|Meaning| |-----------|-------------| -|REG_NOTIFY_CHANGE_NAME|Notify the caller if a subkey is added or deleted.| -|REG_NOTIFY_CHANGE_ATTRIBUTES|Notify the caller of changes to the attributes of the key, such as the security descriptor information.| -|REG_NOTIFY_CHANGE_LAST_SET|Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.| -|REG_NOTIFY_CHANGE_SECURITY|Notify the caller of changes to the security descriptor of the key.| +|`REG_NOTIFY_CHANGE_NAME`|Notify the caller if a subkey is added or deleted.| +|`REG_NOTIFY_CHANGE_ATTRIBUTES`|Notify the caller of changes to the attributes of the key, such as the security descriptor information.| +|`REG_NOTIFY_CHANGE_LAST_SET`|Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.| +|`REG_NOTIFY_CHANGE_SECURITY`|Notify the caller of changes to the security descriptor of the key.| -*hEvent*
-Handle to an event. If the *bAsync* parameter is TRUE, the method returns immediately and changes are reported by signaling this event. If *bAsync* is FALSE, *hEvent* is ignored. +*`hEvent`*\ +Handle to an event. If the *`bAsync`* parameter is `TRUE`, the method returns immediately and changes are reported by signaling this event. If *`bAsync`* is `FALSE`, *`hEvent`* is ignored. -*bAsync*
-Specifies a flag that indicates how the method reports changes. If this parameter is TRUE, the method returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the method does not return until a change has occurred. If *hEvent* does not specify a valid event, the *bAsync* parameter cannot be TRUE. +*`bAsync`*\ +Specifies a flag that indicates how the method reports changes. If this parameter is `TRUE`, the method returns immediately and reports changes by signaling the specified event. When this parameter is `FALSE`, the method doesn't return until a change has occurred. If *`hEvent`* doesn't specify a valid event, the *`bAsync`* parameter can't be `TRUE`. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks > [!NOTE] > This method does not notify the caller if the specified key is deleted. -For more details and a sample program, see [RegNotifyChangeKeyValue](/windows/win32/api/winreg/nf-winreg-regnotifychangekeyvalue). +For more details and a sample program, see [`RegNotifyChangeKeyValue`](/windows/win32/api/winreg/nf-winreg-regnotifychangekeyvalue). -## CRegKey::Open +## `CRegKey::Open` -Call this method to open the specified key and set [m_hKey](#m_hkey) to the handle of this key. +Call this method to open the specified key and set [`m_hKey`](#m_hkey) to the handle of this key. ``` LONG Open( @@ -408,34 +407,34 @@ LONG Open( ### Parameters -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*samDesired*
-The security access for the key. The default value is KEY_ALL_ACCESS. For a list of possible values and descriptions, see [RegCreateKeyEx](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. +*`samDesired`*\ +The security access for the key. The default value is `KEY_ALL_ACCESS`. For a list of possible values and descriptions, see [`RegCreateKeyEx`](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a non-zero error value defined in `WINERROR.H`. ### Remarks -If the *lpszKeyName* parameter is NULL or points to an empty string, `Open` opens a new handle of the key identified by *hKeyParent*, but does not close any previously opened handle. +If the *`lpszKeyName`* parameter is `NULL` or points to an empty string, `Open` opens a new handle of the key identified by *`hKeyParent`*, but doesn't close any previously opened handle. -Unlike [CRegKey::Create](#create), `Open` will not create the specified key if it does not exist. +Unlike [`CRegKey::Create`](#create), `Open` won't create the specified key if it doesn't exist. -## CRegKey::operator HKEY +## `CRegKey::operator HKEY` -Converts a `CRegKey` object to an HKEY. +Converts a `CRegKey` object to an `HKEY`. ``` operator HKEY() const throw(); ``` -## CRegKey::operator = +## `CRegKey::operator =` Assignment operator. @@ -445,7 +444,7 @@ CRegKey& operator= (CRegKey& key) throw(); ### Parameters -*key*
+*`key`*\ The key to copy. ### Return Value @@ -454,9 +453,9 @@ Returns a reference to the new key. ### Remarks -This operator detaches *key* from its current object and assigns it to the `CRegKey` object instead. +This operator detaches *`key`* from its current object and assigns it to the `CRegKey` object instead. -## CRegKey::QueryBinaryValue +## `CRegKey::QueryBinaryValue` Call this method to retrieve the binary data for a specified value name. @@ -469,29 +468,29 @@ LONG QueryBinaryValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pValue*
+*`pValue`*\ Pointer to a buffer that receives the value's data. -*pnBytes*
-Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *pValue* parameter. When the method returns, this variable contains the size of the data copied to the buffer. +*`pnBytes`*\ +Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *`pValue`* parameter. When the method returns, this variable contains the size of the data copied to the buffer. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_BINARY, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_BINARY`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryDWORDValue +## `CRegKey::QueryDWORDValue` -Call this method to retrieve the DWORD data for a specified value name. +Call this method to retrieve the `DWORD` data for a specified value name. ``` LONG QueryDWORDValue( @@ -501,24 +500,24 @@ LONG QueryDWORDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*dwValue*
-Pointer to a buffer that receives the DWORD. +*`dwValue`*\ +Pointer to a buffer that receives the `DWORD`. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_DWORD, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_DWORD`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryGUIDValue +## `CRegKey::QueryGUIDValue` Call this method to retrieve the GUID data for a specified value name. @@ -530,24 +529,24 @@ LONG QueryGUIDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*guidValue*
+*`guidValue`*\ Pointer to a variable that receives the GUID. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not a valid GUID, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't a valid GUID, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `CRegKey::QueryStringValue` and converts the string into a GUID using [CLSIDFromString](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromstring). +This method makes use of `CRegKey::QueryStringValue` and converts the string into a GUID using [`CLSIDFromString`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromstring). > [!IMPORTANT] > This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. -## CRegKey::QueryMultiStringValue +## `CRegKey::QueryMultiStringValue` Call this method to retrieve the multistring data for a specified value name. @@ -560,29 +559,29 @@ LONG QueryMultiStringValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pszValue*
-Pointer to a buffer that receives the multistring data. A multistring is an array of null-terminated strings, terminated by two null characters. +*`pszValue`*\ +Pointer to a buffer that receives the multistring data. A multistring is an array of `NULL`-terminated strings, terminated by two null characters. -*pnChars*
-The size, in TCHARs, of the buffer pointed to by *pszValue*. When the method returns, *pnChars* contains the size, in TCHARs, of the multistring retrieved, including a terminating null character. +*`pnChars`*\ +The size, in `TCHARs`, of the buffer pointed to by *`pszValue`*. When the method returns, *`pnChars`* contains the size, in `TCHARs`, of the multistring retrieved, including a terminating null character. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_MULTI_SZ, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_MULTI_SZ`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryQWORDValue +## `CRegKey::QueryQWORDValue` -Call this method to retrieve the QWORD data for a specified value name. +Call this method to retrieve the `QWORD` data for a specified value name. ``` LONG QueryQWORDValue( @@ -592,24 +591,24 @@ LONG QueryQWORDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*qwValue*
-Pointer to a buffer that receives the QWORD. +*`qwValue`*\ +Pointer to a buffer that receives the `QWORD`. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_QWORD, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_QWORD`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryStringValue +## `CRegKey::QueryStringValue` Call this method to retrieve the string data for a specified value name. @@ -622,29 +621,29 @@ LONG QueryStringValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pszValue*
+*`pszValue`*\ Pointer to a buffer that receives the string data. -*pnChars*
-The size, in TCHARs, of the buffer pointed to by *pszValue*. When the method returns, *pnChars* contains the size, in TCHARs, of the string retrieved, including a terminating null character. +*`pnChars`*\ +The size, in TCHARs, of the buffer pointed to by *`pszValue`*. When the method returns, *`pnChars`* contains the size, in `TCHARs`, of the string retrieved, including a terminating null character. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_SZ, ERROR_INVALID_DATA is returned. If the method returns ERROR_MORE_DATA, *pnChars* equals zero, not the required buffer size in bytes. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_SZ`, `ERROR_INVALID_DATA` is returned. If the method returns `ERROR_MORE_DATA`, *`pnChars`* equals zero, not the required buffer size in bytes. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryValue +## `CRegKey::QueryValue` -Call this method to retrieve the data for the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED. +Call this method to retrieve the data for the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`. ``` LONG QueryValue( @@ -665,44 +664,44 @@ ATL_DEPRECATED LONG QueryValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. If *pszValueName* is NULL or an empty string, "", the method retrieves the type and data for the key's unnamed or default value, if any. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. If *`pszValueName`* is `NULL` or an empty string, `""`, the method retrieves the type and data for the key's unnamed or default value, if any. -*pdwType*
-Pointer to a variable that receives a code indicating the type of data stored in the specified value. The *pdwType* parameter can be NULL if the type code is not required. +*`pdwType`*\ +Pointer to a variable that receives a code indicating the type of data stored in the specified value. The *`pdwType`* parameter can be `NULL` if the type code isn't required. -*pData*
-Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required. +*`pData`*\ +Pointer to a buffer that receives the value's data. This parameter can be `NULL` if the data isn't required. -*pnBytes*
-Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *pData* parameter. When the method returns, this variable contains the size of the data copied to *pData.* +*`pnBytes`*\ +Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *`pData`* parameter. When the method returns, this variable contains the size of the data copied to *`pData`*. -*dwValue*
+*`dwValue`*\ The value field's numerical data. -*lpszValueName*
+*`lpszValueName`*\ Specifies the value field to be queried. -*szValue*
+*`szValue`*\ The value field's string data. -*pdwCount*
-The size of the string data. Its value is initially set to the size of the *szValue* buffer. +*`pdwCount`*\ +The size of the string data. Its value is initially set to the size of the *`szValue`* buffer. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -The two original versions of `QueryValue` are no longer supported and are marked as ATL_DEPRECATED. The compiler will issue a warning if these forms are used. +The two original versions of `QueryValue` are no longer supported and are marked as `ATL_DEPRECATED`. The compiler will issue a warning if these forms are used. -The remaining method calls RegQueryValueEx. +The remaining method calls `RegQueryValueEx`. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the `RegQueryValueEx` function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::RecurseDeleteKey +## `CRegKey::RecurseDeleteKey` Call this method to remove the specified key from the registry and explicitly remove any subkeys. @@ -712,18 +711,18 @@ LONG RecurseDeleteKey(LPCTSTR lpszKey) throw(); ### Parameters -*lpszKey*
-Specifies the name of the key to delete. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszKey`*\ +Specifies the name of the key to delete. This name must be a subkey of [`m_hKey`](#m_hkey). ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a non-zero error value defined in `WINERROR.H`. ### Remarks If the key has subkeys, you must call this method to delete the key. -## CRegKey::SetBinaryValue +## `CRegKey::SetBinaryValue` Call this method to set the binary value of the registry key. @@ -736,26 +735,26 @@ LONG SetBinaryValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pValue*
+*`pValue`*\ Pointer to a buffer containing the data to be stored with the specified value name. -*nBytes*
-Specifies the size, in bytes, of the information pointed to by the *pValue* parameter. +*`nBytes`*\ +Specifies the size, in bytes, of the information pointed to by the *`pValue`* parameter. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetDWORDValue +## `CRegKey::SetDWORDValue` -Call this method to set the DWORD value of the registry key. +Call this method to set the `DWORD` value of the registry key. ``` LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw(); @@ -763,21 +762,21 @@ LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*dwValue*
-The DWORD data to be stored with the specified value name. +*`dwValue`*\ +The `DWORD` data to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetGUIDValue +## `CRegKey::SetGUIDValue` Call this method to set the GUID value of the registry key. @@ -787,21 +786,21 @@ LONG SetGUIDValue(LPCTSTR pszValueName, REFGUID guidValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*guidValue*
+*`guidValue`*\ Reference to the GUID to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method makes use of `CRegKey::SetStringValue` and converts the GUID into a string using [StringFromGUID2](/windows/win32/api/combaseapi/nf-combaseapi-stringfromguid2). +This method makes use of `CRegKey::SetStringValue` and converts the GUID into a string using [`StringFromGUID2`](/windows/win32/api/combaseapi/nf-combaseapi-stringfromguid2). -## CRegKey::SetKeyValue +## `CRegKey::SetKeyValue` Call this method to store data in a specified value field of a specified key. @@ -814,24 +813,24 @@ LONG SetKeyValue( ### Parameters -*lpszKeyName*
-Specifies the name of the key to be created or opened. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszKeyName`*\ +Specifies the name of the key to be created or opened. This name must be a subkey of [`m_hKey`](#m_hkey). -*lpszValue*
-Specifies the data to be stored. This parameter must be non-NULL. +*`lpszValue`*\ +Specifies the data to be stored. This parameter must be non-`NULL`. -*lpszValueName*
-Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added. +*`lpszValueName`*\ +Specifies the value field to be set. If a value field with this name doesn't already exist in the key, it's added. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -Call this method to create or open the *lpszKeyName* key and store the *lpszValue* data in the *lpszValueName* value field. +Call this method to create or open the *`lpszKeyName`* key and store the *`lpszValue`* data in the *`lpszValueName`* value field. -## CRegKey::SetKeySecurity +## `CRegKey::SetKeySecurity` Call this method to set the security of the registry key. @@ -841,28 +840,28 @@ LONG SetKeySecurity(SECURITY_INFORMATION si, PSECURITY_DESCRIPTOR psd) throw(); ### Parameters -*si*
+*`si`*\ Specifies the components of the security descriptor to set. The value can be a combination of the following values: |Value|Meaning| |-----------|-------------| -|DACL_SECURITY_INFORMATION|Sets the key's discretionary access-control list (DACL). The key must have WRITE_DAC access, or the calling process must be the object's owner.| -|GROUP_SECURITY_INFORMATION|Sets the key's primary group security identifier (SID). The key must have WRITE_OWNER access, or the calling process must be the object's owner.| -|OWNER_SECURITY_INFORMATION|Sets the key's owner SID. The key must have WRITE_OWNER access, or the calling process must be the object's owner or have the SE_TAKE_OWNERSHIP_NAME privilege enabled.| -|SACL_SECURITY_INFORMATION|Sets the key's system access-control list (SACL). The key must have ACCESS_SYSTEM_SECURITY access. The proper way to get this access is to enable the SE_SECURITY_NAME [privilege](/windows/win32/secauthz/privileges) in the caller's current access token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.| +|`DACL_SECURITY_INFORMATION`|Sets the key's discretionary access-control list (DACL). The key must have `WRITE_DAC` access, or the calling process must be the object's owner.| +|`GROUP_SECURITY_INFORMATION`|Sets the key's primary group security identifier (SID). The key must have `WRITE_OWNER` access, or the calling process must be the object's owner.| +|`OWNER_SECURITY_INFORMATION`|Sets the key's owner SID. The key must have `WRITE_OWNER` access, or the calling process must be the object's owner or have the `SE_TAKE_OWNERSHIP_NAME` privilege enabled.| +|`SACL_SECURITY_INFORMATION`|Sets the key's system access-control list (SACL). The key must have `ACCESS_SYSTEM_SECURITY` access. The proper way to get this access is to enable the `SE_SECURITY_NAME` [privilege](/windows/win32/secauthz/privileges) in the caller's current access token, open the handle for `ACCESS_SYSTEM_SECURITY` access, and then disable the privilege.| -*psd*
-Pointer to a [SECURITY_DESCRIPTOR](/windows/win32/api/winnt/ns-winnt-security_descriptor) structure that specifies the security attributes to set for the specified key. +*`psd`*\ +Pointer to a [`SECURITY_DESCRIPTOR`](/windows/win32/api/winnt/ns-winnt-security_descriptor) structure that specifies the security attributes to set for the specified key. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -Sets the key's security attributes. See [RegSetKeySecurity](/windows/win32/api/winreg/nf-winreg-regsetkeysecurity) for more details. +Sets the key's security attributes. See [`RegSetKeySecurity`](/windows/win32/api/winreg/nf-winreg-regsetkeysecurity) for more details. -## CRegKey::SetMultiStringValue +## `CRegKey::SetMultiStringValue` Call this method to set the multistring value of the registry key. @@ -872,23 +871,23 @@ LONG SetMultiStringValue(LPCTSTR pszValueName, LPCTSTR pszValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pszValue*
-Pointer to the multistring data to be stored with the specified value name. A multistring is an array of null-terminated strings, terminated by two null characters. +*`pszValue`*\ +Pointer to the multistring data to be stored with the specified value name. A multistring is an array of `NULL`-terminated strings, terminated by two null characters. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetQWORDValue +## `CRegKey::SetQWORDValue` -Call this method to set the QWORD value of the registry key. +Call this method to set the `QWORD` value of the registry key. ``` LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw(); @@ -896,21 +895,21 @@ LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*qwValue*
-The QWORD data to be stored with the specified value name. +*`qwValue`*\ +The `QWORD` data to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetStringValue +## `CRegKey::SetStringValue` Call this method to set the string value of the registry key. @@ -923,26 +922,26 @@ LONG SetStringValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pszValue*
+*`pszValue`*\ Pointer to the string data to be stored with the specified value name. -*dwType*
-The type of the string to write to the registry: either REG_SZ (the default) or REG_EXPAND_SZ (for multistrings). +*`dwType`*\ +The type of the string to write to the registry: either `REG_SZ` (the default) or `REG_EXPAND_SZ` (for multistrings). ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetValue +## `CRegKey::SetValue` -Call this method to store data in the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED. +Call this method to store data in the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`. ``` LONG SetValue( @@ -970,50 +969,50 @@ ATL_DEPRECATED LONG SetValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present in the key, the method adds it to the key. If *pszValueName* is NULL or an empty string, "", the method sets the type and data for the key's unnamed or default value. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present in the key, the method adds it to the key. If *`pszValueName`* is `NULL` or an empty string, `""`, the method sets the type and data for the key's unnamed or default value. -*dwType*
-Specifies a code indicating the type of data pointed to by the *pValue* parameter. +*`dwType`*\ +Specifies a code indicating the type of data pointed to by the *`pValue`* parameter. -*pValue*
+*`pValue`*\ Pointer to a buffer containing the data to be stored with the specified value name. -*nBytes*
-Specifies the size, in bytes, of the information pointed to by the *pValue* parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, *nBytes* must include the size of the terminating null character. +*`nBytes`*\ +Specifies the size, in bytes, of the information pointed to by the *`pValue`* parameter. If the data is of type `REG_SZ`, `REG_EXPAND_SZ`, or `REG_MULTI_SZ`, *`nBytes`* must include the size of the terminating null character. -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*lpszValue*
-Specifies the data to be stored. This parameter must be non-NULL. +*`lpszValue`*\ +Specifies the data to be stored. This parameter must be non-`NULL`. -*lpszValueName*
-Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added. +*`lpszValueName`*\ +Specifies the value field to be set. If a value field with this name doesn't already exist in the key, it's added. -*dwValue*
+*`dwValue`*\ Specifies the data to be stored. -*bMulti*
-If false, indicates the string is of type REG_SZ. If true, indicates the string is a multistring of type REG_MULTI_SZ. +*`bMulti`*\ +If false, indicates the string is of type `REG_SZ`. If true, indicates the string is a multistring of type `REG_MULTI_SZ`. -*nValueLen*
-If *bMulti* is true, *nValueLen* is the length of the *lpszValue* string in characters. If *bMulti* is false, a value of -1 indicates that the method will calculate the length automatically. +*`nValueLen`*\ +If *`bMulti`* is true, *`nValueLen`* is the length of the *`lpszValue`* string in characters. If *`bMulti`* is false, a value of -1 indicates that the method will calculate the length automatically. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -The two original versions of `SetValue` are marked as ATL_DEPRECATED and should no longer be used. The compiler will issue a warning if these forms are used. +The two original versions of `SetValue` are marked as `ATL_DEPRECATED` and should no longer be used. The compiler will issue a warning if these forms are used. -The third method calls [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw). +The third method calls [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw). ## See also -[DCOM Sample](../../overview/visual-cpp-samples.md)
+[DCOM Sample](../../overview/visual-cpp-samples.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/csimplearray-class.md b/docs/atl/reference/csimplearray-class.md index b79b7e57ab..12a7cd1332 100644 --- a/docs/atl/reference/csimplearray-class.md +++ b/docs/atl/reference/csimplearray-class.md @@ -252,7 +252,7 @@ Removes all elements currently stored in the array. Removes the specified element from the array. ``` -BOOL RemoveAtint nIndex); +BOOL RemoveAt(int nIndex); ``` ### Parameters diff --git a/docs/atl/reference/cstockpropimpl-class.md b/docs/atl/reference/cstockpropimpl-class.md index 29b1619156..1f4959941f 100644 --- a/docs/atl/reference/cstockpropimpl-class.md +++ b/docs/atl/reference/cstockpropimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CStockPropImpl Class" title: "CStockPropImpl Class" +description: "Learn more about: CStockPropImpl Class" ms.date: "05/06/2019" f1_keywords: ["CStockPropImpl", "ATLCTL/ATL::CStockPropImpl", "ATLCTL/ATL::get_Appearance", "ATLCTL/ATL::get_AutoSize", "ATLCTL/ATL::get_BackColor", "ATLCTL/ATL::get_BackStyle", "ATLCTL/ATL::get_BorderColor", "ATLCTL/ATL::get_BorderStyle", "ATLCTL/ATL::get_BorderVisible", "ATLCTL/ATL::get_BorderWidth", "ATLCTL/ATL::get_Caption", "ATLCTL/ATL::get_DrawMode", "ATLCTL/ATL::get_DrawStyle", "ATLCTL/ATL::get_DrawWidth", "ATLCTL/ATL::get_Enabled", "ATLCTL/ATL::get_FillColor", "ATLCTL/ATL::get_FillStyle", "ATLCTL/ATL::get_Font", "ATLCTL/ATL::get_ForeColor", "ATLCTL/ATL::get_HWND", "ATLCTL/ATL::get_MouseIcon", "ATLCTL/ATL::get_MousePointer", "ATLCTL/ATL::get_Picture", "ATLCTL/ATL::get_ReadyState", "ATLCTL/ATL::get_TabStop", "ATLCTL/ATL::get_Text", "ATLCTL/ATL::getvalid", "ATLCTL/ATL::get_Window", "ATLCTL/ATL::put_Appearance", "ATLCTL/ATL::put_AutoSize", "ATLCTL/ATL::put_BackColor", "ATLCTL/ATL::put_BackStyle", "ATLCTL/ATL::put_BorderColor", "ATLCTL/ATL::put_BorderStyle", "ATLCTL/ATL::put_BorderVisible", "ATLCTL/ATL::put_BorderWidth", "ATLCTL/ATL::put_Caption", "ATLCTL/ATL::put_DrawMode", "ATLCTL/ATL::put_DrawStyle", "ATLCTL/ATL::put_DrawWidth", "ATLCTL/ATL::put_Enabled", "ATLCTL/ATL::put_FillColor", "ATLCTL/ATL::put_FillStyle", "ATLCTL/ATL::put_Font", "ATLCTL/ATL::put_ForeColor", "ATLCTL/ATL::put_HWND", "ATLCTL/ATL::put_MouseIcon", "ATLCTL/ATL::put_MousePointer", "ATLCTL/ATL::put_Picture", "ATLCTL/ATL::put_ReadyState", "ATLCTL/ATL::put_TabStop", "ATLCTL/ATL::put_Text", "ATLCTL/ATL::putvalid", "ATLCTL/ATL::put_Window", "ATLCTL/ATL::putref_Font", "ATLCTL/ATL::putref_MouseIcon", "ATLCTL/ATL::putref_Picture"] helpviewer_keywords: ["CStockPropImpl class", "controls [ATL], stock properties", "stock properties, ATL controls"] -ms.assetid: 45f11d7d-6580-4a0e-872d-3bc8b836cfda --- # CStockPropImpl Class @@ -607,7 +606,7 @@ Returns S_OK on success, or an error HRESULT on failure. Call this method to set the value of flag that indicates if the control cannot be any other size. ``` -HRESULT STDMETHODCALLTYPE put_AutoSize(VARIANT_BOOL bAutoSize,); +HRESULT STDMETHODCALLTYPE put_AutoSize(VARIANT_BOOL bAutoSize); ``` ### Parameters @@ -1100,5 +1099,5 @@ The same as [CStockPropImpl::put_Picture](#put_picture), but with a reference co ## See also -[Class Overview](../../atl/atl-class-overview.md)
+[Class Overview](../../atl/atl-class-overview.md)\ [IDispatchImpl Class](../../atl/reference/idispatchimpl-class.md) diff --git a/docs/atl/reference/cthreadpool-class.md b/docs/atl/reference/cthreadpool-class.md index e5834d8409..0cca6b473f 100644 --- a/docs/atl/reference/cthreadpool-class.md +++ b/docs/atl/reference/cthreadpool-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CThreadPool Class" title: "CThreadPool Class" -ms.date: "11/04/2016" +description: "Learn more about: CThreadPool Class" +ms.date: 11/04/2016 f1_keywords: ["CThreadPool", "ATLUTIL/ATL::CThreadPool", "ATLUTIL/ATL::CThreadPool::CThreadPool", "ATLUTIL/ATL::CThreadPool::AddRef", "ATLUTIL/ATL::CThreadPool::GetNumThreads", "ATLUTIL/ATL::CThreadPool::GetQueueHandle", "ATLUTIL/ATL::CThreadPool::GetSize", "ATLUTIL/ATL::CThreadPool::GetTimeout", "ATLUTIL/ATL::CThreadPool::Initialize", "ATLUTIL/ATL::CThreadPool::QueryInterface", "ATLUTIL/ATL::CThreadPool::QueueRequest", "ATLUTIL/ATL::CThreadPool::Release", "ATLUTIL/ATL::CThreadPool::SetSize", "ATLUTIL/ATL::CThreadPool::SetTimeout", "ATLUTIL/ATL::CThreadPool::Shutdown"] helpviewer_keywords: ["CThreadPool class"] -ms.assetid: 06683718-01b9-413c-9481-2dc1734ec70f --- # CThreadPool Class @@ -265,7 +264,7 @@ This class does not implement lifetime control using reference counting. Call this method to set the number of threads in the pool. ``` -HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw(); +HRESULT STDMETHODCALLTYPE SetSize(int nNumThreads) throw(); ``` ### Parameters diff --git a/docs/atl/reference/cw2aex-class.md b/docs/atl/reference/cw2aex-class.md index 0be05310ba..9029cccbe7 100644 --- a/docs/atl/reference/cw2aex-class.md +++ b/docs/atl/reference/cw2aex-class.md @@ -4,11 +4,10 @@ title: "CW2AEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2AEX", "ATLCONV/ATL::CW2AEX", "ATLCONV/ATL::CW2AEX::CW2AEX", "ATLCONV/ATL::CW2AEX::m_psz", "ATLCONV/ATL::CW2AEX::m_szBuffer"] helpviewer_keywords: ["CW2AEX class"] -ms.assetid: 44dc2cf5-dd30-440b-a9b9-b21b43f49843 --- -# CW2AEX Class +# `CW2AEX` Class -This class is used by the string conversion macros CT2AEX, CW2TEX, CW2CTEX, and CT2CAEX, and the typedef CW2A. +This class is used by the string conversion macros `CT2AEX`, `CW2TEX`, `CW2CTEX`, and `CT2CAEX`, and the typedef `CW2A`. > [!IMPORTANT] > This class and its members cannot be used in applications that execute in the Windows Runtime. @@ -22,7 +21,7 @@ class CW2AEX #### Parameters -*t_nBufferLength*
+*`t_nBufferLength`*\ The size of the buffer used in the translation process. The default length is 128 bytes. ## Members @@ -31,8 +30,8 @@ The size of the buffer used in the translation process. The default length is 12 |Name|Description| |----------|-----------------| -|[CW2AEX::CW2AEX](#cw2aex)|The constructor.| -|[CW2AEX::~CW2AEX](#dtor)|The destructor.| +|[`CW2AEX::CW2AEX`](#cw2aex)|The constructor.| +|[`CW2AEX::~CW2AEX`](#dtor)|The destructor.| ### Public Operators @@ -44,32 +43,32 @@ The size of the buffer used in the translation process. The default length is 12 |Name|Description| |----------|-----------------| -|[CW2AEX::m_psz](#m_psz)|The data member that stores the source string.| -|[CW2AEX::m_szBuffer](#m_szbuffer)|The static buffer, used to store the converted string.| +|[`CW2AEX::m_psz`](#m_psz)|The data member that stores the source string.| +|[`CW2AEX::m_szBuffer`](#m_szbuffer)|The static buffer, used to store the converted string.| ## Remarks -Unless extra functionality is required, use CT2AEX, CW2TEX, CW2CTEX, CT2CAEX, or CW2A in your code. +Unless extra functionality is required, use `CT2AEX`, `CW2TEX`, `CW2CTEX`, `CT2CAEX`, or `CW2A` in your code. -This class contains a fixed-size static buffer which is used to store the result of the conversion. If the result is too large to fit into the static buffer, the class allocates memory using **malloc**, freeing the memory when the object goes out of scope. This ensures that, unlike text conversion macros available in previous versions of ATL, this class is safe to use in loops and that it won't overflow the stack. +This class contains a fixed-size static buffer that is used to store the result of the conversion. If the result is too large to fit into the static buffer, the class allocates memory using **`malloc`**, freeing the memory when the object goes out of scope. This ensures that, unlike text conversion macros available in previous versions of ATL, this class is safe to use in loops and that it won't overflow the stack. -If the class tries to allocate memory on the heap and fails, it will call `AtlThrow` with an argument of E_OUTOFMEMORY. +If the class tries to allocate memory on the heap and fails, it will call `AtlThrow` with an argument of `E_OUTOFMEMORY`. By default, the ATL conversion classes and macros use the current thread's ANSI code page for the conversion. If you want to override that behavior for a specific conversion, specify the code page as the second parameter to the constructor for the class. The following macros are based on this class: -- CT2AEX +- `CT2AEX` -- CW2TEX +- `CW2TEX` -- CW2CTEX +- `CW2CTEX` -- CT2CAEX +- `CT2CAEX` The following typedef is based on this class: -- CW2A +- `CW2A` For a discussion of these text conversion macros, see [ATL and MFC String Conversion Macros](string-conversion-macros.md). @@ -79,9 +78,9 @@ See [ATL and MFC String Conversion Macros](string-conversion-macros.md) for an e ## Requirements -**Header:** atlconv.h +**Header:** `atlconv.h` -## CW2AEX::CW2AEX +## `CW2AEX::CW2AEX` The constructor. @@ -92,17 +91,17 @@ CW2AEX(LPCWSTR psz) throw(...); ### Parameters -*psz*
+*`psz`*\ The text string to be converted. -*nCodePage*
-The code page used to perform the conversion. See the code page parameter discussion for the Windows SDK function [MultiByteToWideChar](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) for more details. +*`nCodePage`*\ +The code page used to perform the conversion. See the code page parameter discussion for the Windows SDK function [`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) for more details. ### Remarks Allocates the buffer used in the translation process. -## CW2AEX::~CW2AEX +## `CW2AEX::~CW2AEX` The destructor. @@ -114,7 +113,7 @@ The destructor. Frees the allocated buffer. -## CW2AEX::m_psz +## `CW2AEX::m_psz` The data member that stores the source string. @@ -122,7 +121,7 @@ The data member that stores the source string. LPSTR m_psz; ``` -## CW2AEX::m_szBuffer +## `CW2AEX::m_szBuffer` The static buffer, used to store the converted string. @@ -130,7 +129,7 @@ The static buffer, used to store the converted string. char m_szBuffer[t_nBufferLength]; ``` -## CW2AEX::operator LPSTR +## `CW2AEX::operator LPSTR` Conversion operator. @@ -140,13 +139,13 @@ operator LPSTR() const throw(); ### Return Value -Returns the text string as type LPSTR. +Returns the text string as type `LPSTR`. ## See also -[CA2AEX Class](../../atl/reference/ca2aex-class.md)
-[CA2CAEX Class](../../atl/reference/ca2caex-class.md)
-[CA2WEX Class](../../atl/reference/ca2wex-class.md)
-[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)
-[CW2WEX Class](../../atl/reference/cw2wex-class.md)
+[`CA2AEX` Class](../../atl/reference/ca2aex-class.md)\ +[`CA2CAEX` Class](../../atl/reference/ca2caex-class.md)\ +[`CA2WEX` Class](../../atl/reference/ca2wex-class.md)\ +[`CW2CWEX` Class](../../atl/reference/cw2cwex-class.md)\ +[`CW2WEX` Class](../../atl/reference/cw2wex-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cw2wex-class.md b/docs/atl/reference/cw2wex-class.md index 3c0cfb0946..d5c15f69f2 100644 --- a/docs/atl/reference/cw2wex-class.md +++ b/docs/atl/reference/cw2wex-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CW2WEX Class" title: "CW2WEX Class" +description: "Learn more about: CW2WEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2WEX", "ATLCONV/ATL::CW2WEX", "ATLCONV/ATL::CW2WEX::CW2WEX", "ATLCONV/ATL::CW2WEX::m_psz", "ATLCONV/ATL::CW2WEX::m_szBuffer"] helpviewer_keywords: ["CW2WEX class"] -ms.assetid: 46262e56-e0d2-41fe-855b-0b67ecc8fcd7 --- # CW2WEX Class @@ -100,7 +99,7 @@ Creates the buffer required for the translation. ## CW2WEX::~CW2WEX -The destructor.. +The destructor. ``` ~CW2WEX() throw(); @@ -140,9 +139,9 @@ Returns the text string as type LPWSTR. ## See also -[CA2AEX Class](../../atl/reference/ca2aex-class.md)
-[CA2CAEX Class](../../atl/reference/ca2caex-class.md)
-[CA2WEX Class](../../atl/reference/ca2wex-class.md)
-[CW2AEX Class](../../atl/reference/cw2aex-class.md)
-[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)
+[CA2AEX Class](../../atl/reference/ca2aex-class.md)\ +[CA2CAEX Class](../../atl/reference/ca2caex-class.md)\ +[CA2WEX Class](../../atl/reference/ca2wex-class.md)\ +[CW2AEX Class](../../atl/reference/cw2aex-class.md)\ +[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cwindow-class.md b/docs/atl/reference/cwindow-class.md index f342adc8fa..c91fae3db6 100644 --- a/docs/atl/reference/cwindow-class.md +++ b/docs/atl/reference/cwindow-class.md @@ -4,9 +4,8 @@ title: "CWindow Class" ms.date: "11/04/2016" f1_keywords: ["CWindow", "ATLWIN/ATL::CWindow", "ATLWIN/ATL::CWindow::CWindow", "ATLWIN/ATL::CWindow::ArrangeIconicWindows", "ATLWIN/ATL::CWindow::Attach", "ATLWIN/ATL::CWindow::BeginPaint", "ATLWIN/ATL::CWindow::BringWindowToTop", "ATLWIN/ATL::CWindow::CenterWindow", "ATLWIN/ATL::CWindow::ChangeClipboardChain", "ATLWIN/ATL::CWindow::CheckDlgButton", "ATLWIN/ATL::CWindow::CheckRadioButton", "ATLWIN/ATL::CWindow::ChildWindowFromPoint", "ATLWIN/ATL::CWindow::ChildWindowFromPointEx", "ATLWIN/ATL::CWindow::ClientToScreen", "ATLWIN/ATL::CWindow::Create", "ATLWIN/ATL::CWindow::CreateCaret", "ATLWIN/ATL::CWindow::CreateGrayCaret", "ATLWIN/ATL::CWindow::CreateSolidCaret", "ATLWIN/ATL::CWindow::DeferWindowPos", "ATLWIN/ATL::CWindow::DestroyWindow", "ATLWIN/ATL::CWindow::Detach", "ATLWIN/ATL::CWindow::DlgDirList", "ATLWIN/ATL::CWindow::DlgDirListComboBox", "ATLWIN/ATL::CWindow::DlgDirSelect", "ATLWIN/ATL::CWindow::DlgDirSelectComboBox", "ATLWIN/ATL::CWindow::DragAcceptFiles", "ATLWIN/ATL::CWindow::DrawMenuBar", "ATLWIN/ATL::CWindow::EnableScrollBar", "ATLWIN/ATL::CWindow::EnableWindow", "ATLWIN/ATL::CWindow::EndPaint", "ATLWIN/ATL::CWindow::FlashWindow", "ATLWIN/ATL::CWindow::GetClientRect", "ATLWIN/ATL::CWindow::GetDC", "ATLWIN/ATL::CWindow::GetDCEx", "ATLWIN/ATL::CWindow::GetDescendantWindow", "ATLWIN/ATL::CWindow::GetDlgControl", "ATLWIN/ATL::CWindow::GetDlgCtrlID", "ATLWIN/ATL::CWindow::GetDlgHost", "ATLWIN/ATL::CWindow::GetDlgItem", "ATLWIN/ATL::CWindow::GetDlgItemInt", "ATLWIN/ATL::CWindow::GetDlgItemText", "ATLWIN/ATL::CWindow::GetExStyle", "ATLWIN/ATL::CWindow::GetFont", "ATLWIN/ATL::CWindow::GetHotKey", "ATLWIN/ATL::CWindow::GetIcon", "ATLWIN/ATL::CWindow::GetLastActivePopup", "ATLWIN/ATL::CWindow::GetMenu", "ATLWIN/ATL::CWindow::GetNextDlgGroupItem", "ATLWIN/ATL::CWindow::GetNextDlgTabItem", "ATLWIN/ATL::CWindow::GetParent", "ATLWIN/ATL::CWindow::GetScrollInfo", "ATLWIN/ATL::CWindow::GetScrollPos", "ATLWIN/ATL::CWindow::GetScrollRange", "ATLWIN/ATL::CWindow::GetStyle", "ATLWIN/ATL::CWindow::GetSystemMenu", "ATLWIN/ATL::CWindow::GetTopLevelParent", "ATLWIN/ATL::CWindow::GetTopLevelWindow", "ATLWIN/ATL::CWindow::GetTopWindow", "ATLWIN/ATL::CWindow::GetUpdateRect", "ATLWIN/ATL::CWindow::GetUpdateRgn", "ATLWIN/ATL::CWindow::GetWindow", "ATLWIN/ATL::CWindow::GetWindowContextHelpId", "ATLWIN/ATL::CWindow::GetWindowDC", "ATLWIN/ATL::CWindow::GetWindowLong", "ATLWIN/ATL::CWindow::GetWindowLongPtr", "ATLWIN/ATL::CWindow::GetWindowPlacement", "ATLWIN/ATL::CWindow::GetWindowProcessID", "ATLWIN/ATL::CWindow::GetWindowRect", "ATLWIN/ATL::CWindow::GetWindowRgn", "ATLWIN/ATL::CWindow::GetWindowText", "ATLWIN/ATL::CWindow::GetWindowTextLength", "ATLWIN/ATL::CWindow::GetWindowThreadID", "ATLWIN/ATL::CWindow::GetWindowWord", "ATLWIN/ATL::CWindow::GotoDlgCtrl", "ATLWIN/ATL::CWindow::HideCaret", "ATLWIN/ATL::CWindow::HiliteMenuItem", "ATLWIN/ATL::CWindow::Invalidate", "ATLWIN/ATL::CWindow::InvalidateRect", "ATLWIN/ATL::CWindow::InvalidateRgn", "ATLWIN/ATL::CWindow::IsChild", "ATLWIN/ATL::CWindow::IsDialogMessage", "ATLWIN/ATL::CWindow::IsDlgButtonChecked", "ATLWIN/ATL::CWindow::IsIconic", "ATLWIN/ATL::CWindow::IsParentDialog", "ATLWIN/ATL::CWindow::IsWindow", "ATLWIN/ATL::CWindow::IsWindowEnabled", "ATLWIN/ATL::CWindow::IsWindowUnicode", "ATLWIN/ATL::CWindow::IsWindowVisible", "ATLWIN/ATL::CWindow::IsZoomed", "ATLWIN/ATL::CWindow::KillTimer", "ATLWIN/ATL::CWindow::LockWindowUpdate", "ATLWIN/ATL::CWindow::MapWindowPoints", "ATLWIN/ATL::CWindow::MessageBox", "ATLWIN/ATL::CWindow::ModifyStyle", "ATLWIN/ATL::CWindow::ModifyStyleEx", "ATLWIN/ATL::CWindow::MoveWindow", "ATLWIN/ATL::CWindow::NextDlgCtrl", "ATLWIN/ATL::CWindow::OpenClipboard", "ATLWIN/ATL::CWindow::PostMessage", "ATLWIN/ATL::CWindow::PrevDlgCtrl", "ATLWIN/ATL::CWindow::Print", "ATLWIN/ATL::CWindow::PrintClient", "ATLWIN/ATL::CWindow::RedrawWindow", "ATLWIN/ATL::CWindow::ReleaseDC", "ATLWIN/ATL::CWindow::ResizeClient", "ATLWIN/ATL::CWindow::ScreenToClient", "ATLWIN/ATL::CWindow::ScrollWindow", "ATLWIN/ATL::CWindow::ScrollWindowEx", "ATLWIN/ATL::CWindow::SendDlgItemMessage", "ATLWIN/ATL::CWindow::SendMessage", "ATLWIN/ATL::CWindow::SendMessageToDescendants", "ATLWIN/ATL::CWindow::SendNotifyMessage", "ATLWIN/ATL::CWindow::SetActiveWindow", "ATLWIN/ATL::CWindow::SetCapture", "ATLWIN/ATL::CWindow::SetClipboardViewer", "ATLWIN/ATL::CWindow::SetDlgCtrlID", "ATLWIN/ATL::CWindow::SetDlgItemInt", "ATLWIN/ATL::CWindow::SetDlgItemText", "ATLWIN/ATL::CWindow::SetFocus", "ATLWIN/ATL::CWindow::SetFont", "ATLWIN/ATL::CWindow::SetHotKey", "ATLWIN/ATL::CWindow::SetIcon", "ATLWIN/ATL::CWindow::SetMenu", "ATLWIN/ATL::CWindow::SetParent", "ATLWIN/ATL::CWindow::SetRedraw", "ATLWIN/ATL::CWindow::SetScrollInfo", "ATLWIN/ATL::CWindow::SetScrollPos", "ATLWIN/ATL::CWindow::SetScrollRange", "ATLWIN/ATL::CWindow::SetTimer", "ATLWIN/ATL::CWindow::SetWindowContextHelpId", "ATLWIN/ATL::CWindow::SetWindowLong", "ATLWIN/ATL::CWindow::SetWindowLongPtr", "ATLWIN/ATL::CWindow::SetWindowPlacement", "ATLWIN/ATL::CWindow::SetWindowPos", "ATLWIN/ATL::CWindow::SetWindowRgn", "ATLWIN/ATL::CWindow::SetWindowText", "ATLWIN/ATL::CWindow::SetWindowWord", "ATLWIN/ATL::CWindow::ShowCaret", "ATLWIN/ATL::CWindow::ShowOwnedPopups", "ATLWIN/ATL::CWindow::ShowScrollBar", "ATLWIN/ATL::CWindow::ShowWindow", "ATLWIN/ATL::CWindow::ShowWindowAsync", "ATLWIN/ATL::CWindow::UpdateWindow", "ATLWIN/ATL::CWindow::ValidateRect", "ATLWIN/ATL::CWindow::ValidateRgn", "ATLWIN/ATL::CWindow::WinHelp", "ATLWIN/ATL::CWindow::m_hWnd", "ATLWIN/ATL::CWindow::rcDefault"] helpviewer_keywords: ["CWindow class"] -ms.assetid: fefa00c8-f053-4bcf-87bc-dc84f5386683 --- -# CWindow Class +# `CWindow` Class This class provides methods for manipulating a window. @@ -25,206 +24,206 @@ class CWindow |Name|Description| |----------|-----------------| -|[CWindow::CWindow](#cwindow)|Constructor.| +|[`CWindow::CWindow`](#cwindow)|Constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CWindow::ArrangeIconicWindows](#arrangeiconicwindows)|Arranges all minimized child windows.| -|[CWindow::Attach](#attach)|Attaches a window to the `CWindow` object.| -|[CWindow::BeginPaint](#beginpaint)|Prepares the window for painting.| -|[CWindow::BringWindowToTop](#bringwindowtotop)|Brings the window to the top of the Z order.| -|[CWindow::CenterWindow](#centerwindow)|Centers the window against a given window.| -|[CWindow::ChangeClipboardChain](#changeclipboardchain)|Removes the window from the chain of Clipboard viewers.| -|[CWindow::CheckDlgButton](#checkdlgbutton)|Changes the check state of the specified button.| -|[CWindow::CheckRadioButton](#checkradiobutton)|Checks the specified radio button.| -|[CWindow::ChildWindowFromPoint](#childwindowfrompoint)|Retrieves the child window containing the specified point.| -|[CWindow::ChildWindowFromPointEx](#childwindowfrompointex)|Retrieves a particular type of child window containing the specified point.| -|[CWindow::ClientToScreen](#clienttoscreen)|Converts client coordinates to screen coordinates.| -|[CWindow::Create](#create)|Creates a window.| -|[CWindow::CreateCaret](#createcaret)|Creates a new shape for the system caret.| -|[CWindow::CreateGrayCaret](#creategraycaret)|Creates a gray rectangle for the system caret.| -|[CWindow::CreateSolidCaret](#createsolidcaret)|Creates a solid rectangle for the system caret.| -|[CWindow::DeferWindowPos](#deferwindowpos)|Updates the specified multiple-window-position structure for the specified window.| -|[CWindow::DestroyWindow](#destroywindow)|Destroys the window associated with the `CWindow` object.| -|[CWindow::Detach](#detach)|Detaches the window from the `CWindow` object.| -|[CWindow::DlgDirList](#dlgdirlist)|Fills a list box with the names of all files matching a specified path or file name.| -|[CWindow::DlgDirListComboBox](#dlgdirlistcombobox)|Fills a combo box with the names of all files matching a specified path or file name.| -|[CWindow::DlgDirSelect](#dlgdirselect)|Retrieves the current selection from a list box.| -|[CWindow::DlgDirSelectComboBox](#dlgdirselectcombobox)|Retrieves the current selection from a combo box.| -|[CWindow::DragAcceptFiles](#dragacceptfiles)|Registers whether the window accepts dragged files.| -|[CWindow::DrawMenuBar](#drawmenubar)|Redraws the window's menu bar.| -|[CWindow::EnableScrollBar](#enablescrollbar)|Enables or disables the scroll bar arrows.| -|[CWindow::EnableWindow](#enablewindow)|Enables or disables input.| -|[CWindow::EndPaint](#endpaint)|Marks the end of painting.| -|[CWindow::FlashWindow](#flashwindow)|Flashes the window once.| -|[CWindow::GetClientRect](#getclientrect)|Retrieves the coordinates of the client area.| -|[CWindow::GetDC](#getdc)|Retrieves a device context for the client area.| -|[CWindow::GetDCEx](#getdcex)|Retrieves a device context for the client area and allows clipping options.| -|[CWindow::GetDescendantWindow](#getdescendantwindow)|Retrieves the specified descendant window.| -|[CWindow::GetDlgControl](#getdlgcontrol)|Retrieves an interface on the specified control.| -|[CWindow::GetDlgCtrlID](#getdlgctrlid)|Retrieves the window's identifier (for child windows only).| -|[CWindow::GetDlgHost](#getdlghost)|Retrieves a pointer to an interface to the ATL Control hosting container.| -|[CWindow::GetDlgItem](#getdlgitem)|Retrieves the specified child window.| -|[CWindow::GetDlgItemInt](#getdlgitemint)|Translates a control's text to an integer.| -|[CWindow::GetDlgItemText](#getdlgitemtext)|Retrieves a control's text.| -|[CWindow::GetExStyle](#getexstyle)|Retrieves the extended window styles.| -|[CWindow::GetFont](#getfont)|Retrieves the window's current font.| -|[CWindow::GetHotKey](#gethotkey)|Determines the hot key associated with the window.| -|[CWindow::GetIcon](#geticon)|Retrieves the window's large or small icon.| -|[CWindow::GetLastActivePopup](#getlastactivepopup)|Retrieves the most recently active pop-up window.| -|[CWindow::GetMenu](#getmenu)|Retrieves the window's menu.| -|[CWindow::GetNextDlgGroupItem](#getnextdlggroupitem)|Retrieves the previous or next control within a group of controls.| -|[CWindow::GetNextDlgTabItem](#getnextdlgtabitem)|Retrieves the previous or next control having the WS_TABSTOP style.| -|[CWindow::GetParent](#getparent)|Retrieves the immediate parent window.| -|[CWindow::GetScrollInfo](#getscrollinfo)|Retrieves the parameters of a scroll bar.| -|[CWindow::GetScrollPos](#getscrollpos)|Retrieves the position of the scroll box.| -|[CWindow::GetScrollRange](#getscrollrange)|Retrieves the scroll bar range.| -|[CWindow::GetStyle](#getstyle)|Retrieves the window styles.| -|[CWindow::GetSystemMenu](#getsystemmenu)|Creates a copy of the system menu for modification.| -|[CWindow::GetTopLevelParent](#gettoplevelparent)|Retrieves the top-level parent or owner window.| -|[CWindow::GetTopLevelWindow](#gettoplevelwindow)|Retrieves the top-level owner window.| -|[CWindow::GetTopWindow](#gettopwindow)|Retrieves the top-level child window.| -|[CWindow::GetUpdateRect](#getupdaterect)|Retrieves the coordinates of the smallest rectangle that completely encloses the update region.| -|[CWindow::GetUpdateRgn](#getupdatergn)|Retrieves the update region and copies it into a specified region.| -|[CWindow::GetWindow](#getwindow)|Retrieves the specified window.| -|[CWindow::GetWindowContextHelpId](#getwindowcontexthelpid)|Retrieves the window's help context identifier.| -|[CWindow::GetWindowDC](#getwindowdc)|Retrieves a device context for the entire window.| -|[CWindow::GetWindowLong](#getwindowlong)|Retrieves a 32-bit value at a specified offset into the extra window memory.| -|[CWindow::GetWindowLongPtr](#getwindowlongptr)|Retrieves information about the specified window, including a value at a specified offset into the extra window memory.| -|[CWindow::GetWindowPlacement](#getwindowplacement)|Retrieves the show state and positions.| -|[CWindow::GetWindowProcessID](#getwindowprocessid)|Retrieves the identifier of the process that created the window.| -|[CWindow::GetWindowRect](#getwindowrect)|Retrieves the window's bounding dimensions.| -|[CWindow::GetWindowRgn](#getwindowrgn)|Obtains a copy of the window region of a window.| -|[CWindow::GetWindowText](#getwindowtext)|Retrieves the window's text.| -|[CWindow::GetWindowTextLength](#getwindowtextlength)|Retrieves the length of the window's text.| -|[CWindow::GetWindowThreadID](#getwindowthreadid)|Retrieves the identifier of the thread that created the specified window.| -|[CWindow::GetWindowWord](#getwindowword)|Retrieves a 16-bit value at a specified offset into the extra window memory.| -|[CWindow::GotoDlgCtrl](#gotodlgctrl)|Sets the keyboard focus to a control in the dialog box.| -|[CWindow::HideCaret](#hidecaret)|Hides the system caret.| -|[CWindow::HiliteMenuItem](#hilitemenuitem)|Highlights or removes the highlight from a top-level menu item.| -|[CWindow::Invalidate](#invalidate)|Invalidates the entire client area.| -|[CWindow::InvalidateRect](#invalidaterect)|Invalidates the client area within the specified rectangle.| -|[CWindow::InvalidateRgn](#invalidatergn)|Invalidates the client area within the specified region.| -|[CWindow::IsChild](#ischild)|Determines whether the specified window is a child window.| -|[CWindow::IsDialogMessage](#isdialogmessage)|Determines whether a message is intended for the specified dialog box.| -|[CWindow::IsDlgButtonChecked](#isdlgbuttonchecked)|Determines the check state of the button.| -|[CWindow::IsIconic](#isiconic)|Determines whether the window is minimized.| -|[CWindow::IsParentDialog](#isparentdialog)|Determines if the parent window of a control is a dialog window.| -|[CWindow::IsWindow](#iswindow)|Determines whether the specified window handle identifies an existing window.| -|[CWindow::IsWindowEnabled](#iswindowenabled)|Determines whether the window is enabled for input.| -|[CWindow::IsWindowUnicode](#iswindowunicode)|Determines whether the specified window is a native Unicode window.| -|[CWindow::IsWindowVisible](#iswindowvisible)|Determines the window's visibility state.| -|[CWindow::IsZoomed](#iszoomed)|Determines whether the window is maximized.| -|[CWindow::KillTimer](#killtimer)|Destroys a timer event.| -|[CWindow::LockWindowUpdate](#lockwindowupdate)|Disables or enables drawing in the window.| -|[CWindow::MapWindowPoints](#mapwindowpoints)|Converts a set of points from the window's coordinate space to the coordinate space of another window.| -|[CWindow::MessageBox](#messagebox)|Displays a message box.| -|[CWindow::ModifyStyle](#modifystyle)|Modifies the window styles.| -|[CWindow::ModifyStyleEx](#modifystyleex)|Modifies the extended window styles.| -|[CWindow::MoveWindow](#movewindow)|Changes the window's size and position.| -|[CWindow::NextDlgCtrl](#nextdlgctrl)|Sets the keyboard focus to the next control in the dialog box.| -|[CWindow::OpenClipboard](#openclipboard)|Opens the Clipboard.| -|[CWindow::PostMessage](#postmessage)|Places a message in the message queue associated with the thread that created the window. Returns without waiting for the thread to process the message.| -|[CWindow::PrevDlgCtrl](#prevdlgctrl)|Sets the keyboard focus to the previous control in the dialog box.| -|[CWindow::Print](#print)|Requests that the window be drawn in a specified device context.| -|[CWindow::PrintClient](#printclient)|Requests that the window's client area be drawn in a specified device context.| -|[CWindow::RedrawWindow](#redrawwindow)|Updates a specified rectangle or region in the client area.| -|[CWindow::ReleaseDC](#releasedc)|Releases a device context.| -|[CWindow::ResizeClient](#resizeclient)|Resizes the window.| -|[CWindow::ScreenToClient](#screentoclient)|Converts screen coordinates to client coordinates.| -|[CWindow::ScrollWindow](#scrollwindow)|Scrolls the specified client area.| -|[CWindow::ScrollWindowEx](#scrollwindowex)|Scrolls the specified client area with additional features.| -|[CWindow::SendDlgItemMessage](#senddlgitemmessage)|Sends a message to a control.| -|[CWindow::SendMessage](#sendmessage)|Sends a message to the window and does not return until the window procedure has processed the message.| -|[CWindow::SendMessageToDescendants](#sendmessagetodescendants)|Sends a message to the specified descendant windows.| -|[CWindow::SendNotifyMessage](#sendnotifymessage)|Sends a message to the window. If the window was created by the calling thread, `SendNotifyMessage` does not return until the window procedure has processed the message. Otherwise, it returns immediately.| -|[CWindow::SetActiveWindow](#setactivewindow)|Activates the window.| -|[CWindow::SetCapture](#setcapture)|Sends all subsequent mouse input to the window.| -|[CWindow::SetClipboardViewer](#setclipboardviewer)|Adds the window to the Clipboard viewer chain.| -|[CWindow::SetDlgCtrlID](#setdlgctrlid)|Changes the window's identifier.| -|[CWindow::SetDlgItemInt](#setdlgitemint)|Changes a control's text to the string representation of an integer value.| -|[CWindow::SetDlgItemText](#setdlgitemtext)|Changes a control's text.| -|[CWindow::SetFocus](#setfocus)|Sets the input focus to the window.| -|[CWindow::SetFont](#setfont)|Changes the window's current font.| -|[CWindow::SetHotKey](#sethotkey)|Associates a hot key with the window.| -|[CWindow::SetIcon](#seticon)|Changes the window's large or small icon.| -|[CWindow::SetMenu](#setmenu)|Changes the window's current menu.| -|[CWindow::SetParent](#setparent)|Changes the parent window.| -|[CWindow::SetRedraw](#setredraw)|Sets or clears the redraw flag.| -|[CWindow::SetScrollInfo](#setscrollinfo)|Sets the parameters of a scroll bar.| -|[CWindow::SetScrollPos](#setscrollpos)|Changes the position of the scroll box.| -|[CWindow::SetScrollRange](#setscrollrange)|Changes the scroll bar range.| -|[CWindow::SetTimer](#settimer)|Creates a timer event.| -|[CWindow::SetWindowContextHelpId](#setwindowcontexthelpid)|Sets the window's help context identifier.| -|[CWindow::SetWindowLong](#setwindowlong)|Sets a 32-bit value at a specified offset into the extra window memory.| -|[CWindow::SetWindowLongPtr](#setwindowlongptr)|Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory.| -|[CWindow::SetWindowPlacement](#setwindowplacement)|Sets the show state and positions.| -|[CWindow::SetWindowPos](#setwindowpos)|Sets the size, position, and Z order.| -|[CWindow::SetWindowRgn](#setwindowrgn)|Sets the window region of a window.| -|[CWindow::SetWindowText](#setwindowtext)|Changes the window's text.| -|[CWindow::SetWindowWord](#setwindowword)|Sets a 16-bit value at a specified offset into the extra window memory.| -|[CWindow::ShowCaret](#showcaret)|Displays the system caret.| -|[CWindow::ShowOwnedPopups](#showownedpopups)|Shows or hides the pop-up windows owned by the window.| -|[CWindow::ShowScrollBar](#showscrollbar)|Shows or hides a scroll bar.| -|[CWindow::ShowWindow](#showwindow)|Sets the window's show state.| -|[CWindow::ShowWindowAsync](#showwindowasync)|Sets the show state of a window created by a different thread.| -|[CWindow::UpdateWindow](#updatewindow)|Updates the client area.| -|[CWindow::ValidateRect](#validaterect)|Validates the client area within the specified rectangle.| -|[CWindow::ValidateRgn](#validatergn)|Validates the client area within the specified region.| -|[CWindow::WinHelp](#winhelp)|Starts Windows Help.| +|[`CWindow::ArrangeIconicWindows`](#arrangeiconicwindows)|Arranges all minimized child windows.| +|[`CWindow::Attach`](#attach)|Attaches a window to the `CWindow` object.| +|[`CWindow::BeginPaint`](#beginpaint)|Prepares the window for painting.| +|[`CWindow::BringWindowToTop`](#bringwindowtotop)|Brings the window to the top of the Z order.| +|[`CWindow::CenterWindow`](#centerwindow)|Centers the window against a given window.| +|[`CWindow::ChangeClipboardChain`](#changeclipboardchain)|Removes the window from the chain of Clipboard viewers.| +|[`CWindow::CheckDlgButton`](#checkdlgbutton)|Changes the check state of the specified button.| +|[`CWindow::CheckRadioButton`](#checkradiobutton)|Checks the specified radio button.| +|[`CWindow::ChildWindowFromPoint`](#childwindowfrompoint)|Retrieves the child window containing the specified point.| +|[`CWindow::ChildWindowFromPointEx`](#childwindowfrompointex)|Retrieves a particular type of child window containing the specified point.| +|[`CWindow::ClientToScreen`](#clienttoscreen)|Converts client coordinates to screen coordinates.| +|[`CWindow::Create`](#create)|Creates a window.| +|[`CWindow::CreateCaret`](#createcaret)|Creates a new shape for the system caret.| +|[`CWindow::CreateGrayCaret`](#creategraycaret)|Creates a gray rectangle for the system caret.| +|[`CWindow::CreateSolidCaret`](#createsolidcaret)|Creates a solid rectangle for the system caret.| +|[`CWindow::DeferWindowPos`](#deferwindowpos)|Updates the specified multiple-window-position structure for the specified window.| +|[`CWindow::DestroyWindow`](#destroywindow)|Destroys the window associated with the `CWindow` object.| +|[`CWindow::Detach`](#detach)|Detaches the window from the `CWindow` object.| +|[`CWindow::DlgDirList`](#dlgdirlist)|Fills a list box with the names of all files matching a specified path or file name.| +|[`CWindow::DlgDirListComboBox`](#dlgdirlistcombobox)|Fills a combo box with the names of all files matching a specified path or file name.| +|[`CWindow::DlgDirSelect`](#dlgdirselect)|Retrieves the current selection from a list box.| +|[`CWindow::DlgDirSelectComboBox`](#dlgdirselectcombobox)|Retrieves the current selection from a combo box.| +|[`CWindow::DragAcceptFiles`](#dragacceptfiles)|Registers whether the window accepts dragged files.| +|[`CWindow::DrawMenuBar`](#drawmenubar)|Redraws the window's menu bar.| +|[`CWindow::EnableScrollBar`](#enablescrollbar)|Enables or disables the scroll bar arrows.| +|[`CWindow::EnableWindow`](#enablewindow)|Enables or disables input.| +|[`CWindow::EndPaint`](#endpaint)|Marks the end of painting.| +|[`CWindow::FlashWindow`](#flashwindow)|Flashes the window once.| +|[`CWindow::GetClientRect`](#getclientrect)|Retrieves the coordinates of the client area.| +|[`CWindow::GetDC`](#getdc)|Retrieves a device context for the client area.| +|[`CWindow::GetDCEx`](#getdcex)|Retrieves a device context for the client area and allows clipping options.| +|[`CWindow::GetDescendantWindow`](#getdescendantwindow)|Retrieves the specified descendant window.| +|[`CWindow::GetDlgControl`](#getdlgcontrol)|Retrieves an interface on the specified control.| +|[`CWindow::GetDlgCtrlID`](#getdlgctrlid)|Retrieves the window's identifier (for child windows only).| +|[`CWindow::GetDlgHost`](#getdlghost)|Retrieves a pointer to an interface to the ATL Control hosting container.| +|[`CWindow::GetDlgItem`](#getdlgitem)|Retrieves the specified child window.| +|[`CWindow::GetDlgItemInt`](#getdlgitemint)|Translates a control's text to an integer.| +|[`CWindow::GetDlgItemText`](#getdlgitemtext)|Retrieves a control's text.| +|[`CWindow::GetExStyle`](#getexstyle)|Retrieves the extended window styles.| +|[`CWindow::GetFont`](#getfont)|Retrieves the window's current font.| +|[`CWindow::GetHotKey`](#gethotkey)|Determines the hot key associated with the window.| +|[`CWindow::GetIcon`](#geticon)|Retrieves the window's large or small icon.| +|[`CWindow::GetLastActivePopup`](#getlastactivepopup)|Retrieves the most recently active pop-up window.| +|[`CWindow::GetMenu`](#getmenu)|Retrieves the window's menu.| +|[`CWindow::GetNextDlgGroupItem`](#getnextdlggroupitem)|Retrieves the previous or next control within a group of controls.| +|[`CWindow::GetNextDlgTabItem`](#getnextdlgtabitem)|Retrieves the previous or next control having the `WS_TABSTOP` style.| +|[`CWindow::GetParent`](#getparent)|Retrieves the immediate parent window.| +|[`CWindow::GetScrollInfo`](#getscrollinfo)|Retrieves the parameters of a scroll bar.| +|[`CWindow::GetScrollPos`](#getscrollpos)|Retrieves the position of the scroll box.| +|[`CWindow::GetScrollRange`](#getscrollrange)|Retrieves the scroll bar range.| +|[`CWindow::GetStyle`](#getstyle)|Retrieves the window styles.| +|[`CWindow::GetSystemMenu`](#getsystemmenu)|Creates a copy of the system menu for modification.| +|[`CWindow::GetTopLevelParent`](#gettoplevelparent)|Retrieves the top-level parent or owner window.| +|[`CWindow::GetTopLevelWindow`](#gettoplevelwindow)|Retrieves the top-level owner window.| +|[`CWindow::GetTopWindow`](#gettopwindow)|Retrieves the top-level child window.| +|[`CWindow::GetUpdateRect`](#getupdaterect)|Retrieves the coordinates of the smallest rectangle that completely encloses the update region.| +|[`CWindow::GetUpdateRgn`](#getupdatergn)|Retrieves the update region and copies it into a specified region.| +|[`CWindow::GetWindow`](#getwindow)|Retrieves the specified window.| +|[`CWindow::GetWindowContextHelpId`](#getwindowcontexthelpid)|Retrieves the window's help context identifier.| +|[`CWindow::GetWindowDC`](#getwindowdc)|Retrieves a device context for the entire window.| +|[`CWindow::GetWindowLong`](#getwindowlong)|Retrieves a 32-bit value at a specified offset into the extra window memory.| +|[`CWindow::GetWindowLongPtr`](#getwindowlongptr)|Retrieves information about the specified window, including a value at a specified offset into the extra window memory.| +|[`CWindow::GetWindowPlacement`](#getwindowplacement)|Retrieves the show state and positions.| +|[`CWindow::GetWindowProcessID`](#getwindowprocessid)|Retrieves the identifier of the process that created the window.| +|[`CWindow::GetWindowRect`](#getwindowrect)|Retrieves the window's bounding dimensions.| +|[`CWindow::GetWindowRgn`](#getwindowrgn)|Obtains a copy of the window region of a window.| +|[`CWindow::GetWindowText`](#getwindowtext)|Retrieves the window's text.| +|[`CWindow::GetWindowTextLength`](#getwindowtextlength)|Retrieves the length of the window's text.| +|[`CWindow::GetWindowThreadID`](#getwindowthreadid)|Retrieves the identifier of the thread that created the specified window.| +|[`CWindow::GetWindowWord`](#getwindowword)|Retrieves a 16-bit value at a specified offset into the extra window memory.| +|[`CWindow::GotoDlgCtrl`](#gotodlgctrl)|Sets the keyboard focus to a control in the dialog box.| +|[`CWindow::HideCaret`](#hidecaret)|Hides the system caret.| +|[`CWindow::HiliteMenuItem`](#hilitemenuitem)|Highlights or removes the highlight from a top-level menu item.| +|[`CWindow::Invalidate`](#invalidate)|Invalidates the entire client area.| +|[`CWindow::InvalidateRect`](#invalidaterect)|Invalidates the client area within the specified rectangle.| +|[`CWindow::InvalidateRgn`](#invalidatergn)|Invalidates the client area within the specified region.| +|[`CWindow::IsChild`](#ischild)|Determines whether the specified window is a child window.| +|[`CWindow::IsDialogMessage`](#isdialogmessage)|Determines whether a message is intended for the specified dialog box.| +|[`CWindow::IsDlgButtonChecked`](#isdlgbuttonchecked)|Determines the check state of the button.| +|[`CWindow::IsIconic`](#isiconic)|Determines whether the window is minimized.| +|[`CWindow::IsParentDialog`](#isparentdialog)|Determines if the parent window of a control is a dialog window.| +|[`CWindow::IsWindow`](#iswindow)|Determines whether the specified window handle identifies an existing window.| +|[`CWindow::IsWindowEnabled`](#iswindowenabled)|Determines whether the window is enabled for input.| +|[`CWindow::IsWindowUnicode`](#iswindowunicode)|Determines whether the specified window is a native Unicode window.| +|[`CWindow::IsWindowVisible`](#iswindowvisible)|Determines the window's visibility state.| +|[`CWindow::IsZoomed`](#iszoomed)|Determines whether the window is maximized.| +|[`CWindow::KillTimer`](#killtimer)|Destroys a timer event.| +|[`CWindow::LockWindowUpdate`](#lockwindowupdate)|Disables or enables drawing in the window.| +|[`CWindow::MapWindowPoints`](#mapwindowpoints)|Converts a set of points from the window's coordinate space to the coordinate space of another window.| +|[`CWindow::MessageBox`](#messagebox)|Displays a message box.| +|[`CWindow::ModifyStyle`](#modifystyle)|Modifies the window styles.| +|[`CWindow::ModifyStyleEx`](#modifystyleex)|Modifies the extended window styles.| +|[`CWindow::MoveWindow`](#movewindow)|Changes the window's size and position.| +|[`CWindow::NextDlgCtrl`](#nextdlgctrl)|Sets the keyboard focus to the next control in the dialog box.| +|[`CWindow::OpenClipboard`](#openclipboard)|Opens the Clipboard.| +|[`CWindow::PostMessage`](#postmessage)|Places a message in the message queue associated with the thread that created the window. Returns without waiting for the thread to process the message.| +|[`CWindow::PrevDlgCtrl`](#prevdlgctrl)|Sets the keyboard focus to the previous control in the dialog box.| +|[`CWindow::Print`](#print)|Requests that the window be drawn in a specified device context.| +|[`CWindow::PrintClient`](#printclient)|Requests that the window's client area be drawn in a specified device context.| +|[`CWindow::RedrawWindow`](#redrawwindow)|Updates a specified rectangle or region in the client area.| +|[`CWindow::ReleaseDC`](#releasedc)|Releases a device context.| +|[`CWindow::ResizeClient`](#resizeclient)|Resizes the window.| +|[`CWindow::ScreenToClient`](#screentoclient)|Converts screen coordinates to client coordinates.| +|[`CWindow::ScrollWindow`](#scrollwindow)|Scrolls the specified client area.| +|[`CWindow::ScrollWindowEx`](#scrollwindowex)|Scrolls the specified client area with additional features.| +|[`CWindow::SendDlgItemMessage`](#senddlgitemmessage)|Sends a message to a control.| +|[`CWindow::SendMessage`](#sendmessage)|Sends a message to the window and doesn't return until the window procedure has processed the message.| +|[`CWindow::SendMessageToDescendants`](#sendmessagetodescendants)|Sends a message to the specified descendant windows.| +|[`CWindow::SendNotifyMessage`](#sendnotifymessage)|Sends a message to the window. If the window was created by the calling thread, `SendNotifyMessage` doesn't return until the window procedure has processed the message. Otherwise, it returns immediately.| +|[`CWindow::SetActiveWindow`](#setactivewindow)|Activates the window.| +|[`CWindow::SetCapture`](#setcapture)|Sends all subsequent mouse input to the window.| +|[`CWindow::SetClipboardViewer`](#setclipboardviewer)|Adds the window to the Clipboard viewer chain.| +|[`CWindow::SetDlgCtrlID`](#setdlgctrlid)|Changes the window's identifier.| +|[`CWindow::SetDlgItemInt`](#setdlgitemint)|Changes a control's text to the string representation of an integer value.| +|[`CWindow::SetDlgItemText`](#setdlgitemtext)|Changes a control's text.| +|[`CWindow::SetFocus`](#setfocus)|Sets the input focus to the window.| +|[`CWindow::SetFont`](#setfont)|Changes the window's current font.| +|[`CWindow::SetHotKey`](#sethotkey)|Associates a hot key with the window.| +|[`CWindow::SetIcon`](#seticon)|Changes the window's large or small icon.| +|[`CWindow::SetMenu`](#setmenu)|Changes the window's current menu.| +|[`CWindow::SetParent`](#setparent)|Changes the parent window.| +|[`CWindow::SetRedraw`](#setredraw)|Sets or clears the redraw flag.| +|[`CWindow::SetScrollInfo`](#setscrollinfo)|Sets the parameters of a scroll bar.| +|[`CWindow::SetScrollPos`](#setscrollpos)|Changes the position of the scroll box.| +|[`CWindow::SetScrollRange`](#setscrollrange)|Changes the scroll bar range.| +|[`CWindow::SetTimer`](#settimer)|Creates a timer event.| +|[`CWindow::SetWindowContextHelpId`](#setwindowcontexthelpid)|Sets the window's help context identifier.| +|[`CWindow::SetWindowLong`](#setwindowlong)|Sets a 32-bit value at a specified offset into the extra window memory.| +|[`CWindow::SetWindowLongPtr`](#setwindowlongptr)|Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory.| +|[`CWindow::SetWindowPlacement`](#setwindowplacement)|Sets the show state and positions.| +|[`CWindow::SetWindowPos`](#setwindowpos)|Sets the size, position, and Z order.| +|[`CWindow::SetWindowRgn`](#setwindowrgn)|Sets the window region of a window.| +|[`CWindow::SetWindowText`](#setwindowtext)|Changes the window's text.| +|[`CWindow::SetWindowWord`](#setwindowword)|Sets a 16-bit value at a specified offset into the extra window memory.| +|[`CWindow::ShowCaret`](#showcaret)|Displays the system caret.| +|[`CWindow::ShowOwnedPopups`](#showownedpopups)|Shows or hides the pop-up windows owned by the window.| +|[`CWindow::ShowScrollBar`](#showscrollbar)|Shows or hides a scroll bar.| +|[`CWindow::ShowWindow`](#showwindow)|Sets the window's show state.| +|[`CWindow::ShowWindowAsync`](#showwindowasync)|Sets the show state of a window created by a different thread.| +|[`CWindow::UpdateWindow`](#updatewindow)|Updates the client area.| +|[`CWindow::ValidateRect`](#validaterect)|Validates the client area within the specified rectangle.| +|[`CWindow::ValidateRgn`](#validatergn)|Validates the client area within the specified region.| +|[`CWindow::WinHelp`](#winhelp)|Starts Windows Help.| ### Public Operators |Name|Description| |----------|-----------------| -|[CWindow::operator HWND](#operator_hwnd)|Converts the `CWindow` object to an HWND.| -|[CWindow::operator =](#operator_eq)|Assigns an HWND to the `CWindow` object.| +|[`CWindow::operator HWND`](#operator_hwnd)|Converts the `CWindow` object to an `HWND`.| +|[`CWindow::operator =`](#operator_eq)|Assigns an `HWND` to the `CWindow` object.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CWindow::m_hWnd](#m_hwnd)|The handle to the window associated with the `CWindow` object.| -|[CWindow::rcDefault](#rcdefault)|Contains default window dimensions.| +|[`CWindow::m_hWnd`](#m_hwnd)|The handle to the window associated with the `CWindow` object.| +|[`CWindow::rcDefault`](#rcdefault)|Contains default window dimensions.| ## Remarks `CWindow` provides the base functionality for manipulating a window in ATL. Many of the `CWindow` methods simply wrap one of the Win32 API functions. For example, compare the prototypes for `CWindow::ShowWindow` and `ShowWindow`: -|CWindow method|Win32 function| -|--------------------|--------------------| -|**BOOL ShowWindow( int** `nCmdShow` **);**|**BOOL ShowWindow( HWND** `hWnd` **, int** `nCmdShow` **);**| +| CWindow method | Win32 function | +|--|--| +| `BOOL ShowWindow( int nCmdShow );` | `BOOL ShowWindow( HWND hWnd , int nCmdShow );` | `CWindow::ShowWindow` calls the Win32 function `ShowWindow` by passing `CWindow::m_hWnd` as the first parameter. Every `CWindow` method that directly wraps a Win32 function passes the `m_hWnd` member; therefore, much of the `CWindow` documentation will refer you to the Windows SDK. > [!NOTE] > Not every window-related Win32 function is wrapped by `CWindow`, and not every `CWindow` method wraps a Win32 function. -`CWindow::m_hWnd` stores the HWND that identifies a window. An HWND is attached to your object when you: +`CWindow::m_hWnd` stores the `HWND` that identifies a window. An `HWND` is attached to your object when you: -- Specify an HWND in `CWindow`'s constructor. +- Specify an `HWND` in `CWindow`'s constructor. - Call `CWindow::Attach`. -- Use `CWindow`'s **operator =**. +- Use `CWindow`'s **`operator =`**. - Create or subclass a window using one of the following classes derived from `CWindow`: -[CWindowImpl](../../atl/reference/cwindowimpl-class.md) Allows you to create a new window or subclass an existing window. +[`CWindowImpl`](../../atl/reference/cwindowimpl-class.md) Allows you to create a new window or subclass an existing window. -[CContainedWindow](../../atl/reference/ccontainedwindowt-class.md) Implements a window contained within another object. You can create a new window or subclass an existing window. +[`CContainedWindow`](../../atl/reference/ccontainedwindowt-class.md) Implements a window contained within another object. You can create a new window or subclass an existing window. -[CDialogImpl](../../atl/reference/cdialogimpl-class.md) Allows you to create a modal or modeless dialog box. +[`CDialogImpl`](../../atl/reference/cdialogimpl-class.md) Allows you to create a modal or modeless dialog box. For more information about windows, see [Windows](/windows/win32/winmsg/windows) and subsequent topics in the Windows SDK. For more information about using windows in ATL, see the article [ATL Window Classes](../../atl/atl-window-classes.md). ## Requirements -**Header:** atlwin.h +**Header:** `atlwin.h` -## CWindow::ArrangeIconicWindows +## `CWindow::ArrangeIconicWindows` Arranges all minimized child windows. @@ -234,11 +233,11 @@ UINT ArrangeIconicWindows() throw(); ### Remarks -See [ArrangeIconicWindows](/windows/win32/api/winuser/nf-winuser-arrangeiconicwindows) in the Windows SDK. +See [`ArrangeIconicWindows`](/windows/win32/api/winuser/nf-winuser-arrangeiconicwindows) in the Windows SDK. -## CWindow::Attach +## `CWindow::Attach` -Attaches the window identified by *hWndNew* to the `CWindow` object. +Attaches the window identified by *`hWndNew`* to the `CWindow` object. ```cpp void Attach(HWND hWndNew) throw(); @@ -246,14 +245,14 @@ void Attach(HWND hWndNew) throw(); ### Parameters -*hWndNew*
+*`hWndNew`*\ [in] The handle to a window. ### Example [!code-cpp[NVC_ATL_Windowing#1](../../atl/codesnippet/cpp/cwindow-class_1.cpp)] -## CWindow::BeginPaint +## `CWindow::BeginPaint` Prepares the window for painting. @@ -263,13 +262,13 @@ HDC BeginPaint(LPPAINTSTRUCT lpPaint) throw(); ### Remarks -See [BeginPaint](/windows/win32/api/winuser/nf-winuser-beginpaint) in the Windows SDK. +See [`BeginPaint`](/windows/win32/api/winuser/nf-winuser-beginpaint) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#2](../../atl/codesnippet/cpp/cwindow-class_2.cpp)] -## CWindow::BringWindowToTop +## `CWindow::BringWindowToTop` Brings the window to the top of the Z order. @@ -279,13 +278,13 @@ BOOL BringWindowToTop() throw(); ### Remarks -See [BringWindowToTop](/windows/win32/api/winuser/nf-winuser-bringwindowtotop) in the Windows SDK. +See [`BringWindowToTop`](/windows/win32/api/winuser/nf-winuser-bringwindowtotop) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#3](../../atl/codesnippet/cpp/cwindow-class_3.cpp)] -## CWindow::CenterWindow +## `CWindow::CenterWindow` Centers the window against a given window. @@ -295,18 +294,18 @@ BOOL CenterWindow(HWND hWndCenter = NULL) throw(); ### Parameters -*hWndCenter*
-[in] The handle to the window against which to center. If this parameter is NULL (the default value), the method will set *hWndCenter* to the window's parent window if it is a child window. Otherwise, it will set *hWndCenter* to the window's owner window. +*`hWndCenter`*\ +[in] The handle to the window against which to center. If this parameter is `NULL` (the default value), the method will set *`hWndCenter`* to the window's parent window if it's a child window. Otherwise, it will set *`hWndCenter`* to the window's owner window. ### Return Value -TRUE if the window is successfully centered; otherwise, FALSE. +`TRUE` if the window is successfully centered; otherwise, `FALSE`. ### Example [!code-cpp[NVC_ATL_Windowing#4](../../atl/codesnippet/cpp/cwindow-class_4.cpp)] -## CWindow::ChangeClipboardChain +## `CWindow::ChangeClipboardChain` Removes the window from the chain of Clipboard viewers. @@ -316,9 +315,9 @@ BOOL ChangeClipboardChain(HWND hWndNewNext) throw(); ### Remarks -See [ChangeClipboardChain](/windows/win32/api/winuser/nf-winuser-changeclipboardchain) in the Windows SDK. +See [`ChangeClipboardChain`](/windows/win32/api/winuser/nf-winuser-changeclipboardchain) in the Windows SDK. -## CWindow::CheckDlgButton +## `CWindow::CheckDlgButton` Changes the check state of the specified button. @@ -328,9 +327,9 @@ BOOL CheckDlgButton(int nIDButton, UINT nCheck) throw(); ### Remarks -See [CheckDlgButton](/windows/win32/api/winuser/nf-winuser-checkdlgbutton) in the Windows SDK. +See [`CheckDlgButton`](/windows/win32/api/winuser/nf-winuser-checkdlgbutton) in the Windows SDK. -## CWindow::CheckRadioButton +## `CWindow::CheckRadioButton` Checks the specified radio button. @@ -343,9 +342,9 @@ BOOL CheckRadioButton( ### Remarks -See [CheckRadioButton](/windows/win32/api/winuser/nf-winuser-checkradiobutton) in the Windows SDK. +See [`CheckRadioButton`](/windows/win32/api/winuser/nf-winuser-checkradiobutton) in the Windows SDK. -## CWindow::ChildWindowFromPoint +## `CWindow::ChildWindowFromPoint` Retrieves the child window containing the specified point. @@ -355,9 +354,9 @@ HWND ChildWindowFromPoint(POINT point) const throw(); ### Remarks -See [ChildWindowFromPoint](/windows/win32/api/winuser/nf-winuser-childwindowfrompoint) in the Windows SDK. +See [`ChildWindowFromPoint`](/windows/win32/api/winuser/nf-winuser-childwindowfrompoint) in the Windows SDK. -## CWindow::ChildWindowFromPointEx +## `CWindow::ChildWindowFromPointEx` Retrieves a particular type of child window containing the specified point. @@ -367,9 +366,9 @@ HWND ChildWindowFromPoint(POINT point, UINT uFlags) const throw(); ### Remarks -See [ChildWindowFromPointEx](/windows/win32/api/winuser/nf-winuser-childwindowfrompointex) in the Windows SDK. +See [`ChildWindowFromPointEx`](/windows/win32/api/winuser/nf-winuser-childwindowfrompointex) in the Windows SDK. -## CWindow::ClientToScreen +## `CWindow::ClientToScreen` Converts client coordinates to screen coordinates. @@ -380,11 +379,11 @@ BOOL ClientToScreen(LPRECT lpRect) const throw(); ### Remarks -See [ClientToScreen](/windows/win32/api/winuser/nf-winuser-clienttoscreen) in the Windows SDK. +See [`ClientToScreen`](/windows/win32/api/winuser/nf-winuser-clienttoscreen) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::Create +## `CWindow::Create` Creates a window. @@ -402,43 +401,43 @@ HWND Create( ### Parameters -*lpstrWndClass*
+*`lpstrWndClass`*\ [in] A pointer to the window's class. -*hWndParent*
+*`hWndParent`*\ [in] The handle to the parent or owner window. -*rect*
-[in] A variable of type [_U_RECT](../../atl/reference/u-rect-class.md) specifying the position of the window. The default value is NULL. When this parameter is NULL, the value of `CWindow::rcDefault` is used. +*`rect`*\ +[in] A variable of type [`_U_RECT`](../../atl/reference/u-rect-class.md) specifying the position of the window. The default value is `NULL`. When this parameter is `NULL`, the value of `CWindow::rcDefault` is used. -*szWindowName*
-[in] Specifies the name of the window. The default value is NULL. +*`szWindowName`*\ +[in] Specifies the name of the window. The default value is `NULL`. -*dwStyle*
-[in] The style of the window. The default value is 0, meaning no style is specified. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. +*`dwStyle`*\ +[in] The style of the window. The default value is 0, meaning no style is specified. For a list of possible values, see [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. -*dwExStyle*
-[in] The extended window style. The default value is 0, meaning no extended style is specified. For a list of possible values, see [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwExStyle`*\ +[in] The extended window style. The default value is 0, meaning no extended style is specified. For a list of possible values, see [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. -*MenuOrID*
-[in] A variable of type [_U_MENUorID](../../atl/reference/u-menuorid-class.md) specifying a handle to a menu or a window identifier. The default value is 0U. +*`MenuOrID`*\ +[in] A variable of type [`_U_MENUorID`](../../atl/reference/u-menuorid-class.md) specifying a handle to a menu or a window identifier. The default value is `0U`. -*lpCreateParam*
-A pointer to the window-creation data contained in a [CREATESTRUCT](/windows/win32/api/winuser/ns-winuser-createstructw) structure. +*`lpCreateParam`*\ +A pointer to the window-creation data contained in a [`CREATESTRUCT`](/windows/win32/api/winuser/ns-winuser-createstructw) structure. ### Return Value -If successful, the handle to the newly created window, specified by [m_hWnd](#m_hwnd). Otherwise, NULL. +If successful, the handle to the newly created window, specified by [`m_hWnd`](#m_hwnd). Otherwise, `NULL`. ### Remarks `CWindow::rcDefault` is defined as `__declspec(selectany) RECT CWindow::rcDefault = {CW_USEDEFAULT, CW_USEDEFAULT, 0, 0};`. -See [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for more information. +See [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for more information. -**Note** If 0 is used as the value for the *MenuOrID* parameter, it must be specified as 0U (the default value) to avoid a compiler error. +**Note** If 0 is used as the value for the *`MenuOrID`* parameter, it must be specified as `0U` (the default value) to avoid a compiler error. -## CWindow::CreateCaret +## `CWindow::CreateCaret` Creates a new shape for the system caret. @@ -448,9 +447,9 @@ BOOL CreateCaret(HBITMAP pBitmap) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -## CWindow::CreateGrayCaret +## `CWindow::CreateGrayCaret` Creates a gray rectangle for the system caret. @@ -460,11 +459,11 @@ BOOL CreateGrayCaret(int nWidth, int nHeight) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -Passes (HBITMAP) 1 for the bitmap handle parameter to the Win32 function. +Passes `(HBITMAP) 1` for the bitmap handle parameter to the Win32 function. -## CWindow::CreateSolidCaret +## `CWindow::CreateSolidCaret` Creates a solid rectangle for the system caret. @@ -474,11 +473,11 @@ BOOL CreateSolidCaret(int nWidth, int nHeight) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -Passes (HBITMAP) 0 for the bitmap handle parameter to the Win32 function. +Passes `(HBITMAP) 0` for the bitmap handle parameter to the Win32 function. -## CWindow::CWindow +## `CWindow::CWindow` The constructor. @@ -488,17 +487,17 @@ CWindow(HWND hWnd = NULL) throw(); ### Parameters -*hWnd*
+*`hWnd`*\ [in] The handle to a window. ### Remarks -Initializes the [m_hWnd](#m_hwnd) member to *hWnd*, which by default is NULL. +Initializes the [`m_hWnd`](#m_hwnd) member to *`hWnd`*, which by default is `NULL`. > [!NOTE] -> `CWindow::CWindow` does not create a window. Classes [CWindowImpl](../../atl/reference/cwindowimpl-class.md), [CContainedWindow](../../atl/reference/ccontainedwindowt-class.md), and [CDialogImpl](../../atl/reference/cdialogimpl-class.md) (all of which derive from `CWindow`) provide a method to create a window or dialog box, which is then assigned to `CWindow::m_hWnd`. You can also use the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) Win32 function. +> `CWindow::CWindow` does not create a window. Classes [`CWindowImpl`](../../atl/reference/cwindowimpl-class.md), [`CContainedWindow`](../../atl/reference/ccontainedwindowt-class.md), and [`CDialogImpl`](../../atl/reference/cdialogimpl-class.md) (all of which derive from `CWindow`) provide a method to create a window or dialog box, which is then assigned to `CWindow::m_hWnd`. You can also use the [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) Win32 function. -## CWindow::DeferWindowPos +## `CWindow::DeferWindowPos` Updates the specified multiple-window-position structure for the specified window. @@ -515,11 +514,11 @@ HDWP DeferWindowPos( ### Remarks -See [DeferWindowPos](/windows/win32/api/winuser/nf-winuser-deferwindowpos) in the Windows SDK. +See [`DeferWindowPos`](/windows/win32/api/winuser/nf-winuser-deferwindowpos) in the Windows SDK. -## CWindow::DestroyWindow +## `CWindow::DestroyWindow` -Destroys the window associated with the `CWindow` object and sets [m_hWnd](#m_hwnd) to NULL. +Destroys the window associated with the `CWindow` object and sets [`m_hWnd`](#m_hwnd) to `NULL`. ``` BOOL DestroyWindow() throw(); @@ -527,17 +526,17 @@ BOOL DestroyWindow() throw(); ### Remarks -See [DestroyWindow](/windows/win32/api/winuser/nf-winuser-destroywindow) in the Windows SDK. +See [`DestroyWindow`](/windows/win32/api/winuser/nf-winuser-destroywindow) in the Windows SDK. -It does not destroy the `CWindow` object itself. +It doesn't destroy the `CWindow` object itself. ### Example [!code-cpp[NVC_ATL_Windowing#5](../../atl/codesnippet/cpp/cwindow-class_5.cpp)] -## CWindow::Detach +## `CWindow::Detach` -Detaches [m_hWnd](#m_hwnd) from the `CWindow` object and sets `m_hWnd` to NULL. +Detaches [`m_hWnd`](#m_hwnd) from the `CWindow` object and sets `m_hWnd` to `NULL`. ``` HWND Detach() throw(); @@ -545,13 +544,13 @@ HWND Detach() throw(); ### Return Value -The HWND associated with the `CWindow` object. +The `HWND` associated with the `CWindow` object. ### Example [!code-cpp[NVC_ATL_Windowing#6](../../atl/codesnippet/cpp/cwindow-class_6.cpp)] -## CWindow::DlgDirList +## `CWindow::DlgDirList` Fills a list box with the names of all files matching a specified path or file name. @@ -565,9 +564,9 @@ int DlgDirList( ### Remarks -See [DlgDirList](/windows/win32/api/winuser/nf-winuser-dlgdirlistw) in the Windows SDK. +See [`DlgDirList`](/windows/win32/api/winuser/nf-winuser-dlgdirlistw) in the Windows SDK. -## CWindow::DlgDirListComboBox +## `CWindow::DlgDirListComboBox` Fills a combo box with the names of all files matching a specified path or file name. @@ -581,9 +580,9 @@ int DlgDirListComboBox( ### Remarks -See [DlgDirListComboBox](/windows/win32/api/winuser/nf-winuser-dlgdirlistcomboboxw) in the Windows SDK. +See [`DlgDirListComboBox`](/windows/win32/api/winuser/nf-winuser-dlgdirlistcomboboxw) in the Windows SDK. -## CWindow::DlgDirSelect +## `CWindow::DlgDirSelect` Retrieves the current selection from a list box. @@ -596,9 +595,9 @@ BOOL DlgDirSelect( ### Remarks -See [DlgDirSelectEx](/windows/win32/api/winuser/nf-winuser-dlgdirselectexw) in the Windows SDK. +See [`DlgDirSelectEx`](/windows/win32/api/winuser/nf-winuser-dlgdirselectexw) in the Windows SDK. -## CWindow::DlgDirSelectComboBox +## `CWindow::DlgDirSelectComboBox` Retrieves the current selection from a combo box. @@ -611,9 +610,9 @@ BOOL DlgDirSelectComboBox( ### Remarks -See [DlgDirSelectComboBoxEx](/windows/win32/api/winuser/nf-winuser-dlgdirselectcomboboxexw) in the Windows SDK. +See [`DlgDirSelectComboBoxEx`](/windows/win32/api/winuser/nf-winuser-dlgdirselectcomboboxexw) in the Windows SDK. -## CWindow::DragAcceptFiles +## `CWindow::DragAcceptFiles` Registers whether the window accepts dragged files. @@ -623,9 +622,9 @@ void DragAcceptFiles(BOOL bAccept = TRUE); ### Remarks -See [DragAcceptFiles](/windows/win32/api/shellapi/nf-shellapi-dragacceptfiles) in the Windows SDK. +See [`DragAcceptFiles`](/windows/win32/api/shellapi/nf-shellapi-dragacceptfiles) in the Windows SDK. -## CWindow::DrawMenuBar +## `CWindow::DrawMenuBar` Redraws the window's menu bar. @@ -635,9 +634,9 @@ BOOL DrawMenuBar() throw(); ### Remarks -See [DrawMenuBar](/windows/win32/api/winuser/nf-winuser-drawmenubar) in the Windows SDK. +See [`DrawMenuBar`](/windows/win32/api/winuser/nf-winuser-drawmenubar) in the Windows SDK. -## CWindow::EnableScrollBar +## `CWindow::EnableScrollBar` Enables or disables the scroll bar arrows. @@ -647,9 +646,9 @@ BOOL EnableScrollBar(UINT uSBFlags, UINT uArrowFlags = ESB_ENABLE_BOTH) throw(); ### Remarks -See [EnableScrollBar](/windows/win32/api/winuser/nf-winuser-enablescrollbar) in the Windows SDK. +See [`EnableScrollBar`](/windows/win32/api/winuser/nf-winuser-enablescrollbar) in the Windows SDK. -## CWindow::EnableWindow +## `CWindow::EnableWindow` Enables or disables input. @@ -659,13 +658,13 @@ BOOL EnableWindow(BOOL bEnable = TRUE) throw(); ### Remarks -See [EnableWindow](/windows/win32/api/winuser/nf-winuser-enablewindow) in the Windows SDK. +See [`EnableWindow`](/windows/win32/api/winuser/nf-winuser-enablewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#7](../../atl/codesnippet/cpp/cwindow-class_7.cpp)] -## CWindow::EndPaint +## `CWindow::EndPaint` Marks the end of painting. @@ -675,13 +674,13 @@ void EndPaint(LPPAINTSTRUCT lpPaint) throw(); ### Remarks -See [EndPaint](/windows/win32/api/winuser/nf-winuser-endpaint) in the Windows SDK. +See [`EndPaint`](/windows/win32/api/winuser/nf-winuser-endpaint) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#2](../../atl/codesnippet/cpp/cwindow-class_2.cpp)] -## CWindow::FlashWindow +## `CWindow::FlashWindow` Flashes the window once. @@ -691,9 +690,9 @@ BOOL FlashWindow(BOOL bInvert) throw(); ### Remarks -See [FlashWindow](/windows/win32/api/winuser/nf-winuser-flashwindow) in the Windows SDK. +See [`FlashWindow`](/windows/win32/api/winuser/nf-winuser-flashwindow) in the Windows SDK. -## CWindow::GetClientRect +## `CWindow::GetClientRect` Retrieves the coordinates of the client area. @@ -703,13 +702,13 @@ BOOL GetClientRect(LPRECT lpRect) const throw(); ### Remarks -See [GetClientRect](/windows/win32/api/winuser/nf-winuser-getclientrect) in the Windows SDK. +See [`GetClientRect`](/windows/win32/api/winuser/nf-winuser-getclientrect) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#8](../../atl/codesnippet/cpp/cwindow-class_8.cpp)] -## CWindow::GetDC +## `CWindow::GetDC` Retrieves a device context for the client area. @@ -719,13 +718,13 @@ HDC GetDC() throw(); ### Remarks -See [GetDC](/windows/win32/api/winuser/nf-winuser-getdc) in the Windows SDK. +See [`GetDC`](/windows/win32/api/winuser/nf-winuser-getdc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#9](../../atl/codesnippet/cpp/cwindow-class_9.cpp)] -## CWindow::GetDCEx +## `CWindow::GetDCEx` Retrieves a device context for the client area and allows clipping options. @@ -735,9 +734,9 @@ HDC GetDCEx(HRGN hRgnClip, DWORD flags) throw(); ### Remarks -See [GetDCEx](/windows/win32/api/winuser/nf-winuser-getdcex) in the Windows SDK. +See [`GetDCEx`](/windows/win32/api/winuser/nf-winuser-getdcex) in the Windows SDK. -## CWindow::GetDescendantWindow +## `CWindow::GetDescendantWindow` Finds the descendant window specified by the given identifier. @@ -747,7 +746,7 @@ HWND GetDescendantWindow(int nID) const throw(); ### Parameters -*nID*
+*`nID`*\ [in] The identifier of the descendant window to be retrieved. ### Return Value @@ -758,7 +757,7 @@ The handle to a descendant window. `GetDescendantWindow` searches the entire tree of child windows, not only the windows that are immediate children. -## CWindow::GetDlgControl +## `CWindow::GetDlgControl` Call this function to get a pointer to an interface of an ActiveX control that is hosted by a composite control or a control-hosting dialog. @@ -771,24 +770,24 @@ HRESULT GetDlgControl( ### Parameters -*nID*
+*`nID`*\ [in] The resource ID of the control being retrieved. -*iid*
+*`iid`*\ [in] The ID of the interface you would like to get from the control. -*ppCtrl*
+*`ppCtrl`*\ [out] The pointer to the interface. ### Return Value -Returns S_OK on success or any valid error HRESULT. For example, the function returns E_FAIL if the control specified by *nID* cannot be found and it returns E_NOINTERFACE if the control can be found, but it doesn't support the interface specified by *iid*. +Returns `S_OK` on success or any valid error `HRESULT`. For example, the function returns `E_FAIL` if the control specified by *`nID`* can't be found and it returns `E_NOINTERFACE` if the control can be found, but it doesn't support the interface specified by *`iid`*. ### Remarks Using this pointer, you can call methods on the interface. -## CWindow::GetDlgCtrlID +## `CWindow::GetDlgCtrlID` Retrieves the window's identifier (for child windows only). @@ -798,9 +797,9 @@ int GetDlgCtrlID() const throw(); ### Remarks -See [GetDlgCtrlID](/windows/win32/api/winuser/nf-winuser-getdlgctrlid) in the Windows SDK. +See [`GetDlgCtrlID`](/windows/win32/api/winuser/nf-winuser-getdlgctrlid) in the Windows SDK. -## CWindow::GetDlgHost +## `CWindow::GetDlgHost` Retrieves a pointer to an interface to the ATL Control hosting container. @@ -813,24 +812,24 @@ HRESULT GetDlgHost( ### Parameters -*nID*
+*`nID`*\ [in] The resource ID of the control being retrieved. -*iid*
+*`iid`*\ [in] The ID of the interface you would like to get from the control. -*ppHost*
+*`ppHost`*\ [out] The pointer to the interface. ### Return Value -Returns S_OK if the window specified by *iid* is a Control Container, and the requested interface could be retrieved. Returns E_FAIL if the window is not a Control Container, or if the interface requested could not be retrieved. If a window with the specified ID could not be found, then the return value is equal to HRESULT_FROM_WIN32(ERROR_CONTROL_ID_NOT_FOUND). +Returns `S_OK` if the window specified by *`iid`* is a Control Container, and the requested interface could be retrieved. Returns `E_FAIL` if the window isn't a Control Container, or if the interface requested couldn't be retrieved. If a window with the specified ID couldn't be found, then the return value is equal to `HRESULT_FROM_WIN32(ERROR_CONTROL_ID_NOT_FOUND)`. ### Remarks Using this pointer, you can call methods on the interface. -## CWindow::GetDlgItem +## `CWindow::GetDlgItem` Retrieves the specified child window. @@ -842,7 +841,7 @@ HWND GetDlgItem(int nID) const throw(); See [GetDlgItem](/windows/win32/api/winuser/nf-winuser-getdlgitem) in the Windows SDK. -## CWindow::GetDlgItemInt +## `CWindow::GetDlgItemInt` Translates a control's text to an integer. @@ -855,9 +854,9 @@ UINT GetDlgItemInt( ### Remarks -See [GetDlgItemInt](/windows/win32/api/winuser/nf-winuser-getdlgitemint) in the Windows SDK. +See [`GetDlgItemInt`](/windows/win32/api/winuser/nf-winuser-getdlgitemint) in the Windows SDK. -## CWindow::GetDlgItemText +## `CWindow::GetDlgItemText` Retrieves a control's text. @@ -876,9 +875,9 @@ BOOL GetDlgItemText( For more information, see [`GetDlgItemText`](/windows/win32/api/winuser/nf-winuser-getdlgitemtextw) in the Windows SDK. -The second version of this method allows you to copy the control's text to a BSTR. This version returns TRUE if the text is successfully copied; otherwise, FALSE. +The second version of this method allows you to copy the control's text to a `BSTR`. This version returns `TRUE` if the text is successfully copied; otherwise, `FALSE`. -## CWindow::GetExStyle +## `CWindow::GetExStyle` Retrieves the extended window styles of the window. @@ -892,15 +891,15 @@ The window's extended styles. ### Remarks -To retrieve the regular window styles, call [GetStyle](#getstyle). +To retrieve the regular window styles, call [`GetStyle`](#getstyle). ### Example [!code-cpp[NVC_ATL_Windowing#10](../../atl/codesnippet/cpp/cwindow-class_10.cpp)] -## CWindow::GetFont +## `CWindow::GetFont` -Retrieves the window's current font by sending a [WM_GETFONT](/windows/win32/winmsg/wm-getfont) message to the window. +Retrieves the window's current font by sending a [`WM_GETFONT`](/windows/win32/winmsg/wm-getfont) message to the window. ``` HFONT GetFont() const throw(); @@ -910,9 +909,9 @@ HFONT GetFont() const throw(); A font handle. -## CWindow::GetHotKey +## `CWindow::GetHotKey` -Determines the hot key associated with the window by sending a WM_GETHOTKEY message. +Determines the hot key associated with the window by sending a `WM_GETHOTKEY` message. ``` DWORD GetHotKey() const throw(); @@ -920,9 +919,9 @@ DWORD GetHotKey() const throw(); ### Return Value -The virtual key code and modifiers for the hot key associated with the window. For a list of possible modifiers, see [WM_GETHOTKEY](/windows/win32/inputdev/wm-gethotkey) in the Windows SDK. For a list of standard virtual key codes, see Winuser.h. +The virtual key code and modifiers for the hot key associated with the window. For a list of possible modifiers, see [`WM_GETHOTKEY`](/windows/win32/inputdev/wm-gethotkey) in the Windows SDK. For a list of standard virtual key codes, see `Winuser.h`. -## CWindow::GetIcon +## `CWindow::GetIcon` Retrieves the handle to the window's large or small icon. @@ -932,8 +931,8 @@ HICON GetIcon(BOOL bBigIcon = TRUE) const; ### Parameters -*bBigIcon*
-[in] If TRUE (the default value) the method returns the large icon. Otherwise, it returns the small icon. +*`bBigIcon`*\ +[in] If `TRUE` (the default value) the method returns the large icon. Otherwise, it returns the small icon. ### Return Value @@ -941,9 +940,9 @@ An icon handle. ### Remarks -`GetIcon` sends a [WM_GETICON](/windows/win32/winmsg/wm-geticon) message to the window. +`GetIcon` sends a [`WM_GETICON`](/windows/win32/winmsg/wm-geticon) message to the window. -## CWindow::GetLastActivePopup +## `CWindow::GetLastActivePopup` Retrieves the most recently active pop-up window. @@ -953,9 +952,9 @@ HWND GetLastActivePopup() const throw(); ### Remarks -See [GetLastActivePopup](/windows/win32/api/winuser/nf-winuser-getlastactivepopup) in the Windows SDK. +See [`GetLastActivePopup`](/windows/win32/api/winuser/nf-winuser-getlastactivepopup) in the Windows SDK. -## CWindow::GetMenu +## `CWindow::GetMenu` Retrieves the window's menu. @@ -965,9 +964,9 @@ HMENU GetMenu() const throw(); ### Remarks -See [GetMenu](/windows/win32/api/winuser/nf-winuser-getmenu) in the Windows SDK. +See [`GetMenu`](/windows/win32/api/winuser/nf-winuser-getmenu) in the Windows SDK. -## CWindow::GetNextDlgGroupItem +## `CWindow::GetNextDlgGroupItem` Retrieves the previous or next control within a group of controls. @@ -977,11 +976,11 @@ HWND GetNextDlgGroupItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); ### Remarks -See [GetNextDlgGroupItem](/windows/win32/api/winuser/nf-winuser-getnextdlggroupitem) in the Windows SDK. +See [`GetNextDlgGroupItem`](/windows/win32/api/winuser/nf-winuser-getnextdlggroupitem) in the Windows SDK. -## CWindow::GetNextDlgTabItem +## `CWindow::GetNextDlgTabItem` -Retrieves the previous or next control having the WS_TABSTOP style. +Retrieves the previous or next control having the `WS_TABSTOP` style. ``` HWND GetNextDlgTabItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); @@ -989,9 +988,9 @@ HWND GetNextDlgTabItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); ### Remarks -See [GetNextDlgTabItem](/windows/win32/api/winuser/nf-winuser-getnextdlgtabitem) in the Windows SDK. +See [`GetNextDlgTabItem`](/windows/win32/api/winuser/nf-winuser-getnextdlgtabitem) in the Windows SDK. -## CWindow::GetParent +## `CWindow::GetParent` Retrieves the immediate parent window. @@ -1001,13 +1000,13 @@ HWND GetParent() const throw(); ### Remarks -See [GetParent](/windows/win32/api/winuser/nf-winuser-getparent) in the Windows SDK. +See [`GetParent`](/windows/win32/api/winuser/nf-winuser-getparent) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#11](../../atl/codesnippet/cpp/cwindow-class_11.cpp)] -## CWindow::GetScrollInfo +## `CWindow::GetScrollInfo` Retrieves the parameters of a scroll bar. @@ -1017,9 +1016,9 @@ BOOL GetScrollInfo(int nBar, LPSCROLLINFO lpScrollInfo) throw(); ### Remarks -See [GetScrollInfo](/windows/win32/api/winuser/nf-winuser-getscrollinfo) in the Windows SDK. +See [`GetScrollInfo`](/windows/win32/api/winuser/nf-winuser-getscrollinfo) in the Windows SDK. -## CWindow::GetScrollPos +## `CWindow::GetScrollPos` Retrieves the position of the scroll box. @@ -1029,9 +1028,9 @@ int GetScrollPos(int nBar) const throw(); ### Remarks -See [GetScrollPos](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. +See [`GetScrollPos`](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. -## CWindow::GetScrollRange +## `CWindow::GetScrollRange` Retrieves the scroll bar range. @@ -1044,9 +1043,9 @@ BOOL GetScrollRange( ### Remarks -See [GetScrollRange](/windows/win32/api/winuser/nf-winuser-getscrollrange) in the Windows SDK. +See [`GetScrollRange`](/windows/win32/api/winuser/nf-winuser-getscrollrange) in the Windows SDK. -## CWindow::GetStyle +## `CWindow::GetStyle` Retrieves the window styles of the window. @@ -1060,13 +1059,13 @@ The window's styles. ### Remarks -To retrieve the extended window styles, call [GetExStyle](#getexstyle). +To retrieve the extended window styles, call [`GetExStyle`](#getexstyle). ### Example [!code-cpp[NVC_ATL_Windowing#12](../../atl/codesnippet/cpp/cwindow-class_12.cpp)] -## CWindow::GetSystemMenu +## `CWindow::GetSystemMenu` Creates a copy of the system menu for modification. @@ -1076,9 +1075,9 @@ HMENU GetSystemMenu(BOOL bRevert) const throw(); ### Remarks -See [GetSystemMenu](/windows/win32/api/winuser/nf-winuser-getsystemmenu) in the Windows SDK. +See [`GetSystemMenu`](/windows/win32/api/winuser/nf-winuser-getsystemmenu) in the Windows SDK. -## CWindow::GetTopLevelParent +## `CWindow::GetTopLevelParent` Retrieves the window's top-level parent window. @@ -1090,7 +1089,7 @@ HWND GetTopLevelParent() const throw(); The handle to the top-level parent window. -## CWindow::GetTopLevelWindow +## `CWindow::GetTopLevelWindow` Retrieves the window's top-level parent or owner window. @@ -1102,7 +1101,7 @@ HWND GetTopLevelWindow() const throw(); The handle to the top-level owner window. -## CWindow::GetTopWindow +## `CWindow::GetTopWindow` Retrieves the top-level child window. @@ -1112,13 +1111,13 @@ HWND GetTopWindow() const throw(); ### Remarks -See [GetTopWindow](/windows/win32/api/winuser/nf-winuser-gettopwindow) in the Windows SDK. +See [`GetTopWindow`](/windows/win32/api/winuser/nf-winuser-gettopwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#13](../../atl/codesnippet/cpp/cwindow-class_13.cpp)] -## CWindow::GetUpdateRect +## `CWindow::GetUpdateRect` Retrieves the coordinates of the smallest rectangle that completely encloses the update region. @@ -1128,9 +1127,9 @@ BOOL GetUpdateRect(LPRECT lpRect, BOOL bErase = FALSE) throw(); ### Remarks -See [GetUpdateRect](/windows/win32/api/winuser/nf-winuser-getupdaterect) in the Windows SDK. +See [`GetUpdateRect`](/windows/win32/api/winuser/nf-winuser-getupdaterect) in the Windows SDK. -## CWindow::GetUpdateRgn +## `CWindow::GetUpdateRgn` Retrieves the update region and copies it into a specified region. @@ -1140,9 +1139,9 @@ int GetUpdateRgn(HRGN hRgn, BOOL bErase = FALSE) throw(); ### Remarks -See [GetUpdateRgn](/windows/win32/api/winuser/nf-winuser-getupdatergn) in the Windows SDK. +See [`GetUpdateRgn`](/windows/win32/api/winuser/nf-winuser-getupdatergn) in the Windows SDK. -## CWindow::GetWindow +## `CWindow::GetWindow` Retrieves the specified window. @@ -1154,7 +1153,7 @@ HWND GetWindow(UINT nCmd) const throw(); See `GetWindow` in the Windows SDK. -## CWindow::GetWindowContextHelpId +## `CWindow::GetWindowContextHelpId` Retrieves the window's help context identifier. @@ -1164,9 +1163,9 @@ DWORD GetWindowContextHelpId() const throw(); ### Remarks -See [GetWindowContextHelpId](/windows/win32/api/winuser/nf-winuser-getwindowcontexthelpid) in the Windows SDK. +See [`GetWindowContextHelpId`](/windows/win32/api/winuser/nf-winuser-getwindowcontexthelpid) in the Windows SDK. -## CWindow::GetWindowDC +## `CWindow::GetWindowDC` Retrieves a device context for the entire window. @@ -1176,13 +1175,13 @@ HDC GetWindowDC() throw(); ### Remarks -See [GetWindowDC](/windows/win32/api/winuser/nf-winuser-getwindowdc) in the Windows SDK. +See [`GetWindowDC`](/windows/win32/api/winuser/nf-winuser-getwindowdc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#14](../../atl/codesnippet/cpp/cwindow-class_14.cpp)] -## CWindow::GetWindowLong +## `CWindow::GetWindowLong` Retrieves a 32-bit value at a specified offset into the extra window memory. @@ -1192,12 +1191,12 @@ LONG GetWindowLong(int nIndex) const throw(); ### Remarks -See [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. +See [`GetWindowLong`](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. > [!NOTE] -> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [CWindow::GetWindowLongPtr](#getwindowlongptr). +> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [`CWindow::GetWindowLongPtr`](#getwindowlongptr). -## CWindow::GetWindowLongPtr +## `CWindow::GetWindowLongPtr` Retrieves information about the specified window, including a value at a specified offset into the extra window memory. @@ -1209,14 +1208,14 @@ LONG_PTR GetWindowLongPtr(int nIndex) const throw(); For more information, see [`GetWindowLongPtr`](/windows/win32/api/winuser/nf-winuser-getwindowlongptrw) in the Windows SDK. -If you are retrieving a pointer or a handle, this function supersedes the `CWindow::GetWindowLong` method. +If you're retrieving a pointer or a handle, this function supersedes the `CWindow::GetWindowLong` method. > [!NOTE] > Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows. To write code that is compatible with both 32-bit and 64-bit versions of Windows, use `CWindow::GetWindowLongPtr`. -## CWindow::GetWindowPlacement +## `CWindow::GetWindowPlacement` Retrieves the show state and positions. @@ -1226,9 +1225,9 @@ BOOL GetWindowPlacement(WINDOWPLACEMENT FAR* lpwndpl) const throw(); ### Remarks -See [GetWindowPlacement](/windows/win32/api/winuser/nf-winuser-getwindowplacement) in the Windows SDK. +See [`GetWindowPlacement`](/windows/win32/api/winuser/nf-winuser-getwindowplacement) in the Windows SDK. -## CWindow::GetWindowProcessID +## `CWindow::GetWindowProcessID` Retrieves the identifier of the process that created the window. @@ -1238,13 +1237,13 @@ DWORD GetWindowProcessID() throw(); ### Remarks -See [GetWindowThreadProcessID](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. +See [`GetWindowThreadProcessID`](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#15](../../atl/codesnippet/cpp/cwindow-class_15.cpp)] -## CWindow::GetWindowRect +## `CWindow::GetWindowRect` Retrieves the window's bounding dimensions. @@ -1254,9 +1253,9 @@ BOOL GetWindowRect(LPRECT lpRect) const throw(); ### Remarks -See [GetWindowRect](/windows/win32/api/winuser/nf-winuser-getwindowrect) in the Windows SDK. +See [`GetWindowRect`](/windows/win32/api/winuser/nf-winuser-getwindowrect) in the Windows SDK. -## CWindow::GetWindowRgn +## `CWindow::GetWindowRgn` Obtains a copy of the window region of a window. @@ -1266,9 +1265,9 @@ int GetWindowRgn(HRGN hRgn) throw(); ### Remarks -See [GetWindowRgn](/windows/win32/api/winuser/nf-winuser-getwindowrgn) in the Windows SDK. +See [`GetWindowRgn`](/windows/win32/api/winuser/nf-winuser-getwindowrgn) in the Windows SDK. -## CWindow::GetWindowText +## `CWindow::GetWindowText` Retrieves the window's text. @@ -1280,29 +1279,29 @@ int GetWindowText(CSimpleString& strText) const; ### Parameters -*lpszStringBuf*
+*`lpszStringBuf`*\ A buffer to which to write the window text. -*nMaxCount*
+*`nMaxCount`*\ The size of the buffer in characters; also the maximum number of characters to write. -*bstrText*
-A BSTR in which to store the window text. +*`bstrText`*\ +A `BSTR` in which to store the window text. -*strText*
+*`strText`*\ A `CString` in which to store the window text. ### Return Value -If the text is successfully copied, the return value is TRUE; otherwise, the return value is FALSE. +If the text is successfully copied, the return value is `TRUE`; otherwise, the return value is `FALSE`. ### Remarks -See [GetWindowText](/windows/win32/api/winuser/nf-winuser-getwindowtextw) in the Windows SDK. +See [`GetWindowText`](/windows/win32/api/winuser/nf-winuser-getwindowtextw) in the Windows SDK. -The second version of this method allows you to store the text in a BSTR; the third version allows you to store the result in a [CString](../../atl-mfc-shared/reference/cstringt-class.md), since `CSimpleString` is the base class of `CString`. +The second version of this method allows you to store the text in a `BSTR`; the third version allows you to store the result in a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md), since `CSimpleString` is the base class of `CString`. -## CWindow::GetWindowTextLength +## `CWindow::GetWindowTextLength` Retrieves the length of the window's text. @@ -1312,9 +1311,9 @@ int GetWindowTextLength() const throw(); ### Remarks -See [GetWindowTextLength](/windows/win32/api/winuser/nf-winuser-getwindowtextlengthw) in the Windows SDK. +See [`GetWindowTextLength`](/windows/win32/api/winuser/nf-winuser-getwindowtextlengthw) in the Windows SDK. -## CWindow::GetWindowThreadID +## `CWindow::GetWindowThreadID` Retrieves the identifier of the thread that created the specified window. @@ -1324,13 +1323,13 @@ DWORD GetWindowThreadID() throw(); ### Remarks -See [GetWindowThreadProcessID](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. +See [`GetWindowThreadProcessID`](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#16](../../atl/codesnippet/cpp/cwindow-class_16.cpp)] -## CWindow::GetWindowWord +## `CWindow::GetWindowWord` Retrieves a 16-bit value at a specified offset into the extra window memory. @@ -1340,9 +1339,9 @@ WORD GetWindowWord(int nIndex) const throw(); ### Remarks -See [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. +See [`GetWindowLong`](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. -## CWindow::GotoDlgCtrl +## `CWindow::GotoDlgCtrl` Sets the keyboard focus to a control in the dialog box. @@ -1352,9 +1351,9 @@ void GotoDlgCtrl(HWND hWndCtrl) const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::HideCaret +## `CWindow::HideCaret` Hides the system caret. @@ -1364,13 +1363,13 @@ BOOL HideCaret() throw(); ### Remarks -See [HideCaret](/windows/win32/api/winuser/nf-winuser-hidecaret) in the Windows SDK. +See [`HideCaret`](/windows/win32/api/winuser/nf-winuser-hidecaret) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#17](../../atl/codesnippet/cpp/cwindow-class_17.cpp)] -## CWindow::HiliteMenuItem +## `CWindow::HiliteMenuItem` Highlights or removes the highlight from a top-level menu item. @@ -1383,9 +1382,9 @@ BOOL HiliteMenuItem( ### Remarks -See [HiliteMenuItem](/windows/win32/api/winuser/nf-winuser-hilitemenuitem) in the Windows SDK. +See [`HiliteMenuItem`](/windows/win32/api/winuser/nf-winuser-hilitemenuitem) in the Windows SDK. -## CWindow::Invalidate +## `CWindow::Invalidate` Invalidates the entire client area. @@ -1395,15 +1394,15 @@ BOOL Invalidate(BOOL bErase = TRUE) throw(); ### Remarks -See [InvalidateRect](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. +See [`InvalidateRect`](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. -Passes NULL for the `RECT` parameter to the `InvalidateRect` Win32 function. +Passes `NULL` for the `RECT` parameter to the `InvalidateRect` Win32 function. ### Example [!code-cpp[NVC_ATL_Windowing#18](../../atl/codesnippet/cpp/cwindow-class_18.cpp)] -## CWindow::InvalidateRect +## `CWindow::InvalidateRect` Invalidates the client area within the specified rectangle. @@ -1413,9 +1412,9 @@ BOOL InvalidateRect(LPCRECT lpRect, BOOL bErase = TRUE) throw(); ### Remarks -See [InvalidateRect](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. +See [`InvalidateRect`](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. -## CWindow::InvalidateRgn +## `CWindow::InvalidateRgn` Invalidates the client area within the specified region. @@ -1427,9 +1426,9 @@ void InvalidateRgn(HRGN hRgn, BOOL bErase = TRUE) throw(); For more information, see [`InvalidateRgn`](/windows/win32/api/winuser/nf-winuser-invalidatergn) in the Windows SDK. -Specifies a **`void`** return type, while the `InvalidateRgn` Win32 function always returns TRUE. +Specifies a **`void`** return type, while the `InvalidateRgn` Win32 function always returns `TRUE`. -## CWindow::IsChild +## `CWindow::IsChild` Determines whether the specified window is a child window. @@ -1439,9 +1438,9 @@ BOOL IsChild(const HWND hWnd) const throw(); ### Remarks -See [IsChild](/windows/win32/api/winuser/nf-winuser-ischild) in the Windows SDK. +See [`IsChild`](/windows/win32/api/winuser/nf-winuser-ischild) in the Windows SDK. -## CWindow::IsDialogMessage +## `CWindow::IsDialogMessage` Determines whether a message is intended for the specified dialog box. @@ -1451,9 +1450,9 @@ BOOL IsDialogMessage(LPMSG lpMsg) throw(); ### Remarks -See [IsDialogMessage](/windows/win32/api/winuser/nf-winuser-isdialogmessagew) in the Windows SDK. +See [`IsDialogMessage`](/windows/win32/api/winuser/nf-winuser-isdialogmessagew) in the Windows SDK. -## CWindow::IsDlgButtonChecked +## `CWindow::IsDlgButtonChecked` Determines the check state of the button. @@ -1463,9 +1462,9 @@ UINT IsDlgButtonChecked(int nIDButton) const throw(); ### Remarks -See [IsDlgButtonChecked](/windows/win32/api/winuser/nf-winuser-isdlgbuttonchecked) in the Windows SDK. +See [`IsDlgButtonChecked`](/windows/win32/api/winuser/nf-winuser-isdlgbuttonchecked) in the Windows SDK. -## CWindow::IsIconic +## `CWindow::IsIconic` Determines whether the window is minimized. @@ -1475,13 +1474,13 @@ BOOL IsIconic() const throw(); ### Remarks -See [IsIconic](/windows/win32/api/winuser/nf-winuser-isiconic) in the Windows SDK. +See [`IsIconic`](/windows/win32/api/winuser/nf-winuser-isiconic) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#19](../../atl/codesnippet/cpp/cwindow-class_19.cpp)] -## CWindow::IsParentDialog +## `CWindow::IsParentDialog` Determines if the parent window of the control is a dialog window. @@ -1491,9 +1490,9 @@ BOOL IsParentDialog() throw(); ### Return Value -Returns TRUE if the parent window is a dialog, FALSE otherwise. +Returns `TRUE` if the parent window is a dialog, `FALSE` otherwise. -## CWindow::IsWindow +## `CWindow::IsWindow` Determines whether the specified window handle identifies an existing window. @@ -1503,13 +1502,13 @@ BOOL IsWindow() throw(); ### Remarks -See [IsWindow](/windows/win32/api/winuser/nf-winuser-iswindow) in the Windows SDK. +See [`IsWindow`](/windows/win32/api/winuser/nf-winuser-iswindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#20](../../atl/codesnippet/cpp/cwindow-class_20.cpp)] -## CWindow::IsWindowEnabled +## `CWindow::IsWindowEnabled` Determines whether the window is enabled for input. @@ -1519,13 +1518,13 @@ BOOL IsWindowEnabled() const throw(); ### Remarks -See [IsWindowEnabled](/windows/win32/api/winuser/nf-winuser-iswindowenabled) in the Windows SDK. +See [`IsWindowEnabled`](/windows/win32/api/winuser/nf-winuser-iswindowenabled) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#21](../../atl/codesnippet/cpp/cwindow-class_21.cpp)] -## CWindow::IsWindowVisible +## `CWindow::IsWindowVisible` Determines the window's visibility state. @@ -1535,13 +1534,13 @@ BOOL IsWindowVisible() const throw(); ### Remarks -See [IsWindowVisible](/windows/win32/api/winuser/nf-winuser-iswindowvisible) in the Windows SDK. +See [`IsWindowVisible`](/windows/win32/api/winuser/nf-winuser-iswindowvisible) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#22](../../atl/codesnippet/cpp/cwindow-class_22.cpp)] -## CWindow::IsWindowUnicode +## `CWindow::IsWindowUnicode` Determines whether the specified window is a native Unicode window. @@ -1551,13 +1550,13 @@ BOOL IsWindowUnicode() throw(); ### Remarks -See [IsWindowUnicode](/windows/win32/api/winuser/nf-winuser-iswindowunicode) in the Windows SDK. +See [`IsWindowUnicode`](/windows/win32/api/winuser/nf-winuser-iswindowunicode) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#23](../../atl/codesnippet/cpp/cwindow-class_23.cpp)] -## CWindow::IsZoomed +## `CWindow::IsZoomed` Determines whether the window is maximized. @@ -1567,9 +1566,9 @@ BOOL IsZoomed() const throw(); ### Remarks -See [IsZoomed](/windows/win32/api/winuser/nf-winuser-iszoomed) in the Windows SDK. +See [`IsZoomed`](/windows/win32/api/winuser/nf-winuser-iszoomed) in the Windows SDK. -## CWindow::KillTimer +## `CWindow::KillTimer` Destroys a timer event created by `CWindow::SetTimer`. @@ -1579,11 +1578,11 @@ BOOL KillTimer(UINT nIDEvent) throw(); ### Remarks -See [KillTimer](/windows/win32/api/winuser/nf-winuser-killtimer) in the Windows SDK. +See [`KillTimer`](/windows/win32/api/winuser/nf-winuser-killtimer) in the Windows SDK. -## CWindow::LockWindowUpdate +## `CWindow::LockWindowUpdate` -Disables or enables drawing in the window by calling the [LockWindowUpdate](/windows/win32/api/winuser/nf-winuser-lockwindowupdate) Win32 function. +Disables or enables drawing in the window by calling the [`LockWindowUpdate`](/windows/win32/api/winuser/nf-winuser-lockwindowupdate) Win32 function. ``` BOOL LockWindowUpdate(BOOL bLock = TRUE) throw(); @@ -1591,18 +1590,18 @@ BOOL LockWindowUpdate(BOOL bLock = TRUE) throw(); ### Parameters -*bLock*
-[in] If TRUE (the default value), the window will be locked. Otherwise, it will be unlocked. +*`bLock`*\ +[in] If `TRUE` (the default value), the window will be locked. Otherwise, it will be unlocked. ### Return Value -TRUE if the window is successfully locked; otherwise, FALSE. +`TRUE` if the window is successfully locked; otherwise, `FALSE`. ### Remarks -If *bLock* is TRUE, this method passes [m_hWnd](#m_hwnd) to the Win32 function; otherwise, it passes NULL. +If *`bLock`* is `TRUE`, this method passes [`m_hWnd`](#m_hwnd) to the Win32 function; otherwise, it passes `NULL`. -## CWindow::m_hWnd +## `CWindow::m_hWnd` Contains a handle to the window associated with the `CWindow` object. @@ -1610,7 +1609,7 @@ Contains a handle to the window associated with the `CWindow` object. HWND m_hWnd throw() throw(); ``` -## CWindow::MapWindowPoints +## `CWindow::MapWindowPoints` Converts a set of points from the window's coordinate space to the coordinate space of another window. @@ -1627,11 +1626,11 @@ int MapWindowPoints( ### Remarks -See [MapWindowPoints](/windows/win32/api/winuser/nf-winuser-mapwindowpoints) in the Windows SDK. +See [`MapWindowPoints`](/windows/win32/api/winuser/nf-winuser-mapwindowpoints) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::MessageBox +## `CWindow::MessageBox` Displays a message box. @@ -1644,13 +1643,13 @@ int MessageBox( ### Remarks -See [MessageBox](/windows/win32/api/winuser/nf-winuser-messagebox) in the Windows SDK. +See [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#24](../../atl/codesnippet/cpp/cwindow-class_24.cpp)] -## CWindow::ModifyStyle +## `CWindow::ModifyStyle` Modifies the window styles of the `CWindow` object. @@ -1663,40 +1662,40 @@ BOOL ModifyStyle( ### Parameters -*dwRemove*
+*`dwRemove`*\ [in] Specifies the window styles to be removed during style modification. -*dwAdd*
+*`dwAdd`*\ [in] Specifies the window styles to be added during style modification. -*nFlags*
-[in] Window-positioning flags. For a list of possible values, see the [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. +*`nFlags`*\ +[in] Window-positioning flags. For a list of possible values, see the [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. ### Return Value -TRUE if the window styles are modified; otherwise, FALSE. +`TRUE` if the window styles are modified; otherwise, `FALSE`. ### Remarks -Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDKfor information about the available window styles. +Styles to be added or removed can be combined by using the bitwise "or" (`|`) operator. See the [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDKfor information about the available window styles. -If *nFlags* is nonzero, `ModifyStyle` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: +If *`nFlags`* is nonzero, `ModifyStyle` calls the Win32 function `SetWindowPos`, and redraws the window by combining *`nFlags`* with the following four flags: -- SWP_NOSIZE Retains the current size. +- `SWP_NOSIZE` Retains the current size. -- SWP_NOMOVE Retains the current position. +- `SWP_NOMOVE` Retains the current position. -- SWP_NOZORDER Retains the current Z order. +- `SWP_NOZORDER` Retains the current Z order. -- SWP_NOACTIVATE Does not activate the window. +- `SWP_NOACTIVATE` Doesn't activate the window. -To modify a window's extended styles, call [ModifyStyleEx](#modifystyleex). +To modify a window's extended styles, call [`ModifyStyleEx`](#modifystyleex). ### Example [!code-cpp[NVC_ATL_Windowing#25](../../atl/codesnippet/cpp/cwindow-class_25.cpp)] -## CWindow::ModifyStyleEx +## `CWindow::ModifyStyleEx` Modifies the extended window styles of the `CWindow` object. @@ -1709,40 +1708,40 @@ BOOL ModifyStyleEx( ### Parameters -*dwRemove*
+*`dwRemove`*\ [in] Specifies the extended styles to be removed during style modification. -*dwAdd*
+*`dwAdd`*\ [in] Specifies the extended styles to be added during style modification. -*nFlags*
-[in] Window-positioning flags. For a list of possible values, see the [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. +*`nFlags`*\ +[in] Window-positioning flags. For a list of possible values, see the [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. ### Return Value -TRUE if the extended window styles are modified; otherwise, FALSE. +`TRUE` if the extended window styles are modified; otherwise, `FALSE`. ### Remarks -Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDKfor information about the available extended styles. +Styles to be added or removed can be combined by using the bitwise "or" (`|`) operator. See the [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDK for information about the available extended styles. -If *nFlags* is nonzero, `ModifyStyleEx` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: +If *`nFlags`* is nonzero, `ModifyStyleEx` calls the Win32 function `SetWindowPos`, and redraws the window by combining *`nFlags`* with the following four flags: -- SWP_NOSIZE Retains the current size. +- `SWP_NOSIZE` Retains the current size. -- SWP_NOMOVE Retains the current position. +- `SWP_NOMOVE` Retains the current position. -- SWP_NOZORDER Retains the current Z order. +- `SWP_NOZORDER` Retains the current Z order. -- SWP_NOACTIVATE Does not activate the window. +- `SWP_NOACTIVATE` Doesn't activate the window. -To modify windows using regular window styles, call [ModifyStyle](#modifystyle). +To modify windows using regular window styles, call [`ModifyStyle`](#modifystyle). ### Example [!code-cpp[NVC_ATL_Windowing#26](../../atl/codesnippet/cpp/cwindow-class_26.cpp)] -## CWindow::MoveWindow +## `CWindow::MoveWindow` Changes the window's size and position. @@ -1761,11 +1760,11 @@ BOOL MoveWindow( ### Remarks -For a top-level window object, the x and y parameters are relative to the upper-left corner of the screen. For a child window object, they are relative to the upper-left corner of the parent window's client area. +For a top-level window object, the `x` and `y` parameters are relative to the upper-left corner of the screen. For a child window object, they're relative to the upper-left corner of the parent window's client area. -The second version of this method uses a [RECT](/windows/win32/api/windef/ns-windef-rect) structure to determine the window's new position, width, and height. +The second version of this method uses a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure to determine the window's new position, width, and height. -## CWindow::NextDlgCtrl +## `CWindow::NextDlgCtrl` Sets the keyboard focus to the next control in the dialog box. @@ -1775,9 +1774,9 @@ void NextDlgCtrl() const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::OpenClipboard +## `CWindow::OpenClipboard` Opens the Clipboard. @@ -1787,25 +1786,25 @@ BOOL OpenClipboard() throw(); ### Remarks -See [OpenClipboard](/windows/win32/api/winuser/nf-winuser-openclipboard) in the Windows SDK. +See [`OpenClipboard`](/windows/win32/api/winuser/nf-winuser-openclipboard) in the Windows SDK. -## CWindow::operator HWND +## `CWindow::operator HWND` -Converts a `CWindow` object to an HWND. +Converts a `CWindow` object to an `HWND`. ``` operator HWND() const throw(); ``` -## CWindow::operator = +## `CWindow::operator =` -Assigns an HWND to the `CWindow` object by setting the [m_hWnd](#m_hwnd) member to `hWnd`. +Assigns an `HWND` to the `CWindow` object by setting the [`m_hWnd`](#m_hwnd) member to `hWnd`. ``` CWindow& operator= (HWND hWnd) throw(); ``` -## CWindow::PostMessage +## `CWindow::PostMessage` Places a message in the message queue associated with the thread that created the window. @@ -1818,7 +1817,7 @@ BOOL PostMessage( ### Remarks -See [PostMessage](/windows/win32/api/winuser/nf-winuser-postmessagew) in the Windows SDK. +See [`PostMessage`](/windows/win32/api/winuser/nf-winuser-postmessagew) in the Windows SDK. Returns without waiting for the thread to process the message. @@ -1826,7 +1825,7 @@ Returns without waiting for the thread to process the message. [!code-cpp[NVC_ATL_Windowing#27](../../atl/codesnippet/cpp/cwindow-class_27.cpp)] -## CWindow::PrevDlgCtrl +## `CWindow::PrevDlgCtrl` Sets the keyboard focus to the previous control in the dialog box. @@ -1836,11 +1835,11 @@ void PrevDlgCtrl() const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::Print +## `CWindow::Print` -Sends a [WM_PRINT](/windows/win32/gdi/wm-print) message to the window to request that it draw itself in the specified device context. +Sends a [`WM_PRINT`](/windows/win32/gdi/wm-print) message to the window to request that it draw itself in the specified device context. ```cpp void Print(HDC hDC, DWORD dwFlags) const throw(); @@ -1848,27 +1847,27 @@ void Print(HDC hDC, DWORD dwFlags) const throw(); ### Parameters -*hDC*
+*`hDC`*\ [in] The handle to a device context. -*dwFlags*
+*`dwFlags`*\ [in] Specifies the drawing options. You can combine one or more of the following flags: -- PRF_CHECKVISIBLE Draw the window only if it is visible. +- `PRF_CHECKVISIBLE` Draw the window only if it's visible. -- PRF_CHILDREN Draw all visible child windows. +- `PRF_CHILDREN` Draw all visible child windows. -- PRF_CLIENT Draw the client area of the window. +- `PRF_CLIENT` Draw the client area of the window. -- PRF_ERASEBKGND Erase the background before drawing the window. +- `PRF_ERASEBKGND` Erase the background before drawing the window. -- PRF_NONCLIENT Draw the non-client area of the window. +- `PRF_NONCLIENT` Draw the non-client area of the window. -- PRF_OWNED Draw all owned windows. +- `PRF_OWNED` Draw all owned windows. -## CWindow::PrintClient +## `CWindow::PrintClient` -Sends a [WM_PRINTCLIENT](/windows/win32/gdi/wm-printclient) message to the window to request that it draw its client area in the specified device context. +Sends a [`WM_PRINTCLIENT`](/windows/win32/gdi/wm-printclient) message to the window to request that it draw its client area in the specified device context. ```cpp void PrintClient(HDC hDC, DWORD dwFlags) const throw(); @@ -1876,25 +1875,25 @@ void PrintClient(HDC hDC, DWORD dwFlags) const throw(); ### Parameters -*hDC*
+*`hDC`*\ [in] The handle to a device context. -*dwFlags*
+*`dwFlags`*\ [in] Specifies drawing options. You can combine one or more of the following flags: -- PRF_CHECKVISIBLE Draw the window only if it is visible. +- `PRF_CHECKVISIBLE` Draw the window only if it's visible. -- PRF_CHILDREN Draw all visible child windows. +- `PRF_CHILDREN` Draw all visible child windows. -- PRF_CLIENT Draw the client area of the window. +- `PRF_CLIENT` Draw the client area of the window. -- PRF_ERASEBKGND Erase the background before drawing the window. +- `PRF_ERASEBKGND` Erase the background before drawing the window. -- PRF_NONCLIENT Draw the non-client area of the window. +- `PRF_NONCLIENT` Draw the non-client area of the window. -- PRF_OWNED Draw all owned windows. +- `PRF_OWNED` Draw all owned windows. -## CWindow::rcDefault +## `CWindow::rcDefault` Contains default window dimensions. @@ -1902,7 +1901,7 @@ Contains default window dimensions. static RECT rcDefault; ``` -## CWindow::RedrawWindow +## `CWindow::RedrawWindow` Updates a specified rectangle or region in the client area. @@ -1917,13 +1916,13 @@ throw() ### Remarks -See [RedrawWindow](/windows/win32/api/winuser/nf-winuser-redrawwindow) in the Windows SDK. +See [`RedrawWindow`](/windows/win32/api/winuser/nf-winuser-redrawwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#28](../../atl/codesnippet/cpp/cwindow-class_28.cpp)] -## CWindow::ReleaseDC +## `CWindow::ReleaseDC` Releases a device context. @@ -1933,13 +1932,13 @@ int ReleaseDC(HDC hDC); ### Remarks -See [ReleaseDC](/windows/win32/api/winuser/nf-winuser-releasedc) in the Windows SDK. +See [`ReleaseDC`](/windows/win32/api/winuser/nf-winuser-releasedc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#9](../../atl/codesnippet/cpp/cwindow-class_9.cpp)] -## CWindow::ResizeClient +## `CWindow::ResizeClient` Resizes the window to the specified client area size. @@ -1952,16 +1951,16 @@ BOOL ResizeClient( ### Parameters -*nWidth*
+*`nWidth`*\ New width of the window in pixels. -*nHeight*
+*`nHeight`*\ New height of the window in pixels. -*bRedraw*
-A flag indicating whether to redraw changes. Default is FALSE, indicating the window does not redraw changes. +*`bRedraw`*\ +A flag indicating whether to redraw changes. Default is `FALSE`, indicating the window doesn't redraw changes. -## CWindow::ScreenToClient +## `CWindow::ScreenToClient` Converts screen coordinates to client coordinates. @@ -1972,11 +1971,11 @@ BOOL ScreenToClient(LPRECT lpRect) const throw(); ### Remarks -See [ScreenToClient](/windows/win32/api/winuser/nf-winuser-screentoclient) in the Windows SDK. +See [`ScreenToClient`](/windows/win32/api/winuser/nf-winuser-screentoclient) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::ScrollWindow +## `CWindow::ScrollWindow` Scrolls the specified client area. @@ -1990,9 +1989,9 @@ BOOL ScrollWindow( ### Remarks -See [ScrollWindow](/windows/win32/api/winuser/nf-winuser-scrollwindow) in the Windows SDK. +See [`ScrollWindow`](/windows/win32/api/winuser/nf-winuser-scrollwindow) in the Windows SDK. -## CWindow::ScrollWindowEx +## `CWindow::ScrollWindowEx` Scrolls the specified client area with additional features. @@ -2009,9 +2008,9 @@ int ScrollWindowEx( ### Remarks -See [ScrollWindowEx](/windows/win32/api/winuser/nf-winuser-scrollwindowex) in the Windows SDK. +See [`ScrollWindowEx`](/windows/win32/api/winuser/nf-winuser-scrollwindowex) in the Windows SDK. -## CWindow::SendDlgItemMessage +## `CWindow::SendDlgItemMessage` Sends a message to a control. @@ -2025,11 +2024,11 @@ LRESULT SendDlgItemMessage( ### Remarks -See [SendDlgItemMessage](/windows/win32/api/winuser/nf-winuser-senddlgitemmessagew) in the Windows SDK. +See [`SendDlgItemMessage`](/windows/win32/api/winuser/nf-winuser-senddlgitemmessagew) in the Windows SDK. -## CWindow::SendMessage +## `CWindow::SendMessage` -Sends a message to the window and does not return until the window procedure has processed the message. +Sends a message to the window and doesn't return until the window procedure has processed the message. ``` LRESULT SendMessage( @@ -2046,13 +2045,13 @@ static LRESULT SendMessage( ### Remarks -See [SendMessage](/windows/win32/api/winuser/nf-winuser-sendmessage) in the Windows SDK. +See [`SendMessage`](/windows/win32/api/winuser/nf-winuser-sendmessage) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#29](../../atl/codesnippet/cpp/cwindow-class_29.cpp)] -## CWindow::SendMessageToDescendants +## `CWindow::SendMessageToDescendants` Sends the specified message to all immediate children of the `CWindow` object. @@ -2066,23 +2065,23 @@ void SendMessageToDescendants( ### Parameters -*message*
+*`message`*\ [in] The message to be sent. -*wParam*
+*`wParam`*\ [in] Additional message-specific information. -*lParam*
+*`lParam`*\ [in] Additional message-specific information. -*bDeep*
-[in] If TRUE (the default value), the message will be sent to all descendant windows; otherwise, it will be sent only to the immediate child windows. +*`bDeep`*\ +[in] If `TRUE` (the default value), the message will be sent to all descendant windows; otherwise, it will be sent only to the immediate child windows. ### Remarks -If *bDeep* is TRUE, the message is additionally sent to all other descendant windows. +If *`bDeep`* is `TRUE`, the message is additionally sent to all other descendant windows. -## CWindow::SendNotifyMessage +## `CWindow::SendNotifyMessage` Sends a message to the window. @@ -2095,11 +2094,11 @@ BOOL SendNotifyMessage( ### Remarks -See [SendNotifyMessage](/windows/win32/api/winuser/nf-winuser-sendnotifymessagew) in the Windows SDK. +See [`SendNotifyMessage`](/windows/win32/api/winuser/nf-winuser-sendnotifymessagew) in the Windows SDK. -If the window was created by the calling thread, `SendNotifyMessage` does not return until the window procedure has processed the message. Otherwise, it returns immediately. +If the window was created by the calling thread, `SendNotifyMessage` doesn't return until the window procedure has processed the message. Otherwise, it returns immediately. -## CWindow::SetActiveWindow +## `CWindow::SetActiveWindow` Activates the window. @@ -2109,13 +2108,13 @@ HWND SetActiveWindow() throw(); ### Remarks -See [SetActiveWindow](/windows/win32/api/winuser/nf-winuser-setactivewindow) in the Windows SDK. +See [`SetActiveWindow`](/windows/win32/api/winuser/nf-winuser-setactivewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#30](../../atl/codesnippet/cpp/cwindow-class_30.cpp)] -## CWindow::SetCapture +## `CWindow::SetCapture` Sends all subsequent mouse input to the window. @@ -2125,9 +2124,9 @@ HWND SetCapture() throw(); ### Remarks -See [SetCapture](/windows/win32/api/winuser/nf-winuser-setcapture) in the Windows SDK. +See [`SetCapture`](/windows/win32/api/winuser/nf-winuser-setcapture) in the Windows SDK. -## CWindow::SetClipboardViewer +## `CWindow::SetClipboardViewer` Adds the window to the Clipboard viewer chain. @@ -2137,9 +2136,9 @@ HWND SetClipboardViewer() throw(); ### Remarks -See [SetClipboardViewer](/windows/win32/api/winuser/nf-winuser-setclipboardviewer) in the Windows SDK. +See [`SetClipboardViewer`](/windows/win32/api/winuser/nf-winuser-setclipboardviewer) in the Windows SDK. -## CWindow::SetDlgCtrlID +## `CWindow::SetDlgCtrlID` Sets the identifier of the window to the specified value. @@ -2149,14 +2148,14 @@ int SetDlgCtrlID(int nID) throw(); ### Parameters -*nID*
+*`nID`*\ [in] The new value to set for the window's identifier. ### Return Value If successful, the previous identifier of the window; otherwise 0. -## CWindow::SetDlgItemInt +## `CWindow::SetDlgItemInt` Changes a control's text to the string representation of an integer value. @@ -2169,9 +2168,9 @@ BOOL SetDlgItemInt( ### Remarks -See [SetDlgItemInt](/windows/win32/api/winuser/nf-winuser-setdlgitemint) in the Windows SDK. +See [`SetDlgItemInt`](/windows/win32/api/winuser/nf-winuser-setdlgitemint) in the Windows SDK. -## CWindow::SetDlgItemText +## `CWindow::SetDlgItemText` Changes a control's text. @@ -2181,9 +2180,9 @@ BOOL SetDlgItemText(int nID, LPCTSTR lpszString) throw(); ### Remarks -See [SetDlgItemText](/windows/win32/api/winuser/nf-winuser-setdlgitemtextw) in the Windows SDK. +See [`SetDlgItemText`](/windows/win32/api/winuser/nf-winuser-setdlgitemtextw) in the Windows SDK. -## CWindow::SetFocus +## `CWindow::SetFocus` Sets the input focus to the window. @@ -2193,15 +2192,15 @@ HWND SetFocus() throw(); ### Remarks -See [SetFocus](/windows/win32/api/winuser/nf-winuser-setfocus) in the Windows SDK. +See [`SetFocus`](/windows/win32/api/winuser/nf-winuser-setfocus) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#31](../../atl/codesnippet/cpp/cwindow-class_31.cpp)] -## CWindow::SetFont +## `CWindow::SetFont` -Changes the window's current font by sending a [WM_SETFONT](/windows/win32/winmsg/wm-setfont) message to the window. +Changes the window's current font by sending a [`WM_SETFONT`](/windows/win32/winmsg/wm-setfont) message to the window. ```cpp void SetFont(HFONT hFont, BOOL bRedraw = TRUE) throw(); @@ -2209,15 +2208,15 @@ void SetFont(HFONT hFont, BOOL bRedraw = TRUE) throw(); ### Parameters -*hFont*
+*`hFont`*\ [in] The handle to the new font. -*bRedraw*
-[in] If TRUE (the default value), the window is redrawn. Otherwise, it is not. +*`bRedraw`*\ +[in] If `TRUE` (the default value), the window is redrawn. Otherwise, it isn't. -## CWindow::SetHotKey +## `CWindow::SetHotKey` -Associates a hot key with the window by sending a WM_SETHOTKEY message. +Associates a hot key with the window by sending a `WM_SETHOTKEY` message. ``` int SetHotKey(WORD wVirtualKeyCode, WORD wModifiers) throw(); @@ -2225,19 +2224,19 @@ int SetHotKey(WORD wVirtualKeyCode, WORD wModifiers) throw(); ### Parameters -*wVirtualKeyCode*
-[in] The virtual key code of the hot key. For a list of standard virtual key codes, see Winuser.h. +*`wVirtualKeyCode`*\ +[in] The virtual key code of the hot key. For a list of standard virtual key codes, see `Winuser.h`. -*wModifiers*
-[in] The modifiers of the hot key. For a list of possible values, see WM_SETHOTKEY in the Windows SDK. +*`wModifiers`*\ +[in] The modifiers of the hot key. For a list of possible values, see `WM_SETHOTKEY` in the Windows SDK. ### Return Value -For a list of possible return values, see [WM_SETHOTKEY](/windows/win32/inputdev/wm-sethotkey) in the Windows SDK. +For a list of possible return values, see [`WM_SETHOTKEY`](/windows/win32/inputdev/wm-sethotkey) in the Windows SDK. -## CWindow::SetIcon +## `CWindow::SetIcon` -Sets the window's large or small icon to the icon identified by *hIcon*. +Sets the window's large or small icon to the icon identified by *`hIcon`*. ``` HICON SetIcon(HICON hIcon, BOOL bBigIcon = TRUE) throw(); @@ -2245,11 +2244,11 @@ HICON SetIcon(HICON hIcon, BOOL bBigIcon = TRUE) throw(); ### Parameters -*hIcon*
+*`hIcon`*\ [in] The handle to a new icon. -*bBigIcon*
-[in] If TRUE (the default value), the method sets a large icon. Otherwise, it sets a small icon. +*`bBigIcon`*\ +[in] If `TRUE` (the default value), the method sets a large icon. Otherwise, it sets a small icon. ### Return Value @@ -2257,9 +2256,9 @@ The handle to the previous icon. ### Remarks -`SetIcon` sends a [WM_SETICON](/windows/win32/winmsg/wm-seticon) message to the window. +`SetIcon` sends a [`WM_SETICON`](/windows/win32/winmsg/wm-seticon) message to the window. -## CWindow::SetMenu +## `CWindow::SetMenu` Changes the window's current menu. @@ -2269,9 +2268,9 @@ BOOL SetMenu(HMENU hMenu) throw(); ### Remarks -See [SetMenu](/windows/win32/api/winuser/nf-winuser-setmenu) in the Windows SDK. +See [`SetMenu`](/windows/win32/api/winuser/nf-winuser-setmenu) in the Windows SDK. -## CWindow::SetParent +## `CWindow::SetParent` Changes the parent window. @@ -2281,15 +2280,15 @@ HWND SetParent(HWND hWndNewParent) throw(); ### Remarks -See [SetParent](/windows/win32/api/winuser/nf-winuser-setparent) in the Windows SDK. +See [`SetParent`](/windows/win32/api/winuser/nf-winuser-setparent) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#32](../../atl/codesnippet/cpp/cwindow-class_32.cpp)] -## CWindow::SetRedraw +## `CWindow::SetRedraw` -Sets or clears the redraw flag by sending a [WM_SETREDRAW](/windows/win32/gdi/wm-setredraw) message to the window. +Sets or clears the redraw flag by sending a [`WM_SETREDRAW`](/windows/win32/gdi/wm-setredraw) message to the window. ```cpp void SetRedraw(BOOL bRedraw = TRUE) throw(); @@ -2297,8 +2296,8 @@ void SetRedraw(BOOL bRedraw = TRUE) throw(); ### Parameters -*bRedraw*
-[in] Specifies the state of the redraw flag. If TRUE (the default value), the redraw flag is set; if FALSE, the flag is cleared. +*`bRedraw`*\ +[in] Specifies the state of the redraw flag. If `TRUE` (the default value), the redraw flag is set; if `FALSE`, the flag is cleared. ### Remarks @@ -2308,7 +2307,7 @@ Call `SetRedraw` to allow changes to be redrawn or to prevent changes from being [!code-cpp[NVC_ATL_Windowing#33](../../atl/codesnippet/cpp/cwindow-class_33.cpp)] -## CWindow::SetScrollInfo +## `CWindow::SetScrollInfo` Sets the parameters of a scroll bar. @@ -2321,9 +2320,9 @@ int SetScrollInfo( ### Remarks -See [SetScrollInfo](/windows/win32/api/winuser/nf-winuser-setscrollinfo) in the Windows SDK. +See [`SetScrollInfo`](/windows/win32/api/winuser/nf-winuser-setscrollinfo) in the Windows SDK. -## CWindow::SetScrollPos +## `CWindow::SetScrollPos` Changes the position of the scroll box. @@ -2336,9 +2335,9 @@ int SetScrollPos( ### Remarks -See [SetScrollPos](/windows/win32/api/winuser/nf-winuser-setscrollpos) in the Windows SDK. +See [`SetScrollPos`](/windows/win32/api/winuser/nf-winuser-setscrollpos) in the Windows SDK. -## CWindow::SetScrollRange +## `CWindow::SetScrollRange` Changes the scroll bar range. @@ -2352,9 +2351,9 @@ BOOL SetScrollRange( ### Remarks -See [SetScrollRange](/windows/win32/api/winuser/nf-winuser-setscrollrange) in the Windows SDK. +See [`SetScrollRange`](/windows/win32/api/winuser/nf-winuser-setscrollrange) in the Windows SDK. -## CWindow::SetTimer +## `CWindow::SetTimer` Creates a timer event. @@ -2367,9 +2366,9 @@ UINT SetTimer( ### Remarks -See [SetTimer](/windows/win32/api/winuser/nf-winuser-settimer) in the Windows SDK. +See [`SetTimer`](/windows/win32/api/winuser/nf-winuser-settimer) in the Windows SDK. -## CWindow::SetWindowContextHelpId +## `CWindow::SetWindowContextHelpId` Sets the window's help context identifier. @@ -2379,9 +2378,9 @@ BOOL SetWindowContextHelpId(DWORD dwContextHelpId) throw(); ### Remarks -See [SetWindowContextHelpId](/windows/win32/api/winuser/nf-winuser-setwindowcontexthelpid) in the Windows SDK. +See [`SetWindowContextHelpId`](/windows/win32/api/winuser/nf-winuser-setwindowcontexthelpid) in the Windows SDK. -## CWindow::SetWindowLong +## `CWindow::SetWindowLong` Sets a 32-bit value at a specified offset into the extra window memory. @@ -2391,12 +2390,12 @@ LONG SetWindowLong(int nIndex, LONG dwNewLong) throw(); ### Remarks -See [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. +See [`SetWindowLong`](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. > [!NOTE] -> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [CWindow::SetWindowLongPtr](#setwindowlongptr). +> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [`CWindow::SetWindowLongPtr`](#setwindowlongptr). -## CWindow::SetWindowLongPtr +## `CWindow::SetWindowLongPtr` Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory. @@ -2406,11 +2405,11 @@ LONG_PTR SetWindowLongPtr(int nIndex, LONG_PTR dwNewLong) throw(); ### Remarks -See [SetWindowLongPtr](/windows/win32/api/winuser/nf-winuser-setwindowlongptrw) in the Windows SDK. +See [`SetWindowLongPtr`](/windows/win32/api/winuser/nf-winuser-setwindowlongptrw) in the Windows SDK. This function supersedes the `CWindow::SetWindowLong` method. To write code that is compatible with both 32-bit and 64-bit versions of Windows, use `CWindow::SetWindowLongPtr`. -## CWindow::SetWindowPlacement +## `CWindow::SetWindowPlacement` Sets the show state and positions. @@ -2420,9 +2419,9 @@ BOOL SetWindowPlacement(const WINDOWPLACEMENT FAR* lpwndpl); ### Remarks -See [SetWindowPlacement](/windows/win32/api/winuser/nf-winuser-setwindowplacement) in the Windows SDK. +See [`SetWindowPlacement`](/windows/win32/api/winuser/nf-winuser-setwindowplacement) in the Windows SDK. -## CWindow::SetWindowPos +## `CWindow::SetWindowPos` Sets the size, position, and Z order. @@ -2443,11 +2442,11 @@ BOOL SetWindowPos( ### Remarks -See [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) in the Windows SDK. +See [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) in the Windows SDK. -The second version of this method uses a [RECT](/windows/win32/api/windef/ns-windef-rect) structure to set the window's new position, width, and height. +The second version of this method uses a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure to set the window's new position, width, and height. -## CWindow::SetWindowRgn +## `CWindow::SetWindowRgn` Sets the window region of a window. @@ -2457,9 +2456,9 @@ int SetWindowRgn(HRGN hRgn, BOOL bRedraw = FALSE) throw(); ### Remarks -See [SetWindowRgn](/windows/win32/api/winuser/nf-winuser-setwindowrgn) in the Windows SDK. +See [`SetWindowRgn`](/windows/win32/api/winuser/nf-winuser-setwindowrgn) in the Windows SDK. -## CWindow::SetWindowText +## `CWindow::SetWindowText` Changes the window's text. @@ -2469,13 +2468,13 @@ BOOL SetWindowText(LPCTSTR lpszString) throw(); ### Remarks -See [SetWindowText](/windows/win32/api/winuser/nf-winuser-setwindowtextw) in the Windows SDK. +See [`SetWindowText`](/windows/win32/api/winuser/nf-winuser-setwindowtextw) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#34](../../atl/codesnippet/cpp/cwindow-class_34.cpp)] -## CWindow::SetWindowWord +## `CWindow::SetWindowWord` Sets a 16-bit value at a specified offset into the extra window memory. @@ -2485,9 +2484,9 @@ WORD SetWindowWord(int nIndex, WORD wNewWord) throw(); ### Remarks -See [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. +See [`SetWindowLong`](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. -## CWindow::ShowCaret +## `CWindow::ShowCaret` Displays the system caret. @@ -2497,13 +2496,13 @@ BOOL ShowCaret() throw(); ### Remarks -See [ShowCaret](/windows/win32/api/winuser/nf-winuser-showcaret) in the Windows SDK. +See [`ShowCaret`](/windows/win32/api/winuser/nf-winuser-showcaret) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#35](../../atl/codesnippet/cpp/cwindow-class_35.cpp)] -## CWindow::ShowOwnedPopups +## `CWindow::ShowOwnedPopups` Shows or hides the pop-up windows owned by the window. @@ -2513,9 +2512,9 @@ BOOL ShowOwnedPopups(BOOL bShow = TRUE) throw(); ### Remarks -See [ShowOwnedPopups](/windows/win32/api/winuser/nf-winuser-showownedpopups) in the Windows SDK. +See [`ShowOwnedPopups`](/windows/win32/api/winuser/nf-winuser-showownedpopups) in the Windows SDK. -## CWindow::ShowScrollBar +## `CWindow::ShowScrollBar` Shows or hides a scroll bar. @@ -2525,9 +2524,9 @@ BOOL ShowScrollBar(UINT nBar, BOOL bShow = TRUE) throw(); ### Remarks -See [ShowScrollBar](/windows/win32/api/winuser/nf-winuser-showscrollbar) in the Windows SDK. +See [`ShowScrollBar`](/windows/win32/api/winuser/nf-winuser-showscrollbar) in the Windows SDK. -## CWindow::ShowWindow +## `CWindow::ShowWindow` Sets the window's show state. @@ -2537,13 +2536,13 @@ BOOL ShowWindow(int nCmdShow) throw(); ### Remarks -See [ShowWindow](/windows/win32/api/winuser/nf-winuser-showwindow) in the Windows SDK. +See [`ShowWindow`](/windows/win32/api/winuser/nf-winuser-showwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#36](../../atl/codesnippet/cpp/cwindow-class_36.cpp)] -## CWindow::ShowWindowAsync +## `CWindow::ShowWindowAsync` Sets the show state of a window created by a different thread. @@ -2553,9 +2552,9 @@ BOOL ShowWindowAsync(int nCmdShow) throw(); ### Remarks -See [ShowWindowAsync](/windows/win32/api/winuser/nf-winuser-showwindowasync) in the Windows SDK. +See [`ShowWindowAsync`](/windows/win32/api/winuser/nf-winuser-showwindowasync) in the Windows SDK. -## CWindow::UpdateWindow +## `CWindow::UpdateWindow` Updates the client area. @@ -2565,13 +2564,13 @@ BOOL UpdateWindow() throw(); ### Remarks -See [UpdateWindow](/windows/win32/api/winuser/nf-winuser-updatewindow) in the Windows SDK. +See [`UpdateWindow`](/windows/win32/api/winuser/nf-winuser-updatewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#37](../../atl/codesnippet/cpp/cwindow-class_37.cpp)] -## CWindow::ValidateRect +## `CWindow::ValidateRect` Validates the client area within the specified rectangle. @@ -2581,9 +2580,9 @@ BOOL ValidateRect(LPCRECT lpRect) throw(); ### Remarks -See [ValidateRect](/windows/win32/api/winuser/nf-winuser-validaterect) in the Windows SDK. +See [`ValidateRect`](/windows/win32/api/winuser/nf-winuser-validaterect) in the Windows SDK. -## CWindow::ValidateRgn +## `CWindow::ValidateRgn` Validates the client area within the specified region. @@ -2593,9 +2592,9 @@ BOOL ValidateRgn(HRGN hRgn) throw(); ### Remarks -See [ValidateRgn](/windows/win32/api/winuser/nf-winuser-validatergn) in the Windows SDK. +See [`ValidateRgn`](/windows/win32/api/winuser/nf-winuser-validatergn) in the Windows SDK. -## CWindow::WinHelp +## `CWindow::WinHelp` Starts Windows Help. @@ -2608,7 +2607,7 @@ BOOL WinHelp( ### Remarks -See [WinHelp](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. +See [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. ## See also diff --git a/docs/atl/reference/cwindowimpl-class.md b/docs/atl/reference/cwindowimpl-class.md index 79957ded9b..d2041bc669 100644 --- a/docs/atl/reference/cwindowimpl-class.md +++ b/docs/atl/reference/cwindowimpl-class.md @@ -276,7 +276,7 @@ virtual void OnFinalMessage(HWND hWnd); ### Remarks -The default implementation of `OnFinalMessage` does nothing, but you can override this function to handle cleanup before destroying a window. If you want to automatically delete your object upon the window destruction, you can call **delete this;** in this function. +The default implementation of `OnFinalMessage` does nothing, but you can override this function to handle cleanup before destroying a window. If you want to automatically delete your object upon the window destruction, you can call `delete this;` in this function. ## CWindowImpl::SubclassWindow diff --git a/docs/atl/reference/debugging-and-error-reporting-macros.md b/docs/atl/reference/debugging-and-error-reporting-macros.md index 59543bc784..463ef4c007 100644 --- a/docs/atl/reference/debugging-and-error-reporting-macros.md +++ b/docs/atl/reference/debugging-and-error-reporting-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Debugging and Error Reporting Macros" title: "Debugging and Error Reporting Macros" ms.date: "05/06/2019" -f1_keywords: ["atldef/ATL::_ATL_DEBUG_INTERFACES", "atldef/ATL::_ATL_DEBUG_QI", "atldef/ATL::ATLASSERT", "afx/ATL::ATLENSURE", "atltrace/ATL::ATLTRACENOTIMPL", "atltrace/ATL::ATLTRACE"] +f1_keywords: ["atldef/ATL::_ATL_DEBUG_INTERFACES", "atldef/ATL::_ATL_DEBUG_QI", "atldef/ATL::ATLASSERT", "afx/ATL::ATLENSURE", "atltrace/ATL::ATLTRACENOTIMPL", "atltrace/ATL::ATLTRACE", "ATLDEF/_ATL_DEBUG_INTERFACES", "ATLDEF/_ATL_DEBUG_QI", "ATLDEF/ATLASSERT", "AFX/ATLENSURE", "ATLTRACE/ATLTRACENOTIMPL", "ATLTRACE/ATLTRACE", "ATLDEF/ATLSTATIC_ASSERT"] helpviewer_keywords: ["macros, error reporting"] ms.assetid: 4da9b87f-ec5c-4a32-ab93-637780909b9d --- diff --git a/docs/atl/reference/exception-handling-macros.md b/docs/atl/reference/exception-handling-macros.md index b68a348f62..44f9993452 100644 --- a/docs/atl/reference/exception-handling-macros.md +++ b/docs/atl/reference/exception-handling-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Exception Handling Macros" title: "Exception Handling Macros" ms.date: "11/04/2016" -f1_keywords: ["atldef/ATL::_ATLCATCH", "atldef/ATL::_ATLCATCHALL", "atldef/ATL::_ATLTRY"] +f1_keywords: ["atldef/ATL::_ATLCATCH", "atldef/ATL::_ATLCATCHALL", "atldef/ATL::_ATLTRY", "ATLDEF/_ATLCATCH", "ATLDEF/_ATLCATCHALL", "ATLDEF/_ATLTRY"] helpviewer_keywords: ["exception handling, macros", "C++ exception handling, macros"] ms.assetid: a8385d34-3fb0-4006-a42a-de045cacf0f4 --- diff --git a/docs/atl/reference/idispeventimpl-class.md b/docs/atl/reference/idispeventimpl-class.md index 74fd3e72c2..ef54c3c7b5 100644 --- a/docs/atl/reference/idispeventimpl-class.md +++ b/docs/atl/reference/idispeventimpl-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: IDispEventImpl Class" title: "IDispEventImpl Class" -ms.date: "11/04/2016" +description: "Learn more about: IDispEventImpl Class" +ms.date: 11/04/2016 f1_keywords: ["IDispEventImpl", "ATLCOM/ATL::IDispEventImpl", "ATLCOM/ATL::IDispEventImpl::IDispEventImpl", "ATLCOM/ATL::IDispEventImpl::GetFuncInfoFromId", "ATLCOM/ATL::IDispEventImpl::GetIDsOfNames", "ATLCOM/ATL::IDispEventImpl::GetTypeInfo", "ATLCOM/ATL::IDispEventImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispEventImpl::GetUserDefinedType"] helpviewer_keywords: ["IDispEventImpl class"] -ms.assetid: a64b5288-35cb-4638-aad6-2d15b1c7cf7b --- -# IDispEventImpl Class +# `IDispEventImpl` Class This class provides implementations of the `IDispatch` methods. @@ -15,7 +14,7 @@ This class provides implementations of the `IDispatch` methods. ## Syntax -``` +```cpp template #### Parameters -*nID*
+*`nID`*\ A unique identifier for the source object. When `IDispEventImpl` is the base class for a composite control, use the resource ID of the desired contained control for this parameter. In other cases, use an arbitrary positive integer. -*T*
+*`T`*\ The user's class, which is derived from `IDispEventImpl`. -*pdiid*
-The pointer to the IID of the event dispinterface implemented by this class. This interface must be defined in the type library denoted by *plibid*, *wMajor*, and *wMinor*. +*`pdiid`*\ +The pointer to the IID of the event dispinterface implemented by this class. This interface must be defined in the type library denoted by *`plibid`*, *`wMajor`*, and *`wMinor`*. -*plibid*
-A pointer to the type library that defines the dispatch interface pointed to by *pdiid*. If **&GUID_NULL**, the type library will be loaded from the object sourcing the events. +*`plibid`*\ +A pointer to the type library that defines the dispatch interface pointed to by *`pdiid`*. If **`&GUID_NULL`**, the type library will be loaded from the object sourcing the events. -*wMajor*
+*`wMajor`*\ The major version of the type library. The default value is 0. -*wMinor*
+*`wMinor`*\ The minor version of the type library. The default value is 0. -*tihclass*
-The class used to manage the type information for *T*. The default value is a class of type `CComTypeInfoHolder`; however, you can override this template parameter by providing a class of a type other than `CComTypeInfoHolder`. +*`tihclass`*\ +The class used to manage the type information for *`T`*. The default value is a class of type `CComTypeInfoHolder`; however, you can override this template parameter by providing a class of a type other than `CComTypeInfoHolder`. ## Members @@ -54,23 +53,23 @@ The class used to manage the type information for *T*. The default value is a cl |Name|Description| |----------|-----------------| -|[IDispEventImpl::_tihclass](../../atl/reference/idispeventimpl-class.md)|The class used to manage the type information. By default, `CComTypeInfoHolder`.| +|[`IDispEventImpl::_tihclass`](#_tihclass)|The class used to manage the type information. By default, `CComTypeInfoHolder`.| ### Public Constructors |Name|Description| |----------|-----------------| -|[IDispEventImpl::IDispEventImpl](#idispeventimpl)|The constructor.| +|[`IDispEventImpl::IDispEventImpl`](#idispeventimpl)|The constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[IDispEventImpl::GetFuncInfoFromId](#getfuncinfofromid)|Locates the function index for the specified dispatch identifier.| -|[IDispEventImpl::GetIDsOfNames](#getidsofnames)|Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.| -|[IDispEventImpl::GetTypeInfo](#gettypeinfo)|Retrieves the type information for an object.| -|[IDispEventImpl::GetTypeInfoCount](#gettypeinfocount)|Retrieves the number of type information interfaces.| -|[IDispEventImpl::GetUserDefinedType](#getuserdefinedtype)|Retrieves the basic type of a user-defined type.| +|[`IDispEventImpl::GetFuncInfoFromId`](#getfuncinfofromid)|Locates the function index for the specified dispatch identifier.| +|[`IDispEventImpl::GetIDsOfNames`](#getidsofnames)|Maps a single member and an optional set of argument names to a corresponding set of integer `DISPID`s.| +|[`IDispEventImpl::GetTypeInfo`](#gettypeinfo)|Retrieves the type information for an object.| +|[`IDispEventImpl::GetTypeInfoCount`](#gettypeinfocount)|Retrieves the number of type information interfaces.| +|[`IDispEventImpl::GetUserDefinedType`](#getuserdefinedtype)|Retrieves the basic type of a user-defined type.| ## Remarks @@ -78,18 +77,18 @@ The class used to manage the type information for *T*. The default value is a cl `IDispEventImpl` works in conjunction with the event sink map in your class to route events to the appropriate handler function. To use this class: -Add a [SINK_ENTRY](composite-control-macros.md#sink_entry) or [SINK_ENTRY_EX](composite-control-macros.md#sink_entry_ex) macro to the event sink map for each event on each object that you want to handle. When using `IDispEventImpl` as a base class of a composite control, you can call [AtlAdviseSinkMap](connection-point-global-functions.md#atladvisesinkmap) to establish and break the connection with the event sources for all entries in the event sink map. In other cases, or for greater control, call [DispEventAdvise](idispeventsimpleimpl-class.md#dispeventadvise) to establish the connection between the source object and the base class. Call [DispEventUnadvise](idispeventsimpleimpl-class.md#dispeventunadvise) to break the connection. +Add a [`SINK_ENTRY`](composite-control-macros.md#sink_entry) or [`SINK_ENTRY_EX`](composite-control-macros.md#sink_entry_ex) macro to the event sink map for each event on each object that you want to handle. When using `IDispEventImpl` as a base class of a composite control, you can call [`AtlAdviseSinkMap`](connection-point-global-functions.md#atladvisesinkmap) to establish and break the connection with the event sources for all entries in the event sink map. In other cases, or for greater control, call [`DispEventAdvise`](idispeventsimpleimpl-class.md#dispeventadvise) to establish the connection between the source object and the base class. Call [`DispEventUnadvise`](idispeventsimpleimpl-class.md#dispeventunadvise) to break the connection. -You must derive from `IDispEventImpl` (using a unique value for *nID*) for each object for which you need to handle events. You can reuse the base class by unadvising against one source object then advising against a different source object, but the maximum number of source objects that can be handled by a single object at one time is limited by the number of `IDispEventImpl` base classes. +You must derive from `IDispEventImpl` (using a unique value for *`nID`*) for each object for which you need to handle events. You can reuse the base class by unadvising against one source object then advising against a different source object, but the maximum number of source objects that can be handled by a single object at one time is limited by the number of `IDispEventImpl` base classes. -`IDispEventImpl` provides the same functionality as [IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md), except it gets type information about the interface from a type library rather than having it supplied as a pointer to an [_ATL_FUNC_INFO](../../atl/reference/atl-func-info-structure.md) structure. Use `IDispEventSimpleImpl` when you do not have a type library describing the event interface or want to avoid the overhead associated with using the type library. +`IDispEventImpl` provides the same functionality as [`IDispEventSimpleImpl`](idispeventsimpleimpl-class.md), except it gets type information about the interface from a type library rather than having it supplied as a pointer to an [`_ATL_FUNC_INFO`](atl-func-info-structure.md) structure. Use `IDispEventSimpleImpl` when you do not have a type library describing the event interface or want to avoid the overhead associated with using the type library. > [!NOTE] > `IDispEventImpl` and `IDispEventSimpleImpl` provide their own implementation of `IUnknown::QueryInterface` enabling each `IDispEventImpl` and `IDispEventSimpleImpl` base class to act as a separate COM identity while still allowing direct access to class members in your main COM object. -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type `HRESULT` or `void` from your event handler methods; any other return value is unsupported and its behavior is undefined. -For more information, see [Supporting IDispEventImpl](../../atl/supporting-idispeventimpl.md). +For more information, see [Supporting `IDispEventImpl`](../supporting-idispeventimpl.md). ## Inheritance Hierarchy @@ -97,19 +96,19 @@ For more information, see [Supporting IDispEventImpl](../../atl/supporting-idisp `_IDispEventLocator` -[IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md) +[`IDispEventSimpleImpl`](idispeventsimpleimpl-class.md) `IDispEventImpl` ## Requirements -**Header:** atlcom.h +**Header:** `atlcom.h` -## IDispEventImpl::GetFuncInfoFromId +## `IDispEventImpl::GetFuncInfoFromId` Locates the function index for the specified dispatch identifier. -``` +```cpp HRESULT GetFuncInfoFromId( const IID& iid, DISPID dispidMember, @@ -119,27 +118,27 @@ HRESULT GetFuncInfoFromId( ### Parameters -*iid*
+*`iid`*\ [in] A reference to the ID of the function. -*dispidMember*
+*`dispidMember`*\ [in] The dispatch ID of the function. -*lcid*
+*`lcid`*\ [in] The locale context of the function ID. -*info*
+*`info`*\ [in] The structure indicating how the function is called. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. -## IDispEventImpl::GetIDsOfNames +## `IDispEventImpl::GetIDsOfNames` -Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to [IDispatch::Invoke](/windows/win32/api/oaidl/nf-oaidl-idispatch-invoke). +Maps a single member and an optional set of argument names to a corresponding set of integer `DISPID`s, which can be used on subsequent calls to [`IDispatch::Invoke`](/windows/win32/api/oaidl/nf-oaidl-idispatch-invoke). -``` +```cpp STDMETHOD(GetIDsOfNames)( REFIID riid, LPOLESTR* rgszNames, @@ -150,38 +149,36 @@ STDMETHOD(GetIDsOfNames)( ### Remarks -See [IDispatch::GetIDsOfNames](/windows/win32/api/oaidl/nf-oaidl-idispatch-getidsofnames) in the Windows SDK. +See [`IDispatch::GetIDsOfNames`](/windows/win32/api/oaidl/nf-oaidl-idispatch-getidsofnames) in the Windows SDK. -## IDispEventImpl::GetTypeInfo +## `IDispEventImpl::GetTypeInfo` Retrieves the type information for an object, which can then be used to get the type information for an interface. -``` +```cpp STDMETHOD(GetTypeInfo)( UINT itinfo, LCID lcid, ITypeInfo** pptinfo); ``` -### Remarks - -## IDispEventImpl::GetTypeInfoCount +## `IDispEventImpl::GetTypeInfoCount` Retrieves the number of type information interfaces that an object provides (either 0 or 1). -``` +```cpp STDMETHOD(GetTypeInfoCount)(UINT* pctinfo); ``` ### Remarks -See [IDispatch::GetTypeInfoCount](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount) in the Windows SDK. +See [`IDispatch::GetTypeInfoCount`](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount) in the Windows SDK. -## IDispEventImpl::GetUserDefinedType +## `IDispEventImpl::GetUserDefinedType` Retrieves the basic type of a user-defined type. -``` +```cpp VARTYPE GetUserDefinedType( ITypeInfo* pTI, HREFTYPE hrt); @@ -189,10 +186,10 @@ VARTYPE GetUserDefinedType( ### Parameters -*pTI*
-[in] A pointer to the [ITypeInfo](/windows/win32/api/oaidl/nn-oaidl-itypeinfo) interface containing the user-defined type. +*`pTI`*\ +[in] A pointer to the [`ITypeInfo`](/windows/win32/api/oaidl/nn-oaidl-itypeinfo) interface containing the user-defined type. -*hrt*
+*`hrt`*\ [in] A handle to the type description to be retrieved. ### Return Value @@ -201,21 +198,21 @@ The type of variant. ### Remarks -See [ITypeInfo::GetRefTypeInfo](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getreftypeinfo). +See [`ITypeInfo::GetRefTypeInfo`](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getreftypeinfo). -## IDispEventImpl::IDispEventImpl +## `IDispEventImpl::IDispEventImpl` -The constructor. Stores the values of the class template parameters *plibid*, *pdiid*, *wMajor*, and *wMinor*. +The constructor. Stores the values of the class template parameters *`plibid`*, *`pdiid`*, *`wMajor`*, and *`wMinor`*. -``` +```cpp IDispEventImpl(); ``` -## IDispEventImpl::tihclass +## `IDispEventImpl::_tihclass` -This typedef is an instance of the class template parameter *tihclass*. +This typedef is an instance of the class template parameter *`tihclass`*. -``` +```cpp typedef tihclass _tihclass; ``` @@ -225,10 +222,10 @@ By default, the class is `CComTypeInfoHolder`. `CComTypeInfoHolder` manages the ## See also -[_ATL_FUNC_INFO Structure](../../atl/reference/atl-func-info-structure.md)
-[IDispatchImpl Class](../../atl/reference/idispatchimpl-class.md)
-[IDispEventSimpleImpl Class](../../atl/reference/idispeventsimpleimpl-class.md)
-[SINK_ENTRY](composite-control-macros.md#sink_entry)
-[SINK_ENTRY_EX](composite-control-macros.md#sink_entry_ex)
-[SINK_ENTRY_INFO](composite-control-macros.md#sink_entry_info)
-[Class Overview](../../atl/atl-class-overview.md) +[`_ATL_FUNC_INFO` Structure](atl-func-info-structure.md)\ +[`IDispatchImpl` Class](idispatchimpl-class.md)\ +[`IDispEventSimpleImpl` Class](idispeventsimpleimpl-class.md)\ +[`SINK_ENTRY`](composite-control-macros.md#sink_entry)\ +[`SINK_ENTRY_EX`](composite-control-macros.md#sink_entry_ex)\ +[`SINK_ENTRY_INFO`](composite-control-macros.md#sink_entry_info)\ +[Class Overview](../atl-class-overview.md) diff --git a/docs/atl/reference/iolecontrolimpl-class.md b/docs/atl/reference/iolecontrolimpl-class.md index 6dc7d0f8a8..6c3430e9ce 100644 --- a/docs/atl/reference/iolecontrolimpl-class.md +++ b/docs/atl/reference/iolecontrolimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IOleControlImpl Class" title: "IOleControlImpl Class" +description: "Learn more about: IOleControlImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleControlImpl", "ATLCTL/ATL::IOleControlImpl", "ATLCTL/ATL::IOleControlImpl::FreezeEvents", "ATLCTL/ATL::IOleControlImpl::GetControlInfo", "ATLCTL/ATL::IOleControlImpl::OnAmbientPropertyChange", "ATLCTL/ATL::IOleControlImpl::OnMnemonic"] helpviewer_keywords: ["IOleControlImpl class"] -ms.assetid: 5a4255ad-ede4-49ca-ba9a-07c2e919fa85 --- # IOleControlImpl Class @@ -22,7 +21,7 @@ class IOleControlImpl #### Parameters -*T*
+*T*\ Your class, derived from `IOleControlImpl`. ## Members @@ -76,7 +75,7 @@ HRESULT GetControlInfo(LPCONTROLINFO pCI); ### Remarks -See [IOleControl:GetControlInfo](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-getcontrolinfo) in the Windows SDK. +See [IOleControl::GetControlInfo](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-getcontrolinfo) in the Windows SDK. ### Return Value @@ -116,6 +115,6 @@ See [IOleControl::OnMnemonic](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-onmn ## See also -[IOleObjectImpl Class](../../atl/reference/ioleobjectimpl-class.md)
-[ActiveX Controls Interfaces](/windows/win32/com/activex-controls-interfaces)
+[IOleObjectImpl Class](../../atl/reference/ioleobjectimpl-class.md)\ +[ActiveX Controls Interfaces](/windows/win32/com/activex-controls-interfaces)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/iperpropertybrowsingimpl-class.md b/docs/atl/reference/iperpropertybrowsingimpl-class.md index f81692daec..c5f0e2678e 100644 --- a/docs/atl/reference/iperpropertybrowsingimpl-class.md +++ b/docs/atl/reference/iperpropertybrowsingimpl-class.md @@ -16,7 +16,6 @@ This class implements `IUnknown` and allows a client to access the information i ## Syntax ``` - template class ATL_NO_VTABLE IPerPropertyBrowsingImpl : public IPerPropertyBrowsing diff --git a/docs/atl/reference/ipersiststorageimpl-class.md b/docs/atl/reference/ipersiststorageimpl-class.md index 9b8e3de985..a5396bee53 100644 --- a/docs/atl/reference/ipersiststorageimpl-class.md +++ b/docs/atl/reference/ipersiststorageimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IPersistStorageImpl Class" title: "IPersistStorageImpl Class" +description: "Learn more about: IPersistStorageImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistStorageImpl", "ATLCOM/ATL::IPersistStorageImpl", "ATLCOM/ATL::IPersistStorageImpl::GetClassID", "ATLCOM/ATL::IPersistStorageImpl::HandsOffStorage", "ATLCOM/ATL::IPersistStorageImpl::InitNew", "ATLCOM/ATL::IPersistStorageImpl::IsDirty", "ATLCOM/ATL::IPersistStorageImpl::Load", "ATLCOM/ATL::IPersistStorageImpl::Save", "ATLCOM/ATL::IPersistStorageImpl::SaveCompleted"] helpviewer_keywords: ["storage, ATL", "IPersistStorageImpl class"] -ms.assetid: d652f02c-239c-47c7-9a50-3e9fc3014fff --- # IPersistStorageImpl Class @@ -22,7 +21,7 @@ class ATL_NO_VTABLE IPersistStorageImpl : public IPersistStorage #### Parameters -*T*
+*T*\ Your class, derived from `IPersistStorageImpl`. ## Members @@ -97,7 +96,7 @@ STDMETHOD(InitNew)(IStorage*); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. -See [IPersistStorage:InitNew](/windows/win32/api/objidl/nf-objidl-ipersiststorage-initnew) in the Windows SDK. +See [IPersistStorage::InitNew](/windows/win32/api/objidl/nf-objidl-ipersiststorage-initnew) in the Windows SDK. ## IPersistStorageImpl::IsDirty @@ -111,7 +110,7 @@ STDMETHOD(IsDirty)(void); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. -See [IPersistStorage:IsDirty](/windows/win32/api/objidl/nf-objidl-ipersiststorage-isdirty) in the Windows SDK. +See [IPersistStorage::IsDirty](/windows/win32/api/objidl/nf-objidl-ipersiststorage-isdirty) in the Windows SDK. ## IPersistStorageImpl::Load @@ -125,7 +124,7 @@ STDMETHOD(Load)(IStorage* pStorage); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. `Load` uses a stream named "Contents" to retrieve the object's data. The [Save](#save) method originally creates this stream. -See [IPersistStorage:Load](/windows/win32/api/objidl/nf-objidl-ipersiststorage-load) in the Windows SDK. +See [IPersistStorage::Load](/windows/win32/api/objidl/nf-objidl-ipersiststorage-load) in the Windows SDK. ## IPersistStorageImpl::Save @@ -139,7 +138,7 @@ STDMETHOD(Save)(IStorage* pStorage, BOOL fSameAsLoad); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. When `Save` is first called, it creates a stream named "Contents" on the specified storage. This stream is then used in later calls to `Save` and in calls to [Load](#load). -See [IPersistStorage:Save](/windows/win32/api/objidl/nf-objidl-ipersiststorage-save) in the Windows SDK. +See [IPersistStorage::Save](/windows/win32/api/objidl/nf-objidl-ipersiststorage-save) in the Windows SDK. ## IPersistStorageImpl::SaveCompleted @@ -155,11 +154,11 @@ Returns S_OK. ### Remarks -See [IPersistStorage:SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. +See [IPersistStorage::SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. ## See also -[Storages and Streams](/windows/win32/Stg/storages-and-streams)
-[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)
-[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)
+[Storages and Streams](/windows/win32/Stg/storages-and-streams)\ +[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)\ +[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/message-map-macros-atl.md b/docs/atl/reference/message-map-macros-atl.md index 5752c16d10..99775caee5 100644 --- a/docs/atl/reference/message-map-macros-atl.md +++ b/docs/atl/reference/message-map-macros-atl.md @@ -2,7 +2,7 @@ description: "Learn more about: Message Map Macros (ATL)" title: "Message Map Macros (ATL)" ms.date: "11/04/2016" -f1_keywords: ["atlwin/ATL::ALT_MSG_MAP", "atlwin/ATL::BEGIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_ALT", "atlwin/ATL::CHAIN_MSG_MAP_ALT_MEMBER", "atlwin/ATL::CHAIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_DYNAMIC", "atlwin/ATL::CHAIN_MSG_MAP_MEMBER", "atlwin/ATL::COMMAND_CODE_HANDLER", "atlwin/ATL::COMMAND_HANDLER", "atlwin/ATL::COMMAND_ID_HANDLER", "atlwin/ATL::COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::COMMAND_RANGE_HANDLER", "atlwin/ATL::DECLARE_EMPTY_MSG_MAP", "atlwin/ATL::DEFAULT_REFLECTION_HANDLER", "atlwin/ATL::END_MSG_MAP", "atlwin/ATL::FORWARD_NOTIFICATIONS", "atlwin/ATL::MESSAGE_HANDLER", "atlwin/ATL::MESSAGE_RANGE_HANDLER", "atlwin/ATL::NOTIFY_CODE_HANDLER", "atlwin/ATL::NOTIFY_HANDLER", "atlwin/ATL::NOTIFY_ID_HANDLER", "atlwin/ATL::NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::NOTIFY_RANGE_HANDLER", "atlwin/ATL::REFLECT_NOTIFICATIONS", "atlwin/ATL::REFLECTED_COMMAND_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_ID_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_ID_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_HANDLER"] +f1_keywords: ["atlwin/ATL::ALT_MSG_MAP", "atlwin/ATL::BEGIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_ALT", "atlwin/ATL::CHAIN_MSG_MAP_ALT_MEMBER", "atlwin/ATL::CHAIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_DYNAMIC", "atlwin/ATL::CHAIN_MSG_MAP_MEMBER", "atlwin/ATL::COMMAND_CODE_HANDLER", "atlwin/ATL::COMMAND_HANDLER", "atlwin/ATL::COMMAND_ID_HANDLER", "atlwin/ATL::COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::COMMAND_RANGE_HANDLER", "atlwin/ATL::DECLARE_EMPTY_MSG_MAP", "atlwin/ATL::DEFAULT_REFLECTION_HANDLER", "atlwin/ATL::END_MSG_MAP", "atlwin/ATL::FORWARD_NOTIFICATIONS", "atlwin/ATL::MESSAGE_HANDLER", "atlwin/ATL::MESSAGE_RANGE_HANDLER", "atlwin/ATL::NOTIFY_CODE_HANDLER", "atlwin/ATL::NOTIFY_HANDLER", "atlwin/ATL::NOTIFY_ID_HANDLER", "atlwin/ATL::NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::NOTIFY_RANGE_HANDLER", "atlwin/ATL::REFLECT_NOTIFICATIONS", "atlwin/ATL::REFLECTED_COMMAND_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_ID_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_ID_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_HANDLER", "ATLWIN/ALT_MSG_MAP", "ATLWIN/BEGIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_ALT", "ATLWIN/CHAIN_MSG_MAP_ALT_MEMBER", "ATLWIN/CHAIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_DYNAMIC", "ATLWIN/CHAIN_MSG_MAP_MEMBER", "ATLWIN/COMMAND_CODE_HANDLER", "ATLWIN/COMMAND_HANDLER", "ATLWIN/COMMAND_ID_HANDLER", "ATLWIN/COMMAND_RANGE_CODE_HANDLER", "ATLWIN/COMMAND_RANGE_HANDLER", "ATLWIN/DECLARE_EMPTY_MSG_MAP", "ATLWIN/DEFAULT_REFLECTION_HANDLER", "ATLWIN/END_MSG_MAP", "ATLWIN/FORWARD_NOTIFICATIONS", "ATLWIN/MESSAGE_HANDLER", "ATLWIN/MESSAGE_RANGE_HANDLER", "ATLWIN/NOTIFY_CODE_HANDLER", "ATLWIN/NOTIFY_HANDLER", "ATLWIN/NOTIFY_ID_HANDLER", "ATLWIN/NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/NOTIFY_RANGE_HANDLER", "ATLWIN/REFLECT_NOTIFICATIONS", "ATLWIN/REFLECTED_COMMAND_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_HANDLER", "ATLWIN/REFLECTED_COMMAND_ID_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_HANDLER", "ATLWIN/REFLECTED_NOTIFY_ID_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_HANDLER"] ms.assetid: eefdd546-8934-4a30-b263-9c06a8addcbd --- # Message Map Macros (ATL) diff --git a/docs/atl/reference/object-map-macros.md b/docs/atl/reference/object-map-macros.md index c9ebdbdbbe..e0d53e8236 100644 --- a/docs/atl/reference/object-map-macros.md +++ b/docs/atl/reference/object-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Object Map Macros" title: "Object Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::DECLARE_OBJECT_DESCRIPTION", "atlcom/ATL::OBJECT_ENTRY_AUTO", "atlcom/ATL::OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO"] +f1_keywords: ["atlcom/ATL::DECLARE_OBJECT_DESCRIPTION", "atlcom/ATL::OBJECT_ENTRY_AUTO", "atlcom/ATL::OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO", "ATLCOM/DECLARE_OBJECT_DESCRIPTION", "ATLCOM/OBJECT_ENTRY_AUTO", "ATLCOM/OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO"] ms.assetid: 680087f4-9894-41dd-a79c-6f337e1f13c1 --- # Object Map Macros diff --git a/docs/atl/reference/object-status-macros.md b/docs/atl/reference/object-status-macros.md index 81f8189659..06a9bdb39f 100644 --- a/docs/atl/reference/object-status-macros.md +++ b/docs/atl/reference/object-status-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Object Status Macros" title: "Object Status Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::DECLARE_OLEMISC_STATUS"] +f1_keywords: ["atlcom/ATL::DECLARE_OLEMISC_STATUS", "ATLCOM/DECLARE_OLEMISC_STATUS"] ms.assetid: 727dbef2-a342-4157-9d64-a421805d9747 --- # Object Status Macros diff --git a/docs/atl/reference/property-map-macros.md b/docs/atl/reference/property-map-macros.md index 038b525d2f..c0e785543d 100644 --- a/docs/atl/reference/property-map-macros.md +++ b/docs/atl/reference/property-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Property Map Macros" title: "Property Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_PROP_MAP", "atlcom/ATL::PROP_DATA_ENTRY", "atlcom/ATL::PROP_ENTRY_TYPE", "atlcom/ATL::PROP_ENTRY_TYPE_EX", "atlcom/ATL::PROP_PAGE", "atlcom/ATL::END_PROP_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_PROP_MAP", "atlcom/ATL::PROP_DATA_ENTRY", "atlcom/ATL::PROP_ENTRY_TYPE", "atlcom/ATL::PROP_ENTRY_TYPE_EX", "atlcom/ATL::PROP_PAGE", "atlcom/ATL::END_PROP_MAP", "ATLCOM/BEGIN_PROP_MAP", "ATLCOM/PROP_DATA_ENTRY", "ATLCOM/PROP_ENTRY_TYPE", "ATLCOM/PROP_ENTRY_TYPE_EX", "ATLCOM/PROP_PAGE", "ATLCOM/END_PROP_MAP"] helpviewer_keywords: ["property maps"] ms.assetid: 128bc742-2b98-4b97-a243-684dbb83db77 --- @@ -78,7 +78,7 @@ When you create an ActiveX control, the wizard inserts this macro after the prop In the following example, the extent of the object (`m_sizeExtent`) is being persisted. [!code-cpp[NVC_ATL_Windowing#131](../../atl/codesnippet/cpp/property-map-macros_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#132](../../atl/codesnippet/cpp/property-map-macros_3.h)] ## PROP_ENTRY_TYPE diff --git a/docs/atl/reference/registry-data-exchange-macros.md b/docs/atl/reference/registry-data-exchange-macros.md index 06dce60c45..98857707a3 100644 --- a/docs/atl/reference/registry-data-exchange-macros.md +++ b/docs/atl/reference/registry-data-exchange-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Registry Data Exchange Macros" title: "Registry Data Exchange Macros" ms.date: "11/04/2016" -f1_keywords: ["atlplus/ATL::BEGIN_RDX_MAP", "atlplus/ATL::END_RDX_MAP", "atlplus/ATL::RDX_BINARY", "atlplus/ATL::RDX_CSTRING_TEXT", "atlplus/ATL::RDX_DWORD", "atlplus/ATL::RDX_TEXT"] +f1_keywords: ["atlplus/ATL::BEGIN_RDX_MAP", "atlplus/ATL::END_RDX_MAP", "atlplus/ATL::RDX_BINARY", "atlplus/ATL::RDX_CSTRING_TEXT", "atlplus/ATL::RDX_DWORD", "atlplus/ATL::RDX_TEXT", "ATLPLUS/BEGIN_RDX_MAP", "ATLPLUS/END_RDX_MAP", "ATLPLUS/RDX_BINARY", "ATLPLUS/RDX_CSTRING_TEXT", "ATLPLUS/RDX_DWORD", "ATLPLUS/RDX_TEXT"] helpviewer_keywords: ["RegistryDataExchange function, macros"] ms.assetid: c1bc5e79-2307-43d2-9d10-3a62ffadf473 --- diff --git a/docs/atl/reference/registry-macros.md b/docs/atl/reference/registry-macros.md index 930c43fb1a..f18617f0fe 100644 --- a/docs/atl/reference/registry-macros.md +++ b/docs/atl/reference/registry-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Registry Macros" title: "Registry Macros" ms.date: "08/19/2019" -f1_keywords: ["atlcom/ATL::_ATL_STATIC_REGISTRY", "atlcom/ATL::DECLARE_LIBID", "atlcom/ATL::DECLARE_NO_REGISTRY", "atlcom/ATL::DECLARE_REGISTRY", "atlcom/ATL::DECLARE_REGISTRY_APPID_RESOURCEID", "atlcom/ATL::DECLARE_REGISTRY_RESOURCE", "atlcom/ATL::DECLARE_REGISTRY_RESOURCEID"] +f1_keywords: ["ATLBASE/_ATL_STATIC_REGISTRY", "ATLBASE/DECLARE_LIBID", "ATLBASE/DECLARE_NO_REGISTRY", "ATLBASE/DECLARE_REGISTRY", "ATLBASE/DECLARE_REGISTRY_APPID_RESOURCEID", "ATLBASE/DECLARE_REGISTRY_RESOURCE", "ATLBASE/DECLARE_REGISTRY_RESOURCEID", "_ATL_STATIC_REGISTRY", "DECLARE_LIBID", "DECLARE_NO_REGISTRY", "DECLARE_REGISTRY", "DECLARE_REGISTRY_APPID_RESOURCEID", "DECLARE_REGISTRY_RESOURCE", "DECLARE_REGISTRY_RESOURCEID"] helpviewer_keywords: ["registry, ATL macros"] ms.assetid: 3ee041da-c63b-42a4-89cf-2a4b2a6f81ae --- diff --git a/docs/atl/reference/service-map-macros.md b/docs/atl/reference/service-map-macros.md index 76906d95cc..b42010306a 100644 --- a/docs/atl/reference/service-map-macros.md +++ b/docs/atl/reference/service-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Service Map Macros" title: "Service Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_SERVICE_MAP", "atlcom/ATL::END_SERVICE_MAP", "atlcom/ATL::SERVICE_ENTRY", "atlcom/ATL::SERVICE_ENTRY_CHAIN"] +f1_keywords: ["atlcom/ATL::BEGIN_SERVICE_MAP", "atlcom/ATL::END_SERVICE_MAP", "atlcom/ATL::SERVICE_ENTRY", "atlcom/ATL::SERVICE_ENTRY_CHAIN", "ATLCOM/BEGIN_SERVICE_MAP", "ATLCOM/END_SERVICE_MAP", "ATLCOM/SERVICE_ENTRY", "ATLCOM/SERVICE_ENTRY_CHAIN"] ms.assetid: ca02a125-454a-4cf6-aac2-1c5585025ed4 --- # Service Map Macros @@ -115,7 +115,7 @@ STDMETHOD(QueryService)( ### Return Value -The returned HRESULT value is one of the following: +The returned HRESULT is one of the following values: |Return value|Meaning| |------------------|-------------| @@ -123,23 +123,23 @@ The returned HRESULT value is one of the following: |E_INVALIDARG|One or more of the arguments is invalid.| |E_OUTOFMEMORY|Memory is insufficient to create the service.| |E_UNEXPECTED|An unknown error occurred.| -|E_NOINTERFACE|The requested interface is not part of this service, or the service is unknown.| +|E_NOINTERFACE|The requested interface isn't part of this service, or the service is unknown.| ### Remarks -`QueryService` returns an indirect pointer to the requested interface in the specified service. The caller is responsible for releasing this pointer when it is no longer required. +`QueryService` returns an indirect pointer to the requested interface in the specified service. The caller is responsible for releasing this pointer when it's no longer required. When you call `QueryService`, you pass both a service identifier (*guidService*) and an interface identifier (*riid*). The *guidService* specifies the service to which you want access, and the *riid* identifies an interface that is part of the service. In return, you receive an indirect pointer to the interface. -The object that implements the interface might also implement interfaces that are part of other services. Consider the following: +The object that implements the interface might also implement interfaces that are part of other services. Consider the following possibilities: - Some of these interfaces might be optional. Not all interfaces defined in the service description are necessarily present on every implementation of the service or on every returned object. -- Unlike calls to `QueryInterface`, passing a different service identifier does not necessarily mean that a different Component Object Model (COM) object is returned. +- Unlike calls to `QueryInterface`, passing a different service identifier doesn't necessarily mean that a different Component Object Model (COM) object is returned. -- The returned object might have additional interfaces that are not part of the definition of the service. +- The returned object might have other interfaces that aren't part of the definition of the service. -Two different services, such as SID_SMyService and SID_SYourService, can both specify the use of the same interface, even though the implementation of the interface might have nothing in common between the two services. This works, because a call to `QueryService` (SID_SMyService, IID_IDispatch) can return a different object than `QueryService` (SID_SYourService, IID_IDispatch). Object identity is not assumed when you specify a different service identifier. +Two different services, such as SID_SMyService and SID_SYourService, can both specify the use of the same interface, even though the implementation of the interface might have nothing in common between the two services. This approach works, because a call to `QueryService` (SID_SMyService, IID_IDispatch) can return a different object than `QueryService` (SID_SYourService, IID_IDispatch). Object identity isn't assumed when you specify a different service identifier. ## See also diff --git a/docs/atl/reference/snap-in-object-macros.md b/docs/atl/reference/snap-in-object-macros.md index 434f4d34ca..380f4cf116 100644 --- a/docs/atl/reference/snap-in-object-macros.md +++ b/docs/atl/reference/snap-in-object-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Snap-In Object Macros" title: "Snap-In Object Macros" ms.date: "11/04/2016" -f1_keywords: ["atlsnap/ATL::BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::BEGIN_SNAPINTOOLBARID_MAP", "atlsnap/ATL::END_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::END_SNAPINTOOLBARID_MAP", "atlsnap/ATL::EXTENSION_SNAPIN_DATACLASS", "atlsnap/ATL::EXTENSION_SNAPIN_NODEINFO_ENTRY", "atlsnap/ATL::SNAPINMENUID", "atlsnap/ATL::SNAPINTOOLBARID_ENTRY"] +f1_keywords: ["atlsnap/ATL::BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::BEGIN_SNAPINTOOLBARID_MAP", "atlsnap/ATL::END_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::END_SNAPINTOOLBARID_MAP", "atlsnap/ATL::EXTENSION_SNAPIN_DATACLASS", "atlsnap/ATL::EXTENSION_SNAPIN_NODEINFO_ENTRY", "atlsnap/ATL::SNAPINMENUID", "atlsnap/ATL::SNAPINTOOLBARID_ENTRY", "ATLSNAP/BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/BEGIN_SNAPINTOOLBARID_MAP", "ATLSNAP/END_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/END_SNAPINTOOLBARID_MAP", "ATLSNAP/EXTENSION_SNAPIN_DATACLASS", "ATLSNAP/EXTENSION_SNAPIN_NODEINFO_ENTRY", "ATLSNAP/SNAPINMENUID", "ATLSNAP/SNAPINTOOLBARID_ENTRY"] ms.assetid: 4e9850c0-e395-4929-86c9-584a81828053 --- # Snap-In Object Macros diff --git a/docs/atl/reference/string-conversion-macros.md b/docs/atl/reference/string-conversion-macros.md index 9930172187..9b67e45e5f 100644 --- a/docs/atl/reference/string-conversion-macros.md +++ b/docs/atl/reference/string-conversion-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: String Conversion Macros" title: "String Conversion Macros" ms.date: "11/04/2016" -f1_keywords: ["atlconv/ATL::DEVMODEA2W", "atlconv/ATL::TEXTMETRICA2W", "atlconv/ATL::DEVMODEOLE2T", "atlconv/ATL::TEXTMETRICOLE2T", "atlconv/ATL::DEVMODET2OLE", "atlconv/ATL::TEXTMETRICT2OLE", "atlconv/ATL::DEVMODEW2A", "atlconv/ATL::TEXTMETRICW2A"] +f1_keywords: ["atlconv/ATL::DEVMODEA2W", "atlconv/ATL::TEXTMETRICA2W", "atlconv/ATL::DEVMODEOLE2T", "atlconv/ATL::TEXTMETRICOLE2T", "atlconv/ATL::DEVMODET2OLE", "atlconv/ATL::TEXTMETRICT2OLE", "atlconv/ATL::DEVMODEW2A", "atlconv/ATL::TEXTMETRICW2A", "ATLCONV/DEVMODEA2W", "ATLCONV/TEXTMETRICA2W", "ATLCONV/DEVMODEOLE2T", "ATLCONV/TEXTMETRICOLE2T", "ATLCONV/DEVMODET2OLE", "ATLCONV/TEXTMETRICT2OLE", "ATLCONV/DEVMODEW2A", "ATLCONV/TEXTMETRICW2A"] ms.assetid: 2ff7c0b6-2bde-45fe-897f-6128e18e0c27 --- # String Conversion Macros diff --git a/docs/atl/reference/window-class-macros.md b/docs/atl/reference/window-class-macros.md index 1e0a546539..4804e4b723 100644 --- a/docs/atl/reference/window-class-macros.md +++ b/docs/atl/reference/window-class-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Window Class Macros" title: "Window Class Macros" ms.date: "11/04/2016" -f1_keywords: ["atlwin/ATL::DECLARE_WND_CLASS", "atlwin/ATL::DECLARE_WND_SUPERCLASS", "atlwin/ATL::DECLARE_WND_CLASS_EX"] +f1_keywords: ["atlwin/ATL::DECLARE_WND_CLASS", "atlwin/ATL::DECLARE_WND_SUPERCLASS", "atlwin/ATL::DECLARE_WND_CLASS_EX", "ATLWIN/DECLARE_WND_CLASS", "ATLWIN/DECLARE_WND_SUPERCLASS", "ATLWIN/DECLARE_WND_CLASS_EX"] ms.assetid: ce18681a-2bab-4453-9895-0f3ea47c2b24 --- # Window Class Macros diff --git a/docs/atl/reference/windows-messages-macros.md b/docs/atl/reference/windows-messages-macros.md index 3bcec790e6..0675305320 100644 --- a/docs/atl/reference/windows-messages-macros.md +++ b/docs/atl/reference/windows-messages-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Windows Messages Macros" title: "Windows Messages Macros" ms.date: "11/04/2016" -f1_keywords: ["atlbase/ATL::WM_FORWARDMSG"] +f1_keywords: ["atlbase/ATL::WM_FORWARDMSG", "ATLBASE/WM_FORWARDMSG"] ms.assetid: 63abd22c-372d-4148-bb04-c605950ae64f --- # Windows Messages Macros diff --git a/docs/atl/supporting-idispatch-and-ierrorinfo.md b/docs/atl/supporting-idispatch-and-ierrorinfo.md index 177b65623f..7d0c89d28e 100644 --- a/docs/atl/supporting-idispatch-and-ierrorinfo.md +++ b/docs/atl/supporting-idispatch-and-ierrorinfo.md @@ -9,7 +9,7 @@ ms.assetid: 7db2220f-319d-4ce9-9382-d340019f14f7 You can use the template class [IDispatchImpl](../atl/reference/idispatchimpl-class.md) to provide a default implementation of the `IDispatch Interface` portion of any dual interfaces on your object. -If your object uses the `IErrorInfo` interface to report errors back to the client, then your object must support the `ISupportErrorInfo Interface` interface. The template class [ISupportErrorInfoImpl](../atl/reference/isupporterrorinfoimpl-class.md) provides an easy way to implement this if you only have a single interface that generates errors on your object. +If your object uses the `IErrorInfo` interface to report errors back to the client, then your object must support the `ISupportErrorInfo` interface. The template class [ISupportErrorInfoImpl](../atl/reference/isupporterrorinfoimpl-class.md) provides an easy way to implement this if you only have a single interface that generates errors on your object. ## See also diff --git a/docs/build-insights/get-started-with-cpp-build-insights.md b/docs/build-insights/get-started-with-cpp-build-insights.md index 038b948e19..0ee6e8c583 100644 --- a/docs/build-insights/get-started-with-cpp-build-insights.md +++ b/docs/build-insights/get-started-with-cpp-build-insights.md @@ -14,7 +14,7 @@ The C++ Build Insights tools are available in Visual Studio 2019 and later. To s ::: moniker-end ::: moniker range=">=msvc-160" -C++ Build Insights is a collection of tools that provides increased visibility into the Microsoft Visual C++ (MSVC) tool chain. The tools collect data about your C++ builds, and present it in a format that can help you answer common questions, like: +C++ Build Insights is a collection of tools that collect data about your C++ builds, and present it in a format that can help you answer common questions such as: - Are my builds sufficiently parallelized? - What should I include in my pre-compiled header (PCH)? @@ -22,16 +22,16 @@ C++ Build Insights is a collection of tools that provides increased visibility i The main components of this technology are: -- *vcperf.exe*, a command-line utility that you can use to collect traces for your builds, -- a Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and -- the C++ Build Insights SDK, a software development kit for creating your own tools that consume C++ Build Insights data. +- `vcperf.exe`, a command-line utility that you can use to collect traces for your builds +- A Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and +- The C++ Build Insights software development kit for creating your own tools that consume C++ Build Insights data. ## Documentation sections -[Tutorial: vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\ +[vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\ Learn how to collect build traces for your C++ projects and how to view them in WPA. -[Tutorial: Windows Performance Basics](tutorials/wpa-basics.md)\ +[Windows Performance Basics](tutorials/wpa-basics.md)\ Discover useful WPA tips for analyzing your build traces. [C++ Build Insights SDK](reference/sdk/overview.md)\ @@ -41,20 +41,13 @@ An overview of the C++ Build Insights SDK. Read these articles from the official C++ team blog for more information on C++ Build Insights: -[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/) - -[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/) - -[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/) - -[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/) - -[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/) - -[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/) - -[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/) - +[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/)\ +[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/)\ +[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/)\ +[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/)\ +[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/)\ +[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/)\ [Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/) ::: moniker-end diff --git a/docs/build-insights/index.yml b/docs/build-insights/index.yml index 7a68551902..876c27600a 100644 --- a/docs/build-insights/index.yml +++ b/docs/build-insights/index.yml @@ -6,8 +6,8 @@ metadata: title: C++ Build Insights description: Learn how to use C++ Build Insights to analyze and optimize your builds. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 05/26/2020 ms.custom: intro-landing-hub @@ -25,6 +25,10 @@ landingContent: url: get-started-with-cpp-build-insights.md - linkListType: tutorial links: + - text: Build Insights function view + url: tutorials/build-insights-function-view.md + - text: Build Insights included files view + url: tutorials/build-insights-included-files-view.md - text: vcperf and Windows Performance Analyzer url: tutorials/vcperf-and-wpa.md - text: Windows Performance Analyzer basics diff --git a/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md index 3de2bb7457..734b468058 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md @@ -1,7 +1,9 @@ --- -title: "EVENT_DATA structure" -description: "The C++ Build Insights SDK EVENT_DATA structure reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK EVENT_DATA structure" +description: "The C++ Build Insights SDK EVENT_DATA structure reference. The EVENT_DATA structure describes an event received from an analysis or relogging session." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_DATA", "throughput analysis", "build time analysis", "vcperf.exe"] --- # EVENT_DATA structure @@ -13,7 +15,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To s ::: moniker-end ::: moniker range=">=msvc-150" -The `EVENT_DATA` structure describes an event received from an analysis or relogging session. These sessions are started by calling the [Analyze](../functions/analyze.md), [AnalyzeA](../functions/analyze-a.md), [AnalyzeW](../functions/analyze-w.md), [Relog](../functions/relog.md), [RelogA](../functions/relog-a.md), or [RelogW](../functions/relog-w.md) functions. +The `EVENT_DATA` structure describes an event from an analysis or relogging session. The [Analyze](../functions/analyze.md), [AnalyzeA](../functions/analyze-a.md), [AnalyzeW](../functions/analyze-w.md), [Relog](../functions/relog.md), [RelogA](../functions/relog-a.md), or [RelogW](../functions/relog-w.md) functions start these sessions. ## Syntax @@ -51,14 +53,14 @@ typedef struct EVENT_DATA_TAG | `EventId` | A number that identifies the event. For a list of event identifiers, see [EVENT_ID](event-id-enum.md). | | `EventInstanceId` | A number that uniquely identifies the current event inside a trace. This value doesn't change when analyzing or relogging the same trace multiple times. Use this field to identify the same event in multiple analysis or relogging passes over the same trace. | | `TickFrequency` | The number of ticks per second to use when evaluating a duration measured in ticks. | -| `StartTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity started. If this event is a *Simple Event*, this field is set to a tick value captured at the time the event occurred. | -| `StopTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity stopped. If the stop event hasn't yet been received for this activity, this field is set to zero. If this event is a *Simple Event*, this field is set to zero. | -| `ExclusiveDurationTicks` | If this event is an *Activity*, this field is set to the number of ticks that occurred directly in this activity. The number of ticks that occurred in a child activity are excluded. This field is set to zero for *Simple Events*. | -| `CPUTicks` | If this event is an *Activity*, this field is set to the number of CPU ticks that occurred during this activity. A CPU tick is different from a regular tick. CPU ticks are only counted when the CPU is executing code in an activity. CPU ticks aren't counted when the thread associated with the activity is sleeping. This field is set to zero for *Simple Events*. | -| `ExclusiveCPUTicks` | This field has the same meaning as `CPUTicks`, except that it doesn't include CPU ticks that occurred in children activities. This field is set to zero for *Simple Events*. | -| `WallClockTimeResponsibilityTicks` | If this event is an *Activity*, this field is set to a tick count that represents this activity's contribution to overall wall-clock time. A wall-clock time responsibility tick is different from a regular tick. Wall-clock time responsibility ticks take into account parallelism between activities. For example, two parallel activities may have a duration of 50 ticks and the same start and stop time. In this case, both will be assigned a wall-clock time responsibility of 25 ticks. This field is set to zero for *Simple Events*. | -| `ExclusiveWallClockTimeResponsibilityTicks` | This field has the same meaning as `WallClockTimeResponsibilityTicks`, except that it doesn't include the wall-clock time responsibility ticks of children activities. This field is set to zero for *Simple Events*. | -| `Data` | Points to additional data stored in the event. The type of data pointed to is different, depending on the `EventId` field. | +| `StartTimestamp` | When the event is an *Activity*, this field is the tick value captured at the time the activity started. If this event is a *Simple Event*, this field is a tick value captured at the time the event occurred. | +| `StopTimestamp` | When the event is an *Activity*, this field is the tick value captured at the time the activity stopped. If the stop event hasn't yet been received for this activity, this field is zero. If this event is a *Simple Event*, this field is zero. | +| `ExclusiveDurationTicks` | If this event is an *Activity*, this field is the number of ticks that occurred directly in this activity. The number of ticks that occurred in a child activity are excluded. This field is zero for *Simple Events*. | +| `CPUTicks` | If this event is an *Activity*, this field is the number of CPU ticks that occurred during this activity. A CPU tick is different from a regular tick. CPU ticks are only counted when the CPU is executing code in an activity. CPU ticks aren't counted when the thread associated with the activity is sleeping. This field is zero for *Simple Events*. | +| `ExclusiveCPUTicks` | This field has the same meaning as `CPUTicks`, except that it doesn't include CPU ticks that occurred in children activities. This field is zero for *Simple Events*. | +| `WallClockTimeResponsibilityTicks` | If this event is an *Activity*, this field is a tick count that represents this activity's contribution to overall wall-clock time. A wall-clock time responsibility tick is different from a regular tick. Wall-clock time responsibility ticks take into account parallelism between activities. For example, two parallel activities may have a duration of 50 ticks and the same start and stop time. In this case, both will be assigned a wall-clock time responsibility of 25 ticks. This field is zero for *Simple Events*. | +| `ExclusiveWallClockTimeResponsibilityTicks` | This field has the same meaning as `WallClockTimeResponsibilityTicks`, except that it doesn't include the wall-clock time responsibility ticks of children activities. This field is zero for *Simple Events*. | +| `Data` | Points to other data stored in the event. The type of data pointed to is different, depending on the `EventId` field. | | `ProcessId` | The identifier for the process in which the event occurred. | | `ThreadId` | The identifier for the thread in which the event occurred. | | `ProcessorIndex` | The zero-indexed CPU number on which the event occurred. | @@ -67,9 +69,13 @@ typedef struct EVENT_DATA_TAG ## Remarks -Many fields in `EVENT_DATA` contain tick counts. C++ Build Insights uses Window's performance counter as a source of ticks. A tick count must be used with the `TickFrequency` field to convert it into an appropriate time unit such as seconds. See the example below for performing this conversion. `EVENT_DATA` doesn't contain a field for the regular tick count of an activity. To obtain this value, subtract `StartTimestamp` from `StopTimestamp`. `EVENT_DATA` is a structure that's meant to be used by C API users. For C++ API users, classes like [Event](../cpp-event-data-types/event.md) do time conversions automatically. +Many fields in `EVENT_DATA` contain tick counts. C++ Build Insights uses the Windows performance counter as a source of ticks. A tick count must be used with the `TickFrequency` field to convert it into an appropriate time unit such as seconds. See the [tick conversion example](#tick-conversion-example), below. -The value of the `EVENT_DATA` `Data` field depends on the value of its `EventId` field. The value of `Data` is described in the table below. Some entity identifiers may be missing from the table below. In this case, the `Data` field is set to **`nullptr`** or zero. +`EVENT_DATA` doesn't contain a field for the regular tick count of an activity. To obtain this value, subtract `StartTimestamp` from `StopTimestamp`. + +`EVENT_DATA` is a structure that's meant to be used by C API users. For C++ API users, classes like [Event](../cpp-event-data-types/event.md) do time conversions automatically. + +The value of the `EVENT_DATA` `Data` field depends on the value of its `EventId` field. The value of `Data` is described in the table below. Some entity identifiers may be missing from the table below. In this case, the `Data` field is set to `nullptr` or zero. | `EventId` value | Type pointed to by `Data` | |--|--| diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md b/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md index aa060dc27b..fbf985fe5d 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md @@ -1,9 +1,12 @@ --- -title: "Activity class" -description: "The C++ Build Insights SDK Activity class reference." -ms.date: "02/12/2020" +title: "Activity class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK Activity class reference. Use the Activity class to match any activity event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Activity", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # Activity class ::: moniker range="<=msvc-140" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md index d01ecfb1fb..076d93d4d9 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md @@ -1,9 +1,12 @@ --- -title: "BackEndPass class" -description: "The C++ Build Insights SDK BackEndPass class reference." -ms.date: "02/12/2020" +title: "BackEndPass class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK BackEndPass class reference. Use the BackEndPass class to match a BACK_END_PASS event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "BackEndPass", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # BackEndPass class ::: moniker range="<=msvc-140" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md b/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md index 8ad2fb4066..3982034e86 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md @@ -1,9 +1,12 @@ --- -title: "C1DLL class" -description: "The C++ Build Insights SDK C1DLL class reference." -ms.date: "02/12/2020" +title: "C1DLL class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK C1DLL class reference. Use the C1DLL class to match a C1_DLL event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "C1DLL", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # C1DLL class ::: moniker range="<=msvc-140" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md index b98998fd39..5fc55fa2ab 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md @@ -56,7 +56,7 @@ Along with the inherited members from its [Activity](activity.md) base class, th [InputSourcePath](#input-source-path)\ [OutputObjectPath](#output-object-path)\ -[PassCode](#pass-code)\ +[PassCode](#pass-code) ## CompilerPass diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md b/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md index 7265d140e1..133484cb32 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Name](#name) +[Name](#name)\ [Value](#value) ## EnvironmentVariable diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md index 0329689f4c..6eeabda6f4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md @@ -42,11 +42,11 @@ The activity type contained in the group. ### Functions -[Back](#back) -[begin](#begin) -[end](#end) -[Front](#front) -[operator[]](#subscript-operator) +[Back](#back)\ +[begin](#begin)\ +[end](#end)\ +[Front](#front)\ +[operator[]](#subscript-operator)\ [Size](#size) ## Back diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md index 7b64275549..e206d537cf 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md @@ -37,8 +37,8 @@ public: ### Functions -[Back](#back) -[operator[]](#subscript-operator) +[Back](#back)\ +[operator[]](#subscript-operator)\ [Size](#size) ## Back diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event.md index f8f8926917..e4518cef9e 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event.md @@ -43,7 +43,7 @@ public: ### Functions -[Data](#data) +[Data](#data)\ [EventId](#event-id)\ [EventInstanceId](#event-instance-id)\ [EventName](#event-name)\ diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md b/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md index 74ba8fc4ce..1607802410 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md @@ -48,7 +48,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Path](#path) +[Path](#path)\ [Type](#type) ## FileInput diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md index 6772fe813e..f339588c6e 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md @@ -48,7 +48,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Path](#path) +[Path](#path)\ [Type](#type) ## FileOutput diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md b/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md index edd2ae4ddf..ee9bac8bc6 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Name](#name) +[Name](#name)\ [Size](#size) ## ForceInlinee diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/function.md b/docs/build-insights/reference/sdk/cpp-event-data-types/function.md index 8d15a5ce98..bc81e6fbcf 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/function.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/function.md @@ -1,7 +1,9 @@ --- -title: "Function class" -description: "The C++ Build Insights SDK Function class reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK Function class" +description: "The C++ Build Insights SDK Function class reference. Use the Function class to match a FUNCTION event." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Function", "throughput analysis", "build time analysis", "vcperf.exe"] --- # Function class @@ -29,7 +31,7 @@ public: ## Members -Along with the inherited members from its [Activity](activity.md) base class, the `Function` class contains the following members: +Along with the inherited members from the [Activity](activity.md) base class, the `Function` class contains the following members: ### Constructors @@ -39,7 +41,7 @@ Along with the inherited members from its [Activity](activity.md) base class, th [Name](#name) -## Function +## Function ```cpp Function(const RawEvent& event); @@ -50,7 +52,7 @@ Function(const RawEvent& event); *event*\ A [FUNCTION](../event-table.md#function) event. -## Name +## Name ```cpp const char* Name() const; diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md index 0006c06a83..3dc40659f7 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md @@ -50,10 +50,10 @@ Along with the inherited members from its [Activity](activity.md) base class, th ### Functions -[ToolPath](#tool-path) -[ToolVersion](#tool-version) -[ToolVersionString](#tool-version-string) -[Type](#type) +[ToolPath](#tool-path)\ +[ToolVersion](#tool-version)\ +[ToolVersionString](#tool-version-string)\ +[Type](#type)\ [WorkingDirectory](#working-directory) ## Invocation diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md b/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md index fc8d17f3cd..6063aeef27 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md @@ -1,7 +1,9 @@ --- -title: "Pass1 class" -description: "The C++ Build Insights SDK Pass1 class reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK Pass1 class" +description: "The C++ Build Insights SDK Pass1 class reference. Use the Pass1 class to match a PASS1 event" +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Pass1", "throughput analysis", "build time analysis", "vcperf.exe"] --- # Pass1 class @@ -27,13 +29,13 @@ public: ## Members -Along with the inherited members from its [LinkerPass](linker-pass.md) base class, the `Pass1` class contains the following members: +Along with the inherited members from the [LinkerPass](linker-pass.md) base class, the `Pass1` class contains the following members: ### Constructors [Pass1](#pass1) -## Pass1 +## Pass1 ```cpp Pass1(const RawEvent& event); diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md b/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md index 2d767ed280..ef78df1ffc 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md @@ -67,8 +67,8 @@ If you don't want to convert ticks yourself, the `RawEvent` class provides membe [CPUTime](#cpu-time)\ [Data](#data)\ [Duration](#duration)\ -[EventId](#event-id) -[EventInstanceId](#event-instance-id) +[EventId](#event-id)\ +[EventInstanceId](#event-instance-id)\ [EventName](#event-name)\ [EventWideName](#event-wide-name)\ [ExclusiveCPUTicks](#exclusive-cpu-ticks)\ diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md b/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md index 98b10ece5b..a172bccaea 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Key](#key) +[Key](#key)\ [Name](#name) ## Key diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md index 3729c2bebd..b73bc7f4fb 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md @@ -48,8 +48,8 @@ Along with the inherited members from its [Activity](activity.md) base class, th ### Functions -[Kind](#kind) -[PrimaryTemplateSymbolKey](#primary-template-symbol-key) +[Kind](#kind)\ +[PrimaryTemplateSymbolKey](#primary-template-symbol-key)\ [SpecializationSymbolKey](#specialization-symbol-key) ## Kind diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md b/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md index 918f0ecba9..0d7d0284f4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md @@ -47,10 +47,10 @@ If you don't want to convert ticks yourself, the `TraceInfo` class provides a me ### Functions -[Duration](#duration) -[LogicalProcessorCount](#logical-processor-count) -[StartTimestamp](#start-timestamp) -[StopTimestamp](#stop-timestamp) +[Duration](#duration)\ +[LogicalProcessorCount](#logical-processor-count)\ +[StartTimestamp](#start-timestamp)\ +[StopTimestamp](#stop-timestamp)\ [TickFrequency](#tick-frequency) ## Duration diff --git a/docs/build-insights/reference/sdk/functions/analyze-w.md b/docs/build-insights/reference/sdk/functions/analyze-w.md index b4442cb02e..f7dc804272 100644 --- a/docs/build-insights/reference/sdk/functions/analyze-w.md +++ b/docs/build-insights/reference/sdk/functions/analyze-w.md @@ -1,10 +1,13 @@ --- -title: "AnalyzeW" -description: "The C++ Build Insights SDK AnalyzeW function reference." -ms.date: "02/12/2020" +title: "AnalyzeW - C++ Build Insights SDK" +description: "The C++ Build Insights SDK AnalyzeW function reference. Use the AnalyzeW function to analyze MSVC events read from an input Event Tracing for Windows trace." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalyzeW", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- -# AnalyzeW + +# AnalyzeW function ::: moniker range="<=msvc-140" diff --git a/docs/build-insights/reference/sdk/functions/analyze.md b/docs/build-insights/reference/sdk/functions/analyze.md index 3d2f07c585..32e5bd369c 100644 --- a/docs/build-insights/reference/sdk/functions/analyze.md +++ b/docs/build-insights/reference/sdk/functions/analyze.md @@ -1,10 +1,13 @@ --- -title: "Analyze" -description: "The C++ Build Insights SDK Analyze function reference." -ms.date: "02/12/2020" +title: "Analyze - C++ Build Insights SDK" +description: "The C++ Build Insights SDK Analyze function reference. Use the Analyze function to analyze an Event Tracing for Windows trace from MSVC while tracing a build." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Analyze", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- -# Analyze + +# Analyze function ::: moniker range="<=msvc-140" diff --git a/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md b/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md index 49afc72718..e6aac87710 100644 --- a/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md +++ b/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md @@ -1,7 +1,9 @@ --- -title: "MakeStaticAnalyzerGroup" -description: "The C++ Build Insights SDK MakeStaticAnalyzerGroup function reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK MakeStaticAnalyzerGroup" +description: "The C++ Build Insights SDK MakeStaticAnalyzerGroup function reference. Use this function to create a static analyzer group for functions like Analyze or Relog." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeStaticAnalyzerGroup", "throughput analysis", "build time analysis", "vcperf.exe"] --- # MakeStaticAnalyzerGroup @@ -13,7 +15,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To s ::: moniker-end ::: moniker range=">=msvc-150" -The `MakeStaticAnalyzerGroup` function is used to create a static analyzer group that can be passed to functions such as [`Analyze`](analyze.md) or [`Relog`](relog.md). Members of an analyzer group receive events one by one from left to right, until all events in a trace get analyzed. +The `MakeStaticAnalyzerGroup` function creates a static analyzer group that you can pass to functions such as [`Analyze`](analyze.md) or [`Relog`](relog.md). Members of an analyzer group receive events one by one from left to right, until all events in a trace are analyzed. ## Syntax @@ -32,10 +34,12 @@ A parameter pack of [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers in ### Return Value -A static analyzer group. Use the **`auto`** keyword to capture the return value. +A static analyzer group. Use the `auto` keyword to capture the return value. ## Remarks -Unlike dynamic analyzer groups, the members of a static analyzer group must be known at compile time. Additionally, a static analyzer group contains [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers that don't have polymorphic behavior. When using a static analyzer group to analyze an Event Tracing for Windows (ETW) trace, calls to the `IAnalyzer` interface always resolve to the object directly pointed to by the analyzer group member. This loss of flexibility comes with a possibility of faster event processing times. If the members of an analyzer group can't be known at compile time, or if you require polymorphic behavior on your `IAnalyzer` pointers, consider using a dynamic analyzer group. To use a dynamic analyzer group, call [`MakeDynamicAnalyzerGroup`](make-static-analyzer-group.md) instead. +Unlike dynamic analyzer groups, the members of a static analyzer group must be known at compile time. Also, a static analyzer group contains [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers that don't have polymorphic behavior. When a static analyzer group analyzes an Event Tracing for Windows (ETW) trace, calls to the `IAnalyzer` interface always resolve to the object directly pointed to by the analyzer group member. This loss of flexibility comes with a possibility of faster event processing. + +If the members of an analyzer group can't be known at compile time, or if you require polymorphic behavior on your `IAnalyzer` pointers, consider using a dynamic analyzer group. To use a dynamic analyzer group, call [`MakeDynamicAnalyzerGroup`](make-static-analyzer-group.md) instead. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/relog.md b/docs/build-insights/reference/sdk/functions/relog.md index 53fe924c8c..13259b2978 100644 --- a/docs/build-insights/reference/sdk/functions/relog.md +++ b/docs/build-insights/reference/sdk/functions/relog.md @@ -77,4 +77,6 @@ The input trace is passed through the analyzer group *numberOfAnalysisPasses* ti The relogging of system events like CPU samples from within a relogger class isn't supported. Use the *systemEventsRetentionFlags* parameter to decide which system events to keep in the output trace. +The `relog` function depends on the COM API. You must call `CoInitialize` before you call `relog`. Call `CoUninitialize` once `relog` has finished. If you call `relog` without a call to `CoInitialize` first, you'll get error code 9 (`RESULT_CODE_FAILURE_START_RELOGGER`). + ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md index 46dedc00da..39ac969bab 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md @@ -13,7 +13,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To s ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSessionA` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionA` must have administrator privileges. +The `StopTracingSessionA` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionA` must have administrator privileges. ## Syntax diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md index a050b60ed3..32e05f8ce8 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md @@ -13,7 +13,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To s ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSessionW` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionW` must have administrator privileges. +The `StopTracingSessionW` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionW` must have administrator privileges. ## Syntax diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session.md index 1aa039019e..9e52425ed8 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session.md @@ -1,7 +1,9 @@ --- -title: "StopTracingSession" -description: "The C++ Build Insights SDK StopTracingSession function reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK StopTracingSession" +description: "The C++ Build Insights SDK StopTracingSession function reference. StopTracingSession stops an ongoing tracing session and produces a raw trace file." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTracingSession", "throughput analysis", "build time analysis", "vcperf.exe"] --- # StopTracingSession @@ -13,7 +15,9 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To s ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSession` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start a relogging session. Executables calling `StopTracingSession` must have administrator privileges. +The `StopTracingSession` function stops an ongoing tracing session and produces a raw trace file. You can pass raw trace files to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. You can pass raw trace files to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start a relogging session. + +The caller must have administrator permissions to use `StopTracingSession`. ## Syntax @@ -24,7 +28,7 @@ inline RESULT_CODE StopTracingSession( TRACING_SESSION_STATISTICS* statistics); inline RESULT_CODE StopTracingSession( - const wchar_t* sessionName + const wchar_t* sessionName, const wchar_t* outputLogFile, TRACING_SESSION_STATISTICS* statistics); ``` @@ -32,10 +36,10 @@ inline RESULT_CODE StopTracingSession( ### Parameters *sessionName*\ -The name of the tracing session to stop. Use the same session name as the one passed to [StartTracingSession](start-tracing-session.md), [StartTracingSessionA](start-tracing-session-a.md), or [StartTracingSessionW](start-tracing-session-w.md). +The name of the tracing session to stop. Use the same session name as used for [StartTracingSession](start-tracing-session.md), [StartTracingSessionA](start-tracing-session-a.md), or [StartTracingSessionW](start-tracing-session-w.md). *outputLogFile*\ -Path to the final output log file where the raw trace should be saved. +Full path of the final output log file to save the raw trace. *statistics*\ Pointer to a [TRACING_SESSION_STATISTICS](../other-types/tracing-session-statistics-struct.md) object. `StopTracingSession` writes trace collection statistics in this object before returning. diff --git a/docs/build-insights/reference/vcperf-commands.md b/docs/build-insights/reference/vcperf-commands.md index 1a7924241b..ed8342bf1b 100644 --- a/docs/build-insights/reference/vcperf-commands.md +++ b/docs/build-insights/reference/vcperf-commands.md @@ -18,23 +18,23 @@ This article lists and describes the commands available in *`vcperf.exe`*, and h ## Commands to start and stop traces > [!IMPORTANT] -> The following commands all require administrative privileges. +> Unless you specify `/noadmin`, the following commands require administrative privileges. | Option | Arguments and description | |------------------|---------------------------| -| `/start` | `[/nocpusampling]` `` | -| | Tells *vcperf.exe* to start a trace under the given session name. There can only be one active session at a time on a given machine.

If the `/nocpusampling` option is specified, *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller.

Once tracing is started, *vcperf.exe* returns immediately. Events are collected system-wide for all processes running on the machine. That means that you don't need to build your project from the same command prompt as the one you used to run *vcperf.exe*. For example, you can build your project from Visual Studio. | -| `/stop` | `` `` | -| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file viewable in Windows Performance Analyzer (WPA). For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). The `` parameter specifies where to save the output file. | -| `/stopnoanalyze` | `` `` | -| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file isn't meant to be viewed in WPA.

The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you're ready to produce a file viewable in Windows Performance Analyzer. | +| `/start` | [`/noadmin`] [`/nocpusampling`] [`/level1` \| `/level2` \| `/level3`] `` | +| | Starts a trace under the given session name.

The `/noadmin` option runs *vcperf.exe* without admin privileges, and it ignores the `/nocpusampling` option. When you run vcperf without admin privileges, there can be more than one active session on a given machine.

The `/nocpusampling` option specifies *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller.

The `/level1`, `/level2`, or `/level3` options specify which MSVC events to collect, in increasing level of information. Level 3 includes all events. Level 2 includes all events except template instantiation events. Level 1 includes all events except template instantiation, function, and file events. If unspecified, `/level2` is selected by default.

Once *vcperf.exe* starts the trace, it returns immediately. The trace collects events system-wide for all processes running on the machine. That means that you don't need to build your project in the same command prompt window as the one you use to run *vcperf.exe*. For example, you can build your project in Visual Studio. | +| `/stop` | (1) [`/templates`] ` `
(2) [`/templates`] ` /timetrace ` | +| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file specified by the `` parameter.

The `/templates` option includes template instantiation events in the file.

(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.
(2) Generates a file viewable in the Microsoft Edge trace viewer (`edge://tracing`). The output file requires a `.json` extension. | +| `/stopnoanalyze` | ` ` | +| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file isn't meant for viewing in WPA.

The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you're ready to produce a file viewable in Windows Performance Analyzer or the Microsoft Edge trace viewer. | ## Miscellaneous commands | Option | Arguments and description | |------------|---------------------------| -| `/analyze` | ` ` | -| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate a file viewable in Windows Performance Analyzer. For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). | +| `/analyze` | (1) [`/templates`] ` `
(2) [`/templates`] ` /timetrace ` | +| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate the file specified by the `` parameter.

The `/templates` option includes template instantiation events in the file.

(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.

(2) Generates a file viewable in the Microsoft Edge trace viewer (`edge://tracing`). The output file requires a `.json` extension. | ## See also diff --git a/docs/build-insights/toc.yml b/docs/build-insights/toc.yml index 30f047a6e9..99cea23e5b 100644 --- a/docs/build-insights/toc.yml +++ b/docs/build-insights/toc.yml @@ -6,6 +6,12 @@ items: - name: "Tutorials" expanded: true items: + - name: "Troubleshoot function inlining on build time" + href: ../build-insights/tutorials/build-insights-function-view.md + - name: "Troubleshoot header file impact on build time" + href: ../build-insights/tutorials/build-insights-included-files-view.md + - name: "Build Insights tips and tricks" + href: ../build-insights/tutorials/build-insights-tips.md - name: "vcperf and Windows Performance Analyzer" href: ../build-insights/tutorials/vcperf-and-wpa.md - name: "Windows Performance Analyzer basics" diff --git a/docs/build-insights/tutorials/build-insights-function-view.md b/docs/build-insights/tutorials/build-insights-function-view.md new file mode 100644 index 0000000000..598ea77cf2 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-function-view.md @@ -0,0 +1,151 @@ +--- +title: "Troubleshoot function inlining on build time" +description: "Tutorial for how to use Build Insights function view to troubleshoot the impact of function inlining on build time in your C++ projects." +ms.date: 5/30/2024 +helpviewer_keywords: ["C++ Build Insights", "inline function analysis", "build time analysis", "__forceinline analysis", "inlines analysis"] +--- +# Troubleshoot function inlining on build time + +Use Build Insights **Functions** view to troubleshoot the impact of function inlining on build time in your C++ projects. + +## Prerequisites + +- Visual Studio 2022 17.8 or greater. +- C++ Build insights is enabled by default if you install either the Desktop development with C++ workload or the Game development with C++ workload. + +:::image type="complex" source="./media/installer-desktop-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Desktop development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +:::image type="complex" source="./media/installer-gamedev-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Game development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +## Overview + +Build Insights, now integrated into Visual Studio, helps you optimize your build times--especially for large projects like AAA games. Build Insights provides analytics such as **Functions** view, which helps diagnose expensive code generation during build time. It displays the time it takes to generate code for each function, and shows the impact of [`__forceinline`](../../cpp/inline-functions-cpp.md#inline-__inline-and-__forceinline). + +The `__forceinline` directive tells the compiler to inline a function regardless of its size or complexity. Inlining a function can improve runtime performance by reducing the overhead of calling the function. The tradeoff is that it can increase the size of the binary and impact your build times. + +For optimized builds, the time spent generating code contributes significantly to the total build time. In general, C++ function optimization happens quickly. In exceptional cases, some functions can become large enough and complex enough to put pressure on the optimizer and noticeably slow down your builds. + +In this article, learn how to use the Build Insights **Functions** view to find inlining bottlenecks in your build. + +## Set build options + +To measure the results of `__forceinline`, use a **Release** build because debug builds don't inline `__forceinline` since debug builds use the [`/Ob0`](../../build/reference/ob-inline-function-expansion.md) compiler switch, which disables that optimization. Set the build for **Release** and **x64**: + +1. In the **Solution Configurations** dropdown, choose **Release**. +1. In the **Solution Platforms** dropdown, choose **x64**. + +:::image type="content" source="./media/build-options-release.png" alt-text="Screenshot of the Solution Configuration dropdown set to Release, and the Solution Platform dropdown set to x64."::: + +Set the optimization level to maximum optimizations: + +1. In the **Solution Explorer**, right-click the project name and select **Properties**. +1. In the project properties, navigate to **C/C++** > **Optimization**. +1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/ob-inline-function-expansion.md))**. + + :::image type="content" source="./media/max-optimization-setting.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Configuration Properties > C/C++ > Optimization. The Optimization dropdown is set to Maximum Optimization (Favor Speed) (/O2)."::: + +1. Click **OK** to close the dialog. + +## Run Build Insights + +On a project of your choosing, and using the **Release** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now. + +:::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected."::: + +When the build finishes, an Event Trace Log (ETL) file opens. It's saved in the folder pointed to by the Windows `TEMP` environment variable. The generated name is based on the collection time. + +## Function view + +In the window for the ETL file, choose the **Functions** tab. It shows the functions that were compiled and the time it took to generate the code for each function. If the amount of code generated for a function is negligible, it won't appear in the list to avoid degrading build event collection performance. + +:::image type="complex" source="./media/functions-view-before-fix.png" alt-text="Screenshot of the Build Insights Functions view file."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time among functions based on their use of parallel compiler threads. For example, if two different threads are compiling two different functions simultaneously within a one-second period, each function's WCTR is recorded as 0.5 seconds. This reflects each function's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each function has on the overall build time in environments where multiple compilation activities occur simultaneously. + +The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function how roughly how many instructions were generated for each. + +You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation. + +You can search for a specific function by using the **Filter Functions** box. If a function's code generation time is too small, it doesn't appear in the **Functions** View. + +## Improve build time by adjusting function inlining + +In this example, the `performPhysicsCalculations` function is taking the most time to compile. + +:::image type="complex" source="./media/functions-view-before-fix.png" alt-text="Screenshot of the Build Insights Functions view."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +Investigating further, by selecting the chevron before that function, and then sorting the **Forceinline Size** column from highest to lowest, we see the biggest contributors to the problem. + +:::image type="complex" source="./media/functions-view-expanded.png" alt-text="Screenshot of the Build Insights Functions view with an expanded function."::: +performPhysicsCalculations() is expanded and shows a long list of functions that were inlined inside it. There are multiple instances of functions such as complexOperation(), recursiveHelper(), and sin() shown. The Forceinline Size column shows that complexOperation() is the largest inlined function at 315 instructions. recursiveHelper() has 119 instructions. Sin() has 75 instructions, but there are many more instances of it than the other functions. +:::image-end::: + +There are some larger inlined functions, such as `Vector2D::complexOperation()` and `Vector2D::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2d::sin(float)`, `Vector2d::cos(float)`, `Vector2D::power(float,int)`, and `Vector2D::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions. + +Looking at those functions in the source code, we see that execution time is going to be spent inside loops. For example, here's the code for `factorial()`: + +```cpp +static __forceinline T factorial(int n) +{ + T result = 1; + for (int i = 1; i <= n; ++i) { + for (int j = 0; j < i; ++j) { + result *= (i - j) / (T)(j + 1); + } + } + return result; +} +``` + +Perhaps the overall cost of calling this function is insignificant compared to the cost of the function itself. Making a function inline is most beneficial when the time it takes to call the function (pushing arguments on the stack, jumping to the function, popping return arguments, and returning from the function) is roughly similar to the time it takes to execute the function, and when the function is called a lot. When that's not the case, there may be diminishing returns on making it inline. We can try removing the `__forceinline` directive from it to see if it helps the build time. The code for `power`, `sin()` and `cos()` is similar in that the code consists of a loop that will execute many times. We can try removing the `__forceinline` directive from those functions as well. + +We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files may be dirty right now. + +The build time goes from 25.181 seconds to 13.376 seconds and the `performPhysicsCalculations` function doesn't show up anymore in the **Functions** view because it doesn't contribute enough to the build time to be counted. + +:::image type="complex" source="./media/functions-view-after-fix.png" alt-text="Screenshot of the 2D vector header file."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +The Diagnostics Session time is the overall time it took do the build plus any overhead for gathering the Build Insights data. + +The next step would be to profile the application to see if the performance of the application is negatively impacted by the change. If it is, we can selectively add `__forceinline` back as needed. + +## Navigate to the source code + +Double-click, right-click, or press **Enter** while on a file in the **Functions** view to open the source code for that file. + +:::image type="content" source="./media/functions-view-goto-file.png" alt-text="Screenshot of a right-click on a file in the Functions view. The menu option Go To Source File is highlighted."::: + +## Tips + +- You can **File** > **Save As** the ETL file to a more permanent location to keep a record of the build time. You can then compare it to future builds to see if your changes are improving build time. +- If you inadvertently close the Build Insights window, reopen it by finding the `.etl` file in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- To dig into the Build Insights data with Windows Performance Analyzer (WPA), click the **Open in WPA** button in the bottom right of the ETL window. +- Drag columns to change the order of the columns. For instance, you may prefer moving the **Time** column to be the first column. You can hide columns by right-clicking on the column header and deselecting the columns you don't want to see. +- The **Functions** view provides a filter box to find a function that you're interested in. It does partial matches on the name you provide. +- If you forget how to interpret what the **Functions** view is trying to show you, hover over the tab to see a tooltip that describes the view. If you hover over the **Functions** tab, the tooltip says: "View that shows statistics for functions where the children nodes are force-inlined functions." + +## Troubleshooting + +- If the Build Insights window doesn't appear, do a rebuild instead of a build. The Build Insights window doesn't appear if nothing actually builds; which may be the case if no files changed since the last build. +- If the Functions view doesn't show any functions, you may not be building with the right optimization settings. Ensure that you're building Release with full optimizations, as described in [Set build options](#set-build-options). Also, if a function's code generation time is too small, it doesn't appear in the list. + +## See also + +[Build Insights tips and tricks](build-insights-tips.md)\ +[Inline functions (C++)](../../cpp/inline-functions-cpp.md)\ +[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\ +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Troubleshoot header file impact on build time](build-insights-included-files-view.md)\ +[Functions View for Build Insights in Visual Studio 2022 17.8](https://devblogs.microsoft.com/cppblog/functions-view-for-build-insights-in-visual-studio-2022-17-8/)\ +[Tutorial: vcperf and Windows Performance Analyzer](vcperf-and-wpa.md)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights) diff --git a/docs/build-insights/tutorials/build-insights-included-files-view.md b/docs/build-insights/tutorials/build-insights-included-files-view.md new file mode 100644 index 0000000000..3563f96d71 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-included-files-view.md @@ -0,0 +1,188 @@ +--- +title: "Troubleshoot header file impact on build time" +description: "Tutorial on how to use Build Insights Includes Files and Includes Tree views to troubleshoot the impact of #include files on build time." +ms.date: 5/30/2024 +helpviewer_keywords: ["C++ Build Insights", "header file build time", "included files view", "include tree view", "#include analysis", "build time analysis"] +--- +# Troubleshoot header file impact on build time + +Use Build Insights **Included Files** and **Include Tree** views to troubleshoot the impact of `#include` files on C and C++ build times. + +## Prerequisites + +- Visual Studio 2022 17.8 or greater. +- C++ Build Insights is enabled by default if you install either the Desktop development with C++ workload using the Visual Studio installer: + +:::image type="complex" source="./media/installer-desktop-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Desktop development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +Or the Game development with C++ workload: + +:::image type="complex" source="./media/installer-gamedev-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Game development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +## Overview + +Build Insights, now integrated into Visual Studio, helps you optimize your build times--especially for large projects like triple-A games. When a large header file is parsed, and especially when it's repeatedly parsed, there's an impact on build time. + +Build Insights provides analytics in the **Included Files** view, which helps diagnose the impact of parsing `#include` files in your project. It displays the time it takes to parse each header file and a view of the relationships between header files. + +In this article, learn how to use the Build Insights **Included Files** and **Include Tree** views to identify the most expensive header files to parse and how to optimize build time by creating a precompiled header file. + +## Set build options + +Before gathering Build Insights data, set the build options for the type of build you want to measure. For example, if you're concerned about your x64 debug build time, set the build for **Debug** and **x64**: + +- In the **Solution Configurations** dropdown, choose **Debug**. +- In the **Solution Platforms** dropdown, choose **x64**. + + :::image type="complex" source="./media/build-options-debug.png" alt-text="Screenshot of the Solution Configuration dropdowns."::: + The Solution Configuration dropdown is shown. It has options for Debug, Release, and Configuration manager. The Solution Platform dropdown is set to x64. + :::image-end::: + +## Run Build Insights + +On a project of your choosing, and using the **Debug** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on \** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now. + +:::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected."::: + +When the build finishes, an Event Trace Log (ETL) file opens. It's saved in the folder pointed to by the Windows `TEMP` environment variable. The generated name is based on the collection time. + +## Included Files view + +The trace file shows the build time--which for this example was 16.404 seconds. The **Diagnostics Session** is the overall time taken to run the Build Insights session. Choose the **Included Files** tab. + +This view shows the time spent processing `#include` files. + +:::image type="complex" source="./media/included-files-before-fix.png" alt-text="Screenshot of the included files view."::: +In the file path column, several files with a fire icon are highlighted because they take over 10% of the build time to parse. winrtHeaders.h is the biggest one at 8.581 seconds or 52.3% of the 16.404-second build time. +:::image-end::: + +In the **File Path** column, some files have a fire icon next to them to indicate that they take up 10% or more of the build time. + +The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time it takes to parse files based on their use of parallel threads. For example, if two different threads are parsing two different files simultaneously within a one-second period, each file's WCTR is recorded as 0.5 seconds. This reflects each file's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each file has on the overall build time in environments where multiple compilation activities occur simultaneously. + +The **Parse Count** column shows how many time the header file was parsed. + +The first header file highlighted in this list is `winrtHeaders.h` It takes 8.581 seconds of the overall 16.404-second build time, or 52.3% of the build time. The next most expensive is `Windows.UI.Xaml.Interop.h`, and then `Windows.Xaml.h`. + +To see which file includes `winrtHeaders.h`, click the chevron next to it. The **Parse Count** column can be helpful by pointing out how many times a header file is included by other files. Perhaps a header file is included multiple times, which could be a sign that it's a good candidate for a precompiled header file or refactoring. + +The **Translation Unit** column shows which file was being processed when the included file was processed. In this example, `winrtHeaders.h` was included while `Grapher.cpp` was compiled: + +:::image type="complex" source="./media/included-files-translation-unit.png" alt-text="Screenshot of the Included Files view."::: +An example ETL file showing the includes files for a sample project. In the file path column, winrtHeaders.h is selected and expanded. It takes 8.219 seconds to build which is 50.1% of the build time. Its child node is Grapher.cpp, which is also listed as the translation unit." +:::image-end::: + +The translation unit column can help disambiguate which file was being compiled in cases where a header file is included many times and you want to find out where that happens the most. + +We know that `winrtHeaders.h` is expensive to parse, but we can learn more. + +## Include Tree view + +In this view, the children nodes are the files included by the parent node. This can help you understand the relationships between header files and identify opportunities to reduce the number of times a header file is parsed. + +Select the **Include Tree** tab in the ETL file to see the Include Tree view: + +:::image type="complex" source="./media/include-tree-view.png" alt-text="Screenshot of the Include Tree view."::: +Shows the include tree for a project. In the file path column, each file that includes other files is listed, along with how many files it includes and the time to parse it. +:::image-end::: + +In this view, the **File Path** column shows each file that includes other files. The **Include Count** lists how many files this header file includes. The time to parse this file is listed, and when expanded, lists the time to parse each individual header file that this header file includes. + +Earlier, we saw that parsing `winrtHeaders.h` is time consuming. In the **Filter Files** text box, if we enter `winrtHeaders.h`, we can filter the view to only the entries that contain `winrtHeaders.h` in the name. Clicking the chevron next to `winrtHeaders.h` shows which files it includes: + +:::image type="complex" source="./media/include-tree-view-expanded.png" alt-text="Screenshot of the expanded Include Tree view."::: +The file path column lists each file that includes other files, along with how many files it includes and the time it took to parse it. winrtHeaders.h is selected and expanded to show the files it includes. Windows.UI.Xaml.Interop.h is one of those files and is expanded to show Windows.UI.Xaml.Interop.h that is expanded to show the header files it includes. +:::image-end::: + +We see that `winrtHeaders.h` includes `Windows.UI.Xaml.Interop.h`. Remember from the **Included Files** view that this was also time consuming to parse. Click the chevron next to `Windows.UI.Xaml.Interop.h` to see that it includes `Windows.UI.Xaml.h`, which includes 21 other header files, two of which are also on the hot list. + +Having identified some of the most expensive header files to parse, and seeing that `winrtHeaders.h` is responsible for bringing them in, suggests that we can use a precompiled header to make including `winrtHeaders.h` faster. + +## Improve build time with precompiled headers + +Because we know from the **Included Files** view that `winrtHeaders.h` is time consuming to parse, and because we know from the **Include Tree** view that `winrtHeaders.h` includes several other header files that are time consuming to parse, we build a [Precompiled header file](../../build/creating-precompiled-header-files.md) (PCH) to speed that up by only parsing them once into a PCH. + +We add a `pch.h` to include `winrtHeaders.h`, which would look like this: + +```cpp +#ifndef CALC_PCH +#define CALC_PCH + +#include + +#endif // CALC_PCH +``` + +PCH files must be compiled before they can be used, so we add a file to the project, arbitrarily named `pch.cpp`, that includes `pch.h`. It contains one line: + +```cpp +#include "pch.h" +``` + +Then we set our project to use the PCH. That's done in project properties via **C/C++** > **Precompiled Headers** and setting **Precompiled Header** to **Use (/Yu)** and **Precompiled Header File** to **pch.h**. + +:::image type="complex" source="./media/precompiled-header-settings.png" alt-text="Screenshot of the project properties dialog with the Precompiled Headers settings open."::: +Precompiled Header is set to: Use (/Yu). The Precompiled Header File is set to pch.h. +:::image-end::: + +To use the PCH, we include it as the first line in the source files that use `winrtHeaders.h`. It must come before any other include files. Or, for simplicity, we could modify the project properties to include `pch.h` at the beginning of every file in the solution by setting the project property: **C/C++** > **Advanced** > **Forced Include File** to `pch.h`: + +:::image type="complex" source="./media/precompiled-header-settings-force-include.png" alt-text="Screenshot of the project properties dialog with the Advanced settings open."::: +Forced Include File is set to pch.h. +:::image-end::: + +Since the PCH includes `winrtHeaders.h`, we could remove `winrtHeaders.h` from all the files that currently include it. It's not strictly necessary because the compiler realizes that `winrtHeaders.h` is already included and doesn't parse it again. Some developers prefer to keep the `#include` in the source file for clarity, or in case the PCH is likely to be refactored and may not include that header file anymore. + +## Test the changes + +We first clean the project to make sure we're comparing building the same files as before. To clean just one project, right-click the project in the **Solution Explorer** and choose **Project only** > **Clean only \**. + +Because this project now uses a precompiled header (PCH), we don't want to measure the time spent building the PCH because that only happens once. We do this by loading the `pch.cpp` file and choosing **Ctrl+F7** to build just that file. We could also compile this file by right-clicking `pch.cpp` in the Solution Explorer and choosing `Compile`. + +Now we rerun Build Insights in the **Solution Explorer** by right-clicking the project and choosing **Project Only** > **Run Build Insights on Build**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Build**. We don't want **Rebuild** this time because that will rebuild the PCH, which we don't want to measure. We cleaned the project earlier, which means that a normal build compiles all the project files we want to measure. + +When the ETL files appear, we see that build time went from 16.404 seconds to 6.615 seconds. Put `winrtHeaders.h` into the filter box and nothing appears. This is because the time spent parsing it is now negligible since it's being pulled in by the precompiled header. + +:::image type="content" source="./media/included-files-after-fix.png" alt-text="Screenshot of the Include Tree pane in the trace file. winrtHeaders is no longer listed."::: + +This example uses precompiled headers because they're a common solution before C++20. However, starting with C++20, there are other, faster, less brittle, ways to include header files--such as header units and modules. For more information, see [Compare header units, modules, and precompiled headers](../../build/compare-inclusion-methods.md). + +## Navigate between views + +There are some navigation features for both the **Included Files** and **Include Tree** views: + +- Double-click a file (or press **Enter**) in either the **Included Files** or **Include Tree** to open the source code for that file. +- Right-click on a header file to find that file in the other view. For example, in the **Included File**s view, right-click on `winrtHeaders.h` and choose **Find in Include Tree** to see it in the **Include Tree** view. + +:::image type="content" source="./media/included-files-show-in-include-tree.png" alt-text="Screenshot of a right-click on a file in the Included Files view. The menu option Show in Include Tree View is highlighted."::: + +Or, you can right-click a file in the **Include Tree** view to jump to it in the **Included Files** view. + +## Tips + +- You can **File** > **Save As** the ETL file to a more permanent location to keep a record of the build time. You can then compare it to future builds to see if your changes are improving build time. +- If you inadvertently close the Build Insights window, reopen it by finding the `.etl` file in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- To dig into the Build Insights data with Windows Performance Analyzer (WPA), click the **Open in WPA** button in the bottom right of the ETL window. +- Drag columns to change the order of the columns. For instance, you may prefer moving the **Time** column to be the first column. You can hide columns by right-clicking on the column header and deselecting the columns you don't want to see. +- The **Included Files** and **Include Tree** views provide a filter box to find a header file that you're interested in. It does partial matches on the name you provide. +- Sometimes the parse time reported for a header file is different depending on which file includes it. This can be due to the interplay of different `#define`s that affect which parts of the header are expanded, file caching, and other system factors. +- If you forget what the **Included Files** or **Include Tree** view is trying to show you, hover over the tab to see a tooltip that describes the view. For example, if you hover over the **Include Tree** tab, the tooltip says: "View that shows include statistics for every file where the children nodes are the files included by the parent node." +- You may see cases (like `Windows.h`) where the aggregated duration of all the times for a header file is longer than the duration of the entire build. What's happening is that headers are being parsed on multiple threads at the same time. If two threads simultaneously spend one second parsing a header file, that's 2 seconds of build time even though only one second of wall clock time has gone by. For more information, see [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). + +## Troubleshooting + +- If the Build Insights window doesn't appear, do a rebuild instead of a build. The Build Insights window doesn't appear if nothing actually builds; which may be the case if no files changed since the last build. +- If a header file you're interested in doesn't appear in the **Included Files** or **Include Tree** views, it either didn't build or its build time isn't significant enough to be listed. + +## See also + +[Build Insights tips and tricks](build-insights-tips.md)\ +[Compare header units, modules, and precompiled headers](../../build/compare-inclusion-methods.md)\ +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\ +[Troubleshoot function inlining on build time](build-insights-function-view.md)\ +[vcperf and Windows Performance Analyzer](vcperf-and-wpa.md) \ No newline at end of file diff --git a/docs/build-insights/tutorials/build-insights-tips.md b/docs/build-insights/tutorials/build-insights-tips.md new file mode 100644 index 0000000000..d071aaddda --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-tips.md @@ -0,0 +1,79 @@ +--- +title: "Build Insights tips and tricks" +description: "Learn time-saving tips for using Build Insights." +ms.date: 1/8/2025 +author: tylermsft +ms.author: twhitney +ms.topic: article +helpviewer_keywords: ["C++ Build Insights tips and tricks"] +--- +# Build Insights tips and tricks + +Learn time-saving tips for using Build Insights. + +## Run Build Insights on selected files + +This feature requires Visual Studio 2022 17.12 or later. + +If you're working on a specific file or files, and want to see how they impact your build time, you can run Build Insights on just those files. This feature is useful when you want to focus on a subset of files in your project. + +To try it, in **Solution Explorer** select the files in your project you want to profile, right-click, and choose **Run Build Insights on Selected Files**: + + :::image type="content" source="./media/build-insights-run-on-selected-files.png" alt-text="A screenshot of files in the Solution Explorer. The context menu is open and the option to Run Build Insights on Selected Files is highlighted."::: + +## Filter Build Insights results + +This feature requires Visual Studio 2022 17.12 or later. + +If you have a large solution with many projects, you can filter the Build Insights results to see files only the projects you're interested in. This feature is useful when you want to focus on a subset of projects in your solution. + +To try it, click the filter button on the filter column header and select the projects you want to see results for: + + :::image type="complex" source="./media/build-insights-filter-by-project.png" alt-text="A screenshot of the Build Insights window with the Included Files tab open."::: + The filter button is selected and a list of projects appears. Checkboxes next to two projects are checked. + :::image-end::: + +You can also use file wildcards to filter results. The search is case-insensitive and you should use forward slashes (`/`) as path separators: + + :::image type="content" source="./media/build-insights-glob-filter.png" alt-text="A screenshot of the build insights filter dialog. There's a files to include text box and a files to exclude text box."::: + +This allows you to exclude files from a specific folder or only include files from a specific folder. For example, if your source is located at `C:\src\`, you could include files only from the renderer directory and its subdirectories by putting `C:/src/dev/renderer/**` into the **files to include** text box. Use forward slashes (`/`) as path separators. + +Here are some other examples: + +- All files in the renderer directory: `C:/src/dev/renderer/*` +- All files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**` +- All header files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**/*.h` + +For more examples, see the [online glob pattern tester](https://globster.xyz/). + +The filter you enter into either text box persists per solution. Filtering by wildcards isn't supported for CMAKE projects. + +## Save Build Insights reports to a designated folder + +This feature requires Visual Studio 2022 17.12 or later. + +Now you can designate a folder to automatically save Build Insight reports to so you can easily access them. + +To set the designated folder, go to **Tools** > **Options** > **C++ Build Insights** > **Trace Collection**. Set a path in the **Store Build Insights reports in this directory** textbox: + + :::image type="complex" source="./media/build-insights-reports-directory.png" alt-text="A screenshot of the options window."::: + In the left pane, Build Insights > Trace Collection is selected. In the collection settings, the checkbox for Store Build Insights reports in this directory is selected, and the directory text box contains the path c:\users\contoso\workspace as an example. + :::image-end::: + +Reports are automatically saved to this folder when you run Build Insights. If a path isn't set, the `TEMP` folder is used. + +## Get help about the Build Insight window + +This feature requires Visual Studio 2022 17.12 or later. + +To see a short description for the tabs in the Build Insights window, along with a link to the documentation for a detailed explanation, click the question mark icon in the Build Insights window: + + :::image type="content" source="./media/build-insights-view-explanations.png" alt-text="A screenshot of the Build Insights window with the view explanations button (a question mark in a circle) highlighted."::: + +## See also + +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights)\ +[Troubleshoot header file impact on build time](build-insights-included-files-view.md)\ +[Tutorial: Troubleshoot function inlining on build time](build-insights-function-view.md) diff --git a/docs/build-insights/tutorials/media/build-insights-filter-by-project.png b/docs/build-insights/tutorials/media/build-insights-filter-by-project.png new file mode 100644 index 0000000000..4a2f902081 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-filter-by-project.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-glob-filter.png b/docs/build-insights/tutorials/media/build-insights-glob-filter.png new file mode 100644 index 0000000000..98395c240f Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-glob-filter.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-rebuild-project.png b/docs/build-insights/tutorials/media/build-insights-rebuild-project.png new file mode 100644 index 0000000000..63ceed7705 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-rebuild-project.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-reports-directory.png b/docs/build-insights/tutorials/media/build-insights-reports-directory.png new file mode 100644 index 0000000000..e9c751814f Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-reports-directory.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png b/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png new file mode 100644 index 0000000000..1a5c0f8556 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-view-explanations.png b/docs/build-insights/tutorials/media/build-insights-view-explanations.png new file mode 100644 index 0000000000..3b33e677bc Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-view-explanations.png differ diff --git a/docs/build-insights/tutorials/media/build-options-debug.png b/docs/build-insights/tutorials/media/build-options-debug.png new file mode 100644 index 0000000000..156abb7646 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-options-debug.png differ diff --git a/docs/build-insights/tutorials/media/build-options-release.png b/docs/build-insights/tutorials/media/build-options-release.png new file mode 100644 index 0000000000..2fe4589daf Binary files /dev/null and b/docs/build-insights/tutorials/media/build-options-release.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-after-fix.png b/docs/build-insights/tutorials/media/functions-view-after-fix.png new file mode 100644 index 0000000000..9df70ef0b9 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-before-fix.png b/docs/build-insights/tutorials/media/functions-view-before-fix.png new file mode 100644 index 0000000000..109d81e391 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-expanded.png b/docs/build-insights/tutorials/media/functions-view-expanded.png new file mode 100644 index 0000000000..9f0483a4cf Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-expanded.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-goto-file.png b/docs/build-insights/tutorials/media/functions-view-goto-file.png new file mode 100644 index 0000000000..378c335781 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-goto-file.png differ diff --git a/docs/build-insights/tutorials/media/include-tree-view-expanded.png b/docs/build-insights/tutorials/media/include-tree-view-expanded.png new file mode 100644 index 0000000000..d011bb41ee Binary files /dev/null and b/docs/build-insights/tutorials/media/include-tree-view-expanded.png differ diff --git a/docs/build-insights/tutorials/media/include-tree-view.png b/docs/build-insights/tutorials/media/include-tree-view.png new file mode 100644 index 0000000000..629ad3f125 Binary files /dev/null and b/docs/build-insights/tutorials/media/include-tree-view.png differ diff --git a/docs/build-insights/tutorials/media/included-files-after-fix.png b/docs/build-insights/tutorials/media/included-files-after-fix.png new file mode 100644 index 0000000000..42691ef4b6 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/included-files-before-fix.png b/docs/build-insights/tutorials/media/included-files-before-fix.png new file mode 100644 index 0000000000..e4eee66cf0 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png b/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png new file mode 100644 index 0000000000..75df957eb5 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png differ diff --git a/docs/build-insights/tutorials/media/included-files-translation-unit.png b/docs/build-insights/tutorials/media/included-files-translation-unit.png new file mode 100644 index 0000000000..65ad65bcaa Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-translation-unit.png differ diff --git a/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png b/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png new file mode 100644 index 0000000000..152ce06514 Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png differ diff --git a/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png b/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png new file mode 100644 index 0000000000..3eaa8c2df1 Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png differ diff --git a/docs/build-insights/tutorials/media/max-optimization-setting.png b/docs/build-insights/tutorials/media/max-optimization-setting.png new file mode 100644 index 0000000000..78510f0af3 Binary files /dev/null and b/docs/build-insights/tutorials/media/max-optimization-setting.png differ diff --git a/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png b/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png new file mode 100644 index 0000000000..f53b2faf6a Binary files /dev/null and b/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png differ diff --git a/docs/build-insights/tutorials/media/precompiled-header-settings.png b/docs/build-insights/tutorials/media/precompiled-header-settings.png new file mode 100644 index 0000000000..4198430bce Binary files /dev/null and b/docs/build-insights/tutorials/media/precompiled-header-settings.png differ diff --git a/docs/build/adding-references-in-visual-cpp-projects.md b/docs/build/adding-references-in-visual-cpp-projects.md index 9d03daa364..17676d6d6b 100644 --- a/docs/build/adding-references-in-visual-cpp-projects.md +++ b/docs/build/adding-references-in-visual-cpp-projects.md @@ -4,7 +4,6 @@ title: "Consuming libraries and components in C++ projects" ms.date: 12/18/2020 f1_keywords: ["VC.Project.References"] helpviewer_keywords: ["Add References Dialog Box (C++)", ".NET Framework (C++), Add References Dialog Box"] -ms.assetid: 12b8f571-0f21-40b3-9404-5318a57e9cb5 --- # Consuming libraries and components @@ -12,19 +11,23 @@ C++ projects often need to call functions or access data in a binary file such a ## Consuming libraries downloaded via vcpkg -To consume a library that you have downloaded by using the **vcpkg** package manager, you can ignore the instructions below. See [vcpkg.io](https://vcpkg.io/) for more information. +To consume a library that you have downloaded by using the **vcpkg** package manager, you can ignore the instructions below. For more information, see: +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in MSBuild projects](/vcpkg/users/buildsystems/msbuild-integration) +- [Tutorial: Install and use packages with MSBuild in Visual Studio](/vcpkg/get_started/get-started-msbuild) ## Consuming static libraries If your static library project gets built in the same solution: -1. #include the header file(s) for the static library using quotation marks. In a typical solution, the path starts with `../`. IntelliSense will help you find it. +1. `#include` the header file(s) for the static library using quotation marks. In a typical solution, the path starts with `../`. IntelliSense will help you find it. 2. Add a reference to the static library project. Right-click on **References** under the application project node in **Solution Explorer** and choose **Add Reference**. If the static library isn't part of the solution: 1. Right-click on the application project node in **Solution Explorer** and then choose **Properties**. -2. In the **VC++ Directories** property page, add the path to the directory that contains the LIB file to **Library Paths**. Then, add the path to the library header file(s) to **Include Directories**. +2. In the **VC++ Directories** property page, add the path to the directory that contains the LIB file to **Library Directories**. Then, add the path to the library header file(s) to **Include Directories**. 3. In the **Linker > Input** property page, add the name of the LIB file to **Additional Dependencies**. ## Dynamic link libraries @@ -33,7 +36,7 @@ If the DLL gets built as part of the same solution as the application, follow th If the DLL isn't part of the application solution, you need: the DLL file, the header(s) with prototypes for the exported functions and classes, and a LIB file that provides the necessary linking information. -1. Copy the DLL to the output folder of your project, or to another folder in the standard Windows search path for DLLs. See [Dynamic-Link Library Search Order](/windows/win32/dlls/dynamic-link-library-search-order). +1. Copy the DLL to the output folder of your project, or to another folder in the standard Windows search path for DLLs. For more information, see [Dynamic-Link Library Search Order](/windows/win32/dlls/dynamic-link-library-search-order). 2. Follow steps 1-3 for static libraries to provide the paths to the headers and LIB file. ## COM objects @@ -158,5 +161,5 @@ The following properties exist on COM and .NET assembly references, and aren't m ## See also -[C++ project property page reference](reference/property-pages-visual-cpp.md)
+[C++ project property page reference](reference/property-pages-visual-cpp.md)\ [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md) diff --git a/docs/build/arm-exception-handling.md b/docs/build/arm-exception-handling.md index 65c46a9b95..f2f9b9a13e 100644 --- a/docs/build/arm-exception-handling.md +++ b/docs/build/arm-exception-handling.md @@ -166,7 +166,7 @@ When the packed unwind format is insufficient to describe the unwinding of a fun |0|20|*X* is a 1-bit field that indicates the presence (1) or absence (0) of exception data.| |0|21|*`E`* is a 1-bit field that indicates that information that describes a single epilogue is packed into the header (1) rather than requiring additional scope words later (0).| |0|22|*F* is a 1-bit field that indicates that this record describes a function fragment (1) or a full function (0). A fragment implies that there's no prologue and that all prologue processing should be ignored.| - |0|23-27|*Epilogue Count* is a 5-bit field that has two meanings, depending on the state of the *`E`* bit:

- If *`E`* is 0, this field is a count of the total number of exception scopes described in section 3. If more than 31 scopes exist in the function, then this field and the *Code Words* field must both be set to 0 to indicate that an extension word is required.
- If *`E`* is 1, this field specifies the index of the first unwind code that describes the only epilogue.| + |0|23-27|*Epilogue Count* is a 5-bit field that has two meanings, depending on the state of the *`E`* bit:

- If *`E`* is 0, this field is a count of the total number of epilogue scopes described in section 2. If more than 31 scopes exist in the function, then this field and the *Code Words* field must both be set to 0 to indicate that an extension word is required.
- If *`E`* is 1, this field specifies the index of the first unwind code that describes the only epilogue.| |0|28-31|*Code Words* is a 4-bit field that specifies the number of 32-bit words required to contain all of the unwind codes in section 4. If more than 15 words are required for more than 63 unwind code bytes, this field and the *Epilogue Count* field must both be set to 0 to indicate that an extension word is required.| |1|0-15|*Extended Epilogue Count* is a 16-bit field that provides more space for encoding an unusually large number of epilogues. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| |1|16-23|*Extended Code Words* is an 8-bit field that provides more space for encoding an unusually large number of unwind code words. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| diff --git a/docs/build/arm64-exception-handling.md b/docs/build/arm64-exception-handling.md index 2f6ce157a7..9bad5d2883 100644 --- a/docs/build/arm64-exception-handling.md +++ b/docs/build/arm64-exception-handling.md @@ -1,55 +1,55 @@ --- title: "ARM64 exception handling" description: Describes the exception handling conventions and data used by windows on ARM64. -ms.date: "11/19/2018" +ms.date: 01/13/2023 --- # ARM64 exception handling -Windows on ARM64 uses the same structured exception handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM64, and the language helpers used by code that's generated by the Microsoft ARM assembler and the MSVC compiler. +Windows on ARM64 uses the same structured exception handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM64. It illustrates the language helpers used by code that's generated by the Microsoft ARM assembler and the MSVC compiler. ## Goals and motivation The exception unwinding data conventions, and this description, are intended to: -1. Provide enough description to allow unwinding without code probing in all cases. +- Provide enough description to allow unwinding without code probing in all cases. - - Analyzing the code requires the code to be paged in. This prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging). + - Analyzing the code requires the code to be paged in. It prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging). - - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode. + - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode. - - If unwinding can't be fully described through the use of unwind codes, then in some cases it must fall back to instruction decoding. This increases the overall complexity, and ideally should be avoided. + - If unwinding can't be fully described by using unwind codes, then in some cases it must fall back to instruction decoding. Instruction decoding increases the overall complexity, and ideally should be avoided. -1. Support unwinding in mid-prolog and mid-epilog. +- Support unwinding in mid-prolog and mid-epilog. - - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence. + - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence. -1. Take up a minimal amount of space. +- Take up a minimal amount of space. - - The unwind codes must not aggregate to significantly increase the binary size. + - The unwind codes must not aggregate to significantly increase the binary size. - - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary. + - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary. ## Assumptions These assumptions are made in the exception handling description: -1. Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results. +- Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results. -1. Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data. +- Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data. -1. There's no conditional code in epilogs. +- There's no conditional code in epilogs. -1. Dedicated frame pointer register: If the sp is saved in another register (x29) in the prolog, that register remains untouched throughout the function. It means the original sp may be recovered at any time. +- Dedicated frame pointer register: If the `sp` is saved in another register (`x29`) in the prolog, that register remains untouched throughout the function. It means the original `sp` may be recovered at any time. -1. Unless the sp is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. +- Unless the `sp` is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. -1. The stack frame layout is organized as described in the next section. +- The stack frame layout is organized as described in the next section. ## ARM64 stack frame layout ![Diagram that shows the stack frame layout for functions.](media/arm64-exception-handling-stack-frame.png "stack frame layout") -For frame chained functions, the fp and lr pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (x29) or stack pointer (sp). However, for `alloca` functions, it must be chained, and x29 must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding alloca area). `#localsz` and `#outsz` denote local area size (including the save area for the \ pair) and outgoing parameter size, respectively. +For frame chained functions, the `fp` and `lr` pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (`x29`) or stack pointer (`sp`). However, for `alloca` functions, it must be chained, and `x29` must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding `alloca` area). `#localsz` and `#outsz` denote local area size (including the save area for the `` pair) and outgoing parameter size, respectively. 1. Chained, #localsz \<= 512 @@ -59,7 +59,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp x0,x1,[sp,#32] // home params (optional) stp x2,x3,[sp,#48] stp x4,x5,[sp,#64] - stp x6,x7,[sp,#72] + stp x6,x7,[sp,#82] stp x29,lr,[sp,#-localsz]! // save at bottom of local area mov x29,sp // x29 points to bottom of local sub sp,sp,#outsz // (optional for #outsz != 0) @@ -73,13 +73,13 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp x0,x1,[sp,#32] // home params (optional) stp x2,x3,[sp,#48] stp x4,x5,[sp,#64] - stp x6,x7,[sp,#72] + stp x6,x7,[sp,#82] sub sp,sp,#(localsz+outsz) // allocate remaining frame stp x29,lr,[sp,#outsz] // save at bottom of local area add x29,sp,#outsz // setup x29 points to bottom of local area ``` -1. Unchained, leaf functions (lr unsaved) +1. Unchained, leaf functions (`lr` unsaved) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -90,9 +90,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - All locals are accessed based on SP. \ points to the previous frame. For frame size \<= 512, the "sub sp, ..." can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above, and saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. + All locals are accessed based on `sp`. `` points to the previous frame. For frame size \<= 512, the `sub sp, ...` can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above. And, saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. -1. Unchained, non-leaf functions (lr is saved in Int saved area) +1. Unchained, non-leaf functions (saves `lr` in Int saved area) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -114,7 +114,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - Only x19 saved: + Only `x19` saved: ```asm sub sp,sp,#16 // reg save area allocation* @@ -122,9 +122,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-16) // allocate the remaining local area ``` - \* The reg save area allocation isn't folded into the stp because a pre-indexed reg-lr stp can't be represented with the unwind codes. + \* The reg save area allocation isn't folded into the `stp` because a pre-indexed reg-lr `stp` can't be represented with the unwind codes. - All locals are accessed based on SP. \ points to the previous frame. + All locals are accessed based on `sp`. `` points to the previous frame. 1. Chained, #framesz \<= 512, #outsz = 0 @@ -135,9 +135,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp d8,d9,[sp,#(framesz-16)] // save FP pair ``` - Compared to the first prolog example above, the advantage here is that all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on sp that prevents instruction level parallelism. + Compared to the first prolog example above, this example has an advantage: all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on `sp` that prevents instruction level parallelism. -1. Chained, frame size > 512 (optional for functions without alloca) +1. Chained, frame size > 512 (optional for functions without `alloca`) ```asm stp x29,lr,[sp,#-80]! // pre-indexed, save @@ -149,7 +149,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - For optimization purpose, x29 can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on SP. + For optimization purpose, `x29` can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on `sp`. 1. Chained, frame size > 4K, with or without alloca(), @@ -176,11 +176,11 @@ For frame chained functions, the fp and lr pair can be saved at any position in ## ARM64 exception handling information -### .pdata records +### `.pdata` records -The .pdata records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, do not require a .pdata record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from LR to move up to the caller. +The `.pdata` records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, don't require a `.pdata` record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from `lr` to move up to the caller. -Each .pdata record for ARM64 is 8 bytes in length. The general format of each record places the 32-bit RVA of the function start in the first word, followed by a second word that contains either a pointer to a variable-length .xdata block, or a packed word describing a canonical function unwinding sequence. +Each `.pdata` record for ARM64 is 8 bytes in length. The general format of each record places the 32-bit RVA of the function start in the first word, followed by a second word that contains either a pointer to a variable-length `.xdata` block, or a packed word describing a canonical function unwinding sequence. ![.pdata record layout.](media/arm64-exception-handling-pdata-record.png ".pdata record layout") @@ -188,29 +188,29 @@ The fields are as follows: - **Function Start RVA** is the 32-bit RVA of the start of the function. -- **Flag** is a 2-bit field that indicates how to interpret the remaining 30 bits of the second .pdata word. If **Flag** is 0, then the remaining bits form an **Exception Information RVA** (with the two lowest bits implicitly 0). If **Flag** is non-zero, then the remaining bits form a **Packed Unwind Data** structure. +- **Flag** is a 2-bit field that indicates how to interpret the remaining 30 bits of the second `.pdata` word. If **Flag** is 0, then the remaining bits form an **Exception Information RVA** (with the two lowest bits implicitly 0). If **Flag** is non-zero, then the remaining bits form a **Packed Unwind Data** structure. -- **Exception Information RVA** is the address of the variable-length exception information structure, stored in the .xdata section. This data must be 4-byte aligned. +- **Exception Information RVA** is the address of the variable-length exception information structure, stored in the `.xdata` section. This data must be 4-byte aligned. -- **Packed Unwind Data** is a compressed description of the operations needed to unwind from a function, assuming a canonical form. In this case, no .xdata record is required. +- **Packed Unwind Data** is a compressed description of the operations needed to unwind from a function, assuming a canonical form. In this case, no `.xdata` record is required. -### .xdata records +### `.xdata` records -When the packed unwind format is insufficient to describe the unwinding of a function, a variable-length .xdata record must be created. The address of this record is stored in the second word of the .pdata record. The format of the .xdata is a packed variable-length set of words: +When the packed unwind format is insufficient to describe the unwinding of a function, a variable-length `.xdata` record must be created. The address of this record is stored in the second word of the `.pdata` record. The format of the `.xdata` is a packed variable-length set of words: ![.xdata record layout.](media/arm64-exception-handling-xdata-record.png ".xdata record layout") This data is broken into four sections: -1. A 1 or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: +1. A 1-word or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: - a. **Function Length** is an 18-bit field. It indicates the total length of the function in bytes, divided by 4. If a function is larger than 1M, then multiple .pdata and .xdata records must be used to describe the function. For more information, see the [Large functions](#large-functions) section. + a. **Function Length** is an 18-bit field. It indicates the total length of the function in bytes, divided by 4. If a function is larger than 1M, then multiple `.pdata` and `.xdata` records must be used to describe the function. For more information, see the [Large functions](#large-functions) section. - b. **Vers** is a 2-bit field. It describes the version of the remaining .xdata. Currently, only version 0 is defined, so values of 1-3 aren't permitted. + b. **Vers** is a 2-bit field. It describes the version of the remaining `.xdata`. Currently, only version 0 is defined, so values of 1-3 aren't permitted. c. **X** is a 1-bit field. It indicates the presence (1) or absence (0) of exception data. - d. **E** is a 1-bit field. It indicates that information describing a single epilog is packed into the header (1) rather than requiring additional scope words later (0). + d. **E** is a 1-bit field. It indicates that information describing a single epilog is packed into the header (1) rather than requiring more scope words later (0). e. **Epilog Count** is a 5-bit field that has two meanings, depending on the state of **E** bit: @@ -218,11 +218,11 @@ This data is broken into four sections: 2. If **E** is 1, then this field specifies the index of the first unwind code that describes the one and only epilog. - f. **Code Words** is a 5-bit field that specifies the number of 32-bit words needed to contain all of the unwind codes in section 3. If more than 31 words are required (that is, if there are more than 124 unwind code bytes), then this field must be 0 to indicate that an extension word is required. + f. **Code Words** is a 5-bit field that specifies the number of 32-bit words needed to contain all of the unwind codes in section 3. If more than 31 words (that is, 124 unwind codes) are required, then this field must be 0 to indicate that an extension word is required. g. **Extended Epilog Count** and **Extended Code Words** are 16-bit and 8-bit fields, respectively. They provide more space for encoding an unusually large number of epilogs, or an unusually large number of unwind code words. The extension word that contains these fields is only present if both the **Epilog Count** and **Code Words** fields in the first header word are 0. -1. If **Epilog Count** isn't zero, a list of information about epilog scopes, packed one to a word, comes after the header and optional extended header. They're stored in order of increasing starting offset. Each scope contains the following bits: +1. If the count of epilogs isn't zero, a list of information about epilog scopes, packed one to a word, comes after the header and optional extended header. They're stored in order of increasing starting offset. Each scope contains the following bits: a. **Epilog Start Offset** is an 18-bit field that has the offset in bytes, divided by 4, of the epilog relative to the start of the function. @@ -230,11 +230,11 @@ This data is broken into four sections: c. **Epilog Start Index** is a 10-bit field (2 more bits than **Extended Code Words**). It indicates the byte index of the first unwind code that describes this epilog. -1. After the list of epilog scopes comes an array of bytes that contain unwind codes, described in detail in a later section. This array is padded at the end to the nearest full word boundary. Unwind codes are written to this array. They start with the one closest to the body of the function, and move towards the edges of the function. The bytes for each unwind code are stored in big-endian order so they can be fetched directly, starting with the most significant byte first, which identifies the operation and the length of the rest of the code. +1. After the list of epilog scopes comes an array of bytes that contain unwind codes, described in detail in a later section. This array is padded at the end to the nearest full word boundary. Unwind codes are written to this array. They start with the one closest to the body of the function, and move towards the edges of the function. The bytes for each unwind code are stored in big-endian order so the most significant byte gets fetched first, which identifies the operation and the length of the rest of the code. 1. Finally, after the unwind code bytes, if the **X** bit in the header was set to 1, comes the exception handler information. It consists of a single **Exception Handler RVA** that provides the address of the exception handler itself. It's followed immediately by a variable-length amount of data required by the exception handler. -The .xdata record is designed so it's possible to fetch the first 8 bytes, and use them to compute the full size of the record, minus the length of the variable-sized exception data that follows. The following code snippet computes the record size: +The `.xdata` record is designed so it's possible to fetch the first 8 bytes, and use them to compute the full size of the record, minus the length of the variable-sized exception data that follows. The following code snippet computes the record size: ```cpp ULONG ComputeXdataSize(PULONG Xdata) @@ -267,68 +267,86 @@ ULONG ComputeXdataSize(PULONG Xdata) } ``` -Although the prolog and each epilog has its own index into the unwind codes, the table is shared between them. It's entirely possible (and not altogether uncommon) that they can all share the same codes. (For an example, see Example 2 in the [Examples](#examples) section.) Compiler writers should optimize for this case, in particular, because the largest index that can be specified is 255, which limits the total number of unwind codes for a particular function. +Although the prolog and each epilog has its own index into the unwind codes, the table is shared between them. It's entirely possible (and not altogether uncommon) that they can all share the same codes. (For an example, see Example 2 in the [Examples](#examples) section.) Compiler writers should optimize for this case in particular. It's because the largest index that can be specified is 255, which limits the total number of unwind codes for a particular function. ### Unwind codes -The array of unwind codes is pool of sequences that describe exactly how to undo the effects of the prolog, stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the lr register. And, all non-volatile registers are restored to their values at the time the function was called. +The array of unwind codes is a pool of sequences that describe exactly how to undo the effects of the prolog. They're stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the `lr` register. And, all non-volatile registers are restored to their values at the time the function was called. If exceptions were guaranteed to only ever occur within a function body, and never within a prolog or any epilog, then only a single sequence would be necessary. However, the Windows unwinding model requires that code can unwind from within a partially executed prolog or epilog. To meet this requirement, the unwind codes have been carefully designed so they unambiguously map 1:1 to each relevant opcode in the prolog and epilog. This design has several implications: -1. By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog. - -1. By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. Then we can execute the rest of a sequence to complete the partially executed unwind done by the epilog. - -1. By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. Then we can execute the rest of the sequence to undo only those parts of the prolog that have completed execution. - -The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack. Totally there are 21 unwind code. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. - -|Unwind code|Bits and interpretation| -|-|-| -|`alloc_s`|000xxxxx: allocate small stack with size \< 512 (2^5 * 16).| -|`save_r19r20_x`| 001zzzzz: save \ pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | -|`save_fplr`| 01zzzzzz: save \ pair at `[sp+#Z*8]`, offset \<= 504. | -|`save_fplr_x`| 10zzzzzz: save \ pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`alloc_m`| 11000xxx'xxxxxxxx: allocate large stack with size \< 16k (2^11 * 16). | -|`save_regp`| 110010xx'xxzzzzzz: save x(19+#X) pair at `[sp+#Z*8]`, offset \<= 504 | -|`save_regp_x`| 110011xx'xxzzzzzz: save pair x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`save_reg`| 110100xx'xxzzzzzz: save reg x(19+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_reg_x`| 1101010x'xxxzzzzz: save reg x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | -|`save_lrpair`| 1101011x'xxzzzzzz: save pair \ at `[sp+#Z*8]`, offset \<= 504 | -|`save_fregp`| 1101100x'xxzzzzzz: save pair d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_fregp_x`| 1101101x'xxzzzzzz: save pair d(8+#X), at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`save_freg`| 1101110x'xxzzzzzz: save reg d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_freg_x`| 11011110'xxxzzzzz: save reg d(8+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | -|`alloc_l`| 11100000'xxxxxxxx'xxxxxxxx'xxxxxxxx: allocate large stack with size \< 256M (2^24 *16) | -|`set_fp`| 11100001: set up x29: with: `mov x29,sp` | -|`add_fp`| 11100010'xxxxxxxx: set up x29 with: `add x29,sp,#x*8` | -|`nop`| 11100011: no unwind operation is required. | -|`end`| 11100100: end of unwind code. Implies ret in epilog. | -|`end_c`| 11100101: end of unwind code in current chained scope. | -|`save_next`| 11100110: save next non-volatile Int or FP register pair. | -| | 11100111: reserved | -| | 11101xxx: reserved for custom stack cases below only generated for asm routines | -| | 11101000: Custom stack for MSFT_OP_TRAP_FRAME | -| | 11101001: Custom stack for MSFT_OP_MACHINE_FRAME | -| | 11101010: Custom stack for MSFT_OP_CONTEXT | -| | 11101100: Custom stack for MSFT_OP_CLEAR_UNWOUND_TO_CALL | -| | 1111xxxx: reserved | - -In instructions with large values covering multiple bytes, the most significant bits are stored first. This design makes it possible to find the total size in bytes of the unwind code by looking up only the first byte of the code. Since each unwind code is exactly mapped to an instruction in a prolog or epilog, you can compute the size of the prolog or epilog. You can walk from the start of the sequence to the end, and use a lookup table or similar device to determine how long the corresponding opcode is. - -Post-indexed offset addressing isn't allowed in a prolog. All offset ranges (#Z) match the encoding of STP/STR addressing except `save_r19r20_x`, in which 248 is sufficient for all save areas (10 Int registers + 8 FP registers + 8 input registers). - -`save_next` must follow a save for Int or FP volatile register pair: `save_regp`, `save_regp_x`, `save_fregp`, `save_fregp_x`, `save_r19r20_x`, or another `save_next`. It saves the next register pair at the next 16-byte slot in "growing up" order. A `save_next` refers to the first FP register pair when it follows the `save-next` that denotes the last Int register pair. - -Since the size of regular return and jump instructions are the same, there's no need of a separated `end` unwind code for tail-call scenarios. - -`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind code ended with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region ("phantom" prolog). More details and examples are described in the section below. +- By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog. + +- By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. We can execute the rest of a sequence to complete the partially executed unwind done by the epilog. + +- By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. We can execute the rest of the sequence to undo only those parts of the prolog that have completed execution. + +The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack (`alloc_l`). There are 22 unwind codes in total. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. + +| Unwind code | Bits and interpretation | +|--|--| +| `alloc_s` | 000xxxxx: allocate small stack with size \< 512 (2^5 * 16). | +| `save_r19r20_x` | 001zzzzz: save `` pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | +| `save_fplr` | 01zzzzzz: save `` pair at `[sp+#Z*8]`, offset \<= 504. | +| `save_fplr_x` | 10zzzzzz: save `` pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `alloc_m` | 11000xxx'xxxxxxxx: allocate large stack with size \< 32K (2^11 * 16). | +| `save_regp` | 110010xx'xxzzzzzz: save `x(19+#X)` pair at `[sp+#Z*8]`, offset \<= 504 | +| `save_regp_x` | 110011xx'xxzzzzzz: save pair `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_reg` | 110100xx'xxzzzzzz: save reg `x(19+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_reg_x` | 1101010x'xxxzzzzz: save reg `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `save_lrpair` | 1101011x'xxzzzzzz: save pair `` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp` | 1101100x'xxzzzzzz: save pair `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp_x` | 1101101x'xxzzzzzz: save pair `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_freg` | 1101110x'xxzzzzzz: save reg `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_freg_x` | 11011110'xxxzzzzz: save reg `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `alloc_z` | 11011111'zzzzzzzz: allocate stack with size `z * SVE-VL` | +| `alloc_l` | 11100000'xxxxxxxx'xxxxxxxx'xxxxxxxx: allocate large stack with size \< 256M (2^24 * 16) | +| `set_fp` | 11100001: set up `x29` with `mov x29,sp` | +| `add_fp` | 11100010'xxxxxxxx: set up `x29` with `add x29,sp,#x*8` | +| `nop` | 11100011: no unwind operation is required. | +| `end` | 11100100: end of unwind code. Implies `ret` in epilog. | +| `end_c` | 11100101: end of unwind code in current chained scope. | +| `save_next` | 11100110: save next register pair. | +| `save_any_xreg` | 11100111'0pxrrrrr'00oooooo: save register(s)
  • `p`: 0/1 => single `X(#r)` vs pair `X(#r)` + `X(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16, if x=1 or p=1, else `o` * 8
(Windows >= 11 required) | +| `save_any_dreg` | 11100111'0pxrrrrr'01oooooo: save register(s)
  • `p`: 0/1 => single `D(#r)` vs pair `D(#r)` + `D(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16, if x=1 or p=1, else `o` * 8
(Windows >= 11 required) | +| `save_any_qreg` | 11100111'0pxrrrrr'10oooooo: save register(s)
  • `p`: 0/1 => single `Q(#r)` vs pair `Q(#r)` + `Q(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16
(Windows >= 11 required) | +| `save_zreg` | 11100111'0oo0rrrr'11oooooo: save reg `Z(#r+8)` at `[sp + #o * VL]`, (`Z8` through `Z23`) +| `save_preg` | 11100111'0oo1rrrr'11oooooo: save reg `P(#r)` at `[sp + #o * (VL / 8)]`, (`P4` through `P15`; `r` values `[0, 3]` are reserved) +| | 11100111'1yyyyyyy': reserved | +| | 11101xxx: reserved for custom stack cases below only generated for asm routines | +| | 11101000: Custom stack for `MSFT_OP_TRAP_FRAME` | +| | 11101001: Custom stack for `MSFT_OP_MACHINE_FRAME` | +| | 11101010: Custom stack for `MSFT_OP_CONTEXT` | +| | 11101011: Custom stack for `MSFT_OP_EC_CONTEXT` | +| | 11101100: Custom stack for `MSFT_OP_CLEAR_UNWOUND_TO_CALL` | +| | 11101101: reserved | +| | 11101110: reserved | +| | 11101111: reserved | +| | 11110xxx: reserved | +| | 11111000'yyyyyyyy : reserved | +| | 11111001'yyyyyyyy'yyyyyyyy : reserved | +| | 11111010'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| | 11111011'yyyyyyyy'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| `pac_sign_lr` | 11111100: sign the return address in `lr` with `pacibsp` | +| | 11111101: reserved | +| | 11111110: reserved | +| | 11111111: reserved | + +In instructions with large values covering multiple bytes, the most significant bits are stored first. This design makes it possible to find the total size in bytes of the unwind code by looking up only the first byte of the code. Since each unwind code is exactly mapped to an instruction in a prolog or epilog, you can compute the size of the prolog or epilog. Walk from the sequence start to the end, and use a lookup table or similar device to determine the length of the corresponding opcode. + +Post-indexed offset addressing isn't allowed in a prolog. All offset ranges (#Z) match the encoding of `stp`/`str` addressing except `save_r19r20_x`, in which 248 is sufficient for all save areas (10 Int registers + 8 FP registers + 8 input registers). + +`save_next` must follow a save for a register pair: `save_regp`, `save_regp_x`, `save_fregp`, `save_fregp_x`, `save_r19r20_x`, or another `save_next`. It can also be used in conjunction with `save_any_xreg`, `save_any_dreg` or `save_any_qreg` but only when `p = 1`. It saves the next register pair in numerically increasing order to the next stack space. `save_next` must not be used beyond the last register of the same kind. + +Since the sizes of regular return and jump instructions are the same, there's no need for a separated `end` unwind code in tail-call scenarios. + +`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind codes ending with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region (a "phantom" prolog). More details and examples are described in the section below. ### Packed unwind data -For functions whose prologs and epilogs follow the canonical form described below, packed unwind data can be used. It eliminates the need for an .xdata record entirely, and significantly reduces the cost of providing unwind data. The canonical prologs and epilogs are designed to meet the common requirements of a simple function: One that doesn't require an exception handler, and which does its setup and teardown operations in a standard order. +For functions whose prologs and epilogs follow the canonical form described below, packed unwind data can be used. It eliminates the need for an `.xdata` record entirely, and significantly reduces the cost of providing unwind data. The canonical prologs and epilogs are designed to meet the common requirements of a simple function: One that doesn't require an exception handler, and which does its setup and teardown operations in a standard order. -The format of a .pdata record with packed unwind data looks like this: +The format of a `.pdata` record with packed unwind data looks like this: ![.pdata record with packed unwind data.](media/arm64-exception-handling-packed-unwind-data.png ".pdata record with packed unwind data") @@ -336,57 +354,60 @@ The fields are as follows: - **Function Start RVA** is the 32-bit RVA of the start of the function. - **Flag** is a 2-bit field as described above, with the following meanings: - - 00 = packed unwind data not used; remaining bits point to an .xdata record + - 00 = packed unwind data not used; remaining bits point to an `.xdata` record - 01 = packed unwind data used with a single prolog and epilog at the beginning and end of the scope - 10 = packed unwind data used for code without any prolog and epilog. Useful for describing separated function segments - 11 = reserved. -- **Function Length** is an 11-bit field providing the length of the entire function in bytes, divided by 4. If the function is larger than 8k, a full .xdata record must be used instead. -- **Frame Size** is a 9-bit field indicating the number of bytes of stack that is allocated for this function, divided by 16. Functions that allocate greater than (8k-16) bytes of stack must use a full .xdata record. It includes the local variable area, outgoing parameter area, callee-saved Int and FP area, and home parameter area, but excludes the dynamic allocation area. +- **Function Length** is an 11-bit field providing the length of the entire function in bytes, divided by 4. If the function is larger than 8k, a full `.xdata` record must be used instead. +- **Frame Size** is a 9-bit field indicating the number of bytes of stack that is allocated for this function, divided by 16. Functions that allocate greater than (8k-16) bytes of stack must use a full `.xdata` record. It includes the local variable area, outgoing parameter area, callee-saved Int and FP area, and home parameter area. It excludes the dynamic allocation area. - **CR** is a 2-bit flag indicating whether the function includes extra instructions to set up a frame chain and return link: - - 00 = unchained function, \ pair is not saved in stack. - - 01 = unchained function, \ is saved in stack - - 10 = reserved; - - 11 = chained function, a store/load pair instruction is used in prolog/epilog \ -- **H** is a 1-bit flag indicating whether the function homes the integer parameter registers (x0-x7) by storing them at the very start of the function. (0=does not home registers, 1=homes registers). + - 00 = unchained function, `` pair isn't saved in stack + - 01 = unchained function, `` is saved in stack + - 10 = chained function with a `pacibsp` signed return address + - 11 = chained function, a store/load pair instruction is used in prolog/epilog `` +- **H** is a 1-bit flag indicating whether the function homes the integer parameter registers (x0-x7) by storing them at the very start of the function. (0 = doesn't home registers, 1 = homes registers). - **RegI** is a 4-bit field indicating the number of non-volatile INT registers (x19-x28) saved in the canonical stack location. - **RegF** is a 3-bit field indicating the number of non-volatile FP registers (d8-d15) saved in the canonical stack location. (RegF=0: no FP register is saved; RegF>0: RegF+1 FP registers are saved). Packed unwind data can't be used for function that save only one FP register. -Canonical prologs that fall into categories 1, 2 (without outgoing parameter area), 3 and 4 in section above can be represented by packed unwind format. The epilogs for canonical functions follow a similar form, except **H** has no effect, the `set_fp` instruction is omitted, and the order of steps and the instructions in each step are reversed in the epilog. The algorithm for packed .xdata follows these steps, detailed in the following table: +Canonical prologs that fall into categories 1, 2 (without outgoing parameter area), 3 and 4 in section above can be represented by packed unwind format. The epilogs for canonical functions follow a similar form, except **H** has no effect, the `set_fp` instruction is omitted, and the order of steps and the instructions in each step are reversed in the epilog. The algorithm for packed `.xdata` follows these steps, detailed in the following table: Step 0: Pre-compute of the size of each area. -Step 1: Save Int callee-saved registers. +Step 1: Sign the return address. -Step 2: This step is specific for type 4 in early sections. lr is saved at the end of Int area. +Step 2: Save Int callee-saved registers. -Step 3: Save FP callee-saved registers. +Step 3: This step is specific for type 4 in early sections. `lr` is saved at the end of Int area. -Step 4: Save input arguments in the home parameter area. +Step 4: Save FP callee-saved registers. -Step 5: Allocate remaining stack, including local area, \ pair, and outgoing parameter area. 5a corresponds to canonical type 1. 5b and 5c are for canonical type 2. 5d and 5e are for both type 3 and type 4. +Step 5: Save input arguments in the home parameter area. -Step #|Flag values|# of instructions|Opcode|Unwind Code --|-|-|-|- -0|||`#intsz = RegI * 8;`
`if (CR==01) #intsz += 8; // lr`
`#fpsz = RegF * 8;`
`if(RegF) #fpsz += 8;`
`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`
`#locsz = #famsz - #savsz`| -1|0 < **RegI** <= 10|RegI / 2 + **RegI** % 2|`stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...`|`save_regp_x`
`save_regp`
`...` -2|**CR**==01*|1|`str lr,[sp,#(intsz-8)]`\*|`save_reg` -3|0 < **RegF** <=7|(RegF + 1) / 2 +
(RegF + 1) % 2)|`stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]`|`save_fregp`
`...`
`save_freg` -4|**H** == 1|4|`stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]`|`nop`
`nop`
`nop`
`nop` -5a|**CR** == 11 && #locsz
<= 512|2|`stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\*|`save_fplr_x`
`set_fp` -5b|**CR** == 11 &&
512 < #locsz <= 4080|3|`sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0`|`alloc_m`
`save_fplr`
`set_fp` -5c|**CR** == 11 && #locsz > 4080|4|`sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0`|`alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` -5d|(**CR** == 00 \|\| **CR**==01) &&
#locsz <= 4080|1|`sub sp,sp,#locsz`|`alloc_s`/`alloc_m` -5e|(**CR** == 00 \|\| **CR**==01) &&
#locsz > 4080|2|`sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`|`alloc_m`
`alloc_s`/`alloc_m` +Step 6: Allocate remaining stack, including local area, `` pair, and outgoing parameter area. 6a corresponds to canonical type 1. 6b and 6c are for canonical type 2. 6d and 6e are for both type 3 and type 4. -\* If **CR** == 01 and **RegI** is an odd number, Step 2 and last save_rep in step 1 are merged into one save_regp. +| Step # | Flag values | # of instructions | Opcode | Unwind code | +|--|--|--|--|--| +| 0 | | | `#intsz = RegI * 8;`
`if (CR==01) #intsz += 8; // lr`
`#fpsz = RegF * 8;`
`if(RegF) #fpsz += 8;`
`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`
`#locsz = #famsz - #savsz` | +| 1 | **CR** == 10 | 1 | `pacibsp` | `pac_sign_lr` | +| 2 | 0 < **RegI** <= 10 | **RegI** / 2 +
**RegI** % 2 | `stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...` | `save_regp_x`
`save_regp`
`...` | +| 3 | **CR** == 01\* | 1 | `str lr,[sp,#(intsz-8)]`\* | `save_reg` | +| 4 | 0 < **RegF** <= 7 | (**RegF** + 1) / 2 +
(**RegF** + 1) % 2) | `stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]` | `save_fregp`
`...`
`save_freg` | +| 5 | **H** == 1 | 4 | `stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]` | `nop`
`nop`
`nop`
`nop` | +| 6a | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` <= 512 | 2 | `stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\* | `save_fplr_x`
`set_fp` | +| 6b | (**CR** == 10 \|\| **CR** == 11) &&
512 < `#locsz` <= 4080 | 3 | `sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`save_fplr`
`set_fp` | +| 6c | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` > 4080 | 4 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` | +| 6d | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` <= 4080 | 1 | `sub sp,sp,#locsz` | `alloc_s`/`alloc_m` | +| 6e | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` > 4080 | 2 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)` | `alloc_m`
`alloc_s`/`alloc_m` | -\*\* If **RegI** == **CR** == 0, and **RegF** != 0, the first stp for the floating-point does the predecrement. +\* If **CR** == 01 and **RegI** is an odd number, step 3 and the last `save_reg` in step 2 are merged into one `save_regp`. -\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of sp from x29. +\*\* If **RegI** == **CR** == 0, and **RegF** != 0, the first `stp` for the floating-point does the predecrement. + +\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of `sp` from `x29`. ### Unwinding partial prologs and epilogs -The most common unwinding situation is one where the exception or call occurred in the body of the function, away from the prolog and all epilogs. In this situation, unwinding is straightforward: the unwinder simply begins executing the codes in the unwind array beginning at index 0 and continuing until an end opcode is detected. +In the most common unwinding situations, the exception or call occurs in the body of the function, away from the prolog and all epilogs. In these situations, unwinding is straightforward: the unwinder simply executes the codes in the unwind array. It begins at index 0 and continues until an `end` opcode is detected. It's more difficult to correctly unwind in the case where an exception or interrupt occurs while executing a prolog or epilog. In these situations, the stack frame is only partially constructed. The problem is to determine exactly what's been done, to correctly undo it. @@ -405,19 +426,19 @@ For example, take this prolog and epilog sequence: 0110: ret lr // end ``` -Next to each opcode is the appropriate unwind code describing this operation. You can see how the series of unwind codes for the prolog is an exact mirror image of the unwind codes for the epilog (not counting the final instruction of the epilog). It's a common situation, and it's why we always assume the unwind codes for the prolog are stored in reverse order from the prolog's execution order. +Next to each opcode is the appropriate unwind code describing this operation. You can see how the series of unwind codes for the prolog is an exact mirror image of the unwind codes for the epilog (not counting the final instruction of the epilog). It's a common situation: It's why we always assume the unwind codes for the prolog are stored in reverse order from the prolog's execution order. So, for both the prolog and epilog, we're left with a common set of unwind codes: `set_fp`, `save_regp 0,240`, `save_fregp,0,224`, `save_fplr_x_256`, `end` -The epilog case is straightforward, since it's in normal order. Starting at offset 0 within the epilog (which starts at offset 0x100 in the function), we'd expect to execute the full unwind sequence, as no cleanup has yet been done. If we find ourselves one instruction in (at offset 2 in the epilog), we can successfully unwind by skipping the first unwind code. We can generalize this situation, and assume a 1:1 mapping between opcodes and unwind codes. Then, to start unwinding from instruction *n* in the epilog, we should skip the first *n* unwind codes, and begin executing from there. +The epilog case is straightforward, since it's in normal order. Starting at offset 0 within the epilog (which starts at offset 0x100 in the function), we'd expect the full unwind sequence to execute, as no cleanup has yet been done. If we find ourselves one instruction in (at offset 2 in the epilog), we can successfully unwind by skipping the first unwind code. We can generalize this situation, and assume a 1:1 mapping between opcodes and unwind codes. Then, to start unwinding from instruction *n* in the epilog, we should skip the first *n* unwind codes, and begin executing from there. -It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction n in the prolog, we should start executing n unwind codes from the end of the list of codes. +It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction *n* in the prolog, we should start executing *n* unwind codes from the end of the list of codes. -It's not always the case that the prolog and epilog codes match exactly. That's why the unwind array may need to contain several sequences of codes. To determine the offset of where to begin processing codes, use the following logic: +Prolog and epilog codes don't always match exactly, which is why the unwind array may need to contain several sequences of codes. To determine the offset of where to begin processing codes, use the following logic: -1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an "end" opcode. +1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an `end` opcode. 1. If unwinding from within an epilog, use the epilog-specific starting index provided with the epilog scope as a starting point. Compute how many bytes the PC in question is from the start of the epilog. Then advance forward through the unwind codes, skipping unwind codes until all of the already-executed instructions are accounted for. Then execute starting at that point. @@ -427,11 +448,11 @@ These rules mean the unwind codes for the prolog must always be the first in the ### Function fragments -For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called regions). When split, each resulting function fragment requires its own separate .pdata (and possibly .xdata) record. +For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called *regions*). When split, each resulting function fragment requires its own separate `.pdata` (and possibly `.xdata`) record. -For each separated secondary fragment that has its own prolog, it's expected that no stack adjustment is done in its prolog. All stack space required by a secondary region must be pre-allocated by its parent region (or called host region). This keeps stack pointer manipulation strictly in the function's original prolog. +For each separated secondary fragment that has its own prolog, it's expected that no stack adjustment is done in its prolog. All stack space required by a secondary region must be pre-allocated by its parent region (or called host region). This preallocation keeps stack pointer manipulation strictly in the function's original prolog. -A typical case of function fragments is "code separation" with that compiler may move a region of code out of its host function. There are three unusual cases that could be resulted by code separation. +A typical case of function fragments is "code separation", where the compiler may move a region of code out of its host function. There are three unusual cases that could result from code separation. #### Example @@ -468,19 +489,19 @@ A typical case of function fragments is "code separation" with that compiler may 1. Prolog only (region 1: all epilogs are in separated regions): - Only the prolog must be described. This can't be represented in the compact .pdata format. In the full .xdata case, it can be represented by setting Epilog Count = 0. See region 1 in the example above. + Only the prolog must be described. This prolog can't be represented in the compact `.pdata` format. In the full `.xdata` case, it can be represented by setting Epilog Count = 0. See region 1 in the example above. Unwind codes: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. 1. Epilogs only (region 2: prolog is in host region) - It's assumed that by the time control jumping into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact .pdata. In full .xdata record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. + It's assumed that by the time control jumps into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact `.pdata`. In a full `.xdata` record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. Unwind code for region 2: `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. 1. No prologs or epilogs (region 3: prologs and all epilogs are in other fragments): - Compact .pdata format can be applied via setting Flag = 10. With full .xdata record, Epilog Count = 1. Unwind code is the same as the code for region 2 above, but Epilog Start Index also points to `end_c`. Partial unwind will never happen in this region of code. + Compact `.pdata` format can be applied via setting Flag = 10. With full `.xdata` record, Epilog Count = 1. Unwind code is the same as the code for region 2 above, but Epilog Start Index also points to `end_c`. Partial unwind will never happen in this region of code. Another more complicated case of function fragments is "shrink wrapping." The compiler may choose to delay saving some callee-saved registers until outside of the function entry prolog. @@ -515,17 +536,17 @@ Another more complicated case of function fragments is "shrink wrapping." The co In the prolog of region 1, stack space is pre-allocated. You can see that region 2 will have the same unwind code even it's moved out of its host function. -Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end` with Epilog Start Index points to `set_fp` as usual. +Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to `set_fp` as usual. Region 2: `save_regp 2, 224`, `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to first unwind code `save_regp 2, 224`. ### Large functions -Fragments can be used to describe functions larger than the 1M limit imposed by the bit fields in the .xdata header. To describe a very large function like this, it needs to be broken into fragments smaller than 1M. Each fragment should be adjusted so that it doesn't split an epilog into multiple pieces. +Fragments can be used to describe functions larger than the 1M limit imposed by the bit fields in the `.xdata` header. To describe an unusually large function like this, it needs to be broken into fragments smaller than 1M. Each fragment should be adjusted so that it doesn't split an epilog into multiple pieces. Only the first fragment of the function will contain a prolog; all other fragments are marked as having no prolog. Depending on the number of epilogs present, each fragment may contain zero or more epilogs. Keep in mind that each epilog scope in a fragment specifies its starting offset relative to the start of the fragment, not the start of the function. -If a fragment has no prolog and no epilog, it still requires its own .pdata (and possibly .xdata) record, to describe how to unwind from within the body of the function. +If a fragment has no prolog and no epilog, it still requires its own `.pdata` (and possibly `.xdata`) record, to describe how to unwind from within the body of the function. ## Examples @@ -538,7 +559,7 @@ If a fragment has no prolog and no epilog, it still requires its own .pdata (and sub sp,sp,#0x810 // alloc_m stp fp,lr,[sp] // save_fplr mov fp,sp // set_fp - // end of prolog + // end of prolog ... |$pdata$Foo| @@ -624,5 +645,5 @@ Epilog Start Index [4] points to the middle of Prolog unwind code (partially reu ## See also -[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)
-[ARM Exception Handling](arm-exception-handling.md) +[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)\ +[ARM exception handling](arm-exception-handling.md) diff --git a/docs/build/arm64-windows-abi-conventions.md b/docs/build/arm64-windows-abi-conventions.md index e3fb94d10c..db01bfefe2 100644 --- a/docs/build/arm64-windows-abi-conventions.md +++ b/docs/build/arm64-windows-abi-conventions.md @@ -1,15 +1,15 @@ --- description: "Learn more about: Overview of ARM64 ABI conventions" title: "Overview of ARM64 ABI conventions" -ms.date: "03/27/2019" +ms.date: 04/08/2025 --- # Overview of ARM64 ABI conventions -The basic application binary interface (ABI) for Windows when compiled and run on ARM processors in 64-bit mode (ARMv8 or later architectures), for the most part, follows ARM's standard AArch64 EABI. This article highlights some of the key assumptions and changes from what is documented in the EABI. For information about the 32-bit ABI, see [Overview of ARM ABI conventions](overview-of-arm-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](https://github.com/ARM-software/abi-aa) (external link). +The basic application binary interface (ABI) for Windows when compiled and run on ARM processors in 64-bit mode (ARMv8 or later architectures), usually follows ARM's standard AArch64 EABI. This article highlights some of the key assumptions and changes from what is documented in the EABI. For information about the 32-bit ABI, see [Overview of ARM ABI conventions](overview-of-arm-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](https://github.com/ARM-software/abi-aa) (external link). ## Definitions -With the introduction of 64-bit support, ARM has defined several terms: +With the introduction of 64-bit support, ARM defined several terms: - **AArch32** – the legacy 32-bit instruction set architecture (ISA) defined by ARM, including Thumb mode execution. - **AArch64** – the new 64-bit instruction set architecture (ISA) defined by ARM. @@ -19,8 +19,9 @@ With the introduction of 64-bit support, ARM has defined several terms: Windows also uses these terms: - **ARM** – refers to the 32-bit ARM architecture (AArch32), sometimes referred to as WoA (Windows on ARM). -- **ARM32** – same as ARM, above; used in this document for clarity. +- **ARM32** – same as **ARM**. Used in this document for clarity. - **ARM64** – refers to the 64-bit ARM architecture (AArch64). There's no such thing as WoA64. +- **ARM64EC** - code built as ARM64EC can interoperate with x64 code running under emulation in the same process. The Arm64EC code in the process runs with native performance, while the x64 code runs using emulation. Finally, when referring to data types, the following definitions from ARM are referenced: @@ -30,7 +31,7 @@ Finally, when referring to data types, the following definitions from ARM are re ## Base requirements -The ARM64 version of Windows presupposes that it's running on an ARMv8 or later architecture at all times. Both floating-point and NEON support are presumed to be present in hardware. +The ARM64 version of Windows always presupposes that it's running on an ARMv8 or later architecture. Both floating-point and NEON support are presumed to be present in hardware. The ARMv8 specification describes new optional crypto and CRC helper opcodes for both AArch32 and AArch64. Support for them is currently optional, but recommended. To take advantage of these opcodes, apps should first make runtime checks for their existence. @@ -66,16 +67,15 @@ Default layout alignment for globals and statics: The AArch64 architecture supports 32 integer registers: -| Register | Volatile? | Role | +| Register | Volatility | Role | | - | - | - | -| x0 | Volatile | Parameter/scratch register 1, result register | -| x1-x7 | Volatile | Parameter/scratch register 2-8 | -| x8-x15 | Volatile | Scratch registers | +| x0-x8 | Volatile | Parameter/Result scratch registers | +| x9-x15 | Volatile | Scratch registers | | x16-x17 | Volatile | Intra-procedure-call scratch registers | -| x18 | Non-volatile | Platform register: in kernel mode, points to KPCR for the current processor; in user mode, points to TEB | +| x18 | N/A | Reserved platform register: in kernel mode, points to KPCR for the current processor; In user mode, points to TEB | | x19-x28 | Non-volatile | Scratch registers | | x29/fp | Non-volatile | Frame pointer | -| x30/lr | Non-volatile | Link registers | +| x30/lr | Both | Link Register: Callee function must preserve it for its own return, but caller's value is lost. | Each register may be accessed as a full 64-bit value (via x0-x30) or as a 32-bit value (via w0-w30). 32-bit operations zero-extend their results up to 64 bits. @@ -87,20 +87,19 @@ The frame pointer (x29) is required for compatibility with fast stack walking us ## Floating-point/SIMD registers -The AArch64 architecture also supports 32 floating-point/SIMD registers, summarized below: +The AArch64 architecture also supports these 32 floating-point/SIMD registers: -| Register | Volatile? | Role | +| Register | Volatility | Role | | - | - | - | -| v0 | Volatile | Parameter/scratch register 1, result register | -| v1-v7 | Volatile | Parameter/scratch registers 2-8 | -| v8-v15 | Non-volatile | Scratch registers (only the low 64 bits are non-volatile) | +| v0-v7 | Volatile | Parameter/Result scratch registers | +| v8-v15 | Both | Low 64 bits are Non-Volatile. High 64 bits are Volatile. | | v16-v31 | Volatile | Scratch registers | Each register may be accessed as a full 128-bit value (via v0-v31 or q0-q31). It may be accessed as a 64-bit value (via d0-d31), as a 32-bit value (via s0-s31), as a 16-bit value (via h0-h31), or as an 8-bit value (via b0-b31). Accesses smaller than 128 bits only access the lower bits of the full 128-bit register. They leave the remaining bits untouched unless otherwise specified. (AArch64 is different from AArch32, where the smaller registers were packed on top of the larger registers.) The floating-point control register (FPCR) has certain requirements on the various bitfields within it: -| Bits | Meaning | Volatile? | Role | +| Bits | Meaning | Volatility | Role | | - | - | - | - | | 26 | AHP | Non-Volatile | Alternative half-precision control. | | 25 | DN | Non-Volatile | Default NaN mode control. | @@ -120,7 +119,11 @@ Like AArch32, the AArch64 specification provides three system-controlled "thread ## Floating-point exceptions -Support for IEEE floating-point exceptions is optional on AArch64 systems. For processor variants that do have hardware floating-point exceptions, the Windows kernel silently catches the exceptions and implicitly disables them in the FPCR register. This trap ensures normalized behavior across processor variants. Otherwise, code developed on a platform without exception support may find itself taking unexpected exceptions when running on a platform with support. +To determine if an ARM CPU supports exceptions, write a value that enables exceptions to the FPCR register and then read it back. If the CPU supports floating-point exceptions, the bits corresponding to supported exceptions remain set, while the CPU resets the bits for unsupported exceptions. + +On ARM64, Windows delivers exceptions for processors that support hardware floating-point exceptions. + +The [`_set_controlfp`](/cpp/c-runtime-library/reference/controlfp-s) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised. ## Parameter passing @@ -150,7 +153,7 @@ For each argument in the list, the first matching rule from the following list i ### Stage C – Assignment of arguments to registers and stack -For each argument in the list, the following rules are applied in turn until the argument has been allocated. When an argument is assigned to a register, any unused bits in the register have unspecified value. If an argument is assigned to a stack slot, any unused padding bytes have unspecified value. +For each argument in the list, the following rules are applied in turn until the argument is allocated. When an argument is assigned to a register, any unused bits in the register have unspecified value. If an argument is assigned to a stack slot, any unused padding bytes have unspecified value. 1. If the argument is a Half-, Single-, Double- or Quad-precision Floating-point or Short Vector Type, and the NSRN is less than 8, then the argument is allocated to the least significant bits of register v\[NSRN]. The NSRN is incremented by one. The argument has now been allocated. @@ -160,7 +163,7 @@ For each argument in the list, the following rules are applied in turn until the 1. If the argument is an HFA, an HVA, a Quad-precision Floating-point or Short Vector Type, then the NSAA is rounded up to the larger of 8 or the Natural Alignment of the argument's type. -1. If the argument is a Half- or Single-precision Floating Point type, then the size of the argument is set to 8 bytes. The effect is as if the argument had been copied to the least significant bits of a 64-bit register, and the remaining bits filled with unspecified values. +1. If the argument is a Half- or Single-precision Floating Point type, then the size of the argument is set to 8 bytes. The effect is as if the argument were copied to the least significant bits of a 64-bit register, and the remaining bits filled with unspecified values. 1. If the argument is an HFA, an HVA, a Half-, Single-, Double-, or Quad-precision Floating-point or Short Vector Type, then the argument is copied to memory at the adjusted NSAA. The NSAA is incremented by the size of the argument. The argument has now been allocated. @@ -201,10 +204,10 @@ Floating-point values are returned in s0, d0, or v0, as appropriate. A type is considered to be an HFA or HVA if all of the following hold: - It's non-empty, -- It doesn't have any non-trivial default or copy constructors, destructors, or assignment operators, +- It doesn't have any nontrivial default or copy constructors, destructors, or assignment operators, - All of its members have the same HFA or HVA type, or are float, double, or neon types that match the other members' HFA or HVA types. -HFA and HVA values with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. +HVA values with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. Types returned by value are handled differently depending on whether they have certain properties, and whether the function is a non-static member function. Types which have all of these properties, @@ -212,11 +215,12 @@ Types returned by value are handled differently depending on whether they have c - they have a trivial copy-assignment operator, and - they have a trivial destructor, -and are returned by non-member functions or static member functions, use the following return style: +and are returned by nonmember functions or static member functions, use the following return style: +- Types that are HFAs with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. - Types less than or equal to 8 bytes are returned in x0. - Types less than or equal to 16 bytes are returned in x0 and x1, with x0 containing the lower-order 8 bytes. -- For types greater than 16 bytes, the caller shall reserve a block of memory of sufficient size and alignment to hold the result. The address of the memory block shall be passed as an additional argument to the function in x8. The callee may modify the result memory block at any point during the execution of the subroutine. The callee isn't required to preserve the value stored in x8. +- For other aggregate types, the caller shall reserve a block of memory of sufficient size and alignment to hold the result. The address of the memory block shall be passed as another argument to the function in x8. The callee may modify the result memory block at any point during the execution of the subroutine. The callee isn't required to preserve the value stored in x8. All other types use this convention: @@ -224,9 +228,9 @@ All other types use this convention: ## Stack -Following the ABI put forth by ARM, the stack must remain 16-byte aligned at all times. AArch64 contains a hardware feature that generates stack alignment faults whenever the SP isn't 16-byte aligned and an SP-relative load or store is done. Windows runs with this feature enabled at all times. +Following the ABI put forth by ARM, the stack must always remain 16-byte aligned. AArch64 contains a hardware feature that generates stack alignment faults whenever the SP isn't 16-byte aligned and an SP-relative load or store is done. Windows always runs with this feature enabled. -Functions that allocate 4k or more worth of stack must ensure that each page prior to the final page is touched in order. This action ensures no code can "leap over" the guard pages that Windows uses to expand the stack. Typically the touching is done by the `__chkstk` helper, which has a custom calling convention that passes the total stack allocation divided by 16 in x15. +Functions that allocate 4k or more worth of stack must ensure that each page before the final page is touched in order. This action ensures no code can "leap over" the guard pages that Windows uses to expand the stack. Typically the touching is done by the `__chkstk` helper, which has a custom calling convention that passes the total stack allocation divided by 16 in x15. ## Red zone @@ -242,7 +246,7 @@ Code within Windows is compiled with frame pointers enabled ([/Oy-](reference/oy ## Exception unwinding -Unwinding during exception handling is assisted through the use of unwind codes. The unwind codes are a sequence of bytes stored in the .xdata section of the executable. They describe the operation of the prologue and epilogue in an abstract manner, such that the effects of a function's prologue can be undone in preparation for backing up to the caller's stack frame. For more information on the unwind codes, see [ARM64 exception handling](arm64-exception-handling.md). +Unwinding during exception handling is assisted by using unwind codes. The unwind codes are a sequence of bytes stored in the .xdata section of the executable. They describe the operation of the prologue and epilogue in an abstract manner, such that the effects of a function's prologue can be undone in preparation for backing up to the caller's stack frame. For more information on the unwind codes, see [ARM64 exception handling](arm64-exception-handling.md). The ARM EABI also specifies an exception unwinding model that uses unwind codes. However, the specification as presented is insufficient for unwinding in Windows, which must handle cases where the PC is in the middle of a function prologue or epilogue. @@ -252,7 +256,7 @@ Code that is dynamically generated should be described with dynamic function tab All ARMv8 CPUs are required to support a cycle counter register, a 64-bit register that Windows configures to be readable at any exception level, including user mode. It can be accessed via the special PMCCNTR_EL0 register, using the MSR opcode in assembly code, or the `_ReadStatusReg` intrinsic in C/C++ code. -The cycle counter here is a true cycle counter, not a wall clock. The counting frequency will vary with the processor frequency. If you feel you must know the frequency of the cycle counter, you shouldn't be using the cycle counter. Instead, you want to measure wall clock time, for which you should use `QueryPerformanceCounter`. +The cycle counter here is a true cycle counter, not a wall clock. The counting frequency varies with the processor frequency. If you feel you must know the frequency of the cycle counter, you shouldn't be using the cycle counter. Instead, you want to measure wall clock time, for which you should use `QueryPerformanceCounter`. ## See also diff --git a/docs/build/arm64ec-windows-abi-conventions.md b/docs/build/arm64ec-windows-abi-conventions.md new file mode 100644 index 0000000000..9c78bc39f5 --- /dev/null +++ b/docs/build/arm64ec-windows-abi-conventions.md @@ -0,0 +1,192 @@ +--- +title: "Overview of ARM64EC ABI conventions" +description: "Learn more about: Overview of ARM64EC ABI conventions" +ms.date: "06/03/2022" +--- +# Overview of ARM64EC ABI conventions + +ARM64EC is an application binary interface (ABI) that enables ARM64 binaries to run natively and interoperably with x64 code. Specifically, the ARM64EC ABI follows x64 software conventions including calling convention, stack usage, and data alignment, making ARM64EC and x64 code interoperable. The operating system emulates the x64 portion of the binary. (The EC in ARM64EC stands for *emulation compatible*.) + +For more information on the x64 and ARM64 ABIs, see [Overview of x64 ABI conventions](x64-software-conventions.md) and [Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md). + +ARM64EC doesn't solve memory model differences between x64 and ARM based architectures. For more information, see [Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md). + +## Definitions + +- **ARM64** - The code stream for ARM64 processes that contains traditional ARM64 code. +- **ARM64EC** - The code stream that utilizes a subset of the ARM64 register set to provide interoperability with x64 code. + +## Register mapping + +x64 processes may have threads running ARM64EC code. So it's always possible to retrieve an x64 register context, ARM64EC uses a subset of the ARM64 core registers that map 1:1 to emulated x64 registers. Importantly, ARM64EC never uses registers outside of this subset, except to read the Thread Environment Block (TEB) address from `x18`. + +Native ARM64 processes shouldn't regress in performance when some or many functions are recompiled as ARM64EC. To maintain performance, the ABI follows these principles: + +- The ARM64EC register subset includes all registers that are part of the ARM64 function calling convention. + +- The ARM64EC calling convention directly maps to the ARM64 calling convention. + +Special helper routines like `__chkstk_arm64ec` use custom calling conventions and registers. These registers are also included in the ARM64EC subset of registers. + +## Register mapping for integer registers + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `x0` | `rcx` | volatile | volatile | volatile | +| `x1` | `rdx` | volatile | volatile | volatile | +| `x2` | `r8` | volatile | volatile | volatile | +| `x3` | `r9` | volatile | volatile | volatile | +| `x4` | `r10` | volatile | volatile | volatile | +| `x5` | `r11` | volatile | volatile | volatile | +| `x6` | `mm1` (low 64 bits of x87 `R1` register) | volatile | volatile | volatile | +| `x7` | `mm2` (low 64 bits of x87 `R2` register) | volatile | volatile | volatile | +| `x8` | `rax` | volatile | volatile | volatile | +| `x9` | `mm3` (low 64 bits of x87 `R3` register) | volatile | volatile | volatile | +| `x10` | `mm4` (low 64 bits of x87 `R4` register) | volatile | volatile | volatile | +| `x11` | `mm5` (low 64 bits of x87 `R5` register) | volatile | volatile | volatile | +| `x12` | `mm6` (low 64 bits of x87 `R6` register) | volatile | volatile | volatile | +| `x13` | N/A | disallowed | volatile | N/A | +| `x14` | N/A | disallowed | volatile | N/A | +| `x15` | `mm7` (low 64 bits of x87 `R7` register) | volatile | volatile | volatile | +| `x16` | High 16 bits of each of the x87 `R0`-`R3` registers | volatile(`xip0`) | volatile(`xip0`) | volatile | +| `x17` | High 16 bits of each of the x87 `R4`-`R7` registers | volatile(`xip1`) | volatile(`xip1`) | volatile | +| `x18` | GS.base | fixed(TEB) | fixed(TEB) | fixed(TEB) | +| `x19` | `r12` | non-volatile | non-volatile | non-volatile | +| `x20` | `r13` | non-volatile | non-volatile | non-volatile | +| `x21` | `r14` | non-volatile | non-volatile | non-volatile | +| `x22` | `r15` | non-volatile | non-volatile | non-volatile | +| `x23` | N/A | disallowed | non-volatile | N/A | +| `x24` | N/A | disallowed | non-volatile | N/A | +| `x25` | `rsi` | non-volatile | non-volatile | non-volatile | +| `x26` | `rdi` | non-volatile | non-volatile | non-volatile | +| `x27` | `rbx` | non-volatile | non-volatile | non-volatile | +| `x28` | N/A | disallowed | disallowed | N/A | +| `fp` | `rbp` | non-volatile | non-volatile | non-volatile | +| `lr` | `mm0` (low 64 bits of x87 `R0` register) | both | both | both | +| `sp` | `rsp` | non-volatile | non-volatile | non-volatile | +| `pc` | `rip` | instruction pointer | instruction pointer | instruction pointer | +| `PSTATE` subset: `N`/`Z`/`C`/`V`/`SS` 1, 2 | `RFLAGS` subset: `SF`/`ZF`/`CF`/`OF`/`TF` | volatile | volatile | volatile | +| N/A | `RFLAGS` subset: `PF`/`AF` | N/A | N/A | volatile | +| N/A | `RFLAGS` subset: `DF` | N/A | N/A | non-volatile | + +1 Avoid directly reading, writing or computing mappings between `PSTATE` and `RFLAGS`. These bits may be used in the future and are subject to change. + +2 The ARM64EC carry flag `C` is the inverse of the x64 carry flag `CF` for subtraction operations. There's no special handling, because the flag is volatile and is therefore trashed when transitioning between (ARM64EC and x64) functions. + +## Register mapping for vector registers + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `v0`-`v5` | `xmm0`-`xmm5` | volatile | volatile | volatile | +| `v6`-`v7` | `xmm6`-`xmm7` | volatile | volatile | non-volatile | +| `v8`-`v15` | `xmm8`-`xmm15` | volatile 1 | volatile 1 | non-volatile | +| `v16`-`v31` | `xmm16`-`xmm31` | disallowed | volatile | disallowed (x64 emulator doesn't support AVX-512) | +| `FPCR` 2 | `MXCSR[15:6]` | non-volatile | non-volatile | non-volatile | +| `FPSR` 2 | `MXCSR[5:0]` | volatile | volatile | volatile | + +1 These ARM64 registers are special in that the lower 64 bits are non-volatile but the upper 64 bits are volatile. From the point of view of an x64 caller, they're effectively volatile because the callee would trash data. + +2 Avoid directly reading, writing, or computing mappings of `FPCR` and `FPSR`. These bits may be used in the future and are subject to change. + +## Struct packing + +ARM64EC follows the same struct packing rules used for x64 to ensure interoperability between ARM64EC code and x64 code. For more information and examples of x64 struct packing, see [Overview of x64 ABI conventions](x64-software-conventions.md). + +## Floating-point exceptions + +To determine if an ARM CPU supports exceptions, write a value that enables exceptions to the FPCR register and then read it back. If the CPU supports floating-point exceptions, the bits corresponding to supported exceptions remain set, while the CPU resets the bits for unsupported exceptions. + +On ARM64EC, Windows catches processor floating-point exceptions and disables them in the FPCR register. This ensures consistent behavior across different processor variants. + +## Emulation helper ABI routines + +ARM64EC code and [thunks](#thunks) use emulation helper routines to transition between x64 and ARM64EC functions. + +The following table describes each special ABI routine and the registers the ABI uses. The routines don't modify the listed preserved registers under the ABI column. No assumptions should be made about unlisted registers. On-disk, the ABI routine pointers are null. At load time, the loader updates the pointers to point to the x64 emulator routines. + +| Name | Description | ABI | +|--|--|--| +| `__os_arm64x_dispatch_call_no_redirect` | Called by an exit thunk to call an x64 target (either an x64 function or an x64 fast-forward sequence). The routine pushes the ARM64EC return address (in the `LR` register) followed by the address of the instruction that succeeds a `blr x16` instruction that invokes the x64 emulator. It then runs the `blr x16` instruction | return value in `x8` (`rax`) | +| `__os_arm64x_dispatch_ret` | Called by an entry thunk to return to its x64 caller. It pops the x64 return address from the stack and invokes the x64 emulator to jump to it | N/A | +| `__os_arm64x_check_call` | Called by ARM64EC code with a pointer to an exit thunk and the indirect ARM64EC target address to execute. The ARM64EC target is considered patchable, and execution always returns to the caller with either the same data it was called with, or with modified data | Arguments:
`x9`: The target address
`x10`: The exit thunk address
`x11`: The fast forward sequence address

Out:
`x9`: If the target function was detoured, it contains the address of the fast forward sequence
`x10`: The exit thunk address
`x11`: If the function was detoured, it contains the exit thunk address. Otherwise, the target address jumped to

Preserved registers: `x0`-`x8`, `x15` (`chkstk`). and `q0`-`q7` | +| `__os_arm64x_check_icall` | Called by ARM64EC code, with a pointer to an exit thunk, to handle a jump to either a target address that is either x64 or ARM64EC. If the target is x64 and the x64 code hasn't been patched, the routine sets the target address register. It points to the ARM64EC version of the function if one exists. Otherwise, it sets the register to point to the exit thunk that transitions to the x64 target. Then, it returns to the calling ARM64EC code, which then jumps to the address in the register. This routine is a non-optimized version of `__os_arm64x_check_call`, where the target address isn't known at compile time

Used at a call-site of an indirect call | Arguments:
`x9`: The target address
`x10`: The exit thunk address
`x11`: The fast forward sequence address

Out:
`x9`: If the target function was detoured, it contains the address of the fast forward sequence
`x10`: The exit thunk address
`x11`: If the function was detoured, it contains the exit thunk address. Otherwise, the target address jumped to

Preserved registers: `x0`-`x8`, `x15` (`chkstk`), and `q0`-`q7` | +| `__os_arm64x_check_icall_cfg` | Same as `__os_arm64x_check_icall` but also checks that the specified address is a valid Control Flow Graph indirect call target | Arguments:
`x10`: The address of the exit thunk
`x11`: The address of the target function

Out:
`x9`: If the target is x64, the address to the function. Otherwise, undefined
`x10`: The address of the exit thunk
`x11`: If the target is x64, it contains the address of the exit thunk. Otherwise, the address of the function

Preserved registers: `x0`-`x8`, `x15` (`chkstk`), and `q0`-`q7` | +| `__os_arm64x_get_x64_information` | Gets the requested part of the live x64 register context | `_Function_class_(ARM64X_GET_X64_INFORMATION) NTSTATUS LdrpGetX64Information(_In_ ULONG Type, _Out_ PVOID Output, _In_ PVOID ExtraInfo)` | +| `__os_arm64x_set_x64_information` | Sets the requested part of the live x64 register context | `_Function_class_(ARM64X_SET_X64_INFORMATION) NTSTATUS LdrpSetX64Information(_In_ ULONG Type,_In_ PVOID Input, _In_ PVOID ExtraInfo)` | +| `__os_arm64x_x64_jump` | Used in signature-less adjustor and other thunks that directly forward (`jmp`) a call to another function that can have any signature, deferring the potential application of the right thunk to the real target | Arguments:
`x9`: target to jump to

All parameter registers preserved (forwarded) | + +## Thunks + +Thunks are the low-level mechanisms to support ARM64EC and x64 functions calling each other. There are two types: *entry thunks* for entering ARM64EC functions and *exit thunks* for calling x64 functions. + +### Entry thunk and intrinsic entry thunks: x64 to ARM64EC function call + +To support x64 callers when a C/C++ function is compiled as ARM64EC, the toolchain generates a single entry thunk consisting of ARM64EC machine code. Intrinsics have an entry thunk of their own. All other functions share an entry thunk with all functions that have a matching calling convention, parameters, and return type. The content of the thunk depends on the calling convention of the C/C++ function. + +In addition to handling parameters and the return address, the thunk bridges the differences in volatility between ARM64EC and x64 vector registers caused by [ARM64EC vector register mapping](#register-mapping-for-vector-registers): + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `v6`-`v15` | `xmm6`-`xmm15` | volatile, but saved/restored in the entry thunk (x64 to ARM64EC) | volatile or partially volatile upper 64 bits | non-volatile | + +The entry thunk performs the following actions: + +| Parameter number | Stack usage | +|--|--| +| 0-4 | Stores ARM64EC `v6` and `v7` into the caller-allocated home space

Since the callee is ARM64EC, which doesn't have the notion of a home space, the stored values aren't clobbered.

Allocates an extra 128 bytes on the stack and store ARM64EC `v8` through `v15`. | +| 5-8 | `x4` = 5th parameter from the stack
`x5` = 6th parameter from the stack
`x6` = 7th parameter from the stack
`x7` = 8th parameter from the stack

If the parameter is SIMD, the `v4`-`v7` registers are used instead | +| 9+ | Allocates `AlignUp(NumParams - 8 , 2) * 8` bytes on the stack. \*

Copies the 9th and remaining parameters to this area | + +\* Aligning the value to an even number guarantees that the stack remains aligned to 16 bytes + +If the function accepts a 32-bit integer parameter, the thunk is permitted to only push 32 bits instead of the full 64 bits of the parent register. + +Next, the thunk uses an ARM64 `bl` instruction to call the ARM64EC function. After the function returns, the thunk: + +1. Undoes any stack allocations +1. Calls the `__os_arm64x_dispatch_ret` emulator helper to pop the x64 return address and resume x64 emulation. + +### Exit thunk: ARM64EC to x64 function call + +For every call that an ARM64EC C/C++ function makes to potential x64 code, the MSVC toolchain generates an exit thunk. The content of the thunk depends on the parameters of the x64 callee and whether the callee is using the standard calling convention or `__vectorcall`. The compiler obtains this information from a function declaration for the callee. + +First, The thunk pushes the return address that's in the ARM64EC `lr` register and a dummy 8-byte value to guarantee that the stack is aligned to 16 bytes. Second, the thunk handles the parameters: + +| Parameter number | Stack usage | +|--|--| +| 0-4 | Allocates 32 bytes of home space on the stack | +| 5-8 | Allocates `AlignUp(NumParams - 4, 2) * 8` more bytes higher up on the stack. \*

Copies the 5th and any subsequent parameters from ARM64EC's `x4`-`x7` to this extra space | +| 9+ | Copies the 9th and remaining parameters to the extra space | + +\* Aligning the value to an even number guarantees that the stack remains aligned to 16 bytes. + +Third, the thunk calls the `__os_arm64x_dispatch_call_no_redirect` emulator helper to invoke the x64 emulator to run the x64 function. The call must be a `blr x16` instruction (conveniently, `x16` is a volatile register). A `blr x16` instruction is required because the x64 emulator parses this instruction as a hint. + +The x64 function usually attempts to return to the emulator helper by using an x64 `ret` instruction. At this point, the x64 emulator detects that it's in ARM64EC code. It then reads the preceding 4-byte hint that happens to be the ARM64 `blr x16` instruction. Since this hint indicates that the return address is in this helper, the emulator jumps directly to this address. + +The x64 function is permitted to return to the emulator helper using any branch instruction, including x64 `jmp` and `call`. The emulator handles these scenarios as well. + +When the helper then returns to the thunk, the thunk: + +1. Undoes any stack allocation +1. Pops the ARM64EC `lr` register +1. Executes an ARM64 `ret lr` instruction. + +## ARM64EC function name decoration + +An ARM64EC function name has a secondary decoration applied after any language-specific decoration. For functions with C linkage (whether compiled as C or by using `extern "C"`), a `#` is prepended to the name. For C++ decorated functions, a `$$h` tag is inserted into the name. + +``` +foo => #foo +?foo@@YAHXZ => ?foo@@$$hYAHXZ +``` + +## `__vectorcall` + +The ARM64EC toolchain currently doesn't support `__vectorcall`. The compiler emits an error when it detects `__vectorcall` usage with ARM64EC. + +## See also + +[Understanding ARM64EC ABI and assembly code](/windows/arm/arm64ec-abi)\ +[Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ +[Decorated names](./reference/decorated-names.md) diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index f44936dd0b..06332dd523 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -2,7 +2,7 @@ title: "Use the Microsoft C++ toolset from the command line" description: "Use the Microsoft C++ (MSVC) compiler toolset from the command line outside of the Visual Studio IDE." ms.custom: "conceptual" -ms.date: 09/08/2021 +ms.date: 04/07/2022 helpviewer_keywords: ["command-line builds [C++]", "compiling source code [C++], command line", "builds [C++], command-line", "command line [C++], building from", "command line [C++], compilers"] ms.assetid: 7ca9daed-a003-4162-842d-908f79058365 --- @@ -11,7 +11,7 @@ ms.assetid: 7ca9daed-a003-4162-842d-908f79058365 You can build C and C++ applications on the command line by using tools that are included in Visual Studio. The Microsoft C++ (MSVC) compiler toolset is also downloadable as a standalone package. You don't need to install the Visual Studio IDE if you don't plan to use it. > [!NOTE] -> This article is about how to set up an environment to use the individual compilers, linkers, librarian, and other basic tools. The native project build system, MSBuild, does not use the environment as described in this article. For more information on how to use MSBuild from the command line, see [MSBuild on the command line - C++](msbuild-visual-cpp.md). +> This article is about how to set up an environment to use the individual compilers, linkers, librarian, and other basic tools. The native project build system in Visual Studio, based on MSBuild, doesn't use the environment as described in this article. For more information on how to use MSBuild from the command line, see [MSBuild on the command line - C++](msbuild-visual-cpp.md). ## Download and install the tools @@ -28,19 +28,19 @@ If you've installed Visual Studio and a C++ workload, you have all the command-l ## How to use the command-line tools -When you choose one of the C++ workloads in the Visual Studio Installer, it installs the Visual Studio *platform toolset*. A platform toolset has all the C and C++ tools for a specific Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries. You can use all of these tools at the command line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools to build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. +When you choose one of the C++ workloads in the Visual Studio Installer, it installs the Visual Studio *platform toolset*. A platform toolset has all the C and C++ tools for a specific Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries and header files. You can use all of these tools at the command line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools to build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. -To work correctly, the tools require several specific environment variables to be set. These variables are used to add the tools to the path, and to set include file, library file, and SDK locations. To make it easy to set these environment variables, the installer creates customized *command files*, or batch files, during installation. You can run one of these command files to set a specific host and target build architecture, Windows SDK version, and platform toolset. For convenience, the installer also creates shortcuts in your Start menu. The shortcuts start developer command prompt windows by using these command files for specific combinations of host and target. These shortcuts ensure all the required environment variables are set and ready to use. +To work correctly, the tools require several specific environment variables to be set. These variables are used to add the tools to the path, and to set the locations of include files, library files, and SDKs. To make it easy to set these environment variables, the installer creates customized *command files*, or batch files, during installation. You can run one of these command files to set a specific host and target build architecture, Windows SDK version, and platform toolset. For convenience, the installer also creates shortcuts in your Start menu. The shortcuts open developer command prompt windows by using these command files for specific combinations of host and target. These shortcuts ensure all the required environment variables are set and ready to use. -The required environment variables are specific to your installation and to the build architecture you choose. They also might be changed by product updates or upgrades. That's why we recommend you use an installed command prompt shortcut or command file, instead of setting the environment variables yourself. +The required environment variables are specific to your installation and to the build architecture you choose. They also might be changed by product updates or upgrades. This variability is one reason why we recommend you use an installed command prompt shortcut or command file, instead of setting the environment variables yourself. The toolsets, command files, and shortcuts installed depend on your computer processor and the options you selected during installation. The x86-hosted tools and cross tools that build x86 and x64 code are always installed. If you have 64-bit Windows, the x64-hosted tools and cross tools that build x86 and x64 code are also installed. If you choose the optional C++ Universal Windows Platform tools, then the x86 and x64 tools that build ARM and ARM64 code also get installed. Other workloads may install these and other tools. ## Path and environment variables for command-line builds -The MSVC command-line tools use the `PATH`, `TMP`, `INCLUDE`, `LIB`, and `LIBPATH` environment variables, and also use other environment variables specific to your installed tools, platforms, and SDKs. Even a simple Visual Studio installation may set twenty or more environment variables. The values of these environment variables are specific to your installation and your choice of build configuration, and can be changed by product updates or upgrades. That's why we strongly recommend that you use a [developer command prompt shortcut](#developer_command_prompt_shortcuts) or one of the [customized command files](#developer_command_file_locations) to set them. We don't recommend you set them in the Windows environment yourself. +The MSVC command-line tools use the `PATH`, `TMP`, `INCLUDE`, `LIB`, and `LIBPATH` environment variables, and also use other environment variables specific to your installed tools, platforms, and SDKs. Even a simple Visual Studio installation may set twenty or more environment variables. This complexity is why we strongly recommend that you use a [developer command prompt shortcut](#developer_command_prompt_shortcuts) or one of the [customized command files](#developer_command_file_locations). We don't recommend you set these variables in the Windows environment yourself. -To see which environment variables are set by a developer command prompt shortcut, you can use the `SET` command. Open a plain command prompt window and capture the output of the `SET` command for a baseline. Open a developer command prompt window and capture the output of the `SET` command for comparison. A diff tool such as the one built into the Visual Studio IDE can be useful to compare the environment variables and see what's set by the developer command prompt. For information about the specific environment variables used by the compiler and linker, see [CL Environment Variables](reference/cl-environment-variables.md). +To see which environment variables are set by a developer command prompt shortcut, you can use the `SET` command. Open a plain command prompt window and capture the output of the `SET` command for a baseline. Open a developer command prompt window and capture the output of the `SET` command for comparison. Use a diff tool such as the one built into Visual Studio to highlight the environment variables set by the developer command prompt. For more information about the compiler and linker environment variables, see [CL environment variables](reference/cl-environment-variables.md). ## Developer command prompt shortcuts @@ -54,7 +54,7 @@ The command prompt shortcuts are installed in a version-specific Visual Studio f ::: moniker range=">= msvc-160" -The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. If you set one, they also depend on the installation **Nickname**. For example, suppose you installed Visual Studio 2019, and you gave it a nickname of *Latest*. The developer command prompt shortcut is named **Developer Command Prompt for VS 2019 (Latest)**, in a folder named **Visual Studio 2019**. +The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. If you set one, they also depend on the installation **Nickname**. For example, suppose you installed Visual Studio 2022, and you gave it a nickname of *Latest*. The developer command prompt shortcut is named **Developer Command Prompt for VS 2022 (Latest)**, in a folder named **Visual Studio 2022**. ::: moniker-end ::: moniker range="msvc-150" @@ -73,33 +73,41 @@ The Start menu folder and shortcut names vary depending on the installed version ### To open a developer command prompt window -1. On the desktop, open the Windows **Start** menu, and then scroll to find and open the folder for your version of Visual Studio, for example, **Visual Studio 2019**. +1. On the desktop, open the Windows **Start** menu. In Windows 11, choose the **All apps** button to open the list of installed apps. In Windows 10, the list is open to the left. Scroll down the list to find and open the folder (not the app) for your version of Visual Studio, for example, **Visual Studio 2022**. 1. In the folder, choose the **Developer Command Prompt** for your version of Visual Studio. This shortcut starts a developer command prompt window that uses the default build architecture of 32-bit, x86-native tools to build 32-bit, x86-native code. If you prefer a non-default build architecture, choose one of the native or cross tools command prompts to specify the host and target architecture. For an even faster way to open a developer command prompt, enter *developer command prompt* in the desktop search box. Then choose the result you want. +> [!NOTE] +> By default, the current working directory in a developer command prompt is the root of your Visual Studio installation in the Program Files directory. This isn't an appropriate location for your code and projects. Change the current working directory to another location before you create a project. The IDE creates projects in your user directory, typically in *%USERPROFILE%\\source\\repos*. + ## Developer command file locations If you prefer to set the build environment in an existing command prompt window, you can use one of the command files created by the installer. We recommend you set the environment in a new command prompt window. We don't recommend you later switch environments in the same command window. -::: moniker range=">= msvc-160" +::: moniker range=">= msvc-170" + +The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. + +::: moniker-end +::: moniker range="= msvc-160" -The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in \\Program Files (x86)\\Microsoft Visual Studio\\2019\\*edition*. *Edition* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. +The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in *`\Program Files (x86)\Microsoft Visual Studio\2019\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end ::: moniker range="= msvc-150" -The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2017, the typical installation location on a 64-bit system is in \\Program Files (x86)\\Microsoft Visual Studio\\2017\\*edition*. *Edition* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. +The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2017, the typical installation location on a 64-bit system is in *`\Program Files (x86)\Microsoft Visual Studio\2017\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end ::: moniker range="< msvc-150" -The command file location depends on the Visual Studio version, and the installation directory. For Visual Studio 2015, the typical installation location is in \\Program Files (x86)\\Microsoft Visual Studio 14.0. +The command file location depends on the Visual Studio version, and the installation directory. For Visual Studio 2015, the typical installation location on a 64-bit system is in *`\Program Files (x86)\Microsoft Visual Studio 14.0`*. ::: moniker-end -The primary developer command prompt command file, *`VsDevCmd.bat`*, is located in the Common7\\Tools subdirectory. When no parameters are specified, it sets the environment to use the x86-native tools to build 32-bit x86 code. +The primary developer command prompt command file, *`VsDevCmd.bat`*, is located in the *`Common7\Tools`* subdirectory. When no parameters are specified, it sets the environment to use the x86-native tools to build 32-bit x86 code. ::: moniker range=">= msvc-150" @@ -139,7 +147,7 @@ When used with no arguments, *`vcvarsall.bat`* configures the environment variab ### `vcvarsall` syntax -> **`vcvarsall.bat`** [*`architecture`*] [*`platform_type`*] [*`winsdk_version`*] [**`-vcvars_ver=`**_`vcversion`_] [*`spectre_mode`*] +> **`vcvarsall.bat`** [*`architecture`*] [*`platform_type`*] [*`winsdk_version`*] [**`-vcvars_ver=`***`vcversion`*] [*`spectre_mode`*] *`architecture`*
This optional argument specifies the host and target architecture to use. If *architecture* isn't specified, the default build environment is used. These arguments are supported: @@ -246,7 +254,7 @@ Use the compiler (cl.exe) to compile and link source code files into apps, libra [`Link`](reference/linking.md)
Use the linker (link.exe) to link compiled object files and libraries into apps and DLLs. -When you build on the command line, the F1 command isn't available for instant help. Instead, you can use a search engine to get information about warnings, errors, and messages. You can also download and use the offline help files. To use the search in docs.microsoft.com, enter your query in the search box at the top of any article. +When you build on the command line, the F1 command isn't available for instant help. Instead, you can use a search engine to get information about warnings, errors, and messages. You can also download and use the offline help files. To use the search in Microsoft Learn, enter your query in the search box at the top of any article. ## Command-line project management tools diff --git a/docs/build/clang-support-cmake.md b/docs/build/clang-support-cmake.md index 6ae9039afb..157c3259d9 100644 --- a/docs/build/clang-support-cmake.md +++ b/docs/build/clang-support-cmake.md @@ -21,21 +21,23 @@ You can use Visual Studio with Clang to edit and debug C++ CMake projects that t **Linux**: For Linux CMake projects, no special Visual Studio support is required. You can install Clang using your distro's package manager, and add the appropriate commands in the CMakeLists.txt file. ## Install - ::: moniker-end ::: moniker range="msvc-160" -For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. When using a custom Clang installation, check the **C++ Clang-cl for v142 build tools** component. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools** component. + +![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png) ::: moniker-end ::: moniker range="msvc-170" -For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. When using a custom Clang installation, check the **C++ Clang-cl for v143 build tools** component. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **MSBuild support for LLVM (clang-cl) toolset** component. + +![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2022.png) ::: moniker-end ::: moniker range=">=msvc-160" -![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png) ## Create a new configuration @@ -82,9 +84,9 @@ You can modify these values in **CMake Settings** under **CMake variables and ca ## Edit, build, and debug -After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you are using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. +After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. -When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue are not available for Clang configurations. +When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. ![Screenshot of the Visual Studio debugger debugging a CMake Clang project.](media/clang-debug-visualize.png) diff --git a/docs/build/clang-support-msbuild.md b/docs/build/clang-support-msbuild.md index d53368d521..6e44fbb42a 100644 --- a/docs/build/clang-support-msbuild.md +++ b/docs/build/clang-support-msbuild.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Clang/LLVM support in Visual Studio projects" title: "Clang/LLVM support in Visual Studio projects" -ms.date: 11/11/2021 +description: "Learn more about: Clang/LLVM support in Visual Studio projects" +ms.date: 03/13/2024 ms.description: "Configure a Visual Studio MSBuild project to use the Clang/LLVM toolchain." helpviewer_keywords: ["Clang support for C++ MSBuild projects"] --- @@ -9,33 +9,57 @@ helpviewer_keywords: ["Clang support for C++ MSBuild projects"] ::: moniker range="<=msvc-150" -Clang support for both CMake and MSBuild projects is available in Visual Studio 2019. +Clang/LLVM support for both CMake and MSBuild projects is available in Visual Studio 2019 and Visual Studio 2022. ::: moniker-end - ::: moniker range=">=msvc-160" -You can use Visual Studio 2019 version 16.2 and later with Clang to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. +You can use Visual Studio 2019 version 16.2 and later with Clang/LLVM to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. + +::: moniker-end +::: moniker range="=msvc-160" ## Install -For best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **C++ Clang-cl for v142 build tools**. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools**. +::: moniker-end +::: moniker range=">=msvc-170" +## Install + +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **MSBuild support for LLVM (clang-cl) toolset**. +::: moniker-end +::: moniker range=">=msvc-160" The Microsoft C++ Standard Library requires at least Clang 8.0.0. +::: moniker-end + +::: moniker range="=msvc-160" +:::image type="complex" source="media/clang-install-vs2019.png" alt-text="Screenshot of the Visual Studio 2019 installer"::: +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. C++ Clang-cl for v142 build tools (x64/x86) is also selected. +:::image-end::: + +::: moniker-end +::: moniker range=">=msvc-170" +:::image type="complex" source="media/clang-install-vs2022.png" alt-text="Screenshot of the Visual Studio 2022 installer." +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. MSBuild support for LLVM (clang-cl) toolset is also selected. +::: image-end ::: -![Screenshot of the Visual Studio installer with the Individual components tab selected and the C plus plus Clang components visible.](media/clang-install-vs2019.png) +::: moniker-end -Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.9 includes Clang v11. +::: moniker range=">=msvc-160" +Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.11 includes Clang v12. ## Configure a Windows project to use Clang tools To configure a Visual Studio project to use Clang, right-click on the project node in **Solution Explorer** and choose **Properties**. Typically, you should first choose **All configurations** at the top of the dialog. Then, under **General** > **Platform Toolset**, choose **LLVM (clang-cl)** and then **OK**. -![Screenshot of the Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and LLVM (clang-cl) option highlighted.](media/llvm-msbuild-prop-page.png) +:::image type="complex" source="media/llvm-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio project Property Pages dialog box."::: +The project properties page is open to the Configuration Properties > General page. The Platform Toolset dropdown is selected, on which LLVM (clang-cl) is selected. +:::image-end::: -If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *%VCINSTALLDIR%\\Tools\\Llvm\\bin\\* and *%VCINSTALLDIR%\\Tools\\Llvm\\x64\\bin\\*. +If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *`%VCINSTALLDIR%\Tools\Llvm\bin\`* and *`%VCINSTALLDIR%\Tools\Llvm\x64\bin\`*. -If you're using a custom Clang installation, you can either modify **Project** > **Properties** > **VC++ Directories** > **Configuration Properties** > **Executable Directories** by adding the custom Clang installation root as the first directory there, or change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). +If you're using a custom Clang installation, you can change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). ## Configure a Linux project to use Clang tools @@ -48,33 +72,34 @@ To configure a Visual Studio Linux project to use Clang: 1. Under **General** > **Platform Toolset**, choose **Clang for Windows Subsystem for Linux** if you're using Windows Subsystem for Linux (WSL). Choose **Clang for Remote Linux** if you're using a remote machine or VM. 1. Press **OK**. -![Screenshot of the Console App clang Visual Studio 2019 Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and L L V M (clang c l) options highlighted.](media/clang-msbuild-prop-page.png) +:::image type="complex" source="media/clang-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio 2019 project Property Pages dialog box"::: +The project properties page is open to the Configuration Properties > General page. Platform Toolset is selected and from the list of options, LLVM (clang- c l) is selected." +:::image-end::: On Linux, Visual Studio by default uses the first Clang location that it finds in the PATH environment property. If you're using a custom Clang installation, then either change the value of the `LLVMInstallDir` property or else enter the path under **Project** > **Properties** > **Configuration Properties** > **VC++ DIrectories** > **Executable Directories**. For more information, see [Set a custom LLVM location](#custom_llvm_location). -## Set a custom LLVM location +## Set a custom LLVM location and toolset -You can set a custom path to LLVM for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): +To set a custom path to LLVM and set a custom LLVM toolset version for one or more projects, create a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this example (but use your actual LLVM path and version number): ```xml C:\MyLLVMRootDir + 15.0.0 ``` -You can combine this property with a custom LLVM toolset version. For more information, see [Set a custom LLVM toolset version](#custom_llvm_toolset). - -## Set a custom LLVM toolset version +## Set a custom LLVM toolset version in the IDE -Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM. To set this property in a project in Visual Studio: +Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM in Visual Studio. To set this property in a project: -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](./working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties](./working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. +1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. Choose **Apply** to save your changes. 1. Select the **Configuration Properties** > **Advanced** property page. @@ -82,35 +107,16 @@ Starting in Visual Studio 2019 version 16.9, you can set a custom toolset versio The **LLVM Toolset Version** property only appears when the LLVM platform toolset is selected. -You can set the toolset version for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. Add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): - -```xml - - - 11.0.0 - - -``` - -You can also combine this property with a custom LLVM location. For example, your *Directory.build.props* file could look like: - -```xml - - - C:\MyLLVMRootDir - 11.0.0 - - -``` - -When you add a *Directory.build.props* file, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the *Directory.build.props* file. +When you add a `Directory.build.props` file to a project or solution, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the `Directory.build.props` file. -## Set additional properties, edit, build, and debug +## Set properties, edit, build, and debug After you have set up a Clang configuration, right-click again on the project node and choose **Reload project**. You can now build and debug the project using the Clang tools. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. The project property pages for a Clang configuration are similar to the ones for MSVC. However, some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. You can set a Clang compiler or linker option that isn't available in the property pages. Add it manually in the property pages under **Configuration Properties** > **C/C++ (or Linker)** > **Command Line** > **Additional Options**. When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. -![Screenshot of Visual Studio showing Clang debugging.](media/clang-debug-msbuild.png) +:::image type="complex" source="media/clang-debug-msbuild.png" alt-text="Screenshot of Visual Studio debugging a sample app"::: +The portion of the app that is visible creates a string vector and adds some strings to it. Execution has stopped on a breakpoint for the code: v.push_back("Clang/LLVM");. +:::image-end::: ::: moniker-end diff --git a/docs/build/cmake-presets-json-reference.md b/docs/build/cmake-presets-json-reference.md index 51259d2de8..07b08b79e8 100644 --- a/docs/build/cmake-presets-json-reference.md +++ b/docs/build/cmake-presets-json-reference.md @@ -1,7 +1,7 @@ --- description: "Schema reference for `CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps" title: "CMakeUserPresets.json" -ms.date: 08/03/2021 +ms.date: 02/07/2022 helpviewer_keywords: ["CMake in Visual C++"] --- # `CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps @@ -30,13 +30,13 @@ The options in the Visual Studio Settings vendor map don't affect the constructi |--|--| | `hostOS` | An array of supported operating systems (OS). Accepted values are `Windows`, `Linux`, and `macOS`.

The value of `hostOS` is used by Visual Studio and Visual Studio Code to hide Configure Presets that don't apply to the OS of the target system and provide a better user experience.

If `hostOS` is unspecified, then Visual Studio and Visual Studio Code will always show all Configure Presets for selection. This field can also be a string, which is equivalent to an array containing one string

This option is supported by both Visual Studio and Visual Studio Code. | | `intelliSenseMode` | Specifies the mode used for computing IntelliSense information in Visual Studio with the format `--`.

Accepted values:

`android-clang-arm`
`android-clang-arm64`
`android-clang-x6`
`android-clang-x86`
`ios-clang-ar`
`ios-clang-arm64`
`ios-clang-x6`
`ios-clang-x86`
`linux-gcc-arm`
`linux-gcc-x64`
`linux-gcc-x86`
`windows-clang-arm`
`windows-clang-arm64`
`windows-clang-x64`
`windows-clang-x86`
`windows-msvc-arm`
`windows-msvc-arm64`
`windows-msvc-x64`
`windows-msvc-x86`

If `intelliSenseMode` is unspecified, then Visual Studio uses the IntelliSense mode that matches your specified compilers and target architecture. `intelliSenseMode` is often used to provide improved IntelliSense for cross-compilation.

In Visual Studio 2019, you must explicitly specify a clang IntelliSense mode when building with clang or clang-cl. | -| `intelliSenseOptions` | A map of extra IntelliSense configuration options.

`useCompilerDefaults`: A `bool` that specifies whether to use the compilers’ default defines and include paths for IntelliSense. Should only be `false` if the compilers in use don't support gcc-style arguments. Defaults to `true`.

`additionalCompilerArgs`: An array of extra options to control IntelliSense in Visual Studio. This option supports macro expansion. | +| `intelliSenseOptions` | A map of extra IntelliSense configuration options.

`useCompilerDefaults`: A `bool` that specifies whether to use the compiler default defines and include paths for IntelliSense. Should only be `false` if the compilers in use don't support gcc-style arguments. Defaults to `true`.

`additionalCompilerArgs`: An array of extra options to control IntelliSense in Visual Studio. This option supports macro expansion. | | `enableMicrosoftCodeAnalysis` | A `bool` that enables Microsoft code analysis in Visual Studio when building with `cl` or `clang-cl`. Defaults to `false`. | | `codeAnalysisRuleset` | Specifies the ruleset to use when running Microsoft code analysis in Visual Studio. You can use a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | | `disableExternalAnalysis` | A `bool` that specifies whether code analysis should run on external headers in Visual Studio. | | `codeAnalysisExternalRuleset` | Specifies the ruleset to use when running Microsoft code analysis on external header in Visual Studio. You can use a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | | `enableClangTidyCodeAnalysis` | A bool that enables clang-tidy code analysis in Visual Studio when building with `clang-cl`. Defaults to `false`. | -| `clangTidyChecks` | A comma-separated list of warnings passed to clang-tidy when running clang-tidy code analysis in Visual Studio. Wildcards are allowed, and the `–` prefix will remove checks. | +| `clangTidyChecks` | A comma-separated list of warnings passed to clang-tidy when running clang-tidy code analysis in Visual Studio. Wildcards are allowed, and the `-` prefix will remove checks. | | `cacheRoot` | Specifies the path to a CMake cache. This directory should contain an existing *`CMakeCache.txt`* file. This key is only supported by the Open Existing Cache scenario in Visual Studio. This option supports macro expansion. | | `cmakeGenerateCommand` | A command-line tool (specified as a command-line program and arguments, for example, **`gencache.bat debug`**) to generate the CMake cache. This command runs in the shell using the specified environment of the preset when CMake configure is invoked. This key is only supported by the [Open Existing Cache](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/) scenario in Visual Studio. This option supports macro expansion. | diff --git a/docs/build/cmake-presets-vs.md b/docs/build/cmake-presets-vs.md index a7457a5a29..8aface6d9b 100644 --- a/docs/build/cmake-presets-vs.md +++ b/docs/build/cmake-presets-vs.md @@ -1,7 +1,7 @@ --- title: Configure and build with CMake Presets description: "Reference for using CMake Presets to configure and build CMake projects." -ms.date: 12/15/2021 +ms.date: 06/09/2023 ms.topic: reference --- @@ -21,22 +21,31 @@ We recommend *`CMakePresets.json`* as an alternative to *`CMakeSettings.json`*. ## Supported CMake and *`CMakePresets.json`* versions -Visual Studio supports version 2 or later for the *`CMakePresets.json`* and *`CMakeUserPresets.json`* files. You can update your file version by incrementing the version field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). +The supported *`CMakePresets.json`* and *`CMakeUserPresets.json`* schema versions depend on your version of Visual Studio: +- Visual Studio 2019 version 16.10 and later support schema versions 2 and 3. +- Visual Studio 2022 version 17.4 preview 1 adds support for schema version 4. +- Visual Studio 2022 version 17.5 preview 1 adds support for schema version 5. -CMake version 3.20 or later is required when you're invoking CMake with *`CMakePresets.json`* (version 2 or later) from the command line. However, Visual Studio reads and evaluates *`CMakePresets.json`* and *`CMakeUserPresets.json`* itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with *`CMakePresets.json`* inside Visual Studio. We recommend using CMake version 3.14 or later. +You can update the version by changing the `"version"` field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). -## Enable *`CMakePresets.json`* integration in Visual Studio +CMake version 3.20 or later is required when you're invoking CMake with *`CMakePresets.json`* from the command line. However, Visual Studio reads and evaluates *`CMakePresets.json`* and *`CMakeUserPresets.json`* itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with *`CMakePresets.json`* inside Visual Studio. + +We recommend using at least CMake version 3.14 or later. + +## Enable *`CMakePresets.json`* integration in Visual Studio *`CMakePresets.json`* integration isn't enabled by default in Visual Studio. You can enable it in **Tools** > **Options** > **CMake** > **General**: -![Screenshot showing the checkbox to enable CMakePresets.json on the CMake General page of the Tools Options dialog in Visual Studio 2022 version 17.1.](./media/enable-cmakepresets-new.png) +:::image type="complex" source="./media/enable-cmakepresets-new.png" alt-text="Screenshot showing 'Always use CMakePresets.json' selected."::: +This screen is reached from the Visual Studio 2022 menu: Tools > Options > CMake > General. The option is under the CMake configure file section. +:::image-end::: -> [!Important] +> [!IMPORTANT] > Close and reopen the folder in Visual Studio to activate the integration. -In Visual Studio 2022 and Visual Studio 2019 version 16.10 and later, **Tools** > **Options** > **CMake** > **General** has a single option to enable *`CMakePresets.json`* integration. +In some older versions of Visual Studio, **Tools** > **Options** > **CMake** > **General** only has a single option to enable *`CMakePresets.json`* integration: -![Screenshot showing the checkbox to enable CMakePresets.json on the CMake General page of the Tools Options dialog in Visual Studio 2019.](./media/enable-cmakepresets.png) +:::image type="content" source="./media/enable-cmakepresets.png" alt-text="Screenshot of an older version of Visual Studio. There is a checkbox labeled 'Use C Make Presets .json to drive CMake configure, build, and test.'"::: The following table indicates when *`CMakePresets.json`* is used instead of *`CMakeSettings.json`* to drive CMake configuration and build in Visual Studio 2022 and Visual Studio 2019 version 16.10 and later. If no configuration file is present, default Configure Presets are used. @@ -110,15 +119,17 @@ If you try to open or modify a *`CMakePresets.json`* file that doesn't exist, Vi ## Configure and build -Visual Studio provides dropdown lists for the Target Systems, Configure Presets, and Build Presets when *`CMakePresets.json`* integration is enabled: +On the Visual Studio toolbar, there are dropdowns for the Target Systems, Configure Presets, and Build Presets when *`CMakePresets.json`* integration is enabled: -![Screenshot that shows the dropdown lists for the Target System.](./media/target-system-dropdown.png) +:::image type="content" source="./media/target-system-dropdown.png" alt-text="Screenshot showing the dropdowns for target system set to Local Machine, configuration set to windows-arm64, and build preset set to default."::: ### Select a Target System The dropdown list on the left indicates the active *Target System*. It's the system on which CMake is invoked to configure and build the project. This dropdown list includes your local machine, all SSH connections in Connection Manager by host name, and all Windows Subsystem for Linux (WSL) installations that Visual Studio can find: -![Screenshot of the selections in the dropdown list for the Target System.](./media/target-system-selections.png) +:::image type="complex" source="./media/target-system-selections.png" alt-text="Screenshot of the Target System dropdown list"::: +The dropdown list contains several entries including Local Machine, an ip address 192.168.0.5, WSL: ubuntu2004, WSL: debian, and Manage Connections. +:::image-end::: In the preceding example: @@ -177,7 +188,7 @@ Use a forward slash (`/`) for paths in *`CMakePresets.json`* and *`CMakeUserPres To add a new Configure Preset to *`CMakePresets.json`*, from **Solution Explorer**, right-click *`CMakePresets.json`* from **Folder View** and select **Add Configuration** from the shortcut menu. The dialog to select a Configure Preset template appears: -![Screenshot of the dialog for adding a Configure Preset to the J S O N file.](./media/add-configure-preset-to-cmakepresets.png) +:::image type="content" source="./media/add-configure-preset-to-cmakepresets.png" alt-text="Screenshot of the Add Configure Preset to the JSON file dialog. It contains entries such as Linux Debug, macOS Debug, x64 Debug, and so on."::: Select the **Windows x64 Debug** template to configure on Windows systems. Select the **Linux Debug** template to configure on WSL and remote Linux systems. For more information about editing *`CMakePresets.json`*, see [Edit presets](#edit-presets). @@ -283,7 +294,7 @@ You can set the host architecture (x64 or x86) and toolset by using `toolset.val The `architecture.strategy` and `toolset.strategy` values tell CMake how to handle the architecture and toolset fields. `set` means CMake sets the respective value, and `external` means CMake won't set the respective value. -We recommend you use `set` with IDE generators like the Visual Studio Generator. Use `external` with command-line generators like Ninja. These values allow vendors like Visual Studio to supply the required environment before CMake is invoked. For more information about the architecture and toolset fields, see the [list of Configure Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset). +We recommend using `set` with IDE generators like the Visual Studio Generator. Use `external` with command-line generators like Ninja. These values allow vendors like Visual Studio to supply the required environment before CMake is invoked. For more information about the architecture and toolset fields, see the [list of Configure Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset). If you don't want to source an environment, you can set `architecture.strategy` to `external` and `architecture.value` to `unspecified`. You might find it useful not to source an environment for any one of these reasons: @@ -376,9 +387,9 @@ Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment var }, ``` -`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](https://github.com/microsoft/vcpkg/blob/master/docs/users/config-environment.md). +`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](/vcpkg/users/config-environment). -If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](https://github.com/microsoft/vcpkg/blob/master/docs/users/integration.md#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg. +If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](/vcpkg/users/buildsystems/cmake-integration#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg. ## Variable substitution in *`launch.vs.json`* and *`tasks.vs.json`* @@ -467,15 +478,15 @@ cmake --build --preset ## Example *`CMakePresets.json`* file -The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/vs-launch/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. +The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/vs-launch/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. For more information about this example, see the presentation [An Introduction to CMakePresets.json](/events/cpp-pure-virtual-cpp-2021/an-introduction-to-cmakepresetsjson). You can see another example in the [DirectXTK](https://github.com/microsoft/DirectXTK/blob/main/CMakePresets.json) project, which shows many build targets in its `configurePresets` section. ## Next steps Learn more about configuring and debugging CMake projects in Visual Studio: > [!div class="nextstepaction"] -> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)

-> [Customize CMake build settings](customize-cmake-settings.md)

-> [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)

+> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)\ +> [Customize CMake build settings](customize-cmake-settings.md)\ +> [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ > [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) > diff --git a/docs/build/cmake-projects-in-visual-studio.md b/docs/build/cmake-projects-in-visual-studio.md index e1c5afff62..a164d943fe 100644 --- a/docs/build/cmake-projects-in-visual-studio.md +++ b/docs/build/cmake-projects-in-visual-studio.md @@ -1,26 +1,28 @@ --- title: "CMake projects in Visual Studio" -description: "How to create and build C++ projects using CMake in Visual Studio." -ms.date: 12/15/2021 -helpviewer_keywords: ["CMake in Visual C++"] -ms.assetid: 444d50df-215e-4d31-933a-b41841f186f8 +description: "Learn how to create and build C++ projects using CMake in Visual Studio." +ms.date: 03/18/2025 +ms.topic: concept-article +f1_keywords: ["VS.ToolsOptionsPages.CMake.General", "VS.ToolsOptionsPages.CMake.LanguageServices"] --- # CMake projects in Visual Studio [CMake](https://cmake.org) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. This article assumes you're familiar with CMake. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#). The [CMake tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/index.html#guide:CMake%20Tutorial) is a good starting point to learn more. > [!NOTE] -> CMake has become more and more integrated with Visual Studio over the past few releases. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +> CMake has become more and more integrated with Visual Studio over the past few releases. To see the documentation for your preferred version of Visual Studio, use the **Version** selector located at the top of the table of contents on this page. ::: moniker range=">=msvc-160" -Visual Studio's native support for CMake enables you to edit, build, and debug CMake projects on Windows, the Windows Subsystem for Linux (WSL), and remote systems from the same instance of Visual Studio. CMake project files (such as *`CMakeLists.txt`*) are consumed directly by Visual Studio for the purposes of IntelliSense and browsing. `cmake.exe` is invoked directly by Visual Studio for CMake configuration and build. +Visual Studio's native support for CMake allows you to edit, build, and debug CMake projects on Windows, the Windows Subsystem for Linux (WSL), and remote systems from the same instance of Visual Studio. CMake project files (such as *`CMakeLists.txt`*) are consumed directly by Visual Studio for the purposes of IntelliSense and browsing. Visual Studio invokes `cmake.exe` directly for CMake configuration and build. ## Installation **C++ CMake tools for Windows** is installed as part of the **Desktop development with C++** and **Linux Development with C++** workloads. Both **C++ CMake tools for Windows** and **Linux Development with C++** are required for cross-platform CMake development. -![Screenshot of the Desktop development with C plus plus dropdown selected and the C plus plus C Make tools for Windows option called out.](media/cmake-install-2019.png) +:::image type="complex" source="media/cmake-install-2022.png" alt-text="Screenshot of the Visual Studio installer."::: +In the installer, the Desktop development with C plus plus dropdown is selected and C plus plus C Make tools for Windows is selected." +:::image-end::: For more information, see [Install the C++ Linux workload in Visual Studio](../linux/download-install-and-setup-the-linux-development-workload.md). @@ -28,7 +30,9 @@ For more information, see [Install the C++ Linux workload in Visual Studio](../l When you **open a folder** containing a *`CMakeLists.txt`* file, the following things happen. -![A screenshot of the Start Window in Visual Studio.](media/start-window.png) +:::image type="complex" source="media/start-window.png" alt-text="Screenshot of the first dialog that opens when Visual Studio is started."::: +The dialog offers these options: clone a repository, open a project or solution, open a local folder, or create a new project. Open a local folder is called out in the screenshot. +:::image-end::: - Visual Studio adds **CMake** items to the **Project** menu, with commands for viewing and editing CMake scripts. @@ -39,11 +43,11 @@ When you **open a folder** containing a *`CMakeLists.txt`* file, the following t - In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources. > [!NOTE] -> Starting in Visual Studio 2022 version 17.1 Preview 2, if your folder doesn't contain a root `CMakeLists.txt` you'll be prompted whether you'd like to enable CMake integration or not. For more information, see [CMake partial activation](#cmake-partial-activation). +> Starting in Visual Studio 2022 version 17.1 Preview 2, if your top-level *`CMakeLists.txt`* exists in a subfolder and not at the root of the workspace, you're prompted whether you'd like to enable CMake integration or not. For more information, see [CMake partial activation](#cmake-partial-activation). -Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose **Targets view** from the dropdown in the **Solution Explorer** toolbar: +Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose the **Select View** button on the **Solution Explorer** toolbar. From the list in **Solution Explorer - Views**, select **CMake Targets View** and press **Enter** to open the targets view: -![CMake targets view button.](media/cmake-targets-view.png) +:::image type="content" source="media/cmake-targets-view2.png" alt-text="Screenshot of the Solution Explorer Views window. The folder view is open. The C Make Targets View option is highlighted."::: Choose the **Show All Files** button at the top of **Solution Explorer** to see all the CMake-generated output in the *`out/build/`* folders. @@ -56,25 +60,24 @@ To pass arguments to an executable at debug time, you can use another file calle Most Visual Studio and C++ language features are supported by CMake projects in Visual Studio. Examples include: - [Edit and Continue for CMake projects](#edit-and-continue-for-cmake-projects) - - [Incredibuild integration for CMake projects](https://devblogs.microsoft.com/cppblog/seamlessly-accelerate-cmake-projects-in-visual-studio-with-incredibuild/) - - [AddressSanitizer support for CMake projects](cmake-presets-vs.md#enable-addresssanitizer-for-windows-and-linux) - - [Clang/LLVM support](https://devblogs.microsoft.com/cppblog/clang-llvm-support-in-visual-studio/) > [!NOTE] -> For other kinds of Open Folder projects, an additional JSON file *`CppProperties.json`* is used. This file is not relevant for CMake projects. +> For other kinds of Open Folder projects, an additional JSON file *`CppProperties.json`* is used. This file isn't relevant for CMake projects. ## Configuring CMake projects -The CMake configure step generates the project build system. It's equivalent to invoking `cmake.exe` from the command line. For more information on the CMake configure step, see the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html#generate-a-project-buildsystem). +The CMake configure step generates the project build system. It's equivalent to invoking *`cmake.exe`* from the command line. For more information on the CMake configure step, see the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html#generate-a-project-buildsystem). -Visual Studio uses a CMake configuration file to drive CMake generation and build. *`CMakePresets.json`* is supported by Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. *`CMakePresets.json`* is supported directly by CMake and can be used to drive CMake generation and build from Visual Studio, from VS Code, in a Continuous Integration pipeline, and from the command line on Windows, Linux, and Mac. For more information on *`CMakePresets.json`*, see [Configure and build with CMake Presets](cmake-presets-vs.md). *`CMakeSettings.json`* is available for customers using an earlier version of Visual Studio. For more information on *`CMakeSettings.json`*, see [Customize CMake build settings](customize-cmake-settings.md). +Visual Studio uses a CMake configuration file to drive CMake generation and build. *`CMakePresets.json`* is supported by Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. *`CMakePresets.json`* is supported directly by CMake and can be used to drive CMake generation and build from Visual Studio, from VS Code, in a continuous integration pipeline, and from the command line on Windows, Linux, and Mac. For more information on *`CMakePresets.json`*, see [Configure and build with CMake Presets](cmake-presets-vs.md). *`CMakeSettings.json`* is available for customers using an earlier version of Visual Studio. For more information on *`CMakeSettings.json`*, see [Customize CMake build settings](customize-cmake-settings.md). -When you make significant changes to your CMake configuration file or a *`CMakeLists.txt`* file, Visual Studio will automatically run the CMake configure step. You can invoke the configure step manually: Select **Project > Configure Cache** from the toolbar. You can also change your configuration preferences in **Tools** > **Options** > **CMake** > **General**. +When you make significant changes to your CMake configuration file or a *`CMakeLists.txt`* file, Visual Studio automatically runs the CMake configure step. You can invoke the configure step manually: Select **Project > Configure Cache** from the toolbar. You can also change your configuration preferences in **Tools** > **Options** > **CMake** > **General**. -![CMake configuration options.](media/cmake-configure-options.png) +:::image type="complex" source="media/cmake-configure-options.png" alt-text="Screenshot of the C Make configuration options in the Visual Studio settings window."::: +The C Make configure settings are called out. Show C Make cache notifications is selected. Under 'When cache is out of date', the option 'Never run configure step automatically' is selected. +:::image-end::: If the configure step finishes without errors, then the information that's available drives C++ IntelliSense and language services. It's also used in build and debug operations. @@ -86,11 +89,17 @@ By default, most configuration messages are suppressed unless there's an error. You can also disable all CMake cache notifications (gold bars) by deselecting **Show CMake cache notification**. +### Customize Targets View source groups + +By default, the CMake Targets View ignores the following source groups: *Source Files*, *Header Files*, *Resources*, *Object Files*. These groups are included by default in most CMake projects and would unnecessarily increase the number of clicks required to navigate the Targets View. + +You can enable the use of these source groups by selecting **Tools** > **Options** > **CMake** > **Enable the use of ignored source groups in CMake Targets View**. + ### Troubleshooting CMake cache errors If you need more information about the state of the CMake cache to diagnose a problem, open the **Project** main menu or the *`CMakeLists.txt`* context menu in **Solution Explorer** to run one of these commands: -- **View CMakeCache.txt** opens the *`CMakeCache.txt`* file from the build directory in the editor. Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after you clean the cache, see [Customize CMake settings](customize-cmake-settings.md) or [Configure and Build with CMake Presets](cmake-presets-vs.md). +- **View CMakeCache.txt** opens the *`CMakeCache.txt`* file from the build directory in the editor. Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after you clean the cache, see [Customize CMake settings](customize-cmake-settings.md) or [Configure and build with CMake Presets](cmake-presets-vs.md). - **Delete Cache and Reconfigure** deletes the build directory and reconfigures from a clean cache. @@ -110,7 +119,9 @@ To build a CMake project, you have these choices: As you would expect, build results are shown in the **Output Window** and **Error List**. -![CMake build errors.](media/cmake-build-errors.png "CMake build errors") +:::image type="complex" source="media/cmake-build-errors.png" alt-text="Screenshot of the Visual Studio Error List window"::: +C Make build warnings about conversions that might result in data loss such as converting from a float to an integer, are visible. +:::image-end::: ### Edit build settings @@ -118,17 +129,19 @@ Visual Studio uses a CMake configuration file to drive CMake builds. CMake confi ## Debugging CMake projects -All executable CMake targets are shown in the **Startup Item** dropdown in the toolbar. To start debugging, select one and press the **Debug > Start Debugging** button in the toolbar. In a CMake project, the "Current document" option is only valid for .cpp files. +All executable CMake targets are shown in the **Startup Item** dropdown in the toolbar. To start debugging, select one and press the **Debug > Start Debugging** button in the toolbar. In a CMake project, the **Current document** option is only valid for .cpp files. -![A screenshot of the Startup Item dropdown in a CMake project.](media/debug-target.png "The Startup Item dropdown in a CMake project") +:::image type="complex" source="media/debug-target.png" alt-text="Screenshot of the Visual Studio debug dropdown."::: +The dropdown has these options: Show / Hide debug targets, current document, samples (which is highlighted), box2d_tests, and samples-noGUI. +:::image-end::: The **Debug** or **F5** commands first build the project if changes have been made since the previous build. Changes to the CMake configuration file (*`CMakePresets.json`* or *`CMakeSettings.json`*) or a *`CMakeLists.txt`* causes the CMake cache to be regenerated. -You can customize a CMake debugging session by setting properties in the *`launch.vs.json`* file. To customize debug settings for a specific target, select the target in the **Startup Item** dropdown and press **Debug > Debug and Launch Settings for \**. For more information on CMake debugging sessions, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). +You can customize a CMake debugging session by setting properties in the *`launch.vs.json`* file. To customize debug settings for a specific target, select the target in the **Startup Item** dropdown and choose **Debug > Debug and Launch Settings for \**. For more information on CMake debugging sessions, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). ### Just My Code for CMake projects -When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. To change the Just My Code setting, go to **Tools** > **Options** > **Debugging** > **General**. +When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. To change the Just My Code setting, go to **Tools** > **Options** > **Debugging** > **General**. For more information on Just My Code debugging, see [Debug only user code with Just My Code](/visualstudio/debugger/just-my-code). ### Edit and Continue for CMake projects @@ -141,24 +154,28 @@ if(MSVC) endif() ``` +For more information on Edit and Continue, see [Configure Edit and Continue (C#, VB, C++)](/visualstudio/debugger/how-to-enable-and-disable-edit-and-continue). + ### Attach to a CMake project running on Linux Visual Studio allows you to debug a process running on a remote Linux system or WSL and debug it with the GDB debugger. To get started, select **Debug** > **Attach to Process...**, set the **Connection type** to **SSH**, and select your **Connection target** from the list of connections in the Connection Manager. Select a process from the list of available processes and press **Attach**. GDB must be installed on your Linux machine. For more information on SSH connections, see the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md) -![A screenshot of the Attach to Process menu.](media/attach-to-process.png) +:::image type="complex" source="media/attach-to-process.png" alt-text="Screenshot of the Attach to Process menu in Visual Studio."::: +The following options are available on the dialog: Connection type (set to SSH), the connection target (set to demo@ 172. 20. 60. 6), and a list of available processes you can attach to." +:::image-end::: ## CMake partial activation -Starting in Visual Studio 2022 version 17.1 Preview 2, CMake functionality won't be enabled automatically if your root folder doesn't contain a `CMakeLists.txt` file. Instead, a dialog will prompt you on whether you'd like to enable CMake functionality for your project. If you decline, CMake cache generation won't start and CMake configurations (from `CMakeSettings.json` or `CMakePresets.json`) won't appear in the configuration dropdown. If you accept, you'll be taken to a workspace-level configuration file, `CMakeWorkspaceSettings.json` (stored in the `.vs` directory), to specify the folders you'd like to enable CMake for. (These folders contain your root `CMakeLists.txt` files). +In Visual Studio 2022 version 17.1 and later, CMake functionality isn't enabled automatically if your root folder doesn't contain a *`CMakeLists.txt`* file. Instead, a dialog prompts you on whether you'd like to enable CMake functionality for your project. If you decline, CMake cache generation doesn't start and CMake configurations (from *`CMakeSettings.json`* or *`CMakePresets.json`*) doesn't appear in the configuration dropdown. If you accept, you're taken to a workspace-level configuration file, *`CMakeWorkspaceSettings.json`* (stored in the *`.vs`* directory), to specify the folders you'd like to enable CMake for. (These folders contain your root *`CMakeLists.txt`* files). The accepted properties are: | Property | Description | |--|--| | `enableCMake` | Enable Visual Studio's integration for this workspace. | -| `sourceDirectory` | A string or array of strings specifying the directory or directories with `CMakeLists.txt`. Macros (such as `${workspaceRoot}`) are allowed. Relative paths are based on the workspace root. Directories outside of the current workspace will be ignored. | +| `sourceDirectory` | A string or array of strings specifying the directory or directories with *`CMakeLists.txt`*. Macros (such as `${workspaceRoot}`) are allowed. Relative paths are based on the workspace root. Directories outside of the current workspace are ignored. | -You can reach `CMakeWorkspaceSettings.json` through the **Project** > **CMake Workspace Settings** menu command at any time, even if CMake functionality is currently disabled. +You can reach *`CMakeWorkspaceSettings.json`* through the **Project** > **CMake Workspace Settings** menu command at any time, even if CMake functionality is currently disabled. ## Open an existing cache @@ -177,7 +194,7 @@ You can add an existing CMake cache to an open project. It's done the same way y Visual Studio uses the CMake [file-based API](https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html) (in versions 3.14 and later) to populate the editor with information specific to your project structure. For more information, see the C++ team blog post on [multi-root workspaces and file-based API](https://devblogs.microsoft.com/cppblog/visual-studio-code-cmake-tools-extension-multi-root-workspaces-and-file-based-api/). -Before generating the CMake cache, your custom or preferred tools may need to create a query file named *`.cmake/api/v1/query/client-MicrosoftVS/query.json`* in your build output folder (the folder that contains *`CMakeCache.txt`*). The query file should contain this content: +Before generating the CMake cache, your custom or preferred tools might need to create a query file named *`.cmake/api/v1/query/client-MicrosoftVS/query.json`* in your build output folder (the folder that contains *`CMakeCache.txt`*). The query file should contain this content: ```json {"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]} @@ -189,23 +206,31 @@ When your custom or preferred tools generate your cache, CMake places files unde To edit a *`CMakeLists.txt`* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *`CMakeLists.txt`*, see the [CMake documentation](https://cmake.org/documentation/). -![CMakeLists.txt file editing.](media/cmake-cmakelists.png "CMakeLists.txt file editing") +:::image type="complex" source="media/cmake-cmakelists.png" alt-text="Screenshot of a C Make Lists TXT file being edited in Visual Studio." +It contains the lines project (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp), and install (TARGETS hello DESTINATION hello/bin). A message at the top of the window says that c plus plus IntelliSense info will refresh after C Make finishes generating the cache. +:::image-end::: As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *`CMakeLists.txt`*. -![CMakeLists.txt file errors.](media/cmake-cmakelists-error.png "CMakeLists.txt file errors") +:::image type="complex" source="media/cmake-cmakelists-error.png" alt-text="Screenshot of a C Make error in the Visual Studio error list."::: +A C Make error message on line 3 of CMakeLists.txt is highlighted. The details are that C Make couldn't find a package configuration file provided by sqlite3. C Make looked for it in CMAKE_MODULE_PATH but couldn't find it. The suggestion is to add the installation prefix 'sqlite3' to CMAKE_PREFIX_PATH or set sqlite3_DIR to a directory containing sqlite3Config.cmake and/or sqlitet3-config.cmake. +:::image-end::: ### Language services for CMake -Language services for CMake are available in Visual Studio 2019 version 16.5 or later. Code navigation features like Go To Definition, Peek Definition, and Find All References are supported for CMake variables, functions, and targets in CMake script files. For more information, see [Code Navigation for CMake Scripts](https://devblogs.microsoft.com/cppblog/code-navigation-for-cmake-scripts/). +Language services for CMake are available in Visual Studio 2019 version 16.5 or later. Language services support code navigation features like *Go To Definition*, *Peek Definition*, and *Find All References* for CMake variables, functions, and targets in CMake script files. For more information, see [Code Navigation for CMake Scripts](https://devblogs.microsoft.com/cppblog/code-navigation-for-cmake-scripts/). -![Find All References on a CMake variable, target, or function.](media/cmake-find-all-refs.png) +:::image type="complex" source="media/cmake-find-all-refs.png" alt-text="Screenshot of the Visual Studio Find All References window."::: +Results of where SUPERTUX_SOURCES_CXX are found are shown. For example, in list(SORT SSUPERTUX_SOURCES_CXX), file(GLOB SUPERTUX_SOURCES_CXX) and so on. +:::image-end::: ### CMake project manipulation -CMake project manipulation is available in Visual Studio 2019 version 16.5 or later. Project manipulation enables you to add, remove, and rename source files and targets in your CMake project without manually editing your CMake scripts. When you add or remove files from the Solution Explorer, Visual Studio automatically edits your CMake project. There could be more than one place where it makes sense to add or remove a reference to a CMake script. If so, Visual Studio asks you where you want to make the change and displays a preview of the proposed changes. For step-by-step instructions, see [Add, Remove, and Rename Files and Targets in CMake Projects](https://devblogs.microsoft.com/cppblog/easily-add-remove-and-rename-files-and-targets-in-cmake-projects/). +CMake project manipulation is available in Visual Studio 2019 version 16.5 or later. Project manipulation lets you add, remove, and rename source files and targets in your CMake project without manually editing your CMake scripts. When you add or remove files from the Solution Explorer, Visual Studio automatically edits your CMake project. There could be more than one place where it makes sense to add or remove a reference to a CMake script. If so, Visual Studio asks you where you want to make the change and displays a preview of the proposed changes. For step-by-step instructions, see [Add, Remove, and Rename Files and Targets in CMake Projects](https://devblogs.microsoft.com/cppblog/easily-add-remove-and-rename-files-and-targets-in-cmake-projects/). -![Resolving ambiguity with CMake project manipulation.](media/cmake-project-manipulation.png) +:::image type="complex" source="media/cmake-project-manipulation.png" alt-text="Screenshot of the Visual Studio Preview Changes dialog box."::: +A tree view shows CMakeLists.txt, under which are two items: add_executable and set. Set is checked. The preview window shows where changes will be made. The line set PROJECT_SRC "CmakeProject4.cpp" "CMakeProject4.h" shows "Demo.cpp" highlighted before the closing parenthesis. The apply button accepts the change, or you can press cancel. +:::image-end::: ## IntelliSense for CMake projects @@ -221,19 +246,22 @@ In Visual Studio 2019 version 16.9 and later, Visual Studio automatically config ## Vcpkg integration -CMake projects opened in Visual Studio integrate with vcpkg, a cross-platform C/C++ dependency manager. Before using vcpkg with Visual Studio, you must run `vcpkg integrate install`. For instructions and more information on vcpkg, see the [vcpkg documentation](https://vcpkg.io/). +CMake projects opened in Visual Studio integrate with vcpkg, a cross-platform C/C++ dependency manager. Before using vcpkg with Visual Studio, you must run `vcpkg integrate install`. For instructions and more information about vcpkg, see: + +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) If *`CMakeSettings.json`* is your active configuration file, Visual Studio automatically passes the vcpkg toolchain file (`vcpkg.cmake`) to CMake. This behavior is disabled automatically when you specify any other toolchain in your CMake Settings configuration. -If *`CMakePresets.json`* is your active configuration file, you'll need to set the path to `vcpkg.cmake` in *`CMakePresets.json`*. We recommend using the `VCPKG_ROOT` environment variable instead of an absolute path to keep the file shareable. For more information, see [Enable vcpkg integration with CMake Presets](cmake-presets-vs.md#enable-vcpkg-integration). *`CMakePresets.json`* is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. +If *`CMakePresets.json`* is your active configuration file, you need to set the path to `vcpkg.cmake` in *`CMakePresets.json`*. We recommend using the `VCPKG_ROOT` environment variable instead of an absolute path to keep the file shareable. For more information, see [Enable vcpkg integration with CMake Presets](cmake-presets-vs.md#enable-vcpkg-integration). *`CMakePresets.json`* is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. ## Run CMake from the command line If *`CMakePresets.json`* is your active CMake configuration file, then you can easily reproduce your local builds outside of Visual Studio. For more information, see [Run CMake from the command line or a CI pipeline](cmake-presets-vs.md#run-cmake-from-the-command-line-or-a-ci-pipeline). *`CMakePresets.json`* is supported in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. -If *`CMakeSettings.json`* is your active CMake configuration file, then you'll need to manually pass the arguments that are encoded in your *`CMakeSettings.json`* file to CMake. If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: +If *`CMakeSettings.json`* is your active CMake configuration file, then you need to manually pass the arguments that are encoded in your *`CMakeSettings.json`* file to CMake. If you installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: -1. Run the appropriate *`vsdevcmd.bat`* file (x86/x64). For more information, see [Building on the command line](building-on-the-command-line.md) . +1. Run the appropriate *`vsdevcmd.bat`* file (x86/x64). For more information, see [Use the Microsoft C++ toolset from the command line](building-on-the-command-line.md) . 1. Switch to your output folder. @@ -249,13 +277,13 @@ Visual Studio 2017 has rich support for CMake, including [cross-platform CMake p **Visual C++ Tools for CMake** is installed as part of the **Desktop development with C++** and **Linux Development with C++** workloads. -![Screenshot of the Individual components tab with the Visual C plus plus tools for C make option called out.](media/cmake-install.png) +:::image type="content" source="media/cmake-install.png" alt-text="Screenshot of the Visual Studio Installer. The Individual components tab is selected on which Visual C plus plus tools for C Make is selected."::: For more information, see [Install the C++ Linux workload in Visual Studio](../linux/download-install-and-setup-the-linux-development-workload.md). ## IDE integration -When you choose **File > Open > Folder** to open a folder containing a *`CMakeLists.txt`* file, the following things happen: +When you choose **File > Open > Folder** to open a folder containing a *`CMakeLists.txt`* file, the following happens: - Visual Studio adds a **CMake** menu item to the main menu, with commands for viewing and editing CMake scripts. @@ -265,15 +293,17 @@ When you choose **File > Open > Folder** to open a folder containing a *`CMakeLi - In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources. -You can open folders containing any number of CMake projects. Visual Studio detects and configures all the "root" *`CMakeLists.txt`* files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace. +You can open folders containing any number of CMake projects. Visual Studio detects and configures all the top-level *`CMakeLists.txt`* files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace. -![CMake project with multiple roots.](media/cmake-multiple-roots.png) +:::image type="complex" source="media/cmake-multiple-roots.png" alt-text="Screenshot of the Visual Studio Solution Explorer."::: +The files and folders of a C Make project are visible. There's a tests subdirectory, CMakeLists.txt, and hello.cpp. There's a hello-cmake-vcpkg folder that contains CMakeLists.txt, CMakeSettings.json, and hello.cpp. +:::image-end::: You can also view your projects organized logically by targets. Choose **Targets view** from the dropdown in the **Solution Explorer** toolbar: -![CMake targets view button.](media/cmake-targets-view.png) +:::image type="content" source="media/cmake-targets-view.png" alt-text="Screenshot of the dropdown button in the Visual Studio Solution Explorer that offers the CMake targets view option. Which is selected."::: -Visual Studio uses a file called *`CMakeSettings.json`* to store environment variables or command-line options for CMake. *`CMakeSettings.json`* also enables you to define and store multiple CMake build configurations. You can conveniently switch between them in the IDE. +Visual Studio uses a file called *`CMakeSettings.json`* to store environment variables or command-line options for CMake. *`CMakeSettings.json`* also lets you define and store multiple CMake build configurations. You can conveniently switch between them in the IDE. Otherwise, use the *`CMakeLists.txt`* just as you would in any CMake project to specify source files, find libraries, set compiler and linker options, and specify other build system-related information. @@ -284,49 +314,53 @@ If you need to pass arguments to an executable at debug time, you can use anothe ## Import an existing cache -When you import an existing *`CMakeCache.txt`* file, Visual Studio automatically extracts customized variables and creates a pre-populated *`CMakeSettings.json`* file based on them. The original cache isn't modified in any way. It can still be used from the command line, or with whatever tool or IDE used to generate it. The new *`CMakeSettings.json`* file is placed alongside the project's root *`CMakeLists.txt`*. Visual Studio generates a new cache based the settings file. You can override automatic cache generation in the **Tools > Options > CMake > General** dialog. +When you import an existing *`CMakeCache.txt`* file, Visual Studio automatically extracts customized variables and creates a prepopulated *`CMakeSettings.json`* file based on them. The original cache isn't modified in any way. It can still be used from the command line, or with whatever tool or IDE used to generate it. The new *`CMakeSettings.json`* file is placed alongside the project's root *`CMakeLists.txt`*. Visual Studio generates a new cache based the settings file. You can override automatic cache generation in the **Tools > Options > CMake > General** dialog. -Not everything in the cache is imported. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE. +Not everything in the cache is imported. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE. ### To import an existing cache 1. From the main menu, choose **File > Open > CMake**: - ![Open CMake.](media/cmake-file-open.png "File, Open, CMake") + :::image type="content" source="media/cmake-file-open.png" alt-text="Screenshot of the Visual Studio main menu with C Make selected."::: This command brings up the **Import CMake from Cache** wizard. 2. Navigate to the *`CMakeCache.txt`* file that you want to import, and then choose **OK**. The **Import CMake Project from Cache** wizard appears: - ![Import a CMake cache.](media/cmake-import-wizard.png "Open the CMake import cache wizard") + :::image type="content" source="media/cmake-import-wizard.png" alt-text="Screenshot of the Import C Make Project from Cache wizard. The directory path of the C Make project to import goes in the folder textbox."::: - When the wizard completes, you can see the new *`CMakeCache.txt`* file in **Solution Explorer** next to the root *`CMakeLists.txt`* file in your project. + When the wizard completes, you can see the new *`CMakeCache.txt`* file in **Solution Explorer** next to the root *`CMakeLists.txt*` file in your project. ## Building CMake projects To build a CMake project, you have these choices: -1. In the General toolbar, find the **Configurations** dropdown. It's probably showing "Linux-Debug" or "x64-Debug" by default. Select the preferred configuration and press **F5**, or choose the **Run** (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution. +1. In the General toolbar, find the **Configurations** dropdown. It's probably showing **Linux-Debug** or **x64-Debug** by default. Select the preferred configuration and press **F5**, or choose the **Run** (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution. 1. Right-click on *`CMakeLists.txt`* in **Solution Explorer** and select **Build** from the context menu. If you have multiple targets in your folder structure, you can choose to build all or only one specific target. 1. From the main menu, select **Build > Build Solution** (**F7** or **Ctrl+Shift+B**). Make sure that a CMake target is already selected in the **Startup Item** dropdown in the **General** toolbar. -![CMake build menu command.](media/cmake-build-menu.png "CMake build command menu") +:::image type="complex" source="media/cmake-build-menu.png" alt-text="Screenshot of the Visual Studio Solution Explorer after right-clicking C Make Lists dot t x t."::: +The menu has options such as Add, Open, Configure tasks, Build, Clean all, and so on. +:::image-end::: -You can customize build configurations, environment variables, command-line arguments, and other settings in the *`CMakeSettings.json`* file. It lets you make changes without modifying the *`CMakeLists.txt`* file. For more information, see [Customize CMake settings](customize-cmake-settings.md). +You can customize build configurations, environment variables, command-line arguments, and other settings in the *`CMakeSettings.json`* file. It lets you make changes without modifying the *`CMakeLists.txt`* file. For more information, see [Customize CMake build settings](customize-cmake-settings.md). As you would expect, build results are shown in the **Output Window** and **Error List**. -![CMake build errors.](media/cmake-build-errors.png "CMake build errors") +:::image type="complex" source="media/cmake-build-errors.png" alt-text="Screenshot of the Visual Studio Error List window."::: +C Make build warnings about conversions that might result in data loss such as converting from a float to an integer are visible. +:::image-end::: In a folder with multiple build targets, you can specify which CMake target to build: Choose the **Build** item on the **CMake** menu or the *`CMakeLists.txt`* context menu to specify the target. If you enter **Ctrl+Shift+B** in a CMake project, it builds the current active document. ## Debugging CMake projects -To debug a CMake project, choose the preferred configuration and press **F5**. Or, press the **Run** button in the toolbar. If the **Run** button says "Select Startup Item", select the dropdown arrow and choose the target that you want to run. (In a CMake project, the "Current document" option is only valid for .cpp files.) +To debug a CMake project, choose the preferred configuration and press **F5**. Or, press the **Run** button in the toolbar. If the **Run** button says **Select Startup Item**, select the dropdown arrow and choose the target that you want to run. (In a CMake project, the **Current document** option is only valid for .cpp files.) -![CMake run button.](media/cmake-run-button.png "CMake run button") +:::image type="content" source="media/cmake-run-button.png" alt-text="Screenshot of the Select Startup Item dropdown for a C Make project. You can select current document or hello-cmake."::: The **Run** or **F5** commands first build the project if changes have been made since the previous build. @@ -336,19 +370,25 @@ You can customize a CMake debugging session by setting properties in the *`launc To edit a *`CMakeLists.txt`* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *`CMakeLists.txt`*, see the [CMake documentation](https://cmake.org/documentation/). - ![CMakeLists.txt file editing.](media/cmake-cmakelists.png "CMakeLists.txt file editing") + :::image type="complex" source="media/cmake-cmakelists.png" alt-text="Screenshot of a C Make Lists file being edited in Visual Studio."::: + The file contains project (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp), and install (TARGETS hello DESTINATION hello/bin). A message at the top of the window says that c plus plus IntelliSense info will refresh after C Make finishes generating the cache. + :::image-end::: As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *`CMakeLists.txt`*. - ![CMakeLists.txt file errors.](media/cmake-cmakelists-error.png "CMakeLists.txt file errors") + :::image type="complex" source="media/cmake-cmakelists-error.png" alt-text="Screenshot of a C Make error in the Visual Studio error list."::: + A C Make error message on line 3 of CMakeLists.txt is highlighted. The details are that C Make can't find a package configuration file provided by sqlite3. C Make looked for it in CMAKE_MODULE_PATH but couldn't find it. The suggestion is to add the installation prefix 'sqlite3' to CMAKE_PREFIX_PATH or set sqlite3_DIR to a directory containing sqlite3Config.cmake and/or sqlitet3-config.cmake. + :::image-end::: ## CMake configure step -When significant changes are made to the *`CMakeSettings.json`* or to *`CMakeLists.txt`* files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations. +When significant changes are made to the *`CMakeSettings.json`* or to *`CMakeLists.txt`* files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations. -Multiple CMake projects may use the same CMake configuration name (for example, x86-Debug). All of them are configured and built (in their own build root folder) when that configuration is selected. You can debug the targets from all of the CMake projects that participate in that CMake configuration. +Multiple CMake projects might use the same CMake configuration name (for example, *x86-Debug*). All of them are configured and built (in their own build root folder) when that configuration is selected. You can debug the targets from all of the CMake projects that participate in that CMake configuration. - ![CMake Build Only menu item.](media/cmake-build-only.png "CMake Build Only menu item") + :::image type="complex" source="media/cmake-build-only.png" alt-text="Screenshot of Visual Studio's main menu, open to C Make Build Only."::: + The context menu shows what can be built. In this case hello-cmake-a \ hello-cmake.exe (Project hello-cmake) and hello-cmake-b\hello-cmake.exe (Project hello-cmake). The latter is highlighted. + :::image-end::: You can limit builds and debug sessions to a subset of the projects in the workspace. Create a new configuration with a unique name in the *`CMakeSettings.json`* file. Then, apply the configuration to those projects only. When that configuration is selected, IntelliSense and the build and debug commands only apply to those specified projects. @@ -356,7 +396,7 @@ You can limit builds and debug sessions to a subset of the projects in the works If you need more information about the state of the CMake cache to diagnose a problem, open the **CMake** main menu or the *`CMakeLists.txt`* context menu in **Solution Explorer** to run one of these commands: -- **View Cache** opens the *`CMakeCache.txt`* file from the build root folder in the editor. (Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see [Customize CMake settings](customize-cmake-settings.md).) +- **View Cache** opens the *`CMakeCache.txt`* file from the build root folder in the editor. Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see [Customize CMake settings](customize-cmake-settings.md). - **Open Cache Folder** opens an Explorer window to the build root folder. @@ -370,11 +410,11 @@ Automatic cache generation can be disabled in the **Tools > Options > CMake > Ge To build a single file in a CMake project, right-click on the file in **Solution Explorer**. Choose **Compile** from the pop-up menu. You can also build the currently open file in the editor by using the main **CMake** menu: -![CMake single file compilation.](media/cmake-single-file-compile.png) +:::image type="content" source="media/cmake-single-file-compile.png" alt-text="Screenshot of the C Make Compile context menu. It contains one entry, Bullet 3 Collision."::: ## Run CMake from the command line -If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: +If you installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: 1. Run the appropriate *`vsdevcmd.bat`* file (x86/x64). For more information, see [Building on the Command Line](building-on-the-command-line.md). @@ -390,13 +430,15 @@ In Visual Studio 2015, Visual Studio users can use a [CMake generator](https://c ::: moniker-end -## See also - -[Tutorial: Create C++ cross-platform projects in Visual Studio](get-started-linux-cmake.md)\ -[Configure a Linux CMake project](../linux/cmake-linux-project.md)\ -[Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md)\ -[Customize CMake build settings](customize-cmake-settings.md)\ -[`CMakeSettings.json` schema reference](cmakesettings-reference.md)\ -[Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ -[Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md)\ -[CMake predefined configuration reference](cmake-predefined-configuration-reference.md) +## Related content + +- [Tutorial: Create C++ cross-platform projects in Visual Studio](get-started-linux-cmake.md) +- [Configure a Linux CMake project](../linux/cmake-linux-project.md) +- [Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md) +- [Customize CMake build settings](customize-cmake-settings.md) +- [*`CMakeSettings.json`* schema reference](cmakesettings-reference.md) +- [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md) +- [Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md) +- [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) diff --git a/docs/build/cmake-remote-debugging.md b/docs/build/cmake-remote-debugging.md index 42ff2ab6f4..41645840b3 100644 --- a/docs/build/cmake-remote-debugging.md +++ b/docs/build/cmake-remote-debugging.md @@ -1,8 +1,8 @@ --- title: "Tutorial: Debug a CMake project on a remote Windows machine" +description: "How to use Visual Studio C++ on Windows to create and build a CMake project. You'll then deploy and debug it on a remote Windows machine." ms.date: "12/4/2020" ms.topic: tutorial -description: "How to use Visual Studio C++ on Windows to create and build a CMake project. You'll then deploy and debug it on a remote Windows machine." --- # Tutorial: Debug a CMake project on a remote Windows machine @@ -60,7 +60,7 @@ Select the Visual Studio **Configuration** dropdown and select **Manage Configur ![Choose Manage Configurations in the Visual Studio configurations drop-down.](media/vs2019-cmake-manage-configurations.png) Add a new configuration by selecting **Add a new configuration** (the green **+** button).\ -In the **CMakeSettings** dialog that appears, select **arm64-debug**, and then press **Select**: +In the **CMakeSettings** dialog that appears, select **arm64-debug**, and then choose **Select**: ![Add arm64-debug configuration.](media/cmake-add-config-icon-with-target-dialog.png) @@ -71,13 +71,12 @@ The **Toolset** dropdown is set to **msvc_arm64_x64**. Your settings should now ![CMake settings dialog.](media/cmake-settings-editor2.png) > [!Note] -> In the **Toolset** dropdown, **msvc_arm64** selects 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64** selects 64-bit host tools to cross-compile to ARM64, which is what you'll do in this tutorial. +> In the **Toolset** dropdown, **msvc_arm64** selects 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64** selects 64-bit host tools to cross-compile to ARM64, which is what you'll do in this tutorial. For more information about the available toolset environments, see [Pre-defined environments](cppproperties-schema-reference.md#pre-defined-environments). Save the *`CMakeSettings.json`* file. In the configuration dropdown, select **arm64-debug**. (It may take a moment after saving the *`CMakeSettings.json`* file for it to appear in the list): ![Ensure that arm64-debug is selected in the Visual Studio configurations drop-down.](media/vs2019-cmake-manage-configurations-arm.png) - ## Add a debug configuration file Next, add configuration information that tells Visual Studio where to find your remote machine, along with other configuration details. @@ -116,7 +115,7 @@ For example, on the remote machine, from the Visual Studio Remote Debugger menu Then, in Visual Studio on the host machine, update the *`launch.vs.json`* file to match. For example, if you choose **No Authentication** on the remote debugger, update the *`launch.vs.json`* file in your project by adding `"authenticationType": "none"` to the `configurations` section *`launch.vs.json`*. Otherwise, `"authenticationType"` defaults to `"windows"` and doesn't need to be explicitly stated. This example shows a *`launch.vs.json`* file configured for no authentication: -``` XAML +```XAML { "version": "0.2.1", "defaults": {}, diff --git a/docs/build/cmakesettings-reference.md b/docs/build/cmakesettings-reference.md index 16d3566c71..e9a6acdb8f 100644 --- a/docs/build/cmakesettings-reference.md +++ b/docs/build/cmakesettings-reference.md @@ -145,7 +145,7 @@ If you don't define the `"type"`, the `"STRING"` type is assumed by default. ## Environments -An *environment* encapsulates the environment variables set in the process that Visual Studio uses to invoke CMake. For MSVC projects, it captures the variables set in a [developer command prompt](building-on-the-command-line.md) for a specific platform. For example, the `msvc_x64_x64` environment is the same as running the **Developer Command Prompt for VS 2017** or **Developer Command Prompt for VS 2019** with the **-arch=amd64 -host_arch=amd64** arguments. You can use the `env.{}` syntax in *`CMakeSettings.json`* to reference the individual environment variables, for example to construct paths to folders. The following predefined environments are provided: +An *environment* encapsulates the environment variables set in the process that Visual Studio uses to invoke CMake. For MSVC projects, it captures the variables set in a [developer command prompt](building-on-the-command-line.md) for a specific platform. For example, the `msvc_x64_x64` environment is the same as running the **Developer Command Prompt for VS {version}** with the **-arch=amd64 -host_arch=amd64** arguments. You can use the `env.{}` syntax in *`CMakeSettings.json`* to reference the individual environment variables, for example to construct paths to folders. The following predefined environments are provided: - `linux_arm`: Target ARM Linux remotely. - `linux_x64`: Target x64 Linux remotely. diff --git a/docs/build/common-visual-cpp-arm-migration-issues.md b/docs/build/common-visual-cpp-arm-migration-issues.md index f723c06625..36035c044b 100644 --- a/docs/build/common-visual-cpp-arm-migration-issues.md +++ b/docs/build/common-visual-cpp-arm-migration-issues.md @@ -2,28 +2,30 @@ description: "Learn more about: Common Visual C++ ARM Migration Issues" title: "Common Visual C++ ARM Migration Issues" ms.date: "05/06/2019" -ms.assetid: 0f4c434e-0679-4331-ba0a-cc15dd435a46 --- -# Common Visual C++ ARM Migration Issues +# Common Visual C++ ARM migration issues -When using the Microsoft C++ compiler (MSVC), the same C++ source code might produce different results on the ARM architecture than it does on x86 or x64 architectures. +This document describes some of the common issues that you might encounter when you migrate code from x86 or x64 architectures to the ARM architecture. It also describes how to avoid these issues, and how to use the compiler to help identify them. + +> [!NOTE] +> When this article refers to the ARM architecture, it applies to both ARM32 and ARM64. ## Sources of migration issues Many issues that you might encounter when you migrate code from the x86 or x64 architectures to the ARM architecture are related to source-code constructs that might invoke undefined, implementation-defined, or unspecified behavior. -*Undefined behavior* is behavior that the C++ standard does not define, and that's caused by an operation that has no reasonable result: for example, converting a floating-point value to an unsigned integer, or shifting a value by a number of positions that is negative or exceeds the number of bits in its promoted type. +*Undefined behavior* is behavior that the C++ standard doesn't define, and that's caused by an operation that has no reasonable result: for example, converting a floating-point value to an unsigned integer, or shifting a value by a number of positions that is negative or exceeds the number of bits in its promoted type. *Implementation-defined behavior* is behavior that the C++ standard requires the compiler vendor to define and document. A program can safely rely on implementation-defined behavior, even though doing so might not be portable. Examples of implementation-defined behavior include the sizes of built-in data types and their alignment requirements. An example of an operation that might be affected by implementation-defined behavior is accessing the variable arguments list. -*Unspecified behavior* is behavior that the C++ standard leaves intentionally non-deterministic. Although the behavior is considered non-deterministic, particular invocations of unspecified behavior are determined by the compiler implementation. However, there is no requirement for a compiler vendor to predetermine the result or guarantee consistent behavior between comparable invocations, and there is no requirement for documentation. An example of unspecified behavior is the order in which sub-expressions, which include arguments to a function call, are evaluated. +*Unspecified behavior* is behavior that the C++ standard leaves intentionally nondeterministic. Although the behavior is considered nondeterministic, particular invocations of unspecified behavior are determined by the compiler implementation. However, there's no requirement for a compiler vendor to predetermine the result or guarantee consistent behavior between comparable invocations, and there's no requirement for documentation. An example of unspecified behavior is the order in which sub-expressions, which include arguments to a function call, are evaluated. -Other migration issues can be attributed to hardware differences between ARM and x86 or x64 architectures that interact with the C++ standard differently. For example, the strong memory model of the x86 and x64 architecture gives **`volatile`**-qualified variables some additional properties that have been used to facilitate certain kinds of inter-thread communication in the past. But the ARM architecture's weak memory model doesn't support this use, nor does the C++ standard require it. +Other migration issues can be attributed to hardware differences between ARM and x86 or x64 architectures that interact with the C++ standard differently. For example, the strong memory model of the x86 and x64 architecture gives **`volatile`**-qualified variables some extra properties that have been used to facilitate certain kinds of inter-thread communication in the past. But the ARM architecture's weak memory model doesn't support this use, nor does the C++ standard require it. > [!IMPORTANT] -> Although **`volatile`** gains some properties that can be used to implement limited forms of inter-thread communication on x86 and x64, these additional properties are not sufficient to implement inter-thread communication in general. The C++ standard recommends that such communication be implemented by using appropriate synchronization primitives instead. +> Although **`volatile`** gains some properties that can be used to implement limited forms of inter-thread communication on x86 and x64, these properties aren't sufficient to implement inter-thread communication in general. The C++ standard recommends that such communication be implemented by using appropriate synchronization primitives instead. -Because different platforms might express these kinds of behavior differently, porting software between platforms can be difficult and bug-prone if it depends on the behavior of a specific platform. Although many of these kinds of behavior can be observed and might appear stable, relying on them is at least non-portable, and in the cases of undefined or unspecified behavior, is also an error. Even the behavior that's cited in this document should not be relied on, and could change in future compilers or CPU implementations. +Because different platforms might express these kinds of behavior differently, porting software between platforms can be difficult and bug-prone if it depends on the behavior of a specific platform. Although many of these kinds of behavior can be observed and might appear stable, relying on them is at least non-portable, and in the cases of undefined or unspecified behavior, is also an error. Even the behavior cited in this document shouldn't be relied on, and could change in future compilers or CPU implementations. ## Example migration issues @@ -41,15 +43,15 @@ These platforms also differ in how they handle conversion of NaN (Not-a-Number) Floating-point conversion can only be relied on if you know that the value is within the range of the integer type that it's being converted to. -### Shift operator (\<\< >>) behavior +### Shift operator (`<<` `>>`) behavior -On the ARM architecture, a value can be shifted left or right up to 255 bits before the pattern begins to repeat. On x86 and x64 architectures, the pattern is repeated at every multiple of 32 unless the source of the pattern is a 64-bit variable; in that case, the pattern repeats at every multiple of 64 on x64, and every multiple of 256 on x86, where a software implementation is employed. For example, for a 32-bit variable that has a value of 1 shifted left by 32 positions, on ARM the result is 0, on x86 the result is 1, and on x64 the result is also 1. However, if the source of the value is a 64-bit variable, then the result on all three platforms is 4294967296, and the value doesn't "wrap around" until it's shifted 64 positions on x64, or 256 positions on ARM and x86. +On the ARM architecture, a value can be shifted left or right up to 255 bits before the pattern begins to repeat. On x86 and x64 architectures, the pattern is repeated at every multiple of 32 unless the source of the pattern is a 64-bit variable. In that case, the pattern repeats at every multiple of 64 on x64, and every multiple of 256 on x86, where a software implementation is employed. For example, for a 32-bit variable that has a value of 1 shifted left by 32 positions, on ARM the result is 0, on x86 the result is 1, and on x64 the result is also 1. However, if the source of the value is a 64-bit variable, then the result on all three platforms is 4294967296, and the value doesn't "wrap around" until it's shifted 64 positions on x64, or 256 positions on ARM and x86. -Because the result of a shift operation that exceeds the number of bits in the source type is undefined, the compiler is not required to have consistent behavior in all situations. For example, if both operands of a shift are known at compile time, the compiler may optimize the program by using an internal routine to precompute the result of the shift and then substituting the result in place of the shift operation. If the shift amount is too large, or negative, the result of the internal routine might be different than the result of the same shift expression as executed by the CPU. +Because the result of a shift operation that exceeds the number of bits in the source type is undefined, the compiler isn't required to have consistent behavior in all situations. For example, if both operands of a shift are known at compile time, the compiler may optimize the program by using an internal routine to precompute the result of the shift and then substituting the result in place of the shift operation. If the shift amount is too large, or negative, the result of the internal routine might be different than the result of the same shift expression as executed by the CPU. ### Variable arguments (varargs) behavior -On the ARM architecture, parameters from the variable arguments list that are passed on the stack are subject to alignment. For example, a 64-bit parameter is aligned on a 64-bit boundary. On x86 and x64, arguments that are passed on the stack are not subject to alignment and pack tightly. This difference can cause a variadic function like `printf` to read memory addresses that were intended as padding on ARM if the expected layout of the variable arguments list is not matched exactly, even though it might work for a subset of some values on the x86 or x64 architectures. Consider this example: +On the ARM architecture, parameters from the variable arguments list that are passed on the stack are subject to alignment. For example, a 64-bit parameter is aligned on a 64-bit boundary. On x86 and x64, arguments that are passed on the stack aren't subject to alignment and pack tightly. This difference can cause a variadic function like `printf` to read memory addresses that were intended as padding on ARM if the expected layout of the variable arguments list isn't matched exactly, even though it might work for a subset of some values on the x86 or x64 architectures. Consider this example: ```C // notice that a 64-bit integer is passed to the function, but '%d' is used to read it. @@ -69,7 +71,7 @@ printf("%I64d\n", 1LL); Because ARM, x86, and x64 processors are so different, they can present different requirements to compiler implementations, and also different opportunities for optimizations. Because of this, together with other factors like calling-convention and optimization settings, a compiler might evaluate function arguments in a different order on different architectures or when the other factors are changed. This can cause the behavior of an app that relies on a specific evaluation order to change unexpectedly. -This kind of error can occur when arguments to a function have side effects that impact other arguments to the function in the same call. Usually this kind of dependency is easy to avoid, but it can sometimes be obscured by dependencies that are difficult to discern, or by operator overloading. Consider this code example: +This kind of error can occur when arguments to a function have side effects that impact other arguments to the function in the same call. Usually this kind of dependency is easy to avoid but can be obscured by dependencies that are difficult to discern or by operator overloading. Consider this code example: ```cpp handle memory_handle; @@ -83,15 +85,15 @@ This appears well-defined, but if `->` and `*` are overloaded operators, then th Handle::acquire(operator->(memory_handle), operator*(p)); ``` -And if there's a dependency between `operator->(memory_handle)` and `operator*(p)`, the code might rely on a specific evaluation order, even though the original code looks like there is no possible dependency. +And if there's a dependency between `operator->(memory_handle)` and `operator*(p)`, the code might rely on a specific evaluation order, even though the original code looks like there's no possible dependency. -### volatile keyword default behavior +### `volatile` keyword default behavior The MSVC compiler supports two different interpretations of the **`volatile`** storage qualifier that you can specify by using compiler switches. The [/volatile:ms](reference/volatile-volatile-keyword-interpretation.md) switch selects the Microsoft extended volatile semantics that guarantee strong ordering, as has been the traditional case for x86 and x64 because of the strong memory model on those architectures. The [/volatile:iso](reference/volatile-volatile-keyword-interpretation.md) switch selects the strict C++ standard volatile semantics that don't guarantee strong ordering. -On the ARM architecture, the default is **/volatile:iso** because ARM processors have a weakly ordered memory model, and because ARM software doesn't have a legacy of relying on the extended semantics of **/volatile:ms** and doesn't usually have to interface with software that does. However, it's still sometimes convenient or even required to compile an ARM program to use the extended semantics. For example, it may be too costly to port a program to use the ISO C++ semantics, or driver software might have to adhere to the traditional semantics to function correctly. In these cases, you can use the **/volatile:ms** switch; however, to recreate the traditional volatile semantics on ARM targets, the compiler must insert memory barriers around each read or write of a **`volatile`** variable to enforce strong ordering, which can have a negative impact on performance. +On the ARM architecture (except ARM64EC), the default is **/volatile:iso** because ARM processors have a weakly ordered memory model, and because ARM software doesn't have a legacy of relying on the extended semantics of **/volatile:ms** and doesn't usually have to interface with software that does. However, it's still sometimes convenient or even required to compile an ARM program to use the extended semantics. For example, it may be too costly to port a program to use the ISO C++ semantics, or driver software might have to adhere to the traditional semantics to function correctly. In these cases, you can use the **/volatile:ms** switch; however, to recreate the traditional volatile semantics on ARM targets, the compiler must insert memory barriers around each read or write of a **`volatile`** variable to enforce strong ordering, which can have a negative impact on performance. -On the x86 and x64 architectures, the default is **/volatile:ms** because much of the software that has already been created for these architectures by using MSVC relies on them. When you compile x86 and x64 programs, you can specify the **/volatile:iso** switch to help avoid unnecessary reliance on the traditional volatile semantics, and to promote portability. +On the x86, x64, and ARM64EC architectures, the default is **/volatile:ms** because much of the software that has already been created for these architectures by using MSVC relies on them. When you compile x86, x64 and ARM64EC programs, you can specify the **/volatile:iso** switch to help avoid unnecessary reliance on the traditional volatile semantics, and to promote portability. ## See also diff --git a/docs/build/compare-inclusion-methods.md b/docs/build/compare-inclusion-methods.md new file mode 100644 index 0000000000..8c16032aee --- /dev/null +++ b/docs/build/compare-inclusion-methods.md @@ -0,0 +1,43 @@ +--- +description: "Learn about the different ways to include library headers in C++: header files vs modules vs header units vs precompiled headers." +title: "Compare header units, modules, and precompiled headers" +ms.date: 11/30/2022 +f1_keywords: ["#include", "header file", "header unit", "module", "named module", "PCH", "precompiled header file", "IFC"] +helpviewer_keywords: ["headers, C++ library", "libraries, Standard C++", "C++ Standard Library, headers", "STL", "Standard template library, headers", "precompiled header files, creating", "PCH files, creating", "import", "header unit", "ifc", "modules [C++]", "named modules [C++]", "import standard library (STL) using named modules"] +--- +# Compare header units, modules, and precompiled headers + +Historically, you'd include the standard library with a directive like `#include `. However, it's expensive to include header files because they're reprocessed by every source file that includes them. + +Precompiled headers (PCH) were introduced to speed compilation by translating them once and reusing the result. But precompiled headers can be difficult to maintain. + +In C++20, modules were introduced as a significant improvement on header files and precompiled headers. + +Header units were introduced in C++20 as a way to temporarily bridge the gap between header files and modules. They provide some of the speed and robustness benefits of modules, while you migrate your code to use modules. + +Then, the C++23 standard library introduced support for importing the standard library as named modules. This is the fastest and most robust way to consume the standard library. + +To help you sort out the different options, this article compares the traditional `#include` method against precompiled headers, header units, and importing named modules. + +The following table is arranged by compiler processing speed and robustness, with `#include` being the slowest and least robust, and `import` being the fastest and most robust. + +| Method | Summary | +|---|---| +| `#include` | One disadvantage is that they expose macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore. That's a convention to indicate that something is part of the internal implementation and shouldn't be used.

Header files are fragile because the order of #includes can modify behavior or break code and are affected by macro definitions.

Header files slow compilation. Particularly when multiple files include the same file because then the header file is reprocessed multiple times. | +| [Precompiled header](../build/creating-precompiled-header-files.md) | A precompiled header (PCH) improves compile time by creating a compiler memory snapshot of a set of header files. This is an improvement on repeatedly rebuilding header files.

PCH files have restrictions that make them difficult to maintain.

PCH files are faster than `#include` but slower than `import`.| +| [Header units](../build/walkthrough-header-units.md) | This is a new feature in C++20 that allows you to import 'well-behaved' header files as modules.

Header units are faster than `#include`, and are easier to maintain, significantly smaller, and also faster than pre-compiled header files (PCH).

Header units are an 'in-between' step meant to help transition to named modules in cases where you rely on macros defined in header files, since named modules don't expose macros.

Header units are slower than importing a named module.

Header units aren't affected by macro defines unless they're specified on the command line when the header unit is built--making them more robust than header files.

Header units expose the macros and internal implementation defined in them just as header file do, which named modules don't.

As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file. | +| [Modules](../cpp/modules-cpp.md) | This is the fastest and most robust way to import functionality.

Support for importing modules was introduced in C++20. The C++23 standard library introduces the two named modules described in this topic.

When you import `std`, you get the standard names such as `std::vector`, `std::cout`, but no extensions, no internal helpers such as `_Sort_unchecked`, and no macros.

The order of imports doesn't matter because there are no macro or other side-effects.

As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file, which might be represented by a 25-megabyte module.

Named modules are faster because when a named module is compiled into an `.ifc` file and an `.obj` file, the compiler emits a structured representation of the source code that can be loaded quickly when the module is imported. The compiler can do some work (like name resolution) before emitting the `.ifc` file because of how named modules are order-independent and macro-independent--so this work doesn't have to be done when the module is imported. In contrast, when a header file is consumed with `#include`, its contents must be preprocessed and compiled again and again in every translation unit.

Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. | + +If you can use C++20 features and the C++23 standard library in your app, use named modules. + +If you can use C++20 features but want to transition over time to modules, use header units in the interim. + +If you can't use C++20 features, use `#include` and consider precompiled headers. + +## See also + +[Precompiled header files](creating-precompiled-header-files.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)\ +[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md) \ No newline at end of file diff --git a/docs/build/configure-cmake-debugging-sessions.md b/docs/build/configure-cmake-debugging-sessions.md index 724048132e..896d5a3bf4 100644 --- a/docs/build/configure-cmake-debugging-sessions.md +++ b/docs/build/configure-cmake-debugging-sessions.md @@ -1,7 +1,7 @@ --- title: "Configure CMake debugging sessions in Visual Studio" description: "Describes how to use Visual Studio to configure CMake debugger settings." -ms.date: 12/16/2020 +ms.date: 10/26/2023 helpviewer_keywords: ["CMake debugging"] --- # Configure CMake debugging sessions @@ -16,14 +16,28 @@ Native CMake support is available in Visual Studio 2017 and later. To see the do All executable CMake targets are shown in the **Startup Item** dropdown in the toolbar. Select one to start a debugging session and launch the debugger. -![Screenshot of the CMake startup item dropdown.](media/cmake-startup-item-dropdown.png "CMake startup item dropdown") +:::image type="complex" source="media/new-dropdowns.png" alt-text="Screenshot of the CMake startup items dropdown."::: +The dropdown provides a list of debug targets to choose from. The selected item appears as a play button followed by the name of the selected debug target to run. In this example, the selected debug target is Hello World .exe. +:::image-end::: You can also start a debug session from Solution Explorer. First, switch to **CMake Targets View** in the **Solution Explorer** window. -![Screenshot of the CMake targets view command.](media/cmake-targets-view.png "CMake Targets View menu item") +:::image type="complex" source="media/switch-to-targets-view.png" alt-text="Screenshot of the CMake Targets View menu."::: +The solution explorer is shown. A right-click on an item in the Folder View has opened a menu that shows options such as Open, Open with, Compare with, and so on. The Switch to Targets View menu item is highlighted. +:::image-end::: Then, right-click on an executable and select **Debug**. This command automatically starts debugging the selected target based on your active configuration. +:::image type="complex" source="media/debug-targets-view.png" alt-text="Screenshot of the CMake Targets View debug option menu."::: +A right-click on a target in the CMake Targets view has opened a menu with options such as Set as Startup item, Build, Clean All, and so on. The Debug menu option is highlighted. +:::image-end::: + +Starting in Visual Studio 2022 Version 17.6, you can also start a debugging session on your CMakeLists.txt file. To do so, just set a breakpoint in your CMakeLists.txt file and run **Configure Project with CMake Debugger** from the **Project** dropdown. + +:::image type="complex" source="media/cmake-debugger-entry.png" alt-text="Screenshot of the CMake Debugger dropdown."::: +The Project dropdown is shown. The menu option to Configure Project with CMake debugger is highlighted. +:::image-end::: + ## Customize debugger settings You can customize the debugger settings for any executable CMake target in your project. They're found in a configuration file called *launch.vs.json*, located in a *`.vs`* folder in your project root. A launch configuration file is useful in most debugging scenarios, because you can configure and save your debugging setup details. There are three entry points to this file: @@ -111,7 +125,8 @@ In Visual Studio 2019 version 16.6, we added a new debug configuration of `type: - `remoteMachineName`: Defaults to `"${debugInfo.remoteMachineName}"`. Name of the remote system that hosts the program to debug. Only required if different than the build system. Must have an existing entry in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md). Press **Ctrl+Space** to view a list of all existing remote connections. - `cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. Full Unix path to the directory on the remote system where `program` is run. The directory must exist. -- `gdbPath`: Defaults to `${debugInfo.vsInstalledGdb}`. Full Windows path to the `gdb` used to debug. Defaults to the `gdb` installed with the Linux development with C/C++ workload. +- `gdbPath`: Full Windows path to the `gdb` used to debug. + - `gdbserverPath`: Defaults to `usr/bin/gdbserver`. Full Unix path to the `gdbserver` used to debug. - `preDebugCommand`: A Linux command to run immediately before starting `gdbserver`. `gdbserver` doesn't start until the command completes. diff --git a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md index 94614dd10f..fc99baa1b2 100644 --- a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md +++ b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md @@ -2,7 +2,6 @@ description: "Learn more about: Configure C++ projects for ARM processors" title: "Configure C++ projects for ARM processors" ms.date: "07/11/2018" -ms.assetid: 3d95f221-656a-480d-9651-9ad263895747 --- # Configure C++ projects for ARM processors @@ -17,7 +16,7 @@ Describes the application binary interface used by Windows on ARM for register u Describes the application binary interface used by Windows on ARM64 for register usage, calling conventions and exception handling. [Common MSVC ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ -Describes C++ code elements that are commonly assumed to be portable across architectures, but which produce different results for ARM than for x86 and x64. +Describes C++ code elements that are commonly assumed to be portable across architectures, but that produce different results for ARM than for x86 and x64. [ARM exception handling](arm-exception-handling.md)\ Describes the encoding scheme for stack unwinding during structured exception handling in Windows on ARM. @@ -27,8 +26,14 @@ Describes the encoding scheme for stack unwinding during structured exception ha ## Related Sections +[Get started with Arm64EC](/windows/arm/arm64ec-build)\ +Describes how to get started building your app or project using [Arm64EC](/windows/arm/arm64ec). + +[How to: Configure projects to target platforms](/visualstudio/ide/how-to-configure-projects-to-target-platforms)\ +Describes how to set up your build to target different processor architectures, including Arm64. + [ARM intrinsics](../intrinsics/arm-intrinsics.md)\ Describes compiler intrinsics for processors that use the ARM architecture. -[ARM64 intrinsics](../intrinsics/arm-intrinsics.md)\ +[ARM64 intrinsics](../intrinsics/arm64-intrinsics.md)\ Describes compiler intrinsics for processors that use the ARM64 architecture. diff --git a/docs/build/configuring-programs-for-windows-xp.md b/docs/build/configuring-programs-for-windows-xp.md index 36e80bf241..3e96c4f48e 100644 --- a/docs/build/configuring-programs-for-windows-xp.md +++ b/docs/build/configuring-programs-for-windows-xp.md @@ -47,7 +47,7 @@ Along with the Windows XP platform toolset, several libraries include runtime su - Universal C Runtime Library (UCRT) - C++ Standard Library - Active Template Library (ATL) -- Concurrency Runtime Library (ConCRT) +- Concurrency Runtime Library (ConcRT) - Parallel Patterns Library (PPL) - Microsoft Foundation Class Library (MFC) - C++ AMP (C++ Accelerated Massive Programming) library. @@ -61,7 +61,7 @@ These libraries are supported by the platform toolsets installed by Visual Studi |CRT|X|X|X| |C++ Standard Library|X|X|X| |ATL|X|X|X| -|ConCRT/PPL|X|X|X| +|ConcRT/PPL|X|X|X| |MFC|X||X| |C++ AMP|X|X|| diff --git a/docs/build/cppproperties-schema-reference.md b/docs/build/cppproperties-schema-reference.md index 59e6b45f77..cafd37a1e7 100644 --- a/docs/build/cppproperties-schema-reference.md +++ b/docs/build/cppproperties-schema-reference.md @@ -1,28 +1,28 @@ --- description: "Learn more about: CppProperties.json reference" title: "CppProperties.json reference" -ms.date: "08/09/2019" +ms.date: 09/19/2022 helpviewer_keywords: ["CppProperties.json file [C++]"] --- -# CppProperties.json reference +# `CppProperties.json` reference -Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *CppProperties.json* file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. See [Open Folder projects for C++](open-folder-projects-cpp.md) for more information about how to add configurations in an Open Folder project. The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *CppProperties.json* is open. +Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *`CppProperties.json`* file. (CMake projects use a [`CMakeSettings.json`](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. For more information about how to add configurations in an Open Folder project, see [Open Folder projects for C++](open-folder-projects-cpp.md). The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *`CppProperties.json`* is open. ## Configuration properties A configuration may have any of the following properties: -|Name|Description| -|-|-| -|`inheritEnvironments`| Specifies which environments apply to this configuration.| -|`name`|The configuration name that will appear in the C++ configuration dropdown| -|`includePath`|A comma-separated list of folders that should be specified in the include path (maps to /I for most compilers)| -|`defines`|The list of macros that should be defined (maps to /D for most compilers)| -|`compilerSwitches`|One or more additional switches that can influence IntelliSense behavior| -|`forcedInclude`|Header to be automatically included in every compilation unit (maps to /FI for MSVC or -include for clang)| -|`undefines`|The list of macros to be undefined (maps to /U for MSVC)| -|`intelliSenseMode`|The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang.| -|`environments`|User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the ${env.\} macro.| +| Name | Description | +|--|--| +| `inheritEnvironments` | Specifies which environments apply to this configuration. | +| `name` | The configuration name that will appear in the C++ configuration dropdown | +| `includePath` | A comma-separated list of folders that should be specified in the include path (maps to `/I` for most compilers) | +| `defines` | The list of macros that should be defined (maps to `/D` for most compilers) | +| `compilerSwitches` | One or more additional switches that can influence IntelliSense behavior | +| `forcedInclude` | Header to be automatically included in every compilation unit (maps to `/FI` for MSVC or `-include` for clang) | +| `undefines` | The list of macros to be undefined (maps to `/U` for MSVC) | +| `intelliSenseMode` | The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang. | +| `environments` | User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the `${env.VARIABLE}` macro. | ### intelliSenseMode values @@ -30,58 +30,58 @@ The code editor shows the available options when you start to type: ![Screenshot of the IntelliSense pop-up in the editor.](media/open-folder-intellisense-mode.png "Open Folder IntelliSense") -These are the supported values: - -- windows-msvc-x86 -- windows-msvc-x64 -- windows-msvc-arm -- windows-msvc-arm64 -- android-clang-x86 -- android-clang-x64 -- android-clang-arm -- android-clang-arm64 -- ios-clang-x86 -- ios-clang-x64 -- ios-clang-arm -- ios-clang-arm64 -- windows-clang-x86 -- windows-clang-x64 -- windows-clang-arm -- windows-clang-arm64 -- linux-gcc-x86 -- linux-gcc-x64 -- linux-gcc-arm +This list shows the supported values: + +- `windows-msvc-x86` +- `windows-msvc-x64` +- `windows-msvc-arm` +- `windows-msvc-arm64` +- `android-clang-x86` +- `android-clang-x64` +- `android-clang-arm` +- `android-clang-arm64` +- `ios-clang-x86` +- `ios-clang-x64` +- `ios-clang-arm` +- `ios-clang-arm64` +- `windows-clang-x86` +- `windows-clang-x64` +- `windows-clang-arm` +- `windows-clang-arm64` +- `linux-gcc-x86` +- `linux-gcc-x64` +- `linux-gcc-arm` Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only. Use the `windows-msvc-*` variants instead. ## Pre-defined Environments -Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: ${env.\}. +Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: `${env.VARIABLE}`. -|Variable Name|Description| -|-----------|-----------------| -|vsdev|The default Visual Studio environment| -|msvc_x86|Compile for x86 using x86 tools| -|msvc_x64|Compile for AMD64 using 64-bit tools| -|msvc_arm|Compile for ARM using x86 tools| -|msvc_arm64|Compile for ARM64 using x86 tools| -|msvc_x86_x64|Compile for AMD64 using x86 tools| -|msvc_arm_x64|Compile for ARM using 64-bit tools| -|msvc_arm64_x64|Compile for ARM64 using 64-bit tools| +| Variable Name | Description | +|--|--| +| `vsdev` | The default Visual Studio environment | +| `msvc_x86` | Compile for x86 using x86 tools | +| `msvc_x64` | Compile for AMD64 using 64-bit tools | +| `msvc_arm` | Compile for ARM using x86 tools | +| `msvc_arm64` | Compile for ARM64 using x86 tools | +| `msvc_x86_x64` | Compile for AMD64 using x86 tools | +| `msvc_arm_x64` | Compile for ARM using 64-bit tools | +| `msvc_arm64_x64` | Compile for ARM64 using 64-bit tools | When the Linux workload is installed, the following environments are available for remotely targeting Linux and WSL: -|Variable Name|Description| -|-----------|-----------------| -|linux_x86|Target x86 Linux remotely| -|linux_x64|Target x64 Linux remotely| -|linux_arm|Target ARM Linux remotely| +| Variable Name | Description | +|--|--| +| `linux_x86` | Target x86 Linux remotely | +| `linux_x64` | Target x64 Linux remotely | +| `linux_arm` | Target ARM Linux remotely | ## User-defined environments -You can optionally use the `environments` property to define sets of variables in *CppProperties.json* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed with the ${env.\} syntax from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. +You can optionally use the `environments` property to define sets of variables in *`CppProperties.json`* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project. You can access them with the `${env.VARIABLE}` syntax from *`tasks.vs.json`* and *`launch.vs.json`* after they're defined here. However, they aren't necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. -**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *CppProperties.json* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *CppProperties.json*. +**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *`CppProperties.json`* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *`CppProperties.json`*. **Visual Studio 2019 version 16.3 and earlier:** When you consume an environment, then you have to specify it in the `inheritsEnvironments` property even if the environment is defined as part of the same configuration; the `environment` property specifies the name of the environment. The following example shows a sample configuration for enabling IntelliSense for GCC in an MSYS2 installation. Note how the configuration both defines and inherits the `mingw_64` environment, and how the `includePath` property can access the `INCLUDE` variable. @@ -113,21 +113,21 @@ You can optionally use the `environments` property to define sets of variables i ] ``` -When you define an **environments** property inside a configuration, it overrides any global variables of the same name. +When you define an `"environments"` property inside a configuration, it overrides any global variables that have the same names. ## Built-in macros -You have access to the following built-in macros inside *CppProperties.json*: +You have access to the following built-in macros inside *`CppProperties.json`*: -|Macro|Description| -|-|-| -|`${workspaceRoot}`| The full path to the workspace folder| -|`${projectRoot}`| The full path to the folder where *CppProperties.json* is placed| -|`${env.vsInstallDir}`| The full path to the folder where the running instance of Visual Studio is installed| +| Macro | Description | +|--|--| +| `${workspaceRoot}` | The full path to the workspace folder | +| `${projectRoot}` | The full path to the folder where *`CppProperties.json`* is placed | +| `${env.vsInstallDir}` | The full path to the folder where the running instance of Visual Studio is installed | ### Example -If your project has an include folder and also includes *windows.h* and other common headers from the Windows SDK, you may want to update your *CppProperties.json* configuration file with the following includes: +If your project has an include folder and also includes `*windows.h`* and other common headers from the Windows SDK, you may want to update your *`CppProperties.json`* configuration file with the following includes: ```json { @@ -136,28 +136,28 @@ If your project has an include folder and also includes *windows.h* and other co "name": "Windows", "includePath": [ // local include folder - "${workspaceRoot}\include", + "${workspaceRoot}\\include", // Windows SDK and CRT headers - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\ucrt", - "${env.NETFXSDKDir}\include\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\shared", - "${env.VCToolsInstallDir}\include" + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\ucrt", + "${env.NETFXSDKDir}\\include\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\shared", + "${env.VCToolsInstallDir}\\include" ] } ] } ``` -> [!Note] -> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables so make sure you start devenv.exe from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu.) +> [!NOTE] +> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables. Make sure you start *`devenv.exe`* from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu to find a Developer Command Prompt shortcut.) ## Troubleshoot IntelliSense errors -If you are not seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. +If you aren't seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. ![Screenshot of the Diagnostic logging settings in the Options dialog.](media/diagnostic-logging.png) -Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *CppProperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data. +Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths don't match the ones in *`CppProperties.json`*, try closing the folder and deleting the *`.vs`* subfolder that contains cached browsing data. -To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** and filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". +To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** tab, and then filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". diff --git a/docs/build/create-reusable-property-configurations.md b/docs/build/create-reusable-property-configurations.md index f9f7157a8c..d046426504 100644 --- a/docs/build/create-reusable-property-configurations.md +++ b/docs/build/create-reusable-property-configurations.md @@ -1,45 +1,45 @@ --- description: "Learn more about: Share or reuse Visual Studio project settings" title: "Share or reuse Visual Studio project settings - C++" -ms.date: "07/17/2019" +ms.date: 02/07/2022 helpviewer_keywords: ["project properties [C++], reusable"] --- # Share or reuse Visual Studio project settings -To create a custom group of settings that you can share with others or reuse in multiple projects, use **Property Manager** to create a *property sheet* (.props file) to store the settings for each kind of project that you want to be able to reuse or share with others. Using property sheets are far less error-prone than other ways of creating "global" settings. +To create a custom group of settings that you can share with others or reuse in multiple projects, use **Property Manager** to create a *property sheet* (a *`.props`* file) to store the settings for each kind of project that you want to be able to reuse or share with others. Using property sheets are far less error-prone than other ways of creating "global" settings. > [!IMPORTANT] -> **.user files and why they are problematic** +> **The problem with *`*.user`* files** > -> Past versions of Visual Studio used global property sheets that had a .user file name extension and were located in the \\AppData\Local\Microsoft\MSBuild\v4.0\ folder. We no longer recommend these files because they set properties for project configurations on a per-user, per-computer basis. Such "global" settings can interfere with builds, especially when you are targeting more than one platform on your build computer. For example, if you have both an MFC project and Windows Phone project, the .user properties would be invalid for one of them. Reusable property sheets are more flexible and more robust. +> Past versions of Visual Studio used global property sheets that had a *`.user`* file name extension and were located in the *`\\AppData\Local\Microsoft\MSBuild\v4.0\`* folder. We no longer recommend these files because they set properties for project configurations on a per-user, per-computer basis. Such "global" settings can interfere with builds, especially when you are targeting more than one platform on your build computer. For example, if you have both an MFC project and Windows Phone project, the *`.user`* properties would be invalid for one of them. Reusable property sheets are more flexible and more robust. > -> Although .user files are still installed by Visual Studio and participate in property inheritance, they are empty by default. The best practice is to delete the reference to them in **Property Manager** to ensure that your projects operate independently of any per-user, per-computer settings This is important to ensure correct behavior in a SCC (source code control) environment. +> Although *`.user`* files are still installed by Visual Studio and participate in property inheritance, they're empty by default. The best practice is to delete any reference to them in **Property Manager** to ensure that your projects operate independently of any per-user, per-computer settings. This practice is important to ensure correct behavior in a SCC (source code control) environment. To display **Property Manager**, on the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**, depending on your settings. -If you have a common, frequently used set of properties that you want to apply to multiple projects, you can use **Property Manager** to capture them in a reusable *property sheet* file, which by convention has a .props file name extension. You can apply the sheet (or sheets) to new projects so that you don't have to set its properties from scratch. +If you want to apply a common, frequently used set of properties to multiple projects, you can use **Property Manager** to capture them in a reusable *property sheet* file, which by convention has a *`.props`* file name extension. You can apply the sheet (or sheets) to new projects so you don't have to set those properties from scratch. ![Screenshot of the Property Manager shortcut menu.](media/sharingnew.png "SharingNew") -Under each configuration node, you see nodes for each property sheet that applies to that configuration. The system adds property sheets that set values based on options you choose in the app wizard when you create the project. Right-click any node and choose Properties to see the properties that apply to that node. All the property sheets are imported automatically into the project's "master" property sheet (ms.cpp.props) and are evaluated in the order they appear in Property Manager. You can move them to change the evaluation order. Property sheets that are evaluated later will override the values in previously-evaluated sheets. See [Project property inheritance](project-property-inheritance.md) for more information about the order of evaluation in the .vcxproj file, the .props and .targets files, environment variables and the command line. +Under each configuration node, you see nodes for each property sheet that applies to that configuration. The system adds property sheets that set common values based on options you choose in the app wizard when you create the project. Right-click any node and choose Properties to see the properties that apply to that node. All the property sheets are imported automatically into the project's primary property sheet (*`ms.cpp.props`*) and are evaluated in the order they appear in Property Manager. You can move them to change the evaluation order. Property sheets that are evaluated later override the values in previously evaluated sheets. For more information about the order of evaluation in the *`.vcxproj`* file, the *`.props`* and *`.targets`* files, environment variables, and the command line, see [Project property inheritance](project-property-inheritance.md). If you choose **Add New Project Property Sheet** and then select, for example, the MyProps.props property sheet, a property page dialog box appears. Notice that it applies to the MyProps property sheet; any changes you make are written to the sheet, not to the project file (.vcxproj). -Properties in a property sheet are overridden if the same property is set directly in the .vcxproj file. +Properties in a property sheet are overridden if the same property is set directly in the *`.vcxproj`* file. You can import a property sheet as often as required. Multiple projects in a solution can inherit settings from the same property sheet, and a project can have multiple sheets. A property sheet itself can inherit settings from another property sheet. -You can also create one property sheet for multiple configurations. To do this, create a property sheet for each configuration, open the shortcut menu for one of them, choose **Add Existing Property Sheet**, and then add the other sheets. However, if you use one common property sheet, be aware that when you set a property, it gets set for all configurations that the sheet applies to, and that the IDE doesn't show which projects or other property sheets are inheriting from a given property sheet. +You can also create a common property sheet for multiple configurations. To create a property sheet for each configuration, open the shortcut menu for one of them, choose **Add Existing Property Sheet**, and then add the other sheets. However, if you use a common property sheet, properties you set for all configurations that the sheet applies to. The IDE doesn't show which projects or other property sheets inherit from a given property sheet. -In large solutions that will have many projects, it can be useful to create a property sheet at the solution level. When you add a project to the solution, use **Property Manager** to add that property sheet to the project. If required at the project level, you can add a new property sheet to set project-specific values. +In large solutions that have many projects, it can be useful to create a common property sheet for all the projects in the solution. Create the property sheet as usual. Use **Property Manager** to add that property sheet to each project in the solution. If necessary at the project level, you can add another property sheet to set project-specific values. > [!IMPORTANT] -> A .props file by default does not participate in source control because it isn't created as a project item. You can manually add the file as a solution item if you want to include it in source control. +> A *`.props`* file by default does not participate in source control because it isn't created as a project item. You can manually add the file as a solution item if you want to include it in source control. #### To create a property sheet 1. On the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**. The **Property Manager** opens. -2. To define the scope of the property sheet, select the item to which it applies. This can be a particular configuration, or another property sheet. Open the shortcut menu for this item and then choose **Add New Project Property Sheet**. Specify a name and location. +2. To define the scope of the property sheet, select the item to which it applies. This item can be a particular configuration, or another property sheet. Open the shortcut menu for this item and then choose **Add New Project Property Sheet**. Specify a name and location. 3. In **Property Manager**, open the new property sheet and then set the properties you want to include. diff --git a/docs/build/creating-and-managing-visual-cpp-projects.md b/docs/build/creating-and-managing-visual-cpp-projects.md index f6fa4c479e..2441a8b327 100644 --- a/docs/build/creating-and-managing-visual-cpp-projects.md +++ b/docs/build/creating-and-managing-visual-cpp-projects.md @@ -1,80 +1,92 @@ --- -description: "Learn more about: Visual Studio projects - C++" -title: "Visual Studio Projects - C++" -ms.date: "10/25/2019" -helpviewer_keywords: ["ATL projects, creating", "Visual Studio C++ projects, creating", "projects [C++], creating", "Visual Studio C++ projects", "ATL projects"] -ms.assetid: 11003cd8-9046-4630-a189-a32bf3b88047 +title: "Create and Configure Visual Studio C++ Projects" +description: "Learn how to create a Visual Studio C++ project, and then add code and build your project." +ms.date: 03/24/2025 +ms.topic: concept-article +helpviewer_keywords: ["Visual Studio C++ projects, creating", "projects [C++], creating", "Visual Studio C++ projects"] --- -# Visual Studio projects - C++ +# Visual Studio C++ projects -A *Visual Studio project* is a project based on the MSBuild build system. MSBuild is the native build system for Visual Studio and is generally the best build system to use for Windows-specific programs. MSBuild is tightly integrated with Visual Studio, but you can also use it from the command line. For cross-platform projects, or projects that use open-source libraries, we recommend using [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md) in Visual Studio 2017 and later. For information about upgrading MSBuild projects from older versions of Visual Studio, see the [Microsoft C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md). +A *Visual Studio project* is a collection of code files and assets such as icons, images, and so on, that are built together using the MSBuild system. MSBuild is the native build system for Visual Studio and is generally the best build system to use for Windows-specific programs. MSBuild is tightly integrated with Visual Studio, but you can also use it from the command line. -## Create a project +For information about upgrading MSBuild projects from older versions of Visual Studio, see the [Microsoft C++ porting and upgrading guide](../porting/visual-cpp-porting-and-upgrading-guide.md). + +For cross-platform projects, or projects that use open-source libraries, we recommend using [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md). + +## Create a Visual Studio C++ project ::: moniker range=">=msvc-160" -You can create C++ projects by choosing **File** > **New** > **Project**, then setting the **Language** to C++. In the results list you see a list of project templates which you can filter by setting the **Platform** or **Project Type** and by typing keywords into the search box. +1. Create a C++ project by choosing **File** > **New** > **Project**. + +1. In the **Create a new project** dialog, set the **Language** dropdown to **C++**. This filters the list of project templates to C++ projects. You can filter the templates by setting the **Platform**, **Project Type**, or by entering keywords in the search box. - ![Screenshot of the Create a new project wizard in Visual Studio.](../build/media/vs2019-choose-console-app.png "Visual Studio 2019 New Project Dialog") + :::image type="content" source="../build/media/vs2019-choose-console-app.png" alt-text="Screenshot of the Create a new project wizard. The Console App project template is selected."::: + +1. Select a project template, then choose **Next**. + +1. On the **Configure your new project page**, enter project-specific settings such as the project name or location and then choose **Create** to create your project. ::: moniker-end ::: moniker range="msvc-150" -You can create C++ projects by choosing **File** > **New** > **Project**, then choosing Visual C++ in the left pane. In the center pane you see a list of project templates: - - ![Screenshot of the New Project dialog, showing available project templates.](../overview/media/vs2017-new-project.png "Visual Studio 2017 New Project Dialog") +1. Create a C++ project by choosing **File** > **New** > **Project**. -::: moniker-end +1. Choose **Visual C++** in the left pane. In the center pane, a list of project templates appears: -For more information about all the default project templates that are included in Visual Studio, see [C++ project templates in Visual Studio](reference/visual-cpp-project-types.md). You can create your own project templates. For more information, see [How to: Create project templates](/visualstudio/ide/how-to-create-project-templates). + :::image type="content" source="../overview/media/vs2017-new-project.png" alt-text="Screenshot of the New Project dialog, showing available project templates for C++ such as Windows Console Application."::: -After you create a project, it appears in the [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio) window: +::: moniker-end - ![Screenshot of the Solution Explorer window.](media/mathlibrary-solution-explorer-153.png) +For more information about the default project templates included in Visual Studio, see [C++ project templates in Visual Studio](reference/visual-cpp-project-types.md). -When you create a new project, a solution file (.sln) is also created. You can add additional projects to the solution by right-clicking on it in **Solution Explorer**. The solution file is used to coordinate build dependencies when you have multiple related projects but doesn't do much more than that. All the compiler options are set at the project level. +You can create your own project templates. For more information, see [Create project templates](/visualstudio/ide/how-to-create-project-templates). -## Add items +After you create a project, it appears in the [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio) window: -Add source code files, icons, or any other items to your project by right-clicking on the project in **Solution Explorer** and choosing **Add > New** or **Add > Existing**. +:::image type="content" source="media/mathlibrary-solution-explorer-153.png" alt-text="Screenshot of the Solution Explorer window, showing source files, header files, and resource files."::: -## Add third party libraries +When you create a new project, a solution file (*`.sln`*) is also created. A *Visual Studio solution* is a collection of one or more projects. You can add another project to the solution by right-clicking the solution name in **Solution Explorer** > **Add** > **New project**. -To add third-party libraries, use the [vcpkg](https://vcpkg.io/) package manager. Run the Visual Studio integration step to set up the paths to that library when you reference it from any Visual Studio project. +The solution file coordinates build dependencies when you have multiple related projects. Compiler options are set at the project level. -## Set compiler options and other build properties +## Add code, icons, and other assets to a project -To configure build settings for a project, right-click on the project in **Solution Explorer** and choose **Properties**. For more information, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). +Add source code files, icons, or any other items to your project by right-clicking on the project in **Solution Explorer** and choosing **Add > New** or **Add > Existing**. -## Compile and run +## Add third-party libraries to a project -To compile and run the new project, press **F5** or click the *debug dropdown* with the green arrow on the main toolbar. The *configuration dropdown* is where you choose whether to perform a *Debug* or *Release* build (or some other custom configuration). +Over 900 C++ open source libraries are available via the [vcpkg](/vcpkg/) package manager. Run the Visual Studio integration step to set up the paths to that library when you reference it from any Visual Studio project. -A new project compiles without errors. When adding your own code, you may occasionally introduce an error or trigger a warning. An error prevents the build from completing; a warning does not. All errors and warnings will appear both in the Output Window and in the Error List when you build the project. +For more information about consuming a library that you have downloaded by using the **vcpkg** package manager, see: +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in MSBuild projects](/vcpkg/users/buildsystems/msbuild-integration) +- [Tutorial: Install and use packages with MSBuild in Visual Studio](/vcpkg/get_started/get-started-msbuild) - ![Screenshot of the Output window and Error list.](../overview/media/vs2017-output-error-list.png) +There are also commercial third-party libraries that you can install. Follow their installation instructions. -In the Error List, you can press **F1** on a highlighted error to go to its documentation topic. +## Set compiler options and build properties -## In This Section +To configure build settings for a project, right-click on the project in **Solution Explorer** and choose **Properties**. For more information, see [Set compiler and build properties](working-with-project-properties.md). -[Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md)
-How to use Property Pages and Property Sheets to specify your project settings. +## Compile and run a project -[Reference libraries and components at build time](adding-references-in-visual-cpp-projects.md)
-How to include libs, DLLs, COM and .NET components in a project. +To compile and run the new project, press **F5** or select the *debug dropdown* with the green arrow on the main toolbar. The *configuration dropdown* is where you choose whether to perform a *Debug* or *Release* build (or some other custom configuration). -[Organize Project Output Files](how-to-organize-project-output-files-for-builds.md)
-How to customize the location of the executable files created in the build process. +A new project compiles without errors. When adding your own code, you might occasionally introduce an error or trigger a warning. An error prevents the build from completing; a warning doesn't. All errors and warnings appear both in the Output Window and in the Error List when you build the project. -[Custom Build Steps and Build Events](understanding-custom-build-steps-and-build-events.md)
-How to add any arbitrary command to the build process at specified points. +:::image type="content" source="../overview/media/vs2017-output-error-list.png" alt-text="Screenshot of the Output window and Error list, showing a syntax error for a misplaced colon."::: -[Create a project from existing code](how-to-create-a-cpp-project-from-existing-code.md)
-How to create a new Visual Studio project from a loose collection of source files. +In the **Error List**, you can press **F1** on the highlighted error to go to its documentation topic. -## See also +## Related content -[Projects and build systems](projects-and-build-systems-cpp.md)
-[Microsoft C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md) +- [Create a project from existing code](how-to-create-a-cpp-project-from-existing-code.md) +- [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md) +- [Custom build steps and build events](understanding-custom-build-steps-and-build-events.md) +- [Reference libraries and components at build time](adding-references-in-visual-cpp-projects.md) +- [Organize project output files](how-to-organize-project-output-files-for-builds.md) +- [Projects and build systems](projects-and-build-systems-cpp.md) +- [Microsoft C++ porting and upgrade guide](../porting/visual-cpp-porting-and-upgrading-guide.md) diff --git a/docs/build/creating-precompiled-header-files.md b/docs/build/creating-precompiled-header-files.md index 447af4f6e0..2b0f1f5ebe 100644 --- a/docs/build/creating-precompiled-header-files.md +++ b/docs/build/creating-precompiled-header-files.md @@ -1,86 +1,85 @@ --- -description: "Learn more about: Precompiled Header Files" title: "Precompiled Header Files" -ms.date: "10/24/2019" +description: "Learn more about: Precompiled header files" +ms.date: 06/29/2022 helpviewer_keywords: ["precompiled header files, creating", "PCH files, creating", "cl.exe compiler, precompiling code", ".pch files, creating"] -ms.assetid: e2cdb404-a517-4189-9771-c869c660cb1b --- -# Precompiled Header Files +# Precompiled header files -When you create a new project in Visual Studio, a *precompiled header file* named *pch.h* is added to the project. (In Visual Studio 2017 and earlier, the file was called *stdafx.h*.) The purpose of the file is to speed up the build process. Any stable header files, for example Standard Library headers such as ``, should be included here. The precompiled header is compiled only when it, or any files it includes, are modified. If you only make changes in your project source code, the build will skip compilation for the precompiled header. +When you create a new project in Visual Studio, a *precompiled header file* named *`pch.h`* is added to the project. (In Visual Studio 2017 and earlier, the file was called *`stdafx.h`*.) The purpose of the file is to speed up the build process. Any stable header files, for example Standard Library headers such as ``, should be included here. The precompiled header is compiled only when it, or any files it includes, are modified. If you only make changes in your project source code, the build will skip compilation for the precompiled header. -The compiler options for precompiled headers are [/Y](reference/y-precompiled-headers.md). In the project property pages, the options are located under **Configuration Properties > C/C++ > Precompiled Headers**. You can choose to not use precompiled headers, and you can specify the header file name and the name and path of the output file. +The compiler options for precompiled headers are [`/Y`](reference/y-precompiled-headers.md). In the project property pages, the options are located under **Configuration Properties** > **C/C++** > **Precompiled Headers**. You can choose to not use precompiled headers, and you can specify the header file name and the name and path of the output file. ## Custom precompiled code -For large projects that take significant time to build, you may want to consider creating custom precompiled files. The Microsoft C and C++ compilers provide options for precompiling any C or C++ code, including inline code. Using this performance feature, you can compile a stable body of code, store the compiled state of the code in a file, and, during subsequent compilations, combine the precompiled code with code that is still under development. Each subsequent compilation is faster because the stable code does not need to be recompiled. +For large projects that take significant time to build, you may want to consider creating custom precompiled files. The Microsoft C and C++ compilers provide options for precompiling any C or C++ code, including inline code. Using this performance feature, you can compile a stable body of code, store the compiled state of the code in a file, and, during subsequent compilations, combine the precompiled code with code that's still under development. Each later compilation is faster because the stable code doesn't need to be recompiled. -## When to Precompile Source Code +## When to precompile source code Precompiled code is useful during the development cycle to reduce compilation time, especially if: - You always use a large body of code that changes infrequently. -- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. +- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. For more information about newer ways to handle include files, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). -The first compilation — the one that creates the precompiled header (PCH) file — takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code. +The first compilation (the one that creates the precompiled header file) takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code. -You can precompile both C and C++ programs. In C++ programming, it is common practice to separate class interface information into header files. These header files can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile. +You can precompile both C and C++ programs. In C++ programming, it's common practice to separate class interface information into header files. These header files can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile. > [!NOTE] -> Although you can use only one precompiled header (.pch) file per source file, you can use multiple .pch files in a project. +> Although you can use only one precompiled header (*`.pch`*) file per source file, you can use multiple *`.pch`* files in a project. -## Two Choices for Precompiling Code +## Two choices for precompiling code -You can precompile any C or C++ code; you are not limited to precompiling only header files. +You can precompile any C or C++ code; you're not limited to precompiling only header files. -Precompiling requires planning, but it offers significantly faster compilations if you precompile source code other than simple header files. +Precompiling requires planning, but it offers much faster compilations if you precompile source code other than simple header files. -Precompile code when you know that your source files use common sets of header files but don't include them in the same order, or when you want to include source code in your precompilation. +Precompile code when you know that your source files use common sets of header files, or when you want to include source code in your precompilation. -The precompiled-header options are [/Yc (Create Precompiled Header File)](reference/yc-create-precompiled-header-file.md) and [/Yu (Use Precompiled Header File)](reference/yu-use-precompiled-header-file.md). Use **/Yc** to create a precompiled header. When used with the optional [hdrstop](../preprocessor/hdrstop.md) pragma, **/Yc** lets you precompile both header files and source code. Select **/Yu** to use an existing precompiled header in the existing compilation. You can also use **/Fp** with the **/Yc** and **/Yu** options to provide an alternative name for the precompiled header. +The precompiled-header options are [`/Yc` (Create Precompiled Header File)](reference/yc-create-precompiled-header-file.md) and [`/Yu` (Use Precompiled Header File)](reference/yu-use-precompiled-header-file.md). Use **`/Yc`** to create a precompiled header. When used with the optional [`hdrstop`](../preprocessor/hdrstop.md) pragma, **`/Yc`** lets you precompile both header files and source code. Select **`/Yu`** to use an existing precompiled header in the existing compilation. You can also use **`/Fp`** with the **`/Yc`** and **`/Yu`** options to provide an alternative name for the precompiled header. -The compiler option reference topics for **/Yu** and **/Yc** discuss how to access this functionality in the development environment. +The compiler option reference articles for **`/Yu`** and **`/Yc`** discuss how to access this functionality in the development environment. -## Precompiled Header Consistency Rules +## Precompiled header consistency rules -Because PCH files contain information about the machine environment as well as memory address information about the program, you should only use a PCH file on the machine where it was created. +Because PCH files contain information about the machine environment and memory address information about the program, you should only use a PCH file on the machine where it was created. -## Consistency Rules for Per-File Use of Precompiled Headers +## Consistency rules for per-file use of precompiled headers -The [/Yu](reference/yu-use-precompiled-header-file.md) compiler option lets you specify which PCH file to use. +The [`/Yu`](reference/yu-use-precompiled-header-file.md) compiler option lets you specify which PCH file to use. -When you use a PCH file, the compiler assumes the same compilation environment — one that uses consistent compiler options, pragmas, and so on — that was in effect when you created the PCH file, unless you specify otherwise. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings do not necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections. +When you use a PCH file, the compiler assumes the same compilation environment that was in effect when you created the PCH file, unless you specify otherwise. The compilation environment includes the compiler options, pragmas, and so on. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections. -### Compiler Option Consistency +### Compiler option consistency The following compiler options can trigger an inconsistency warning when using a PCH file: -- Macros created using the Preprocessor (/D) option must be the same between the compilation that created the PCH file and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if these change. +- Macros created using the Preprocessor (**`/D`**) option must be the same between the compilation that created the PCH file and the current compilation. The state of defined constants isn't checked, but unpredictable results can occur if these macros change. -- PCH files do not work with the /E and /EP options. +- PCH files don't work with the **`/E`** and **`/EP`** options. -- PCH files must be created using either the Generate Browse Info (/FR) option or the Exclude Local Variables (/Fr) option before subsequent compilations that use the PCH file can use these options. +- PCH files must be created using either the Generate Browse Info (**`/FR`**) option or the Exclude Local Variables (**`/Fr`**) option before subsequent compilations that use the PCH file can use these options. -### C 7.0-Compatible (/Z7) +### C 7.0-compatible (`/Z7`) -If this option is in effect when the PCH file is created, subsequent compilations that use the PCH file can use the debugging information. +If this option is in effect when the PCH file is created, later compilations that use the PCH file can use the debugging information. -If the C 7.0-Compatible (/Z7) option is not in effect when the PCH file is created, subsequent compilations that use the PCH file and /Z7 trigger a warning. The debugging information is placed in the current .obj file, and local symbols defined in the PCH file are not available to the debugger. +If the C 7.0-Compatible (**`/Z7`**) option isn't in effect when the PCH file is created, later compilations that use the PCH file and **`/Z7`** trigger a warning. The debugging information is placed in the current *`.obj`* file, and local symbols defined in the PCH file aren't available to the debugger. -### Include Path Consistency +### Include path consistency -A PCH file does not contain information about the include path that was in effect when it was created. When you use a PCH file, the compiler always uses the include path specified in the current compilation. +A PCH file doesn't contain information about the header include path that was in effect when it was created. When you use a PCH file, the compiler always uses the header include path specified in the current compilation. -### Source File Consistency +### Source file consistency -When you specify the Use Precompiled Header File (/Yu) option, the compiler ignores all preprocessor directives (including pragmas) that appear in the source code that will be precompiled. The compilation specified by such preprocessor directives must be the same as the compilation used for the Create Precompiled Header File (/Yc) option. +When you specify the Use Precompiled Header File (**`/Yu`**) option, the compiler ignores all preprocessor directives (including pragmas) that appear in the source code that will be precompiled. The compilation specified by such preprocessor directives must be the same as the compilation used for the Create Precompiled Header File (**`/Yc`**) option. -### Pragma Consistency +### Pragma consistency -Pragmas processed during the creation of a PCH file usually affect the file with which the PCH file is subsequently used. The `comment` and `message` pragmas do not affect the remainder of the compilation. +Pragmas processed during the creation of a PCH file usually affect the file with which the PCH file is later used. The `comment` and `message` pragmas don't affect the remainder of the compilation. -These pragmas affect only the code within the PCH file; they do not affect code that subsequently uses the PCH file: +These pragmas affect only the code within the PCH file; they don't affect code that later uses the PCH file: :::row::: :::column span=""::: @@ -131,57 +130,60 @@ These pragmas are retained as part of a precompiled header, and affect the remai :::column-end::: :::row-end::: -## Consistency Rules for /Yc and /Yu +## Consistency rules for /Yc and /Yu -When you use a precompiled header created using /Yc or /Yu, the compiler compares the current compilation environment to the one that existed when you created the PCH file. Be sure to specify an environment consistent with the previous one (using consistent compiler options, pragmas, and so on) for the current compilation. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. The following sections explain the consistency requirements for precompiled headers. +When you use a precompiled header created using **`/Yc`** or **`/Yu`**, the compiler compares the current compilation environment to the one that existed when you created the PCH file. Be sure to specify an environment consistent with the previous one (using consistent compiler options, pragmas, and so on) for the current compilation. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. The following sections explain the consistency requirements for precompiled headers. -### Compiler Option Consistency +### Compiler option consistency This table lists compiler options that might trigger an inconsistency warning when using a precompiled header: -|Option|Name|Rule| -|------------|----------|----------| -|/D|Define constants and macros|Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if your files depend on the values of the changed constants.| -|/E or /EP|Copy preprocessor output to standard output|Precompiled headers do not work with the /E or /EP option.| -|/Fr or /FR|Generate Microsoft Source Browser information|For the /Fr and /FR options to be valid with the /Yu option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single .sbr file and is referenced by other files in the same manner as CodeView information. You cannot override the placement of Source Browser information.| -|/GA, /GD, /GE, /Gw, or /GW|Windows protocol options|Must be the same between the compilation that created the precompiled header and the current compilation. If these options differ, a warning message results.| -|/Zi|Generate complete debugging information|If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that debugging information. If /Zi is not in effect when the precompiled header is created, subsequent compilations that use the precompilation and the /Zi option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header are not available to the debugger.| +| Option | Name | Rule | +|--|--|--| +| **`/D`**| Define constants and macros | Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants isn't checked. However, unpredictable results can occur if your files depend on the values of the changed constants. | +| **`/E`** or **`/EP`** | Copy preprocessor output to standard output | Precompiled headers don't work with the **`/E`** or **`/EP`** option. | +| **`/Fr`** or **`/FR`** | Generate Microsoft Source Browser information | For the **`/Fr`** and **`/FR`** options to be valid with the **`/Yu`** option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single *`.sbr`* file and is referenced by other files in the same manner as CodeView information. You can't override the placement of Source Browser information. | +| **`/GA`**, **`/GD`**, **`/GE`**, **`/Gw`**, or **`/GW`** | Windows protocol options | Must be the same between the compilation that created the precompiled header and the current compilation. The compiler emits a warning if these options differ. | +| **`/Zi`** | Generate complete debugging information | If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that debugging information. If **`/Zi`** isn't in effect when the precompiled header is created, subsequent compilations that use the precompilation and the **`/Zi`** option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header aren't available to the debugger. | > [!NOTE] > The precompiled header facility is intended for use only in C and C++ source files. -## Using Precompiled Headers in a Project +## Using precompiled headers in a project Previous sections present an overview of precompiled headers: /Yc and /Yu, the /Fp option, and the [hdrstop](../preprocessor/hdrstop.md) pragma. This section describes a method for using the manual precompiled-header options in a project; it ends with an example makefile and the code that it manages. -For another approach to using the manual precompiled-header options in a project, study one of the makefiles located in the MFC\SRC directory that is created during the default setup of Visual Studio. These makefiles take a similar approach to the one presented in this section but make greater use of Microsoft Program Maintenance Utility (NMAKE) macros, and offer greater control of the build process. +For another approach to using the manual precompiled-header options in a project, study one of the makefiles located in the *`MFC\SRC`* directory that's created during the default setup of Visual Studio. These makefiles take a similar approach to the one presented in this section. They make greater use of Microsoft Program Maintenance Utility (NMAKE) macros, and offer greater control of the build process. -## PCH Files in the Build Process +## PCH files in the build process -The code base of a software project is usually contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with those in the example code found in [Sample Makefile for PCH](#sample-makefile-for-pch) and [Example Code for PCH](#example-code-for-pch). +The code base of a software project is often contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with the example code found in [Sample makefile for PCH](#sample-makefile-for-pch) and [Example code for PCH](#example-code-for-pch). The figure uses three diagrammatic devices to show the flow of the build process. Named rectangles represent each file or macro; the three macros represent one or more files. Shaded areas represent each compile or link action. Arrows show which files and macros are combined during the compilation or linking process. -![Diagram showing example inputs and outputs of a makefile that uses a precompiled header file.](media/vc30ow1.gif "Structure of a makefile that uses a precompiled header file")
-Structure of a Makefile That Uses a Precompiled Header File +Structure of a makefile that uses a precompiled header file: -Beginning at the top of the diagram, both STABLEHDRS and BOUNDRY are NMAKE macros in which you list files not likely to need recompilation. These files are compiled by the command string +:::image type="complex" source="media/vc30ow1.gif" alt-text="Diagram showing example inputs and outputs of a makefile that uses a precompiled header file."::: +The diagram shows `$(STABLEHDRS)` and `$(BOUNDRY)` feeding into CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp. The output of that is $(STABLE.PCH). Then, applib.cpp and $(UNSTABLEHDRS) and $(STABLE.PCH) feed into CL /c /w3 /Yu $(BOUNDRY) applib.cpp, which produces applib.obj. myapp.cpp, $(UNSTABLEHDR), and $(STABLE.PCH) feed into CL /c /w3 /Yu $(BOUNDRY) myapp.cpp, which produces myapp.obj. Finally, applib.obj and myapp.obj are combined by LINK /NOD ONERROR:NOEXE $(OBJS), myapp, NUL, $(LIBS), NUL to produce myapp.exe. +:::image-end::: + +Beginning at the top of the diagram, both `STABLEHDRS` and `BOUNDRY` are NMAKE macros in which you list files not likely to need recompilation. These files are compiled by the command string `CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp` -only if the precompiled header file (STABLE.pch) does not exist or if you make changes to the files listed in the two macros. In either case, the precompiled header file will contain code only from the files listed in the STABLEHDRS macro. List the last file you want precompiled in the BOUNDRY macro. +only if the precompiled header file (*`STABLE.pch`*) doesn't exist or if you make changes to the files listed in the two macros. In either case, the precompiled header file will contain code only from the files listed in the `STABLEHDRS` macro. List the last file you want precompiled in the `BOUNDRY` macro. -The files you list in these macros can be either header files or C or C++ source files. (A single PCH file cannot be used with both C and C++ modules.) Note that you can use the **hdrstop** macro to stop precompilation at some point within the BOUNDRY file. See [hdrstop](../preprocessor/hdrstop.md) for more information. +The files you list in these macros can be either header files or C or C++ source files. (A single PCH file can't be used with both C and C++ sources.) You can use the **`hdrstop`** macro to stop precompilation at some point within the `BOUNDRY` file. For more information, see [`hdrstop`](../preprocessor/hdrstop.md). -Continuing down the diagram, APPLIB.obj represents the support code used in your final application. It is created from APPLIB.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header. +Next in the diagram, *`APPLIB.obj`* represents the support code used in your final application. It's created from *`APPLIB.cpp`*, the files listed in the `UNSTABLEHDRS` macro, and precompiled code from the precompiled header. -MYAPP.obj represents your final application. It is created from MYAPP.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header. +*`MYAPP.obj`* represents your final application. It's created from *`MYAPP.cpp`*, the files listed in the `UNSTABLEHDRS` macro, and precompiled code from the precompiled header. -Finally, the executable file (MYAPP.EXE) is created by linking the files listed in the OBJS macro (APPLIB.obj and MYAPP.obj). +Finally, the executable file (*`MYAPP.EXE`*) is created by linking the files listed in the `OBJS` macro (*`APPLIB.obj`* and *`MYAPP.obj`*). -## Sample Makefile for PCH +## Sample makefile for PCH -The following makefile uses macros and an !IF, !ELSE, !ENDIF flow-of-control command structure to simplify its adaptation to your project. +The following makefile uses macros and an `!IF`, `!ELSE`, `!ENDIF` flow-of-control command structure to simplify its adaptation to your project. ```NMAKE # Makefile : Illustrates the effective use of precompiled @@ -227,26 +229,28 @@ stable.pch : $(STABLEHDRS) $(CPP) $(CLFLAGS) /Yc$(BOUNDRY) applib.cpp myapp.cpp ``` -Aside from the STABLEHDRS, BOUNDRY, and UNSTABLEHDRS macros shown in the figure "Structure of a Makefile That Uses a Precompiled Header File" in [PCH Files in the Build Process](#pch-files-in-the-build-process), this makefile provides a CLFLAGS macro and a LINKFLAGS macro. You must use these macros to list compiler and linker options that apply whether you build a debug or final version of the application's executable file. There is also a LIBS macro where you list the libraries your project requires. +Aside from the `STABLEHDRS`, `BOUNDRY`, and `UNSTABLEHDRS` macros shown in the figure "Structure of a Makefile That Uses a Precompiled Header File" in [PCH files in the build process](#pch-files-in-the-build-process), this makefile provides a `CLFLAGS` macro and a `LINKFLAGS` macro. You must use these macros to list compiler and linker options that apply whether you build a debug or final version of the application's executable file. There's also a `LIBS` macro where you list the libraries your project requires. -The makefile also uses !IF, !ELSE, !ENDIF to detect whether you define a DEBUG symbol on the NMAKE command line: +The makefile also uses `!IF`, `!ELSE`, `!ENDIF` to detect whether you define a `DEBUG` symbol on the NMAKE command line: ```NMAKE NMAKE DEBUG=[1|0] ``` -This feature makes it possible for you to use the same makefile during development and for the final versions of your program — use DEBUG=0 for the final versions. The following command lines are equivalent: +This feature makes it possible for you to use the same makefile during development and for the final versions of your program. Use `DEBUG=0` for the final versions. The following command lines are equivalent: ```NMAKE NMAKE NMAKE DEBUG=0 ``` -For more information on makefiles, see [NMAKE Reference](reference/nmake-reference.md). Also see [MSVC Compiler Options](reference/compiler-options.md) and the [MSVC Linker Options](reference/linker-options.md). +For more information on makefiles, see [NMAKE reference](reference/nmake-reference.md). Also see [MSVC compiler options](reference/compiler-options.md) and the [MSVC linker options](reference/linker-options.md). + +## Example code for PCH -## Example Code for PCH +The following source files are used in the makefile described in [PCH files in the build process](#pch-files-in-the-build-process) and [Sample makefile for PCH](#sample-makefile-for-pch). The comments contain important information. -The following source files are used in the makefile described in [PCH Files in the Build Process](#pch-files-in-the-build-process) and [Sample Makefile for PCH](#sample-makefile-for-pch). Note that the comments contain important information. +Source file `ANOTHER.H`: ```cpp // ANOTHER.H : Contains the interface to code that is not @@ -254,11 +258,13 @@ The following source files are used in the makefile described in [PCH Files in t // #ifndef __ANOTHER_H #define __ANOTHER_H -#include +#include void savemoretime( void ); #endif // __ANOTHER_H ``` +Source file `STABLE.H`: + ```cpp // STABLE.H : Contains the interface to code that is not likely // to change. List code that is likely to change @@ -266,11 +272,13 @@ void savemoretime( void ); // #ifndef __STABLE_H #define __STABLE_H -#include +#include void savetime( void ); #endif // __STABLE_H ``` +Source file `UNSTABLE.H`: + ```cpp // UNSTABLE.H : Contains the interface to code that is // likely to change. As the code in a header @@ -280,19 +288,21 @@ void savetime( void ); // #ifndef __UNSTABLE_H #define __UNSTABLE_H -#include +#include void notstable( void ); #endif // __UNSTABLE_H ``` +Source file `APPLIB.CPP`: + ```cpp // APPLIB.CPP : This file contains the code that implements // the interface code declared in the header // files STABLE.H, ANOTHER.H, and UNSTABLE.H. // -#include"another.h" -#include"stable.h" -#include"unstable.h" +#include "another.h" +#include "stable.h" +#include "unstable.h" using namespace std; // The following code represents code that is deemed stable and // not likely to change. The associated interface code is @@ -310,6 +320,8 @@ void notstable( void ) } ``` +Source file `MYAPP.CPP`: + ```cpp // MYAPP.CPP : Sample application // All precompiled code other than the file listed @@ -318,9 +330,9 @@ void notstable( void ) // listed in the BOUNDRY macro. Unstable code must // be included after the precompiled code. // -#include"another.h" -#include"stable.h" -#include"unstable.h" +#include "another.h" +#include "stable.h" +#include "unstable.h" int main( void ) { savetime(); @@ -331,5 +343,10 @@ int main( void ) ## See also -[C/C++ Building Reference](reference/c-cpp-building-reference.md)
-[MSVC Compiler Options](reference/compiler-options.md) +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ +[C/C++ building reference](reference/c-cpp-building-reference.md)\ +[MSVC compiler options](reference/compiler-options.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) diff --git a/docs/build/customize-cmake-settings.md b/docs/build/customize-cmake-settings.md index 222c2e4a83..3ccdd13da6 100644 --- a/docs/build/customize-cmake-settings.md +++ b/docs/build/customize-cmake-settings.md @@ -14,11 +14,13 @@ If you maintain projects that use a *`CMakeSettings.json`* file for CMake build To open the CMake settings editor, select the **Configuration** drop-down in the main toolbar and choose **Manage Configurations**. -![Screenshot of the CMake configuration drop-down that highlights the Manage Configurations selection.](media/vs2019-cmake-manage-configurations.png) +![Screenshot of the CMake configuration drop-down. Manage Configurations is highlighted.](media/vs2019-cmake-manage-configurations.png) Now you see the **Settings Editor** with the installed configurations on the left. -![Screenshot of the CMake settings editor.](media/cmake-settings-editor.png) +:::image type="complex" source="media/cmake-settings-editor.png" alt-text="Screenshot of the CMake settings editor."::: +The left pane shows the installed configurations (x86-Debug). The right pane shows the settings for the selected configuration. The settings include the configuration name, configuration type (set to Debug), toolset (set to msvc_x86), CMake toolchain file (empty), build root (contains ${env:USERPROFILE}\CMakeBuilds\${workspaceHash}\build\${name}), CMake command arguments (empty), and build command arguments (-v). +:::image-end::: Visual Studio provides one `x64-Debug` configuration by default. You can add more configurations by choosing the green plus sign. The settings that you see in the editor might vary depending on which configuration is selected. @@ -34,7 +36,7 @@ Corresponds to the **name** setting. This name appears in the C++ configuration ### Configuration type -Corresponds to the **configurationType** setting. Defines the build configuration type for the selected generator. Currently supported values are "Debug", "MinSizeRel", "Release", and "RelWithDebInfo". It maps to [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). +Corresponds to the **configurationType** setting. Defines the build configuration type for the selected generator. Currently supported values are Debug, MinSizeRel, Release, and RelWithDebInfo. It maps to [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). ### Toolset @@ -42,7 +44,7 @@ Corresponds to the **inheritedEnvironments** setting. Defines the compiler envir ### CMake toolchain file -Path to the [CMake toolchain file](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html). This path is passed to CMake as "-DCMAKE_TOOLCHAIN_FILE = \". Toolchain files specify locations of compilers and toolchain utilities, and other target platform and compiler-related information. By default, Visual Studio uses the [vcpkg toolchain file](https://github.com/microsoft/vcpkg/blob/master/docs/examples/installing-and-using-packages.md#cmake) if this setting is unspecified. +Path to the [CMake toolchain file](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html). This path is passed to CMake as `"-DCMAKE_TOOLCHAIN_FILE = `. Toolchain files specify locations of compilers and toolchain utilities, and other target platform and compiler-related information. By default, Visual Studio uses the [vcpkg toolchain file](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/examples/installing-and-using-packages.md#cmake) if this setting is unspecified. ### Build root @@ -70,7 +72,7 @@ For configurations such as Linux that use remote builds, the following settings ### `rsync` command arguments -Extra command-line options passed to [`rsync`](https://download.samba.org/pub/rsync/rsync.html), a fast, versatile file-copying tool. +Extra command-line options passed to [`rsync`](https://download.samba.org/pub/rsync/), a fast, versatile file-copying tool. ## CMake variables and cache @@ -96,7 +98,7 @@ Corresponds to **generator**. Maps to the CMake **`-G`** switch, and specifies t - "Visual Studio 14 2015 Win64" - "Visual Studio 14 2015 ARM" -Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. However, some CMake projects may be unable to correctly build using Ninja. If that occurs, you can instruct CMake to generate a Visual Studio project instead. +Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. However, some CMake projects might be unable to correctly build using Ninja. If that occurs, you can instruct CMake to generate a Visual Studio project instead. ### IntelliSense mode @@ -190,8 +192,10 @@ You can also directly edit *`CMakeSettings.json`* to create custom configuration JSON IntelliSense helps you edit the *`CMakeSettings.json`* file: - ![Screenshot of the CMake JSON IntelliSense pop-up in the editor.](media/cmake-json-intellisense.png "CMake JSON IntelliSense") - + :::image type="complex" source="media/cmake-json-intellisense.png" alt-text="Screenshot of the CMake JSON IntelliSense pop-up in the editor."::: + The JSON IntelliSense pop-up for "configurations" shows buildCommandArgs, buildRoot, cmakeCommandArgs, configurationType, among several others. + :::image-end::: + For more information about each of the properties in the file, see [`CMakeSettings.json` schema reference](cmakesettings-reference.md). ::: moniker-end diff --git a/docs/build/dll-frequently-asked-questions.yml b/docs/build/dll-frequently-asked-questions.yml index 5c89b9fac9..d35f75948d 100644 --- a/docs/build/dll-frequently-asked-questions.yml +++ b/docs/build/dll-frequently-asked-questions.yml @@ -5,7 +5,7 @@ metadata: ms.date: "05/06/2019" helpviewer_keywords: ["troubleshooting [C++], DLLs", "DLLs [C++], frequently asked questions", "FAQs [C++], DLLs"] ms.assetid: 09dd068e-fc33-414e-82f7-289c70680256 - + ms.topic: faq title: DLL frequently asked questions summary: | diff --git a/docs/build/exception-handling-x64.md b/docs/build/exception-handling-x64.md index 3447b9f6af..41a6e29b6e 100644 --- a/docs/build/exception-handling-x64.md +++ b/docs/build/exception-handling-x64.md @@ -440,6 +440,8 @@ typedef enum _UNWIND_OP_CODES { UWOP_PUSH_MACHFRAME /* info == 0: no error-code, 1: error-code */ } UNWIND_CODE_OPS; +typedef unsigned char UBYTE; + typedef union _UNWIND_CODE { struct { UBYTE CodeOffset; @@ -488,7 +490,7 @@ typedef struct _RUNTIME_FUNCTION { ((PRUNTIME_FUNCTION)((base) + *(PULONG)GetLanguageSpecificDataPtr(info))) #define GetExceptionDataPtr(info) \ - ((PVOID)((PULONG)GetLanguageSpecificData(info) + 1) + ((PVOID)((PULONG)GetLanguageSpecificData(info) + 1)) ``` ## See also diff --git a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md index ae89cbf097..2386881514 100644 --- a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md +++ b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: Exporting C Functions for Use in C or C++ Language Executables" -title: "Exporting C Functions for Use in C or C++ Language Executables" -ms.date: "11/04/2016" +description: "Learn more about: Exporting C functions for use in C or C++ language executables" +title: "Export C functions for use in C or C++ language executables" +ms.date: 05/24/2022 helpviewer_keywords: ["functions [C], exporting", "functions [C], C or C++ executables and", "__cplusplus macro", "exporting DLLs [C++], C functions in C++ executables", "exporting functions [C++], C functions in C++ executables"] ms.assetid: b51d6e5e-37cf-4c1c-b0bf-fcf188c82f00 --- -# Exporting C Functions for Use in C or C++ Language Executables +# Export C functions for use in C or C++ language executables -If you have functions in a DLL written in C that you want to access from a C language or C++ language module, you should use the **__cplusplus** preprocessor macro to determine which language is being compiled, and then declare these functions with C linkage if being used from a C++ language module. If you use this technique and provide header files for your DLL, these functions can be used by C and C++ users with no change. +If you have functions in a DLL written in C, you can use a preprocessor macro to make them easy to access from both C language and C++ language code. The **`__cplusplus`** preprocessor macro indicates which language is being compiled. You may use it to declare the functions with C linkage when called from C++ language code. If you use this technique and provide header files for your DLL, these functions can be used by C and C++ users with no change. -The following code shows a header file that can be used by C and C++ client applications: +The following code shows a header file that both C and C++ client applications can use: ```h // MyCFuncs.h @@ -26,7 +26,7 @@ __declspec( dllimport ) void AnotherCFunc(); #endif ``` -If you need to link C functions to your C++ executable and the function declaration header files have not used the above technique, in the C++ source file, do the following to prevent the compiler from decorating the C function names: +Sometimes you may need to link C functions to your C++ executable, but the function declaration header files haven't used the above technique. You can still call the functions from C++. In the C++ source file, wrap the `#include` directive to prevent the compiler from decorating the C function names: ```cpp extern "C" { @@ -36,15 +36,15 @@ extern "C" { ## What do you want to do? -- [Export from a DLL using .def files](exporting-from-a-dll-using-def-files.md) +- [Export from a DLL using `.def` files](exporting-from-a-dll-using-def-files.md) -- [Export from a DLL using __declspec(dllexport)](exporting-from-a-dll-using-declspec-dllexport.md) +- [Export from a DLL using `__declspec(dllexport)`](exporting-from-a-dll-using-declspec-dllexport.md) -- [Export and import using AFX_EXT_CLASS](exporting-and-importing-using-afx-ext-class.md) +- [Export and import using `AFX_EXT_CLASS`](exporting-and-importing-using-afx-ext-class.md) - [Determine which exporting method to use](determining-which-exporting-method-to-use.md) -- [Import into an application using __declspec(dllimport)](importing-into-an-application-using-declspec-dllimport.md) +- [Import into an application using `__declspec(dllimport)`](importing-into-an-application-using-declspec-dllimport.md) - [Initialize a DLL](run-time-library-behavior.md#initializing-a-dll) @@ -52,7 +52,7 @@ extern "C" { - [Decorated names](reference/decorated-names.md) -- [Using extern to Specify Linkage](../cpp/extern-cpp.md) +- [Using `extern` to specify linkage](../cpp/extern-cpp.md) ## See also diff --git a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md index 14b67bab22..938dc06425 100644 --- a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md +++ b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Formatting the Output of a Custom Build Step or Build Event" -title: "Formatting the Output of a Custom Build Step or Build Event" -ms.date: "08/27/2018" +description: "Learn more about: Formatting the output of a custom build step or build event" +title: "Formatting the output of a custom build step or build event" +ms.date: 03/15/2022 helpviewer_keywords: ["builds [C++], build events", "custom build steps [C++], output format", "events [C++], build", "build events [C++], output format", "build steps [C++], output format", "builds [C++], custom build steps"] ms.assetid: 92ad3e38-24d7-4b89-90e6-5a16f5f998da --- -# Formatting the Output of a Custom Build Step or Build Event +# Formatting the output of a custom build step or build event If the output of a custom build step or build event is formatted correctly, users get the following benefits: @@ -13,28 +13,30 @@ If the output of a custom build step or build event is formatted correctly, user - Output appears in the **Task List** window. -- Clicking on the output in the **Output** window displays the appropriate topic. +- Clicking on the output in the **Output** window displays the appropriate location. -- F1 operations are enabled in the **Task List** window or **Output** window. +- **F1** operations are enabled in the **Task List** window or **Output** window. + +## Output format The format of the output should be: -> {filename**(**line# \[**,** column#]**)** | *toolname*} **:** \[ any text ] {**error** | **warning**} code+number**:**localizable string \[ any text ] +> { *filename*`(`*line-number* \[`,` *column-number*]`)` \| *tool-name* } `:` \[ *any-text* ] {`error` \| `warning`} *code-type-and-number* `:` *localizable-string* \[ *any-text* ] Where: -- {*a* | *b*} is a choice of either *a* or *b*. +- { *a* \| *b* } is a choice of either *a* or *b*, -- \[item] is an optional string or parameter. +- \[ *item* ] is an optional string or parameter, -- **Bold** represents a literal. +- `text` represents a literal. For example: -> C:\\*sourcefile.cpp*(134) : error C2143: syntax error : missing ';' before '}' +> C:\\sourcefile.cpp(134) : error C2143: syntax error : missing ';' before '}' > -> LINK : fatal error LNK1104: cannot open file '*somelib.lib*' +> LINK : fatal error LNK1104: cannot open file 'some-library.lib' ## See also -[Understanding Custom Build Steps and Build Events](understanding-custom-build-steps-and-build-events.md) +[Understanding custom build steps and build events](understanding-custom-build-steps-and-build-events.md) diff --git a/docs/build/get-started-linux-cmake.md b/docs/build/get-started-linux-cmake.md index a22da6c554..1ffb0fb6d2 100644 --- a/docs/build/get-started-linux-cmake.md +++ b/docs/build/get-started-linux-cmake.md @@ -2,7 +2,7 @@ title: Create C++ cross-platform projects in Visual Studio description: "How to set up, compile, and debug a C++ open-source CMake project in Visual Studio that targets both Linux and Windows." ms.topic: tutorial -ms.date: "01/08/2020" +ms.date: 02/07/2022 --- # Tutorial: Create C++ cross-platform projects in Visual Studio @@ -21,11 +21,13 @@ In this tutorial, you learn how to: ## Prerequisites * Set up Visual Studio for Cross Platform C++ Development + * First, [install Visual Studio](https://visualstudio.microsoft.com/vs/) and choose the **Desktop development with C++** and **Linux development with C++ workloads**. This minimal install is only 3 GB. Depending on your download speed, installation shouldn't take more than 10 minutes. * Set up a Linux machine for Cross Platform C++ Development - * Visual Studio doesn't require any specific distribution of Linux. The OS can be running on a physical machine, in a VM, or in the cloud. You could also use the Windows Subsystem for Linux (WSL). However, for this tutorial a graphical environment is required. WSL isn't recommended here, because it's intended primarily for command-line operations. - * Visual Studio requires these tools on the Linux machine: C++ compilers, gdb, ssh, rsync, make, and zip. On Debian-based systems, you can use this command to install these dependencies: + + * Visual Studio doesn't require any specific distribution of Linux. The OS can be running on a physical machine, in a VM, or in the cloud. You could also use the Windows Subsystem for Linux (WSL). However, for this tutorial, a graphical environment is required. WSL isn't recommended here, because it's intended primarily for command-line operations. + * Visual Studio requires these tools on the Linux machine: C++ compilers, `gdb`, `ssh`, `rsync`, `make`, and `zip`. On Debian-based systems, you can use this command to install these dependencies: ```cmd sudo apt install -y openssh-server build-essential gdb rsync make zip @@ -38,7 +40,7 @@ In this tutorial, you learn how to: chmod +x cmake-3.11.18033000-MSVC_2-Linux-x86_64.sh ``` - * You can see the options for running the script with `-–help`. We recommend that you use the `–prefix` option to specify installing in the **/usr** path, because **/usr/bin** is the default location where Visual Studio looks for CMake. The following example shows the Linux-x86_64 script. Change it as needed if you're using a different target platform. + * You can see the options for running the script with `--help`. We recommend that you use the `-prefix` option to specify installing in the **/usr** path, because **/usr/bin** is the default location where Visual Studio looks for CMake. The following example shows the Linux-x86_64 script. Change it as needed if you're using a different target platform. ```cmd sudo ./cmake-3.11.18033000-MSVC_2-Linux-x86_64.sh --skip-license --prefix=/usr @@ -49,43 +51,43 @@ In this tutorial, you learn how to: ## Clone an open-source CMake project from GitHub -This tutorial uses the Bullet Physics SDK on GitHub. It provides collision detection and physics simulations for many applications. The SDK includes sample executable programs that compile and run without having to write additional code. This tutorial doesn't modify any of the source code or build scripts. To start, clone the *bullet3* repository from GitHub on the machine where you have Visual Studio installed. +This tutorial uses the Bullet Physics SDK on GitHub. It provides collision detection and physics simulations for many applications. The SDK includes sample executable programs that compile and run without having to write other code. This tutorial doesn't modify any of the source code or build scripts. To start, clone the *bullet3* repository from GitHub on the machine where you have Visual Studio installed. ```cmd git clone https://github.com/bulletphysics/bullet3.git ``` -1. On the Visual Studio main menu, choose **File > Open > CMake**. Navigate to the CMakeLists.txt file in the root of the bullet3 repo you just downloaded. +1. On the Visual Studio main menu, choose **File > Open > CMake**. Navigate to the `CMakeLists.txt` file in the root of the bullet3 repo you downloaded. - ![Visual Studio menu for File > Open > CMake.](media/cmake-open-cmake.png) + ![Screenshot of Visual Studio menu showing File > Open > C Make. A folder has yet to be opened. This is just the menu opened to this point.](media/cmake-open-cmake.png) As soon as you open the folder, your folder structure becomes visible in the **Solution Explorer**. - ![Solution Explorer window in Folder View mode.](media/cmake-bullet3-solution-explorer.png) + ![Screenshot of the Solution Explorer window in Folder View mode. It displays the contents of the project (files and folders) and CMakeLists.txt is highlighted.](media/cmake-bullet3-solution-explorer.png) This view shows you exactly what is on disk, not a logical or filtered view. By default, it doesn't show hidden files. 1. Choose the **Show all files** button to see all the files in the folder. - ![Solution Explorer window with the Show All Files button highlighted.](media/cmake-bullet3-show-all-files.png) + ![Screenshot of the Solution Explorer window with the Show All Files button highlighted. This button sits on top of the solution explorer window and to the right.](media/cmake-bullet3-show-all-files.png) ## Switch to targets view When you open a folder that uses CMake, Visual Studio automatically generates the CMake cache. This operation might take a few moments, depending on the size of your project. -1. In the **Output Window**, select **Show output from** and then choose **CMake** to monitor the status of the cache generation process. When the operation is complete, it says "Target info extraction done". +1. In the **Output Window**, select **Show output from** and then choose **CMake** to monitor the status of the cache generation process. When the operation is complete, it says "Target info extraction done." - ![Output window showing output from CMake.](media/cmake-bullet3-output-window.png) + ![Screenshot of the Output window. The Show output from: dropdown is set to CMake.](media/cmake-bullet3-output-window.png) After this operation completes, IntelliSense is configured. You can build the project, and debug the application. Visual Studio now shows a logical view of the solution, based on the targets specified in the CMakeLists files. 1. Use the **Solutions and Folders** button in the **Solution Explorer** to switch to CMake Targets View. - ![Solutions and Folders button in the Solution Explorer to show CMake targets view.](media/cmake-bullet3-show-targets.png) + ![Screenshot of the Solutions and Folders button in the Solution Explorer. It is selected, showing a dropdown with a choice for c:\projects\bullet3 and another choice for CMake Targets View, which is selected.](media/cmake-bullet3-show-targets.png) - Here is what that view looks like for the Bullet SDK: + Here's what that view looks like for the Bullet SDK: - ![Solution Explorer CMake targets view.](media/cmake-bullet3-targets-view.png) + ![Screenshot of the Solution Explorer CMake targets view. It contains an entry called BULLET_PHYSICS Project, under which are entries like App_BasicExample (executable), App_ExampleBrowser (executable), and so on.](media/cmake-bullet3-targets-view.png) Targets view provides a more intuitive view of what is in this source base. You can see some targets are libraries and others are executables. @@ -97,17 +99,17 @@ Visual Studio creates a default **x64-Debug** configuration for Windows. Configu 1. Add a new configuration. Open the **Configuration** drop-down in the toolbar and select **Manage Configurations**. - ![Manage Configuration command highlighted in the Configuration drop-down.](media/cmake-bullet3-manage-configurations.png) + ![Screenshot of the Configuration drop-down in the toolbar. Manage Configurations... is selected.](media/cmake-bullet3-manage-configurations.png) - The [CMake Settings Editor](customize-cmake-settings.md) opens. Select the green plus sign on the left-hand side of the editor to add a new configuration. The **Add Configuration to CMakeSettings** dialog appears. + The [CMake Settings Editor](customize-cmake-settings.md) opens. Select the green plus sign on the left-hand side of the editor to add a new configuration. The **Add Configuration to CMakeSettings** dialog appears: - ![Add Configuration to CMakeSettings dialog.](media/cmake-bullet3-add-configuration-x64-debug.png) + ![Screenshot of the Add Configuration to CMakeSettings dialog. It has entries such as Linux-Debug, x86-Debug. x64-Debug is selected.](media/cmake-bullet3-add-configuration-x64-debug.png) - This dialog shows all the configurations included with Visual Studio, plus any custom configurations that you create. If you want to continue to use a **x64-Debug** configuration, that should be the first one you add. Select **x64-Debug**, and then choose the **Select** button. Visual Studio creates the CMakeSettings.json file with a configuration for **x64-Debug**, and saves it to disk. You can use whatever names you like for your configurations by changing the name parameter directly in CMakeSettings.json. + This dialog shows all the configurations included with Visual Studio, plus any custom configurations that you create. If you want to continue to use a **x64-Debug** configuration that should be the first one you add. Select **x64-Debug**, and then choose the **Select** button. Visual Studio creates the CMakeSettings.json file with a configuration for **x64-Debug**, and saves it to disk. You can use whatever names you like for your configurations by changing the name parameter directly in CMakeSettings.json. ## Set a breakpoint, build, and run on Windows -In this step, we'll debug an example program that demonstrates the Bullet Physics library. +In this step, we debug an example program that demonstrates the Bullet Physics library. 1. In **Solution Explorer**, select AppBasicExampleGui and expand it. @@ -121,17 +123,17 @@ In this step, we'll debug an example program that demonstrates the Bullet Physic 1. In the browser view above your source, you should see that you're in the `CommonRigidBodyBase`. To the right, you can select members to examine. Open the drop-down and select `mouseButtonCallback` to go to the definition of that function in the header. - ![Member list toolbar drop-down in the editor window, with mouse button callback item highlighted.](media/cmake-bullet3-member-list-toolbar.png) + ![Screenshot of the Member list toolbar drop-down in the editor window. It list functions such as getRayTo(in x, int y). The mouse button callback method is highlighted.](media/cmake-bullet3-member-list-toolbar.png) 1. Place a breakpoint on the first line within this function. It gets hit when you click a mouse button within the window of the application, when run under the Visual Studio debugger. -1. To launch the application, select the launch drop-down in the toolbar. It's the one with the green play icon that says "Select Startup Item". In the drop-down, select AppBasicExampleGui.exe. The executable name now displays on the launch button: +1. To launch the application, select the launch drop-down in the toolbar. It's the one with the green play icon that says "Select Startup Item." In the drop-down, select AppBasicExampleGui.exe. The executable name now displays on the launch button: - ![Visual Studio toolbar launch drop-down for Select Startup Item.](media/cmake-bullet3-launch-button.png) + ![Screenshot of the Visual Studio toolbar launch drop-down. AppBasicExampleGui.exe is selected, but other options are visible such as App_ExampleBrowser.exe, App_HelloWorld.exe, and others.](media/cmake-bullet3-launch-button.png) 1. Choose the launch button to build the application and necessary dependencies, then launch it with the Visual Studio debugger attached. After a few moments, the running application appears: - ![Visual Studio debugging a Windows application.](media/cmake-bullet3-launched.png) + ![Screenshot of the running application. It's a collection of colored blocks on a yellow plane.](media/cmake-bullet3-launched.png) 1. Move your mouse into the application window, then click a button to trigger the breakpoint. The breakpoint brings Visual Studio back to the foreground, and the editor shows the line where execution is paused. You can inspect the application variables, objects, threads, and memory, or step through your code interactively. Choose **Continue** to let the application resume, and then exit it normally. Or, halt execution within Visual Studio by using the stop button. @@ -143,19 +145,21 @@ In this step, we'll debug an example program that demonstrates the Bullet Physic 1. Select **Linux-Debug** in the configuration drop-down. - ![Launch configuration drop-down with X64-Debug and Linux-Debug options.](media/cmake-bullet3-linux-configuration-item.png) + ![Screenshot of the launch configuration drop-down. The visible options are: x64-Debug, Linux-Debug, and Manage Configurations.](media/cmake-bullet3-linux-configuration-item.png) If it's the first time you're connecting to a Linux system, the **Connect to Remote System** dialog appears. - ![Visual Studio Connect to Remote System dialog.](media/cmake-bullet3-connection-manager.png) - + :::image type="complex" source="./media/cmake-bullet3-connection-manager.png" alt-text="Screenshot of the Visual Studio Connect to Remote System dialog."::: + The dialog has fields for the host name, port, user name, authentication type, and password. All of the fields are blank except Port is set to 22 and Authentication type is set to Password. + :::image-end::: + If you've already added a remote connection, you can open this window by navigating to **Tools > Options > Cross Platform > Connection Manager**. -1. Provide the [connection information to your Linux machine](../linux/connect-to-your-remote-linux-computer.md) and choose **Connect**. Visual Studio adds that machine as to CMakeSettings.json as your default connection for **Linux-Debug**. It also pulls down the headers from your remote machine, so you get [IntelliSense specific to that remote connection](../linux/configure-a-linux-project.md#remote_intellisense). Next, Visual Studio sends your files to the remote machine and generates the CMake cache on the remote system. These steps may take some time, depending on the speed of your network and power of your remote machine. You'll know it's complete when the message "Target info extraction done" appears in the CMake output window. +1. Provide the [connection information to your Linux machine](../linux/connect-to-your-remote-linux-computer.md) and choose **Connect**. Visual Studio adds that machine as to CMakeSettings.json as your default connection for **Linux-Debug**. It also pulls down the headers from your remote machine, so you get [IntelliSense specific to that remote connection](../linux/configure-a-linux-project.md#remote_intellisense). Next, Visual Studio sends your files to the remote machine and generates the CMake cache on the remote system. These steps might take some time, depending on the speed of your network and power of your remote machine. You know it's complete when the message "Target info extraction done" appears in the CMake output window. ## Set a breakpoint, build, and run on Linux -Because it's a desktop application, you need to provide some additional configuration information to the debug configuration. +Because it's a desktop application, you need to provide some more configuration information to the debug configuration. 1. In the CMake Targets view, right-click AppBasicExampleGui and choose **Debug and Launch Settings** to open the launch.vs.json file that's in the hidden **.vs** subfolder. This file is local to your development environment. You can move it into the root of your project if you wish to check it in and save it with your team. In this file, a configuration has been added for AppBasicExampleGui. These default settings work in most cases, but not here. Because it's a desktop application, you need to provide some additional information to launch the program so you can see it on your Linux machine. @@ -165,7 +169,7 @@ Because it's a desktop application, you need to provide some additional configur echo $DISPLAY ``` - In the configuration for AppBasicExampleGui, there's a parameter array, "pipeArgs". It contains a line: "${debuggerCommand}". It's the command that launches gdb on the remote machine. Visual Studio must export the display into this context before that command runs. For example, if the value of your display is `:1`, modify that line as follows: + In the configuration for AppBasicExampleGui, there's a parameter array, "pipeArgs". It contains a line: "${debuggerCommand}". It's the command that launches `gdb` on the remote machine. Visual Studio must export the display into this context before that command runs. For example, if the value of your display is `:1`, modify that line as follows: ```cmd "export DISPLAY=:1;${debuggerCommand}", @@ -175,13 +179,17 @@ Because it's a desktop application, you need to provide some additional configur 1. Move your mouse into the application window, and click a button. The breakpoint is hit. Program execution pauses, Visual Studio comes back to the foreground, and you see your breakpoint. You should also see a Linux Console Window appear in Visual Studio. The window provides output from the remote Linux machine, and it can also accept input for `stdin`. Like any Visual Studio window, you can dock it where you prefer to see it. Its position is persisted in future sessions. - ![Visual Studio Linux Console Window.](media/cmake-bullet3-linux-console.png) + :::image type="complex" source="media/cmake-bullet3-linux-console.png" alt-text="Screenshot of the Visual Studio Linux Console Window."::: + The output in the window indicates that the C11 functions dynamically loaded using dlopen/dlsym is OK, a GL 3.0 context has been created and the Direct GLX rendering context obtained and made current. The window has various version information for GL_VENDOR, GL_VERSION, GL_SHADING_LANGUAGE_VERSION, and so on. + :::image-end::: -1. You can inspect the application variables, objects, threads, memory, and step through your code interactively using Visual Studio. But this time, you're doing it all on a remote Linux machine instead of your local Windows environment. You can choose **Continue** to let the application resume and exit normally, or you can choose the stop button, just as with local execution. +1. You can inspect the application variables, objects, threads, memory, and step through your code interactively using Visual Studio. But this time, you're doing it all on a remote Linux machine instead of your local Windows environment. You can choose **Continue** to let the application resume and exit normally, or you can choose the stop button, as with local execution. 1. Look at the Call Stack window and view the Calls to `x11OpenGLWindow` since Visual Studio launched the application on Linux. - ![Call Stack window showing Linux call stack.](media/cmake-bullet3-linux-callstack.png) + :::image type="complex" source="media/cmake-bullet3-linux-callstack.png" alt-text="The Visual Studio Call Stack window, showing Linux call stack."::: + The callstack shows the breakpoint on CommonRigidBodyBase::mouseMoveCallback, and the calls that precede it such as OnMouseMove, X11OpenGLWindow::pumpMessage, and so on. + :::image-end::: ## What you learned @@ -199,4 +207,5 @@ Learn more about configuring and debugging CMake projects in Visual Studio: > [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)

> [Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md)

> [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) -> +> [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +> [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) diff --git a/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md b/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md index 979b34abdb..ca0ed06ff1 100644 --- a/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md +++ b/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md @@ -1,25 +1,27 @@ --- -description: "Learn more about: How to: Add Custom Build Tools to MSBuild Projects" -title: "How to: Add Custom Build Tools to MSBuild Projects" -ms.date: "11/04/2016" +description: "Learn more about how to add custom build tools to MSBuild projects" +title: "How to: Add custom build tools to MSBuild projects" +ms.date: 03/15/2022 helpviewer_keywords: ["msbuild (c++), howto: add custom build tools"] ms.assetid: de03899a-371d-4396-9bf9-34f45a65e909 --- -# How to: Add Custom Build Tools to MSBuild Projects +# How to: Add custom build tools to MSBuild projects -A custom build tool is a user-defined, command-line tool that is associated with a particular file. +A custom build tool is a user-defined, command-line tool that's associated with a particular file. -For a particular file, specify in the project file (.vcxproj) the command line to execute, any additional input or output files, and a message to display. If **MSBuild** determines that your output files are out of date with regard to your input files, it displays the message and executes the command-line tool. +For a particular file, specify in the project file (*`.vcxproj`*) the command line to execute, any other input or output files, and a message to display. If **MSBuild** determines that your output files are out of date relative to your input files, it displays the message and executes the command-line tool. -To specify when the custom build tool executes, use one or both of the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements in the project file. For example, you might specify that your custom build tool run after the MIDL compiler and before the C/C++ compiler. Specify the `CustomBuildBeforeTargets` element to execute the tool before a particular target runs; the `CustomBuildAfterTargets` element to execute the tool after a particular target; or both elements to run the tool between execution of two targets. If neither element is specified, your custom build tool executes at its default location, which is before the **MIDL** target. +## Specify custom build tools and custom build steps + +To specify when the custom build tool executes, use one or both of the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements in the project file. For example, you might specify that your custom build tool run after the MIDL compiler and before the C/C++ compiler. Specify the `CustomBuildBeforeTargets` element to execute the tool before a particular target runs. Use the `CustomBuildAfterTargets` element to execute the tool after a particular target runs. Use both elements to run the tool between execution of two targets. If neither element is specified, your custom build tool executes at its default location, which is before the **MIDL** target. Custom build steps and custom build tools share the information specified in the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements. Specify those targets one time in your project file. ### To add a custom build tool -1. Add an item group to the project file and add an item for each input file. Specify the command, additional inputs, outputs, and a message as item metadata, as shown here. This example assumes that a "faq.txt" file exists in the same directory as your project. +1. Add an item group to the project file and add an item for each input file. Specify the command and its inputs, outputs, and a message as item metadata, as shown here. This example assumes that a "faq.txt" file exists in the same directory as your project. The custom build step copies it to the output directory. - ``` + ```xml Copying readme... @@ -29,11 +31,11 @@ Custom build steps and custom build tools share the information specified in the ``` -### To define where in the build the custom build tools will execute +### To define where in the build the custom build tools execute -1. Add the following property group to the project file. You have to specify at least one of the targets, but you can omit the other if you are only interested in having your build step execute before (or after) a particular target. This example performs the custom step after compiling but before linking. +1. Add the following property group to the project file. You have to specify at least one of the targets. You can omit the other if you're only interested in having your build step execute before (or after) a particular target. This example performs the custom step after compiling but before linking. - ``` + ```xml ClCompile Link @@ -42,6 +44,8 @@ Custom build steps and custom build tools share the information specified in the ## See also -[Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md)
-[How to: Use Build Events in MSBuild Projects](how-to-use-build-events-in-msbuild-projects.md)
-[How to: Add a Custom Build Step to MSBuild Projects](how-to-add-a-custom-build-step-to-msbuild-projects.md) +[Walkthrough: Using MSBuild to create a C++ project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md)\ +[How to: Use build events in MSBuild projects](how-to-use-build-events-in-msbuild-projects.md)\ +[How to: Add a custom build step to MSBuild projects](how-to-add-a-custom-build-step-to-msbuild-projects.md)\ +[Common macros for MSBuild commands and properties](reference/common-macros-for-build-commands-and-properties.md)\ +[MSBuild well-known item metadata](/visualstudio/msbuild/msbuild-well-known-item-metadata) diff --git a/docs/build/how-to-create-a-cpp-project-from-existing-code.md b/docs/build/how-to-create-a-cpp-project-from-existing-code.md index 338beeacb2..7d4b11a4b2 100644 --- a/docs/build/how-to-create-a-cpp-project-from-existing-code.md +++ b/docs/build/how-to-create-a-cpp-project-from-existing-code.md @@ -1,21 +1,26 @@ --- description: "Learn more about: How to: Create a C++ Project from Existing Code" title: "How to: Create a C++ Project from Existing Code" -ms.date: "05/06/2019" +ms.date: 08/12/2024 helpviewer_keywords: ["C++, creating projects from existing code", "Create New Project From Existing Code Files Wizard, project settings"] f1_keywords: ["vc.appwiz.importwiz.location", "vc.appwiz.importwiz.appsettings", "vc.appwiz.importwiz.debugsettings", "vc.appwiz.importwiz.releasesettings"] -ms.assetid: e328a938-395c-48ea-9e35-dd433de12b31 --- # How to: Create a C++ Project from Existing Code -In Visual Studio, you can port existing code files into a C++ project using the **Create New Project From Existing Code Files** wizard. This wizard creates a project solution that uses the MSBuild system to manage source files and build configuration. It works best with relatively simple projects that do not have complex folder hierarchies. The wizard isn't available in older Express editions of Visual Studio. +In Visual Studio, you can port existing code files into a C++ project using the **Create New Project From Existing Code Files** wizard. This wizard creates a project solution that uses the MSBuild system to manage source files and build configuration. It works best with relatively simple projects that don't have complex folder hierarchies. The wizard isn't available in older Express editions of Visual Studio. Porting existing code files into a C++ project enables the use of native MSBuild project management features built into the IDE. If you prefer to use your existing build system, such as nmake makefiles, CMake, or alternatives, you can use the Open Folder or CMake options instead. For more information, see [Open Folder projects for C++](open-folder-projects-cpp.md) or [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md). Both options let you use IDE features such as [IntelliSense](/visualstudio/ide/using-intellisense) and [Project Properties](working-with-project-properties.md). ### To create a C++ project from existing code +The following instructions assume that Visual Studio is running and is past the start page. If you are on the Visual Studio start page, choose **Continue without code** to open the IDE. + 1. On the **File** menu, select **New** > **Project From Existing Code**. +1. The **Create New Project from Existing Code Files** wizard opens. Choose what type of project to create from the dropdown: **Visual C++**, **Visual Basic**, or **C#**. Then choose **Next** to continue. + :::image type="complex" source="./media/create-from-existing-code-wizard.png" alt-text="Screenshot showing the Create New Project from Existing Code dialog."::: + The project type dropdown shows the options Visual C++ (which is selected), Visual Basic, and C#. + :::image-end::: 1. Specify your project location, the directory for your source files, and the kinds of files the wizard imports into the new project. Choose **Next** to continue. | Setting | Description | @@ -58,7 +63,8 @@ Porting existing code files into a C++ project enables the use of native MSBuild > [!NOTE] > The **Build**, **Rebuild**, **Clean** command line, and **Output (for debugging)** settings are only enabled if the **Use external build system** option is selected on the **Specify Project Settings** page. -1. Specify the Release configuration settings to use, these settings are the same as the Debug configuration settings. Choose **Finish** to generate the new project. +1. Specify the Release configuration settings to use, these settings are the same as the Debug configuration settings. +1. Choose **Finish** to generate the new project. > [!NOTE] > Here you can check **Same as Debug configuration** to specify that the wizard will generate Release configuration project settings identical to Debug configuration project settings. This option is checked by default. All other options on this page are inactive unless you uncheck this box. diff --git a/docs/build/how-to-debug-a-release-build.md b/docs/build/how-to-debug-a-release-build.md index bb260ccf93..3063cfc32b 100644 --- a/docs/build/how-to-debug-a-release-build.md +++ b/docs/build/how-to-debug-a-release-build.md @@ -1,31 +1,27 @@ --- description: "Learn more about: How to: Debug a Release Build" title: "How to: Debug a Release Build" -ms.date: "11/04/2016" +ms.date: 03/14/2025 helpviewer_keywords: ["debugging [C++], release builds", "release builds, debugging"] -ms.assetid: d333e4d1-4e6c-4384-84a9-cb549702da25 --- # How to: Debug a Release Build -You can debug a release build of an application. +This article explains which compiler and linker switches to set to enable you to debug a release build of an application. -### To debug a release build +A better experience is available starting in Visual Studio 2022 version 17.14 that allows you to debug optimized code as if it were compiled unoptimized, while retaining the speed of optimized code. For more information, see [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging). -1. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). +## To debug a release build +1. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). 1. Click the **C/C++** node. Set **Debug Information Format** to [C7 compatible (/Z7)](reference/z7-zi-zi-debug-information-format.md) or **Program Database (/Zi)**. - 1. Expand **Linker** and click the **General** node. Set **Enable Incremental Linking** to [No (/INCREMENTAL:NO)](reference/incremental-link-incrementally.md). - -1. Select the **Debugging** node. Set **Generate Debug Info** to [Yes (/DEBUG)](reference/debug-generate-debug-info.md). - -1. Select the **Optimization** node. Set **References** to [/OPT:REF](reference/opt-optimizations.md) and **Enable COMDAT Folding** to [/OPT:ICF](reference/opt-optimizations.md). - +1. Under **Linker**, select the **Debugging** node. Set **Generate Debug Info** to [Yes (/DEBUG)](reference/debug-generate-debug-info.md). +1. Under **Linker**, select the **Optimization** node. Set **References** to [No (/OPT:NOREF)](reference/opt-optimizations.md) and **Enable COMDAT Folding** to [No (/OPT:NOICF)](reference/opt-optimizations.md). 1. You can now debug your release build application. To find a problem, step through the code (or use Just-In-Time debugging) until you find where the failure occurs, and then determine the incorrect parameters or code. If an application works in a debug build, but fails in a release build, one of the compiler optimizations may be exposing a defect in the source code. To isolate the problem, disable selected optimizations for each source code file until you locate the file and the optimization that is causing the problem. (To expedite the process, you can divide the files into two groups, disable optimization on one group, and when you find a problem in a group, continue dividing until you isolate the problem file.) - You can use [/RTC](reference/rtc-run-time-error-checks.md) to try to expose such bugs in your debug builds. + Use [/RTC](reference/rtc-run-time-error-checks.md) to try to expose such bugs in your debug builds. For more information, see [Optimizing Your Code](optimizing-your-code.md). diff --git a/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md b/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md deleted file mode 100644 index cb98e6dabb..0000000000 --- a/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -description: "Learn more about: How to: Embed a Manifest Inside a C/C++ Application" -title: "How to: Embed a Manifest Inside a C/C++ Application" -ms.date: "05/06/2019" -helpviewer_keywords: ["manifests [C++]", "embedding manifests", "makefiles, updating to embed manifest"] -ms.assetid: ec0bac69-2fdc-466c-ab0d-710a22974e5d ---- -# How to: Embed a Manifest Inside a C/C++ Application - -We recommended that you embed the manifest of your application or library inside the final binary because this guarantees correct runtime behavior in most scenarios. By default, Visual Studio tries to embed the manifest when it builds a project. For more information, see [Manifest Generation in Visual Studio](manifest-generation-in-visual-studio.md). However, if you build your application by using nmake, you have to make some changes to the makefile. This section shows how to change the makefiles so that it automatically embeds the manifest inside the final binary. - -## Two approaches - -There are two ways to embed the manifest inside an application or library. - -- If you are not doing an incremental build you can directly embed the manifest using a command line similar to the following as a post-build step: - - ```cmd - mt.exe -manifest MyApp.exe.manifest -outputresource:MyApp.exe;1 - ``` - - or - - ```cmd - mt.exe -manifest MyLibrary.dll.manifest -outputresource:MyLibrary.dll;2 - ``` - - Use 1 for an EXE and 2 for a DLL. - -- If you are doing an incremental build, use the following steps: - - - Link the binary to generate the MyApp.exe.manifest file. - - - Convert the manifest to a resource file. - - - Re-link (incrementally) to embed the manifest resource into the binary. - -The following examples show how to change makefiles to incorporate both techniques. - -## Makefiles (Before) - -Consider the nmake script for MyApp.exe, a simple application built from one file: - -``` -# build MyApp.exe -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -!else -CPPFLAGS=$(CPPFLAGS) /MD -!endif - -MyApp.exe : MyApp.obj - link $** /out:$@ $(LFLAGS) - -MyApp.obj : MyApp.cpp - -clean : - del MyApp.obj MyApp.exe -``` - -If this script is run unchanged with Visual Studio, it successfully creates MyApp.exe. It also creates the external manifest file MyApp.exe.manifest, for use by the operating system to load dependent assemblies at runtime. - -The nmake script for MyLibrary.dll looks very similar: - -``` -# build MyLibrary.dll -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /DLL /INCREMENTAL - -!else -CPPFLAGS=$(CPPFLAGS) /MD -LFLAGS=$(LFLAGS) /DLL - -!endif - -MyLibrary.dll : MyLibrary.obj - link $** /out:$@ $(LFLAGS) - -MyLibrary.obj : MyLibrary.cpp - -clean : - del MyLibrary.obj MyLibrary.dll -``` - -## Makefiles (After) - -To build with embedded manifests you have to make four small changes to the original makefiles. For the MyApp.exe makefile: - -``` -# build MyApp.exe -!include makefile.inc -#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -!else -CPPFLAGS=$(CPPFLAGS) /MD -!endif - -MyApp.exe : MyApp.obj - link $** /out:$@ $(LFLAGS) - $(_VC_MANIFEST_EMBED_EXE) -#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2 - -MyApp.obj : MyApp.cpp - -clean : - del MyApp.obj MyApp.exe - $(_VC_MANIFEST_CLEAN) -#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3 - -!include makefile.targ.inc -#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) -``` - -For the MyLibrary.dll makefile: - -``` -# build MyLibrary.dll -!include makefile.inc -#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /DLL /INCREMENTAL - -!else -CPPFLAGS=$(CPPFLAGS) /MD -LFLAGS=$(LFLAGS) /DLL - -!endif - -MyLibrary.dll : MyLibrary.obj - link $** /out:$@ $(LFLAGS) - $(_VC_MANIFEST_EMBED_DLL) -#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2. - -MyLibrary.obj : MyLibrary.cpp - -clean : - del MyLibrary.obj MyLibrary.dll - $(_VC_MANIFEST_CLEAN) -#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3. - -!include makefile.targ.inc -#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) -``` - -The makefiles now include two files that do the real work, makefile.inc and makefile.targ.inc. - -Create makefile.inc and copy the following into it: - -``` -# makefile.inc -- Include this file into existing makefile at the very top. - -# _VC_MANIFEST_INC specifies whether build is incremental (1 - incremental). -# _VC_MANIFEST_BASENAME specifies name of a temporary resource file. - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -_VC_MANIFEST_INC=1 -_VC_MANIFEST_BASENAME=__VC90.Debug - -!else -CPPFLAGS=$(CPPFLAGS) /MD -_VC_MANIFEST_INC=0 -_VC_MANIFEST_BASENAME=__VC90 - -!endif - -#################################################### -# Specifying name of temporary resource file used only in incremental builds: - -!if "$(_VC_MANIFEST_INC)" == "1" -_VC_MANIFEST_AUTO_RES=$(_VC_MANIFEST_BASENAME).auto.res -!else -_VC_MANIFEST_AUTO_RES= -!endif - -#################################################### -# _VC_MANIFEST_EMBED_EXE - command to embed manifest in EXE: - -!if "$(_VC_MANIFEST_INC)" == "1" - -#MT_SPECIAL_RETURN=1090650113 -#MT_SPECIAL_SWITCH=-notify_resource_update -MT_SPECIAL_RETURN=0 -MT_SPECIAL_SWITCH= -_VC_MANIFEST_EMBED_EXE= \ -if exist $@.manifest mt.exe -manifest $@.manifest -out:$(_VC_MANIFEST_BASENAME).auto.manifest $(MT_SPECIAL_SWITCH) & \ -if "%ERRORLEVEL%" == "$(MT_SPECIAL_RETURN)" \ -rc /r $(_VC_MANIFEST_BASENAME).auto.rc & \ -link $** /out:$@ $(LFLAGS) - -!else - -_VC_MANIFEST_EMBED_EXE= \ -if exist $@.manifest mt.exe -manifest $@.manifest -outputresource:$@;1 - -!endif - -#################################################### -# _VC_MANIFEST_CLEAN - command to clean resources files generated temporarily: - -!if "$(_VC_MANIFEST_INC)" == "1" - -_VC_MANIFEST_CLEAN=-del $(_VC_MANIFEST_BASENAME).auto.res \ - $(_VC_MANIFEST_BASENAME).auto.rc \ - $(_VC_MANIFEST_BASENAME).auto.manifest - -!else - -_VC_MANIFEST_CLEAN= - -!endif - -# End of makefile.inc -#################################################### -``` - -Now create **makefile.targ.inc** and copy the following into it: - -``` -# makefile.targ.inc - include this at the very bottom of the existing makefile - -#################################################### -# Commands to generate initial empty manifest file and the RC file -# that references it, and for generating the .res file: - -$(_VC_MANIFEST_BASENAME).auto.res : $(_VC_MANIFEST_BASENAME).auto.rc - -$(_VC_MANIFEST_BASENAME).auto.rc : $(_VC_MANIFEST_BASENAME).auto.manifest - type <<$@ -#include -1RT_MANIFEST"$(_VC_MANIFEST_BASENAME).auto.manifest" -<< KEEP - -$(_VC_MANIFEST_BASENAME).auto.manifest : - type <<$@ - - - -<< KEEP - -# end of makefile.targ.inc -``` - -## See also - -[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md) diff --git a/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md b/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md index 1c061847d2..4e5fb87009 100644 --- a/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md +++ b/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md @@ -3,7 +3,6 @@ description: "Learn more about: How to: Enable a 64-Bit, x64 hosted MSVC toolset title: "How to: Enable a 64-Bit MSVC Toolset on the Command Line" ms.date: "07/24/2019" helpviewer_keywords: ["x64 [C++]", "64-bit compiler [C++], command line usage", "64-bit compiler [C++], toolset enabling at command line", "command line [C++], 64-bit compiler", "Itanium [C++], command-line compiler", "IPF", "Itanium [C++]", "IPF, command-line compiler", "x64 [C++], command-line compiler"] -ms.assetid: 4da93a19-e20d-4778-902a-5eee9a6a90b5 --- # How to: Enable a 64-Bit, x64 hosted MSVC toolset on the command line @@ -11,11 +10,13 @@ Visual Studio includes C++ compilers, linkers, and other tools that you can use ## Use a 64-bit hosted developer command prompt shortcut -To access these command prompts on Windows, on the **Start** menu, open the folder for your version of Visual Studio, and then choose one of the x64 native or cross-tool developer command prompts. +To access these command prompts on Windows, on the **Start** menu type `x64` and then choose one of the x64 native or cross-tool developer command prompts. -![Windows Start menu showing the x64 Native Tools Command Prompt shortcut.](media/x64-native-tools-command-prompt.png "x64 Native Tools in Start Menu") +:::image type="complex" source="./media/x64-native-tools-command-prompt.png" alt-text="Screenshot showing the start menu with x64 in the search box and the x64 Native Tools Command Prompt shortcut selected."::: +If you have different versions of Visual Studio installed, other versions of the prompt appear. Choose the prompt for the version of Visual Studio that you want to use. +:::image-end::: -To access these command prompts on Windows 8.1, on the **Start** screen, open **All apps**. Under the heading for the installed version of Visual Studio, open the **Visual Studio** folder (in older versions of Visual Studio, it may be named **Visual Studio Tools**). On earlier versions of Windows, choose **Start**, expand **All Programs**, the folder for your version of **Visual Studio** (and on older versions of Visual Studio, **Visual Studio Tools**). For more information, see [Developer command prompt shortcuts](building-on-the-command-line.md#developer_command_prompt_shortcuts). +On earlier versions of Windows, choose **Start**, expand **All Programs**, and then expand the folder for your version of **Visual Studio** (and on older versions of Visual Studio, **Visual Studio Tools**). For more information, see [Developer command prompt shortcuts](building-on-the-command-line.md#developer_command_prompt_shortcuts). ## Use Vcvarsall.bat to set a 64-bit hosted build architecture diff --git a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md index b85c149a46..a91d9d9158 100644 --- a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md +++ b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md @@ -1,7 +1,6 @@ --- description: "Learn more about: How to: Modify the Target Framework and Platform Toolset" title: "How to: Modify the Target Framework and Platform Toolset" -ms.custom: "contperf-fy21q3" ms.date: 03/31/2021 helpviewer_keywords: ["msbuild (c++), howto: modify target framework and platform toolset"] --- @@ -24,7 +23,7 @@ Visual Studio also supports multitargeting for C++ projects. You can use the lat ## Target framework (C++/CLI project only) -When you change the target Framework, also change the platform toolset to a version that supports that Framework. For example, to target the .NET Framework 4.5, you must use a compatible platform toolset. These toolsets include Visual Studio 2015 (v140), Visual Studio 2013 (v120), or Visual Studio 2012 (v110). You can use the [Windows 7.1 SDK](https://www.microsoft.com/download/details.aspx?id=8279) to target .NET Framework 2.0, 3.0, 3.5, and 4. +When you change the target Framework, also change the platform toolset to a version that supports that Framework. For example, to target the .NET Framework 4.5, you must use a compatible platform toolset. These toolsets include Visual Studio 2015 (v140), Visual Studio 2013 (v120), or Visual Studio 2012 (v110). You can use the [Windows 7.1 SDK](https://www.microsoft.com/en-us/download/details.aspx?id=8442) to target .NET Framework 2.0, 3.0, 3.5, and 4. You can extend the target platform further by creating a custom platform toolset. For more information, see [C++ Native Multi-Targeting](https://devblogs.microsoft.com/cppblog/c-native-multi-targeting/) on the Visual C++ blog. diff --git a/docs/build/how-to-use-build-events-in-msbuild-projects.md b/docs/build/how-to-use-build-events-in-msbuild-projects.md index c747397334..72aea3d96a 100644 --- a/docs/build/how-to-use-build-events-in-msbuild-projects.md +++ b/docs/build/how-to-use-build-events-in-msbuild-projects.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: How to: Use Build Events in MSBuild Projects" title: "How to: Use Build Events in MSBuild Projects" +description: "Learn more about: How to: Use Build Events in MSBuild Projects" ms.date: "11/04/2016" helpviewer_keywords: ["msbuild (c++), howto: use build events in projects"] -ms.assetid: 2a58dc9d-3d50-4e49-97c1-86c5a05ce218 --- # How to: Use Build Events in MSBuild Projects @@ -33,7 +32,7 @@ The following table lists each *use-in-build* element: The following example can be added inside of the Project element of the myproject.vcxproj file created in [Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md). A *pre-build* event makes a copy of main.cpp; a *pre-link* event makes a copy of main.obj; and a *post-build* event makes a copy of myproject.exe. If the project is built using a release configuration, the build events are executed. If the project is built using a debug configuration, the build events are not executed. -``` xml +```xml copy $(ProjectDir)main.cpp $(ProjectDir)copyOfMain.cpp @@ -64,5 +63,5 @@ The following example can be added inside of the Project element of the myprojec ## See also -[MSBuild on the command line - C++](msbuild-visual-cpp.md)
+[MSBuild on the command line - C++](msbuild-visual-cpp.md)\ [Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md) diff --git a/docs/build/launch-vs-schema-reference-cpp.md b/docs/build/launch-vs-schema-reference-cpp.md index 787510553f..290cc1a1ce 100644 --- a/docs/build/launch-vs-schema-reference-cpp.md +++ b/docs/build/launch-vs-schema-reference-cpp.md @@ -18,7 +18,7 @@ To create the file, right-click on an executable file in **Solution Explorer** a | `buildConfigurations` | array | A key-value pair that specifies the name of the build mode to apply the configurations. For example, `Debug` or `Release` and the configurations to use according to the selected build mode. | | `currentDir` | string | Specifies the full directory path to the Build Target. The directory is detected automatically unless this parameter is set. | | `cwd` | string | Full path to the directory on the remote system where the program will run. Defaults to `"${debugInfo.defaultWorkingDirectory}"` | -| `debugType` | string | Specifies the debugging mode according to the type of code (native, managed, or mixed). The mode is automatically detected unless this parameter is set. Allowed values: `"native"`", `"managed"`, `"mixed"`. | +| `debugType` | string | Specifies the debugging mode according to the type of code (native, managed, or mixed). The mode is automatically detected unless this parameter is set. Allowed values: `"native"`, `"managed"`, `"mixed"`. | | `env` | array | Specifies a key-value list of custom environment variables. For example: `env:{"myEnv":"myVal"}`. | | `inheritEnvironments` | array | Specifies a set of environment variables inherited from multiple sources. You can define some variables in files like *`CMakeSettings.json`* or *`CppProperties.json`* and make them available to debug context. **Visual Studio 16.4:** Specify environment variables on a per-target basis using the `env.VARIABLE_NAME` syntax. To unset a variable, set it to `"null"`. | | `name` | string | Specifies the name of the entry in the **Startup Item** dropdown. | @@ -37,7 +37,7 @@ To create the file, right-click on an executable file in **Solution Explorer** a |--|--|--| | `program` | string | Full path to program executable on the remote machine. When using CMake, the macro `${debugInfo.fullTargetPath}` can be used as the value of this field. | | `processId` | integer | Optional process ID to attach the debugger to. | -| `sourceFileMap` | object | Optional source file mappings passed to the debug engine. Format: `{ "\": "\" }` or `{ "\": { "editorPath": "\", "useForBreakpoints": true } }`. Example: `{ "/home/user/foo": "C:\\foo" }` or `{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }`. See [Source file map options](#source_file_map_options). | +| `sourceFileMap` | object | Optional source file mappings passed to the debug engine. Format: `{ "\": "\" }` or `{ "\": { "editorPath": "\", "useForBreakpoints": true } }`. Example: `{ "/home/user/foo": "C:\\foo" }` or `{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }`. For more information, see [Source file map options](#source_file_map_options). | | `additionalProperties` | string | One of the sourceFileMapOptions. (See below.) | | `MIMode` | string | Indicates the type of MI-enabled console debugger that the MIDebugEngine will connect to. Allowed values are `"gdb"`, `"lldb"`. | | `args` | array | Command-line arguments passed to the program. | @@ -48,14 +48,14 @@ To create the file, right-click on an executable file in **Solution Explorer** a | `remoteMachineName` | string | The remote Linux machine that hosts gdb and the program to debug. Use the Connection Manager for adding new Linux machines. When using CMake, the macro `${debugInfo.remoteMachineName}` can be used as the value of this field. | | `miDebuggerPath` | string | The path to the MI-enabled debugger (such as gdb). When unspecified, it will search PATH first for the debugger. | | `miDebuggerServerAddress` | string | Network address of the MI-enabled debugger server to connect to. Example: `"localhost:1234"`. | -| `setupCommands` | array | One or more GDB/LLDB commands to execute to set up the underlying debugger. Example: `"setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]`. See [Launch setup commands](#launch_setup_commands). | +| `setupCommands` | array | One or more GDB/LLDB commands to execute to set up the underlying debugger. Example: `"setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]`. For more information, see [Launch setup commands](#launch_setup_commands). | | `customLaunchSetupCommands` | array | If provided, this value replaces the default commands used to launch a target with some other commands. For example, use "-target-attach" to attach to a target process. An empty command list replaces the launch commands with nothing, which can be useful if the debugger is being provided launch options as command-line options. Example: `"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`. | | `launchCompleteCommand` | string | The command to execute after the debugger is fully set up, to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run". | | `debugServerPath` | string | Optional full path to debug server to launch. Defaults to null. | | `debugServerArgs` | string | Optional debug server args. Defaults to null. | | `filterStderr` | boolean | Search stderr stream for server-started pattern and log stderr to debug output. Defaults to **`false`**. | | `coreDumpPath` | string | Optional full path to a core dump file for the specified program. Defaults to null. | -| externalConsole | boolean | If true, a console is launched for the debuggee. If **`false`**, no console is launched. The default for this setting is **`false`**. This option is ignored in some cases for technical reasons. | +| `externalConsole` | boolean | If true, a console is launched for the debuggee. If **`false`**, no console is launched. The default for this setting is **`false`**. This option is ignored in some cases for technical reasons. | | `pipeTransport` | string | When present, this value tells the debugger to connect to a remote computer using another executable as a pipe that will relay standard input/output between Visual Studio and the MI-enabled debugger (such as gdb). Allowed values: one or more [Pipe Transport Options](#pipe_transport_options). | ## debugInfo macros diff --git a/docs/build/manifest-generation-at-the-command-line.md b/docs/build/manifest-generation-at-the-command-line.md deleted file mode 100644 index e7acf1a1d6..0000000000 --- a/docs/build/manifest-generation-at-the-command-line.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: "Learn more about: Manifest Generation at the Command Line" -title: "Manifest Generation at the Command Line" -ms.date: "11/04/2016" -helpviewer_keywords: ["manifests [C++]", "manifest tool (mt.exe)"] -ms.assetid: fc2ff255-82b1-4c44-af76-8405c5850292 ---- -# Manifest Generation at the Command Line - -When building C/C++ applications from the command line using nmake or similar tools, the manifest is generated after the linker has processed all object files and built the final binary. The linker collects assembly information stored in the object files and combines this information into a final manifest file. By default the linker will generate a file named *binary_name*.*extension*.manifest to describe the final binary. The linker does not embed a manifest file inside the binary and can only generate a manifest as an external file. There are several ways to embed a manifest inside the final binary, such as using the [Manifest Tool (mt.exe)](/windows/win32/sbscs/mt-exe) or compiling the manifest into a resource file. It is important to keep in mind that specific rules have to be followed when embedding a manifest inside the final binary to enable such features as incremental linking, signing, and edit and continue. These and other options are discussed in [How to: Embed a Manifest Inside a C/C++ Application](how-to-embed-a-manifest-inside-a-c-cpp-application.md) when building on the command line. - -## See also - -[Manifests](/windows/win32/sbscs/manifests)
-[/INCREMENTAL (Link Incrementally)](reference/incremental-link-incrementally.md)
-[Strong Name Assemblies (Assembly Signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md)
-[Edit and Continue](/visualstudio/debugger/edit-and-continue)
-[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md)
diff --git a/docs/build/manifest-generation-in-visual-studio.md b/docs/build/manifest-generation-in-visual-studio.md deleted file mode 100644 index e8c943d4a3..0000000000 --- a/docs/build/manifest-generation-in-visual-studio.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: "Learn more about: Manifest Generation in Visual Studio" -title: "Manifest Generation in Visual Studio" -ms.date: "11/04/2016" -helpviewer_keywords: ["manifests [C++]"] -ms.assetid: 0af60aa9-d223-42cd-8426-b3fc543a2a81 ---- -# Manifest Generation in Visual Studio - -Generation of a manifest file for a particular project can be controlled in the project **Property Pages** dialog. On the **Configuration Properties** tab, click **Linker**, then **Manifest File**, then **Generate Manifest**. By default the project properties of new projects are set to generate a manifest file. However it is possible to disable generation of the manifest for a project using the **Generate Manifest** property of the project. When this property is set to **Yes**, the manifest for this project is generated. Otherwise the linker ignores assembly information when resolving dependencies of the application code, and does not generate the manifest. - -The build system in Visual Studio allows the manifest to be embedded in the final binary application file, or generated as an external file. This behavior is controlled by the **Embed Manifest** option in the **Project Properties** dialog. To set this property, open the **Manifest Tool** node, then select **Input and Output**. If the manifest is not embedded, it is generated as an external file and saved in the same directory as the final binary. If the manifest is embedded, Visual Studio embeds the final manifests using the following process: - -1. After the source code is compiled to object files, the linker collects dependent assembly information. While linking the final binary, the linker generates an intermediate manifest that is used later to generate the final manifest. - -1. After the intermediate manifest and linking are finished, the manifest tool will be executed to merge a final manifest and save it as an external file. - -1. The project build system then detects whether the manifest generated by the manifest tool contains different information than the manifest already embedded in the binary. - -1. If the manifest embedded in the binary is different from the manifest generated by the manifest tool, or the binary does not contain an embedded manifest, Visual Studio will invoke the linker one more time to embed the external manifest file inside the binary as a resource. - -1. If the manifest embedded in the binary is the same as the manifest generated by the manifest tool, the build will continue to the next build steps. - -The manifest is embedded inside the final binary as a text resource and it can be viewed by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the Dependencies of a Visual C++ Application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md) or follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) section. - -## See also - -[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md) diff --git a/docs/build/media/add-configure-preset-to-cmakepresets.png b/docs/build/media/add-configure-preset-to-cmakepresets.png index 343e8a85ed..47d963209c 100644 Binary files a/docs/build/media/add-configure-preset-to-cmakepresets.png and b/docs/build/media/add-configure-preset-to-cmakepresets.png differ diff --git a/docs/build/media/clang-install-vs2022.png b/docs/build/media/clang-install-vs2022.png new file mode 100644 index 0000000000..cd97b752d3 Binary files /dev/null and b/docs/build/media/clang-install-vs2022.png differ diff --git a/docs/build/media/cmake-build-errors.png b/docs/build/media/cmake-build-errors.png index 089db013a3..80127fdebd 100644 Binary files a/docs/build/media/cmake-build-errors.png and b/docs/build/media/cmake-build-errors.png differ diff --git a/docs/build/media/cmake-bullet3-connection-manager.png b/docs/build/media/cmake-bullet3-connection-manager.png index afdedb01e3..345ec7ec4b 100644 Binary files a/docs/build/media/cmake-bullet3-connection-manager.png and b/docs/build/media/cmake-bullet3-connection-manager.png differ diff --git a/docs/build/media/cmake-cmakelists-error.png b/docs/build/media/cmake-cmakelists-error.png index 6601ecbed3..5c0877845b 100644 Binary files a/docs/build/media/cmake-cmakelists-error.png and b/docs/build/media/cmake-cmakelists-error.png differ diff --git a/docs/build/media/cmake-cmakelists.png b/docs/build/media/cmake-cmakelists.png index f957bb6c1d..58f4729779 100644 Binary files a/docs/build/media/cmake-cmakelists.png and b/docs/build/media/cmake-cmakelists.png differ diff --git a/docs/build/media/cmake-debugger-entry.png b/docs/build/media/cmake-debugger-entry.png new file mode 100644 index 0000000000..0f7eae51a2 Binary files /dev/null and b/docs/build/media/cmake-debugger-entry.png differ diff --git a/docs/build/media/cmake-general-prefer-cmake-presets.png b/docs/build/media/cmake-general-prefer-cmake-presets.png index 4cb0c1ac64..1026817075 100644 Binary files a/docs/build/media/cmake-general-prefer-cmake-presets.png and b/docs/build/media/cmake-general-prefer-cmake-presets.png differ diff --git a/docs/build/media/cmake-install-2022.png b/docs/build/media/cmake-install-2022.png new file mode 100644 index 0000000000..870db48e1c Binary files /dev/null and b/docs/build/media/cmake-install-2022.png differ diff --git a/docs/build/media/cmake-targets-view.png b/docs/build/media/cmake-targets-view.png index f756047205..ac9dab9002 100644 Binary files a/docs/build/media/cmake-targets-view.png and b/docs/build/media/cmake-targets-view.png differ diff --git a/docs/build/media/cmake-targets-view2.png b/docs/build/media/cmake-targets-view2.png index 04ae1e2a13..673ddd555b 100644 Binary files a/docs/build/media/cmake-targets-view2.png and b/docs/build/media/cmake-targets-view2.png differ diff --git a/docs/build/media/create-from-existing-code-wizard.png b/docs/build/media/create-from-existing-code-wizard.png new file mode 100644 index 0000000000..881cbe8a36 Binary files /dev/null and b/docs/build/media/create-from-existing-code-wizard.png differ diff --git a/docs/build/media/debug-targets-view.png b/docs/build/media/debug-targets-view.png new file mode 100644 index 0000000000..a9ba70b3c5 Binary files /dev/null and b/docs/build/media/debug-targets-view.png differ diff --git a/docs/build/media/desktop-app-project-run-150.gif b/docs/build/media/desktop-app-project-run-150.gif deleted file mode 100644 index a46faeb947..0000000000 Binary files a/docs/build/media/desktop-app-project-run-150.gif and /dev/null differ diff --git a/docs/build/media/new-dropdowns.png b/docs/build/media/new-dropdowns.png new file mode 100644 index 0000000000..47a83973c6 Binary files /dev/null and b/docs/build/media/new-dropdowns.png differ diff --git a/docs/build/media/switch-to-targets-view.png b/docs/build/media/switch-to-targets-view.png new file mode 100644 index 0000000000..455bbfebc9 Binary files /dev/null and b/docs/build/media/switch-to-targets-view.png differ diff --git a/docs/build/media/vcppdir_libdir_macros.png b/docs/build/media/vcppdir_libdir_macros.png index 430fd309e7..80f0d633ed 100644 Binary files a/docs/build/media/vcppdir_libdir_macros.png and b/docs/build/media/vcppdir_libdir_macros.png differ diff --git a/docs/build/media/visual-c---project-defaults.png b/docs/build/media/visual-c---project-defaults.png index 3b3db949ce..659946ac9c 100644 Binary files a/docs/build/media/visual-c---project-defaults.png and b/docs/build/media/visual-c---project-defaults.png differ diff --git a/docs/build/media/visual-c---property-pages-showing-active-configuration.png b/docs/build/media/visual-c---property-pages-showing-active-configuration.png index 57e12a4419..521ba2fec9 100644 Binary files a/docs/build/media/visual-c---property-pages-showing-active-configuration.png and b/docs/build/media/visual-c---property-pages-showing-active-configuration.png differ diff --git a/docs/build/media/visual-c---property-pages-showing-release-config.png b/docs/build/media/visual-c---property-pages-showing-release-config.png index 763a22945a..39ff39170d 100644 Binary files a/docs/build/media/visual-c---property-pages-showing-release-config.png and b/docs/build/media/visual-c---property-pages-showing-release-config.png differ diff --git a/docs/build/media/vs2019-scan-module-dependencies.png b/docs/build/media/vs2019-scan-module-dependencies.png index 5b207ea85c..8541eff487 100644 Binary files a/docs/build/media/vs2019-scan-module-dependencies.png and b/docs/build/media/vs2019-scan-module-dependencies.png differ diff --git a/docs/build/media/vscpp-quickstart-first-run.gif b/docs/build/media/vscpp-quickstart-first-run.gif deleted file mode 100644 index 10d887cbcb..0000000000 Binary files a/docs/build/media/vscpp-quickstart-first-run.gif and /dev/null differ diff --git a/docs/build/media/x64-native-tools-command-prompt.png b/docs/build/media/x64-native-tools-command-prompt.png index ac088d3aa2..bc48f40b7a 100644 Binary files a/docs/build/media/x64-native-tools-command-prompt.png and b/docs/build/media/x64-native-tools-command-prompt.png differ diff --git a/docs/build/modify-project-properties-without-changing-project-file.md b/docs/build/modify-project-properties-without-changing-project-file.md index 55a167526f..aebbc2c0f7 100644 --- a/docs/build/modify-project-properties-without-changing-project-file.md +++ b/docs/build/modify-project-properties-without-changing-project-file.md @@ -1,7 +1,7 @@ --- description: "Learn more about: How to: Modify C++ project properties and targets without changing the project file" title: "How to: Modify C++ project properties and targets without changing the project file" -ms.date: "11/28/2018" +ms.date: "7/28/2023" helpviewer_keywords: ["project properties [C++], modifying outside project file"] --- # How to: Modify C++ project properties and targets without changing the project file @@ -13,27 +13,27 @@ You can override project properties and targets from the MSBuild command prompt *To override project properties:* -1. Create a .props file that specifies the properties you want to override. +1. Create a `.props` file that specifies the properties you want to override. -1. From the command prompt: set ForceImportBeforeCppTargets="C:\sources\my_props.props" +1. From the command prompt: `set ForceImportBeforeCppTargets="C:\sources\my_props.props"` *To override project targets:* -1. Create a .targets file with their implementation or a particular target +1. Create a `.targets` file with their implementation or a particular target -2. From the command prompt: set ForceImportAfterCppTargets ="C:\sources\my_target.targets" +2. From the command prompt: `set ForceImportAfterCppTargets ="C:\sources\my_target.targets"` -You can also set either option on the msbuild command line by using the /p: option: +You can also set either option on the msbuild command line by using the `/p:` option: ```cmd -> msbuild myproject.sln /p:ForceImportBeforeCppTargets="C:\sources\my_props.props" -> msbuild myproject.sln /p:ForceImportAfterCppTargets="C:\sources\my_target.targets" +msbuild myproject.sln /p:ForceImportBeforeCppTargets="C:\sources\my_props.props" +msbuild myproject.sln /p:ForceImportAfterCppTargets="C:\sources\my_target.targets" ``` -Overriding properties and targets in this way is equivalent to adding the following imports to all .vcxproj files in the solution: +Overriding properties and targets in this way is equivalent to adding the following imports to all `.vcxproj` files in the solution: -```cmd - +```xml + - + ``` diff --git a/docs/build/open-folder-projects-cpp.md b/docs/build/open-folder-projects-cpp.md index 7e49f70c10..dff693a632 100644 --- a/docs/build/open-folder-projects-cpp.md +++ b/docs/build/open-folder-projects-cpp.md @@ -74,7 +74,7 @@ This configuration inherits the environment variables of the Visual Studio [x64 ## Default configuration for MinGW-w64 -If you add the MinGW-W64 configuration, the JSON looks this this: +If you add the MinGW-W64 configuration, the JSON looks this: ```json { @@ -147,7 +147,6 @@ This creates (or opens) the *tasks.vs.json* file in the .vs folder which Visual } ] } - ``` The JSON file is placed in the *.vs* subfolder. To see that folder, click on the **Show All Files** button at the top of **Solution Explorer**. You can run this task by right-clicking on the root node in **Solution Explorer** and choosing **build hello**. When the task completes you should see a new file, *hello.exe* in **Solution Explorer**. @@ -194,7 +193,6 @@ To customize your program's command line arguments and debugging instructions, r } ] } - ``` To start debugging, choose the executable in the debug dropdown, then click the green arrow: diff --git a/docs/build/profile-guided-optimizations.md b/docs/build/profile-guided-optimizations.md index 4c6cdc579d..065565ef0d 100644 --- a/docs/build/profile-guided-optimizations.md +++ b/docs/build/profile-guided-optimizations.md @@ -9,7 +9,7 @@ ms.assetid: 2225c307-d3ae-42c1-8345-a5a959d132dc Profile-guided optimization (PGO) lets you optimize a whole executable file, where the optimizer uses data from test runs of the .exe or .dll file. The data represents the likely performance of the program in a production environment. -Profile-guided optimizations are only available for x86 or x64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. +Profile-guided optimizations are only available for x86, x64, or ARM64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. > [!NOTE] > Information that's gathered from profiling test runs overrides optimizations that would otherwise be in effect if you specify **/Ob**, **/Os**, or **/Ot**. For more information, see [/Ob (Inline Function Expansion)](reference/ob-inline-function-expansion.md) and [/Os, /Ot (Favor Small Code, Favor Fast Code)](reference/os-ot-favor-small-code-favor-fast-code.md). diff --git a/docs/build/project-property-inheritance.md b/docs/build/project-property-inheritance.md index cccf6e6fbe..3456a29290 100644 --- a/docs/build/project-property-inheritance.md +++ b/docs/build/project-property-inheritance.md @@ -24,7 +24,7 @@ Project properties are stored in several files. Some are stored directly in the ::: moniker range=">=msvc-160" -Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%MSBuild\Microsoft\VC\`*. The `` is specific to the version of Visual Studio. It's *`v160`* for Visual Studio 2019. +Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%\MSBuild\Microsoft\VC\`*. The `` is specific to the version of Visual Studio. It's *`v160`* for Visual Studio 2019. ::: moniker-end diff --git a/docs/build/reference/advanced-property-page.md b/docs/build/reference/advanced-property-page.md index a6e787e267..f119173610 100644 --- a/docs/build/reference/advanced-property-page.md +++ b/docs/build/reference/advanced-property-page.md @@ -1,9 +1,10 @@ --- description: "Use the Advanced property page in Visual Studio 2019 to set various properties for C++ projects." title: "Advanced Property Page (Project)" -ms.date: 11/22/2021 +ms.date: 08/31/2022 f1_keywords: ["VC.Project.VCConfiguration.TargetExt", "VC.Project.VCConfiguration.DeleteExtensionsOnClean", "VC.Project.VCConfiguration.BuildLogFile", "VC.Project.VCConfiguration.PreferredToolArchitecture", "VC.Project.VCConfiguration.UseDebugLibraries", "VC.Project.VCConfiguration.EnableUnitySupport", "VC.Project.VCConfiguration.CopyLocalDeploymentContent", "VC.Project.VCConfiguration.CopyLocalProjectReference", "VC.Project.VCConfiguration.CopyLocalDebugSymbols", "VC.Project.VCConfiguration.CopyCppRuntimeToOutputDir", "VC.Project.VCConfiguration.useOfMfc", "VC.Project.VCConfiguration.CharacterSet", "VC.Project.VCConfiguration.WholeProgramOptimization", "VC.Project.VCConfiguration.VCToolsVersion", "VC.Project.VCConfiguration.LLVMToolsVersion", "VC.Project.VCConfiguration.ManagedExtensions", "VC.Project.TargetFrameworkVersion", "VC.Project.VCConfiguration.EnableManagedIncrementalBuild", "VC.Project.VCConfiguration.ManagedAssembly"] --- + # Advanced Property Page ::: moniker range="<=msvc-150" @@ -42,7 +43,7 @@ To programmatically access this property, see **/ALIGN**[**:**_number_] +> **`/ALIGN`**\[**`:`*`number`***] ### Arguments -*number*
+*`number`*\ The alignment value in bytes. ## Remarks -The **/ALIGN** option specifies the alignment of each section within the linear address space of the program. The *number* argument is in bytes and must be a power of two. The default is 4K (4096). The linker issues a warning if the alignment produces an invalid image. +The **`/ALIGN`** linker option specifies the alignment of each section within the linear address space of the program. The *`number`* argument is in bytes and must be a power of two. The default is 4K (4096). The linker issues a warning if the alignment produces an invalid image. -Unless you are writing an application such as a device driver, you should not need to modify the alignment. +Unless you're writing an application such as a device driver, you shouldn't need to modify the alignment. -It is possible to modify the alignment of a particular section with the align parameter to the [/SECTION](section-specify-section-attributes.md) option. +It's possible to modify the alignment of a particular section with the *`align`* parameter to the [`/SECTION`](section-specify-section-attributes.md) option. -The alignment value that you specify cannot be smaller than the largest section alignment. +The alignment value that you specify can't be smaller than the largest section alignment. ### To set this linker option in the Visual Studio development environment @@ -40,5 +41,5 @@ The alignment value that you specify cannot be smaller than the largest section ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/allowbind-prevent-dll-binding.md b/docs/build/reference/allowbind-prevent-dll-binding.md index f3d1146904..583b85e26a 100644 --- a/docs/build/reference/allowbind-prevent-dll-binding.md +++ b/docs/build/reference/allowbind-prevent-dll-binding.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: /ALLOWBIND (Prevent DLL Binding)" -title: "/ALLOWBIND (Prevent DLL Binding)" -ms.date: "11/04/2016" +description: "Learn more about: /ALLOWBIND (Prevent DLL binding)" +title: "/ALLOWBIND (Prevent DLL binding)" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.PreventDLLBinding", "/allowbind"] helpviewer_keywords: ["/ALLOWBIND linker option", "binding DLLs", "preventing DLL binding", "ALLOWBIND linker option", "-ALLOWBIND linker option", "DLLs [C++], preventing binding"] ms.assetid: 30e37e24-12e4-407e-988a-39d357403598 --- -# /ALLOWBIND (Prevent DLL Binding) +# `/ALLOWBIND` (Prevent DLL binding) -``` -/ALLOWBIND[:NO] -``` +Set a flag to disallow DLL binding. + +## Syntax + +> **`/ALLOWBIND`**\[**`:NO`**] ## Remarks -/ALLOWBIND:NO sets a bit in a DLL's header that indicates to Bind.exe that the image is not allowed to be bound. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). +The **`/ALLOWBIND:NO`** linker option sets a bit in a DLL's header that indicates to Bind.exe that the image can't be bound. You may not want a DLL to be bound if it's been digitally signed (binding invalidates the signature). -You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND](allowbind.md) option of the EDITBIN utility. +You can edit an existing DLL for **`/ALLOWBIND`** functionality with the [`/ALLOWBIND`](allowbind.md) option of the EDITBIN utility. ### To set this linker option in the Visual Studio development environment @@ -24,7 +26,7 @@ You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND]( 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Enter `/ALLOWBIND:NO` into **Additional Options**. +1. Enter *`/ALLOWBIND:NO`* into **Additional Options**. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically @@ -32,7 +34,7 @@ You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND]( ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[BindImage function](/windows/win32/api/imagehlp/nf-imagehlp-bindimage)
-[BindImageEx function](/windows/win32/api/imagehlp/nf-imagehlp-bindimageex) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`BindImage` function](/windows/win32/api/imagehlp/nf-imagehlp-bindimage)\ +[`BindImageEx` function](/windows/win32/api/imagehlp/nf-imagehlp-bindimageex) diff --git a/docs/build/reference/allowbind.md b/docs/build/reference/allowbind.md index c57e11a615..b7404db175 100644 --- a/docs/build/reference/allowbind.md +++ b/docs/build/reference/allowbind.md @@ -11,7 +11,6 @@ ms.assetid: eaadbb8c-4339-4281-9a75-3a1ce2352ff8 Specifies whether a DLL can be bound. ``` - /ALLOWBIND[:NO] ``` diff --git a/docs/build/reference/allowisolation-manifest-lookup.md b/docs/build/reference/allowisolation-manifest-lookup.md index 7b475485b1..4d178ade64 100644 --- a/docs/build/reference/allowisolation-manifest-lookup.md +++ b/docs/build/reference/allowisolation-manifest-lookup.md @@ -1,32 +1,30 @@ --- -description: "Learn more about: /ALLOWISOLATION (Manifest Lookup)" -title: "/ALLOWISOLATION (Manifest Lookup)" -ms.date: "11/04/2016" +description: "Learn more about: /ALLOWISOLATION (Manifest lookup)" +title: "/ALLOWISOLATION (Manifest lookup)" +ms.date: 05/11/2022 f1_keywords: ["/ALLOWISOLATION", "VC.Project.VCLinkerTool.AllowIsolation"] helpviewer_keywords: ["-ALLOWISOLATION linker option", "/ALLOWISOLATION linker option"] ms.assetid: 6d41851e-b3c1-4bdf-beaa-031773089d6f --- -# /ALLOWISOLATION (Manifest Lookup) +# `/ALLOWISOLATION` (Manifest lookup) Specifies behavior for manifest lookup. ## Syntax -``` -/ALLOWISOLATION[:NO] -``` +> **`/ALLOWISOLATION`**\[**`:NO`**] ## Remarks -**/ALLOWISOLATION:NO** indicates DLLs are loaded as if there was no manifest and causes the linker to set the `IMAGE_DLLCHARACTERISTICS_NO_ISOLATION` bit in the optional header's `DllCharacteristics` field. +The **`/ALLOWISOLATION:NO`** linker option indicates DLLs are loaded as if there was no manifest and causes the linker to set the `IMAGE_DLLCHARACTERISTICS_NO_ISOLATION` bit in the optional header's `DllCharacteristics` field. -**/ALLOWISOLATION** causes the operating system to do manifest lookups and loads. +**`/ALLOWISOLATION`** causes the operating system to do manifest lookups and loads. -**/ALLOWISOLATION** is the default. +**`/ALLOWISOLATION`** is the default. -When isolation is disabled for an executable, the Windows loader will not attempt to find an application manifest for the newly created process. The new process will not have a default activation context, even if there is a manifest inside the executable or placed in the same directory as the executable with name executable-name**.exe.manifest**. +When isolation is disabled for an executable, the Windows loader won't attempt to find an application manifest for the newly created process. The new process won't have a default activation context, even if there's a manifest inside the executable or placed in the same directory as the executable with name *`.exe.manifest`*. -For more information, see [Manifest Files Reference](/windows/win32/SbsCs/manifest-files-reference). +For more information, see [Manifest files reference](/windows/win32/SbsCs/manifest-files-reference). ### To set this linker option in the Visual Studio development environment @@ -38,5 +36,5 @@ For more information, see [Manifest Files Reference](/windows/win32/SbsCs/manife ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/allowisolation.md b/docs/build/reference/allowisolation.md index 28ab8b6038..579f9900b3 100644 --- a/docs/build/reference/allowisolation.md +++ b/docs/build/reference/allowisolation.md @@ -13,7 +13,6 @@ Specifies behavior for manifest lookup. ## Syntax ``` - /ALLOWISOLATION[:NO] ``` diff --git a/docs/build/reference/analyze-code-analysis.md b/docs/build/reference/analyze-code-analysis.md index e2f0739798..8064dc9e98 100644 --- a/docs/build/reference/analyze-code-analysis.md +++ b/docs/build/reference/analyze-code-analysis.md @@ -1,10 +1,9 @@ --- title: "/analyze (Code analysis)" description: "The Microsoft C++ compiler /analyze option syntax and usage." -ms.date: 10/19/2021 -f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins", "VC.Project.VCCLCompilerTool.DisableAnalyzeExternal", "VC.Project.VCCLCompilerTool.AnalyzeExternalRuleset"] helpviewer_keywords: ["/analyze compiler option [C++]", "-analyze compiler option [C++]", "analyze compiler option [C++]"] -ms.assetid: 81da536a-e030-4bd4-be18-383927597d08 --- # `/analyze` (Code analysis) @@ -135,7 +134,7 @@ Then, use compiler option `/analyze:plugin EspXEngine.dll` to use the EspXEngine #### External file analysis options -Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. By using the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options, directories can be specified as "external" directories. Any files that are included by using `#include`from an external directory or one of its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). +Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. Use the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options to specify directories as "external" directories. Any files that are included by using `#include` from an external directory or its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). Code analysis provides these options to control analysis of external files: @@ -206,14 +205,14 @@ Specifies the current project directory. If the ruleset (or an item it includes) Specifies a semicolon-separated list of ruleset search paths. If the ruleset (or an item it includes) is a file name, then the compiler first looks for the file under the *`project_directory`* specified by **`/analyze:projectdirectory`**, if any, followed by the specified *`ruleset_directories`*. This option is available starting in Visual Studio 2019 version 16.9. **`/analyze:ruleset`** *`ruleset_files`*\ -Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. +Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end ::: moniker range="msvc-150" **`/analyze:ruleset`** *`ruleset_file`*\ -Specifies a ruleset file to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. +Specifies a ruleset file to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end @@ -267,6 +266,26 @@ For more information, see [Code analysis for C/C++ overview](../../code-quality/ 1. Modify one or more of the **Code Analysis** properties. +1. Choose **OK** or **Apply** to save your changes. + +::: moniker range=">=msvc-160" + +To set external file analysis options in Visual Studio 2019 version 16.10 and later: + +1. Open the project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - **Disable Code Analysis for External Headers** sets the **`/analyze:external-`** option. + + - **Analysis Ruleset for External Headers** sets the **`/analyze:external:ruleset path`** option. + +1. Choose **OK** or **Apply** to save your changes. + +::: moniker-end + ### To set this compiler option programmatically 1. See . diff --git a/docs/build/reference/appcontainer-windows-store-app.md b/docs/build/reference/appcontainer-windows-store-app.md index 4d57c088f3..4c0e6f856c 100644 --- a/docs/build/reference/appcontainer-windows-store-app.md +++ b/docs/build/reference/appcontainer-windows-store-app.md @@ -1,26 +1,22 @@ --- -description: "Learn more about: /APPCONTAINER (Microsoft Store App)" -title: "/APPCONTAINER (UWP/Microsoft Store App)" -ms.date: "11/04/2016" +description: "Learn more about: /APPCONTAINER (Microsoft Store app)" +title: "/APPCONTAINER (UWP/Microsoft Store app)" +ms.date: 05/11/2022 ms.assetid: 9a432db5-7640-460b-ab18-6f61fa7daf6f --- -# /APPCONTAINER (Microsoft Store App) +# `/APPCONTAINER` (Microsoft Store app) -Specifies whether the linker creates an executable image that must be run in an app container. +Specifies whether the linker creates an executable image that must run in an AppContainer environment. ## Syntax -``` -/APPCONTAINER[:NO] -``` +> **`/APPCONTAINER`**\[**`:NO`**] ## Remarks -By default, /APPCONTAINER is off. +The **`/APPCONTAINER`** linker option modifies an executable to indicate whether the app must run in the AppContainer process-isolation environment. Specify **`/APPCONTAINER`** for an app that must run in the AppContainer environment—for example, a Universal Windows Platform (UWP) or Windows Phone 8.x app. The option is set automatically in Visual Studio when you create a Universal Windows app from a template. For a desktop app, specify **`/APPCONTAINER:NO`** or just omit the option. By default, **`/APPCONTAINER`** is off. -This option modifies an executable to indicate whether the app must be run in the appcontainer process-isolation environment. Specify /APPCONTAINER for an app that must run in the appcontainer environment—for example, a Universal Windows Platform (UWP) or Windows Phone 8.x app. (The option is set automatically in Visual Studio when you create a Universal Windows app from a template.) For a desktop app, specify /APPCONTAINER:NO or just omit the option. - -The /APPCONTAINER option was introduced in Windows 8. +The **`/APPCONTAINER`** option was introduced in Windows 8. ### To set this linker option in Visual Studio @@ -28,9 +24,9 @@ The /APPCONTAINER option was introduced in Windows 8. 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter `/APPCONTAINER` or `/APPCONTAINER:NO`. +1. In **Additional Options**, enter *`/APPCONTAINER`* or *`/APPCONTAINER:NO`*. ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/appcontainer.md b/docs/build/reference/appcontainer.md index 3b0db522a6..7cf45709d1 100644 --- a/docs/build/reference/appcontainer.md +++ b/docs/build/reference/appcontainer.md @@ -11,7 +11,6 @@ ms.assetid: 0ca4f1ec-c8de-4a37-b3e2-deda7af0bb88 Marks an executable that must run in an app container—for example, a Microsoft Store or Universal Windows app. ``` - /APPCONTAINER[:NO] ``` diff --git a/docs/build/reference/arch-arm.md b/docs/build/reference/arch-arm.md index b622745e0e..8d7ebd3293 100644 --- a/docs/build/reference/arch-arm.md +++ b/docs/build/reference/arch-arm.md @@ -1,34 +1,31 @@ --- description: "Learn more about: /arch (ARM)" title: "/arch (ARM)" -ms.date: "11/04/2016" -ms.assetid: 4f1406ff-f174-487c-a126-8ab06cf447c1 +ms.date: 07/01/2022 --- -# /arch (ARM) +# `/arch` (ARM) -Specifies the architecture for code generation on ARM. See also [/arch (x86)](arch-x86.md) and [/arch (x64)](arch-x64.md). +Specifies the architecture for code generation on ARM. These switches apply to the ARM targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (ARM64)](arch-arm64.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (x86)](arch-x86.md) ## Syntax -``` -/arch:[ARMv7VE|VFPv4] -``` +> **`/arch:`**\[**`ARMv7VE`**|**`VFPv4`**] ## Arguments -**/arch:ARMv7VE**
+**`/arch:ARMv7VE`**\ Enables the use of ARMv7VE Virtualization Extensions instructions. -**/arch:VFPv4**
-Enables the use of ARM VFPv4 instructions. If this option is not specified, VFPv3 is the default. +**`/arch:VFPv4`**\ +Enables the use of ARM VFPv4 instructions. If this option isn't specified, VFPv3 is the default. ## Remarks -The `_M_ARM_FP` macro (for ARM only) indicates which, if any, **/arch** compiler option was used. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). +The `_M_ARM_FP` macro (for ARM only) indicates which, if any, **`/arch`** compiler option was used. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). -When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. **/arch** only affects code generation for native functions. +When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. **`/arch`** only affects code generation for native functions. -### To set the /arch:ARMv7VE or /arch:VFPv4 compiler option in Visual Studio +### To set the `/arch:ARMv7VE` or `/arch:VFPv4` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -42,6 +39,6 @@ When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/a ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md new file mode 100644 index 0000000000..7b432961ec --- /dev/null +++ b/docs/build/reference/arch-arm64.md @@ -0,0 +1,63 @@ +--- +title: "/arch (ARM64)" +description: "Learn more about: /arch (ARM64)" +ms.date: 05/24/2024 +--- +# `/arch` (ARM64) + +Specifies the Arm A-Profile architecture extension for code generation on ARM64. These switches apply to the ARM64 targeting version of the compiler. For more information about **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md). + +## Syntax + +>**`/arch:`**[[+feature]](feature-arm64.md)\ +>**`/arch:`**[[+feature]](feature-arm64.md) + +## Arguments + +**`/arch:armv8.x`**\ +Specifies the Armv8-A architecture, where **`x`** is a required extension value from **`0`** to **`9`**1. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified. + +**`/arch:armv9.x`**2\ +Specifies the Armv9-A architecture, where **`x`** is a required extension value from **`0`** to **`4`**. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified. + +## Remarks + +You can specify an ARM64 extension from Armv8.0-A through Armv8.9-A, and Armv9.0-A through Armv9.4-A. Optionally, enable one or more architecture features by appending a feature argument to the option3. For example, to target Armv8.0-A and enable feature `FEAT_LSE`, append feature argument **`lse`** so that the option becomes **`/arch:armv8.0+lse`**. For more information about available features and their requirements, see [`/feature` (ARM64)](feature-arm64.md)3. + +> [!NOTE] +> Depending on your version of Visual Studio, the compiler may not yet generate instructions from all feature sets required by the extension level you specify. For example, **`/arch:armv8.1`** allows the *`Interlocked`* intrinsic functions to use the appropriate atomic instruction introduced with the Armv8.1-A extension feature `FEAT_LSE`, but compiler support requires Visual Studio 2022 version 17.2 or later. + +The `_M_ARM64` macro is defined by default when compiling for an ARM64 target. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +The `__ARM_ARCH` macro is defined for `/arch:ARMv8.0` and higher. It indicates the ARM architecture extension level that the compiler is targeting. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +```cpp +#if __ARM_ARCH >= 802 + // code that requires ARMv8.2... +#endif +``` + +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. + +### To set the `/arch` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In the **Additional options** box, add *`/arch:armv8.0`* or replace `armv8.0` with a different ARM64 extension. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +1 Armv8-A architecture extension `armv8.9` is available starting in Visual Studio 2022 version 17.10.\ +2 Armv9-A architecture extensions are available starting in Visual Studio 2022 version 17.10.\ +3 Architecture feature enablement is available starting in Visual Studio 2022 version 17.10. + +## See also + +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[Predefined macros](../../preprocessor/predefined-macros.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-minimum-cpu-architecture.md b/docs/build/reference/arch-minimum-cpu-architecture.md index 48a02679bc..3c17866868 100644 --- a/docs/build/reference/arch-minimum-cpu-architecture.md +++ b/docs/build/reference/arch-minimum-cpu-architecture.md @@ -1,22 +1,23 @@ --- description: "Learn more about: /arch (Minimum CPU Architecture)" title: "/arch (Minimum CPU Architecture)" -ms.date: "11/04/2016" +ms.date: 06/30/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.EnableEnhancedInstructionSet", "/arch"] helpviewer_keywords: ["-arch compiler option [C++]", "/arch compiler option [C++]", "arch compiler option [C++]"] -ms.assetid: cc17da15-47bd-4e74-b905-4e73c3bdb8a0 --- -# /arch (Minimum CPU Architecture) +# `/arch` (Minimum CPU Architecture) -The architecture options specify the architecture for code generation. Select the base hardware architecture you are working with to see /arch options for that target platform. +The architecture options specify the architecture for code generation. Select the base hardware architecture you're working with to see **`/arch`** options for that target platform. -- [/arch (x86)](arch-x86.md) +- [`/arch (x86`)](arch-x86.md) -- [/arch (x64)](arch-x64.md) +- [`/arch (x64)`](arch-x64.md) -- [/arch (ARM)](arch-arm.md) +- [`/arch (ARM)`](arch-arm.md) + +- [`/arch (ARM64)`](arch-arm64.md) ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-x64.md b/docs/build/reference/arch-x64.md index ffa9f2996e..0bcf4ff202 100644 --- a/docs/build/reference/arch-x64.md +++ b/docs/build/reference/arch-x64.md @@ -1,57 +1,75 @@ --- description: "Learn more about: /arch (x64)" title: "/arch (x64)" -ms.date: "10/01/2019" -ms.assetid: ecda22bf-5bed-43f4-99fb-88aedd83d9d8 +ms.date: 06/30/2022 +f1_keywords: ["/arch:SSE2", "/arch:SSE4.2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1"] +helpviewer_keywords: ["/arch:SSE2 compiler option [C++]", "/arch:SSE4.2 compiler option [C++]", "/arch:AVX compiler option [C++]", "/arch:AVX2 compiler option [C++]", "/arch:AVX512 compiler option [C++]", "/arch:AVX10.1 compiler option [C++]"] --- -# /arch (x64) +# `/arch` (x64) -Specifies the architecture for code generation on x64. Also see [/arch (x86)](arch-x86.md) and [/arch (ARM)](arch-arm.md). +Specifies the architecture for code generation on x64. These switches apply to the x64 targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (ARM64)](arch-arm64.md), and [`/arch` (ARM)](arch-arm.md). ## Syntax -``` -/arch:[AVX|AVX2|AVX512] -``` +> **`/arch:`**\[**`SSE2`**|**`SSE4.2`**|**`AVX`**|**`AVX2`**|**`AVX512`**|**`AVX10.1`**] ## Arguments -**/arch:AVX**
-Enables the use of Intel Advanced Vector Extensions instructions. +**`/arch:SSE2`**\ +Enables Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. -**/arch:AVX2**
-Enables the use of Intel Advanced Vector Extensions 2 instructions. +**`/arch:SSE4.2`**\ +Enables Intel Streaming SIMD Extensions 4.2. -**/arch:AVX512**
-Enables the use of Intel Advanced Vector Extensions 512 instructions. +**`/arch:AVX`**\ +Enables Intel Advanced Vector Extensions. + +**`/arch:AVX2`**\ +Enables Intel Advanced Vector Extensions 2. + +**`/arch:AVX512`**\ +Enables Intel Advanced Vector Extensions 512. + +**`/arch:AVX10.1`**\ +Enables Intel Advanced Vector Extensions 10 version 1. ## Remarks -The **/arch** option enables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support additional extensions over those supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [__cpuid](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. +The **`/arch`** option enables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support extensions beyond the ones supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [`__cpuid`](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. You can also use the [`__check_isa_support`](../../intrinsics/check-isa-arch-support.md) intrinsic to check for more frequently used CPU features. -**/arch** only affects code generation for native functions. When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. The processor extensions have the following characteristics: -- The default mode uses SSE2 instructions for scalar floating-point and vector calculations. These instructions allow calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8 byte integer values, as well as single-precision and double-precision scalar floating-point values. +- The default mode uses SSE2 instructions for scalar floating-point and vector calculations. These instructions allow calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8-byte integer values, as well as single-precision and double-precision scalar floating-point values. + +- **`SSE4.2`** uses the full set of SSE instructions for floating-point scalar, vector, and integer vector calculations. + +- **`AVX`** introduced an alternative instruction encoding for vector and floating-point scalar instructions. It allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. -- **AVX** introduced an alternative instruction encoding for vector and floating-point scalar instructions that allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. +- **`AVX2`** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. -- **AVX2** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. +- **`AVX-512`** introduced another instruction encoding form that allows 512-bit vectors, masking, embedded rounding/broadcast, and new instructions. The default vector length for **`AVX-512`** is 512 bits and can be changed to 256 bits using the [`/vlen`](vlen.md) flag. -- **AVX-512** introduced another instruction encoding form that allows 512-bit vectors, plus certain other optional features. Instructions for additional operations were also added. +- **`AVX10.1`** adds more instructions on top of **`AVX-512`**. The default vector length for **`AVX10.1`** is 256 bits and can be changed to 512 bits using the [`/vlen`](vlen.md) flag. -Each **/arch** option may also enable the use of other non-vector instructions that are associated with that option. An example is the use of certain BMI instructions when **/arch:AVX2** is specified. +Each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the use of certain BMI instructions when **`/arch:AVX2`** is specified. -The `__AVX__` preprocessor symbol is defined when the **/arch:AVX**, **/arch:AVX2** or **/arch:AVX512** compiler option is specified. The `__AVX2__` preprocessor symbol is defined when the **/arch:AVX2** or **/arch:AVX512** compiler option is specified. The `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__` and `__AVX512VL__` preprocessor symbols are defined when the **/arch:AVX512** compiler option is specified. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). The **/arch:AVX2** option was introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **/arch:AVX512** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +The `__AVX__` preprocessor symbol is defined when the **`/arch:AVX`**, **`/arch:AVX2`**, **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX2__` preprocessor symbol is defined when the **`/arch:AVX2`**, **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__`, and `__AVX512VL__` preprocessor symbols are defined when the **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX10_VER__` preprocessor symbol is defined when the **`/arch:AVX10.1`** compiler option is specified. It indicates the AVX10 version the compiler is targeting. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). +The **`/arch:AVX2`** option was introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. +Limited support for **`/arch:AVX512`** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +Support for **`/arch:AVX10.1`** was added in Visual Studio 2022. -### To set the /arch:AVX, /arch:AVX2 or /arch:AVX512 compiler option in Visual Studio +### To set the `/arch` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. -1. In the **Enable Enhanced Instruction Set** drop-down box, choose **Advanced Vector Extensions (/arch:AVX)**, **Advanced Vector Extensions 2 (/arch:AVX2)** or **Advanced Vector Extensions 512 (/arch:AVX512)**. +1. Modify the **Enable Enhanced Instruction Set** property. ### To set this compiler option programmatically @@ -59,6 +77,6 @@ The `__AVX__` preprocessor symbol is defined when the **/arch:AVX**, **/arch:AVX ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-x86.md b/docs/build/reference/arch-x86.md index 73eefc119a..cb71ce0716 100644 --- a/docs/build/reference/arch-x86.md +++ b/docs/build/reference/arch-x86.md @@ -1,64 +1,68 @@ --- description: "Learn more about: /arch (x86)" title: "/arch (x86)" -ms.date: "10/01/2019" -ms.assetid: 9dd5a75d-06e4-4674-aade-33228486078d +ms.date: 06/30/2022 +f1_keywords: ["/arch:IA32", "/arch:SSE", "/arch:SSE2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1"] +helpviewer_keywords: ["/arch:IA32 compiler option [C++]", "/arch:SSE compiler option [C++]", "/arch:SSE2 compiler option [C++]", "/arch:AVX compiler option [C++]", "/arch:AVX2 compiler option [C++]", "/arch:AVX512 compiler option [C++]", "/arch:AVX10.1 compiler option [C++]"] --- -# /arch (x86) +# `/arch` (x86) -Specifies the architecture for code generation on x86. Also see [/arch (x64)](arch-x64.md) and [/arch (ARM)](arch-arm.md). +Specifies the architecture for code generation on x86. These switches apply to the x86 (32-bit) targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (ARM64)](arch-arm64.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md). ## Syntax -``` -/arch:[IA32|SSE|SSE2|AVX|AVX2|AVX512] -``` +> **`/arch:`**\[**`IA32`**|**`SSE`**|**`SSE2`**|**`AVX`**|**`AVX2`**|**`AVX512`**|**`AVX10.1`**] ## Arguments -**/arch:IA32**
+**`/arch:IA32`**\ Specifies no enhanced instructions and also specifies x87 for floating-point calculations. -**/arch:SSE**
-Enables the use of SSE instructions. +**`/arch:SSE`**\ +Enables Intel Streaming SIMD Extensions. -**/arch:SSE2**
-Enables the use of SSE2 instructions. This is the default instruction on x86 platforms if no **/arch** option is specified. +**`/arch:SSE2`**\ +Enables Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. -**/arch:AVX**
-Enables the use of Intel Advanced Vector Extensions instructions. +**`/arch:AVX`**\ +Enables Intel Advanced Vector Extensions. -**/arch:AVX2**
-Enables the use of Intel Advanced Vector Extensions 2 instructions. +**`/arch:AVX2`**\ +Enables Intel Advanced Vector Extensions 2. -**/arch:AVX512**
-Enables the use of Intel Advanced Vector Extensions 512 instructions. +**`/arch:AVX512`**\ +Enables Intel Advanced Vector Extensions 512. + +**`/arch:AVX10.1`**\ +Enables Intel Advanced Vector Extensions 10 version 1. ## Remarks -The **/arch** option enables or disables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support additional extensions over those supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [__cpuid](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. +The **`/arch`** option enables or disables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support extensions beyond the ones supported by older processors. You should consult the documentation for a particular processor or test for instruction set extension support using [`__cpuid`](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. You can also use the [`__check_isa_support`](../../intrinsics/check-isa-arch-support.md) intrinsic to check for more frequently used CPU features. + +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. -**/arch** only affects code generation for native functions. When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. +The **`/arch`** options refer to instruction set extensions with the following characteristics: -The **/arch** options refer to instruction set extensions with the following characteristics: +- **`IA32`** is the legacy 32-bit x86 instruction set without any vector operations and using x87 for floating-point calculations. -- **IA32** is the legacy 32-bit x86 instruction set without any vector operations and using x87 for floating-point calculations. +- **`SSE`** allows calculation with vectors of up to four single-precision floating-point values. Corresponding scalar floating-point instructions were added as well. -- **SSE** allows calculation with vectors of up to four single-precision floating-point values. Corresponding scalar floating-point instructions were added as well. +- **`SSE2`** allows calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4, or 8-byte integer values. Double-precision scalar instructions were also added. -- **SSE2** allows calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8 byte integer values. Double-precision scalar instructions were also added. +- **`AVX`** introduced an alternative instruction encoding for vector and floating-point scalar instructions. It allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. -- **AVX** introduced an alternative instruction encoding for vector and floating-point scalar instructions that allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. +- **`AVX2`** extends most integer operations to 256-bit vectors, and enables use of Fused Multiply-Add (FMA) instructions. -- **AVX2** extends most integer operations to 256-bit vectors, and enables use of Fused Multiply-Add (FMA) instructions. +- **`AVX512`** introduced another instruction encoding form that allows 512-bit vectors, masking, embedded rounding/broadcast, and new instructions. The default vector length for **`AVX512`** is 512 bits and can be changed to 256 bits using the [`/vlen`](vlen.md) flag. -- **AVX512** introduced another instruction encoding form that allows 512-bit vectors, plus certain other optional features. Instructions for additional operations were also added. +- **`AVX10.1`** adds more instructions on top of **`AVX-512`**. The default vector length for **`AVX10.1`** is 256 bits and can be changed to 512 bits using the [`/vlen`](vlen.md) flag. -The optimizer chooses when and how to use vector instructions depending on which **/arch** is specified. Scalar floating-point computations are performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. +The optimizer chooses when and how to use vector instructions depending on which **`/arch`** is specified. Scalar floating-point computations are usually performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. -In addition to the vector and floating-point scalar instructions, each **/arch** option may also enable the use of other non-vector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **/arch:IA32** is specified. +In addition to the vector and floating-point scalar instructions, each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **`/arch:IA32`** is specified. -Floating-point operations are normally rounded to double-precision (64-bit) in x87 code, but you can use `_controlfp` to modify the FP control word, including setting the precision control to extended precision (80-bit) or single-precision (32-bit). For more information, see [_control87, _controlfp, \__control87_2](../../c-runtime-library/reference/control87-controlfp-control87-2.md). SSE and AVX have separate single-precision and double-precision instructions for each operation, so there is no equivalent for SSE/AVX code. This can change how results are rounded when the result of a floating-point operation is used directly in further calculation instead of assigning it to a user variable. Consider the following: +Floating-point operations are normally rounded to double-precision (64-bit) in x87 code, but you can use `_controlfp` to modify the FP control word, including setting the precision control to extended precision (80-bit) or single-precision (32-bit). For more information, see [`_control87`, `_controlfp`, `__control87_2`](../../c-runtime-library/reference/control87-controlfp-control87-2.md). SSE and AVX have separate single-precision and double-precision instructions for each operation, so there's no equivalent for SSE/AVX code. It can change how results are rounded when the result of a floating-point operation is used directly in further calculation instead of assigning it to a user variable. Consider the following operations: ```cpp r = f1 * f2 + d; // Different results are possible on SSE/SSE2. @@ -72,7 +76,7 @@ r = t + d; // This should produce the same overall result // whether x87 stack is used or SSE/SSE2 is used. ``` -**/arch** and [/QIfist](qifist-suppress-ftol.md) cannot be used on the same compiland. The **/QIfist** option changes the rounding behavior of floating-point to integer conversion. The default behavior is to truncate (round toward zero), whereas the **/QIfist** option specifies use of the floating-point environment rounding mode. Because this changes the behavior of all floating-point to integer conversions, this flag has been deprecated. When compiling for SSE or AVX you can round a floating-point value to an integer using the floating-point environment rounding mode by using an intrinsic function sequence: +**`/arch`** and [`/QIfist`](qifist-suppress-ftol.md) can't be used together. The **`/QIfist`** option changes the rounding behavior of floating-point to integer conversion. The default behavior is to truncate (round toward zero), whereas the **`/QIfist`** option specifies use of the [floating-point environment](fp-specify-floating-point-behavior.md) rounding mode. Because the option changes the behavior of all floating-point to integer conversions, **`/QIfist`** is deprecated. When compiling for SSE or AVX, you can round a floating-point value to an integer using the floating-point environment rounding mode by using an intrinsic function sequence: ```cpp int convert_float_to_int(float x) { @@ -84,9 +88,9 @@ int convert_double_to_int(double x) { } ``` -The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__` and `__AVX512VL__` macros indicate which, if any, **/arch** compiler option was used. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). The **/arch:AVX2** option and `__AVX2__` macro were introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **/arch:AVX512** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__`, `__AVX512VL__`, and `__AVX10_VER__` macros indicate which, if any, **`/arch`** compiler option was used. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). The **`/arch:AVX2`** option, and `__AVX2__` macro were introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **`/arch:AVX512`** was added in Visual Studio 2017, and expanded in Visual Studio 2019. Support for **`/arch:AVX10.1`** was added in Visual Studio 2022. -### To set this compiler option for AVX, AVX2, AVX512, IA32, SSE, or SSE2 in Visual Studio +### To set the `/arch` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -100,6 +104,6 @@ The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX51 ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arm64-function-pad-min-x64.md b/docs/build/reference/arm64-function-pad-min-x64.md new file mode 100644 index 0000000000..28fabf8505 --- /dev/null +++ b/docs/build/reference/arm64-function-pad-min-x64.md @@ -0,0 +1,43 @@ +--- +description: "Learn more about: /ARM64XFUNCTIONPADMINX64 (Minimum padding between x64 functions in an ARM64X image)" +title: "/ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding)" +ms.date: 01/08/2024 +helpviewer_keywords: ["/ARM64XFUNCTIONPADMINX64 linker option", "-ARM64XFUNCTIONPADMINX64 linker option", "ARM64XFUNCTIONPADMINX64 linker option"] +--- +# /ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding) + +Specifies the minimum number of bytes of padding between x64 functions in ARM64X images. + +## Syntax + +``` +/ARM64XFUNCTIONPADMINX64:[number] +``` + +## Arguments + +*number*\ +The minimum number of bytes of padding between x64 functions. + +## Remarks + +This switch ensures that there is at least as much padding between X64 functions in an ARM64X image as specified. There may be more padding to meet architecture alignment requirements. + +This flag is available in Visual Studio 17.8 and later. + +### To set this linker option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Modify the **Additional Options** property to include **/ARM64XFUNCTIONPADMINX64:**`number`, where `number` is the minimum number of bytes of padding to put between x64 functions, and then choose **OK**. + +### To set this linker option programmatically + +- See . + +## See also + +[`/FUNCTIONPADMIN` (Create hotpatchable image)](../reference/functionpadmin-create-hotpatchable-image.md)\ +[`/NOFUNCTIONPADSECTION`](no-function-pad-section.md)\ +[MSVC Linker Options](linker-options.md)\ +[MSVC linker reference](linking.md) diff --git a/docs/build/reference/assemblydebug-add-debuggableattribute.md b/docs/build/reference/assemblydebug-add-debuggableattribute.md index 62c71671dc..fb77f5d492 100644 --- a/docs/build/reference/assemblydebug-add-debuggableattribute.md +++ b/docs/build/reference/assemblydebug-add-debuggableattribute.md @@ -1,56 +1,58 @@ --- description: "Learn more about: /ASSEMBLYDEBUG (Add DebuggableAttribute)" title: "/ASSEMBLYDEBUG (Add DebuggableAttribute)" -ms.date: "11/04/2016" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.AssemblyDebug", "/ASSEMBLYDEBUG"] helpviewer_keywords: ["/ASSEMBLYDEBUG linker option", "-ASSEMBLYDEBUG linker option", "ASSEMBLYDEBUG linker option"] ms.assetid: 94443af3-470c-41d7-83a0-7434563d7982 --- -# /ASSEMBLYDEBUG (Add DebuggableAttribute) +# `/ASSEMBLYDEBUG` (Add DebuggableAttribute) -``` -/ASSEMBLYDEBUG[:DISABLE] -``` +Specify whether to emit the `DebuggableAttribute` attribute with debug information tracking and to disable JIT optimizations. -/ASSEMBLYDEBUG emits the **DebuggableAttribute** attribute with debug information tracking and disables JIT optimizations. This is the same as specifying the following attribute in source: +## Syntax -``` +> **`/ASSEMBLYDEBUG`**\[**`:DISABLE`**] + +## Remarks + +The **`/ASSEMBLYDEBUG`** linker option emits the `DebuggableAttribute` attribute with debug information tracking and disables JIT optimizations. This option is the same as specifying the following attribute in source: + +```cpp [assembly:Debuggable(true, true)]; // same as /ASSEMBLYDEBUG ``` -/ASSEMBLYDEBUG:DISABLE emits the **DebuggableAttribute** attribute but disables the tracking of debug information and enables JIT optimizations. This is the same as specifying the following attribute in source: +**`/ASSEMBLYDEBUG:DISABLE`** emits the `DebuggableAttribute` attribute but disables the tracking of debug information and enables JIT optimizations. This option is the same as specifying the following attribute in source: -``` +```cpp [assembly:Debuggable(false, false)]; // same as /ASSEMBLYDEBUG:DISABLE ``` -The default is to not emit the **DebuggableAttribute** attribute. +By default, the linker doesn't emit the `DebuggableAttribute` attribute. -DebuggableAttribute can also be added to an assembly directly in source code. For example, +`DebuggableAttribute` can also be added to an assembly directly in source code. For example: -``` +```cpp [assembly:Debuggable(true, true)]; // same as /ASSEMBLYDEBUG ``` -## Remarks - -It is necessary to explicitly specify that a managed image be debuggable. Using [/Zi](z7-zi-zi-debug-information-format.md) alone is not sufficient. +You must explicitly specify that a managed image is debuggable. The [`/Zi`](z7-zi-zi-debug-information-format.md) option alone is insufficient. Other linker options that affect assembly generation are: -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -66,5 +68,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md b/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md index 8a36b426db..bb0cd45a3f 100644 --- a/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md +++ b/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md @@ -1,49 +1,51 @@ --- -description: "Learn more about: /ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource)" -title: "/ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYLINKRESOURCE (Link to .NET Framework resource)" +title: "/ASSEMBLYLINKRESOURCE (Link to .NET Framework resource)" +ms.date: 05/11/2022 f1_keywords: ["/ASSEMBLYLINKRESOURCE", "VC.Project.VCLinkerTool.AssemblyLinkResource"] helpviewer_keywords: ["-ASSEMBLYLINKRESOURCE linker option", "ASSEMBLYLINKRESOURCE linker option", "/ASSEMBLYLINKRESOURCE linker option"] ms.assetid: 8b6ad184-1b33-47a4-8513-4803cf915b64 --- -# /ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource) +# `/ASSEMBLYLINKRESOURCE` (Link to .NET Framework resource) -``` -/ASSEMBLYLINKRESOURCE:filename -``` +Create a link to a .NET Framework resource in the output file. + +## Syntax + +> **`/ASSEMBLYLINKRESOURCE:`*`filename`*** ## Arguments -*filename*
-The .NET Framework resource file to which you want to link from the assembly. +*`filename`* +The .NET Framework resource file to link from the assembly. ## Remarks -The /ASSEMBLYLINKRESOURCE option creates a link to a .NET Framework resource in the output file; the resource file is not placed in the output file. [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. +The **`/ASSEMBLYLINKRESOURCE`** linker option creates a link to a .NET Framework resource in the output file. The resource file isn't placed in the output file. Use the [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) option to embed a resource file in the output file. Linked resources are public in the assembly when created with the linker. -/ASSEMBLYLINKRESOURCE requires that the compilation include [/clr](clr-common-language-runtime-compilation.md); [/LN](ln-create-msil-module.md) or [/NOASSEMBLY](noassembly-create-a-msil-module.md) is not allowed with /ASSEMBLYLINKRESOURCE. +**`/ASSEMBLYLINKRESOURCE`** requires the [`/clr`](clr-common-language-runtime-compilation.md) compiler option. The [`/LN`](ln-create-msil-module.md) or [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) options aren't allowed with **`/ASSEMBLYLINKRESOURCE`**. -If *filename* is a .NET Framework resource file created, for example, by [Resgen.exe](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the **System.Resources** namespace. For more information, see [System.Resources.ResourceManager](/dotnet/api/system.resources.resourcemanager). For all other resources, use the **GetManifestResource**\* methods in the **System.Reflection.Assembly** class to access the resource at run time. +If *`filename`* is a .NET Framework resource file that's created, for example, by [`Resgen.exe`](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the `System.Resources` namespace. For more information, see [`System.Resources.ResourceManager`](/dotnet/api/system.resources.resourcemanager). For all other resources, use the `GetManifestResource*` methods in the `System.Reflection.Assembly` class to access the resource at run time. -*filename* can be any file format. For example, you may want to make a native DLL part of the assembly, so it can be installed into the Global Assembly Cache and accessed from managed code in the assembly. +*`filename`* can have any file format. For example, you may want to make a native DLL part of the assembly. Then it can be installed into the Global Assembly Cache and accessed from managed code in the assembly. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -51,7 +53,7 @@ Other linker options that affect assembly generation are: 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Type the option into the **Additional Options** box. +1. Enter the option in **Additional Options**. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically @@ -59,5 +61,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md b/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md index 59423c6bbc..60b001d27d 100644 --- a/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md +++ b/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md @@ -1,53 +1,53 @@ --- -description: "Learn more about: /ASSEMBLYMODULE (Add a MSIL Module to the Assembly)" -title: "/ASSEMBLYMODULE (Add a MSIL Module to the Assembly)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYMODULE (Add an MSIL module to the assembly)" +title: "/ASSEMBLYMODULE (Add an MSIL module to the assembly)" +ms.date: 05/11/2022 f1_keywords: ["/assemblymodule", "VC.Project.VCLinkerTool.AddModuleNamesToAssembly"] helpviewer_keywords: ["ASSEMBLYMODULE linker option", "assemblies [C++], adding modules to", "assemblies [C++]", "/ASSEMBLYMODULE linker option", "-ASSEMBLYMODULE linker option"] ms.assetid: 67357da8-e4b6-49fd-932c-329a5777f143 --- -# /ASSEMBLYMODULE (Add a MSIL Module to the Assembly) +# `/ASSEMBLYMODULE` (Add an MSIL module to the assembly) -``` -/ASSEMBLYMODULE:filename -``` +## Syntax -## Arguments +> **`/ASSEMBLYMODULE:`*`filename`*** -*filename*
+### Arguments + +*`filename`*\ The module you want to include in this assembly. ## Remarks -The /ASSEMBLYMODULE option allows you to add a module reference to an assembly. Type information in the module will not be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. +The **`/ASSEMBLYMODULE`** linker option allows you to add a module reference to an assembly. Type information in the module won't be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. -Use [#using](../../preprocessor/hash-using-directive-cpp.md) to both add a module reference to an assembly and make the module's type information available to the assembly program. +Use [`#using`](../../preprocessor/hash-using-directive-cpp.md) to both add a module reference to an assembly and make the module's type information available to the assembly program. For example, consider the following scenario: -1. Create a module with [/LN](ln-create-msil-module.md). +1. Create a module with [`/LN`](ln-create-msil-module.md). -1. Use /ASSEMBLYMODULE in a different project to include the module in the current compilation, which will create an assembly. This project will not reference the module with `#using`. +1. Use **`/ASSEMBLYMODULE`** in a different project to include the module in the current compilation, which creates an assembly. This project won't reference the module with `#using`. 1. Any project that references this assembly can now also use types from the module. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -The MSVC linker accepts .netmodule files as input and the output file produced by the linker will be an assembly or .netmodule with no run-time dependence on any of the .netmodules that were input to the linker. For more information, see [.netmodule Files as Linker Input](netmodule-files-as-linker-input.md). +The MSVC linker accepts *`.netmodule`* files as input and the output file produced by the linker will be an assembly or *`.netmodule`* file with no run-time dependence on any of the *`.netmodule`* files that were input to the linker. For more information, see [`.netmodule` files as linker input](netmodule-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment @@ -63,5 +63,5 @@ The MSVC linker accepts .netmodule files as input and the output file produced b ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblyresource-embed-a-managed-resource.md b/docs/build/reference/assemblyresource-embed-a-managed-resource.md index ee50a4984d..c21d423109 100644 --- a/docs/build/reference/assemblyresource-embed-a-managed-resource.md +++ b/docs/build/reference/assemblyresource-embed-a-managed-resource.md @@ -1,50 +1,52 @@ --- -description: "Learn more about: /ASSEMBLYRESOURCE (Embed a Managed Resource)" -title: "/ASSEMBLYRESOURCE (Embed a Managed Resource)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYRESOURCE (Embed a managed resource)" +title: "/ASSEMBLYRESOURCE (Embed a managed resource)" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.EmbedManagedResourceFile", "/ASSEMBLYRESOURCE"] helpviewer_keywords: ["ASSEMBLYRESOURCE linker option", "assemblies [C++]", "-ASSEMBLYRESOURCE linker option", "assemblies [C++], linking resource files", "/ASSEMBLYRESOURCE linker option"] ms.assetid: 0ce6e1fb-921b-4b1b-a59c-d35388d789f2 --- -# /ASSEMBLYRESOURCE (Embed a Managed Resource) +# `/ASSEMBLYRESOURCE` (Embed a managed resource) -``` -/ASSEMBLYRESOURCE:filename[,[name][,PRIVATE]] -``` +Embeds a managed resource in an assembly. -## Parameters +## Syntax -*filename*
+> **`/ASSEMBLYRESOURCE:`*`filename`***\[**`,`**\[***`name`***]\[**`,PRIVATE`**]] + +## Arguments + +*`filename`*\ The managed resource you want to embed in this assembly. -*name*
+*`name`*\ Optional. The logical name for the resource; the name used to load the resource. The default is the name of the file. -Optionally, you can specify if the file should be private in the assembly manifest. By default, *name* is public in the assembly. +Optionally, you can use `PRIVATE` to specify if the file should be private in the assembly manifest. By default, *`name`* is public in the assembly. ## Remarks -Use the /ASSEMBLYRESOURCE option to embed a resource in an assembly. +Use the **`/ASSEMBLYRESOURCE`** linker option to embed a resource in an assembly. -Resources are public in the assembly when created with the linker. The linker does not allow you to rename the resource in the assembly. +Resources are public in the assembly when created with the linker. The linker doesn't allow you to rename the resource in the assembly. -If *filename* is a .NET Framework resource (.resources) file created, for example, by the [Resource File Generator (Resgen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the **System.Resources** namespace (see [System.Resources.ResourceManager](/dotnet/api/system.resources.resourcemanager) for more information). For all other resources, use the **GetManifestResource**\* methods in **System.Reflection.Assembly** class to access the resource at run time. +If *`filename`* is a .NET Framework resource (*`.resources`*) file created, for example, by the [Resource file generator (`Resgen.exe`)](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the `System.Resources` namespace. For more information, see [`System.Resources.ResourceManager`](/dotnet/api/system.resources.resourcemanager). For all other resources, use the `GetManifestResource*` methods in the `System.Reflection.Assembly` class to access the resource at run time. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -60,5 +62,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/at-specify-a-linker-response-file.md b/docs/build/reference/at-specify-a-linker-response-file.md index db8b195c3c..b72b81d9d8 100644 --- a/docs/build/reference/at-specify-a-linker-response-file.md +++ b/docs/build/reference/at-specify-a-linker-response-file.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: @ (Specify a Linker Response File)" -title: "@ (Specify a Linker Response File)" -ms.date: "09/05/2018" +description: "Learn more about: @ (Specify a linker response file)" +title: "@ (Specify a linker response file)" +ms.date: 05/11/2022 f1_keywords: ["@"] helpviewer_keywords: ["linker [C++], response files", "command files [C++]", "command files [C++], linker response file", "@ linker option", "response files, C/C++ linker"] ms.assetid: 5530014f-17d0-4f6b-a6b0-a6ba34f34cfd --- -# @ (Specify a Linker Response File) +# `@` (Specify a linker response file) Specifies a linker response file. ## Syntax -> **\@**response_file +> **`@`** *`response_file`* ## Arguments -*response_file*
-A text file specifying linker commands. +*`response_file`*\ +A text file that contains linker commands. ## Remarks -See [@ (Specify a Compiler Response File)](at-specify-a-compiler-response-file.md) for more information. +For more information, see [`@` (Specify a compiler response file)](at-specify-a-compiler-response-file.md). ### To set this linker option in the Visual Studio development environment -- This linker option is not available from the Visual Studio development environment. +- This linker option isn't available from the Visual Studio development environment. ### To set this linker option programmatically -- This linker option cannot be changed programmatically. +- This linker option can't be changed programmatically. ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/atl-program-or-control-source-and-header-files.md b/docs/build/reference/atl-program-or-control-source-and-header-files.md index 827a02bd71..5057444504 100644 --- a/docs/build/reference/atl-program-or-control-source-and-header-files.md +++ b/docs/build/reference/atl-program-or-control-source-and-header-files.md @@ -1,26 +1,60 @@ --- -description: "Learn more about: ATL Program or Control Source and Header Files" -title: "ATL Program or Control Source and Header Files" -ms.date: "11/04/2016" +description: "Learn more about: ATL program or control source and header files" +title: "ATL program or control source and header files" +ms.date: 09/27/2022 helpviewer_keywords: ["file types [C++], ATL source and headers"] ms.assetid: cb65372f-4880-4007-b582-a52eaa568fd1 --- -# ATL Program or Control Source and Header Files +# ATL program or control source and header files -The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. +The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. The file names depend on the name you choose for your project, which we'll call *`ProjectName`*. -All of these files are located in the *Projname* directory, and in either the Header Files (.h files) folder or Source Files (.cpp files) folder in Solution Explorer. +All of the files created by the project template are located in the *`ProjectName`* and *`ProjectNamePS`* project directories. In Solution Explorer, the *`ProjectName`* files are located in the **Generated Files**, **Header Files**, **Resource Files**, and **Source Files** folders. The *`ProjectNamePS`* files are in the **Generated Files** and **Source Files** folders. Not all files listed here are generated for every project type. Files in the **Generated Files** folder are generated automatically by the MIDL compiler; they shouldn't be edited directly. -|File name|Description| -|---------------|-----------------| -|*Projname*.h|The main include file containing the C++ interface definitions and GUID declarations of the items defined in ATLSample.idl. It is regenerated by MIDL during compilation.| -|*Projname*.cpp|The main program source file. It contains the implementation of your DLL's exports for an in-process server and the implementation of `WinMain` for a local server. For a service, this additionally implements all the service management functions.| -|Resource.h|The header file for the resource file.| -|StdAfx.cpp|Includes the files StdAfx.h and Atlimpl.cpp.| -|StdAfx.h|Includes the ATL header files.| +::: moniker range=">=msvc-150" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`framework.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`Resource.h`* resource file header. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`Resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`pch.cpp`* | Includes the file *`pch.h`*. | +| *`pch.h`* | Includes the *`framework.h`* header file. | + +::: moniker-end + +::: moniker range="msvc-140" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`stdafx.cpp`* | Includes the file *`stdafx.h`*. | +| *`stdafx.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`resource.h`* resource file header. | + +::: moniker-end ## See also -[File Types Created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)
-[MFC Program or Control Source and Header Files](mfc-program-or-control-source-and-header-files.md)
-[CLR Projects](files-created-for-clr-projects.md) +[File types created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)\ +[MFC program or control source and header files](mfc-program-or-control-source-and-header-files.md)\ +[Add ATL support to an existing MFC executable or DLL](../../mfc/reference/adding-atl-support-to-your-mfc-project.md)\ +[CLR projects](files-created-for-clr-projects.md) diff --git a/docs/build/reference/base-base-address.md b/docs/build/reference/base-base-address.md index e6d026d383..1728032bac 100644 --- a/docs/build/reference/base-base-address.md +++ b/docs/build/reference/base-base-address.md @@ -1,54 +1,51 @@ --- -description: "Learn more about: /BASE (Base Address)" -title: "/BASE (Base Address)" -ms.date: "09/05/2018" +description: "Learn more about: /BASE (Base address)" +title: "/BASE (Base address)" +ms.date: 03/27/2025 f1_keywords: ["/base", "VC.Project.VCLinkerTool.BaseAddress"] helpviewer_keywords: ["base addresses [C++]", "programs [C++], preventing relocation", "semicolon [C++], specifier", "-BASE linker option", "key address size", "environment variables [C++], LIB", "programs [C++], base address", "LIB environment variable", "BASE linker option", "DLLs [C++], linking", "/BASE linker option", "@ symbol for base address", "executable files [C++], base address", "at sign symbol for base address"] -ms.assetid: 00b9f6fe-0bd2-4772-a69c-7365eb199069 --- -# /BASE (Base Address) +# `/BASE` (Base address) Specifies the base address for a program. ## Syntax -> **/BASE:**{*address*[**,**size] | **\@**filename**,**key} +> **`/BASE:`**{*`address`*[**`,`***`size`*] | **`@`***`filename`***`,`***`key`*} ## Remarks > [!NOTE] -> For security reasons, Microsoft recommends you use the [/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md) option instead of specifying base addresses for your executables. This generates an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. The /DYNAMICBASE option is on by default. +> For security reasons, Microsoft recommends you use the [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) option instead of specifying base addresses for your executables. **`/DYNAMICBASE`** generates an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. The **`/DYNAMICBASE`** option is on by default. -The /BASE option sets a base address for the program, overriding the default location for an .exe or DLL file. The default base address for an .exe file is 0x400000 for 32-bit images or 0x140000000 for 64-bit images. For a DLL, the default base address is 0x10000000 for 32-bit images or 0x180000000 for 64-bit images. On operating systems that do not support address space layout randomization (ASLR), or when the /DYNAMICBASE:NO option was set, the operating system first attempts to load a program at its specified or default base address. If sufficient space is not available there, the system relocates the program. To prevent relocation, use the [/FIXED](fixed-fixed-base-address.md) option. +The **`/BASE`** linker option sets a base address for the program. It overrides the default location for an EXE or DLL file. The default base address for an EXE file is 0x400000 for 32-bit images or 0x140000000 for 64-bit images. For a DLL, the default base address is 0x10000000 for 32-bit images or 0x180000000 for 64-bit images. On operating systems that don't support address space layout randomization (ASLR), or when the **`/DYNAMICBASE:NO`** option was set, the operating system first attempts to load a program at its specified or default base address. If insufficient space is available there, the system relocates the program. To prevent relocation, use the [`/FIXED`](fixed-fixed-base-address.md) option. -The linker issues an error if *address* is not a multiple of 64K. You can optionally specify the size of the program; the linker issues a warning if the program can't fit in the size you specified. +The linker issues an error if *`address`* isn't a multiple of 64K. You can optionally specify the size of the program. The linker issues a warning if the program can't fit in the size you specified. -On the command line, another way to specify the base address is by using a base address response file. A base address response file is a text file that contains the base addresses and optional sizes of all the DLLs your program will use, and a unique text key for each base address. To specify a base address by using a response file, use an at sign (**\@**) followed by the name of the response file, *filename*, followed by a comma, then the *key* value for the base address to use in the file. The linker looks for *filename* in either the specified path, or if no path is specified, in the directories specified in the LIB environment variable. Each line in *filename* represents one DLL and has the following syntax: +On the command line, another way to specify the base address is by using a *base address response file*. A base address response file is a text file that contains the base addresses and optional sizes of all the DLLs your program uses, and a unique text key for each base address. To specify a base address by using a response file, use an at sign (**`@`**) followed by the name of the response file, *`filename`*, followed by a comma, then the *`key`* value for the base address to use in the file. The linker looks for *`filename`* in either the specified path, or if no path is specified, in the directories specified in the `LIB` environment variable. The fully qualified *`filename`* must not exceed `MAX_PATH` (260 characters). Each line in *`filename`* represents one DLL and has the following syntax: -> *key* *address* [*size*] **;** *comment* +> *`key`* *`address`* \[*`size`*] **`;`** *`comment`* -The *key* is a string of alphanumeric characters and is not case sensitive. It is usually the name of a DLL, but it need not be. The *key* is followed by a base *address* in C-language, hexadecimal, or decimal notation and an optional maximum *size*. All three arguments are separated by spaces or tabs. The linker issues a warning if the specified *size* is less than the virtual address space required by the program. A *comment* is specified by a semicolon (**;**) and can be on the same or a separate line. The linker ignores all text from the semicolon to the end of the line. This example shows part of such a file: +The *`key`* is a string of alphanumeric characters and isn't case sensitive. It's usually the name of a DLL, but that's not required. The *`key`* is followed by a base *`address`* in C-language, hexadecimal, or decimal notation and an optional maximum *`size`*. All three arguments are separated by spaces or tabs. The linker issues a warning if the specified *`size`* is less than the virtual address space required by the program. A *`comment`* is specified by a semicolon (**`;`**) and can be on the same or a separate line. The linker ignores all text from the semicolon to the end of the line. This example shows part of such a file: -``` +```txt main 0x00010000 0x08000000 ; for PROJECT.exe one 0x28000000 0x00100000 ; for DLLONE.DLL two 0x28100000 0x00300000 ; for DLLTWO.DLL ``` -If the file that contains these lines is called DLLS.txt, the following example command applies this information: +If the file that contains these lines is called `DLLS.txt`, the following example command applies this information: -``` +```cmd link dlltwo.obj /dll /base:@dlls.txt,two ``` -Another way to set the base address is by using the *BASE* argument in a [NAME](name-c-cpp.md) or [LIBRARY](library.md) statement. The /BASE and [/DLL](dll-build-a-dll.md) options together are equivalent to the **LIBRARY** statement. +Another way to set the base address is by using the *`BASE`* argument in a [`NAME`](name-c-cpp.md) or [`LIBRARY`](library.md) statement. The **`/BASE`** and [`/DLL`](dll-build-a-dll.md) options together are equivalent to the **`LIBRARY`** statement. ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. - 1. Modify the **Base Address** property. ### To set this linker option programmatically @@ -57,5 +54,5 @@ Another way to set the base address is by using the *BASE* argument in a [NAME]( ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/bscmake-options.md b/docs/build/reference/bscmake-options.md index 2bd54b3e3d..f9b87e68d5 100644 --- a/docs/build/reference/bscmake-options.md +++ b/docs/build/reference/bscmake-options.md @@ -1,63 +1,67 @@ --- -title: "BSCMAKE Options" +title: "BSCMAKE options" description: "Reference to the Microsoft BSCMAKE utility command-line options." -ms.date: "02/09/2020" +ms.date: 03/21/2022 f1_keywords: ["VC.Project.VCBscMakeTool.OutputFile", "VC.Project.VCBscMakeTool.SuppressStartupBanner", "VC.Project.VCBscMakeTool.PreserveSBR"] helpviewer_keywords: ["/v BSCMAKE option", "Iu BSCMAKE option", "browse information files (.bsc), content", "/Er BSCMAKE option", "NOLOGO BSCMAKE option", "/s BSCMAKE option", "/Ei BSCMAKE option", "/o BSCMAKE option", "/NOLOGO BSCMAKE option", "/Iu BSCMAKE option", "s BSCMAKE option (/s)", "/Em BSCMAKE option", "Em BSCMAKE option", "Es BSCMAKE option", "files [C++], BSCMAKE", "Er BSCMAKE option", "BSCMAKE, options for controlling files", "controlling BSCMAKE options", "El BSCMAKE option", "/El BSCMAKE option", "/Es BSCMAKE option", "Ei BSCMAKE option"] ms.assetid: fa2f1e06-c684-41cf-80dd-6a554835ebd2 --- -# BSCMAKE Options +# BSCMAKE options > [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. -This section describes the options available for controlling BSCMAKE. Several options control the content of the browse information file by excluding or including certain information. The exclusion options can allow BSCMAKE to run faster and may result in a smaller *`.bsc`* file. Option names are case-sensitive (except for **/HELP** and **/NOLOGO**). +This section describes the options available for controlling BSCMAKE. Several options control the content of the browse information file by excluding or including certain information. The exclusion options can allow BSCMAKE to run faster and may result in a smaller *`.bsc`* file. Option names are case-sensitive (except for **`/HELP`** and **`/NOLOGO`**). -Only **/NOLOGO** and **/o** are available from within the Visual Studio development environment. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md) for information on access a project's property pages. +Only **`/NOLOGO`** and **`/o`** are available from within the Visual Studio development environment. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -**/Ei (**_filename_...**)**\ -Excludes the contents of the specified include files from the browse information file. To specify multiple files, separate the names with a space and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *filename*. Use **/Ei** along with the **/Es** option to exclude files not excluded by **/Es**. +## Options -**/El**\ +**`/Ei (`** *`filename`* ... **`)`**\ +Excludes the contents of one or more specified *`filename`* include files from the browse information file. To specify multiple files, separate the names with a space and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *`filename`*. Use **`/Ei`** along with the **`/Es`** option to exclude files not excluded by **`/Es`**. + +**`/El`**\ Excludes local symbols. The default is to include local symbols. For more information about local symbols, see [Creating an .sbr File](creating-an-dot-sbr-file.md). -**/Em**\ -Excludes symbols in the body of macros. Use **/Em** to include only the names of macros in the browse information file. The default is to include both the macro names and the result of the macro expansions. +**`/Em`**\ +Excludes symbols in the body of macros. Use **`/Em`** to include only the names of macros in the browse information file. The default is to include both the macro names and the result of the macro expansions. -**/Er (**_symbol_...**)**\ -Excludes the specified symbols from the browse information file. To specify multiple symbol names, separate the names with a space and enclose the list in parentheses. Parentheses are unnecessary if you specify only one *symbol*. +**`/Er (`** *`symbol`* ... **`)`**\ +Excludes one or more of the specified *`symbol`* symbols from the browse information file. To specify multiple symbol names, separate the names with a space and enclose the list in parentheses. Parentheses are unnecessary if you specify only one *`symbol`*. -**/Es**\ -Excludes every include file specified with an absolute path, or found in an absolute path specified in the INCLUDE environment variable. (Usually, these files are the system include files, which contain much information you may not need in your browse information file.) This option doesn't exclude files specified without a path, or with relative paths, or files found in a relative path in INCLUDE. You can use the **/Ei** option along with **/Es** to exclude files that **/Es** doesn't exclude. If you want to exclude only some of the files, use **/Ei** instead of **/Es**, and list the files you want to exclude. +**`/Es`**\ +Excludes every include file specified with an absolute path, or found in an absolute path specified in the INCLUDE environment variable. (Usually, these files are the system include files, which contain much information you may not need in your browse information file.) This option doesn't exclude files specified without a path, or with relative paths, or files found in a relative path in INCLUDE. You can use the **`/Ei`** option along with **`/Es`** to exclude files that **`/Es`** doesn't exclude. If you want to exclude only some of the files, use **`/Ei`** instead of **`/Es`**, and list the files you want to exclude. -**/errorreport:**[**none** | **prompt** | **queue** | **send**]\ -This option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. +**`/errorreport:`**\[ **`none`** \| **`prompt`** \| **`queue`** \| **`send`** ]\ +This option is deprecated. In Windows Vista and later, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. -**/HELP**\ +**`/HELP`**\ Displays a summary of the BSCMAKE command-line syntax. -**/Iu**\ +**`/Iu`**\ Includes unreferenced symbols. By default, BSCMAKE doesn't record any symbols that are defined but not referenced. If an *`.sbr`* file has been packed, this option has no effect for that input file because the compiler has already removed the unreferenced symbols. -**/n**\ -Forces a nonincremental build. Use **/n** to force a full build of the browse information file whether a *`.bsc`* file exists or not, and to prevent *`.sbr`* files from being truncated. See [How BSCMAKE Builds a .bsc File](how-bscmake-builds-a-dot-bsc-file.md). +**`/n`**\ +Forces a non-incremental build. Use **`/n`** to force a full build of the browse information file whether a *`.bsc`* file exists or not, and to prevent *`.sbr`* files from being truncated. For more information, see [How BSCMAKE builds a `.bsc` file](how-bscmake-builds-a-dot-bsc-file.md). -**/NOLOGO**\ +**`/NOLOGO`**\ Suppresses the BSCMAKE copyright message. -**/o** *filename*\ -Specifies a name for the browse information file. By default, BSCMAKE gives the browse information file the base name of the first *`.sbr`* file and a *`.bsc`* extension. +**`/o`** *`filename`*\ +The *`filename`* option parameter specifies a name for the browse information file. By default, BSCMAKE gives the browse information file the base name of the first *`.sbr`* file and a *`.bsc`* extension. -**/S (**_filename_...**)**\ -Tells BSCMAKE to process the specified include file the first time it's encountered and to exclude it otherwise. Use this option to save processing time when a file (such as a header, or *`.h`*, file for a *`.c`* or *`.cpp`* source file) is included in several source files but is unchanged by preprocessing directives each time. Use this option if a file is changed in ways unimportant for the browse information file you're creating. To specify multiple files, separate the names with a space, and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *filename*. If you want to exclude the file every time it's included, use the **/Ei** or **/Es** option. +**`/S (`** *`filename`* ... **`)`**\ +Tells BSCMAKE to process each specified *`filename`* include file the first time it's encountered and to exclude it otherwise. Use this option to save processing time when a file (such as a header, or *`.h`*, file for a *`.c`* or *`.cpp`* source file) is included in several source files but is unchanged by preprocessing directives each time. Use this option if a file is changed in ways unimportant for the browse information file you're creating. To specify multiple files, separate the names with a space, and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *`filename`*. If you want to exclude the file every time it's included, use the **`/Ei`** or **`/Es`** option. -**/v**\ +**`/v`**\ Provides verbose output, which includes the name of each *`.sbr`* file being processed and information about the complete BSCMAKE run. -**/?**\ +**`/?`**\ Displays a brief summary of BSCMAKE command-line syntax. -The following command line tells BSCMAKE to do a full build of MAIN.bsc from three *`.sbr`* files. It also tells BSCMAKE to exclude duplicate instances of TOOLBOX.h: +## Example + +The following command line tells BSCMAKE to do a full build of *`main.bsc`* from three *`.sbr`* files. It also tells BSCMAKE to exclude duplicate instances of *`toolbox.h`*: ```cmd BSCMAKE /n /S toolbox.h /o main.bsc file1.sbr file2.sbr file3.sbr @@ -65,4 +69,4 @@ BSCMAKE /n /S toolbox.h /o main.bsc file1.sbr file2.sbr file3.sbr ## See also -[BSCMAKE Reference](bscmake-reference.md) +[BSCMAKE reference](bscmake-reference.md) diff --git a/docs/build/reference/building-browse-information-files-overview.md b/docs/build/reference/building-browse-information-files-overview.md index d69bc31429..c7217d48af 100644 --- a/docs/build/reference/building-browse-information-files-overview.md +++ b/docs/build/reference/building-browse-information-files-overview.md @@ -1,43 +1,43 @@ --- description: "Learn more about: Building Browse Information Files: Overview" title: "Building Browse Information Files: Overview" -ms.date: "05/06/2019" +ms.date: 03/02/2022 helpviewer_keywords: [".bsc files, about .bsc files", "bsc files, about bsc files", "browse information files (.bsc)", "browse information files (.bsc), creating"] ms.assetid: b5c12832-51f6-4953-8044-4264dd0fb242 --- # Building Browse Information Files: Overview > [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server .sdf file in the solution folder. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. -To create browse information for symbol browsing, the compiler creates an .sbr file for each source file in your project, then BSCMAKE.EXE concatenates the .sbr files into one .bsc file. +To create browse information for symbol browsing, the compiler creates an *`.sbr`* file for each source file in your project, then BSCMAKE.EXE concatenates the *`.sbr`* files into one *`.bsc`* file. -Generating .sbr and .bsc files takes time, so Visual Studio turns these functions off by default. If you want to browse current information, you must turn the browse options on and build your project again. +Generating *`.sbr`* and *`.bsc`* files takes time, so Visual Studio turns off these functions by default. If you want to browse current information, you must turn on the browse options and build your project again. -Use [/FR](fr-fr-create-dot-sbr-file.md) or [/Fr](fr-fr-create-dot-sbr-file.md) to tell the compiler to create .sbr files. To create .bsc files, you can call [BSCMAKE](bscmake-command-line.md) from the command line. Using BSCMAKE from the command line gives you more precise control over the manipulation of browse information files. See [BSCMAKE Reference](bscmake-reference.md) for more information. +Use [`/FR`](fr-fr-create-dot-sbr-file.md) or [`/Fr`](fr-fr-create-dot-sbr-file.md) to tell the compiler to create *`.sbr`* files. To create *`.bsc`* files, you can call [BSCMAKE](bscmake-command-line.md) from the command line. Using BSCMAKE from the command line gives you more precise control over the manipulation of browse information files. For more information, see [BSCMAKE reference](bscmake-reference.md). > [!TIP] -> You can turn on .sbr file generation but leave .bsc file generation turned off. This provides fast builds but also enables you to create a fresh .bsc file quickly by turning on .bsc file generation and building the project. +> You can turn on *`.sbr`* file generation but leave *`.bsc`* file generation turned off. This provides fast builds but also enables you to create a fresh *`.bsc`* file quickly by turning on *`.bsc`* file generation and building the project. -You can reduce the time, memory, and disk space required to build a .bsc file by reducing the size of the .bsc file. +You can reduce the time, memory, and disk space required to build a *`.bsc`* file by reducing the size of the *`.bsc`* file. See [General Property Page (Project)](general-property-page-project.md) for information on how to build a browser file in the development environment. -### To create a smaller .bsc file +### To create a smaller `.bsc` file 1. Use [BSCMAKE command-line options](bscmake-options.md) to exclude information from the browse information file. -1. Omit local symbols in one or more .sbr files when compiling or assembling. +1. Omit local symbols in one or more *`.sbr`* files when compiling or assembling. -1. If an object file does not contain information needed for your current stage of debugging, omit its .sbr file from the BSCMAKE command when you rebuild the browse information file. +1. If an object file doesn't contain information needed for your current stage of debugging, omit its *`.sbr`* file from the BSCMAKE command when you rebuild the browse information file. -### To combine the browse information from several projects into one browser file (.bsc) +### To combine the browse information from several projects into one browser file (`.bsc`) -1. Either don't build the .bsc file at the project level or use the /n switch to prevent the .sbr files from being truncated. +1. Either don't build the *`.bsc`* file at the project level or use the **`/n`** switch to prevent the *`.sbr`* files from being truncated. -1. After all the projects are built, run BSCMAKE with all of the .sbr files as input. Wildcards are accepted. For instance, if you had project directories C:\X, C:\Y, and C:\Z with .sbr files in them and you wanted to combine them all into one .bsc file, then use BSCMAKE C:\X\\\*.sbr C:\Y\\\*.sbr C:\Z\\\*.sbr /o c:\whatever_directory\combined.bsc to build the combined .bsc file. +1. After all the projects are built, run BSCMAKE with all of the *`.sbr`* files as input. Wildcards are accepted. For instance, if you had project directories *`C:\X`*, *`C:\Y`*, and *`C:\Z`* with *`.sbr`* files in them and you wanted to combine them all into one *`.bsc`* file, then use `BSCMAKE C:\X\*.sbr C:\Y\*.sbr C:\Z\*.sbr /o c:\whatever_directory\combined.bsc` to build the combined *`.bsc`* file. ## See also -[Additional MSVC Build Tools](c-cpp-build-tools.md)
-[BSCMAKE Reference](bscmake-reference.md) +[Additional MSVC build tools](c-cpp-build-tools.md)\ +[BSCMAKE reference](bscmake-reference.md) diff --git a/docs/build/reference/c-compile-without-linking.md b/docs/build/reference/c-compile-without-linking.md index 4a881375b4..e552d6a30e 100644 --- a/docs/build/reference/c-compile-without-linking.md +++ b/docs/build/reference/c-compile-without-linking.md @@ -41,7 +41,7 @@ CL /c FIRST.C SECOND.C THIRD.OBJ To create an executable file, you must invoke LINK: ``` -LINK firsti.obj second.obj third.obj /OUT:filename.exe +LINK first.obj second.obj third.obj /OUT:filename.exe ``` ## See also diff --git a/docs/build/reference/c-cpp-prop-page.md b/docs/build/reference/c-cpp-prop-page.md index a5744b0b89..4f92e38d17 100644 --- a/docs/build/reference/c-cpp-prop-page.md +++ b/docs/build/reference/c-cpp-prop-page.md @@ -1,9 +1,9 @@ --- title: "C/C++ Project Properties (Visual Studio)" description: "Reference guide to the Visual Studio Microsoft C/C++ project Property Pages properties." -ms.date: 09/03/2020 +ms.date: 6/9/2023 ms.topic: "article" -ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7 +f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"] --- # C/C++ Property Pages @@ -13,22 +13,44 @@ The following property pages are found under **Project** > **Properties** > **Co ### Additional Include Directories -Specifies one or more directories to add to the include path; separate with semi-colons if more than one. Sets [`/I` (Additional include directories)](i-additional-include-directories.md). +Specifies one or more directories to add to the include path. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/I` (Additional include directories)](i-additional-include-directories.md) compiler option. ### Additional #using Directories -Specifies one or more directories (separate directory names with a semicolon) to be searched to resolve names passed to a #using directive. Sets [`/AI`](ai-specify-metadata-directories.md). +Specifies one or more directories to search to resolve names passed to a `#using` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/AI`](ai-specify-metadata-directories.md) compiler option. + +### Additional BMI Directories + +Specifies one or more directories to search to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the **`/ifcSearchDir[path]`** compiler option. + +### Additional Module Dependencies + +Specifies one or more modules to use to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/reference`](module-reference.md) compiler option. + +### Additional Header Unit Dependencies + +Specifies one or more header units to use to resolve names passed to an `import` header directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/headerUnit`](headerunit.md) compiler option. + +### Scan Sources for Module Dependencies + +When set to **Yes**, the compiler scans all C++ sources, not just module interface and header unit sources, for module and header units dependencies. The build system builds the full dependencies graph, which ensures that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header file that's specified in a [`header-units.json`](header-unit-json-reference.md) file in the same directory as the header file is compiled into a header unit. + +Files that have the extension *`.ixx`*, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/exportHeader)**, are always scanned. + +### Translate Includes to Imports + +When set to **Yes**, the compiler treats a `#include` directive as an `import` directive if certain conditions are met: The header file is specified in a *`header-units.json`* file in the same directory, and a compiled header unit (an *`.ifc`* file) is available for the header file. Otherwise, the header file is treated as a normal `#include`. The *`header-units.json`* file is used to build header units for each `#include` without symbol duplication. When combined with **Scan Sources for Module Dependencies**, the compiler automatically finds all of the header files that can be compiled into header units. This property sets the [`/translateInclude`](translateinclude.md) compiler option. ### Debug Information Format -Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md). +Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md) compiler options. #### Choices - **None** - Produces no debugging information, so compilation may be faster. - **C7 compatible** - Select the type of debugging information created for your program and whether this information is kept in object (.obj) files or in a program database (PDB). - **Program Database** - Produces a program database (PDB) that contains type information and symbolic debugging information for use with the debugger. The symbolic debugging information includes the names and types of variables and functions, and line numbers. -- **Program Database for Edit And Continue** - Produces a program database, as described above, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature. +- **Program Database for Edit And Continue** - Produces a program database, as described previously, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature. ### Support Just My Code Debugging @@ -90,7 +112,11 @@ Additional Security Development Lifecycle (SDL) recommended checks; includes ena ### Multi-processor Compilation -Multi-processor Compilation. +Enable multi-processor compilation. Sets the [`/MP`](mp-build-with-multiple-processes.md) compiler option. + +### Enable Address Sanitizer + +Compiles and links the program with AddressSanitizer instrumentation. This property currently supports x86 and x64 target builds. Sets the [`/fsanitize`](fsanitize.md) compiler option. ## C/C++ Optimization Properties @@ -115,7 +141,7 @@ Select the level of [inline function](../../cpp/inline-functions-cpp.md) expansi - **Default** - **Disabled** - Disables inline expansion, which is on by default. - **Only __inline** - Expands only functions marked as **`inline`**, **`__forceinline`**, or **`__inline`**. Or, in a C++ member function, defined within a class declaration. -- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *auto-inlining*.) +- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *autoinlining*.) ### Enable Intrinsic Functions @@ -216,9 +242,9 @@ Specify runtime library for linking. Sets [`/MT`, `/MTd`, `/MD`, `/MDd`](md-mt-l #### Choices - **Multi-threaded** - Causes your application to use the multithread, static version of the run-time library. -- **Multi-threaded Debug** - Defines _DEBUG and _MT. This option also causes the compiler to place the library name *LIBCMTD.lib* into the *`.obj`* file so that the linker will use *LIBCMTD.lib* to resolve external symbols. +- **Multi-threaded Debug** - Defines `_DEBUG` and `_MT`. This option also causes the compiler to place the library name *`LIBCMTD.lib`* into the *`.obj`* file so that the linker will use *`LIBCMTD.lib`* to resolve external symbols. - **Multi-threaded DLL** - Causes your application to use the multithread- and DLL-specific version of the run-time library. Defines `_MT` and `_DLL` and causes the compiler to place the library name *MSVCRT.lib* into the *`.obj`* file. -- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *MSVCRTD.lib* into the *`.obj`* file. +- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *`MSVCRTD.lib`* into the *`.obj`* file. ### Struct Member Alignment @@ -226,11 +252,11 @@ Specifies 1, 2, 4, or 8-byte boundaries for struct member alignment. Sets [`/Zp` #### Choices -- **1 Byte** - Packs structures on 1-byte boundaries. Same as **`/Zp`**. -- **2 Bytes** - Packs structures on 2-byte boundaries. -- **4 Bytes** - Packs structures on 4-byte boundaries. -- **8 Bytes** - Packs structures on 8-byte boundaries (default). -- **16 Bytes** - Packs structures on 16-byte boundaries. +- **1 Byte** - Packs structures on one-byte boundaries. Same as **`/Zp`**. +- **2 Bytes** - Packs structures on two-byte boundaries. +- **4 Bytes** - Packs structures on four-byte boundaries. +- **8 Bytes** - Packs structures on eight-byte boundaries (default). +- **16 Bytes** - Packs structures on sixteen-byte boundaries. - **Default** - Default alignment settings. ### Security Check @@ -261,7 +287,7 @@ Allows the compiler to generate parallel code for loops identified using `#pragm ### Enable Enhanced Instruction Set -Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler will use instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), and [`/arch (ARM)`](arch-arm.md). +Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler uses instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), [`/arch (ARM64)`](arch-arm64.md), and [`/arch (ARM)`](arch-arm.md). #### Choices @@ -280,7 +306,7 @@ Sets the floating point model. Sets [`/fp:precise`, `/fp:strict`, `/fp:fast`](fp - **Precise** - Default. Improves the consistency of floating-point tests for equality and inequality. - **Strict** - The strictest floating-point model. **`/fp:strict`** causes **`fp_contract`** to be OFF and **`fenv_access`** to be ON. **`/fp:except`** is implied and can be disabled by explicitly specifying **`/fp:except-`**. When used with **`/fp:except-`**, **`/fp:strict`** enforces strict floating-point semantics but without respect for exceptional events. -- **Fast** - Creates the fastest code in the majority of cases. +- **Fast** - Creates the fastest code in most cases. ### Enable Floating Point Exceptions @@ -305,11 +331,7 @@ Spectre mitigations for CVE 2017-5753. Sets [`/Qspectre`](qspectre.md). Suppresses or enables language extensions. Sets [`/Za`](za-ze-disable-language-extensions.md). -### Conformance mode - -Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md). - -### Treat wchar_t As Built in Type +### Treat WChar_t As Built in Type When specified, the type **`wchar_t`** becomes a native type that maps to **`__wchar_t`** in the same way that **`short`** maps to **`__int16`**. [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) is on by default. @@ -333,9 +355,9 @@ Adds code for checking C++ object types at run time (*runtime type information*, Enables OpenMP 2.0 language extensions. Sets [`/openmp`](openmp-enable-openmp-2-0-support.md). -### C++ Language Standard +### C++ Language Standard -Determines the C++ language standard the compiler enables. The default value doesn't set a standard option, so the compiler uses its default C++14 setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md). +Determines the C++ language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default C++14 setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md). #### Choices @@ -345,10 +367,28 @@ Determines the C++ language standard the compiler enables. The default value doe - **ISO C++20 Standard (/std:c++20)** - **Preview - Features from the Latest C++ Working Draft (/std:c++latest)** -### Enable C++ Modules (experimental) +### C Language Standard + +Determines the C language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default legacy MSVC setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md). + +#### Choices + +- **Default (Legacy MSVC)** +- **ISO C11 Standard (/std:c11)** +- **ISO C17 (2018) Standard (/std:c17)** + +### Conformance mode + +Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md). + +### Enable Experimental C++ Standard Library Modules Experimental support for the C++ Modules TS and Standard Library modules. +### Build ISO C++23 Standard Library Modules + +Starting in Visual Studio 17.6, when this property is enabled and [C++ Language Standard](#cpplang) is set to `/std:c++latest`, Visual C++ projects automatically find and build ISO C++23 Standard Library modules. This enables you to `import std` or `import std.compat` in your C++ code. + ## C/C++ Precompiled Headers Properties ### Create/Use Precompiled Header @@ -421,6 +461,28 @@ Specifies level of browse information in *`.bsc`* file. Sets [`/FR`](fr-fr-creat Specifies optional name for browser information file. Sets [`/FR`\](fr-fr-create-dot-sbr-file.md). +## External Includes + +### Treat Files Included with Angle Brackets as External + +Specifies whether to treat files included with angle brackets as external. Set this property to **Yes** to set the [`/external:anglebrackets`](external-external-headers-diagnostics.md) compiler option. + +### External Header Warning Level + +Select how strict you want the compiler to be about code errors in external headers. This property sets the [`/external:Wn`](external-external-headers-diagnostics.md) compiler option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + +### Template Diagnostics in External Headers + +Specifies whether to evaluate the warning level across a template instantiation chain. Set this property to **Yes** to set the [`/external:templates-`](external-external-headers-diagnostics.md) compiler option. + +### Disable Code Analysis for External Headers + +Disables code analysis for external headers. Sets the [`/analyze:external-`](analyze-code-analysis.md) compiler option. + +### Analysis Ruleset for External Headers + +Specifies a code analysis ruleset override for external headers. If not specified, the Code Analysis setting is used. Sets the [`/analyze:external:ruleset path`](analyze-code-analysis.md) compiler option. + ## C/C++ Advanced Properties ### Calling Convention @@ -436,13 +498,16 @@ Select the default calling convention for your application (can be overridden by ### Compile As -Select compile language option for *`.c`* and *`.cpp`* files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md). +Select compile language option for source files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md), [/interface](./interface.md), [`/internalPartition`](./internal-partition.md), or [`/exportHeader`](./module-exportheader.md) options. #### Choices - **Default** - Default. -- **Compile as C Code** - Compile as C Code. -- **Compile as C++ Code** - Compile as C++ Code. +- **Compile as C Code ([`/TC`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C code. By default, files with a *`.c`* extension are compiled as C. +- **Compile as C++ Code ([`/TP`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C++ code. By default, all source files that don't have a *`.c`*, *`.ixx`*, *`.cppm`*, *`.h`*, or no extension are compiled as C++. +- **Compile as C++ Module Code ([`/interface`](./interface.md))** - Compile specified source files as C++ module code. By default, files with a *`.ixx`* or *`.cppm`* extension are compiled as C++ module code. +- **Compile as C++ Module Internal Partition ([`/internalPartition`](./internal-partition.md))** - Compile specified source files as C++ module internal partition. +- **Compile as C++ Header Unit ([`/exportHeader`](./module-exportheader.md))** - Compile specified source files as C++ header unit. By default, files with a *`.h`* extension or no extension are compiled as header units. ### Disable Specific Warnings diff --git a/docs/build/reference/cetcompat.md b/docs/build/reference/cetcompat.md index 3eb8eecd94..d5c8870b4c 100644 --- a/docs/build/reference/cetcompat.md +++ b/docs/build/reference/cetcompat.md @@ -2,12 +2,12 @@ description: "Learn more about: /CETCOMPAT (CET Shadow Stack compatible)" title: "/CETCOMPAT (CET Shadow Stack compatible)" ms.date: 09/22/2021 -f1_keywords: ["/CETCOMPAT"] +f1_keywords: ["VC.Project.VCLinkerTool.CETCompat", "/CETCOMPAT"] helpviewer_keywords: ["/CETCOMPAT linker option", "/CETCOMPAT"] --- -# /CETCOMPAT (CET Shadow Stack compatible) +# `/CETCOMPAT` (CET Shadow Stack compatible) -Specifies whether to mark an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. +Specifies whether the linker marks an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. ## Syntax @@ -21,7 +21,7 @@ Specifies that the executable shouldn't be marked compatible with CET Shadow Sta ## Remarks -Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel’s Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html). +Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel's Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html). The **`/CETCOMPAT`** linker option tells the linker to mark the binary as CET Shadow Stack-compatible. **`/CETCOMPAT:NO`** marks the binary as not compatible with CET Shadow Stack. If both options are specified on the command line, the last one specified is used. This switch is currently only applicable to x86 and x64 architectures. @@ -31,7 +31,7 @@ The **`/CETCOMPAT`** option is available beginning in Visual Studio 2019. Starting in Visual Studio 2019 version 16.7: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. @@ -41,7 +41,7 @@ Starting in Visual Studio 2019 version 16.7: In previous versions of Visual Studio 2019: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. diff --git a/docs/build/reference/clr-restrictions.md b/docs/build/reference/clr-restrictions.md index 13ab850c9f..7f929098e7 100644 --- a/docs/build/reference/clr-restrictions.md +++ b/docs/build/reference/clr-restrictions.md @@ -1,74 +1,74 @@ --- description: "Learn more about: /clr Restrictions" title: "/clr Restrictions" -ms.date: "11/04/2016" +ms.date: 03/02/2022 helpviewer_keywords: ["/clr compiler option [C++], restrictions"] ms.assetid: 385f6462-2c68-46d6-810e-469553ead447 --- -# /clr Restrictions +# `/clr` Restrictions -Note the following restrictions on the use of **/clr**: +Note the following restrictions on the use of **`/clr`**: -- In a structured exception handler, there are restrictions on using `_alloca` when compiling with **/clr**. For more information, see [_alloca](../../c-runtime-library/reference/alloca.md). +- In a structured exception handler, there are restrictions on using `_alloca` when compiling with **`/clr`**. For more information, see [`_alloca`](../../c-runtime-library/reference/alloca.md). -- The use of run-time error checks is not valid with **/clr**. For more information, see [How to: Use Native Run-Time Checks](/visualstudio/debugger/how-to-use-native-run-time-checks). +- The use of run-time error checks isn't valid with **`/clr`**. For more information, see [How to: Use native run-time checks](/visualstudio/debugger/how-to-use-native-run-time-checks). -- When **/clr** is used to compile a program that only uses standard C++ syntax, the following guidelines apply to the use of inline assembly: +- When **`/clr`** is used to compile a program that only uses standard C++ syntax, the following guidelines apply to the use of inline assembly: - - Inline assembly code that assumes knowledge of the native stack layout, calling conventions outside of the current function, or other low-level information about the computer may fail if that knowledge is applied to the stack frame for a managed function. Functions containing inline assembly code are generated as unmanaged functions, as if they were placed in a separate module that was compiled without **/clr**. + - Inline assembly code that assumes knowledge of the native stack layout, calling conventions outside of the current function, or other low-level information about the computer may fail if that knowledge is applied to the stack frame for a managed function. Functions containing inline assembly code are generated as unmanaged functions, as if they were placed in a separate module that was compiled without **`/clr`**. - - Inline assembly code in functions that pass copy-constructed function parameters is not supported. + - Inline assembly code in functions that pass copy-constructed function parameters isn't supported. -- The [vprintf Functions](../../c-runtime-library/vprintf-functions.md) cannot be called from a program compiled with **/clr**. +- The [`vprintf` Functions](../../c-runtime-library/vprintf-functions.md) can't be called from a program compiled with **`/clr`**. -- The [naked](../../cpp/naked-cpp.md) [__declspec](../../cpp/declspec.md) modifier is ignored under /clr. +- The [`naked`](../../cpp/naked-cpp.md) [`__declspec`](../../cpp/declspec.md) modifier is ignored under **`/clr`**. -- The translator function set by [_set_se_translator](../../c-runtime-library/reference/set-se-translator.md) will affect only catches in unmanaged code. See [Exception Handling](../../extensions/exception-handling-cpp-component-extensions.md) for more information. +- The translator function set by [`_set_se_translator`](../../c-runtime-library/reference/set-se-translator.md) will affect only catches in unmanaged code. For more information, see [Exception handling](../../extensions/exception-handling-cpp-component-extensions.md). -- The comparison of function pointers is not permitted under **/clr**. +- The comparison of function pointers isn't permitted under **`/clr`**. -- The use of functions that are not fully prototyped is not permitted under **/clr**. +- The use of functions that aren't fully prototyped isn't permitted under **`/clr`**. -- The following compiler options are not supported with **/clr**: +- The following compiler options aren't supported with **`/clr`**: - - **/EHsc** and **/EHs** (**/clr** implies **/EHa** (see [/EH (Exception Handling Model)](eh-exception-handling-model.md)) + - **`/EHsc`** and **`/EHs`** (**`/clr`** implies **`/EHa`** (see [`/EH` (Exception Handling Model)](eh-exception-handling-model.md)) - - **/fp:strict** and **/fp:except** (see [/fp (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md)) + - **`/fp:strict`** and **`/fp:except`** (see [`/fp` (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md)) - - [/Zd](z7-zi-zi-debug-information-format.md) + - [`/Zd`](z7-zi-zi-debug-information-format.md) - - [/Gm](gm-enable-minimal-rebuild.md) + - [`/Gm`](gm-enable-minimal-rebuild.md) - - [/MT](md-mt-ld-use-run-time-library.md) + - [`/MT`](md-mt-ld-use-run-time-library.md) - - [/RTC](rtc-run-time-error-checks.md) + - [`/RTC`](rtc-run-time-error-checks.md) - - [/ZI](z7-zi-zi-debug-information-format.md) + - [`/ZI`](z7-zi-zi-debug-information-format.md) -- The combination of the `_STATIC_CPPLIB` preprocessor definition (`/D_STATIC_CPPLIB`) and the **/clr** compiler option is not supported. This is so because the definition would cause your application to link with the static multithreaded C++ Standard Library, which is not supported. For more information, see the [/MD, /MT, /LD (Use Run-Time Library)](md-mt-ld-use-run-time-library.md) topic. +- The combination of the `_STATIC_CPPLIB` preprocessor definition (`/D_STATIC_CPPLIB`) and the **`/clr`** compiler option isn't supported. It's because the definition would cause your application to link with the static, multithreaded C++ Standard Library, which isn't supported. For more information, see [`/MD`, `/MT`, `/LD` (Use Run-Time Library)](md-mt-ld-use-run-time-library.md). -- When using **/Zi** with **/clr**, there are performance implications. For more information, see [/Zi](z7-zi-zi-debug-information-format.md). +- When you use **`/Zi`** with **`/clr`**, there are performance implications. For more information, see [`/Zi`](z7-zi-zi-debug-information-format.md). -- Passing a wide character to a .NET Framework output routine without also specifying [/Zc:wchar_t](zc-wchar-t-wchar-t-is-native-type.md) or without casting the character to **`__wchar_t`** will cause the output to appear as an `unsigned short int`. For example: +- Passing a wide character to a .NET Framework output routine without also specifying [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) or without casting the character to **`_wchar_t`** will cause the output to appear as an `unsigned short int`. For example: ```cpp Console::WriteLine(L' ') // Will output 32. Console::WriteLine((__wchar_t)L' ') // Will output a space. ``` -- [/GS](gs-buffer-security-check.md) is ignored when compiling with **/clr**, unless a function is under `#pragma` [unmanaged](../../preprocessor/managed-unmanaged.md) or if the function must be compiled to native, in which case the compiler will generate warning C4793, which is off by default. +- [`/GS`](gs-buffer-security-check.md) is ignored when compiling with **`/clr`**, unless a function is under [`#pragma unmanaged`](../../preprocessor/managed-unmanaged.md) or if the function must be compiled as native code, in which case the compiler will generate warning C4793, which is off by default. -- See [/ENTRY](entry-entry-point-symbol.md) for function signature requirements of a managed application. +- See [`/ENTRY`](entry-entry-point-symbol.md) for function signature requirements of a managed application. -- Applications compiled with **/openmp** and **/clr** can only be run in a single appdomain process. See [/openmp (Enable OpenMP 2.0 Support)](openmp-enable-openmp-2-0-support.md) for more information. +- Applications compiled with **`/openmp`** and **`/clr`** can only be run in a single appdomain process. For more information, see [`/openmp` (Enable OpenMP 2.0 Support)](openmp-enable-openmp-2-0-support.md). -- Functions that take a variable number of arguments (varargs) will be generated as native functions. Any managed data types in the variable argument position will be marshaled to native types. Note that types are actually wide-character strings, but they are marshaled to single-byte character strings. So if a printf specifier is %S (wchar_t*), it will marshal to a %s string instead. +- Functions that take a variable number of arguments (varargs) will be generated as native functions. Any managed data types in the variable argument position will be marshaled to native types. Any types are actually wide-character strings, but they're marshaled to single-byte character strings. So if a `printf` specifier is `%S` (`wchar_t*`), it will marshal to a `%s` string instead. -- When using the va_arg macro, you may get unexpected results when compiling with **/clr:pure**. For more information, see [va_arg, va_copy, va_end, va_start](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. Code that must be "pure" or "safe" should be ported to C#. +- When using the `va_arg` macro, you may get unexpected results when compiling with **`/clr:pure`**. For more information, see [`va_arg`, `va_copy`, `va_end`, `va_start`](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). The **`/clr:pure`** and **`/clr:safe`** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. Code that must be "pure" or "safe" should be ported to C#. -- You should not call, from managed code, any functions that walk the stack to get parameter information (function arguments); the P/Invoke layer causes that information to be further down the stack. For example, do not compile proxy/stub with **/clr**. +- You shouldn't call any functions that walk the stack to get parameter information (function arguments) from managed code. The P/Invoke layer causes that information to be further down the stack. For example, don't compile proxy/stub with **`/clr`**. -- Functions will be compiled to managed code whenever possible, but not all C++ constructs can be translated to managed code. This determination is made on a function-by-function basis. If any part of a function cannot be converted to managed code, the entire function will be converted to native code instead. The following cases prevent the compiler from generating managed code. +- Functions will be compiled to managed code whenever possible, but not all C++ constructs can be translated to managed code. This determination is made on a function-by-function basis. If any part of a function can't be converted to managed code, the entire function will be converted to native code instead. The following cases prevent the compiler from generating managed code. - Compiler-generated thunks or helper functions. Native thunks are generated for any function call through a function pointer, including virtual function calls. @@ -76,10 +76,10 @@ Note the following restrictions on the use of **/clr**: - Functions that use certain intrinsic routines to directly manipulate machine resources. For example, the use of `__enable` and `__disable`, `_ReturnAddress` and `_AddressOfReturnAddress`, or multimedia intrinsics will all result in native code. - - Functions that follow the `#pragma unmanaged` directive. (Note that the inverse, `#pragma managed`, is also supported.) + - Functions that follow the `#pragma unmanaged` directive. (The inverse, `#pragma managed`, is also supported.) - A function that contains references to aligned types, that is, types declared using `__declspec(align(...))`. ## See also -- [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) +- [/clr (Common Language Runtime compilation)](clr-common-language-runtime-compilation.md) diff --git a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md index ef9e5e1e0d..7ab680d3cf 100644 --- a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md +++ b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md @@ -1,39 +1,39 @@ --- description: "Learn more about: /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" title: "/CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" -ms.date: "11/04/2016" -f1_keywords: ["/CLRSUPPORTLASTERROR"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CLRSupportLastError", "/CLRSUPPORTLASTERROR"] helpviewer_keywords: ["/CLRSUPPORTLASTERROR linker option", "-CLRSUPPORTLASTERROR linker option"] ms.assetid: b7057990-4154-4b1d-9fc9-6236f7be7575 --- -# /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls) +# `/CLRSUPPORTLASTERROR` (Preserve Last Error Code for PInvoke Calls) -**/CLRSUPPORTLASTERROR**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **/clr**. +**`/CLRSUPPORTLASTERROR`**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. ## Syntax -``` -/CLRSUPPORTLASTERROR{:NO | SYSTEMDLL} -``` +> **`/CLRSUPPORTLASTERROR`**\ +> **`/CLRSUPPORTLASTERROR:NO`**\ +> **`/CLRSUPPORTLASTERROR:SYSTEMDLL`** ## Remarks -Preserving the last error code implies a decrease in performance. If you do not want to incur the performance impact of preserving the last error code, link with **/CLRSUPPORTLASTERROR:NO**. +Preserving the last error code implies a decrease in performance. If you don't want to incur the performance cost of preserving the last error code, link by using **`/CLRSUPPORTLASTERROR:NO`**. -You can minimize the performance impact by linking with **/CLRSUPPORTLASTERROR:SYSTEMDLL**, which only preserves the last error code for functions in system DLLs. +You can minimize the performance penalty by linking with **`/CLRSUPPORTLASTERROR:SYSTEMDLL`**, which only preserves the last error code for functions in system DLLs. > [!NOTE] -> Preserving the last error is not supported for unmanaged functions that are consumed by CLR code, in the same module. +> Preserving the last error isn't supported for unmanaged functions that are consumed by CLR code in the same module. -- For more information, see [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). +- For more information, see [`/clr` (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Preserve Last Error Code for PInvoke Calls** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -56,7 +56,7 @@ __declspec(dllexport) double MySqrt(__int64 n) { } ``` -The following sample consumes the DLL, demonstrating how to use **/CLRSUPPORTLASTERROR**. +The following sample consumes the DLL, demonstrating how to use **`/CLRSUPPORTLASTERROR`**. ```cpp // CLRSUPPORTLASTERROR_client.cpp @@ -109,5 +109,5 @@ GetLastError for system call succeeded (183). ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md index fe8ce160d2..ffc60a41e9 100644 --- a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md +++ b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md @@ -1,37 +1,38 @@ --- description: "Learn more about: /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" title: "/CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" -ms.date: "05/16/2019" +ms.date: 09/19/2022 ms.topic: "reference" -f1_keywords: ["/CLRUNMANAGEDCODECHECK"] +f1_keywords: ["VC.Project.VCLinkerTool.CLRUnmanagedCodeCheck", "/CLRUNMANAGEDCODECHECK"] helpviewer_keywords: ["-CLRUNMANAGEDCODECHECK linker option", "/CLRUNMANAGEDCODECHECK linker option"] ms.assetid: 73abc426-dab0-45e2-be85-0f9a14206cc2 -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" +ms.author: "twhitney" --- -# /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute) +# `/CLRUNMANAGEDCODECHECK` (Remove SuppressUnmanagedCodeSecurityAttribute) -**/CLRUNMANAGEDCODECHECK** specifies that the linker does not apply to linker-generated `PInvoke` calls from managed code into native DLLs. +**`/CLRUNMANAGEDCODECHECK`** specifies that the linker doesn't apply to linker-generated `PInvoke` calls from managed code into native DLLs. ## Syntax -> **/CLRUNMANAGEDCODECHECK**[**:NO**] +> **`/CLRUNMANAGEDCODECHECK`**\ +> **`/CLRUNMANAGEDCODECHECK:NO`** ## Remarks -By default, the linker applies the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls. When **/CLRUNMANAGEDCODECHECK** is in effect, **SuppressUnmanagedCodeSecurityAttribute** is removed. To explicitly apply the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls, you can use **/CLRUNMANAGEDCODECHECK:NO**. +By default, the linker applies the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls. When **`/CLRUNMANAGEDCODECHECK`** is in effect, `SuppressUnmanagedCodeSecurityAttribute` is removed. To explicitly apply the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls, you can use **`/CLRUNMANAGEDCODECHECK:NO`**. -The linker only adds the attribute to objects that are compiled using **/clr** or **/clr:pure**. However, the **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. +The linker only adds the attribute to objects that are compiled using **`/clr`** or **`/clr:pure`**. However, the **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -A `PInvoke` call is generated by the linker when the linker cannot find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). +A `PInvoke` call is generated by the linker when the linker can't find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). -Note that if you use in your code, you should explicitly set **/CLRUNMANAGEDCODECHECK** to remove the **SuppressUnmanagedCodeSecurity** attribute. It is a potential security vulnerability if an image contains both the **SuppressUnmanagedCodeSecurity** and **AllowPartiallyTrustedCallers** attributes. +If you use in your code, you should explicitly set **`/CLRUNMANAGEDCODECHECK`** to remove the `SuppressUnmanagedCodeSecurity` attribute. It's a potential security vulnerability if an image contains both the `SuppressUnmanagedCodeSecurity` and `AllowPartiallyTrustedCallers` attributes. -See [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/framework/windows-identity-foundation/secure-coding-guidelines-for-unmanaged-code) for more information about the implications of using **SuppressUnmanagedCodeSecurityAttribute**. +For more information about the implications of using `SuppressUnmanagedCodeSecurityAttribute`, see [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/framework/windows-identity-foundation/secure-coding-guidelines-for-unmanaged-code). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. @@ -43,5 +44,5 @@ See [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/fram ## See also -- [MSVC linker reference](linking.md) -- [MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/command-line-property-pages.md b/docs/build/reference/command-line-property-pages.md index 9f7efcc20a..3e5ab9a2c5 100644 --- a/docs/build/reference/command-line-property-pages.md +++ b/docs/build/reference/command-line-property-pages.md @@ -1,20 +1,33 @@ --- -description: "Learn more about: Command Line Property Pages" -title: "Command Line Property Pages" -ms.date: "11/04/2016" +description: "Learn more about: Command line property pages" +title: "Command line property pages" +ms.date: 09/21/2022 f1_keywords: ["vc.project.AdditionalOptionsPage", "vc.project.CommandLinePage"] helpviewer_keywords: ["Command Line property pages"] ms.assetid: e1721b6c-8b39-4b44-a41e-69b5bb470cc9 --- -# Command Line Property Pages +# Command line property pages -Most property page folders contain a **Command Line** property page. This page displays which properties are set in the folder. The **Command Line** property page also contains an **Additional Options** box where you can specify properties that are valid for the tool but for which there is no property in the folder. +Most property page folders that correspond with a command-line tool contain a **Command Line** property page. For information on how to access the **Command Line** property pages, see [Set compiler and build properties](../working-with-project-properties.md). -Any command that you enter in the edit box will be passed through to the tool for the folder. No verification or checks will be done on the input, nor will there be any dependency checking. +## Command Line property page -For information on how to access the **Command Line** property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +### All Options + +The **All Options** display-only control shows the tool command line created by the properties set in the folder. + +### Additional Options + +This property's edit control lets you specify other command-line options that are valid for the tool but that don't have a corresponding property. + +The options that you enter in the edit box are passed through to the tool for the folder after the options listed in **All Options**. No verification or validity checks are done on the options you enter, and there's no dependency checking. ## See also -[C++ project property page reference](property-pages-visual-cpp.md)
-[.Lib Files as Linker Input](dot-lib-files-as-linker-input.md) +[Windows C++ project property page reference](property-pages-visual-cpp.md)\ +[Linux C++ property page reference](../../linux/prop-pages-linux.md)\ +[Linker property pages](./linker-property-pages.md)\ +[Manifest tool property pages](manifest-tool-property-pages.md)\ +[MIDL property pages](midl-property-pages.md)\ +[NMake property page](nmake-property-page.md)\ +[XML document generator tool property pages](xml-document-generator-tool-property-pages.md) diff --git a/docs/build/reference/commands-in-a-makefile.md b/docs/build/reference/commands-in-a-makefile.md index 05a0f36f14..9929e2f05b 100644 --- a/docs/build/reference/commands-in-a-makefile.md +++ b/docs/build/reference/commands-in-a-makefile.md @@ -18,7 +18,7 @@ A command preceded by a semicolon (**`;`**) can appear on a dependency line or i project.obj : project.c project.h ; cl /c project.c ``` -## Command modifiers +## Command modifiers You can specify one or more command modifiers preceding a command, optionally separated by spaces or tabs. As with commands, modifiers must be indented. @@ -28,7 +28,7 @@ You can specify one or more command modifiers preceding a command, optionally se | **`-`**\[*number*] *command* | Turns off error checking for *command*. By default, NMAKE halts when a command returns a nonzero exit code. If *-number* is used, NMAKE stops if the exit code exceeds *number*. Spaces or tabs can't appear between the dash and *number.* At least one space or tab must appear between *number* and *command*. Use **`/I`** to turn off error checking for the entire makefile; use **`.IGNORE`** to turn off error checking for part of the makefile. | | **`!`** *command* | Executes *command* for each dependent file if *command* uses **`$**`** (all dependent files in the dependency) or **`$?`** (all dependent files in the dependency with a later timestamp than the target). | -## Filename-parts syntax +## Filename-parts syntax Filename-parts syntax in commands represents components of the first dependent filename (which may be an implied dependent). Filename components are the file's drive, path, base name, and extension as specified, not as it exists on disk. Use **`%s`** to represent the complete filename. Use **`%|`**\[*parts*]**`F`** (a vertical bar character follows the percent symbol) to represent parts of the filename, where *parts* can be zero or more of the following letters, in any order. diff --git a/docs/build/reference/common-macros-for-build-commands-and-properties.md b/docs/build/reference/common-macros-for-build-commands-and-properties.md index 6cee9dc83c..dfe8c6a5c0 100644 --- a/docs/build/reference/common-macros-for-build-commands-and-properties.md +++ b/docs/build/reference/common-macros-for-build-commands-and-properties.md @@ -1,77 +1,87 @@ --- description: "Learn more about: Common macros for MSBuild commands and properties" title: "Common macros for MSBuild commands and properties" -ms.date: "08/02/2019" +ms.date: 01/12/2024 helpviewer_keywords: ["$(FrameworkSDKDir) macro", "ProjectName macro $(ProjectName)", "DevEnvDir macro $(DevEnvDir)", "$(DevEnvDir) macro", "TargetPath macro $(TargetPath)", "VSInstallDir macro $(VSInstallDir)", "$(InputFileName) macro", "$(SolutionFileName) macro", "macros [C++], build macros", "InputFileName macro $(InputFileName)", "$(VCInstallDir) macro", "$(IntDir) macro", "$(ConfigurationName) macro", "SolutionDir macro $(SolutionDir)", "$(TargetPath) macro", "$(Inherit) macro", "$(SolutionPath) macro", "WebDeployRoot macro $(WebDeployRoot)", "WebDeployPath macro $(WebDeployPath)", "StopEvaluating macro $(StopEvaluating)", "$(RootNamespace) macro", "$(WebDeployRoot) macro", "ProjectPath macro $(ProjectPath)", "$(ProjectPath) macro", "$(InputDir) macro", "SolutionName macro $(SolutionName)", "ProjectExt macro $(ProjectExt)", "$(TargetExt) macro", "$(ProjectFileName) macro", "TargetName macro $(TargetName)", "$(References) macro", "References macro $(References)", "TargetExt macro $(TargetExt)", "ProjectDir macro $(ProjectDir)", "$(TargetDir) macro", "SolutionExt macro $(SolutionExt)", "$(SolutionDir) macro", "ProjectFileName macro $(ProjectFileName)", "VCInstallDir macro $(VCInstallDir)", "$(InputExt) macro", "$(TargetFileName) macro", "$(SolutionExt) macro", "PlatformName macro $(PlatformName)", "IntDir macro $(IntDir)", "$(FrameworkVersion) macro", "$(ProjectDir) macro", "build macros [C++]", "InputPath macro $(InputPath)", "$(VSInstallDir) macro", "$(WebDeployPath) macro", "TargetFileName macro $(TargetFileName)", "NoInherit macro $(NoInherit)", "ConfigurationName macro $(ConfigurationName)", "$(ProjectExt) macro", "TargetDir macro $(TargetDir)", "InputName macro $(InputName)", "$(ProjectName) macro", "FrameworkSDKDir macro $(FrameworkSDKDir)", "$(ParentName) macro", "InputExt macro $(InputExt)", "$(SafeRootNamespace) macro", "InputDir macro $(InputDir)", "$(FxCopDir) macro", "$(RemoteMachine) macro", "Inherit macro $(Inherit)", "FrameworkVersion macro $(FrameworkVersion)", "$(StopEvaluating) macro", "$(OutDir) macro", "FrameworkDir macro $(FrameworkDir)", "SolutionFileName macro $(SolutionFileName)", "$(NoInherit) macro", "RemoteMachine macro $(RemoteMachine)", "properties [C++], build property macros", "$(TargetName) macro", "$(SolutionName) macro", "$(InputPath) macro", "ParentName macro $(ParentName)", "OutDir macro $(OutDir)", "SafeRootNamespace macro $(SafeRootNamespace)", "FxCopDir macro $(FxCopDir)", "$(InputName) macro", "RootNamespace macro $(RootNamespace)", "builds [C++], macros", "$(FrameworkDir) macro", "$(PlatformName) macro", "$(PlatformShortName) macro","SolutionPath macro $(SolutionPath)"] -ms.assetid: 239bd708-2ea9-4687-b264-043f1febf98b --- # Common macros for MSBuild commands and properties -Depending on your installation options, Visual Studio can make hundreds of macros available to you in a Visual Studio project (based on MSBuild). They correspond to the MSBuild properties that are set by default, or in .props or .targets files, or in your project settings. You can use these macros anywhere in a project's **Property Pages** dialog box where strings are accepted. These macros aren't case-sensitive. +Depending on your installation options, Visual Studio can make hundreds of macros available to you in an MSBuild-based *`.vcxproj`* Visual Studio project. The macros correspond to the MSBuild properties that are set by default, or in *`.props`* or *`.targets`* files, or in your project settings. You can use these macros anywhere in a project's **Property Pages** dialog box where strings are accepted. These macros aren't case-sensitive. ## View the current properties and macros -To display all of the currently available macros, in the **Property Pages** dialog, under **VC++ Directories**, choose the drop-down arrow at the end of a property row. Click on **Edit** and then in the edit dialog box, choose the **Macros** button. The current set of properties and macros visible to Visual Studio is listed along with the current value for each. For more information, see the **Specifying User-Defined Values** section of [C++ project property page reference](property-pages-visual-cpp.md). +To display all of the currently available macros, open the project property pages from the main menu by selecting **Project** > **Properties**. In the **Property Pages** dialog, choose an entry that has a macro in it. You can recognize a macro by the dollar sign and parenthesis that surround its name. -![Screenshot of the Library Directories dialog after choosing the Macros button.](../media/vcppdir_libdir_macros.png "Macros menu") +For example, in the left pane, select **Configuration Properties** > **VC++ Directories**, and then in the right pane, select **Include directories**. The value for **Include directories** is `$(VC_IncludePath);$(WindowsSDK_IncludePath);`. + +The dollar sign and parenthesis surrounding these two values indicates that they're macros. The expansion of those two macros sets the include directories to search. + +Select **Include Directories** and a dropdown appears at the end of the row. Select the dropdown button, then select **Edit**. In the **Include Directories** dialog box that appears, select the **Macros>>** button. + +That expands the dialog to show the current set of properties and macros visible to Visual Studio, along with the current value for each. For more information, see the **Specifying User-Defined Values** section of [C++ project property page reference](property-pages-visual-cpp.md). + +:::image type="complex" source="../media/vcppdir_libdir_macros.png" alt-text="Screenshot of the Visual Studio Include Directories dialog after choosing the Macros button."::: +On the right is a list of Visual Studio macros such as $(AllowLocalNetworkLoopback). The left pane shows the evaluated value of the include directory property. The bottom pane shows which macros were expanded, if any, to produce the include directory property value. Because the Include Directories macro is a combination of two other macros, $(VC_IncludePath) and $(WindowsSDK_IncludePath), the bottom pane, labeled Inherited values, lists those two macros. +:::image-end::: ## List of common macros -This table describes a commonly used subset of the available macros; there are many more not listed here. Go to the **Macros** dialog to see all of the properties and their current values in your project. For details on how MSBuild property definitions are created and used as macros in .props, .targets, and .vcxproj files, see [MSBuild Properties](/visualstudio/msbuild/msbuild-properties). - -|Macro|Description| -|-----------|-----------------| -|**$(Configuration)**|The name of the current project configuration, for example, "Debug".| -|**$(DevEnvDir)**|The installation directory of Visual Studio (defined as drive + path); includes the trailing backslash '\\'.| -|**$(FrameworkDir)**|The directory into which the .NET Framework was installed.| -|**$(FrameworkSDKDir)**|The directory into which you installed the .NET Framework. The .NET Framework could have been installed as part of Visual Studio or separately.| -|**$(FrameworkVersion)**|The version of the .NET Framework used by Visual Studio. Combined with **$(FrameworkDir)**, the full path to the version of the .NET Framework use by Visual Studio.| -|**$(FxCopDir)**|The path to the fxcop.cmd file. The fxcop.cmd file is not installed with all Visual Studio editions.| -|**$(IntDir)**|Path to the directory specified for intermediate files. If it's a relative path, intermediate files go to this path appended to the project directory. This path should have a trailing slash. It resolves to the value for the **Intermediate Directory** property. Don't use **$(OutDir)** to define this property.| -|**$(OutDir)**|Path to the output file directory. If it's a relative path, output files go to this path appended to the project directory. This path should have a trailing slash. It resolves to the value for the **Output Directory** property. Don't use **$(IntDir)** to define this property.| -|**$(Platform)**|The name of current project platform, for example, "Win32".| -|**$(PlatformShortName)**|The short name of current architecture, for example, "x86" or "x64".| -|**$(ProjectDir)**|The directory of the project (defined as drive + path); includes the trailing backslash '\\'.| -|**$(ProjectExt)**|The file extension of the project. It includes the '.' before the file extension.| -|**$(ProjectFileName)**|The file name of the project (defined as base name + file extension).| -|**$(ProjectName)**|The base name of the project.| -|**$(ProjectPath)**|The absolute path name of the project (defined as drive + path + base name + file extension).| -|**$(PublishDir)**|The output location for the publish target; includes the trailing backslash '\\'. Defaults to the **$(OutDir)app.publish\\** folder.| -|**$(RemoteMachine)**|Set to the value of the **Remote Machine** property on the Debug property page. See [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration) for more information.| -|**$(RootNameSpace)**|The namespace, if any, containing the application.| -|**$(SolutionDir)**|The directory of the solution (defined as drive + path); includes the trailing backslash '\\'. Defined only when building a solution in the IDE.| -|**$(SolutionExt)**|The file extension of the solution. It includes the '.' before the file extension. Defined only when building a solution in the IDE.| -|**$(SolutionFileName)**|The file name of the solution (defined as base name + file extension). Defined only when building a solution in the IDE.| -|**$(SolutionName)**|The base name of the solution. Defined only when building a solution in the IDE.| -|**$(SolutionPath)**|The absolute path name of the solution (defined as drive + path + base name + file extension). Defined only when building a solution in the IDE.| -|**$(TargetDir)**|The directory of the primary output file for the build (defined as drive + path); includes the trailing backslash '\\'.| -|**$(TargetExt)**|The file extension of the primary output file for the build. It includes the '.' before the file extension.| -|**$(TargetFileName)**|The file name of the primary output file for the build (defined as base name + file extension).| -|**$(TargetName)**|The base name of the primary output file for the build.| -|**$(TargetPath)**|The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension).| -|**$(VCInstallDir)**|The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **$(VCInstallDir)** contains the path to the Visual Studio 2015 installation.| -|**$(VSInstallDir)**|The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **$(VSInstallDir)** contains the path to the Visual Studio 2012 installation.| -|**$(WebDeployPath)**|The relative path from the web deployment root to where the project outputs belong.| -|**$(WebDeployRoot)**|The absolute path to the location of **\**. For example, c:\inetpub\wwwroot.| +This table describes a commonly used subset of the available macros; there are many more not listed here. Go to the **Macros** dialog to see all of the properties and their current values in your project. For details on how MSBuild property definitions are created and used as macros in *`.props`*, *`.targets`*, and *`.vcxproj`* files, see [MSBuild Properties](/visualstudio/msbuild/msbuild-properties). + +| Macro | Description | +|--|--| +| **`$(Configuration)`** | The name of the current project configuration, for example, "Debug". | +| **`$(DevEnvDir)`** | The installation directory of Visual Studio (defined as drive + path); includes the trailing backslash (\\). | +| **`$(FrameworkDir)`** | The directory into which the .NET Framework was installed. | +| **`$(FrameworkSDKDir)`** | The directory into which you installed the .NET Framework. The .NET Framework may have been installed as part of Visual Studio or separately. | +| **`$(FrameworkVersion)`** | The version of the .NET Framework used by Visual Studio. Combined with **`$(FrameworkDir)`**, the full path to the version of the .NET Framework use by Visual Studio. | +| **`$(FxCopDir)`** | The path to the *`fxcop.cmd`* file. The *`fxcop.cmd`* file isn't installed in all Visual Studio editions. | +| **`$(IntDir)`** | Path to the directory specified for intermediate files. If it's a relative path, intermediate files go to this path appended to the project directory. This path should have a trailing backslash (\\). It resolves to the value for the **Intermediate Directory** property. Don't use **`$(OutDir)`** to define this property. | +| **`$(OutDir)`** | Path to the output file directory. If it's a relative path, output files go to this path appended to the project directory. This path should have a trailing backslash (\\). It resolves to the value for the **Output Directory** property. Don't use **`$(IntDir)`** to define this property. | +| **`$(Platform)`** | The name of current project platform, for example, "Win32". | +| **`$(PlatformShortName)`** | The short name of current architecture, for example, "x86" or "x64". | +| **`$(ProjectDir)`** | The directory of the project (defined as drive + path); includes the trailing backslash (\\). | +| **`$(ProjectExt)`** | The file extension of the project. It includes the '.' before the file extension. | +| **`$(ProjectFileName)`** | The file name of the project (defined as base name + file extension). | +| **`$(ProjectName)`** | The base name of the project. | +| **`$(ProjectPath)`** | The absolute path name of the project (defined as drive + path + base name + file extension). | +| **`$(PublishDir)`** | The output location for the publish target; includes the trailing backslash (\\). Defaults to the **`$(OutDir)app.publish\`** folder. | +| **`$(RemoteMachine)`** | Set to the value of the **Remote Machine** property on the Debug property page. For more information, see [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration). | +| **`$(RootNameSpace)`** | The namespace, if any, containing the application. | +| **`$(SolutionDir)`** | The directory of the solution (defined as drive + path); includes the trailing backslash (\\). Defined only when building a solution in the IDE. | +| **`$(SolutionExt)`** | The file extension of the solution. It includes the '.' before the file extension. Defined only when building a solution in the IDE. | +| **`$(SolutionFileName)`** | The file name of the solution (defined as base name + file extension). Defined only when building a solution in the IDE. | +| **`$(SolutionName)`** | The base name of the solution. Defined only when building a solution in the IDE. | +| **`$(SolutionPath)`** | The absolute path name of the solution (defined as drive + path + base name + file extension). Defined only when building a solution in the IDE. | +| **`$(TargetDir)`** | The directory of the primary output file for the build (defined as drive + path); includes the trailing backslash (\\). | +| **`$(TargetExt)`** | The file extension of the primary output file for the build. It includes the '.' before the file extension. | +| **`$(TargetFileName)`** | The file name of the primary output file for the build (defined as base name + file extension). | +| **`$(TargetName)`** | The base name of the primary output file for the build. | +| **`$(TargetPath)`** | The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension). | +| **`$(VCInstallDir)`** | The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **`$(VCInstallDir)`** contains the path to the Visual Studio 2015 installation. | +| **`$(VSInstallDir)`** | The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **`$(VSInstallDir)`** contains the path to the Visual Studio 2012 installation. | +| **`$(WebDeployPath)`** | The relative path from the web deployment root to where the project outputs belong. | +| **`$(WebDeployRoot)`** | The absolute path to the location of **``**. For example, *`c:\inetpub\wwwroot`*. | ## Obsolete macros -The build system for C++ was significantly changed between Visual Studio 2008 and Visual Studio 2010. Many macros used in earlier project types have been changed to new ones. These macros are no longer used or have been replaced by one or more equivalent properties or [item metadata macro](/visualstudio/msbuild/itemmetadata-element-msbuild) (**%(**_name_**)**) values. Macros that are marked "migrated" can be updated by the project migration tool. If the project that contains the macro is migrated from Visual Studio 2008 or earlier to Visual Studio 2010, Visual Studio converts the macro to the equivalent current macro. Later versions of Visual Studio can't convert projects from Visual Studio 2008 and earlier to the new project type. You must convert these projects in two steps; first convert them to Visual Studio 2010, and then convert the result to your newer version of Visual Studio. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md). +The build system for C++ was changed significantly between Visual Studio 2008 and Visual Studio 2010. Many macros used in earlier project types changed to new ones. These macros are no longer used or are replaced by one or more equivalent properties or [item metadata macro](/visualstudio/msbuild/itemmetadata-element-msbuild) (**`%(item-name)`**) values. The migration tool can update macros marked "migrated". If a project containing the macro is migrated from Visual Studio 2008 or earlier to Visual Studio 2010, Visual Studio converts the macro to the equivalent current macro. Later versions of Visual Studio can't convert projects from Visual Studio 2008 and earlier to the new project type. You must convert these projects in two steps; first convert them to Visual Studio 2010, and then convert the result to your newer version of Visual Studio. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md). -|Macro|Description| -|-----------|-----------------| -|**$(InputDir)**|(Migrated.) The directory of the input file (defined as drive + path); includes the trailing backslash '\\'. If the project is the input, then this macro is equivalent to **$(ProjectDir)**.| -|**$(InputExt)**|(Migrated.) The file extension of the input file. It includes the '.' before the file extension. If the project is the input, then this macro is equivalent to **$(ProjectExt)**. For source files, this is **%(Extension)**.| -|**$(InputFileName)**|(Migrated.) The file name of the input file (defined as base name + file extension). If the project is the input, then this macro is equivalent to **$(ProjectFileName)**. For source files, this is **%(Identity)**.| -|**$(InputName)**|(Migrated.) The base name of the input file. If the project is the input, then this macro is equivalent to **$(ProjectName)**. For source files, this is **%(Filename)**.| -|**$(InputPath)**|(Migrated.) The absolute path name of the input file (defined as drive + path + base name + file extension). If the project is the input, then this macro is equivalent to **$(ProjectPath)**. For source files, this is **%(FullPath)**.| -|**$(ParentName)**|Name of the item containing this project item. This will be the parent folder name, or project name.| -|**$(SafeInputName)**|The name of the file as a valid class name, minus file extension. This property does not have an exact equivalent.| -|**$(SafeParentName)**|The name of the immediate parent in valid name format. For example, a form is the parent of a .resx file. This property does not have an exact equivalent.| -|**$(SafeRootNamespace)**|The namespace name in which the project wizards will add code. This namespace name will only contain characters that would be permitted in a valid C++ identifier. This property does not have an exact equivalent.| +| Macro | Description | +|--|--| +| **`$(InputDir)`** | (Migrated.) The directory of the input file (defined as drive + path); includes the trailing backslash (\\). If the project is the input, then this macro is equivalent to **`$(ProjectDir)`**. | +| **`$(InputExt)`** | (Migrated.) The file extension of the input file. It includes the '.' before the file extension. If the project is the input, then this macro is equivalent to **`$(ProjectExt)`**. For source files, it's equivalent to **`%(Extension)`**. | +| **`$(InputFileName)`** | (Migrated.) The file name of the input file (defined as base name + file extension). If the project is the input, then this macro is equivalent to **`$(ProjectFileName)`**. For source files, it's equivalent to **`%(Identity)`**. | +| **`$(InputName)`** | (Migrated.) The base name of the input file. If the project is the input, then this macro is equivalent to **`$(ProjectName)`**. For source files, it's equivalent to **`%(Filename)`**. | +| **`$(InputPath)`** | (Migrated.) The absolute path name of the input file (defined as drive + path + base name + file extension). If the project is the input, then this macro is equivalent to **`$(ProjectPath)`**. For source files, it's equivalent to **`%(FullPath)`**. | +| **`$(ParentName)`** | Name of the item containing this project item. This macro is the parent folder name, or project name. | +| **`$(SafeInputName)`** | The name of the file as a valid class name, minus file extension. This property doesn't have an exact equivalent. | +| **`$(SafeParentName)`** | The name of the immediate parent in valid name format. For example, a form is the parent of a *`.resx`* file. This property doesn't have an exact equivalent. | +| **`$(SafeRootNamespace)`** | The namespace name where the project wizards should add code. This namespace name only contains characters that would be permitted in a valid C++ identifier. This property doesn't have an exact equivalent. | ## See also [Visual Studio Projects - C++](../creating-and-managing-visual-cpp-projects.md)\ [Visual C++ porting and upgrading guide](../../porting/visual-cpp-porting-and-upgrading-guide.md)\ -[Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md) +[Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md)\ +[MSBuild well-known item metadata](/visualstudio/msbuild/msbuild-well-known-item-metadata) diff --git a/docs/build/reference/compiler-command-line-syntax.md b/docs/build/reference/compiler-command-line-syntax.md index 8cea8f4ff5..0f56baaed5 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -17,10 +17,10 @@ The following table describes input to the CL command. |Entry|Meaning| |-----------|-------------| -|*option*|One or more [CL options](compiler-options.md). Note that all options apply to all specified source files. Options are specified by either a forward slash (/) or a dash (-). If an option takes an argument, the option's description documents whether a space is allowed between the option and the arguments. Option names (except for the /HELP option) are case sensitive. See [Order of CL Options](order-of-cl-options.md) for more information.| -|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. See [CL Filename Syntax](cl-filename-syntax.md) for more information.| +|*option*|One or more [CL options](compiler-options.md). All options apply to all specified source files. Specify options using either a forward slash (/) or a dash (-). Generally, there can't be a space between the option and argument. The option's description states when a space is allowed. Options are case-sensitive--except for `/HELP`. For more information, see [Order of CL Options](order-of-cl-options.md).| +|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. For more information, see [CL Filename Syntax](cl-filename-syntax.md).| |*lib*|One or more library names. CL passes these names to the linker.| -|*command-file*|A file that contains multiple options and filenames. See [CL Command Files](cl-command-files.md) for more information.| +|*command-file*|A file that contains multiple options and filenames. For more information, see [CL Command Files](cl-command-files.md).| |*link-opt*|One or more [MSVC Linker Options](linker-options.md). CL passes these options to the linker.| You can specify any number of options, filenames, and library names, as long as the number of characters on the command line does not exceed 1024, the limit dictated by the operating system. diff --git a/docs/build/reference/compiler-option-warning-level.md b/docs/build/reference/compiler-option-warning-level.md index 4b89c26f11..251396f31f 100644 --- a/docs/build/reference/compiler-option-warning-level.md +++ b/docs/build/reference/compiler-option-warning-level.md @@ -1,8 +1,8 @@ --- title: "/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level)" description: "Reference for the Microsoft C/C++ compiler options: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, and /WX." -ms.date: "01/31/2020" -f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "VC.Project.VCCLCompilerTool.WarningVersion", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] helpviewer_keywords: ["/W1 compiler option [C++]", "w compiler option [C++]", "-wo compiler option [C++]", "Warning Level compiler option", "W1 compiler option [C++]", "-we compiler option [C++]", "/WX compiler option [C++]", "-wd compiler option [C++]", "WX compiler option [C++]", "wo compiler option [C++]", "Wall compiler option [C++]", "/w compiler option", "W2 compiler option [C++]", "-W2 compiler option [C++]", "wd compiler option [C++]", "/we compiler option [C++]", "we compiler option [C++]", "-W1 compiler option [C++]", "-W4 compiler option [C++]", "-Wall compiler option [C++]", "/Wall compiler option [C++]", "-W0 compiler option [C++]", "W0 compiler option [C++]", "-WX compiler option [C++]", "/wo compiler option [C++]", "W4 compiler option [C++]", "W3 compiler option [C++]", "/wd compiler option [C++]", "warnings, as errors compiler option", "/W3 compiler option [C++]", "/W0 compiler option [C++]", "/W4 compiler option [C++]", "-W3 compiler option [C++]", "-w compiler option [C++]", "/W2 compiler option [C++]", "/Wv compiler option [C++]"] --- # /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level) diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index 8a8a2ff7bc..686023b214 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/docs/build/reference/compiler-options-listed-alphabetically.md @@ -1,7 +1,7 @@ --- title: "Compiler options listed alphabetically" description: "Reference listing in alphabetical order of the Microsoft C/C++ compiler command-line options." -ms.date: 12/15/2021 +ms.date: 2/5/2025 helpviewer_keywords: ["compiler options, C++"] --- # Compiler options listed alphabetically @@ -16,7 +16,8 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/?`](help-compiler-command-line-help.md) | Lists the compiler options. | | [`/AI`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | | [`/analyze`](analyze-code-analysis.md) | Enables code analysis. | -| [`/arch:`](arch-x86.md) | Minimum CPU architecture requirements. IA32, SSE, and SSE2 are x86 only. | +| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. | +| `/arm64EC` | Generate code compatible with the arm64EC ABI. | | [`/await`](await-enable-coroutine-support.md) | Enable coroutines (resumable functions) extensions. | | [`/await:strict`](await-enable-coroutine-support.md) | Enable standard C++20 coroutine support with earlier language versions. | | [`/bigobj`](bigobj-increase-number-of-sections-in-dot-obj-file.md) | Increases the number of addressable sections in an .obj file. | @@ -36,6 +37,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/constexpr:depth`](constexpr-control-constexpr-evaluation.md) | Recursion depth limit for `constexpr` evaluation (default: 512). | | [`/constexpr:steps`](constexpr-control-constexpr-evaluation.md) | Terminate `constexpr` evaluation after N steps (default: 100000) | | [`/D{=|#}`](d-preprocessor-definitions.md) | Defines constants and macros. | +| [`/dynamicdeopt`](dynamic-deopt.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) and step in anywhere with on-demand function deoptimization. | | [`/diagnostics`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column information. | | [`/diagnostics:caret[-]`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column and the indicated line of source. | | [`/diagnostics:classic`](diagnostics-compiler-diagnostic-options.md) | Use legacy diagnostics format. | @@ -46,8 +48,9 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. | | [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). | | [`/EP`](ep-preprocess-to-stdout-without-hash-line-directives.md) | Copies preprocessor output to standard output. | -| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control error reporting. | | [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set execution character set. | +| [`/experimental:log`](experimental-log.md) | Enables experimental structured SARIF output. | | [`/experimental:module`](experimental-module.md) | Enables experimental module support. | | [`/exportHeader`](module-exportheader.md) | Create the header units files (*`.ifc`*) specified by the input arguments. | | [`/external:anglebrackets`](external-external-headers-diagnostics.md) | Treat all headers included via `<>` as external. | @@ -63,6 +66,8 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. | | [`/Fd`](fd-program-database-file-name.md) | Renames program database file. | | [`/Fe`](fe-name-exe-file.md) | Renames the executable file. | +| [`/feature`](feature-arm64.md) | Enable architecture features.17.10 | +| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.17.14 | | [`/FI`](fi-name-forced-include-file.md) | Preprocesses the specified include file. | | [`/Fi`](fi-preprocess-output-file-name.md) | Specifies the preprocessed output file name. | | [`/Fm`](fm-name-mapfile.md) | Creates a mapfile. | @@ -80,7 +85,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. | | [`/fsanitize-coverage`](fsanitize-coverage.md) | Enables compilation of code coverage instrumentation for libraries such as LibFuzzer. | | `/Ft` | Location of the header files generated for `#import`. | -| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it had been passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it were passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | | [`/Fx`](fx-merge-injected-code.md) | Merges injected code with the source file. | | [`/GA`](ga-optimize-for-windows-application.md) | Optimizes for Windows applications. | | [`/Gd`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__cdecl`** calling convention. (x86 only) | @@ -111,9 +116,13 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/homeparams`](homeparams-copy-register-parameters-to-stack.md) | Forces parameters passed in registers to be written to their locations on the stack upon function entry. This compiler option is only for the x64 compilers (native and cross compile). | | [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hotpatchable image. | | [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | +| [`/ifcOutput`](ifc-output.md) | Specify output file name or directory for built *`.ifc`* files. | +| [`/interface`](interface.md) | Treat the input file as a module interface unit. | +| [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. | +| [`/jumptablerdata`](jump-table-rdata.md) | Put switch case statement jump tables in the `.rdata` section. | | [`/JMC`](jmc.md) | Supports native C++ Just My Code debugging. | -| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker will create a binary that can be executed in the Windows kernel. | +| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker create a binary that can be executed in the Windows kernel. | | [`/LD`](md-mt-ld-use-run-time-library.md) | Creates a dynamic-link library. | | [`/LDd`](md-mt-ld-use-run-time-library.md) | Creates a debug dynamic-link library. | | [`/link`](link-pass-options-to-linker.md) | Passes the specified option to LINK. | @@ -159,7 +168,8 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/RTCc`](rtc-run-time-error-checks.md) | Convert to smaller type checks at run-time. | | [`/RTCs`](rtc-run-time-error-checks.md) | Enable stack frame runtime checks. | | [`/RTCu`](rtc-run-time-error-checks.md) | Enables uninitialized local usage checks. | -| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable additional security features and warnings. | +| [`/scanDependencies`](scandependencies.md) | List module dependencies in C++ Standard JSON form. | +| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable more security features and warnings. | | [`/showIncludes`](showincludes-list-include-files.md) | Displays a list of all include files during compilation. | | [`/source-charset`](source-charset-set-source-character-set.md) | Set source character set. | | [`/sourceDependencies`](sourcedependencies.md) | List all source-level dependencies. | @@ -170,6 +180,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/std:c++latest`](std-specify-language-standard-version.md) | The latest draft C++ standard preview features. | | [`/std:c11`](std-specify-language-standard-version.md) | C11 standard ISO/IEC 9899:2011. | | [`/std:c17`](std-specify-language-standard-version.md) | C17 standard ISO/IEC 9899:2018. | +| [`/std:clatest`](std-specify-language-standard-version.md) | The latest draft C standard preview features. | | [`/TC`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C. | | [`/Tc`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C source file. | | [`/TP`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C++. | @@ -181,6 +192,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/V`](v-version-number.md) | Deprecated. Sets the version string. | | [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. | | [`/vd{0|1|2}`](vd-disable-construction-displacements.md) | Suppresses or enables hidden `vtordisp` class members. | +| [`/vlen`](vlen.md) | Specifies vector length. | | [`/vmb`](vmb-vmg-representation-method.md) | Uses best base for pointers to members. | | [`/vmg`](vmb-vmg-representation-method.md) | Uses full generality for pointers to members. | | [`/vmm`](vmm-vms-vmv-general-purpose-representation.md) | Declares multiple inheritance. | @@ -188,7 +200,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. | | [`/volatile:iso`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics not guaranteed on volatile accesses. | | [`/volatile:ms`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics guaranteed on volatile accesses. | -| `/volatileMetadata` | Generate metadata on volatile memory accesses. | +| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. | | [`/w`](compiler-option-warning-level.md) | Disable all warnings. | | [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Set output warning level. | | [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Set warning level for the specified warning. | @@ -208,30 +220,35 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | | [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | | [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | | [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | | [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | | [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction (off by default). | | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | | [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | -| `/Zc:tlsGuards[-]` | Generate runtime checks for TLS variable initialization (on by default). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | | [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | | [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | -| `/Zc:zeroSizeArrayNew[-]` | Call member `new`/`delete` for 0-size arrays of objects (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for zero-size arrays of objects (on by default). | | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | | [`/ZH:[MD5|SHA1|SHA_256]`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | @@ -240,10 +257,13 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/Zl`](zl-omit-default-library-name.md) | Removes the default library name from the *`.obj`* file. | | [`/Zm`](zm-specify-precompiled-header-memory-allocation-limit.md) | Specifies the precompiled header memory allocation limit. | | [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | -| [`/Zp[n]`](zp-struct-member-alignment.md) *n* | Packs structure members. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | +17.10 This option is available starting in Visual Studio 2022 version 17.10.\ +17.14 This option is available starting in Visual Studio 2022 version 17.14. + ## See also [MSVC compiler options](compiler-options.md)\ diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md index 2a4c903bd4..2fbfbc1357 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/docs/build/reference/compiler-options-listed-by-category.md @@ -1,9 +1,8 @@ --- title: "Compiler Options Listed by Category" description: "Reference listing by category of the Microsoft C/C++ compiler command-line options." -ms.date: 12/15/2021 +ms.date: 2/5/2025 helpviewer_keywords: ["compiler options, C++"] -ms.assetid: c4750dcf-dba0-4229-99b6-45cdecc11729 --- # Compiler options listed by category @@ -13,6 +12,7 @@ This article contains a categorical list of compiler options. For an alphabetica | Option | Purpose | |--|--| +| [`/dynamicdeopt`](dynamic-deopt.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) to debug optimized code as if it had been compiled deoptimized. | | [`/favor:`](favor-optimize-for-architecture-specifics.md) | Produces code that is optimized for a specified architecture, or for a range of architectures. | | [`/O1`](o1-o2-minimize-size-maximize-speed.md) | Creates small code. | | [`/O2`](o1-o2-minimize-size-maximize-speed.md) | Creates fast code. | @@ -29,7 +29,7 @@ This article contains a categorical list of compiler options. For an alphabetica | Option | Purpose | |--|--| -| [`/arch:`](arch-x86.md) | Minimum CPU architecture requirements. IA32, SSE, and SSE2 are x86 only. | +| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. | | [`/clr`](clr-common-language-runtime-compilation.md) | Produces an output file to run on the common language runtime. | | [`/clr:implicitKeepAlive-`](clr-common-language-runtime-compilation.md) | Turn off implicit emission of `System::GC::KeepAlive(this)`. | | [`/clr:initialAppDomain`](clr-common-language-runtime-compilation.md) | Enable initial AppDomain behavior of Visual C++ 2002. | @@ -43,6 +43,8 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/EHc`](eh-exception-handling-model.md) | `extern "C"` defaults to `nothrow`. | | [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. | | [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). | +| [`/feature`](feature-arm64.md) | Enable architecture features.17.10 | +| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.17.14 | | [`/fp:contract`](fp-specify-floating-point-behavior.md) | Consider floating-point contractions when generating code. | | [`/fp:except[-]`](fp-specify-floating-point-behavior.md) | Consider floating-point exceptions when generating code. | | [`/fp:fast`](fp-specify-floating-point-behavior.md) | "fast" floating-point model; results are less predictable. | @@ -76,6 +78,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/GZ`](gz-enable-stack-frame-run-time-error-checking.md) | Deprecated. Enables fast checks. (Same as [`/RTC1`](rtc-run-time-error-checks.md)) | | [`/homeparams`](homeparams-copy-register-parameters-to-stack.md) | Forces parameters passed in registers to be written to their locations on the stack upon function entry. This compiler option is only for the x64 compilers (native and cross compile). | | [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hotpatchable image. | +| [`/jumptablerdata`](jump-table-rdata.md) | Put switch case statement jump tables in the `.rdata` section. | | [`/Qfast_transcendentals`](qfast-transcendentals-force-fast-transcendentals.md) | Generates fast transcendentals. | | [`/QIfist`](qifist-suppress-ftol.md) | Deprecated. Suppresses the call of the helper function `_ftol` when a conversion from a floating-point type to an integral type is required. (x86 only) | | [`/Qimprecise_fwaits`](qimprecise-fwaits-remove-fwaits-inside-try-blocks.md) | Removes `fwait` commands inside **`try`** blocks. | @@ -91,6 +94,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/RTCc`](rtc-run-time-error-checks.md) | Convert to smaller type checks at run-time. | | [`/RTCs`](rtc-run-time-error-checks.md) | Enable stack frame runtime checks. | | [`/RTCu`](rtc-run-time-error-checks.md) | Enables uninitialized local usage checks. | +| [`/vlen`](vlen.md) | Specifies vector length. | | [`/volatile:iso`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics not guaranteed on volatile accesses. | | [`/volatile:ms`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics guaranteed on volatile accesses. | @@ -130,14 +134,18 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/u`](u-u-undefine-symbols.md) | Removes all predefined macros. | | [`/X`](x-ignore-standard-include-paths.md) | Ignores the standard include directory. | -## Header units +## Header units/modules | Option | Purpose | |--|--| | [`/exportHeader`](module-exportheader.md) | Create the header units files (*`.ifc`*) specified by the input arguments. | -| [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (`.ifc`) for the specified header. | +| [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (*`.ifc`*) for the specified header. | | [`/headerName`](headername.md) | Build a header unit from the specified header. | +| [`/ifcOutput`](ifc-output.md) | Specify the output file name or directory for built *`.ifc`* files. | +| [`/interface`](interface.md) | Treat the input file as a module interface unit. | +| [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/reference`](module-reference.md) | Use named module IFC. | +| [`/scanDependencies`](scandependencies.md) | List module and header unit dependencies in C++ Standard JSON form. | | [`/sourceDependencies`](sourcedependencies.md) | List all source-level dependencies. | | [`/sourceDependencies:directives`](sourcedependencies-directives.md) | List module and header unit dependencies. | | [`/translateInclude`](translateinclude.md) | Treat `#include` as `import`. | @@ -161,6 +169,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/std:c++latest`](std-specify-language-standard-version.md) | The latest draft C++ standard preview features. | | [`/std:c11`](std-specify-language-standard-version.md) | C11 standard ISO/IEC 9899:2011. | | [`/std:c17`](std-specify-language-standard-version.md) | C17 standard ISO/IEC 9899:2018. | +| [`/std:clatest`](std-specify-language-standard-version.md) | The latest draft C standard preview features. | | [`/vd{0|1|2}`](vd-disable-construction-displacements.md) | Suppresses or enables hidden `vtordisp` class members. | | [`/vmb`](vmb-vmg-representation-method.md) | Uses best base for pointers to members. | | [`/vmg`](vmb-vmg-representation-method.md) | Uses full generality for pointers to members. | @@ -169,39 +178,44 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. | | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | | [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | | [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | | [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | | [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | -| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for inferred `enum` base types (Off b y default, not implied by **`/permissive-`**). | | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | | [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | | [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| `/Zc:tlsGuards[-]` | Generate runtime checks for TLS variable initialization (on by default). | -| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | | [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | -| `/Zc:zeroSizeArrayNew[-]` | Call member `new`/`delete` for 0-size arrays of objects (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects (on by default). | | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | -| [`/ZH:[MD5|SHA1|SHA_256]`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | +| [`/ZH`:[MD5|SHA1|SHA_256]](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | | [`/ZI`](z7-zi-zi-debug-information-format.md) | Includes debug information in a program database compatible with Edit and Continue. (x86 only) | | [`/Zi`](z7-zi-zi-debug-information-format.md) | Generates complete debugging information. | | [`/Zl`](zl-omit-default-library-name.md) | Removes the default library name from the *`.obj`* file. | | [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | -| [`/Zp[n]`](zp-struct-member-alignment.md) *n* | Packs structure members. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | @@ -229,7 +243,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/bigobj`](bigobj-increase-number-of-sections-in-dot-obj-file.md) | Increases the number of addressable sections in an .obj file. | | [`/c`](c-compile-without-linking.md) | Compiles without linking. | | [`/cgthreads`](cgthreads-code-generation-threads.md) | Specifies number of *cl.exe* threads to use for optimization and code generation. | -| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control error reporting. | | [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set execution character set. | | `/fastfail` | Enable fast-fail mode. | | [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. | @@ -238,7 +252,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/HELP`](help-compiler-command-line-help.md) | Lists the compiler options. | | [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. | | [`/JMC`](jmc.md) | Supports native C++ Just My Code debugging. | -| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker will create a binary that can be executed in the Windows kernel. | +| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker create a binary that can be executed in the Windows kernel. | | [`/MP`](mp-build-with-multiple-processes.md) | Builds multiple source files concurrently. | | [`/nologo`](nologo-suppress-startup-banner-c-cpp.md) | Suppresses display of sign-on banner. | | `/presetPadding` | Zero initialize padding for stack based class types. | @@ -251,7 +265,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/utf-8`](utf-8-set-source-and-executable-character-sets-to-utf-8.md) | Set source and execution character sets to UTF-8. | | [`/V`](v-version-number.md) | Deprecated. Sets the version string. | | [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. | -| `/volatileMetadata` | Generate metadata on volatile memory accesses. | +| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. | | [`/Yc`](yc-create-precompiled-header-file.md) | Create *`.PCH`* file. | | [`/Yd`](yd-place-debug-information-in-object-file.md) | Deprecated. Places complete debugging information in all object files. Use [`/Zi`](z7-zi-zi-debug-information-format.md) instead. | | [`/Yl`](yl-inject-pch-reference-for-debug-library.md) | Injects a PCH reference when creating a debug library. | @@ -272,7 +286,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/external:templates[-]`](external-external-headers-diagnostics.md) | Evaluate warning level across template instantiation chain. | | [`/external:W`](external-external-headers-diagnostics.md) | Set warning level for external headers. | | [`/options:strict`](options-strict.md) | Unrecognized compiler options are errors. | -| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable additional security features and warnings. | +| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable more security features and warnings. | | [`/w`](compiler-option-warning-level.md) | Disable all warnings. | | [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Set output warning level. | | [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Set warning level for the specified warning. | @@ -290,6 +304,7 @@ Experimental options may only be supported by certain versions of the compiler. | Option | Purpose | |--|--| +| [`/experimental:log`](experimental-log.md) | Enables experimental structured SARIF output. | | [`/experimental:module`](experimental-module.md) | Enables experimental module support. | ## Deprecated and removed compiler options @@ -314,6 +329,9 @@ Experimental options may only be supported by certain versions of the compiler. | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables language extensions. | | [`/Zg`](zg-generate-function-prototypes.md) | Removed in Visual Studio 2015. Generates function prototypes. | +17.10 This option is available starting in Visual Studio 2022 version 17.10.\ +17.14 This option is available starting in Visual Studio 2022 version 17.14. + ## See also [C/C++ building reference](c-cpp-building-reference.md)\ diff --git a/docs/build/reference/compiling-a-c-cpp-program.md b/docs/build/reference/compiling-a-c-cpp-program.md index 5bb1e6e938..04b7733c86 100644 --- a/docs/build/reference/compiling-a-c-cpp-program.md +++ b/docs/build/reference/compiling-a-c-cpp-program.md @@ -11,7 +11,7 @@ C and C++ compiler options can be set either in the Visual Studio IDE or on the ## In Visual Studio -You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. See [MSVC Compiler Options](compiler-options.md) for a complete list. +You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. For more information and a complete list of options, see [MSVC compiler options](compiler-options.md). ## From the command line diff --git a/docs/build/reference/constexpr-control-constexpr-evaluation.md b/docs/build/reference/constexpr-control-constexpr-evaluation.md index 6bee6fa00a..9052345e64 100644 --- a/docs/build/reference/constexpr-control-constexpr-evaluation.md +++ b/docs/build/reference/constexpr-control-constexpr-evaluation.md @@ -1,45 +1,42 @@ --- description: "Learn more about: /constexpr (Control constexpr evaluation)" title: "/constexpr (Control constexpr evaluation)" -ms.date: "08/15/2017" +ms.date: 04/14/2025 f1_keywords: ["/constexpr", "-constexpr"] helpviewer_keywords: ["/constexpr control constexpr evaluation [C++]", "-constexpr control constexpr evaluation [C++]", "constexpr control constexpr evaluation [C++]"] -ms.assetid: 76d56784-f5ad-401d-841d-09d1059e8b8c --- # /constexpr (Control constexpr evaluation) -Use the **/constexpr** compiler options to control parameters for **`constexpr`** evaluation at compile time. +Use the **`/constexpr`** compiler options to control parameters for **`constexpr`** evaluation at compile time. ## Syntax -> **/constexpr:depth**N\ -> **/constexpr:backtrace**N\ -> **/constexpr:steps**N +> `/constexpr:depth`N\ +> `/constexpr:backtrace`N\ +> `/constexpr:steps`N ## Arguments -**depth**N +**`depth`**N\ Limit the depth of recursive **`constexpr`** function invocation to *N* levels. The default is 512. -**backtrace**N +**`backtrace`**N\ Show up to *N* **`constexpr`** evaluations in diagnostics. The default is 10. -**steps**N -Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000. +**`steps`**N\ +Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000. A step refers to an individual computation taken towards evaluating the constant expression. Increasing the maximum number of steps might cause compilation to take longer in cases where compilation would otherwise fail. ## Remarks -The **/constexpr** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [constexpr (C++)](../../cpp/constexpr-cpp.md). +The **`/constexpr`** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [`constexpr` (C++)](../../cpp/constexpr-cpp.md). -The **/constexpr** options are available beginning in Visual Studio 2015. +The **`/constexpr`** flag is available beginning in Visual Studio 2015. ### To set this compiler option in the Visual Studio development environment 1. Open your project's **Property Pages** dialog box. - 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. - -1. Enter any **/constexpr** compiler options in the **Additional Options** box. Choose **OK** or **Apply** to save your changes. +1. Enter **/constexpr** compiler options in the **Additional Options** box. Choose **OK** to save your changes. ### To set this compiler option programmatically @@ -47,5 +44,5 @@ The **/constexpr** options are available beginning in Visual Studio 2015. ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/contents-of-a-makefile.md b/docs/build/reference/contents-of-a-makefile.md index 943a29c916..8883cd8cc7 100644 --- a/docs/build/reference/contents-of-a-makefile.md +++ b/docs/build/reference/contents-of-a-makefile.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: NMAKE makefile contents and features" title: "NMAKE makefile contents and features" +description: "Learn more about: NMAKE makefile contents and features" ms.date: 09/30/2021 helpviewer_keywords: ["makefiles", "makefiles, contents", "NMAKE program, special characters", "makefiles, special characters", "special characters, in NMAKE macros", "macros, special characters", "NMAKE program, long filenames", "makefiles, comments", "NMAKE program, wildcards", "wildcards, expanding"] --- @@ -24,11 +24,11 @@ For a sample, see [Sample makefile](sample-makefile.md). NMAKE supports other features, such as wildcards, long filenames, comments, and escapes for special characters. -## Wildcards and NMAKE +## Wildcards and NMAKE NMAKE expands filename wildcards (**`*`** and **`?`**) in dependency lines. A wildcard specified in a command is passed to the command; NMAKE doesn't expand it. -## Long filenames in a makefile +## Long filenames in a makefile Enclose long filenames in double quotation marks, as follows: @@ -36,7 +36,7 @@ Enclose long filenames in double quotation marks, as follows: all : "VeryLongFileName.exe" ``` -## Comments in a makefile +## Comments in a makefile Precede a comment with a number sign (**`#`**). NMAKE ignores text from the number sign to the next newline character. @@ -66,7 +66,7 @@ To specify a literal number sign, precede it with a caret (**`^`**), as follows: DEF = ^#define #Macro for a C preprocessing directive ``` -## Special characters in a makefile +## Special characters in a makefile To use an NMAKE special character as a literal character, place a caret (**`^`**) in front of it as an escape. NMAKE ignores carets that precede other characters. The special characters are: diff --git a/docs/build/reference/creating-a-makefile-project.md b/docs/build/reference/creating-a-makefile-project.md index 3b351c0c02..1f88156dfd 100644 --- a/docs/build/reference/creating-a-makefile-project.md +++ b/docs/build/reference/creating-a-makefile-project.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Create a makefile project" title: "Create a C++ makefile project in Visual Studio" +description: "Learn more about: Create a makefile project" ms.date: 09/30/2021 f1_keywords: ["vc.appwiz.makefile.project"] helpviewer_keywords: ["Makefile projects [C++]"] @@ -16,7 +16,7 @@ If you have an existing makefile project, you have these choices if you want to - **Visual Studio 2017 and later**: Use the **Open Folder** feature to edit and build a makefile project as-is without any involvement of the MSBuild system. For more information, see [Open Folder projects for C++](../open-folder-projects-cpp.md). - **Visual Studio 2019 and later**: Create a UNIX makefile project for Linux. -## To create a makefile project with the makefile project template +## To create a makefile project with the makefile project template In Visual Studio 2017 and later, the Makefile project template is available when the C++ Desktop Development workload is installed. @@ -50,7 +50,7 @@ The output file that you specify in the project has no effect on the name that t ::: moniker-end -You can view and edit the project's properties in its property page. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md) for information about displaying the property page. +You can view and edit the project's properties in its property page. For more information about displaying the property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). ## Makefile project wizard diff --git a/docs/build/reference/creating-an-dot-sbr-file.md b/docs/build/reference/creating-an-dot-sbr-file.md index 47312c2da9..37096da3b1 100644 --- a/docs/build/reference/creating-an-dot-sbr-file.md +++ b/docs/build/reference/creating-an-dot-sbr-file.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Creating an .Sbr File" title: "Creating an .Sbr File" +description: "Learn more about: Creating an .Sbr File" ms.date: "11/04/2016" helpviewer_keywords: ["SBR files", "BSCMAKE, input files", ".sbr files", "source browser files", "local symbols in browse information", "symbols"] -ms.assetid: bdb4b93c-a88a-441a-84fd-01087d03be25 --- # Creating an .Sbr File @@ -14,7 +13,7 @@ The input files for BSCMAKE are .sbr files. The compiler creates an .sbr file fo To create an .sbr file with all possible information, specify [/FR](fr-fr-create-dot-sbr-file.md). -To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md)`.` +To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md). You can create an .sbr file without performing a full compile. For example, you can specify the /Zs option to the compiler to perform a syntax check and still generate an .sbr file if you specify /FR or /Fr. diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md old mode 100755 new mode 100644 index 7bc0fcc21b..85a515deba --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -1,52 +1,52 @@ --- -description: "Learn more about: /DEBUG (Generate Debug Info)" +description: "Learn more about: /DEBUG (Generate debug info)" title: "/DEBUG (Generate Debug Info)" -ms.date: "05/16/2019" +ms.date: 10/26/2023 f1_keywords: ["VC.Project.VCLinkerTool.GenerateDebugInformation", "/debug"] helpviewer_keywords: ["DEBUG linker option", "/DEBUG linker option", "-DEBUG linker option", "PDB files", "debugging [C++], debug information files", "generate debug info linker option", "pdb files, generating debug info", ".pdb files, generating debug info", "debugging [C++], linker option", "program databases [C++]"] ms.assetid: 1af389ae-3f8b-4d76-a087-1cdf861e9103 --- -# /DEBUG (Generate Debug Info) +# `/DEBUG` (Generate debug info) -``` -/DEBUG[:{FASTLINK|FULL|NONE}] -``` +The **`/DEBUG`** linker option creates a debugging information file for the executable. + +## Syntax + +> **`/DEBUG`**\[**`:`**{**`FASTLINK`**|**`FULL`**|**`NONE`**}] ## Remarks -The **/DEBUG** option creates debugging information for the executable. +The **`/DEBUG`** option puts the debugging information from linked object and library files into a program database (PDB) file. It updates the PDB during subsequent builds of the program. -The linker puts the debugging information into a program database (PDB) file. It updates the PDB during subsequent builds of the program. +An executable (an EXE or DLL file) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension *`.pdb`* to name the program database, and embeds the path where it was created. To override this default, set the [`/PDB`](pdb-use-program-database.md) option and specify a different file name. -An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. +The **`/DEBUG:FASTLINK`** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. You can only use this limited PDB to debug from the computer where the binary and its libraries were built. If you deploy the binary elsewhere, you may debug it remotely from the build computer, but not directly on the test computer. Since Visual Studio 2019, **`/DEBUG:FULL`** linking times have improved significantly, and **`/DEBUG:FASTLINK`** isn't always faster than **`/DEBUG:FULL`**. Since **`/DEBUG:FASTLINK`** no longer provides large build time improvements and results in a slower debugging experience versus **`/DEBUG:FULL`**, this option is no longer recommended. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option leaves private symbol information in the individual compilation products used to build the executable. It generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This option can link from two to four times as fast as full PDB generation, and is recommended when you are debugging locally and have the build products available. This limited PDB can't be used for debugging when the required build products are not available, such as when the executable is deployed on another computer. In a developer command prompt, you can use the mspdbcmf.exe tool to generate a full PDB from this limited PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. +A **`/DEBUG:FASTLINK`** PDB can be converted to a full PDB that you can deploy to a test machine for local debugging. In Visual Studio, use the **Property Pages** dialog as described below to create a full PDB for the project or solution. In a developer command prompt, you can use the `mspdbcmf.exe` tool to create a full PDB. -The **/DEBUG:FULL** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. +The **`/DEBUG:FULL`** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. -The **/DEBUG:NONE** option does not generate a PDB. +The **`/DEBUG:NONE`** option doesn't generate a PDB. -When you specify **/DEBUG** with no additional options, the linker defaults to **/DEBUG:FULL** for command line and makefile builds, for release builds in the Visual Studio IDE, and for both debug and release builds in Visual Studio 2015 and earlier versions. Beginning in Visual Studio 2017, the build system in the IDE defaults to **/DEBUG:FASTLINK** when you specify the **/DEBUG** option for debug builds. Other defaults are unchanged to maintain backward compatibility. +Specifying **`/DEBUG`** with no extra arguments is equivalent to specifying **`/DEBUG:FULL`**. -The compiler's [C7 Compatible](z7-zi-zi-debug-information-format.md) (/Z7) option causes the compiler to leave the debugging information in the .obj files. You can also use the [Program Database](z7-zi-zi-debug-information-format.md) (/Zi) compiler option to store the debugging information in a PDB for the .obj file. The linker looks for the object's PDB first in the absolute path written in the .obj file, and then in the directory that contains the .obj file. You cannot specify an object's PDB file name or location to the linker. +The compiler's [`/Z7`](z7-zi-zi-debug-information-format.md) (C7 Compatible) option causes the compiler to leave the debugging information in the object (OBJ) files. You can also use the [`/Zi`](z7-zi-zi-debug-information-format.md) (Program Database) compiler option to store the debugging information in a PDB for the OBJ file. The linker looks for the object's PDB first in the absolute path written in the OBJ file, and then in the directory that contains the OBJ file. You can't specify an object's PDB file name or location to the linker. -[/INCREMENTAL](incremental-link-incrementally.md) is implied when /DEBUG is specified. +[`/INCREMENTAL`](incremental-link-incrementally.md) is implied when **`/DEBUG`** is specified. -/DEBUG changes the defaults for the [/OPT](opt-optimizations.md) option from REF to NOREF and from ICF to NOICF, so if you want the original defaults, you must explicitly specify /OPT:REF or /OPT:ICF. +**`/DEBUG`** changes the defaults for the [`/OPT`](opt-optimizations.md) option from **`REF`** to **`NOREF`** and from **`ICF`** to **`NOICF`**, so if you want the original defaults, you must explicitly specify **`/OPT:REF`** or **`/OPT:ICF`** after the **`/DEBUG`** option. -It is not possible to create an .exe or .dll that contains debug information. Debug information is always placed in a .obj or .pdb file. +It isn't possible to create an EXE or DLL that contains debug information. Debug information is always placed in an OBJ or PDB file. ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Click the **Linker** folder. - -1. Click the **Debugging** property page. +1. Select the **Linker** > **Debugging** property page. -1. Modify the **Generate Debug Info** property to enable PDB generation. This enables /DEBUG:FASTLINK by default in Visual Studio 2017 and later. +1. Modify the **Generate Debug Info** property to enable or disable PDB generation. This property enables **`/DEBUG:FASTLINK`** by default in Visual Studio 2017 and later. -1. Modify the **Generate Full Program Database File** property to enable /DEBUG:FULL for full PDB generation for every incremental build. +1. Modify the **Generate Full Program Database File** property to enable **`/DEBUG:FULL`** for full PDB generation for every incremental build. ### To set this linker option programmatically @@ -54,5 +54,5 @@ It is not possible to create an .exe or .dll that contains debug information. De ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/decorated-names.md b/docs/build/reference/decorated-names.md index 70a2e2d05d..6370302c0d 100644 --- a/docs/build/reference/decorated-names.md +++ b/docs/build/reference/decorated-names.md @@ -1,22 +1,22 @@ --- -description: "Learn more about: Decorated Names" -title: "Decorated Names" -ms.date: "09/05/2018" +description: "Learn more about: Decorated names" +title: "Decorated names" +ms.date: 06/08/2022 helpviewer_keywords: ["decorated names, definition", "name decoration [C++]", "names [C++], decorated"] ms.assetid: a4e9ae8e-b239-4454-b401-4102793cb344 --- -# Decorated Names +# Decorated names Functions, data, and objects in C and C++ programs are represented internally by their decorated names. A *decorated name* is an encoded string created by the compiler during compilation of an object, data, or function definition. It records calling conventions, types, function parameters and other information together with the name. This name decoration, also known as *name mangling*, helps the linker find the correct functions and objects when linking an executable. The decorated naming conventions have changed in various versions of Visual Studio, and can also be different on different target architectures. To link correctly with source files created by using Visual Studio, C and C++ DLLs and libraries should be compiled by using the same compiler toolset, flags, and target architecture. > [!NOTE] -> Libraries built with Visual Studio 2015 can be consumed by applications built with Visual Studio 2017 or Visual Studio 2019. +> Libraries built by Visual Studio 2015 or later can be consumed by applications built with later versions of Visual Studio through Visual Studio 2022. For more information, see [C++ binary compatibility between Visual Studio versions](../../porting/binary-compat-2015-2017.md). ## Using decorated names -Normally, you don't have to know the decorated name to write code that compiles and links successfully. Decorated names are an implementation detail internal to the compiler and linker. The tools can usually handle the name in its undecorated form. However, a decorated name is sometimes required when you specify a function name to the linker and other tools. For example, to match overloaded C++ functions, members of namespaces, class constructors, destructors and special member functions, you must specify the decorated name. For details about the option flags and other situations that require decorated names, see the documentation for the tools and options that you are using. +Normally, you don't have to know the decorated name to write code that compiles and links successfully. Decorated names are an implementation detail internal to the compiler and linker. The tools can usually handle the name in its undecorated form. However, a decorated name is sometimes required when you specify a function name to the linker and other tools. For example, to match overloaded C++ functions, members of namespaces, class constructors, destructors and special member functions, you must specify the decorated name. For details about the option flags and other situations that require decorated names, see the documentation for the tools and options that you're using. If you change the function name, class, calling convention, return type, or any parameter, the decorated name also changes. In this case, you must get the new decorated name and use it everywhere the decorated name is specified. @@ -28,9 +28,9 @@ A decorated name for a C++ function contains the following information: - The function name. -- The class that the function is a member of, if it is a member function. This may include the class that encloses the class that contains the function, and so on. +- The class that the function is a member of, if it's a member function. The decoration may include the class that encloses the class that contains the function, and so on. -- The namespace the function belongs to, if it is part of a namespace. +- The namespace the function belongs to, if it's part of a namespace. - The types of the function parameters. @@ -38,47 +38,51 @@ A decorated name for a C++ function contains the following information: - The return type of the function. +- An optional target-specific element. In ARM64EC objects, a **`$$h`** tag is inserted into the name. + The function and class names are encoded in the decorated name. The rest of the decorated name is a code that has internal meaning only for the compiler and the linker. The following are examples of undecorated and decorated C++ names. -|Undecorated name|Decorated name| -|----------------------|--------------------| -|`int a(char){int i=3;return i;};`|`?a@@YAHD@Z`| -|`void __stdcall b::c(float){};`|`?c@b@@AAGXM@Z`| +| Undecorated name | Decorated name | +|--|--| +| `int a(char){int i=3;return i;};` | `?a@@YAHD@Z` | +| `void __stdcall b::c(float){};` | `?c@b@@AAGXM@Z` | ## Format of a C decorated name -The form of decoration for a C function depends on the calling convention used in its declaration, as shown in the following table. This is also the decoration format that is used when C++ code is declared to have `extern "C"` linkage. The default calling convention is **`__cdecl`**. Note that in a 64-bit environment, functions are not decorated. +The form of decoration for a C function depends on the calling convention used in its declaration, as shown in the following table. It's also the decoration format that's used when C++ code is declared to have `extern "C"` linkage. The default calling convention is **`__cdecl`**. In a 64-bit environment, C or `extern "C"` functions are only decorated when using the `__vectorcall` calling convention. + +| Calling convention | Decoration | +|--|--| +| **`__cdecl`** | Leading underscore (**`_`**) | +| **`__stdcall`** | Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal | +| **`__fastcall`** | Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list | +| **`__vectorcall`** | Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list | -|Calling convention|Decoration| -|------------------------|----------------| -|**`__cdecl`**|Leading underscore (**`_`**)| -|**`__stdcall`**|Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal| -|**`__fastcall`**|Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list| -|**`__vectorcall`**|Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list| +For ARM64EC functions with C linkage (whether compiled as C or by using `extern "C"`), a **`#`** is prepended to the decorated name. -## Viewing decorated names +## View decorated names You can get the decorated form of a symbol name after you compile the source file that contains the data, object, or function definition or prototype. To examine decorated names in your program, you can use one of the following methods: -#### To use a listing to view decorated names +### To use a listing to view decorated names -1. Generate a listing by compiling the source file that contains the data, object, or function definition or prototype with the [Listing File Type](fa-fa-listing-file.md) compiler option set to Assembly with Source Code (**/FAs**). +1. Generate a listing by compiling the source file that contains the data, object, or function definition or prototype with the [`/FA` (Listing file type)](fa-fa-listing-file.md) compiler option set to assembly with source code (**`/FAs`**). - For example, enter `cl /c /FAs example.cpp` at a developer command prompt to generate a listing file, example.asm. + For example, enter `cl /c /FAs example.cpp` at a developer command prompt to generate a listing file, *`example.asm`*. -2. In the resulting listing file, find the line that starts with PUBLIC and ends a semicolon followed by the undecorated data or function name. The symbol between PUBLIC and the semicolon is the decorated name. +1. In the resulting listing file, find the line that starts with `PUBLIC` and ends a semicolon (**`;`**) followed by the undecorated data or function name. The symbol between `PUBLIC` and the semicolon is the decorated name. -#### To use DUMPBIN to view decorated names +### To use DUMPBIN to view decorated names -1. To see the exported symbols in an .obj or .lib file, enter `dumpbin /exports ` at a developer command prompt. +1. To see the exported symbols in an OBJ or LIB file, enter `dumpbin /exports ` at a developer command prompt. -2. To find the decorated form of a symbol, look for the undecorated name in parentheses. The decorated name is on the same line, before the undecorated name. +1. To find the decorated form of a symbol, look for the undecorated name in parentheses. The decorated name is on the same line, before the undecorated name. ## Viewing undecorated names You can use undname.exe to convert a decorated name to its undecorated form. This example shows how it works: -``` +```cmd C:\>undname ?func1@a@@AAEXH@Z Microsoft (R) C++ Name Undecorator Copyright (C) Microsoft Corporation. All rights reserved. @@ -89,5 +93,5 @@ is :- "private: void __thiscall a::func1(int)" ## See also -[Additional MSVC Build Tools](c-cpp-build-tools.md)
-[Using extern to Specify Linkage](../../cpp/extern-cpp.md) +[Additional MSVC build tools](c-cpp-build-tools.md)\ +[Using `extern` to specify linkage](../../cpp/extern-cpp.md) diff --git a/docs/build/reference/def-specify-module-definition-file.md b/docs/build/reference/def-specify-module-definition-file.md index ad5e6a38fa..42e938c3ff 100644 --- a/docs/build/reference/def-specify-module-definition-file.md +++ b/docs/build/reference/def-specify-module-definition-file.md @@ -1,37 +1,34 @@ --- -description: "Learn more about: /DEF (Specify Module-Definition File)" -title: "/DEF (Specify Module-Definition File)" -ms.date: "11/04/2016" +description: "Learn more about: /DEF (Specify module-definition file)" +title: "/DEF (Specify module-definition file)" +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.ModuleDefinitionFile", "/def"] helpviewer_keywords: ["module definition files, specifying", "DEF linker option", "-DEF linker option", "module definition files", "/DEF linker option"] -ms.assetid: 6497fa68-65f0-48ca-8f66-b87166fc631a --- -# /DEF (Specify Module-Definition File) +# `/DEF` (Specify module-definition file) -``` -/DEF:filename -``` +Specifies a module-definition file to the linker. -## Arguments +## Syntax -*filename*
-The name of a module-definition file (.def) to be passed to the linker. +> **`/DEF:`***`filename`* -## Remarks +## Arguments -The /DEF option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. For details about .def files, see [Module-Definition Files](module-definition-dot-def-files.md). +*`filename`*\ +The name of a module-definition file (*`.def`*) to be passed to the linker. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). -### To set this linker option in the Visual Studio development environment - -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +## Remarks -1. Click the **Linker** folder. +The **`/DEF`** linker option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. For details about *`.def`* files, see [Module-definition files](module-definition-dot-def-files.md). -1. Click the **Input** property page. +To specify a *`.def`* file from within the development environment, add it to the project along with your other source files and then specify the file in the project's **Property Pages** dialog. -1. Modify the **Module Definition File** property. +### To set this linker option in the Visual Studio development environment -To specify a .def file from within the development environment, you should add it to the project along with other files and then specify the file to the /DEF option. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Input** property page. +1. Modify the **Module Definition File** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +36,5 @@ To specify a .def file from within the development environment, you should add i ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/defining-an-nmake-macro.md b/docs/build/reference/defining-an-nmake-macro.md index e503302651..dd09538893 100644 --- a/docs/build/reference/defining-an-nmake-macro.md +++ b/docs/build/reference/defining-an-nmake-macro.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Defining an NMAKE Macro" title: "Define an NMAKE Macro" +description: "Learn more about: Defining an NMAKE Macro" ms.date: 09/30/2021 helpviewer_keywords: ["macros, NMAKE", "defining NMAKE macros", "NMAKE macros, defining", "defining macros", "NMAKE program, defining macros", "NMAKE program, undefined macros", "Null macros in NMAKE", "macros, null and undefined", "undefined macros and NMAKE", "NMAKE program, null macros", "special characters, in NMAKE macros"] --- @@ -16,7 +16,7 @@ The *macro_name* is a case-sensitive combination of letters, digits, and undersc The *string* can be any sequence of zero or more characters. A *null* string contains zero characters or only spaces or tabs. The *string* can contain a macro invocation. -## Special characters in macros +## Special characters in macros A number sign (**`#`**) after a definition specifies a comment. To specify a literal number sign in a macro, use a caret (**`^`**) to escape it, as in **`^#`**. @@ -31,11 +31,11 @@ CMDS = cls^ dir ``` -## Null and undefined macros +## Null and undefined macros Both null and undefined macros expand to null strings, but a macro defined as a null string is considered defined in preprocessing expressions. To define a macro as a null string, specify no characters except spaces or tabs after the equal sign (**`=`**) in a command line or command file, and enclose the null string or definition in double quotation marks (**`" "`**). To undefine a macro, use **`!UNDEF`**. For more information, see [Makefile preprocessing directives](makefile-preprocessing.md#makefile-preprocessing-directives). -## Where to define macros +## Where to define macros Define macros in a command line, command file, makefile, or the *`Tools.ini`* file. @@ -43,7 +43,7 @@ In a makefile or the *`Tools.ini`* file, each macro definition must appear on a In a command line or command file, spaces and tabs delimit arguments and can't surround the equal sign. If *string* has embedded spaces or tabs, enclose either the string itself or the entire macro in double quotation marks (**`" "`**). -## Precedence in macro definitions +## Precedence in macro definitions If a macro has multiple definitions, NMAKE uses the highest-precedence definition. The following list shows the order of precedence, from highest to lowest: diff --git a/docs/build/reference/delay-delay-load-import-settings.md b/docs/build/reference/delay-delay-load-import-settings.md index 07856d7724..a1054d65b8 100644 --- a/docs/build/reference/delay-delay-load-import-settings.md +++ b/docs/build/reference/delay-delay-load-import-settings.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /DELAY (Delay load import settings)" title: "/DELAY (Delay load import settings)" -ms.date: 01/28/2021 -f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload"] +ms.date: 09/19/2022 +f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload", "VC.Project.VCLinkerTool.SupportNobindOfDelayLoadedDLL"] helpviewer_keywords: ["delayed loading of DLLs, /DELAY option", "DELAY linker option", "/DELAY linker option", "-DELAY linker option"] --- # `/DELAY` (Delay load import settings) @@ -32,15 +32,15 @@ To specify DLLs to delay load, use the [`/DELAYLOAD`](delayload-delay-load-impor ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Modify the **Delay Loaded DLL** property. Choose **OK** to save your changes. +1. Modify the **Unload delay loaded DLL** property or the **Unbind delay loaded DLL** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- See . +- See . ## See also diff --git a/docs/build/reference/description-blocks.md b/docs/build/reference/description-blocks.md index 6175063ce7..3f45702146 100644 --- a/docs/build/reference/description-blocks.md +++ b/docs/build/reference/description-blocks.md @@ -156,7 +156,7 @@ In this example, UPDATE is a pseudotarget. ```makefile UPDATE : *.* -!COPY $** c:\product\release +COPY $** c:\product\release ``` When UPDATE is evaluated, NMAKE copies all files in the current directory to the specified drive and directory. diff --git a/docs/build/reference/dot-ilk-files-as-linker-input.md b/docs/build/reference/dot-ilk-files-as-linker-input.md index e53baf1be6..5e5e761ff8 100644 --- a/docs/build/reference/dot-ilk-files-as-linker-input.md +++ b/docs/build/reference/dot-ilk-files-as-linker-input.md @@ -1,15 +1,19 @@ --- -description: "Learn more about: .Ilk Files as Linker Input" -title: ".Ilk Files as Linker Input" -ms.date: "11/04/2016" -helpviewer_keywords: ["ILK files", ".ilk files"] +description: "Learn more about: .ilk files as linker input" +title: ".ilk files as linker input" +ms.date: 09/07/2022 +helpviewer_keywords: [".ilk files", ".ilk files"] ms.assetid: 7324c104-9e5d-423d-b268-b59f92607bf2 --- -# .Ilk Files as Linker Input +# `.ilk` files as linker input -When linking incrementally, LINK updates the .ilk status file that it created during the first incremental link. This file has the same base name as the .exe file or the .dll file, and it has the extension .ilk. During subsequent incremental links, LINK updates the .ilk file. If the .ilk file is missing, LINK performs a full link and creates a new .ilk file. If the .ilk file is unusable, LINK performs a nonincremental link. For details about incremental linking, see the [Link Incrementally (/INCREMENTAL)](incremental-link-incrementally.md) option. +The linker creates and uses a *`.ilk`* database file for incremental link information. + +## Remarks + +When linking incrementally, LINK updates the *`.ilk`* status file that it created during the first incremental link. This file has the same base name as the target EXE or DLL file, and it has the extension *`.ilk`*. During subsequent incremental links, LINK updates the *`.ilk`* file. If the *`.ilk`* file is missing, LINK performs a full link and creates a new *`.ilk`* file. If the *`.ilk`* file is unusable, LINK performs a non-incremental link. For more information about incremental linking, see the [`/INCREMENTAL` (Link incrementally)](incremental-link-incrementally.md) linker option. For information about how to specify the name and location of the file, see [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md). ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dot-lib-files-as-linker-input.md b/docs/build/reference/dot-lib-files-as-linker-input.md index dc12e4a0bb..875c8694c9 100644 --- a/docs/build/reference/dot-lib-files-as-linker-input.md +++ b/docs/build/reference/dot-lib-files-as-linker-input.md @@ -1,32 +1,36 @@ --- -description: "Learn more about: .Lib Files as Linker Input" -title: ".Lib Files as Linker Input" -ms.date: "11/04/2016" +description: "Learn more about: .lib files as linker input" +title: ".lib files as linker input" +ms.date: 09/09/2022 f1_keywords: ["VC.Project.VCLinkerTool.AdditionalDependencies"] helpviewer_keywords: ["OMF libraries", "linking [C++], OMF libraries", "import libraries, linker files", "libraries [C++], .lib files as linker input", "COFF files, import libraries", "default libraries [C++], linker output", "default libraries [C++]", "defaults [C++], libraries", ".lib files"] ms.assetid: dc5d2b1c-2487-41fa-aa71-ad1e0647958b --- -# .Lib Files as Linker Input +# `.lib` files as linker input -LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension .lib. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [/DLL](dll-build-a-dll.md) option. +LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension *`.lib`*. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [`/DLL`](dll-build-a-dll.md) option. -A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [/DEFAULTLIB](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the LIB environment variable. +A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the `LIB` environment variable. -## To add .lib files as linker input in the development environment +## To add `.lib` files as linker input in the development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Input** property page in the **Linker** folder. +1. Choose the **Configuration Properties** > **Linker** > **Input** property page. -1. Modify the **Additional Dependencies** property to add the .lib files. +1. Modify the **Additional Dependencies** property to add the *`.lib`* files. -## To programmatically add .lib files as linker input +1. Choose **OK** or **Apply** to save your changes. -- See [AdditionalDependencies](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.additionaldependencies). +## To programmatically add `.lib` files as linker input + +- See . ## Example -The following sample shows how to build and use a .lib file. First, build a .lib file: +The following sample shows how to build and use a *`.lib`* file. + +First, build the *`.lib`* file: ```cpp // lib_link_input_1.cpp @@ -36,7 +40,7 @@ __declspec(dllexport) int Test() { } ``` -And then, compile this sample by using the .lib file you just created: +And then, compile this sample by using the *`.lib`* file you just created: ```cpp // lib_link_input_2.cpp @@ -54,5 +58,5 @@ int main() { ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dumpbin-options.md b/docs/build/reference/dumpbin-options.md index 2bedc34b9e..71bd3a9c66 100644 --- a/docs/build/reference/dumpbin-options.md +++ b/docs/build/reference/dumpbin-options.md @@ -1,9 +1,8 @@ --- title: "DUMPBIN options" description: "Reference guide to the Microsoft DUMPBIN utility command-line options." -ms.date: "02/09/2020" +ms.date: 02/09/2020 helpviewer_keywords: ["DUMPBIN program, options"] -ms.assetid: 563b696e-7599-4480-94b9-014776289ec8 --- # DUMPBIN options @@ -49,7 +48,7 @@ DUMPBIN has the following options: - [/PDBPATH\[:VERBOSE\]](pdbpath.md) -- [/RANGEE:vaMin\[,vaMax\]](range.md) +- [/RANGE:vaMin\[,vaMax\]](range.md) - [/RAWDATA\[:{NONE\|1\|2\|4\|8}\[,#\]\]](rawdata.md) diff --git a/docs/build/reference/dynamic-deopt-linker.md b/docs/build/reference/dynamic-deopt-linker.md new file mode 100644 index 0000000000..6d4602acfc --- /dev/null +++ b/docs/build/reference/dynamic-deopt-linker.md @@ -0,0 +1,53 @@ +--- +title: "/DYNAMICDEOPT (Support C++ Dynamic Debugging) (Preview)" +description: "Learn more about: /DYNAMICDEOPT (Support C++ Dynamic Debugging)." +ms.date: 03/14/2025 +f1_keywords: ["VC.Project.VCLinkerTool.GenerateDynamicDeoptInformation", "/dynamicdeopt"] +helpviewer_keywords: ["DYNAMICDEOPT linker option", "/DYNAMICDEOPT linker option", "-DYNAMICDEOPT linker option", "c++ dynamic debugging"] +--- +# `/DYNAMICDEOPT` (Support C++ Dynamic Debugging) (Preview) + +> [!IMPORTANT] +> The `/DYNAMICDEOPT` linker switch is currently in PREVIEW. +> This information relates to a prerelease feature that might be substantially modified before release. Microsoft makes no warranties, expressed or implied, with respect to the information provided here. + +The **`/DYNAMICDEOPT`** linker option, when used with the compiler switch [`/dynamicdeopt`](dynamic-deopt.md), enables [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging), which allows you to debug optimized code as if it were compiled deoptimized and step in anywhere with on-demand function deoptimization. + +## Syntax + +> **`/DYNAMICDEOPT`**\ +> **`/DYNAMICDEOPT:SUFFIX=`**\ +> **`/DYNAMICDEOPT:SYNC`** + +## Arguments + +*`suffix`*\ +Specify the file extension for the deoptimized output. + +With no options and given `test.cpp` as input, the compiler output includes `test.obj`, `test.exe`, and `test.pdb`, as well as `test.alt.obj`, `test.alt.exe`, and `test.alt.pdb`. This switch allows you to change the suffix for the unoptimized binary build artifacts from `.alt` to something else. If you change the suffix, all files must use the new suffix, and it needs to match the name passed to the compiler using [`/dynamicdeopt:suffix` (Preview)](dynamic-deopt.md). You typically don't use this switch unless you need to avoid filename collisions with other files that you have. + +*`SYNC`*\ +Builds the deoptimized output after building the optimized output instead of in parallel. By default, the compiler spawns a parallel linker to link the unoptimized binary. This switch makes the second link run serially after the first one. This switch is provided in case this better suits your build environment. + +## Remarks + +This preview flag, available starting with Visual Studio 2022 Version 17.14 Preview 2, applies only to x64 projects. + +IncrediBuild 10.24 supports C++ Dynamic Debugging builds.\ +FastBuild v1.15 supports C++ Dynamic Debugging builds. + +### Set this linker option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the **Linker** > **Debugging** property page. + +### Set this linker option programmatically + +- See . + +## See also + +[`/dynamicdeopt` (Enable C++ Dynamic Debugging) (Preview)](dynamic-deopt.md)\ +[C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dynamic-deopt.md b/docs/build/reference/dynamic-deopt.md new file mode 100644 index 0000000000..33edd942e3 --- /dev/null +++ b/docs/build/reference/dynamic-deopt.md @@ -0,0 +1,78 @@ +--- +title: "/dynamicdeopt (Enable C++ Dynamic Debugging (Preview))" +description: "Enable the Microsoft C++ compiler option /dynamicdeopt to use C++ Dynamic Debugging." +ms.date: 04/01/2025 +f1_keywords: ["/dynamicdeopt"] +helpviewer_keywords: ["-dynamicdeopt compiler option [C++]", "dynamicdeopt compiler option [C++]"] +--- +# `/dynamicdeopt` (Enable C++ Dynamic Debugging) (Preview) + +> [!IMPORTANT] +> The `/dynamicdeopt` compiler switch is currently in PREVIEW. +> This information relates to a prerelease feature that might be substantially modified before release. Microsoft makes no warranties, expressed or implied, with respect to the information provided here. + +Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) so you can debug optimized code as if it were compiled deoptimized and step in anywhere with on-demand function deoptimization. + +## Syntax + +> **`/dynamicdeopt`**\ +> **`/dynamicdeopt:suffix `**\ +> **`/dynamicdeopt:sync`** + +## Arguments + +*`suffix`*\ +Specify the file extension for the deoptimized output. + +With no options and given `test.cpp` as input, your output includes `test.obj`, `test.exe`, and `test.pdb`, as well as `test.alt.obj`, `test.alt.exe`, and `test.alt.pdb`. This switch allows you to change the suffix of the unoptimized binary build artifacts from `.alt` to something else. If you change the suffix, all files must use the new suffix, and it needs to match the name passed to the linker using [`/dynamicdeopt:suffix` (Preview)](dynamic-deopt-linker.md). You typically don't use this switch unless you need to avoid filename collisions with other files that you have. + +*`sync`*\ +Builds the deoptimized output after building the optimized output instead of in parallel. By default, the compiler spawns a parallel instance of the code generator. This switch makes them run serially instead. This switch is provided in case this better suits your build environment. + +## Remarks + +This preview flag, available starting with Visual Studio 2022 Version 17.14 Preview 2, applies only to x64 projects and must be used with the corresponding linker flag, [`/DYNAMICDEOPT`](dynamic-deopt-linker.md). + +Compiling with `/dynamicdeopt` generates other binaries that are used for debugging. When you debug an optimized function in an optimized file, the debugger steps into the alternate binary instead. This allows you to debug as if you're debugging unoptimized code while still getting the performance advantages of optimized code. + +`/dynamicdeopt` requires: + +`/DEBUG` or `/DEBUG:FULL`. If you don't specify `/DEBUG`, or if you specify `/DEBUG:FASTLINK`, the linker gives a fatal error. +If you specify `/INCREMENTAL`, the compiler generates a warning and automatically turns off `/INCREMENTAL`. +If you specify `/OPT:ICF`, the compiler generates a warning that the debug experience isn't as good. This is because ICF can cause functions to be removed from the alt file, which means you can't step into them. + +IncrediBuild 10.24 supports C++ Dynamic Debugging builds.\ +FastBuild v1.15 supports C++ Dynamic Debugging builds. + +`/dynamicdeopt` is incompatible with edit-and-continue and the following compiler switches: + +```cpp +/GL +/ZI +/RTC1 +/RTCs +/RTCc +/RTCu +/GH +/Gh +/fastcap +/callcap +/ZW +/fsanitize=address +/fsanitize=kernel-address +All of the CLR flags +``` + +### Set this linker option in the Visual Studio development environment + +You can set this switch inside Visual Studio. For more information, see [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging#build-system-integration). There are advantages to setting the switch in Visual Studio because MSBuild automatically suppresses some of the incompatible switches such as `/GL` and `/OPT:ICF`. It also sets the corresponding linker option (`/DYNAMICDEOPT`). You can also set the switch in the command line. + +### Set this compiler option programmatically + +- See . + +## See also + +[C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging)\ +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md b/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md index a611af178f..b5ca6135c2 100644 --- a/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md +++ b/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md @@ -1,24 +1,26 @@ --- description: "Learn more about: /DYNAMICBASE (Use address space layout randomization)" title: "/DYNAMICBASE (Use address space layout randomization)" -ms.date: "06/12/2018" +ms.date: 05/05/2022 f1_keywords: ["VC.Project.VCLinkerTool.RandomizedBaseAddress"] helpviewer_keywords: ["-DYNAMICBASE linker option", "/DYNAMICBASE linker option", "DYNAMICBASE linker option"] ms.assetid: 6c0ced8e-fe9c-4b63-b956-eb8a55fbceb2 --- -# /DYNAMICBASE (Use address space layout randomization) +# `/DYNAMICBASE` (Use address space layout randomization) -Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows that was first available in Windows Vista. +Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. ASLR was first available in Windows Vista. ## Syntax -> **/DYNAMICBASE**[**:NO**] +> **`/DYNAMICBASE`**[**`:NO`**] ## Remarks -The **/DYNAMICBASE** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **/DYNAMICBASE** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. +The **`/DYNAMICBASE`** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **`/DYNAMICBASE`** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. -By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICBASE:NO**. The **/DYNAMICBASE** option is required for the [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) option to have an effect. +By default, **`/DYNAMICBASE`** is enabled. To disable this option, use **`/DYNAMICBASE:NO`**. The **`/DYNAMICBASE`** option is required for the [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) option to have an effect. + +Because ASLR can't be disabled on ARM, ARM64, or ARM64EC architectures, **`/DYNAMICBASE:NO`** isn't supported for these targets. ### To set this linker option in Visual Studio @@ -35,6 +37,6 @@ By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICB ## See also - [MSVC linker reference](linking.md) -- [MSVC Linker Options](linker-options.md) -- [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) +- [MSVC linker options](linker-options.md) +- [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) - [Windows ISV Software Security Defenses](/previous-versions/bb430720(v=msdn.10)) diff --git a/docs/build/reference/dynamicbase.md b/docs/build/reference/dynamicbase.md index 7d42ad401b..9ccddd3219 100644 --- a/docs/build/reference/dynamicbase.md +++ b/docs/build/reference/dynamicbase.md @@ -1,24 +1,26 @@ --- description: "Learn more about: /DYNAMICBASE" title: "/DYNAMICBASE" -ms.date: "06/12/2018" +ms.date: "05/05/2022" f1_keywords: ["/dynamicbase"] helpviewer_keywords: ["-DYNAMICBASE editbin option", "DYNAMICBASE editbin option", "/DYNAMICBASE editbin option"] ms.assetid: edb3df90-7b07-42fb-a94a-f5a4c1d325d6 --- -# /DYNAMICBASE +# `/DYNAMICBASE` Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows that was first available in Windows Vista. ## Syntax -> **/DYNAMICBASE**[**:NO**] +> **`/DYNAMICBASE`**[**`:NO`**] ## Remarks -The **/DYNAMICBASE** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **/DYNAMICBASE** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. +The **`/DYNAMICBASE`** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **`/DYNAMICBASE`** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. -By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICBASE:NO**. The **/DYNAMICBASE** option is required for the [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) option to have an effect. +By default, **`/DYNAMICBASE`** is enabled. To disable this option, use **`/DYNAMICBASE:NO`**. The **`/DYNAMICBASE`** option is required for the [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) option to have an effect. + +Because ASLR can't be disabled on ARM, ARM64, or ARM64EC architectures, **`/DYNAMICBASE:NO`** isn't supported for these targets. ## See also diff --git a/docs/build/reference/execution-charset-set-execution-character-set.md b/docs/build/reference/execution-charset-set-execution-character-set.md index fda1c306f4..2d67217025 100644 --- a/docs/build/reference/execution-charset-set-execution-character-set.md +++ b/docs/build/reference/execution-charset-set-execution-character-set.md @@ -1,51 +1,49 @@ --- -description: "Learn more about: /execution-charset (Set Execution Character Set)" -title: "/execution-charset (Set Execution Character Set)" -ms.date: "02/06/2019" +description: "Learn more about: /execution-charset (Set execution character set)" +title: "/execution-charset (Set execution character set)" +ms.date: 01/31/2022 f1_keywords: ["execution-charset", "/execution-charset"] helpviewer_keywords: ["/execution-charset compiler option", "-execution-charset compiler option"] ms.assetid: 0e02f487-2236-45bc-95f3-5760933a8f96 --- -# /execution-charset (Set Execution Character Set) +# `/execution-charset` (Set execution character set) -Lets you specify the execution character set for your executable. +This option lets you specify the execution character set for your executable. ## Syntax -``` -/execution-charset:[IANA_name|.CPID] -``` +> **`/execution-charset:`**[*`IANA_name`* | *`.CPID`*] ## Arguments -*IANA_name*
+*`IANA_name`*\ The IANA-defined character set name. -*CPID*
-The code page identifier. +*`.CPID`*\ +The code page identifier, preceded by a `.` character. ## Remarks -You can use the **/execution-charset** option to specify an execution character set. The execution character set is the encoding used for the text of your program that is input to the compilation phase after all preprocessing steps. This character set is used for the internal representation of any string or character literals in the compiled code. Set this option to specify the extended execution character set to use when your source files include characters that are not representable in the basic execution character set. You can use either the IANA or ISO character set name, or a dot (.) followed by a 3 to 5 digit decimal code page identifier to specify the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +You can use the **`/execution-charset`** option to specify an execution character set. The execution character set is the encoding used for the text of your program that is input to the compilation phase after all preprocessing steps. This character set is used for the internal representation of any string or character literals in the compiled code. Set this option to specify the extended execution character set to use when your source files include characters that are not representable in the basic execution character set. You can use either the IANA or ISO character set name, or a dot (`.`) followed by 3-5 decimal digits that specify the code page identifier of the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you have specified a character set name or code page by using the **/source-charset** option or the **/utf-8** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you used the **`/source-charset`** or **`/utf-8`** option to specify a character set name or code page. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. -If you want to set both the source character set and the execution character set to UTF-8, you can use the **/utf-8** compiler option as a shortcut. It is equivalent to specifying **/source-charset:utf-8 /execution-charset:utf-8** on the command line. Any of these options also enables the **/validate-charset** option by default. +If you want to set both the source character set and the execution character set to UTF-8, you can use the **`/utf-8`** compiler option as a shortcut. It's equivalent to **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for your project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In **Additional Options**, add the **/execution-charset** option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/execution-charset`** option, and specify your preferred encoding. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/experimental-log.md b/docs/build/reference/experimental-log.md new file mode 100644 index 0000000000..413151fd86 --- /dev/null +++ b/docs/build/reference/experimental-log.md @@ -0,0 +1,56 @@ +--- +title: "/experimental:log (Structured SARIF diagnostics)" +description: "The /experimental:log compiler option outputs experimental structured SARIF output for diagnostics." +ms.date: 06/05/2025 +f1_keywords: ["/experimental:log"] +helpviewer_keywords: ["/experimental:log", "SARIF", "structured diagnostics"] +--- +# `/experimental:log` (Structured SARIF diagnostics) + +Output [SARIF](https://sarifweb.azurewebsites.net/) diagnostics to the specified file or directory. For more information, see [Structured SARIF Diagnostics](sarif-output.md). + +## Syntax + +> **`/experimental:log`** *filename*\ +> **`/experimental:log`** *directoryname\\* + +## Arguments + +*filename* + +The output file for SARIF diagnostics. The compiler automatically adds the `.sarif` extension to *filename*. The space between `/experimental:log` and *filename* is optional. Use double quotes around paths containing spaces. Both relative and absolute paths are supported. + +*directoryname\\* + +The output directory for SARIF diagnostics (for example, `/experimental:log sarif_output\`). Remember to add the trailing backslash (`\`) to indicate it's a directory. Each source file name forms the base name for each SARIF file saved in the directory. The compiler automatically adds the `.sarif` extension to each file name. The space between `/experimental:log` and *directoryname\\* is optional. Use double quotes around paths containing spaces. Both relative and absolute paths are supported. + +## Remarks + +This option is available starting in Visual Studio 2022 version 17.8. + +Diagnostics are also output as text to the console as usual. + +### To set this compiler option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the specific project **Configuration** and **Platform** for which you want to change the property. You can also choose **"All Configurations"** and **"All Platforms"**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Modify the **Additional Options** property, and then choose **OK**. + +## Examples + +The following command produces SARIF information for the compilation of `main.cpp` and saves it in the file `mySarifInfo.sarif`: + +```cmd +cl /experimental:log mySarifInfo main.cpp +``` + +The following command produces SARIF information for the entire compilation and saves it in the `sarif_output` directory in the files `main.sarif` and `other.sarif`: + +```cmd +cl /experimental:log sarif_output\ main.cpp other.cpp +``` + +## See also + +[Structured SARIF Diagnostics](sarif-output.md) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index e8c53e432b..bfbcec74a8 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -1,13 +1,13 @@ --- title: "/experimental:module (Enable module support)" description: "Use the /experimental:module compiler option to enable experimental compiler support for named modules." -ms.date: "04/13/2021" +ms.date: 02/12/2025 f1_keywords: ["module", "/experimental:module"] helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- -# `/experimental:module` (Enable module support) +# `/experimental:module` (Enable experimental module support) -Enables experimental compiler support for C++ Standard modules. This option is obsolete in Visual Studio version 16.11 and later. +Enables compiler support for Microsoft's experimental form of C++ Standard modules. This option is obsolete in Visual Studio 2019 version 16.11 and later. ## Syntax @@ -15,24 +15,46 @@ Enables experimental compiler support for C++ Standard modules. This option is o ## Remarks -In versions of Visual Studio before Visual Studio 2019 version 16.11, you can enable experimental modules support by use of the **`/experimental:module`** compiler option along with the [`/std:c++latest`](std-specify-language-standard-version.md) option. In Visual Studio 2019 version 16.11, module support is enabled automatically by either **`/std:c++20`** or **`/std:c++latest`**. Use **`/experimental:module-`** to disable module support explicitly. + This switch applies to the time before the new, standardized, way of consuming the C++ Standard Library as modules was available. Although you can use this switch to use the older experimental named modules, we recommend that you use the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). -This option is available starting in Visual Studio 2015 Update 1. As of Visual Studio 2019 version 16.2, C++20 Standard modules aren't fully implemented in the Microsoft C++ compiler. Modules support is feature complete in Visual Studio 2019 version 16.10. You can use the modules feature import the Standard Library modules provided by Microsoft. A module and the code that consumes it must be compiled with the same compiler options. +This compiler switch is available starting in Visual Studio 2015 Update 1. In the VS Installer under the **Individual components** tab, ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** is selected. You can use the search box with **experimental** to find it. For more information, see [Install C and C++ support in Visual Studio](../vscpp-step-0-installation.md). -For more information on modules and how to use and create them, see [Overview of modules in C++](../../cpp/modules-cpp.md). +| Version | Status | +|---|---| +| Visual Studio 2015 Update 1 | `/experimental:module` introduced. | +| Visual Studio 2019 version 16.10 | C++20 modules support is feature complete. | +| Visual Studio 2019 16.11 and earlier | Enable experimental modules support using **`/experimental:module`** along with [`/std:c++latest`](std-specify-language-standard-version.md). | +| Visual Studio 2019 version 16.11 and later | Modules support is enabled automatically with **`/std:c++20`** or later, or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. | + +The experimental library consists of the following named modules: + +- `std.regex` provides the content of header `` +- `std.filesystem` provides the content of header `` +- `std.memory` provides the content of header `` +- `std.threading` provides the contents of headers ``, ``, ``, ``, ``, and `` +- `std.core` provides everything else in the C++ Standard Library + +To consume these modules, add an import declaration to the top of the source code file. For example: + +```cpp +import std.core; +import std.regex; +``` + +To consume the experimental Microsoft Standard Library modules, compile your program with the [`/EHsc`](eh-exception-handling-model.md) and [`/MD`](md-mt-ld-use-run-time-library.md) options. ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Set the **Configuration** drop-down to **All Configurations**. - 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. - 1. Modify the **Enable C++ Modules (experimental)** property, and then choose **OK**. +For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). + ## See also +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/exportHeader` (Create header units)](module-exportheader.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ diff --git a/docs/build/reference/external-external-headers-diagnostics.md b/docs/build/reference/external-external-headers-diagnostics.md index 9423c65d7b..30134f5f93 100644 --- a/docs/build/reference/external-external-headers-diagnostics.md +++ b/docs/build/reference/external-external-headers-diagnostics.md @@ -1,8 +1,8 @@ --- title: "/external (External headers diagnostics)" description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage." -ms.date: 07/02/2021 -f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external"] +ms.date: 06/29/2022 +f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external", "VC.Project.VCCLCompilerTool.ExternalDirectoriesEnv", "VC.Project.VCCLCompilerTool.ExternalIncludeDirectories", "VC.Project.VCCLCompilerTool.ExternalWarningLevel", "VC.Project.VCCLCompilerTool.TreatExternalTemplatesAsInternal"] helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"] --- # `/external` (External headers diagnostics) @@ -18,7 +18,7 @@ Use external header options (Not required in 16.10 and later): Specify external headers: > **`/external:anglebrackets`**\ -> **`/external:env:`**_`var`_\ +> **`/external:env:`***`var`*\ > **`/external:I`** *`path`* Specify diagnostics behavior: @@ -40,7 +40,7 @@ Treats all headers included by `#include
`, where the *`header`* file is **`/external:I`** *`path`*\ Defines a root directory that contains external headers. All recursive subdirectories of *`path`* are considered external, but only the *`path`* value is added to the list of directories the compiler searches for include files. The space between **`/external:I`** and *`path`* is optional. Directories that include spaces must be enclosed in double quotes. A directory may be an absolute path or a relative path. -**`/external:env:`**_`var`_\ +**`/external:env:`***`var`*\ Specifies the name of an environment variable *`var`* that holds a semicolon-separated list of external header directories. It's useful for build systems that rely on environment variables such as `INCLUDE`, which you use to specify the list of external include files. Or, `CAExcludePath`, for files that shouldn't be analyzed by `/analyze`. For example, you can specify `/external:env:INCLUDE` to make every directory in `INCLUDE` an external header directory at once. It's the same as using **`/external:I`** to specify the individual directories, but much less verbose. There should be no space between *`var`* and **`/external:env:`**. **`/external:Wn`**\ @@ -68,6 +68,8 @@ All the existing mechanisms to enable, disable, and suppress warnings still work This sample program has two source files, *`program.cpp`* and *`header_file.h`*. The *`header_file.h`* file is in an *`include_dir`* subdirectory of the directory containing the *`program.cpp`* file: +Source file `include_dir/header_file.h`: + ```cpp // External header: include_dir/header_file.h @@ -79,6 +81,8 @@ struct sample_struct }; ``` +Source file `program.cpp`: + ```cpp // User code: program.cpp #include @@ -97,7 +101,7 @@ cl /EHsc /I include_dir /W4 program.cpp As expected, this sample generates a warning: -```console +```Output program.cpp include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch with @@ -167,17 +171,41 @@ Some warnings emitted by the compiler's back-end code generation aren't affected ### To set this compiler option in the Visual Studio development environment +In Visual Studio 2019 version 16.10 and later: + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **VC++ Directories** property page. + +1. Set the **External Include Directories** property to specify the IDE equivalent of the **`/external:I path`** option for each semicolon-delimited path. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - Set **Treat Files Included with Angle Brackets as External** to **Yes** to set the **`/external:anglebrackets`** option. + + - **External Header Warning Level** allows you to set the **`/external:Wn`** option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + + - Set **Template Diagnostics in External Headers** to **Yes** to set the **`/external:templates-`** option. + +1. Choose **OK** or **Apply** to save your changes. + +In versions of Visual Studio before Visual Studio 2019 version 16.10: + 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Enter the compiler options[\*](#note_experimental) in the **Additional Options** box. +1. Enter the **`/experimental:external`** option and other **`/external`** compiler options in the **Additional Options** box. + +1. Choose **OK** or **Apply** to save your changes. ### To set this compiler option programmatically - See . -\* Add the `/experimental:external` option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10. +\* Add the **`/experimental:external`** option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10. ## See also diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md new file mode 100644 index 0000000000..2954b4fed1 --- /dev/null +++ b/docs/build/reference/feature-arm64.md @@ -0,0 +1,47 @@ +--- +description: "Learn more about: /feature (ARM64)" +title: "/feature (ARM64)" +ms.date: 05/28/2024 +--- +# `/feature` (ARM64) + +Enable one or more Arm A-Profile architecture features for an ARM64 extension as specified by **`/arch`** (ARM64). For more information about **`/arch`** (ARM64), see [`/arch` (ARM64)](arch-arm64.md). + +## Syntax + +> **`/feature:`**[**`+arg2`**] + +## Arguments +To enable one or more features the targeted ARM64 extension supports, specify one or more of the following feature arguments: + +| Feature argument | Feature identifier | Optional from | Enabled by default | Description | Supported in version +|--|--|--|--|--|--| +|**`lse`** | `FEAT_LSE` | Armv8.0 | Armv8.1 | Large System Extensions. | Visual Studio 2022 17.10 +|**`rcpc`** | `FEAT_LRCPC` | Armv8.2 | Armv8.3 | Load-Acquire RCpc instructions. | Visual Studio 2022 17.10 +|**`rcpc2`** | `FEAT_LRCPC2` | Armv8.2 | Armv8.4 | Load-Acquire RCpc instructions v2. | Visual Studio 2022 17.11 + +## Remarks + +Example usage: to enable `FEAT_LSE`, specify **`/feature:lse`**. + +If there are conflicting feature arguments specified by **`/feature`**, the right-most feature is enabled. Enabling a feature the targeted ARM64 extension doesn't support may cause unexpected behavior, especially if a CPU doesn't implement the feature. + +Use either **`/feature`** or only **`/arch`** (ARM64) to specify features. For example, to enable `FEAT_LSE` when targeting Armv8.0-A, use both **`/feature:lse`** and **`/arch:armv8.0`**, or specify **`/arch:armv8.0+lse`**. **`/feature`** is a way to specify features without specifying them in **`/arch`** (ARM64). + +### To set the `/feature` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In the **Additional options** box, add *`/feature:lse`* or replace `lse` with the feature to enable. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/filealign.md b/docs/build/reference/filealign.md index 31f8c859d1..1e794ab0e1 100644 --- a/docs/build/reference/filealign.md +++ b/docs/build/reference/filealign.md @@ -8,7 +8,7 @@ ms.assetid: c1017a35-8d71-4ad9-934b-a3e3ea037fa0 --- # /FILEALIGN (Align sections in files) -The **/FILEALIGN** linker option lets you specify the alignment of sections written to your output file as a multiple of an specified size. +The **/FILEALIGN** linker option lets you specify the alignment of sections written to your output file as a multiple of a specified size. ## Syntax diff --git a/docs/build/reference/fo-object-file-name.md b/docs/build/reference/fo-object-file-name.md index ea78434297..a0be19b447 100644 --- a/docs/build/reference/fo-object-file-name.md +++ b/docs/build/reference/fo-object-file-name.md @@ -1,35 +1,47 @@ --- title: "/Fo (Object file name)" description: "Reference guide to the Microsoft C++ /Fo (Object file name) compiler option in Visual Studio." -ms.date: "04/20/2020" +ms.date: 01/29/2024 f1_keywords: ["/Fo", "VC.Project.VCCLCompilerTool.ObjectFile", "VC.Project.VCCLWCECompilerTool.ObjectFile"] helpviewer_keywords: ["Fo compiler option [C++]", "object files, naming", "/Fo compiler option [C++]", "-Fo compiler option [C++]"] -ms.assetid: 0e6d593e-4e7f-4990-9e6e-92e1dcbcf6e6 --- -# /Fo (Object File Name) +# `/Fo` (Object File Name) Specifies an object (*`.obj`*) file name or directory to be used instead of the default. ## Syntax -> **`/Fo`**_pathname_ +> **`/Fo"pathname"`**\ +> **`/Fo:[ ]"pathname"`** ## Remarks -You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. +You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. Don't put a space between the **`/Fo`** option and the *`pathname`* argument. By default, the object files generated by the compiler are placed in the current directory. They're given the base name of the source file and a *`.obj`* extension. -To use the **`/Fo`** option to rename an object file, specify the output filename as the *pathname* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use *`.obj`*. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. +To use the **`/Fo`** option to rename an object file, specify the output filename as the *`pathname`* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use an *`.obj`* extension. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. -To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *pathname* argument. A directory is indicated by a trailing slash in the *pathname* argument. The specified directory must exist; it's not created automatically. +To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *`pathname`* argument. A directory is indicated by a trailing slash or backslash in the *`pathname`* argument. Use an escaped backslash (a double backslash), if you're using a quoted path. The directory path can be absolute, or relative to the source directory. The specified directory must exist, or the compiler reports error D8003. The directory isn't created automatically. ## Example -The following command line creates an object file named *sample.obj* in an existing directory, *\\intermediate*, on drive D. +This command line demonstrates the format that allows for an optional space between the `/Fo` option and the *`pathname`* argument. It creates an object file named *`test.obj`* in the current directory. ```cmd -CL /Fo"D:\intermediate\" /EHsc /c sample.cpp +CL /Fo: "test" /EHsc /c sample1.cpp +``` + +The following command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`D:\intermediate\`*. It uses escaped backslash characters as path segment separators in a quoted path: + +```cmd +CL /Fo"D:\\intermediate\\" /EHsc /c sample1.cpp sample2.cpp +``` + +This command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`output\`*, relative to the source directory. + +```cmd +CL /Fooutput\ /EHsc /c sample1.cpp sample2.cpp ``` ## Set the option in Visual Studio or programmatically @@ -40,7 +52,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp 1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. -1. Modify the **Object File Name** property to set the output directory. In the IDE, the object file must have an extension of *`.obj`*. +1. Modify the **Object File Name** property to set the output directory. In the IDE, the object files must have an extension of *`.obj`*. ### To set this compiler option programmatically @@ -48,7 +60,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-file (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/force-force-file-output.md b/docs/build/reference/force-force-file-output.md index 1e013395bb..0df90153e1 100644 --- a/docs/build/reference/force-force-file-output.md +++ b/docs/build/reference/force-force-file-output.md @@ -1,44 +1,45 @@ --- -description: "Learn more about: /FORCE (Force File Output)" -title: "/FORCE (Force File Output)" -ms.date: "07/19/2019" -f1_keywords: ["VC.Project.VCLinkerTool.ForceLink", "/force"] +description: "Learn more about: /FORCE (Force file output)" +title: "/FORCE (Force file output)" +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ForceFileOutput", "VC.Project.VCLinkerTool.ForceLink", "/force"] helpviewer_keywords: ["FORCE linker option", "file output in linker", "/FORCE linker option", "-FORCE linker option"] ms.assetid: b1e9a218-a5eb-4e60-a4a4-65b4be15e5da --- -# /FORCE (Force File Output) +# `/FORCE` (Force file output) -``` -/FORCE:[MULTIPLE|UNRESOLVED] -``` +Tells the linker to create an executable even if symbols are undefined or multiply defined. -## Remarks +## Syntax -The /FORCE option tells the linker to create a valid .exe file or DLL even if a symbol is referenced but not defined or is multiply defined. +> **`/FORCE`**\[**`:MULTIPLE`**\|**`:UNRESOLVED`**] -The /FORCE option can take an optional argument: +## Remarks -- Use /FORCE:MULTIPLE to create an output file whether or not LINK finds more than one definition for a symbol. +The **`/FORCE`** linker option tells the linker to create an executable image (EXE file or DLL) even if a symbol is referenced but not defined or is defined more than once. -- Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +> [!IMPORTANT] +> The **`/FORCE`** option can create an executable that crashes or misbehaves at runtime if it references an undefined symbol or, when a multiply defined symbol has different definitions, if it invokes an unexpected definition in context. -/FORCE with no arguments implies both multiple and unresolved. +The **`/FORCE`** option can take an optional argument: -A file created with this option may not run as expected. The linker will not link incrementally when the /FORCE option is specified. +- Use **`/FORCE:MULTIPLE`** to create an output file whether or not LINK finds more than one definition for a symbol. -If a module is compiled with **/clr**, **/FORCE** will not create an image. +- Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. -### To set this linker option in the Visual Studio development environment +**`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. -1. Right-click on the project in **Solution Explorer** and choose **Properties**. +The linker won't link incrementally when the **`/FORCE`** option is specified. -1. Click the **Linker** folder. +If a module is compiled with **`/clr`**, the linker ignores the **`/FORCE`** option. + +### To set this linker option in the Visual Studio development environment -1. Click the **Command Line** property page. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Type the option into the **Additional Options** box. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Modify the **Force File Output** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +47,5 @@ For more information, see [Set C++ compiler and build properties in Visual Studi ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/force-interlocked-functions.md b/docs/build/reference/force-interlocked-functions.md new file mode 100644 index 0000000000..b0fb4df6fa --- /dev/null +++ b/docs/build/reference/force-interlocked-functions.md @@ -0,0 +1,55 @@ +--- +title: "/forceInterlockedFunctions" +description: "Learn more about /forceInterlockedFunctions" +ms.date: 03/07/2025 +--- +# `/forceInterlockedFunctions` + +Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 Large System Extension (LSE) atomic instructions based on CPU capability at runtime. + +## Syntax + +> **`/forceInterlockedFunctions`**[**`-`**] + +## Remarks +When possible, this flag avoids using Armv8.0 load and store exclusive instructions, as these instructions can result in livelocks. +This flag forces the following interlocked intrinsics to be generated as out-of-line functions: + +|Operation|8|16|32|64|128|Pointer| +|-|-------|--------|--------|--------|-------|-------| +|Add|None|None|Full|Full|None|None| +|And|Full|Full|Full|Full|None|None| +|CompareExchange|Full|Full|Full|Full|Full|Full| +|Decrement|None|Full|Full|Full|None|None| +|Exchange|Full|Full|Full|Full|None|Full| +|ExchangeAdd|Full|Full|Full|Full|None|None| +|Increment|None|Full|Full|Full|None|None| +|Or|Full|Full|Full|Full|None|None| +|Xor|Full|Full|Full|Full|None|None| +|bittestandreset|None|None|Full|Full|None|None| +|bittestandset|None|None|Full|Full|None|None| + +Key: + +- **Full**: supports plain, `_acq`, `_rel`, and `_nf` forms. + +- **None**: Not supported + +For more information about interlocked intrinsics, see the "Interlocked intrinsics" section in [Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md). + +### To set the `/forceInterlockedFunctions` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In the **Additional options** box, add *`/forceInterlockedFunctions`* to enable. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also +[Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/fr-fr-create-dot-sbr-file.md b/docs/build/reference/fr-fr-create-dot-sbr-file.md index 18ee204b7f..4090865e8f 100644 --- a/docs/build/reference/fr-fr-create-dot-sbr-file.md +++ b/docs/build/reference/fr-fr-create-dot-sbr-file.md @@ -1,39 +1,40 @@ --- -description: "Learn more about: /FR, /Fr (Create .Sbr File)" -title: "/FR, /Fr (Create .Sbr File)" -ms.date: "11/04/2016" +description: "Learn more about: /FR, /Fr (Name SBR file)" +title: "/FR, /Fr (Name SBR file)" +ms.date: 08/30/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.BrowseInformation", "VC.Project.VCCLCompilerTool.BrowseInformation", "/fr", "VC.Project.VCCLCompilerTool.BrowseInformationFile", "VC.Project.VCCLWCECompilerTool.BrowseInformationFile"] helpviewer_keywords: ["/FR compiler option [C++]", "-FR compiler option [C++]", "FR compiler option [C++]", "symbolic browser information"] ms.assetid: 3fd8f88b-3924-4feb-9393-287036a28896 --- -# /FR, /Fr (Create .Sbr File) +# `/FR`, `/Fr` (Name SBR file) -Creates .sbr files. +Creates *`.sbr`* (source browser) files, used by [Code maps](/visualstudio/modeling/code-maps-for-cpp), BSCMAKE, and some third-party code browsing tools. ## Syntax -``` -/FR[pathname[\filename]] -/Fr[pathname[\filename]] -``` +> **`/FR`**\[*`pathname`*\[*`\filename`*]]\ +> **`/Fr`**\[*`pathname`*\[*`\filename`*]] -## Remarks +### Arguments + +*`pathname`*\ +The optional destination directory for the generated *`.sbr`* files. If this value isn't specified, the files are created in the default output directory. For more information, see [Specifying the pathname](specifying-the-pathname.md). -> [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server .sdf file in the solution folder. +*`filename`*\ +An optional filename for the generated *`.sbr`* file. If this value isn't specified, the compiler uses the base name of the source file with a *`.sbr`* extension. For more information, see [Specifying the pathname](specifying-the-pathname.md). -During the build process, the Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses these files to create a .BSC file, which is used to display browse information. +## Remarks -**/FR** creates an .sbr file with complete symbolic information. +**`/FR`** creates an *`.sbr`* file with complete symbolic information. -**/Fr** creates an .sbr file without information on local variables. +**`/Fr`** creates an *`.sbr`* file without information on local variables. **`/Fr`** is deprecated; use **`/FR`** instead. For more information, see the Deprecated and removed compiler options section in [Compiler options listed by category](compiler-options-listed-by-category.md). -If you do not specify `filename`, the .sbr file gets the same base name as the source file. +The Visual Studio [Code Maps](/visualstudio/modeling/code-maps-for-cpp) feature requires the *`.sbr`* files generated by **`/FR`**. -**/Fr** is deprecated; use **/FR** instead. For more information, see Deprecated and Removed Compiler Options in [Compiler Options Listed by Category](compiler-options-listed-by-category.md). +The Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses *`.sbr`* files to create a *`.bsc`* file, used to display browse information in some third-party tools. For more information, see [BSCMAKE reference](bscmake-reference.md). > [!NOTE] -> Do not change the .sbr extension. BSCMAKE requires the intermediary files to have that extension. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server SDF file in the solution folder. If you use BSCMAKE, don't change the *`.sbr`* extension. BSCMAKE requires the intermediate files to have that extension. ### To set this compiler option in the Visual Studio development environment @@ -49,7 +50,7 @@ If you do not specify `filename`, the .sbr file gets the same base name as the s ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-File (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/fsanitize.md b/docs/build/reference/fsanitize.md index 8106ba7c22..6e9e8c9439 100644 --- a/docs/build/reference/fsanitize.md +++ b/docs/build/reference/fsanitize.md @@ -1,8 +1,8 @@ --- description: "Learn more about the /fsanitize (enable sanitizers) compiler option" title: "/fsanitize (Enable sanitizers)" -ms.date: 09/15/2021 -f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize=fuzzer", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib"] +ms.date: 02/17/2022 +f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize=fuzzer", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib", "VC.Project.VCCLCompilerTool.EnableASAN"] helpviewer_keywords: ["/fsanitize [C++]", "-fsanitize=address [C++]", "address sanitizer compiler option [C++]", "/fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib"] --- # `/fsanitize` (Enable sanitizers) @@ -12,19 +12,24 @@ Use the **`/fsanitize`** compiler options to enable sanitizers. ## Syntax > **`/fsanitize=address`**\ +> **`/fsanitize=kernel-address`**\ > **`/fsanitize=fuzzer`**\ > **`/fsanitize-address-use-after-return`**\ > **`/fno-sanitize-address-vcasan-lib`** +> **`/fsanitize-address-asan-compat-lib`** +> **`/fno-sanitize-address-asan-compat-lib`** ## Remarks The **`/fsanitize=address`** compiler option enables [AddressSanitizer](../../sanitizers/asan.md), a powerful compiler and runtime technology to uncover [hard-to-find bugs](../../sanitizers/asan.md#error-types). Support for the **`/fsanitize=address`** option is available starting in Visual Studio 2019 version 16.9. -The **`/fsanitize=fuzzer`** compiler option enables experimental support for [LibFuzzer](https://releases.llvm.org/3.8.0/docs/LibFuzzer.html). LibFuzzer is a coverage-guided fuzzing library that can be used to find bugs and crashes caused by user-provided input. We recommended you use **`/fsanitize=address`** with LibFuzzer. This option is useful for fuzzing tools such as OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). Support for the **`/fsanitize=fuzzer`** option is available starting in Visual Studio 2022 version 17.0. +The **`/fsanitize=kernel-address`** compiler option enables [Kernel AddressSanitizer (KASan)](/windows-hardware/drivers/devtest/kasan). KASan is the kernel-mode variant of AddressSanitizer, available starting in Visual Studio 2022 version 17.11. KASan is only supported on Windows 11 24H2 or Windows Server 2025 and higher, and requires building using a Windows SDK 10.0.26100.2161 and higher. Building with KASan also implies the **`/fsanitize-address-asan-compat-lib`** compiler option. + +The **`/fsanitize=fuzzer`** compiler option enables experimental support for [LibFuzzer](https://llvm.org/docs/LibFuzzer.html). LibFuzzer is a coverage-guided fuzzing library that can be used to find bugs and crashes caused by user-provided input. We recommended you use **`/fsanitize=address`** with LibFuzzer. This option is useful for fuzzing tools such as OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). Support for the **`/fsanitize=fuzzer`** option is available starting in Visual Studio 2022 version 17.0. The **`/fsanitize`** option doesn't allow comma-separated syntax, for example: **`/fsanitize=address,fuzzer`**. These options must be specified individually. -The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasan-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). +The **`/fsanitize-address-use-after-return`**, **`/fno-sanitize-address-vcasan-lib`**, **`/fsanitize-address-asan-compat-lib`**, and **`/fno-sanitize-address-asan-compat-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). ### To set the **`/fsanitize=address`** compiler option in the Visual Studio development environment diff --git a/docs/build/reference/functionpadmin-create-hotpatchable-image.md b/docs/build/reference/functionpadmin-create-hotpatchable-image.md index 3795500ad1..98057d1ebd 100644 --- a/docs/build/reference/functionpadmin-create-hotpatchable-image.md +++ b/docs/build/reference/functionpadmin-create-hotpatchable-image.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: /FUNCTIONPADMIN (Create Hotpatchable Image)" -title: "/FUNCTIONPADMIN (Create Hotpatchable Image)" -ms.date: "03/09/2018" -f1_keywords: ["/functionpadmin"] +description: "Learn more about: /FUNCTIONPADMIN (Create hotpatchable image)" +title: "/FUNCTIONPADMIN (Create hotpatchable image)" +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CreateHotPatchableImage", "/functionpadmin"] helpviewer_keywords: ["-FUNCTIONPADMIN linker option", "/FUNCTIONPADMIN linker option"] ms.assetid: 25b02c13-1add-4fbd-add9-fcb30eb2cae7 --- -# /FUNCTIONPADMIN (Create Hotpatchable Image) +# `/FUNCTIONPADMIN` (Create hotpatchable image) -Prepares an image for hotpatching. +Tells the linker to prepare an executable image for hot patching. ## Syntax -> **/FUNCTIONPADMIN**[**:**_space_] +> **`/FUNCTIONPADMIN`**[**`:`***`size`*] ### Arguments -*space*
-The amount of padding to add to the beginning of each function in bytes. On x86 this defaults to 5 bytes of padding and on x64 this defaults to 6 bytes. On other targets a value must be provided. +*`size`*\ +The amount of padding to add to the beginning of each function in bytes. On x86 the default is 5 bytes of padding and on x64 the default is 6 bytes. On other targets a value must be provided. ## Remarks -In order for the linker to produce a hotpatchable image, the .obj files must have been compiled with [/hotpatch (Create Hotpatchable Image)](hotpatch-create-hotpatchable-image.md). +In order for the linker to produce a hotpatchable image, the *`.obj`* files must be compiled by using the [`/hotpatch` (Create hotpatchable image)](hotpatch-create-hotpatchable-image.md) compiler option. -When you compile and link an image with a single invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. +When you compile and link an image with a single invocation of cl.exe, **`/hotpatch`** implies **`/FUNCTIONPADMIN`**. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the **/FUNCTIONPADMIN** option in **Additional Options**. Choose **OK** to save your changes. +1. Modify the **Create Hot Patchable Image** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +39,5 @@ When you compile and link an image with a single invocation of cl.exe, **/hotpat ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/gd-gr-gv-gz-calling-convention.md b/docs/build/reference/gd-gr-gv-gz-calling-convention.md index 834a53189c..50380ebb09 100644 --- a/docs/build/reference/gd-gr-gv-gz-calling-convention.md +++ b/docs/build/reference/gd-gr-gv-gz-calling-convention.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" title: "/Gd, /Gr, /Gv, /Gz (Calling Convention)" -ms.date: "09/05/2018" +description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" +ms.date: 09/05/2018 f1_keywords: ["/Gr", "/Gv", "/Gd", "VC.Project.VCCLCompilerTool.CallingConvention"] helpviewer_keywords: ["-Gd compiler option [C++]", "-Gv compiler option [C++]", "/Gv compiler option [C++]", "-Gr compiler option [C++]", "Gd compiler option [C++]", "Gr compiler option [C++]", "/Gz compiler option [C++]", "-Gz compiler option [C++]", "/Gd compiler option [C++]", "Gz compiler option [C++]", "Gv compiler option [C++]", "/Gr compiler option [C++]"] -ms.assetid: fd3110cb-2d77-49f2-99cf-a03f9ead00a3 --- # /Gd, /Gr, /Gv, /Gz (Calling Convention) @@ -44,7 +43,7 @@ For more information about calling conventions, see [Calling Conventions](../../ On x86 processors, all function arguments are passed on the stack from right to left. On ARM and x64 architectures, some arguments are passed by register and the rest are passed on the stack from right to left. The calling routine pops the arguments from the stack. -For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore ( `_` ); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). +For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore (`_`); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). ## __fastcall Specifics diff --git a/docs/build/reference/general-property-page-file.md b/docs/build/reference/general-property-page-file.md index 5b9b42230a..f4dc2206c6 100644 --- a/docs/build/reference/general-property-page-file.md +++ b/docs/build/reference/general-property-page-file.md @@ -21,7 +21,7 @@ When you right-click on a file node **Solution Explorer**, the **General** prope - **Item Type** - The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. See [Specifying Custom Build Tools](../specifying-custom-build-tools.md) for more information. You can also use this property page to specify that a file is not part of the build process. + The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. For more information, see [Specifying Custom Build Tools](../specifying-custom-build-tools.md). You can also use this property page to specify that a file is not part of the build process. The following illustration shows the property page for a *.cpp* file. The default **Item Type** for this kind of file is the **C/C++ Compiler** (*cl.exe*) and the property page exposes various compiler settings that can be applied to this file only. diff --git a/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md b/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md index e77bc2bfd9..37657efee2 100644 --- a/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md +++ b/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" title: "/GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" -ms.date: 04/14/2021 +description: "Learn more about: /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" +ms.date: 03/27/2025 f1_keywords: ["GENPROFILE", "FASTGENPROFILE", "/GENPROFILE", "/FASTGENPROFILE"] helpviewer_keywords: ["GENPROFILE", "FASTGENPROFILE"] --- @@ -12,7 +12,7 @@ Specifies generation of a *`.pgd`* file by the linker to support profile-guided ## Syntax > **`/GENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]]\ -> **`/FASTGENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]]\ +> **`/FASTGENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]] > *`profile-argument`*\ >  { **`COUNTER32`** | **`COUNTER64`** }\ @@ -43,7 +43,7 @@ Use **`PATH`** to specify a separate set of PGO counters for each unique path t Specifies whether to use extra counters to keep an accurate count when exceptions are thrown during training. Use **`TRACKEH`** to specify extra counters for an exact count. Use **`NOTRACKEH`** to specify single counters for code that doesn't use exception handling or that doesn't run into exceptions in your training scenarios. When you specify **`/GENPROFILE`**, the default is **`TRACKEH`** . When you specify **`/FASTGENPROFILE`**, the default is **`NOTRACKEH`** . **`PGD`**=*filename*\ -Specifies a base file name for the *`.pgd`* file. By default, the linker uses the base executable image file name with a *`.pgd`* extension. +Specifies a base filename for the *`.pgd`* file. By default, the linker uses the base executable image filename with a *`.pgd`* extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks diff --git a/docs/build/reference/gh-enable-penter-hook-function.md b/docs/build/reference/gh-enable-penter-hook-function.md index 12a83774da..fbf4459ec3 100644 --- a/docs/build/reference/gh-enable-penter-hook-function.md +++ b/docs/build/reference/gh-enable-penter-hook-function.md @@ -1,7 +1,7 @@ --- title: "/Gh (Enable _penter hook function)" description: "Describes the /Gh compiler option to call the supplied _penter function." -ms.date: "07/06/2020" +ms.date: 06/29/2022 f1_keywords: ["_penter"] helpviewer_keywords: ["/Gh compiler option [C++]", "Gh compiler option [C++]", "_penter function", "-Gh compiler option [C++]"] ms.assetid: 1510a082-8a0e-486e-a309-6add814b494f @@ -42,6 +42,8 @@ This declaration isn't available for 64-bit projects. The following code, when compiled with **/Gh**, shows how `_penter` is called twice; once when entering function `main` and once when entering function `x`. The example consists of two source files, which you compile separately. +Source file `local_penter.cpp`: + ```cpp // local_penter.cpp // compile with: cl /EHsc /c local_penter.cpp @@ -74,6 +76,8 @@ extern "C" void __declspec(naked) __cdecl _penter( void ) { } ``` +Source file `Gh_compiler_option.cpp`: + ```cpp // Gh_compiler_option.cpp // compile with: cl /EHsc /Gh Gh_compiler_option.cpp local_penter.obj @@ -90,7 +94,6 @@ int main() { When run, the local `_penter` function is called on entry to `main` and `x`: ```Output - In a function! In a function! ``` diff --git a/docs/build/reference/gs-buffer-security-check.md b/docs/build/reference/gs-buffer-security-check.md index 227124b814..41fe1b082c 100644 --- a/docs/build/reference/gs-buffer-security-check.md +++ b/docs/build/reference/gs-buffer-security-check.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /GS (Buffer Security Check)" title: "/GS (Buffer Security Check)" -ms.date: "11/04/2016" +description: "Learn more about: /GS (Buffer Security Check)" +ms.date: 11/04/2016 f1_keywords: ["VC.Project.VCCLWCECompilerTool.BufferSecurityCheck", "VC.Project.VCCLCompilerTool.BufferSecurityCheck"] helpviewer_keywords: ["buffers [C++], buffer overruns", "buffer overruns, compiler /GS switch", "GS compiler option [C++]", "/GS compiler option [C++]", "security check compiler option [C++]", "-GS compiler option [C++]", "buffers [C++], avoiding overruns"] -ms.assetid: 8d8a5ea1-cd5e-42e1-bc36-66e1cd7e731e --- # /GS (Buffer Security Check) @@ -29,11 +28,8 @@ On functions that the compiler recognizes as subject to buffer overrun problems, A buffer overrun security check is performed on a *GS buffer*. A GS buffer can be one of these: - An array that is larger than 4 bytes, has more than two elements, and has an element type that is not a pointer type. - - A data structure whose size is more than 8 bytes and contains no pointers. - -- A buffer allocated by using the [_alloca](../../c-runtime-library/reference/alloca.md) function. - +- A buffer allocated by using the [`_alloca`](../../c-runtime-library/reference/alloca.md) function. - Any class or structure that contains a GS buffer. For example, the following statements declare GS buffers. @@ -57,16 +53,14 @@ struct { int a; int b; }; ## Initialize the Security Cookie -The **/GS** compiler option requires that the security cookie be initialized before any function that uses the cookie is run. The security cookie must be initialized immediately on entry to an EXE or DLL. This is done automatically if you use the default VCRuntime entry points: mainCRTStartup, wmainCRTStartup, WinMainCRTStartup, wWinMainCRTStartup, or _DllMainCRTStartup. If you use an alternate entry point, you must manually initialize the security cookie by calling [__security_init_cookie](../../c-runtime-library/reference/security-init-cookie.md). +The **/GS** compiler option requires that the security cookie be initialized before any function that uses the cookie is run. The security cookie must be initialized immediately on entry to an EXE or DLL. This is done automatically if you use the default VCRuntime entry points: `mainCRTStartup`, `wmainCRTStartup`, `WinMainCRTStartup`, `wWinMainCRTStartup`, or `_DllMainCRTStartup`. If you use an alternate entry point, you must manually initialize the security cookie by calling [`__security_init_cookie`](../../c-runtime-library/reference/security-init-cookie.md). ## What Is Protected The **/GS** compiler option protects the following items: - The return address of a function call. - - The address of an exception handler for a function. - - Vulnerable function parameters. On all platforms, **/GS** attempts to detect buffer overruns into the return address. Buffer overruns are more easily exploited on platforms such as x86 and x64, which use calling conventions that store the return address of a function call on the stack. @@ -80,15 +74,10 @@ A vulnerable parameter is allocated before the cookie and local variables. A buf The compiler does not make copies of vulnerable parameters in the following situations: - Functions that do not contain a GS buffer. - -- Optimizations ([/O options](o-options-optimize-code.md)) are not enabled. - +- Optimizations ([`/O` options](o-options-optimize-code.md)) are not enabled. - Functions that have a variable argument list (...). - - Functions that are marked with [naked](../../cpp/naked-cpp.md). - - Functions that contain inline assembly code in the first statement. - - A parameter is used only in ways that are less likely to be exploitable in the event of a buffer overrun. ## What Is Not Protected @@ -100,9 +89,7 @@ Even if you use **/GS**, always try to write secure code that has no buffer over ### To set this compiler option in Visual Studio 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. - 1. Modify the **Buffer Security Check** property. ### To set this compiler option programmatically @@ -138,5 +125,5 @@ int main() { ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/gs-control-stack-checking-calls.md b/docs/build/reference/gs-control-stack-checking-calls.md index f681a54a15..4e1ff0eb87 100644 --- a/docs/build/reference/gs-control-stack-checking-calls.md +++ b/docs/build/reference/gs-control-stack-checking-calls.md @@ -1,44 +1,44 @@ --- description: "Learn more about: /Gs (Control Stack Checking Calls)" title: "/Gs (Control Stack Checking Calls)" -ms.date: "10/25/2018" +ms.date: 02/16/2023 f1_keywords: ["/GS"] helpviewer_keywords: ["disabling stack probes", "GS compiler option [C++]", "/GS compiler option [C++]", "stack, stack probes", "stack probes", "-GS compiler option [C++]", "stack checking calls"] ms.assetid: 40daed7c-f942-4085-b872-01e12b37729e --- -# /Gs (Control Stack Checking Calls) +# `/Gs` (Control stack checking calls) Controls the threshold for stack probes. ## Syntax -> **/Gs**[*size*] +> **`/Gs`**[*`size`*] ## Arguments -*size*
-(Optional) The number of bytes that local variables can occupy before a stack probe is initiated. No space is allowed between **/Gs** and *size*. +*`size`*\ +(Optional) The number of bytes that local variables can occupy before a stack probe is initiated. No whitespace is allowed between **`/Gs`** and *`size`*. ## Remarks -A *stack probe* is a sequence of code that the compiler inserts at the beginning of a function call. When initiated, a stack probe reaches benignly into memory by the amount of space that is required to store the function's local variables. This causes the operating system to transparently page in additional stack memory if required, before the rest of the function runs. +A *stack probe* is a sequence of code that the compiler inserts at the beginning of a function call. When initiated, a stack probe reaches benignly into memory by the amount of space required to store the function's local variables. This probe causes the operating system to transparently page in more stack memory if necessary, before the rest of the function runs. -By default, the compiler generates code that initiates a stack probe when a function requires more than one page of stack space. This is equivalent to a compiler option of **/Gs4096** for x86, x64, ARM, and ARM64 platforms. This value allows an application and the Windows memory manager to increase the amount of memory committed to the program stack dynamically at run time. +By default, the compiler generates code that initiates a stack probe when a function requires more than one page of stack space. This default is equivalent to a compiler option of **`/Gs4096`** for x86, x64, ARM, and ARM64 platforms. This value allows an application and the Windows memory manager to increase the amount of memory committed to the program stack dynamically at run time. > [!NOTE] -> The default value of **/Gs4096** allows the program stack of applications for Windows to grow correctly at run time. We recommend that you do not change the default value unless you know exactly why you have to change it. +> The default value of **`/Gs4096`** allows the program stack of applications for Windows to grow correctly at run time. We recommend that you do not change the default value unless you know exactly why you have to change it. -Some programs—for example, virtual device drivers—do not require this default stack-growth mechanism. In such cases, the stack probes are not necessary and you can stop the compiler from generating them by setting *size* to a value that is larger than any function will require for local variable storage. +Some programs—for example, virtual device drivers—don't require this default stack-growth mechanism. In such cases, the stack probes aren't necessary and you can stop the compiler from generating them by setting *`size`* to a value that is larger than any function requires for local variable storage. -**/Gs0** initiates stack probes for every function call that requires storage for local variables. This can have a negative impact on performance. +**`/Gs0`** initiates stack probes for every function call that requires storage for local variables. This value can have a negative impact on performance. -For x64 targets, if the **/Gs** option is specified without a *size* argument, it is the same as **/Gs0**. If the *size* argument is 1 through 9, warning D9014 is emitted, and the effect is the same as specifying **/Gs0**. +For x64 targets, if you specify the **`/Gs`** option without a *`size`* argument, it's the same as **`/Gs0`**. If the *`size`* argument is 1 through 9, the compiler emits warning D9014, and the effect is the same as specifying **`/Gs0`**. -For x86, ARM, and ARM64 targets, the **/Gs** option without a *size* argument is the same as **/Gs4096**. If the *size* argument is 1 through 9, warning D9014 is emitted, and the effect is the same as specifying **/Gs4096**. +For x86, ARM, and ARM64 targets, the **`/Gs`** option without a *`size`* argument is the same as **`/Gs4096`**. If the *`size`* argument is 1 through 9, the compiler emits warning D9014, and the effect is the same as specifying **`/Gs4096`**. -For all targets, a *size* argument between 10 and 2147485647 sets the threshold at the specified value. A *size* of 2147485648 or greater causes fatal error C1049. +For all targets, a *`size`* argument between 10 and 2147483647 sets the threshold at the specified value. A *`size`* of 2147483648 or greater causes fatal error C1049. -You can turn stack probes on or off by using the [check_stack](../../preprocessor/check-stack.md) directive. **/Gs** and the `check_stack` pragma have no effect on standard C library routines; they affect only the functions you compile. +You can turn stack probes on or off by using the [`check_stack`](../../preprocessor/check-stack.md) directive. **`/Gs`** and the `check_stack` pragma have no effect on standard C library routines; they affect only the functions you compile. ### To set this compiler option in the Visual Studio development environment @@ -54,5 +54,5 @@ You can turn stack probes on or off by using the [check_stack](../../preprocesso ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/guard-enable-control-flow-guard.md b/docs/build/reference/guard-enable-control-flow-guard.md index b4d970ac8c..61a24b9f5a 100644 --- a/docs/build/reference/guard-enable-control-flow-guard.md +++ b/docs/build/reference/guard-enable-control-flow-guard.md @@ -1,47 +1,48 @@ --- description: "Learn more about: /guard (Enable Control Flow Guard)" title: "/guard (Enable Control Flow Guard)" -ms.date: "11/04/2016" +ms.date: 2/24/2025 f1_keywords: ["/guard", "VC.Project.VCCLCompilerTool.ControlFlowGuard"] -ms.assetid: be495323-f59f-4cf3-a6b6-8ee69e6a19dd --- -# /guard (Enable Control Flow Guard) +# `/guard` (Enable Control Flow Guard) Enable compiler generation of Control Flow Guard security checks. ## Syntax -``` -/guard:cf[-] -``` +> **`/guard:cf`**\ +> **`/guard:cf-`** ## Remarks -The **/guard:cf** option causes the compiler to analyze control flow for indirect call targets at compile time, and then to insert code to verify the targets at runtime. By default, **/guard:cf** is off and must be explicitly enabled. To explicitly disable this option, use **/guard:cf-**. +The **`/guard:cf`** option causes the compiler to analyze control flow for indirect call targets at compile time, and inserts code at runtime to verify the targets. By default, **`/guard:cf`** is off and must be explicitly enabled. To explicitly disable this option, use **`/guard:cf-`**. **Visual Studio 2017 and later**: This option adds guards for **`switch`** statements that generate jump tables. -When the **/guard:cf** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. +When the **`/guard:cf`** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. -A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks do not fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. +A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This technique can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks don't fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. -The **/guard:cf** option must be passed to both the compiler and linker to build code that uses the CFG exploit mitigation technique. If your binary is built by using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, the option must be set on both the compiler and linker commands. The /DYNAMICBASE linker option is also required. To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. +To use the CFG exploit mitigation technique, pass **`/guard:cf`** to the compiler and **`/GUARD:CF`** to the linker. -The **/guard:cf** option is incompatible with [/ZI](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [/clr](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). +To disable the CFG exploit mitigation technique, pass **`/guard:cf-`** to the compiler **`/GUARD:NO`** to the linker. -Code compiled by using **/guard:cf** can be linked to libraries and object files that are not compiled by using the option. Only this code, when also linked by using the **/guard:cf** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option will not stop an attack, we recommend that you use the option on all the code you compile. There is a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. +If you build using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, set the option for both the compiler and linker commands. The `/DYNAMICBASE` linker option is also required. -### To set this compiler option in the Visual Studio development environment +To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +The **`/guard:cf`** option is incompatible with [`/ZI`](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [`/clr`](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). -1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +Code compiled by using **`/guard:cf`** can be linked to libraries and object files that aren't compiled by using the option. Only this code, when also linked by using the **`/guard:cf`** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option won't stop an attack, we recommend that you use the option on all the code you compile. There's a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. -1. Select the **Control Flow Guard** property. +### To set this compiler option in the Visual Studio development environment +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +1. Select the **Control Flow Guard** property. 1. In the dropdown control, choose **Yes** to enable Control Flow Guard, or **No** to disable it. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/guard-enable-guard-checks.md b/docs/build/reference/guard-enable-guard-checks.md index 85afea2c3c..3df932fa31 100644 --- a/docs/build/reference/guard-enable-guard-checks.md +++ b/docs/build/reference/guard-enable-guard-checks.md @@ -1,37 +1,41 @@ --- -description: "Learn more about: /GUARD (Enable Guard Checks)" +description: "Learn more about: /GUARD (Enable Guard Checks) linker option" title: "/GUARD (Enable Guard Checks)" -ms.date: "11/04/2016" +ms.date: 09/21/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.LinkControlFlowGuard"] ms.assetid: 72758e23-70ac-4616-94d7-d767477406d1 --- -# /GUARD (Enable Guard Checks) +# `/GUARD` (Enable Guard Checks) -Specifies support for Control Flow Guard checks in the executable image. +Tells the linker whether to support Control Flow Guard checks in the executable image. ## Syntax -``` -/GUARD:{CF|NO} -``` +> **`/GUARD:CF`**\ +> **`/GUARD:NO`** ## Remarks -When /GUARD:CF is specified, the linker modifies the header of a .dll or .exe to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, /GUARD:CF is disabled. It can be explicitly disabled by using /GUARD:NO. To be effective, /GUARD:CF also requires the [/DYNAMICBASE (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. +The **`/GUARD:CF`** linker option modifies the header of a DLL or EXE file to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, **`/GUARD:CF`** is disabled. It can be explicitly disabled by using **`/GUARD:NO`**. To be effective, **`/GUARD:CF`** also requires the [`/DYNAMICBASE` (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. -When source code is compiled by using the [/guard:cf](guard-enable-control-flow-guard.md) option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. +When source code is compiled by using the [`/guard:cf`](guard-enable-control-flow-guard.md) compiler option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This check makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. -The /GUARD:CF option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using /GUARD:CF incurs the cost of runtime checks, but does not enable CFG protection. When the /GUARD:CF option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the /GUARD:CF option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. +The **`/GUARD:CF`** option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using **`/GUARD:CF`** incurs the cost of runtime checks, but doesn't enable CFG protection. When the **`/guard:cf`** option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the **`/GUARD:CF`** option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter `/GUARD:CF`. +1. In **Additional Options**, enter *`/GUARD:CF`*. Choose **OK** or **Apply** to save your changes. + +### To set this linker option programmatically + +- See . ## See also -[/guard (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)
-[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[`/guard` (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/header-unit-json-reference.md b/docs/build/reference/header-unit-json-reference.md new file mode 100644 index 0000000000..cc0a1bf2c5 --- /dev/null +++ b/docs/build/reference/header-unit-json-reference.md @@ -0,0 +1,115 @@ +--- +description: "Reference for header-units.json file" +title: "C++ header unit.json reference" +ms.date: 11/09/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["header-units.json"] +helpviewer_keywords: ["header-units.json", "header unit"] +monikerRange: '>=msvc-160' +--- + +# C++ header-units.json reference + +The `header-units.json` file serves two purposes: +- Specify which header files can be translated into header units when [`/translateInclude`](translateinclude.md) is specified. +- Minimize duplicated symbols to increase build throughput. + +This file must be in the same directory as the included header file. This file is only used when [`/translateInclude`](translateinclude.md) is specified along with either [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies:directives`](sourcedependencies-directives.md). + +## Rationale + +Some header files can't be safely translated to header units. Header files that depend on macros that aren't defined on the command line, or that aren't defined in the header files included by the header, can't be translated to header units. + +If a header defines macros that affect whether other headers are included, it can't be safely translated. For example, given `a.h`, `b.h` and `macros.h`, which are all in the same directory: + +```cpp +// a.h + +#include "macros.h" // #defines MACRO=1 +#ifdef MACRO +#include "b.h" +#endif +``` + +The `header-units.json` in this directory can contain `a.h` and `b.h`, but not `macros.h`. The `header-units.json` for this example would be similar to this: + +```json +{ + "Version": "1.0", + "BuildAsHeaderUnits": [ + // macros.h should not be listed + "a.h", + "b.h" + ] +} +``` + +The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) might not be compiled yet for `macros.h`. In that case, `MACRO` won't be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Since it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file. + +To avoid this problem, when there's a dependency on a macro in another header file, the header file that defines the macro is excluded from the list of files that can be compiled into a header unit. This way the header file that defines the macro is treated as a normal `#include` and `MACRO` will be visible so that `b.h` is included and listed as one of the dependencies. + +### Preventing duplicated symbols + +The `header-units.json` file is also important because it allows for automatic header unit creation without duplicated symbols. It does this by creating "atomic" header units for the files listed in `header-units.json`. The imported header units don't contain duplicated symbols from the various `#include` directives that were processed while translating the header file. + +For example, consider two header files that both include a common header file. Both header files are included by the same source file: + +```cpp +// a.h +#include "b.h" + +// c.h +#include "b.h" + +// Source.cpp +import "a.h"; +import "c.h"; +``` + +If the compiler built header units for `a.h`, `b.h` and `c.h`, then the compiled header units `a.h.ifc`, `b.h.ifc`, and `c.h.ifc` would each contain all of the types from `b.h`. Compiling `Source.cpp`, which imports both `a.h` and `c.h`, would require the compiler to deduplicate the `b.h` types, which would impact build performance. + +But if there's a `header-units.json` in the `b.h` directory, and `/translateInclude` is specified, then the following happens: + +1. The scan of `a.h` and `c.h` lists `b.h` as a header unit import in the dependency scan files generated by the compiler. +1. The build system reads the dependency scan files and determines to build `b.h.ifc` first. +1. Then the build system adds `/headerUnit` for `b.h.ifc` to the command lines for compiling `a.h` and `c.h`. It calls the compiler to build the header units `a.h.ifc` and `c.h.ifc`. Because `/translateInclude` is specified, and `/headerUnit for b.h.ifc` is also specified, `a.h.ifc` and `c.h.ifc` won't contain `b.h` types, so there won't be any duplication in the produced header units. + +## Schema + +There's a `headerunits.json` file for the Standard Template Library (STL) headers. The build system uses it to determine whether to create a header unit for an STL header file, and for its dependencies. If the STL header file isn't on the list, it's treated as a normal `#include` instead of importing it as a header unit. + +You can see the `header-units.json` file under the installation directory for Visual Studio. For example: `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json` + +The `header-units.json` file starts with the schema version, followed by an array of filenames for headers that can be built into header units. + +The schema also supports comments, as shown here: + +```json +{ + "Version": "1.0", + "BuildAsHeaderUnits": [ + // "__msvc_all_public_headers.hpp", // for testing, not production + "__msvc_system_error_abi.hpp", + "__msvc_tzdb.hpp", + "__msvc_xlocinfo_types.hpp", + "algorithm", + "any", + "array", + "atomic", + "barrier", + "bit", + "bitset", + // "cassert", // design is permanently incompatible with header units + ... +} +``` + +## Search rules + +The compiler looks for this file in the same directory as the header file being processed. If your library is organized into subdirectories, each subdirectory needs its own `header-units.json` file. + +## See also + +[Walkthrough: Import STL libraries as header units](..\walkthrough-import-stl-header-units.md#approach1)\ +[Walkthrough: Build and import header units in your Visual C++ projects](..\walkthrough-header-units.md) \ No newline at end of file diff --git a/docs/build/reference/headername.md b/docs/build/reference/headername.md index 25bb89d596..2f7824ddfb 100644 --- a/docs/build/reference/headername.md +++ b/docs/build/reference/headername.md @@ -1,7 +1,7 @@ --- title: "/headerName (Build a header unit from the specified header)" description: "Use the /headerName compiler option to establish a mapping between a header file and the header unit to build." -ms.date: 04/13/2021 +ms.date: 11/16/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/headerName"] @@ -23,30 +23,32 @@ The name of a header file that the compiler should compile into a header unit (* ## Remarks -The **`/headerName`** compiler option is available starting in Visual Studio 2019 version 16.10. +The **`/headerName:quote`** and **`/headerName:angle`** compiler options are available starting in Visual Studio 2019 version 16.10. -The **`/headerName`** compiler option, in all its forms, requires the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).\ -If you specify **`/headerName:{quote,angle}`**, you must also specify [`/exportHeader`](module-exportheader.md). +The **`/headerName`** compiler options, in all their forms, require the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).\ +If you specify a **`/headerName`** option, you must also specify [`/exportHeader`](module-exportheader.md). -**`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-name"` and builds it as a header unit (*`.ifc`* file).\ -**`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-filename"` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). + +For more information about the path searching rules for included files in quotes or angle brackets, see [`#include` directive](../../preprocessor/hash-include-directive-c-cpp.md). ### Examples -Given a project that references a header file it defines called `m.h`, the compiler option to compile it into a header unit looks similar to this: +Given a project that references a header file it defines called *`m.h`*, the compiler option to compile it into a header unit looks similar to this example: -```Bash +```bash cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj ``` -The `/headerName:{quote,angle}` option acts like a flag and does not explicitly need an argument. The following examples are valid: +The **`/headerName:quote`** and **`/headerName:angle`** options act like a flag and don't need an argument. The following examples are valid: -```Bash +```bash cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h ``` -You can specify multiple `/headerName` options on the same command line, and every argument after that option will be processed with the specified *`header-filename`* lookup rules. The following example processes all the headers as the previous two command line examples in the same way. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: +You can specify multiple **`/headerName`** options on the same command line. Every argument after a **`/headerName`** option is processed with the specified include file lookup rules for quotes or angle brackets until the next **`/headerName`** option. The following example processes all the headers as the previous two command line examples in the same way as before. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include `, `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: ```bash cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h @@ -55,19 +57,19 @@ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algo ### To set this compiler option in the Visual Studio development environment > [!NOTE] -> Users don't typically set this command line option. It's set by the build system. +> You normally shouldn't set this option in the Visual Studio development environment. It's set by the build system. 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Set the **Configuration** drop-down to **All Configurations**. +1. Set the **Configuration** drop-down to **All Configurations**. Set the **Platform** drop-down to **All Platforms**. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to add the *`/headerName`* options and arguments. Then, choose **OK** or **Apply** to save your changes. +1. Modify the **Additional Options** property to add the *`/headerName:quote`* or *`/headerName:angle`* options and the header filenames the options apply to. Then, choose **OK** or **Apply** to save your changes. ## See also [`/exportHeader` (Create header units)](module-exportheader.md)\ -[`/headerUnit` (Create header units)](headerunit.md)\ +[`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md index 8b92219208..6ee2d63554 100644 --- a/docs/build/reference/headerunit.md +++ b/docs/build/reference/headerunit.md @@ -1,7 +1,7 @@ --- title: "/headerUnit (Use header unit IFC)" description: "Use the /headerUnit compiler option to associate a header file with the header unit to import in its place." -ms.date: 04/13/2021 +ms.date: 5/28/2024 f1_keywords: ["/headerUnit"] helpviewer_keywords: ["/headerUnit", "Use header unit IFC"] author: "tylermsft" @@ -9,13 +9,13 @@ ms.author: "twhitney" --- # `/headerUnit` (Use header unit IFC) -Used to import a header unit. Tells the compiler where to find the *`.ifc`* file (the binary representation of the header unit) for the specified header. +Imports a header unit. Tells the compiler where to find the *`.ifc`* file (the binary representation of the header unit) for the specified header. ## Syntax > **`/headerUnit`** *`header-filename`*=*`ifc-filename`*\ -> **`/headerUnit:quote`** \[*`header-filename`*=*`ifc-filename`*\]\ -> **`/headerUnit:angle`** \[*`header-filename`*=*`ifc-filename`*\] +> **`/headerUnit:quote`** *`header-filename`*=*`ifc-filename`*\ +> **`/headerUnit:angle`** *`header-filename`*=*`ifc-filename`* ### Arguments @@ -27,34 +27,34 @@ The name of a file that contains compiled header unit information. To import mor ## Remarks -The **`/headerUnit`** compiler option requires the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**). +The **`/headerUnit`** compiler option requires [`/std:c++20`](std-specify-language-standard-version.md) or later. -The **`/headerUnit`** compiler option is available starting in Visual Studio 2019 version 16.10. +The **`/headerUnit`** compiler option is available in Visual Studio 2019 version 16.10 or later. -When the compiler comes across `import "file";` or `import ;`, this compiler option helps the compiler find the compiled header unit (*`.ifc`*) for the specified header file. The path to this file can be expressed in three ways: +When the compiler comes across `import "file";` or `import ;` this compiler option helps the compiler find the compiled header unit (*`.ifc`*) for the specified header file. The path to this file can be expressed in these ways: -**`/headerUnit`** looks up the compiled header unit in the current directory, or at the location specified in *`ifc-filename`*. +- **`/headerUnit`** looks up the compiled header unit in the current directory, or at the location specified by *`ifc-filename`*. -**`/headerUnit:quote`** looks up the compiled header unit file using the same rules as `#include "file"`. +- **`/headerUnit:quote`** looks up the compiled header unit file using the same rules as `#include "file"`. -**`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include `. +- **`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include `. -The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. While mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, we don't recommend it. The contents of the *`.ifc`* get imported as if it was only the header specified by *`header-name`*. +The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. You can map multiple *`header-name`* arguments to a single *`.ifc`*. The contents of the *`.ifc`* are imported as if it was only the header specified by *`header-name`*. -The compiler implicitly enables the new preprocessor when this option is used. That is, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler if any form of `/headerUnit` is specified on the command line. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-` +The compiler implicitly enables the new preprocessor when this option is used. If any form of `/headerUnit` is specified on the command line, then [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-` If you disable the new preprocessor, but a file you compile imports a header unit, the compiler will report an error. ### Examples -Given a project that references two header files and their header units, listed in this table: +Given a project that references two header files and their header units as listed in this table: | Header file | IFC file | |--|--| | *`C:\utils\util.h`* | *`C:\util.h.ifc`* | | *`C:\app\app.h`* | *`C:\app\app.h.ifc`* | -The compiler options to reference the header units for these particular header files would look similar to this: +The compiler options to reference the header units for these particular header files would look like this: ```CMD cl ... /std:c++latest /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit:quote app.h=app.h.ifc @@ -62,10 +62,11 @@ cl ... /std:c++latest /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit:quot ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this in the Visual Studio development environment. It's set by the build system. ## See also [`/exportHeader` (Create header units)](module-exportheader.md)\ [`/headerName` (Create a header unit from the specified header)](headername.md)\ -[`/reference` (Use named module IFC)](module-reference.md) +[`/reference` (Use named module IFC)](module-reference.md)\ +[`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/idlout-name-midl-output-files.md b/docs/build/reference/idlout-name-midl-output-files.md index 38b277f76d..3c18293306 100644 --- a/docs/build/reference/idlout-name-midl-output-files.md +++ b/docs/build/reference/idlout-name-midl-output-files.md @@ -1,51 +1,45 @@ --- -description: "Learn more about: /IDLOUT (Name MIDL Output Files)" title: "/IDLOUT (Name MIDL Output Files)" -ms.date: "11/04/2016" +description: "Learn more about: /IDLOUT (Name MIDL Output Files)" +ms.date: 03/27/2025 f1_keywords: ["/idlout", "VC.Project.VCLinkerTool.MergedIDLBaseFileName"] helpviewer_keywords: ["MIDL, output file names", ".idl files, path", "MIDL", "/IDLOUT linker option", "IDL files, path", "-IDLOUT linker option", "IDLOUT linker option"] -ms.assetid: 10d00a6a-85b4-4de1-8732-e422c6931509 --- # /IDLOUT (Name MIDL Output Files) -``` -/IDLOUT:[path\]filename -``` +## Syntax -## Parameters +> /IDLOUT:[path\]filename -*path*
-An absolute or relative path specification. By specifying a path, you affect only the location of an .idl file; all other files are placed in the project directory. +## Argument -*filename*
-Specifies the name of the .idl file created by the MIDL compiler. No file extension is assumed; specify *filename*.idl if you want an .idl extension. +*`path`*\ +An absolute or relative path specification. By specifying a path, you affect only the location of an `.idl` file; all other files are placed in the project directory. + +*`filename`*\ +Specifies the name of the `.idl` file created by the MIDL compiler. No file extension is assumed; specify *`filename.idl` if you want an `.idl` extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /IDLOUT option specifies the name and extension of the .idl file. +The `/IDLOUT` option specifies the name and extension of the `.idl` file. -The MIDL compiler is called by the MSVC linker when linking projects that have the [module](../../windows/attributes/module-cpp.md) attribute. +The MIDL compiler is called by the MSVC linker when linking projects that have the [`module`](../../windows/attributes/module-cpp.md) attribute. -/IDLOUT also specifies the file names of the other output files associated with the MIDL compiler: +`/IDLOUT` also specifies the file names of the other output files associated with the MIDL compiler: - *filename*.tlb - - *filename*_p.c - - *filename*_i.c - - *filename*.h -*filename* is the parameter that you pass to /IDLOUT. If [/TLBOUT](tlbout-name-dot-tlb-file.md) is specified, the .tlb file will get its name from /TLBOUT *filename*. +*`filename`* is the parameter that you pass to `/IDLOUT`. If [`/TLBOUT`](tlbout-name-dot-tlb-file.md) is specified, the .tlb file will get its name from `/TLBOUT` *`filename`*. -If you specify neither /IDLOUT nor /TLBOUT, the linker will create vc70.tlb, vc70.idl, vc70_p.c, vc70_i.c, and vc70.h. +If you specify neither `/IDLOUT` nor `/TLBOUT`, the linker will create vc70.tlb, vc70.idl, vc70_p.c, vc70_i.c, and vc70.h. ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Embedded IDL** property page. - 1. Modify the **Merge IDL Base File Name** property. ### To set this linker option programmatically @@ -54,8 +48,8 @@ If you specify neither /IDLOUT nor /TLBOUT, the linker will create vc70.tlb, vc7 ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
-[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)\ +[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)\ [Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/ifc-map.md b/docs/build/reference/ifc-map.md new file mode 100644 index 0000000000..7466fd2b00 --- /dev/null +++ b/docs/build/reference/ifc-map.md @@ -0,0 +1,88 @@ +--- +title: "/ifcMap" +description: "Map named modules and header units to IFC files." +ms.date: 10/16/2023 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcMap"] +helpviewer_keywords: ["/ifcMap", "Specify named module and header unit mappings to IFC files."] +--- +# `/ifcMap` + +This switch tells the compiler where to find the IFC reference map file, which maps references to named modules and header units to their corresponding IFC (`.ifc`) files. + +## Syntax + +> **`/ifcMap`** *`filename`* + +## Remarks + +The *`filename`* argument specifies the IFC reference map file. It can be relative to the compiler's working directory, or an absolute path. + +You can provide multiple `/ifcMap` arguments to the compiler. + +The IFC reference map file format is a subset of the [TOML](https://toml.io/en/) file format. The IFC reference map file can contain a mix of `[[module]]` and `[[header-unit]]` references. + +Syntax errors or unrecognized table names result in compiler error `C7696` (TOML parse error). + +### Map named modules + +The format of the IFC reference map file for named modules is: + +``` +# Using literal strings +[[module]] +name = 'M' +ifc = 'C:\modules\M.ifc' + +# Using basic strings +[[module]] +name = "N" +ifc = "C:\\modules\\N.ifc" +``` + +This IFC reference map file maps the named modules `'M'` and `'N'` to their respective IFC files. The equivalent [`/reference`](module-reference.md) is: + +```cmd +/reference M=C:\modules\M.ifc /reference N=C:\modules\N.ifc +``` + +For more information about what types of module names are valid for the `name` field, see [`/reference remarks`](module-reference.md#remarks). + +### Map header units + +The format of the IFC reference map file for header units is: + +``` +# Using literal strings +[[header-unit]] +name = ['quote', 'my-utility.h'] +ifc = 'C:\header-units\my-utility.h.ifc' + +[[header-unit]] +name = ['angle', 'vector'] +ifc = 'C:\header-units\vector.ifc' + +# Using basic strings +[[header-unit]] +name = ["quote", "my-engine.h"] +ifc = "C:\\header-units\\my-engine.h.ifc" + +[[header-unit]] +name = ["angle", "algorithm"] +ifc = "C:\\header-units\\algorithm.ifc" +``` + +This IFC reference map file maps `"my-utility.h"` to `C:\header-units\my-utility.h.ifc`, and `` to `C:\header-units\vector.ifc`, and so on. The equivalent [`/headerUnit`](headerunit.md) is: + +```cmd +/headerUnit:quote my-utility=C:\header-units\my-utility.h.ifc /headerUnit:angle vector=C:\header-units\vector.ifc /headerUnit:quote my-engine.h=C:\header-units\my-engine.h.ifc /headerUnit:angle algorithm=C:\header-units\algorithm.ifc +``` + +When `[[header-unit]]` is specified in an IFC reference map file, the compiler implicitly enables [`/Zc:preprocessor`](zc-preprocessor.md), just as it's implicitly enabled when [`/headerUnit`](headerunit.md) is used. For more information about the behavior of the `angle` and `quote` lookup methods, see [/headerUnit remarks](headerunit.md#remarks). + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Walkthrough: Build and import header units in Visual C++ projects](../walkthrough-header-units.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ifc-output.md b/docs/build/reference/ifc-output.md new file mode 100644 index 0000000000..2fd60fcca2 --- /dev/null +++ b/docs/build/reference/ifc-output.md @@ -0,0 +1,56 @@ +--- +title: "/ifcOutput" +description: "Specify output file or directory for `.ifc` files." +ms.date: 11/21/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcOutput", "VC.Project.VCCLCompilerTool.ifcOutput"] +helpviewer_keywords: ["/ifcOutput", "Specify where the compiled `.ifc` should go"] +--- +# `/ifcOutput` + +This switch tells the compiler where to output built *`.ifc`* files. If the destination is a directory, then the compiler generates the name of each `.ifc` file based on the interface name or the header unit name. + +## Syntax + +> **`/ifcOutput`** *`filename`*\ +> **`/ifcOutput`** *`directory\`* + +## Remarks + +By default, the compiler derives the name for each generated *`.ifc`* file from the module interface name. For example, given a module name `MyModule`, the generated *`.ifc`* will be named *`MyModule.ifc`*, unless you override the name with the `/ifcOutput` switch. + +Use this switch to specify an alternative *`.ifc`* filename or directory. If you want to use the default built *`.ifc`* filenames, but specify a directory where they should be built, ensure that you add a trailing backslash (`\`) to the directory name. + +When you're building multiple *`.ifc`* files, only use the directory form of the `/ifcOutput` switch. If you provide multiple `/ifcOutput` switches, the compiler only uses the last one. + +If you build with the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) switch, we recommend that you use the directory form of the `/ifcOutput` switch if you have multiple input module files. + +In the following example, the *`.ifc`* file for module `m` defined in *`m.ixx`* is built as `c:\example\m.ifc`. + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\ +``` + +In the following example, the built *`.ifc`* file for module `m` defined in *`m.ixx`** is built as `c:\example\MyModule.ifc`: + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\MyModule.ifc +``` + +### To set this compiler option in the Visual Studio development environment + +1. To apply the **`/ifcOutput`** option to one file in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the **Property Pages** dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Output Files** property page. + +1. Use the dropdown control to modify the **Module Output File Name** property to a directory name (ending in `\`) or an alternate file name. Or you can specify a directory + file name, for example, `c:\example\mymodule.ifc`. Choose **OK** or **Apply** to save your changes. + +Alternatively, you can specify the `/ifcOutput` switch with a right-click on the project name in the **Solution Explorer** > **Configuration Properties** > **C/C++** > **Command Line**. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ilk-name-incremental-database-file.md b/docs/build/reference/ilk-name-incremental-database-file.md new file mode 100644 index 0000000000..ab1d1d456e --- /dev/null +++ b/docs/build/reference/ilk-name-incremental-database-file.md @@ -0,0 +1,39 @@ +--- +title: "/ILK (Name incremental database file)" +description: "The MSVC linker option /ILK specifies the incremental link database file pathname." +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IncrementalLinkDatabaseFile", "/ilk", "ilk"] +helpviewer_keywords: ["Name incremental database file in C++ linker", "/ILK linker option", "-ILK linker option", "ILK linker option"] +--- +# `/ILK` (Name incremental database file) + +The **`/ILK`** linker option tells the linker where to put the *`.ilk`* database file for incremental link information ([`/INCREMENTAL`](./incremental-link-incrementally.md)). + +## Syntax + +> **`/ILK:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The destination directory and filename for the generated *`.ilk`* file. If the **`/ILK`** option isn't specified when **`/INCREMENTAL`** is used, the filename is created by appending *`.ilk`* to the target base filename. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + +## Remarks + +The **`/ILK`** linker option tells the linker the path and filename to use for the *`.ilk`* incremental database file when you specify [`/INCREMENTAL`](./incremental-link-incrementally.md). + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **General** property page. +1. Modify the **Incremental Link Database File** property. The default value is `$(IntDir)$(TargetName).ilk`. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/INCREMENTAL`](./incremental-link-incrementally.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) \ No newline at end of file diff --git a/docs/build/reference/implib-name-import-library.md b/docs/build/reference/implib-name-import-library.md index 9bf0f23ef3..93ad9b6efb 100644 --- a/docs/build/reference/implib-name-import-library.md +++ b/docs/build/reference/implib-name-import-library.md @@ -1,38 +1,35 @@ --- description: "Learn more about: /IMPLIB (Name Import Library)" title: "/IMPLIB (Name Import Library)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["/implib", "VC.Project.VCLinkerTool.ImportLIbrary"] helpviewer_keywords: ["IMPLIB linker option", "/IMPLIB linker option", "-IMPLIB linker option", "import libraries, overriding default name"] -ms.assetid: fe8f71ab-7055-41b5-8ef8-2b97cfa4a432 --- -# /IMPLIB (Name Import Library) +# `/IMPLIB` (Name Import Library) + +## Syntax > /IMPLIB:*filename* -## Parameters +## Argument -*filename*
-A user-specified name for the import library. It replaces the default name. +*`filename`*\ +A user-specified name for the import library. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /IMPLIB option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension .lib. A program contains exports if one or more of the following are specified: +The `/IMPLIB` option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension `.lib`. A program contains exports if one or more of the following are specified: - The [__declspec(dllexport)](../../cpp/dllexport-dllimport.md) keyword in the source code - - [EXPORTS](exports.md) statement in a .def file - - An [/EXPORT](export-exports-a-function.md) specification in a LINK command -LINK ignores /IMPLIB when an import library is not being created. If no exports are specified, LINK does not create an import library. If an export file is used in the build, LINK assumes that an import library already exists and does not create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). +LINK ignores `/IMPLIB` when an import library isn't being created. If no exports are specified, LINK doesn't create an import library. If an export file is used in the build, LINK assumes that an import library already exists and doesn't create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. - 1. Modify the **Import Library** property. ### To set this linker option programmatically @@ -41,5 +38,5 @@ LINK ignores /IMPLIB when an import library is not being created. If no exports ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/incremental-link-incrementally.md b/docs/build/reference/incremental-link-incrementally.md index ef569a1246..581ba2ccd8 100644 --- a/docs/build/reference/incremental-link-incrementally.md +++ b/docs/build/reference/incremental-link-incrementally.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: /INCREMENTAL (Link Incrementally)" -title: "/INCREMENTAL (Link Incrementally)" -ms.date: "11/04/2016" +description: "Learn more about: /INCREMENTAL (Link incrementally)" +title: "/INCREMENTAL (Link incrementally)" +ms.date: 09/07/2022 f1_keywords: ["/incremental", "VC.Project.VCLinkerTool.LinkIncremental"] helpviewer_keywords: ["/INCREMENTAL linker option", "-INCREMENTAL linker option", "INCREMENTAL linker option", "link incrementally option", "LINK tool [C++], options for full linking", "incremental linking"] ms.assetid: 135656ff-94fa-4ad4-a613-22e1a2a5d16b --- -# /INCREMENTAL (Link Incrementally) +# `/INCREMENTAL` (Link incrementally) -``` -/INCREMENTAL[:NO] -``` +Specifies whether to link incrementally or always perform a full link. + +## Syntax + +> **`/INCREMENTAL`**\[**`:NO`**] ## Remarks -Controls how the linker handles incremental linking. +The **`/INCREMENTAL`** linker option controls how the linker handles incremental linking. -By default, the linker runs in incremental mode. To override a default incremental link, specify /INCREMENTAL:NO. +By default, the linker runs in incremental mode. To override a default incremental link, specify **`/INCREMENTAL:NO`**. -An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it is prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: +An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it's prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: - Is larger than a non-incrementally linked program because of padding of code and data. Padding enables the linker to increase the size of functions and data without recreating the file. @@ -27,35 +29,37 @@ An incrementally linked program is functionally equivalent to a program that is > [!NOTE] > To ensure that your final release build does not contain padding or thunks, link your program non-incrementally. -To link incrementally regardless of the default, specify /INCREMENTAL. When this option is selected, the linker issues a warning if it cannot link incrementally, and then links the program non-incrementally. Certain options and situations override /INCREMENTAL. +To link incrementally regardless of the default, specify **`/INCREMENTAL`**. When this option is selected, the linker issues a warning if it can't link incrementally, and then links the program non-incrementally. Certain options and situations override **`/INCREMENTAL`**. Most programs can be linked incrementally. However, some changes are too great, and some options are incompatible with incremental linking. LINK performs a full link if any of the following options are specified: -- Link Incrementally is not selected (/INCREMENTAL:NO) +- Link Incrementally isn't selected (**`/INCREMENTAL:NO`**) -- /OPT:REF is selected +- **`/OPT:REF`** is selected -- /OPT:ICF is selected +- **`/OPT:ICF`** is selected -- /OPT:LBR is selected +- **`/OPT:LBR`** is selected -- /ORDER is selected +- **`/ORDER`** is selected -/INCREMENTAL is implied when [/DEBUG](debug-generate-debug-info.md) is specified. +**`/INCREMENTAL`** is implied when [`/DEBUG`](debug-generate-debug-info.md) is specified. Additionally, LINK performs a full link if any of the following situations occur: -- The incremental status (.ilk) file is missing. (LINK creates a new .ilk file in preparation for subsequent incremental linking.) +- The incremental status (*`.ilk`*) file is missing. (LINK creates a new *`.ilk`* file in preparation for subsequent incremental linking.) -- There is no write permission for the .ilk file. (LINK ignores the .ilk file and links non-incrementally.) +- There's no write permission for the *`.ilk`* file. (LINK ignores the *`.ilk`* file and links non-incrementally.) -- The .exe or .dll output file is missing. +- The *`.exe`* or *`.dll`* output file is missing. -- The timestamp of the .ilk, .exe, or .dll is changed. +- The timestamp of the *`.ilk`*, *`.exe`*, or *`.dll`* is changed. - A LINK option is changed. Most LINK options, when changed between builds, cause a full link. -- An object (.obj) file is added or omitted. +- An object (*`.obj`*) file is added or omitted. + +An incremental link creates or updates an incremental link database *`.ilk`* file. You can specify the name and location of this file by using the [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md) linker option. For more information about the *`.ilk`* file, see [`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment @@ -71,5 +75,6 @@ Additionally, LINK performs a full link if any of the following situations occur ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md) diff --git a/docs/build/reference/inference-rules.md b/docs/build/reference/inference-rules.md index 593b8b2bbb..ebb37cb557 100644 --- a/docs/build/reference/inference-rules.md +++ b/docs/build/reference/inference-rules.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: NMAKE inference rules" title: "Inference rules" +description: "Learn more about: NMAKE inference rules" ms.date: 09/30/2021 helpviewer_keywords: ["inference rules in NMAKE", "rules, inference", "NMAKE program, inference rules", "search paths in NMAKE inference rules", "defining inference rules", "batch-mode inference rules in NMAKE", "rules, predefined", "NMAKE program, predefined rules", "predefined rules in NMAKE", "rules, inferred", "inferred dependents in NMAKE", "inferred rules in NMAKE", "dependents, inferred", "precedence, inference rule"] --- @@ -10,7 +10,7 @@ Inference rules in NMAKE supply commands to update targets and to infer dependen If an out-of-date dependency has no commands, and if [`.SUFFIXES`](dot-directives.md) contains the dependent's extension, NMAKE uses a rule whose extensions match the target and an existing file in the current or specified directory. If more than one rule matches existing files, the **`.SUFFIXES`** list determines which to use; list priority descends from left to right. If a dependent file doesn't exist and isn't listed as a target in another description block, an inference rule can create the missing dependent from another file that has the same base name. If a description block's target has no dependents or commands, an inference rule can update the target. Inference rules can build a command-line target even if no description block exists. NMAKE may invoke a rule for an inferred dependent even if an explicit dependent is specified. -## Defining a rule +## Defining a rule The *from_ext* represents the extension of a dependent file, and *to_ext* represents the extension of a target file. @@ -21,7 +21,7 @@ The *from_ext* represents the extension of a dependent file, and *to_ext* repres Extensions aren't case-sensitive. Macros can be invoked to represent *from_ext* and *to_ext*; the macros are expanded during preprocessing. The period (**`.`**) that precedes *from_ext* must appear at the beginning of the line. The colon (**`:`**) is preceded by zero or more spaces or tabs. It can be followed only by spaces or tabs, a semicolon (**`;`**) to specify a command, a number sign (**`#`**) to specify a comment, or a newline character. No other spaces are allowed. Commands are specified as in description blocks. -## Search paths in rules +## Search paths in rules ```makefile {from_path}.from_ext{to_path}.to_ext: @@ -61,7 +61,7 @@ An inference rule applies to a dependency only if paths specified in the depende $(CC) $(CFLAGS) $< ``` -## Batch-mode rules +## Batch-mode rules ```makefile {from_path}.from_ext{to_path}.to_ext:: @@ -135,7 +135,7 @@ foo4.cpp Generating Code... ``` -## Predefined rules +## Predefined rules Predefined inference rules use NMAKE-supplied command and options macros. @@ -155,7 +155,7 @@ Predefined inference rules use NMAKE-supplied command and options macros. | `.cxx.obj` | `$(CXX) $(CXXFLAGS) /c $<` | `cl /c $<` | yes | all | | `.rc.res` | `$(RC) $(RFLAGS) /r $<` | `rc /r $<` | no | all | -## Inferred dependents and rules +## Inferred dependents and rules NMAKE assumes an inferred dependent for a target if an applicable inference rule exists. A rule applies if: @@ -169,7 +169,7 @@ NMAKE assumes an inferred dependent for a target if an applicable inference rule Inferred dependents can cause unexpected side effects. If the target's description block contains commands, NMAKE executes those commands instead of the commands in the rule. -## Precedence in inference rules +## Precedence in inference rules If an inference rule is defined more than once, NMAKE uses the highest-precedence definition. The following list shows the order of precedence from highest to lowest: diff --git a/docs/build/reference/inline-files-in-a-makefile.md b/docs/build/reference/inline-files-in-a-makefile.md index 5e2e03c1b2..b18211ffdc 100644 --- a/docs/build/reference/inline-files-in-a-makefile.md +++ b/docs/build/reference/inline-files-in-a-makefile.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Inline files in a makefile" title: "Inline files in a makefile" +description: "Learn more about: Inline files in a makefile" ms.date: 09/30/2021 helpviewer_keywords: ["inline files [C++], in makefiles", "inline files [C++]", "NMAKE program, inline files", "makefiles, inline files", "files [C++], inline", "inline files, multiple NMAKE", "multiple inline files", "inline files, reusing NMAKE", "reusing inline files", "inline files, creating text", "inline files [C++], specifying NMAKE"] --- @@ -8,7 +8,7 @@ helpviewer_keywords: ["inline files [C++], in makefiles", "inline files [C++]", An inline file contains text you specify in the makefile. Its name can be used in commands as input (for example, a LINK command file), or it can pass commands to the operating system. The file is created on disk when a command that creates the file is run. -## Specify an inline file +## Specify an inline file Specify two angle brackets (**`<<`**) in the command where *filename* is to appear. The angle brackets can't be a macro expansion. The *filename* is optional: @@ -18,7 +18,7 @@ Specify two angle brackets (**`<<`**) in the command where *filename* is to appe When the command is run, the angle brackets are replaced by *filename*, if specified, or by a unique NMAKE-generated name. If specified, *filename* must follow angle brackets without a space or tab. A path is permitted. No extension is required or assumed. If *filename* is specified, the file is created in the current or specified directory, overwriting any existing file by that name. Otherwise, it's created in the `TMP` directory (or the current directory, if the `TMP` environment variable isn't defined). If a previous *filename* is reused, NMAKE replaces the previous file. -## Create inline file text +## Create inline file text Inline files are temporary or permanent. @@ -34,11 +34,11 @@ Specify your *inline_text* on the first line after the command. Mark the end wit A temporary file exists for the duration of the session and can be reused by other commands. Specify **`KEEP`** after the closing angle brackets to retain the file after the NMAKE session; an unnamed file is preserved on disk with the generated filename. Specify **`NOKEEP`** or nothing for a temporary file. **`KEEP`** and **`NOKEEP`** are not case sensitive. -## Reuse inline files +## Reuse inline files To reuse an inline file, specify `< Multiple inline files +## Multiple inline files A command can create more than one inline file: diff --git a/docs/build/reference/integritycheck-require-signature-check.md b/docs/build/reference/integritycheck-require-signature-check.md index e8786d6bd6..2e154fe960 100644 --- a/docs/build/reference/integritycheck-require-signature-check.md +++ b/docs/build/reference/integritycheck-require-signature-check.md @@ -1,23 +1,23 @@ --- description: "Learn more about: /INTEGRITYCHECK (Require signature check)" title: "/INTEGRITYCHECK (Require signature check)" -ms.date: 04/21/2021 +ms.date: 08/29/2023 --- # `/INTEGRITYCHECK` (Require signature check) Specifies that the digital signature of the binary image must be checked at load time. -> **`/INTEGRITYCHECK`**[**`:NO`**] +> **`/INTEGRITYCHECK`** ## Remarks By default, **`/INTEGRITYCHECK`** is off. -The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that implement kernel-mode code loaded by certain Windows features. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). +The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that certain Windows features load. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). ### Signing `/INTEGRITYCHECK` files -Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). We recommend you sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Azure Code Signing](https://techcommunity.microsoft.com/t5/video-hub/reduce-developer-friction-with-azure-code-signing/m-p/1698637) program instead. +Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). You must now sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Trusted Signing service](/azure/trusted-signing/) program instead. ### To set this linker option in Visual Studio @@ -25,12 +25,14 @@ Microsoft has new signing guidance for DLL and executable files linked by using 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter *`/INTEGRITYCHECK`* or *`/INTEGRITYCHECK:NO`*. Choose **OK** to save your changes. +1. To create a digitally signed image, include `/INTEGRITYCHECK` in the **Additional Options** command line. A digitally signed image must pass a verification check before it's loaded. This feature is disabled by default. + +1. Choose **OK** to save your changes. ## See also -[MSVC linker reference](linking.md)
-[MSVC linker options](linker-options.md)
-[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)
-[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)
+[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)\ +[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)\ [AppInit DLLs and Secure Boot](/windows/win32/dlls/secure-boot-and-appinit-dlls) diff --git a/docs/build/reference/interface.md b/docs/build/reference/interface.md new file mode 100644 index 0000000000..743215fc73 --- /dev/null +++ b/docs/build/reference/interface.md @@ -0,0 +1,50 @@ +--- +title: "/interface" +description: "Use the /interface compiler option to treat the input file as a module interface unit." +ms.date: 11/16/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/interface", "VC.Project.VCCLCompilerTool.Interface"] +helpviewer_keywords: ["/interface", "Translate include directives into import directives"] +--- +# `/interface` + +This switch instructs the compiler to treat the input file on the command line as a module interface unit. + +## Syntax + +> **`/interface`** *`filename`* + +## Remarks + +Use this switch when a module interface has a different extension than `.ixx`. + +In the following example, the module interface has a `.cppm` extension instead of `.ixx`, so the `/interface` switch is used to compile it as a module interface: + +```bash +cl /c /std:c++latest /interface /TP my-module.cppm +``` + +The compiler derives the name for the generated `.ifc` file from the module interface name. For example, given a module name `MyModule` defined in `my-module.cppm`, the generated `.ifc` will be named `MyModule.ifc`. + +This switch must be used in with the [`/TP` (Specify source file type)](tc-tp-tc-tp-specify-source-file-type.md) compiler flag. + +**`/interface`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/interface`** requires [/std:c++20](std-specify-language-standard-version.md) or later. + +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your module interface files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/interface`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Code (/interface)**. Choose **OK** or **Apply** to save your changes. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/internal-partition.md b/docs/build/reference/internal-partition.md new file mode 100644 index 0000000000..393c44956a --- /dev/null +++ b/docs/build/reference/internal-partition.md @@ -0,0 +1,69 @@ +--- +title: "/internalPartition" +description: "Use the /internalPartition compiler option to treat the input file as an internal partition unit." +ms.date: 11/16/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/internalPartition", "VC.Project.VCCLCompilerTool.Interface"] +helpviewer_keywords: ["/internalPartition", "Translate include directives into import directives"] +--- +# `/internalPartition` + +Use the **`/internalPartition`** compiler option to treat the input file as an *internal partition unit*, which is a [module partition implementation unit](../../cpp/modules-cpp.md#implementing-modules) that doesn't contribute to the external interface of the module. + +## Syntax + +> **`/internalPartition`** *`filename`* + +## Remarks + +The following example demonstrates how to use the `/internalPartition` option: + +Source file `m-internals.cpp`: + +```cpp +// m-internals.cpp +module m:internals; + +void internalFunc() {} // cannot have `export` since this is an internal partition +``` + +Source file `m.ixx`: + +```cpp +// m.ixx +export module m; +import :internals; // Cannot export this partition. + +export +void wrapper() { internalFunc(); } +``` + +To compile this interface: + +```bash +cl /std:c++latest /internalPartition /c m-internals.cpp +``` + +This option can't be used with the [`/interface`](interface.md) compiler option. + +**`/internalPartition`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/internalPartition`** requires [/std:c++20](std-specify-language-standard-version.md) or later. + +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your partition files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/internalPartition`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Internal Partition (/internalPartition)**. Choose **OK** or **Apply** to save your changes. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/)\ +[C++ Modules conformance improvements with MSVC in Visual Studio 2019 16.5](https://devblogs.microsoft.com/cppblog/c-modules-conformance-improvements-with-msvc-in-visual-studio-2019-16-5/#module-partitions) \ No newline at end of file diff --git a/docs/build/reference/jmc.md b/docs/build/reference/jmc.md index ebff0e2dec..c78e3b3eb1 100644 --- a/docs/build/reference/jmc.md +++ b/docs/build/reference/jmc.md @@ -1,25 +1,27 @@ --- description: "Learn more about: /JMC (Just My Code debugging)" title: "/JMC (Just My Code debugging)" -ms.date: "08/20/2018" +ms.date: 03/01/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.SupportJustMyCode"] helpviewer_keywords: ["/JMC compiler option [C++]", "Just my code [C++]", "-JMC compiler option [C++]", "User code, debugging", "JMC compiler option [C++]"] --- -# /JMC (Just My Code debugging) +# `/JMC` (Just My Code debugging) -Specifies compiler support for native *Just My Code* debugging in the Visual Studio debugger. This option supports the user settings that allow Visual Studio to step over system, framework, library, and other non-user calls, and to collapse those calls in the call stack window. The **/JMC** compiler option is available starting in Visual Studio 2017 version 15.8. +Specifies compiler support for native *Just My Code* debugging in the Visual Studio debugger. This option supports the user settings that allow Visual Studio to step over system, framework, library, and other non-user calls, and to collapse those calls in the call stack window. The **`/JMC`** compiler option is available starting in Visual Studio 2017 version 15.8. ## Syntax -> **/JMC**\[**-**] +> **`/JMC`**\[**`-`**] ## Remarks -The Visual Studio [Just My Code](/visualstudio/debugger/just-my-code) settings specify whether the Visual Studio debugger steps over system, framework, library, and other non-user calls. The **/JMC** compiler option enables support for Just My Code debugging in your native C++ code. When **/JMC** is enabled, the compiler inserts calls to a helper function, `__CheckForDebuggerJustMyCode`, in the function prolog. The helper function provides hooks that support Visual Studio debugger Just My Code step operations. To enable Just My Code in the Visual Studio debugger, on the menu bar, choose **Tools** > **Options**, and then set the option in **Debugging** > **General** > **Enable Just My Code**. +The Visual Studio [Just My Code](/visualstudio/debugger/just-my-code#BKMK_C___Just_My_Code) settings specify whether the Visual Studio debugger steps over system, framework, library, and other non-user calls. The **`/JMC`** compiler option enables support for Just My Code debugging in your native C++ code. When **`/JMC`** is enabled, the compiler inserts calls to a helper function, `__CheckForDebuggerJustMyCode`, in the function prolog. The helper function provides hooks that support Visual Studio debugger Just My Code step operations. To enable Just My Code in the Visual Studio debugger, on the menu bar, choose **Tools** > **Options**, and then set the option in **Debugging** > **General** > **Enable Just My Code**. -The **/JMC** option requires that your code links to the C Runtime Library (CRT), which provides the `__CheckForDebuggerJustMyCode` helper function. If your project does not link to the CRT, you may see linker error **LNK2019: unresolved external symbol __CheckForDebuggerJustMyCode**. To resolve this error, either link to the CRT, or disable the **/JMC** option. +The **`/JMC`** option requires that your code links to the C Runtime Library (CRT), which provides the `__CheckForDebuggerJustMyCode` helper function. If your project doesn't link to the CRT, you may see linker error **LNK2019: unresolved external symbol __CheckForDebuggerJustMyCode**. To resolve this error, either link to the CRT, or disable the **`/JMC`** option. -By default, the **/JMC** compiler option is off. However, starting in Visual Studio 2017 version 15.8 this option is enabled in most Visual Studio project templates. To explicitly disable this option, use the **/JMC-** option on the command line. In Visual Studio, open the project Property Pages dialog box, and change the **Support Just My Code Debugging** property in the **Configuration Properties** > **C/C++** > **General** property page to **No**. +When the **`/JMC`** option is enabled, the PDB file is annotated with extra line number information. In versions before Visual Studio 2019 version 16.8, this information may appear in code coverage reports as occurring at line 15732480 (0xF00F00) or 16707566 (0xFEEFEE). These fictitious line numbers are used as markers to delineate user code from non-user code. To include non-user code in code coverage reports without these unexpected line numbers, build your code with the **`/JMC-`** option. + +By default, the **`/JMC`** compiler option is off. However, starting in Visual Studio 2017 version 15.8 this option is enabled in most Visual Studio project templates. To explicitly disable this option, use the **`/JMC-`** option on the command line. In Visual Studio, open the project Property Pages dialog box, and change the **Support Just My Code Debugging** property in the **Configuration Properties** > **C/C++** > **General** property page to **No**. For more information, see [C++ Just My Code](/visualstudio/debugger/just-my-code#BKMK_C___Just_My_Code) in [Specify whether to debug only user code using Just My Code in Visual Studio](/visualstudio/debugger/just-my-code), and the Visual C++ Team Blog post [Announcing C++ Just My Code Stepping in Visual Studio](https://devblogs.microsoft.com/cppblog/announcing-jmc-stepping-in-visual-studio/). @@ -37,5 +39,5 @@ For more information, see [C++ Just My Code](/visualstudio/debugger/just-my-code ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/jump-table-rdata.md b/docs/build/reference/jump-table-rdata.md new file mode 100644 index 0000000000..9cb7dd4fdc --- /dev/null +++ b/docs/build/reference/jump-table-rdata.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: /jumptablerdata (Place switch case jump tables in .rdata)" +title: "/jumptablerdata (put switch case jump tables in `.rdata`)" +ms.date: 06/02/2023 +f1_keywords: ["/jumptable"] +helpviewer_keywords: ["-jumptablerdata compiler option [C++]", "/jumptablerdata compiler option [C++]"] +--- +# /jumptablerdata (put switch case jump tables in `.rdata`) + +Puts the generated switch case jump tables in the `.rdata` section instead of alongside code in the `.text` section. + +## Syntax + +```cpp +/jumptablerdata +``` + +## Remarks + +Putting jump tables generated for switch case statements in the `.rdata` section prevents the jump table from being loaded into both the instruction cache (iCache) and data cache (dCache), potentially increasing performance. The `.rdata` section is where const initialized data is stored. + +> [!IMPORTANT] +> This flag only applies to x64 code. This flag was introduced in Visual Studio 17.7. + +### To set this compiler option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to include `/jumptablerdata` and then choose **OK**. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md index cb7054b09a..8ee29e44c0 100644 --- a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md +++ b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md @@ -23,7 +23,7 @@ The linker creates a signed assembly by inserting a public key into the assembly If you compile with [/LN](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [#using](../../preprocessor/hash-using-directive-cpp.md), or when linking with [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md). -You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. See [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) for more information on signing an assembly. +You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md). Other linker options that affect assembly generation are: diff --git a/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md b/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md index 2ef01ea543..3d1a74d531 100644 --- a/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md +++ b/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: /KEYFILE (Specify Key or Key Pair to Sign an Assembly)" title: "/KEYFILE (Specify Key or Key Pair to Sign an Assembly)" -ms.date: "11/04/2016" +description: "Learn more about: /KEYFILE (Specify Key or Key Pair to Sign an Assembly)" +ms.date: 03/24/2025 f1_keywords: ["/keyfile", "VC.Project.VCLinkerTool.KeyFile"] helpviewer_keywords: ["/KEYFILE linker option", "-KEYFILE linker option", "KEYFILE linker option"] -ms.assetid: 9b71f8c0-541c-4fe5-a0c7-9364f42ecb06 --- -# /KEYFILE (Specify Key or Key Pair to Sign an Assembly) +# `/KEYFILE` (Specify Key or Key Pair to Sign an Assembly) ``` /KEYFILE:filename @@ -14,39 +13,33 @@ ms.assetid: 9b71f8c0-541c-4fe5-a0c7-9364f42ecb06 ## Arguments -*filename*
+*`filename`*\ File that contains the key. Place the string in double quotation marks (" ") if it contains a space. ## Remarks -The linker inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type [sn -k](/dotnet/framework/tools/sn-exe-strong-name-tool) *filename* at the command line. A signed assembly is said to have a strong name. +The linker inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type [`sn -k`](/dotnet/framework/tools/sn-exe-strong-name-tool) *filename* at the command line. A signed assembly is said to have a strong name. -If you compile with [/LN](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [#using](../../preprocessor/hash-using-directive-cpp.md), or when linking with [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md). +If you compile with [`/LN`](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [`#using`](../../preprocessor/hash-using-directive-cpp.md), or when linking with [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md). -You can also pass your encryption information to the linker with [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) and [Creating and Using Strong-Named Assemblies](/dotnet/framework/app-domains/create-and-use-strong-named-assemblies). +You can also pass your encryption information to the linker with [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md). Use [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) and [Creating and Using Strong-Named Assemblies](/dotnet/framework/app-domains/create-and-use-strong-named-assemblies). -In case both **/KEYFILE** and **/KEYCONTAINER** are specified (either by command-line option or by custom attribute), the linker will first try the key container. If that succeeds, then the assembly is signed with the information in the key container. If the linker doesn't find the key container, it will try the file specified with /KEYFILE. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to sn -i) so that on the next compilation, the key container will be valid. +In case both **`/KEYFILE`** and **`/KEYCONTAINER`** are specified (either by command-line option or by custom attribute), the linker will first try the key container. If that succeeds, then the assembly is signed with the information in the key container. If the linker doesn't find the key container, it will try the file specified with /KEYFILE. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to sn -i) so that on the next compilation, the key container will be valid. A key file might contain only the public key. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) - -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) - -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) - -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) - -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. - 1. Enter the option into the **Additional Options** box. ### To set this linker option programmatically @@ -55,5 +48,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/largeaddressaware-handle-large-addresses.md b/docs/build/reference/largeaddressaware-handle-large-addresses.md index e63c9bf10e..4d3910054e 100644 --- a/docs/build/reference/largeaddressaware-handle-large-addresses.md +++ b/docs/build/reference/largeaddressaware-handle-large-addresses.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /LARGEADDRESSAWARE (Handle Large Addresses)" title: "/LARGEADDRESSAWARE (Handle Large Addresses)" -ms.date: "11/04/2016" +description: "Learn more about: /LARGEADDRESSAWARE (Handle Large Addresses)" +ms.date: "02/12/2024" f1_keywords: ["VC.Project.VCLinkerTool.LargeAddressAware", "/largeaddressaware"] helpviewer_keywords: ["LARGEADDRESSAWARE linker option", "-LARGEADDRESSAWARE linker option", "/LARGEADDRESSAWARE linker option"] -ms.assetid: a29756c8-e893-47a9-9750-1f0d25359385 --- # /LARGEADDRESSAWARE (Handle Large Addresses) @@ -14,9 +13,11 @@ ms.assetid: a29756c8-e893-47a9-9750-1f0d25359385 ## Remarks -The /LARGEADDRESSAWARE option tells the linker that the application can handle addresses larger than 2 gigabytes. In the 64-bit compilers, this option is enabled by default. In the 32-bit compilers, /LARGEADDRESSAWARE:NO is enabled if /LARGEADDRESSAWARE is not otherwise specified on the linker line. +The /LARGEADDRESSAWARE option tells the linker that the application can handle addresses larger than 2 gigabytes. In the 64-bit compilers, this option is enabled by default. In the 32-bit compilers, `/LARGEADDRESSAWARE:NO` is enabled if `/LARGEADDRESSAWARE` is not otherwise specified on the linker line. + +If an application was linked with `/LARGEADDRESSAWARE`, `DUMPBIN` [/HEADERS](headers.md) will display information to that effect. -If an application was linked with /LARGEADDRESSAWARE, DUMPBIN [/HEADERS](headers.md) will display information to that effect. +Linking 64-bit applications with **`/LARGEADDRESSAWARE:NO`** is not recommended because it restricts the available address space, which can result in runtime failures if the app exhausts memory. It may also prevent x64 apps from running on ARM64 systems because the emulation runtime will try to reserve 4GB of virtual address space. If the app was linked with `/LARGEADDRESSAWARE:NO`, the app won't launch because it can't allocate that much address space. ### To set this linker option in the Visual Studio development environment @@ -32,5 +33,5 @@ If an application was linked with /LARGEADDRESSAWARE, DUMPBIN [/HEADERS](headers ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/libpath-additional-libpath.md b/docs/build/reference/libpath-additional-libpath.md index 1ac84a5485..64cfdd3f94 100644 --- a/docs/build/reference/libpath-additional-libpath.md +++ b/docs/build/reference/libpath-additional-libpath.md @@ -1,32 +1,29 @@ --- description: "Learn more about: /LIBPATH (Additional Libpath)" title: "/LIBPATH (Additional Libpath)" -ms.date: "11/04/2016" +ms.date: 03/27/2025 f1_keywords: ["/libpath", "VC.Project.VCLinkerTool.AdditionalLibraryDirectories"] helpviewer_keywords: ["LIBPATH linker option", "/LIBPATH linker option", "Additional Libpath linker option", "environment library path override", "-LIBPATH linker option", "library path linker option"] -ms.assetid: 7240af0b-9a3d-4d53-8169-2a92cd6958ba --- -# /LIBPATH (Additional Libpath) +# `/LIBPATH` (Additional Libpath) -``` -/LIBPATH:dir -``` +## Syntax -## Parameters +> /LIBPATH:dir -*dir*
-Specifies a path that the linker will search before it searches the path specified in the LIB environment option. +## Argument + +*`dir`*\ +Specifies a path that the linker searches before it searches the path specified in the `LIB` environment option. When expanded, the fully qualified directory must not exceed `MAX_PATH` (260 characters). ## Remarks -Use the /LIBPATH option to override the environment library path. The linker will first search in the path specified by this option, and then search in the path specified in the LIB environment variable. You can specify only one directory for each /LIBPATH option you enter. If you want to specify more than one directory, you must specify multiple /LIBPATH options. The linker will then search the specified directories in order. +Use the `/LIBPATH` option to override the environment library path. The linker first searches in the path specified by this option, and then searches in the path specified in the `LIB` environment variable. You can specify only one directory for each `/LIBPATH` option you enter. To specify more than one directory, specify multiple `/LIBPATH` options. The linker searches the specified directories in order. ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **General** property page. - 1. Modify the **Additional Library Directories** property. ### To set this linker option programmatically @@ -35,5 +32,5 @@ Use the /LIBPATH option to override the environment library path. The linker wil ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/link-code-for-kernel-mode.md b/docs/build/reference/link-code-for-kernel-mode.md new file mode 100644 index 0000000000..6a9d5e3901 --- /dev/null +++ b/docs/build/reference/link-code-for-kernel-mode.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: /KERNEL (Create kernel mode binary)." +title: /KERNEL +ms.date: "08/25/2023" +--- +# /KERNEL (Create kernel mode binary) + +Create a binary that is suitable for running in kernel mode. + +## Syntax + +> **`/KERNEL`** + +## Remarks + +Causes the linker to emit a warning if any object file or library linked in the binary wasn't compiled with [/kernel](kernel-create-kernel-mode-binary.md). + +Code that can run in kernel mode must be compiled with the **`/kernel`** option. If you link a binary that contains code that wasn't compiled with **`/kernel`**, the binary might not run correctly in kernel mode. + +Code for kernel mode is compiled with a simplified set of C++ language features that are specific to code that runs in kernel mode. The compiler produces warnings for C++ language features that are potentially disruptive but can't be disabled. For more information about compiling code in kernel mode, see [/kernel (Create kernel mode binary)](kernel-create-kernel-mode-binary.md). + +### To set this linker option in Visual Studio + +1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. + +1. In **Additional Options**, enter `/KERNELMODE`. + +## See also + +- [MSVC linker reference](linking.md) +- [MSVC linker options](linker-options.md) +- [Compiler options: /kernel](kernel-create-kernel-mode-binary.md) \ No newline at end of file diff --git a/docs/build/reference/link-input-files.md b/docs/build/reference/link-input-files.md index 793f81974a..80664636c6 100644 --- a/docs/build/reference/link-input-files.md +++ b/docs/build/reference/link-input-files.md @@ -1,42 +1,42 @@ --- description: "Learn more about: LINK Input Files" title: "LINK Input Files" -ms.date: "11/04/2016" +ms.date: 09/01/2022 helpviewer_keywords: ["files [C++], LINK", "module definition files", "resources [C++], linker files", "LINK tool [C++], input files", "module definition files, linker files", "input files [C++], LINK", "linker [C++], input files", "import libraries [C++], linker files", "command input to linker files [C++]"] ms.assetid: bb26fcc5-509a-4620-bc3e-b6c6e603a412 --- -# LINK Input Files +# LINK input files -You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK does not use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. +You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK doesn't use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. -Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [/DEFAULTLIB (Specify Default Library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. +Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [`/DEFAULTLIB` (Specify default library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. > [!NOTE] -> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (.def). +> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (`.def`). LINK uses the following types of input files: -- [.obj files](dot-obj-files-as-linker-input.md) +- [`.obj` files](dot-obj-files-as-linker-input.md) -- [.netmodule files](netmodule-files-as-linker-input.md) +- [`.netmodule` files](netmodule-files-as-linker-input.md) -- [.lib files](dot-lib-files-as-linker-input.md) +- [`.lib` files](dot-lib-files-as-linker-input.md) -- [.exp files](dot-exp-files-as-linker-input.md) +- [`.exp` files](dot-exp-files-as-linker-input.md) -- [.def files](dot-def-files-as-linker-input.md) +- [`.def` files](dot-def-files-as-linker-input.md) -- [.pdb files](dot-pdb-files-as-linker-input.md) +- [`.pdb` files](dot-pdb-files-as-linker-input.md) -- [.res files](dot-res-files-as-linker-input.md) +- [`.res` files](dot-res-files-as-linker-input.md) -- [.exe files](dot-exe-files-as-linker-input.md) +- [`.exe` files](dot-exe-files-as-linker-input.md) -- [.txt files](dot-txt-files-as-linker-input.md) +- [`.txt` files](dot-txt-files-as-linker-input.md) -- [.ilk files](dot-ilk-files-as-linker-input.md) +- [`.ilk` files](dot-ilk-files-as-linker-input.md) ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/link-repro-full-path-rsp.md b/docs/build/reference/link-repro-full-path-rsp.md new file mode 100644 index 0000000000..c08892e4c7 --- /dev/null +++ b/docs/build/reference/link-repro-full-path-rsp.md @@ -0,0 +1,51 @@ +--- +description: "Learn more about: /LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files)" +title: "/LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files)" +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.LinkReproFullPathRSP", "/LINKREPROFULLPATHRSP"] +helpviewer_keywords: ["/LINKREPROFULLPATHRSP linker option", "-LINKREPROFULLPATHRSP linker option", "LINKREPROFULLPATHRSP linker option"] +--- +# `/LINKREPROFULLPATHRSP` (Generate file containing absolute paths of linked files) + +Generates a response file (`.RSP`) containing the absolute paths of all the files the linker took as input. + +This flag was introduced in Visual Studio 2022 version 17.11. + +## Syntax + +> **/LINKREPROFULLPATHRSP:filename** + +## Argument + +*`filename`*\ +Specifies the name of the response file to create. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + +## Remarks + +Rather than generate a full link repro like `/LINKREPRO`, which copies all the files to a directory and creates a response file with relative paths to that directory, this option writes the names of the files used during linking to the specified file. + +For example, given: +- a directory `c:\temp\test` that contains the files `test.cpp`, `f1.cpp`, `f2.cpp` +- the linker command line: `link f1.obj f2.obj test.obj /out:test.exe /LINKREPROFULLPATHRSP:test.rsp` +The linker produces `test.rsp` containing the following lines to reflect the fully qualified paths of the input files: + +```cmd +"c:\temp\test\f1.obj" +"c:\temp\test\f2.obj" +"c:\temp\test\test.obj" +``` + +### To set this linker option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Enter *`/LINKREPROFULLPATHRSP:file.rsp`* into **Additional Options**. Choose **OK** or **Apply** to apply the change. + +### To set this linker option programmatically + +- See [VCLinkerTool.AdditionalOptions](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.additionaloptions) + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/linker-options.md b/docs/build/reference/linker-options.md index 4fb8cbd463..5749d0c236 100644 --- a/docs/build/reference/linker-options.md +++ b/docs/build/reference/linker-options.md @@ -1,136 +1,140 @@ --- title: "MSVC Linker options" description: "A list of the options supported by the Microsoft LINK linker." -ms.date: "09/01/2020" +ms.date: 03/14/2025 f1_keywords: ["link"] helpviewer_keywords: ["linker [C++]", "linker [C++], options listed", "libraries [C++], linking to COFF", "LINK tool [C++], linker options"] -ms.assetid: c1d51b8a-bd23-416d-81e4-900e02b2c129 --- # Linker options -LINK.exe links Common Object File Format (COFF) object files and libraries to create an executable (.exe) file or a dynamic-link library (DLL). +LINK.exe links Common Object File Format (COFF) object files and libraries to create an executable (EXE) file or a dynamic-link library (DLL). -The following table lists options for LINK.exe. For more information about LINK, see: +The following table lists options for `LINK.exe`. For more information about LINK, see: -- [Compiler-Controlled LINK Options](compiler-controlled-link-options.md) +- [Compiler-controlled LINK options](compiler-controlled-link-options.md) +- [LINK input files](link-input-files.md) +- [LINK output](link-output.md) +- [Reserved words](reserved-words.md) -- [LINK Input Files](link-input-files.md) +Linker options aren't case-sensitive; for example, `/base` and `/BASE` mean the same thing. For details on how to specify each option on the command line or in Visual Studio, see the documentation for that option. -- [LINK Output](link-output.md) - -- [Reserved Words](reserved-words.md) - -On the command line, linker options aren't case-sensitive; for example, `/base` and `/BASE` mean the same thing. For details on how to specify each option on the command line or in Visual Studio, see the documentation for that option. - -You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify some linker options. +You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to specify some linker options. ## Linker options listed alphabetically -|Option|Purpose| -|------------|-------------| -|[@](at-specify-a-linker-response-file.md)|Specifies a response file.| -|[/ALIGN](align-section-alignment.md)|Specifies the alignment of each section.| -|[/ALLOWBIND](allowbind-prevent-dll-binding.md)|Specifies that a DLL can't be bound.| -|[/ALLOWISOLATION](allowisolation-manifest-lookup.md)|Specifies behavior for manifest lookup.| -|[/APPCONTAINER](appcontainer-windows-store-app.md)|Specifies whether the app must run within an appcontainer process environment.| -|[/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md)|Adds the to a managed image.| -|[/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md)|Creates a link to a managed resource.| -|[/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md)|Specifies that a Microsoft intermediate language (MSIL) module should be imported into the assembly.| -|[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md)|Embeds a managed resource file in an assembly.| -|[/BASE](base-base-address.md)|Sets a base address for the program.| -|[/CETCOMPAT](cetcompat.md)|Marks the binary as CET Shadow Stack compatible.| -|[/CGTHREADS](cgthreads-compiler-threads.md)|Sets number of cl.exe threads to use for optimization and code generation when link-time code generation is specified.| -|[/CLRIMAGETYPE](clrimagetype-specify-type-of-clr-image.md)|Sets the type (IJW, pure, or safe) of a CLR image.| -|[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md)|Preserves the last error code of functions that are called through the P/Invoke mechanism.| -|[/CLRTHREADATTRIBUTE](clrthreadattribute-set-clr-thread-attribute.md)|Specifies the threading attribute to apply to the entry point of your CLR program.| -|[/CLRUNMANAGEDCODECHECK](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md)|Specifies whether the linker will apply the SuppressUnmanagedCodeSecurity attribute to linker-generated PInvoke stubs that call from managed code into native DLLs.| -|[/DEBUG](debug-generate-debug-info.md)|Creates debugging information.| -|[/DEBUGTYPE](debugtype-debug-info-options.md)|Specifies which data to include in debugging information.| -|[/DEF](def-specify-module-definition-file.md)|Passes a module-definition (.def) file to the linker.| -|[/DEFAULTLIB](defaultlib-specify-default-library.md)|Searches the specified library when external references are resolved.| -|[/DELAY](delay-delay-load-import-settings.md)|Controls the delayed loading of DLLs.| -|[/DELAYLOAD](delayload-delay-load-import.md)|Causes the delayed loading of the specified DLL.| -|[/DELAYSIGN](delaysign-partially-sign-an-assembly.md)|Partially signs an assembly.| -|[/DEPENDENTLOADFLAG](dependentloadflag.md)|Sets default flags on dependent DLL loads.| -|[/DLL](dll-build-a-dll.md)|Builds a DLL.| -|[/DRIVER](driver-windows-nt-kernel-mode-driver.md)|Creates a kernel mode driver.| -|[/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md)|Specifies whether to generate an executable image that's rebased at load time by using the address space layout randomization (ASLR) feature.| -|[/ENTRY](entry-entry-point-symbol.md)|Sets the starting address.| -|[/ERRORREPORT](errorreport-report-internal-linker-errors.md)| Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -|[/EXPORT](export-exports-a-function.md)|Exports a function.| -|[/FILEALIGN](filealign.md)|Aligns sections within the output file on multiples of a specified value.| -|[/FIXED](fixed-fixed-base-address.md)|Creates a program that can be loaded only at its preferred base address.| -|[/FORCE](force-force-file-output.md)|Forces a link to complete even with unresolved symbols or symbols defined more than once.| -|[/FUNCTIONPADMIN](functionpadmin-create-hotpatchable-image.md)|Creates an image that can be hot patched.| -|[/GENPROFILE, /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)|Both of these options specify generation of a *`.pgd`* file by the linker to support profile-guided optimization (PGO). /GENPROFILE and /FASTGENPROFILE use different default parameters.| -|[/GUARD](guard-enable-guard-checks.md)|Enables Control Flow Guard protection.| -|[/HEAP](heap-set-heap-size.md)|Sets the size of the heap, in bytes.| -|[/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md)|Specifies support for high-entropy 64-bit address space layout randomization (ASLR).| -|[/IDLOUT](idlout-name-midl-output-files.md)|Specifies the name of the *`.idl`* file and other MIDL output files.| -|[/IGNORE](ignore-ignore-specific-warnings.md)|Suppresses output of specified linker warnings.| -|[/IGNOREIDL](ignoreidl-don-t-process-attributes-into-midl.md)|Prevents the processing of attribute information into an *`.idl`* file.| -|[/IMPLIB](implib-name-import-library.md)|Overrides the default import library name.| -|[/INCLUDE](include-force-symbol-references.md)|Forces symbol references.| -|[/INCREMENTAL](incremental-link-incrementally.md)|Controls incremental linking.| -|[/INFERASANLIBS](inferasanlibs.md)|Uses inferred sanitizer libraries.| -|[/INTEGRITYCHECK](integritycheck-require-signature-check.md)|Specifies that the module requires a signature check at load time.| -|[/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md)|Specifies a key container to sign an assembly.| -|[/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md)|Specifies a key or key pair to sign an assembly.| -|[/LARGEADDRESSAWARE](largeaddressaware-handle-large-addresses.md)|Tells the compiler that the application supports addresses larger than two gigabytes| -|[/LIBPATH](libpath-additional-libpath.md)|Specifies a path to search before the environmental library path.| -|[/LINKREPRO](linkrepro.md)|Specifies a path to generate link repro artifacts in.| -|[/LINKREPROTARGET](linkreprotarget.md)|Generates a link repro only when producing the specified target.16.1| -|[/LTCG](ltcg-link-time-code-generation.md)|Specifies link-time code generation.| -|[/MACHINE](machine-specify-target-platform.md)|Specifies the target platform.| -|[/MANIFEST](manifest-create-side-by-side-assembly-manifest.md)|Creates a side-by-side manifest file and optionally embeds it in the binary.| -|[/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md)|Specifies a \ section in the manifest file.| -|[/MANIFESTFILE](manifestfile-name-manifest-file.md)|Changes the default name of the manifest file.| -|[/MANIFESTINPUT](manifestinput-specify-manifest-input.md)|Specifies a manifest input file for the linker to process and embed in the binary. You can use this option multiple times to specify more than one manifest input file.| -|[/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md)|Specifies whether User Account Control (UAC) information is embedded in the program manifest.| -|[/MAP](map-generate-mapfile.md)|Creates a mapfile.| -|[/MAPINFO](mapinfo-include-information-in-mapfile.md)|Includes the specified information in the mapfile.| -|[/MERGE](merge-combine-sections.md)|Combines sections.| -|[/MIDL](midl-specify-midl-command-line-options.md)|Specifies MIDL command-line options.| -|[/NATVIS](natvis-add-natvis-to-pdb.md)|Adds debugger visualizers from a Natvis file to the program database (PDB).| -|[/NOASSEMBLY](noassembly-create-a-msil-module.md)|Suppresses the creation of a .NET Framework assembly.| -|[/NODEFAULTLIB](nodefaultlib-ignore-libraries.md)|Ignores all (or the specified) default libraries when external references are resolved.| -|[/NOENTRY](noentry-no-entry-point.md)|Creates a resource-only DLL.| -|[/NOLOGO](nologo-suppress-startup-banner-linker.md)|Suppresses the startup banner.| -|[/NXCOMPAT](nxcompat-compatible-with-data-execution-prevention.md)|Marks an executable as verified to be compatible with the Windows Data Execution Prevention feature.| -|[/OPT](opt-optimizations.md)|Controls LINK optimizations.| -|[/ORDER](order-put-functions-in-order.md)|Places COMDATs into the image in a predetermined order.| -|[/OUT](out-output-file-name.md)|Specifies the output file name.| -|[/PDB](pdb-use-program-database.md)|Creates a PDB file.| -|[/PDBALTPATH](pdbaltpath-use-alternate-pdb-path.md)|Uses an alternate location to save a PDB file.| -|[/PDBSTRIPPED](pdbstripped-strip-private-symbols.md)|Creates a PDB file that has no private symbols.| -|[/PGD](pgd-specify-database-for-profile-guided-optimizations.md)|Specifies a *`.pgd`* file for profile-guided optimizations.| -|[/POGOSAFEMODE](pogosafemode-linker-option.md)|**Obsolete** Creates a thread-safe PGO instrumented build.| -|[/PROFILE](profile-performance-tools-profiler.md)|Produces an output file that can be used with the Performance Tools profiler.| -|[/RELEASE](release-set-the-checksum.md)|Sets the Checksum in the *`.exe`* header.| -|[/SAFESEH](safeseh-image-has-safe-exception-handlers.md)|Specifies that the image will contain a table of safe exception handlers.| -|[/SECTION](section-specify-section-attributes.md)|Overrides the attributes of a section.| -|[/SOURCELINK](sourcelink.md)|Specifies a SourceLink file to add to the PDB.| -|[/STACK](stack-stack-allocations.md)|Sets the size of the stack in bytes.| -|[/STUB](stub-ms-dos-stub-file-name.md)|Attaches an MS-DOS stub program to a Win32 program.| -|[/SUBSYSTEM](subsystem-specify-subsystem.md)|Tells the operating system how to run the *`.exe`* file.| -|[/SWAPRUN](swaprun-load-linker-output-to-swap-file.md)|Tells the operating system to copy the linker output to a swap file before it's run.| -|[/TLBID](tlbid-specify-resource-id-for-typelib.md)|Specifies the resource ID of the linker-generated type library.| -|[/TLBOUT](tlbout-name-dot-tlb-file.md)|Specifies the name of the *`.tlb`* file and other MIDL output files.| -|[/TSAWARE](tsaware-create-terminal-server-aware-application.md)|Creates an application that is designed specifically to run under Terminal Server.| -|[/USEPROFILE](useprofile.md)|Uses profile-guided optimization training data to create an optimized image.| -|[/VERBOSE](verbose-print-progress-messages.md)|Prints linker progress messages.| -|[/VERSION](version-version-information.md)|Assigns a version number.| -|[/WHOLEARCHIVE](wholearchive-include-all-library-object-files.md)|Includes every object file from specified static libraries.| -|[/WINMD](winmd-generate-windows-metadata.md)|Enables generation of a Windows Runtime Metadata file.| -|[/WINMDFILE](winmdfile-specify-winmd-file.md)|Specifies the file name for the Windows Runtime Metadata (winmd) output file that's generated by the [/WINMD](winmd-generate-windows-metadata.md) linker option.| -|[/WINMDKEYFILE](winmdkeyfile-specify-winmd-key-file.md)|Specifies a key or key pair to sign a Windows Runtime Metadata file.| -|[/WINMDKEYCONTAINER](winmdkeycontainer-specify-key-container.md)|Specifies a key container to sign a Windows Metadata file.| -|[/WINMDDELAYSIGN](winmddelaysign-partially-sign-a-winmd.md)|Partially signs a Windows Runtime Metadata (.winmd) file by placing the public key in the winmd file.| -|[/WX](wx-treat-linker-warnings-as-errors.md)|Treats linker warnings as errors.| +| Option | Purpose | +|--|--| +| [`@`](at-specify-a-linker-response-file.md) | Specifies a response file. | +| [`/ALIGN`](align-section-alignment.md) | Specifies the alignment of each section. | +| [`/ALLOWBIND`](allowbind-prevent-dll-binding.md) | Specifies that a DLL can't be bound. | +| [`/ALLOWISOLATION`](allowisolation-manifest-lookup.md) | Specifies behavior for manifest lookup. | +| [`/APPCONTAINER`](appcontainer-windows-store-app.md) | Specifies whether the app must run within an appcontainer process environment. | +| [`/ARM64XFUNCTIONPADMINX64`](arm64-function-pad-min-x64.md) | Specifies the minimum number of bytes of padding between x64 functions in ARM64X images.17.8 | +| [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) | Adds the to a managed image. | +| [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) | Creates a link to a managed resource. | +| [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) | Specifies that a Microsoft intermediate language (MSIL) module should be imported into the assembly. | +| [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) | Embeds a managed resource file in an assembly. | +| [`/BASE`](base-base-address.md) | Sets a base address for the program. | +| [`/CETCOMPAT`](cetcompat.md) | Marks the binary as CET Shadow Stack compatible. | +| [`/CGTHREADS`](cgthreads-compiler-threads.md) | Sets number of cl.exe threads to use for optimization and code generation when link-time code generation is specified. | +| [`/CLRIMAGETYPE`](clrimagetype-specify-type-of-clr-image.md) | Sets the type (IJW, pure, or safe) of a CLR image. | +| [`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md) | Preserves the last error code of functions that are called through the P/Invoke mechanism. | +| [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md) | Specifies the threading attribute to apply to the entry point of your CLR program. | +| [`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) | Specifies whether the linker applies the `SuppressUnmanagedCodeSecurity` attribute to linker-generated P/Invoke stubs that call from managed code into native DLLs. | +| [`/DEBUG`](debug-generate-debug-info.md) | Creates debugging information. | +| [`/DEBUGTYPE`](debugtype-debug-info-options.md) | Specifies which data to include in debugging information. | +| [`/DEF`](def-specify-module-definition-file.md) | Passes a module-definition (.def) file to the linker. | +| [`/DEFAULTLIB`](defaultlib-specify-default-library.md) | Searches the specified library when external references are resolved. | +| [`/DELAY`](delay-delay-load-import-settings.md) | Controls the delayed loading of DLLs. | +| [`/DELAYLOAD`](delayload-delay-load-import.md) | Causes the delayed loading of the specified DLL. | +| [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) | Partially signs an assembly. | +| [`/DEPENDENTLOADFLAG`](dependentloadflag.md) | Sets default flags on dependent DLL loads. | +| [`/DLL`](dll-build-a-dll.md) | Builds a DLL. | +| [`/DRIVER`](driver-windows-nt-kernel-mode-driver.md) | Creates a kernel mode driver. | +| [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) | Specifies whether to generate an executable image that's rebased at load time by using the address space layout randomization (ASLR) feature. | +| [`/DYNAMICDEOPT`](dynamic-deopt-linker.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) and step in anywhere with on-demand function deoptimization. | +| [`/ENTRY`](entry-entry-point-symbol.md) | Sets the starting address. | +| [`/ERRORREPORT`](errorreport-report-internal-linker-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| [`/EXPORT`](export-exports-a-function.md) | Exports a function. | +| [`/FILEALIGN`](filealign.md) | Aligns sections within the output file on multiples of a specified value. | +| [`/FIXED`](fixed-fixed-base-address.md) | Creates a program that can be loaded only at its preferred base address. | +| [`/FORCE`](force-force-file-output.md) | Forces a link to complete even with unresolved symbols or symbols defined more than once. | +| [`/FUNCTIONPADMIN`](functionpadmin-create-hotpatchable-image.md) | Creates an image that can be hot patched. | +| [`/GENPROFILE`, `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) | Both of these options specify generation of a *`.pgd`* file by the linker to support profile-guided optimization (PGO). /GENPROFILE and /FASTGENPROFILE use different default parameters. | +| [`/GUARD`](guard-enable-guard-checks.md) | Enables Control Flow Guard protection. | +| [`/HEAP`](heap-set-heap-size.md) | Sets the size of the heap, in bytes. | +| [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) | Specifies support for high-entropy 64-bit address space layout randomization (ASLR). | +| [`/IDLOUT`](idlout-name-midl-output-files.md) | Specifies the name of the *`.idl`* file and other MIDL output files. | +| [`/IGNORE`](ignore-ignore-specific-warnings.md) | Suppresses output of specified linker warnings. | +| [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) | Prevents the processing of attribute information into an *`.idl`* file. | +| [`/ILK`](ilk-name-incremental-database-file.md) | Overrides the default incremental database file name. | +| [`/IMPLIB`](implib-name-import-library.md) | Overrides the default import library name. | +| [`/INCLUDE`](include-force-symbol-references.md) | Forces symbol references. | +| [`/INCREMENTAL`](incremental-link-incrementally.md) | Controls incremental linking. | +| [`/INFERASANLIBS`](inferasanlibs.md) | Uses inferred sanitizer libraries. | +| [`/INTEGRITYCHECK`](integritycheck-require-signature-check.md) | Specifies that the module requires a signature check at load time. | +| [`/KERNEL`](link-code-for-kernel-mode.md) | Create a kernel mode binary. | +| [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) | Specifies a key container to sign an assembly. | +| [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) | Specifies a key or key pair to sign an assembly. | +| [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) | Tells the compiler that the application supports addresses larger than 2 gigabytes | +| [`/LIBPATH`](libpath-additional-libpath.md) | Specifies a path to search before the environmental library path. | +| [`/LINKREPRO`](linkrepro.md) | Specifies a path to generate link repro artifacts in. | +| [`/LINKREPROFULLPATHRSP`](link-repro-full-path-rsp.md) | Generates a response file containing the absolute paths to all the files that the linker took as input. | +| [`/LINKREPROTARGET`](linkreprotarget.md) | Generates a link repro only when producing the specified target.16.1 | +| [`/LTCG`](ltcg-link-time-code-generation.md) | Specifies link-time code generation. | +| [`/MACHINE`](machine-specify-target-platform.md) | Specifies the target platform. | +| [`/MANIFEST`](manifest-create-side-by-side-assembly-manifest.md) | Creates a side-by-side manifest file and optionally embeds it in the binary. | +| [`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) | Specifies a \ section in the manifest file. | +| [`/MANIFESTFILE`](manifestfile-name-manifest-file.md) | Changes the default name of the manifest file. | +| [`/MANIFESTINPUT`](manifestinput-specify-manifest-input.md) | Specifies a manifest input file for the linker to process and embed in the binary. You can use this option multiple times to specify more than one manifest input file. | +| [`/MANIFESTUAC`](manifestuac-embeds-uac-information-in-manifest.md) | Specifies whether User Account Control (UAC) information is embedded in the program manifest. | +| [`/MAP`](map-generate-mapfile.md) | Creates a mapfile. | +| [`/MAPINFO`](mapinfo-include-information-in-mapfile.md) | Includes the specified information in the mapfile. | +| [`/MERGE`](merge-combine-sections.md) | Combines sections. | +| [`/MIDL`](midl-specify-midl-command-line-options.md) | Specifies MIDL command-line options. | +| [`/NATVIS`](natvis-add-natvis-to-pdb.md) | Adds debugger visualizers from a Natvis file to the program database (PDB). | +| [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) | Suppresses the creation of a .NET Framework assembly. | +| [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) | Ignores all (or the specified) default libraries when external references are resolved. | +| [`/NOENTRY`](noentry-no-entry-point.md) | Creates a resource-only DLL. | +| [`/NOFUNCTIONPADSECTION`](no-function-pad-section.md) | Disables function padding for functions in the specified section.17.8 | +| [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) | Suppresses the startup banner. | +| [`/NXCOMPAT`](nxcompat-compatible-with-data-execution-prevention.md) | Marks an executable as verified to be compatible with the Windows Data Execution Prevention feature. | +| [`/OPT`](opt-optimizations.md) | Controls LINK optimizations. | +| [`/ORDER`](order-put-functions-in-order.md) | Places COMDATs into the image in a predetermined order. | +| [`/OUT`](out-output-file-name.md) | Specifies the output file name. | +| [`/PDB`](pdb-use-program-database.md) | Creates a PDB file. | +| [`/PDBALTPATH`](pdbaltpath-use-alternate-pdb-path.md) | Uses an alternate location to save a PDB file. | +| [`/PDBSTRIPPED`](pdbstripped-strip-private-symbols.md) | Creates a PDB file that has no private symbols. | +| [`/PGD`](pgd-specify-database-for-profile-guided-optimizations.md) | Specifies a *`.pgd`* file for profile-guided optimizations. | +| [`/POGOSAFEMODE`](pogosafemode-linker-option.md) | **Obsolete** Creates a thread-safe PGO instrumented build. | +| [`/PROFILE`](profile-performance-tools-profiler.md) | Produces an output file that can be used with the Performance Tools profiler. | +| [`/RELEASE`](release-set-the-checksum.md) | Sets the Checksum in the *`.exe`* header. | +| [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) | Specifies that the image will contain a table of safe exception handlers. | +| [`/SECTION`](section-specify-section-attributes.md) | Overrides the attributes of a section. | +| [`/SOURCELINK`](sourcelink.md) | Specifies a SourceLink file to add to the PDB. | +| [`/STACK`](stack-stack-allocations.md) | Sets the size of the stack in bytes. | +| [`/STUB`](stub-ms-dos-stub-file-name.md) | Attaches an MS-DOS stub program to a Win32 program. | +| [`/SUBSYSTEM`](subsystem-specify-subsystem.md) | Tells the operating system how to run the *`.exe`* file. | +| [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) | Tells the operating system to copy the linker output to a swap file before it's run. | +| [`/TIME`](time-linker-time-information.md) | Output linker pass timing information. | +| [`/TLBID`](tlbid-specify-resource-id-for-typelib.md) | Specifies the resource ID of the linker-generated type library. | +| [`/TLBOUT`](tlbout-name-dot-tlb-file.md) | Specifies the name of the *`.tlb`* file and other MIDL output files. | +| [`/TSAWARE`](tsaware-create-terminal-server-aware-application.md) | Creates an application that is designed specifically to run under Terminal Server. | +| [`/USEPROFILE`](useprofile.md) | Uses profile-guided optimization training data to create an optimized image. | +| [`/VERBOSE`](verbose-print-progress-messages.md) | Prints linker progress messages. | +| [`/VERSION`](version-version-information.md) | Assigns a version number. | +| [`/WHOLEARCHIVE`](wholearchive-include-all-library-object-files.md) | Includes every object file from specified static libraries. | +| [`/WINMD`](winmd-generate-windows-metadata.md) | Enables generation of a Windows Runtime Metadata file. | +| [`/WINMDFILE`](winmdfile-specify-winmd-file.md) | Specifies the file name for the Windows Runtime Metadata (winmd) output file that's generated by the [`/WINMD`](winmd-generate-windows-metadata.md) linker option. | +| [`/WINMDKEYFILE`](winmdkeyfile-specify-winmd-key-file.md) | Specifies a key or key pair to sign a Windows Runtime Metadata file. | +| [`/WINMDKEYCONTAINER`](winmdkeycontainer-specify-key-container.md) | Specifies a key container to sign a Windows Metadata file. | +| [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) | Partially signs a Windows Runtime Metadata (*`.winmd`*) file by placing the public key in the winmd file. | +| [`/WX`](wx-treat-linker-warnings-as-errors.md) | Treats linker warnings as errors. | -16.1 This option is available starting in Visual Studio 2019 version 16.1. +16.1 This option is available starting in Visual Studio 2019 version 16.1.\ +17.8 This option is available starting in Visual Studio 2022 version 17.8. ## See also -[C/C++ Building Reference](c-cpp-building-reference.md)\ +[C/C++ building reference](c-cpp-building-reference.md)\ [MSVC linker reference](linking.md) diff --git a/docs/build/reference/linker-property-pages.md b/docs/build/reference/linker-property-pages.md index b198808f57..27a8a52d11 100644 --- a/docs/build/reference/linker-property-pages.md +++ b/docs/build/reference/linker-property-pages.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Linker Property Pages" title: "Linker Property Pages" -ms.date: "07/24/2019" +description: "Learn more about: Linker Property Pages" +ms.date: 09/07/2022 ms.topic: "article" -ms.assetid: 7e7671e5-a35a-4e67-9bdb-661d75c4d11e +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreImportLibrary", "VC.Project.VCLinkerTool.RegisterOutput", "VC.Project.VCLinkerTool.PerUserRedirection", "VC.Project.VCLinkerTool.LinkLibraryDependencies", "VC.Project.VCLinkerTool.UseLibraryDependencyInputs"] --- # Linker Property Pages @@ -13,7 +13,7 @@ The following properties are found under **Project** > **Properties** > **Config ### Output File -The [/OUT](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. +The [`/OUT`](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. ### Show Progress @@ -31,150 +31,150 @@ Prints Linker Progress Messages ### Version -The [/VERSION](version-version-information.md) option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN /HEADERS to see the image version field of the OPTIONAL HEADER VALUES to see the effect of **/VERSION**. +The [`/VERSION`](version-version-information.md) option tells the linker to put a version number in the header of the *`.exe`* or *`.dll`* file. Use `DUMPBIN /HEADERS` to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. ### Enable Incremental Linking -Enables incremental linking. ([/INCREMENTAL](incremental-link-incrementally.md), /INCREMENTAL:NO) +Enables incremental linking. ([`/INCREMENTAL, /INCREMENTAL:NO`](incremental-link-incrementally.md)) ### Suppress Startup Banner -The [/NOLOGO](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. +The [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. ### Ignore Import Library -This property tells the linker not to link any .lib output generated from this build into any dependent project. It allows the project system to handle .dll files that don't produce a .lib file when built. If a project depends on another project that produces a DLL, the project system automatically links the .lib file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a .lib file. If no export .lib file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the .lib file, and causes any project that depends on this project to not link with the nonexistent .lib file. +This property tells the linker not to link any *`.lib`* output generated from this build into any dependent project. It allows the project system to handle *`.dll`* files that don't produce a *`.lib`* file when built. If a project depends on another project that produces a DLL, the project system automatically links the *`.lib`* file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a *`.lib`* file. If no export *`.lib`* file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the *`.lib`* file, and causes any project that depends on this project to not link with the nonexistent *`.lib`* file. To programmatically access this property, see . ### Register Output -Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on .dll projects. For .exe projects, this property is ignored. To register an .exe output, set a postbuild event on the configuration to do the custom registration that is always required for registered .exe files. +Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on *`.dll`* projects. For *`.exe`* projects, this property is ignored. To register an *`.exe`* output, set a postbuild event on the configuration to do the custom registration that is always required for registered *`.exe`* files. To programmatically access this property, see . ### Per-user Redirection -Registration in Visual Studio has traditionally been done in HKEY_CLASSES_ROOT (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. +Registration in Visual Studio has traditionally been done in `HKEY_CLASSES_ROOT` (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. -Per-user redirection forces any writes to HKCR to be redirected to HKEY\_CURRENT\_USER (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. +Per-user redirection forces any writes to HKCR to be redirected to `HKEY_CURRENT_USER` (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. ### Additional Library Directories -Allows the user to override the environmental library path. ([/LIBPATH](libpath-additional-libpath.md):folder) +Allows the user to override the environment's library path. ([`/LIBPATH:folder`](libpath-additional-libpath.md)) ### Link Library Dependencies -Specifies whether to link the .lib files that are produced by dependent projects. Typically, you want to link in the .lib files, but it may not be the case for certain DLLs. +Specifies whether to link the *`.lib`* files that are produced by dependent projects. Typically, you want to link in the *`.lib`* files, but it may not be the case for certain DLLs. -You can also specify a .obj file by providing the file name and relative path, for example "..\\..\MyLibProject\MyObjFile.obj". If the source code for the .obj file #includes a precompiled header, for example pch.h, then the pch.obj file is located in the same folder as MyObjFile.obj. You must also add pch.obj as an additional dependency. +You can also specify a *`.obj`* file by providing the file name and relative path, for example, *`..\..\MyLibProject\MyObjFile.obj`*. If the source code for the *`.obj`* file has a `#include` for a precompiled header, for example, *`pch.h`*, then the *`pch.obj`* file is located in the same folder as *`MyObjFile.obj`*. You must also add *`pch.obj`* as an additional dependency. ### Use Library Dependency Inputs -Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a .lib file, incremental linking is disabled. If there are many dependent projects that produce .lib files, building the application can take a long time. When this property is set to **Yes**, the project system links in the .obj files for .libs produced by dependent projects, enabling incremental linking. +Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a *`.lib`* file, incremental linking is disabled. If there are many dependent projects that produce *`.lib`* files, building the application can take a long time. When this property is set to **Yes**, the project system links in the *`.obj`* files for *`.lib`* files produced by dependent projects, enabling incremental linking. -For information about how to access the **General** linker property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +For information about how to access the **General** linker property page, see [Set compiler and build properties](../working-with-project-properties.md). ### Link Status -Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([/LTCG](ltcg-link-time-code-generation.md):STATUS|LTCG:NOSTATUS) +Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([`/LTCG:STATUS|LTCG:NOSTATUS`](ltcg-link-time-code-generation.md)) ### Prevent DLL Binding -[/ALLOWBIND](allowbind-prevent-dll-binding.md):NO sets a bit in a DLL's header that indicates to Bind.exe that the image isn't allowed to be bound. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). +[`/ALLOWBIND:NO`](allowbind-prevent-dll-binding.md) sets a bit in a DLL's header that indicates to *`Bind.exe`* that binding the image isn't allowed. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). ### Treat Linker Warning As Errors -[/WX](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. +[`/WX`](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. ### Force File Output -The [/FORCE](force-force-file-output.md) option tells the linker to create an .exe file or DLL even if a symbol is referenced but not defined, or is multiply defined. It may create invalid .exe file. +The [`/FORCE`](force-force-file-output.md) option tells the linker to create an *`.exe`* file or DLL even if a symbol is referenced but not defined (**`UNRESOLVED`**), or is defined multiple times (**`MULTIPLE`**). It may create an invalid *`.exe`* file. **Choices** -- **Enabled** - /FORCE with no arguments implies both multiple and unresolved. -- **Multiply Defined Symbol Only** - Use /FORCE:MULTIPLE to create an output file, even if LINK finds more than one definition for a symbol. -- **Undefined Symbol Only** - Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +- **Enabled** - **`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. +- **Multiply Defined Symbol Only** - Use **`/FORCE:MULTIPLE`** to create an output file, even if LINK finds more than one definition for a symbol. +- **Undefined Symbol Only** - Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. ### Create Hot Patchable Image -Prepares an image for hotpatching. +Prepares an image for hot patching. **Choices** -- **Enabled** - Prepares an image for hotpatching. -- **X86 Image Only** - Prepares an X86 image for hotpatching. -- **X64 Image Only** - Prepares an X64 image for hotpatching. -- **Itanium Image Only** - Prepares an Itanium image for hotpatching. +- **Enabled** - Prepares an image for hot patching. +- **X86 Image Only** - Prepares an X86 image for hot patching. +- **X64 Image Only** - Prepares an X64 image for hot patching. +- **Itanium Image Only** - Prepares an Itanium image for hot patching. ### Specify Section Attributes -The [/SECTION](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The [`/SECTION`](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. ## Input Property Page ### Additional Dependencies -Specifies additional items to add to the link command line, for example *kernel32.lib*. +Specifies extra dependency items to add to the link command line, for example *`kernel32.lib`*. ### Ignore All Default Libraries -The [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. +The [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. ### Ignore Specific Default Libraries -Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. (/NODEFAULTLIB:[name, name, ...]) +Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. ([`/NODEFAULTLIB:[name, name, ...]`](nodefaultlib-ignore-libraries.md)) ### Module Definition File -The [/DEF](def-specify-module-definition-file.md) option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. +The [`/DEF`](def-specify-module-definition-file.md) option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. ### Add Module to Assembly -The [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module will not be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. +The [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module won't be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. ### Embed Managed Resource File -[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. +[`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. ### Force Symbol References -The [/INCLUDE](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. +The [`/INCLUDE`](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. ### Delay Loaded DLLs -The [/DELAYLOAD](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. +The [`/DELAYLOAD`](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. ### Assembly Link Resource -The [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file; the resource file is not placed in the output file. +The [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file. The linker doesn't place the resource file in the output file. ## Manifest File Property Page ### Generate Manifest -[/MANIFEST](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. +[`/MANIFEST`](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. ### Manifest File -[/MANIFESTFILE](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with .manifest appended. +[`/MANIFESTFILE`](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with *`.manifest`* appended. ### Additional Manifest Dependencies -[/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. +[`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. ### Allow Isolation -Specifies behavior for manifest lookup. ([/ALLOWISOLATION](allowisolation-manifest-lookup.md):NO) +Specifies behavior for manifest lookup. ([`/ALLOWISOLATION:NO`](allowisolation-manifest-lookup.md)) ### Enable User Account Control (UAC) -Specifies whether or not User Account Control is enabled. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md), /MANIFESTUAC:NO) +Specifies whether or not User Account Control is enabled. ([`/MANIFESTUAC, /MANIFESTUAC:NO`](manifestuac-embeds-uac-information-in-manifest.md)) ### UAC Execution Level -Specifies the requested execution level for the application when running with User Account Control. (/MANIFESTUAC:level=[value]) +Specifies the requested execution level for the application when running with User Account Control. ([`/MANIFESTUAC:level=[value]`](manifestuac-embeds-uac-information-in-manifest.md)) **Choices** @@ -184,32 +184,32 @@ Specifies the requested execution level for the application when running with Us ### UAC Bypass UI Protection -Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md):uiAccess=[true | false]) +Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([`/MANIFESTUAC:uiAccess=[true | false]`](manifestuac-embeds-uac-information-in-manifest.md)) ## Debugging Property Page ### Generate Debug Info -This option enables creation of debugging information for the .exe file or the DLL. +This option enables creation of debugging information for the *`.exe`* file or the DLL. **Choices** - **No** - Produces no debugging information. - **Generate Debug Information** - Create a complete Program Database (PDB) ideal for distribution to Microsoft Symbol Server. -- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for edit-link-debug cycle. -- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for edit-link-debug cycle. +- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for a fast edit-link-debug cycle. +- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for a shared edit-link-debug cycle. ### Generate Program Database File -By default, when [/DEBUG](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. +By default, when [`/DEBUG`](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension *`.pdb`*. ### Strip Private Symbols -The [/PDBSTRIPPED](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (/DEBUG, /Z7, /Zd, or /Zi). +The [`/PDBSTRIPPED`](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (**`/DEBUG`**, **`/Z7`**, **`/Zd`**, or **`/Zi`**). ### Generate Map File -The [/MAP](map-generate-mapfile.md) option tells the linker to create a mapfile. +The [`/MAP`](map-generate-mapfile.md) option tells the linker to create a mapfile. ### Map File Name @@ -217,24 +217,24 @@ A user-specified name for the mapfile. It replaces the default name. ### Map Exports -The [/MAPINFO](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the /MAP option. EXPORTS tells the linker to include exported functions. +The [`/MAPINFO`](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the **`/MAP`** option. **`EXPORTS`** tells the linker to include exported functions. ### Debuggable Assembly -[/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) emits the DebuggableAttribute attribute with debug information tracking and disables JIT optimizations. +[`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) emits the `DebuggableAttribute` attribute with debug information tracking and disables JIT optimizations. ## System Property Page ### SubSystem -The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating system how to run the .exe file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. +The [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option tells the operating system how to run the *`.exe`* file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. **Choices** - **Not Set** - No subsystem set. -- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If main or wmain is defined, CONSOLE is the default. -- **Windows** - Application does not require a console, probably because it creates its own windows for interaction with the user. If WinMain or wWinMain is defined, WINDOWS is the default. -- **Native** - Device drivers for Windows NT. If /DRIVER:WDM is specified, NATIVE is the default. +- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If `main` or `wmain` is defined, `CONSOLE` is the default. +- **Windows** - Application doesn't require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined, `WINDOWS` is the default. +- **Native** - Device drivers for Windows NT. If **`/DRIVER:WDM`** is specified, `NATIVE` is the default. - **EFI Application** - EFI Application. - **EFI Boot Service Driver** - EFI Boot Service Driver. - **EFI ROM** - EFI ROM. @@ -243,109 +243,109 @@ The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating syst ### Minimum Required Version -Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. +Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65535. ### Heap Reserve Size -Specifies total heap allocation size in virtual memory. Default is 1 MB. ([/HEAP](heap-set-heap-size.md):reserve) +Specifies total heap allocation size in virtual memory. Default is 1 MB. ([`/HEAP:reserve`](heap-set-heap-size.md)) ### Heap Commit Size -Specifies total heap allocation size in physical memory. Default is 4 KB. ([/HEAP](heap-set-heap-size.md):reserve,commit) +Specifies total heap allocation size in physical memory. Default is 4 KB. ([`/HEAP:reserve,commit`](heap-set-heap-size.md)) ### Stack Reserve Size -Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([/STACK](stack-stack-allocations.md):reserve) +Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([`/STACK:reserve`](stack-stack-allocations.md)) ### Stack Commit Size -Specifies the total stack allocation size in physical memory. Default is 4 KB. ([/STACK](stack-stack-allocations.md):reserve,commit) +Specifies the total stack allocation size in physical memory. Default is 4 KB. ([`/STACK:reserve,commit`](stack-stack-allocations.md)) ### Enable Large Addresses -The [/LARGEADDRESSAWARE](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, /LARGEADDRESSAWARE:NO is enabled if /LARGEADDRESSAWARE is not otherwise specified on the linker line. +The [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, **`/LARGEADDRESSAWARE:NO`** is enabled if **`/LARGEADDRESSAWARE`** isn't otherwise specified on the linker line. ### Terminal Server -The [/TSAWARE](tsaware-create-terminal-server-aware-application.md) option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The [`/TSAWARE`](tsaware-create-terminal-server-aware-application.md) option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. ### Swap Run From CD -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **CD** is specified, the operating system will copy the image on a removable disk to a page file and then load it. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **`CD`** is specified, the operating system will copy the image on a removable disk to a page file, and then load it. ### Swap Run From Network -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **NET** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **`NET`** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. ### Driver -Use the [/DRIVER](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. +Use the [`/DRIVER`](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. **Choices** - **Not Set** - Default driver setting. - **Driver** - Driver -- **UP Only** - /DRIVER:UPONLY causes the linker to add the IMAGE_FILE_UP_SYSTEM_ONLY bit to the characteristics in the output header to specify that it is a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. -- **WDM** - /DRIVER:WDM causes the linker to set the IMAGE_DLLCHARACTERISTICS_WDM_DRIVER bit in the optional header's DllCharacteristics field. +- **UP Only** - **`/DRIVER:UPONLY`** causes the linker to add the `IMAGE_FILE_UP_SYSTEM_ONLY` bit to the characteristics in the output header to specify that it's a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. +- **WDM** - **`/DRIVER:WDM`** causes the linker to set the `IMAGE_DLLCHARACTERISTICS_WDM_DRIVER` bit in the optional header's `DllCharacteristics` field. ## Optimization Property Page ### References -[/OPT](opt-optimizations.md):REF eliminates functions and/or data that's never referenced while /OPT:NOREF keeps functions and/or data that's never referenced. +[`/OPT:REF`](opt-optimizations.md) eliminates functions and/or data that's never referenced while **`/OPT:NOREF`** keeps functions and/or data that's never referenced. ### Enable COMDAT Folding -Use [/OPT](opt-optimizations.md):ICF\[=iterations] to perform identical COMDAT folding. +Use [`/OPT:ICF[=iterations]`](opt-optimizations.md) to perform identical COMDAT folding. ### Function Order -The [/ORDER](order-put-functions-in-order.md)option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. +The [`/ORDER`](order-put-functions-in-order.md) option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. ### Profile Guided Database -Specify .pgd file for profile guided optimizations. ([/PGD](pgd-specify-database-for-profile-guided-optimizations.md)) +Specify the *`.pgd`* file for profile guided optimizations. ([`/PGD`](pgd-specify-database-for-profile-guided-optimizations.md)) ### Link Time Code Generation -Specifies link-time code generation. ([/LTCG](ltcg-link-time-code-generation.md)) +Specifies link-time code generation. ([`/LTCG`](ltcg-link-time-code-generation.md)) **Choices** - **Default** - Default LTCG setting. -- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [/FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). +- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [`/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). - **Use Link Time Code Generation** - Use [Link Time Code Generation](ltcg-link-time-code-generation.md). -- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with :PGINSTRUMENT. +- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with `:PGINSTRUMENT`. - **Profile Guided Optimization - Optimization** - Specifies that the linker should use the profile data created after running the instrumented binary to create an optimized image. -- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the :PGINSTRUMENT phase. +- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the `:PGINSTRUMENT` phase. ## Embedded IDL Property Page ### MIDL Commands -Specify MIDL command line Options. ([/MIDL](midl-specify-midl-command-line-options.md):@responsefile) +Specify MIDL command line options. ([`/MIDL:@responsefile`](midl-specify-midl-command-line-options.md)) ### Ignore Embedded IDL -The [/IGNOREIDL](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code should not be processed into an .idl file. +The [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code shouldn't be processed into an *`.idl`* file. ### Merged IDL Base File Name -The [/IDLOUT](idlout-name-midl-output-files.md) option specifies the name and extension of the .idl file. +The [`/IDLOUT`](idlout-name-midl-output-files.md) option specifies the name and extension of the *`.idl`* file. ### Type Library -The [/TLBOUT](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the .tlb file. +The [`/TLBOUT`](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the *`.tlb`* file. ### TypeLib Resource ID -Allows you to specify the resource ID of the linker-generated type library. ([/TLBID](tlbid-specify-resource-id-for-typelib.md):id) +Allows you to specify the resource ID of the linker-generated type library. ([`/TLBID:id`](tlbid-specify-resource-id-for-typelib.md)) ## Windows Metadata Property Page ### Generate Windows Metadata -Enables or disable generation of Windows Metadata. +Enables or disables generation of Windows Metadata. **Choices** @@ -354,73 +354,73 @@ Enables or disable generation of Windows Metadata. ### Windows Metadata File -The [/WINMDFILE](winmdfile-specify-winmd-file.md) option switch. +The [`/WINMDFILE`](winmdfile-specify-winmd-file.md) option switch. ### Windows Metadata Key File -Specify key or key pair to sign an Windows Metadata. ([/WINMDKEYFILE](winmdkeyfile-specify-winmd-key-file.md):filename) +Specify a key or key pair to sign the Windows Metadata. ([`/WINMDKEYFILE:filename`](winmdkeyfile-specify-winmd-key-file.md)) ### Windows Metadata Key Container -Specify a key container to sign an Windows Metadata. ([/WINMDKEYCONTAINER](winmdkeycontainer-specify-key-container.md):name) +Specify a key container to sign the Windows Metadata. ([`/WINMDKEYCONTAINER:name`](winmdkeycontainer-specify-key-container.md)) ### Windows Metadata Delay Sign -Partially sign an Windows Metadata. Use [/WINMDDELAYSIGN](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is /WINMDDELAYSIGN:NO. +Partially sign the Windows Metadata. Use [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is **`/WINMDDELAYSIGN:NO`**. ## Advanced Property Page ### Entry Point -The [/ENTRY](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an .exe file or DLL. +The [`/ENTRY`](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an *`.exe`* file or DLL. ### No Entry Point -The [/NOENTRY](noentry-no-entry-point.md)option is required for creating a resource-only DLL.Use this option to prevent LINK from linking a reference to `_main` into the DLL. +The [`/NOENTRY`](noentry-no-entry-point.md) option is required for creating a resource-only DLL. Use this option to prevent LINK from linking a reference to `_main` into the DLL. ### Set Checksum -The [/RELEASE](release-set-the-checksum.md) option sets the Checksum in the header of an .exe file. +The [`/RELEASE`](release-set-the-checksum.md) option sets the Checksum in the header of an *`.exe`* file. ### Base Address -Sets a base address for the program. ([/BASE](base-base-address.md):{address\[,size] | @filename,key}) +Sets a base address for the program. ([`/BASE:{address[,size] | @filename,key}`](base-base-address.md)) ### Randomized Base Address -Randomized Base Address. ([/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md)\[:NO]) +Randomized Base Address. ([`/DYNAMICBASE[:NO]`](dynamicbase-use-address-space-layout-randomization.md)) ### Fixed Base Address -Creates a program that can be loaded only at its preferred base address. ([/FIXED](fixed-fixed-base-address.md)\[:NO]) +Creates a program that can be loaded only at its preferred base address. ([`/FIXED[:NO]`](fixed-fixed-base-address.md)) ### Data Execution Prevention (DEP) -Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([/NXCOMPAT](nxcompat-compatible-with-data-execution-prevention.md)\[:NO]) +Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([`/NXCOMPAT[:NO]`](nxcompat-compatible-with-data-execution-prevention.md)) ### Turn Off Assembly Generation -The [/NOASSEMBLY](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. +The [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. ### Unload delay loaded DLL -The **UNLOAD** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([/DELAY](delay-delay-load-import-settings.md):UNLOAD) +The **`UNLOAD`** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([`/DELAY:UNLOAD`](delay-delay-load-import-settings.md)) ### Nobind delay loaded DLL -The **NOBIND** qualifier tells the linker not to include a bindable IAT in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([/DELAY](delay-delay-load-import-settings.md):NOBIND) +The **`NOBIND`** qualifier tells the linker not to include a bindable Import Address Table (IAT) in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([`/DELAY:NOBIND`](delay-delay-load-import-settings.md)) ### Import Library -Overrides the default import library name. ([/IMPLIB](implib-name-import-library.md):filename) +Overrides the default import library name. ([`/IMPLIB:filename`](implib-name-import-library.md)) ### Merge Sections -The [/MERGE](merge-combine-sections.md) option combines the first section (from) with the second section (to), naming the resulting section to. For example, /merge:.rdata=.text. +The [`/MERGE`](merge-combine-sections.md) option combines the first section with the second section, and gives the resulting section the second section name. For example, `/merge:.rdata=.text` merges the `.rdata` section with the `.text` section, and names the combined section `.text`. ### Target Machine -The [/MACHINE](machine-specify-target-platform.md) option specifies the target platform for the program. +The [`/MACHINE`](machine-specify-target-platform.md) option specifies the target platform for the program. **Choices** @@ -440,7 +440,7 @@ The [/MACHINE](machine-specify-target-platform.md) option specifies the target p ### Profile -Produces an output file that can be used with the Performance Tools profiler. Requires GenerateDebugInformation (/[/DEBUG](debug-generate-debug-info.md)) to be set. ([/PROFILE](profile-performance-tools-profiler.md)) +Produces an output file that can be used with the Performance Tools profiler. Requires the **Generate Debug Info** property be set to **GenerateDebugInformation (/DEBUG)**. ([`/PROFILE`](profile-performance-tools-profiler.md)) ### CLR Thread Attribute @@ -450,7 +450,7 @@ Explicitly specify the threading attribute for the entry point of your CLR progr - **MTA threading attribute** - Applies the MTAThreadAttribute attribute to the entry point of your program. - **STA threading attribute** - Applies the STAThreadAttribute attribute to the entry point of your program. -- **Default threading attribute** - Same as not specifying [/CLRTHREADATTRIBUTE](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. +- **Default threading attribute** - Same as not specifying [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. ### CLR Image Type @@ -465,45 +465,45 @@ Sets the type (IJW, pure, or safe) of a CLR image. ### Key File -Specify key or key pair to sign an assembly. ([/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md):filename) +Specify key or key pair to sign an assembly. ([`/KEYFILE:filename`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md)) ### Key Container -Specify a key container to sign an assembly. ([/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md):name) +Specify a key container to sign an assembly. ([`/KEYCONTAINER:name`](keycontainer-specify-a-key-container-to-sign-an-assembly.md)) ### Delay Sign -Partially sign an assembly. Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is /DELAYSIGN:NO. +Partially sign an assembly. Use [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is **`/DELAYSIGN:NO`**. ### CLR Unmanaged Code Check -[/CLRUNMANAGEDCODECHECK](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply SuppressUnmanagedCodeSecurityAttribute to linker-generated PInvoke calls from managed code into native DLLs. +[`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply `SuppressUnmanagedCodeSecurityAttribute` to linker-generated P/Invoke calls from managed code into native DLLs. ### Error Reporting -Allows you to provide internal compiler error (ICE) information directly to the Visual C++ team. +Allows you to provide internal compiler error (ICE) information directly to the Visual Studio C++ team. **Choices** - **PromptImmediately** - Prompt immediately. -- **Queue For Next Login** - Queue for next login. +- **Queue For Next Login** - Queue for next sign-in. - **Send Error Report** - Send error report. - **No Error Report** - No error report. ### SectionAlignment -The [/ALIGN](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. +The [`/ALIGN`](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. ### Preserve Last Error Code for PInvoke Calls -[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with /clr. +[`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. **Choices** -- **Enabled** - Enable CLRSupportLastError. -- **Disabled** - Disable CLRSupportLastError. -- **System Dlls Only** - Enable CLRSupportLastError for system dlls only. +- **Enabled** - Enable **`/CLRSupportLastError`**. +- **Disabled** - Disable **`/CLRSupportLastError`**. +- **System DLLs Only** - Enable **`/CLRSupportLastError`** for system DLLs only. ### Image Has Safe Exception Handlers -When [/SAFESEH](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +When [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. diff --git a/docs/build/reference/linking.md b/docs/build/reference/linking.md index 3cc16467a7..8891ebf554 100644 --- a/docs/build/reference/linking.md +++ b/docs/build/reference/linking.md @@ -1,83 +1,80 @@ --- description: "Learn more about: Linking" title: "MSVC linker reference" -ms.date: "12/10/2018" -ms.assetid: bb736587-d13b-4f3c-8982-3cc2c015c59c +ms.date: 03/27/2025 --- # Linking -In a C++ project, the *linking* step is performed after the compiler has compiled the source code into object files (*.obj). The linker (link.exe) combines the object files into a single executable file. +In a C++ project, the *linking* step is performed after the compiler compiles the source code into object files (*.obj). The linker (`link.exe`) combines the object files into a single executable file. Linker options can be set inside or outside of Visual Studio. Within Visual Studio, you access linker options by right-clicking on a project node in **Solution Explorer** and choosing **Properties** to display the property pages. Choose **Linker** in the left pane to expand the node and see all the options. ## Linker command-line syntax -When you run LINK outside of Visual Studio, you can specify input in one or more ways: +When you run the linker outside of Visual Studio, you can specify input in one or more ways: - On the command line - - Using command files - - In environment variables -LINK first processes options specified in the LINK environment variable, followed by options in the order they are specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. +The linker first processes options specified in the `LINK` environment variable, followed by options in the order they're specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. Options apply to the entire build; no options can be applied to specific input files. -To run LINK.EXE, use the following command syntax: +To run `link.exe`, use the following command syntax: -``` -LINK arguments +```cmd +link arguments ``` The `arguments` include options and filenames and can be specified in any order. Options are processed first, then files. Use one or more spaces or tabs to separate arguments. > [!NOTE] -> You can start this tool only from the Visual Studio command prompt. You cannot start it from a system command prompt or from File Explorer. +> You can start this tool only from the Visual Studio command prompt. You can't start it from a system command prompt or from File Explorer. ## Command line -On the command line, an option consists of an option specifier, either a dash (-) or a forward slash (/), followed by the name of the option. Option names cannot be abbreviated. Some options take an argument, specified after a colon (:). No spaces or tabs are allowed within an option specification, except within a quoted string in the /COMMENT option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments are not case sensitive, but identifiers as arguments are case sensitive. +On the command line, an option consists of an option specifier, either a dash (`-`) or a forward slash (`/`), followed by the name of the option. Option names can't be abbreviated. Some options take an argument, specified after a colon (`:`). No spaces or tabs are allowed within an option specification, except within a quoted string in the `/COMMENT` option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments aren't case sensitive, but identifiers as arguments are case sensitive. -To pass a file to the linker, specify the filename on the command line after the LINK command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (.) and filename extension, LINK assumes .obj for the purpose of finding the file. LINK does not use filename extensions or the lack of them to make assumptions about the contents of files; it determines the type of file by examining it, and processes it accordingly. +To pass a file to the linker, specify the filename on the command line after the `link.exe` command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (`.`) and filename extension, the linker assumes an extension of `.obj` to find the file. The linker doesn't use filename extensions or the lack of them to make assumptions about the contents of files. It determines the type of file by examining it, and processes it accordingly. -link.exe returns zero for success (no errors). Otherwise, the linker returns the error number that stopped the link. For example, if the linker generates LNK1104, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either link.exe or c2.dll. +> [!NOTE] +> Various linker flags take a filename. Whether you specify a relative path or an absolute path, if the fully-qualified filename exceeds `MAX_PATH` (260 characters), the linker may fail--particularly while searching for libraries. If you encounter this problem, try using a shorter path. -## LINK Command Files +The linker returns zero for success (no errors). Otherwise, it returns the error number that stopped the link. For example, if the linker generates `LNK1104`, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either `link.exe` or `c2.dll`. -You can pass command-line arguments to LINK in the form of a command file. To specify a command file to the linker, use the following syntax: +## Linker command files -> **LINK \@**commandfile +You can pass command-line arguments to `link.exe` in the form of a command file. To specify a command file to the linker, use the following syntax: -The *commandfile* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There is no default extension; you must specify the full filename, including any extension. Wildcards cannot be used. You can specify an absolute or relative path with the filename. LINK does not use an environment variable to search for the file. +> `link @commandfile` -In the command file, arguments can be separated by spaces or tabs (as on the command line) and by newline characters. +The *`commandfile`* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There's no default extension; you must specify the full filename, including any extension. Wildcards can't be used. You can specify an absolute or relative path with the filename. Must not exceed `MAX_PATH` (260 characters). The linker doesn't use an environment variable to search for the file. -You can specify all or part of the command line in a command file. You can use more than one command file in a LINK command. LINK accepts the command-file input as if it were specified in that location on the command line. Command files cannot be nested. LINK echoes the contents of command files, unless the [/NOLOGO](nologo-suppress-startup-banner-linker.md) option is specified. +In the command file, arguments are separated by spaces or tabs (as on the command line) and by newline characters. + +You can specify all or part of the command line in a command file. You can use more than one command file in a `link.exe` command. The linker accepts the command-file input as if it was specified in that location on the command line. Command files can't be nested. The linker echoes the contents of command files, unless [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) is specified. ## Example -The following command to build a DLL passes the names of object files and libraries in separate command files and uses a third command file for specification of the /EXPORTS option: +The following command builds a DLL. It passes the names of object files and libraries in separate command files and uses a third command file for specification of the `/EXPORTS` option: ```cmd link /dll @objlist.txt @liblist.txt @exports.txt ``` -## LINK Environment Variables - -The LINK tool uses the following environment variables: - -- LINK and \_LINK\_, if defined. The LINK tool prepends the options and arguments defined in the LINK environment variable and appends the options and arguments defined in the \_LINK\_ environment variable to the command line arguments before processing. - -- LIB, if defined. The LINK tools uses the LIB path when searching for an object, library, or other file specified on the command line or by the [/BASE](base-base-address.md) option. It also uses the LIB path to find a .pdb file named in an object. The LIB variable can contain one or more path specifications, separated by semicolons. One path must point to the \lib subdirectory of your Visual C++ installation. +## LINK environment variables -- PATH, if the tool needs to run CVTRES and cannot find the file in the same directory as LINK itself. (LINK requires CVTRES to link a .res file.) PATH must point to the \bin subdirectory of your Visual C++ installation. +The linker recognizes the following environment variables: -- TMP, to specify a directory when linking OMF or .res files. +- `LINK` and `_LINK_`, if defined. The linker prepends the options and arguments defined in the `LINK` environment variable and appends the options and arguments defined in the `_LINK_` environment variable to the command line arguments before processing. +- `LIB`, if defined. The linker uses the `LIB` path when it searches for an object, library, or other file specified on the command line or by the [`/BASE`](base-base-address.md) option. It also uses the `LIB` path to find a `.pdb` file named in an object. The `LIB` variable can contain one or more path specifications, separated by semicolons. One path must point to the `\lib` subdirectory of your Visual C++ installation. +- `PATH`, if the tool needs to run `CVTRES` and can't find the file in the same directory as `link.exe` itself. (`link.exe` requires `CVTRES` to link a `.res` file.) `PATH` must point to the `\bin` subdirectory of your Visual C++ installation. +- `TMP`, to specify a directory when linking OMF or `.res` files. ## See also -[C/C++ Building Reference](c-cpp-building-reference.md) -[MSVC Linker Options](linker-options.md) -[Module-Definition (.def) Files](module-definition-dot-def-files.md) +[C/C++ Building Reference](c-cpp-building-reference.md)\ +[MSVC Linker Options](linker-options.md)\ +[Module-Definition (.def) Files](module-definition-dot-def-files.md)\ [Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/linkrepro.md b/docs/build/reference/linkrepro.md index 9d00525a14..a106200fdc 100644 --- a/docs/build/reference/linkrepro.md +++ b/docs/build/reference/linkrepro.md @@ -1,7 +1,7 @@ --- title: "/LINKREPRO (Link repro directory name)" description: Linker or library tool option to set the directory for a link repro. -ms.date: "09/24/2019" +ms.date: 03/28/2025 f1_keywords: ["/LINKREPRO"] helpviewer_keywords: ["LINKREPRO linker option", "/LINKREPRO linker option", "-LINKREPRO linker option", "linker repro reporting"] --- @@ -11,12 +11,12 @@ Tells the linker or library tool to generate a link repro in a specified directo ## Syntax -> **/LINKREPRO:**_directory-name_ +> `/LINKREPRO:` **_directory-name_** ### Arguments -**/LINKREPRO:**_directory-name_\ -The user-specified directory to store the link repro in. Directory names that include spaces must be enclosed in double quotes. +**_directory-name_**\ +The user-specified directory to store the link repro in. Directory names that include spaces must be enclosed in double quotes. When expanded, the fully qualified link repro filename must not exceed `MAX_PATH` (260 characters). ## Remarks diff --git a/docs/build/reference/ltcg-link-time-code-generation.md b/docs/build/reference/ltcg-link-time-code-generation.md index e38ae4810e..1a22070855 100644 --- a/docs/build/reference/ltcg-link-time-code-generation.md +++ b/docs/build/reference/ltcg-link-time-code-generation.md @@ -1,8 +1,8 @@ --- title: "/LTCG (Link-time code generation)" description: "The MSVC linker option /LTCG enables link-time code generation for whole-program optimization." -ms.date: 07/08/2020 -f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization"] +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization", "VC.Project.VCLinkerTool.LinkStatus"] helpviewer_keywords: ["link-time code generation in C++ linker", "/LTCG linker option", "-LTCG linker option", "LTCG linker option"] ms.assetid: 788c6f52-fdb8-40c2-90af-4026ea2cf2e2 --- @@ -12,22 +12,22 @@ Use **`/LTCG`** to perform whole-program optimization, or to create profile-guid ## Syntax -> **`/LTCG`**[**`:`**{**`INCREMENTAL`**|**`NOSTATUS`**|**`STATUS`**|**`OFF`**}] +> **`/LTCG`**[**`:`**{**`INCREMENTAL`**\|**`NOSTATUS`**\|**`STATUS`**\|**`OFF`**}] These options are deprecated starting in Visual Studio 2015: -> **`/LTCG:`**{**`PGINSTRUMENT`**|**`PGOPTIMIZE`**|**`PGUPDATE`**} +> **`/LTCG:`**{**`PGINSTRUMENT`**\|**`PGOPTIMIZE`**\|**`PGUPDATE`**} ### Arguments **`INCREMENTAL`**
(Optional) Specifies that the linker only applies whole program optimization or link-time code generation (LTCG) to files affected by an edit, instead of the entire project. By default, this flag isn't set when **`/LTCG`** is specified, and the entire project is linked by using whole program optimization. -**`NOSTATUS`** | **`STATUS`**
+**`NOSTATUS`** \| **`STATUS`**
(Optional) Specifies whether the linker displays a progress indicator that shows what percentage of the link is complete. By default, this status information isn't displayed. **`OFF`**
-(Optional) Disables link-time code generation. This behavior is the same as when **`/LTCG`** isn't specified on the command line. +(Optional) Disables link-time code generation. The linker treats all modules compiled with **`/GL`** as if they're compiled without that option, and any MSIL modules cause the link to fail. **`PGINSTRUMENT`**
(Optional) This option is deprecated starting in Visual Studio 2015. Instead, use **`/LTCG`** and [`/GENPROFILE` or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) to generate an instrumented build for profile-guided optimization. The data that is collected from instrumented runs is used to create an optimized image. For more information, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). The short form of this option is **`/LTCG:PGI`**. @@ -76,7 +76,7 @@ The rest of this article discusses the link-time code generation done by **`/LTC The linker invokes link-time code generation if it's passed a module that was compiled by using **`/GL`** or an MSIL module (see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md)). If you don't explicitly specify **`/LTCG`** when you pass **`/GL`** or MSIL modules to the linker, the linker eventually detects this situation and restarts the link by using **`/LTCG`**. Explicitly specify **`/LTCG`** when you pass **`/GL`** and MSIL modules to the linker for the fastest possible build performance. -For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). +For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). If you remove the **`/LTCG:INCREMENTAL`** option, also remove any [`/LTCGOUT`](./ltcgout.md) option to improve build times and disk utilization. **`/LTCG`** isn't valid for use with [`/INCREMENTAL`](incremental-link-incrementally.md). @@ -101,7 +101,7 @@ Using **`/LTCG`** and **`/O2`** causes double-alignment optimization. If **`/LTCG`** and **`/O1`** are specified, double alignment isn't performed. If most of the functions in an application are compiled for speed, with a few functions compiled for size (for example, by using the [`optimize`](../../preprocessor/optimize.md) pragma), the compiler double-aligns the functions that are optimized for size if they call functions that require double alignment. -If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers on a function and tries to optimize the function's calling convention: +If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers, and tries to optimize the function's calling convention: - pass parameters in registers @@ -124,14 +124,40 @@ Modules that are compiled by using [`/GL`](gl-whole-program-optimization.md) and ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +The Whole Program Optimization property sets several compiler and linker options, including **`/LTCG`**. We recommend you use this property to change the settings for an entire build configuration. To set Whole Program Optimization for your project: + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Whole Program Optimization** property. +1. Modify the **Whole Program Optimization** property. Choose **OK** or **Apply** to save your changes. You can also apply **`/LTCG`** to specific builds by choosing **Build** > **Profile Guided Optimization** on the menu bar, or by choosing one of the Profile Guided Optimization options on the shortcut menu for the project. +To enable Link Time Code Generation separately or set a specific Link Time Code Generation option: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation** property to one of the following options: + - **Default** + - **Use Fast Link Time Code Generation (LTCG:incremental)** + - **Use Link Time Code Generation (LTCG)** + - **Profile Guided Optimization - Instrument (LTCG:PGInstrument)** + - **Profile Guided Optimization - Optimization (LTCG:PGOptimize)** + - **Profile Guided Optimization - Update (LTCG:PGUpdate)** + +1. Choose **OK** or **Apply** to save your changes. + +To specify whether the linker displays a progress indicator for Link Time Code Generation: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Link Status** property. Choose **OK** or **Apply** to save your changes. + ### To set this compiler option programmatically - See . diff --git a/docs/build/reference/ltcgout.md b/docs/build/reference/ltcgout.md new file mode 100644 index 0000000000..6a02243c24 --- /dev/null +++ b/docs/build/reference/ltcgout.md @@ -0,0 +1,40 @@ +--- +title: "/LTCGOUT (Name LTCG incremental object file)" +description: "The MSVC linker option /LTCGOUT names the incremental link-time code generation object file." +ms.date: 08/31/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGenerationObjectFile", "/ltcgout", "ltcgout"] +helpviewer_keywords: ["Name link-time code generation file in C++ linker", "/LTCGOUT linker option", "-LTCGOUT linker option", "LTCGOUT linker option"] +--- +# `/LTCGOUT` (Name LTCG incremental object file) + +The **`/LTCGOUT`** linker option tells the linker where to put the intermediate *`.iobj`* object file for incremental link-time code generation (**`/LTCG:INCREMENTAL`**). + +## Syntax + +> **`/LTCGOUT:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The optional destination directory and filename for the generated *`.iobj`* file. If the **`/LTCGOUT`** option isn't specified when **`/LTCG:INCREMENTAL`** is used, the filename is created by appending *`.iobj`* to the target base filename. If the **`/LTCGOUT`** option is specified with an empty *`pathname`* when **`/LTCG:INCREMENTAL`** isn't used, no *`.iobj`* file is generated. + +## Remarks + +The **`/LTCGOUT`** linker option tells the linker the path and filename to use for the intermediate *`.iobj`* object file when you specify [`/LTCG:INCREMENTAL`](./ltcg-link-time-code-generation.md). If you remove the **`/LTCG:INCREMENTAL`** option from your project, you should also remove any **`/LTCGOUT`** option. + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation Object File** property. The option isn't set if this property is empty. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/machine-specify-target-platform.md b/docs/build/reference/machine-specify-target-platform.md index f5cf171020..203ac3a325 100644 --- a/docs/build/reference/machine-specify-target-platform.md +++ b/docs/build/reference/machine-specify-target-platform.md @@ -1,22 +1,20 @@ --- description: "Learn more about: /MACHINE (Specify Target Platform)" title: "/MACHINE (Specify Target Platform)" -ms.date: "11/04/2016" +ms.date: 03/25/2022 f1_keywords: ["VC.Project.VCLinkerTool.TargetMachine", "/machine"] helpviewer_keywords: ["mapfiles, creating linker", "target platform", "-MACHINE linker option", "/MACHINE linker option", "MACHINE linker option"] ms.assetid: 8d41bf4b-7e53-4ab9-9085-d852b08d31c2 --- # /MACHINE (Specify Target Platform) -``` -/MACHINE:{ARM|EBC|X64|X86} -``` +> **`/MACHINE:`**{**`ARM`**|**`ARM64`**|**`ARM64EC`**|**`EBC`**|**`X64`**|**`X86`**} ## Remarks -The /MACHINE option specifies the target platform for the program. +The **`/MACHINE`** option specifies the target platform for the program. -Usually, you don't have to specify the /MACHINE option. LINK infers the machine type from the .obj files. However, in some circumstances, LINK cannot determine the machine type and issues a [linker tools error LNK1113](../../error-messages/tool-errors/linker-tools-error-lnk1113.md). If such an error occurs, specify /MACHINE. +Usually, you don't have to specify the **`/MACHINE`** option. LINK infers the machine type from the *`.obj`* files. However, in some circumstances, LINK cannot determine the machine type and issues a [linker tools error LNK1113](../../error-messages/tool-errors/linker-tools-error-lnk1113.md). If such an error occurs, specify **`/MACHINE`**. ### To set this linker option in the Visual Studio development environment @@ -32,5 +30,5 @@ Usually, you don't have to specify the /MACHINE option. LINK infers the machine ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/makefile-preprocessing.md b/docs/build/reference/makefile-preprocessing.md index f8ff9993a7..7092de7a26 100644 --- a/docs/build/reference/makefile-preprocessing.md +++ b/docs/build/reference/makefile-preprocessing.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Makefile Preprocessing" title: "Makefile preprocessing" +description: "Learn more about: Makefile Preprocessing" ms.date: 09/30/2021 f1_keywords: ["!UNDEF", "!INCLUDE", "!IFNDEF", "!MESSAGE"] helpviewer_keywords: ["preprocessing makefiles", "makefiles, preprocessing", "!CMDSWITCHES directive", "!ELSE directive", "!ELSEIF directive", "!ELSEIFDEF directive", "!ELSEIFNDEF directive", "!ENDIF directive", "!ERROR directive", "!IF directive", "!IFDEF directive", "!IFNDEF directive", "!INCLUDE directive", "!MESSAGE directive", "!UNDEF directive", "directives, makefile preprocessing", "preprocessing directives, makefiles", "NMAKE program, expressions", "NMAKE program, preprocessor directives", "makefiles, preprocessing directives", "expressions [C++], makefile preprocessing", "operators [C++], makefile preprocessing", "EXIST operator", "preprocessing NMAKE makefile operators", "NMAKE program, operators", "DEFINED operator", "makefiles, preprocessing operators"] @@ -9,11 +9,11 @@ helpviewer_keywords: ["preprocessing makefiles", "makefiles, preprocessing", "!C You can control the NMAKE session by using preprocessing directives and expressions. Preprocessing instructions can be placed in the makefile or in *`Tools.ini`*. Using directives, you can conditionally process your makefile, display error messages, include other makefiles, undefine a macro, and turn certain options on or off. -## Makefile Preprocessing Directives +## Makefile Preprocessing Directives Preprocessing directives aren't case-sensitive. The initial exclamation point (**`!`**) must appear at the beginning of the line. Zero or more spaces or tabs can appear after the exclamation point, for indentation. -- **`!CMDSWITCHES`** { **`+`**_option_ | **`-`**_option_ } ... +- **`!CMDSWITCHES`** { **`+`**_option_ \| **`-`**_option_ } ... Turns each listed *option* on or off. Spaces or tabs must appear before the **`+`** or **`-`** operator. No spaces can appear between the operator and the [option letters](running-nmake.md#nmake-options). Letters aren't case-sensitive and are specified without a slash (`/`). To turn on some options and turn off others, use separate specifications of **`!CMDSWITCHES`**. @@ -43,7 +43,7 @@ Preprocessing directives aren't case-sensitive. The initial exclamation point (* Processes statements between **`!IFNDEF`** and the next **`!ELSE`** or **`!ENDIF`** if *macro_name* isn't defined. -- **`!ELSE`** [ **`IF`** *constant_expression* | **`IFDEF`** *macro_name* | **`IFNDEF`** *macro_name* ] +- **`!ELSE`** [ **`IF`** *constant_expression* \| **`IFDEF`** *macro_name* \| **`IFNDEF`** *macro_name* ] Processes statements between **`!ELSE`** and the next **`!ENDIF`** if the prior **`!IF`**, **`!IFDEF`**, or **`!IFNDEF`** statement evaluated to zero. The optional keywords give further control of preprocessing. @@ -67,13 +67,13 @@ Preprocessing directives aren't case-sensitive. The initial exclamation point (* Undefines *macro_name*. -## Expressions in makefile preprocessing +## Expressions in makefile preprocessing The **`!IF`** or **`!ELSE IF`** *constant_expression* consists of integer constants (in decimal or C-language notation), string constants, or commands. Use parentheses to group expressions. Expressions use C-style signed long integer arithmetic; numbers are in 32-bit two's-complement form in the range -2147483648 to 2147483647. Expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. -## Makefile preprocessing operators +## Makefile preprocessing operators Makefile preprocessing expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. To evaluate the expression, the preprocessor first expands macros, and then executes commands, and then does the operations. It evaluates operations in order of explicit grouping in parentheses, and then in order of operator precedence. The result is a constant value. @@ -96,7 +96,7 @@ Expressions can use the following operators. The operators of equal precedence a | **`~`** | Unary one's complement. | | **`-`** | Unary negation. | | | | -| **`*`*** | Multiplication. | +| **`*`** | Multiplication. | | **`/`** | Division. | | **`%`** | Modulus (remainder). | | | | @@ -120,12 +120,12 @@ Expressions can use the following operators. The operators of equal precedence a | | | | **`&&`** | Logical AND. | | | | -| **` | | `** | Logical OR. | +| **` || `** | Logical OR. | > [!NOTE] > The bitwise XOR operator (**`^`**) is the same as the escape character, and must be escaped (as **`^^`**) when it's used in an expression. -## Executing a program in preprocessing +## Executing a program in preprocessing To use a command's exit code during preprocessing, specify the command, with any arguments, within brackets (**`[ ]`**). Any macros are expanded before the command is executed. NMAKE replaces the command specification with the command's exit code, which can be used in an expression to control preprocessing. diff --git a/docs/build/reference/managing-a-library.md b/docs/build/reference/managing-a-library.md index 12b8cb236a..5ea56fcb14 100644 --- a/docs/build/reference/managing-a-library.md +++ b/docs/build/reference/managing-a-library.md @@ -1,49 +1,47 @@ --- description: "Learn more about: Managing a Library" title: "Managing a Library" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLibrarianTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLibrarianTool.AdditionalDependencies", "VC.Project.VCLibrarianTool.RemoveObjects", "VC.Project.VCLibrarianTool.LibraryPaths", "VC.Project.VCLibrarianTool.OutputFile", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryNames", "VC.Project.VCLibrarianTool.AdditionalLibraryDirectories", "VC.Project.VCLibrarianTool.ListContentsFile", "VC.Project.VCLibrarianTool.ListContents", "VC.Project.VCLibrarianTool.SubSystemVersion", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryName", "VC.Project.VCLibrarianTool.SubSystem"] helpviewer_keywords: ["/LIBPATH library manager option", "OUT library manager option", "CONVERT library manager option", "LIBPATH library manager option", "/LIST library manager option", "object files, building and modifying", "-LINK50COMPAT library manager option", "REMOVE library manager option", "SUBSYSTEM library manager option", "/LINK50COMPAT library manager option", "/OUT library manager option", "LIB [C++], managing COFF libraries", "-CONVERT library manager option", "LINK50COMPAT library manager option", "-OUT library manager option", "-REMOVE library manager option", "-LIST library manager option", "/SUBSYSTEM library manager option", "-SUBSYSTEM library manager option", "/REMOVE library manager option", "-LIBPATH library manager option", "object files", "LIST library manager option", "/CONVERT library manager option"] ms.assetid: f56a8b85-fbdc-4c09-8d8e-00f0ffe1da53 --- # Managing a Library -The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you do not specify /EXTRACT (to copy an object to a file) or /DEF (to build an import library). +The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you don't specify **`/EXTRACT`** (to copy an object to a file) or **`/DEF`** (to build an import library). To build a library from objects and/or libraries, use the following syntax: -``` -LIB [options...] files... -``` +> **`LIB`** [*`options...`*] *`files...`* -This command creates a library from one or more input *files*. The *files* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB cannot accept a 32-bit OMF object that is in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. +This command creates a library from one or more input files, *`files`*. The *`files`* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB can't accept a 32-bit OMF object that's in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. -By default, LIB names the output file using the base name of the first object or library file and the extension .lib. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the /OUT option to specify a name for the output file. +By default, LIB names the output file using the base name of the first object or library file and the extension *`.lib`*. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the **`/OUT`** option to specify a name for the output file. The following options apply to building and modifying a library: -**/LIBPATH:** *dir*
-Overrides the environment library path. For details, see the description of the LINK [/LIBPATH](libpath-additional-libpath.md) option. +**`/LIBPATH:`** *`dir`*\ +Overrides the environment library path and sets it to *`dir`*. For details, see the description of the LINK [`/LIBPATH`](libpath-additional-libpath.md) option. -**/LIST**
-Displays information about the output library to standard output. The output can be redirected to a file. You can use /LIST to determine the contents of an existing library without modifying it. +**`/LIST`**\ +Displays information about the output library to standard output. The output can be redirected to a file. You can use **`/LIST`** to determine the contents of an existing library without modifying it. -**/NAME:** *filename*
-When building an import library, specifies the name of the DLL for which the import library is being built. +**`/NAME:`** *`filename`*\ +When building an import library, *`filename`* specifies the name of the DLL for which the import library is being built. -**/NODEFAULTLIB**
-Removes one or more default libraries from the list of libraries it searches when resolving external references. See [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) for more information. +**`/NODEFAULTLIB`**\ +Removes one or more default libraries from the list of libraries it searches when resolving external references. For more information, see [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md). -**/OUT:** *filename*
-Overrides the default output filename. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension .lib. +**`/OUT:`** *`filename`*\ +Overrides the default output filename and replaces it with *`filename`*. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension *`.lib`*. -**/REMOVE:** *object*
-Omits the specified *object* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with /REMOVE. +**`/REMOVE:`** *`object`*\ +Omits the specified *`object`* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with **`/REMOVE`**. -**/SUBSYSTEM:**{**CONSOLE** | **EFI_APPLICATION** | **EFI_BOOT_SERVICE_DRIVER** | **EFI_ROM** | **EFI_RUNTIME_DRIVER** | **NATIVE** | **POSIX** | **WINDOWS** | **WINDOWSCE**}[,#[.##]]
-Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [/SUBSYSTEM](subsystem-specify-subsystem.md) option. +**`/SUBSYSTEM:`**{**`CONSOLE`** \| **`EFI_APPLICATION`** \| **`EFI_BOOT_SERVICE_DRIVER`** \| **`EFI_ROM`** \| **`EFI_RUNTIME_DRIVER`** \| **`NATIVE`** \| **`POSIX`** \| **`WINDOWS`** \| **`WINDOWSCE`**}[,#[.##]]\ +Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option. -LIB options specified on the command line are not case sensitive. +LIB options specified on the command line aren't case sensitive. You can use LIB to perform the following library-management tasks: @@ -56,7 +54,7 @@ You can use LIB to perform the following library-management tasks: - To delete a member from a library, use the /REMOVE option. LIB processes any specifications of /REMOVE after combining all input objects, regardless of command-line order. > [!NOTE] -> You cannot both delete a member and extract it to a file in the same step. You must first extract the member object using /EXTRACT, then run LIB again using /REMOVE. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. +> You can't both delete a member and extract it to a file in the same step. You must first extract the member object using **`/EXTRACT`**, then run LIB again using **`/REMOVE`**. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. ## See also diff --git a/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md index 6b8a9ce9ea..0cfe26b687 100644 --- a/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md +++ b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md @@ -1,44 +1,46 @@ --- -description: "Learn more about: /MANIFEST (Create Side-by-Side Assembly Manifest)" -title: "/MANIFEST (Create Side-by-Side Assembly Manifest)" +description: "Learn more about: /MANIFEST (Create side-by-side assembly manifest)" +title: "/MANIFEST (Create side-by-side assembly manifest)" ms.date: "11/04/2016" -f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest"] +f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest", "VC.Project.VCLinkerTool.ManifestEmbed"] helpviewer_keywords: ["-MANIFEST linker option", "/MANIFEST linker option", "MANIFEST linker option"] ms.assetid: 98c52e1e-712c-4f49-b149-4d0a3501b600 --- -# /MANIFEST (Create Side-by-Side Assembly Manifest) +# `/MANIFEST` (Create side-by-side assembly manifest) -``` -/MANIFEST[:{EMBED[,ID=#]|NO}] -``` +Specifies whether the linker should create a side-by-side manifest file. + +## Syntax + +> **`/MANIFEST`**\[**`:`**{**`EMBED`**\[**`,ID=`***`resource_id`*]\|**`NO`**}] ## Remarks -/MANIFEST specifies that the linker should create a side-by-side manifest file. For more information about manifest files, see [Manifest Files Reference](/windows/win32/SbsCs/manifest-files-reference). +The **`/MANIFEST`** linker option tells the linker to create a side-by-side manifest file. For more information about manifest files, see [Manifest files reference](/windows/win32/SbsCs/manifest-files-reference). -The default is /MANIFEST. +The default is **`/MANIFEST`**. -The /MANIFEST:EMBED option specifies that the linker should embed the manifest file in the image as a resource of type RT_MANIFEST. The optional `ID` parameter is the resource ID to use for the manifest. Use a value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter is not specified, the default value is 2 if the /DLL option is set; otherwise, the default value is 1. +The **`/MANIFEST:EMBED`** option specifies that the linker should embed the manifest file in the image as a resource of type `RT_MANIFEST`. The optional `ID` parameter sets the resource ID to use for the manifest. Use a *`resource_id`* value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter isn't specified, the default value is 2 if the **`/DLL`** option is set; otherwise, the default value is 1. -Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify /MANIFEST but specify neither [/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md) nor [/DLL](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *asInvoker* is inserted into the manifest. For more information about UAC levels, see [/MANIFESTUAC (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). +Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify **`/MANIFEST`** but don't specify either [`/MANIFESTUAC`](manifestuac-embeds-uac-information-in-manifest.md) or [`/DLL`](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *`asInvoker`* is inserted into the manifest. For more information about UAC levels, see [`/MANIFESTUAC` (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). -To change the default behavior for UAC, do one of these: +To change the default behavior for UAC, set one of these options: -- Specify the /MANIFESTUAC option and set the UAC level to the desired value. +- Specify the **`/MANIFESTUAC`** option and set the UAC level to the desired value. -- Or specify the /MANIFESTUAC:NO option if you do not want to generate a UAC fragment in the manifest. +- Or, specify the **`/MANIFESTUAC:NO`** option if you don't want to generate a UAC fragment in the manifest. -If you do not specify /MANIFEST but do specify [/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) comments, a manifest file is created. A manifest file is not created if you specify /MANIFEST:NO. +If you don't specify **`/MANIFEST`** but do specify [`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) attributes, a manifest file is created. A manifest file isn't created if you specify **`/MANIFEST:NO`**. -If you specify /MANIFEST, the name of the manifest file is the same as the name of your output file, but with .manifest appended to the file name. For example, if your output file name is MyFile.exe, the manifest file name is MyFile.exe.manifest. If you specify /MANIFESTFILE:*name*, the name of the manifest is what you specify in *name*. +If you specify **`/MANIFEST`**, the name of the manifest file is the same as the full name of your output file, but with *`.manifest`* appended to the file name. For example, if your output file name is *`MyFile.exe`*, the manifest file name is *`MyFile.exe.manifest`*. If you specify **`/MANIFESTFILE:`***`name`*, the name of the manifest is what you specify in *`name`*. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Manifest File** property page. -1. Modify the **Generate Manifest** property. +1. Modify the **Generate Manifest** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +48,9 @@ If you specify /MANIFEST, the name of the manifest file is the same as the name ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[Manifest files reference](/windows/win32/SbsCs/manifest-files-reference)\ +[`/MANIFESTDEPENDENCY` (Specify manifest dependencies)](./manifestdependency-specify-manifest-dependencies.md)\ +[`/MANIFESTFILE` (Name manifest file)](./manifestfile-name-manifest-file.md)\ +[`/MANIFESTUAC` (Embeds UAC information in manifest)](./manifestuac-embeds-uac-information-in-manifest.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/manifest-tool-property-pages.md b/docs/build/reference/manifest-tool-property-pages.md index 144a37acfb..cdf705d3d8 100644 --- a/docs/build/reference/manifest-tool-property-pages.md +++ b/docs/build/reference/manifest-tool-property-pages.md @@ -22,7 +22,6 @@ f1_keywords: - VC.Project.VCManifestTool.ReplacementsFile - VC.Project.VCManifestTool.UpdateFileHashes - VC.Project.VCManifestTool.UpdateFileHashesSearchPath - - vc.project.AdditionalOptionsPage --- # Manifest Tool Property Pages diff --git a/docs/build/reference/manifestfile-name-manifest-file.md b/docs/build/reference/manifestfile-name-manifest-file.md index acd17845b9..32a06f368e 100644 --- a/docs/build/reference/manifestfile-name-manifest-file.md +++ b/docs/build/reference/manifestfile-name-manifest-file.md @@ -4,26 +4,28 @@ title: "/MANIFESTFILE (Name Manifest File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.ManifestFile"] helpviewer_keywords: ["MANIFESTFILE linker option", "-MANIFESTFILE linker option", "/MANIFESTFILE linker option"] -ms.assetid: befa5ab2-a9cf-4c9b-969a-e7b4a930f08d --- # /MANIFESTFILE (Name Manifest File) -``` -/MANIFESTFILE:filename -``` +Change the default name of the manifest file. -## Remarks +## Syntax + +> `/MANIFESTFILE:`**filename** -/MANIFESTFILE lets you change the default name of the manifest file. The default name of the manifest file is the file name with .manifest appended. +## Arguments -/MANIFESTFILE will have no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). +**filename**\ +The default name of the manifest file is *filename* with `.manifest` appended. + +## Remarks + +`/MANIFESTFILE` has no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Manifest File** property page. - 1. Modify the **Manifest File** property. ### To set this linker option programmatically @@ -32,5 +34,5 @@ ms.assetid: befa5ab2-a9cf-4c9b-969a-e7b4a930f08d ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/manifestinput-specify-manifest-input.md b/docs/build/reference/manifestinput-specify-manifest-input.md index 3b71cd47df..df8b326f7d 100644 --- a/docs/build/reference/manifestinput-specify-manifest-input.md +++ b/docs/build/reference/manifestinput-specify-manifest-input.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /MANIFESTINPUT (Specify Manifest Input)" title: "/MANIFESTINPUT (Specify Manifest Input)" -ms.date: "07/24/2019" -ms.assetid: a0b0c21e-1f9b-4d8c-bb3f-178f57fa7f1b +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.ManifestInput"] --- # /MANIFESTINPUT (Specify Manifest Input) @@ -10,22 +10,20 @@ Specifies a manifest input file to include in the manifest that's embedded in th ## Syntax -``` -/MANIFESTINPUT:filename -``` +> `/MANIFESTINPUT:`*filename* ### Parameters -*filename*
-The manifest file to include in the embedded manifest. +*filename*\ +The manifest file to include in the embedded manifest. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The **/MANIFESTINPUT** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times—once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **/MANIFEST:EMBED** option. +The **`/MANIFESTINPUT`** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times: once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **`/MANIFEST:EMBED`** option. -This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify additional manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). +This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify other manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/md-mt-ld-use-run-time-library.md b/docs/build/reference/md-mt-ld-use-run-time-library.md index 0db8d589cb..0867d33ed0 100644 --- a/docs/build/reference/md-mt-ld-use-run-time-library.md +++ b/docs/build/reference/md-mt-ld-use-run-time-library.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: /MD, /MT, /LD (Use Run-Time Library)" -title: "/MD, -MT, -LD (Use Run-Time Library)" -ms.date: "07/17/2019" +title: "/MD, /MT, /LD (Use runtime library)" +description: "Learn more about: /MD, /MT, /LD (Use runtime library)" +ms.date: "01/13/2025" f1_keywords: ["/ld", "/mt", "VC.Project.VCCLWCECompilerTool.RuntimeLibrary", "VC.Project.VCCLCompilerTool.RuntimeLibrary", "/md", "/ml"] helpviewer_keywords: ["/MT compiler option [C++]", "-MD compiler option [C++]", "threading [C++], multithread compiler option", "MSVCRTD.lib", "MSVCRT.lib", "LIBCMT.lib", "MD compiler option [C++]", "/MD compiler option [C++]", "MT compiler option [C++]", "LD compiler option [C++]", "MDd compiler option [C++]", "-MDd compiler option [C++]", "LIBCD.lib", "-MTd compiler option [C++]", "MTd compiler option [C++]", "/MTd compiler option [C++]", "-LD compiler option [C++]", "/MDd compiler option [C++]", "multithread compiler option", "_STATIC_CPPLIB symbol", "LIBC.lib", "/LD compiler option [C++]", "DLLs [C++], compiler options", "LIBCMTD.lib", "-MT compiler option [C++]"] -ms.assetid: cf7ed652-dc3a-49b3-aab9-ad60e5395579 --- -# /MD, /MT, /LD (Use Run-Time Library) +# /MD, /MT, /LD (Use runtime library) -Indicates whether a multithreaded module is a DLL and specifies retail or debug versions of the run-time library. +Indicates whether a multithreaded module is a DLL and specifies retail or debug versions of the runtime library. ## Syntax @@ -22,27 +21,25 @@ Indicates whether a multithreaded module is a DLL and specifies retail or debug |Option|Description| |------------|-----------------| -|**/MD**|Causes the application to use the multithread-specific and DLL-specific version of the run-time library. Defines `_MT` and `_DLL` and causes the compiler to place the library name MSVCRT.lib into the .obj file.

Applications compiled with this option are statically linked to MSVCRT.lib. This library provides a layer of code that enables the linker to resolve external references. The actual working code is contained in MSVCR*versionnumber*.DLL, which must be available at run time to applications linked with MSVCRT.lib.| -|**/MDd**|Defines `_DEBUG`, `_MT`, and `_DLL` and causes the application to use the debug multithread-specific and DLL-specific version of the run-time library. It also causes the compiler to place the library name MSVCRTD.lib into the .obj file.| -|**/MT**|Causes the application to use the multithread, static version of the run-time library. Defines `_MT` and causes the compiler to place the library name LIBCMT.lib into the .obj file so that the linker will use LIBCMT.lib to resolve external symbols.| -|**/MTd**|Defines `_DEBUG` and `_MT`. This option also causes the compiler to place the library name LIBCMTD.lib into the .obj file so that the linker will use LIBCMTD.lib to resolve external symbols.| -|**/LD**|Creates a DLL.

Passes the **/DLL** option to the linker. The linker looks for, but does not require, a `DllMain` function. If you do not write a `DllMain` function, the linker inserts a `DllMain` function that returns TRUE.

Links the DLL startup code.

Creates an import library (.lib), if an export (.exp) file is not specified on the command line. You link the import library to applications that call your DLL.

Interprets [/Fe (Name EXE File)](fe-name-exe-file.md) as naming a DLL rather than an .exe file. By default, the program name becomes *basename*.dll instead of *basename*.exe.

Implies **/MT** unless you explicitly specify **/MD**.| -|**/LDd**|Creates a debug DLL. Defines `_MT` and `_DEBUG`.| +|**/MD**|Use the multithread-specific and DLL-specific version of the runtime library. Defines `_MT` and `_DLL`. The linker uses the `MSVCRT.lib` import library to resolve runtime symbols.| +|**/MDd**|Use the debug multithread-specific and DLL-specific version of the runtime library. Defines `_DEBUG`, `_MT`, and `_DLL`. The linker uses the `MSVCRTD.lib` import library to resolve runtime symbols.| +|**/MT**| Use the multithread, static version of the runtime library. Defines `_MT`. The linker uses `LIBCMT.lib` to resolve runtime symbols.| +|**/MTd**| Use the debug multithread, static version of the runtime library. Defines `_DEBUG` and `_MT`. The linker uses `LIBCMTD.lib` to resolve runtime symbols.| +|**/LD**|Create a DLL.

Passes the **/DLL** option to the linker. The linker looks for, but does not require, a `DllMain` function. If you don't write a `DllMain` function, the linker inserts a `DllMain` function that returns TRUE.

Links the DLL startup code.

Creates an import library (`.lib`), if an export (`.exp`) file is not specified on the command line. You link the import library to applications that call your DLL.

Interprets [/Fe (Name EXE File)](fe-name-exe-file.md) as naming a DLL rather than an `.exe` file. By default, the program name becomes *basename*.dll instead of *basename*.exe.

Implies **/MT** unless you explicitly specify **/MD**.| +|**/LDd**|Create a debug DLL. Defines `_MT` and `_DEBUG`.| -For more information about C run-time libraries and which libraries are used when you compile with [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), see [CRT Library Features](../../c-runtime-library/crt-library-features.md). +For more information about C runtime libraries and which libraries are used when you compile with [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), see [CRT Library Features](../../c-runtime-library/crt-library-features.md). -All modules passed to a given invocation of the linker must have been compiled with the same run-time library compiler option (**/MD**, **/MT**, **/LD**). +All modules passed to a given invocation of the linker must have been compiled with the same runtime library compiler option (**/MD**, **/MT**, **/LD**). -For more information about how to use the debug versions of the run-time libraries, see [C Run-Time Library Reference](../../c-runtime-library/c-run-time-library-reference.md). +For more information about how to use the debug versions of the runtime libraries, see [C runtime Library Reference](../../c-runtime-library/c-run-time-library-reference.md). For more about DLLs, see [Create C/C++ DLLs in Visual Studio](../dlls-in-visual-cpp.md). ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. - 1. Modify the **Runtime Library** property. ### To set this compiler option programmatically @@ -51,5 +48,6 @@ For more about DLLs, see [Create C/C++ DLLs in Visual Studio](../dlls-in-visual- ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ +[The Great C Runtime (CRT) Refactoring](https://devblogs.microsoft.com/cppblog/the-great-c-runtime-crt-refactoring/) \ No newline at end of file diff --git a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md index 17f74d81fd..77eceff58e 100644 --- a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md +++ b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md @@ -1,108 +1,103 @@ --- description: "Learn more about: Microsoft extensions to C and C++" title: "Microsoft extensions to C and C++" -ms.date: "06/14/2018" +ms.date: 03/15/2022 helpviewer_keywords: ["or_eq operator", "~ operator, extensions to C/C++", "& operator, extensions to C/C++", "&= operator", "iso646.h header", "Xor operator, Microsoft extensions to C/C++", "!= operator", "! operator, extension to C++", "Or operator, Microsoft extensions to C/C++", "^ operator, extensions to C/C++", "^= operator, C++ extensions", "xor_eq operator", "and_eq operator", "Microsoft extensions to C/C++", "|= operator", "|| operator", "And operator, extensions to C/C++", "NOT operator", "&& operator", "extensions, C language", "Visual C++, extensions to C/C++", "| operator, extensions", "not_eq operator", "Visual C, Microsoft extensions", "extensions", "compl method"] -ms.assetid: e811a74a-45ba-4c00-b206-2f2321b8689a --- # Microsoft extensions to C and C++ -Visual C++ extends the ANSI C and ANSI C++ standards as follows. +Microsoft Visual C++ (MSVC) extends the C and C++ language standards in several ways, detailed in this article. -## Keywords - -Several keywords are added. In the list in [Keywords](../../cpp/keywords-cpp.md), the keywords that have two leading underscores are Visual C++ extensions. +The MSVC C++ compiler defaults to support for ISO C++14 with some ISO C++17 features and some Microsoft-specific language extensions. For more information on supported features, see [Microsoft C/C++ language conformance by Visual Studio version](../../overview/visual-cpp-language-conformance.md). You can use the **`/std`** compiler option to enable full support for ISO C++17 and ISO C++20 language features. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). -## Out of class definition of static const integral (or enum) members +Where specified, some MSVC C++ language extensions can be disabled by use of the **`/Za`** compiler option. In Visual Studio 2017 and later versions, the **`/permissive-`** compiler option disables Microsoft-specific C++ language extensions. The **`/permissive-`** compiler option is implicitly enabled by the **`/std:c++20`** and **`/std:c++latest`** compiler options. -Under the standard (**/Za**), you must make an out-of-class definition for data members, as shown here: +By default, when MSVC compiles code as C, it implements ANSI C89 with Microsoft-specific language extensions. Some of these MSVC extensions are standardized in ISO C99 and later. Most MSVC C extensions can be disabled by use of the **`/Za`** compiler option, as detailed later in this article. You can use the **`/std`** compiler option to enable support for ISO C11 and C17. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). -```cpp -class CMyClass { - static const int max = 5; - int m_array[max]; -} -// . . . -const int CMyClass::max; // out of class definition -``` +The standard C runtime library is implemented by the Universal C runtime library (UCRT) in Windows. The UCRT also implements many POSIX and Microsoft-specific library extensions. The UCRT supports the ISO C11 and C17 C runtime library standards, with certain implementation-specific caveats. It doesn't support the full ISO C99 standard C runtime library. For more information, see [compatibility](../../c-runtime-library/compatibility.md) in the Universal C runtime library documentation. -Under **/Ze**, the out-of-class definition is optional for static, const integral, and const enum data members. Only integrals and enums that are static and const can have initializers in a class; the initializing expression must be a const expression. +## Keywords -To avoid errors when an out-of-class definition is provided in a header file and the header file is included in multiple source files, use [selectany](../../cpp/selectany.md). For example: - -```cpp -__declspec(selectany) const int CMyClass::max = 5; -``` +MSVC adds several Microsoft-specific keywords to C and C++. In the list in [Keywords](../../cpp/keywords-cpp.md), the keywords that have two leading underscores are MSVC extensions. ## Casts -Both the C++ compiler and C compiler support these kinds of non-ANSI casts: +Both the C++ compiler and C compiler support these kinds of non-standard casts: -- Non-ANSI casts to produce l-values. For example: +- The C compiler supports non-standard casts to produce l-values. For example: ```C char *p; (( int * ) p )++; + // In C with /W4, both by default and under /Ze: + // warning C4213: nonstandard extension used: cast on l-value + // Under /TP or /Za: + // error C2105: '++' needs l-value ``` > [!NOTE] - > This extension is available in the C language only. You can use the following ANSI C standard form in C++ code to modify a pointer as if it is a pointer to a different type. + > This extension is available in the C language only. You can use the following C standard form in C++ code to modify a pointer as if it's a pointer to a different type. - The preceding example could be rewritten as follows to conform to the ANSI C standard. + The preceding example could be rewritten as follows to conform to the C standard. ```C p = ( char * )(( int * )p + 1 ); ``` -- Non-ANSI casts of a function pointer to a data pointer. For example: +- Both the C and C++ compilers support non-standard casts of a function pointer to a data pointer. For example: ```C int ( * pfunc ) (); int *pdata; pdata = ( int * ) pfunc; - ``` - - To perform the same cast and also maintain ANSI compatibility, you can cast the function pointer to a `uintptr_t` before you cast it to a data pointer: - - ```C - pdata = ( int * ) (uintptr_t) pfunc; + /* No diagnostic at any level, whether compiled with default options or under /Za */ ``` ## Variable-length argument lists -Both the C++ compiler and C compiler support a function declarator that specifies a variable number of arguments, followed by a function definition that provides a type instead: +Both C and C++ compilers support a function declarator that specifies a variable number of arguments, followed by a function definition that provides a type instead: ```cpp void myfunc( int x, ... ); void myfunc( int x, char * c ) { } +// In C with /W4, either by default or under /Ze: +// warning C4212: nonstandard extension used: function declaration used ellipsis +// In C with /W4, under /Za: +// warning C4028: formal parameter 2 different from declaration +// In C++, no diagnostic by default or under /Za. ``` ## Single-line comments -The C compiler supports single-line comments, which are introduced by using two forward slash (//) characters: +The C compiler supports single-line comments, which are introduced by using two forward slash (`//`) characters: ```C // This is a single-line comment. ``` +Single-line comments are a C99 feature. They're unaffected by **`/Za`** and cause no diagnostic at any level. + ## Scope The C compiler supports the following scope-related features. -- Redefinitions of extern items as static: +- Redefinitions of `extern` items as `static`: ```C extern int clip(); - static int clip() - {} + static int clip() {} + // In C and C++ with /W4, either by default or under /Ze: + // warning C4211: nonstandard extension used: redefined extern to static + // In C and C++ under /Za: + // error C2375: 'clip': redefinition; different linkage ``` - Use of benign typedef redefinitions within the same scope: ```C typedef int INT; - typedef int INT; + typedef int INT; // No diagnostic at any level in C or C++ ``` - Function declarators have file scope: @@ -110,7 +105,8 @@ The C compiler supports the following scope-related features. ```C void func1() { - extern int func2( double ); + extern double func2( double ); + // In C at /W4: warning C4210: nonstandard extension used: function given file scope } int main( void ) { @@ -118,7 +114,7 @@ The C compiler supports the following scope-related features. } // /Za passes 4 as type int ``` -- Use of block-scope variables that are initialized by using nonconstant expressions: +- Use of block-scope variables that are initialized by using non-constant expressions: ```C int clip( int ); @@ -144,7 +140,11 @@ The C compiler supports the following data declaration and definition features. - Mixed character and string constants in an initializer: ```C - char arr[5] = {'a', 'b', "cde"}; + char arr[6] = {'a', 'b', "cde"}; + // In C with /W4, either by default or under /Ze: + // warning C4207: nonstandard extension used: extended initializer form + // Under /Za: + // error C2078: too many initializers ``` - Bit fields that have base types other than **`unsigned int`** or **`signed int`**. @@ -153,6 +153,10 @@ The C compiler supports the following data declaration and definition features. ```C x; + // By default or under /Ze, /Za, /std:c11, and /std:c17, when /W4 is specified: + // warning C4431: missing type specifier - int assumed. Note: C no longer supports default-int + // warning C4218: nonstandard extension used: must specify at least a storage class or a type + */ int main( void ) { x = 1; @@ -166,6 +170,10 @@ The C compiler supports the following data declaration and definition features. { char *c; int zarray[]; + // In C with /W4, either by default, under /Ze, /std:c11, and /std:c17: + // warning C4200: nonstandard extension used: zero-sized array in struct/union + // Under /Za: + // error C2133: 'zarray': unknown size }; ``` @@ -177,6 +185,10 @@ The C compiler supports the following data declaration and definition features. int i; char *s; }; + // By default or under /Ze, /std:c11, and /std:c17, when /W4 is specified: + // warning C4094: untagged 'struct' declared no symbols + // Under /Za: + // error C2059: syntax error: 'empty declaration' ``` - Unnamed (anonymous) unions: @@ -187,88 +199,38 @@ The C compiler supports the following data declaration and definition features. int i; float fl; }; - ``` - -- Unnamed members: - - ```C - struct s - { - unsigned int flag : 1; - unsigned int : 31; - } + // By default or under /Ze, /std:c11, and /std:c17, when /W4 is specified: + // warning C4094: untagged 'union' declared no symbols + // Under /Za: + // error C2059: syntax error: 'empty declaration' ``` ## Intrinsic floating-point functions -Both the x86 C++ compiler and C compiler support inline generation of the `atan`, `atan2`, `cos`, `exp`, `log`, `log10`, `sin`, `sqrt`, and `tan` functions when **/Oi** is specified. For the C compiler, ANSI conformance is lost when these intrinsics are used, because they do not set the `errno` variable. - -## Passing a non-const pointer parameter to a function that expects a reference to a const pointer parameter - -This is an extension to C++. This code will compile with **/Ze**: +Both the x86 C++ compiler and C compiler support inline generation of the `atan`, `atan2`, `cos`, `exp`, `log`, `log10`, `sin`, `sqrt`, and `tan` functions when **`/Oi`** is specified. These intrinsics don't conform to the standard, because they don't set the `errno` variable. -```cpp -typedef int T; - -const T acT = 9; // A constant of type 'T' -const T* pcT = &acT; // A pointer to a constant of type 'T' - -void func2 ( const T*& rpcT ) // A reference to a pointer to a constant of type 'T' -{ - rpcT = pcT; -} - -T* pT; // A pointer to a 'T' - -void func () -{ - func2 ( pT ); // Should be an error, but isn't detected - *pT = 7; // Invalidly overwrites the constant 'acT' -} -``` - -## ISO646.H not enabled - -Under **/Ze**, you have to include iso646.h if you want to use text forms of the following operators: - -- && (and) - -- &= (and_eq) - -- & (bitand) +## *`ISO646.H`* not enabled -- | (bitor) +Under **`/Ze`**, you have to include *`iso646.h`* if you want to use text forms of the following operators: -- ~ (compl) +| Operator | Text form | +|--|--| +| `&&` | `and` | +| `&=` | `and_eq` | +| `&` | `bitand` | +| `|` | `bitor` | +| `~` | `compl` | +| `!` | `not` | +| `!=` | `not_eq` | +| `||` | `or` | +| `|=` | `or_eq` | +| `^` | `xor` | +| `^=` | `xor_eq` | -- ! (not) - -- != (not_eq) - -- || (or) - -- |= (or_eq) - -- ^ (xor) - -- ^= (xor_eq) - -## Address of string literal has type const char [], not const char (*) [] - -The following example will output `char const (*)[4]` under **/Za**, but `char const [4]` under **/Ze**. - -```cpp -#include -#include - -int main() -{ - printf_s("%s\n", typeid(&"abc").name()); -} -``` +These text forms are available as C++ keywords under **`/Za`** or when **`/permissive-`** is specified or implied. ## See also -- [/Za, /Ze (Disable Language Extensions)](za-ze-disable-language-extensions.md) -- [MSVC Compiler Options](compiler-options.md) -- [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Za`, `/Ze` (Disable language extensions)](za-ze-disable-language-extensions.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/midl-property-pages.md b/docs/build/reference/midl-property-pages.md index 612fa24307..66c3955c39 100644 --- a/docs/build/reference/midl-property-pages.md +++ b/docs/build/reference/midl-property-pages.md @@ -47,7 +47,6 @@ f1_keywords: - VC.Project.VCMidlTool.StructMemberAlignment - VC.Project.VCMidlTool.RedirectOutputAndErrors - VC.Project.VCMidlTool.MinimumTargetSystem - - vc.project.AdditionalOptionsPage --- # MIDL Property Pages diff --git a/docs/build/reference/module-exportheader.md b/docs/build/reference/module-exportheader.md index a6e1cc2cf3..5c1b8a839c 100644 --- a/docs/build/reference/module-exportheader.md +++ b/docs/build/reference/module-exportheader.md @@ -53,11 +53,19 @@ cl . . . /std:c++latest /exportHeader /headerName:quote util/util.h ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your header files. By default, the build system applies this option to compiled files that have a *`.h`* extension, or no extension. + +1. To apply the **`/exportHeader`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**. Choose **OK** or **Apply** to save your changes. ## See also -[`/headerName (Build a header unit from the specified header)`](headername.md)\ +[`/headerName` (Build a header unit from the specified header)](headername.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/module-reference.md b/docs/build/reference/module-reference.md index 6abe5a1758..10f51331a9 100644 --- a/docs/build/reference/module-reference.md +++ b/docs/build/reference/module-reference.md @@ -1,8 +1,8 @@ --- title: "/reference (Use named module IFC)" description: "Use the /reference compiler option to create module header units for the header-name or include files specified." -ms.date: 04/13/2020 -f1_keywords: ["/reference"] +ms.date: 02/17/2022 +f1_keywords: ["/reference", "VC.Project.VCCLCompilerTool.AdditionalModuleDependencies"] helpviewer_keywords: ["/reference", "Use named module IFC"] --- # `/reference` (Use named module IFC) @@ -24,7 +24,7 @@ A valid name of an exported primary module interface unit name or full module pa ## Remarks -In most cases you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. +In most cases, you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. The **`/reference`** compiler option requires you enable the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**). The **`/reference`** option is available starting in Visual Studio 2019 version 16.10. @@ -76,6 +76,7 @@ cl ... /std:c++latest /reference m=m.ifc /reference M:Part1=m-part.ifc /referenc ## See also +[`/scanDependencies` (List module dependencies in standard form)](scandependencies.md)\ [`/sourceDependencies:directives` (List module and header unit dependencies)](sourcedependencies-directives.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/exportHeader` (Create header units)](module-exportheader.md) diff --git a/docs/build/reference/mp-build-with-multiple-processes.md b/docs/build/reference/mp-build-with-multiple-processes.md index b63a912e7b..de05d5234b 100644 --- a/docs/build/reference/mp-build-with-multiple-processes.md +++ b/docs/build/reference/mp-build-with-multiple-processes.md @@ -1,122 +1,122 @@ --- -description: "Learn more about: /MP (Build with Multiple Processes)" -title: "/MP (Build with Multiple Processes)" -ms.date: "04/08/2019" +description: "Learn more about: /MP (Build with multiple processes)" +title: "/MP (Build with multiple processes)" +ms.date: 06/13/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.MultiProcessorCompilation"] helpviewer_keywords: ["-MP compiler option (C++)", "/MP compiler option (C++)", "MP compiler option (C++)", "cl.exe compiler, multi-process build"] --- -# /MP (Build with Multiple Processes) +# `/MP` (Build with multiple processes) -The **/MP** option can reduce the total time to compile the source files on the command line. The **/MP** option causes the compiler to create one or more copies of itself, each in a separate process. Then these copies simultaneously compile the source files. Consequently, the total time to build the source files can be significantly reduced. +The **`/MP`** option can reduce the total time to compile the source files on the command line. The **`/MP`** option causes the compiler to create one or more copies of itself, each in a separate process. Then these instances simultaneously compile the source files. In some cases, the total time to build the source files can be reduced significantly. ## Syntax -> **/MP**[*processMax*] +> **`/MP`**[*`processMax`*] ## Arguments -*processMax*
+*`processMax`*\ (Optional) The maximum number of processes that the compiler can create. -The *processMax* argument must range from 1 through 65536. Otherwise, the compiler issues warning message **D9014**, ignores the *processMax* argument, and assumes the maximum number of processes is 1. +The *`processMax`* argument must range from 1 through 65536. Otherwise, the compiler issues warning message **D9014**, ignores the *`processMax`* argument, and assumes the maximum number of processes is 1. -If you omit the *processMax* argument, the compiler retrieves the number of [effective processors](#effective_processors) on your computer from the operating system, and creates a process for each processor. +If you omit the *`processMax`* argument, the compiler retrieves the number of [effective processors](#effective_processors) on your computer from the operating system, and creates a process for each processor. ## Remarks -The **/MP** compiler option can significantly reduce build time when you compile many files. To improve build time, the compiler creates up to *processMax* copies of itself, and then uses those copies to compile your source files at the same time. The **/MP** option applies to compilations, but not to linking or link-time code generation. By default the **/MP** option is off. +The **`/MP`** compiler option can significantly reduce build time when you compile many files. To improve build time, the compiler creates up to *`processMax`* copies of itself, and then uses those copies to compile your source files at the same time. The **`/MP`** option applies to compilations, but not to linking or link-time code generation. By default the **`/MP`** option is off. -The improvement in build time depends on the number of processors on a computer, the number of files to compile, and the availability of system resources, such as I/O capacity. Experiment with the **/MP** option to determine the best setting to build a particular project. For advice to help you make that decision, see [Guidelines](#guidelines). +The improvement in build time depends on the number of processors on a computer, the number of files to compile, and the availability of system resources, such as I/O capacity. Experiment with the **`/MP`** option to determine the best setting to build a particular project. For advice to help you make that decision, see [Guidelines](#guidelines). -## Incompatible Options and Language Features +## Incompatible options and language features -The **/MP** option is incompatible with some compiler options and language features. If you use an incompatible compiler option with the **/MP** option, the compiler issues warning **D9030** and ignores the **/MP** option. If you use an incompatible language feature, the compiler issues error [C2813](../../error-messages/compiler-errors-2/compiler-error-c2813.md) then ends or continues depending on the current compiler warning level option. +The **`/MP`** option is incompatible with some compiler options and language features. If you use an incompatible compiler option with the **`/MP`** option, the compiler issues warning **D9030** and ignores the **`/MP`** option. If you use an incompatible language feature, the compiler issues error [C2813](../../error-messages/compiler-errors-2/compiler-error-c2813.md) then ends or continues depending on the current compiler warning level option. > [!NOTE] > Most options are incompatible because if they were permitted, the concurrently executing compilers would write their output at the same time to the console or to a particular file. As a result, the output would intermix and be garbled. In some cases, the combination of options would make the performance worse. -The following table lists compiler options and language features that are incompatible with the **/MP** option: +The following table lists compiler options and language features that are incompatible with the **`/MP`** option: -|Option or Language Feature|Description| -|--------------------------------|-----------------| -|[#import](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive|Converts the types in a type library into C++ classes, and then writes those classes to a header file.| -|[/E](e-preprocess-to-stdout.md), [/EP](ep-preprocess-to-stdout-without-hash-line-directives.md)|Copies preprocessor output to the standard output (**stdout**).| -|[/Gm](gm-enable-minimal-rebuild.md)|Deprecated. Enables an incremental rebuild.| -|[/showIncludes](showincludes-list-include-files.md)|Writes a list of include files to the standard error (**stderr**).| -|[/Yc](yc-create-precompiled-header-file.md)|Writes a precompiled header file.| +| Option or Language Feature | Description | +|--|--| +| [`#import`](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive | Converts the types in a type library into C++ classes, and then writes those classes to a header file. | +| [`/E`](e-preprocess-to-stdout.md), [`/EP`](ep-preprocess-to-stdout-without-hash-line-directives.md) | Copies preprocessor output to the standard output (**`stdout`**). | +| [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables an incremental rebuild. | +| [`/showIncludes`](showincludes-list-include-files.md) | Writes a list of include files to the standard error (**`stderr`**). | +| [`/Yc`](yc-create-precompiled-header-file.md) | Writes a precompiled header file. | -## Diagnostic Messages +## Diagnostic messages -If you specify an option or language feature that is incompatible with the **/MP** option, you will receive a diagnostic message. The following table lists the messages and the behavior of the compiler: +If you specify an option or language feature that is incompatible with the **`/MP`** option, you'll receive a diagnostic message. The following table lists the messages and the behavior of the compiler: -|Diagnostic Message|Description|Compiler Behavior| -|------------------------|-----------------|-----------------------| -|**C2813**|The **#import** directive is not compatible with the **/MP** option.|The compilation ends unless a [compiler warning level](compiler-option-warning-level.md) option specifies otherwise.| -|**D9014**|An invalid value is specified for the *processMax* argument.|The compiler ignores the invalid value and assumes a value of 1.| -|**D9030**|The specified option is incompatible with **/MP**.|The compiler ignores the **/MP** option.| +| Diagnostic Message | Description | Compiler Behavior | +|--|--|--| +| **C2813** | The **`#import`** directive isn't compatible with the **`/MP`** option. | The compilation ends unless a [compiler warning level](compiler-option-warning-level.md) option specifies otherwise. | +| **D9014** | An invalid value is specified for the *`processMax`* argument. | The compiler ignores the invalid value and assumes a value of 1. | +| **D9030** | The specified option is incompatible with **`/MP`**. | The compiler ignores the **`/MP`** option. | ## Guidelines -### Measure Performance +### Measure performance Use total build time to measure performance. You can measure the build time with a physical clock, or you can use software that calculates the difference between when the build starts and stops. If your computer has multiple processors, a physical clock might yield more accurate results than a software time measurement. -### Effective Processors +### Effective processors A computer can have one or more virtual processors, which are also known as *effective processors*, for each of its physical processors. Each physical processor can have one or more cores, and if the operating system enables hyperthreading for a core, each core appears to be two virtual processors. For example, a computer has one effective processor if it has one physical processor that has one core, and hyperthreading is disabled. In contrast, a computer has eight effective processors if it has two physical processors, each of which has two cores, and all the cores have hyperthreading enabled. That is, (8 effective processors) = (2 physical processors) x (2 cores per physical processor) x (2 effective processors per core because of hyperthreading). -If you omit the *processMax* argument in the **/MP** option, the compiler obtains the number of effective processors from the operating system, and then creates one process per effective processor. However, the compiler cannot guarantee which process executes on a particular processor; the operating system makes that decision. +If you omit the *`processMax`* argument in the **`/MP`** option, the compiler obtains the number of effective processors from the operating system, and then creates one process per effective processor. However, the compiler can't guarantee which process executes on a particular processor; the operating system makes that decision. -### Number of Processes +### Number of processes -The compiler calculates the number of processes that it will use to compile the source files. That value is the lesser of the number of source files that you specify on the command line, and the number of processes that you explicitly or implicitly specify with the **/MP** option. You can explicitly set the maximum number of processes if you provide the *processMax* argument of the **/MP** option. Or you can use the default, which is equal to the number of effective processors in a computer, if you omit the *processMax* argument. +The compiler calculates the number of processes that it will use to compile the source files. That value is the lesser of the number of source files that you specify on the command line, and the number of processes that you explicitly or implicitly specify with the **`/MP`** option. You can explicitly set the maximum number of processes if you provide the *`processMax`* argument of the **`/MP`** option. Or you can use the default, which is equal to the number of effective processors in a computer, if you omit the *`processMax`* argument. For example, suppose you specify the following command line: `cl /MP7 a.cpp b.cpp c.cpp d.cpp e.cpp` -In this case the compiler uses five processes because that is the lesser of five source files and a maximum of seven processes. Alternatively, suppose your computer has two effective processors and you specify the following command line: +In this case, the compiler uses five processes because that is the lesser of five source files and a maximum of seven processes. Alternatively, suppose your computer has two effective processors and you specify the following command line: `cl /MP a.cpp b.cpp c.cpp` -In this case the operating system reports two processors; therefore, the compiler uses two processes in its calculation. As a result, the compiler will execute the build with two processes because that is the lesser of two processes and three source files. +In this case, the operating system reports two processors, so the compiler uses two processes in its calculation. As a result, the compiler uses two processes to execute the build because that's the lesser of two processes and three source files. -### Source Files and Build Order +### Source files and build order -The source files might not be compiled in the same order in which they appear on the command line. Although the compiler creates a set of processes that contain copies of the compiler, the operating system schedules when each process executes. Consequently, you cannot guarantee that the source files will be compiled in a particular order. +The source files might not be compiled in the same order in which they appear on the command line. Although the compiler creates a set of processes that contain copies of the compiler, the operating system schedules when each process executes. The **`/MP`** option can't guarantee that the source files will be compiled in a particular order. A source file is compiled when a process is available to compile it. If there are more files than processes, the first set of files is compiled by the available processes. The remaining files are processed when a process finishes handling a previous file and is available to work on one of the remaining files. -Do not specify the same source file multiple times on a command line. This might occur, for example, if a tool automatically creates a [makefile](contents-of-a-makefile.md) that is based on dependency information in a project. If you do not specify the **/MP** option, the compiler processes the list of files sequentially and recompiles each occurrence of the file. However, if you specify the **/MP** option, different compilers might compile the same file at the same time. Consequently, the different compilers will try to write to the same output file at the same time. One compiler will acquire exclusive write access to the output file and succeed, and the other compilers will fail with a file access error. +Don't specify the same source file multiple times on a command line. Multiple specifications could occur, for example, if a tool automatically creates a [makefile](contents-of-a-makefile.md) that's based on dependency information in a project. If you don't specify the **`/MP`** option, the compiler processes the list of files sequentially and recompiles each occurrence of the file. However, if you specify the **`/MP`** option, different compiler instances might compile the same file at the same time. The different instances may try to write to the same output file at the same time. One compiler instance acquires exclusive write access to the output file and succeed, and the other compiler instances fail with a file access error. -### Using Type Libraries (#import) +### Using type libraries (`#import`) -The compiler does not support the use of the [#import](../../preprocessor/hash-import-directive-cpp.md) directive with the **/MP** switch. If possible, follow these steps to work around this problem: +The compiler doesn't support the use of the [`#import`](../../preprocessor/hash-import-directive-cpp.md) directive with the **`/MP`** switch. If possible, follow these steps to work around this problem: -- Move all the `#import` directives in your various source files to one or more files, and then compile those files without the **/MP** option. The result is a set of generated header files. +- Move all the `#import` directives in your various source files to one or more files, and then compile those files without the **`/MP`** option. The result is a set of generated header files. -- In your remaining source files, insert [#include](../../preprocessor/hash-include-directive-c-cpp.md) directives that specify the generated headers, and then compile your remaining source files by using the **/MP** option. +- In your remaining source files, insert [`#include`](../../preprocessor/hash-include-directive-c-cpp.md) directives that specify the generated headers, and then compile your remaining source files by using the **`/MP`** option. -### Visual Studio Project Settings +### Visual Studio Project settings -#### The MSBUILD.exe Tool +#### The MSBuild tool -Visual Studio uses the [MSBuild.exe](/visualstudio/msbuild/msbuild-reference) tool to build solutions and projects. The **/maxcpucount:**_number_ (or **/m:**_number_) command-line option of the MSBuild.exe tool can build multiple projects at the same time. And the **/MP** compiler option can build multiple compilation units at the same time. If it is appropriate for your application, improve your solution's build time by using either or both **/MP** and **/maxcpucount**. +Visual Studio uses the [`MSBuild`](/visualstudio/msbuild/msbuild-reference) tool (`msbuild.exe`) to build solutions and projects. The **`/maxcpucount:number`** (or **`/m:number`**) command-line option of the MSBuild tool can build multiple projects at the same time. And the **`/MP`** compiler option can build multiple compilation units at the same time. If it's appropriate for your application, improve your solution's build time by using either or both **`/MP`** and **`/maxcpucount`**. -The build time of your solution partly depends on the number of processes that perform the build. The *number* argument of the [/maxcpucount](/visualstudio/msbuild/msbuild-command-line-reference) MSBuild option specifies the maximum number of projects to build at the same time. Similarly, the *processMax* argument of the **/MP** compiler option specifies the maximum number of compilation units to build at the same time. If the **/maxcpucount** option specifies *P* projects and the **/MP** option specifies *C* processes, a maximum of *P* x *C* processes execute at the same time. +The build time of your solution partly depends on the number of processes that perform the build. The *`number`* argument of the [`/maxcpucount`](/visualstudio/msbuild/msbuild-command-line-reference) MSBuild option specifies the maximum number of projects to build at the same time. Similarly, the *`processMax`* argument of the **`/MP`** compiler option specifies the maximum number of compilation units to build at the same time. If the **`/maxcpucount`** option specifies *P* projects and the **`/MP`** option specifies *C* processes, a maximum of *P* x *C* processes execute at the same time. -The guideline for deciding whether to use MSBuild or **/MP** technology is as follows: +The guideline for deciding whether to use MSBuild or **`/MP`** technology is as follows: -- If there are many projects with few files in each project, use the MSBuild tool. +- If there are many projects with few files in each project, use the MSBuild tool with the **`/maxcpucount`** option. -- If there are few projects with many files in each project, use the **/MP** option. +- If there are few projects with many files in each project, use the **`/MP`** option. -- If the number of projects and files per project is balanced, use both MSBuild and **/MP**. Initially set the **/maxcpucount** option to the number of projects to build and the **/MP** option to the number of processors on your computer. Measure performance and then adjust your settings to yield the best results. Repeat that cycle until you are satisfied with the total build time. +- If the number of projects and files per project is balanced, use both MSBuild and **`/MP`**. Initially set the **`/maxcpucount`** option to the number of projects to build and the **`/MP`** option to the number of processors on your computer. Measure performance and then adjust your settings to yield the best results. Repeat that cycle until you're satisfied with the total build time. ## See also -[#import Directive](../../preprocessor/hash-import-directive-cpp.md)
-[Command-Line Reference](/visualstudio/msbuild/msbuild-command-line-reference)
-[/Zf (Faster PDB generation)](zf.md)
+[`#import` directive](../../preprocessor/hash-import-directive-cpp.md)\ +[MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference)\ +[`/Zf` (Faster PDB generation)](zf.md) diff --git a/docs/build/reference/msbuild-reference-cpp.md b/docs/build/reference/msbuild-reference-cpp.md index e779a699b2..bbc889a922 100644 --- a/docs/build/reference/msbuild-reference-cpp.md +++ b/docs/build/reference/msbuild-reference-cpp.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: MSBuild reference for C++ projects" title: "MSBuild reference for C++ projects in Visual Studio" -ms.date: "12/08/2018" +description: "Learn more about: MSBuild reference for C++ projects" +ms.date: 12/08/2018 helpviewer_keywords: ["MSBuild reference [C++]"] --- # MSBuild reference for C++ projects @@ -12,25 +12,25 @@ If for some reason you wish to use MSBuild directly from the command line, see [ ## In this section -[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)
+[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)\ Information about how properties and targets are stored and consumed. -[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)
+[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)\ Describes macros (compile-time constants) that can be used to define properties such as paths and product versions. -[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)
+[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)\ Describes the various kinds of files that Visual Studio creates for different project types. -[Visual Studio C++ project templates](visual-cpp-project-types.md)
+[Visual Studio C++ project templates](visual-cpp-project-types.md)\ Describes the MSBuild-based project types that are available for C++. -[C++ new item templates](using-visual-cpp-add-new-item-templates.md)
+[C++ new item templates](using-visual-cpp-add-new-item-templates.md)\ Describes source files and other items you can add to a Visual Studio project. -[Precompiled header files](../creating-precompiled-header-files.md) +[Precompiled header files](../creating-precompiled-header-files.md)\ How to use precompiled header files and how to create your own custom precompiled code to speed up build times. -[Visual Studio project property reference](property-pages-visual-cpp.md)
+[Visual Studio project property reference](property-pages-visual-cpp.md)\ Reference documentation for project properties that are set in the Visual Studio IDE. ## See also diff --git a/docs/build/reference/msbuild-visual-cpp-overview.md b/docs/build/reference/msbuild-visual-cpp-overview.md index 85b0314b00..e614f2f98a 100644 --- a/docs/build/reference/msbuild-visual-cpp-overview.md +++ b/docs/build/reference/msbuild-visual-cpp-overview.md @@ -1,7 +1,7 @@ --- title: "MSBuild internals for C++ projects in Visual Studio" description: "The support files, properties, and targets used by MSBuild for Visual Studio C++ projects." -ms.date: 10/14/2020 +ms.date: 02/10/2022 helpviewer_keywords: ["MSBuild overview"] --- # MSBuild internals for C++ projects @@ -16,11 +16,11 @@ By default, the primary Visual Studio support files are located in the following ::: moniker range=">=msvc-160" -### Visual Studio 2019 +### Visual Studio 2022 and 2019 - *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\`* - Contains the primary target files (.targets) and property files (.props) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. The *``* placeholder refers to the Visual Studio version: v160 for Visual Studio 2019, v150 for Visual Studio 2017. + Contains the primary target files (*`.targets`*) and property files (*`.props`*) that are used by the targets. By default, the `$(VCTargetsPath)` macro references this directory. The *``* placeholder refers to the Visual Studio version: v170 for Visual Studio 2022, v160 for Visual Studio 2019, or v150 for Visual Studio 2017. - *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\Platforms\\`* @@ -52,19 +52,19 @@ By default, the primary Visual Studio support files are located in the following ### Visual Studio 2015 and earlier -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\`* - Contains the primary target files (.targets) and property files (.props) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. + Contains the primary target files (*`.targets`*) and property files (*`.props`*) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\`* Contains platform-specific target and property files that override targets and properties in its parent directory. This directory also contains a DLL that defines the tasks that are used by the targets in this directory. The *``* placeholder represents the ARM, Win32, or x64 subdirectory. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\PlatformToolsets\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\PlatformToolsets\\`* Contains the directories that enable the build to generate C++ applications by using the specified *``*. The *``* placeholder is V110 for Visual Studio 2012, V120 for Visual Studio 2013, and V140 for Visual Studio 2015. The *``* placeholder represents the ARM, Win32, or x64 subdirectory. The *``* placeholder represents the toolset subdirectory. For example, it's v140 for building Windows apps by using the Visual Studio 2015 toolset. Or, v120_xp to build for Windows XP using the Visual Studio 2013 toolset. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\Platforms\\PlatformToolsets\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\Platforms\\PlatformToolsets\\`* The paths that enable the build to generate either Visual Studio 2008 or Visual Studio 2010 applications don't include the *``*. In those versions, the *``* placeholder represents the Itanium, Win32, or x64 subdirectory. The *``* placeholder represents the v90 or v100 toolset subdirectory. @@ -74,13 +74,13 @@ The support file directories contain files with these extensions: | Extension | Description | | --------- | ----------- | -| *`.targets`* | Contains `Target` XML elements that specify the tasks that are executed by the target. May also contain `PropertyGroup`, `ItemGroup`, `ItemDefinitionGroup`, and user-defined `Item` elements that are used to assign files and command-line options to task parameters.

For more information, see [Target Element (MSBuild)](/visualstudio/msbuild/target-element-msbuild). | -| *`.props`* | Contains `Property Group` and user-defined `Property` XML elements that specify file and parameter settings that are used during a build.

May also contain `ItemDefinitionGroup` and user-defined `Item` XML elements that specify additional settings. Items defined in an item definition group resemble properties, but can't be accessed from the command line. Visual Studio project files frequently use items instead of properties to represent settings.

For more information, see [ItemGroup Element (MSBuild)](/visualstudio/msbuild/itemgroup-element-msbuild), [ItemDefinitionGroup Element (MSBuild)](/visualstudio/msbuild/itemdefinitiongroup-element-msbuild), and [Item Element (MSBuild)](/visualstudio/msbuild/item-element-msbuild). | +| *`.targets`* | Contains `Target` XML elements that specify the tasks that are executed by the target. May also contain `PropertyGroup`, `ItemGroup`, `ItemDefinitionGroup`, and user-defined `Item` elements that are used to assign files and command-line options to task parameters.

For more information, see [`Target` Element (MSBuild)](/visualstudio/msbuild/target-element-msbuild). | +| *`.props`* | Contains `Property Group` and user-defined `Property` XML elements that specify file and parameter settings that are used during a build.

May also contain `ItemDefinitionGroup` and user-defined `Item` XML elements that specify additional settings. Items defined in an item definition group resemble properties, but can't be accessed from the command line. Visual Studio project files frequently use items instead of properties to represent settings.

For more information, see [`ItemGroup` Element (MSBuild)](/visualstudio/msbuild/itemgroup-element-msbuild), [`ItemDefinitionGroup` Element (MSBuild)](/visualstudio/msbuild/itemdefinitiongroup-element-msbuild), and [`Item` Element (MSBuild)](/visualstudio/msbuild/item-element-msbuild). | | *`.xml`* | Contains XML elements that declare and initialize IDE user interface elements. For example, property sheets, property pages, textbox controls, and listbox controls.

The *`.xml`* files directly support the IDE, not MSBuild. However, the values of IDE properties are assigned to build properties and items.

Most *`.xml`* files are in a locale-specific subdirectory. For example, files for the English-US region are in `$(VCTargetsPath)\1033\`. | ## User targets and properties -To use MSBuild effectively, it helps to know which properties and targets are useful and relevant. Most properties and targets help implement the Visual Studio build system, and consequently aren't relevant to the user. This section describes user-oriented properties and targets worth knowing about. +To use MSBuild effectively, it helps to know which properties and targets are useful and relevant. Most properties and targets help implement the Visual Studio build system, and aren't relevant to the user. This section describes user-oriented properties and targets worth knowing about. ### `PlatformToolset` property @@ -100,7 +100,7 @@ For example, set the `PreferredToolArchitecture` property to `x64` to use the 64 ### `UseEnv` property -By default, the platform-specific settings for the current project override the PATH, INCLUDE, LIB, LIBPATH, CONFIGURATION, and PLATFORM environment variables. Set the `UseEnv` property to **`true`** to guarantee that the environment variables don't get overridden. +By default, the platform-specific settings for the current project override the `PATH`, `INCLUDE`, `LIB`, `LIBPATH`, `CONFIGURATION`, and `PLATFORM` environment variables. Set the `UseEnv` property to **`true`** to guarantee that the environment variables don't get overridden. > `msbuild myProject.vcxproj /p:UseEnv=true` @@ -112,33 +112,33 @@ The following table lists several useful user-oriented targets. | Target | Description | | ------ | ----------- | -| BscMake | Executes the Microsoft Browse Information Maintenance Utility tool, bscmake.exe. | -| Build | Builds the project.

This target is the default for a project. | -| ClCompile | Executes the MSVC compiler tool, cl.exe. | -| Clean | Deletes temporary and intermediate build files. | -| Lib | Executes the Microsoft 32-Bit Library Manager tool, lib.exe. | -| Link | Executes the MSVC linker tool, link.exe. | -| ManifestResourceCompile | Extracts a list of resources from a manifest and then executes the Microsoft Windows Resource Compiler tool, rc.exe. | -| Midl | Executes the Microsoft Interface Definition Language (MIDL) compiler tool, midl.exe. | -| Rebuild | Cleans and then builds your project. | -| ResourceCompile | Executes the Microsoft Windows Resource Compiler tool, rc.exe. | -| XdcMake | Executes the XML Documentation tool, xdcmake.exe. | -| Xsd | Executes the XML Schema Definition tool, xsd.exe. *See note.* | +| `BscMake` | Executes the Microsoft Browse Information Maintenance Utility tool, *`bscmake.exe`*. | +| `Build` | Builds the project.

This target is the default for a project. | +| `ClCompile` | Executes the MSVC compiler tool, *`cl.exe`*. | +| `Clean` | Deletes temporary and intermediate build files. | +| `Lib` | Executes the Microsoft 32-Bit Library Manager tool, *`lib.exe`*. | +| `Link` | Executes the MSVC linker tool, *`link.exe`*. | +| `ManifestResourceCompile` | Extracts a list of resources from a manifest and then executes the Microsoft Windows Resource Compiler tool, *`rc.exe`*. | +| `Midl` | Executes the Microsoft Interface Definition Language (MIDL) compiler tool, *`midl.exe`*. | +| `Rebuild` | Cleans and then builds your project. | +| `ResourceCompile` | Executes the Microsoft Windows Resource Compiler tool, *`rc.exe`*. | +| `XdcMake` | Executes the XML Documentation tool, *`xdcmake.exe`*. | +| `Xsd` | Executes the XML Schema Definition tool, *`xsd.exe`*. *See note.* | > [!NOTE] -> In Visual Studio 2017 and later, C++ project support for **xsd** files is deprecated. You can still use **Microsoft.VisualC.CppCodeProvider** by adding **CppCodeProvider.dll** manually to the GAC. +> In Visual Studio 2017 and later, C++ project support for *`.xsd`* files is deprecated. You can still use `Microsoft.VisualC.CppCodeProvider` by adding *`CppCodeProvider.dll`* manually to the GAC. ## See also -[MSBuild Task Reference](/visualstudio/msbuild/msbuild-task-reference)\ -[BscMake Task](/visualstudio/msbuild/bscmake-task)\ -[CL Task](/visualstudio/msbuild/cl-task)\ -[CPPClean Task](/visualstudio/msbuild/cppclean-task)\ -[LIB Task](/visualstudio/msbuild/lib-task)\ -[Link Task](/visualstudio/msbuild/link-task)\ -[MIDL Task](/visualstudio/msbuild/midl-task)\ -[MT Task](/visualstudio/msbuild/mt-task)\ -[RC Task](/visualstudio/msbuild/rc-task)\ -[SetEnv Task](/visualstudio/msbuild/setenv-task)\ -[VCMessage Task](/visualstudio/msbuild/vcmessage-task)\ -[XDCMake Task](/visualstudio/msbuild/xdcmake-task) +[MSBuild task reference](/visualstudio/msbuild/msbuild-task-reference)\ +[`BscMake` task](/visualstudio/msbuild/bscmake-task)\ +[`CL` task](/visualstudio/msbuild/cl-task)\ +[`CPPClean` task](/visualstudio/msbuild/cppclean-task)\ +[`LIB` task](/visualstudio/msbuild/lib-task)\ +[`Link` task](/visualstudio/msbuild/link-task)\ +[`MIDL` task](/visualstudio/msbuild/midl-task)\ +[`MT` task](/visualstudio/msbuild/mt-task)\ +[`RC` task](/visualstudio/msbuild/rc-task)\ +[`SetEnv` task](/visualstudio/msbuild/setenv-task)\ +[`VCMessage` task](/visualstudio/msbuild/vcmessage-task)\ +[`XDCMake` task](/visualstudio/msbuild/xdcmake-task) diff --git a/docs/build/reference/natvis-add-natvis-to-pdb.md b/docs/build/reference/natvis-add-natvis-to-pdb.md index 326072d5fa..dbc59b4eb0 100644 --- a/docs/build/reference/natvis-add-natvis-to-pdb.md +++ b/docs/build/reference/natvis-add-natvis-to-pdb.md @@ -1,39 +1,43 @@ --- description: "Learn more about: /NATVIS (Add Natvis to PDB)" title: "/NATVIS (Add Natvis to PDB)" -ms.date: "08/10/2017" -f1_keywords: ["/natvis"] +ms.date: 09/08/2022 +f1_keywords: ["/natvis", "natvis"] helpviewer_keywords: ["NATVIS linker option", "/NATVIS linker option", "-NATVIS linker option", "Add Natvis file to PDB"] ms.assetid: 8747fc0c-701a-4796-bb4d-818ab4465cca --- -# /NATVIS (Add Natvis to PDB) +# `/NATVIS` (Add Natvis to PDB) -> /NATVIS:*filename* +Specifies a debugger visualization file (a Natvis file) to embed in the PDB file generated by the linker. + +## Syntax + +> **`/NATVIS:`***`filename`* ## Parameters -*filename*
-A Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. +*`filename`*\ +The pathname for a Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. ## Remarks -The /NATVIS option embeds the debugger visualizations defined in the Natvis file *filename* into the PDB file generated by LINK. This allows the debugger to display the visualizations independently of the .natvis file. You can use multiple /NATVIS options to embed more than one Natvis file in the generated PDB file. +The **`/NATVIS`** linker option embeds the debugger visualizations defined in the Natvis file *`filename`* into the PDB file generated by LINK. A Natvis file has a *`.natvis`* extension. Embedding the information allows the debugger to display the visualizations independently of the Natvis file. You can use multiple **`/NATVIS`** options to embed more than one Natvis file in the generated PDB file. For more information on how to create and use Natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). -LINK ignores /NATVIS when a PDB file is not created by using a [/DEBUG](debug-generate-debug-info.md) option. For information on creation and use of .natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). +LINK ignores **`/NATVIS`** when a PDB file isn't created by using a [`/DEBUG`](debug-generate-debug-info.md) option. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Add the *`/NATVIS`* option to the **Additional Options** text box. +1. Add the *`/NATVIS`* option to the **Additional Options** text box. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- This option does not have a programmatic equivalent. +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/netmodule-files-as-linker-input.md b/docs/build/reference/netmodule-files-as-linker-input.md index 6b5af46bb6..5bd54dc8df 100644 --- a/docs/build/reference/netmodule-files-as-linker-input.md +++ b/docs/build/reference/netmodule-files-as-linker-input.md @@ -16,7 +16,7 @@ link.exe accepts MSIL *`.obj`* and *`.netmodule`* files as input. The output fil The linker must be passed the *`.obj`* file from the C++ compilation that created the *`.netmodule`*. Passing in a *`.netmodule`* is no longer supported because the **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -For information on how to invoke the linker from the command line, see [Linker command-line syntax](linking.md), [Use the MSVC toolset from the command line](../building-on-the-command-line.md), and [Use the MSVC toolset from the command line](../building-on-the-command-line.md). +For information on how to invoke the linker from the command line, see [Linker command-line syntax](linking.md) and [Use the MSVC toolset from the command line](../building-on-the-command-line.md). Passing a *`.netmodule`* or *`.dll`* file to the linker that was compiled by the MSVC compiler with **/clr** can result in a linker error. For more information, see [Choosing the format of .netmodule input files](choosing-the-format-of-netmodule-input-files.md). diff --git a/docs/build/reference/nmake-function-abspath.md b/docs/build/reference/nmake-function-abspath.md index 73efeb8193..49297c7264 100644 --- a/docs/build/reference/nmake-function-abspath.md +++ b/docs/build/reference/nmake-function-abspath.md @@ -28,7 +28,7 @@ A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items fr `abspath` supports extended-length paths, either by using the `\\?\` prefix, or when long paths are enabled. For more information about long paths, see [Maximum Path Length Limitation](/windows/win32/fileio/maximum-file-path-limitation). -This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. ## Example diff --git a/docs/build/reference/nmake-function-basename.md b/docs/build/reference/nmake-function-basename.md index 1289f9f7d9..c72a40b563 100644 --- a/docs/build/reference/nmake-function-basename.md +++ b/docs/build/reference/nmake-function-basename.md @@ -30,7 +30,7 @@ A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items fr The `basename` function is equivalent to using the [`R` modifier in a filename macro](special-nmake-macros.md#filename-macros). -This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. ## Example diff --git a/docs/build/reference/nmake-function-lowercase.md b/docs/build/reference/nmake-function-lowercase.md new file mode 100644 index 0000000000..bacd24a70b --- /dev/null +++ b/docs/build/reference/nmake-function-lowercase.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: lowercase NMAKE function" +title: "lowercase NMAKE function" +ms.date: "2/23/2022" +helpviewer_keywords: ["lowercase NMAKE function", "NMAKE function, lowercase"] +monikerRange: '>=msvc-170' +--- +# `lowercase` NMAKE function + +Evaluates to a string where all characters have been converted to their lowercase equivalent. + +## Syntax + +```makefile +$(lowercase input) +``` + +### Parameters + +*`input`*\ +The string to convert. + +## Return value + +Returns *`input`*, but all characters have been converted to their lowercase equivalent. + +## Remarks + +This macro function is available starting in Visual Studio 2022 version 17.2, in NMAKE version 14.32 or later. + +## Example + +```makefile +$(lowercase Hello World!) # Evaluates to "hello world!" +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-patsubst.md b/docs/build/reference/nmake-function-patsubst.md index dac44c57c5..c060a65350 100644 --- a/docs/build/reference/nmake-function-patsubst.md +++ b/docs/build/reference/nmake-function-patsubst.md @@ -35,7 +35,7 @@ Returns *`input`*, but each item that matches *`pattern`* is replaced by *`repla `patsubsti` is the case-insensitive version of `patsubst`. -This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. ## Example diff --git a/docs/build/reference/nmake-function-uppercase.md b/docs/build/reference/nmake-function-uppercase.md new file mode 100644 index 0000000000..0b0a64969e --- /dev/null +++ b/docs/build/reference/nmake-function-uppercase.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: uppercase NMAKE function" +title: "uppercase NMAKE function" +ms.date: "2/23/2022" +helpviewer_keywords: ["uppercase NMAKE function", "NMAKE function, uppercase"] +monikerRange: '>=msvc-170' +--- +# `uppercase` NMAKE function + +Evaluates to a string where all characters have been converted to their uppercase equivalent. + +## Syntax + +```makefile +$(uppercase input) +``` + +### Parameters + +*`input`*\ +The string to convert. + +## Return value + +Returns *`input`*, but all characters have been converted to their uppercase equivalent. + +## Remarks + +This macro function is available starting in Visual Studio 2022 version 17.2, in NMAKE version 14.32 or later. + +## Example + +```makefile +$(uppercase Hello World!) # Evaluates to "HELLO WORLD!" +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-property-page.md b/docs/build/reference/nmake-property-page.md index c44c478a15..d726226b5a 100644 --- a/docs/build/reference/nmake-property-page.md +++ b/docs/build/reference/nmake-property-page.md @@ -1,6 +1,6 @@ --- description: "Learn more about: NMake Property Page" -title: "NMake Property Page (Windows C++)| Microsoft Docs" +title: NMake Property Page (Windows C++) ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCNMakeTool.ReBuildCommandLine", "VC.Project.VCNMakeTool.CleanCommandLine", "VC.Project.VCNMakeTool.Output", "VC.Project.VCNMakeTool.BuildCommandLine"] helpviewer_keywords: ["NMake property page"] @@ -8,13 +8,13 @@ ms.assetid: bd20cb52-9f1d-4240-b4fc-4f43205ac94b --- # NMake Property Page -The **NMake** property page lets you specify build settings for NMake projects. (NMAKE is the Microsoft implementation of [Make](https://wikipedia.org/wiki/Make_(software)).) +The **NMake** property page lets you specify build settings for *Makefile* projects. (NMAKE is the Microsoft implementation of [Make](https://wikipedia.org/wiki/Make_(software)).) -For more information about NMake projects, see [Creating a Makefile Project](creating-a-makefile-project.md). For non-Windows MakeFile projects, see [MakeFile Project Properties (Linux C++)](../../linux/prop-pages/makefile-linux.md), [General Project Properties (Android C++ Makefile)](/visualstudio/cross-platform/general-makefile-android-prop-page) or [NMake Properties (Android C++)](/visualstudio/cross-platform/nmake-android-prop-page). +For more information about Makefile projects, see [Creating a Makefile Project](creating-a-makefile-project.md). For non-Windows Makefile projects, see [Makefile Project Properties (Linux C++)](../../linux/prop-pages/makefile-linux.md), [General Project Properties (Android C++ Makefile)](/visualstudio/cross-platform/general-makefile-android-prop-page) or [NMake Properties (Android C++)](/visualstudio/cross-platform/nmake-android-prop-page). -The **NMake** property page contains the following properties. +The property page contains the following properties: -## UIElement List +## General - **Build Command Line** @@ -32,6 +32,8 @@ The **NMake** property page contains the following properties. Specifies the name of the file that will contain the output for the command line. By default, this file name is based on the project name. +## IntelliSense + - **Preprocessor Definitions** Specifies any preprocessor definitions that the source files use. The default value is determined by the current platform and configuration. @@ -42,11 +44,11 @@ The **NMake** property page contains the following properties. - **Forced Includes** - Specifies files that the preprocessor automatically processes even if they are not included in the project files. + Specifies files that the preprocessor automatically processes even if they aren't included in the project files. - **Assembly Search Path** - Specifies the directories where the .NET Framework searches when it trys to resolve .NET assemblies. + Specifies the directories where the .NET Framework searches when it resolves .NET assemblies. - **Forced Using Assemblies** @@ -54,9 +56,9 @@ The **NMake** property page contains the following properties. - **Additional Options** - Specifies any additional compiler switches for IntelliSense to use when it parses C++ files. + Specifies any extra compiler switches for IntelliSense to use when it parses C++ files. -For information about how to access the **NMake** property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +For information about how to access this property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). For information about how to programmatically access members of this object, see . diff --git a/docs/build/reference/no-function-pad-section.md b/docs/build/reference/no-function-pad-section.md new file mode 100644 index 0000000000..a63675b5cd --- /dev/null +++ b/docs/build/reference/no-function-pad-section.md @@ -0,0 +1,43 @@ +--- +description: "Learn more about: /NOFUNCTIONPADSECTION (Disable function padding)" +title: "/NOFUNCTIONPADSECTION (Disable function padding)" +ms.date: 01/09/2024 +helpviewer_keywords: ["/NOFUNCTIONPADSECTION linker option", "-NOFUNCTIONPADSECTION linker option", "NOFUNCTIONPADSECTION linker option"] +--- +# /NOFUNCTIONPADSECTION (Disable function padding) + +Disables function padding for functions in the specified section. + +## Syntax + +``` +/NOFUNCTIONPADSECTION:[name] +``` + +## Arguments + +*name*\ +The name of the section to disable x64 function padding in. + +## Remarks + +You can instruct the linker to put a specified minimum number of bytes between functions with [`/FUNCTIONPADMIN` (Create hotpatchable image)](../reference/functionpadmin-create-hotpatchable-image.md) and [`/ARM64XFUNCTIONPADMINX64`](arm64-function-pad-min-x64.md). This flag disables adding that padding for the specified sections. + +To exclude multiple sections, specify the switch multiple times. + +This flag is available starting with in Visual Studio 17.8 and later. + +### To set this linker option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Modify the **Additional Options** property to include **/NOFUNCTIONPADSECTION:**`name`, where `name` is the name of the section to disable x64 function padding in, and then choose **OK**. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC Linker Options](linker-options.md)\ +[MSVC linker reference](linking.md) diff --git a/docs/build/reference/nodefaultlib-ignore-libraries.md b/docs/build/reference/nodefaultlib-ignore-libraries.md index f5c94dc4a6..646e515a1e 100644 --- a/docs/build/reference/nodefaultlib-ignore-libraries.md +++ b/docs/build/reference/nodefaultlib-ignore-libraries.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: /NODEFAULTLIB (Ignore Libraries)" -title: "/NODEFAULTLIB (Ignore Libraries)" -ms.date: "03/26/2019" -f1_keywords: ["VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] +description: "Learn more about: /NODEFAULTLIB (Ignore libraries)" +title: "/NODEFAULTLIB (Ignore libraries)" +ms.date: 04/16/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreAllDefaultLibraries", "VC.Project.VCLinkerTool.IgnoreDefaultLibraryNames", "VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] helpviewer_keywords: ["default libraries, removing", "-NODEFAULTLIB linker option", "libraries, ignore", "NODEFAULTLIB linker option", "/NODEFAULTLIB linker option", "ignore libraries linker option"] -ms.assetid: 7270b673-6711-468e-97a7-c2925ac2be6e --- -# /NODEFAULTLIB (Ignore Libraries) +# `/NODEFAULTLIB` (Ignore Libraries) -> **/NODEFAULTLIB**[__:__*library*] +Unless an optional library name is provided, the `/NODEFAULTLIB` linker option removes all libraries not explicitly specified on the linker command-line. This also includes `#pragma`, `cl.exe` command-line switches, libs referenced by other libs, and so on. + +## Syntax + +> **`/NODEFAULTLIB`**\[**`:`***`library`*] ## Arguments -*library*
-A library that you want the linker to ignore when it resolves external references. +*`library`*\ +An optional library name that you want the linker to ignore when it resolves external references. ## Remarks -The /NODEFAULTLIB option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. - -To create an .obj file that contains no references to default libraries, use [/Zl (Omit Default Library Name)](zl-omit-default-library-name.md). +To create an *`.obj`* file that contains no references to default libraries, use [`/Zl` (Omit default library name)](zl-omit-default-library-name.md). -By default, /NODEFAULTLIB removes all default libraries from the list of libraries it searches when resolving external references. The optional *library* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one /NODEFAULTLIB option for each library you want to exclude. +By default, **`/NODEFAULTLIB`** removes all default libraries from the list of libraries it searches when resolving external references. The optional *`library`* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one **`/NODEFAULTLIB`** option for each library you want to exclude. -The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified with the [/DEFAULTLIB:](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. +The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified by the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. -/NODEFAULTLIB:*library* overrides /DEFAULTLIB:*library* when the same *library* name is specified in both. +**`/NODEFAULTLIB:`***`library`* overrides **`/DEFAULTLIB:`***`library`* when the same *`library`* name is specified in both. -If you use /NODEFAULTLIB to build your program without the C run-time library, you may have to also use [/ENTRY](entry-entry-point-symbol.md) to specify the entry-point function in your program. For more information, see [CRT Library Features](../../c-runtime-library/crt-library-features.md). +If you use **`/NODEFAULTLIB`** to build your program without the C run-time library, you may also have to use the [`/ENTRY`](entry-entry-point-symbol.md) option to specify the entry-point function in your program. For more information, see [CRT library features](../../c-runtime-library/crt-library-features.md). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Input** property page. - -1. Select the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Command Line** property page shows the effect of the changes you make to these properties. +1. Modify the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Linker** > **Command Line** property page shows the effect of the changes you make to these properties. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -43,5 +43,5 @@ If you use /NODEFAULTLIB to build your program without the C run-time library, y ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md index c723f7ca02..b8497a078d 100644 --- a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md +++ b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md @@ -1,23 +1,23 @@ --- title: "/NXCOMPAT (Compatible with Data Execution Prevention)" description: "Describes the Microsoft C/C++ (MSVC) /NXCOMPAT linker option, which marks an executable as compatible with Data Execution Prevention (DEP)." -ms.date: "12/17/2019" -f1_keywords: ["/NXCOMPAT"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.DataExecutionPrevention", "/NXCOMPAT"] helpviewer_keywords: ["/NXCOMPAT linker option", "-NXCOMPAT linker option", "NXCOMPAT linker option"] --- -# /NXCOMPAT (Compatible with Data Execution Prevention) +# `/NXCOMPAT` (Compatible with Data Execution Prevention) Indicates that an executable is compatible with the Windows Data Execution Prevention feature. ## Syntax -> **/NXCOMPAT**[**:NO**] +> **`/NXCOMPAT`**[**`:NO`**] ## Remarks -By default, **/NXCOMPAT** is on. +By default, **`/NXCOMPAT`** is on. -**/NXCOMPAT:NO** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. +**`/NXCOMPAT:NO`** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. For more information about Data Execution Prevention, see these articles: @@ -27,17 +27,17 @@ For more information about Data Execution Prevention, see these articles: ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Data Execution Prevention (DEP)** property. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically -- See . +- See . ## See also [MSVC linker reference](linking.md)\ -[MSVC Linker Options](linker-options.md) +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/oi-generate-intrinsic-functions.md b/docs/build/reference/oi-generate-intrinsic-functions.md index 7eb1b3e971..22b21114a4 100644 --- a/docs/build/reference/oi-generate-intrinsic-functions.md +++ b/docs/build/reference/oi-generate-intrinsic-functions.md @@ -4,7 +4,6 @@ title: "/Oi (Generate Intrinsic Functions)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.EnableIntrinsicFunctions", "/oi", "VC.Project.VCCLWCECompilerTool.EnableIntrinsicFunctions"] helpviewer_keywords: ["Oi compiler option [C++]", "intrinsic functions, generate", "/Oi compiler option [C++]", "-Oi compiler option [C++]", "generate intrinsic functions compiler option [C++]"] -ms.assetid: fa4a3bf6-0ed8-481b-91c0-add7636132b4 --- # /Oi (Generate Intrinsic Functions) @@ -18,17 +17,18 @@ Replaces some function calls with intrinsic or otherwise special forms of the fu ## Remarks -Programs that use intrinsic functions are faster because they do not have the overhead of function calls, but may be larger because of the additional code created. +Programs that use intrinsic functions are faster because they don't have the overhead of function calls but may be larger because of the extra code created. -See [intrinsic](../../preprocessor/intrinsic.md) for more information on which functions have intrinsic forms. +For more information about which functions have intrinsic forms, see [intrinsic](../../preprocessor/intrinsic.md). -**/Oi** is only a request to the compiler to replace some function calls with intrinsics; the compiler may call the function (and not replace the function call with an intrinsic) if it will result in better performance. +**/Oi** is only a request to the compiler to replace some function calls with intrinsics. The compiler may call the function (and not replace the function call with an intrinsic) if it results in better performance.\ +**/Oi-** turns off this behavior, which may be useful if `/Oi` has been specified elsewhere and you want to override it. **x86 Specific** -The intrinsic floating-point functions do not perform any special checks on input values and so work in restricted ranges of input, and have different exception handling and boundary conditions than the library routines with the same name. Using the true intrinsic forms implies loss of IEEE exception handling, and loss of `_matherr` and `errno` functionality; the latter implies loss of ANSI conformance. However, the intrinsic forms can considerably speed up floating-point-intensive programs, and for many programs, the conformance issues are of little practical value. +The intrinsic floating-point functions don't perform any special checks on input values and so work in restricted ranges of input, and have different exception handling and boundary conditions than the library routines with the same name. Using the true intrinsic forms implies loss of IEEE exception handling, and loss of `_matherr` and `errno` functionality; the latter implies loss of ANSI conformance. However, the intrinsic forms can considerably speed up floating-point-intensive programs, and for many programs, the conformance issues are of little practical value. -You can use the [Za](za-ze-disable-language-extensions.md) compiler option to override generation of true intrinsic floating-point options. In this case, the functions are generated as library routines that pass arguments directly to the floating-point chip instead of pushing them onto the program stack. +You can use the [`Za`](za-ze-disable-language-extensions.md) compiler option to override generation of true intrinsic floating-point options. In this case, the functions are generated as library routines that pass arguments directly to the floating-point chip instead of pushing them onto the program stack. **END x86 Specific** @@ -37,9 +37,7 @@ You also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic fu ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **C/C++** > **Optimization** property page. - 1. Modify the **Enable Intrinsic Functions** property. ### To set this compiler option programmatically @@ -48,7 +46,7 @@ You also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic fu ## See also -[/O Options (Optimize Code)](o-options-optimize-code.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
+[/O Options (Optimize Code)](o-options-optimize-code.md)\ +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md) diff --git a/docs/build/reference/openmp-enable-openmp-2-0-support.md b/docs/build/reference/openmp-enable-openmp-2-0-support.md index 388695f426..3e1687f5a2 100644 --- a/docs/build/reference/openmp-enable-openmp-2-0-support.md +++ b/docs/build/reference/openmp-enable-openmp-2-0-support.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /openmp (Enable OpenMP Support)" title: "/openmp (Enable OpenMP Support)" -ms.date: 04/01/2021 +ms.date: 07/05/2023 f1_keywords: ["/openmp", "/openmp:experimental", "/openmp:llvm", "VC.Project.VCCLCompilerTool.OpenMP"] helpviewer_keywords: ["/openmp compiler option [C++]", "/openmp:experimental compiler option [C++]", "/openmp:llvm compiler option [C++]", "-openmp compiler option [C++]"] --- @@ -31,11 +31,11 @@ Causes the compiler to process [`#pragma omp`](../../preprocessor/omp.md) direct ::: moniker range=">= msvc-160" -The C++ compiler currently supports the OpenMP 2.0 standard. However, Visual Studio 2019 also now offers SIMD functionality. To use SIMD, compile by using the **`/openmp:experimental`** option. This option enables both the usual OpenMP features, and OpenMP SIMD features not available when using the **`/openmp`** switch. +The C++ compiler currently supports the OpenMP 2.0 standard. Visual Studio 2019 also now offers SIMD functionality. To use SIMD, compile using the **`/openmp:experimental`** option. This option enables both the usual OpenMP features, and OpenMP SIMD features not available when using the **`/openmp`** switch. Starting in Visual Studio 2019 version 16.9, you can use the experimental **`/openmp:llvm`** option instead of **`/openmp`** to target the LLVM OpenMP runtime. Support currently isn't available for production code, since the required libomp DLLs aren't redistributable. The option supports the same OpenMP 2.0 directives as **`/openmp`**. And, it supports all the SIMD directives supported by the **`/openmp:experimental`** option. It also supports unsigned integer indices in parallel for loops according to the OpenMP 3.0 standard. For more information, see [Improved OpenMP Support for C++ in Visual Studio](https://devblogs.microsoft.com/cppblog/improved-openmp-support-for-cpp-in-visual-studio/). -Currently, the **`/openmp:llvm`** option only works on the x64 architecture. The option isn't compatible with **`/clr`** or **`/ZW`**. +The **`/openmp:llvm`** option supports the x64 architecture. Starting with Visual Studio 2019 version 16.10, it also supports the x86 and ARM64 architectures. This option isn't compatible with **`/clr`** or **`/ZW`**. ::: moniker-end diff --git a/docs/build/reference/opt-optimizations.md b/docs/build/reference/opt-optimizations.md index 0c2494f2bf..e02850e624 100644 --- a/docs/build/reference/opt-optimizations.md +++ b/docs/build/reference/opt-optimizations.md @@ -18,7 +18,7 @@ Controls the optimizations that LINK performs during a build. ## Arguments -**REF** | **NOREF** +**REF** \| **NOREF** **/OPT:REF** eliminates functions and data that are never referenced; **/OPT:NOREF** keeps functions and data that are never referenced. @@ -30,7 +30,7 @@ By default, **/OPT:REF** is enabled by the linker unless **/OPT:NOREF** or [/DEB If [/DEBUG](debug-generate-debug-info.md) is specified, the default for **/OPT** is **NOREF**, and all functions are preserved in the image. To override this default and optimize a debug build, specify **/OPT:REF**. This can reduce the size of your executable, and can be a useful optimization even in debug builds. We recommend that you also specify **/OPT:NOICF** to preserve identical functions in debug builds. This makes it easier to read stack traces and set breakpoints in functions that would otherwise be folded together. -**ICF**\[**=**_iterations_] | **NOICF** +**ICF**\[**=**_iterations_] \| **NOICF** Use **ICF**\[**=**_iterations_] to perform identical COMDAT folding. Redundant COMDATs can be removed from the linker output. The optional *iterations* parameter specifies the number of times to traverse the symbols for duplicates. The default number of iterations is 1. Additional iterations may locate more duplicates that are uncovered through folding in the previous iteration. @@ -41,7 +41,7 @@ In a debug build, you must explicitly specify **/OPT:ICF** to enable COMDAT fold > [!NOTE] > Because **/OPT:ICF** can cause the same address to be assigned to different functions or read-only data members (that is, **`const`** variables when compiled by using **/Gy**), it can break a program that depends on unique addresses for functions or read-only data members. For more information, see [/Gy (Enable Function-Level Linking)](gy-enable-function-level-linking.md). -**LBR** | **NOLBR** +**LBR** \| **NOLBR** The **/OPT:LBR** and **/OPT:NOLBR** options apply only to ARM binaries. Because certain ARM processor branch instructions have a limited range, if the linker detects a jump to an out-of-range address, it replaces the branch instruction's destination address with the address of a code "island" that contains a branch instruction that targets the actual destination. You can use **/OPT:LBR** to optimize the detection of long branch instructions and the placement of intermediate code islands to minimize overall code size. **/OPT:NOLBR** instructs the linker to generate code islands for long branch instructions as they are encountered, without optimization. diff --git a/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md b/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md index 7d66878bd7..9325d11012 100644 --- a/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md +++ b/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md @@ -1,14 +1,14 @@ --- title: "/Os, /Ot (Favor Small Code, Favor Fast Code)" description: "The MSVC compiler options /Os and /Ot specify whether to favor size or speed when optimizing code." -ms.date: 07/08/2020 +ms.date: 04/18/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.FavorSizeOrSpeed", "/os", "VC.Project.VCCLCompilerTool.FavorSizeOrSpeed"] helpviewer_keywords: ["favor fast code compiler option [C++]", "/Os compiler option [C++]", "Ot compiler option [C++]", "/Ot compiler option [C++]", "small machine code", "-Ot compiler option [C++]", "fast code", "favor small code compiler option [C++]", "Os compiler option [C++]", "-Os compiler option [C++]"] ms.assetid: 9a340806-fa15-4308-892c-355d83cac0f2 --- # `/Os`, `/Ot` (Favor Small Code, Favor Fast Code) -Minimizes or maximizes the size of EXEs and DLLs. +The **`/Os`** and **`/Ot`** compiler options specify whether to favor size (**`/Os`**) or speed (**`/Ot`**) when optimizing code. ## Syntax diff --git a/docs/build/reference/out-output-file-name.md b/docs/build/reference/out-output-file-name.md index f43bb724dc..f671586c63 100644 --- a/docs/build/reference/out-output-file-name.md +++ b/docs/build/reference/out-output-file-name.md @@ -1,29 +1,26 @@ --- description: "Learn more about: /OUT (Output File Name)" title: "/OUT (Output File Name)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.OutputFile", "/out"] helpviewer_keywords: ["output files, name linker option", "-OUT linker option", "OUT linker option", "/OUT C++ linker option", "linker [C++], output files"] -ms.assetid: 976210a4-e51f-4cfb-af5e-c16344455834 --- # /OUT (Output File Name) -``` -/OUT:filename -``` +> /OUT:filename ## Arguments -*filename*
-A user-specified name for the output file. It replaces the default name. +*`filename`*\ +A user-specified name for the output file. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /OUT option overrides the default name and location of the program that the linker creates. +The `/OUT` option overrides the default name and location of the program that the linker creates. -By default, the linker forms the file name using the base name of the first .obj file specified and the appropriate extension (.exe or .dll). +By default, the linker forms the file name using the base name of the first `.obj` file specified and the appropriate extension (`.exe` or `.dll`). -This option the default base name for a .mapfile or import library. For details, see [Generate Mapfile](map-generate-mapfile.md) (/MAP) and [/IMPLIB](implib-name-import-library.md). +This option the default base name for a `.mapfile` or import library. For details, see [Generate Mapfile](map-generate-mapfile.md) (`/MAP`) and [/IMPLIB](implib-name-import-library.md). ### To set this linker option in the Visual Studio development environment @@ -39,5 +36,5 @@ This option the default base name for a .mapfile or import library. For details, ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/pdb-use-program-database.md b/docs/build/reference/pdb-use-program-database.md index 3801076b0d..9d61dad7b1 100644 --- a/docs/build/reference/pdb-use-program-database.md +++ b/docs/build/reference/pdb-use-program-database.md @@ -1,38 +1,37 @@ --- -description: "Learn more about: /PDB (Use Program Database)" title: "/PDB (Use Program Database)" -ms.date: "11/04/2016" +description: "Learn more about: /PDB (Use Program Database)" +ms.date: 03/24/2025 f1_keywords: ["/pdb", "VC.Project.VCLinkerTool.ProgramDatabaseFile"] helpviewer_keywords: ["-PDB linker option", "/PDB linker option", "PDB linker option", "PDB files, creating", ".pdb files, creating"] -ms.assetid: d23db0ce-10cb-427a-bc60-d6b2a852723d --- # /PDB (Use Program Database) -``` -/PDB:filename -``` +Specify the name of the program database (PDB) file that the linker creates. + +## Syntax + +> /PDB:filename ## Arguments -*filename*
-A user-specified name for the program database (PDB) that the linker creates. It replaces the default name. +*`filename`*\ +A user-specified name for the program database (PDB) that the linker creates. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -By default, when [/DEBUG](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. +By default, when [`/DEBUG`](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. -Use /PDB:*filename* to specify the name of the PDB file. If /DEBUG is not specified, the /PDB option is ignored. +Use `/PDB:`*`filename`* to specify the name of the PDB file. If `/DEBUG` is not specified, the `/PDB` option is ignored. -A PDB file can be up to 2GB. +A PDB file can be up to 2GB in size. For more information, see [.pdb Files as Linker Input](dot-pdb-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Debug** property page. - 1. Modify the **Generate Program Database File** property. ### To set this linker option programmatically @@ -41,5 +40,5 @@ For more information, see [.pdb Files as Linker Input](dot-pdb-files-as-linker-i ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md b/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md index 654278e537..6c198f7815 100644 --- a/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md +++ b/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md @@ -1,29 +1,30 @@ --- description: "Learn more about: /PDBALTPATH (Use Alternate PDB Path)" title: "/PDBALTPATH (Use Alternate PDB Path)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["/pdbaltpath"] helpviewer_keywords: [".pdb files, path", "PDBALTPATH dumpbin option", "-PDBALTPATH dumpbin option", "/PDBALTPATH dumpbin option", "PDB files, path"] -ms.assetid: 72e200aa-e2c3-4ad8-b687-25528da1aaaf --- # /PDBALTPATH (Use Alternate PDB Path) -``` -/PDBALTPATH:pdb_file_name -``` +Provide an alternate location for the Program Database (`.pdb`) file in a compiled binary file. + +## Syntax + +> /PDBALTPATH:pdb_file_name ## Arguments -*pdb_file_name*
-The path and file name for the .pdb file. +*`pdb_file_name`*\ +The path and filename for the `.pdb` file. The path may exceed `MAX_PATH` (260 characters). The filename (not including the path) must not exceed `MAX_PATH`. ## Remarks -Use this option to provide an alternate location for the Program Database (.pdb) file in a compiled binary file. Normally, the linker records the location of the .pdb file in the binaries that it produces. You can use this option to provide a different path and file name for the .pdb file. The information provided with /PDBALTPATH does not change the location or name of the actual .pdb file; it changes the information that the linker writes in the binary file. This enables you to provide a path that is independent of the file structure of the build computer. Two common uses for this option are to provide a network path or a file that has no path information. +Use this option to provide an alternate location for the Program Database (`.pdb`) file in a compiled binary file. Normally, the linker records the location of the `.pdb` file in the binaries that it produces. You can use this option to provide a different path and file name for the `.pdb` file. The information provided with `/PDBALTPATH` does not change the location or name of the actual `.pdb` file; it changes the information that the linker writes in the binary file. This enables you to provide a path that is independent of the file structure of the build computer. Two common uses for this option are to provide a network path or a file that has no path information. -The value of *pdb_file_name* can be an arbitrary string, an environment variable, or **%_PDB%**. The linker will expand an environment variable, such as **%SystemRoot%**, to its value. The linker defines the environment variables **%_PDB%** and **%_EXT%**. **%_PDB%** expands to the file name of the actual .pdb file without any path information and **%_EXT%** is the extension of the generated executable. +The value of *`pdb_file_name`* can be an arbitrary string, an environment variable, or `%_PDB%`. The linker will expand an environment variable, such as `%SystemRoot%`, to its value. The linker defines the environment variables `%_PDB%` and `%_EXT%`. `%_PDB%` expands to the file name of the actual `.pdb` file without any path information and `%_EXT%` is the extension of the generated executable. ## See also -[DUMPBIN Options](dumpbin-options.md)
-[/PDBPATH](pdbpath.md) +[DUMPBIN Options](dumpbin-options.md)\ +[`/PDBPATH`](pdbpath.md) diff --git a/docs/build/reference/pdbpath.md b/docs/build/reference/pdbpath.md index f97ea47913..b88420f081 100644 --- a/docs/build/reference/pdbpath.md +++ b/docs/build/reference/pdbpath.md @@ -2,11 +2,10 @@ description: "Learn more about: /PDBPATH" title: "/PDBPATH" ms.date: "11/04/2016" -f1_keywords: ["/pdbpath"] +f1_keywords: ["/PDBPATH"] helpviewer_keywords: [".pdb files, path", "-PDBPATH dumpbin option", "/PDBPATH dumpbin option", "PDBPATH dumpbin option", "PDB files, path"] -ms.assetid: ccf67dcd-0b23-4250-ad47-06c48acbe82b --- -# /PDBPATH +# `/PDBPATH` ``` /PDBPATH[:VERBOSE] filename @@ -14,31 +13,27 @@ ms.assetid: ccf67dcd-0b23-4250-ad47-06c48acbe82b ### Parameters -*filename*
-The name of the .dll or .exe file for which you want to find the matching .pdb file. +*filename*\ +The name of the .dll or `.exe` file for which you want to find the matching `.pdb` file. -**:VERBOSE**
-(Optional) Reports all directories where an attempt was made to locate the .pdb file. +**`:VERBOSE`**\ +(Optional) Reports all directories where an attempt was made to locate the `.pdb` file. ## Remarks -/PDBPATH will search your computer along the same paths that the debugger would search for a .pdb file and will report which, if any, .pdb files correspond to the file specified in *filename*. +`/PDBPATH` searches your computer along the same paths that the debugger searches for a `.pdb` file and reports which, if any, `.pdb` files correspond to the file specified in *filename*. -When using the Visual Studio debugger, you may experience a problem due to the fact that the debugger is using a .pdb file for a different version of the file you are debugging. +When using the Visual Studio debugger, you may experience a problem because the debugger is using a `.pdb` file for a different version of the file you're debugging. -/PDBPATH will search for .pdb files along the following paths: +`/PDBPATH` will search for `.pdb` files along the following paths: - Check the location where the executable resides. - - Check the location of the PDB written into the executable. This is usually the location at the time the image was linked. - - Check along the search path configured in the Visual Studio IDE. - -- Check along the paths in the _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH environment variables. - +- Check along the paths in the `_NT_SYMBOL_PATH` and `_NT_ALT_SYMBOL_PATH` environment variables. - Check in the Windows directory. ## See also -[DUMPBIN Options](dumpbin-options.md)
-[/PDBALTPATH (Use Alternate PDB Path)](pdbaltpath-use-alternate-pdb-path.md) +[`DUMPBIN` Options](dumpbin-options.md)\ +[`/PDBALTPATH` (Use Alternate PDB Path)](pdbaltpath-use-alternate-pdb-path.md) diff --git a/docs/build/reference/permissive-standards-conformance.md b/docs/build/reference/permissive-standards-conformance.md index c4014dce33..3a182cb84d 100644 --- a/docs/build/reference/permissive-standards-conformance.md +++ b/docs/build/reference/permissive-standards-conformance.md @@ -1,12 +1,11 @@ --- title: "/permissive- (Standards conformance)" description: "Reference guide to the Microsoft C++ /permissive- (Standards conformance) compiler option." -ms.date: 10/28/2020 +ms.date: 10/12/2023 f1_keywords: ["/permissive", "VC.Project.VCCLCompilerTool.ConformanceMode"] helpviewer_keywords: ["/permissive compiler options [C++]", "-permissive compiler options [C++]", "Standards conformance compiler options", "permissive compiler options [C++]"] -ms.assetid: db1cc175-6e93-4a2e-9396-c3725d2d8f71 --- -# /permissive- (Standards conformance) +# `/permissive-` (Standards conformance) Specify standards conformance mode to the compiler. Use this option to help you identify and fix conformance issues in your code, to make it both more correct and more portable. @@ -23,7 +22,7 @@ You can use the **`/permissive-`** compiler option to specify standards-conformi The **`/permissive-`** option uses the conformance support in the current compiler version to determine which language constructs are non-conforming. The option doesn't determine if your code conforms to a specific version of the C++ standard. To enable all implemented compiler support for the latest draft standard, use the [`/std:c++latest`](std-specify-language-standard-version.md) option. To restrict the compiler support to the currently implemented C++20 standard, use the [`/std:c++20`](std-specify-language-standard-version.md) option. To restrict the compiler support to the currently implemented C++17 standard, use the [`/std:c++17`](std-specify-language-standard-version.md) option. To restrict the compiler support to more closely match the C++14 standard, use the [`/std:c++14`](std-specify-language-standard-version.md) option, which is the default. -The **`/permissive-`** option is implicitly set by the **`/std:c++latest`** option starting in Visual Studio 2019 version 16.8, and in version 16.11 by the **`/std:c++20`** option. **`/permissive-`** is required for C++20 Modules support. Perhaps your code doesn't need modules support but requires other features enabled under **`/std:c++20`** or **`/std:c++latest`**. You can explicitly enable Microsoft extension support by using the **`/permissive`** option without the trailing dash. +The **`/permissive-`** option is implicitly set by the **`/std:c++latest`** option starting in Visual Studio 2019 version 16.8, and in version 16.11 by the **`/std:c++20`** option. **`/permissive-`** is required for C++20 Modules support. Perhaps your code doesn't need modules support but requires other features enabled under **`/std:c++20`** or **`/std:c++latest`**. You can explicitly enable Microsoft extension support by using the **`/permissive`** option without the trailing dash. The **`/permissive`** option must come after any option that sets **`/permissive-`** implicitly. By default, the **`/permissive-`** option is set in new projects created by Visual Studio 2017 version 15.5 and later versions. It's not set by default in earlier versions. When the option is set, the compiler generates diagnostic errors or warnings when non-standard language constructs are detected in your code. These constructs include some common bugs in pre-C++11 code. @@ -33,15 +32,17 @@ The **`/permissive-`** option sets the [`/Zc:referenceBinding`](zc-referencebind In versions of the compiler beginning in Visual Studio 2017 version 15.3, the **`/permissive-`** option sets the [`/Zc:ternary`](zc-ternary.md) option. The compiler also implements more of the requirements for two-phase name look-up. When the **`/permissive-`** option is set, the compiler parses function and class template definitions, and identifies dependent and non-dependent names used in the templates. In this release, only name dependency analysis is performed. -Environment-specific extensions and language areas that the standard leaves up to the implementation are not affected by **`/permissive-`**. For example, the Microsoft-specific **`__declspec`**, calling convention and structured exception handling keywords, and compiler-specific pragma directives or attributes are not flagged by the compiler in **`/permissive-`** mode. +As of Visual Studio 2022 Update 17.6, the **`/permissive-`** option sets the [`/Zc:lambda`](zc-lambda.md) and [`/Zc:externConstexpr`](zc-externconstexpr.md) options. In prior versions, **`/permissive-`** didn't set either one. -Not all C++11, C++14, or C++17 standards-conforming code is supported by the MSVC compiler in all versions of Visual Studio 2017. Depending on the version of Visual Studio, the **`/permissive-`** option may not detect issues in some aspects of two-phase name lookup, binding a non-const reference to a temporary, treating copy init as direct init, allowing multiple user-defined conversions in initialization, or alternative tokens for logical operators, and other non-supported conformance areas. For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). To get the most out of **`/permissive-`**, update Visual Studio to the latest version. +Environment-specific extensions and language areas that the standard leaves up to the implementation aren't affected by **`/permissive-`**. For example, the Microsoft-specific **`__declspec`**, calling convention and structured exception handling keywords, and compiler-specific `pragma` directives or attributes aren't flagged by the compiler in **`/permissive-`** mode. + +The MSVC compiler in earlier versions of Visual Studio 2017 doesn't support all C++11, C++14, or C++17 standards-conforming code. Depending on the version of Visual Studio, the **`/permissive-`** option may not detect issues in some aspects of two-phase name lookup, binding a non-const reference to a temporary, treating copy init as direct init, allowing multiple user-defined conversions in initialization, or alternative tokens for logical operators, and other non-supported conformance areas. For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). To get the most out of **`/permissive-`**, update Visual Studio to the latest version. ### How to fix your code Here are some examples of code that is detected as non-conforming when you use **`/permissive-`**, along with suggested ways to fix the issues. -#### Use default as an identifier in native code +#### Use `default` as an identifier in native code ```cpp void func(int default); // Error C2321: 'default' is a keyword, and @@ -52,27 +53,45 @@ void func(int default); // Error C2321: 'default' is a keyword, and ```cpp template -struct B { - void f(); +struct B +{ + void f() {} + template + struct S { void operator()(){ return; } }; }; template struct D : public B // B is a dependent base because its type // depends on the type of T. { - // One possible fix is to uncomment the following line. - // If this is a type, don't forget the 'typename' keyword. + // One possible fix for non-template members and function + // template members is a using statement: // using B::f; + // If it's a type, don't forget the 'typename' keyword. - void g() { + void g() + { f(); // error C3861: 'f': identifier not found - // Another fix is to change it to 'this->f();' + // Another fix is to change the call to 'this->f();' + } + + void h() + { + S s; // C2065 or C3878 + // Since template S is dependent, the type must be qualified + // with the `typename` keyword. + // To fix, replace the declaration of s with: + // typename B::template S s; + // Or, use this: + // typename D::template S s; + s(); } }; void h() { D d; d.g(); + d.h(); } ``` @@ -103,6 +122,8 @@ union U #### Hidden friend name lookup rules +A declaration outside a class can make a hidden friend visible: + ```cpp // Example 1 struct S { @@ -115,6 +136,8 @@ using type = void (*)(S *); type p = &f; // error C2065: 'f': undeclared identifier. ``` +Use of literal `nullptr` can prevent argument dependent lookup: + ```cpp // Example 2 struct S { @@ -158,7 +181,9 @@ void func() { } ``` -#### Use of ATL Attributes +#### Use of ATL attributes + +Microsoft-specific ATL attributes can cause issues under **`/permissive-`**: ```cpp // Example 1 @@ -166,11 +191,15 @@ void func() { class A {}; ``` +You can fix the issue by using the **`__declspec`** form instead: + ```cpp // Fix for example 1 class __declspec(uuid("594382D9-44B0-461A-8DE3-E06A3E73C5EB")) B {}; ``` +A more complex example: + ```cpp // Example 2 [emitidl]; @@ -187,6 +216,8 @@ class CFoo : public ICustom {}; ``` +Resolution requires extra build steps. In this case, create an IDL file: + ```cpp // Fix for example 2 // First, create the *.idl file. The vc140.idl generated file can be @@ -241,7 +272,7 @@ Common errors that may result from this change include: - `error C2446: ':': no conversion from 'B' to 'A'` -A typical code pattern that can cause this issue is when some class C provides both a non-explicit constructor from another type T and a non-explicit conversion operator to type T. In this case, both the conversion of the second argument to the type of the third argument, and the conversion of the third argument to the type of the second argument, are valid conversions. Since both are valid, it's ambiguous according to the standard. +A typical code pattern that can cause this issue is when some class `C` provides both a non-explicit constructor from another type `T` and a non-explicit conversion operator to type `T`. The conversion of the second argument to the third argument's type is a valid conversion. So is the conversion of the third argument to the second argument's type. Since both are valid, it's ambiguous according to the standard. ```cpp // Example 1: class that provides conversion to and initialization from some type T @@ -282,7 +313,7 @@ auto x = cond ? "A" : s; auto y = cond ? "A" : static_cast(s); ``` -Another case where you may see errors is in conditional operators with one argument of type **`void`**. This case may be common in ASSERT-like macros. +You may also see errors in conditional operators with one argument of type **`void`**. This case may be common in ASSERT-like macros. ```cpp // Example 3: void arguments @@ -343,7 +374,7 @@ Certain header files in the Windows April 2018 Update SDK (10.0.17134.0), the Wi These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.17134.0) aren't clean with **`/permissive-`**. To work around these issues, either don't use **`/permissive-`**, or use **`/permissive-`** with **`/Zc:twoPhase-`** when you work with these headers: -- Issues in winrt/wrl/async.h +- Issues in *`winrt/wrl/async.h`* ```Output C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\winrt\wrl\async.h(483): error C3861: 'TraceDelegateAssigned': identifier not found @@ -352,7 +383,7 @@ These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.1713 C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\winrt\wrl\async.h(513): error C3861: 'TraceProgressNotificationComplete': identifier not found ``` -- Issue in winrt/wrl/implements.h +- Issue in *`winrt/wrl/implements.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\winrt\wrl\implements.h(2086): error C2039: 'SetStrongReference': is not a member of 'Microsoft::WRL::Details::WeakReferenceImpl' @@ -360,7 +391,7 @@ These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.1713 These User Mode headers released in the Windows April 2018 Update SDK (10.0.17134.0) aren't clean with **`/permissive-`**. To work around these issues, don't use **`/permissive-`** when working with these headers: -- Issues in um/Tune.h +- Issues in *`um/Tune.h`* ```Output C:\ProgramFiles(x86)\Windows Kits\10\include\10.0.17134.0\um\tune.h(139): error C3861: 'Release': identifier not found @@ -369,13 +400,13 @@ These User Mode headers released in the Windows April 2018 Update SDK (10.0.1713 C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\tune.h(1240): note: 'Release': function declaration must be available as none of the arguments depend on a template parameter ``` -- Issue in um/spddkhlp.h +- Issue in *`um/spddkhlp.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\spddkhlp.h(759): error C3861: 'pNode': identifier not found ``` -- Issues in um/refptrco.h +- Issues in *`um/refptrco.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\refptrco.h(179): error C2760: syntax error: unexpected token 'identifier', expected 'type specifier' @@ -385,9 +416,9 @@ These User Mode headers released in the Windows April 2018 Update SDK (10.0.1713 These issues are specific to User Mode headers in the Windows Fall Creators Update SDK (10.0.16299.0): -- Issue in um/Query.h +- Issue in *`um/Query.h`* - When using the **`/permissive-`** compiler switch, the `tagRESTRICTION` structure doesn't compile because of the case(RTOr) member 'or'. + When you use the **`/permissive-`** compiler switch, the `tagRESTRICTION` structure doesn't compile because of the `case(RTOr)` member `or`. ```cpp struct tagRESTRICTION @@ -409,21 +440,21 @@ These issues are specific to User Mode headers in the Windows Fall Creators Upda }; ``` - To address this issue, compile files that include Query.h without the **`/permissive-`** option. + To address this issue, compile files that include *`Query.h`* without the **`/permissive-`** option. -- Issue in um/cellularapi_oem.h +- Issue in *`um/cellularapi_oem.h`* - When using the **`/permissive-`** compiler switch, the forward declaration of `enum UICCDATASTOREACCESSMODE` causes a warning: + When you use the **`/permissive-`** compiler switch, the forward declaration of `enum UICCDATASTOREACCESSMODE` causes a warning: ```cpp typedef enum UICCDATASTOREACCESSMODE UICCDATASTOREACCESSMODE; // C4471 ``` - The forward declaration of unscoped enum is a Microsoft extension. To address this issue, compile files that include cellularapi_oem.h without the **`/permissive-`** option, or use the [`/wd`](compiler-option-warning-level.md) option to silence warning C4471. + The forward declaration of an unscoped `enum` is a Microsoft extension. To address this issue, compile files that include *`cellularapi_oem.h`* without the **`/permissive-`** option, or use the [`/wd`](compiler-option-warning-level.md) option to silence warning C4471. -- Issue in um/omscript.h +- Issue in *`um/omscript.h`* - In C++03, a conversion from a string literal to BSTR (which is a typedef to 'wchar_t *') is deprecated but allowed. In C++11, the conversion is no longer allowed. + In C++03, a conversion from a string literal to `BSTR` (which is a typedef to `wchar_t *`) is deprecated but allowed. In C++11, the conversion is no longer allowed. ```cpp virtual /* [id] */ HRESULT STDMETHODCALLTYPE setExpression( diff --git a/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md b/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md index 219bd6b023..77539e99b0 100644 --- a/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md +++ b/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md @@ -1,14 +1,13 @@ --- description: "Learn more about: /PGD (Specify Database for Profile-Guided Optimizations)" title: "/PGD (Specify Database for Profile-Guided Optimizations)" -ms.date: "03/14/2018" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.ProfileGuidedDatabase"] helpviewer_keywords: ["-PGD linker option", "/PGD linker option"] -ms.assetid: 9f312498-493b-461f-886f-92652257e443 --- # /PGD (Specify Database for Profile-Guided Optimizations) -**The /PGD option is deprecated.** Starting in Visual Studio 2015, prefer the [/GENPROFILE or /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) linker options instead. This option is used to specify the name of the .pgd file used by the profile-guided optimization process. +**The /PGD option is deprecated.** Starting in Visual Studio 2015, prefer the [`/GENPROFILE`or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) linker options instead. This option is used to specify the name of the .pgd file used by the profile-guided optimization process. ## Syntax @@ -16,14 +15,14 @@ ms.assetid: 9f312498-493b-461f-886f-92652257e443 ## Argument -*filename*
-Specifies the name of the .pgd file that is used to hold information about the running program. +`filename`\ +Specifies the name of the `.pgd` file that is used to hold information about the running program. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -When using the deprecated [/LTCG:PGINSTRUMENT](ltcg-link-time-code-generation.md) option, use **/PGD** to specify a nondefault name or location for the .pgd file. If you do not specify **/PGD**, the .pgd file base name is the same as the output file (.exe or .dll) base name and is created in the same directory from which the link was invoked. +When using the deprecated [`/LTCG:PGINSTRUMENT`](ltcg-link-time-code-generation.md) option, use **`/PGD`** to specify a nondefault name or location for the `.pgd` file. If you don't specify **`/PGD`**, the `.pgd` file base name is the same as the output file (`.exe` or `.dll`) base name and is created in the same directory from which the link was invoked. -When using the deprecated **/LTCG:PGOPTIMIZE** option, use the **/PGD** option to specify the name of the .pgd file to use to create the optimized image. The *filename* argument should match the *filename* specified to **/LTCG:PGINSTRUMENT**. +When using the deprecated **`/LTCG:PGOPTIMIZE`** option, use the **`/PGD`** option to specify the name of the `.pgd` file to use to create the optimized image. The *`filename`* argument should match the *`filename`* specified to **`/LTCG:PGINSTRUMENT`**. For more information, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). @@ -41,5 +40,5 @@ For more information, see [Profile-Guided Optimizations](../profile-guided-optim ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md index 7259b4b09e..4cff2b6e29 100644 --- a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md +++ b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md @@ -1,26 +1,24 @@ --- -description: "Learn more about: /Qfast_transcendentals (Force Fast Transcendentals)" -title: "/Qfast_transcendentals (Force Fast Transcendentals)" -ms.date: "11/04/2016" +description: "Learn more about: /Qfast_transcendentals (Force fast transcendentals)" +title: "/Qfast_transcendentals (Force fast transcendentals)" +ms.date: 03/02/2022 f1_keywords: ["/Qfast_transcendentals"] helpviewer_keywords: ["/Qfast_transcendentals", "Force Fast Transcendentals"] ms.assetid: 4de24bd1-38e6-49d4-9a05-04c9937d24ac --- -# /Qfast_transcendentals (Force Fast Transcendentals) +# `/Qfast_transcendentals` (Force fast transcendentals) Generates inline code for transcendental functions. ## Syntax -``` -/Qfast_transcendentals -``` +> **`/Qfast_transcendentals`** ## Remarks -This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **/fp:except** or **/fp:precise**. Generating inline code for transcendental functions is already the default behavior under **/fp:fast**. +This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **`/fp:except`** or **`/fp:precise`**. Generating inline code for transcendental functions is already the default behavior under **`/fp:fast`**. -This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md) for more information about floating point compiler options. +This option is incompatible with **`/fp:strict`**. For more information about floating point compiler options, see [`/fp` (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -36,6 +34,6 @@ This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Poin ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Q` Options (Low-level operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qpar-auto-parallelizer.md b/docs/build/reference/qpar-auto-parallelizer.md index c50be3c3e1..37cedc2517 100644 --- a/docs/build/reference/qpar-auto-parallelizer.md +++ b/docs/build/reference/qpar-auto-parallelizer.md @@ -1,45 +1,43 @@ --- -description: "Learn more about: /Qpar (Auto-Parallelizer)" -title: "/Qpar (Auto-Parallelizer)" -ms.date: "11/04/2016" +description: "Learn more about: /Qpar (Auto-parallelizer)" +title: "/Qpar (Auto-parallelizer)" +ms.date: 02/22/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.EnableParallelCodeGeneration"] ms.assetid: 33ecf49d-c0d5-4f34-bce3-84ff03f38918 --- -# /Qpar (Auto-Parallelizer) +# `/Qpar` (Auto-parallelizer) -Enables the [Auto-Parallelizer](../../parallel/auto-parallelization-and-auto-vectorization.md) feature of the compiler to automatically parallelize loops in your code. +Enables the [Auto-parallelizer](../../parallel/auto-parallelization-and-auto-vectorization.md) feature of the compiler to automatically parallelize loops in your code. ## Syntax -``` -/Qpar -``` +> **`/Qpar`** ## Remarks -When the compiler automatically parallelizes loops in code, it spreads computation across multiple processor cores. A loop is parallelized only if the compiler determines that it is legal to do so and that parallelization would improve performance. +When the compiler automatically parallelizes loops in code, it spreads computation across multiple processor cores. The compiler parallelizes a loop only if it determines that it's legal to do so and that parallelization would improve performance. -The `#pragma loop()` directives are available to help the optimizer parallelize specific loops. For more information, see [loop](../../preprocessor/loop.md). +The `#pragma loop()` directives are available to help the optimizer parallelize specific loops. For more information, see [`loop`](../../preprocessor/loop.md). -For information about how to enable output messages for the auto-parallelizer, see [/Qpar-report (Auto-Parallelizer Reporting Level)](qpar-report-auto-parallelizer-reporting-level.md). +For information about how to enable output messages for the auto-parallelizer, see [`/Qpar-report` (Auto-parallelizer reporting level)](qpar-report-auto-parallelizer-reporting-level.md). -### To set the /Qpar compiler option in Visual Studio +### To set the `/Qpar` compiler option in Visual Studio 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. -1. In the **Additional Options** box, enter *`/Qpar`*. +1. Modify the **Enable Parallel Code Generation** property. Choose **OK** or **Apply** to save your changes. -### To set the /Qpar compiler option programmatically +### To set the `/Qpar` compiler option programmatically - Use the code example in . ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[/Qpar-report (Auto-Parallelizer Reporting Level)](qpar-report-auto-parallelizer-reporting-level.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[#pragma loop()](../../preprocessor/loop.md)
+[`/Q` options (Low-level operations)](q-options-low-level-operations.md)\ +[`/Qpar-report` (Auto-parallelizer reporting level)](qpar-report-auto-parallelizer-reporting-level.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`#pragma loop()`](../../preprocessor/loop.md)\ [Native code vectorization in Visual Studio](/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) diff --git a/docs/build/reference/qspectre-jmp.md b/docs/build/reference/qspectre-jmp.md new file mode 100644 index 0000000000..b04d970480 --- /dev/null +++ b/docs/build/reference/qspectre-jmp.md @@ -0,0 +1,38 @@ +--- +title: "/Qspectre-jmp" +description: "Describes the Microsoft C/C++ compiler (MSVC) /Qspectre-jmp option." +ms.date: 11/30/2023 +helpviewer_keywords: ["/Qspectre-jmp"] +--- +# `/Qspectre-jmp` + +Causes the compiler to generate an `int3` instruction (software interrupt) after unconditional direct branches. This option extends the [`/Qspectre`](qspectre.md) flag and mitigates speculative execution side-channel attacks on unconditional direct branches. + +## Syntax + +> **/Qspectre-jmp** + +## Remarks + +**`/Qspectre-jmp`** causes the compiler to detect executable instructions following unconditional direct branches. An `int3` is inserted following unconditional direct branches to ensure that no instructions are speculatively executed beyond the branch. For example, the compiler mitigates `jmp addr` by adding an `int3` instruction following the `jmp` instruction as shown here: + +```asm +jmp addr +int3 +``` + +`/Qspectre-jmp` is off by default. It's supported for all optimization levels. + +### Set this compiler option programmatically + +To set this option programmatically, see [VCCLCompilerTool.AdditionalOptions property](/dotnet/api/microsoft.visualstudio.vcprojectengine.vcclcompilertool.additionaloptions). + +## See also + +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ +[/Q options (Low-Level Operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre-load-cf.md b/docs/build/reference/qspectre-load-cf.md index 063058a264..0d0640ab81 100644 --- a/docs/build/reference/qspectre-load-cf.md +++ b/docs/build/reference/qspectre-load-cf.md @@ -15,7 +15,7 @@ Specifies compiler generation of serializing instructions for every control-flow ## Remarks -**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here: +**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here: ```asm xor rbx, [rax] @@ -44,6 +44,9 @@ The **/Qspectre-load-cf** option is available in Visual Studio 2019 version 16.5 ## See also +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ [/Q options (Low-level operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre-load.md b/docs/build/reference/qspectre-load.md index 6d37e74ffd..728c2cad9b 100644 --- a/docs/build/reference/qspectre-load.md +++ b/docs/build/reference/qspectre-load.md @@ -14,7 +14,7 @@ Specifies compiler generation of serializing instructions for every load instruc ## Remarks -**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here: +**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here: ```asm xor rbx, [rax] @@ -43,6 +43,9 @@ The **/Qspectre-load** option is available in Visual Studio 2019 version 16.5 an ## See also +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ [/Q options (Low-Level Operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre.md b/docs/build/reference/qspectre.md index c8d209b16c..2eace5222a 100644 --- a/docs/build/reference/qspectre.md +++ b/docs/build/reference/qspectre.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: /Qspectre" title: "/Qspectre" +description: "Learn more about: /Qspectre" ms.date: 07/02/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.SpectreMitigation"] helpviewer_keywords: ["/Qspectre"] --- -# /Qspectre +# `/Qspectre` Specifies compiler generation of instructions to mitigate certain Spectre variant 1 security vulnerabilities. @@ -23,7 +23,7 @@ The **`/Qspectre`** option is off by default. In its initial release, the **`/Qspectre`** option only worked on optimized code. Starting in Visual Studio 2017 version 15.7, the **`/Qspectre`** option is supported at all optimization levels. -Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable haven't been modified. +Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable are unmodified. You can also install Spectre-mitigated libraries for MFC and ATL. They're found in the **Individual Components** tab under **SDKs, libraries, and frameworks**. @@ -38,7 +38,7 @@ If your code operates on data that crosses a trust boundary, then we recommend y The **`/Qspectre`** option is available starting in Visual Studio 2017 version 15.5.5, and in all updates to Microsoft C/C++ compilers (MSVC) made on or after January 23, 2018. Use the Visual Studio Installer to update the compiler, and to install the Spectre-mitigated libraries as individual components. The **`/Qspectre`** option is also available in Visual Studio 2015 Update 3 through a patch. For more information, see [KB 4338871](https://support.microsoft.com/help/4338871). -All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **/`d2guardspecload`**. It's equivalent to the initial behavior of **`/Qspectre`**. You can use **`/d2guardspecload`** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **`/Qspectre`** in compilers that support the option. The **`/Qspectre`** option may also support new mitigations in later versions of the compiler. +All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **`/d2guardspecload`**. It's equivalent to the initial behavior of **`/Qspectre`**. You can use **`/d2guardspecload`** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **`/Qspectre`** in compilers that support the option. The **`/Qspectre`** option may also support new mitigations in later versions of the compiler. ### Effect @@ -72,7 +72,7 @@ The default MSBuild-based project system in the Visual Studio IDE lets you speci ::: moniker range="msvc-150" -The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found". If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. +The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found." If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. ::: moniker-end @@ -134,6 +134,9 @@ For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, se ## See also +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ [`/Q` options (Low-level operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/resources-property-pages.md b/docs/build/reference/resources-property-pages.md index 0f09208f2b..cea6e5ba33 100644 --- a/docs/build/reference/resources-property-pages.md +++ b/docs/build/reference/resources-property-pages.md @@ -14,7 +14,6 @@ f1_keywords: - VC.Project.VCResourceCompilerTool.SuppressStartupBanner - VC.Project.VCResourceCompilerTool.ResourceOutputFileName - VC.Project.VCResourceCompilerTool.NullTerminateStrings - - vc.project.AdditionalOptionsPage --- # Resources property page diff --git a/docs/build/reference/running-lib.md b/docs/build/reference/running-lib.md index f469017355..0bfac11edc 100644 --- a/docs/build/reference/running-lib.md +++ b/docs/build/reference/running-lib.md @@ -32,7 +32,7 @@ An option consists of an option specifier, which is either a dash (**-**) or a f The following options apply to all modes of LIB: -> **/ERRORREPORT** \[**NONE** | **PROMPT** | **QUEUE** | **SEND**] +> **/ERRORREPORT** \[**NONE** \| **PROMPT** \| **QUEUE** \| **SEND**] The /ERRORREPORT option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. diff --git a/docs/build/reference/running-nmake.md b/docs/build/reference/running-nmake.md index a2b87e9920..e9633b59a9 100644 --- a/docs/build/reference/running-nmake.md +++ b/docs/build/reference/running-nmake.md @@ -12,6 +12,8 @@ helpviewer_keywords: ["targets, building", "response files, NMAKE", "targets", " ## Remarks +NMAKE must run in a Developer Command Prompt window. A Developer Command Prompt window has the environment variables set for the tools, libraries, and include file paths required to build at the command line. For details on how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](../building-on-the-command-line.md). + NMAKE builds only specified *targets* or, when none is specified, the first target in the makefile. The first makefile target can be a [pseudotarget](description-blocks.md#pseudotargets) that builds other targets. NMAKE uses makefiles specified with **`/F`**, or if **`/F`** isn't specified, the Makefile file in the current directory. If no makefile is specified, it uses inference rules to build command-line *targets*. The *command-file* text file (or response file) contains command-line input. Other input can precede or follow \@*command-file*. A path is permitted. In *command-file*, line breaks are treated as spaces. Enclose macro definitions in quotation marks if they contain spaces. @@ -27,7 +29,7 @@ NMAKE options are described in the following table. Options are preceded by eith | **`/C`** | Suppresses default output, including nonfatal NMAKE errors or warnings, timestamps, and NMAKE copyright message. Suppresses warnings issued by **`/K`**. | | **`/D`** | Displays timestamps of each evaluated target and dependent and a message when a target doesn't exist. Useful with **`/P`** for debugging a makefile. Use `!CMDSWITCHES` to set or clear **`/D`** for part of a makefile. | | **`/E`** | Causes environment variables to override makefile macro definitions. | -| **`/ERRORREPORT`** [ **`NONE`** | **`PROMPT`** | **`QUEUE`** | **`SEND`** ] | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control reporting. | +| **`/ERRORREPORT`** [ **`NONE`** \| **`PROMPT`** \| **`QUEUE`** \| **`SEND`** ] | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control reporting. | | **`/F`** *filename* | Specifies *filename* as a makefile. Spaces or tabs can precede *filename*. Specify **`/F`** once for each makefile. To supply a makefile from standard input, specify a dash (`-`) for *filename*, and end keyboard input with either **F6** or **CTRL+Z**. | | **`/G`** | Displays the makefiles included with the `!INCLUDE` directive. For more information, see [Makefile preprocessing directives](makefile-preprocessing.md#makefile-preprocessing-directives). | | **`/HELP`**, **`/?`** | Displays a brief summary of NMAKE command-line syntax. | diff --git a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md index 23f40109f4..40de4d33be 100644 --- a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md +++ b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md @@ -1,34 +1,37 @@ --- description: "Learn more about: /SAFESEH (Image has Safe Exception Handlers)" title: "/SAFESEH (Image has Safe Exception Handlers)" -ms.date: "11/04/2016" -f1_keywords: ["/SAFESEH"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ImageHasSafeExceptionHandlers", "/SAFESEH"] helpviewer_keywords: ["/SAFESEH linker option", "-SAFESEH linker option", "SAFESEH linker option"] ms.assetid: 7722ff99-b833-4c65-a855-aaca902ffcb7 --- -# /SAFESEH (Image has Safe Exception Handlers) +# `/SAFESEH` (Image has Safe Exception Handlers) -``` -/SAFESEH[:NO] -``` +When **`/SAFESEH`** is specified, the linker only produces an image if it can also produce a table of the image's safe exception handlers. This table specifies to the operating system which exception handlers are valid for the image. -When **/SAFESEH** is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +## Syntax -**/SAFESEH** is only valid when linking for x86 targets. **/SAFESEH** is not supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. See [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md) for more information. +> **`/SAFESEH`**\ +> **`/SAFESEH:NO`** -If **/SAFESEH** is not specified, the linker will produce an image with a table of safe exceptions handlers if all modules are compatible with the safe exception handling feature. If any modules were not compatible with safe exception handling feature, the resulting image will not contain a table of safe exception handlers. If [/SUBSYSTEM](subsystem-specify-subsystem.md) specifies WINDOWSCE or one of the EFI_* options, the linker will not attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. +## Remarks -If **/SAFESEH:NO** is specified, the linker will not produce an image with a table of safe exceptions handlers even if all modules are compatible with the safe exception handling feature. +**`/SAFESEH`** is only valid when linking for x86 targets. **`/SAFESEH`** isn't supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. For more information, see [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md). -The most common reason for the linker not to be able to produce an image is because one or more of the input files (modules) to the linker was not compatible with the safe exception handlers feature. A common reason for a module to not be compatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. +If **`/SAFESEH`** isn't specified, the linker will produce an image with a table of safe exceptions handlers if all code segments are compatible with the safe exception handling feature. If any code segments weren't compatible with the safe exception handling feature, the resulting image won't contain a table of safe exception handlers. If [`/SUBSYSTEM`](subsystem-specify-subsystem.md) specifies `WINDOWSCE` or one of the `EFI_*` options, the linker won't attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. -You can also register a function as a structured exception handler by using [.SAFESEH](../../assembler/masm/dot-safeseh.md). +If **`/SAFESEH:NO`** is specified, the linker won't produce an image with a table of safe exceptions handlers even if all code segments are compatible with the safe exception handling feature. -It is not possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. +The most common reason the linker can't produce an image is because one or more of the input files to the linker was incompatible with the safe exception handlers feature. A common reason why code is incompatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. -The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in loadcfg.c CRT source file) that contains all the entries defined for Visual C++. For example: +You can also register a function as a structured exception handler by using [`.SAFESEH`](../../assembler/masm/dot-safeseh.md). -``` +It isn't possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. + +The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in the *`loadcfg.c`* CRT source file) that contains all the entries defined for Visual C++. For example: + +```C #include extern DWORD_PTR __security_cookie; /* /GS security cookie */ @@ -89,13 +92,11 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - -1. Select the **Linker** folder. +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Image Has Safe Exception Handlers** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -103,5 +104,5 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/sarif-output.md b/docs/build/reference/sarif-output.md new file mode 100644 index 0000000000..29e608baa8 --- /dev/null +++ b/docs/build/reference/sarif-output.md @@ -0,0 +1,151 @@ +--- +description: "How to make the compiler output diagnostics as structured SARIF" +title: "Structured SARIF Diagnostics" +ms.date: "10/26/2023" +author: tartanllama +ms.author: sybrand +manager: mluparu +helpviewer_keywords: ["SARIF", "structured diagnostics"] +--- + +# Structured SARIF Diagnostics + +The MSVC compiler can be made to output diagnostics as [SARIF](https://sarifweb.azurewebsites.net/) (Static Analysis Results Interchange Format). SARIF is a machine-readable JSON-based format. + +There are two ways to make the MSVC compiler produce SARIF diagnostics: + +- Pass the `/experimental:log` switch on the command line. See the [documentation for `/experimental:log`](experimental-log.md) for details. +- Launch `cl.exe` programmatically and set the `SARIF_OUTPUT_PIPE` environment variable to retrieve SARIF blocks through a pipe. + +## Retrieving SARIF through a pipe + +Tools that consume SARIF from the MSVC compiler while a compilation is in progress use a pipe. See the documentation for [`CreatePipe`](/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe) for details about creating Windows pipes. + +To retrieve SARIF through a pipe, set the `SARIF_OUTPUT_PIPE` environment variable to be the UTF-16-encoded integer representation of the `HANDLE` to the write end of the pipe, then launch `cl.exe`. SARIF is sent along the pipe as follows: + +- When a new diagnostic is available, it is written to this pipe. +- Diagnostics are written to the pipe one-at-a-time rather than as an entire SARIF object. +- Each diagnostic is represented by a [JSON-RPC 2.0](https://www.jsonrpc.org/) message of type [Notification](https://www.jsonrpc.org/specification#notification:~:text=as%20binary%20fractions.-,4.1%20Notification,-A%20Notification%20is). +- The JSON-RPC message is prefixed with a `Content-Length` header with the form `Content-Length: ` followed by two newlines, where `` is the length of the following JSON-RPC message in bytes. +- The JSON-RPC message and header are both encoded in UTF-8. +- This JSON-RPC-with-header format is compatible with [vs-streamjsonrpc](https://github.com/microsoft/vs-streamjsonrpc). +- The method name for the JSON-RPC call is `OnSarifResult`. +- The call has a single parameter that is encoded [by-name](https://www.jsonrpc.org/specification#parameter_structures) with the parameter name `result`. +- The value of the argument is a single `result` object as specified by the [SARIF Version 2.1 standard](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790888). + +### Example + +Here's an example of a JSON-RPC SARIF result produced by `cl.exe`: + +```json +Content-Length: 334 + +{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}}{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}} +``` + +## SARIF result data + +The compiler outputs SARIF that may include additional information to represent the nested structure of some diagnostics. A diagnostic (represented by a `result` SARIF object) may contain a "diagnostic tree" of additional information in its `relatedLocations` field. This tree is encoded using a SARIF [property bag](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790698) as follows: + +A `location` object's `properties` field may contain a `nestingLevel` property whose value is the depth of this location in the diagnostic tree. If a location doesn't have a `nestingLevel` specified, the depth is considered to be `0` and this location is a child of the root diagnostic represented by the `result` object containing it. Otherwise, if the value is greater than the depth of the location immediately preceding this location in the `relatedLocations` field, this location is a child of that location. Otherwise, this location is a sibling of the closest preceding `location` in the `relatedLocations` field with the same depth. + +### Example + +Consider the following code: + +```cpp +struct dog {}; +struct cat {}; + +void pet(dog); +void pet(cat); + +struct lizard {}; + +int main() { + pet(lizard{}); +} +``` + +When this code is compiled, the compiler produces the following `result` object (`physicalLocation` properties have been removed for brevity): + +```json +{ + "ruleId": "C2665", + "level": "error", + "message": { + "text": "'pet': no overloaded function could convert all the argument types" + }, + "relatedLocations": [ + { + "id": 0, + "message": { + "text": "could be 'void pet(cat)'" + } + }, + { + "id": 1, + "message": { + "text": "'void pet(cat)': cannot convert argument 1 from 'lizard' to 'cat'" + }, + "properties": { + "nestingLevel": 1 + } + }, + { + "id": 2, + "message": { + "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called" + }, + "properties": { + "nestingLevel": 2 + } + }, + { + "id": 3, + "message": { + "text": "or 'void pet(dog)'" + } + }, + { + "id": 4, + "message": { + "text": "'void pet(dog)': cannot convert argument 1 from 'lizard' to 'dog'" + }, + "properties": { + "nestingLevel": 1 + } + }, + { + "id": 5, + "message": { + "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called" + }, + "properties": { + "nestingLevel": 2 + } + }, + { + "id": 6, + "message": { + "text": "while trying to match the argument list '(lizard)'" + } + } + ] +} +``` + +The logical diagnostics tree produced from the messages in this `result` object is: + +- 'pet': no overloaded function could convert all the argument types + - could be 'void pet(cat)' + - 'void pet(cat)': cannot convert argument 1 from 'lizard' to 'cat + - No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called + - or 'void pet(dog)' + - 'void pet(dog)': cannot convert argument 1 from 'lizard' to 'dog' + - No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called + - while trying to match the argument list '(lizard)' + +## See also + +[`/experimental:log` (Enable structured SARIF diagnostics)](experimental-log.md) \ No newline at end of file diff --git a/docs/build/reference/scandependencies.md b/docs/build/reference/scandependencies.md new file mode 100644 index 0000000000..d7a6f2f99c --- /dev/null +++ b/docs/build/reference/scandependencies.md @@ -0,0 +1,141 @@ +--- +title: "/scanDependencies (List module and header unit dependencies per Standard)" +description: "Reference guide to the /scanDependencies compiler option in Microsoft C++." +ms.date: 09/21/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/scanDependencies"] +helpviewer_keywords: ["/scanDependencies compiler option", "/scanDependencies"] +--- +# `/scanDependencies` (List module dependencies in standard form) + +This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R5 Format for describing dependencies of source files`](https://wg21.link/P1689r5). + +## Syntax + +> **`/scanDependencies-`**\ +> **`/scanDependencies`** *`filename`*\ +> **`/scanDependencies`** *`directory`* + +## Arguments + +*`-`*\ +If the single dash is provided, then the compiler emits the source dependencies JSON to `stdout`, or to where compiler output is redirected. + +*`filename`*\ +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. + +*`directory`*\ +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.module.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.module.json`*. + +## Remarks + +The **`/scanDependencies`** compiler option identifies which dependencies, modules, and header units must be compiled before you can compile the project that uses them. For instance, it lists `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake. To report module and header unit dependencies, you must also compile by using [`/std:c++20`](std-specify-language-standard-version.md) or later. + +This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: + +- The output uses the [`P1689R5`](https://wg21.link/P1689r5) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**. +- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. +- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list. +- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. +- Textually included header files such as `#include ` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option. +- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built. + +**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2. It's not enabled by default. + +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results. + +When a non-fatal compiler error occurs, the dependency information still gets written to the output file. + +All file paths appear as absolute paths in the output. + +For details on the format and schema used in the output JSON file, see [`P1689R5`](https://wg21.link/P1689r5#_format) section 6. + +### Examples + +Consider the following sample code: + +```cpp +//app.cpp: +#include + +import other.module; +import std; +import "t.h"; +import ; + +int main() {} +``` + +You can use this command line to report dependencies in *`app.cpp`*: + +> `cl /std:c++latest /scanDependencies output.json app.cpp` + +The compiler produces a JSON file, *`output.json`*, with content similar to: + +```JSON +{ + "version": 1, + "revision": 0, + "rules": [ + { + "primary-output": "app.obj", + "outputs": [ + "output.json" + ], + "requires": [ + { + "logical-name": "other.module" + }, + { + "logical-name": "std" + }, + { + "logical-name": "t.h", + "source-path": "C:\\Users\\username\\source\\repos\\app\\app\\t.h", + "lookup-method": "include-quote", + "unique-on-source-path": true + }, + { + "logical-name": "iostream", + "source-path": "C:\\Program Files\\...\\include\\iostream", + "lookup-method": "include-angle", + "unique-on-source-path": true + } + ] + } + ] +} +``` + +We've used `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. + +No *`.ifc`* files are listed in the output because they weren't built. Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output when **`/scanDependencies`** is specified, so no compiled modules or header units are produced to import. + +## To set this compiler option in Visual Studio + +You normally shouldn't set the **`/scanDependencies`** option in the Visual Studio development environment. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error. + +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to add *`/scanDependencies-`* or *`/scanDependencies "pathname"`*, where *`"pathname"`* refers to a directory for output. + +1. Choose **OK** to save your changes. + +To report module and header unit dependencies, you must also set the **Configuration Properties** > **General** > **C++ Language Standard** property to **ISO C++20 Standard** or later. + +### To set this compiler option programmatically + +- See . + +## See also + +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/sourceDependencies:directives`](sourcedependencies-directives.md)\ +[`/sourceDependencies`](sourcedependencies.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md)\ +[`/translateInclude`](translateinclude.md) diff --git a/docs/build/reference/section-specify-section-attributes.md b/docs/build/reference/section-specify-section-attributes.md index 50cd06a531..c994dd4799 100644 --- a/docs/build/reference/section-specify-section-attributes.md +++ b/docs/build/reference/section-specify-section-attributes.md @@ -1,79 +1,79 @@ --- description: "Learn more about: /SECTION (Specify Section Attributes)" title: "/SECTION (Specify Section Attributes)" -ms.date: "12/29/2017" -f1_keywords: ["/section"] +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.SpecifySectionAttributes", "/section"] helpviewer_keywords: ["SECTION linker option", "-SECTION linker option", "section attributes", "/SECTION linker option"] --- -# /SECTION (Specify Section Attributes) +# `/SECTION` (Specify Section Attributes) -> **/SECTION:**_name_,[[**!**]{**DEKPRSW**}][**,ALIGN=**_number_] +> **`/SECTION:`***`name`***`,`**\[\[**`!`**]{**`D`**\|**`E`**\|**`K`**\|**`P`**\|**`R`**\|**`S`**\|**`W`**}]\[**`,ALIGN=`***`number`*] ## Remarks -The **/SECTION** option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The **`/SECTION`** option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. -A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly, while other data sections are created for you by the linker and library manager (lib.exe) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). +A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly. Other data sections are created for you by the linker and library manager (LIB) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). -Specify a colon (:) and a section *name*. The *name* is case sensitive. +Specify a colon (**`:`**) and a section name *`name`*. The *`name`* is case sensitive. -Do not use the following names, as they conflict with standard names. For example, .sdata is used on RISC platforms: +Don't use the following names, as they conflict with standard names. For example, `.sdata` is used on RISC platforms: -- .arch +- `.arch` -- .bss +- `.bss` -- .data +- `.data` -- .edata +- `.edata` -- .idata +- `.idata` -- .pdata +- `.pdata` -- .rdata +- `.rdata` -- .reloc +- `.reloc` -- .rsrc +- `.rsrc` -- .sbss +- `.sbss` -- .sdata +- `.sdata` -- .srdata +- `.srdata` -- .text +- `.text` -- .xdata +- `.xdata` -Specify one or more attributes for the section. The attribute characters, listed below, are not case sensitive. You must specify all attributes that you want the section to have; an omitted attribute character causes that attribute bit to be turned off. If you do not specify R, W, or E, the existing read, write, or executable status remains unchanged. +Specify one or more attributes for the section. The attribute characters, listed below, aren't case sensitive. You must specify all attributes that you want the section to have. An omitted attribute character causes that attribute bit to be turned off. If you don't specify `R`, `W`, or `E`, the existing read, write, or executable status remains unchanged. -To negate an attribute, precede its character with an exclamation point (!). The meanings of the attribute characters are shown in this table: +To negate an attribute, precede its character with an exclamation point (`!`). The meanings of the attribute characters are shown in this table: -|Character|Attribute|Meaning| -|---------------|---------------|-------------| -|E|Execute|The section is executable| -|R|Read|Allows read operations on data| -|W|Write|Allows write operations on data| -|S|Shared|Shares the section among all processes that load the image| -|D|Discardable|Marks the section as discardable| -|K|Cacheable|Marks the section as not cacheable| -|P|Pageable|Marks the section as not pageable| +| Character | Attribute | Meaning | +|--|--|--| +| `E` | Execute | The section is executable | +| `R` | Read | Allows read operations on data | +| `W` | Write | Allows write operations on data | +| `S` | Shared | Shares the section among all processes that load the image | +| `D` | Discardable | Marks the section as discardable | +| `K` | Cacheable | Marks the section as not cacheable | +| `P` | Pageable | Marks the section as not pageable | -K and P are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the .text section by using the **/SECTION:.text,K** option, there is no difference in the section flags when you run [DUMPBIN](dumpbin-options.md) with the [/HEADERS](headers.md) option; the section was already implicitly cached. To remove the default, specify **/SECTION:.text,!K** instead. DUMPBIN reveals section characteristics, including "Not Cached." +`K` and `P` are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the `.text` section by using the **`/SECTION:.text,K`** option, there's no difference in the section flags when you run [`DUMPBIN`](dumpbin-options.md) with the [`/HEADERS`](headers.md) option; the section was already implicitly cached. To remove the default, specify **`/SECTION:.text,!K`** instead. DUMPBIN reveals section characteristics, including "Not Cached." -A section in the PE file that does not have E, R, or W set is probably invalid. +A section in the PE file that doesn't have `E`, `R`, or `W` set is probably invalid. -The **ALIGN=**_number_ argument lets you specify an alignment value for a particular section. The _number_ argument is in bytes and must be a power of two. See [/ALIGN](align-section-alignment.md) for more information. +The **`ALIGN=`***`number`* argument lets you specify an alignment value for a particular section. The *`number`* argument is in bytes and must be a power of two. For more information, see [`/ALIGN`](align-section-alignment.md). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Specify Section Attributes** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -81,5 +81,5 @@ The **ALIGN=**_number_ argument lets you specify an alignment value for a partic ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/showincludes-list-include-files.md b/docs/build/reference/showincludes-list-include-files.md index 86a35f799f..ced65322f7 100644 --- a/docs/build/reference/showincludes-list-include-files.md +++ b/docs/build/reference/showincludes-list-include-files.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /showIncludes (List include files)" title: "/showIncludes (List include files)" -ms.date: 04/15/2021 +ms.date: 05/24/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.ShowIncludes", "VC.Project.VCCLCompilerTool.ShowIncludes", "/showincludes"] helpviewer_keywords: ["include files", "/showIncludes compiler option [C++]", "include files, displaying in compilation", "-showIncludes compiler option [C++]", "showIncludes compiler option [C++]"] --- @@ -30,8 +30,6 @@ Note: including file: d:\temp\2.h In this case, *`2.h`* was included from within *`1.h`*, causing the indentation. -The **`/showIncludes`** option emits to `stderr`, not `stdout`. - ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/source-charset-set-source-character-set.md b/docs/build/reference/source-charset-set-source-character-set.md index 0a0597a1c0..ed047dda01 100644 --- a/docs/build/reference/source-charset-set-source-character-set.md +++ b/docs/build/reference/source-charset-set-source-character-set.md @@ -1,53 +1,51 @@ --- -description: "Learn more about: /source-charset (Set Source Character Set)" -title: "/source-charset (Set Source Character Set)" -ms.date: "02/06/2019" +description: "Learn more about: /source-charset (Set source character set)" +title: "/source-charset (Set source character set)" +ms.date: 01/31/2022 f1_keywords: ["source-charset", "/source-charset"] helpviewer_keywords: ["/execution-charset compiler option"] ms.assetid: d3c5bf7f-526d-4ee4-acc5-c1a02a4fc481 --- -# /source-charset (Set Source Character Set) +# `/source-charset` (Set source character set) -Lets you specify the source character set for your executable. +This option lets you specify the source character set for your executable. ## Syntax -``` -/source-charset:[IANA_name|.CPID] -``` +> **`/source-charset:`**[*`IANA_name`* | *`.CPID`*] ## Arguments -**IANA_name**
+*`IANA_name`*\ The IANA-defined character set name. -**CPID**
-The code page identifier as a decimal number. +*`.CPID`*\ +The code page identifier as a decimal number, preceded by a `.` character. ## Remarks -You can use the **/source-charset** option to specify an extended source character set to use when your source files include characters that are not represented in the basic source character set. The source character set is the encoding used to interpret the source text of your program into the internal representation used as input to the preprocessing phases before compilation. The internal representation is then converted to the execution character set to store string and character values in the executable. You can use either the IANA or ISO character set name, or a dot (.) followed by a 3 to 5 digit decimal code page identifier to specify the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +You can use the **`/source-charset`** option to specify an extended source character set to use when your source files include characters that are not represented in the basic source character set. The source character set is the encoding used to interpret the source text of your program. It's converted into the internal representation used as input to the preprocessing phases before compilation. The internal representation is then converted to the execution character set to store string and character values in the executable. You can use either the IANA or ISO character set name, or a dot (`.`) followed by 3-5 decimal digits that specify the code page identifier of the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you specify a character set name or code page by using the **/source-charset** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For more information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you use the **`/source-charset`** or **`/utf-8`** option to specify a character set name or code page. Visual Studio allows you to save your C++ source code in any of several character encodings. For more information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. -The source character set you supply must map the 7-bit ASCII characters to the same code points in your character set, or many compilation errors are likely to follow. Your source character set must also be mappable to the extended Unicode character set encodable by UTF-8. Characters that are not encodable in UTF-8 are represented by an implementation-specific substitute. The Microsoft compiler uses a question mark for these characters. +The source character set you supply must map the 7-bit ASCII characters to the same code points in your character set, or many compilation errors are likely to follow. Your source character set must also have a mapping to the extended Unicode character set of UTF-8. Characters that have no equivalent in UTF-8 are represented by an implementation-specific substitute. The Microsoft compiler uses a question mark for these characters. -If you want to set both the source character set and the execution character set to UTF-8, you can use the **/utf-8** compiler option as a shortcut. It is equivalent to specifying **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **/validate-charset** option by default. +If you want to set both the source character set and the execution character set to UTF-8, you can use the **`/utf-8`** compiler option as a shortcut. It's equivalent to **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. ### To set this compiler option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for your project. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In **Additional Options**, add the *`/source-charset`* option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/source-charset`** option, and specify your preferred encoding. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/sourcedependencies-directives.md b/docs/build/reference/sourcedependencies-directives.md index 23877f7a16..25cfd5f192 100644 --- a/docs/build/reference/sourcedependencies-directives.md +++ b/docs/build/reference/sourcedependencies-directives.md @@ -1,7 +1,7 @@ --- title: "/sourceDependencies:directives (List module and header unit dependencies)" description: "Reference guide to the /sourceDependencies:directives compiler option in Microsoft C++." -ms.date: 04/13/2020 +ms.date: 05/19/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/sourceDependencies:directives"] @@ -9,45 +9,47 @@ helpviewer_keywords: ["/sourceDependencies:directives compiler option", "/source --- # `/sourceDependencies:directives` (List module and header unit dependencies) -This command-line option generates a JSON file that lists module and header-unit dependencies. +This command-line option scans source files and their `#include` statements to generate a JSON file that lists module export and imports. A build system can use this information to determine the build order of modules and header units. -It identifies which modules and header units need to be compiled before the project that uses them is compiled. For instance, it will list `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. +This option differs from [`/sourceDependencies`](sourcedependencies.md) in the following ways: -This command-line option is similar to [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: - -- The compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. +- The compiler doesn't produce compiled output. No compiled code, modules, or header units are produced. Instead, the files are scanned for module directives. +- The JSON format is different from what `/sourceDependencies` produces. The `/sourceDependencies` option is intended to be used with other build tools, such as CMake. - The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option does a scan of the project files, not a compilation. So there are no built modules or header units to list. - Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. -- Header file dependencies are not listed. That is, `#include ` or `#include "file"` dependencies are not listed. +- Header file dependencies aren't listed. That is, `#include ` or `#include "file"` dependencies aren't listed. - `/sourceDependencies:directives` is meant to be used before *`.ifc`* files are built. +- `/sourceDependencies` causes the compiler to report all of the files, such as `#includes`, `.pch` files, `.ifc` files, and so on, that were used for a particular translation unit, whereas `/sourceDependencies:directives [file1]` scans the specified source file and reports all `import` and `export` statements. `/sourceDependencies` can be used with `/sourceDependencies:directives`. ## Syntax -> **`/sourceDependencies:directives`** -\ +> **`/sourceDependencies:directives-`**\ > **`/sourceDependencies:directives`** *filename*\ -> **`/sourceDependencies:directives`** *directory*\ +> **`/sourceDependencies:directives`** *directory* ## Arguments *`-`*\ -If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected to. +If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected. *`filename`*\ -The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. *`directory`*\ -If the argument is a directory, the compiler generates source dependency files in the specified directory. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. ## Remarks -**`/sourceDependencies:directives`** is available starting in Visual Studio 2019 version 16.10. It's not enabled by default. +**`/sourceDependencies:directives`** is available starting in Visual Studio 2019 version 16.10. -When you specify the **`/MP`** compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. For more information on **`/MP`**, see [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md). +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/sourceDependencies:directives`** with a directory argument. This option makes the compiler output a separate *`*.module.json`* file for each source file. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/sourceDependencies:directives-`** to send output to `stdout` could cause interleaved results. When a non-fatal compiler error occurs, the dependency information still gets written to the output file. All file paths appear as absolute paths in the output. +This switch can be used with [`/translateInclude`](translateinclude.md). + ### Examples Given the following sample code: @@ -57,48 +59,54 @@ Given the following sample code: #include import m; -import std.core; - +import std; import ; - import "t.h"; int main() {} ``` -> `cl /std:c++latest /sourceDependencies:directives output.json main.cpp` +This following command line: + +`cl /std:c++latest /translateInclude /sourceDependencies:directives output.json main.cpp` -This command line produces a JSON file *`output.json`* with content like: +produces a JSON file *`output.json`* similar to: ```JSON { "Version":"1.1", "Data":{ - "Source":"C:\\a\\b\\main.cpp", + "Source":"C:\\test\\main.cpp", "ProvidedModule":"", "ImportedModules":[ "m", - "std.core" + "std" ], "ImportedHeaderUnits":[ "C:\\...\\utility", - "C:\\a\\b\\t.h" + "C:\\...\\vector", + "C:\\test\\t.h" ] } } ``` -We've used `...` to abbreviate the reported paths. The report will contain the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. +For brevity, the previous example uses `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you might want to check your project's include path settings. `ProvidedModule` lists exported module or module partition names. -No *`.ifc`* files are listed in the output because they weren't built. Unlike `/sourceDependencies`, the compiler doesn't produce compiled output when `/sourceDependencies:directives` is specified, so no compiled modules or header units are produced to import. +No *`.ifc`* files are listed in the output because they weren't built. Unlike `/sourceDependencies`, the compiler doesn't produce compiled output when `/sourceDependencies:directives` is specified, so no compiled modules or header units are produced. ## To set this compiler option in Visual Studio -You normally shouldn't set this yourself in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option yourself in the Visual Studio development environment. The build system sets it. ## See also +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ +[`/translateInclude`](translateinclude.md)\ +[C++ header-units.json reference](header-unit-json-reference.md)\ [MSVC compiler options](compiler-options.md)\ -[MSVC compiler command-line syntax](compiler-command-line-syntax.md) +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/scanDependencies` (List module dependencies in standard form)](scandependencies.md)\ +[`/sourceDependencies` (List all source-level dependencies)](sourcedependencies.md) diff --git a/docs/build/reference/sourcedependencies.md b/docs/build/reference/sourcedependencies.md index d5405349d6..e789466f8b 100644 --- a/docs/build/reference/sourcedependencies.md +++ b/docs/build/reference/sourcedependencies.md @@ -1,7 +1,7 @@ --- title: "/sourceDependencies (Report source-level dependencies)" description: "Describes the /sourceDependencies compiler option in Microsoft C++." -ms.date: 04/13/2020 +ms.date: 02/23/2024 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/sourceDependencies"] @@ -14,32 +14,32 @@ This command-line switch generates a JSON file that details the source-level dep - Header files. Both directly included and the list of headers included by those headers. - The PCH used (if **`/Yu`** is specified). - Names of imported modules -- File paths and names of imported header units. Both directly imported and those imported by those modules and headers units. +- File paths and names of both directly imported header units and of the modules and header units they import in turn. -This provides information necessary to build modules and header units in the proper dependency order. +This option provides information necessary to build modules and header units in the proper dependency order. ## Syntax -> **`/sourceDependencies`** -\ +> **`/sourceDependencies-`**\ > **`/sourceDependencies`** *filename*\ > **`/sourceDependencies`** *directory* ## Arguments *`-`*\ -If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected to. +If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected. *`filename`*\ -The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. *`directory`*\ -If the argument is a directory, the compiler generates source dependency files in the specified directory. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. ## Remarks The **`/sourceDependencies`** compiler option is available starting in Visual Studio 2019 version 16.7. It's not enabled by default. -When you specify the **`/MP`** compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. For more information on **`/MP`**, see [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md). +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/sourceDependencies-`** to send output to `stdout` could cause interleaved results. When a non-fatal compiler error occurs, the dependency information still gets written to the output file. @@ -61,11 +61,11 @@ You can use **`/sourceDependencies`** with the rest of your compiler options: > `cl ... /sourceDependencies output.json ... main.cpp` -where `...` represents your other compiler options. This command line produces a JSON file *`output.json`* with content like: +where `...` represents your other compiler options. This command line produces a JSON file *`output.json`* with content like: ```JSON { - "Version": "1.1", + "Version": "1.2", "Data": { "Source": "F:\\Sample\\myproject\\modulee.ixx", "ProvidedModule": "ModuleE", @@ -88,25 +88,23 @@ where `...` represents your other compiler options. This command line produces a { "Header": "f:\\visual studio 16 main\\vc\\tools\\msvc\\14.29.30030\\include\\iostream", "BMI": "F:\\Sample\\Outputs\\Intermediate\\HeaderUnits\\x64\\Debug\\iostream_W4L4JYGFJ3GL8OG9.ifc" - }, - { - "Header": "f:\\visual studio 16 main\\vc\\tools\\msvc\\14.29.30030\\include\\yvals_core.h", - "BMI": "F:\\Sample\\Outputs\\Intermediate\\HeaderUnits\\x64\\Debug\\yvals_core.h.ifc" } ] } } ``` -We've used `...` to abbreviate the reported paths. The report will contain the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. +We've used `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. `ProvidedModule` lists exported module or module partition names. ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this yourself in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option yourself in the Visual Studio development environment. It's set by the build system. ## See also -[MSVC compiler options](compiler-options.md)
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/scanDependencies`](scandependencies.md)\ +[`/sourceDependencies:directives`](sourcedependencies-directives.md) diff --git a/docs/build/reference/sourcelink.md b/docs/build/reference/sourcelink.md index 1e9b7002ed..2240b03d4b 100644 --- a/docs/build/reference/sourcelink.md +++ b/docs/build/reference/sourcelink.md @@ -16,11 +16,11 @@ Specifies a Source Link configuration file to include in the PDB file generated ## Arguments *filename*
-Specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md#source-link-json-schema). +Specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-json-schema). ## Remarks -Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native C++ binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). +Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native C++ binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). ### To set the /SOURCELINK linker option in Visual Studio @@ -36,5 +36,5 @@ Source Link is a language- and source-control agnostic system for providing sour ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/special-nmake-macros.md b/docs/build/reference/special-nmake-macros.md index 9e5b5c6439..93dcf23449 100644 --- a/docs/build/reference/special-nmake-macros.md +++ b/docs/build/reference/special-nmake-macros.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Special NMAKE macros" title: "Special NMAKE macros" +description: "Learn more about: Special NMAKE macros" ms.date: 09/30/2021 helpviewer_keywords: ["special NMAKE macros", "macros, NMAKE", "NMAKE macros, special", "NMAKE program, environment variable macros", "environment variables, macros in NMAKE", "macros, environment-variable", "options macros", "command macros in NMAKE", "macros, options macros", "macros, command macros", "NMAKE program, recursion macros", "recursion macros", "macros, recursion", "filename macros in NMAKE", "NMAKE program, filename macros"] no-loc: [AS, AFLAGS, CC, CFLAGS, CPP, CPPFLAGS, CXX, CXXFLAGS, RC, RFLAGS, ias, ml, ml64, cl, rc] @@ -9,7 +9,7 @@ no-loc: [AS, AFLAGS, CC, CFLAGS, CPP, CPPFLAGS, CXX, CXXFLAGS, RC, RFLAGS, ias, NMAKE provides several special macros to represent various filenames and commands. One use for some of these macros is in the predefined inference rules. Like all macros, the macros provided by NMAKE are case sensitive. -## Filename Macros +## Filename Macros Filename macros are predefined as filenames specified in the dependency (not full filename specifications on disk). These macros don't need to be enclosed in parentheses when invoked; specify only a **`$`** as shown. @@ -17,7 +17,7 @@ Filename macros are predefined as filenames specified in the dependency (not ful |--|--| | **`$@`** | Current target's full name (path, base name, extension), as currently specified. | | **`$$@`** | Current target's full name (path, base name, extension), as currently specified. Valid only as a dependent in a dependency. | -| **`$*`*** | Current target's path and base name minus file extension. | +| **`$*`** | Current target's path and base name minus file extension. | | **`$**`** | All dependents of the current target. | | **`$?`** | All dependents with a later timestamp than the current target. | | **`$<`** | Dependent file with a later timestamp than the current target. Valid only in commands in inference rules. | @@ -31,7 +31,7 @@ To specify part of a predefined filename macro, append a macro modifier and encl | **`F`** | Base name plus extension | | **`R`** | Drive plus directory plus base name | -## Recursion macros +## Recursion macros Use recursion macros to call NMAKE recursively. Recursive sessions inherit command-line and environment-variable macros and *`Tools.ini`* information. They don't inherit makefile-defined inference rules or `.SUFFIXES` and `.PRECIOUS` specifications. There are three ways to pass macros to a recursive NMAKE session: @@ -45,7 +45,7 @@ Use recursion macros to call NMAKE recursively. Recursive sessions inherit comma | **`MAKEDIR`** | Current directory when NMAKE was invoked. | | **`MAKEFLAGS`** | Options currently in effect. Use as `/$(MAKEFLAGS)`. The **`/F`** option isn't included. | -## Command macros and options macros +## Command macros and options macros Command macros are predefined for Microsoft products. Options macros represent options to these products and are undefined by default. Both are used in predefined inference rules and can be used in description blocks or user-defined inference rules. Command macros can be redefined to represent part or all of a command line, including options. Options macros generate a null string if left undefined. @@ -57,7 +57,7 @@ Command macros are predefined for Microsoft products. Options macros represent o | C++ Compiler | **`CXX`** | `cl` | **`CXXFLAGS`** | | Resource Compiler | **`RC`** | `rc` | **`RFLAGS`** | -## Environment-variable macros +## Environment-variable macros NMAKE inherits macro definitions for environment variables that exist before the start of the session. If a variable was set in the operating-system environment, it is available as an NMAKE macro. The inherited names are converted to uppercase. Inheritance occurs before preprocessing. Use the /E option to cause macros inherited from environment variables to override any macros with the same name in the makefile. diff --git a/docs/build/reference/stack-stack-allocations.md b/docs/build/reference/stack-stack-allocations.md index 995fbeeefd..5bd9529826 100644 --- a/docs/build/reference/stack-stack-allocations.md +++ b/docs/build/reference/stack-stack-allocations.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: /STACK (Stack Allocations)" -title: "/STACK (Stack Allocations)" -ms.date: "11/04/2016" +description: "Learn more about: /STACK (Stack allocations)" +title: "/STACK (Stack allocations)" +ms.date: 02/22/2022 f1_keywords: ["VC.Project.VCLinkerTool.StackReserveSize", "VC.Project.VCLinkerTool.StackCommitSize", "/stack"] helpviewer_keywords: ["STACK linker option", "-STACK linker option", "memory allocation, stack", "/STACK linker option", "stack, setting size"] ms.assetid: 73283660-e4bd-47cc-b5ca-04c5d739034c --- -# /STACK (Stack Allocations) +# `/STACK` (Stack allocations) -``` -/STACK:reserve[,commit] -``` +> **`/STACK:`***`reserve`*[**`,`***`commit`*] ## Remarks -The /STACK option sets the size of the stack in bytes. Use this option only when you build an .exe file. +The **`/STACK`** linker option sets the size of the stack in bytes. Use this option only when you build an *`.exe`* file. The **`/STACK`** option is ignored when applied to *`.dll`* files. -The `reserve` value specifies the total stack allocation in virtual memory. For ARM, x86 and x64 machines, the default stack size is 1 MB. +The *`reserve`* value specifies the total stack allocation in virtual memory. For ARM64, x86, and x64 machines, the default stack size is 1 MB. -`commit` is subject to interpretation by the operating system. In Windows WindowsRT it specifies the amount of physical memory to allocate at a time. Committed virtual memory causes space to be reserved in the paging file. A higher `commit` value saves time when the application needs more stack space, but increases the memory requirements and possibly the startup time. For ARM, x86 and x64 machines, the default commit value is 4 KB. +The *`commit`* value is subject to interpretation by the operating system. In WindowsRT, it specifies the amount of physical memory to allocate at a time. Committed virtual memory causes space to be reserved in the paging file. A higher *`commit`* value saves time when the application needs more stack space, but increases the memory requirements and possibly the startup time. For ARM64, x86, and x64 machines, the default *`commit`* value is 4 KB. -Specify the `reserve` and `commit` values in decimal or C-language notation. +Specify the *`reserve`* and *`commit`* values in decimal or C-language hexadecimal notation (use a `0x` prefix). -Another way to set the size of the stack is with the [STACKSIZE](stacksize.md) statement in a module-definition (.def) file. **STACKSIZE** overrides the Stack Allocations (/STACK) option if both are specified. You can change the stack size after the .exe file is built by using the [EDITBIN](editbin-reference.md) tool. +Another way to set the size of the stack is with the [`STACKSIZE`](stacksize.md) statement in a module-definition (*`.def`*) file. **`STACKSIZE`** overrides the Stack Allocations (**`/STACK`**) option if both are specified. You can change the stack size after the *`.exe`* file is built by using the [`EDITBIN`](editbin-reference.md) tool. ### To set this linker option in the Visual Studio development environment @@ -42,5 +40,5 @@ Another way to set the size of the stack is with the [STACKSIZE](stacksize.md) s ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/std-specify-language-standard-version.md b/docs/build/reference/std-specify-language-standard-version.md index 9aac61f438..c9eeb3f544 100644 --- a/docs/build/reference/std-specify-language-standard-version.md +++ b/docs/build/reference/std-specify-language-standard-version.md @@ -1,8 +1,8 @@ --- title: "/std (Specify Language Standard Version)" description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler." -ms.date: 10/22/2021 -f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c11", "/std:c17", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] +ms.date: 1/29/2025 +f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c++20", "/std:c++23preview", "/std:c++latest", "/std:c11", "/std:c17", "/std:clatest", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] --- # `/std` (Specify Language Standard Version) @@ -13,24 +13,32 @@ Enable supported C and C++ language features from the specified version of the C > **`/std:c++14`**\ > **`/std:c++17`**\ > **`/std:c++20`**\ +> **`/std:c++23preview`**\ > **`/std:c++latest`**\ > **`/std:c11`**\ -> **`/std:c17`** +> **`/std:c17`**\ +> **`/std:clatest`** ## Remarks The **`/std`** options are available in Visual Studio 2017 and later. They're used to control the version-specific ISO C or C++ programming language standard features enabled during compilation of your code. The options allow you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard. -### C++ standards support +The Microsoft C++ compiler in Visual Studio 2017 and later versions doesn't support C++ standards modes earlier than C++14 (**`/std:c++14`**). Such support isn't planned. As an imperfect workaround, it's possible to use older Visual C++ compiler toolsets that didn't implement features from later standards. For more information on how to install and use older compiler toolsets in Visual Studio, see [Use native multi-targeting in Visual Studio to build old projects](../../porting/use-native-multi-targeting.md). -The **`/std`** option in effect during a C++ compilation can be detected by use of the [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). +## C++ standards support -**`/std:c++14`**\ -The **`/std:c++14`** option enables C++14 standard-specific features implemented by the MSVC compiler. This option is the default for code compiled as C++. It's available starting in Visual Studio 2015 Update 3. +Detect whether the **`/std`** option is in effect during a C++ compilation with the [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). + +> [!IMPORTANT] +> Because some existing code depends on the value of the macro `__cplusplus` being `199711L`, the MSVC compiler doesn't change the value of this macro unless you explicitly opt in by setting [`/Zc:__cplusplus`](zc-cplusplus.md). Specify `/Zc:__cplusplus` and the **`/std`** option to set `__cplusplus` to the appropriate value. + +### `/std:c++14` + +Enables C++14 standard-specific features implemented by the MSVC compiler. This option is the default for code compiled as C++. It's available starting in Visual Studio 2015 Update 3. This option disables compiler and standard library support for features that are changed or new in more recent versions of the language standard. However, it doesn't disable some C++17 features already implemented in previous releases of the MSVC compiler. For more information, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). The tables indicate which C++17 features are enabled when you specify **`/std:c++14`**. -The following features remain enabled when the **`/std:c++14`** option is specified to avoid breaking changes for users who have already taken dependencies on the features available in or before Visual Studio 2015 Update 2: +The following features remain enabled when the **`/std:c++14`** option is specified to avoid breaking changes for users who took dependencies on features available in or before Visual Studio 2015 Update 2: - [Rules for `auto` with braced-init-lists](https://wg21.link/n3922) - [`typename` in template template-parameters](https://wg21.link/n4051) @@ -38,39 +46,52 @@ The following features remain enabled when the **`/std:c++14`** option is specif - [Attributes for namespaces and enumerators](https://wg21.link/n4266) - [u8 character literals](https://wg21.link/n4267) -**`/std:c++17`**\ -The **`/std:c++17`** option enables C++17 standard-specific features and behavior. It enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. It specifically disables post-C++17 changes in the C++ Standard and versions of the Working Draft. It does not disable retroactive defect updates of the C++ Standard. This option is available starting in Visual Studio 2017 version 15.3. +### `/std:c++17` + +Enables C++17 standard-specific features and behavior. It enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. It specifically disables post-C++17 changes in the C++ Standard and versions of the Working Draft. It doesn't disable retroactive defect updates of the C++ Standard. This option is available starting in Visual Studio 2017 version 15.3. Depending on the MSVC compiler version or update level, C++17 features may not be fully implemented or fully conforming when you specify the **`/std:c++17`** option. For an overview of C++ language conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). -**`/std:c++20`**\ -The **`/std:c++20`** option enables C++20 standard-specific features and behavior. Available starting in Visual Studio 2019 version 16.11, it enables the full set of C++20 features implemented by the MSVC compiler, with the exception of `std::format`, the C++20 `` formatting extensions, and the range factories and range adaptors from ``. These features are still only available under **`/std:c++latest`**. +### `/std:c++20` + +Enables C++20 standard-specific features and behavior. + +Enables the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. -The **`/std:c++20`** option disables compiler and standard library support for features that are new or changed after C++20. It specifically disables post-C++20 changes in the C++ Standard and versions of the Working Draft. It doesn't disable retroactive defect updates of the C++ Standard. +### `/std:c++23preview` -**`/std:c++latest`**\ -The **`/std:c++latest`** option enables all currently implemented compiler and standard library features proposed for the next draft standard, as well as some in-progress and experimental features. This option is available starting in Visual Studio 2015 Update 3. +Enables preview C++23 standard-specific features and behavior. Available starting in Visual Studio 2022 version 17.13 Preview 4. Preview features may change and may not be ABI compatible across releases. -Depending on the MSVC compiler version or update level, C++17, C++20, or proposed C++23 features may not be fully implemented or fully conforming when you specify the **`/std:c++latest`** option. We recommend you use the latest version of Visual Studio for maximum standards conformance. For an overview of C++ language and library conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). +This switch will be removed when the `/std:c++23` switch is implemented--at which point C++23 features will be fully implemented and ABI stable. If in project properties **C/C++** > **Language** you specify **Preview - ISO C++ 23 Standard (/std:c++preview)**, it will automatically change to mean `/std:c++23` once the new switch is implemented. -In versions of Visual Studio 2019 before version 16.11, **`/std:c++latest`** is required to enable all the compiler and standard library features of C++20. +This switch differs from `/std:c++latest` in that it only enables features that are part of the C++23 standard. It doesn't enable experimental or in-progress features. + +### `/std:c++latest` + +Enables all currently implemented compiler and standard library features proposed in the next ISO C++ working draft, as well as some in-progress and experimental features. This option is available starting with Visual Studio 2015 Update 3. + +Depending on the MSVC compiler version or update level, features from published C++ standards or proposed features in the current C++ working draft, may not be fully implemented or fully conforming when you specify the **`/std:c++latest`** option. We recommend you use the latest version of Visual Studio for maximum standards conformance. For an overview of C++ language and library conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). + +Since Visual Studio 2019 version 16.8, the **`/std:c++latest`** option has enabled the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. For a list of supported language and library features, see [What's New for C++ in Visual Studio](../../overview/what-s-new-for-visual-cpp-in-visual-studio.md). The **`/std:c++latest`** option doesn't enable features guarded by the **`/experimental`** switch, but may be required to enable them. > [!NOTE] -> The compiler and library features enabled by **`/std:c++latest`** may appear in a future C++ standard. Features that have not been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. +> The compiler and library features enabled by **`/std:c++latest`** may appear in a future C++ standard. Features that haven't been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. -### C standards support +## C standards support You can invoke the Microsoft C compiler by using the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. It's used by default for code that has a *`.c`* file extension, unless overridden by a **`/TP`** or **`/Tp`** option. The default C compiler (that is, the compiler when **`/std:c11`** or **`/std:c17`** isn't specified) implements ANSI C89, but includes several Microsoft extensions, some of which are part of ISO C99. Some Microsoft extensions to C89 can be disabled by using the [`/Za`](za-ze-disable-language-extensions.md) compiler option, but others remain in effect. It isn't possible to specify strict C89 conformance. The compiler doesn't implement several required features of C99, so it isn't possible to specify C99 conformance, either. -**`/std:c11`**\ -The **`/std:c11`** option enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. +### `/std:c11` + +Enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. -**`/std:c17`**\ -The **`/std:c17`** option enables ISO C17 conformance. It's available starting in Visual Studio 2019 version 16.8. +### `/std:c17` + +Enables ISO C17 conformance. It's available starting in Visual Studio 2019 version 16.8. Because the new preprocessor is needed to support these standards, the **`/std:c11`** and **`/std:c17`** compiler options set the [`/Zc:preprocessor`](zc-preprocessor.md) option automatically. If you want to use the traditional (legacy) preprocessor for C11 or C17, you must set the **`/Zc:preprocessor-`** compiler option explicitly. Setting the **`/Zc:preprocessor-`** option may lead to unexpected behavior, and isn't recommended. @@ -80,15 +101,10 @@ Because the new preprocessor is needed to support these standards, the **`/std:c When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the features of C11 and C17 required by the standards. The **`/std:c11`** and **`/std:c17`** compiler options enable support for these functionalities: - [`_Pragma`](../../preprocessor/pragma-directives-and-the-pragma-keyword.md#the-pragma-preprocessing-operator) - - [`restrict`](../../c-language/type-qualifiers.md#restrict) - - [`_Noreturn`](../../c-language/noreturn.md) and \ - - [`_Alignas`, `_Alignof`](../../c-language/alignment-c.md) and \ - - [`_Generic`](../../c-language/generic-selection.md) and \ - - [`_Static_assert`](../../c-language/static-assert-c.md) The IDE uses C settings for IntelliSense and code highlighting when your source files have a *`.c`* file extension, or when you specify the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. Currently, IntelliSense in C highlights keywords `_Alignas`, `_Alignof`, `_Noreturn`, and `_Static_assert`, but not the equivalent macros defined in the standard headers: `alignas`, `alignof`, `noreturn`, and `static_assert`. @@ -101,21 +117,24 @@ The compiler doesn't support most optional features of ISO C11. Several of these - `aligned_alloc` support is missing, because of the Windows heap implementation. The alternative is to use [`_aligned_malloc`](../../c-runtime-library/reference/aligned-malloc.md). -- [DR 400](https://wg14.link/n2148#dr_400) support is currently unimplemented for `realloc`, because this change would break the ABI. +- [Defect report 400](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2148.htm#dr_400) support is currently unimplemented for `realloc` because this change would break the ABI. - Variable length array (VLA) support isn't planned. VLAs provide attack vectors comparable to [`gets`](../../c-runtime-library/gets-getws.md), which is deprecated and planned for removal. +### `/std:clatest` + +The **`/std:clatest`** option behaves like the `/std:c++latest` switch for the C++ compiler. The switch enables all currently implemented compiler and standard library features proposed in the next draft C standard, as well as some in-progress and experimental features. + For more information, see the C Standard library features section of [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. - 1. In **C++ Language Standard** (or for C, **C Language Standard**), choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes. ## See also -[MSVC compiler options](compiler-options.md)
+[`/Zc:__cplusplus[-]`](zc-cplusplus.md)\ +[MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/subsystem-specify-subsystem.md b/docs/build/reference/subsystem-specify-subsystem.md index 1a0ff36443..5669fa0e8b 100644 --- a/docs/build/reference/subsystem-specify-subsystem.md +++ b/docs/build/reference/subsystem-specify-subsystem.md @@ -1,63 +1,65 @@ --- description: "Learn more about: /SUBSYSTEM (Specify Subsystem)" title: "/SUBSYSTEM (Specify Subsystem)" -ms.date: "11/04/2016" -f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion"] +ms.date: 09/09/2022 +f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion", "VC.Project.VCLinkerTool.MinimumRequiredVersion"] helpviewer_keywords: ["/SUBSYSTEM linker option", "SUBSYSTEM linker option", "-SUBSYSTEM linker option", "subsystem specifications"] ms.assetid: d7b133cf-cf22-4da8-ab46-6552702c0b9b --- -# /SUBSYSTEM (Specify Subsystem) +# `/SUBSYSTEM` (Specify Subsystem) -``` -/SUBSYSTEM:{BOOT_APPLICATION|CONSOLE|EFI_APPLICATION| - EFI_BOOT_SERVICE_DRIVER|EFI_ROM|EFI_RUNTIME_DRIVER|NATIVE| - POSIX|WINDOWS} - [,major[.minor]] -``` +Specify the Windows subsystem targeted by the executable. + +## Syntax + +> **`/SUBSYSTEM:`** { **`BOOT_APPLICATION`** | **`CONSOLE`** | **`EFI_APPLICATION`** |\ +>   **`EFI_BOOT_SERVICE_DRIVER`** | **`EFI_ROM`** | **`EFI_RUNTIME_DRIVER`** | **`NATIVE`** |\ +>   **`POSIX`** | **`WINDOWS`** }\ +>   [ **`,`**_`major`_ [ **`.`**_`minor`_ ]] ## Arguments -**BOOT_APPLICATION**
+**`BOOT_APPLICATION`**\ An application that runs in the Windows boot environment. For more information about boot applications, see [About BCD](/previous-versions/windows/desktop/bcd/about-bcd). -**CONSOLE**
+**`CONSOLE`**\ Win32 character-mode application. The operating system provides a console for console applications. If `main` or `wmain` is defined for native code, `int main(array ^)` is defined for managed code, or you build the application completely by using `/clr:safe`, CONSOLE is the default. -**EFI_APPLICATION**
-**EFI_BOOT_SERVICE_DRIVER**
-**EFI_ROM**
-**EFI_RUNTIME_DRIVER**
-The Extensible Firmware Interface subsystems. See the EFI specification for more information. For examples, see the Intel Web site. The minimum version and default version is 1.0. +**`EFI_APPLICATION`**\ +**`EFI_BOOT_SERVICE_DRIVER`**\ +**`EFI_ROM`**\ +**`EFI_RUNTIME_DRIVER`**\ +The Extensible Firmware Interface subsystems. For more information, see the [UEFI specification](https://uefi.org/specifications). The minimum version and default version is 1.0. -**NATIVE**
-Kernel mode drivers for Windows NT. This option is usually reserved for Windows system components. If [/DRIVER:WDM](driver-windows-nt-kernel-mode-driver.md) is specified, NATIVE is the default. +**`NATIVE`**\ +Kernel mode drivers for Windows NT. This option is normally reserved for Windows system components. If [`/DRIVER:WDM`](driver-windows-nt-kernel-mode-driver.md) is specified, `NATIVE` is the default. -**POSIX**
+**`POSIX`**\ Application that runs with the POSIX subsystem in Windows NT. -**WINDOWS**
-Application does not require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined for native code, or `WinMain(HISTANCE *, HINSTANCE *, char *, int)` or `wWinMain(HINSTANCE *, HINSTANCE *, wchar_t *, int)` is defined for managed code, WINDOWS is the default. +**`WINDOWS`**\ +The application doesn't require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined for native code, or `WinMain(HINSTANCE *, HINSTANCE *, char *, int)` or `wWinMain(HINSTANCE *, HINSTANCE *, wchar_t *, int)` is defined for managed code, `WINDOWS` is the default. -*major* and *minor*
-(Optional) Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. See the Remarks for more information. There are no upper bounds for version numbers. +*`major`* and *`minor`*\ +(Optional) Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. There are no upper bounds for version numbers. ## Remarks -The **/SUBSYSTEM** option specifies the environment for the executable. +The **`/SUBSYSTEM`** option specifies the environment for the executable. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will select. -The optional minimum and default *major* and *minor* version numbers for the subsystems are as follows. +The optional minimum and default *`major`* and *`minor`* version numbers for the subsystems are as follows: -|Subsystem|Minimum|Default| -|---------------|-------------|-------------| -|BOOT_APPLICATION|1.0|1.0| -|CONSOLE|5.01 (x86) 5.02 (x64) 6.02 (ARM)|6.00 (x86, x64) 6.02 (ARM)| -|WINDOWS|5.01 (x86) 5.02 (x64) 6.02 (ARM)|6.00 (x86, x64) 6.02 (ARM)| -|NATIVE (with DRIVER:WDM)|1.00 (x86) 1.10 (x64, ARM)|1.00 (x86) 1.10 (x64, ARM)| -|NATIVE (without /DRIVER:WDM)|4.00 (x86) 5.02 (x64) 6.02 (ARM)|4.00 (x86) 5.02 (x64) 6.02 (ARM)| -|POSIX|1.0|19.90| -|EFI_APPLICATION, EFI_BOOT_SERVICE_DRIVER, EFI_ROM, EFI_RUNTIME_DRIVER|1.0|1.0| +| Subsystem | Minimum | Default | +|--|--|--| +| `BOOT_APPLICATION` | 1.0 | 1.0 | +| `CONSOLE` | 5.01 (x86) 5.02 (x64) 6.02 (ARM) | 6.00 (x86, x64) 6.02 (ARM) | +| `WINDOWS` | 5.01 (x86) 5.02 (x64) 6.02 (ARM) | 6.00 (x86, x64) 6.02 (ARM) | +| `NATIVE` (with **`/DRIVER:WDM`**) | 1.00 (x86) 1.10 (x64, ARM) | 1.00 (x86) 1.10 (x64, ARM) | +| `NATIVE` (without **`/DRIVER:WDM`**) | 4.00 (x86) 5.02 (x64) 6.02 (ARM) | 4.00 (x86) 5.02 (x64) 6.02 (ARM) | +| `POSIX` | 1.0 | 19.90 | +| `EFI_APPLICATION`, `EFI_BOOT_SERVICE_DRIVER`, `EFI_ROM`, `EFI_RUNTIME_DRIVER` | 1.0 | 1.0 | ### To set this linker option in the Visual Studio development environment @@ -73,5 +75,5 @@ The optional minimum and default *major* and *minor* version numbers for the sub ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/time-linker-time-information.md b/docs/build/reference/time-linker-time-information.md new file mode 100644 index 0000000000..04c414de2d --- /dev/null +++ b/docs/build/reference/time-linker-time-information.md @@ -0,0 +1,35 @@ +--- +description: "Learn more about the /TIME (Linker time information) linker option." +title: "/TIME" +ms.date: 05/11/2022 +f1_keywords: ["/time"] +helpviewer_keywords: ["/time"] +--- +# `/TIME` (Linker time information) + +Output the time taken by linker steps and total link time. + +## Syntax + +> **`/TIME`** + +## Remarks + +The `/TIME` linker option displays the time taken by the linker steps and the total link time in seconds, with millisecond precision. + +### To set this linker option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. + +1. In the **Additional Options** box, add the *`/TIME`* linker option. Choose **OK** or **Apply** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/tlbout-name-dot-tlb-file.md b/docs/build/reference/tlbout-name-dot-tlb-file.md index a9fde3067b..3daba01380 100644 --- a/docs/build/reference/tlbout-name-dot-tlb-file.md +++ b/docs/build/reference/tlbout-name-dot-tlb-file.md @@ -1,32 +1,31 @@ --- description: "Learn more about: /TLBOUT (Name .TLB File)" title: "/TLBOUT (Name .TLB File)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.TypeLibraryFile", "/tlbout"] helpviewer_keywords: ["tlb files, renaming", "TLBOUT linker option", "/TLBOUT linker option", ".tlb files, renaming", "-TLBOUT linker option"] -ms.assetid: 0df6d078-2e48-46c9-a1a5-02674d85dce8 --- -# /TLBOUT (Name .TLB File) +# `/TLBOUT` (Name .TLB File) -``` +```cmd /TLBOUT:[path\]filename ``` ## Arguments -*path*
+*`path`*\ An absolute or relative path specification for where the .tlb file should be created. -*filename*
-Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. +*`filename`* +Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /TLBOUT option specifies the name and extension of the .tlb file. +The `/TLBOUT` option specifies the name and extension of the .tlb file. The MIDL compiler is called by the MSVC linker when linking projects that have the [module](../../windows/attributes/module-cpp.md) attribute. -If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. +If `/TLBOUT` is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. ### To set this linker option in the Visual Studio development environment @@ -42,8 +41,8 @@ If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlo ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
-[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)\ +[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)\ [Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md index d8bf095313..fa5cadac9e 100644 --- a/docs/build/reference/translateinclude.md +++ b/docs/build/reference/translateinclude.md @@ -1,76 +1,50 @@ --- -title: "/translateInclude (Translate include directives into import directives)" +title: "/translateInclude" description: "Use the /translateInclude compiler option to treat #include directives as import statements when an importable header unit is available." -ms.date: 4/13/2021 +ms.date: 02/17/2022 author: "tylermsft" ms.author: "twhitney" -f1_keywords: ["/translateInclude"] +f1_keywords: ["/translateInclude", "VC.Project.VCCLCompilerTool.TranslateIncludes"] helpviewer_keywords: ["/translateInclude", "Translate include directives into import directives"] --- -# `/translateInclude` (Translate include directives into import directives) +# `/translateInclude` -Instructs the compiler to treat `#include` as `import` for those headers that have been prebuilt into a header unit (`.ifc`) file. +This switch instructs the compiler to treat `#include` as `import` for header files that have been built into header unit (`.ifc`) files and that are specified on the command line with [`/headerUnit`](headerunit.md). -## Syntax - -> **`/translateInclude`** - -## Remarks - -The **`/translateInclude`** compiler option requires you enable the [/std:c++20](std-specify-language-standard-version.md) or later option (such as **`/std:c++latest`**). `/translateInclude` is available starting in Visual Studio 2019 version 16.10. - -The **`/translateInclude`** option effectively makes the following transformation, where the example `` has been prebuilt into an importable header unit: - -```cpp -#include -``` +When used with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists as imported header units in the generated dependency file those headers that are both included in the source and have a corresponding entry in a `header-units.json` file. This dependency info is used by the build system to generate compiled header unit `.ifc` files. Once the header units are built, they're treated by the compiler as an `import` instead of an `#include`. -The compiler replaces this directive with: +The `header-units.json` file is only consulted when `/translateInclude` is specified. For more information about the format and purpose of the `header-units.json` file, see [`header-units.json`](header-unit-json-reference.md). -```cpp -import ; -``` +If an `#include` file isn't listed in the `header-units.json` file, it's treated as a normal `#include`. -In MSVC, available header units are made available by the **`/headerUnit`** option, which maps a header file to its corresponding prebuilt importable header unit. For more information, see [`/headerUnit` (Specify where to find the header unit file (`.ifc`) for the specified header)](headerunit.md). +For an example of how this switch is used, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md). -### Examples - -Given a project that references two header files and their header units, listed in this table: - -| Header file | IFC file | -|--|--| -| *`C:\utils\util.h`* | *`C:\util.h.ifc`* | -| *`C:\app\app.h`* | *`C:\app.h.ifc`* | - -And a source *`.cpp`* file that includes the headers, +## Syntax -```cpp -#include "utils/util.h" -#include "app/app.h" +> **`/translateInclude`** -int main() { } -``` +## Remarks -The **`/translateInclude`** option allows the compiler to treat an `#include` as an `import` for header files that have a corresponding compiled header unit file (*`.ifc`*) and that have been specified on the command line via the `/headerUnit` switch. +**`/translateInclude`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/translateInclude`** requires [/std:c++20](std-specify-language-standard-version.md) or later. -If an `#include` is encountered that doesn't have a corresponding header unit specified via the `/headerUnit` switch, it is processed by the preprocessor as a normal `#include` directive. +## To set this compiler option in Visual Studio - Here's an example command line that translates the include directives for *`util.h`* and *`app.h`* into imports of the header units instead: +To enable `/translateInclude`, in the project properties dialog, set **Translate Includes to Imports**: -```CMD -cl /IC:\ /translateInclude /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit C:\app\app.h=C:\app.h.ifc -``` +1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General**. -## To set this compiler option in Visual Studio +1. Change the **Translate Includes to Imports** dropdown to **Yes**. -To enable `/translateInclude`, set the **Translate Includes to Imports** option in project properties: + ![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png) -1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General** -1. Change the **Translate Includes to Imports** dropdown to **Yes** -![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png) +1. Choose **OK** or **Apply** to save your changes. ## See also [`/headerUnit` (Use header unit IFC)](headerunit.md).\ [`/exportHeader` (Create header units)](module-exportheader.md)\ -[`/reference` (Use named module IFC)](module-reference.md) +[`/reference` (Use named module IFC)](module-reference.md)\ +[`/scanDependencies`](scandependencies.md)\ +[`/sourceDependencies-directives`](sourcedependencies-directives.md)\ +[Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md) diff --git a/docs/build/reference/tsaware-create-terminal-server-aware-application.md b/docs/build/reference/tsaware-create-terminal-server-aware-application.md index e5d398e9d6..3b060a4c75 100644 --- a/docs/build/reference/tsaware-create-terminal-server-aware-application.md +++ b/docs/build/reference/tsaware-create-terminal-server-aware-application.md @@ -1,32 +1,30 @@ --- -description: "Learn more about: /TSAWARE (Create Terminal Server Aware Application)" -title: "/TSAWARE (Create Terminal Server Aware Application)" -ms.date: "11/04/2016" +description: "Learn more about: /TSAWARE (Create Terminal Server aware application)" +title: "/TSAWARE (Create Terminal Server aware application)" +ms.date: 03/02/2022 f1_keywords: ["/tsaware", "VC.Project.VCLinkerTool.TerminalServerAware"] helpviewer_keywords: ["Terminal Server", "/TSAWARE linker option", "Terminal Server, Terminal Server-aware applications", "-TSAWARE linker option", "TSAWARE linker option"] ms.assetid: fe1c1846-de5b-4839-b562-93fbfe36cd29 --- -# /TSAWARE (Create Terminal Server Aware Application) +# `/TSAWARE` (Create Terminal Server aware application) -``` -/TSAWARE[:NO] -``` +> **`/TSAWARE`**\[**`:NO`**] ## Remarks -The /TSAWARE option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The **`/TSAWARE`** option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. -When an application is not Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server will create a virtual Windows folder, such that each user gets a Windows folder instead of getting the system's Windows directory. This gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. +When an application isn't Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server creates a virtual *`Windows`* folder, such that each user gets a *`Windows`* folder instead of getting the system's *`Windows`* directory. This virtual folder gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. -If an application is Terminal Server aware, it must neither rely on INI files nor write to the **HKEY_CURRENT_USER** registry during setup. +If an application is Terminal Server aware, it must not rely on INI files or write to the `HKEY_CURRENT_USER` registry during setup. -If you use /TSAWARE and your application still uses INI files, the files will be shared by all users of the system. If that is acceptable, you can still link your application with /TSAWARE; otherwise you need to use /TSAWARE:NO. +If you use **`/TSAWARE`** and your application still uses INI files, the files will be shared by all users of the system. If that's acceptable, you can still link your application with **`/TSAWARE`**; otherwise you need to use **`/TSAWARE:NO`**. -The /TSAWARE option is enabled by default for Windows and console applications. See [/SUBSYSTEM](subsystem-specify-subsystem.md) and [/VERSION](version-version-information.md) for information. +The **`/TSAWARE`** option is enabled by default for Windows and console applications. For more information, see [`/SUBSYSTEM`](subsystem-specify-subsystem.md) and [`/VERSION`](version-version-information.md). -/TSAWARE is not valid for drivers or DLLs. +**`/TSAWARE`** isn't valid for drivers or DLLs. -If an application was linked with /TSAWARE, DUMPBIN [/HEADERS](headers.md) will display information to that effect. +If an application was linked with **`/TSAWARE`**, [`DUMPBIN /HEADERS`](headers.md) will display information to that effect. ### To set this linker option in the Visual Studio development environment diff --git a/docs/build/reference/u-u-undefine-symbols.md b/docs/build/reference/u-u-undefine-symbols.md index 816c704527..cdc3cdd3ba 100644 --- a/docs/build/reference/u-u-undefine-symbols.md +++ b/docs/build/reference/u-u-undefine-symbols.md @@ -1,12 +1,11 @@ --- title: "/U, /u (Undefine symbols)" description: "Use the Microsoft C/C++ compiler /U and /u options to undefine preprocessor symbols." -ms.date: 09/03/2020 +ms.date: 04/14/2025 f1_keywords: ["VC.Project.VCCLCompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLWCECompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLCompilerTool.UndefineAllPreprocessorDefinitions", "/u", "VC.Project.VCCLWCECompilerTool.UndefineAllPreprocessorDefinitions"] helpviewer_keywords: ["-U compiler option [C++]", "Undefine Symbols compiler option", "/U compiler option [C++]", "U compiler option [C++]"] -ms.assetid: 7bc0474f-6d1f-419b-807d-0d8816763b2a --- -# /U, /u (Undefine symbols) +# `/U`, `/u` (Undefine symbols) The **`/U`** compiler option undefines the specified preprocessor symbol. The **`/u`** compiler option undefines the Microsoft-specific symbols that the compiler defines. @@ -17,7 +16,7 @@ The **`/U`** compiler option undefines the specified preprocessor symbol. The ** ## Arguments -*symbol*
+*`symbol`*\ The preprocessor symbol to undefine. ## Remarks @@ -44,9 +43,7 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - -1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. - +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. 1. Modify the **Undefine Preprocessor Definitions** or **Undefine All Preprocessor Definitions** properties. ### To set this compiler option programmatically @@ -55,9 +52,9 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac ## See also -[MSVC compiler options](compiler-options.md)
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
-[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)
-[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)
-[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)\ +[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)\ +[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)\ [**`/MD`**, **`/MT`**, **`/LD`** (Use run-time library)](md-mt-ld-use-run-time-library.md) diff --git a/docs/build/reference/useprofile.md b/docs/build/reference/useprofile.md index 9efe996529..9a9fde9e72 100644 --- a/docs/build/reference/useprofile.md +++ b/docs/build/reference/useprofile.md @@ -1,12 +1,12 @@ --- description: "Learn more about: /USEPROFILE (Run PGO in thread safe mode)" title: "/USEPROFILE (Use PGO data with LTCG)" -ms.date: "03/14/2018" +ms.date: 03/24/2025 f1_keywords: ["USEPROFILE"] --- # /USEPROFILE (Run PGO in thread safe mode) -This linker option together with [/LTCG (Link-time code generation](ltcg-link-time-code-generation.md) tells the linker to build by using profile-guided optimization (PGO) training data. +This linker option together with [`/LTCG` (Link-time code generation](ltcg-link-time-code-generation.md) tells the linker to build by using profile-guided optimization (PGO) training data. ## Syntax @@ -14,21 +14,21 @@ This linker option together with [/LTCG (Link-time code generation](ltcg-link-ti ### Arguments -**AGGRESSIVE**
+**`AGGRESSIVE`**\ This optional argument specifies that aggressive speed optimizations should be used during optimized code generation. -**PGD**=*filename*
-Specifies a base file name for the .pgd file. By default, the linker uses the base executable file name with a .pgd extension. +**`PGD`**=*filename*\ +Specifies a base filename for the `.pgd` file. By default, the linker uses the base executable filename with a `.pgd` extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The **/USEPROFILE** linker option is used together with **/LTCG** to generate or update an optimized build based on PGO training data. It is the equivalent of the deprecated **/LTCG:PGUPDATE** and **/LTCG:PGOPTIMIZE** options. +The **`/USEPROFILE`** linker option is used together with **`/LTCG`** to generate or update an optimized build based on PGO training data. It is the equivalent of the deprecated **`/LTCG:PGUPDATE`** and **`/LTCG:PGOPTIMIZE`** options. -The optional **AGGRESSIVE** argument disables size-related heuristics to attempt to optimize for speed. This may result in optimizations that substantially increase the size of your executable, and may not increase the resulting speed. You should profile and compare the results of using and not using **AGGRESSIVE**. This argument must be specified explicitly; it is not enabled by default. +The optional **`AGGRESSIVE`** argument disables size-related heuristics to attempt to optimize for speed. This may result in optimizations that substantially increase the size of your executable, and may not increase the resulting speed. You should profile and compare the results of using and not using **`AGGRESSIVE`**. This argument must be specified explicitly; it is not enabled by default. -The **PGD** argument specifies an optional name for the training data .pgd file to use, the same as in [/GENPROFILE or /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). It is the equivalent of the deprecated **/PGD** switch. By default, or if no *filename* is specified, a .pgd file that has the same base name as the executable is used. +The **`PGD`** argument specifies an optional name for the training data `.pgd` file to use, the same as in [`/GENPROFILE` or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). It is the equivalent of the deprecated **/PGD** switch. By default, or if no *`filename`* is specified, a `.pgd` file that has the same base name as the executable is used. -The **/USEPROFILE** linker option is new in Visual Studio 2015. +The **`/USEPROFILE`** linker option is new in Visual Studio 2015. ### To set this linker option in the Visual Studio development environment @@ -48,7 +48,7 @@ The **/USEPROFILE** linker option is new in Visual Studio 2015. ## See also -[/GENPROFILE and /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)
-[/LTCG](ltcg-link-time-code-generation.md)
-[Profile-Guided Optimizations](../profile-guided-optimizations.md)
-[Environment Variables for Profile-Guided Optimizations](../environment-variables-for-profile-guided-optimizations.md)
+[`/GENPROFILE` and `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)\ +[`/LTCG`](ltcg-link-time-code-generation.md)\ +[Profile-Guided Optimizations](../profile-guided-optimizations.md)\ +[Environment Variables for Profile-Guided Optimizations](../environment-variables-for-profile-guided-optimizations.md) diff --git a/docs/build/reference/using-an-nmake-macro.md b/docs/build/reference/using-an-nmake-macro.md index 86fba9a857..f4b418744b 100644 --- a/docs/build/reference/using-an-nmake-macro.md +++ b/docs/build/reference/using-an-nmake-macro.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Using an NMAKE macro" title: "Use an NMAKE macro" +description: "Learn more about: Using an NMAKE macro" ms.date: 09/30/2021 helpviewer_keywords: ["macros, NMAKE", "NMAKE macros, using", "NMAKE program, macro substitution", "substitution macros in NMAKE", "NMAKE functions", "functions, NMAKE"] --- @@ -14,7 +14,7 @@ $(macro_name) No spaces are allowed. The parentheses are optional if *macro_name* is a single character. The definition string replaces `$(macro_name)`; an undefined macro is replaced by a null string. -## Macro substitution +## Macro substitution When *macro_name* is invoked, each occurrence of *string1* in its definition string is replaced by *string2*. @@ -28,11 +28,11 @@ No spaces or tabs precede the colon (**`:`**); any spaces or tabs after the colo ::: moniker range=">=msvc-170" -## Macro functions +## Macro functions NMAKE provides a set of functions that can be used to modify strings, lists of items and file paths. These functions are available in NMAKE starting in Visual Studio 2022. -### Function syntax +### Function syntax Functions use the following syntax: @@ -57,7 +57,7 @@ INPUT=a, b $(subst $(COMMA) , and ,$(INPUT)) # Evaluates to "a and b" ``` -### List syntax +### List syntax Some functions support a whitespace-separated list of items. Extra whitespace is ignored at the beginning of the list, the end of the list, or between each item. Lists produced by a function use a single space between each item as a separator, and don't have leading or trailing whitespace. @@ -67,7 +67,7 @@ For example, the simplest list function is `strip`, which takes a single list ar $(strip a b c d ) # Evaluates to "a b c d" ``` -### Pattern syntax +### Pattern syntax Some functions support using a *pattern*. A pattern is a string that contains a single wildcard that can match any number of characters. The first `%` in a pattern is the wildcard, and any later `%` characters are treated as literals. A `%` anywhere before the actual wildcard can be escaped by using `\` (that is, `\%` is treated as a literal `%`). Any `\` that would escape the wildcard can be escaped with another `\` (so `\\%` is treated as a literal `\` followed by the wildcard). To be considered a match, all of the input characters must be matched by the pattern; partial matches aren't supported. @@ -86,30 +86,23 @@ $(filter a%c\\%d,abc\\%d) # Evaluates to "abc\\%d" - any `\` after the wildcard $(filter \\a%f,\\abcdef) # Evaluates to "\\abcdef" - any `\\` that isn't directly before the wildcard isn't treated as an escape ``` -### Functions by category - -#### Text functions - -| Function | Purpose | -|--|--| -| [`findstring`, `findstringi`](nmake-function-findstring.md) | Checks if the input contains a string. | -| [`subst`, `substi`](nmake-function-subst.md) | Replaces all instances of one string with another. | - -#### List functions - -| Function | Purpose | -|--|--| -| [`filter`, `filteri`](nmake-function-filter.md) | Keeps items in a list that match at least one pattern. | -| [`filterout`, `filterouti`](nmake-function-filterout.md) | Keeps items in a list that don't match any patterns. | -| [`patsubst`, `patsubsti`](nmake-function-patsubst.md) | Transforms each item that matches a pattern, items that don't match are left as-is. | -| [`strip`](nmake-function-strip.md) | Cleans the whitespace in and around a list of items. | - -#### File path functions - -| Function | Purpose | -|--|--| -| [`abspath`](nmake-function-abspath.md) | Gets the absolute path for each item in a list. | -| [`basename`](nmake-function-basename.md) | Gets the base name for each item in a list. | +### Functions by category + +| Function | Purpose | Supported | +|--|--|--| +| **Text functions** | **Purpose** | **Supported** | +|  [`findstring`, `findstringi`](nmake-function-findstring.md) | Checks if the input contains a string. | VS 2022 17.0 | +|  [`lowercase`](nmake-function-lowercase.md) | Converts a string to lowercase. | VS 2022 17.2 | +|  [`subst`, `substi`](nmake-function-subst.md) | Replaces all instances of one string with another. | VS 2022 17.0 | +|  [`uppercase`](nmake-function-uppercase.md) | Converts a string to uppercase. | VS 2022 17.2 | +| **List functions** | **Purpose** | **Supported** | +|  [`filter`, `filteri`](nmake-function-filter.md) | Keeps items in a list that match at least one pattern. | VS 2022 17.0 | +|  [`filterout`, `filterouti`](nmake-function-filterout.md) | Keeps items in a list that don't match any patterns. | VS 2022 17.0 | +|  [`patsubst`, `patsubsti`](nmake-function-patsubst.md) | Transforms each item that matches a pattern, items that don't match are left as-is. | VS 2022 17.1 | +|  [`strip`](nmake-function-strip.md) | Cleans the whitespace in and around a list of items. | VS 2022 17.0 | +| **File path functions** | **Purpose** | **Supported** | +|  [`abspath`](nmake-function-abspath.md) | Gets the absolute path for each item in a list. | VS 2022 17.1 | +|  [`basename`](nmake-function-basename.md) | Gets the base name for each item in a list. | VS 2022 17.1 | ::: moniker-end diff --git a/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md b/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md index f2524dd177..b0e8d0d005 100644 --- a/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md +++ b/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: `/utf-8` (Set Source and Executable character sets to UTF-8)" -title: "/utf-8 (Set Source and Executable character sets to UTF-8)" -ms.date: "04/26/2020" +description: "Learn more about: `/utf-8` (Set source and execution character sets to UTF-8)" +title: "/utf-8 (Set source and execution character sets to UTF-8)" +ms.date: 01/31/2022 f1_keywords: ["/utf-8"] helpviewer_keywords: ["/utf-8 compiler option"] ms.assetid: f0e1f3cb-6cae-46eb-9483-04ed13d9b504 no-loc: [UTF, UTF-8, UTF-16] --- -# `/utf-8` (Set Source and Executable character sets to UTF-8) +# `/utf-8` (Set source and execution character sets to UTF-8) Specifies both the source character set and the execution character set as UTF-8. @@ -19,7 +19,7 @@ Specifies both the source character set and the execution character set as UTF-8 You can use the **`/utf-8`** option to specify both the source and execution character sets as encoded by using UTF-8. It's equivalent to specifying **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you've specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you've specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. ## Set the option in Visual Studio or programmatically @@ -39,8 +39,8 @@ By default, Visual Studio detects a byte-order mark to determine if the source f ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/validate-charset-validate-for-compatible-characters.md b/docs/build/reference/validate-charset-validate-for-compatible-characters.md index 34faa7f57f..ec8e1a2a15 100644 --- a/docs/build/reference/validate-charset-validate-for-compatible-characters.md +++ b/docs/build/reference/validate-charset-validate-for-compatible-characters.md @@ -1,43 +1,41 @@ --- description: "Learn more about: /validate-charset (Validate for compatible characters)" title: "/validate-charset (Validate for compatible characters)" -ms.date: "02/06/2019" +ms.date: 01/31/2022 f1_keywords: ["/validate-charset", "validate-charset"] helpviewer_keywords: ["/validate-charset compiler option"] ms.assetid: 50360fd0-4d32-4a4f-95d0-53d38c12ad4c --- -# /validate-charset (Validate for compatible characters) +# `/validate-charset` (Validate for compatible characters) -Validates that the source file text contains only characters representable as UTF-8. +This compiler option validates that the source file text contains only characters representable as UTF-8. ## Syntax -``` -/validate-charset[-] -``` +> **`validate-charset`**[**`-`**] ## Remarks -You can use the **/validate-charset** option to validate that the source code contains only characters that can be represented in both the source character set and the execution character set. This check is enabled automatically when you specify **/source-charset**, **/execution-charset**, or **/utf-8** compiler options. You can explicitly disable this check by specifying the **/validate-charset-** option. +You can use the **`/validate-charset`** option to validate that the source code contains only characters that can be represented in both the source character set and the execution character set. This check is enabled automatically when you specify **`/source-charset`**, **`/execution-charset`**, or **`/utf-8`** compiler options. To explicitly disable this check, specify the **`/validate-charset-`** option. -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you have specified a code page by using **/utf-8** or the **/source-charset** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you have specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -Visual Studio uses UTF-8 as the internal character encoding during conversion between the source character set and the execution character set. If a character in the source file cannot be represented in the execution character set, the UTF-8 conversion substitutes a question mark '?' character. The **/validate-charset** option causes the compilation to report a warning if this occurs. +Visual Studio uses UTF-8 as the internal character encoding during conversion between the source character set and the execution character set. If a character in the source file can't be represented in the execution character set, the UTF-8 conversion substitutes a question mark (`?`) character. If a substitution occurs, the **`/validate-charset`** option causes the compiler to report a warning. ### To set this compiler option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In **Additional Options**, add the **/validate-charset** option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/validate-charset`** or **`/validate-charset-`** option. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md) diff --git a/docs/build/reference/vcpp-directories-property-page.md b/docs/build/reference/vcpp-directories-property-page.md index e00afe6139..4b5daa513b 100644 --- a/docs/build/reference/vcpp-directories-property-page.md +++ b/docs/build/reference/vcpp-directories-property-page.md @@ -1,34 +1,35 @@ --- description: "Learn more about: VC++ Directories Property Page (Windows)" title: "VC++ Directories Property Page" -ms.date: "07/17/2019" -f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath", "VC.Project.VCDirectories.ExternalIncludePath", "VC.Project.VCConfiguration.PublicIncludeDirectories", "VC.Project.VCConfiguration.AllProjectIncludesArePublic", "VC.Project.VCConfiguration.PublicModuleDirectories", "VC.Project.VCConfiguration.AllProjectBMIsArePublic"] helpviewer_keywords: ["VC++ Directories Property Page"] -ms.assetid: 428eeef6-f127-4271-b3ea-0ae6f2c3d624 --- # VC++ Directories Property Page (Windows) -Use this property page to tell Visual Studio which directories to use when building the currently-selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this property page to tell Visual Studio which directories to use when building the currently selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). For the Linux version of this page, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). To access the **VC++ Directories** property page: -1. If the **Solution Explorer** window is not visible, then on the main menu choose **View** > **Solution Explorer**. +1. If the **Solution Explorer** window isn't visible, choose **View** > **Solution Explorer** on the main menu. 1. Right-click on a project node (not the top-level solution) and choose **Properties** to open the **Property Pages** dialog box. 1. Select the **Configuration Properties** > **VC++ Directories** property page. -VC++ Directories properties apply to a project, not the top-level solution node. If you do not see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: +VC++ Directories properties apply to a project, not the top-level solution node. If you don't see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: -![Screenshot of the Solution Explorer window with the Project node selected.](../media/vcppdir.png "Select the project node to see the VC++ Directories properties") +:::image type="complex" source="../media/vcppdir.png" alt-text="Screenshot of the Solution Explorer window with the Project node selected."::: +In the property pages dialog, Configuration properties > VC++ directories is selected. The various C++ directories are listed, such as: executable directories, include directories, library directories, source directories, and so on. +:::image-end::: -Note that the **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). +The **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). -If you are not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you're not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -The default settings for **VC++ Directories** properties depend on project type. For desktop projects they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. +The default settings for **VC++ Directories** properties depend on project type. For desktop projects, they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. To view the values for any of the directories: @@ -40,55 +41,76 @@ To view the values for any of the directories: You now see a dialog box like this: -![Screenshot of the Library Directories dialog.](../media/vcppdir_libdir.png "Dialog to add or remove library paths") +:::image type="complex" source="../media/vcppdir_libdir.png" alt-text="Screenshot of the Library Directories dialog."::: +The library directories dialog has a library directories area and an evaluated value area that shows the path values after all macros have been expanded. There's an inherited values area that shows the macro values inherited from the parent or the project. There's a checkbox, checked, that says Inherit from parent or project defaults. There's a macros button and an OK and Cancel button. +:::image-end::: -Use this dialog to view the current directories. However, if you want to change or add a directory, it is better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this dialog to view the current directories. However, if you want to change or add a directory, it's better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). -As shown above, many of the inherited paths are given as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Note that many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build. +As shown earlier, many of the inherited paths are provided as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build, for example. For information about examining macros values, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). -You can search for partial or complete matches in the edit box. The following illustration shows all the macros that contain the string "WindowsSDK" and it also shows the current path that the macro evaluates to: +You can search for partial or complete matches of a macro in the edit box. The following screenshot shows all the macros that contain the string "WindowsSDK". It also shows the current path that each macro evaluates to: -![Screenshot of the Library Directories dialog with the list of macro values displayed.](../media/vcppdir_libdir_macros.png "Dialog to edit macros") +:::image type="complex" source="../media/vcppdir_libdir_macros.png" alt-text="Screenshot of the Library Directories dialog with the list of macro values displayed."::: +The Library Directories dialog is shown, and a filtered list of macros. Results include macros that contain the string "WindowsSDK", such as $ ( Windows SDK _ Executable Path ), $ ( Windows SDK _ Include Path ), $ ( Windows SDK _ Library Path ), and more. There's an inherited values area that shows which macro values are inherited from a parent or project. There's an evaluated value area that shows the path values after all macros have been expanded. There's a checkbox, checked, that says Inherit from parent or project defaults. There's a macros button and an Insert, OK, and Cancel button. +:::image-end::: -Note: The list is populated as you type. Don't press **Enter**. +This list is populated as you type. Don't press **Enter**. For more information about macros and why you should use them instead of hard-coded paths whenever possible, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -For a list of commonly used macros, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). +For information about examining the values of the macros, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). That topic also lists commonly used macros. You can define your own macros in two ways: - Set environment variables in a developer command prompt. All environment variables are treated as MSBuild properties/macros. -- Define user macros in a .props file. For more information, see [Property page macros](../working-with-project-properties.md). +- Define user macros in a *`.props`* file. For more information, see [Property page macros](../working-with-project-properties.md). For more information, see [Property inheritance in Visual Studio projects](../project-property-inheritance.md), and these blog posts: [VC++ Directories](/archive/blogs/vsproject/vc-directories), [Visual Studio 2010 C++ Project Upgrade Guide](https://devblogs.microsoft.com/cppblog/visual-studio-2010-c-project-upgrade-guide/). -## Directory Types +## General You can also specify other directories, as follows. -**Executable Directories**
-Directories in which to search for executable files. Corresponds to the **PATH** environment variable. +**Executable Directories**\ +Directories in which to search for executable files. Corresponds to the **`PATH`** environment variable. -**Include Directories**
-Directories in which to search for include files that are referenced in the source code. Corresponds to the **INCLUDE** environment variable. +**Include Directories**\ +Directories in which to search for include files that are referenced in the source code. Corresponds to the **`INCLUDE`** environment variable. -**Reference Directories**
-Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **LIBPATH** environment variable. +**External Include Directories**\ +Paths for include files to treat as external or system files during compilation. These files are skipped in build up-to-date checks. These paths are also used by the [External Includes](c-cpp-prop-page.md#external-includes) properties. For more information on how to set these options in the IDE, see the [`/external`](../../build/reference/external-external-headers-diagnostics.md) compiler option. -**Library Directories**
-Directories in which to search for libraries (.lib) files; this includes run-time libraries. Corresponds to the **LIB** environment variable. This setting does not apply to .obj files; to link to an .obj file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). +**Reference Directories**\ +Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **`LIBPATH`** environment variable. -**Library WinRT Directories**
+**Library Directories**\ +Directories to search for library (*`.lib`*) files. This search includes run-time libraries. Corresponds to the **`LIB`** environment variable. This setting doesn't apply to *`.obj`* files; to link to an *`.obj`* file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). + +**Library WinRT Directories**\ Directories to search for WinRT library files for use in Universal Windows Platform (UWP) apps. -**Source Directories**
+**Source Directories**\ Directories in which to search for source files to use for IntelliSense. -**Exclude Directories**
+**Exclude Directories**\ Before each compilation, Visual Studio queries the timestamp on all files to determine whether any have been modified since the previous compilation. If your project has large stable libraries, you can potentially speed up build times by excluding those directories from the timestamp check. -## Sharing the Settings +## Public Project Content + +**Public Include Directories**\ +One or more directories to automatically add to the include path in projects that reference this project. + +**All Header Files are Public**\ +Specifies whether to automatically add public directories or all project header files to the include path in projects that reference this project. + +**Public C++ Module Directories**\ +One or more directories that contain C++ module or header unit sources to make available automatically to projects that reference this project. + +**All Modules are Public**\ +Specifies whether to make all project modules and header units available automatically to projects that reference this project. + +## Sharing the settings You can share project properties with other users or across multiple computers. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/vcxproj-file-structure.md b/docs/build/reference/vcxproj-file-structure.md index 0f0cd77c75..0ce1e28fb5 100644 --- a/docs/build/reference/vcxproj-file-structure.md +++ b/docs/build/reference/vcxproj-file-structure.md @@ -1,7 +1,7 @@ --- title: ".vcxproj and .props file structure" description: "How the C++ native MSBuild project system .vcxproj and .props files store project information." -ms.date: 09/30/2020 +ms.date: 11/14/2022 helpviewer_keywords: [".vcxproj file structure"] ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c --- @@ -9,15 +9,15 @@ ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c [MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project** in Visual C++ you're creating an MSBuild project whose settings are stored in an XML project file that has the extension *`.vcxproj`*. The project file may also import *`.props`* files and *`.targets`* files where settings can be stored. -We recommend you only create and modify *`.vcxproj`* projects in the IDE, and avoid manual editing as much as possible. In most cases, you never need to manually edit the project file. Whenever possible you should use the Visual Studio property pages to modify project settings. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you intend to maintain your project properties in the IDE, we recommend you only create and modify your *`.vcxproj`* projects in the IDE, and avoid manual edits to the files. In most cases, you never need to manually edit the project file. Manual edits may break the project connections required to modify project settings in the Visual Studio property pages, and can cause build errors that are difficult to debug and repair. For more information about using the property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -If you need customizations that aren't possible in the IDE, we recommend you add custom props or targets. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. +At scale, managing many individual projects in the IDE becomes tedious and error-prone. It's hard to maintain consistency or enforce standardization across tens or hundreds of projects. In these cases, it's worthwhile to edit your project files to use customized *`.props`* or *`.targets`* files for common properties across many projects. You may also use these files when you require customizations that aren't possible in the IDE. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. -In some cases, you may still need to modify a *`.vcxproj`* project file or property sheet manually. We don't recommend you edit it manually unless you have a good understanding of MSBuild, and follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. They weren't designed for manual editing. Mistakes can cause the IDE to crash or behave in unexpected ways. +In some cases, customized *`.props`* or *`.targets`* files alone may not be sufficient for your project management needs. You may still need to modify *`.vcxproj`* project files or property sheets manually. Manual editing requires a good understanding of MSBuild, and must follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. Mistakes can cause the IDE to crash or behave in unexpected ways. For manual editing scenarios, this article contains basic information about the structure of *`.vcxproj`* and related files. -**Important:** +## Important considerations If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: @@ -42,7 +42,7 @@ If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: ``` - "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. That's because the IDE doesn't expect project item paths to be different for different project configurations. + "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. The IDE doesn't expect project item paths to be different for different project configurations. - To add, remove, or modify project properties correctly when you edit them in the **Project Properties** dialog, the file must contain separate groups for each project configuration. The conditions must be in this form: @@ -272,7 +272,7 @@ Defines (directly or through imports) C++ targets such as build, clean, and so o This group contains imports for the Build Customization target files. -## Impact of incorrect ordering +## Consequences of incorrect ordering The Visual Studio IDE depends on the project file having the ordering described previously. For example, when you define a property value in the property pages, the IDE will generally place the property definition in the property group with the empty label. This ordering ensures that default values brought in the system property sheets are overridden by user-defined values. Similarly, the target files are imported at the end since they consume the properties defined before, and since they generally don't define properties themselves. Likewise, user property sheets are imported after the system property sheets (included by *`Microsoft.Cpp.props`*). This order ensures that the user can override any defaults brought in by the system property sheets. diff --git a/docs/build/reference/vcxproj-filters-files.md b/docs/build/reference/vcxproj-filters-files.md index 53893c7a64..f03ac67005 100644 --- a/docs/build/reference/vcxproj-filters-files.md +++ b/docs/build/reference/vcxproj-filters-files.md @@ -6,19 +6,21 @@ helpviewer_keywords: ["vcxproj.filters", "filters file [C++]"] --- # vcxproj.filters files -The *filters* file (\*.vcxproj.filters) is an XML file in MSBuild format that is located in the root project folder. It specifies which file types go into which logical folder in **Solution Explorer**. In the following illustration, the *.cpp* files are under the **Source Files** node. the *.h* files are under the **Header Files** node, and *.ico* and *.rc* files are under **Resource Files**. This placement is controlled by the filters file. +The *filters* file (`*.vcxproj.filters`) is an XML file in MSBuild format that is located in the root project folder. It specifies which file types go into which logical folder in **Solution Explorer**. In the following illustration, the `.cpp` files are under the **Source Files** node. the `.h` files are under the **Header Files** node, and `.ico` and `.rc` files are under **Resource Files**. This placement is controlled by the filters file. -![Screenshot of the Logical folders view in Solution Explorer.](media/solution-explorer-filters.png) +:::image type="complex" source="media/solution-explorer-filters.png" alt-text="Screenshot of the Logical folders view in Solution Explorer."::: +The solution explorer is shown with call outs for the following nodes: Header Files (which contains files like MFCApplication1.h), Resource Files (which contains files like MFCApplication1.ico), and Source Files (which contains files like MFCApplication1.cpp). +:::image-end::: ## Creating a custom filters file -Visual Studio creates this file automatically. For desktop applications, the predefined logical folders (filters) are: **Source Files**, **Header Files** and **Resource Files**. Other project types such as UWP might have a different set of default folders. Visual Studio automatically assigns known file types to each folder. If you want to create a filter with a custom name or a filter that holds custom file types, you can create your own filters file in the root folder of the project, or under an existing filter. (**References** and **External Dependencies** are special folders that do not participate in filtering.) +Visual Studio creates this file automatically. For desktop applications, the predefined logical folders (filters) are: **Source Files**, **Header Files** and **Resource Files**. Other project types such as UWP might have a different set of default folders. Visual Studio automatically assigns known file types to each folder. If you want to create a filter with a custom name or a filter that holds custom file types, you can create your own filters file in the root folder of the project, or under an existing filter. (**References** and **External Dependencies** are special folders that don't participate in filtering.) ## Example -The following example shows the filters file for the example show previously. It has a flat hierarchy; in other words, there are no nested logical folders. The `UniqueIdentifier` node is optional. It enables Visual Studio automation interfaces to find the filter. `Extensions` is also optional. When a new file is added to a project, it is added to the topmost filter with a matching file extension. To add a file to a specific filter, right-click on the filter and choose **Add New Item**. +The following example shows the filters file for the example show previously. It has a flat hierarchy; in other words, there are no nested logical folders. The `UniqueIdentifier` node is optional. It enables Visual Studio automation interfaces to find the filter. `Extensions` is also optional. When a new file is added to a project, it's added to the topmost filter with a matching file extension. To add a file to a specific filter, right-click on the filter and choose **Add New Item**. -The `ItemGroup` that contains the `ClInclude` nodes is created when the project is first launched. If you are generating your own vcxproj files, make sure that all project items also have an entry in the filters file. Values in a `ClInclude` node override the default filtering based on file extensions. When you use Visual Studio to add a new item to the project, the IDE will add an individual file entry in the filters file. The filter is not automatically reassigned if you change the file's extension. +The `ItemGroup` that contains the `ClInclude` nodes is created when the project is first launched. If you're generating your own vcxproj files, make sure that all project items also have an entry in the filters file. Values in a `ClInclude` node override the default filtering based on file extensions. When you use Visual Studio to add a new item to the project, the IDE adds an individual file entry in the filters file. The filter isn't automatically reassigned if you change the file's extension. ```xml @@ -83,7 +85,7 @@ The `ItemGroup` that contains the `ClInclude` nodes is created when the project ``` -To create nested logical folders, declare all nodes in filters `ItemGroup` as shown below. Each child node must declare the full logical path to the topmost parent. In the following example, an empty `ParentFilter` must be declared because it is referenced in later nodes. +To create nested logical folders, declare all nodes in filters `ItemGroup` as shown below. Each child node must declare the full logical path to the topmost parent. In the following example, an empty `ParentFilter` must be declared because it's referenced in later nodes. ```xml diff --git a/docs/build/reference/version-version-information.md b/docs/build/reference/version-version-information.md index 9d3cbf2c2c..d4ab8a430e 100644 --- a/docs/build/reference/version-version-information.md +++ b/docs/build/reference/version-version-information.md @@ -1,31 +1,29 @@ --- -description: "Learn more about: /VERSION (Version Information)" -title: "/VERSION (Version Information)" -ms.date: "11/04/2016" +description: "Learn more about: /VERSION (Version information)" +title: "/VERSION (Version information)" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLinkerTool.Version", "/version"] helpviewer_keywords: ["-VERSION linker option", "Version Information linker option", "version numbers, specifying in .exe", "/VERSION linker option", "VERSION linker option"] ms.assetid: b86d0e86-dca6-4316-aee2-d863ccb9f223 --- -# /VERSION (Version Information) +# `/VERSION` (Version information) -``` -/VERSION:major[.minor] -``` +> **`/VERSION:`***`major`*\[*`.minor`*] ## Arguments -*major* and *minor*
-The version number you want in the header of the .exe or .dll file. +*`major`* and *`minor`*
+The version number you want in the header of the EXE or DLL file. ## Remarks -The /VERSION option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN [/HEADERS](headers.md) to see the image version field of the OPTIONAL HEADER VALUES to see the effect of /VERSION. +The **`/VERSION`** option tells the linker to put a version number in the header of the EXE or DLL file. Use [`DUMPBIN /HEADERS`](headers.md) to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. -The *major* and *minor* arguments are decimal numbers in the range 0 through 65,535. The default is version 0.0. +The *`major`* and *`minor`* arguments are decimal numbers in the range 0 through 65,535. The default is version `0.0`. -The information specified with /VERSION does not affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that is used to build the application. See [Version Information Editor](../../windows/version-information-editor.md) for more information. +The information specified with **`/VERSION`** doesn't affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that's used to build the application. For more information, see [Version Information Editor](../../windows/version-information-editor.md). -Another way to insert a version number is with the [VERSION](version-c-cpp.md) module-definition statement. +Another way to insert a version number is with the [`VERSION`](version-c-cpp.md) module-definition statement. ### To set this linker option in the Visual Studio development environment @@ -41,5 +39,5 @@ Another way to insert a version number is with the [VERSION](version-c-cpp.md) m ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/vlen.md b/docs/build/reference/vlen.md new file mode 100644 index 0000000000..6557c219ef --- /dev/null +++ b/docs/build/reference/vlen.md @@ -0,0 +1,52 @@ +--- +description: "Learn more about: /vlen" +title: "/vlen" +ms.date: 09/24/2024 +f1_keywords: ["/vlen", "-vlen"] +helpviewer_keywords: ["specify vector length", "-vlen compiler option [C++]", "vlen compiler option [C++]", "/vlen compiler option [C++]"] +--- +# `/vlen` + +Specifies the vector length for code generation on x86 and x64. For more information about **`/arch`** for x86 and x64, see [`/arch` (x86)](arch-x86.md) and [`/arch` (x64)](arch-x64.md). + +## Syntax + +> **`/vlen=`**\[**`256`**|**`512`**] + +> **`/vlen`** + +## Arguments + +**`/vlen=256`**\ +Specify a vector length of 256 bits for auto-vectorization and other optimizations. + +**`/vlen=512`**\ +Specify a vector length of 512 bits for auto-vectorization and other optimizations. + +**`/vlen`**\ +Specify the default vector length for the selected **`/arch`** setting. + +## Remarks + +If a specific **`/vlen`** value isn't specified, the default vector length depends on the **`/arch`** flag setting. The **`/vlen`** flag can override the default vector length specified by **`/arch:AVX512`** or **`/arch:AVX10.1`** flag. For example: + +- **`/arch:AVX512 /vlen=256`** overrides the default vector length of 512 bits specified by **`/arch:AVX512`** to be 256 bits. +- **`/arch:AVX10.1 /vlen=512`** overrides the default vector length of 256 bits specified by **`/arch:AVX10.1`** to be 512 bits. + +When the specified **`/vlen`** value is incompatible with specified **`/arch`** flag, a warning is generated and default vector length for the **`/arch`** setting is used. For example: + +- **`/arch:AVX2 /vlen=512`** generates a warning because AVX2 doesn't support 512-bit vectors. Vector length of 256 bits is used in this case. + +### To set the `/vlen=256` or `/vlen=512` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In the **Additional options** box, add *`/vlen=256`* or *`/vlen=512`*. Choose **OK** to save your changes. + +## See also + +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/volatile-volatile-keyword-interpretation.md b/docs/build/reference/volatile-volatile-keyword-interpretation.md index e0f9e10d37..8e54521e89 100644 --- a/docs/build/reference/volatile-volatile-keyword-interpretation.md +++ b/docs/build/reference/volatile-volatile-keyword-interpretation.md @@ -17,10 +17,10 @@ Specifies how the [volatile](../../cpp/volatile-cpp.md) keyword is to be interpr ## Arguments **/volatile:iso**
-Selects strict **`volatile`** semantics as defined by the ISO-standard C++ language. Acquire/release semantics are not guaranteed on volatile accesses. If the compiler targets ARM, this is the default interpretation of **`volatile`**. +Selects strict **`volatile`** semantics as defined by the ISO-standard C++ language. Acquire/release semantics are not guaranteed on volatile accesses. If the compiler targets ARM (except ARM64EC), this is the default interpretation of **`volatile`**. **/volatile:ms**
-Selects Microsoft extended **`volatile`** semantics, which add memory ordering guarantees beyond the ISO-standard C++ language. Acquire/release semantics are guaranteed on volatile accesses. However, this option also forces the compiler to generate hardware memory barriers, which might add significant overhead on ARM and other weak memory-ordering architectures. If the compiler targets any platform except ARM, this is default interpretation of **`volatile`**. +Selects Microsoft extended **`volatile`** semantics, which add memory ordering guarantees beyond the ISO-standard C++ language. Acquire/release semantics are guaranteed on volatile accesses. However, this option also forces the compiler to generate hardware memory barriers, which might add significant overhead on ARM and other weak memory-ordering architectures. If the compiler targets ARM64EC or any non-ARM platform, this is default interpretation of **`volatile`**. ## Remarks diff --git a/docs/build/reference/volatile.md b/docs/build/reference/volatile.md new file mode 100644 index 0000000000..fb3cced847 --- /dev/null +++ b/docs/build/reference/volatile.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: /volatileMetadata" +title: "/volatileMetadata (Generate metadata on volatile memory accesses)" +ms.date: 5/30/2024 +f1_keywords: ["/volatileMetadata"] +helpviewer_keywords: ["/volatileMetadata", "-volatileMetadata compiler option", "/volatileMetadata compiler option", "volatileMetadata"] +--- +# `/volatileMetadata` (Generate metadata on volatile memory accesses) + +Generate metadata for volatile memory accesses to improve performance when running x64 code on ARM64. + +## Syntax + +```cpp +/volatileMetadata[-] +``` + +## Arguments + +**`-`**\ +Turns off `/volatileMetadata`. This may result in worse performance when your code runs in emulation mode on ARM64 because the emulator pessimistically assumes that every load/store needs a barrier. + +## Remarks + +Starting with Visual Studio 2019 16.10, `/volatileMetadata` is on by default when generating x64 code. It improves the emulation performance of x64 code on ARM64 by generating metadata that identifies volatile memory addresses. An emulator can use this metadata to improve performance by not using acquire/release semantics on those accesses it knows aren't volatile. Without this metadata, the emulator assumes that all addresses are volatile and uses acquire and release semantics. + +One side effect of `/volatileMetadata` is you may see `npad` macros used in the generated code. This macro expands to a specified number of `NOP` instructions that create an address to associate with a memory barrier. That address is then recorded in the metadata to indicate that acquire/release semantics should be used to access it. + +`/volatileMetadata` is ignored when targeting x86. + +`/volatileMetadata` can be disabled by using `/volatileMetadata-`. + +## Requirements + +Visual Studio 2019 version 16.10 or later. + +## See also + +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/wholearchive-include-all-library-object-files.md b/docs/build/reference/wholearchive-include-all-library-object-files.md index 4a1addad37..dafe4bcd5f 100644 --- a/docs/build/reference/wholearchive-include-all-library-object-files.md +++ b/docs/build/reference/wholearchive-include-all-library-object-files.md @@ -1,8 +1,7 @@ --- description: "Learn more about: /WHOLEARCHIVE (Include All Library Object Files)" title: "/WHOLEARCHIVE (Include All Library Object Files)" -ms.date: "02/12/2020" -ms.assetid: ee92d12f-18af-4602-9683-d6223be62ac9 +ms.date: 03/27/2025 --- # /WHOLEARCHIVE (Include All Library Object Files) @@ -15,26 +14,24 @@ Force the linker to include all object files in the static library in the linked ### Arguments -*library*\ -An optional pathname to a static library. The linker includes every object file from this library. +*`library`*\ +An optional pathname to a static library. The linker includes every object file from this library. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /WHOLEARCHIVE option forces the linker to include every object file from either a specified static library, or if no library is specified, from all static libraries specified to the LINK command. To specify the /WHOLEARCHIVE option for multiple libraries, you can use more than one /WHOLEARCHIVE switch on the linker command line. By default, the linker includes object files in the linked output only if they export symbols referenced by other object files in the executable. The /WHOLEARCHIVE option makes the linker treat all object files archived in a static library as if they were specified individually on the linker command line. +The `/WHOLEARCHIVE` option forces the linker to include every object file from either a specified static library, or if no library is specified, from all static libraries specified to the LINK command. To specify the `/WHOLEARCHIVE` option for multiple libraries, you can use more than one `/WHOLEARCHIVE` switch on the linker command line. By default, the linker includes object files in the linked output only if they export symbols referenced by other object files in the executable. The `/WHOLEARCHIVE` option makes the linker treat all object files archived in a static library as if they were specified individually on the linker command line. -The /WHOLEARCHIVE option can be used to re-export all the symbols from a static library. This allows you to make sure that all of your library code, resources, and metadata are included when you create a component from more than one static library. If you see warning LNK4264 when you create a static library that contains Windows Runtime components for export, use the /WHOLEARCHIVE option when linking that library into another component or app. +The `/WHOLEARCHIVE` option can be used to re-export all the symbols from a static library. This allows you to make sure that all of your library code, resources, and metadata are included when you create a component from more than one static library. If you see warning LNK4264 when you create a static library that contains Windows Runtime components for export, use the `/WHOLEARCHIVE` option when linking that library into another component or app. -The /WHOLEARCHIVE option was introduced in Visual Studio 2015 Update 2. +The `/WHOLEARCHIVE` option was introduced in Visual Studio 2015 Update 2. ### To set this linker option in Visual Studio 1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. - 1. Add the *`/WHOLEARCHIVE`* option to the **Additional Options** text box. ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/winmd-generate-windows-metadata.md b/docs/build/reference/winmd-generate-windows-metadata.md index d87f06e155..4694f1f317 100644 --- a/docs/build/reference/winmd-generate-windows-metadata.md +++ b/docs/build/reference/winmd-generate-windows-metadata.md @@ -24,7 +24,7 @@ The linker generates only the .winmd file, but not the binary executable file. ## Remarks -The **/WINMD** linker option is used for UWP apps and Windows runtime components to control the creation of a Windows Runtime metadata (.winmd) file. A .winmd file is a kind of DLL that contains metadata for Windows runtime types and, in the case of runtime components, the implementations of those types. The metadata follows the [ECMA-335](https://www.ecma-international.org/publications/standards/Ecma-335.htm) standard. +The **/WINMD** linker option is used for UWP apps and Windows runtime components to control the creation of a Windows Runtime metadata (.winmd) file. A .winmd file is a kind of DLL that contains metadata for Windows runtime types and, in the case of runtime components, the implementations of those types. The metadata follows the [ECMA-335](https://ecma-international.org/publications-and-standards/standards/ecma-335/) standard. By default, the output file name has the form *binaryname*.winmd. To specify a different file name, use the [/WINMDFILE](winmdfile-specify-winmd-file.md) option. diff --git a/docs/build/reference/winmdfile-specify-winmd-file.md b/docs/build/reference/winmdfile-specify-winmd-file.md index fb489848b5..69f135c446 100644 --- a/docs/build/reference/winmdfile-specify-winmd-file.md +++ b/docs/build/reference/winmdfile-specify-winmd-file.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: /WINMDFILE (Specify winmd File)" title: "/WINMDFILE (Specify winmd File)" -ms.date: "11/04/2016" +description: "Learn more about: /WINMDFILE (Specify winmd File)" +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.GenerateWindowsMetadataFile"] -ms.assetid: 062b41b3-14d6-432c-a361-fdb66e918931 --- # /WINMDFILE (Specify winmd File) -Specifies the file name for the Windows Runtime Metadata (.winmd) output file that is generated by the [/WINMD](winmd-generate-windows-metadata.md) linker option. +Specifies the filename for the Windows Runtime Metadata (`.winmd`) output file that is generated by the [`/WINMD`](winmd-generate-windows-metadata.md) linker option. ``` /WINMDFILE:filename ``` +## Argument + +*`filename`*\ +The filename for `.winmd` output file. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + ## Remarks -Use the value that is specified in `filename` to override the default .winmd file name (`binaryname`.winmd). Notice that you do not append ".winmd" to `filename`. If multiple values are listed on the **/WINMDFILE** command line, the last one takes precedence. +Use the value that is specified in `filename` to override the default `.winmd` file name (`binaryname`.winmd). Don't append `".winmd"` to `filename`. If multiple values are listed on the **`/WINMDFILE`** command line, the last one takes precedence. The resulting name when combined with `.winmd` must not exceed `MAX_PATH` (260 characters). ### To set this linker option in the Visual Studio development environment @@ -27,6 +31,6 @@ Use the value that is specified in `filename` to override the default .winmd fil ## See also -[/WINMD (Generate Windows Metadata)](winmd-generate-windows-metadata.md)
-[MSVC linker reference](linking.md)
+[`/WINMD` (Generate Windows Metadata)](winmd-generate-windows-metadata.md)\ +[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/wx-treat-linker-warnings-as-errors.md b/docs/build/reference/wx-treat-linker-warnings-as-errors.md index 0d1b027b34..881a1ae174 100644 --- a/docs/build/reference/wx-treat-linker-warnings-as-errors.md +++ b/docs/build/reference/wx-treat-linker-warnings-as-errors.md @@ -1,38 +1,50 @@ --- -description: "Learn more about: /WX (Treat Linker Warnings as Errors)" -title: "/WX (Treat Linker Warnings as Errors)" -ms.date: "11/04/2016" -f1_keywords: ["/WX"] +description: "Learn more about: /WX (Treat linker warnings as errors)" +title: "/WX (Treat linker warnings as errors)" +ms.date: 02/02/2023 +f1_keywords: ["VC.Project.VCLinkerTool.TreatLinkerWarningsAsErrors"] helpviewer_keywords: ["/WX linker option", "-WX linker option", "WX linker option"] ms.assetid: e4ba97c7-93f7-43ae-a4bb-d866790926c9 --- -# /WX (Treat Linker Warnings as Errors) +# `/WX` (Treat linker warnings as errors) -``` -/WX[:NO] -``` +Specifies whether to treat linker warnings as errors. + +## Syntax + +> **`/WX`**\[**`:NO`**]\ +> **`/WX`**\[**`:`***`nnnn`*\[**`,`***`nnnn`*...]] ## Remarks -/WX causes no output file to be generated if the linker generates a warning. +The **`/WX`** linker option causes no output file to be generated if the linker generates a warning. + +This option is similar to **`/WX`** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **`/WX`** for the compilation doesn't imply that **`/WX`** will also be in effect for the link phase; you must explicitly specify **`/WX`** for each tool. -This option is similar to **/WX** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **/WX** for the compilation doesn't imply that **/WX** will also be in effect for the link phase; you must explicitly specify **/WX** for each tool. +In Visual Studio 2022 and later versions, you can specify **`/WX`** with one or more comma-separated *`nnnn`* arguments, where *`nnnn`* is a number between 4000 and 4999. The linker treats the corresponding *`LNKnnnn`* warnings as errors. -By default, **/WX** is not in effect. To treat linker warnings as errors, specify **/WX**. **/WX:NO** is the same as not specifying **/WX**. +By default, **`/WX`** isn't in effect. To treat linker warnings as errors, specify a **`/WX`** option. **`/WX:NO`** is the same as not specifying **`/WX`**, and overrides any previous **`/WX`** linker option. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. To set or unset all warnings as errors, select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Treat Linker Warnings as Errors** property. + +1. To set specific warnings as errors, select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. In the **Additional Options** edit control, add *`/WX:warnings`*, where *`warnings`* is a comma-separated list of linker warning numbers. -1. Enter the option into the **Additional Options** box. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -1. See . +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`/WX` compiler option](./compiler-option-warning-level.md) diff --git a/docs/build/reference/xml-document-generator-tool-property-pages.md b/docs/build/reference/xml-document-generator-tool-property-pages.md index 44c2fc716e..ddcf002fca 100644 --- a/docs/build/reference/xml-document-generator-tool-property-pages.md +++ b/docs/build/reference/xml-document-generator-tool-property-pages.md @@ -1,16 +1,16 @@ --- description: "Learn more about: XML Document Generator Tool Property Pages" title: "XML Document Generator Tool Property Pages" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCXDCMakeTool.ValidateIntelliSense", "VC.Project.VCXDCMakeTool.SuppressStartupBanner", "VC.Project.VCXDCMakeTool.DocumentLibraryDependencies", "VC.Project.VCXDCMakeTool.OutputDocumentFile", "VC.Project.VCXDCMakeTool.AdditionalDocumentFiles"] ms.assetid: 645912b5-197a-4c36-ba58-64df09444ca0 --- # XML Document Generator Tool Property Pages -The XML Document Generator Tool property page exposes the functionality of xdcmake.exe. xdcmake.exe merges .xdc files into an .xml file when your source code contains documentation comments and [/doc (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified,. See [Recommended Tags for Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md) for information on adding documentation comments to source code. +The XML Document Generator Tool property page exposes the functionality of *`xdcmake.exe`*, or XDCMake. XDCMake merges *`.xdc`* files into an *`.xml`* file when your source code contains documentation comments and [`/doc` (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified. For more information on adding documentation comments to source code, see [Recommended tags for documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). > [!NOTE] -> xdcmake.exe options in the development environment (property pages) differ from the options when xdcmake.exe is used at the command line. For information on using xdcmake.exe at the command line, see [XDCMake Reference](xdcmake-reference.md). +> XDCMake options in the development environment (property pages) differ from the options when *`xdcmake.exe`* is used at the command line. For information on using *`xdcmake.exe`* at the command line, see [XDCMake reference](xdcmake-reference.md). ## UIElement List @@ -20,15 +20,15 @@ The XML Document Generator Tool property page exposes the functionality of xdcma - **Additional Document Files** - Additional directories in which you want the project system to look for .xdc files. xdcmake will always look for .xdc files generated by the project. Multiple directories can be specified. + Additional directories in which you want the project system to look for *`.xdc`* files. XDCMake always looks for *`.xdc`* files generated by the project. Multiple directories can be specified. - **Output Document File** - The name and directory location of the .xml output file. See [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md) for information on using macros to specify directory locations. + The name and directory location of the *`.xml`* output file. For more information on using macros to specify directory locations, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). - **Document Library Dependencies** - If your project has a dependency on a .lib project in the solution, you can process .xdc files from the .lib project into the .xml files for the current project. + If your project has a dependency on a *`.lib`* project in the solution, you can process *`.xdc`* files from the *`.lib`* project into the *`.xml`* files for the current project. ## See also diff --git a/docs/build/reference/zc-alignednew.md b/docs/build/reference/zc-alignednew.md index c8a583964a..c591923268 100644 --- a/docs/build/reference/zc-alignednew.md +++ b/docs/build/reference/zc-alignednew.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: /Zc:alignedNew (C++17 over-aligned allocation)" title: "/Zc:alignedNew (C++17 over-aligned allocation)" +description: "Learn more about: /Zc:alignedNew (C++17 over-aligned allocation)" ms.date: "05/18/2019" f1_keywords: ["/Zc:alignedNew"] helpviewer_keywords: ["/Zc:alignedNew", "Zc:alignedNew", "-Zc:alignedNew"] @@ -17,7 +17,7 @@ Enable support for C++17 over-aligned **`new`**, dynamic memory allocation align The MSVC compiler and library support C++17 standard over-aligned dynamic memory allocation. When the **`/Zc:alignedNew`** option is specified, a dynamic allocation such as `new Example;` respects the alignment of `Example` even when it's greater than `max_align_t`, the largest alignment required for any fundamental type. When the alignment of the allocated type is no more than the alignment guaranteed by the original operator **`new`**, available as the value of the predefined macro `__STDCPP_DEFAULT_NEW_ALIGNMENT__`, the statement `new Example;` results in a call to `::operator new(size_t)` as it did in C++14. When the alignment is greater than `__STDCPP_DEFAULT_NEW_ALIGNMENT__`, the implementation instead obtains the memory by using `::operator new(size_t, align_val_t)`. Similarly, deletion of over-aligned types invokes `::operator delete(void*, align_val_t)` or the sized delete signature `::operator delete(void*, size_t, align_val_t)`. -The **`/Zc:alignedNew`** option is only available when [`/std:c++17`](std-specify-language-standard-version.md) or later is enabled. Under **`/std:c++17`** or later, **`/Zc:alignedNew`** is enabled by default to conform to the C++ standard. If the only reason you implement operator **`new`** and **`delete`** is to support over-aligned allocations, you may no longer need this code in C++17 or later modes. To turn off this option and revert to the C++14 behavior of **`new`** and **`delete`** when you use **`/std::c++17`** or later, specify **`/Zc:alignedNew-`**. If you implement operator **`new`** and **`delete`** but you're not ready to implement the over-aligned operator **`new`** and **`delete`** overloads that have the `align_val_t` parameter, use the **`/Zc:alignedNew-`** option to prevent the compiler and Standard Library from generating calls to the over-aligned overloads. The [`/permissive-`](permissive-standards-conformance.md) option doesn't change the default setting of **`/Zc:alignedNew`**. +The **`/Zc:alignedNew`** option is only available when [`/std:c++17`](std-specify-language-standard-version.md) or later is enabled. Under **`/std:c++17`** or later, **`/Zc:alignedNew`** is enabled by default to conform to the C++ standard. If the only reason you implement operator **`new`** and **`delete`** is to support over-aligned allocations, you may no longer need this code in C++17 or later modes. To turn off this option and revert to the C++14 behavior of **`new`** and **`delete`** when you use **`/std:c++17`** or later, specify **`/Zc:alignedNew-`**. If you implement operator **`new`** and **`delete`** but you're not ready to implement the over-aligned operator **`new`** and **`delete`** overloads that have the `align_val_t` parameter, use the **`/Zc:alignedNew-`** option to prevent the compiler and Standard Library from generating calls to the over-aligned overloads. The [`/permissive-`](permissive-standards-conformance.md) option doesn't change the default setting of **`/Zc:alignedNew`**. Support for **`/Zc:alignedNew`** is available starting in Visual Studio 2017 version 15.5. diff --git a/docs/build/reference/zc-check-gwodr.md b/docs/build/reference/zc-check-gwodr.md new file mode 100644 index 0000000000..2bec0383a7 --- /dev/null +++ b/docs/build/reference/zc-check-gwodr.md @@ -0,0 +1,34 @@ +--- +title: "/Zc:zc-checkGwOdr (Enforce Standard C++ ODR violations under /Gw)" +description: "Learn about the Microsoft C++ /Zc:checkGwOdr compiler option for improving C++ standards conformance when using /Gw (Optimize global data)" +ms.date: 08/31/2023 +f1_keywords: ["/Zc:checkGwOdr"] +helpviewer_keywords: ["/Zc:checkGwOdr", "Zc:checkGwOdr", "-Zc:checkGwOdr"] +--- +# `/Zc:checkGwOdr` (Enforce Standard C++ ODR violations under `/Gw`) + +This switch enforces C++ standards conformance when using [`/Gw` (Optimize global data)](gw-optimize-global-data.md). When using `/Gw`, certain One Definition Rule (ODR) violations are ignored. This flag ensures that the appropriate errors are raised. + +## Syntax + +> **`/Zc:checkGwOdr`**\[**`-`**] + +## Remarks + +This switch is off by default. + +To see an example of ODR violations that are ignored when using `/Gw`, see [Standards conformance improvements to /Gw](https://devblogs.microsoft.com/cppblog/standards-conformance-improvements-to-gw-in-visual-studio-version-17-5-preview-2/). + +### To set this compiler option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to include *`/Zc:checkGwOdr`* or *`/Zc:checkGwOdr-`* and then choose **OK**. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[One Definition Rule (ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule)\ +[Standards conformance improvements to /Gw](https://devblogs.microsoft.com/cppblog/standards-conformance-improvements-to-gw-in-visual-studio-version-17-5-preview-2/) diff --git a/docs/build/reference/zc-conformance.md b/docs/build/reference/zc-conformance.md index 10c457b8d1..efa980dbb7 100644 --- a/docs/build/reference/zc-conformance.md +++ b/docs/build/reference/zc-conformance.md @@ -1,12 +1,12 @@ --- title: "/Zc (Conformance)" description: "The /Zc conformance compiler options enable or disable support for conforming or backward-compatible behavior." -ms.date: 12/02/2021 +ms.date: 08/31/2023 helpviewer_keywords: ["/Zc compiler options [C++]", "-Zc compiler options [C++]", "Conformance compiler options", "Zc compiler options [C++]"] --- # `/Zc` (Conformance) -You can use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. +Use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. ## Syntax @@ -22,34 +22,42 @@ Here are the **`/Zc`** compiler options: | Option | Behavior | |--|--| -| [`/Zc:alignedNew`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | -| [`/Zc:auto`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | -| [`/Zc:char8_t`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | -| [`/Zc:__cplusplus`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | -| [`/Zc:externC`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | -| [`/Zc:externConstexpr`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | -| [`/Zc:forScope`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | -| [`/Zc:hiddenFriend`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | -| [`/Zc:implicitNoexcept`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | -| [`/Zc:inline`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | -| [`/Zc:lambda`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | -| [`/Zc:noexceptTypes`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | -| [`/Zc:preprocessor`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | -| [`/Zc:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | -| [`/Zc:rvalueCast`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | -| [`/Zc:sizedDealloc`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | -| [`/Zc:strictStrings`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | -| [`/Zc:static_assert`](zc-static-assert.md) | strict handling of `static_assert` (implied by **`/permissive-`**). | -| [`/Zc:ternary`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | -| [`/Zc:threadSafeInit`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | -| [`/Zc:throwingNew`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | -| [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| [`/Zc:twoPhase`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | -| [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard. Off by default. | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported. Off by default. | +| [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`**. On by default. | +| [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t`. Off by default unless **`/std:c++20`** or later is specified. | +| [`/Zc:checkGwOdr[-]`](zc-check-gwodr.md) | Enforce Standard C++ ODR violations under `/Gw`. | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction. Off by default. | +| [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables. Off by default. | +| [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules. On by default. | +| [`/Zc:gotoScope[-]`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions. On by default. | +| [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only. Off by default. | +| [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. Off by default unless **`/std:c++20`** or later is specified. | +| [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions. Off by default unless **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later is specified. | +| [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor. Off by default unless **`/std:c11`** or later is specified. | +| [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a nonconst lvalue reference. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions. On by default. | +| [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:static_assert[-]`](zc-static-assert.md) | strict handling of `static_assert`. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules. Off by default. | +| [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization. On by default. | +| [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure. Off by default. | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization. On by default. | +| [`/Zc:trigraphs[-]`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | +| [`/Zc:twoPhase-`](zc-twophase.md) | Use nonconforming template parsing behavior (only applicable when **`/permissive-`** is specified, which defaults to conforming). | +| [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef. On by default. | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects. On by default. | For more information about conformance issues in MSVC, see [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ## See also -[MSVC compiler options](compiler-options.md)
+[MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/zc-enumtypes.md b/docs/build/reference/zc-enumtypes.md new file mode 100644 index 0000000000..7c2f590e2f --- /dev/null +++ b/docs/build/reference/zc-enumtypes.md @@ -0,0 +1,88 @@ +--- +description: "Learn more about the /Zc:enumTypes (Enable enum type deduction) compiler option." +title: "/Zc:enumTypes (Enable enum type deduction)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:enumTypes"] +helpviewer_keywords: ["-Zc:enumTypes compiler option (C++)", "/Zc:enumTypes compiler option (C++)"] +--- +# `/Zc:enumTypes` (Enable enum type deduction) + +The **`/Zc:enumTypes`** compiler option enables C++ conforming **`enum`** underlying type and enumerator type deduction. + +## Syntax + +> **`/Zc:enumTypes`**\[**`-`**] + +## Remarks + +The **`/Zc:enumTypes`** compiler option implements Standard C++ conforming behavior for deduction of enumeration base types and the types of enumerators. + +The **`/Zc:enumTypes`** option is new in Visual Studio 2022 version 17.4. This option is off by default, and isn't enabled by **`/permissive-`**. To explicitly disable the option, use **`/Zc:enumTypes-`**. + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. Some enumeration types change size when the conforming **`/Zc:enumTypes`** option is enabled. Certain Windows SDK headers include such enumeration definitions. + +The C++ Standard requires that the underlying type of an enumeration is large enough to hold all enumerators declared in it. Sufficiently large enumerators can set the underlying type of the **`enum`** to **`unsigned int`**, **`long long`**, or **`unsigned long long`**. Previously, such enumeration types always had an underlying type of **`int`** in the Microsoft compiler, regardless of enumerator values. + +The C++ Standard also specifies that, within an enumeration definition that has no fixed underlying type, the types of enumerators are determined by their initializers. Or, for the enumerators with no initializer, by the type of the previous enumerator (accounting for overflow). Previously, such enumerators were always given the deduced type of the enumeration, with a placeholder for the underlying type (typically **`int`**). + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly determine the underlying type of an unscoped enumeration with no fixed base type. The compiler also didn't correctly model the types of enumerators. It could assume an incorrect type in enumerations without a fixed underlying type before the closing brace of the enumeration. Under **`/Zc:enumTypes`**, the compiler correctly implements the standard behavior. + +### Example: Underlying type of unscoped `enum` with no fixed type + +```cpp +enum Unsigned +{ + A = 0xFFFFFFFF // Value 'A' does not fit in 'int'. +}; + +// Previously, this static_assert failed. It passes with /Zc:enumTypes. +static_assert(std::is_same_v, unsigned int>); + +template +void f(T x) +{ +} + +int main() +{ + // Previously called f, now calls f. + f(+A); +} + +// Previously, this enum would have an underlying type of `int`, +// but Standard C++ requires this to have a 64-bit underlying type. +// The /Zc:enumTypes option changes the size of this enum from 4 to 8, +// which could impact binary compatibility with code compiled with an +// earlier compiler version, or without the switch. +enum Changed +{ + X = -1, + Y = 0xFFFFFFFF +}; +``` + +### Example: Enumerators within an `enum` definition with no fixed underlying type + +```cpp +enum Enum { + A = 'A', + B = sizeof(A) +}; + +static_assert(B == 1); // previously failed, now succeeds under /Zc:enumTypes +``` + +In this example the enumerator `A` should have type **`char`** prior to the closing brace of the enumeration, so `B` should be initialized using `sizeof(char)`. Before the **`/Zc:enumTypes`** fix, `A` had enumeration type `Enum` with a deduced underlying type **`int`**, and `B` was initialized using `sizeof(Enum)`, or 4. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:enumTypes`* or *`/Zc:enumTypes-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-externconstexpr.md b/docs/build/reference/zc-externconstexpr.md index c689fee737..ee9c10b502 100644 --- a/docs/build/reference/zc-externconstexpr.md +++ b/docs/build/reference/zc-externconstexpr.md @@ -1,10 +1,9 @@ --- description: "Learn more about: `/Zc:externConstexpr` (Enable extern constexpr variables)" title: "/Zc:externConstexpr (Enable extern constexpr variables)" -ms.date: "02/28/2018" +ms.date: 10/12/2023 f1_keywords: ["/Zc:externConstexpr"] helpviewer_keywords: ["-Zc:externConstexpr compiler option (C++)", "extern constexpr variables (C++)"] -ms.assetid: 4da5e33a-2e4d-4ed2-8616-bd8f43265c27 --- # `/Zc:externConstexpr` (Enable extern constexpr variables) @@ -16,9 +15,13 @@ The **`/Zc:externConstexpr`** compiler option tells the compiler to conform to t ## Remarks -The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. In earlier versions of Visual Studio, and by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. The [`/permissive-`](permissive-standards-conformance.md) option does not enable **`/Zc:externConstexpr`**. +The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. -If a header file contains a variable declared `extern constexpr`, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. +In earlier versions of Visual Studio, by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. + +As of Visual Studio 2022 Update 17.6, the **`/permissive-`** option enables both **`/Zc:externConstexpr`** and [`/Zc:lambda`](zc-lambda.md). In prior versions, **`/permissive-`** didn't enable either one. + +If a header file contains a variable declared **`extern constexpr`**, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. ### To set this compiler option in Visual Studio @@ -30,5 +33,6 @@ If a header file contains a variable declared `extern constexpr`, it must be mar ## See also -[`/Zc` (Conformance)](zc-conformance.md)
-[`auto` Keyword](../../cpp/auto-cpp.md) +[`auto` Keyword](../../cpp/auto-cpp.md)\ +[`permissive`](permissive-standards-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-gotoscope.md b/docs/build/reference/zc-gotoscope.md new file mode 100644 index 0000000000..e71d607142 --- /dev/null +++ b/docs/build/reference/zc-gotoscope.md @@ -0,0 +1,93 @@ +--- +description: "Learn more about the /Zc:gotoScope (Enforce conformance in goto scope) compiler option." +title: "/Zc:gotoScope (Enforce conformance in goto scope)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:gotoScope"] +helpviewer_keywords: ["-Zc:gotoScope compiler option (C++)", "/Zc:gotoScope compiler option (C++)"] +--- +# `/Zc:gotoScope` (Enforce conformance in goto scope) + +The **`/Zc:gotoScope`** compiler option enables checks for Standard C++ behavior around **`goto`** statements that jump over the initialization of local variables. + +## Syntax + +> **`/Zc:gotoScope`**\[**`-`**] + +## Remarks + +The **`/Zc:gotoScope`** compiler option enforces C++ Standard behavior around **`goto`** statements that jump over the initialization of one or more local variables. The compiler emits error [C2362](../../error-messages/compiler-errors-1/compiler-error-c2362.md) in all such cases when **`/Zc:gotoScope`** is specified. The **`/Zc:gotoScope-`** relaxes this check, but the compiler still emits an error if a **`goto`** skips initialization of a local variable that has a non-trivial destructor. + +The intent of the **`/Zc:gotoScope-`** option is to help ease the migration of older code bases to more conformant code. You may use it to suppress certain errors until you've updated the non-conforming code. + +The **`/Zc:gotoScope`** compiler option is new in Visual Studio 2022 version 17.4. The option is off by default. It's enabled automatically by the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check explicitly, add **`/Zc:gotoScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:gotoScope-`** option. The **`/Zc:gotoScope-`** must appear after the **`/permissive-`** option or any option that implies **`/permissive-`**. + +### Example + +This sample generates an error message when compiled using **`/Zc:gotoScope`**: + +```cpp +int g(int*); +bool failed(int); + +int f() { + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + int v2 = v1 + 2; + return v2; +OnError: + return -1; +} + +/* Output: +t.cpp(9): error C2362: initialization of 'v2' is skipped by 'goto OnError' +*/ +``` + +If the code is compiled with **`/Zc:gotoScope-`**, the compiler doesn't emit the error. + +Even when **`/Zc:gotoScope-`** is specified, the compiler still emits an error if the local variable has a non-trivial destructor. For example: + +```cpp +int g(int*); +bool failed(int); + +class S { +public: + S(int); + ~S(); + int mf() const; +}; + +int f() +{ + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + S s(v1); + return s.mf(); + +OnError: + return -1; +} + +/* Output: +t.cpp(17): error C2362: initialization of 's' is skipped by 'goto OnError' +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:gotoScope`* or *`/Zc:gotoScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-inline-remove-unreferenced-comdat.md b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md index 0353c52f35..37f4265cea 100644 --- a/docs/build/reference/zc-inline-remove-unreferenced-comdat.md +++ b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md @@ -1,30 +1,32 @@ --- description: "Learn more about: /Zc:inline (Remove unreferenced COMDAT)" title: "/Zc:inline (Remove unreferenced COMDAT)" -ms.date: "09/05/2019" +ms.date: 06/29/2022 f1_keywords: ["/Zc:inline", "VC.Project.VCCLCompilerTool.RemoveUnreferencedCodeData"] helpviewer_keywords: ["-Zc compiler options (C++)", "/Zc compiler options (C++)", "Zc compiler options (C++)", "/Zc:inline"] ms.assetid: a4c94224-1d73-4bea-a9d5-4fa73dc924df --- -# /Zc:inline (Remove unreferenced COMDAT) +# `/Zc:inline` (Remove unreferenced COMDAT) -Removes unreferenced data or functions that are COMDATs, or that only have internal linkage. Under **/Zc:inline**, the compiler specifies that translation units with inline data or functions must also include their definitions. +Removes unreferenced data or functions that are COMDATs, or that only have internal linkage. Under **`/Zc:inline`**, the compiler specifies that translation units with inline data or functions must also include their definitions. ## Syntax -> **/Zc:inline**[**-**] +> **`/Zc:inline`**[**`-`**] ## Remarks -When **/Zc:inline** is specified, the compiler doesn't emit symbol information for unreferenced COMDAT functions or data. Or, for data or functions that have internal linkage only. This optimization simplifies some of the work the linker does in release builds, or when you specify the [/OPT:REF](opt-optimizations.md) linker option. This compiler optimization can significantly reduce .obj file size and improve linker speeds. The compiler option isn't enabled when you disable optimizations ([/Od](od-disable-debug.md)). Or, when you specify [/GL (Whole Program Optimization)](gl-whole-program-optimization.md). +When **`/Zc:inline`** is specified, the compiler doesn't emit symbol information for unreferenced COMDAT functions or data. Or, for data or functions that have internal linkage only. This optimization simplifies some of the work the linker does in release builds, or when you specify the [`/OPT:REF`](opt-optimizations.md) linker option. This compiler optimization can significantly reduce .obj file size and improve linker speeds. The compiler option isn't enabled when you disable optimizations ([`/Od`](od-disable-debug.md)). Or, when you specify [`/GL` (Whole Program Optimization)](gl-whole-program-optimization.md). -By default, this option is off (**/Zc:inline-**) in command-line builds. The [/permissive-](permissive-standards-conformance.md) option doesn't enable **/Zc:inline**. In MSBuild projects, the option is set by the **Configuration Properties** > **C/C++** > **Language** > **Remove unreferenced code and data** property, which is set to **Yes** by default. +By default, this option is off (**`/Zc:inline-`**) in command-line builds. The [`/permissive-`](permissive-standards-conformance.md) option doesn't enable **`/Zc:inline`**. In MSBuild projects, the option is set by the **Configuration Properties** > **C/C++** > **Language** > **Remove unreferenced code and data** property, which is set to **Yes** by default. -If **/Zc:inline** is specified, the compiler enforces the C++11 requirement that all functions declared **`inline`** must have a definition available in the same translation unit if they are used. When the option is not specified, the Microsoft compiler allows non-conformant code that invokes functions declared **`inline`** even if no definition is visible. For more information, see the C++11 standard, in section 3.2 and section 7.1.2. This compiler option was introduced in Visual Studio 2013 Update 2. +If **`/Zc:inline`** is specified, the compiler enforces the C++11 requirement that all functions declared **`inline`** must have a definition available in the same translation unit if they're used. When the option isn't specified, the Microsoft compiler allows non-conformant code that invokes functions declared **`inline`** even if no definition is visible. For more information, see the C++11 standard, in section 3.2 and section 7.1.2. This compiler option was introduced in Visual Studio 2013 Update 2. -To use the **/Zc:inline** option, update non-conforming code. +To use the **`/Zc:inline`** option, update non-conforming code. -This example shows how the non-conforming use of an inline function declaration without a definition still compiles and links when the default **/Zc:inline-** option is used: +This example shows how the non-conforming use of an inline function declaration without a definition still compiles and links when the default **`/Zc:inline-`** option is used: + +Source file `example.h`: ```cpp // example.h @@ -39,6 +41,8 @@ public: }; ``` +Source file `example.cpp`: + ```cpp // example.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline.cpp example.cpp @@ -55,6 +59,8 @@ void Example::normal_call() { } ``` +Source file `zcinline.cpp`: + ```cpp // zcinline.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline.cpp example.cpp @@ -66,9 +72,11 @@ int main() { } ``` -When **/Zc:inline** is enabled, the same code causes a [LNK2019](../../error-messages/tool-errors/linker-tools-error-lnk2019.md) error, because the compiler does not emit a non-inlined code body for `Example::inline_call` in example.obj. This causes the non-inlined call in `main` to reference an undefined external symbol. +When **`/Zc:inline`** is enabled, the same code causes a [LNK2019](../../error-messages/tool-errors/linker-tools-error-lnk2019.md) error, because the compiler doesn't emit a non-inlined code body for `Example::inline_call` in `example.obj`. The missing code causes the non-inlined call in `main` to reference an undefined external symbol. -To resolve this error, you can remove the **`inline`** keyword from the declaration of `Example::inline_call`, move the definition of `Example::inline_call` into the header file, or move the implementation of `Example` into main.cpp. The next example moves the definition into the header file, where it is visible to any caller that includes the header. +To resolve this error, you can remove the **`inline`** keyword from the declaration of `Example::inline_call`, or move the definition of `Example::inline_call` into the header file, or move the implementation of `Example` into `main.cpp`. The next example moves the definition into the header file, where it's visible to any caller that includes the header. + +Source file `example2.h`: ```cpp // example2.h @@ -86,6 +94,8 @@ public: }; ``` +Source file `example2.cpp`: + ```cpp // example2.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline2.cpp example2.cpp @@ -97,6 +107,8 @@ void Example2::normal_call() { } ``` +Source file `zcinline2.h`: + ```cpp // zcinline2.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline2.cpp example2.cpp @@ -108,7 +120,7 @@ int main() { } ``` -For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +For more information about conformance issues in Visual C++, see [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -120,4 +132,4 @@ For more information about conformance issues in Visual C++, see [Nonstandard Be ## See also -[/Zc (Conformance)](zc-conformance.md)
+[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-lambda.md b/docs/build/reference/zc-lambda.md index 6c2e3080ec..6081969b7c 100644 --- a/docs/build/reference/zc-lambda.md +++ b/docs/build/reference/zc-lambda.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zc:lambda (Enable updated lambda processor)" title: "/Zc:lambda (Enable updated lambda processor)" -ms.date: 08/11/2021 +ms.date: 06/01/2023 f1_keywords: ["/Zc:lambda"] helpviewer_keywords: ["-Zc:lambda compiler option (C++)", "/Zc:lambda compiler option (C++)"] --- @@ -17,7 +17,7 @@ The **`/Zc:lambda`** compiler option enables conforming lambda grammar and proce The **`/Zc:lambda`** compiler option enables the conforming lambda processor. It parses and implements lambda code according to the C++ standard. This option is off by default, which uses the legacy lambda processor. Use this option to enable conformance-mode syntax checks of generic lambdas when you use the default [`/std:c++14`](std-specify-language-standard-version.md) or the [`/std:c++17`](std-specify-language-standard-version.md) compiler options. -**`/Zc:lambda`** is automatically enabled by the [`/std:c++20`](std-specify-language-standard-version.md), [`/std:c++latest`](std-specify-language-standard-version.md), and [`/experimental:module`](experimental-module.md) options. You can disable it explicitly by using **`/Zc:lambda-`**. The [`/permissive-`](permissive-standards-conformance.md) option doesn't enable **`/Zc:lambda`**. +**`/Zc:lambda`** is automatically enabled by the [`/std:c++20`](std-specify-language-standard-version.md), [`/std:c++latest`](std-specify-language-standard-version.md), [`/permissive-`](permissive-standards-conformance.md), and [`/experimental:module`](experimental-module.md) options. You can disable it explicitly by using **`/Zc:lambda-`**. The **`/Zc:lambda`** option is available starting in Visual Studio 2019 version 16.8. It's available as **`/experimental:newLambdaProcessor`** starting in Visual Studio 2019 version 16.3, but this spelling is now deprecated. diff --git a/docs/build/reference/zc-nrvo.md b/docs/build/reference/zc-nrvo.md new file mode 100644 index 0000000000..1248f10e14 --- /dev/null +++ b/docs/build/reference/zc-nrvo.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about the /Zc:nrvo (Control optional NRVO) compiler option." +title: "/Zc:nrvo (Control optional NRVO)" +ms.date: 11/10/2022 +f1_keywords: ["/Zc:nrvo"] +helpviewer_keywords: ["-Zc:nrvo compiler option (C++)", "/Zc:nrvo compiler option (C++)"] +--- +# `/Zc:nrvo` (Control optional NRVO) + +The **`/Zc:nrvo`** compiler option controls Standard C++ optional named return value optimization (NRVO) copy or move elision behavior. + +## Syntax + +> **`/Zc:nrvo`**\[**`-`**] + +## Remarks + +In Visual Studio 2022 version 17.4 and later, you can explicitly enable optional copy or move elision behavior by using the **`/Zc:nrvo`** compiler option. This option is off by default, but is set automatically when you compile using the **`/O2`** option, the **`/permissive-`** option, or **`/std:c++20`** or later. Under **`/Zc:nrvo`**, copy and move elision is performed wherever possible. Optional copy or move elision can also be explicitly disabled by using the **`/Zc:nrvo-`** option. These compiler options only control optional copy or move elision. Mandatory copy or move elision (specified by the C++ Standard) can't be disabled. + +### Mandatory copy and move elision + +The C++ standard requires copy or move elision when the returned value is initialized as part of the return statement. For example, it's required when a function returns an `ExampleType` returned by using `return ExampleType();`. The MSVC compiler always performs copy and move elision for **`return`** statements when it's required, even under **`/Zc:nrvo-`**. + +### Optional copy and move elision + +When a **`return`** statement contains an expression of non-primitive type, its execution copies the expression result into the return slot of the calling function. The compiler invokes the copy or move constructor of the returned type. Then, as the function is exited, destructors for function-local variables are called, which includes any variables named in the expression. + +The C++ standard allows (but doesn't require) the compiler to optionally construct the returned object directly in the return slot of the calling function. This construction skips (or *elides*) the copy or move constructor executed as part of the **`return`** statement. Unlike most other optimizations, this transformation is allowed to have an observable effect on the program's output. Namely, the copy or move constructor and associated destructor are called one less time. The standard still requires that the named returned variable has a defined copy or move constructor, even if the compiler elides the constructor in all cases. + +In versions before Visual Studio 2022 version 17.4, when optimizations are disabled (such as under **`/Od`** or in functions marked `#pragma optimize("", off)`) the compiler only performs mandatory copy and move elision. Under **`/O2`**, the older compilers perform optional copy or move elision on return of a named variable in an optimized function when all of these conditions are met: it has no loops or exception handling, it doesn't return multiple symbols with overlapping lifetimes, the type's copy or move constructor doesn't have default arguments. + +Visual Studio 2022 version 17.4 increases the number of places where the compiler does optional copy or move elisions under **`/Zc:nrvo`**, whether enabled explicitly, or automatically by using the **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later options. Under **`/Zc:nrvo`**, the compiler performs optional copy or move elision on return of a named variable for any function when: it has no loops or exception handling (as before); it returns the variable from a loop; it has exception handling; the returned type's copy or move constructor has default arguments. Optional copy or move elisions are never done when **`/Zc:nrvo-`** is applied, or when the function returns multiple symbols with overlapping lifetimes, or for a throw of a named variable. + +For more information and examples of mandatory and optional copy elision under **`/Zc:nrvo`**, see [Improving Copy and Move Elision](https://devblogs.microsoft.com/cppblog/improving-copy-and-move-elision) in the C++ Team Blog. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:nrvo`* or *`/Zc:nrvo-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/O2`](./o1-o2-minimize-size-maximize-speed.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-preprocessor.md b/docs/build/reference/zc-preprocessor.md index 6e8587f90a..fd8708017a 100644 --- a/docs/build/reference/zc-preprocessor.md +++ b/docs/build/reference/zc-preprocessor.md @@ -1,8 +1,8 @@ --- title: "/Zc:preprocessor (Enable preprocessor conformance mode)" description: "Use the /Zc:preprocessor compiler option to enable compiler support for a standard conforming preprocessor." -ms.date: 09/10/2020 -f1_keywords: ["preprocessor", "/Zc:preprocessor"] +ms.date: 02/17/2022 +f1_keywords: ["preprocessor", "/Zc:preprocessor", "VC.Project.VCCLCompilerTool.PreprocessorStandard"] helpviewer_keywords: ["preprocessor conformance", "/Zc:preprocessor", "Enable preprocessor conformance mode"] --- # `/Zc:preprocessor` (Enable preprocessor conformance mode) @@ -11,7 +11,7 @@ This option enables a token-based preprocessor that conforms to C99 and C++11 an ## Syntax -> **`/Zc:preprocessor`**[**-**] +> **`/Zc:preprocessor`**[**`-`**] ## Remarks @@ -23,9 +23,9 @@ The **`/Zc:preprocessor`** option is available starting in Visual Studio 2019 ve 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. -1. Modify the **Additional Options** property to include *`/Zc:preprocessor`* and then choose **OK**. +1. Modify the **Use Standard Conforming Preprocessor** property and then choose **OK**. ## See also diff --git a/docs/build/reference/zc-static-assert.md b/docs/build/reference/zc-static-assert.md index 78276252a8..9eb98b94a5 100644 --- a/docs/build/reference/zc-static-assert.md +++ b/docs/build/reference/zc-static-assert.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zc:static_assert (Strict static_assert handling)" title: "/Zc:static_assert (Strict static_assert handling)" -ms.date: 12/15/2021 +ms.date: 1/15/2025 f1_keywords: ["/Zc:static_assert"] helpviewer_keywords: ["/Zc:static_assert compiler option (C++)"] --- @@ -16,7 +16,9 @@ The **`/Zc:static_assert`** compiler option tells the compiler to evaluate `stat ## Remarks -The **`/Zc:static_assert`** compiler option tells the compiler to evaluate a `static_assert` in the body of a function template or in the body of a class template member function when first parsed, if the test expression isn't dependent. If the non-dependent test expression isn't `false`, the compiler emits an error immediately. When the test expression is dependent, the `static_assert` isn't evaluated until the template is instantiated. +Starting with Visual Studio 17.10, `/Zc:static_assert` and `/Zc:static_assert-` have no effect. Both options are ignored to avoid breaking builds that use them. `static_assert` is now never evaluated when parsing class or function templates. + +The **`/Zc:static_assert`** compiler option tells the compiler to evaluate a `static_assert` in the body of a function template or in the body of a class template member function when first parsed, if the test expression isn't dependent. If the non-dependent test expression is `false`, the compiler emits an error immediately. When the test expression is dependent, the `static_assert` isn't evaluated until the template is instantiated. The **`/Zc:static_assert`** option is available starting in Visual Studio 2022 version 17.1. In earlier versions of Visual Studio, or if **`/Zc:static_assert-`** is specified, Visual Studio doesn't do dependent analysis if the `static_assert` is within the body of a function template or within the body of a member function of a class template. Instead, it only evaluates the `static_assert` when a template is instantiated. diff --git a/docs/build/reference/zc-stdc.md b/docs/build/reference/zc-stdc.md new file mode 100644 index 0000000000..7a55aafc98 --- /dev/null +++ b/docs/build/reference/zc-stdc.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about the /Zc:__STDC__ (Enable __STDC__ macro) compiler option." +title: "/Zc:__STDC__ (Enable __STDC__ macro)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:__STDC__"] +helpviewer_keywords: ["-Zc:__STDC__ compiler option (C++)", "/Zc:__STDC__ compiler option (C++)"] +--- +# `/Zc:__STDC__` (Enable `__STDC__` macro) + +The **`/Zc:__STDC__`** compiler option defines the built-in `__STDC__` preprocessor macro as 1 in C code. + +## Syntax + +> **`/Zc:__STDC__`** + +## Remarks + +The **`/Zc:__STDC__`** compiler option implements Standard C conforming behavior for the `__STDC__` preprocessor macro, setting it to 1 when compiling C11 and C17 code. + +The **`/Zc:__STDC__`** option is new in Visual Studio 2022 version 17.2. This option is off by default, but can be enabled explicitly when **`/std:c11`** or **`/std:c17`** is specified. There's no negative version of the option. + +This option is a source breaking change. Due to the behavior of the UCRT, which doesn't expose POSIX functions when `__STDC__` is `1`, it isn't possible to define this macro for C by default without introducing breaking changes to the stable language versions. + +### Example + +```c +// test__STDC__.c +#include +#include +#include + +int main() { +#if __STDC__ + int f = _open("file.txt", _O_RDONLY); + _close(f); +#else + int f = open("file.txt", O_RDONLY); + close(f); +#endif +} + +/* Command line behavior + +C:\Temp>cl /EHsc /W4 /Zc:__STDC__ test__STDC__.c && test__STDC__ + +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:__STDC__`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-templatescope.md b/docs/build/reference/zc-templatescope.md new file mode 100644 index 0000000000..a6ca453833 --- /dev/null +++ b/docs/build/reference/zc-templatescope.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about the /Zc:templateScope (Check template parameter shadowing) compiler option." +title: "/Zc:templateScope (Check template parameter shadowing)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:templateScope"] +helpviewer_keywords: ["-Zc:templateScope compiler option (C++)", "/Zc:templateScope compiler option (C++)"] +--- +# `/Zc:templateScope` (Check template parameter shadowing) + +The **`/Zc:templateScope`** compiler option enables checks for Standard C++ behavior around shadowing of template parameters. + +## Syntax + +> **`/Zc:templateScope`**\[**`-`**] + +## Remarks + +The C++ Standard doesn't allow the reuse of a template parameter's name (or *shadowing*) for another declaration within the scope of the template. The **`/Zc:templateScope`** compiler option enables an error check for such shadowing. + +The **`/Zc:templateScope`** option is new in Visual Studio 2022 version 17.5 preview 1. The option is off by default even when the code is compiled using the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check, you must explicitly add **`/Zc:templateScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:templateScope-`** option. + +### Example + +Under **`/Zc:templateScope`**, this sample code produces an error: + +```cpp +template +void f(T&& t) { + int T = 13; +} + +/* Output: +t.cpp(3): error C7527: 'T': a template parameter name cannot be reused within its scope +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:templateScope`* or *`/Zc:templateScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-ternary.md b/docs/build/reference/zc-ternary.md index 61d8b6a058..b77f0d7739 100644 --- a/docs/build/reference/zc-ternary.md +++ b/docs/build/reference/zc-ternary.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" title: "/Zc:ternary (Enforce conditional operator rules)" -ms.date: "09/12/2019" +description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" +ms.date: 09/12/2019 f1_keywords: ["/Zc:ternary"] helpviewer_keywords: ["/Zc:ternary", "Zc:ternary", "-Zc:ternary"] --- @@ -23,7 +23,7 @@ The **`/Zc:ternary`** option is off by default in Visual Studio 2017. Use **`/Zc ### Examples -This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **/`Zc:ternary`** or **`/permissive-`** is specified. +This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **`/Zc:ternary`** or **`/permissive-`** is specified. ```cpp // zcternary1.cpp diff --git a/docs/build/reference/zc-tlsguards.md b/docs/build/reference/zc-tlsguards.md new file mode 100644 index 0000000000..15c36abf13 --- /dev/null +++ b/docs/build/reference/zc-tlsguards.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:tlsGuards (Check TLS initialization)" +description: "Learn more about the /Zc:tlsGuards (Check TLS initialization) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:tlsGuards"] +helpviewer_keywords: ["-Zc:tlsGuards compiler option (C++)", "/Zc:tlsGuards compiler option (C++)"] +--- +# `/Zc:tlsGuards` (Check TLS initialization) + +The **`/Zc:tlsGuards`** compiler option generates runtime checks for thread local storage (TLS) initialization in DLLs. + +## Syntax + +> **`/Zc:tlsGuards`**\[**`-`**] + +## Remarks + +The **`/Zc:tlsGuards`** compiler option enables checks for initialization of thread-local variables in DLLs. Previously, thread-local variables in DLLs weren't correctly initialized. Other than on the thread that loaded the DLL, they weren't initialized before first use on threads that existed before the DLL was loaded. The **`/Zc:tlsGuards`** option enables code that corrects this defect. Thread-local variables in such a DLL get initialized immediately before their first use on such threads. + +The **`/Zc:tlsGuards`** option is new in Visual Studio 2019 version 16.5. This option is on by default in all compiler modes. The new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. To disable checks for specific thread-local variables, use the [`[[msvc::no_tls_guard]]`](../../cpp/attributes.md) attribute. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:tlsGuards`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-twophase.md b/docs/build/reference/zc-twophase.md index d4e1d5506b..5675256313 100644 --- a/docs/build/reference/zc-twophase.md +++ b/docs/build/reference/zc-twophase.md @@ -1,29 +1,29 @@ --- title: "/Zc:twoPhase- (disable two-phase name lookup)" description: "Explains how /Zc:twoPhase- disables two-phase name lookup when /permissive- is specified." -ms.date: "12/03/2019" +ms.date: 09/27/2022 f1_keywords: ["twoPhase", "/Zc:twoPhase"] helpviewer_keywords: ["twoPhase", "disable two-phase name lookup", "/Zc:twoPhase"] --- -# /Zc:twoPhase- (disable two-phase name lookup) +# `/Zc:twoPhase-` (disable two-phase name lookup) -The **/Zc:twoPhase-** option, under **/permissive-**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. +The **`/Zc:twoPhase-`** option, under **`/permissive-`**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. ## Syntax -> **/Zc:twoPhase-** +> **`/Zc:twoPhase-`** ## Remarks -Visual Studio 2017 version 15.3 and later: Under [/permissive-](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **/Zc:twoPhase-**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **/permissive-** isn't specified, the non-conforming behavior is the default. +Visual Studio 2017 version 15.3 and later: Under [`/permissive-`](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **`/Zc:twoPhase-`**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **`/permissive-`** isn't specified, the non-conforming behavior is the default. -The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **/Zc:twoPhase-** is required to compile code for those SDK versions when you use **/permissive-**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **/Zc:twoPhase-** option. +The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **`/Zc:twoPhase-`** is required to compile code for those SDK versions when you use **`/permissive-`**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **`/Zc:twoPhase-`** option. -Use **/Zc:twoPhase-** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. +Use **`/Zc:twoPhase-`** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. -### Compiler behavior under /Zc:twoPhase- +### Compiler behavior under `/Zc:twoPhase-` -By default, or in Visual Studio 2017 version 15.3 and later when you specify both **/permissive-** and **/Zc:twoPhase-**, the compiler uses this behavior: +By default, or in Visual Studio 2017 version 15.3 and later when you specify both **`/permissive-`** and **`/Zc:twoPhase-`**, the compiler uses this behavior: - It parses only the template declaration, the class head, and the base class list. The template body is captured as a token stream. No function bodies, initializers, default arguments, or noexcept arguments are parsed. The class template is pseudo-instantiated on a tentative type to validate that the declarations in the class template are correct. Consider this class template: @@ -33,7 +33,7 @@ By default, or in Visual Studio 2017 version 15.3 and later when you specify bot The template declaration, `template `, the class head `class Derived`, and the base-class list `public Base` are parsed, but the template body is captured as a token stream. -- When parsing a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. +- When it parses a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. As a result, if the template body has syntax errors, but the template never gets instantiated, the compiler doesn't diagnose the errors. @@ -65,7 +65,7 @@ int main() } ``` -Here's the output when you use the default mode, conformance mode, and conformance mode with **/Zc:twoPhase-** compiler options: +Here's the output when you use the default mode, conformance mode, and conformance mode with **`/Zc:twoPhase-`** compiler options: ```cmd C:\Temp>cl /EHsc /nologo /W4 zctwophase.cpp && zctwophase @@ -81,11 +81,11 @@ zctwophase.cpp Microsoft one-phase ``` -When compiled in conformance mode under **/permissive-**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **/Zc:twoPhase-**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **/permissive-**. +When compiled in conformance mode under **`/permissive-`**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **`/Zc:twoPhase-`**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **`/permissive-`**. -*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **/Zc:twoPhase-**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Additional overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. +*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **`/Zc:twoPhase-`**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Other overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. -Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **/Zc:twoPhase-**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. +Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **`/Zc:twoPhase-`**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. Here's another example: @@ -118,28 +118,28 @@ int main() { } ``` -When compiled without **/permissive-**, this code prints: +When compiled without **`/permissive-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -When compiled with **/permissive-**, but without **/Zc:twoPhase-**, this code prints: +When compiled with **`/permissive-`**, but without **`/Zc:twoPhase-`**, this code prints: ```Output func(long) NS::func(NS::S) ``` -When compiled with both **/permissive-** and **/Zc:twoPhase-**, this code prints: +When compiled with both **`/permissive-`** and **`/Zc:twoPhase-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -In conformance mode under **/permissive-**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **/Zc:twoPhase-**. That's because the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the template function. +In conformance mode under **`/permissive-`**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **`/Zc:twoPhase-`**. The reason is, the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the function template. ### Update your code for two-phase conformance @@ -151,7 +151,7 @@ A conforming compiler parses `Foo` as a variable in the scope of `T`, meaning th `T::template Foo(c);` -In versions Visual Studio 2017 version 15.3 and later, when **/permissive-** and **/Zc:twoPhase-** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. +In versions Visual Studio 2017 version 15.3 and later, when **`/permissive-`** and **`/Zc:twoPhase-`** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. This behavior can also be seen by eliminating the keyword **`typename`** before names in function template bodies, initializers, default arguments, and noexcept arguments. For example: @@ -163,7 +163,7 @@ typename T::TYPE func(typename T::TYPE*) } ``` -If you don't use the keyword **`typename`** in the function body, this code compiles under **/permissive- /Zc:twoPhase-**, but not under **/permissive-** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **/Zc:twoPhase-**, the compiler does't require the keyword. In **/permissive-** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. +If you don't use the keyword **`typename`** in the function body, this code compiles under **`/permissive- /Zc:twoPhase-`**, but not under **`/permissive-`** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **`/Zc:twoPhase-`**, the compiler doesn't require the keyword. In **`/permissive-`** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. Similarly, consider this code sample: @@ -175,9 +175,9 @@ typename T::template X::TYPE func(typename T::TYPE) } ``` -Under **/permissive- /Zc:twoPhase-** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. +Under **`/permissive- /Zc:twoPhase-`** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. -For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -185,8 +185,8 @@ For more information about conformance issues, see [C++ conformance improvements 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include **/Zc:twoPhase-** and then choose **OK**. +1. Modify the **Additional Options** property to include *`/Zc:twoPhase-`* and then choose **OK**. ## See also -[/Zc (Conformance)](zc-conformance.md) +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-zerosizearraynew.md b/docs/build/reference/zc-zerosizearraynew.md new file mode 100644 index 0000000000..05abb101da --- /dev/null +++ b/docs/build/reference/zc-zerosizearraynew.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" +description: "Learn more about the /Zc:zeroSizeArrayNew (Call member new/delete on arrays) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:zeroSizeArrayNew"] +helpviewer_keywords: ["-Zc:zeroSizeArrayNew compiler option (C++)", "/Zc:zeroSizeArrayNew compiler option (C++)"] +--- +# `/Zc:zeroSizeArrayNew` (Call member new/delete on arrays) + +The **`/Zc:zeroSizeArrayNew`** compiler option calls member `new` and `delete` for zero-length arrays of objects. + +## Syntax + +> **`/Zc:zeroSizeArrayNew`**\[**`-`**] + +## Remarks + +The **`/Zc:zeroSizeArrayNew`** compiler option enables calls to member `new` and `delete` for zero-length arrays of objects of class types with virtual destructors. This behavior conforms to the standard. This compiler option is new in Visual Studio 2019 version 16.9 and is enabled by default in all compiler modes. Previously, in code compiled by versions before Visual Studio 2019 version 16.9, the compiler invoked global `new` and `delete` on zero-length arrays of objects of class types with virtual destructors. + +The **`/Zc:zeroSizeArrayNew`** option may cause a breaking change in code that relied on the previous non-conforming behavior. To restore the previous behavior, use the **`/Zc:zeroSizeArrayNew-`** compiler option. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:zeroSizeArrayNew`* or *`/Zc:zeroSizeArrayNew-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zh.md b/docs/build/reference/zh.md index 728569bc3c..3cefaf8e71 100644 --- a/docs/build/reference/zh.md +++ b/docs/build/reference/zh.md @@ -1,48 +1,50 @@ --- title: "/ZH (Hash algorithm for calculation of file checksum in debug info)" description: "Use the /ZH compiler option to enable MD5, SHA-1, or SHA-256 source file checksums in debug info" -ms.date: "09/16/2019" +ms.date: 02/01/2022 f1_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256"] helpviewer_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256", "/ZH compiler option", "/ZH:MD5 compiler option", "/ZH:SHA1 compiler option", "/ZH:SHA_256 compiler option", "Hash algorithm for file checksum in debug info"] --- -# /ZH (Hash algorithm for calculation of file checksum in debug info) +# `/ZH` (Hash algorithm for calculation of file checksum in debug info) Specifies which cryptographic hash algorithm to use to generate a checksum of each source file. ## Syntax -> **/ZH:**{**MD5**|**SHA1**|**SHA_256**} +> **`/ZH:MD5`**\ +> **`/ZH:SHA1`**\ +> **`/ZH:SHA_256`** ## Arguments -**/ZH:MD5**\ -Use an MD5 hash for the checksum. This option is the default. +**`/ZH:MD5`**\ +Use an MD5 hash for the checksum. This option is the default in Visual Studio 2019. -**/ZH:SHA1**\ +**`/ZH:SHA1`**\ Use an SHA-1 hash for the checksum. -**/ZH:SHA_256**\ -Use an SHA-256 hash for the checksum. +**`/ZH:SHA_256`**\ +Use an SHA-256 hash for the checksum. This option is the default in Visual Studio 2022 version 17.0 and later. ## Remarks -PDB files store a checksum for each source file compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. By default, the compiler uses an MD5 hash to generate the checksum. You can specify this option explicitly by using the **/ZH:MD5** option. +PDB files store a checksum for each source file, compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. By default, in Visual Studio 2019 the compiler uses an MD5 hash to generate the checksum. To specify this hash algorithm explicitly, use the **`/ZH:MD5`** option. -Because of a risk of collision problems in MD5 and SHA-1, Microsoft recommends you use the **/ZH:SHA_256** option. The SHA-256 hash may result in a small increase in compile times. +Because of a risk of collision problems in MD5 and SHA-1, Microsoft recommends you use the **`/ZH:SHA_256`** option. The SHA-256 hash might result in a small increase in compile times. The **`/ZH:SHA_256`** option is the default in Visual Studio 2022 version 17.0 and later. -When more than one **/ZH** option is specified, the last option is used. +When more than one **`/ZH`** option is specified, the last option is used. -The **/ZH** option is available starting in Visual Studio 2019 version 16.4. +The **`/ZH`** option is available in Visual Studio 2019 version 16.4 and later. ### To set this compiler option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Set the **Configuration** drop-down to **All Configurations**. +1. Set the **Configuration** drop-down to **All Configurations**. Set the **Platform** drop-down to **All Platforms**. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional options** property to add a **/ZH:MD5**, **/ZH:SHA1**, or **/ZH:SHA_256** option, and then choose **OK**. +1. Modify the **Additional options** property to add a **`/ZH:MD5`**, **`/ZH:SHA1`**, or **`/ZH:SHA_256`** option, and then choose **OK**. ## See also diff --git a/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md b/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md index 0eef814ed4..f587fd78fd 100644 --- a/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md +++ b/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md @@ -1,49 +1,47 @@ --- -description: "Learn more about: /Zm (Specify Precompiled Header Memory Allocation Limit)" -title: "/Zm (Specify Precompiled Header Memory Allocation Limit)" -ms.date: "03/08/2019" -f1_keywords: ["/zm"] +description: "Learn more about: /Zm (Specify precompiled header memory allocation limit)" +title: "/Zm (Specify precompiled header memory allocation limit)" +ms.date: 02/22/2022 +f1_keywords: ["/Zm"] helpviewer_keywords: ["PCH files, memory allocation limit", "Zm compiler option [C++]", "/Zm compiler option [C++]", "precompiled header files, memory allocation limit", "Specify Precompiled Header Memory Allocation Limit compiler option", "cl.exe compiler, memory allocation limit", ".pch files, memory allocation limit", "memory allocation, Memory Allocation Limit compiler option", "-Zm compiler option [C++]"] ms.assetid: 94c77d5e-6672-46a7-92e0-3f69e277727d --- -# /Zm (Specify Precompiled Header Memory Allocation Limit) +# `/Zm` (Specify precompiled header memory allocation limit) Determines the amount of memory that the compiler allocates to construct precompiled headers. ## Syntax -``` -/Zmfactor -``` +> **`/Zm`***`factor`* ## Arguments -*factor*
-A scaling factor that determines the amount of memory that the compiler uses to construct precompiled headers. +*`factor`*
+A scaling factor percentage that determines the amount of memory that the compiler uses to construct precompiled headers. -The *factor* argument is a percentage of the default size of a compiler-defined work buffer. The default value of *factor* is 100 (percent), but you can specify larger or smaller amounts. +The *`factor`* argument is a percentage of the default size of a compiler-defined work buffer. The default value of *`factor`* is 100 (percent), but you can specify larger or smaller amounts. ## Remarks -In versions before Visual Studio 2015, the C++ compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and allows the precompiled header to comprise multiple address ranges. Consequently, the **/Zm** compiler option is rarely necessary. +In versions before Visual Studio 2015, the C++ compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and allows the precompiled header to comprise multiple address ranges. Now, the **`/Zm`** compiler option is rarely necessary. -If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **/Zm** compiler option, you might have reserved too much memory. Consider removing the **/Zm** option. +If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **`/Zm`** compiler option, you might have reserved too much memory. Consider removing the **`/Zm`** option. -If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *factor* argument to use when you recompile by using the **/Zm** compiler option. This message is only significant when a precompiled header uses `#pragma hdrstop`. In other cases, it is a spurious error caused by Windows virtual memory pressure issues, and the recommendation to use the **/Zm** option should be ignored. Instead, consider reducing the number of parallel processes when using the **/maxcpucount** option to MSBUILD.EXE in conjunction with the **/MP** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/). +If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *`factor`* argument to use when you recompile by using the **`/Zm`** compiler option. This message is only significant when a precompiled header uses `#pragma hdrstop`. In other cases, it's a spurious error caused by Windows virtual memory pressure issues, and the recommendation to use the **`/Zm`** option should be ignored. Instead, consider reducing the number of parallel processes when using the **`/maxcpucount`** option to MSBUILD.EXE together with the **`/MP`** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/). -The following table shows how the *factor* argument affects the memory allocation limit if you assume the size of the default precompiled header buffer is 75 MB. +The following table shows how the *`factor`* argument affects the memory allocation limit. In the table, we assume the size of the default precompiled header buffer is 75 MB. -|Value of *factor*|Memory allocation limit| -|-----------------------|-----------------------------| -|10|7.5 MB| -|100|75 MB| -|200|150 MB| -|1000|750 MB| -|2000|1500 MB| +| Value of *`factor`* | Memory allocation limit | +|--|--| +| 10 | 7.5 MB | +| 100 | 75 MB | +| 200 | 150 MB | +| 1000 | 750 MB | +| 2000 | 1500 MB | -## Other Ways to Set the Memory Allocation Limit +## Other ways to set the memory allocation limit -### To set the /Zm compiler option in the Visual Studio development environment +### To set the `/Zm` compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -51,11 +49,11 @@ The following table shows how the *factor* argument affects the memory allocatio 1. Enter the **/Zm** compiler option in the **Additional Options** box. -### To set the /Zm compiler option programmatically +### To set the `/Zm` compiler option programmatically - See . ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/zo-enhance-optimized-debugging.md b/docs/build/reference/zo-enhance-optimized-debugging.md index c698def89f..c4ff8c18fa 100644 --- a/docs/build/reference/zo-enhance-optimized-debugging.md +++ b/docs/build/reference/zo-enhance-optimized-debugging.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zo (Enhance Optimized Debugging)" title: "/Zo (Enhance Optimized Debugging)" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["-Zo", "/Zo"] helpviewer_keywords: ["Zo compiler option [C++]", "/Zo compiler option [C++]", "-Zo compiler option [C++]"] ms.assetid: eea8d89a-7fe0-4fe1-86b2-7689bbebbd7f @@ -12,17 +12,17 @@ Generate enhanced debugging information for optimized code in non-debug builds. ## Syntax -```cpp -/Zo[-] -``` +> **`/Zo`**\[**`-`**] ## Remarks -The **/Zo** compiler switch generates enhanced debugging information for optimized code. Optimization may use registers for local variables, reorder code, vectorize loops, and inline function calls. These optimizations can obscure the relationship between the source code and the compiled object code. The **/Zo** switch tells the compiler to generate additional debugging information for local variables and inlined functions. Use it to see variables in the **Autos**, **Locals**, and **Watch** windows when you step through optimized code in the Visual Studio debugger. It also enables stack traces to show inlined functions in the WinDBG debugger. Debug builds that have disabled optimizations ([/Od](od-disable-debug.md)) do not need the additional debugging information generated when **/Zo** is specified. Use the **/Zo** switch to debug Release configurations with optimization turned on. For more information on optimization switches, see [/O Options (Optimize Code)](o-options-optimize-code.md). The **/Zo** option is enabled by default in Visual Studio when you specify debugging information with **/Zi** or **/Z7**. Specify **/Zo-** to explicitly disable this compiler option. +The **`/Zo`** compiler option generates enhanced debugging information for optimized code. Optimization may use registers for local variables, reorder code, vectorize loops, and inline function calls. These optimizations can obscure the relationship between the source code and the compiled object code. The **`/Zo`** option tells the compiler to generate extra debugging information for local variables and inlined functions. It allows you to see variables in the **Autos**, **Locals**, and **Watch** windows when you step through optimized code in the Visual Studio debugger. It also enables stack traces to show inlined functions in the WinDBG debugger. Debug builds that have disabled optimizations ([`/Od`](od-disable-debug.md)) don't need the extra debugging information generated when **`/Zo`** is specified. Use the **`/Zo`** option to debug Release configurations with optimization turned on. For more information on optimization options, see [`/O` options (Optimize Code)](o-options-optimize-code.md). -The **/Zo** switch is available starting in Visual Studio 2013 Update 3, and it replaces the previously undocumented **/d2Zi+** switch. +The **`/Zo`** option is enabled by default when you specify debugging information with **`/Zi`** or **`/Z7`**. It's disabled by the **`/ZI`** compiler option. Specify **`/Zo-`** to explicitly disable this compiler option. -### To set the /Zo compiler option in Visual Studio +The **`/Zo`** option is available starting in Visual Studio 2013 Update 3, and it replaces the previously undocumented **`/d2Zi+`** option. + +### To set the `/Zo` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -36,6 +36,6 @@ The **/Zo** switch is available starting in Visual Studio 2013 Update 3, and it ## See also -[/O Options (Optimize Code)](o-options-optimize-code.md)
-[/Z7, /Zi, /ZI (Debug Information Format)](z7-zi-zi-debug-information-format.md)
+[`/O` Options (Optimize code)](o-options-optimize-code.md)\ +[`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md)\ [Edit and Continue](/visualstudio/debugger/edit-and-continue) diff --git a/docs/build/reference/zp-struct-member-alignment.md b/docs/build/reference/zp-struct-member-alignment.md index 6a8e4d9370..cfb89975b2 100644 --- a/docs/build/reference/zp-struct-member-alignment.md +++ b/docs/build/reference/zp-struct-member-alignment.md @@ -26,7 +26,7 @@ The available packing values are described in the following table: |2|Packs structures on 2-byte boundaries.| |4|Packs structures on 4-byte boundaries.| |8|Packs structures on 8-byte boundaries (default for x86, ARM, and ARM64).| -|16| Packs structures on 16-byte boundaries (default for x64).| +|16| Packs structures on 16-byte boundaries (default for x64 and ARM64EC).| Don't use this option unless you have specific alignment requirements. diff --git a/docs/build/reference/zw-windows-runtime-compilation.md b/docs/build/reference/zw-windows-runtime-compilation.md index b93a6d5745..6bba2c712c 100644 --- a/docs/build/reference/zw-windows-runtime-compilation.md +++ b/docs/build/reference/zw-windows-runtime-compilation.md @@ -1,16 +1,16 @@ --- description: "Learn more about: /ZW (Windows Runtime Compilation)" title: "/ZW (Windows Runtime Compilation)" -ms.date: "04/08/2019" +ms.date: 06/22/2023 f1_keywords: ["VC.Project.VCCLCompilerTool.CompileAsWinRT", "/zw"] helpviewer_keywords: ["/ZW", "-ZW compiler option", "/ZW compiler option", "-ZW", "Windows Runtime compiler option"] -ms.assetid: 0fe362b0-9526-498b-96e0-00d7a965a248 --- -# /ZW (Windows Runtime Compilation) +# `/ZW` (Windows Runtime Compilation) Compiles source code to support Microsoft C++ component extensions C++/CX for the creation of Universal Windows Platform (UWP) apps. -When you use **/ZW** to compile, always specify **/EHsc** as well. +When you use **`/ZW`** to compile, always specify **`/EHsc`** as well.\ +**`/ZW`** isn't compatible with **`/std:c++20`**. ## Syntax @@ -21,18 +21,18 @@ When you use **/ZW** to compile, always specify **/EHsc** as well. ## Arguments -**nostdlib**
-Indicates that Platform.winmd, Windows.Foundation.winmd, and other default Windows metadata (.winmd) files are not automatically included in the compilation. Instead, you must use the [/FU (Name Forced #using File)](fu-name-forced-hash-using-file.md) compiler option to explicitly specify Windows metadata files. +**`nostdlib`**\ +Indicates that `Platform.winmd`, `Windows.Foundation.winmd`, and other default Windows metadata (`.winmd`) files aren't automatically included in the compilation. Instead, you must use the [`/FU` (Name Forced #using File)](fu-name-forced-hash-using-file.md) compiler option to explicitly specify Windows metadata files. ## Remarks -When you specify the **/ZW** option, the compiler supports these features: +When you specify the **`/ZW`** option, the compiler supports these features: - The required metadata files, namespaces, data types, and functions that your app requires to execute in the Windows Runtime. - Automatic reference-counting of Windows Runtime objects, and automatic discarding of an object when its reference count goes to zero. -Because the incremental linker does not support the Windows metadata included in .obj files by using the **/ZW** option, the deprecated [/Gm (Enable Minimal Rebuild)](gm-enable-minimal-rebuild.md) option is incompatible with **/ZW**. +Because the incremental linker doesn't support the Windows metadata included in .obj files by using the **`/ZW`** option, the deprecated [/Gm (Enable Minimal Rebuild)](gm-enable-minimal-rebuild.md) option is incompatible with **`/ZW`**. For more information, see [Visual C++ Language Reference](../../cppcx/visual-c-language-reference-c-cx.md). @@ -40,5 +40,5 @@ For more information, see [Visual C++ Language Reference](../../cppcx/visual-c-l ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/run-time-library-behavior.md b/docs/build/run-time-library-behavior.md index f2304bc108..1a85ae8d84 100644 --- a/docs/build/run-time-library-behavior.md +++ b/docs/build/run-time-library-behavior.md @@ -41,7 +41,7 @@ extern "C" BOOL WINAPI DllMain ( Some libraries wrap the `DllMain` function for you. For example, in a regular MFC DLL, implement the `CWinApp` object's `InitInstance` and `ExitInstance` member functions to perform initialization and termination required by your DLL. For more details, see the [Initialize regular MFC DLLs](#initializing-regular-dlls) section. > [!WARNING] -> There are significant limits on what you can safely do in a DLL entry point. See [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices) for specific Windows APIs that are unsafe to call in `DllMain`. If you need anything but the simplest initialization then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. +> There are significant limits on what you can safely do in a DLL entry point. For more information about specific Windows APIs that are unsafe to call in `DllMain`, see [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices). If you need anything but the simplest initialization then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. diff --git a/docs/build/tips-for-improving-time-critical-code.md b/docs/build/tips-for-improving-time-critical-code.md index 822661efc8..aa3481e9e2 100644 --- a/docs/build/tips-for-improving-time-critical-code.md +++ b/docs/build/tips-for-improving-time-critical-code.md @@ -7,7 +7,7 @@ ms.assetid: 3e95a8cc-6239-48d1-9d6d-feb701eccb54 --- # Tips for Improving Time-Critical Code -Writing fast code requires understanding all aspects of your application and how it interacts with the system. This topic suggests alternatives to some of the more obvious coding techniques to help you ensure that the time-critical portions of your code perform satisfactorily. +Writing fast code requires understanding all aspects of your application and how it interacts with the system. This article suggests alternatives to some of the more obvious coding techniques to help you ensure that the time-critical portions of your code perform satisfactorily. To summarize, improving time-critical code requires that you: @@ -41,13 +41,13 @@ To gather information on the performance of your code, you can use the performan Missed cache hits, on both the internal and external cache, as well as page faults (going to secondary storage for program instructions and data) slow the performance of a program. -A CPU cache hit can cost your program 10-20 clock cycles. An external cache hit can cost 20-40 clock cycles. A page fault can cost one million clock cycles (assuming a processor that handles 500 million instructions/second and a time of 2 millisecond for a page fault). Therefore, it is in the best interest of program execution to write code that will reduce the number of missed cache hits and page faults. +A CPU cache hit can cost your program 10-20 clock cycles. An external cache hit can cost 20-40 clock cycles. A page fault can cost a million clock cycles (assuming a processor that handles 500 million instructions/second and a time of 2 millisecond for a page fault). Therefore, it is in the best interest of program execution to write code that will reduce the number of missed cache hits and page faults. -One reason for slow programs is that they take more page faults or miss the cache more often than necessary. To avoid this, it's important to use data structures with good locality of reference, which means keeping related things together. Sometimes a data structure that looks great turns out to be horrible because of poor locality of reference, and sometimes the reverse is true. Here are two examples: +One reason for slow programs is that they take more page faults or miss the cache more often than necessary. To avoid this problem, it's important to use data structures with good locality of reference, which means keeping related things together. Sometimes a data structure that looks great turns out to be horrible because of poor locality of reference, and sometimes the reverse is true. Here are two examples: -- Dynamically allocated linked lists can reduce program performance because when you search for an item or when you traverse a list to the end, each skipped link could miss the cache or cause a page fault. A list implementation based on simple arrays might actually be much faster because of better caching and fewer page faults even — allowing for the fact that the array would be harder to grow, it still might be faster. +- Dynamically allocated linked lists can reduce program performance. When you search for an item, or when you traverse a list to the end, each skipped link could miss the cache or cause a page fault. A list implementation based on simple arrays might be faster because of better caching and fewer page faults. Even if you allow for the fact that the array would be harder to grow, it still might be faster. -- Hash tables that use dynamically allocated linked lists can degrade performance. By extension, hash tables that use dynamically allocated linked lists to store their contents might perform substantially worse. In fact, in the final analysis, a simple linear search through an array might actually be faster (depending on the circumstances). Array-based hash tables (so-called "closed hashing") is an often-overlooked implementation which frequently has superior performance. +- Hash tables that use dynamically allocated linked lists can degrade performance. By extension, hash tables that use dynamically allocated linked lists to store their contents might perform substantially worse. In fact, in the final analysis, a simple linear search through an array might actually be faster (depending on the circumstances). Use of an array-based hash table (so-called "closed hashing") is an often-overlooked implementation that frequently has superior performance. ## Sorting and Searching @@ -59,49 +59,49 @@ Sorting is inherently time consuming compared to many typical operations. The be - Sort only the part of the data that truly needs sorting. -Sometimes, you can build the list in sorted order. Be careful, because if you need to insert data in sorted order, you may require a more complicated data structure with poor locality of reference, leading to cache misses and page faults. There is no approach that works in all cases. Try several approaches and measure the differences. +Sometimes, you can build the list in sorted order. Be careful, because if you need to insert data in sorted order, you may require a more complicated data structure with poor locality of reference, leading to cache misses and page faults. There's no approach that works in all cases. Try several approaches and measure the differences. Here are some general tips for sorting: - Use a stock sort to minimize bugs. -- Any work you can do beforehand to reduce the complexity of the sort is worthwhile. If a one-time pass over your data simplifies the comparisons and reduces the sort from O(n log n) to O(n), you will almost certainly come out ahead. +- Any work you can do beforehand to reduce the complexity of the sort is worthwhile. If a one-time pass over your data simplifies the comparisons and reduces the sort from O(n log n) to O(n), you'll almost certainly come out ahead. - Think about the locality of reference of the sort algorithm and the data you expect it to run on. -There are fewer alternatives for searches than for sorting. If the search is time-critical, a binary search or hash table lookup is almost always best, but as with sorting, you must keep locality in mind. A linear search through a small array can be faster than a binary search through a data structure with a lot of pointers that causes page faults or cache misses. +There are fewer alternatives for searches than for sorting. If the search is time-critical, a binary search or hash table lookup is almost always best, but as with sorting, you must keep locality in mind. A linear search through a small array can be faster than a binary search through a data structure with many pointers that causes page faults or cache misses. ## MFC and Class Libraries The Microsoft Foundation Classes (MFC) can greatly simplify writing code. When writing time-critical code, you should be aware of the overhead inherent in some of the classes. Examine the MFC code that your time-critical code uses to see if it meets your performance requirements. The following list identifies MFC classes and functions you should be aware of: -- `CString` MFC calls the C run-time library to allocate memory for a [CString](../atl-mfc-shared/reference/cstringt-class.md) dynamically. Generally speaking, `CString` is as efficient as any other dynamically-allocated string. As with any dynamically allocated string, it has the overhead of dynamic allocation and release. Often, a simple **`char`** array on the stack can serve the same purpose and is faster. Don't use a `CString` to store a constant string. Use `const char *` instead. Any operation you perform with a `CString` object has some overhead. Using the run-time library [string functions](../c-runtime-library/string-manipulation-crt.md) may be faster. +- `CString` MFC calls the C run-time library to allocate memory for a [`CString`](../atl-mfc-shared/reference/cstringt-class.md) dynamically. Generally speaking, `CString` is as efficient as any other dynamically allocated string. As with any dynamically allocated string, it has the overhead of dynamic allocation and release. Often, a simple **`char`** array on the stack can serve the same purpose and is faster. Don't use a `CString` to store a constant string. Use `const char *` instead. Any operation you perform with a `CString` object has some overhead. Using the run-time library [string functions](../c-runtime-library/string-manipulation-crt.md) may be faster. -- `CArray` A [CArray](../mfc/reference/carray-class.md) provides flexibility that a regular array doesn't, but your program may not need that. If you know the specific limits for the array, you can use a global fixed array instead. If you use `CArray`, use `CArray::SetSize` to establish its size and specify the number of elements by which it grows when a reallocation is necessary. Otherwise, adding elements can cause your array to be frequently reallocated and copied, which is inefficient and can fragment memory. Also be aware that if you insert an item into an array, `CArray` moves subsequent items in memory and may need to grow the array. These actions can cause cache misses and page faults. If you look through the code that MFC uses, you may see that you can write something more specific to your scenario to improve performance. Since `CArray` is a template, for example, you might provide `CArray` specializations for specific types. +- `CArray` A [`CArray`](../mfc/reference/carray-class.md) provides flexibility that a regular array doesn't, but your program may not need that. If you know the specific limits for the array, you can use a global fixed array instead. If you use `CArray`, use `CArray::SetSize` to establish its size and specify the number of elements by which it grows when a reallocation is necessary. Otherwise, adding elements can cause your array to be frequently reallocated and copied, which is inefficient and can fragment memory. Also, if you insert an item into an array, `CArray` moves subsequent items in memory and may need to grow the array. These actions can cause cache misses and page faults. If you look through the code that MFC uses, you may see that you can write something more specific to your scenario to improve performance. Since `CArray` is a template, for example, you might provide `CArray` specializations for specific types. -- `CList` [CList](../mfc/reference/clist-class.md) is a doubly linked list, so element insertion is fast at the head, tail, and at a known position (`POSITION`) in the list. Looking up an element by value or index requires a sequential search, however, which can be slow if the list is long. If your code does not require a doubly linked list you may want to reconsider using `CList`. Using a singly linked list saves the overhead of updating an additional pointer for all operations as well as the memory for that pointer. The additional memory is not great, but it is another opportunity for cache misses or page faults. +- `CList` [`CList`](../mfc/reference/clist-class.md) is a doubly linked list, so element insertion is fast at the head, tail, and at a known position (`POSITION`) in the list. Looking up an element by value or index requires a sequential search, however, which can be slow if the list is long. If your code doesn't require a doubly linked list, you may want to reconsider using `CList`. Using a singly linked list saves the overhead of updating another pointer for all operations and the memory for that pointer. The extra memory isn't large, but it's another opportunity for cache misses or page faults. -- `IsKindOf` This function can generate many calls and access a lot of memory in different data areas, leading to bad locality of reference. It is useful for a debug build (in an ASSERT call, for example), but try to avoid using it in a release build. +- `IsKindOf` This function can generate many calls and may access memory in different data areas, leading to bad locality of reference. It's useful for a debug build (in an ASSERT call, for example), but try to avoid using it in a release build. -- `PreTranslateMessage` Use `PreTranslateMessage` when a particular tree of windows needs different keyboard accelerators or when you must insert message handling into the message pump. `PreTranslateMessage` alters MFC dispatch messages. If you override `PreTranslateMessage`, do so only at the level needed. For example, it is not necessary to override `CMainFrame::PreTranslateMessage` if you are interested only in messages going to children of a particular view. Override `PreTranslateMessage` for the view class instead. +- `PreTranslateMessage` Use `PreTranslateMessage` when a particular tree of windows needs different keyboard accelerators or when you must insert message handling into the message pump. `PreTranslateMessage` alters MFC dispatch messages. If you override `PreTranslateMessage`, do so only at the level needed. For example, it isn't necessary to override `CMainFrame::PreTranslateMessage` if you're interested only in messages going to children of a particular view. Override `PreTranslateMessage` for the view class instead. - Do not circumvent the normal dispatch path by using `PreTranslateMessage` to handle any message sent to any window. Use [window procedures](../mfc/registering-window-classes.md) and MFC message maps for that purpose. + Don't circumvent the normal dispatch path by using `PreTranslateMessage` to handle any message sent to any window. Use [window procedures](../mfc/registering-window-classes.md) and MFC message maps for that purpose. -- `OnIdle` Idle events can occur at times you do not expect, such as between `WM_KEYDOWN` and `WM_KEYUP` events. Timers may be a more efficient way to trigger your code. Do not force `OnIdle` to be called repeatedly by generating false messages or by always returning `TRUE` from an override of `OnIdle`, which would never allow your thread to sleep. Again, a timer or a separate thread might be more appropriate. +- `OnIdle` Idle events can occur at times you don't expect, such as between `WM_KEYDOWN` and `WM_KEYUP` events. Timers may be a more efficient way to trigger your code. Don't force `OnIdle` to be called repeatedly by generating false messages or by always returning `TRUE` from an override of `OnIdle`, which would never allow your thread to sleep. Again, a timer or a separate thread might be more appropriate. -## Shared Libraries +## Shared libraries -Code reuse is desirable. However, if you are going to use someone else's code, you should make sure you know exactly what it does in those cases where performance is critical to you. The best way to understand this is by stepping through the source code or by measuring with tools such as PView or Performance Monitor. +Code reuse is desirable. However, if you're going to use someone else's code, you should make sure you know exactly what it does in those cases where performance is critical to you. The best way to understand it is by stepping through the source code or by measuring with tools such as PView or Performance Monitor. ## Heaps Use multiple heaps with discretion. Additional heaps created with `HeapCreate` and `HeapAlloc` let you manage and then dispose of a related set of allocations. Don't commit too much memory. If you're using multiple heaps, pay special attention to the amount of memory that is initially committed. -Instead of multiple heaps, you can use helper functions to interface between your code and the default heap. Helper functions facilitate custom allocation strategies that can improve the performance of your application. For example, if you frequently perform small allocations, you may want to localize these allocations to one part of the default heap. You can allocate a large block of memory and then use a helper function to suballocate from that block. If you do this, you will not have additional heaps with unused memory because the allocation is coming out of the default heap. +Instead of multiple heaps, you can use helper functions to interface between your code and the default heap. Helper functions facilitate custom allocation strategies that can improve the performance of your application. For example, if you frequently perform small allocations, you may want to localize these allocations to one part of the default heap. You can allocate a large block of memory and then use a helper function to suballocate from that block. Then you won't have multiple heaps with unused memory, because the allocation is coming out of the default heap. In some cases, however, using the default heap can reduce locality of reference. Use Process Viewer, Spy++, or Performance Monitor to measure the effects of moving objects from heap to heap. -Measure your heaps so you can account for every allocation on the heap. Use the C run-time [debug heap routines](/visualstudio/debugger/crt-debug-heap-details) to checkpoint and dump your heap. You can read the output into a spreadsheet program like Microsoft Excel and use pivot tables to view the results. Note the total number, size, and distribution of allocations. Compare these with the size of working sets. Also look at the clustering of related-sized objects. +Measure your heaps so you can account for every allocation on the heap. Use the C run-time [debug heap routines](../c-runtime-library/crt-debug-heap-details.md) to checkpoint and dump your heap. You can read the output into a spreadsheet program like Microsoft Excel and use pivot tables to view the results. Note the total number, size, and distribution of allocations. Compare these results with the size of working sets. Also look at the clustering of related-sized objects. You can also use the performance counters to monitor memory usage. @@ -109,7 +109,7 @@ You can also use the performance counters to monitor memory usage. For background tasks, effective idle handling of events may be faster than using threads. It's easier to understand locality of reference in a single-threaded program. -A good rule of thumb is to use a thread only if an operating system notification that you block on is at the root of the background work. Threads are the best solution in such a case because it is impractical to block a main thread on an event. +A good rule of thumb is to use a thread only if an operating system notification that you block on is at the root of the background work. Threads are the best solution in such a case because it's impractical to block a main thread on an event. Threads also present communication problems. You must manage the communication link between your threads, with a list of messages or by allocating and using shared memory. Managing the communication link usually requires synchronization to avoid race conditions and deadlock problems. This complexity can easily turn into bugs and performance problems. diff --git a/docs/build/toc.yml b/docs/build/toc.yml index a81bc43512..444ec54501 100644 --- a/docs/build/toc.yml +++ b/docs/build/toc.yml @@ -9,7 +9,7 @@ items: - name: Set C++ compiler and build properties in Visual Studio expanded: false items: - - name: Set C++ compiler and build properties in Visual Studio + - name: Set C++ compiler and build properties href: ../build/working-with-project-properties.md - name: Share or reuse Visual Studio project settings href: ../build/create-reusable-property-configurations.md @@ -78,13 +78,17 @@ items: href: ../build/cmake-predefined-configuration-reference.md - name: "C++ Build Insights" href: ../build-insights/get-started-with-cpp-build-insights.md -- name: "Build and import header units" +- name: "Compare header units, modules, and precompiled headers" + href: ../build/compare-inclusion-methods.md +- name: "Header units" expanded: false items: - name: "Walkthrough: Build and import header units in Visual C++ projects" href: ../build/walkthrough-header-units.md - name: "Walkthrough: Import STL libraries as header units" href: ../build/walkthrough-import-stl-header-units.md + - name: C++ header unit.json reference + href: ../build/reference/header-unit-json-reference.md - name: Precompiled header files href: ../build/creating-precompiled-header-files.md - name: C++ release builds @@ -283,16 +287,7 @@ items: - name: "How to: Build isolated applications to consume COM components" href: ../build/how-to-build-isolated-applications-to-consume-com-components.md - name: Understanding manifest generation for C/C++ programs - expanded: false - items: - - name: Understanding manifest generation for C/C++ programs - href: ../build/understanding-manifest-generation-for-c-cpp-programs.md - - name: Manifest generation in Visual Studio - href: ../build/manifest-generation-in-visual-studio.md - - name: Manifest generation at the command line - href: ../build/manifest-generation-at-the-command-line.md - - name: "How to: Embed a manifest inside a C/C++ application" - href: ../build/how-to-embed-a-manifest-inside-a-c-cpp-application.md + href: ../build/understanding-manifest-generation-for-c-cpp-programs.md - name: Troubleshooting C/C++ isolated applications and side-by-side assemblies href: ../build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md - name: Configure MSVC for 64-bit, x64 targets @@ -306,10 +301,10 @@ items: href: ../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md - name: Common MSVC 64-bit migration issues href: ../build/common-visual-cpp-64-bit-migration-issues.md - - name: x64 software conventions + - name: x64 ABI conventions expanded: false items: - - name: x64 software conventions + - name: Overview of x64 ABI conventions href: ../build/x64-software-conventions.md - name: x64 calling convention href: ../build/x64-calling-convention.md @@ -330,6 +325,8 @@ items: href: ../build/overview-of-arm-abi-conventions.md - name: Overview of ARM64 ABI conventions href: ../build/arm64-windows-abi-conventions.md + - name: Overview of ARM64EC ABI conventions + href: ../build/arm64ec-windows-abi-conventions.md - name: ARM exception handling href: ../build/arm-exception-handling.md - name: ARM64 exception handling @@ -377,7 +374,7 @@ items: href: ../build/reference/help-files-html-help.md - name: Winhelp help files href: ../build/reference/help-files-winhelp.md - - name: Hint files for Intellisense + - name: Hint files for IntelliSense href: ../build/reference/hint-files.md - name: Property page XML files href: ../build/reference/property-page-xml-files.md @@ -481,6 +478,8 @@ items: href: ../build/reference/arch-x64.md - name: /arch (ARM) href: ../build/reference/arch-arm.md + - name: /arch (ARM64) + href: ../build/reference/arch-arm64.md - name: /await (Enable coroutine support) href: ../build/reference/await-enable-coroutine-support.md - name: /bigobj (Increase number of sections in .Obj file) @@ -516,6 +515,8 @@ items: href: ../build/reference/errorreport-report-internal-compiler-errors.md - name: /execution-charset (Set execution character set) href: ../build/reference/execution-charset-set-execution-character-set.md + - name: /experimental:log + href: ../build/reference/experimental-log.md - name: /experimental:module href: ../build/reference/experimental-module.md - name: /experimental:preprocessor @@ -559,6 +560,11 @@ items: href: ../build/reference/favor-optimize-for-architecture-specifics.md - name: /FC (Full path of source code file in diagnostics) href: ../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md + - name: /feature (Enable architecture features) + href: ../build/reference/feature-arm64.md + - name: /forceInterlockedFunctions (Generate and link with out-of-line atomic + functions) + href: ./reference/force-interlocked-functions.md - name: /fp (Specify floating-point behavior) href: ../build/reference/fp-specify-floating-point-behavior.md - name: /fpcvt (Floating-point to unsigned integer conversion behavior) @@ -619,10 +625,20 @@ items: href: ../build/reference/hotpatch-create-hotpatchable-image.md - name: /I (Additional include directories) href: ../build/reference/i-additional-include-directories.md + - name: /ifcOutput (Specify where the compiled `.ifc` should go.) + href: ../build/reference/ifc-output.md + - name: /ifcMap (Map named modules and header units to IFC files.) + href: ../build/reference/ifc-map.md + - name: /interface (Treat input file as a module interface unit) + href: ../build/reference/interface.md + - name: /internalPartition (Treat the input file as an internal partition unit) + href: ../build/reference/internal-partition.md - name: /J (Default char type is unsigned) href: ../build/reference/j-default-char-type-is-unsigned.md - name: /JMC (Just My Code debugging) href: ../build/reference/jmc.md + - name: /jumptablerdata (put switch case jump tables in .rdata) + href: ../build/reference/jump-table-rdata.md - name: /kernel (Create kernel mode binary) href: ../build/reference/kernel-create-kernel-mode-binary.md - name: /link (Pass options to linker) @@ -689,6 +705,8 @@ items: href: ../build/reference/qsafe-fp-loads.md - name: /Qspectre href: ../build/reference/qspectre.md + - name: /Qspectre-jmp + href: ../build/reference/qspectre-jmp.md - name: /Qspectre-load href: ../build/reference/qspectre-load.md - name: /Qspectre-load-cf @@ -697,7 +715,9 @@ items: href: ../build/reference/qvec-report-auto-vectorizer-reporting-level.md - name: /RTC (Run-time error checks) href: ../build/reference/rtc-run-time-error-checks.md - - name: /sdl (Enable additional security checks) + - name: /scanDependencies (List module dependencies in standard form) + href: ../build/reference/scandependencies.md + - name: /sdl (Enable more security checks) href: ../build/reference/sdl-enable-additional-security-checks.md - name: /showIncludes (List include files) href: ../build/reference/showincludes-list-include-files.md @@ -715,7 +735,7 @@ items: href: ../build/reference/translateinclude.md - name: /U, /u (Undefine symbols) href: ../build/reference/u-u-undefine-symbols.md - - name: /utf-8 (Set source and executable character sets to UTF-8) + - name: /utf-8 (Set source and execution character sets to UTF-8) href: ../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md - name: /V (Version number) href: ../build/reference/v-version-number.md @@ -723,12 +743,16 @@ items: href: ../build/reference/validate-charset-validate-for-compatible-characters.md - name: /vd (Disable construction displacements) href: ../build/reference/vd-disable-construction-displacements.md + - name: /vlen (Specify vector length) + href: ../build/reference/vlen.md - name: /vmb, /vmg (Representation method) href: ../build/reference/vmb-vmg-representation-method.md - name: /vmm, /vms, /vmv (General purpose representation) href: ../build/reference/vmm-vms-vmv-general-purpose-representation.md - name: /volatile (volatile keyword interpretation) href: ../build/reference/volatile-volatile-keyword-interpretation.md + - name: /volatileMetadata + href: ../build/reference/volatile.md - name: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level) href: ../build/reference/compiler-option-warning-level.md - name: /WL (Enable one-line diagnostics) @@ -764,22 +788,30 @@ items: - name: /Zc (Conformance) expanded: false items: - - name: /Zc (Conformance) + - name: "/Zc (Conformance)" href: ../build/reference/zc-conformance.md + - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" + href: ../build/reference/zc-cplusplus.md + - name: "/Zc:__STDC__ (Enable __STDC__ macro)" + href: ../build/reference/zc-stdc.md - name: "/Zc:alignedNew (C++17 over-aligned allocation)" href: ../build/reference/zc-alignednew.md - name: "/Zc:auto (Deduce variable type)" href: ../build/reference/zc-auto-deduce-variable-type.md - name: "/Zc:char8_t (Enable C++20 char8_t type)" href: ../build/reference/zc-char8-t.md - - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" - href: ../build/reference/zc-cplusplus.md + - name: "/Zc:checkGwOdr (Enforce Standard C++ ODR violations under /Gw)" + href: ../build/reference/zc-check-gwodr.md + - name: "/Zc:enumTypes (Enable enum type deduction)" + href: ../build/reference/zc-enumtypes.md - name: '/Zc:externC (Use Standard C++ extern "C" rules)' href: ../build/reference/zc-externc.md - name: "/Zc:externConstexpr (Enable extern constexpr variables)" href: ../build/reference/zc-externconstexpr.md - name: "/Zc:forScope (Force conformance in for loop scope)" href: ../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md + - name: "/Zc:gotoScope (Enforce conformance in goto scope)" + href: ../build/reference/zc-gotoscope.md - name: "/Zc:hiddenFriend (Enforce Standard C++ hidden friend rules)" href: ../build/reference/zc-hiddenfriend.md - name: "/Zc:implicitNoexcept (Implicit exception specifiers)" @@ -790,6 +822,8 @@ items: href: ../build/reference/zc-lambda.md - name: "/Zc:noexceptTypes (C++17 noexcept rules)" href: ../build/reference/zc-noexcepttypes.md + - name: "/Zc:nrvo (Control optional NRVO)" + href: ../build/reference/zc-nrvo.md - name: "/Zc:preprocessor (Enable preprocessor conformance mode)" href: ../build/reference/zc-preprocessor.md - name: "/Zc:referenceBinding (Enforce reference binding rules)" @@ -802,18 +836,24 @@ items: href: ../build/reference/zc-static-assert.md - name: "/Zc:strictStrings (Disable string literal type conversion)" href: ../build/reference/zc-strictstrings-disable-string-literal-type-conversion.md + - name: "/Zc:templateScope (Check template parameter shadowing)" + href: ../build/reference/zc-templatescope.md - name: "/Zc:ternary (Enforce conditional operator rules)" href: ../build/reference/zc-ternary.md - - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" + - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" href: ../build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md - name: "/Zc:throwingNew (Assume operator new throws)" href: ../build/reference/zc-throwingnew-assume-operator-new-throws.md + - name: "/Zc:tlsGuards (Check TLS initialization)" + href: ../build/reference/zc-tlsguards.md - name: "/Zc:trigraphs (Trigraphs substitution)" href: ../build/reference/zc-trigraphs-trigraphs-substitution.md - name: "/Zc:twoPhase- (disable two-phase name lookup)" href: ../build/reference/zc-twophase.md - name: "/Zc:wchar_t (wchar_t is native type)" href: ../build/reference/zc-wchar-t-wchar-t-is-native-type.md + - name: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" + href: ../build/reference/zc-zerosizearraynew.md - name: /Zf (Faster PDB generation) href: ../build/reference/zf.md - name: /Zg (Generate function prototypes) @@ -832,6 +872,8 @@ items: href: ../build/reference/zs-syntax-check-only.md - name: /ZW (Windows Runtime compilation) href: ../build/reference/zw-windows-runtime-compilation.md + - name: Structured SARIF output + href: ../build/reference/sarif-output.md - name: Unicode support in the compiler and linker href: ../build/reference/unicode-support-in-the-compiler-and-linker.md - name: MSVC linker reference @@ -890,6 +932,8 @@ items: href: ../build/reference/allowisolation-manifest-lookup.md - name: /APPCONTAINER (UWP/Microsoft Store app) href: ../build/reference/appcontainer-windows-store-app.md + - name: /ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding) + href: ../build/reference/arm64-function-pad-min-x64.md - name: /ASSEMBLYDEBUG (Add DebuggableAttribute) href: ../build/reference/assemblydebug-add-debuggableattribute.md - name: /ASSEMBLYLINKRESOURCE (Link to .NET Framework resource) @@ -962,16 +1006,20 @@ items: href: ../build/reference/ignore-ignore-specific-warnings.md - name: /IGNOREIDL (Don't process attributes into MIDL) href: ../build/reference/ignoreidl-don-t-process-attributes-into-midl.md - - name: /INFERASANLIBS (Use inferred sanitizer libs) - href: ../build/reference/inferasanlibs.md + - name: /ILK (Name incremental database file) + href: ../build/reference/ilk-name-incremental-database-file.md - name: /IMPLIB (Name import library) href: ../build/reference/implib-name-import-library.md - name: /INCLUDE (Force symbol references) href: ../build/reference/include-force-symbol-references.md - name: /INCREMENTAL (Link incrementally) href: ../build/reference/incremental-link-incrementally.md + - name: /INFERASANLIBS (Use inferred sanitizer libs) + href: ../build/reference/inferasanlibs.md - name: /INTEGRITYCHECK (Require signature check) href: ../build/reference/integritycheck-require-signature-check.md + - name: /KERNEL (Create a kernel mode binary) + href: ../build/reference/link-code-for-kernel-mode.md - name: /KEYCONTAINER (Specify a key container to sign an assembly) href: ../build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md - name: /KEYFILE (Specify key or key pair to sign an assembly) @@ -982,10 +1030,14 @@ items: href: ../build/reference/libpath-additional-libpath.md - name: /LINKREPRO (Link repro directory name) href: ../build/reference/linkrepro.md + - name: /LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files) + href: ../build/reference/link-repro-full-path-rsp.md - name: /LINKREPROTARGET (Link repro file name) href: ../build/reference/linkreprotarget.md - name: /LTCG (Link-time code generation) href: ../build/reference/ltcg-link-time-code-generation.md + - name: /LTCGOUT (Name LTCG .iobj file) + href: ../build/reference/ltcgout.md - name: /MACHINE (Specify target platform) href: ../build/reference/machine-specify-target-platform.md - name: /MANIFEST (Create side-by-side assembly manifest) @@ -1014,6 +1066,8 @@ items: href: ../build/reference/nodefaultlib-ignore-libraries.md - name: /NOENTRY (No entry point) href: ../build/reference/noentry-no-entry-point.md + - name: /NOFUNCTIONPADSECTION (Disable function padding) + href: ../build/reference/no-function-pad-section.md - name: /NOLOGO (Suppress startup banner) (Linker) href: ../build/reference/nologo-suppress-startup-banner-linker.md - name: /NXCOMPAT (Compatible with Data Execution Prevention) @@ -1115,10 +1169,10 @@ items: href: ../build/reference/error-handling-and-notification.md - name: Understand the delay load helper function href: ../build/reference/understanding-the-helper-function.md - - name: Additional MSVC build tools + - name: Other MSVC build tools expanded: false items: - - name: Additional MSVC build tools + - name: Other MSVC build tools href: ../build/reference/c-cpp-build-tools.md - name: NMAKE reference expanded: false @@ -1164,12 +1218,16 @@ items: href: ../build/reference/nmake-function-filterout.md - name: findstring, findstringi href: ../build/reference/nmake-function-findstring.md + - name: lowercase + href: ../build/reference/nmake-function-lowercase.md - name: patsubst, patsubsti href: ../build/reference/nmake-function-patsubst.md - name: strip href: ../build/reference/nmake-function-strip.md - name: subst, substi href: ../build/reference/nmake-function-subst.md + - name: uppercase + href: ../build/reference/nmake-function-uppercase.md - name: Special NMAKE macros href: ../build/reference/special-nmake-macros.md - name: Inference rules diff --git a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md index 412ec26186..2735311ee3 100644 --- a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md +++ b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md @@ -1,19 +1,291 @@ --- -description: "Learn more about: Understanding Manifest Generation for C/C++ Programs" -title: "Understanding Manifest Generation for C/C++ Programs" -ms.date: "11/04/2016" +title: "Understanding manifest generation for C/C++ programs" +description: "Learn more about: Understanding manifest generation for C/C++ programs" +ms.date: 06/10/2022 helpviewer_keywords: ["manifests [C++]"] -ms.assetid: a1f24221-5b09-4824-be48-92eae5644b53 --- -# Understanding Manifest Generation for C/C++ Programs +# Understanding manifest generation for C/C++ programs -A [manifest](/windows/win32/sbscs/manifests) is an XML document that can be an external XML file or a resource embedded inside an application or an assembly. The manifest of an [isolated application](/windows/win32/SbsCs/isolated-applications) is used to manage the names and versions of shared side-by-side assemblies to which the application should bind at run time. The manifest of a side-by-side assembly specifies its dependencies on names, versions, resources, and other assemblies. +A [manifest](/windows/win32/sbscs/manifests) is an XML document that uniquely identifies an assembly. It contains information used for binding and activation, such as COM classes, interfaces, and type libraries. A manifest can be an external XML file or a resource embedded inside an application or an assembly. The manifest of an [isolated application](/windows/win32/SbsCs/isolated-applications) is used to manage the names and versions of shared side-by-side assemblies the application should bind to at run time. The manifest of a side-by-side assembly specifies its dependencies on names, versions, resources, and other assemblies. -There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file following rules and naming requirements. Alternatively, if a program only depends on Visual C++ assemblies such as CRT, MFC, ATL or others, then a manifest can be generated automatically by the linker. +There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file by following the rules and naming requirements. For more information, see [Manifest files reference](/windows/win32/sbscs/manifest-files-reference). Alternatively, if a program only depends on MSVC assemblies such as CRT, MFC, ATL or others, then the linker can generate a manifest automatically. -The headers of Visual C++ libraries contain assembly information, and when the libraries are included in application code, this assembly information is used by the linker to form a manifest for the final binary. The linker does not embed the manifest file inside the binary, and can only generate the manifest as an external file. Having a manifest as an external file may not work for all scenarios. For example, it is recommended that private assemblies have embedded manifests. In command line builds such as those that use nmake to build code, a manifest can be embedded using the manifest tool; for more information see [Manifest Generation at the Command Line](manifest-generation-at-the-command-line.md). When building in Visual Studio, a manifest can be embedded by setting a property for the manifest tool in the **Project Properties** dialog; see [Manifest Generation in Visual Studio](manifest-generation-in-visual-studio.md). +The headers of MSVC libraries contain assembly information, and when the libraries are included in application code, this assembly information is used by the linker to form a manifest for the final binary. By default, the linker doesn't embed the manifest file inside the binary. Having a manifest as an external file may not work for all scenarios. For example, it's recommended that private assemblies have embedded manifests. In command line builds such as ones that use NMAKE to build code, you can use the [`/MANIFEST:EMBED`](./reference/manifest-create-side-by-side-assembly-manifest.md) linker option to embed the manifest. Alternatively, a manifest can be embedded using the manifest tool. For more information, see [Manifest generation at the command line](#manifest-generation-at-the-command-line). When you build in Visual Studio, a manifest can be embedded by setting a property for the manifest tool in the **Project Properties** dialog, as described in the next section. + +## Manifest generation in Visual Studio + +You can tell Visual Studio to generate a manifest file for a particular project in the project's **Property Pages** dialog. Under **Configuration Properties**, select **Linker** > **Manifest File** > **Generate Manifest**. By default, the project properties of new projects are set to generate a manifest file. However it's possible to disable generation of the manifest for a project by using the **Generate Manifest** property of the project. When this property is set to **Yes**, the manifest for the project is generated. Otherwise the linker ignores assembly information when resolving dependencies of the application code, and doesn't generate the manifest. + +The build system in Visual Studio allows the manifest to be embedded in the final binary application file, or generated as an external file. This behavior is controlled by the **Embed Manifest** option in the **Project Properties** dialog. To set this property, open the **Manifest Tool** node, then select **Input and Output**. If the manifest isn't embedded, it's generated as an external file and saved in the same directory as the final binary. If the manifest is embedded, Visual Studio embeds the final manifests using the following process: + +1. After the source code is compiled to object files, the linker collects dependent assembly information. While it links the final binary, the linker generates an intermediate manifest that's used later to generate the final manifest. + +1. After the intermediate manifest and linking are finished, the manifest tool merges a final manifest and saves it as an external file. + +1. The project build system then detects whether the manifest generated by the manifest tool contains different information than the manifest already embedded in the binary. + +1. If the manifest embedded in the binary is different from the manifest generated by the manifest tool, or the binary doesn't contain an embedded manifest, Visual Studio invokes the linker one more time to embed the external manifest file inside the binary as a resource. + +1. If the manifest embedded in the binary is the same as the manifest generated by the manifest tool, the build continues to the next build steps. + +The manifest is embedded inside the final binary as a text resource. You can view it by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the dependencies of a Visual C++ application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). Or, follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) article. + +## Manifest generation at the command line + +When you build C/C++ applications from the command line using NMAKE or similar tools, the manifest is generated after the linker has processed all object files and built the final binary. The linker collects assembly information stored in the object files and combines this information into a final manifest file. By default, the linker generates a file named *`..manifest`* to describe the final binary. The linker can embed a manifest file inside the binary by specifying the [`/MANIFEST:EMBED`](./reference/manifest-create-side-by-side-assembly-manifest.md) linker option. + +There are several other ways to embed a manifest inside the final binary, such as using the [Manifest tool (`mt.exe`)](/windows/win32/sbscs/mt-exe) or compiling the manifest into a resource file. You must follow specific rules when you embed a manifest to enable features such as incremental linking, signing, and Edit and Continue. These rules and other options are discussed in the next section. + +## How to embed a manifest inside a C/C++ application + +We recommended that you embed the manifest of your application or library inside the final binary. This approach guarantees correct runtime behavior in most scenarios. By default, Visual Studio tries to embed the manifest when it builds a project. However, if you build your application by using NMAKE, you have to make some changes to the makefile. This section shows how to change the makefiles so that it automatically embeds the manifest inside the final binary. + +### Two approaches + +There are two ways to embed the manifest inside an application or library. + +1. If you aren't doing an incremental build, you can directly embed the manifest using a command line similar to the following as a post-build step: + + ```cmd + mt.exe -manifest MyApp.exe.manifest -outputresource:MyApp.exe;1 + ``` + + or + + ```cmd + mt.exe -manifest MyLibrary.dll.manifest -outputresource:MyLibrary.dll;2 + ``` + + Use 1 for an EXE and 2 for a DLL. + +1. If you're doing an incremental build, use the following steps: + + - Link the binary to generate the *`MyApp.exe.manifest`* file. + + - Convert the manifest to a resource file. + + - Relink (incrementally) to embed the manifest resource into the binary. + +The following examples show how to change makefiles to incorporate both techniques. + +### Makefiles (Before) + +Consider the NMAKE script for *`MyApp.exe`*, a simple application built from one file: + +```makefile +# build MyApp.exe +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +!else +CPPFLAGS=$(CPPFLAGS) /MD +!endif + +MyApp.exe : MyApp.obj + link $** /out:$@ $(LFLAGS) + +MyApp.obj : MyApp.cpp + +clean : + del MyApp.obj MyApp.exe +``` + +If this script is run unchanged with Visual Studio, it successfully creates *`MyApp.exe`*. It also creates the external manifest file *`MyApp.exe.manifest`*, for use by the operating system to load dependent assemblies at runtime. + +The NMAKE script for *`MyLibrary.dll`* looks similar: + +```makefile +# build MyLibrary.dll +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /DLL /INCREMENTAL + +!else +CPPFLAGS=$(CPPFLAGS) /MD +LFLAGS=$(LFLAGS) /DLL + +!endif + +MyLibrary.dll : MyLibrary.obj + link $** /out:$@ $(LFLAGS) + +MyLibrary.obj : MyLibrary.cpp + +clean : + del MyLibrary.obj MyLibrary.dll +``` + +### Makefiles (After) + +To build with embedded manifests, you have to make four small changes to the original makefiles. For the *`MyApp.exe`* makefile: + +```makefile +# build MyApp.exe +!include makefile.inc +#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +!else +CPPFLAGS=$(CPPFLAGS) /MD +!endif + +MyApp.exe : MyApp.obj + link $** /out:$@ $(LFLAGS) + $(_VC_MANIFEST_EMBED_EXE) +#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2 + +MyApp.obj : MyApp.cpp + +clean : + del MyApp.obj MyApp.exe + $(_VC_MANIFEST_CLEAN) +#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3 + +!include makefile.target.inc +#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) +``` + +For the MyLibrary.dll makefile: + +```makefile +# build MyLibrary.dll +!include makefile.inc +#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /DLL /INCREMENTAL + +!else +CPPFLAGS=$(CPPFLAGS) /MD +LFLAGS=$(LFLAGS) /DLL + +!endif + +MyLibrary.dll : MyLibrary.obj + link $** /out:$@ $(LFLAGS) + $(_VC_MANIFEST_EMBED_DLL) +#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2. + +MyLibrary.obj : MyLibrary.cpp + +clean : + del MyLibrary.obj MyLibrary.dll + $(_VC_MANIFEST_CLEAN) +#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3. + +!include makefile.target.inc +#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) +``` + +The makefiles now include two files that do the real work, *`makefile.inc`* and *`makefile.target.inc`*. + +Create *`makefile.inc`* and copy the following content into it: + +```makefile +# makefile.inc -- Include this file into existing makefile at the very top. + +# _VC_MANIFEST_INC specifies whether build is incremental (1 - incremental). +# _VC_MANIFEST_BASENAME specifies name of a temporary resource file. + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +_VC_MANIFEST_INC=1 +_VC_MANIFEST_BASENAME=__VC90.Debug + +!else +CPPFLAGS=$(CPPFLAGS) /MD +_VC_MANIFEST_INC=0 +_VC_MANIFEST_BASENAME=__VC90 + +!endif + +#################################################### +# Specifying name of temporary resource file used only in incremental builds: + +!if "$(_VC_MANIFEST_INC)" == "1" +_VC_MANIFEST_AUTO_RES=$(_VC_MANIFEST_BASENAME).auto.res +!else +_VC_MANIFEST_AUTO_RES= +!endif + +#################################################### +# _VC_MANIFEST_EMBED_EXE - command to embed manifest in EXE: + +!if "$(_VC_MANIFEST_INC)" == "1" + +#MT_SPECIAL_RETURN=1090650113 +#MT_SPECIAL_SWITCH=-notify_resource_update +MT_SPECIAL_RETURN=0 +MT_SPECIAL_SWITCH= +_VC_MANIFEST_EMBED_EXE= \ +if exist $@.manifest mt.exe -manifest $@.manifest -out:$(_VC_MANIFEST_BASENAME).auto.manifest $(MT_SPECIAL_SWITCH) & \ +if "%ERRORLEVEL%" == "$(MT_SPECIAL_RETURN)" \ +rc /r $(_VC_MANIFEST_BASENAME).auto.rc & \ +link $** /out:$@ $(LFLAGS) + +!else + +_VC_MANIFEST_EMBED_EXE= \ +if exist $@.manifest mt.exe -manifest $@.manifest -outputresource:$@;1 + +!endif + +#################################################### +# _VC_MANIFEST_CLEAN - command to clean resources files generated temporarily: + +!if "$(_VC_MANIFEST_INC)" == "1" + +_VC_MANIFEST_CLEAN=-del $(_VC_MANIFEST_BASENAME).auto.res \ + $(_VC_MANIFEST_BASENAME).auto.rc \ + $(_VC_MANIFEST_BASENAME).auto.manifest + +!else + +_VC_MANIFEST_CLEAN= + +!endif + +# End of makefile.inc +#################################################### +``` + +Now create *`makefile.target.inc`* and copy the following content into it: + +```makefile +# makefile.target.inc - include this at the very bottom of the existing makefile + +#################################################### +# Commands to generate initial empty manifest file and the RC file +# that references it, and for generating the .res file: + +$(_VC_MANIFEST_BASENAME).auto.res : $(_VC_MANIFEST_BASENAME).auto.rc + +$(_VC_MANIFEST_BASENAME).auto.rc : $(_VC_MANIFEST_BASENAME).auto.manifest + type <<$@ +#include +1RT_MANIFEST"$(_VC_MANIFEST_BASENAME).auto.manifest" +<< KEEP + +$(_VC_MANIFEST_BASENAME).auto.manifest : + type <<$@ + + + +<< KEEP + +# end of makefile.target.inc +``` ## See also -[Concepts of Isolated Applications and Side-by-side Assemblies](concepts-of-isolated-applications-and-side-by-side-assemblies.md)
-[Building C/C++ Isolated Applications and Side-by-side Assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md) +[Building C/C++ isolated applications and side-by-side assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\ +[Concepts of isolated applications and side-by-side assemblies](concepts-of-isolated-applications-and-side-by-side-assemblies.md)\ +[Troubleshooting C/C++ isolated applications and side-by-side assemblies](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\ +[`/INCREMENTAL` (Link incrementally)](./reference/incremental-link-incrementally.md)\ +[`/MANIFEST` (Create side-by-side assembly manifest)](./reference/manifest-create-side-by-side-assembly-manifest.md)\ +[Strong Name assemblies (Assembly signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md)\ +[Edit and Continue](/visualstudio/debugger/edit-and-continue) diff --git a/docs/build/vscpp-step-0-installation.md b/docs/build/vscpp-step-0-installation.md index f36a65840b..f6e9b8cea0 100644 --- a/docs/build/vscpp-step-0-installation.md +++ b/docs/build/vscpp-step-0-installation.md @@ -1,30 +1,29 @@ --- title: Install C and C++ support in Visual Studio -description: "Learn how to install Visual Studio with support for Microsoft C/C++ and related workloads." +description: "Learn how to install Visual Studio with support for Microsoft C and C++ and related workloads." ms.custom: vs-acquisition, intro-installation -ms.date: 11/08/2021 -ms.topic: "tutorial" +ms.date: 03/18/2025 +ms.topic: tutorial ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 --- # Install C and C++ support in Visual Studio -If you haven't downloaded and installed Visual Studio and the Microsoft C/C++ tools yet, here's how to get started. +If you haven't installed Visual Studio and the Microsoft C and C++ tools yet, here's how to get started. ::: moniker range="msvc-170" -## Visual Studio 2022 Installation +## Visual Studio 2022 installation -Welcome to Visual Studio 2022! In this version, it's easy to choose and install just the features you need. And because of its reduced minimum footprint, it installs quickly and with less system impact. +Welcome to Visual Studio 2022! In this version, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, Visual Studio installs quickly and with less system impact. > [!NOTE] -> This topic applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com/) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, auto-completion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). +> This article applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, autocompletion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). -Want to know more about what else is new in this version? See the Visual Studio [release notes](/visualstudio/releases/2022/release-notes/). +To learn what else is new in this version, see the Visual Studio [release notes](/visualstudio/releases/2022/release-notes/). -Ready to install? We'll walk you through it, step-by-step. +Ready to install? Use the following step-by-step guide. -### Step 1 - Make sure your computer is ready for Visual Studio +### Step 1 - Prepare your computer for Visual Studio Before you begin installing Visual Studio: @@ -32,69 +31,68 @@ Before you begin installing Visual Studio: 1. Apply the latest Windows updates. These updates ensure that your computer has both the latest security updates and the required system components for Visual Studio. -1. Reboot. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. +1. Reboot your computer. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. -1. Free up space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. +1. Free up disk space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. For questions about running previous versions of Visual Studio side by side with Visual Studio 2022, see the [Visual Studio 2022 Platform Targeting and Compatibility](/visualstudio/releases/2022/compatibility/) page. ### Step 2 - Download Visual Studio -Next, download the Visual Studio bootstrapper file. To do so, choose the following button to go to the Visual Studio download page. Select the edition of Visual Studio that you want and choose the **Free trial** or **Free download** button. +Select the following button to go to the Visual Studio download page, and download the Visual Studio bootstrapper file. Select the edition of Visual Studio that you want and choose the **Free trial** or **Free download** button. - > [!div class="button"] - > [Download Visual Studio](https://visualstudio.microsoft.com/downloads/) +> [!div class="button"] +> [Download Visual Studio](https://visualstudio.microsoft.com/downloads/) -### Step 3 - Install the Visual Studio installer +>[!TIP] +> The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install Visual Studio 2022 Professional or Visual Studio 2022 Enterprise. -Run the bootstrapper file you downloaded to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. +### Step 3 - Install the Visual Studio Installer -1. From your **Downloads** folder, double-click the bootstrapper that matches or is similar to one of the following files: +Run the bootstrapper file you downloaded to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. - - **vs_community.exe** for Visual Studio Community - - **vs_professional.exe** for Visual Studio Professional - - **vs_enterprise.exe** for Visual Studio Enterprise +1. From your *Downloads* folder, double-click the bootstrapper file called *VisualStudioSetup.exe*. If you receive a User Account Control notice, choose **Yes** to allow the bootstrapper to run. -1. We'll ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. +1. We ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. ### Step 4 - Choose workloads -After the installer is installed, you can use it to customize your installation by selecting the *workloads*, or feature sets, that you want. Here's how. +You can use the installer to customize your installation by selecting the *workloads*, or feature sets, that you want. 1. Find the workload you want in the **Installing Visual Studio** screen. - ![Visual Studio 2022: Install a workload.](../get-started/media/vs2022-installer-workloads.png) - - For core C and C++ support, choose the "Desktop development with C++" workload. It comes with the default core editor, which includes basic code editing support for over 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. + :::image type="content" source="../get-started/media/vs2022-installer-workloads.png" alt-text="Screenshot of the Visual Studio 2022 installer with the Desktop development with C plus plus workload selected." lightbox="../get-started/media/vs2022-installer-workloads.png"::: - Additional workloads support other kinds of development. For example, choose the "Universal Windows Platform development" workload to create apps that use the Windows Runtime for the Microsoft Store. Choose "Game development with C++" to create games that use DirectX, Unreal, and Cocos2d. Choose "Linux development with C++" to target Linux platforms, including IoT development. + For core C and C++ support, choose the **Desktop development with C++** workload. It comes with the default core editor, which includes basic code editing support for more than 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. The **Installation details** pane lists the included and optional components installed by each workload. You can select or deselect optional components in this list. For example, to support development by using the Visual Studio 2017 or 2015 compiler toolsets, choose the MSVC v141 or MSVC v140 optional components. You can add support for MFC, the experimental Modules language extension, IncrediBuild, and more. -1. After you choose the workload(s) and optional components you want, choose **Install**. + Other workloads support more kinds of development. For example, choose the **Universal Windows Platform development** workload to create apps that use the Windows Runtime for the Microsoft Store. Choose **Game development with C++** to create games that use DirectX, Unreal, or Cocos2d. Choose **Linux development with C++** to target Linux platforms, including IoT development. + +1. After you choose the workloads and optional components you want, choose **Install**. Next, status screens appear that show the progress of your Visual Studio installation. > [!TIP] > At any time after installation, you can install workloads or components that you didn't install initially. If you have Visual Studio open, go to **Tools** > **Get Tools and Features...** which opens the Visual Studio Installer. Or, open **Visual Studio Installer** from the Start menu. From there, you can choose the workloads or components that you wish to install. Then, choose **Modify**. -### Step 5 - Choose individual components (Optional) +### Step 5 - Choose individual components (optional) If you don't want to use the Workloads feature to customize your Visual Studio installation, or you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. -### Step 6 - Install language packs (Optional) +### Step 6 - Install language packs (optional) By default, the installer program tries to match the language of the operating system when it runs for the first time. To install Visual Studio in a language of your choosing, choose the **Language packs** tab from the Visual Studio Installer, and then follow the prompts. - ![Screenshot of the Visual Studio Installer, showing the Install language packs tab view.](../get-started/media/vs-installer-language-packs.png) + :::image type="content" source="../get-started/media/vs-installer-language-packs.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install language packs tab view and the languages you can choose from like English, Spanish, Chinese (simplified or traditional)." lightbox="../get-started/media/vs-installer-language-packs.png"::: #### Change the installer language from the command line -Another way that you can change the default language is by running the installer from the command line. For example, you can force the installer to run in English by using the following command: `vs_installer.exe --locale en-US`. The installer will remember this setting when it's run the next time. The installer supports the following language tokens: zh-cn, zh-tw, cs-cz, en-us, es-es, fr-fr, de-de, it-it, ja-jp, ko-kr, pl-pl, pt-br, ru-ru, and tr-tr. +Another way that you can change the default language is by running the installer from the command line. For example, you can force the installer to run in English by using the following command: `vs_installer.exe --locale en-US`. The installer remembers this setting when it's run the next time. The installer supports the following language tokens: zh-cn, zh-tw, cs-cz, en-us, es-es, fr-fr, de-de, it-it, ja-jp, ko-kr, pl-pl, pt-br, ru-ru, and tr-tr. -### Step 7 - Change the installation location (Optional) +### Step 7 - Change the installation location (optional) You can reduce the installation footprint of Visual Studio on your system drive. You can choose to move the download cache, shared components, SDKs, and tools to different drives, and keep Visual Studio on the drive that runs it the fastest. @@ -107,9 +105,9 @@ You can reduce the installation footprint of Visual Studio on your system drive. 1. On the start window, choose **Create a new project**. -1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workload(s) that you chose during installation. To see different templates, choose different workloads. +1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workloads that you chose during installation. To see different templates, choose different workloads. - You can also filter your search for a specific programming language by using the **Language** drop-down list. You can filter by using the **Platform** list and the **Project type** list, too. + You can also filter your search for a specific programming language by using the **Language** dropdown list. You can filter by using the **Platform** list and the **Project type** list, too. 1. Visual Studio opens your new project, and you're ready to code! @@ -117,18 +115,18 @@ You can reduce the installation footprint of Visual Studio on your system drive. ::: moniker range="msvc-160" -## Visual Studio 2019 Installation +## Visual Studio 2019 installation -Welcome to Visual Studio 2019! In this version, it's easy to choose and install just the features you need. And because of its reduced minimum footprint, it installs quickly and with less system impact. +Welcome to Visual Studio 2019! In this version, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, Visual Studio installs quickly and with less system impact. > [!NOTE] -> This topic applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com/) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, auto-completion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). +> This article applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, autocompletion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). -Want to know more about what else is new in this version? See the Visual Studio [release notes](/visualstudio/releases/2019/release-notes/). +To learn what else is new in this version, see the Visual Studio [release notes](/visualstudio/releases/2019/release-notes/). -Ready to install? We'll walk you through it, step-by-step. +Ready to install? Use the following step-by-step guide. -### Step 1 - Make sure your computer is ready for Visual Studio +### Step 1 - Prepare your computer for Visual Studio Before you begin installing Visual Studio: @@ -136,75 +134,71 @@ Before you begin installing Visual Studio: 1. Apply the latest Windows updates. These updates ensure that your computer has both the latest security updates and the required system components for Visual Studio. -1. Reboot. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. +1. Reboot your computer. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. -1. Free up space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. +1. Free up disk space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. For questions about running previous versions of Visual Studio side by side with Visual Studio 2019, see the [Visual Studio 2019 Platform Targeting and Compatibility](/visualstudio/releases/2019/compatibility/) page. ### Step 2 - Download Visual Studio -Next, download the Visual Studio bootstrapper file. To do so, choose the following button to go to the Visual Studio download page. Choose the Download button, then you can select the edition of Visual Studio that you want. +Select the following button to go to the Visual Studio older downloads page, and download the Visual Studio 2019 bootstrapper file. > [!div class="button"] > [Download Visual Studio 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products) -### Step 3 - Install the Visual Studio installer +### Step 3 - Install the Visual Studio Installer Run the bootstrapper file you downloaded to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. -1. From your **Downloads** folder, double-click the bootstrapper that matches or is similar to one of the following files: - - - **vs_community.exe** for Visual Studio Community - - **vs_professional.exe** for Visual Studio Professional - - **vs_enterprise.exe** for Visual Studio Enterprise +1. From your *Downloads* folder, double-click the bootstrapper file. If you receive a User Account Control notice, choose **Yes** to allow the bootstrapper to run. -1. We'll ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. +1. We ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. ### Step 4 - Choose workloads -After the installer is installed, you can use it to customize your installation by selecting the *workloads*, or feature sets, that you want. Here's how. +You can use the installer to customize your installation by selecting the *workloads*, or feature sets, that you want. 1. Find the workload you want in the **Installing Visual Studio** screen. - ![Visual Studio 2019: Install a workload.](../get-started/media/vs-installer-workloads.png) + :::image type="content" source="../get-started/media/vs-installer-workloads.png" alt-text="Screenshot of the Visual Studio 2019 installer." lightbox="../get-started/media/vs-installer-workloads.png"::: - For core C and C++ support, choose the "Desktop development with C++" workload. It comes with the default core editor, which includes basic code editing support for over 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. - - Additional workloads support other kinds of development. For example, choose the "Universal Windows Platform development" workload to create apps that use the Windows Runtime for the Microsoft Store. Choose "Game development with C++" to create games that use DirectX, Unreal, and Cocos2d. Choose "Linux development with C++" to target Linux platforms, including IoT development. + For core C and C++ support, choose the **Desktop development with C++** workload. It comes with the default core editor, which includes basic code editing support for over 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. The **Installation details** pane lists the included and optional components installed by each workload. You can select or deselect optional components in this list. For example, to support development by using the Visual Studio 2017 or 2015 compiler toolsets, choose the MSVC v141 or MSVC v140 optional components. You can add support for MFC, the experimental Modules language extension, IncrediBuild, and more. -1. After you choose the workload(s) and optional components you want, choose **Install**. + Other workloads support more kinds of development. For example, choose the **Universal Windows Platform development** workload to create apps that use the Windows Runtime for the Microsoft Store. Choose **Game development with C++** to create games that use DirectX, Unreal, and Cocos2d. Choose **Linux development with C++** to target Linux platforms, including IoT development. + +1. After you choose the workloads and optional components you want, choose **Install**. Next, status screens appear that show the progress of your Visual Studio installation. > [!TIP] > At any time after installation, you can install workloads or components that you didn't install initially. If you have Visual Studio open, go to **Tools** > **Get Tools and Features...** which opens the Visual Studio Installer. Or, open **Visual Studio Installer** from the Start menu. From there, you can choose the workloads or components that you wish to install. Then, choose **Modify**. -### Step 5 - Choose individual components (Optional) +### Step 5 - Choose individual components (optional) -If you don't want to use the Workloads feature to customize your Visual Studio installation, or you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. +If you don't want to use the Workloads feature to customize your Visual Studio installation, or if you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. - ![Screenshot of the Visual Studio Installer, showing the Install individual components tab view.](../get-started/media/vs-installer-individual-components.png "Install Visual Studio individual components") +:::image type="content" source="../get-started/media/vs-installer-individual-components.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install individual components tab view." lightbox="../get-started/media/vs-installer-individual-components.png"::: -### Step 6 - Install language packs (Optional) +### Step 6 - Install language packs (optional) By default, the installer program tries to match the language of the operating system when it runs for the first time. To install Visual Studio in a language of your choosing, choose the **Language packs** tab from the Visual Studio Installer, and then follow the prompts. - ![Screenshot of the Visual Studio Installer, showing the Install language packs tab view.](../get-started/media/vs-installer-language-packs.png "Install Visual Studio language packs") +:::image type="content" source="../get-started/media/vs-installer-language-packs.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install language packs tab view." lightbox="../get-started/media/vs-installer-language-packs.png"::: #### Change the installer language from the command line Another way that you can change the default language is by running the installer from the command line. For example, you can force the installer to run in English by using the following command: `vs_installer.exe --locale en-US`. The installer will remember this setting when it's run the next time. The installer supports the following language tokens: zh-cn, zh-tw, cs-cz, en-us, es-es, fr-fr, de-de, it-it, ja-jp, ko-kr, pl-pl, pt-br, ru-ru, and tr-tr. -### Step 7 - Change the installation location (Optional) +### Step 7 - Change the installation location (optional) You can reduce the installation footprint of Visual Studio on your system drive. You can choose to move the download cache, shared components, SDKs, and tools to different drives, and keep Visual Studio on the drive that runs it the fastest. - ![Screenshot of the Visual Studio Installer, showing the installation locations tab view.](../get-started/media/vs-installer-installation-locations.png "Change the installation location") +:::image type="content" source="../get-started/media/vs-installer-installation-locations.png" alt-text="Screenshot of the Visual Studio Installer, showing the installation locations tab view." lightbox="../get-started/media/vs-installer-installation-locations.png"::: > [!IMPORTANT] > You can select a different drive only when you first install Visual Studio. If you've already installed it and want to change drives, you must uninstall Visual Studio and then reinstall it. @@ -215,9 +209,9 @@ You can reduce the installation footprint of Visual Studio on your system drive. 1. On the start window, choose **Create a new project**. -1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workload(s) that you chose during installation. To see different templates, choose different workloads. +1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workloads that you chose during installation. To see different templates, choose different workloads. - You can also filter your search for a specific programming language by using the **Language** drop-down list. You can filter by using the **Platform** list and the **Project type** list, too. + You can also filter your search for a specific programming language by using the **Language** dropdown list. You can filter by using the **Platform** list and the **Project type** list, too. 1. Visual Studio opens your new project, and you're ready to code! @@ -225,14 +219,12 @@ You can reduce the installation footprint of Visual Studio on your system drive. ::: moniker range="msvc-150" -## Visual Studio 2017 Installation +## Visual Studio 2017 installation -In Visual Studio 2017, it's easy to choose and install just the features you need. And because of its reduced minimum footprint, it installs quickly and with less system impact. +In Visual Studio 2017, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, it installs quickly and with less system impact. ### Prerequisites -- A broadband internet connection. The Visual Studio installer can download several gigabytes of data. - - A computer that runs Microsoft Windows 7 or later versions. We recommend the latest version of Windows for the best development experience. Make sure that the latest updates are applied to your system before you install Visual Studio. - Enough free disk space. Visual Studio requires at least 7 GB of disk space, and can take 50 GB or more if many common options are installed. We recommend you install it on your C: drive. @@ -241,36 +233,29 @@ For details on the disk space and operating system requirements, see [Visual Stu ### Download and install -1. To download the latest Visual Studio 2017 installer for Windows, go to the Microsoft Visual Studio [Older downloads](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-and-other-products) page. Expand the **2017** section, and choose the **Download** button. +1. To download the Visual Studio 2017 installer for Windows, go to the Visual Studio [older downloads](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-and-other-products) page. Expand the **2017** section, and choose the **Download** button. - >[!Tip] - > The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install Visual Studio 2017 Professional or Visual Studio 2017 Enterprise. +1. Find the installer file you downloaded and run it. The downloaded file might be displayed in your browser, or you might find it in your *Downloads* folder. The installer needs Administrator privileges to run. You might see a **User Account Control** dialog asking you to give permission to let the installer make changes to your system; choose **Yes**. If you're having trouble, find the downloaded file in File Explorer, right-click on the installer icon, and choose **Run as Administrator** from the context menu. -1. Find the installer file you downloaded and run it. The downloaded file may be displayed in your browser, or you may find it in your Downloads folder. The installer needs Administrator privileges to run. You may see a **User Account Control** dialog asking you to give permission to let the installer make changes to your system; choose **Yes**. If you're having trouble, find the downloaded file in File Explorer, right-click on the installer icon, and choose **Run as Administrator** from the context menu. - - ![What you see when you download and install the Visual Studio Installer.](media/vscpp-concierge-run-installer.gif "Download and install the Visual Studio Installer") + :::image type="content" source="media/vscpp-concierge-run-installer.gif" alt-text="Animation that shows the Visual Studio Installer."::: 1. The installer presents you with a list of workloads, which are groups of related options for specific development areas. Support for C++ is now part of optional workloads that aren't installed by default. - ![Detail showing the Desktop development with C++ workload.](media/desktop-development-with-cpp.png "Desktop development with C++") + :::image type="content" source="media/desktop-development-with-cpp.png" alt-text="Screenshot showing the Desktop development with C plus plus workload."::: For C and C++, select the **Desktop development with C++** workload and then choose **Install**. - ![What you see when you select the Desktop development with C++ workload then choose the Install button.](media/vscpp-concierge-choose-workload.gif "Install the Desktop development with C++ workload") + :::image type="content" source="media/vscpp-concierge-choose-workload.gif" alt-text="Animation that shows the Desktop development with C plus plus workload then choose the Install button."::: 1. When the installation completes, choose the **Launch** button to start Visual Studio. The first time you run Visual Studio, you're asked to sign in with a Microsoft Account. If you don't have one, you can create one for free. You must also choose a theme. Don't worry, you can change it later if you want to. - It may take Visual Studio several minutes to get ready for use the first time you run it. Here's what it looks like in a quick time-lapse: - - ![Visual Studio sign in dialog.](media/vscpp-quickstart-first-run.gif "Visual Studio 2017 sign in") - - Visual Studio starts much faster when you run it again. + It might take Visual Studio several minutes to get ready for use the first time you run it. 1. When Visual Studio opens, check to see if the flag icon in the title bar is highlighted: - ![Visual Studio notification flag.](media/vscpp-first-start-page-flag.png "Visual Studio 2017 notification flag") + :::image type="content" source="media/vscpp-first-start-page-flag.png" alt-text="Screenshot of the Visual Studio notification flag."::: If it's highlighted, select it to open the **Notifications** window. If there are any updates available for Visual Studio, we recommend you install them now. Once the installation is complete, restart Visual Studio. @@ -278,9 +263,9 @@ For details on the disk space and operating system requirements, see [Visual Stu ::: moniker range=" [!div class="nextstepaction"] -> [Create a C++ project](vscpp-step-1-create.md) +> [Create a C++ console app project](vscpp-step-1-create.md) diff --git a/docs/build/vscpp-step-1-create.md b/docs/build/vscpp-step-1-create.md index af10d950ea..e4830eee92 100644 --- a/docs/build/vscpp-step-1-create.md +++ b/docs/build/vscpp-step-1-create.md @@ -2,35 +2,42 @@ title: Create a C++ console app project description: "Create a Hello World console app using Microsoft C++ in Visual Studio." ms.custom: "mvc" -ms.date: 04/20/2020 +ms.date: 07/05/2023 ms.topic: "tutorial" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 --- # Create a C++ console app project -The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. That's what you'll create in Visual Studio in this step. +The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. That's what you create in Visual Studio in this step. ## Prerequisites -- Have Visual Studio with the Desktop development with C++ workload installed and running on your computer. If it's not installed yet, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). +- The **Desktop development with C++** workload must be installed to make the **Console App (C++)** project type available. If it's not installed, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). ## Create your app project -Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize your projects. A project contains all the options, configurations, and rules used to build your apps. It manages the relationship between all the project's files and any external files. To create your app, first, you'll create a new project and solution. +Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize your projects. A project contains all the options, configurations, and rules used to build your apps. It manages the relationship between all the project's files and any external files. To create your app, first, create a new project and solution. ::: moniker range=">=msvc-160" 1. In Visual Studio, open the **File** menu and choose **New > Project** to open the **Create a new Project** dialog. Select the **Console App** template that has **C++**, **Windows**, and **Console** tags, and then choose **Next**. - ![Create a new project dialog.](media/vs2019-choose-console-app.png "Open the Create a new project dialog") + :::image type="complex" source="media/vs2019-choose-console-app.png" alt-text="Screenshot of the create a new project dialog."::: + The create a new project dialog with the Console App template selected. That template says: Run code in a windows terminal. Prints hello world by default. Has the tags c++, Windows, and Console. + :::image-end::: + + The **Desktop development with C++** workload must be installed for the C++ Console App template to show up. See [Install C++ support in Visual Studio](vscpp-step-0-installation.md) if you haven't already installed it. 1. In the **Configure your new project** dialog, enter *HelloWorld* in the **Project name** edit box. Choose **Create** to create the project. - ![Screenshot of the Configure your new project dialog box with Hello World typed in the Project name text field.](media/vs2019-configure-new-project-hello-world.png "Name and create the new project") + :::image type="complex" source="media/vs2019-configure-new-project-hello-world.png" alt-text="Screenshot of Configure your new project dialog."::: + The Configure your new project dialog with HelloWorld entered into the Project name field. + :::image-end::: - Visual Studio creates a new project. It's ready for you to add and edit your source code. By default, the Console App template fills in your source code with a "Hello World" app: + Visual Studio creates a new project. It's ready for you to add and edit your source code. By default, the Console App template provides source code for a "Hello World" app, like this: - ![Screenshot of the Hello World project in the IDE.](media/vs2019-hello-world-code.png "Hello World project in the IDE") + :::image type="complex" source="media/vs2019-hello-world-code.png" alt-text="Screenshot of the NEW Hello World project."::: + Shows the new project. The HelloWorld.cpp file is open, showing the default code that is included with this template. That code consists of #include iostream and a main() function that contains the line: std::cout << quote hello world!\n quote; + :::image-end::: When the code looks like this in the editor, you're ready to go on to the next step and build your app. @@ -48,7 +55,7 @@ Visual Studio uses *projects* to organize the code for an app, and *solutions* t ![Screenshot of the New Project dialog box with Installed > Visual C plus plus selected and called out, the Empty Project option called out, and Hello World typed in the Name text box.](media/vscpp-concierge-project-name-callouts.png "Name and create the new project") -Visual Studio creates a new, empty project. It's ready for you to specialize for the kind of app you want to create and to add your source code files. You'll do that next. +Visual Studio creates a new, empty project. It's ready for you to specialize for the kind of app you want to create and to add your source code files. You do that next. [I ran into a problem.](#create-your-app-project-issues) @@ -62,7 +69,7 @@ Visual Studio can create all kinds of apps and components for Windows and other ![View of using the Property Pages dialog to set the Subsystem property.](media/vscpp-properties-linker-subsystem.gif "Open the Property Pages dialog") -Visual Studio now knows to build your project to run in a console window. Next, you'll add a source code file and enter the code for your app. +Visual Studio now knows to build your project to run in a console window. Next, you add a source code file and enter the code for your app. [I ran into a problem.](#make-your-project-a-console-app-issues) @@ -74,7 +81,7 @@ Visual Studio now knows to build your project to run in a console window. Next, ![View of the process to add a source file for HelloWorld.cpp.](media/vscpp-add-new-item.gif "Add a source file for HelloWorld.cpp") -Visual studio creates a new, empty source code file and opens it in an editor window, ready to enter your source code. +Visual Studio creates a new, empty source code file and opens it in an editor window, ready to enter your source code. [I ran into a problem.](#add-a-source-code-file-issues) @@ -94,7 +101,7 @@ Visual studio creates a new, empty source code file and opens it in an editor wi The code should look like this in the editor window: - ![Screenshot of the Hello World code in the editor.](media/vscpp-hello-world-editor.png "Hello World code in editor") + ![Screenshot of the Hello World code in the editor.](media/vscpp-hello-world-editor.png "The default Hello World code provided by the Console App template project in the IDE. The code consists of #include iostream and a main() function that contains the line: std::cout << \"hello world!\n\"; followed by return 0;") When the code looks like this in the editor, you're ready to go on to the next step and build your app. @@ -102,7 +109,7 @@ When the code looks like this in the editor, you're ready to go on to the next s ::: moniker-end -## Next Steps +## Next steps > [!div class="nextstepaction"] > [Build and run a C++ project](vscpp-step-2-build.md) @@ -119,7 +126,7 @@ The **New Project** dialog should show a **Console App** template that has **C++ To install **Desktop development with C++**, you can run the installer right from the **New Project** dialog. Choose the **Install more tools and features** link at the bottom of the template list to start the installer. If the **User Account Control** dialog requests permissions, choose **Yes**. In the installer, make sure the **Desktop development with C++** workload is checked. Then choose **Modify** to update your Visual Studio installation. -If another project with the same name already exists, choose another name for your project. Or, delete the existing project and try again. To delete an existing project, delete the solution folder (the folder that contains the *helloworld.sln* file) in File Explorer. +If another project with the same name already exists, choose another name for your project. Or, delete the existing project and try again. To delete an existing project, delete the solution folder (the folder that contains the `helloworld.sln` file) in File Explorer. [Go back](#create-your-app-project). @@ -133,7 +140,7 @@ If the **New Project** dialog doesn't show a **Visual C++** entry under **Instal ::: moniker range="<=msvc-150" -If another project with the same name already exists, choose another name for your project. Or, delete the existing project and try again. To delete an existing project, delete the solution folder (the folder that contains the *helloworld.sln* file) in File Explorer. +If another project with the same name already exists, choose another name for your project. Or, delete the existing project and try again. To delete an existing project, delete the solution folder (the folder that contains the `helloworld.sln` file) in File Explorer. [Go back](#create-your-app-project). diff --git a/docs/build/vscpp-step-2-build.md b/docs/build/vscpp-step-2-build.md index f77e62bf30..e708ea80e0 100644 --- a/docs/build/vscpp-step-2-build.md +++ b/docs/build/vscpp-step-2-build.md @@ -2,62 +2,77 @@ title: Build and run a C++ console app project description: "Build and run a Hello World console app in Visual C++" ms.custom: "mvc" -ms.date: 04/20/2020 +ms.date: 06/28/2024 ms.topic: "tutorial" ms.devlang: "cpp" -ms.assetid: 45138d71-719d-42dc-90d7-1d0ca31a2f55 --- # Build and run a C++ console app project -You've created a C++ console app project and entered your code. Now you can build and run it within Visual Studio. Then, run it as a stand-alone app from the command line. +In [Create a C++ console app project](vscpp-step-1-create.md) you created a C++ console app project and entered your code. Now you can build and run it within Visual Studio. Then, run it as a stand-alone app from the command line. ## Prerequisites -- Have Visual Studio with the Desktop development with C++ workload installed and running on your computer. If it's not installed yet, follow the steps in [Install C++ support in Visual Studio](vscpp-step-0-installation.md). - -- Create a "Hello, World!" project and enter its source code. If you haven't done this step yet, follow the steps in [Create a C++ console app project](vscpp-step-1-create.md). +- Have Visual Studio with the Desktop development with C++ workload installed and running on your computer. If it's not installed, follow the steps in [Install C++ support in Visual Studio](vscpp-step-0-installation.md). +- Create a "Hello, World!" project. By default, it contains code to print `Hello World!`. If you haven't done this step yet, follow the steps in [Create a C++ console app project](vscpp-step-1-create.md). If Visual Studio looks like this, you're ready to build and run your app: - ![Screenshot of Visual Studio showing the Hello World source code in the editor.](media/vscpp-ready-to-build.png "Ready to build the new project") + :::image type="complex" source="media/vscpp-ready-to-build.png" alt-text="Screenshot of the Hello World source code in the Visual Studio editor."::: + The source consists of #include \ and a main function that does std::cout hello world and returns 0 from the function. + :::image-end::: ## Build and run your code in Visual Studio -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, from the main menu choose **Build** > **Build Solution**. The **Output** window shows the results of the build process. - ![View of the sequence of actions you take to build the project.](media/vscpp-build-solution.gif "Build the project") + :::image type="complex" source="media/vscpp-build-solution.gif" alt-text="Animated screenshot showing the sequence of actions taken to build a project in Visual Studio."::: + First, Build is selected from the main menu. Then Build Solution is selected. The Output window shows the build output messages, including that the build is successful. + :::image-end::: 1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. - ![View of the actions you take to start the project.](media/vscpp-start-without-debugging.gif "Start the project") + :::image type="complex" source="media/vscpp-start-without-debugging.gif" alt-text="Video showing the actions taken to start a project in Visual Studio."::: + First, Debug is selected from the main menu. Then 'Start without debugging' is selected. A console window appears with the output of the program: Hello, World! + :::image-end::: A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to continue . . ." to give you a chance to see the output. -Congratulations! You've created your first "Hello, world!" console app in Visual Studio! Press a key to dismiss the console window and return to Visual Studio. +Congratulations! You created your first "Hello, world!" console app in Visual Studio! Press a key to dismiss the console window and return to Visual Studio. [I ran into a problem.](#build-and-run-your-code-in-visual-studio-issues) ## Run your code in a command window -Normally, you run console apps at the command prompt, not in Visual Studio. Once your app is built by Visual Studio, you can run it from any command window. Here's how to find and run your new app in a command prompt window. +Normally, you run console apps at the command prompt, not in Visual Studio. Once Visual Studio builds your app, you can run it from a command window. Here's how to find and run your new app in a command prompt window. 1. In **Solution Explorer**, select the HelloWorld solution (not the HelloWorld project) and right-click to open the context menu. Choose **Open Folder in File Explorer** to open a **File Explorer** window in the HelloWorld solution folder. -1. In the **File Explorer** window, open the Debug folder. This folder contains your app, *HelloWorld.exe*, and a couple of other debugging files. Hold down the **Shift** key and right-click on *HelloWorld.exe* to open the context menu. Choose **Copy as path** to copy the path to your app to the clipboard. +::: moniker range=" **Options** > **CMake** > **General**. Select **Prefer using CMake Presets for configure, build, and test**, then select **OK**. Instead, you could have added a `CMakePresets.json` file to the root of the project. For more information, see [Enable CMake Presets integration](cmake-presets-vs.md#-enable--cmakepresetsjson-integration-in-visual-studio). +5. Enable Visual Studio's CMake Presets integration. Select **Tools** > **Options** > **CMake** > **General**. Select **Prefer using CMake Presets for configure, build, and test**, then select **OK**. Instead, you could have added a `CMakePresets.json` file to the root of the project. For more information, see [Enable CMake Presets integration](cmake-presets-vs.md#enable-cmakepresets-json-integration). - ![Screenshot of CMake general options screen with Prefer using CMake Presets for configure, build, and test highlighted and selected](media/cmake-general-prefer-cmake-presets.png) + :::image type="complex" source="media/cmake-general-prefer-cmake-presets.png" alt-text="Screenshot of the Visual Studio project options. Cmake > General is selected."::: + In the CMake configuration file group, 'Use CMake Presets if available, otherwise use CMakeSettings.json' is called out and is selected. + :::image-end::: 6. To activate the integration: from the main menu, select **File** > **Close Folder**. The **Get started** page appears. Under **Open recent**, select the folder you just closed to reopen the folder. -7. There are three dropdowns across the Visual Studio main menu bar. Use the dropdown on the left to select your active target system. This is the system where CMake will be invoked to configure and build the project. Visual Studio queries for WSL installations with `wsl -l -v`. In the following image, **WSL2: Ubuntu-20.04** is shown selected as the **Target System**. +7. There are three dropdowns across the Visual Studio main menu bar. Use the dropdown on the left to select your active target system. This is the system where CMake is invoked to configure and build the project. Visual Studio queries for WSL installations with `wsl -l -v`. In the following image, **WSL2: Ubuntu-20.04** is shown selected as the **Target System**. - ![Target system dropdown displaying WSL2: Ubuntu-20.04 as being selected](media/vs2022-target-system-dropdown.png) + :::image type="content" source="media/vs2022-target-system-dropdown.png" alt-text="Screenshot of the Visual Studio target system dropdown. WSL2: Ubuntu-20.04 is the selected."::: > [!NOTE] > If Visual Studio starts to configure your project automatically, read step 11 to manage CMake binary deployment, and then continue to the step below. To customize this behavior, see [Modify automatic configuration and cache notifications](cmake-presets-vs.md#modify-automatic-configuration-and-cache-notifications). 8. Use the dropdown in the middle to select your active Configure Preset. Configure Presets tell Visual Studio how to invoke CMake and generate the underlying build system. In step 7, the active Configure Preset is the **linux-default** Preset created by Visual Studio. To create a custom Configure Preset, select **Manage Configurations…** For more information about Configure Presets, see [Select a Configure Preset](cmake-presets-vs.md#select-a-configure-preset) and [Edit Presets](cmake-presets-vs.md#edit-presets). - ![Active configure preset dropdown, showing Manage Configurations... selected](media/vs2022-ActivePresetDropdown.png) + :::image type="content" source="media/vs2022-ActivePresetDropdown.png" alt-text="Screenshot of the Visual Studio active configure preset dropdown. Manage Configurations... is selected."::: 9. Use the dropdown on the right to select your active Build Preset. Build Presets tell Visual Studio how to invoke build. In the illustration for step 7, the active Build Preset is the **Default** Build Preset created by Visual Studio. For more information about Build Presets, see [Select a Build Preset](cmake-presets-vs.md#select-a-build-preset). 10. Configure the project on WSL 2. If project generation doesn't start automatically, then manually invoke configure with **Project** > **Configure** *project-name* - ![Project configure drop-down showing Configure CMakeProject selected](media/vs2022-project-configure.png) + :::image type="content" source="media/vs2022-project-configure.png" alt-text="Screenshot of the Visual Studio project configure dropdown. Configure CMakeProject is selected."::: -11. If you don't have a supported version of CMake installed on your WSL 2 distro, then Visual Studio will prompt you beneath the main menu ribbon to deploy a recent version of CMake. Select **Yes** to deploy CMake binaries to your WSL 2 distro. +11. If you don't have a supported version of CMake installed on your WSL 2 distro, then Visual Studio prompts you beneath the main menu ribbon to deploy a recent version of CMake. Select **Yes** to deploy CMake binaries to your WSL 2 distro. - ![Visual Studio prompt beneath the toolbar that says: supported cmake version is not present. Install latest CMake binaries from Cmake.org? Yes no](media/vs2022-supported-cmake-not-present-prompt.png) + :::image type="complex" source="media/vs2022-supported-cmake-not-present-prompt.png" alt-text="Screenshot of a prompt beneath the Visual Studio toolbar"::: + The user is prompted whether to install the latest C Make binaries from C make . org because the supported C Make version isn't installed." + :::image-end::: -12. Confirm that the configure step has completed and that you can see the **CMake generation finished** message in the **Output** window under the **CMake** pane. Build files are written to a directory in the WSL 2 distro’s file system. +12. Confirm that the configure step completed and that you can see the **CMake generation finished** message in the **Output** window under the **CMake** pane. Build files are written to a directory in the WSL 2 distro's file system. - ![Output window showing message that CMake generation is done](media/vs-output-window-cmake-generation.png) + :::image type="content" source="media/vs-output-window-cmake-generation.png" alt-text="Screenshot of the Visual Studio Output window. It contains messages generated during the configure step, including that C Make generation is complete."::: 13. Select the active debug target. The debug dropdown menu lists all the CMake targets available to the project. - ![Debug dropdown menu showing CMakeProject selected](media/vs-debug-dropdown-menu-cmake.png) + :::image type="content" source="media/vs-debug-dropdown-menu-cmake.png" alt-text="Screenshot of the Visual Studio debug dropdown menu. CMakeProject is selected."::: 14. Expand the project subfolder in the **Solution Explorer**. In the `CMakeProject.cpp` file, set a breakpoint in `main()`. You can also navigate to CMake targets view by selecting the View Picker button in the **Solution Explorer**, highlighted in following screenshot: - ![Solution explorer showing the button to switch views. The button is just to the right of the home (house) button](media/solution-explorer-switch-view.png) + :::image type="content" source="media/solution-explorer-switch-view.png" alt-text="Screenshot of the Visual Studio solution explorer showing the button to switch views. It's located to the right of the home button."::: -15. Select **Debug** > **Start**, or press **F5**. Your project will build, the executable will launch on your WSL 2 distro, and Visual Studio will stop execution at the breakpoint. You can see the output of your program (in this case, `"Hello CMake."`) in the Linux Console Window: +15. Select **Debug** > **Start**, or press **F5**. Your project builds, the executable launches on your WSL 2 distro, and Visual Studio halts execution at the breakpoint. The output of your program (in this case, `"Hello CMake."`) is visible in the Linux Console Window: - ![Linux console window, displaying the text "Hello Cmake." Also shows the sample program with a breakpoint on the line following cout << "Hello CMake."](media/walkthrough-build-debug-wsl2-breakpoint.png) + :::image type="complex" source="media/walkthrough-build-debug-wsl2-breakpoint.png" alt-text="Screenshot of a running hello world program."::: + The Visual Studio Linux console window displays the output of the program: 'Hello C Make.' The editor window shows the hello world program. Execution stopped at a breakpoint on the line that says return 0;." + :::image-end::: You've now built and debugged a C++ app with WSL 2 and Visual Studio 2022. ## Advanced WSL 2 and CMake projects considerations -Visual Studio only provides native support for WSL 2 for CMake projects that use `CMakePresets.json` as the active configuration file. To migrate from `CMakeSettings.json` to `CMakePresets.json`, see [Enable CMake Presets integration in Visual Studio](cmake-presets-vs.md#-enable--cmakepresetsjson-integration-in-visual-studio). +Visual Studio only provides native support for WSL 2 for CMake projects that use `CMakePresets.json` as the active configuration file. To migrate from `CMakeSettings.json` to `CMakePresets.json`, see [Enable CMake Presets integration in Visual Studio](cmake-presets-vs.md#enable-cmakepresets-json-integration). -If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the Visual Studio Remote Settings vendor map in `CMakePresets.json`, set **forceWSL1Toolset** to **true** . See [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map) for details. +If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the Visual Studio Remote Settings vendor map in `CMakePresets.json`, set **forceWSL1Toolset** to **true** . For more information, see [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map). -If **forceWSL1Tooslet** is set to **true**, then Visual Studio won't maintain a copy of your source files in the WSL file system. Instead, it will access source files in the mounted Windows drive (`/mnt/`…). +If **forceWSL1Tooslet** is set to **true**, then Visual Studio doesn't maintain a copy of your source files in the WSL file system. Instead, it accesses source files in the mounted Windows drive (`/mnt/`…). -In most cases, it’s best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are instead stored in the Windows file system. To learn more about file system performance in WSL 2, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). +In most cases, it's best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are instead stored in the Windows file system. To learn more about file system performance in WSL 2, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). -Specify advanced settings such as the path to the directory on WSL 2 where the project will be copied, copy source options, and rsync command arguments, in the Visual Studio Remote Settings vendor map in `CMakePresets.json`. See [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map) for details. +Specify advanced settings such as the path to the directory on WSL 2 where the project is copied, copy source options, and rsync command arguments, in the Visual Studio Remote Settings vendor map in `CMakePresets.json`. For more information, see [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map). System headers are still automatically copied to the Windows file system to supply the native IntelliSense experience. You can customize the headers that are included or excluded from this copy in the Visual Studio Remote Settings vendor map in `CMakePresets.json`. @@ -118,13 +125,17 @@ You can change the IntelliSense mode, or specify other IntelliSense options, in ## WSL 2 and MSBuild-based Linux projects -CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. If you're already using a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio via **Property pages** > **General** > **Platform Toolset**: +CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. -![A screenshot of a dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected](media/wsl-platform-toolset-selection.png) +But you may have a MSBuild-based Linux project. -If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in **Property Pages** > **General** > **Platform Toolset**, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio won't maintain a copy of your source files in the WSL file system and will instead access source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**. +If you have a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio. Right-click the project in the solution explorer, then choose **Properties** > **General** > **Platform Toolset**: -In most cases, it’s best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are stored in the Windows file system. To to learn more, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). +:::image type="content" source="media/wsl-platform-toolset-selection.png" alt-text="Screenshot of a Visual Studio dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected."::: + +If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the **Platform Toolset** dropdown, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio doesn't maintain a copy of your source files in the WSL file system and instead accesses source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**. + +In most cases, it's best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are stored in the Windows file system. To learn more, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). ## See also diff --git a/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md b/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md index 548923ec71..d8b15d2ed5 100644 --- a/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md +++ b/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md @@ -1,37 +1,36 @@ --- -title: "Walkthrough: Compile a C program on the command line" -description: "Walkthrough that shows how to create a Hello World C program." -ms.custom: "conceptual" -ms.date: "9/10/2020" +title: "Compile a C Program on the Command Line" +description: "Learn how to create a Hello World C program by using a text editor, and then compile it by using the command line compiler." +ms.custom: tutorial +ms.date: 03/17/2025 helpviewer_keywords: ["command-line applications [C++], C programs", "Visual C, compiling", "compiling programs [C++]", "C program compiling [C++]"] ms.assetid: 7e74cc2d-54b1-49de-b7ad-d3ae6b39ab8d --- # Walkthrough: Compile a C program on the command line -Visual C++ includes a C compiler that you can use to create everything from basic console programs to full Windows Desktop applications, mobile apps, and more. +The Visual Studio build tools include a C compiler that you can use to create everything from basic console programs to full Windows desktop applications and mobile apps. Microsoft C/C++ (MSVC) is a C and C++ compiler that, in its latest versions, conforms to some of the latest C language standards, including C11 and C17. -This walkthrough shows how to create a basic, "Hello, World"-style C program by using a text editor, and then compile it on the command line. If you'd rather work in C++ on the command line, see [Walkthrough: Compiling a Native C++ Program on the Command Line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md). If you'd like to try the Visual Studio IDE instead of using the command line, see [Walkthrough: Working with Projects and Solutions (C++)](../ide/walkthrough-working-with-projects-and-solutions-cpp.md) or [Using the Visual Studio IDE for C++ Desktop Development](../ide/using-the-visual-studio-ide-for-cpp-desktop-development.md). +This guide explains how to create a basic *Hello, World*-style C program by using a text editor, and then compile it on the command line. If you'd rather work in C++ on the command line, see [Walkthrough: Compiling a Native C++ Program on the Command Line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md). If you'd like to try the Visual Studio IDE instead of using the command line, see [Walkthrough: Working with Projects and Solutions (C++)](../ide/walkthrough-working-with-projects-and-solutions-cpp.md) or [Using the Visual Studio IDE for C++ Desktop Development](../ide/using-the-visual-studio-ide-for-cpp-desktop-development.md). ## Prerequisites -To complete this walkthrough, you must have installed either Visual Studio and the optional Visual C++ components, or the Build Tools for Visual Studio. +- Either **Visual Studio** or the **build tools for Visual Studio**, and the **Desktop development with C++** workload + - Visual Studio is a powerful integrated development environment that supports a full-featured editor, resource managers, debuggers, and compilers for many languages and platforms. For information on these features and how to download and install Visual Studio, including the free Visual Studio Community edition, see [Install Visual Studio](/visualstudio/install/install-visual-studio). + - The build tools for Visual Studio install only the command-line toolset, the compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line toolset, download build tools for Visual Studio from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) page and run the installer. In the Visual Studio installer, select the **Desktop development with C++** workload (in older versions of Visual Studio, select the **C++ build tools** workload), and choose **Install**. -Visual Studio is a powerful integrated development environment that supports a full-featured editor, resource managers, debuggers, and compilers for many languages and platforms. For information on these features and how to download and install Visual Studio, including the free Visual Studio Community edition, see [Install Visual Studio](/visualstudio/install/install-visual-studio). - -The Build Tools for Visual Studio version of Visual Studio installs only the command-line toolset, the compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line toolset, download Build Tools for Visual Studio from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) page and run the installer. In the Visual Studio installer, select the **C++ build tools** workload, and choose **Install**. - -Before you can build a C or C++ program on the command line, you must verify that the tools are installed, and that you can access them from the command line. Visual C++ has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use Visual C++ in a plain command prompt window** without some preparation. You need a *developer command prompt* window, which is a regular command prompt window that has all the required environment variables set. Fortunately, Visual C++ installs shortcuts for you to launch developer command prompts that have the environment set up for command line builds. Unfortunately, the names of the developer command prompt shortcuts and where they're located are different in almost every version of Visual C++ and on different versions of Windows. Your first walkthrough task is to find the right shortcut to use. +- **MSVC compiler** + - MSVC has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use MSVC in a plain command prompt window** without some preparation. You need a *developer command prompt* window, which is a regular command prompt window that has all the required environment variables set. Fortunately, Visual Studio installs shortcuts for you to launch developer command prompts that have the environment set up for command line builds. Unfortunately, the names of the developer command prompt shortcuts and where they're located are different in almost every version of Visual Studio and on different versions of Windows. Your first walkthrough task is to find the right shortcut to use. > [!NOTE] > A developer command prompt shortcut automatically sets the correct paths for the compiler and tools, and for any required headers and libraries. Some of these values are different for each build configuration. You must set these environment values yourself if you don't use one of the shortcuts. For more information, see [Use the MSVC toolset from the command line](./building-on-the-command-line.md). Because the build environment is complex, we strongly recommend you use a developer command prompt shortcut instead of building your own. -These instructions vary depending on which version of Visual Studio you are using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +These instructions vary depending on which version of Visual Studio you're using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector located at the top of the table of contents on this page. ::: moniker range="msvc-170" ## Open a developer command prompt in Visual Studio 2022 -If you've installed Visual Studio 2022 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2022** folder (not the Visual Studio 2022 app). Choose **Developer Command Prompt for VS 2022** to open the command prompt window. +If you installed Visual Studio 2022 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2022** folder (not the Visual Studio 2022 app). Choose **Developer Command Prompt for VS 2022** to open the command prompt window. ::: moniker-end @@ -39,7 +38,7 @@ If you've installed Visual Studio 2022 on Windows 10 or later, open the Start me ## Open a developer command prompt in Visual Studio 2019 -If you've installed Visual Studio 2019 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2019** folder (not the Visual Studio 2019 app). Choose **Developer Command Prompt for VS 2019** to open the command prompt window. +If you installed Visual Studio 2019 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2019** folder (not the Visual Studio 2019 app). Choose **Developer Command Prompt for VS 2019** to open the command prompt window. ::: moniker-end @@ -47,7 +46,7 @@ If you've installed Visual Studio 2019 on Windows 10 or later, open the Start me ## Open a developer command prompt in Visual Studio 2017 -If you've installed Visual Studio 2017 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2017** folder (not the Visual Studio 2017 app). Choose **Developer Command Prompt for VS 2017** to open the command prompt window. +If you installed Visual Studio 2017 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual Studio 2017** folder (not the Visual Studio 2017 app). Choose **Developer Command Prompt for VS 2017** to open the command prompt window. ::: moniker-end @@ -55,13 +54,13 @@ If you've installed Visual Studio 2017 on Windows 10 or later, open the Start me ## Open a developer command prompt in Visual Studio 2015 -If you've installed Microsoft Visual C++ Build Tools 2015 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual C++ Build Tools** folder. Choose **Visual C++ 2015 x86 Native Tools Command Prompt** to open the command prompt window. +If you installed Microsoft Visual C++ Build Tools 2015 on Windows 10 or later, open the Start menu, and choose **All apps**. Then, scroll down and open the **Visual C++ Build Tools** folder. Choose **Visual C++ 2015 x86 Native Tools Command Prompt** to open the command prompt window. ::: moniker-end -If you're using a different version of Windows, look in your Start menu or Start page for a Visual Studio tools folder that contains a developer command prompt shortcut. You can also use the Windows search function to search for "developer command prompt" and choose one that matches your installed version of Visual Studio. Use the shortcut to open the command prompt window. +If you're using a different version of Windows, look in your Start menu or Start page for a Visual Studio tools folder that contains a developer command prompt shortcut. You can also use the Windows search function to search for *developer command prompt* and choose one that matches your installed version of Visual Studio. Use the shortcut to open the command prompt window. -Next, verify that the Visual C++ developer command prompt is set up correctly. In the command prompt window, enter `cl` and verify that the output looks something like this: +Next, verify that the developer command prompt is set up correctly. In the command prompt window, enter `cl` (or `CL`, case doesn't matter for the compiler name, but it does matter for compiler options). The output should look something like this: ```Output C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise>cl @@ -71,19 +70,19 @@ Copyright (C) Microsoft Corporation. All rights reserved. usage: cl [ option... ] filename... [ /link linkoption... ] ``` -There may be differences in the current directory or version numbers, depending on the version of Visual C++ and any updates installed. If the above output is similar to what you see, then you're ready to build C or C++ programs at the command line. +There might be differences in the current directory or version numbers, depending on the version of Visual Studio and any updates installed. If the preceding output is similar to what you see, then you're ready to build C or C++ programs at the command line. > [!NOTE] -> If you get an error such as "'cl' is not recognized as an internal or external command, operable program or batch file," error C1034, or error LNK1104 when you run the **cl** command, then either you are not using a developer command prompt, or something is wrong with your installation of Visual C++. You must fix this issue before you can continue. +> If you get an error such as **'cl' is not recognized as an internal or external command, operable program or batch file**, error C1034, or error LNK1104 when you run the `cl` command, then either you're not using a developer command prompt, or something is wrong with your installation of Visual Studio. You must fix this issue before you can continue. -If you can't find the developer command prompt shortcut, or if you get an error message when you enter `cl`, then your Visual C++ installation may have a problem. If you're using Visual Studio 2017 or later, try reinstalling the **Desktop development with C++** workload in the Visual Studio installer. For details, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). Or, reinstall the Build Tools from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/) page. Don't go on to the next section until the `cl` command works. For more information about installing and troubleshooting Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). +If you can't find the developer command prompt shortcut, or if you get an error message when you enter `cl`, then your Visual Studio installation might have a problem. If you're using Visual Studio 2017 or later, try reinstalling the **Desktop development with C++** workload in the Visual Studio installer. For details, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). Or, reinstall the build tools from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/) page. Don't go on to the next section until the `cl` command works. For more information about installing and troubleshooting Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). > [!NOTE] -> Depending on the version of Windows on the computer and the system security configuration, you might have to right-click to open the shortcut menu for the developer command prompt shortcut and then choose **Run as Administrator** to successfully build and run the program that you create by following this walkthrough. +> Depending on the version of Windows on the computer and the system security configuration, you might need to right-click to open the shortcut menu for the developer command prompt shortcut and then choose **Run as Administrator** to successfully build and run the program that you create by following this walkthrough. ## Create a C source file and compile it on the command line -1. In the developer command prompt window, enter `cd c:\` to change the current working directory to the root of your C: drive. Next, enter `md c:\hello` to create a directory, and then enter `cd c:\hello` to change to that directory. This directory will hold your source file and the compiled program. +1. In the developer command prompt window, enter `cd c:\` to change the current working directory to the root of your C: drive. Next, enter `md c:\hello` to create a directory, and then enter `cd c:\hello` to change to that directory. This directory holds your source file and the compiled program. 1. Enter `notepad hello.c` at the developer command prompt. In the Notepad alert dialog that pops up, choose **Yes** to create a new *`hello.c`* file in your working directory. @@ -122,7 +121,7 @@ If you can't find the developer command prompt shortcut, or if you get an error 1. To compile your program, enter `cl hello.c` at the developer command prompt. - You can see the executable program name, hello.exe, in the lines of output information that the compiler displays: + You can see the executable program name, *`hello.exe`*, in the lines of output information that the compiler displays: ```Output c:\hello>cl hello.c @@ -138,7 +137,7 @@ If you can't find the developer command prompt shortcut, or if you get an error ``` > [!NOTE] - > If you get an error such as "'cl' is not recognized as an internal or external command, operable program or batch file," error C1034, or error LNK1104, your developer command prompt is not set up correctly. For information on how to fix this issue, go back to the **Open a developer command prompt** section. + > If you get an error such as **'cl' is not recognized as an internal or external command, operable program or batch file,** error C1034, or error LNK1104, your developer command prompt isn't set up correctly. For information on how to fix this issue, go back to the **Open a developer command prompt** section. > > If you get a different compiler or linker error or warning, review your source code to correct any errors, then save it and run the compiler again. For information about specific errors, use the search box at the top of this page to look for the error number. @@ -152,35 +151,35 @@ If you can't find the developer command prompt shortcut, or if you get an error Congratulations, you've compiled and run a C program by using the command line. -## Next steps +## Advanced steps -This "Hello, World" example is about as basic as a C program can get. Real world programs have header files and more source files, link in libraries, and do useful work. +This *Hello, World* example is about as basic as a C program can get. Real-world programs have header files and more source files, link in libraries, and do useful work. -You can use the steps in this walkthrough to build your own C code instead of typing the sample code shown. You can also build many C code sample programs that you find elsewhere. To compile a program that has additional source code files, enter them all on the command line, like: +You can use the steps in this walkthrough to build your own C code instead of typing the sample code shown. You can also build many C code sample programs that you find elsewhere. To compile a program that has more source code files, enter them all on the command line: `cl file1.c file2.c file3.c` -The compiler outputs a program called file1.exe. To change the name to program1.exe, add an [/out](reference/out-output-file-name.md) linker option: +The compiler outputs a program called *`file1.exe`*. To change the name to *`program1.exe`*, add an [/out](reference/out-output-file-name.md) linker option: `cl file1.c file2.c file3.c /link /out:program1.exe` -And to catch more programming mistakes automatically, we recommend you compile by using either the [/W3](reference/compiler-option-warning-level.md) or [/W4](reference/compiler-option-warning-level.md) warning level option: +And to catch more programming mistakes automatically, we recommend you compile by using either the [/W3 or /W4](reference/compiler-option-warning-level.md) warning level option: `cl /W4 file1.c file2.c file3.c /link /out:program1.exe` -The compiler, cl.exe, has many more options you can apply to build, optimize, debug, and analyze your code. For a quick list, enter `cl /?` at the developer command prompt. You can also compile and link separately and apply linker options in more complex build scenarios. For more information on compiler and linker options and usage, see [C/C++ Building Reference](reference/c-cpp-building-reference.md). +The compiler, *`cl.exe`*, has many more options you can apply to build, optimize, debug, and analyze your code. For a quick list, enter `cl /?` at the developer command prompt. You can also compile and link separately and apply linker options in more complex build scenarios. For more information on compiler and linker options and usage, see [C/C++ Building Reference](reference/c-cpp-building-reference.md). You can use NMAKE and makefiles, or MSBuild and project files to configure and build more complex projects on the command line. For more information on using these tools, see [NMAKE Reference](reference/nmake-reference.md) and [MSBuild](msbuild-visual-cpp.md). -The C and C++ languages are similar, but not the same. The Microsoft C/C++ compiler (MSVC) uses a basic rule to determine which language to use when it compiles your code. By default, the MSVC compiler treats all files that end in *`.c`* as C source code, and all files that end in *`.cpp`* as C++ source code. To force the compiler to treat all files as C no matter the file name extension, use the [/TC](reference/tc-tp-tc-tp-specify-source-file-type.md) compiler option. +The C and C++ languages are similar, but not the same. The MSVC compiler uses a basic rule to determine which language to use when it compiles your code. By default, the MSVC compiler treats all files that end in *`.c`* as C source code, and all files that end in *`.cpp`* as C++ source code. To force the compiler to treat all files as C no matter the file name extension, use the [/TC](reference/tc-tp-tc-tp-specify-source-file-type.md) compiler option. -MSVC is compatible with the ANSI C89 and ISO C99 standards, but not strictly conforming. In most cases, portable C code will compile and run as expected. The compiler provides optional support for the changes in ISO C11/C17. To compile with C11/C17 support, use the compiler flag **`/std:c11`** or **`/std:c17`**. C11/C17 support requires Windows SDK 10.0.20201.0 or later. Windows SDK 10.0.22000.0 or later is recommended. You can download the latest SDK from the [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk/) page. For more information, and instructions on how to install and use this SDK for C development, see [Install C11 and C17 support in Visual Studio](../overview/install-c17-support.md). +By default, MSVC is compatible with the ANSI C89 and ISO C99 standards, but not strictly conforming. In most cases, portable C code compiles and runs as expected. The compiler provides optional support for the changes in ISO C11 and C17. To compile with C11 and C17 support, use the compiler flag `/std:c11` or `/std:c17`. C11 and C17 support requires Windows SDK 10.0.20201.0 or later. Windows SDK 10.0.22000.0 or later is recommended. You can download the latest SDK from the [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk/) page. For more information, and instructions on how to install and use this SDK for C development, see [Install C11 and C17 support in Visual Studio](../overview/install-c17-support.md). Certain library functions and POSIX function names are deprecated by MSVC. The functions are supported, but the preferred names have changed. For more information, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md) and [Compiler Warning (level 3) C4996](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). ## See also -[Walkthrough: Creating a Standard C++ Program (C++)](../windows/walkthrough-creating-a-standard-cpp-program-cpp.md)
-[C Language Reference](../c-language/c-language-reference.md)
-[Projects and build systems](projects-and-build-systems-cpp.md)
-[Compatibility](../c-runtime-library/compatibility.md) +- [Walkthrough: Create a Standard C++ Program](../windows/walkthrough-creating-a-standard-cpp-program-cpp.md) +- [C Language Reference](../c-language/c-language-reference.md) +- [C/C++ projects and build systems](projects-and-build-systems-cpp.md) +- [Compatibility](../c-runtime-library/compatibility.md) diff --git a/docs/build/walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md b/docs/build/walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md index 6e37f2a46c..1bf1c0904f 100644 --- a/docs/build/walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md @@ -26,6 +26,8 @@ To enable compilation for C++/CLI, you must use the [/clr](reference/clr-common- Administrator credentials may be required to successfully compile the code, depending on the computer's operating system and configuration. To run the command prompt window as an administrator, right-click to open the shortcut menu for the command prompt and then choose **More** > **Run as administrator**. +1. Change the current working directory in the command prompt window to a directory you can write to, such as your Documents directory. + 1. At the command prompt, enter `notepad basicclr.cpp`. Choose **Yes** when you're prompted to create a file. diff --git a/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md b/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md index 474a424a2d..8ab636443f 100644 --- a/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md @@ -26,9 +26,11 @@ To enable compilation for C++/CX, you must use the [/ZW](reference/zw-windows-ru #### To compile a C++/CX application on the command line -1. Open a **Developer Command Prompt** window. (On the **Start** window, open **Apps**. Open the **Visual Studio Tools** folder under your version of Visual Studio, and then choose the **Developer Command Prompt** shortcut.) For more information about how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](building-on-the-command-line.md). +1. Open a **Developer Command Prompt** window. For specific instructions, see [To open a developer command prompt window](building-on-the-command-line.md#developer_command_prompt). - Administrator credentials may be required to successfully compile the code, depending on the computer's operating system and configuration. To run the Command Prompt window as an administrator, open the shortcut menu for **Developer Command Prompt** and then choose **Run as administrator**. + Administrator credentials may be required to successfully compile the code, depending on the computer's operating system and configuration. To run the command prompt window as an administrator, right-click to open the shortcut menu for the command prompt and then choose **More** > **Run as administrator**. + +1. Change the current working directory in the command prompt window to a directory you can write to, such as your Documents directory. 1. At the command prompt, enter **notepad basiccx.cpp**. @@ -49,7 +51,7 @@ To enable compilation for C++/CX, you must use the [/ZW](reference/zw-windows-ru You've created a C++ source file that uses the Windows Runtime [Platform namespace](../cppcx/platform-namespace-c-cx.md) namespace. -1. At the command prompt, enter **cl /EHsc /ZW basiccx.cpp /link /SUBSYSTEM:CONSOLE**. The cl.exe compiler compiles the source code into an .obj file, and then runs the linker to generate an executable program named basiccx.exe. (The [/EHsc](reference/eh-exception-handling-model.md) compiler option specifies the C++ exception-handling model, and the [/link](reference/link-pass-options-to-linker.md) flag specifies a console application.) +1. At the command prompt, enter `cl /EHsc /ZW basiccx.cpp /link /SUBSYSTEM:CONSOLE`. The `cl.exe` compiler compiles the source code into an `.obj` file, and then runs the linker to generate an executable program named basiccx.exe. The [/EHsc](reference/eh-exception-handling-model.md) compiler option specifies the C++ exception-handling model, and the [/link](reference/link-pass-options-to-linker.md) flag specifies a console application. 1. To run the basiccx.exe program, at the command prompt, enter **basiccx**. diff --git a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md index 03f3e090ca..5cd2502e96 100644 --- a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md @@ -139,7 +139,7 @@ Before you can build a C or C++ program on the command line, verify that the too This "Hello, World" example is about as simple as a C++ program can get. Real world programs usually have header files, more source files, and link to libraries. -You can use the steps in this walkthrough to build your own C++ code instead of typing the sample code shown. These steps also let you build many C++ code sample programs that you find elsewhere. You can put your source code and build your apps in any writeable directory. By default, the Visual Studio IDE creates projects in your user folder, in a *source\\repos* subfolder. Older versions may put projects in a *Documents\\Visual Studio \\\*Projects* folder. +You can use the steps in this walkthrough to build your own C++ code instead of typing the sample code shown. These steps also let you build many C++ code sample programs that you find elsewhere. You can put your source code and build your apps in any writeable directory. By default, the Visual Studio IDE creates projects in your user folder, in a *source\\repos* subfolder. Older versions may put projects in a *Documents\\Visual Studio \\\Projects* folder. To compile a program that has additional source code files, enter them all on the command line, like: diff --git a/docs/build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md b/docs/build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md index 0228b1f047..ad06919a0c 100644 --- a/docs/build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md +++ b/docs/build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md @@ -1,60 +1,55 @@ --- -title: "Walkthrough: Create and use your own Dynamic Link Library (C++)" -description: "Use C++ to create a Windows dynamic-link library (DLL) in Visual Studio." -ms.custom: "contperf-fy21q2" +title: "Create and Use Your Own Dynamic-Link Library (C++)" +description: "Learn how to use C++ to create a Windows dynamic-link library (DLL) in Visual Studio." ms.topic: tutorial -ms.date: 12/09/2021 +ms.date: 03/17/2025 helpviewer_keywords: ["libraries [C++], DLLs", "DLLs [C++], walkthroughs"] --- -# Walkthrough: Create and use your own Dynamic Link Library (C++) +# Walkthrough: Create and use your own dynamic-link library (C++) -This step-by-step walkthrough shows how to use the Visual Studio IDE to create your own dynamic link library (DLL) written in Microsoft C++ (MSVC). Then it shows how to use the DLL from another C++ app. DLLs (also known as *shared libraries* in UNIX-based operating systems) are one of the most useful kinds of Windows components. You can use them as a way to share code and resources, and to shrink the size of your apps. DLLs can even make it easier to service and extend your apps. +This step-by-step walkthrough explains how to use the Visual Studio IDE to create your own dynamic-link library (DLL) written in Microsoft C++ (MSVC), and how to use the DLL from another C++ app. DLLs, also known as *shared libraries* in UNIX-based operating systems, are one of the most useful kinds of Windows components. You can use them to share code and resources, and to shrink the size of your apps. DLLs can even make it easier to service and extend your apps. -In this walkthrough, you'll create a DLL that implements some math functions. Then you'll create a console app that uses the functions from the DLL. You'll also get an introduction to some of the programming techniques and conventions used in Windows DLLs. +In this walkthrough, you create a DLL that implements some math functions. Then you create a console app that uses the functions from the DLL. You also get an introduction to some of the programming techniques and conventions used in Windows DLLs. -This walkthrough covers these tasks: +This walkthrough covers the following steps: - Create a DLL project in Visual Studio. - - Add exported functions and variables to the DLL. - - Create a console app project in Visual Studio. - - Use the functions and variables imported from the DLL in the console app. - - Run the completed app. Like a statically linked library, a DLL _exports_ variables, functions, and resources by name. A client app _imports_ the names to use those variables, functions, and resources. Unlike a statically linked library, Windows connects the imports in your app to the exports in a DLL at load time or at run time, instead of connecting them at link time. Windows requires extra information that isn't part of the standard C++ compilation model to make these connections. The MSVC compiler implements some Microsoft-specific extensions to C++ to provide this extra information. We explain these extensions as we go. -This walkthrough creates two Visual Studio solutions; one that builds the DLL, and one that builds the client app. The DLL uses the C calling convention. It can be called from apps written in other programming languages, as long as the platform, calling conventions, and linking conventions match. The client app uses _implicit linking_, where Windows links the app to the DLL at load-time. This linking lets the app call the DLL-supplied functions just like the functions in a statically linked library. +This walkthrough creates two Visual Studio solutions: one that builds the DLL, and one that builds the client app. The DLL uses the C calling convention. It can be called from apps written in other programming languages, as long as the platform, calling conventions, and linking conventions match. The client app uses _implicit linking_, where Windows links the app to the DLL at load time. This linking lets the app call the DLL-supplied functions just like the functions in a statically linked library. -This walkthrough doesn't cover some common situations. The code doesn't show the use of C++ DLLs by other programming languages. It doesn't show how to [create a resource-only DLL](creating-a-resource-only-dll.md), or how to use [explicit linking](linking-an-executable-to-a-dll.md#linking-explicitly) to load DLLs at run-time rather than at load-time. Rest assured, you can use MSVC and Visual Studio to do all these things. +This walkthrough doesn't cover some common situations. The code doesn't show the use of C++ DLLs by other programming languages. It doesn't show how to [create a resource-only DLL](creating-a-resource-only-dll.md), or how to use [explicit linking](linking-an-executable-to-a-dll.md#linking-explicitly) to load DLLs at run time rather than at load time. Rest assured, you can use MSVC and Visual Studio to do all these things. -Even though the code of the DLL is written in C++, we've used C-style interfaces for the exported functions. There are two main reasons for this: First, many other languages support imports of C-style functions. The client app doesn't have to be written in C++. Second, it avoids some common pitfalls related to exported classes and member functions. It's easy to make hard-to-diagnose errors when exporting classes, since everything referred to within a class declaration has to have an instantiation that's also exported. This restriction applies to DLLs, but not static libraries. If your classes are plain-old-data style, you shouldn't run into this issue. +Even though the code of the DLL is written in C++, we use C-style interfaces for the exported functions. There are two main reasons for this: First, many other languages support imports of C-style functions. The client app doesn't have to be written in C++. Second, it avoids some common pitfalls related to exported classes and member functions. It's easy to make hard-to-diagnose errors when exporting classes, since everything referred to within a class declaration has to have an instantiation that's also exported. This restriction applies to DLLs, but not static libraries. If your classes are plain-old-data style, you shouldn't run into this issue. For links to more information about DLLs, see [Create C/C++ DLLs in Visual Studio](dlls-in-visual-cpp.md). For more information about implicit linking and explicit linking, see [Determine which linking method to use](linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use). For information about creating C++ DLLs for use with programming languages that use C-language linkage conventions, see [Exporting C++ functions for use in C-language executables](exporting-cpp-functions-for-use-in-c-language-executables.md). For information about how to create DLLs for use with .NET languages, see [Calling DLL Functions from Visual Basic Applications](calling-dll-functions-from-visual-basic-applications.md). ## Prerequisites -- A computer that runs Microsoft Windows 7 or later versions. We recommend the latest version of Windows for the best development experience. +- Microsoft Windows 7 or later. We recommend the latest version of Windows for the best development experience. ::: moniker range=">=msvc-150" -- A copy of Visual Studio. For information on how to download and install Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). When you run the installer, make sure that the **Desktop development with C++** workload is checked. Don't worry if you didn't install this workload when you installed Visual Studio. You can run the installer again and install it now. +- Visual Studio. To learn how to download and install Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). When you run the installer, make sure that the **Desktop development with C++** workload is checked. Don't worry if you didn't install this workload when you installed Visual Studio. You can run the installer again and install it now. - ![Visual Studio Installer, Desktop development with C++ workload.](media/desktop-development-with-cpp.png "Desktop development with C++") + :::image type="content" source="media/desktop-development-with-cpp.png" alt-text="Screenshot of the Visual Studio Installer, Desktop development with C++ workload."::: ::: moniker-end ::: moniker range="msvc-140" -- A copy of Visual Studio. For information on how to download and install Visual Studio 2015, see [Install Visual Studio 2015](/visualstudio/install/install-visual-studio-2015?view=vs-2015&preserve-view=true). Use a **Custom** installation to install the C++ compiler and tools, since they're not installed by default. +- Visual Studio. For information on how to download and install Visual Studio 2015, see [Install Visual Studio 2015](/visualstudio/install/install-visual-studio-2015?view=vs-2015&preserve-view=true). Use a **Custom** installation to install the C++ compiler and tools, since they're not installed by default. ::: moniker-end - An understanding of the basics of using the Visual Studio IDE. If you've used Windows desktop apps before, you can probably keep up. For an introduction, see [Visual Studio IDE feature tour](/visualstudio/ide/visual-studio-ide). -- An understanding of enough of the fundamentals of the C++ language to follow along. Don't worry, we don't do anything too complicated. +- Some familiarity with the C++ language. Don't worry, we don't do anything too complicated. ::: moniker range="msvc-150" @@ -65,15 +60,15 @@ For links to more information about DLLs, see [Create C/C++ DLLs in Visual Studi ## Create the DLL project -In this set of tasks, you create a project for your DLL, add code, and build it. To begin, start the Visual Studio IDE, and sign in if you need to. The instructions vary slightly depending on which version of Visual Studio you're using. Make sure you have the correct version selected in the control in the upper left of this page. +In the following set of tasks, you create a project for your DLL, add code, and build it. To begin, start the Visual Studio IDE, and sign in if you need to. The instructions vary slightly depending on which version of Visual Studio you're using. To see the steps for your preferred version of Visual Studio, use the **Version** selector located at the top of the table of contents on this page. ::: moniker range=">=msvc-160" -### To create a DLL project in Visual Studio 2019 +### To create a DLL project in Visual Studio 1. On the menu bar, choose **File** > **New** > **Project** to open the **Create a New Project** dialog box. - ![Screenshot of the Create a new project dialog with the Dynamic Link Library template highlighted.](media/create-new-dll-project-2019.png "Create the MathLibrary project") + :::image type="content" source="media/create-new-dll-project-2019.png" alt-text="Screenshot of the Create a new project dialog box with the dynamic-link library template highlighted."::: 1. At the top of the dialog, set **Language** to **C++**, set **Platform** to **Windows**, and set **Project type** to **Library**. @@ -85,7 +80,7 @@ In this set of tasks, you create a project for your DLL, add code, and build it. When the solution is created, you can see the generated project and source files in the **Solution Explorer** window in Visual Studio. -![Screenshot of the Solution Explorer window with the Math Library project highlighted.](media/mathlibrary-solution-explorer-162.png "Generated solution in Visual Studio") + :::image type="content" source="media/mathlibrary-solution-explorer-162.png" alt-text="Screenshot of the Solution Explorer window with the MathLibrary project highlighted."::: ::: moniker-end @@ -97,13 +92,13 @@ When the solution is created, you can see the generated project and source files 1. In the left pane of the **New Project** dialog box, select **Installed** > **Visual C++** > **Windows Desktop**. In the center pane, select **Dynamic-Link Library (DLL)**. Enter *MathLibrary* in the **Name** box to specify a name for the project. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Check **Create directory for solution** if it's unchecked. - ![Screenshot of the New Project dialog box showing Math Library in the Name text box.](media/mathlibrary-new-project-name-159.png "Name the MathLibrary project") + :::image type="content" source="media/mathlibrary-new-project-name-159.png" alt-text="Screenshot of the New Project dialog box in Visual Studio 2017 showing Math Library in the Name text box."::: 1. Choose the **OK** button to create the project. When the solution is created, you can see the generated project and source files in the **Solution Explorer** window in Visual Studio. -![Screenshot of the Solution Explorer window with the Math Library highlighted.](media/mathlibrary-solution-explorer-159.png "Generated solution in Visual Studio") +:::image type="content" source="media/mathlibrary-solution-explorer-159.png" alt-text="Screenshot of the Solution Explorer window in Visual Studio 2017 with the Math Library highlighted."::: ::: moniker-end @@ -115,21 +110,21 @@ When the solution is created, you can see the generated project and source files 1. In the left pane of the **New Project** dialog box, expand **Installed** > **Templates**, and select **Visual C++**, and then in the center pane, select **Win32 Console Application**. Enter *MathLibrary* in the **Name** edit box to specify a name for the project. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Check **Create directory for solution** if it's unchecked. - ![Screenshot of the New Project dialog box showing Math Library in the Name text box.](media/mathlibrary-project-name.png "Name the MathLibrary project") + :::image type="content" source="media/mathlibrary-project-name.png" alt-text="Screenshot of the New Project dialog box in Visual Studio 2015 showing MathLibrary in the Name text box."::: 1. Choose the **OK** button to dismiss the **New Project** dialog and start the **Win32 Application Wizard**. - ![Screenshot of the Win32 Application Wizard Overview page.](media/mathlibrary-project-wizard-1.png "Win32 Application Wizard Overview") + :::image type="content" source="media/mathlibrary-project-wizard-1.png" alt-text="Screenshot of the Win32 Application Wizard Overview page."::: 1. Choose the **Next** button. On the **Application Settings** page, under **Application type**, select **DLL**. - ![Screenshot of the Win32 Application Wizard Application Settings Page.](media/mathlibrary-project-wizard-2.png "Create DLL in Win32 Application Wizard") + :::image type="content" source="media/mathlibrary-project-wizard-2.png" alt-text="Screenshot of the Win32 Application Wizard Application Settings Page."::: 1. Choose the **Finish** button to create the project. When the wizard completes the solution, you can see the generated project and source files in the **Solution Explorer** window in Visual Studio. -![Screenshot of the Solution Explorer window with the Math Library highlighted.](media/mathlibrary-solution-explorer-153.png "Generated solution in Visual Studio") +:::image type="content" source="media/mathlibrary-solution-explorer-153.png" alt-text="Screenshot of the Solution Explorer window in Visual Studio 2015 with the MathLibrary highlighted."::: ::: moniker-end @@ -139,13 +134,13 @@ Right now, this DLL doesn't do very much. Next, you'll create a header file to d 1. To create a header file for your functions, on the menu bar, choose **Project** > **Add New Item**. -1. In the **Add New Item** dialog box, in the left pane, select **Visual C++**. In the center pane, select **Header File (.h)**. Specify *MathLibrary.h* as the name for the header file. +1. In the **Add New Item** dialog box, in the left pane, select **Visual C++**. In the center pane, select **Header File (.h)**. Specify *`MathLibrary.h`* as the name for the header file. - ![Screenshot of the Add New Item dialog with the C plus plus Header File template selected, and MathLibrary.h entered in the Name textbox.](media/mathlibrary-add-new-item-header-file.png "Add header file in Add New Item dialog") + :::image type="content" source="media/mathlibrary-add-new-item-header-file.png" alt-text="Screenshot of the Add New Item dialog with the C plus plus Header File template selected, and MathLibrary.h entered in the Name textbox."::: 1. Choose the **Add** button to generate a blank header file, which is displayed in a new editor window. - ![Screenshot of the empty MathLibrary.h file in the editor.](media/edit-empty-mathlibrary-header.png "Empty MathLibrary.h file in editor") + :::image type="content" source="media/edit-empty-mathlibrary-header.png" alt-text="Screenshot of the empty MathLibrary.h file in the editor."::: 1. Replace the contents of the header file with this code: @@ -196,11 +191,11 @@ When the `MATHLIBRARY_EXPORTS` macro is defined, the `MATHLIBRARY_API` macro set ::: moniker range=">=msvc-160" -1. In **Solution Explorer**, right-click on the **Source Files** node and choose **Add** > **New Item**. Create a new .cpp file called *MathLibrary.cpp*, in the same way that you added a new header file in the previous step. +1. In **Solution Explorer**, right-click on the **Source Files** node and choose **Add** > **New Item**. Create a new *`.cpp`* file called *`MathLibrary.cpp`*, in the same way that you added a new header file in the previous step. -1. In the editor window, select the tab for **MathLibrary.cpp** if it's already open. If not, in **Solution Explorer**, double-click **MathLibrary.cpp** in the **Source Files** folder of the **MathLibrary** project to open it. +1. In the editor window, select the *`MathLibrary.cpp`* tab if it's already open. If not, in **Solution Explorer**, double-click *`MathLibrary.cpp`* in the **Source Files** folder of the **MathLibrary** project to open it. -1. In the editor, replace the contents of the MathLibrary.cpp file with the following code: +1. In the editor, replace the contents of the *`MathLibrary.cpp`* file with the following code: ```cpp // MathLibrary.cpp : Defines the exported functions for the DLL. @@ -267,7 +262,7 @@ When the `MATHLIBRARY_EXPORTS` macro is defined, the `MATHLIBRARY_API` macro set 1. In the editor window, select the tab for **MathLibrary.cpp** if it's already open. If not, in **Solution Explorer**, double-click **MathLibrary.cpp** in the **Source Files** folder of the **MathLibrary** project to open it. -1. In the editor, replace the contents of the MathLibrary.cpp file with the following code: +1. In the editor, replace the contents of the *`MathLibrary.cpp`* file with the following code: ```cpp // MathLibrary.cpp : Defines the exported functions for the DLL. @@ -330,7 +325,7 @@ When the `MATHLIBRARY_EXPORTS` macro is defined, the `MATHLIBRARY_API` macro set ::: moniker-end -To verify that everything works so far, compile the dynamic link library. To compile, choose **Build** > **Build Solution** on the menu bar. The DLL and related compiler output are placed in a folder called *Debug* directly below the solution folder. If you create a Release build, the output is placed in a folder called *Release*. The output should look something like this: +To verify that everything works so far, compile the DLL. To compile, choose **Build** > **Build Solution** on the menu bar. The DLL and related compiler output are placed in a folder called `Debug` directly below the solution folder. If you create a Release build, the output is placed in a folder called `Release`. The output should look something like this: ::: moniker range=">=msvc-160" @@ -381,9 +376,9 @@ Congratulations, you've created a DLL using Visual Studio! Next, you'll create a ## Create a client app that uses the DLL -When you create a DLL, think about how client apps may use it. To call the functions or access the data exported by a DLL, client source code must have the declarations available at compile time. At link time, the linker requires information to resolve the function calls or data accesses. A DLL supplies this information in an *import library*, a file that contains information about how to find the functions and data, instead of the actual code. And at run time, the DLL must be available to the client, in a location that the operating system can find. +When you create a DLL, think about how client apps might use it. To call the functions or access the data exported by a DLL, client source code must have the declarations available at compile time. At link time, the linker requires information to resolve the function calls or data accesses. A DLL supplies this information in an *import library*, a file that contains information about how to find the functions and data, instead of the actual code. And at run time, the DLL must be available to the client, in a location that the operating system can find. -Whether it's your own or from a third-party, your client app project needs several pieces of information to use a DLL. It needs to find the headers that declare the DLL exports, the import libraries for the linker, and the DLL itself. One solution is to copy all of these files into your client project. For third-party DLLs that are unlikely to change while your client is in development, this method may be the best way to use them. However, when you also build the DLL, it's better to avoid duplication. If you make a local copy of DLL files that are under development, you may accidentally change a header file in one copy but not the other, or use an out-of-date library. +Whether it's your own or from a third-party, your client app project needs several pieces of information to use a DLL. It needs to find the headers that declare the DLL exports, the import libraries for the linker, and the DLL itself. One solution is to copy all of these files into your client project. For third-party DLLs that are unlikely to change while your client is in development, this method might be the best way to use them. However, when you also build the DLL, it's better to avoid duplication. If you make a local copy of DLL files that are under development, you might accidentally change a header file in one copy but not the other, or use an out-of-date library. To avoid out-of-sync code, we recommend you set the include path in your client project to include the DLL header files directly from your DLL project. Also, set the library path in your client project to include the DLL import libraries from the DLL project. And finally, copy the built DLL from the DLL project into your client build output directory. This step allows your client app to use the same DLL code you build. @@ -399,11 +394,11 @@ To avoid out-of-sync code, we recommend you set the include path in your client 1. In the **Configure your new project** page, enter *MathClient* in the **Project name** box to specify a name for the project. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Uncheck **Place solution and project in the same directory** if it's checked. - ![Screenshot of the Create a new project dialog box with the Console App option highlighted.](media/mathclient-project-name-2019.png "Name the client project") + :::image type="content" source="media/mathclient-project-name-2019.png" alt-text="Screenshot of the Create a new project dialog box with the Console App option highlighted."::: 1. Choose the **Create** button to create the client project. -A minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named **MathClient.cpp**. You can build it, but it doesn't use your DLL yet. +A minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named *`MathClient.cpp`*. You can build it, but it doesn't use your DLL yet. ::: moniker-end @@ -413,13 +408,13 @@ A minimal console application project is created for you. The name for the main 1. To create a C++ app that uses the DLL that you created, on the menu bar, choose **File** > **New** > **Project**. -1. In the left pane of the **New Project** dialog, select **Windows Desktop** under **Installed** > **Visual C++**. In the center pane, select **Windows Console Application**. Specify the name for the project, *MathClient*, in the **Name** edit box. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Check **Create directory for solution** if it's unchecked. +1. In the left pane of the **New Project** dialog, select **Windows Desktop** under **Installed** > **Visual C++**. In the center pane, select **Windows Console Application**. Specify the name for the project, *MathClient*, in the **Name** edit box. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Check **Create directory for solution** if it's unchecked. - ![Screenshot of the New Project dialog box with Installed > Visual C plus plus > Windows Desktop selected, Windows Console Application highlighted, and Math Client typed in the Name text box.](media/mathclient-new-project-name-159.png "Name the client project") + :::image type="content" source="media/mathclient-new-project-name-159.png" alt-text="Screenshot of the New Project dialog box with Windows Console Application highlighted, and Math Client typed in the Name text box."::: 1. Choose **OK** to create the client app project. -A minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named **MathClient.cpp**. You can build it, but it doesn't use your DLL yet. +A minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named *`MathClient.cpp`*. You can build it, but it doesn't use your DLL yet. ::: moniker-end @@ -431,7 +426,7 @@ A minimal console application project is created for you. The name for the main 1. In the left pane of the **New Project** dialog, select **Win32** under **Installed** > **Templates** > **Visual C++**. In the center pane, select **Win32 Console Application**. Specify the name for the project, *MathClient*, in the **Name** edit box. Leave the default **Location** and **Solution name** values. Set **Solution** to **Create new solution**. Check **Create directory for solution** if it's unchecked. - ![Screenshot of the New Project dialog box with Installed > Templates > Visual C plus plus > Win32 selected, Win32 Console Application Visual C plus plus highlighted, and Math Client typed in the Name text box.](media/mathclient-project-name.png "Name the client project") + :::image type="content" source="media/mathclient-project-name.png" alt-text="Screenshot of the New Project dialog box with Win32 Console Application Visual C plus plus highlighted, and Math Client typed in the Name text box."::: 1. Choose the **OK** button to dismiss the **New Project** dialog and start the **Win32 Application Wizard**. On the **Overview** page of the **Win32 Application Wizard** dialog box, choose the **Next** button. @@ -439,27 +434,27 @@ A minimal console application project is created for you. The name for the main 1. Choose the **Finish** button to create the project. -When the wizard finishes, a minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named **MathClient.cpp**. You can build it, but it doesn't use your DLL yet. +When the wizard finishes, a minimal console application project is created for you. The name for the main source file is the same as the project name that you entered earlier. In this example, it's named *`MathClient.cpp`*. You can build it, but it doesn't use your DLL yet. ::: moniker-end -Next, to call the MathLibrary functions in your source code, your project must include the *MathLibrary.h* file. You could copy this header file into your client app project, then add it to the project as an existing item. This method can be a good choice for third-party libraries. However, if you're working on the code for your DLL and your client at the same time, the header files could get out of sync. To avoid this issue, set the **Additional Include Directories** path in your project to include the path to the original header. +Next, to call the MathLibrary functions in your source code, your project must include the *`MathLibrary.h`* file. You could copy this header file into your client app project, then add it to the project as an existing item. This method can be a good choice for third-party libraries. However, if you're working on the code for your DLL and your client at the same time, the header files could get out of sync. To avoid this issue, set the **Additional Include Directories** path in your project to include the path to the original header. ### To add the DLL header to your include path 1. Right-click on the **MathClient** node in **Solution Explorer** to open the **Property Pages** dialog. -1. In the **Configuration** drop-down box, select **All Configurations** if it's not already selected. +1. In the **Configuration** dropdown box, select **All Configurations** if it's not already selected. 1. In the left pane, select **Configuration Properties** > **C/C++** > **General**. -1. In the property pane, select the drop-down control next to the **Additional Include Directories** edit box, and then choose **Edit**. +1. In the property pane, select the dropdown control next to the **Additional Include Directories** edit box, and then choose **Edit**. - ![Screenshot of the Property Pages dialog showing the Edit command in the Additional Include Directories property drop-down.](media/mathclient-additional-include-directories-property.png "Edit the Additional Include Directories property") + :::image type="content" source="media/mathclient-additional-include-directories-property.png" alt-text="Screenshot of the Property Pages dialog showing the Edit command in the Additional Include Directories property dropdown."::: 1. Double-click in the top pane of the **Additional Include Directories** dialog box to enable an edit control. Or, choose the folder icon to create a new entry. -1. In the edit control, specify the path to the location of the **MathLibrary.h** header file. You can choose the ellipsis (**...**) control to browse to the correct folder. +1. In the edit control, specify the path to the location of the *`MathLibrary.h`* header file. You can choose the ellipsis (**...**) control to browse to the correct folder. You can also enter a relative path from your client source files to the folder that contains the DLL header files. If you followed the directions to put your client project in a separate solution from the DLL, the relative path should look like this: @@ -471,11 +466,11 @@ Next, to call the MathLibrary functions in your source code, your project must i When the DLL and client projects are in other folders, adjust the relative path to match. Or, use the ellipsis control to browse for the folder. - ![Screenshot of the Additional Include Directories dialog showing the relative path to the MathLibrary directory.](media/mathclient-additional-include-directories.png "Add the header location to the Additional Include Directories property") + :::image type="content" source="media/mathclient-additional-include-directories.png" alt-text="Screenshot of the Additional Include Directories dialog showing the relative path to the MathLibrary directory."::: 1. After you've entered the path to the header file in the **Additional Include Directories** dialog box, choose the **OK** button. In the **Property Pages** dialog box, choose the **OK** button to save your changes. -You can now include the **MathLibrary.h** file and use the functions it declares in your client application. Replace the contents of **MathClient.cpp** by using this code: +You can now include the *`MathLibrary.h`* file and use the functions it declares in your client application. Replace the contents of *`MathClient.cpp`* by using this code: ```cpp // MathClient.cpp : Client app for MathLibrary DLL. @@ -499,51 +494,51 @@ int main() } ``` -This code can be compiled, but not linked. If you build the client app now, the error list shows several LNK2019 errors. That's because your project is missing some information: You haven't specified that your project has a dependency on the *MathLibrary.lib* library yet. And, you haven't told the linker how to find the *MathLibrary.lib* file. +This code can be compiled, but not linked. If you build the client app now, the error list shows several LNK2019 errors. That's because your project is missing some information: You haven't specified that your project has a dependency on the *`MathLibrary.lib`* library yet. And, you haven't told the linker how to find the *`MathLibrary.lib`* file. -To fix this issue, you could copy the library file directly into your client app project. The linker would find and use it automatically. However, if both the library and the client app are under development, that might lead to changes in one copy that aren't shown in the other. To avoid this issue, you can set the **Additional Dependencies** property to tell the build system that your project depends on *MathLibrary.lib*. And, you can set an **Additional Library Directories** path in your project to include the path to the original library when you link. +To fix this issue, you could copy the library file directly into your client app project. The linker would find and use it automatically. However, if both the library and the client app are under development, that might lead to changes in one copy that aren't shown in the other. To avoid this issue, you can set the **Additional Dependencies** property to tell the build system that your project depends on *`MathLibrary.lib`*. And, you can set an **Additional Library Directories** path in your project to include the path to the original library when you link. ### To add the DLL import library to your project 1. Right-click on the **MathClient** node in **Solution Explorer** and choose **Properties** to open the **Property Pages** dialog. -1. In the **Configuration** drop-down box, select **All Configurations** if it's not already selected. It ensures that any property changes apply to both Debug and Release builds. +1. In the **Configuration** dropdown box, select **All Configurations** if it's not already selected. It ensures that any property changes apply to both Debug and Release builds. -1. In the left pane, select **Configuration Properties** > **Linker** > **Input**. In the property pane, select the drop-down control next to the **Additional Dependencies** edit box, and then choose **Edit**. +1. In the left pane, select **Configuration Properties** > **Linker** > **Input**. In the property pane, select the dropdown control next to the **Additional Dependencies** edit box, and then choose **Edit**. - ![Screenshot of the Property Pages dialog showing the Edit command in the Linker > Input > Additional Dependencies property drop-down.](media/mathclient-additional-dependencies-property.png "Edit the Additional Dependencies property") + :::image type="content" source="media/mathclient-additional-dependencies-property.png" alt-text="Screenshot of the Property Pages dialog box under Input that shows the Edit command in the Additional Dependencies property dropdown."::: -1. In the **Additional Dependencies** dialog, add *MathLibrary.lib* to the list in the top edit control. +1. In the **Additional Dependencies** dialog, add *`MathLibrary.lib`* to the list in the top edit control. - ![Screenshot of the Additional Dependencies dialog showing the MathLibrary.lib file.](media/mathclient-additional-dependencies.png "Add the library dependency") + :::image type="content" source="media/mathclient-additional-dependencies.png" alt-text="Screenshot of the Additional Dependencies dialog box showing the MathLibrary.lib file."::: 1. Choose **OK** to go back to the **Property Pages** dialog box. -1. In the left pane, select **Configuration Properties** > **Linker** > **General**. In the property pane, select the drop-down control next to the **Additional Library Directories** edit box, and then choose **Edit**. +1. In the left pane, select **Configuration Properties** > **Linker** > **General**. In the property pane, select the dropdown control next to the **Additional Library Directories** edit box, and then choose **Edit**. - ![Screenshot of the Property Pages dialog showing the Edit command in the Linker > General > Additional Library Directories property drop-down.](media/mathclient-additional-library-directories-property.png "Edit the Additional Library Directories property") + :::image type="content" source="media/mathclient-additional-library-directories-property.png" alt-text="Screenshot of the Property Pages dialog box under General that shows the Edit command in the Additional Library Directories property dropdown."::: -1. Double-click in the top pane of the **Additional Library Directories** dialog box to enable an edit control. In the edit control, specify the path to the location of the **MathLibrary.lib** file. By default, it's in a folder called *Debug* directly under the DLL solution folder. If you create a release build, the file is placed in a folder called *Release*. You can use the `$(IntDir)` macro so that the linker can find your DLL, no matter which kind of build you create. If you followed the directions to put your client project in a separate solution from the DLL project, the relative path should look like this: +1. Double-click in the top pane of the **Additional Library Directories** dialog box to enable an edit control. In the edit control, specify the path to the location of the *`MathLibrary.lib`* file. By default, it's in a folder called *Debug* directly under the DLL solution folder. If you create a release build, the file is placed in a folder called *Release*. You can use the `$(IntDir)` macro so that the linker can find your DLL, no matter which kind of build you create. If you followed the directions to put your client project in a separate solution from the DLL project, the relative path should look like this: `..\..\MathLibrary\$(IntDir)` If your DLL and client projects are in other locations, adjust the relative path to match. - ![Screenshot of the Additional Library Directories dialog.](media/mathclient-additional-library-directories.png "Add the library directory") + :::image type="content" source="media/mathclient-additional-library-directories.png" alt-text="Screenshot of the Additional Library Directories dialog."::: 1. Once you've entered the path to the library file in the **Additional Library Directories** dialog box, choose the **OK** button to go back to the **Property Pages** dialog box. Choose **OK** to save the property changes. Your client app can now compile and link successfully, but it still doesn't have everything it needs to run. When the operating system loads your app, it looks for the MathLibrary DLL. If it can't find the DLL in certain system directories, the environment path, or the local app directory, the load fails. Depending on the operating system, you'll see an error message like this: -![Screenshot of the error dialog, MathLibrary DLL not found.](media/mathclient-system-error-mathlibrary-dll-not-found.png "MathLibrary DLL not found error") +:::image type="content" source="media/mathclient-system-error-mathlibrary-dll-not-found.png" alt-text="Screenshot of the error dialog, MathLibrary DLL not found."::: -One way to avoid this issue is to copy the DLL to the directory that contains your client executable as part of the build process. You can add a **Post-Build Event** to your project, to add a command that copies the DLL to your build output directory. The command specified here copies the DLL only if it's missing or has changed. It uses macros to copy to and from the Debug or Release locations, based on your build configuration. +One way to avoid this issue is to copy the DLL to the directory that contains your client executable as part of the build process. You can add a *post-build event* to your project, to add a command that copies the DLL to your build output directory. The command specified here copies the DLL only if it's missing or has changed. It uses macros to copy to and from the Debug or Release locations, based on your build configuration. ### To copy the DLL in a post-build event 1. Right-click on the **MathClient** node in **Solution Explorer** and choose **Properties** to open the **Property Pages** dialog. -1. In the **Configuration** drop-down box, select **All Configurations** if it isn't already selected. +1. In the **Configuration** dropdown box, select **All Configurations** if it isn't already selected. 1. In the left pane, select **Configuration Properties** > **Build Events** > **Post-Build Event**. @@ -553,7 +548,7 @@ One way to avoid this issue is to copy the DLL to the directory that contains yo If your DLL and client projects are in other directories, change the relative path to the DLL to match. - ![Screenshot of the Property Pages dialog showing the post build event command line property.](media/mathclient-post-build-command-line.png "Add the post-build command") + :::image type="content" source="media/mathclient-post-build-command-line.png" alt-text="Screenshot of the Property Pages dialog showing the post build event command line property."::: 1. Choose the **OK** button to save your changes to the project properties. @@ -569,7 +564,7 @@ Now your client app has everything it needs to build and run. Build the applicat Congratulations, you've created an application that calls functions in your DLL. Now run your application to see what it does. On the menu bar, choose **Debug** > **Start Without Debugging**. Visual Studio opens a command window for the program to run in. The last part of the output should look like: -![Screenshot of the command window output when you start the client app without debugging.](media/mathclient-run-without-debugging.png "Start the client app without debugging") +:::image type="content" source="media/mathclient-run-without-debugging.png" alt-text="Screenshot of the command window output when you start the client app without debugging."::: Press any key to dismiss the command window. @@ -579,4 +574,4 @@ When you deploy your app, you must also deploy the DLLs it uses. The simplest wa ## See also -[Calling DLL Functions from Visual Basic Applications](calling-dll-functions-from-visual-basic-applications.md) +- [Calling DLL Functions from Visual Basic Applications](calling-dll-functions-from-visual-basic-applications.md) diff --git a/docs/build/walkthrough-creating-and-using-a-static-library-cpp.md b/docs/build/walkthrough-creating-and-using-a-static-library-cpp.md index d8f66d6f61..6ca1569909 100644 --- a/docs/build/walkthrough-creating-and-using-a-static-library-cpp.md +++ b/docs/build/walkthrough-creating-and-using-a-static-library-cpp.md @@ -290,5 +290,4 @@ The instructions for how to create the project vary depending on your version of ## See also -[Walkthrough: Creating and Using a Dynamic Link Library (C++)](../build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md)
-[Desktop Applications (Visual C++)](../windows/desktop-applications-visual-cpp.md)
+[Walkthrough: Creating and Using a Dynamic Link Library (C++)](../build/walkthrough-creating-and-using-a-dynamic-link-library-cpp.md) \ No newline at end of file diff --git a/docs/build/walkthrough-header-units.md b/docs/build/walkthrough-header-units.md index a5b66528d6..2a21f566b6 100644 --- a/docs/build/walkthrough-header-units.md +++ b/docs/build/walkthrough-header-units.md @@ -1,52 +1,60 @@ --- -description: "Learn more about C++ header units by converting a header file to a header unit by using Visual Studio 2019." +description: "Learn more about C++ header units. Convert a header file to a header unit using Visual Studio 2022." title: "Walkthrough: Build and import header units in Visual C++ projects" -ms.date: 01/10/2022 +ms.date: 09/29/2022 ms.custom: "conceptual" author: "tylermsft" ms.author: "twhitney" helpviewer_keywords: ["import", "header unit", "ifc"] +monikerRange: '>=msvc-160' --- # Walkthrough: Build and import header units in Microsoft Visual C++ -This article is about building and importing header units by using Visual Studio 2019. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md) to learn specifically how to import Standard Template Library headers as header units. +This article is about building and importing header units with Visual Studio 2022. To learn how to import C++ standard library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md). -Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). They're easier to set up and use than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio), but they provide similar performance benefits. Unlike a PCH, when a header unit changes, only it and what depends on it are rebuilt. +Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). Header units are easier to set up and use, are significantly smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio). +To contrast header units with other ways to include functionality in your programs, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). ## Prerequisites To use header units, you need Visual Studio 2019 16.10 or later. -## What is a header unit? +## What is a header unit -A header unit is a binary representation of a header file. A header unit ends with an *`.ifc`* extension. This format is also used for named modules. +A header unit is a binary representation of a header file. A header unit ends with an *`.ifc`* extension. The same format is used for named modules. -An important difference between a header unit and a header file is that header units aren't affected by macro definitions. You can't `#define` a symbol that causes the header unit to behave differently when you import it. You can do that with a header file. +An important difference between a header unit and a header file is that a header unit isn't affected by macro definitions outside of the header unit. That is, you can't define a preprocessor symbol that causes the header unit to behave differently. By the time you import the header unit, the header unit is already compiled. That's different from how an `#include` file is treated. An included file can be affected by a macro definition outside of the header file because the header file goes through the preprocessor when you compile the source file that includes it. -A similarity is that everything visible from a header file is also visible from a header unit. +Header units can be imported in any order, which isn't true of header files. Header file order matters because macro definitions defined in one header file might affect a subsequent header file. Macro definitions in one header unit can't affect another header unit. -Before you can import a header unit, you need to compile a header file into a header unit. An advantage of header units over PCH is that they can be used in distributed builds. For example, as long as you compile the *`.ifc`* and the program that imports it with the same compiler, and target the same platform and architecture, a header unit produced on one computer can be used on another. +Everything visible from a header file is also visible from a header unit, including macros defined within the header unit. -Another advantage of header units over PCH is that there's more flexibility for differences between the compiler flags used to compile the header unit and the program that imports it. With a PCH, more compiler flags must be the same. With header units, only the following flags need to be the same: +A header file must be translated into a header unit before it can be imported. An advantage of header units over precompiled header files (PCH) is that they can be used in distributed builds. As long as you compile the *`.ifc`* and the program that imports it with the same compiler, and target the same platform and architecture, a header unit produced on one computer can be consumed on another. Unlike a PCH, when a header unit changes, only it and what depends on it are rebuilt. Header units can be up to an order of magnitude smaller in size than a `.pch`. -- Exception handling options like **`/EHsc`**. -- **`/MD[d]`** or **`MT[d]`**. -- **`/D`**. You can define other macros when you build the program that imports the header unit. But the ones used to build the header unit should also be present and defined the same way when you build the program that imports the header unit. +Header units impose fewer constraints on the required similarities of compiler switch combinations used to create the header unit and to compile the code that consumes it than a PCH does. However, some switch combinations and macro definitions might create violations of the one definition rule (ODR) between various translation units. + +Finally, header units are more flexible than a PCH. With a PCH, you can't choose to bring in only one of the headers in the PCH--the compiler processes all of them. With header units, even when you compile them together into a static library, you only bring the contents of the header unit you import into your application. + +Header units are a step in between header files and C++20 modules. They provide some of the benefits of modules. They're more robust because outside macro definitions don't affect them--so you can import them in any order. And the compiler can process them faster than header files. But header units don't have all of the advantages of modules because header units expose the macros defined within them (modules don't). Unlike modules, there's no way to hide private implementation in a header unit. To indicate private implementation with header files, different techniques are employed like adding leading underscores to names, or putting things in an implementation namespace. A module doesn't expose private implementation in any form, so you don't need to do that. + +Consider replacing your precompiled headers with header units. You get the same speed advantage, but with other code hygiene and flexibility benefits as well. ## Ways to compile a header unit There are several ways to compile a file into a header unit: -- **Automatically scan for header units**. This approach is best suited to smaller projects that include many different header files. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) for a demonstration of this approach. This approach is better suited to smaller projects because it can't guarantee optimal build throughput. That's because it scans all the files to find what should be built into header units. +- **Build a shared header unit project**. We recommend this approach because it provides more control over the organization and reuse of the imported header units. Create a static library project that contains the header units that you want, and then reference it to import the header units. For a walkthrough of this approach, see [Build a header unit static library project for header units](walkthrough-import-stl-header-units.md#approach2). -- **Build a shared header unit project**. This approach is best suited for larger projects and for when you want more control over the organization of the imported header units. You create a static library project (or projects) that contain the header units that you want. Then reference that library project (or projects) to import the header units. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach2) for a demonstration of this approach. +- **Choose individual files to translate into header units**. This approach gives you file-by-file control over what is treated as a header unit. It's also useful when you must compile a file as a header unit that, because it doesn't have the default extension (`.ixx`, `.cppm`, `.h`, `.hpp`), wouldn't normally be compiled into a header unit. This approach is demonstrated in this walkthrough. To get started, see [Approach 1: Translate a specific file into a header unit](#approach1). -- **Choose individual header units to build**. This approach gives you file-by-file control over which header files are treated as header units. It's also a good way to try out header units in your project. This approach is demonstrated in this walkthrough. +- **Automatically scan for and build header units**. This approach is convenient, but is best suited to smaller projects because it doesn't guarantee optimal build throughput. For details about this approach, see [Approach 2: Automatically scan for header units](#approach2). -## Convert a project to use header units +- As mentioned in the introduction, you can build and import STL header files as header units, and automatically treat `#include` for STL library headers as `import` without rewriting your code. To see how, visit [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). -Compile a header file as a header unit using the following steps in Visual Studio: +## Approach 1: Translate a specific file into a header unit + +This section shows how to choose a specific file to translate into a header unit. Compile a header file as a header unit using the following steps in Visual Studio: 1. Create a new C++ console app project. 1. Replace the source file content as follows: @@ -76,38 +84,80 @@ Compile a header file as a header unit using the following steps in Visual Studi #endif ``` -To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later: +### Set project properties + +To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later with the following steps: -1. On the Visual Studio main menu, select **Project** > **Properties**. +1. In **Solution Explorer**, right-click the project name and choose **Properties**. 1. In the left pane of the project property pages window, select **Configuration Properties** > **General**. -1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**. +1. In the **C++ Language Standard** dropdown, select **ISO C++20 Standard (/std:c++20)** or later. Choose **Ok** to close the dialog. -### Compile a header file as a header unit +Compile the header file as a header unit: -In **Solution Explorer**, select the file you want to compile as a header unit (in this case, `Pythagorean.h`). Right-click the file and select **Properties**. Since this is a header file, set the **Item Type** property to **C/C++ compiler**. By default, header files have an **Item Type** of **C/C++ header**. Setting this property also sets **C/C++** > **Advanced** > **Compile As** to **Compile as C++ Header Unit (/exportHeader)**. -:::image type="content" source="media/change-item-type.png" alt-text="Screenshot that shows changing the item type to C/C++ compiler."::: +1. In **Solution Explorer**, select the file you want to compile as a header unit (in this case, `Pythagorean.h`). Right-click the file and choose **Properties**. +1. Set the **Configuration properties** > **General** > **Item Type** dropdown to **C/C++ compiler** and choose **Ok**. -**Compile a source file as a header unit**: + :::image type="content" source="media/change-item-type.png" alt-text="Screenshot that shows changing the item type to C/C++ compiler."::: -If you want to compile a file that doesn't have an *`.h`* or *`.hpp`* extension as a header unit, set the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**. -:::image type="content" source="media/change-compile-as.png" alt-text="Screenshot that shows changing Compile As to Compile as C++ Header Unit."::: +When you build this project later in this walkthrough, `Pythagorean.h` will be translated into a header unit. It's translated into a header unit because the item type for this header file is set to **C/C++ compiler**, and because the default action for `.h` and `.hpp` files set this way is to translate the file into a header unit. -### Change your code to import a header unit +> [!NOTE] +> This isn't required for this walkthrough, but is provided for your information. To compile a file as a header unit that doesn't have a default header unit file extension, like `.cpp` for example, set **Configuration properties** > **C/C++** > **Advanced** > **Compile As** to **Compile as C++ Header Unit (/exportHeader)**: +> :::image type="content" source="media/change-compile-as.png" alt-text="Screenshot that shows changing Configuration properties > C/C++ > Advanced > Compile As to Compile as C++ Header Unit (/exportHeader)."::: -In the source file for the example project that contains `main()`, change `#include "Pythagorean.h"` to `import "Pythagorean.h";`. Don't forget the trailing semicolon that's required for `import` statements. +### Change your code to import the header unit -When compiling a header unit from a system header, use angle brackets (`import ;`). If it's a project header, use `import "file";`. +1. In the source file for the example project, change `#include "Pythagorean.h"` to `import "Pythagorean.h";` Don't forget the trailing semicolon. It's required for `import` statements. Because it's a header file in a directory local to the project, we used quotes with the `import` statement: `import "file";`. In your own projects, to compile a header unit from a system header, use angle brackets: `import ;` -Build the solution by selecting **Build** > **Build Solution** on the main menu. Run it to see that it produces the expected output: `Pythagorean triple a:2 b:3 c:13` +1. Build the solution by selecting **Build** > **Build Solution** on the main menu. Run it to see that it produces the expected output: `Pythagorean triple a:2 b:3 c:13` In your own projects, repeat this process to compile the header files you want to import as header units. -If you want to convert only a few header files to header units, this approach is a good one. But if you have many header files that you want to compile, and the convenience of having the build system automatically handle it outweighs the potential effect on build performance, you can have the build system scan for and build header units for you. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) to learn how. +If you want to convert only a few header files to header units, this approach is good. But if you have many header files that you want to compile, and the potential loss of build performance is outweighed by the convenience of having the build system handle them automatically, see the following section. + +If you're interested in specifically importing STL library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1). + +## Approach 2: Automatically scan for and build header units + +Because it takes time to scan all of your source files for header units, and time to build them, the following approach is best suited for smaller projects. It doesn't guarantee optimal build throughput. + +This approach combines two Visual Studio project settings: + +- **Scan Sources for Module Dependencies** causes the build system to call the compiler to ensure that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header files included in your source that are also specified in a [`header-units.json`](./reference/header-unit-json-reference.md) file located in the same directory as the header file, are compiled into header units. +- **Translate Includes to Imports** treats a header file as an `import` if the `#include` refers to a header file that can be compiled as a header unit (as specified in a `header-units.json` file), and a compiled header unit is available for the header file. Otherwise, the header file is treated as a normal `#include`. The [`header-units.json`](./reference/header-unit-json-reference.md) file is used to automatically build header units for each `#include`, without symbol duplication. + +You can turn on these settings in the properties for your project. To do so, right-click the project in the **Solution Explorer** and choose **Properties**. Then choose **Configuration Properties** > **C/C++** > **General**. + +:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the project properties screen with Configuration highlighted and All Configurations selected. Under C/C++ > General, Scan Sources for Module Dependencies is highlighted and set to yes, and Translate Includes to Imports is highlighted and set to Yes (/translateInclude)"::: + +**Scan Sources for Module Dependencies** can be set for all of the files in the project in **Project Properties** as shown here, or for individual files in **File Properties**. Modules and header units are always scanned. Set this option when you have a `.cpp` file that imports header units that you want built automatically and might not be built yet. + +These settings work together to automatically build and import header units under these conditions: + +- **Scan Sources for Module Dependencies** scans your sources for the files and their dependencies that can be treated as header units. Files that have the extension `.ixx`, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned regardless of this setting. The compiler also looks for `import` statements to identify header unit dependencies. If `/translateInclude` is specified, the compiler also scans for `#include` directives that are also specified in a `header-units.json` file to treat as header units. A dependency graph is built of all the modules and header units in your project. +- **Translate Includes to Imports** When the compiler encounters an `#include` statement, and a matching header unit file (`.ifc`) exists for the specified header file, the compiler imports the header unit instead of treating the header file as an `#include`. When combined with **Scan for dependencies**, the compiler finds all of the header files that can be compiled into header units. An allowlist is consulted by the compiler to decide which header files can compile into header units. This list is stored in a [`header-units.json`](./reference/header-unit-json-reference.md) file that must be in the same directory as the included file. You can see an example of a `header-units.json` file under the installation directory for Visual Studio. For example, `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json` is used by the compiler to determine whether a Standard Template Library header can be compiled into a header unit. This functionality exists to serve as a bridge with legacy code to get some benefits of header units. + +The `header-units.json` file serves two purposes. In addition to specifying which header files can be compiled into header units, it minimizes duplicated symbols to increase build throughput. For more information about symbol duplication, see [C++ header-units.json reference](reference/header-unit-json-reference.md#preventing-duplicated-symbols). + +These switches and the `header-unit.json` provide some of the benefits of header units. The convenience comes at the cost of build throughput. This approach might not be the best for larger projects because it doesn't guarantee optimal build times. Also, the same header files might be reprocessed repeatedly, which increases build time. However, the convenience might be worth it depending on the project. + +These features are designed for legacy code. For new code, move to modules instead of header units or `#include` files. For a tutorial on using modules, see [Name modules tutorial (C++)](../cpp/tutorial-named-modules-cpp.md). + +For an example of how this technique is used to import STL header files as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach2). + +## Preprocessor implications + +The standard C99/C++11 conforming preprocessor is required to create and use header units. The compiler enables the new C99/C++11 conforming preprocessor when compiling header units by implicitly adding [`/Zc:preprocessor`](./reference/zc-preprocessor.md) to the command line whenever any form of `/exportHeader` is used. Attempting to turn it off will result in a compilation error. + +Enabling the new preprocessor affects the processing of variadic macros. For more information, see the [Variadic macros](../preprocessor/variadic-macros.md#remarks) remarks section. ## See also -[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)\ -[Overview of modules in C++](../cpp/modules-cpp.md) \ -[`/translateInclude`](./reference/translateinclude.md) \ -[`/exportHeader`](./reference/module-exportheader.md) \ -[`/headerUnit`](./reference/headerunit.md) +[`/translateInclude`](./reference/translateinclude.md)\ +[`/exportHeader`](./reference/module-exportheader.md)\ +[`/headerUnit`](./reference/headerunit.md)\ +[`header-units.json`](./reference/header-unit-json-reference.md)\ +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) diff --git a/docs/build/walkthrough-import-stl-header-units.md b/docs/build/walkthrough-import-stl-header-units.md index d840569779..3c2fd2d7e5 100644 --- a/docs/build/walkthrough-import-stl-header-units.md +++ b/docs/build/walkthrough-import-stl-header-units.md @@ -1,118 +1,49 @@ --- -description: "Learn to use header units to import C++ Standard Template Library (STL) libraries in Visual Studio." title: "Walkthrough: Import STL libraries as header units" -ms.date: 01/10/2022 +description: "Learn to use header units to import C++ Standard Template Library (STL) libraries in Visual Studio." +ms.date: 10/15/2022 ms.custom: "conceptual" author: "tylermsft" ms.author: "twhitney" helpviewer_keywords: ["import", "header unit", "ifc", "stl"] +monikerRange: '>=msvc-160' --- # Walkthrough: Import STL libraries as header units -This walkthrough shows two ways to import C++ Standard Template Library (STL) libraries as header units in Visual Studio. - -The [first way](#approach1) shows how to have the build system automatically scan for and build header units based on the STL headers you import in your project. - -The [second way](#approach2) shows how to build a static library project that contains header units for the STL headers you want to use, and then reference that project to import the header units. - -Importing an STL header as a header unit is a simpler alternative to [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use than a shared precompiled header file (PCH), but still provide similar performance benefits. Unlike a PCH, when a header unit changes, only it and what depends on it are rebuilt. +This walkthrough shows how to import C++ Standard Template Library (STL) libraries as header units in Visual Studio. For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md). -Before you can import an STL header, it must be compiled into a header unit. A header unit is a binary representation of a header file. A header unit ends with an *`.ifc`* extension. +Importing an STL header as a header unit is simpler than using [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use, are substantially smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio). -Everything visible from a header file is also visible from a header unit. An important difference between a header unit and a header file is that header units aren't affected by macro definitions. You can't `#define` a symbol that causes the header unit to behave differently when you import it as you can with a header file. +For more detailed information about what header units are and the benefits they provide, see [What is a header unit?](walkthrough-header-units.md#what-is-a-header-unit). To contrast header units with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). ## Prerequisites -To use header units, you need Visual Studio 2019 16.10 or later. - -## Two approaches - -Before you can import an STL header, you must compile it into a header unit. There are two approaches: - -**Scan for module dependencies** - -With this approach, the build system scans your sources for `import "header";` and `import
;` statements. Those header files and their dependencies are then compiled into header units. Finally, it imports the compiled header unit files (*`.ifc`*) instead of running the header file through the preprocessor. - -This approach might not be the best for larger projects because it doesn't guarantee optimal build times. That's because the build system needs to scan through the files to find the headers to build into header units. The same header files might be encountered and reprocessed repeatedly, which would increase build time. Also, not all header files can be automatically converted to header units. For example, headers that depend on conditional compilation via `#define` symbols might not work as header units. If a header file fails to be compiled into a header unit, it's treated as a normal `#include` file. - -See [Approach 1: Scan for headers](#approach1) in this article to walk through this approach. - -**Create a static library project** - -The recommended approach, particularly for larger projects or when you want to share a common set of header units across multiple projects, is to create a static library project that contains the header units you want to share. Then reference the library project from the projects that import the header units. It's like using [shared precompiled headers](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio/), but easier. - -See [Approach 2: Build a static library project](#approach2) in this article to walk through this approach. - -## Approach 1: Scan for imports - -We'll start with the easiest way to import STL libraries as header units. This approach might not be appropriate for larger projects because it doesn't guarantee an optimal build time. That's because the sources need to be scanned for `import` statements. - -This option is convenient when there are many header files or when build throughput isn't critical. This option doesn't guarantee that a header unit for a particular header will be built only once. But header units that are part of referenced static library projects are reused. - -You can import your STL libraries as header units without changing your code. To do so, enable the Visual C++ project **Scan Sources for Module Dependencies** option. This setting causes the build system to scan your source code for `import` directives and tries to compile the imported header file into a header unit. There are other ways to indicate that a header file should be treated as a header unit besides scanning your entire project. For more information, see [Walkthrough: Build and import header units in Visual C++ projects](walkthrough-header-units.md). - -Not all headers can be converted to a header unit such as header files that rely on `#define` symbols to cause the header file to compile differently. If a header file relies on this, it won't be converted to a header unit. Instead, it's treated as an ordinary `#include`. +To use header units, use Visual Studio 2022 or later, or Visual Studio 2019 version 16.11 or later. The [`/std:c++20`](./reference/std-specify-language-standard-version.md) option (or later) is required to use header units. -To demonstrate this approach, we'll create a project that imports two STL libraries and then change the project properties so that it treats the libraries as header units. +## Two approaches to import STL headers as header units -### Create a C++ console app project +Before you can import an STL header, it must be compiled into a header unit. A header unit is a binary representation of a header file. It has an *`.ifc`* extension. -This step creates a project that includes two libraries: `` and ``. You'll modify the project settings to scan for header files that can be compiled into header units. +The recommended approach is to create a static library that contains the built header units for the STL headers you want to use. Then reference that library and `import` its header units. This approach can result in faster builds and better reuse. To try out this approach, see [Approach 1: Create a static library of STL library header units](#approach1). -1. In Visual Studio, create a new C++ console app project. -1. Modify the source file as follows: +Another approach is to have Visual Studio scan for the STL headers you `#include` in your project, compile them into header units, and `import` rather than `#include` those headers. This approach is useful if you have a large codebase, because you don't have to change your source code. This approach is less flexible than the static library approach, because it doesn't lend itself to reusing the built header units in other projects. But, you still get the performance advantage of importing individual STL libraries as header units. To try out this approach, see [Approach 2: Scan includes for STL headers to import](#approach2). - ```cpp - import ; - import ; - - int main() - { - std::vector numbers = {0, 1, 2}; - std::cout << numbers[1]; - } - ``` - -### Set project options and run the project - -Follow these steps to set the options that cause the build system to scan for imported headers that can be compiled into header units. +## Approach 1: Create a static library of STL library header units -1. On the main menu, select **Project** > **Properties**. The project property pages dialog opens: -:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting in the project property pages."::: -1. Select **All Configurations** in the **Configuration** list and **All Platforms** in the **Platform** list. Doing so ensures the settings you change apply whether you're building for debug or release, and other configurations. -1. In the left pane of the project property pages dialog, select **C/C++** > **General**. -1. Set **Scan Sources for Module Dependencies** to **Yes**. Because we're setting the project property, all source files in this project will be scanned. - -Change the C++ language standard used by the compiler. The [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later option is required to use header units. - -1. In the left pane of the project property pages dialog, select **Configuration Properties** > **General**. -1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**. -1. Choose **OK** to close the project property pages dialog. From the main menu, build the solution by selecting **Build** > **Build Solution**. - -Run the solution to verify that it produces the expected output: `1` +The recommended way to consume STL libraries as header units is to create one or more static library projects. These projects should consist of the STL library header units that you want to use. Then, reference the library projects to consume those STL header units. It's similar to using [shared precompiled headers](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio/), but easier. -The main consideration when using this approach is the balance between convenience and the cost of scanning all your files to determine which header files to build as header units. +Header units (and modules) built in a static library project are automatically available to referencing projects because the project system automatically adds the appropriate [`/headerUnit`](./reference/headerunit.md) command-line option to the compiler so that referencing projects can import the header units. -You can fine-tune this balance by not scanning every file for import dependencies. Instead, you can indicate which files should be built as header units. That approach is shown in [Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md). +This approach ensures that the header unit for a particular header is built only once. It allows you to import some or all of the header units, which isn't possible with a PCH. You can include header units in any order. -## Approach 2: Build a static library project +In the following example, you create a static library project consisting of the `` and `` header units. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import ;` or `import ;` is found, the built header unit for that library is used instead of translating the header with the preprocessor. It improves build performance, like PCH files do, when the same header is included in multiple files. The header won't have to be processed over and over by the files that include it. Instead, the already processed compiled header unit is imported. -A more flexible way to consume STL headers is to create one or more static library projects that build header units from the STL headers you want to reuse. Then, reference the library project or projects from your projects that will consume those STL headers. Modules and header units built in a static library project are automatically available to referencing projects. The project system automatically adds the appropriate [`/headerUnit`](./reference/headerunit.md) command-line options to the compiler so that the referencing projects will import the header units. +To create a static library that contains the STL libraries `` and ``, follow these steps: -This approach ensures that header units for a particular header will be built only once. It's similar to using a shared precompiled header file, but is much easier. - -In this example, you'll create a project that imports `` and ``. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import ;` or `import ;` is found, the project will import the built header unit for that library instead of running the library header through the preprocessor. - -In projects that include the same library header in multiple files, this change will improve build performance like PCH files do. The header won't have to be processed over and over by the files that include it. Instead, the already processed compiled header unit will be imported. - -### Create the shared header unit project - -Create the project for the shared header unit as follows: - -1. Create an empty C++ project. For this example, call it **SharedPrj**.\ - Select empty C++ project from the project types available in the **Create a new project** window: +1. Create an empty C++ project. Name it *SharedPrj*.\ + Select **Empty Project** for C++ from the project types available in the **Create a new project** window: :::image type="content" source="media/empty-project-option.png" alt-text="Screenshot that shows creating a new empty C++ project."::: -1. Add a new (empty) C++ file to the project. Change the file's content to this: +1. Add a new C++ file to the project. Change the file's content to: ```cpp import ; @@ -123,25 +54,25 @@ Create the project for the shared header unit as follows: Set project properties to share the header units from this project: -1. On the Visual Studio main menu, select **Project** > **Properties**. The project property pages dialog opens: +1. On the Visual Studio main menu, select **Project** > **SharedPrj Properties** to open the project Property Pages dialog: :::image type="content" source="media/set-header-unit-library-settings.png" alt-text="Screenshot that shows settings for Configuration Type and C++ Language Standard."::: -1.Select **All Configurations** in the **Configuration** list and **All Platforms** in the **Platform** list. Doing so ensures the settings you change apply whether you're building for debug or retail, and so on. -1. In the left pane of the project property pages dialog, select **General**. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release. +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **General**. 1. Change the **Configuration Type** option to **Static library (.lib)**. -1. Change **C++ Language Standard** to **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**. -1. In the left pane of the project property pages dialog, select **C/C++** > **General**. - -1. In the **Scan Sources for Module Dependencies** list, select **Yes**: +1. Change **C++ Language Standard** to **ISO C++20 Standard (/std:c++20)** (or later). +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **C/C++** > **General**. +1. In the **Scan Sources for Module Dependencies** dropdown list, select **Yes**. (This option causes the compiler to scan your code for dependencies that can be built into header units): :::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting."::: -1. Choose **OK** to close the project property pages dialog. Build the solution by selecting **Build** > **Build Solution** on the main menu. +1. Choose **OK** to close the project Property Pages dialog. Build the solution by selecting **Build** > **Build Solution** on the main menu. -## Reference the shared header unit project +### Reference the header unit library -Next, create a project that will use the built `` and `` shared header project. +To import `` and `` as header units from the static library, create a project that references the static library as follows: 1. With the current solution still open, on the Visual Studio menu, select **File** > **Add** > **New Project**. -1. Add a C++ console app project. For this example, call it **Walkthrough**. -1. Change the content of its source file as follows: +1. In the **Create a new project** wizard, select the C++ **Console App** template and choose **Next**. +1. Name the new project *Walkthrough*. Change the **Solution** dropdown to **Add to solution**. Choose **Create** to create the project and add it to your solution. +1. Change the content of the *Walkthrough.cpp* source file as follows: ```cpp import ; @@ -154,75 +85,76 @@ Next, create a project that will use the built `` and `` share } ``` -Change the **C++ Language Standard** used by the compiler. To use header units, you need the [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later option. In versions before Visual Studio 2019 version 16.11, use **`/std:c++latest`**. +Header units require the [`/std:c++20`](./reference/std-specify-language-standard-version.md) option (or later). Set the language standard by using the following steps: -1. In **Solution Explorer**, right-click the **Walkthrough** project and select **Properties**. The project property pages dialog opens: +1. In **Solution Explorer**, right-click the **Walkthrough** project and select **Properties** to open the project Property Pages dialog: :::image type="content" source="media/set-cpp-language-latest.png" alt-text="Screenshot that shows setting the language standard to the preview version."::: -1. In the left pane of the **Walkthrough** project property pages dialog, select **Configuration Properties** > **General**. -1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**. -1. Select **OK** to close the project property pages dialog. +1. In the left pane of the **Walkthrough** project Property Pages dialog, select **Configuration Properties** > **General**. +1. In the **C++ Language Standard** dropdown, select **ISO C++20 Standard (/std:c++20)** (or later). +1. Choose **OK** to close the project Property Pages dialog. In the **Walkthrough** project, add a reference to the **SharedPrj** project with the following steps: 1. In the **Walkthrough** project, select the **References** node, and then select **Add Reference**. Select **SharedPrj** in the list of projects: :::image type="content" source="./media/add-reference-to-walkthrough.png" alt-text="Screenshot that shows the Add Reference dialog. It's used to add a reference to the Walkthrough project."::: -Now that you've added this reference, the build system will use the header units built by **SharedPrj** whenever an `import` in the **Walkthrough** project matches one of the built header units in **SharedPrj**. -1. Select **OK** to close the **Add Reference** dialog. +Adding this reference causes the build system to use the header units built by **SharedPrj** whenever an `import` in the **Walkthrough** project matches one of the built header units in **SharedPrj**. +1. Choose **OK** to close the **Add Reference** dialog. 1. Right-click the **Walkthrough** project and select **Set as Startup Project**. - -Build the solution. (**Build** > **Build Solution** on the main menu.) Run it to see that it produces the expected output: `1` +1. Build the solution. (Use **Build** > **Build Solution** on the main menu.) Run it to see that it produces the expected output: `1` The advantage of this approach is that you can reference the static library project from any project to reuse the header units in it. In this example, the static library contains the `` and `` header units. You can make a monolithic static library project that contains all the commonly used STL headers that you want to import from your various projects. Or you can create smaller shared library projects for the different groupings of STL libraries that you want to import as header units. Then reference those shared header unit projects as needed. -The result should be increased build throughput because importing a header unit significantly reduces the work the compiler needs to do. +The result should be increased build throughput because importing a header unit significantly reduces the work the compiler must do. + +When you use this approach with your own projects, build the static library project with compiler options that are compatible with the project that references it. For example, STL projects should be built with the **`/EHsc`** compiler option to turn on exception handling, and so should the projects that reference the static library project. -When you use this approach with your own projects, build the static library project with compiler options that are compatible with the project that will reference it. For example, STL projects should be built with the **`/EHsc`** compiler option to turn on exception handling, and so should the projects that reference the static library project. +### Use `/translateInclude` -## `/translateInclude` +The [`/translateInclude`](./reference/translateinclude.md) compiler option (available in the project Property Pages dialog under **C/C++** > **General** > **Translate Includes to Imports**) makes it easier for you to use a header unit library in older projects that `#include` the STL libraries. It makes it unnecessary to change `#include` directives to `import` in your project, while still giving you the advantage of importing the header units instead of including them. -The [`/translateInclude`](./reference/translateinclude.md) compiler option (available in the project properties dialog under **C/C++** > **General** > **Translate Includes to Imports**) makes it easier for you to use a referenced shared header unit project from your project. It does this by making it unnecessary to modify `#include` directives in your project to take advantage of importing built header units from the referenced shared header unit project. +For example, if you have `#include ` in your project and you reference a static library that contains a header unit for ``, you don't need to manually change `#include ` to `import ;` in your source code. Instead, the compiler automatically treats `#include ` as `import ;`. For more information in detail on this approach, see [Approach 2: Scan includes for STL headers to import](#approach2). Not all STL header files can be compiled to a header unit. The `header-units.json` shipped with Visual Studio lists which STL header files can be compiled into header units. A header that relies on macros to specify its behavior often can't be compiled into a header unit. -For example, if you have `#include ` in your project and you reference a shared header unit project that contains a header unit for ``, you don't need to manually change `#include ` to `import ;` in your source code. Instead, the compiler will automatically treat `#include ` as `import ;`. This behavior applies to any `#include` statement that refers to a built header unit in a referenced shared header unit project. An `#include` statement that doesn't refer to a header unit is treated as a normal `#include#`. +An `#include` statement that doesn't refer to a header unit is treated as a normal `#include`. -## Reuse header units among projects +### Reuse header units among projects Header units built by a static library project are automatically available to all directly and indirectly referencing projects. There are project settings that allow you to select which header units should be automatically available to all referencing projects. The settings are in project settings under **VC++ Directories**. -1. In **Solution Explorer**, right-click the project and select **Properties**. -1. In the left pane of the project properties page, select **VC++ Directories**: +1. In **Solution Explorer**, right-click the project and select **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **VC++ Directories**: :::image type="content" source="media/public-include-module-directories-setting.png" alt-text="Screenshot that shows public project content properties, like Public Include Directories and All Header Files are Public."::: -The following settings control the visibility of header units to the build system: +The following properties control the visibility of header units to the build system: -- **Public Include Directories**. Specifies project directories for header units that should be automatically added to the include path in referencing projects. -- **Public C++ Module Directories**. Specifies which project directories contain header units that should be available to referencing projects. This setting allows you to make some header units public. It's visible to other projects so this is where you put header units that you want to share. If you use this setting, for convenience, specify **Public Include Directories** to automatically add your public headers to the include path in referencing projects. -- **All Modules are Public**. When you use header units built as a part of a DLL project, the symbols have to be exported from the DLL. To do so, set this property to **Yes**. +- **Public Include Directories** specifies project directories for header units that should be automatically added to the include path in referencing projects. +- **Public C++ Module Directories** specifies which project directories contain header units that should be available to referencing projects. This property allows you to make some header units public. It's visible to other projects, so put header units that you want to share here. If you use this setting, for convenience, specify **Public Include Directories** to automatically add your public headers to the Include path in referencing projects. +- **All Modules are Public**: when you use header units built as a part of a DLL project, the symbols have to be exported from the DLL. To export module symbols automatically, set this property to **Yes**. -## Use a prebuilt module file +### Use a prebuilt module file Typically, the easiest way to reuse header units among solutions is to reference a shared header unit project from each solution. -But if you need to use a built header unit that you don't have the project for, you can specify where the built *`.ifc`* file is so you can import it in your solution. To access this setting: +If you must use a built header unit that you don't have the project for, you can specify where the built *`.ifc`* file is so you can import it in your solution. To access this setting: -1. On the main menu, select **Project** > **Properties**. The project properties dialog opens. -1. In the left pane of the project properties page, select **C/C++** > **General**. -1. In the **Additional Module Dependencies** list, add the modules to reference. Here's an example of the format to use for **Additional Module Dependencies**: `ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc` -:::image type="content" source="media/vs2019-additional-module-dependencies.png" alt-text="Screenshot showing project properties under C/C++, General, which Additional Module Dependencies selected."::: +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. In **Additional Module Dependencies**, add the modules to reference, separated by semicolons. Here's an example of the format to use for **Additional Module Dependencies**: `ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc` +:::image type="content" source="media/vs2019-additional-module-dependencies.png" alt-text="Screenshot showing project Property Pages properties under Configuration Properties, C/C++, General, with Additional Module Dependencies selected."::: -## Select among multiple copies of a header unit +### Select among multiple copies of a header unit -If you reference two or more projects that built two or more header units with the same name, or that built two or more header units for the same header file, there will be multiple header units to choose from for the same import. You might have different versions of the header unit that were built with different compiler settings, for example, and need to specify which one to use. +If you reference projects that build multiple header units, either with the same name or for the same header file, you must specify which one to use. You might have different versions of the header unit built with different compiler settings, for example, and must specify the one that matches your project settings. -Use the project properties **C/C++** > **Additional Header Unit Dependencies** setting to resolve collisions by specifying which header unit to use. Otherwise, you can't predict which one will be picked. +Use the project's **Additional Header Unit Dependencies** property to resolve collisions by specifying which header unit to use. Otherwise, it isn't possible to predict which one is picked. -To access this setting: +To set the **Additional Header Unit Dependencies** property: -1. On the main menu, select **Project** > **Properties**. The project properties dialog opens. -1. In the left pane of the project properties page, select **C/C++** > **General**. -1. Use **Additional Header Unit Dependencies** to resolve collisions by specifying which module or header unit should be used for the project. Use this format for **Additional Header Unit Dependencies**: `Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc` -:::image type="content" source="media/additional-header-unit-dependencies-setting.png" alt-text="Screenshot that shows the Additional Header Unit Dependencies setting in the project properties page."::: +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. Specify which modules or header unit files to use in **Additional Header Unit Dependencies** to resolve collisions. Use this format for **Additional Header Unit Dependencies**: `Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc` +:::image type="content" source="media/additional-header-unit-dependencies-setting.png" alt-text="Screenshot that shows the Additional Header Unit Dependencies setting in the project Property Pages dialog."::: > [!IMPORTANT] > Ensure that projects that share header units are built with compatible compilation options. If you use compilation options when you implement the header unit that are different from the ones you used when you created it, the compiler will issue warnings. @@ -230,7 +162,64 @@ To access this setting: > [!NOTE] > To use header units built as a part of a DLL project, set **All Modules are Public** to **Yes**. +## Approach 2: Scan includes for STL headers to import + +Another way to import STL libraries is to have Visual Studio scan for the STL headers you `#include` in your project and compile them into header units. The compiler then imports rather than includes those headers. + +This option is convenient when your project includes many STL header files across many files, or when build throughput isn't critical. This option doesn't guarantee that a header unit for a particular header file is built only once. However, it's useful if you have a large codebase: You don't have to change your source code to take advantage of the benefits of header units for many of the STL libraries you use. + +This approach is less flexible than the static library approach, because it doesn't lend itself towards reusing the built header units in other projects. This approach might not be appropriate for larger projects: It doesn't guarantee an optimal build time, since all of the sources must be scanned for `#include` statements. + +Not all header files can be automatically converted to header units. For example, headers that depend on conditional compilation via macros shouldn't be converted to header units. There's an allowlist in the form of a `header-units.json` file for the STL headers that the compiler uses when `/translateInclude` is specified. It determines which STL headers can be compiled into header units. The `header-units.json` file is under the installation directory for Visual Studio. For example, `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json`. If the STL header file isn't on the list, it's treated as a normal `#include` instead of importing it as a header unit. Another advantage of the `header-units.json` file is that it prevents symbol duplication in the built header units. That is, if compiling a header unit brings in another library header multiple times, the symbols won't be duplicated. + +To try out this approach, create a project that includes two STL libraries. Then, change the project's properties so that it imports the libraries as header units instead of including them, as described in the next section. + +### Create a C++ console app project + +Follow these steps to create a project that includes two STL libraries: `` and ``. + +1. In Visual Studio, create a new C++ console app project. +1. Replace the contents of the source file as follows: + + ```cpp + #include + #include + + int main() + { + std::vector numbers = {0, 1, 2}; + std::cout << numbers[1]; + } + ``` + +### Set project options and run the project + +The following steps set the option that causes the compiler to scan for included headers to translate into header units. They also set the option that causes the compiler to treat `#include` as if you had written `import` for header files that can be treated as header units. + +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release, and other configurations. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. Set **Scan Sources for Module Dependencies** to **Yes**. This setting ensures that all compatible header files compile into header units. +1. Set **Translate Includes to Imports** to **Yes**. This setting compiles the STL header files listed in the `header-unit.json` file as header units, and then imports them instead of using the preprocessor to `#include` them. +:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting in the project Property Pages."::: +1. Choose **OK** to save your changes and close the project Property Pages dialog. + +The [`/std:c++20`](./reference/std-specify-language-standard-version.md) option or later is required to use header units. To change the C++ language standard used by the compiler: + +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release, and other configurations. +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **General**. +1. In the **C++ Language Standard** dropdown list, select **ISO C++20 Standard (/std:c++20)** (or later). +1. Choose **OK** to save your changes and close the project Property Pages dialog. +1. From the main menu, build the solution by selecting **Build** > **Build Solution**. + +Run the solution to verify that it produces the expected output: `1` + +The main consideration for whether to use this approach is the balance between convenience and the cost of scanning all your files to determine which header files to build as header units. + ## See also -[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md) \ +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\ [`/translateInclude`](./reference/translateinclude.md) diff --git a/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md b/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md index cdfa078819..2e21028185 100644 --- a/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md +++ b/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md @@ -14,11 +14,8 @@ This walkthrough demonstrates how to use MSBuild in a command prompt to build a This walkthrough illustrates these tasks: - Creating the C++ source files for your project. - - Creating the XML MSBuild project file. - - Using MSBuild to build your project. - - Using MSBuild to customize your project. ## Prerequisites @@ -26,7 +23,6 @@ This walkthrough illustrates these tasks: You need these prerequisites to complete this walkthrough: - A copy of Visual Studio with the **Desktop development with C++** workload installed. - - A general understanding of the MSBuild system. ::: moniker range="msvc-140" @@ -57,7 +53,6 @@ In this walkthrough, you'll create a project that has a source file and a header ### To create the C++ source files for your project 1. Create a folder for your project. - 1. Create a file named *`main.cpp`* and add this code to the file: ```cpp @@ -83,17 +78,15 @@ In this walkthrough, you'll create a project that has a source file and a header An MSBuild project file is an XML file that contains a project root element (``). In the example project you'll build, the `` element contains seven child elements: - Three item group tags (``) that specify project configuration and platform, source file name, and header file name. - - Three import tags (``) that specify the location of Microsoft Visual C++ settings. - - A property group tag (``) that specifies project settings. ### To create the MSBuild project file -1. Use a text editor to create a project file that is named *`myproject.vcxproj`*, and then add the root `` element shown here. (Use `ToolsVersion="14.0"` if you're using Visual Studio 2015, `ToolsVersion="15.0"` if you're using Visual Studio 2017, or `ToolsVersion="16.0"` if you're using Visual Studio 2019.) +1. Use a text editor to create a project file that is named *`myproject.vcxproj`*, and then add the root `` element shown here. (Use `ToolsVersion="14.0"` if you're using Visual Studio 2015, `ToolsVersion="15.0"` if you're using Visual Studio 2017, `ToolsVersion="16.0"` if you're using Visual Studio 2019, or `ToolsVersion="17.0"` if you're using Visual Studio 2022.) ```xml - + ``` @@ -120,12 +113,12 @@ An MSBuild project file is an XML file that contains a project root element (`

``` -1. Add a property group element (``) that specifies two project properties, `` and ``. (Use `v140` as the `` value if you're using Visual Studio 2015, `v141` if you're using Visual Studio 2017, or `v142` if you're using Visual Studio 2019.) +1. Add a property group element (``) that specifies two project properties, `` and ``. (Use `v140` as the `` value if you're using Visual Studio 2015, `v141` if you're using Visual Studio 2017, `v142` if you're using Visual Studio 2019 or `v143` if you're using Visual Studio 2022.) ```xml Application - v142 + v143 ``` @@ -162,10 +155,10 @@ An MSBuild project file is an XML file that contains a project root element (`

+ Debug @@ -209,13 +202,9 @@ The application should display "Hello, from MSBuild!" in the console window. MSBuild enables you to execute predefined build targets, apply user-defined properties, and use custom tools, events, and build steps. This section illustrates these tasks: - Using MSBuild with build targets. - - Using MSBuild with build properties. - - Using MSBuild with the 64-bit compiler and tools. - - Using MSBuild with different toolsets. - - Adding MSBuild customizations. ### Using MSBuild with Build Targets @@ -277,7 +266,10 @@ To rebuild your project with the Visual C++ 11.0 Windows XP toolset, enter this MSBuild provides various ways to customize your build process. These articles show how to add custom build steps, tools, and events to your MSBuild project: - [How to: Add a Custom Build Step to MSBuild Projects](how-to-add-a-custom-build-step-to-msbuild-projects.md) - - [How to: Add Custom Build Tools to MSBuild Projects](how-to-add-custom-build-tools-to-msbuild-projects.md) - - [How to: Use Build Events in MSBuild Projects](how-to-use-build-events-in-msbuild-projects.md) + +## See also + +- [vcpkg in MSBuild projects](/vcpkg/users/buildsystems/msbuild-integration) +- [Tutorial: Install and use packages with MSBuild in Visual Studio](/vcpkg/get_started/get-started-msbuild) diff --git a/docs/build/working-with-project-properties.md b/docs/build/working-with-project-properties.md index 1e6c5ddd66..7f6b508708 100644 --- a/docs/build/working-with-project-properties.md +++ b/docs/build/working-with-project-properties.md @@ -1,35 +1,39 @@ --- -title: "Set C++ compiler and build properties in Visual Studio" +title: "Set C++ Compiler and Build Properties in Visual Studio" description: "Use the Visual Studio IDE to change C++ compiler and linker options and other build settings." -ms.date: "07/17/2019" +ms.date: 03/19/2025 +ms.topic: concept-article helpviewer_keywords: ["project properties [C++], modifying", "properties [C++]", "Visual C++ projects, properties", "projects [C++], properties"] -ms.assetid: 9b0d6f8b-7d4e-4e61-aa75-7d14944816cd --- # Set compiler and build properties -In the IDE, all information that's needed to build a project is exposed as *properties*. This information includes the application name, extension (such as DLL, LIB, EXE), compiler options, linker options, debugger settings, custom build steps, and many other things. Typically, you use *property pages* to view and modify these properties. To access the property pages, choose **Project** > **_project-name_ Properties** from the main menu, or right-click on the project node in **Solution Explorer** and choose **Properties**. +In the Visual Studio IDE, you can view and edit the properties needed to compile and build a project. This information includes the application name, extension (such as DLL, LIB, EXE), compiler options, linker options, debugger settings, and custom build steps. + +You can view and modify these properties by using *property pages*. To access the property pages, choose **Project** > **_project-name_ Properties** from the main menu, or right-click on the project node in **Solution Explorer** and choose **Properties**. ## Default properties -When you create a project, the system assigns values for various properties. The defaults vary somewhat depending on the kind of project and what options you choose in the app wizard. For example, an ATL project has properties related to MIDL files, but these properties are absent in a basic console application. The default properties are shown in the General pane in the Property Pages: +When you create a project, the system assigns values for various properties. The defaults vary somewhat depending on the kind of project and what options you choose in the app wizard. For example, an Active Template Library (ATL) project has properties related to Microsoft Interface Definition Language (MIDL) files, but these properties are absent in a basic console application. The default properties are shown in the Advanced pane in the **Property Pages** window: -![Screenshot of the Property Pages dialog with the Project Defaults properties highlighted.](media/visual-c---project-defaults.png "Visual C++ project Defaults") +:::image type="content" source="media/visual-c---project-defaults.png" alt-text="Screenshot of the Visual Studio project properties dialog box with the Advanced pane selected. Properties such as Use of MFC, Character Set, and so on are highlighted." lightbox="media/visual-c---project-defaults.png"::: -## Applying properties to build configurations and target platforms +## Apply properties to build configurations and target platforms -Some properties, such as the application name, apply to all build variations and target platforms, whether it's a debug or release build. But most properties are configuration-dependent. To generate the correct code, the compiler has to know both the specific platform the program will run on and which specific compiler options to use. So when you set a property, it's important to pay attention to which configuration and platform the new value should apply to. Should it apply only to Debug Win32 builds, or should it also apply to Debug ARM64 and Debug x64? For example, the **Optimization** property, by default, is set to **Maximize Speed (/O2)** in a Release configuration, but it's disabled in the Debug configuration. +Some properties, such as the application name, apply to all build variations and target platforms, whether it's a debug or release build. But most properties are configuration-dependent. To generate the correct code, the compiler has to know both the specific platform the program runs on and which specific compiler options to use. So when you set a property, it's important to pay attention to which configuration and platform the new value should apply to. Should it apply only to Debug Win32 builds, or should it also apply to Debug ARM64 and Debug x64? For example, the **Optimization** property, by default, is set to **Maximize Speed (/O2)** in a Release configuration, but is disabled in the Debug configuration. -You can always see and change the configuration and platform a property value should apply to. The following illustration shows the property pages with the configuration and platform information controls at the top. When the **Optimization** property is set here, it will apply only to Debug Win32 builds, the currently active configuration, as shown by the red arrows. +You can always see and change the configuration and platform a property value should apply to. The following illustration shows the property pages with the configuration and platform information controls at the top. When the **Optimization** property is set here, it only applies to Debug Win32 builds, the currently active configuration, as shown by the red arrows. -![Screenshot of the Property Pages dialog showing property values for the currently active configuration.](media/visual-c---property-pages-showing-active-configuration.png "Visual C++ Property Pages showing active configuration") +:::image type="complex" source="media/visual-c---property-pages-showing-active-configuration.png" alt-text="Screenshot of the Visual Studio Property Pages dialog."::: +The page is open to C/C++, Optimization. The Optimization setting is set to Disabled (/Od), which is called out. An arrow calls out the relationship between the Configuration setting in the project property page, which is set to Active(Debug), and the setting in the Solution configuration dropdown on the toolbar, which is set to Debug. Another arrow calls out the relationship between the Platform setting in the project property page, which is set to Active(Win32), and the setting in the Solutions platform dropdown on the toolbar, which is set to x86. +:::image-end::: The following illustration shows the same project property page, but the configuration has been changed to Release. Note the different value for the Optimization property. Also note that the active configuration is still Debug. You can set properties for any configuration here; it doesn't have to be the active one. -![Screenshot of the Property Pages dialog showing property values for the release configuration.](media/visual-c---property-pages-showing-release-config.png "Visual C++ Property Pages showing release config") +:::image type="content" source="media/visual-c---property-pages-showing-release-config.png" alt-text="Screenshot of the Visual Studio project Property Pages dialog. The Configuration dropdown is called out and is set to Release. The optimization setting is set to Maximize Speed slash O2."::: ## Target platforms -*Target platform* refers to the kind of device and operating system that the executable will run on. You can build a project for more than one platform. The available target platforms for C++ projects depend on the kind of project. They include but aren't limited to Win32, x64, ARM, ARM64, Android, and iOS. The **x86** target platform that you might see in **Configuration Manager** is identical to **Win32** in native C++ projects. Win32 means 32-bit Windows and **x64** means 64-bit Windows. For more information about these two platforms, see [Running 32-bit applications](/windows/win32/WinProg64/running-32-bit-applications). +*Target platform* refers to the kind of device and operating system that the executable runs on. You can build a project for more than one platform. The available target platforms for C++ projects depend on the kind of project. They include but aren't limited to Win32, x64, ARM, ARM64, Android, and iOS. The **x86** target platform that you might see in **Configuration Manager** is identical to **Win32** in native C++ projects. Win32 means 32-bit Windows and **x64** means 64-bit Windows. For more information about these two platforms, see [Running 32-bit applications](/windows/win32/WinProg64/running-32-bit-applications). The **Any CPU** target platform value that you might see in **Configuration Manager** has no effect on native C++ projects. It's only relevant for C++/CLI and other .NET project types. For more information, see [`/CLRIMAGETYPE` (Specify Type of CLR Image)](reference/clrimagetype-specify-type-of-clr-image.md). @@ -42,37 +46,39 @@ For more information about setting properties for a Debug build, see: ## C++ compiler and linker options -C++ compiler and linker options are located under the **C/C++** and **Linker** nodes in the left pane under **Configuration Properties**. These options translate directly to command-line options that will be passed to the compiler. To read documentation about a specific option, select the option in the center pane and press **F1**. Or, you can browse documentation for all the options at [MSVC compiler options](reference/compiler-options.md) and [MSVC linker options](reference/linker-options.md). +C++ compiler and linker options are located under the **C/C++** and **Linker** nodes in the left pane under **Configuration Properties**. These options translate directly to command-line options that are passed to the compiler. To read documentation about a specific option, select the option in the center pane and press **F1**. Or, you can browse documentation for all the options at [MSVC compiler options](reference/compiler-options.md) and [MSVC linker options](reference/linker-options.md). The **Property Pages** dialog box shows only the property pages that are relevant to the current project. For example, if the project doesn't have an *`.idl`* file, the MIDL property page isn't displayed. For more information about the settings on each property page, see [Property Pages (C++)](reference/property-pages-visual-cpp.md). ## Directory and path values -MSBuild supports the use of compile-time constants for certain string values, such as include directories and paths, called *macros*. A macro can refer to a value that's defined by Visual Studio or the MSBuild system, or to a user-defined value. Macros look like `$(macro-name)` or `%(item-macro-name)`. They're exposed in the property pages, where you can refer to and modify them by using the [Property Editor](#property_editor). Use macros instead of hard-coded values such as directory paths. Macros make it easier to share property settings between machines and between versions of Visual Studio. And, you can better ensure that your project settings participate correctly in [property inheritance](project-property-inheritance.md). +MSBuild supports the use of compile-time constants for certain string values, such as include directories and paths, called *macros*. A macro can refer to a value that's defined by Visual Studio or the MSBuild system, or to a user-defined value. Macros look like `$(macro-name)` or `%(item-macro-name)`. They're exposed in the property pages, where you can refer to and modify them by using the [Property Editor](#property_editor). Use macros instead of hard-coded values such as directory paths. Macros make it easier to share property settings between machines and between versions of Visual Studio. You can also better ensure that your project settings participate correctly in [property inheritance](project-property-inheritance.md). The following illustration shows the property pages for a Visual Studio C++ project. In the left pane, the **VC++ Directories** *rule* is selected, and the right pane lists the properties that are associated with that rule. The property values are often macros, such as `$(VC_SourcePath)`: -![Screenshot of the Property Pages dialog showing the VC project directories.](media/project_property_pages_vc.png "Project_Property_Pages_VC") +:::image type="complex" source="media/project_property_pages_vc.png" alt-text="Screenshot of the Visual Studio Property Pages dialog for rules for various directories."::: +The VC plus plus Directories page is open, which has properties for the VC++ Directories rules. An example rule is Source directories, which is set to $(VC_SourcePath). There are rules for the include directories, library directories, executable directories, and so on. +:::image-end::: You can use the [Property Editor](#property_editor) to view the values of all available macros. ### Predefined macros -- **Global macros**:\ +- **Global macros**\ Global macros apply to all items in a project configuration. A global macro has the syntax `$(name)`. An example of a global macro is `$(VCInstallDir)`, which stores the root directory of your Visual Studio installation. A global macro corresponds to a `PropertyGroup` in MSBuild. - **Item macros**\ - Item macros have the syntax `%(name)`. For a file, an item macro applies only to that file—for example, you can use `%(AdditionalIncludeDirectories)` to specify include directories that apply only to a particular file. This kind of item macro corresponds to an `ItemGroup` metadata in MSBuild. When it's used in the context of a project configuration, an item macro applies to all files of a certain type. For example, the C/C++ **Preprocessor Definitions** configuration property can take a `%(PreprocessorDefinitions)` item macro that applies to all .cpp files in the project. This kind of item macro corresponds to an `ItemDefinitionGroup` metadata in MSBuild. For more information, see [Item Definitions](/visualstudio/msbuild/item-definitions). + Item macros have the syntax `%(name)`. For a file, an item macro applies only to that file. For example, you can use `%(AdditionalIncludeDirectories)` to specify include directories that apply only to a particular file. This kind of item macro corresponds to an `ItemGroup` metadata in MSBuild. When used in the context of a project configuration, an item macro applies to all files of a certain type. For example, the C/C++ **Preprocessor Definitions** configuration property can take a `%(PreprocessorDefinitions)` item macro that applies to all .cpp files in the project. This kind of item macro corresponds to an `ItemDefinitionGroup` metadata in MSBuild. For more information, see [Item definitions](/visualstudio/msbuild/item-definitions). ### User-defined macros -You can create *user-defined macros* to use as variables in project builds. For example, you could create a user-defined macro that provides a value to a custom build step or a custom build tool. A user-defined macro is a name/value pair. In a project file, use the `$(name)` notation to access the value. +You can create *user-defined macros* to use as variables in project builds. For example, you could create a user-defined macro that provides a value to a custom build step or a custom build tool. A user-defined macro is a name-value pair. In a project file, use the `$(name)` notation to access the value. A user-defined macro is stored in a property sheet. If your project doesn't already contain a property sheet, you can create one by following the steps under [Share or reuse Visual Studio project settings](create-reusable-property-configurations.md). #### To create a user-defined macro -1. Open the **Property Manager** window. (On the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**.) Open the shortcut menu for a property sheet (its name ends in *`.user`*) and then choose **Properties**. The **Property Pages** dialog box for that property sheet opens. +1. Open the **Property Manager** window. On the menu bar, select **View** > **Other Windows** > **Property Manager**. Open the shortcut menu for a property sheet (its name ends in *`.user`*) and then choose **Properties**. The **Property Pages** dialog box for that property sheet opens. 1. In the left pane of the dialog box, select **User Macros**. In the right pane, choose the **Add Macro** button to open the **Add User Macro** dialog box. @@ -82,28 +88,29 @@ A user-defined macro is stored in a property sheet. If your project doesn't alre You can use the Property Editor to modify certain string properties and select macros as values. To access the Property Editor, select a property on a property page and then choose the down arrow button on the right. If the drop-down list contains **\**, then you can choose it to display the Property Editor for that property. -![A property drop-down control is used to access the Property Editor.](media/property_editor_dropdown.png "Property Editor dropdown") +:::image type="complex" source="media/property_editor_dropdown.png" alt-text="Screenshot of the Visual Studio project properties page for VC plus plus Directories."::: +The Property Editor for the Include Directories setting is open. It shows the evaluated value for the Include Directories, which is C:\Program Files(x86)\Microsoft Visual Studio 14.0\VC\Include. It shows the two inherited values: $(VC_IncludePath) and $(WindowsSDK_IncludePath). A checkbox for 'Inherit from parent or project defaults' is selected. +:::image-end::: In the Property Editor, you can choose the **Macros** button to view the available macros and their current values. The following illustration shows the Property Editor for the **Additional Include Directories** property after the **Macros** button was chosen. When the **Inherit from parent or project defaults** check box is selected and you add a new value, it's appended to any values that are currently being inherited. If you clear the check box, your new value replaces the inherited values. In most cases, leave the check box selected. -![The Property Editor dialog for the Include Directories property.](media/propertyeditorvc.png "PropertyEditorVC") +:::image type="complex" source="media/propertyeditorvc.png" alt-text="Screenshot of the Property Editor dialog after selecting the Macros button."::: +The property editor for Include Directories is open. The evaluated value is displayed along with the inherited values. A listbox contains various macros and their values, such as $(CharacterSet) which is set to Unicode. +:::image-end::: ## Add an include directory to the set of default directories -When you add an include directory to a project, it's important not to override all the default directories. The correct way to add a directory is to append the new path, for example "`C:\MyNewIncludeDir\`", and then to Append the **`$(IncludePath)`** macro to the property value. +When you add an include directory to a project, it's important not to override all the default directories. The correct way to add a directory is to append the new path, for example `C:\MyNewIncludeDir\`, and then to append the `$(IncludePath)` macro to the property value. ## Quickly browse and search all properties -The **All Options** property page (under the **Configuration Properties | C/C++** node in the **Property Pages** dialog box) provides a quick way to browse and search the properties that are available in the current context. It has a special search box and a simple syntax to help you filter results: +The **All Options** property page (under the **Configuration Properties** > **C/C++** node in the **Property Pages** dialog box) provides a quick way to browse and search the properties that are available in the current context. It has a special search box and a simple syntax to help you filter results: -No prefix:\ -Search in property names only (case-insensitive substring). +- No prefix: Search in property names only (case-insensitive substring). -'`/`' or '`-`':\ -Search only in compiler switches (case-insensitive prefix) +- '`/`' or '`-`': Search only in compiler switches (case-insensitive prefix). -`v`:\ -Search only in values (case-insensitive substring). +- `v`: Search only in values (case-insensitive substring). ## Set environment variables for a build @@ -115,19 +122,14 @@ In the left pane of the project's **Property Pages** dialog box, expand **Config In the right pane, modify the **Environment** or **Merge Environment** project settings and then choose the **OK** button. -## In this section - -[Share or reuse Visual Studio project settings](create-reusable-property-configurations.md)\ -How to create a *`.props`* file with custom build settings that can be shared or reused. - -[Project property inheritance](project-property-inheritance.md)\ -Describes the order of evaluation for the *`.props`*, *`.targets`*, *`.vcxproj`* files, and environment variables in the build process. +## Articles in this section -[Modify properties and targets without changing the project file](modify-project-properties-without-changing-project-file.md)\ -How to create temporary build settings without having to modify a project file. +- [Share or reuse Visual Studio project settings](create-reusable-property-configurations.md) +- [Property inheritance in Visual Studio projects](project-property-inheritance.md) +- [Modify C++ project properties and targets without changing the project file](modify-project-properties-without-changing-project-file.md) ## See also -[Visual Studio Projects - C++](creating-and-managing-visual-cpp-projects.md)\ -[`.vcxproj` and `.props` file structure](reference/vcxproj-file-structure.md)\ -[Property page XML files](reference/property-page-xml-files.md) +- [Visual Studio projects - C++](creating-and-managing-visual-cpp-projects.md) +- [`.vcxproj` and `.props` file structure](reference/vcxproj-file-structure.md) +- [Property Page XML rule files](reference/property-page-xml-files.md) diff --git a/docs/build/x64-calling-convention.md b/docs/build/x64-calling-convention.md index f410bbead9..abb153a846 100644 --- a/docs/build/x64-calling-convention.md +++ b/docs/build/x64-calling-convention.md @@ -1,38 +1,40 @@ --- -title: "x64 calling convention" -description: "Details of the default x64 calling convention." -ms.date: "07/06/2020" -ms.assetid: 41ca3554-b2e3-4868-9a84-f1b46e6e21d9 +title: "x64 Calling Convention" +description: "Learn about the default x64 calling convention that one function uses to make calls into another function." +ms.date: 03/19/2025 +ms.topic: concept-article --- # x64 calling convention -This section describes the standard processes and conventions that one function (the caller) uses to make calls into another function (the callee) in x64 code. +This article describes the standard processes and conventions that one function (the caller) uses to make calls into another function (the callee) in x64 code. + +For more information about the `__vectorcall` calling convention, see [__vectorcall](../cpp/vectorcall.md). ## Calling convention defaults -The x64 Application Binary Interface (ABI) uses a four-register fast-call calling convention by default. Space is allocated on the call stack as a shadow store for callees to save those registers. +The x64 Application Binary Interface (ABI) uses a four-register, fast-call calling convention by default. Space is allocated on the call stack as a shadow store for callees to save those registers. There's a strict one-to-one correspondence between a function call's arguments and the registers used for those arguments. Any argument that doesn't fit in 8 bytes, or isn't 1, 2, 4, or 8 bytes, must be passed by reference. A single argument is never spread across multiple registers. -The x87 register stack is unused. It may be used by the callee, but consider it volatile across function calls. All floating point operations are done using the 16 XMM registers. +The x87 register stack is unused. It might be used by the callee, but consider it volatile across function calls. All floating point operations are done using the 16 XMM registers. -Integer arguments are passed in registers RCX, RDX, R8, and R9. Floating point arguments are passed in XMM0L, XMM1L, XMM2L, and XMM3L. 16-byte arguments are passed by reference. Parameter passing is described in detail in [Parameter passing](#parameter-passing). These registers, and RAX, R10, R11, XMM4, and XMM5, are considered volatile. Register usage is documented in detail in [Register usage](../build/x64-software-conventions.md#register-usage) and [Caller/callee saved registers](#callercallee-saved-registers). +Integer arguments are passed in registers RCX, RDX, R8, and R9. Floating point arguments are passed in XMM0L, XMM1L, XMM2L, and XMM3L. 16-byte arguments are passed by reference. Parameter passing is described in detail in [Parameter passing](#parameter-passing). These registers, and RAX, R10, R11, XMM4, and XMM5, are considered *volatile*, or potentially changed by a callee on return. Register usage is documented in detail in [x64 register usage](x64-software-conventions.md#x64-register-usage) and [Caller/callee saved registers](#callercallee-saved-registers). For prototyped functions, all arguments are converted to the expected callee types before passing. The caller is responsible for allocating space for the callee's parameters. The caller must always allocate sufficient space to store four register parameters, even if the callee doesn't take that many parameters. This convention simplifies support for unprototyped C-language functions and vararg C/C++ functions. For vararg or unprototyped functions, any floating point values must be duplicated in the corresponding general-purpose register. Any parameters beyond the first four must be stored on the stack after the shadow store before the call. Vararg function details can be found in [Varargs](#varargs). Unprototyped function information is detailed in [Unprototyped functions](#unprototyped-functions). ## Alignment -Most structures are aligned to their natural alignment. The primary exceptions are the stack pointer and `malloc` or `alloca` memory, which are 16-byte aligned to aid performance. Alignment above 16 bytes must be done manually. Since 16 bytes is a common alignment size for XMM operations, this value should work for most code. For more information about structure layout and alignment, see [Types and Storage](../build/x64-software-conventions.md#types-and-storage). For information about the stack layout, see [x64 stack usage](../build/stack-usage.md). +Most structures are aligned to their natural alignment. The primary exceptions are the stack pointer and `malloc` or `alloca` memory, which are 16-byte aligned to aid performance. Alignment above 16 bytes must be done manually. Since 16 bytes is a common alignment size for XMM operations, this value should work for most code. For more information about structure layout and alignment, see [x64 type and storage layout](x64-software-conventions.md#x64-type-and-storage-layout). For information about the stack layout, see [x64 stack usage](../build/stack-usage.md). ## Unwindability -Leaf functions are functions that don't change any non-volatile registers. A non-leaf function may change non-volatile RSP, for example, by calling a function. Or, it could change RSP by allocating additional stack space for local variables. To recover non-volatile registers when an exception is handled, non-leaf functions are annotated with static data. The data describes how to properly unwind the function at an arbitrary instruction. This data is stored as *pdata*, or procedure data, which in turn refers to *xdata*, the exception handling data. The xdata contains the unwinding information, and can point to additional pdata or an exception handler function. +Leaf functions are functions that don't change any nonvolatile registers. A nonleaf function might change nonvolatile RSP, for example, by calling a function. Or, it could change RSP by allocating more stack space for local variables. To recover nonvolatile registers when an exception is handled, nonleaf functions are annotated with static data. The data describes how to properly unwind the function at an arbitrary instruction. This data is stored as *pdata*, or procedure data, which in turn refers to *xdata*, the exception handling data. The xdata contains the unwinding information, and can point to additional pdata or an exception handler function. Prologs and epilogs are highly restricted so that they can be properly described in xdata. The stack pointer must remain 16-byte aligned in any region of code that isn't part of an epilog or prolog, except within leaf functions. Leaf functions can be unwound simply by simulating a return, so pdata and xdata aren't required. For details about the proper structure of function prologs and epilogs, see [x64 prolog and epilog](../build/prolog-and-epilog.md). For more information about exception handling, and the exception handling and unwinding of pdata and xdata, see [x64 exception handling](../build/exception-handling-x64.md). ## Parameter passing -By default, the x64 calling convention passes the first four arguments to a function in registers. The registers used for these arguments depend on the position and type of the argument. Remaining arguments get pushed on the stack in right-to-left order. +By default, the x64 calling convention passes the first four arguments to a function in registers. The registers used for these arguments depend on the position and type of the argument. Remaining arguments get pushed on the stack in right-to-left order. All arguments passed on the stack are 8-byte aligned. Integer valued arguments in the leftmost four positions are passed in left-to-right order in RCX, RDX, R8, and R9, respectively. The fifth and higher arguments are passed on the stack as previously described. All integer arguments in registers are right-justified, so the callee can ignore the upper bits of the register and access only the portion of the register necessary. @@ -100,15 +102,15 @@ func2() { // RCX = 2, RDX = XMM1 = 1.0, and R8 = 7 ## Return values -A scalar return value that can fit into 64 bits, including the **`__m64`** type, is returned through RAX. Non-scalar types including floats, doubles, and vector types such as [`__m128`](../cpp/m128.md), [`__m128i`](../cpp/m128i.md), [`__m128d`](../cpp/m128d.md) are returned in XMM0. The state of unused bits in the value returned in RAX or XMM0 is undefined. +A scalar return value that can fit into 64 bits, including the `__m64` type, is returned through RAX. Nonscalar types including floats, doubles, and vector types such as [`__m128`](../cpp/m128.md), [`__m128i`](../cpp/m128i.md), [`__m128d`](../cpp/m128d.md) are returned in XMM0. The state of unused bits in the value returned in RAX or XMM0 is undefined. -User-defined types can be returned by value from global functions and static member functions. To return a user-defined type by value in RAX, it must have a length of 1, 2, 4, 8, 16, 32, or 64 bits. It must also have no user-defined constructor, destructor, or copy assignment operator. It can have no private or protected non-static data members, and no non-static data members of reference type. It can't have base classes or virtual functions. And, it can only have data members that also meet these requirements. (This definition is essentially the same as a C++03 POD type. Because the definition has changed in the C++11 standard, we don't recommend using `std::is_pod` for this test.) Otherwise, the caller must allocate memory for the return value and pass a pointer to it as the first argument. The remaining arguments are then shifted one argument to the right. The same pointer must be returned by the callee in RAX. +User-defined types can be returned by value from global functions and static member functions. To return a user-defined type by value in RAX, it must have a length of 1, 2, 4, 8, 16, 32, or 64 bits. It must also have no user-defined constructor, destructor, or copy assignment operator. It can have no private or protected nonstatic data members, and no nonstatic data members of reference type. It can't have base classes or virtual functions. And, it can only have data members that also meet these requirements. This definition is essentially the same as a C++03 POD type. Because the definition has changed in the C++11 standard, we don't recommend using `std::is_pod` for this test. Otherwise, the caller must allocate memory for the return value and pass a pointer to it as the first argument. The remaining arguments are then shifted one argument to the right. The same pointer must be returned by the callee in RAX. These examples show how parameters and return values are passed for functions with the specified declarations: ### Example of return value 1 - 64-bit result -```Output +```cpp __int64 func1(int a, float b, int c, int d, int e); // Caller passes a in RCX, b in XMM1, c in R8, d in R9, e pushed on stack, // callee returns __int64 result in RAX. @@ -116,7 +118,7 @@ __int64 func1(int a, float b, int c, int d, int e); ### Example of return value 2 - 128-bit result -```Output +```cpp __m128 func2(float a, double b, int c, __m64 d); // Caller passes a in XMM0, b in XMM1, c in R8, d in R9, // callee returns __m128 result in XMM0. @@ -124,7 +126,7 @@ __m128 func2(float a, double b, int c, __m64 d); ### Example of return value 3 - user type result by pointer -```Output +```cpp struct Struct1 { int j, k, l; // Struct1 exceeds 64 bits. }; @@ -136,7 +138,7 @@ Struct1 func3(int a, double b, int c, float d); ### Example of return value 4 - user type result by value -```Output +```cpp struct Struct2 { int j, k; // Struct2 fits in 64 bits, and meets requirements for return by value. }; @@ -147,7 +149,7 @@ Struct2 func4(int a, double b, int c, float d); ## Caller/callee saved registers -The x64 ABI considers the registers RAX, RCX, RDX, R8, R9, R10, R11, and XMM0-XMM5 volatile. When present, the upper portions of YMM0-YMM15 and ZMM0-ZMM15 are also volatile. On AVX512VL, the ZMM, YMM, and XMM registers 16-31 are also volatile. Consider volatile registers destroyed on function calls unless otherwise safety-provable by analysis such as whole program optimization. +The x64 ABI considers the registers RAX, RCX, RDX, R8, R9, R10, R11, and XMM0-XMM5 volatile. When present, the upper portions of YMM0-YMM15 and ZMM0-ZMM15 are also volatile. On AVX512VL, the ZMM, YMM, and XMM registers 16-31 are also volatile. When AMX support is present, the TMM tile registers are volatile. Consider volatile registers destroyed on function calls unless otherwise safety-provable by analysis such as whole program optimization. The x64 ABI considers registers RBX, RBP, RDI, RSI, RSP, R12, R13, R14, R15, and XMM6-XMM15 nonvolatile. They must be saved and restored by a function that uses them. @@ -167,7 +169,7 @@ The x87 FPU control word register gets set using the following standard values a | Register\[bits] | Setting | |-|-| -| FPCSR\[0:6] | Exception masks all 1's (all exceptions masked) | +| FPCSR\[0:6] | Exception masks all 1s (all exceptions masked) | | FPCSR\[7] | Reserved - 0 | | FPCSR\[8:9] | Precision Control - 10B (double precision) | | FPCSR\[10:11] | Rounding control - 0 (round to nearest) | @@ -175,7 +177,7 @@ The x87 FPU control word register gets set using the following standard values a A callee that modifies any of the fields within FPCSR must restore them before returning to its caller. Furthermore, a caller that has modified any of these fields must restore them to their standard values before invoking a callee, unless by agreement the callee expects the modified values. -There are two exceptions to the rules about the non-volatility of the control flags: +There are two exceptions to the rules about the nonvolatility of the control flags: - In functions where the documented purpose of the given function is to modify the nonvolatile FPCSR flags. @@ -190,13 +192,13 @@ The nonvolatile portion is set to the following standard values at the start of | Register\[bits] | Setting | |-|-| | MXCSR\[6] | Denormals are zeros - 0 | -| MXCSR\[7:12] | Exception masks all 1's (all exceptions masked) | +| MXCSR\[7:12] | Exception masks all 1s (all exceptions masked) | | MXCSR\[13:14] | Rounding control - 0 (round to nearest) | | MXCSR\[15] | Flush to zero for masked underflow - 0 (off) | A callee that modifies any of the nonvolatile fields within MXCSR must restore them before returning to its caller. Furthermore, a caller that has modified any of these fields must restore them to their standard values before invoking a callee, unless by agreement the callee expects the modified values. -There are two exceptions to the rules about the non-volatility of the control flags: +There are two exceptions to the rules about the nonvolatility of the control flags: - In functions where the documented purpose of the given function is to modify the nonvolatile MXCSR flags. @@ -206,10 +208,10 @@ Make no assumptions about the MXCSR register's volatile portion state across a f ## setjmp/longjmp -When you include setjmpex.h or setjmp.h, all calls to [`setjmp`](../c-runtime-library/reference/setjmp.md) or [`longjmp`](../c-runtime-library/reference/longjmp.md) result in an unwind that invokes destructors and **`__finally`** calls. This behavior differs from x86, where including setjmp.h results in **`__finally`** clauses and destructors not being invoked. +When you include `setjmpex.h` or `setjmp.h`, all calls to [`setjmp`](../c-runtime-library/reference/setjmp.md) or [`longjmp`](../c-runtime-library/reference/longjmp.md) result in an unwind that invokes destructors and `__finally` calls. This behavior differs from x86, where including `setjmp.h` results in `__finally` clauses and destructors not being invoked. -A call to `setjmp` preserves the current stack pointer, non-volatile registers, and MXCSR registers. Calls to `longjmp` return to the most recent `setjmp` call site and resets the stack pointer, non-volatile registers, and MXCSR registers, back to the state as preserved by the most recent `setjmp` call. +A call to `setjmp` preserves the current stack pointer, nonvolatile registers, and MXCSR registers. Calls to `longjmp` return to the most recent `setjmp` call site and resets the stack pointer, nonvolatile registers, and MXCSR registers, back to the state as preserved by the most recent `setjmp` call. ## See also -[x64 software conventions](../build/x64-software-conventions.md) +- [Overview of x64 ABI conventions](../build/x64-software-conventions.md) diff --git a/docs/build/x64-software-conventions.md b/docs/build/x64-software-conventions.md index 48fb2b2292..fe644a1aa5 100644 --- a/docs/build/x64-software-conventions.md +++ b/docs/build/x64-software-conventions.md @@ -1,43 +1,47 @@ --- -description: "Learn more about: x64 software conventions" -title: "x64 software conventions" -ms.date: "12/17/2018" -helpviewer_keywords: ["x64 coding conventions", "Visual C++, x64 calling conventions"] -ms.assetid: 750f3d97-1706-4840-b2fc-41a007329a08 +description: "Learn more about: x64 ABI conventions" +title: "x64 ABI conventions" +ms.date: 03/28/2025 +helpviewer_keywords: ["x64 coding conventions", "x64 abi", "Visual C++, x64 calling conventions"] --- -# x64 software conventions +# Overview of x64 ABI conventions -This section describes the C++ calling convention methodology for x64, the 64-bit extension to the x86 architecture. +This topic describes the basic application binary interface (ABI) for x64, the 64-bit extension to the x86 architecture. It covers topics such as the calling convention, type layout, stack and register usage, and more. -## Overview of x64 calling conventions +## x64 calling conventions -Two important differences between x86 and x64 are the 64-bit addressing capability and a flat set of 16 64-bit registers for general use. Given the expanded register set, x64 uses the [__fastcall](../cpp/fastcall.md) calling convention and a RISC-based exception-handling model. The **`__fastcall`** convention uses registers for the first four arguments and the stack frame to pass additional arguments. For details on the x64 calling convention, including register usage, stack parameters, return values, and stack unwinding, see [x64 calling convention](x64-calling-convention.md). +Two important differences between x86 and x64 are: -## Enable optimization for x64 +- 64-bit addressing capability +- Sixteen 64-bit registers for general use. + +Given the expanded register set, x64 uses the [`__fastcall`](../cpp/fastcall.md) calling convention and a RISC-based exception-handling model. + +The **`__fastcall`** convention uses registers for the first four arguments, and the stack frame to pass more arguments. For details on the x64 calling convention, including register usage, stack parameters, return values, and stack unwinding, see [x64 calling convention](x64-calling-convention.md). + +For more information on the `__vectorcall` calling convention, see [`__vectorcall`](../cpp/vectorcall.md). + +## Enable x64 compiler optimization The following compiler option helps you optimize your application for x64: - [/favor (Optimize for Architecture Specifics)](../build/reference/favor-optimize-for-architecture-specifics.md) -## Types and storage +## x64 type and storage layout -This section describes the enumeration and storage of data types for the x64 architecture. +This section describes the storage of data types for the x64 architecture. ### Scalar types -Although it's possible to access data with any alignment, it's recommended to align data on its natural boundary, or some multiple, to avoid performance loss. Enums are constant integers and are treated as 32-bit integers. The following table describes the type definition and recommended storage for data as it pertains to alignment using the following alignment values: +Although it's possible to access data with any alignment, align data on its natural boundary, or a multiple of its natural boundary, to avoid performance loss. Enums are constant integers and are treated as 32-bit integers. The following table describes the type definition and recommended storage for data as it pertains to alignment using the following alignment values: - Byte - 8 bits - - Word - 16 bits - - Doubleword - 32 bits - - Quadword - 64 bits - - Octaword - 128 bits -|Scalar Type|C Data Type|Storage Size (in bytes)|Recommended Alignment| +|Scalar type|C data type|Storage size (in bytes)|Recommended alignment| |-|-|-|-| |**`INT8`**|**`char`**|1|Byte| |**`UINT8`**|**`unsigned char`**|1|Byte| @@ -53,7 +57,7 @@ Although it's possible to access data with any alignment, it's recommended to al |**`__m64`**|**`struct __m64`**|8|Quadword| |**`__m128`**|**`struct __m128`**|16|Octaword| -### Aggregates and unions +### x64 aggregate and union layout Other types, such as arrays, structs, and unions, have stricter alignment requirements that ensure consistent aggregate and union storage and data retrieval. Here are the definitions for array, structure, and union: @@ -63,13 +67,13 @@ Other types, such as arrays, structs, and unions, have stricter alignment requir - Structure - Contains an ordered group of data objects. Unlike the elements of an array, the data objects within a structure can have different data types and sizes. Each data object in a structure is called a *member*. + Contains an ordered group of data objects. Unlike the elements of an array, the members of a structure can have different data types and sizes. - Union An object that holds any one of a set of named members. The members of the named set can be of any type. The storage allocated for a union is equal to the storage required for the largest member of that union, plus any padding required for alignment. -The following table shows the strongly suggested alignment for the scalar members of unions and structures. +The following table shows the strongly recommended alignment for the scalar members of unions and structures. |Scalar Type|C Data Type|Required Alignment| |-|-|-| @@ -95,11 +99,11 @@ The following aggregate alignment rules apply: - Structure size must be an integral multiple of its alignment, which may require padding after the last member. Since structures and unions can be grouped in arrays, each array element of a structure or union must begin and end at the proper alignment previously determined. -- It is possible to align data in such a way as to be greater than the alignment requirements as long as the previous rules are maintained. +- It's possible to align data in such a way as to be greater than the alignment requirements as long as the previous rules are maintained. -- An individual compiler may adjust the packing of a structure for size reasons. For example [/Zp (Struct Member Alignment)](../build/reference/zp-struct-member-alignment.md) allows for adjusting the packing of structures. +- An individual compiler may adjust the packing of a structure for size reasons. For example, [/Zp (Struct Member Alignment)](../build/reference/zp-struct-member-alignment.md) allows for adjusting the packing of structures. -### Examples of Structure Alignment +### x64 structure alignment examples The following four examples each declare an aligned structure or union, and the corresponding figures illustrate the layout of that structure or union in memory. Each column in a figure represents a byte of memory, and the number in the column indicates the displacement of that byte. The name in the second row of each figure corresponds to the name of a variable in the declaration. The shaded columns indicate padding that is required to achieve the specified alignment. @@ -113,7 +117,7 @@ _declspec(align(2)) struct { } ``` -![Diagram showing the example 1 structure layout.](../build/media/vcamd_conv_ex_1_block.png "AMD conversion example 1 structure layout") +:::image type="content" source="../build/media/vcamd_conv_ex_1_block.png" alt-text="Diagram showing the structure layout for example 1. The diagram shows 2 bytes of memory. Member a, a short, occupies bytes 0 through 1."::: #### Example 2 @@ -127,7 +131,9 @@ _declspec(align(8)) struct { } ``` -![Diagram showing the example 2 structure layout.](../build/media/vcamd_conv_ex_2_block.png "AMD conversion example 2 structure layout") +:::image type="complex" source="../build/media/vcamd_conv_ex_2_block.png" alt-text="Diagram showing the structure layout for example 2."::: +The diagram shows 24 bytes of memory. Member a, an int, occupies bytes 0 through 3. The diagram shows padding for bytes 4 through 7. Member b, a double, occupies bytes 8 through 15. Member c, a short, occupies bytes 16 through 17. Bytes 18 through 23 are unused. +:::image-end::: #### Example 3 @@ -142,7 +148,9 @@ _declspec(align(4)) struct { } ``` -![Diagram showing the example 3 structure layout.](../build/media/vcamd_conv_ex_3_block.png "AMD conversion example 3 structure layout") +:::image type="complex" source="../build/media/vcamd_conv_ex_3_block.png" alt-text="Diagram showing the structure layout for example 3."::: +The diagram shows 12 bytes of memory. Member a, a char, occupies byte 0. Byte 1 is padding. Member b, a short, occupies bytes 2 through 4. Member c, a char, occupies byte 4. Bytes 5 through 7 are padding. Member d, an int, occupies bytes 8 through 11. +:::image-end::: #### Example 4 @@ -156,25 +164,27 @@ _declspec(align(8)) union { } ``` -![Diagram showing the example 4 union layout.](../build/media/vcamd_conv_ex_4_block.png "AMD conversion example 4 union layout") +:::image type="complex" source="../build/media/vcamd_conv_ex_4_block.png" alt-text="Diagram showing the union layout for example 4."::: +The diagram shows 8 bytes of memory. Member p, a char, occupies byte 0. Member s, a short, occupies bytes 0 through 1. Member l, a long, occupies bytes 0 through 3. Bytes 4 through 7 are padding. +:::image-end::: ### Bitfields -Structure bit fields are limited to 64 bits and can be of type signed int, unsigned int, int64, or unsigned int64. Bit fields that cross the type boundary will skip bits to align the bitfield to the next type alignment. For example, integer bitfields may not cross a 32-bit boundry. +Structure bit fields are limited to 64 bits and can be of type signed int, unsigned int, int64, or unsigned int64. Bit fields that cross the type boundary will skip bits to align the bitfield to the next type alignment. For example, integer bitfields may not cross a 32-bit boundary. ### Conflicts with the x86 compiler -Data types that are larger than 4 bytes are not automatically aligned on the stack when you use the x86 compiler to compile an application. Because the architecture for the x86 compiler is a 4 byte aligned stack, anything larger than 4 bytes, for example, a 64-bit integer, cannot be automatically aligned to an 8-byte address. +Data types that are larger than 4 bytes aren't automatically aligned on the stack when you use the x86 compiler to compile an application. Because the architecture for the x86 compiler is a 4 byte aligned stack, anything larger than 4 bytes, for example, a 64-bit integer, can't be automatically aligned to an 8-byte address. Working with unaligned data has two implications. - It may take longer to access unaligned locations than it takes to access aligned locations. -- Unaligned locations cannot be used in interlocked operations. +- Unaligned locations can't be used in interlocked operations. If you require more strict alignment, use `__declspec(align(N))` on your variable declarations. This causes the compiler to dynamically align the stack to meet your specifications. However, dynamically adjusting the stack at run time may cause slower execution of your application. -## Register usage +## x64 register usage The x64 architecture provides for 16 general-purpose registers (hereafter referred to as integer registers) as well as 16 XMM/YMM registers available for floating-point use. Volatile registers are scratch registers presumed by the caller to be destroyed across a call. Nonvolatile registers are required to retain their values across a function call and must be saved by the callee if used. @@ -208,7 +218,7 @@ On function exit and on function entry to C Runtime Library calls and Windows sy ## Stack usage -For details on stack allocation, alignment, function types and stack frames on x64, see [x64 stack usage](stack-usage.md). +For details on stack allocation, alignment, function types, and stack frames on x64, see [x64 stack usage](stack-usage.md). ## Prolog and epilog @@ -220,11 +230,11 @@ For information on the conventions and data structures used to implement structu ## Intrinsics and inline assembly -One of the constraints for the x64 compiler is to have no inline assembler support. This means that functions that cannot be written in C or C++ will either have to be written as subroutines or as intrinsic functions supported by the compiler. Certain functions are performance sensitive while others are not. Performance-sensitive functions should be implemented as intrinsic functions. +One of the constraints for the x64 compiler is no inline assembler support. This means that functions that can't be written in C or C++ will either have to be written as subroutines or as intrinsic functions supported by the compiler. Certain functions are performance sensitive while others aren't. Performance-sensitive functions should be implemented as intrinsic functions. -The intrinsics supported by the compiler are described in [Compiler Intrinsics](../intrinsics/compiler-intrinsics.md). +The intrinsics supported by the compiler are described in [Compiler intrinsics](../intrinsics/compiler-intrinsics.md). -## Image format +## x64 image format The x64 executable image format is PE32+. Executable images (both DLLs and EXEs) are restricted to a maximum size of 2 gigabytes, so relative addressing with a 32-bit displacement can be used to address static image data. This data includes the import address table, string constants, static global data, and so on. diff --git a/docs/c-language/argument-description.md b/docs/c-language/argument-description.md index 876403b865..e8f007f13c 100644 --- a/docs/c-language/argument-description.md +++ b/docs/c-language/argument-description.md @@ -1,28 +1,28 @@ --- description: "Learn more about: Argument Description" title: "Argument Description" -ms.date: "11/04/2016" +ms.date: 09/28/2022 helpviewer_keywords: ["envp argument", "main function, syntax", "arguments [C++], for main function", "argv argument", "argc argument"] ms.assetid: 91c2cbe3-9aca-4277-afa1-6137eb8fb704 --- -# Argument Description +# Argument description -The `argc` parameter in the **main** and **wmain** functions is an integer specifying how many arguments are passed to the program from the command line. Since the program name is considered an argument, the value of `argc` is at least one. +The *`argc`* parameter in the `main` and `wmain` functions is an integer specifying how many arguments are passed to the program from the command line. Since the program name is considered an argument, the value of *`argc`* is at least one. ## Remarks -The `argv` parameter is an array of pointers to null-terminated strings representing the program arguments. Each element of the array points to a string representation of an argument passed to **main** (or **wmain**). (For information about arrays, see [Array Declarations](../c-language/array-declarations.md).) The `argv` parameter can be declared either as an array of pointers to type **`char`** (`char *argv[]`) or as a pointer to pointers to type **`char`** (`char **argv`). For **wmain**, the `argv` parameter can be declared either as an array of pointers to type **`wchar_t`** (`wchar_t *argv[]`) or as a pointer to pointers to type **`wchar_t`** (`wchar_t **argv`). +The *`argv`* parameter is an array of pointers to null-terminated strings representing the program arguments. Each element of the array points to a string representation of an argument passed to `main` (or `wmain`). (For information about arrays, see [Array declarations](../c-language/array-declarations.md).) The *`argv`* parameter can be declared either as an array of pointers to type **`char`** (`char *argv[]`) or as a pointer to pointers to type **`char`** (`char **argv`). For `wmain`, the *`argv`* parameter can be declared either as an array of pointers to type **`wchar_t`** (`wchar_t *argv[]`) or as a pointer to pointers to type **`wchar_t`** (`wchar_t **argv`). -By convention, `argv`**[0]** is the command with which the program is invoked. However, it is possible to spawn a process using [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) and if you use both the first and second arguments (`lpApplicationName` and `lpCommandLine`), `argv`**[0]** may not be the executable name; use [GetModuleFileName](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name. +By convention, `argv[0]` is the command with which the program is invoked. However, it's possible to spawn a process using [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) and if you use both the first and second arguments (`lpApplicationName` and `lpCommandLine`), `argv[0]` may not be the executable name; use [`GetModuleFileName`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name. -The last pointer (`argv[argc]`) is **NULL**. (See [getenv](../c-runtime-library/reference/getenv-wgetenv.md) in the *Run-Time Library Reference* for an alternative method for getting environment variable information.) +The last pointer (`argv[argc]`) is `NULL`. (See [`getenv`](../c-runtime-library/reference/getenv-wgetenv.md) in the *Run-Time Library Reference* for an alternative method for getting environment variable information.) **Microsoft Specific** -The `envp` parameter is a pointer to an array of null-terminated strings that represent the values set in the user's environment variables. The `envp` parameter can be declared as an array of pointers to **`char`** (`char *envp[]`) or as a pointer to pointers to **`char`** (`char **envp`). In a **wmain** function, the `envp` parameter can be declared as an array of pointers to **`wchar_t`** (`wchar_t *envp[]`) or as a pointer to pointers to **`wchar_t`** (`wchar_t **envp`). The end of the array is indicated by a **NULL** \*pointer. Note that the environment block passed to **main** or **wmain** is a "frozen" copy of the current environment. If you subsequently change the environment via a call to _**putenv** or `_wputenv`, the current environment (as returned by `getenv`/`_wgetenv` and the `_environ` or `_wenviron` variables) will change, but the block pointed to by `envp` will not change. The `envp` parameter is ANSI compatible in C, but not in C++. +The *`envp`* parameter is a pointer to an array of null-terminated strings that represent the values set in the user's environment variables. The *`envp`* parameter can be declared as an array of pointers to **`char`** (`char *envp[]`) or as a pointer to pointers to **`char`** (`char **envp`). In a `wmain` function, the *`envp`* parameter can be declared as an array of pointers to **`wchar_t`** (`wchar_t *envp[]`) or as a pointer to pointers to **`wchar_t`** (`wchar_t **envp`). The end of the array is indicated by a `NULL*` pointer. The environment block passed to `main` or `wmain` is a "frozen" copy of the current environment. If you later change the environment via a call to `_putenv` or `_wputenv`, the current environment (as returned by `getenv`/`_wgetenv` and the `_environ` or `_wenviron` variables) will change, but the block pointed to by *`envp`* won't change. The *`envp`* parameter is ANSI/ISO C89 compatible in C, but is a Microsoft extension in C++. **END Microsoft Specific** ## See also -[main Function and Program Execution](../c-language/main-function-and-program-execution.md) +[`main` function and program execution](../c-language/main-function-and-program-execution.md) diff --git a/docs/c-language/arguments-to-main.md b/docs/c-language/arguments-to-main.md index 1c09eb08f8..844ed2be7c 100644 --- a/docs/c-language/arguments-to-main.md +++ b/docs/c-language/arguments-to-main.md @@ -1,32 +1,32 @@ --- description: "Learn more about: Arguments to main" title: "Arguments to main" -ms.date: "11/04/2016" +ms.date: 09/28/2022 ms.assetid: 39824fef-05ad-461d-ae82-49447dda8060 --- # Arguments to main **ANSI 2.1.2.2.1** The semantics of the arguments to main -In Microsoft C, the function called at program startup is called **main**. There is no prototype declared for **main**, and it can be defined with zero, two, or three parameters: +In Microsoft C, the function called at program startup is called **`main`**. There's no prototype declared for **`main`**, and it can be defined with zero, two, or three parameters: -``` +```C int main( void ) int main( int argc, char *argv[] ) int main( int argc, char *argv[], char *envp[] ) ``` -The third line above, where **main** accepts three parameters, is a Microsoft extension to the ANSI C standard. The third parameter, **envp**, is an array of pointers to environment variables. The **envp** array is terminated by a null pointer. See [The main Function and Program Execution](../c-language/main-function-and-program-execution.md) for more information about **main** and **envp**. +The third line above, where **`main`** accepts three parameters, is a Microsoft extension to the ANSI C standard. The third parameter, *`envp`*, is an array of pointers to environment variables. The *`envp`* array is terminated by a null pointer. For more information about **`main`** and *`envp`*, see [The `main` function and program execution](../c-language/main-function-and-program-execution.md). -The variable **argc** never holds a negative value. +The variable *`argc`* never holds a negative value. -The array of strings ends with **argv[argc]**, which contains a null pointer. +The array of strings ends with `argv[argc]`, which contains a null pointer. -All elements of the **argv** array are pointers to strings. +All elements of the *`argv`* array are pointers to strings. -A program invoked with no command-line arguments will receive a value of one for **argc**, as the name of the executable file is placed in **argv[0]**. (In MS-DOS versions prior to 3.0, the executable-file name is not available. The letter "C" is placed in **argv[0]**.) Strings pointed to by **argv[1]** through **argv[argc - 1]** represent program parameters. +A program invoked with no command-line arguments will receive a value of 1 for *`argc`*, as the name of the executable file is placed in `argv[0]`. (In MS-DOS versions prior to 3.0, the executable-file name isn't available. The letter "C" is placed in `argv[0]`.) Strings pointed to by `argv[1]` through `argv[argc - 1]` represent program parameters. -The parameters **argc** and **argv** are modifiable and retain their last-stored values between program startup and program termination. +The parameters *`argc`* and *`argv`* are modifiable and retain their last-stored values between program startup and program termination. ## See also diff --git a/docs/c-language/array-declarations.md b/docs/c-language/array-declarations.md index bf6e678fa3..cf593aeb02 100644 --- a/docs/c-language/array-declarations.md +++ b/docs/c-language/array-declarations.md @@ -11,38 +11,38 @@ An "array declaration" names the array and specifies the type of its elements. I ## Syntax -*declaration*:
-    *declaration-specifiers* *init-declarator-list*opt **;** +*`declaration`*:\ + *`declaration-specifiers`* *`init-declarator-list`*opt **`;`** -*init-declarator-list*:
-    *init-declarator*
-    *init-declarator-list* **,** *init-declarator* +*`init-declarator-list`*:\ + *`init-declarator`*\ + *`init-declarator-list`* **`,`** *`init-declarator`* -*init-declarator*:
-    *declarator*
-    *declarator* **=** *initializer* +*`init-declarator`*:\ + *`declarator`*\ + *`declarator`* **`=`** *`initializer`* -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*: /\* A function declarator \*/
-    *direct-declarator* **[** *constant-expression*opt **]** +*`direct-declarator`*:\ + *`direct-declarator`* **`[`** *`constant-expression`*opt **`]`** -Because *constant-expression* is optional, the syntax has two forms: +Because *`constant-expression`* is optional, the syntax has two forms: -- The first form defines an array variable. The *constant-expression* argument within the brackets specifies the number of elements in the array. The *constant-expression*, if present, must have integral type, and a value larger than zero. Each element has the type given by *type-specifier*, which can be any type except **`void`**. An array element cannot be a function type. +- The first form defines an array variable. The *`constant-expression`* argument within the brackets specifies the number of elements in the array. The *`constant-expression`*, if present, must have integral type, and a value larger than zero. Each element has the type given by *`type-specifier`*, which can be any type except **`void`**. An array element can't be a function type. -- The second form declares a variable that has been defined elsewhere. It omits the *constant-expression* argument in brackets, but not the brackets. You can use this form only if you previously have initialized the array, declared it as a parameter, or declared it as a reference to an array explicitly defined elsewhere in the program. +- The second form declares a variable that has been defined elsewhere. It omits the *`constant-expression`* argument in brackets, but not the brackets. You can use this form only if you've previously initialized the array, declared it as a parameter, or declared it as a reference to an array that's explicitly defined elsewhere in the program. -In both forms, *direct-declarator* names the variable and can modify the variable's type. The brackets (**[ ]**) following *direct-declarator* modify the declarator to an array type. +In both forms, *`direct-declarator`* names the variable and can modify the variable's type. The brackets (**`[ ]`**) following *`direct-declarator`* modify the declarator to an array type. Type qualifiers can appear in the declaration of an object of array type, but the qualifiers apply to the elements rather than the array itself. You can declare an array of arrays (a "multidimensional" array) by following the array declarator with a list of bracketed constant expressions in this form: -> *type-specifier* *declarator* **[** *constant-expression* **]** **[** *constant-expression* **]** ... +> *`type-specifier`* *`declarator`* **`[`** *`constant-expression`* **`]`** **`[`** *`constant-expression`* **`]`** ... -Each *constant-expression* in brackets defines the number of elements in a given dimension: two-dimensional arrays have two bracketed expressions, three-dimensional arrays have three, and so on. You can omit the first constant expression if you have initialized the array, declared it as a parameter, or declared it as a reference to an array explicitly defined elsewhere in the program. +Each *`constant-expression`* in brackets defines the number of elements in a given dimension: two-dimensional arrays have two bracketed expressions, three-dimensional arrays have three, and so on. You can omit the first constant expression if you've initialized the array, declared it as a parameter, or declared it as a reference to an array explicitly defined elsewhere in the program. You can define arrays of pointers to various types of objects by using complex declarators, as described in [Interpreting More Complex Declarators](../c-language/interpreting-more-complex-declarators.md). @@ -52,7 +52,7 @@ Arrays are stored by row. For example, the following array consists of two rows char A[2][3]; ``` -The three columns of the first row are stored first, followed by the three columns of the second row. This means that the last subscript varies most quickly. +The three columns of the first row are stored first, followed by the three columns of the second row. It means that the last subscript varies most quickly. To refer to an individual element of an array, use a subscript expression, as described in [Postfix Operators](../c-language/postfix-operators.md). @@ -72,7 +72,7 @@ struct { } complex[100]; ``` -This is a declaration of an array of structures. This array has 100 elements; each element is a structure containing two members. +This example is a declaration of an array of structures. This array has 100 elements; each element is a structure containing two members. ```C extern char *name[]; @@ -82,7 +82,7 @@ This statement declares the type and name of an array of pointers to **`char`**. **Microsoft Specific** -The type of integer required to hold the maximum size of an array is the size of **size_t**. Defined in the header file STDDEF.H, **size_t** is an **`unsigned int`** with the range 0x00000000 to 0x7CFFFFFF. +The type of integer required to hold the maximum size of an array is the size of **`size_t`**. **END Microsoft Specific** diff --git a/docs/c-language/bitwise-shift-operators.md b/docs/c-language/bitwise-shift-operators.md index 69596997f4..1e2d2e35de 100644 --- a/docs/c-language/bitwise-shift-operators.md +++ b/docs/c-language/bitwise-shift-operators.md @@ -11,14 +11,14 @@ The shift operators shift their first operand left (**`<<`**) or right (**`>>`** ## Syntax -*shift-expression*:
-    *additive-expression*
-    *shift-expression* **`<<`** *additive-expression*
-    *shift-expression* **`>>`** *additive-expression* +*`shift-expression`*:\ + *`additive-expression`*\ + *`shift-expression`* **`<<`** *`additive-expression`*\ + *`shift-expression`* **`>>`** *`additive-expression`* Both operands must be integral values. These operators perform the usual arithmetic conversions; the type of the result is the type of the left operand after conversion. -For leftward shifts, the vacated right bits are set to 0. For rightward shifts, the vacated left bits are filled based on the type of the first operand after conversion. If the type is **`unsigned`**, they are set to 0. Otherwise, they are filled with copies of the sign bit. For left-shift operators without overflow, the statement +For leftward shifts, the vacated right bits are set to 0. For rightward shifts, the vacated left bits are filled based on the type of the first operand after conversion. If the type is **`unsigned`**, they're set to 0. Otherwise, they're filled with copies of the sign bit. For left-shift operators without overflow, the statement ```C expr1 << expr2 @@ -34,7 +34,7 @@ is equivalent to division by 2expr2 if `expr1` is unsigned or has a n The result of a shift operation is undefined if the second operand is negative, or if the right operand is greater than or equal to the width in bits of the promoted left operand. -Since the conversions performed by the shift operators do not provide for overflow or underflow conditions, information may be lost if the result of a shift operation cannot be represented in the type of the first operand after conversion. +Since the conversions performed by the shift operators don't provide for overflow or underflow conditions, information may be lost if the result of a shift operation can't be represented in the type of the first operand after conversion. ```C unsigned int x, y, z; diff --git a/docs/c-language/break-statement-c.md b/docs/c-language/break-statement-c.md index 61b1167120..470da893c5 100644 --- a/docs/c-language/break-statement-c.md +++ b/docs/c-language/break-statement-c.md @@ -12,8 +12,8 @@ The **`break`** statement terminates the execution of the nearest enclosing **`d ## Syntax -*jump-statement*:
-    **break ;** +*`jump-statement`*:\ + **`break ;`** The **`break`** statement is frequently used to terminate the processing of a particular case within a **`switch`** statement. Lack of an enclosing iterative or **`switch`** statement generates an error. diff --git a/docs/c-language/c-abstract-declarators.md b/docs/c-language/c-abstract-declarators.md index 2fcedeb2ec..3766b3dd90 100644 --- a/docs/c-language/c-abstract-declarators.md +++ b/docs/c-language/c-abstract-declarators.md @@ -7,7 +7,7 @@ ms.assetid: 6a556ad7-0555-421a-aa02-294d77cda8b5 --- # C Abstract Declarators -An abstract declarator is a declarator without an identifier, consisting of one or more pointer, array, or function modifiers. The pointer modifier (\*) always precedes the identifier in a declarator; array (**[ ]**) and function ( **( )** ) modifiers follow the identifier. Knowing this, you can determine where the identifier would appear in an abstract declarator and interpret the declarator accordingly. See [Interpreting More Complex Declarators](../c-language/interpreting-more-complex-declarators.md) for additional information and examples of complex declarators. Generally **`typedef`** can be used to simplify declarators. See [Typedef Declarations](../c-language/typedef-declarations.md). +An abstract declarator is a declarator without an identifier, consisting of one or more pointer, array, or function modifiers. The pointer modifier (**`*`**) always precedes the identifier in a declarator; array (**[ ]**) and function ( **( )** ) modifiers follow the identifier. Knowing this, you can determine where the identifier would appear in an abstract declarator and interpret the declarator accordingly. See [Interpreting More Complex Declarators](../c-language/interpreting-more-complex-declarators.md) for additional information and examples of complex declarators. Generally **`typedef`** can be used to simplify declarators. See [Typedef Declarations](../c-language/typedef-declarations.md). Abstract declarators can be complex. Parentheses in a complex abstract declarator specify a particular interpretation, just as they do for the complex declarators in declarations. diff --git a/docs/c-language/c-additive-operators.md b/docs/c-language/c-additive-operators.md index f3f9aaa6f5..13d26b7238 100644 --- a/docs/c-language/c-additive-operators.md +++ b/docs/c-language/c-additive-operators.md @@ -7,22 +7,22 @@ ms.assetid: bb8ac205-b061-41fc-8dd4-dab87c8b900c --- # C Additive Operators -The additive operators perform addition (**+**) and subtraction (**-**). +The additive operators perform addition (**`+`**) and subtraction (**`-`**). ## Syntax -*additive-expression*:
-    *multiplicative-expression*
-    *additive-expression* **+** *multiplicative-expression*
-    *additive-expression* **-** *multiplicative-expression* +*`additive-expression`*:\ + *`multiplicative-expression`*\ + *`additive-expression`* **`+`** *`multiplicative-expression`*\ + *`additive-expression`* **`-`** *`multiplicative-expression`* > [!NOTE] -> Although the syntax for *additive-expression* includes *multiplicative-expression*, this does not imply that expressions using multiplication are required. See the syntax in [C Language Syntax Summary](../c-language/c-language-syntax-summary.md), for *multiplicative-expression*, *cast-expression*, and *unary-expression*. +> Although the syntax for *`additive-expression`* includes *`multiplicative-expression`*, this does not imply that expressions using multiplication are required. See the syntax in [C Language Syntax Summary](../c-language/c-language-syntax-summary.md), for *`multiplicative-expression`*, *cast-expression*, and *unary-expression*. The operands can be integral or floating values. Some additive operations can also be performed on pointer values, as outlined under the discussion of each operator. -The additive operators perform the usual arithmetic conversions on integral and floating operands. The type of the result is the type of the operands after conversion. Since the conversions performed by the additive operators do not provide for overflow or underflow conditions, information may be lost if the result of an additive operation cannot be represented in the type of the operands after conversion. +The additive operators perform the usual arithmetic conversions on integral and floating operands. The type of the result is the type of the operands after conversion. Since the conversions performed by the additive operators don't provide for overflow or underflow conditions, information may be lost if the result of an additive operation isn't representable in the type of the operands after conversion. ## See also -[Additive Operators: + and -](../cpp/additive-operators-plus-and.md) +[Additive Operators: `+` and `-`](../cpp/additive-operators-plus-and.md) diff --git a/docs/c-language/c-assignment-operators.md b/docs/c-language/c-assignment-operators.md index f2f2ad8b85..c42d7402c8 100644 --- a/docs/c-language/c-assignment-operators.md +++ b/docs/c-language/c-assignment-operators.md @@ -7,7 +7,7 @@ ms.assetid: 11688dcb-c941-44e7-a636-3fc98e7dac40 --- # C Assignment Operators -An assignment operation assigns the value of the right-hand operand to the storage location named by the left-hand operand. Therefore, the left-hand operand of an assignment operation must be a modifiable l-value. After the assignment, an assignment expression has the value of the left operand but is not an l-value. +An assignment operation assigns the value of the right-hand operand to the storage location named by the left-hand operand. Therefore, the left-hand operand of an assignment operation must be a modifiable l-value. After the assignment, an assignment expression has the value of the left operand but isn't an l-value. ## Syntax @@ -15,24 +15,24 @@ An assignment operation assigns the value of the right-hand operand to the stora  *`conditional-expression`*\  *`unary-expression`* *`assignment-operator`* *`assignment-expression`* -*`assignment-operator`*: one of
+*`assignment-operator`*: one of\  **`=`** **`*=`** **`/=`** **`%=`** **`+=`** **`-=`** **`<<=`** **`>>=`** **`&=`** **`^=`** **`|=`** The assignment operators in C can both transform and assign values in a single operation. C provides the following assignment operators: -|Operator|Operation Performed| -|--------------|-------------------------| -|**`=`**|Simple assignment| -|**`*=`**|Multiplication assignment| -|**`/=`**|Division assignment| -|**`%=`**|Remainder assignment| -|**`+=`**|Addition assignment| -|**`-=`**|Subtraction assignment| -|**`<<=`**|Left-shift assignment| -|**`>>=`**|Right-shift assignment| -|**`&=`**|Bitwise-AND assignment| -|**`^=`**|Bitwise-exclusive-OR assignment| -|**`|=`**|Bitwise-inclusive-OR assignment| +| Operator | Operation Performed | +|---|---| +| **`=`** | Simple assignment | +| **`*=`** | Multiplication assignment | +| **`/=`** | Division assignment | +| **`%=`** | Remainder assignment | +| **`+=`** | Addition assignment | +| **`-=`** | Subtraction assignment | +| **`<<=`** | Left-shift assignment | +| **`>>=`** | Right-shift assignment | +| **`&=`** | Bitwise-AND assignment | +| **`^=`** | Bitwise-exclusive-OR assignment | +| **` | =`** | Bitwise-inclusive-OR assignment | In assignment, the type of the right-hand value is converted to the type of the left-hand value, and the value is stored in the left operand after the assignment has taken place. The left operand must not be an array, a function, or a constant. The specific conversion path, which depends on the two types, is outlined in detail in [Type Conversions](../c-language/type-conversions-c.md). diff --git a/docs/c-language/c-bit-fields.md b/docs/c-language/c-bit-fields.md index f581def8fc..ddd8fac1af 100644 --- a/docs/c-language/c-bit-fields.md +++ b/docs/c-language/c-bit-fields.md @@ -11,24 +11,24 @@ In addition to declarators for members of a structure or union, a structure decl ## Syntax -*struct-declarator*:
-    *declarator*
-    *type-specifier* *declarator*opt **:** *constant-expression* +*`struct-declarator`*:\ + *`declarator`*\ + *`type-specifier`* *`declarator`*opt **`:`** *`constant-expression`* -The *constant-expression* specifies the width of the field in bits. The *type-specifier* for the `declarator` must be **`unsigned int`**, **`signed int`**, or **`int`**, and the *constant-expression* must be a nonnegative integer value. If the value is zero, the declaration has no `declarator`. Arrays of bit fields, pointers to bit fields, and functions returning bit fields are not allowed. The optional `declarator` names the bit field. Bit fields can only be declared as part of a structure. The address-of operator (**&**) cannot be applied to bit-field components. +The *`constant-expression`* specifies the width of the field in bits. The *`type-specifier`* for the `declarator` must be **`unsigned int`**, **`signed int`**, or **`int`**, and the *`constant-expression`* must be a nonnegative integer value. If the value is zero, the declaration has no `declarator`. Arrays of bit fields, pointers to bit fields, and functions returning bit fields aren't allowed. The optional `declarator` names the bit field. Bit fields can only be declared as part of a structure. The address-of operator (**`&`**) can't be applied to bit-field components. -Unnamed bit fields cannot be referenced, and their contents at run time are unpredictable. They can be used as "dummy" fields, for alignment purposes. An unnamed bit field whose width is specified as 0 guarantees that storage for the member following it in the *struct-declaration-list* begins on an **`int`** boundary. +Unnamed bit fields can't be referenced, and their contents at run time are unpredictable. They can be used as "dummy" fields, for alignment purposes. An unnamed bit field whose width is specified as 0 guarantees that storage for the member following it in the *struct-declaration-list* begins on an **`int`** boundary. -Bit fields must also be long enough to contain the bit pattern. For example, these two statements are not legal: +The number of bits in a bit field must be less than or equal to the size of the underlying type. For example, these two statements aren't legal: -``` +```C short a:17; /* Illegal! */ int long y:33; /* Illegal! */ ``` This example defines a two-dimensional array of structures named `screen`. -``` +```C struct { unsigned short icon : 8; @@ -38,9 +38,9 @@ struct } screen[25][80]; ``` -The array contains 2,000 elements. Each element is an individual structure containing four bit-field members: `icon`, `color`, `underline`, and `blink`. The size of each structure is two bytes. +The array contains 2,000 elements. Each element is an individual structure containing four bit-field members: `icon`, `color`, `underline`, and `blink`. The size of each structure is 2 bytes. -Bit fields have the same semantics as the integer type. This means a bit field is used in expressions in exactly the same way as a variable of the same base type would be used, regardless of how many bits are in the bit field. +Bit fields have the same semantics as the integer type. A bit field is used in expressions in exactly the same way as a variable of the same base type would be used. It doesn't matter how many bits are in the bit field. **Microsoft Specific** @@ -72,9 +72,9 @@ the bits of `test` would be arranged as follows: cccccccb bbbbaaaa ``` -Since the 8086 family of processors stores the low byte of integer values before the high byte, the integer `0x01F2` above would be stored in physical memory as `0xF2` followed by `0x01`. +Since the 8086 family of processors store the low byte of integer values before the high byte, the integer `0x01F2` would be stored in physical memory as `0xF2` followed by `0x01`. -The ISO C99 standard lets an implementation choose whether a bit field may straddle two storage instances. Consider this structure, which stores four bit fields that total 64 bits: +The ISO C99 standard lets an implementation choose whether a bit field may straddle two storage instances. Consider this structure, which stores bit fields that total 64 bits: ```C struct diff --git a/docs/c-language/c-bitwise-operators.md b/docs/c-language/c-bitwise-operators.md index 7d21966e18..abb495b294 100644 --- a/docs/c-language/c-bitwise-operators.md +++ b/docs/c-language/c-bitwise-operators.md @@ -7,31 +7,31 @@ ms.assetid: e22127b1-9a2d-4876-b01d-c8f72cec3317 --- # C Bitwise Operators -The bitwise operators perform bitwise-AND (**&**), bitwise-exclusive-OR (**^**), and bitwise-inclusive-OR (**|**) operations. +The bitwise operators perform bitwise-AND (**`&`**), bitwise-exclusive-OR (**`^`**), and bitwise-inclusive-OR (**`|`**) operations. ## Syntax -*AND-expression*: -  *equality-expression* -  *AND-expression* **&** *equality-expression* +*`AND-expression`*:\ + *`equality-expression`*\ + *`AND-expression`* **`&`** *`equality-expression`* -*exclusive-OR-expression*: -  *AND-expression* -  *exclusive-OR-expression* **^** *AND-expression* +*`exclusive-OR-expression`*:\ + *`AND-expression`*\ + *`exclusive-OR-expression`* **`^`** *`AND-expression`* -*inclusive-OR-expression*: -  *exclusive-OR-expression* -  *inclusive-OR-expression* | *exclusive-OR-expression* +*`inclusive-OR-expression`*:\ + *`exclusive-OR-expression`* + *`inclusive-OR-expression`* **`|`** *`exclusive-OR-expression`* The operands of bitwise operators must have integral types, but their types can be different. These operators perform the usual arithmetic conversions; the type of the result is the type of the operands after conversion. The C bitwise operators are described below: -|Operator|Description| -|--------------|-----------------| -|**&**|The bitwise-AND operator compares each bit of its first operand to the corresponding bit of its second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0.| -|**^**|The bitwise-exclusive-OR operator compares each bit of its first operand to the corresponding bit of its second operand. If one bit is 0 and the other bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0.| -|**|**|The bitwise-inclusive-OR operator compares each bit of its first operand to the corresponding bit of its second operand. If either bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0.| +| Operator | Description | +|--|--| +| **`&`** | The bitwise-AND operator compares each bit of its first operand to the corresponding bit of its second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. | +| **`^`** | The bitwise-exclusive-OR operator compares each bit of its first operand to the corresponding bit of its second operand. If one bit is 0 and the other bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. | +| **`|`** | The bitwise-inclusive-OR operator compares each bit of its first operand to the corresponding bit of its second operand. If either bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. | ## Examples @@ -57,7 +57,7 @@ The bitwise-inclusive OR in the second example results in the value 0xABCD (hexa **Microsoft Specific** -The results of bitwise operation on signed integers is implementation-defined according to the ANSI C standard. For the Microsoft C compiler, bitwise operations on signed integers work the same as bitwise operations on unsigned integers. For example, `-16 & 99` can be expressed in binary as +The result of a bitwise operation on signed integers is implementation-defined according to the C standard. For the Microsoft C compiler, bitwise operations on signed integers work the same as bitwise operations on unsigned integers. For example, `-16 & 99` can be expressed in binary as ```Expression 11111111 11110000 @@ -72,6 +72,6 @@ The result of the bitwise AND is 96 decimal. ## See also -[Bitwise AND Operator: &](../cpp/bitwise-and-operator-amp.md)
-[Bitwise Exclusive OR Operator: ^](../cpp/bitwise-exclusive-or-operator-hat.md)
-[Bitwise Inclusive OR Operator: |](../cpp/bitwise-inclusive-or-operator-pipe.md) +[Bitwise AND Operator: `&`](../cpp/bitwise-and-operator-amp.md)\ +[Bitwise Exclusive OR Operator: `^`](../cpp/bitwise-exclusive-or-operator-hat.md)\ +[Bitwise Inclusive OR Operator: `|`](../cpp/bitwise-inclusive-or-operator-pipe.md) diff --git a/docs/c-language/c-character-constants.md b/docs/c-language/c-character-constants.md index dc7bf20e97..e96fe00a6f 100644 --- a/docs/c-language/c-character-constants.md +++ b/docs/c-language/c-character-constants.md @@ -11,44 +11,35 @@ A "character constant" is formed by enclosing a single character from the repres ## Syntax -*character-constant*: -**'** *c-char-sequence* **'** - -**L'** *c-char-sequence* **'** - -*c-char-sequence*: -*c-char* - -*c-char-sequence c-char* - -*c-char*: -Any member of the source character set except the single quotation mark (**'**), backslash (**\\**), or newline character - -*escape-sequence* - -*escape-sequence*: -*simple-escape-sequence* - -*octal-escape-sequence* - -*hexadecimal-escape-sequence* - -*simple-escape-sequence*: one of -**\a \b \f \n \r \t \v** - -**\\' \\" \\\ \\?** - -*octal-escape-sequence*: -**\\** *octal-digit* - -**\\** *octal-digit octal-digit* - -**\\** *octal-digit octal-digit octal-digit* - -*hexadecimal-escape-sequence*: -**\x** *hexadecimal-digit* - -*hexadecimal-escape-sequence hexadecimal-digit* +*`character-constant`*:\ + **`'`** *`c-char-sequence`* **`'`**\ + **`L'`** *`c-char-sequence`* **`'`** + +*`c-char-sequence`*:\ + *`c-char`*\ + *`c-char-sequence`* *`c-char`* + +*`c-char`*:\ + Any member of the source character set except the single quotation mark (**`'`**), backslash (**`\`**), or newline character\ + *`escape-sequence`* + +*`escape-sequence`*:\ + *`simple-escape-sequence`*\ + *`octal-escape-sequence`*\ + *`hexadecimal-escape-sequence`* + +*`simple-escape-sequence`*: one of\ + **`\a`** **`\b`** **`\f`** **`\n`** **`\r`** **`\t`** **`\v`**\ + **`\'`** **`\"`** **`\\`** **`\?`** + +*`octal-escape-sequence`*:\ + **`\`** *`octal-digit`*\ + **`\`** *`octal-digit`* *`octal-digit`*\ + **`\`** *`octal-digit`* *`octal-digit`* *`octal-digit`* + +*`hexadecimal-escape-sequence`*:\ + **`\x`** *`hexadecimal-digit`*\ + *`hexadecimal-escape-sequence`* *`hexadecimal-digit`* ## See also diff --git a/docs/c-language/c-comments.md b/docs/c-language/c-comments.md index cb2d216b87..aaa1c15a1e 100644 --- a/docs/c-language/c-comments.md +++ b/docs/c-language/c-comments.md @@ -7,9 +7,9 @@ ms.assetid: 0f5f2825-e673-49e7-8669-94e2f5294989 --- # C Comments -A "comment" is a sequence of characters beginning with a forward slash/asterisk combination (/\*) that is treated as a single white-space character by the compiler and is otherwise ignored. A comment can include any combination of characters from the representable character set, including newline characters, but excluding the "end comment" delimiter (\*/). Comments can occupy more than one line but cannot be nested. +A "comment" is a sequence of characters beginning with a forward slash/asterisk combination (/\*) that is treated as a single white-space character by the compiler and is otherwise ignored. A comment can include any combination of characters from the representable character set, including newline characters, but excluding the "end comment" delimiter (\*/). Comments can occupy more than one line but can't be nested. -Comments can appear anywhere a white-space character is allowed. Since the compiler treats a comment as a single white-space character, you cannot include comments within tokens. The compiler ignores the characters in the comment. +Comments can appear anywhere a white-space character is allowed. Since the compiler treats a comment as a single white-space character, you can't include comments within tokens. The compiler ignores the characters in the comment. Use comments to document your code. This example is a comment accepted by the compiler: @@ -32,7 +32,7 @@ You can choose to precede functions or program modules with a descriptive commen */ ``` -Since comments cannot contain nested comments, this example causes an error: +Since comments can't contain nested comments, this example causes an error: ```C /* Comment out this routine for testing @@ -51,13 +51,13 @@ While you can use comments to render certain lines of code inactive for test pur **Microsoft Specific** -The Microsoft compiler also supports single-line comments preceded by two forward slashes (__//__). If you compile with /Za (ANSI standard), these comments generate errors. These comments cannot extend to a second line. +The Microsoft compiler also supports single-line comments preceded by two forward slashes (**`//`**). These comments can't extend to a second line. ```C // This is a valid comment ``` -Comments beginning with two forward slashes (__//__) are terminated by the next newline character that is not preceded by an escape character. In the next example, the newline character is preceded by a backslash (**\\**), creating an "escape sequence." This escape sequence causes the compiler to treat the next line as part of the previous line. (For more information, see [Escape Sequences](../c-language/escape-sequences.md).) +Comments beginning with two forward slashes (**`//`**) are terminated by the next newline character that isn't preceded by an escape character. In the next example, the newline character is preceded by a backslash (**`\`**), creating an "escape sequence." This escape sequence causes the compiler to treat the next line as part of the previous line. (For more information, see [Escape Sequences](../c-language/escape-sequences.md).) ```C // my comment \ diff --git a/docs/c-language/c-enumeration-declarations.md b/docs/c-language/c-enumeration-declarations.md index 6f9153022e..08d1312b46 100644 --- a/docs/c-language/c-enumeration-declarations.md +++ b/docs/c-language/c-enumeration-declarations.md @@ -103,7 +103,7 @@ enum BOOLEAN end_flag, match_flag; /* Two variables of type BOOLEAN */ This declaration can also be specified as ```C -enum BOOLEAN { false, true } end_flag, match_flag;\ +enum BOOLEAN { false, true } end_flag, match_flag; ``` or as @@ -133,4 +133,4 @@ enum { yes, no } response; ## See also -[Enumerations](../cpp/enumerations-cpp.md) +[Enumerations(C++)](../cpp/enumerations-cpp.md) diff --git a/docs/c-language/c-extended-storage-class-attributes.md b/docs/c-language/c-extended-storage-class-attributes.md index fc0a478032..544263691b 100644 --- a/docs/c-language/c-extended-storage-class-attributes.md +++ b/docs/c-language/c-extended-storage-class-attributes.md @@ -16,17 +16,17 @@ The extended attribute syntax for specifying storage-class information uses the ## Syntax -*`storage-class-specifier`*:
+*`storage-class-specifier`*:\  **`__declspec (`** *`extended-decl-modifier-seq`* **`)`** /\* Microsoft-specific \*/ -*`extended-decl-modifier-seq`*: /\* Microsoft-specific \*/
- *`extended-decl-modifier`*opt
+*`extended-decl-modifier-seq`*: /\* Microsoft-specific \*/\ + *`extended-decl-modifier`*opt\  *`extended-decl-modifier-seq`* *`extended-decl-modifier`* -*`extended-decl-modifier`*: /\* Microsoft-specific \*/
- **`thread`**
- **`naked`**
- **`dllimport`**
+*`extended-decl-modifier`*: /\* Microsoft-specific \*/\ + **`thread`**\ + **`naked`**\ + **`dllimport`**\  **`dllexport`** White space separates the declaration modifiers. An *`extended-decl-modifier-seq`* can be empty; in this case, **`__declspec`** has no effect. diff --git a/docs/c-language/c-floating-point-constants.md b/docs/c-language/c-floating-point-constants.md index f95d294852..98876f7e43 100644 --- a/docs/c-language/c-floating-point-constants.md +++ b/docs/c-language/c-floating-point-constants.md @@ -10,26 +10,26 @@ A "floating-point constant" is a decimal number that represents a signed real nu ## Syntax -*`floating-point-constant`*:
- *`fractional-constant`* *`exponent-part`*opt *`floating-suffix`*opt
+*`floating-point-constant`*:\ + *`fractional-constant`* *`exponent-part`*opt *`floating-suffix`*opt\  *`digit-sequence`* *`exponent-part`* *`floating-suffix`*opt -*`fractional-constant`*:
- *`digit-sequence`*opt **.** *`digit-sequence`*
+*`fractional-constant`*:\ + *`digit-sequence`*opt **.** *`digit-sequence`*\  *`digit-sequence`* **.** -*`exponent-part`*:
- **e** *`sign`*opt *`digit-sequence`*
+*`exponent-part`*:\ + **e** *`sign`*opt *`digit-sequence`*\  **E** *`sign`*opt *`digit-sequence`* -*`sign`*: one of
+*`sign`*: one of\  **`+`** **`-`** -*`digit-sequence`*:
- *`digit`*
+*`digit-sequence`*:\ + *`digit`*\  *`digit-sequence`* *`digit`* -*`floating-suffix`*: one of
+*`floating-suffix`*: one of\  **`f`** **`l`** **`F`** **`L`** You can omit either the digits before the decimal point (the integer portion of the value) or the digits after the decimal point (the fractional portion), but not both. You may leave out the decimal point only if you include an exponent. No white-space characters can separate the digits or characters of the constant. diff --git a/docs/c-language/c-function-definitions.md b/docs/c-language/c-function-definitions.md index e0808d1490..91f45c71fb 100644 --- a/docs/c-language/c-function-definitions.md +++ b/docs/c-language/c-function-definitions.md @@ -11,71 +11,71 @@ A function definition specifies the name of the function, the types and number o ## Syntax -*translation-unit*:
-    *external-declaration*
-    *translation-unit* *external-declaration* +*`translation-unit`*:\ + *`external-declaration`* \ + *`translation-unit`* *`external-declaration`* -*external-declaration*: /\* Allowed only at external (file) scope \*/
-    *function-definition*
-    *declaration* +*`external-declaration`*: /\* Allowed only at external (file) scope \*/\ + *`function-definition`*\ + *`declaration`* -*function-definition*:
-    *declaration-specifiers*opt *attribute-seq*opt *declarator* *declaration-list*opt *compound-statement* +*`function-definition`*:\ + *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* -/\* *attribute-seq* is Microsoft-specific \*/ +/\* *`attribute-seq`* is Microsoft-specific \*/ Prototype parameters are: -*declaration-specifiers*:
-    *storage-class-specifier* *declaration-specifiers*opt
-    *type-specifier* *declaration-specifiers*opt
-    *type-qualifier* *declaration-specifiers*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt \ + *`type-specifier`* *`declaration-specifiers`*opt\ + *`type-qualifier`* *`declaration-specifiers`*opt -*declaration-list*:
-    *declaration*
-    *declaration-list* *declaration* +*`declaration-list`*:\ + *`declaration`*\ + *`declaration-list`* *`declaration`* -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*: /\* A function declarator \*/
-    *direct-declarator* **(** *parameter-type-list* **)** /\* New-style declarator \*/
-    *direct-declarator* **(** *identifier-list*opt **)** /\* Obsolete-style declarator \*/ +*`direct-declarator`*: /\* A function declarator \*/\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`** /\* New-style declarator \*/\ + *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** /\* Obsolete-style declarator \*/ The parameter list in a definition uses this syntax: -*parameter-type-list*: /\* The parameter list \*/
-    *parameter-list*
-    *parameter-list* **, ...** +*`parameter-type-list`*: /\* The parameter list \*/\ + *`parameter-list`* \ + *`parameter-list`* **`, ...`** -*parameter-list*:
-    *parameter-declaration*
-    *parameter-list* **,** *parameter-declaration* +*`parameter-list`*:\ + *`parameter-declaration`*\ + *`parameter-list`* **`,`** *`parameter-declaration`* -*parameter-declaration*:
-    *declaration-specifiers* *declarator*
-    *declaration-specifiers* *abstract-declarator*opt +*`parameter-declaration`*:\ + *`declaration-specifiers`* *`declarator`*\ + *`declaration-specifiers`* *`abstract-declarator`*opt The parameter list in an old-style function definition uses this syntax: -*identifier-list*: /\* Used in obsolete-style function definitions and declarations \*/
-    *identifier*
-    *identifier-list* **,** *identifier* +*`identifier-list`*: /\* Used in obsolete-style function definitions and declarations \*/\ + *`identifier`*\ + *`identifier-list`* **`,`** *`identifier`* The syntax for the function body is: -*compound-statement*:
-    **{** *declaration-list*opt *statement-list*opt **}** +*`compound-statement`*:\ + **`{`** *`declaration-list`*opt *`statement-list`*opt **`}`** -The only storage-class specifiers that can modify a function declaration are **`extern`** and **`static`**. The **`extern`** specifier signifies that the function can be referenced from other files; that is, the function name is exported to the linker. The **`static`** specifier signifies that the function cannot be referenced from other files; that is, the name is not exported by the linker. If no storage class appears in a function definition, **`extern`** is assumed. In any case, the function is always visible from the definition point to the end of the file. +The only storage-class specifiers that can modify a function declaration are **`extern`** and **`static`**. The **`extern`** specifier signifies that the function can be referenced from other files; that is, the function name is exported to the linker. The **`static`** specifier signifies that the function can't be referenced from other files; that is, the name isn't exported by the linker. If no storage class appears in a function definition, **`extern`** is assumed. In any case, the function is always visible from the definition point to the end of the file. -The optional *declaration-specifiers* and mandatory *declarator* together specify the function's return type and name. The *declarator* is a combination of the identifier that names the function and the parentheses following the function name. The optional *attribute-seq* nonterminal is a Microsoft-specific feature defined in [Function Attributes](../c-language/function-attributes.md). +The optional *`declaration-specifiers`* and mandatory *`declarator`* together specify the function's return type and name. The *`declarator`* is a combination of the identifier that names the function and the parentheses following the function name. The optional *`attribute-seq`* nonterminal is a Microsoft-specific feature defined in [Function Attributes](../c-language/function-attributes.md). -The *direct-declarator* (in the *declarator* syntax) specifies the name of the function being defined and the identifiers of its parameters. If the *direct-declarator* includes a *parameter-type-list*, the list specifies the types of all the parameters. Such a declarator also serves as a function prototype for later calls to the function. +The *`direct-declarator`* (in the *`declarator`* syntax) specifies the name of the function being defined and the identifiers of its parameters. If the *`direct-declarator`* includes a *`parameter-type-list`*, the list specifies the types of all the parameters. Such a declarator also serves as a function prototype for later calls to the function. -A *declaration* in the *declaration-list* in function definitions cannot contain a *storage-class-specifier* other than **`register`**. The *type-specifier* in the *declaration-specifiers* syntax can be omitted only if the **`register`** storage class is specified for a value of **`int`** type. +A *`declaration`* in the *`declaration-list`* in function definitions can't contain a *`storage-class-specifier`* other than **`register`**. The *`type-specifier`* in the *`declaration-specifiers`* syntax can be omitted only if the **`register`** storage class is specified for a value of **`int`** type. -The *compound-statement* is the function body containing local variable declarations, references to externally declared items, and statements. +The *`compound-statement`* is the function body containing local variable declarations, references to externally declared items, and statements. The sections [Function Attributes](../c-language/function-attributes.md), [Storage Class](../c-language/storage-class.md), [Return Type](../c-language/return-type.md), [Parameters](../c-language/parameters.md), and [Function Body](../c-language/function-body.md) describe the components of the function definition in detail. diff --git a/docs/c-language/c-identifiers.md b/docs/c-language/c-identifiers.md index 4cc86b8a4c..56a44d534e 100644 --- a/docs/c-language/c-identifiers.md +++ b/docs/c-language/c-identifiers.md @@ -7,7 +7,7 @@ ms.assetid: d02edbbc-85a0-4118-997b-84ee6b972eb6 --- # C Identifiers -"Identifiers" or "symbols" are the names you supply for variables, types, functions, and labels in your program. Identifier names must differ in spelling and case from any keywords. You cannot use keywords (either C or Microsoft) as identifiers; they are reserved for special use. You create an identifier by specifying it in the declaration of a variable, type, or function. In this example, `result` is an identifier for an integer variable, and `main` and `printf` are identifier names for functions. +"Identifiers" or "symbols" are the names you supply for variables, types, functions, and labels in your program. Identifier names must differ in spelling and case from any keywords. You can't use keywords (either C or Microsoft) as identifiers; they're reserved for special use. You create an identifier by specifying it in the declaration of a variable, type, or function. In this example, `result` is an identifier for an integer variable, and `main` and `printf` are identifier names for functions. ``` #include @@ -23,27 +23,27 @@ int main() Once declared, you can use the identifier in later program statements to refer to the associated value. -A special kind of identifier, called a statement label, can be used in **`goto`** statements. (Declarations are described in [Declarations and Types](../c-language/declarations-and-types.md) Statement labels are described in [The goto and Labeled Statements](../c-language/goto-and-labeled-statements-c.md).) +A special variety of identifier, called a statement label, can be used in **`goto`** statements. (Declarations are described in [Declarations and Types](../c-language/declarations-and-types.md) Statement labels are described in [The goto and Labeled Statements](../c-language/goto-and-labeled-statements-c.md).) ## Syntax -*identifier*:
-    *nondigit*
-    *identifier* *nondigit*
-    *identifier* *digit* +*`identifier`*:\ + *`nondigit`*\ + *`identifier`* *`nondigit`*\ + *`identifier`* *`digit`* -*nondigit*: one of
-    **_ a b c d e f g h i j k l mn o p q r s t u v w x y z**
-    **A B C D E F G H I J K L MN O P Q R S T U V W X Y Z** +*`nondigit`*: one of\ + **`_ a b c d e f g h i j k l m n o p q r s t u v w x y z`**\ + **`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`** -*digit*: one of
-    **0 1 2 3 4 5 6 7 8 9** +*`digit`*: one of\ + **`0 1 2 3 4 5 6 7 8 9`** -The first character of an identifier name must be a `nondigit` (that is, the first character must be an underscore or an uppercase or lowercase letter). ANSI allows six significant characters in an external identifier's name and 31 for names of internal (within a function) identifiers. External identifiers (ones declared at global scope or declared with storage class **`extern`**) may be subject to additional naming restrictions because these identifiers have to be processed by other software such as linkers. +The first character of an identifier name must be a *`nondigit`* (that is, the first character must be an underscore or an uppercase or lowercase letter). ANSI allows six significant characters in an external identifier's name and 31 for names of internal (within a function) identifiers. External identifiers (ones declared at global scope or declared with storage class **`extern`**) may be subject to more naming restrictions because these identifiers have to be processed by other software such as linkers. **Microsoft Specific** -Although ANSI allows 6 significant characters in external identifier names and 31 for names of internal (within a function) identifiers, the Microsoft C compiler allows 247 characters in an internal or external identifier name. If you aren't concerned with ANSI compatibility, you can modify this default to a smaller or larger number using the /H (restrict length of external names) option. +Although ANSI allows 6 significant characters in external identifier names and 31 for names of internal (within a function) identifiers, the Microsoft C compiler allows 247 characters in an internal or external identifier name. If you aren't concerned with ANSI compatibility, you can modify this default to use a smaller or larger number by specifying the [`/H` (restrict length of external names)](../build/reference/h-restrict-length-of-external-names.md) option. **END Microsoft Specific** @@ -58,7 +58,7 @@ aDD **Microsoft Specific** -Do not select names for identifiers that begin with two underscores or with an underscore followed by an uppercase letter. The ANSI C standard allows identifier names that begin with these character combinations to be reserved for compiler use. Identifiers with file-level scope should also not be named with an underscore and a lowercase letter as the first two letters. Identifier names that begin with these characters are also reserved. By convention, Microsoft uses an underscore and an uppercase letter to begin macro names and double underscores for Microsoft-specific keyword names. To avoid any naming conflicts, always select identifier names that do not begin with one or two underscores, or names that begin with an underscore followed by an uppercase letter. +Don't select names for identifiers that begin with two underscores or with an underscore followed by an uppercase letter. The ANSI C standard allows identifier names that begin with these character combinations to be reserved for compiler use. Identifiers with file-level scope should also not be named with an underscore and a lowercase letter as the first two letters. Identifier names that begin with these characters are also reserved. By convention, Microsoft uses an underscore and an uppercase letter to begin macro names and double underscores for Microsoft-specific keyword names. To avoid any naming conflicts, always select identifier names that don't begin with one or two underscores, or names that begin with an underscore followed by an uppercase letter. **END Microsoft Specific** @@ -75,7 +75,7 @@ LastNum **Microsoft Specific** -Although identifiers in source files are case sensitive by default, symbols in object files are not. Microsoft C treats identifiers within a compilation unit as case sensitive. +Although identifiers in source files are case sensitive by default, symbols in object files aren't. Microsoft C treats identifiers within a compilation unit as case sensitive. The Microsoft linker is case sensitive. You must specify all identifiers consistently according to case. @@ -83,7 +83,7 @@ The "source character set" is the set of legal characters that can appear in sou **END Microsoft Specific** -An identifier has "scope," which is the region of the program in which it is known, and "linkage," which determines whether the same name in another scope refers to the same identifier. These topics are explained in [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md). +An identifier has "scope," which is the region of the program in which it's known. It also has "linkage," which determines whether the same name in another scope refers to the same identifier. These terms are explained in [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md). ## See also diff --git a/docs/c-language/c-integer-constants.md b/docs/c-language/c-integer-constants.md index d552935d9b..03a08c77ea 100644 --- a/docs/c-language/c-integer-constants.md +++ b/docs/c-language/c-integer-constants.md @@ -7,66 +7,66 @@ ms.assetid: fcf6b83c-2038-49ec-91ca-3d5ca1f83037 --- # C Integer Constants -An *integer constant* is a decimal (base 10), octal (base 8), or hexadecimal (base 16) number that represents an integral value. Use integer constants to represent integer values that cannot be changed. +An *integer constant* is a decimal (base 10), octal (base 8), or hexadecimal (base 16) number that represents an integral value. Use integer constants to represent integer values that can't be changed. ## Syntax -*integer-constant*:
-    *decimal-constant* *integer-suffix*opt
-    *octal-constant* *integer-suffix*opt
-    *hexadecimal-constant* *integer-suffix*opt +*`integer-constant`*:\ + *`decimal-constant`* *`integer-suffix`*opt\ + *`octal-constant`* *`integer-suffix`*opt\ + *`hexadecimal-constant`* *`integer-suffix`*opt -*decimal-constant*:
-    *nonzero-digit*
-    *decimal-constant* *digit* +*`decimal-constant`*:\ + *`nonzero-digit`*\ + *`decimal-constant`* *`digit`* -*octal-constant*:
-    **0**
-    *octal-constant* *octal-digit* +*`octal-constant`*:\ + **`0`**\ + *`octal-constant`* *`octal-digit`* -*hexadecimal-constant*:
-    *hexadecimal-prefix* *hexadecimal-digit*
-    *hexadecimal-constant* *hexadecimal-digit* +*`hexadecimal-constant`*:\ + *`hexadecimal-prefix`* *`hexadecimal-digit`*\ + *`hexadecimal-constant`* *`hexadecimal-digit`* -*hexadecimal-prefix*: one of
-    **0x** **0X** +*`hexadecimal-prefix`*: one of\ + **`0x`** **`0X`** -*nonzero-digit*: one of
-    **1 2 3 4 5 6 7 8 9** +*`nonzero-digit`*: one of\ + **`1 2 3 4 5 6 7 8 9`** -*octal-digit*: one of
-    **0 1 2 3 4 5 6 7** +*`octal-digit`*: one of\ + **`0 1 2 3 4 5 6 7`** -*hexadecimal-digit*: one of
-    **0 1 2 3 4 5 6 7 8 9**
-    **a b c d e f**
-    **A B C D E F** +*`hexadecimal-digit`*: one of\ + **`0 1 2 3 4 5 6 7 8 9`**\ + **`a b c d e f`**\ + **`A B C D E F`** -*integer-suffix*:
-    *unsigned-suffix* *long-suffix*opt
-    *unsigned-suffix* *long-long-suffix*
-    *unsigned-suffix* *64-bit-integer-suffix*
-    *long-suffix* *unsigned-suffix*opt
-    *long-long-suffix* *unsigned-suffix*opt
-    *64-bit-integer-suffix* +*`integer-suffix`*:\ + *`unsigned-suffix`* *`long-suffix`*opt\ + *`unsigned-suffix`* *`long-long-suffix`*\ + *`unsigned-suffix`* *`64-bit-integer-suffix`*\ + *`long-suffix`* *`unsigned-suffix`*opt\ + *`long-long-suffix`* *`unsigned-suffix`*opt\ + *`64-bit-integer-suffix`* -*unsigned-suffix*: one of
-    **u U** +*`unsigned-suffix`*: one of\ + **`u U`** -*long-suffix*: one of
-    **l L** +*`long-suffix`*: one of\ + **`l L`** -*long-long-suffix*: one of
-    **ll LL** +*`long-long-suffix`*: one of\ + **`ll LL`** -*64-bit-integer-suffix*: one of
-    **i64 I64** +*`64-bit-integer-suffix`*: one of\ + **`i64 I64`** -The **i64** and **I64** suffixes are Microsoft-specific. +The **`i64`** and **`I64`** suffixes are Microsoft-specific. -Integer constants are positive unless they are preceded by a minus sign (**-**). The minus sign is interpreted as the unary arithmetic negation operator. (See [Unary Arithmetic Operators](../c-language/unary-arithmetic-operators.md) for information about this operator.) +Integer constants are positive unless they're preceded by a minus sign (**`-`**). The minus sign is interpreted as the unary arithmetic negation operator. (See [Unary Arithmetic Operators](../c-language/unary-arithmetic-operators.md) for information about this operator.) -If an integer constant begins with **0x** or **0X**, it is hexadecimal. If it begins with the digit **0**, it is octal. Otherwise, it is assumed to be decimal. +If an integer constant begins with **`0x`** or **`0X`**, it's hexadecimal. If it begins with the digit **`0`**, it's octal. Otherwise, it's assumed to be decimal. The following integer constants are equivalent: diff --git a/docs/c-language/c-keywords.md b/docs/c-language/c-keywords.md index 7ab089e397..37810945be 100644 --- a/docs/c-language/c-keywords.md +++ b/docs/c-language/c-keywords.md @@ -47,6 +47,8 @@ The C language uses the following keywords: **`struct`**\ **`switch`**\ **`typedef`**\ + **[`typeof`](typeof-c.md)**\ + **[`typeof_unqual`](typeof-unqual-c.md)**\ **`union`**\ **`unsigned`**\ **`void`**\ @@ -67,12 +69,9 @@ The C language uses the following keywords: :::column-end::: :::row-end::: -1 Keywords introduced in ISO C99. - -2 Keywords introduced in ISO C11. - -a Starting in Visual Studio 2019 version 16.8, these keywords are supported in code compiled as C when the **`/std:c11`** or **`/std:c17`** compiler options are specified. - +1 Keywords introduced in ISO C99.\ +2 Keywords introduced in ISO C11.\ +a Starting in Visual Studio 2019 version 16.8, these keywords are supported in code compiled as C when the **`/std:c11`** or **`/std:c17`** compiler options are specified.\ b Starting in Visual Studio 2019 version 16.8, these keywords are recognized but not supported by the compiler in code compiled as C when the **`/std:c11`** or **`/std:c17`** compiler options are specified. You can't redefine keywords. However, you can specify text to replace keywords before compilation by using C [preprocessor directives](../preprocessor/preprocessor-directives.md). @@ -105,6 +104,8 @@ The following keywords and special identifiers are recognized by the Microsoft C :::column::: **`__stdcall`**5\ **`__try`**5\ + **[`__typeof__`](typeof-c.md)**\ + **[`__typeof_unqual__`](typeof-unqual-c.md)**\ **`dllexport`**4\ **`dllimport`**4\ **`naked`**4\ @@ -113,17 +114,14 @@ The following keywords and special identifiers are recognized by the Microsoft C :::column-end::: :::row-end::: -3 The **`__based`** keyword has limited uses for 32-bit and 64-bit target compilations. - -4 These are special identifiers when used with **`__declspec`**; their use in other contexts is unrestricted. - -5 For compatibility with previous versions, these keywords are available both with two leading underscores and a single leading underscore when Microsoft extensions are enabled. - +3 The **`__based`** keyword has limited uses for 32-bit and 64-bit target compilations.\ +4 These are special identifiers when used with **`__declspec`**; their use in other contexts is unrestricted.\ +5 For compatibility with previous versions, these keywords are available both with two leading underscores and a single leading underscore when Microsoft extensions are enabled.\ 6 If you don't include , the Microsoft Visual C compiler maps **`static_assert`** to the C11 **`_Static_assert`** keyword. -Microsoft extensions are enabled by default. To assist in creating portable code, you can disable Microsoft extensions by specifying the [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. When you use this option, some Microsoft-specific keywords are disabled. +Microsoft extensions are enabled by default. To help create portable code, you can disable Microsoft extensions by specifying the [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. When you use this option, some Microsoft-specific keywords are disabled. -When Microsoft extensions are enabled, you can use the keywords listed above in your programs. To conform to the language standard, most of these keywords are prefaced by a double underscore. The four exceptions, **`dllexport`**, **`dllimport`**, **`naked`**, and **`thread`**, are used only with **`__declspec`** and don't require a leading double underscore. For backward compatibility, single-underscore versions of the rest of the keywords are supported. +When Microsoft extensions are enabled, you can use the keywords listed above in your programs. To conform to the language standard, most of these keywords have a leading double underscore. The four exceptions, **`dllexport`**, **`dllimport`**, **`naked`**, and **`thread`**, are used only with **`__declspec`** and don't require a leading double underscore. For backward compatibility, single-underscore versions of the rest of the keywords are supported. ## See also diff --git a/docs/c-language/c-logical-operators.md b/docs/c-language/c-logical-operators.md index 387ee79abe..06eaf4090b 100644 --- a/docs/c-language/c-logical-operators.md +++ b/docs/c-language/c-logical-operators.md @@ -7,30 +7,30 @@ ms.assetid: c0a4e766-ad56-4300-bf76-b28dc0e19b43 --- # C logical operators -The logical operators perform logical-AND (**&&**) and logical-OR (**||**) operations. +The logical operators perform logical-AND (**`&&`**) and logical-OR (**`||`**) operations. ## Syntax -*logical-AND-expression*:
-    *inclusive-OR-expression*
-    *logical-AND-expression* **&&** *inclusive-OR-expression* +*`logical-AND-expression`*:\ + *`inclusive-OR-expression`*\ + *`logical-AND-expression`* **`&&`** *`inclusive-OR-expression`* -*logical-OR-expression*:
-    *logical-AND-expression*
-    *logical-OR-expression* **||** *logical-AND-expression* +*`logical-OR-expression`*:\ + *`logical-AND-expression`*\ + *`logical-OR-expression`* **`||`** *`logical-AND-expression`* ## Remarks -Logical operators do not perform the usual arithmetic conversions. Instead, they evaluate each operand in terms of its equivalence to 0. The result of a logical operation is either 0 or 1. The result's type is **`int`**. +Logical operators don't perform the usual arithmetic conversions. Instead, they evaluate each operand in terms of its equivalence to 0. The result of a logical operation is either 0 or 1. The type of the result is **`int`**. The C logical operators are described below: -|Operator|Description| -|--------------|-----------------| -|**&&**|The logical-AND operator produces the value 1 if both operands have nonzero values. If either operand is equal to 0, the result is 0. If the first operand of a logical-AND operation is equal to 0, the second operand is not evaluated.| -|**||**|The logical-OR operator performs an inclusive-OR operation on its operands. The result is 0 if both operands have 0 values. If either operand has a nonzero value, the result is 1. If the first operand of a logical-OR operation has a nonzero value, the second operand is not evaluated.| +| Operator | Description | +|--|--| +| **`&&`** | The logical-AND operator produces the value 1 if both operands have nonzero values. If either operand is equal to 0, the result is 0. If the first operand of a logical-AND operation is equal to 0, the second operand isn't evaluated. | +| **`||`** | The logical-OR operator performs an inclusive-OR operation on its operands. The result is 0 if both operands have 0 values. If either operand has a nonzero value, the result is 1. If the first operand of a logical-OR operation has a nonzero value, the second operand isn't evaluated. | -The operands of logical-AND and logical-OR expressions are evaluated from left to right. If the value of the first operand is sufficient to determine the result of the operation, the second operand is not evaluated. This is called "short-circuit evaluation." There is a sequence point after the first operand. See [Sequence Points](../c-language/c-sequence-points.md) for more information. +The operands of logical-AND and logical-OR expressions are evaluated from left to right. If the value of the first operand is sufficient to determine the result of the operation, the second operand isn't evaluated. This effect is known as "short-circuit" evaluation. There's a sequence point after the first operand in the expression. For more information, see [Sequence points](../c-language/c-sequence-points.md). ## Examples @@ -43,15 +43,15 @@ if ( x < y && y < z ) printf( "x is less than z\n" ); ``` -In this example, the **printf** function is called to print a message if `x` is less than `y` and `y` is less than `z`. If `x` is greater than `y`, the second operand (`y < z`) is not evaluated and nothing is printed. Note that this could cause problems in cases where the second operand has side effects that are being relied on for some other reason. +In this example, the `printf` function is called to print a message if `x` is less than `y` and `y` is less than `z`. If `x` is greater than `y`, the second operand (`y < z`) isn't evaluated and nothing is printed. It's another case of short-circuit evaluation that must be considered when writing logical comparisons. Otherwise, it could cause problems if code relies on the side-effects of evaluating the second operand. ```C printf( "%d" , (x == w || x == y || x == z) ); ``` -In this example, if `x` is equal to either `w`, `y`, or `z`, the second argument to the **printf** function evaluates to true and the value 1 is printed. Otherwise, it evaluates to false and the value 0 is printed. As soon as one of the conditions evaluates to true, evaluation ceases. +In this example, if `x` is equal to either `w`, `y`, or `z`, the second argument to the `printf` function evaluates to true and the value 1 is printed. Otherwise, it evaluates to false and the value 0 is printed. As soon as one of the conditions evaluates to true, evaluation ceases. ## See also -- [Logical AND Operator: &&](../cpp/logical-and-operator-amp-amp.md) -- [Logical OR Operator: ||](../cpp/logical-or-operator-pipe-pipe.md) +- [Logical AND operator: `&&`](../cpp/logical-and-operator-amp-amp.md) +- [Logical OR operator: `||`](../cpp/logical-or-operator-pipe-pipe.md) diff --git a/docs/c-language/c-multiplicative-operators.md b/docs/c-language/c-multiplicative-operators.md index 72b67af583..986ee8c86c 100644 --- a/docs/c-language/c-multiplicative-operators.md +++ b/docs/c-language/c-multiplicative-operators.md @@ -7,30 +7,30 @@ ms.assetid: 495471c9-319b-4eb4-bd97-039a025fd3a9 --- # C Multiplicative Operators -The multiplicative operators perform multiplication (\*), division (**/**), and remainder (**%**) operations. +The multiplicative operators perform multiplication (**`*`**), division (**`/`**), and remainder (**`%`**) operations. ## Syntax -*multiplicative-expression*: -    *cast-expression* -    *multiplicative-expression* \* *cast-expression* -    *multiplicative-expression* **/** *cast-expression* -    *multiplicative-expression* **%** *cast-expression* +*`multiplicative-expression`*: + *`cast-expression`* + *`multiplicative-expression`* **`*`** *`cast-expression`* + *`multiplicative-expression`* **`/`** *`cast-expression`* + *`multiplicative-expression`* **`%`** *`cast-expression`* -The operands of the remainder operator (**%**) must be integral. The multiplication (\*) and division (**/**) operators can take integral- or floating-type operands; the types of the operands can be different. +The operands of the remainder operator (**`%`**) must be integral. The multiplication (**`*`**) and division (**`/`**) operators can take integral- or floating-type operands; the types of the operands can be different. The multiplicative operators perform the usual arithmetic conversions on the operands. The type of the result is the type of the operands after conversion. > [!NOTE] > Since the conversions performed by the multiplicative operators do not provide for overflow or underflow conditions, information may be lost if the result of a multiplicative operation cannot be represented in the type of the operands after conversion. -The C multiplicative operators are described below: +The C multiplicative operators are described in this table: -|Operator|Description| -|--------------|-----------------| -|\*|The multiplication operator causes its two operands to be multiplied.| -|**/**|The division operator causes the first operand to be divided by the second. If two integer operands are divided and the result is not an integer, it is truncated according to the following rules:

- The result of division by 0 is undefined according to the ANSI C standard. The Microsoft C compiler generates an error at compile time or run time.

- If both operands are positive or unsigned, the result is truncated toward 0.

- If either operand is negative, whether the result of the operation is the largest integer less than or equal to the algebraic quotient or is the smallest integer greater than or equal to the algebraic quotient is implementation defined. (See the Microsoft-specific section below.)| -|**%**|The result of the remainder operator is the remainder when the first operand is divided by the second. When the division is inexact, the result is determined by the following rules:

- If the right operand is zero, the result is undefined.

- If both operands are positive or unsigned, the result is positive.

- If either operand is negative and the result is inexact, the result is implementation defined. (See the Microsoft-specific section below.)| +| Operator | Description | +|---|---| +| **`*`** | The multiplication operator causes its two operands to be multiplied. | +| **`/`** | The division operator causes the first operand to be divided by the second. If two integer operands are divided and the result isn't an integer, it's truncated according to the following rules:

- The result of division by 0 is undefined according to the ANSI C standard. The Microsoft C compiler generates an error at compile time or run time.

- If both operands are positive or unsigned, the result is truncated toward 0.

- If either operand is negative, whether the result of the operation is the largest integer less than or equal to the algebraic quotient, or is the smallest integer greater than or equal to the algebraic quotient, is implementation defined. (See the Microsoft-specific section.) | +| **`%`** | The result of the remainder operator is the remainder when the first operand is divided by the second. When the division is inexact, the result is determined by the following rules:

- If the right operand is zero, the result is undefined.

- If both operands are positive or unsigned, the result is positive.

- If either operand is negative and the result is inexact, the result is implementation defined. (See the Microsoft-specific section.) | ### Microsoft-specific @@ -40,28 +40,28 @@ If either operation is negative in division with the remainder operator, the res ## Examples -The declarations shown below are used for the following examples: +The declarations shown here are used for the following examples: -``` +```c int i = 10, j = 3, n; double x = 2.0, y; ``` This statement uses the multiplication operator: -``` +```c y = x * i; ``` In this case, `x` is multiplied by `i` to give the value 20.0. The result has **`double`** type. -``` +```c n = i / j; ``` In this example, 10 is divided by 3. The result is truncated toward 0, yielding the integer value 3. -``` +```c n = i % j; ``` @@ -71,7 +71,7 @@ This statement assigns `n` the integer remainder, 1, when 10 is divided by 3. The sign of the remainder is the same as the sign of the dividend. For example: -``` +```c 50 % -6 = 2 -50 % 6 = -2 ``` diff --git a/docs/c-language/c-operators.md b/docs/c-language/c-operators.md index ef33061499..50eadfde67 100644 --- a/docs/c-language/c-operators.md +++ b/docs/c-language/c-operators.md @@ -1,44 +1,45 @@ --- -description: "Learn more about: C Operators" -title: "C Operators" -ms.date: "06/14/2018" +description: "Learn more about: C operators" +title: "C operators" +ms.date: 04/07/2022 helpviewer_keywords: ["ternary operators", "operators [C]", "symbols, operators", "binary operators", "associativity of operators", "binary data, binary expressions"] ms.assetid: 13bc4c8e-2dc9-4b23-9f3a-25064e8777ed --- -# C Operators +# C operators The C operators are a subset of the [C++ built-in operators](../cpp/cpp-built-in-operators-precedence-and-associativity.md). -There are three types of operators. A unary expression consists of either a unary operator prepended to an operand, or the **`sizeof`** keyword followed by an expression. The expression can be either the name of a variable or a cast expression. If the expression is a cast expression, it must be enclosed in parentheses. A binary expression consists of two operands joined by a binary operator. A ternary expression consists of three operands joined by the conditional-expression operator. +There are three types of operators. A unary expression consists of either a unary operator followed by an operand, or the **`sizeof`** or **`_Alignof`** keyword followed by an expression. The expression can be either the name of a variable or a cast expression. If the expression is a cast expression, it must be enclosed in parentheses. A binary expression consists of two operands joined by a binary operator. A ternary expression consists of three operands joined by the conditional-expression operator. C includes the following unary operators: -|Symbol|Name| -|------------|----------| -|**-** **~** **!**|Negation and complement operators| -|**`*`** **`&`**|Indirection and address-of operators| -|**`sizeof`**|Size operator| -|**+**|Unary plus operator| -|**++** **--**|Unary increment and decrement operators| +| Symbol | Name | +|--|--| +| **`-`** **`~`** **`!`** | Negation and complement operators | +| **`*`** **`&`** | Indirection and address-of operators | +| **`_Alignof`** | Alignment operator (since C11) | +| **`sizeof`** | Size operator | +| **`+`** | Unary plus operator | +| **`++`** **`--`** | Unary increment and decrement operators | Binary operators associate from left to right. C provides the following binary operators: -|Symbol|Name| -|------------|----------| -|**`*`** **`/`** **`%`**|Multiplicative operators| -|**+** **-**|Additive operators| -|**\<\<** **>>**|Shift operators| -|**\<** **>** **\<=** **>=** **==** **!=**|Relational operators| -|**&** **|** **^**|Bitwise operators| -|**&&** **||**|Logical operators| -|**,**|Sequential-evaluation operator| +| Symbol | Name | +|--|--| +| **`*`** **`/`** **`%`** | Multiplicative operators | +| **`+`** **`-`** | Additive operators | +| **`<<`** **`>>`** | Shift operators | +| **`<`** **`>`** **`<=`** **`>=`** **`==`** **`!=`** | Relational operators | +| **`&`** **`|`** **`^`** | Bitwise operators | +| **`&&`** **`||`** | Logical operators | +| **`,`** | Sequential-evaluation operator | -The base operator (**:>**), supported by previous versions of the Microsoft 16-bit C compiler, is described in [C Language Syntax Summary](../c-language/c-language-syntax-summary.md). +The base operator (**`:>`**), supported by previous versions of the Microsoft 16-bit C compiler, is described in [C Language syntax summary](../c-language/c-language-syntax-summary.md). The conditional-expression operator has lower precedence than binary expressions and differs from them in being right associative. -Expressions with operators also include assignment expressions, which use unary or binary assignment operators. The unary assignment operators are the increment (**++**) and decrement (**--**) operators; the binary assignment operators are the simple-assignment operator (**=**) and the compound-assignment operators. Each compound-assignment operator is a combination of another binary operator with the simple-assignment operator. +Expressions with operators also include assignment expressions, which use unary or binary assignment operators. The unary assignment operators are the increment (**`++`**) and decrement (**`--`**) operators; the binary assignment operators are the simple-assignment operator (**`=`**) and the compound-assignment operators. Each compound-assignment operator is a combination of another binary operator with the simple-assignment operator. ## See also -- [Expressions and Assignments](../c-language/expressions-and-assignments.md) +- [Expressions and assignments](../c-language/expressions-and-assignments.md) diff --git a/docs/c-language/c-postfix-increment-and-decrement-operators.md b/docs/c-language/c-postfix-increment-and-decrement-operators.md index da10c1a8b0..a80001ce71 100644 --- a/docs/c-language/c-postfix-increment-and-decrement-operators.md +++ b/docs/c-language/c-postfix-increment-and-decrement-operators.md @@ -11,14 +11,14 @@ Operands of the postfix increment and decrement operators are scalar types that ## Syntax -*postfix-expression*:
-    *postfix-expression* **++**
-    *postfix-expression* **--** +*`postfix-expression`*:\ + *`postfix-expression`* **`++`**\ + *`postfix-expression`* **`--`** The result of the postfix increment or decrement operation is the value of the operand. After the result is obtained, the value of the operand is incremented (or decremented). The following code illustrates the postfix increment operator. -``` -if( var++ > 0 ) +```C +if ( var++ > 0 ) *p++ = *q++; ``` diff --git a/docs/c-language/c-primary-expressions.md b/docs/c-language/c-primary-expressions.md index 81a50ee115..b2939192a2 100644 --- a/docs/c-language/c-primary-expressions.md +++ b/docs/c-language/c-primary-expressions.md @@ -11,17 +11,17 @@ Primary expressions are the building blocks of more complex expressions. They ma ## Syntax *`primary-expression`*:\ -    *`identifier`*\ -    *`constant`*\ -    *`string-literal`*\ -    **(** *`expression`* **)**\ -    *`generic-selection`* + *`identifier`*\ + *`constant`*\ + *`string-literal`*\ + **`(`** *`expression`* **`)`**\ + *`generic-selection`* -*expression*:\ -    *`assignment-expression`*\ -    *`expression`***,** *`assignment-expression`* +*`expression`*:\ + *`assignment-expression`*\ + *`expression`* **`,`** *`assignment-expression`* ## See also -[Generic selection](generic-selection.md) +[Generic selection](generic-selection.md)\ [Operands and Expressions](../c-language/operands-and-expressions.md) diff --git a/docs/c-language/c-relational-and-equality-operators.md b/docs/c-language/c-relational-and-equality-operators.md index 7451821364..d0a1178103 100644 --- a/docs/c-language/c-relational-and-equality-operators.md +++ b/docs/c-language/c-relational-and-equality-operators.md @@ -7,21 +7,21 @@ ms.assetid: c89a3815-a65e-4e0d-8333-0e8dc7fdb30b --- # C Relational and Equality Operators -The binary relational and equality operators compare their first operand to their second operand to test the validity of the specified relationship. The result of a relational expression is 1 if the tested relationship is true and 0 if it is false. The type of the result is **`int`**. +The binary relational and equality operators compare their first operand to their second operand to test the validity of the specified relationship. The result of a relational expression is 1 if the tested relationship is true and 0 if it's false. The type of the result is **`int`**. -**Syntax** +## Syntax -*relational-expression*:
-    *shift-expression*
-    *relational-expression* **`<`** *shift-expression*
-    *relational-expression* **`>`** *shift-expression*
-    *relational-expression* **`<=`** *shift-expression*
-    *relational-expression* **`>=`** *shift-expression* +*`relational-expression`*:\ + *`shift-expression`*\ + *`relational-expression`* **`<`** *`shift-expression`*\ + *`relational-expression`* **`>`** *`shift-expression`*\ + *`relational-expression`* **`<=`** *`shift-expression`*\ + *`relational-expression`* **`>=`** *`shift-expression`* -*equality-expression*:
-    *relational-expression*
-    *equality-expression* **==** *relational-expression*
-    *equality-expression* **!=** *relational-expression* +*`equality-expression`*:\ + *`relational-expression`*\ + *`equality-expression`* **`==`** *`relational-expression`*\ + *`equality-expression`* **`!=`** *`relational-expression`* The relational and equality operators test the following relationships: @@ -31,24 +31,24 @@ The relational and equality operators test the following relationships: |**`>`**|First operand greater than second operand| |**`<=`**|First operand less than or equal to second operand| |**`>=`**|First operand greater than or equal to second operand| -|**==**|First operand equal to second operand| -|**!=**|First operand not equal to second operand| +|**`==`**|First operand equal to second operand| +|**`!=`**|First operand not equal to second operand| -The first four operators in the list above have a higher precedence than the equality operators (`==` and `!=`). See the precedence information in the table [Precedence and Associativity of C Operators](../c-language/precedence-and-order-of-evaluation.md). +The first four operators in the list have a higher precedence than the equality operators (**`==`** and **`!=`**). See the precedence information in the table [Precedence and Associativity of C Operators](../c-language/precedence-and-order-of-evaluation.md). The operands can have integral, floating, or pointer type. The types of the operands can be different. Relational operators perform the usual arithmetic conversions on integral and floating type operands. In addition, you can use the following combinations of operand types with the relational and equality operators: -- Both operands of any relational or equality operator can be pointers to the same type. For the equality (`==`) and inequality (`!=`) operators, the result of the comparison indicates whether the two pointers address the same memory location. For the other relational operators (**\<**, **>**, **\<**=, and **>**=), the result of the comparison indicates the relative position of the two memory addresses of the objects pointed to. Relational operators compare only offsets. +- Both operands of any relational or equality operator can be pointers to the same type. For the equality (**`==`**) and inequality (**`!=`**) operators, the result of the comparison indicates whether the two pointers address the same memory location. For the other relational operators (**`<`**, **`>`**, **`<=`**, and **`>=`**), the result of the comparison indicates the relative position of the two memory addresses of the objects pointed to. Relational operators compare only offsets. - Pointer comparison is defined only for parts of the same object. If the pointers refer to members of an array, the comparison is equivalent to comparison of the corresponding subscripts. The address of the first array element is "less than" the address of the last element. In the case of structures, pointers to structure members declared later are "greater than" pointers to members declared earlier in the structure. Pointers to the members of the same union are equal. + Pointer comparison is defined only for parts of the same object. If the pointers refer to members of an array, the comparison is equivalent to comparison of the corresponding subscripts. The address of the first array element is "less than" the address of the last element. For structures, pointers to structure members declared later are "greater than" pointers to members declared earlier in the structure. Pointers to the members of the same union are equal. -- A pointer value can be compared to the constant value 0 for equality (`==`) or inequality (`!=`). A pointer with a value of 0 is called a "null" pointer; that is, it does not point to a valid memory location. +- A pointer value can be compared to the constant value 0 for equality (**`==`**) or inequality (**`!=`**). A pointer with a value of 0 is called a "null" pointer; that is, it doesn't point to a valid memory location. -- The equality operators follow the same rules as the relational operators, but permit additional possibilities: a pointer can be compared to a constant integral expression with value 0, or to a pointer to **`void`**. If two pointers are both null pointers, they compare as equal. Equality operators compare both segment and offset. +- The equality operators follow the same rules as the relational operators, but permit more possibilities: a pointer can be compared to a constant integral expression with value 0, or to a pointer to **`void`**. If two pointers are both null pointers, they compare as equal. Equality operators compare both segment and offset. ## Examples -The examples below illustrate relational and equality operators. +These examples illustrate relational and equality operators. ```C int x = 0, y = 0; @@ -78,9 +78,9 @@ enum color { red, white, green } col; . ``` -These statements declare an enumeration variable named `col` with the tag `color`. At any time, the variable may contain an integer value of 0, 1, or 2, which represents one of the elements of the enumeration set `color`: the color red, white, or green, respectively. If `col` contains 0 when the **`if`** statement is executed, any statements depending on the **`if`** will be executed. +These statements declare an enumeration variable named `col` with the tag `color`. At any time, the variable may contain an integer value of 0, 1, or 2, which represents one of the elements of the enumeration set `color`: the color `red`, `white`, or `green`, respectively. If `col` contains 0 when the **`if`** statement is executed, any statements depending on the **`if`** will be executed. ## See also -[Relational Operators: \<, >, \<=, and >=](../cpp/relational-operators-equal-and-equal.md)
-[Equality Operators: == and !=](../cpp/equality-operators-equal-equal-and-exclpt-equal.md) +[Relational Operators: `<`, `>`, `<=`, and `>=`](../cpp/relational-operators-equal-and-equal.md)\ +[Equality Operators: `==` and `!=`](../cpp/equality-operators-equal-equal-and-exclpt-equal.md) diff --git a/docs/c-language/c-storage-classes.md b/docs/c-language/c-storage-classes.md index d558b04a56..7ad68fdbfb 100644 --- a/docs/c-language/c-storage-classes.md +++ b/docs/c-language/c-storage-classes.md @@ -9,25 +9,25 @@ ms.assetid: 893fb929-f7a9-43dc-a0b3-29cb1ef845c1 The "storage class" of a variable determines whether the item has a "global" or "local" lifetime. C calls these two lifetimes "static" and "automatic." An item with a global lifetime exists and has a value throughout the execution of the program. All functions have global lifetimes. -Automatic variables, or variables with local lifetimes, are allocated new storage each time execution control passes to the block in which they are defined. When execution returns, the variables no longer have meaningful values. +Automatic variables, or variables with local lifetimes, are allocated new storage each time execution control passes to the block in which they're defined. When execution returns, the variables no longer have meaningful values. C provides the following storage-class specifiers: ## Syntax -*storage-class-specifier*:
-    **`auto`**
-    **`register`**
-    **`static`**
-    **`extern`**
-    **`typedef`**
-    **`__declspec (`** *extended-decl-modifier-seq* **`)`** /\* Microsoft-specific \*/ +*`storage-class-specifier`*:\ + **`auto`**\ + **`register`**\ + **`static`**\ + **`extern`**\ + **`typedef`**\ + **`__declspec (`** *`extended-decl-modifier-seq`* **`)`** /\* Microsoft-specific \*/ -Except for **`__declspec`**, you can use only one *storage-class-specifier* in the *declaration-specifier* in a declaration. If no storage-class specification is made, declarations within a block create automatic objects. +Except for **`__declspec`**, you can use only one *`storage-class-specifier`* in the *`declaration-specifier`* in a declaration. If no storage-class specification is made, declarations within a block create automatic objects. Items declared with the **`auto`** or **`register`** specifier have local lifetimes. Items declared with the **`static`** or **`extern`** specifier have global lifetimes. -Since **`typedef`** and **`__declspec`** are semantically different from the other four *storage-class-specifier* terminals, they are discussed separately. For specific information on **`typedef`**, see [`typedef` Declarations](../c-language/typedef-declarations.md). For specific information on **`__declspec`**, see [Extended Storage-Class Attributes](../c-language/c-extended-storage-class-attributes.md). +Since **`typedef`** and **`__declspec`** are semantically different from the other four *`storage-class-specifier`* terminals, they're discussed separately. For specific information on **`typedef`**, see [`typedef` Declarations](../c-language/typedef-declarations.md). For specific information on **`__declspec`**, see [Extended Storage-Class Attributes](../c-language/c-extended-storage-class-attributes.md). The placement of variable and function declarations within source files also affects storage class and visibility. Declarations outside all function definitions are said to appear at the "external level." Declarations within function definitions appear at the "internal level." @@ -37,7 +37,7 @@ The exact meaning of each storage-class specifier depends on two factors: - Whether the item being declared is a variable or a function -[Storage-Class Specifiers for External-Level Declarations](../c-language/storage-class-specifiers-for-external-level-declarations.md) and [Storage-Class Specifiers for Internal-Level Declarations](../c-language/storage-class-specifiers-for-internal-level-declarations.md) describe the *storage-class-specifier* terminals in each kind of declaration and explain the default behavior when the *storage-class-specifier* is omitted from a variable. [Storage-Class Specifiers with Function Declarations](../c-language/storage-class-specifiers-with-function-declarations.md) discusses storage-class specifiers used with functions. +[Storage-Class Specifiers for External-Level Declarations](../c-language/storage-class-specifiers-for-external-level-declarations.md) and [Storage-Class Specifiers for Internal-Level Declarations](../c-language/storage-class-specifiers-for-internal-level-declarations.md) describe the *`storage-class-specifier`* terminals in each kind of declaration and explain the default behavior when the *`storage-class-specifier`* is omitted from a variable. [Storage-Class Specifiers with Function Declarations](../c-language/storage-class-specifiers-with-function-declarations.md) discusses storage-class specifiers used with functions. ## See also diff --git a/docs/c-language/c-string-literals.md b/docs/c-language/c-string-literals.md index 247e0a3707..54b5432c76 100644 --- a/docs/c-language/c-string-literals.md +++ b/docs/c-language/c-string-literals.md @@ -7,33 +7,31 @@ ms.assetid: 4b05523e-49a2-4900-b21a-754350af3328 --- # C String Literals -A "string literal" is a sequence of characters from the source character set enclosed in double quotation marks (**" "**). String literals are used to represent a sequence of characters which, taken together, form a null-terminated string. You must always prefix wide-string literals with the letter **L**. +A "string literal" is a sequence of characters from the source character set enclosed in double quotation marks (**`" "`**). String literals are used to represent a sequence of characters, which taken together form a null-terminated string. You must always prefix wide-string literals with the letter **`L`**. ## Syntax -*string-literal*:
-    **"** *s-char-sequence*opt **"**
-    **L"** *s-char-sequence*opt **"** +*`string-literal`*:\ + **`"`** *`s-char-sequence`*opt **`"`**\ + **`L"`** *`s-char-sequence`*opt **`"`** -*s-char-sequence*:
-    *s-char* +*`s-char-sequence`*:\ + *`s-char`*\ + *`s-char-sequence`* *`s-char`* -    *s-char-sequence* *s-char* - -*s-char*:
-    any member of the source character set except the double quotation mark ("), backslash (\\), or newline character - -    *escape-sequence* +*`s-char`*:\ + any member of the source character set except the double quotation mark (**`"`**), backslash (**`\`**), or newline character\ + *`escape-sequence`* ## Remarks -The example below is a simple string literal: +This example is a simple string literal: ```C char *amessage = "This is a string literal."; ``` -All escape codes listed in the [Escape Sequences](../c-language/escape-sequences.md) table are valid in string literals. To represent a double quotation mark in a string literal, use the escape sequence **\\"**. The single quotation mark (**'**) can be represented without an escape sequence. The backslash (**\\**) must be followed with a second backslash (**\\\\**) when it appears within a string. When a backslash appears at the end of a line, it is always interpreted as a line-continuation character. +All escape codes listed in the [Escape Sequences](../c-language/escape-sequences.md) table are valid in string literals. To represent a double quotation mark in a string literal, use the escape sequence **`\"`**. The single quotation mark (**`'`**) can be represented without an escape sequence. The backslash (**`\`**) must be followed with a second backslash (**`\\`**) when it appears within a string. When a backslash appears at the end of a line, it's always interpreted as a line-continuation character. ## See also diff --git a/docs/c-language/c-tokens.md b/docs/c-language/c-tokens.md index 7e39df4144..d00556d9fa 100644 --- a/docs/c-language/c-tokens.md +++ b/docs/c-language/c-tokens.md @@ -7,27 +7,22 @@ ms.assetid: 05e5f6f1-b8ea-4f74-af17-c0b9b5dbd3b5 --- # C Tokens -In a C source program, the basic element recognized by the compiler is the "token." A token is source-program text that the compiler does not break down into component elements. +In a C source program, the basic element recognized by the compiler is the "token." A token is source-program text that the compiler doesn't break down into component elements. ## Syntax -*token*: -*keyword* - -*identifier* - -*constant* - -*string-literal* - -*operator* - -*punctuator* +*`token`*:\ + *`keyword`*\ + *`identifier`*\ + *`constant`*\ + *`string-literal`*\ + *`operator`*\ + *`punctuator`* > [!NOTE] > See the introduction to [C Language Syntax Summary](../c-language/c-language-syntax-summary.md) for an explanation of the ANSI syntax conventions. -The keywords, identifiers, constants, string literals, and operators described in this section are examples of tokens. Punctuation characters such as brackets (**[ ]**), braces (**{ }**), parentheses ( **( )** ), and commas (**,**) are also tokens. +The keywords, identifiers, constants, string literals, and operators described in this section are examples of tokens. Punctuation characters such as brackets (**`[ ]`**), braces (**`{ }`**), parentheses ( **`( )`** ), and commas (**`,`**) are also tokens. ## See also diff --git a/docs/c-language/c-type-specifiers.md b/docs/c-language/c-type-specifiers.md index 0cffa4a1bd..a8ba159155 100644 --- a/docs/c-language/c-type-specifiers.md +++ b/docs/c-language/c-type-specifiers.md @@ -3,7 +3,6 @@ description: "Learn more about: C Type Specifiers" title: "C Type Specifiers" ms.date: "01/29/2018" helpviewer_keywords: ["type specifiers, C", "specifiers, type"] -ms.assetid: fbe13441-04c3-4829-b047-06d374adc2b6 --- # C Type Specifiers @@ -11,23 +10,23 @@ Type specifiers in declarations define the type of a variable or function declar ## Syntax -*type-specifier*: -    **`void`** -    **`char`** -    **`short`** -    **`int`** -    **`long`** -    **`float`** -    **`double`** -    **`signed`** -    **`unsigned`** -    *struct-or-union-specifier* -    *enum-specifier* -    *typedef-name* +*`type-specifier`*: + **`void`** + **`char`** + **`short`** + **`int`** + **`long`** + **`float`** + **`double`** + **`signed`** + **`unsigned`** + *`struct-or-union-specifier`* + *`enum-specifier`* + *`typedef-name`* -The **`signed char`**, **`signed int`**, **`signed short int`**, and **signed long int** types, together with their **`unsigned`** counterparts and **`enum`**, are called *integral* types. The **`float`**, **`double`**, and **`long double`** type specifiers are referred to as *floating* or *floating-point* types. You can use any integral or floating-point type specifier in a variable or function declaration. If a *type-specifier* is not provided in a declaration, it is taken to be **`int`**. +The **`signed char`**, **`signed int`**, **`signed short int`**, and **signed long int** types, together with their **`unsigned`** counterparts and **`enum`**, are called *integral* types. The **`float`**, **`double`**, and **`long double`** type specifiers are referred to as *floating* or *floating-point* types. You can use any integral or floating-point type specifier in a variable or function declaration. Originally, if a *`type-specifier`* wasn't provided in a declaration, it was taken to be **`int`**. The Microsoft compiler no longer accepts default **`int`** declarations. -The optional keywords **`signed`** and **`unsigned`** can precede or follow any of the integral types, except **`enum`**, and can also be used alone as type specifiers, in which case they are understood as **`signed int`** and **`unsigned int`**, respectively. When used alone, the keyword **`int`** is assumed to be **`signed`**. When used alone, the keywords **`long`** and **`short`** are understood as **long int** and **`short int`**. +The optional keywords **`signed`** and **`unsigned`** can precede or follow any of the integral types, except **`enum`**, and can also be used alone as type specifiers, in which case they're understood as **`signed int`** and **`unsigned int`**, respectively. When used alone, the keyword **`int`** is assumed to be **`signed`**. When used alone, the keywords **`long`** and **`short`** are understood as **long int** and **`short int`**. Enumeration types are considered basic types. Type specifiers for enumeration types are discussed in [Enumeration Declarations](../c-language/c-enumeration-declarations.md). @@ -35,7 +34,7 @@ The keyword **`void`** has three uses: to specify a function return type, to spe **Microsoft Specific** -Type checking is now ANSI-conforming, which means that type **`short`** and type **`int`** are distinct types. For example, this is a redefinition in the Microsoft C compiler that was accepted by previous versions of the compiler. +Type checking is now ANSI-conforming, which means that type **`short`** and type **`int`** are distinct types. For example, this sample shows a redefinition in the Microsoft C compiler that was accepted by previous versions of the compiler. ```C int myfunc(); @@ -55,19 +54,21 @@ The Microsoft C compiler also generates warnings for differences in sign. For ex ```C signed int *pi; -unsigned int *pu +unsigned int *pu; pi = pu; /* Now generates warning */ ``` -Type **`void`** expressions are evaluated for side effects. You cannot use the (nonexistent) value of an expression that has type **`void`** in any way, nor can you convert a **`void`** expression (by implicit or explicit conversion) to any type except **`void`**. If you do use an expression of any other type in a context where a **`void`** expression is required, its value is discarded. +Type **`void`** expressions are evaluated for side effects. You can't use the (nonexistent) value of an expression that has type **`void`** in any way, nor can you convert a **`void`** expression (by implicit or explicit conversion) to any type except **`void`**. If you do use an expression of any other type in a context where a **`void`** expression is required, its value is discarded. -To conform to the ANSI specification, void\*\* cannot be used as int\*\*. Only **`void`**\* can be used as a pointer to an unspecified type. +To conform to the ANSI specification, `void**` can't be used as `int**`. Only `void*` can be used as a pointer to an unspecified type. **END Microsoft Specific** -You can create additional type specifiers with **`typedef`** declarations, as described in [Typedef Declarations](../c-language/typedef-declarations.md). See [Storage of Basic Types](../c-language/storage-of-basic-types.md) for information on the size of each type. +You can create more type specifiers with **`typedef`** declarations, as described in [Typedef Declarations](../c-language/typedef-declarations.md). See [Storage of Basic Types](../c-language/storage-of-basic-types.md) for information on the size of each type. ## See also -[Declarations and Types](../c-language/declarations-and-types.md) +[Declarations and Types](../c-language/declarations-and-types.md)\ +[`typeof, __typeof__` (C23)](typeof-c.md)\ +[`typeof_unqual, __typeof_unqual__` (C23)](typeof-unqual-c.md) \ No newline at end of file diff --git a/docs/c-language/c-unary-operators.md b/docs/c-language/c-unary-operators.md index 104e0f38ae..b62c8f56fc 100644 --- a/docs/c-language/c-unary-operators.md +++ b/docs/c-language/c-unary-operators.md @@ -11,21 +11,16 @@ Unary operators appear before their operand and associate from right to left. ## Syntax -*unary-expression*: -*postfix-expression* - -**++** *unary-expression* - -`--` *unary-expression* - -*unary-operator cast-expression* - -**`sizeof`** *unary-expression* - -**sizeof (** *type-name* **)** - -*unary-operator*: one of -**& \* + -** `~` **!** +*`unary-expression`*:\ + *`postfix-expression`*\ + **`++`** *`unary-expression`*\ + **`--`** *`unary-expression`*\ + *`unary-operator`* *`cast-expression`*\ + **`sizeof`** *`unary-expression`*\ + **`sizeof (`** *`type-name`* **`)`** + +*`unary-operator`*: one of\ + **`&`** **`*`** **`+`** **`-`** **`~`** **`!`** ## See also diff --git a/docs/c-language/cast-operators.md b/docs/c-language/cast-operators.md index 57df56958f..237a207f9f 100644 --- a/docs/c-language/cast-operators.md +++ b/docs/c-language/cast-operators.md @@ -11,13 +11,12 @@ A type cast provides a method for explicit conversion of the type of an object i ## Syntax -*cast-expression*: -*unary-expression* +*`cast-expression`*:\ + *`unary-expression`*\ + **`(`** *`type-name`* **`)`** *`cast-expression`* -**(** *type-name* **)** *cast-expression* - -The compiler treats *cast-expression* as type *type-name* after a type cast has been made. Casts can be used to convert objects of any scalar type to or from any other scalar type. Explicit type casts are constrained by the same rules that determine the effects of implicit conversions, discussed in [Assignment Conversions](../c-language/assignment-conversions.md). Additional restraints on casts may result from the actual sizes or representation of specific types. See [Storage of Basic Types](../c-language/storage-of-basic-types.md) for information on actual sizes of integral types. For more information on type casts, see [Type-Cast Conversions](../c-language/type-cast-conversions.md). +The compiler treats *`cast-expression`* as type *`type-name`* after a type cast has been made. Casts can be used to convert objects of any scalar type to or from any other scalar type. Explicit type casts are constrained by the same rules that determine the effects of implicit conversions, discussed in [Assignment Conversions](../c-language/assignment-conversions.md). Additional restraints on casts may result from the actual sizes or representation of specific types. See [Storage of Basic Types](../c-language/storage-of-basic-types.md) for information on actual sizes of integral types. For more information on type casts, see [Type-Cast Conversions](../c-language/type-cast-conversions.md). ## See also -[Cast Operator: ()](../cpp/cast-operator-parens.md) +[Cast Operator: `()`](../cpp/cast-operator-parens.md) diff --git a/docs/c-language/compound-statement-c.md b/docs/c-language/compound-statement-c.md index f3c48a567a..f395a11aa1 100644 --- a/docs/c-language/compound-statement-c.md +++ b/docs/c-language/compound-statement-c.md @@ -11,24 +11,24 @@ A compound statement (also called a "block") typically appears as the body of an ## Syntax -*compound-statement*:
-    **{** *declaration-list*opt *statement-list*opt **}** +*`compound-statement`*:\ + **`{`** *`declaration-list`*opt *`statement-list`*opt **`}`** -*declaration-list*:
-    *declaration*
-    *declaration-list* *declaration* +*`declaration-list`*:\ + *`declaration`*\ + *`declaration-list`* *`declaration`* -*statement-list*:
-    *statement*
-    *statement-list* *statement* +*`statement-list`*:\ + *`statement`*\ + *`statement-list`* *`statement`* -If there are declarations, they must come before any statements. The scope of each identifier declared at the beginning of a compound statement extends from its declaration point to the end of the block. It is visible throughout the block unless a declaration of the same identifier exists in an inner block. +If there are declarations, they must come before any statements. The scope of each identifier declared at the beginning of a compound statement extends from its declaration point to the end of the block. It's visible throughout the block unless a declaration of the same identifier exists in an inner block. Identifiers in a compound statement are presumed **`auto`** unless explicitly declared otherwise with **`register`**, **`static`**, or **`extern`**, except functions, which can only be **`extern`**. You can leave off the **`extern`** specifier in function declarations and the function will still be **`extern`**. -Storage is not allocated and initialization is not permitted if a variable or function is declared in a compound statement with storage class **`extern`**. The declaration refers to an external variable or function defined elsewhere. +Storage isn't allocated and initialization isn't permitted if a variable or function is declared in a compound statement with storage class **`extern`**. The declaration refers to an external variable or function defined elsewhere. -Variables declared in a block with the **`auto`** or **`register`** keyword are reallocated and, if necessary, initialized each time the compound statement is entered. These variables are not defined after the compound statement is exited. If a variable declared inside a block has the **`static`** attribute, the variable is initialized when program execution begins and keeps its value throughout the program. See [Storage Classes](../c-language/c-storage-classes.md) for information about **`static`**. +Variables declared in a block with the **`auto`** or **`register`** keyword are reallocated and, if necessary, initialized each time the compound statement is entered. These variables are no longer defined after the compound statement is exited. If a variable declared inside a block has the **`static`** attribute, the variable is initialized when program execution begins and keeps its value throughout the program. See [Storage Classes](../c-language/c-storage-classes.md) for information about **`static`**. This example illustrates a compound statement: diff --git a/docs/c-language/conditional-expression-operator.md b/docs/c-language/conditional-expression-operator.md index e427bcfc9f..4dfba70eff 100644 --- a/docs/c-language/conditional-expression-operator.md +++ b/docs/c-language/conditional-expression-operator.md @@ -7,33 +7,33 @@ ms.assetid: c4f1a5ca-0844-44a7-a384-eca584d4e3dd --- # Conditional-Expression Operator -C has one ternary operator: the conditional-expression operator (**? :**). +C has one ternary operator: the conditional-expression operator (**`? :`**). ## Syntax -*conditional-expression*:
-    *logical-OR-expression*
-    *logical-OR expression* **?** *expression* **:** *conditional-expression* +*`conditional-expression`*:\ + *`logical-OR-expression`*\ + *`logical-OR-expression`* **`?`** *`expression`* **`:`** *`conditional-expression`* -The *logical-OR-expression* must have integral, floating, or pointer type. It is evaluated in terms of its equivalence to 0. A sequence point follows *logical-OR-expression*. Evaluation of the operands proceeds as follows: +The *`logical-OR-expression`* must have integral, floating, or pointer type. It's evaluated in terms of its equivalence to 0. A sequence point follows *`logical-OR-expression`*. Evaluation of the operands proceeds as follows: -- If *logical-OR-expression* is not equal to 0, *expression* is evaluated. The result of evaluating the expression is given by the nonterminal *expression*. (This means *expression* is evaluated only if *logical-OR-expression* is true.) +- If *`logical-OR-expression`* isn't equal to 0, *`expression`* is evaluated. The result of evaluating the expression is given by the nonterminal *`expression`*. (It means *`expression`* is evaluated only if *`logical-OR-expression`* is true.) -- If *logical-OR-expression* equals 0, *conditional-expression* is evaluated. The result of the expression is the value of *conditional-expression*. (This means *conditional-expression* is evaluated only if *logical-OR-expression* is false.) +- If *`logical-OR-expression`* equals 0, *`conditional-expression`* is evaluated. The result of the expression is the value of *`conditional-expression`*. (It means *`conditional-expression`* is evaluated only if *`logical-OR-expression`* is false.) -Note that either *expression* or *conditional-expression* is evaluated, but not both. +The effect is, either *`expression`* or *`conditional-expression`* is evaluated, but not both. -The type of the result of a conditional operation depends on the type of the *expression* or *conditional-expression* operand, as follows: +The type of the result of a conditional operation depends on the type of the *`expression`* or *`conditional-expression`* operand, as follows: -- If *expression* or *conditional-expression* has integral or floating type (their types can be different), the operator performs the usual arithmetic conversions. The type of the result is the type of the operands after conversion. +- If *`expression`* or *`conditional-expression`* has integral or floating type (their types can be different), the operator performs the usual arithmetic conversions. The type of the result is the type of the operands after conversion. -- If both *expression* and *conditional-expression* have the same structure, union, or pointer type, the type of the result is the same structure, union, or pointer type. +- If both *`expression`* and *`conditional-expression`* have the same structure, union, or pointer type, the type of the result is the same structure, union, or pointer type. - If both operands have type **`void`**, the result has type **`void`**. - If either operand is a pointer to an object of any type, and the other operand is a pointer to **`void`**, the pointer to the object is converted to a pointer to **`void`** and the result is a pointer to **`void`**. -- If either *expression* or *conditional-expression* is a pointer and the other operand is a constant expression with the value 0, the type of the result is the pointer type. +- If either *`expression`* or *`conditional-expression`* is a pointer and the other operand is a constant expression with the value 0, the type of the result is the pointer type. In the type comparison for pointers, any type qualifiers (**`const`** or **`volatile`**) in the type to which the pointer points are insignificant, but the result type inherits the qualifiers from both components of the conditional. @@ -41,13 +41,13 @@ In the type comparison for pointers, any type qualifiers (**`const`** or **`vola The following examples show uses of the conditional operator: -``` +```C j = ( i < 0 ) ? ( -i ) : ( i ); ``` This example assigns the absolute value of `i` to `j`. If `i` is less than 0, `-i` is assigned to `j`. If `i` is greater than or equal to 0, `i` is assigned to `j`. -```cpp +```C void f1( void ); void f2( void ); int x; @@ -62,4 +62,4 @@ In this example, two functions, `f1` and `f2`, and two variables, `x` and `y`, a ## See also -[Conditional Operator: ? :](../cpp/conditional-operator-q.md) +[Conditional Operator: `? :`](../cpp/conditional-operator-q.md) diff --git a/docs/c-language/continue-statement-c.md b/docs/c-language/continue-statement-c.md index 5cb99ac73d..7804883b74 100644 --- a/docs/c-language/continue-statement-c.md +++ b/docs/c-language/continue-statement-c.md @@ -11,7 +11,7 @@ The **`continue`** statement passes control to the next iteration of the nearest ## Syntax -*`jump-statement`*:
+*`jump-statement`*:\  **`continue ;`** The next iteration of a **`do`**, **`for`**, or **`while`** statement is determined as follows: diff --git a/docs/c-language/conversions-from-floating-point-types.md b/docs/c-language/conversions-from-floating-point-types.md index e837ef811b..5ab27478fa 100644 --- a/docs/c-language/conversions-from-floating-point-types.md +++ b/docs/c-language/conversions-from-floating-point-types.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Conversions from floating-point types" title: "Conversions from floating-point types" -ms.date: "10/02/2019" +ms.date: 02/07/2022 helpviewer_keywords: ["converting floating point", "floating-point conversion"] ms.assetid: 96804c8e-fa3b-4742-9006-0082ed9e57f2 --- @@ -17,13 +17,13 @@ Microsoft compilers use IEEE-754 binary32 representation for **`float`** values, When the compiler converts a **`double`** or **`long double`** floating-point number to a **`float`**, it rounds the result according to the floating-point environment controls, which default to "round to nearest, ties to even." If a numeric value is too high or too low to be represented as a numeric **`float`** value, the conversion result is positive or negative infinity according to the sign of the original value, and an overflow exception is raised, if enabled. -When converting to integer types, the result of a conversion to a type smaller than **`long`** is the result of converting the value to **`long`**, and then converting to the result type. +The result of a conversion to an integral type smaller than **`long`** is the result of converting the value to **`long`**, and then converting to the result type. For conversion to integer types at least as large as **`long`**, a conversion of a value that is too high or too low to represent in the result type may return any of the following values: - The result may be a *sentinel value*, which is the representable value farthest from zero. For signed types, it's the lowest representable value (0x800...0). For unsigned types, it's the highest representable value (0xFF...F). -- The result may be *saturated*, where values too high to represent are converted to the highest representable value, and values too low to represent are converted to the lowest representable value. One of these two values is also used as the sentinel value. +- The result may be *saturated*, where values too high to represent are converted to the highest representable value. Values too low to represent are converted to the lowest representable value. One of these two values is also used as the sentinel value. - For conversion to **`unsigned long`** or **`unsigned long long`**, the result of converting an out-of-range value may be some value other than the highest or lowest representable value. Whether the result is a sentinel or saturated value or not depends on the compiler options and target architecture. Future compiler releases may return a saturated or sentinel value instead. @@ -33,31 +33,31 @@ The following table summarizes conversions from floating types. ## Table of conversions from floating-point types -|From|To|Method| -|----------|--------|------------| -|**`float`**|**`char`**|Convert to **`long`**; convert **`long`** to **`char`**| -|**`float`**|**`short`**|Convert to **`long`**; convert **`long`** to **`short`**| -|**`float`**|**`int`**|Truncate at decimal point. If result is too large to be represented as **`int`**, result is undefined.| -|**`float`**|**`long`**|Truncate at decimal point. If result is too large to be represented as **`long`**, result is undefined.| -|**`float`**|**`long long`**|Truncate at decimal point. If result is too large to be represented as **`long long`**, result is undefined.| -|**`float`**|**`unsigned char`**|Convert to **`long`**; convert **`long`** to **`unsigned char`**| -|**`float`**|**`unsigned short`**|Convert to **`long`**; convert **`long`** to **`unsigned short`**| -|**`float`**|**`unsigned`**|Truncate at decimal point. If result is too large to be represented as **`unsigned`**, result is undefined.| -|**`float`**|**`unsigned long`**|Truncate at decimal point. If result is too large to be represented as **`unsigned long`**, result is undefined.| -|**`float`**|**`unsigned long long`**|Truncate at decimal point. If result is too large to be represented as **`unsigned long long`**, result is undefined.| -|**`float`**|**`double`**|Represent as a **`double`**.| -|**`float`**|**`long double`**|Represent as a **`long double`**.| -|**`double`**|**`char`**|Convert to **`float`**; convert **`float`** to **`char`**| -|**`double`**|**`short`**|Convert to **`float`**; convert **`float`** to **`short`**| -|**`double`**|**`int`**|Truncate at decimal point. If result is too large to be represented as **`int`**, result is undefined.| -|**`double`**|**`long`**|Truncate at decimal point. If result is too large to be represented as **`long`**, result is undefined.| -|**`double`**|**`unsigned char`**|Convert to **`long`**; convert **`long`** to **`unsigned char`**| -|**`double`**|**`unsigned short`**|Convert to **`long`**; convert **`long`** to **`unsigned short`**| -|**`double`**|**`unsigned`**|Truncate at decimal point. If result is too large to be represented as **`unsigned`**, result is undefined.| -|**`double`**|**`unsigned long`**|Truncate at decimal point. If result is too large to be represented as **`unsigned long`**, result is undefined.| -|**`double`**|**`unsigned long long`**|Truncate at decimal point. If result is too large to be represented as **`unsigned long long`**, result is undefined.| -|**`double`**|**`float`**|Represent as a **`float`**. If **`double`** value can't be represented exactly as **`float`**, loss of precision occurs. If value is too large to be represented as **`float`**, the result is undefined.| -|**`double`**|**`long double`**|The **`long double`** value is treated as **`double`**.| +| From | To | Method | +|--|--|--| +| **`float`** | **`char`** | Convert to **`long`**, then convert **`long`** to **`char`** | +| **`float`** | **`short`** | Convert to **`long`**, then convert **`long`** to **`short`** | +| **`float`** | **`int`** | Truncate at decimal point. If result is too large to be represented as **`int`**, result is undefined. | +| **`float`** | **`long`** | Truncate at decimal point. If result is too large to be represented as **`long`**, result is undefined. | +| **`float`** | **`long long`** | Truncate at decimal point. If result is too large to be represented as **`long long`**, result is undefined. | +| **`float`** | **`unsigned char`** | Convert to **`long`**, then convert **`long`** to **`unsigned char`** | +| **`float`** | **`unsigned short`** | Convert to **`long`**, then convert **`long`** to **`unsigned short`** | +| **`float`** | **`unsigned`** | Truncate at decimal point. If result is too large to be represented as **`unsigned`**, result is undefined. | +| **`float`** | **`unsigned long`** | Truncate at decimal point. If result is too large to be represented as **`unsigned long`**, result is undefined. | +| **`float`** | **`unsigned long long`** | Truncate at decimal point. If result is too large to be represented as **`unsigned long long`**, result is undefined. | +| **`float`** | **`double`** | Represent as a **`double`**. | +| **`float`** | **`long double`** | Represent as a **`long double`**. In MSVC, **`long double`** and **`double`** have the same representation. | +| **`double`** | **`char`** | Convert to **`float`**, then convert **`float`** to **`char`** | +| **`double`** | **`short`** | Convert to **`float`**, then convert **`float`** to **`short`** | +| **`double`** | **`int`** | Truncate at decimal point. If result is too large to be represented as **`int`**, result is undefined. | +| **`double`** | **`long`** | Truncate at decimal point. If result is too large to be represented as **`long`**, result is undefined. | +| **`double`** | **`unsigned char`** | Convert to **`long`**, then convert **`long`** to **`unsigned char`** | +| **`double`** | **`unsigned short`** | Convert to **`long`**, then convert **`long`** to **`unsigned short`** | +| **`double`** | **`unsigned`** | Truncate at decimal point. If result is too large to be represented as **`unsigned`**, result is undefined. | +| **`double`** | **`unsigned long`** | Truncate at decimal point. If result is too large to be represented as **`unsigned long`**, result is undefined. | +| **`double`** | **`unsigned long long`** | Truncate at decimal point. If result is too large to be represented as **`unsigned long long`**, result is undefined. | +| **`double`** | **`float`** | Represent as a **`float`**. If the **`double`** value can't be represented exactly as **`float`**, loss of precision occurs. | +| **`double`** | **`long double`** | The **`long double`** value is treated as **`double`**. | Conversions from **`long double`** follow the same method as conversions from **`double`**. diff --git a/docs/c-language/conversions-from-signed-integral-types.md b/docs/c-language/conversions-from-signed-integral-types.md index 12027dad24..607b431457 100644 --- a/docs/c-language/conversions-from-signed-integral-types.md +++ b/docs/c-language/conversions-from-signed-integral-types.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Conversions from signed integral types" title: "Conversions from signed integral types" -ms.date: "10/02/2019" +ms.date: 12/06/2022 helpviewer_keywords: ["integral conversions, from signed", "integers, converting", "conversions [C++], integral", "data type conversion [C++], signed and unsigned integers", "type conversion [C++], signed and unsigned integers"] ms.assetid: 5eea32f8-8b14-413d-acac-c063b3d118d7 --- # Conversions from signed integral types -When a signed integer is converted to an integer or a floating-point type, if the original value is representable in the result type, the value is unchanged. +When a signed integer is converted to an integer or a floating-point type, the value is unchanged if it's representable in the result type. When a signed integer is converted to an integer of greater size, the value is sign-extended. When converted to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example: @@ -19,7 +19,7 @@ u = i; printf_s( "%hu\n", u ); // Prints 65533 ``` -When converting a signed integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. +When the compiler converts a signed integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. For information about the sizes of integral and floating-point types, see [Storage of basic types](../c-language/storage-of-basic-types.md). @@ -33,48 +33,48 @@ In the Microsoft compiler, **`int`** and **`long`** are distinct but equivalent ## Table of conversions from signed integral types -|From|To|Method| -|----------|--------|------------| -|**`char`**1|**`short`**|Sign-extend| -|**`char`**|**`long`**|Sign-extend| -|**`char`**|**`long long`**|Sign-extend| -|**`char`**|**`unsigned char`**|Preserve pattern; high-order bit loses function as sign bit| -|**`char`**|**`unsigned short`**|Sign-extend to **`short`**; convert **`short`** to **`unsigned short`**| -|**`char`**|**`unsigned long`**|Sign-extend to **`long`**; convert **`long`** to **`unsigned long`**| -|**`char`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`char`**|**`float`**|Sign-extend to **`long`**; convert **`long`** to **`float`**| -|**`char`**|**`double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`char`**|**`long double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`short`**|**`char`**|Preserve low-order byte| -|**`short`**|**`long`**|Sign-extend| -|**`short`**|**`long long`**|Sign-extend| -|**`short`**|**`unsigned char`**|Preserve low-order byte| -|**`short`**|**`unsigned short`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`short`**|**`unsigned long`**|Sign-extend to **`long`**; convert **`long`** to **`unsigned long`**| -|**`short`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`short`**|**`float`**|Sign-extend to **`long`**; convert **`long`** to **`float`**| -|**`short`**|**`double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`short`**|**`long double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`long`**|**`char`**|Preserve low-order byte| -|**`long`**|**`short`**|Preserve low-order word| -|**`long`**|**`long long`**|Sign-extend| -|**`long`**|**`unsigned char`**|Preserve low-order byte| -|**`long`**|**`unsigned short`**|Preserve low-order word| -|**`long`**|**`unsigned long`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`long`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`long`**|**`float`**|Represent as **`float`**. If **`long`** can't be represented exactly, some precision is lost.| -|**`long`**|**`double`**|Represent as **`double`**. If **`long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long`**|**`long double`**|Represent as **`double`**. If **`long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long long`**|**`char`**|Preserve low-order byte| -|**`long long`**|**`short`**|Preserve low-order word| -|**`long long`**|**`long`**|Preserve low-order dword| -|**`long long`**|**`unsigned char`**|Preserve low-order byte| -|**`long long`**|**`unsigned short`**|Preserve low-order word| -|**`long long`**|**`unsigned long`**|Preserve low-order dword| -|**`long long`**|**`unsigned long long`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`long long`**|**`float`**|Represent as **`float`**. If **`long long`** can't be represented exactly, some precision is lost.| -|**`long long`**|**`double`**|Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long long`**|**`long double`**|Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost.| +| From | To | Method | +|---|---|---| +| **`char`**1 | **`short`** | Sign-extend | +| **`char`** | **`long`** | Sign-extend | +| **`char`** | **`long long`** | Sign-extend | +| **`char`** | **`unsigned char`** | Preserve pattern; high-order bit loses function as sign bit | +| **`char`** | **`unsigned short`** | Sign-extend to **`short`**; convert **`short`** to **`unsigned short`** | +| **`char`** | **`unsigned long`** | Sign-extend to **`long`**; convert **`long`** to **`unsigned long`** | +| **`char`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`char`** | **`float`** | Represent exactly as **`float`** | +| **`char`** | **`double`** | Represent exactly as **`double`** | +| **`char`** | **`long double`** | Represent exactly as **`long double`** | +| **`short`** | **`char`** | Preserve low-order byte | +| **`short`** | **`long`** | Sign-extend | +| **`short`** | **`long long`** | Sign-extend | +| **`short`** | **`unsigned char`** | Preserve low-order byte | +| **`short`** | **`unsigned short`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`short`** | **`unsigned long`** | Sign-extend to **`long`**; convert **`long`** to **`unsigned long`** | +| **`short`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`short`** | **`float`** | Represent exactly as **`float`** | +| **`short`** | **`double`** | Represent exactly as **`double`** | +| **`short`** | **`long double`** | Represent exactly as **`long double`** | +| **`long`** | **`char`** | Preserve low-order byte | +| **`long`** | **`short`** | Preserve low-order word | +| **`long`** | **`long long`** | Sign-extend | +| **`long`** | **`unsigned char`** | Preserve low-order byte | +| **`long`** | **`unsigned short`** | Preserve low-order word | +| **`long`** | **`unsigned long`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`long`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`long`** | **`float`** | Represent as **`float`**. If **`long`** can't be represented exactly, some precision is lost. | +| **`long`** | **`double`** | Represent exactly as **`double`** | +| **`long`** | **`long double`** | Represent exactly as **`long double`** | +| **`long long`** | **`char`** | Preserve low-order byte | +| **`long long`** | **`short`** | Preserve low-order word | +| **`long long`** | **`long`** | Preserve low-order dword | +| **`long long`** | **`unsigned char`** | Preserve low-order byte | +| **`long long`** | **`unsigned short`** | Preserve low-order word | +| **`long long`** | **`unsigned long`** | Preserve low-order dword | +| **`long long`** | **`unsigned long long`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`long long`** | **`float`** | Represent as **`float`**. If **`long long`** can't be represented exactly, some precision is lost. | +| **`long long`** | **`double`** | Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost. | +| **`long long`** | **`long double`** | Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost. | 1 All **`char`** entries assume that the **`char`** type is signed by default. diff --git a/docs/c-language/conversions-from-unsigned-integral-types.md b/docs/c-language/conversions-from-unsigned-integral-types.md index df5f8de764..4330ab6851 100644 --- a/docs/c-language/conversions-from-unsigned-integral-types.md +++ b/docs/c-language/conversions-from-unsigned-integral-types.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Conversions from unsigned integral types" title: "Conversions from unsigned integral types" -ms.date: "10/02/2019" +ms.date: 12/06/2022 helpviewer_keywords: ["integers, converting", "type casts, involving integers", "data type conversion [C++], signed and unsigned integers", "type conversion [C++], signed and unsigned integers", "integral conversions, from unsigned"] ms.assetid: 60fb7e10-bff9-4a13-8a48-e19f25a36a02 --- @@ -9,7 +9,7 @@ ms.assetid: 60fb7e10-bff9-4a13-8a48-e19f25a36a02 When an unsigned integer is converted to an integer or floating-point type, if the original value is representable in the result type the value is unchanged. -When converting an unsigned integer to an integer of greater size, the value is zero-extended. When converting to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example. +When the compiler converts an unsigned integer to an integer of greater size, the value is zero-extended. When converted to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example: ```C unsigned k = 65533; @@ -19,7 +19,7 @@ j = k; printf_s( "%hd\n", j ); // Prints -3 ``` -When converting an unsigned integer to a floating-point type, if the original value can't be represented exactly in the result type, the result is the next higher or lower representable value. +When the compiler converts an unsigned integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. See [Storage of basic types](../c-language/storage-of-basic-types.md) for information about the sizes of integral and floating-point types. @@ -33,48 +33,48 @@ The following table summarizes conversions from unsigned integral types. ## Table of conversions from unsigned integral types -|From|To|Method| -|----------|--------|------------| -|**`unsigned char`**|**`char`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned char`**|**`short`**|Zero-extend| -|**`unsigned char`**|**`long`**|Zero-extend| -|**`unsigned char`**|**`long long`**|Zero-extend| -|**`unsigned char`**|**`unsigned short`**|Zero-extend| -|**`unsigned char`**|**`unsigned long`**|Zero-extend| -|**`unsigned char`**|**`unsigned long long`**|Zero-extend| -|**`unsigned char`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned char`**|**`double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned char`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned short`**|**`char`**|Preserve low-order byte| -|**`unsigned short`**|**`short`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned short`**|**`long`**|Zero-extend| -|**`unsigned short`**|**`long long`**|Zero-extend| -|**`unsigned short`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned short`**|**`unsigned long`**|Zero-extend| -|**`unsigned short`**|**`unsigned long long`**|Zero-extend| -|**`unsigned short`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned short`**|**`double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned short`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned long`**|**`char`**|Preserve low-order byte| -|**`unsigned long`**|**`short`**|Preserve low-order word| -|**`unsigned long`**|**`long`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned long`**|**`long long`**|Zero-extend| -|**`unsigned long`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned long`**|**`unsigned short`**|Preserve low-order word| -|**`unsigned long`**|**`unsigned long long`**|Zero-extend| -|**`unsigned long`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned long`**|**`double`**|Convert directly to **`double`**| -|**`unsigned long`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned long long`**|**`char`**|Preserve low-order byte| -|**`unsigned long long`**|**`short`**|Preserve low-order word| -|**`unsigned long long`**|**`long`**|Preserve low-order dword| -|**`unsigned long long`**|**`long long`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned long long`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned long long`**|**`unsigned short`**|Preserve low-order word| -|**`unsigned long long`**|**`unsigned long`**|Preserve low-order dword| -|**`unsigned long long`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned long long`**|**`double`**|Convert directly to **`double`**| -|**`unsigned long long`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| +| From | To | Method | +|---|---|---| +| **`unsigned char`** | **`char`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned char`** | **`short`** | Zero-extend | +| **`unsigned char`** | **`long`** | Zero-extend | +| **`unsigned char`** | **`long long`** | Zero-extend | +| **`unsigned char`** | **`unsigned short`** | Zero-extend | +| **`unsigned char`** | **`unsigned long`** | Zero-extend | +| **`unsigned char`** | **`unsigned long long`** | Zero-extend | +| **`unsigned char`** | **`float`** | Convert exactly to **`float`** | +| **`unsigned char`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned char`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned short`** | **`char`** | Preserve low-order byte | +| **`unsigned short`** | **`short`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned short`** | **`long`** | Zero-extend | +| **`unsigned short`** | **`long long`** | Zero-extend | +| **`unsigned short`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned short`** | **`unsigned long`** | Zero-extend | +| **`unsigned short`** | **`unsigned long long`** | Zero-extend | +| **`unsigned short`** | **`float`** | Convert exactly to **`float`** | +| **`unsigned short`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned short`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned long`** | **`char`** | Preserve low-order byte | +| **`unsigned long`** | **`short`** | Preserve low-order word | +| **`unsigned long`** | **`long`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned long`** | **`long long`** | Zero-extend | +| **`unsigned long`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned long`** | **`unsigned short`** | Preserve low-order word | +| **`unsigned long`** | **`unsigned long long`** | Zero-extend | +| **`unsigned long`** | **`float`** | Convert to nearest representable **`float`** | +| **`unsigned long`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned long`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned long long`** | **`char`** | Preserve low-order byte | +| **`unsigned long long`** | **`short`** | Preserve low-order word | +| **`unsigned long long`** | **`long`** | Preserve low-order dword | +| **`unsigned long long`** | **`long long`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned long long`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned long long`** | **`unsigned short`** | Preserve low-order word | +| **`unsigned long long`** | **`unsigned long`** | Preserve low-order dword | +| **`unsigned long long`** | **`float`** | Convert to nearest representable **`float`** | +| **`unsigned long long`** | **`double`** | Convert to nearest representable **`double`** | +| **`unsigned long long`** | **`long double`** | Convert to nearest representable **`long double`** | ## See also diff --git a/docs/c-language/conversions-to-and-from-pointer-types.md b/docs/c-language/conversions-to-and-from-pointer-types.md index 6980b48742..f14c6a2fb7 100644 --- a/docs/c-language/conversions-to-and-from-pointer-types.md +++ b/docs/c-language/conversions-to-and-from-pointer-types.md @@ -11,11 +11,11 @@ A pointer to one type of value can be converted to a pointer to a different type A pointer to **`void`** can be converted to or from a pointer to any type, without restriction or loss of information. If the result is converted back to the original type, the original pointer is recovered. -If a pointer is converted to another pointer with the same type but having different or additional qualifiers, the new pointer is the same as the old except for restrictions imposed by the new qualifier. +If a pointer is converted to another pointer with the same type but having different or extra qualifiers, the new pointer is the same as the old except for restrictions imposed by the new qualifier. A pointer value can also be converted to an integral value. The conversion path depends on the size of the pointer and the size of the integral type, according to the following rules: -- If the size of the pointer is greater than or equal to the size of the integral type, the pointer behaves like an unsigned value in the conversion, except that it cannot be converted to a floating value. +- If the size of the pointer is greater than or equal to the size of the integral type, the pointer behaves like an unsigned value in the conversion, except that it can't be converted to a floating value. - If the pointer is smaller than the integral type, the pointer is first converted to a pointer with the same size as the integral type, then converted to the integral type. @@ -23,9 +23,9 @@ Conversely, an integral type can be converted to a pointer type according to the - If the integral type is the same size as the pointer type, the conversion simply causes the integral value to be treated as a pointer (an unsigned integer). -- If the size of the integral type is different from the size of the pointer type, the integral type is first converted to the size of the pointer, using the conversion paths given in the tables [Conversion from Signed Integral Types](../c-language/conversions-from-signed-integral-types.md) and [Conversion from Unsigned Integral Types](../c-language/conversions-from-unsigned-integral-types.md). It is then treated as a pointer value. +- If the size of the integral type is different from the size of the pointer type, the integral type is first converted to the size of the pointer, using the conversion paths given in the tables [Conversion from Signed Integral Types](../c-language/conversions-from-signed-integral-types.md) and [Conversion from Unsigned Integral Types](../c-language/conversions-from-unsigned-integral-types.md). It's then treated as a pointer value. -An integral constant expression with value 0 or such an expression cast to type **`void`** \* can be converted by a type cast, by assignment, or by comparison to a pointer of any type. This produces a null pointer that is equal to another null pointer of the same type, but this null pointer is not equal to any pointer to a function or to an object. Integers other than the constant 0 can be converted to pointer type, but the result is not portable. +An integral constant expression with value 0 or such an expression cast to type `void*` can be converted by a type cast, by assignment, or by comparison to a pointer of any type. This operation produces a null pointer that's equal to another null pointer of the same type, but it isn't equal to any pointer to a function or to an object. Integers other than the constant 0 can be converted to pointer type, but the result isn't portable. ## See also diff --git a/docs/c-language/cpp-integer-limits.md b/docs/c-language/cpp-integer-limits.md index 82ebf2660e..c860fb2336 100644 --- a/docs/c-language/cpp-integer-limits.md +++ b/docs/c-language/cpp-integer-limits.md @@ -23,7 +23,7 @@ Microsoft C also permits the declaration of sized integer variables, which are i |**UCHAR_MAX**|Maximum value for a variable of type **`unsigned char`**.|255 (0xff)| |**CHAR_MIN**|Minimum value for a variable of type **`char`**.|-128; 0 if /J option used| |**CHAR_MAX**|Maximum value for a variable of type **`char`**.|127; 255 if /J option used| -|**MB_LEN_MAX**|Maximum number of bytes in a multicharacter constant.|5| +|**MB_LEN_MAX**|Maximum number of bytes in a multibyte character.|5| |**SHRT_MIN**|Minimum value for a variable of type **`short`**.|-32768| |**SHRT_MAX**|Maximum value for a variable of type **`short`**.|32767| |**USHRT_MAX**|Maximum value for a variable of type **`unsigned short`**.|65535 (0xffff)| diff --git a/docs/c-language/declarators-and-variable-declarations.md b/docs/c-language/declarators-and-variable-declarations.md index c6c50541cd..d8c27aab0a 100644 --- a/docs/c-language/declarators-and-variable-declarations.md +++ b/docs/c-language/declarators-and-variable-declarations.md @@ -35,22 +35,22 @@ You use declarators to declare arrays of values, pointers to values, and functio ## Syntax -*`declarator`*:
+*`declarator`*:\  *`pointer`*opt *`direct-declarator`* -*`direct-declarator`*:
- *`identifier`*
- **`(`** *`declarator`* **`)`**
- *`direct-declarator`* **`[`** *`constant-expression`*opt **`]`**
- *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`**
+*`direct-declarator`*:\ + *`identifier`*\ + **`(`** *`declarator`* **`)`**\ + *`direct-declarator`* **`[`** *`constant-expression`*opt **`]`**\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`**\  *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** -*`pointer`*:
- **`*`** *`type-qualifier-list`*opt
+*`pointer`*:\ + **`*`** *`type-qualifier-list`*opt\  **`*`** *`type-qualifier-list`*opt *`pointer`* -*`type-qualifier-list`*:
- *`type-qualifier`*
+*`type-qualifier-list`*:\ + *`type-qualifier`*\  *`type-qualifier-list`* *`type-qualifier`* > [!NOTE] @@ -67,7 +67,7 @@ int list[20]; // Declares an array of 20 int values named list char *cp; // Declares a pointer to a char value double func( void ); // Declares a function named func, with no // arguments, that returns a double value -int *aptr[10] // Declares an array of 10 pointers +int *aptr[10]; // Declares an array of 10 pointers ``` **Microsoft Specific** diff --git a/docs/c-language/definitions-and-conventions.md b/docs/c-language/definitions-and-conventions.md index 47dc3a7f24..672aee2222 100644 --- a/docs/c-language/definitions-and-conventions.md +++ b/docs/c-language/definitions-and-conventions.md @@ -1,11 +1,11 @@ --- description: "Learn more about: Definitions and Conventions" title: "Definitions and Conventions" -ms.date: "11/04/2016" +ms.date: 01/23/2023 helpviewer_keywords: ["nonterminals definition"] ms.assetid: f9b3cf5f-6a7c-4a10-9b18-9d4a43efdaeb --- -# Definitions and Conventions +# Definitions and conventions Terminals are endpoints in a syntax definition. No other resolution is possible. Terminals include the set of reserved words and user-defined identifiers. @@ -13,20 +13,20 @@ Nonterminals are placeholders in the syntax and are defined elsewhere in this sy An optional component is indicated by the subscripted opt. For example, -> **{** *expression*opt **}** +> **`{`** *`expression`*opt **`}`** indicates an optional expression enclosed in braces. The syntax conventions use different font attributes for different components of the syntax. The symbols and fonts are as follows: -|Attribute|Description| -|---------------|-----------------| -|*nonterminal*|Italic type indicates nonterminals.| -|**`const`**|Terminals in bold type are literal reserved words and symbols that must be entered as shown. Characters in this context are always case sensitive.| -|opt|Nonterminals followed by opt are always optional.| -|default typeface|Characters in the set described or listed in this typeface can be used as terminals in C statements.| +| Attribute | Description | +|---|---| +| *`nonterminal`* | Italic type indicates nonterminals. | +| **`const`** | Terminals in bold monospace type are literal reserved words and symbols that must be entered as shown. Characters in this context are always case sensitive. | +| opt | Nonterminals followed by opt are always optional. | +| default typeface | Characters in the set described or listed in this typeface can be used as terminals in C statements. | -A colon (**:**) following a nonterminal introduces its definition. Alternative definitions are listed on separate lines, except when prefaced with the words "one of." +A colon (**`:`**) following a nonterminal introduces its definition. Alternative definitions are listed on separate lines, except when prefaced with the words "one of." ## See also diff --git a/docs/c-language/demotion-of-integers.md b/docs/c-language/demotion-of-integers.md index f64f4104f9..5cc14b1695 100644 --- a/docs/c-language/demotion-of-integers.md +++ b/docs/c-language/demotion-of-integers.md @@ -25,7 +25,7 @@ char y = (char)0x1234; assigns the value 0x34 to `y`. -When **`signed`** variables are converted to **`unsigned`** and vice-versa, the bit patterns remain the same. For example, casting -2 (0xFE) to an **`unsigned`** value yields 254 (also 0xFE). +When **`signed`** variables are converted to **`unsigned`** and vice-versa, the bit patterns remain the same. For example, casting -2 (0xFFFFFFFE) to an **`unsigned int`** value yields 4294967294 (also 0xFFFFFFFE). ## See also diff --git a/docs/c-language/do-while-statement-c.md b/docs/c-language/do-while-statement-c.md index ca9fac1f5a..96fcb62925 100644 --- a/docs/c-language/do-while-statement-c.md +++ b/docs/c-language/do-while-statement-c.md @@ -6,26 +6,26 @@ f1_keywords: ["do"] helpviewer_keywords: ["do-while keyword [C]"] ms.assetid: f2ac20a6-10c7-4a08-b5e3-c3b3639dbeaf --- -# do-while Statement (C) +# `do-while` Statement (C) -The *do-while* statement lets you repeat a statement or compound statement until a specified expression becomes false. +The *`do-while`* statement lets you repeat a statement or compound statement until a specified expression becomes false. ## Syntax -*iteration-statement*: -    **`do`** *statement* **while (** *expression* **) ;** +*`iteration-statement`*: + **`do`** *`statement`* **`while (`** *`expression`* **`) ;`** -The *expression* in a *do-while* statement is evaluated after the body of the loop is executed. Therefore, the body of the loop is always executed at least once. +The *`expression`* in a *`do-while`* statement is evaluated after the body of the loop is executed. Therefore, the body of the loop is always executed at least once. -The *expression* must have arithmetic or pointer type. Execution proceeds as follows: +The *`expression`* must have arithmetic or pointer type. Execution proceeds as follows: 1. The statement body is executed. -1. Next, *expression* is evaluated. If *expression* is false, the *do-while* statement terminates and control passes to the next statement in the program. If *expression* is true (nonzero), the process is repeated, beginning with step 1. +1. Next, *`expression`* is evaluated. If *`expression`* is false, the *`do-while`* statement terminates and control passes to the next statement in the program. If *`expression`* is true (nonzero), the process is repeated, beginning with step 1. -The *do-while* statement can also terminate when a **`break`**, **`goto`**, or **`return`** statement is executed within the statement body. +The *`do-while`* statement can also terminate when a **`break`**, **`goto`**, or **`return`** statement is executed within the statement body. -This is an example of the *do-while* statement: +Here's an example of the *`do-while`* statement: ```C do @@ -35,8 +35,8 @@ do } while ( x > 0 ); ``` -In this *do-while* statement, the two statements `y = f( x );` and `x--;` are executed, regardless of the initial value of `x`. Then `x > 0` is evaluated. If `x` is greater than 0, the statement body is executed again and `x > 0` is reevaluated. The statement body is executed repeatedly as long as `x` remains greater than 0. Execution of the *do-while* statement terminates when `x` becomes 0 or negative. The body of the loop is executed at least once. +In this *`do-while`* statement, the two statements `y = f( x );` and `x--;` are executed, regardless of the initial value of `x`. Then `x > 0` is evaluated. If `x` is greater than 0, the statement body is executed again, and `x > 0` is reevaluated. The statement body is executed repeatedly as long as `x` remains greater than 0. Execution of the *`do-while`* statement terminates when `x` becomes 0 or negative. The body of the loop is executed at least once. ## See also -[do-while Statement (C++)](../cpp/do-while-statement-cpp.md) +[`do-while` Statement (C++)](../cpp/do-while-statement-cpp.md) diff --git a/docs/c-language/elements-of-c.md b/docs/c-language/elements-of-c.md index e32b34331d..eee10f7ed6 100644 --- a/docs/c-language/elements-of-c.md +++ b/docs/c-language/elements-of-c.md @@ -29,7 +29,7 @@ The following topics are discussed: The section also includes reference tables for [Trigraphs](../c-language/trigraphs.md), [Limits on Floating-Point Constants](../c-language/limits-on-floating-point-constants.md), [C and C++ Integer Limits](../c-language/cpp-integer-limits.md), and [Escape Sequences](../c-language/escape-sequences.md). -Operators are symbols (both single characters and character combinations) that specify how values are to be manipulated. Each symbol is interpreted as a single unit, called a token. For more information, see [Operators](../c-language/c-operators.md). +Operators (as both single characters and character combinations) are symbols that specify how values are to be manipulated. Each symbol is interpreted as a single unit, called a token. For more information, see [Operators](../c-language/c-operators.md). ## See also diff --git a/docs/c-language/escape-sequences.md b/docs/c-language/escape-sequences.md index 3b4b7b76a7..e1d271617f 100644 --- a/docs/c-language/escape-sequences.md +++ b/docs/c-language/escape-sequences.md @@ -34,7 +34,7 @@ Note that the question mark preceded by a backslash (**\\?**) specifies a litera **Microsoft Specific** -If a backslash precedes a character that does not appear in the table, the compiler handles the undefined character as the character itself. For example, `\c` is treated as an `c`. +If a backslash precedes a character that does not appear in the table, the compiler handles the undefined character as the character itself. For example, `\c` is treated as a `c`. **END Microsoft Specific** diff --git a/docs/c-language/expression-statement-c.md b/docs/c-language/expression-statement-c.md index 0ab152e397..36c21bc202 100644 --- a/docs/c-language/expression-statement-c.md +++ b/docs/c-language/expression-statement-c.md @@ -11,10 +11,10 @@ When an expression statement is executed, the expression is evaluated according ## Syntax -*expression-statement*:
-    *expression*opt **;** +*`expression-statement`*:\ + *`expression`*opt **`;`** -All side effects from the expression evaluation are completed before the next statement is executed. An empty expression statement is called a null statement. See [The Null Statement](../c-language/null-statement-c.md) for more information. +All side effects from the expression evaluation are completed before the next statement is executed. An empty expression statement is called a null statement. For more information, see [The Null Statement](../c-language/null-statement-c.md). These examples demonstrate expression statements. diff --git a/docs/c-language/extern-storage-class-specifier.md b/docs/c-language/extern-storage-class-specifier.md index 749c6227ae..fc53268609 100644 --- a/docs/c-language/extern-storage-class-specifier.md +++ b/docs/c-language/extern-storage-class-specifier.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: extern Storage-Class Specifier" title: "extern Storage-Class Specifier" +description: "Learn more about: extern Storage-Class Specifier" ms.date: "07/10/2018" helpviewer_keywords: ["extern keyword [C]", "storage class specifiers, extern", "extern keyword [C], storage class specifier", "external linkage, storage-class specifiers", "external linkage, extern modifier"] -ms.assetid: 6e16d927-291f-49e4-986c-9d91a482a441 --- # extern Storage-Class Specifier @@ -14,12 +13,11 @@ A variable declared with the **`extern`** storage-class specifier is a reference This example illustrates internal- and external-level declarations: ```c - // Source1.c int i = 1; -// Source2. c +// Source2.c #include @@ -49,7 +47,7 @@ void func(void) } ``` -In this example, the variable `i` is defined in Source1.c with an initial value of 1. An **`extern`** declaration in Source2.c is makes 'i' visible in that file. +In this example, the variable `i` is defined in Source1.c with an initial value of 1. An **`extern`** declaration in Source2.c makes 'i' visible in that file. In the `func` function, the address of the global variable `i` is used to initialize the **`static`** pointer variable `external_i`. This works because the global variable has **`static`** lifetime, meaning its address does not change during program execution. Next, a variable `i` is defined within the scope of `func` as a local variable with initial value 16. This definition does not affect the value of the external-level `i`, which is hidden by the use of its name for the local variable. The value of the global `i` is now accessible only through the pointer `external_i`. diff --git a/docs/c-language/external-definitions.md b/docs/c-language/external-definitions.md index aeab60394f..59f3272830 100644 --- a/docs/c-language/external-definitions.md +++ b/docs/c-language/external-definitions.md @@ -7,16 +7,16 @@ ms.assetid: 41e37bfc-b360-43b1-9972-28af2d365b20 --- # External Definitions -*translation-unit*:
-    *external-declaration*
-    *translation-unit* *external-declaration* +*`translation-unit`*:\ + *`external-declaration`* \ + *`translation-unit`* *`external-declaration`* -*external-declaration*: /\* Allowed only at external (file) scope \*/
-    *function-definition*
-    *declaration* +*`external-declaration`*: /\* Allowed only at external (file) scope \*/\ + *`function-definition`*\ + *`declaration`* -*function-definition*: /\* Declarator here is the function declarator \*/
-    *declaration-specifiers*opt *declarator* *declaration-list*opt *compound-statement* +*`function-definition`*: /\* This declarator is the function declarator \*/\ + *`declaration-specifiers`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* ## See also diff --git a/docs/c-language/for-statement-c.md b/docs/c-language/for-statement-c.md index 67579fbef5..c92740feda 100644 --- a/docs/c-language/for-statement-c.md +++ b/docs/c-language/for-statement-c.md @@ -5,34 +5,34 @@ ms.date: "11/04/2016" helpviewer_keywords: ["for keyword [C]"] ms.assetid: 560a8de4-19db-4868-9f18-dbe51b17900d --- -# for Statement (C) +# `for` Statement (C) The **`for`** statement lets you repeat a statement or compound statement a specified number of times. The body of a **`for`** statement is executed zero or more times until an optional condition becomes false. You can use optional expressions within the **`for`** statement to initialize and change values during the **`for`** statement's execution. ## Syntax -*iteration-statement*:
-    **`for`** **(** *init-expression*opt **;** *cond-expression*opt **;** *loop-expression*opt **)** *statement* +*`iteration-statement`*:\ + **`for`** **`(`** *`init-expression`*opt **`;`** *`cond-expression`*opt **`;`** *`loop-expression`*opt **`)`** *`statement`* Execution of a **`for`** statement proceeds as follows: -1. The *init-expression*, if any, is evaluated. This specifies the initialization for the loop. There is no restriction on the type of *init-expression*. +1. The *`init-expression`*, if any, is evaluated. It specifies the initialization for the loop. There's no restriction on the type of *`init-expression`*. -1. The *cond-expression*, if any, is evaluated. This expression must have arithmetic or pointer type. It is evaluated before each iteration. Three results are possible: +1. The *`cond-expression`*, if any, is evaluated. This expression must have arithmetic or pointer type. It's evaluated before each iteration. Three results are possible: - - If *cond-expression* is **`true`** (nonzero), *statement* is executed; then *loop-expression*, if any, is evaluated. The *loop-expression* is evaluated after each iteration. There is no restriction on its type. Side effects will execute in order. The process then begins again with the evaluation of *cond-expression*. + - If *`cond-expression`* is **`true`** (nonzero), *`statement`* is executed; then *`loop-expression`*, if any, is evaluated. The *`loop-expression`* is evaluated after each iteration. There's no restriction on its type. Side effects will execute in order. The process then begins again with the evaluation of *`cond-expression`*. - - If *cond-expression* is omitted, *cond-expression* is considered true, and execution proceeds exactly as described in the previous paragraph. A **`for`** statement without a *cond-expression* argument terminates only when a **`break`** or **`return`** statement within the statement body is executed, or when a **`goto`** (to a labeled statement outside the **`for`** statement body) is executed. + - If *`cond-expression`* is omitted, *`cond-expression`* is considered true, and execution proceeds exactly as described in the previous paragraph. A **`for`** statement without a *`cond-expression`* argument terminates only when a **`break`** or **`return`** statement within the statement body is executed, or when a **`goto`** (to a labeled statement outside the **`for`** statement body) is executed. - - If *cond-expression* is **`false`** (0), execution of the **`for`** statement terminates and control passes to the next statement in the program. + - If *`cond-expression`* is **`false`** (0), execution of the **`for`** statement terminates and control passes to the next statement in the program. -A **`for`** statement also terminates when a **`break`**, **`goto`**, or **`return`** statement within the statement body is executed. A **`continue`** statement in a **`for`** loop causes *loop-expression* to be evaluated. When a **`break`** statement is executed inside a **`for`** loop, *loop-expression* is not evaluated or executed. This statement +A **`for`** statement also terminates when a **`break`**, **`goto`**, or **`return`** statement within the statement body is executed. A **`continue`** statement in a **`for`** loop causes *`loop-expression`* to be evaluated. When a **`break`** statement is executed inside a **`for`** loop, *`loop-expression`* isn't evaluated or executed. This statement ```C for( ; ; ) ``` -is the customary way to produce an infinite loop which can only be exited with a **`break`**, **`goto`**, or **`return`** statement. +is the customary way to produce an infinite loop, which can only be exited with a **`break`**, **`goto`**, or **`return`** statement. ## Example diff --git a/docs/c-language/function-body.md b/docs/c-language/function-body.md index aae08b367c..352ae7c97e 100644 --- a/docs/c-language/function-body.md +++ b/docs/c-language/function-body.md @@ -11,17 +11,17 @@ A *function body* is a compound statement containing the statements that specify ## Syntax -*function-definition*:
-    *declaration-specifiers*opt *attribute-seq*opt *declarator* *declaration-list*opt *compound-statement* +*`function-definition`*:\ + *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* -/\* *attribute-seq* is Microsoft-specific \*/ +/\* *`attribute-seq`* is Microsoft-specific \*/ -*compound-statement*: /\* The function body \*/
-    **{** *declaration-list*opt *statement-list*opt **}** +*`compound-statement`*: /\* The function body \*/\ + **`{`** *`declaration-list`*opt *`statement-list`*opt **`}`** -Variables declared in a function body, known as *local variables*, have **`auto`** storage class unless otherwise specified. When the function is called, storage is created for the local variables and local initializations are performed. Execution control passes to the first statement in *compound-statement* and continues until a **`return`** statement is executed or the end of the function body is encountered. Control then returns to the point at which the function was called. +Variables declared in a function body, known as *local variables*, have **`auto`** storage class unless otherwise specified. When the function is called, storage is created for the local variables, and local initializations are performed. Execution control passes to the first statement in *`compound-statement`* and continues until a **`return`** statement is executed or the end of the function body is encountered. Control then returns to the point at which the function was called. -A **`return`** statement containing an expression must be executed if the function is to return a value. The return value of a function is undefined if no **`return`** statement is executed or if the **`return`** statement does not include an expression. +A **`return`** statement containing an expression must be executed if the function is to return a value. The return value of a function is undefined if no **`return`** statement is executed or if the **`return`** statement doesn't include an expression. ## See also diff --git a/docs/c-language/function-call-c.md b/docs/c-language/function-call-c.md index dd14511130..8d977b1718 100644 --- a/docs/c-language/function-call-c.md +++ b/docs/c-language/function-call-c.md @@ -11,17 +11,17 @@ A *function call* is an expression that includes the name of the function being ## Syntax -*postfix-expression*:
-    *postfix-expression* **(** *argument-expression-list*opt **)** +*`postfix-expression`*:\ + *`postfix-expression`* **`(`** *`argument-expression-list`*opt **`)`** -*argument-expression-list*:
-    *assignment-expression*
-    *argument-expression-list* **,** *assignment-expression* +*`argument-expression-list`*:\ + *`assignment-expression`*\ + *`argument-expression-list`* **`,`** *`assignment-expression`* -The *postfix-expression* must evaluate to a function address (for example, a function identifier or the value of a function pointer), and *argument-expression-list* is a list of expressions (separated by commas) whose values (the "arguments") are passed to the function. The *argument-expression-list* argument can be empty. +The *`postfix-expression`* must evaluate to a function address (for example, a function identifier or the value of a function pointer), and *`argument-expression-list`* is a list of expressions (separated by commas) whose values (the "arguments") are passed to the function. The *`argument-expression-list`* argument can be empty. -A function-call expression has the value and type of the function's return value. A function cannot return an object of array type. If the function's return type is **`void`** (that is, the function has been declared never to return a value), the function-call expression also has **`void`** type. (See [Function Calls](../c-language/function-calls.md) for more information.) +A function-call expression has the value and type of the function's return value. A function can't return an object of array type. If the function's return type is **`void`** (that is, the function has been declared never to return a value), the function-call expression also has **`void`** type. For more information, see [Function Calls](../c-language/function-calls.md). ## See also -[Function Call Operator: ()](../cpp/function-call-operator-parens.md) +[Function Call Operator: `()`](../cpp/function-call-operator-parens.md) diff --git a/docs/c-language/function-prototypes.md b/docs/c-language/function-prototypes.md index 85a4cdeff4..01f8a0cbd6 100644 --- a/docs/c-language/function-prototypes.md +++ b/docs/c-language/function-prototypes.md @@ -11,32 +11,32 @@ A function declaration precedes the function definition and specifies the name, ## Syntax -*declaration*:
-    *declaration-specifiers* *attribute-seq*opt *init-declarator-list*opt **;** +*`declaration`*:\ + *`declaration-specifiers`* *`attribute-seq`*opt *`init-declarator-list`*opt **`;`** -/\* *attribute-seq*opt is Microsoft-specific \*/ +/\* *`attribute-seq`*opt is Microsoft-specific \*/ -*declaration-specifiers*:
-    *storage-class-specifier* *declaration-specifiers*opt
-    *type-specifier* *declaration-specifiers*opt
-    *type-qualifier* *declaration-specifiers*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt \ + *`type-specifier`* *`declaration-specifiers`*opt \ + *`type-qualifier`* *`declaration-specifiers`*opt -*init-declarator-list*:
-    *init-declarator*
-    *init-declarator-list* **,** *init-declarator* +*`init-declarator-list`*:\ + *`init-declarator`*\ + *`init-declarator-list`* **`,`** *`init-declarator`* -*init-declarator*:
-    *declarator*
-    *declarator* **=** *initializer* +*`init-declarator`*:\ + *`declarator`*\ + *`declarator`* **`=`** *`initializer`* -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*: /\* A function declarator \*/
-    *direct-declarator* **(** *parameter-type-list* **)** /\* New-style declarator \*/
-    *direct-declarator* **(** *identifier-list*opt **)** /\* Obsolete-style declarator \*/ +*`direct-declarator`*: /\* A function declarator \*/\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`** /\* New-style declarator \*/\ + *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** /\* Obsolete-style declarator \*/ -The prototype has the same form as the function definition, except that it is terminated by a semicolon immediately following the closing parenthesis and therefore has no body. In either case, the return type must agree with the return type specified in the function definition. +The prototype has the same form as the function definition, except that it's terminated by a semicolon immediately following the closing parenthesis and therefore has no body. In either case, the return type must agree with the return type specified in the function definition. Function prototypes have the following important uses: @@ -48,7 +48,7 @@ Function prototypes have the following important uses: - The parameter list is used to check that arguments in the function call match the parameters in the function definition. -The converted type of each parameter determines the interpretation of the arguments that the function call places on the stack. A type mismatch between an argument and a parameter may cause the arguments on the stack to be misinterpreted. For example, on a 16-bit computer, if a 16-bit pointer is passed as an argument, then declared as a **`long`** parameter, the first 32 bits on the stack are interpreted as a **`long`** parameter. This error creates problems not only with the **`long`** parameter, but with any parameters that follow it. You can detect errors of this kind by declaring complete function prototypes for all functions. +The converted type of each parameter determines the interpretation of the arguments that the function call places on the stack. A type mismatch between an argument and a parameter may cause the arguments on the stack to be misinterpreted. For example, on a 16-bit computer, if a 16-bit pointer is passed as an argument, then declared as a **`long`** parameter, the first 32 bits on the stack are interpreted as a **`long`** parameter. This error creates problems not only with the **`long`** parameter, but with all the subsequent parameters. You can detect errors of this kind by declaring complete function prototypes for all functions. A prototype establishes the attributes of a function. Then, function calls that precede the function definition (or that occur in other source files) can be checked for argument-type and return-type mismatches. For example, if you specify the **`static`** storage-class specifier in a prototype, you must also specify the **`static`** storage class in the function definition. @@ -73,7 +73,7 @@ struct S; void func1( struct S * ); ``` -Under **/Ze**, the tag is still entered at global scope. +Under **`/Ze`**, the tag is still entered at global scope. ## See also diff --git a/docs/c-language/generic-selection.md b/docs/c-language/generic-selection.md index f5c1edd6c3..2e9872209a 100644 --- a/docs/c-language/generic-selection.md +++ b/docs/c-language/generic-selection.md @@ -67,7 +67,6 @@ int main() /* Output: Type name: double */ - ``` ## Requirements diff --git a/docs/c-language/goto-and-labeled-statements-c.md b/docs/c-language/goto-and-labeled-statements-c.md index 799303884e..712deb1f11 100644 --- a/docs/c-language/goto-and-labeled-statements-c.md +++ b/docs/c-language/goto-and-labeled-statements-c.md @@ -6,27 +6,27 @@ f1_keywords: ["goto"] helpviewer_keywords: ["labeled statement", "statements, labeled", "goto keyword [C]"] ms.assetid: 3d0473dc-4b18-4fcc-9616-31a38499d7d7 --- -# goto and Labeled Statements (C) +# `goto` and Labeled Statements (C) The **`goto`** statement transfers control to a label. The given label must reside in the same function and can appear before only one statement in the same function. ## Syntax -*statement*:
-    *labeled-statement*
-    *jump-statement* +*`statement`*:\ + *`labeled-statement`*\ + *`jump-statement`* -*jump-statement*:
-    **`goto`** *identifier* **;** +*`jump-statement`*:\ + **`goto`** *`identifier`* **`;`** -*labeled-statement*:
-    *identifier* **:** *statement* +*`labeled-statement`*:\ + *`identifier`* **`:`** *`statement`* A statement label is meaningful only to a **`goto`** statement; in any other context, a labeled statement is executed without regard to the label. -A *jump-statement* must reside in the same function and can appear before only one statement in the same function. The set of *identifier* names following a **`goto`** has its own name space so the names do not interfere with other identifiers. Labels cannot be redeclared. See [Name Spaces](../c-language/name-spaces.md) for more information. +A *`jump-statement`* must reside in the same function and can appear before only one statement in the same function. The set of *`identifier`* names following a **`goto`** has its own name space so the names don't interfere with other identifiers. Labels can't be redeclared. For more information, see [Name spaces](../c-language/name-spaces.md). -It is good programming style to use the **`break`**, **`continue`**, and **`return`** statement in preference to **`goto`** whenever possible. Since the **`break`** statement only exits from one level of the loop, a **`goto`** may be necessary for exiting a loop from within a deeply nested loop. +It's good programming style to use the **`break`**, **`continue`**, and **`return`** statement in preference to **`goto`** whenever possible. Since the **`break`** statement only exits from one level of the loop, a **`goto`** may be necessary for exiting a loop from within a deeply nested loop. This example demonstrates the **`goto`** statement: diff --git a/docs/c-language/if-statement-c.md b/docs/c-language/if-statement-c.md index 068726e077..31ab134898 100644 --- a/docs/c-language/if-statement-c.md +++ b/docs/c-language/if-statement-c.md @@ -6,20 +6,19 @@ f1_keywords: ["else", "if"] helpviewer_keywords: ["if keyword [C]", "else clauses", "else keyword [C]", "if keyword [C], if statement syntax", "nested statements"] ms.assetid: d7fc16a0-fdbc-4f39-b596-76e1ca4ad4a5 --- -# if Statement (C) +# `if` Statement (C) The **`if`** statement controls conditional branching. The body of an **`if`** statement is executed if the value of the expression is nonzero. The syntax for the **`if`** statement has two forms. ## Syntax -*selection-statement*: -**if (** *expression* **)** *statement* - -**if (** *expression* **)** *statement* **`else`** *statement* +*`selection-statement`*:\ + **`if (`** *`expression`* **`)`** *`statement`*\ + **`if (`** *`expression`* **`)`** *`statement`* **`else`** *`statement`* In both forms of the **`if`** statement, the expressions, which can have any value except a structure, are evaluated, including all side effects. -In the first form of the syntax, if *expression* is true (nonzero), *statement* is executed. If *expression* is false, *statement* is ignored. In the second form of syntax, which uses **`else`**, the second *statement* is executed if *expression* is false. With both forms, control then passes from the **`if`** statement to the next statement in the program unless one of the statements contains a **`break`**, **`continue`**, or **`goto`**. +In the first form of the syntax, if *`expression`* is true (nonzero), *`statement`* is executed. If *`expression`* is false, *`statement`* is ignored. In the second form of syntax, which uses **`else`**, the second *`statement`* is executed if *`expression`* is false. With both forms, control then passes from the **`if`** statement to the next statement in the program unless one of the statements contains a **`break`**, **`continue`**, or **`goto`**. The following are examples of the **`if`** statement: @@ -33,7 +32,7 @@ else } ``` -In this example, the statement `y = x/i;` is executed if `i` is greater than 0. If `i` is less than or equal to 0, `i` is assigned to `x` and `f( x )` is assigned to `y`. Note that the statement forming the **`if`** clause ends with a semicolon. +In this example, the statement `y = x/i;` is executed if `i` is greater than 0. If `i` is less than or equal to 0, `i` is assigned to `x`, and `f( x )` is assigned to `y`. The statement forming the **`if`** clause ends with a semicolon. When nesting **`if`** statements and **`else`** clauses, use braces to group the statements and clauses into compound statements that clarify your intent. If no braces are present, the compiler resolves ambiguities by associating each **`else`** with the closest **`if`** that lacks an **`else`**. diff --git a/docs/c-language/index.yml b/docs/c-language/index.yml index feb5f6855e..3f038a096b 100644 --- a/docs/c-language/index.yml +++ b/docs/c-language/index.yml @@ -5,6 +5,7 @@ summary: Learn to use C and the C runtime library. metadata: title: C docs - get started, tutorials, reference. description: C programming reference for users of Microsoft C/C++ and Visual Studio. + ms.author: twhitney ms.topic: landing-page ms.date: 05/28/2020 ms.custom: intro-landing-hub diff --git a/docs/c-language/indirection-and-address-of-operators.md b/docs/c-language/indirection-and-address-of-operators.md index defc502fab..bca030fb56 100644 --- a/docs/c-language/indirection-and-address-of-operators.md +++ b/docs/c-language/indirection-and-address-of-operators.md @@ -1,29 +1,37 @@ --- -description: "Learn more about: Indirection and Address-of Operators" -title: "Indirection and Address-of Operators" -ms.date: "02/16/2018" +description: "Learn more about: Indirection and address-of operators" +title: "Indirection and address-of operators" +ms.date: 05/09/2022 helpviewer_keywords: ["address-of operator (&)", "* operator", "operators [C++], address-of", "ampersand operator (&)", "* operator, indirection operator", "addresses [C++], indirection", "addresses [C++]", "indirection operator", "& operator, address-of operator", "null pointers [C++]", "* operator, address-of operator", "operators [C++], indirection"] ms.assetid: 10d62b00-12ba-4ea9-a2d5-09ac29ca2232 --- -# Indirection and Address-of Operators +# Indirection and address-of operators The unary indirection operator (**`*`**) accesses a value indirectly, through a pointer. The operand must be a pointer type. The result of the operation is the value addressed by the operand; that is, the value at the address to which its operand points. The type of the result is the type that the operand addresses. The result of the indirection operator is *type* if the operand is of type *pointer to type*. If the operand points to a function, the result is a function designator. If it points to an object, the result is an lvalue that designates the object. -If the pointer value is not valid, the result of the indirection operator is undefined. These are some of the most common conditions that invalidate a pointer value: +If the pointer value isn't valid, the result of the indirection operator is undefined. Here are some of the most common conditions that invalidate a pointer value: - The pointer is a null pointer. -- The pointer specifies the address of an object after the end of its lifetime (such as an object that's gone out of scope or that's been deallocated) at the time of the reference. +- The pointer specifies the address of an object after the end of its lifetime at the time of the reference. (For example, an object that's gone out of scope or that's been deallocated.) -- The pointer specifies an address that is inappropriately aligned for the type of the object pointed to. +- The pointer specifies an address that's inappropriately aligned for the type of the object pointed to. - The pointer specifies an address not used by the executing program. -The unary address-of operator (**`&`**) gives the address of its operand. The operand must be either an lvalue that designates an object that is not declared **`register`** and is not a bit-field, or the result of a unary **`*`** operator or an array dereference (**`[]`**) operator, or a function designator. The result is of type *pointer to type* for an operand of type *type*. +The unary address-of operator (**`&`**) gives the address of its operand. The operand must be one of these things: -If the operand is the result of a unary **`*`** operator, neither operator is evaluated and the result is as if both were omitted. The result is not an lvalue, and the constraints on the operators still apply. If the operand is the result of a **`[]`** operator, neither the **`&`** operator nor the unary **`*`** implied by the **`[]`** operator is evaluated. The result has the same effect as removing the **`&`** operator and changing the **`[]`** operator to a **`+`** operator. Otherwise, the result is a pointer to the object or function designated by the operand. +- An lvalue that designates an object that isn't declared **`register`** and isn't a bit-field. + +- The result of a unary dereference (**`*`**) or array dereference (**`[]`**) operator. + +- A function designator. + +The result is of type *pointer to operand_type* for an operand of type *operand_type*. + +If the operand is the result of a unary **`*`** operator, neither operator is evaluated and the result is as if both were omitted. The result isn't an lvalue, and the constraints on the operators still apply. If the operand is the result of a **`[]`** operator, the **`&`** operator and the unary **`*`** implied by the **`[]`** operator aren't evaluated. The result has the same effect as removing the **`&`** operator and changing the **`[]`** operator to a **`+`** operator. Otherwise, the result is a pointer to the object or function designated by the operand. ## Examples @@ -32,7 +40,6 @@ The following examples use these common declarations: ```C int *pa, x; int a[20]; -double d; ``` This statement uses the address-of operator (**`&`**) to take the address of the sixth element of the array `a`. The result is stored in the pointer variable `pa`: @@ -67,5 +74,5 @@ Once the function `roundup` is declared, two pointers to `roundup` are declared ## See also -[Indirection Operator: `*`](../cpp/indirection-operator-star.md)
-[Address-of Operator: &](../cpp/address-of-operator-amp.md) +[Indirection operator: `*`](../cpp/indirection-operator-star.md)\ +[Address-of operator: `&`](../cpp/address-of-operator-amp.md) diff --git a/docs/c-language/initializing-aggregate-types.md b/docs/c-language/initializing-aggregate-types.md index 4b1c2b7553..b842ad54b3 100644 --- a/docs/c-language/initializing-aggregate-types.md +++ b/docs/c-language/initializing-aggregate-types.md @@ -11,27 +11,27 @@ An *aggregate* type is a structure, union, or array type. If an aggregate type c ## Syntax -*initializer*:
-    **{** *initializer-list* **}** /* For aggregate initialization \*/
-    **{** *initializer-list* **, }** +*`initializer`*:\ + **`{`** *`initializer-list`* **`}`** /* For aggregate initialization \*/\ + **`{`** *`initializer-list`* **`, }`** -*initializer-list*:
-    *initializer*
-    *initializer-list* **,** *initializer* +*`initializer-list`*:\ + *`initializer`*\ + *`initializer-list`* **`,`** *`initializer`* -The *initializer-list* is a list of initializers separated by commas. Each initializer in the list is either a constant expression or an initializer list. Therefore, initializer lists can be nested. This form is useful for initializing aggregate members of an aggregate type, as shown in the examples in this section. However, if the initializer for an automatic identifier is a single expression, it need not be a constant expression; it merely needs to have appropriate type for assignment to the identifier. +The *`initializer-list`* is a list of initializers separated by commas. Each initializer in the list is either a constant expression or an initializer list. Therefore, initializer lists can be nested. This form is useful for initializing aggregate members of an aggregate type, as shown in the examples in this section. However, if the initializer for an automatic identifier is a single expression, it need not be a constant expression; it merely needs to have appropriate type for assignment to the identifier. For each initializer list, the values of the constant expressions are assigned, in order, to the corresponding members of the aggregate variable. -If *initializer-list* has fewer values than an aggregate type, the remaining members or elements of the aggregate type are initialized to 0. The initial value of an automatic identifier not explicitly initialized is undefined. If *initializer-list* has more values than an aggregate type, an error results. These rules apply to each embedded initializer list, as well as to the aggregate as a whole. +If *`initializer-list`* has fewer values than an aggregate type, the remaining members or elements of the aggregate type are initialized to 0. The initial value of an automatic identifier not explicitly initialized is undefined. If *`initializer-list`* has more values than an aggregate type, an error results. These rules apply to each embedded initializer list, and to the aggregate as a whole. -A structure's initializer is either an expression of the same type, or a list of initializers for its members enclosed in curly braces (**{ }**). Unnamed bit-field members are not initialized. +A structure's initializer is either an expression of the same type, or a list of initializers for its members enclosed in curly braces (**`{ }`**). Unnamed bit-field members aren't initialized. -When a union is initialized, *initializer-list* must be a single constant expression. The value of the constant expression is assigned to the first member of the union. +When a union is initialized, *`initializer-list`* must be a single constant expression. The value of the constant expression is assigned to the first member of the union. -If an array has unknown size, the number of initializers determines the size of the array, and its type becomes complete. There is no way to specify repetition of an initializer in C, or to initialize an element in the middle of an array without providing all preceding values as well. If you need this operation in your program, write the routine in assembly language. +If an array has unknown size, the number of initializers determines the size of the array, and its type becomes complete. There's no way to specify repetition of an initializer in C, or to initialize an element in the middle of an array without providing all preceding values as well. If you need this operation in your program, write the routine in assembly language. -Note that the number of initializers can set the size of the array: +The number of initializers can set the size of the array: ```C int x[ ] = { 0, 1, 2 } @@ -41,7 +41,7 @@ If you specify the size and give the wrong number of initializers, however, the **Microsoft Specific** -The maximum size for an array is defined by **size_t**. Defined in the header file STDDEF.H, **size_t** is an **`unsigned int`** with the range 0x00000000 to 0x7CFFFFFF. +The maximum size for an array is defined by **`size_t`**. **END Microsoft Specific** @@ -59,9 +59,9 @@ int P[4][3] = }; ``` -This statement declares `P` as a four-by-three array and initializes the elements of its first row to 1, the elements of its second row to 2, and so on through the fourth row. Note that the initializer list for the third and fourth rows contains commas after the last constant expression. The last initializer list (`{4, 4, 4,},`) is also followed by a comma. These extra commas are permitted but are not required; only commas that separate constant expressions from one another, and those that separate one initializer list from another, are required. +This statement declares `P` as a four-by-three array and initializes the elements of its first row to 1, the elements of its second row to 2, and so on, through the fourth row. The initializer list for the third and fourth rows contains commas after the last constant expression. The last initializer list (`{4, 4, 4,},`) is also followed by a comma. These extra commas are permitted but aren't required. Only commas that separate constant expressions from one another, and commas that separate one initializer list from another, are required. -If an aggregate member has no embedded initializer list, values are simply assigned, in order, to each member of the subaggregate. Therefore, the initialization in the previous example is equivalent to the following: +If an aggregate member has no embedded initializer list, values are assigned, in order, to each member of the subaggregate. Therefore, the initialization in the previous example is equivalent to the following example: ```C int P[4][3] = @@ -70,7 +70,7 @@ int P[4][3] = }; ``` -Braces can also appear around individual initializers in the list and would help to clarify the example above. +Braces can also appear around individual initializers in the list and would help to clarify the example. When you initialize an aggregate variable, you must be careful to use braces and initializer lists properly. The following example illustrates the compiler's interpretation of braces in more detail: @@ -97,7 +97,7 @@ In this example, `nlist` is declared as a 2-by-3 array of structures, each struc 1. The process continues until the end of the line, where the closing right brace ends initialization of `nlist[0]`. -Row 2 assigns values to the second row of `nlist` in a similar way. Note that the outer sets of braces enclosing the initializers on rows 1 and 2 are required. The following construction, which omits the outer braces, would cause an error: +Row 2 assigns values to the second row of `nlist` in a similar way. The outer sets of braces enclosing the initializers on rows 1 and 2 are required. The following construction, which omits the outer braces, would cause an error: ```C triplet nlist[2][3] = /* THIS CAUSES AN ERROR */ @@ -124,7 +124,7 @@ struct list }; ``` -In the `list` structure above, the three elements in the first row of `m` are initialized to 4.0; the elements of the remaining row of `m` are initialized to 0.0 by default. +In the `list` structure, the three elements in the first row of `m` are initialized to 4.0; the elements of the remaining row of `m` are initialized to 0.0 by default. ```C union diff --git a/docs/c-language/initializing-scalar-types.md b/docs/c-language/initializing-scalar-types.md index ee4b75ca48..77c5673825 100644 --- a/docs/c-language/initializing-scalar-types.md +++ b/docs/c-language/initializing-scalar-types.md @@ -7,40 +7,40 @@ ms.assetid: 73c516f5-c3ad-4d56-ab3b-f2a82b621104 --- # Initializing Scalar Types -When initializing scalar types, the value of the *`assignment-expression`* is assigned to the variable. The conversion rules for assignment apply. (See [Type Conversions](../c-language/type-conversions-c.md) for information on conversion rules.) +When you initialize scalar types, the value of the *`assignment-expression`* is assigned to the variable. The conversion rules for assignment apply. (See [Type Conversions](../c-language/type-conversions-c.md) for information on conversion rules.) ## Syntax -*`declaration`*:
-    *`declaration-specifiers`* *`init-declarator-list`*opt **`;`** +*`declaration`*:\ + *`declaration-specifiers`* *`init-declarator-list`*opt **`;`** -*`declaration-specifiers`*:
-    *`storage-class-specifier`* *`declaration-specifiers`*opt
-    *`type-specifier`* *`declaration-specifiers`*opt
-    *`type-qualifier`* *`declaration-specifiers`*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt \ + *`type-specifier`* *`declaration-specifiers`*opt \ + *`type-qualifier`* *`declaration-specifiers`*opt -*`init-declarator-list`*:
-    *`init-declarator`*
-    *`init-declarator-list`* **`,`** *`init-declarator`* +*`init-declarator-list`*:\ + *`init-declarator`*\ + *`init-declarator-list`* **`,`** *`init-declarator`* -*`init-declarator`*:
-    *`declarator`*
-    *`declarator`* **`=`** *`initializer`* /\* For scalar initialization \*/ +*`init-declarator`*:\ + *`declarator`*\ + *`declarator`* **`=`** *`initializer`* /\* For scalar initialization \*/ -*`initializer`*:
-    *`assignment-expression`* +*`initializer`*:\ + *`assignment-expression`* -You can initialize variables of any type, provided that you obey the following rules: +You can initialize variables of any type, as long as you obey the following rules: -- Variables declared at the file-scope level can be initialized. If you do not explicitly initialize a variable at the external level, it is initialized to 0 by default. +- Variables declared at the file-scope level can be initialized. If you don't explicitly initialize a variable at the external level, it's initialized to 0 by default. -- A constant expression can be used to initialize any global variable declared with the **`static`** *`storage-class-specifier`*. Variables declared to be **`static`** are initialized when program execution begins. If you do not explicitly initialize a global **`static`** variable, it is initialized to 0 by default, and every member that has pointer type is assigned a null pointer. +- A constant expression can be used to initialize any global variable declared with the **`static`** *`storage-class-specifier`*. Variables declared to be **`static`** are initialized when program execution begins. If you don't explicitly initialize a global **`static`** variable, it's initialized to 0 by default, and every member that has pointer type is assigned a null pointer. -- Variables declared with the **`auto`** or **`register`** storage-class specifier are initialized each time execution control passes to the block in which they are declared. If you omit an initializer from the declaration of an **`auto`** or **`register`** variable, the initial value of the variable is undefined. For automatic and register values, the initializer is not restricted to being a constant; it can be any expression involving previously defined values, even function calls. +- Variables declared with the **`auto`** or **`register`** storage-class specifier are initialized each time execution control passes to the block in which they're declared. If you omit an initializer from the declaration of an **`auto`** or **`register`** variable, the initial value of the variable is undefined. For automatic and register values, the initializer isn't restricted to being a constant; it can be any expression involving previously defined values, even function calls. -- The initial values for external variable declarations and for all **`static`** variables, whether external or internal, must be constant expressions. (For more information, see [Constant Expressions](../c-language/c-constant-expressions.md).) Since the address of any externally declared or static variable is constant, it can be used to initialize an internally declared **`static`** pointer variable. However, the address of an **`auto`** variable cannot be used as a static initializer because it may be different for each execution of the block. You can use either constant or variable values to initialize **`auto`** and **`register`** variables. +- The initial values for external variable declarations and for all **`static`** variables, whether external or internal, must be constant expressions. (For more information, see [Constant Expressions](../c-language/c-constant-expressions.md).) Since the address of any externally declared or static variable is constant, it can be used to initialize an internally declared **`static`** pointer variable. However, the address of an **`auto`** variable can't be used as a static initializer because it may be different for each execution of the block. You can use either constant or variable values to initialize **`auto`** and **`register`** variables. -- If the declaration of an identifier has block scope, and the identifier has external linkage, the declaration cannot have an initialization. +- If the declaration of an identifier has block scope, and the identifier has external linkage, the declaration can't have an initialization. ## Examples @@ -62,7 +62,7 @@ The pointer `px` is initialized to 0, producing a "null" pointer. const int c = (3 * 1024); ``` -This example uses a constant expression `(3 * 1024)` to initialize `c` to a constant value that cannot be modified because of the **`const`** keyword. +This example uses a constant expression `(3 * 1024)` to initialize `c` to a constant value that can't be modified because of the **`const`** keyword. ```C int *b = &x; @@ -74,7 +74,7 @@ This statement initializes the pointer `b` with the address of another variable, int *const a = &z; ``` -The pointer `a` is initialized with the address of a variable named `z`. However, since it is specified to be a **`const`**, the variable `a` can only be initialized, never modified. It always points to the same location. +The pointer `a` is initialized with the address of a variable named `z`. However, since it's specified to be a **`const`**, the variable `a` can only be initialized, never modified. It always points to the same location. ```C int GLOBAL ; @@ -88,7 +88,7 @@ int function( void ) } ``` -The global variable `GLOBAL` is declared at the external level, so it has global lifetime. The local variable `LOCAL` has **`auto`** storage class and only has an address during the execution of the function in which it is declared. Therefore, attempting to initialize the **`static`** pointer variable `lp` with the address of `LOCAL` is not permitted. The **`static`** pointer variable `gp` can be initialized to the address of `GLOBAL` because that address is always the same. Similarly, `*rp` can be initialized because `rp` is a local variable and can have a non-constant initializer. Each time the block is entered, `LOCAL` has a new address, which is then assigned to `rp`. +The global variable `GLOBAL` is declared at the external level, so it has global lifetime. The local variable `LOCAL` has **`auto`** storage class and only has an address during the execution of the function in which it's declared. Therefore, attempting to initialize the **`static`** pointer variable `lp` with the address of `LOCAL` isn't permitted. The **`static`** pointer variable `gp` can be initialized to the address of `GLOBAL` because that address is always the same. Similarly, `*rp` can be initialized because `rp` is a local variable and can have a non-constant initializer. Each time the block is entered, `LOCAL` has a new address, which is then assigned to `rp`. ## See also diff --git a/docs/c-language/inline-functions.md b/docs/c-language/inline-functions.md index e30ede15a1..86dae219ef 100644 --- a/docs/c-language/inline-functions.md +++ b/docs/c-language/inline-functions.md @@ -1,34 +1,42 @@ --- description: "Learn more about: Inline Functions" title: "Inline Functions" -ms.date: "10/16/2017" +ms.date: 08/24/2022 helpviewer_keywords: ["fast code", "inline functions, __inline keyword", "functions [C++], inline functions"] ms.assetid: 00f4b2ff-8ad0-4165-9f4c-2ef157d03f31 --- -# Inline Functions +# Inline functions -**Microsoft Specific** +The **`inline`** keyword is a function specifier that tells the compiler to substitute the code within the function definition for every instance of a function call. -The **`__inline`** keyword tells the compiler to substitute the code within the function definition for every instance of a function call. However, substitution occurs only at the compiler's discretion. For example, the compiler does not inline a function if its address is taken or if it is too large to inline. +## Remarks -For a function to be considered as a candidate for inlining, it must use the new-style function definition. +Inline code substitution occurs only at the compiler's discretion. For example, the compiler won't inline a function if its address is taken or if it's too large to inline. When the compiler doesn't inline a function defined in a header file, it's marked for the linker to avoid one-definition rule (ODR) violations. + +For a function to be considered as a candidate for inlining, it must use the new-style function definition with a signature that declares the return type and any parameter types. Use this form to specify an inline function: -> **`__inline`** *type*opt *function-definition* +> **`inline`** *function-definition* + +Inline functions generate faster and sometimes smaller code than the equivalent function call: + +- Inline functions save the time required to prepare the stack for arguments and a return value, and the time to execute the jump and return of a function call. + +- Even when repeated several times, small inline functions of perhaps three lines or less create less code than the equivalent function call because the compiler doesn't generate code to handle arguments and a return value. -The use of inline functions generates faster code and can sometimes generate smaller code than the equivalent function call generates for the following reasons: +- The compiler can optimize functions generated inline in ways that aren't available to normal functions. The compiler doesn't usually perform optimizations between different procedures. -- It saves the time required to execute function calls. +Don't confuse functions that use **`inline`** with inline assembler code. For more information about inline assembler, see [Inline assembler](../c-language/inline-assembler-c.md). -- Small inline functions, perhaps three lines or less, create less code than the equivalent function call because the compiler doesn't generate code to handle arguments and a return value. +**Microsoft specific** -- Functions generated inline are subject to code optimizations not available to normal functions because the compiler does not perform interprocedural optimizations. +Microsoft also supports **`__inline`** and **`__forceinline`** keywords to tell the compiler to substitute the code within the function definition for every instance of a function call. The **`__inline`** keyword is a synonym for **`inline`**. The **`__forceinline`** keyword tells the compiler to relax the heuristics on whether to inline the function, though it doesn't guarantee a function will be inlined. -Functions using **`__inline`** should not be confused with inline assembler code. See [Inline Assembler](../c-language/inline-assembler-c.md) for more information. +For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`** and **`__forceinline`**, respectively, unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. -**END Microsoft Specific** +**END Microsoft specific** ## See also -[inline, __inline, \__forceinline](../cpp/inline-functions-cpp.md) +[`inline`, `__inline`, `__forceinline`](../cpp/inline-functions-cpp.md) diff --git a/docs/c-language/interpreting-more-complex-declarators.md b/docs/c-language/interpreting-more-complex-declarators.md index d780d03e13..938504a381 100644 --- a/docs/c-language/interpreting-more-complex-declarators.md +++ b/docs/c-language/interpreting-more-complex-declarators.md @@ -47,31 +47,31 @@ In this example, the steps are numbered in order and can be interpreted as follo The following examples illustrate other complex declarations and show how parentheses can affect the meaning of a declaration. -``` +```C int *var[5]; /* Array of pointers to int values */ ``` The array modifier has higher priority than the pointer modifier, so `var` is declared to be an array. The pointer modifier applies to the type of the array elements; therefore, the array elements are pointers to **`int`** values. -``` +```C int (*var)[5]; /* Pointer to array of int values */ ``` In this declaration for `var`, parentheses give the pointer modifier higher priority than the array modifier, and `var` is declared to be a pointer to an array of five **`int`** values. -``` +```C long *var( long, long ); /* Function returning pointer to long */ ``` Function modifiers also have higher priority than pointer modifiers, so this declaration for `var` declares `var` to be a function returning a pointer to a **`long`** value. The function is declared to take two **`long`** values as arguments. -``` +```C long (*var)( long, long ); /* Pointer to function returning long */ ``` This example is similar to the previous one. Parentheses give the pointer modifier higher priority than the function modifier, and `var` is declared to be a pointer to a function that returns a **`long`** value. Again, the function takes two **`long`** arguments. -``` +```C struct both /* Array of pointers to functions */ { /* returning structures */ int a; @@ -81,14 +81,14 @@ struct both /* Array of pointers to functions */ The elements of an array cannot be functions, but this declaration demonstrates how to declare an array of pointers to functions instead. In this example, `var` is declared to be an array of five pointers to functions that return structures with two members. The arguments to the functions are declared to be two structures with the same structure type, `both`. Note that the parentheses surrounding `*var[5]` are required. Without them, the declaration is an illegal attempt to declare an array of functions, as shown below: -``` +```C /* ILLEGAL */ struct both *var[5](struct both, struct both); ``` The following statement declares an array of pointers. -``` +```C unsigned int *(* const *name[5][10] ) ( void ); ``` @@ -96,13 +96,13 @@ The `name` array has 50 elements organized in a multidimensional array. The elem This next example is a function returning a pointer to an array of three **`double`** values. -``` +```C double ( *var( double (*)[3] ) )[3]; ``` In this declaration, a function returns a pointer to an array, since functions returning arrays are illegal. Here `var` is declared to be a function returning a pointer to an array of three **`double`** values. The function `var` takes one argument. The argument, like the return value, is a pointer to an array of three **`double`** values. The argument type is given by a complex *abstract-declarator*. The parentheses around the asterisk in the argument type are required; without them, the argument type would be an array of three pointers to **`double`** values. For a discussion and examples of abstract declarators, see [Abstract Declarators](../c-language/c-abstract-declarators.md). -``` +```C union sign /* Array of arrays of pointers */ { /* to pointers to unions */ int x; @@ -112,7 +112,7 @@ union sign /* Array of arrays of pointers */ As the above example shows, a pointer can point to another pointer, and an array can contain arrays as elements. Here `var` is an array of five elements. Each element is a five-element array of pointers to pointers to unions with two members. -``` +```C union sign *(*var[5])[5]; /* Array of pointers to arrays of pointers to unions */ ``` diff --git a/docs/c-language/l-value-and-r-value-expressions.md b/docs/c-language/l-value-and-r-value-expressions.md index 90ee531673..cca7a68bf2 100644 --- a/docs/c-language/l-value-and-r-value-expressions.md +++ b/docs/c-language/l-value-and-r-value-expressions.md @@ -7,9 +7,9 @@ ms.assetid: b790303e-ec6f-4d0d-bc55-df42da267172 --- # L-Value and R-Value Expressions -Expressions that refer to memory locations are called "l-value" expressions. An l-value represents a storage region's "locator" value, or a "left" value, implying that it can appear on the left of the equal sign (**=**). L-values are often identifiers. +Expressions that refer to memory locations are called "l-value" expressions. An l-value represents a storage region's "locator" value, or a "left" value, implying that it can appear on the left of the equal sign (**`=`**). L-values are often identifiers. -Expressions referring to modifiable locations are called "modifiable l-values." A modifiable l-value cannot have an array type, an incomplete type, or a type with the **`const`** attribute. For structures and unions to be modifiable l-values, they must not have any members with the **`const`** attribute. The name of the identifier denotes a storage location, while the value of the variable is the value stored at that location. +Expressions referring to modifiable locations are called "modifiable l-values." A modifiable l-value can't have an array type, an incomplete type, or a type with the **`const`** attribute. For structures and unions to be modifiable l-values, they must not have any members with the **`const`** attribute. The name of the identifier denotes a storage location, while the value of the variable is the value stored at that location. An identifier is a modifiable l-value if it refers to a memory location and if its type is arithmetic, structure, union, or pointer. For example, if `ptr` is a pointer to a storage region, then `*ptr` is a modifiable l-value that designates the storage region to which `ptr` points. @@ -17,11 +17,11 @@ Any of the following C expressions can be l-value expressions: - An identifier of integral, floating, pointer, structure, or union type -- A subscript (**[ ]**) expression that does not evaluate to an array +- A subscript (**`[ ]`**) expression that doesn't evaluate to an array -- A member-selection expression (**->** or **.**) +- A member-selection expression (**`->`** or **`.`**) -- A unary-indirection (\*) expression that does not refer to an array +- A unary-indirection (**`*`**) expression that doesn't refer to an array - An l-value expression in parentheses @@ -31,7 +31,7 @@ The term "r-value" is sometimes used to describe the value of an expression and **Microsoft Specific** -Microsoft C includes an extension to the ANSI C standard that allows casts of l-values to be used as l-values, as long as the size of the object is not lengthened through the cast. (See [Type-Cast Conversions](../c-language/type-cast-conversions.md) for more information.) The following example illustrates this feature: +Microsoft C includes an extension to the ANSI C standard that allows casts of l-values to be used as l-values, as long as the size of the object isn't lengthened through the cast. (For more information, see [Type-Cast Conversions](../c-language/type-cast-conversions.md).) The following example illustrates this feature: ``` char *p ; diff --git a/docs/c-language/lexical-grammar.md b/docs/c-language/lexical-grammar.md index 77ab33c4a0..70757f0cf6 100644 --- a/docs/c-language/lexical-grammar.md +++ b/docs/c-language/lexical-grammar.md @@ -1,7 +1,7 @@ --- title: "C lexical grammar" description: "Describes the standard C language lexical grammar implemented by the Microsoft C/C++ compiler." -ms.date: 10/30/2020 +ms.date: 03/07/2022 helpviewer_keywords: ["lexical grammar"] ms.assetid: cb5847fa-aef3-47f5-8825-97c2bf4a3d87 --- @@ -114,7 +114,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo  **`0`** **`1`** **`2`** **`3`** **`4`** **`5`** **`6`** **`7`** *`hexadecimal-digit`*: one of\ - **`0`** **`1`** **`2`** **`3`** **`4`** **`5`** **`6`** **`7`** **`8`**\ + **`0`** **`1`** **`2`** **`3`** **`4`** **`5`** **`6`** **`7`** **`8`** **`9`**\  **`a`** **`b`** **`c`** **`d`** **`e`** **`f`**\  **`A`** **`B`** **`C`** **`D`** **`E`** **`F`** @@ -187,7 +187,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo  *`c-char-sequence`* *`c-char`* *`c-char`*:\ - Any member of the source character set except the single quotation mark (**`'`**), backslash (**`\`**), or newline character\ + Any member of the source character set except the single quotation mark (**`'`**), backslash (**`\`**), or new-line character\  *`escape-sequence`* *`escape-sequence`*:\ @@ -212,7 +212,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo ## String literals *`string-literal`*:\ - *`encoding-prefix`* *`s-char-sequence`*opt **`"`** + *`encoding-prefix`* **`"`** *`s-char-sequence`*opt **`"`** *`encoding-prefix`*:\  **`u8`**\ @@ -225,7 +225,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo  *`s-char-sequence`* *`s-char`* *`s-char`*:\ - any member of the source character set except the double-quotation mark (**`"`**), backslash (**`\`**), or newline character\ + any member of the source character set except the double-quotation mark (**`"`**), backslash (**`\`**), or new-line character\  *`escape-sequence`* ## Punctuators diff --git a/docs/c-language/main-function-and-program-execution.md b/docs/c-language/main-function-and-program-execution.md index f4b6cd1e8f..c12de71ba2 100644 --- a/docs/c-language/main-function-and-program-execution.md +++ b/docs/c-language/main-function-and-program-execution.md @@ -1,31 +1,48 @@ --- -description: "Learn more about: main Function and Program Execution" -title: "main Function and Program Execution" -ms.date: "11/04/2016" +description: "Learn more about: main function and program execution" +title: "main function and program execution" +ms.date: 09/28/2022 helpviewer_keywords: ["program startup [C++]", "entry points, program", "main function, program execution", "startup code, main function", "main function", "programs [C++], terminating"] ms.assetid: 5984f1bd-072d-4e06-8640-122fb1454401 --- -# main Function and Program Execution +# `main` function and program execution -Every C program has a primary (main) function that must be named **main**. If your code adheres to the Unicode programming model, you can use the wide-character version of **main**, **wmain**. The **main** function serves as the starting point for program execution. It usually controls program execution by directing the calls to other functions in the program. A program usually stops executing at the end of **main**, although it can terminate at other points in the program for a variety of reasons. At times, perhaps when a certain error is detected, you may want to force the termination of a program. To do so, use the **exit** function. See the *Run-Time Library Reference* for information on and an example using the [exit](../c-runtime-library/reference/exit-exit-exit.md) function. +Every C program has a primary function that must be named `main`. The `main` function serves as the starting point for program execution. It usually controls program execution by directing the calls to other functions in the program. -## Syntax +Several restrictions apply to the `main` function that don't apply to any other C functions. The `main` function: -``` -main( int argc, char *argv[ ], char *envp[ ] ) +- Can't be declared as **`inline`**. +- Can't be declared as **`static`**. +- Can't have its address taken. +- Can't be called from your program. + +## The `main` function signature + +The `main` function doesn't have a declaration, because it's built into the language. If it did, the declaration syntax for `main` would look like this: + +```C +int main( void ); +int main( int argc, char *argv[ ] ); +int main( int argc, char *argv[ ], char *envp[ ] ); ``` +The `main` function is declared implicitly by using one of these signatures. You may use any of these signatures when you define your `main` function. The Microsoft compiler also allows `main` to have a return type of **`void`** when no value is returned. The *`argv`* and *`envp`* parameters to `wmain` can also be defined as type `char**`. For more information about the arguments, see [Argument description](./argument-description.md). + ## Remarks -Functions within the source program perform one or more specific tasks. The **main** function can call these functions to perform their respective tasks. When **main** calls another function, it passes execution control to the function, so that execution begins at the first statement in the function. A function returns control to **main** when a **`return`** statement is executed or when the end of the function is reached. +Functions within the source program perform one or more specific tasks. The `main` function can call these functions to perform their respective tasks. When `main` calls another function, it passes execution control to the function, so that execution begins at the first statement in the function. A function returns control to `main` when a **`return`** statement is executed or when the end of the function is reached. + +You can declare any function, including `main`, to have parameters. The term "parameter" or "formal parameter" refers to the identifier that receives a value passed to a function. See [Parameters](../c-language/parameters.md) for information on passing arguments to parameters. When one function calls another, the called function receives values for its parameters from the calling function. These values are called *arguments*. You can declare formal parameters to `main` so that it can receive arguments from the command line using the format shown in the function signature. + +When you want to pass information to the `main` function, the parameters are traditionally named *`argc`* and *`argv`*, although the C compiler doesn't require these names. Traditionally, if a third parameter is passed to `main`, that parameter is named *`envp`*. The types for *`argc`*, *`argv`*, and *`envp`* are defined by the C language. You can also declare *`argv`* as `char** argv` and *`envp`* as `char** envp`. Examples later in this section show how to use these three parameters to access command-line arguments. The following sections explain these parameters. -You can declare any function, including **main**, to have parameters. The term "parameter" or "formal parameter" refers to the identifier that receives a value passed to a function. See [Parameters](../c-language/parameters.md) for information on passing arguments to parameters. When one function calls another, the called function receives values for its parameters from the calling function. These values are called "arguments." You can declare formal parameters to **main** so that it can receive arguments from the command line using this format: +If your code adheres to the Unicode programming model, you can use the Microsoft-specific wide-character version of **`main`**, **`wmain`**, as your program's entry point. For more information about this wide-character version of **`main`**, see [Using `wmain`](../c-language/using-wmain.md). -When you want to pass information to the **main** function, the parameters are traditionally named `argc` and `argv`, although the C compiler does not require these names. The types for `argc` and `argv` are defined by the C language. Traditionally, if a third parameter is passed to **main**, that parameter is named `envp`. Examples later in this section show how to use these three parameters to access command-line arguments. The following sections explain these parameters. +## `main` termination -See [Using wmain](../c-language/using-wmain.md) for a description of the wide-character version of **main**. +A program usually stops executing when it returns from or reaches the end of `main`, although it can terminate at other points in the program for various reasons. For example, you may want to force the termination of your program when some error condition is detected. To do so, you can use the `exit` function. For more information on `exit` and an example of usage, see [`exit`](../c-runtime-library/reference/exit-exit-exit.md). ## See also -[main function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ -[Parsing C Command-Line Arguments](../c-language/parsing-c-command-line-arguments.md) +[`main` function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ +[Parsing C command-line arguments](../c-language/parsing-c-command-line-arguments.md) diff --git a/docs/c-language/multidimensional-arrays-c.md b/docs/c-language/multidimensional-arrays-c.md index 06fedbf4a4..3aa1d2768b 100644 --- a/docs/c-language/multidimensional-arrays-c.md +++ b/docs/c-language/multidimensional-arrays-c.md @@ -9,11 +9,11 @@ ms.assetid: 4ba5c360-1f17-4575-b370-45f62e1f2bc2 A subscript expression can also have multiple subscripts, as follows: -``` -expression1 [ expression2 ] [ expression3 ] ... +```c +expression1 [ expression2 ] [ expression3 ] /*...*/ ; ``` -Subscript expressions associate from left to right. The leftmost subscript expression, *expression1* **[** *expression2* **]**, is evaluated first. The address that results from adding *expression1* and *expression2* forms a pointer expression; then *expression3* is added to this pointer expression to form a new pointer expression, and so on until the last subscript expression has been added. The indirection operator (\*) is applied after the last subscripted expression is evaluated, unless the final pointer value addresses an array type (see examples below). +Subscript expressions associate from left to right. The leftmost subscript expression, `expression1[ expression2 ]`, is evaluated first. The address that results from adding `expression1` and `expression2` forms a pointer expression; then `expression3` is added to this pointer expression to form a new pointer expression, and so on, until the last subscript expression has been added. The indirection operator (**`*`**) is applied after the last subscripted expression is evaluated, unless the final pointer value addresses an array type. Expressions with multiple subscripts refer to elements of "multidimensional arrays." A multidimensional array is an array whose elements are arrays. For example, the first element of a three-dimensional array is an array with two dimensions. @@ -21,20 +21,20 @@ Expressions with multiple subscripts refer to elements of "multidimensional arra For the following examples, an array named `prop` is declared with three elements, each of which is a 4-by-6 array of **`int`** values. -``` +```c int prop[3][4][6]; int i, *ip, (*ipp)[6]; ``` A reference to the `prop` array looks like this: -``` +```c i = prop[0][0][1]; ``` -The example above shows how to refer to the second individual **`int`** element of `prop`. Arrays are stored by row, so the last subscript varies most quickly; the expression `prop[0][0][2]` refers to the next (third) element of the array, and so on. +The example shows how to refer to the second individual **`int`** element of `prop`. Arrays are stored by row, so the last subscript varies most quickly; the expression `prop[0][0][2]` refers to the next (third) element of the array, and so on. -``` +```c i = prop[2][1][3]; ``` @@ -44,19 +44,19 @@ This statement is a more complex reference to an individual element of `prop`. T 1. The second subscript, `1`, is multiplied by the size of the 6-element **`int`** array and added to the address represented by `prop[2]`. -1. Each element of the 6-element array is an **`int`** value, so the final subscript, `3`, is multiplied by the size of an **`int`** before it is added to `prop[2][1]`. The resulting pointer addresses the fourth element of the 6-element array. +1. Each element of the 6-element array is an **`int`** value, so the final subscript, `3`, is multiplied by the size of an **`int`** before it's added to `prop[2][1]`. The resulting pointer addresses the fourth element of the 6-element array. 1. The indirection operator is applied to the pointer value. The result is the **`int`** element at that address. -These next two examples show cases where the indirection operator is not applied. +These next two examples show cases where the indirection operator isn't applied. -``` +```c ip = prop[2][1]; ipp = prop[2]; ``` -In the first of these statements, the expression `prop[2][1]` is a valid reference to the three-dimensional array `prop`; it refers to a 6-element array (declared above). Since the pointer value addresses an array, the indirection operator is not applied. +In the first of these statements, the expression `prop[2][1]` is a valid reference to the three-dimensional array `prop`; it refers to a 6-element array (declared previously). Since the pointer value addresses an array, the indirection operator isn't applied. Similarly, the result of the expression `prop[2]` in the second statement `ipp = prop[2];` is a pointer value addressing a two-dimensional array. diff --git a/docs/c-language/name-spaces.md b/docs/c-language/name-spaces.md index f41ec42a2a..7d525866b3 100644 --- a/docs/c-language/name-spaces.md +++ b/docs/c-language/name-spaces.md @@ -14,19 +14,19 @@ The compiler sets up "name spaces" to distinguish between the identifiers used f This list describes the name spaces used in C. -Statement labels +**Statement labels**\ Named statement labels are part of statements. Definitions of statement labels are always followed by a colon but are not part of **`case`** labels. Uses of statement labels always immediately follow the keyword **`goto`**. Statement labels do not have to be distinct from other names or from label names in other functions. -Structure, union, and enumeration tags +**Structure, union, and enumeration tags**\ These tags are part of structure, union, and enumeration type specifiers and, if present, always immediately follow the reserved words **`struct`**, **`union`**, or **`enum`**. The tag names must be distinct from all other structure, enumeration, or union tags with the same visibility. -Members of structures or unions +**Members of structures or unions**\ Member names are allocated in name spaces associated with each structure and union type. That is, the same identifier can be a component name in any number of structures or unions at the same time. Definitions of component names always occur within structure or union type specifiers. Uses of component names always immediately follow the member-selection operators (**->** and **.**). The name of a member must be unique within the structure or union, but it does not have to be distinct from other names in the program, including the names of members of different structures and unions, or the name of the structure itself. -Ordinary identifiers +**Ordinary identifiers**\ All other names fall into a name space that includes variables, functions (including formal parameters and local variables), and enumeration constants. Identifier names have nested visibility, so you can redefine them within blocks. -Typedef names +**Typedef names**\ Typedef names cannot be used as identifiers in the same scope. For example, since structure tags, structure members, and variable names are in three different name spaces, the three items named `student` in this example do not conflict. The context of each item allows correct interpretation of each occurrence of `student` in the program. (For information about structures, see [Structure Declarations](../c-language/structure-declarations.md).) diff --git a/docs/c-language/one-dimensional-arrays.md b/docs/c-language/one-dimensional-arrays.md index d0bdc880cf..f436a95cb8 100644 --- a/docs/c-language/one-dimensional-arrays.md +++ b/docs/c-language/one-dimensional-arrays.md @@ -7,13 +7,11 @@ ms.assetid: e28536e5-3b77-46b5-97fd-9b938c771816 --- # One-Dimensional Arrays -A postfix expression followed by an expression in square brackets (**[ ]**) is a subscripted representation of an element of an array object. A subscript expression represents the value at the address that is *expression* positions beyond *postfix-expression* when expressed as +A postfix expression followed by an expression in square brackets (**`[ ]`**) is a subscripted representation of an element of an array object. A subscript expression represents the value at the address that is *`expression`* positions beyond *`postfix-expression`* when expressed as -``` -postfix-expression [ expression ] -``` +*`postfix-expression`* **`[`** *`expression`* **`]`** -Usually, the value represented by *postfix-expression* is a pointer value, such as an array identifier, and *expression* is an integral value. However, all that is required syntactically is that one of the expressions be of pointer type and the other be of integral type. Thus the integral value could be in the *postfix-expression* position and the pointer value could be in the brackets in the *expression*, or "subscript," position. For example, this code is legal: +Usually, the value represented by *`postfix-expression`* is a pointer value, such as an array identifier, and *`expression`* is an integral value. However, all that's required syntactically is that one of the expressions has pointer type and the other has integral type. The integral value could be in the *`postfix-expression`* position and the pointer value could be in the brackets in the *`expression`*, or "subscript," position. For example, this code is legal: ```c // one_dimensional_arrays.c @@ -24,18 +22,18 @@ int main() { } ``` -Subscript expressions are generally used to refer to array elements, but you can apply a subscript to any pointer. Whatever the order of values, *expression* must be enclosed in brackets (**[ ]**). +Subscript expressions are often used to refer to array elements, but you can apply a subscript to any pointer. Whatever the order of values, *`expression`* must be enclosed in brackets (**`[ ]`**). -The subscript expression is evaluated by adding the integral value to the pointer value, then applying the indirection operator (\*) to the result. (See [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) for a discussion of the indirection operator.) In effect, for a one-dimensional array, the following four expressions are equivalent, assuming that `a` is a pointer and `b` is an integer: +The subscript expression is evaluated by adding the integral value to the pointer value, then applying the indirection operator (**`*`**) to the result. (See [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) for a discussion of the indirection operator.) In effect, for a one-dimensional array, the following four expressions are equivalent, assuming that `a` is a pointer and `b` is an integer: -``` +```c a[b] *(a + b) *(b + a) b[a] ``` -According to the conversion rules for the addition operator (given in [Additive Operators](../c-language/c-additive-operators.md)), the integral value is converted to an address offset by multiplying it by the length of the type addressed by the pointer. +The conversion rules for the addition operator are given in [Additive Operators](../c-language/c-additive-operators.md)). To convert the integral value to an address offset, it's multiplied by the length of the type addressed by the pointer. For example, suppose the identifier `line` refers to an array of **`int`** values. The following procedure is used to evaluate the subscript expression `line[ i ]`: diff --git a/docs/c-language/overview-of-c-statements.md b/docs/c-language/overview-of-c-statements.md index d3e6525bb3..8608b7ba86 100644 --- a/docs/c-language/overview-of-c-statements.md +++ b/docs/c-language/overview-of-c-statements.md @@ -11,28 +11,21 @@ C statements consist of tokens, expressions, and other statements. A statement t ## Syntax -*statement*: -[labeled-statement](../c-language/goto-and-labeled-statements-c.md) - -[compound-statement](../c-language/compound-statement-c.md) - -[expression-statement](../c-language/expression-statement-c.md) - -[selection-statement](../c-language/if-statement-c.md) - -[iteration-statement](../c-language/do-while-statement-c.md) - -[jump-statement](../c-language/break-statement-c.md) - -[try-except-statement](../c-language/try-except-statement-c.md) /* Microsoft-specific \*/ - -[try-finally-statement](../c-language/try-finally-statement-c.md) /\* Microsoft-specific \*/ - -Frequently the statement body is a "compound statement." A compound statement consists of other statements that can include keywords. The compound statement is delimited by braces (**{ }**). All other C statements end with a semicolon (**;**). The semicolon is a statement terminator. +*`statement`*:\ + [`labeled-statement`](../c-language/goto-and-labeled-statements-c.md)\ + [`compound-statement`](../c-language/compound-statement-c.md)\ + [`expression-statement`](../c-language/expression-statement-c.md)\ + [`selection-statement`](../c-language/if-statement-c.md)\ + [`iteration-statement`](../c-language/do-while-statement-c.md)\ + [`jump-statement`](../c-language/break-statement-c.md)\ + [`try-except-statement`](../c-language/try-except-statement-c.md) /\* Microsoft-specific \*/\ + [`try-finally-statement`](../c-language/try-finally-statement-c.md) /\* Microsoft-specific \*/ + +Frequently the statement body is a "compound statement." A compound statement consists of other statements that can include keywords. The compound statement is delimited by braces (**`{ }`**). All other C statements end with a semicolon (**`;`**). The semicolon is a statement terminator. The expression statement contains a C expression that can contain the arithmetic or logical operators introduced in [Expressions and Assignments](../c-language/expressions-and-assignments.md). The null statement is an empty statement. -Any C statement can begin with an identifying label consisting of a name and a colon. Since only the **`goto`** statement recognizes statement labels, statement labels are discussed with **`goto`**. See [The goto and Labeled Statements](../c-language/goto-and-labeled-statements-c.md) for more information. +Any C statement can begin with an identifying label consisting of a name and a colon. Since only the **`goto`** statement recognizes statement labels, statement labels are discussed with **`goto`**. For more information, see [The goto and Labeled Statements](../c-language/goto-and-labeled-statements-c.md). ## See also diff --git a/docs/c-language/overview-of-declarations.md b/docs/c-language/overview-of-declarations.md index 8e99b63b82..131cec5c23 100644 --- a/docs/c-language/overview-of-declarations.md +++ b/docs/c-language/overview-of-declarations.md @@ -11,23 +11,23 @@ A "declaration" specifies the interpretation and attributes of a set of identifi ## Syntax -*`declaration`*:
-    *`declaration-specifiers`* *`attribute-seq`*opt *`init-declarator-list`*opt**`;`** +*`declaration`*:\ + *`declaration-specifiers`* *`attribute-seq`*opt *`init-declarator-list`*opt **`;`** /\* *`attribute-seq`*opt is Microsoft-specific */ -*`declaration-specifiers`*:
-    *`storage-class-specifier`* *`declaration-specifiers`*opt
-    *`type-specifier`* *`declaration-specifiers`*opt
-    *`type-qualifier`* *`declaration-specifiers`*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt\ + *`type-specifier`* *`declaration-specifiers`*opt\ + *`type-qualifier`* *`declaration-specifiers`*opt -*`init-declarator-list`*:
-    *`init-declarator`*
-    *`init-declarator-list`* **`,`** *`init-declarator`* +*`init-declarator-list`*:\ + *`init-declarator`*\ + *`init-declarator-list`* **`,`** *`init-declarator`* -*`init-declarator`*:
-    *`declarator`*
-    *`declarator`* **`=`** *`initializer`* +*`init-declarator`*:\ + *`declarator`*\ + *`declarator`* **`=`** *`initializer`* > [!NOTE] > This syntax for *`declaration`* is not repeated in the following sections. Syntax in the following sections usually begins with the *`declarator`* nonterminal. @@ -46,7 +46,7 @@ declares a variable named `fp` as a pointer to a nonmodifiable (**`const`**) **` A declaration must have at least one declarator, or its type specifier must declare a structure tag, union tag, or members of an enumeration. Declarators provide any remaining information about an identifier. A declarator is an identifier that can be modified with brackets (**`[ ]`**), asterisks (`*`), or parentheses ( **`( )`** ) to declare an array, pointer, or function type, respectively. When you declare simple variables (such as character, integer, and floating-point items), or structures and unions of simple variables, the `declarator` is just an identifier. For more information on declarators, see [Declarators and Variable Declarations](../c-language/declarators-and-variable-declarations.md). -All definitions are implicitly declarations, but not all declarations are definitions. For example, variable declarations that begin with the **`extern`** storage-class specifier are "referencing," rather than "defining" declarations. If an external variable is to be referred to before it's defined, or if it's defined in another source file from the one where it's used, an **`extern`** declaration is necessary. Storage is not allocated by "referencing" declarations, nor can variables be initialized in declarations. +All definitions are implicitly declarations, but not all declarations are definitions. For example, variable declarations using the **`extern`** storage-class specifier are "referencing," rather than "defining" declarations. If an external variable is to be referred to before it's defined, or if it's defined in another source file from the one where it's used, an **`extern`** declaration is necessary. Storage isn't allocated by "referencing" declarations, nor can variables be initialized in declarations. A storage class or a type (or both) is required in variable declarations. Except for **`__declspec`**, only one storage-class specifier is allowed in a declaration and not all storage-class specifiers are permitted in every context. The **`__declspec`** storage class is allowed with other storage-class specifiers, and it's allowed more than once. The storage-class specifier of a declaration affects how the declared item is stored and initialized, and which parts of a program can reference the item. @@ -56,7 +56,7 @@ The location of the declaration within the source program and the presence or ab Type specifiers provide some information about the data types of identifiers. The default type specifier is **`int`**. For more information, see [Type Specifiers](../c-language/c-type-specifiers.md). Type specifiers can also define type tags, structure and union component names, and enumeration constants. For more information, see [Enumeration Declarations](../c-language/c-enumeration-declarations.md), [Structure Declarations](../c-language/structure-declarations.md), and [Union Declarations](../c-language/union-declarations.md). -There are two *`type-qualifier`* terminals: **`const`** and **`volatile`**. These qualifiers specify additional properties of types that are relevant only when accessing objects of that type through l-values. For more information on **`const`** and **`volatile`**, see [Type Qualifiers](../c-language/type-qualifiers.md). For a definition of l-values, see [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md). +There are two *`type-qualifier`* terminals: **`const`** and **`volatile`**. These qualifiers specify extra properties of types that are relevant only when accessing objects of that type through l-values. For more information on **`const`** and **`volatile`**, see [Type Qualifiers](../c-language/type-qualifiers.md). For a definition of l-values, see [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md). ## See also diff --git a/docs/c-language/parameters.md b/docs/c-language/parameters.md index 8e5c6eefc2..cc504bb490 100644 --- a/docs/c-language/parameters.md +++ b/docs/c-language/parameters.md @@ -11,29 +11,29 @@ Arguments are names of values passed to a function by a function call. Parameter ## Syntax -*`function-definition`*:
-    *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* +*`function-definition`*:\ + *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* /\* *`attribute-seq`* is Microsoft-specific \*/ -*`declarator`*:
-    *`pointer`*opt *`direct-declarator`* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*`direct-declarator`*: /\* A function declarator \*/
-    *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`** /\* New-style declarator \*/
-    *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** /\* Obsolete-style declarator \*/ +*`direct-declarator`*: /\* A function declarator \*/\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`** /\* New-style declarator \*/\ + *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** /\* Obsolete-style declarator \*/ -*`parameter-type-list`*: /\* The parameter list \*/
-    *`parameter-list`*
-    *`parameter-list`* **`, ...`** +*`parameter-type-list`*: /\* The parameter list \*/\ + *`parameter-list`* \ + *`parameter-list`* **`, ...`** -*`parameter-list`*:
-    *`parameter-declaration`*
-    *`parameter-list`* **`,`** *`parameter-declaration`* +*`parameter-list`*:\ + *`parameter-declaration`*\ + *`parameter-list`* **`,`** *`parameter-declaration`* -*`parameter-declaration`*:
-    *`declaration-specifiers`* *`declarator`*
-    *`declaration-specifiers`* *`abstract-declarator`*opt +*`parameter-declaration`*:\ + *`declaration-specifiers`* *`declarator`*\ + *`declaration-specifiers`* *`abstract-declarator`*opt The *`parameter-type-list`* is a sequence of parameter declarations separated by commas. The form of each parameter in a parameter list looks like this: diff --git a/docs/c-language/pointer-declarations.md b/docs/c-language/pointer-declarations.md index 022967a414..b189f3cd6f 100644 --- a/docs/c-language/pointer-declarations.md +++ b/docs/c-language/pointer-declarations.md @@ -11,64 +11,64 @@ A *pointer declaration* names a pointer variable and specifies the type of the o ## Syntax -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*:
-    *identifier*
-    **(** *declarator* **)**
-    *direct-declarator* **[** *constant-expression*opt **]**
-    *direct-declarator* **(** *parameter-type-list* **)**
-    *direct-declarator* **(** *identifier-list*opt **)** +*`direct-declarator`*:\ + *`identifier`*\ + **`(`** *`declarator`* **`)`**\ + *`direct-declarator`* **`[`** *`constant-expression`*opt **`]`**\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`**\ + *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** -*pointer*:
-    \* *type-qualifier-list*opt
-    \* *type-qualifier-list*opt *pointer* +*`pointer`*:\ + **`*`** *`type-qualifier-list`*opt\ + **`*`** *`type-qualifier-list`*opt *`pointer`* -*type-qualifier-list*:
-    *type-qualifier*
-    *type-qualifier-list* *type-qualifier* +*`type-qualifier-list`*:\ + *`type-qualifier`*\ + *`type-qualifier-list`* *`type-qualifier`* -The *type-specifier* gives the type of the object, which can be any basic, structure, or union type. Pointer variables can also point to functions, arrays, and other pointers. (For information on declaring and interpreting more complex pointer types, refer to [Interpreting More Complex Declarators](../c-language/interpreting-more-complex-declarators.md).) +The *`type-specifier`* gives the type of the object, which can be any basic, structure, or union type. Pointer variables can also point to functions, arrays, and other pointers. (For information on declaring and interpreting more complex pointer types, refer to [Interpreting More Complex Declarators](../c-language/interpreting-more-complex-declarators.md).) -By making the *type-specifier* **`void`**, you can delay specification of the type to which the pointer refers. Such an item is referred to as a "pointer to **`void`**" and is written as `void *`. A variable declared as a pointer to *void* can be used to point to an object of any type. However, to perform most operations on the pointer or on the object to which it points, the type to which it points must be explicitly specified for each operation. (Variables of type **`char`** \* and type **`void`** \* are assignment-compatible without a type cast.) Such conversion can be accomplished with a type cast (see [Type-Cast Conversions](../c-language/type-cast-conversions.md) for more information). +By making the *`type-specifier`* **`void`**, you can delay specification of the type to which the pointer refers. Such an item is referred to as a "pointer to **`void`**" and is written as `void *`. A variable declared as a pointer to **`void`** can be used to point to an object of any type. However, to perform most operations on the pointer or on the object to which it points, the type to which it points must be explicitly specified for each operation. (Variables of type `char *` and type `void *` are assignment-compatible without a type cast.) Such conversion can be accomplished with a type cast. For more information, see [Type-Cast Conversions](../c-language/type-cast-conversions.md). -The *type-qualifier* can be either **`const`** or **`volatile`**, or both. These specify, respectively, that the pointer cannot be modified by the program itself (**`const`**), or that the pointer can legitimately be modified by some process beyond the control of the program (**`volatile`**). (See [Type Qualifiers](../c-language/type-qualifiers.md) for more information on **`const`** and **`volatile`**.) +The *`type-qualifier`* can be either **`const`** or **`volatile`**, or both. These keywords specify, respectively, that the pointer can't be modified by the program itself (**`const`**), or that the pointer can legitimately be modified by some process beyond the control of the program (**`volatile`**). For more information on **`const`** and **`volatile`**, see [Type Qualifiers](../c-language/type-qualifiers.md). -The *declarator* names the variable and can include a type modifier. For example, if *declarator* represents an array, the type of the pointer is modified to be a pointer to an array. +The *`declarator`* names the variable and can include a type modifier. For example, if *`declarator`* represents an array, the type of the pointer is modified to be a pointer to an array. -You can declare a pointer to a structure, union, or enumeration type before you define the structure, union, or enumeration type. You declare the pointer by using the structure or union tag as shown in the examples below. Such declarations are allowed because the compiler does not need to know the size of the structure or union to allocate space for the pointer variable. +You can declare a pointer to a structure, union, or enumeration type before you define the structure, union, or enumeration type. You declare the pointer by using the structure or union tag as shown in the examples. Such declarations are allowed because the compiler doesn't need to know the size of the structure or union to allocate space for the pointer variable. ## Examples The following examples illustrate pointer declarations. -``` +```c char *message; /* Declares a pointer variable named message */ ``` -The *message* pointer points to a variable with **`char`** type. +The `message` pointer points to a variable with **`char`** type. -``` +```c int *pointers[10]; /* Declares an array of pointers */ ``` -The *pointers* array has 10 elements; each element is a pointer to a variable with **`int`** type. +The `pointers` array has 10 elements; each element is a pointer to a variable with **`int`** type. -``` +```c int (*pointer)[10]; /* Declares a pointer to an array of 10 elements */ ``` -The *pointer* variable points to an array with 10 elements. Each element in this array has **`int`** type. +The `pointer` variable points to an array with 10 elements. Each element in this array has **`int`** type. -``` +```c int const *x; /* Declares a pointer variable, x, to a constant value */ ``` -The pointer *x* can be modified to point to a different **`int`** value, but the value to which it points cannot be modified. +The pointer `x` can be modified to point to a different **`int`** value, but the value to which it points can't be modified. -``` +```c const int some_object = 5 ; int other_object = 37; int *const y = &fixed_object; @@ -76,15 +76,15 @@ int volatile *const z = &some_object; int *const volatile w = &some_object; ``` -The variable *y* in these declarations is declared as a constant pointer to an **`int`** value. The value it points to can be modified, but the pointer itself must always point to the same location: the address of *fixed_object*. Similarly, *z* is a constant pointer, but it is also declared to point to an **`int`** whose value cannot be modified by the program. The additional specifier **`volatile`** indicates that although the value of the **const int** pointed to by *z* cannot be modified by the program, it could legitimately be modified by a process running concurrently with the program. The declaration of *w* specifies that the program cannot change the value pointed to and that the program cannot modify the pointer. +The variable `y` in these declarations is declared as a constant pointer to an **`int`** value. The value it points to can be modified, but the pointer itself must always point to the same location: the address of `fixed_object`. Similarly, `z` is a constant pointer, but it's also declared to point to an **`int`** whose value can't be modified by the program. The **`volatile`** specifier indicates that although the value of the `const int` pointed to by `z` can't be modified by the program, it could legitimately be modified by a process running concurrently with the program. The declaration of `w` specifies that the program can't change the value pointed to and that the program can't modify the pointer. -``` +```c struct list *next, *previous; /* Uses the tag for list */ ``` -This example declares two pointer variables, *next* and *previous*, that point to the structure type *list*. This declaration can appear before the definition of the *list* structure type (see the next example), as long as the *list* type definition has the same visibility as the declaration. +This example declares two pointer variables (`next` and `previous`) that point to the structure type `list`. This declaration can appear before the definition of the `list` structure type (see the next example), as long as the `list` type definition has the same visibility as the declaration. -``` +```c struct list { char *token; @@ -93,9 +93,9 @@ struct list } line; ``` -The variable *line* has the structure type named *list*. The *list* structure type has three members: the first member is a pointer to a **`char`** value, the second is an **`int`** value, and the third is a pointer to another *list* structure. +The variable `line` has the structure type named `list`. The `list` structure type has three members: the first member is a pointer to a **`char`** value, the second is an **`int`** value, and the third is a pointer to another `list` structure. -``` +```c struct id { unsigned int id_no; @@ -103,7 +103,7 @@ struct id } record; ``` -The variable *record* has the structure type *id*. Note that *pname* is declared as a pointer to another structure type named *name*. This declaration can appear before the *name* type is defined. +The variable `record` has the structure type `id`. `pname` is declared as a pointer to another structure type named `name`. This declaration can appear before the `name` type is defined. ## See also diff --git a/docs/c-language/postfix-operators.md b/docs/c-language/postfix-operators.md index a862e10827..9f2aa68269 100644 --- a/docs/c-language/postfix-operators.md +++ b/docs/c-language/postfix-operators.md @@ -11,14 +11,14 @@ The postfix operators have the highest precedence (the tightest binding) in expr ## Syntax -*postfix-expression*:
-    *primary-expression*
-    *postfix-expression* **[** *expression* **]**
-    *postfix-expression* **(** *argument-expression-list*opt **)**
-    *postfix-expression* **.** *identifier*
-    *postfix-expression* **->** *identifier*
-    *postfix-expression* **++**
-    *postfix-expression* **--** +*`postfix-expression`*:\ + *`primary-expression`*\ + *`postfix-expression`* **`[`** *`expression`* **`]`**\ + *`postfix-expression`* **`(`** *`argument-expression-list`*opt **`)`**\ + *`postfix-expression`* **`.`** *`identifier`*\ + *`postfix-expression`* **`->`** *`identifier`*\ + *`postfix-expression`* **`++`**\ + *`postfix-expression`* **`--`** Operators in this precedence level are the array subscripts, function calls, structure and union members, and postfix increment and decrement operators. diff --git a/docs/c-language/return-statement-c.md b/docs/c-language/return-statement-c.md index 57eb60e450..e5f0d686d0 100644 --- a/docs/c-language/return-statement-c.md +++ b/docs/c-language/return-statement-c.md @@ -5,22 +5,22 @@ ms.date: "06/10/2020" helpviewer_keywords: ["( ) parentheses in return statements"] ms.assetid: 18cd82cf-f899-4b28-83ad-4eff353ddcb4 --- -# return Statement (C) +# `return` Statement (C) A **`return`** statement ends the execution of a function, and returns control to the calling function. Execution resumes in the calling function at the point immediately following the call. A **`return`** statement can return a value to the calling function. For more information, see [Return type](../c-language/return-type.md). ## Syntax -> *jump-statement*:\ ->     **`return`** *expression*opt **`;`** +> *`jump-statement`*:\ +>  **`return`** *`expression`*opt **`;`** -The value of *expression*, if present, is returned to the calling function. If *expression* is omitted, the return value of the function is undefined. The expression, if present, is evaluated and then converted to the type returned by the function. When a **`return`** statement contains an expression in functions that have a **`void`** return type, the compiler generates a warning, and the expression isn't evaluated. +The value of *`expression`*, if present, is returned to the calling function. If *`expression`* is omitted, the return value of the function is undefined. The expression, if present, is evaluated and then converted to the type returned by the function. When a **`return`** statement contains an expression in functions that have a **`void`** return type, the compiler generates a warning, and the expression isn't evaluated. If no **`return`** statement appears in a function definition, control automatically returns to the calling function after the last statement of the called function is executed. In this case, the return value of the called function is undefined. If the function has a return type other than **`void`**, it's a serious bug, and the compiler prints a warning diagnostic message. If the function has a **`void`** return type, this behavior is okay, but may be considered poor style. Use a plain **`return`** statement to make your intent clear. As a good engineering practice, always specify a return type for your functions. If a return value isn't required, declare the function to have **`void`** return type. If a return type isn't specified, the C compiler assumes a default return type of **`int`**. -Many programmers use parentheses to enclose the *expression* argument of the **`return`** statement. However, C doesn't require the parentheses. +Many programmers use parentheses to enclose the *`expression`* argument of the **`return`** statement. However, C doesn't require the parentheses. The compiler may issue a warning diagnostic message about unreachable code if it finds any statements placed after the **`return`** statement. diff --git a/docs/c-language/return-type.md b/docs/c-language/return-type.md index 05297d66d1..653e79678b 100644 --- a/docs/c-language/return-type.md +++ b/docs/c-language/return-type.md @@ -7,41 +7,43 @@ ms.assetid: 3e5b8a97-b341-48c5-8be8-8986980ef586 --- # Return Type -The return type of a function establishes the size and type of the value returned by the function and corresponds to the type-specifier in the syntax below: +The return type of a function establishes the size and type of the value returned by the function. It corresponds to the *`type-specifier`* in the Syntax section: ## Syntax -*function-definition*:
-    *declaration-specifiers*opt *attribute-seq*opt *declarator* *declaration-list*opt *compound-statement* - -/\* *attribute-seq* is Microsoft-specific \*/ - -*declaration-specifiers*:
-    *storage-class-specifier* *declaration-specifiers*opt
-    *type-specifier* *declaration-specifiers*opt
-    *type-qualifier* *declaration-specifiers*opt - -*type-specifier*:
-    **`void`**
-    **`char`**
-    **`short`**
-    **`int`**
-    **`__int8`** /\* Microsoft-specific \*/
-    **`__int16`** /\* Microsoft-specific \*/
-    **`__int32`** /\* Microsoft-specific \*/
-    **`__int64`** /\* Microsoft-specific \*/
-    **`long`**
-    **`float`**
-    **`double`**
-    **`signed`**
-    **`unsigned`**
-    *struct-or-union-specifier*
-    *enum-specifier*
-    *typedef-name* - -The *type-specifier* can specify any fundamental, structure, or union type. If you do not include *type-specifier*, the return type **`int`** is assumed. - -The return type given in the function definition must match the return type in declarations of the function elsewhere in the program. A function returns a value when a **`return`** statement containing an expression is executed. The expression is evaluated, converted to the return value type if necessary, and returned to the point at which the function was called. If a function is declared with return type **`void`**, a return statement containing an expression generates a warning and the expression is not evaluated. +*`function-definition`*:\ + *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* + +/\* *`attribute-seq`* is Microsoft-specific \*/ + +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt\ + *`type-specifier`* *`declaration-specifiers`*opt\ + *`type-qualifier`* *`declaration-specifiers`*opt + +*`type-specifier`*:\ + **`void`**\ + **`char`**\ + **`short`**\ + **`int`**\ + **`__int8`** /\* Microsoft-specific \*/\ + **`__int16`** /\* Microsoft-specific \*/\ + **`__int32`** /\* Microsoft-specific \*/\ + **`__int64`** /\* Microsoft-specific \*/\ + **`long`**\ + **`long long`**\ + **`float`**\ + **`double`**\ + **`long double`**\ + **`signed`**\ + **`unsigned`**\ + *`struct-or-union-specifier`*\ + *`enum-specifier`*\ + *`typedef-name`* + +The *`type-specifier`* can specify any fundamental, structure, or union type. + +The return type given in the function definition must match the return type in declarations of the function elsewhere in the program. A function returns a value when a **`return`** statement containing an expression is executed. The expression is evaluated, converted to the return value type if necessary, and returned to the point at which the function was called. If a function is declared with return type **`void`**, a return statement containing an expression generates a warning, and the expression isn't evaluated. The following examples illustrate function return values. diff --git a/docs/c-language/scope-and-visibility.md b/docs/c-language/scope-and-visibility.md index 179defafeb..72e07ffd0f 100644 --- a/docs/c-language/scope-and-visibility.md +++ b/docs/c-language/scope-and-visibility.md @@ -11,16 +11,16 @@ An identifier's "visibility" determines the portions of the program in which it All identifiers except labels have their scope determined by the level at which the declaration occurs. The following rules for each kind of scope govern the visibility of identifiers within a program: -File scope +**File scope**\ The declarator or type specifier for an identifier with file scope appears outside any block or list of parameters and is accessible from any place in the translation unit after its declaration. Identifier names with file scope are often called "global" or "external." The scope of a global identifier begins at the point of its definition or declaration and terminates at the end of the translation unit. -Function scope +**Function scope**\ A label is the only kind of identifier that has function scope. A label is declared implicitly by its use in a statement. Label names must be unique within a function. (For more information about labels and label names, see [The goto and Labeled Statements](../c-language/goto-and-labeled-statements-c.md).) -Block scope +**Block scope**\ The declarator or type specifier for an identifier with block scope appears inside a block or within the list of formal parameter declarations in a function definition. It is visible only from the point of its declaration or definition to the end of the block containing its declaration or definition. Its scope is limited to that block and to any blocks nested in that block and ends at the curly brace that closes the associated block. Such identifiers are sometimes called "local variables." -Function-prototype scope +**Function-prototype scope**\ The declarator or type specifier for an identifier with function-prototype scope appears within the list of parameter declarations in a function prototype (not part of the function declaration). Its scope terminates at the end of the function declarator. The appropriate declarations for making variables visible in other source files are described in [Storage Classes](../c-language/c-storage-classes.md). However, variables and functions declared at the external level with the **`static`** storage-class specifier are visible only within the source file in which they are defined. All other functions are globally visible. diff --git a/docs/c-language/sequential-evaluation-operator.md b/docs/c-language/sequential-evaluation-operator.md index 5860fb88f2..992ccf4363 100644 --- a/docs/c-language/sequential-evaluation-operator.md +++ b/docs/c-language/sequential-evaluation-operator.md @@ -11,27 +11,27 @@ The sequential-evaluation operator, also called the "comma operator," evaluates ## Syntax -*expression*:
-    *assignment-expression*
-    *expression* **,** *assignment-expression* +*`expression`*:\ + *`assignment-expression`*\ + *`expression`* **`,`** *`assignment-expression`* -The left operand of the sequential-evaluation operator is evaluated as a **`void`** expression. The result of the operation has the same value and type as the right operand. Each operand can be of any type. The sequential-evaluation operator does not perform type conversions between its operands, and it does not yield an l-value. There is a sequence point after the first operand, which means all side effects from the evaluation of the left operand are completed before beginning evaluation of the right operand. See [Sequence Points](../c-language/c-sequence-points.md) for more information. +The left operand of the sequential-evaluation operator (**`,`**) is evaluated as a **`void`** expression. The result of the operation has the same value and type as the right operand. Each operand can be of any type. The sequential-evaluation operator doesn't perform type conversions between its operands, and it doesn't yield an l-value. There's a sequence point after the first operand, which means all side effects from the evaluation of the left operand are completed before beginning evaluation of the right operand. For more information, see [Sequence Points](../c-language/c-sequence-points.md). The sequential-evaluation operator is typically used to evaluate two or more expressions in contexts where only one expression is allowed. -Commas can be used as separators in some contexts. However, you must be careful not to confuse the use of the comma as a separator with its use as an operator; the two uses are completely different. +Commas can be used as separators in some contexts. However, you must be careful not to confuse the use of the comma as a separator with its use as an operator; the two uses are distinct. ## Example This example illustrates the sequential-evaluation operator: -``` +```c for ( i = j = 1; i + j < 20; i += i, j-- ); ``` In this example, each operand of the **`for`** statement's third expression is evaluated independently. The left operand `i += i` is evaluated first; then the right operand, `j--`, is evaluated. -``` +```c func_one( x, y + 2, z ); func_two( (x--, y + 2), z ); ``` diff --git a/docs/c-language/simple-variable-declarations.md b/docs/c-language/simple-variable-declarations.md index daaa215883..895313b298 100644 --- a/docs/c-language/simple-variable-declarations.md +++ b/docs/c-language/simple-variable-declarations.md @@ -13,27 +13,27 @@ Storage classes or types (or both) are required on variable declarations. Untype ## Syntax -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*:
-    *identifier* +*`direct-declarator`*:\ + *`identifier`* -*identifier*:
-    *nondigit*
-    *identifier* *nondigit*
-    *identifier* *digit* +*`identifier`*:\ + *`nondigit`*\ + *`identifier`* *`nondigit`*\ + *`identifier`* *`digit`* For arithmetic, structure, union, enumerations, and void types, and for types represented by **`typedef`** names, simple declarators can be used in a declaration since the type specifier supplies all the typing information. Pointer, array, and function types require more complicated declarators. -You can use a list of identifiers separated by commas (**,**) to specify several variables in the same declaration. All variables defined in the declaration have the same base type. For example: +You can use a list of identifiers separated by commas (**`,`**) to specify several variables in the same declaration. All variables defined in the declaration have the same base type. For example: ```C int x, y; /* Declares two simple variables of type int */ int const z = 1; /* Declares a constant value of type int */ ``` -The variables `x` and `y` can hold any value in the set defined by the **`int`** type for a particular implementation. The simple object `z` is initialized to the value 1 and is not modifiable. +The variables `x` and `y` can hold any value in the set defined by the **`int`** type for a particular implementation. The simple object `z` is initialized to the value 1 and isn't modifiable. If the declaration of `z` was for an uninitialized static variable or was at file scope, it would receive an initial value of 0, and that value would be unmodifiable. diff --git a/docs/c-language/source-files-and-source-programs.md b/docs/c-language/source-files-and-source-programs.md index 225e7f01e5..240db4af66 100644 --- a/docs/c-language/source-files-and-source-programs.md +++ b/docs/c-language/source-files-and-source-programs.md @@ -11,13 +11,13 @@ A source program can be divided into one or more "source files," or "translation ## Syntax -*translation-unit*:
-    *external-declaration*
-    *translation-unit* *external-declaration* +*`translation-unit`*:\ + *`external-declaration`* \ + *`translation-unit`* *`external-declaration`* -*external-declaration*:
-    *function-definition*
-    *declaration* +*`external-declaration`*:\ + *`function-definition`*\ + *`declaration`* [Overview of Declarations](../c-language/overview-of-declarations.md) gives the syntax for the `declaration` nonterminal, and the *Preprocessor Reference* explains how the [translation unit](../preprocessor/phases-of-translation.md) is processed. @@ -26,9 +26,9 @@ A source program can be divided into one or more "source files," or "translation The components of a translation unit are external declarations that include function definitions and identifier declarations. These declarations and definitions can be in source files, header files, libraries, and other files the program needs. You must compile each translation unit and link the resulting object files to make a program. -A C "source program" is a collection of directives, pragmas, declarations, definitions, statement blocks, and functions. To be valid components of a Microsoft C program, each must have the syntax described in this book, although they can appear in any order in the program (subject to the rules outlined throughout this book). However, the location of these components in a program does affect how variables and functions can be used in a program. (See [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md) for more information.) +A C "source program" is a collection of directives, pragmas, declarations, definitions, statement blocks, and functions. To be valid components of a Microsoft C program, each must have the syntax described in this book, although they can appear in any order in the program (subject to the rules outlined throughout this book). However, the location of these components in a program does affect how variables and functions can be used in a program. For more information, see [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md). -Source files need not contain executable statements. For example, you may find it useful to place definitions of variables in one source file and then declare references to these variables in other source files that use them. This technique makes the definitions easy to find and update when necessary. For the same reason, constants and macros are often organized into separate files called "include files" or "header files" that can be referenced in source files as required. See the *Preprocessor Reference* for information about [macros](../preprocessor/macros-c-cpp.md) and [include files](../preprocessor/hash-include-directive-c-cpp.md). +Source files don't have to contain executable statements. For example, you may find it useful to place definitions of variables in one source file and then declare references to these variables in other source files that use them. This technique makes the definitions easy to find and update when necessary. For the same reason, constants and macros are often organized into separate files called "include files" or "header files" that can be referenced in source files as required. See the *Preprocessor Reference* for information about [macros](../preprocessor/macros-c-cpp.md) and [include files](../preprocessor/hash-include-directive-c-cpp.md). ## See also diff --git a/docs/c-language/static-assert-c.md b/docs/c-language/static-assert-c.md index dc8ab22981..0890f6594b 100644 --- a/docs/c-language/static-assert-c.md +++ b/docs/c-language/static-assert-c.md @@ -78,5 +78,5 @@ Windows SDK 10.0.20348.0 (version 2104) or later. For more information on instal ## See also [`_STATIC_ASSERT` Macro](../c-runtime-library/reference/static-assert-macro.md)\ -[`assert` macro and `_assert` and `_wassert` functions](../c-runtime-library/reference/assert-macro-assert-wassert.md) +[`assert` macro and `_assert` and `_wassert` functions](../c-runtime-library/reference/assert-macro-assert-wassert.md)\ [`/std` (Specify language standard version)](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/c-language/storage-and-alignment-of-structures.md b/docs/c-language/storage-and-alignment-of-structures.md index 1032e70a32..e48c280822 100644 --- a/docs/c-language/storage-and-alignment-of-structures.md +++ b/docs/c-language/storage-and-alignment-of-structures.md @@ -27,7 +27,7 @@ where *n* is the packing size expressed with the /Zp[*n*] option and *item* is t To use the `pack` pragma to specify packing other than the packing specified on the command line for a particular structure, give the `pack` pragma, where the packing size is 1, 2, 4, 8, or 16, before the structure. To reinstate the packing given on the command line, specify the `pack` pragma with no arguments. -Bit fields default to size **`long`** for the Microsoft C compiler. Structure members are aligned on the size of the type or the /Zp[*n*] size, whichever is smaller. The default size is 4. +For the Microsoft C compiler, bit fields default to a size of 4 bytes, which is a **`long`** data type. Structure members are aligned on the size of the type or the /Zp[*n*] size, whichever is smaller. **END Microsoft Specific** diff --git a/docs/c-language/storage-class-specifiers-for-external-level-declarations.md b/docs/c-language/storage-class-specifiers-for-external-level-declarations.md index 7eb9b1d56b..c4b93d2c53 100644 --- a/docs/c-language/storage-class-specifiers-for-external-level-declarations.md +++ b/docs/c-language/storage-class-specifiers-for-external-level-declarations.md @@ -51,6 +51,7 @@ The example below illustrates external declarations: #include extern int i; // Reference to i, defined below +extern void other ( void ); // Reference to other(), defined in second source file void next( void ); // Function prototype int main() diff --git a/docs/c-language/storage-class.md b/docs/c-language/storage-class.md index 21c75e6b9c..273a8e7977 100644 --- a/docs/c-language/storage-class.md +++ b/docs/c-language/storage-class.md @@ -11,33 +11,33 @@ The storage-class specifier in a function definition gives the function either * ## Syntax -*function-definition*:
-    *declaration-specifiers*opt *attribute-seq*opt *declarator* *declaration-list*opt *compound-statement* +*`function-definition`*:\ + *`declaration-specifiers`*opt *`attribute-seq`*opt *`declarator`* *`declaration-list`*opt *`compound-statement`* -/\* *attribute-seq* is Microsoft-specific \*/ +/\* *`attribute-seq`* is Microsoft-specific \*/ -*declaration-specifiers*:
-    *storage-class-specifier* *declaration-specifiers*opt
-    *type-specifier* *declaration-specifiers*opt
-    *type-qualifier* *declaration-specifiers*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt\ + *`type-specifier`* *`declaration-specifiers`*opt\ + *`type-qualifier`* *`declaration-specifiers`*opt -*storage-class-specifier*: /\* For function definitions \*/
-    **`extern`**
-    **`static`** +*`storage-class-specifier`*: /\* For function definitions \*/\ + **`extern`**\ + **`static`** -If a function definition does not include a *storage-class-specifier*, the storage class defaults to **`extern`**. You can explicitly declare a function as **`extern`**, but it is not required. +If a function definition doesn't include a *`storage-class-specifier`*, the storage class defaults to **`extern`**. You can explicitly declare a function as **`extern`**, but it isn't required. -If the declaration of a function contains the *storage-class-specifier* **`extern`**, the identifier has the same linkage as any visible declaration of the identifier with file scope. If there is no visible declaration with file scope, the identifier has external linkage. If an identifier has file scope and no *storage-class-specifier*, the identifier has external linkage. External linkage means that each instance of the identifier denotes the same object or function. See [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md) for more information about linkage and file scope. +If the declaration of a function contains the *`storage-class-specifier`* **`extern`**, the identifier has the same linkage as any visible declaration of the identifier with file scope. If there's no visible declaration with file scope, the identifier has external linkage. If an identifier has file scope and no *`storage-class-specifier`*, the identifier has external linkage. External linkage means that each instance of the identifier denotes the same object or function. For more information about linkage and file scope, see [Lifetime, Scope, Visibility, and Linkage](../c-language/lifetime-scope-visibility-and-linkage.md). Block-scope function declarations with a storage-class specifier other than **`extern`** generate errors. -A function with **`static`** storage class is visible only in the source file in which it is defined. All other functions, whether they are given **`extern`** storage class explicitly or implicitly, are visible throughout all source files in the program. If **`static`** storage class is desired, it must be declared on the first occurrence of a declaration (if any) of the function, and on the definition of the function. +A function with **`static`** storage class is visible only in the source file in which it's defined. All other functions, whether they're given **`extern`** storage class explicitly or implicitly, are visible throughout all source files in the program. If **`static`** storage class is desired, it must be declared on the first occurrence of a declaration (if any) of the function, and on the definition of the function. **Microsoft Specific** When the Microsoft extensions are enabled, a function originally declared without a storage class (or with **`extern`** storage class) is given **`static`** storage class if the function definition is in the same source file and if the definition explicitly specifies **`static`** storage class. -When compiling with the /Ze compiler option, functions declared within a block using the **`extern`** keyword have global visibility. This is not true when compiling with /Za. This feature should not be relied upon if portability of source code is a consideration. +When compiled with the /Ze compiler option, functions declared within a block using the **`extern`** keyword have global visibility, which isn't true when compiling with /Za. This feature shouldn't be relied upon if portability of source code is a consideration. **END Microsoft Specific** diff --git a/docs/c-language/structure-and-union-members.md b/docs/c-language/structure-and-union-members.md index 98fbb1ef45..3660b1788f 100644 --- a/docs/c-language/structure-and-union-members.md +++ b/docs/c-language/structure-and-union-members.md @@ -9,36 +9,36 @@ ms.assetid: bb1fe304-af49-4f98-808d-afdc99b3e319 A "member-selection expression" refers to members of structures and unions. Such an expression has the value and type of the selected member. -> *postfix-expression* **.** *identifier*\ -> *postfix-expression* **->** *identifier* +> *`postfix-expression`* **`.`** *`identifier`*\ +> *`postfix-expression`* **`->`** *`identifier`* This list describes the two forms of the member-selection expressions: -1. In the first form, *postfix-expression* represents a value of **`struct`** or **`union`** type, and *identifier* names a member of the specified structure or union. The value of the operation is that of *identifier* and is an l-value if *postfix-expression* is an l-value. See [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md) for more information. +1. In the first form, *`postfix-expression`* represents a value of **`struct`** or **`union`** type, and *`identifier`* names a member of the specified structure or union. The value of the operation is that of *`identifier`* and is an l-value if *`postfix-expression`* is an l-value. For more information, see [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md). -1. In the second form, *postfix-expression* represents a pointer to a structure or union, and *identifier* names a member of the specified structure or union. The value is that of *identifier* and is an l-value. +1. In the second form, *`postfix-expression`* represents a pointer to a structure or union, and *`identifier`* names a member of the specified structure or union. The value is that of *`identifier`* and is an l-value. The two forms of member-selection expressions have similar effects. -In fact, an expression involving the member-selection operator (**->**) is a shorthand version of an expression using the period (**.**) if the expression before the period consists of the indirection operator (\*) applied to a pointer value. Therefore, +In fact, an expression involving the member-selection operator (**`->`**) is a shorthand version of an expression using the period (**`.`**) if the expression before the period consists of the indirection operator (**`*`**) applied to a pointer value. Therefore, -```cpp +```c expression->identifier ``` is equivalent to -```cpp +```c (*expression).identifier ``` -when *expression* is a pointer value. +when `expression` is a pointer value. ## Examples -The following examples refer to this structure declaration. For information about the indirection operator (\*) used in these examples, see [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md). +The following examples refer to this structure declaration. For information about the indirection operator (**`*`**) used in these examples, see [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md). -``` +```c struct pair { int a; @@ -49,19 +49,19 @@ struct pair A member-selection expression for the `item` structure looks like this: -``` +```c item.sp = &item; ``` -In the example above, the address of the `item` structure is assigned to the `sp` member of the structure. This means that `item` contains a pointer to itself. +In the example, the address of the `item` structure is assigned to the `sp` member of the structure. It means that `item` contains a pointer to itself. -``` +```c (item.sp)->a = 24; ``` -In this example, the pointer expression `item.sp` is used with the member-selection operator (**->**) to assign a value to the member `a`. +In this example, the pointer expression `item.sp` is used with the member-selection operator (**`->`**) to assign a value to the member `a`. -``` +```c list[8].b = 12; ``` diff --git a/docs/c-language/structure-declarations.md b/docs/c-language/structure-declarations.md index a1b6811b90..e0bc7d5492 100644 --- a/docs/c-language/structure-declarations.md +++ b/docs/c-language/structure-declarations.md @@ -11,45 +11,45 @@ A "structure declaration" names a type and specifies a sequence of variable valu ## Syntax -*struct-or-union-specifier*:
-    *struct-or-union* *identifier*opt **{** *struct-declaration-list* **}**
-    *struct-or-union* *identifier* +*`struct-or-union-specifier`*:\ + *`struct-or-union`* *`identifier`*opt **`{`** *`struct-declaration-list`* **`}`**\ + *`struct-or-union`* *`identifier`* -*struct-or-union*:
-    **`struct`**
-    **`union`** +*`struct-or-union`*:\ + **`struct`**\ + **`union`** -*struct-declaration-list*:
-    *struct-declaration*
-    *struct-declaration-list* *struct-declaration* +*`struct-declaration-list`*:\ + *`struct-declaration`*\ + *`struct-declaration-list`* *`struct-declaration`* -*struct-declaration*:
-    *specifier-qualifier-list* *struct-declarator-list* **;** +*`struct-declaration`*:\ + *`specifier-qualifier-list`* *`struct-declarator-list`* **`;`** -*specifier-qualifier-list*:
-    *type-specifier* *specifier-qualifier-list*opt
-    *type-qualifier* *specifier-qualifier-list*opt +*`specifier-qualifier-list`*:\ + *`type-specifier`* *`specifier-qualifier-list`*opt\ + *`type-qualifier`* *`specifier-qualifier-list`*opt -*struct-declarator-list*:
-    *struct-declarator* *struct-declarator-list* **,** *struct-declarator* +*`struct-declarator-list`*:\ + *`struct-declarator`* *`struct-declarator-list`* **`,`** *`struct-declarator`* -*struct-declarator*:
-    *declarator*
-    *type-specifier* *declarator*opt **:** *constant-expression* +*`struct-declarator`*:\ + *`declarator`*\ + *`type-specifier`* *`declarator`*opt **`:`** *`constant-expression`* -The declaration of a structure type does not set aside space for a structure. It is only a template for later declarations of structure variables. +The declaration of a structure type doesn't set aside space for a structure. It's only a template for later declarations of structure variables. -A previously defined *identifier* (tag) can be used to refer to a structure type defined elsewhere. In this case, *struct-declaration-list* cannot be repeated as long as the definition is visible. Declarations of pointers to structures and typedefs for structure types can use the structure tag before the structure type is defined. However, the structure definition must be encountered prior to any actual use of the size of the fields. This is an incomplete definition of the type and the type tag. For this definition to be completed, a type definition must appear later in the same scope. +A previously defined *`identifier`* (tag) can be used to refer to a structure type defined elsewhere. In this case, *`struct-declaration-list`* can't be repeated as long as the definition is visible. Declarations of pointers to structures and typedefs for structure types can use the structure tag before the structure type is defined. However, the structure definition must be encountered prior to any actual use of the size of the fields. This use is an incomplete definition of the type and the type tag. For this definition to be completed, a type definition must appear later in the same scope. -The *struct-declaration-list* specifies the types and names of the structure members. A *struct-declaration-list* argument contains one or more variable or bit-field declarations. +The *`struct-declaration-list`* specifies the types and names of the structure members. A *`struct-declaration-list`* argument contains one or more variable or bit-field declarations. -Each variable declared in *struct-declaration-list* is defined as a member of the structure type. Variable declarations within *struct-declaration-list* have the same form as other variable declarations discussed in this section, except that the declarations cannot contain storage-class specifiers or initializers. The structure members can have any variable types except type **`void`**, an incomplete type, or a function type. +Each variable declared in *`struct-declaration-list`* is defined as a member of the structure type. Variable declarations within *`struct-declaration-list`* have the same form as other variable declarations discussed in this section, except that the declarations can't contain storage-class specifiers or initializers. The structure members can have any variable types except type **`void`**, an incomplete type, or a function type. -A member cannot be declared to have the type of the structure in which it appears. However, a member can be declared as a pointer to the structure type in which it appears as long as the structure type has a tag. This allows you to create linked lists of structures. +A member can't be declared to have the type of the structure in which it appears. However, a member can be declared as a pointer to the structure type in which it appears as long as the structure type has a tag. It allows you to create linked lists of structures. Structures follow the same scoping as other identifiers. Structure identifiers must be distinct from other structure, union, and enumeration tags with the same visibility. -Each *struct-declaration* in a *struct-declaration-list* must be unique within the list. However, identifier names in a *struct-declaration-list* do not have to be distinct from ordinary variable names or from identifiers in other structure declaration lists. +Each *`struct-declaration`* in a *`struct-declaration-list`* must be unique within the list. However, identifier names in a *`struct-declaration-list`* don't have to be distinct from ordinary variable names or from identifiers in other structure declaration lists. Nested structures can also be accessed as though they were declared at the file-scope level. For example, given this declaration: @@ -112,7 +112,7 @@ struct sample /* Defines a structure named x */ The first two members of the structure are a **`char`** variable and a pointer to a **`float`** value. The third member, `next`, is declared as a pointer to the structure type being defined (`sample`). -Anonymous structures can be useful when the tag named is not needed. This is the case when one declaration defines all structure instances. For example: +Anonymous structures can be useful when the tag name isn't needed, such as when one declaration defines all structure instances. For example: ```C struct @@ -137,13 +137,13 @@ struct somestruct **Microsoft Specific** -The compiler allows an unsized or zero-sized array as the last member of a structure. This can be useful if the size of a constant array differs when used in various situations. The declaration of such a structure looks like this: +The compiler allows an unsized or zero-sized array as the last member of a structure. It's useful if the size of a constant array differs when used in various situations. The declaration of such a structure looks like this: -**`struct`** *identifier* **{** *set-of-declarations* *type* array-name**\[]; };** +**`struct`** *`identifier`* **`{`** *`set-of-declarations`* *`type`* *`array-name`* **`[]; };`** -Unsized arrays can appear only as the last member of a structure. Structures containing unsized array declarations can be nested within other structures as long as no further members are declared in any enclosing structures. Arrays of such structures are not allowed. The **`sizeof`** operator, when applied to a variable of this type or to the type itself, assumes 0 for the size of the array. +Unsized arrays can appear only as the last member of a structure. Structures containing unsized array declarations can be nested within other structures as long as no further members are declared in any enclosing structures. Arrays of such structures aren't allowed. The **`sizeof`** operator, when applied to a variable of this type or to the type itself, assumes 0 for the size of the array. -Structure declarations can also be specified without a declarator when they are members of another structure or union. The field names are promoted into the enclosing structure. For example, a nameless structure looks like this: +Structure declarations can also be specified without a declarator when they're members of another structure or union. The field names are promoted into the enclosing structure. For example, a nameless structure looks like this: ```C struct s @@ -161,7 +161,7 @@ struct s p_s->b = 100; /* A reference to a field in the s structure */ ``` -See [Structure and Union Members](../c-language/structure-and-union-members.md) for information about structure references. +For more information about structure references, see [Structure and Union Members](../c-language/structure-and-union-members.md). **END Microsoft Specific** diff --git a/docs/c-language/summary-of-declarations.md b/docs/c-language/summary-of-declarations.md index df8e11d520..117a5baaaa 100644 --- a/docs/c-language/summary-of-declarations.md +++ b/docs/c-language/summary-of-declarations.md @@ -4,7 +4,7 @@ description: "Learn about the standard C grammar for declarations as implemented ms.date: 10/30/2020 ms.assetid: 53a5e9e5-1a33-40b5-9dea-7f669b479329 --- -# Summary of Declarations +# Summary of declarations *`declaration`*:\  *`declaration-specifiers`* *`attribute-seq`*opt1 *`init-declarator-list`*opt **`;`**\ @@ -209,7 +209,7 @@ ms.assetid: 53a5e9e5-1a33-40b5-9dea-7f669b479329  **`_Static_assert`** **`(`** *`constant-expression`* **`,`** *`string-literal`* **`)`** **`;`** 1 This grammar element is Microsoft-specific.\ -2 For more information about these elements, see [`__asm`](../assembler/inline/asm.md), [`__clrcall`](../cpp/clrcall.md), [`__stdcall`](../cpp/stdcall.md), [`__based`](../cpp/based-grammar.md), [`__fastcall`](../cpp/fastcall.md), [`__thiscall`](../cpp/thiscall.md), [`__cdecl`](../cpp/cdecl.md), [`__inline`](../cpp/inline-functions-cpp.md), and [`__vectorcall`](../cpp/vectorcall.md). +2 For more information about these elements, see [`__asm`](../assembler/inline/asm.md), [`__clrcall`](../cpp/clrcall.md), [`__stdcall`](../cpp/stdcall.md), [`__based`](../cpp/based-grammar.md), [`__fastcall`](../cpp/fastcall.md), [`__thiscall`](../cpp/thiscall.md), [`__cdecl`](../cpp/cdecl.md), [`__inline`](../cpp/inline-functions-cpp.md), and [`__vectorcall`](../cpp/vectorcall.md).\ 3 This style is obsolete. ## See also diff --git a/docs/c-language/summary-of-statements.md b/docs/c-language/summary-of-statements.md index be4e226df0..6e6e98aa36 100644 --- a/docs/c-language/summary-of-statements.md +++ b/docs/c-language/summary-of-statements.md @@ -6,56 +6,56 @@ ms.assetid: ce45d2fe-ec0e-459f-afb1-80ab6a7f0239 --- # Summary of C statements -*`statement`*:
- *`labeled-statement`*
- *`compound-statement`*
- *`expression-statement`*
- *`selection-statement`*
- *`iteration-statement`*
- *`jump-statement`*
- *`try-except-statement`* /\* Microsoft-specific \*/
+*`statement`*:\ + *`labeled-statement`*\ + *`compound-statement`*\ + *`expression-statement`*\ + *`selection-statement`*\ + *`iteration-statement`*\ + *`jump-statement`*\ + *`try-except-statement`* /\* Microsoft-specific \*/\  *`try-finally-statement`* /\* Microsoft-specific \*/ -*`jump-statement`*:
- **`goto`** *`identifier`* **`;`**
- **`continue ;`**
- **`break ;`**
- **`return`** *`expression`*opt **`;`**
+*`jump-statement`*:\ + **`goto`** *`identifier`* **`;`**\ + **`continue ;`**\ + **`break ;`**\ + **`return`** *`expression`*opt **`;`**\  **`__leave ;`** /\* Microsoft-specific1 \*/ -*`compound-statement`*:
+*`compound-statement`*:\  **`{`** *`declaration-list`*opt *`statement-list`*opt **`}`** -*`declaration-list`*:
- *`declaration`*
+*`declaration-list`*:\ + *`declaration`*\  *`declaration-list`* *`declaration`* -*`statement-list`*:
- *`statement`*
+*`statement-list`*:\ + *`statement`*\  *`statement-list`* *`statement`* -*`expression-statement`*:
+*`expression-statement`*:\  *`expression`*opt **`;`** -*`iteration-statement`*:
- **`while (`** *`expression`* **`)`** *`statement`*
- **`do`** *`statement`* **`while (`** *`expression`* **`) ;`**
+*`iteration-statement`*:\ + **`while (`** *`expression`* **`)`** *`statement`*\ + **`do`** *`statement`* **`while (`** *`expression`* **`) ;`**\  **`for (`** *`expression`*opt **`;`** *`expression`*opt **`;`** *`expression`*opt **`)`** *`statement`* -*`selection-statement`*:
- **`if (`** *`expression`* **`)`** *`statement`*
- **`if (`** *`expression`* **`)`** *`statement`* **`else`** *`statement`*
+*`selection-statement`*:\ + **`if (`** *`expression`* **`)`** *`statement`*\ + **`if (`** *`expression`* **`)`** *`statement`* **`else`** *`statement`*\  **`switch (`** *`expression`* **`)`** *`statement`* -*`labeled-statement`*:
- *`identifier`* **`:`** *`statement`*
- **`case`** *`constant-expression`* **`:`** *`statement`*
+*`labeled-statement`*:\ + *`identifier`* **`:`** *`statement`*\ + **`case`** *`constant-expression`* **`:`** *`statement`*\  **`default :`** *`statement`* -*`try-except-statement`*: /\* Microsoft-specific \*/
+*`try-except-statement`*: /\* Microsoft-specific \*/\  **`__try`** *`compound-statement`* **`__except (`** *`expression`* **`)`** *`compound-statement`* -*`try-finally-statement`*: /\* Microsoft-specific \*/
+*`try-finally-statement`*: /\* Microsoft-specific \*/\  **`__try`** *`compound-statement`* **`__finally`** *`compound-statement`* 1 The **`__leave`** keyword is only valid within the **`__try`** block of a *`try-except-statement`* or a *`try-finally-statement`*. diff --git a/docs/c-language/switch-statement-c.md b/docs/c-language/switch-statement-c.md index 414efdeed7..8f9394ed80 100644 --- a/docs/c-language/switch-statement-c.md +++ b/docs/c-language/switch-statement-c.md @@ -13,12 +13,12 @@ The **`switch`** and **`case`** statements help control complex conditional and ## Syntax -> *`selection-statement`*:\ ->      **`switch (`** *`expression`*  **`)`** *`statement`* +*`selection-statement`*:\ +  **`switch (`** *`expression`* **`)`** *`statement`* -> *`labeled-statement`*:\ ->      **`case`** *`constant-expression`* **`:`** *`statement`*\ ->      **`default`** **`:`** *`statement`* +*`labeled-statement`*:\ +  **`case`** *`constant-expression`* **`:`** *`statement`*\ +  **`default`** **`:`** *`statement`* ## Remarks @@ -103,7 +103,7 @@ switch( c ) } ``` -In this example, if *constant-expression* equals any letter between `'a'` and `'f'`, the `convert_hex` function is called. +In this example, if *`constant-expression`* equals any letter between `'a'` and `'f'`, the `convert_hex` function is called. ### Microsoft-specific diff --git a/docs/c-language/system-function.md b/docs/c-language/system-function.md index 95609210cf..35ef3def66 100644 --- a/docs/c-language/system-function.md +++ b/docs/c-language/system-function.md @@ -9,9 +9,9 @@ ms.assetid: 0786ccdc-20cd-4d96-b3d8-3230507c3066 **ANSI 4.10.4.5** The contents and mode of execution of the string by the **system** function -The **system** function executes an internal operating system command, or an .EXE, .COM (.CMD in Windows NT) or .BAT file from within a C program rather than from the command line. +The **system** function executes an internal operating system command, or an .EXE, .COM, .CMD, or .BAT file from within a C program rather than from the command line. -The system function finds the command interpreter, which is typically CMD.EXE in the Windows NT operating system or COMMAND.COM in Windows. The system function then passes the argument string to the command interpreter. +The system function finds the command interpreter, which is typically CMD.EXE in the Windows operating system. The system function then passes the argument string to the command interpreter. For more information, see [system, _wsystem](../c-runtime-library/reference/system-wsystem.md). diff --git a/docs/c-language/toc.yml b/docs/c-language/toc.yml index bdec148f7a..cfd26f82ed 100644 --- a/docs/c-language/toc.yml +++ b/docs/c-language/toc.yml @@ -171,6 +171,10 @@ items: href: ../c-language/c-type-specifiers.md - name: Data type specifiers and equivalents href: ../c-language/data-type-specifiers-and-equivalents.md + - name: typeof + href: typeof-c.md + - name: typeof_unqual + href: typeof-unqual-c.md - name: Type qualifiers href: ../c-language/type-qualifiers.md - name: Declarators and variable declarations diff --git a/docs/c-language/type-cast-conversions.md b/docs/c-language/type-cast-conversions.md index 925ddeba36..f73cde27f3 100644 --- a/docs/c-language/type-cast-conversions.md +++ b/docs/c-language/type-cast-conversions.md @@ -9,39 +9,39 @@ ms.assetid: 57ab5902-f12f-4326-a2f6-6282f1d4025a You can use type casts to explicitly convert types. -**Syntax** +## Syntax -*cast-expression*:
-    *unary expression*
-    **(** *type-name* **)** *cast-expression* +*`cast-expression`*:\ + *`unary-expression`*\ + **`(`** *`type-name`* **`)`** *`cast-expression`* -*type-name*:
-    *specifier-qualifier-list* *abstract-declarator*opt +*`type-name`*:\ + *`specifier-qualifier-list`* *`abstract-declarator`*opt -The *type-name* is a type and *cast-expression* is a value to be converted to that type. An expression with a type cast is not an l-value. The *cast-expression* is converted as though it had been assigned to a variable of type *type-name*. The conversion rules for assignments (outlined in [Assignment Conversions](../c-language/assignment-conversions.md)) apply to type casts as well. The following table shows the types that can be cast to any given type. +The *`type-name`* is a type and *`cast-expression`* is a value to be converted to that type. An expression with a type cast isn't an l-value. The *`cast-expression`* is converted as though it had been assigned to a variable of type *`type-name`*. The conversion rules for assignments (outlined in [Assignment Conversions](../c-language/assignment-conversions.md)) apply to type casts as well. The following table shows the types that can be cast to any given type. -### Legal Type Casts +### Legal type casts -|Destination Types|Potential Sources| -|-----------------------|-----------------------| -|Integral types|Any integer type or floating-point type, or pointer to an object| -|Floating-point|Any arithmetic type| -|A pointer to an object, or (**`void`** \*)|Any integer type, (**`void`** \*), a pointer to an object, or a function pointer| -|Function pointer|Any integral type, a pointer to an object, or a function pointer| -|A structure, union, or array|None| -|Void type|Any type| +| Destination Types | Potential Sources | +|---|---| +| Integral types | Any integer type or floating-point type, or pointer to an object | +| Floating-point | Any arithmetic type | +| A pointer to an object, or `void *` | Any integer type, `void *`, a pointer to an object, or a function pointer | +| Function pointer | Any integral type, a pointer to an object, or a function pointer | +| A structure, union, or array | None | +| Void type | Any type | -Any identifier can be cast to **`void`** type. However, if the type specified in a type-cast expression is not **`void`**, then the identifier being cast to that type cannot be a **`void`** expression. Any expression can be cast to **`void`**, but an expression of type **`void`** cannot be cast to any other type. For example, a function with **`void`** return type cannot have its return cast to another type. +Any identifier can be cast to **`void`** type. However, if the type specified in a type-cast expression isn't **`void`**, then the identifier being cast to that type can't be a **`void`** expression. Any expression can be cast to **`void`**, but an expression of type **`void`** can't be cast to any other type. For example, a function with **`void`** return type can't have its return cast to another type. -Note that a **`void`** \* expression has a type pointer to **`void`**, not type **`void`**. If an object is cast to **`void`** type, the resulting expression cannot be assigned to any item. Similarly, a type-cast object is not an acceptable l-value, so no assignment can be made to a type-cast object. +A `void *` expression has a type pointer to **`void`**, not type **`void`**. If an object is cast to **`void`** type, the resulting expression can't be assigned to any item. Similarly, a type-cast object isn't an acceptable l-value, so no assignment can be made to a type-cast object. **Microsoft Specific** -A type cast can be an l-value expression as long as the size of the identifier does not change. For information on l-value expressions, see [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md). +A type cast can be an l-value expression as long as the size of the identifier doesn't change. For information on l-value expressions, see [L-Value and R-Value Expressions](../c-language/l-value-and-r-value-expressions.md). **END Microsoft Specific** -You can convert an expression to type **`void`** with a cast, but the resulting expression can be used only where a value is not required. An object pointer converted to **`void`** \* and back to the original type will return to its original value. +You can convert an expression to type **`void`** with a cast, but the resulting expression can be used only where a value isn't required. An object pointer converted to `void *` and back to the original type will return to its original value. ## See also diff --git a/docs/c-language/typedef-declarations.md b/docs/c-language/typedef-declarations.md index 898ab631bd..019f17fbdf 100644 --- a/docs/c-language/typedef-declarations.md +++ b/docs/c-language/typedef-declarations.md @@ -7,43 +7,43 @@ ms.assetid: e92a3b82-9269-4bc6-834a-6f431ccac83e --- # Typedef Declarations -A typedef declaration is a declaration with typedef as the storage class. The declarator becomes a new type. You can use typedef declarations to construct shorter or more meaningful names for types already defined by C or for types that you have declared. Typedef names allow you to encapsulate implementation details that may change. +A typedef declaration is a declaration with typedef as the storage class. The declarator becomes a new type. You can use typedef declarations to construct shorter or more meaningful names for types already defined by C or for types that you've declared. Typedef names allow you to encapsulate implementation details that may change. A typedef declaration is interpreted in the same way as a variable or function declaration, but the identifier, instead of assuming the type specified by the declaration, becomes a synonym for the type. ## Syntax -*declaration*:
-    *declaration-specifiers init-declarator-list*opt **;** +*`declaration`*:\ + *`declaration-specifiers`* *`init-declarator-list`*opt **`;`** -*declaration-specifiers*:
-    *storage-class-specifier declaration-specifiers*opt
-    *type-specifier declaration-specifiers*opt
-    *type-qualifier declaration-specifiers*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt\ + *`type-specifier`* *`declaration-specifiers`*opt\ + *`type-qualifier`* *`declaration-specifiers`*opt -*storage-class-specifier*:
-    **`typedef`** +*`storage-class-specifier`*:\ + **`typedef`** -*type-specifier*:
-    **`void`**
-    **`char`**
-    **`short`**
-    **`int`**
-    **`long`**
-    **`float`**
-    **`double`**
-    **`signed`**
-    **`unsigned`**
-    *struct-or-union-specifier*
-    *enum-specifier*
-    *typedef-name* +*`type-specifier`*:\ + **`void`**\ + **`char`**\ + **`short`**\ + **`int`**\ + **`long`**\ + **`float`**\ + **`double`**\ + **`signed`**\ + **`unsigned`**\ + *`struct-or-union-specifier`*\ + *`enum-specifier`*\ + *`typedef-name`* -*typedef-name*:
-    *identifier* +*`typedef-name`*:\ + *`identifier`* -Note that a typedef declaration does not create types. It creates synonyms for existing types, or names for types that could be specified in other ways. When a typedef name is used as a type specifier, it can be combined with certain type specifiers, but not others. Acceptable modifiers include **`const`** and **`volatile`**. +A typedef declaration doesn't create new types. It creates synonyms for existing types, or names for types that could be specified in other ways. When a typedef name is used as a type specifier, it can be combined with certain type specifiers, but not others. Acceptable modifiers include **`const`** and **`volatile`**. -Typedef names share the name space with ordinary identifiers (see [Name Spaces](../c-language/name-spaces.md) for more information). Therefore, a program can have a typedef name and a local-scope identifier by the same name. For example: +Typedef names share the name space with ordinary identifiers. (For more information, see [Name Spaces](../c-language/name-spaces.md).) Therefore, a program can have a typedef name and a local-scope identifier by the same name. For example: ```C typedef char FlagType; @@ -58,7 +58,7 @@ int myproc( int ) } ``` -When declaring a local-scope identifier by the same name as a typedef, or when declaring a member of a structure or union in the same scope or in an inner scope, the type specifier must be specified. This example illustrates this constraint: +When you declare a local-scope identifier by the same name as a typedef, or when you declare a member of a structure or union in the same scope or in an inner scope, you must also specify the type specifier. This example illustrates this constraint: ```C typedef char FlagType; @@ -71,7 +71,7 @@ To reuse the `FlagType` name for an identifier, a structure member, or a union m const int FlagType; /* Type specifier required */ ``` -It is not sufficient to say +It isn't sufficient to say ```C const FlagType; /* Incomplete specification */ @@ -83,7 +83,7 @@ because the `FlagType` is taken to be part of the type, not an identifier that i int; /* Illegal declaration */ ``` -You can declare any type with typedef, including pointer, function, and array types. You can declare a typedef name for a pointer to a structure or union type before you define the structure or union type, as long as the definition has the same visibility as the declaration. +You can declare any type with **`typedef`**, including pointer, function, and array types. You can declare a typedef name for a pointer to a structure or union type before you define the structure or union type, as long as the definition has the same visibility as the declaration. Typedef names can be used to improve code readability. All three of the following declarations of `signal` specify exactly the same type, the first without making use of any typedef names. @@ -103,7 +103,7 @@ The following examples illustrate typedef declarations: typedef int WHOLE; /* Declares WHOLE to be a synonym for int */ ``` -Note that `WHOLE` could now be used in a variable declaration such as `WHOLE i;` or `const WHOLE i;`. However, the declaration `long WHOLE i;` would be illegal. +For example, `WHOLE` could now be used in a variable declaration such as `WHOLE i;` or `const WHOLE i;`. However, the declaration `long WHOLE i;` would be illegal. ```C typedef struct club @@ -113,7 +113,7 @@ typedef struct club } GROUP; ``` -This statement declares `GROUP` as a structure type with three members. Since a structure tag, `club`, is also specified, either the typedef name (`GROUP`) or the structure tag can be used in declarations. You must use the struct keyword with the tag, and you cannot use the struct keyword with the typedef name. +This statement declares `GROUP` as a structure type with three members. Since a structure tag, `club`, is also specified, either the typedef name (`GROUP`) or the structure tag can be used in declarations. You must use the **`struct`** keyword with the tag, and you can't use the **`struct`** keyword with the typedef name. ```C typedef GROUP *PG; /* Uses the previous typedef name @@ -126,7 +126,7 @@ The type `PG` is declared as a pointer to the `GROUP` type, which in turn is def typedef void DRAWF( int, int ); ``` -This example provides the type `DRAWF` for a function returning no value and taking two int arguments. This means, for example, that the declaration +This example provides the type `DRAWF` for a function returning no value and taking two int arguments. It means, for example, that the declaration ```C DRAWF box; diff --git a/docs/c-language/typeof-c.md b/docs/c-language/typeof-c.md new file mode 100644 index 0000000000..1537669942 --- /dev/null +++ b/docs/c-language/typeof-c.md @@ -0,0 +1,59 @@ +--- +title: "typeof, __typeof__ (C23)" +description: "Describes Microsoft Visual C23 typeof operator" +ms.date: 02/06/2024 +helpviewer_keywords: ["typeof keyword [C]", "__typeof__ keyword [C]"] +--- +# `typeof`, `__typeof__` (C23) + +New in the C23 standard, the **`typeof`** operator is a unary operator that returns the type of an expression. It can be used in type declarations, type casts, type checks, and so on. It gets the type of a variable, function, or any C expression. + +The **`__typeof__`** keyword is a Microsoft-specific extension that provides the same functionality as **`typeof`**. The `__typeof__` keyword differs from `typeof` only in that it's available when compiling for all versions of C (not just `/std:clatest`), and it may ease porting code between other compilers that support `__typeof__`. + +### `typeof` syntax + +```c +typeof(type) +typeof(constant-expression) +__typeof__(constant-expression) +``` + +### `typeof` example + +This example uses `typeof()`, but the behavior is the same if you use `__typeof__`. + +```c +// Compile with /std:clatest + +#include + +double func() +{ + 3.14; +} + +#define POINTER(T) typeof(T*) + +int main() +{ + auto a = func(); // the type for a (double) is inferred, but requires initialization at point of declaration + typeof(func()) b; // the type for b is double, but didn't have to be initialized at point of declaration + + // Some declarations using typeof + POINTER(int) p1 = NULL; // p1 is int* + + typeof(double(void))* pFunc = func; // pFunc is a pointer to a function that takes no arguments and returns a double + printf("pFunc() returns %f\n", pFunc()); + + return 0; +} +``` + +## Requirements + +Requires Visual Studio 17.9 or later, or `cl.exe` version 19.39.33428 or later. +To use `typeof`, compile with [`/std:clatest`](../build/reference/std-specify-language-standard-version.md). + +## See also + +[`/std` (Specify Language Standard Version)](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/c-language/typeof-unqual-c.md b/docs/c-language/typeof-unqual-c.md new file mode 100644 index 0000000000..7786d9ecb8 --- /dev/null +++ b/docs/c-language/typeof-unqual-c.md @@ -0,0 +1,57 @@ +--- +title: "typeof_unqual, __typeof_unqual__ (C23)" +description: "Describes Microsoft Visual C23 typeof_unqual operator" +ms.date: 02/06/2024 +helpviewer_keywords: ["typeof_unqual keyword [C]", "__typeof_unqual__ keyword [C]"] +--- +# `typeof_unqual`, `__typeof_unqual__` (C23) + +New in the C23 standard, the **`typeof_unqual`** operator is a unary operator that returns the type of an expression after discarding qualifiers such as `const`, `volatile`, and `restrict`. It can be used in type declarations, type casts, type checks, and so on. It gets the type of a variable, function, or any C expression. + +The **`__typeof_unqual__`** keyword is a Microsoft-specific extension that provides the same functionality as **`typeof_unqual`**. The **`__typeof_unqual__`** keyword differs from `typeof_unqual` only in that it's available when compiling for all versions of C (not just `/std:clatest`), and it may ease porting code between other compilers that support `__typeof_unqual__`. + +### `typeof_unqual` syntax + +```c +typeof_unqual(type) +typeof_unqual(constant-expression) +__typeof__unqual(constant-expression) +``` + +### `typeof_unqual` example + +This example uses `typeof_unqual()`, but the behavior is the same if you use `__typeof_unqual__`. + +```c +// Compile with /std:clatest and /experimental:c11atomics +#include + +// A function that takes an atomic int pointer, but uses a non-atomic copy of the value +void func(_Atomic(int) * pAtomic) +{ + typeof_unqual(*pAtomic) local = *pAtomic; + + // Use local non-atomic copy of value +} + +int main() +{ + int* const cpVar1 = 2; + typeof_unqual(cpVar1) pVar2 = 3; + pVar2 = 4; // no error because pi is not const. cpVar1 = 4 would be an error. + + _Atomic(int)i = 42; + func(&i); + + return 0; +} +``` + +## Requirements + +Requires Visual Studio 17.9 or later, or `cl.exe` version 19.39.33428 or later. +To use `typeof_unqual`, compile with [`/std:clatest`](../build/reference/std-specify-language-standard-version.md). + +## See also + +[`/std` (Specify Language Standard Version)](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/c-language/union-declarations.md b/docs/c-language/union-declarations.md index 03f8d046bc..7a0a0cd01e 100644 --- a/docs/c-language/union-declarations.md +++ b/docs/c-language/union-declarations.md @@ -5,42 +5,42 @@ ms.date: "11/04/2016" helpviewer_keywords: ["unions", "union keyword [C], declarations", "variant records"] ms.assetid: 978c6165-e0ae-4196-afa7-6d94e24f62f7 --- -# Union Declarations +# `union` Declarations A "union declaration" specifies a set of variable values and, optionally, a tag naming the union. The variable values are called "members" of the union and can have different types. Unions are similar to "variant records" in other languages. ## Syntax -*struct-or-union-specifier*:
-    *struct-or-union* *identifier*opt **{** *struct-declaration-list* **}**
-    *struct-or-union* *identifier* +*`struct-or-union-specifier`*:\ + *`struct-or-union`* *`identifier`*opt **`{`** *`struct-declaration-list`* **`}`**\ + *`struct-or-union`* *`identifier`* -*struct-or-union*:
-    **`struct`**
-    **`union`** +*`struct-or-union`*:\ + **`struct`**\ + **`union`** -*struct-declaration-list*:
-    *struct-declaration*
-    *struct-declaration-list* *struct-declaration* +*`struct-declaration-list`*:\ + *`struct-declaration`*\ + *`struct-declaration-list`* *`struct-declaration`* The union content is defined to be -*struct-declaration*:
-    *specifier-qualifier-list* *struct-declarator-list* **;** +*`struct-declaration`*:\ + *`specifier-qualifier-list`* *`struct-declarator-list`* **`;`** -*specifier-qualifier-list*:
-    *type-specifier* *specifier-qualifier-list*opt
-    *type-qualifier* *specifier-qualifier-list*opt +*`specifier-qualifier-list`*:\ + *`type-specifier`* *`specifier-qualifier-list`*opt \ + *`type-qualifier`* *`specifier-qualifier-list`*opt -*struct-declarator-list*:
-    *struct-declarator*
-    *struct-declarator-list* **,** *struct-declarator* +*`struct-declarator-list`*:\ + *`struct-declarator`*\ + *`struct-declarator-list`* **`,`** *`struct-declarator`* A variable with **`union`** type stores one of the values defined by that type. The same rules govern structure and union declarations. Unions can also have bit fields. -Members of unions cannot have an incomplete type, type **`void`**, or function type. Therefore members cannot be an instance of the union but can be pointers to the union type being declared. +Members of unions can't have an incomplete type, type **`void`**, or function type. Therefore members can't be an instance of the union but can be pointers to the union type being declared. -A union type declaration is a template only. Memory is not reserved until the variable is declared. +A union type declaration is a template only. Memory isn't reserved until the variable is declared. > [!NOTE] > If a union of two types is declared and one value is stored, but the union is accessed with the other type, the results are unreliable. For example, a union of **`float`** and **`int`** is declared. A **`float`** value is stored, but the program later accesses the value as an **`int`**. In such a situation, the value would depend on the internal storage of **`float`** values. The integer value would not be reliable. @@ -75,13 +75,13 @@ The `screen` array contains 2,000 elements. Each element of the array is an indi **Microsoft Specific** -Nested unions can be declared anonymously when they are members of another structure or union. This is an example of a nameless union: +Nested unions can be declared anonymously when they're members of another structure or union. Here's an example of a nameless union: ```C struct str { int a, b; - union / * Unnamed union */ + union /* Unnamed union */ { char c[4]; long l; @@ -95,7 +95,7 @@ struct str my_str.l == 0L; /* A reference to a field in the my_str union */ ``` -Unions are often nested within a structure that includes a field giving the type of data contained in the union at any particular time. This is an example of a declaration for such a union: +Unions are often nested within a structure that includes a field giving the type of data contained in the union at any particular time. Here's an example of a declaration for such a union: ```C struct x diff --git a/docs/c-language/using-wmain.md b/docs/c-language/using-wmain.md index 6d6844dae0..a3c8096833 100644 --- a/docs/c-language/using-wmain.md +++ b/docs/c-language/using-wmain.md @@ -1,34 +1,45 @@ --- description: "Learn more about: Using wmain" title: "Using wmain" -ms.date: "11/04/2016" +ms.date: 09/27/2022 helpviewer_keywords: ["wmain function"] ms.assetid: d0300812-adc4-40c6-bba3-b2da25468c80 --- -# Using wmain +# Using `wmain` **Microsoft Specific** -In the Unicode programming model, you can define a wide-character version of the **main** function. Use **wmain** instead of **main** if you want to write portable code that adheres to the Unicode programming model. +In the Unicode programming model, you can define a wide-character version of the `main` function. Use `wmain` instead of `main` if you want to write portable code that adheres to the Unicode programming model. -## Syntax +Like `main`, several restrictions apply to the `wmain` function that don't apply to any other C functions. The `wmain` function: -``` -wmain( int argc, wchar_t *argv[ ], wchar_t *envp[ ] ) +- Can't be declared as **`inline`**. +- Can't be declared as **`static`**. +- Can't have its address taken. +- Can't be called from your program. + +## The `wmain` function signature + +The `wmain` function doesn't have a declaration, because it's built into the language. If it did, the declaration syntax for `wmain` would look like this: + +```C +int wmain( void ); +int wmain( int argc, wchar_t *argv[ ] ); +int wmain( int argc, wchar_t *argv[ ], wchar_t *envp[ ] ); ``` -## Remarks +The `wmain` function is declared implicitly by using one of these signatures. You may use any of these signatures when you define your `wmain` function. You can then pass wide-character arguments and, optionally, a wide-character environment pointer to the program. The Microsoft compiler also allows `wmain` to have a return type of **`void`** when no value is returned. The *`argv`* and *`envp`* parameters to `wmain` can also be defined as type `wchar_t**`. For more information about the arguments, see [Argument description](./argument-description.md). -You declare formal parameters to **wmain** using a similar format to **main**. You can then pass wide-character arguments and, optionally, a wide-character environment pointer to the program. The `argv` and `envp` parameters to **wmain** are of type `wchar_t*`. For example: +## The `envp` environment -If your program uses a **main** function, the multibyte-character environment is created by the run-time library at program startup. A wide-character copy of the environment is created only when needed (for example, by a call to the `_wgetenv` or `_wputenv` functions). On the first call to `_wputenv`, or on the first call to `_wgetenv` if an MBCS environment already exists, a corresponding wide-character string environment is created and is then pointed to by the `_wenviron` global variable, which is a wide-character version of the `_environ` global variable. At this point, two copies of the environment (MBCS and Unicode) exist simultaneously and are maintained by the operating system throughout the life of the program. +If your program uses a `main` function, the multibyte-character environment is created by the run-time library at program startup. A wide-character copy of the environment is created only when needed (for example, by a call to the `_wgetenv` or `_wputenv` functions). On the first call to `_wputenv`, or on the first call to `_wgetenv` if an MBCS environment already exists, a corresponding wide-character string environment is created and is then pointed to by the `_wenviron` global variable, which is a wide-character version of the `_environ` global variable. At this point, two copies of the environment (MBCS and Unicode) exist simultaneously and are maintained by the operating system throughout the life of the program. -Similarly, if your program uses a **wmain** function, a wide-character environment is created at program startup and is pointed to by the `_wenviron` global variable. An MBCS (ASCII) environment is created on the first call to `_putenv` or `getenv`, and is pointed to by the `_environ` global variable. +Similarly, if your program uses a `wmain` function, a wide-character environment is created at program startup and is pointed to by the `_wenviron` global variable. An MBCS (ASCII) environment is created on the first call to `_putenv` or `getenv`, and is pointed to by the `_environ` global variable. -For more information on the MBCS environment, see [Internationalization](../c-runtime-library/internationalization.md) in the *Run-Time Library Reference.* +For more information on the MBCS environment, see [Internationalization](../c-runtime-library/internationalization.md). **END Microsoft Specific** ## See also -[main Function and Program Execution](../c-language/main-function-and-program-execution.md) +[`main` function and program execution](../c-language/main-function-and-program-execution.md) diff --git a/docs/c-language/while-statement-c.md b/docs/c-language/while-statement-c.md index 462f57070c..5035e2c114 100644 --- a/docs/c-language/while-statement-c.md +++ b/docs/c-language/while-statement-c.md @@ -6,26 +6,26 @@ f1_keywords: ["while"] helpviewer_keywords: ["while keyword [C]", "while keyword [C], syntax"] ms.assetid: d0c970b8-12a9-4827-afb2-a051111834b7 --- -# while Statement (C) +# `while` Statement (C) The **`while`** statement lets you repeat a statement until a specified expression becomes false. ## Syntax -*iteration-statement*:
-    **while (** *expression* **)** *statement* +*`iteration-statement`*:\ + **`while (`** *`expression`* **`)`** *`statement`* -The *expression* must have arithmetic or pointer type. Execution proceeds as follows: +The *`expression`* must have arithmetic or pointer type. Execution proceeds as follows: -1. The *expression* is evaluated. +1. The *`expression`* is evaluated. -1. If *expression* is initially false, the body of the **`while`** statement is never executed, and control passes from the **`while`** statement to the next statement in the program. +1. If *`expression`* is initially false, the body of the **`while`** statement is never executed, and control passes from the **`while`** statement to the next statement in the program. - If *expression* is true (nonzero), the body of the statement is executed and the process is repeated beginning at step 1. + If *`expression`* is true (nonzero), the body of the statement is executed and the process is repeated beginning at step 1. The **`while`** statement can also terminate when a **`break`**, **`goto`**, or **`return`** within the statement body is executed. Use the **`continue`** statement to terminate an iteration without exiting the **`while`** loop. The **`continue`** statement passes control to the next iteration of the **`while`** statement. -This is an example of the **`while`** statement: +Here's an example of the **`while`** statement: ```C while ( i >= 0 ) @@ -35,8 +35,8 @@ while ( i >= 0 ) } ``` -This example copies characters from `string2` to `string1`. If `i` is greater than or equal to 0, `string2[i]` is assigned to `string1[i]` and `i` is decremented. When `i` reaches or falls below 0, execution of the **`while`** statement terminates. +This example copies characters from `string2` to `string1`. If `i` is greater than or equal to 0, then `string2[i]` is assigned to `string1[i]` and `i` is decremented. When `i` reaches or falls below 0, execution of the **`while`** statement terminates. ## See also -[while Statement (C++)](../cpp/while-statement-cpp.md) +[`while` Statement (C++)](../cpp/while-statement-cpp.md) diff --git a/docs/c-runtime-library/32-bit-windows-time-date-formats.md b/docs/c-runtime-library/32-bit-windows-time-date-formats.md index bb77e184b1..dfe8f3f72e 100644 --- a/docs/c-runtime-library/32-bit-windows-time-date-formats.md +++ b/docs/c-runtime-library/32-bit-windows-time-date-formats.md @@ -6,27 +6,27 @@ f1_keywords: ["vc.time"] helpviewer_keywords: ["32-bit Windows"] ms.assetid: ef1589db-84d7-4b24-8799-7c7a22cfe2bf --- -# 32-Bit Windows Time/Date Formats +# 32-Bit Windows time/date formats The file time and the date are stored individually, using unsigned integers as bit fields. File time and date are packed as follows: ### Time -|Bit position:|0 1 2 3 4|5 6 7 8 9 A|B C D E F| -|-------------------|-----------------------|---------------------------|-----------------------| -|Length:|5|6|5| -|Contents:|hours|minutes|2-second increments| -|Value Range:|0-23|0-59|0-29 in 2-second intervals| +| Bit position: | 0 1 2 3 4 | 5 6 7 8 9 A | B C D E F | +|---|---|---|---| +| Length: | 5 | 6 | 5 | +| Contents: | hours | minutes | 2-second increments | +| Value Range: | 0-23 | 0-59 | 0-29 in 2-second intervals | ### Date -|Bit position:|0 1 2 3 4 5 6|7 8 9 A|B C D E F| -|-------------------|-------------------------------|-------------------|-----------------------| -|Length:|7|4|5| -|Contents:|year|month|day| -|Value Range:|0-119|1-12|1-31| -||(relative to 1980)||| +| Bit position: | 0 1 2 3 4 5 6 | 7 8 9 A | B C D E F | +|---|---|---|---| +| Length: | 7 | 4 | 5 | +| Contents: | year | month | day | +| Value Range: | 0-119 | 1-12 | 1-31 | +| | (relative to 1980) | | | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/a-sample-generic-text-program.md b/docs/c-runtime-library/a-sample-generic-text-program.md index 0cf11e3a3d..95628a223a 100644 --- a/docs/c-runtime-library/a-sample-generic-text-program.md +++ b/docs/c-runtime-library/a-sample-generic-text-program.md @@ -5,7 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["_TCHAR type", "mappings, TCHAR.H data types", "generic-text example [CRT]", "TCHAR type", "TCHAR.H data types, mapping"] ms.assetid: a03de0db-8118-4bd9-a03f-640e8dfc5ed3 --- -# A Sample Generic-Text Program +# A sample generic-text program **Microsoft Specific** @@ -87,7 +87,7 @@ int __cdecl main(int argc, char **argv, char **envp) } ``` -If `_UNICODE` has been defined, GENTEXT.C maps to the following Unicode version of the program. For more information about using `wmain` in Unicode programs as a replacement for `main`, see [Using wmain](../c-language/using-wmain.md) in *C Language Reference*. +If `_UNICODE` has been defined, GENTEXT.C maps to the following Unicode version of the program. For more information about using `wmain` in Unicode programs as a replacement for `main`, see [Using `wmain`](../c-language/using-wmain.md) in *C Language Reference*. ```C // crt_unicgtxt.c @@ -125,7 +125,7 @@ int __cdecl wmain(int argc, wchar_t **argv, wchar_t **envp) } ``` -If neither `_MBCS` nor `_UNICODE` has been defined, GENTEXT.C maps to single-byte ASCII code, as follows: +If `_MBCS` or `_UNICODE` hasn't been defined, GENTEXT.C maps to single-byte ASCII code, as follows: ```C // crt_sbcsgtxt.c @@ -166,8 +166,8 @@ int __cdecl main(int argc, char **argv, char **envp) ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/abnormal-termination.md b/docs/c-runtime-library/abnormal-termination.md index 7bbfc9cb6a..f513fc45d1 100644 --- a/docs/c-runtime-library/abnormal-termination.md +++ b/docs/c-runtime-library/abnormal-termination.md @@ -6,11 +6,11 @@ api_name: ["_abnormal_termination"] api_location: ["msvcr110.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_abnormal_termination"] +f1_keywords: ["_abnormal_termination", "EXCPT/_abnormal_termination"] helpviewer_keywords: ["_abnormal_termination"] ms.assetid: 952970a4-9586-4c3d-807a-db729448c91c --- -# _abnormal_termination +# `_abnormal_termination` Indicates whether the **`__finally`** block of a [try-finally statement](../cpp/try-finally-statement.md) is entered while the system is executing an internal list of termination handlers. @@ -21,19 +21,19 @@ int _abnormal_termination( ); ``` -## Return Value +## Return value -**`true`** if the system is *unwinding* the stack; otherwise, **`false`**. +**`true`** if the system is unwinding the stack; otherwise, **`false`**. ## Remarks -This is an internal function used to manage unwinding exceptions, and is not intended to be called from user code. +**`_abnormal_termination`** is an internal function used to manage unwinding exceptions, and isn't intended to be called from user code. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_abnormal_termination|excpt.h| +| Routine | Required header | +|---|---| +| **`_abnormal_termination`** | `` | ## See also diff --git a/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md b/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md index b4c49e9ae3..4d60eaa7af 100644 --- a/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md +++ b/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md @@ -6,17 +6,17 @@ api_name: ["_wcmdln", "_acmdln"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_acmdln", "acmdln", "_wcmdln", "wcmdln", "_tcmdln", "tcmdln"] +f1_keywords: ["_acmdln", "_wcmdln", "_tcmdln"] helpviewer_keywords: ["_wcmdln global variable", "wcmdln global variable", "_acmdln global variable", "_tcmdln global variable", "tcmdln global variable", "acmdln global variable"] ms.assetid: 4fc0a6a0-3f93-420a-a19f-5276061ba539 --- -# _acmdln, _tcmdln, _wcmdln +# `_acmdln`, `_tcmdln`, `_wcmdln` Internal CRT global variable. The command line. ## Syntax -``` +```C char * _acmdln; wchar_t * _wcmdln; @@ -28,8 +28,8 @@ wchar_t * _wcmdln; ## Remarks -These CRT internal variables store the complete command line. They are exposed in the exported symbols for the CRT, but are not intended for use in your code. `_acmdln` stores the data as a character string. `_wcmdln` stores the data as a wide character string. `_tcmdln` can be defined as either `_acmdln` or `_wcmdln`, depending on which is appropriate. +These CRT internal variables store the complete command line. They're exposed in the exported symbols for the CRT, but aren't intended for use in your code. `_acmdln` stores the data as a character string. `_wcmdln` stores the data as a wide character string. `_tcmdln` can be defined as either `_acmdln` or `_wcmdln`, depending on which is appropriate. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](./global-variables.md) diff --git a/docs/c-runtime-library/ansi-c-compliance.md b/docs/c-runtime-library/ansi-c-compliance.md index 2d748a75e9..e9aad2a085 100644 --- a/docs/c-runtime-library/ansi-c-compliance.md +++ b/docs/c-runtime-library/ansi-c-compliance.md @@ -3,7 +3,6 @@ title: "ANSI C Conformance" description: "An overview of Microsoft C runtime naming conventions for ANSI C conformance." ms.date: "11/04/2016" ms.topic: "conceptual" -f1_keywords: ["Ansi"] helpviewer_keywords: ["underscores, leading", "compatibility [C++], ANSI C", "conformance with ANSI C", "conventions [C++], Microsoft extensions", "underscores", "naming conventions [C++], Microsoft library", "ANSI [C++], C standard", "Microsoft extensions naming conventions"] ms.assetid: 6be271bf-eecf-491a-a928-0ee2dd60e3b9 --- @@ -13,8 +12,8 @@ The naming convention for all Microsoft-specific identifiers in the run-time sys The names of Microsoft-specific functions and global variables begin with a single underscore. These names can be overridden only locally, within the scope of your code. For example, when you include Microsoft run-time header files, you can still locally override the Microsoft-specific function named `_open` by declaring a local variable of the same name. However, you can't use this name for your own global function or global variable. -The names of Microsoft-specific macros and manifest constants begin with two underscores, or with a single leading underscore immediately followed by an uppercase letter. The scope of these identifiers is absolute. For example, you can't use the Microsoft-specific identifier **_UPPER** for this reason. +The names of Microsoft-specific macros and manifest constants begin with two underscores, or with a single leading underscore immediately followed by an uppercase letter. The scope of such identifiers is absolute. For example, you can't use the Microsoft-specific identifier `_UPPER` for this reason. ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/argc-argv-wargv.md b/docs/c-runtime-library/argc-argv-wargv.md index 4142ddbab8..776f920bae 100644 --- a/docs/c-runtime-library/argc-argv-wargv.md +++ b/docs/c-runtime-library/argc-argv-wargv.md @@ -6,14 +6,14 @@ api_name: ["__wargv", "__argv", "__argc"] api_location: ["msvcrt120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__argv", "__argc", "__wargv"] +f1_keywords: ["__argc", "STDLIB/__argc", "__argv", "STDLIB/__argv", "__wargv", "STDLIB/__wargv"] helpviewer_keywords: ["__argv", "__wargv", "__argc"] ms.assetid: 17001b0a-04ad-4762-b3a6-c54847f02d7c no-loc: [__argc, __argv, __wargv, main, wmain] --- -# __argc, __argv, __wargv +# `__argc`, `__argv`, `__wargv` -The `__argc` global variable is a count of the number of command-line arguments passed to the program. `__argv` is a pointer to an array of single-byte-character or multi-byte-character strings that contain the program arguments, and `__wargv` is a pointer to an array of wide-character strings that contain the program arguments. These global variables provide the arguments to `main` or `wmain`. +The **`__argc`** global variable is a count of the number of command-line arguments passed to the program. **`__argv`** is a pointer to an array of single-byte-character or multi-byte-character strings that contain the program arguments, and **`__wargv`** is a pointer to an array of wide-character strings that contain the program arguments. These global variables provide the arguments to `main` or `wmain`. ## Syntax @@ -25,26 +25,26 @@ extern wchar_t ** __wargv; ## Remarks -In a program that uses the `main` function, `__argc` and `__argv` are initialized at program startup by using the command line that's used to start the program. The command line is parsed into individual arguments, and wildcards are expanded. The count of arguments is assigned to `__argc` and the argument strings are allocated on the heap, and a pointer to the array of arguments is assigned to `__argv`. In a program compiled to use wide characters and a `wmain` function, the arguments are parsed and wildcards are expanded as wide-character strings, and a pointer to the array of argument strings is assigned to `__wargv`. +In a program that uses the `main` function, **`__argc`** and **`__argv`** are initialized at program startup by using the command line that's used to start the program. The command line is parsed into individual arguments, and wildcards are expanded. The count of arguments is assigned to **`__argc`** and the argument strings are allocated on the heap, and a pointer to the array of arguments is assigned to **`__argv`**. In a program compiled to use wide characters and a `wmain` function, the arguments are parsed and wildcards are expanded as wide-character strings, and a pointer to the array of argument strings is assigned to **`__wargv`**. For portable code, we recommend you use the arguments passed to `main` to get the command-line arguments in your program. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE not defined|_UNICODE defined| -|---------------------|---------------------------|-----------------------| -|`__targv`|`__argv`|`__wargv`| +| Tchar.h routine | `_UNICODE` not defined | `_UNICODE` defined | +|---|---|---| +| `__targv` | **`__argv`** | **`__wargv`** | ## Requirements -|Global variable|Required header| -|---------------------|---------------------| -|`__argc`, `__argv`, `__wargv`|\, \ (C++)| +| Global variable | Required header | +|---|---| +| **`__argc`**, **`__argv`**, **`__wargv`** | \, \ (C++) | -`__argc`, `__argv`, and `__wargv` are Microsoft extensions. For compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +**`__argc`**, **`__argv`**, and **`__wargv`** are Microsoft extensions. For compatibility information, see [Compatibility](./compatibility.md). ## See also -[Global variables](../c-runtime-library/global-variables.md)\ -[main function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ -[Using wmain Instead of main](../cpp/main-function-command-line-args.md) +[Global variables](./global-variables.md)\ +[`main` function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ +[Using `wmain` instead of `main`](../cpp/main-function-command-line-args.md) diff --git a/docs/c-runtime-library/argument-access.md b/docs/c-runtime-library/argument-access.md index 0f31799ba6..a596c13d28 100644 --- a/docs/c-runtime-library/argument-access.md +++ b/docs/c-runtime-library/argument-access.md @@ -8,16 +8,16 @@ ms.assetid: 7046ae34-a0ec-44f0-815d-3209492a3e19 --- # Argument access -The **va_arg**, **va_end**, and **va_start** macros provide access to function arguments when the number of arguments is variable. These macros are defined in \ for ANSI/ISO C compatibility and in \ for compatibility with UNIX System V. +The `va_arg`, `va_end`, and `va_start` macros provide access to function arguments when the number of arguments is variable. These macros are defined in \ for ANSI/ISO C compatibility and in \ for compatibility with UNIX System V. ## Argument-access macros -|Macro|Use| -|-----------|-------------------------------| -|[va_arg](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Retrieve argument from list| -|[va_end](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Reset pointer| -|[va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Set pointer to beginning of argument list| +| Macro | Use | +|---|---| +| [`va_arg`](./reference/va-arg-va-copy-va-end-va-start.md) | Retrieve argument from list | +| [`va_end`](./reference/va-arg-va-copy-va-end-va-start.md) | Reset pointer | +| [`va_start`](./reference/va-arg-va-copy-va-end-va-start.md) | Set pointer to beginning of argument list | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/backward-compatibility.md b/docs/c-runtime-library/backward-compatibility.md index 91183173c4..16e0a796c7 100644 --- a/docs/c-runtime-library/backward-compatibility.md +++ b/docs/c-runtime-library/backward-compatibility.md @@ -6,16 +6,16 @@ ms.topic: "conceptual" helpviewer_keywords: ["CRT, compatibility", "backward compatibility, C run-time libraries", "compatibility, C run-time libraries", "backward compatibility"] ms.assetid: cc3175cf-97fd-492f-b329-5791aea63090 --- -# Backward Compatibility +# Backward compatibility For compatibility between product versions, the library OLDNAMES.LIB maps old names to new names. For instance, `open` maps to `_open`. You must explicitly link with OLDNAMES.LIB only when you compile with the following combinations of command-line options: -- `/Zl` (omit default library name from object file) and `/Ze` (the default — use Microsoft extensions) +- `/Zl` (omit default library name from object file) and `/Ze` (the default: use Microsoft extensions) - `/link` (linker-control), `/NOD` (no default-library search), and `/Ze` -For more information about compiler command-line options, see [Compiler Reference](../build/reference/compiler-options.md). +For more information about compiler command-line options, see [Compiler options](../build/reference/compiler-options.md). ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/buffer-manipulation.md b/docs/c-runtime-library/buffer-manipulation.md index fb2d1941a0..7fce41ba6c 100644 --- a/docs/c-runtime-library/buffer-manipulation.md +++ b/docs/c-runtime-library/buffer-manipulation.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Buffer manipulation" title: "Buffer manipulation" -ms.date: "04/04/2018" +description: "Learn more about: Buffer manipulation" +ms.date: 04/04/2018 helpviewer_keywords: ["buffers, manipulation routines", "buffers"] -ms.assetid: 164f4860-ce66-412c-8291-396fbd70f03e --- # Buffer manipulation @@ -11,19 +10,19 @@ Use these routines to work with areas of memory on a byte-by-byte basis. ## Buffer-manipulation routines -|Routine|Use| -|-------------|---------| -|[_memccpy](../c-runtime-library/reference/memccpy.md)|Copy characters from one buffer to another until given character or given number of characters has been copied| -|[memchr, wmemchr](../c-runtime-library/reference/memchr-wmemchr.md)|Return pointer to first occurrence, within specified number of characters, of given character in buffer| -|[memcmp, wmemcmp](../c-runtime-library/reference/memcmp-wmemcmp.md)|Compare specified number of characters from two buffers| -|[memcpy, wmemcpy](../c-runtime-library/reference/memcpy-wmemcpy.md), [memcpy_s, wmemcpy_s](../c-runtime-library/reference/memcpy-s-wmemcpy-s.md)|Copy specified number of characters from one buffer to another| -|[_memicmp, _memicmp_l](../c-runtime-library/reference/memicmp-memicmp-l.md)|Compare specified number of characters from two buffers without regard to case| -|[memmove, wmemmove](../c-runtime-library/reference/memmove-wmemmove.md),[memmove_s, wmemmove_s](../c-runtime-library/reference/memmove-s-wmemmove-s.md)|Copy specified number of characters from one buffer to another| -|[memset, wmemset](../c-runtime-library/reference/memset-wmemset.md)|Use given character to initialize specified number of bytes in the buffer| -|[_swab](../c-runtime-library/reference/swab.md)|Swap bytes of data and store them at specified location| +| Routine | Use | +|---|---| +| [`_memccpy`](reference/memccpy.md) | Copy characters from one buffer to another until given character or given number of characters has been copied | +| [`memchr`, `wmemchr`](reference/memchr-wmemchr.md) | Return pointer to first occurrence, within specified number of characters, of given character in buffer | +| [`memcmp`, `wmemcmp`](reference/memcmp-wmemcmp.md) | Compare specified number of characters from two buffers | +| [`memcpy`, `wmemcpy`](reference/memcpy-wmemcpy.md), [`memcpy_s`, `wmemcpy_s`](reference/memcpy-s-wmemcpy-s.md) | Copy specified number of characters from one buffer to another | +| [`_memicmp`, `_memicmp_l`](reference/memicmp-memicmp-l.md) | Compare specified number of characters from two buffers without regard to case | +| [`memmove`, `wmemmove`](reference/memmove-wmemmove.md), [`memmove_s`, `wmemmove_s`](reference/memmove-s-wmemmove-s.md) | Copy specified number of characters from one buffer to another | +| [`memset`, `wmemset`](reference/memset-wmemset.md) | Use given character to initialize specified number of bytes in the buffer | +| [`_swab`](reference/swab.md) | Swap bytes of data and store them at specified location | -When the source and target areas overlap, only **memmove** is guaranteed to copy the full source properly. +When the source and target areas overlap, only `memmove` is guaranteed to copy the full source properly. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/bufsiz.md b/docs/c-runtime-library/bufsiz.md index d42cf2cf32..35fcf77acf 100644 --- a/docs/c-runtime-library/bufsiz.md +++ b/docs/c-runtime-library/bufsiz.md @@ -2,23 +2,23 @@ description: "Learn more about: BUFSIZ" title: "BUFSIZ" ms.date: "11/04/2016" -f1_keywords: ["BUFSIZ"] +f1_keywords: ["BUFSIZ", "STDIO/BUFSIZ"] helpviewer_keywords: ["BUFSIZ constant"] ms.assetid: 94ac04a3-d154-476b-bd89-eefbc7b949ae --- -# BUFSIZ +# `BUFSIZ` ## Syntax -``` +```C #include ``` ## Remarks -`BUFSIZ` is the required user-allocated buffer for the [setvbuf](../c-runtime-library/reference/setvbuf.md) routine. +`BUFSIZ` is the required user-allocated buffer for the [`setvbuf`](./reference/setvbuf.md) routine. ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Stream I/O](./stream-i-o.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/byte-and-wide-streams.md b/docs/c-runtime-library/byte-and-wide-streams.md index 840a11276c..8ef801bf6c 100644 --- a/docs/c-runtime-library/byte-and-wide-streams.md +++ b/docs/c-runtime-library/byte-and-wide-streams.md @@ -3,19 +3,17 @@ title: "Byte and Wide Streams" description: "An overview of byte streams in the Microsoft C runtime library." ms.date: "11/04/2016" ms.topic: "conceptual" -f1_keywords: ["Byte and Wide Streams"] helpviewer_keywords: ["byte streams", "wide streams"] -ms.assetid: 61ef0587-4cbc-4eb8-aae5-4c298dbbc6f9 --- -# Byte and Wide Streams +# Byte and wide streams A byte stream treats a file as a sequence of bytes. Within the program, the stream is the identical sequence of bytes. -By contrast, a wide stream treats a file as a sequence of generalized multibyte characters, which can have a broad range of encoding rules. (Text and binary files are still read and written as previously described.) Within the program, the stream looks like the corresponding sequence of wide characters. Conversions between the two representations occur within the Standard C Library. The conversion rules can, in principle, be altered by a call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) that alters the category `LC_CTYPE`. Each wide stream determines its conversion rules at the time it becomes wide oriented, and retains these rules even if the category `LC_CTYPE` subsequently changes. +By contrast, a wide stream treats a file as a sequence of generalized multibyte characters, which can have a broad range of encoding rules. (Text and binary files are still read and written as previously described.) Within the program, the stream looks like the corresponding sequence of wide characters. Conversions between the two representations occur within the Standard C Library. The conversion rules can, in principle, be altered by a call to [`setlocale`](./reference/setlocale-wsetlocale.md) that alters the category `LC_CTYPE`. Each wide stream determines its conversion rules at the time it becomes wide oriented, and retains these rules even if the category `LC_CTYPE` later changes. -Positioning within a wide stream suffers the same limitations as for text steams. Moreover, the file-position indicator may well have to deal with a state-dependent encoding. Typically, it includes both a byte offset within the stream and an object of type `mbstate_t`. Thus, the only reliable way to obtain a file position within a wide stream is by calling [fgetpos](../c-runtime-library/reference/fgetpos.md), and the only reliable way to restore a position obtained this way is by calling [fsetpos](../c-runtime-library/reference/fsetpos.md). +Positioning within a wide stream suffers the same limitations as for text streams. Moreover, the file-position indicator may well have to deal with a state-dependent encoding. Typically, it includes both a byte offset within the stream and an object of type `mbstate_t`. Thus, the only reliable way to obtain a file position within a wide stream is by calling [`fgetpos`](./reference/fgetpos.md), and the only reliable way to restore a position obtained this way is by calling [`fsetpos`](./reference/fsetpos.md). ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) +[Files and streams](./files-and-streams.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/byte-classification.md b/docs/c-runtime-library/byte-classification.md index 2bd5d089d4..46fd6bbbac 100644 --- a/docs/c-runtime-library/byte-classification.md +++ b/docs/c-runtime-library/byte-classification.md @@ -8,37 +8,37 @@ ms.assetid: 1cb52d71-fb0c-46ca-aad7-6472c1103370 --- # Byte classification -Each of these routines tests a specified byte of a multibyte character for satisfaction of a condition. Except where specified otherwise, the output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +Each of these routines tests a specified byte of a multibyte character for satisfaction of a condition. Except where specified otherwise, the output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. > [!NOTE] > By definition, the ASCII characters between 0 and 127 are a subset of all multibyte-character sets. For example, the Japanese katakana character set includes ASCII as well as non-ASCII characters. -The predefined constants in the following table are defined in \. +The predefined constants in the following table are defined in ``. ## Multibyte-character byte-classification routines -|Routine|Byte Test Condition| -|-------------|-------------------------| -|[isleadbyte, _isleadbyte_l](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md)|Lead byte; test result depends on **LC_CTYPE** category setting of current locale| -|[_ismbbalnum, _ismbbalnum_l](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md)|**isalnum** || **_ismbbkalnum**| -|[_ismbbalpha, _ismbbalpha_l](../c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md)|**isalpha** || **_ismbbkalnum**| -|[_ismbbgraph, _ismbbgraph_l](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md)|Same as **_ismbbprint**, but **_ismbbgraph** does not include the space character (0x20)| -|[_ismbbkalnum, _ismbbkalnum_l](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md)|Non-ASCII text symbol other than punctuation. For example, in code page 932 only, **_ismbbkalnum** tests for katakana alphanumeric| -|[_ismbbkana, _ismbbkana_l](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md)|Katakana (0xA1 - 0xDF), code page 932 only| -|[_ismbbkprint, _ismbbkprint_l](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md)|Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, **_ismbbkprint** tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF).| -|[_ismbbkpunct, _ismbbkpunct_l](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md)|Non-ASCII punctuation. For example, in code page 932 only, **_ismbbkpunct** tests for katakana punctuation.| -|[_ismbblead, _ismbblead_l](../c-runtime-library/reference/ismbblead-ismbblead-l.md)|First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC.| -|[_ismbbprint, _ismbbprint_l](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md)|**isprint** || **_ismbbkprint**. **ismbbprint** includes the space character (0x20)| -|[_ismbbpunct, _ismbbpunct_l](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md)|**ispunct** || **_ismbbkpunct**| -|[_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md)|Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC.| -|[_ismbslead, _ismbslead_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md)|Lead byte (in string context)| -|[ismbstrail, _ismbstrail_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md)|Trail byte (in string context)| -|[_mbbtype, _mbbtype_l](../c-runtime-library/reference/mbbtype-mbbtype-l.md)|Return byte type based on previous byte| -|[_mbsbtype, _mbsbtype_l](../c-runtime-library/reference/mbsbtype-mbsbtype-l.md)|Return type of byte within string| -|[mbsinit](../c-runtime-library/reference/mbsinit.md)|Tracks the state of a multibyte character conversion.| - -The **MB_LEN_MAX** macro, defined in \, expands to the maximum length in bytes that any multibyte character can have. **MB_CUR_MAX**, defined in \, expands to the maximum length in bytes of any multibyte character in the current locale. +| Routine | Byte Test Condition | +|--|--| +| [`isleadbyte`, `_isleadbyte_l`](./reference/isleadbyte-isleadbyte-l.md) | Lead byte; test result depends on `LC_CTYPE` category setting of current locale | +| [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md) | `isalnum || _ismbbkalnum` | +| [`_ismbbalpha`, `_ismbbalpha_l`](./reference/ismbbalpha-ismbbalpha-l.md) | `isalpha || _ismbbkalpha` | +| [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` doesn't include the space character (0x20) | +| [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | +| [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF), code page 932 only | +| [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF). | +| [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation. | +| [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC. | +| [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md) | `isprint || _ismbbkprint`. `ismbbprint` includes the space character (0x20) | +| [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md) | `ispunct || _ismbbkpunct` | +| [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC. | +| [`_ismbslead`, `_ismbslead_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Lead byte (in string context) | +| [`ismbstrail`, `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Trail byte (in string context) | +| [`_mbbtype`, `_mbbtype_l`](./reference/mbbtype-mbbtype-l.md) | Return byte type based on previous byte | +| [`_mbsbtype`, `_mbsbtype_l`](./reference/mbsbtype-mbsbtype-l.md) | Return type of byte within string | +| [`mbsinit`](./reference/mbsinit.md) | Tracks the state of a multibyte character conversion. | + +The `MB_LEN_MAX` macro, defined in ``, expands to the maximum length in bytes that any multibyte character can have. `MB_CUR_MAX`, defined in ``, expands to the maximum length in bytes of any multibyte character in the current locale. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/c-run-time-library-reference.md b/docs/c-runtime-library/c-run-time-library-reference.md index 269e399f15..192b1df77e 100644 --- a/docs/c-runtime-library/c-run-time-library-reference.md +++ b/docs/c-runtime-library/c-run-time-library-reference.md @@ -7,11 +7,11 @@ helpviewer_keywords: ["CRT", "runtime libraries", "CRT, reference"] --- # Microsoft C runtime library (CRT) reference -The Microsoft runtime library provides routines for programming the Microsoft Windows operating system. These routines automate many common programming tasks that are not provided by the C and C++ languages. +The Microsoft runtime library provides routines for programming the Microsoft Windows operating system. These routines automate many common programming tasks that aren't provided by the C and C++ languages. -Sample programs are included in the individual reference topics for most routines in the library. +Sample programs are included in the individual reference articles for most routines in the library. -## In This Section +## In this section [Universal C runtime routines by category](run-time-routines-by-category.md)\ Provides links to the runtime library by category. @@ -40,7 +40,7 @@ Describes how to use the `setlocale` function to set the language and Country/Re [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](crt-library-features.md)\ List of `.lib` files that make up the C runtime libraries and their associated compiler options and preprocessor directives. -## Related Sections +## Related sections [Debug routines](debug-routines.md)\ Provides links to the debug versions of the runtime library routines. diff --git a/docs/c-runtime-library/cgets-cgetws.md b/docs/c-runtime-library/cgets-cgetws.md index d50430497c..3869e4230c 100644 --- a/docs/c-runtime-library/cgets-cgetws.md +++ b/docs/c-runtime-library/cgets-cgetws.md @@ -3,26 +3,26 @@ description: "Learn more about: _cgets, _cgetws" title: "_cgets, _cgetws" ms.date: "4/2/2020" api_name: ["_cgetws", "_cgets", "_o__cgets", "_o__cgetws"] -api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cgetws", "_cgetws", "_cgets"] helpviewer_keywords: ["_cgetws function", "strings [C++], getting from console", "console, getting strings from", "_cgets function", "cgetws function", "cgets function"] ms.assetid: 4d5e134a-58c3-4f62-befd-5d235b0212f4 --- -# _cgets, _cgetws +# `_cgets`, `_cgetws` -Gets a character string from the console. More secure versions of these functions are available; see [_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md). +Gets a character string from the console. More secure versions of these functions are available; see [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md). > [!IMPORTANT] -> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, _cgets_s and _cgetws_s, are still available. For information on these alternative functions, see [_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md). +> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, _cgets_s and _cgetws_s, are still available. For information on these alternative functions, see [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax -``` +```C char *_cgets( char *buffer ); @@ -41,37 +41,37 @@ wchar_t *_cgetws( #### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -## Return Value +## Return value -`_cgets` and `_cgetws` return a pointer to the start of the string, at `buffer[2]`. If `buffer` is **NULL**, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **NULL** and set `errno` to `EINVAL`. +**`_cgets`** and **`_cgetws`** return a pointer to the start of the string, at `buffer[2]`. If *`buffer`* is `NULL`, these functions invoke the invalid parameter handler, as described in [Parameter validation](./parameter-validation.md). If execution is allowed to continue, they return `NULL` and set `errno` to `EINVAL`. ## Remarks -These functions read a string of characters from the console and store the string and its length in the location pointed to by `buffer`. The `buffer` parameter must be a pointer to a character array. The first element of the array, `buffer[0]`, must contain the maximum length (in characters) of the string to be read. The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 additional bytes. The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. The string is stored starting at `buffer[2]`. If the function reads a CR-LF, it stores the null character ('\0'). The function then stores the actual length of the string in the second array element, `buffer[1]`. +These functions read a string of characters from the console and store the string and its length in the location pointed to by *`buffer`*. The *`buffer`* parameter must be a pointer to a character array. The first element of the array, `buffer[0]`, must contain the maximum length (in characters) of the string to be read. The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 extra bytes. The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. The string is stored starting at `buffer[2]`. If the function reads a CR-LF, it stores the null character ('\0'). The function then stores the actual length of the string in the second array element, `buffer[1]`. -Because all editing keys are active when `_cgets` or `_cgetws` is called while in a console window, pressing the F3 key repeats the last entered entry. +Because all editing keys are active when **`_cgets`** or **`_cgetws`** is called while in a console window, pressing the F3 key repeats the last entered entry. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](./secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_cgetts`|`_cgets`|`_cgets`|`_cgetws`| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cgetts` | **`_cgets`** | **`_cgets`** | **`_cgetws`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_cgets`|\| -|`_cgetws`|\ or \| +| Routine | Required header | +|---|---| +| **`_cgets`** | \ | +| **`_cgetws`** | \ or \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Example @@ -119,5 +119,5 @@ Text = A line of input. ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)
-[_getch, _getwch](../c-runtime-library/reference/getch-getwch.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`_getch`, `_getwch`](./reference/getch-getwch.md) diff --git a/docs/c-runtime-library/character-classification.md b/docs/c-runtime-library/character-classification.md index db0eff2bc3..3a040c99cc 100644 --- a/docs/c-runtime-library/character-classification.md +++ b/docs/c-runtime-library/character-classification.md @@ -6,11 +6,11 @@ f1_keywords: ["c.types.character"] helpviewer_keywords: ["character classification routines", "characters, testing"] ms.assetid: 3b6c8f0b-9701-407a-b384-9086698773f5 --- -# Character Classification +# Character classification -Each of these routines tests a specified single-byte character, wide character, or multibyte character for satisfaction of a condition. (By definition, the ASCII character set between 0 and 127 are a subset of all multibyte-character sets. For example, Japanese katakana includes ASCII as well as non-ASCII characters.) +Each of these routines tests a specified single-byte character, wide character, or multibyte character for satisfaction of a condition. (By definition, the ASCII character set between 0 and 127 are a subset of all multibyte-character sets. For example, Japanese katakana includes both ASCII and non-ASCII characters.) -The test conditions are affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The test conditions are affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. Generally these routines execute faster than tests you might write and should be favored over. For example, the following code executes slower than a call to `isalpha(c)`: @@ -19,36 +19,36 @@ if ((c >= 'A') && (c <= 'Z')) || ((c >= 'a') && (c <= 'z')) return TRUE; ``` -## Character-Classification Routines - -|Routine|Character test condition| -|-------------|------------------------------| -|[isalnum, iswalnum, _isalnum_l, _iswalnum_l](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphanumeric| -|[_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Multibyte alphanumeric| -|[isalpha, iswalpha, _isalpha_l, _iswalpha_l](../c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphabetic| -|[isascii, __isascii, iswascii](../c-runtime-library/reference/isascii-isascii-iswascii.md)|ASCII| -|[isblank, iswblank, _isblank_l, _iswblank_l](../c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md), [_ismbcsblank, _ismbcsblank_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Blank (space or horizontal tab)| -|[iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)|Control| -|[iscsym, iscsymf, __iscsym, \__iswcsym, \__iscsymf, \__iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l](../c-runtime-library/reference/iscsym-functions.md)|Letter, underscore, or digit| -|[iscsym, iscsymf, __iscsym, \__iswcsym, \__iscsymf, \__iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l](../c-runtime-library/reference/iscsym-functions.md)|Letter or underscore| -|[isdigit, iswdigit, _isdigit_l, _iswdigit_l](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Decimal digit| -|[isgraph, iswgraph, _isgraph_l, _iswgraph_l](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable other than space| -|[islower, iswlower, _islower_l, _iswlower_l](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md), [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Lowercase| -|[_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Hiragana| -|[_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Katakana| -|[_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Legal multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 0 multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 1 multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 2 multibyte character| -|[_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Non-alphanumeric multibyte character| -|[isprint, iswprint, _isprint_l, _iswprint_l](../c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable| -|[ispunct, iswpunct, _ispunct_l, _iswpunct_l](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Punctuation| -|[isspace, iswspace, _isspace_l, _iswspace_l](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|White-space| -|[isupper, iswupper](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md), [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Uppercase| -|[_isctype, iswctype, _isctype_l, _iswctype_l](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)|Property specified by *desc* argument| -|[isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md)|Hexadecimal digit| -|[_mbclen, mblen, _mblen_l](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Return length of valid multibyte character; result depends on **LC_CTYPE** category setting of current locale| +## Character-classification routines + +| Routine | Character test condition | +|---|---| +| [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Alphanumeric | +| [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Multibyte alphanumeric | +| [`isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l`](./reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Alphabetic | +| [`isascii`, `__isascii`, `iswascii`](./reference/isascii-isascii-iswascii.md) | ASCII | +| [`isblank`, `iswblank`, `_isblank_l`, `_iswblank_l`](./reference/isblank-iswblank-isblank-l-iswblank-l.md), [`_ismbcsblank`, `_ismbcsblank_l`](./reference/ismbcgraph-functions.md) | Blank (space or horizontal tab) | +| [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md) | Control | +| [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md) | Letter, underscore, or digit | +| [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md) | Letter or underscore | +| [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Decimal digit | +| [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Printable other than space | +| [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md), [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](./reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Lowercase | +| [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](./reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Hiragana | +| [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](./reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Katakana | +| [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](./reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Legal multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 0 multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 1 multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 2 multibyte character | +| [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](./reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Non-alphanumeric multibyte character | +| [`isprint`, `iswprint`, `_isprint_l`, `_iswprint_l`](./reference/isprint-iswprint-isprint-l-iswprint-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Printable | +| [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Punctuation | +| [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | White-space | +| [`isupper`, `iswupper`](./reference/isupper-isupper-l-iswupper-iswupper-l.md), [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](./reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Uppercase | +| [`_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l`](./reference/isctype-iswctype-isctype-l-iswctype-l.md) | Property specified by *`desc`* argument | +| [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) | Hexadecimal digit | +| [`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md) | Return length of valid multibyte character; result depends on `LC_CTYPE` category setting of current locale | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/ciatan.md b/docs/c-runtime-library/ciatan.md index 73494e71d9..35d6549103 100644 --- a/docs/c-runtime-library/ciatan.md +++ b/docs/c-runtime-library/ciatan.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIatan" title: "_CIatan" ms.date: "4/2/2020" api_name: ["_CIatan", "_o__CIatan"] -api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIatan", "CIatan"] helpviewer_keywords: ["CIatan intrinsic", "_CIatan intrinsic"] ms.assetid: 3baa0429-fe46-4bab-8b00-868e2186dc8c --- -# _CIatan +# `_CIatan` Calculates the arctangent of the top value on the stack. @@ -26,7 +26,7 @@ This version of the `atan` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[atan, atanf, atanl, atan2, atan2f, atan2l](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) diff --git a/docs/c-runtime-library/ciatan2.md b/docs/c-runtime-library/ciatan2.md index 832d7261ac..d0f9ab04c6 100644 --- a/docs/c-runtime-library/ciatan2.md +++ b/docs/c-runtime-library/ciatan2.md @@ -3,16 +3,16 @@ description: "Learn more about: _CIatan2" title: "_CIatan2" ms.date: "4/2/2020" api_name: ["_CIatan2", "_o__CIatan2"] -api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIatan2", "_CIatan2"] helpviewer_keywords: ["_CIatan2 intrinsic", "CIatan2 intrinsic"] ms.assetid: 31f8cc78-b79f-4576-b73b-8add18e08680 --- -# _CIatan2 +# `_CIatan2` -Calculates the arctangent of *x* / *y* where *x* and *y* are values on the top of the stack. +Calculates the arctangent of *`x`* / *`y`* where *`x`* and *`y`* are values on the top of the stack. ## Syntax @@ -26,7 +26,7 @@ This version of the `atan2` function has a specialized calling convention that t The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[atan, atanf, atanl, atan2, atan2f, atan2l](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) diff --git a/docs/c-runtime-library/cicos.md b/docs/c-runtime-library/cicos.md index e9e4751094..d84df02680 100644 --- a/docs/c-runtime-library/cicos.md +++ b/docs/c-runtime-library/cicos.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIcos" title: "_CIcos" ms.date: "4/2/2020" api_name: ["_CIcos", "_o__CIcos"] -api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIcos", "_CIcos"] helpviewer_keywords: ["_CIcos intrinsic", "CIcos intrinsic"] ms.assetid: 6fc203fb-66f3-4ead-9784-f85833c26f1b --- -# _CIcos +# `_CIcos` Calculates the cosine of the top value in the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CIcos(); ## Remarks -This version of the [cos](../c-runtime-library/reference/cos-cosf-cosl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. +This version of the [`cos`](./reference/cos-cosf-cosl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[cos, cosf, cosl](../c-runtime-library/reference/cos-cosf-cosl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`cos`, `cosf`, `cosl`](./reference/cos-cosf-cosl.md) diff --git a/docs/c-runtime-library/ciexp.md b/docs/c-runtime-library/ciexp.md index 9b2004f03a..0fd7e1227a 100644 --- a/docs/c-runtime-library/ciexp.md +++ b/docs/c-runtime-library/ciexp.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIexp" title: "_CIexp" ms.date: "4/2/2020" api_name: ["_CIexp", "_o__CIexp"] -api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIexp", "_CIexp"] helpviewer_keywords: ["CIexp intrinsic", "_CIexp intrinsic"] ms.assetid: f8a3e3b7-fa57-41a3-9983-6c81914cbb55 --- -# _CIexp +# `_CIexp` Calculates the exponential of the top value on the stack. @@ -26,7 +26,7 @@ This version of the `exp` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[exp, expf, expl](../c-runtime-library/reference/exp-expf.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`exp`, `expf`, `expl`](./reference/exp-expf.md) diff --git a/docs/c-runtime-library/cifmod.md b/docs/c-runtime-library/cifmod.md index 3637973196..660a17bcb9 100644 --- a/docs/c-runtime-library/cifmod.md +++ b/docs/c-runtime-library/cifmod.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIfmod" title: "_CIfmod" ms.date: "4/2/2020" api_name: ["_CIfmod", "_o__CIfmod"] -api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIfmod", "CIfmod"] helpviewer_keywords: ["CIfmod intrinsic", "_CIfmod intrinsic"] ms.assetid: 7c050653-7ec6-4810-b3a7-7a0057ea65ed --- -# _CIfmod +# `_CIfmod` Calculates the floating-point remainder of the top two values on the stack. @@ -26,7 +26,7 @@ This version of the `fmod` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[fmod, fmodf](../c-runtime-library/reference/fmod-fmodf.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`fmod`, `fmodf`](./reference/fmod-fmodf.md) diff --git a/docs/c-runtime-library/cilog.md b/docs/c-runtime-library/cilog.md index 5071a255eb..229d1fb834 100644 --- a/docs/c-runtime-library/cilog.md +++ b/docs/c-runtime-library/cilog.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIlog" title: "_CIlog" ms.date: "4/2/2020" api_name: ["_CIlog", "_o__CIlog"] -api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIlog", "CIlog"] helpviewer_keywords: ["_CIlog intrinsic", "CIlog intrinsic"] ms.assetid: 23503854-ddaa-4fe0-a4a3-7fbb3a43bdec --- -# _CIlog +# `_CIlog` Calculates the natural logarithm of the top value in the stack. @@ -26,7 +26,7 @@ This version of the `log` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[log, logf, log10, log10f](../c-runtime-library/reference/log-logf-log10-log10f.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`log`, `logf`, `log10`, `log10f`](./reference/log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/cilog10.md b/docs/c-runtime-library/cilog10.md index be7c4fcf92..1c1447da3b 100644 --- a/docs/c-runtime-library/cilog10.md +++ b/docs/c-runtime-library/cilog10.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIlog10" title: "_CIlog10" ms.date: "4/2/2020" api_name: ["_CIlog10", "_o__CIlog10"] -api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIlog10", "_CIlog10"] helpviewer_keywords: ["_CIlog10 intrinsic", "CIlog10 intrinsic"] ms.assetid: 05d7fcaa-3cff-4cc5-8d44-015e7cacba24 --- -# _CIlog10 +# `_CIlog10` Performs a `log10` operation on the top value in the stack. @@ -26,7 +26,7 @@ This version of the `log10` function has a specialized calling convention that t The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[log, logf, log10, log10f](../c-runtime-library/reference/log-logf-log10-log10f.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`log`, `logf`, `log10`, `log10f`](./reference/log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/cipow.md b/docs/c-runtime-library/cipow.md index e375a887d1..6fe366afca 100644 --- a/docs/c-runtime-library/cipow.md +++ b/docs/c-runtime-library/cipow.md @@ -3,16 +3,16 @@ description: "Learn more about: _CIpow" title: "_CIpow" ms.date: "4/2/2020" api_name: ["_CIpow", "_o__CIpow"] -api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIpow", "_CIpow"] helpviewer_keywords: ["CIpow intrinsic", "_CIpow intrinsic"] ms.assetid: 477aaf0c-ac58-4252-89dd-9f3e35d47536 --- -# _CIpow +# `_CIpow` -Calculates *x* raised to the *y* power based on the top values in the stack. +Calculates *`x`* raised to the *`y`* power based on the top values in the stack. ## Syntax @@ -26,7 +26,7 @@ This version of the `pow` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[pow, powf, powl](../c-runtime-library/reference/pow-powf-powl.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`pow`, `powf`, `powl`](./reference/pow-powf-powl.md) diff --git a/docs/c-runtime-library/cisin.md b/docs/c-runtime-library/cisin.md index 10b73f0b9b..6eb5cf8f26 100644 --- a/docs/c-runtime-library/cisin.md +++ b/docs/c-runtime-library/cisin.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIsin" title: "_CIsin" ms.date: "4/2/2020" api_name: ["_CIsin", "_o__CIsin"] -api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIsin", "_CIsin"] helpviewer_keywords: ["_CIsin intrinsic", "CIsin intrinsic"] ms.assetid: f215f39a-2341-4f1c-ba8e-cb522451ceb2 --- -# _CIsin +# `_CIsin` Calculates the sine of the top value in the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CIsin(); ## Remarks -This intrinsic version of the [sin](../c-runtime-library/reference/sin-sinf-sinl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. +This intrinsic version of the [`sin`](./reference/sin-sinf-sinl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[sin, sinf, sinl](../c-runtime-library/reference/sin-sinf-sinl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`sin`, `sinf`, `sinl`](./reference/sin-sinf-sinl.md) diff --git a/docs/c-runtime-library/cisqrt.md b/docs/c-runtime-library/cisqrt.md index a45c65c4c3..ab5f5e0a72 100644 --- a/docs/c-runtime-library/cisqrt.md +++ b/docs/c-runtime-library/cisqrt.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIsqrt" title: "_CIsqrt" ms.date: "4/2/2020" api_name: ["_CIsqrt", "_o__CIsqrt"] -api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIsqrt", "CIsqrt"] helpviewer_keywords: ["CIsqrt intrinsic", "_CIsqrt intrinsic"] ms.assetid: 663548ea-398c-48ee-8397-a787c6ebb937 --- -# _CIsqrt +# `_CIsqrt` Calculates the square root of the top value in the stack. @@ -26,7 +26,7 @@ This version of the `sqrt` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[sqrt, sqrtf, sqrtl](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`sqrt`, `sqrtf`, `sqrtl`](./reference/sqrt-sqrtf-sqrtl.md) diff --git a/docs/c-runtime-library/citan.md b/docs/c-runtime-library/citan.md index efd56c6653..25708828fe 100644 --- a/docs/c-runtime-library/citan.md +++ b/docs/c-runtime-library/citan.md @@ -3,14 +3,14 @@ description: "Learn more about: _CItan" title: "_CItan" ms.date: "4/2/2020" api_name: ["_CItan", "_o__CItan"] -api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CItan", "CItan"] helpviewer_keywords: ["CItan intrinsic", "_CItan intrinsic"] ms.assetid: d1ea3113-50a2-45a6-b6bc-680fcdcc0928 --- -# _CItan +# `_CItan` Calculates the tangent of the top value on the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CItan(); ## Remarks -This version of the [tan](../c-runtime-library/reference/tan-tanf-tanl.md) function has a specialized calling convention that the compiler understands. The function speeds up the execution because it prevents copies from being generated and helps with register allocation. +This version of the [`tan`](./reference/tan-tanf-tanl.md) function has a specialized calling convention that the compiler understands. The function speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[tan, tanf, tanl](../c-runtime-library/reference/tan-tanf-tanl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`tan`, `tanf`, `tanl`](./reference/tan-tanf-tanl.md) diff --git a/docs/c-runtime-library/clocks-per-sec-clk-tck.md b/docs/c-runtime-library/clocks-per-sec-clk-tck.md index 4c16e39eb3..927a19ef92 100644 --- a/docs/c-runtime-library/clocks-per-sec-clk-tck.md +++ b/docs/c-runtime-library/clocks-per-sec-clk-tck.md @@ -2,15 +2,15 @@ description: "Learn more about: CLOCKS_PER_SEC, CLK_TCK" title: "CLOCKS_PER_SEC, CLK_TCK" ms.date: "11/04/2016" -f1_keywords: ["CLOCKS_PER_SEC", "CLK_TCK"] +f1_keywords: ["CLOCKS_PER_SEC", "TIME/CLOCKS_PER_SEC", "CLK_TCK", "TIME/CLK_TCK"] helpviewer_keywords: ["CLOCKS_PER_SEC", "CLK_TCK constant"] ms.assetid: bc285106-383d-44cb-91bf-276ad7de57bf --- -# CLOCKS_PER_SEC, CLK_TCK +# `CLOCKS_PER_SEC`, `CLK_TCK` ## Syntax -``` +```C #include ``` @@ -20,5 +20,5 @@ The time in seconds is the value returned by the `clock` function, divided by `C ## See also -[clock](../c-runtime-library/reference/clock.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`clock`](./reference/clock.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/code-pages.md b/docs/c-runtime-library/code-pages.md index 677ae94612..e61fe0e5ee 100644 --- a/docs/c-runtime-library/code-pages.md +++ b/docs/c-runtime-library/code-pages.md @@ -6,7 +6,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["character sets [C++], code pages", "ANSI [C++], code pages", "system-default code page", "multibyte code pages [C++]", "localization [C++], code pages", "code pages [C++], types of", "locale code pages [C++]"] ms.assetid: 4a26fc42-185a-4add-98bf-a7b314ae6186 --- -# Code Pages +# Code pages A *code page* is a character set, which can include numbers, punctuation marks, and other glyphs. Different languages and locales may use different code pages. For example, ANSI code page 1252 is used for English and most European languages; OEM code page 932 is used for Japanese Kanji. @@ -14,7 +14,7 @@ A code page can be represented in a table as a mapping of characters to single-b The Microsoft runtime library uses the following types of code pages: -- System-default ANSI code page. By default, at startup the runtime system automatically sets the multibyte code page to the system-default ANSI code page, which is obtained from the operating system. The call: +- System-default ANSI code page. By default, at startup, the runtime system automatically sets the multibyte code page to the system-default ANSI code page, which is obtained from the operating system. The call: ```C setlocale ( LC_ALL, "" ); @@ -22,13 +22,13 @@ The Microsoft runtime library uses the following types of code pages: also sets the locale to the system-default ANSI code page. -- Locale code page. The behavior of a number of run-time routines is dependent on the current locale setting, which includes the locale code page. (For more information, see [Locale-Dependent Routines](../c-runtime-library/locale.md).) By default, all locale-dependent routines in the Microsoft run-time library use the code page that corresponds to the "C" locale. At run time, you can change or query the locale code page in use with a call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). +- Locale code page. The behavior of several run-time routines is dependent on the current locale setting, which includes the locale code page. (For more information, see [Locale](./locale.md).) By default, all locale-dependent routines in the Microsoft run-time library use the code page that corresponds to the "C" locale. At run time, you can change or query the locale code page in use with a call to [`setlocale`](./reference/setlocale-wsetlocale.md). -- Multibyte code page. The behavior of most of the multibyte-character routines in the run-time library depends on the current multibyte code page setting. By default, these routines use the system-default ANSI code page. At run-time you can query and change the multibyte code page with [_getmbcp](../c-runtime-library/reference/getmbcp.md) and [_setmbcp](../c-runtime-library/reference/setmbcp.md), respectively. +- Multibyte code page. The behavior of most of the multibyte-character routines in the run-time library depends on the current multibyte code page setting. By default, these routines use the system-default ANSI code page. At run-time you can query and change the multibyte code page with [`_getmbcp`](./reference/getmbcp.md) and [`_setmbcp`](./reference/setmbcp.md), respectively. -- The "C" locale is defined by ANSI to correspond to the locale in which C programs have traditionally executed. The code page for the "C" locale ("C" code page) corresponds to the ASCII character set. For example, in the "C" locale, **islower** returns true for the values 0x61 - 0x7A only. In another locale, **islower** may return `true` for these and other values, as defined by that locale. +- The "C" locale is defined by ANSI to correspond to the locale in which C programs have traditionally executed. The code page for the "C" locale ("C" code page) corresponds to the ASCII character set. For example, in the "C" locale, `islower` returns true for the values 0x61 - 0x7A only. In another locale, `islower` may return `true` for these and other values, as defined by that locale. ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/commit-to-disk-constants.md b/docs/c-runtime-library/commit-to-disk-constants.md index 5ab2a097bc..9b0fd03de3 100644 --- a/docs/c-runtime-library/commit-to-disk-constants.md +++ b/docs/c-runtime-library/commit-to-disk-constants.md @@ -6,13 +6,13 @@ f1_keywords: ["vc.constants"] helpviewer_keywords: ["commit-to-disk constants"] ms.assetid: 0b903b23-b4fa-431e-a937-51d95f695ecf --- -# Commit-To-Disk Constants +# Commit-to-disk constants **Microsoft Specific** ## Syntax -``` +```C #include ``` @@ -24,7 +24,7 @@ The commit-to-disk modes are as follows: - **c** - Writes the unwritten contents of the specified buffer to disk. This commit-to-disk functionality only occurs at explicit calls to either the [fflush](../c-runtime-library/reference/fflush.md) or the [_flushall](../c-runtime-library/reference/flushall.md) function. This mode is useful when dealing with sensitive data. For example, if your program terminates after a call to `fflush` or `_flushall`, you can be sure that your data reached the operating system's buffers. However, unless a file is opened with the **c** option, the data might never make it to disk if the operating system also terminates. + Writes the unwritten contents of the specified buffer to disk. This commit-to-disk functionality only occurs at explicit calls to either the [`fflush`](./reference/fflush.md) or the [`_flushall`](./reference/flushall.md) function. This mode is useful when dealing with sensitive data. For example, if your program terminates after a call to `fflush` or `_flushall`, you can be sure that your data reached the operating system's buffers. However, unless a file is opened with the **c** option, the data might never make it to disk if the operating system also terminates. - **n** @@ -33,9 +33,9 @@ The commit-to-disk modes are as follows: > [!NOTE] > The **c** and **n** options are not part of the ANSI standard for `fopen`, but are Microsoft extensions and should not be used where ANSI portability is desired. -## Using the Commit-to-Disk Feature with Existing Code +## Using the commit-to-disk feature with existing code -By default, calls to the [fflush](../c-runtime-library/reference/fflush.md) or [_flushall](../c-runtime-library/reference/flushall.md) library functions write data to buffers maintained by the operating system. The operating system determines the optimal time to actually write the data to disk. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system's buffers. You can give this capability to an existing program without rewriting it by linking its object files with COMMODE.OBJ. +By default, calls to the [`fflush`](./reference/fflush.md) or [`_flushall`](./reference/flushall.md) library functions write data to buffers maintained by the operating system. The operating system determines the optimal time to actually write the data to disk. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system's buffers. You can give this capability to an existing program without rewriting it by linking its object files with COMMODE.OBJ. In the resulting executable file, calls to `fflush` write the contents of the buffer directly to disk, and calls to `_flushall` write the contents of all buffers to disk. These two functions are the only ones affected by COMMODE.OBJ. @@ -43,7 +43,7 @@ In the resulting executable file, calls to `fflush` write the contents of the bu ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Stream I/O](./stream-i-o.md)\ +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/compatibility.md b/docs/c-runtime-library/compatibility.md index 124a06492e..45f753bf02 100644 --- a/docs/c-runtime-library/compatibility.md +++ b/docs/c-runtime-library/compatibility.md @@ -20,19 +20,19 @@ The UCRT also implements a large subset of the POSIX.1 (ISO/IEC 9945-1:1996, the Functions specific to the Microsoft implementation of Visual C++ are found in the vcruntime library. Many of these functions are for internal use and can't be called by user code. Some are documented for use in debugging and implementation compatibility. -The C++ standard reserves names that begin with an underscore in the global namespace to the implementation. Both the POSIX functions and Microsoft-specific runtime library functions are in the global namespace, but aren't part of the standard C runtime library. That's why the preferred Microsoft implementations of these functions have a leading underscore. For portability, the UCRT also supports the default names, but the Microsoft C++ compiler issues a deprecation warning when code that uses them is compiled. Only the default names are deprecated, not the functions themselves. To suppress the warning, define `_CRT_NONSTDC_NO_WARNINGS` before including any headers in code that uses the original POSIX names. Because the C standard doesn't allow non-standard names in header files, by default [`/std:c11`](../build/reference/std-specify-language-standard-version.md) and [`/std:c17`](../build/reference/std-specify-language-standard-version.md) don't expose the default names for POSIX functions, types, and macros. If these names are necessary, define `_CRT_DECLARE_NONSTDC_NAMES` to expose them. +The C++ standard reserves names that begin with an underscore in the global namespace to the implementation. Both the POSIX functions and Microsoft-specific runtime library functions are in the global namespace, but aren't part of the standard C runtime library. It's why the preferred Microsoft implementations of these functions have a leading underscore. For portability, the UCRT also supports the default names, but the Microsoft C++ compiler issues a deprecation warning when code that uses them is compiled. Only the default names are deprecated, not the functions themselves. To suppress the warning, define `_CRT_NONSTDC_NO_WARNINGS` before including any headers in code that uses the original POSIX names. Because the C standard doesn't allow non-standard names in header files, by default [`/std:c11`](../build/reference/std-specify-language-standard-version.md) and [`/std:c17`](../build/reference/std-specify-language-standard-version.md) don't expose the default names for POSIX functions, types, and macros. If these names are necessary, define `_CRT_DECLARE_NONSTDC_NAMES` to expose them. -Certain functions in the standard C library have a history of unsafe usage, because of misused parameters and unchecked buffers. These functions are often the source of security issues in code. Microsoft created a set of safer versions of these functions that verify parameter usage. They invoke the invalid parameter handler when an issue is detected at runtime. By default, the Microsoft C++ compiler issues a deprecation warning when a function is used that has a safer variant available. When you compile your code as C++, you can define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 to eliminate most warnings. This macro enables template overloads to call the safer variants while maintaining portable source code. To suppress the warning, define `_CRT_SECURE_NO_WARNINGS` before including any headers in code that uses these functions. For more information, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). +Certain functions in the standard C library have a history of unsafe usage, because of misused parameters and unchecked buffers. These functions are often the source of security issues in code. Microsoft created a set of safer versions of these functions that verify parameter usage. They invoke the invalid parameter handler when an issue is detected at runtime. By default, the Microsoft C++ compiler issues a deprecation warning when a function is used that has a safer variant available. When you compile your code as C++, you can define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 to eliminate most warnings. This macro enables template overloads to call the safer variants while maintaining portable source code. To suppress the warning, define `_CRT_SECURE_NO_WARNINGS` before including any headers in code that uses these functions. For more information, see [Security features in the CRT](./security-features-in-the-crt.md). Except as noted within the documentation for specific functions, the UCRT is compatible with the Windows API. Certain functions aren't supported in Windows Store or Universal Windows Platform ([UWP](/uwp)) apps. These functions are listed in [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). -## Related Articles +## Related articles -|Title|Description| -|-----------|-----------------| -|[UWP Apps, the Windows Runtime, and the C runtime](../c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md)|Describes when UCRT routines aren't compatible with Universal Windows apps or Microsoft Store apps.| -|[ANSI C Conformance](../c-runtime-library/ansi-c-compliance.md)|Describes standard-conforming names in the UCRT.| -|[UNIX](../c-runtime-library/unix.md)|Provides guidelines for porting programs to UNIX.| -|[Windows Platforms (CRT)](../c-runtime-library/windows-platforms-crt.md)|Lists the operating systems that are the CRT supports.| -|[Backward Compatibility](../c-runtime-library/backward-compatibility.md)|Describes how to map old CRT names to the new ones.| -|[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md)|Provides an overview of the CRT library (.lib) files and the associated compiler options.| +| Title | Description | +|---|---| +| [UWP apps, the Windows Runtime, and the C runtime](./windows-store-apps-the-windows-runtime-and-the-c-run-time.md) | Describes when UCRT routines aren't compatible with Universal Windows apps or Microsoft Store apps. | +| [ANSI C conformance](./ansi-c-compliance.md) | Describes standard-conforming names in the UCRT. | +| [UNIX](./unix.md) | Provides guidelines for porting programs to UNIX. | +| [Windows platforms (CRT)](./windows-platforms-crt.md) | Lists the operating systems that CRT supports. | +| [Backward compatibility](./backward-compatibility.md) | Describes how to map old CRT names to the new ones. | +| [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) | Provides an overview of the CRT library (.lib) files and the associated compiler options. | diff --git a/docs/c-runtime-library/complex-math-support.md b/docs/c-runtime-library/complex-math-support.md index bb38eaf611..218495fa17 100644 --- a/docs/c-runtime-library/complex-math-support.md +++ b/docs/c-runtime-library/complex-math-support.md @@ -7,88 +7,88 @@ helpviewer_keywords: ["complex numbers, math routines", "math routines", "comple --- # C complex math support -The Microsoft C Runtime library (CRT) provides complex math library functions, including all of those required by ISO C99. The compiler does not directly support a **`complex`** or **`_Complex`** keyword, therefore the Microsoft implementation uses structure types to represent complex numbers. +The Microsoft C Runtime library (CRT) provides complex math library functions, including all of the ones required by ISO C99. The compiler doesn't directly support a **`complex`** or **`_Complex`** keyword, therefore the Microsoft implementation uses structure types to represent complex numbers. -These functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ulp of the correctly rounded result, though there may be cases where there is greater inaccuracy. +These functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 unit of least precision (ULP) of the correctly rounded result, though there may be cases where there's greater inaccuracy. -The complex math routines rely on the floating point math library functions for their implementation. These functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that does not support SSE2, the slower x87 implementation is used. Because different implementations of the math library functions may use different CPU instructions and different algorithms to produce their results, the functions may produce different results across CPUs. In most cases, the results are within +/-1 ulp of the correctly rounded result, but the actual results may vary across CPUs. +The complex math routines rely on the floating point math library functions for their implementation. These functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that doesn't support SSE2, the slower x87 implementation is used. Because different implementations of the math library functions may use different CPU instructions and different algorithms to produce their results, the functions may produce different results across CPUs. In most cases, the results are within +/-1 ULP of the correctly rounded result, but the actual results may vary across CPUs. ## Types used in complex math -The Microsoft implementation of the complex.h header defines these types as equivalents for the C99 standard native complex types: +The Microsoft implementation of the `complex.h` header defines these types as equivalents for the C99 standard native complex types: -|Standard type|Microsoft type| -|-|-| -|**`float complex`** or **`float _Complex`**|**_Fcomplex**| -|**`double complex`** or **`double _Complex`**|**_Dcomplex**| -|**`long double complex`** or **`long double _Complex`**|**_Lcomplex**| +| Standard type | Microsoft type | +|---|---| +| **`float complex`** or **`float _Complex`** | **`_Fcomplex`** | +| **`double complex`** or **`double _Complex`** | **`_Dcomplex`** | +| **`long double complex`** or **`long double _Complex`** | **`_Lcomplex`** | -The math.h header defines a separate type, **struct _complex**, used for the [_cabs](../c-runtime-library/reference/cabs.md) function. The **struct _complex** type is not used by the equivalent complex math functions [cabs, cabsf, cabsl](../c-runtime-library/reference/cabs-cabsf-cabsl.md). +The `math.h` header defines a separate type, **`struct _complex`**, used for the [`_cabs`](./reference/cabs.md) function. The **`struct _complex`** type isn't used by the equivalent complex math functions [`cabs`, `cabsf`, `cabsl`](./reference/cabs-cabsf-cabsl.md). ## Complex constants and macros -**I** is defined as the complex type **_Fcomplex** initialized by `{ 0.0f, 1.0f }`. +**`I`** is defined as the complex type **`_Fcomplex`** initialized by `{ 0.0f, 1.0f }`. ## Trigonometric functions -|Function|Description| -|-|-| -|[cacos, cacosf, cacosl](../c-runtime-library/reference/cacos-cacosf-cacosl.md)|Compute the complex arc cosine of a complex number| -|[casin, casinf, casinl](../c-runtime-library/reference/casin-casinf-casinl.md)|Compute the complex arc sine of a complex number| -|[catan, catanf, catanl](../c-runtime-library/reference/catan-catanf-catanl.md)|Compute the complex arc tangent of a complex number| -|[ccos, ccosf, ccosl](../c-runtime-library/reference/ccos-ccosf-ccosl.md)|Compute the complex cosine of a complex number| -|[csin, csinf, csinl](../c-runtime-library/reference/csin-csinf-csinl.md)|Compute the complex sine of a complex number| -|[ctan, ctanf, ctanl](../c-runtime-library/reference/ctan-ctanf-ctanl.md)|Compute the complex tangent of a complex number| +| Function | Description | +|---|---| +| [`cacos`, `cacosf`, `cacosl`](./reference/cacos-cacosf-cacosl.md) | Compute the complex arc cosine of a complex number | +| [`casin`, `casinf`, `casinl`](./reference/casin-casinf-casinl.md) | Compute the complex arc sine of a complex number | +| [`catan`, `catanf`, `catanl`](./reference/catan-catanf-catanl.md) | Compute the complex arc tangent of a complex number | +| [`ccos`, `ccosf`, `ccosl`](./reference/ccos-ccosf-ccosl.md) | Compute the complex cosine of a complex number | +| [`csin`, `csinf`, `csinl`](./reference/csin-csinf-csinl.md) | Compute the complex sine of a complex number | +| [`ctan`, `ctanf`, `ctanl`](./reference/ctan-ctanf-ctanl.md) | Compute the complex tangent of a complex number | ## Hyperbolic functions -|Function|Description| -|-|-| -|[cacosh, cacoshf, cacoshl](../c-runtime-library/reference/cacosh-cacoshf-cacoshl.md)|Compute the complex arc hyperbolic cosine of a complex number| -|[casinh, casinhf, casinhl](../c-runtime-library/reference/casinh-casinhf-casinhl.md)|Compute the complex arc hyperbolic sine of a complex number| -|[catanh, catanhf, catanhl](../c-runtime-library/reference/catanh-catanhf-catanhl.md)|Compute the complex arc hyperbolic tangent of a complex number| -|[ccosh, ccoshf, ccoshl](../c-runtime-library/reference/ccosh-ccoshf-ccoshl.md)|Compute the complex hyperbolic cosine of a complex number| -|[csinh, csinhf, csinhl](../c-runtime-library/reference/csinh-csinhf-csinhl.md)|Compute the complex hyperbolic sine of a complex number| -|[ctanh, ctanhf, ctanhl](../c-runtime-library/reference/ctanh-ctanhf-ctanhl.md)|Compute the complex hyperbolic tangent of a complex number| +| Function | Description | +|---|---| +| [`cacosh`, `cacoshf`, `cacoshl`](./reference/cacosh-cacoshf-cacoshl.md) | Compute the complex arc hyperbolic cosine of a complex number | +| [`casinh`, `casinhf`, `casinhl`](./reference/casinh-casinhf-casinhl.md) | Compute the complex arc hyperbolic sine of a complex number | +| [`catanh`, `catanhf`, `catanhl`](./reference/catanh-catanhf-catanhl.md) | Compute the complex arc hyperbolic tangent of a complex number | +| [`ccosh`, `ccoshf`, `ccoshl`](./reference/ccosh-ccoshf-ccoshl.md) | Compute the complex hyperbolic cosine of a complex number | +| [`csinh`, `csinhf`, `csinhl`](./reference/csinh-csinhf-csinhl.md) | Compute the complex hyperbolic sine of a complex number | +| [`ctanh`, `ctanhf`, `ctanhl`](./reference/ctanh-ctanhf-ctanhl.md) | Compute the complex hyperbolic tangent of a complex number | ## Exponential and logarithmic functions -|Function|Description| -|-|-| -|[cexp, cexpf, cexpl](../c-runtime-library/reference/cexp-cexpf-cexpl.md)|Compute the complex base-*e* exponential of a complex number| -|[clog, clogf, clogl](../c-runtime-library/reference/clog-clogf-clogl.md)|Compute the complex natural (base-*e*) logarithm of a complex number| -|[clog10, clog10f, clog10l](../c-runtime-library/reference/clog10-clog10f-clog10l.md)|Compute the complex base-10 logarithm of a complex number| +| Function | Description | +|---|---| +| [`cexp`, `cexpf`, `cexpl`](./reference/cexp-cexpf-cexpl.md) | Compute the complex base-*e* exponential of a complex number | +| [`clog`, `clogf`, `clogl`](./reference/clog-clogf-clogl.md) | Compute the complex natural (base-*e*) logarithm of a complex number | +| [`clog10`, `clog10f`, `clog10l`](./reference/clog10-clog10f-clog10l.md) | Compute the complex base-10 logarithm of a complex number | ## Power and absolute-value functions -|Function|Description| -|-|-| -|[cabs, cabsf, cabsl](../c-runtime-library/reference/cabs-cabsf-cabsl.md)|Compute the complex absolute value (also called the norm, modulus, or magnitude) of a complex number| -|[cpow, cpowf, cpowl](../c-runtime-library/reference/cpow-cpowf-cpowl.md)|Compute the complex power function xy| -|[csqrt, csqrtf, csqrtl](../c-runtime-library/reference/csqrt-csqrtf-csqrtl.md)|Compute the complex square root of a complex number| +| Function | Description | +|---|---| +| [`cabs`, `cabsf`, `cabsl`](./reference/cabs-cabsf-cabsl.md) | Compute the complex absolute value (also called the norm, modulus, or magnitude) of a complex number | +| [`cpow`, `cpowf`, `cpowl`](./reference/cpow-cpowf-cpowl.md) | Compute the complex power function | +| [`csqrt`, `csqrtf`, `csqrtl`](./reference/csqrt-csqrtf-csqrtl.md) | Compute the complex square root of a complex number | ## Manipulation functions -|Function|Description| -|-|-| -|[_Cbuild, _FCbuild, _LCbuild](../c-runtime-library/reference/cbuild-fcbuild-lcbuild.md)|Construct a complex number from real and imaginary parts| -|[carg, cargf, cargl](../c-runtime-library/reference/carg-cargf-cargl.md)|Compute the argument (also called the phase angle) of a complex number| -|[cimag, cimagf, cimagl](../c-runtime-library/reference/cimag-cimagf-cimagl.md)|Compute the imaginary part of a complex number| -|[conj, conjf, conjl](../c-runtime-library/reference/conj-conjf-conjl.md)|Compute the complex conjugate of a complex number| -|[cproj, cprojf, cprojl](../c-runtime-library/reference/cproj-cprojf-cprojl.md)|Compute a projection of a complex number onto the Riemann sphere| -|[creal, crealf, creall](../c-runtime-library/reference/creal-crealf-creall.md)|Compute the real part of a complex number| -|[norm, normf, norml](../c-runtime-library/reference/norm-normf-norml1.md)|Compute the squared magnitude of a complex number| +| Function | Description | +|---|---| +| [`_Cbuild`, `_FCbuild`, `_LCbuild`](./reference/cbuild-fcbuild-lcbuild.md) | Construct a complex number from real and imaginary parts | +| [`carg`, `cargf`, `cargl`](./reference/carg-cargf-cargl.md) | Compute the argument (also called the phase angle) of a complex number | +| [`cimag`, `cimagf`, `cimagl`](./reference/cimag-cimagf-cimagl.md) | Compute the imaginary part of a complex number | +| [`conj`, `conjf`, `conjl`](./reference/conj-conjf-conjl.md) | Compute the complex conjugate of a complex number | +| [`cproj`, `cprojf`, `cprojl`](./reference/cproj-cprojf-cprojl.md) | Compute a projection of a complex number onto the Riemann sphere | +| [`creal`, `crealf`, `creall`](./reference/creal-crealf-creall.md) | Compute the real part of a complex number | +| [`norm`, `normf`, `norml`](./reference/norm-normf-norml1.md) | Compute the squared magnitude of a complex number | ## Operation functions -Because complex numbers are not a native type in the Microsoft compiler, the standard arithmetic operators are not defined on complex types. For convenience, these complex math library functions are provided to enable limited manipulation of complex numbers in user code: +Because complex numbers aren't a native type in the Microsoft compiler, the standard arithmetic operators aren't defined on complex types. For convenience, these complex math library functions are provided to enable limited manipulation of complex numbers in user code: -|Function|Description| -|-|-| -|[_Cmulcc, _FCmulcc, _LCmulcc](../c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md)|Multiply two complex numbers| -|[_Cmulcr, _FCmulcr, _LCmulcr](../c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md)|Multiply a complex and a floating-point number| +| Function | Description | +|---|---| +| [`_Cmulcc`, `_FCmulcc`, `_LCmulcc`](./reference/cmulcc-fcmulcc-lcmulcc.md) | Multiply two complex numbers | +| [`_Cmulcr`, `_FCmulcr`, `_LCmulcr`](./reference/cmulcr-fcmulcr-lcmulcr.md) | Multiply a complex and a floating-point number | ## See also [Type-generic math](tgmath.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/console-and-port-i-o.md b/docs/c-runtime-library/console-and-port-i-o.md index 42a79871bb..df8063f300 100644 --- a/docs/c-runtime-library/console-and-port-i-o.md +++ b/docs/c-runtime-library/console-and-port-i-o.md @@ -3,33 +3,32 @@ description: "Learn more about: Console and Port I/O" title: "Console and Port I/O" ms.date: "11/04/2016" helpviewer_keywords: ["routines, console and port I/O", "routines", "ports, I/O routines", "I/O [CRT], console", "I/O [CRT], port", "I/O routines, console and port I/O"] -ms.assetid: 0eee1c92-9b3d-41e0-a43a-257e546eeec8 --- -# Console and Port I/O +# Console and port I/O -These routines read and write on your console or on the specified port. The console I/O routines are not compatible with stream I/O or low-level I/O library routines. The console or port does not have to be opened or closed before I/O is performed, so there are no open or close routines in this category. In the Windows operating systems, the output from these functions is always directed to the console and cannot be redirected. +These routines read and write on your console or on the specified port. The console I/O routines aren't compatible with stream I/O or low-level I/O library routines. The console or port doesn't have to be opened or closed before I/O is performed, so there are no open or close routines in this category. In the Windows operating systems, the output from these functions is always directed to the console and can't be redirected. -## Console and Port I/O Routines +## Console and port I/O routines -|Routine|Use| -|-------------|---------| -|[_cgets, _cgetws](../c-runtime-library/cgets-cgetws.md), [_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md)|Read string from console| -|[_cprintf, _cwprintf](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md), [_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](../c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)|Write formatted data to console| -|[_cputs](../c-runtime-library/reference/cputs-cputws.md)|Write string to console| -|[_cscanf, _cwscanf](../c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md), [_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](../c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)|Read formatted data from console| -|[_getch, _getwch](../c-runtime-library/reference/getch-getwch.md)|Read character from console| -|[_getche, _getwche](../c-runtime-library/reference/getch-getwch.md)|Read character from console and echo it| -|[_inp](../c-runtime-library/inp-inpw-inpd.md)|Read one byte from specified I/O port| -|[_inpd](../c-runtime-library/inp-inpw-inpd.md)|Read double word from specified I/O port| -|[_inpw](../c-runtime-library/inp-inpw-inpd.md)|Read 2-byte word from specified I/O port| -|[_kbhit](../c-runtime-library/reference/kbhit.md)|Check for keystroke at console; use before attempting to read from console| -|[_outp](../c-runtime-library/outp-outpw-outpd.md)|Write one byte to specified I/O port| -|[_outpd](../c-runtime-library/outp-outpw-outpd.md)|Write double word to specified I/O port| -|[_outpw](../c-runtime-library/outp-outpw-outpd.md)|Write word to specified I/O port| -|[_putch, _putwch](../c-runtime-library/reference/putch-putwch.md)|Write character to console| -|[_ungetch, _ungetwch](../c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)|"Unget" last character read from console so it becomes next character read| +| Routine | Use | +|---|---| +| [`_cgets`, `_cgetws`](./cgets-cgetws.md), [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | Read string from console | +| [`_cprintf`, `_cwprintf`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md), [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](./reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) | Write formatted data to console | +| [`_cputs`](./reference/cputs-cputws.md) | Write string to console | +| [`_cscanf`, `_cwscanf`](./reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md), [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](./reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md) | Read formatted data from console | +| [`_getch`, `_getwch`](./reference/getch-getwch.md) | Read character from console | +| [`_getche`, `_getwche`](./reference/getch-getwch.md) | Read character from console and echo it | +| [`_inp`](./inp-inpw-inpd.md) | Read a byte from the specified I/O port | +| [`_inpd`](./inp-inpw-inpd.md) | Read double word from specified I/O port | +| [`_inpw`](./inp-inpw-inpd.md) | Read 2-byte word from specified I/O port | +| [`_kbhit`](./reference/kbhit.md) | Check for keystroke at console; use before attempting to read from console | +| [`_outp`](./outp-outpw-outpd.md) | Write a byte to the specified I/O port | +| [`_outpd`](./outp-outpw-outpd.md) | Write double word to specified I/O port | +| [`_outpw`](./outp-outpw-outpd.md) | Write word to specified I/O port | +| [`_putch`, `_putwch`](./reference/putch-putwch.md) | Write character to console | +| [`_ungetch`, `_ungetwch`](./reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) | "Unget" last character read from console so it becomes next character read | ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Input and output](./input-and-output.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/constant-and-global-variable-mappings.md b/docs/c-runtime-library/constant-and-global-variable-mappings.md index 1a99b8b921..92f33e1dd7 100644 --- a/docs/c-runtime-library/constant-and-global-variable-mappings.md +++ b/docs/c-runtime-library/constant-and-global-variable-mappings.md @@ -2,26 +2,26 @@ description: "Learn more about: Constant and Global Variable Mappings" title: "Constant and Global Variable Mappings" ms.date: "11/04/2016" -f1_keywords: ["_tenviron", "_TEOF", "_tfinddata_t"] -helpviewer_keywords: ["tfinddatat function", "tenviron function", "TEOF type", "_TEOF type", "generic-text mappings", "_tenviron function", "_tfinddata_t function"] +f1_keywords: ["_tenviron", "TCHAR/_tenviron", "_TEOF", "TCHAR/_TEOF", "_tpgmptr", "TCHAR/_tpgmptr"] +helpviewer_keywords: ["_tenviron global constant", "_TEOF global constant", "_tpgmptr global constant"] ms.assetid: 3af4fd3e-9ed5-4ed9-96fd-7031e5126fd1 --- -# Constant and Global Variable Mappings +# Constant and global variable mappings These generic-text constant, global variable, and standard-type mappings are defined in TCHAR.H and depend on whether the constant `_UNICODE` or `_MBCS` has been defined in your program. -### Generic-Text Constant and Global Variable Mappings +### Generic-text constant and global variable mappings -|Generic-text - object name|SBCS (_UNICODE, _MBCS not defined)|_MBCS defined|_UNICODE defined| -|----------------------------------|--------------------------------------------|--------------------|-----------------------| -|`_TEOF`|`EOF`|`EOF`|`WEOF`| -|`_tenviron`|`_environ`|`_environ`|`_wenviron`| -|`_tpgmptr`|`_pgmptr`|`_pgmptr`|`_wpgmptr`| +| Generic-text - object name | SBCS (`_UNICODE`, `_MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_TEOF` | `EOF` | `EOF` | `WEOF` | +| `_tenviron` | `_environ` | `_environ` | `_wenviron` | +| `_tpgmptr` | `_pgmptr` | `_pgmptr` | `_wpgmptr` | ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/control-flags.md b/docs/c-runtime-library/control-flags.md index 39bd64088d..5ba1384bfc 100644 --- a/docs/c-runtime-library/control-flags.md +++ b/docs/c-runtime-library/control-flags.md @@ -6,18 +6,18 @@ f1_keywords: ["c.flags"] helpviewer_keywords: ["flags, control", "heap allocation, control flags", "debug heap, control flags"] ms.assetid: 8dbd24a5-0633-42d1-9771-776db338465f --- -# Control Flags +# Control flags -The debug version of the Microsoft C run-time library uses the following flags to control the heap allocation and reporting process. For more information, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +The debug version of the Microsoft C run-time library uses the following flags to control the heap allocation and reporting process. For more information, see [CRT debugging techniques](./crt-debugging-techniques.md). -|Flag|Description| -|----------|-----------------| -|[_CRTDBG_MAP_ALLOC](../c-runtime-library/crtdbg-map-alloc.md)|Maps the base heap functions to their debug version counterparts| -|[_DEBUG](../c-runtime-library/debug.md)|Enables the use of the debugging versions of the run-time functions| -|[_crtDbgFlag](../c-runtime-library/crtdbgflag.md)|Controls how the debug heap manager tracks allocations| +| Flag | Description | +|---|---| +| [`_CRTDBG_MAP_ALLOC`](./crtdbg-map-alloc.md) | Maps the base heap functions to their debug version counterparts | +| [`_DEBUG`](./debug.md) | Enables the use of the debugging versions of the run-time functions | +| [`_crtDbgFlag`](./crtdbgflag.md) | Controls how the debug heap manager tracks allocations | -These flags can be defined with a /D command-line option or with a `#define` directive. When the flag is defined with `#define`, the directive must appear before the header file include statement for the routine declarations. +These flags can be defined with a /D command-line option or with a `#define` directive. When the flag is defined with `#define`, the directive must appear before the header file `#include` directive for the routine declarations. ## See also -[Global Variables and Standard Types](../c-runtime-library/global-variables-and-standard-types.md) +[Global variables and standard types](./global-variables-and-standard-types.md) diff --git a/docs/c-runtime-library/controlling-streams.md b/docs/c-runtime-library/controlling-streams.md index 995d1e12d5..7bdf6321eb 100644 --- a/docs/c-runtime-library/controlling-streams.md +++ b/docs/c-runtime-library/controlling-streams.md @@ -3,15 +3,14 @@ title: "Controlling Streams" description: "An overview of working with streams in the Microsoft C runtime library." ms.date: "11/04/2016" ms.topic: "conceptual" -f1_keywords: ["Controlling Streams"] helpviewer_keywords: ["streams, controlling", "controlling streams", "streams"] ms.assetid: 267e9013-9afc-45f6-91e3-ca093230d9d9 --- -# Controlling Streams +# Controlling streams -[fopen](../c-runtime-library/reference/fopen-wfopen.md) returns the address of an object of type `FILE`. You use this address as the `stream` argument to several library functions to perform various operations on an open file. For a byte stream, all input takes place as if each character is read by calling [fgetc](../c-runtime-library/reference/fgetc-fgetwc.md), and all output takes place as if each character is written by calling [fputc](../c-runtime-library/reference/fputc-fputwc.md). For a wide stream, all input takes place as if each character is read by calling [fgetwc](../c-runtime-library/reference/fgetc-fgetwc.md), and all output takes place as if each character is written by calling [fputwc](../c-runtime-library/reference/fputc-fputwc.md). +[`fopen`](./reference/fopen-wfopen.md) returns the address of an object of type `FILE`. You use this address as the `stream` argument to several library functions to perform various operations on an open file. For a byte stream, all input takes place as if each character is read by calling [`fgetc`](./reference/fgetc-fgetwc.md). All output takes place as if each character is written by calling [`fputc`](./reference/fputc-fputwc.md). For a wide stream, all input takes place as if each character is read by calling [`fgetwc`](./reference/fgetc-fgetwc.md). All output takes place as if each character is written by calling [`fputwc`](./reference/fputc-fputwc.md). -You can close a file by calling [fclose](../c-runtime-library/reference/fclose-fcloseall.md), after which the address of the `FILE` object is invalid. +You can close a file by calling [`fclose`](./reference/fclose-fcloseall.md), after which the address of the `FILE` object is invalid. A `FILE` object stores the state of a stream, including: @@ -21,14 +20,14 @@ A `FILE` object stores the state of a stream, including: - A file-position indicator specifies the next byte in the stream to read or write, if the file can support positioning requests. -- A [stream state](../c-runtime-library/stream-states.md) specifies whether the stream will accept reads and/or writes and whether the stream is unbound, byte oriented, or wide oriented. +- A [stream state](./stream-states.md) specifies whether the stream will accept reads and/or writes and whether the stream is unbound, byte oriented, or wide oriented. -- A conversion state remembers the state of any partly assembled or generated generalized multibyte character, as well as any shift state for the sequence of bytes in the file). +- A conversion state remembers the state of any partly assembled or generated generalized multibyte character, and any shift state for the sequence of bytes in the file). -- A file buffer specifies the address and size of an array object that library functions can use to improve the performance of read and write operations to the stream. +- A file buffer specifies the address and size of an array object. Library functions can use it to improve the performance of read and write operations to the stream. -Do not alter any value stored in a `FILE` object or in a file buffer that you specify for use with that object. You cannot copy a `FILE` object and portably use the address of the copy as a `stream` argument to a library function. +Don't alter any value stored in a `FILE` object or in a file buffer that you specify for use with that object. You can't copy a `FILE` object and portably use the address of the copy as a `stream` argument to a library function. ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md) +[Files and streams](./files-and-streams.md) diff --git a/docs/c-runtime-library/country-region-strings.md b/docs/c-runtime-library/country-region-strings.md index 2f44a1e86a..30b8889911 100644 --- a/docs/c-runtime-library/country-region-strings.md +++ b/docs/c-runtime-library/country-region-strings.md @@ -4,45 +4,45 @@ description: "Learn more about: Country/Region Strings" ms.date: "1/29/2020" helpviewer_keywords: ["country/region strings"] --- -# Country/Region Strings +# Country/region strings Country and region strings can be combined with a language string to create a locale specification for the `setlocale`, `_wsetlocale`, `_create_locale`, and `_wcreate_locale` functions. For lists of country and region names that are supported by various Windows operating system versions, see the **Language**, **Location**, and **Language tag** columns of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. For an example of code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). -## Additional supported country and region strings +## Other supported country and region strings -The Microsoft C run-time library implementation also supports the following additional country/region strings and abbreviations: +The Microsoft C run-time library implementation also supports the following country/region strings and abbreviations: -|Country/region string|Abbreviation|Equivalent locale name| -|----------------------------|------------------|----------------------------| -|`america`|`USA`|`en-US`| -|`britain`|`GBR`|`en-GB`| -|`china`|`CHN`|`zh-CN`| -|`czech`|`CZE`|`cs-CZ`| -|`england`|`GBR`|`en-GB`| -|`great britain`|`GBR`|`en-GB`| -|`holland`|`NLD`|`nl-NL`| -|`hong-kong`|`HKG`|`zh-HK`| -|`new-zealand`|`NZL`|`en-NZ`| -|`nz`|`NZL`|`en-NZ`| -|`pr china`|`CHN`|`zh-CN`| -|`pr-china`|`CHN`|`zh-CN`| -|`puerto-rico`|`PRI`|`es-PR`| -|`slovak`|`SVK`|`sk-SK`| -|`south africa`|`ZAF`|`af-ZA`| -|`south korea`|`KOR`|`ko-KR`| -|`south-africa`|`ZAF`|`af-ZA`| -|`south-korea`|`KOR`|`ko-KR`| -|`trinidad & tobago`|`TTO`|`en-TT`| -|`uk`|`GBR`|`en-GB`| -|`united-kingdom`|`GBR`|`en-GB`| -|`united-states`|`USA`|`en-US`| -|`us`|`USA`|`en-US`| +| Country/region string | Abbreviation | Equivalent locale name | +|---|---|---| +| `america` | `USA` | `en-US` | +| `britain` | `GBR` | `en-GB` | +| `china` | `CHN` | `zh-CN` | +| `czech` | `CZE` | `cs-CZ` | +| `england` | `GBR` | `en-GB` | +| `great britain` | `GBR` | `en-GB` | +| `holland` | `NLD` | `nl-NL` | +| `hong-kong` | `HKG` | `zh-HK` | +| `new-zealand` | `NZL` | `en-NZ` | +| `nz` | `NZL` | `en-NZ` | +| `pr china` | `CHN` | `zh-CN` | +| `pr-china` | `CHN` | `zh-CN` | +| `puerto-rico` | `PRI` | `es-PR` | +| `slovak` | `SVK` | `sk-SK` | +| `south africa` | `ZAF` | `af-ZA` | +| `south korea` | `KOR` | `ko-KR` | +| `south-africa` | `ZAF` | `af-ZA` | +| `south-korea` | `KOR` | `ko-KR` | +| `trinidad & tobago` | `TTO` | `en-TT` | +| `uk` | `GBR` | `en-GB` | +| `united-kingdom` | `GBR` | `en-GB` | +| `united-states` | `USA` | `en-US` | +| `us` | `USA` | `en-US` | ## See also -[Locale Names, Languages, and Country/Region Strings](../c-runtime-library/locale-names-languages-and-country-region-strings.md)
-[Language Strings](../c-runtime-library/language-strings.md)
-[`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[`_create_locale`, `_wcreate_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) +[Locale names, Languages, and Country/Region strings](./locale-names-languages-and-country-region-strings.md)\ +[Language strings](./language-strings.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md) diff --git a/docs/c-runtime-library/crt-debug-heap-details.md b/docs/c-runtime-library/crt-debug-heap-details.md new file mode 100644 index 0000000000..5a0d180c7d --- /dev/null +++ b/docs/c-runtime-library/crt-debug-heap-details.md @@ -0,0 +1,325 @@ +--- +title: CRT debug heap details +description: The debug heap provides powerful tools to help solve memory allocation problems. Learn about the tools and how they help with problems such as leaks and overruns. +ms.date: 02/03/2023 +helpviewer_keywords: + - "debug heap, accessing" + - "heap functions" + - "_CRTDBG_CHECK_ALWAYS_DF macro" + - "_CrtMemDumpStatistics function" + - "debugging [C++], debug heap" + - "_CRT_BLOCK macro" + - "DBGINT.H file" + - "_CrtMemDumpAllObjectsSince function" + - "_crtBreakAlloc global variable" + - "_CrtMemState function" + - "_CLIENT_BLOCK macro" + - "_FREE_BLOCK block" + - "_CrtMemBlockHeader function" + - "heap state reporting functions" + - "_CRTDBG_ALLOC_MEM_DF macro" + - "_CrtSetBreakAlloc function" + - "memory blocks, allocation types on debug heap" + - "debugging [C++], CRT debug support" + - "debug heap, tracking heap allocation requests" + - "memory allocation, debug heap" + - "_NORMAL_BLOCK block" + - "crtBreakAlloc global variable" + - "_CrtDoForAllClientObjects function" + - "new operator, using debug heap from C++" + - "_CrtSetDumpClient function" + - "debugging [CRT], heap-related problems" + - "debug heap, solving memory allocation problems" + - "_CrtMemCheckpoint function" + - "debug builds, linking to debug heap" + - "_IGNORE_BLOCK block" + - "_crtDbgFlag function" + - "client blocks, specifying subtypes" + - "memory leaks, tracking" + - "_CrtSetDbgFlag function" + - "nBlockUse method" + - "memory leaks, CRT debug library functions" + - "_CRTDBG_DELAY_FREE_MEM_DF macro" + - "allocation request numbers" + - "_CRTDBG_LEAK_CHECK_DF macro" + - "debug heap" + - "memory, debugging" + - "_CrtReportBlockType function" + - "_CrtDumpMemoryLeaks function" + - "_CrtCheckMemory function" + - "debug heap, CRT" + - "memory blocks, free" + - "_BLOCK_TYPE macro" + - "debug heap, memory blocks" + - "heap allocation, debug" + - "debugging memory leaks" + - "_BLOCK_SUBTYPE macro" + - "debug heap, using from C++" + - "_CrtMemDifference function" + - "heap allocation, tracking requests" + - "debugging [Visual Studio], debug heap" + - "delete operator, using debug heap from C++" + - "blocks, types of on the debug heap" + - "_CRTDBG_CHECK_CRT_DF macro" + - "debug heap, reporting functions" +--- +# CRT debug heap details + +The CRT debug heap and related functions provide many ways to track and debug memory management issues in your code. You can use it to find buffer overruns, and to track and report on memory allocations and memory state. It also has support for creating your own debug allocation functions for your unique app needs. + +## Find buffer overruns with debug heap + +Two of the most common and intractable problems that programmers encounter are overwriting the end of an allocated buffer and memory leaks (failing to free allocations after they're no longer needed). The debug heap provides powerful tools to solve memory allocation problems of this kind. + +The Debug versions of the heap functions call the standard or base versions used in Release builds. When you request a memory block, the debug heap manager allocates from the base heap a slightly larger block of memory than you requested and returns a pointer to your portion of that block. For example, suppose your application contains the call: `malloc( 10 )`. In a Release build, [`malloc`](./reference/malloc.md) would call the base heap allocation routine requesting an allocation of 10 bytes. In a Debug build, however, `malloc` would call [`_malloc_dbg`](./reference/malloc-dbg.md), which would then call the base heap allocation routine requesting an allocation of 10 bytes plus approximately 36 bytes of extra memory. All the resulting memory blocks in the debug heap are connected in a single linked list, ordered according to when they were allocated. + +The extra memory allocated by the debug heap routines is used for bookkeeping information. It has pointers that link debug memory blocks together, and small buffers on either side of your data to catch overwrites of the allocated region. + +Currently, the block header structure used to store the debug heap's bookkeeping information is declared in the `` header and defined in the `` CRT source file. Conceptually, it's similar to this structure: + +```cpp +typedef struct _CrtMemBlockHeader +{ +// Pointer to the block allocated just before this one: + _CrtMemBlockHeader* _block_header_next; +// Pointer to the block allocated just after this one: + _CrtMemBlockHeader* _block_header_prev; + char const* _file_name; + int _line_number; + + int _block_use; // Type of block + size_t _data_size; // Size of user block + + long _request_number; // Allocation number +// Buffer just before (lower than) the user's memory: + unsigned char _gap[no_mans_land_size]; + + // Followed by: + // unsigned char _data[_data_size]; + // unsigned char _another_gap[no_mans_land_size]; +} _CrtMemBlockHeader; +``` + +The `no_mans_land` buffers on either side of the user data area of the block are currently 4 bytes in size, and are filled with a known byte value used by the debug heap routines to verify that the limits of the user's memory block haven't been overwritten. The debug heap also fills new memory blocks with a known value. If you elect to keep freed blocks in the heap's linked list, these freed blocks are also filled with a known value. Currently, the actual byte values used are as follows: + +|Code |Description | +|---------|---------| +|`no_mans_land` (0xFD) | The "no_mans_land" buffers on either side of the memory used by an application are currently filled with 0xFD. | +|Freed blocks (0xDD) | The freed blocks kept unused in the debug heap's linked list when the `_CRTDBG_DELAY_FREE_MEM_DF` flag is set are currently filled with 0xDD. | +|New objects (0xCD) | New objects are filled with 0xCD when they're allocated.| + +## Types of blocks on the debug heap + +Every memory block in the debug heap is assigned to one of five allocation types. These types are tracked and reported differently for purposes of leak detection and state reporting. You can specify a block's type by allocating it using a direct call to one of the debug heap allocation functions such as [`_malloc_dbg`](./reference/malloc-dbg.md). The five types of memory blocks in the debug heap (set in the `nBlockUse` member of the `_CrtMemBlockHeader` structure) are as follows: + +`_NORMAL_BLOCK`\ +A call to [`malloc`](./reference/malloc.md) or [`calloc`](./reference/calloc.md) creates a Normal block. If you intend to use Normal blocks only, and have no need for Client blocks, you may want to define [`_CRTDBG_MAP_ALLOC`](./crtdbg-map-alloc.md). `_CRTDBG_MAP_ALLOC` causes all heap allocation calls to be mapped to their debug equivalents in Debug builds. It allows storage of file name and line number information about each allocation call in the corresponding block header. + +`_CRT_BLOCK`\ +The memory blocks allocated internally by many run-time library functions are marked as CRT blocks so they can be handled separately. As a result, leak detection and other operations may remain unaffected by them. An allocation must never allocate, reallocate, or free any block of CRT type. + +`_CLIENT_BLOCK`\ +An application can keep special track of a given group of allocations for debugging purposes by allocating them as this type of memory block, using explicit calls to the debug heap functions. MFC, for example, allocates all `CObject` objects as Client blocks; other applications might keep different memory objects in Client blocks. Subtypes of Client blocks can also be specified for greater tracking granularity. To specify subtypes of Client blocks, shift the number left by 16 bits and `OR` it with `_CLIENT_BLOCK`. For example: + +```cpp +#define MYSUBTYPE 4 +freedbg(pbData, _CLIENT_BLOCK|(MYSUBTYPE<<16)); +``` + +A client-supplied hook function for dumping the objects stored in Client blocks can be installed using [`_CrtSetDumpClient`](./reference/crtsetdumpclient.md), and will then be called whenever a Client block is dumped by a debug function. Also, [`_CrtDoForAllClientObjects`](./reference/crtdoforallclientobjects.md) can be used to call a given function supplied by the application for every Client block in the debug heap. + +`_FREE_BLOCK`\ +Normally, blocks that are freed are removed from the list. To check that freed memory isn't written to, or to simulate low memory conditions, you can keep freed blocks on the linked list, marked as Free, and filled with a known byte value (currently 0xDD). + +`_IGNORE_BLOCK`\ +It's possible to turn off the debug heap operations for some interval. During this time, memory blocks are kept on the list, but are marked as Ignore blocks. + +To determine the type and subtype of a given block, use the function [`_CrtReportBlockType`](./reference/crtreportblocktype.md) and the macros `_BLOCK_TYPE` and `_BLOCK_SUBTYPE`. The macros are defined in `` as follows: + +```cpp +#define _BLOCK_TYPE(block) (block & 0xFFFF) +#define _BLOCK_SUBTYPE(block) (block >> 16 & 0xFFFF) +``` + +## Check for heap integrity and memory leaks + +Many of the debug heap's features must be accessed from within your code. The following section describes some of the features and how to use them. + +`_CrtCheckMemory`\ +You can use a call to [`_CrtCheckMemory`](./reference/crtcheckmemory.md), for example, to check the heap's integrity at any point. This function inspects every memory block in the heap. It verifies that the memory block header information is valid, and confirms that the buffers haven't been modified. + +`_CrtSetDbgFlag`\ +You can control how the debug heap keeps track of allocations using an internal flag, [`_crtDbgFlag`](./crtdbgflag.md), which can be read and set using the [`_CrtSetDbgFlag`](./reference/crtsetdbgflag.md) function. By changing this flag, you can instruct the debug heap to check for memory leaks when the program exits and report any leaks that are detected. Similarly, you can tell the heap to leave freed memory blocks in the linked list, to simulate low-memory situations. When the heap is checked, these freed blocks are inspected in their entirety to ensure that they haven't been disturbed. + +The `_crtDbgFlag` flag contains the following bit fields: + +| Bit field | Default value | Description | +|---|---|---| +| `_CRTDBG_ALLOC_MEM_DF` | On | Turns on debug allocation. When this bit is off, allocations remain chained together, but their block type is `_IGNORE_BLOCK`. | +| `_CRTDBG_DELAY_FREE_MEM_DF` | Off | Prevents memory from actually being freed, as for simulating low-memory conditions. When this bit is on, freed blocks are kept in the debug heap's linked list but are marked as `_FREE_BLOCK` and filled with a special byte value. | +| `_CRTDBG_CHECK_ALWAYS_DF` | Off | Causes `_CrtCheckMemory` to be called at every allocation and deallocation. Execution is slower, but it catches errors quickly. | +| `_CRTDBG_CHECK_CRT_DF` | Off | Causes blocks marked as type `_CRT_BLOCK` to be included in leak-detection and state-difference operations. When this bit is off, the memory used internally by the run-time library is ignored during such operations. | +| `_CRTDBG_LEAK_CHECK_DF` | Off | Causes leak checking to be performed at program exit via a call to `_CrtDumpMemoryLeaks`. An error report is generated if the application has failed to free all the memory that it allocated. | + +## Configure the debug heap + +All calls to heap functions such as `malloc`, `free`, `calloc`, `realloc`, `new`, and `delete` resolve to debug versions of those functions that operate in the debug heap. When you free a memory block, the debug heap automatically checks the integrity of the buffers on either side of your allocated area and issues an error report if overwriting has occurred. + +### To use the debug heap + +Link the debug build of your application with a debug version of the C runtime library. + +### To change one or more `_crtDbgFlag` bit fields and create a new state for the flag + +1. Call `_CrtSetDbgFlag` with the `newFlag` parameter set to `_CRTDBG_REPORT_FLAG` (to obtain the current `_crtDbgFlag` state) and store the returned value in a temporary variable. + +1. Turn on any bits by using a bitwise **`|`** operator ("or") on the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants). + +1. Turn off the other bits by using a bitwise **`&`** operator ("and") on the variable with a bitwise **`~`** operator ("not" or complement) of the appropriate bitmasks. + +1. Call `_CrtSetDbgFlag` with the `newFlag` parameter set to the value stored in the temporary variable to create the new state for `_crtDbgFlag`. + + For example, the following lines of code enable automatic leak detection and disable checks for blocks of type `_CRT_BLOCK`: + + ```cpp + // Get current flag + int tmpFlag = _CrtSetDbgFlag( _CRTDBG_REPORT_FLAG ); + + // Turn on leak-checking bit. + tmpFlag |= _CRTDBG_LEAK_CHECK_DF; + + // Turn off CRT block checking bit. + tmpFlag &= ~_CRTDBG_CHECK_CRT_DF; + + // Set flag to the new value. + _CrtSetDbgFlag( tmpFlag ); + ``` + +## `new`, `delete`, and `_CLIENT_BLOCK` allocations in the C++ debug heap + +The debug versions of the C run-time library contain debug versions of the C++ `new` and `delete` operators. If you use the `_CLIENT_BLOCK` allocation type, you must call the debug version of the `new` operator directly or create macros that replace the `new` operator in debug mode, as shown in the following example: + +```cpp +/* MyDbgNew.h + Defines global operator new to allocate from + client blocks +*/ + +#ifdef _DEBUG + #define DEBUG_CLIENTBLOCK new( _CLIENT_BLOCK, __FILE__, __LINE__) +#else + #define DEBUG_CLIENTBLOCK +#endif // _DEBUG + +/* MyApp.cpp + Use a default workspace for a Console Application to + * build a Debug version of this code +*/ + +#include "crtdbg.h" +#include "mydbgnew.h" + +#ifdef _DEBUG +#define new DEBUG_CLIENTBLOCK +#endif + +int main( ) { + char *p1; + p1 = new char[40]; + _CrtMemDumpAllObjectsSince( NULL ); +} +``` + +The Debug version of the `delete` operator works with all block types and requires no changes in your program when you compile a Release version. + +## Heap state reporting functions + +To capture a summary snapshot of the state of the heap at a given time, use the `_CrtMemState` structure defined in ``: + +```cpp +typedef struct _CrtMemState +{ + // Pointer to the most recently allocated block: + struct _CrtMemBlockHeader * pBlockHeader; + // A counter for each of the 5 types of block: + size_t lCounts[_MAX_BLOCKS]; + // Total bytes allocated in each block type: + size_t lSizes[_MAX_BLOCKS]; + // The most bytes allocated at a time up to now: + size_t lHighWaterCount; + // The total bytes allocated at present: + size_t lTotalCount; +} _CrtMemState; +``` + +This structure saves a pointer to the first (most recently allocated) block in the debug heap's linked list. Then, in two arrays, it records how many of each type of memory block (`_NORMAL_BLOCK`, `_CLIENT_BLOCK`, `_FREE_BLOCK`, and so on) are in the list and the number of bytes allocated in each type of block. Finally, it records the highest number of bytes allocated in the heap as a whole up to that point, and the number of bytes currently allocated. + +## Other CRT reporting functions + +The following functions report the state and contents of the heap, and use the information to help detect memory leaks and other problems. + +| Function | Description | +|---|---| +| [`_CrtMemCheckpoint`](./reference/crtmemcheckpoint.md) | Saves a snapshot of the heap in a `_CrtMemState` structure supplied by the application. | +| [`_CrtMemDifference`](./reference/crtmemdifference.md) | Compares two memory state structures, saves the difference between them in a third state structure, and returns TRUE if the two states are different. | +| [`_CrtMemDumpStatistics`](./reference/crtmemdumpstatistics.md) | Dumps a given `_CrtMemState` structure. The structure may contain a snapshot of the state of the debug heap at a given moment or the difference between two snapshots. | +| [`_CrtMemDumpAllObjectsSince`](./reference/crtmemdumpallobjectssince.md) | Dumps information about all objects allocated since a given snapshot was taken of the heap or from the start of execution. Every time it dumps a `_CLIENT_BLOCK` block, it calls a hook function supplied by the application, if one has been installed using `_CrtSetDumpClient`. | +| [`_CrtDumpMemoryLeaks`](./reference/crtdumpmemoryleaks.md) | Determines whether any memory leaks occurred since the start of program execution and, if so, dumps all allocated objects. Every time `_CrtDumpMemoryLeaks` dumps a `_CLIENT_BLOCK` block, it calls a hook function supplied by the application, if one has been installed using `_CrtSetDumpClient`. | + +## Track heap allocation requests + +Knowing the source file name and line number of an assert or reporting macro is often useful in locating the cause of a problem. The same isn't as likely to be true of heap allocation functions. While you can insert macros at many appropriate points in an application's logic tree, an allocation is often buried in a function that's called from many different places at many different times. The question isn't what line of code made a bad allocation. Instead, it's which one of the thousands of allocations made by that line of code was bad, and why. + +### Unique allocation request numbers and `_crtBreakAlloc` + +There's a simple way to identify the specific heap allocation call that went bad. It takes advantage of the unique allocation request number associated with each block in the debug heap. When information about a block is reported by one of the dump functions, this allocation request number is enclosed in braces. For example, `{36}`. + +Once you know the allocation request number of an improperly allocated block, you can pass this number to [`_CrtSetBreakAlloc`](./reference/crtsetbreakalloc.md) to create a breakpoint. Execution will break just before allocating the block and you can backtrack to determine what routine was responsible for the bad call. To avoid recompiling, you can accomplish the same thing in the debugger by setting `_crtBreakAlloc` to the allocation request number you're interested in. + +### Creating debug versions of your allocation routines + +A more complex approach is to create Debug versions of your own allocation routines, comparable to the `_dbg` versions of the [heap allocation functions](./debug-versions-of-heap-allocation-functions.md). You can then pass source file and line number arguments through to the underlying heap allocation routines, and you'll immediately be able to see where a bad allocation originated. + +For example, suppose your application contains a commonly used routine similar to the following example: + +```cpp +int addNewRecord(struct RecStruct * prevRecord, + int recType, int recAccess) +{ + // ...code omitted through actual allocation... + if ((newRec = malloc(recSize)) == NULL) + // ... rest of routine omitted too ... +} +``` + +In a header file, you could add code such as the following example: + +```cpp +#ifdef _DEBUG +#define addNewRecord(p, t, a) \ + addNewRecord(p, t, a, __FILE__, __LINE__) +#endif +``` + +Next, you could change the allocation in your record-creation routine as follows: + +```cpp +int addNewRecord(struct RecStruct *prevRecord, + int recType, int recAccess +#ifdef _DEBUG + , const char *srcFile, int srcLine +#endif + ) +{ + /* ... code omitted through actual allocation ... */ + if ((newRec = _malloc_dbg(recSize, _NORMAL_BLOCK, + srcFile, scrLine)) == NULL) + /* ... rest of routine omitted too ... */ +} +``` + +Now the source file name and line number where `addNewRecord` was called will be stored in each resulting block allocated in the debug heap and will be reported when that block is examined. + +## See also + +[Debugging Native Code](/visualstudio/debugger/debugging-native-code) diff --git a/docs/c-runtime-library/crt-debugging-techniques.md b/docs/c-runtime-library/crt-debugging-techniques.md new file mode 100644 index 0000000000..39d625f0e1 --- /dev/null +++ b/docs/c-runtime-library/crt-debugging-techniques.md @@ -0,0 +1,173 @@ +--- +title: CRT debugging techniques +description: There are various techniques you can use to debug a program that uses the C run-time (CRT) library. Use this article and its links to learn about such techniques. +ms.custom: SEO-VS-2020 +ms.date: 02/03/2023 +f1_keywords: + - "c.runtime.debugging" +helpviewer_keywords: + - "debugging [CRT]" + - "CRT, debugging" + - "debugging [C++], CRT debug support" +--- +# CRT debugging techniques + +When you debug a program that uses the C run-time library, these debugging techniques might be useful. + +## CRT debug library use + +The C runtime (CRT) library provides extensive debugging support. To use one of the CRT debug libraries, you must link with [`/DEBUG`](/cpp/build/reference/debug-generate-debug-info) and compile with [`/MDd`, `/MTd`, or `/LDd`](../build/reference/md-mt-ld-use-run-time-library.md). + +The main definitions and macros for CRT debugging can be found in the`` header file. + +The functions in the CRT debug libraries are compiled with debug information ([/Z7, /Zd, /Zi, /ZI (Debug Information Format)](../build/reference/z7-zi-zi-debug-information-format.md)) and without optimization. Some functions contain assertions to verify parameters that are passed to them, and source code is provided. With this source code, you can step into CRT functions to confirm that the functions are working as you expect and check for bad parameters or memory states. (Some CRT technology is proprietary and doesn't provide source code for exception handling, floating point, and a few other routines.) + +For more information on the various run-time libraries you can use, see [C Run-Time Libraries](./crt-library-features.md). + +## Macros for reporting + +For debugging, you can use the `_RPTn` and `_RPTFn` macros, defined in``, to replace the use of `printf` statements. You don't need to enclose them in `#ifdef` directives, because they automatically disappear in your release build when `_DEBUG` isn't defined. + +| Macro | Description | +|---|---| +| `_RPT0`, `_RPT1`, `_RPT2`, `_RPT3`, `_RPT4` | Outputs a message string and zero to four arguments. For `_RPT1` through `_RPT4`, the message string serves as a printf-style formatting string for the arguments. | +| `_RPTF0`, `_RPTF1`, `_RPTF2`, `_RPTF3`, `_RPTF4` | Same as `_RPTn`, but these macros also output the file name and line number where the macro is located. | + +Consider the following example: + +```cpp +#ifdef _DEBUG + if ( someVar > MAX_SOMEVAR ) + printf( "OVERFLOW! In NameOfThisFunc( ), + someVar=%d, otherVar=%d.\n", + someVar, otherVar ); +#endif +``` + +This code outputs the values of `someVar` and `otherVar` to `stdout`. You can use the following call to `_RPTF2` to report these same values and, additionally, the file name and line number: + +```cpp +if (someVar > MAX_SOMEVAR) _RPTF2(_CRT_WARN, "In NameOfThisFunc( ), someVar= %d, otherVar= %d\n", someVar, otherVar ); +``` + +Some applications may need debug reporting that the macros supplied with the C run-time library don't provide. For these cases, you can write a macro designed specifically to fit your own requirements. In one of your header files, for example, you could include code like the following to define a macro called `ALERT_IF2`: + +```cpp +#ifndef _DEBUG /* For RELEASE builds */ +#define ALERT_IF2(expr, msg, arg1, arg2) do {} while (0) +#else /* For DEBUG builds */ +#define ALERT_IF2(expr, msg, arg1, arg2) \ + do { \ + if ((expr) && \ + (1 == _CrtDbgReport(_CRT_ERROR, \ + __FILE__, __LINE__, msg, arg1, arg2))) \ + _CrtDbgBreak( ); \ + } while (0) +#endif +``` + +One call to `ALERT_IF2` could do all the functions of the `printf` code: + +```cpp +ALERT_IF2(someVar > MAX_SOMEVAR, "OVERFLOW! In NameOfThisFunc( ), +someVar=%d, otherVar=%d.\n", someVar, otherVar ); +``` + +You can easily change a custom macro to report more or less information to different destinations. This approach is useful as your debugging requirements evolve. + +## Debug hook function writing + +You can write several kinds of custom debug hook functions that allow you to insert your code into some predefined points inside the debugger's normal processing. + +### Client block hook functions + +If you want to validate or report the contents of the data stored in `_CLIENT_BLOCK` blocks, you can write a function specifically for this purpose. The function that you write must have a prototype similar to the following, as defined in``: + +```cpp +void YourClientDump(void *, size_t) +``` + +In other words, your hook function should accept a `void` pointer to the beginning of the allocation block, together with a `size_t` type value indicating the size of the allocation, and return `void`. Otherwise, its contents are up to you. + +Once you've installed your hook function using [_CrtSetDumpClient](./reference/crtsetdumpclient.md), it will be called every time a `_CLIENT_BLOCK` block is dumped. You can then use [_CrtReportBlockType](./reference/crtreportblocktype.md) to get information on the type or subtype of dumped blocks. + +The pointer to your function that you pass to `_CrtSetDumpClient` is of type `_CRT_DUMP_CLIENT`, as defined in``: + +```cpp +typedef void (__cdecl *_CRT_DUMP_CLIENT) + (void *, size_t); +``` + +### Allocation hook functions + +An allocation hook function, installed using [`_CrtSetAllocHook`](./reference/crtsetallochook.md), is called every time memory is allocated, reallocated, or freed. You can use this type of hook for many different purposes. Use it to test how an application handles insufficient memory situations, such as to examine allocation patterns, or log allocation information for later analysis. + +> [!NOTE] +> Be aware of the restriction about using C runtime library functions in an allocation hook function, described in [Allocation hooks and crt memory allocations](#allocation-hooks-and-crt-memory-allocations). + +An allocation hook function should have a prototype like the following example: + +```cpp +int YourAllocHook(int nAllocType, void *pvData, + size_t nSize, int nBlockUse, long lRequest, + const unsigned char * szFileName, int nLine ) +``` + +The pointer that you pass to [`_CrtSetAllocHook`](./reference/crtsetallochook.md) is of type `_CRT_ALLOC_HOOK`, as defined in``: + +```cpp +typedef int (__cdecl * _CRT_ALLOC_HOOK) + (int, void *, size_t, int, long, const unsigned char *, int); +``` + +When the run-time library calls your hook, the *`nAllocType`* argument indicates what allocation operation is about to be made (`_HOOK_ALLOC`, `_HOOK_REALLOC`, or `_HOOK_FREE`). In a free or in a reallocation, `pvData` has a pointer to the user article of the block about to be freed. However for an allocation, this pointer is null, because the allocation hasn't occurred. The remaining arguments contain the size of the allocation, its block type, a sequential request number, and a pointer to the file name. If available, the arguments also include the line number in which the allocation was made. After the hook function performs whatever analysis and other tasks its author wants, it must return either `TRUE`, indicating that the allocation operation can continue, or `FALSE`, indicating that the operation should fail. A simple hook of this type might check the amount of memory allocated so far, and return `FALSE` if that amount exceeded a small limit. The application would then experience the kind of allocation errors that would normally occur only when available memory was low. More complex hooks might keep track of allocation patterns, analyze memory use, or report when specific situations occur. + +### Allocation hooks and CRT memory allocations + +An important restriction on allocation hook functions is that they must explicitly ignore `_CRT_BLOCK` blocks. These blocks are the memory allocations made internally by C run-time library functions if they make any calls to C run-time library functions that allocate internal memory. You can ignore `_CRT_BLOCK` blocks by including the following code at the beginning of your allocation hook function: + +```cpp +if ( nBlockUse == _CRT_BLOCK ) + return( TRUE ); +``` + +If your allocation hook doesn't ignore `_CRT_BLOCK` blocks, then any C run-time library function called in your hook can trap the program in an endless loop. For example, `printf` makes an internal allocation. If your hook code calls `printf`, then the resulting allocation will cause your hook to be called again, which will call `printf` again, and so on, until the stack overflows. If you need to report `_CRT_BLOCK` allocation operations, one way to circumvent this restriction is to use Windows API functions, rather than C run-time functions, for formatting and output. Because the Windows APIs don't use the C run-time library heap, they won't trap your allocation hook in an endless loop. + +If you examine the run-time library source files, you'll see that the default allocation hook function, `_CrtDefaultAllocHook` (which simply returns `TRUE`), is located in a separate file of its own, *`debug_heap_hook.cpp`*. If you want your allocation hook to be called even for the allocations made by the run-time startup code that is executed before your application's `main` function, you can replace this default function with one of your own, instead of using [`_CrtSetAllocHook`](./reference/crtsetallochook.md). + +### Report hook functions + +A report hook function, installed using [`_CrtSetReportHook`](./reference/crtsetreporthook.md), is called every time [`_CrtDbgReport`](./reference/crtdbgreport-crtdbgreportw.md) generates a debug report. You can use it, among other things, for filtering reports to focus on specific types of allocations. A report hook function should have a prototype like this example: + +```cpp +int AppReportHook(int nRptType, char *szMsg, int *retVal); +``` + +The pointer that you pass to `_CrtSetReportHook` is of type `_CRT_REPORT_HOOK`, as defined in ``: + +```cpp +typedef int (__cdecl *_CRT_REPORT_HOOK)(int, char *, int *); +``` + +When the run-time library calls your hook function, the *`nRptType`* argument contains the category of the report (`_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`), *`szMsg`* contains a pointer to a fully assembled report message string, and *`retVal`* specifies whether `_CrtDbgReport` should continue normal execution after generating the report or start the debugger. (A *`retVal`* value of zero continues execution, a value of 1 starts the debugger.) + +If the hook handles the message in question completely, so that no further reporting is required, it should return `TRUE`. If it returns `FALSE`, `_CrtDbgReport` will report the message normally. + +## In this section + +- [Debug versions of heap allocation functions](./debug-versions-of-heap-allocation-functions.md) + + Discusses the special Debug versions of the heap allocation functions, including: how the CRT maps calls, the benefits of calling them explicitly, how to avoid conversion, tracking the separate types of allocations in client blocks, and the results of not defining `_DEBUG`. + +- [CRT debug heap details](./crt-debug-heap-details.md) + + Describes memory management and the debug heap, the types of blocks on the debug heap, heap state reporting functions, and how to use the debug heap to track allocation requests. + +- [Find memory leaks using the CRT library](./find-memory-leaks-using-the-crt-library.md) + + Covers techniques for detecting and isolating memory leaks by using the debugger and the C Run-Time Library. + +## See also + +- [Debugging Native Code](/visualstudio/debugger/debugging-native-code) +- [Debugger Security](/visualstudio/debugger/debugger-security) diff --git a/docs/c-runtime-library/crt-disable-perfcrit-locks.md b/docs/c-runtime-library/crt-disable-perfcrit-locks.md index c6d776a32c..bd9a092c1b 100644 --- a/docs/c-runtime-library/crt-disable-perfcrit-locks.md +++ b/docs/c-runtime-library/crt-disable-perfcrit-locks.md @@ -2,24 +2,24 @@ description: "Learn more about: _CRT_DISABLE_PERFCRIT_LOCKS" title: "_CRT_DISABLE_PERFCRIT_LOCKS" ms.date: "11/04/2016" -f1_keywords: ["_CRT_DISABLE_PERFCRIT_LOCKS", "CRT_DISABLE_PERFCRIT_LOCKS"] +f1_keywords: ["_CRT_DISABLE_PERFCRIT_LOCKS"] helpviewer_keywords: ["CRT_DISABLE_PERFCRIT_LOCKS constant", "_CRT_DISABLE_PERFCRIT_LOCKS constant"] ms.assetid: 36cc2d86-cdb1-4b2b-a03c-c0d3818e7c6f --- -# _CRT_DISABLE_PERFCRIT_LOCKS +# `_CRT_DISABLE_PERFCRIT_LOCKS` Disables performance-critical locking in I/O operations. ## Syntax -``` +```C #define _CRT_DISABLE_PERFCRIT_LOCKS ``` ## Remarks -Defining this symbol can improve performance in single-threaded I/O-bound programs by forcing all I/O operations to assume a single-threaded I/O model. For more information, see [Multithreaded Libraries Performance](../c-runtime-library/multithreaded-libraries-performance.md). +Defining this symbol can improve performance in single-threaded I/O-bound programs by forcing all I/O operations to assume a single-threaded I/O model. For more information, see [Multithreaded libraries performance](./multithreaded-libraries-performance.md). ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/crt-initialization.md b/docs/c-runtime-library/crt-initialization.md index d426c7aee0..b2971c1be1 100644 --- a/docs/c-runtime-library/crt-initialization.md +++ b/docs/c-runtime-library/crt-initialization.md @@ -4,9 +4,8 @@ description: "Describes how the CRT initializes global state in native code." ms.topic: "conceptual" ms.date: 08/02/2021 helpviewer_keywords: ["CRT initialization [C++]"] -ms.assetid: e7979813-1856-4848-9639-f29c86b74ad7 --- -# CRT Initialization +# CRT initialization This article describes how the CRT initializes global state in native code. @@ -14,11 +13,11 @@ By default, the linker includes the CRT library, which provides its own startup It's possible, though not recommended, to take advantage of Microsoft-specific linker behavior to insert your own global initializers in a specific order. This code isn't portable, and comes with some important caveats. -## Initializing a Global Object +## Initializing a global object -Consider the following code: +Consider the following C++ code (C won't allow this code because it doesn't allow a function call in a constant expression). -``` +```cpp int func(void) { return 3; @@ -69,7 +68,6 @@ Offset Type Applied To Index Name The CRT defines two pointers: - `__xc_a` in `.CRT$XCA` - - `__xc_z` in `.CRT$XCZ` Neither group has any other symbols defined except `__xc_a` and `__xc_z`. @@ -88,7 +86,7 @@ The section should resemble this example: __xc_z ``` -So, the CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded. +The CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded. ## Linker features for initialization @@ -112,4 +110,5 @@ The names `.CRT$XCT` and `.CRT$XCV` aren't used by either the compiler or the CR ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[`_initterm, _initterm_e`](./reference/initterm-initterm-e.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/crt-library-features.md b/docs/c-runtime-library/crt-library-features.md index 8d5d337794..165f509086 100644 --- a/docs/c-runtime-library/crt-library-features.md +++ b/docs/c-runtime-library/crt-library-features.md @@ -1,24 +1,28 @@ --- -title: "C runtime (CRT) and C++ Standard Library .lib files" -description: "List of Microsoft C runtime and C++ Standard Library .lib files that you can link against and their associated compiler options and preprocessor directives." +title: "C runtime (CRT) and C++ standard library (STL) lib files" +description: "List of Microsoft C runtime and C++ standard library (STL) lib files that you can link against and their associated compiler options and preprocessor directives." ms.date: "3/5/2021" ms.topic: "reference" -ms.custom: contperf-fy21q3 -helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries"] +helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries", "STL libraries", "Microsoft standard template libraries"] --- -# C runtime (CRT) and C++ Standard Library (STL) `.lib` files +# C runtime (CRT) and C++ standard library (STL) `.lib` files -This topic lists the Microsoft C runtime library `.lib` files that you can link against when you develop your application, and their associated compiler options and preprocessor directives. +This article lists the Microsoft C runtime library `.lib` files that you can link against when you develop your application, and their associated compiler options and preprocessor directives. See [Redistributing Visual C++ files](../windows/redistributing-visual-cpp-files.md) if you're looking for information about deploying the C runtime files necessary to support your application. -See [C runtime library reference](../c-runtime-library/c-run-time-library-reference.md) if you're looking for API reference for the C runtime library. +See [C runtime library reference](./c-run-time-library-reference.md) if you're looking for API reference for the C runtime library. + +>[!NOTE] +> Microsoft's implementation of the C++ standard library is often referred to as the *STL* or *Standard Template Library*. Although *C++ standard library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. + +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ standard library. The standard library also incorporates the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ standard library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ standard library as a whole. ## C runtime `.lib` files -The C runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files. +The ISO C standard library is part of the C++ standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files. -Starting in Visual Studio 2015, the CRT has been refactored into new binaries. The Universal CRT (UCRT) contains the functions and globals exported by the standard C99 CRT library. The UCRT is now a Windows component, and ships as part of Windows 10 and later versions. The static library, DLL import library, and header files for the UCRT are now found in the Windows SDK. When you install Visual C++, Visual Studio setup installs the subset of the Windows SDK required to use the UCRT. You can use the UCRT on any version of Windows supported by Visual Studio 2015 and later versions. You can redistribute it using vcredist for supported versions of Windows other than Windows 10 or later. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). +In Visual Studio 2015, the CRT was refactored into new binaries. The Universal CRT (UCRT) contains the functions and globals exported by the standard C99 CRT library. The UCRT is now a Windows component, and ships as part of Windows 10 and later versions. The static library, DLL import library, and header files for the UCRT are now found in the Windows SDK. When you install Visual C++, Visual Studio setup installs the subset of the Windows SDK required to use the UCRT. You can use the UCRT on any version of Windows supported by Visual Studio 2015 and later versions. You can redistribute it using vcredist for supported versions of Windows other than Windows 10 or later. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). The following table lists the libraries that implement the UCRT. @@ -29,7 +33,7 @@ The following table lists the libraries that implement the UCRT. | *`ucrt.lib`* | *`ucrtbase.dll`* | DLL import library for the UCRT. | **`/MD`** | `_MT`, `_DLL` | | *`ucrtd.lib`* | *`ucrtbased.dll`* | DLL import library for the Debug version of the UCRT. Not redistributable. | **`/MDd`** | `_DEBUG`, `_MT`, `_DLL` | -The vcruntime library contains Visual C++ CRT implementation-specific code, such as exception handling and debugging support, runtime checks and type information, implementation details and certain extended library functions. The vcruntime library version needs to match the version of the compiler you're using. +The vcruntime library contains Visual C++ CRT implementation-specific code: exception handling and debugging support, runtime checks and type information, implementation details, and certain extended library functions. The vcruntime library version needs to match the version of the compiler you're using. This table lists the libraries that implement the vcruntime library. @@ -42,7 +46,7 @@ This table lists the libraries that implement the vcruntime library. > [!NOTE] > When the UCRT was refactored, the Concurrency Runtime functions were moved into -*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ Standard Library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables. +*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ standard library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables. The code that initializes the CRT is in one of several libraries, based on whether the CRT library is statically or dynamically linked, or native, managed, or mixed code. This code handles CRT startup, internal per-thread data initialization, and termination. It's specific to the version of the compiler used. This library is always statically linked, even when using a dynamically linked UCRT. @@ -61,46 +65,46 @@ This table lists the libraries that implement CRT initialization and termination If you link your program from the command line without a compiler option that specifies a C runtime library, the linker will use the statically linked CRT libraries: *`libcmt.lib`*, *`libvcruntime.lib`*, and *`libucrt.lib`*. -Using the statically linked CRT implies that any state information saved by the C runtime library will be local to that instance of the CRT. For example, if you use [`strtok`](../c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) when using a statically linked CRT, the position of the `strtok` parser is unrelated to the `strtok` state used in code in the same process (but in a different DLL or EXE) that is linked to another instance of the static CRT. In contrast, the dynamically linked CRT shares state for all code within a process that is dynamically linked to the CRT. This concern doesn't apply if you use the new more secure versions of these functions; for example, `strtok_s` doesn't have this problem. +Using the statically linked CRT implies that any state information saved by the C runtime library will be local to that instance of the CRT. For example, if you use [`strtok`](./reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) when using a statically linked CRT, the position of the `strtok` parser is unrelated to the `strtok` state used in code in the same process (but in a different DLL or EXE) that is linked to another instance of the static CRT. In contrast, the dynamically linked CRT shares state for all code within a process that is dynamically linked to the CRT. This concern doesn't apply if you use the new more secure versions of these functions; for example, `strtok_s` doesn't have this problem. -Because a DLL built by linking to a static CRT has its own CRT state, it isn't recommended to link statically to the CRT in a DLL unless the consequences of this are specifically desired and understood. For example, if you call [`_set_se_translator`](../c-runtime-library/reference/set-se-translator.md) in an executable that loads the DLL linked to its own static CRT, any hardware exceptions generated by the code in the DLL will not be caught by the translator, but hardware exceptions generated by code in the main executable will be caught. +Because a DLL built by linking to a static CRT has its own CRT state, we don't recommend you link statically to the CRT in a DLL unless the consequences are understood and desired. For example, if you call [`_set_se_translator`](./reference/set-se-translator.md) in an executable that loads the DLL linked to its own static CRT, any hardware exceptions generated by the code in the DLL won't be caught by the translator, but hardware exceptions generated by code in the main executable will be caught. -If you're using the **`/clr`** compiler switch, your code will be linked with a static library, `msvcmrt.lib`. The static library provides a proxy between your managed code and the native CRT. You cannot use the statically linked CRT ( **`/MT`** or **`/MTd`** options) with **`/clr`**. Use the dynamically-linked libraries (**`/MD`** or **`/MDd`**) instead. The pure managed CRT libraries are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +If you're using the **`/clr`** compiler switch, your code will be linked with a static library, `msvcmrt.lib`. The static library provides a proxy between your managed code and the native CRT. You can't use the statically linked CRT ( **`/MT`** or **`/MTd`** options) with **`/clr`**. Use the dynamically linked libraries (**`/MD`** or **`/MDd`**) instead. The pure managed CRT libraries are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. For more information on using the CRT with **`/clr`**, see [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md). -To build a debug version of your application, the [`_DEBUG`](../c-runtime-library/debug.md) flag must be defined and the application must be linked with a debug version of one of these libraries. For more information about using the debug versions of the library files, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +To build a debug version of your application, the [`_DEBUG`](./debug.md) flag must be defined and the application must be linked with a debug version of one of these libraries. For more information about using the debug versions of the library files, see [CRT debugging techniques](./crt-debugging-techniques.md). This version of the CRT isn't fully conformant with the C99 standard. In versions before Visual Studio 2019 version 16.8, the `` header isn't supported. In all versions, the `CX_LIMITED_RANGE` and `FP_CONTRACT` pragma macros aren't supported. Certain elements such as the meaning of parameter specifiers in standard IO functions use legacy interpretations by default. You can use **`/Zc`** compiler conformance options and specify linker options to control some aspects of library conformance. -## C++ Standard Library `.lib` files +## C++ standard library (STL) `.lib` files -| C++ Standard Library | Characteristics | Option | Preprocessor directives | +| C++ standard library | Characteristics | Option | Preprocessor directives | |--|--|--|--| | *`libcpmt.lib`* | Multithreaded, static link | **`/MT`** | `_MT` | | *`msvcprt.lib`* | Multithreaded, dynamic link (import library for *`msvcp.dll`*) | **`/MD`** | `_MT`, `_DLL` | | *`libcpmtd.lib`* | Multithreaded, static link | **`/MTd`** | `_DEBUG`, `_MT` | | *`msvcprtd.lib`* | Multithreaded, dynamic link (import library for *`msvcpd.dll`*) | **`/MDd`** | `_DEBUG`, `_MT`, `_DLL` | -When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ Standard Library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ Standard Library will be linked automatically by Visual C++ at compile time. For example: +When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ standard library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ standard library will be linked automatically by Visual C++ at compile time. For example: ```cpp #include ``` -For binary compatibility, more than one DLL file may be specified by a single import library. Version updates may introduce *dot libraries*, separate DLLs that introduce new library functionality. For example, Visual Studio 2017 version 15.6 introduced *`msvcp140_1.dll`* to support additional standard library functionality without breaking the Application Binary Interface (ABI) supported by *`msvcp140.dll`*. The *`msvcprt.lib`* import library included in the toolset for Visual Studio 2017 version 15.6 supports both DLLs, and the vcredist for this version installs both DLLs. Once shipped, a dot library has a fixed ABI, and will never have a dependency on a later dot library. +For binary compatibility, more than one DLL file may be specified by a single import library. Version updates may introduce *dot libraries*, separate DLLs that introduce new library functionality. For example, Visual Studio 2017 version 15.6 introduced *`msvcp140_1.dll`* to support more standard library functionality without breaking the Application Binary Interface (ABI) supported by *`msvcp140.dll`*. The *`msvcprt.lib`* import library included in the toolset for Visual Studio 2017 version 15.6 supports both DLLs, and the vcredist for this version installs both DLLs. Once shipped, a dot library has a fixed ABI, and will never have a dependency on a later dot library. ## What problems exist if an application uses more than one CRT version? -Every executable image (EXE or DLL) can have its own statically linked CRT, or can dynamically link to a CRT. The version of the CRT statically included in or dynamically loaded by a particular image depends on the version of the tools and libraries it was built with. A single process may load multiple EXE and DLL images, each with its own CRT. Each of those CRTs may use a different allocator, may have different internal structure layouts, and may use different storage arrangements. This means allocated memory, CRT resources, or classes passed across a DLL boundary can cause problems in memory management, internal static usage, or layout interpretation. For example, if a class is allocated in one DLL but passed to and deleted by another, which CRT deallocator is used? The errors caused can range from the subtle to the immediately fatal, and therefore direct transfer of such resources is strongly discouraged. +Every executable image (EXE or DLL) can have its own statically linked CRT, or can dynamically link to a CRT. The version of the CRT statically included in or dynamically loaded by a particular image depends on the version of the tools and libraries it was built with. A single process may load multiple EXE and DLL images, each with its own CRT. Each of those CRTs may use a different allocator, may have different internal structure layouts, and may use different storage arrangements. It means allocated memory, CRT resources, or classes passed across a DLL boundary can cause problems in memory management, internal static usage, or layout interpretation. For example, if a class is allocated in one DLL but passed to and deleted by another, which CRT deallocator is used? The errors caused can range from the subtle to the immediately fatal, and therefore direct transfer of such resources is discouraged. -You can avoid many of these issues by using Application Binary Interface (ABI) technologies instead, as they are designed to be stable and versionable. Design your DLL export interfaces to pass information by value, or to work on memory that is passed in by the caller rather than allocated locally and returned to the caller. Use marshaling techniques to copy structured data between executable images. Encapsulate resources locally and only allow manipulation through handles or functions you expose to clients. +You can avoid many of these issues by using Application Binary Interface (ABI) technologies instead, as they're designed to be stable and versionable. Design your DLL export interfaces to pass information by value, or to work on memory that is passed in by the caller rather than allocated locally and returned to the caller. Use marshaling techniques to copy structured data between executable images. Encapsulate resources locally and only allow manipulation through handles or functions you expose to clients. It's also possible to avoid some of these issues if all of the images in your process use the same dynamically loaded version of the CRT. To ensure that all components use the same DLL version of the CRT, build them by using the **`/MD`** option, and use the same compiler toolset and property settings. -Be careful if your program passes certain CRT resources across DLL boundaries. Resources such as file handles, locales, and environment variables can cause problems, even when using the same version of the CRT. For more information on the issues involved and how to resolve them, see [Potential Errors Passing CRT Objects Across DLL Boundaries](../c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md). +Be careful if your program passes certain CRT resources across DLL boundaries. Resources such as file handles, locales, and environment variables can cause problems, even when using the same version of the CRT. For more information on the issues involved and how to resolve them, see [Potential errors passing CRT objects across DLL boundaries](./potential-errors-passing-crt-objects-across-dll-boundaries.md). ## See also -[C runtime library reference](../c-runtime-library/c-run-time-library-reference.md)\ +[C runtime library reference](./c-run-time-library-reference.md)\ [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md) diff --git a/docs/c-runtime-library/crtdbg-map-alloc.md b/docs/c-runtime-library/crtdbg-map-alloc.md index 106781b49d..b2b1cfec57 100644 --- a/docs/c-runtime-library/crtdbg-map-alloc.md +++ b/docs/c-runtime-library/crtdbg-map-alloc.md @@ -6,12 +6,12 @@ f1_keywords: ["CRTDBG_MAP_ALLOC", "_CRTDBG_MAP_ALLOC"] helpviewer_keywords: ["_CRTDBG_MAP_ALLOC macro", "memory allocation, in debug builds", "CRTDBG_MAP_ALLOC macro"] ms.assetid: 435242b8-caea-4063-b765-4a608200312b --- -# _CRTDBG_MAP_ALLOC +# `_CRTDBG_MAP_ALLOC` -When the **_CRTDBG_MAP_ALLOC** flag is defined in the debug version of an application, the base version of the heap functions are directly mapped to their debug versions. The flag is used in Crtdbg.h to do the mapping. This flag is only available when the [_DEBUG](../c-runtime-library/debug.md) flag has been defined in the application. +When the `_CRTDBG_MAP_ALLOC` flag is defined in the debug version of an application, the base versions of the heap functions are directly mapped to their debug versions. The flag is used in Crtdbg.h to do the mapping. This flag is only available when the [`_DEBUG`](./debug.md) flag has been defined in the application. -For more information about using the debug version versus the base version of a heap function, see [Using the Debug Version Versus the Base Version](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For more information about using the debug version versus the base version of a heap function, see [Debug versions of heap allocation functions](./debug-versions-of-heap-allocation-functions.md). ## See also -[Control Flags](../c-runtime-library/control-flags.md) +[Control flags](./control-flags.md) diff --git a/docs/c-runtime-library/crtdbgflag.md b/docs/c-runtime-library/crtdbgflag.md index f300ca39ed..6617f29a18 100644 --- a/docs/c-runtime-library/crtdbgflag.md +++ b/docs/c-runtime-library/crtdbgflag.md @@ -2,16 +2,16 @@ description: "Learn more about: _crtDbgFlag" title: "_crtDbgFlag" ms.date: "11/04/2016" -f1_keywords: ["_crtDbgFlag", "crtDbgFlag"] +f1_keywords: ["_crtDbgFlag", "CRTDBG/_crtDbgFlag"] helpviewer_keywords: ["memory allocation, tracking flag", "crtDbgFlag constant", "_crtDbgFlag constant", "debug heap, tracking memory on", "debug heap, control flags", "enable memory allocation tracking flag", "memory, tracking on the debug heap"] ms.assetid: 9e7adb47-8ab9-4e19-81d5-e2f237979973 --- -# _crtDbgFlag +# `_crtDbgFlag` -The **_crtDbgFlag** flag consists of five bit fields that control how memory allocations on the debug version of the heap are tracked, verified, reported, and dumped. The bit fields of the flag are set using the [_CrtSetDbgFlag](../c-runtime-library/reference/crtsetdbgflag.md) function. This flag and its bit fields are declared in Crtdbg.h. This flag is only available when the [_DEBUG](../c-runtime-library/debug.md) flag has been defined in the application. +The **`_crtDbgFlag`** flag consists of five bit-fields that control how memory allocations on the debug version of the heap are tracked, verified, reported, and dumped. The bit fields of the flag are set using the [`_CrtSetDbgFlag`](./reference/crtsetdbgflag.md) function. This flag and its bit fields are declared in Crtdbg.h. This flag is only available when the [`_DEBUG`](./debug.md) flag has been defined in the application. -For more information about using this flag in conjunction with other debug functions, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). +For more information about using this flag along with other debug functions, see [Heap state reporting functions](./crt-debug-heap-details.md#heap-state-reporting-functions). ## See also -[Control Flags](../c-runtime-library/control-flags.md) +[Control flags](./control-flags.md) diff --git a/docs/c-runtime-library/crtlcmapstringw.md b/docs/c-runtime-library/crtlcmapstringw.md index 1a127c9d1c..c75880b05f 100644 --- a/docs/c-runtime-library/crtlcmapstringw.md +++ b/docs/c-runtime-library/crtlcmapstringw.md @@ -10,7 +10,7 @@ f1_keywords: ["__crtLCMapStringW"] helpviewer_keywords: ["__crtLCMapStringW"] ms.assetid: 45b4ac0e-438c-4fa3-b4d1-34195f4467d9 --- -# __crtLCMapStringW +# `__crtLCMapStringW` Maps one character string to another, performing a specified locale-dependent transformation. This function can also be used to generate a sort key for the input string. @@ -28,27 +28,27 @@ int __crtLCMapStringW( #### Parameters -*Locale*
-Locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the `MAKELCID` macro to create a locale identifier. +*`Locale`*\ +The locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the `MAKELCID` macro to create a locale identifier. -*dwMapFlags*
+*`dwMapFlags`*\ The type of transformation to be used during string mapping or sort key generation. -*lpSrcStr*
+*`lpSrcStr`*\ Pointer to a source string that the function maps or uses for sort key generation. This parameter is assumed to be a Unicode string. -*cchSrc*
+*`cchSrc`*\ Size, in characters, of the string pointed to by the `lpSrcStr` parameter. This count can include the null terminator, or not include it. -A `cchSrc` value of -1 specifies that the string pointed to by `lpSrcStr` is null-terminated. If this is the case, and this function is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into `*lpDestStr`. +A `cchSrc` value of -1 specifies that the string pointed to by `lpSrcStr` is null-terminated. If so, and this function is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into `*lpDestStr`. -*lpDestStr*
+*`lpDestStr`*\ Long pointer to a buffer into which the function stores the mapped string or sort key. -*cchDest*
+*`cchDest`*\ Size, in characters, of the buffer pointed to by `lpDestStr`. -## Return Value +## Return value If the value of `cchDest` is nonzero, the number of characters, or bytes if `LCMAP_SORTKEY` is specified, written to the buffer indicates success. This count includes room for a null terminator. @@ -58,10 +58,10 @@ Zero indicates failure. To get extended error information, call the `GetLastErro ## Remarks -If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, `__crtLCMapStringW` sets `cchSrc` to the length of the string. Then `__crtLCMapStringW` calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [LCMapString](/windows/win32/api/winnls/nf-winnls-lcmapstringw). +If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, **`__crtLCMapStringW`** sets `cchSrc` to the length of the string. Then **`__crtLCMapStringW`** calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [`LCMapString`](/windows/win32/api/winnls/nf-winnls-lcmapstringw). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__crtLCMapStringW|awint.h| +| Routine | Required header | +|---|---| +| **`__crtLCMapStringW`** | `` | diff --git a/docs/c-runtime-library/cxxframehandler.md b/docs/c-runtime-library/cxxframehandler.md index 8f6e9df406..67d417b3f1 100644 --- a/docs/c-runtime-library/cxxframehandler.md +++ b/docs/c-runtime-library/cxxframehandler.md @@ -3,14 +3,14 @@ description: "Learn more about: __CxxFrameHandler" title: "__CxxFrameHandler" ms.date: "1/14/2021" api_name: ["__CxxFrameHandler"] -api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__CxxFrameHandler"] helpviewer_keywords: ["__CxxFrameHandler"] ms.assetid: b79ac97f-425a-42ae-9b91-8beaef935333 --- -# __CxxFrameHandler +# `__CxxFrameHandler` Internal CRT function. Used by the CRT to handle structured exception frames. @@ -22,24 +22,24 @@ EXCEPTION_DISPOSITION __CxxFrameHandler( EHRegistrationNode *pRN, void *pContext, DispatcherContext *pDC - ) + ); ``` #### Parameters -*pExcept*
+*`pExcept`*\ Exception record that is passed to the possible **`catch`** statements. -*pRN*
+*`pRN`*\ Dynamic information about the stack frame that is used to handle the exception. For more information, see ehdata.h. -*pContext*
+*`pContext`*\ Context. (Not used on Intel processors.) -*pDC*
+*`pDC`*\ Additional information about the function entry and stack frame. -## Return Value +## Return value One of the *filter expression* values used by the [try-except Statement](../cpp/try-except-statement.md). @@ -47,6 +47,6 @@ One of the *filter expression* values used by the [try-except Statement](../cpp/ ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__CxxFrameHandler|excpt.h, ehdata.h| +| Routine | Required header | +|---|---| +| **`__CxxFrameHandler`** | ``, `` | diff --git a/docs/c-runtime-library/data-alignment.md b/docs/c-runtime-library/data-alignment.md index 9cb5bfe0ee..97b03773fb 100644 --- a/docs/c-runtime-library/data-alignment.md +++ b/docs/c-runtime-library/data-alignment.md @@ -1,36 +1,35 @@ --- -description: "Learn more about: Data Alignment" title: "Data Alignment" -ms.date: "11/04/2016" +description: "Learn more about: Data Alignment" +ms.date: 11/04/2016 f1_keywords: ["data.alignment"] helpviewer_keywords: ["data alignment [C++]"] -ms.assetid: 35ac3d2d-a4b3-421b-954f-b7372b1f18e1 --- -# Data Alignment +# Data alignment The following C run-time functions support data alignment. -## Data-Alignment Routines +## Data-alignment routines -|Routine|Use| -|-------------|---------| -|[_aligned_free](../c-runtime-library/reference/aligned-free.md)|Frees a block of memory that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md)or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_free_dbg](../c-runtime-library/reference/aligned-free-dbg.md)|Frees a block of memory that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug only).| -|[_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md)|Allocates memory on a specified alignment boundary.| -|[_aligned_malloc_dbg](../c-runtime-library/reference/aligned-malloc-dbg.md)|Allocates memory on a specified alignment boundary with additional space for a debugging header and overwrite buffers (debug version only).| -|[_aligned_msize](../c-runtime-library/reference/aligned-msize.md)|Returns the size of a memory block allocated in the heap.| -|[_aligned_msize_dbg](../c-runtime-library/reference/aligned-msize-dbg.md)|Returns the size of a memory block allocated in the heap (debug version only).| -|[_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md)|Allocates memory on a specified alignment boundary.| -|[_aligned_offset_malloc_dbg](../c-runtime-library/reference/aligned-offset-malloc-dbg.md)|Allocates memory on a specified alignment boundary (debug version only).| -|[_aligned_offset_realloc](../c-runtime-library/reference/aligned-offset-realloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_offset_realloc_dbg](../c-runtime-library/reference/aligned-offset-realloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug version only).| -|[_aligned_offset_recalloc](../c-runtime-library/reference/aligned-offset-recalloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0.| -|[_aligned_offset_recalloc_dbg](../c-runtime-library/reference/aligned-offset-recalloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only).| -|[_aligned_realloc](../c-runtime-library/reference/aligned-realloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_realloc_dbg](../c-runtime-library/reference/aligned-realloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug version only).| -|[_aligned_recalloc](../c-runtime-library/reference/aligned-recalloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0.| -|[_aligned_recalloc_dbg](../c-runtime-library/reference/aligned-recalloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only).| +| Routine | Use | +|---|---| +| [`_aligned_free`](./reference/aligned-free.md) | Frees a block of memory that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_free_dbg`](./reference/aligned-free-dbg.md) | Frees a block of memory that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug only). | +| [`_aligned_malloc`](./reference/aligned-malloc.md) | Allocates memory on a specified alignment boundary. | +| [`_aligned_malloc_dbg`](./reference/aligned-malloc-dbg.md) | Allocates memory on a specified alignment boundary with extra space for a debugging header and overwrite buffers (debug version only). | +| [`_aligned_msize`](./reference/aligned-msize.md) | Returns the size of a memory block allocated in the heap. | +| [`_aligned_msize_dbg`](./reference/aligned-msize-dbg.md) | Returns the size of a memory block allocated in the heap (debug version only). | +| [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) | Allocates memory on a specified alignment boundary. | +| [`_aligned_offset_malloc_dbg`](./reference/aligned-offset-malloc-dbg.md) | Allocates memory on a specified alignment boundary (debug version only). | +| [`_aligned_offset_realloc`](./reference/aligned-offset-realloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_offset_realloc_dbg`](./reference/aligned-offset-realloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug version only). | +| [`_aligned_offset_recalloc`](./reference/aligned-offset-recalloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0. | +| [`_aligned_offset_recalloc_dbg`](./reference/aligned-offset-recalloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). | +| [`_aligned_realloc`](./reference/aligned-realloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_realloc_dbg`](./reference/aligned-realloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug version only). | +| [`_aligned_recalloc`](./reference/aligned-recalloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0. | +| [`_aligned_recalloc_dbg`](./reference/aligned-recalloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/data-conversion.md b/docs/c-runtime-library/data-conversion.md index ca67e7e7f4..5c3c7b5b61 100644 --- a/docs/c-runtime-library/data-conversion.md +++ b/docs/c-runtime-library/data-conversion.md @@ -4,53 +4,52 @@ title: "Data Conversion" ms.date: "03/21/2018" f1_keywords: ["c.conversions"] helpviewer_keywords: ["data conversion routines [C++]", "converting data"] -ms.assetid: b15b5268-7467-49f1-bf95-5299b598f94c --- -# Data Conversion +# Data conversion -These routines convert data from one form to another. Generally these routines execute faster than conversions you might write. Each routine that begins with a *to* prefix is implemented as a function and as a macro. See [Choosing Between Functions and Macros](../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md) for information about choosing an implementation. +These routines convert data from one form to another. Generally these routines execute faster than conversions you might write. Each routine that begins with a `to` prefix is implemented as a function and as a macro. See [Recommendations for choosing between functions and macros](./recommendations-for-choosing-between-functions-and-macros.md) for information about choosing an implementation. ## Data-conversion routines -|Routine|Use| -|-------------|---------| -|[abs](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of integer| -|[atof, _atof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert string to **`float`**| -|[atoi, _atoi_l](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert string to **`int`**| -|[_atoi64, _atoi64_l](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert string to **`__int64`** or **`long long`**| -|[atol, _atol_l](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert string to **`long`**| -|[c16rtomb, c32rtomb](../c-runtime-library/reference/c16rtomb-c32rtomb1.md)|Convert UTF-16 or UTF-32 character to equivalent multibyte character| -|[_ecvt](../c-runtime-library/reference/ecvt.md), [_ecvt_s](../c-runtime-library/reference/ecvt-s.md)|Convert **`double`** to string of specified length| -|[_fcvt](../c-runtime-library/reference/fcvt.md), [_fcvt_s](../c-runtime-library/reference/fcvt-s.md)|Convert **`double`** to string with specified number of digits following decimal point| -|[_gcvt](../c-runtime-library/reference/gcvt.md), [_gcvt_s](../c-runtime-library/reference/gcvt-s.md)|Convert **`double`** number to string; store string in buffer| -|[_itoa, _ltoa, _ultoa, _i64toa, _ui64toa, _itow, _ltow, ultow, _i64tow, _ui64tow](../c-runtime-library/reference/itoa-itow.md), [_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s, _itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s](../c-runtime-library/reference/itoa-s-itow-s.md)|Convert integer types to string| -|[labs](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of **`long`** integer| -|[llabs](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of **`long long`** integer| -|[_mbbtombc, _mbbtombc_l](../c-runtime-library/reference/mbbtombc-mbbtombc-l.md)|Convert 1-byte multibyte character to corresponding 2-byte multibyte character| -|[_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l](../c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)|Convert Japan Industry Standard (JIS) character to Japan Microsoft (JMS) character| -|[_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l](../c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)|Convert JMS character to JIS character| -|[_mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l](../c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)|Convert multibyte character to 1-byte hiragana code| -|[_mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l](../c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)|Convert multibyte character to 1-byte katakana code| -|[_mbctombb, _mbctombb_l](../c-runtime-library/reference/mbctombb-mbctombb-l.md)|Convert 2-byte multibyte character to corresponding 1-byte multibyte character| -|[mbrtoc16, mbrtoc32](../c-runtime-library/reference/mbrtoc16-mbrtoc323.md)|Convert multibyte character to equivalent UTF-16 or UTF-32 character| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md), [mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters| -|[mbtowc, _mbtowc_l](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character| -|[strtod, _strtod_l, wcstod, _wcstod_l](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md)|Convert string to **`double`**| -|[strtol, wcstol, _strtol_l, _wcstol_l](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md)|Convert string to **`long`** integer| -|[strtoul, _strtoul_l, wcstoul, _wcstoul_l](../c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md)|Convert string to **`unsigned long`** integer| -|[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form based on locale-specific information| -|[toascii, __toascii](../c-runtime-library/reference/toascii-toascii.md)|Convert character to ASCII code| -|[tolower, _tolower, towlower, _tolower_l, _towlower_l](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Test character and convert to lowercase if currently uppercase| -|[tolower, _tolower, towlower, _tolower_l, _towlower_l](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md)|Convert character to lowercase unconditionally| -|[toupper, _toupper, towupper, _toupper_l, _towupper_l](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Test character and convert to uppercase if currently lowercase| -|[toupper, _toupper, towupper, _toupper_l, _towupper_l](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md)|Convert character to uppercase unconditionally| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md), [wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md), [wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character| -|[_wtof, _wtof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert wide-character string to a **`double`**| -|[_wtoi, _wtoi_l](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert wide-character string to **`int`**| -|[_wtoi64, _wtoi64_l](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert wide-character string to **`__int64`** or **`long long`**| -|[_wtol, _wtol_l](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert wide-character string to **`long`**| +| Routine | Use | +|---|---| +| [`abs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of integer | +| [`atof`, `_atof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Convert string to **`float`** | +| [`atoi`, `_atoi_l`](./reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert string to **`int`** | +| [`_atoi64`, `_atoi64_l`](./reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert string to **`__int64`** or **`long long`** | +| [`atol`, `_atol_l`](./reference/atol-atol-l-wtol-wtol-l.md) | Convert string to **`long`** | +| [`c16rtomb`, `c32rtomb`](./reference/c16rtomb-c32rtomb1.md) | Convert UTF-16 or UTF-32 character to equivalent multibyte character | +| [`_ecvt`](./reference/ecvt.md), [`_ecvt_s`](./reference/ecvt-s.md) | Convert **`double`** to string of specified length | +| [`_fcvt`](./reference/fcvt.md), [`_fcvt_s`](./reference/fcvt-s.md) | Convert **`double`** to string with specified number of digits following decimal point | +| [`_gcvt`](./reference/gcvt.md), [`_gcvt_s`](./reference/gcvt-s.md) | Convert **`double`** number to string; store string in buffer | +| [`_itoa`, `_ltoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `ultow`, `_i64tow`, `_ui64tow`](./reference/itoa-itow.md), [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](./reference/itoa-s-itow-s.md) | Convert integer types to string | +| [`labs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of **`long`** integer | +| [`llabs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of **`long long`** integer | +| [`_mbbtombc`, `_mbbtombc_l`](./reference/mbbtombc-mbbtombc-l.md) | Convert 1-byte multibyte character to corresponding 2-byte multibyte character | +| [`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](./reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md) | Convert Japan Industry Standard (JIS) character to Japan Microsoft (JMS) character | +| [`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](./reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md) | Convert JMS character to JIS character | +| [`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](./reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md) | Convert multibyte character to 1-byte hiragana code | +| [`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](./reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md) | Convert multibyte character to 1-byte katakana code | +| [`_mbctombb`, `_mbctombb_l`](./reference/mbctombb-mbctombb-l.md) | Convert 2-byte multibyte character to corresponding 1-byte multibyte character | +| [`mbrtoc16`, `mbrtoc32`](./reference/mbrtoc16-mbrtoc323.md) | Convert multibyte character to equivalent UTF-16 or UTF-32 character | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | +| [`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | +| [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](./reference/strtod-strtod-l-wcstod-wcstod-l.md) | Convert string to **`double`** | +| [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](./reference/strtol-wcstol-strtol-l-wcstol-l.md) | Convert string to **`long`** integer | +| [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](./reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) | Convert string to **`unsigned long`** integer | +| [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) | Transform string into collated form based on locale-specific information | +| [`toascii`, `__toascii`](./reference/toascii-toascii.md) | Convert character to ASCII code | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Test character and convert to lowercase if currently uppercase | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md) | Convert character to lowercase unconditionally | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Test character and convert to uppercase if currently lowercase | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md) | Convert character to uppercase unconditionally | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | +| [`_wtof`, `_wtof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Convert wide-character string to a **`double`** | +| [`_wtoi`, `_wtoi_l`](./reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert wide-character string to **`int`** | +| [`_wtoi64`, `_wtoi64_l`](./reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert wide-character string to **`__int64`** or **`long long`** | +| [`_wtol`, `_wtol_l`](./reference/atol-atol-l-wtol-wtol-l.md) | Convert wide-character string to **`long`** | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/data-type-constants.md b/docs/c-runtime-library/data-type-constants.md index 3811e66bb2..1c631e5b87 100644 --- a/docs/c-runtime-library/data-type-constants.md +++ b/docs/c-runtime-library/data-type-constants.md @@ -2,11 +2,10 @@ description: "Learn more about: Data Type Constants" title: "Data Type Constants" ms.date: "06/25/2018" -f1_keywords: ["FLT_MIN", "SHRT_MAX", "CHAR_MIN", "MB_LEN_MAX", "DBL_EPSILON", "SHRT_MIN", "_FLT_RADIX", "FLT_DIG", "FLT_MAX_10_EXP", "FLT_MANT_DIG", "DBL_MAX_EXP", "SCHAR_MIN", "SCHAR_MAX", "DBL_MIN", "FLT_MIN_10_EXP", "_DBL_ROUNDS", "USHRT_MAX", "FLT_MAX_EXP", "LONG_MAX", "DBL_MAX", "DBL_DIG", "FLT_MIN_EXP", "INT_MIN", "DBL_MIN_10_EXP", "CHAR_BIT", "INT_MAX", "ULONG_MAX", "DBL_MIN_EXP", "LONG_MIN", "_FLT_ROUNDS", "DBL_MANT_DIG", "_DBL_RADIX", "CHAR_MAX", "FLT_MAX", "DBL_MAX_10_EXP", "UCHAR_MAX", "FLT_EPSILON", "UINT_MAX", "LLONG_MIN", "LLONG_MAX", "ULLONG_MAX", "_I8_MIN", "_I8_MAX", "_UI8_MAX", "_I16_MIN", "_I16_MAX", "_UI16_MAX", "_I32_MIN", "_I32_MAX", "_UI32_MAX", "_I64_MIN", "_I64_MAX", "_UI64_MAX", "_I128_MIN", "_I128_MAX", "_UI128_MAX", "SIZE_MAX", "RSIZE_MAX", "LDBL_DIG", "LDBL_EPSILON", "LDBL_HAS_SUBNORM", "LDBL_MANT_DIG", "LDBL_MAX", "LDBL_MAX_10_EXP", "LDBL_MAX_EXP", "LDBL_MIN", "LDBL_MIN_10_EXP", "LDBL_MIN_EXP", "_LDBL_RADIX", "LDBL_TRUE_MIN", "DECIMAL_DIG"] +f1_keywords: ["CHAR_BIT", "SCHAR_MIN", "SCHAR_MAX", "UCHAR_MAX", "CHAR_MIN", "CHAR_MAX", "MB_LEN_MAX", "SHRT_MIN", "SHRT_MAX", "USHRT_MAX", "INT_MIN", "INT_MAX", "UINT_MAX", "LONG_MIN", "LONG_MAX", "ULONG_MAX", "LLONG_MIN", "LLONG_MAX", "ULLONG_MAX", "_I8_MIN", "_I8_MAX", "_UI8_MAX", "_I16_MIN", "_I16_MAX", "_UI16_MAX", "_I32_MIN", "_I32_MAX", "_UI32_MAX", "_I64_MIN", "_I64_MAX", "_UI64_MAX", "_I128_MIN", "_I128_MAX", "_UI128_MAX", "SIZE_MAX", "RSIZE_MAX", "LIMITS/CHAR_BIT", "LIMITS/SCHAR_MIN", "LIMITS/SCHAR_MAX", "LIMITS/UCHAR_MAX", "LIMITS/CHAR_MIN", "LIMITS/CHAR_MAX", "LIMITS/MB_LEN_MAX", "LIMITS/SHRT_MIN", "LIMITS/SHRT_MAX", "LIMITS/USHRT_MAX", "LIMITS/INT_MIN", "LIMITS/INT_MAX", "LIMITS/UINT_MAX", "LIMITS/LONG_MIN", "LIMITS/LONG_MAX", "LIMITS/ULONG_MAX", "LIMITS/LLONG_MIN", "LIMITS/LLONG_MAX", "LIMITS/ULLONG_MAX", "LIMITS/_I8_MIN", "LIMITS/_I8_MAX", "LIMITS/_UI8_MAX", "LIMITS/_I16_MIN", "LIMITS/_I16_MAX", "LIMITS/_UI16_MAX", "LIMITS/_I32_MIN", "LIMITS/_I32_MAX", "LIMITS/_UI32_MAX", "LIMITS/_I64_MIN", "LIMITS/_I64_MAX", "LIMITS/_UI64_MAX", "LIMITS/_I128_MIN", "LIMITS/_I128_MAX", "LIMITS/_UI128_MAX", "LIMITS/SIZE_MAX", "LIMITS/RSIZE_MAX", "DBL_DECIMAL_DIG", "DBL_DIG", "DBL_EPSILON", "DBL_HAS_SUBNORM", "DBL_MANT_DIG", "DBL_MAX", "DBL_MAX_10_EXP", "DBL_MAX_EXP", "DBL_MIN", "DBL_MIN_10_EXP", "DBL_MIN_EXP", "_DBL_RADIX", "DBL_TRUE_MIN", "FLT_DECIMAL_DIG", "FLT_DIG", "FLT_EPSILON", "FLT_HAS_SUBNORM", "FLT_MANT_DIG", "FLT_MAX", "FLT_MAX_10_EXP", "FLT_MAX_EXP", "FLT_MIN", "FLT_MIN_10_EXP", "FLT_MIN_EXP", "FLT_RADIX", "FLT_TRUE_MIN", "LDBL_DIG", "LDBL_EPSILON", "LDBL_HAS_SUBNORM", "LDBL_MANT_DIG", "LDBL_MAX", "LDBL_MAX_10_EXP", "LDBL_MAX_EXP", "LDBL_MIN", "LDBL_MIN_10_EXP", "LDBL_MIN_EXP", "_LDBL_RADIX", "LDBL_TRUE_MIN", "DECIMAL_DIG", "FLOAT/DBL_DECIMAL_DIG", "FLOAT/DBL_DIG", "FLOAT/DBL_EPSILON", "FLOAT/DBL_HAS_SUBNORM", "FLOAT/DBL_MANT_DIG", "FLOAT/DBL_MAX", "FLOAT/DBL_MAX_10_EXP", "FLOAT/DBL_MAX_EXP", "FLOAT/DBL_MIN", "FLOAT/DBL_MIN_10_EXP", "FLOAT/DBL_MIN_EXP", "FLOAT/_DBL_RADIX", "FLOAT/DBL_TRUE_MIN", "FLOAT/FLT_DECIMAL_DIG", "FLOAT/FLT_DIG", "FLOAT/FLT_EPSILON", "FLOAT/FLT_HAS_SUBNORM", "FLOAT/FLT_MANT_DIG", "FLOAT/FLT_MAX", "FLOAT/FLT_MAX_10_EXP", "FLOAT/FLT_MAX_EXP", "FLOAT/FLT_MIN", "FLOAT/FLT_MIN_10_EXP", "FLOAT/FLT_MIN_EXP", "FLOAT/FLT_RADIX", "FLOAT/FLT_TRUE_MIN", "FLOAT/LDBL_DIG", "FLOAT/LDBL_EPSILON", "FLOAT/LDBL_HAS_SUBNORM", "FLOAT/LDBL_MANT_DIG", "FLOAT/LDBL_MAX", "FLOAT/LDBL_MAX_10_EXP", "FLOAT/LDBL_MAX_EXP", "FLOAT/LDBL_MIN", "FLOAT/LDBL_MIN_10_EXP", "FLOAT/LDBL_MIN_EXP", "FLOAT/_LDBL_RADIX", "FLOAT/LDBL_TRUE_MIN", "FLOAT/DECIMAL_DIG"] helpviewer_keywords: ["DBL_MAX_EXP constant", "_DBL_RADIX constant", "FLT_MIN_EXP constant", "DBL_EPSILON constant", "INT_MIN constant", "FLT_EPSILON constant", "DBL_MANT_DIG constant", "_FLT_RADIX constant", "DBL_MIN constant", "USHRT_MAX constant", "FLT_MAX_10_EXP constant", "_FLT_ROUNDS constant", "data type constants [C++]", "_DBL_ROUNDS constant", "CHAR_MAX constant", "FLT_MAX_EXP constant", "FLT_MIN constant", "CHAR_MIN constant", "FLT_MIN_10_EXP constant", "DBL_MIN_EXP constant", "SCHAR_MAX constant", "FLT_RADIX constant", "CHAR_BIT constant", "UCHAR_MAX constant", "DBL_RADIX constant", "FLT_ROUNDS constant", "LONG_MIN constant", "SHRT_MAX constant", "LONG_MAX constant", "DBL_MAX_10_EXP constant", "DBL_MIN_10_EXP constant", "INT_MAX constant", "constants [C++], data type", "ULONG_MAX constant", "FLT_DIG constant", "MB_LEN_MAX constant", "DBL_DIG constant", "SHRT_MIN constant", "DBL_MAX constant", "DBL_ROUNDS constant", "FLT_MAX constant", "UINT_MAX constant", "FLT_MANT_DIG constant", "SCHAR_MIN constant", "LLONG_MIN constant", "LLONG_MAX constant", "ULLONG_MAX constant", "_I8_MIN constant", "_I8_MAX constant", "_UI8_MAX constant", "_I16_MIN constant", "_I16_MAX constant", "_UI16_MAX constant", "_I32_MIN constant", "_I32_MAX constant", "_UI32_MAX constant", "_I64_MIN constant", "_I64_MAX constant", "_UI64_MAX constant", "_I128_MIN constant", "_I128_MAX constant", "_UI128_MAX constant", "SIZE_MAX constant", "RSIZE_MAX constant"] -ms.assetid: c0f1c405-0465-41d5-b5ff-e81cdb6f1622 --- -# Data Type Constants +# Data type constants Data type constants are implementation-dependent ranges of values allowed for integral and floating-point data types. @@ -21,44 +20,44 @@ These constants give the ranges for the integral data types. To use these consta > [!NOTE] > The [`/J`](../build/reference/j-default-char-type-is-unsigned.md) compiler option changes the default **`char`** type from **`signed char`** to **`unsigned char`**. -|Constant|Value|Description| -|--------------|-----------|-------------| -|**CHAR_BIT**|8|Number of bits in a **`char`**| -|**SCHAR_MIN**|(-128)|Minimum **`signed char`** value| -|**SCHAR_MAX**|127|Maximum **`signed char`** value| -|**UCHAR_MAX**|255 (0xff)|Maximum **`unsigned char`** value| -|**CHAR_MIN**|(-128) (0 if **`/J`** option used)|Minimum **`char`** value| -|**CHAR_MAX**|127 (255 if **`/J`** option used)|Maximum **`char`** value| -|**MB_LEN_MAX**|5|Maximum number of bytes in multibyte **`char`**| -|**SHRT_MIN**|-32768|Minimum **`signed short`** value| -|**SHRT_MAX**|32767|Maximum **`signed short`** value| -|**USHRT_MAX**|65535 (0xffff)|Maximum **`unsigned short`** value| -|**INT_MIN**|(-2147483647 - 1)|Minimum **`signed int`** value| -|**INT_MAX**|2147483647|Maximum **`signed int`** value| -|**UINT_MAX**|4294967295 (0xffffffff)|Maximum **`unsigned int`** value| -|**LONG_MIN**|(-2147483647L - 1)|Minimum **`signed long`** value| -|**LONG_MAX**|2147483647L|Maximum **`signed long`** value| -|**ULONG_MAX**|4294967295UL (0xfffffffful)|Maximum **`unsigned long`** value| -|**LLONG_MIN**|(-9223372036854775807LL - 1)|Minimum **`signed long long`** or **`__int64`** value| -|**LLONG_MAX**|9223372036854775807LL|Maximum **`signed long long`** or **`__int64`** value| -|**ULLONG_MAX**|0xffffffffffffffffull|Maximum **`unsigned long long`** value| -|**_I8_MIN**|(-127i8 - 1)|Minimum signed 8-bit value| -|**_I8_MAX**|127i8|Maximum signed 8-bit value| -|**_UI8_MAX**|0xffui8|Maximum unsigned 8-bit value| -|**_I16_MIN**|(-32767i16 - 1)|Minimum signed 16-bit value| -|**_I16_MAX**|32767i16|Maximum signed 16-bit value| -|**_UI16_MAX**|0xffffui16|Maximum unsigned 16-bit value| -|**_I32_MIN**|(-2147483647i32 - 1)|Minimum signed 32-bit value| -|**_I32_MAX**|2147483647i32|Maximum signed 32-bit value| -|**_UI32_MAX**|0xffffffffui32|Maximum unsigned 32-bit value| -|**_I64_MIN**|(-9223372036854775807 - 1)|Minimum signed 64-bit value| -|**_I64_MAX**|9223372036854775807|Maximum signed 64-bit value| -|**_UI64_MAX**|0xffffffffffffffffui64|Maximum unsigned 64-bit value| -|**_I128_MIN**|(-170141183460469231731687303715884105727i128 - 1)|Minimum signed 128-bit value| -|**_I128_MAX**|170141183460469231731687303715884105727i128|Maximum signed 128-bit value| -|**_UI128_MAX**|0xffffffffffffffffffffffffffffffffui128|Maximum unsigned 128-bit value| -|**SIZE_MAX**|same as **_UI64_MAX** if **_WIN64** is defined, or **UINT_MAX**|Maximum native integer size| -|**RSIZE_MAX**|same as (**SIZE_MAX** >> 1)|Maximum secure library integer size| +| Constant | Value | Description | +|---|---|---| +| `CHAR_BIT` | 8 | Number of bits in a **`char`** | +| `SCHAR_MIN` | (-128) | Minimum **`signed char`** value | +| `SCHAR_MAX` | 127 | Maximum **`signed char`** value | +| `UCHAR_MAX` | 255 (0xff) | Maximum **`unsigned char`** value | +| `CHAR_MIN` | (-128) (0 if **`/J`** option used) | Minimum **`char`** value | +| `CHAR_MAX` | 127 (255 if **`/J`** option used) | Maximum **`char`** value | +| `MB_LEN_MAX` | 5 | Maximum number of bytes in multibyte **`char`** | +| `SHRT_MIN` | -32768 | Minimum **`signed short`** value | +| `SHRT_MAX` | 32767 | Maximum **`signed short`** value | +| `USHRT_MAX` | 65535 (0xffff) | Maximum **`unsigned short`** value | +| `INT_MIN` | (-2147483647 - 1) | Minimum **`signed int`** value | +| `INT_MAX` | 2147483647 | Maximum **`signed int`** value | +| `UINT_MAX` | 4294967295 (0xffffffff) | Maximum **`unsigned int`** value | +| `LONG_MIN` | (-2147483647L - 1) | Minimum **`signed long`** value | +| `LONG_MAX` | 2147483647L | Maximum **`signed long`** value | +| `ULONG_MAX` | 4294967295UL (0xfffffffful) | Maximum **`unsigned long`** value | +| `LLONG_MIN` | (-9223372036854775807LL - 1) | Minimum **`signed long long`** or **`__int64`** value | +| `LLONG_MAX` | 9223372036854775807LL | Maximum **`signed long long`** or **`__int64`** value | +| `ULLONG_MAX` | 0xffffffffffffffffull | Maximum **`unsigned long long`** value | +| `_I8_MIN` | (-127i8 - 1) | Minimum signed 8-bit value | +| `_I8_MAX` | 127i8 | Maximum signed 8-bit value | +| `_UI8_MAX` | 0xffui8 | Maximum unsigned 8-bit value | +| `_I16_MIN` | (-32767i16 - 1) | Minimum signed 16-bit value | +| `_I16_MAX` | 32767i16 | Maximum signed 16-bit value | +| `_UI16_MAX` | 0xffffui16 | Maximum unsigned 16-bit value | +| `_I32_MIN` | (-2147483647i32 - 1) | Minimum signed 32-bit value | +| `_I32_MAX` | 2147483647i32 | Maximum signed 32-bit value | +| `_UI32_MAX` | 0xffffffffui32 | Maximum unsigned 32-bit value | +| `_I64_MIN` | (-9223372036854775807 - 1) | Minimum signed 64-bit value | +| `_I64_MAX` | 9223372036854775807 | Maximum signed 64-bit value | +| `_UI64_MAX` | 0xffffffffffffffffui64 | Maximum unsigned 64-bit value | +| `_I128_MIN` | (-170141183460469231731687303715884105727i128 - 1) | Minimum signed 128-bit value | +| `_I128_MAX` | 170141183460469231731687303715884105727i128 | Maximum signed 128-bit value | +| `_UI128_MAX` | 0xffffffffffffffffffffffffffffffffui128 | Maximum unsigned 128-bit value | +| `SIZE_MAX` | same as `_UI64_MAX` if `_WIN64` is defined, or `UINT_MAX` | Maximum native integer size | +| `RSIZE_MAX` | same as (`SIZE_MAX` >> 1) | Maximum secure library integer size | ## Floating-point type constants @@ -68,48 +67,48 @@ The following constants give the range and other characteristics of the **`long #include ``` -|Constant|Value|Description| -|--------------|-----------|-----------------| -|**DBL_DECIMAL_DIG**|17|# of decimal digits of rounding precision| -|**DBL_DIG**|15|# of decimal digits of precision| -|**DBL_EPSILON**|2.2204460492503131e-016|Smallest such that 1.0 + **DBL_EPSILON** != 1.0| -|**DBL_HAS_SUBNORM**|1|Type supports subnormal (denormal) numbers| -|**DBL_MANT_DIG**|53|# of bits in significand (mantissa)| -|**DBL_MAX**|1.7976931348623158e+308|Maximum value| -|**DBL_MAX_10_EXP**|308|Maximum decimal exponent| -|**DBL_MAX_EXP**|1024|Maximum binary exponent| -|**DBL_MIN**|2.2250738585072014e-308|Minimum normalized positive value| -|**DBL_MIN_10_EXP**|(-307)|Minimum decimal exponent| -|**DBL_MIN_EXP**|(-1021)|Minimum binary exponent| -|**_DBL_RADIX**|2|Exponent radix| -|**DBL_TRUE_MIN**|4.9406564584124654e-324|Minimum positive subnormal value| -|**FLT_DECIMAL_DIG**|9|Number of decimal digits of rounding precision| -|**FLT_DIG**|6|Number of decimal digits of precision| -|**FLT_EPSILON**|1.192092896e-07F|Smallest such that 1.0 + **FLT_EPSILON** != 1.0| -|**FLT_HAS_SUBNORM**|1|Type supports subnormal (denormal) numbers| -|**FLT_MANT_DIG**|24|Number of bits in significand (mantissa)| -|**FLT_MAX**|3.402823466e+38F|Maximum value| -|**FLT_MAX_10_EXP**|38|Maximum decimal exponent| -|**FLT_MAX_EXP**|128|Maximum binary exponent| -|**FLT_MIN**|1.175494351e-38F|Minimum normalized positive value| -|**FLT_MIN_10_EXP**|(-37)|Minimum decimal exponent| -|**FLT_MIN_EXP**|(-125)|Minimum binary exponent| -|**FLT_RADIX**|2|Exponent radix| -|**FLT_TRUE_MIN**|1.401298464e-45F|Minimum positive subnormal value| -|**LDBL_DIG**|15|# of decimal digits of precision| -|**LDBL_EPSILON**|2.2204460492503131e-016|Smallest such that 1.0 + **LDBL_EPSILON** != 1.0| -|**LDBL_HAS_SUBNORM**|1|Type supports subnormal (denormal) numbers| -|**LDBL_MANT_DIG**|53|# of bits in significand (mantissa)| -|**LDBL_MAX**|1.7976931348623158e+308|Maximum value| -|**LDBL_MAX_10_EXP**|308|Maximum decimal exponent| -|**LDBL_MAX_EXP**|1024|Maximum binary exponent| -|**LDBL_MIN**|2.2250738585072014e-308|Minimum normalized positive value| -|**LDBL_MIN_10_EXP**|(-307)|Minimum decimal exponent| -|**LDBL_MIN_EXP**|(-1021)|Minimum binary exponent| -|**_LDBL_RADIX**|2|Exponent radix| -|**LDBL_TRUE_MIN**|4.9406564584124654e-324|Minimum positive subnormal value| -|**DECIMAL_DIG**|same as **DBL_DECIMAL_DIG**|Default (double) decimal digits of rounding precision| +| Constant | Value | Description | +|---|---|---| +| `DBL_DECIMAL_DIG` | 17 | # of decimal digits of rounding precision | +| `DBL_DIG` | 15 | # of decimal digits of precision | +| `DBL_EPSILON` | 2.2204460492503131e-016 | Smallest such that 1.0 + `DBL_EPSILON` != 1.0 | +| `DBL_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `DBL_MANT_DIG` | 53 | # of bits in significand (mantissa) | +| `DBL_MAX` | 1.7976931348623158e+308 | Maximum value | +| `DBL_MAX_10_EXP` | 308 | Maximum decimal exponent | +| `DBL_MAX_EXP` | 1024 | Maximum binary exponent | +| `DBL_MIN` | 2.2250738585072014e-308 | Minimum normalized positive value | +| `DBL_MIN_10_EXP` | (-307) | Minimum decimal exponent | +| `DBL_MIN_EXP` | (-1021) | Minimum binary exponent | +| `_DBL_RADIX` | 2 | Exponent radix | +| `DBL_TRUE_MIN` | 4.9406564584124654e-324 | Minimum positive subnormal value | +| `FLT_DECIMAL_DIG` | 9 | Number of decimal digits of rounding precision | +| `FLT_DIG` | 6 | Number of decimal digits of precision | +| `FLT_EPSILON` | 1.192092896e-07F | Smallest such that 1.0 + `FLT_EPSILON` != 1.0 | +| `FLT_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `FLT_MANT_DIG` | 24 | Number of bits in significand (mantissa) | +| `FLT_MAX` | 3.402823466e+38F | Maximum value | +| `FLT_MAX_10_EXP` | 38 | Maximum decimal exponent | +| `FLT_MAX_EXP` | 128 | Maximum binary exponent | +| `FLT_MIN` | 1.175494351e-38F | Minimum normalized positive value | +| `FLT_MIN_10_EXP` | (-37) | Minimum decimal exponent | +| `FLT_MIN_EXP` | (-125) | Minimum binary exponent | +| `FLT_RADIX` | 2 | Exponent radix | +| `FLT_TRUE_MIN` | 1.401298464e-45F | Minimum positive subnormal value | +| `LDBL_DIG` | 15 | # of decimal digits of precision | +| `LDBL_EPSILON` | 2.2204460492503131e-016 | Smallest such that 1.0 + `LDBL_EPSILON` != 1.0 | +| `LDBL_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `LDBL_MANT_DIG` | 53 | # of bits in significand (mantissa) | +| `LDBL_MAX` | 1.7976931348623158e+308 | Maximum value | +| `LDBL_MAX_10_EXP` | 308 | Maximum decimal exponent | +| `LDBL_MAX_EXP` | 1024 | Maximum binary exponent | +| `LDBL_MIN` | 2.2250738585072014e-308 | Minimum normalized positive value | +| `LDBL_MIN_10_EXP` | (-307) | Minimum decimal exponent | +| `LDBL_MIN_EXP` | (-1021) | Minimum binary exponent | +| `_LDBL_RADIX` | 2 | Exponent radix | +| `LDBL_TRUE_MIN` | 4.9406564584124654e-324 | Minimum positive subnormal value | +| `DECIMAL_DIG` | same as `DBL_DECIMAL_DIG` | Default (double) decimal digits of rounding precision | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/data-type-mappings.md b/docs/c-runtime-library/data-type-mappings.md index aa0d1a52f0..3ae69e97e5 100644 --- a/docs/c-runtime-library/data-type-mappings.md +++ b/docs/c-runtime-library/data-type-mappings.md @@ -2,34 +2,34 @@ description: "Learn more about: Data Type Mappings" title: "Data Type Mappings" ms.date: "11/04/2016" -f1_keywords: ["_TXCHAR", "_TUCHAR", "_TINT", "_TSCHAR", "_TCHAR", "TCHAR::H", "TCHAR", "_T", "_TEXT"] +f1_keywords: ["_TXCHAR", "_TUCHAR", "_TINT", "_TSCHAR", "_TCHAR", "TCHAR", "_T", "_TEXT"] helpviewer_keywords: ["_TXCHAR type", "TINT type", "_TCHAR type", "TSCHAR type", "TEXT type", "TCHAR type", "TCHAR.H data types, mappings defined in", "generic-text data types", "_TINT type", "TUCHAR type", "TXCHAR type", "_TSCHAR type", "T type", "_TUCHAR type", "_TEXT type", "_T type"] ms.assetid: 4e573c05-8800-468b-ae5f-76ff7409835e --- -# Data Type Mappings +# Data type mappings These data-type mappings are defined in TCHAR.H and depend on whether the constant `_UNICODE` or `_MBCS` has been defined in your program. For related information, see [Using TCHAR.H Data Types with _MBCS Code](../text/using-tchar-h-data-types-with-mbcs-code.md). -### Generic-Text Data Type Mappings +### Generic-text data type mappings -|Generic-text

data type name|SBCS (_UNICODE,

_MBCS not

defined)|_MBCS

defined|_UNICODE

defined| -|--------------------------------------|----------------------------------------------------|------------------------|---------------------------| -|`_TCHAR`|**`char`**|**`char`**|**`wchar_t`**| -|`_tfinddata_t`|`_finddata_t`|`_finddata_t`|`_wfinddata_t`| -|`_tfinddata64_t`|`__finddata64_t`|`__finddata64_t`|`__wfinddata64_t`| -|`_tfinddatai64_t`|`_finddatai64_t`|`_finddatai64_t`|`_wfinddatai64_t`| -|`_TINT`|**`int`**|**`int`**|`wint_t`| -|`_TSCHAR`|**`signed char`**|**`signed char`**|**`wchar_t`**| -|`_TUCHAR`|**`unsigned char`**|**`unsigned char`**|**`wchar_t`**| -|`_TXCHAR`|**`char`**|**`unsigned char`**|**`wchar_t`**| -|`_T` or `_TEXT`|No effect (removed by preprocessor)|No effect (removed by preprocessor)|`L` (converts following character or string to its Unicode counterpart)| +| Generic-text

data type name | SBCS (_UNICODE,

_MBCS not

defined) | _MBCS

defined | _UNICODE

defined | +|---|---|---|---| +| `_TCHAR` | **`char`** | **`char`** | **`wchar_t`** | +| `_tfinddata_t` | `_finddata_t` | `_finddata_t` | `_wfinddata_t` | +| `_tfinddata64_t` | `__finddata64_t` | `__finddata64_t` | `_wfinddata64_t` | +| `_tfinddatai64_t` | `_finddatai64_t` | `_finddatai64_t` | `_wfinddatai64_t` | +| `_TINT` | **`int`** | **`int`** | `wint_t` | +| `_TSCHAR` | **`signed char`** | **`signed char`** | **`wchar_t`** | +| `_TUCHAR` | **`unsigned char`** | **`unsigned char`** | **`wchar_t`** | +| `_TXCHAR` | **`char`** | **`unsigned char`** | **`wchar_t`** | +| `_T` or `_TEXT` | No effect (removed by preprocessor) | No effect (removed by preprocessor) | `L` (converts following character or string to its Unicode counterpart) | ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/daylight-dstbias-timezone-and-tzname.md b/docs/c-runtime-library/daylight-dstbias-timezone-and-tzname.md index 3ce1b9c440..997a01c0ef 100644 --- a/docs/c-runtime-library/daylight-dstbias-timezone-and-tzname.md +++ b/docs/c-runtime-library/daylight-dstbias-timezone-and-tzname.md @@ -2,26 +2,26 @@ description: "Learn more about: _daylight, _dstbias, _timezone, and _tzname" title: "_daylight, _dstbias, _timezone, and _tzname" ms.date: "11/04/2016" -f1_keywords: ["tzname", "_timezone", "timezone", "_daylight", "_tzname", "daylight"] -helpviewer_keywords: ["time zones", "time adjustments", "timezone variables", "_tzname function", "_daylight function", "_timezone function", "daylight function", "local time adjustments", "timezone function", "tzname function", "time-zone variables"] +f1_keywords: ["_daylight", "TIME/_daylight", "_dstbias", "TIME/_dstbias", "_timezone", "TIME/_timezone", "_tzname", "TIME/_tzname"] +helpviewer_keywords: ["time zones", "time adjustments", "timezone variables", "_daylight global variable", "_dstbias global variable", "_timezone global variable", "_tzname global variable", "local time adjustments", "time-zone variables"] ms.assetid: d06c7292-6b99-4aba-b284-16a96570c856 --- -# _daylight, _dstbias, _timezone, and _tzname +# `_daylight`, `_dstbias`, `_timezone`, and `_tzname` -`_daylight`, `_dstbias`, `_timezone`, and `_tzname` are used in some time and date routines to make local-time adjustments. These global variables have been deprecated for the more secure functional versions, which should be used in place of the global variables. +**`_daylight`**, **`_dstbias`**, **`_timezone`**, and **`_tzname`** are used in some time and date routines to make local-time adjustments. These global variables have been deprecated for the more secure functional versions, which should be used in place of the global variables. -|Global variable|Functional equivalent| -|---------------------|---------------------------| -|`_daylight`|[_get_daylight](../c-runtime-library/reference/get-daylight.md)| -|`_dstbias`|[_get_dstbias](../c-runtime-library/reference/get-dstbias.md)| -|`_timezone`|[_get_timezone](../c-runtime-library/reference/get-timezone.md)| -|`_tzname`|[_get_tzname](../c-runtime-library/reference/get-tzname.md)| +| Global variable | Functional equivalent | +|---|---| +| **`_daylight`** | [`_get_daylight`](./reference/get-daylight.md) | +| **`_dstbias`** | [`_get_dstbias`](./reference/get-dstbias.md) | +| **`_timezone`** | [`_get_timezone`](./reference/get-timezone.md) | +| **`_tzname`** | [`_get_tzname`](./reference/get-tzname.md) | -They are declared in Time.h as follows. +They're declared in Time.h as follows. ## Syntax -``` +```C extern int _daylight; extern int _dstbias; extern long _timezone; @@ -30,20 +30,20 @@ extern char *_tzname[2]; ## Remarks -On a call to `_ftime`, `localtime`, or `_tzset`, the values of `_daylight`, `_dstbias`, `_timezone`, and `_tzname` are determined from the value of the `TZ` environment variable. If you do not explicitly set the value of `TZ`, `_tzname[0]` and `_tzname[1]` contain the default settings of "PST" and "PDT" respectively. The time-manipulation functions ([_tzset](../c-runtime-library/reference/tzset.md), [_ftime](../c-runtime-library/reference/ftime-ftime32-ftime64.md), and [localtime](../c-runtime-library/reference/localtime-localtime32-localtime64.md)) attempt to set the values of `_daylight`, `_dstbias` and `_timezone` by querying the operating system for the default value of each variable. The time-zone global variable values are shown in the following table. +On a call to `_ftime`, `localtime`, or `_tzset`, the values of **`_daylight`**, **`_dstbias`**, **`_timezone`**, and **`_tzname`** are determined from the value of the `TZ` environment variable. If you don't explicitly set the value of `TZ`, `_tzname[0]` and `_tzname[1]` contain the default settings of "PST" and "PDT" respectively. The time-manipulation functions ([`_tzset`](./reference/tzset.md), [`_ftime`](./reference/ftime-ftime32-ftime64.md), and [`localtime`](./reference/localtime-localtime32-localtime64.md)) attempt to set the values of **`_daylight`**, **`_dstbias`** and **`_timezone`** by querying the operating system for the default value of each variable. The time-zone global variable values are shown in the following table. -|Variable|Value| -|--------------|-----------| -|`_daylight`|Nonzero if daylight saving time (DST) zone is specified in `TZ` or determined from the operating system; otherwise, 0. The default value is 1.| -|`_dstbias`|Offset for daylight saving time.| -|`_timezone`|Difference in seconds between coordinated universal time and local time. The default value is 28,800.| -|`_tzname[0]`|Time-zone name derived from the `TZ` environment variable. The default value is "PST".| -|`_tzname[1]`|DST zone name derived from the `TZ` environment variable. The default value is "PDT" (Pacific daylight time).| +| Variable | Value | +|---|---| +| **`_daylight`** | Nonzero if daylight saving time (DST) zone is specified in `TZ` or determined from the operating system; otherwise, 0. The default value is 1. | +| **`_dstbias`** | Offset for daylight saving time. | +| **`_timezone`** | Difference in seconds between coordinated universal time and local time. The default value is 28,800. | +| `_tzname[0]` | Time-zone name derived from the `TZ` environment variable. The default value is "PST". | +| `_tzname[1]` | DST zone name derived from the `TZ` environment variable. The default value is "PDT" (Pacific daylight time). | ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[_get_daylight](../c-runtime-library/reference/get-daylight.md)
-[_get_dstbias](../c-runtime-library/reference/get-dstbias.md)
-[_get_timezone](../c-runtime-library/reference/get-timezone.md)
-[_get_tzname](../c-runtime-library/reference/get-tzname.md) +[Global variables](./global-variables.md)\ +[`_get_daylight`](./reference/get-daylight.md)\ +[`_get_dstbias`](./reference/get-dstbias.md)\ +[`_get_timezone`](./reference/get-timezone.md)\ +[`_get_tzname`](./reference/get-tzname.md) diff --git a/docs/c-runtime-library/debug-routines.md b/docs/c-runtime-library/debug-routines.md index 4678751db2..eb6d0ab2dd 100644 --- a/docs/c-runtime-library/debug-routines.md +++ b/docs/c-runtime-library/debug-routines.md @@ -20,120 +20,120 @@ The debug version of the C runtime library supplies many diagnostic services tha ## Debug versions of the C runtime library routines -To use these routines, the [_DEBUG](../c-runtime-library/debug.md) flag must be defined. All of these routines do nothing in a retail build of an application. For more information on how to use the new debug routines, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +To use these routines, the [`_DEBUG`](./debug.md) flag must be defined. All of these routines do nothing in a retail build of an application. For more information on how to use the new debug routines, see [CRT debugging techniques](./crt-debugging-techniques.md). | Routine | Use | |--|--| -| [`_ASSERT`](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) | Evaluate an expression and generates a debug report when the result is FALSE | -| [`_ASSERTE`](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) | Similar to **`_ASSERT`**, but includes the failed expression in the generated report | -| [`_CrtCheckMemory`](../c-runtime-library/reference/crtcheckmemory.md) | Confirm the integrity of the memory blocks allocated on the debug heap | -| [`_CrtDbgBreak`](../c-runtime-library/reference/crtdbgbreak.md) | Sets a break point. | -| [`_CrtDbgReport`, `_CrtDbgReportW`](../c-runtime-library/reference/crtdbgreport-crtdbgreportw.md) | Generate a debug report with a user message and send the report to three possible destinations | -| [`_CrtDoForAllClientObjects`](../c-runtime-library/reference/crtdoforallclientobjects.md) | Call an application-supplied function for all `_CLIENT_BLOCK` types on the heap | -| [`_CrtDumpMemoryLeaks`](../c-runtime-library/reference/crtdumpmemoryleaks.md) | Dump all of the memory blocks on the debug heap when a significant memory leak has occurred | -| [`_CrtIsMemoryBlock`](../c-runtime-library/reference/crtismemoryblock.md) | Verify that a specified memory block is located within the local heap and that it has a valid debug heap block type identifier | -| [`_CrtIsValidHeapPointer`](../c-runtime-library/reference/crtisvalidheappointer.md) | Verifies that a specified pointer is in the local heap | -| [`_CrtIsValidPointer`](../c-runtime-library/reference/crtisvalidpointer.md) | Verify that a specified memory range is valid for reading and writing | -| [`_CrtMemCheckpoint`](../c-runtime-library/reference/crtmemcheckpoint.md) | Obtain the current state of the debug heap and store it in an application-supplied `_CrtMemState` structure | -| [`_CrtMemDifference`](../c-runtime-library/reference/crtmemdifference.md) | Compare two memory states for significant differences and return the results | -| [`_CrtMemDumpAllObjectsSince`](../c-runtime-library/reference/crtmemdumpallobjectssince.md) | Dump information about objects on the heap since a specified checkpoint was taken or from the start of program execution | -| [`_CrtMemDumpStatistics`](../c-runtime-library/reference/crtmemdumpstatistics.md) | Dump the debug header information for a specified memory state in a user-readable form | -| [`_CrtReportBlockType`](../c-runtime-library/reference/crtreportblocktype.md) | Returns the block type/subtype associated with a given debug heap block pointer. | -| [`_CrtSetAllocHook`](../c-runtime-library/reference/crtsetallochook.md) | Install a client-defined allocation function by hooking it into the C run-time debug memory allocation process | -| [`_CrtSetBreakAlloc`](../c-runtime-library/reference/crtsetbreakalloc.md) | Set a breakpoint on a specified object allocation order number | -| [`_CrtSetDbgFlag`](../c-runtime-library/reference/crtsetdbgflag.md) | Retrieve or modify the state of the `_crtDbgFlag` flag to control the allocation behavior of the debug heap manager | -| [`_CrtSetDumpClient`](../c-runtime-library/reference/crtsetdumpclient.md) | Install an application-defined function that is called every time a debug dump function is called to dump `_CLIENT_BLOCK` type memory blocks | -| [`_CrtSetReportFile`](../c-runtime-library/reference/crtsetreportfile.md) | Identify the file or stream to be used as a destination for a specific report type by `_CrtDbgReport` | -| [`_CrtSetReportHook`](../c-runtime-library/reference/crtsetreporthook.md) | Install a client-defined reporting function by hooking it into the C run-time debug reporting process | -| [`_CrtSetReportHook2`, `_CrtSetReportHookW2`](../c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md) | Installs or uninstalls a client-defined reporting function by hooking it into the C run-time debug reporting process. | -| [`_CrtSetReportMode`](../c-runtime-library/reference/crtsetreportmode.md) | Specify the general destination(s) for a specific report type generated by `_CrtDbgReport` | -| [`_RPT[0,1,2,3,4]`](../c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md) | Track the application's progress by generating a debug report by calling `_CrtDbgReport` with a format string and a variable number of arguments. Provides no source file and line number information. | -| [`_RPTF[0,1,2,3,4]`](../c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md) | Similar to the `_RPTn` macros, but provides the source file name and line number where the report request originated | -| [`_calloc_dbg`](../c-runtime-library/reference/calloc-dbg.md) | Allocate a specified number of memory blocks on the heap with additional space for a debugging header and overwrite buffers | -| [`_expand_dbg`](../c-runtime-library/reference/expand-dbg.md) | Resize a specified block of memory on the heap by expanding or contracting the block | -| [`_free_dbg`](../c-runtime-library/reference/free-dbg.md) | Free a block of memory on the heap | -| [`_fullpath_dbg`, `_wfullpath_dbg`](../c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md) | Create an absolute or full path name for the specified relative path name, using [`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md) to allocate memory. | -| [`_getcwd_dbg`, `_wgetcwd_dbg`](../c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md) | Get the current working directory, using [`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md) to allocate memory. | -| [`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md) | Allocate a block of memory on the heap with additional space for a debugging header and overwrite buffers | -| [`_msize_dbg`](../c-runtime-library/reference/msize-dbg.md) | Calculate the size of a block of memory on the heap | -| [`_realloc_dbg`](../c-runtime-library/reference/realloc-dbg.md) | Reallocate a specified block of memory on the heap by moving and/or resizing the block | -| [`_strdup_dbg`, `_wcsdup_dbg`](../c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md) | Duplicates a string, using [`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md) to allocate memory. | -| [`_tempnam_dbg`, `_wtempnam_dbg`](../c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md) | Generate names you can use to create temporary files, using [`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md) to allocate memory. | - -## C runtime routines that are not available in source code form - -The debugger can be used to step through the source code for most of the C runtime routines during the debugging process. However, Microsoft considers some technology to be proprietary and, therefore, does not provide the source code for a subset of these routines. Most of these routines belong to either the exception handling or floating-point processing groups, but a few others are included as well. The following table lists these routines. +| [`_ASSERT`](./reference/assert-asserte-assert-expr-macros.md) | Evaluate an expression and generates a debug report when the result is `FALSE` | +| [`_ASSERTE`](./reference/assert-asserte-assert-expr-macros.md) | Similar to `_ASSERT`, but includes the failed expression in the generated report | +| [`_CrtCheckMemory`](./reference/crtcheckmemory.md) | Confirm the integrity of the memory blocks allocated on the debug heap | +| [`_CrtDbgBreak`](./reference/crtdbgbreak.md) | Sets a break point. | +| [`_CrtDbgReport`, `_CrtDbgReportW`](./reference/crtdbgreport-crtdbgreportw.md) | Generate a debug report with a user message and send the report to three possible destinations | +| [`_CrtDoForAllClientObjects`](./reference/crtdoforallclientobjects.md) | Call an application-supplied function for all `_CLIENT_BLOCK` types on the heap | +| [`_CrtDumpMemoryLeaks`](./reference/crtdumpmemoryleaks.md) | Dump all of the memory blocks on the debug heap when a significant memory leak has occurred | +| [`_CrtIsMemoryBlock`](./reference/crtismemoryblock.md) | Verify that a specified memory block is located within the local heap and that it has a valid debug heap block type identifier | +| [`_CrtIsValidHeapPointer`](./reference/crtisvalidheappointer.md) | Verifies that a specified pointer is in the local heap | +| [`_CrtIsValidPointer`](./reference/crtisvalidpointer.md) | Verify that a specified memory range is valid for reading and writing | +| [`_CrtMemCheckpoint`](./reference/crtmemcheckpoint.md) | Obtain the current state of the debug heap and store it in an application-supplied `_CrtMemState` structure | +| [`_CrtMemDifference`](./reference/crtmemdifference.md) | Compare two memory states for significant differences and return the results | +| [`_CrtMemDumpAllObjectsSince`](./reference/crtmemdumpallobjectssince.md) | Dump information about objects on the heap since a specified checkpoint was taken or from the start of program execution | +| [`_CrtMemDumpStatistics`](./reference/crtmemdumpstatistics.md) | Dump the debug header information for a specified memory state in a user-readable form | +| [`_CrtReportBlockType`](./reference/crtreportblocktype.md) | Returns the block type/subtype associated with a given debug heap block pointer. | +| [`_CrtSetAllocHook`](./reference/crtsetallochook.md) | Install a client-defined allocation function by hooking it into the C run-time debug memory allocation process | +| [`_CrtSetBreakAlloc`](./reference/crtsetbreakalloc.md) | Set a breakpoint on a specified object allocation order number | +| [`_CrtSetDbgFlag`](./reference/crtsetdbgflag.md) | Retrieve or modify the state of the `_crtDbgFlag` flag to control the allocation behavior of the debug heap manager | +| [`_CrtSetDumpClient`](./reference/crtsetdumpclient.md) | Install an application-defined function that is called every time a debug dump function is called to dump `_CLIENT_BLOCK` type memory blocks | +| [`_CrtSetReportFile`](./reference/crtsetreportfile.md) | Identify the file or stream to be used as a destination for a specific report type by `_CrtDbgReport` | +| [`_CrtSetReportHook`](./reference/crtsetreporthook.md) | Install a client-defined reporting function by hooking it into the C run-time debug reporting process | +| [`_CrtSetReportHook2`, `_CrtSetReportHookW2`](./reference/crtsetreporthook2-crtsetreporthookw2.md) | Installs or uninstalls a client-defined reporting function by hooking it into the C run-time debug reporting process. | +| [`_CrtSetReportMode`](./reference/crtsetreportmode.md) | Specify the general destination(s) for a specific report type generated by `_CrtDbgReport` | +| [`_RPT[0,1,2,3,4]`](./reference/rpt-rptf-rptw-rptfw-macros.md) | Track the application's progress by generating a debug report by calling `_CrtDbgReport` with a format string and a variable number of arguments. Provides no source file and line number information. | +| [`_RPTF[0,1,2,3,4]`](./reference/rpt-rptf-rptw-rptfw-macros.md) | Similar to the `_RPTn` macros, but provides the source file name and line number where the report request originated | +| [`_calloc_dbg`](./reference/calloc-dbg.md) | Allocate a specified number of memory blocks on the heap with extra space for a debugging header and overwrite buffers | +| [`_expand_dbg`](./reference/expand-dbg.md) | Resize a specified block of memory on the heap by expanding or contracting the block | +| [`_free_dbg`](./reference/free-dbg.md) | Free a block of memory on the heap | +| [`_fullpath_dbg`, `_wfullpath_dbg`](./reference/fullpath-dbg-wfullpath-dbg.md) | Create an absolute or full path name for the specified relative path name, using [`_malloc_dbg`](./reference/malloc-dbg.md) to allocate memory. | +| [`_getcwd_dbg`, `_wgetcwd_dbg`](./reference/getcwd-dbg-wgetcwd-dbg.md) | Get the current working directory, using [`_malloc_dbg`](./reference/malloc-dbg.md) to allocate memory. | +| [`_malloc_dbg`](./reference/malloc-dbg.md) | Allocate a block of memory on the heap with extra space for a debugging header and overwrite buffers | +| [`_msize_dbg`](./reference/msize-dbg.md) | Calculate the size of a block of memory on the heap | +| [`_realloc_dbg`](./reference/realloc-dbg.md) | Reallocate a specified block of memory on the heap by moving and/or resizing the block | +| [`_strdup_dbg`, `_wcsdup_dbg`](./reference/strdup-dbg-wcsdup-dbg.md) | Duplicates a string, using [`_malloc_dbg`](./reference/malloc-dbg.md) to allocate memory. | +| [`_tempnam_dbg`, `_wtempnam_dbg`](./reference/tempnam-dbg-wtempnam-dbg.md) | Generate names you can use to create temporary files, using [`_malloc_dbg`](./reference/malloc-dbg.md) to allocate memory. | + +## C runtime routines that aren't available in source code form + +The debugger can be used to step through the source code for most of the C runtime routines during the debugging process. However, Microsoft considers some technology to be proprietary and, therefore, doesn't provide the source code for a subset of these routines. Most of these routines belong to either the exception handling or floating-point processing groups, but a few others are included as well. The following table lists these routines. :::row::: :::column span=""::: - [`acos`](../c-runtime-library/reference/acos-acosf-acosl.md)\ - [`acosh`](../c-runtime-library/reference/acosh-acoshf-acoshl.md)\ - [`asin`](../c-runtime-library/reference/asin-asinf-asinl.md)\ - [`asinh`](../c-runtime-library/reference/asinh-asinhf-asinhl.md)\ - [`atan`, `atan2`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ - [`atanh`](../c-runtime-library/reference/atanh-atanhf-atanhl.md)\ - [`Bessel functions`](../c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)\ - [`_cabs`](../c-runtime-library/reference/cabs.md)\ - [`ceil`](../c-runtime-library/reference/ceil-ceilf-ceill.md)\ - [`_chgsign`](../c-runtime-library/reference/chgsign-chgsignf-chgsignl.md)\ - [`_clear87`, `_clearfp`](../c-runtime-library/reference/clear87-clearfp.md)\ - [`_control87`, `_controlfp`](../c-runtime-library/reference/control87-controlfp-control87-2.md) + [`acos`](./reference/acos-acosf-acosl.md)\ + [`acosh`](./reference/acosh-acoshf-acoshl.md)\ + [`asin`](./reference/asin-asinf-asinl.md)\ + [`asinh`](./reference/asinh-asinhf-asinhl.md)\ + [`atan`, `atan2`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ + [`atanh`](./reference/atanh-atanhf-atanhl.md)\ + [`Bessel functions`](./reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)\ + [`_cabs`](./reference/cabs.md)\ + [`ceil`](./reference/ceil-ceilf-ceill.md)\ + [`_chgsign`](./reference/chgsign-chgsignf-chgsignl.md)\ + [`_clear87`, `_clearfp`](./reference/clear87-clearfp.md)\ + [`_control87`, `_controlfp`](./reference/control87-controlfp-control87-2.md) :::column-end::: :::column span=""::: - [`copysign`](../c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md)\ - [`cos`](../c-runtime-library/reference/cos-cosf-cosl.md)\ - [`cosh`](../c-runtime-library/reference/cosh-coshf-coshl.md)\ - [`Exp`](../c-runtime-library/reference/exp-expf.md)\ - [`fabs`](../c-runtime-library/reference/fabs-fabsf-fabsl.md)\ - [`_finite`](../c-runtime-library/reference/finite-finitef.md)\ - [`floor`](../c-runtime-library/reference/floor-floorf-floorl.md)\ - [`fmod`](../c-runtime-library/reference/fmod-fmodf.md)\ - [`_fpclass`](../c-runtime-library/reference/fpclass-fpclassf.md)\ - [`_fpieee_flt`](../c-runtime-library/reference/fpieee-flt.md)\ - [`_fpreset`](../c-runtime-library/reference/fpreset.md)\ - [`frexp`](../c-runtime-library/reference/frexp.md) + [`copysign`](./reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md)\ + [`cos`](./reference/cos-cosf-cosl.md)\ + [`cosh`](./reference/cosh-coshf-coshl.md)\ + [`Exp`](./reference/exp-expf.md)\ + [`fabs`](./reference/fabs-fabsf-fabsl.md)\ + [`_finite`](./reference/finite-finitef.md)\ + [`floor`](./reference/floor-floorf-floorl.md)\ + [`fmod`](./reference/fmod-fmodf.md)\ + [`_fpclass`](./reference/fpclass-fpclassf.md)\ + [`_fpieee_flt`](./reference/fpieee-flt.md)\ + [`_fpreset`](./reference/fpreset.md)\ + [`frexp`](./reference/frexp.md) :::column-end::: :::column span=""::: - [`_hypot`](../c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md)\ - [`_isnan`](../c-runtime-library/reference/isnan-isnan-isnanf.md)\ - [`ldexp`](../c-runtime-library/reference/ldexp.md)\ - [`log`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ - [`_logb`](../c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md)\ - [`log10`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ - [`longjmp`](../c-runtime-library/reference/longjmp.md)\ - [`_matherr`](../c-runtime-library/reference/matherr.md)\ - [`modf`](../c-runtime-library/reference/modf-modff-modfl.md)\ - [`_nextafter`](../c-runtime-library/reference/nextafter-functions.md)\ - [`pow`](../c-runtime-library/reference/pow-powf-powl.md)\ - [`printf_s`](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) + [`_hypot`](./reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md)\ + [`_isnan`](./reference/isnan-isnan-isnanf.md)\ + [`ldexp`](./reference/ldexp.md)\ + [`log`](./reference/log-logf-log10-log10f.md)\ + [`_logb`](./reference/logb-logbf-logbl-logb-logbf.md)\ + [`log10`](./reference/log-logf-log10-log10f.md)\ + [`longjmp`](./reference/longjmp.md)\ + [`_matherr`](./reference/matherr.md)\ + [`modf`](./reference/modf-modff-modfl.md)\ + [`_nextafter`](./reference/nextafter-functions.md)\ + [`pow`](./reference/pow-powf-powl.md)\ + [`printf_s`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) :::column-end::: :::column span=""::: - [`printf`](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)\ - [`_scalb`](../c-runtime-library/reference/scalb.md)\ - [`scanf_s`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ - [`scanf`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)\ - [`setjmp`](../c-runtime-library/reference/setjmp.md)\ - [`sin`](../c-runtime-library/reference/sin-sinf-sinl.md)\ - [`sinh`](../c-runtime-library/reference/sinh-sinhf-sinhl.md)\ - [`sqrt`](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md)\ - [`_status87`, `_statusfp`](../c-runtime-library/reference/status87-statusfp-statusfp2.md)\ - [`tan`](../c-runtime-library/reference/tan-tanf-tanl.md)\ - [`tanh`](../c-runtime-library/reference/tanh-tanhf-tanhl.md) + [`printf`](./reference/printf-printf-l-wprintf-wprintf-l.md)\ + [`_scalb`](./reference/scalb.md)\ + [`scanf_s`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ + [`scanf`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ + [`setjmp`](./reference/setjmp.md)\ + [`sin`](./reference/sin-sinf-sinl.md)\ + [`sinh`](./reference/sinh-sinhf-sinhl.md)\ + [`sqrt`](./reference/sqrt-sqrtf-sqrtl.md)\ + [`_status87`, `_statusfp`](./reference/status87-statusfp-statusfp2.md)\ + [`tan`](./reference/tan-tanf-tanl.md)\ + [`tanh`](./reference/tanh-tanhf-tanhl.md) :::column-end::: :::row-end::: -Although source code is available for most of the **printf** and **scanf** routines, they make an internal call to another routine for which source code is not provided. +Although source code is available for most of the `printf` and `scanf` routines, they make an internal call to another routine for which source code isn't provided. ## Routines that behave differently in a debug build of an application -Some C run-time functions and C++ operators behave differently when called from a debug build of an application. (Note that a debug build of an application can be done by either defining the `_DEBUG` flag or by linking with a debug version of the C run-time library.) The behavioral differences usually consist of extra features or information provided by the routine to support the debugging process. The following table lists these routines. +Some C run-time functions and C++ operators behave differently when called from a debug build of an application. (You can create a debug build of an application by either defining the `_DEBUG` flag or by linking with a debug version of the C run-time library.) The behavioral differences usually consist of extra features or information provided by the routine to support the debugging process. The following table lists these routines. :::row::: :::column span=""::: - C [`abort`](../c-runtime-library/reference/abort.md) routine + C [`abort`](./reference/abort.md) routine :::column-end::: :::column span=""::: - C [`assert`](../c-runtime-library/reference/assert-macro-assert-wassert.md) routine + C [`assert`](./reference/assert-macro-assert-wassert.md) routine :::column-end::: :::column span=""::: C++ [`delete`](../cpp/delete-operator-cpp.md) operator @@ -145,5 +145,5 @@ Some C run-time functions and C++ operators behave differently when called from ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[Run-Time Error Checking](../c-runtime-library/run-time-error-checking.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[Runtime error checking](./run-time-error-checking.md) diff --git a/docs/c-runtime-library/debug-versions-of-heap-allocation-functions.md b/docs/c-runtime-library/debug-versions-of-heap-allocation-functions.md new file mode 100644 index 0000000000..0a8e8bb967 --- /dev/null +++ b/docs/c-runtime-library/debug-versions-of-heap-allocation-functions.md @@ -0,0 +1,38 @@ +--- +title: Debug versions of heap allocation functions +description: Use debug versions of heap allocation functions in the C run-time library. These functions have the same names as the release versions with _dbg appended. +ms.date: 02/03/2023 +helpviewer_keywords: + - "_CRTDBG_MAP_ALLOC macro" + - "debugging [CRT], heap allocation functions" + - "debugging memory leaks, CRT debug library functions" + - "malloc function" + - "memory leaks, CRT debug library functions" + - "heap allocation, debug" + - "_malloc_dbg function" +--- +# Debug versions of heap allocation functions + +The C runtime (CRT) library contains special Debug versions of the heap allocation functions. These functions have the same names as the Release versions with `_dbg` appended to them. This article describes the differences between the Release version of a CRT function and the `_dbg` version, using `malloc` and `_malloc_dbg` as examples. + +## Behavior in debug builds + +When [`_DEBUG`](./debug.md) is defined, the CRT maps all [`malloc`](./reference/malloc.md) calls to [`_malloc_dbg`](./reference/malloc-dbg.md). Therefore, you don't need to rewrite your code using `_malloc_dbg` instead of `malloc` to receive the benefits while debugging. + +You might want to call `_malloc_dbg` explicitly, however. Calling `_malloc_dbg` explicitly has some added benefits: + +- Tracking `_CLIENT_BLOCK` type allocations. + +- Storing the source file and line number where the allocation request occurred. + +If you don't want to convert your `malloc` calls to `_malloc_dbg`, you can obtain the source file information by defining [`_CRTDBG_MAP_ALLOC`](./crtdbg-map-alloc.md), which causes the preprocessor to directly map all calls to `malloc` to `_malloc_dbg` instead of relying on a wrapper around `malloc`. + +To track the separate types of allocations in client blocks, you must call `_malloc_dbg` directly and set the `blockType` parameter to `_CLIENT_BLOCK`. + +## Behavior in non-debug builds + +When `_DEBUG` isn't defined, calls to `malloc` aren't disturbed, calls to `_malloc_dbg` are resolved to `malloc`, the definition of [`_CRTDBG_MAP_ALLOC`](./crtdbg-map-alloc.md) is ignored, and source file information pertaining to the allocation request isn't provided. Because `malloc` doesn't have a block type parameter, requests for `_CLIENT_BLOCK` types are treated as standard allocations. + +## See also + +[CRT debugging techniques](./crt-debugging-techniques.md) diff --git a/docs/c-runtime-library/debug.md b/docs/c-runtime-library/debug.md index 2841c3d3c8..049cce0df2 100644 --- a/docs/c-runtime-library/debug.md +++ b/docs/c-runtime-library/debug.md @@ -5,12 +5,12 @@ ms.date: "11/04/2016" helpviewer_keywords: ["DEBUG macro", "_DEBUG macro"] ms.assetid: a9901568-4846-4731-a404-399d947e2e7a --- -# _DEBUG +# `_DEBUG` The compiler defines `_DEBUG` when you specify the /MTd or /MDd option. These options specify debug versions of the C run-time library. -For more information, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +For more information, see [CRT debugging techniques](./crt-debugging-techniques.md). ## See also -[Control Flags](../c-runtime-library/control-flags.md) +[Control flags](./control-flags.md) diff --git a/docs/c-runtime-library/delete-operator-crt.md b/docs/c-runtime-library/delete-operator-crt.md index 1303e9b1b3..bbafce6e44 100644 --- a/docs/c-runtime-library/delete-operator-crt.md +++ b/docs/c-runtime-library/delete-operator-crt.md @@ -9,6 +9,6 @@ f1_keywords: ["delete[]"] helpviewer_keywords: ["operator delete[]", "vector delete"] ms.assetid: e91bd0df-3815-40ca-950a-67b470518aed --- -# operator delete(CRT) +# `operator delete` (CRT) -Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator new and operator delete functions. These are now part of the C++ Standard Library. For more information, see [new and delete operators](../cpp/new-and-delete-operators.md) and [delete operator](../cpp/delete-operator-cpp.md) in the C++ Language Reference. +Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific `operator new` and `operator delete` functions. These functions are now part of the C++ Standard Library. For more information, see [`new` and `delete` operators](../cpp/new-and-delete-operators.md) and [`delete` operator](../cpp/delete-operator-cpp.md) in the C++ Language Reference. diff --git a/docs/c-runtime-library/direction-flag.md b/docs/c-runtime-library/direction-flag.md index 4c0e30c576..1acd9cfb5f 100644 --- a/docs/c-runtime-library/direction-flag.md +++ b/docs/c-runtime-library/direction-flag.md @@ -6,14 +6,14 @@ ms.topic: "conceptual" helpviewer_keywords: ["direction flag"] ms.assetid: 0836b4af-dbbb-4ab8-a4b2-156f2e2099e2 --- -# Direction Flag +# Direction flag -The direction flag is a CPU flag specific to all Intel x86-compatible CPUs. It applies to all assembly instructions that use the REP (repeat) prefix, such as MOVS, MOVSD, MOVSW, and others. Addresses provided to applicable instructions are increased if the direction flag is cleared. +The direction flag is a CPU flag specific to all Intel x86-compatible CPUs. It applies to all assembly instructions that use the `REP` (repeat) prefix, such as `MOVS`, `MOVSD`, `MOVSW`, and others. Addresses provided to applicable instructions are increased if the direction flag is cleared. -The C run-time routines assume that the direction flag is cleared. If you are using other functions with the C run-time functions, you must ensure that the other functions leave the direction flag alone or restore it to its original condition. Expecting the direction flag to be clear upon entry makes the run-time code faster and more efficient. +The C run-time routines assume that the direction flag is cleared. If you're using other functions with the C run-time functions, you must ensure that the other functions leave the direction flag alone or restore it to its original condition. Expecting the direction flag to be clear upon entry makes the run-time code faster and more efficient. The C Run-Time library functions, such as the string-manipulation and buffer-manipulation routines, expect the direction flag to be clear. ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/directory-control.md b/docs/c-runtime-library/directory-control.md index c9c32901a1..9f47f3871d 100644 --- a/docs/c-runtime-library/directory-control.md +++ b/docs/c-runtime-library/directory-control.md @@ -5,27 +5,27 @@ ms.date: "11/04/2016" helpviewer_keywords: ["controls [C++], directory", "directory control routines"] ms.assetid: a72dcf6f-f366-4d20-8850-0e19cc53ca18 --- -# Directory Control +# Directory control These routines access, modify, and obtain information about the directory structure. -## Directory-Control Routines +## Directory-control routines -|Routine|Use| -|-------------|---------| -|[_chdir, _wchdir](../c-runtime-library/reference/chdir-wchdir.md)|Change current working directory| -|[_chdrive](../c-runtime-library/reference/chdrive.md)|Change current drive| -|[_getcwd, _wgetcwd](../c-runtime-library/reference/getcwd-wgetcwd.md)|Get current working directory for default drive| -|[_getdcwd, _wgetdcwd](../c-runtime-library/reference/getdcwd-wgetdcwd.md)|Get current working directory for specified drive| -|[_getdiskfree](../c-runtime-library/reference/getdiskfree.md)|Populates a **_diskfree_t** structure with information about a disk drive.| -|[_getdrive](../c-runtime-library/reference/getdrive.md)|Get current (default) drive| -|[_getdrives](../c-runtime-library/reference/getdrives.md)|Returns a bitmask representing the currently available disk drives.| -|[_mkdir, _wmkdir](../c-runtime-library/reference/mkdir-wmkdir.md)|Make new directory| -|[_rmdir, _wrmdir](../c-runtime-library/reference/rmdir-wrmdir.md)|Remove directory| -|[_searchenv, _wsearchenv](../c-runtime-library/reference/searchenv-wsearchenv.md), [_searchenv_s, _wsearchenv_s](../c-runtime-library/reference/searchenv-s-wsearchenv-s.md)|Search for given file on specified paths| +| Routine | Use | +|---|---| +| [`_chdir`, `_wchdir`](./reference/chdir-wchdir.md) | Change current working directory | +| [`_chdrive`](./reference/chdrive.md) | Change current drive | +| [`_getcwd`, `_wgetcwd`](./reference/getcwd-wgetcwd.md) | Get current working directory for default drive | +| [`_getdcwd`, `_wgetdcwd`](./reference/getdcwd-wgetdcwd.md) | Get current working directory for specified drive | +| [`_getdiskfree`](./reference/getdiskfree.md) | Populates a `_diskfree_t` structure with information about a disk drive. | +| [`_getdrive`](./reference/getdrive.md) | Get current (default) drive | +| [`_getdrives`](./reference/getdrives.md) | Returns a bitmask representing the currently available disk drives. | +| [`_mkdir`, `_wmkdir`](./reference/mkdir-wmkdir.md) | Make new directory | +| [`_rmdir`, `_wrmdir`](./reference/rmdir-wrmdir.md) | Remove directory | +| [`_searchenv`, `_wsearchenv`](./reference/searchenv-wsearchenv.md), [`_searchenv_s`, `_wsearchenv_s`](./reference/searchenv-s-wsearchenv-s.md) | Search for given file on specified paths | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[File Handling](../c-runtime-library/file-handling.md)
-[System Calls](../c-runtime-library/system-calls.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[File handling](./file-handling.md)\ +[System calls](./system-calls.md) diff --git a/docs/c-runtime-library/dllonexit.md b/docs/c-runtime-library/dllonexit.md index fc8f8fc4a0..8cadda4ee4 100644 --- a/docs/c-runtime-library/dllonexit.md +++ b/docs/c-runtime-library/dllonexit.md @@ -10,37 +10,38 @@ f1_keywords: ["__dllonexit"] helpviewer_keywords: ["__dllonexit"] ms.assetid: 708f2ceb-f95c-46b0-a58d-d68b3fa36f12 --- -# __dllonexit +# `__dllonexit` Registers a routine to be called at exit time. ## Syntax -``` -_onexit_t __dllonexit( _onexit_t func, +```C +_onexit_t __dllonexit( + _onexit_t func, _PVFV ** pbegin, _PVFV ** pend - ) + ); ``` #### Parameters -*func*
+*`func`*\ Pointer to a function to be executed upon exit. -*pbegin*
+*`pbegin`*\ Pointer to a variable that points to the beginning of a list of functions to execute on detach. -*pend*
+*`pend`*\ Pointer to variable that points to the end of a list of functions to execute on detach. -## Return Value +## Return value -If successful, a pointer to the user’s function. Otherwise, a **NULL** pointer. +If successful, a pointer to the user's function. Otherwise, a `NULL` pointer. ## Remarks -The `__dllonexit` function is analogous to the [_onexit](../c-runtime-library/reference/onexit-onexit-m.md) function except that the global variables used by that function are not visible to this routine. Instead of global variables, this function uses the `pbegin` and `pend` parameters. +The `__dllonexit` function is analogous to the [`_onexit`](./reference/onexit-onexit-m.md) function except that the global variables used by that function aren't visible to this routine. Instead of global variables, this function uses the `pbegin` and `pend` parameters. The `_onexit` and `atexit` functions in a DLL linked with MSVCRT.LIB must maintain their own atexit/_onexit list. This routine is the worker that gets called by such DLLs. @@ -48,10 +49,10 @@ The `_PVFV` type is defined as `typedef void (__cdecl *_PVFV)(void)`. ## Requirements -|Routine|Required file| -|-------------|-------------------| -|__dllonexit|onexit.c| +| Routine | Required file | +|---|---| +| **`__dllonexit`** | `onexit.c` | ## See also -[_onexit, _onexit_m](../c-runtime-library/reference/onexit-onexit-m.md) +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md) diff --git a/docs/c-runtime-library/environ-wenviron.md b/docs/c-runtime-library/environ-wenviron.md index 6ce08781f4..8411febc71 100644 --- a/docs/c-runtime-library/environ-wenviron.md +++ b/docs/c-runtime-library/environ-wenviron.md @@ -2,20 +2,20 @@ description: "Learn more about: _environ, _wenviron" title: "_environ, _wenviron" ms.date: "11/04/2016" -f1_keywords: ["environ", "wenviron", "_wenviron", "_environ"] -helpviewer_keywords: ["environ function", "_environ function", "_wenviron function", "process environment", "wenviron function"] +f1_keywords: ["_environ", "STDLIB/_environ", "_wenviron", "STDLIB/_wenviron"] +helpviewer_keywords: ["_environ global variable", "_wenviron global variable", "process environment"] ms.assetid: 7e639962-6536-47cd-8095-0cbe44a56e03 --- -# _environ, _wenviron +# `_environ`, `_wenviron` -The `_environ` variable is a pointer to an array of pointers to the multibyte-character strings that constitute the process environment. This global variable has been deprecated for the more secure functional versions [getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md) and [_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md), which should be used in place of the global variable. `_environ` is declared in Stdlib.h. +The `_environ` variable is a pointer to an array of pointers to the multibyte-character strings that constitute the process environment. This global variable has been deprecated for the more secure functional versions [`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md) and [`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md), which should be used in place of the global variable. `_environ` is declared in Stdlib.h. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax -``` +```C extern char **_environ; ``` @@ -29,15 +29,15 @@ In a program that uses the `main` function, `_environ` is initialized at program The `_wenviron` variable, declared in Stdlib.h as: -``` +```C extern wchar_t **_wenviron; ``` is a wide-character version of `_environ`. In a program that uses the `wmain` function, `_wenviron` is initialized at program startup according to settings taken from the operating-system environment. -In a program that uses `main`, `_wenviron` is initially **NULL** because the environment is composed of multibyte-character strings. On the first call to `_wgetenv` or `_wputenv`, a corresponding wide-character string environment is created and is pointed to by `_wenviron`. +In a program that uses `main`, `_wenviron` is initially `NULL` because the environment is composed of multibyte-character strings. On the first call to `_wgetenv` or `_wputenv`, a corresponding wide-character string environment is created and is pointed to by `_wenviron`. -Similarly, in a program that uses `wmain`, `_environ` is initially **NULL** because the environment is composed of wide-character strings. On the first call to `_getenv` or `_putenv`, a corresponding multibyte-character string environment is created and is pointed to by `_environ`. +Similarly, in a program that uses `wmain`, `_environ` is initially `NULL` because the environment is composed of wide-character strings. On the first call to `_getenv` or `_putenv`, a corresponding multibyte-character string environment is created and is pointed to by `_environ`. When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, resulting in slower execution time. For example, whenever you call `_putenv`, a call to `_wputenv` is also executed automatically, so that the two environment strings correspond. @@ -46,9 +46,9 @@ When two copies of the environment (MBCS and Unicode) exist simultaneously in a Polling `_environ` in a Unicode context is meaningless when [/MD](../build/reference/md-mt-ld-use-run-time-library.md) or `/MDd` linkage is used. For the CRT DLL, the type (wide or multibyte) of the program is unknown. Only the multibyte type is created because that is the most likely scenario. -The following pseudo-code illustrates how this can happen. +The following pseudo-code illustrates how this creation can happen. -``` +```C int i, j; i = _wputenv( "env_var_x=string1" ); // results in the implicit call: // putenv ("env_var_z=string1") @@ -56,14 +56,14 @@ j = _wputenv( "env_var_y=string2" ); // also results in implicit call: // putenv("env_var_z=string2") ``` -In the notation used for this example, the character strings are not C string literals; rather, they are placeholders that represent Unicode environment string literals in the `_wputenv` call and multibyte environment strings in the `putenv` call. The character placeholders '`x`' and '`y`' in the two distinct Unicode environment strings do not map uniquely to characters in the current MBCS. Instead, both map to some MBCS character '`z`' that is the default result of the attempt to convert the strings. +In the notation used for this example, the character strings aren't C string literals; rather, they're placeholders that represent Unicode environment string literals in the `_wputenv` call and multibyte environment strings in the `putenv` call. The character placeholders '`x`' and '`y`' in the two distinct Unicode environment strings don't map uniquely to characters in the current MBCS. Instead, both map to some MBCS character '`z`' that is the default result of the attempt to convert the strings. Thus, in the multibyte environment, the value of "`env_var_z`" after the first implicit call to `putenv` would be "`string1`", but this value would be overwritten on the second implicit call to `putenv`, when the value of "`env_var_z`" is set to "`string2`". The Unicode environment (in `_wenviron`) and the multibyte environment (in `_environ`) would therefore differ following this series of calls. ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md)
-[getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)
-[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md)
-[_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md) +[Global variables](./global-variables.md)\ +[`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md)\ +[`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md)\ +[`_putenv`, `_wputenv`](./reference/putenv-wputenv.md)\ +[`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md) diff --git a/docs/c-runtime-library/environmental-constants.md b/docs/c-runtime-library/environmental-constants.md index 01f29009a0..bc19ee30a5 100644 --- a/docs/c-runtime-library/environmental-constants.md +++ b/docs/c-runtime-library/environmental-constants.md @@ -5,22 +5,22 @@ ms.date: "11/04/2016" helpviewer_keywords: ["MAX_ENV constant", "_MAX_ENV constant"] ms.assetid: 5224f540-231c-47aa-be9a-467efd1db281 --- -# Environmental Constants +# Environmental constants ## Syntax -``` +```C #include ``` ## Remarks -This constant defines the environmental length for strings. +The `_MAX_ENV` constant defines the environmental length for strings. -|Constant|Meaning| -|--------------|-------------| -|`_MAX_ENV`|Maximum string size of an environmental string.| +| Constant | Meaning | +|---|---| +| `_MAX_ENV` | Maximum string size of an environmental string. | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/eof-weof.md b/docs/c-runtime-library/eof-weof.md index 32f393a1a6..9845193f68 100644 --- a/docs/c-runtime-library/eof-weof.md +++ b/docs/c-runtime-library/eof-weof.md @@ -2,31 +2,32 @@ description: "Learn more about: EOF, WEOF" title: "EOF, WEOF" ms.date: "11/04/2016" -helpviewer_keywords: ["EOF function", "WEOF function", "end of file"] +f1_keywords: ["EOF", "STDIO/EOF", "WEOF", "CORECRT_WSTDIO/WEOF"] +helpviewer_keywords: ["EOF constant", "WEOF constant", "end of file"] ms.assetid: a7150563-cdae-4cdf-9798-ad509990e505 --- -# EOF, WEOF +# `EOF`, `WEOF` ## Syntax -``` +```C #include ``` ## Remarks -EOF is returned by an I/O routine when the end-of-file (or in some cases, an error) is encountered. +`EOF` is returned by an I/O routine when the end-of-file (or in some cases, an error) is encountered. -WEOF yields the return value, of type **wint_t**, used to signal the end of a wide stream, or to report an error condition. +`WEOF` yields the return value, of type **`wint_t`**, used to signal the end of a wide stream, or to report an error condition. ## See also -[putc, putwc](../c-runtime-library/reference/putc-putwc.md)
-[ungetc, ungetwc](../c-runtime-library/reference/ungetc-ungetwc.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)
-[fflush](../c-runtime-library/reference/fflush.md)
-[fclose, _fcloseall](../c-runtime-library/reference/fclose-fcloseall.md)
-[_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock](../c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)
-[_putch, _putwch](../c-runtime-library/reference/putch-putwch.md)
-[isascii, __isascii, iswascii](../c-runtime-library/reference/isascii-isascii-iswascii.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`putc`, `putwc`](./reference/putc-putwc.md)\ +[`ungetc`, `ungetwc`](./reference/ungetc-ungetwc.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ +[`fflush`](./reference/fflush.md)\ +[`fclose`, `_fcloseall`](./reference/fclose-fcloseall.md)\ +[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](./reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)\ +[`_putch`, `_putwch`](./reference/putch-putwch.md)\ +[`isascii`, `__isascii`, `iswascii`](./reference/isascii-isascii-iswascii.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/errno-constants.md b/docs/c-runtime-library/errno-constants.md index 71d58bb108..57db146f7b 100644 --- a/docs/c-runtime-library/errno-constants.md +++ b/docs/c-runtime-library/errno-constants.md @@ -15,31 +15,31 @@ helpviewer_keywords: ["E2BIG constant", "EACCES constant", "EAGAIN constant", "E ## Remarks -The **`errno`** constants are values assigned to [`errno`](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) in the event of various error conditions. +The `errno` constants are values assigned to [`errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) for various error conditions. -`ERRNO.H` contains the definitions of the **`errno`** values. However, not all the definitions given in `ERRNO.H` are used in 32-bit Windows operating systems. Some of the values in `ERRNO.H` are present to maintain compatibility with the UNIX family of operating systems. The **`errno`** values in a 32-bit Windows operating system are a subset of the values for **`errno`** in UNIX systems. +`ERRNO.H` contains the definitions of the `errno` values. However, not all the definitions given in `ERRNO.H` are used in 32-bit Windows operating systems. Some of the values in `ERRNO.H` are present to maintain compatibility with the UNIX family of operating systems. The `errno` values in a 32-bit Windows operating system are a subset of the values for `errno` in UNIX systems. -The **`errno`** value isn't necessarily the same as the actual error code returned by a system call from the Windows operating system. To access the actual operating system error code, use the [`_doserrno`](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) variable, which contains this value. +The `errno` value isn't necessarily the same as the actual error code returned by a system call from the Windows operating system. To access the actual operating system error code, use the [`_doserrno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) variable, which contains this value. -The following **`errno`** values are supported: +The following `errno` values are supported: | Constant | Description | Value | |--|--|--| | `E2BIG` | Argument list too long. | 7 | -| `EACCES` | Permission denied. The file's permission setting does not allow the specified access. This error signifies that an attempt was made to access a file (or, in some cases, a directory) in a way that is incompatible with the file's attributes.

For example, the error can occur when an attempt is made to read from a file that is not open, to open an existing read-only file for writing, or to open a directory instead of a file. Under MS-DOS operating system versions 3.0 and later, `EACCES` may also indicate a locking or sharing violation.

The error can also occur in an attempt to rename a file or directory or to remove an existing directory. | 13 | -| `EAGAIN` | No more processes or not enough memory or maximum nesting level reached. An attempt to create a new process failed because there are no more process slots, or there is not enough memory, or the maximum nesting level has been reached. | 11 | -| `EBADF` | Bad file number. There are two possible causes: 1) The specified file descriptor is not a valid value or does not refer to an open file. 2) An attempt was made to write to a file or device opened for read-only access. | 9 | +| `EACCES` | Permission denied. The file's permission setting doesn't allow the specified access. An attempt was made to access a file (or, in some cases, a directory) in a way that's incompatible with the file's attributes.

For example, the error can occur when an attempt is made to read from a file that isn't open. Or, on an attempt to open an existing read-only file for writing, or to open a directory instead of a file. Under MS-DOS operating system versions 3.0 and later, `EACCES` may also indicate a locking or sharing violation.

The error can also occur in an attempt to rename a file or directory or to remove an existing directory. | 13 | +| `EAGAIN` | No more processes or not enough memory or maximum nesting level reached. An attempt to create a new process failed because there are no more process slots, or there isn't enough memory, or the maximum nesting level has been reached. | 11 | +| `EBADF` | Bad file number. There are two possible causes: 1) The specified file descriptor isn't a valid value or doesn't refer to an open file. 2) An attempt was made to write to a file or device opened for read-only access. | 9 | | `EBUSY` | Device or resource busy. | 16 | | `ECHILD` | No spawned processes. | 10 | | `EDEADLK` | Resource deadlock would occur. | 36 | | `EDEADLOCK` | Same as `EDEADLK` for compatibility with older Microsoft C versions. | 36 | -| `EDOM` | Math argument. The argument to a math function is not in the domain of the function. | 33 | +| `EDOM` | Math argument. The argument to a math function isn't in the domain of the function. | 33 | | `EEXIST` | Files exists. An attempt has been made to create a file that already exists. For example, the `_O_CREAT` and `_O_EXCL` flags are specified in an `_open` call, but the named file already exists. | 17 | | `EFAULT` | Bad address. | 14 | | `EFBIG` | File too large. | 27 | | `EILSEQ` | Illegal sequence of bytes (for example, in an `MBCS` string). | 42 | | `EINTR` | Interrupted function. | 4 | -| `EINVAL` | Invalid argument. An invalid value was given for one of the arguments to a function. For example, the value given for the origin when positioning a file pointer (by means of a call to `fseek`) is before the beginning of the file. | 22 | +| `EINVAL` | Invalid argument. An invalid value was given for one of the arguments to a function. For example, the value given for the origin when positioning a file pointer (by a call to `fseek`) is before the beginning of the file. | 22 | | `EIO` | I/O error. | 5 | | `EISDIR` | Is a directory. | 21 | | `EMFILE` | Too many open files. No more file descriptors are available, so no more files can be opened. | 24 | @@ -47,10 +47,10 @@ The following **`errno`** values are supported: | `ENAMETOOLONG` | Filename too long. | 38 | | `ENFILE` | Too many files open in system. | 23 | | `ENODEV` | No such device. | 19 | -| `ENOENT` | No such file or directory. The specified file or directory does not exist or cannot be found. This message can occur whenever a specified file does not exist or a component of a path does not specify an existing directory. | 2 | -| `ENOEXEC` | Exec format error. An attempt was made to execute a file that is not executable or that has an invalid executable-file format. | 8 | +| `ENOENT` | No such file or directory. The specified file or directory doesn't exist or can't be found. This message can occur whenever a specified file doesn't exist or a component of a path doesn't specify an existing directory. | 2 | +| `ENOEXEC` | Exec format error. An attempt was made to execute a file that isn't executable or that has an invalid executable-file format. | 8 | | `ENOLCK` | No locks available. | 39 | -| `ENOMEM` | Not enough memory is available for the attempted operator. For example, this message can occur when insufficient memory is available to execute a child process, or when the allocation request in a `_getcwd` call cannot be satisfied. | 12 | +| `ENOMEM` | Not enough memory is available for the attempted operator. For example, this message can occur when insufficient memory is available to execute a child process, or when the allocation request in a `_getcwd` call can't be satisfied. | 12 | | `ENOSPC` | No space left on device. No more space for writing is available on the device (for example, when the disk is full). | 28 | | `ENOSYS` | Function not supported. | 40 | | `ENOTDIR` | Not a directory. | 20 | @@ -64,7 +64,7 @@ The following **`errno`** values are supported: | `ESPIPE` | Invalid seek. | 29 | | `ESRCH` | No such process. | 3 | | `EXDEV` | Cross-device link. An attempt was made to move a file to a different device (using the `rename` function). | 18 | -| `STRUNCATE` | A string copy or concatenation resulted in a truncated string. See [`_TRUNCATE`](../c-runtime-library/truncate.md). | 80 | +| `STRUNCATE` | A string copy or concatenation resulted in a truncated string. See [`_TRUNCATE`](./truncate.md). | 80 | The following values are supported for compatibility with POSIX: @@ -114,4 +114,4 @@ The following values are supported for compatibility with POSIX: ## See also -[Global constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md b/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md index fa0c677d3f..e614373d8c 100644 --- a/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md +++ b/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md @@ -2,11 +2,7 @@ description: "Learn more about: errno, _doserrno, _sys_errlist, and _sys_nerr" title: "errno, _doserrno, _sys_errlist, and _sys_nerr" ms.date: "11/04/2016" -api_name: ["_errno"] -api_location: ["msvcrt.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_sys_errlist", "errno", "_sys_nerr", "_doserrno"] +f1_keywords: ["errno", "ERRNO/errno", "_doserrno", "ERRNO/_doserrno", "_sys_errlist", "STDLIB/_sys_errlist", "_sys_nerr", "STDLIB/_sys_nerr"] helpviewer_keywords: ["error codes, printing", "sys_errlist global variable", "doserrno global variable", "errno global variable", "_doserrno global variable", "_sys_errlist global variable", "_sys_nerr global variable", "sys_nerr global variable"] ms.assetid: adbec641-6d91-4e19-8398-9a34046bd369 --- @@ -16,7 +12,7 @@ Global macros that hold error codes that are set during program execution, and s ## Syntax -``` +```C #define errno (*_errno()) #define _doserrno (*__doserrno()) #define _sys_errlist (__sys_errlist()) @@ -25,39 +21,39 @@ Global macros that hold error codes that are set during program execution, and s ## Remarks -Both `errno` and `_doserrno` are set to 0 by the runtime during program startup. `errno` is set on an error in a system-level call. Because `errno` holds the value for the last call that set it, this value may be changed by succeeding calls. Run-time library calls that set `errno` on an error do not clear `errno` on success. Always clear `errno` by calling `_set_errno(0)` immediately before a call that may set it, and check it immediately after the call. +Both **`errno`** and **`_doserrno`** are set to 0 by the runtime during program startup. **`errno`** is set on an error in a system-level call. Because **`errno`** holds the value for the last call that set it, this value may be changed by succeeding calls. Run-time library calls that set **`errno`** on an error don't clear **`errno`** on success. Always clear **`errno`** by calling `_set_errno(0)` immediately before a call that may set it, and check it immediately after the call. -On an error, `errno` is not necessarily set to the same value as the error code returned by a system call. For I/O operations, `_doserrno` stores the operating-system error-code equivalents of `errno` codes. For most non-I/O operations, the value of `_doserrno` is not set. +On an error, **`errno`** isn't necessarily set to the same value as the error code returned by a system call. For I/O operations, **`_doserrno`** stores the operating-system error-code equivalents of **`errno`** codes. For most non-I/O operations, the value of **`_doserrno`** isn't set. -Each `errno` value is associated with an error message in `_sys_errlist` that can be printed by using one of the [`perror`](../c-runtime-library/reference/perror-wperror.md) functions, or stored in a string by using one of the [`strerror`](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md) or [`strerror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) functions. The `perror` and `strerror` functions use the `_sys_errlist` array and `_sys_nerr`—the number of elements in `_sys_errlist`—to process error information. Direct access to `_sys_errlist` and `_sys_nerr` is deprecated for code-security reasons. We recommend that you use the more secure, functional versions instead of the global macros, as shown here: +Each **`errno`** value is associated with an error message in **`_sys_errlist`** that can be printed by using one of the [`perror`](./reference/perror-wperror.md) functions, or stored in a string by using one of the [`strerror`](./reference/strerror-strerror-wcserror-wcserror.md) or [`strerror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) functions. The `perror` and `strerror` functions use the **`_sys_errlist`** array and **`_sys_nerr`**—the number of elements in **`_sys_errlist`**—to process error information. Direct access to **`_sys_errlist`** and **`_sys_nerr`** is deprecated for code-security reasons. We recommend that you use the more secure, functional versions instead of the global macros, as shown here: -|Global Macro|Functional Equivalents| -|------------------|----------------------------| -|`_doserrno`|[`_get_doserrno`](../c-runtime-library/reference/get-doserrno.md), [`_set_doserrno`](../c-runtime-library/reference/set-doserrno.md)| -|`errno`|[`_get_errno`](../c-runtime-library/reference/get-errno.md), [`_set_errno`](../c-runtime-library/reference/set-errno.md)| -|`_sys_errlist`, `_sys_nerr`|[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)| +| Global macro | Functional equivalents | +|---|---| +| **`_doserrno`** | [`_get_doserrno`](./reference/get-doserrno.md), [`_set_doserrno`](./reference/set-doserrno.md) | +| **`errno`** | [`_get_errno`](./reference/get-errno.md), [`_set_errno`](./reference/set-errno.md) | +| **`_sys_errlist`**, **`_sys_nerr`** | [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) | -Library math routines set `errno` by calling [`_matherr`](../c-runtime-library/reference/matherr.md). To handle math errors differently, write your own routine according to the `_matherr` reference description and name it `_matherr`. +Library math routines set **`errno`** by calling [`_matherr`](./reference/matherr.md). To handle math errors differently, write your own routine according to the `_matherr` reference description and name it `_matherr`. -All `errno` values are predefined constants in ``, and are UNIX-compatible. Only `ERANGE`, `EILSEQ`, and `EDOM` are specified in the ISO C99 standard. For a complete list, see [errno Constants](../c-runtime-library/errno-constants.md). +All **`errno`** values are predefined constants in ``, and are UNIX-compatible. Only `ERANGE`, `EILSEQ`, and `EDOM` are specified in the ISO C99 standard. For a complete list, see [`errno` constants](./errno-constants.md). ## Requirements -|Global macro|Required header|Optional header| -|------------------|---------------------|---------------------| -|`errno`|`` or ``, `` or `` (C++)|| -|`_doserrno`, `_sys_errlist`, `_sys_nerr`|``, `` (C++)|``, `` (C++)| +| Global macro | Required header | Optional header | +|---|---|---| +| `errno` | `` or ``, `` or `` (C++) | | +| `_doserrno`, `_sys_errlist`, `_sys_nerr` | ``, `` (C++) | ``, `` (C++) | -The `_doserrno`, `_sys_errlist`, and `_sys_nerr` macros are Microsoft extensions. For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +The `_doserrno`, `_sys_errlist`, and `_sys_nerr` macros are Microsoft extensions. For more compatibility information, see [Compatibility](./compatibility.md). ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[`errno` Constants](../c-runtime-library/errno-constants.md)
-[`perror`, `_wperror`](../c-runtime-library/reference/perror-wperror.md)
-[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)
-[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)
-[`_get_doserrno`](../c-runtime-library/reference/get-doserrno.md)
-[`_set_doserrno`](../c-runtime-library/reference/set-doserrno.md)
-[`_get_errno`](../c-runtime-library/reference/get-errno.md)
-[`_set_errno`](../c-runtime-library/reference/set-errno.md) +[Global variables](./global-variables.md)\ +[`errno` constants](./errno-constants.md)\ +[`perror`, `_wperror`](./reference/perror-wperror.md)\ +[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](./reference/strerror-strerror-wcserror-wcserror.md)\ +[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)\ +[`_get_doserrno`](./reference/get-doserrno.md)\ +[`_set_doserrno`](./reference/set-doserrno.md)\ +[`_get_errno`](./reference/get-errno.md)\ +[`_set_errno`](./reference/set-errno.md) diff --git a/docs/c-runtime-library/error-handling-crt.md b/docs/c-runtime-library/error-handling-crt.md index e031657626..e2eca821d5 100644 --- a/docs/c-runtime-library/error-handling-crt.md +++ b/docs/c-runtime-library/error-handling-crt.md @@ -11,18 +11,18 @@ Use these routines to handle program errors. ## Error-handling routines -|Routine|Use| -|-------------|---------| -|[assert](../c-runtime-library/reference/assert-macro-assert-wassert.md) macro|Test for programming logic errors; available in both the release and debug versions of the run-time library.| -|[_ASSERT, _ASSERTE](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) macros|Similar to **assert**, but only available in the debug versions of the run-time library.| -|[clearerr](../c-runtime-library/reference/clearerr.md)|Reset error indicator. Calling **rewind** or closing a stream also resets the error indicator.| -|[_eof](../c-runtime-library/reference/eof.md)|Check for end of file in low-level I/O.| -|[feof](../c-runtime-library/reference/feof.md)|Test for end of file. End of file is also indicated when **_read** returns 0.| -|[ferror](../c-runtime-library/reference/ferror.md)|Test for stream I/O errors.| -|[_RPT, _RPTF](../c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md) macros|Generate a report similar to **printf**, but only available in the debug versions of the run-time library.| -|[_set_error_mode](../c-runtime-library/reference/set-error-mode.md)|Modifies **__error_mode** to determine a non-default location where the C run time writes an error message for an error that will possibly end the program.| -|[_set_purecall_handler](../c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md)|Sets the handler for a pure virtual function call.| +| Routine | Use | +|---|---| +| [`assert`](./reference/assert-macro-assert-wassert.md) macro | Test for programming logic errors; available in both the release and debug versions of the run-time library. | +| [`_ASSERT`, `_ASSERTE`](./reference/assert-asserte-assert-expr-macros.md) macros | Similar to `assert`, but only available in the debug versions of the run-time library. | +| [`clearerr`](./reference/clearerr.md) | Reset error indicator. Calling `rewind` or closing a stream also resets the error indicator. | +| [`_eof`](./reference/eof.md) | Check for end of file in low-level I/O. | +| [`feof`](./reference/feof.md) | Test for end of file. End of file is also indicated when `_read` returns 0. | +| [`ferror`](./reference/ferror.md) | Test for stream I/O errors. | +| [`_RPT`, `_RPTF`](./reference/rpt-rptf-rptw-rptfw-macros.md) macros | Generate a report similar to `printf`, but only available in the debug versions of the run-time library. | +| [`_set_error_mode`](./reference/set-error-mode.md) | Modifies `__error_mode` to determine a non-default location where the C run time writes an error message for an error that will possibly end the program. | +| [`_set_purecall_handler`](./reference/get-purecall-handler-set-purecall-handler.md) | Sets the handler for a pure virtual function call. | ## See also -- [Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +- [Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/except-handler3.md b/docs/c-runtime-library/except-handler3.md index 0e1ce4b6bf..c40b47cbad 100644 --- a/docs/c-runtime-library/except-handler3.md +++ b/docs/c-runtime-library/except-handler3.md @@ -3,20 +3,20 @@ description: "Learn more about: _except_handler3" title: "_except_handler3" ms.date: "1/14/2021" api_name: ["_except_handler3"] -api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_except_handler3", "except_handler3"] helpviewer_keywords: ["_except_handler3 function", "except_handler3 function"] ms.assetid: b0c64898-0ae5-48b7-9724-80135a0813e2 --- -# _except_handler3 +# `_except_handler3` Internal CRT function. Used by a framework to find the appropriate exception handler to process the current exception. ## Syntax -``` +```C int _except_handler3( PEXCEPTION_RECORD exception_record, PEXCEPTION_REGISTRATION registration, @@ -27,26 +27,26 @@ int _except_handler3( #### Parameters -*exception_record*
+*`exception_record`*\ [in] Information about the specific exception. -*registration*
+*`registration`*\ [in] The record that indicates which scope table should be used to find the exception handler. -*context*
+*`context`*\ [in] Reserved. -*dispatcher*
+*`dispatcher`*\ [in] Reserved. -## Return Value +## Return value If an exception should be dismissed, returns `DISPOSITION_DISMISS`. If the exception should be passed up a level to the encapsulating exception handlers, returns `DISPOSITION_CONTINUE_SEARCH`. ## Remarks -If this method finds an appropriate exception handler, it passes the exception to the handler. In this situation, this method does not return to the code that called it and the return value is irrelevant. +If this method finds an appropriate exception handler, it passes the exception to the handler. In this situation, this method doesn't return to the code that called it and the return value is irrelevant. ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/exception-handling-constants.md b/docs/c-runtime-library/exception-handling-constants.md index 6bdc7e4748..3ea54bfa93 100644 --- a/docs/c-runtime-library/exception-handling-constants.md +++ b/docs/c-runtime-library/exception-handling-constants.md @@ -2,14 +2,14 @@ description: "Learn more about: Exception-Handling Constants" title: "Exception-Handling Constants" ms.date: "11/04/2016" -f1_keywords: ["EXCEPTION_CONTINUE_SEARCH", "EXCEPTION_CONTINUE_EXECUTION", "EXCEPTION_EXECUTE_HANDLER"] +f1_keywords: ["EXCEPTION_CONTINUE_SEARCH", "EXCEPTION_CONTINUE_EXECUTION", "EXCEPTION_EXECUTE_HANDLER", "EXCPT/EXCEPTION_CONTINUE_SEARCH", "EXCPT/EXCEPTION_CONTINUE_EXECUTION", "EXCPT/EXCEPTION_EXECUTE_HANDLER"] helpviewer_keywords: ["exception handling, constants", "EXCEPTION_CONTINUE_SEARCH constant", "EXCEPTION_EXECUTE_HANDLER constant", "EXCEPTION_CONTINUE_EXECUTION constant", "EH constants"] ms.assetid: e1870f41-be9e-46a3-a2ea-830dfbaa18fb --- -# Exception-Handling Constants +# Exception-handling constants The constant `EXCEPTION_CONTINUE_SEARCH`, `EXCEPTION_CONTINUE_EXECUTION`, or `EXCEPTION_EXECUTE_HANDLER` is returned when an exception occurs during execution of the guarded section of a **try-except** statement. The return value determines how the exception is handled. For more information, see [try-except Statement](../cpp/try-except-statement.md) in the *C++ Language Reference*. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/exception-handling-routines.md b/docs/c-runtime-library/exception-handling-routines.md index 1de3f22da4..c9755f8bf9 100644 --- a/docs/c-runtime-library/exception-handling-routines.md +++ b/docs/c-runtime-library/exception-handling-routines.md @@ -6,20 +6,20 @@ f1_keywords: ["c.exceptions"] helpviewer_keywords: ["exception handling, routines"] ms.assetid: f60548c6-850a-4e1e-a79b-a2a6a541ab62 --- -# Exception Handling Routines +# Exception handling routines Use the C++ exception-handling functions to recover from unexpected events during program execution. -## Exception-Handling Functions +## Exception-handling functions -|Function|Use| -|--------------|---------| -|[_set_se_translator](../c-runtime-library/reference/set-se-translator.md)|Handle Win32 exceptions (C structured exceptions) as C++ typed exceptions| -|[set_terminate](../c-runtime-library/reference/set-terminate-crt.md)|Install your own termination routine to be called by **terminate**| -|[set_unexpected](../c-runtime-library/reference/set-unexpected-crt.md)|Install your own termination function to be called by **unexpected**| -|[terminate](../c-runtime-library/reference/terminate-crt.md)|Called automatically under certain circumstances after exception is thrown. The **terminate** function calls **abort** or a function you specify using **set_terminate**| -|[unexpected](../c-runtime-library/reference/unexpected-crt.md)|Calls **terminate** or a function you specify using **set_unexpected**. The **unexpected** function is not used in current Microsoft C++ exception-handling implementation| +| Function | Use | +|---|---| +| [`_set_se_translator`](./reference/set-se-translator.md) | Handle Win32 exceptions (C structured exceptions) as C++ typed exceptions | +| [`set_terminate`](./reference/set-terminate-crt.md) | Install your own termination routine to be called by `terminate` | +| [`set_unexpected`](./reference/set-unexpected-crt.md) | Install your own termination function to be called by `unexpected` | +| [`terminate`](./reference/terminate-crt.md) | Called automatically under certain circumstances after exception is thrown. The `terminate` function calls `abort` or a function you specify using `set_terminate` | +| [`unexpected`](./reference/unexpected-crt.md) | Calls `terminate` or a function you specify using `set_unexpected`. The `unexpected` function isn't used in current Microsoft C++ exception-handling implementation | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/exec-wexec-functions.md b/docs/c-runtime-library/exec-wexec-functions.md index 616720a787..9b9921f56f 100644 --- a/docs/c-runtime-library/exec-wexec-functions.md +++ b/docs/c-runtime-library/exec-wexec-functions.md @@ -7,78 +7,77 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_texecve", "texecl", "_texeclpe", "texecve", "texecv", "texeclp", "texecle", "exec", "texeclpe", "_texecvp", "_texecl", "_texecle", "wexec", "_exec", "_texeclp", "_texecvpe", "texecvpe", "_texecv", "_wexec"] helpviewer_keywords: ["_texecle function", "_texecv function", "texeclpe function", "texecle function", "_texecl function", "texecv function", "_texeclp function", "_texecve function", "texecl function", "texecve function", "exec function", "texeclp function", "texecvp function", "texecvpe function", "processes, executing new", "_texecvp function", "_texeclpe function", "_wexec functions", "wexec functions", "_exec function", "_texecvpe function"] -ms.assetid: a261df93-206a-4fdc-b8ac-66aa7db83bc6 --- -# _exec, _wexec Functions +# `_exec`, `_wexec` Functions Each function in this family loads and executes a new process: :::row::: :::column span=""::: - [_execl, _wexecl](../c-runtime-library/reference/execl-wexecl.md)\ - [_execv, _wexecv](../c-runtime-library/reference/execv-wexecv.md)\ - [_execle, _wexecle](../c-runtime-library/reference/execle-wexecle.md) + [`_execl`, `_wexecl`](./reference/execl-wexecl.md)\ + [`_execv`, `_wexecv`](./reference/execv-wexecv.md)\ + [`_execle`, `_wexecle`](./reference/execle-wexecle.md) :::column-end::: :::column span=""::: - [_execve, _wexecve](../c-runtime-library/reference/execve-wexecve.md)\ - [_execlp, _wexeclp](../c-runtime-library/reference/execlp-wexeclp.md)\ - [_execvp, _wexecvp](../c-runtime-library/reference/execvp-wexecvp.md) + [`_execve`, `_wexecve`](./reference/execve-wexecve.md)\ + [`_execlp`, `_wexeclp`](./reference/execlp-wexeclp.md)\ + [`_execvp`, `_wexecvp`](./reference/execvp-wexecvp.md) :::column-end::: :::column span=""::: - [_execlpe, _wexeclpe](../c-runtime-library/reference/execlpe-wexeclpe.md)\ - [_execvpe, _wexecvpe](../c-runtime-library/reference/execvpe-wexecvpe.md) + [`_execlpe`, `_wexeclpe`](./reference/execlpe-wexeclpe.md)\ + [`_execvpe`, `_wexecvpe`](./reference/execvpe-wexecvpe.md) :::column-end::: :::row-end::: The letter at the end of the function name determines the variation. -|_exec function suffix|Description| -|----------------------------|-----------------| -|`e`|`envp`, array of pointers to environment settings, is passed to the new process.| -|`l`|Command-line arguments are passed individually to `_exec` function. Typically used when the number of parameters to the new process is known in advance.| -|`p`|`PATH` environment variable is used to find the file to execute.| -|`v`|`argv`, array of pointers to command-line arguments, is passed to `_exec`. Typically used when the number of parameters to the new process is variable.| +| `_exec` function suffix | Description | +|---|---| +| `e` | `envp`, array of pointers to environment settings, is passed to the new process. | +| `l` | Command-line arguments are passed individually to `_exec` function. Typically used when the number of parameters to the new process is known in advance. | +| `p` | `PATH` environment variable is used to find the file to execute. | +| `v` | `argv`, array of pointers to command-line arguments, is passed to `_exec`. Typically used when the number of parameters to the new process is variable. | ## Remarks -Each `_exec` function loads and executes a new process. All `_exec` functions use the same operating-system function ([CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw)). The `_exec` functions automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wexec` functions are wide-character versions of the `_exec` functions. The `_wexec` functions behave identically to their `_exec` family counterparts except that they do not handle multibyte-character strings. +Each `_exec` function loads and executes a new process. All `_exec` functions use the same operating-system function ([`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw)). The `_exec` functions automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wexec` functions are wide-character versions of the `_exec` functions. The `_wexec` functions behave identically to their `_exec` family counterparts except that they don't handle multibyte-character strings. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_texecl`|`_execl`|`_execl`|`_wexecl`| -|`_texecle`|`_execle`|`_execle`|`_wexecle`| -|`_texeclp`|`_execlp`|`_execlp`|`_wexeclp`| -|`_texeclpe`|`_execlpe`|`_execlpe`|`_wexeclpe`| -|`_texecv`|`_execv`|`_execv`|`_wexecv`| -|`_texecve`|`_execve`|`_execve`|`_wexecve`| -|`_texecvp`|`_execvp`|`_execvp`|`_wexecvp`| -|`_texecvpe`|`_execvpe`|`_execvpe`|`_wexecvpe`| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_texecl` | **`_execl`** | **`_execl`** | **`_wexecl`** | +| `_texecle` | **`_execle`** | **`_execle`** | **`_wexecle`** | +| `_texeclp` | **`_execlp`** | **`_execlp`** | **`_wexeclp`** | +| `_texeclpe` | **`_execlpe`** | **`_execlpe`** | **`_wexeclpe`** | +| `_texecv` | **`_execv`** | **`_execv`** | **`_wexecv`** | +| `_texecve` | **`_execve`** | **`_execve`** | **`_wexecve`** | +| `_texecvp` | **`_execvp`** | **`_execvp`** | **`_wexecvp`** | +| `_texecvpe` | **`_execvpe`** | **`_execvpe`** | **`_wexecvpe`** | -The `cmdname` parameter specifies the file to be executed as the new process. It can specify a full path (from the root), a partial path (from the current working directory), or a file name. If `cmdname` does not have a file name extension or does not end with a period (.), the `_exec` function searches for the named file. If the search is unsuccessful, it tries the same base name with the .com file name extension and then with the .exe, .bat, and .cmd file name extensions. If `cmdname` has a file name extension, only that extension is used in the search. If `cmdname` ends with a period, the `_exec` function searches for `cmdname` with no file name extension. `_execlp`, `_execlpe`, `_execvp`, and `_execvpe` search for `cmdname` (using the same procedures) in the directories specified by the `PATH` environment variable. If `cmdname` contains a drive specifier or any slashes (that is, if it is a relative path), the `_exec` call searches only for the specified file; the path is not searched. +The `cmdname` parameter specifies the file to be executed as the new process. It can specify a full path (from the root), a partial path (from the current working directory), or a file name. If `cmdname` doesn't have a file name extension or doesn't end with a period (.), the `_exec` function searches for the named file. If the search is unsuccessful, it tries the same base name with the .com file name extension and then with the .exe, .bat, and .cmd file name extensions. If `cmdname` has a file name extension, only that extension is used in the search. If `cmdname` ends with a period, the `_exec` function searches for `cmdname` with no file name extension. **`_execlp`**, **`_execlpe`**, **`_execvp`**, and **`_execvpe`** search for `cmdname` (using the same procedures) in the directories specified by the `PATH` environment variable. If `cmdname` contains a drive specifier or any slashes (that is, if it's a relative path), the `_exec` call searches only for the specified file; the path isn't searched. -Parameters are passed to the new process by giving one or more pointers to character strings as parameters in the `_exec` call. These character strings form the parameter list for the new process. The combined length of the inherited environment settings and the strings forming the parameter list for the new process must not exceed 32 kilobytes. The terminating null character ('\0') for each string is not included in the count, but space characters (inserted automatically to separate the parameters) are counted. +Parameters are passed to the new process by giving one or more pointers to character strings as parameters in the `_exec` call. These character strings form the parameter list for the new process. The combined length of the inherited environment settings and the strings forming the parameter list for the new process must not exceed 32 kilobytes. The terminating `NULL` character (`\0`) for each string isn't included in the count, but space characters (inserted automatically to separate the parameters) are counted. > [!NOTE] > Spaces embedded in strings may cause unexpected behavior; for example, passing `_exec` the string `"hi there"` will result in the new process getting two arguments, `"hi"` and `"there"`. If the intent was to have the new process open a file named "hi there", the process would fail. You can avoid this by quoting the string: `"\"hi there\""`. > [!IMPORTANT] -> Do not pass user input to `_exec` without explicitly checking its content. `_exec` will result in a call to [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) so keep in mind that unqualified path names could lead to potential security vulnerabilities. +> Do not pass user input to `_exec` without explicitly checking its content. `_exec` will result in a call to [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) so keep in mind that unqualified path names could lead to potential security vulnerabilities. -The `_exec` functions validate their parameters. If expected parameters are null pointers, empty strings, or omitted, the `_exec` functions invoke the invalid parameter handler as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. +The `_exec` functions validate their parameters. If expected parameters are null pointers, empty strings, or omitted, the `_exec` functions invoke the invalid parameter handler as described in [Parameter validation](./parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. -The argument pointers can be passed as separate parameters (in `_execl`, `_execle`, `_execlp`, and `_execlpe`) or as an array of pointers (in `_execv`, `_execve`, `_execvp`, and `_execvpe`). At least one parameter, `arg0`, must be passed to the new process; this parameter is `argv`[0] of the new process. Usually, this parameter is a copy of `cmdname`. (A different value does not produce an error.) +The argument pointers can be passed as separate parameters (in **`_execl`**, **`_execle`**, **`_execlp`**, and **`_execlpe`**) or as an array of pointers (in **`_execv`**, **`_execve`**, **`_execvp`**, and **`_execvpe`**). At least one parameter, `arg0`, must be passed to the new process; this parameter is `argv[0]` of the new process. Usually, this parameter is a copy of `cmdname`. (A different value doesn't produce an error.) -The `_execl`, `_execle`, `_execlp`, and `_execlpe` calls are typically used when the number of parameters is known in advance. The parameter `arg0` is usually a pointer to `cmdname`. The parameters `arg1` through `argn` point to the character strings forming the new parameter list. A null pointer must follow `argn` to mark the end of the parameter list. +The **`_execl`**, **`_execle`**, **`_execlp`**, and **`_execlpe`** calls are typically used when the number of parameters is known in advance. The parameter `arg0` is usually a pointer to `cmdname`. The parameters `arg1` through `argn` point to the character strings forming the new parameter list. A null pointer must follow `argn` to mark the end of the parameter list. -The `_execv`, `_execve`, `_execvp`, and `_execvpe` calls are useful when the number of parameters to the new process is variable. Pointers to the parameters are passed as an array, `argv`. The parameter `argv`[0] is usually a pointer to `cmdname`. The parameters `argv`[1] through `argv`[`n`] point to the character strings forming the new parameter list. The parameter `argv`[`n`+1] must be a **NULL** pointer to mark the end of the parameter list. +The **`_execv`**, **`_execve`**, **`_execvp`**, and **`_execvpe`** calls are useful when the number of parameters to the new process is variable. Pointers to the parameters are passed as an array, `argv`. The parameter `argv[0]` is usually a pointer to `cmdname`. The parameters `argv[1]` through `argv[n]` point to the character strings forming the new parameter list. The parameter `argv[n+1]` must be a `NULL` pointer to mark the end of the parameter list. -Files that are open when an `_exec` call is made remain open in the new process. In `_execl`, `_execlp`, `_execv`, and `_execvp` calls, the new process inherits the environment of the calling process. `_execle`, `_execlpe`, `_execve`, and `_execvpe` calls alter the environment for the new process by passing a list of environment settings through the `envp` parameter. `envp` is an array of character pointers, each element of which (except for the final element) points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME`=`value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (Note that `value` is not enclosed in double quotation marks.) The final element of the `envp` array should be **NULL**. When `envp` itself is **NULL**, the new process inherits the environment settings of the calling process. +Files that are open when an `_exec` call is made remain open in the new process. In **`_execl`**, **`_execlp`**, **`_execv`**, and **`_execvp`** calls, the new process inherits the environment of the calling process. **`_execle`**, **`_execlpe`**, **`_execve`**, and **`_execvpe`** calls alter the environment for the new process by passing a list of environment settings through the `envp` parameter. `envp` is an array of character pointers, each element of which (except for the final element) points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME=value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (The `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be `NULL`. When `envp` itself is `NULL`, the new process inherits the environment settings of the calling process. -A program executed with one of the `_exec` functions is always loaded into memory as if the maximum allocation field in the program's .exe file header were set to the default value of 0xFFFFH. +A program executed with one of the `_exec` functions is always loaded into memory as if the maximum allocation field in the program's .exe file header were set to the default value of `0xFFFFH`. -The `_exec` calls do not preserve the translation modes of open files. If the new process must use files inherited from the calling process, use the [_setmode](../c-runtime-library/reference/setmode.md) routine to set the translation mode of these files to the desired mode. You must explicitly flush (using `fflush` or `_flushall`) or close any stream before the `_exec` function call. Signal settings are not preserved in new processes that are created by calls to `_exec` routines. The signal settings are reset to the default in the new process. +The `_exec` calls don't preserve the translation modes of open files. If the new process must use files inherited from the calling process, use the [`_setmode`](./reference/setmode.md) routine to set the translation mode of these files to the desired mode. You must explicitly flush (using `fflush` or `_flushall`) or close any stream before the `_exec` function call. Signal settings aren't preserved in new processes that are created by calls to `_exec` routines. The signal settings are reset to the default in the new process. ## Example @@ -190,14 +189,14 @@ int main( int ac, char* av[] ) ## Requirements -**Header:** process.h +**Header:** `process.h` ## See also -[Process and Environment Control](../c-runtime-library/process-and-environment-control.md)
-[abort](../c-runtime-library/reference/abort.md)
-[atexit](../c-runtime-library/reference/atexit.md)
-[exit, _Exit, _exit](../c-runtime-library/reference/exit-exit-exit.md)
-[_onexit, _onexit_m](../c-runtime-library/reference/onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](../c-runtime-library/reference/system-wsystem.md) +[Process and environment control](./process-and-environment-control.md)\ +[`abort`](./reference/abort.md)\ +[`atexit`](./reference/atexit.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](./spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](./reference/system-wsystem.md) diff --git a/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md b/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md index c142484008..d03b81c389 100644 --- a/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md +++ b/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md @@ -3,20 +3,20 @@ description: "Learn more about: _execute_onexit_table, _initialize_onexit_table, title: "_execute_onexit_table, _initialize_onexit_table, _register_onexit_function" ms.date: "4/2/2020" api_name: ["_execute_onexit_table", "_initialize_onexit_table", "_register_onexit_function", "_o__execute_onexit_table", "_o__initialize_onexit_table", "_o__register_onexit_function"] -api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execute_onexit_table", "process/_execute_onexit_table", "_initialize_onexit_table", "process/_initialize_onexit_table", "_register_onexit_function", "process/_register_onexit_function"] helpviewer_keywords: ["_execute_onexit_table function", "_initialize_onexit_table function", "_register_onexit_function function"] ms.assetid: ad9e4149-d4ad-4fdf-aaaf-cf786fcb4473 --- -# _execute_onexit_table, _initialize_onexit_table, _register_onexit_function +# `_execute_onexit_table`, `_initialize_onexit_table`, `_register_onexit_function` Manages the routines to be called at exit time. ## Syntax -``` +```C int _initialize_onexit_table( _onexit_table_t* table ); @@ -33,38 +33,38 @@ int _execute_onexit_table( #### Parameters -*table*
-[in, out] Pointer to the onexit function table. +*`table`*\ +[in, out] Pointer to the `onexit` function table. -*function*
-[in] Pointer to a function to add to the onexit function table. +*`function`*\ +[in] Pointer to a function to add to the `onexit` function table. -## Return Value +## Return value -If successful, returns 0. Otherwise, returns a negative value. +If successful, the function returns 0. Otherwise, it returns a negative value. ## Remarks -These functions are infrastructure implementation details used to support the C runtime, and should not be called directly from your code. The C runtime uses an *onexit function table* to represent the sequence of functions registered by calls to `atexit`, `at_quick_exit`, and `_onexit`. The onexit function table data structure is an opaque implementation detail of the C runtime; the order and meaning of its data members may change. They should not be inspected by external code. +These functions are infrastructure implementation details used to support the C runtime, and shouldn't be called directly from your code. The C runtime uses an `onexit` function table to represent the sequence of functions registered by calls to `atexit`, `at_quick_exit`, and `_onexit`. The `onexit` function table data structure is an opaque implementation detail of the C runtime; the order and meaning of its data members may change. They shouldn't be inspected by external code. -The `_initialize_onexit_table` function initializes the onexit function table to its initial value. This function must be called before the onexit function table is passed to either `_register_onexit_function` or `_execute_onexit_table`. +The **`_initialize_onexit_table`** function initializes the `onexit` function table to its initial value. This function must be called before the `onexit` function table is passed to either **`_register_onexit_function`** or **`_execute_onexit_table`**. -The `_register_onexit_function` function appends a function to the end of the onexit function table. +The **`_register_onexit_function`** function appends a function to the end of the `onexit` function table. -The `_execute_onexit_table` function executes all of the functions in the onexit function table, clears the table, and then returns. After a call to `_execute_onexit_table`, the table is in a non-valid state; it must be reinitialized by a call to `_initialize_onexit_table` before it is used again. +The **`_execute_onexit_table`** function executes all of the functions in the `onexit` function table, clears the table, and then returns. After a call to **`_execute_onexit_table`**, the table is in a non-valid state; it must be reinitialized by a call to **`_initialize_onexit_table`** before it's used again. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_initialize_onexit_table function`, `_register_onexit_function`, `_execute_onexit_table`|C, C++: \| +| Routine | Required header | +|---|---| +| **`_initialize_onexit_table`**, **`_register_onexit_function`**, **`_execute_onexit_table`** | C, C++: \ | -The `_initialize_onexit_table`, `_register_onexit_function`, and `_execute_onexit_table` functions are Microsoft-specific. For compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +The **`_initialize_onexit_table`**, **`_register_onexit_function`**, and **`_execute_onexit_table`** functions are Microsoft-specific. For compatibility information, see [Compatibility](./compatibility.md). ## See also -[atexit](../c-runtime-library/reference/atexit.md)
-[exit, _Exit, _exit](../c-runtime-library/reference/exit-exit-exit.md)
-[_onexit, _onexit_m](../c-runtime-library/reference/onexit-onexit-m.md) +[`atexit`](./reference/atexit.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md) diff --git a/docs/c-runtime-library/exit-success-exit-failure.md b/docs/c-runtime-library/exit-success-exit-failure.md index 685d85a80c..ddedc9aa4c 100644 --- a/docs/c-runtime-library/exit-success-exit-failure.md +++ b/docs/c-runtime-library/exit-success-exit-failure.md @@ -2,11 +2,10 @@ description: "Learn more about: EXIT_SUCCESS, EXIT_FAILURE" title: "EXIT_SUCCESS, EXIT_FAILURE" ms.date: "06/25/2018" -f1_keywords: ["EXIT_FAILURE", "EXIT_SUCCESS"] +f1_keywords: ["EXIT_FAILURE", "EXIT_SUCCESS", "STDLIB/EXIT_FAILURE", "STDLIB/EXIT_SUCCESS"] helpviewer_keywords: ["EXIT_SUCCESS constant", "EXIT_FAILURE constant"] -ms.assetid: ff2c82cb-c0bb-4556-a812-59aa278bfac5 --- -# EXIT_SUCCESS, EXIT_FAILURE +# `EXIT_SUCCESS`, `EXIT_FAILURE` ## Required header @@ -16,13 +15,13 @@ ms.assetid: ff2c82cb-c0bb-4556-a812-59aa278bfac5 ## Remarks -These are arguments for the [exit](reference/exit-exit-exit.md) and [_exit](reference/exit-exit-exit.md) functions, and the return values for the [atexit](reference/atexit.md) and [_onexit](reference/onexit-onexit-m.md) functions. +The **`EXIT_SUCCESS`** and `EXIT_FAILURE` constants are arguments for the [`exit`](reference/exit-exit-exit.md) and [`_exit`](reference/exit-exit-exit.md) functions, and the return values for the [`atexit`](reference/atexit.md) and [`_onexit`](reference/onexit-onexit-m.md) functions. -|Constant|Defined value| -|-|-| -|EXIT_SUCCESS|0| -|EXIT_FAILURE|1| +| Constant | Defined value | +|---|---| +| **`EXIT_SUCCESS`** | 0 | +| **`EXIT_FAILURE`** | 1 | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-attribute-constants.md b/docs/c-runtime-library/file-attribute-constants.md index 1d69f0283c..a7d89dbfd8 100644 --- a/docs/c-runtime-library/file-attribute-constants.md +++ b/docs/c-runtime-library/file-attribute-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: File Attribute Constants" title: "File Attribute Constants" ms.date: "11/04/2016" -f1_keywords: ["A_HIDDEN", "_A_NORMAL", "_A_SUBDIR", "_A_RDONLY", "A_NORMAL", "A_SUBDIR", "_A_SYSTEM", "c.constants.file", "_A_HIDDEN", "A_RDONLY", "_A_ARCH", "A_ARCH"] +f1_keywords: ["_A_ARCH", "_A_HIDDEN", "_A_NORMAL", "_A_RDONLY", "_A_SUBDIR", "_A_SYSTEM", "CORECRT_IO/_A_ARCH", "CORECRT_IO/_A_HIDDEN", "CORECRT_IO/_A_NORMAL", "CORECRT_IO/_A_RDONLY", "CORECRT_IO/_A_SUBDIR", "CORECRT_IO/_A_SYSTEM", "c.constants.file"] helpviewer_keywords: ["constants [C++], file attributes", "file attribute constants [C++]", "_A_SYSTEM constant", "files [C++], file attribute constants", "_A_SUBDIR constant", "_A_ARCH constant", "_A_NORMAL constant", "_A_HIDDEN constant", "_A_RDONLY constant"] ms.assetid: 8dc8ccb9-99f5-446b-876c-7ebecc2f764f --- -# File Attribute Constants +# File attribute constants ## Syntax -``` +```C #include ``` @@ -20,18 +20,18 @@ These constants specify the current attributes of the file or directory specifie The attributes are represented by the following manifest constants: -|Constant|Description| -|-|-| -|`_A_ARCH`| Archive. Set whenever the file is changed, and cleared by the BACKUP command. Value: 0x20| -|`_A_HIDDEN`| Hidden file. Not normally seen with the DIR command, unless the /AH option is used. Returns information about normal files as well as files with this attribute. Value: 0x02| -|`_A_NORMAL`| Normal. File can be read or written to without restriction. Value: 0x00| -|`_A_RDONLY`| Read-only. File cannot be opened for writing, and a file with the same name cannot be created. Value: 0x01| -|`_A_SUBDIR`| Subdirectory. Value: 0x10| -|`_A_SYSTEM`| System file. Not normally seen with the DIR command, unless the /AS option is used. Value: 0x04| +| Constant | Description | +|---|---| +| `_A_ARCH` | Archive. Set whenever the file is changed, and cleared by the BACKUP command. Value: 0x20 | +| `_A_HIDDEN` | Hidden file. Not normally seen with the DIR command, unless the /AH option is used. Returns information about both normal files and files with this attribute. Value: 0x02 | +| `_A_NORMAL` | Normal. File can be read or written to without restriction. Value: 0x00 | +| `_A_RDONLY` | Read-only. File can't be opened for writing, and a file with the same name can't be created. Value: 0x01 | +| `_A_SUBDIR` | Subdirectory. Value: 0x10 | +| `_A_SYSTEM` | System file. Not normally seen with the DIR command, unless the /AS option is used. Value: 0x04 | -Multiple constants can be combined with the OR operator (|). +Multiple constants can be combined with the OR operator (`|`). ## See also -[Filename Search Functions](../c-runtime-library/filename-search-functions.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Filename search functions](./filename-search-functions.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-constants.md b/docs/c-runtime-library/file-constants.md index 0e8b4eca68..2d129f4ee1 100644 --- a/docs/c-runtime-library/file-constants.md +++ b/docs/c-runtime-library/file-constants.md @@ -2,36 +2,36 @@ description: "Learn more about: File Constants" title: "File Constants" ms.date: "11/04/2016" -f1_keywords: ["_O_EXCL", "_O_RDWR", "_O_APPEND", "_O_RDONLY", "_O_TRUNC", "_O_CREAT", "_O_WRONLY"] +f1_keywords: ["_O_APPEND", "_O_CREAT", "_O_EXCL", "_O_RDONLY", "_O_RDWR", "_O_TRUNC", "_O_WRONLY", "FCNTL/_O_APPEND", "FCNTL/_O_CREAT", "FCNTL/_O_EXCL", "FCNTL/_O_RDONLY", "FCNTL/_O_RDWR", "FCNTL/_O_TRUNC", "FCNTL/_O_WRONLY"] helpviewer_keywords: ["_O_RDWR constant", "O_EXCL constant", "O_RDWR constant", "O_WRONLY constant", "O_APPEND constant", "O_CREAT constant", "_O_CREAT constant", "_O_APPEND constant", "_O_EXCL constant", "O_TRUNC constant", "_O_RDONLY constant", "_O_TRUNC constant", "O_RDONLY constant", "_O_WRONLY constant"] ms.assetid: c8fa5548-9ac2-4217-801d-eb45e86f2fa4 --- -# File Constants +# File constants ## Syntax -``` +```C #include ``` ## Remarks -The integer expression formed from one or more of these constants determines the type of reading or writing operations permitted. It is formed by combining one or more constants with a translation-mode constant. +The integer expression formed from one or more of these constants determines the type of reading or writing operations permitted. It's formed by combining one or more constants with a translation-mode constant. The file constants are as follows: -|Constant|Description| -|-|-| -| `_O_APPEND` | Repositions the file pointer to the end of the file before every write operation. | -| `_O_CREAT` | Creates and opens a new file for writing; this has no effect if the file specified by *filename* exists. | -| `_O_EXCL` | Returns an error value if the file specified by *filename* exists. Only applies when used with `_O_CREAT`. | -| `_O_RDONLY` | Opens file for reading only; if this flag is given, neither `_O_RDWR` nor `_O_WRONLY` can be given. | -| `_O_RDWR` | Opens file for both reading and writing; if this flag is given, neither `_O_RDONLY` nor `_O_WRONLY` can be given. | -| `_O_TRUNC` | Opens and truncates an existing file to zero length; the file must have write permission. The contents of the file are destroyed. If this flag is given, you cannot specify `_O_RDONLY`. | -| `_O_WRONLY` | Opens file for writing only; if this flag is given, neither `_O_RDONLY` nor `_O_RDWR` can be given. | +| Constant | Description | +|---|---| +| `_O_APPEND` | Repositions the file pointer to the end of the file before every write operation. | +| `_O_CREAT` | Creates and opens a new file for writing; the constant has no effect if the file specified by *`filename`* exists. | +| `_O_EXCL` | Returns an error value if the file specified by *`filename`* exists. Only applies when used with `_O_CREAT`. | +| `_O_RDONLY` | Opens file for reading only; if this flag is given, `_O_RDWR` and `_O_WRONLY` can't be given. | +| `_O_RDWR` | Opens file for both reading and writing; if this flag is given, `_O_RDONLY` and `_O_WRONLY` can't be given. | +| `_O_TRUNC` | Opens and truncates an existing file to zero length; the file must have write permission. The contents of the file are destroyed. If this flag is given, you can't specify `_O_RDONLY`. | +| `_O_WRONLY` | Opens file for writing only; if this flag is given, `_O_RDONLY` and `_O_RDWR` can't be given. | ## See also -[_open, _wopen](../c-runtime-library/reference/open-wopen.md)
-[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_open`, `_wopen`](./reference/open-wopen.md)\ +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-handling.md b/docs/c-runtime-library/file-handling.md index 5da950aeef..661f7a0fb3 100644 --- a/docs/c-runtime-library/file-handling.md +++ b/docs/c-runtime-library/file-handling.md @@ -1,82 +1,79 @@ --- -description: "Learn more about: File Handling" title: "File Handling" -ms.date: "11/04/2016" +description: "Learn more about: File Handling" +ms.date: 11/04/2016 f1_keywords: ["c.files"] helpviewer_keywords: ["files [C++], handling", "files [C++], opening", "files [C++], manipulating"] -ms.assetid: 48119e2e-e94f-4602-b08b-b72440f731d8 --- -# File Handling +# File handling Use these routines to create, delete, and manipulate files and to set and check file-access permissions. -The C run-time libraries have a 512 limit for the number of files that can be open at any one time. Attempting to open more than the maximum number of file descriptors or file streams causes program failure. Use [`_setmaxstdio`](../c-runtime-library/reference/setmaxstdio.md) to change this number. +The C run-time libraries have a 512 limit for the number of files that can be open at any one time. Attempting to open more than the maximum number of file descriptors or file streams causes program failure. Use [`_setmaxstdio`](reference/setmaxstdio.md) to change this number. -## File-Handling Routines (File Descriptor) +## File-handling routines (file descriptor) These routines operate on files designated by a file descriptor. -|Routine|Use| -|-------------|---------| -|[`_chsize`](../c-runtime-library/reference/chsize.md),[`_chsize_s`](../c-runtime-library/reference/chsize-s.md)|Change file size| -|[`_filelength`, `_filelengthi64`](../c-runtime-library/reference/filelength-filelengthi64.md)|Get file length| -|[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)|Get file-status information on descriptor| -|[`_get_osfhandle`](../c-runtime-library/reference/get-osfhandle.md)|Return operating-system file handle associated with existing C run-time file descriptor| -|[`_isatty`](../c-runtime-library/reference/isatty.md)|Check for character device| -|[`_locking`](../c-runtime-library/reference/locking.md)|Lock areas of file| -|[`_open_osfhandle`](../c-runtime-library/reference/open-osfhandle.md)|Associate C run-time file descriptor with existing operating-system file handle| -|[`_setmode`](../c-runtime-library/reference/setmode.md)|Set file-translation mode| +| Routine | Use | +|---|---| +| [`_chsize`](reference/chsize.md), [`_chsize_s`](reference/chsize-s.md) | Change file size | +| [`_filelength`, `_filelengthi64`](reference/filelength-filelengthi64.md) | Get file length | +| [`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md) | Get file-status information on descriptor | +| [`_get_osfhandle`](reference/get-osfhandle.md) | Return operating-system file handle associated with existing C run-time file descriptor | +| [`_isatty`](reference/isatty.md) | Check for character device | +| [`_locking`](reference/locking.md) | Lock areas of file | +| [`_open_osfhandle`](reference/open-osfhandle.md) | Associate C run-time file descriptor with existing operating-system file handle | +| [`_setmode`](reference/setmode.md) | Set file-translation mode | ## File-Handling Routines (Path or Filename) These routines operate on files specified by a path or filename. -|Routine|Use| -|-------------|---------| -|[`_access`, `_waccess`](../c-runtime-library/reference/access-waccess.md), [`_access_s`, `_waccess_s`](../c-runtime-library/reference/access-s-waccess-s.md)|Check file-permission setting| -|[`_chmod`, `_wchmod`](../c-runtime-library/reference/chmod-wchmod.md)|Change file-permission setting| -|[`_fullpath`, `_wfullpath`](../c-runtime-library/reference/fullpath-wfullpath.md)|Expand a relative path to its absolute path name| -|[`_makepath`, `_wmakepath`](../c-runtime-library/reference/makepath-wmakepath.md), [`_makepath_s`, `_wmakepath_s`](../c-runtime-library/reference/makepath-s-wmakepath-s.md)|Merge path components into single, full path| -|[`_mktemp`, `_wmktemp`](../c-runtime-library/reference/mktemp-wmktemp.md), [`_mktemp_s`, `_wmktemp_s`](../c-runtime-library/reference/mktemp-s-wmktemp-s.md)|Create unique filename| -|[`remove`, `_wremove`](../c-runtime-library/reference/remove-wremove.md)|Delete file| -|[`rename`, `_wrename`](../c-runtime-library/reference/rename-wrename.md)|Rename file| -|[`_splitpath`, `_wsplitpath`](../c-runtime-library/reference/splitpath-wsplitpath.md), [`_splitpath_s`, `_wsplitpath_s`](../c-runtime-library/reference/splitpath-s-wsplitpath-s.md)|Parse path into components| -|[`_stat`, `_stat64`, `_stati64`, `_wstat`, `_wstat64`, `_wstati64`](../c-runtime-library/reference/stat-functions.md)|Get file-status information on named file| -|[`_umask`](../c-runtime-library/reference/umask.md), [`_umask_s`](../c-runtime-library/reference/umask-s.md)|Set default permission mask for new files created by program| -|[`_unlink`, `_wunlink`](../c-runtime-library/reference/unlink-wunlink.md)|Delete file| +| Routine | Use | +|---|---| +| [`_access`, `_waccess`](reference/access-waccess.md), [`_access_s`, `_waccess_s`](reference/access-s-waccess-s.md) | Check file-permission setting | +| [`_chmod`, `_wchmod`](reference/chmod-wchmod.md) | Change file-permission setting | +| [`_fullpath`, `_wfullpath`](reference/fullpath-wfullpath.md) | Expand a relative path to its absolute path name | +| [`_makepath`, `_wmakepath`](reference/makepath-wmakepath.md), [`_makepath_s`, `_wmakepath_s`](reference/makepath-s-wmakepath-s.md) | Merge path components into single, full path | +| [`_mktemp`, `_wmktemp`](reference/mktemp-wmktemp.md), [`_mktemp_s`, `_wmktemp_s`](reference/mktemp-s-wmktemp-s.md) | Create unique filename | +| [`remove`, `_wremove`](reference/remove-wremove.md) | Delete file | +| [`rename`, `_wrename`](reference/rename-wrename.md) | Rename file | +| [`_splitpath`, `_wsplitpath`](reference/splitpath-wsplitpath.md), [`_splitpath_s`, `_wsplitpath_s`](reference/splitpath-s-wsplitpath-s.md) | Parse path into components | +| [`_stat`, `_stat64`, `_stati64`, `_wstat`, `_wstat64`, `_wstati64`](reference/stat-functions.md) | Get file-status information on named file | +| [`_umask`](reference/umask.md), [`_umask_s`](reference/umask-s.md) | Set default permission mask for new files created by program | +| [`_unlink`, `_wunlink`](reference/unlink-wunlink.md) | Delete file | ## File-Handling Routines (Open File) These routines open files. -|Routine|Use| -|-------------|---------| -|[`fopen`, `_wfopen`](../c-runtime-library/reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](../c-runtime-library/reference/fopen-s-wfopen-s.md)|Opens a file and returns a pointer to the open file.| -|[`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md)|Open a stream with file sharing and returns a pointer to the open file.| -|[`_open`, `_wopen`](../c-runtime-library/reference/open-wopen.md)|Opens a file and returns a file descriptor to the opened file.| -|[`_sopen`, `_wsopen`](../c-runtime-library/reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open a file with file sharing and returns a file descriptor to the open file.| -|[`_pipe`](../c-runtime-library/reference/pipe.md)|Creates a pipe for reading and writing.| -|[`freopen`, `_wfreopen`](../c-runtime-library/reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](../c-runtime-library/reference/freopen-s-wfreopen-s.md)|Reassign a file pointer.| +| Routine | Use | +|---|---| +| [`fopen`, `_wfopen`](reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](reference/fopen-s-wfopen-s.md) | Opens a file and returns a pointer to the open file. | +| [`_fsopen`, `_wfsopen`](reference/fsopen-wfsopen.md) | Open a stream with file sharing and returns a pointer to the open file. | +| [`_open`, `_wopen`](reference/open-wopen.md) | Opens a file and returns a file descriptor to the opened file. | +| [`_sopen`, `_wsopen`](reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](reference/sopen-s-wsopen-s.md) | Open a file with file sharing and returns a file descriptor to the open file. | +| [`_pipe`](reference/pipe.md) | Creates a pipe for reading and writing. | +| [`freopen`, `_wfreopen`](reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](reference/freopen-s-wfreopen-s.md) | Reassign a file pointer. | These routines provide a way to change the representation of the file between a `FILE` structure, a file descriptor, and a Win32 file handle. -|Routine|Use| -|-------------|---------| -|[`_fdopen`, `_wfdopen`](../c-runtime-library/reference/fdopen-wfdopen.md)|Associates a stream with a file that was previously opened for low-level I/O and returns a pointer to the open stream.| -|[`_fileno`](../c-runtime-library/reference/fileno.md)|Gets the file descriptor associated with a stream.| -|[`_get_osfhandle`](../c-runtime-library/reference/get-osfhandle.md)|Return operating-system file handle associated with existing C run-time file descriptor| -|[`_open_osfhandle`](../c-runtime-library/reference/open-osfhandle.md)|Associates C run-time file descriptor with an existing operating-system file handle.| +| Routine | Use | +|---|---| +| [`_fdopen`, `_wfdopen`](reference/fdopen-wfdopen.md) | Associates a stream with a file that was previously opened for low-level I/O and returns a pointer to the open stream. | +| [`_fileno`](reference/fileno.md) | Gets the file descriptor associated with a stream. | +| [`_get_osfhandle`](reference/get-osfhandle.md) | Return operating-system file handle associated with existing C run-time file descriptor | +| [`_open_osfhandle`](reference/open-osfhandle.md) | Associates C run-time file descriptor with an existing operating-system file handle. | The following Win32 functions also open files and pipes: - [`CreateFile`](/windows/win32/api/fileapi/nf-fileapi-createfilew) - - [`CreatePipe`](/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe) - - [`CreateNamedPipe`](/windows/win32/api/winbase/nf-winbase-createnamedpipea) ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[Directory Control](../c-runtime-library/directory-control.md)
-[System Calls](../c-runtime-library/system-calls.md)
+[Universal C runtime routines by category](run-time-routines-by-category.md)\ +[Directory control](directory-control.md)\ +[System calls](system-calls.md) diff --git a/docs/c-runtime-library/file-permission-constants.md b/docs/c-runtime-library/file-permission-constants.md index 3c5303afa1..cf52032484 100644 --- a/docs/c-runtime-library/file-permission-constants.md +++ b/docs/c-runtime-library/file-permission-constants.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["S_IWRITE constant", "constants [C++], file attributes", "S_IREAD constant", "file permissions [C++]", "_S_IWRITE constant", "_S_IREAD constant"] ms.assetid: 593cad33-31d1-44d2-8941-8af7d210c88c --- -# File Permission Constants +# File permission constants ## Syntax -``` +```C #include ``` @@ -19,24 +19,24 @@ One of these constants is required when `_O_CREAT` (`_open`, `_sopen`) is specif The `pmode` argument specifies the file's permission settings as follows. -|Constant|Meaning| -|--------------|-------------| -|`_S_IREAD`|Reading permitted| -|`_S_IWRITE`|Writing permitted| -|`_S_IREAD` | `_S_IWRITE`|Reading and writing permitted| +| Constant | Meaning | +|---|---| +| `_S_IREAD` | Reading permitted | +| `_S_IWRITE` | Writing permitted | +| `_S_IREAD | _S_IWRITE` | Reading and writing permitted | When used as the `pmode` argument for `_umask`, the manifest constant sets the permission setting, as follows. -|Constant|Meaning| -|--------------|-------------| -|`_S_IREAD`|Writing not permitted (file is read-only)| -|`_S_IWRITE`|Reading not permitted (file is write-only)| -|`_S_IREAD` | `_S_IWRITE`|Neither reading nor writing permitted| +| Constant | Meaning | +|---|---| +| `_S_IREAD` | Writing not permitted (file is read-only) | +| `_S_IWRITE` | Reading not permitted (file is write-only) | +| `_S_IREAD | _S_IWRITE` | Both reading and writing not permitted | ## See also -[_open, _wopen](../c-runtime-library/reference/open-wopen.md)
-[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[_umask](../c-runtime-library/reference/umask.md)
-[Standard Types](../c-runtime-library/standard-types.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_open`, `_wopen`](./reference/open-wopen.md)\ +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[`_umask`](./reference/umask.md)\ +[Standard types](./standard-types.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-read-write-access-constants.md b/docs/c-runtime-library/file-read-write-access-constants.md index 61bd190803..ebb65e68dd 100644 --- a/docs/c-runtime-library/file-read-write-access-constants.md +++ b/docs/c-runtime-library/file-read-write-access-constants.md @@ -5,36 +5,36 @@ ms.date: "11/04/2016" helpviewer_keywords: ["read/write access constants", "write access constants", "access constants for file read/write", "constants [C++], file attributes", "file read/write access constants"] ms.assetid: 56cd1d22-39a5-4fcf-bea2-7046d249e8ee --- -# File Read/Write Access Constants +# File read/write access constants ## Syntax -``` +```C #include ``` ## Remarks -These constants specify the access type ("a", "r", or "w") requested for the file. Both the [translation mode](../c-runtime-library/file-translation-constants.md) ("b" or "t") and the [commit-to-disk mode](../c-runtime-library/commit-to-disk-constants.md) ("c" or "n") can be specified with the type of access. +These constants specify the access type ("a", "r", or "w") requested for the file. Both the [translation mode](./file-translation-constants.md) ("b" or "t") and the [commit-to-disk mode](./commit-to-disk-constants.md) ("c" or "n") can be specified with the type of access. The access types are described in this table: -|Access type|Description| -|----------|----------------| -|**"r"**|Opens for reading. If the file does not exist or cannot be found, the call to open the file fails.| -|**"w"**|Opens an empty file for writing. If the given file exists, its contents are destroyed.| -|**"a"**|Opens for writing at the end of the file (appending); creates the file first if it does not exist. All write operations occur at the end of the file. Although the file pointer can be repositioned using `fseek` or `rewind`, it is always moved back to the end of the file before any write operation is carried out. | -|**"r+"**|Opens for both reading and writing. If the file does not exist or cannot be found, the call to open the file fails.| -|**"w+"**|Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.| -|**"a+"**|The same as **"a"** but also allows reading.| +| Access type | Description | +|---|---| +| **"`r`"** | Opens for reading. If the file doesn't exist or can't be found, the call to open the file fails. | +| **"`w`"** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | +| **"`a`"** | Opens for writing at the end of the file (appending); creates the file first if it doesn't exist. All write operations occur at the end of the file. Although the file pointer can be repositioned using `fseek` or `rewind`, it's always moved back to the end of the file before any write operation is carried out. | +| **"`r+`"** | Opens for both reading and writing. If the file doesn't exist or can't be found, the call to open the file fails. | +| **"`w+`"** | Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. | +| **"`a+`"** | The same as **"`a`"** but also allows reading. | When the "r+", "w+", or "a+" type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening `fflush`, `fsetpos`, `fseek`, or `rewind` operation. The current position can be specified for the `fsetpos` or `fseek` operation. ## See also -[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[_popen, _wpopen](../c-runtime-library/reference/popen-wpopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[`_popen`, `_wpopen`](./reference/popen-wpopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-translation-constants.md b/docs/c-runtime-library/file-translation-constants.md index 92f8263ea7..74ecd23f24 100644 --- a/docs/c-runtime-library/file-translation-constants.md +++ b/docs/c-runtime-library/file-translation-constants.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["translation constants", "file translation [C++], constants", "translation, file translation constants", "translation, constants", "constants [C++], file translation mode", "file translation [C++]"] ms.assetid: 49b13bf3-442e-4d19-878b-bd1029fa666a --- -# File Translation Constants +# File translation constants ## Syntax -``` +```C #include ``` @@ -21,7 +21,7 @@ The translation modes are as follows: - **t** - Opens in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input, and LF characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. This is done because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. + Opens in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input, and LF characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. It's removed because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. > [!NOTE] > The **t** option is not part of the ANSI standard for `fopen` and `freopen`. It is a Microsoft extension and should not be used where ANSI portability is desired. @@ -30,12 +30,12 @@ The translation modes are as follows: Opens in binary (untranslated) mode. The above translations are suppressed. -If **t** or **b** is not given in *mode*, the translation mode is defined by the default-mode variable [_fmode](../c-runtime-library/fmode.md). For more information about using text and binary modes, see [Text and Binary Mode File I/O](../c-runtime-library/text-and-binary-mode-file-i-o.md). +If **t** or **b** isn't given in *`mode`*, the translation mode is defined by the default-mode variable [`_fmode`](./fmode.md). For more information about using text and binary modes, see [Text and binary mode file I/O](./text-and-binary-mode-file-i-o.md). ## See also -[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/filename-max.md b/docs/c-runtime-library/filename-max.md index 15923f7b07..81d0ddb93a 100644 --- a/docs/c-runtime-library/filename-max.md +++ b/docs/c-runtime-library/filename-max.md @@ -2,21 +2,21 @@ description: "Learn more about: FILENAME_MAX" title: "FILENAME_MAX" ms.date: "11/04/2016" -f1_keywords: ["FILENAME_MAX"] +f1_keywords: ["STDIO/FILENAME_MAX", "FILENAME_MAX"] helpviewer_keywords: ["FILENAME_MAX constant"] ms.assetid: fe368d24-3f31-42d6-859c-cbd84f446ee5 --- -# FILENAME_MAX +# `FILENAME_MAX` The maximum permissible length for a `filename` string buffer size. ## Syntax -``` +```C #include ``` ## See also -[Path Field Limits](../c-runtime-library/path-field-limits.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Path field limits](./path-field-limits.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/filename-search-functions.md b/docs/c-runtime-library/filename-search-functions.md index e7414e0598..fd8726e2d6 100644 --- a/docs/c-runtime-library/filename-search-functions.md +++ b/docs/c-runtime-library/filename-search-functions.md @@ -6,85 +6,84 @@ api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msv api_type: ["DLLExport"] topic_type: ["apiref"] helpviewer_keywords: ["file names [C++], searching for", "_find function", "wfind function", "find function", "_wfind function"] -ms.assetid: 2bc2f8ef-44e4-4271-b3e8-666d36fde828 --- -# Filename Search Functions +# Filename search functions These functions search for and close searches for specified file names: -- [_findnext, _wfindnext](../c-runtime-library/reference/findnext-functions.md) +- [`_findnext`, `_wfindnext`](./reference/findnext-functions.md) -- [_findfirst, _wfindfirst](../c-runtime-library/reference/findfirst-functions.md) +- [`_findfirst`, `_wfindfirst`](./reference/findfirst-functions.md) -- [_findclose](../c-runtime-library/reference/findclose.md) +- [`_findclose`](./reference/findclose.md) ## Remarks The `_findfirst` function provides information about the first instance of a file name that matches the file specified in the `filespec` argument. You can use in `filespec` any combination of wildcard characters that is supported by the host operating system. -The functions return file information in a `_finddata_t` structure, which is defined in IO.h. Various functions in the family use many variations on the `_finddata_t` structure. The basic `_finddata_t` structure includes the following elements: +The functions return file information in a `_finddata_t` structure, which is defined in `IO.h`. Various functions in the family use many variations on the `_finddata_t` structure. The basic `_finddata_t` structure includes the following elements: -`unsigned attrib`
+`unsigned attrib`\ File attribute. -`time_t time_create`
-Time of file creation (-1L for FAT file systems). This time is stored in UTC format. To convert to the local time, use [localtime_s](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md). +`time_t time_create`\ +Time of file creation (`-1L` for FAT file systems). This time is stored in UTC format. To convert to the local time, use [`localtime_s`](./reference/localtime-s-localtime32-s-localtime64-s.md). -`time_t time_access`
-Time of the last file access (-1L for FAT file systems). This time is stored in UTC format. To convert to the local time, use `localtime_s`. +`time_t time_access`\ +Time of the last file access (`-1L` for FAT file systems). This time is stored in UTC format. To convert to the local time, use `localtime_s`. -`time_t time_write`
+`time_t time_write`\ Time of the last write to file. This time is stored in UTC format. To convert to the local time, use `localtime_s`. -`_fsize_t size`
+`_fsize_t size`\ Length of the file in bytes. `char name`[ `_MAX_PATH`] -Null-terminated name of matched file or directory, without the path. +`NULL`-terminated name of matched file or directory, without the path. -In file systems that do not support the creation and last access times of a file, such as the FAT system, the `time_create` and `time_access` fields are always -1L. +In file systems that don't support the creation and last access times of a file, such as the FAT system, the `time_create` and `time_access` fields are always `-1L`. -`_MAX_PATH` is defined in Stdlib.h as 260 bytes. +`_MAX_PATH` is defined in `Stdlib.h` as 260 bytes. -You cannot specify target attributes (such as `_A_RDONLY`) to limit the find operation. These attributes are returned in the `attrib` field of the `_finddata_t` structure and can have the following values (defined in IO.h). Users should not rely on these being the only values possible for the `attrib` field. +You can't specify target attributes (such as `_A_RDONLY`) to limit the find operation. These attributes are returned in the `attrib` field of the `_finddata_t` structure and can have the following values (defined in `IO.h`). Users shouldn't rely on these attributes being the only values possible for the `attrib` field. -`_A_ARCH`
-Archive. Set whenever the file is changed and cleared by the **BACKUP** command. Value: 0x20. +`_A_ARCH`\ +Archive. Set whenever the file is changed and cleared by the **`BACKUP`** command. Value: `0x20`. -`_A_HIDDEN`
-Hidden file. Not generally seen with the DIR command, unless you use the **/AH** option. Returns information about normal files and files that have this attribute. Value: 0x02. +`_A_HIDDEN`\ +Hidden file. Not often seen with the `DIR` command, unless you use the **`/AH`** option. Returns information about normal files and files that have this attribute. Value: `0x02`. -`_A_NORMAL`
-Normal. File has no other attributes set and can be read or written to without restriction. Value: 0x00. +`_A_NORMAL`\ +Normal. File has no other attributes set and can be read or written to without restriction. Value: `0x00`. -`_A_RDONLY`
-Read-only. File cannot be opened for writing and a file that has the same name cannot be created. Value: 0x01. +`_A_RDONLY`\ +Read-only. File can't be opened for writing and a file that has the same name can't be created. Value: `0x01`. -`_A_SUBDIR`
-Subdirectory. Value: 0x10. +`_A_SUBDIR`\ +Subdirectory. Value: `0x10`. -`_A_SYSTEM`
-System file. Not ordinarily seen with the **DIR** command, unless the **/A** or **/A:S** option is used. Value: 0x04. +`_A_SYSTEM`\ +System file. Not ordinarily seen with the **`DIR`** command, unless the **`/A`** or **`/A:S`** option is used. Value: `0x04`. -`_findnext` finds the next name, if any, that matches the `filespec` argument specified in an earlier call to `_findfirst`. The `fileinfo` argument should point to a structure initialized by the previous call to `_findfirst`. If a match is found, the `fileinfo` structure contents are changed as described earlier. Otherwise, it is left unchanged. `_findclose` closes the specified search handle and releases all associated resources for both `_findfirst` and `_findnext`. The handle returned by either `_findfirst` or `_findnext` must first be passed to `_findclose`, before modification operations, such as deleting, can be performed on the directories that form the paths passed to them. +`_findnext` finds the next name, if any, that matches the `filespec` argument specified in an earlier call to `_findfirst`. The `fileinfo` argument should point to a structure initialized by the previous call to `_findfirst`. If a match is found, the `fileinfo` structure contents are changed as described earlier. Otherwise, it's left unchanged. `_findclose` closes the specified search handle and releases all associated resources for both `_findfirst` and `_findnext`. The handle returned by either `_findfirst` or `_findnext` must first be passed to `_findclose`, before modification operations, such as deleting, can be performed on the directories that form the paths passed to them. You can nest the `_find` functions. For example, if a call to `_findfirst` or `_findnext` finds the file that is a subdirectory, a new search can be initiated with another call to `_findfirst` or `_findnext`. -`_wfindfirst` and `_wfindnext` are wide-character versions of `_findfirst` and `_findnext`. The structure argument of the wide-character versions has the `_wfinddata_t` data type, which is defined in IO.h and in Wchar.h. The fields of this data type are the same as those of the `_finddata_t` data type, except that in `_wfinddata_t` the name field is of type **`wchar_t`** instead of type **`char`**. Otherwise `_wfindfirst` and `_wfindnext` behave identically to `_findfirst` and `_findnext`. +`_wfindfirst` and `_wfindnext` are wide-character versions of `_findfirst` and `_findnext`. The structure argument of the wide-character versions has the `_wfinddata_t` data type, which is defined in `IO.h` and in `Wchar.h`. The fields of this data type are the same as the fields of the `_finddata_t` data type, except that in `_wfinddata_t` the `name` field is of type **`wchar_t`** instead of type **`char`**. Otherwise, `_wfindfirst` and `_wfindnext` behave identically to `_findfirst` and `_findnext`. -`_findfirst` and `_findnext` use the 64-bit time type. If you must use the old 32-bit time type, you can define `_USE_32BIT_TIME_T`. The versions of these functions that have the `32` suffix in their names use the 32-bit time type, and those with the `64` suffix use the 64-bit time type. +`_findfirst` and `_findnext` use the 64-bit time type. If you must use the old 32-bit time type, you can define `_USE_32BIT_TIME_T`. The versions of these functions that have the `32` suffix in their names use the 32-bit time type, and the ones with the `64` suffix use the 64-bit time type. Functions `_findfirst32i64`, `_findnext32i64`, `_wfindfirst32i64`, and `_wfindnext32i64` also behave identically to the 32-bit time type versions of these functions except they use and return 64-bit file lengths. Functions `_findfirst64i32`, `_findnext64i32`, `_wfindfirst64i32`, and `_wfindnext64i32` use the 64-bit time type but use 32-bit file lengths. These functions use appropriate variations of the `_finddata_t` type in which the fields have different types for the time and the file size. `_finddata_t` is actually a macro that evaluates to `_finddata64i32_t` (or `_finddata32_t` if `_USE_32BIT_TIME_T` is defined). The following table summarizes the variations on `_finddata_t`: -|Structure|Time type|File size type| -|---------------|---------------|--------------------| -|`_finddata_t`, `_wfinddata_t`|`__time64_t`|`_fsize_t`| -|`_finddata32_t`, `_wfinddata32_t`|`__time32_t`|`_fsize_t`| -|`__finddata64_t`, `__wfinddata64_t`|`__time64_t`|**`__int64`**| -|`_finddata32i64_t`, `_wfinddata32i64_t`|`__time32_t`|**`__int64`**| -|`_finddata64i32_t`, `_wfinddata64i32_t`|`__time64_t`|`_fsize_t`| +| Structure | Time type | File size type | +|---|---|---| +| `_finddata_t`, `_wfinddata_t` | `__time64_t` | `_fsize_t` | +| `_finddata32_t`, `_wfinddata32_t` | `__time32_t` | `_fsize_t` | +| `__finddata64_t`, `_wfinddata64_t` | `__time64_t` | **`__int64`** | +| `_finddata32i64_t`, `_wfinddata32i64_t` | `__time32_t` | **`__int64`** | +| `_finddata64i32_t`, `_wfinddata64i32_t` | `__time64_t` | `_fsize_t` | `_fsize_t` is a **`typedef`** for **`unsigned long`** (32 bits). @@ -140,4 +139,4 @@ N N N Y test.c Wed Feb 06 14:30:44 2002 312 ## See also -[System Calls](../c-runtime-library/system-calls.md) +[System calls](./system-calls.md) diff --git a/docs/c-runtime-library/files-and-streams.md b/docs/c-runtime-library/files-and-streams.md index 9d4ea210d1..16b6697be7 100644 --- a/docs/c-runtime-library/files-and-streams.md +++ b/docs/c-runtime-library/files-and-streams.md @@ -6,7 +6,7 @@ ms.topic: "conceptual" helpviewer_keywords: ["files [C++]", "streams"] ms.assetid: f61e712b-eac9-4c28-bb18-97c3786ef387 --- -# Files and Streams +# Files and streams A program communicates with the target environment by reading and writing files. A file can be: @@ -16,27 +16,27 @@ A program communicates with the target environment by reading and writing files. - A stream of bytes received from or sent to a peripheral device. -The last two items are interactive files. Files are typically the principal means by which to interact with a program. You manipulate all these kinds of files in much the same way — by calling library functions. You include the standard header STDIO.H to declare most of these functions. +The last two items are interactive files. Files are typically the principal means by which to interact with a program. You manipulate all these kinds of files in much the same way: by calling library functions. You include the standard header STDIO.H to declare most of these functions. Before you can perform many of the operations on a file, the file must be opened. Opening a file associates it with a stream, a data structure within the Standard C Library that glosses over many differences among files of various kinds. The library maintains the state of each stream in an object of type FILE. -The target environment opens three files before program startup. You can open a file by calling the library function [fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md) with two arguments. (The `fopen` function has been deprecated, use [fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md) instead.) The first argument is a filename. The second argument is a C string that specifies: +The target environment opens three files before program startup. You can open a file by calling the library function [`fopen`, `_wfopen`](./reference/fopen-wfopen.md) with two arguments. (The `fopen` function has been deprecated, use [`fopen_s`, `_wfopen_s`](./reference/fopen-s-wfopen-s.md) instead.) The first argument is a filename. The second argument is a C string that specifies: - Whether you intend to read data from the file or write data to it or both. -- Whether you intend to generate new contents for the file (or create a file if it did not previously exist) or leave the existing contents in place. +- Whether you intend to generate new contents for the file (or create a file if it didn't previously exist) or leave the existing contents in place. - Whether writes to a file can alter existing contents or should only append bytes at the end of the file. - Whether you want to manipulate a text stream or a binary stream. -Once the file is successfully opened, you can then determine whether the stream is byte oriented (a byte stream) or wide oriented (a wide stream). A stream is initially unbound. Calling certain functions to operate on the stream makes it byte oriented, while certain other functions make it wide oriented. Once established, a stream maintains its orientation until it is closed by a call to [fclose](../c-runtime-library/reference/fclose-fcloseall.md) or [freopen](../c-runtime-library/reference/freopen-wfreopen.md). +Once the file is successfully opened, you can then determine whether the stream is byte oriented (a byte stream) or wide oriented (a wide stream). A stream is initially unbound. Calling certain functions to operate on the stream makes it byte oriented, while certain other functions make it wide oriented. Once established, a stream maintains its orientation until it's closed by a call to [`fclose`](./reference/fclose-fcloseall.md) or [`freopen`](./reference/freopen-wfreopen.md). © 1989-2001 by P.J. Plauger and Jim Brodie. All rights reserved. ## See also -[Text and Binary Streams](../c-runtime-library/text-and-binary-streams.md)
-[Byte and Wide Streams](../c-runtime-library/byte-and-wide-streams.md)
-[Controlling Streams](../c-runtime-library/controlling-streams.md)
-[Stream States](../c-runtime-library/stream-states.md) +[Text and binary streams](./text-and-binary-streams.md)\ +[Byte and wide streams](./byte-and-wide-streams.md)\ +[Controlling streams](./controlling-streams.md)\ +[Stream states](./stream-states.md) diff --git a/docs/c-runtime-library/find-memory-leaks-using-the-crt-library.md b/docs/c-runtime-library/find-memory-leaks-using-the-crt-library.md new file mode 100644 index 0000000000..1e78d27ce5 --- /dev/null +++ b/docs/c-runtime-library/find-memory-leaks-using-the-crt-library.md @@ -0,0 +1,285 @@ +--- +title: Find memory leaks with the CRT library +description: Learn how the C/C++ debugger and C Run-time Library (CRT) can help find memory leaks. The techniques include memory-leak reports and comparing memory snapshots. +ms.date: 02/03/2023 +helpviewer_keywords: + - breakpoints, on memory allocation + - _CrtMemState + - _CrtMemCheckpoint + - memory leaks + - _CrtMemDifference + - memory leaks, detecting and isolating + - _CrtDumpMemoryLeaks + - _CrtSetBreakAlloc + - _crtBreakAlloc + - _CrtSetReportMode + - memory, debugging + - _CrtMemDumpStatistics + - debugging memory leaks + - _CRTDBG_MAP_ALLOC + - _CrtSetDbgFlag +--- +# Find memory leaks with the CRT library + +Memory leaks are among the most subtle and hard-to-detect bugs in C/C++ apps. Memory leaks result from the failure to correctly deallocate memory that was previously allocated. A small memory leak might not be noticed at first, but over time can cause symptoms ranging from poor performance to crashing when the app runs out of memory. A leaking app that uses up all available memory can cause other apps to crash, creating confusion as to which app is responsible. Even harmless memory leaks might indicate other problems that should be corrected. + +The Visual Studio debugger and C Run-time Library (CRT) can help you detect and identify memory leaks. + +## Enable memory leak detection + +The primary tools for detecting memory leaks are the C/C++ debugger and the CRT debug heap functions. + +To enable all the debug heap functions, include the following statements in your C++ program, in the following order: + +```cpp +#define _CRTDBG_MAP_ALLOC +#include +#include +``` + +The `#define` statement maps a base version of the CRT heap functions to the corresponding debug version. If you leave out the `#define` statement, the memory leak dump will be [less detailed](#interpret-the-memory-leak-report). + +Including *crtdbg.h* maps the `malloc` and `free` functions to their debug versions, [`_malloc_dbg`](./reference/malloc-dbg.md) and [`_free_dbg`](./reference/free-dbg.md), which track memory allocation and deallocation. This mapping occurs only in debug builds, which have `_DEBUG`. Release builds use the ordinary `malloc` and `free` functions. + +After you've enabled the debug heap functions by using the preceding statements, place a call to [`_CrtDumpMemoryLeaks`](./reference/crtdumpmemoryleaks.md) before an app exit point to display a memory-leak report when the app exits. + +```cpp +_CrtDumpMemoryLeaks(); +``` + +If your app has several exits, you don't need to manually place `_CrtDumpMemoryLeaks` at every exit point. To cause an automatic call to `_CrtDumpMemoryLeaks` at each exit point, place a call to `_CrtSetDbgFlag` at the beginning of your app with the bit fields shown here: + +```cpp +_CrtSetDbgFlag ( _CRTDBG_ALLOC_MEM_DF | _CRTDBG_LEAK_CHECK_DF ); +``` + +By default, `_CrtDumpMemoryLeaks` outputs the memory-leak report to the **Debug** pane of the **Output** window. If you use a library, the library might reset the output to another location. + +You can use `_CrtSetReportMode` to redirect the report to another location, or back to the **Output** window as shown here: + +```cpp +_CrtSetReportMode( _CRT_WARN, _CRTDBG_MODE_DEBUG ); +``` + +The following example shows a simple memory leak and displays memory leak information using `_CrtDumpMemoryLeaks();`. + +```cpp +// debug_malloc.cpp +// compile by using: cl /EHsc /W4 /D_DEBUG /MDd debug_malloc.cpp +#define _CRTDBG_MAP_ALLOC +#include +#include +#include + +int main() +{ + std::cout << "Hello World!\n"; + + int* x = (int*)malloc(sizeof(int)); + + *x = 7; + + printf("%d\n", *x); + + x = (int*)calloc(3, sizeof(int)); + x[0] = 7; + x[1] = 77; + x[2] = 777; + + printf("%d %d %d\n", x[0], x[1], x[2]); + + _CrtSetReportMode(_CRT_WARN, _CRTDBG_MODE_DEBUG); + _CrtDumpMemoryLeaks(); +} +``` + +## Interpret the memory-leak report + +If your app doesn't define `_CRTDBG_MAP_ALLOC`, [_CrtDumpMemoryLeaks](./reference/crtdumpmemoryleaks.md) displays a memory-leak report that looks like: + +```cmd +Detected memory leaks! +Dumping objects -> +{18} normal block at 0x00780E80, 64 bytes long. + Data: < > CD CD CD CD CD CD CD CD CD CD CD CD CD CD CD CD +Object dump complete. +``` + +If your app defines `_CRTDBG_MAP_ALLOC`, the memory-leak report looks like: + +```cmd +Detected memory leaks! +Dumping objects -> +c:\users\username\documents\projects\leaktest\leaktest.cpp(20) : {18} +normal block at 0x00780E80, 64 bytes long. + Data: < > CD CD CD CD CD CD CD CD CD CD CD CD CD CD CD CD +Object dump complete. +``` + +The second report shows the filename and line number where the leaked memory is first allocated. + +Whether or not you define `_CRTDBG_MAP_ALLOC`, the memory-leak report displays: + +- The memory allocation number, which is `18` in the example +- The block type, `normal` in the example. +- The hexadecimal memory location, `0x00780E80` in the example. +- The size of the block, `64 bytes` in the example. +- The first 16 bytes of data in the block, in hexadecimal form. + +Memory block types are *normal*, *client*, or *CRT*. A *normal block* is ordinary memory allocated by your program. A *client block* is a special type of memory block used by MFC programs for objects that require a destructor. The MFC `new` operator creates either a normal block or a client block, as appropriate for the object being created. + +A *CRT block* is allocated by the CRT library for its own use. The CRT library handles the deallocation for these blocks, so CRT blocks won't appear in the memory-leak report unless there are serious problems with the CRT library. + +There are two other types of memory blocks that never appear in memory-leak reports. A *free block* is memory that has been released, so by definition isn't leaked. An *ignore block* is memory that you've explicitly marked to exclude from the memory-leak report. + +The preceding techniques identify memory leaks for memory allocated using the standard CRT `malloc` function. If your program allocates memory using the C++ `new` operator, however, you may only see the filename and line number where `operator new` calls `_malloc_dbg` in the memory-leak report. To create a more useful memory-leak report, you can write a macro like the following to report the line that made the allocation: + +```cpp +#ifdef _DEBUG + #define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ ) + // Replace _NORMAL_BLOCK with _CLIENT_BLOCK if you want the + // allocations to be of _CLIENT_BLOCK type +#else + #define DBG_NEW new +#endif +``` + +Now you can replace the `new` operator by using the `DBG_NEW` macro in your code. In debug builds, `DBG_NEW` uses an overload of global `operator new` that takes extra parameters for the block type, file, and line number. The overload of `new` calls `_malloc_dbg` to record the extra information. The memory-leak reports show the filename and line number where the leaked objects were allocated. Release builds still use the default `new`. Here's an example of the technique: + +```cpp +// debug_new.cpp +// compile by using: cl /EHsc /W4 /D_DEBUG /MDd debug_new.cpp +#define _CRTDBG_MAP_ALLOC +#include +#include + +#ifdef _DEBUG + #define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ ) + // Replace _NORMAL_BLOCK with _CLIENT_BLOCK if you want the + // allocations to be of _CLIENT_BLOCK type +#else + #define DBG_NEW new +#endif + +struct Pod { + int x; +}; + +int main() { + Pod* pPod = DBG_NEW Pod; + pPod = DBG_NEW Pod; // Oops, leaked the original pPod! + delete pPod; + + _CrtDumpMemoryLeaks(); +} +``` + +When you run this code in the Visual Studio debugger, the call to `_CrtDumpMemoryLeaks` generates a report in the **Output** window that looks similar to: + +```Output +Detected memory leaks! +Dumping objects -> +c:\users\username\documents\projects\debug_new\debug_new.cpp(20) : {75} + normal block at 0x0098B8C8, 4 bytes long. + Data: < > CD CD CD CD +Object dump complete. +``` + +This output reports that the leaked allocation was on line 20 of *debug_new.cpp*. + +>[!NOTE] +>We don't recommend you create a preprocessor macro named `new`, or any other language keyword. + +## Set breakpoints on a memory allocation number + +The memory allocation number tells you when a leaked memory block was allocated. A block with a memory allocation number of 18, for example, is the 18th block of memory allocated during the run of the app. The CRT report counts all memory-block allocations during the run, including allocations by the CRT library and other libraries such as MFC. Therefore, memory allocation block number 18 probably isn't the 18th memory block allocated by your code. + +You can use the allocation number to set a breakpoint on the memory allocation. + +### To set a memory-allocation breakpoint using the Watch window + +1. Set a breakpoint near the start of your app, and start debugging. + +1. When the app pauses at the breakpoint, open a **Watch** window by selecting **Debug** > **Windows** > **Watch 1** (or **Watch 2**, **Watch 3**, or **Watch 4**). + +1. In the **Watch** window, type `_crtBreakAlloc` in the **Name** column. + + If you're using the multithreaded DLL version of the CRT library (the /MD option), add the context operator: `{,,ucrtbased.dll}_crtBreakAlloc` + + Make sure that debug symbols are loaded. Otherwise, `_crtBreakAlloc` is reported as *unidentified*. + +1. Press **Enter**. + + The debugger evaluates the call and places the result in the **Value** column. This value is **-1** if you haven't set any breakpoints on memory allocations. + +1. In the **Value** column, replace the value with the allocation number of the memory allocation where you want the debugger to break. + +After you set a breakpoint on a memory-allocation number, continue to debug. Make sure to run under the same conditions, so the memory-allocation number doesn't change. When your program breaks at the specified memory allocation, use the **Call Stack** window and other debugger windows to determine the conditions under which the memory was allocated. Then, you can continue execution to observe what happens to the object and determine why it isn't correctly deallocated. + +Setting a data breakpoint on the object might also be helpful. For more information, see [Using breakpoints](/visualstudio/debugger/using-breakpoints). + +You can also set memory-allocation breakpoints in code. You can set: + +```cpp +_crtBreakAlloc = 18; +``` + + or: + +```cpp +_CrtSetBreakAlloc(18); +``` + +## Compare memory states + +Another technique for locating memory leaks involves taking snapshots of the application's memory state at key points. To take a snapshot of the memory state at a given point in your application, create a `_CrtMemState` structure and pass it to the `_CrtMemCheckpoint` function. + +```cpp +_CrtMemState s1; +_CrtMemCheckpoint( &s1 ); +``` + +The `_CrtMemCheckpoint` function fills in the structure with a snapshot of the current memory state. + +To output the contents of a `_CrtMemState` structure, pass the structure to the `_CrtMemDumpStatistics` function: + +```cpp +_CrtMemDumpStatistics( &s1 ); +``` + +`_CrtMemDumpStatistics` outputs a dump of memory state that looks like: + +```cmd +0 bytes in 0 Free Blocks. +0 bytes in 0 Normal Blocks. +3071 bytes in 16 CRT Blocks. +0 bytes in 0 Ignore Blocks. +0 bytes in 0 Client Blocks. +Largest number used: 3071 bytes. +Total allocations: 3764 bytes. +``` + +To determine whether a memory leak has occurred in a section of code, you can take snapshots of the memory state before and after the section, and then use `_CrtMemDifference` to compare the two states: + +```cpp +_CrtMemCheckpoint( &s1 ); +// memory allocations take place here +_CrtMemCheckpoint( &s2 ); + +if ( _CrtMemDifference( &s3, &s1, &s2) ) + _CrtMemDumpStatistics( &s3 ); +``` + +`_CrtMemDifference` compares the memory states `s1` and `s2` and returns a result in (`s3`) that is the difference between `s1` and `s2`. + +One technique for finding memory leaks begins by placing `_CrtMemCheckpoint` calls at the beginning and end of your app, then using `_CrtMemDifference` to compare the results. If `_CrtMemDifference` shows a memory leak, you can add more `_CrtMemCheckpoint` calls to divide your program using a binary search, until you've isolated the source of the leak. + +## False positives + + `_CrtDumpMemoryLeaks` can give false indications of memory leaks if a library marks internal allocations as normal blocks instead of CRT blocks or client blocks. In that case, `_CrtDumpMemoryLeaks` is unable to tell the difference between user allocations and internal library allocations. If the global destructors for the library allocations run after the point where you call `_CrtDumpMemoryLeaks`, every internal library allocation is reported as a memory leak. Versions of the Standard Template Library earlier than Visual Studio .NET may cause `_CrtDumpMemoryLeaks` to report such false positives. + +## See also + +- [CRT debug heap details](./crt-debug-heap-details.md) +- [Debugger security](/visualstudio/debugger/debugger-security) +- [Debugging native code](/visualstudio/debugger/debugging-native-code) diff --git a/docs/c-runtime-library/floating-point-support.md b/docs/c-runtime-library/floating-point-support.md index 18568b2500..7f4ac7bc98 100644 --- a/docs/c-runtime-library/floating-point-support.md +++ b/docs/c-runtime-library/floating-point-support.md @@ -4,131 +4,132 @@ description: "Describes floating-point support in the Microsoft Universal C Runt ms.date: "9/14/2020" f1_keywords: ["c.math"] helpviewer_keywords: ["floating-point numbers, math routines", "math routines", "floating-point numbers"] -ms.assetid: e4fcaf69-5c8e-4854-a9bb-1f412042131e --- # Math and floating-point support -The Universal C Runtime library (UCRT) provides many integral and floating-point math library functions, including all of those required by ISO C99. The floating-point functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ulp of the correctly rounded result, though there may be cases where there is greater inaccuracy. +The Universal C Runtime library (UCRT) provides many integral and floating-point math library functions, including all of the functions required by ISO C99. The floating-point functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ULP (unit of least precision) of the correctly rounded result, though there may be cases where there's greater inaccuracy. -For ISO C Standard 11 (C11) and later, the \ header, in addition to including \ and \, provides macros that invoke a corresponding math function based on the types of the parameters. See [Type-generic math](tgmath.md) for details. +For ISO C Standard 11 (C11) and later, the `` header, in addition to including `` and ``, provides macros that invoke a corresponding math function based on the types of the parameters. See [Type-generic math](tgmath.md) for details. -Many of the floating point math library functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that does not support SSE2, the slower x87 implementation is used. Because different implementations of the math library functions may use different CPU instructions and different algorithms to produce their results, the functions may produce different results across CPUs. In most cases, the results are within +/-1 ulp of the correctly rounded result, but the actual results may vary across CPUs. +Many of the floating-point math library functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that doesn't support SSE2, the slower x87 implementation is used. Because different implementations of the math library functions may use different CPU instructions and different algorithms to produce their results, the functions may produce different results across CPUs. In most cases, the results are within +/-1 ULP of the correctly rounded result, but the actual results may vary across CPUs. + +Newer versions of the UCRT might improve the precision and accuracy of the floating-point math library functions. Since the UCRT is part of the Windows operating system, you might get different results for these functions on different operating system versions or between debug and release builds. Although it is not recommended, you can statically link to the UCRT to guarantee consistent results if you need these functions will produce identical results everywhere. Previous 16-bit versions of Microsoft C/C++ and Microsoft Visual C++ supported the **`long double`** type as an 80-bit precision floating-point data type. In later versions of Visual C++, the **`long double`** data type is a 64-bit precision floating-point data type identical to the **`double`** type. The compiler treats **`long double`** and **`double`** as distinct types, but the **`long double`** functions are identical to their **`double`** counterparts. The CRT provides **`long double`** versions of the math functions for ISO C99 source code compatibility, but note that the binary representation may differ from other compilers. ## Supported math and floating-point routines -|Routine|Use| -|-|-| -[abs, labs, llabs, _abs64](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Computes the absolute value of an integer type -[acos, acosf, acosl](../c-runtime-library/reference/acos-acosf-acosl.md)|Computes the arc cosine -[acosh, acoshf, acoshl](../c-runtime-library/reference/acosh-acoshf-acoshl.md)|Computes the hyperbolic arc cosine -[asin, asinf, asinl](../c-runtime-library/reference/asin-asinf-asinl.md)|Computes the arc sine -[asinh, asinhf, asinhl](../c-runtime-library/reference/asinh-asinhf-asinhl.md)|Computes the hyperbolic arc sine -[atan, atanf, atanl, atan2, atan2f, atan2l](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)|Computes the arc tangent -[atanh, atanhf, atanhl](../c-runtime-library/reference/atanh-atanhf-atanhl.md)|Computes the hyperbolic arc tangent -[_atodbl, _atodbl_l](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Converts a locale-specific string to a **`double`** -[atof, _atof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Converts a string to a **`double`** -[_atoflt, _atoflt_l, _atoldbl, _atoldbl_l](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Converts a locale-specific string to a **`float`** or **`long double`** -[cbrt, cbrtf, cbrtl](../c-runtime-library/reference/cbrt-cbrtf-cbrtl.md)|Computes the cube root -[ceil, ceilf, ceill](../c-runtime-library/reference/ceil-ceilf-ceill.md)|Computes the ceiling -[_chgsign, _chgsignf, _chgsignl](../c-runtime-library/reference/chgsign-chgsignf-chgsignl.md)|Computes the additive inverse -[_clear87, _clearfp](../c-runtime-library/reference/clear87-clearfp.md)|Gets and clears the floating-point status register -[_control87, \__control87_2, _controlfp](../c-runtime-library/reference/control87-controlfp-control87-2.md)|Gets and sets the floating-point control word -[_controlfp_s](../c-runtime-library/reference/controlfp-s.md)|Secure version of **_controlfp** -[copysign, copysignf, copysignl, _copysign, _copysignf, _copysignl](../c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md)|Returns a value that has the magnitude of one argument and the sign of another -[cos, cosf, cosl](../c-runtime-library/reference/cos-cosf-cosl.md)|Computes the sine -[cosh, coshf, coshl](../c-runtime-library/reference/cosh-coshf-coshl.md)|Computes the hyperbolic sine -[div, ldiv, lldiv](../c-runtime-library/reference/div.md)|Computes the quotient and the remainder of two integer values -[_ecvt](../c-runtime-library/reference/ecvt.md), [ecvt](../c-runtime-library/reference/posix-ecvt.md)|Converts a **`double`** to a string -[_ecvt_s](../c-runtime-library/reference/ecvt-s.md)|Secure version of **_ecvt** -[erf, erff, erfl](../c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md)|Computes the error function -[erfc, erfcf, erfcl](../c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md)|Computes the complementary error function -[exp, expf, expl](../c-runtime-library/reference/exp-expf.md)|Computes the exponential *e*x -[exp2, exp2f, exp2l](../c-runtime-library/reference/exp2-exp2f-exp2l.md)|Computes the exponential 2x -[expm1, expm1f, expm1l](../c-runtime-library/reference/expm1-expm1f-expm1l.md)|Computes *e*x-1 -[fabs, fabsf, fabsl](../c-runtime-library/reference/fabs-fabsf-fabsl.md)|Computes the absolute value of a floating-point type -[_fcvt](../c-runtime-library/reference/fcvt.md), [fcvt](../c-runtime-library/reference/posix-fcvt.md)|Converts a floating-point number to a string -[_fcvt_s](../c-runtime-library/reference/fcvt-s.md)|Secure version of **_fcvt** -[fdim, fdimf, fdiml](../c-runtime-library/reference/fdim-fdimf-fdiml.md)|Determines the positive difference between two values -[feclearexcept](../c-runtime-library/reference/feclearexcept1.md)|Clears specified floating-point exceptions -[fegetenv](../c-runtime-library/reference/fegetenv1.md)|Stores the current floating-point environment -[fegetexceptflag](../c-runtime-library/reference/fegetexceptflag2.md)|Gets the specified floating-point exception status -[fegetround](../c-runtime-library/reference/fegetround-fesetround2.md)|Gets the floating-point rounding mode -[feholdexcept](../c-runtime-library/reference/feholdexcept2.md)|Sets non-stop floating-point exception mode -[feraiseexcept](../c-runtime-library/reference/feraiseexcept.md)|Raises the specified floating-point exceptions -[fesetenv](../c-runtime-library/reference/fesetenv1.md)|Sets the current floating-point environment -[fesetexceptflag](../c-runtime-library/reference/fesetexceptflag2.md)|Sets the specified floating-point status flags -[fesetround](../c-runtime-library/reference/fegetround-fesetround2.md)|Sets the specified floating-point rounding mode -[fetestexcept](../c-runtime-library/reference/fetestexcept1.md)|Determines which floating-point exception status flags are set -[feupdateenv](../c-runtime-library/reference/feupdateenv.md)|Restores a floating-point environment then raises previous exceptions -[floor, floorf, floorl](../c-runtime-library/reference/floor-floorf-floorl.md)|Computes the floor -[fma, fmaf, fmal](../c-runtime-library/reference/fma-fmaf-fmal.md)|Computes a fused multiply-add -[fmax, fmaxf, fmaxl](../c-runtime-library/reference/fmax-fmaxf-fmaxl.md)|Computes the maximum of the arguments -[fmin, fminf, fminl](../c-runtime-library/reference/fmin-fminf-fminl.md)|Computes the minimum of the arguments -[fmod, fmodf, fmodl](../c-runtime-library/reference/fmod-fmodf.md)|Computes the floating-point remainder -[_fpclass, _fpclassf](../c-runtime-library/reference/fpclass-fpclassf.md)|Returns the classification of a floating-point value -[fpclassify](../c-runtime-library/reference/fpclassify.md)|Returns the classification of a floating-point value -[_fpieee_flt](../c-runtime-library/reference/fpieee-flt.md)|Sets a handler for floating-point exceptions -[_fpreset](../c-runtime-library/reference/fpreset.md)|Resets the floating-point environment -[frexp, frexpf, frexpl](../c-runtime-library/reference/frexp.md)|Gets the mantissa and exponent of a floating-point number -[_gcvt](../c-runtime-library/reference/gcvt.md), [gcvt](../c-runtime-library/reference/posix-gcvt.md)|Converts a floating-point number to a string -[_gcvt_s](../c-runtime-library/reference/gcvt-s.md)|Secure version of **_gcvt** -[_get_FMA3_enable, _set_FMA3_enable](../c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md)|Gets or sets a flag for use of FMA3 instructions on x64 -[hypot, hypotf, hypotl, _hypot, _hypotf, _hypotl](../c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md)|Computes the hypotenuse -[ilogb, ilogbf, ilogbl](../c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md)|Computes the integer base-2 exponent -[imaxabs](../c-runtime-library/reference/imaxabs.md)|Computes the absolute value of an integer type -[imaxdiv](../c-runtime-library/reference/imaxdiv.md)|Computes the quotient and the remainder of two integer values -[isfinite, _finite, _finitef](../c-runtime-library/reference/finite-finitef.md)|Determines whether a value is finite -[isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered](../c-runtime-library/reference/floating-point-ordering.md)|Compare the order of two floating point values -[isinf](../c-runtime-library/reference/isinf.md)|Determines whether a floating-point value is infinite -[isnan, _isnan, _isnanf](../c-runtime-library/reference/isnan-isnan-isnanf.md)|Tests a floating-point value for NaN -[isnormal](../c-runtime-library/reference/isnormal.md)|Tests whether a floating-point value is both finite and not subnormal -[_j0, _j1, _jn](../c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)|Computes the Bessel function -[ldexp, ldexpf, ldexpl](../c-runtime-library/reference/ldexp.md)|Computes x*2n -[lgamma, lgammaf, lgammal](../c-runtime-library/reference/lgamma-lgammaf-lgammal.md)|Computes the natural logarithm of the absolute value of the gamma function -[llrint, llrintf, llrintl](../c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)|Rounds a floating-point value to the nearest **`long long`** value -[llround, llroundf, llroundl](../c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md)|Rounds a floating-point value to the nearest **`long long`** value -[log, logf, logl, log10, log10f, log10l](../c-runtime-library/reference/log-logf-log10-log10f.md)|Computes the natural or base-10 logarithm -[log1p, log1pf, log1pl](../c-runtime-library/reference/log1p-log1pf-log1pl2.md)|Computes the natural logarithm of 1+x -[log2, log2f, log2l](../c-runtime-library/reference/log2-log2f-log2l.md)|Computes the base-2 logarithm -[logb, logbf, logbl, _logb, _logbf](../c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md)|Returns the exponent of a floating-point value -[lrint, lrintf, lrintl](../c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)|Rounds a floating-point value to the nearest **`long`** value -[_lrotl, _lrotr](../c-runtime-library/reference/lrotl-lrotr.md)|Rotates an integer value left or right -[lround, lroundf, lroundl](../c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md)|Rounds a floating-point value to the nearest **`long`** value -[_matherr](../c-runtime-library/reference/matherr.md)|The default math error handler -[__max](../c-runtime-library/reference/max.md)|Macro that returns the larger of two values -[__min](../c-runtime-library/reference/min.md)|Macro that returns the smaller of two values -[modf, modff, modfl](../c-runtime-library/reference/modf-modff-modfl.md)|Splits a floating-point value into fractional and integer parts -[nan, nanf, nanl](../c-runtime-library/reference/nan-nanf-nanl.md)|Returns a quiet NaN value -[nearbyint, nearbyintf, nearbyintl](../c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md)|Returns the rounded value -[nextafter, nextafterf, nextafterl, _nextafter, _nextafterf](../c-runtime-library/reference/nextafter-functions.md)|Returns the next representable floating-point value -[nexttoward, nexttowardf, nexttowardl](../c-runtime-library/reference/nextafter-functions.md)|Returns the next representable floating-point value -[pow, powf, powl](../c-runtime-library/reference/pow-powf-powl.md)|Returns the value of *x**y* -[remainder, remainderf, remainderl](../c-runtime-library/reference/remainder-remainderf-remainderl.md)|Computes the remainder of the quotient of two floating-point values -[remquo, remquof, remquol](../c-runtime-library/reference/remquo-remquof-remquol.md)|Computes the remainder of two integer values -[rint, rintf, rintl](../c-runtime-library/reference/rint-rintf-rintl.md)|Rounds a floating-point value -[_rotl, _rotl64, _rotr, _rotr64](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)|Rotates bits in integer types -[round, roundf, roundl](../c-runtime-library/reference/round-roundf-roundl.md)|Rounds a floating-point value -[_scalb, _scalbf](../c-runtime-library/reference/scalb.md)|Scales argument by a power of 2 -[scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl](../c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md)|Multiplies a floating-point number by an integral power of **FLT_RADIX** -[_set_controlfp](../c-runtime-library/reference/set-controlfp.md)|Sets the floating-point control word -[_set_SSE2_enable](../c-runtime-library/reference/set-sse2-enable.md)|Enables or disables SSE2 instructions -[signbit](../c-runtime-library/reference/signbit.md)|Tests the sign bit of a floating-point value -[sin, sinf, sinl](../c-runtime-library/reference/sin-sinf-sinl.md)|Computes the sine -[sinh, sinhf, sinhl](../c-runtime-library/reference/sinh-sinhf-sinhl.md)|Computes the hyperbolic sine -[sqrt, sqrtf, sqrtl](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md)|Computes the square root -[_status87, _statusfp, _statusfp2](../c-runtime-library/reference/status87-statusfp-statusfp2.md)|Gets the floating-point status word -[strtof, _strtof_l](../c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md)|Converts a string to a **`float`** -[strtold, _strtold_l](../c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md)|Converts a string to a **`long double`** -[tan, tanf, tanl](../c-runtime-library/reference/tan-tanf-tanl.md)|Computes the tangent -[tanh, tanhf, tanhl](../c-runtime-library/reference/tanh-tanhf-tanhl.md)|Computes the hyperbolic tangent -[tgamma, tgammaf, tgammal](../c-runtime-library/reference/tgamma-tgammaf-tgammal.md)|Computes the gamma function -[trunc, truncf, truncl](../c-runtime-library/reference/trunc-truncf-truncl.md)|Truncates the fractional part -[_wtof, _wtof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Converts a wide string to a **`double`** -[_y0, _y1, _yn](../c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)|Computes the Bessel function +| Routine | Use | +|---|---| +| [`abs`, `labs`, `llabs`, `_abs64`](./reference/abs-labs-llabs-abs64.md) | Computes the absolute value of an integer type | +| [`acos`, `acosf`, `acosl`](./reference/acos-acosf-acosl.md) | Computes the arc cosine | +| [`acosh`, `acoshf`, `acoshl`](./reference/acosh-acoshf-acoshl.md) | Computes the hyperbolic arc cosine | +| [`asin`, `asinf`, `asinl`](./reference/asin-asinf-asinl.md) | Computes the arc sine | +| [`asinh`, `asinhf`, `asinhl`](./reference/asinh-asinhf-asinhl.md) | Computes the hyperbolic arc sine | +| [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | Computes the arc tangent | +| [`atanh`, `atanhf`, `atanhl`](./reference/atanh-atanhf-atanhl.md) | Computes the hyperbolic arc tangent | +| [`_atodbl`, `_atodbl_l`](./reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Converts a locale-specific string to a **`double`** | +| [`atof`, `_atof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Converts a string to a **`double`** | +| [`_atoflt`, `_atoflt_l`, `_atoldbl`, `_atoldbl_l`](./reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Converts a locale-specific string to a **`float`** or **`long double`** | +| [`cbrt`, `cbrtf`, `cbrtl`](./reference/cbrt-cbrtf-cbrtl.md) | Computes the cube root | +| [`ceil`, `ceilf`, `ceill`](./reference/ceil-ceilf-ceill.md) | Computes the ceiling | +| [`_chgsign`, `_chgsignf`, `_chgsignl`](./reference/chgsign-chgsignf-chgsignl.md) | Computes the additive inverse | +| [`_clear87`, `_clearfp`](./reference/clear87-clearfp.md) | Gets and clears the floating-point status register | +| [`_control87`, `_controlfp`, `__control87_2`](./reference/control87-controlfp-control87-2.md) | Gets and sets the floating-point control word | +| [`_controlfp_s`](./reference/controlfp-s.md) | Secure version of **`_controlfp`** | +| [`copysign`, `copysignf`, `copysignl`, `_copysign`, `_copysignf`, `_copysignl`](./reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | Returns a value that has the magnitude of one argument and the sign of another | +| [`cos`, `cosf`, `cosl`](./reference/cos-cosf-cosl.md) | Computes the sine | +| [`cosh`, `coshf`, `coshl`](./reference/cosh-coshf-coshl.md) | Computes the hyperbolic sine | +| [`div`, `ldiv`, `lldiv`](./reference/div.md) | Computes the quotient and the remainder of two integer values | +| [`_ecvt`](./reference/ecvt.md), [`ecvt`](./reference/posix-ecvt.md) | Converts a **`double`** to a string | +| [`_ecvt_s`](./reference/ecvt-s.md) | Secure version of **`_ecvt`** | +| [`erf`, `erff`, `erfl`](./reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | Computes the error function | +| [`erfc`, `erfcf`, `erfcl`](./reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | Computes the complementary error function | +| [`exp`, `expf`, `expl`](./reference/exp-expf.md) | Computes the exponential *e*x | +| [`exp2`, `exp2f`, `exp2l`](./reference/exp2-exp2f-exp2l.md) | Computes the exponential 2x | +| [`expm1`, `expm1f`, `expm1l`](./reference/expm1-expm1f-expm1l.md) | Computes *e*x-1 | +| [`fabs`, `fabsf`, `fabsl`](./reference/fabs-fabsf-fabsl.md) | Computes the absolute value of a floating-point type | +| [`_fcvt`](./reference/fcvt.md), [`fcvt`](./reference/posix-fcvt.md) | Converts a floating-point number to a string | +| [`_fcvt_s`](./reference/fcvt-s.md) | Secure version of **`_fcvt`** | +| [`fdim`, `fdimf`, `fdiml`](./reference/fdim-fdimf-fdiml.md) | Determines the positive difference between two values | +| [`feclearexcept`](./reference/feclearexcept1.md) | Clears specified floating-point exceptions | +| [`fegetenv`](./reference/fegetenv1.md) | Stores the current floating-point environment | +| [`fegetexceptflag`](./reference/fegetexceptflag2.md) | Gets the specified floating-point exception status | +| [`fegetround`](./reference/fegetround-fesetround2.md) | Gets the floating-point rounding mode | +| [`feholdexcept`](./reference/feholdexcept2.md) | Sets non-stop floating-point exception mode | +| [`feraiseexcept`](./reference/feraiseexcept.md) | Raises the specified floating-point exceptions | +| [`fesetenv`](./reference/fesetenv1.md) | Sets the current floating-point environment | +| [`fesetexceptflag`](./reference/fesetexceptflag2.md) | Sets the specified floating-point status flags | +| [`fesetround`](./reference/fegetround-fesetround2.md) | Sets the specified floating-point rounding mode | +| [`fetestexcept`](./reference/fetestexcept1.md) | Determines which floating-point exception status flags are set | +| [`feupdateenv`](./reference/feupdateenv.md) | Restores a floating-point environment then raises previous exceptions | +| [`floor`, `floorf`, `floorl`](./reference/floor-floorf-floorl.md) | Computes the floor | +| [`fma`, `fmaf`, `fmal`](./reference/fma-fmaf-fmal.md) | Computes a fused multiply-add | +| [`fmax`, `fmaxf`, `fmaxl`](./reference/fmax-fmaxf-fmaxl.md) | Computes the maximum of the arguments | +| [`fmin`, `fminf`, `fminl`](./reference/fmin-fminf-fminl.md) | Computes the minimum of the arguments | +| [`fmod`, `fmodf`, `fmodl`](./reference/fmod-fmodf.md) | Computes the floating-point remainder | +| [`_fpclass`, `_fpclassf`](./reference/fpclass-fpclassf.md) | Returns the classification of a floating-point value | +| [`fpclassify`](./reference/fpclassify.md) | Returns the classification of a floating-point value | +| [`_fpieee_flt`](./reference/fpieee-flt.md) | Sets a handler for floating-point exceptions | +| [`_fpreset`](./reference/fpreset.md) | Resets the floating-point environment | +| [`frexp`, `frexpf`, `frexpl`](./reference/frexp.md) | Gets the mantissa and exponent of a floating-point number | +| [`_gcvt`](./reference/gcvt.md), [`gcvt`](./reference/posix-gcvt.md) | Converts a floating-point number to a string | +| [`_gcvt_s`](./reference/gcvt-s.md) | Secure version of **`_gcvt`** | +| [`_get_FMA3_enable`, `_set_FMA3_enable`](./reference/get-fma3-enable-set-fma3-enable.md) | Gets or sets a flag for use of FMA3 instructions on x64 | +| [`hypot`, `hypotf`, `hypotl`, `_hypot`, `_hypotf`, `_hypotl`](./reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | Computes the hypotenuse | +| [`ilogb`, `ilogbf`, `ilogbl`](./reference/ilogb-ilogbf-ilogbl2.md) | Computes the integer base-2 exponent | +| [`imaxabs`](./reference/imaxabs.md) | Computes the absolute value of an integer type | +| [`imaxdiv`](./reference/imaxdiv.md) | Computes the quotient and the remainder of two integer values | +| [`isfinite`, `_finite`, `_finitef`](./reference/finite-finitef.md) | Determines whether a value is finite | +| [`isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, `isunordered`](./reference/floating-point-ordering.md) | Compare the order of two floating-point values | +| [`isinf`](./reference/isinf.md) | Determines whether a floating-point value is infinite | +| [`isnan`, `_isnan`, `_isnanf`](./reference/isnan-isnan-isnanf.md) | Tests a floating-point value for NaN | +| [`isnormal`](./reference/isnormal.md) | Tests whether a floating-point value is both finite and not subnormal | +| [`_j0`, `_j1`, `_jn`](./reference/bessel-functions-j0-j1-jn-y0-y1-yn.md) | Computes the Bessel function | +| [`ldexp`, `ldexpf`, `ldexpl`](./reference/ldexp.md) | Computes x*2n | +| [`lgamma`, `lgammaf`, `lgammal`](./reference/lgamma-lgammaf-lgammal.md) | Computes the natural logarithm of the absolute value of the gamma function | +| [`llrint`, `llrintf`, `llrintl`](./reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | Rounds a floating-point value to the nearest **`long long`** value | +| [`llround`, `llroundf`, `llroundl`](./reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | Rounds a floating-point value to the nearest **`long long`** value | +| [`log`, `logf`, `logl`, `log10`, `log10f`, `log10l`](./reference/log-logf-log10-log10f.md) | Computes the natural or base-10 logarithm | +| [`log1p`, `log1pf`, `log1pl`](./reference/log1p-log1pf-log1pl2.md) | Computes the natural logarithm of 1+x | +| [`log2`, `log2f`, `log2l`](./reference/log2-log2f-log2l.md) | Computes the base-2 logarithm | +| [`logb`, `logbf`, `logbl`, `_logb`, `_logbf`](./reference/logb-logbf-logbl-logb-logbf.md) | Returns the exponent of a floating-point value | +| [`lrint`, `lrintf`, `lrintl`](./reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | Rounds a floating-point value to the nearest **`long`** value | +| [`_lrotl`, `_lrotr`](./reference/lrotl-lrotr.md) | Rotates an integer value left or right | +| [`lround`, `lroundf`, `lroundl`](./reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | Rounds a floating-point value to the nearest **`long`** value | +| [`_matherr`](./reference/matherr.md) | The default math error handler | +| [`__max`](./reference/max.md) | Macro that returns the larger of two values | +| [`__min`](./reference/min.md) | Macro that returns the smaller of two values | +| [`modf`, `modff`, `modfl`](./reference/modf-modff-modfl.md) | Splits a floating-point value into fractional and integer parts | +| [`nan`, `nanf`, `nanl`](./reference/nan-nanf-nanl.md) | Returns a quiet NaN value | +| [`nearbyint`, `nearbyintf`, `nearbyintl`](./reference/nearbyint-nearbyintf-nearbyintl1.md) | Returns the rounded value | +| [`nextafter`, `nextafterf`, `nextafterl`, `_nextafter`, `_nextafterf`](./reference/nextafter-functions.md) | Returns the next representable floating-point value | +| [`nexttoward`, `nexttowardf`, `nexttowardl`](./reference/nextafter-functions.md) | Returns the next representable floating-point value | +| [`pow`, `powf`, `powl`](./reference/pow-powf-powl.md) | Returns the value of *`x`**`y`* | +| [`remainder`, `remainderf`, `remainderl`](./reference/remainder-remainderf-remainderl.md) | Computes the remainder of the quotient of two floating-point values | +| [`remquo`, `remquof`, `remquol`](./reference/remquo-remquof-remquol.md) | Computes the remainder of two integer values | +| [`rint`, `rintf`, `rintl`](./reference/rint-rintf-rintl.md) | Rounds a floating-point value | +| [`_rotl`, `_rotl64`, `_rotr`, `_rotr64`](./reference/rotl-rotl64-rotr-rotr64.md) | Rotates bits in integer types | +| [`round`, `roundf`, `roundl`](./reference/round-roundf-roundl.md) | Rounds a floating-point value | +| [`_scalb`, `_scalbf`](./reference/scalb.md) | Scales argument by a power of 2 | +| [`scalbn`, `scalbnf`, `scalbnl`, `scalbln`, `scalblnf`, `scalblnl`](./reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | Multiplies a floating-point number by an integral power of `FLT_RADIX` | +| [`_set_controlfp`](./reference/set-controlfp.md) | Sets the floating-point control word | +| [`_set_SSE2_enable`](./reference/set-sse2-enable.md) | Enables or disables SSE2 instructions | +| [`signbit`](./reference/signbit.md) | Tests the sign bit of a floating-point value | +| [`sin`, `sinf`, `sinl`](./reference/sin-sinf-sinl.md) | Computes the sine | +| [`sinh`, `sinhf`, `sinhl`](./reference/sinh-sinhf-sinhl.md) | Computes the hyperbolic sine | +| [`sqrt`, `sqrtf`, `sqrtl`](./reference/sqrt-sqrtf-sqrtl.md) | Computes the square root | +| [`_status87`, `_statusfp`, `_statusfp2`](./reference/status87-statusfp-statusfp2.md) | Gets the floating-point status word | +| [`strtof`, `_strtof_l`](./reference/strtof-strtof-l-wcstof-wcstof-l.md) | Converts a string to a **`float`** | +| [`strtold`, `_strtold_l`](./reference/strtold-strtold-l-wcstold-wcstold-l.md) | Converts a string to a **`long double`** | +| [`tan`, `tanf`, `tanl`](./reference/tan-tanf-tanl.md) | Computes the tangent | +| [`tanh`, `tanhf`, `tanhl`](./reference/tanh-tanhf-tanhl.md) | Computes the hyperbolic tangent | +| [`tgamma`, `tgammaf`, `tgammal`](./reference/tgamma-tgammaf-tgammal.md) | Computes the gamma function | +| [`trunc`, `truncf`, `truncl`](./reference/trunc-truncf-truncl.md) | Truncates the fractional part | +| [`_wtof`, `_wtof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Converts a wide string to a **`double`** | +| [`_y0`, `_y1`, `_yn`](./reference/bessel-functions-j0-j1-jn-y0-y1-yn.md) | Computes the Bessel function | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ -[Floating-point primitives](../c-runtime-library/reference/floating-point-primitives.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[Floating-point primitives](./reference/floating-point-primitives.md) diff --git a/docs/c-runtime-library/fmode.md b/docs/c-runtime-library/fmode.md index 308b112b32..9bc5cb02e4 100644 --- a/docs/c-runtime-library/fmode.md +++ b/docs/c-runtime-library/fmode.md @@ -2,17 +2,17 @@ description: "Learn more about: _fmode" title: "_fmode" ms.date: "11/04/2016" -f1_keywords: ["fmode", "_fmode"] -helpviewer_keywords: ["file translation [C++], default mode", "fmode function", "_fmode function"] +f1_keywords: ["_fmode", "STDLIB/_fmode"] +helpviewer_keywords: ["file translation [C++], default mode", "_fmode global variable"] ms.assetid: ac6df9eb-e5cc-4c54-aff3-373c21983118 --- -# _fmode +# `_fmode` -The `_fmode` variable sets the default file-translation mode for text or binary translation. This global variable has been deprecated for the more secure functional versions [_get_fmode](../c-runtime-library/reference/get-fmode.md) and [_set_fmode](../c-runtime-library/reference/set-fmode.md), which should be used in place of the global variable. It is declared in Stdlib.h as follows. +The `_fmode` variable sets the default file-translation mode for text or binary translation. This global variable has been deprecated for the more secure functional versions [`_get_fmode`](./reference/get-fmode.md) and [`_set_fmode`](./reference/set-fmode.md), which should be used in place of the global variable. It's declared in Stdlib.h as follows. ## Syntax -``` +```C extern int _fmode; ``` @@ -22,7 +22,7 @@ The default setting of `_fmode` is `_O_TEXT` for text-mode translation. `_O_BINA You can change the value of `_fmode` in three ways: -- Link with Binmode.obj. This changes the initial setting of `_fmode` to `_O_BINARY`, causing all files except `stdin`, `stdout`, and `stderr` to be opened in binary mode. +- Link with Binmode.obj. This object file changes the initial setting of `_fmode` to `_O_BINARY`, causing all files except `stdin`, `stdout`, and `stderr` to be opened in binary mode. - Make a call to `_get_fmode` or `_set_fmode` to get or set the `_fmode` global variable, respectively. @@ -30,6 +30,6 @@ You can change the value of `_fmode` in three ways: ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[_get_fmode](../c-runtime-library/reference/get-fmode.md)
-[_set_fmode](../c-runtime-library/reference/set-fmode.md) +[Global variables](./global-variables.md)\ +[`_get_fmode`](./reference/get-fmode.md)\ +[`_set_fmode`](./reference/set-fmode.md) diff --git a/docs/c-runtime-library/fopen-max-sys-open.md b/docs/c-runtime-library/fopen-max-sys-open.md index 2c9b6fd3a5..8076924089 100644 --- a/docs/c-runtime-library/fopen-max-sys-open.md +++ b/docs/c-runtime-library/fopen-max-sys-open.md @@ -2,22 +2,22 @@ description: "Learn more about: FOPEN_MAX, _SYS_OPEN" title: "FOPEN_MAX, _SYS_OPEN" ms.date: "11/04/2016" -f1_keywords: ["_SYS_OPEN", "FOPEN_MAX"] +f1_keywords: ["STDIO/_SYS_OPEN", "STDIO/FOPEN_MAX", "_SYS_OPEN", "FOPEN_MAX"] helpviewer_keywords: ["SYS_OPEN constant", "_SYS_OPEN constant", "FOPEN_MAX constant", "files [C++], maximum open", "maximum number of files", "open files, maximum"] ms.assetid: 39cf5196-250a-459d-ae90-ce3d99f79039 --- -# FOPEN_MAX, _SYS_OPEN +# `FOPEN_MAX`, `_SYS_OPEN` ## Syntax -``` +```C #include ``` ## Remarks -This is the maximum number of files that can be opened simultaneously. `FOPEN_MAX` is the ANSI-compatible name. `_SYS_OPEN` is provided for compatibility with existing code. + `FOPEN_MAX` and `_SYS_OPEN` are the maximum number of files that can be opened simultaneously. `FOPEN_MAX` is the ANSI-compatible name. `_SYS_OPEN` is provided for compatibility with existing code. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md b/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md index d2d2699b17..ee57428b23 100644 --- a/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md +++ b/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md @@ -1,45 +1,45 @@ --- -description: "Learn more about: Format Specification Fields: scanf and wscanf Functions" -title: "Format Specification Fields: scanf and wscanf Functions" -ms.date: "11/04/2016" +description: "Learn more about: Format specification fields: scanf and wscanf functions" +title: "Format specification fields: scanf and wscanf functions" +ms.date: 05/13/2022 ms.topic: "reference" -ms.custom: contperf-fy21q1 helpviewer_keywords: ["width, specifications in scanf function", "scanf format specifications", "scanf width specifications", "scanf type field characters", "type fields, scanf function", "format specification fields for scanf function", "type fields"] -ms.assetid: 7e95de1b-0b71-4de3-9f81-c9560c78e039 --- -# Format Specification Fields: scanf and wscanf Functions +# Format specification fields: `scanf` and `wscanf` functions -The information here applies to the entire `scanf` family of functions, including the secure versions and describes the symbols used to tell the `scanf` functions how to parse the input stream, such as the input stream `stdin` for `scanf`, into values that are inserted into program variables. +The information here applies to the entire `scanf` family of functions, including the secure versions. It describes the symbols used to tell the `scanf` functions how to parse the input stream, such as the input stream `stdin`, into values that are inserted into program variables. -A format specification has the following form: +The `format` argument is a string that specifies the interpretation of the input and can contain one or more of: -`%`[`*`] [[width](../c-runtime-library/scanf-width-specification.md)] [{[h | l | ll | I64 | L](../c-runtime-library/scanf-width-specification.md)}][type](../c-runtime-library/scanf-type-field-characters.md) +- White-space characters: blank (` `); tab (`\t`); or newline (`\n`). A white-space character causes `scanf` to read, but not store, all consecutive white-space characters in the input up to the next non-white-space character. One white-space character in the format matches any number (including 0) and combination of white-space characters in the input. -The `format` argument specifies the interpretation of the input and can contain one or more of the following: +- Non-white-space characters, except for the percent sign (`%`). A non-white-space character causes `scanf` to read, but not store, a matching non-white-space character. If the next character in the input stream doesn't match, `scanf` terminates. -- White-space characters: blank (' '); tab ('\t'); or newline ('\n'). A white-space character causes `scanf` to read, but not store, all consecutive white-space characters in the input up to the next non-white-space character. One white-space character in the format matches any number (including 0) and combination of white-space characters in the input. +- Format specifications, introduced by the percent sign (`%`). A format specification causes `scanf` to read and convert characters in the input into a value of a specified type. The value is assigned to an argument in the argument list. -- Non-white-space characters, except for the percent sign (`%`). A non-white-space character causes `scanf` to read, but not store, a matching non-white-space character. If the next character in the input stream does not match, `scanf` terminates. + A format specification has the following form: -- Format specifications, introduced by the percent sign (`%`). A format specification causes `scanf` to read and convert characters in the input into values of a specified type. The value is assigned to an argument in the argument list. + > **`%`**\[**`*`**]\[***`width`***]\[{**`h`**\|**`l`**\|**`ll`**\|**`I64`**\|**`L`**}]***`type`*** -The format is read from left to right. Characters outside format specifications are expected to match the sequence of characters in the input stream; the matching characters in the input stream are scanned but not stored. If a character in the input stream conflicts with the format specification, `scanf` terminates, and the character is left in the input stream as if it had not been read. + Here, ***`width`***, **`h`**, **`l`**, **`ll`**, **`I64`**, and **`L`** represent a `scanf` [width specification](./scanf-width-specification.md), and ***`type`*** represents a `scanf` [type field character](./scanf-type-field-characters.md). -When the first format specification is encountered, the value of the first input field is converted according to this specification and stored in the location that is specified by the first `argument`. The second format specification causes the second input field to be converted and stored in the second `argument`, and so on through the end of the format string. +The `format` argument string is read from left to right. Characters outside format specifications are expected to match the sequence of characters in the input stream. The matching characters in the input stream are scanned but not stored. If a character in the input stream conflicts with the format specification, `scanf` terminates, and the character is left in the input stream as if it hadn't been read. -An input field is defined as all characters up to the first white-space character (space, tab, or newline), or up to the first character that cannot be converted according to the format specification, or until the field width (if specified) is reached. If there are too many arguments for the given specifications, the extra arguments are evaluated but ignored. The results are unpredictable if there are not enough arguments for the format specification. +When the first format specification is encountered, the value of the first input field is converted according to this specification. This value is stored in the location specified by the first argument that follows the `format` argument. The second format specification causes the second input field to be converted and stored in the next argument, and so on, through the end of the format string. + +An input field is defined as: All characters up to the first white-space character (space, tab, or newline), or up to the first character that can't be converted according to the format specification, or until the field width (if specified) is reached. If there are too many arguments for the given specifications, the extra arguments are evaluated but ignored. The results are unpredictable if there aren't enough arguments for the format specification. Each field of the format specification is a single character or a number signifying a particular format option. The `type` character, which appears after the last optional format field, determines whether the input field is interpreted as a character, a string, or a number. -The simplest format specification contains only the percent sign and a `type` character (for example, `%s`). If a percent sign (`%`) is followed by a character that has no meaning as a format-control character, that character and the following characters (up to the next percent sign) are treated as an ordinary sequence of characters, that is, a sequence of characters that must match the input. For example, to specify that a percent-sign character is to be input, use `%%`. +The simplest format specification contains only the percent sign and a `type` character (for example, `%s`). If a percent sign (`%`) is followed by a character that has no meaning as a format-control character, that character and the following characters (up to the next percent sign) are treated as an ordinary sequence of characters. That is, they're treated as a sequence of characters that must match the input. For example, to specify that a percent-sign character is to be input, use `%%`. -An asterisk (`*`) following the percent sign suppresses assignment of the next input field, which is interpreted as a field of the specified type. The field is scanned but not stored. +An asterisk (`*`) following the percent sign suppresses assignment of the next input field, which is interpreted as a field of the specified type. The field is scanned but not stored in an argument. -The secure versions (those with the `_s` suffix) of the `scanf` family of functions require that a buffer size parameter be passed immediately following each parameter of type `c`, `C`, `s`, `S` or `[`. For more information on the secure versions of the `scanf` family of functions, see [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). +The secure versions (the ones with the `_s` suffix) of the `scanf` family of functions require each parameter of type `c`, `C`, `s`, `S` or `[` to have a buffer size parameter passed immediately following. For more information on the secure versions of the `scanf` family of functions, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). ## See also -[scanf Width Specification](../c-runtime-library/scanf-width-specification.md)
-[scanf Type Field Characters](../c-runtime-library/scanf-type-field-characters.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[`scanf` Width specification](./scanf-width-specification.md)\ +[`scanf` Type field characters](./scanf-type-field-characters.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) diff --git a/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md b/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md index 3e089295b4..7b8fe37495 100644 --- a/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md +++ b/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md @@ -7,18 +7,18 @@ ms.assetid: 664b1717-2760-4c61-bd9c-22eee618d825 --- # Format specification syntax: `printf` and `wprintf` functions -The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](../c-runtime-library/stream-i-o.md). +The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](./stream-i-o.md). A conversion specification consists of optional and required fields in this form: -**%**[[*flags*](#flags)][[*width*](#width)][.[*precision*](#precision)][[*size*](#size)][*type*](#type) +> **%**\[[*flags*](#flags)\]\[[*width*](#width)\]\[.[*precision*](#precision)\]\[[*size*](#size)\][*type*](#type) -Each field of the conversion specification is a character or a number that signifies a particular format option or conversion specifier. The required *type* field specifies the kind of conversion to be applied to an argument. The optional *flags*, *width*, and *precision* fields control additional format aspects such as leading spaces or zeroes, justification, and displayed precision. The *size* field specifies the size of the argument consumed and converted. +Each field of the conversion specification is a character or a number that signifies a particular format option or conversion specifier. The required *type* field specifies the kind of conversion to be applied to an argument. The optional *flags*, *width*, and *precision* fields control other format aspects such as leading spaces or zeroes, justification, and displayed precision. The *size* field specifies the size of the argument consumed and converted. -A basic conversion specification contains only the percent sign and a *type* character. For example, `%s` specifies a string conversion. To print a percent-sign character, use `%%`. If a percent sign is followed by a character that has no meaning as a format field, the invalid parameter handler is invoked. For more information, see [Parameter Validation](../c-runtime-library/parameter-validation.md). +A basic conversion specification contains only the percent sign and a *type* character. For example, `%s` specifies a string conversion. To print a percent-sign character, use `%%`. If a percent sign is followed by a character that has no meaning as a format field, the invalid parameter handler is invoked. For more information, see [Parameter validation](./parameter-validation.md). > [!IMPORTANT] -> For security and stability, ensure that conversion specification strings are not user-defined. For example, consider a program that prompts the user to enter a name and stores the input in a string variable that's named `user_name`. To print `user_name`, do not do this: +> For security and stability, ensure that format conversion specification strings aren't end-user defined. For example, consider a program that prompts the user to enter a name and stores the input in a string variable that's named `user_name`. To print `user_name`, never do this: > > `printf( user_name ); /* Danger! If user_name contains "%s", program will crash */` > @@ -26,18 +26,16 @@ A basic conversion specification contains only the percent sign and a *type* cha > > `printf( "%s", user_name );` - - > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). -## Type conversion specifier +## Type conversion specifier The *type* conversion specifier character specifies whether to interpret the corresponding argument as a character, a string, a pointer, an integer, or a floating-point number. The *type* character is the only required conversion specification field, and it appears after any optional fields. -The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [size](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific. +The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [*size*](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific. For historical reasons, the `wprintf` functions use **`c`** and **`s`** to refer to `wchar_t` characters, and **`C`** and **`S`** specify narrow characters. -Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and **`long double`**, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **ll** or **I64** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform. +Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and `long double`, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **`ll`** or **`I64`** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform. > [!NOTE] > **Microsoft-specific:**\ @@ -45,82 +43,78 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` ### Type field characters -|Type character|Argument|Output format| -|--------------------|--------------|-------------------| -|**`c`**|Character|When used with `printf` functions, specifies a single-byte character; when used with `wprintf` functions, specifies a wide character.| -|**`C`**|Character|When used with `printf` functions, specifies a wide character; when used with `wprintf` functions, specifies a single-byte character.| -|**`d`**|Integer|Signed decimal integer.| -|**`i`**|Integer|Signed decimal integer.| -|**`o`**|Integer|Unsigned octal integer.| -|**`u`**|Integer|Unsigned decimal integer.| -|**`x`**|Integer|Unsigned hexadecimal integer; uses "`abcdef`".| -|**`X`**|Integer|Unsigned hexadecimal integer; uses "`ABCDEF`".| -|**`e`**|Floating-point|Signed value that has the form [-]*`d.dddd`*__e±__*`dd`*\[*`d`*], where *`d`* is one decimal digit, *`dddd`* is one or more decimal digits depending on the specified precision, or six by default, and *`dd`*\[*`d`*] is two or three decimal digits depending on the [output format](../c-runtime-library/set-output-format.md) and size of the exponent.| -|**`E`**|Floating-point|Identical to the **`e`** format except that **`E`** rather than **`e`** introduces the exponent.| -|**`f`**|Floating-point|Signed value that has the form [-]*`dddd`*__.__*`dddd`*, where *`dddd`* is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default.| -|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and nan output is capitalized.| -|**`g`**|Floating-point|Signed values are displayed in **`f`** or **`e`** format, whichever is more compact for the given value and precision. The **`e`** format is used only when the exponent of the value is less than -4 or greater than or equal to the *precision* argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.| -|**`G`**|Floating-point|Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate).| -|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0xh.hhhh*__p±__*`dd`*, where *h.hhhh* are the hex digits (using lower case letters) of the mantissa, and *`dd`* are one or more digits for the exponent. The precision specifies the number of digits after the point.| -|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0Xh.hhhh*__P±__*`dd`*, where *h.hhhh* are the hex digits (using capital letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point.| -|**`n`**|Pointer to integer|Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed at can be controlled by an argument size specification prefix. The **`n`** specifier is disabled by default; for information see the important security note.| -|**`p`**|Pointer type|Display the argument as an address in hexadecimal digits.| -|**`s`**|String|When used with `printf` functions, specifies a single-byte or multi-byte character string; when used with `wprintf` functions, specifies a wide-character string. Characters are displayed up to the first null character or until the *precision* value is reached.| -|**`S`**|String|When used with `printf` functions, specifies a wide-character string; when used with `wprintf` functions, specifies a single-byte or multi-byte character string. Characters are displayed up to the first null character or until the *precision* value is reached.| -|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [`ANSI_STRING`](/windows/win32/api/ntdef/ns-ntdef-string) or [`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, display the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **`w`** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.

Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`.| - -Starting in Visual Studio 2015, if the argument that corresponds to a floating-point conversion specifier (**`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, **`G`**) is infinite, indefinite, or NaN, the formatted output conforms to the C99 standard. This table lists the formatted output: - -|Value|Output| -|-----------|------------| -|infinity|`inf`| -|Quiet NaN|`nan`| -|Signaling NaN|`nan(snan)`| -|Indefinite NaN|`nan(ind)`| - -Any of these values may be prefixed by a sign. If a floating-point *type* conversion specifier character is a capital letter, then the output is also formatted in capital letters. For example, if the format specifier is `%F` instead of `%f`, an infinity is formatted as `INF` instead of `inf`. The `scanf` functions can also parse these strings, so these values can make a round trip through `printf` and `scanf` functions. +| Type character | Argument | Output format | +|---|---|---| +| **`c`** | Character | When used with `printf` functions, specifies a single-byte character; when used with `wprintf` functions, specifies a wide character. | +| **`C`** | Character | When used with `printf` functions, specifies a wide character; when used with `wprintf` functions, specifies a single-byte character. | +| **`d`** | Integer | Signed decimal integer. | +| **`i`** | Integer | Signed decimal integer. | +| **`o`** | Integer | Unsigned octal integer. | +| **`u`** | Integer | Unsigned decimal integer. | +| **`x`** | Integer | Unsigned hexadecimal integer; uses "`abcdef`". | +| **`X`** | Integer | Unsigned hexadecimal integer; uses "`ABCDEF`". | +| **`e`** | Floating-point | Signed value that has the form [`-`]*d.dddd*`e`\[`+`\|`-`]*dd*\[*d*], where *d* is one decimal digit, *dddd* is one or more decimal digits depending on the specified precision, or six by default, and *dd*\[*d*] is two or three decimal digits depending on the [output format](./set-output-format.md) and size of the exponent. | +| **`E`** | Floating-point | Identical to the **`e`** format except that **`E`** rather than **`e`** introduces the exponent. | +| **`f`** | Floating-point | Signed value that has the form [`-`]*dddd*`.`*dddd*, where *dddd* is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default. | +| **`F`** | Floating-point | Identical to the **`f`** format except that infinity and NaN output is capitalized. | +| **`g`** | Floating-point | Signed values are displayed in **`f`** or **`e`** format, whichever is more compact for the given value and precision. The **`e`** format is used only when the exponent of the value is less than -4 or greater than or equal to the *precision* argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it. | +| **`G`** | Floating-point | Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate). | +| **`a`** | Floating-point | Signed hexadecimal double-precision floating-point value that has the form [`-`]`0x`*h.hhhh*`p`\[`+`\|`-`]*dd*, where *h.hhhh* are the hex digits (using lower case letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point. | +| **`A`** | Floating-point | Signed hexadecimal double-precision floating-point value that has the form \[`-`]`0X`*h.hhhh*`P`\[`+`\|`-`]*dd*, where *h.hhhh* are the hex digits (using capital letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point. | +| **`n`** | Pointer to integer | Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed at can be controlled by an argument size specification prefix. The **`n`** specifier is disabled by default; for information see the important security note. | +| **`p`** | Pointer type | Display the argument as an address in hexadecimal digits. | +| **`s`** | String | When used with `printf` functions, specifies a single-byte or multi-byte character string; when used with `wprintf` functions, specifies a wide-character string. Characters are displayed up to the first null character or until the *precision* value is reached. | +| **`S`** | String | When used with `printf` functions, specifies a wide-character string; when used with `wprintf` functions, specifies a single-byte or multi-byte character string. Characters are displayed up to the first null character or until the *precision* value is reached. | +| **`Z`** | `ANSI_STRING` or `UNICODE_STRING` structure | **VS 2013 and earlier**
When the address of an [`ANSI_STRING`](/windows/win32/api/ntdef/ns-ntdef-string) or [`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, display the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **`w`** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.

**Universal C Runtime (UCRT)**
There is a known issue in the UCRT that is currently maintained for compatibility. Like the **`S`** specifier, the **`Z`** specifier without a size modifier prefix refers to a `UNICODE_STRING` when using a narrow printing function (like `printf`) and an `ANSI_STRING` when using a wide printing function (like `wprintf`).
Instead of **`Z`**, use **`hZ`** to specify an `ANSI_STRING`. **`wZ`** (or **`lZ`**) can still be used to specify a `UNICODE_STRING`.

Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`. | + +In Visual Studio 2015 and later versions, if the argument that corresponds to a floating-point conversion specifier (**`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, **`G`**) is infinite, indefinite, or NaN, the formatted output conforms to the C99 standard. This table lists the formatted output: + +| Value | Output | +|---|---| +| Infinity | `inf` | +| Quiet NaN | `nan` | +| Signaling NaN | `nan(snan)` | +| Indefinite NaN | `nan(ind)` | + +Any of these strings may be prefixed by a sign. If a floating-point *type* conversion specifier character is a capital letter, then the output is also formatted in capital letters. For example, if the format specifier is `%F` instead of `%f`, an infinity is formatted as `INF` instead of `inf`. The `scanf` functions can also parse these strings, so these values can make a round trip through `printf` and `scanf` functions. Before Visual Studio 2015, the CRT used a different, non-standard format for output of infinite, indefinite, and NaN values: -|Value|Output| -|-----------|------------| -|+ infinity|`1.#INF` *random-digits*| -|- infinity|`-1.#INF` *random-digits*| -|Indefinite (same as quiet NaN)|*digit* `.#IND` *random-digits*| -|NaN|*digit* `.#NAN` *random-digits*| +| Value | Output | +|---|---| +| + Infinity | `1.#INF` *random-digits* | +| - Infinity | `-1.#INF` *random-digits* | +| Indefinite (same as quiet NaN) | *digit* `.#IND` *random-digits* | +| NaN | *digit* `.#NAN` *random-digits* | -Any of these may have been prefixed by a sign, and may have been formatted differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)` prints `1.#J` because the *#INF* would be "rounded" to two digits of precision. +Any of these strings may have been prefixed by a sign, and may have been formatted differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)` prints `1.#J` because the *#INF* would be "rounded" to two digits of precision. > [!NOTE] > If the argument that corresponds to `%s` or `%S`, or the `Buffer` field of the argument that corresponds to `%Z`, is a null pointer, "(null)" is displayed. > [!NOTE] -> In all exponential formats, the minimum number of digits of exponent to display is two, using three only if necessary. By using the [`_set_output_format`](../c-runtime-library/set-output-format.md) function, you can set the number of digits displayed to three for backward compatibility with code written for Visual Studio 2013 and before. +> In all exponential formats, the minimum number of digits of exponent to display is two, using three only if necessary. By using the [`_set_output_format`](./set-output-format.md) function, you can set the number of digits displayed to three for backward compatibility with code written for Visual Studio 2013 and before. > [!IMPORTANT] -> Because the `%n` format is inherently insecure, it's disabled by default. If `%n` is encountered in a format string, the invalid parameter handler is invoked, as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). To enable `%n` support, see [`_set_printf_count_output`](../c-runtime-library/reference/set-printf-count-output.md). - - +> Because the `%n` format is inherently insecure, it's disabled by default. If `%n` is encountered in a format string, the invalid parameter handler is invoked, as described in [Parameter validation](./parameter-validation.md). To enable `%n` support, see [`_set_printf_count_output`](./reference/set-printf-count-output.md). -## Flag directives +## Flag directives -The first optional field in a conversion specification contains *flag directives*, zero or more flag characters that specify output justification and control output of signs, blanks, leading zeros, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a conversion specification, and the flag characters can appear in any order. +The first optional field in a conversion specification contains *flag directives*. This field contains zero or more flag characters that specify output justification and control output of signs, blanks, leading zeros, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a conversion specification, and the flag characters can appear in any order. ### Flag characters -|Flag|Meaning|Default| -|----------|-------------|-------------| -|**`-`**|Left align the result within the given field width.|Right align.| -|**`+`**|Use a sign (+ or -) to prefix the output value if it's of a signed type.|Sign appears only for negative signed values (-).| -|**`0`**|If *width* is prefixed by **`0`**, leading zeros are added until the minimum width is reached. If both **`0`** and **`-`** appear, the **`0`** is ignored. If **`0`** is specified for an integer format (**`i`**, **`u`**, **`x`**, **`X`**, **`o`**, **`d`**) and a precision specification is also present—for example, `%04.d`—the **`0`** is ignored. If **`0`** is specified for the **`a`** or **`A`** floating-point format, leading zeros are prepended to the mantissa, after the `0x` or `0X` prefix.|No padding.| -|**blank (' ')**|Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.| -|**`#`**|When it's used with the **`o`**, **`x`**, or **`X`** format, the **`#`** flag uses `0`, `0x`, or `0X`, respectively, to prefix any nonzero output value.|No prefix appears.| -||When it's used with the **`e`**, **`E`**, **`f`**, **`F`**, **`a`**, or **`A`** format, the **`#`** flag forces the output value to contain a decimal point.|Decimal point appears only if digits follow it.| -||When it's used with the **`g`** or **`G`** format, the **`#`** flag forces the output value to contain a decimal point and prevents the truncation of trailing zeros.

Ignored when used with **`c`**, **`d`**, **`i`**, **`u`**, or **`s`**.|Decimal point appears only if digits follow it. Trailing zeros are truncated.| - - +| Flag | Meaning | Default | +|---|---|---| +| **`-`** | Left align the result within the given field width. | Right align. | +| **`+`** | Use a sign (+ or -) to prefix the output value if it's of a signed type. | Sign appears only for negative signed values (-). | +| **`0`** | If *width* is prefixed by **`0`**, leading zeros are added until the minimum width is reached. If both **`0`** and **`-`** appear, the **`0`** is ignored. If **`0`** is specified for an integer format (**`i`**, **`u`**, **`x`**, **`X`**, **`o`**, **`d`**) and a precision specification is also present—for example, `%04.d`—the **`0`** is ignored. If **`0`** is specified for the **`a`** or **`A`** floating-point format, leading zeros are prepended to the mantissa, after the `0x` or `0X` prefix. | No padding. | +| **blank (' ')** | Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear. | No blank appears. | +| **`#`** | When it's used with the **`o`**, **`x`**, or **`X`** format, the **`#`** flag uses `0`, `0x`, or `0X`, respectively, to prefix any nonzero output value. | No prefix appears. | +| | When it's used with the **`e`**, **`E`**, **`f`**, **`F`**, **`a`**, or **`A`** format, the **`#`** flag forces the output value to contain a decimal point. | Decimal point appears only if digits follow it. | +| | When it's used with the **`g`** or **`G`** format, the **`#`** flag forces the output value to contain a decimal point and prevents the truncation of trailing zeros.

Ignored when used with **`c`**, **`d`**, **`i`**, **`u`**, or **`s`**. | Decimal point appears only if digits follow it. Trailing zeros are truncated. | -## Width specification +## Width specification In a conversion specification, the optional width specification field appears after any *flags* characters. The *`width`* argument is a non-negative decimal integer that controls the minimum number of characters that are output. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values—depending on whether the left-alignment flag (**`-`**) is specified—until the minimum width is reached. If *`width`* is prefixed by 0, leading zeros are added to integer or floating-point conversions until the minimum width is reached, except when conversion is to an infinity or `NaN`. @@ -132,9 +126,7 @@ If the width specification is an asterisk (`*`), an `int` argument from the argu A missing or small *`width`* value in a conversion specification doesn't cause the truncation of an output value. If the result of a conversion is wider than the *`width`* value, the field expands to contain the conversion result. - - -## Precision specification +## Precision specification In a conversion specification, the third optional field is the precision specification. It consists of a period (`.`) followed by a non-negative decimal integer that, depending on the conversion type, specifies the number of string characters, the number of decimal places, or the number of significant digits to be output. @@ -148,44 +140,42 @@ If the precision specification is an asterisk (`*`), an `int` argument from the The *`type`* character determines either the interpretation of *`precision`* or the default precision when *`precision`* is omitted, as shown in the following table. -### How Precision Values Affect Type - -|Type|Meaning|Default| -|----------|-------------|-------------| -|**`a`**, **`A`**|The precision specifies the number of digits after the point.|Default precision is 13. If precision is 0, no decimal point is printed unless the **`#`** flag is used.| -|**`c`**, **`C`**|The precision has no effect.|Character is printed.| -|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, **`X`**|The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than *precision*, the output value is padded on the left with zeros. The value isn't truncated when the number of digits exceeds *precision*.|Default precision is 1.| -|**`e`**, **`E`**|The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.|Default precision is 6. If *precision* is 0 or the period (`.`) appears without a number following it, no decimal point is printed.| -|**`f`**, **`F`**|The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.|Default precision is 6. If *precision* is 0, or if the period (`.`) appears without a number following it, no decimal point is printed.| -|**`g`**, **`G`**|The precision specifies the maximum number of significant digits printed.|Six significant digits are printed, and any trailing zeros are truncated.| -|**`s`**, **`S`**|The precision specifies the maximum number of characters to be printed. Characters in excess of *precision* aren't printed.|Characters are printed until a null character is found.| +### How precision values affect type - +| Type | Meaning | Default | +|---|---|---| +| **`a`**, **`A`** | The precision specifies the number of digits after the point. | Default precision is 13. If precision is 0, no decimal point is printed unless the **`#`** flag is used. | +| **`c`**, **`C`** | The precision has no effect. | Character is printed. | +| **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, **`X`** | The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than *precision*, the output value is padded on the left with zeros. The value isn't truncated when the number of digits exceeds *precision*. | Default precision is 1. | +| **`e`**, **`E`** | The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. | Default precision is 6. If *precision* is 0 or the period (`.`) appears without a number following it, no decimal point is printed. | +| **`f`**, **`F`** | The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. | Default precision is 6. If *precision* is 0, or if the period (`.`) appears without a number following it, no decimal point is printed. | +| **`g`**, **`G`** | The precision specifies the maximum number of significant digits printed. | Six significant digits are printed, and any trailing zeros are truncated. | +| **`s`**, **`S`** | The precision specifies the maximum number of characters to be printed. Characters in excess of *precision* aren't printed. | Characters are printed until a null character is found. | -## Argument size specification +## Argument size specification In a conversion specification, the *size* field is an argument length modifier for the *type* conversion specifier. The *size* field prefixes to the *type* field—**`hh`**, **`h`**, **`j`**, **`l`** (lowercase L), **`L`**, **`ll`**, **`t`**, **`w`**, **`z`**, **`I`** (uppercase i), **`I32`**, and **`I64`**—specify the "size" of the corresponding argument—long or short, 32-bit or 64-bit, single-byte character or wide character—depending on the conversion specifier that they modify. These size prefixes are used with *type* characters in the `printf` and `wprintf` families of functions to specify the interpretation of argument sizes, as shown in the following table. The *size* field is optional for some argument types. When no size prefix is specified, the formatter consumes integer arguments—for example, signed or unsigned `char`, `short`, `int`, `long`, and enumeration types—as 32-bit `int` types, and `float`, `double`, and `long double` floating-point arguments are consumed as 64-bit `double` types. This behavior matches the default argument promotion rules for variable argument lists. For more information about argument promotion, see Ellipsis and Default Arguments in [Postfix expressions](../cpp/postfix-expressions.md). On both 32-bit and 64-bit systems, the conversion specification of a 64-bit integer argument must include a size prefix of **`ll`** or **`I64`**. Otherwise, the behavior of the formatter is undefined. Some types are different sizes in 32-bit and 64-bit code. For example, `size_t` is 32 bits long in code compiled for x86, and 64 bits in code compiled for x64. To create platform-agnostic formatting code for variable-width types, you can use a variable-width argument size modifier. Instead, use a 64-bit argument size modifier and explicitly promote the variable-width argument type to 64 bits. The Microsoft-specific **`I`** (uppercase i) argument size modifier handles variable-width integer arguments, but we recommend the type-specific **`j`**, **`t`**, and **`z`** modifiers for portability. -### Size Prefixes for printf and wprintf Format-Type Specifiers - -|To specify|Use prefix|With type specifier| -|----------------|----------------|-------------------------| -|`char`
`unsigned char`|**`hh`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`short int`
`short unsigned int`|**`h`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`__int32`
`unsigned __int32`|**`I32`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`__int64`
`unsigned __int64`|**`I64`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`intmax_t`
`uintmax_t`|**`j`** or **`I64`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`long double`|**`l`** (lowercase L) or **`L`**|**`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, or **`G`**| -|`long int`
`long unsigned int`|**`l`** (lowercase L) |**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | -|`long long int`
`unsigned long long int`|**`ll`** (lowercase LL)|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`ptrdiff_t`|**`t`** or **`I`** (uppercase i)|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|`size_t`|**`z`** or **`I`** (uppercase i)|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|Single-byte character|**`h`**|**`c`** or **`C`**| -|Wide character|**`l`** (lowercase L) or **`w`**|**`c`** or **`C`**| -|Single-byte character string|**`h`**|**`s`**, **`S`**, or **`Z`**| -|Wide-character string|**`l`** (lowercase L) or **`w`**|**`s`**, **`S`**, or **`Z`**| +### Size prefixes for printf and wprintf format-type specifiers + +| To specify | Use prefix | With type specifier | +|---|---|---| +| `char`
`unsigned char` | **`hh`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `short int`
`short unsigned int` | **`h`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `__int32`
`unsigned __int32` | **`I32`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `__int64`
`unsigned __int64` | **`I64`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `intmax_t`
`uintmax_t` | **`j`** or **`I64`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `long double` | **`l`** (lowercase L) or **`L`** | **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, or **`G`** | +| `long int`
`long unsigned int` | **`l`** (lowercase L) | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `long long int`
`unsigned long long int` | **`ll`** (lowercase LL) | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `ptrdiff_t` | **`t`** or **`I`** (uppercase i) | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| `size_t` | **`z`** or **`I`** (uppercase i) | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| Single-byte character | **`h`** | **`c`** or **`C`** | +| Wide character | **`l`** (lowercase L) or **`w`** | **`c`** or **`C`** | +| Single-byte character string | **`h`** | **`s`**, **`S`**, or **`Z`** | +| Wide-character string | **`l`** (lowercase L) or **`w`** | **`s`**, **`S`**, or **`Z`** | The `ptrdiff_t` and `size_t` types are `__int32` or `unsigned __int32` on 32-bit platforms, and `__int64` or `unsigned __int64` on 64-bit platforms. The **`I`** (uppercase i), **`j`**, **`t`**, and **`z`** size prefixes take the correct argument width for the platform. @@ -199,6 +189,6 @@ An **`hc`** or **`hC`** type specifier is synonymous with **`c`** in `printf` fu ## See also -[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)\ -[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ -[`printf_p` Positional Parameters](../c-runtime-library/printf-p-positional-parameters.md) +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md)\ +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`printf_p` Positional Parameters](./printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/freeentry-usedentry.md b/docs/c-runtime-library/freeentry-usedentry.md index 3fd34d2972..e6dd6248f6 100644 --- a/docs/c-runtime-library/freeentry-usedentry.md +++ b/docs/c-runtime-library/freeentry-usedentry.md @@ -2,23 +2,23 @@ description: "Learn more about: _FREEENTRY, _USEDENTRY" title: "_FREEENTRY, _USEDENTRY" ms.date: "11/04/2016" -f1_keywords: ["USEDENTRY", "_USEDENTRY", "_FREEENTRY", "FREEENTRY"] +f1_keywords: ["MALLOC/_USEDENTRY", "MALLOC/_FREEENTRY", "_USEDENTRY", "_FREEENTRY", "USEDENTRY", "FREEENTRY"] helpviewer_keywords: ["_USEDENTRY constant", "_FREEENTRY constant", "FREEENTRY constant", "USEDENTRY constant"] ms.assetid: 26f658e6-6846-4a4e-9984-262cfe392770 --- -# _FREEENTRY, _USEDENTRY +# `_FREEENTRY`, `_USEDENTRY` ## Syntax -``` +```C #include ``` ## Remarks -These constants represent values assigned by the `_heapwalk` routines to the **_useflag** element of the **_HEAPINFO** structure. They indicate the status of the heap entry. +These constants represent values assigned by the `_heapwalk` routines to the `_useflag` element of the `_HEAPINFO` structure. They indicate the status of the heap entry. ## See also -[_heapwalk](../c-runtime-library/reference/heapwalk.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_heapwalk`](./reference/heapwalk.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/fseek-lseek-constants.md b/docs/c-runtime-library/fseek-lseek-constants.md index ca5be7933d..8218c3ace8 100644 --- a/docs/c-runtime-library/fseek-lseek-constants.md +++ b/docs/c-runtime-library/fseek-lseek-constants.md @@ -2,30 +2,30 @@ description: "Learn more about: fseek, _lseek Constants" title: "fseek, _lseek Constants" ms.date: "11/04/2016" -f1_keywords: ["SEEK_END", "SEEK_SET", "SEEK_CUR"] +f1_keywords: ["STDIO/SEEK_END", "STDIO/SEEK_SET", "STDIO/SEEK_CUR", "SEEK_END", "SEEK_SET", "SEEK_CUR"] helpviewer_keywords: ["SEEK_SET constant", "SEEK_END constant", "SEEK_CUR constant"] ms.assetid: 9deeb13e-5aa3-4c33-80d8-721c80a4de9d --- -# fseek, _lseek Constants +# `fseek`, `_lseek` constants ## Syntax -``` +```C #include ``` ## Remarks -The *origin* argument specifies the initial position and can be one of the following manifest constants: +The *`origin`* argument specifies the initial position and can be one of the following manifest constants: -|Constant|Meaning| -|--------------|-------------| -|`SEEK_END`|End of file| -|`SEEK_CUR`|Current position of file pointer| -|`SEEK_SET`|Beginning of file| +| Constant | Meaning | +|---|---| +| `SEEK_END` | End of file | +| `SEEK_CUR` | Current position of file pointer | +| `SEEK_SET` | Beginning of file | ## See also -[fseek, _fseeki64](../c-runtime-library/reference/fseek-fseeki64.md)
-[_lseek, _lseeki64](../c-runtime-library/reference/lseek-lseeki64.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`fseek`, `_fseeki64`](./reference/fseek-fseeki64.md)\ +[`_lseek`, `_lseeki64`](./reference/lseek-lseeki64.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/function-family-overviews.md b/docs/c-runtime-library/function-family-overviews.md index d8fa708dd7..c6223a9cc1 100644 --- a/docs/c-runtime-library/function-family-overviews.md +++ b/docs/c-runtime-library/function-family-overviews.md @@ -10,7 +10,7 @@ This section lists C runtime library routines by function family. ## CRT library routine families -[_exec, _wexec](exec-wexec-functions.md)\ +[`_exec`, `_wexec`](exec-wexec-functions.md)\ Functions to load and execute a new process. [Filename search functions](filename-search-functions.md)\ @@ -23,7 +23,7 @@ Describes the format string and arguments for `printf` and `wprintf`. Describes the format specification fields for parsing an input stream for the entire `scanf` family of functions. [`is`, `isw` functions](is-isw-routines.md)\ -Functions for testing characters for things like whether they are uppercase, ASCII, numeric, punctuation, and so on. +Functions for testing characters for things like whether they're uppercase, ASCII, numeric, punctuation, and so on. [`_ismbb` functions](ismbb-routines.md)\ Functions for testing an integer value for whether it represents an alpha character, blank character, a print character, and so on. @@ -32,13 +32,13 @@ Functions for testing an integer value for whether it represents an alpha charac Functions for testing a multibyte character for whether it represents an alpha character, blank character, a print character, and so on. [operator `delete` (CRT)](delete-operator-crt.md)\ -Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator delete function. It is now part of the C++ Standard Library. +Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator delete function. It's now part of the C++ Standard Library. [operator `new` (CRT)](new-operator-crt.md)\ -Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator new function. It is now part of the C++ Standard Library. +Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator new function. It's now part of the C++ Standard Library. [`printf` positional parameter functions](printf-p-positional-parameters.md)\ -Positional parameters specify by number which of the arguments is to be substituted into a field in a format string. +Positional parameters specify by number the argument to substitute into a field in a format string. [`scanf` type field characters](scanf-type-field-characters.md)\ The type character determines whether the associated argument is interpreted as a character, string, or number for any of the `scanf` family of functions, including the secure versions, such as `scanf_s`. @@ -56,7 +56,7 @@ The `strcoll` and `wcscoll` functions compare two strings according to the `LC_C The `strtod` family of functions convert a null-terminated string to a numeric value. [`vprintf` functions](vprintf-functions.md)\ -The `vprintf` functions take a pointer to an argument list, formats it, and writes the result to the specified destination. The functions differ in the parameter validation performed, whether they take wide or single-byte character strings, the output destination, and support for specifying the order in which parameters are used in the format string. +The `vprintf` functions take a pointer to an argument list, format it, and write the result to the specified destination. The functions differ in several ways: the parameter validation performed; whether they take wide or single-byte character strings; the output destination; and support for specifying the order in which parameters are used in the format string. ## See also diff --git a/docs/c-runtime-library/generic-text-mappings.md b/docs/c-runtime-library/generic-text-mappings.md index 583bbc5975..ada65a3cd9 100644 --- a/docs/c-runtime-library/generic-text-mappings.md +++ b/docs/c-runtime-library/generic-text-mappings.md @@ -6,19 +6,19 @@ f1_keywords: ["c.mappings"] helpviewer_keywords: ["generic-text mappings", "mappings, generic-text"] ms.assetid: 1ed02e02-3649-42dd-a697-e1b4af25bb02 --- -# Generic-Text Mappings +# Generic-text mappings To simplify writing code for international markets, generic-text mappings are defined in TCHAR.H for: -- [Data types](../c-runtime-library/data-type-mappings.md) +- [Data types](./data-type-mappings.md) -- [Constants and global variables](../c-runtime-library/constant-and-global-variable-mappings.md) +- [Constants and global variables](./constant-and-global-variable-mappings.md) -- [Routine mappings](../c-runtime-library/routine-mappings.md) +- [Routine mappings](./routine-mappings.md) -For more information, see [Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md). Generic-text mappings are Microsoft extensions that are not ANSI compatible. +For more information, see [Using generic-text mappings](./using-generic-text-mappings.md). Generic-text mappings are Microsoft extensions that aren't ANSI compatible. ## See also -[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md) +[Data type mappings](./data-type-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md) diff --git a/docs/c-runtime-library/get-output-format.md b/docs/c-runtime-library/get-output-format.md index 9a5ea52f24..ae1ddd4667 100644 --- a/docs/c-runtime-library/get-output-format.md +++ b/docs/c-runtime-library/get-output-format.md @@ -10,7 +10,7 @@ f1_keywords: ["get_output_format", "_get_output_format"] helpviewer_keywords: ["output formatting", "get_output_format function", "_get_output_format function"] ms.assetid: 0ce42f3b-3479-41c4-bcbf-1d21f7ee37e7 --- -# _get_output_format +# `_get_output_format` Gets the current value of the output format flag. @@ -19,29 +19,29 @@ Gets the current value of the output format flag. ## Syntax -``` +```C unsigned int _get_output_format(); ``` -## Return Value +## Return value The current value of the output format flag. ## Remarks -The output format flag controls features of formatted I/O. At present the flag has two possible values: 0 and `_TWO_DIGIT_EXPONENT`. If `_TWO_DIGIT_EXPONENT` is set, the floating point numbers is printed with only two digits in the exponent unless a third digit is required by the size of the exponent. If the flag is zero, the floating point output displays three digits of exponent, using zeroes if necessary to pad the value to three digits. +The output format flag controls features of formatted I/O. The flag has two possible values: 0 and `_TWO_DIGIT_EXPONENT`. If `_TWO_DIGIT_EXPONENT` is set, the floating point number is printed with only two digits in the exponent unless a third digit is required by the size of the exponent. If the flag is zero, the floating point output displays three digits of exponent, using zeroes if necessary to pad the value to three digits. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_get_output_format`|\| +| Routine | Required header | +|---|---| +| **`_get_output_format`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## See also -[Format Specification Syntax: printf and wprintf Functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)
-[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)
-[_set_output_format](../c-runtime-library/set-output-format.md) +[Format specification syntax: `printf` and `wprintf` functions](./format-specification-syntax-printf-and-wprintf-functions.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md)\ +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`_set_output_format`](./set-output-format.md) diff --git a/docs/c-runtime-library/getmainargs-wgetmainargs.md b/docs/c-runtime-library/getmainargs-wgetmainargs.md index 5ae0fde552..a5a8f96735 100644 --- a/docs/c-runtime-library/getmainargs-wgetmainargs.md +++ b/docs/c-runtime-library/getmainargs-wgetmainargs.md @@ -10,7 +10,7 @@ f1_keywords: ["__wgetmainargs", "__getmainargs"] helpviewer_keywords: ["__wgetmainargs", "__getmainargs"] ms.assetid: f72f54eb-9509-4bdf-8752-40fc49055439 --- -# __getmainargs, __wgetmainargs +# `__getmainargs`, `__wgetmainargs` Invokes command-line parsing and copies the arguments to `main()` back through the passed pointers. @@ -18,48 +18,48 @@ Invokes command-line parsing and copies the arguments to `main()` back through t ```cpp int __getmainargs( - int * _Argc, - char *** _Argv, - char *** _Env, - int _DoWildCard, -_startupinfo * _StartInfo); + int * argc, + char *** argv, + char *** env, + int doWildCard, +_startupinfo * startInfo); int __wgetmainargs ( - int *_Argc, - wchar_t ***_Argv, - wchar_t ***_Env, - int _DoWildCard, - _startupinfo * _StartInfo) + int *argc, + wchar_t ***argv, + wchar_t ***env, + int doWildCard, + _startupinfo * startInfo) ``` #### Parameters -`_Argc`
+*`argc`*\ An integer that contains the number of arguments that follow in `argv`. The `argc` parameter is always greater than or equal to 1. -`_Argv`
-An array of null-terminated strings representing command-line arguments entered by the user of the program. By convention, `argv[0]` is the command with which the program is invoked, argv[1] is the first command-line argument, and so on, until argv[argc], which is always **NULL**. The first command-line argument is always `argv[1]` and the last one is `argv[argc - 1]`. +*`argv`*\ +An array of null-terminated strings representing command-line arguments entered by the user of the program. By convention, `argv[0]` is the command with which the program is invoked, argv[1] is the first command-line argument, and so on, until argv[argc], which is always `NULL`. The first command-line argument is always `argv[1]` and the last one is `argv[argc - 1]`. -`_Env`
-An array of strings that represent the variables set in the user's environment. This array is terminated by a **NULL** entry. +*`env`*\ +An array of strings that represent the variables set in the user's environment. This array is terminated by a `NULL` entry. -`_DoWildCard`
+*`doWildCard`*\ An integer that if set to 1 expands the wildcards in the command line arguments, or if set to 0 does nothing. -`_StartInfo`
+*`startInfo`*\ Other information to be passed to the CRT DLL. -## Return Value +## Return value 0 if successful; a negative value if unsuccessful. ## Remarks -Use `__getmainargs` on non-wide character platforms, and `__wgetmainargs` on wide-character (Unicode) platforms. +Use **`__getmainargs`** on non-wide character platforms, and **`__wgetmainargs`** on wide-character (Unicode) platforms. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__getmainargs|internal.h| -|__wgetmainargs|internal.h| +| Routine | Required header | +|---|---| +| **`__getmainargs`** | `internal.h` | +| **`__wgetmainargs`** | `internal.h` | diff --git a/docs/c-runtime-library/gets-getws.md b/docs/c-runtime-library/gets-getws.md index 0f316ad0e1..f3da079669 100644 --- a/docs/c-runtime-library/gets-getws.md +++ b/docs/c-runtime-library/gets-getws.md @@ -3,7 +3,7 @@ description: "Learn more about: gets, _getws" title: "gets, _getws" ms.date: "4/2/2020" api_name: ["_getws", "gets", "_o__getws", "_o_gets"] -api_location: ["msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getts", "gets", "_getws"] @@ -11,17 +11,17 @@ helpviewer_keywords: ["getws function", "getts function", "_getws function", "li --- # `gets`, `_getws` -Gets a line from the `stdin` stream. More secure versions of these functions are available; see [`gets_s`, `_getws_s`](../c-runtime-library/reference/gets-s-getws-s.md). +Gets a line from the **`stdin`** stream. More secure versions of these functions are available; see [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md). > [!IMPORTANT] -> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, `gets_s` and `_getws_s`, are still available. For information on these alternative functions, see [`gets_s`, `_getws_s`](../c-runtime-library/reference/gets-s-getws-s.md). +> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, `gets_s` and `_getws_s`, are still available. For information on these alternative functions, see [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax -``` +```C char *gets( char *buffer ); @@ -38,40 +38,40 @@ wchar_t *_getws( ); // C++ only ``` -#### Parameters +### Parameters *`buffer`*\ Storage location for input string. -## Return Value +## Return value -Returns its argument if successful. A **`NULL`** pointer indicates an error or end-of-file condition. Use [`ferror`](../c-runtime-library/reference/ferror.md) or [`feof`](../c-runtime-library/reference/feof.md) to determine which one has occurred. If `buffer` is **`NULL`**, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`NULL`** and set `errno` to `EINVAL`. +Returns its argument if successful. A `NULL` pointer indicates an error or end-of-file condition. Use [`ferror`](./reference/ferror.md) or [`feof`](./reference/feof.md) to determine which one has occurred. If *`buffer`* is `NULL`, these functions invoke an invalid parameter handler, as described in [Parameter validation](./parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set `errno` to `EINVAL`. ## Remarks -The `gets` function reads a line from the standard input stream `stdin` and stores it in `buffer`. The line consists of all characters up to and including the first newline character ('\n'). `gets` then replaces the newline character with a null character ('\0') before returning the line. In contrast, the `fgets` function retains the newline character. `_getws` is a wide-character version of `gets`; its argument and return value are wide-character strings. +The **`gets`** function reads a line from the standard input stream **`stdin`** and stores it in *`buffer`*. The line consists of all characters up to and including the first newline character ('\n'). **`gets`** then replaces the newline character with a null character ('\0') before returning the line. In contrast, the `fgets` function retains the newline character. **`_getws`** is a wide-character version of **`gets`**; its argument and return value are wide-character strings. > [!IMPORTANT] -> Because there is no way to limit the number of characters read by `gets`, untrusted input can easily cause buffer overruns. Use `fgets` instead. +> Because there is no way to limit the number of characters read by **`gets`**, untrusted input can easily cause buffer overruns. Use `fgets` instead. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](./secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_getts`|`gets`|`gets`|`_getws`| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_getts` | **`gets`** | **`gets`** | **`_getws`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`gets`|``| -|`_getws`|`` or ``| +| Routine | Required header | +|---|---| +| **`gets`** | `` | +| **`_getws`** | `` or `` | -For additional compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Example @@ -91,7 +91,7 @@ int main( void ) } ``` -Note that input longer than 20 characters will overrun the line buffer and almost certainly cause the program to crash. +Input longer than 20 characters will overrun the line buffer and almost certainly cause the program to crash. ```Output @@ -100,7 +100,7 @@ Hello there!The line entered was: Hello there! ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)\ -[`fgets`, `fgetws`](../c-runtime-library/reference/fgets-fgetws.md)\ -[`fputs`, `fputws`](../c-runtime-library/reference/fputs-fputws.md)\ -[`puts`, `_putws`](../c-runtime-library/reference/puts-putws.md) +[Stream I/O](./stream-i-o.md)\ +[`fgets`, `fgetws`](./reference/fgets-fgetws.md)\ +[`fputs`, `fputws`](./reference/fputs-fputws.md)\ +[`puts`, `_putws`](./reference/puts-putws.md) diff --git a/docs/c-runtime-library/global-constants.md b/docs/c-runtime-library/global-constants.md index e836c8345c..1feefd8f3e 100644 --- a/docs/c-runtime-library/global-constants.md +++ b/docs/c-runtime-library/global-constants.md @@ -6,65 +6,61 @@ f1_keywords: ["c.constants"] helpviewer_keywords: ["global constants"] ms.assetid: 778d86fd-3ca6-4d2b-b4c5-aee6dc1efe6b --- -# Global Constants +# Global constants -The Microsoft run-time library contains definitions for global constants used by library routines. To use these constants, include the appropriate header files as indicated in the description for each constant. The global constants are listed in the following table. +The Microsoft run-time library contains definitions for global constants used by library routines. To use these constants, include the appropriate header files as indicated in the description for each constant. The global constant articles follow in this section. -:::row::: - :::column span=""::: - [32-Bit Windows Time/Date Formats](../c-runtime-library/32-bit-windows-time-date-formats.md)\ - [BUFSIZ](../c-runtime-library/bufsiz.md)\ - [CLOCKS_PER_SEC, CLK_TCK](../c-runtime-library/clocks-per-sec-clk-tck.md)\ - [Commit-To-Disk Constants](../c-runtime-library/commit-to-disk-constants.md)\ - [_CRT_DISABLE_PERFCRIT_LOCKS](../c-runtime-library/crt-disable-perfcrit-locks.md)\ - [Data Type Constants](../c-runtime-library/data-type-constants.md)\ - [Environmental Constants](../c-runtime-library/environmental-constants.md)\ - [EOF, WEOF](../c-runtime-library/eof-weof.md)\ - [errno Constants](../c-runtime-library/errno-constants.md)\ - [Exception-Handling Constants](../c-runtime-library/exception-handling-constants.md)\ - [EXIT_SUCCESS, EXIT_FAILURE](../c-runtime-library/exit-success-exit-failure.md)\ - [File Attribute Constants](../c-runtime-library/file-attribute-constants.md)\ - [File Constants](../c-runtime-library/file-constants.md)\ - [File Permission Constants](../c-runtime-library/file-permission-constants.md)\ - [File Read/Write Access Constants](../c-runtime-library/file-read-write-access-constants.md)\ - [File Translation Constants](../c-runtime-library/file-translation-constants.md)\ - [FILENAME_MAX](../c-runtime-library/filename-max.md)\ - [FOPEN_MAX, _SYS_OPEN](../c-runtime-library/fopen-max-sys-open.md)\ - [_FREEENTRY, _USEDENTRY](../c-runtime-library/freeentry-usedentry.md)\ - [fseek, _lseek Constants](../c-runtime-library/fseek-lseek-constants.md)\ - [Heap Constants](../c-runtime-library/heap-constants.md)\ - [_HEAP_MAXREQ](../c-runtime-library/heap-maxreq.md)\ - [HUGE_VAL, _HUGE](../c-runtime-library/huge-val-huge.md) - :::column-end::: - :::column span=""::: - [Locale Categories](../c-runtime-library/locale-categories.md)\ - [_locking Constants](../c-runtime-library/locking-constants.md)\ - [Math Constants](../c-runtime-library/math-constants.md)\ - [Math Error Constants](../c-runtime-library/math-error-constants.md)\ - [_MAX_ENV](../c-runtime-library/max-env.md)\ - [MB_CUR_MAX](../c-runtime-library/mb-cur-max.md)\ - [NULL](../c-runtime-library/null-crt.md)\ - [Path Field Limits](../c-runtime-library/path-field-limits.md)\ - [RAND_MAX](../c-runtime-library/rand-max.md)\ - [setvbuf Constants](../c-runtime-library/setvbuf-constants.md)\ - [Sharing Constants](../c-runtime-library/sharing-constants.md)\ - [signal Constants](../c-runtime-library/signal-constants.md)\ - [signal Action Constants](../c-runtime-library/signal-action-constants.md)\ - [spawn Constants](../c-runtime-library/spawn-constants.md)\ - [_stat Structure st_mode Field Constants](../c-runtime-library/stat-structure-st-mode-field-constants.md)\ - [stdin, stdout, stderr](../c-runtime-library/stdin-stdout-stderr.md)\ - [TMP_MAX, L_tmpnam](../c-runtime-library/tmp-max-l-tmpnam.md)\ - [Translation Mode Constants](../c-runtime-library/translation-mode-constants.md)\ - [_TRUNCATE](../c-runtime-library/truncate.md)\ - [TZNAME_MAX](../c-runtime-library/tzname-max.md)\ - [_WAIT_CHILD, _WAIT_GRANDCHILD](../c-runtime-library/wait-child-wait-grandchild.md)\ - [WCHAR_MAX](../c-runtime-library/wchar-max.md)\ - [WCHAR_MIN](../c-runtime-library/wchar-min.md) - :::column-end::: -:::row-end::: +## Global constant articles + +[32-Bit Windows Time/Date Formats](./32-bit-windows-time-date-formats.md)\ +[`BUFSIZ`](./bufsiz.md)\ +[`CLOCKS_PER_SEC`, `CLK_TCK`](./clocks-per-sec-clk-tck.md)\ +[Commit-to-disk constants](./commit-to-disk-constants.md)\ +[`_CRT_DISABLE_PERFCRIT_LOCKS`](./crt-disable-perfcrit-locks.md)\ +[Data type constants](./data-type-constants.md)\ +[Environmental constants](./environmental-constants.md)\ +[`EOF`, `WEOF`](./eof-weof.md)\ +[`errno` constants](./errno-constants.md)\ +[Exception-handling constants](./exception-handling-constants.md)\ +[`EXIT_SUCCESS`, `EXIT_FAILURE`](./exit-success-exit-failure.md)\ +[File attribute constants](./file-attribute-constants.md)\ +[File constants](./file-constants.md)\ +[File permission constants](./file-permission-constants.md)\ +[File read/write access constants](./file-read-write-access-constants.md)\ +[File translation constants](./file-translation-constants.md)\ +[`FILENAME_MAX`](./filename-max.md)\ +[`FOPEN_MAX`, `_SYS_OPEN`](./fopen-max-sys-open.md)\ +[`_FREEENTRY`, `_USEDENTRY`](./freeentry-usedentry.md)\ +[`fseek`, `_lseek` constants](./fseek-lseek-constants.md)\ +[Heap constants](./heap-constants.md)\ +[`_HEAP_MAXREQ`](./heap-maxreq.md)\ +[`HUGE_VAL`, `_HUGE`](./huge-val-huge.md)\ +[Locale categories](./locale-categories.md)\ +[`_locking` constants](./locking-constants.md)\ +[Math constants](./math-constants.md)\ +[Math error constants](./math-error-constants.md)\ +[`_MAX_ENV`](./max-env.md)\ +[`MB_CUR_MAX`](./mb-cur-max.md)\ +[`NULL`](./null-crt.md)\ +[Path field limits](./path-field-limits.md)\ +[`RAND_MAX`](./rand-max.md)\ +[`setvbuf` constants](./setvbuf-constants.md)\ +[Sharing constants](./sharing-constants.md)\ +[`signal` constants](./signal-constants.md)\ +[`signal` action constants](./signal-action-constants.md)\ +[`spawn` constants](./spawn-constants.md)\ +[`_stat` structure `st_mode` field constants](./stat-structure-st-mode-field-constants.md)\ +[`stdin`, `stdout`, `stderr`](./stdin-stdout-stderr.md)\ +[`TMP_MAX`, `L_tmpnam`](./tmp-max-l-tmpnam.md)\ +[Translation mode constants](./translation-mode-constants.md)\ +[`_TRUNCATE`](./truncate.md)\ +[`TZNAME_MAX`](./tzname-max.md)\ +[`_WAIT_CHILD`, `_WAIT_GRANDCHILD`](./wait-child-wait-grandchild.md)\ +[`WCHAR_MAX`](./wchar-max.md)\ +[`WCHAR_MIN`](./wchar-min.md) ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[Global Variables](../c-runtime-library/global-variables.md)
-[Considerations for Writing Prolog/Epilog Code](../cpp/considerations-for-writing-prolog-epilog-code.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[Global variables](./global-variables.md)\ +[Considerations for writing prolog/epilog code](../cpp/considerations-for-writing-prolog-epilog-code.md) diff --git a/docs/c-runtime-library/global-state.md b/docs/c-runtime-library/global-state.md index 04d32ae9c4..b1d216c39c 100644 --- a/docs/c-runtime-library/global-state.md +++ b/docs/c-runtime-library/global-state.md @@ -26,34 +26,34 @@ The OS-specific versions of these functions are in `ucrt.osmode.lib`. For exampl There are two ways to isolate your component's CRT state from an app's CRT state: - Statically link your component by using compiler options `/MT` (release) or `/MTd` (debug). For details, see [/MD, /MT, /LD](../build/reference/md-mt-ld-use-run-time-library.md). Static linking can greatly increase binary size. -- Starting in Windows versions beginning with Windows 10 version 2004, dynamically link to the CRT but call the OS-mode exports (the functions that begin with _o_). To call the OS-mode exports, statically link as before, but ignore the static UCRT by using linker option `/NODEFAULTLIB:libucrt.lib` (release) or `/NODEFAULTLIB:libucrtd.lib` (debug). And add `ucrt.osmode.lib` to the linker input. See [/NODEFAULTLIB (Ignore Libraries)](../build/reference/nodefaultlib-ignore-libraries.md) for details. +- Starting in Windows versions beginning with Windows 10 version 2004, dynamically link to the CRT but call the OS-mode exports (the functions that begin with _o_). To call the OS-mode exports, statically link as before, but ignore the static UCRT by using linker option `/NODEFAULTLIB:libucrt.lib` (release) or `/NODEFAULTLIB:libucrtd.lib` (debug). And add `ucrt.osmode.lib` to the linker input. See [`/NODEFAULTLIB` (Ignore Libraries)](../build/reference/nodefaultlib-ignore-libraries.md) for details. -> [!Note] +> [!NOTE] > In source code, write `setlocale()`, not `_o_setlocale()`. When you link against `ucrt.osmode.lib`, the linker will automatically substitute the OS-specific version of the function. That is, `setlocale()` will be substituted with `_o_setlocale()`. -Linking against `ucrt.osmode.lib` disables some UCRT calls that are only available in app mode. Attempting to call these will result in a link error. +Linking against `ucrt.osmode.lib` disables some UCRT calls that are only available in app mode. Attempting to call these functions will result in a link error. ## Global state affected by app/OS separation Global state affected by the separation of app and OS state includes: - [Locale data](locale.md) -- Signal handlers set by [signal](reference/signal.md) -- Termination routines set by [terminate](reference/set-terminate-crt.md) -- [errno and _doserrno](errno-doserrno-sys-errlist-and-sys-nerr.md) -- Random number generation state used by [rand](reference/rand.md) and [srand](reference/srand.md) +- Signal handlers set by [`signal`](reference/signal.md) +- Termination routines set by [`terminate`](reference/set-terminate-crt.md) +- [`errno` and `_doserrno`](errno-doserrno-sys-errlist-and-sys-nerr.md) +- Random number generation state used by [`rand`](reference/rand.md) and [`srand`](reference/srand.md) - Functions that return a buffer that the user doesn't need to release: - [strtok, wcstok, _mbstok](reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) - [Tmpnam, _wtmpnam](reference/tempnam-wtempnam-tmpnam-wtmpnam.md) - [asctime, _wasctime](reference/asctime-wasctime.md) - [gmtime, _gmtime32, _gmtime64](reference/gmtime-gmtime32-gmtime64.md) - [_fcvt](reference/fcvt.md) - [_ecvt](reference/ecvt.md) - [strerror, _strerror, _wcserror, __wcserror](reference/strerror-strerror-wcserror-wcserror.md) -- The buffer used by [_putch, _putwch](reference/putch-putwch.md) -- [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) -- [_set_new_handler](reference/set-new-handler.md) and [_set_new_mode](reference/set-new-mode.md) -- [fmode](text-and-binary-mode-file-i-o.md) + [`strtok`, `wcstok`, `_mbstok`](reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md)\ + [`Tmpnam`, `_wtmpnam`](reference/tempnam-wtempnam-tmpnam-wtmpnam.md)\ + [`asctime`, `_wasctime`](reference/asctime-wasctime.md)\ + [`gmtime`, `_gmtime32`, `_gmtime64`](reference/gmtime-gmtime32-gmtime64.md)\ + [`_fcvt`](reference/fcvt.md)\ + [`_ecvt`](reference/ecvt.md)\ + [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](reference/strerror-strerror-wcserror-wcserror.md) +- The buffer used by [`_putch`, `_putwch`](reference/putch-putwch.md) +- [`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`](reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) +- [`_set_new_handler`](reference/set-new-handler.md) and [`_set_new_mode`](reference/set-new-mode.md) +- [`fmode`](text-and-binary-mode-file-i-o.md) - [Time zone information](time-management.md) ## See also diff --git a/docs/c-runtime-library/global-variables-and-standard-types.md b/docs/c-runtime-library/global-variables-and-standard-types.md index 6fcb49b026..e8f156062e 100644 --- a/docs/c-runtime-library/global-variables-and-standard-types.md +++ b/docs/c-runtime-library/global-variables-and-standard-types.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["global variables, CRT", "standard types, CRT", "standard types", "types [CRT]"] ms.assetid: 8f8bad6f-2b78-4068-a0dc-77d58d978920 --- -# Global Variables and Standard Types +# Global variables and standard types -The Microsoft run-time library contains definitions for [global variables](../c-runtime-library/global-variables.md), [control flags](../c-runtime-library/control-flags.md), and [standard types](../c-runtime-library/standard-types.md) used by library routines. Access these variables, flags, and types by declaring them in your program or by including the appropriate header files. +The Microsoft run-time library contains definitions for [global variables](./global-variables.md), [control flags](./control-flags.md), and [standard types](./standard-types.md) used by library routines. Access these variables, flags, and types by declaring them in your program or by including the appropriate header files. ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/global-variables.md b/docs/c-runtime-library/global-variables.md index 74b1fc6e13..495831f814 100644 --- a/docs/c-runtime-library/global-variables.md +++ b/docs/c-runtime-library/global-variables.md @@ -6,40 +6,40 @@ f1_keywords: ["c.variables"] helpviewer_keywords: ["global variables", "variables, global", "global variables, Microsoft run-time library"] ms.assetid: 01d1551c-2f0c-4f72-935c-6442caccf84f --- -# Global Variables +# Global variables The Microsoft C run-time library provides the following global variables or macros. Several of these global variables or macros have been deprecated in favor of more-secure functional versions, which we recommend you use instead of the global variables. -|Variable|Description| -|--------------|-----------------| -|[__argc, \__argv, \__wargv](../c-runtime-library/argc-argv-wargv.md)|Contains the command-line arguments.| -|[_daylight, _dstbias, _timezone, and _tzname](../c-runtime-library/daylight-dstbias-timezone-and-tzname.md)|Deprecated. Instead, use `_get_daylight`, `_get_dstbias`, `_get_timezone`, and `_get_tzname`.

Adjusts for local time; used in some date and time functions.| -|[errno, _doserrno, _sys_errlist, and _sys_nerr](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)|Deprecated. Instead, use `_get_errno`, `_set_errno`, `_get_doserrno`, `_set_doserrno`, `perror` and `strerror`.

Stores error codes and related information.| -|[_environ, _wenviron](../c-runtime-library/environ-wenviron.md)|Deprecated. Instead, use `getenv_s`, `_wgetenv_s`, `_dupenv_s`, `_wdupenv_s`, `_putenv_s`, and `_wputenv_s`.

Pointers to arrays of pointers to the process environment strings; initialized at startup.| -|[_fmode](../c-runtime-library/fmode.md)|Deprecated. Instead, use `_get_fmode` or `_set_fmode`.

Sets default file-translation mode.| -|[_iob](../c-runtime-library/iob.md)|Array of I/O control structures for the console, files, and devices.| -|[_pctype, _pwctype, _wctype, _mbctype, _mbcasemap](../c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md)|Contains information used by the character-classification functions.| -|[_pgmptr, _wpgmptr](../c-runtime-library/pgmptr-wpgmptr.md)|Deprecated. Instead, use `_get_pgmptr` or `_get_wpgmptr`.

Initialized at program startup to the fully-qualified or relative path of the program, the full program name, or the program name without its file name extension, depending on how the program was invoked.| +| Variable | Description | +|---|---| +| [`__argc`, `__argv`, `__wargv`](./argc-argv-wargv.md) | Contains the command-line arguments. | +| [`_daylight`, `_dstbias`, `_timezone`, and `_tzname`](./daylight-dstbias-timezone-and-tzname.md) | Deprecated. Instead, use `_get_daylight`, `_get_dstbias`, `_get_timezone`, and `_get_tzname`.

Adjusts for local time; used in some date and time functions. | +| [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](./errno-doserrno-sys-errlist-and-sys-nerr.md) | Deprecated. Instead, use `_get_errno`, `_set_errno`, `_get_doserrno`, `_set_doserrno`, `perror` and `strerror`.

Stores error codes and related information. | +| [`_environ`, `_wenviron`](./environ-wenviron.md) | Deprecated. Instead, use `getenv_s`, `_wgetenv_s`, `_dupenv_s`, `_wdupenv_s`, `_putenv_s`, and `_wputenv_s`.

Pointers to arrays of pointers to the process environment strings; initialized at startup. | +| [`_fmode`](./fmode.md) | Deprecated. Instead, use `_get_fmode` or `_set_fmode`.

Sets default file-translation mode. | +| [`_iob`](./iob.md) | Array of I/O control structures for the console, files, and devices. | +| [`_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | Contains information used by the character-classification functions. | +| [`_pgmptr`, `_wpgmptr`](./pgmptr-wpgmptr.md) | Deprecated. Instead, use `_get_pgmptr` or `_get_wpgmptr`.

Based on how the program is invoked, the runtime initializes these values at program startup: either to the fully qualified or relative path of the program, the full program name, or the program name without its file name extension. | ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[Global Constants](../c-runtime-library/global-constants.md)
-[__argc, \__argv, \__wargv](../c-runtime-library/argc-argv-wargv.md)
-[_get_daylight](../c-runtime-library/reference/get-daylight.md)
-[_get_dstbias](../c-runtime-library/reference/get-dstbias.md)
-[_get_timezone](../c-runtime-library/reference/get-timezone.md)
-[_get_tzname](../c-runtime-library/reference/get-tzname.md)
-[perror](../c-runtime-library/reference/perror-wperror.md)
-[strerror](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)
-[_get_doserrno](../c-runtime-library/reference/get-doserrno.md)
-[_set_doserrno](../c-runtime-library/reference/set-doserrno.md)
-[_get_errno](../c-runtime-library/reference/get-errno.md)
-[_set_errno](../c-runtime-library/reference/set-errno.md)
-[_dupenv_s, _wdupenv_s](../c-runtime-library/reference/dupenv-s-wdupenv-s.md)
-[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md)
-[getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)
-[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md)
-[_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md)
-[_get_fmode](../c-runtime-library/reference/get-fmode.md)
-[_set_fmode](../c-runtime-library/reference/set-fmode.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[Global constants](./global-constants.md)\ +[`__argc`, `__argv`, `__wargv`](./argc-argv-wargv.md)\ +[`_get_daylight`](./reference/get-daylight.md)\ +[`_get_dstbias`](./reference/get-dstbias.md)\ +[`_get_timezone`](./reference/get-timezone.md)\ +[`_get_tzname`](./reference/get-tzname.md)\ +[`perror`](./reference/perror-wperror.md)\ +[`strerror`](./reference/strerror-strerror-wcserror-wcserror.md)\ +[`_get_doserrno`](./reference/get-doserrno.md)\ +[`_set_doserrno`](./reference/set-doserrno.md)\ +[`_get_errno`](./reference/get-errno.md)\ +[`_set_errno`](./reference/set-errno.md)\ +[`_dupenv_s`, `_wdupenv_s`](./reference/dupenv-s-wdupenv-s.md)\ +[`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md)\ +[`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md)\ +[`_putenv`, `_wputenv`](./reference/putenv-wputenv.md)\ +[`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md)\ +[`_get_fmode`](./reference/get-fmode.md)\ +[`_set_fmode`](./reference/set-fmode.md) diff --git a/docs/c-runtime-library/heap-constants.md b/docs/c-runtime-library/heap-constants.md index ec7e079d88..71ae99a468 100644 --- a/docs/c-runtime-library/heap-constants.md +++ b/docs/c-runtime-library/heap-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: Heap Constants" title: "Heap Constants" ms.date: "11/04/2016" -f1_keywords: ["_HEAPBADPTR", "_HEAPEMPTY", "_HEAPBADBEGIN", "_HEAPOK", "_HEAPBADNODE", "_HEAPEND"] +f1_keywords: ["MALLOC/_HEAPBADPTR", "MALLOC/_HEAPEMPTY", "MALLOC/_HEAPBADBEGIN", "MALLOC/_HEAPOK", "MALLOC/_HEAPBADNODE", "MALLOC/_HEAPEND", "_HEAPBADPTR", "_HEAPEMPTY", "_HEAPBADBEGIN", "_HEAPOK", "_HEAPBADNODE", "_HEAPEND"] helpviewer_keywords: ["_HEAPOK constants", "_HEAPEND constants", "HEAPBADBEGIN constants", "_HEAPBADNODE constants", "HEAPBADNODE constants", "HEAPBADPTR constants", "_HEAPEMPTY constants", "HEAPEND constants", "HEAPOK constants", "HEAPEMPTY constants", "_HEAPBADBEGIN constants", "_HEAPBADPTR constants", "heap constants"] ms.assetid: 3f751bb9-2dc4-486f-b5f5-9061c96d3754 --- -# Heap Constants +# Heap constants ## Syntax -``` +```C #include ``` @@ -18,18 +18,18 @@ ms.assetid: 3f751bb9-2dc4-486f-b5f5-9061c96d3754 These constants give the return value indicating status of the heap. -|Constant|Meaning| -|--------------|-------------| -|`_HEAPBADBEGIN`|Initial header information was not found or was invalid.| -|`_HEAPBADNODE`|Bad node was found, or heap is damaged.| -|`_HEAPBADPTR`|**_pentry** field of **_HEAPINFO** structure does not contain valid pointer into heap (`_heapwalk` routine only).| -|`_HEAPEMPTY`|Heap has not been initialized.| -|`_HEAPEND`|End of heap was reached successfully (`_heapwalk` routine only).| -|`_HEAPOK`|Heap is consistent (`_heapset` and `_heapchk` routines only). No errors so far; **_HEAPINFO** structure contains information about next entry (`_heapwalk` routine only).| +| Constant | Meaning | +|---|---| +| `_HEAPBADBEGIN` | Initial header information wasn't found or was invalid. | +| `_HEAPBADNODE` | Bad node was found, or heap is damaged. | +| `_HEAPBADPTR` | `_pentry` field of `_HEAPINFO` structure doesn't contain valid pointer into heap (`_heapwalk` routine only). | +| `_HEAPEMPTY` | Heap hasn't been initialized. | +| `_HEAPEND` | End of heap was reached successfully (`_heapwalk` routine only). | +| `_HEAPOK` | Heap is consistent (`_heapset` and `_heapchk` routines only). No errors so far; `_HEAPINFO` structure contains information about next entry (`_heapwalk` routine only). | ## See also -[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapset](../c-runtime-library/heapset.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_heapchk`](./reference/heapchk.md)\ +[`_heapset`](./heapset.md)\ +[`_heapwalk`](./reference/heapwalk.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/heap-maxreq.md b/docs/c-runtime-library/heap-maxreq.md index e4688366f2..e0b2918230 100644 --- a/docs/c-runtime-library/heap-maxreq.md +++ b/docs/c-runtime-library/heap-maxreq.md @@ -2,15 +2,15 @@ description: "Learn more about: _HEAP_MAXREQ" title: "_HEAP_MAXREQ" ms.date: "11/04/2016" -f1_keywords: ["HEAP_MAXREQ", "_HEAP_MAXREQ"] +f1_keywords: ["HEAP_MAXREQ", "MALLOC/_HEAP_MAXREQ", "_HEAP_MAXREQ"] helpviewer_keywords: ["HEAP_MAXREQ constants", "_HEAP_MAXREQ constants", "heap constants"] ms.assetid: c2dbc2ea-35ad-45d8-b459-d76ba0089ff7 --- -# _HEAP_MAXREQ +# `_HEAP_MAXREQ` ## Syntax -``` +```C #include ``` @@ -20,6 +20,6 @@ The maximum size of a user request for memory that can be granted. ## See also -[malloc](../c-runtime-library/reference/malloc.md)
-[calloc](../c-runtime-library/reference/calloc.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`malloc`](./reference/malloc.md)\ +[`calloc`](./reference/calloc.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/heapadd.md b/docs/c-runtime-library/heapadd.md index f5aadfdcc1..737e7991fe 100644 --- a/docs/c-runtime-library/heapadd.md +++ b/docs/c-runtime-library/heapadd.md @@ -10,7 +10,7 @@ f1_keywords: ["heapadd", "_heapadd"] helpviewer_keywords: ["_heapadd function", "memory, adding to heaps", "heaps, adding memory", "heapadd function"] ms.assetid: 4d691fe2-2763-49f4-afb1-62738b7cd3ff --- -# _heapadd +# `_heapadd` Adds memory to the heap. @@ -19,46 +19,46 @@ Adds memory to the heap. ## Syntax -``` +```C int _heapadd( void *memblock, size_t size ); ``` -#### Parameters +### Parameters -*memblock*
+*`memblock`*\ Pointer to the heap memory. -*size*
+*`size`*\ Size of memory to add, in bytes. -## Return Value +## Return value -If successful, `_heapadd` returns 0; otherwise, the function returns -1 and sets `errno` to `ENOSYS`. +If successful, **`_heapadd`** returns 0; otherwise, the function returns -1 and sets `errno` to `ENOSYS`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](./errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Beginning with Visual C++ version 4.0, the underlying heap structure was moved to the C run-time libraries to support the new debugging features. As a result, `_heapadd` is no longer supported on any platform that is based on the Win32 API. +Beginning with Visual C++ version 4.0, the underlying heap structure was moved to the C run-time libraries to support the new debugging features. As a result, **`_heapadd`** is no longer supported on any platform that is based on the Win32 API. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|`_heapadd`|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapadd`** | \ | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## See also -[Memory Allocation](../c-runtime-library/memory-allocation.md)
-[free](../c-runtime-library/reference/free.md)
-[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapmin](../c-runtime-library/reference/heapmin.md)
-[_heapset](../c-runtime-library/heapset.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md)
-[malloc](../c-runtime-library/reference/malloc.md)
-[realloc](../c-runtime-library/reference/realloc.md) +[Memory allocation](./memory-allocation.md)\ +[`free`](./reference/free.md)\ +[`_heapchk`](./reference/heapchk.md)\ +[`_heapmin`](./reference/heapmin.md)\ +[`_heapset`](./heapset.md)\ +[`_heapwalk`](./reference/heapwalk.md)\ +[`malloc`](./reference/malloc.md)\ +[`realloc`](./reference/realloc.md) diff --git a/docs/c-runtime-library/heapset.md b/docs/c-runtime-library/heapset.md index 5b1adc0b61..71dcd09725 100644 --- a/docs/c-runtime-library/heapset.md +++ b/docs/c-runtime-library/heapset.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _heapset" title: "_heapset" +description: "Learn more about: _heapset" ms.date: "11/04/2016" api_name: ["_heapset"] api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_heapset", "heapset"] helpviewer_keywords: ["checking heap", "heapset function", "heaps, checking", "debugging [CRT], heap-related problems", "_heapset function"] -ms.assetid: 9667eeb0-55bc-4c19-af5f-d1fd0a142b3c --- -# _heapset +# `_heapset` Checks heaps for minimal consistency and sets the free entries to a specified value. @@ -19,7 +18,7 @@ Checks heaps for minimal consistency and sets the free entries to a specified va ## Syntax -``` +```C int _heapset( unsigned int fill ); @@ -27,35 +26,35 @@ int _heapset( #### Parameters -*fill*
+*`fill`*\ Fill character. -## Return Value +## Return value -`_heapset` returns one of the following integer manifest constants defined in Malloc.h. +**`_heapset`** returns one of the following integer manifest constants defined in Malloc.h. -|Value|Description| -|-|-| -| `_HEAPBADBEGIN` | Initial header information invalid or not found. | -| `_HEAPBADNODE` | Heap damaged or bad node found. | -| `_HEAPEMPTY` | Heap not initialized. | -| `_HEAPOK` | Heap appears to be consistent. | +| Value | Description | +|---|---| +| `_HEAPBADBEGIN` | Initial header information invalid or not found. | +| `_HEAPBADNODE` | Heap damaged or bad node found. | +| `_HEAPEMPTY` | Heap not initialized. | +| `_HEAPOK` | Heap appears to be consistent. | -In addition, if an error occurs, `_heapset` sets `errno` to `ENOSYS`. +In addition, if an error occurs, **`_heapset`** sets `errno` to `ENOSYS`. ## Remarks -The `_heapset` function shows free memory locations or nodes that have been unintentionally overwritten. +The **`_heapset`** function shows free memory locations or nodes that have been unintentionally overwritten. -`_heapset` checks for minimal consistency on the heap and then sets each byte of the heap's free entries to the `fill` value. This known value shows which memory locations of the heap contain free nodes and which contain data that were unintentionally written to freed memory. If the operating system does not support `_heapset`(for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. +**`_heapset`** checks for minimal consistency on the heap and then sets each byte of the heap's free entries to the `fill` value. This known value shows which memory locations of the heap contain free nodes and which contain data that were unintentionally written to freed memory. If the operating system doesn't support **`_heapset`** (for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|`_heapset`|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapset`** | \ | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## Example @@ -101,8 +100,8 @@ OK - heap is fine ## See also -[Memory Allocation](../c-runtime-library/memory-allocation.md)
-[_heapadd](../c-runtime-library/heapadd.md)
-[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapmin](../c-runtime-library/reference/heapmin.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md) +[Memory allocation](./memory-allocation.md)\ +[`_heapadd`](./heapadd.md)\ +[`_heapchk`](./reference/heapchk.md)\ +[`_heapmin`](./reference/heapmin.md)\ +[`_heapwalk`](./reference/heapwalk.md) diff --git a/docs/c-runtime-library/huge-val-huge.md b/docs/c-runtime-library/huge-val-huge.md index be0042e116..98eaf2b2ea 100644 --- a/docs/c-runtime-library/huge-val-huge.md +++ b/docs/c-runtime-library/huge-val-huge.md @@ -6,22 +6,22 @@ api_name: ["_HUGE"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_HUGE", "HUGE_VAL"] +f1_keywords: ["CORECRT_MATH/HUGE_VAL", "CORECRT_MATH/HUGE_VALF", "CORECRT_MATH/HUGE_VALL", "CORECRT_MATH/HUGE", "CORECRT_MATH/_HUGE", "HUGE_VAL", "HUGE_VALF", "HUGE_VALL", "HUGE", "_HUGE"] helpviewer_keywords: ["_HUGE constant", "HUGE_VAL constant", "double value"] ms.assetid: 3f044b45-02cd-46b2-b1de-87fd0441dd6a --- -# HUGE_VAL, _HUGE +# `HUGE_VAL`, `_HUGE` ## Syntax -``` +```C #include ``` ## Remarks -`HUGE_VAL` is the largest representable double value. This value is returned by many run-time math functions when an error occurs. For some functions, -`HUGE_VAL` is returned. `HUGE_VAL` is defined as `_HUGE`, but run-time math functions return `HUGE_VAL`. You should also use `HUGE_VAL` in your code for consistency. +`HUGE_VAL` is the largest representable double value. This value is returned by many run-time math functions when an error occurs. For some functions, `-HUGE_VAL` is returned. `HUGE_VAL` is defined as the result of a floating-point product that is guaranteed to overflow. `HUGE_VALF` and `HUGE_VALL` are the largest representable `float` and `long double` typed values, respectively. The internal value `_HUGE` and the synonymous `HUGE` are defined similarly, but run-time math functions return `HUGE_VAL`. You should also use `HUGE_VAL` in your code for consistency. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/inp-inpw-inpd.md b/docs/c-runtime-library/inp-inpw-inpd.md index 8b690315e4..3e98fc33a2 100644 --- a/docs/c-runtime-library/inp-inpw-inpd.md +++ b/docs/c-runtime-library/inp-inpw-inpd.md @@ -10,13 +10,13 @@ f1_keywords: ["inp", "inpw", "_inp", "_inpw", "_inpd"] helpviewer_keywords: ["inp function", "inpw function", "ports, I/O routines", "inpd function", "_inp function", "_inpd function", "I/O [CRT], port", "_inpw function"] ms.assetid: 5d9c2e38-fc85-4294-86d5-7282cc02d1b3 --- -# inp, _inp, inpw, _inpw, _inpd +# `inp`, `_inp`, `inpw`, `_inpw`, `_inpd` -Inputs, from a port, a byte (`inp`, `_inp`), a word (`inpw`, `_inpw`), or a double word (`_inpd`). +Inputs, from a port, a byte (**`inp`**, **`_inp`**), a word (**`inpw`**, **`_inpw`**), or a double word (**`_inpd`**). > [!IMPORTANT] > These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT.\ -> This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> This API can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -34,36 +34,36 @@ unsigned long _inpd( ### Parameters -*port*\ +*`port`*\ I/O port number. -## Return Value +## Return value -The functions return the byte, word, or double word read from `port`. There's no error return. +The functions return the byte, word, or double word read from *`port`*. There's no error return. ## Remarks -The `_inp`, `_inpw`, and `_inpd` functions read a byte, a word, and a double word, respectively, from the specified input port. The input value can be any unsigned short integer in the range 0 - 65,535. +The **`_inp`**, **`_inpw`**, and **`_inpd`** functions read a byte, a word, and a double word, respectively, from the specified input port. The input value can be any unsigned short integer in the range 0 - 65,535. -Because these functions read directly from an I/O port, they cannot be used in user code. +Because these functions read directly from an I/O port, they can't be used in user code. -The `inp` and `inpw` names are older, deprecated names for the `_inp` and `_inpw` functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +The **`inp`** and **`inpw`** names are older, deprecated names for the **`_inp`** and **`_inpw`** functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_inp`|\| -|`_inpw`|\| -|`_inpd`|\| +| Routine | Required header | +|---|---| +| **`_inp`** | \ | +| **`_inpw`** | \ | +| **`_inpd`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Libraries -All versions of the [C run-time libraries](../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](./crt-library-features.md). ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)\ -[outp, outpw, _outp, _outpw, _outpd](../c-runtime-library/outp-outpw-outpd.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`outp`, `outpw`, `_outp`, `_outpw`, `_outpd`](./outp-outpw-outpd.md) diff --git a/docs/c-runtime-library/input-and-output.md b/docs/c-runtime-library/input-and-output.md index b7600f7709..d459ce63c1 100644 --- a/docs/c-runtime-library/input-and-output.md +++ b/docs/c-runtime-library/input-and-output.md @@ -4,21 +4,20 @@ title: "Input and Output" ms.date: "11/04/2016" f1_keywords: ["c.io"] helpviewer_keywords: ["input routines", "I/O [CRT]", "I/O routines", "I/O [CRT], routines", "output routines"] -ms.assetid: 1c177301-e341-4ca0-aedc-0a87fe1c75ae --- -# Input and Output +# Input and output The I/O functions read and write data to and from files and devices. File I/O operations take place in text mode or binary mode. The Microsoft run-time library has three types of I/O functions: -- [Stream I/O](../c-runtime-library/stream-i-o.md) functions treat data as a stream of individual characters. +- [Stream I/O](./stream-i-o.md) functions treat data as a stream of individual characters. -- [Low-level I/O](../c-runtime-library/low-level-i-o.md) functions invoke the operating system directly for lower-level operation than that provided by stream I/O. +- [Low-level I/O](./low-level-i-o.md) functions invoke the operating system directly for lower-level operation than that provided by stream I/O. -- [Console and port I/O](../c-runtime-library/console-and-port-i-o.md) functions read or write directly to a console (keyboard and screen) or an I/O port (such as a printer port). +- [Console and port I/O](./console-and-port-i-o.md) functions read or write directly to a console (keyboard and screen) or an I/O port (such as a printer port). > [!NOTE] > Because stream functions are buffered and low-level functions are not, these two types of functions are generally incompatible. For processing a particular file, use either stream or low-level functions exclusively. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/internal-crt-globals-and-functions.md b/docs/c-runtime-library/internal-crt-globals-and-functions.md index baad53841b..e9b6ae617b 100644 --- a/docs/c-runtime-library/internal-crt-globals-and-functions.md +++ b/docs/c-runtime-library/internal-crt-globals-and-functions.md @@ -2,348 +2,346 @@ description: "Learn more about: Internal CRT Globals and Functions" title: "Internal CRT Globals and Functions" ms.date: "1/14/2021" -api_name: ["__acrt_iob_func", "__AdjustPointer", "_assert", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__daylight", "_dclass", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_dpcomp", "_dsign", "__dstbias", "_dtest", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_fdclass", "_fdpcomp", "_fdsign", "_fdtest", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "_ldclass", "_ldpcomp", "_ldsign", "_ldtest", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "_pctype", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__std_type_info_name", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_wassert", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error", "_o__CIacos", "_o__CIasin", "_o__CIcosh", "_o__CIsinh", "_o__CItanh", "_o__Getdays", "_o__Getmonths", "_o__Gettnames", "_o__Strftime", "_o__W_Getdays", "_o__W_Getmonths", "_o__Wcsftime", "_o___acrt_iob_func", "_o___conio_common_vcprintf", "_o___conio_common_vcprintf_p", "_o___conio_common_vcprintf_s", "_o___conio_common_vcscanf", "_o___conio_common_vcwprintf", "_o___conio_common_vcwprintf_p", "_o___conio_common_vcwprintf_s", "_o___conio_common_vcwscanf", "_o___fpe_flt_rounds", "_o___libm_sse2_acos", "_o___libm_sse2_acosf", "_o___libm_sse2_asin", "_o___libm_sse2_asinf", "_o___libm_sse2_atan", "_o___libm_sse2_atan2", "_o___libm_sse2_atanf", "_o___libm_sse2_cos", "_o___libm_sse2_cosf", "_o___libm_sse2_exp", "_o___libm_sse2_expf", "_o___libm_sse2_log", "_o___libm_sse2_log10", "_o___libm_sse2_log10f", "_o___libm_sse2_logf", "_o___libm_sse2_pow", "_o___libm_sse2_powf", "_o___libm_sse2_sin", "_o___libm_sse2_sinf", "_o___libm_sse2_tan", "_o___libm_sse2_tanf", "_o___p___argc", "_o___p___argv", "_o___p___wargv", "_o___p__acmdln", "_o___p__environ", "_o___p__mbcasemap", "_o___p__mbctype", "_o___p__pgmptr", "_o___p__wcmdln", "_o___p__wenviron", "_o___p__wpgmptr", "_o___pwctype_func", "_o___std_exception_copy", "_o___std_exception_destroy", "_o___std_type_info_destroy_list", "_o___stdio_common_vfprintf", "_o___stdio_common_vfprintf_p", "_o___stdio_common_vfprintf_s", "_o___stdio_common_vfscanf", "_o___stdio_common_vfwprintf", "_o___stdio_common_vfwprintf_p", "_o___stdio_common_vfwprintf_s", "_o___stdio_common_vfwscanf", "_o___stdio_common_vsnprintf_s", "_o___stdio_common_vsnwprintf_s", "_o___stdio_common_vsprintf", "_o___stdio_common_vsprintf_p", "_o___stdio_common_vsprintf_s", "_o___stdio_common_vsscanf", "_o___stdio_common_vswprintf", "_o___stdio_common_vswprintf_p", "_o___stdio_common_vswprintf_s", "_o___stdio_common_vswscanf", "_o___timezone", "_o___tzname", "_o__calloc_base", "_o__configure_narrow_argv", "_o__configure_wide_argv", "_o__crt_atexit", "_o__errno", "_o__except1", "_o__free_base", "_o__get_initial_narrow_environment", "_o__get_initial_wide_environment", "_o__get_narrow_winmain_command_line", "_o__get_stream_buffer_pointers", "_o__get_wide_winmain_command_line", "_o__initialize_narrow_environment", "_o__initialize_wide_environment", "_o__libm_sse2_acos_precise", "_o__libm_sse2_asin_precise", "_o__libm_sse2_atan_precise", "_o__libm_sse2_cos_precise", "_o__libm_sse2_exp_precise", "_o__libm_sse2_log10_precise", "_o__libm_sse2_log_precise", "_o__libm_sse2_pow_precise", "_o__libm_sse2_sin_precise", "_o__libm_sse2_sqrt_precise", "_o__libm_sse2_tan_precise", "_o__malloc_base", "_o__realloc_base", "_o__sopen_dispatch", "_o__wsopen_dispatch"] -api_location: ["api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-core-crt-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-conio-l1-1-0.dll", "vcruntime140_app.dll", "msvcp140_app.dll", "ntdll.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-environment-l1-1-0.dll"] +api_name: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__std_type_info_name", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error", "_o__CIacos", "_o__CIasin", "_o__CIcosh", "_o__CIsinh", "_o__CItanh", "_o__Getdays", "_o__Getmonths", "_o__Gettnames", "_o__Strftime", "_o__W_Getdays", "_o__W_Getmonths", "_o__Wcsftime", "_o___acrt_iob_func", "_o___conio_common_vcprintf", "_o___conio_common_vcprintf_p", "_o___conio_common_vcprintf_s", "_o___conio_common_vcscanf", "_o___conio_common_vcwprintf", "_o___conio_common_vcwprintf_p", "_o___conio_common_vcwprintf_s", "_o___conio_common_vcwscanf", "_o___fpe_flt_rounds", "_o___libm_sse2_acos", "_o___libm_sse2_acosf", "_o___libm_sse2_asin", "_o___libm_sse2_asinf", "_o___libm_sse2_atan", "_o___libm_sse2_atan2", "_o___libm_sse2_atanf", "_o___libm_sse2_cos", "_o___libm_sse2_cosf", "_o___libm_sse2_exp", "_o___libm_sse2_expf", "_o___libm_sse2_log", "_o___libm_sse2_log10", "_o___libm_sse2_log10f", "_o___libm_sse2_logf", "_o___libm_sse2_pow", "_o___libm_sse2_powf", "_o___libm_sse2_sin", "_o___libm_sse2_sinf", "_o___libm_sse2_tan", "_o___libm_sse2_tanf", "_o___p___argc", "_o___p___argv", "_o___p___wargv", "_o___p__acmdln", "_o___p__environ", "_o___p__mbcasemap", "_o___p__mbctype", "_o___p__pgmptr", "_o___p__wcmdln", "_o___p__wenviron", "_o___p__wpgmptr", "_o___pwctype_func", "_o___std_exception_copy", "_o___std_exception_destroy", "_o___std_type_info_destroy_list", "_o___stdio_common_vfprintf", "_o___stdio_common_vfprintf_p", "_o___stdio_common_vfprintf_s", "_o___stdio_common_vfscanf", "_o___stdio_common_vfwprintf", "_o___stdio_common_vfwprintf_p", "_o___stdio_common_vfwprintf_s", "_o___stdio_common_vfwscanf", "_o___stdio_common_vsnprintf_s", "_o___stdio_common_vsnwprintf_s", "_o___stdio_common_vsprintf", "_o___stdio_common_vsprintf_p", "_o___stdio_common_vsprintf_s", "_o___stdio_common_vsscanf", "_o___stdio_common_vswprintf", "_o___stdio_common_vswprintf_p", "_o___stdio_common_vswprintf_s", "_o___stdio_common_vswscanf", "_o___timezone", "_o___tzname", "_o__calloc_base", "_o__configure_narrow_argv", "_o__configure_wide_argv", "_o__crt_atexit", "_o__errno", "_o__except1", "_o__free_base", "_o__get_initial_narrow_environment", "_o__get_initial_wide_environment", "_o__get_narrow_winmain_command_line", "_o__get_stream_buffer_pointers", "_o__get_wide_winmain_command_line", "_o__initialize_narrow_environment", "_o__initialize_wide_environment", "_o__libm_sse2_acos_precise", "_o__libm_sse2_asin_precise", "_o__libm_sse2_atan_precise", "_o__libm_sse2_cos_precise", "_o__libm_sse2_exp_precise", "_o__libm_sse2_log10_precise", "_o__libm_sse2_log_precise", "_o__libm_sse2_pow_precise", "_o__libm_sse2_sin_precise", "_o__libm_sse2_sqrt_precise", "_o__libm_sse2_tan_precise", "_o__malloc_base", "_o__realloc_base", "_o__sopen_dispatch", "_o__wsopen_dispatch"] +api_location: ["api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-core-crt-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-conio-l1-1-0.dll", "vcruntime140_app.dll", "msvcp140_app.dll", "ntdll.dll", "ntoskrnl.exe", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "__CxxUnregisterExceptionObject", "__daylight", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_free_base", "_freea_s", "_freefls", "_ftol", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] -helpviewer_keywords: ["__acrt_iob_func", "__AdjustPointer", "_assert", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__daylight", "_dclass", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_dpcomp", "_dsign", "__dstbias", "_dtest", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_fdclass", "_fdpcomp", "_fdsign", "_fdtest", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "_ldclass", "_ldpcomp", "_ldsign", "_ldtest", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "_pctype", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_wassert", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] +f1_keywords: ["CORECRT_WSTDIO/__acrt_iob_func", "EXCPT/__C_specific_handler", "CORECRT_MALLOC/_calloc_base", "CTYPE/_chvalidator", "CTYPE/_chvalidator_l", "STDIO/_commode", "CORECRT_STARTUP/_configure_narrow_argv", "CORECRT_STARTUP/_configure_wide_argv", "CONIO/__conio_common_vcprintf", "CONIO/__conio_common_vcprintf_p", "CONIO/__conio_common_vcprintf_s", "CONIO/__conio_common_vcscanf", "CONIO/__conio_common_vcwprintf", "CONIO/__conio_common_vcwprintf_p", "CONIO/__conio_common_vcwprintf_s", "CONIO/__conio_common_vcwscanf", "CORECRT_STARTUP/_crt_at_quick_exit", "CORECRT_STARTUP/_crt_atexit", "CRTDBG/_crtAssertBusy", "CRTDBG/_crtBreakAlloc", "STDLIB/__doserrno", "STDDEF/_errno", "EXCPT/_except_handler", "FLOAT/__fpe_flt_rounds", "FLOAT/__fpecode", "CORECRT_MALLOC/_free_base", "CORECRT_STARTUP/_get_initial_narrow_environment", "CORECRT_STARTUP/_get_initial_wide_environment", "CORECRT_STARTUP/_get_narrow_winmain_command_line", "CORECRT_STARTUP/_get_wide_winmain_command_line", "STDIO/_get_stream_buffer_pointers", "LOCALE/_Getdays", "LOCALE/_Getmonths", "LOCALE/_Gettnames", "CORECRT_STARTUP/_initialize_narrow_environment", "CORECRT_STARTUP/_initialize_wide_environment", "LOCALE/_lock_locales", "CORECRT_MALLOC/_malloc_base", "STDLIB/__p___argc", "STDLIB/__p___argv", "STDLIB/__p___wargv", "CORECRT_STARTUP/__p__acmdln", "CRTDBG/__p__crtBreakAlloc", "CRTDBG/__p__crtDbgFlag", "STDLIB/__p__environ", "MBCTYPE/__p__mbcasemap", "MBCTYPE/__p__mbctype", "STDLIB/__p__pgmptr", "CORECRT_STARTUP/__p__wcmdln", "STDLIB/__p__wenviron", "STDLIB/__p__wpgmptr", "CORECRT_WCTYPE/__pwctype_func", "SIGNAL/__pxcptinfoptrs", "CORECRT_STARTUP/_query_app_type", "CORECRT_MALLOC/_realloc_base", "PROCESS/_register_thread_local_exe_atexit_callback", "VCRUNTIME/__report_gsfailure", "RTTIDATA/__RTCastToVoid", "RTTIDATA/__RTtypeid", "CORECRT_IO/_sopen_dispatch", "VCRUNTIME_EXCEPTION/__std_exception_copy", "VCRUNTIME_EXCEPTION/__std_exception_destroy", "STDIO/__stdio_common_vfprintf", "STDIO/__stdio_common_vfprintf_p", "STDIO/__stdio_common_vfprintf_s", "STDIO/__stdio_common_vfscanf", "STDIO/__stdio_common_vfwprintf", "STDIO/__stdio_common_vfwprintf_p", "STDIO/__stdio_common_vfwprintf_s", "STDIO/__stdio_common_vfwscanf", "STDIO/__stdio_common_vsnprintf_s", "STDIO/__stdio_common_vsnwprintf_s", "STDIO/__stdio_common_vsprintf", "STDIO/__stdio_common_vsprintf_p", "STDIO/__stdio_common_vsprintf_s", "STDIO/__stdio_common_vsscanf", "STDIO/__stdio_common_vswprintf", "STDIO/__stdio_common_vswprintf_p", "STDIO/__stdio_common_vswprintf_s", "STDIO/__stdio_common_vswscanf", "LOCALE/_Strftime", "STRING/__strncnt", "STDDEF/__threadhandle", "STDDEF/__threadid", "TIME/__timezone", "TIME/__tzname", "LOCALE/_unlock_locales", "CRTDBG/_VCrtDbgReportA", "CRTDBG/_VCrtDbgReportW", "LOCALE/_W_Getdays", "LOCALE/_W_Getmonths", "LOCALE/_W_Getgnames", "LOCALE/_Wcsftime", "TCHAR/__wcsncnt", "CORECRT_WIO/_wsopen_dispatch", "__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_free_base", "_freea_s", "_freefls", "_ftol", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] +helpviewer_keywords: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] --- -# Internal CRT Globals and Functions +# Internal CRT globals and functions The C runtime (CRT) library contains functions and global variables that are used only to support the public library interface. Some of them are exposed in public headers as implementation details. Although these functions and global variables are accessible through public exports, they're not intended for use by your code. We recommend that you change any code that uses these functions and variables to use public library equivalents instead. These functions may change from version to version. They're listed here to help you identify them. Links are provided when other documentation exists, but in general, these implementation details aren't documented. -## Internal CRT Globals and Value Macros +## Internal CRT globals and value macros These global variables and macro definitions are used to implement the CRT. -|Name| -|----------| -|`__badioinfo`| -|[`_acmdln`](../c-runtime-library/acmdln-tcmdln-wcmdln.md)| -|`_commode`| -|`_crtAssertBusy`| -|`_crtBreakAlloc`| -|`__initenv`| -|`__lconv`| -|[`__mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`__pioinfo`| -|`__unguarded_readlc_active`| -|[`_wcmdln`](../c-runtime-library/acmdln-tcmdln-wcmdln.md)| -|`__winitenv`| +| Name | +|---| +| `__badioinfo` | +| [`_acmdln`](./acmdln-tcmdln-wcmdln.md) | +| `_commode` | +| `_crtAssertBusy` | +| `_crtBreakAlloc` | +| `__initenv` | +| `__lconv` | +| [`__mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `__pioinfo` | +| `__unguarded_readlc_active` | +| [`_wcmdln`](./acmdln-tcmdln-wcmdln.md) | +| `__winitenv` | -## Internal CRT Functions and Function Macros +## Internal CRT functions and function macros These functions and function macros are used to implement the CRT and the C++ Standard Library. -|Name| -|----------| -|`__acrt_iob_func`| -|`__AdjustPointer`| -|`_assert`| -|`__BuildCatchObject`| -|`__BuildCatchObjectHelper`| -|`__C_specific_handler`| -|`_calloc_base`| -|`_chkesp`| -|`__chkstk`| -|`_chkstk`| -|`_chvalidator`| -|`_chvalidator_l`| -|`_CIacos`| -|`_CIasin`| -|[`_CIatan`](../c-runtime-library/ciatan.md)| -|[`_CIatan2`](../c-runtime-library/ciatan2.md)| -|[`_CIcos`](../c-runtime-library/cicos.md)| -|`_CIcosh`| -|[`_CIexp`](../c-runtime-library/ciexp.md)| -|[`_CIfmod`](../c-runtime-library/cifmod.md)| -|[`_CIlog`](../c-runtime-library/cilog.md)| -|[`_CIlog10`](../c-runtime-library/cilog10.md)| -|[`_CIpow`](../c-runtime-library/cipow.md)| -|[`_CIsin`](../c-runtime-library/cisin.md)| -|`_CIsinh`| -|[`_CIsqrt`](../c-runtime-library/cisqrt.md)| -|[`_CItan`](../c-runtime-library/citan.md)| -|`_CItanh`| -|`__clean_type_info_names_internal`| -|`_configure_narrow_argv`| -|`_configure_wide_argv`| -|`__conio_common_vcprintf`| -|`__conio_common_vcprintf_p`| -|`__conio_common_vcprintf_s`| -|`__conio_common_vcscanf`| -|`__conio_common_vcwprintf`| -|`__conio_common_vcwprintf_p`| -|`__conio_common_vcwprintf_s`| -|`__conio_common_vcwscanf`| -|`__CppXcptFilter`| -|`__create_locale`| -|`_crt_atexit`| -|`_crt_at_quick_exit`| -|`__crtCompareStringA`| -|`__crtCompareStringEx`| -|`__crtCompareStringW`| -|`__crtCreateEventExW`| -|`__crtCreateSemaphoreExW`| -|`__crtCreateSymbolicLinkW`| -|`_crt_debugger_hook`| -|`__crtEnumSystemLocalesEx`| -|`__crtFlsAlloc`| -|`__crtFlsFree`| -|`__crtFlsGetValue`| -|`__crtFlsSetValue`| -|`_CrtGetCheckCount`| -|`__crtGetDateFormatEx`| -|`__crtGetFileInformationByHandleEx`| -|`__crtGetLocaleInfoEx`| -|`__crtGetShowWindowMode`| -|`__crtGetTickCount64`| -|`__crtGetTimeFormatEx`| -|`__crtGetUserDefaultLocaleName`| -|`__crtInitializeCriticalSectionEx`| -|`__crtIsPackagedApp`| -|`__crtIsValidLocaleName`| -|`__crtLCMapStringA`| -|`__crtLCMapStringEx`| -|[`__crtLCMapStringW`](../c-runtime-library/crtlcmapstringw.md)| -|`_CrtSetCheckCount`| -|`_CrtSetDbgBlockType`| -|`__crtSetFileInformationByHandle`| -|`__crtSetThreadStackGuarantee`| -|`__crtSetUnhandledExceptionFilter`| -|`__crtSleep`| -|`__crtTerminateProcess`| -|`__crtUnhandledException`| -|`__CxxDetectRethrow`| -|`__CxxExceptionFilter`| -|[`__CxxFrameHandler`](../c-runtime-library/cxxframehandler.md)| -|`__CxxFrameHandler2`| -|`__CxxFrameHandler3`| -|`__CxxLongjmpUnwind`| -|`__CxxQueryExceptionSize`| -|`__CxxRegisterExceptionObject`| -|`_CxxThrowException`| -|`__CxxUnregisterExceptionObject`| -|`__daylight`| -|`_dclass`| -|`__DestructExceptionObject`| -|[`__dllonexit`](../c-runtime-library/dllonexit.md)| -|`__doserrno`| -|`_dosmaperr`| -|`_dpcomp`| -|`_dsign`| -|`__dstbias`| -|`_dtest`| -|`_EH_prolog`| -|`_errno`| -|`_except_handler2`| -|[`_except_handler3`](../c-runtime-library/except-handler3.md)| -|`_except_handler4_common`| -|`_except1`| -|[`_execute_onexit_table`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_fdclass`| -|`_fdpcomp`| -|`_fdsign`| -|`_fdtest`| -|`_filbuf`| -|`_FindAndUnlinkFrame`| -|`_flsbuf`| -|`__fpe_flt_rounds`| -|`_FPE_Raise`| -|`__fpecode`| -|`__FrameUnwindFilter`| -|`_fread_nolock_s`| -|`_free_base`| -|`__free_locale`| -|`_freea_s`| -|`_freefls`| -|`_ftol`| -|`__get_current_locale`| -|`__get_flsindex`| -|`_get_initial_narrow_environment`| -|`_get_initial_wide_environment`| -|`_get_narrow_winmain_command_line`| -|`_get_stream_buffer_pointers`| -|`__get_tlsindex`| -|`_get_wide_winmain_command_line`| -|`_Getdays`| -|[`__getmainargs`](../c-runtime-library/getmainargs-wgetmainargs.md)| -|`_Getmonths`| -|`__GetPlatformExceptionInfo`| -|`_getptd`| -|`_Gettnames`| -|`_global_unwind2`| -|`_inconsistency`| -|`_initialize_lconv_for_unsigned_char`| -|`_initialize_narrow_environment`| -|[`_initialize_onexit_table`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_initialize_wide_environment`| -|`_initptd`| -|`_invalid_parameter`| -|`_invoke_watson`| -|`__iob_func`| -|`_IsExceptionObjectToBeDestroyed`| -|[`___lc_codepage_func`](../c-runtime-library/lc-codepage-func.md)| -|[`___lc_collate_cp_func`](../c-runtime-library/lc-collate-cp-func.md)| -|[`___lc_locale_name_func`](../c-runtime-library/lc-locale-name-func.md)| -|`__lconv_init`| -|`_ldclass`| -|`_ldpcomp`| -|`_ldsign`| -|`_ldtest`| -|`__libm_sse2_acos`| -|`_libm_sse2_acos_precise`| -|`__libm_sse2_acosf`| -|`__libm_sse2_asin`| -|`_libm_sse2_asin_precise`| -|`__libm_sse2_asinf`| -|`__libm_sse2_atan`| -|`_libm_sse2_atan_precise`| -|`__libm_sse2_atan2`| -|`__libm_sse2_atanf`| -|`__libm_sse2_cos`| -|`_libm_sse2_cos_precise`| -|`__libm_sse2_cosf`| -|`__libm_sse2_exp`| -|`_libm_sse2_exp_precise`| -|`__libm_sse2_expf`| -|`__libm_sse2_log`| -|`_libm_sse2_log_precise`| -|`__libm_sse2_log10`| -|`_libm_sse2_log10_precise`| -|`__libm_sse2_log10f`| -|`__libm_sse2_logf`| -|`__libm_sse2_pow`| -|`_libm_sse2_pow_precise`| -|`__libm_sse2_powf`| -|`__libm_sse2_sin`| -|`_libm_sse2_sin_precise`| -|`__libm_sse2_sinf`| -|`_libm_sse2_sqrt_precise`| -|`__libm_sse2_tan`| -|`_libm_sse2_tan_precise`| -|`__libm_sse2_tanf`| -|[`_local_unwind2`](../c-runtime-library/local-unwind2.md)| -|`_local_unwind4`| -|`_lock_locales`| -|`_longjmpex`| -|`_malloc_base`| -|[`___mb_cur_max_func`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|[`___mb_cur_max_l_func`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`_mbctype`| -|`_NLG_Dispatch2`| -|`_NLG_Return`| -|`_NLG_Return2`| -|`__p___argc`| -|`__p___argv`| -|`__p___initenv`| -|[`__p___mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`__p___wargv`| -|`__p___winitenv`| -|`__p__acmdln`| -|[`__p__commode`](../c-runtime-library/p-commode.md)| -|`__p__crtAssertBusy`| -|`__p__crtBreakAlloc`| -|`__p__crtDbgFlag`| -|`__p__daylight`| -|`__p__dstbias`| -|`__p__environ`| -|[`__p__fmode`](../c-runtime-library/p-fmode.md)| -|`__p__iob`| -|`__p__mbcasemap`| -|`__p__mbctype`| -|`__p__pctype`| -|`__p__pgmptr`| -|`__p__pwctype`| -|`__p__timezone`| -|`__p__tzname`| -|`__p__wcmdln`| -|`__p__wenviron`| -|`__p__wpgmptr`| -|`_pctype`| -|[`__pctype_func`](../c-runtime-library/pctype-func.md)| -|`_pwctype`| -|`__pwctype_func`| -|`__pxcptinfoptrs`| -|`_query_app_type`| -|`_realloc_base`| -|[`_register_onexit_function`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_register_thread_local_exe_atexit_callback`| -|`__report_gsfailure`| -|`__RTCastToVoid`| -|[`__RTDynamicCast`](../c-runtime-library/rtdynamiccast.md)| -|`__RTtypeid`| -|`_seh_filter_dll`| -|`_seh_filter_exe`| -|`_seh_longjmp_unwind`| -|`_seh_longjmp_unwind4`| -|[`__set_app_type`](../c-runtime-library/internal-set-app-type.md)| -|`_set_malloc_crt_max_wait`| -|[`_setjmp3`](../c-runtime-library/setjmp3.md)| -|`__setlc_active`| -|[`___setlc_active_func`](../c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md)| -|[`__setusermatherr`](../c-runtime-library/setusermatherr.md)| -|`_SetWinRTOutOfMemoryExceptionCallback`| -|`_sopen_dispatch`| -|`__std_exception_copy`| -|`__std_exception_destroy`| -|`__std_type_info_destroy_list`| -|`__std_type_info_name`| -|`__stdio_common_vfprintf`| -|`__stdio_common_vfprintf_p`| -|`__stdio_common_vfprintf_s`| -|`__stdio_common_vfscanf`| -|`__stdio_common_vfwprintf`| -|`__stdio_common_vfwprintf_p`| -|`__stdio_common_vfwprintf_s`| -|`__stdio_common_vfwscanf`| -|`__stdio_common_vsnprintf_s`| -|`__stdio_common_vsnwprintf_s`| -|`__stdio_common_vsprintf`| -|`__stdio_common_vsprintf_p`| -|`__stdio_common_vsprintf_s`| -|`__stdio_common_vsscanf`| -|`__stdio_common_vswprintf`| -|`__stdio_common_vswprintf_p`| -|`__stdio_common_vswprintf_s`| -|`__stdio_common_vswscanf`| -|`_Strftime`| -|`__STRINGTOLD`| -|`__STRINGTOLD_L`| -|`__strncnt`| -|`__sys_errlist`| -|`__sys_nerr`| -|`__threadhandle`| -|`__threadid`| -|`__timezone`| -|`__TypeMatch`| -|`__tzname`| -|`__unDName`| -|`__unDNameEx`| -|`__unDNameHelper`| -|`__unguarded_readlc_active`| -|[`___unguarded_readlc_active_add_func`](../c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md)| -|`_unloaddll`| -|`_unlock_locales`| -|`_vacopy`| -|`_ValidateExecute`| -|`_ValidateRead`| -|`_ValidateWrite`| -|`_VCrtDbgReportA`| -|`_VCrtDbgReportW`| -|`_W_Getdays`| -|`_W_Getmonths`| -|`_W_Getnames`| -|`_W_Gettnames`| -|`_wassert`| -|`_Wcsftime`| -|`__wcsncnt`| -|[`__wgetmainargs`](../c-runtime-library/getmainargs-wgetmainargs.md)| -|`_wsopen_dispatch`| -|`_Xbad_alloc`| -|`_Xlength_error`| +| Name | +|---| +| `__acrt_iob_func` | +| `__AdjustPointer` | +| `__BuildCatchObject` | +| `__BuildCatchObjectHelper` | +| [`__C_specific_handler`](/windows/win32/devnotes/--c-specific-handler2) | +| `_calloc_base` | +| `_chkesp` | +| `__chkstk` | +| `_chkstk` | +| `_chvalidator` | +| `_chvalidator_l` | +| `_CIacos` | +| `_CIasin` | +| [`_CIatan`](./ciatan.md) | +| [`_CIatan2`](./ciatan2.md) | +| [`_CIcos`](./cicos.md) | +| `_CIcosh` | +| [`_CIexp`](./ciexp.md) | +| [`_CIfmod`](./cifmod.md) | +| [`_CIlog`](./cilog.md) | +| [`_CIlog10`](./cilog10.md) | +| [`_CIpow`](./cipow.md) | +| [`_CIsin`](./cisin.md) | +| `_CIsinh` | +| [`_CIsqrt`](./cisqrt.md) | +| [`_CItan`](./citan.md) | +| `_CItanh` | +| `__clean_type_info_names_internal` | +| `_configure_narrow_argv` | +| `_configure_wide_argv` | +| `__conio_common_vcprintf` | +| `__conio_common_vcprintf_p` | +| `__conio_common_vcprintf_s` | +| `__conio_common_vcscanf` | +| `__conio_common_vcwprintf` | +| `__conio_common_vcwprintf_p` | +| `__conio_common_vcwprintf_s` | +| `__conio_common_vcwscanf` | +| `__CppXcptFilter` | +| `__create_locale` | +| `_crt_atexit` | +| `_crt_at_quick_exit` | +| `__crtCompareStringA` | +| `__crtCompareStringEx` | +| `__crtCompareStringW` | +| `__crtCreateEventExW` | +| `__crtCreateSemaphoreExW` | +| `__crtCreateSymbolicLinkW` | +| `_crt_debugger_hook` | +| `__crtEnumSystemLocalesEx` | +| `__crtFlsAlloc` | +| `__crtFlsFree` | +| `__crtFlsGetValue` | +| `__crtFlsSetValue` | +| `_CrtGetCheckCount` | +| `__crtGetDateFormatEx` | +| `__crtGetFileInformationByHandleEx` | +| `__crtGetLocaleInfoEx` | +| `__crtGetShowWindowMode` | +| `__crtGetTickCount64` | +| `__crtGetTimeFormatEx` | +| `__crtGetUserDefaultLocaleName` | +| `__crtInitializeCriticalSectionEx` | +| `__crtIsPackagedApp` | +| `__crtIsValidLocaleName` | +| `__crtLCMapStringA` | +| `__crtLCMapStringEx` | +| [`__crtLCMapStringW`](./crtlcmapstringw.md) | +| `_CrtSetCheckCount` | +| `_CrtSetDbgBlockType` | +| `__crtSetFileInformationByHandle` | +| `__crtSetThreadStackGuarantee` | +| `__crtSetUnhandledExceptionFilter` | +| `__crtSleep` | +| `__crtTerminateProcess` | +| `__crtUnhandledException` | +| `__CxxDetectRethrow` | +| `__CxxExceptionFilter` | +| [`__CxxFrameHandler`](./cxxframehandler.md) | +| `__CxxFrameHandler2` | +| `__CxxFrameHandler3` | +| `__CxxLongjmpUnwind` | +| `__CxxQueryExceptionSize` | +| `__CxxRegisterExceptionObject` | +| `_CxxThrowException` | +| `__CxxUnregisterExceptionObject` | +| [`_dclass`](./reference/floating-point-primitives.md) | +| `__DestructExceptionObject` | +| [`__dllonexit`](./dllonexit.md) | +| `__doserrno` | +| `_dosmaperr` | +| [`_dpcomp`](./reference/floating-point-primitives.md) | +| [`_dsign`](./reference/floating-point-primitives.md) | +| [`__dstbias`](./reference/get-dstbias.md) | +| [`_dtest`](./reference/floating-point-primitives.md) | +| `_EH_prolog` | +| [`_errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) | +| `_except_handler` | +| `_except_handler2` | +| [`_except_handler3`](./except-handler3.md) | +| `_except_handler4_common` | +| `_except1` | +| [`_execute_onexit_table`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| [`_fdclass`](./reference/floating-point-primitives.md) | +| [`_fdpcomp`](./reference/floating-point-primitives.md) | +| [`_fdsign`](./reference/floating-point-primitives.md) | +| [`_fdtest`](./reference/floating-point-primitives.md) | +| `_filbuf` | +| `_FindAndUnlinkFrame` | +| `_flsbuf` | +| `__fpe_flt_rounds` | +| `_FPE_Raise` | +| `__fpecode` | +| `__FrameUnwindFilter` | +| `_fread_nolock_s` | +| `_free_base` | +| `__free_locale` | +| `_freea_s` | +| `_freefls` | +| `_ftol` | +| `__get_current_locale` | +| `__get_flsindex` | +| `_get_initial_narrow_environment` | +| `_get_initial_wide_environment` | +| `_get_narrow_winmain_command_line` | +| `_get_stream_buffer_pointers` | +| `__get_tlsindex` | +| `_get_wide_winmain_command_line` | +| `_Getdays` | +| [`__getmainargs`](./getmainargs-wgetmainargs.md) | +| `_Getmonths` | +| `__GetPlatformExceptionInfo` | +| `_getptd` | +| `_Gettnames` | +| `_global_unwind2` | +| `_inconsistency` | +| `_initialize_lconv_for_unsigned_char` | +| `_initialize_narrow_environment` | +| [`_initialize_onexit_table`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| `_initialize_wide_environment` | +| `_initptd` | +| `_invalid_parameter` | +| `_invoke_watson` | +| `__iob_func` | +| `_IsExceptionObjectToBeDestroyed` | +| [`___lc_codepage_func`](./lc-codepage-func.md) | +| [`___lc_collate_cp_func`](./lc-collate-cp-func.md) | +| [`___lc_locale_name_func`](./lc-locale-name-func.md) | +| `__lconv_init` | +| [`_ldclass`](./reference/floating-point-primitives.md) | +| [`_ldpcomp`](./reference/floating-point-primitives.md) | +| [`_ldsign`](./reference/floating-point-primitives.md) | +| [`_ldtest`](./reference/floating-point-primitives.md) | +| `__libm_sse2_acos` | +| `_libm_sse2_acos_precise` | +| `__libm_sse2_acosf` | +| `__libm_sse2_asin` | +| `_libm_sse2_asin_precise` | +| `__libm_sse2_asinf` | +| `__libm_sse2_atan` | +| `_libm_sse2_atan_precise` | +| `__libm_sse2_atan2` | +| `__libm_sse2_atanf` | +| `__libm_sse2_cos` | +| `_libm_sse2_cos_precise` | +| `__libm_sse2_cosf` | +| `__libm_sse2_exp` | +| `_libm_sse2_exp_precise` | +| `__libm_sse2_expf` | +| `__libm_sse2_log` | +| `_libm_sse2_log_precise` | +| `__libm_sse2_log10` | +| `_libm_sse2_log10_precise` | +| `__libm_sse2_log10f` | +| `__libm_sse2_logf` | +| `__libm_sse2_pow` | +| `_libm_sse2_pow_precise` | +| `__libm_sse2_powf` | +| `__libm_sse2_sin` | +| `_libm_sse2_sin_precise` | +| `__libm_sse2_sinf` | +| `_libm_sse2_sqrt_precise` | +| `__libm_sse2_tan` | +| `_libm_sse2_tan_precise` | +| `__libm_sse2_tanf` | +| [`_local_unwind2`](./local-unwind2.md) | +| `_local_unwind4` | +| `_lock_locales` | +| `_longjmpex` | +| `_malloc_base` | +| [`___mb_cur_max_func`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| [`___mb_cur_max_l_func`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `_mbctype` | +| `_NLG_Dispatch2` | +| `_NLG_Return` | +| `_NLG_Return2` | +| `__p___argc` | +| `__p___argv` | +| `__p___initenv` | +| [`__p___mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `__p___wargv` | +| `__p___winitenv` | +| `__p__acmdln` | +| [`__p__commode`](./p-commode.md) | +| `__p__crtAssertBusy` | +| `__p__crtBreakAlloc` | +| `__p__crtDbgFlag` | +| `__p__daylight` | +| `__p__dstbias` | +| `__p__environ` | +| [`__p__fmode`](./p-fmode.md) | +| `__p__iob` | +| `__p__mbcasemap` | +| `__p__mbctype` | +| `__p__pctype` | +| `__p__pgmptr` | +| `__p__pwctype` | +| `__p__timezone` | +| `__p__tzname` | +| `__p__wcmdln` | +| `__p__wenviron` | +| `__p__wpgmptr` | +| [`_pctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | +| [`__pctype_func`](./pctype-func.md) | +| [`_pwctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | +| `__pwctype_func` | +| `__pxcptinfoptrs` | +| `_query_app_type` | +| `_realloc_base` | +| [`_register_onexit_function`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| `_register_thread_local_exe_atexit_callback` | +| `__report_gsfailure` | +| `__RTCastToVoid` | +| [`__RTDynamicCast`](./rtdynamiccast.md) | +| `__RTtypeid` | +| `_seh_filter_dll` | +| `_seh_filter_exe` | +| `_seh_longjmp_unwind` | +| `_seh_longjmp_unwind4` | +| [`__set_app_type`](./internal-set-app-type.md) | +| `_set_malloc_crt_max_wait` | +| [`_setjmp3`](./setjmp3.md) | +| `__setlc_active` | +| [`___setlc_active_func`](./setlc-active-func-unguarded-readlc-active-add-func.md) | +| [`__setusermatherr`](./setusermatherr.md) | +| `_SetWinRTOutOfMemoryExceptionCallback` | +| `_sopen_dispatch` | +| `__std_exception_copy` | +| `__std_exception_destroy` | +| `__std_type_info_destroy_list` | +| `__std_type_info_name` | +| `__stdio_common_vfprintf` | +| `__stdio_common_vfprintf_p` | +| `__stdio_common_vfprintf_s` | +| `__stdio_common_vfscanf` | +| `__stdio_common_vfwprintf` | +| `__stdio_common_vfwprintf_p` | +| `__stdio_common_vfwprintf_s` | +| `__stdio_common_vfwscanf` | +| `__stdio_common_vsnprintf_s` | +| `__stdio_common_vsnwprintf_s` | +| `__stdio_common_vsprintf` | +| `__stdio_common_vsprintf_p` | +| `__stdio_common_vsprintf_s` | +| `__stdio_common_vsscanf` | +| `__stdio_common_vswprintf` | +| `__stdio_common_vswprintf_p` | +| `__stdio_common_vswprintf_s` | +| `__stdio_common_vswscanf` | +| `_Strftime` | +| `__STRINGTOLD` | +| `__STRINGTOLD_L` | +| `__strncnt` | +| `__sys_errlist` | +| `__sys_nerr` | +| `__threadhandle` | +| `__threadid` | +| `__timezone` | +| `__TypeMatch` | +| `__tzname` | +| `__unDName` | +| `__unDNameEx` | +| `__unDNameHelper` | +| `__unguarded_readlc_active` | +| [`___unguarded_readlc_active_add_func`](./setlc-active-func-unguarded-readlc-active-add-func.md) | +| `_unloaddll` | +| `_unlock_locales` | +| `_vacopy` | +| `_ValidateExecute` | +| `_ValidateRead` | +| `_ValidateWrite` | +| `_VCrtDbgReportA` | +| `_VCrtDbgReportW` | +| `_W_Getdays` | +| `_W_Getmonths` | +| `_W_Getnames` | +| `_W_Gettnames` | +| `_Wcsftime` | +| `__wcsncnt` | +| [`__wgetmainargs`](./getmainargs-wgetmainargs.md) | +| `_wsopen_dispatch` | +| `_Xbad_alloc` | +| `_Xlength_error` | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/internal-set-app-type.md b/docs/c-runtime-library/internal-set-app-type.md index 9a86584f3a..9faaf4a49e 100644 --- a/docs/c-runtime-library/internal-set-app-type.md +++ b/docs/c-runtime-library/internal-set-app-type.md @@ -10,9 +10,9 @@ f1_keywords: ["__set_app_type"] helpviewer_keywords: ["__set_app_type"] ms.assetid: f0ac0f4d-70e6-4e96-9e43-eb9d1515490c --- -# __set_app_type +# `__set_app_type` -Sets the current application type. +Sets the current application type. This internal function is obsolete. ## Syntax @@ -22,21 +22,21 @@ void __set_app_type ( ) ``` -#### Parameters +### Parameters -*at*
+*`at`*\ A value that indicates the application type. The possible values are: -|Value|Description| -|-----------|-----------------| -|_UNKNOWN_APP|Unknown application type.| -|_CONSOLE_APP|Console (command-line) application.| -|_GUI_APP|GUI (Windows) application.| +| Value | Description | +|---|---| +| `_UNKNOWN_APP` | Unknown application type. | +| `_CONSOLE_APP` | Console (command-line) application. | +| `_GUI_APP` | GUI (Windows) application. | ## Remarks ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__set_app_type|internal.h| +| Routine | Required header | +|---|---| +| **`__set_app_type`** | `internal.h` | diff --git a/docs/c-runtime-library/internationalization.md b/docs/c-runtime-library/internationalization.md index e22e191549..e66a9a923f 100644 --- a/docs/c-runtime-library/internationalization.md +++ b/docs/c-runtime-library/internationalization.md @@ -11,7 +11,7 @@ ms.assetid: ee536a04-3558-4729-8e10-6dabcde055fd The Microsoft runtime library provides many routines that you can use to customize your app for international markets such as: -- [locale-related routines](../c-runtime-library/locale.md) +- [locale-related routines](./locale.md) - wide-character routines - multibyte-character routines - generic-text routines @@ -24,4 +24,4 @@ ISO646 operator alternatives are also included. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md b/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md index d33d043d0e..63a877ee60 100644 --- a/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md +++ b/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md @@ -8,27 +8,27 @@ ms.assetid: da9150de-70ea-4d2f-90e6-ddb9202dd80b --- # Interpretation of multibyte-character sequences -Most multibyte-character routines in the Microsoft run-time library recognize multibyte-character sequences relating to a multibyte code page. The output value is affected by the setting of the **LC_CTYPE** category setting of the locale. For more information, see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior. The versions with the **_l** suffix are identical, except they use the locale parameter instead of the current locale. +Most multibyte-character routines in the Microsoft run-time library recognize multibyte-character sequences relating to a multibyte code page. The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior. The versions with the `_l` suffix are identical, except they use the locale parameter instead of the current locale. ## Locale-dependent multibyte routines -|Routine|Use| -|-------------|---------| -|[_mbclen, mblen, _mblen_l](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Validate and return number of bytes in multibyte character| -|[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)|For multibyte character strings: validate each character in string; return string length. For wide character strings: return string length.| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md), [mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters| -|[mbtowc, _mbtowc_l](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md), [wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md), [wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character| +| Routine | Use | +|---|---| +| [`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md) | Validate and return number of bytes in multibyte character | +| [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](./reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | For multibyte character strings: validate each character in string; return string length. For wide character strings: return string length. | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | +| [`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | ## Locale-independent multibyte routines -|Routine|Use| -|-------------|---------| -|[mbrtoc16, mbrtoc32](../c-runtime-library/reference/mbrtoc16-mbrtoc323.md)|Convert multibyte UTF-8 character to equivalent UTF-16 or UTF-32 character| -|[c16rtomb, c32rtomb](../c-runtime-library/reference/c16rtomb-c32rtomb1.md)|Convert UTF-16 or UTF-32 character to equivalent UTF-8 multibyte character| +| Routine | Use | +|---|---| +| [`mbrtoc16`, `mbrtoc32`](./reference/mbrtoc16-mbrtoc323.md) | Convert multibyte UTF-8 character to equivalent UTF-16 or UTF-32 character | +| [`c16rtomb`, `c32rtomb`](./reference/c16rtomb-c32rtomb1.md) | Convert UTF-16 or UTF-32 character to equivalent UTF-8 multibyte character | ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/iob.md b/docs/c-runtime-library/iob.md index 14418570e9..9341f6b617 100644 --- a/docs/c-runtime-library/iob.md +++ b/docs/c-runtime-library/iob.md @@ -1,29 +1,32 @@ --- description: "Learn more about: _iob" title: "_iob" -ms.date: "11/04/2016" +ms.date: 07/10/2023 api_name: ["_iob"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_iob", "iob"] +f1_keywords: ["_iob", "_IOB_ENTRIES", "STDIO/_IOB_ENTRIES"] helpviewer_keywords: ["_iob global variable", "iob global variable"] -ms.assetid: 008ed376-8078-4bbd-bc6c-0677c63d0ff1 --- -# _iob +# `_iob` -The array of stdio control structures. +The array of `stdio` control structures. ## Syntax -``` +```C FILE _iob[_IOB_ENTRIES]; ``` ## Remarks -`IOB_ENTRIES` is defined as 20 in stdio.h. +Starting with Visual Studio 2015, `_IOB_ENTRIES` is defined as 3 with the introduction of the Universal CRT. +It was previously defined as 20. + +Defined in `stdio.h`. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](./global-variables.md)\ +[Introducing the Universal CRT](https://devblogs.microsoft.com/cppblog/introducing-the-universal-crt/) diff --git a/docs/c-runtime-library/is-isw-routines.md b/docs/c-runtime-library/is-isw-routines.md index d4bd8bd11d..749a96439b 100644 --- a/docs/c-runtime-library/is-isw-routines.md +++ b/docs/c-runtime-library/is-isw-routines.md @@ -1,36 +1,29 @@ --- -description: "Learn more about: is, isw Routines" title: "is, isw Routines" -ms.date: "11/04/2016" -api_location: ["msvcr110_clr0400.dll", "msvcr90.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110.dll", "msvcr120.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["isw", "is"] +description: "Learn more about: is, isw Routines" +ms.date: 01/11/2022 helpviewer_keywords: ["is routines", "isw routines"] -ms.assetid: 1e171a57-2cde-41f6-a75f-a080fa3c12e5 --- -# is, isw Routines +# `is`, `isw` routines :::row::: :::column span=""::: - [isalnum, iswalnum, _isalnum_l, _iswalnum_l](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md)\ - [isalpha, iswalpha, _isalpha_l, _iswalpha_l](../c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md)\ - [isascii, __isascii, iswascii](../c-runtime-library/reference/isascii-isascii-iswascii.md)\ - [isblank, iswblank, _isblank_l, _iswblank_l](../c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md)\ - [iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)\ - [iscsym, iscsymf, __iscsym, \__iswcsym, \__iscsymf, \__iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l](../c-runtime-library/reference/iscsym-functions.md)\ - [_isctype, iswctype, _isctype_l, _iswctype_l](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)\ - [isdigit, iswdigit, _isdigit_l, _iswdigit_l](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md) - :::column-end::: - :::column span=""::: - [isgraph, iswgraph, _isgraph_l, _iswgraph_l](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md)\ - [isleadbyte, _isleadbyte_l](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md)\ - [islower, iswlower, _islower_l, _iswlower_l](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md)\ - [isprint, iswprint, _isprint_l, _iswprint_l](../c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md)\ - [ispunct, iswpunct, _ispunct_l, _iswpunct_l](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md)\ - [isspace, iswspace, _isspace_l, _iswspace_l](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md)\ - [isupper, _isupper_l, iswupper, _iswupper_l](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md)\ - [isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) + [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md)\ + [`isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l`](./reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md)\ + [`isascii`, `__isascii`, `iswascii`](./reference/isascii-isascii-iswascii.md)\ + [`isblank`, `iswblank`, `_isblank_l`, `_iswblank_l`](./reference/isblank-iswblank-isblank-l-iswblank-l.md)\ + [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)\ + [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md)\ + [`_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l`](./reference/isctype-iswctype-isctype-l-iswctype-l.md)\ + [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md)\ + [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md)\ + [`isleadbyte`, `_isleadbyte_l`](./reference/isleadbyte-isleadbyte-l.md)\ + [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md)\ + [`isprint`, `iswprint`, `_isprint_l`, `_iswprint_l`](./reference/isprint-iswprint-isprint-l-iswprint-l.md)\ + [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md)\ + [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md)\ + [`isupper`, `_isupper_l`, `iswupper`, `_iswupper_l`](./reference/isupper-isupper-l-iswupper-iswupper-l.md)\ + [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) :::column-end::: :::row-end::: @@ -38,128 +31,128 @@ ms.assetid: 1e171a57-2cde-41f6-a75f-a080fa3c12e5 These routines test characters for specified conditions. -The **is** routines produce meaningful results for any integer argument from -1 (`EOF`) to **UCHAR_MAX** (0xFF), inclusive. The expected argument type is **`int`**. +The `is` routines produce meaningful results for any integer argument from -1 (`EOF`) to `UCHAR_MAX` (0xFF), inclusive. The expected argument type is **`int`**. > [!CAUTION] -> For the **is** routines, passing an argument of type **`char`** may yield unpredictable results. An SBCS or MBCS single-byte character of type **`char`** with a value greater than 0x7F is negative. If a **`char`** is passed, the compiler may convert the value to a **`signed int`** or a **`signed long`**. This value may be sign-extended by the compiler, with unexpected results. +> For the `is` routines, passing an argument of type **`char`** may yield unpredictable results. An SBCS or MBCS single-byte character of type **`char`** with a value greater than 0x7F is negative. If a **`char`** is passed, the compiler may convert the value to a **`signed int`** or a **`signed long`**. This value may be sign-extended by the compiler, with unexpected results. -The **isw** routines produce meaningful results for any integer value from - 1 (**WEOF**) to 0xFFFF, inclusive. The **wint_t** data type is defined in WCHAR.H as an **`unsigned short`**; it can hold any wide character or the wide-character end-of-file (**WEOF**) value. +The `isw` routines produce meaningful results for any integer value from -1 (`WEOF`) to 0xFFFF, inclusive. The `wint_t` data type is defined in `` as an **`unsigned short`**. It can hold any wide character or the wide-character end-of-file (`WEOF`) value. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. -In the "C" locale, the test conditions for the **is** routines are as follows: +In the "C" locale, the test conditions for the `is` routines are as follows: -`isalnum`
+`isalnum`\ Alphanumeric (A - Z, a - z, or 0 - 9). -`isalpha`
+`isalpha`\ Alphabetic (A - Z or a - z). -`__isascii`
+`__isascii`\ ASCII character (0x00 - 0x7F). -`isblank`
+`isblank`\ Horizontal tab or space character (0x09 or 0x20). -`iscntrl`
+`iscntrl`\ Control character (0x00 - 0x1F or 0x7F). -`__iscsym`
+`__iscsym`\ Letter, underscore, or digit. -`__iscsymf`
+`__iscsymf`\ Letter or underscore. -`isdigit`
+`isdigit`\ Decimal digit (0 - 9). -`isgraph`
-Printable character except space ( ). +`isgraph`\ +Printable character except space (0x20). -`islower`
+`islower`\ Lowercase letter (a - z). -`isprint`
+`isprint`\ Printable character including space (0x20 - 0x7E). -`ispunct`
+`ispunct`\ Punctuation character. -`isspace`
+`isspace`\ White-space character (0x09 - 0x0D or 0x20). -`isupper`
+`isupper`\ Uppercase letter (A - Z). -`isxdigit`
+`isxdigit`\ Hexadecimal digit (A - F, a - f, or 0 - 9). -For the **isw** routines, the result of the test for the specified condition is independent of locale. The test conditions for the **isw** functions are as follows: +For the `isw` routines, the result of the test for the specified condition is independent of locale. The test conditions for the `isw` functions are as follows: -`iswalnum`
+`iswalnum`\ `iswalpha` or `iswdigit`. -`iswalpha`
+`iswalpha`\ Any wide character that is one of an implementation-defined set for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. `iswalpha` returns nonzero only for wide characters for which `iswupper` or `iswlower` is nonzero. -`iswascii`
+`iswascii`\ Wide-character representation of ASCII character (0x0000 - 0x007F). -`iswblank`
-Wide character that corresponds to the standard space character or is one of an implementation-defined set of wide characters for which `iswalnum` is false. Standard blank characters are space (L' ') and horizontal tab (L'\t'). +`iswblank`\ +Wide character that corresponds to the standard space character or is one of an implementation-defined set of wide characters for which `iswalnum` is false. Standard blank characters are space (`L' '`) and horizontal tab (`L'\t'`). -`iswcntrl`
+`iswcntrl`\ Control wide character. -`__iswcsym`
+`__iswcsym`\ Any wide character for which `isalnum` is true, or the '_' character. -`__iswcsymf`
+`__iswcsymf`\ Any wide character for which `iswalpha` is true, or the '_' character. -`iswctype`
-Character has property specified by the `desc` argument. For each valid value of the `desc` argument of `iswctype`, there is an equivalent wide-character classification routine, as shown in the following table: - -### Equivalence of iswctype(c, desc) to Other isw Testing Routines - -|Value of *desc* argument|iswctype( *c, desc* ) equivalent| -|------------------------------|----------------------------------------| -|**_ALPHA**|**iswalpha(** `c` **)**| -|**_ALPHA** | **_DIGIT**|**iswalnum(** `c` **)**| -|**_BLANK**|**iswblank(** `c` **)**| -|**_CONTROL**|**iswcntrl(** `c` **)**| -|**_DIGIT**|**iswdigit(** `c` **)**| -|**_ALPHA** | **_DIGIT** | **_PUNCT**|**iswgraph(** `c` **)**| -|**_LOWER**|**iswlower(** `c` **)**| -|**_ALPHA** | **_BLANK** | **_DIGIT** | **_PUNCT**|**iswprint(** `c` **)**| -|**_PUNCT**|**iswpunct(** `c` **)**| -|**_BLANK**|**iswblank(** `c` **)**| -|**_SPACE**|**iswspace(** `c` **)**| -|**_UPPER**|**iswupper(** `c` **)**| -|**_HEX**|**iswxdigit(** `c` **)**| - -`iswdigit`
+`iswctype`\ +Character has property specified by the `desc` argument. For each valid value of the `desc` argument of `iswctype`, there's an equivalent wide-character classification routine, as shown in the following table: + +### Equivalence of `iswctype(c, desc)` to other `isw` testing routines + +| Value of *`desc`* argument | `iswctype(c, desc)` equivalent | +|--|--| +| `_ALPHA` | `iswalpha(c)` | +| `_ALPHA | _DIGIT` | `iswalnum(c)` | +| `_BLANK` | `iswblank(c)` | +| `_CONTROL` | `iswcntrl(c)` | +| `_DIGIT` | `iswdigit(c)` | +| `_ALPHA | _DIGIT | _PUNCT` | `iswgraph(c)` | +| `_LOWER` | `iswlower(c)` | +| `_ALPHA | _BLANK | _DIGIT | _PUNCT` | `iswprint(c)` | +| `_PUNCT` | `iswpunct(c)` | +| `_BLANK` | `iswblank(c)` | +| `_SPACE` | `iswspace(c)` | +| `_UPPER` | `iswupper(c)` | +| `_HEX` | `iswxdigit(c)` | + +`iswdigit`\ Wide character corresponding to a decimal-digit character. -`iswgraph`
-Printable wide character except space wide character (L' '). +`iswgraph`\ +Printable wide character except space wide character (`L' '`). -`iswlower`
+`iswlower`\ Lowercase letter, or one of implementation-defined set of wide characters for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. `iswlower` returns nonzero only for wide characters that correspond to lowercase letters. -`iswprint`
-Printable wide character, including space wide character (L' '). +`iswprint`\ +Printable wide character, including space wide character (`L' '`). -`iswpunct`
-Printable wide character that is neither space wide character (L' ') nor wide character for which `iswalnum` is nonzero. +`iswpunct`\ +Printable wide character that's both not a space wide character (`L' '`) and not a wide character for which `iswalnum` is nonzero. -`iswspace`
-Wide character that corresponds to standard white-space character or is one of implementation-defined set of wide characters for which `iswalnum` is false. Standard white-space characters are: space (L' '), form feed (L'\f'), newline (L'\n'), carriage return (L'\r'), horizontal tab (L'\t'), and vertical tab (L'\v'). +`iswspace`\ +Wide character that corresponds to standard white-space character or is one of implementation-defined set of wide characters for which `iswalnum` is false. Standard white-space characters are: space (`L' '`), form feed (`L'\f'`), newline (`L'\n'`), carriage return (`L'\r'`), horizontal tab (`L'\t'`), and vertical tab (`L'\v'`). -`iswupper`
+`iswupper`\ Wide character that is uppercase or is one of an implementation-defined set of wide characters for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. `iswupper` returns nonzero only for wide characters that correspond to uppercase characters. -`iswxdigit`
+`iswxdigit`\ Wide character that corresponds to a hexadecimal-digit character. ## Example @@ -335,8 +328,8 @@ int main( void ) ## See also -[Character Classification](../c-runtime-library/character-classification.md)
-[Locale](../c-runtime-library/locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[Interpretation of Multibyte-Character Sequences](../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[to Functions](../c-runtime-library/to-functions.md) +[Character classification](./character-classification.md)\ +[Locale](./locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[Interpretation of multibyte-character sequences](./interpretation-of-multibyte-character-sequences.md)\ +[`to` functions](./to-functions.md) diff --git a/docs/c-runtime-library/ismbb-routines.md b/docs/c-runtime-library/ismbb-routines.md index bd04c1557f..2d24fedf48 100644 --- a/docs/c-runtime-library/ismbb-routines.md +++ b/docs/c-runtime-library/ismbb-routines.md @@ -1,79 +1,72 @@ --- -description: "Learn more about: _ismbb Routines" -title: "_ismbb Routines" -ms.date: "11/04/2016" -api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_ismbb", "ismbb"] +description: "Learn more about: _ismbb routines" +title: "_ismbb routines" +ms.date: 01/11/2022 helpviewer_keywords: ["ismbb routines", "_ismbb routines"] -ms.assetid: d63c232e-3fe4-4844-aafd-2133846ece4b --- -# _ismbb Routines +# `_ismbb` routines -Tests the given integer value `c` for a particular condition, by using the current locale or a specified LC_CTYPE conversion state category. +Tests the given integer value `c` for a particular condition, by using the current locale or a specified `LC_CTYPE` conversion state category. :::row::: :::column span=""::: - [_ismbbalnum, _ismbbalnum_l](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md)\ - [_ismbbalpha, _ismbbalpha_l](../c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md)\ - [_ismbbblank, _ismbbblank_l](../c-runtime-library/reference/ismbbblank-ismbbblank-l.md)\ - [_ismbbgraph, _ismbbgraph_l](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md)\ - [_ismbbkalnum, _ismbbkalnum_l](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md)\ - [_ismbbkana, _ismbbkana_l](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md)\ - :::column-end::: - :::column span=""::: - [_ismbbkprint, _ismbbkprint_l](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md)\ - [_ismbbkpunct, _ismbbkpunct_l](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md)\ - [_ismbblead, _ismbblead_l](../c-runtime-library/reference/ismbblead-ismbblead-l.md)\ - [_ismbbprint, _ismbbprint_l](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md)\ - [_ismbbpunct, _ismbbpunct_l](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md)\ - [_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md)\ + [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md)\ + [`_ismbbalpha`, `_ismbbalpha_l`](./reference/ismbbalpha-ismbbalpha-l.md)\ + [`_ismbbblank`, `_ismbbblank_l`](./reference/ismbbblank-ismbbblank-l.md)\ + [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md)\ + [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md)\ + [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md)\ + [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md)\ + [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md)\ + [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md)\ + [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md)\ + [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md)\ + [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md)\ :::column-end::: :::row-end::: ## Remarks -Every routine in the `_ismbb` family tests the given integer value `c` for a particular condition. The test result depends on the multibyte code page that's in effect. By default, the multibyte code page is set to the ANSI code page that's obtained from the operating system at program startup. You can use [_getmbcp](../c-runtime-library/reference/getmbcp.md) to query for the multibyte code page that's in use, or [_setmbcp](../c-runtime-library/reference/setmbcp.md) to change it. +Every routine in the `_ismbb` family tests the given integer value `c` for a particular condition. The test result depends on the multibyte code page that's in effect. By default, the multibyte code page is set to the ANSI code page that's obtained from the operating system at program startup. You can use [`_getmbcp`](./reference/getmbcp.md) to query for the multibyte code page that's in use, or [`_setmbcp`](./reference/setmbcp.md) to change it. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions that don't have the **_l** suffix use the current locale for this locale-dependent behavior; the versions that do have the **_l** suffix are identical except that instead they use the locale parameter that's passed in. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that do have the **`_l`** suffix are identical except that instead they use the locale parameter that's passed in. The routines in the `_ismbb` family test the given integer `c` as follows. -|Routine|Byte test condition| -|-------------|-------------------------| -|[_ismbbalnum](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md)|`isalnum` || `_ismbbkalnum`.| -|[_ismbbalpha](reference/ismbbalpha-ismbbalpha-l.md)|`isalpha` || `_ismbbkalnum`.| -|[_ismbbblank](../c-runtime-library/reference/ismbbblank-ismbbblank-l.md)|`isblank`| -|[_ismbbgraph](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md)|Same as `_ismbbprint`, but `_ismbbgraph` does not include the space character (0x20).| -|[_ismbbkalnum](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md)|Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric.| -|[_ismbbkana](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md)|Katakana (0xA1 - 0xDF). Specific to code page 932.| -|[_ismbbkprint](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md)|Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF).| -|[_ismbbkpunct](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md)|Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation.| -|[_ismbblead](../c-runtime-library/reference/ismbblead-ismbblead-l.md)|First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC.| -|[_ismbbprint](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md)|`isprint` || `_ismbbkprint`. **ismbbprint** includes the space character (0x20).| -|[_ismbbpunct](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md)|`ispunct` || `_ismbbkpunct`.| -|[_ismbbtrail](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md)|Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC.| +| Routine | Byte test condition | +|--|--| +| [`_ismbbalnum`](./reference/ismbbalnum-ismbbalnum-l.md) | `isalnum(c) || _ismbbkalnum(c)` | +| [`_ismbbalpha`](reference/ismbbalpha-ismbbalpha-l.md) | `isalpha(c) || _ismbbkalpha(c)` | +| [`_ismbbblank`](./reference/ismbbblank-ismbbblank-l.md) | `isblank(c)` | +| [`_ismbbgraph`](./reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` doesn't include the space character (0x20) | +| [`_ismbbkalnum`](./reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | +| [`_ismbbkana`](./reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF). Specific to code page 932 | +| [`_ismbbkprint`](./reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF) | +| [`_ismbbkpunct`](./reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation | +| [`_ismbblead`](./reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC | +| [`_ismbbprint`](./reference/ismbbprint-ismbbprint-l.md) | `isprint(c) || _ismbbkprint(c)`. `ismbbprint` includes the space character (0x20) | +| [`_ismbbpunct`](./reference/ismbbpunct-ismbbpunct-l.md) | `ispunct(c) || _ismbbkpunct(c)`. | +| [`_ismbbtrail`](./reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC | -The following table shows the ORed values that compose the test conditions for these routines. The manifest constants `_BLANK`, `_DIGIT`, `_LOWER`, `_PUNCT`, and `_UPPER` are defined in Ctype.h. +The following table shows the `|`-combined values that compose the test conditions for these routines. The manifest constants `_BLANK`, `_DIGIT`, `_LOWER`, `_PUNCT`, and `_UPPER` are defined in *`ctype.h`*. -|Routine|_BLANK|_DIGIT|LOWER|_PUNCT|UPPER|Non-

ASCII

text|Non-

ASCII

punct| -|-------------|-------------|-------------|-----------|-------------|-----------|------------------------------|-------------------------------| -|`_ismbbalnum`|—|x|x|—|x|x|—| -|`_ismbbalpha`|—|—|x|—|x|x|—| -|`_ismbbblank`|x|—|—|—|—|—|—| -|`_ismbbgraph`|—|x|x|x|x|x|x| -|`_ismbbkalnum`|—|—|—|—|—|x|—| -|`_ismbbkprint`|—|—|—|—|—|x|x| -|`_ismbbkpunct`|—|—|—|—|—|—|x| -|`_ismbbprint`|x|x|x|x|x|x|x| -|`_ismbbpunct`|—|—|—|x|—|—|x| +| Routine | `_BLANK` | `_DIGIT` | `LOWER` | `_PUNCT` | `UPPER` | Non-ASCII
text | Non-ASCII
punctuation | +|--|--|--|--|--|--|--|--| +| `_ismbbalnum` | — | x | x | — | x | x | — | +| `_ismbbalpha` | — | — | x | — | x | x | — | +| `_ismbbblank` | x | — | — | — | — | — | — | +| `_ismbbgraph` | — | x | x | x | x | x | x | +| `_ismbbkalnum` | — | — | — | — | — | x | — | +| `_ismbbkprint` | — | — | — | — | — | x | x | +| `_ismbbkpunct` | — | — | — | — | — | — | x | +| `_ismbbprint` | x | x | x | x | x | x | x | +| `_ismbbpunct` | — | — | — | x | — | — | x | -The `_ismbb` routines are implemented both as functions and as macros. For more information about how to choose either implementation, see [Recommendations for Choosing Between Functions and Macros](../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md). +The `_ismbb` routines are implemented both as functions and as macros. For more information about how to choose either implementation, see [Recommendations for choosing between functions and macros](./recommendations-for-choosing-between-functions-and-macros.md). ## See also -[Byte Classification](../c-runtime-library/byte-classification.md)
-[is, isw Routines](../c-runtime-library/is-isw-routines.md)
-[_mbbtombc, _mbbtombc_l](../c-runtime-library/reference/mbbtombc-mbbtombc-l.md)
-[_mbctombb, _mbctombb_l](../c-runtime-library/reference/mbctombb-mbctombb-l.md) +[Byte classification](./byte-classification.md)\ +[`is`, `isw` routines](./is-isw-routines.md)\ +[`_mbbtombc`, `_mbbtombc_l`](./reference/mbbtombc-mbbtombc-l.md)\ +[`_mbctombb`, `_mbctombb_l`](./reference/mbctombb-mbctombb-l.md) diff --git a/docs/c-runtime-library/ismbc-routines.md b/docs/c-runtime-library/ismbc-routines.md index 8410545500..7c7a33362c 100644 --- a/docs/c-runtime-library/ismbc-routines.md +++ b/docs/c-runtime-library/ismbc-routines.md @@ -1,68 +1,59 @@ --- -description: "Learn more about: _ismbc Routines" title: "_ismbc Routines" +description: "Learn more about: _ismbc Routines" ms.date: "11/04/2016" -api_location: ["msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_ismbc"] helpviewer_keywords: ["ismbc routines", "_ismbc routines"] -ms.assetid: b8995391-7857-4ac3-9a1e-de946eb4464d --- -# _ismbc Routines +# `_ismbc` routines -Each **_ismbc** routine tests a given multibyte character `c` for a particular condition. +Each `_ismbc` routine tests a given multibyte character `c` for a particular condition. -:::row::: - :::column span=""::: - [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)\ - [_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)\ - [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)\ - [_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)\ - [_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)\ - [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) - :::column-end::: -:::row-end::: +- [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](reference/ismbcalnum-functions.md) +- [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) +- [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](reference/ismbcgraph-functions.md) +- [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) +- [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) +- [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) ## Remarks -The test result of each **_ismbc** routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [_getmbcp](../c-runtime-library/reference/getmbcp.md) or [_setmbcp](../c-runtime-library/reference/setmbcp.md), respectively. - -The output value is affected by the `LC_CTYPE` category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. - -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|[_ismbcalnum, _ismbcalnum_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphanumeric|Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcdigit` and `_ismbcalpha`.| -|[_ismbcalpha, _ismbcalpha_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcupper` and `_ismbclower`; or a katakana letter: 0xA6<=`c`<=0xDF.| -|[_ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Digit|Returns nonzero if and only if `c` is a single-byte representation of an ASCII digit: 0x30<=`c`<=0x39.| -|[_ismbcgraph, _ismbcgraph_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Graphic|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character except a white space ( ). See examples for `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`.| -|[_ismbclegal, _ismbclegal_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Valid multibyte character|Returns nonzero if and only if the first byte of `c` is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC.| -|[_ismbclower, _ismbclower_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Lowercase alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII lowercase English letter: 0x61<=`c`<=0x7A.| -|[_ismbcprint, _ismbcprint_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character including a white space ( ): See examples for `_ismbcspace`, `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`.| -|[_ismbcpunct, _ismbcpunct_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Punctuation|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana punctuation character.| -|[_ismbcblank, _ismbcblank_l,](../c-runtime-library/reference/ismbcgraph-functions.md)|Space or horizontal tab|Returns nonzero if and only if `c` is a single-byte representation of a space character or a horizontal tab character: `c`=0x20 or `c`=0x09.| -|[_ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Whitespace|Returns nonzero if and only if `c` is a white space character: `c`=0x20 or 0x09<=`c`<=0x0D.| -|[_ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Multibyte symbol|Returns nonzero if and only if 0x8141<=`c`<=0x81AC.| -|[_ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Uppercase alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII uppercase English letter: 0x41<=`c`<=0x5A.| +The test result of each `_ismbc` routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [`_getmbcp`](reference/getmbcp.md) or [`_setmbcp`](reference/setmbcp.md), respectively. + +The output value is affected by the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. + +| Routine | Test condition | Code page 932 example | +|---|---|---| +| [`_ismbcalnum`, `_ismbcalnum_l`](reference/ismbcalnum-functions.md) | Alphanumeric | Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcdigit` and `_ismbcalpha`. | +| [`_ismbcalpha`, `_ismbcalpha_l`](reference/ismbcalnum-functions.md) | Alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcupper` and `_ismbclower`; or a katakana letter: 0xA6<=`c`<=0xDF. | +| [`_ismbcdigit`, `_ismbcdigit_l`](reference/ismbcalnum-functions.md) | Digit | Returns nonzero if and only if `c` is a single-byte representation of an ASCII digit: 0x30<=`c`<=0x39. | +| [`_ismbcgraph`, `_ismbcgraph_l`](reference/ismbcgraph-functions.md) | Graphic | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character except a white space ( ). See examples for `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`. | +| [`_ismbclegal`, `_ismbclegal_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Valid multibyte character | Returns nonzero if and only if the first byte of `c` is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC. | +| [`_ismbclower`, `_ismbclower_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Lowercase alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII lowercase English letter: 0x61<=`c`<=0x7A. | +| [`_ismbcprint`, `_ismbcprint_l`](reference/ismbcgraph-functions.md) | Printable | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character including a white space ( ): See examples for `_ismbcspace`, `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`. | +| [`_ismbcpunct`, `_ismbcpunct_l`](reference/ismbcgraph-functions.md) | Punctuation | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana punctuation character. | +| [`_ismbcblank`, `_ismbcblank_l`](reference/ismbcgraph-functions.md) | Space or horizontal tab | Returns nonzero if and only if `c` is a single-byte representation of a space character or a horizontal tab character: `c`=0x20 or `c`=0x09. | +| [`_ismbcspace`, `_ismbcspace_l`](reference/ismbcgraph-functions.md) | Whitespace | Returns nonzero if and only if `c` is a white space character: `c`=0x20 or 0x09<=`c`<=0x0D. | +| [`_ismbcsymbol`, `_ismbcsymbol_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Multibyte symbol | Returns nonzero if and only if 0x8141<=`c`<=0x81AC. | +| [`_ismbcupper`, `_ismbcupper_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Uppercase alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII uppercase English letter: 0x41<=`c`<=0x5A. | **Code Page 932 Specific** The following routines are specific to code page 932. -|Routine|Test condition (code page 932 only)| -|-------------|-------------------------------------------| -|[_ismbchira, _ismbchira_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Double-byte Hiragana: 0x829F<=`c`<=0x82F1.| -|[_ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Double-byte katakana: 0x8340<=`c`<=0x8396.| -|[_ismbcl0, _ismbcl0_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS non-Kanji: 0x8140<=`c`<=0x889E.| -|[_ismbcl1, _ismbcl1_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS level-1: 0x889F<=`c`<=0x9872.| -|[_ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS level-2: 0x989F<=`c`<=0xEA9E.| +| Routine | Test condition (code page 932 only) | +|---|---| +| [`_ismbchira`, `_ismbchira_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Double-byte Hiragana: 0x829F<=`c`<=0x82F1. | +| [`_ismbckata`, `_ismbckata_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Double-byte katakana: 0x8340<=`c`<=0x8396. | +| [`_ismbcl0`, `_ismbcl0_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS non-Kanji: 0x8140<=`c`<=0x889E. | +| [`_ismbcl1`, `_ismbcl1_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS level-1: 0x889F<=`c`<=0x9872. | +| [`_ismbcl2`, `_ismbcl2_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS level-2: 0x989F<=`c`<=0xEA9E. | -`_ismbcl0`, `_ismbcl1`, and `_ismbcl2` check that the specified value `c` matches the test conditions described in the preceding table, but do not check that `c` is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. +`_ismbcl0`, `_ismbcl1`, and `_ismbcl2` check that the specified value `c` matches the test conditions described in the preceding table, but don't check that `c` is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [`_ismbbtrail`, `_ismbbtrail_l`](reference/ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. **END Code Page 932 Specific** ## See also -[Character Classification](../c-runtime-library/character-classification.md)
-[is, isw Routines](../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../c-runtime-library/ismbb-routines.md) +[Character classification](character-classification.md)\ +[`is`, `isw` routines](is-isw-routines.md)\ +[`_ismbb` routines](ismbb-routines.md) diff --git a/docs/c-runtime-library/iso646-operators.md b/docs/c-runtime-library/iso646-operators.md index f46b895623..8e0225b114 100644 --- a/docs/c-runtime-library/iso646-operators.md +++ b/docs/c-runtime-library/iso646-operators.md @@ -4,27 +4,27 @@ title: "ISO646 Operators" ms.date: "04/11/2018" ms.assetid: 93e6d3e7-4889-4d8e-8dcb-c1a6b9bbe0f5 --- -# ISO646 Operators +# ISO646 operators Provides readable alternatives to certain operators or punctuators. The standard header \ is available even in a freestanding implementation. ## Macros -|Name|Description| -|-|-| -|[and](../c-runtime-library/reference/and.md)|An alternative to the && operator.| -|[and_eq](../c-runtime-library/reference/and-eq.md)|An alternative to the &= operator.| -|[bitand](../c-runtime-library/reference/bitand.md)|An alternative to the & operator.| -|[bitor](../c-runtime-library/reference/bitor.md)|An alternative to the | operator.| -|[compl](../c-runtime-library/reference/compl.md)|An alternative to the ~ operator.| -|[not](../c-runtime-library/reference/not.md)|An alternative to the ! operator.| -|[not_eq](../c-runtime-library/reference/not-eq.md)|An alternative to the != operator.| -|[or](../c-runtime-library/reference/or.md)|An alternative to the || operator.| -|[or_eq](../c-runtime-library/reference/or-eq.md)|An alternative to the |= operator.| -|[xor](../c-runtime-library/reference/xor.md)|An alternative to the ^ operator.| -|[xor_eq](../c-runtime-library/reference/xor-eq.md)|An alternative to the ^= operator.| +| Name | Description | +|--|--| +| [`and`](./reference/and.md) | An alternative to the `&&` operator. | +| [`and_eq`](./reference/and-eq.md) | An alternative to the `&=` operator. | +| [`bitand`](./reference/bitand.md) | An alternative to the `&` operator. | +| [`bitor`](./reference/bitor.md) | An alternative to the `|` operator. | +| [`compl`](./reference/compl.md) | An alternative to the `~` operator. | +| [`not`](./reference/not.md) | An alternative to the `!` operator. | +| [`not_eq`](./reference/not-eq.md) | An alternative to the `!=` operator. | +| [`or`](./reference/or.md) | An alternative to the `||` operator. | +| [`or_eq`](./reference/or-eq.md) | An alternative to the `|=` operator. | +| [`xor`](./reference/xor.md) | An alternative to the `^` operator. | +| [`xor_eq`](./reference/xor-eq.md) | An alternative to the `^=` operator. | ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/language-strings.md b/docs/c-runtime-library/language-strings.md index 26dc512fd9..99b9af3a15 100644 --- a/docs/c-runtime-library/language-strings.md +++ b/docs/c-runtime-library/language-strings.md @@ -4,85 +4,85 @@ description: "Learn more about: Language Strings" ms.date: "1/12/2021" helpviewer_keywords: ["language strings"] --- -# Language Strings +# Language strings -The [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md) and [`_create_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) functions can use the Windows NLS API supported languages on operating systems that don't use the Unicode code page. For a list of supported languages by operating system version, see [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. The language string can be any of the values in the **Language** and **Language tag** columns of the list of supported languages. For example code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). +The [`setlocale`](reference/setlocale-wsetlocale.md) and [`_create_locale`](reference/create-locale-wcreate-locale.md) functions can use the Windows NLS API supported languages on operating systems that don't use the Unicode code page. For a list of supported languages by operating system version, see [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. The language string can be any of the values in the **Language** and **Language tag** columns of the list of supported languages. For example code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). ## Supported language strings The Microsoft C run-time library implementation also supports these language strings: -|Language string|Equivalent Locale Name| -|---------------------|----------------------------| -|`american`|`en-US`| -|`american english`|`en-US`| -|`american-english`|`en-US`| -|`australian`|`en-AU`| -|`belgian`|`nl-BE`| -|`canadian`|`en-CA`| -|`chh`|`zh-HK`| -|`chi`|`zh-SG`| -|`chinese`|`zh`| -|`chinese-hongkong`|`zh-HK`| -|`chinese-simplified`|`zh-CN`| -|`chinese-singapore`|`zh-SG`| -|`chinese-traditional`|`zh-TW`| -|`dutch-belgian`|`nl-BE`| -|`english-american`|`en-US`| -|`english-aus`|`en-AU`| -|`english-belize`|`en-BZ`| -|`english-can`|`en-CA`| -|`english-caribbean`|`en-029`| -|`english-ire`|`en-IE`| -|`english-jamaica`|`en-JM`| -|`english-nz`|`en-NZ`| -|`english-south africa`|`en-ZA`| -|`english-trinidad y tobago`|`en-TT`| -|`english-uk`|`en-GB`| -|`english-us`|`en-US`| -|`english-usa`|`en-US`| -|`french-belgian`|`fr-BE`| -|`french-canadian`|`fr-CA`| -|`french-luxembourg`|`fr-LU`| -|`french-swiss`|`fr-CH`| -|`german-austrian`|`de-AT`| -|`german-lichtenstein`|`de-LI`| -|`german-luxembourg`|`de-LU`| -|`german-swiss`|`de-CH`| -|`irish-english`|`en-IE`| -|`italian-swiss`|`it-CH`| -|`norwegian`|`no`| -|`norwegian-bokmal`|`nb-NO`| -|`norwegian-nynorsk`|`nn-NO`| -|`portuguese-brazilian`|`pt-BR`| -|`spanish-argentina`|`es-AR`| -|`spanish-bolivia`|`es-BO`| -|`spanish-chile`|`es-CL`| -|`spanish-colombia`|`es-CO`| -|`spanish-costa rica`|`es-CR`| -|`spanish-dominican republic`|`es-DO`| -|`spanish-ecuador`|`es-EC`| -|`spanish-el salvador`|`es-SV`| -|`spanish-guatemala`|`es-GT`| -|`spanish-honduras`|`es-HN`| -|`spanish-mexican`|`es-MX`| -|`spanish-modern`|`es-ES`| -|`spanish-nicaragua`|`es-NI`| -|`spanish-panama`|`es-PA`| -|`spanish-paraguay`|`es-PY`| -|`spanish-peru`|`es-PE`| -|`spanish-puerto rico`|`es-PR`| -|`spanish-uruguay`|`es-UY`| -|`spanish-venezuela`|`es-VE`| -|`swedish-finland`|`sv-FI`| -|`swiss`|`de-CH`| -|`uk`|`en-GB`| -|`us`|`en-US`| -|`usa`|`en-US`| +| Language string | Equivalent Locale Name | +|---|---| +| `american` | `en-US` | +| `american english` | `en-US` | +| `american-english` | `en-US` | +| `australian` | `en-AU` | +| `belgian` | `nl-BE` | +| `canadian` | `en-CA` | +| `chh` | `zh-HK` | +| `chi` | `zh-SG` | +| `chinese` | `zh` | +| `chinese-hongkong` | `zh-HK` | +| `chinese-simplified` | `zh-CN` | +| `chinese-singapore` | `zh-SG` | +| `chinese-traditional` | `zh-TW` | +| `dutch-belgian` | `nl-BE` | +| `english-american` | `en-US` | +| `english-aus` | `en-AU` | +| `english-belize` | `en-BZ` | +| `english-can` | `en-CA` | +| `english-caribbean` | `en-029` | +| `english-ire` | `en-IE` | +| `english-jamaica` | `en-JM` | +| `english-nz` | `en-NZ` | +| `english-south africa` | `en-ZA` | +| `english-trinidad y tobago` | `en-TT` | +| `english-uk` | `en-GB` | +| `english-us` | `en-US` | +| `english-usa` | `en-US` | +| `french-belgian` | `fr-BE` | +| `french-canadian` | `fr-CA` | +| `french-luxembourg` | `fr-LU` | +| `french-swiss` | `fr-CH` | +| `german-austrian` | `de-AT` | +| `german-lichtenstein` | `de-LI` | +| `german-luxembourg` | `de-LU` | +| `german-swiss` | `de-CH` | +| `irish-english` | `en-IE` | +| `italian-swiss` | `it-CH` | +| `norwegian` | `no` | +| `norwegian-bokmal` | `nb-NO` | +| `norwegian-nynorsk` | `nn-NO` | +| `portuguese-brazilian` | `pt-BR` | +| `spanish-argentina` | `es-AR` | +| `spanish-bolivia` | `es-BO` | +| `spanish-chile` | `es-CL` | +| `spanish-colombia` | `es-CO` | +| `spanish-costa rica` | `es-CR` | +| `spanish-dominican republic` | `es-DO` | +| `spanish-ecuador` | `es-EC` | +| `spanish-el salvador` | `es-SV` | +| `spanish-guatemala` | `es-GT` | +| `spanish-honduras` | `es-HN` | +| `spanish-mexican` | `es-MX` | +| `spanish-modern` | `es-ES` | +| `spanish-nicaragua` | `es-NI` | +| `spanish-panama` | `es-PA` | +| `spanish-paraguay` | `es-PY` | +| `spanish-peru` | `es-PE` | +| `spanish-puerto rico` | `es-PR` | +| `spanish-uruguay` | `es-UY` | +| `spanish-venezuela` | `es-VE` | +| `swedish-finland` | `sv-FI` | +| `swiss` | `de-CH` | +| `uk` | `en-GB` | +| `us` | `en-US` | +| `usa` | `en-US` | ## See also -- [Locale Names, Languages, and Country/Region Strings](../c-runtime-library/locale-names-languages-and-country-region-strings.md)\ -- [Country/Region Strings](../c-runtime-library/country-region-strings.md)\ -- [`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)\ -- [`_create_locale`, `_wcreate_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) +- [Locale names, Languages, and Country/Region strings](locale-names-languages-and-country-region-strings.md) +- [Country/Region strings](country-region-strings.md) +- [`setlocale`, `_wsetlocale`](reference/setlocale-wsetlocale.md) +- [`_create_locale`, `_wcreate_locale`](reference/create-locale-wcreate-locale.md) diff --git a/docs/c-runtime-library/lc-codepage-func.md b/docs/c-runtime-library/lc-codepage-func.md index 2e7ea34bc5..21d5dd5640 100644 --- a/docs/c-runtime-library/lc-codepage-func.md +++ b/docs/c-runtime-library/lc-codepage-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_codepage_func" title: "___lc_codepage_func" ms.date: "1/14/2021" api_name: ["___lc_codepage_func", "_o____lc_codepage_func"] -api_location: ["msvcr120.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110.dll", "msvcrt.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110.dll", "msvcrt.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["lc_codepage_func", "___lc_codepage_func"] +f1_keywords: ["lc_codepage_func", "LOCALE/___lc_codepage_func", "___lc_codepage_func"] helpviewer_keywords: ["___lc_codepage_func"] ms.assetid: 6a663bd0-5a63-4a2f-9507-872ec1582aae --- -# ___lc_codepage_func +# `___lc_codepage_func` Internal CRT function. Retrieves the current code page of the thread. @@ -20,29 +20,29 @@ Internal CRT function. Retrieves the current code page of the thread. UINT ___lc_codepage_func(void); ``` -## Return Value +## Return value The current code page of the thread. ## Remarks -`___lc_codepage_func` is an internal CRT function that is used by other CRT functions to get the current code page from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function. +**`___lc_codepage_func`** is an internal CRT function that is used by other CRT functions to get the current code page from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function. -A *code page* is a mapping of single-byte or double-byte codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. For more information about code pages, see [Code Pages](../c-runtime-library/code-pages.md). +A *code page* is a mapping of single-byte or double-byte codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. For more information about code pages, see [Code pages](./code-pages.md). Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_codepage_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_codepage_func`** | `crt\src\setlocal.h` | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/lc-collate-cp-func.md b/docs/c-runtime-library/lc-collate-cp-func.md index 056692ffa6..e507776555 100644 --- a/docs/c-runtime-library/lc-collate-cp-func.md +++ b/docs/c-runtime-library/lc-collate-cp-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_collate_cp_func" title: "___lc_collate_cp_func" ms.date: "1/14/2021" api_name: ["___lc_collate_cp_func", "_o____lc_collate_cp_func"] -api_location: ["msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr90.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr90.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___lc_collate_cp_func"] +f1_keywords: ["LOCALE/___lc_collate_cp_func", "___lc_collate_cp_func"] helpviewer_keywords: ["___lc_collate_cp_func"] ms.assetid: 46ccc084-7ac9-4e5d-9138-e12cb5845615 --- -# ___lc_collate_cp_func +# `___lc_collate_cp_func` Internal CRT function. Retrieves the current collation code page of the thread. @@ -20,27 +20,27 @@ Internal CRT function. Retrieves the current collation code page of the thread. UINT ___lc_codepage_func(void); ``` -## Return Value +## Return value The current collation code page of the thread. ## Remarks -`___lc_collate_cp_func` is an internal CRT function that is used by other CRT functions to get the current collation code page from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function. +**`___lc_collate_cp_func`** is an internal CRT function that is used by other CRT functions to get the current collation code page from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_collate_cp_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_collate_cp_func`** | crt\src\setlocal.h | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/lc-locale-name-func.md b/docs/c-runtime-library/lc-locale-name-func.md index 8f19df313b..0fbf0416f2 100644 --- a/docs/c-runtime-library/lc-locale-name-func.md +++ b/docs/c-runtime-library/lc-locale-name-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_locale_name_func" title: "___lc_locale_name_func" ms.date: "1/14/2021" api_name: ["___lc_locale_name_func", "_o____lc_locale_name_func"] -api_location: ["msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___lc_locale_name_func"] +f1_keywords: ["LOCALE/___lc_locale_name_func", "___lc_locale_name_func"] helpviewer_keywords: ["___lc_locale_name_func"] ms.assetid: ef858308-872e-43de-95e0-9b1b4084343e --- -# ___lc_locale_name_func +# `___lc_locale_name_func` Internal CRT function. Retrieves the current locale name of the thread. @@ -20,27 +20,27 @@ Internal CRT function. Retrieves the current locale name of the thread. wchar_t** ___lc_locale_name_func(void); ``` -## Return Value +## Return value A pointer to a string that contains the current locale name of the thread. ## Remarks -`___lc_locale_name_func` is an internal CRT function that is used by other CRT functions to get the current locale name from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function or the [setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) functions. +**`___lc_locale_name_func`** is an internal CRT function that is used by other CRT functions to get the current locale name from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function or the [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) functions. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_locale_name_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_locale_name_func`** | `crt\src\setlocal.h` | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/link-options.md b/docs/c-runtime-library/link-options.md index 86cadf70ab..7f27f9a178 100644 --- a/docs/c-runtime-library/link-options.md +++ b/docs/c-runtime-library/link-options.md @@ -1,35 +1,34 @@ --- -description: "Learn more about: Link Options" -title: "Link Options" +title: "Link options" +description: "Learn more about: Link options" ms.date: "11/04/2016" helpviewer_keywords: ["nothrownew.obj", "newmode.obj", "noenv.obj", "psetargv.obj", "legacy_stdio_float_rounding.obj", "loosefpmath.obj", "smallheap.obj", "fp10.obj", "nochkclr.obj", "chkstk.obj", "pcommode.obj", "pnoenv.obj", "link options [C++]", "invalidcontinue.obj", "pnothrownew.obj", "pwsetargv.obj", "pinvalidcontinue.obj", "wsetargv.obj", "binmode.obj", "setargv.obj", "noarg.obj", "pnewmode.obj", "commode.obj", "pthreadlocale.obj", "pbinmode.obj", "threadlocale.obj", "pnoarg.obj"] -ms.assetid: 05b5a77b-9dd1-494b-ae46-314598c770bb --- -# Link Options +# Link options -The CRT lib directory includes a number of small object files that enable specific CRT features without any code change. These are called "link options" since you just have to add them to the linker command line to use them. +The CRT lib directory includes several small object files that enable specific CRT features without code changes. These object files are called "link options" because you only have to add them to the linker command line to use them. To do this from Visual Studio, in the Solution Explorer right-click your project and choose **Properties**. Under **Configuration Properties**, choose **Linker** > **Input** > **Additional Dependencies** and specify the additional items to add to the link command line. -CLR pure mode versions of these objects are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Use the regular versions for native and /clr code. +CLR pure mode versions of these objects are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Use the regular versions for native and [`/clr`](../build/reference/clr-common-language-runtime-compilation.md) code. -|Native and /clr|Pure mode|Description| -|----------------------|---------------|-----------------| -|binmode.obj|pbinmode.obj|Sets the default file-translation mode to binary. See [_fmode](../c-runtime-library/fmode.md).| -|chkstk.obj|n/a|Provides stack-checking and alloca support when not using the CRT.| -|commode.obj|pcommode.obj|Sets the global commit flag to "commit". See [fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md) and [fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md).| -|exe_initialize_mta.lib|n/a|Initializes the MTA apartment during EXE startup, which allows the use of COM objects in global smart pointers. Because this option leaks an MTA apartment reference during shutdown, do not use it for DLLs. Linking to this is equivalent to including combase.h and defining _EXE_INITIALIZE_MTA. | -|fp10.obj|n/a|Changes the default precision control to 64 bits. See [Floating-Point Support](../c-runtime-library/floating-point-support.md).| -|invalidcontinue.obj|pinvalidcontinue.obj|Sets a default invalid parameter handler that does nothing, meaning that invalid parameters passed to CRT functions will just set errno and return an error result.| -|legacy_stdio_float_rounding.obj|n/a|Printing floating-point values (for example, when using [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)) with the Windows 10 19041 Universal C Runtime has been fixed. It now properly rounds exactly representable floating-point numbers, and respects the floating-point rounding requested by [fesetround](../c-runtime-library/reference/fegetround-fesetround2.md). This behavior update is available in Visual Studio 2019 version 16.2 and later. Legacy behavior is used in earlier versions of Visual Studio, or by providing this link option.| -|loosefpmath.obj|n/a|Ensures that floating point code tolerates denormal values.| -|newmode.obj|pnewmode.obj|Causes [malloc](../c-runtime-library/reference/malloc.md) to call the new handler on failure. See [_set_new_mode](../c-runtime-library/reference/set-new-mode.md), [_set_new_handler](../c-runtime-library/reference/set-new-handler.md), [calloc](../c-runtime-library/reference/calloc.md), and [realloc](../c-runtime-library/reference/realloc.md).| -|noarg.obj|pnoarg.obj|Disables all processing of argc and argv.| -|nochkclr.obj|n/a|Does nothing. Remove from your project.| -|noenv.obj|pnoenv.obj|Disables the creation of a cached environment for the CRT.| -|nothrownew.obj|pnothrownew.obj|Enables the non-throwing version of new in the CRT. See [new and delete Operators](../cpp/new-and-delete-operators.md).| -|setargv.obj|psetargv.obj|Enables command-line argument wildcard expansion. See [Expanding Wildcard Arguments](../c-language/expanding-wildcard-arguments.md).| -|threadlocale.obj|pthreadlocale.obj|Enables per-thread locale for all new threads by default.| -|wsetargv.obj|pwsetargv.obj|Enables command-line argument wildcard expansion. See [Expanding Wildcard Arguments](../c-language/expanding-wildcard-arguments.md).| +| Native and /clr | Pure mode | Description | +|---|---|---| +| `binmode.obj` | `pbinmode.obj` | Sets the default file-translation mode to binary. See [`_fmode`](fmode.md). | +| `chkstk.obj` | n/a | Provides stack-checking and alloca support when not using the CRT. | +| `commode.obj` | `pcommode.obj` | Sets the global commit flag to "commit". See [`fopen`, `_wfopen`](reference/fopen-wfopen.md) and [`fopen_s`, `_wfopen_s`](reference/fopen-s-wfopen-s.md). | +| `exe_initialize_mta.lib` | n/a | Initializes the MTA apartment during EXE startup, which allows the use of COM objects in global smart pointers. Because this option leaks an MTA apartment reference during shutdown, don't use it for DLLs. Linking to this file is equivalent to including `combase.h` and defining `_EXE_INITIALIZE_MTA`. Using this link option adds [`onecore.lib`](/windows/win32/apiindex/windows-umbrella-libraries) to the default library list. If this effect is undesirable (such as using onecore_apiset.lib or other umbrella library), use [`/NODEFAULTLIB`](../build/reference/nodefaultlib-ignore-libraries.md) to override this behavior and provide an alternative. | +| `fp10.obj` | n/a | Changes the default precision control to 64 bits. See [Math and floating-point support](floating-point-support.md). | +| `invalidcontinue.obj` | `pinvalidcontinue.obj` | Sets a default invalid parameter handler that does nothing, meaning that invalid parameters passed to CRT functions will just set errno and return an error result. | +| `legacy_stdio_float_rounding.obj` | n/a | The printing of floating-point values (for example, when using [`printf`](reference/printf-printf-l-wprintf-wprintf-l.md)) with the Windows 10 19041 Universal C Runtime has been fixed. It now properly rounds exactly representable floating-point numbers, and respects the floating-point rounding requested by [`fesetround`](reference/fegetround-fesetround2.md). This behavior update is available in Visual Studio 2019 version 16.2 and later. Legacy behavior is used in earlier versions of Visual Studio, or by providing this link option. | +| `loosefpmath.obj` | n/a | Ensures that floating point code tolerates denormal values. | +| `newmode.obj` | `pnewmode.obj` | Causes [`malloc`](reference/malloc.md) to call the new handler on failure. See [`_set_new_mode`](reference/set-new-mode.md), [`_set_new_handler`](reference/set-new-handler.md), [`calloc`](reference/calloc.md), and [`realloc`](reference/realloc.md). | +| `noarg.obj` | `pnoarg.obj` | Disables all processing of argc and argv. | +| `nochkclr.obj` | n/a | Does nothing. Remove from your project. | +| `noenv.obj` | `pnoenv.obj` | Disables the creation of a cached environment for the CRT. | +| `nothrownew.obj` | `pnothrownew.obj` | Enables the non-throwing version of new in the CRT. See [new and delete Operators](../cpp/new-and-delete-operators.md). | +| `setargv.obj` | `psetargv.obj` | Enables command-line argument wildcard expansion. See [Expanding wildcard arguments](../c-language/expanding-wildcard-arguments.md). | +| `threadlocale.obj` | `pthreadlocale.obj` | Enables per-thread locale for all new threads by default. | +| `wsetargv.obj` | `pwsetargv.obj` | Enables command-line argument wildcard expansion. See [Expanding wildcard arguments](../c-language/expanding-wildcard-arguments.md). | ## See also -- [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +- [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](crt-library-features.md) diff --git a/docs/c-runtime-library/local-unwind2.md b/docs/c-runtime-library/local-unwind2.md index f3f84e1b0e..d3f4fcc87d 100644 --- a/docs/c-runtime-library/local-unwind2.md +++ b/docs/c-runtime-library/local-unwind2.md @@ -3,14 +3,14 @@ description: "Learn more about: _local_unwind2" title: "_local_unwind2" ms.date: "1/14/2021" api_name: ["_local_unwind2"] -api_location: ["msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_local_unwind2", "local_unwind2"] helpviewer_keywords: ["_local_unwind2 function", "local_unwind2 function"] ms.assetid: 44f1fa82-e01e-490f-a6e6-18fc6811c28c --- -# _local_unwind2 +# `_local_unwind2` Internal CRT Function. Runs all termination handlers that are listed in the indicated scope table. @@ -25,18 +25,18 @@ void _local_unwind2( #### Parameters -*xr*
+*`xr`*\ [in] A registration record that is associated with one scope table. -*stop*
+*`stop`*\ [in] The lexical level that indicates where `_local_unwind2` should stop. ## Remarks -This method is used only by the run-time environment. Do not call the method in your code. +This method is used only by the run-time environment. Don't call the method in your code. -When this method executes termination handlers, it starts at the current lexical level and works its way up in lexical levels until it reaches the level that is indicated by `stop`. It does not execute termination handlers at the level that is indicated by `stop`. +When this method executes termination handlers, it starts at the current lexical level, and works upward in lexical levels until it reaches the level that's indicated by `stop`. It doesn't execute termination handlers at the level that's indicated by `stop`. ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/locale-categories.md b/docs/c-runtime-library/locale-categories.md index 9a17ab8f5f..891ebbf4d1 100644 --- a/docs/c-runtime-library/locale-categories.md +++ b/docs/c-runtime-library/locale-categories.md @@ -2,15 +2,15 @@ description: "Learn more about: Locale Categories" title: "Locale Categories" ms.date: "11/04/2016" -f1_keywords: ["LC_MAX", "LC_MIN", "LC_MONETARY", "LC_TIME", "LC_NUMERIC", "LC_COLLATE", "LC_CTYPE", "LC_ALL"] +f1_keywords: ["LOCALE/LC_MAX", "LOCALE/LC_MIN", "LOCALE/LC_MONETARY", "LOCALE/LC_TIME", "LOCALE/LC_NUMERIC", "LOCALE/LC_COLLATE", "LOCALE/LC_CTYPE", "LOCALE/LC_ALL", "LC_MAX", "LC_MIN", "LC_MONETARY", "LC_TIME", "LC_NUMERIC", "LC_COLLATE", "LC_CTYPE", "LC_ALL"] helpviewer_keywords: ["LC_MIN constant", "LC_MONETARY constant", "LC_CTYPE constant", "locale constants", "LC_MAX constant", "LC_ALL constant", "LC_TIME constant", "LC_NUMERIC constant", "LC_COLLATE constant"] ms.assetid: 868f1493-fe5d-4722-acab-bfcd374a063a --- -# Locale Categories +# Locale categories ## Syntax -``` +```C #include ``` @@ -18,24 +18,24 @@ ms.assetid: 868f1493-fe5d-4722-acab-bfcd374a063a Locale categories are manifest constants used by the localization routines to specify which portion of a program's locale information will be used. The locale refers to the locality (or Country/Region) for which certain aspects of your program can be customized. Locale-dependent areas include, for example, the formatting of dates or the display format for monetary values. -|Locale category|Parts of program affected| -|---------------------|-------------------------------| -|`LC_ALL`|All locale-specific behavior (all categories)| -|`LC_COLLATE`|Behavior of `strcoll` and `strxfrm` functions| -|`LC_CTYPE`|Behavior of character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected)| -|`LC_MAX`|Same as `LC_TIME`| -|`LC_MIN`|Same as `LC_ALL`| -|`LC_MONETARY`|Monetary formatting information returned by the `localeconv` function| -|`LC_NUMERIC`|Decimal-point character for formatted output routines (for example, `printf`), data conversion routines, and nonmonetary formatting information returned by `localeconv` function| -|`LC_TIME`|Behavior of `strftime` function| +| Locale category | Parts of program affected | +|---|---| +| `LC_ALL` | All locale-specific behavior (all categories) | +| `LC_COLLATE` | Behavior of `strcoll` and `strxfrm` functions | +| `LC_CTYPE` | Behavior of character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected) | +| `LC_MAX` | Same as `LC_TIME` | +| `LC_MIN` | Same as `LC_ALL` | +| `LC_MONETARY` | Monetary formatting information returned by the `localeconv` function | +| `LC_NUMERIC` | Decimal-point character for formatted output routines (for example, `printf`), data conversion routines, and nonmonetary formatting information returned by `localeconv` function | +| `LC_TIME` | Behavior of `strftime` function | -See [setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for an example. +See [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) for an example. ## See also -[localeconv](../c-runtime-library/reference/localeconv.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[strcoll Functions](../c-runtime-library/strcoll-functions.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`localeconv`](./reference/localeconv.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`strcoll` functions](./strcoll-functions.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](./reference/strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md b/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md index fd9ee6817a..dd2fae03a4 100644 --- a/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md +++ b/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md @@ -8,31 +8,31 @@ ms.assetid: a0e5a0c5-5602-4da0-b65f-de3d6c8530a2 --- # UCRT Locale names, Languages, and Country/Region strings -The *locale* argument to the [setlocale, \_wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md), [\_create\_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md), and [\_wcreate\_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md) functions can be set by using the locale names, languages, country/region codes, and code pages that are supported by the Windows NLS API. The *locale* argument takes the following form: +You can set the *`locale`* argument to the [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md), [`_create_locale`](./reference/create-locale-wcreate-locale.md), and [`_wcreate_locale`](./reference/create-locale-wcreate-locale.md) functions in several ways. The locale can be set by using the locale names, languages, country/region codes, and code pages that are supported by the Windows NLS API. The *`locale`* argument takes one of the following forms: -> *locale* :: "*locale-name*"
-    \| "*language*\[**\_**_country-region_\[__.__*code-page*]]"
-    \| "__.__*code-page*"
-    \| "C"
-    \| ""
-    \| NULL +> *`locale`* :: "*locale-name*"\ + \| "*language*\[_*country-region*\[.*code-page*]]"\ + \| ".*code-page*"\ + \| "C"\ + \| ""\ + \| NULL -The *locale-name* form is a short, IETF-standardized string; for example, `en-US` for English (United States) or `bs-Cyrl-BA` for Bosnian (Cyrillic, Bosnia and Herzegovina). These forms are preferred. For a list of supported locale names by Windows operating system version, see the **Language tag** column of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. This resource lists the supported language, script, and region parts of the locale names. For information about the supported locale names that have non-default sort orders, see the **Locale name** column in [Sort Order Identifiers](/windows/win32/Intl/sort-order-identifiers). Under Windows 10 or later, locale names that correspond to valid [BCP-47](https://tools.ietf.org/html/bcp47) language tags are allowed. For example, `jp-US` is a valid BCP-47 tag, but it is effectively only `US` for locale functionality. +The *locale-name* form is a short, IETF-standardized string; for example, `en-US` for English (United States) or `bs-Cyrl-BA` for Bosnian (Cyrillic, Bosnia and Herzegovina). These forms are preferred. For a list of supported locale names by Windows operating system version, see the **Language tag** column of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. This resource lists the supported language, script, and region parts of the locale names. For information about the supported locale names that have non-default sort orders, see the **Locale name** column in [Sort order identifiers](/windows/win32/Intl/sort-order-identifiers). Under Windows 10 or later, locale names that correspond to valid [BCP-47](https://tools.ietf.org/html/bcp47) language tags are allowed. For example, `jp-US` is a valid BCP-47 tag, but it's effectively only `US` for locale functionality. -The *language*\[**\_**_country-region_\[__.__*code-page*]] form is stored in the locale setting for a category when a language string, or language string and country or region string, is used to create the locale. The set of supported language strings is described in [Language Strings](../c-runtime-library/language-strings.md), and the list of supported country and region strings is listed in [Country/Region Strings](../c-runtime-library/country-region-strings.md). If the specified language is not associated with the specified country or region, the default language for the specified country or region is stored in the locale setting. We do not recommend this form for locale strings embedded in code or serialized to storage, because these strings are more likely to be changed by an operating system update than the locale name form. +The *language*\[**\_**_country-region_\[__.__*code-page*]] form is stored in the locale setting for a category when a language string, or language string and country or region string, is used to create the locale. The set of supported language strings is described in [Language strings](./language-strings.md), and the list of supported country and region strings is listed in [Country/Region strings](./country-region-strings.md). If the specified language isn't associated with the specified country or region, the default language for the specified country or region is stored in the locale setting. We don't recommend this form for locale strings embedded in code or serialized to storage: These strings are more likely to be changed by an operating system update than the locale name form. -The *code-page* is the ANSI/OEM code page that's associated with the locale. The code page is determined for you when you specify a locale by language or by language and country/region alone. The special value `.ACP` specifies the ANSI code page for the country/region. The special value `.OCP` specifies the OEM code page for the country/region. For example, if you specify `"Greek_Greece.ACP"` as the locale, the locale is stored as `Greek_Greece.1253` (the ANSI code page for Greek), and if you specify `"Greek_Greece.OCP"` as the locale, it is stored as `Greek_Greece.737` (the OEM code page for Greek). For more information about code pages, see [Code Pages](../c-runtime-library/code-pages.md). For a list of supported code pages on Windows, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +The *code-page* is the ANSI/OEM code page that's associated with the locale. The code page is determined for you when you specify a locale by language or by language and country/region alone. The special value `.ACP` specifies the ANSI code page for the country/region. The special value `.OCP` specifies the OEM code page for the country/region. For example, if you specify `"Greek_Greece.ACP"` as the locale, the locale is stored as `Greek_Greece.1253` (the ANSI code page for Greek), and if you specify `"Greek_Greece.OCP"` as the locale, it's stored as `Greek_Greece.737` (the OEM code page for Greek). For more information about code pages, see [Code pages](./code-pages.md). For a list of supported code pages on Windows, see [Code page identifiers](/windows/win32/Intl/code-page-identifiers). -If you use only the code page to specify the locale, the user's default language and country/region as reported by [GetUserDefaultLocaleName](/windows/win32/api/winnls/nf-winnls-getuserdefaultlocalename) are used. For example, if you specify `".1254"` (ANSI Turkish) as the locale for a user that's configured for English (United States), the locale that's stored is `English_United States.1254`. We do not recommend this form, because it could lead to inconsistent behavior. +If you use only the code page to specify the locale, the user's default language and country/region as reported by [`GetUserDefaultLocaleName`](/windows/win32/api/winnls/nf-winnls-getuserdefaultlocalename) are used. For example, if you specify `".1254"` (ANSI Turkish) as the locale for a user that's configured for English (United States), the locale that's stored is `English_United States.1254`. We don't recommend this form, because it could lead to inconsistent behavior. -A *locale* argument value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that every **`char`** data type is 1 byte and its value is always less than 256. If *locale* points to an empty string, the locale is the implementation-defined native environment. +A *`locale`* argument value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that every **`char`** data type is 1 byte and its value is always less than 256. If *`locale`* points to an empty string, the locale is the implementation-defined native environment. You can specify all of the locale categories at the same time for the `setlocale` and `_wsetlocale` functions by using the `LC_ALL` category. The categories can all be set to the same locale, or you can set each category individually by using a locale argument that has this form: -> *LC-ALL-specifier* :: *locale*
-    \| \[**LC_COLLATE=**_locale_]\[**;LC_CTYPE=**_locale_]\[**;LC_MONETARY=**_locale_]\[**;LC_NUMERIC=**_locale_]\[**;LC_TIME=**_locale_] +> *`LC-ALL-specifier`* :: *`locale`*\ + \| \[**`LC_COLLATE=`***`locale`*]\[**`;LC_CTYPE=`***`locale`*]\[**`;LC_MONETARY=`***`locale`*]\[**`;LC_NUMERIC=`***`locale`*]\[**`;LC_TIME=`***`locale`*] -You can specify multiple category types, separated by semicolons. Category types that are not specified use the current locale setting. For example, this code snippet sets the current locale for all categories to `de-DE`, and then sets the categories `LC_MONETARY` to `en-GB` and `LC_TIME` to `es-ES`: +You can specify multiple category types, separated by semicolons. Category types that aren't specified use the current locale setting. For example, this code snippet sets the current locale for all categories to `de-DE`, and then sets the categories `LC_MONETARY` to `en-GB` and `LC_TIME` to `es-ES`: ```C _wsetlocale(LC_ALL, L"de-DE"); @@ -41,13 +41,13 @@ _wsetlocale(LC_ALL, L"LC_MONETARY=en-GB;LC_TIME=es-ES"); ## UTF-8 Support -UTF-8 support can be enabled by using the UTF-8 code page in your locale string. See the [UTF-8 Support section of `setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md#utf-8-support) for more information. +UTF-8 support can be enabled by using the UTF-8 code page in your locale string. For more information, see the [UTF-8 support section of `setlocale`](./reference/setlocale-wsetlocale.md#utf-8-support). ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[Language Strings](../c-runtime-library/language-strings.md)
-[Country/Region Strings](../c-runtime-library/country-region-strings.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[Language strings](./language-strings.md)\ +[Country/Region strings](./country-region-strings.md) diff --git a/docs/c-runtime-library/locale.md b/docs/c-runtime-library/locale.md index ffea705048..5801ca774e 100644 --- a/docs/c-runtime-library/locale.md +++ b/docs/c-runtime-library/locale.md @@ -1,64 +1,63 @@ --- -description: "Learn more about: Locale" title: "Locale" -ms.date: "04/11/2018" +description: "Learn more about: Locale" +ms.date: 04/11/2018 f1_keywords: ["c.international"] -helpviewer_keywords: ["localization, locale", "country information", "language information routines", "setlocale function", "locale routines"] -ms.assetid: 442f8112-9288-44d7-be3c-15d22652093a +helpviewer_keywords: ["localization, locale", "country/region information", "language information routines", "setlocale function", "locale routines"] --- # Locale -*Locale* refers to country/region and language settings that you can use to customize your program. Some locale-dependent categories include the display formats for dates and monetary values. For more information, see [Locale Categories](../c-runtime-library/locale-categories.md). - -Use the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function to change or query some or all of the current program or thread locale information while using functions without the **_l** suffix. The functions with the **_l** suffix will use the locale parameter passed in for their locale information during the execution of that specific function only. To create a locale for use with a function with a **_l** suffix, use [_create_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md). To free this locale, use [_free_locale](../c-runtime-library/reference/free-locale.md). To get the current locale, use [_get_current_locale](../c-runtime-library/reference/get-current-locale.md). - -Use [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) to control whether each thread has its own locale, or all threads in a program share the same locale. For more information, see [Locales and Code Pages](../text/locales-and-code-pages.md). - -More secure versions of the functions in the following table are available, indicated by the **_s** ("secure") suffix. For more information, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). - -## Locale-Dependent Routines - -|Routine|Use|**setlocale** category setting dependence| -|-------------|---------|---------------------------------------------| -|[atof, _atof_l, _wtof, _wtof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert character to floating-point value|**LC_NUMERIC**| -|[atoi, _atoi_l, _wtoi, _wtoi_l](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert character to integer value|**LC_NUMERIC**| -|[_atoi64, _atoi64_l, _wtoi64, _wtoi64_l](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert character to 64-bit integer value|**LC_NUMERIC**| -|[atol, _atol_l, _wtol, _wtol_l](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert character to long value|**LC_NUMERIC**| -|[_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Convert character to double-long value|**LC_NUMERIC**| -|[is Routines](../c-runtime-library/is-isw-routines.md)|Test given integer for particular condition.|**LC_CTYPE**| -|[isleadbyte, _isleadbyte_l](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md)|Test for lead byte|**LC_CTYPE**| -|[localeconv](../c-runtime-library/reference/localeconv.md)|Read appropriate values for formatting numeric quantities|`LC_MONETARY, LC_NUMERIC`| -|[MB_CUR_MAX](../c-runtime-library/mb-cur-max.md)|Maximum length in bytes of any multibyte character in current locale (macro defined in STDLIB.H)|**LC_CTYPE**| -|[_mbccpy, _mbccpy_l](../c-runtime-library/reference/mbccpy-mbccpy-l.md),[_mbccpy_s, _mbccpy_s_l](../c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md)|Copy one multibyte character|**LC_CTYPE**| -|[_mbclen, mblen, _mblen_l](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Validate and return number of bytes in multibyte character|**LC_CTYPE**| -|[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)|For multibyte-character strings: validate each character in string; return string length|**LC_CTYPE**| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md),[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters|**LC_CTYPE**| -|[mbtowc, _mbtowc_l](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character|**LC_CTYPE**| -|[printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) functions|Write formatted output|**LC_NUMERIC** (determines radix character output)| -|[scanf](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) functions|Read formatted input|**LC_NUMERIC** (determines radix character recognition)| -|[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)|Select locale for program|Not applicable| -|[strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|Compare characters of two strings|**LC_COLLATE**| -|[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](../c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)|Compare two strings without regard to case|**LC_CTYPE**| -|[_stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|Compare characters of two strings (case insensitive)|**LC_COLLATE**| -|[_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|Compare first **n** characters of two strings|**LC_COLLATE**| -|[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](../c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)|Compare characters of two strings without regard to case.|**LC_CTYPE**| -|[_strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Compare first **n** characters of two strings (case insensitive)|**LC_COLLATE**| -|[strftime, wcsftime, _strftime_l, _wcsftime_l](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)|Format date and time value according to supplied **format** argument|**LC_TIME**| -|[_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](../c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md),[_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](../c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert, in place, each uppercase letter in given string to lowercase|**LC_CTYPE**| -|[strtod, _strtod_l, wcstod, _wcstod_l](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md)|Convert character string to **`double`** value|**LC_NUMERIC** (determines radix character recognition)| -|[strtol, wcstol, _strtol_l, _wcstol_l](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md)|Convert character string to **`long`** value|**LC_NUMERIC** (determines radix character recognition)| -|[strtoul, _strtoul_l, wcstoul, _wcstoul_l](../c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md)|Convert character string to unsigned long value|**LC_NUMERIC** (determines radix character recognition)| -|[_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](../c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md),[_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](../c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert, in place, each lowercase letter in string to uppercase|**LC_CTYPE**| -|[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form according to locale|**LC_COLLATE**| -|[tolower, _tolower, towlower, _tolower_l, _towlower_l](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md),[_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding lowercase character|**LC_CTYPE**| -|[toupper, _toupper, towupper, _toupper_l, _towupper_l](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md),[_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding uppercase letter|**LC_CTYPE**| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md),[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters|**LC_CTYPE**| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md),[wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character|**LC_CTYPE**| +*Locale* refers to country/region and language settings that you can use to customize your program. Some locale-dependent categories include the display formats for dates and monetary values. For more information, see [Locale categories](locale-categories.md). + +Use the [`setlocale`](reference/setlocale-wsetlocale.md) function to change or query some or all of the current program or thread locale information while using functions without the **`_l`** suffix. The functions with the **`_l`** suffix will use the locale parameter passed in for their locale information during the execution of that specific function only. To create a locale for use with a function with a **`_l`** suffix, use [`_create_locale`](reference/create-locale-wcreate-locale.md). To free this locale, use [`_free_locale`](reference/free-locale.md). To get the current locale, use [`_get_current_locale`](reference/get-current-locale.md). + +Use [`_configthreadlocale`](reference/configthreadlocale.md) to control whether each thread has its own locale, or all threads in a program share the same locale. For more information, see [Locales and code pages](../text/locales-and-code-pages.md). + +More secure versions of the functions in the following table are available, indicated by the **`_s`** ("secure") suffix. For more information, see [Security features in the CRT](security-features-in-the-crt.md). + +## Locale-dependent routines + +| Routine | Use | **`setlocale`** category setting dependence | +|---|---|---| +| [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](reference/atof-atof-l-wtof-wtof-l.md) | Convert character to floating-point value | `LC_NUMERIC` | +| [`atoi`, `_atoi_l`, `_wtoi`, `_wtoi_l`](reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert character to integer value | `LC_NUMERIC` | +| [`_atoi64`, `_atoi64_l`, `_wtoi64`, `_wtoi64_l`](reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert character to 64-bit integer value | `LC_NUMERIC` | +| [`atol`, `_atol_l`, `_wtol`, `_wtol_l`](reference/atol-atol-l-wtol-wtol-l.md) | Convert character to long value | `LC_NUMERIC` | +| [`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Convert character to double-long value | `LC_NUMERIC` | +| [`is`, `isw` routines](is-isw-routines.md) | Test given integer for particular condition. | `LC_CTYPE` | +| [`isleadbyte`, `_isleadbyte_l`](reference/isleadbyte-isleadbyte-l.md) | Test for lead byte | `LC_CTYPE` | +| [`localeconv`](reference/localeconv.md) | Read appropriate values for formatting numeric quantities | `LC_MONETARY, LC_NUMERIC` | +| [`MB_CUR_MAX`](mb-cur-max.md) | Maximum length in bytes of any multibyte character in current locale (macro defined in `STDLIB.H`) | `LC_CTYPE` | +| [`_mbccpy`, `_mbccpy_l`](reference/mbccpy-mbccpy-l.md), [`_mbccpy_s`, `_mbccpy_s_l`](reference/mbccpy-s-mbccpy-s-l.md) | Copy one multibyte character | `LC_CTYPE` | +| [`_mbclen`, `mblen`, `_mblen_l`](reference/mbclen-mblen-mblen-l.md) | Validate and return number of bytes in multibyte character | `LC_CTYPE` | +| [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | For multibyte-character strings: validate each character in string; return string length | `LC_CTYPE` | +| [`mbstowcs`, `_mbstowcs_l`](reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | `LC_CTYPE` | +| [`mbtowc`, `_mbtowc_l`](reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | `LC_CTYPE` | +| [`printf`](reference/printf-printf-l-wprintf-wprintf-l.md) functions | Write formatted output | `LC_NUMERIC` (determines radix character output) | +| [`scanf`](reference/scanf-scanf-l-wscanf-wscanf-l.md) functions | Read formatted input | `LC_NUMERIC` (determines radix character recognition) | +| [`setlocale`, `_wsetlocale`](reference/setlocale-wsetlocale.md) | Select locale for program | Not applicable | +| [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md) | Compare characters of two strings | `LC_COLLATE` | +| [`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) | Compare two strings without regard to case | `LC_CTYPE` | +| [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) | Compare characters of two strings (case insensitive) | `LC_COLLATE` | +| [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | Compare first **`n`** characters of two strings | `LC_COLLATE` | +| [`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) | Compare characters of two strings without regard to case. | `LC_CTYPE` | +| [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | Compare first **`n`** characters of two strings (case insensitive) | `LC_COLLATE` | +| [`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](reference/strftime-wcsftime-strftime-l-wcsftime-l.md) | Format date and time value according to supplied **`format`** argument | `LC_TIME` | +| [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md), [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) | Convert, in place, each uppercase letter in given string to lowercase | `LC_CTYPE` | +| [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](reference/strtod-strtod-l-wcstod-wcstod-l.md) | Convert character string to **`double`** value | `LC_NUMERIC` (determines radix character recognition) | +| [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](reference/strtol-wcstol-strtol-l-wcstol-l.md) | Convert character string to **`long`** value | `LC_NUMERIC` (determines radix character recognition) | +| [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) | Convert character string to unsigned long value | `LC_NUMERIC` (determines radix character recognition) | +| [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md), [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) | Convert, in place, each lowercase letter in string to uppercase | `LC_CTYPE` | +| [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) | Transform string into collated form according to locale | `LC_COLLATE` | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Convert given character to corresponding lowercase character | `LC_CTYPE` | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Convert given character to corresponding uppercase letter | `LC_CTYPE` | +| [`wcstombs`, `_wcstombs_l`](reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | `LC_CTYPE` | +| [`wctomb`, `_wctomb_l`](reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | `LC_CTYPE` | > [!NOTE] -> For multibyte routines, the multibyte code page must be equivalent to the locale set with [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). [_setmbcp](../c-runtime-library/reference/setmbcp.md), with an argument of **_MB_CP_LOCALE** makes the multibyte code page the same as the **setlocale** code page. +> For multibyte routines, the multibyte code page must be equivalent to the locale set with [`setlocale`](reference/setlocale-wsetlocale.md). [`_setmbcp`](reference/setmbcp.md), with an argument of `_MB_CP_LOCALE` makes the multibyte code page the same as the **`setlocale`** code page. ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](internationalization.md)\ +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/lock.md b/docs/c-runtime-library/lock.md index 087babd800..19562f13ef 100644 --- a/docs/c-runtime-library/lock.md +++ b/docs/c-runtime-library/lock.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _lock" title: "_lock" -ms.date: "11/04/2016" +description: "Learn more about: _lock" +ms.date: 11/04/2016 api_name: ["_lock"] api_location: ["msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110.dll", "msvcrt.dll", "msvcr120_clr0400.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["lock", "_lock"] +f1_keywords: ["_lock"] helpviewer_keywords: ["lock function", "_lock function"] -ms.assetid: 29f77c37-30de-4b3d-91b6-030216e645a6 --- -# _lock +# `_lock` Acquires a multi-thread lock. @@ -20,19 +19,19 @@ Acquires a multi-thread lock. ## Syntax ```cpp -void __cdecl _lock +void __cdecl _lock( int locknum ); ``` #### Parameters -*locknum*
+*`locknum`*\ [in] The identifier of the lock to acquire. ## Remarks -If the lock has already been acquired, this method acquires the lock anyway and causes an internal C run-time (CRT) error. If the method cannot acquire a lock, it exits with a fatal error and sets the error code to `_RT_LOCK`. +If the lock has already been acquired, this method acquires the lock anyway and causes an internal C run-time (CRT) error. If the method can't acquire a lock, it exits with a fatal error and sets the error code to `_RT_LOCK`. ## Requirements @@ -40,5 +39,5 @@ If the lock has already been acquired, this method acquires the lock anyway and ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[_unlock](../c-runtime-library/unlock.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`_unlock`](./unlock.md) diff --git a/docs/c-runtime-library/locking-constants.md b/docs/c-runtime-library/locking-constants.md index 392f25237d..3951399044 100644 --- a/docs/c-runtime-library/locking-constants.md +++ b/docs/c-runtime-library/locking-constants.md @@ -2,33 +2,33 @@ description: "Learn more about: _locking Constants" title: "_locking Constants" ms.date: "11/04/2016" -f1_keywords: ["_LK_RLCK", "_LK_NBLCK", "_LK_LOCK", "_LK_NBRLCK", "_LK_UNLCK"] +f1_keywords: ["LOCKING/_LK_RLCK", "LOCKING/_LK_NBLCK", "LOCKING/_LK_LOCK", "LOCKING/_LK_NBRLCK", "LOCKING/_LK_UNLCK", "LOCKING/LK_RLCK", "LOCKING/LK_NBLCK", "LOCKING/LK_LOCK", "LOCKING/LK_NBRLCK", "LOCKING/LK_UNLCK", "_LK_RLCK", "_LK_NBLCK", "_LK_LOCK", "_LK_NBRLCK", "_LK_UNLCK", "LK_RLCK", "LK_NBLCK", "LK_LOCK", "LK_NBRLCK", "LK_UNLCK"] helpviewer_keywords: ["LK_UNLCK constant", "LK_NBRLCK constant", "_LK_NBRLCK constant", "_LK_NBLCK constant", "_LK_LOCK constant", "LK_NBLCK constant", "_LK_UNLCK constant", "LK_RLCK constant", "_LK_RLCK constant", "LK_LOCK constant"] ms.assetid: c3dc92c8-60e3-4d29-9f50-5d217627c8ad --- -# _locking Constants +# `_locking` constants ## Syntax -``` +```C #include ``` ## Remarks -The *mode* argument in the call to the `_locking` function specifies the locking action to be performed. +The *`mode`* argument in the call to the `_locking` function specifies the locking action to be performed. -The *mode* argument must be one of the following manifest constants. +The *`mode`* argument must be one of the following manifest constants. -|Value|Description| -|-|-| -| `_LK_LOCK` | Locks the specified bytes. If the bytes cannot be locked, the function tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, the function returns an error. | -| `_LK_RLCK` | Same as `_LK_LOCK`. | -|`_LK_NBLCK` | Locks the specified bytes. If bytes cannot be locked, the function returns an error. | -| `_LK_NBRLCK` | Same as `_LK_NBLCK`. | -| `_LK_UNLCK` | Unlocks the specified bytes. (The bytes must have been previously locked.) | +| Value | Description | +|---|---| +| `_LK_LOCK` | Locks the specified bytes. If the bytes can't be locked, the function tries again after 1 second. If the bytes can't be locked after 10 attempts, the function returns an error. | +| `_LK_RLCK` | Same as `_LK_LOCK`. | +| `_LK_NBLCK` | Locks the specified bytes. If bytes can't be locked, the function returns an error. | +| `_LK_NBRLCK` | Same as `_LK_NBLCK`. | +| `_LK_UNLCK` | Unlocks the specified bytes. (The bytes must have been previously locked.) | ## See also -[_locking](../c-runtime-library/reference/locking.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_locking`](./reference/locking.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/low-level-i-o.md b/docs/c-runtime-library/low-level-i-o.md index c2f2b3f5b3..b08223be75 100644 --- a/docs/c-runtime-library/low-level-i-o.md +++ b/docs/c-runtime-library/low-level-i-o.md @@ -3,44 +3,43 @@ description: "Learn more about: Low-Level I/O" title: "Low-Level I/O" ms.date: "11/04/2016" helpviewer_keywords: ["I/O [CRT], low-level", "I/O [CRT], functions", "low-level I/O routines", "file handles [C++]", "file handles [C++], I/O functions"] -ms.assetid: 53e11bdd-6720-481c-8b2b-3a3a569ed534 --- -# Low-Level I/O +# Low-level I/O -These functions invoke the operating system directly for lower-level operation than that provided by stream I/O. Low-level input and output calls do not buffer or format data. +These functions invoke the operating system directly for lower-level operation than that provided by stream I/O. Low-level input and output calls don't buffer or format data. Low-level routines can access the standard streams opened at program startup using the following predefined file descriptors. -|Stream|File Descriptor| -|------------|---------------------| -|**stdin**|0| -|**stdout**|1| -|**stderr**|2| - -Low-level I/O routines set the [errno](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) global variable when an error occurs. You must include STDIO.H when you use low-level functions only if your program requires a constant that is defined in STDIO.H, such as the end-of-file indicator (**EOF**). - -## Low-Level I/O Functions - -|Function|Use| -|--------------|---------| -|[_close](../c-runtime-library/reference/close.md)|Close file| -|[_commit](../c-runtime-library/reference/commit.md)|Flush file to disk| -|[_creat, _wcreat](../c-runtime-library/reference/creat-wcreat.md)|Create file| -|[_dup](../c-runtime-library/reference/dup-dup2.md)|Return next available file descriptor for given file| -|[_dup2](../c-runtime-library/reference/dup-dup2.md)|Create second descriptor for given file| -|[_eof](../c-runtime-library/reference/eof.md)|Test for end of file| -|[_lseek, _lseeki64](../c-runtime-library/reference/lseek-lseeki64.md)|Reposition file pointer to given location| -|[_open, _wopen](../c-runtime-library/reference/open-wopen.md)|Open file| -|[_read](../c-runtime-library/reference/read.md)|Read data from file| -|[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md), [_sopen_s, _wsopen_s](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open file for file sharing| -|[_tell, _telli64](../c-runtime-library/reference/tell-telli64.md)|Get current file-pointer position| -|[_umask](../c-runtime-library/reference/umask.md), [_umask_s](../c-runtime-library/reference/umask-s.md)|Set file-permission mask| -|[_write](../c-runtime-library/reference/write.md)|Write data to file| - -**_dup** and **_dup2** are typically used to associate the predefined file descriptors with different files. +| Stream | File Descriptor | +|---|---| +| **`stdin`** | 0 | +| **`stdout`** | 1 | +| **`stderr`** | 2 | + +Low-level I/O routines set the [`errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) global variable when an error occurs. You must include `STDIO.H` when you use low-level functions only if your program requires a constant that is defined in `STDIO.H`, such as the end-of-file indicator (`EOF`). + +## Low-level I/O functions + +| Function | Use | +|---|---| +| [`_close`](./reference/close.md) | Close file | +| [`_commit`](./reference/commit.md) | Flush file to disk | +| [`_creat`, `_wcreat`](./reference/creat-wcreat.md) | Create file | +| [`_dup`](./reference/dup-dup2.md) | Return next available file descriptor for given file | +| [`_dup2`](./reference/dup-dup2.md) | Create second descriptor for given file | +| [`_eof`](./reference/eof.md) | Test for end of file | +| [`_lseek`, `_lseeki64`](./reference/lseek-lseeki64.md) | Reposition file pointer to given location | +| [`_open`, `_wopen`](./reference/open-wopen.md) | Open file | +| [`_read`](./reference/read.md) | Read data from file | +| [`_sopen`, `_wsopen`](./reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](./reference/sopen-s-wsopen-s.md) | Open file for file sharing | +| [`_tell`, `_telli64`](./reference/tell-telli64.md) | Get current file-pointer position | +| [`_umask`](./reference/umask.md), [`_umask_s`](./reference/umask-s.md) | Set file-permission mask | +| [`_write`](./reference/write.md) | Write data to file | + +`_dup` and `_dup2` are typically used to associate the predefined file descriptors with different files. ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[System Calls](../c-runtime-library/system-calls.md)
+[Input and output](./input-and-output.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[System calls](./system-calls.md) diff --git a/docs/c-runtime-library/math-constants.md b/docs/c-runtime-library/math-constants.md index 50afa4a9e6..61b129659a 100644 --- a/docs/c-runtime-library/math-constants.md +++ b/docs/c-runtime-library/math-constants.md @@ -2,15 +2,17 @@ description: "Learn more about: Math Constants" title: "Math Constants" ms.date: "11/04/2016" -f1_keywords: ["c.constants.math"] +f1_keywords: ["c.constants.math", "_USE_MATH_DEFINES", "CORECRT_MATH_DEFINES/M_E", "CORECRT_MATH_DEFINES/M_LOG2E", "CORECRT_MATH_DEFINES/M_LOG10E", "CORECRT_MATH_DEFINES/M_LN2", "CORECRT_MATH_DEFINES/M_LN10", "CORECRT_MATH_DEFINES/M_PI", "CORECRT_MATH_DEFINES/M_PI_2", "CORECRT_MATH_DEFINES/M_PI_4", "CORECRT_MATH_DEFINES/M_1_PI", "CORECRT_MATH_DEFINES/M_2_PI", "CORECRT_MATH_DEFINES/M_2_SQRTPI", "CORECRT_MATH_DEFINES/M_SQRT2", "CORECRT_MATH_DEFINES/M_SQRT1_2", "M_E", "M_LOG2E", "M_LOG10E", "M_LN2", "M_LN10", "M_PI", "M_PI_2", "M_PI_4", "M_1_PI", "M_2_PI", "M_2_SQRTPI", "M_SQRT2", "M_SQRT1_2"] helpviewer_keywords: ["M_PI constant", "M_PI_2 constant", "math constants", "M_2_PI constant", "M_1_PI constant", "M_E constant", "USE_MATH_DEFINES constant", "M_LOG2E constant", "M_LOG10E constant", "M_LN10 constant", "M_SQRT1_2 constant", "_USE_MATH_DEFINES constant", "M_PI_4 constant", "constants, math", "M_2_SQRTPI constant", "M_SQRT2 constant", "M_LN2 constant"] ms.assetid: db533c3f-6ae8-4520-9d35-c8fabbef3529 --- -# Math Constants +# Math constants + +Microsoft provides several predefined preprocessor macros for common math constants. ## Syntax -``` +```cpp #define _USE_MATH_DEFINES // for C++ #include @@ -22,26 +24,26 @@ ms.assetid: db533c3f-6ae8-4520-9d35-c8fabbef3529 The following symbols are defined for the values of their indicated expressions: -|Symbol|Expression|Value| -|------------|----------------|-----------| -|`M_E`|e|2.71828182845904523536| -|`M_LOG2E`|log2(e)|1.44269504088896340736| -|`M_LOG10E`|log10(e)|0.434294481903251827651| -|`M_LN2`|ln(2)|0.693147180559945309417| -|`M_LN10`|ln(10)|2.30258509299404568402| -|`M_PI`|pi|3.14159265358979323846| -|`M_PI_2`|pi/2|1.57079632679489661923| -|`M_PI_4`|pi/4|0.785398163397448309616| -|`M_1_PI`|1/pi|0.318309886183790671538| -|`M_2_PI`|2/pi|0.636619772367581343076| -|`M_2_SQRTPI`|2/sqrt(pi)|1.12837916709551257390| -|`M_SQRT2`|sqrt(2)|1.41421356237309504880| -|`M_SQRT1_2`|1/sqrt(2)|0.707106781186547524401| - -Math Constants are not defined in Standard C/C++. To use them, you must first define `_USE_MATH_DEFINES` and then include cmath or *`math.h`*. - -The file *`ATLComTime.h`* includes *`math.h`* when your project is built in Release mode. If you use one or more of the math constants in a project that also includes *`ATLComTime.h`*, you must define `_USE_MATH_DEFINES` before you include *`ATLComTime.h`*. +| Symbol | Expression | Value | +|---|---|---| +| `M_E` | e | 2.71828182845904523536 | +| `M_LOG2E` | log2(e) | 1.44269504088896340736 | +| `M_LOG10E` | log10(e) | 0.434294481903251827651 | +| `M_LN2` | ln(2) | 0.693147180559945309417 | +| `M_LN10` | ln(10) | 2.30258509299404568402 | +| `M_PI` | pi | 3.14159265358979323846 | +| `M_PI_2` | pi/2 | 1.57079632679489661923 | +| `M_PI_4` | pi/4 | 0.785398163397448309616 | +| `M_1_PI` | 1/pi | 0.318309886183790671538 | +| `M_2_PI` | 2/pi | 0.636619772367581343076 | +| `M_2_SQRTPI` | 2/sqrt(pi) | 1.12837916709551257390 | +| `M_SQRT2` | sqrt(2) | 1.41421356237309504880 | +| `M_SQRT1_2` | 1/sqrt(2) | 0.707106781186547524401 | + +The math constants aren't defined in Standard C/C++. To use them, you must first define `_USE_MATH_DEFINES`, and then include `` or ``. + +The file `` includes `` when your project is built in Release mode. If you use one or more of the math constants in a project that also includes ``, you must define `_USE_MATH_DEFINES` before you include ``. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/math-error-constants.md b/docs/c-runtime-library/math-error-constants.md index 394f6be7e7..78d4219229 100644 --- a/docs/c-runtime-library/math-error-constants.md +++ b/docs/c-runtime-library/math-error-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: Math Error Constants" title: "Math Error Constants" ms.date: "11/04/2016" -f1_keywords: ["_PLOSS", "_UNDERFLOW", "_TLOSS", "_SING", "_DOMAIN", "_OVERFLOW"] +f1_keywords: ["CORECRT_MATH/_PLOSS", "CORECRT_MATH/_UNDERFLOW", "CORECRT_MATH/_TLOSS", "CORECRT_MATH/_SING", "CORECRT_MATH/_DOMAIN", "CORECRT_MATH/_OVERFLOW", "_PLOSS", "_UNDERFLOW", "_TLOSS", "_SING", "_DOMAIN", "_OVERFLOW"] helpviewer_keywords: ["_TLOSS constant", "_SING constant", "PLOSS constant", "UNDERFLOW constant", "_UNDERFLOW constant", "_OVERFLOW constant", "DOMAIN constant", "OVERFLOW constant", "TLOSS constant", "SING constant", "_DOMAIN constant", "_PLOSS constant", "math error constants"] ms.assetid: 4be933a6-674e-45a5-8ac9-090023542f5b --- -# Math Error Constants +# Math error constants ## Syntax -``` +```C #include ``` @@ -20,16 +20,16 @@ The math routines of the run-time library can generate math error constants. These errors, described as follows, correspond to the exception types defined in MATH.H and are returned by the `_matherr` function when a math error occurs. -|Constant|Meaning| -|--------------|-------------| -|`_DOMAIN`|Argument to function is outside domain of function.| -|`_OVERFLOW`|Result is too large to be represented in function's return type.| -|`_PLOSS`|Partial loss of significance occurred.| -|`_SING`|Argument singularity: argument to function has illegal value. (For example, value 0 is passed to function that requires nonzero value.)| -|`_TLOSS`|Total loss of significance occurred.| -|`_UNDERFLOW`|Result is too small to be represented.| +| Constant | Meaning | +|---|---| +| `_DOMAIN` | Argument to function is outside domain of function. | +| `_OVERFLOW` | Result is too large to be represented in function's return type. | +| `_PLOSS` | Partial loss of significance occurred. | +| `_SING` | Argument singularity: argument to function has illegal value. (For example, value 0 is passed to function that requires nonzero value.) | +| `_TLOSS` | Total loss of significance occurred. | +| `_UNDERFLOW` | Result is too small to be represented. | ## See also -[_matherr](../c-runtime-library/reference/matherr.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_matherr`](./reference/matherr.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/max-env.md b/docs/c-runtime-library/max-env.md index 040f8e0d81..8c4c735c43 100644 --- a/docs/c-runtime-library/max-env.md +++ b/docs/c-runtime-library/max-env.md @@ -2,21 +2,21 @@ description: "Learn more about: _MAX_ENV" title: "_MAX_ENV" ms.date: "11/04/2016" -f1_keywords: ["_MAX_ENV", "MAX_ENV"] -helpviewer_keywords: ["MAX_ENV constant", "_MAX_ENV constant"] +f1_keywords: ["_MAX_ENV", "STDLIB/_MAX_ENV"] +helpviewer_keywords: ["_MAX_ENV constant"] ms.assetid: 66f0683e-6132-4297-b99b-6940534898b5 --- -# _MAX_ENV +# `_MAX_ENV` The maximum permissible string length of an environmental variable. ## Syntax -``` +```C #include ``` ## See also -[Environmental Constants](../c-runtime-library/environmental-constants.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Environmental constants](./environmental-constants.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md b/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md index 166fd485fe..4c8ff5a4ab 100644 --- a/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md +++ b/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md @@ -3,14 +3,14 @@ description: "Learn more about: ___mb_cur_max_func, ___mb_cur_max_l_func, __p___ title: "___mb_cur_max_func, ___mb_cur_max_l_func, __p___mb_cur_max, __mb_cur_max" ms.date: "4/2/2020" api_name: ["___mb_cur_max_l_func", "__p___mb_cur_max", "___mb_cur_max_func", "__mb_cur_max", "_o____mb_cur_max_func"] -api_location: ["msvcr110_clr0400.dll", "msvcr110.dll", "msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110_clr0400.dll", "msvcr110.dll", "msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max", "__mb_cur_max"] +f1_keywords: ["STDLIB/___mb_cur_max_func", "STDLIB/___mb_cur_max_l_func", "STDLIB/__mb_cur_max", "___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max", "__mb_cur_max"] helpviewer_keywords: ["__mb_cur_max", "___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max"] ms.assetid: 60d36108-1ca7-45a6-8ce7-68a91f13e3a1 --- -# ___mb_cur_max_func, ___mb_cur_max_l_func, __p___mb_cur_max, __mb_cur_max +# `___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max` Internal CRT function. Retrieves the maximum number of bytes in a multibyte character for the current or specified locale. @@ -25,29 +25,29 @@ int * __p___mb_cur_max(void); #### Parameters -locale +*`locale`*\ The locale structure to retrieve the result from. If this value is null, the current thread locale is used. -## Return Value +## Return value The maximum number of bytes in a multibyte character for the current thread locale or the specified locale. ## Remarks -This is an internal function that the CRT uses to retrieve the current value of the [MB_CUR_MAX](../c-runtime-library/mb-cur-max.md) macro from thread local storage. We recommend that you use the `MB_CUR_MAX` macro in your code for portability. +**`___mb_cur_max_func`** is an internal function that the CRT uses to retrieve the current value of the [`MB_CUR_MAX`](./mb-cur-max.md) macro from thread local storage. We recommend that you use the `MB_CUR_MAX` macro in your code for portability. -The `__mb_cur_max` macro is a convenient way to call the `___mb_cur_max_func()` function. The `__p___mb_cur_max` function is defined for compatibility with Visual C++ 5.0 and earlier versions. +The **`__mb_cur_max`** macro is a convenient way to call the **`___mb_cur_max_func`** function. The **`__p___mb_cur_max`** function is defined for compatibility with Visual C++ 5.0 and earlier versions. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`|\, \| +| Routine | Required header | +|---|---| +| **`___mb_cur_max_func`**, **`___mb_cur_max_l_func`**, **`__p___mb_cur_max`** | \, \ | ## See also -[MB_CUR_MAX](../c-runtime-library/mb-cur-max.md) +[`MB_CUR_MAX`](./mb-cur-max.md) diff --git a/docs/c-runtime-library/mb-cur-max.md b/docs/c-runtime-library/mb-cur-max.md index 259ce06545..28e22034ba 100644 --- a/docs/c-runtime-library/mb-cur-max.md +++ b/docs/c-runtime-library/mb-cur-max.md @@ -2,7 +2,7 @@ description: "Learn more about: MB_CUR_MAX" title: "MB_CUR_MAX" ms.date: "10/18/2017" -f1_keywords: ["MB_CUR_MAX"] +f1_keywords: ["MB_CUR_MAX", "CTYPE/MB_CUR_MAX"] helpviewer_keywords: ["MB_CUR_MAX constant"] ms.assetid: fab22609-c14d-4c19-991c-bd09ff30e604 --- @@ -24,12 +24,12 @@ The value of `MB_CUR_MAX` is the maximum number of bytes in a multibyte characte ## See also -[`_mbclen`, `mblen`, `_mblen_l`](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)
-[`mbstowcs`, `_mbstowcs_l`](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md)
-[`mbtowc`, `_mbtowc_l`](../c-runtime-library/reference/mbtowc-mbtowc-l.md)
-[`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)
-[Standard Types](../c-runtime-library/standard-types.md)
-[`wcstombs`, `_wcstombs_l`](../c-runtime-library/reference/wcstombs-wcstombs-l.md)
-[`wctomb`, `_wctomb_l`](../c-runtime-library/reference/wctomb-wctomb-l.md)
-[Data Type Constants](../c-runtime-library/data-type-constants.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md)\ +[`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)\ +[Standard types](./standard-types.md)\ +[`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md)\ +[Data type constants](./data-type-constants.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/memory-allocation.md b/docs/c-runtime-library/memory-allocation.md index 09a9aeca3c..605cf305cb 100644 --- a/docs/c-runtime-library/memory-allocation.md +++ b/docs/c-runtime-library/memory-allocation.md @@ -11,35 +11,35 @@ These routines allocate, free, and reallocate memory. ## Memory-allocation routines -|Routine|Use| -|-------------|---------| -|[`_alloca`](../c-runtime-library/reference/alloca.md), [`_malloca`](../c-runtime-library/reference/malloca.md)|Allocate memory from the stack| -|[`calloc`](../c-runtime-library/reference/calloc.md)|Allocate an array and initialize its elements to 0 (zero)| -|[`_calloc_dbg`](../c-runtime-library/reference/calloc-dbg.md)|Debug version of **`calloc`**. Only available in the debug versions of the run-time libraries| -|[`operator delete`, `operator delete[]`](../c-runtime-library/delete-operator-crt.md)|Free memory allocated on the heap | -|[`_expand`](../c-runtime-library/reference/expand.md)|Expand or shrink a block of memory without moving it| -|[`_expand_dbg`](../c-runtime-library/reference/expand-dbg.md)|Debug version of **`_expand`**. Only available in the debug versions of the run-time libraries| -|[`free`](../c-runtime-library/reference/free.md)|Free memory allocated on the heap| -|[`_free_dbg`](../c-runtime-library/reference/free-dbg.md)|Debug version of **`free`**. Only available in the debug versions of the run-time libraries| -|[`_freea`](../c-runtime-library/reference/freea.md)|Free memory allocated on the stack| -|[`_get_heap_handle`](../c-runtime-library/reference/get-heap-handle.md)|Get a Win32 `HANDLE` to the C runtime (CRT) heap.| -|[`_heapadd`](../c-runtime-library/heapadd.md)|Add memory to the heap| -|[`_heapchk`](../c-runtime-library/reference/heapchk.md)|Check the heap for consistency| -|[`_heapmin`](../c-runtime-library/reference/heapmin.md)|Release unused memory in the heap| -|[`_heapset`](../c-runtime-library/heapset.md)|Fill free heap entries with a value| -|[`_heapwalk`](../c-runtime-library/reference/heapwalk.md)|Get info about each entry in the heap| -|[`malloc`](../c-runtime-library/reference/malloc.md)|Allocate memory from the heap| -|[`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md)|Debug version of **`malloc`**; only available in the debug versions of the run-time libraries| -|[`_msize`](../c-runtime-library/reference/msize.md)|Return the size of an allocated block of memory| -|[`_msize_dbg`](../c-runtime-library/reference/msize-dbg.md)|Debug version of **`_msize`**; only available in the debug versions of the run-time libraries| -|[`new`, `new[]`](../c-runtime-library/new-operator-crt.md)|Allocate a block of memory from the heap| -|[`_query_new_handler`](../c-runtime-library/reference/query-new-handler.md)|Get the address of the current new handler routine set by **`_set_new_handler`**| -|[`_query_new_mode`](../c-runtime-library/reference/query-new-mode.md)|Get the new handler mode set by **`_set_new_mode`** for **`malloc`**| -|[`realloc`](../c-runtime-library/reference/realloc.md)|Reallocate a block to a new size| -|[`_realloc_dbg`](../c-runtime-library/reference/realloc-dbg.md)|Debug version of **`realloc`**; only available in the debug versions of the run-time libraries| -|[`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md)|Enable error-handling mechanism when the **`new`** operator fails to allocate memory, and enable compilation of the C++ Standard Libraries| -|[`_set_new_mode`](../c-runtime-library/reference/set-new-mode.md)|Set the new handler mode for **`malloc`**| +| Routine | Use | +|---|---| +| [`_alloca`](./reference/alloca.md), [`_malloca`](./reference/malloca.md) | Allocate memory from the stack | +| [`calloc`](./reference/calloc.md) | Allocate an array and initialize its elements to 0 (zero) | +| [`_calloc_dbg`](./reference/calloc-dbg.md) | Debug version of **`calloc`**. Only available in the debug versions of the run-time libraries | +| [`operator delete`, `operator delete[]`](./delete-operator-crt.md) | Free memory allocated on the heap | +| [`_expand`](./reference/expand.md) | Expand or shrink a block of memory without moving it | +| [`_expand_dbg`](./reference/expand-dbg.md) | Debug version of **`_expand`**. Only available in the debug versions of the run-time libraries | +| [`free`](./reference/free.md) | Free memory allocated on the heap | +| [`_free_dbg`](./reference/free-dbg.md) | Debug version of **`free`**. Only available in the debug versions of the run-time libraries | +| [`_freea`](./reference/freea.md) | Free memory allocated on the stack | +| [`_get_heap_handle`](./reference/get-heap-handle.md) | Get a Win32 `HANDLE` to the C runtime (CRT) heap. | +| [`_heapadd`](./heapadd.md) | Add memory to the heap | +| [`_heapchk`](./reference/heapchk.md) | Check the heap for consistency | +| [`_heapmin`](./reference/heapmin.md) | Release unused memory in the heap | +| [`_heapset`](./heapset.md) | Fill free heap entries with a value | +| [`_heapwalk`](./reference/heapwalk.md) | Get info about each entry in the heap | +| [`malloc`](./reference/malloc.md) | Allocate memory from the heap | +| [`_malloc_dbg`](./reference/malloc-dbg.md) | Debug version of **`malloc`**; only available in the debug versions of the run-time libraries | +| [`_msize`](./reference/msize.md) | Return the size of an allocated block of memory | +| [`_msize_dbg`](./reference/msize-dbg.md) | Debug version of **`_msize`**; only available in the debug versions of the run-time libraries | +| [`new`, `new[]`](./new-operator-crt.md) | Allocate a block of memory from the heap | +| [`_query_new_handler`](./reference/query-new-handler.md) | Get the address of the current new handler routine set by **`_set_new_handler`** | +| [`_query_new_mode`](./reference/query-new-mode.md) | Get the new handler mode set by **`_set_new_mode`** for **`malloc`** | +| [`realloc`](./reference/realloc.md) | Reallocate a block to a new size | +| [`_realloc_dbg`](./reference/realloc-dbg.md) | Debug version of **`realloc`**; only available in the debug versions of the run-time libraries | +| [`_set_new_handler`](./reference/set-new-handler.md) | Enable error-handling mechanism when the **`new`** operator fails to allocate memory, and enable compilation of the C++ Standard Libraries | +| [`_set_new_mode`](./reference/set-new-mode.md) | Set the new handler mode for **`malloc`** | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/multithreaded-libraries-performance.md b/docs/c-runtime-library/multithreaded-libraries-performance.md index d8aa90c502..12d78d352f 100644 --- a/docs/c-runtime-library/multithreaded-libraries-performance.md +++ b/docs/c-runtime-library/multithreaded-libraries-performance.md @@ -6,26 +6,26 @@ ms.topic: "conceptual" helpviewer_keywords: ["threading [C++], performance", "libraries, multithreaded", "performance, multithreading", "multithreaded libraries"] ms.assetid: faa5d808-087c-463d-8f0d-8c478d137296 --- -# Multithreaded Libraries Performance +# Multithreaded libraries performance -The single-threaded CRT is no longer available. This topic discusses how to get the maximum performance from the multithreaded libraries. +The single-threaded CRT is no longer available. This article discusses how to get the maximum performance from the multithreaded libraries. ## Maximizing performance The performance of the multithreaded libraries has been improved and is close to the performance of the now-eliminated single-threaded libraries. For those situations when even higher performance is required, there are several new features. -- Independent stream locking allows you to lock a stream and then use [_nolock Functions](../c-runtime-library/nolock-functions.md) that access the stream directly. This allows lock usage to be hoisted outside critical loops. +- Independent stream locking allows you to lock a stream and then use [`_nolock` functions](./nolock-functions.md) that access the stream directly. This feature allows lock usage to be hoisted outside critical loops. -- Per-thread locale reduces the cost of locale access for multithreaded scenarios (see [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md)). +- Per-thread locale reduces the cost of locale access for multithreaded scenarios (see [`_configthreadlocale`](./reference/configthreadlocale.md)). -- Locale-dependent functions (with names ending in _l) take the locale as a parameter, removing substantial cost (for example, [printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)). +- Locale-dependent functions (with names ending in _l) take the locale as a parameter, removing substantial cost (for example, [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md)). - Optimizations for common codepages reduce the cost of many short operations. -- Defining [_CRT_DISABLE_PERFCRIT_LOCKS](../c-runtime-library/crt-disable-perfcrit-locks.md) forces all I/O operations to assume a single-threaded I/O model and use the _nolock forms of the functions. This allows highly I/O-based single-threaded applications to get better performance. +- Defining [`_CRT_DISABLE_PERFCRIT_LOCKS`](./crt-disable-perfcrit-locks.md) forces all I/O operations to assume a single-threaded I/O model and use the `_nolock` forms of the functions. This macro allows highly I/O-based single-threaded applications to get better performance. - Exposure of the CRT heap handle allows you to enable the Windows Low Fragmentation Heap (LFH) for the CRT heap, which can substantially improve performance in highly scaled scenarios. ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/new-operator-crt.md b/docs/c-runtime-library/new-operator-crt.md index dd43a78d1b..c5273af0c4 100644 --- a/docs/c-runtime-library/new-operator-crt.md +++ b/docs/c-runtime-library/new-operator-crt.md @@ -5,10 +5,9 @@ ms.date: "11/04/2016" api_location: ["msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["new[]"] helpviewer_keywords: ["operator new[]", "vector new"] ms.assetid: 79682f85-6889-40f6-b8f7-9eed5176ea35 --- -# operator new(CRT) +# `operator new` (CRT) -Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator new and operator delete functions. These are now part of the C++ Standard Library. For more information, see [new and delete operators](../cpp/new-and-delete-operators.md) and [new operator](../cpp/new-operator-cpp.md) in the C++ Language Reference. +Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific `operator new` and `operator delete` functions. These functions are now part of the C++ Standard Library. For more information, see [`new` and `delete` operators](../cpp/new-and-delete-operators.md) and [`new` operator](../cpp/new-operator-cpp.md) in the C++ Language Reference. diff --git a/docs/c-runtime-library/nolock-functions.md b/docs/c-runtime-library/nolock-functions.md index 6cfc9a402e..b231f2d923 100644 --- a/docs/c-runtime-library/nolock-functions.md +++ b/docs/c-runtime-library/nolock-functions.md @@ -1,53 +1,38 @@ --- -description: "Learn more about: _nolock Functions" title: "_nolock Functions" -ms.date: "11/04/2016" +description: "Learn more about: _nolock Functions" +ms.date: "04/14/2024" helpviewer_keywords: ["_nolock functions", "nolock functions"] -ms.assetid: 7d651d87-38d2-4303-9897-fdb5f7a3e899 --- -# _nolock Functions +# `_nolock` functions -These are functions that do not perform any locking. They are provided for users requiring maximum performance. For more information, see [Multithreaded Libraries Performance](../c-runtime-library/multithreaded-libraries-performance.md). +The `_nolock` functions are versions of I/O functions that don't perform any locking. They're provided for users requiring maximum performance. For more information, see [Multithreaded libraries performance](multithreaded-libraries-performance.md). -Use _nolock functions only if your program is truly single-threaded or if it does its own locking. +Use `_nolock` functions only if your program is truly single-threaded or if it does its own locking. ## No lock routines -[_fclose_nolock](../c-runtime-library/reference/fclose-nolock.md) - -[_fflush_nolock](../c-runtime-library/reference/fflush-nolock.md) - -[_fgetc_nolock, _fgetwc_nolock](../c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md) - -[_fread_nolock](../c-runtime-library/reference/fread-nolock.md) - -[_fseek_nolock, _fseeki64_nolock](../c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md) - -[_ftell_nolock, _ftelli64_nolock](../c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md) - -[_fwrite_nolock](../c-runtime-library/reference/fwrite-nolock.md) - -[_getc_nolock, _getwc_nolock](../c-runtime-library/reference/getc-nolock-getwc-nolock.md) - -[_getch_nolock, _getwch_nolock](../c-runtime-library/reference/getch-nolock-getwch-nolock.md) - -[_getchar_nolock, _getwchar_nolock](../c-runtime-library/reference/getchar-nolock-getwchar-nolock.md) - -[_getche_nolock, _getwche_nolock](../c-runtime-library/reference/getche-nolock-getwche-nolock.md) - -[_getdcwd_nolock, _wgetdcwd_nolock](../c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md) - -[_putc_nolock, _putwc_nolock](../c-runtime-library/reference/putc-nolock-putwc-nolock.md) - -[_putch_nolock, _putwch_nolock](../c-runtime-library/reference/putch-nolock-putwch-nolock.md) - -[_putchar_nolock, _putwchar_nolock](../c-runtime-library/reference/putchar-nolock-putwchar-nolock.md) - -[_ungetc_nolock, _ungetwc_nolock](../c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md) - -[_ungetch_nolock, _ungetwch_nolock](../c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) +| Routine | Use | +|---|---| +| [`_fclose_nolock`](reference/fclose-nolock.md) | Closes a stream without locking | +| [`_fflush_nolock`](reference/fflush-nolock.md) | Flushes a stream without locking | +| [`_fgetc_nolock`, `_fgetwc_nolock`](reference/fgetc-nolock-fgetwc-nolock.md) | Reads a character from a stream without locking | +| [`_fread_nolock`](reference/fread-nolock.md) | Reads data from a stream without locking | +| [`_fseek_nolock`, `_fseeki64_nolock`](reference/fseek-nolock-fseeki64-nolock.md) | Moves the file pointer to a specified location without locking | +| [`_ftell_nolock`, `_ftelli64_nolock`](reference/ftell-nolock-ftelli64-nolock.md) | Gets the current position of a file pointer without locking | +| [`_fwrite_nolock`](reference/fwrite-nolock.md) | Writes data to a stream without locking | +| [`_getc_nolock`, `_getwc_nolock`](reference/getc-nolock-getwc-nolock.md) | Reads a character from a stream without locking | +| [`_getch_nolock`, `_getwch_nolock`](reference/getch-nolock-getwch-nolock.md) | Gets a character from the console without echo and without locking | +| [`_getchar_nolock`, `_getwchar_nolock`](reference/getchar-nolock-getwchar-nolock.md) | Reads a character from the standard input without locking | +| [`_getche_nolock`, `_getwche_nolock`](reference/getche-nolock-getwche-nolock.md) | Gets a character from the console with echo and without locking | +| [`_getdcwd_nolock`, `_wgetdcwd_nolock`](reference/getdcwd-nolock-wgetdcwd-nolock.md) | Gets the full path of the current working directory on the specified drive | +| [`_putc_nolock`, `_putwc_nolock`](reference/putc-nolock-putwc-nolock.md) | Writes a character to a stream without locking | +| [`_putch_nolock`, `_putwch_nolock`](reference/putch-nolock-putwch-nolock.md) | Writes a character to the console without locking | +| [`_putchar_nolock`, `_putwchar_nolock`](reference/putchar-nolock-putwchar-nolock.md) | Writes a character to `stdout` without locking | +| [`_ungetc_nolock`, `_ungetwc_nolock`](reference/ungetc-nolock-ungetwc-nolock.md) | Pushes a character back onto the stream without locking | +| [`_ungetch_nolock`, `_ungetwch_nolock`](reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) | Pushes back the last character that's read from the console without locking | ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Input and output](input-and-output.md)\ +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/null-crt.md b/docs/c-runtime-library/null-crt.md index 9286b072fb..a0e2fb5725 100644 --- a/docs/c-runtime-library/null-crt.md +++ b/docs/c-runtime-library/null-crt.md @@ -2,14 +2,14 @@ description: "Learn more about: NULL (CRT)" title: "NULL (CRT)" ms.date: "11/04/2016" -f1_keywords: ["null"] +f1_keywords: ["NULL", "VCRUNTIME/NULL"] helpviewer_keywords: ["NULL", "null pointers", "NULL, null pointer value"] ms.assetid: f9aac2a0-4f79-423f-8738-a76dccc0b1c3 --- -# NULL (CRT) +# `NULL` (CRT) -**NULL** is the null-pointer value used with many pointer operations and functions. It is equivalent to 0. **NULL** is defined in the following header files: CRTDBG.H, LOCALE.H, STDDEF.H, STDIO.H, STDLIB.H, STRING.H, TCHAR.H, TIME.H and WCHAR.H. +`NULL` is the null-pointer value used with many pointer operations and functions. It's equivalent to 0. `NULL` is defined in the following header files: CRTDBG.H, LOCALE.H, STDDEF.H, STDIO.H, STDLIB.H, STRING.H, TCHAR.H, TIME.H and WCHAR.H. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/obsolete-functions.md b/docs/c-runtime-library/obsolete-functions.md index 7a8b34d60b..90759b70fa 100644 --- a/docs/c-runtime-library/obsolete-functions.md +++ b/docs/c-runtime-library/obsolete-functions.md @@ -3,46 +3,45 @@ title: "Obsolete functions" description: "Lists the obsolete functions that have been deprecated and removed from the Microsoft C runtime library (CRT)." ms.date: "4/2/2020" api_name: ["_beep", "_sleep", "_loaddll", "_getdllprocaddr", "_seterrormode", "is_wctype", "_getsystime", "_setsystime", "_unloaddll", "_o__beep", "_o__getdllprocaddr", "_o__getsystime", "_o__loaddll", "_o__seterrormode", "_o__setsystime", "_o__sleep", "_o__unloaddll", "_o_is_wctype"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["is_wctype", "_loaddll", "_unloaddll", "_getdllprocaddr", "_seterrormode", "_beep", "_sleep", "_getsystime", "corecrt_wctype/is_wctype", "process/_loaddll", "process/_unloaddll", "process/_getdllprocaddr", "stdlib/_seterrormode", "stdlib/_beep", "stdlib/_sleep", "time/_getsystime", "time/_setsystime"] helpviewer_keywords: ["obsolete functions", "_beep function", "_sleep function", "_seterrormode function"] ms.assetid: 8e14c2d4-1481-4240-8586-47eb43db02b0 --- -# Obsolete Functions +# Obsolete functions Certain library functions are obsolete and have more recent equivalents. We recommend you change these functions to the updated versions. Other obsolete functions have been removed from the CRT. This article lists the functions deprecated as obsolete, and the functions removed in a particular version of Visual Studio. ## Deprecated as obsolete in Visual Studio 2015 -|Obsolete function|Alternative| -|-----------------------|-----------------| -|`is_wctype`|[iswctype](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)| -|`_loaddll`|[LoadLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw), [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw), or [LoadPackagedLibrary](/windows/win32/api/winbase/nf-winbase-loadpackagedlibrary)| -|`_unloaddll`|[FreeLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-freelibrary)| -|`_getdllprocaddr`|[GetProcAddress](../build/getprocaddress.md)| -|`_seterrormode`|[SetErrorMode](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode)| -|`_beep`|[Beep](/windows/win32/api/utilapiset/nf-utilapiset-beep)| -|`_sleep`|[Sleep](/windows/win32/api/synchapi/nf-synchapi-sleep)| -|`_getsystime`|[GetLocalTime](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlocaltime)| -|`_setsystime`|[SetLocalTime](/windows/win32/api/sysinfoapi/nf-sysinfoapi-setlocaltime)| +| Obsolete function | Alternative | +|---|---| +| `is_wctype` | [`iswctype`](./reference/isctype-iswctype-isctype-l-iswctype-l.md) | +| `_loaddll` | [`LoadLibrary`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw), [`LoadLibraryEx`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw), or [`LoadPackagedLibrary`](/windows/win32/api/winbase/nf-winbase-loadpackagedlibrary) | +| `_unloaddll` | [`FreeLibrary`](/windows/win32/api/libloaderapi/nf-libloaderapi-freelibrary) | +| `_getdllprocaddr` | [`GetProcAddress`](../build/getprocaddress.md) | +| `_seterrormode` | [`SetErrorMode`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode) | +| `_beep` | [`Beep`](/windows/win32/api/utilapiset/nf-utilapiset-beep) | +| `_sleep` | [`Sleep`](/windows/win32/api/synchapi/nf-synchapi-sleep) | +| `_getsystime` | [`GetLocalTime`](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlocaltime) | +| `_setsystime` | [`SetLocalTime`](/windows/win32/api/sysinfoapi/nf-sysinfoapi-setlocaltime) | ## Removed from the CRT in Visual Studio 2015 -|Obsolete function|Alternative| -|-----------------------|-----------------| -|[_cgets, _cgetws](../c-runtime-library/cgets-cgetws.md)|[_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md)| -|[gets, _getws](../c-runtime-library/gets-getws.md)|[gets_s, _getws_s](../c-runtime-library/reference/gets-s-getws-s.md)| -|[_get_output_format](../c-runtime-library/get-output-format.md)|None| -|[_heapadd](../c-runtime-library/heapadd.md)|None| -|[_heapset](../c-runtime-library/heapset.md)|None| -|[inp, inpw, _inp, _inpw, _inpd](../c-runtime-library/inp-inpw-inpd.md)|None| -|[outp, outpw, _outp, _outpw, _outpd](../c-runtime-library/outp-outpw-outpd.md)|None| -|[_set_output_format](../c-runtime-library/set-output-format.md)|None| +| Obsolete function | Alternative | +|---|---| +| [`_cgets`, `_cgetws`](./cgets-cgetws.md) | [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | +| [`gets`, `_getws`](./gets-getws.md) | [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md) | +| [`_get_output_format`](./get-output-format.md) | None | +| [`_heapadd`](./heapadd.md) | None | +| [`_heapset`](./heapset.md) | None | +| [`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](./inp-inpw-inpd.md) | None | +| [`outp`, `outpw`, `_outp`, `_outpw`, `_outpd`](./outp-outpw-outpd.md) | None | +| [`_set_output_format`](./set-output-format.md) | None | ## Removed from the CRT in earlier versions of Visual Studio -[_lock](../c-runtime-library/lock.md) - -[_unlock](../c-runtime-library/unlock.md) +[`_lock`](./lock.md)\ +[`_unlock`](./unlock.md) diff --git a/docs/c-runtime-library/outp-outpw-outpd.md b/docs/c-runtime-library/outp-outpw-outpd.md index 161f457d1e..bc7244ca7a 100644 --- a/docs/c-runtime-library/outp-outpw-outpd.md +++ b/docs/c-runtime-library/outp-outpw-outpd.md @@ -12,7 +12,7 @@ ms.assetid: c200fe22-41f6-46fd-b0be-ebb805b35181 --- # `outp`, `outpw`, `_outp`, `_outpw`, `_outpd` -Outputs, at a port, a byte (`outp`, `_outp`), a word (`outpw`, `_outpw`), or a double word (`_outpd`). +Outputs, at a port, a byte (**`outp`**, **`_outp`**), a word (**`outpw`**, **`_outpw`**), or a double word (**`_outpd`**). > [!IMPORTANT] > These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT.\ @@ -43,35 +43,35 @@ Port number. *`data_byte`*, *`data_word`*\ Output values. -## Return Value +## Return value The functions return the data output. There's no error return. ## Remarks -The `_outp`, `_outpw`, and `_outpd` functions write a byte, a word, and a double word, respectively, to the specified output port. The *`port`* argument can be any unsigned integer in the range 0 - 65,535. *`data_byte`* can be any integer in the range 0 - 255. *`data_word`* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. +The **`_outp`**, **`_outpw`**, and **`_outpd`** functions write a byte, a word, and a double word, respectively, to the specified output port. The *`port`* argument can be any unsigned integer in the range 0 - 65,535. *`data_byte`* can be any integer in the range 0 - 255. *`data_word`* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. Because these functions write directly to an I/O port, they can't be used in user-mode Windows code. -For information about using I/O ports in the Windows operating system, see [Serial Communications](/previous-versions/ff802693(v=msdn.10)). +For information about using I/O ports in the Windows operating system, see [Serial communications](/previous-versions/ff802693(v=msdn.10)). -The `outp` and `outpw` names are older, deprecated names for the `_outp` and `_outpw` functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +The **`outp`** and **`outpw`** names are older, deprecated names for the **`_outp`** and **`_outpw`** functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_outp`|\| -|`_outpw`|\| -|`_outpd`|\| +| Routine | Required header | +|---|---| +| **`_outp`** | \ | +| **`_outpw`** | \ | +| **`_outpd`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Libraries -All versions of the [C run-time libraries](../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](./crt-library-features.md). ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)\ -[`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](../c-runtime-library/inp-inpw-inpd.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](./inp-inpw-inpd.md) diff --git a/docs/c-runtime-library/p-commode.md b/docs/c-runtime-library/p-commode.md index f9ced688c9..3367ece1ce 100644 --- a/docs/c-runtime-library/p-commode.md +++ b/docs/c-runtime-library/p-commode.md @@ -3,14 +3,14 @@ description: "Learn more about: __p__commode" title: "__p__commode" ms.date: "4/2/2020" api_name: ["__p__commode", "_o___p__commode"] -api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__p__commode"] +f1_keywords: ["STDIO/__p__commode", "__p__commode"] helpviewer_keywords: ["__p__commode"] ms.assetid: 4380acb8-e3e4-409c-a60f-6205ac5189ce --- -# __p__commode +# `__p__commode` Points to the `_commode` global variable, which specifies the default *file commit mode* for file I/O operations. @@ -21,20 +21,20 @@ int * __p__commode( ); ``` -## Return Value +## Return value Pointer to the `_commode` global variable. ## Remarks -The `__p__commode` function is for internal use only, and should not be called from user code. +The **`__p__commode`** function is for internal use only, and shouldn't be called from user code. -File commit mode specifies when critical data is written to disk. For more information, see [fflush](../c-runtime-library/reference/fflush.md). +File commit mode specifies when critical data is written to disk. For more information, see [`fflush`](./reference/fflush.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__p\__commode|internal.h| +| Routine | Required header | +|---|---| +| **`__p__commode`** | `internal.h` | diff --git a/docs/c-runtime-library/p-fmode.md b/docs/c-runtime-library/p-fmode.md index 8d2e7075ca..ce214aea1b 100644 --- a/docs/c-runtime-library/p-fmode.md +++ b/docs/c-runtime-library/p-fmode.md @@ -3,14 +3,14 @@ description: "Learn more about: __p__fmode" title: "__p__fmode" ms.date: "4/2/2020" api_name: ["__p__fmode", "_o___p__fmode"] -api_location: ["msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__p__fmode"] +f1_keywords: ["STDLIB/__p__fmode", "__p__fmode"] helpviewer_keywords: ["__p__fmode"] ms.assetid: 1daa1394-81eb-43aa-a71b-4cc6acf3207b --- -# __p__fmode +# `__p__fmode` Points to the `_fmode` global variable, which specifies the default *file translation mode* for file I/O operations. @@ -21,20 +21,20 @@ int* __p__fmode( ); ``` -## Return Value +## Return value Pointer to the `_fmode` global variable. ## Remarks -The `__p__fmode` function is for internal use only, and should not be called from user code. +The **`__p__fmode`** function is for internal use only, and shouldn't be called from user code. -File translation mode specifies either `binary` or `text` translation for [_open](../c-runtime-library/reference/open-wopen.md) and [_pipe](../c-runtime-library/reference/pipe.md) I/O operations. For more information, see [_fmode](../c-runtime-library/fmode.md). +File translation mode specifies either `binary` or `text` translation for [`_open`](./reference/open-wopen.md) and [`_pipe`](./reference/pipe.md) I/O operations. For more information, see [`_fmode`](./fmode.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__p\__fmode|stdlib.h| +| Routine | Required header | +|---|---| +| **`__p__fmode`** | `` | diff --git a/docs/c-runtime-library/parameter-validation.md b/docs/c-runtime-library/parameter-validation.md index 6e1ee99025..a2d188ec7e 100644 --- a/docs/c-runtime-library/parameter-validation.md +++ b/docs/c-runtime-library/parameter-validation.md @@ -6,23 +6,23 @@ ms.topic: "conceptual" helpviewer_keywords: ["parameters, validation"] ms.assetid: 019dd5f0-dc61-4d2e-b4e9-b66409ddf1f2 --- -# Parameter Validation +# Parameter validation -Most of the security-enhanced CRT functions, and many that aren't, validate their parameters for things like checking pointers for **NULL**, that integers fall into a valid range, or that enumeration values are valid. If an invalid parameter is found, the invalid parameter handler is called. +Most of the security-enhanced CRT functions, and many that aren't, validate their parameters for things like checking pointers for `NULL`, that integers fall into a valid range, or that enumeration values are valid. If an invalid parameter is found, the invalid parameter handler is called. -## Invalid Parameter Handler Routine +## Invalid parameter handler routine -When a C Runtime Library function detects an invalid parameter, it captures some information about the error, and then calls a macro that wraps an invalid parameter handler dispatch function. Which will be one of [_invalid_parameter](../c-runtime-library/reference/invalid-parameter-functions.md), [_invalid_parameter_noinfo](../c-runtime-library/reference/invalid-parameter-functions.md), or [_invalid_parameter_noinfo_noreturn](../c-runtime-library/reference/invalid-parameter-functions.md). Which dispatch function is called depends on whether your code is, respectively, a debug build, a retail build, or the error isn't considered recoverable. +When a C Runtime Library function detects an invalid parameter, it captures some information about the error, and then calls a macro that wraps an invalid parameter handler dispatch function. Which will be one of [`_invalid_parameter`](./reference/invalid-parameter-functions.md), [`_invalid_parameter_noinfo`](./reference/invalid-parameter-functions.md), or [`_invalid_parameter_noinfo_noreturn`](./reference/invalid-parameter-functions.md). Which dispatch function is called depends on whether your code is, respectively, a debug build, a retail build, or the error isn't considered recoverable. -In debug builds, the invalid parameter macro usually raises a failed assertion and a debugger breakpoint before the dispatch function is called. When the code is executed, the assertion may be reported to the user in a dialog box that has "Abort", "Retry", and "Continue" or similar choices depending on the operating system and runtime library version. These options allow the user to immediately terminate the program, to attach a debugger, or to let the existing code continue to run which calls the dispatch function. +In debug builds, the invalid parameter macro usually raises a failed assertion and a debugger breakpoint before the dispatch function is called. When the code runs, the assertion may be reported to the user in a dialog box that has "Abort", "Retry", and "Continue" or similar choices that depend on the operating system and CRT version. These options allow the user to immediately terminate the program, to attach a debugger, or to let the existing code continue to run which calls the dispatch function. The invalid parameter handler dispatch function calls the currently assigned invalid parameter handler. By default, the invalid parameter calls `_invoke_watson`, which causes the application to close and generate a mini-dump. If enabled by the operating system, a dialog box asks the user if they want to send the crash dump to Microsoft for analysis. -You can change this behavior by using the functions [_set_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) or [_set_thread_local_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) to set the invalid parameter handler to your own function. If the function you specify does not terminate the application, control is returned to the function that received the invalid parameters. In the CRT, these functions will normally stop function execution, set `errno` to an error code, and return an error code. In many cases, the `errno` value and the return value are both `EINVAL`, to indicate an invalid parameter. In some cases, a more specific error code is returned, such as `EBADF` for a bad file pointer passed in as a parameter. +You can change this behavior by using the functions [`_set_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) or [`_set_thread_local_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) to set the invalid parameter handler to your own function. If the function you specify doesn't terminate the application, control is returned to the function that received the invalid parameters. In the CRT, these functions will normally stop function execution, set `errno` to an error code, and return an error code. In many cases, the `errno` value and the return value are both `EINVAL`, to indicate an invalid parameter. In some cases, a more specific error code is returned, such as `EBADF` for a bad file pointer passed in as a parameter. -For more information on `errno`, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](./errno-doserrno-sys-errlist-and-sys-nerr.md). ## See also -[Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md)\ -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Security features in the CRT](./security-features-in-the-crt.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/path-field-limits.md b/docs/c-runtime-library/path-field-limits.md index 75144b8a9e..1890385a5d 100644 --- a/docs/c-runtime-library/path-field-limits.md +++ b/docs/c-runtime-library/path-field-limits.md @@ -2,11 +2,11 @@ description: "Learn more about: Path Field Limits" title: "Path Field Limits" ms.date: "11/04/2016" -f1_keywords: ["_MAX_EXT", "_MAX_DIR", "_MAX_PATH", "_MAX_FNAME", "_MAX_DRIVE"] +f1_keywords: ["_MAX_EXT", "_MAX_DIR", "_MAX_PATH", "_MAX_FNAME", "_MAX_DRIVE", "STDLIB/_MAX_EXT", "STDLIB/_MAX_DIR", "STDLIB/_MAX_PATH", "STDLIB/_MAX_FNAME", "STDLIB/_MAX_DRIVE"] helpviewer_keywords: ["path field constants", "MAX_FNAME constant", "_MAX_DIR constant", "_MAX_DRIVE constant", "paths, maximum limit", "_MAX_PATH constant", "MAX_DRIVE constant", "_MAX_FNAME constant", "_MAX_EXT constant", "MAX_DIR constant", "MAX_EXT constant"] ms.assetid: 2b5d0e43-1347-45b4-8397-24a8a45c444e --- -# Path Field Limits +# Path field limits ## Syntax @@ -18,17 +18,17 @@ ms.assetid: 2b5d0e43-1347-45b4-8397-24a8a45c444e These constants define the maximum length for the path and for the individual fields within the path. -|Constant|Meaning| -|--------------|-------------| -|`_MAX_DIR`|Maximum length of directory component| -|`_MAX_DRIVE`|Maximum length of drive component| -|`_MAX_EXT`|Maximum length of extension component| -|`_MAX_FNAME`|Maximum length of filename component| -|`_MAX_PATH`|Maximum length of full path| +| Constant | Meaning | +|---|---| +| `_MAX_DIR` | Maximum length of directory component | +| `_MAX_DRIVE` | Maximum length of drive component | +| `_MAX_EXT` | Maximum length of extension component | +| `_MAX_FNAME` | Maximum length of filename component | +| `_MAX_PATH` | Maximum length of full path | > [!NOTE] > The C Runtime supports path lengths up to 32768 characters in length, but it is up to the operating system, specifically the file system, to support these longer paths. The sum of the fields should not exceed `_MAX_PATH` for full backwards compatibility with FAT32 file systems. The Windows NTFS file system supports paths up to 32768 characters in length, but only when using the Unicode APIs. When using long path names, prefix the path with the characters \\\\?\ and use the Unicode versions of the C Runtime functions. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/pctype-func.md b/docs/c-runtime-library/pctype-func.md index 29d5695873..e3918dc32f 100644 --- a/docs/c-runtime-library/pctype-func.md +++ b/docs/c-runtime-library/pctype-func.md @@ -3,14 +3,14 @@ description: "Learn more about: __pctype_func" title: "__pctype_func" ms.date: "1/14/2021" api_name: ["__pctype_func", "_o___pctype_func"] -api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__pctype_func"] +f1_keywords: ["CORECRT_WCTYPE/__pctype_func", "__pctype_func"] helpviewer_keywords: ["__pctype_func"] ms.assetid: d52b8add-d07d-4516-a22f-e836cde0c57f --- -# __pctype_func +# `__pctype_func` Retrieves a pointer to an array of character classification information. @@ -21,22 +21,22 @@ const unsigned short *__pctype_func( ) ``` -## Return Value +## Return value A pointer to an array of character classification information. ## Remarks -The information in the character classification table is for internal use only, and is used by various functions that classify characters of type **`char`**. For more information, see the `Remarks` section of [_pctype, _pwctype, _wctype, _mbctype, _mbcasemap](../c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md). +The information in the character classification table is for internal use only, and is used by various functions that classify characters of type **`char`**. For more information, see the `Remarks` section of [`_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap`](./pctype-pwctype-wctype-mbctype-mbcasemap.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__pctype_func|ctype.h| +| Routine | Required header | +|---|---| +| **`__pctype_func`** | `` | ## See also -[_pctype, _pwctype, _wctype, _mbctype, _mbcasemap](../c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md) +[`_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) diff --git a/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md b/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md index 069c9d6b64..9359692fd9 100644 --- a/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md +++ b/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md @@ -6,17 +6,17 @@ api_name: ["_pctype", "_pwctype", "_wctype", "_mbctype", "_mbcasemap"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["pwctype", "pctype", "mbctype", "mbcasemap", "_mbcasemap", "_mbctype", "_pctype", "_wctype", "_pcwtype"] -helpviewer_keywords: ["_wctype function", "_pwctype function", "_pctype function", "_mbctype function", "wctype function", "pwctype function", "pctype function", "mbcasemap function", "mbctype function", "_mbcasemap function"] +f1_keywords: ["_pctype", "CORECRT_WCTYPE/_pctype", "_pwctype", "CORECRT_WCTYPE/_pcwtype", "_mbctype", "MBCTYPE/_mbctype", "_mbcasemap", "MBCTYPE/_mbcasemap", "_wctype"] +helpviewer_keywords: ["_pctype global variable", "_pwctype global variable", "_wctype global variable", "_mbctype global variable", "_mbcasemap global variable"] ms.assetid: 7f5e1107-c43b-4b9b-b387-781e6d2373cb --- -# _pctype, _pwctype, _wctype, _mbctype, _mbcasemap +# `_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap` These global variables contain information used by the character classification functions. They are for internal use only. ## Syntax -``` +```C extern const unsigned short *_pctype; extern const wctype_t *_pwctype; extern const unsigned short _wctype[]; @@ -26,9 +26,9 @@ extern unsigned char _mbcasemap[]; ## Remarks -The information in `_pctype`, `_pwctype`, and `_wctype` is used internally by [isupper, _isupper_l, iswupper, _iswupper_l](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md), [islower, iswlower, _islower_l, _iswlower_l](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md), [isdigit, iswdigit, _isdigit_l, _iswdigit_l](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md), [isspace, iswspace, _isspace_l, _iswspace_l](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md), [isalnum, iswalnum, _isalnum_l, _iswalnum_l](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [ispunct, iswpunct, _ispunct_l, _iswpunct_l](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [isgraph, iswgraph, _isgraph_l, _iswgraph_l](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md), [toupper, _toupper, towupper, _toupper_l, _towupper_l](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [tolower, _tolower, towlower, _tolower_l, and _towlower_l](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md) functions. These functions should be used instead of accessing these global variables. +The information in `_pctype`, `_pwctype`, and `_wctype` is used internally by [`isupper`, `_isupper_l`, `iswupper`, `_iswupper_l`](./reference/isupper-isupper-l-iswupper-iswupper-l.md), [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md), [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md), [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md), [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md), [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`tolower`, `_tolower`, `towlower`, `_tolower_l`, and `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md) functions. These functions should be used instead of accessing these global variables. -The information in `_mbctype` and `_mbcasemap` is used internally by [_ismbbkalnum, _ismbbkalnum_l](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md), [_ismbbkana, _ismbbkana_l](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md), [_ismbbkpunct, _ismbbkpunct_l](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md), [_ismbbkprint, _ismbbkprint_l](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md), [_ismbbalpha](reference/ismbbalpha-ismbbalpha-l.md), [_ismbbpunct, _ismbbpunct_l](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md), [_ismbbalnum, _ismbbalnum_l](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md), [_ismbbprint, _ismbbprint_l](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md), [_ismbbgraph, _ismbbgraph_l](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md), [_ismbblead, _ismbblead_l](../c-runtime-library/reference/ismbblead-ismbblead-l.md), [_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md), [_ismbslead, _ismbstrail, _ismbslead_l, _ismbstrail_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md), [_ismbslead, _ismbstrail, _ismbslead_l, and _ismbstrail_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md). Use these functions instead of accessing the global variables. +The information in `_mbctype` and `_mbcasemap` is used internally by [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md), [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md), [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md), [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md), [`_ismbbalpha`](reference/ismbbalpha-ismbbalpha-l.md), [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md), [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md), [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md), [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md), [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md), [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md), [`_ismbslead`, `_ismbstrail`, `_ismbslead_l`, `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md), [`_ismbslead`, `_ismbstrail`, `_ismbslead_l`, and `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md). Use these functions instead of accessing the global variables. ## Requirements @@ -36,5 +36,5 @@ Not for public use. ## See also -[is, isw Routines](../c-runtime-library/is-isw-routines.md)
-[__pctype_func](../c-runtime-library/pctype-func.md) +[`is`, `isw` routines](./is-isw-routines.md)\ +[`__pctype_func`](./pctype-func.md) diff --git a/docs/c-runtime-library/pgmptr-wpgmptr.md b/docs/c-runtime-library/pgmptr-wpgmptr.md index 1118e345ba..e5779e9075 100644 --- a/docs/c-runtime-library/pgmptr-wpgmptr.md +++ b/docs/c-runtime-library/pgmptr-wpgmptr.md @@ -2,48 +2,48 @@ description: "Learn more about: _pgmptr, _wpgmptr" title: "_pgmptr, _wpgmptr" ms.date: "11/04/2016" -f1_keywords: ["pgmptr", "_pgmptr", "wpgmptr", "_wpgmptr"] -helpviewer_keywords: ["wpgmptr function", "_wpgmptr function", "_pgmptr function", "pgmptr function"] +f1_keywords: ["_pgmptr", "STDLIB/_pgmptr", "_wpgmptr", "STDLIB/_wpgmptr"] +helpviewer_keywords: ["_pgmptr global variable", "_wpgmptr global variable"] ms.assetid: 4d44b515-0eff-4136-8bc4-684195f218f5 --- -# _pgmptr, _wpgmptr +# `_pgmptr`, `_wpgmptr` -The path of the executable file. Deprecated; use [_get_pgmptr](../c-runtime-library/reference/get-pgmptr.md) and [_get_wpgmptr](../c-runtime-library/reference/get-wpgmptr.md). +The path of the executable file. Deprecated; use [`_get_pgmptr`](./reference/get-pgmptr.md) and [`_get_wpgmptr`](./reference/get-wpgmptr.md). ## Syntax -``` +```C extern char *_pgmptr; extern wchar_t *_wpgmptr; ``` ## Remarks -When a program is run from the command interpreter (Cmd.exe), `_pgmptr` is automatically initialized to the full path of the executable file. For example, if Hello.exe is in C:\BIN and C:\BIN is in the path, `_pgmptr` is set to C:\BIN\Hello.exe when you execute: +When a program is run from the command interpreter (Cmd.exe), **`_pgmptr`** is automatically initialized to the full path of the executable file. For example, if Hello.exe is in C:\BIN and C:\BIN is in the path, **`_pgmptr`** is set to *`C:\BIN\Hello.exe`* when you execute: -``` +```cmd C> hello ``` -When a program is not run from the command line, `_pgmptr` might be initialized to the program name (the file's base name without the file name extension) or to a file name, relative path, or full path. +When a program isn't run from the command line, **`_pgmptr`** might be initialized to the program name (the file's base name without the file name extension) or to a file name, relative path, or full path. -`_wpgmptr` is the wide-character counterpart of `_pgmptr` for use with programs that use `wmain`. +**`_wpgmptr`** is the wide-character counterpart of **`_pgmptr`** for use with programs that use `wmain`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_tpgmptr`|`_pgmptr`|`_pgmptr`|`_wpgmptr`| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tpgmptr` | **`_pgmptr`** | **`_pgmptr`** | **`_wpgmptr`** | ## Requirements -|Variable|Required header| -|--------------|---------------------| -|`_pgmptr`, `_wpgmptr`|\| +| Variable | Required header | +|---|---| +| **`_pgmptr`**, **`_wpgmptr`** | \ | ## Example -The following program demonstrates the use of `_pgmptr`. +The following program demonstrates the use of **`_pgmptr`**. ```c // crt_pgmptr.c @@ -60,8 +60,8 @@ int main( void ) } ``` -You could use `_wpgmptr` by changing `%Fs` to `%S` and `main` to `wmain`. +You could use **`_wpgmptr`** by changing `%Fs` to `%S` and `main` to `wmain`. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](./global-variables.md) diff --git a/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md b/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md index 116c38fd93..9aac11ab8d 100644 --- a/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md +++ b/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md @@ -1,16 +1,16 @@ --- title: "Potential Errors Passing CRT Objects Across DLL Boundaries" description: "An overview of potential problems you may come across when passing Microsoft C runtime objects across a dynamic link library (DLL) boundary." -ms.date: "11/04/2016" +ms.date: 06/29/2022 ms.topic: "conceptual" helpviewer_keywords: ["DLL conflicts [C++]"] ms.assetid: c217ffd2-5d9a-4678-a1df-62a637a96460 --- -# Potential Errors Passing CRT Objects Across DLL Boundaries +# Potential errors passing CRT objects across DLL boundaries -When you pass C Run-time (CRT) objects such as file handles, locales, and environment variables into or out of a DLL via function calls across the DLL boundary, unexpected behavior can occur if the DLL, or any files that call into the DLL, use different copies of the CRT libraries. +Your code may have errors when you pass C Runtime (CRT) objects such as file handles, locales, and environment variables into or out of a DLL. Function calls across the DLL boundary can cause unexpected behavior if the DLL and any files that call into the DLL use different copies of the CRT libraries. -A related problem can occur when you allocate memory (either explicitly with `new` or `malloc`, or implicitly with `strdup`, `strstreambuf::str`, and so on) and then pass a pointer across a DLL boundary where it is freed. This can cause a memory access violation, or heap corruption, if the DLL and its consumers are using different copies of the CRT libraries. +A related problem can occur when you allocate memory (either explicitly with `new` or `malloc`, or implicitly with `strdup`, `strstreambuf::str`, and so on) and then pass a pointer across a DLL boundary where it's freed. Such pointers can cause a memory access violation, or heap corruption, if the DLL and its consumers are using different copies of the CRT libraries. Another symptom of this problem is an error in the output window during debugging such as `HEAP[]: Invalid Address specified to RtlValidateHeap(#,#)` @@ -18,13 +18,13 @@ Another symptom of this problem is an error in the output window during debuggin Each copy of the CRT library has a separate and distinct state, kept in thread local storage by your app or DLL. -CRT objects such as file handles, environment variables, and locales are only valid for the copy of the CRT in the app or DLL where these objects were allocated or set. When a DLL and its clients use different copies of the CRT library, you can't pass these CRT objects across the DLL boundary and expect them to be used correctly on the other side. This is true of CRT versions before the Universal CRT in Visual Studio 2015 and later. +CRT objects such as file handles, environment variables, and locales are only valid for the copy of the CRT in the app or DLL where these objects were allocated or set. When a DLL and its clients use different copies of the CRT library, you can't expect these CRT objects to be used correctly when passed across the DLL boundary. -There was a version-specific CRT library for every version of Visual Studio built with Visual Studio 2013 or earlier. Internal implementation details of the CRT, such as data structures and naming conventions, were different in each version. Dynamically linking code that was compiled for one version of the CRT to a different version of the CRT DLL has never been supported. Occasionally it would work, but because of luck rather than design. +It's especially true of CRT versions before the Universal CRT in Visual Studio 2015 and later. There was a version-specific CRT library for every version of Visual Studio built with Visual Studio 2013 or earlier. Internal implementation details of the CRT, such as data structures and naming conventions, were different in each version. Dynamically linking code that was compiled for one version of the CRT to a different version of the CRT DLL has never been supported. Occasionally it would work, but because of luck rather than design. -Because each copy of the CRT library has its own heap manager, allocating memory in one CRT library and passing the pointer across a DLL boundary to be freed by a different copy of the CRT library, can cause heap corruption. If you design your DLL so that it passes CRT objects across the DLL boundary, or allocates memory and expects it to be freed outside the DLL, clients of the DLL must use the same copy of the CRT library as the DLL. +Each copy of the CRT library has its own heap manager. It can cause heap corruption if you allocate memory in one CRT library and pass the pointer across a DLL boundary to be freed by a different copy of the CRT library. If your DLL passes CRT objects across the DLL boundary, or allocates memory that's freed outside the DLL, clients of the DLL must use the same copy of the CRT library as the DLL. -The DLL and its clients normally use the same copy of the CRT library only if both are linked at load time to the same version of the CRT DLL. Because the DLL version of the Universal CRT library used by Visual Studio 2015 and later is now a centrally deployed Windows component (ucrtbase.dll), it's the same for apps built with Visual Studio 2015 and later versions. However, even when the CRT code is identical, you can't give memory allocated in one heap to a component that uses a different heap. +The DLL and its clients normally use the same copy of the CRT library only if both are linked at load time to the same version of the CRT DLL. Because the DLL version of the Universal CRT library used by Visual Studio 2015 and later is now a centrally deployed Windows component (`ucrtbase.dll`), it's the same for apps built with Visual Studio 2015 and later versions. However, even when the CRT code is identical, you can't give memory allocated in one heap to a component that uses a different heap. ## Example: Pass file handle across DLL boundary @@ -34,7 +34,9 @@ This example passes a file handle across a DLL boundary. The DLL and .exe files are built with `/MD`, so that they share a single copy of the CRT. -If you rebuild with `/MT` so that they use separate copies of the CRT, running the resulting **test1Main.exe** results in an access violation. +If you rebuild with `/MT` so that they use separate copies of the CRT, running the resulting `test1Main.exe` results in an access violation. + +DLL source file `test1Dll.cpp`: ```cpp // test1Dll.cpp @@ -48,6 +50,8 @@ __declspec(dllexport) void writeFile(FILE *stream) } ``` +Executable source file `test1Main.cpp`: + ```cpp // test1Main.cpp // compile with: cl /EHsc /W4 /MD test1Main.cpp test1Dll.lib @@ -74,6 +78,8 @@ this is a string This example passes environment variables across a DLL boundary. +DLL source file `test2Dll.cpp`: + ```cpp // test2Dll.cpp // compile with: cl /EHsc /W4 /MT /LD test2Dll.cpp @@ -96,6 +102,8 @@ __declspec(dllexport) void readEnv() } ``` +Executable source file `test2Main.cpp`: + ```cpp // test2Main.cpp // compile with: cl /EHsc /W4 /MT test2Main.cpp test2dll.lib @@ -115,12 +123,12 @@ int main( void ) MYLIB has not been set. ``` -If both the DLL and .exe file are built with `/MD` so that only one copy of the CRT is used, the program runs successfully and produces the following output: +If you build both the DLL and EXE files by using `/MD`, so that only one copy of the CRT is used, the program runs successfully and produces the following output: -``` +```Output New MYLIB variable is: c:\mylib;c:\yourlib ``` ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/printf-p-positional-parameters.md b/docs/c-runtime-library/printf-p-positional-parameters.md index 7f64e9d3e9..4237a034ea 100644 --- a/docs/c-runtime-library/printf-p-positional-parameters.md +++ b/docs/c-runtime-library/printf-p-positional-parameters.md @@ -2,31 +2,28 @@ description: "Learn more about: printf_p Positional Parameters" title: "printf_p Positional Parameters" ms.date: "11/04/2016" -api_location: ["msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr80.dll", "msvcr100.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] helpviewer_keywords: ["_printf_p function, positional parameters", "printf_p function, positional parameters"] ms.assetid: beb4fd85-a7aa-4665-9085-2c907a5b9ab0 --- -# printf_p Positional Parameters +# `printf_p` positional parameters -Positional parameters provide the ability to specify by number which of the arguments is to be substituted into a field in a format string. The following positional parameter `printf` functions are available: +Positional parameters let you specify by number the argument to substitute into a field in a format string. The following positional parameter `printf` functions are available: | Non-positional printf functions | Positional parameter equivalents | |---|---| -|[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](../c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)| -|[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](../c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)| -|[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|[_cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l](../c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)| -|[fprintf, _fprintf_l, fwprintf, _fwprintf_l](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)| -|[vprintf, _vprintf_l, vwprintf, _vwprintf_l](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)|[_vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l](../c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md)| -|[vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)|[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](../c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)| -|[vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, \__vswprintf_l](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)|[_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l](../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)| +| [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md) | [`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](./reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) | +| [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | [`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](./reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) | +| [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | [`_cprintf_p`, `_cprintf_p_l`, `_cwprintf_p`, `_cwprintf_p_l`](./reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md) | +| [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | [`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](./reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md) | +| [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) | [`_vprintf_p`, `_vprintf_p_l`, `_vwprintf_p`, `_vwprintf_p_l`](./reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md) | +| [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) | [`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](./reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md) | +| [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) | [`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](./reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md) | ## How to specify positional parameters ### Parameter indexing -By default, if no positional formatting is present, the positional functions behave identically to the non-positional ones. You specify the positional parameter to format by using `%n$` at the beginning of the format specifier, where `n` is the position of the parameter to format in the parameter list. The parameter position starts at 1 for the first argument after the format string. The remainder of the format specifier follows the same rules as the `printf` format specifier. For more information about format specfiers, see [Format Specification Syntax: printf and wprintf Functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +By default, if no positional formatting is present, the positional functions behave identically to the non-positional ones. You specify the positional parameter to format by using `%n$` at the beginning of the format specifier, where `n` is the position of the parameter to format in the parameter list. The parameter position starts at 1 for the first argument after the format string. The remainder of the format specifier follows the same rules as the `printf` format specifier. For more information about format specifiers, see [Format specification syntax: `printf` and `wprintf` functions](./format-specification-syntax-printf-and-wprintf-functions.md). Here's an example of positional formatting: @@ -34,21 +31,21 @@ Here's an example of positional formatting: _printf_p("%1$s %2$s", "November", "10"); ``` -This prints: +This example prints: -``` +```Output November 10 ``` -The order of the numbers used doesn't need to match the order of the arguments. For example, this is a valid format string: +The order of the numbers used doesn't need to match the order of the arguments. For example, here's a valid format string: ```C _printf_p("%2$s %1$s", "November", "10"); ``` -This prints: +This example prints: -``` +```Output 10 November ``` @@ -58,9 +55,9 @@ Unlike traditional format strings, positional parameters may be used more than o _printf_p("%1$d times %1$d is %2$d", 10, 100); ``` -This prints: +This example prints: -``` +```Output 10 times 10 is 100 ``` @@ -136,4 +133,4 @@ ghi abc def ## See also -[Format Specification Syntax: printf and wprintf Functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) +[Format specification syntax: `printf` and `wprintf` functions](./format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/process-and-environment-control.md b/docs/c-runtime-library/process-and-environment-control.md index 13b09b0810..06d36fd705 100644 --- a/docs/c-runtime-library/process-and-environment-control.md +++ b/docs/c-runtime-library/process-and-environment-control.md @@ -4,76 +4,75 @@ title: "Process and Environment Control" ms.date: "11/04/2016" f1_keywords: ["c.programs"] helpviewer_keywords: ["processes, stopping", "processes, administrative tasks", "parent process", "processes, starting", "environment control routines", "process control routines"] -ms.assetid: 7fde74c3-c2a6-4d15-84b8-092160d60c3e --- -# Process and Environment Control +# Process and environment control Use the process-control routines to start, stop, and manage processes from within a program. Use the environment-control routines to get and change information about the operating-system environment. -## Process and Environment Control Functions +## Process and environment control functions -|Routine|Use| -|-------------|---------| -|[abort](../c-runtime-library/reference/abort.md)|Abort process without flushing buffers or calling functions registered by **atexit** and **_onexit**| -|[assert](../c-runtime-library/reference/assert-macro-assert-wassert.md)|Test for logic error| -|[_ASSERT, _ASSERTE](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) macros|Similar to **assert**, but only available in the debug versions of the run-time libraries| -|[atexit](../c-runtime-library/reference/atexit.md)|Schedule routines for execution at program termination| -|[_beginthread, _beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md)|Create a new thread on a Windows operating system process| -|[_cexit](../c-runtime-library/reference/cexit-c-exit.md)|Perform **exit** termination procedures (such as flushing buffers), then return control to calling program without terminating process| -|[_c_exit](../c-runtime-library/reference/cexit-c-exit.md)|Perform **_exit** termination procedures, then return control to calling program without terminating process| -|[_cwait](../c-runtime-library/reference/cwait.md)|Wait until another process terminates| -|[_endthread, _endthreadex](../c-runtime-library/reference/endthread-endthreadex.md)|Terminate a Windows operating system thread| -|[_execl, _wexecl](../c-runtime-library/reference/execl-wexecl.md)|Execute new process with argument list| -|[_execle, _wexecle](../c-runtime-library/reference/execle-wexecle.md)|Execute new process with argument list and given environment| -|[_execlp, _wexeclp](../c-runtime-library/reference/execlp-wexeclp.md)|Execute new process using **PATH** variable and argument list| -|[_execlpe, _wexeclpe](../c-runtime-library/reference/execlpe-wexeclpe.md)|Execute new process using **PATH** variable, given environment, and argument list| -|[_execv, _wexecv](../c-runtime-library/reference/execv-wexecv.md)|Execute new process with argument array| -|[_execve, _wexecve](../c-runtime-library/reference/execve-wexecve.md)|Execute new process with argument array and given environment| -|[_execvp, _wexecvp](../c-runtime-library/reference/execvp-wexecvp.md)|Execute new process using **PATH** variable and argument array| -|[_execvpe, _wexecvpe](../c-runtime-library/reference/execvpe-wexecvpe.md)|Execute new process using **PATH** variable, given environment, and argument array| -|[exit](../c-runtime-library/reference/exit-exit-exit.md)|Call functions registered by **atexit** and **_onexit**, flush all buffers, close all open files, and terminate process| -|[_exit](../c-runtime-library/reference/exit-exit-exit.md)|Terminate process immediately without calling **atexit** or **_onexit** or flushing buffers| -|[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md), [getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)|Get value of environment variable| -|[_getpid](../c-runtime-library/reference/getpid.md)|Get process ID number| -|[longjmp](../c-runtime-library/reference/longjmp.md)|Restore saved stack environment; use it to execute a nonlocal **`goto`**| -|[_onexit](../c-runtime-library/reference/onexit-onexit-m.md)|Schedule routines for execution at program termination; use for compatibility with Microsoft C/C++ version 7.0 and earlier| -|[_pclose](../c-runtime-library/reference/pclose.md)|Wait for new command processor and close stream on associated pipe| -|[perror, _wperror](../c-runtime-library/reference/perror-wperror.md)|Print error message| -|[_pipe](../c-runtime-library/reference/pipe.md)|Create pipe for reading and writing| -|[_popen, _wpopen](../c-runtime-library/reference/popen-wpopen.md)|Create pipe and execute command| -|[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md), [_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md)|Add or change value of environment variable| -|[raise](../c-runtime-library/reference/raise.md)|Send signal to calling process| -|[setjmp](../c-runtime-library/reference/setjmp.md)|Save stack environment; use to execute non local **`goto`**| -|[signal](../c-runtime-library/reference/signal.md)|Handle interrupt signal| -|[_spawnl, _wspawnl](../c-runtime-library/reference/spawnl-wspawnl.md)|Create and execute new process with specified argument list| -|[_spawnle, _wspawnle](../c-runtime-library/reference/spawnle-wspawnle.md)|Create and execute new process with specified argument list and environment| -|[_spawnlp, _wspawnlp](../c-runtime-library/reference/spawnlp-wspawnlp.md)|Create and execute new process using **PATH** variable and specified argument list| -|[_spawnlpe, _wspawnlpe](../c-runtime-library/reference/spawnlpe-wspawnlpe.md)|Create and execute new process using **PATH** variable, specified environment, and argument list| -|[_spawnv, _wspawnv](../c-runtime-library/reference/spawnv-wspawnv.md)|Create and execute new process with specified argument array| -|[_spawnve, _wspawnve](../c-runtime-library/reference/spawnve-wspawnve.md)|Create and execute new process with specified environment and argument array| -|[_spawnvp, _wspawnvp](../c-runtime-library/reference/spawnvp-wspawnvp.md)|Create and execute new process using **PATH** variable and specified argument array| -|[_spawnvpe, _wspawnvpe](../c-runtime-library/reference/spawnvpe-wspawnvpe.md)|Create and execute new process using **PATH** variable, specified environment, and argument array| -|[system, _wsystem](../c-runtime-library/reference/system-wsystem.md)|Execute operating-system command| +| Routine | Use | +|---|---| +| [`abort`](./reference/abort.md) | Abort process without flushing buffers or calling functions registered by **`atexit`** and **`_onexit`** | +| [`assert`](./reference/assert-macro-assert-wassert.md) | Test for logic error | +| [`_ASSERT`, `_ASSERTE`](./reference/assert-asserte-assert-expr-macros.md) macros | Similar to **`assert`**, but only available in the debug versions of the run-time libraries | +| [`atexit`](./reference/atexit.md) | Schedule routines for execution at program termination | +| [`_beginthread`, `_beginthreadex`](./reference/beginthread-beginthreadex.md) | Create a new thread on a Windows operating system process | +| [`_cexit`](./reference/cexit-c-exit.md) | Perform **`exit`** termination procedures (such as flushing buffers), then return control to calling program without terminating process | +| [`_c_exit`](./reference/cexit-c-exit.md) | Perform **`_exit`** termination procedures, then return control to calling program without terminating process | +| [`_cwait`](./reference/cwait.md) | Wait until another process terminates | +| [`_endthread`, `_endthreadex`](./reference/endthread-endthreadex.md) | Terminate a Windows operating system thread | +| [`_execl`, `_wexecl`](./reference/execl-wexecl.md) | Execute new process with argument list | +| [`_execle`, `_wexecle`](./reference/execle-wexecle.md) | Execute new process with argument list and given environment | +| [`_execlp`, `_wexeclp`](./reference/execlp-wexeclp.md) | Execute new process using `PATH` variable and argument list | +| [`_execlpe`, `_wexeclpe`](./reference/execlpe-wexeclpe.md) | Execute new process using `PATH` variable, given environment, and argument list | +| [`_execv`, `_wexecv`](./reference/execv-wexecv.md) | Execute new process with argument array | +| [`_execve`, `_wexecve`](./reference/execve-wexecve.md) | Execute new process with argument array and given environment | +| [`_execvp`, `_wexecvp`](./reference/execvp-wexecvp.md) | Execute new process using `PATH` variable and argument array | +| [`_execvpe`, `_wexecvpe`](./reference/execvpe-wexecvpe.md) | Execute new process using `PATH` variable, given environment, and argument array | +| [`exit`](./reference/exit-exit-exit.md) | Call functions registered by **`atexit`** and **`_onexit`**, flush all buffers, close all open files, and terminate process | +| [`_exit`](./reference/exit-exit-exit.md) | Terminate process immediately without calling **`atexit`** or **`_onexit`** or flushing buffers | +| [`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md), [`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md) | Get value of environment variable | +| [`_getpid`](./reference/getpid.md) | Get process ID number | +| [`longjmp`](./reference/longjmp.md) | Restore saved stack environment; use it to execute a nonlocal **`goto`** | +| [`_onexit`](./reference/onexit-onexit-m.md) | Schedule routines for execution at program termination; use for compatibility with Microsoft C/C++ version 7.0 and earlier | +| [`_pclose`](./reference/pclose.md) | Wait for new command processor and close stream on associated pipe | +| [`perror`, `_wperror`](./reference/perror-wperror.md) | Print error message | +| [`_pipe`](./reference/pipe.md) | Create pipe for reading and writing | +| [`_popen`, `_wpopen`](./reference/popen-wpopen.md) | Create pipe and execute command | +| [`_putenv`, `_wputenv`](./reference/putenv-wputenv.md), [`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md) | Add or change value of environment variable | +| [`raise`](./reference/raise.md) | Send signal to calling process | +| [`setjmp`](./reference/setjmp.md) | Save stack environment; use to execute non local **`goto`** | +| [`signal`](./reference/signal.md) | Handle interrupt signal | +| [`_spawnl`, `_wspawnl`](./reference/spawnl-wspawnl.md) | Create and execute new process with specified argument list | +| [`_spawnle`, `_wspawnle`](./reference/spawnle-wspawnle.md) | Create and execute new process with specified argument list and environment | +| [`_spawnlp`, `_wspawnlp`](./reference/spawnlp-wspawnlp.md) | Create and execute new process using `PATH` variable and specified argument list | +| [`_spawnlpe`, `_wspawnlpe`](./reference/spawnlpe-wspawnlpe.md) | Create and execute new process using `PATH` variable, specified environment, and argument list | +| [`_spawnv`, `_wspawnv`](./reference/spawnv-wspawnv.md) | Create and execute new process with specified argument array | +| [`_spawnve`, `_wspawnve`](./reference/spawnve-wspawnve.md) | Create and execute new process with specified environment and argument array | +| [`_spawnvp`, `_wspawnvp`](./reference/spawnvp-wspawnvp.md) | Create and execute new process using `PATH` variable and specified argument array | +| [`_spawnvpe`, `_wspawnvpe`](./reference/spawnvpe-wspawnvpe.md) | Create and execute new process using `PATH` variable, specified environment, and argument array | +| [`system`, `_wsystem`](./reference/system-wsystem.md) | Execute operating-system command | -In the Windows operating system, the spawned process is equivalent to the spawning process. Any process can use **_cwait** to wait for any other process for which the process ID is known. +In the Windows operating system, the spawned process is equivalent to the spawning process. Any process can use **`_cwait`** to wait for any other process for which the process ID is known. -The difference between the **_exec** and **_spawn** families is that a **_spawn** function can return control from the new process to the calling process. In a **_spawn** function, both the calling process and the new process are present in memory unless **_P_OVERLAY** is specified. In an **_exec** function, the new process overlays the calling process, so control cannot return to the calling process unless an error occurs in the attempt to start execution of the new process. +The difference between the **`_exec`** and **`_spawn`** families is that a **`_spawn`** function can return control from the new process to the calling process. In a **`_spawn`** function, both the calling process and the new process are present in memory unless `_P_OVERLAY` is specified. In an **`_exec`** function, the new process overlays the calling process, so control can't return to the calling process unless an error occurs in the attempt to start execution of the new process. -The differences among the functions in the **_exec** family, as well as among those in the **_spawn** family, involve the method of locating the file to be executed as the new process, the form in which arguments are passed to the new process, and the method of setting the environment, as shown in the following table. Use a function that passes an argument list when the number of arguments is constant or is known at compile time. Use a function that passes a pointer to an array containing the arguments when the number of arguments is to be determined at run time. The information in the following table also applies to the wide-character counterparts of the **_spawn** and **_exec** functions. +The differences among the functions in the **`_exec`** and **`_spawn`** families involve the method of locating the file to be executed as the new process, the form in which arguments are passed to the new process, and the method of setting the environment, as shown in the following table. Use a function that passes an argument list when the number of arguments is constant or is known at compile time. Use a function that passes a pointer to an array containing the arguments when the number of arguments is to be determined at run time. The information in the following table also applies to the wide-character counterparts of the **`_spawn`** and **`_exec`** functions. -### _spawn and _exec Function Families +### `_spawn` and `_exec` Function Families -|Functions|Use PATH variable to locate file|Argument-passing convention|Environment settings| -|---------------|--------------------------------------|----------------------------------|--------------------------| -|**_execl**, **_spawnl**|No|List|Inherited from calling process| -|**_execle**, **_spawnle**|No|List|Pointer to environment table for new process passed as last argument| -|**_execlp**, **_spawnlp**|Yes|List|Inherited from calling process| -|**_execvpe**, **_spawnvpe**|Yes|Array|Pointer to environment table for new process passed as last argument| -|**_execlpe**, **_spawnlpe**|Yes|List|Pointer to environment table for new process passed as last argument| -|**_execv**, **_spawnv**|No|Array|Inherited from calling process| -|**_execve**, **_spawnve**|No|Array|Pointer to environment table for new process passed as last argument| -|**_execvp**, **_spawnvp**|Yes|Array|Inherited from calling process| +| Functions | Use `PATH` variable to locate file | Argument-passing convention | Environment settings | +|---|---|---|---| +| **`_execl`**, **`_spawnl`** | No | List | Inherited from calling process | +| **`_execle`**, **`_spawnle`** | No | List | Pointer to environment table for new process passed as last argument | +| **`_execlp`**, **`_spawnlp`** | Yes | List | Inherited from calling process | +| **`_execvpe`**, **`_spawnvpe`** | Yes | Array | Pointer to environment table for new process passed as last argument | +| **`_execlpe`**, **`_spawnlpe`** | Yes | List | Pointer to environment table for new process passed as last argument | +| **`_execv`**, **`_spawnv`** | No | Array | Inherited from calling process | +| **`_execve`**, **`_spawnve`** | No | Array | Pointer to environment table for new process passed as last argument | +| **`_execvp`**, **`_spawnvp`** | Yes | Array | Inherited from calling process | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/rand-max.md b/docs/c-runtime-library/rand-max.md index 570899fd72..532c58038c 100644 --- a/docs/c-runtime-library/rand-max.md +++ b/docs/c-runtime-library/rand-max.md @@ -2,15 +2,14 @@ description: "Learn more about: RAND_MAX" title: "RAND_MAX" ms.date: "11/04/2016" -f1_keywords: ["RAND_MAX"] +f1_keywords: ["STDLIB/RAND_MAX", "RAND_MAX"] helpviewer_keywords: ["RAND_MAX constant"] -ms.assetid: a2039697-8908-4911-bd2d-a2bdd19912a0 --- -# RAND_MAX +# `RAND_MAX` ## Syntax -``` +```C #include ``` @@ -20,5 +19,5 @@ The constant `RAND_MAX` is the maximum value that can be returned by the `rand` ## See also -[rand](../c-runtime-library/reference/rand.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`rand`](./reference/rand.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md b/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md index 7017d4a920..1971598d3b 100644 --- a/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md +++ b/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md @@ -7,7 +7,7 @@ f1_keywords: ["c.functions"] helpviewer_keywords: ["functions [CRT], vs. macros", "macros, vs. functions"] ms.assetid: 18a633d6-cf1c-470c-a649-fa7677473e2b --- -# Recommendations for Choosing Between Functions and Macros +# Recommendations for choosing between functions and macros Most Microsoft run-time library routines are compiled or assembled functions, but some routines are implemented as macros. When a header file declares both a function and a macro version of a routine, the macro definition takes precedence, because it always appears after the function declaration. When you invoke a routine that is implemented as both a function and a macro, you can force the compiler to use the function version in two ways: @@ -29,13 +29,13 @@ Most Microsoft run-time library routines are compiled or assembled functions, bu If you need to choose between a function and a macro implementation of a library routine, consider the following trade-offs: -- **Speed versus size** The main benefit of using macros is faster execution time. During preprocessing, a macro is expanded (replaced by its definition) inline each time it is used. A function definition occurs only once regardless of how many times it is called. Macros may increase code size but do not have the overhead associated with function calls. +- **Speed versus size** The main benefit of using macros is faster execution time. During preprocessing, a macro is expanded (replaced by its definition) inline each time it's used. A function definition occurs only once regardless of how many times it's called. Macros may increase code size but don't have the overhead associated with function calls. -- **Function evaluation** A function evaluates to an address; a macro does not. Thus you cannot use a macro name in contexts requiring a pointer. For instance, you can declare a pointer to a function, but not a pointer to a macro. +- **Function evaluation** A function evaluates to an address; a macro doesn't. Thus you can't use a macro name in contexts requiring a pointer. For instance, you can declare a pointer to a function, but not a pointer to a macro. -- **Type-checking** When you declare a function, the compiler can check the argument types. Because you cannot declare a macro, the compiler cannot check macro argument types; although it can check the number of arguments you pass to a macro. +- **Type-checking** When you declare a function, the compiler can check the argument types. Because you can't declare a macro, the compiler can't check macro argument types; although it can check the number of arguments you pass to a macro. ## See also [Type-generic math](tgmath.md)\ -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/reference/abort.md b/docs/c-runtime-library/reference/abort.md index 118b97c887..436a39de91 100644 --- a/docs/c-runtime-library/reference/abort.md +++ b/docs/c-runtime-library/reference/abort.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: abort" title: "abort" -ms.date: "4/2/2020" +description: "Learn more about: abort" +ms.date: 07/07/2022 api_name: ["abort", "_o_abort"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["Abort"] +f1_keywords: ["STDLIB/abort", "abort"] helpviewer_keywords: ["aborting current process", "abort function", "processes, aborting"] --- -# abort +# `abort` Aborts the current process and returns an error code. > [!NOTE] -> Do not use this method to shut down a Microsoft Store app or Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use this method to shut down a Microsoft Store app or Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -22,15 +22,15 @@ Aborts the current process and returns an error code. void abort( void ); ``` -## Return Value +## Return value -**abort** does not return control to the calling process. By default, it checks for an abort signal handler and raises `SIGABRT` if one is set. Then **abort** terminates the current process and returns an exit code to the parent process. +**`abort`** doesn't return control to the calling process. By default, it checks for an abort signal handler and raises `SIGABRT` if one is set. Then **`abort`** terminates the current process and returns an exit code to the parent process. ## Remarks **Microsoft Specific** -By default, when an app is built with the debug runtime library, the **abort** routine displays an error message before `SIGABRT` is raised. For console apps running in console mode, the message is sent to `STDERR`. Windows desktop apps and console apps running in windowed mode display the message in a message box. To suppress the message, use [_set_abort_behavior](set-abort-behavior.md) to clear the `_WRITE_ABORT_MSG` flag. The message displayed depends on the version of the runtime environment used. For applications built by using the most recent versions of Visual C++, the message resembles this: +By default, when an app is built with the debug runtime library, the **`abort`** routine displays an error message before `SIGABRT` is raised. For console apps running in console mode, the message is sent to `STDERR`. Windows desktop apps and console apps running in windowed mode display the message in a message box. To suppress the message, use [`_set_abort_behavior`](set-abort-behavior.md) to clear the `_WRITE_ABORT_MSG` flag. The message displayed depends on the version of the runtime environment used. For applications built by using the most recent versions of Visual C++, the message resembles this one: > R6010 - abort() has been called @@ -38,25 +38,27 @@ In previous versions of the C runtime library, this message was displayed: > This application has requested the Runtime to terminate it in an unusual way. Please contact the application's support team for more information. -When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **abort** continues normal processing. +When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **`abort`** continues normal processing. + +In both retail and debug builds, **`abort`** then checks whether an abort signal handler is set. If a non-default signal handler is set, **`abort`** calls `raise(SIGABRT)`. Use the [`signal`](signal.md) function to associate an abort signal handler function with the `SIGABRT` signal. You can perform custom actions—for example, clean up resources or log information—and terminate the app with your own error code in the handler function. If no custom signal handler is defined, **`abort`** doesn't raise the `SIGABRT` signal. -In both retail and debug builds, **abort** then checks whether an abort signal handler is set. If a non-default signal handler is set, **abort** calls `raise(SIGABRT)`. Use the [signal](signal.md) function to associate an abort signal handler function with the `SIGABRT` signal. You can perform custom actions—for example, clean up resources or log information—and terminate the app with your own error code in the handler function. If no custom signal handler is defined, **abort** does not raise the `SIGABRT` signal. +By default, in non-debug builds of desktop or console apps, **`abort`** then invokes the Windows Error Reporting Service mechanism (formerly known as Dr. Watson) to report failures to Microsoft. This behavior can be enabled or disabled by calling `_set_abort_behavior` and setting or masking the `_CALL_REPORTFAULT` flag. When the flag is set, Windows displays a message box that has text something like "A problem caused the program to stop working correctly." The user can choose to invoke a debugger with a **Debug** button, or choose the **Close program** button to terminate the app with an error code that's defined by the operating system. -By default, in non-debug builds of desktop or console apps, **abort** then invokes the Windows Error Reporting Service mechanism (formerly known as Dr. Watson) to report failures to Microsoft. This behavior can be enabled or disabled by calling `_set_abort_behavior` and setting or masking the `_CALL_REPORTFAULT` flag. When the flag is set, Windows displays a message box that has text something like "A problem caused the program to stop working correctly." The user can choose to invoke a debugger with a **Debug** button, or choose the **Close program** button to terminate the app with an error code that's defined by the operating system. +If the Windows error reporting handler isn't invoked, then **`abort`** calls [`_exit`](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` doesn't flush stream buffers or do `atexit`/`_onexit` processing. -If the Windows error reporting handler is not invoked, then **abort** calls [_exit](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` does not flush stream buffers or do `atexit`/`_onexit` processing. +For Windows compatibility reasons, when **`abort`** calls `_exit`, it may invoke the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API, which in turn allows DLL termination routines to run. Destructors aren't run in the executable, but the same may not be true of DLLs loaded in the executable's process space. This behavior doesn't strictly conform to the C++ standard. To immediately terminate a process including any DLLs, use the Windows [`TerminateProcess`](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminateprocess) API. You can also register an abort signal handler that invokes `TerminateProcess` for standard-compliant behavior. Compliant behavior may come at some cost in Windows compatibility. -For more information about CRT debugging, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +For more information about CRT debugging, see [CRT debugging techniques](../crt-debugging-techniques.md). **End Microsoft Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**abort**|\ or \| +| Routine | Required header | +|---|---| +| **`abort`** | `` or `` | ## Example @@ -69,8 +71,8 @@ The following program tries to open a file and aborts if the attempt fails. // the abort function by attempting to open a file // and aborts if the attempt fails. -#include -#include +#include +#include int main( void ) { @@ -96,13 +98,13 @@ File could not be opened: No such file or directory ## See also -[Using abort](../../cpp/using-abort.md)
-[abort Function](../../c-language/abort-function-c.md)
-[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[raise](raise.md)
-[signal](signal.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[_DEBUG](../../c-runtime-library/debug.md)
-[_set_abort_behavior](set-abort-behavior.md) +[Using `abort`](../../cpp/using-abort.md)\ +[`abort` function](../../c-language/abort-function-c.md)\ +[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`raise`](raise.md)\ +[`signal`](signal.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`_DEBUG`](../debug.md)\ +[`_set_abort_behavior`](set-abort-behavior.md) diff --git a/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md b/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md index 49d19b4ad0..19dbdf4c9d 100644 --- a/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md +++ b/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md @@ -6,11 +6,10 @@ api_name: ["abs", "_abs64", "labs", "llabs"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["stdlib/_abs64", "math/abs", "_abs64", "abs", "labs", "math/labs", "llabs", "math/llabs", "cmath/abs"] +f1_keywords: ["_abs64", "STDLIB/_abs64", "abs", "CORECRT_MATH/abs", "STDLIB/abs", "CSTDLIB/abs", "labs", "CORECRT_MATH/labs", "llabs", "CORECRT_MATH/llabs"] helpviewer_keywords: ["absolute values", "abs function", "abs64 function", "_abs64 function", "calculating absolute values"] -ms.assetid: 60f789d1-4a1e-49f5-9e4e-0bdb277ea26a --- -# abs, labs, llabs, _abs64 +# `abs`, `labs`, `llabs`, `_abs64` Calculates the absolute value of the argument. @@ -33,27 +32,27 @@ float abs( float n ); // C++ only ### Parameters -*n*\ +*`n`*\ Numeric value. -## Return Value +## Return value -The **abs**, **labs**, **llabs**, and **_abs64** functions return the absolute value of the parameter *n*. There's no error return. +The **`abs`**, **`labs`**, **`llabs`**, and **`_abs64`** functions return the absolute value of the parameter *`n`*. There's no error return. ## Remarks -Because C++ allows overloading, you can call overloads of **abs** that take and return **`long`**, **`long long`**, **`float`**, **`double`**, and **`long double`** values. These overloads are defined in the \ header. In a C program, **abs** always takes and returns an **`int`**. +Because C++ allows overloading, you can call overloads of **`abs`** that take and return **`long`**, **`long long`**, **`float`**, **`double`**, and **`long double`** values. These overloads are defined in the `` header. In a C program, **`abs`** always takes and returns an **`int`**. -**Microsoft-specific**: Because the range of negative integers that can be represented by using any integral type is larger than the range of positive integers that can be represented by using that type, it's possible to supply an argument to these functions that can't be converted. If the absolute value of the argument cannot be represented by the return type, the **abs** functions return the argument value unchanged. Specifically, `abs(INT_MIN)` returns `INT_MIN`, `labs(LONG_MIN)` returns `LONG_MIN`, `llabs(LLONG_MIN)` returns `LLONG_MIN`, and `_abs64(_I64_MIN)` returns `_I64_MIN`. This means that the **abs** functions cannot be used to guarantee a positive value. +**Microsoft-specific**: The range of negative integers representable in any integral type is larger than the range of positive integers representable in that type. So, it's possible to supply an argument to these functions that can't be converted. If the absolute value of the argument can't be represented by the return type, the **`abs`** functions return the argument value unchanged. Specifically, `abs(INT_MIN)` returns `INT_MIN`, `labs(LONG_MIN)` returns `LONG_MIN`, `llabs(LLONG_MIN)` returns `LLONG_MIN`, and `_abs64(_I64_MIN)` returns `_I64_MIN`. Effectively, the **`abs`** functions can't be used to guarantee a positive value. ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|-----------------------|---------------------------| -|**abs**, **labs**, **llabs**|\ or \|\, \, \ or \| -|**_abs64**|\|\ or \| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`abs`**, **`labs`**, **`llabs`** | `` or `` | ``, ``, `` or `` | +| **`_abs64`** | `` | `` or `` | -To use the overloaded versions of **abs** in C++, you must include the \ header. +To use the overloaded versions of **`abs`** in C++, you must include the `` header. ## Example @@ -114,8 +113,8 @@ _abs64(_I64_MIN) returns 0x8000000000000000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_cabs](cabs.md)
-[fabs, fabsf, fabsl](fabs-fabsf-fabsl.md)
-[imaxabs](imaxabs.md) +[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`_cabs`](cabs.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ +[`imaxabs`](imaxabs.md) diff --git a/docs/c-runtime-library/reference/access-crt.md b/docs/c-runtime-library/reference/access-crt.md index 98e59aab62..7a6d411ca8 100644 --- a/docs/c-runtime-library/reference/access-crt.md +++ b/docs/c-runtime-library/reference/access-crt.md @@ -6,12 +6,12 @@ api_name: ["access"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["access"] +f1_keywords: ["access", "CORECRT_IO/access"] helpviewer_keywords: ["access function"] ms.assetid: 65197793-bd0a-41c3-9c29-18de2d95d9a6 --- -# access (CRT) +# `access` (CRT) -The Microsoft-implemented POSIX function name `access` is a deprecated alias for the [_access](access-waccess.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `access` is a deprecated alias for the [`_access`](access-waccess.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_access](access-waccess.md) or the security-enhanced [_access_s](access-s-waccess-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_access`](access-waccess.md) or the security-enhanced [`_access_s`](access-s-waccess-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/access-s-waccess-s.md b/docs/c-runtime-library/reference/access-s-waccess-s.md index 8b92d4b4e7..c054b3b97d 100644 --- a/docs/c-runtime-library/reference/access-s-waccess-s.md +++ b/docs/c-runtime-library/reference/access-s-waccess-s.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: _access_s, _waccess_s" -title: "_access_s, _waccess_s" +description: "Learn more about: _access_s, _waccess_s, _taccess_s" +title: "_access_s, _waccess_s, _taccess_s" ms.date: "4/2/2020" -api_name: ["_access_s", "_waccess_s", "_o__access_s", "_o__waccess_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_access_s", "_waccess_s", "_taccess_s", "_o__access_s", "_o__waccess_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["waccess_s", "access_s", "_waccess_s", "_access_s"] -helpviewer_keywords: ["access_s function", "taccess_s function", "_taccess_s function", "waccess_s function", "_access_s function", "_waccess_s function"] -ms.assetid: fb3004fc-dcd3-4569-8b27-d817546e947e +f1_keywords: ["waccess_s", "access_s", "_taccess_s"] +helpviewer_keywords: ["access_s function", "waccess_s function", "_taccess_s function"] --- -# _access_s, _waccess_s +# `_access_s`, `_waccess_s`, `_taccess_s` -Determines file read/write permissions. This is a version of [_access, _waccess](access-waccess.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Determines file read/write permissions. These functions are versions of [`_access`, `_waccess`](access-waccess.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). + +For `_taccess_s`, see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -29,59 +30,61 @@ errno_t _waccess_s( ### Parameters -*path*
+*`path`*\ File or directory path. -*mode*
+*`mode`*\ Permission setting. -## Return Value +## Return value -Each function returns 0 if the file has the given mode. The function returns an error code if the named file does not exist or is not accessible in the given mode. In this case, the function returns an error code from the set as follows and also sets `errno` to the same value. +Each function returns 0 if the file has the given mode. The function returns an error code if the named file doesn't exist or isn't accessible in the given mode. In this case, the function returns an error code from the set as follows and also sets `errno` to the same value. -|errno value|Condition| -|-|-| -`EACCES`|Access denied. The file's permission setting does not allow specified access. -`ENOENT`|File name or path not found. -`EINVAL`|Invalid parameter. +| `errno` value | Condition | +|---|---| +| `EACCES` | Access denied. The file's permission setting doesn't allow specified access. | +| `ENOENT` | File name or path not found. | +| `EINVAL` | Invalid parameter. | -For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -When used with files, the **_access_s** function determines whether the specified file exists and can be accessed as specified by the value of *mode*. When used with directories, **_access_s** determines only whether the specified directory exists. In Windows 2000 and later operating systems, all directories have read and write access. +When used with files, the **`_access_s`** function determines whether the specified file exists and can be accessed as specified by the value of *`mode`*. When used with directories, **`_access_s`** determines only whether the specified directory exists. In Windows 2000 and later operating systems, all directories have read and write access. + +| *`mode`* value | Checks file for | +|---|---| +| 00 | Existence only. | +| 02 | Write permission. | +| 04 | Read permission. | +| 06 | Read and write permission. | -|mode value|Checks file for| -|----------------|---------------------| -|00|Existence only.| -|02|Write permission.| -|04|Read permission.| -|06|Read and write permission.| +Permission to read or write the file isn't enough to ensure the ability to open a file. For example, if a file is locked by another process, it might not be accessible even though **`_access_s`** returns 0. -Permission to read or write the file is not enough to ensure the ability to open a file. For example, if a file is locked by another process, it might not be accessible even though **_access_s** returns 0. +**`_waccess_s`** is a wide-character version of **`_access_s`**, where the *`path`* argument to **`_waccess_s`** is a wide-character string. Otherwise, **`_waccess_s`** and **`_access_s`** behave identically. -**_waccess_s** is a wide-character version of **_access_s**, where the *path* argument to **_waccess_s** is a wide-character string. Otherwise, **_waccess_s** and **_access_s** behave identically. +These functions validate their parameters. If *`path`* is `NULL` or *`mode`* doesn't specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. -These functions validate their parameters. If *path* is NULL or *mode* does not specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_taccess_s`|**_access_s**|**_access_s**|**_waccess_s**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_taccess_s` | `_access_s` | `_access_s` | `_waccess_s` | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_access_s**|\|\| -|**_waccess_s**|\ or \|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_access_s`** | `` | `` | +| **`_waccess_s`** | `` or `` | `` | ## Example -This example uses **_access_s** to check the file named crt_access_s.c to see whether it exists and whether writing is allowed. +This example uses **`_access_s`** to check the file named crt_access_s.c to see whether it exists and whether writing is allowed. ```C // crt_access_s.c @@ -125,9 +128,9 @@ File crt_access_s.c does not have write permission. ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_access, _waccess](access-waccess.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_open, _wopen](open-wopen.md)
-[_stat, _wstat Functions](stat-functions.md) +[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/access-waccess.md b/docs/c-runtime-library/reference/access-waccess.md index 7597f5528f..87cf212ca0 100644 --- a/docs/c-runtime-library/reference/access-waccess.md +++ b/docs/c-runtime-library/reference/access-waccess.md @@ -1,19 +1,20 @@ --- -description: "Learn more about: _access, _waccess" title: "_access, _waccess" +description: "Learn more about: _access, _waccess" ms.date: "4/2/2020" -api_name: ["_access", "_waccess", "_o__access", "_o__waccess"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_access", "_waccess", "t_access", "_o__access", "_o__waccess"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_waccess", "_access", "taccess", "waccess", "_taccess"] helpviewer_keywords: ["access function", "_taccess function", "waccess function", "_access function", "_waccess function", "taccess function"] -ms.assetid: ba34f745-85c3-49e5-a7d4-3590bd249dd3 --- -# `_access`, `_waccess` +# `_access`, `_waccess`, `t_access` Determines if a file is read-only or not. More secure versions are available; see [`_access_s`, `_waccess_s`](access-s-waccess-s.md). +For `_taccess`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -29,55 +30,55 @@ int _waccess( ### Parameters -*`path`*
+*`path`*\ File or directory path. -*`mode`*
+*`mode`*\ Read/write attribute. -## Return Value +## Return value -Each function returns 0 if the file has the given mode. The function returns -1 if the named file does not exist or does not have the given mode; in this case, `errno` is set as shown in the following table. +Each function returns 0 if the file has the given mode. The function returns -1 if the named file doesn't exist or doesn't have the given mode; in this case, `errno` is set as shown in the following table. | Value | Description | -|--|--| -| `EACCES` | Access denied: the file's permission setting does not allow specified access. | +|---|---| +| `EACCES` | Access denied: the file's permission setting doesn't allow specified access. | | `ENOENT` | File name or path not found. | | `EINVAL` | Invalid parameter. | -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks When used with files, the **`_access`** function determines whether the specified file or directory exists and has the attributes specified by the value of *`mode`*. When used with directories, **`_access`** determines only whether the specified directory exists; in Windows 2000 and later operating systems, all directories have read and write access. -|*`mode`* value|Checks file for| -|------------------|---------------------| -|00|Existence only| -|02|Write-only| -|04|Read-only| -|06|Read and write| +| *`mode`* value | Checks file for | +|---|---| +| 00 | Existence only | +| 02 | Write-only | +| 04 | Read-only | +| 06 | Read and write | -This function only checks whether the file and directory are read-only or not, it does not check the filesystem security settings. For that you need an access token. For more information on filesystem security, see [Access Tokens](/windows/win32/SecAuthZ/access-tokens). An ATL class exists to provide this functionality; see [`CAccessToken` Class](../../atl/reference/caccesstoken-class.md). +This function only checks whether the file and directory are read-only or not, it doesn't check the filesystem security settings. For that you need an access token. For more information on filesystem security, see [Access tokens](/windows/win32/SecAuthZ/access-tokens). An ATL class exists to provide this functionality; see [`CAccessToken` Class](../../atl/reference/caccesstoken-class.md). **`_waccess`** is a wide-character version of **`_access`**; the *`path`* argument to **`_waccess`** is a wide-character string. **`_waccess`** and **`_access`** behave identically otherwise. -This function validates its parameters. If *`path`* is `NULL` or *`mode`* does not specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. +This function validates its parameters. If *`path`* is `NULL` or *`mode`* doesn't specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text function mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_taccess`|**`_access`**|**`_access`**|**`_waccess`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_taccess` | **`_access`** | **`_access`** | **`_waccess`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`_access`**|``|``| -|**`_waccess`**|`` or ``|``| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_access`** | `` | `` | +| **`_waccess`** | `` or `` | `` | ## Example @@ -89,9 +90,9 @@ The following example uses **`_access`** to check the file named *`crt_ACCESS.C` // This example uses _access to check the file named // crt_ACCESS.C to see if it exists and if writing is allowed. -#include -#include -#include +#include +#include +#include int main( void ) { @@ -115,8 +116,8 @@ File crt_ACCESS.C does not have write permission. ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_chmod`, `_wchmod`](chmod-wchmod.md)
-[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[`_open`, `_wopen`](open-wopen.md)
-[`_stat`, `_wstat` Functions](stat-functions.md) +[File handling](../file-handling.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/acos-acosf-acosl.md b/docs/c-runtime-library/reference/acos-acosf-acosl.md index d4deb8d020..5296418f6b 100644 --- a/docs/c-runtime-library/reference/acos-acosf-acosl.md +++ b/docs/c-runtime-library/reference/acos-acosf-acosl.md @@ -3,10 +3,10 @@ title: "acos, acosf, acosl" description: "API reference for acos, acosf, and acosl; which calculate the arccosine of a floating-point value." ms.date: "1/15/2021" api_name: ["acosf", "acos", "acosl", "_o_acos", "_o_acosf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["acos", "acosl", "acosf", "math/acosf", "math/acosl"] +f1_keywords: ["acos", "CMATH/acos", "CORECRT_MATH/acos", "acosl", "CORECRT_MATH/acosl", "acosf", "CORECRT_MATH/acosf"] helpviewer_keywords: ["acos function", "acosl function", "acosf function", "trigonometric functions", "arccosine function"] --- # `acos`, `acosf`, `acosl` @@ -30,32 +30,32 @@ long double acos( long double x ); // C++ only *`x`*\ Value between -1 and 1, for which to calculate the arccosine (the inverse cosine). -## Return Value +## Return value -The **`acos`** function returns the arccosine of *x* in the range 0 to π radians. +The **`acos`** function returns the arccosine of *`x`* in the range 0 to π radians. By default, if *`x`* is less than -1 or greater than 1, **`acos`** returns an indefinite. -|Input|`SEH` exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|`± ∞`|`INVALID`|`_DOMAIN`| -|`± QNAN, IND`|none|`_DOMAIN`| -||`x`|>1|`INVALID`|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF | `INVALID` | `_DOMAIN` | +| ± QNaN, IND | none | `_DOMAIN` | +| `|x| > 1` | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`acos`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`acos`** always takes and returns a **`double`**. -If you use the `` `acos()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `acos` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`acos`**, **`acosf`**, **`acosl`**|``|``| -|**`acos()`** macro | `` || +| Routine | Required header | Optional headers | +|---|---|---| +| **`acos`**, **`acosf`**, **`acosl`** | `` | `` | +| **`acos`** macro | `` | | ## Example @@ -109,7 +109,7 @@ Arccosine of 0.000000 = 1.570796 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ diff --git a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md index a0d9af2118..eae18abea8 100644 --- a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md +++ b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md @@ -3,14 +3,14 @@ title: "acosh, acoshf, acoshl" description: "API reference for acosh, acoshf, and acoshl; which calculate the inverse hyperbolic cosine of a floating-point value." ms.date: "08/31/2020" api_name: ["acoshf", "acosh", "acoshl", "_o_acosh", "_o_acoshf", "_o_acoshl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["acosh", "acoshf", "acoshl", "math/acosh", "math/acoshf", "math/acoshl"] helpviewer_keywords: ["acoshf function", "acosh function", "acoshl function"] ms.assetid: 6985c4d7-9e2a-44ce-9a9b-5a43015f15f7 --- -# acosh, acoshf, acoshl +# `acosh`, `acoshf`, `acoshl` Calculates the inverse hyperbolic cosine. @@ -28,34 +28,34 @@ long double acosh( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **acosh** functions return the inverse hyberbolic cosine (arc hyperbolic cosine) of *x*. These functions are valid over the domain *x* ≥ 1. If *x* is less than 1, `errno` is set to `EDOM` and the result is a quiet NaN. If *x* is a quiet NaN, indefinite, or infinity, the same value is returned. +The **`acosh`** functions return the inverse hyperbolic cosine (arc hyperbolic cosine) of *`x`*. These functions are valid over the domain *`x`* ≥ 1. If *`x`* is less than 1, `errno` is set to `EDOM`, and the result is a quiet NaN. If *`x`* is a quiet NaN, indefinite, or infinity, the same value is returned. -|Input|SEH Exception|`_matherr` Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND, INF|none|none| -|*x* < 1|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND, INF | none | none | +| *`x`* < 1 | none | none | ## Remarks -When you use C++, you can call overloads of **acosh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **acosh** always takes and returns **`double`**. +When you use C++, you can call overloads of **`acosh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`acosh`** always takes and returns **`double`**. -If you use the \ `acosh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `acosh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**acosh**, **acoshf**, **acoshl**|\|\| -|**acosh()** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`acosh`**, **`acoshf`**, **`acoshl`** | \ | \ | +| **`acosh`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,9 +87,9 @@ acosh( 1.324609 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[asinh, asinhf, asinhl](asinh-asinhf-asinhl.md)
-[atanh, atanhf, atanhl](atanh-atanhf-atanhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md) +[Math and floating-point support](../floating-point-support.md)\ +[`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ +[`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/aligned-free-dbg.md b/docs/c-runtime-library/reference/aligned-free-dbg.md index 5a724e6b3d..1ef9d5fe97 100644 --- a/docs/c-runtime-library/reference/aligned-free-dbg.md +++ b/docs/c-runtime-library/reference/aligned-free-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_free_dbg", "aligned_free_dbg"] helpviewer_keywords: ["_aligned_free_dbg function", "aligned_free_dbg function"] ms.assetid: eb0cb3c8-0992-4db8-bac3-65f1b8311ca6 --- -# _aligned_free_dbg +# `_aligned_free_dbg` -Frees a block of memory that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug only). +Frees a block of memory that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug only). ## Syntax @@ -24,27 +24,27 @@ void _aligned_free_dbg( ### Parameters -*memblock*
-A pointer to the memory block that was returned to the [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) function. +*`memblock`*\ +A pointer to the memory block that was returned to the [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) function. ## Remarks -The **_aligned_free_dbg** function is a debug version of the [_aligned_free](aligned-free.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_free_dbg** is reduced to a call to `_aligned_free`. Both `_aligned_free` and **_aligned_free_dbg** free a memory block in the base heap, but **_aligned_free_dbg** accommodates a debugging feature: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions. +The **`_aligned_free_dbg`** function is a debug version of the [`_aligned_free`](aligned-free.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_free_dbg`** is reduced to a call to `_aligned_free`. Both `_aligned_free` and **`_aligned_free_dbg`** free a memory block in the base heap, but **`_aligned_free_dbg`** accommodates a debugging feature: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions. -**_aligned_free_dbg** performs a validity check on all specified files and block locations before performing the free operation. The application is not expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion and issues an error report if overwriting has occurred. If the _CRTDBG_DELAY_FREE_MEM_DF bit field of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the _FREE_BLOCK block type, and kept in the heap's linked list of memory blocks. +**`_aligned_free_dbg`** performs a validity check on all specified files and block locations before performing the free operation. The application isn't expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion. It issues an error report if overwriting has occurred. If the `_CRTDBG_DELAY_FREE_MEM_DF` bit field of the [`_crtDbgFlag`](../crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the `_FREE_BLOCK` block type, and kept in the heap's linked list of memory blocks. -If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_free_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_free_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-free.md b/docs/c-runtime-library/reference/aligned-free.md index 264b0485be..e369c86795 100644 --- a/docs/c-runtime-library/reference/aligned-free.md +++ b/docs/c-runtime-library/reference/aligned-free.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_free" title: "_aligned_free" ms.date: "4/2/2020" api_name: ["_aligned_free", "_o__aligned_free"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_free", "_aligned_free"] helpviewer_keywords: ["_aligned_free function", "aligned_free function"] ms.assetid: ed1ce952-cdfc-4682-85cc-f75d4101603d --- -# _aligned_free +# `_aligned_free` -Frees a block of memory that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Frees a block of memory that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -24,27 +24,27 @@ void _aligned_free ( ### Parameters -*memblock*
+*`memblock`*\ A pointer to the memory block that was returned to the `_aligned_malloc` or `_aligned_offset_malloc` function. ## Remarks -**_aligned_free** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [noalias](../../cpp/noalias.md). +**`_aligned_free`** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [`noalias`](../../cpp/noalias.md). -This function does not validate its parameter, unlike the other _aligned CRT functions. If *memblock* is a NULL pointer, this function simply performs no actions. It does not change `errno` and it does not invoke the invalid parameter handler. If an error occurs in the function due to not using _aligned functions previously to allocate the block of memory or a misalignment of memory occurs due to some unforeseen calamity, the function generates a debug report from the [_RPT, _RPTF, _RPTW, _RPTFW Macros](rpt-rptf-rptw-rptfw-macros.md). +This function doesn't validate its parameter, unlike the other _aligned CRT functions. If *`memblock`* is a `NULL` pointer, this function simply performs no actions. It doesn't change `errno` and it doesn't invoke the invalid parameter handler. If an error occurs in the function because `_aligned` functions weren't used to allocate the block of memory, or a misalignment of memory occurs due to some unforeseen calamity, the function generates a debug report from the [`_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` macros](rpt-rptf-rptw-rptfw-macros.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_free**|\| +| Routine | Required header | +|---|---| +| **`_aligned_free`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md) +[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-malloc-dbg.md index 7dfd0eb979..c9a59fa438 100644 --- a/docs/c-runtime-library/reference/aligned-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-malloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_malloc_dbg", "aligned_malloc_dbg"] helpviewer_keywords: ["aligned_malloc_dbg function", "_aligned_malloc_dbg function"] ms.assetid: fb0429c3-685d-4826-9075-2515c5bdc5c6 --- -# _aligned_malloc_dbg +# `_aligned_malloc_dbg` -Allocates memory on a specified alignment boundary with additional space for a debugging header and overwrite buffers (debug version only). +Allocates memory on a specified alignment boundary with extra space for a debugging header and overwrite buffers (debug version only). ## Syntax @@ -27,44 +27,44 @@ void * _aligned_malloc_dbg( ### Parameters -*size*
+*`size`*\ Size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to the name of the source file that requested the allocation operation or NULL. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or NULL. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -A pointer to the memory block that was allocated or NULL if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_malloc_dbg** is a debug version of the [_aligned_malloc](aligned-malloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_malloc_dbg** is reduced to a call to `_aligned_malloc`. Both `_aligned_malloc` and **_aligned_malloc_dbg** allocate a block of memory in the base heap, but **_aligned_malloc_dbg** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_malloc_dbg`** is a debug version of the [`_aligned_malloc`](aligned-malloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_malloc_dbg`** is reduced to a call to `_aligned_malloc`. Both `_aligned_malloc` and **`_aligned_malloc_dbg`** allocate a block of memory in the base heap, but **`_aligned_malloc_dbg`** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_malloc_dbg** allocates the memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_aligned_malloc_dbg`** allocates the memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_aligned_malloc_dbg** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_malloc_dbg** validates its parameters. If *alignment* is not a power of 2 or *size* is zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns NULL and sets `errno` to `EINVAL`. +**`_aligned_malloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_malloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_malloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-malloc.md b/docs/c-runtime-library/reference/aligned-malloc.md index c0a5a7fb13..38430e1f86 100644 --- a/docs/c-runtime-library/reference/aligned-malloc.md +++ b/docs/c-runtime-library/reference/aligned-malloc.md @@ -3,7 +3,7 @@ description: "Learn more about: _aligned_malloc" title: "_aligned_malloc" ms.date: "4/2/2020" api_name: ["_aligned_malloc", "_o__aligned_malloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_malloc", "alligned_malloc"] @@ -25,13 +25,13 @@ void * _aligned_malloc( ### Parameters -*`size`*
+*`size`*\ Size of the requested memory allocation. -*`alignment`*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value A pointer to the memory block that was allocated or `NULL` if the operation failed. The pointer is a multiple of *`alignment`*. @@ -39,19 +39,19 @@ A pointer to the memory block that was allocated or `NULL` if the operation fail **`_aligned_malloc`** is based on [`malloc`](malloc.md). -**`_aligned_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). +**`_aligned_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc`** validates its parameters. If *`alignment`* is not a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns NULL and sets `errno` to `EINVAL`. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc`** validates its parameters. If *`alignment`* isn't a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. Use [`_aligned_free`](aligned-free.md) to deallocate memory obtained by both **`_aligned_malloc`** and `_aligned_offset_malloc`. Don't use `free`, which doesn't reclaim the aligned memory correctly and can lead to hard-to-diagnose bugs. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_aligned_malloc`**|``| +| Routine | Required C header | C++ header | +|---|---|---| +| **`_aligned_malloc`** | `` | `` | ## Example @@ -137,4 +137,4 @@ This pointer, 3280891, is offset by 5 on alignment of 16 ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md) +[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-msize-dbg.md b/docs/c-runtime-library/reference/aligned-msize-dbg.md index 6d20552a77..ef2623a5e2 100644 --- a/docs/c-runtime-library/reference/aligned-msize-dbg.md +++ b/docs/c-runtime-library/reference/aligned-msize-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_aligned_msize_dbg"] helpviewer_keywords: ["_aligned_msize_dbg"] ms.assetid: f1c44af0-3f66-4033-81d1-d71d3afecba0 --- -# _aligned_msize_dbg +# `_aligned_msize_dbg` Returns the size of a memory block allocated in the heap (debug version only). @@ -26,41 +26,41 @@ size_t _aligned_msize_dbg( ### Parameters -*memblock*
+*`memblock`*\ Pointer to the memory block. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value Returns the size (in bytes) as an unsigned integer. ## Remarks -The *alignment* and *offset* values must be the same as the values passed to the function that allocated the block. +The *`alignment`* and *`offset`* values must be the same as the values passed to the function that allocated the block. -**_aligned_msize_dbg** is a debug version of the [_aligned_msize](aligned-msize.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_msize_dbg** is reduced to a call to **_aligned_msize**. Both **_aligned_msize** and **_aligned_msize_dbg** calculate the size of a memory block in the base heap, but **_aligned_msize_dbg** adds a debugging feature: It includes the buffers on either side of the user portion of the memory block in the returned size. +**`_aligned_msize_dbg`** is a debug version of the [`_aligned_msize`](aligned-msize.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_msize_dbg`** is reduced to a call to `_aligned_msize`. Both `_aligned_msize` and **`_aligned_msize_dbg`** calculate the size of a memory block in the base heap, but **`_aligned_msize_dbg`** adds a debugging feature: It includes the buffers on either side of the user portion of the memory block in the returned size. -This function validates its parameter. If *memblock* is a null pointer or *alignment* is not a power of 2, **_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer or *`alignment`* isn't a power of 2, `_msize` invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_msize_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_msize_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/aligned-msize.md b/docs/c-runtime-library/reference/aligned-msize.md index 65b5f73a8b..62782ee251 100644 --- a/docs/c-runtime-library/reference/aligned-msize.md +++ b/docs/c-runtime-library/reference/aligned-msize.md @@ -3,14 +3,14 @@ description: "Learn more about: _aligned_msize" title: "_aligned_msize" ms.date: "4/2/2020" api_name: ["_aligned_msize", "_o__aligned_msize"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_msize", "aligned_msize"] helpviewer_keywords: ["aligned_msize function", "_aligned_msize function"] ms.assetid: 10995edc-2110-4212-9ca9-5e0220a464f4 --- -# _aligned_msize +# `_aligned_msize` Returns the size of a memory block allocated in the heap. @@ -26,41 +26,41 @@ size_t _aligned_msize( ### Parameters -*memblock*
+*`memblock`*\ Pointer to the memory block. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value Returns the size (in bytes) as an unsigned integer. ## Remarks -The **_aligned_msize** function returns the size, in bytes, of the memory block allocated by a call to [_aligned_malloc](aligned-malloc.md) or [_aligned_realloc](aligned-realloc.md). The *alignment* and *offset* values must be the same as the values passed to the function that allocated the block. +The **`_aligned_msize`** function returns the size, in bytes, of the memory block allocated by a call to [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_realloc`](aligned-realloc.md). The *`alignment`* and *`offset`* values must be the same as the values passed to the function that allocated the block. -When the application is linked with a debug version of the C run-time libraries, **_aligned_msize** resolves to [_aligned_msize_dbg](aligned-msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_aligned_msize`** resolves to [`_aligned_msize_dbg`](aligned-msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -This function validates its parameter. If *memblock* is a null pointer or *alignment* is not a power of 2, **_aligned_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer or *`alignment`* isn't a power of 2, **`_aligned_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_msize**|\| +| Routine | Required header | +|---|---| +| **`_aligned_msize`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md index 527f4be281..3eaa602cfb 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_aligned_offset_malloc_dbg", "aligned_offset_malloc_dbg"] helpviewer_keywords: ["_aligned_offset_malloc_dbg function", "aligned_offset_malloc_dbg function"] ms.assetid: 6c242307-c59e-4d63-aae5-d8cbec8e021c --- -# _aligned_offset_malloc_dbg +# `_aligned_offset_malloc_dbg` Allocates memory on a specified alignment boundary (debug version only). @@ -28,53 +28,53 @@ void * _aligned_offset_malloc_dbg( ### Parameters -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -A pointer to the memory block that was allocated or **NULL** if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_offset_malloc_dbg** is a debug version of the [_aligned_offset_malloc](aligned-offset-malloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_malloc_dbg** is reduced to a call to **_aligned_offset_malloc**. Both **_aligned_offset_malloc** and **_aligned_offset_malloc_dbg** allocate a block of memory in the base heap, but **_aligned_offset_malloc_dbg** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_malloc_dbg`** is a debug version of the [`_aligned_offset_malloc`](aligned-offset-malloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_malloc_dbg`** is reduced to a call to **`_aligned_offset_malloc`**. Both **`_aligned_offset_malloc`** and **`_aligned_offset_malloc_dbg`** allocate a block of memory in the base heap, but **`_aligned_offset_malloc_dbg`** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_offset_malloc_dbg** allocates the memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_aligned_offset_malloc_dbg`** allocates the memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_aligned_offset_malloc_dbg** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. +**`_aligned_offset_malloc_dbg`** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. -**_aligned_offset_malloc_dbg** is based on **malloc**; for more information, see [malloc](malloc.md). +**`_aligned_offset_malloc_dbg`** is based on `malloc`; for more information, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_malloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, `_aligned_offset_malloc` validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). -For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_malloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_malloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-malloc.md b/docs/c-runtime-library/reference/aligned-offset-malloc.md index d0eae71c05..70bd83880b 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc.md @@ -3,14 +3,14 @@ description: "Learn more about: _aligned_offset_malloc" title: "_aligned_offset_malloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_malloc", "_o__aligned_offset_malloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_offset_malloc", "aligned_offset_malloc"] helpviewer_keywords: ["_aligned_offset_malloc function", "aligned_offset_malloc function"] ms.assetid: 447681a3-7c95-4655-86ba-fa3a4ca4c521 --- -# _aligned_offset_malloc +# `_aligned_offset_malloc` Allocates memory on a specified alignment boundary. @@ -26,41 +26,41 @@ void * _aligned_offset_malloc( ### Parameters -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -A pointer to the memory block that was allocated or **NULL** if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_offset_malloc** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. +**`_aligned_offset_malloc`** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. -**_aligned_offset_malloc** is based on **malloc**; for more information, see [malloc](malloc.md). +**`_aligned_offset_malloc`** is based on `malloc`; for more information, see [`malloc`](malloc.md). -**_aligned_offset_malloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_malloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_malloc`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_malloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_malloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md index ec0b186318..b9292dae92 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_offset_realloc_dbg", "_aligned_offset_realloc_dbg"] helpviewer_keywords: ["aligned_offset_realloc_dbg function", "_aligned_offset_realloc_dbg function"] ms.assetid: 64e30a12-887e-453b-aea8-aed793fca9d8 --- -# _aligned_offset_realloc_dbg +# `_aligned_offset_realloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug version only). ## Syntax @@ -29,52 +29,52 @@ void * _aligned_offset_realloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the **aligned_offset_realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the **`aligned_offset_realloc`** operation or `NULL`. -*linenumber*
-Line number in the source file where the **aligned_offset_realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the **`aligned_offset_realloc`** operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_offset_realloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_realloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that's suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. ## Remarks -**_aligned_offset_realloc_dbg** is a debug version of the [_aligned_offset_realloc](aligned-offset-realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_realloc_dbg** is reduced to a call to **_aligned_offset_realloc**. Both **_aligned_offset_realloc** and **_aligned_offset_realloc_dbg** reallocate a memory block in the base heap, but **_aligned_offset_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_realloc_dbg`** is a debug version of the [`_aligned_offset_realloc`](aligned-offset-realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_realloc_dbg`** is reduced to a call to **`_aligned_offset_realloc`**. Both **`_aligned_offset_realloc`** and **`_aligned_offset_realloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_offset_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_realloc_dbg** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_realloc_dbg`** allows a structure to be aligned at an offset within the structure. -**_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +`_realloc_dbg` reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and also change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_realloc_dbg** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-realloc.md b/docs/c-runtime-library/reference/aligned-offset-realloc.md index 53d2c11384..462eb5e22a 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_offset_realloc" title: "_aligned_offset_realloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_realloc", "_o__aligned_offset_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_offset_realloc", "_aligned_offset_realloc"] helpviewer_keywords: ["aligned_offset_realloc function", "_aligned_offset_realloc function"] ms.assetid: e0263533-991e-41b0-acc9-1b8a51ab9ecd --- -# _aligned_offset_realloc +# `_aligned_offset_realloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -27,44 +27,44 @@ void * _aligned_offset_realloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -**_aligned_offset_realloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_realloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. -**_aligned_offset_realloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). ## Remarks -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_realloc** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_realloc`** allows a structure to be aligned at an offset within the structure. -**_aligned_offset_realloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). If *memblock* is **NULL**, the function calls **_aligned_offset_malloc** internally. +**`_aligned_offset_realloc`** is based on `malloc`. For more information about using **`_aligned_offset_malloc`**, see [`malloc`](malloc.md). If *`memblock`* is `NULL`, the function calls **`_aligned_offset_malloc`** internally. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_realloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_realloc`** validates its parameters. If *`alignment`* isn't a power of 2 or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_realloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_realloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md index 99bd6f9653..34046b47a6 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_offset_recalloc_dbg", "_aligned_offset_recalloc_dbg"] helpviewer_keywords: ["aligned_offset_recalloc_dbg function", "_aligned_offset_recalloc_dbg function"] ms.assetid: 7ab719c3-77e0-4d2e-934f-01529d062fbf --- -# _aligned_offset_recalloc_dbg +# `_aligned_offset_recalloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). ## Syntax @@ -30,47 +30,47 @@ void * _aligned_offset_recalloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the realloc operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the realloc operation or `NULL`. -*linenumber*
-Line number in the source file where the realloc operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the realloc operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_offset_recalloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_recalloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. ## Remarks -**_aligned_offset_realloc_dbg** is a debug version of the [_aligned_offset_recalloc](aligned-offset-recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_recalloc_dbg** is reduced to a call to **_aligned_offset_recalloc**. Both **_aligned_offset_recalloc** and **_aligned_offset_recalloc_dbg** reallocate a memory block in the base heap, but **_aligned_offset_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_realloc_dbg`** is a debug version of the [`_aligned_offset_recalloc`](aligned-offset-recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_recalloc_dbg`** is reduced to a call to **`_aligned_offset_recalloc`**. Both **`_aligned_offset_recalloc`** and **`_aligned_offset_recalloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_offset_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_offset_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_aligned_offset_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and also change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size (*number* * *size*) was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_recalloc_dbg** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to the requested size and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size (*`number`* * *`size`*) was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to the requested *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_recalloc_dbg`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-recalloc.md b/docs/c-runtime-library/reference/aligned-offset-recalloc.md index e553600123..6b8878748f 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_offset_recalloc" title: "_aligned_offset_recalloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_recalloc", "_o__aligned_offset_recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_offset_recalloc", "_aligned_offset_recalloc"] helpviewer_keywords: ["aligned_offset_recalloc function", "_aligned_offset_recalloc function"] ms.assetid: a258f54e-eeb4-4853-96fc-007d710f98e9 --- -# _aligned_offset_recalloc +# `_aligned_offset_recalloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0. +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0. ## Syntax @@ -28,45 +28,45 @@ void * _aligned_offset_recalloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -**_aligned_offset_recalloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_recalloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -**_aligned_offset_recalloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_recalloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). ## Remarks -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_recalloc** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_recalloc`** allows a structure to be aligned at an offset within the structure. -**_aligned_offset_recalloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). If *memblock* is **NULL**, the function calls **_aligned_offset_malloc** internally. +**`_aligned_offset_recalloc`** is based on `malloc`. For more information about using **`_aligned_offset_malloc`**, see [`malloc`](malloc.md). If *`memblock`* is `NULL`, the function calls **`_aligned_offset_malloc`** internally. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size (*number* * *size*) was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_recalloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to the requested size and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size (*`number`* * *`size`*) was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_recalloc`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to the requested *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_recalloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_recalloc`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
-[_recalloc](recalloc.md)
-[_aligned_recalloc](aligned-recalloc.md)
+[Data alignment](../data-alignment.md)\ +[`_recalloc`](recalloc.md)\ +[`_aligned_recalloc`](aligned-recalloc.md) diff --git a/docs/c-runtime-library/reference/aligned-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-realloc-dbg.md index b817c6b38a..02f8a69c49 100644 --- a/docs/c-runtime-library/reference/aligned-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-realloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_realloc_dbg", "_aligned_realloc_dbg"] helpviewer_keywords: ["_aligned_realloc_dbg function", "aligned_realloc_dbg function"] ms.assetid: 8aede920-991e-44cd-867f-83dc2165db47 --- -# _aligned_realloc_dbg +# `_aligned_realloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug version only). ## Syntax @@ -28,51 +28,51 @@ void * _aligned_realloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to the name of the source file that requested the **realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the `realloc` operation or `NULL`. -*linenumber*
-Line number in the source file where the **realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the `realloc` operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_realloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_realloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_realloc_dbg** is a debug version of the [_aligned_realloc](aligned-realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_realloc_dbg** is reduced to a call to **_aligned_realloc**. Both **_aligned_realloc** and **_aligned_realloc_dbg** reallocate a memory block in the base heap, but **_aligned_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_realloc_dbg`** is a debug version of the [`_aligned_realloc`](aligned-realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_realloc_dbg`** is reduced to a call to `_aligned_realloc`. Both `_aligned_realloc` and **`_aligned_realloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_aligned_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -**_aligned_realloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_aligned_realloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -Also, **_aligned_realloc_dbg** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +Also, **`_aligned_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-realloc.md b/docs/c-runtime-library/reference/aligned-realloc.md index 964f8acf63..bb7f2177f0 100644 --- a/docs/c-runtime-library/reference/aligned-realloc.md +++ b/docs/c-runtime-library/reference/aligned-realloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_realloc" title: "_aligned_realloc" ms.date: "4/2/2020" api_name: ["_aligned_realloc", "_o__aligned_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_realloc", "aligned_realloc"] helpviewer_keywords: ["aligned_realloc function", "_aligned_realloc function"] ms.assetid: 80ce96e8-6087-416f-88aa-4dbb8cb1d218 --- -# _aligned_realloc +# `_aligned_realloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -26,39 +26,39 @@ void * _aligned_realloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value -**_aligned_realloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_realloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_realloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). +**`_aligned_realloc`** is based on `malloc`. For more information about using `_aligned_offset_malloc`, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_realloc** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_realloc`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_realloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_realloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md index f4743e9444..41d2154689 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_recalloc_dbg", "aligned_recalloc_dbg"] helpviewer_keywords: ["aligned_recalloc_dbg function", "_aligned_recalloc_dbg function"] ms.assetid: 55c3c27e-561c-4d6b-9bf9-1e34cc556e4b --- -# _aligned_recalloc_dbg +# `_aligned_recalloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). ## Syntax @@ -29,54 +29,54 @@ void * _aligned_recalloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ The number of elements. -*size*
+*`size`*\ The size in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_recalloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_recalloc_dbg`** returns a `void` pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_recalloc_dbg** is a debug version of the [_aligned_recalloc](aligned-recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_recalloc_dbg** is reduced to a call to **_aligned_recalloc**. Both **_aligned_recalloc** and **_aligned_recalloc_dbg** reallocate a memory block in the base heap, but **_aligned_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_recalloc_dbg`** is a debug version of the [`_aligned_recalloc`](aligned-recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_recalloc_dbg`** is reduced to a call to `_aligned_recalloc`. Both `_aligned_recalloc` and **`_aligned_recalloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_recalloc_dbg** reallocates the specified memory block with slightly more space than the requested size (*number* * *size*) which might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. The user portion of the block is filled with the value 0xCD and the overwrite buffers are filled with 0xFD. +**`_aligned_recalloc_dbg`** reallocates the specified memory block with slightly more space than the requested size (*`number`* * *`size`*) which might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and change the size of the memory block. The user portion of the block is filled with the value 0xCD, and the overwrite buffers are filled with 0xFD. -**_aligned_recalloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails; **EINVAL** is returned if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_aligned_recalloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails; `EINVAL` is returned if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -Also, **_aligned_recalloc_dbg** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +Also, **`_aligned_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_recalloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-recalloc.md b/docs/c-runtime-library/reference/aligned-recalloc.md index 0dd18cf48f..f3127771e7 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-recalloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_recalloc" title: "_aligned_recalloc" ms.date: "4/2/2020" api_name: ["_aligned_recalloc", "_o__aligned_recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_recalloc", "_aligned_recalloc"] helpviewer_keywords: ["aligned_recalloc function", "_aligned_recalloc function"] ms.assetid: d3da3dcc-79ef-4273-8af5-ac7469420142 --- -# _aligned_recalloc +# `_aligned_recalloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0. +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0. ## Syntax @@ -27,40 +27,40 @@ void * _aligned_recalloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ The number of elements. -*size*
+*`size`*\ The size in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value -**_aligned_recalloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_recalloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_recalloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). +**`_aligned_recalloc`** is based on `malloc`. For more information about using `_aligned_offset_malloc`, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_recalloc** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_recalloc`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_recalloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_recalloc`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
-[_recalloc](recalloc.md)
-[_aligned_offset_recalloc](aligned-offset-recalloc.md)
+[Data alignment](../data-alignment.md)\ +[`_recalloc`](recalloc.md)\ +[`_aligned_offset_recalloc`](aligned-offset-recalloc.md) diff --git a/docs/c-runtime-library/reference/alloca.md b/docs/c-runtime-library/reference/alloca.md index 5367a7aec4..693bcebda9 100644 --- a/docs/c-runtime-library/reference/alloca.md +++ b/docs/c-runtime-library/reference/alloca.md @@ -26,36 +26,36 @@ void *_alloca( *`size`*\ Bytes to be allocated from the stack. -## Return Value +## Return value -The **`_alloca`** routine returns a **`void`** pointer to the allocated space, which is guaranteed to be suitably aligned for storage of any type of object. If *`size`* is 0, **`_alloca`** allocates a zero-length item and returns a valid pointer to that item. +The **`_alloca`** routine returns a **`void`** pointer to the allocated space, which is suitably aligned for storage of any type of object. If *`size`* is 0, **`_alloca`** allocates a zero-length item and returns a valid pointer to that item. -A stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured Exception Handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH). +A stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH). ## Remarks -**`_alloca`** allocates *`size`* bytes from the program stack. The allocated space is automatically freed when the calling function exits (not when the allocation merely passes out of scope). Therefore, do not pass the pointer value returned by **`_alloca`** as an argument to [`free`](free.md). +**`_alloca`** allocates *`size`* bytes from the program stack. The allocated space is automatically freed when the calling function exits (not when the allocation merely passes out of scope). Therefore, don't pass the pointer value returned by **`_alloca`** as an argument to [`free`](free.md). -There are restrictions to explicitly calling **`_alloca`** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that isn't based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows NT structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **`_alloca`** in any of the following scenarios results in program failure during the return to the calling EH routine: +There are restrictions to explicitly calling **`_alloca`** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that isn't based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **`_alloca`** in any of the following scenarios results in program failure during the return to the calling EH routine: -- Windows NT SEH exception filter expression: `__except ( _alloca() )` +- Windows SEH exception filter expression: `__except ( _alloca() )` -- Windows NT SEH final exception handler: `__finally { _alloca() }` +- Windows SEH final exception handler: `__finally { _alloca() }` - C++ EH catch clause expression However, **`_alloca`** can be called directly from within an EH routine or from an application-supplied callback that gets invoked by one of the EH scenarios previously listed. > [!IMPORTANT] -> In Windows XP, if **`_alloca`** is called inside a try/catch block, you must call [`_resetstkoflw`](resetstkoflw.md) in the catch block. +> If **`_alloca`** is called inside a try block, you must call [`_resetstkoflw`](resetstkoflw.md) in the catch block. In addition to the above restrictions, when using the[`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option, **`_alloca`** can't be used in **`__except`** blocks. For more information, see [`/clr` Restrictions](../../build/reference/clr-restrictions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_alloca`**|``| +| Routine | Required header | +|---|---| +| **`_alloca`** | `` | ## Example @@ -117,7 +117,7 @@ Allocated 1000 bytes of stack at 0x0012FB50 ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`calloc`](calloc.md)\ [`malloc`](malloc.md)\ [`realloc`](realloc.md)\ diff --git a/docs/c-runtime-library/reference/amsg-exit.md b/docs/c-runtime-library/reference/amsg-exit.md index 7710315f0e..ca2e19752d 100644 --- a/docs/c-runtime-library/reference/amsg-exit.md +++ b/docs/c-runtime-library/reference/amsg-exit.md @@ -10,7 +10,7 @@ f1_keywords: ["_amsg_exit"] helpviewer_keywords: ["_amsg_exit"] ms.assetid: 146d4faf-d763-43a4-b264-12711196456b --- -# _amsg_exit +# `_amsg_exit` Emits a specified runtime error message and then exits your application with error code 255. @@ -22,15 +22,15 @@ void _amsg_exit ( int rterrnum ); ### Parameters -*rterrnum*
+*`rterrnum`*\ The identification number of a system-defined runtime error message. ## Remarks -This function emits the runtime error message to **stderr** for console applications, or displays the message in a message box for Windows applications. In debug mode, you can choose to invoke the debugger before exiting. +This function emits the runtime error message to `stderr` for console applications, or displays the message in a message box for Windows applications. In debug mode, you can choose to invoke the debugger before exiting. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_amsg_exit|internal.h| +| Routine | Required header | +|---|---| +| _amsg_exit | internal.h | diff --git a/docs/c-runtime-library/reference/and-eq.md b/docs/c-runtime-library/reference/and-eq.md index 08fc82a019..b8844704b3 100644 --- a/docs/c-runtime-library/reference/and-eq.md +++ b/docs/c-runtime-library/reference/and-eq.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["and_eq", "std.and_eq", "std::and_eq"] +f1_keywords: ["ISO646/and_eq", "and_eq", "std.and_eq", "std::and_eq"] helpviewer_keywords: ["and_eq macro"] ms.assetid: 11091772-e359-4c2b-95c6-00841ac04354 --- -# and_eq +# `and_eq` An alternative to the &= operator. diff --git a/docs/c-runtime-library/reference/and.md b/docs/c-runtime-library/reference/and.md index 99a4520eff..efa2cca286 100644 --- a/docs/c-runtime-library/reference/and.md +++ b/docs/c-runtime-library/reference/and.md @@ -1,22 +1,20 @@ --- -description: "Learn more about: and" title: "and" +description: "Learn more about: and" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["And", "std.and", "std::and"] +f1_keywords: ["ISO646/and", "and", "std.and", "std::and"] helpviewer_keywords: ["and macro"] -ms.assetid: 2644ab57-8e1b-48f0-9021-cafe3e26bdc4 --- -# and +# `and` An alternative to the && operator. ## Syntax ```C - #define and && ``` diff --git a/docs/c-runtime-library/reference/asctime-s-wasctime-s.md b/docs/c-runtime-library/reference/asctime-s-wasctime-s.md index 4ea2fcd6d8..c7762a0c8f 100644 --- a/docs/c-runtime-library/reference/asctime-s-wasctime-s.md +++ b/docs/c-runtime-library/reference/asctime-s-wasctime-s.md @@ -3,16 +3,16 @@ description: "Learn more about: asctime_s, _wasctime_s" title: "asctime_s, _wasctime_s" ms.date: "4/2/2020" api_name: ["_wasctime_s", "asctime_s", "_o__wasctime_s", "_o_asctime_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asctime_s", "_wasctime_s", "_tasctime_s"] helpviewer_keywords: ["tasctime_s function", "_tasctime_s function", "time structure conversion", "wasctime_s function", "time, converting", "_wasctime_s function", "asctime_s function"] ms.assetid: 17ad9b2b-a459-465d-976a-42822897688a --- -# asctime_s, _wasctime_s +# `asctime_s`, `_wasctime_s` -Convert a **tm** time structure to a character string. These functions are versions of [asctime, _wasctime](asctime-wasctime.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a `tm` time structure to a character string. These functions are versions of [`asctime`, `_wasctime`](asctime-wasctime.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -41,82 +41,82 @@ errno_t _wasctime_s( ### Parameters -*buffer*
-A pointer to a buffer to store the character string result. This function assumes a pointer to a valid memory location with a size specified by *numberOfElements*. +*`buffer`*\ +A pointer to a buffer to store the character string result. This function assumes a pointer to a valid memory location with a size specified by *`numberOfElements`*. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer used to store the result. -*tmSource*
-Time/date structure. This function assumes a pointer to a valid **`struct`** **tm** object. +*`tmSource`*\ +Time/date structure. This function assumes a pointer to a valid `struct tm` object. -## Return Value +## Return value -Zero if successful. If there is a failure, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the return value is an error code. Error codes are defined in ERRNO.H. For more information, see [errno Constants](../../c-runtime-library/errno-constants.md). The actual error codes returned for each error condition are shown in the following table. +Zero if successful. If there's a failure, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the return value is an error code. Error codes are defined in ERRNO.H. For more information, see [`errno` constants](../errno-constants.md). The actual error codes returned for each error condition are shown in the following table. -### Error Conditions +### Error conditions -|*buffer*|*numberOfElements*|*tmSource*|Return|Value in *buffer*| -|--------------|------------------------|----------|------------|-----------------------| -|**NULL**|Any|Any|**EINVAL**|Not modified| -|Not **NULL** (points to valid memory)|0|Any|**EINVAL**|Not modified| -|Not **NULL**|0< size < 26|Any|**EINVAL**|Empty string| -|Not **NULL**|>= 26|**NULL**|**EINVAL**|Empty string| -|Not **NULL**|>= 26|Invalid time structure or out of range values for components of the time|**EINVAL**|Empty string| +| *`buffer`* | *`numberOfElements`* | *`tmSource`* | Return | Value in *`buffer`* | +|---|---|---|---|---| +| `NULL` | Any | Any | `EINVAL` | Not modified | +| Not `NULL` (points to valid memory) | 0 | Any | `EINVAL` | Not modified | +| Not `NULL` | 0< *`numberOfElements`* < 26 | Any | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | `NULL` | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | Invalid time structure or out of range values for components of the time | `EINVAL` | Empty string | > [!NOTE] -> Error conditions for **wasctime_s** are similar to **asctime_s** with the exception that the size limit is measured in words. +> Error conditions for **`wasctime_s`** are similar to **`asctime_s`** with the exception that the size limit is measured in words. ## Remarks -The **asctime** function converts a time stored as a structure to a character string. The *tmSource* value is usually obtained from a call to **gmtime** or **localtime**. Both functions can be used to fill in a **tm** structure, as defined in TIME.H. +The `asctime` function converts a time stored as a structure to a character string. The *`tmSource`* value is typically obtained from a call to `gmtime` or `localtime`. Both functions can be used to fill in a `tm` structure, as defined in TIME.H. -|timeptr member|Value| -|--------------------|-----------| -|**tm_hour**|Hours since midnight (0-23)| -|**tm_isdst**|Positive if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST).| -|**tm_mday**|Day of month (1-31)| -|**tm_min**|Minutes after hour (0-59)| -|**tm_mon**|Month (0-11; January = 0)| -|**tm_sec**|Seconds after minute (0-59)| -|**tm_wday**|Day of week (0-6; Sunday = 0)| -|**tm_yday**|Day of year (0-365; January 1 = 0)| -|**tm_year**|Year (current year minus 1900)| +| timeptr member | Value | +|---|---| +| `tm_hour` | Hours since midnight (0-23) | +| `tm_isdst` | Positive if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST). | +| `tm_mday` | Day of month (1-31) | +| `tm_min` | Minutes after hour (0-59) | +| `tm_mon` | Month (0-11; January = 0) | +| `tm_sec` | Seconds after minute (0-59) | +| `tm_wday` | Day of week (0-6; Sunday = 0) | +| `tm_yday` | Day of year (0-365; January 1 = 0) | +| `tm_year` | Year (current year minus 1900) | -The converted character string is also adjusted according to the local time zone settings. See the [time, _time32, _time64](time-time32-time64.md), [_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md), and [localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md) functions for information about configuring the local time and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information about configuring the local time, see the [`time`, `_time32`, `_time64`](time-time32-time64.md), [`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md), and [`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md) functions. For information about defining the time zone environment and global variables, see [`_tzset`](tzset.md). -The string result produced by **asctime_s** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The new line character and the null character occupy the last two positions of the string. The value passed in as the second parameter should be at least this big. If it is less, an error code, **EINVAL**, will be returned. +The string result produced by **`asctime_s`** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The new line character and the null character occupy the last two positions of the string. The value passed in as *`numberOfElements`* should be at least this size. If it's less, an error code, `EINVAL`, will be returned. -**_wasctime_s** is a wide-character version of **asctime_s**. **_wasctime_s** and **asctime_s** behave identically otherwise. +**`_wasctime_s`** is a wide-character version of **`asctime_s`**. **`_wasctime_s`** and **`asctime_s`** behave identically otherwise. -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime_s**|**asctime_s**|**asctime_s**|**_wasctime_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tasctime_s`** | **`asctime_s`** | **`asctime_s`** | **`_wasctime_s`** | -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**asctime_s**|\| -|**_wasctime_s**|\ or \| +| Routine | Required header | +|---|---| +| **`asctime_s`** | \ | +| **`_wasctime_s`** | \ or \ | ## Security -If the buffer pointer is not **NULL** and the pointer does not point to a valid buffer, the function will overwrite whatever is at the location. This can also result in an access violation. +If the buffer pointer isn't `NULL` and the pointer doesn't point to a valid buffer, the function will overwrite whatever is at the location. This error can also result in an access violation. A [buffer overrun](/windows/win32/SecBP/avoiding-buffer-overruns) can occur if the size argument passed in is greater than the actual size of the buffer. ## Example -This program places the system time in the long integer **aclock**, translates it into the structure **newtime** and then converts it to string form for output, using the **asctime_s** function. +This program places the system time in the long integer `aclock`, translates it into the structure `newtime`, and then converts it to string form for output, using the **`asctime_s`** function. ```C // crt_asctime_s.c @@ -152,10 +152,10 @@ Current date and time: Wed May 14 15:30:17 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/asctime-wasctime.md b/docs/c-runtime-library/reference/asctime-wasctime.md index 1d66bb3cda..f08c1fbfb8 100644 --- a/docs/c-runtime-library/reference/asctime-wasctime.md +++ b/docs/c-runtime-library/reference/asctime-wasctime.md @@ -1,18 +1,18 @@ --- description: "Learn more about: asctime, _wasctime" title: "asctime, _wasctime" -ms.date: "4/2/2020" +ms.date: 12/21/2022 api_name: ["_wasctime", "asctime", "_o__wasctime", "_o_asctime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tasctime", "asctime", "_wasctime"] helpviewer_keywords: ["asctime function", "tasctime function", "wasctime function", "_tasctime function", "_wasctime function", "time structure conversion", "time, converting"] ms.assetid: 974f1727-10ff-4ed4-8cac-2eb2d681f576 --- -# asctime, _wasctime +# `asctime`, `_wasctime` -Convert a **tm** time structure to a character string. More secure versions of these functions are available; see [asctime_s, _wasctime_s](asctime-s-wasctime-s.md). +Convert a `tm` time structure to a character string. More secure versions of these functions are available; see [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md). ## Syntax @@ -27,57 +27,57 @@ wchar_t *_wasctime( ### Parameters -*timeptr*
+*`timeptr`*\ Time/date structure. -## Return Value +## Return value -**asctime** returns a pointer to the character string result; **_wasctime** returns a pointer to the wide-character string result. There is no error return value. +**`asctime`** returns a pointer to the character string result; **`_wasctime`** returns a pointer to the wide-character string result. There's no error return value. ## Remarks -More secure versions of these functions are available; see [asctime_s, _wasctime_s](asctime-s-wasctime-s.md). +More secure versions of these functions are available; see [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md). -The **asctime** function converts a time stored as a structure to a character string. The *timeptr* value is usually obtained from a call to **gmtime** or **localtime**, which both return a pointer to a **tm** structure, defined in TIME.H. +The **`asctime`** function converts a time stored as a structure to a character string. The *`timeptr`* value is typically obtained from a call to `gmtime` or `localtime`, which both return a pointer to a `tm` structure, defined in TIME.H. -|timeptr member|Value| -|--------------------|-----------| -|**tm_hour**|Hours since midnight (0-23)| -|**tm_isdst**|Positive if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST).| -|**tm_mday**|Day of month (1-31)| -|**tm_min**|Minutes after hour (0-59)| -|**tm_mon**|Month (0-11; January = 0)| -|**tm_sec**|Seconds after minute (0-59)| -|**tm_wday**|Day of week (0-6; Sunday = 0)| -|**tm_yday**|Day of year (0-365; January 1 = 0)| -|**tm_year**|Year (current year minus 1900)| +| `timeptr` member | Value | +|---|---| +| `tm_hour` | Hours since midnight (0-23) | +| `tm_isdst` | Positive if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST). | +| `tm_mday` | Day of month (1-31) | +| `tm_min` | Minutes after hour (0-59) | +| `tm_mon` | Month (0-11; January = 0) | +| `tm_sec` | Seconds after minute (0-59) | +| `tm_wday` | Day of week (0-6; Sunday = 0) | +| `tm_yday` | Day of year (0-365; January 1 = 0) | +| `tm_year` | Year (current year minus 1900) | -The converted character string is also adjusted according to the local time zone settings. For information about configuring the local time, see the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime](localtime-localtime32-localtime64.md) functions and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +For information about configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For information about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. -The string result produced by **asctime** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The newline character and the null character occupy the last two positions of the string. **asctime** uses a single, statically allocated buffer to hold the return string. Each call to this function destroys the result of the previous call. +The string result produced by **`asctime`** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The newline character and the null character occupy the last two positions of the string. **`asctime`** uses a single, statically allocated buffer to hold the return string. Each call to this function destroys the result of the previous call. -**_wasctime** is a wide-character version of **asctime**. **_wasctime** and **asctime** behave identically otherwise. +**`_wasctime`** is a wide-character version of **`asctime`**, and otherwise behaves identically to **`asctime`**. -These functions validate their parameters. If *timeptr* is a null pointer, or if it contains out-of-range values, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **NULL** and sets **errno** to **EINVAL**. +These functions validate their parameters. If *`timeptr`* is a null pointer, or if it contains out-of-range values, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime**|**asctime**|**asctime**|**_wasctime**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tasctime` | **`asctime`** | **`asctime`** | **`_wasctime`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**asctime**|\| -|**_wasctime**|\ or \| +| Routine | Required header | +|---|---| +| **`asctime`** | `` | +| **`_wasctime`** | `` or `` | ## Example -This program places the system time in the long integer **aclock**, translates it into the structure **newtime** and then converts it to string form for output, using the **asctime** function. +This program places the system time in the long integer `aclock`, translates it into the structure `newtime`, and then converts it to string form for output using the **`asctime`** function. ```C // crt_asctime.c @@ -109,11 +109,11 @@ Current date and time: Sun Feb 3 11:38:58 2002 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
+[Time management](../time-management.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md) diff --git a/docs/c-runtime-library/reference/asin-asinf-asinl.md b/docs/c-runtime-library/reference/asin-asinf-asinl.md index fc1a444e13..9fbe4cda49 100644 --- a/docs/c-runtime-library/reference/asin-asinf-asinl.md +++ b/docs/c-runtime-library/reference/asin-asinf-asinl.md @@ -3,7 +3,7 @@ title: "asin, asinf, asinl" description: "API reference for asin, asinf, and asinl; which calculate the arcsine of a floating-point value." ms.date: "1/15/2021" api_name: ["asinf", "asinl", "asin", "_o_asin", "_o_asinf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asin", "asinl", "asinf"] @@ -30,32 +30,32 @@ long double asin( long double x ); // C++ only *`x`*\ Value whose arcsine is to be calculated. -## Return Value +## Return value The **`asin`** function returns the arcsine (the inverse sine function) of *`x`* in the range -π/2 to π/2 radians. By default, if *`x`* is less than -1 or greater than 1, **`asin`** returns an indefinite. -|Input|SEH exception|Matherr exception| -|-----------|-------------------|-----------------------| -|± ∞|**`INVALID`**|**`_DOMAIN`**| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| -||x|>1|**`INVALID`**|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF | `INVALID` | `_DOMAIN` | +| ± QNaN, IND | none | `_DOMAIN` | +| `|x| > 1` | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`asin`** with **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`asin`** always takes and returns a **`double`**. -If you use the `` `asin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `asin` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`asin`**, **`asinf`**, **`asinl`**|``|`` or ``| -|**`asin()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`asin`**, **`asinf`**, **`asinl`** | `` | `` or `` | +| **`asin`** macro | `` | | ## Example @@ -63,7 +63,7 @@ For more information, see [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ diff --git a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md index ae062b5df9..1c9480aac2 100644 --- a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md +++ b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md @@ -3,14 +3,14 @@ title: "asinh, asinhf, asinhl" description: "API reference for asinh, asinhf, and asinhl; which calculate the inverse hyperbolic sine of a floating-point value." ms.date: "08/31/2020" api_name: ["asinh", "asinhf", "asinhl", "_o_asinh", "_o_asinhf", "_o_asinhl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asinhf", "asinhl", "asinh"] helpviewer_keywords: ["asinh function", "asinhl function", "asinhf function"] ms.assetid: 4488babe-1a7e-44ca-8b7b-c2db0a70084f --- -# asinh, asinhf, asinhl +# `asinh`, `asinhf`, `asinhl` Calculates the inverse hyperbolic sine. @@ -28,33 +28,33 @@ long double asinh( long double x ); // C++ only ### Parameters -*x*
+*`x`*\ Floating-point value. -## Return Value +## Return value -The **asinh** functions return the inverse hyberbolic sine (arc hyperbolic sine) of *x*. This function is valid over the floating-point domain. If *x* is a quiet NaN, indefinite, or infinity, the same value is returned. +The **`asinh`** functions return the inverse hyperbolic sine (arc hyperbolic sine) of *`x`*. This function is valid over the floating-point domain. If *`x`* is a quiet NaN, indefinite, or infinity, the same value is returned. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND, INF|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND, INF | none | none | ## Remarks -When you use C++, you can call overloads of **asinh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **asinh** always takes and returns **`double`**. +When you use C++, you can call overloads of **`asinh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`asinh`** always takes and returns **`double`**. -If you use the \ `asinh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `asinh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|--------------|------------------| -|**asinh**, **asinhf**, **asinhl**|\|\ or \| -|**asinh()** macro | \ || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`asinh`**, **`asinhf`**, **`asinhl`** | \ | \ or \ | +| **asinh()** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For additional compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -86,9 +86,9 @@ asinh( 0.868671 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[acosh, acoshf, acoshl](acosh-acoshf-acoshl.md)
-[atanh, atanhf, atanhl](atanh-atanhf-atanhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ +[`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md b/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md index c7a2b5784d..d2d7395810 100644 --- a/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md +++ b/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md @@ -7,11 +7,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ASSERTE", "ASSERTE", "_ASSERT_EXPR"] helpviewer_keywords: ["debugging [CRT], using macros", "_ASSERTE macro", "macros, debugging with", "debug reporting macros", "_ASSERT macro", "_ASSERT_EXPR macro"] -ms.assetid: e98fd2a6-7f5e-4aa8-8fe8-e93490deba36 --- -# _ASSERT, _ASSERTE, _ASSERT_EXPR Macros +# `_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros -Evaluate an expression and generate a debug report when the result is **False** (debug version only). +Evaluate an expression and generate a debug report when the result is **`false`** (debug version only). ## Syntax @@ -24,47 +23,47 @@ _ASSERTE( booleanExpression ); ### Parameters -*booleanExpression*
-A scalar expression (including pointer expressions) that evaluates to nonzero (true) or 0 (false). +*`booleanExpression`*\ +A scalar expression (including pointer expressions) that evaluates to nonzero (`true`) or 0 (`false`). -*message*
+*`message`*\ A wide string to display as part of the report. ## Remarks -The **_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They are very flexible because they do not need to be enclosed in `#ifdef` statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [_DEBUG](../../c-runtime-library/debug.md) macro. **_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** are only available when **_DEBUG** is defined at compile time. When **_DEBUG** is not defined, calls to these macros are removed during preprocessing. +The `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They're flexible because they don't need to be enclosed in `#ifdef` statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [`_DEBUG`](../debug.md) macro. `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` are only available when `_DEBUG` is defined at compile time. When `_DEBUG` isn't defined, calls to these macros are removed during preprocessing. -**_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** evaluate their *booleanExpression* argument and when the result is **`false`** (0), they print a diagnostic message and call [_CrtDbgReportW](crtdbgreport-crtdbgreportw.md) to generate a debug report. The **_ASSERT** macro prints a simple diagnostic message, **_ASSERTE** includes a string representation of the failed expression in the message, and **_ASSERT_EXPR** includes the *message* string in the diagnostic message. These macros do nothing when *booleanExpression* evaluates to nonzero. +`_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` evaluate their *`booleanExpression`* argument and when the result is **`false`** (0), they print a diagnostic message and call [`_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) to generate a debug report. The `_ASSERT` macro prints a simple diagnostic message, `_ASSERTE` includes a string representation of the failed expression in the message, and `_ASSERT_EXPR` includes the *`message`* string in the diagnostic message. These macros do nothing when *`booleanExpression`* evaluates to nonzero. -**_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** invoke **_CrtDbgReportW**, which causes all output to be in wide characters. **_ASSERTE** properly prints Unicode characters in *booleanExpression* and **_ASSERT_EXPR** prints Unicode characters in *message*. +`_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` invoke `_CrtDbgReportW`, which causes all output to be in wide characters. `_ASSERTE` properly prints Unicode characters in *`booleanExpression`* and `_ASSERT_EXPR` prints Unicode characters in *`message`*. -Because the **_ASSERTE** macro specifies the failed expression, and **_ASSERT_EXPR** lets you specify a message in the generated report, they enable users to identify the problem without referring to the application source code. However, a disadvantage exists in that every *message* printed by **_ASSERT_EXPR** and every expression evaluated by **_ASSERTE** is included in the output (debug version) file of your application as a string constant. Therefore, if a large number of calls are made to **_ASSERT_EXPR** or **_ASSERTE**, these expressions can greatly increase the size of your output file. +Because the `_ASSERTE` macro specifies the failed expression, and `_ASSERT_EXPR` lets you specify a message in the generated report, they enable users to identify the problem without referring to the application source code. However, a disadvantage exists in that every *`message`* printed by `_ASSERT_EXPR` and every expression evaluated by `_ASSERTE` is included in the output (debug version) file of your application as a string constant. Therefore, if a large number of calls are made to `_ASSERT_EXPR` or `_ASSERTE`, these expressions can greatly increase the size of your output file. -Unless you specify otherwise with the [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md) functions, messages appear in a pop-up dialog box equivalent to setting: +Unless you specify otherwise with the [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions, messages appear in a pop-up dialog box equivalent to setting: ```C -_CrtSetReportMode(CRT_ASSERT, _CRTDBG_MODE_WNDW); -```` +_CrtSetReportMode(_CRT_ASSERT, _CRTDBG_MODE_WNDW); +``` -**_CrtDbgReportW** generates the debug report and determines its destination or destinations, based on the current report mode or modes and file defined for the **_CRT_ASSERT** report type. By default, assertion failures and errors are directed to a debug message window. The [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md) functions are used to define the destinations for each report type. +`_CrtDbgReportW` generates the debug report and determines its destination or destinations, based on the current report mode or modes and file defined for the `_CRT_ASSERT` report type. By default, assertion failures and errors are directed to a debug message window. The [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions are used to define the destinations for each report type. -When the destination is a debug message window and the user clicks the **Retry** button, **_CrtDbgReportW** returns 1, causing the **_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** macros to start the debugger provided that just-in-time (JIT) debugging is enabled. +When the destination is a debug message window and the user selects the **Retry** button, `_CrtDbgReportW` returns 1, causing the `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` macros to start the debugger if just-in-time (JIT) debugging is enabled. -For more information about the reporting process, see the [_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md) function. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see [Using Macros for Verification and Reporting](/visualstudio/debugger/macros-for-reporting). +For more information about the reporting process, see the [`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) function. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). -In addition to the **_ASSERT** macros, the [assert](assert-macro-assert-wassert.md) macro can be used to verify program logic. This macro is available in both the debug and release versions of the libraries. The [_RPT, _RPTF](rpt-rptf-rptw-rptfw-macros.md) debug macros are also available for generating a debug report, but they do not evaluate an expression. The **_RPT** macros generate a simple report. The **_RPTF** macros include the source file and line number where the report macro was called in the generated report. Wide character versions of these macros are available (**_RPTW**, **_RPTFW**). The wide character versions are identical to the narrow character versions except that wide character strings are used for all string parameters and output. +In addition to the `_ASSERT` macros, the [`assert`](assert-macro-assert-wassert.md) macro can be used to verify program logic. This macro is available in both the debug and release versions of the libraries. The [`_RPT`, `_RPTF`](rpt-rptf-rptw-rptfw-macros.md) debug macros are also available for generating a debug report, but they don't evaluate an expression. The `_RPT` macros generate a simple report. The `_RPTF` macros include the source file and line number where the report macro was called in the generated report. Wide character versions of these macros are available (`_RPTW`, `_RPTFW`). The wide character versions are identical to the narrow character versions except that wide character strings are used for all string parameters and output. -Although **_ASSERT_EXPR**, **_ASSERT** and **_ASSERTE** are macros and are available by including \, the application must link with a debug version of the C run-time library when **_DEBUG** is defined because these macros call other run-time functions. +Although `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` are macros and are available by including ``, the application must link with a debug version of the C run-time library when `_DEBUG` is defined because these macros call other run-time functions. ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**_ASSERT_EXPR**, **_ASSERT**, **_ASSERTE**|\| +| Macro | Required header | +|---|---| +| `_ASSERT_EXPR`, `_ASSERT`, `_ASSERTE` | `` | ## Example -In this program, calls are made to the **_ASSERT** and **_ASSERTE** macros to test the condition `string1 == string2`. If the condition fails, these macros print a diagnostic message. The **_RPT** and **_RPTF** group of macros is also exercised in this program, as an alternative to the **printf** function. +In this program, calls are made to the `_ASSERT` and `_ASSERTE` macros to test the condition `string1 == string2`. If the condition fails, these macros print a diagnostic message. The `_RPT` and `_RPTF` group of macros is also exercised in this program, as an alternative to the **`printf`** function. ```C // crt_ASSERT_macro.c @@ -140,6 +139,6 @@ crt_ASSERT_macro.c(59) : Assertion failed: p1 == p2 ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[assert Macro, _assert, _wassert](assert-macro-assert-wassert.md)
-[_RPT, _RPTF, _RPTW, _RPTFW Macros](rpt-rptf-rptw-rptfw-macros.md)
+[Debug routines](../debug-routines.md)\ +[`assert` Macro, `_assert`, `_wassert`](assert-macro-assert-wassert.md)\ +[`_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` Macros](rpt-rptf-rptw-rptfw-macros.md) diff --git a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md index 38e959d001..116c8c986c 100644 --- a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md +++ b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md @@ -10,7 +10,7 @@ f1_keywords: ["assert", "_assert", "_wassert", "assert/_wassert"] helpviewer_keywords: ["aborting programs", "assert function", "assert macro"] ms.assetid: a9ca031a-648b-47a6-bdf1-65fc7399dd40 --- -# `assert` Macro, `_assert`, `_wassert` +# `assert` macro, `_assert`, `_wassert` Evaluates an expression and, when the result is **`false`**, prints a diagnostic message and aborts the program. @@ -34,53 +34,53 @@ void _wassert( ### Parameters -*`expression`*
+*`expression`*\ A scalar expression (including pointer expressions) that evaluates to nonzero (**`true`**) or 0 (**`false`**). -*`message`*
+*`message`*\ The message to display. -*`filename`*
+*`filename`*\ The name of the source file the assertion failed in. -*`line`*
+*`line`*\ The line number in the source file of the failed assertion. ## Remarks -The `assert` macro is typically used to identify logic errors during program development. Use it to stop program execution when unexpected conditions occur by implementing the *`expression`* argument to evaluate to **`false`** only when the program is operating incorrectly. Assertion checks can be turned off at compile time by defining the macro **`NDEBUG`**. You can turn off the `assert` macro without modifying your source files by using a **`/DNDEBUG`** command-line option. You can turn off the `assert` macro in your source code by using a `#define NDEBUG` directive before `` is included. +The `assert` macro is typically used to identify logic errors during program development. Use it to stop program execution when unexpected conditions occur by implementing the *`expression`* argument to evaluate to **`false`** only when the program is operating incorrectly. Assertion checks can be turned off at compile time by defining the macro `NDEBUG`. You can turn off the `assert` macro without modifying your source files by using a **`/DNDEBUG`** command-line option. You can turn off the `assert` macro in your source code by using a `#define NDEBUG` directive before `` is included. The `assert` macro prints a diagnostic message when *`expression`* evaluates to **`false`** (0) and calls [`abort`](abort.md) to stop program execution. No action is taken if *`expression`* is **`true`** (nonzero). The diagnostic message includes the failed expression, the name of the source file and line number where the assertion failed. The diagnostic message is printed in wide (`wchar_t`) characters. Therefore, it will work as expected even if there are Unicode characters in the expression. -The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **`stderr`**. In a Windows-based application, `assert` calls the Windows [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message with three buttons: **Abort**, **Retry**, and **Ignore**. If the user clicks **Abort**, the program aborts immediately. If the user clicks **Retry**, the debugger is called and the user can debug the program if just-in-time (JIT) debugging is enabled. If the user clicks **Ignore**, the program will continue with normal execution. Clicking **Ignore** when an error condition exists can result in undefined behavior since preconditions of the calling code weren't met. +The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **`stderr`**. In a Windows-based application, `assert` calls the Windows [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message with three buttons: **Abort**, **Retry**, and **Ignore**. If the user chooses **Abort**, the program aborts immediately. If the user chooses **Retry**, the debugger is called, and the user can debug the program if just-in-time (JIT) debugging is enabled. If the user chooses **Ignore**, the program will continue with normal execution. Clicking **Ignore** when an error condition exists can result in undefined behavior since preconditions of the calling code weren't met. To override the default output behavior regardless of the app type, call [`_set_error_mode`](set-error-mode.md) to select between the output-to-stderr and display-dialog-box behavior. -After `assert` displays its message, it calls [`abort`](abort.md), which displays a dialog box with **Abort**, **Retry**, and **Ignore** buttons. [`abort`](abort.md) exits the program, so the **Retry** and **Ignore** button won't resume program execution following the `assert` call. If `assert` displayed a dialog box, the [`abort`](abort.md) dialog box isn't shown. The only time the [`abort`](abort.md) dialog box is shown is when `assert` sends its output to stderr. +After `assert` displays its message, it calls [`abort`](abort.md), which displays a dialog box with **Abort**, **Retry**, and **Ignore** buttons. [`abort`](abort.md) exits the program, so the **Retry** and **Ignore** button won't resume program execution following the `assert` call. If `assert` displayed a dialog box, the [`abort`](abort.md) dialog box isn't shown. The only time the [`abort`](abort.md) dialog box is shown, is when `assert` sends its output to stderr. As a consequence of the above behavior, a dialog box is always displayed following an `assert` call in debug mode. The behavior of each button is captured in the below table. -|Error mode|Output to `stderr` (Console/`_OUT_TO_STDERR`)|Display Dialog Box (Windows/`_OUT_TO_MSGBOX`)| -|----------|----------------|------------------| -|`Abort`|Exit immediately with exit code 3|Exit immediately with exit code 3| -|`Retry`|Break into debugger during `abort`|Break into debugger during `assert`| -|`Ignore`|Finish exiting via `abort`|Continue program as though the assert didn't fire (may result in undefined behavior since preconditions of the calling code weren't met)| +| Error mode | Output to `stderr` (Console/`_OUT_TO_STDERR`) | Display Dialog Box (Windows/`_OUT_TO_MSGBOX`) | +|---|---|---| +| `Abort` | Exit immediately with exit code 3 | Exit immediately with exit code 3 | +| `Retry` | Break into debugger during `abort` | Break into debugger during `assert` | +| `Ignore` | Finish exiting via `abort` | Continue program as though `assert` didn't fire (may result in undefined behavior since preconditions of the calling code weren't met) | -For more information about CRT debugging, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +For more information about CRT debugging, see [CRT debugging techniques](../crt-debugging-techniques.md). The `_assert` and `_wassert` functions are internal CRT functions. They help minimize the code required in your object files to support assertions. We don't recommend that you call these functions directly. -The `assert` macro is enabled in both the release and debug versions of the C run-time libraries when **`NDEBUG`** isn't defined. When **`NDEBUG`** is defined, the macro is available but doesn't evaluate its argument and has no effect. When it's enabled, the `assert` macro calls `_wassert` for its implementation. Other assertion macros, [`_ASSERT`](assert-asserte-assert-expr-macros.md), [`_ASSERTE`](assert-asserte-assert-expr-macros.md) and [`_ASSERT_EXPR`](assert-asserte-assert-expr-macros.md), are also available, but they only evaluate the expressions passed to them when the [`_DEBUG`](../../c-runtime-library/debug.md) macro has been defined and when they are in code linked with the debug version of the C run-time libraries. +The `assert` macro is enabled in both the release and debug versions of the C run-time libraries when `NDEBUG` isn't defined. When `NDEBUG` is defined, the macro is available, but doesn't evaluate its argument and has no effect. When it's enabled, the `assert` macro calls `_wassert` for its implementation. Other assertion macros, [`_ASSERT`](assert-asserte-assert-expr-macros.md), [`_ASSERTE`](assert-asserte-assert-expr-macros.md) and [`_ASSERT_EXPR`](assert-asserte-assert-expr-macros.md), are also available, but they only evaluate the expressions passed to them when the [`_DEBUG`](../debug.md) macro has been defined and when they are in code linked with the debug version of the C run-time libraries. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`assert`, `_wassert`|``| +| Routine | Required header | +|---|---| +| `assert`, `_wassert` | `` | -The signature of the `_assert` function isn't available in a header file. The signature of the `_wassert` function is only available when the **`NDEBUG`** macro isn't defined. +The signature of the `_assert` function isn't available in a header file. The signature of the `_wassert` function is only available when the `NDEBUG` macro isn't defined. ## Example @@ -135,10 +135,10 @@ If a debugger is installed, choose the **Debug** button to start the debugger, o ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`abort`](abort.md)
-[`raise`](raise.md)
-[`signal`](signal.md)
-[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md)
-[`_DEBUG`](../../c-runtime-library/debug.md)
+[Error handling](../error-handling-crt.md)\ +[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`raise`](raise.md)\ +[`signal`](signal.md)\ +[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md)\ +[`_DEBUG`](../debug.md) diff --git a/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md b/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md index 3d6bf584cd..12dab5d047 100644 --- a/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md +++ b/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md @@ -3,7 +3,7 @@ title: "atan, atanf, atanl, atan2, atan2f, atan2l" description: "API reference for atan, atanf, atanl, atan2, atan2f, and atan2l; which calculate the arctangent of a floating-point value." ms.date: "1/15/2021" api_name: ["atan2f", "atan2l", "atan2", "atanf", "atan", "atanl", "_o_atan", "_o_atan2", "_o_atan2f", "_o_atanf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["atan", "atan2l", "atan2", "atanl", "atanf", "atan2f"] @@ -38,34 +38,34 @@ long double atan2( long double y, long double x ); // C++ only *`x`*, *`y`*\ Any numbers. -## Return Value +## Return value **`atan`** returns the arctangent of *`x`* in the range -π/2 to π/2 radians. **`atan2`** returns the arctangent of *`y`*/*`x`* in the range -π to π radians. If *`x`* is 0, **`atan`** returns 0. If both parameters of **`atan2`** are 0, the function returns 0. All results are in radians. **`atan2`** uses the signs of both parameters to determine the quadrant of the return value. -|Input|SEH exception|Matherr exception| -|-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks The **`atan`** function calculates the arctangent (the inverse tangent function) of *`x`*. **`atan2`** calculates the arctangent of *`y`*/*`x`* (if *`x`* equals 0, **`atan2`** returns π/2 if *`y`* is positive, -π/2 if *`y`* is negative, or 0 if *`y`* is 0.) -If you use the `` `atan()` or `atan2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `atan` or `atan2` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. **`atan`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). Because C++ allows overloading, you can call overloads of **`atan`** and **`atan2`** that take **`float`** or **`long double`** arguments. In a C program, unless you're using the `` macro to call this function, **`atan`** and **`atan2`** always take **`double`** arguments and return a **`double`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`atan`**, **`atan2`**, **`atanf`**, **`atan2f`**, **`atanl`**, **`atan2l`**|``|`` or ``| -|**`atan()`**, **`atan2`** macros | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`atan`**, **`atan2`**, **`atanf`**, **`atan2f`**, **`atanl`**, **`atan2l`** | `` | `` or `` | +| **`atan`**, **`atan2`** macros | `` | | ## Example @@ -100,12 +100,12 @@ Arctangent of 0.500000 / 5.000000: 0.099669 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ [`_matherr`](matherr.md)\ [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md)\ [`tan`, `tanf`, `tanl`](tan-tanf-tanl.md)\ -[`_CIatan`](../../c-runtime-library/ciatan.md)\ -[`_CIatan2`](../../c-runtime-library/ciatan2.md) +[`_CIatan`](../ciatan.md)\ +[`_CIatan2`](../ciatan2.md) diff --git a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md index 5986cbb41b..b7ce5af41b 100644 --- a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md +++ b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md @@ -1,16 +1,15 @@ --- title: "atanh, atanhf, atanhl" description: "API reference for atanh, atanhf, and atanhl; which calculate the inverse hyperbolic tangent of a floating-point value." -ms.date: "08/31/2020" +ms.date: 08/31/2020 api_name: ["atanhl", "atanhf", "atanh", "_o_atanh", "_o_atanhf", "_o_atanhl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["atanhl", "atanhf", "atanh"] -helpviewer_keywords: ["atanhf function", "atanhl function", "atanh funciton"] -ms.assetid: 83a43b5b-2580-4461-854f-dc84236d9f32 +helpviewer_keywords: ["atanhf function", "atanhl function", "atanh function"] --- -# atanh, atanhf, atanhl +# `atanh`, `atanhf`, `atanhl` Calculates the inverse hyperbolic tangent. @@ -28,34 +27,34 @@ long double atanh( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **atanh** functions return the inverse hyberbolic tangent (arc hyperbolic tangent) of *x*. If *x* is greater than 1, or less than -1, **errno** is set to **EDOM** and the result is a quiet NaN. If *x* is equal to 1 or -1, a positive or negative infinity is returned, respectively, and **errno** is set to **ERANGE**. +The **`atanh`** functions return the inverse hyperbolic tangent (arc hyperbolic tangent) of *`x`*. If *`x`* is greater than 1, or less than -1, `errno` is set to `EDOM` and the result is a quiet NaN. If *`x`* is equal to 1 or -1, a positive or negative infinity is returned, respectively, and `errno` is set to `ERANGE`. -|Input|SEH Exception|**Matherr** Exception| -|-----------|-------------------|-------------------------| -|± QNAN,IND|none|none| -|*X* ≥ 1; *x* ≤ -1|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | none | +| *`X`* ≥ 1; *`x`* ≤ -1 | none | none | ## Remarks -Because C++ allows overloading, you can call overloads of **atanh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **atanh** always takes and returns **`double`**. +Because C++ allows overloading, you can call overloads of **`atanh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`atanh`** always takes and returns **`double`**. -If you use the \ `atanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `atanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**atanh**, **atanhf**, **atanhl**|\|\ or \| -|**atanh()** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`atanh`**, **`atanhf`**, **`atanhl`** | \ | \ or \ | +| **`atanh`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,9 +86,9 @@ atanh( 0.655794 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[acosh, acoshf, acoshl](acosh-acoshf-acoshl.md)
-[asinh, asinhf, asinhl](asinh-asinhf-asinhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ +[`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/atexit.md b/docs/c-runtime-library/reference/atexit.md index 7aaf1ee838..1264498d49 100644 --- a/docs/c-runtime-library/reference/atexit.md +++ b/docs/c-runtime-library/reference/atexit.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["atexit"] helpviewer_keywords: ["processing, at exit", "atexit function"] -ms.assetid: 92c156d2-8052-4e58-96dc-00128baac6f9 --- -# atexit +# `atexit` Processes the specified function at exit. @@ -24,30 +23,30 @@ int atexit( ### Parameters -*func*
+*`func`*\ Function to be called. -## Return Value +## Return value -**atexit** returns 0 if successful, or a nonzero value if an error occurs. +**`atexit`** returns 0 if successful, or a nonzero value if an error occurs. ## Remarks -The **atexit** function is passed the address of a function *func* to be called when the program terminates normally. Successive calls to **atexit** create a register of functions that are executed in last-in, first-out (LIFO) order. The functions passed to **atexit** cannot take parameters. **atexit** and **_onexit** use the heap to hold the register of functions. Thus, the number of functions that can be registered is limited only by heap memory. +The **`atexit`** function is passed the address of a function *`func`* to be called when the program terminates normally. Successive calls to **`atexit`** create a register of functions that are executed in last-in, first-out (LIFO) order. The functions passed to **`atexit`** can't take parameters. **`atexit`** and **`_onexit`** use the heap to hold the register of functions. Thus, the number of functions that can be registered is limited only by heap memory. -The code in the **atexit** function should not contain any dependency on any DLL which could have already been unloaded when the **atexit** function is called. +The code in the **`atexit`** function shouldn't contain any dependency on any DLL that could have already been unloaded when the **`atexit`** function is called. -To generate an ANSI-conformant application, use the ANSI-standard **atexit** function (rather than the similar **_onexit** function). +To generate an ANSI-conformant application, use the ANSI-standard **`atexit`** function (rather than the similar **`_onexit`** function). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**atexit**|\| +| Routine | Required header | +|---|---| +| **`atexit`** | `` | ## Example -This program pushes four functions onto the stack of functions to be executed when **atexit** is called. When the program exits, these programs are executed on a last in, first out basis. +This program pushes four functions onto the stack of functions to be executed when **`atexit`** is called. When the program exits, these programs are executed on a last in, first out basis. ```C // crt_atexit.c @@ -93,7 +92,7 @@ This is executed next. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md) diff --git a/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md b/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md index e69575f0f8..d195860120 100644 --- a/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md +++ b/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atofl title: "_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l" ms.date: "4/2/2020" api_name: ["_atoldbl", "_atoldbl_l", "_atodbl", "_atoflt", "_atoflt_l", "_atodbl_l", "_o__atodbl", "_o__atodbl_l", "_o__atoflt", "_o__atoflt_l", "_o__atoldbl", "_o__atoldbl_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_atoflt", "_atoflt_l", "atodbl_l", "atoflt_l", "_atoldbl", "_atoldbl_l", "atodbl", "_atodbl_l", "atoldbl", "atoflt", "atoldbl_l", "_atodbl"] helpviewer_keywords: ["_atodbl function", "_atoldbl_l function", "atoflt function", "atoflt_l function", "atoldbl function", "_atoldbl function", "atodbl_l function", "_atoflt_l function", "atoldbl_l function", "atodbl function", "string conversion, to floating point values", "_atoflt function", "_atodbl_l function"] ms.assetid: 2d2530f4-4bd4-42e3-8083-f2d2fbc8432a --- -# _atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l +# `_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l` -Converts a string to a double (**_atodbl**), long double (**_atoldbl**), or float (**_atoflt**). +Converts a string to a double (**`_atodbl`**), long double (**`_atoldbl`**), or float (**`_atoflt`**). ## Syntax @@ -27,34 +27,34 @@ int _atoflt_l( _CRT_FLOAT * value, const char * str, _locale_t locale ); ### Parameters -*value*
+*`value`*\ The double, long double, or float value that's produced by converting the string to a floating-point value. These values are wrapped in a structure. -*str*
+*`str`*\ The string to be parsed to convert into a floating-point value. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns 0 if successful. Possible error codes are **_UNDERFLOW** or **_OVERFLOW**, which are defined in the header file \. +Returns 0 if successful. Possible error codes are `_UNDERFLOW` or `_OVERFLOW`, which are defined in the header file \. ## Remarks -These functions convert a string to a floating-point value. The difference between these functions and the **atof** family of functions is that these functions do not generate floating-point code and do not cause hardware exceptions. Instead, error conditions are reported as error codes. +These functions convert a string to a floating-point value. The difference between these functions and the `atof` family of functions is that these functions don't generate floating-point code and don't cause hardware exceptions. Instead, error conditions are reported as error codes. -If a string does not have a valid interpretation as a floating-point value, *value* is set to zero and the return value is zero. +If a string doesn't have a valid interpretation as a floating-point value, *`value`* is set to zero, and the return value is zero. -The versions of these functions that have the **_l** suffix are identical the versions that don't have the suffix, except that they use the *locale* parameter that's passed in instead of the current thread locale. +The versions of these functions that have the `_l` suffix are identical the versions that don't have the suffix, except that they use the *`locale`* parameter that's passed in instead of the current thread locale. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**_atodbl**, **_atoldbl**, **_atoflt**

**_atodbl_l**, **_atoldbl_l**, **_atoflt_l**|\| +| Routines | Required header | +|---|---| +| **`_atodbl`**, **`_atoldbl`**, **`_atoflt`**

**`_atodbl_l`**, **`_atoldbl_l`**, **`_atoflt_l`** | \ | ## Example @@ -114,7 +114,7 @@ Return value: 3 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md b/docs/c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md index c9813eb761..ce4da9a2fb 100644 --- a/docs/c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md +++ b/docs/c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md @@ -3,7 +3,7 @@ description: "Learn more about: atof, _atof_l, _wtof, _wtof_l" title: "atof, _atof_l, _wtof, _wtof_l" ms.date: "4/2/2020" api_name: ["_wtof_l", "atof", "_atof_l", "_wtof", "_o__atof_l", "_o__wtof", "_o__wtof_l", "_o_atof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tstof", "_ttof", "atof", "stdlib/atof", "math/atof", "_atof_l", "stdlib/_atof_l", "math/_atof_l", "_wtof", "corecrt_wstdlib/_wtof", "_wtof_l", "corecrt_wstdlib/_wtof_l"] @@ -35,49 +35,49 @@ double _wtof_l( ## Parameters -*`str`*
+*`str`*\ String to be converted. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each function returns the **`double`** value produced by interpreting the input characters as a number. The return value is 0.0 if the input cannot be converted to a value of that type. +Each function returns the **`double`** value produced by interpreting the input characters as a number. The return value is 0.0 if the input can't be converted to a value of that type. -In all out-of-range cases, **`errno`** is set to **`ERANGE`**. If the parameter passed in is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return 0. +In all out-of-range cases, `errno` is set to `ERANGE`. If the parameter passed in is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return 0. ## Remarks These functions convert a character string to a double-precision, floating-point value. -The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string. +The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it can't recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string. The *`str`* argument to **`atof`** and **`_wtof`** has the following form: -[*whitespace*] [*sign*] [*digits*] [__.__*digits*] [ {**e** | **E** }[*sign*]*digits*] +[*`whitespace`*] [*`sign`*] [*`digits`*] [**`.`***`digits`*] [ {**`e`** \| **`E`** }[*`sign`*]*`digits`*] A *`whitespace`* consists of space or tab characters, which are ignored; *`sign`* is either plus (+) or minus (-); and *`digits`* are one or more decimal digits. If no digits appear before the decimal point, at least one must appear after the decimal point. The decimal digits may be followed by an exponent, which consists of an introductory letter (**`e`**, or **`E`**) and an optionally signed decimal integer. -The UCRT versions of these functions do not support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. +The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. The versions of these functions with the **`_l`** suffix are identical except that they use the *`locale`* parameter passed in instead of the current locale. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tstof`**|**`atof`**|**`atof`**|**`_wtof`**| -|**`_ttof`**|**`atof`**|**`atof`**|**`_wtof`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tstof`** | **`atof`** | **`atof`** | **`_wtof`** | +| **`_ttof`** | **`atof`** | **`atof`** | **`_wtof`** | ## Requirements -|Routine(s)|Required header| -|------------------|---------------------| -|**`atof`**, **`_atof_l`**|C: `` or `` C++: ``, ``, `` or ``| -|**`_wtof`**, **`_wtof_l`**|C: `` or `` C++: ``, `` or ``| +| Routine(s) | Required header | +|---|---| +| **`atof`**, **`_atof_l`** | C: `` or `` C++: ``, ``, `` or `` | +| **`_wtof`**, **`_wtof_l`** | C: `` or `` C++: ``, `` or `` | ## Example @@ -132,11 +132,11 @@ Function: _atof_l(" -2,309e-25", fr)) = -2.309000e-25 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[`_ecvt`](ecvt.md)
-[`_fcvt`](fcvt.md)
-[`_gcvt`](gcvt.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) diff --git a/docs/c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md b/docs/c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md index b6748cbcc5..4101aad9e3 100644 --- a/docs/c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md +++ b/docs/c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md @@ -3,7 +3,7 @@ description: "Learn more about: atoi, _atoi_l, _wtoi, _wtoi_l" title: "atoi, _atoi_l, _wtoi, _wtoi_l" ms.date: "4/2/2020" api_name: ["_wtoi", "_wtoi_l", "atoi", "_atoi_l", "_o__atoi_l", "_o__wtoi", "_o__wtoi_l", "_o_atoi"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tstoi", "_wtoi", "_ttoi", "atoi", "_atoi_l", "_wtoi_l"] @@ -35,45 +35,45 @@ int _wtoi_l( ### Parameters -*`str`*
+*`str`*\ String to be converted. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each function returns the **`int`** value produced by interpreting the input characters as a number. The return value is 0 for **`atoi`** and **`_wtoi`**, if the input cannot be converted to a value of that type. +Each function returns the **`int`** value produced by interpreting the input characters as a number. The return value is 0 for **`atoi`** and **`_wtoi`**, if the input can't be converted to a value of that type. -In the case of overflow with large negative integral values, **`LONG_MIN`** is returned. **`atoi`** and **`_wtoi`** return **`INT_MAX`** and **`INT_MIN`** on these conditions. In all out-of-range cases, **`errno`** is set to **`ERANGE`**. If the parameter passed in is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return 0. +When the functions overflow with large negative integral values, `LONG_MIN` is returned. **`atoi`** and **`_wtoi`** return `INT_MAX` and `INT_MIN` on these conditions. In all out-of-range cases, `errno` is set to `ERANGE`. If the parameter passed in is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return 0. ## Remarks -These functions convert a character string to an integer value (**`atoi`** and **`_wtoi`**). The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string. +These functions convert a character string to an integer value (**`atoi`** and **`_wtoi`**). The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it can't recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string. The *`str`* argument to **`atoi`** and **`_wtoi`** has the following form: -> [*`whitespace`*] [*`sign`*] [*`digits`*]] +> [*`whitespace`*] [*`sign`*] [*`digits`*] A *`whitespace`* consists of space or tab characters, which are ignored; *`sign`* is either plus (+) or minus (-); and *`digits`* are one or more digits. -The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tstoi`**|**`atoi`**|**`atoi`**|**`_wtoi`**| -|**`_ttoi`**|**`atoi`**|**`atoi`**|**`_wtoi`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tstoi`** | **`atoi`** | **`atoi`** | **`_wtoi`** | +| **`_ttoi`** | **`atoi`** | **`atoi`** | **`_wtoi`** | ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**`atoi`**|``| -|**`_atoi_l`**, **`_wtoi`**, **`_wtoi_l`**|`` or ``| +| Routines | Required header | +|---|---| +| **`atoi`** | `` | +| **`_atoi_l`**, **`_wtoi`**, **`_wtoi_l`** | `` or `` | ## Example @@ -125,11 +125,11 @@ Overflow condition occurred. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[`_ecvt`](ecvt.md)
-[`_fcvt`](fcvt.md)
-[`_gcvt`](gcvt.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) diff --git a/docs/c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md b/docs/c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md index 900296516c..e9b8da5a7a 100644 --- a/docs/c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md +++ b/docs/c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _atoi64, _atoi64_l, _wtoi64, _wtoi64_l" title: "_atoi64, _atoi64_l, _wtoi64, _wtoi64_l" ms.date: "4/2/2020" api_name: ["_atoi64_l", "_wtoi64", "_atoi64", "_wtoi64_l", "_o__atoi64", "_o__atoi64_l", "_o__wtoi64", "_o__wtoi64_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_atoi64", "_tstoi64", "_ttoi64", "wtoi64", "_tstoi64_l", "atoi64", "_wtoi64_l", "_wtoi64", "wtoi64_l", "_atoi64_l", "atoi64_l"] helpviewer_keywords: ["tstoi64 function", "wtoi64 function", "atoi64_l function", "_ttoi64 function", "string conversion, to integers", "wtoi64_l function", "atoi64 function", "_tstoi64 function", "_atoi64_l function", "_wtoi64_l function", "ttoi64 function", "_wtoi64 function", "_atoi64 function"] ms.assetid: 2c3e30fd-545d-4222-8364-0c5905df9526 --- -# _atoi64, _atoi64_l, _wtoi64, _wtoi64_l +# `_atoi64`, `_atoi64_l`, `_wtoi64`, `_wtoi64_l` Converts a string to a 64-bit integer. @@ -35,55 +35,55 @@ __int64 _wtoi64_l( ### Parameters -*str*
+*`str`*\ String to be converted. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each function returns the **`__int64`** value produced by interpreting the input characters as a number. The return value is 0 for **_atoi64** if the input cannot be converted to a value of that type. +Each function returns the **`__int64`** value produced by interpreting the input characters as a number. The return value is 0 for **`_atoi64`** if the input can't be converted to a value of that type. -In the case of overflow with large positive integral values, **_atoi64** returns **I64_MAX** and **I64_MIN** in the case of overflow with large negative integral values. +If the functions overflow with large positive integral values, they return `I64_MAX`. The functions return `I64_MIN` if they overflow with large negative integral values. -In all out-of-range cases, **errno** is set to **ERANGE**. If the parameter passed in is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return 0. +In all out-of-range cases, `errno` is set to `ERANGE`. If the parameter passed in is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return 0. ## Remarks These functions convert a character string to a 64-bit integer value. -The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character might be the null character ('\0' or L'\0') terminating the string. +The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it can't recognize as part of a number. This character might be the null character ('\0' or L'\0') terminating the string. -The *str* argument to **_atoi64** has the following form: +The *`str`* argument to **`_atoi64`** has the following form: -> [*whitespace*] [*sign*] [*digits*] +> [*`whitespace`*] [*`sign`*] [*`digits`*] -A *whitespace* consists of space or tab characters, which are ignored; *sign* is either plus (+) or minus (-); and *digits* are one or more digits. +A *`whitespace`* consists of space or tab characters, which are ignored; *`sign`* is either plus (+) or minus (-); and *`digits`* are one or more digits. -**_wtoi64** is identical to **_atoi64** except that it takes a wide character string as a parameter. +**`_wtoi64`** is identical to **`_atoi64`** except that it takes a wide character string as a parameter. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tstoi64**|**_atoi64**|**_atoi64**|**_wtoi64**| -|**_ttoi64**|**_atoi64**|**_atoi64**|**_wtoi64**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstoi64` | **`_atoi64`** | **`_atoi64`** | **`_wtoi64`** | +| `_ttoi64` | **`_atoi64`** | **`_atoi64`** | **`_wtoi64`** | ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**_atoi64**, **_atoi64_l**|\| -|**_wtoi64**, **_wtoi64_l**|\ or \| +| Routines | Required header | +|---|---| +| **`_atoi64`**, **`_atoi64_l`** | \ | +| **`_wtoi64`**, **`_wtoi64_l`** | \ or \ | ## Example -This program shows how numbers stored as strings can be converted to numeric values using the **_atoi64** functions. +This program shows how numbers stored as strings can be converted to numeric values using the **`_atoi64`** functions. ```C // crt_atoi64.c @@ -132,11 +132,11 @@ Overflow condition occurred. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[_ecvt](ecvt.md)
-[_fcvt](fcvt.md)
-[_gcvt](gcvt.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) diff --git a/docs/c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md b/docs/c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md index 08ba5c8b12..f724d15eaa 100644 --- a/docs/c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md +++ b/docs/c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md @@ -3,14 +3,13 @@ description: "Learn more about: atol, _atol_l, _wtol, _wtol_l" title: "atol, _atol_l, _wtol, _wtol_l" ms.date: "4/2/2020" api_name: ["atol", "_wtol_l", "_wtol", "_atol_l", "_o__atol_l", "_o__wtol", "_o__wtol_l", "_o_atol"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_atol_l", "_ttol_l", "_tstol_l", "_tstol", "_wtol", "_ttol", "_wtol_l"] helpviewer_keywords: ["tstol function", "atol function", "ttol function", "_atol_l function", "_tstol_l function", "string conversion, to integers", "_tstol function", "_ttol function", "_ttol_l function", "atol_l function", "wtol_l function", "_wtol_l function", "wtol function", "_wtol function"] -ms.assetid: cedfc21c-2d64-4e9c-bd04-bdf60b12db46 --- -# atol, _atol_l, _wtol, _wtol_l +# `atol`, `_atol_l`, `_wtol`, `_wtol_l` Convert a string to a long integer. @@ -35,53 +34,53 @@ long _wtol_l( ### Parameters -*str*
+*`str`*\ String to be converted. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each function returns the **`long`** value produced by interpreting the input characters as a number. The return value is 0L for **atol** if the input cannot be converted to a value of that type. +Each function returns the **`long`** value produced by interpreting the input characters as a number. The return value is `0L` for **`atol`** if the input can't be converted to a value of that type. -In the case of overflow with large positive integral values, **atol** returns **LONG_MAX**; in the case of overflow with large negative integral values, **LONG_MIN** is returned. In all out-of-range cases, **errno** is set to **ERANGE**. If the parameter passed in is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return 0. +If these functions overflow with large positive integral values, they return `LONG_MAX`. If the functions overflow with large negative integral values, `LONG_MIN` is returned. In all out-of-range cases, `errno` is set to `ERANGE`. If the parameter passed in is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return 0. ## Remarks -These functions convert a character string to a long integer value (**atol**). +These functions convert a character string to a long integer value (**`atol`**). -The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string. +The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it can't recognize as part of a number. This character may be the null character (`\0` or `L\0`) terminating the string. -The *str* argument to **atol** has the following form: +The *`str`* argument to **`atol`** has the following form: -> [*whitespace*] [*sign*] [*digits*]] +> [*`whitespace`*] [*`sign`*] [*`digits`*] -A *whitespace* consists of space or tab characters, which are ignored; *sign* is either plus (+) or minus (-); and *digits* are one or more digits. +A *`whitespace`* consists of space or tab characters, which are ignored; *`sign`* is either plus (`+`) or minus (`-`); and *`digits`* are one or more digits. -**_wtol** is identical to **atol** except that it takes a wide character string. +**`_wtol`** is identical to **`atol`** except that it takes a wide character string. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstol**|**atol**|**atol**|**_wtol**| -|**_ttol**|**atol**|**atol**|**_wtol**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tstol`** | **`atol`** | **`atol`** | **`_wtol`** | +| **`_ttol`** | **`atol`** | **`atol`** | **`_wtol`** | ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**atol**|\| -|**_atol_l**, **_wtol**, **_wtol_l**|\ and \| +| Routines | Required header | +|---|---| +| **`atol`** | `` | +| **`_atol_l`**, **`_wtol`**, **`_wtol_l`** | `` and `` | ## Example -This program shows how numbers stored as strings can be converted to numeric values using the **atol** function. +This program shows how numbers stored as strings can be converted to numeric values using the **`atol`** function. ```C // crt_atol.c @@ -130,11 +129,11 @@ Overflow condition occurred. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[_ecvt](ecvt.md)
-[_fcvt](fcvt.md)
-[_gcvt](gcvt.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) diff --git a/docs/c-runtime-library/reference/atoll-atoll-l-wtoll-wtoll-l.md b/docs/c-runtime-library/reference/atoll-atoll-l-wtoll-wtoll-l.md index 229e4666de..aca7caf8bd 100644 --- a/docs/c-runtime-library/reference/atoll-atoll-l-wtoll-wtoll-l.md +++ b/docs/c-runtime-library/reference/atoll-atoll-l-wtoll-wtoll-l.md @@ -3,14 +3,14 @@ description: "Learn more about: atoll, _atoll_l, _wtoll, _wtoll_l" title: "atoll, _atoll_l, _wtoll, _wtoll_l" ms.date: "4/2/2020" api_name: ["_wtoll", "_atoll_l", "_wtoll_l", "atoll", "_o__atoll_l", "_o__wtoll", "_o__wtoll_l", "_o_atoll"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tstoll_l", "_wtoll", "_atoll_l", "_ttoll", "_tstoll", "_wtoll_l", "atoll"] helpviewer_keywords: ["atoll function", "_wtoll_l function", "_wtoll function", "_atoll_l function"] ms.assetid: 5e85fcac-b351-4882-bff2-6e7c469b7fa8 --- -# atoll, _atoll_l, _wtoll, _wtoll_l +# `atoll`, `_atoll_l`, `_wtoll`, `_wtoll_l` Converts a string to a **`long long`** integer. @@ -35,56 +35,56 @@ long long _wtoll_l( ### Parameters -*str*
+*`str`*\ String to be converted. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each function returns the **`long long`** value that's produced by interpreting the input characters as a number. The return value for **atoll** is 0 if the input cannot be converted to a value of that type. +Each function returns the **`long long`** value that's produced by interpreting the input characters as a number. The return value for **`atoll`** is 0 if the input can't be converted to a value of that type. -For overflow with large positive integral values, **atoll** returns **LLONG_MAX**, and for overflow with large negative integral values, it returns **LLONG_MIN**. +For overflow with large positive integral values, **`atoll`** returns `LLONG_MAX`, and for overflow with large negative integral values, it returns `LLONG_MIN`. -In all out-of-range cases, **errno** is set to **ERANGE**. If the parameter that's passed in is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return 0. +In all out-of-range cases, `errno` is set to `ERANGE`. If the parameter that's passed in is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return 0. ## Remarks These functions convert a character string to a **`long long`** integer value. -The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character might be the null character ('\0' or L'\0') that terminates the string. +The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it can't recognize as part of a number. This character might be the null character ('\0' or L'\0') that terminates the string. -The *str* argument to **atoll** has the following form: +The *`str`* argument to **`atoll`** has the following form: -> [*whitespace*] [*sign*] [*digits*] +> [*`whitespace`*] [*`sign`*] [*`digits`*] -A *whitespace* consists of space or tab characters, which are ignored; *sign* is either plus (+) or minus (-); and *digits* are one or more digits. +A *`whitespace`* consists of space or tab characters, which are ignored; *`sign`* is either plus (+) or minus (-); and *`digits`* are one or more digits. -**_wtoll** is identical to **atoll** except that it takes a wide character string as a parameter. +**`_wtoll`** is identical to **`atoll`** except that it takes a wide character string as a parameter. -The versions of these functions that have the **_l** suffix are identical to the versions that don't have it, except that they use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix are identical to the versions that don't have it, except that they use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tstoll**|**atoll**|**atoll**|**_wtoll**| -|**_tstoll_l**|**_atoll_l**|**_atoll_l**|**_wtoll_l**| -|**_ttoll**|**_atoll**|**_atoll**|**_wtoll**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstoll` | **`atoll`** | **`atoll`** | **`_wtoll`** | +| `_tstoll_l` | **`_atoll_l`** | **`_atoll_l`** | **`_wtoll_l`** | +| `_ttoll` | **`_atoll`** | **`_atoll`** | **`_wtoll`** | ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**atoll**, **_atoll_l**|\| -|**_wtoll**, **_wtoll_l**|\ or \| +| Routines | Required header | +|---|---| +| **`atoll`**, **`_atoll_l`** | \ | +| **`_wtoll`**, **`_wtoll_l`** | \ or \ | ## Example -This program shows how to use the **atoll** functions to convert numbers stored as strings to numeric values. +This program shows how to use the **`atoll`** functions to convert numbers stored as strings to numeric values. ```C // crt_atoll.c @@ -134,11 +134,11 @@ Overflow condition occurred. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Locale](../../c-runtime-library/locale.md)
-[_ecvt](ecvt.md)
-[_fcvt](fcvt.md)
-[_gcvt](gcvt.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Locale](../locale.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) diff --git a/docs/c-runtime-library/reference/beginthread-beginthreadex.md b/docs/c-runtime-library/reference/beginthread-beginthreadex.md index 15e33dbbd8..3f7043ca25 100644 --- a/docs/c-runtime-library/reference/beginthread-beginthreadex.md +++ b/docs/c-runtime-library/reference/beginthread-beginthreadex.md @@ -3,7 +3,7 @@ description: "Learn more about: _beginthread, _beginthreadex" title: "_beginthread, _beginthreadex" ms.date: "4/2/2020" api_name: ["_beginthread", "_beginthreadex", "_o__beginthread", "_o__beginthreadex"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["beginthread", "_beginthread", "beginthreadex", "_beginthreadex"] @@ -47,41 +47,41 @@ uintptr_t _beginthreadex( // MANAGED CODE ### Parameters -*`start_address`*
-Start address of a routine that begins execution of a new thread. For **`_beginthread`**, the calling convention is either [`__cdecl`](../../cpp/cdecl.md) (for native code) or [`__clrcall`](../../cpp/clrcall.md) (for managed code); for **`_beginthreadex`**, it is either [`__stdcall`](../../cpp/stdcall.md) (for native code) or [`__clrcall`](../../cpp/clrcall.md) (for managed code). +*`start_address`*\ +Start address of a routine that begins execution of a new thread. For **`_beginthread`**, the calling convention is either [`__cdecl`](../../cpp/cdecl.md) (for native code) or [`__clrcall`](../../cpp/clrcall.md) (for managed code). For **`_beginthreadex`**, the calling convention is either [`__stdcall`](../../cpp/stdcall.md) (for native code) or [`__clrcall`](../../cpp/clrcall.md) (for managed code). -*`stack_size`*
+*`stack_size`*\ Stack size for a new thread, or 0. -*`arglist`*
-Argument list to be passed to a new thread, or **`NULL`**. +*`arglist`*\ +Argument list to be passed to a new thread, or `NULL`. -*`Security`*
-Pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that determines whether the returned handle can be inherited by child processes. If *`Security`* is **`NULL`**, the handle cannot be inherited. Must be **`NULL`** for Windows 95 applications. +*`Security`*\ +Pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that determines whether the returned handle can be inherited by child processes. If *`Security`* is `NULL`, the handle can't be inherited. -*`initflag`*
-Flags that control the initial state of a new thread. Set *`initflag`* to 0 to run immediately, or to **`CREATE_SUSPENDED`** to create the thread in a suspended state; use [`ResumeThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-resumethread) to execute the thread. Set *`initflag`* to **`STACK_SIZE_PARAM_IS_A_RESERVATION`** flag to use *`stack_size`* as the initial reserve size of the stack in bytes; if this flag is not specified, *`stack_size`* specifies the commit size. +*`initflag`*\ +Flags that control the initial state of a new thread. Set *`initflag`* to 0 to run immediately, or to `CREATE_SUSPENDED` to create the thread in a suspended state; use [`ResumeThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-resumethread) to execute the thread. Set *`initflag`* to `STACK_SIZE_PARAM_IS_A_RESERVATION` flag to use *`stack_size`* as the initial reserve size of the stack in bytes; if this flag isn't specified, *`stack_size`* specifies the commit size. -*`thrdaddr`*
-Points to a 32-bit variable that receives the thread identifier. If it's **`NULL`**, it's not used. +*`thrdaddr`*\ +Points to a 32-bit variable that receives the thread identifier. If it's `NULL`, it's not used. -## Return Value +## Return value -If successful, each of these functions returns a handle to the newly created thread; however, if the newly created thread exits too quickly, **`_beginthread`** might not return a valid handle. (See the discussion in the Remarks section.) On an error, **`_beginthread`** returns -1L, and **`errno`** is set to **`EAGAIN`** if there are too many threads, to **`EINVAL`** if the argument is invalid or the stack size is incorrect, or to **`EACCES`** if there are insufficient resources (such as memory). On an error, **`_beginthreadex`** returns 0, and **`errno`** and **`_doserrno`** are set. +If successful, each of these functions returns a handle to the newly created thread; however, if the newly created thread exits too quickly, **`_beginthread`** might not return a valid handle. (See the discussion in the Remarks section.) On an error, **`_beginthread`** returns -1L, and `errno` is set to `EAGAIN` if there are too many threads, to `EINVAL` if the argument is invalid or the stack size is incorrect, or to `EACCES` if there are insufficient resources (such as memory). On an error, **`_beginthreadex`** returns 0, and `errno` and **`_doserrno`** are set. -If *`start_address`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. +If *`start_address`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For more information about **`uintptr_t`**, see [Standard Types](../../c-runtime-library/standard-types.md). +For more information about **`uintptr_t`**, see [Standard types](../standard-types.md). ## Remarks -The **`_beginthread`** function creates a thread that begins execution of a routine at *`start_address`*. The routine at *`start_address`* must use the **`__cdecl`** (for native code) or **`__clrcall`** (for managed code) calling convention and should have no return value. When the thread returns from that routine, it is terminated automatically. For more information about threads, see [Multithreading Support for Older Code (Visual C++)](../../parallel/multithreading-support-for-older-code-visual-cpp.md). +The **`_beginthread`** function creates a thread that begins execution of a routine at *`start_address`*. The routine at *`start_address`* must use the **`__cdecl`** (for native code) or **`__clrcall`** (for managed code) calling convention and should have no return value. When the thread returns from that routine, it's terminated automatically. For more information about threads, see [Multithreading support for older code (Visual C++)](../../parallel/multithreading-support-for-older-code-visual-cpp.md). **`_beginthreadex`** resembles the Win32 [`CreateThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createthread) API more closely than **`_beginthread`** does. **`_beginthreadex`** differs from **`_beginthread`** in the following ways: -- **`_beginthreadex`** has three additional parameters: *`initflag`*, *`Security`*, and **`threadaddr`**. The new thread can be created in a suspended state, with a specified security, and can be accessed by using *`thrdaddr`*, which is the thread identifier. +- **`_beginthreadex`** has three more parameters: *`initflag`*, *`Security`*, and **`threadaddr`**. The new thread can be created in a suspended state, with a specified security, and can be accessed by using *`thrdaddr`*, which is the thread identifier. - The routine at *`start_address`* that's passed to **`_beginthreadex`** must use the **`__stdcall`** (for native code) or **`__clrcall`** (for managed code) calling convention and must return a thread exit code. @@ -89,39 +89,39 @@ The **`_beginthread`** function creates a thread that begins execution of a rout - A thread that's created by using **`_beginthreadex`** is terminated by a call to [`_endthreadex`](endthread-endthreadex.md). -The **`_beginthreadex`** function gives you more control over how the thread is created than **`_beginthread`** does. The **`_endthreadex`** function is also more flexible. For example, with **`_beginthreadex`**, you can use security information, set the initial state of the thread (running or suspended), and get the thread identifier of the newly created thread. You can also use the thread handle that's returned by **`_beginthreadex`** with the synchronization APIs, which you cannot do with **`_beginthread`**. +The **`_beginthreadex`** function gives you more control over how the thread is created than **`_beginthread`** does. The **`_endthreadex`** function is also more flexible. For example, with **`_beginthreadex`**, you can use security information, set the initial state of the thread (running or suspended), and get the thread identifier of the newly created thread. You can also use the thread handle that's returned by **`_beginthreadex`** with the synchronization APIs, which you can't do with **`_beginthread`**. -It's safer to use **`_beginthreadex`** than **`_beginthread`**. If the thread that's generated by **`_beginthread`** exits quickly, the handle that's returned to the caller of **`_beginthread`** might be invalid or point to another thread. However, the handle that's returned by **`_beginthreadex`** has to be closed by the caller of **`_beginthreadex`**, so it is guaranteed to be a valid handle if **`_beginthreadex`** did not return an error. +**`_beginthreadex`** is safer to use than **`_beginthread`**. If the thread that's generated by **`_beginthread`** exits quickly, the handle that's returned to the caller of **`_beginthread`** might be invalid or point to another thread. However, the handle that's returned by **`_beginthreadex`** has to be closed by the caller of **`_beginthreadex`**, so it's guaranteed to be a valid handle if **`_beginthreadex`** didn't return an error. You can call [`_endthread`](endthread-endthreadex.md) or **`_endthreadex`** explicitly to terminate a thread; however, **`_endthread`** or **`_endthreadex`** is called automatically when the thread returns from the routine that's passed as a parameter. Terminating a thread with a call to **`_endthread`** or **`_endthreadex`** helps ensure correct recovery of resources that are allocated for the thread. -**`_endthread`** automatically closes the thread handle, whereas **`_endthreadex`** does not. Therefore, when you use **`_beginthread`** and **`_endthread`**, do not explicitly close the thread handle by calling the Win32 [`CloseHandle`](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. This behavior differs from the Win32 [`ExitThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API. +**`_endthread`** automatically closes the thread handle, whereas **`_endthreadex`** doesn't. Therefore, when you use **`_beginthread`** and **`_endthread`**, don't explicitly close the thread handle by calling the Win32 [`CloseHandle`](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. This behavior differs from the Win32 [`ExitThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API. > [!NOTE] -> For an executable file linked with Libcmt.lib, do not call the Win32 **`ExitThread`** API so that you don't prevent the run-time system from reclaiming allocated resources. **`_endthread`** and **`_endthreadex`** reclaim allocated thread resources and then call **`ExitThread`**. +> For an executable file linked with Libcmt.lib, do not call the Win32 `ExitThread` API so that you don't prevent the run-time system from reclaiming allocated resources. **`_endthread`** and **`_endthreadex`** reclaim allocated thread resources and then call `ExitThread`. The operating system handles the allocation of the stack when either **`_beginthread`** or **`_beginthreadex`** is called; you don't have to pass the address of the thread stack to either of these functions. In addition, the *`stack_size`* argument can be 0, in which case the operating system uses the same value as the stack that's specified for the main thread. -*`arglist`* is a parameter to be passed to the newly created thread. Typically, it is the address of a data item, such as a character string. *`arglist`* can be **`NULL`** if it is not needed, but **`_beginthread`** and **`_beginthreadex`** must be given some value to pass to the new thread. All threads are terminated if any thread calls [`abort`](abort.md), **`exit`**, **`_exit`**, or **`ExitProcess`**. +*`arglist`* is a parameter to be passed to the newly created thread. Typically, it's the address of a data item, such as a character string. *`arglist`* can be `NULL` if it isn't needed, but **`_beginthread`** and **`_beginthreadex`** must be given some value to pass to the new thread. All threads are terminated if any thread calls [`abort`](abort.md), **`exit`**, **`_exit`**, or `ExitProcess`. -The locale of the new thread is initialized by using the per-process global current locale info. If per-thread locale is enabled by a call to [`_configthreadlocale`](configthreadlocale.md) (either globally or for new threads only), the thread can change its locale independently from other threads by calling **`setlocale`** or **`_wsetlocale`**. Threads that don't have the per-thread locale flag set can affect the locale info in all other threads that also don't have the per-thread locale flag set, as well as all newly-created threads. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale of the new thread is initialized by using the per-process global current locale info. If per-thread locale is enabled by a call to [`_configthreadlocale`](configthreadlocale.md) (either globally or for new threads only), the thread can change its locale independently from other threads by calling **`setlocale`** or **`_wsetlocale`**. Threads that don't have the per-thread locale flag set can affect the locale info in all other threads that also don't have the per-thread locale flag set, and also all newly created threads. For more information, see [Locale](../locale.md). -For **`/clr`** code, **`_beginthread`** and **`_beginthreadex`** each have two overloads. One takes a native calling-convention function pointer, and the other takes a **`__clrcall`** function pointer. The first overload is not application domain-safe and never will be. If you are writing **`/clr`** code you must ensure that the new thread enters the correct application domain before it accesses managed resources. You can do this, for example, by using [`call_in_appdomain` Function](../../dotnet/call-in-appdomain-function.md). The second overload is application domain-safe; the newly created thread will always end up in the application domain of the caller of **`_beginthread`** or **`_beginthreadex`**. +For **`/clr`** code, **`_beginthread`** and **`_beginthreadex`** each have two overloads. One takes a native calling-convention function pointer, and the other takes a **`__clrcall`** function pointer. The first overload isn't application domain-safe and never will be. If you're writing **`/clr`** code, you must ensure that the new thread enters the correct application domain before it accesses managed resources. You can do so, for example, by using [`call_in_appdomain`](../../dotnet/call-in-appdomain-function.md). The second overload is application domain-safe; the newly created thread will always end up in the application domain of the caller of **`_beginthread`** or **`_beginthreadex`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_beginthread`**|``| -|**`_beginthreadex`**|``| +| Routine | Required header | +|---|---| +| **`_beginthread`** | `` | +| **`_beginthreadex`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Multithreaded versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Multithreaded versions of the [C run-time libraries](../crt-library-features.md) only. To use **`_beginthread`** or **`_beginthreadex`**, the application must link with one of the multithreaded C run-time libraries. @@ -245,7 +245,7 @@ void Bounce( void * parg ) Press any key to end the sample application. -The following sample code demonstrates how you can use the thread handle that's returned by **`_beginthreadex`** with the synchronization API [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject). The main thread waits for the second thread to terminate before it continues. When the second thread calls **`_endthreadex`**, it causes its thread object to go to the signaled state. This allows the primary thread to continue running. This cannot be done with **`_beginthread`** and **`_endthread`**, because **`_endthread`** calls **`CloseHandle`**, which destroys the thread object before it can be set to the signaled state. +The following sample code demonstrates how you can use the thread handle that's returned by **`_beginthreadex`** with the synchronization API [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject). The main thread waits for the second thread to terminate before it continues. When the second thread calls **`_endthreadex`**, it causes its thread object to go to the signaled state, which allows the primary thread to continue running. It can't be done with **`_beginthread`** and **`_endthread`**, because **`_endthread`** calls `CloseHandle`, which destroys the thread object before it can be set to the signaled state. ```cpp // crt_begthrdex.cpp @@ -295,7 +295,7 @@ Counter should be 1000000; it is-> 1000000 ## See also -- [Process and Environment Control](../../c-runtime-library/process-and-environment-control.md) +- [Process and environment control](../process-and-environment-control.md) - [`_endthread`, `_endthreadex`](endthread-endthreadex.md) - [`abort`](abort.md) - [`exit`, `_Exit`, `_exit`](exit-exit-exit.md) diff --git a/docs/c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md b/docs/c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md index f67141b8af..8bd895a262 100644 --- a/docs/c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md +++ b/docs/c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md @@ -3,14 +3,14 @@ description: "Learn more about: Bessel Functions: _j0, _j1, _jn, _y0, _y1, _yn" title: "Bessel Functions: _j0, _j1, _jn, _y0, _y1, _yn" ms.date: "4/2/2020" api_name: ["_j0", "_j1", "_jn", "_y0", "_y1", "_yn", "_o__j0", "_o__j1", "_o__jn", "_o__y0", "_o__y1", "_o__yn"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["c.bessel", "_j0", "_j1", "_jn", "_y0", "_y1", "_yn"] helpviewer_keywords: ["Bessel functions", "_j0 function", "_j1 function", "_jn function", "_y0 function", "_y1 function", "_yn function"] ms.assetid: a21a8bf1-df9d-4ba0-a8c2-e7ef71921d96 --- -# Bessel Functions: _j0, _j1, _jn, _y0, _y1, _yn +# Bessel functions: `_j0`, `_j1`, `_jn`, `_y0`, `_y1`, `_yn` Computes the Bessel function of the first or second kind, of orders 0, 1, or n. The Bessel functions are commonly used in the mathematics of electromagnetic wave theory. @@ -41,41 +41,41 @@ double _yn( ### Parameters -*x*
+*`x`*\ Floating-point value. -*n*
+*`n`*\ Integer order of Bessel function. -## Return Value +## Return value -Each of these routines returns a Bessel function of *x*. If *x* is negative in the **_y0**, **_y1**, or **_yn** functions, the routine sets **errno** to **EDOM**, prints a **_DOMAIN** error message to **stderr**, and returns **_HUGE_VAL**. You can modify error handling by using **_matherr**. +Each of these routines returns a Bessel function of *`x`*. If *`x`* is negative in the **`_y0`**, **`_y1`**, or **`_yn`** functions, the routine sets `errno` to `EDOM`, prints a `_DOMAIN` error message to `stderr`, and returns `HUGE_VAL`. You can modify error handling by using `_matherr`. ## Remarks -The **_j0**, **_j1**, and **_jn** routines return Bessel functions of the first kind: orders 0, 1, and n, respectively. +The **`_j0`**, **`_j1`**, and **`_jn`** routines return Bessel functions of the first kind: orders 0, 1, and n, respectively. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **QNAN**, **IND**|**INVALID**|**_DOMAIN**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | `INVALID` | `_DOMAIN` | -The **_y0**, **_y1**, and **_yn** routines return Bessel functions of the second kind: orders 0, 1, and n, respectively. +The **`_y0`**, **`_y1`**, and **`_yn`** routines return Bessel functions of the second kind: orders 0, 1, and n, respectively. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **QNAN**, **IND**|**INVALID**|**_DOMAIN**| -|± 0|**ZERODIVIDE**|**_SING**| -||x| < 0.0|**INVALID**|**_DOMAIN**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | `INVALID` | `_DOMAIN` | +| ± 0 | `ZERODIVIDE` | `_SING` | +| `|x| < 0.0` | `INVALID` | `_DOMAIN` | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_j0**, **_j1**, **_jn**, **_y0**, **_y1**, **_yn**|\ (C++), \ (C, C++)| +| Routine | Required header | +|---|---| +| **`_j0`**, **`_j1`**, **`_jn`**, **`_y0`**, **`_y1`**, **`_yn`** | \ (C++), \ (C, C++) | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -120,5 +120,5 @@ Bessel functions for x = 2.387000: ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_matherr](matherr.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_matherr`](matherr.md) diff --git a/docs/c-runtime-library/reference/bitand.md b/docs/c-runtime-library/reference/bitand.md index 3b0d220683..0701824a21 100644 --- a/docs/c-runtime-library/reference/bitand.md +++ b/docs/c-runtime-library/reference/bitand.md @@ -1,22 +1,20 @@ --- -description: "Learn more about: bitand" title: "bitand" +description: "Learn more about: bitand" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::bitand", "std.bitand", "bitand"] +f1_keywords: ["std::bitand", "std.bitand", "ISO646/bitand", "bitand"] helpviewer_keywords: ["bitand function"] -ms.assetid: 279cf9b5-fac1-49de-b329-f1a31b3481fe --- -# bitand +# `bitand` An alternative to the & operator. ## Syntax ```C - #define bitand & ``` diff --git a/docs/c-runtime-library/reference/bitor.md b/docs/c-runtime-library/reference/bitor.md index 92ed622d22..8f2aaf236d 100644 --- a/docs/c-runtime-library/reference/bitor.md +++ b/docs/c-runtime-library/reference/bitor.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: bitor" title: "bitor" +description: "Learn more about: bitor" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["bitor", "std.bitor", "std::bitor"] +f1_keywords: ["ISO646/bitor", "bitor", "std.bitor", "std::bitor"] helpviewer_keywords: ["bitor function"] -ms.assetid: 3c0a3711-9c74-41f2-b400-2f7797da30d1 --- -# bitor +# `bitor` -An alternative to the | operator. +An alternative to the `|` operator. ## Syntax ```C - #define bitor | ``` ## Remarks -The macro yields the operator |. +The macro yields the operator `|`. ## Example diff --git a/docs/c-runtime-library/reference/bsearch-s.md b/docs/c-runtime-library/reference/bsearch-s.md index 14c061f1a2..fd7664e758 100644 --- a/docs/c-runtime-library/reference/bsearch-s.md +++ b/docs/c-runtime-library/reference/bsearch-s.md @@ -3,16 +3,16 @@ description: "Learn more about: bsearch_s" title: "bsearch_s" ms.date: "4/2/2020" api_name: ["bsearch_s", "_o_bsearch_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["bsearch_s"] helpviewer_keywords: ["arrays [CRT], binary search", "bsearch_s function"] ms.assetid: d5690d5e-6be3-4f1d-aa0b-5ca6dbded276 --- -# bsearch_s +# `bsearch_s` -Performs a binary search of a sorted array. This function is a version of [bsearch](bsearch.md) with security enhancements as described in [Security features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Performs a binary search of a sorted array. This function is a version of [`bsearch`](bsearch.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -29,64 +29,64 @@ void *bsearch_s( ### Parameters -*key*\ +*`key`*\ Pointer to the key to search for. -*base*\ +*`base`*\ Pointer to the base of the search data. -*number*\ +*`number`*\ Number of elements. -*width*\ +*`width`*\ Width of elements. -*compare*\ -Callback function that compares two elements. The first argument is the *context* pointer. The second argument is a pointer to the *key* for the search. The third argument is a pointer to the array element to be compared with *key*. +*`compare`*\ +Callback function that compares two elements. The first argument is the *`context`* pointer. The second argument is a pointer to the *`key`* for the search. The third argument is a pointer to the array element to be compared with *`key`*. -*context*\ +*`context`*\ A pointer to an object that can be accessed in the comparison function. ## Return value -**bsearch_s** returns a pointer to an occurrence of *key* in the array pointed to by *base*. If *key* is not found, the function returns **NULL**. If the array is not in ascending sort order or contains duplicate records with identical keys, the result is unpredictable. +**`bsearch_s`** returns a pointer to an occurrence of *`key`* in the array pointed to by *`base`*. If *`key`* isn't found, the function returns `NULL`. If the array isn't in ascending sort order or contains duplicate records with identical keys, the result is unpredictable. -If invalid parameters are passed to the function, it invokes the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If invalid parameters are passed to the function, it invokes the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ### Error conditions -|*key*|*base*|*compare*|*number*|*width*|**`errno`** value| -|-|-|-|-|-|-| -|**NULL**|any|any|any|any|**EINVAL**| -|any|**NULL**|any|!= 0|any|**EINVAL**| -|any|any|any|any|= 0|**EINVAL**| -|any|any|**NULL**|an|any|**EINVAL**| +| *`key`* | *`base`* | *`compare`* | *`number`* | *`width`* | `errno` value | +|---|---|---|---|---|---| +| `NULL` | any | any | any | any | `EINVAL` | +| any | `NULL` | any | != 0 | any | `EINVAL` | +| any | any | any | any | = 0 | `EINVAL` | +| any | any | `NULL` | an | any | `EINVAL` | ## Remarks -The **bsearch_s** function performs a binary search of a sorted array of *number* elements, each of *width* bytes in size. The *base* value is a pointer to the base of the array to be searched, and *key* is the value being sought. The *compare* parameter is a pointer to a user-supplied routine that compares the requested key to an array element and returns one of the following values specifying their relationship: +The **`bsearch_s`** function performs a binary search of a sorted array of *`number`* elements, each of *`width`* bytes in size. The *`base`* value is a pointer to the base of the array to be searched, and *`key`* is the value being sought. The *`compare`* parameter is a pointer to a user-supplied routine that compares the requested key to an array element and returns one of the following values specifying their relationship: -|Value returned by *compare* routine|Description| -|-----------------------------------------|-----------------| -|\< 0|Key is less than array element.| -|0|Key is equal to array element.| -|> 0|Key is greater than array element.| +| Value returned by *`compare`* routine | Description | +|---|---| +| \< 0 | Key is less than array element. | +| 0 | Key is equal to array element. | +| > 0 | Key is greater than array element. | -The *context* pointer may be useful if the searched data structure is part of an object, and the compare function needs to access members of the object. The *compare* function may cast the void pointer into the appropriate object type and access members of that object. The addition of the *context* parameter makes **bsearch_s** more secure since additional context may be used to avoid reentrancy bugs associated with using static variables to make data available to the *compare* function. +The *`context`* pointer may be useful if the searched data structure is part of an object, and the compare function needs to access members of the object. The *`compare`* function may cast the void pointer into the appropriate object type and access members of that object. The addition of the *`context`* parameter makes **`bsearch_s`** more secure, since the context may be used to avoid reentrancy bugs associated with using static variables to make data available to the *`compare`* function. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**bsearch_s**|\ and \| +| Routine | Required header | +|---|---| +| **`bsearch_s`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program sorts a string array with [qsort_s](qsort-s.md), and then uses bsearch_s to find the word "cat". +This program sorts a string array with [`qsort_s`](qsort-s.md), and then uses bsearch_s to find the word "cat". ```cpp // crt_bsearch_s.cpp @@ -172,7 +172,7 @@ cat found at 002F0F04 ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)\ -[_lfind](lfind.md)\ -[_lsearch](lsearch.md)\ -[qsort](qsort.md) +[Searching and sorting](../searching-and-sorting.md)\ +[`_lfind`](lfind.md)\ +[`_lsearch`](lsearch.md)\ +[`qsort`](qsort.md) diff --git a/docs/c-runtime-library/reference/bsearch.md b/docs/c-runtime-library/reference/bsearch.md index 5e66543035..36d5695dc0 100644 --- a/docs/c-runtime-library/reference/bsearch.md +++ b/docs/c-runtime-library/reference/bsearch.md @@ -3,16 +3,16 @@ description: "Learn more about: bsearch" title: "bsearch" ms.date: "4/2/2020" api_name: ["bsearch", "_o_bsearch"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["bsearch"] helpviewer_keywords: ["arrays [CRT], binary search", "bsearch function"] ms.assetid: e0ad2f47-e7dd-49ed-8288-870457a14a2c --- -# bsearch +# `bsearch` -Performs a binary search of a sorted array. A more secure version of this function is available; see [bsearch_s](bsearch-s.md). +Performs a binary search of a sorted array. A more secure version of this function is available; see [`bsearch_s`](bsearch-s.md). ## Syntax @@ -28,46 +28,46 @@ void *bsearch( ### Parameters -*key*\ +*`key`*\ Pointer to the key to search for. -*base*\ +*`base`*\ Pointer to the base of the search data. -*number*\ +*`number`*\ Number of elements. -*width*\ +*`width`*\ Width of elements. -*compare*\ +*`compare`*\ Callback function that compares two elements. The first is a pointer to the key for the search, and the second is a pointer to the array element to be compared with the key. ## Return value -**bsearch** returns a pointer to an occurrence of *key* in the array pointed to by *base*. If *key* is not found, the function returns **NULL**. If the array is not in ascending sort order or contains duplicate records with identical keys, the result is unpredictable. +**`bsearch`** returns a pointer to an occurrence of *`key`* in the array pointed to by *`base`*. If *`key`* isn't found, the function returns `NULL`. If the array isn't in ascending sort order or contains duplicate records with identical keys, the result is unpredictable. ## Remarks -The **bsearch** function performs a binary search of a sorted array of *number* elements, each of *width* bytes in size. The *base* value is a pointer to the base of the array to be searched, and *key* is the value being sought. The *compare* parameter is a pointer to a user-supplied routine that compares the requested key to an array element. It returns one of the following values that specify their relationship: +The **`bsearch`** function performs a binary search of a sorted array of *`number`* elements, each of *`width`* bytes in size. The *`base`* value is a pointer to the base of the array to be searched, and *`key`* is the value being sought. The *`compare`* parameter is a pointer to a user-supplied routine that compares the requested key to an array element. It returns one of the following values that specify their relationship: -|Value returned by *compare* routine|Description| -|-----------------------------------------|-----------------| -|`< 0`|Key is less than array element.| -|`0`|Key is equal to array element.| -|`> 0`|Key is greater than array element.| +| Value returned by *`compare`* routine | Description | +|---|---| +| `< 0` | Key is less than array element. | +| `0` | Key is equal to array element. | +| `> 0` | Key is greater than array element. | -This function validates its parameters. If *compare*, *key* or *number* is **NULL**, or if *base* is **NULL** and *number* is nonzero, or if *width* is zero, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to `EINVAL` and the function returns **NULL**. +This function validates its parameters. If *`compare`*, *`key`* or *`number`* is `NULL`, or if *`base`* is `NULL` and *`number`* is nonzero, or if *`width`* is zero, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**bsearch**|\ and \| +| Routine | Required header | +|---|---| +| **`bsearch`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,7 +116,7 @@ cat found at 002F0F04 ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)\ -[_lfind](lfind.md)\ -[_lsearch](lsearch.md)\ -[qsort](qsort.md) +[Searching and sorting](../searching-and-sorting.md)\ +[`_lfind`](lfind.md)\ +[`_lsearch`](lsearch.md)\ +[`qsort`](qsort.md) diff --git a/docs/c-runtime-library/reference/btowc.md b/docs/c-runtime-library/reference/btowc.md index 738d84be12..4913551e2d 100644 --- a/docs/c-runtime-library/reference/btowc.md +++ b/docs/c-runtime-library/reference/btowc.md @@ -3,14 +3,14 @@ description: "Learn more about: btowc" title: "btowc" ms.date: "4/2/2020" api_name: ["btowc", "_o_btowc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["btowc"] helpviewer_keywords: ["btowc function"] ms.assetid: 99a46e02-6f86-4569-af79-5feca012add8 --- -# btowc +# `btowc` Determine whether an integer represents a valid single-byte character in the initial shift state. @@ -24,25 +24,25 @@ wint_t btowc( ### Parameters -*character*
+*`character`*\ Integer to test. -## Return Value +## Return value -Returns the wide-character representation of the character if the integer represents a valid single-byte character in the initial shift state. Returns WEOF if the integer is EOF or is not a valid single-byte character in the initial shift state. The output of this function is affected by the current **LC_TYPE** locale. +Returns the wide-character representation of the character if the integer represents a valid single-byte character in the initial shift state. Returns `WEOF` if the integer is `EOF` or isn't a valid single-byte character in the initial shift state. The output of this function is affected by the current `LC_TYPE` locale. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**btowc**|\ or \| +| Routine | Required header | +|---|---| +| **`btowc`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
+[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md) diff --git a/docs/c-runtime-library/reference/byteswap-uint64-byteswap-ulong-byteswap-ushort.md b/docs/c-runtime-library/reference/byteswap-uint64-byteswap-ulong-byteswap-ushort.md index 463ebcdf0a..88af49e8eb 100644 --- a/docs/c-runtime-library/reference/byteswap-uint64-byteswap-ulong-byteswap-ushort.md +++ b/docs/c-runtime-library/reference/byteswap-uint64-byteswap-ulong-byteswap-ushort.md @@ -24,18 +24,18 @@ unsigned __int64 _byteswap_uint64 ( unsigned __int64 val ); ### Parameters -*`val`*
+*`val`*\ The integer to reverse byte order. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_byteswap_ushort`**|``| -|**`_byteswap_ulong`**|``| -|**`_byteswap_uint64`**|``| +| Routine | Required header | +|---|---| +| **`_byteswap_ushort`** | `` | +| **`_byteswap_ulong`** | `` | +| **`_byteswap_uint64`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -54,10 +54,10 @@ int main() ``` ```Output -byteswap of 102030405060708 = 807060504030201 -byteswap of 1020304 = 4030201 +byteswap of 0102030405060708 = 0807060504030201 +byteswap of 01020304 = 04030201 ``` ## See also -[Universal C runtime routines by category](../../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](../run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md b/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md index e80e6f6a3a..8e6069ca3c 100644 --- a/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md +++ b/docs/c-runtime-library/reference/c16rtomb-c32rtomb1.md @@ -10,7 +10,7 @@ f1_keywords: ["c16rtomb", "c32rtomb", "uchar/c16rtomb", "uchar/c32rtomb"] helpviewer_keywords: ["c16rtomb function", "c32rtomb function"] ms.assetid: 7f5743ca-a90e-4e3f-a310-c73e16f4e14d --- -# c16rtomb, c32rtomb +# `c16rtomb`, `c32rtomb` Convert a UTF-16 or UTF-32 wide character into a UTF-8 multibyte character. @@ -31,36 +31,36 @@ size_t c32rtomb( ### Parameters -*mbchar*\ +*`mbchar`*\ Pointer to an array to store the converted UTF-8 multibyte character. -*wchar*\ +*`wchar`*\ A wide character to convert. -*state*\ -A pointer to an **mbstate_t** object. +*`state`*\ +A pointer to an `mbstate_t` object. ## Return value -The number of bytes stored in array object *mbchar*, including any shift sequences. If *wchar* isn't a valid wide character, the value (**size_t**)(-1) is returned, **errno** is set to **EILSEQ**, and the value of *state* is unspecified. +The number of bytes stored in array object *`mbchar`*, including any shift sequences. If *`wchar`* isn't a valid wide character, the value (`size_t`)(-1) is returned, `errno` is set to `EILSEQ`, and the value of *`state`* is unspecified. ## Remarks -The **c16rtomb** function converts the UTF-16 LE character *wchar* to the equivalent UTF-8 multibyte narrow character sequence. If *mbchar* isn't a null pointer, the function stores the converted sequence in the array object pointed to by *mbchar*. Up to **MB_CUR_MAX** bytes are stored in *mbchar*, and *state* is set to the resulting multibyte shift state. +The **`c16rtomb`** function converts the UTF-16 LE character *`wchar`* to the equivalent UTF-8 multibyte narrow character sequence. If *`mbchar`* isn't a null pointer, the function stores the converted sequence in the array object pointed to by *`mbchar`*. Up to `MB_CUR_MAX` bytes are stored in *`mbchar`*, and *`state`* is set to the resulting multibyte shift state. -If *wchar* is a null wide character, a sequence required to restore the initial shift state is stored, if needed, followed by the null character. *state* is set to the initial conversion state. The **c32rtomb** function is identical, but converts a UTF-32 character. +If *`wchar`* is a null wide character, a sequence required to restore the initial shift state is stored, if needed, followed by the null character. *`state`* is set to the initial conversion state. The **`c32rtomb`** function is identical, but converts a UTF-32 character. -If *mbchar* is a null pointer, the behavior is equivalent to a call to the function that substitutes an internal buffer for *mbchar* and a wide null character for *wchar*. +If *`mbchar`* is a null pointer, the behavior is equivalent to a call to the function that substitutes an internal buffer for *`mbchar`* and a wide null character for *`wchar`*. -The *state* conversion state object allows you to make subsequent calls to this function and other restartable functions that maintain the shift state of the multibyte output characters. Results are undefined when you mix the use of restartable and non-restartable functions. +The *`state`* conversion state object allows you to make subsequent calls to this function and other restartable functions that maintain the shift state of the multibyte output characters. Results are undefined when you mix the use of restartable and non-restartable functions. -To convert UTF-16 characters into non-UTF-8 multibyte characters, use the [wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md), [wcstombs_s, or _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md) functions. +To convert UTF-16 characters into non-UTF-8 multibyte characters, use the [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md), [wcstombs_s, or _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md) functions. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**c16rtomb**, **c32rtomb**|C, C++: \| +| Routine | Required header | +|---|---| +| **`c16rtomb`**, **`c32rtomb`** | C, C++: \ | For compatibility information, see [Compatibility](../compatibility.md). @@ -69,6 +69,6 @@ For compatibility information, see [Compatibility](../compatibility.md). [Data conversion](../data-conversion.md)\ [Locale](../locale.md)\ [Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ -[mbrtoc16, mbrtoc32](mbrtoc16-mbrtoc323.md)\ -[wcrtomb](wcrtomb.md)\ -[wcrtomb_s](wcrtomb-s.md) +[`mbrtoc16`, `mbrtoc32`](mbrtoc16-mbrtoc323.md)\ +[`wcrtomb`](wcrtomb.md)\ +[`wcrtomb_s`](wcrtomb-s.md) diff --git a/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md b/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md index 8e6c845d36..dbac4dbb89 100644 --- a/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md +++ b/docs/c-runtime-library/reference/cabs-cabsf-cabsl.md @@ -10,7 +10,7 @@ f1_keywords: ["cabs", "cabsf", "cabsl", "complex/cabs", "complex/cabsf", "comple helpviewer_keywords: ["cabs function", "cabsf function", "cabsl function"] ms.assetid: 6b8eb453-cc8f-4972-bebf-351cbdfdfc15 --- -# cabs, cabsf, cabsl +# `cabs`, `cabsf`, `cabsl` Retrieves the absolute value of a complex number. @@ -36,31 +36,31 @@ long double cabsl( ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The absolute value of *z*. +The absolute value of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **cabs** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, **cabs** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`cabs`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, **`cabs`** always takes a `_Dcomplex` value and returns a **`double`** value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cabs**, **cabsf**, **cabsl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`cabs`**, **`cabsf`**, **`cabsl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md) diff --git a/docs/c-runtime-library/reference/cabs.md b/docs/c-runtime-library/reference/cabs.md index 88e992d916..1569031df9 100644 --- a/docs/c-runtime-library/reference/cabs.md +++ b/docs/c-runtime-library/reference/cabs.md @@ -3,14 +3,14 @@ description: "Learn more about: _cabs" title: "_cabs" ms.date: "4/2/2020" api_name: ["_cabs", "_o__cabs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_cabs"] helpviewer_keywords: ["cabs function", "absolute values", "_cabs function", "calculating absolute values"] ms.assetid: fea292ee-1a39-4a0a-b416-4a189346ff26 --- -# _cabs +# `_cabs` Calculates the absolute value of a complex number. @@ -24,26 +24,26 @@ double _cabs( ### Parameters -*z*
+*`z`*\ Complex number. -## Return Value +## Return value -**_cabs** returns the absolute value of its argument if successful. On overflow, **_cabs** returns **HUGE_VAL** and sets **errno** to **ERANGE**. You can change error handling with [_matherr](matherr.md). +**`_cabs`** returns the absolute value of its argument if successful. On overflow, **`_cabs`** returns `HUGE_VAL` and sets `errno` to `ERANGE`. You can change error handling with [`_matherr`](matherr.md). ## Remarks -The **_cabs** function calculates the absolute value of a complex number, which must be a structure of type [_complex](../../c-runtime-library/standard-types.md). The structure *z* is composed of a real component *x* and an imaginary component *y*. A call to **_cabs** produces a value equivalent to that of the expression `sqrt( z.x * z.x + z.y * z.y )`. +The **`_cabs`** function calculates the absolute value of a complex number, which must be a structure of type [`_complex`](../standard-types.md). The structure *`z`* is composed of a real component *`x`* and an imaginary component *`y`*. A call to **`_cabs`** produces a value equivalent to that of the expression `sqrt( z.x * z.x + z.y * z.y )`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cabs**|\| +| Routine | Required header | +|---|---| +| **`_cabs`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -72,6 +72,6 @@ The absolute value of 3.000000 + 4.000000i is 5.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[abs, labs, llabs, _abs64](abs-labs-llabs-abs64.md)
-[fabs, fabsf, fabsl](fabs-fabsf-fabsl.md) +[Math and floating-point support](../floating-point-support.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md) diff --git a/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md b/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md index c6b4b12f7c..661b09887c 100644 --- a/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md +++ b/docs/c-runtime-library/reference/cacos-cacosf-cacosl.md @@ -10,7 +10,7 @@ f1_keywords: ["cacos", "cacosf", "cacosl", "complex/cacos", "complex/cacosf", "c helpviewer_keywords: ["cacos function", "cacosf function", "cacosl function"] ms.assetid: 78118c00-0a07-49c1-8a13-4bf19ce3aea8 --- -# cacos, cacosf, cacosl +# `cacos`, `cacosf`, `cacosl` Retrieves the arccosine of a complex number, with branch cuts outside the interval [-1, +1] along the real axis. @@ -29,37 +29,37 @@ _Lcomplex cacos( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The arccosine of *z*, in radians. The result is unbounded along the imaginary axis, and in the in the interval [0, π] along the real axis. A domain error will occur if *z* is outside the interval [-1, +1]. +The arc cosine of *`z`*, in radians. The result is unbounded along the imaginary axis, and bounded in the interval [0, π] along the real axis. A domain error will occur if *`z`* is outside the interval [-1, +1]. ## Remarks -Because C++ allows overloading, you can call overloads of **cacos** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **cacos** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`cacos`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`cacos`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cacos**, **cacosf**, **cacosl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`cacos`**, **`cacosf`**, **`cacosl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md b/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md index 893b6560c0..f9f0c7198b 100644 --- a/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md +++ b/docs/c-runtime-library/reference/cacosh-cacoshf-cacoshl.md @@ -10,9 +10,9 @@ f1_keywords: ["cacosh", "cacoshf", "cacoshl", "complex/cacosh", "complex/cacoshf helpviewer_keywords: ["cacosh function", "cacoshf function", "cacoshl function"] ms.assetid: 83fd05eb-3587-4741-9be6-589a830a1703 --- -# cacosh, cacoshf, cacoshl +# `cacosh`, `cacoshf`, `cacoshl` -Retrieves the inverse hyperbolic cosine of a complex number with a branch cut at values less than 1 along the real axis. . +Retrieves the inverse hyperbolic cosine of a complex number with a branch cut at values less than 1 along the real axis. ## Syntax @@ -36,37 +36,37 @@ _Lcomplex cacoshl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The inverse hyperbolic cosine of *z*, in radians. The result is unbounded and non-negative along the real axis, and in the interval [-iπ, +iπ] along the imaginary axis. +The inverse hyperbolic cosine of *`z`*, in radians. The result is unbounded and non-negative along the real axis, and in the interval [-iπ, +iπ] along the imaginary axis. ## Remarks -Because C++ allows overloading, you can call overloads of **cacosh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **cacosh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`cacosh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`cacosh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cacosh**, **cacoshf**, **cacoshl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`cacosh`**, **`cacoshf`**, **`cacoshl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/callnewh.md b/docs/c-runtime-library/reference/callnewh.md index 17a5bcf3e7..150693becc 100644 --- a/docs/c-runtime-library/reference/callnewh.md +++ b/docs/c-runtime-library/reference/callnewh.md @@ -3,16 +3,16 @@ description: "Learn more about: _callnewh" title: "_callnewh" ms.date: "4/2/2020" api_name: ["_callnewh", "_o__callnewh"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_callnewh"] helpviewer_keywords: ["_callnewh"] ms.assetid: 4dcb73e9-6384-4d12-a973-a8807d4de7a8 --- -# _callnewh +# `_callnewh` -Calls the currently installed *new handler*. +Calls the currently installed *`new` handler*. ## Syntax @@ -24,33 +24,33 @@ int _callnewh( ### Parameters -*size*
-The amount of memory that the [new operator](../../cpp/new-operator-cpp.md) tried to allocate. +*`size`*\ +The amount of memory that the [`new` operator](../../cpp/new-operator-cpp.md) tried to allocate. -## Return Value +## Return value -|Value|Description| -|-----------|-----------------| -|0|Failure: Either no new handler is installed or no new handler is active.| -|1|Success: The new handler is installed and active. The memory allocation can be retried.| +| Value | Description | +|---|---| +| 0 | Failure: Either no `new` handler is installed or no `new` handler is active. | +| 1 | Success: The `new` handler is installed and active. The memory allocation can be retried. | ## Exceptions -This function throws [bad_alloc](../../standard-library/bad-alloc-class.md) if the *new handler* can’t be located. +This function throws [`bad_alloc`](../../standard-library/bad-alloc-class.md) if the *`new` handler* can't be located. ## Remarks -The *new handler* is called if the [new operator](../../cpp/new-operator-cpp.md) fails to successfully allocate memory. The new handler might then initiate some appropriate action, such as freeing memory so that subsequent allocations succeed. +The *`new` handler* is called if the [`new` operator](../../cpp/new-operator-cpp.md) fails to successfully allocate memory. The `new` handler might then initiate some appropriate action, such as freeing memory so that subsequent allocations succeed. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_callnewh|internal.h| +| Routine | Required header | +|---|---| +| `_callnewh` | internal.h | ## See also -[_set_new_handler](set-new-handler.md)
-[_set_new_mode](set-new-mode.md)
+[`_set_new_handler`](set-new-handler.md)\ +[`_set_new_mode`](set-new-mode.md) diff --git a/docs/c-runtime-library/reference/calloc-dbg.md b/docs/c-runtime-library/reference/calloc-dbg.md index 6606142a00..fbff456b61 100644 --- a/docs/c-runtime-library/reference/calloc-dbg.md +++ b/docs/c-runtime-library/reference/calloc-dbg.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _calloc_dbg" title: "_calloc_dbg" +description: "Learn more about: _calloc_dbg" ms.date: "11/04/2016" api_name: ["_calloc_dbg"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_calloc_dbg", "calloc_dbg"] helpviewer_keywords: ["_calloc_dbg function", "calloc_dbg function"] -ms.assetid: 7f62c42b-eb9f-4de5-87d0-df57036c87de --- -# _calloc_dbg +# `_calloc_dbg` -Allocates a number of memory blocks in the heap with additional space for a debugging header and overwrite buffers (debug version only). +Allocates memory blocks in the heap with extra space for a debugging header and overwrite buffers (debug version only). ## Syntax @@ -28,52 +27,52 @@ void *_calloc_dbg( ### Parameters -*number*
+*`number`*\ Requested number of memory blocks. -*size*
+*`size`*\ Requested size of each memory block (bytes). -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -For information about the allocation block types and how they are used, see[Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -*filename*
-Pointer to name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where allocation operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_calloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_calloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function returns a pointer to the user portion of the last allocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the Remarks section. For more information about how the new handler function is used, see the [calloc](calloc.md) function. +On successful completion, this function returns a pointer to the user portion of the last allocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the Remarks section. For more information about how the new handler function is used, see the [`calloc`](calloc.md) function. ## Remarks -**_calloc_dbg** is a debug version of the [calloc](calloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_calloc_dbg** is reduced to a call to **calloc**. Both **calloc** and **_calloc_dbg** allocate *number* memory blocks in the base heap, but **_calloc_dbg** offers several debugging features: +**`_calloc_dbg`** is a debug version of the [`calloc`](calloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_calloc_dbg`** is reduced to a call to `calloc`. Both `calloc` and **`_calloc_dbg`** allocate *`number`* memory blocks in the base heap, but **`_calloc_dbg`** offers several debugging features: - Buffers on either side of the user portion of the block to test for leaks. - A block type parameter to track specific allocation types. -- *filename*/*linenumber* information to determine the origin of allocation requests. +- *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_calloc_dbg** allocates each memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_calloc_dbg`** allocates each memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_calloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails; **EINVAL** is returned if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_calloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails; `EINVAL` is returned if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function versus its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the differences between calling a standard heap function and the debug version, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_calloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_calloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,7 +99,7 @@ int main( void ) else printf( "Problem allocating memory\n" ); - / _free_dbg must be called to free CLIENT type blocks + // _free_dbg must be called to free CLIENT type blocks free( bufferN ); _free_dbg( bufferC, _CLIENT_BLOCK ); } @@ -112,7 +111,7 @@ Allocated memory successfully ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[calloc](calloc.md)
-[_malloc_dbg](malloc-dbg.md)
-[_DEBUG](../../c-runtime-library/debug.md)
+[Debug routines](../debug-routines.md)\ +[`calloc`](calloc.md)\ +[`_malloc_dbg`](malloc-dbg.md)\ +[`_DEBUG`](../debug.md) diff --git a/docs/c-runtime-library/reference/calloc.md b/docs/c-runtime-library/reference/calloc.md index 89d666d8d4..eda1a8195f 100644 --- a/docs/c-runtime-library/reference/calloc.md +++ b/docs/c-runtime-library/reference/calloc.md @@ -3,7 +3,7 @@ title: "calloc" description: The C runtime library function calloc allocates zero-initialized memory. ms.date: "4/2/2020" api_name: ["calloc", "_o_calloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["calloc"] @@ -30,15 +30,15 @@ Number of elements. *`size`*\ Length in bytes of each element. -## Return Value +## Return value -**`calloc`** returns a pointer to the allocated space. The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. +**`calloc`** returns a pointer to the allocated space. The storage space pointed to by the return value is suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. ## Remarks The **`calloc`** function allocates storage space for an array of *`number`* elements, each of length *`size`* bytes. Each element is initialized to 0. -**`calloc`** sets **`errno`** to **`ENOMEM`** if a memory allocation fails or if the amount of memory requested exceeds **`_HEAP_MAXREQ`**. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`calloc`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). In the Microsoft implementation, if *`number`* or *`size`* is zero, **`calloc`** returns a pointer to an allocated block of non-zero size. An attempt to read or write through the returned pointer leads to undefined behavior. @@ -48,21 +48,21 @@ In the Microsoft implementation, if *`number`* or *`size`* is zero, **`calloc`** _set_new_mode(1); ``` -early in your program, or link with *`NEWMODE.OBJ`* (see [Link Options](../../c-runtime-library/link-options.md)). +early in your program, or link with *`NEWMODE.OBJ`* (see [Link options](../link-options.md)). -When the application is linked with a debug version of the C run-time libraries, **`calloc`** resolves to [`_calloc_dbg`](calloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`calloc`** resolves to [`_calloc_dbg`](calloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). **`calloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`calloc`**|`` and ``| +| Routine | Required header | +|---|---| +| **`calloc`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -93,7 +93,7 @@ Allocated 40 long integers ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`free`](free.md)\ [`malloc`](malloc.md)\ -[`realloc`](realloc.md)\ +[`realloc`](realloc.md) diff --git a/docs/c-runtime-library/reference/carg-cargf-cargl.md b/docs/c-runtime-library/reference/carg-cargf-cargl.md index 1a9276224b..0635b71a2e 100644 --- a/docs/c-runtime-library/reference/carg-cargf-cargl.md +++ b/docs/c-runtime-library/reference/carg-cargf-cargl.md @@ -10,7 +10,7 @@ f1_keywords: ["carg", "cargf", "cargl", "complex/carg", "complex/cargf", "comple helpviewer_keywords: ["carg function", "cargf function", "cargl function"] ms.assetid: 610d6a93-b929-46ab-a966-b77db0b804be --- -# carg, cargf, cargl +# `carg`, `cargf`, `cargl` Retrieves the argument of a complex number, with a branch cut along the negative real axis. @@ -37,34 +37,34 @@ long double cargl( ### Parameters -*z*\ +*`z`*\ A complex number. -## Return Value +## Return value -The argument (also known as the phase) of *z*. The result is in the interval [-π, +π]. +The argument (also known as the phase) of *`z`*. The result is in the interval [-π, +π]. ## Remarks -Because C++ allows overloading, you can call overloads of **carg** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **carg** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`carg`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`carg`** always takes a `_Dcomplex` value and returns a **`double`** value. -If you use the \ `carg()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `carg()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**carg**, **cargf**, **cargl**|\|\| -|**carg** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`carg`**, **`cargf`**, **`cargl`** | \ | \ | +| **`carg`** macro | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/casin-casinf-casinl.md b/docs/c-runtime-library/reference/casin-casinf-casinl.md index 1fdfb8f66e..e6e24b16ab 100644 --- a/docs/c-runtime-library/reference/casin-casinf-casinl.md +++ b/docs/c-runtime-library/reference/casin-casinf-casinl.md @@ -10,7 +10,7 @@ f1_keywords: ["casin", "casinf", "casinl", "complex/casin", "complex/casinf", "c helpviewer_keywords: ["casin function", "casinf function", "casinl function"] ms.assetid: b75d1455-7b1e-43b0-bd46-c530be190be9 --- -# casin, casinf, casinl +# `casin`, `casinf`, `casinl` Retrieves the arcsine of a complex number, with branch cuts outside the interval [-1, +1] along the real axis. @@ -36,37 +36,37 @@ _Lcomplex casinl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The arcsine of *z*, in radians. The result is unbounded along the imaginary axis, and in the interval [-π/2, +π/2] along the real axis. +The arcsine of *`z`*, in radians. The result is unbounded along the imaginary axis, and in the interval [-π/2, +π/2] along the real axis. ## Remarks -Because C++ allows overloading, you can call overloads of **casin** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **casin** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`casin`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`casin`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**casin**, **casinf**, **casinl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`casin`**, **`casinf`**, **`casinl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md b/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md index 3a54c18b37..8065bac92c 100644 --- a/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md +++ b/docs/c-runtime-library/reference/casinh-casinhf-casinhl.md @@ -10,7 +10,7 @@ f1_keywords: ["casinh", "casinhf", "casinhl", "complex/casinh", "complex/casinhf helpviewer_keywords: ["casinh function", "casinhf function", "casinhl function"] ms.assetid: bd18340b-21dd-4c86-a14e-e8e15dd97e3b --- -# casinh, casinhf, casinhl +# `casinh`, `casinhf`, `casinhl` Retrieves the inverse hyperbolic sine of a complex number, with branch cuts outside the interval [-i, +i] along the imaginary axis. @@ -36,37 +36,37 @@ _Lcomplex casinhl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The inverse hyperbolic sine of *z*, in radians. The result is unbound along the real axis, and in the interval [-iπ/2, +iπ/2] along the imaginary axis. +The inverse hyperbolic sine of *`z`*, in radians. The result is unbound along the real axis, and in the interval [-iπ/2, +iπ/2] along the imaginary axis. ## Remarks -Because C++ allows overloading, you can call overloads of **casinh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **casinh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`casinh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`casinh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**casinh**, **casinhf**, **casinhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`casinh`**, **`casinhf`**, **`casinhl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/catan-catanf-catanl.md b/docs/c-runtime-library/reference/catan-catanf-catanl.md index ea8eae0d28..aa7746b3a8 100644 --- a/docs/c-runtime-library/reference/catan-catanf-catanl.md +++ b/docs/c-runtime-library/reference/catan-catanf-catanl.md @@ -10,7 +10,7 @@ f1_keywords: ["catan", "catanf", "catanl", "complex/catan", "complex/catanf", "c helpviewer_keywords: ["catan function", "catanf function", "catanl function"] ms.assetid: 8415ed9c-7909-4d08-b532-4630bafdc7e8 --- -# catan, catanf, catanl +# `catan`, `catanf`, `catanl` Retrieves the arctangent of a complex number with branch cuts outside the interval [-1; +1] along the imaginary axis. @@ -29,37 +29,37 @@ _Lcomplex catan( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The arctangent of *z*, in radians. The result is unbounded along the imaginary axis, and in the interval [-π/2; +π/2] along the real axis. +The arctangent of *`z`*, in radians. The result is unbounded along the imaginary axis, and in the interval [-π/2; +π/2] along the real axis. ## Remarks -Because C++ allows overloading, you can call overloads of **catan** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **catan** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`catan`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`catan`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**catan**, **catanf**, **catanl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`catan`**, **`catanf`**, **`catanl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md b/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md index 848f83820f..97b1628a26 100644 --- a/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md +++ b/docs/c-runtime-library/reference/catanh-catanhf-catanhl.md @@ -10,7 +10,7 @@ f1_keywords: ["catanh", "catanhf", "catanhl", "complex/catanh", "complex/catanhf helpviewer_keywords: ["catanh function", "catanhf function", "catanhl function"] ms.assetid: 1b6021cb-647a-41b4-9d7f-919cc8b57b86 --- -# catanh, catanhf, catanhl +# `catanh`, `catanhf`, `catanhl` Retrieves the inverse hyperbolic tangent of a complex number, with branch cuts outside the interval [-1; +1] along the real axis. @@ -36,37 +36,37 @@ _Lcomplex catanhl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The inverse hyperbolic tangent of *z*, in radians. The result is unbounded along the real axis, and in the interval [-iπ/2; +iπ/2] along the imaginary axis. A domain error will occur if *z* is outside the interval [-1, +1]. A pole error will occur if *z* is -1 or +1. +The inverse hyperbolic tangent of *`z`*, in radians. The result is unbounded along the real axis, and in the interval [-iπ/2; +iπ/2] along the imaginary axis. A domain error will occur if *`z`* is outside the interval [-1, +1]. A pole error will occur if *`z`* is -1 or +1. ## Remarks -Because C++ allows overloading, you can call overloads of **catanh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **catanh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`catanh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`catanh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**catanh**, **catanhf**, **catanhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`catanh`**, **`catanhf`**, **`catanhl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md b/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md index ed378c8eac..930c3fcaad 100644 --- a/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md +++ b/docs/c-runtime-library/reference/cbrt-cbrtf-cbrtl.md @@ -3,14 +3,14 @@ title: "cbrt, cbrtf, cbrtl" description: "API reference for cbrt, cbrtf, and cbrtl; which calculate a cube root" ms.date: "9/1/2020" api_name: ["cbrt", "cbrtf", "cbrtl", "_o_cbrt", "_o_cbrtf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cbrtl", "cbrt", "cbrtf"] helpviewer_keywords: ["cbrtl function", "cbrtf function", "cbrt function"] ms.assetid: ab51d916-3db2-4beb-b46a-28b4062cd33f --- -# cbrt, cbrtf, cbrtl +# `cbrt`, `cbrtf`, `cbrtl` Calculates the cube root. @@ -37,33 +37,33 @@ long double cbrtl( ### Parameters -*x*\ +*`x`*\ Floating-point value -## Return Value +## Return value -The **cbrt** functions return the cube-root of *x*. +The **`cbrt`** functions return the cube-root of *`x`*. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | none | ## Remarks -Because C++ allows overloading, you can call overloads of **cbrt** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **cbrt** always takes and returns **`double`**. +Because C++ allows overloading, you can call overloads of **`cbrt`** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`cbrt`** always takes and returns **`double`**. -If you use the \ `cbrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `cbrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**cbrt**, **cbrtf**, **cbrtl**|\|\| -|**cbrt** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`cbrt`**, **`cbrtf`**, **`cbrtl`** | \ | \ | +| **`cbrt`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,7 +91,7 @@ The cube root of -64.64 is -4.013289 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[exp, expf, expl](exp-expf.md)
-[log, logf, log10, log10f](log-logf-log10-log10f.md)
-[pow, powf, powl](pow-powf-powl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ +[`pow`, `powf`, `powl`](pow-powf-powl.md) diff --git a/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md b/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md index bb78a4e87b..54a1feffe8 100644 --- a/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md +++ b/docs/c-runtime-library/reference/cbuild-fcbuild-lcbuild.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["_Cbuild", "_FCbuild", "_LCbuild", "complex/_Cbuild", "complex/_FCbuild", "complex/_LCbuild"] helpviewer_keywords: ["_Cbuild function", "_FCbuild function", "_LCbuild function"] --- -# _Cbuild, _FCbuild, _LCbuild +# `_Cbuild`, `_FCbuild`, `_LCbuild` Constructs a complex number from real and imaginary parts. @@ -23,37 +23,37 @@ _Lcomplex _LCbuild( long double real, long double imaginary ); ### Parameters -*real*
+*`real`*\ The real part of the complex number to construct. -*imaginary*
+*`imaginary`*\ The imaginary part of the complex number to construct. -## Return Value +## Return value -A **_Dcomplex**, **_Fcomplex**, or **_Lcomplex** structure that represents the complex number (*real*, *imaginary* \* i) for values of the specified floating-point type. +A `_Dcomplex`, `_Fcomplex`, or `_Lcomplex` structure that represents the complex number (*`real`*, *`imaginary`* \* i) for values of the specified floating-point type. ## Remarks -The **_Cbuild**, **_FCbuild**, and **_LCbuild** functions simplify creation of complex types. Use the [creal, crealf, creall](creal-crealf-creall.md) and [cimag, cimagf, cimagl](cimag-cimagf-cimagl.md) functions to retrieve the real and imaginary portions of the represented complex numbers. +The **`_Cbuild`**, **`_FCbuild`**, and **`_LCbuild`** functions simplify creation of complex types. Use the [`creal`, `crealf`, `creall`](creal-crealf-creall.md) and [`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md) functions to retrieve the real and imaginary portions of the represented complex numbers. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**_Cbuild**, **_FCbuild**, **_LCbuild**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`_Cbuild`**, **`_FCbuild`**, **`_LCbuild`** | \ | \ | -These functions are Microsoft-specific. The types **_Dcomplex**, **_Fcomplex**, and **_Lcomplex** are Microsoft-specific equivalents to the unimplemented C99 native types **`double _Complex`**, **`float _Complex`**, and **`long double _Complex`**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. The types `_Dcomplex`, `_Fcomplex`, and `_Lcomplex` are Microsoft-specific equivalents to the unimplemented C99 native types **`double _Complex`**, **`float _Complex`**, and **`long double _Complex`**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_Cmulcc, _FCmulcc, _LCmulcc](cmulcc-fcmulcc-lcmulcc.md)
-[_Cmulcr, _FCmulcr, _LCmulcr](cmulcr-fcmulcr-lcmulcr.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_Cmulcc`, `_FCmulcc`, `_LCmulcc`](cmulcc-fcmulcc-lcmulcc.md)\ +[`_Cmulcr`, `_FCmulcr`, `_LCmulcr`](cmulcr-fcmulcr-lcmulcr.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md b/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md index 02cd728cba..9e690c8a46 100644 --- a/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md +++ b/docs/c-runtime-library/reference/ccos-ccosf-ccosl.md @@ -10,7 +10,7 @@ f1_keywords: ["ccos", "ccosf", "ccosl", "complex/ccos", "complex/ccosf", "comple helpviewer_keywords: ["ccos function", "ccosf function", "ccosl function"] ms.assetid: 4ab936ac-ff85-49ac-9418-2b69cf5d4696 --- -# ccos, ccosf, ccosl +# `ccos`, `ccosf`, `ccosl` Retrieves the cosine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex ccosl( ### Parameters -*z*
+*`z`*\ A complex number that represents the angle, in radians. -## Return Value +## Return value -The cosine of *z*, in radians. +The cosine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **ccos** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ccos** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ccos`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ccos`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ccos**, **ccosf**, **ccosl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ccos`**, **`ccosf`**, **`ccosl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md b/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md index 970f801b8d..5097b02582 100644 --- a/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md +++ b/docs/c-runtime-library/reference/ccosh-ccoshf-ccoshl.md @@ -10,7 +10,7 @@ f1_keywords: ["ccosh", "ccoshf", "ccoshl", "complex/ccosh", "complex/ccoshf", "c helpviewer_keywords: ["ccosh function", "ccoshf function", "ccoshl function"] ms.assetid: 79667449-4edf-4948-bf6b-720adf2b3f3b --- -# ccosh, ccoshf, ccoshl +# `ccosh`, `ccoshf`, `ccoshl` Retrieves the hyperbolic cosine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex ccoshl( ### Parameters -*z*
+*`z`*\ A complex number that represents the angle, in radians. -## Return Value +## Return value -The hyperbolic cosine of *z*, in radians. +The hyperbolic cosine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **ccosh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ccosh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ccosh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ccosh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ccosh**, **ccoshf**, **ccoshl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ccosh`**, **`ccoshf`**, **`ccoshl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ceil-ceilf-ceill.md b/docs/c-runtime-library/reference/ceil-ceilf-ceill.md index 34f697ad1a..0b4598a254 100644 --- a/docs/c-runtime-library/reference/ceil-ceilf-ceill.md +++ b/docs/c-runtime-library/reference/ceil-ceilf-ceill.md @@ -3,14 +3,14 @@ title: "ceil, ceilf, ceill" description: "API ref for calculating the ceiling of a value with ceil()." ms.date: "9/1/2020" api_name: ["ceilf", "ceil", "ceill", "_o_ceil", "_o_ceilf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntdll.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntdll.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ceil", "ceilf", "ceill"] helpviewer_keywords: ["calculating value ceilings", "ceill function", "ceil function", "ceilf function"] ms.assetid: f4e5acab-5c8f-4b10-9ae2-9561e6453718 --- -# ceil, ceilf, ceill +# `ceil`, `ceilf`, `ceill` Calculates the ceiling of a value. @@ -37,43 +37,43 @@ long double ceill( ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **ceil** functions return a floating-point value that represents the smallest integer that is greater than or equal to *x*. There's no error return. +The **`ceil`** functions return a floating-point value that represents the smallest integer that is greater than or equal to *`x`*. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **QNAN**, **IND**|none|**_DOMAIN**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | -**ceil** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [_set_SSE2_enable](set-sse2-enable.md). +**`ceil`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). ## Remarks -Because C++ allows overloading, you can call overloads of **ceil** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **ceil** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`ceil`** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`ceil`** always takes and returns a **`double`**. -If you use the \ `ceil()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `ceil()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. By default, this function's global state is scoped to the application. To change this state, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -| **ceil**, **ceilf**, **ceill**| \ | -| **ceil** macro | \ | +| Routine | Required header | +|---|---| +| **`ceil`**, **`ceilf`**, **`ceill`** | \ | +| **`ceil`** macro | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [floor](floor-floorf-floorl.md). +See the example for [`floor`](floor-floorf-floorl.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[fmod, fmodf](fmod-fmodf.md)
-[round, roundf, roundl](round-roundf-roundl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md) diff --git a/docs/c-runtime-library/reference/cexit-c-exit.md b/docs/c-runtime-library/reference/cexit-c-exit.md index 4d8e7f67bc..c02e829b58 100644 --- a/docs/c-runtime-library/reference/cexit-c-exit.md +++ b/docs/c-runtime-library/reference/cexit-c-exit.md @@ -3,14 +3,14 @@ description: "Learn more about: _cexit, _c_exit" title: "_cexit, _c_exit" ms.date: "4/2/2020" api_name: ["_c_exit", "_cexit", "_o__cexit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_cexit", "c_exit", "_c_exit", "cexit"] helpviewer_keywords: ["cleanup operations during processes", "cexit function", "_c_exit function", "_cexit function", "c_exit function"] ms.assetid: f3072045-9924-4b1a-9fef-b0dcd6d12663 --- -# _cexit, _c_exit +# `_cexit`, `_c_exit` Performs cleanup operations and returns without terminating the process. @@ -23,39 +23,39 @@ void _c_exit( void ); ## Remarks -The **_cexit** function calls, in last-in, first-out (LIFO) order, the functions registered by **atexit** and **_onexit**. Then **_cexit** flushes all I/O buffers and closes all open streams before returning. **_c_exit** is the same as **_exit** but returns to the calling process without processing **atexit** or **_onexit** or flushing stream buffers. The behavior of **exit**, **_exit**, **_cexit**, and **_c_exit** is shown in the following table. +The **`_cexit`** function calls, in last-in, first-out (LIFO) order, the functions registered by `atexit` and `_onexit`. Then **`_cexit`** flushes all I/O buffers and closes all open streams before returning. **`_c_exit`** is the same as `_exit` but returns to the calling process without processing `atexit` or `_onexit` or flushing stream buffers. The behavior of `exit`, `_exit`, **`_cexit`**, and **`_c_exit`** is shown in the following table. -|Function|Behavior| -|--------------|--------------| -|**exit**|Performs complete C library termination procedures, terminates process, and exits with supplied status code.| -|**_exit**|Performs quick C library termination procedures, terminates process, and exits with supplied status code.| -|**_cexit**|Performs complete C library termination procedures and returns to caller, but does not terminate process.| -|**_c_exit**|Performs quick C library termination procedures and returns to caller, but does not terminate process.| +| Function | Behavior | +|---|---| +| `exit` | Performs complete C library termination procedures, terminates process, and exits with supplied status code. | +| `_exit` | Performs quick C library termination procedures, terminates process, and exits with supplied status code. | +| **`_cexit`** | Performs complete C library termination procedures and returns to caller, but doesn't terminate process. | +| **`_c_exit`** | Performs quick C library termination procedures and returns to caller, but doesn't terminate process. | -When you call the **_cexit** or **_c_exit** functions, the destructors for any temporary or automatic objects that exist at the time of the call are not called. An automatic object is an object that is defined in a function where the object is not declared to be static. A temporary object is an object created by the compiler. To destroy an automatic object before calling **_cexit** or **_c_exit**, explicitly call the destructor for the object, as follows: +When you call the **`_cexit`** or **`_c_exit`** functions, the destructors for any temporary or automatic objects that exist at the time of the call aren't called. An automatic object is an object that is defined in a function where the object isn't declared to be static. A temporary object is an object created by the compiler. To destroy an automatic object before calling **`_cexit`** or **`_c_exit`**, explicitly call the destructor for the object, as follows: ```cpp myObject.myClass::~myClass( ); ``` -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cexit**|\| -|**_c_exit**|\| +| Routine | Required header | +|---|---| +| **`_cexit`** | \ | +| **`_c_exit`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md b/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md index 357ad8fabb..c2c221f1f2 100644 --- a/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md +++ b/docs/c-runtime-library/reference/cexp-cexpf-cexpl.md @@ -10,7 +10,7 @@ f1_keywords: ["cexp", "cexpf", "cexpl", "complex/cepx", "complex/cexpf", "comple helpviewer_keywords: ["cexp function", "cexpl function", "cexpf function"] ms.assetid: f27fd5a9-70c7-4957-a7ee-5256d19bd1da --- -# cexp, cexpf, cexpl +# `cexp`, `cexpf`, `cexpl` Compute the base-e exponential of a complex number. @@ -27,28 +27,28 @@ _Lcomplex cexp( _Lcomplex z ); // C++ only ### Parameters -*z*\ +*`z`*\ A complex number that represents the exponent. -## Return Value +## Return value -The value of **e** raised to the power of *z*. +The value of **e** raised to the power of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **cexp** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **cexp** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`cexp`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`cexp`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cexp**, **cexpf**, **cexpl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`cexp`**, **`cexpf`**, **`cexpl`** | \ | \ | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)\ -[cpow, cpowf, cpowl](cpow-cpowf-cpowl.md)\ -[clog10, clog10f, clog10l](clog10-clog10f-clog10l.md)\ -[clog, clogf, clogl](clog-clogf-clogl.md) +[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`cpow`, `cpowf`, `cpowl`](cpow-cpowf-cpowl.md)\ +[`clog10`, `clog10f`, `clog10l`](clog10-clog10f-clog10l.md)\ +[`clog`, `clogf`, `clogl`](clog-clogf-clogl.md) diff --git a/docs/c-runtime-library/reference/cgets-s-cgetws-s.md b/docs/c-runtime-library/reference/cgets-s-cgetws-s.md index 2ca6c0d0aa..82de69ea28 100644 --- a/docs/c-runtime-library/reference/cgets-s-cgetws-s.md +++ b/docs/c-runtime-library/reference/cgets-s-cgetws-s.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _cgets_s, _cgetws_s" title: "_cgets_s, _cgetws_s" +description: "Learn more about: _cgets_s, _cgetws_s" ms.date: "4/2/2020" api_name: ["_cgetws_s", "_cgets_s", "_o__cgets_s", "_o__cgetws_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_cgets_s", "cgets_s", "cgetws_s", "_cgetws_s"] helpviewer_keywords: ["strings [C++], getting from console", "console, getting strings from", "_cgets_s function", "cget_s function", "_cgetws_s function", "cgetws_s function"] -ms.assetid: 38b74897-afe6-4dd9-a43f-36a3c0d72c5c --- -# _cgets_s, _cgetws_s +# `_cgets_s`, `_cgetws_s` -Gets a character string from the console. These versions of [_cgets and _cgetws](../../c-runtime-library/cgets-cgetws.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Gets a character string from the console. These versions of [`_cgets` and `_cgetws`](../cgets-cgetws.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -26,7 +25,7 @@ errno_t _cgets_s( size_t *pSizeRead ); errno_t _cgetws_s( - wchar_t *buffer + wchar_t *buffer, size_t numberOfElements, size_t *pSizeRead ); @@ -44,55 +43,55 @@ errno_t _cgetws_s( ### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer in single-byte or wide characters, which is also the maximum number of characters to be read. -*pSizeRead*
+*`pSizeRead`*\ The number of characters actually read. -## Return Value +## Return value The return value is zero if successful; otherwise, an error code if a failure occurs. -### Error Conditions +### Error conditions -|*buffer*|*numberOfElements*|*pSizeRead*|Return|Contents of *buffer*| -|--------------|------------------------|-----------------|------------|--------------------------| -|**NULL**|any|any|**EINVAL**|n/a| -|not **NULL**|zero|any|**EINVAL**|not modified| -|not **NULL**|any|**NULL**|**EINVAL**|zero-length string| +| *`buffer`* | *`numberOfElements`* | *`pSizeRead`* | Return | Contents of *`buffer`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | n/a | +| not `NULL` | zero | any | `EINVAL` | not modified | +| not `NULL` | any | `NULL` | `EINVAL` | zero-length string | ## Remarks -**_cgets_s** and **_cgetws_s** read a string from the console and copy the string (with a null terminator) into *buffer*. **_cgetws_s** is the wide character version of the function; other than the character size, the behavior of these two functions is identical. The maximum size of the string to be read is passed in as the *numberOfElements* parameter. This size should include an extra character for the terminating null. The actual number of characters read is placed in *pSizeRead*. +**`_cgets_s`** and **`_cgetws_s`** read a string from the console and copy the string (with a null terminator) into *`buffer`*. **`_cgetws_s`** is the wide character version of the function; other than the character size, the behavior of these two functions is identical. The maximum size of the string to be read is passed in as the *`numberOfElements`* parameter. This size should include an extra character for the terminating null. The actual number of characters read is placed in *`pSizeRead`*. -If an error occurs during the operation or in the validating of the parameters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, **errno** is set to **EINVAL** and **EINVAL** is returned. +If an error occurs during the operation or in the validating of the parameters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and `EINVAL` is returned. -In C++, the use of these functions is simplified by template overloads; the overloads can infer buffer length automatically, thereby eliminating the need to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, the use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a size argument. They can also automatically replace older, less-secure functions with their newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_cgetts_s**|**_cgets_s**|**_cgets_s**|**_cgetws_s**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cgetts_s` | **`_cgets_s`** | **`_cgets_s`** | **`_cgetws_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cgets_s**|\| -|**_cgetws_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_cgets_s`** | \ | +| **`_cgetws_s`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/cgets.md b/docs/c-runtime-library/reference/cgets.md index acd45107fe..70cba4d954 100644 --- a/docs/c-runtime-library/reference/cgets.md +++ b/docs/c-runtime-library/reference/cgets.md @@ -10,11 +10,11 @@ f1_keywords: ["cgets"] helpviewer_keywords: ["cgets function"] ms.assetid: 54faf257-5ed6-4301-be19-66d953e901fa --- -# cgets +# `cgets` -The Microsoft-specific function name `cgets` is a deprecated alias for the [_cgets](../cgets-cgetws.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cgets` is a deprecated alias for the [`_cgets`](../cgets-cgetws.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use the security-enhanced [_cgets_s](cgets-s-cgetws-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use the security-enhanced [`_cgets_s`](cgets-s-cgetws-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/chdir-wchdir.md b/docs/c-runtime-library/reference/chdir-wchdir.md index 5af5137619..d95f085350 100644 --- a/docs/c-runtime-library/reference/chdir-wchdir.md +++ b/docs/c-runtime-library/reference/chdir-wchdir.md @@ -3,14 +3,13 @@ description: "Learn more about: _chdir, _wchdir" title: "_chdir, _wchdir" ms.date: "4/2/2020" api_name: ["_wchdir", "_chdir", "_o__chdir", "_o__wchdir"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["tchdir", "_chdir", "_wchdir", "_tchdir", "wchdir"] helpviewer_keywords: ["_tchdir function", "_chdir function", "_wchdir function", "tchdir function", "wchdir function", "chdir function", "directories [C++], changing"] -ms.assetid: 85e9393b-62ac-45d5-ab2a-fa2217f6152e --- -# _chdir, _wchdir +# `_chdir`, `_wchdir` Changes the current working directory. @@ -27,41 +26,41 @@ int _wchdir( ### Parameters -*dirname*
+*`dirname`*\ Path of new working directory. -## Return Value +## Return value -These functions return a value of 0 if successful. A return value of -1 indicates failure. If the specified path could not be found, **errno** is set to **ENOENT**. If *dirname* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns -1. +These functions return a value of 0 if successful. A return value of -1 indicates failure. If the specified path couldn't be found, `errno` is set to `ENOENT`. If *`dirname`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns -1. ## Remarks -The **_chdir** function changes the current working directory to the directory specified by *dirname*. The *dirname* parameter must refer to an existing directory. This function can change the current working directory on any drive. If a new drive letter is specified in *dirname*, the default drive letter is changed as well. For example, if A is the default drive letter and \BIN is the current working directory, the following call changes the current working directory for drive C and establishes C as the new default drive: +The **`_chdir`** function changes the current working directory to the directory specified by *`dirname`*. The *`dirname`* parameter must refer to an existing directory. This function can change the current working directory on any drive. If a new drive letter is specified in *`dirname`*, the default drive letter is changed as well. For example, assume `A` is the default drive letter and `\BIN` is the current working directory. The following call changes the current working directory for drive `C` to `\temp` and establishes `C` as the new default drive: ```C -_chdir("c:\temp"); +_chdir("c:\\temp"); ``` When you use the optional backslash character (**`\`**) in paths, you must place two backslashes (**`\\`**) in a C string literal to represent a single backslash (**`\`**). -**_wchdir** is a wide-character version of **_chdir**; the *dirname* argument to **_wchdir** is a wide-character string. **_wchdir** and **_chdir** behave identically otherwise. +**`_wchdir`** is a wide-character version of **`_chdir`**; the *`dirname`* argument to **`_wchdir`** is a wide-character string. **`_wchdir`** and **`_chdir`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping: +### Generic-text routine mapping -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tchdir**|**_chdir**|**_chdir**|**_wchdir**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tchdir`** | **`_chdir`** | **`_chdir`** | **`_wchdir`** | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_chdir**|\|\| -|**_wchdir**|\ or \|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_chdir`** | `` | `` | +| **`_wchdir`** | `` or `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -79,7 +78,6 @@ For more compatibility information, see [Compatibility](../../c-runtime-library/ int main( int argc, char *argv[] ) { - if(_chdir( argv[1] ) ) { switch (errno) @@ -124,7 +122,7 @@ Directory of c:\windows ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_rmdir, _wrmdir](rmdir-wrmdir.md)
-[system, _wsystem](system-wsystem.md)
+[Directory control](../directory-control.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/chdir.md b/docs/c-runtime-library/reference/chdir.md index ded2bd685a..36a96e7b21 100644 --- a/docs/c-runtime-library/reference/chdir.md +++ b/docs/c-runtime-library/reference/chdir.md @@ -10,11 +10,11 @@ f1_keywords: ["chdir"] helpviewer_keywords: ["chdir function"] ms.assetid: a65275a1-41e4-46be-83a5-167dfacb62a0 --- -# chdir +# `chdir` -The Microsoft-implemented POSIX function name `chdir` is a deprecated alias for the [_chdir](chdir-wchdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `chdir` is a deprecated alias for the [`_chdir`](chdir-wchdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_chdir](chdir-wchdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_chdir`](chdir-wchdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/chdrive.md b/docs/c-runtime-library/reference/chdrive.md index 103e31fe01..3343c14ce8 100644 --- a/docs/c-runtime-library/reference/chdrive.md +++ b/docs/c-runtime-library/reference/chdrive.md @@ -3,14 +3,14 @@ description: "Learn more about: _chdrive" title: "_chdrive" ms.date: "4/2/2020" api_name: ["_chdrive", "_o__chdrive"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["chdrive", "_chdrive"] helpviewer_keywords: ["drives, changing", "_chdrive function", "chdrive function"] ms.assetid: 212a1a4b-4fa8-444e-9677-7fca4c8c47e3 --- -# _chdrive +# `_chdrive` Changes the current working drive. @@ -27,42 +27,42 @@ int _chdrive( ### Parameters -*drive*
+*`drive`*\ An integer from 1 through 26 that specifies the current working drive (1=A, 2=B, and so forth). -## Return Value +## Return value Zero (0) if the current working drive was changed successfully; otherwise, -1. ## Remarks -If *drive* is not in the range from 1 through 26, the invalid-parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the **_chdrive** function returns -1, **errno** is set to **EACCES**, and **_doserrno** is set to **ERROR_INVALID_DRIVE**. +If *`drive`* isn't in the range from 1 through 26, the invalid-parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the **`_chdrive`** function returns -1, `errno` is set to `EACCES`, and `_doserrno` is set to `ERROR_INVALID_DRIVE`. -The **_chdrive** function is not thread-safe because it depends on the **SetCurrentDirectory** function, which is itself not thread-safe. To use **_chdrive** safely in a multi-threaded application, you must provide your own thread synchronization. For more information, see [SetCurrentDirectory](/windows/win32/api/winbase/nf-winbase-setcurrentdirectory). +The **`_chdrive`** function isn't thread-safe because it depends on the `SetCurrentDirectory` function, which is itself not thread-safe. To use **`_chdrive`** safely in a multi-threaded application, you must provide your own thread synchronization. For more information, see [`SetCurrentDirectory`](/windows/win32/api/winbase/nf-winbase-setcurrentdirectory). -The **_chdrive** function changes only the current working drive; **_chdir** changes the current working directory. +The **`_chdrive`** function changes only the current working drive; `_chdir` changes the current working directory. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_chdrive**|\| +| Routine | Required header | +|---|---| +| **`_chdrive`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Example -See the example for [_getdrive](getdrive.md). +See the example for [`_getdrive`](getdrive.md). ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdir, _wchdir](chdir-wchdir.md)
-[_fullpath, _wfullpath](fullpath-wfullpath.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdrive](getdrive.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_rmdir, _wrmdir](rmdir-wrmdir.md)
-[system, _wsystem](system-wsystem.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdrive`](getdrive.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md b/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md index 96007ca53f..3377a6e345 100644 --- a/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md +++ b/docs/c-runtime-library/reference/chgsign-chgsignf-chgsignl.md @@ -10,7 +10,7 @@ f1_keywords: ["_chgsignf", "chgsign", "_chgsignl", "_chgsign"] helpviewer_keywords: ["_chgsignl function", "_chgsignf function", "chgsign function", "_chgsign function"] ms.assetid: a6646f8e-213d-4564-8617-f43bc66f989f --- -# _chgsign, _chgsignf, _chgsignl +# `_chgsign`, `_chgsignf`, `_chgsignl` Reverses the sign of a floating-point argument. @@ -30,24 +30,24 @@ long double _chgsignl( ### Parameters -*x*
+*`x`*\ The floating-point value to be changed. -## Return Value +## Return value -The **_chgsign** functions return a value that's equal to the floating-point argument *x*, but with its sign reversed. There's no error return. +The **`_chgsign`** functions return a value that's equal to the floating-point argument *`x`*, but with its sign reversed. There's no error return. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_chgsign**|\| -|**_chgsignf**, **_chgsignl**|\| +| Routine | Required header | +|---|---| +| **`_chgsign`** | \ | +| **`_chgsignf`**, **`_chgsignl`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fabs, fabsf, fabsl](fabs-fabsf-fabsl.md)
-[copysign, copysignf, copysignl, _copysign, _copysignf, _copysignl](copysign-copysignf-copysignl-copysign-copysignf-copysignl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ +[`copysign`, `copysignf`, `copysignl`, `_copysign`, `_copysignf`, `_copysignl`](copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) diff --git a/docs/c-runtime-library/reference/chmod-wchmod.md b/docs/c-runtime-library/reference/chmod-wchmod.md index d6355bedd4..eb98e7289c 100644 --- a/docs/c-runtime-library/reference/chmod-wchmod.md +++ b/docs/c-runtime-library/reference/chmod-wchmod.md @@ -3,14 +3,14 @@ description: "Learn more about: _chmod, _wchmod" title: "_chmod, _wchmod" ms.date: "4/2/2020" api_name: ["_chmod", "_wchmod", "_o__chmod", "_o__wchmod"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_chmod", "_wchmod", "wchmod"] helpviewer_keywords: ["_chmod function", "wchmod function", "file permissions [C++]", "chmod function", "files [C++], changing permissions", "_wchmod function"] ms.assetid: 92f7cb86-b3b0-4232-a599-b8c04a2f2c19 --- -# _chmod, _wchmod +# `_chmod`, `_wchmod` Changes the file-permission settings. @@ -23,48 +23,48 @@ int _wchmod( const wchar_t *filename, int pmode ); ### Parameters -*filename*
+*`filename`*\ Name of the existing file. -*pmode*
+*`pmode`*\ Permission setting for the file. -## Return Value +## Return value -These functions return 0 if the permission setting is successfully changed. A return value of -1 indicates failure. If the specified file could not be found, **errno** is set to **ENOENT**; if a parameter is invalid, **errno** is set to **EINVAL**. +These functions return 0 if the permission setting is successfully changed. A return value of -1 indicates failure. If the specified file couldn't be found, `errno` is set to `ENOENT`; if a parameter is invalid, `errno` is set to `EINVAL`. ## Remarks -The **_chmod** function changes the permission setting of the file specified by *filename*. The permission setting controls the read and write access to the file. The integer expression *pmode* contains one or both of the following manifest constants, defined in SYS\Stat.h. +The **`_chmod`** function changes the permission setting of the file specified by *`filename`*. The permission setting controls the read and write access to the file. The integer expression *`pmode`* contains one or both of the following manifest constants, defined in SYS\Stat.h. -| *pmode* | Meaning | +| *`pmode`* | Meaning | |-|-| -| **\_S\_IREAD** | Only reading permitted. | -| **\_S\_IWRITE** | Writing permitted. (In effect, permits reading and writing.) | -| **\_S\_IREAD** | **\_S\_IWRITE** | Reading and writing permitted. | +| `_S_IREAD` | Only reading permitted. | +| `_S_IWRITE` | Writing permitted. (In effect, permits reading and writing.) | +| `_S_IREAD | _S_IWRITE` | Reading and writing permitted. | -When both constants are given, they are joined with the bitwise or operator (**\|**). If write permission is not given, the file is read-only. Note that all files are always readable; it is not possible to give write-only permission. Thus, the modes **_S_IWRITE** and **_S_IREAD** \| **_S_IWRITE** are equivalent. +When both constants are given, they're joined with the bitwise or operator (**`|`**). If write permission isn't given, the file is read-only. Note that all files are always readable; it isn't possible to give write-only permission. Thus, the modes `_S_IWRITE` and `_S_IREAD | _S_IWRITE` are equivalent. -**_wchmod** is a wide-character version of **_chmod**; the *filename* argument to **_wchmod** is a wide-character string. **_wchmod** and **_chmod** behave identically otherwise. +**`_wchmod`** is a wide-character version of **`_chmod`**; the *`filename`* argument to **`_wchmod`** is a wide-character string. **`_wchmod`** and **`_chmod`** behave identically otherwise. -This function validates its parameters. If *pmode* is not a combination of one of the manifest constants or incorporates an alternate set of constants, the function simply ignores those. If *filename* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns -1. +This function validates its parameters. If *`pmode`* isn't a combination of one of the manifest constants or incorporates an alternate set of constants, the function simply ignores them. If *`filename`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tchmod**|**_chmod**|**_chmod**|**_wchmod**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tchmod` | **`_chmod`** | **`_chmod`** | **`_wchmod`** | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_chmod**|\|\, \, \| -|**_wchmod**|\ or \|\, \, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_chmod`** | \ | \, \, \ | +| **`_wchmod`** | \ or \ | \, \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -114,7 +114,6 @@ void set_mode_and_report(char * filename, int mask) int main( void ) { - // Create or append to a file. system( "echo /* End of file */ >> crt_chmod.c_input" ); @@ -144,9 +143,9 @@ Mode set to read/write ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_access, _waccess](access-waccess.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_open, _wopen](open-wopen.md)
-[_stat, _wstat Functions](stat-functions.md)
+[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/chmod.md b/docs/c-runtime-library/reference/chmod.md index 513152cf1f..f4f46b3f37 100644 --- a/docs/c-runtime-library/reference/chmod.md +++ b/docs/c-runtime-library/reference/chmod.md @@ -10,8 +10,8 @@ f1_keywords: ["chmod"] helpviewer_keywords: ["chmod function"] ms.assetid: c3294722-2194-4ff4-ac87-d69f155e279b --- -# chmod +# `chmod` -The Microsoft-implemented POSIX function name `chmod` is a deprecated alias for the [_chmod](chmod-wchmod.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `chmod` is a deprecated alias for the [`_chmod`](chmod-wchmod.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_chmod](chmod-wchmod.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_chmod`](chmod-wchmod.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/chsize-s.md b/docs/c-runtime-library/reference/chsize-s.md index 27179e8070..f665218fbd 100644 --- a/docs/c-runtime-library/reference/chsize-s.md +++ b/docs/c-runtime-library/reference/chsize-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _chsize_s" title: "_chsize_s" ms.date: "4/2/2020" api_name: ["_chsize_s", "_o__chsize_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["chsize_s", "_chsize_s"] helpviewer_keywords: ["files [C++], changing size", "chsize_s function", "_chsize_s function"] ms.assetid: d88d2e94-6e3b-42a5-8631-16ac4d82fa38 --- -# _chsize_s +# `_chsize_s` -Changes the size of a file. This is a version of [_chsize](chsize.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Changes the size of a file. This function is a version of [`_chsize`](chsize.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -25,40 +25,40 @@ errno_t _chsize_s( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to an open file. -*size*
+*`size`*\ New length of the file in bytes. -## Return Value +## Return value -**_chsize_s** returns the value 0 if the file size is successfully changed. A nonzero return value indicates an error: the return value is **EACCES** if the specified file is locked against access, **EBADF** if the specified file is read-only or the descriptor is invalid, **ENOSPC** if no space is left on the device, or **EINVAL** if size is less than zero. **errno** is set to the same value. +**`_chsize_s`** returns the value 0 if the file size is successfully changed. A nonzero return value indicates an error: the return value is `EACCES` if the specified file is locked against access, `EBADF` if the specified file is read-only or the descriptor is invalid, `ENOSPC` if no space is left on the device, or `EINVAL` if size is less than zero. `errno` is set to the same value. -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_chsize_s** function extends or truncates the file associated with *fd* to the length specified by *size*. The file must be open in a mode that permits writing. Null characters ('\0') are appended if the file is extended. If the file is truncated, all data from the end of the shortened file to the original length of the file is lost. +The **`_chsize_s`** function extends or truncates the file associated with *`fd`* to the length specified by *`size`*. The file must be open in a mode that permits writing. Null characters ('\0') are appended if the file is extended. If the file is truncated, all data from the end of the shortened file to the original length of the file is lost. -**_chsize_s** takes a 64-bit integer as the file size, and therefore can handle file sizes greater than 4 GB. **_chsize** is limited to 32-bit file sizes. +**`_chsize_s`** takes a 64-bit integer as the file size, and therefore can handle file sizes greater than 4 GB. `_chsize` is limited to 32-bit file sizes. -This function validates its parameters. If *fd* is not a valid file descriptor or size is less than zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +This function validates its parameters. If *`fd`* isn't a valid file descriptor or size is less than zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_chsize_s**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_chsize_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_chsize](chsize.md)
-[_close](close.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
+[File handling](../file-handling.md)\ +[`_chsize`](chsize.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/chsize.md b/docs/c-runtime-library/reference/chsize.md index 94000ad768..94341adba6 100644 --- a/docs/c-runtime-library/reference/chsize.md +++ b/docs/c-runtime-library/reference/chsize.md @@ -3,16 +3,16 @@ description: "Learn more about: _chsize" title: "_chsize" ms.date: "4/2/2020" api_name: ["_chsize", "_o__chsize"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_chsize"] helpviewer_keywords: ["size", "_chsize function", "size, changing file", "files [C++], changing size", "chsize function"] ms.assetid: b3e881c5-7b27-4837-a3d4-c51591ab10ff --- -# _chsize +# `_chsize` -Changes the size of a file. A more secure version is available; see [_chsize_s](chsize-s.md). +Changes the size of a file. A more secure version is available; see [`_chsize_s`](chsize-s.md). ## Syntax @@ -25,33 +25,33 @@ int _chsize( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to an open file. -*size*
+*`size`*\ New length of the file in bytes. -## Return Value +## Return value -**_chsize** returns the value 0 if the file size is successfully changed. A return value of -1 indicates an error: **errno** is set to **EACCES** if the specified file is read-only or the specified file is locked against access, to **EBADF** if the descriptor is invalid, **ENOSPC** if no space is left on the device, or **EINVAL** if *size* is less than zero. +**`_chsize`** returns the value 0 if the file size is successfully changed. A return value of -1 indicates an error: `errno` is set to `EACCES` if the specified file is read-only or the specified file is locked against access, to `EBADF` if the descriptor is invalid, `ENOSPC` if no space is left on the device, or `EINVAL` if *`size`* is less than zero. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_chsize** function extends or truncates the file associated with *fd* to the length specified by *size*. The file must be open in a mode that permits writing. Null characters ('\0') are appended if the file is extended. If the file is truncated, all data from the end of the shortened file to the original length of the file is lost. +The **`_chsize`** function extends or truncates the file associated with *`fd`* to the length specified by *`size`*. The file must be open in a mode that permits writing. Null characters ('\0') are appended if the file is extended. If the file is truncated, all data from the end of the shortened file to the original length of the file is lost. -This function validates its parameters. If *size* is less than zero or *fd* is a bad file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +This function validates its parameters. If *`size`* is less than zero or *`fd`* is a bad file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_chsize**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_chsize`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,7 +95,7 @@ File length after: 329678 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_close](close.md)
-[_sopen, _wsopen](sopen-wsopen.md)
-[_open, _wopen](open-wopen.md)
+[File handling](../file-handling.md)\ +[`_close`](close.md)\ +[`_sopen`, `_wsopen`](sopen-wsopen.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md b/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md index 8774981901..dfcdd2f381 100644 --- a/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md +++ b/docs/c-runtime-library/reference/cimag-cimagf-cimagl.md @@ -10,7 +10,7 @@ f1_keywords: ["cimagf", "cimagl", "complex/cimag", "complex/cimagf", "complex/ci helpviewer_keywords: ["cimag function", "cimagf function", "cimagl function"] ms.assetid: 0d8836f5-d61d-44cd-8731-6f75cb776def --- -# cimag, cimagf, cimagl +# `cimag`, `cimagf`, `cimagl` Retrieves the imaginary part of a complex number. @@ -28,34 +28,34 @@ long double cimag( _Lcomplex z ); // C++ only ### Parameters -*z*\ +*`z`*\ A complex number. -## Return Value +## Return value -The imaginary part of *z*. +The imaginary part of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **cimag** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **cimag** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`cimag`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`cimag`** always takes a `_Dcomplex` value and returns a **`double`** value. -If you use the \ `cimag()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `cimag()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cimag**, **cimagf**, **cimagl**|\|\| -|**cimag** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`cimag`**, **`cimagf`**, **`cimagl`** | \ | \ | +| **`cimag`** macro | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/clear87-clearfp.md b/docs/c-runtime-library/reference/clear87-clearfp.md index 7e38595c18..e91fd1f739 100644 --- a/docs/c-runtime-library/reference/clear87-clearfp.md +++ b/docs/c-runtime-library/reference/clear87-clearfp.md @@ -10,7 +10,7 @@ f1_keywords: ["clearfp", "_clearfp", "_clear87", "clear87"] helpviewer_keywords: ["clearing floating point status word", "clearfp function", "_clear87 function", "_clearfp function", "clear87 function"] ms.assetid: 72d24a70-7688-4793-ae09-c96d33fcca52 --- -# _clear87, _clearfp +# `_clear87`, `_clearfp` Gets and clears the floating-point status word. @@ -21,26 +21,26 @@ unsigned int _clear87( void ); unsigned int _clearfp( void ); ``` -## Return Value +## Return value -The bits in the value returned indicate the floating-point status before the call to **_clear87** or **_clearfp**. For a complete definition of the bits returned by **_clear87**, see Float.h. Many of the math library functions modify the 8087/80287 status word, with unpredictable results. Return values from **_clear87** and **_status87** become more reliable as fewer floating-point operations are performed between known states of the floating-point status word. +The bits in the value returned indicate the floating-point status before the call to **`_clear87`** or **`_clearfp`**. For a complete definition of the bits returned by **`_clear87`**, see Float.h. Many of the math library functions modify the 8087/80287 status word, with unpredictable results. Return values from **`_clear87`** and `_status87` become more reliable as fewer floating-point operations are performed between known states of the floating-point status word. ## Remarks -The **_clear87** function clears the exception flags in the floating-point status word, sets the busy bit to 0, and returns the status word. The floating-point status word is a combination of the 8087/80287 status word and other conditions detected by the 8087/80287 exception handler, such as floating-point stack overflow and underflow. +The **`_clear87`** function clears the exception flags in the floating-point status word, sets the busy bit to 0, and returns the status word. The floating-point status word is a combination of the 8087/80287 status word and other conditions detected by the 8087/80287 exception handler, such as floating-point stack overflow and underflow. -**_clearfp** is a platform-independent, portable version of the **_clear87** routine. It is identical to **_clear87** on Intel (x86) platforms and is also supported by the x64 and ARM platforms. To ensure that your floating-point code is portable to x64 and ARM, use **_clearfp**. If you are only targeting x86 platforms, you can use either **_clear87** or **_clearfp**. +**`_clearfp`** is a platform-independent, portable version of the **`_clear87`** routine. It's identical to **`_clear87`** on Intel (x86) platforms and is also supported by the x64 and ARM platforms. To ensure that your floating-point code is portable to x64 and ARM, use **`_clearfp`**. If you're only targeting x86 platforms, you can use either **`_clear87`** or **`_clearfp`**. These functions are deprecated when compiling with [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime only supports the default floating-point precision. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_clear87**|\| -|**_clearfp**|\| +| Routine | Required header | +|---|---| +| **`_clear87`** | \ | +| **`_clearfp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -83,6 +83,6 @@ Status: 80000 - denormal ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md)
-[_status87, _statusfp, _statusfp2](status87-statusfp-statusfp2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md)\ +[`_status87`, `_statusfp`, `_statusfp2`](status87-statusfp-statusfp2.md) diff --git a/docs/c-runtime-library/reference/clearerr-s.md b/docs/c-runtime-library/reference/clearerr-s.md index 1e471ade4c..d8a0bdb95a 100644 --- a/docs/c-runtime-library/reference/clearerr-s.md +++ b/docs/c-runtime-library/reference/clearerr-s.md @@ -3,16 +3,16 @@ description: "Learn more about: clearerr_s" title: "clearerr_s" ms.date: "4/2/2020" api_name: ["clearerr_s", "_o_clearerr_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["clearerr_s"] helpviewer_keywords: ["error indicator for streams", "resetting stream error indicator", "clearerr_s function"] ms.assetid: b74d014d-b7a8-494a-a330-e5ffd5614772 --- -# clearerr_s +# `clearerr_s` -Resets the error indicator for a stream. This is a version of [clearerr](clearerr.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Resets the error indicator for a stream. This function is a version of [`clearerr`](clearerr.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,28 +24,28 @@ errno_t clearerr_s( ### Parameters -*stream*
-Pointer to **FILE** structure +*`stream`*\ +Pointer to `FILE` structure -## Return Value +## Return value -Zero if successful; **EINVAL** if *stream* is **NULL**. +Zero if successful; `EINVAL` if *`stream`* is `NULL`. ## Remarks -The **clearerr_s** function resets the error indicator and end-of-file indicator for *stream*. Error indicators are not automatically cleared; once the error indicator for a specified stream is set, operations on that stream continue to return an error value until **clearerr_s**, **clearerr**, [fseek](fseek-fseeki64.md), **fsetpos**, or [rewind](rewind.md) is called. +The **`clearerr_s`** function resets the error indicator and end-of-file indicator for *`stream`*. Error indicators aren't automatically cleared; once the error indicator for a specified stream is set, operations on that stream continue to return an error value until **`clearerr_s`**, `clearerr`, [`fseek`](fseek-fseeki64.md), `fsetpos`, or [`rewind`](rewind.md) is called. -If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**clearerr_s**|\| +| Routine | Required header | +|---|---| +| **`clearerr_s`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,10 +104,10 @@ Will input cause an error? n ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[clearerr](clearerr.md)
-[_eof](eof.md)
-[feof](feof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`_eof`](eof.md)\ +[`feof`](feof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/clearerr.md b/docs/c-runtime-library/reference/clearerr.md index 3d653023bc..d9b1235977 100644 --- a/docs/c-runtime-library/reference/clearerr.md +++ b/docs/c-runtime-library/reference/clearerr.md @@ -3,16 +3,16 @@ description: "Learn more about: clearerr" title: "clearerr" ms.date: "4/2/2020" api_name: ["clearerr", "_o_clearerr"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["clearerr"] helpviewer_keywords: ["error indicator for streams", "resetting stream error indicator", "clearerr function"] ms.assetid: a9711cd4-3335-43d4-a018-87bbac5b3bac --- -# clearerr +# `clearerr` -Resets the error indicator for a stream. A more secure version of this function is available; see [clearerr_s](clearerr-s.md). +Resets the error indicator for a stream. A more secure version of this function is available; see [`clearerr_s`](clearerr-s.md). ## Syntax @@ -24,26 +24,26 @@ void clearerr( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. ## Remarks -The **clearerr** function resets the error indicator and end-of-file indicator for *stream*. Error indicators are not automatically cleared; once the error indicator for a specified stream is set, operations on that stream continue to return an error value until **clearerr**, [fseek](fseek-fseeki64.md), **fsetpos**, or [rewind](rewind.md) is called. +The **`clearerr`** function resets the error indicator and end-of-file indicator for *`stream`*. Error indicators aren't automatically cleared; once the error indicator for a specified stream is set, operations on that stream continue to return an error value until **`clearerr`**, [`fseek`](fseek-fseeki64.md), `fsetpos`, or [`rewind`](rewind.md) is called. -If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns. For more information on **errno** and error codes, see [errno Constants](../../c-runtime-library/errno-constants.md). +If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns. For more information on `errno` and error codes, see [`errno` constants](../errno-constants.md). -A more secure version of this function is available; see [clearerr_s](clearerr-s.md). +A more secure version of this function is available; see [`clearerr_s`](clearerr-s.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**clearerr**|\| +| Routine | Required header | +|---|---| +| **`clearerr`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,9 +95,9 @@ No read error ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_eof](eof.md)
-[feof](feof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`_eof`](eof.md)\ +[`feof`](feof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/clock.md b/docs/c-runtime-library/reference/clock.md index 0950343175..6d1d7d63b9 100644 --- a/docs/c-runtime-library/reference/clock.md +++ b/docs/c-runtime-library/reference/clock.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["clock"] helpviewer_keywords: ["processor time used, calculating", "time, calculating processor", "clock function", "processor time used", "calculating processor time used"] -ms.assetid: 3e1853dd-498f-49ba-b06a-f2315f20904e --- -# clock +# `clock` Calculates the wall-clock time used by the calling process. @@ -20,23 +19,23 @@ Calculates the wall-clock time used by the calling process. clock_t clock( void ); ``` -## Return Value +## Return value -The elapsed time since the CRT initialization at the start of the process, measured in **CLOCKS_PER_SEC** units per second. If the elapsed time is unavailable or has exceeded the maximum positive time that can be recorded as a **clock_t** type, the function returns the value `(clock_t)(-1)`. +The elapsed time since the CRT initialization at the start of the process, measured in `CLOCKS_PER_SEC` units per second. If the elapsed time is unavailable or has exceeded the maximum positive time that can be recorded as a `clock_t` type, the function returns the value `(clock_t)(-1)`. ## Remarks -The **clock** function tells how much wall-clock time has passed since the CRT initialization during process start. Note that this function does not strictly conform to ISO C, which specifies net CPU time as the return value. To obtain CPU times, use the Win32 [GetProcessTimes](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes) function. To determine the elapsed time in seconds, divide the value returned by the **clock** function by the macro **CLOCKS_PER_SEC**. +The **`clock`** function tells how much wall-clock time has passed since the CRT initialization during process start. This function doesn't strictly conform to ISO C, which specifies net CPU time as the return value. To obtain CPU times, use the Win32 [`GetProcessTimes`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes) function. To determine the elapsed time in seconds, divide the value returned by the **`clock`** function by the macro `CLOCKS_PER_SEC`. -Given enough time, the value returned by **clock** can exceed the maximum positive value of **clock_t**. When the process has run longer, the value returned by **clock** is always `(clock_t)(-1)`, as specified by the ISO C99 standard (7.23.2.1) and ISO C11 standard (7.27.2.1). Microsoft implements **clock_t** as a **`long`**, a signed 32-bit integer, and the **CLOCKS_PER_SEC** macro is defined as 1000. This gives a maximum **clock** function return value of 2147483.647 seconds, or about 24.8 days. Do not rely on the value returned by **clock** in processes that have run for longer than this amount of time. You can use the 64-bit [time](time-time32-time64.md) function or the Windows [QueryPerformanceCounter](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) function to record process elapsed times of many years. +Given enough time, the value returned by **`clock`** can exceed the maximum positive value of `clock_t`. When the process has run longer, the value returned by **`clock`** is always `(clock_t)(-1)`, as specified by the ISO C99 standard (7.23.2.1) and ISO C11 standard (7.27.2.1). Microsoft implements `clock_t` as a **`long`**, a signed 32-bit integer, and the `CLOCKS_PER_SEC` macro is defined as 1000. This macro gives a maximum **`clock`** function return value of 2147483.647 seconds, or about 24.8 days. Don't rely on the value returned by **`clock`** in processes that have run for longer than this amount of time. You can use the 64-bit [`time`](time-time32-time64.md) function or the Windows [`QueryPerformanceCounter`](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) function to record process elapsed times of many years. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**clock**|\| +| Routine | Required header | +|---|---| +| **`clock`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,6 +90,6 @@ Time to do 600000000 empty loops is 1.354 seconds ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[difftime, _difftime32, _difftime64](difftime-difftime32-difftime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`difftime`, `_difftime32`, `_difftime64`](difftime-difftime32-difftime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/clog-clogf-clogl.md b/docs/c-runtime-library/reference/clog-clogf-clogl.md index 4683d3eac6..833e6b3e77 100644 --- a/docs/c-runtime-library/reference/clog-clogf-clogl.md +++ b/docs/c-runtime-library/reference/clog-clogf-clogl.md @@ -10,7 +10,7 @@ f1_keywords: ["clog", "clogf", "clogl", "complex/clog", "complex/clogf", "comple helpviewer_keywords: ["clog function", "clogf function", "clogl function"] ms.assetid: 870b9b0b-6618-46f3-bfcf-da595cbd5e18 --- -# clog, clogf, clogl +# `clog`, `clogf`, `clogl` Retrieves the natural logarithm of a complex number, with a branch cut along the negative real axis. @@ -36,38 +36,38 @@ _Lcomplex clogl( ### Parameters -*z*\ +*`z`*\ The base of the logarithm. -## Return Value +## Return value -The natural logarithm of *z*. The result is unbounded along the real axis and in the interval [-iπ, +iπ] along the imaginary axis. +The natural logarithm of *`z`*. The result is unbounded along the real axis and in the interval [-iπ, +iπ] along the imaginary axis. The possible return values are: -|z parameter|Return value| -|-----------------|------------------| -|Positive|The base 10 logarithm of z| -|Zero|- ∞| -|Negative|NaN| -|NaN|NaN| -|+ ∞|+ ∞| +| *`z`* parameter | Return value | +|---|---| +| Positive | The logarithm (base 10) of *`z`* | +| Zero | - INF | +| Negative | NaN | +| NaN | NaN | +| + INF | + INF | ## Remarks -Because C++ allows overloading, you can call overloads of **clog** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **clog** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`clog`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`clog`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**clog**, **clogf**, **clogl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`clog`**, **`clogf`**, **`clogl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[cexp, cexpf, cexpl](cexp-cexpf-cexpl.md)
-[cpow, cpowf, cpowl](cpow-cpowf-cpowl.md)
-[clog10, clog10f, clog10l](clog10-clog10f-clog10l.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`cexp`, `cexpf`, `cexpl`](cexp-cexpf-cexpl.md)\ +[`cpow`, `cpowf`, `cpowl`](cpow-cpowf-cpowl.md)\ +[`clog10`, `clog10f`, `clog10l`](clog10-clog10f-clog10l.md) diff --git a/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md b/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md index 1b46c62537..d5588e2316 100644 --- a/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md +++ b/docs/c-runtime-library/reference/clog10-clog10f-clog10l.md @@ -10,9 +10,9 @@ f1_keywords: ["clog10", "clog10f", "clog10l", "complex/clog10", "complex/clog10f helpviewer_keywords: ["clog10 function", "clog10f function", "clog10l function"] ms.assetid: 2ddae00d-ef93-4441-add3-f4d58358401b --- -# clog10, clog10f, clog10l +# `clog10`, `clog10f`, `clog10l` -Retrieves the base 10 logarithm of a complex number. +Retrieves the logarithm (base 10) of a complex number. ## Syntax @@ -29,36 +29,36 @@ _Lcomplex clog10( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ The base of the logarithm. -## Return Value +## Return value The possible return values are: -|z parameter|Return value| -|-----------------|------------------| -|Positive|The base 10 logarithm of z| -|Zero|- ∞| -|Negative|NaN| -|NaN|NaN| -|+ ∞|+ ∞| +| *`z`* parameter | Return value | +|---|---| +| Positive | The logarithm (base 10) of *`z`* | +| Zero | - INF | +| Negative | NaN | +| NaN | NaN | +| + INF | + INF | ## Remarks -Because C++ allows overloading, you can call overloads of **clog10** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **clog10** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`clog10`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`clog10`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**clog10**, **clog10f**, **clogl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`clog10`**, **`clog10f`**, **`clog10l`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[cexp, cexpf, cexpl](cexp-cexpf-cexpl.md)
-[cpow, cpowf, cpowl](cpow-cpowf-cpowl.md)
-[clog, clogf, clogl](clog-clogf-clogl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`cexp`, `cexpf`, `cexpl`](cexp-cexpf-cexpl.md)\ +[`cpow`, `cpowf`, `cpowl`](cpow-cpowf-cpowl.md)\ +[`clog`, `clogf`, `clogl`](clog-clogf-clogl.md) diff --git a/docs/c-runtime-library/reference/close.md b/docs/c-runtime-library/reference/close.md index a6b228b62e..3e1554f974 100644 --- a/docs/c-runtime-library/reference/close.md +++ b/docs/c-runtime-library/reference/close.md @@ -3,14 +3,14 @@ description: "Learn more about: _close" title: "_close" ms.date: "4/2/2020" api_name: ["_close", "_o__close"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_close"] helpviewer_keywords: ["_close function", "close function", "files [C++], closing"] ms.assetid: 4708a329-8acf-4cd9-b7b0-a952e1897247 --- -# _close +# `_close` Closes a file. @@ -24,40 +24,40 @@ int _close( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to the open file. -## Return Value +## Return value -**_close** returns 0 if the file was successfully closed. A return value of -1 indicates an error. +**`_close`** returns 0 if the file was successfully closed. A return value of -1 indicates an error. ## Remarks -The **_close** function closes the file associated with *fd*. +The **`_close`** function closes the file associated with *`fd`*. -The file descriptor and the underlying OS file handle are closed. Thus, it is not necessary to call **CloseHandle** if the file was originally opened using the Win32 function **CreateFile** and converted to a file descriptor using **_open_osfhandle**. +The file descriptor and the underlying OS file handle are closed. Thus, it isn't necessary to call `CloseHandle` if the file was originally opened using the Win32 function `CreateFile` and converted to a file descriptor using `_open_osfhandle`. -This function validates its parameters. If *fd* is a bad file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions returns -1 and **errno** is set to **EBADF**. +This function validates its parameters. If *`fd`* is a bad file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions returns -1 and `errno` is set to `EBADF`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_close**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_close`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_open](open-wopen.md). +See the example for [`_open`](open-wopen.md). ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_chsize](chsize.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_dup, _dup2](dup-dup2.md)
-[_open, _wopen](open-wopen.md)
-[_unlink, _wunlink](unlink-wunlink.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_chsize`](chsize.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_dup`, `_dup2`](dup-dup2.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_unlink`, `_wunlink`](unlink-wunlink.md) diff --git a/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md b/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md index 244a9dd2e5..cfffc2b315 100644 --- a/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md +++ b/docs/c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["_Cmulcc", "_FCmulcc", "_LCmulcc", "complex/_Cmulcc", "complex/_FCmulcc", "complex/_LCmulcc"] helpviewer_keywords: ["_Cmulcc function", "_FCmulcc function", "_LCmulcc function"] --- -# _Cmulcc, _FCmulcc, _LCmulcc +# `_Cmulcc`, `_FCmulcc`, `_LCmulcc` Multiplies two complex numbers. @@ -23,37 +23,37 @@ _Lcomplex _LCmulcc( _Lcomplex x, _Lcomplex y ); ### Parameters -*x*
+*`x`*\ One of the complex operands to multiply. -*y*
+*`y`*\ The other complex operand to multiply. -## Return Value +## Return value -A **_Dcomplex**, **_Fcomplex**, or **_Lcomplex** structure that represents the complex product of the complex numbers *x* and *y*. +A `_Dcomplex`, `_Fcomplex`, or `_Lcomplex` structure that represents the complex product of the complex numbers *`x`* and *`y`*. ## Remarks -Because the built-in arithmetic operators do not work on the Microsoft implementation of the complex types, the **_Cmulcc**, **_FCmulcc**, and **_LCmulcc** functions simplify multiplication of complex types. +Because the built-in arithmetic operators don't work on the Microsoft implementation of the complex types, the **`_Cmulcc`**, **`_FCmulcc`**, and **`_LCmulcc`** functions simplify multiplication of complex types. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**_Cmulcc**, **_FCmulcc**, **_LCmulcc**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`_Cmulcc`**, **`_FCmulcc`**, **`_LCmulcc`** | \ | \ | -These functions are Microsoft-specific. The types **_Dcomplex**, **_Fcomplex**, and **_Lcomplex** are Microsoft-specific equivalents to the unimplemented C99 native types **double _Complex**, **float _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. The types `_Dcomplex`, `_Fcomplex`, and `_Lcomplex` are Microsoft-specific equivalents to the unimplemented C99 native types **double _Complex**, **float _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_Cbuild, _FCbuild, _LCbuild](cbuild-fcbuild-lcbuild.md)
-[_Cmulcr, _FCmulcr, _LCmulcr](cmulcr-fcmulcr-lcmulcr.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_Cbuild`, `_FCbuild`, `_LCbuild`](cbuild-fcbuild-lcbuild.md)\ +[`_Cmulcr`, `_FCmulcr`, `_LCmulcr`](cmulcr-fcmulcr-lcmulcr.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md b/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md index e4446b567f..c6323ec167 100644 --- a/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md +++ b/docs/c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["_Cmulcr", "_FCmulcr", "_LCmulcr", "complex/_Cmulcr", "complex/_FCmulcr", "complex/_LCmulcr"] helpviewer_keywords: ["_Cmulcr function", "_FCmulcr function", "_LCmulcr function"] --- -# _Cmulcr, _FCmulcr, _LCmulcr +# `_Cmulcr`, `_FCmulcr`, `_LCmulcr` Multiplies a complex number by a floating-point number. @@ -23,37 +23,37 @@ _Lcomplex _LCmulcr( _Lcomplex x, long double y ); ### Parameters -*x*
+*`x`*\ One of the complex operands to multiply. -*y*
+*`y`*\ The floating-point operand to multiply. -## Return Value +## Return value -A **_Dcomplex**, **_Fcomplex**, or **_Lcomplex** structure that represents the complex product of the complex number *x* and flaoting-point number *y*. +A `_Dcomplex`, `_Fcomplex`, or `_Lcomplex` structure that represents the complex product of the complex number *`x`* and floating-point number *`y`*. ## Remarks -Because the built-in arithmetic operators do not work on the Microsoft implementation of the complex types, the **_Cmulcr**, **_FCmulcr**, and **_LCmulcr** functions simplify multiplication of complex types by floating-point types. +Because the built-in arithmetic operators don't work on the Microsoft implementation of the complex types, the **`_Cmulcr`**, **`_FCmulcr`**, and **`_LCmulcr`** functions simplify multiplication of complex types by floating-point types. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**_Cmulcr**, **_FCmulcr**, **_LCmulcr**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`_Cmulcr`**, **`_FCmulcr`**, **`_LCmulcr`** | \ | \ | -These functions are Microsoft-specific. The types **_Dcomplex**, **_Fcomplex**, and **_Lcomplex** are Microsoft-specific equivalents to the unimplemented C99 native types **double _Complex**, **float _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. The types `_Dcomplex`, `_Fcomplex`, and `_Lcomplex` are Microsoft-specific equivalents to the unimplemented C99 native types **`double _Complex`**, **`float _Complex`**, and **`long double _Complex`**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_Cbuild, _FCbuild, _LCbuild](cbuild-fcbuild-lcbuild.md)
-[_Cmulcc, _FCmulcc, _LCmulcc](cmulcc-fcmulcc-lcmulcc.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_Cbuild`, `_FCbuild`, `_LCbuild`](cbuild-fcbuild-lcbuild.md)\ +[`_Cmulcc`, `_FCmulcc`, `_LCmulcc`](cmulcc-fcmulcc-lcmulcc.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/commit.md b/docs/c-runtime-library/reference/commit.md index 5b720de20f..951a4063bd 100644 --- a/docs/c-runtime-library/reference/commit.md +++ b/docs/c-runtime-library/reference/commit.md @@ -3,14 +3,14 @@ description: "Learn more about: _commit" title: "_commit" ms.date: "4/2/2020" api_name: ["_commit", "_o__commit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_commit", "commit"] helpviewer_keywords: ["files [C++], flushing", "flushing files to disk", "commit function", "_commit function", "committing files to disk"] ms.assetid: d0c74d3a-4f2d-4fb0-b140-2d687db3d233 --- -# _commit +# `_commit` Flushes a file directly to disk. @@ -24,33 +24,33 @@ int _commit( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to the open file. -## Return Value +## Return value -**_commit** returns 0 if the file was successfully flushed to disk. A return value of -1 indicates an error. +**`_commit`** returns 0 if the file was successfully flushed to disk. A return value of -1 indicates an error. ## Remarks -The **_commit** function forces the operating system to write the file associated with *fd* to disk. This call ensures that the specified file is flushed immediately, not at the operating system's discretion. +The **`_commit`** function forces the operating system to write the file associated with *`fd`* to disk. This call ensures that the specified file is flushed immediately, not at the operating system's discretion. -If *fd* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and **errno** is set to **EBADF**. +If *`fd`* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and `errno` is set to `EBADF`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_commit**|\|\| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_commit`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
-[_read](read.md)
-[_write](write.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_read`](read.md)\ +[`_write`](write.md) diff --git a/docs/c-runtime-library/reference/compl.md b/docs/c-runtime-library/reference/compl.md index b5dda3e080..290367a95d 100644 --- a/docs/c-runtime-library/reference/compl.md +++ b/docs/c-runtime-library/reference/compl.md @@ -6,11 +6,11 @@ api_name: ["compl"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::compl", "std.compl", "compl"] +f1_keywords: ["std::compl", "std.compl", "ISO646/compl", "compl"] helpviewer_keywords: ["compl function"] ms.assetid: e03f6fb5-cb8b-4afa-99c0-905f4105fb34 --- -# compl +# `compl` An alternative to the ~ operator. diff --git a/docs/c-runtime-library/reference/configthreadlocale.md b/docs/c-runtime-library/reference/configthreadlocale.md index 088eb2931b..20c0d8bf79 100644 --- a/docs/c-runtime-library/reference/configthreadlocale.md +++ b/docs/c-runtime-library/reference/configthreadlocale.md @@ -3,7 +3,7 @@ title: "_configthreadlocale" ms.date: "10/29/2020" description: "Describes the Microsoft C runtime function `_configthreadlocale` used to configure per-thread locale options." api_name: ["_configthreadlocale", "_o__configthreadlocale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_configthreadlocale", "configthreadlocale"] @@ -25,9 +25,9 @@ int _configthreadlocale( int per_thread_locale_type ); *`per_thread_locale_type`*\ The option to set. One of the options listed in the following table. -## Return Value +## Return value -The previous per-thread locale status (**`_DISABLE_PER_THREAD_LOCALE`** or **`_ENABLE_PER_THREAD_LOCALE`**), or -1 on failure. +The previous per-thread locale status (`_DISABLE_PER_THREAD_LOCALE` or `_ENABLE_PER_THREAD_LOCALE`), or -1 on failure. ## Remarks @@ -35,23 +35,23 @@ The **`_configthreadlocale`** function is used to control the use of thread-spec | Option | Description | |-|-| -| **`_ENABLE_PER_THREAD_LOCALE`** | Make the current thread use a thread-specific locale. Subsequent calls to **`setlocale`** in this thread affect only the thread's own locale. | -| **`_DISABLE_PER_THREAD_LOCALE`** | Make the current thread use the global locale. Subsequent calls to **`setlocale`** in this thread affect other threads using the global locale. | +| `_ENABLE_PER_THREAD_LOCALE` | Make the current thread use a thread-specific locale. Subsequent calls to **`setlocale`** in this thread affect only the thread's own locale. | +| `_DISABLE_PER_THREAD_LOCALE` | Make the current thread use the global locale. Subsequent calls to **`setlocale`** in this thread affect other threads using the global locale. | | **0** | Retrieves the current setting for this particular thread. | These functions affect the behavior of **`setlocale`**, **`_tsetlocale`**, **`_wsetlocale`**, and **`_setmbcp`**. When per-thread locale is disabled, any subsequent call to **`setlocale`** or **`_wsetlocale`** changes the locale of all threads that use the global locale. When per-thread locale is enabled, **`setlocale`** or **`_wsetlocale`** only affects the current thread's locale. -If you use **`_configthreadlocale`** to enable a per-thread locale, we recommend that you call **`setlocale`** or **`_wsetlocale`** to set the preferred locale in that thread immediately afterward. +If you use **`_configthreadlocale`** to enable a per-thread locale, set the preferred locale in that thread immediately afterward by a call to **`setlocale`** or **`_wsetlocale`**. -If *`per_thread_locale_type`* isn't one of the values listed in the table, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns -1. +If *`per_thread_locale_type`* isn't one of the values listed in the table, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_configthreadlocale`**|\``| +| Routine | Required header | +|---|---| +| **`_configthreadlocale`** | \`` | ## Example @@ -166,5 +166,5 @@ The time in German locale is: 'Mittwoch, 12. Mai 2004' [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ [`_beginthread`, `_beginthreadex`](beginthread-beginthreadex.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Locale](../locale.md)\ [Multithreading and locales](../../parallel/multithreading-and-locales.md) diff --git a/docs/c-runtime-library/reference/conj-conjf-conjl.md b/docs/c-runtime-library/reference/conj-conjf-conjl.md index 55ad3569ff..60b5e95ad9 100644 --- a/docs/c-runtime-library/reference/conj-conjf-conjl.md +++ b/docs/c-runtime-library/reference/conj-conjf-conjl.md @@ -10,7 +10,7 @@ f1_keywords: ["conj", "conjf", "conjl", "complex/conj", "complex/conjf", "comple helpviewer_keywords: ["conj function", "conjf function", "conjl function"] ms.assetid: 792fccfa-19c6-4890-99f9-a3b89effccd6 --- -# conj, conjf, conjl +# `conj`, `conjf`, `conjl` Retrieves the complex conjugate of a complex number. @@ -37,34 +37,34 @@ _Lcomplex conjl( ### Parameters -*z*\ +*`z`*\ A complex number. -## Return Value +## Return value -The complex conjugate of *z*. The result has the same real and imaginary part as *z*, but with the opposite sign. +The complex conjugate of *`z`*. The result has the same real and imaginary part as *`z`*, but with the opposite sign. ## Remarks -Because C++ allows overloading, you can call overloads of **conj** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, unless you're using the \ macro to call this function, **conj** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`conj`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, unless you're using the \ macro to call this function, **`conj`** always takes and returns a `_Dcomplex` value. -If you use the \ `conj()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `conj()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**conj**, **conjf**, **conjl**|\|\| -|**conj** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`conj`**, **`conjf`**, **`conjl`** | \ | \ | +| **`conj`** macro | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/control87-controlfp-control87-2.md b/docs/c-runtime-library/reference/control87-controlfp-control87-2.md index 5453bf6876..4f3f7cc98a 100644 --- a/docs/c-runtime-library/reference/control87-controlfp-control87-2.md +++ b/docs/c-runtime-library/reference/control87-controlfp-control87-2.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_control87", "__control87_2", "control87", "_controlfp", "controlfp", "control87_2", "_control87_2"] helpviewer_keywords: ["floating-point numbers, control word", "_control87 function", "control87 function", "controlfp function", "_controlfp function", "__control87_2 function", "floating-point functions, setting control word", "floating-point functions", "EM_AMBIGUOUS", "control87_2 function"] -ms.assetid: 0d09729d-d9a0-43d6-864c-43ff25e7e0c5 --- -# _control87, _controlfp, __control87_2 +# `_control87`, `_controlfp`, `__control87_2` -Gets and sets the floating-point control word. A more secure version of **_controlfp** is available; see [_controlfp_s](controlfp-s.md). +Gets and sets the floating-point control word. A more secure version of **`_controlfp`** is available; see [`_controlfp_s`](controlfp-s.md). ## Syntax @@ -35,32 +34,32 @@ int __control87_2( ### Parameters -*new*\ +*`new`*\ New control-word bit values. -*mask*\ +*`mask`*\ Mask for new control-word bits to set. -*x86_cw*\ -Filled in with the control word for the x87 floating-point unit. Pass in 0 (**NULL**) to set only the SSE2 control word. +*`x86_cw`*\ +Filled in with the control word for the x87 floating-point unit. Pass in 0 (`NULL`) to set only the SSE2 control word. -*sse2_cw*\ -Control word for the SSE floating-point unit. Pass in 0 (**NULL**) to set only the x87 control word. +*`sse2_cw`*\ +Control word for the SSE floating-point unit. Pass in 0 (`NULL`) to set only the x87 control word. ## Return value -For **_control87** and **_controlfp**, the bits in the value returned indicate the floating-point control state. For a complete definition of the bits that are returned by **_control87**, see FLOAT.H. +For **`_control87`** and **`_controlfp`**, the bits in the value returned indicate the floating-point control state. For a complete definition of the bits that are returned by **`_control87`**, see `FLOAT.H`. -For **__control87_2**, the return value is 1, which indicates success. +For **`__control87_2`**, the return value is 1, which indicates success. ## Remarks -The **_control87** function gets and sets the floating-point control word. The floating-point control word enables the program to change the precision, rounding, and infinity modes, depending on the platform. You can also use **_control87** to mask or unmask floating-point exceptions. If the value for *mask* is equal to 0, **_control87** gets the floating-point control word. If *mask* is nonzero, a new value for the control word is set: For any bit that is on (that is, equal to 1) in *mask*, the corresponding bit in *new* is used to update the control word. In other words, **fpcntrl** = ((**fpcntrl** & ~*mask*) | (*new* & *mask*)) where **fpcntrl** is the floating-point control word. +The **`_control87`** function gets and sets the floating-point control word. The floating-point control word enables the program to change the precision, rounding, and infinity modes, depending on the platform. You can also use **`_control87`** to mask or unmask floating-point exceptions. If the value for *`mask`* is equal to 0, **`_control87`** gets the floating-point control word. If *`mask`* is nonzero, a new value for the control word is set: For any bit that is on (that is, equal to 1) in *`mask`*, the corresponding bit in *`new`* is used to update the control word. In other words, `fpcntrl = ((fpcntrl & ~mask) | (new & mask))` where **`fpcntrl`** is the floating-point control word. > [!NOTE] > By default, the run-time libraries mask all floating-point exceptions. -**_controlfp** is a platform-independent, portable version of **_control87** that's nearly identical to the **_control87** function. If your code targets more than one platform, use **_controlfp** or **_controlfp_s**. The difference between **_control87** and **_controlfp** is in how they treat DENORMAL values. For x86, x64, ARM, and ARM64 platforms, **_control87** can set and clear the DENORMAL OPERAND exception mask. **_controlfp** doesn't modify the DENORMAL OPERAND exception mask. This example demonstrates the difference: +**`_controlfp`** is a platform-independent, portable version of **`_control87`** that's nearly identical to the **`_control87`** function. If your code targets more than one platform, use **`_controlfp`** or **`_controlfp_s`**. The difference between **`_control87`** and **`_controlfp`** is in how they treat `DENORMAL` values. For x86, x64, ARM, and ARM64 platforms, **`_control87`** can set and clear the `DENORMAL OPERAND` exception mask. **`_controlfp`** doesn't modify the `DENORMAL OPERAND` exception mask. This example demonstrates the difference: ```C _control87( _EM_INVALID, _MCW_EM ); @@ -69,9 +68,9 @@ _controlfp( _EM_INVALID, _MCW_EM ); // DENORMAL exception mask remains unchanged ``` -The possible values for the mask constant (*mask*) and new control values (*new*) are shown in the Control word masks and values table. Use the portable constants listed below (**_MCW_EM**, **_EM_INVALID**, and so forth) as arguments to these functions, rather than supplying the hexadecimal values explicitly. +The possible values for the mask constant (*`mask`*) and new control values (*`new`*) are shown in the Control word masks and values table. Use the portable constants listed below (`_MCW_EM`, `_EM_INVALID`, and so forth) as arguments to these functions, rather than supplying the hexadecimal values explicitly. -Intel x86-derived platforms support the DENORMAL input and output values in hardware. The x86 behavior is to preserve DENORMAL values. The ARM and ARM64 platforms and the x64 platforms that have SSE2 support enable DENORMAL operands and results to be flushed, or forced to zero. The **_controlfp** and **_control87** functions provide a mask to change this behavior. The following example demonstrates the use of this mask. +Intel x86-derived platforms support the `DENORMAL` input and output values in hardware. The x86 behavior is to preserve `DENORMAL` values. The ARM and ARM64 platforms and the x64 platforms that have SSE2 support enable `DENORMAL` operands and results to be flushed, or forced to zero. The **`_controlfp`** and **`_control87`** functions provide a mask to change this behavior. The following example demonstrates the use of this mask. ```C _controlfp(_DN_SAVE, _MCW_DN); @@ -82,38 +81,38 @@ _controlfp(_DN_FLUSH, _MCW_DN); // and x64 processors with SSE2 support. Ignored on other x86 platforms. ``` -On ARM and ARM64 platforms, the **_control87** and **_controlfp** functions apply to the FPSCR register. Only the SSE2 control word that's stored in the MXCSR register is affected on x64 platforms. On x86 platforms, **_control87** and **_controlfp** affect the control words for both the x87 and the SSE2, if present. +On ARM and ARM64 platforms, the **`_control87`** and **`_controlfp`** functions apply to the FPSCR register. Only the SSE2 control word that's stored in the MXCSR register is affected on x64 platforms. On x86 platforms, **`_control87`** and **`_controlfp`** affect the control words for both the x87 and the SSE2, if present. -The function **__control87_2** enables both the x87 and SSE2 floating-point units to be controlled together or separately. To affect both units, pass in the addresses of two integers to **x86_cw** and **sse2_cw**. If you only want to affect one unit, pass in an address for that parameter, but pass in 0 (**NULL**) for the other. If 0 is passed for one of these parameters, the function has no effect on that floating-point unit. It's useful when part of your code uses the x87 floating-point unit, and another part uses the SSE2 floating-point unit. +The function **`__control87_2`** enables both the x87 and SSE2 floating-point units to be controlled together or separately. To affect both units, pass in the addresses of two integers to **`x86_cw`** and **`sse2_cw`**. If you only want to affect one unit, pass in an address for that parameter, but pass in 0 (`NULL`) for the other. If 0 is passed for one of these parameters, the function has no effect on that floating-point unit. It's useful when part of your code uses the x87 floating-point unit, and another part uses the SSE2 floating-point unit. -If you use **__control87_2** to set different values for the floating-point control words, then **_control87** or **_controlfp** might be unable to return a single control word to represent the state of both floating-point units. In such a case, these functions set the **EM_AMBIGUOUS** flag in the returned integer value to indicate an inconsistency between the two control words. The **EM_AMBIGUOUS** flag is a warning that the returned control word might not represent the state of both floating-point control words accurately. +If you use **`__control87_2`** to set different values for the floating-point control words, then **`_control87`** or **`_controlfp`** might be unable to return a single control word to represent the state of both floating-point units. In such a case, these functions set the `EM_AMBIGUOUS` flag in the returned integer value to indicate an inconsistency between the two control words. The `EM_AMBIGUOUS` flag is a warning that the returned control word might not represent the state of both floating-point control words accurately. -On the ARM, ARM64, and x64 platforms, changing the infinity mode or the floating-point precision isn't supported. If the precision control mask is used on the x64 platform, the function raises an assertion, and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +On the ARM, ARM64, and x64 platforms, changing the infinity mode or the floating-point precision isn't supported. If the precision control mask is used on the x64 platform, the function raises an assertion, and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). > [!NOTE] -> **__control87_2** is not supported on the ARM, ARM64, or x64 platforms. If you use **__control87_2** and compile your program for the ARM, ARM64, or x64 platforms, the compiler generates an error. +> **`__control87_2`** is not supported on the ARM, ARM64, or x64 platforms. If you use **`__control87_2`** and compile your program for the ARM, ARM64, or x64 platforms, the compiler generates an error. -These functions are ignored when you use [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) to compile. The common language runtime (CLR) only supports the default floating-point precision. +These functions are ignored when you use [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) to compile. The common language runtime (CLR) only supports the default floating-point precision. ### Control word masks and values -For the **_MCW_EM** mask, clearing the mask sets the exception, which allows the hardware exception; setting the mask hides the exception. If a **_EM_UNDERFLOW** or **_EM_OVERFLOW** occurs, no hardware exception is thrown until the next floating-point instruction is executed. To generate a hardware exception immediately after **_EM_UNDERFLOW** or **_EM_OVERFLOW**, call the **FWAIT** MASM instruction. +For the `_MCW_EM` mask, clearing the mask sets the exception, which allows the hardware exception; setting the mask hides the exception. If a `_EM_UNDERFLOW` or `_EM_OVERFLOW` occurs, no hardware exception is thrown until the next floating-point instruction is executed. To generate a hardware exception immediately after `_EM_UNDERFLOW` or `_EM_OVERFLOW`, call the `FWAIT` MASM instruction. -|Mask|Hex value|Constant|Hex value| -|----------|---------------|--------------|---------------| -|**_MCW_DN** (Denormal control)|0x03000000|**_DN_SAVE**

**_DN_FLUSH**|0x00000000

0x01000000| -|**_MCW_EM** (Interrupt exception mask)|0x0008001F|**_EM_INVALID**

**_EM_DENORMAL**

**_EM_ZERODIVIDE**

**_EM_OVERFLOW**

**_EM_UNDERFLOW**

**_EM_INEXACT**|0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

0x00000001| -|**_MCW_IC** (Infinity control)

(Not supported on ARM or x64 platforms.)|0x00040000|**_IC_AFFINE**

**_IC_PROJECTIVE**|0x00040000

0x00000000| -|**_MCW_RC** (Rounding control)|0x00000300|**_RC_CHOP**

**_RC_UP**

**_RC_DOWN**

**_RC_NEAR**|0x00000300

0x00000200

0x00000100

0x00000000| -|**_MCW_PC** (Precision control)

(Not supported on ARM or x64 platforms.)|0x00030000|**_PC_24** (24 bits)

**_PC_53** (53 bits)

**_PC_64** (64 bits)|0x00020000

0x00010000

0x00000000| +| Mask | Hex value | Constant | Hex value | +|---|---|---|---| +| `_MCW_DN` (Denormal control) | 0x03000000 | `_DN_SAVE`

`_DN_FLUSH` | 0x00000000

0x01000000 | +| `_MCW_EM` (Interrupt exception mask) | 0x0008001F | `_EM_INVALID`

`_EM_DENORMAL`

`_EM_ZERODIVIDE`

`_EM_OVERFLOW`

`_EM_UNDERFLOW`

`_EM_INEXACT` | 0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

0x00000001 | +| `_MCW_IC` (Infinity control)

(Not supported on ARM or x64 platforms.) | 0x00040000 | `_IC_AFFINE`

`_IC_PROJECTIVE` | 0x00040000

0x00000000 | +| `_MCW_RC` (Rounding control) | 0x00000300 | `_RC_CHOP`

`_RC_UP`

`_RC_DOWN`

`_RC_NEAR` | 0x00000300

0x00000200

0x00000100

0x00000000 | +| `_MCW_PC` (Precision control)

(Not supported on ARM or x64 platforms.) | 0x00030000 | `_PC_24` (24 bits)

`_PC_53` (53 bits)

`_PC_64` (64 bits) | 0x00020000

0x00010000

0x00000000 | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_control87**, **_controlfp**, **_control87_2**|\| +| Routine | Required header | +|---|---| +| **`_control87`**, **`_controlfp`**, **`_control87_2`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -163,7 +162,7 @@ Default: 0x0009001f ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[_clear87, _clearfp](clear87-clearfp.md)\ -[_status87, _statusfp, _statusfp2](status87-statusfp-statusfp2.md)\ -[_controlfp_s](controlfp-s.md) +[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_status87`, `_statusfp`, `_statusfp2`](status87-statusfp-statusfp2.md)\ +[`_controlfp_s`](controlfp-s.md) diff --git a/docs/c-runtime-library/reference/controlfp-s.md b/docs/c-runtime-library/reference/controlfp-s.md index 1fca08a199..8de3df8b7c 100644 --- a/docs/c-runtime-library/reference/controlfp-s.md +++ b/docs/c-runtime-library/reference/controlfp-s.md @@ -1,18 +1,17 @@ --- description: "Learn more about: _controlfp_s" title: "_controlfp_s" -ms.date: "4/2/2020" +ms.date: 03/27/2025 api_name: ["_controlfp_s", "_o__controlfp_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["controlfp_s", "_controlfp_s"] helpviewer_keywords: ["floating-point numbers, control word", "controlfp_s function", "floating-point functions, setting control word", "EM_AMBIGUOUS", "_controlfp_s function"] -ms.assetid: a51fc3f6-ab13-41f0-b227-6bf02d98e987 --- -# _controlfp_s +# `_controlfp_s` -Gets and sets the floating-point control word. This version of [_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md) has security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Gets and sets the floating-point control word. This version of [`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md) has security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -26,33 +25,33 @@ errno_t _controlfp_s( ### Parameters -*currentControl*
+*`currentControl`*\ The current control-word bit value. -*newControl*
+*`newControl`*\ New control-word bit values. -*mask*
+*`mask`*\ Mask for new control-word bits to set. -## Return Value +## Return value -Zero if successful, or an **errno** value error code. +Zero if successful, or an `errno` value error code. ## Remarks -The **_controlfp_s** function is a platform-independent and more secure version of **_control87**, which gets the floating-point control word into the address that's stored in *currentControl* and sets it by using *newControl*. The bits in the values indicate the floating-point control state. The floating-point control state enables the program to change the precision, rounding, and infinity modes in the floating-point math package, depending on the platform. You can also use **_controlfp_s** to mask or unmask floating-point exceptions. +The **`_controlfp_s`** function is a platform-independent and more secure version of **`_control87`**, which gets the floating-point control word into the address that's stored in *`currentControl`* and sets it by using *`newControl`*. The bits in the values indicate the floating-point control state. The floating-point control state enables the program to change the precision, rounding, and infinity modes in the floating-point math package, depending on the platform. You can also use **`_controlfp_s`** to mask or unmask floating-point exceptions. -If the value for *mask* is equal to 0, **_controlfp_s** gets the floating-point control word and stores the retrieved value in *currentControl*. +If the value for *`mask`* is equal to 0, **`_controlfp_s`** gets the floating-point control word and stores the retrieved value in *`currentControl`*. -If *mask* is nonzero, a new value for the control word is set: For any bit that is set (that is, equal to 1) in *mask*, the corresponding bit in *new* is used to update the control word. In other words, *fpcntrl* = ((*fpcntrl* & ~*mask*) | (*newControl* & *mask*)) where *fpcntrl* is the floating-point control word. In this scenario, *currentControl* is set to the value after the change completes; it is not the old control-word bit value. +If *`mask`* is nonzero, a new value for the control word is set: For any bit that is set (that is, equal to 1) in *`mask`*, the corresponding bit in *`new`* is used to update the control word. In other words, `fpcntrl = ((fpcntrl & ~mask) | (newControl & mask))` where *`fpcntrl`* is the floating-point control word. In this scenario, *`currentControl`* is set to the value after the change completes; it isn't the old control-word bit value. > [!NOTE] > By default, the run-time libraries mask all floating-point exceptions. -**_controlfp_s** is nearly identical to the **_control87** function on Intel (x86), x64, and ARM platforms. If you are targeting x86, x64, or ARM platforms, you can use **_control87** or **_controlfp_s**. +**`_controlfp_s`** is nearly identical to the **`_control87`** function on Intel (x86), x64, and ARM platforms. If you're targeting x86, x64, or ARM platforms, you can use **`_control87`** or **`_controlfp_s`**. -The difference between **_control87** and **_controlfp_s** is in how they treat denormal values. For Intel (x86), x64, and ARM platforms, **_control87** can set and clear the DENORMAL OPERAND exception mask. **_controlfp_s** does not modify the DENORMAL OPERAND exception mask. This example demonstrates the difference: +The difference between **`_control87`** and **`_controlfp_s`** is in how they treat denormal values. For Intel (x86), x64, and ARM platforms, **`_control87`** can set and clear the `DENORMAL OPERAND` exception mask. **`_controlfp_s`** doesn't modify the `DENORMAL OPERAND` exception mask. This example demonstrates the difference: ```C _control87( _EM_INVALID, _MCW_EM ); @@ -62,9 +61,9 @@ _controlfp_s( ¤t_word, _EM_INVALID, _MCW_EM ); // DENORMAL exception mask remains unchanged. ``` -The possible values for the mask constant (*mask*) and new control values (*newControl*) are shown in the following Hexadecimal Values table. Use the portable constants listed below (**_MCW_EM**, **_EM_INVALID**, and so on) as arguments to these functions, rather than supplying the hexadecimal values explicitly. +The possible values for the mask constant (*`mask`*) and new control values (*`newControl`*) are shown in the following Hexadecimal Values table. Use the portable constants listed below (`_MCW_EM`, `_EM_INVALID`, and so on) as arguments to these functions, rather than supplying the hexadecimal values explicitly. -Intel (x86)-derived platforms support the DENORMAL input and output values in hardware. The x86 behavior is to preserve DENORMAL values. The ARM platform and the x64 platforms that have SSE2 support enable DENORMAL operands and results to be flushed, or forced to zero. The **_controlfp_s**, **_controlfp**, and **_control87** functions provide a mask to change this behavior. The following example demonstrates the use of this mask: +Intel (x86)-derived platforms support the `DENORMAL` input and output values in hardware. The x86 behavior is to preserve `DENORMAL` values. The ARM platform and the x64 platforms that have SSE2 support enable `DENORMAL` operands and results to be flushed, or forced to zero. The **`_controlfp_s`**, **`_controlfp`**, and **`_control87`** functions provide a mask to change this behavior. The following example demonstrates the use of this mask: ```C unsigned int current_word = 0; @@ -76,35 +75,42 @@ _controlfp_s(¤t_word, _DN_FLUSH, _MCW_DN); // and x64 processors with SSE2 support. Ignored on other x86 platforms. ``` -On ARM platforms, the **_controlfp_s** function applies to the FPSCR register. On x64 architectures, only the SSE2 control word that's stored in the MXCSR register is affected. On Intel (x86) platforms, **_controlfp_s** affects the control words for both the x87 and the SSE2, if present. It is possible for the two control words to be inconsistent with each other (because of a previous call to [__control87_2](control87-controlfp-control87-2.md), for example); if there is an inconsistency between the two control words, **_controlfp_s** sets the **EM_AMBIGUOUS** flag in *currentControl*. This is a warning that the returned control word might not represent the state of both floating-point control words accurately. +This function is ignored when you use [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) to compile because the common language runtime (CLR) only supports the default floating-point precision. -On the ARM and x64 architectures, changing the infinity mode or the floating-point precision is not supported. If the precision control mask is used on the x64 platform, the function raises an assertion and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +On x64, only the SSE2 control word stored in the MXCSR register is affected. Changing the infinity mode or the floating-point precision isn't supported. If the precision control mask is used on the x64 platform, the function raises an assertion and the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). -If the mask is not set correctly, this function generates an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **EINVAL** and sets **errno** to **EINVAL**. +On x86, **`_controlfp_s`** affects the control words for both the x87 and the SSE2, if present. It's possible for the two control words to be inconsistent with each other (because of a previous call to [`__control87_2`](control87-controlfp-control87-2.md), for example); if there's an inconsistency between the two control words, **`_controlfp_s`** sets the `EM_AMBIGUOUS` flag in *`currentControl`*. It's a warning that the returned control word might not represent the state of both floating-point control words accurately. -This function is ignored when you use [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) to compile because the common language runtime (CLR) only supports the default floating-point precision. +If the mask isn't set correctly, this function generates an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `EINVAL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +### Arm platforms + +- Changing the infinity mode or the floating-point precision isn't supported. If the precision control mask is used on the x64 platform, the function raises an assertion and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). +- On ARM32 (discontinued), Windows doesn't support FP exceptions. +- On ARM64, unmasking the whole `_MCW_EM` or any bits from it (`_EM_INEXACT`, `_EM_UNDERFLOW`, `_EM_OVERFLOW`, `_EM_ZERODIVIDE`, and `_EM_INVALID`) correctly change the FPCR register. Floating point exceptions raised by standard math functions, like Invalid operation from `std::acos`, are exempt from this behavior and can be ignored or raised properly depending on the FPCR register. For more information, see [Overview of ARM32 ABI Conventions](../../build/overview-of-arm-abi-conventions.md#floating-point-exceptions). +- On ARM64EC, Windows catches processor floating-point exceptions and disables them in the FPCR register. This ensures consistent behavior across different processor variants. ### Mask constants and values -For the **_MCW_EM** mask, clearing it sets the exception, which allows the hardware exception; setting it hides the exception. If a **_EM_UNDERFLOW** or **_EM_OVERFLOW** occurs, no hardware exception is thrown until the next floating-point instruction is executed. To generate a hardware exception immediately after **_EM_UNDERFLOW** or **_EM_OVERFLOW**, call the FWAIT MASM instruction. +For the `_MCW_EM` mask, clearing it sets the exception, which allows the hardware exception; setting it hides the exception. If a `_EM_UNDERFLOW` or `_EM_OVERFLOW` occurs, no hardware exception is thrown until the next floating-point instruction is executed. To generate a hardware exception immediately after `_EM_UNDERFLOW` or `_EM_OVERFLOW`, call the `FWAIT MASM` instruction. -|Mask|Hex value|Constant|Hex value| -|----------|---------------|--------------|---------------| -|**_MCW_DN** (Denormal control)|0x03000000|**_DN_SAVE**

**_DN_FLUSH**|0x00000000

0x01000000| -|**_MCW_EM** (Interrupt exception mask)|0x0008001F|**_EM_INVALID**

**_EM_DENORMAL**

**_EM_ZERODIVIDE**

**_EM_OVERFLOW**

**_EM_UNDERFLOW**

**_EM_INEXACT**|0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

0x00000001| -|**_MCW_IC** (Infinity control)

(Not supported on ARM or x64 platforms.)|0x00040000|**_IC_AFFINE**

**_IC_PROJECTIVE**|0x00040000

0x00000000| -|**_MCW_RC** (Rounding control)|0x00000300|**_RC_CHOP**

**_RC_UP**

**_RC_DOWN**

**_RC_NEAR**|0x00000300

0x00000200

0x00000100

0x00000000| -|**_MCW_PC** (Precision control)

(Not supported on ARM or x64 platforms.)|0x00030000|**_PC_24** (24 bits)

**_PC_53** (53 bits)

**_PC_64** (64 bits)|0x00020000

0x00010000

0x00000000| +| Mask | Hex value | Constant | Hex value | +|---|---|---|---| +| `_MCW_DN` (Denormal control) | 0x03000000 | `_DN_SAVE`

`_DN_FLUSH` | 0x00000000

0x01000000 | +| `_MCW_EM` (Interrupt exception mask) | 0x0008001F | `_EM_INVALID`

`_EM_DENORMAL`

`_EM_ZERODIVIDE`

`_EM_OVERFLOW`

`_EM_UNDERFLOW`

`_EM_INEXACT` | 0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

0x00000001 | +| `_MCW_IC` (Infinity control)

(Not supported on ARM or x64 platforms.) | 0x00040000 | `_IC_AFFINE`

`_IC_PROJECTIVE` | 0x00040000

0x00000000 | +| `_MCW_RC` (Rounding control) | 0x00000300 | `_RC_CHOP`

`_RC_UP`

`_RC_DOWN`

`_RC_NEAR` | 0x00000300

0x00000200

0x00000100

0x00000000 | +| `_MCW_PC` (Precision control)

(Not supported on ARM or x64 platforms.) | 0x00030000 | `_PC_24` (24 bits)

`_PC_53` (53 bits)

`_PC_64` (64 bits) | 0x00020000

0x00010000

0x00000000 | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_controlfp_s**|\| +| Routine | Required header | +|---|---| +| **`_controlfp_s`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -159,7 +165,7 @@ Default: 0x9001f ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_clear87, _clearfp](clear87-clearfp.md)
-[_status87, _statusfp, _statusfp2](status87-statusfp-statusfp2.md)
-[_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_status87`, `_statusfp`, `_statusfp2`](status87-statusfp-statusfp2.md)\ +[`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md) diff --git a/docs/c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md b/docs/c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md index 5b7cc18dca..8d979ab1f3 100644 --- a/docs/c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md +++ b/docs/c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md @@ -10,7 +10,7 @@ f1_keywords: ["_copysignl", "copysign", "copysignf", "_copysign", "copysignl", " helpviewer_keywords: ["copysignl function", "_copysignl function", "copysign function", "_copysignf function", "_copysign function", "copysignf function"] ms.assetid: 009216d6-72a2-402d-aa6c-91d924b2c9e4 --- -# copysign, copysignf, copysignl, _copysign, _copysignf, _copysignl +# `copysign`, `copysignf`, `copysignl`, `_copysign`, `_copysignf`, `_copysignl` Returns a value that has the magnitude of one argument and the sign of another. @@ -50,35 +50,35 @@ long double _copysignl( ### Parameters -*x*\ +*`x`*\ The floating-point value that's returned as the magnitude of the result. -*y*\ +*`y`*\ The floating-point value that's returned as the sign of the result. -[Floating-Point Support Routines](../../c-runtime-library/floating-point-support.md) +[Math and floating-point support](../floating-point-support.md) -## Return Value +## Return value -The **copysign** functions return a floating-point value that combines the magnitude of *x* and the sign of *y*. There's no error return. +The **`copysign`** functions return a floating-point value that combines the magnitude of *`x`* and the sign of *`y`*. There's no error return. ## Remarks -Because C++ allows overloading, you can call overloads of **copysign** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **copysign** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`copysign`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`copysign`** always takes and returns a **`double`**. -If you use the \ `copysign()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `copysign()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_copysign**|\| -|**copysign**, **copysignf**, **copysignl**, **_copysignf**, **_copysignl**|\| -|**copysign** macro | \ | +| Routine | Required header | +|---|---| +| **`_copysign`** | \ | +| **`copysign`**, **`copysignf`**, **`copysignl`**, **`_copysignf`**, **`_copysignl`** | \ | +| **`copysign`** macro | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[fabs, fabsf, fabsl](fabs-fabsf-fabsl.md)
-[_chgsign, _chgsignf, _chgsignl](chgsign-chgsignf-chgsignl.md)
+[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ +[`_chgsign`, `_chgsignf`, `_chgsignl`](chgsign-chgsignf-chgsignl.md) diff --git a/docs/c-runtime-library/reference/cos-cosf-cosl.md b/docs/c-runtime-library/reference/cos-cosf-cosl.md index e95318e03a..5e31e2aa7e 100644 --- a/docs/c-runtime-library/reference/cos-cosf-cosl.md +++ b/docs/c-runtime-library/reference/cos-cosf-cosl.md @@ -3,14 +3,14 @@ title: "cos, cosf, cosl" description: "API reference for cos, cosf, and cosl; which calculate the cosine value of a floating-point number." ms.date: "08/31/2020" api_name: ["cos", "cosf", "cosl", "_o_cos", "_o_cosf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cos", "cosf", "cosl"] helpviewer_keywords: ["cosines", "cosl function", "calculating cosine", "cosf function", "cos function", "trigonometric functions", "cosines, calculating"] ms.assetid: ae90435e-6b68-4a47-a81f-be87d5c08f16 --- -# cos, cosf, cosl +# `cos`, `cosf`, `cosl` Calculates the cosine. @@ -28,46 +28,45 @@ long double cos( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ Angle in radians. -## Return Value +## Return value -The cosine of *x*. If *x* is greater than or equal to 263, or less than or equal to -263, a loss of significance in the result occurs. +The cosine of *`x`*. If *`x`* is greater than or equal to 263, or less than or equal to -263, a loss of significance in the result occurs. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± QNAN, IND|none|**_DOMAIN**| -|± INF|**INVALID**|**_DOMAIN**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| ± INF | `INVALID` | `_DOMAIN` | ## Remarks -Because C++ allows overloading, you can call overloads of **cos** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **cos** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`cos`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`cos`** always takes and returns a **`double`**. -If you use the \ `cos()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `cos()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|---------------------|-| -|**cos**, **cosh**, **cosf**|\|\ or \| -|**cos()** macro | \ || +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`cos`**, **`cosh`**, **`cosf`** | \ | \ or \ | +| **cos()** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [sin, sinf, sinl](sin-sinf-sinl.md). +See the example in [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[acos, acosf, acosl](acos-acosf-acosl.md)
-[asin, asinf, asinl](asin-asinf-asinl.md)
-[atan, atanf, atanl, atan2, atan2f, atan2l](atan-atanf-atanl-atan2-atan2f-atan2l.md)
-[_matherr](matherr.md)
-[sin, sinf, sinl](sin-sinf-sinl.md)
-[tan, tanf, tanl](tan-tanf-tanl.md)
-[_CIcos](../../c-runtime-library/cicos.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ +[`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ +[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ +[`_matherr`](matherr.md)\ +[`sin`, `sinf`, `sinl`](sin-sinf-sinl.md)\ +[`tan`, `tanf`, `tanl`](tan-tanf-tanl.md) diff --git a/docs/c-runtime-library/reference/cosh-coshf-coshl.md b/docs/c-runtime-library/reference/cosh-coshf-coshl.md index 233d3e4cb0..cddafd7d1b 100644 --- a/docs/c-runtime-library/reference/cosh-coshf-coshl.md +++ b/docs/c-runtime-library/reference/cosh-coshf-coshl.md @@ -3,7 +3,7 @@ title: "cosh, coshf, coshl" description: "API reference for cosh, coshf, and coshl; which calculate the hyperbolic cosine of a floating-point value." ms.date: "1/15/2021" api_name: ["cosh", "coshf", "coshl", "_o_cosh", "_o_coshf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cosh", "coshf", "coshl"] @@ -30,33 +30,33 @@ long double cosh( long double x ); // C++ only *`x`*\ Angle in radians. -## Return Value +## Return value The hyperbolic cosine of *`x`*. -By default, if the result is too large in a **`cosh`**, **`coshf`**, or **`coshl`** call, the function returns **`HUGE_VAL`** and sets **`errno`** to **`ERANGE`**. +By default, if the result is too large in a **`cosh`**, **`coshf`**, or **`coshl`** call, the function returns `HUGE_VAL` and sets `errno` to `ERANGE`. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| -|*`x`* ≥ 7.104760e+002|**`INEXACT`**+**`OVERFLOW`**|**`OVERFLOW`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| *`x`* ≥ 7.104760e+002 | `INEXACT`+`OVERFLOW` | `OVERFLOW` | ## Remarks Because C++ allows overloading, you can call overloads of **`cosh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`cosh`** always takes and returns a **`double`**. -If you use the `` `cosh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `cosh` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`coshf`**, **`cosl`**, **`coshl`**|``|`` or ``| -|**`coshf()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`coshf`**, **`cosl`**, **`coshl`** | `` | `` or `` | +| **`coshf`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -64,10 +64,10 @@ See the example in [`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`acosh, acoshf, acoshl`](acosh-acoshf-acoshl.md)\ -[`asinh, asinhf, asinhl`](asinh-asinhf-asinhl.md)\ -[`atanh, atanhf, atanhl`](atanh-atanhf-atanhl.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ +[`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ +[`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ [`_matherr`](matherr.md)\ -[`sinh, sinhf, sinhl`](sinh-sinhf-sinhl.md)\ -[`tanh, tanhf, tanhl`](tanh-tanhf-tanhl.md) +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/countof-macro.md b/docs/c-runtime-library/reference/countof-macro.md index 5f26d8160e..cec03ed26c 100644 --- a/docs/c-runtime-library/reference/countof-macro.md +++ b/docs/c-runtime-library/reference/countof-macro.md @@ -11,7 +11,7 @@ ms.assetid: 86198767-f7e5-4beb-898d-3cbbf60350a3 --- # `_countof` Macro -Computes the number of elements in a statically-allocated array. +Computes the number of elements in a statically allocated array. ## Syntax @@ -21,10 +21,10 @@ Computes the number of elements in a statically-allocated array. ### Parameters -*`array`*
+*`array`*\ The name of an array. -## Return Value +## Return value The number of elements in the array, expressed as a **`size_t`**. @@ -36,9 +36,9 @@ Ensure that *`array`* is actually an array, not a pointer. In C, **`_countof`** ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**`_countof`**|``| +| Macro | Required header | +|---|---| +| **`_countof`** | `` | ## Example @@ -69,4 +69,4 @@ _countof(arr) = 20 elements ## See also -[`sizeof` Operator](../../cpp/sizeof-operator.md)
+[`sizeof` Operator](../../cpp/sizeof-operator.md) diff --git a/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md b/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md index 49f0b287c0..aad1d819dd 100644 --- a/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md +++ b/docs/c-runtime-library/reference/cpow-cpowf-cpowl.md @@ -10,7 +10,7 @@ f1_keywords: ["cpow", "cpowf", "cpowl", "complex/cpow", "complex/cpowf", "comple helpviewer_keywords: ["cpow function", "cpowf function", "complex/cpowl function"] ms.assetid: 83fe2187-22b7-4295-ab16-4d77abdbb80b --- -# cpow, cpowf, cpowl +# `cpow`, `cpowf`, `cpowl` Retrieves the value of a number raised to the specified power, where the base and exponent are complex numbers. This function has a branch cut for the exponent along the negative real axis. @@ -36,31 +36,31 @@ _Lcomplex cpowl( ### Parameters -*x*
+*`x`*\ The base. -*y*
+*`y`*\ The exponent. -## Return Value +## Return value -The value of *x* raised to the power of *y* with a branch cut for *x* along the negative real axis. +The value of *`x`* raised to the power of *`y`* with a branch cut for *`x`* along the negative real axis. ## Remarks -Because C++ allows overloading, you can call overloads of **cpow** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **cpow** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`cpow`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`cpow`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cpow**, **cpowf**, **cpowl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`cpow`**, **`cpowf`**, **`cpowl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[cexp, cexpf, cexpl](cexp-cexpf-cexpl.md)
-[clog10, clog10f, clog10l](clog10-clog10f-clog10l.md)
-[clog, clogf, clogl](clog-clogf-clogl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`cexp`, `cexpf`, `cexpl`](cexp-cexpf-cexpl.md)\ +[`clog10`, `clog10f`, `clog10l`](clog10-clog10f-clog10l.md)\ +[`clog`, `clogf`, `clogl`](clog-clogf-clogl.md) diff --git a/docs/c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md b/docs/c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md index 0f297f2218..55418b0ad2 100644 --- a/docs/c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md +++ b/docs/c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["_cwprintf", "cwprintf", "tcprintf", "_tcprintf", "_cprintf", "cwprintf_l", "tcprintf_l", "_tcprintf_l", "cprintf_l", "_cprintf_l", "_cwprintf_l"] helpviewer_keywords: ["_cprintf_l function", "_cwprintf_l function", "cwprintf function", "cprintf_l function", "characters, printing to console", "printing characters to console", "_tcprintf_l function", "tcprintf function", "_tcprintf function", "tcprintf_l function", "_cwprintf function", "cwprintf_l function", "_cprintf function"] --- -# _cprintf, _cprintf_l, _cwprintf, _cwprintf_l +# `_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l` -Formats and prints to the console. More-secure versions are available; see [_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md). +Formats and prints to the console. More-secure versions are available; see [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -37,50 +37,49 @@ int _cwprintf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument_list*
+*`argument_list`*\ Optional parameters for the format string. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value The number of characters printed. ## Remarks -These functions format and print a series of characters and values directly to the console, using the **_putch** function (**_putwch** for **_cwprintf**) to output characters. Each argument in *argument_list* (if any) is converted and output according to the corresponding format specification in *format*. The *format* argument uses the [format specification syntax for printf and wprintf functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). Unlike the **fprintf**, **printf**, and **sprintf** functions, neither **_cprintf** nor **_cwprintf** translates line-feed characters into carriage return-line feed (CR-LF) combinations when output. +These functions format and print a series of characters and values directly to the console, using the `_putch` function (`_putwch` for **`_cwprintf`**) to output characters. Each argument in *`argument_list`* (if any) is converted and output according to the corresponding format specification in *`format`*. The *`format`* argument uses the [format specification syntax for printf and wprintf functions](../format-specification-syntax-printf-and-wprintf-functions.md). Unlike the `fprintf`, `printf`, and `sprintf` functions, **`_cprintf`** and **`_cwprintf`** don't translate line-feed characters into carriage return-line feed (CR-LF) combinations when output. -An important distinction is that **_cwprintf** displays Unicode characters when used in Windows. Unlike **_cprintf**, **_cwprintf** uses the current console locale settings. +An important distinction is that **`_cwprintf`** displays Unicode characters when used in Windows. Unlike **`_cprintf`**, **`_cwprintf`** uses the current console locale settings. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. -**_cprintf** validates the *format* parameter. If *format* is a null pointer, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **errno** to **EINVAL**. +**`_cprintf`** validates the *`format`* parameter. If *`format`* is a null pointer, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcprintf**|**_cprintf**|**_cprintf**|**_cwprintf**| -|**_tcprintf_l**|**_cprintf_l**|**_cprintf_l**|**_cwprintf_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcprintf` | **`_cprintf`** | **`_cprintf`** | **`_cwprintf`** | +| `_tcprintf_l` | **`_cprintf_l`** | **`_cprintf_l`** | **`_cwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cprintf**, **_cprintf_l**|\| -|**_cwprintf**, **_cwprintf_l**|\| +| Routine | Required header | +|---|---| +| **`_cprintf`**, **`_cprintf_l`** | \ | +| **`_cwprintf`**, **`_cwprintf_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,12 +111,12 @@ int main( void ) ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)
-[_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)
-[_cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l](cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)\ +[`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)\ +[`_cprintf_p`, `_cprintf_p_l`, `_cwprintf_p`, `_cwprintf_p_l`](cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md b/docs/c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md index b53af8226d..5c99264be7 100644 --- a/docs/c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md +++ b/docs/c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["cprintf_p", "cwprintf_p", "tcprintf_p", "_cwprintf_p_l", "_cprintf_p", "csprintf_p_l", "_cprintf_p_l", "_cwprintf_p", "_tcprintf_p", "cprintf_p_l"] helpviewer_keywords: ["_cwprintf_p_l function", "cwprintf_p function", "tcprintf_p_l function", "cprintf_p_l function", "_tcprintf_p function", "_tcprintf_p_l function", "_cprintf_p function", "_cprintf_p_l function", "cwprintf_p_l function", "_cwprintf_p function", "tcprintf_p function", "cprintf_p function"] --- -# _cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l +# `_cprintf_p`, `_cprintf_p_l`, `_cwprintf_p`, `_cwprintf_p_l` Formats and prints to the console, and supports positional parameters in the format string. @@ -41,50 +41,50 @@ int _cwprintf_p_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value The number of characters printed or a negative value if an error occurs. ## Remarks -These functions format and print a series of characters and values directly to the console, using the **_putch** and **_putwch** functions to output characters. Each *argument* (if any) is converted and output according to the corresponding format specification in *format*. The format has the same form and function as the *format* parameter for the [printf_p](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) function. The difference between **_cprintf_p** and **cprintf_s** is that **_cprintf_p** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions format and print a series of characters and values directly to the console, using the `_putch` and `_putwch` functions to output characters. Each *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. The format has the same form and function as the *`format`* parameter for the [`printf_p`](../format-specification-syntax-printf-and-wprintf-functions.md) function. The difference between **`_cprintf_p`** and `cprintf_s` is that **`_cprintf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -Unlike the **fprintf_p**, **printf_p**, and **sprintf_p** functions, neither **_cprintf_p** nor **_cwprintf_p** translates line-feed characters into carriage return-line feed (CR-LF) combinations when output. An important distinction is that **_cwprintf_p** displays Unicode characters when used in Windows NT. Unlike **_cprintf_p**, **_cwprintf_p** uses the current console locale settings. +Unlike the `fprintf_p`, `printf_p`, and `sprintf_p` functions, **`_cprintf_p`** and **`_cwprintf_p`** don't translate line-feed characters into carriage return-line feed (CR-LF) combinations when output. An important distinction is that **`_cwprintf_p`** displays Unicode characters when used in Windows NT. Unlike **`_cprintf_p`**, **`_cwprintf_p`** uses the current console locale settings. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. -Also, like **_cprintf_s** and **_cwprintf_s**, they validate the input pointer and the format string. If *format* or *argument* are **NULL**, or of the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +Also, like `_cprintf_s` and `_cwprintf_s`, they validate the input pointer and the format string. If *`format`* or *`argument`* are `NULL`, or of the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. +> Ensure that *`format`* is not a user-defined string. > > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcprintf_p**|**_cprintf_p**|**_cprintf_p**|**_cwprintf_p**| -|**_tcprintf_p_l**|**_cprintf_p_l**|**_cprintf_p_l**|**_cwprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcprintf_p` | **`_cprintf_p`** | **`_cprintf_p`** | **`_cwprintf_p`** | +| `_tcprintf_p_l` | **`_cprintf_p_l`** | **`_cprintf_p_l`** | **`_cwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cprintf_p**, **_cprintf_p_l**|\| -|**_cwprintf_p**, **_cwprintf_p_l**|\| +| Routine | Required header | +|---|---| +| **`_cprintf_p`**, **`_cprintf_p_l`** | \ | +| **`_cwprintf_p`**, **`_cwprintf_p_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,15 +116,15 @@ int main( void ) ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
-[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)
-[_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)\ +[`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)\ +[`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md b/docs/c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md index 59a0eeb011..cab723ba69 100644 --- a/docs/c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md +++ b/docs/c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["_cwprintf_s_l", "_cprintf_s", "cwprintf_s", "_cprintf_s_l", "cwprintf_s_l", "cprintf_s_l", "_tcprintf_s", "cprintf_s", "_cwprintf_s", "tcprintf_s"] helpviewer_keywords: ["tcprintf_s_l function", "_cprintf_s_l function", "_cwprintf_s_l function", "tcprintf_s function", "_tcprintf_s_l function", "_cwprintf_s function", "cwprintf_s function", "_cprintf_s function", "cprintf_s function", "_tcprintf_s function", "cprintf_s_l function", "cwprintf_s_l function"] --- -# _cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l +# `_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l` -Formats and prints to the console. These versions of [_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Formats and prints to the console. These versions of [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -41,54 +41,53 @@ int _cwprintf_s_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value The number of characters printed. ## Remarks -These functions format and print a series of characters and values directly to the console, using the **_putch** function (**_putwch** for **_cwprintf_s**) to output characters. Each *argument* (if any) is converted and output according to the corresponding format specification in *format*. The format has the same form and function as the *format* parameter for the [printf_s](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) function. Unlike the **fprintf_s**, **printf_s**, and **sprintf_s** functions, neither **_cprintf_s** nor **_cwprintf_s** translates line-feed characters into carriage return-line feed (CR-LF) combinations when output. +These functions format and print a series of characters and values directly to the console, using the `_putch` function (`_putwch` for **`_cwprintf_s`**) to output characters. Each *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. The format has the same form and function as the *`format`* parameter for the [`printf_s`](../format-specification-syntax-printf-and-wprintf-functions.md) function. Unlike the `fprintf_s`, `printf_s`, and `sprintf_s` functions, **`_cprintf_s`** and **`_cwprintf_s`** don't translate line-feed characters into carriage return-line feed (CR-LF) combinations when output. -An important distinction is that **_cwprintf_s** displays Unicode characters when used in Windows NT. Unlike **_cprintf_s**, **_cwprintf_s** uses the current console locale +An important distinction is that **`_cwprintf_s`** displays Unicode characters when used in Windows NT. Unlike **`_cprintf_s`**, **`_cwprintf_s`** uses the current console locale -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -Like the non-secure versions (see [_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if *format* is a null pointer. These functions differ from the non-secure versions in that the format string itself is also validated. If there are any unknown or badly formed formatting specifiers, these functions invoke the invalid parameter handler. In all cases, If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +Like the non-secure versions (see [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), if *`format`* is a null pointer. These functions differ from the non-secure versions in that the format string itself is also validated. If there are any unknown or badly formed formatting specifiers, these functions invoke the invalid parameter handler. In all cases, If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcprintf_s**|**_cprintf_s**|**_cprintf_s**|**_cwprintf_s**| -|**_tcprintf_s_l**|**_cprintf_s_l**|**_cprintf_s_l**|**_cwprintf_s_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcprintf_s` | **`_cprintf_s`** | **`_cprintf_s`** | **`_cwprintf_s`** | +| `_tcprintf_s_l` | **`_cprintf_s_l`** | **`_cprintf_s_l`** | **`_cwprintf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cprintf_s**, **_cprintf_s_l**|\| -|**_cwprintf_s**, **_cwprintf_s_l**|\| +| Routine | Required header | +|---|---| +| **`_cprintf_s`**, **`_cprintf_s_l`** | \ | +| **`_cwprintf_s`**, **`_cwprintf_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -119,10 +118,10 @@ int main( void ) ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)
-[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)
-[vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/reference/cprintf.md b/docs/c-runtime-library/reference/cprintf.md index b8ee683b48..38ae9de609 100644 --- a/docs/c-runtime-library/reference/cprintf.md +++ b/docs/c-runtime-library/reference/cprintf.md @@ -9,11 +9,11 @@ topic_type: ["apiref"] f1_keywords: ["cprintf"] helpviewer_keywords: ["cprintf function"] --- -# cprintf +# `cprintf` -The Microsoft-specific function name `cprintf` is a deprecated alias for the [_cprintf](cprintf-cprintf-l-cwprintf-cwprintf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cprintf` is a deprecated alias for the [`_cprintf`](cprintf-cprintf-l-cwprintf-cwprintf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use the [_cprintf](cprintf-cprintf-l-cwprintf-cwprintf-l.md) or security-enhanced [_cprintf_s](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use the [`_cprintf`](cprintf-cprintf-l-cwprintf-cwprintf-l.md) or security-enhanced [`_cprintf_s`](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md b/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md index 6992c54b97..39bd6ca7d8 100644 --- a/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md +++ b/docs/c-runtime-library/reference/cproj-cprojf-cprojl.md @@ -10,7 +10,7 @@ f1_keywords: ["cproj", "cprojf", "cprojl", "complex/cproj", "complex/cprojf", "c helpviewer_keywords: ["cproj function", "cprojf function", "cprojl function"] ms.assetid: 32b49623-13bf-4cae-802e-7912d75030fe --- -# cproj, cprojf, cprojl +# `cproj`, `cprojf`, `cprojl` Retrieves the projection of a complex number on the Reimann sphere. @@ -37,34 +37,34 @@ _Lcomplex cprojl( ### Parameters -*z*\ +*`z`*\ A complex number. -## Return Value +## Return value -The projection of *z* on the Reimann sphere. +The projection of *`z`* on the Reimann sphere. ## Remarks -Because C++ allows overloading, you can call overloads of **cproj** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, unless you're using the \ macro to call this function, **cproj** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`cproj`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, unless you're using the \ macro to call this function, **`cproj`** always takes and returns a `_Dcomplex` value. -If you use the \ `cproj()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `cproj()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**cproj**, **cprojf**, **cprojl**|\|\| -|**cproj** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`cproj`**, **`cprojf`**, **`cprojl`** | \ | \ | +| **`cproj`** macro | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/cputs-cputws.md b/docs/c-runtime-library/reference/cputs-cputws.md index cce48ce3ca..5ffe5fe412 100644 --- a/docs/c-runtime-library/reference/cputs-cputws.md +++ b/docs/c-runtime-library/reference/cputs-cputws.md @@ -3,14 +3,14 @@ description: "Learn more about: _cputs, _cputws" title: "_cputs, _cputws" ms.date: "4/2/2020" api_name: ["_cputws", "_cputs", "_o__cputs", "_o__cputws"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cputws", "_cputs", "_cputws"] helpviewer_keywords: ["strings [C++], writing", "_cputs function", "_cputws function", "putting strings to the console", "cputs function", "console, sending strings to", "cputws function"] ms.assetid: ec418484-0f8d-43ec-8d8b-198a556c659e --- -# _cputs, _cputws +# `_cputs`, `_cputws` Puts a string to the console. @@ -30,39 +30,39 @@ int _cputws( ### Parameters -*str*
+*`str`*\ Output string. -## Return Value +## Return value -If successful, **_cputs** returns 0. If the function fails, it returns a nonzero value. +If successful, **`_cputs`** returns 0. If the function fails, it returns a nonzero value. ## Remarks -The **_cputs** function writes the null-terminated string that's pointed to by *str* directly to the console. A carriage return-line feed (CR-LF) combination is not automatically appended to the string. +The **`_cputs`** function writes the null-terminated string that's pointed to by *`str`* directly to the console. A carriage return-line feed (CR-LF) combination isn't automatically appended to the string. -This function validates its parameter. If *str* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and -1 is returned. +This function validates its parameter. If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and -1 is returned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_cputts**|**_cputs**|**_cputs**|**_cputws**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cputts` | **`_cputs`** | **`_cputs`** | **`_cputws`** | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_cputs**|\|\| -|**_cputws**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_cputs`** | \ | \ | +| **`_cputws`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -106,7 +106,6 @@ void wprint_to_console(wchar_t* wbuffer) int main() { - // String to print at console. // Notice the \r (return) character. char* buffer = "Hello world (courtesy of _cputs)!\r\n"; @@ -123,5 +122,5 @@ Hello world (courtesy of _cputws)! ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_putch, _putwch](putch-putwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_putch`, `_putwch`](putch-putwch.md) diff --git a/docs/c-runtime-library/reference/cputs.md b/docs/c-runtime-library/reference/cputs.md index 6eed32aa59..acc7c92f87 100644 --- a/docs/c-runtime-library/reference/cputs.md +++ b/docs/c-runtime-library/reference/cputs.md @@ -10,11 +10,11 @@ f1_keywords: ["cputs"] helpviewer_keywords: ["cputs function"] ms.assetid: 0c2a7d4e-623a-4cb2-a0f9-1900c05bac08 --- -# cputs +# `cputs` -The Microsoft-specific function name `cputs` is a deprecated alias for the [_cputs](cputs-cputws.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cputs` is a deprecated alias for the [`_cputs`](cputs-cputws.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_cputs](cputs-cputws.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_cputs`](cputs-cputws.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/creal-crealf-creall.md b/docs/c-runtime-library/reference/creal-crealf-creall.md index cf820db337..40a36d933e 100644 --- a/docs/c-runtime-library/reference/creal-crealf-creall.md +++ b/docs/c-runtime-library/reference/creal-crealf-creall.md @@ -10,7 +10,7 @@ f1_keywords: ["creal", "crealf", "creall", "complex/creal", "complex/crealf", "c helpviewer_keywords: ["creal function", "crealf function", "creall function"] ms.assetid: fa3ac62f-7aa3-4238-a71f-d6b00cd0c7c8 --- -# creal, crealf, creall +# `creal`, `crealf`, `creall` Retrieves the real part of a complex number. @@ -28,35 +28,35 @@ long double creal( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The real part of *z*. +The real part of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **creal** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **creal** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`creal`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`creal`** always takes a `_Dcomplex` value and returns a **`double`** value. -If you use the \ `creal()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `creal()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**creal**, **crealf**, **creall**|\|\| -|**creal** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`creal`**, **`crealf`**, **`creall`** | \ | \ | +| **`creal`** macro | \ | | -The **_Fcomplex**, **_Dcomplex**, and **_Lcomplex** types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The `_Fcomplex`, `_Dcomplex`, and `_Lcomplex` types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_Cbuild, _FCbuild, _LCbuild](cbuild-fcbuild-lcbuild.md)
-[norm, normf, norml](norm-normf-norml1.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_Cbuild`, `_FCbuild`, `_LCbuild`](cbuild-fcbuild-lcbuild.md)\ +[`norm`, `normf`, `norml`](norm-normf-norml1.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/creat-wcreat.md b/docs/c-runtime-library/reference/creat-wcreat.md index bc34a57750..da6faafa41 100644 --- a/docs/c-runtime-library/reference/creat-wcreat.md +++ b/docs/c-runtime-library/reference/creat-wcreat.md @@ -3,16 +3,16 @@ description: "Learn more about: _creat, _wcreat" title: "_creat, _wcreat" ms.date: "4/2/2020" api_name: ["_creat", "_wcreat", "_o__creat", "_o__wcreat"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcreat", "_wcreat", "_creat", "tcreat", "_tcreat"] helpviewer_keywords: ["wcreat function", "_wcreat function", "files [C++], creating", "_creat function", "tcreat function", "creat function", "_tcreat function"] ms.assetid: 3b3b795d-1620-40ec-bd2b-a4bbb0d20fe5 --- -# _creat, _wcreat +# `_creat`, `_wcreat` -Creates a new file. **_creat** and **_wcreat** have been deprecated; use [_sopen_s, _wsopen_s](sopen-s-wsopen-s.md) instead. +Creates a new file. **`_creat`** and **`_wcreat`** have been deprecated; use [`_sopen_s`, `_wsopen_s`](sopen-s-wsopen-s.md) instead. ## Syntax @@ -29,58 +29,58 @@ int _wcreat( ### Parameters -*filename*
+*`filename`*\ Name of new file. -*pmode*
+*`pmode`*\ Permission setting. -## Return Value +## Return value -These functions, if successful, return a file descriptor to the created file. Otherwise, the functions return -1 and set **errno** as shown in the following table. +These functions, if successful, return a file descriptor to the created file. Otherwise, the functions return -1 and set `errno` as shown in the following table. -|**errno** setting|Description| -|---------------------|-----------------| -|**EACCES**|*filename* specifies an existing read-only file or specifies a directory instead of a file.| -|**EMFILE**|No more file descriptors are available.| -|**ENOENT**|Specified file could not be found.| +| `errno` value | Description | +|---|---| +| `EACCES` | *`filename`* specifies an existing read-only file or specifies a directory instead of a file. | +| `EMFILE` | No more file descriptors are available. | +| `ENOENT` | Specified file couldn't be found. | -If *filename* is **NULL**, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. +If *`filename`* is `NULL`, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_creat** function creates a new file or opens and truncates an existing one. **_wcreat** is a wide-character version of **_creat**; the *filename* argument to **_wcreat** is a wide-character string. **_wcreat** and **_creat** behave identically otherwise. +The **`_creat`** function creates a new file or opens and truncates an existing one. **`_wcreat`** is a wide-character version of **`_creat`**; the *`filename`* argument to **`_wcreat`** is a wide-character string. **`_wcreat`** and **`_creat`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcreat**|**_creat**|**_creat**|**_wcreat**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcreat` | **`_creat`** | **`_creat`** | **`_wcreat`** | -If the file specified by *filename* does not exist, a new file is created with the given permission setting and is opened for writing. If the file already exists and its permission setting allows writing, **_creat** truncates the file to length 0, destroying the previous contents, and opens it for writing. The permission setting, *pmode*, applies to newly created files only. The new file receives the specified permission setting after it is closed for the first time. The integer expression *pmode* contains one or both of the manifest constants **_S_IWRITE** and **_S_IREAD**, defined in SYS\Stat.h. When both constants are given, they are joined with the bitwise or operator ( **|** ). The *pmode* parameter is set to one of the following values. +If the file specified by *`filename`* doesn't exist, a new file is created with the given permission setting and is opened for writing. If the file already exists and its permission setting allows writing, **`_creat`** truncates the file to length 0, destroying the previous contents, and opens it for writing. The permission setting, *`pmode`*, applies to newly created files only. The new file receives the specified permission setting after it's closed for the first time. The integer expression *`pmode`* contains one or both of the manifest constants `_S_IWRITE` and `_S_IREAD`, defined in SYS\Stat.h. When both constants are given, they're joined with the bitwise or operator ( **`|`** ). The *`pmode`* parameter is set to one of the following values. -|Value|Definition| -|-----------|----------------| -|**_S_IWRITE**|Writing permitted.| -|**_S_IREAD**|Reading permitted.| -|**_S_IREAD** | **_S_IWRITE**|Reading and writing permitted.| +| Value | Definition | +|---|---| +| `_S_IWRITE` | Writing permitted. | +| `_S_IREAD` | Reading permitted. | +| `_S_IREAD | _S_IWRITE` | Reading and writing permitted. | -If write permission is not given, the file is read-only. All files are always readable; it is impossible to give write-only permission. The modes **_S_IWRITE** and **_S_IREAD** | **_S_IWRITE** are then equivalent. Files opened using **_creat** are always opened in compatibility mode (see [_sopen](sopen-wsopen.md)) with **_SH_DENYNO**. +If write permission isn't given, the file is read-only. All files are always readable; it's impossible to give write-only permission. The modes `_S_IWRITE` and `_S_IREAD | _S_IWRITE` are then equivalent. Files opened using **`_creat`** are always opened in compatibility mode (see [`_sopen`](sopen-wsopen.md)) with `_SH_DENYNO`. -**_creat** applies the current file-permission mask to *pmode* before setting the permissions (see [_umask](umask.md)). **_creat** is provided primarily for compatibility with previous libraries. A call to **_open** with **_O_CREAT** and **_O_TRUNC** in the *oflag* parameter is equivalent to **_creat** and is preferable for new code. +**`_creat`** applies the current file-permission mask to *`pmode`* before setting the permissions (see [`_umask`](umask.md)). **`_creat`** is provided primarily for compatibility with previous libraries. A call to `_open` with `_O_CREAT` and `_O_TRUNC` in the *`oflag`* parameter is equivalent to **`_creat`** and is preferable for new code. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_creat**|\|\, \, \| -|**_wcreat**|\ or \|\, \, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_creat`** | \ | \, \, \ | +| **`_wcreat`** | \ or \ | \, \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -119,11 +119,11 @@ Created data file. ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_chsize](chsize.md)
-[_close](close.md)
-[_dup, _dup2](dup-dup2.md)
-[_open, _wopen](open-wopen.md)
-[_sopen, _wsopen](sopen-wsopen.md)
-[_umask](umask.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_chsize`](chsize.md)\ +[`_close`](close.md)\ +[`_dup`, `_dup2`](dup-dup2.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_sopen`, `_wsopen`](sopen-wsopen.md)\ +[`_umask`](umask.md) diff --git a/docs/c-runtime-library/reference/creat.md b/docs/c-runtime-library/reference/creat.md index 910ff8a7f9..108bb751c6 100644 --- a/docs/c-runtime-library/reference/creat.md +++ b/docs/c-runtime-library/reference/creat.md @@ -10,8 +10,8 @@ f1_keywords: ["creat"] helpviewer_keywords: ["creat function"] ms.assetid: 3aa6f0cc-5ae6-40d5-be94-0ab6f53c0c5b --- -# creat +# `creat` -The Microsoft-implemented POSIX function name `creat` is a deprecated alias for the [_creat](creat-wcreat.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `creat` is a deprecated alias for the [`_creat`](creat-wcreat.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_creat](creat-wcreat.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_creat`](creat-wcreat.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/create-locale-wcreate-locale.md b/docs/c-runtime-library/reference/create-locale-wcreate-locale.md index ffeb575dfe..52da38a7b5 100644 --- a/docs/c-runtime-library/reference/create-locale-wcreate-locale.md +++ b/docs/c-runtime-library/reference/create-locale-wcreate-locale.md @@ -3,14 +3,14 @@ description: "Learn more about: _create_locale, _wcreate_locale" title: "_create_locale, _wcreate_locale" ms.date: "4/2/2020" api_name: ["_create_locale", "__create_locale", "_wcreate_locale", "_o__create_locale", "_o__wcreate_locale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["create_locale", "_create_locale", "__create_locale"] helpviewer_keywords: ["locales, creating", "_create_locale function", "create_locale function", "__create_locale function"] ms.assetid: ca362464-9f4a-4ec6-ab03-316c55c5be81 --- -# _create_locale, _wcreate_locale +# `_create_locale`, `_wcreate_locale` Creates a locale object. @@ -29,53 +29,53 @@ _locale_t _wcreate_locale( ### Parameters -*category*
+*`category`*\ Category. -*locale*
+*`locale`*\ Locale specifier. -## Return Value +## Return value -If a valid *locale* and *category* are given, returns the specified locale settings as a **_locale_t** object. The current locale settings of the program are not changed. +If a valid *`locale`* and *`category`* are given, the functions return the specified locale settings as a `_locale_t` object. The current locale settings of the program aren't changed. ## Remarks -The **_create_locale** function allows you to create an object that represents certain region-specific settings, for use in locale-specific versions of many CRT functions (functions with the **_l** suffix). The behavior is similar to **setlocale**, except that instead of applying the specified locale settings to the current environment, the settings are saved in a **_locale_t** structure that is returned. The **_locale_t** structure should be freed using [_free_locale](free-locale.md) when it is no longer needed. +The **`_create_locale`** function allows you to create an object that represents certain region-specific settings, for use in locale-specific versions of many CRT functions (functions with the `_l` suffix). The behavior is similar to `setlocale`, except that instead of applying the specified locale settings to the current environment, the settings are saved in a `_locale_t` structure that is returned. The `_locale_t` structure should be freed using [`_free_locale`](free-locale.md) when it's no longer needed. -**_wcreate_locale** is a wide-character version of **_create_locale**; the *locale* argument to **_wcreate_locale** is a wide-character string. **_wcreate_locale** and **_create_locale** behave identically otherwise. +**`_wcreate_locale`** is a wide-character version of **`_create_locale`**; the *`locale`* argument to **`_wcreate_locale`** is a wide-character string. **`_wcreate_locale`** and **`_create_locale`** behave identically otherwise. -The *category* argument specifies the parts of the locale-specific behavior that are affected. The flags used for *category* and the parts of the program they affect are as shown in this table: +The *`category`* argument specifies the parts of the locale-specific behavior that are affected. The flags used for *`category`* and the parts of the program they affect are as shown in this table: -| *category* flag | Affects | +| *`category`* flag | Affects | |-----------------|---------| -| **LC_ALL** |All categories, as listed below. | -| **LC_COLLATE** |The **strcoll**, **_stricoll**, **wcscoll**, **_wcsicoll**, **strxfrm**, **_strncoll**, **_strnicoll**, **_wcsncoll**, **_wcsnicoll**, and **wcsxfrm** functions. | -| **LC_CTYPE** | The character-handling functions (except **isdigit**, **isxdigit**, **mbstowcs**, and **mbtowc**, which are unaffected). | -| **LC_MONETARY** | Monetary-formatting information returned by the **localeconv** function. | -| **LC_NUMERIC** | Decimal-point character for the formatted output routines (such as **printf**), for the data-conversion routines, and for the non-monetary formatting information returned by **localeconv**. In addition to the decimal-point character, **LC_NUMERIC** sets the thousands separator and the grouping control string returned by [localeconv](localeconv.md). | -| **LC_TIME** | The **strftime** and **wcsftime** functions. | +| `LC_ALL` |All categories, as listed below. | +| `LC_COLLATE` |The `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll`, and `wcsxfrm` functions. | +| `LC_CTYPE` | The character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected). | +| `LC_MONETARY` | Monetary-formatting information returned by the `localeconv` function. | +| `LC_NUMERIC` | Decimal-point character for the formatted output routines (such as `printf`), for the data-conversion routines, and for the non-monetary formatting information returned by `localeconv`. In addition to the decimal-point character, `LC_NUMERIC` sets the thousands separator and the grouping control string returned by [`localeconv`](localeconv.md). | +| `LC_TIME` | The `strftime` and `wcsftime` functions. | -This function validates the *category* and *locale* parameters. If the category parameter is not one of the values given in the previous table or if *locale* is **NULL**, the function returns **NULL**. +This function validates the *`category`* and *`locale`* parameters. If the category parameter isn't one of the values given in the previous table or if *`locale`* is `NULL`, the function returns `NULL`. -The *locale* argument is a pointer to a string that specifies the locale. For information about the format of the *locale* argument, see [Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md). +The *`locale`* argument is a pointer to a string that specifies the locale. For information about the format of the *`locale`* argument, see [Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md). -The *locale* argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. The set of available locale names, languages, country/region codes, and code pages includes all that are supported by the Windows NLS API. The set of locale names supported by **_create_locale** are described in [Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md). The set of language and country/region strings supported by **_create_locale** are listed in [Language Strings](../../c-runtime-library/language-strings.md) and [Country/Region Strings](../../c-runtime-library/country-region-strings.md). +The *`locale`* argument can take several kinds of values: a locale name, a language string, a language string and country/region code, a code page, or a combination of language string, country/region code, and code page. The set (of available locale names, languages, country/region codes, and code pages) includes all that are supported by the Windows NLS API. The set of locale names **`_create_locale`** supports is described in [Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md). The set of language and country/region strings supported by **`_create_locale`** are listed in [Language strings](../language-strings.md) and [Country/Region strings](../country-region-strings.md). -For more information about locale settings, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). +For more information about locale settings, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). -The previous name of this function, **__create_locale** (with two leading underscores), has been deprecated. +The previous name of this function, **`__create_locale`** (with two leading underscores), has been deprecated. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_create_locale**|\| -|**_wcreate_locale**|\ or \| +| Routine | Required header | +|---|---| +| **`_create_locale`** | \ | +| **`_wcreate_locale`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -141,22 +141,22 @@ In 'C' locale, _strftime_l returns 'Saturday, February 09, 2002' ## See also -[Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md)
-[Language Strings](../../c-runtime-library/language-strings.md)
-[Country/Region Strings](../../c-runtime-library/country-region-strings.md)
-[_free_locale](free-locale.md)
-[_configthreadlocale](configthreadlocale.md)
-[setlocale](../../preprocessor/setlocale.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[_setmbcp](setmbcp.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](strftime-wcsftime-strftime-l-wcsftime-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
+[Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md)\ +[Language strings](../language-strings.md)\ +[Country/Region strings](../country-region-strings.md)\ +[`_free_locale`](free-locale.md)\ +[`_configthreadlocale`](configthreadlocale.md)\ +[`setlocale`](../../preprocessor/setlocale.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`_setmbcp`](setmbcp.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) diff --git a/docs/c-runtime-library/reference/crt-alphabetical-function-reference.md b/docs/c-runtime-library/reference/crt-alphabetical-function-reference.md index 079a532a23..43265128f6 100644 --- a/docs/c-runtime-library/reference/crt-alphabetical-function-reference.md +++ b/docs/c-runtime-library/reference/crt-alphabetical-function-reference.md @@ -7,7 +7,7 @@ ms.assetid: c2169b0e-cd86-489a-a2fa-2ee15c03b5c2 --- # UCRT alphabetical function reference -The Universal C Runtime (UCRT, often just CRT) Library reference documentation is arranged alphabetically by routine. To find a CRT routine based on functionality, see [Universal C runtime routines by category](../../c-runtime-library/run-time-routines-by-category.md). +The Universal C Runtime (UCRT, often just CRT) Library reference documentation is arranged alphabetically by routine. To find a CRT routine based on functionality, see [Universal C runtime routines by category](../run-time-routines-by-category.md). ## A @@ -3501,4 +3501,4 @@ The Universal C Runtime (UCRT, often just CRT) Library reference documentation i ## See also -[C Run-Time Library Reference](../../c-runtime-library/c-run-time-library-reference.md)
+[C runtime library reference](../c-run-time-library-reference.md) diff --git a/docs/c-runtime-library/reference/crtcheckmemory.md b/docs/c-runtime-library/reference/crtcheckmemory.md index a64677ef23..5c9ca5d58e 100644 --- a/docs/c-runtime-library/reference/crtcheckmemory.md +++ b/docs/c-runtime-library/reference/crtcheckmemory.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CrtCheckMemory" title: "_CrtCheckMemory" +description: "Learn more about: _CrtCheckMemory" ms.date: "11/04/2016" api_name: ["_CrtCheckMemory"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,55 +8,53 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtCheckMemory", "_CrtCheckMemory"] helpviewer_keywords: ["_CrtCheckMemory function", "CrtCheckMemory function"] -ms.assetid: 457cc72e-60fd-4177-ab5c-6ae26a420765 --- -# _CrtCheckMemory +# `_CrtCheckMemory` Confirms the integrity of the memory blocks allocated in the debug heap (debug version only). ## Syntax ```C - int _CrtCheckMemory( void ); ``` -## Return Value +## Return value -If successful, **_CrtCheckMemory** returns TRUE; otherwise, the function returns FALSE. +If successful, **`_CrtCheckMemory`** returns `TRUE`; otherwise, the function returns `FALSE`. ## Remarks -The **_CrtCheckMemory** function validates memory allocated by the debug heap manager by verifying the underlying base heap and inspecting every memory block. If an error or memory inconsistency is encountered in the underlying base heap, the debug header information, or the overwrite buffers, **_CrtCheckMemory** generates a debug report with information describing the error condition. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtCheckMemory** are removed during preprocessing. +The **`_CrtCheckMemory`** function validates memory allocated by the debug heap manager by verifying the underlying base heap and inspecting every memory block. If an error or memory inconsistency is encountered in the underlying base heap, the debug header information, or the overwrite buffers, **`_CrtCheckMemory`** generates a debug report with information describing the error condition. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtCheckMemory`** are removed during preprocessing. -The behavior of **_CrtCheckMemory** can be controlled by setting the bit fields of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag using the [_CrtSetDbgFlag](crtsetdbgflag.md) function. Turning the **_CRTDBG_CHECK_ALWAYS_DF** bit field ON results in **_CrtCheckMemory** being called every time a memory allocation operation is requested. Although this method slows down execution, it is useful for catching errors quickly. Turning the **_CRTDBG_ALLOC_MEM_DF** bit field OFF causes **_CrtCheckMemory** to not verify the heap and immediately return **TRUE**. +The behavior of **`_CrtCheckMemory`** can be controlled by setting the bit fields of the [`_crtDbgFlag`](../crtdbgflag.md) flag using the [`_CrtSetDbgFlag`](crtsetdbgflag.md) function. Turning the `_CRTDBG_CHECK_ALWAYS_DF` bit field ON results in **`_CrtCheckMemory`** being called every time a memory allocation operation is requested. Although this method slows down execution, it's useful for catching errors quickly. Turning the `_CRTDBG_ALLOC_MEM_DF` bit field OFF causes **`_CrtCheckMemory`** to not verify the heap and immediately return `TRUE`. -Because this function returns **TRUE** or **FALSE**, it can be passed to one of the [_ASSERT](assert-asserte-assert-expr-macros.md) macros to create a simple debugging error handling mechanism. The following example causes an assertion failure if corruption is detected in the heap: +Because this function returns `TRUE` or `FALSE`, it can be passed to one of the [`_ASSERT`](assert-asserte-assert-expr-macros.md) macros to create a basic debugging error handling mechanism. The following example causes an assertion failure if corruption is detected in the heap: ```C _ASSERTE( _CrtCheckMemory( ) ); ``` -For more information about how **_CrtCheckMemory** can be used with other debug functions, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For an overview of memory management and the debug heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about how **`_CrtCheckMemory`** can be used with other debug functions, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For an overview of memory management and the debug heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtCheckMemory**|\| +| Routine | Required header | +|---|---| +| **`_CrtCheckMemory`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_CrtCheckMemory**, see [crt_dbg1](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). +For a sample of how to use **`_CrtCheckMemory`**, see [`crt_dbg1`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_crtDbgFlag](../../c-runtime-library/crtdbgflag.md)
-[_CrtSetDbgFlag](crtsetdbgflag.md)
+[Debug routines](../debug-routines.md)\ +[`_crtDbgFlag`](../crtdbgflag.md)\ +[`_CrtSetDbgFlag`](crtsetdbgflag.md) diff --git a/docs/c-runtime-library/reference/crtdbgbreak.md b/docs/c-runtime-library/reference/crtdbgbreak.md index b419956aa3..057be6cfa3 100644 --- a/docs/c-runtime-library/reference/crtdbgbreak.md +++ b/docs/c-runtime-library/reference/crtdbgbreak.md @@ -10,7 +10,7 @@ f1_keywords: ["_CrtDbgBreak", "CrtDbgBreak"] helpviewer_keywords: ["CrtDbgBreak function", "_CrtDbgBreak function"] ms.assetid: 01f8b4a2-a2c7-4e1f-9f39-e573b4a7871f --- -# _CrtDbgBreak +# `_CrtDbgBreak` Sets a break point on a particular line of code. (Used in debug mode only.) @@ -20,27 +20,27 @@ Sets a break point on a particular line of code. (Used in debug mode only.) void _CrtDbgBreak( void ); ``` -## Return Value +## Return value -There is no return value. +There's no return value. ## Remarks -The **_CrtDbgBreak** function sets a debug breakpoint on the particular line of code where the function resides. This function is used in debug mode only and is dependent on **_DEBUG** being previously defined. +The **`_CrtDbgBreak`** function sets a debug breakpoint on the particular line of code where the function resides. This function is used in debug mode only and is dependent on `_DEBUG` being previously defined. -For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Writing Your Own Debug Hook Functions](/visualstudio/debugger/debug-hook-function-writing). +For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Writing your own debug hook functions](../crt-debugging-techniques.md#debug-hook-function-writing). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtDbgBreak**|\| +| Routine | Required header | +|---|---| +| **`_CrtDbgBreak`** | \ | ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[__debugbreak](../../intrinsics/debugbreak.md)
+[Debug routines](../debug-routines.md)\ +[`__debugbreak`](../../intrinsics/debugbreak.md) diff --git a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md index 0aeea2da6d..10ec08e428 100644 --- a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md +++ b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtDbgReport", "CrtDbgReportW", "_CrtDbgReportW", "_CrtDbgReport" helpviewer_keywords: ["debug reporting", "_CrtDbgReport function", "CrtDbgReport function", "CrtDbgReportW function", "_CrtDbgReportW function"] ms.assetid: 6e581fb6-f7fb-4716-9432-f0145d639ecc --- -# _CrtDbgReport, _CrtDbgReportW +# `_CrtDbgReport`, `_CrtDbgReportW` Generates a report with a debugging message and sends the report to three possible destinations (debug version only). @@ -37,65 +37,65 @@ int _CrtDbgReportW( ### Parameters -*reportType*
-Report type: **_CRT_WARN**, **_CRT_ERROR**, and **_CRT_ASSERT**. +*`reportType`*\ +Report type: `_CRT_WARN`, `_CRT_ERROR`, and `_CRT_ASSERT`. -*filename*
-Pointer to name of source file where assert/report occurred or **NULL**. +*`filename`*\ +Pointer to name of source file where assert/report occurred or `NULL`. -*linenumber*
-Line number in source file where assert/report occurred or **NULL**. +*`lineNumber`*\ +Line number in source file where assert/report occurred or `NULL`. -*moduleName*
+*`moduleName`*\ Pointer to name of module (.exe or .dll) where assert or report occurred. -*format*
+*`format`*\ Pointer to format-control string used to create the user message. -*argument*
-Optional substitution arguments used by *format*. +*`argument`*\ +Optional substitution arguments used by *`format`*. -## Return Value +## Return value -For all report destinations, **_CrtDbgReport** and **_CrtDbgReportW** return -1 if an error occurs and 0 if no errors are encountered. However, when the report destination is a debug message window and the user clicks the **Retry** button, these functions return 1. If the user clicks the **Abort** button in the Debug Message window, these functions immediately abort and do not return a value. +For all report destinations, **`_CrtDbgReport`** and **`_CrtDbgReportW`** return -1 if an error occurs and 0 if no errors are encountered. However, when the report destination is a debug message window and the user chooses the **Retry** button, these functions return 1. If the user chooses the **Abort** button in the Debug Message window, these functions immediately abort and don't return a value. -The [_RPT, _RPTF](rpt-rptf-rptw-rptfw-macros.md) debug macros call **_CrtDbgReport** to generate their debug reports. The wide-character versions of these macros as well as [_ASSERT, _ASSERTE](assert-asserte-assert-expr-macros.md), [_RPTW](rpt-rptf-rptw-rptfw-macros.md) -and [_RPTFW](rpt-rptf-rptw-rptfw-macros.md), use **_CrtDbgReportW** to generate their debug reports. When **_CrtDbgReport** or **_CrtDbgReportW** return 1, these macros start the debugger, provided that just-in-time (JIT) debugging is enabled. +The [`_RPT`, `_RPTF`](rpt-rptf-rptw-rptfw-macros.md) debug macros call **`_CrtDbgReport`** to generate their debug reports. The wide-character versions of these macros, along with [`_ASSERT`, `_ASSERTE`](assert-asserte-assert-expr-macros.md), [`_RPTW`](rpt-rptf-rptw-rptfw-macros.md) +and [`_RPTFW`](rpt-rptf-rptw-rptfw-macros.md), use **`_CrtDbgReportW`** to generate their debug reports. When **`_CrtDbgReport`** or **`_CrtDbgReportW`** return 1, these macros start the debugger, if just-in-time (JIT) debugging is enabled. ## Remarks -**_CrtDbgReport** and **_CrtDbgReportW** can send the debug report to three different destinations: a debug report file, a debug monitor (the Visual Studio debugger), or a debug message window. Two configuration functions, [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md), are used to specify the destination or destinations for each report type. These functions allow the reporting destination or destinations for each report type to be separately controlled. For example, it is possible to specify that a *reportType* of **_CRT_WARN** only be sent to the debug monitor, while a *reportType* of **_CRT_ASSERT** be sent to a debug message window and a user-defined report file. +**`_CrtDbgReport`** and **`_CrtDbgReportW`** can send the debug report to three different destinations: a debug report file, a debug monitor (the Visual Studio debugger), or a debug message window. Two configuration functions, [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md), are used to specify the destination or destinations for each report type. These functions allow the reporting destination or destinations for each report type to be separately controlled. For example, it's possible to specify that a *`reportType`* of `_CRT_WARN` only goes to the debug monitor, while a *`reportType`* of `_CRT_ASSERT` goes to both a debug message window and a user-defined report file. -**_CrtDbgReportW** is the wide-character version of **_CrtDbgReport**. All its output and string parameters are in wide-character strings; otherwise it is identical to the single-byte character version. +**`_CrtDbgReportW`** is the wide-character version of **`_CrtDbgReport`**. All its output and string parameters are in wide-character strings; otherwise it's identical to the single-byte character version. -**_CrtDbgReport** and **_CrtDbgReportW** create the user message for the debug report by substituting the *argument*[**n**] arguments into the *format* string, using the same rules defined by the **printf** or **wprintf** functions. These functions then generate the debug report and determine the destination or destinations, based on the current report modes and file defined for *reportType*. When the report is sent to a debug message window, the *filename*, **lineNumber**, and *moduleName* are included in the information displayed in the window. +**`_CrtDbgReport`** and **`_CrtDbgReportW`** create the user message for the debug report by substituting the *`argument[n]`* arguments into the *`format`* string, using the same rules defined by the `printf` or `wprintf` functions. These functions then generate the debug report and determine the destination or destinations, based on the current report modes and file defined for *`reportType`*. When the report is sent to a debug message window, the *`filename`*, *`lineNumber`*, and *`moduleName`* are included in the information displayed in the window. -The following table lists the available choices for the report mode or modes and file and the resulting behavior of **_CrtDbgReport** and **_CrtDbgReportW**. These options are defined as bit flags in \. +The following table lists the available choices for the report mode or modes and file and the resulting behavior of **`_CrtDbgReport`** and **`_CrtDbgReportW`**. These options are defined as bit flags in \. -|Report mode|Report file|**_CrtDbgReport**, **_CrtDbgReportW** behavior| -|-----------------|-----------------|------------------------------------------------| -|**_CRTDBG_MODE_DEBUG**|Not applicable|Writes message by using Windows [OutputDebugString](/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw) API.| -|**_CRTDBG_MODE_WNDW**|Not applicable|Calls Windows [MessageBox](/windows/win32/api/winuser/nf-winuser-messagebox) API to create message box to display the message along with **Abort**, **Retry**, and **Ignore** buttons. If a user clicks **Abort**, **_CrtDbgReport** or **_CrtDbgReport** immediately aborts. If a user clicks **Retry**, it returns 1. If a user clicks **Ignore**, execution continues and **_CrtDbgReport** and **_CrtDbgReportW** return 0. Note that clicking **Ignore** when an error condition exists often results in "undefined behavior."| -|**_CRTDBG_MODE_FILE**|**__HFILE**|Writes message to user-supplied **HANDLE**, using the Windows [WriteFile](/windows/win32/api/fileapi/nf-fileapi-writefile) API and does not verify validity of file handle; the application is responsible for opening the report file and passing a valid file handle.| -|**_CRTDBG_MODE_FILE**|**_CRTDBG_FILE_STDERR**|Writes message to **stderr**.| -|**_CRTDBG_MODE_FILE**|**_CRTDBG_FILE_STDOUT**|Writes message to **stdout**.| +| Report mode | Report file | **`_CrtDbgReport`**, **`_CrtDbgReportW`** behavior | +|---|---|---| +| `_CRTDBG_MODE_DEBUG` | Not applicable | Writes message by using Windows [`OutputDebugString`](/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw) API. | +| `_CRTDBG_MODE_WNDW` | Not applicable | Calls Windows [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) API to create message box to display the message along with **Abort**, **Retry**, and **Ignore** buttons. If a user chooses **Abort**, **`_CrtDbgReport`** or **`_CrtDbgReport`** immediately aborts. If a user chooses **Retry**, it returns 1. If a user chooses **Ignore**, execution continues and **`_CrtDbgReport`** and **`_CrtDbgReportW`** return 0. Choosing **Ignore** when an error condition exists often results in undefined behavior. | +| `_CRTDBG_MODE_FILE` | `__HFILE` | Writes message to user-supplied `HANDLE`, using the Windows [`WriteFile`](/windows/win32/api/fileapi/nf-fileapi-writefile) API and doesn't verify validity of file handle; the application is responsible for opening the report file and passing a valid file handle. | +| `_CRTDBG_MODE_FILE` | `_CRTDBG_FILE_STDERR` | Writes message to `stderr`. | +| `_CRTDBG_MODE_FILE` | `_CRTDBG_FILE_STDOUT` | Writes message to `stdout`. | -The report can be sent to one, two, or three destinations or to no destination at all. For more information about specifying the report mode or modes and report file, see the [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md) functions. For more information about using the debug macros and reporting functions, see [Macros for Reporting](/visualstudio/debugger/macros-for-reporting). +The report can be sent to one, two, or three destinations or to no destination at all. For more information about specifying the report mode or modes and report file, see the [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions. For more information about using the debug macros and reporting functions, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). -If your application needs more flexibility than that provided by **_CrtDbgReport** and **_CrtDbgReportW**, you can write your own reporting function and hook it into the C run-time library reporting mechanism by using the [_CrtSetReportHook](crtsetreporthook.md) function. +If your application needs more flexibility than that provided by **`_CrtDbgReport`** and **`_CrtDbgReportW`**, you can write your own reporting function and hook it into the C run-time library reporting mechanism by using the [`_CrtSetReportHook`](crtsetreporthook.md) function. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtDbgReport**|\| -|**_CrtDbgReportW**|\| +| Routine | Required header | +|---|---| +| **`_CrtDbgReport`** | \ | +| **`_CrtDbgReportW`** | \ | -**_CrtDbgReport** and **_CrtDbgReportW** are Microsoft extensions. For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_CrtDbgReport`** and **`_CrtDbgReportW`** are Microsoft extensions. For more information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -110,12 +110,12 @@ int main(int argc, char *argv[]) { } ``` -See [crt_dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2) for an example of how to change the report function. +See [`crt_dbg2`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2) for an example of how to change the report function. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtSetReportMode](crtsetreportmode.md)
-[_CrtSetReportFile](crtsetreportfile.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[_DEBUG](../../c-runtime-library/debug.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtSetReportMode`](crtsetreportmode.md)\ +[`_CrtSetReportFile`](crtsetreportfile.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`_DEBUG`](../debug.md) diff --git a/docs/c-runtime-library/reference/crtdoforallclientobjects.md b/docs/c-runtime-library/reference/crtdoforallclientobjects.md index 8c36215df3..fdf8480c26 100644 --- a/docs/c-runtime-library/reference/crtdoforallclientobjects.md +++ b/docs/c-runtime-library/reference/crtdoforallclientobjects.md @@ -10,9 +10,9 @@ f1_keywords: ["_CrtDoForAllClientObjects", "CrtDoForAllClientObjects", "crtdbg/_ helpviewer_keywords: ["_CrtDoForAllClientObjects function", "CrtDoForAllClientObjects function"] ms.assetid: d0fdb835-3cdc-45f1-9a21-54208e8df248 --- -# _CrtDoForAllClientObjects +# `_CrtDoForAllClientObjects` -Calls an application-supplied function for all **_CLIENT_BLOCK** types in the heap (debug version only). +Calls an application-supplied function for all `_CLIENT_BLOCK` types in the heap (debug version only). ## Syntax @@ -25,35 +25,35 @@ void _CrtDoForAllClientObjects( ### Parameters -*pfn*
-Pointer to the application-supplied function callback function. The first parameter to this function points to the data. The second parameter is the context pointer that is passed to the call to **_CrtDoForAllClientObjects**. +*`pfn`*\ +Pointer to the application-supplied function callback function. The first parameter to this function points to the data. The second parameter is the context pointer that is passed to the call to **`_CrtDoForAllClientObjects`**. -*context*
+*`context`*\ Pointer to the application-supplied context to pass to the application-supplied function. ## Remarks -The **_CrtDoForAllClientObjects** function searches the heap's linked list for memory blocks with the **_CLIENT_BLOCK** type and calls the application-supplied function when a block of this type is found. The found block and the *context* parameter are passed as arguments to the application-supplied function. During debugging, an application can track a specific group of allocations by explicitly calling the debug heap functions to allocate the memory and specifying that the blocks be assigned the **_CLIENT_BLOCK** block type. These blocks can then be tracked separately and reported on differently during leak detection and memory state reporting. +The **`_CrtDoForAllClientObjects`** function searches the heap's linked list for memory blocks with the `_CLIENT_BLOCK` type and calls the application-supplied function when a block of this type is found. The found block and the *`context`* parameter are passed as arguments to the application-supplied function. During debugging, an application can track a specific group of allocations by explicitly calling the debug heap functions to allocate the memory and specifying that the blocks be assigned the `_CLIENT_BLOCK` block type. These blocks can then be tracked separately and reported on differently during leak detection and memory state reporting. -If the **_CRTDBG_ALLOC_MEM_DF** bit field of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag is not turned on, **_CrtDoForAllClientObjects** immediately returns. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtDoForAllClientObjects** are removed during preprocessing. +If the `_CRTDBG_ALLOC_MEM_DF` bit field of the [`_crtDbgFlag`](../crtdbgflag.md) flag isn't turned on, **`_CrtDoForAllClientObjects`** immediately returns. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtDoForAllClientObjects`** are removed during preprocessing. -For more information about the **_CLIENT_BLOCK** type and how it can be used by other debug functions, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about the `_CLIENT_BLOCK` type and how it can be used by other debug functions, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). -If *pfn* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is set to **EINVAL** and the function returns. +If *`pfn`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is set to `EINVAL` and the function returns. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtDoForAllClientObjects**|\, \| +| Routine | Required header | +|---|---| +| **`_CrtDoForAllClientObjects`** | \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). **Libraries:** Debug versions of universal C run-time libraries only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtSetDbgFlag](crtsetdbgflag.md)
-[Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details)
-[_CrtReportBlockType](crtreportblocktype.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtSetDbgFlag`](crtsetdbgflag.md)\ +[Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions)\ +[`_CrtReportBlockType`](crtreportblocktype.md) diff --git a/docs/c-runtime-library/reference/crtdumpmemoryleaks.md b/docs/c-runtime-library/reference/crtdumpmemoryleaks.md index 3f55207d0f..28291b7a9c 100644 --- a/docs/c-runtime-library/reference/crtdumpmemoryleaks.md +++ b/docs/c-runtime-library/reference/crtdumpmemoryleaks.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CrtDumpMemoryLeaks" title: "_CrtDumpMemoryLeaks" +description: "Learn more about: _CrtDumpMemoryLeaks" ms.date: "11/04/2016" api_name: ["_CrtDumpMemoryLeaks"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,51 +8,49 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CRTDBG_LEAK_CHECK_DF", "CRTDBG_CHECK_CRT_DF", "_CRTDBG_LEAK_CHECK_DF", "CrtDumpMemoryLeaks", "_CrtDumpMemoryLeaks", "_CRTDBG_CHECK_CRT_DF"] helpviewer_keywords: ["CrtDumpMemoryLeaks function", "CRTDBG_LEAK_CHECK_DF macro", "_CRTDBG_LEAK_CHECK_DF macro", "_CrtDumpMemoryLeaks function", "CRTDBG_CHECK_CRT_DF macro", "_CRTDBG_CHECK_CRT_DF macro"] -ms.assetid: 71b2eab4-7f55-44e8-a55a-bfea4f32d34c --- -# _CrtDumpMemoryLeaks +# `_CrtDumpMemoryLeaks` Dumps all the memory blocks in the debug heap when a memory leak has occurred (debug version only). ## Syntax ```C - int _CrtDumpMemoryLeaks( void ); ``` -## Return Value +## Return value -**_CrtDumpMemoryLeaks** returns TRUE if a memory leak is found. Otherwise, the function returns FALSE. +**`_CrtDumpMemoryLeaks`** returns `TRUE` if a memory leak is found. Otherwise, the function returns `FALSE`. ## Remarks -The **_CrtDumpMemoryLeaks** function determines whether a memory leak has occurred since the start of program execution. When a leak is found, the debug header information for all the objects in the heap is dumped in a user-readable form. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtDumpMemoryLeaks** are removed during preprocessing. +The **`_CrtDumpMemoryLeaks`** function determines whether a memory leak has occurred since the start of program execution. When a leak is found, the debug header information for all the objects in the heap is dumped in a user-readable form. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtDumpMemoryLeaks`** are removed during preprocessing. -**_CrtDumpMemoryLeaks** is frequently called at the end of program execution to verify that all memory allocated by the application has been freed. The function can be called automatically at program termination by turning on the **_CRTDBG_LEAK_CHECK_DF** bit field of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag using the [_CrtSetDbgFlag](crtsetdbgflag.md) function. +**`_CrtDumpMemoryLeaks`** is frequently called at the end of program execution to verify that all memory allocated by the application has been freed. The function can be called automatically at program termination by turning on the `_CRTDBG_LEAK_CHECK_DF` bit field of the [`_crtDbgFlag`](../crtdbgflag.md) flag using the [`_CrtSetDbgFlag`](crtsetdbgflag.md) function. -**_CrtDumpMemoryLeaks** calls [_CrtMemCheckpoint](crtmemcheckpoint.md) to obtain the current state of the heap and then scans the state for blocks that have not been freed. When an unfreed block is encountered, **_CrtDumpMemoryLeaks** calls [_CrtMemDumpAllObjectsSince](crtmemdumpallobjectssince.md) to dump information for all the objects allocated in the heap from the start of program execution. +**`_CrtDumpMemoryLeaks`** calls [`_CrtMemCheckpoint`](crtmemcheckpoint.md) to obtain the current state of the heap and then scans the state for blocks that haven't been freed. When an unfreed block is encountered, **`_CrtDumpMemoryLeaks`** calls [`_CrtMemDumpAllObjectsSince`](crtmemdumpallobjectssince.md) to dump information for all the objects allocated in the heap from the start of program execution. -By default, internal C run-time blocks (**_CRT_BLOCK**) are not included in memory dump operations. The [_CrtSetDbgFlag](crtsetdbgflag.md) function can be used to turn on the **_CRTDBG_CHECK_CRT_DF** bit of **_crtDbgFlag** to include these blocks in the leak detection process. +By default, internal C run-time blocks (`_CRT_BLOCK`) aren't included in memory dump operations. The [`_CrtSetDbgFlag`](crtsetdbgflag.md) function can be used to turn on the `_CRTDBG_CHECK_CRT_DF` bit of **`_crtDbgFlag`** to include these blocks in the leak detection process. -For more information about heap state functions and the **_CrtMemState** structure, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about heap state functions and the **`_CrtMemState`** structure, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtDumpMemoryLeaks**|\| +| Routine | Required header | +|---|---| +| **`_CrtDumpMemoryLeaks`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_CrtDumpMemoryLeaks**, see [crt_dbg1](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). +For a sample of how to use **`_CrtDumpMemoryLeaks`**, see [`crt_dbg1`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtgetallochook.md b/docs/c-runtime-library/reference/crtgetallochook.md index df324f10e7..44feae4b2f 100644 --- a/docs/c-runtime-library/reference/crtgetallochook.md +++ b/docs/c-runtime-library/reference/crtgetallochook.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtGetAllocHook", "_CrtGetAllocHook"] helpviewer_keywords: ["_CrtGetAllocHook function", "CrtGetAllocHook function"] ms.assetid: 036acf7c-547a-4b3f-a636-80451070d7ed --- -# _CrtGetAllocHook +# `_CrtGetAllocHook` Retrieves the current client-defined allocation function for hooking into the C run-time debug memory allocation process (debug version only). @@ -20,29 +20,29 @@ Retrieves the current client-defined allocation function for hooking into the C _CRT_ALLOC_HOOK _CrtGetAllocHook( void ); ``` -## Return Value +## Return value Returns the currently defined allocation hook function. ## Remarks -**_CrtGetAllocHook** retrieves the current client-defined application hook function for the C run-time debug library memory allocation process. +**`_CrtGetAllocHook`** retrieves the current client-defined application hook function for the C run-time debug library memory allocation process. -For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug Hook Function Writing](/visualstudio/debugger/debug-hook-function-writing). +For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug hook function writing](../crt-debugging-techniques.md#debug-hook-function-writing). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtGetAllocHook**|\| +| Routine | Required header | +|---|---| +| **`_CrtGetAllocHook`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtSetAllocHook](crtsetallochook.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtSetAllocHook`](crtsetallochook.md) diff --git a/docs/c-runtime-library/reference/crtgetdumpclient.md b/docs/c-runtime-library/reference/crtgetdumpclient.md index bf2678dcd5..5fb865da19 100644 --- a/docs/c-runtime-library/reference/crtgetdumpclient.md +++ b/docs/c-runtime-library/reference/crtgetdumpclient.md @@ -10,9 +10,9 @@ f1_keywords: ["CrtGetDumpClient", "_CrtGetDumpClient"] helpviewer_keywords: ["_CrtGetDumpClient function", "CrtGetDumpClient function"] ms.assetid: 9051867f-341b-493b-b53d-45d2b454a3ad --- -# _CrtGetDumpClient +# `_CrtGetDumpClient` -Retrieves the current application-defined function for dumping the **_CLIENT_BLOCK** type memory blocks (debug version only). +Retrieves the current application-defined function for dumping the `_CLIENT_BLOCK` type memory blocks (debug version only). ## Syntax @@ -20,30 +20,30 @@ Retrieves the current application-defined function for dumping the **_CLIENT_BLO _CRT_DUMP_CLIENT _CrtGetDumpClient( void ); ``` -## Return Value +## Return value Returns the current dump routine. ## Remarks -The **_CrtGetDumpClient** function retrieves the current hook function for dumping objects stored in the **_CLIENT_BLOCK** memory blocks for the C run-time debug memory dump process. +The **`_CrtGetDumpClient`** function retrieves the current hook function for dumping objects stored in the `_CLIENT_BLOCK` memory blocks. -For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug Hook Function Writing](/visualstudio/debugger/debug-hook-function-writing). +For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug hook function writing](../crt-debugging-techniques.md#debug-hook-function-writing). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtGetDumpClient**|\| +| Routine | Required header | +|---|---| +| **`_CrtGetDumpClient`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtReportBlockType](crtreportblocktype.md)
-[_CrtSetDumpClient](crtsetdumpclient.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtReportBlockType`](crtreportblocktype.md)\ +[`_CrtSetDumpClient`](crtsetdumpclient.md) diff --git a/docs/c-runtime-library/reference/crtgetreporthook.md b/docs/c-runtime-library/reference/crtgetreporthook.md index 3e57a3b033..f1782c2533 100644 --- a/docs/c-runtime-library/reference/crtgetreporthook.md +++ b/docs/c-runtime-library/reference/crtgetreporthook.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtGetReportHook", "_CrtGetReportHook"] helpviewer_keywords: ["CrtGetReportHook function", "_CrtGetReportHook function"] ms.assetid: 922758ed-7edd-4359-9c92-0535192dc11a --- -# _CrtGetReportHook +# `_CrtGetReportHook` Retrieves the client-defined reporting function for hooking it into the C run time for the debug reporting process (debug version only). @@ -20,33 +20,33 @@ Retrieves the client-defined reporting function for hooking it into the C run ti _CRT_REPORT_HOOK _CrtGetReportHook( void ); ``` -## Return Value +## Return value Returns the current client-defined reporting function. ## Remarks -**_CrtGetReportHook** allows an application to retrieve the current reporting function for the C run-time debug library reporting process. +**`_CrtGetReportHook`** allows an application to retrieve the current reporting function for the C run-time debug library reporting process. -For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug Hook Function Writing](/visualstudio/debugger/debug-hook-function-writing). +For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug hook function writing](../crt-debugging-techniques.md#debug-hook-function-writing). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtGetReportHook**|\| +| Routine | Required header | +|---|---| +| **`_CrtGetReportHook`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_CrtSetReportHook**, see [report](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/report). +For a sample of how to use `_CrtSetReportHook`, see [`report`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/report). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtSetReportHook](crtsetreporthook.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtSetReportHook`](crtsetreporthook.md) diff --git a/docs/c-runtime-library/reference/crtismemoryblock.md b/docs/c-runtime-library/reference/crtismemoryblock.md index e3a942b381..367d8155be 100644 --- a/docs/c-runtime-library/reference/crtismemoryblock.md +++ b/docs/c-runtime-library/reference/crtismemoryblock.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtlsMemoryBlock", "_CrtIsMemoryBlock"] helpviewer_keywords: ["_CrtIsMemoryBlock function", "CrtIsMemoryBlock function"] ms.assetid: f7cbbc60-3690-4da0-a07b-68fd7f250273 --- -# _CrtIsMemoryBlock +# `_CrtIsMemoryBlock` Verifies that a specified memory block is in the local heap and that it has a valid debug heap block type identifier (debug version only). @@ -22,62 +22,62 @@ int _CrtIsMemoryBlock( unsigned int size, long *requestNumber, char **filename, - int *linenumber + int *lineNumber ); ``` ### Parameters -*userData*
+*`userData`*\ Pointer to the beginning of the memory block to verify. -*size*
+*`size`*\ Size of the specified block (in bytes). -*requestNumber*
-Pointer to the allocation number of the block or **NULL**. +*`requestNumber`*\ +Pointer to the allocation number of the block or `NULL`. -*filename*
-Pointer to the name of the source file that requested the block or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the block or `NULL`. -*linenumber*
-Pointer to the line number in the source file or **NULL**. +*`lineNumber`*\ +Pointer to the line number in the source file or `NULL`. -## Return Value +## Return value -**_CrtIsMemoryBlock** returns **TRUE** if the specified memory block is located within the local heap and has a valid debug heap block type identifier; otherwise, the function returns **FALSE**. +**`_CrtIsMemoryBlock`** returns `TRUE` if the specified memory block is located within the local heap and has a valid debug heap block type identifier; otherwise, the function returns `FALSE`. ## Remarks -The **_CrtIsMemoryBlock** function verifies that a specified memory block is located within the application's local heap and that it has a valid block type identifier. This function can also be used to obtain the object allocation order number and the source file name/line number where the memory block allocation was originally requested. Passing non-**NULL** values for the *requestNumber*, *filename*, or *linenumber* parameters causes **_CrtIsMemoryBlock** to set these parameters to the values in the memory block's debug header, if it finds the block in the local heap. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtIsMemoryBlock** are removed during preprocessing. +The **`_CrtIsMemoryBlock`** function verifies that a specified memory block is located within the application's local heap and that it has a valid block type identifier. This function can also be used to obtain the object allocation order number and the source file name/line number where the memory block allocation was originally requested. A non-`NULL` value passed in a *`requestNumber`*, *`filename`*, or *`lineNumber`* parameter causes **`_CrtIsMemoryBlock`** to set the parameter to the value in the memory block's debug header, if it finds the block in the local heap. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtIsMemoryBlock`** are removed during preprocessing. -If **_CrtIsMemoryBlock** fails, it returns **FALSE** and the output parameters are initialized to default values: *requestNumber* and **lineNumber** are set to 0 and *filename* is set to **NULL**. +If **`_CrtIsMemoryBlock`** fails, it returns `FALSE`, and the output parameters are initialized to default values: *`requestNumber`* and *`lineNumber`* are set to 0 and *`filename`* is set to `NULL`. -Because this function returns **TRUE** or **FALSE**, it can be passed to one of the [_ASSERT](assert-asserte-assert-expr-macros.md) macros to create a simple debugging error handling mechanism. The following example causes an assertion failure if the specified address is not located within the local heap: +Because this function returns `TRUE` or `FALSE`, it can be passed to one of the [`_ASSERT`](assert-asserte-assert-expr-macros.md) macros to create a basic debugging error handling mechanism. The following example causes an assertion failure if the specified address isn't located within the local heap: ```C _ASSERTE( _CrtIsMemoryBlock( userData, size, &requestNumber, &filename, &linenumber ) ); ``` -For more information about how **_CrtIsMemoryBlock** can be used with other debug functions and macros, see [Macros for Reporting](/visualstudio/debugger/macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about how **`_CrtIsMemoryBlock`** can be used with other debug functions and macros, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtIsMemoryBlock**|\| +| Routine | Required header | +|---|---| +| **`_CrtIsMemoryBlock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -See the example for the [_CrtIsValidHeapPointer](crtisvalidheappointer.md) topic. +See the example for the [`_CrtIsValidHeapPointer`](crtisvalidheappointer.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtisvalidheappointer.md b/docs/c-runtime-library/reference/crtisvalidheappointer.md index 7c834f21e2..8ed29e0417 100644 --- a/docs/c-runtime-library/reference/crtisvalidheappointer.md +++ b/docs/c-runtime-library/reference/crtisvalidheappointer.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtlsValidHeapPointer", "_CrtIsValidHeapPointer"] helpviewer_keywords: ["_CrtIsValidHeapPointer function", "CrtIsValidHeapPointer function"] -ms.assetid: caf597ce-1b05-4764-9f37-0197a982bec5 --- -# _CrtIsValidHeapPointer +# `_CrtIsValidHeapPointer` -Verifies that a specified pointer is in a heap allocated by some C run-time library, but not necessarily by the caller's CRT library. In versions of the CRT before Visual Studio 2010, this verifies that the specified pointer is in the local heap (debug version only). +Verifies that a specified pointer is in a heap allocated by some C run-time library, but not necessarily by the caller's CRT library. In versions of the CRT before Visual Studio 2010, this function verifies that the specified pointer is in the local heap (debug version only). ## Syntax @@ -24,40 +23,40 @@ int _CrtIsValidHeapPointer( ### Parameters -*userData*
+*`userData`*\ Pointer to the beginning of an allocated memory block. -## Return Value +## Return value -**_CrtIsValidHeapPointer** returns TRUE if the specified pointer is in the heap shared by all CRT library instances. In versions of the CRT before Visual Studio 2010, this returns TRUE if the specified pointer is in the local heap. Otherwise, the function returns FALSE. +**`_CrtIsValidHeapPointer`** returns `TRUE` if the specified pointer is in the heap shared by all CRT library instances. In versions of the CRT before Visual Studio 2010, this function returns `TRUE` if the specified pointer is in the local heap. Otherwise, the function returns `FALSE`. ## Remarks -We do not recommend that you use this function. Starting with the Visual Studio 2010 CRT library, all CRT libraries share one OS heap, the *process heap*. The **_CrtIsValidHeapPointer** function reports whether the pointer was allocated in a CRT heap, but not that it was allocated by the caller's CRT library. For example, consider a block allocated by using the Visual Studio 2010 version of the CRT library. If the **_CrtIsValidHeapPointer** function exported by the Visual Studio 2012 version of the CRT library tests the pointer, it returns TRUE. This is no longer a useful test. In versions of the CRT library before Visual Studio 2010, the function is used to ensure that a specific memory address is within the local heap. The local heap refers to the heap created and managed by a particular instance of the C run-time library. If a dynamic-link library (DLL) contains a static link to the run-time library, it has its own instance of the run-time heap, and therefore its own heap, independent of the application's local heap. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtIsValidHeapPointer** are removed during preprocessing. +We don't recommend that you use this function. Starting with the Visual Studio 2010 CRT library, all CRT libraries share one OS heap, the *process heap*. The **`_CrtIsValidHeapPointer`** function reports whether the pointer was allocated in a CRT heap, but not that it was allocated by the caller's CRT library. For example, consider a block allocated by using the Visual Studio 2010 version of the CRT library. If the **`_CrtIsValidHeapPointer`** function exported by the Visual Studio 2012 version of the CRT library tests the pointer, it returns `TRUE`. This test is no longer useful. In versions of the CRT library before Visual Studio 2010, the function is used to ensure that a specific memory address is within the local heap. The local heap refers to the heap created and managed by a particular instance of the C run-time library. If a dynamic-link library (DLL) contains a static link to the run-time library, it has its own instance of the run-time heap, and therefore its own heap, independent of the application's local heap. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtIsValidHeapPointer`** are removed during preprocessing. -Because this function returns TRUE or FALSE, it can be passed to one of the [_ASSERT](assert-asserte-assert-expr-macros.md) macros to create a simple debugging error handling mechanism. The following example causes an assertion failure if the specified address is not located within the local heap: +Because this function returns `TRUE` or `FALSE`, it can be passed to one of the [`_ASSERT`](assert-asserte-assert-expr-macros.md) macros to create a basic debugging error handling mechanism. The following example causes an assertion failure if the specified address isn't located within the local heap: ```C _ASSERTE( _CrtIsValidHeapPointer( userData ) ); ``` -For more information about how **_CrtIsValidHeapPointer** can be used with other debug functions and macros, see [Macros for Reporting](/visualstudio/debugger/macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about how **`_CrtIsValidHeapPointer`** can be used with other debug functions and macros, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtIsValidHeapPointer**|\| +| Routine | Required header | +|---|---| +| **`_CrtIsValidHeapPointer`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -The following example demonstrates how to test whether memory is valid when it is used with C run-time libraries before Visual Studio 2010. This example is provided for users of legacy CRT library code. +The following example demonstrates how to test whether memory is valid when it's used with C run-time libraries before Visual Studio 2010. This example is provided for users of legacy CRT library code. ```C // crt_isvalid.c @@ -111,4 +110,4 @@ my_pointer is within the local heap. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtisvalidpointer.md b/docs/c-runtime-library/reference/crtisvalidpointer.md index 7cd4a5eb5f..202506f2c0 100644 --- a/docs/c-runtime-library/reference/crtisvalidpointer.md +++ b/docs/c-runtime-library/reference/crtisvalidpointer.md @@ -10,9 +10,9 @@ f1_keywords: ["CrtlsValidPointer", "_CrtIsValidPointer"] helpviewer_keywords: ["CrtIsValidPointer function", "_CrtIsValidPointer function"] ms.assetid: 91c35590-ea5e-450f-a15d-ad8d62ade1fa --- -# _CrtIsValidPointer +# `_CrtIsValidPointer` -Verifies that a pointer is not null. In versions of the C run-time library before Visual Studio 2010, verifies that a specified memory range is valid for reading and writing (debug version only). +Verifies that a pointer isn't null. In versions of the C run-time library before Visual Studio 2010, verifies that a specified memory range is valid for reading and writing (debug version only). ## Syntax @@ -26,47 +26,47 @@ int _CrtIsValidPointer( ### Parameters -*address*
+*`address`*\ Points to the beginning of the memory range to test for validity. -*size*
+*`size`*\ Size of the specified memory range (in bytes). -*access*
+*`access`*\ Read/write accessibility to determine for the memory range. -## Return Value +## Return value -**_CrtIsValidPointer** returns TRUE if the specified pointer is not null. In CRT library versions before Visual Studio 2010, returns TRUE if the memory range is valid for the specified operation or operations. Otherwise, the function returns FALSE. +**`_CrtIsValidPointer`** returns `TRUE` if the specified pointer isn't null. In CRT library versions before Visual Studio 2010, returns `TRUE` if the memory range is valid for the specified operation or operations. Otherwise, the function returns `FALSE`. ## Remarks -Starting with the CRT library in Visual Studio 2010, the *size* and *access* parameters are ignored, and **_CrtIsValidPointer** only verifies that the specified *address* is not null. Because this test is easy to perform yourself, we do not recommend you use this function. In versions before Visual Studio 2010, the function verifies that the memory range beginning at *address* and extending for *size* bytes is valid for the specified accessibility operation or operations. When *access* is set to TRUE, the memory range is verified for both reading and writing. When *access* is FALSE, the memory range is only validated for reading. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtIsValidPointer** are removed during preprocessing. +In the CRT library in Visual Studio 2010 and later versions, the *`size`* and *`access`* parameters are ignored, and **`_CrtIsValidPointer`** only verifies that the specified *`address`* isn't null. Because this test is easy to perform yourself, we don't recommend you use this function. In versions before Visual Studio 2010, the function verifies that the memory range beginning at *`address`* and extending for *`size`* bytes is valid for the specified accessibility operation or operations. When *`access`* is set to `TRUE`, the memory range is verified for both reading and writing. When *`access`* is `FALSE`, the memory range is only validated for reading. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtIsValidPointer`** are removed during preprocessing. -Because this function returns TRUE or FALSE, it can be passed to one of the [_ASSERT](assert-asserte-assert-expr-macros.md) macros to create a simple debugging error handling mechanism. The following example causes an assertion failure if the memory range is not valid for both reading and writing operations: +Because this function returns `TRUE` or `FALSE`, it can be passed to one of the [`_ASSERT`](assert-asserte-assert-expr-macros.md) macros to create a basic debugging error handling mechanism. The following example causes an assertion failure if the memory range isn't valid for both reading and writing operations: ```C _ASSERTE( _CrtIsValidPointer( address, size, TRUE ) ); ``` -For more information about how **_CrtIsValidPointer** can be used with other debug functions and macros, see [Macros for Reporting](/visualstudio/debugger/macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about how **`_CrtIsValidPointer`** can be used with other debug functions and macros, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtIsValidPointer**|\| +| Routine | Required header | +|---|---| +| **`_CrtIsValidPointer`** | \ | -**_CrtIsValidPointer** is a Microsoft extension. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_CrtIsValidPointer`** is a Microsoft extension. For compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -See the example for the [_CrtIsValidHeapPointer](crtisvalidheappointer.md) topic. +See the example for the [`_CrtIsValidHeapPointer`](crtisvalidheappointer.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtmemcheckpoint.md b/docs/c-runtime-library/reference/crtmemcheckpoint.md index 05bf4fda7e..9f5043ab22 100644 --- a/docs/c-runtime-library/reference/crtmemcheckpoint.md +++ b/docs/c-runtime-library/reference/crtmemcheckpoint.md @@ -10,9 +10,9 @@ f1_keywords: ["CrtMemCheckpoint", "_CrtMemCheckpoint", "crtdbg/_CrtMemCheckpoint helpviewer_keywords: ["CrtMemCheckpoint function", "_CrtMemCheckpoint function"] ms.assetid: f1bacbaa-5a0c-498a-ac7a-b6131d83dfbc --- -# _CrtMemCheckpoint +# `_CrtMemCheckpoint` -Obtains the current state of the debug heap and stores in an application-supplied **_CrtMemState** structure (debug version only). +Obtains the current state of the debug heap and stores in an application-supplied `_CrtMemState` structure (debug version only). ## Syntax @@ -24,30 +24,30 @@ void _CrtMemCheckpoint( ### Parameters -*state*
-Pointer to **_CrtMemState** structure to fill with the memory checkpoint. +*`state`*\ +Pointer to `_CrtMemState` structure to fill with the memory checkpoint. ## Remarks -The **_CrtMemCheckpoint** function creates a snapshot of the current state of the debug heap at any given moment. This snapshot can be used by other heap state functions such as [_CrtMemDifference](crtmemdifference.md) to help detect memory leaks and other problems. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtMemState** are removed during preprocessing. +The **`_CrtMemCheckpoint`** function creates a snapshot of the current state of the debug heap at any given moment. This snapshot can be used by other heap state functions such as [`_CrtMemDifference`](crtmemdifference.md) to help detect memory leaks and other problems. When [`_DEBUG`](../debug.md) isn't defined, calls to `_CrtMemState` are removed during preprocessing. -The application must pass a pointer to a previously allocated instance of the **_CrtMemState** structure, defined in Crtdbg.h, in the *state* parameter. If **_CrtMemCheckpoint** encounters an error during the checkpoint creation, the function generates a **_CRT_WARN** debug report describing the problem. +The application must pass a pointer to a previously allocated instance of the `_CrtMemState` structure, defined in Crtdbg.h, in the *`state`* parameter. If **`_CrtMemCheckpoint`** encounters an error during the checkpoint creation, the function generates a `_CRT_WARN` debug report describing the problem. -For more information about heap state functions and the **_CrtMemState** structure, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about heap state functions and the `_CrtMemState` structure, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). -If *state* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is set to **EINVAL** and the function returns. +If *`state`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is set to `EINVAL` and the function returns. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtMemCheckpoint**|\, \| +| Routine | Required header | +|---|---| +| **`_CrtMemCheckpoint`** | \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). **Libraries:** Debug versions of the UCRT only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtMemDifference](crtmemdifference.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtMemDifference`](crtmemdifference.md) diff --git a/docs/c-runtime-library/reference/crtmemdifference.md b/docs/c-runtime-library/reference/crtmemdifference.md index 71304902ae..2424df0b3f 100644 --- a/docs/c-runtime-library/reference/crtmemdifference.md +++ b/docs/c-runtime-library/reference/crtmemdifference.md @@ -34,33 +34,33 @@ Pointer to an earlier memory state (**`_CrtMemState`** structure). *`newState`*\ Pointer to a later memory state (**`_CrtMemState`** structure). -## Return Value +## Return value -If the memory states are significantly different, **`_CrtMemDifference`** returns `TRUE`. Otherwise, the function returns FALSE. +If the difference in memory states is significant, **`_CrtMemDifference`** returns `TRUE`. Otherwise, the function returns `FALSE`. ## Remarks -The **`_CrtMemDifference`** function compares *`oldState`* and *`newState`* and stores their differences in *`stateDiff`*, which can then be used by the app to detect memory leaks and other memory problems. When [_DEBUG](../../c-runtime-library/debug.md) isn't defined, calls to **`_CrtMemDifference`** are removed during preprocessing. +The **`_CrtMemDifference`** function compares *`oldState`* and *`newState`* and stores their differences in *`stateDiff`*, which can then be used by the app to detect memory leaks and other memory problems. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtMemDifference`** are removed during preprocessing. -*`newState`* and *`oldState`* must each be a valid pointer to a **`_CrtMemState`** structure, defined in Crtdbg.h, that has been filled in by [`_CrtMemCheckpoint`](crtmemcheckpoint.md) before calling **`_CrtMemDifference`**. *`stateDiff`* must be a pointer to a previously allocated instance of the **`_CrtMemState`** structure. If *`stateDiff`*, *`newState`*, or *`oldState`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is set to **`EINVAL`** and the function returns FALSE. +*`newState`* and *`oldState`* must each be a valid pointer to a **`_CrtMemState`** structure, defined in `crtdbg.h`, that [`_CrtMemCheckpoint`](crtmemcheckpoint.md) has filled in before the call to **`_CrtMemDifference`**. *`stateDiff`* must be a pointer to a previously allocated instance of the **`_CrtMemState`** structure. If *`stateDiff`*, *`newState`*, or *`oldState`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is set to `EINVAL` and the function returns `FALSE`. -**`_CrtMemDifference`** compares the **`_CrtMemState`** field values of the blocks in *`oldState`* to those in *`newState`* and stores the result in *`stateDiff`*. When the number of allocated block types or total number of allocated blocks for each type differs between the two memory states, the states are said to be significantly different. The difference between the largest amount ever allocated at once for the two states and the difference between total allocations for the two states are also stored in *`stateDiff`*. +**`_CrtMemDifference`** compares the **`_CrtMemState`** field values of the blocks in *`oldState`* to the ones in *`newState`* and stores the result in *`stateDiff`*. When the number of allocated block types or total number of allocated blocks for each type differs between the two memory states, the difference in states is considered significant. The difference between the largest amount ever allocated at once for the two states and the difference between total allocations for the two states are also stored in *`stateDiff`*. -By default, internal C run-time blocks (**`_CRT_BLOCK`**) aren't included in memory state operations. The [_CrtSetDbgFlag](crtsetdbgflag.md) function can be used to turn on the **`_CRTDBG_CHECK_CRT_DF`** bit of **`_crtDbgFlag`** to include these blocks in leak detection and other memory state operations. Freed memory blocks (**`_FREE_BLOCK`**) don't cause **`_CrtMemDifference`** to return `TRUE`. +By default, internal C run-time blocks (`_CRT_BLOCK`) aren't included in memory state operations. The [`_CrtSetDbgFlag`](crtsetdbgflag.md) function can be used to turn on the `_CRTDBG_CHECK_CRT_DF` bit of **`_crtDbgFlag`** to include these blocks in leak detection and other memory state operations. Freed memory blocks (`_FREE_BLOCK`) don't cause **`_CrtMemDifference`** to return `TRUE`. -For more information about heap state functions and the **`_CrtMemState`** structure, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about heap state functions and the **`_CrtMemState`** structure, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_CrtMemDifference`**|``|``| +| Routine | Required header | Optional header | +|---|---|---| +| **`_CrtMemDifference`** | `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** Debug versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md) only. +**Libraries:** Debug versions of the [C runtime libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)\ -[`_crtDbgFlag`](../../c-runtime-library/crtdbgflag.md)\ +[Debug routines](../debug-routines.md)\ +[`_crtDbgFlag`](../crtdbgflag.md) diff --git a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md index 9c66d37ed9..0f3b1f0fdd 100644 --- a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md +++ b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtMemDumpAllObjectsSince", "_CrtMemDumpAllObjectsSince"] helpviewer_keywords: ["_CrtMemDumpAllObjectsSince function", "CrtMemDumpAllObjectsSince function"] ms.assetid: c48a447a-e6bb-475c-9271-a3021182a0dc --- -# _CrtMemDumpAllObjectsSince +# `_CrtMemDumpAllObjectsSince` Dumps information about objects in the heap from the start of program execution or from a specified heap state (debug version only). @@ -24,36 +24,36 @@ void _CrtMemDumpAllObjectsSince( ### Parameters -*state*
-Pointer to the heap state to begin dumping from or **NULL**. +*`state`*\ +Pointer to the heap state to begin dumping from or `NULL`. ## Remarks -The **_CrtMemDumpAllObjectsSince** function dumps the debug header information of objects allocated in the heap in a user-readable form. The dump information can be used by the application to track allocations and detect memory problems. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtMemDumpAllObjectsSince** are removed during preprocessing. +The **`_CrtMemDumpAllObjectsSince`** function dumps the debug header information of objects allocated in the heap in a user-readable form. The dump information can be used by the application to track allocations and detect memory problems. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtMemDumpAllObjectsSince`** are removed during preprocessing. -**_CrtMemDumpAllObjectsSince** uses the value of the *state* parameter to determine where to initiate the dump operation. To begin dumping from a specified heap state, the *state* parameter must be a pointer to a **_CrtMemState** structure that has been filled in by [_CrtMemCheckpoint](crtmemcheckpoint.md) before **_CrtMemDumpAllObjectsSince** was called. When *state* is **NULL**, the function begins the dump from the start of program execution. +**`_CrtMemDumpAllObjectsSince`** uses the value of the *`state`* parameter to determine where to initiate the dump operation. To begin dumping from a specified heap state, the *`state`* parameter must be a pointer to a `_CrtMemState` structure that has been filled in by [`_CrtMemCheckpoint`](crtmemcheckpoint.md) before **`_CrtMemDumpAllObjectsSince`** was called. When *`state`* is `NULL`, the function begins the dump from the start of program execution. -If the application has installed a dump hook function by calling [_CrtSetDumpClient](crtsetdumpclient.md), then every time **_CrtMemDumpAllObjectsSince** dumps information about a **_CLIENT_BLOCK** type of block, it calls the application-supplied dump function as well. By default, internal C run-time blocks (**_CRT_BLOCK**) are not included in memory dump operations. The [_CrtSetDbgFlag](crtsetdbgflag.md) function can be used to turn on the **_CRTDBG_CHECK_CRT_DF** bit of **_crtDbgFlag** to include these blocks. In addition, blocks marked as freed or ignored (**_FREE_BLOCK**, **_IGNORE_BLOCK**) are not included in the memory dump. +If the application has installed a dump hook function by calling [`_CrtSetDumpClient`](crtsetdumpclient.md), then every time **`_CrtMemDumpAllObjectsSince`** dumps information about a `_CLIENT_BLOCK` type of block, it calls the application-supplied dump function as well. By default, internal C run-time blocks (`_CRT_BLOCK`) aren't included in memory dump operations. The [`_CrtSetDbgFlag`](crtsetdbgflag.md) function can be used to turn on the `_CRTDBG_CHECK_CRT_DF` bit of `_crtDbgFlag` to include these blocks. In addition, blocks marked as freed or ignored (`_FREE_BLOCK`, `_IGNORE_BLOCK`) aren't included in the memory dump. -For more information about heap state functions and the **_CrtMemState** structure, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about heap state functions and the `_CrtMemState` structure, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtMemDumpAll-ObjectsSince**|\| +| Routine | Required header | +|---|---| +| **_CrtMemDumpAll-ObjectsSince** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_CrtMemDumpAllObjectsSince**, see [crt_dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). +For a sample of how to use **`_CrtMemDumpAllObjectsSince`**, see [`crt_dbg2`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_crtDbgFlag](../../c-runtime-library/crtdbgflag.md)
+[Debug routines](../debug-routines.md)\ +[`_crtDbgFlag`](../crtdbgflag.md) diff --git a/docs/c-runtime-library/reference/crtmemdumpstatistics.md b/docs/c-runtime-library/reference/crtmemdumpstatistics.md index c72faeafb3..8c41b648eb 100644 --- a/docs/c-runtime-library/reference/crtmemdumpstatistics.md +++ b/docs/c-runtime-library/reference/crtmemdumpstatistics.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CrtMemDumpStatistics" title: "_CrtMemDumpStatistics" +description: "Learn more about: _CrtMemDumpStatistics" ms.date: "11/04/2016" api_name: ["_CrtMemDumpStatistics"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtMemDumpStatistics", "_CrtMemDumpStatistics"] helpviewer_keywords: ["_CrtMemDumpStatistics function", "CrtMemDumpStatistics function"] -ms.assetid: 27b9d731-3184-4a2d-b9a7-6566ab28a9fe --- -# _CrtMemDumpStatistics +# `_CrtMemDumpStatistics` Dumps the debug header information for a specified heap state in a user-readable form (debug version only). @@ -24,27 +23,27 @@ void _CrtMemDumpStatistics( ### Parameters -*state*
+*`state`*\ Pointer to the heap state to dump. ## Remarks -The **_CrtMemDumpStatistics** function dumps the debug header information for a specified state of the heap in a user-readable form. The dump statistics can be used by the application to track allocations and detect memory problems. The memory state can contain a specific heap state or the difference between two states. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtMemDumpStatistics** are removed during preprocessing. +The **`_CrtMemDumpStatistics`** function dumps the debug header information for a specified state of the heap in a user-readable form. The dump statistics can be used by the application to track allocations and detect memory problems. The memory state can contain a specific heap state or the difference between two states. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtMemDumpStatistics`** are removed during preprocessing. -The *state* parameter must be a pointer to a **_CrtMemState** structure that has been filled in by [_CrtMemCheckpoint](crtmemcheckpoint.md) or returned by [_CrtMemDifference](crtmemdifference.md) before **_CrtMemDumpStatistics** is called. If *state* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and no action is taken. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +The *`state`* parameter must be a pointer to a `_CrtMemState` structure that has been filled in by [`_CrtMemCheckpoint`](crtmemcheckpoint.md) or returned by [`_CrtMemDifference`](crtmemdifference.md) before **`_CrtMemDumpStatistics`** is called. If *`state`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and no action is taken. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For more information about heap state functions and the **_CrtMemState** structure, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about heap state functions and the `_CrtMemState` structure, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_CrtMemDumpStatistics**|\|\| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_CrtMemDumpStatistics`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** Debug versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md) only. +**Libraries:** Debug versions of the [C runtime libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtreportblocktype.md b/docs/c-runtime-library/reference/crtreportblocktype.md index 7695f04bd8..e9c58f7c24 100644 --- a/docs/c-runtime-library/reference/crtreportblocktype.md +++ b/docs/c-runtime-library/reference/crtreportblocktype.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _CrtReportBlockType" title: "_CrtReportBlockType" -ms.date: "11/04/2016" +description: "Learn more about: _CrtReportBlockType" +ms.date: 11/04/2016 api_name: ["_CrtReportBlockType"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CrtReportBlockType", "CrtReportBlockType"] helpviewer_keywords: ["CrtReportBlockType function", "BLOCK_SUBTYPE macro", "_CrtReportBlockType function", "_BLOCK_TYPE macro", "_BLOCK_SUBTYPE macro", "BLOCK_TYPE macro"] -ms.assetid: 0f4b9da7-bebb-4956-9541-b2581640ec6b --- -# _CrtReportBlockType +# `_CrtReportBlockType` Returns the block type/subtype associated with a given debug heap block pointer. @@ -19,35 +18,35 @@ Returns the block type/subtype associated with a given debug heap block pointer. ```C int _CrtReportBlockType( const void * pBlock -}; +); ``` ### Parameters -*pBlock*
+*`pBlock`*\ Pointer to a valid debug heap block. -## Return Value +## Return value -When passed a valid debug heap pointer, the **_CrtReportBlockType** function returns the block type and subtype in the form of an **`int`**. When passed an invalid pointer, the function returns -1. +When passed a valid debug heap pointer, the **`_CrtReportBlockType`** function returns the block type and subtype in the form of an **`int`**. When passed an invalid pointer, the function returns -1. ## Remarks -To extract the type and subtype returned by **_CrtReportBlockType**, use the macros **_BLOCK_TYPE** and **_BLOCK_SUBTYPE** (both defined in Crtdbg.h) on the return value. +To extract the type and subtype returned by **`_CrtReportBlockType`**, use the macros `_BLOCK_TYPE` and `_BLOCK_SUBTYPE` (both defined in Crtdbg.h) on the return value. -For information about the allocation block types and how they are used, see [Types of Blocks on the Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtReportBlockType**|\| +| Routine | Required header | +|---|---| +| **`_CrtReportBlockType`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -89,7 +88,7 @@ int main(void) } ``` -### Sample Output +### Sample output ```Output Dumper found block at 00314F78: type 4, subtype 3 @@ -110,7 +109,7 @@ Object dump complete. ## See also -[_CrtDoForAllClientObjects](crtdoforallclientobjects.md)
-[_CrtSetDumpClient](crtsetdumpclient.md)
-[_CrtMemDumpAllObjectsSince](crtmemdumpallobjectssince.md)
-[_CrtDumpMemoryLeaks](crtdumpmemoryleaks.md)
+[`_CrtDoForAllClientObjects`](crtdoforallclientobjects.md)\ +[`_CrtSetDumpClient`](crtsetdumpclient.md)\ +[`_CrtMemDumpAllObjectsSince`](crtmemdumpallobjectssince.md)\ +[`_CrtDumpMemoryLeaks`](crtdumpmemoryleaks.md) diff --git a/docs/c-runtime-library/reference/crtsetallochook.md b/docs/c-runtime-library/reference/crtsetallochook.md index ab4ddbfdb8..9219339783 100644 --- a/docs/c-runtime-library/reference/crtsetallochook.md +++ b/docs/c-runtime-library/reference/crtsetallochook.md @@ -10,7 +10,7 @@ f1_keywords: ["_CrtSetAllocHook", "CrtSetAllocHook"] helpviewer_keywords: ["_CrtSetAllocHook function", "CrtSetAllocHook function"] ms.assetid: 405df37b-2fd1-42c8-83bc-90887f17f29d --- -# _CrtSetAllocHook +# `_CrtSetAllocHook` Installs a client-defined allocation function by hooking it into the C run-time debug memory allocation process (debug version only). @@ -24,18 +24,18 @@ _CRT_ALLOC_HOOK _CrtSetAllocHook( ### Parameters -*allocHook*
+*`allocHook`*\ New client-defined allocation function to hook into the C run-time debug memory allocation process. -## Return Value +## Return value -Returns the previously defined allocation hook function, or **NULL** if *allocHook* is **NULL**. +Returns the previously defined allocation hook function, or `NULL` if *`allocHook`* is `NULL`. ## Remarks -**_CrtSetAllocHook** allows an application to hook its own allocation function into the C run-time debug library memory allocation process. As a result, every call to a debug allocation function to allocate, reallocate, or free a memory block triggers a call to the application's hook function. **_CrtSetAllocHook** provides an application with an easy method for testing how the application handles insufficient memory situations, the ability to examine allocation patterns, and the opportunity to log allocation information for later analysis. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetAllocHook** are removed during preprocessing. +**`_CrtSetAllocHook`** allows an application to hook its own allocation function into the C run-time debug library memory allocation process. As a result, every call to a debug allocation function to allocate, reallocate, or free a memory block triggers a call to the application's hook function. **`_CrtSetAllocHook`** provides an application with an easy method for testing how the application handles insufficient memory situations, the ability to examine allocation patterns, and the opportunity to log allocation information for later analysis. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetAllocHook`** are removed during preprocessing. -The **_CrtSetAllocHook** function installs the new client-defined allocation function specified in *allocHook* and returns the previously defined hook function. The following example demonstrates how a client-defined allocation hook should be prototyped: +The **`_CrtSetAllocHook`** function installs the new client-defined allocation function specified in *`allocHook`* and returns the previously defined hook function. The following example demonstrates how a client-defined allocation hook should be prototyped: ```C int YourAllocHook( int allocType, void *userData, size_t size, @@ -43,38 +43,38 @@ int YourAllocHook( int allocType, void *userData, size_t size, const unsigned char *filename, int lineNumber); ``` -The **allocType** argument specifies the type of allocation operation (**_HOOK_ALLOC**, **_HOOK_REALLOC**, and **_HOOK_FREE**) that triggered the call to the allocation's hook function. When the triggering allocation type is **_HOOK_FREE**, *userData* is a pointer to the user data section of the memory block about to be freed. However, when the triggering allocation type is **_HOOK_ALLOC** or **_HOOK_REALLOC**, *userData* is **NULL** because the memory block has not been allocated yet. +The `allocType` argument specifies the type of allocation operation (`_HOOK_ALLOC`, `_HOOK_REALLOC`, and `_HOOK_FREE`) that triggered the call to the allocation's hook function. When the triggering allocation type is `_HOOK_FREE`, *`userData`* is a pointer to the user data section of the memory block about to be freed. However, when the triggering allocation type is `_HOOK_ALLOC` or `_HOOK_REALLOC`, *`userData`* is `NULL` because the memory block hasn't been allocated yet. -*size* specifies the size of the memory block in bytes, *blockType* indicates the type of the memory block, *requestNumber* is the object allocation order number of the memory block, and, if available, *filename* and **lineNumber** specify the source file name and line number where the triggering allocation operation was initiated. +*`size`* specifies the size of the memory block in bytes, *`blockType`* indicates the type of the memory block, *`requestNumber`* is the object allocation order number of the memory block, and, if available, *`filename`* and *`lineNumber`* specify the source file name and line number where the triggering allocation operation was initiated. -After the hook function has finished processing, it must return a Boolean value, which tells the main C run-time allocation process how to continue. When the hook function wants the main allocation process to continue as if the hook function had never been called, then the hook function should return **TRUE**. This causes the original triggering allocation operation to be executed. Using this implementation, the hook function can gather and save allocation information for later analysis, without interfering with the current allocation operation or state of the debug heap. +After the hook function has finished processing, it must return a Boolean value, which tells the main C run-time allocation process how to continue. When the hook function wants the main allocation process to continue as if the hook function had never been called, then the hook function should return `TRUE`, which causes the original triggering allocation operation to be executed. The hook function can gather and save allocation information for later analysis, without interfering with the current allocation operation or state of the debug heap. -When the hook function wants the main allocation process to continue as if the triggering allocation operation was called and it failed, then the hook function should return **FALSE**. Using this implementation, the hook function can simulate a wide range of memory conditions and debug heap states to test how the application handles each situation. +When the hook function wants the main allocation process to continue as if the triggering allocation operation was called and it failed, then the hook function should return `FALSE`. The hook function can simulate a wide range of memory conditions and debug heap states to test how the application handles each situation. -To clear the hook function, pass **NULL** to **_CrtSetAllocHook**. +To clear the hook function, pass `NULL` to **`_CrtSetAllocHook`**. -For more information about how **_CrtSetAllocHook** can be used with other memory management functions or how to write your own client-defined hook functions, see [Debug Hook Function Writing](/visualstudio/debugger/debug-hook-function-writing). +For more information about how **`_CrtSetAllocHook`** can be used with other memory management functions or how to write your own client-defined hook functions, see [Debug hook function writing](../crt-debugging-techniques.md#debug-hook-function-writing). > [!NOTE] -> **_CrtSetAllocHook** is not supported under **/clr:pure**. The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and removed in Visual Studio 2017. +> **`_CrtSetAllocHook`** is not supported under **/clr:pure**. The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and removed in Visual Studio 2017. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetAllocHook**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetAllocHook`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_CrtSetAllocHook**, see [crt_dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). +For a sample of how to use **`_CrtSetAllocHook`**, see [`crt_dbg2`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtGetAllocHook](crtgetallochook.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtGetAllocHook`](crtgetallochook.md) diff --git a/docs/c-runtime-library/reference/crtsetbreakalloc.md b/docs/c-runtime-library/reference/crtsetbreakalloc.md index 9a8727ae1a..dba54054c4 100644 --- a/docs/c-runtime-library/reference/crtsetbreakalloc.md +++ b/docs/c-runtime-library/reference/crtsetbreakalloc.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CrtSetBreakAlloc" title: "_CrtSetBreakAlloc" +description: "Learn more about: _CrtSetBreakAlloc" ms.date: "11/04/2016" api_name: ["_CrtSetBreakAlloc"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtSetBreakAlloc", "_CrtSetBreakAlloc"] helpviewer_keywords: ["CrtSetBreakAlloc function", "_CrtSetBreakAlloc function"] -ms.assetid: 33bfc6af-a9ea-405b-a29f-1c2d4d9880a1 --- -# _CrtSetBreakAlloc +# `_CrtSetBreakAlloc` Sets a breakpoint on a specified object allocation order number (debug version only). @@ -24,32 +23,32 @@ long _CrtSetBreakAlloc( ### Parameters -*lBreakAlloc*
+*`lBreakAlloc`*\ Allocation order number, for which to set the breakpoint. -## Return Value +## Return value Returns the previous object allocation order number that had a breakpoint set. ## Remarks -**_CrtSetBreakAlloc** allows an application to perform memory leak detection by breaking at a specific point of memory allocation and tracing back to the origin of the request. The function uses the sequential object allocation order number assigned to the memory block when it was allocated in the heap. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetBreakAlloc** are removed during preprocessing. +**`_CrtSetBreakAlloc`** allows an application to perform memory leak detection by breaking at a specific point of memory allocation and tracing back to the origin of the request. The function uses the sequential object allocation order number assigned to the memory block when it was allocated in the heap. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetBreakAlloc`** are removed during preprocessing. -The object allocation order number is stored in the *lRequest* field of the **_CrtMemBlockHeader** structure, defined in Crtdbg.h. When information about a memory block is reported by one of the debug dump functions, this number is enclosed in braces, such as {36}. +The object allocation order number is stored in the *`lRequest`* field of the `_CrtMemBlockHeader` structure, defined in Crtdbg.h. When information about a memory block is reported by one of the debug dump functions, this number is enclosed in braces, such as {36}. -For more information about how **_CrtSetBreakAlloc** can be used with other memory management functions, see [Tracking Heap Allocation Requests](/visualstudio/debugger/crt-debug-heap-details). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For more information about how **`_CrtSetBreakAlloc`** can be used with other memory management functions, see [Tracking heap allocation requests](../crt-debug-heap-details.md#track-heap-allocation-requests). For more information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetBreakAlloc**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetBreakAlloc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -99,4 +98,4 @@ int main( ) ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtsetdbgflag.md b/docs/c-runtime-library/reference/crtsetdbgflag.md index a6f51e36b2..e65cc7cb4e 100644 --- a/docs/c-runtime-library/reference/crtsetdbgflag.md +++ b/docs/c-runtime-library/reference/crtsetdbgflag.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CRTDBG_REPORT_FLAG", "_CRTDBG_CHECK_EVERY_16_DF", "_CRTDBG_CHECK_DEFAULT_DF", "CRTDBG_CHECK_DEFAULT_DF", "CRTDBG_CHECK_EVERY_128_DF", "CRTDBG_CHECK_EVERY_1024_DF", "_CRTDBG_CHECK_EVERY_128_DF", "CrtSetDbgFlag", "CRTDBG_CHECK_EVERY_16_DF", "_CRTDBG_CHECK_EVERY_1024_DF", "_CrtSetDbgFlag", "CRTDBG_REPORT_FLAG"] helpviewer_keywords: ["_CRTDBG_CHECK_EVERY_16_DF macro", "CRTDBG_CHECK_EVERY_16_DF macro", "_CRTDBG_CHECK_ALWAYS_DF macro", "_CRTDBG_CHECK_DEFAULT_DF macro", "CRTDBG_ALLOC_MEM_DF macro", "CRTDBG_CHECK_ALWAYS_DF macro", "_CRTDBG_ALLOC_MEM_DF macro", "_CRTDBG_REPORT_FLAG macro", "_CRTDBG_CHECK_EVERY_128_DF macro", "CRTDBG_REPORT_FLAG macro", "_CRTDBG_CHECK_EVERY_1024_DF macro", "CRTDBG_CHECK_DEFAULT_DF macro", "CRTDBG_CHECK_EVERY_1024_DF macro", "_CrtSetDbgFlag function", "CrtSetDbgFlag function", "_CRTDBG_DELAY_FREE_MEM_DF macro", "CRTDBG_CHECK_EVERY_128_DF macro", "CRTDBG_DELAY_FREE_MEM_DF macro", "CRTDBG_CHECK_CRT_DF macro", "_CRTDBG_CHECK_CRT_DF macro"] -ms.assetid: b5657ffb-6178-4cbf-9886-1af904ede94c --- -# _CrtSetDbgFlag +# `_CrtSetDbgFlag` -Retrieves or modifies the state of the **_crtDbgFlag** flag to control the allocation behavior of the debug heap manager (debug version only). +Retrieves or modifies the state of the **`_crtDbgFlag`** flag to control the allocation behavior of the debug heap manager (debug version only). ## Syntax @@ -24,43 +23,49 @@ int _CrtSetDbgFlag( ### Parameters -*newFlag*
-New state for **_crtDbgFlag**. +*`newFlag`*\ +New state for **`_crtDbgFlag`**. -## Return Value +## Return value -Returns the previous state of **_crtDbgFlag**. +Returns the previous state of **`_crtDbgFlag`**. ## Remarks -The **_CrtSetDbgFlag** function allows the application to control how the debug heap manager tracks memory allocations by modifying the bit fields of the **_crtDbgFlag** flag. By setting the bits (turning on), the application can instruct the debug heap manager to perform special debugging operations, including checking for memory leaks when the application exits and reporting if any are found, simulating low-memory conditions by specifying that freed memory blocks should remain in the heap's linked list, and verifying the integrity of the heap by inspecting each memory block at every allocation request. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetDbgFlag** are removed during preprocessing. +The **`_CrtSetDbgFlag`** function allows the application to control how the debug heap manager tracks memory allocations by modifying the bit fields of the **`_crtDbgFlag`** flag. By setting the bit fields, the application can instruct the debug heap manager to perform special debugging operations. There are several possible operations: -The following table lists the bit fields for **_crtDbgFlag** and describes their behavior. Because setting the bits results in increased diagnostic output and reduced program execution speed, these bits are not set (turned off) by default. For more information about these bit fields, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). +- Checking for memory leaks when the application exits and reporting if any are found, +- Simulating low-memory conditions by specifying that freed memory blocks should remain in the heap's linked list, +- Verifying the integrity of the heap by inspecting each memory block at every allocation request. -|Bit field|Default|Description| -|---------------|-------------|-----------------| -|**_CRTDBG_ALLOC_MEM_DF**|ON|ON: Enable debug heap allocations and use of memory block type identifiers, such as **_CLIENT_BLOCK**. OFF: Add new allocations to heap's linked list, but set block type to **_IGNORE_BLOCK**.

Can also be combined with any of the heap-frequency check macros.| -|**_CRTDBG_CHECK_ALWAYS_DF**|OFF|ON: Call [_CrtCheckMemory](crtcheckmemory.md) at every allocation and deallocation request. OFF: **_CrtCheckMemory** must be called explicitly.

Heap-frequency check macros have no effect when this flag is set.| -|**_CRTDBG_CHECK_CRT_DF**|OFF|ON: Include **_CRT_BLOCK** types in leak detection and memory state difference operations. OFF: Memory used internally by the run-time library is ignored by these operations.

Can also be combined with any of the heap-frequency check macros.| -|**_CRTDBG_DELAY_FREE_MEM_DF**|OFF|ON: Keep freed memory blocks in the heap's linked list, assign them the **_FREE_BLOCK** type, and fill them with the byte value 0xDD. OFF: Do not keep freed blocks in the heap's linked list.

Can also be combined with any of the heap-frequency check macros.| -|**_CRTDBG_LEAK_CHECK_DF**|OFF|ON: Perform automatic leak checking at program exit through a call to [_CrtDumpMemoryLeaks](crtdumpmemoryleaks.md) and generate an error report if the application failed to free all the memory it allocated. OFF: Do not automatically perform leak checking at program exit.

Can also be combined with any of the heap-frequency check macros.| +When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetDbgFlag`** are removed during preprocessing. + +The following table lists the bit fields for **`_crtDbgFlag`** and describes their behavior. Because setting the bits results in increased diagnostic output and reduced program execution speed, these bits aren't set (turned off) by default. For more information about these bit fields, see [Heap state reporting functions](../crt-debug-heap-details.md#heap-state-reporting-functions). + +| Bit field | Default | Description | +|---|---|---| +| `_CRTDBG_ALLOC_MEM_DF` | ON | ON: Enable debug heap allocations and use of memory block type identifiers, such as `_CLIENT_BLOCK`. OFF: Add new allocations to heap's linked list, but set block type to `_IGNORE_BLOCK`.

Can also be combined with any of the heap-frequency check macros. | +| `_CRTDBG_CHECK_ALWAYS_DF` | OFF | ON: Call [`_CrtCheckMemory`](crtcheckmemory.md) at every allocation and deallocation request. OFF: **`_CrtCheckMemory`** must be called explicitly.

Heap-frequency check macros have no effect when this flag is set. | +| `_CRTDBG_CHECK_CRT_DF` | OFF | ON: Include `_CRT_BLOCK` types in leak detection and memory state difference operations. OFF: Memory used internally by the run-time library is ignored by these operations.

Can also be combined with any of the heap-frequency check macros. | +| `_CRTDBG_DELAY_FREE_MEM_DF` | OFF | ON: Keep freed memory blocks in the heap's linked list, assign them the `_FREE_BLOCK` type, and fill them with the byte value 0xDD. OFF: Don't keep freed blocks in the heap's linked list.

Can also be combined with any of the heap-frequency check macros. | +| `_CRTDBG_LEAK_CHECK_DF` | OFF | ON: Perform automatic leak checking at program exit through a call to [`_CrtDumpMemoryLeaks`](crtdumpmemoryleaks.md) and generate an error report if the application failed to free all the memory it allocated. OFF: Don't automatically perform leak checking at program exit.

Can also be combined with any of the heap-frequency check macros. | **Heap-Check Frequency Macros** -You can specify how often the C run-time library performs validation of the debug heap (**_CrtCheckMemory**) based on the number of calls to **malloc**, **realloc**, **free**, and **_msize**. +You can specify how often the C run-time library performs validation of the debug heap (**`_CrtCheckMemory`**) based on the number of calls to **`malloc`**, **`realloc`**, **`free`**, and **`_msize`**. -**_CrtSetDbgFlag** then inspects the upper 16 bits of the *newFlag* parameter for a value. The value specified is the number of **malloc**, **realloc**, **free**, and **_msize** calls between **_CrtCheckMemory** calls. Four predefined macros are provided for this purpose. +**`_CrtSetDbgFlag`** then inspects the upper 16 bits of the *`newFlag`* parameter for a value. The value specified is the number of **`malloc`**, **`realloc`**, **`free`**, and **`_msize`** calls between **`_CrtCheckMemory`** calls. Four predefined macros are provided for this purpose. -|Macro|Number of malloc, realloc, free, and _msize calls between calls to _CrtCheckMemory| -|-----------|------------------------------------------------------------------------------------------| -|_CRTDBG_CHECK_EVERY_16_DF|16| -|_CRTDBG_CHECK_EVERY_128_DF|128| -|_CRTDBG_CHECK_EVERY_1024_DF|1024| -|_CRTDBG_CHECK_DEFAULT_DF|0 (by default, no heap checks)| +| Macro | Number of `malloc`, `realloc`, `free`, and `_msize` calls between calls to `_CrtCheckMemory` | +|---|---| +| `_CRTDBG_CHECK_EVERY_16_DF` | 16 | +| `_CRTDBG_CHECK_EVERY_128_DF` | 128 | +| `_CRTDBG_CHECK_EVERY_1024_DF` | 1024 | +| `_CRTDBG_CHECK_DEFAULT_DF` | 0 (by default, no heap checks) | -By default, **_CrtCheckMemory** is called once every 1,024 times you call **malloc**, **realloc**, **free**, and **_msize**. +By default, **`_CrtCheckMemory`** isn't called during memory operations. You can change that by sending the flags shown above to [`_CrtSetDbgFlag()`](crtsetdbgflag.md). -For example, you could specify a heap check every 16 **malloc**, **realloc**, **free**, and **_msize** operations with the following code: +For example, you can specify a heap check every 16 **`malloc`**, **`realloc`**, **`free`**, and **`_msize`** operations with the following code: ```C #include @@ -79,21 +84,21 @@ int main( ) } ``` -The upper 16 bits of the *newFlag* parameter are ignored when _CRTDBG_CHECK_ALWAYS_DF is specified. In this case, **_CrtCheckMemory** is called each time you call **malloc**, **realloc**, **free**, and **_msize**. +The upper 16 bits of the *`newFlag`* parameter are ignored when `_CRTDBG_CHECK_ALWAYS_DF` is specified. In this case, **`_CrtCheckMemory`** is called each time you call **`malloc`**, **`realloc`**, **`free`**, and **`_msize`**. -*newFlag* is the new state to apply to the **_crtDbgFlag** and is a combination of the values for each of the bit fields. +*`newFlag`* is the new state to apply to the **`_crtDbgFlag`** and is a combination of the values for each of the bit fields. ### To change one or more of these bit fields and create a new state for the flag -1. Call **_CrtSetDbgFlag** with *newFlag* equal to **_CRTDBG_REPORT_FLAG** to obtain the current **_crtDbgFlag** state and store the returned value in a temporary variable. +1. Call **`_CrtSetDbgFlag`** with *`newFlag`* equal to `_CRTDBG_REPORT_FLAG` to obtain the current **`_crtDbgFlag`** state and store the returned value in a temporary variable. -1. Turn on any bits by a bitwise **OR** of the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants). +1. Turn on any bits by a bitwise "or" (`|`) of the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants). -1. Turn off the other bits by **AND**-ing the variable with a bitwise **NOT** of the appropriate bitmasks. +1. Turn off the other bits with a bitwise "and" (`&`) of the variable with a bitwise "not" (`~`) of the appropriate bitmasks. -1. Call **_CrtSetDbgFlag** with *newFlag* equal to the value stored in the temporary variable to set the new state for **_crtDbgFlag**. +1. Call **`_CrtSetDbgFlag`** with *`newFlag`* equal to the value stored in the temporary variable to set the new state for **`_crtDbgFlag`**. -The following code demonstrates how to simulate low-memory conditions by keeping freed memory blocks in the heap's linked list and prevent **_CrtCheckMemory** from being called at every allocation request: +The following code demonstrates how to simulate low-memory conditions by keeping freed memory blocks in the heap's linked list and prevent **`_CrtCheckMemory`** from being called at every allocation request: ```C // Get the current state of the flag @@ -112,23 +117,23 @@ tmpFlag &= ~_CRTDBG_CHECK_ALWAYS_DF; _CrtSetDbgFlag( tmpFlag ); ``` -For an overview of memory management and the debug heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For an overview of memory management and the debug heap, see [CRT debug heap details](../crt-debug-heap-details.md). -To disable a flag with the **_CrtSetDbgFlag** function, you should **AND** the variable with the bitwise **NOT** of the bitmask. +To disable a flag with the **`_CrtSetDbgFlag`** function, use a bitwise "and" (`&`) of the variable with the bitwise "not" (`~`) of the bitmask. -If *newFlag* is not a valid value, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns the previous state of **_crtDbgFlag**. +If *`newFlag`* isn't a valid value, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns the previous state of **`_crtDbgFlag`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetDbgFlag**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetDbgFlag`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -196,6 +201,6 @@ int main( ) ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_crtDbgFlag](../../c-runtime-library/crtdbgflag.md)
-[_CrtCheckMemory](crtcheckmemory.md)
+[Debug routines](../debug-routines.md)\ +[`_crtDbgFlag`](../crtdbgflag.md)\ +[`_CrtCheckMemory`](crtcheckmemory.md) diff --git a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md index 718224aa85..b7ce8b7bbb 100644 --- a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md +++ b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md @@ -1,16 +1,15 @@ --- title: "_CrtSetDebugFillThreshold" description: "Use the _CrtSetDebugFillThreshold function to set the maximum amount of buffer to fill in secure CRT functions." -ms.date: "10/31/2019" +ms.date: 04/10/2025 api_name: ["_CrtSetDebugFillThreshold"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CrtSetDebugFillThreshold", "CrtSetDebugFillThreshold"] helpviewer_keywords: ["debug, buffer-filling behavior", "CrtSetDebugFillThreshold function", "_CrtSetDebugFillThreshold function", "buffer-filling behavior", "0xFE"] -ms.assetid: 6cb360e8-56ae-4248-b17f-e28aee3e0ed7 --- -# _CrtSetDebugFillThreshold +# `_CrtSetDebugFillThreshold` Retrieves or modifies the threshold controlling buffer-filling behavior in debug functions. @@ -22,7 +21,7 @@ size_t _CrtSetDebugFillThreshold( size_t newThreshold ); ### Parameters -*newThreshold*
+*`newThreshold`*\ New threshold size in bytes. ## Return value @@ -31,71 +30,49 @@ The previous threshold value. ## Remarks -The debug versions of some security-enhanced CRT functions fill the buffer passed to them with a special character (0xFE). This fill character helps to find cases where the incorrect size was passed to the function. Unfortunately, it also reduces performance. To improve performance, use **_CrtSetDebugFillThreshold** to disable buffer-filling for buffers larger than the *newThreshold* threshold. A *newThreshold* value of 0 disables it for all buffers. - -The default threshold is **SIZE_T_MAX**. - -Here is a list of the affected functions. - -- [asctime_s, _wasctime_s](asctime-s-wasctime-s.md) - -- [_cgets_s, _cgetws_s](cgets-s-cgetws-s.md) - -- [ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md) - -- [_ecvt_s](ecvt-s.md) - -- [_fcvt_s](fcvt-s.md) - -- [_gcvt_s](gcvt-s.md) - -- [_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s, _itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s](itoa-s-itow-s.md) - -- [_makepath_s, _wmakepath_s](makepath-s-wmakepath-s.md) - -- [_mbsnbcat_s, _mbsnbcat_s_l](mbsnbcat-s-mbsnbcat-s-l.md) - -- [_mbsnbcpy_s, _mbsnbcpy_s_l](mbsnbcpy-s-mbsnbcpy-s-l.md) - -- [_mbsnbset_s, _mbsnbset_s_l](mbsnbset-s-mbsnbset-s-l.md) - -- [_mktemp_s, _wmktemp_s](makepath-s-wmakepath-s.md) - -- [_splitpath_s, _wsplitpath_s](splitpath-s-wsplitpath-s.md) - -- [strcat_s, wcscat_s, _mbscat_s](strcat-s-wcscat-s-mbscat-s.md) - -- [strcpy_s, wcscpy_s, _mbscpy_s](strcpy-s-wcscpy-s-mbscpy-s.md) - -- [_strdate_s, _wstrdate_s](strdate-s-wstrdate-s.md) - -- [strerror_s, _strerror_s, _wcserror_s, \__wcserror_s](strerror-s-strerror-s-wcserror-s-wcserror-s.md) - -- [_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) - -- [strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) - -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) - -- [_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) - -- [_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) - -- [_strtime_s, _wstrtime_s](strtime-s-wstrtime-s.md) - -- [_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) - +The debug versions of some security-enhanced CRT functions fill the buffer passed to them with a special character (0xFE). This fill character helps to find cases where the incorrect size was passed to the function. Unfortunately, it also reduces performance. To improve performance, use **`_CrtSetDebugFillThreshold`** to disable buffer-filling for buffers larger than the *`newThreshold`* threshold. A *`newThreshold`* value of 0 disables it for all buffers. + +The default threshold is `SIZE_T_MAX`. + +Here's a list of the affected functions: + +- [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md) +- [`_cgets_s`, `_cgetws_s`](cgets-s-cgetws-s.md) +- [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md) +- [`_ecvt_s`](ecvt-s.md) +- [`_fcvt_s`](fcvt-s.md) +- [`_gcvt_s`](gcvt-s.md) +- [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](itoa-s-itow-s.md) +- [`_makepath_s`, `_wmakepath_s`](makepath-s-wmakepath-s.md) +- [`_mbsnbcat_s`, `_mbsnbcat_s_l`](mbsnbcat-s-mbsnbcat-s-l.md) +- [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](mbsnbcpy-s-mbsnbcpy-s-l.md) +- [`_mbsnbset_s`, `_mbsnbset_s_l`](mbsnbset-s-mbsnbset-s-l.md) +- [`_mktemp_s`, `_wmktemp_s`](makepath-s-wmakepath-s.md) +- [`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md) +- [`strcat_s`, `wcscat_s`, `_mbscat_s`](strcat-s-wcscat-s-mbscat-s.md) +- [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) +- [`_strdate_s`, `_wstrdate_s`](strdate-s-wstrdate-s.md) +- [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](strerror-s-strerror-s-wcserror-s-wcserror-s.md) +- [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) +- [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) +- [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) +- [`_strtime_s`, `_wstrtime_s`](strtime-s-wstrtime-s.md) +- [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) +- [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, _vsnwpr`intf_s_l](vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) + ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetDebugFillThreshold**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetDebugFillThreshold`** | `` | -This function is Microsoft-specific. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +This function is Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of the [C run-time libraries](../crt-library-features.md) only. ## Example @@ -163,4 +140,4 @@ With buffer-filling off: ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtsetdumpclient.md b/docs/c-runtime-library/reference/crtsetdumpclient.md index 77843d943f..8d2590b289 100644 --- a/docs/c-runtime-library/reference/crtsetdumpclient.md +++ b/docs/c-runtime-library/reference/crtsetdumpclient.md @@ -10,9 +10,9 @@ f1_keywords: ["_CrtSetDumpClient", "CrtSetDumpClient"] helpviewer_keywords: ["_CrtSetDumpClient function", "CrtSetDumpClient function"] ms.assetid: f3dd06d0-c331-4a12-b68d-25378d112033 --- -# _CrtSetDumpClient +# `_CrtSetDumpClient` -Installs an application-defined function to dump **_CLIENT_BLOCK** type memory blocks (debug version only). +Installs an application-defined function to dump `_CLIENT_BLOCK` type memory blocks (debug version only). ## Syntax @@ -22,45 +22,45 @@ _CRT_DUMP_CLIENT _CrtSetDumpClient( _CRT_DUMP_CLIENT dumpClient ); ### Parameters -*dumpClient*
-New client-defined memory dump function to hook into the C run-time debug memory dump process. +*`dumpClient`*\ +New client-defined memory dump function to hook. -## Return Value +## Return value Returns the previously defined client block dump function. ## Remarks -The **_CrtSetDumpClient** function allows the application to hook its own function to dump objects stored in **_CLIENT_BLOCK** memory blocks into the C run-time debug memory dump process. As a result, every time a debug dump function such as [_CrtMemDumpAllObjectsSince](crtmemdumpallobjectssince.md) or [_CrtDumpMemoryLeaks](crtdumpmemoryleaks.md) dumps a **_CLIENT_BLOCK** memory block, the application's dump function is called as well. **_CrtSetDumpClient** provides an application with an easy method for detecting memory leaks and validating or reporting the contents of data stored in **_CLIENT_BLOCK** blocks. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetDumpClient** are removed during preprocessing. +The **`_CrtSetDumpClient`** function allows the application to hook its own function to dump objects stored in `_CLIENT_BLOCK` memory blocks. As a result, every time a debug dump function such as [`_CrtMemDumpAllObjectsSince`](crtmemdumpallobjectssince.md) or [`_CrtDumpMemoryLeaks`](crtdumpmemoryleaks.md) dumps a `_CLIENT_BLOCK` memory block, the application's dump function is called as well. **`_CrtSetDumpClient`** provides an application with an easy method for detecting memory leaks and validating or reporting the contents of data stored in `_CLIENT_BLOCK` blocks. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetDumpClient`** are removed during preprocessing. -The **_CrtSetDumpClient** function installs the new application-defined dump function specified in *dumpClient* and returns the previously defined dump function. An example of a client block dump function is as follows: +The **`_CrtSetDumpClient`** function installs the new application-defined dump function specified in *`dumpClient`* and returns the previously defined dump function. An example of a client block dump function is as follows: ```C void DumpClientFunction( void *userPortion, size_t blockSize ); ``` -The *userPortion* argument is a pointer to the beginning of the user data portion of the memory block and *blockSize* specifies the size of the allocated memory block in bytes. The client block dump function must return **`void`**. The pointer to the client dump function that is passed to **_CrtSetDumpClient** is of type **_CRT_DUMP_CLIENT**, as defined in Crtdbg.h: +The *`userPortion`* argument is a pointer to the beginning of the user data portion of the memory block and *`blockSize`* specifies the size of the allocated memory block in bytes. The client block dump function must return **`void`**. The pointer to the client dump function that is passed to **`_CrtSetDumpClient`** is of type `_CRT_DUMP_CLIENT`, as defined in Crtdbg.h: ```C typedef void (__cdecl *_CRT_DUMP_CLIENT)( void *, size_t ); ``` -For more information about functions that operate on **_CLIENT_BLOCK** type memory blocks, see [Client Block Hook Functions](/visualstudio/debugger/client-block-hook-functions). The [_CrtReportBlockType](crtreportblocktype.md) function can be used to return information about block types and subtypes. +For more information about functions that operate on `_CLIENT_BLOCK` type memory blocks, see [Client block hook functions](../crt-debugging-techniques.md#client-block-hook-functions). The [`_CrtReportBlockType`](crtreportblocktype.md) function can be used to return information about block types and subtypes. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetDumpClient**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetDumpClient`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtReportBlockType](crtreportblocktype.md)
-[_CrtGetDumpClient](crtgetdumpclient.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtReportBlockType`](crtreportblocktype.md)\ +[`_CrtGetDumpClient`](crtgetdumpclient.md) diff --git a/docs/c-runtime-library/reference/crtsetreportfile.md b/docs/c-runtime-library/reference/crtsetreportfile.md index c5f0b82e2b..be7c2e89e1 100644 --- a/docs/c-runtime-library/reference/crtsetreportfile.md +++ b/docs/c-runtime-library/reference/crtsetreportfile.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CrtSetReportFile" title: "_CrtSetReportFile" +description: "Learn more about: _CrtSetReportFile" ms.date: "11/04/2016" api_name: ["_CrtSetReportFile"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtSetReportFile", "_CrtSetReportFile"] helpviewer_keywords: ["CrtSetReportFile function", "_CrtSetReportFile function"] -ms.assetid: 3126537e-511b-44af-9c1c-0605265eabc4 --- -# _CrtSetReportFile +# `_CrtSetReportFile` -After you use [_CrtSetReportMode](crtsetreportmode.md) to specify **_CRTDBG_MODE_FILE**, you can specify the file handle to receive the message text. **_CrtSetReportFile** is also used by [_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md) to specify the destination of text (debug version only). +After you use [`_CrtSetReportMode`](crtsetreportmode.md) to specify `_CRTDBG_MODE_FILE`, you can specify the file handle to receive the message text. **`_CrtSetReportFile`** is also used by [`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) to specify the destination of text (debug version only). ## Syntax @@ -25,21 +24,21 @@ _HFILE _CrtSetReportFile( ### Parameters -*reportType*
-Report type: **_CRT_WARN**, **_CRT_ERROR**, and **_CRT_ASSERT**. +*`reportType`*\ +Report type: `_CRT_WARN`, `_CRT_ERROR`, and `_CRT_ASSERT`. -*reportFile*
-New report file for *reportType*. +*`reportFile`*\ +New report file for *`reportType`*. -## Return Value +## Return value -On successful completion, **_CrtSetReportFile** returns the previous report file defined for the report type specified in *reportType*. If an invalid value is passed in for *reportType*, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **_CRTDBG_HFILE_ERROR**. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +On successful completion, **`_CrtSetReportFile`** returns the previous report file defined for the report type specified in *`reportType`*. If an invalid value is passed in for *`reportType`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and the function returns `_CRTDBG_HFILE_ERROR`. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -**_CrtSetReportFile** is used with the [_CrtSetReportMode](crtsetreportmode.md) function to define the destination or destinations for a specific report type generated by **_CrtDbgReport**. When **_CrtSetReportMode** has been called to assign the **_CRTDBG_MODE_FILE** reporting mode for a specific report type, **_CrtSetReportFile** should then be called to define the specific file or stream to use as the destination. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetReportFile** are removed during preprocessing. +**`_CrtSetReportFile`** is used with the [`_CrtSetReportMode`](crtsetreportmode.md) function to define the destination or destinations for a specific report type generated by `_CrtDbgReport`. When you call `_CrtSetReportMode` to assign the `_CRTDBG_MODE_FILE` reporting mode for a specific report type, also call **`_CrtSetReportFile`** to specify the destination file or stream. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetReportFile`** are removed during preprocessing. -The following list shows the available choices for *reportFile* and the resulting behavior of **_CrtDbgReport**. These options are defined as bit flags in Crtdbg.h. +The following list shows the available choices for *`reportFile`* and the resulting behavior of `_CrtDbgReport`. These options are defined as bit flags in Crtdbg.h. - **file handle** @@ -57,9 +56,9 @@ The following list shows the available choices for *reportFile* and the resultin CloseHandle(hLogFile); ``` -- **_CRTDBG_FILE_STDERR** +- `_CRTDBG_FILE_STDERR` - Writes message to **stderr**, which can be redirected as follows: + Writes message to `stderr`, which can be redirected as follows: ```C freopen( "c:\\log2.txt", "w", stderr); @@ -69,26 +68,26 @@ The following list shows the available choices for *reportFile* and the resultin _RPT0(_CRT_ERROR,"1st message\n"); ``` -- **_CRTDBG_FILE_STDOUT** +- `_CRTDBG_FILE_STDOUT` - Writes message to **stdout**, which you can redirect. + Writes message to `stdout`, which you can redirect. -- **_CRTDBG_REPORT_FILE** +- `_CRTDBG_REPORT_FILE` Returns the current report mode. -The report file used by each report type can be separately controlled. For example, it is possible to specify that a *reportType* of **_CRT_ERROR** be reported to **stderr**, while a *reportType* of **_CRT_ASSERT** be reported to a user-defined file handle or stream. +You can control the report file used by each report type separately. For example, it's possible to specify that a *`reportType`* of `_CRT_ERROR` reports through `stderr`, while a *`reportType`* of `_CRT_ASSERT` reports through a user-defined file handle or stream. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_CrtSetReportFile**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_CrtSetReportFile`** | \ | \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** Debug versions of [CRT Library Features](../../c-runtime-library/crt-library-features.md) only. +**Libraries:** Debug versions of [CRT library features](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtsetreporthook.md b/docs/c-runtime-library/reference/crtsetreporthook.md index 27f9ef49c0..1938344e34 100644 --- a/docs/c-runtime-library/reference/crtsetreporthook.md +++ b/docs/c-runtime-library/reference/crtsetreporthook.md @@ -10,7 +10,7 @@ f1_keywords: ["_CrtSetReportHook", "CrtSetReportHook"] helpviewer_keywords: ["CrtSetReportHook function", "_CrtSetReportHook function"] ms.assetid: 1ae7c64f-8c84-4797-9574-b59f00f7a509 --- -# _CrtSetReportHook +# `_CrtSetReportHook` Installs a client-defined reporting function by hooking it into the C run-time debug reporting process (debug version only). @@ -24,47 +24,47 @@ _CRT_REPORT_HOOK _CrtSetReportHook( ### Parameters -*reportHook*
+*`reportHook`*\ New client-defined reporting function to hook into the C run-time debug reporting process. -## Return Value +## Return value Returns the previous client-defined reporting function. ## Remarks -**_CrtSetReportHook** allows an application to use its own reporting function into the C run-time debug library reporting process. As a result, whenever [_CrtDbgReport](crtdbgreport-crtdbgreportw.md) is called to generate a debug report, the application's reporting function is called first. This functionality enables an application to perform operations such as filtering debug reports so it can focus on specific allocation types or send a report to destinations not available by using **_CrtDbgReport**. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, calls to **_CrtSetReportHook** are removed during preprocessing. +**`_CrtSetReportHook`** allows an application to use its own reporting function into the C run-time debug library reporting process. As a result, whenever [`_CrtDbgReport`](crtdbgreport-crtdbgreportw.md) is called to generate a debug report, the application's reporting function is called first. This functionality enables an application to perform operations such as filtering debug reports so it can focus on specific allocation types or send a report to destinations not available by using `_CrtDbgReport`. When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetReportHook`** are removed during preprocessing. -For a more robust version of **_CrtSetReportHook**, see [_CrtSetReportHook2](crtsetreporthook2-crtsetreporthookw2.md). +For a more robust version of **`_CrtSetReportHook`**, see [`_CrtSetReportHook2`](crtsetreporthook2-crtsetreporthookw2.md). -The **_CrtSetReportHook** function installs the new client-defined reporting function specified in *reportHook* and returns the previous client-defined hook. The following example demonstrates how a client-defined report hook should be prototyped: +The **`_CrtSetReportHook`** function installs the new client-defined reporting function specified in *`reportHook`* and returns the previous client-defined hook. The following example demonstrates how a client-defined report hook should be prototyped: ```C int YourReportHook( int reportType, char *message, int *returnValue ); ``` -where *reportType* is the debug report type (**_CRT_WARN**, **_CRT_ERROR**, or **_CRT_ASSERT**), *message* is the fully assembled debug user message to be contained in the report, and **returnValue** is the value specified by the client-defined reporting function that should be returned by **_CrtDbgReport**. For a complete description of the available report types, see the [_CrtSetReportMode](crtsetreportmode.md) function. +where *`reportType`* is the debug report type (`_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`), *`message`* is the fully assembled debug user message to be contained in the report, and *`returnValue`* is the value specified by the client-defined reporting function that should be returned by `_CrtDbgReport`. For a complete description of the available report types, see the [`_CrtSetReportMode`](crtsetreportmode.md) function. -If the client-defined reporting function completely handles the debug message such that no further reporting is required, then the function should return **TRUE**. When the function returns **FALSE**, **_CrtDbgReport** is called to generate the debug report using the current settings for the report type, mode, and file. In addition, by specifying the **_CrtDbgReport** return value in **returnValue**, the application can also control whether a debug break occurs. For a complete description of how the debug report is configured and generated, see **_CrtSetReportMode**, [_CrtSetReportFile](crtsetreportfile.md), and **_CrtDbgReport**. +If the client-defined reporting function completely handles the debug message such that no further reporting is required, then the function should return `TRUE`. When the function returns `FALSE`, `_CrtDbgReport` is called to generate the debug report using the current settings for the report type, mode, and file. In addition, by specifying the `_CrtDbgReport` return value in *`returnValue`*, the application can also control whether a debug break occurs. For a complete description of how the debug report is configured and generated, see `_CrtSetReportMode`, [`_CrtSetReportFile`](crtsetreportfile.md), and `_CrtDbgReport`. -For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug Hook Function Writing](/visualstudio/debugger/debug-hook-function-writing). +For more information about using other hook-capable run-time functions and writing your own client-defined hook functions, see [Debug hook function writing](../crt-debugging-techniques.md#debug-hook-function-writing). > [!NOTE] > If your application is compiled with **/clr** and the reporting function is called after the application has exited main, the CLR will throw an exception if the reporting function calls any CRT functions. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_CrtSetReportHook**|\| +| Routine | Required header | +|---|---| +| **`_CrtSetReportHook`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_CrtGetReportHook](crtgetreporthook.md)
+[Debug routines](../debug-routines.md)\ +[`_CrtGetReportHook`](crtgetreporthook.md) diff --git a/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md b/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md index 2ce8a96e27..bbd300bda3 100644 --- a/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md +++ b/docs/c-runtime-library/reference/crtsetreporthook2-crtsetreporthookw2.md @@ -10,7 +10,7 @@ f1_keywords: ["CrtSetReportHookW2", "CrtSetReportHook2", "_CrtSetReportHookW2", helpviewer_keywords: ["CrtSetReportHook2 function", "_CrtSetReportHook2 function", "_CrtSetReportHookW2 function", "CrtSetReportHookW2 function"] ms.assetid: 12e5f68d-c8a7-4b1a-9a75-72ba4a8592d0 --- -# _CrtSetReportHook2, _CrtSetReportHookW2 +# `_CrtSetReportHook2`, `_CrtSetReportHookW2` Installs or uninstalls a client-defined reporting function by hooking it into the C run-time debug reporting process (debug version only). @@ -29,23 +29,23 @@ int _CrtSetReportHookW2( ### Parameters -*mode*
-The action to take: **_CRT_RPTHOOK_INSTALL** or **_CRT_RPTHOOK_REMOVE**. +*`mode`*\ +The action to take: `_CRT_RPTHOOK_INSTALL` or `_CRT_RPTHOOK_REMOVE`. -*pfnNewHook*
+*`pfnNewHook`*\ Report hook to install or remove in the narrow-character or wide-character version of this function. -## Return Value +## Return value --1 if an error was encountered, with **EINVAL** or **ENOMEM** set; otherwise returns the reference count of *pfnNewHook* after the call. +-1 if an error was encountered, with `EINVAL` or `ENOMEM` set; otherwise returns the reference count of *`pfnNewHook`* after the call. ## Remarks -**_CrtSetReportHook2** and **_CrtSetReportHookW2** let you hook or unhook a function, whereas [_CrtSetReportHook](crtsetreporthook.md) only lets you hook a function. +**`_CrtSetReportHook2`** and **`_CrtSetReportHookW2`** let you hook or unhook a function, whereas [`_CrtSetReportHook`](crtsetreporthook.md) only lets you hook a function. -**_CrtSetReportHook2** or **_CrtSetReportHookW2** should be used instead of **_CrtSetReportHook** when the hook call is made in a DLL and when multiple DLLs might be loaded and setting their own hook functions. In such a situation, DLLs can be unloaded in a different order than they were loaded and the hook function can be left pointing at an unloaded DLL. Any debug output crashes the process if the hook functions were added with **_CrtSetReportHook**. +**`_CrtSetReportHook2`** or **`_CrtSetReportHookW2`** should be used instead of `_CrtSetReportHook` when the hook call is made in a DLL and when multiple DLLs might be loaded and setting their own hook functions. In such a situation, DLLs can be unloaded in a different order than they were loaded and the hook function can be left pointing at an unloaded DLL. Any debug output crashes the process if the hook functions were added with `_CrtSetReportHook`. -Any hook functions added with **_CrtSetReportHook** are called if there are no hook functions added with **_CrtSetReportHook2** or **_CrtSetReportHookW2** or if all hook functions added with **_CrtSetReportHook2** and **_CrtSetReportHookW2** return **FALSE**. +Any hook functions added with `_CrtSetReportHook` are called if there are no hook functions added with **`_CrtSetReportHook2`** or **`_CrtSetReportHookW2`** or if all hook functions added with **`_CrtSetReportHook2`** and **`_CrtSetReportHookW2`** return `FALSE`. The wide-character version of this function is available. The report hook functions take a string whose type (wide or narrow characters) must match the version of this function used. Use the following function prototype for the report hooks used with the wide-character version of this function: @@ -59,23 +59,23 @@ Use the following prototype for the narrow-character report hooks: int YourReportHook( int reportType, char *message, int *returnValue ); ``` -These functions validate their parameters. If *mode* or **pfnNewNook** is invalid, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. +These functions validate their parameters. If *`mode`* or *`pfnNewHook`* is invalid, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. > [!NOTE] > If your application is compiled with **/clr** and the reporting function is called after the application has exited main, the CLR will throw an exception if the reporting function calls any CRT functions. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_CrtSetReportHook2**|\|\| -|**_CrtSetReportHookW2**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_CrtSetReportHook2`** | \ | \ | +| **`_CrtSetReportHookW2`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -227,4 +227,4 @@ _CrtSetReportHook2(_CRT_RPTHOOK_REMOVE, TestHook1) returned 0 ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/crtsetreportmode.md b/docs/c-runtime-library/reference/crtsetreportmode.md index 625303cfe1..1049ca67b0 100644 --- a/docs/c-runtime-library/reference/crtsetreportmode.md +++ b/docs/c-runtime-library/reference/crtsetreportmode.md @@ -11,7 +11,7 @@ helpviewer_keywords: ["_CrtSetReportMode function", "CrtSetReportMode function"] --- # `_CrtSetReportMode` -Specifies the destination or destinations for a specific report type generated by **_CrtDbgReport** and any macros that call [`_CrtDbgReport, _CrtDbgReportW`](crtdbgreport-crtdbgreportw.md), such as [`_ASSERT, _ASSERTE, _ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md), [`_ASSERT, _ASSERTE, _ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md), [`_RPT, _RPTF, _RPTW, _RPTFW` Macros](rpt-rptf-rptw-rptfw-macros.md), and [`_RPT, _RPTF, _RPTW, _RPTFW` Macros](rpt-rptf-rptw-rptfw-macros.md) (debug version only). +Specifies the destination or destinations for a specific report type generated by `_CrtDbgReport` and any macros that call [`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md), such as [`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` macros](assert-asserte-assert-expr-macros.md) and [`_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` macros](rpt-rptf-rptw-rptfw-macros.md) (debug version only). ## Syntax @@ -25,65 +25,65 @@ int _CrtSetReportMode( ### Parameters *`reportType`*\ -Report type: **`_CRT_WARN`**, **`_CRT_ERROR`**, and **`_CRT_ASSERT`**. +Report type: `_CRT_WARN`, `_CRT_ERROR`, and `_CRT_ASSERT`. *`reportMode`*\ New report mode or modes for *`reportType`*. -## Return Value +## Return value -On successful completion, **`_CrtSetReportMode`** returns the previous report mode or modes for the report type specified in *`reportType`*. If an invalid value is passed in as *`reportType`* or an invalid mode is specified for *`reportMode`*, **`_CrtSetReportMode`** invokes the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns -1. For more information, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +On successful completion, **`_CrtSetReportMode`** returns the previous report mode or modes for the report type specified in *`reportType`*. If an invalid value is passed in as *`reportType`* or an invalid mode is specified for *`reportMode`*, **`_CrtSetReportMode`** invokes the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns -1. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks **`_CrtSetReportMode`** specifies the output destination for **`_CrtDbgReport`**. Because the macros [`_ASSERT`](assert-asserte-assert-expr-macros.md), [`_ASSERTE`](assert-asserte-assert-expr-macros.md), [`_RPT`](rpt-rptf-rptw-rptfw-macros.md), and [`_RPTF`](rpt-rptf-rptw-rptfw-macros.md) call **`_CrtDbgReport`**, **`_CrtSetReportMode`** specifies the output destination of text specified with those macros. -When [`_DEBUG`](../../c-runtime-library/debug.md) is not defined, calls to **`_CrtSetReportMode`** are removed during preprocessing. +When [`_DEBUG`](../debug.md) isn't defined, calls to **`_CrtSetReportMode`** are removed during preprocessing. -If you do not call **`_CrtSetReportMode`** to define the output destination of messages, then the following defaults are in effect: +If you don't call **`_CrtSetReportMode`** to define the output destination of messages, then the following defaults are in effect: - Assertion failures and errors are directed to a debug message window. - Warnings from Windows applications are sent to the debugger's output window. -- Warnings from console applications are not displayed. +- Warnings from console applications aren't displayed. The following table lists the report types defined in `Crtdbg.h`. -|Report type|Description| -|-----------------|-----------------| -|**`_CRT_WARN`**|Warnings, messages, and information that does not need immediate attention.| -|**`_CRT_ERROR`**|Errors, unrecoverable problems, and issues that require immediate attention.| -|**`_CRT_ASSERT`**|Assertion failures (asserted expressions that evaluate to **`FALSE`**).| +| Report type | Description | +|---|---| +| `_CRT_WARN` | Warnings, messages, and information that doesn't need immediate attention. | +| `_CRT_ERROR` | Errors, unrecoverable problems, and issues that require immediate attention. | +| `_CRT_ASSERT` | Assertion failures (asserted expressions that evaluate to `FALSE`). | The **`_CrtSetReportMode`** function assigns the new report mode specified in *`reportMode`* to the report type specified in *`reportType`* and returns the previously defined report mode for *`reportType`*. The following table lists the available choices for *`reportMode`* and the resulting behavior of **`_CrtDbgReport`**. These options are defined as bit flags in Crtdbg.h. -|Report mode|_CrtDbgReport behavior| -|-----------------|-----------------------------| -|**`_CRTDBG_MODE_DEBUG`**|Writes the message to the debugger's output window.| -|**`_CRTDBG_MODE_FILE`**|Writes the message to a user-supplied file handle. [`_CrtSetReportFile`](crtsetreportfile.md) should be called to define the specific file or stream to use as the destination.| -|**`_CRTDBG_MODE_WNDW`**|Creates a message box to display the message along with the [`abort`](abort.md), **`Retry`**, and **Ignore** buttons.| -|**`_CRTDBG_REPORT_MODE`**|Returns *`reportMode`* for the specified *`reportType`*:

1 **`_CRTDBG_MODE_FILE`**

2 **`_CRTDBG_MODE_DEBUG`**

4 **`_CRTDBG_MODE_WNDW`**| +| Report mode | _CrtDbgReport behavior | +|---|---| +| `_CRTDBG_MODE_DEBUG` | Writes the message to the debugger's output window. | +| `_CRTDBG_MODE_FILE` | Writes the message to a user-supplied file handle. [`_CrtSetReportFile`](crtsetreportfile.md) should be called to define the specific file or stream to use as the destination. | +| `_CRTDBG_MODE_WNDW` | Creates a message box to display the message along with the **Abort**, **Retry**, and **Ignore** buttons. | +| `_CRTDBG_REPORT_MODE` | Returns *`reportMode`* for the specified *`reportType`*:

1 `_CRTDBG_MODE_FILE`

2 `_CRTDBG_MODE_DEBUG`

4 `_CRTDBG_MODE_WNDW` | -Each report type can be reported using one, two, or three modes or no mode at all. Therefore, it is possible to have more than one destination defined for a single report type. For example, the following code fragment causes assertion failures to be sent to both a debug message window and to **`stderr`**: +Each report type can be reported using one, two, or three modes or no mode at all. Therefore, it's possible to have more than one destination defined for a single report type. For example, the following code fragment causes assertion failures to be sent to both a debug message window and to **`stderr`**: ```C _CrtSetReportMode( _CRT_ASSERT, _CRTDBG_MODE_FILE | _CRTDBG_MODE_WNDW ); _CrtSetReportFile( _CRT_ASSERT, _CRTDBG_FILE_STDERR ); ``` -In addition, the reporting mode or modes for each report type can be separately controlled. For example, it is possible to specify that a *`reportType`* of **`_CRT_WARN`** be sent to an output debug string, while **`_CRT_ASSERT`** be displayed using a debug message window and sent to **`stderr`**, as previously illustrated. +In addition, you can control the reporting mode or modes for each report type separately. For example, it's possible to specify that a *`reportType`* of `_CRT_WARN` goes to an output debug string, while `_CRT_ASSERT` is displayed using a debug message window and is sent to **`stderr`**, as previously illustrated. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_CrtSetReportMode`**|``|``| +| Routine | Required header | Optional header | +|---|---|---| +| **`_CrtSetReportMode`** | `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** Debug versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md) only. +**Libraries:** Debug versions of the [C runtime libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md b/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md index 989fb1faea..a28d6c58c6 100644 --- a/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md +++ b/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md @@ -10,12 +10,12 @@ f1_keywords: ["_cwscanf", "cwscanf_l", "tcscanf_l", "_tcscanf_l", "_cscanf", "_c helpviewer_keywords: ["_cwscanf function", "data [C++], reading from the console", "cscanf_l function", "tcscanf function", "_cscanf_l function", "cwscanf function", "_tcscanf_l function", "_cscanf function", "_tcscanf function", "cwscanf_l function", "tcscanf_l function", "reading data [C++], from the console", "_cwscanf_l function"] ms.assetid: dbfe7547-b577-4567-a1cb-893fa640e669 --- -# _cscanf, _cscanf_l, _cwscanf, _cwscanf_l +# `_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l` -Reads formatted data from the console. More secure versions of these functions are available; see [_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md). +Reads formatted data from the console. More secure versions of these functions are available; see [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md). > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see Linker Error LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -45,42 +45,42 @@ int _cwscanf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -The number of fields that were successfully converted and assigned. The return value does not include fields that were read but not assigned. The return value is **EOF** for an attempt to read at end of file. This can occur when keyboard input is redirected at the operating-system command-line level. A return value of 0 means that no fields were assigned. +The number of fields that were successfully converted and assigned. The return value doesn't include fields that were read but not assigned. The return value is `EOF` for an attempt to read at end of file. An `EOF` can also be returned when keyboard input is redirected at the operating-system command-line level. A return value of zero means that no fields were assigned. ## Remarks -The **_cscanf** function reads data directly from the console into the locations given by *argument*. The [_getche](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *format*. The format controls the interpretation of the input fields and has the same form and function as the *format* parameter for the [scanf](scanf-scanf-l-wscanf-wscanf-l.md) function. While **_cscanf** normally echoes the input character, it does not do so if the last call was to **_ungetch**. +The **`_cscanf`** function reads data directly from the console into the locations given by *`argument`*. The [`_getche`](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The format controls the interpretation of the input fields and has the same form and function as the *`format`* parameter for the [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) function. While **`_cscanf`** normally echoes the input character, it doesn't do so if the last call was to `_ungetch`. -This function validates its parameters. If format is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **EOF**. +This function validates its parameters. If format is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `EOF`. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcscanf**|**_cscanf**|**_cscanf**|**_cwscanf**| -|**_tcscanf_l**|**_cscanf_l**|**_cscanf_l**|**_cwscanf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscanf` | **`_cscanf`** | **`_cscanf`** | **`_cwscanf`** | +| `_tcscanf_l` | **`_cscanf_l`** | **`_cscanf_l`** | **`_cwscanf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cscanf**, **_cscanf_l**|\| -|**_cwscanf**, **_cwscanf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_cscanf`**, **`_cscanf_l`** | \ | +| **`_cwscanf`**, **`_cwscanf_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -121,8 +121,8 @@ You entered 3 2 1 ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md b/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md index dd471dbac6..87dac808b6 100644 --- a/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md +++ b/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md @@ -10,9 +10,9 @@ f1_keywords: ["cscanf_s", "cscanf_s_l", "cwscanf_s", "_cwscanf_s", "_tcscanf_s", helpviewer_keywords: ["cscanf_s function", "_cwscanf_s_l function", "tcscanf_s function", "console [C++], reading from", "_cscanf_s function", "data [C++], reading from the console", "cwscanf_s function", "_tcscanf_s_l function", "_cscanf_s_l function", "cscanf_s_l function", "cwscanf_s_l function", "reading data [C++], from the console", "_cwscanf_s function", "_tcscanf_s function", "tcscanf_s_l function"] ms.assetid: 9ccab74d-916f-42a6-93d8-920525efdf4b --- -# _cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l +# `_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l` -Reads formatted data from the console. These more secure versions of [_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the console. These more secure versions of [`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -42,51 +42,51 @@ int _cwscanf_s_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -The number of fields that were successfully converted and assigned. The return value does not include fields that were read but not assigned. The return value is **EOF** for an attempt to read at end of file. This can occur when keyboard input is redirected at the operating-system command-line level. A return value of 0 means that no fields were assigned. +The number of fields that were successfully converted and assigned. The return value doesn't include fields that were read but not assigned. The return value is `EOF` for an attempt to read at end of file. An `EOF` can also be returned when keyboard input is redirected at the operating-system command-line level. A return value of zero means that no fields were assigned. -These functions validate their parameters. If *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and **errno** is set to **EINVAL**. +These functions validate their parameters. If *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF`, and `errno` is set to `EINVAL`. ## Remarks -The **_cscanf_s** function reads data directly from the console into the locations given by *argument*. The [_getche](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *format*. The format controls the interpretation of the input fields and has the same form and function as the *format* parameter for the [scanf_s](scanf-scanf-l-wscanf-wscanf-l.md) function. While **_cscanf_s** normally echoes the input character, it does not do so if the last call was to **_ungetch**. +The **`_cscanf_s`** function reads data directly from the console into the locations given by *`argument`*. The [`_getche`](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The format controls the interpretation of the input fields and has the same form and function as the *`format`* parameter for the [`scanf_s`](scanf-scanf-l-wscanf-wscanf-l.md) function. While **`_cscanf_s`** normally echoes the input character, it doesn't do so if the last call was to `_ungetch`. -Like other secure versions of functions in the **scanf** family, **_cscanf_s** and **_cswscanf_s** require size arguments for the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +Like other secure versions of functions in the `scanf` family, **`_cscanf_s`** and **`_cwscanf_s`** require size arguments for the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Width Specification](../scanf-width-specification.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcscanf_s**|**_cscanf_s**|**_cscanf_s**|**_cwscanf_s**| -|**_tcscanf_s_l**|**_cscanf_s_l**|**_cscanf_s_l**|**_cwscanf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscanf_s` | **`_cscanf_s`** | **`_cscanf_s`** | **`_cwscanf_s`** | +| `_tcscanf_s_l` | **`_cscanf_s_l`** | **`_cscanf_s_l`** | **`_cwscanf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cscanf_s**, **_cscanf_s_l**|\| -|**_cwscanf_s**, **_cwscanf_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_cscanf_s`**, **`_cscanf_s_l`** | \ | +| **`_cwscanf_s`**, **`_cwscanf_s_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -125,8 +125,8 @@ You entered 1 2 3 ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) diff --git a/docs/c-runtime-library/reference/cscanf.md b/docs/c-runtime-library/reference/cscanf.md index 8f4dfb73c4..ee1ad90cfe 100644 --- a/docs/c-runtime-library/reference/cscanf.md +++ b/docs/c-runtime-library/reference/cscanf.md @@ -10,11 +10,11 @@ f1_keywords: ["cscanf"] helpviewer_keywords: ["cscanf function"] ms.assetid: 51aa2da2-0d53-4272-b510-f3eabf049ea7 --- -# cscanf +# `cscanf` -The Microsoft-specific function name `cscanf` is a deprecated alias for the [_cscanf](cscanf-cscanf-l-cwscanf-cwscanf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cscanf` is a deprecated alias for the [`_cscanf`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_cscanf](cscanf-cscanf-l-cwscanf-cwscanf-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_cscanf`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/csin-csinf-csinl.md b/docs/c-runtime-library/reference/csin-csinf-csinl.md index 399c064829..b2b68bab63 100644 --- a/docs/c-runtime-library/reference/csin-csinf-csinl.md +++ b/docs/c-runtime-library/reference/csin-csinf-csinl.md @@ -10,7 +10,7 @@ f1_keywords: ["csin", "csinf", "csinl", "complex/csin", "complex/csinf", "comple helpviewer_keywords: ["csin function", "csinf function", "csinl function"] ms.assetid: 3ed475e8-9aae-42ba-a25c-7ae656a0fd4d --- -# csin, csinf, csinl +# `csin`, `csinf`, `csinl` Retrieves the sine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex csinl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The sine of *z*, in radians. +The sine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **csin** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csin** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csin`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csin`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csin**, **csinf**, **csinl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csin`**, **`csinf`**, **`csinl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md index b87356ab45..b1dea5a742 100644 --- a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md +++ b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md @@ -10,7 +10,7 @@ f1_keywords: ["csinh", "csinhf", "csinhl", "complex/csinh", "complex/csinhf", "c helpviewer_keywords: ["csinh function", "csinhf function", "csinhl function"] ms.assetid: cc616e55-d14d-4cd3-91f0-fbee03ce5edf --- -# csinh, csinhf, csinhl +# `csinh`, `csinhf`, `csinhl` Retrieves the hyperbolic sine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex csinhl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The hyperbolic sine of *z*, in radians. +The hyperbolic sine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **csinh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csinh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csinh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csinh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csinh**, **csinhf**, **csinhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csinh`**, **`csinhf`**, **`csinhl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md index dcfc4cea17..91ae3bdad6 100644 --- a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md +++ b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md @@ -10,7 +10,7 @@ f1_keywords: ["csqrt", "csqrtf", "csqrtl", "complex/csqrt", "complex/csqrtf", "c helpviewer_keywords: ["csqrt function", "csqrtf function", "csqrtl function"] ms.assetid: b65f086b-0f55-4622-a7a3-4e79d9c9c05c --- -# csqrt, csqrtf, csqrtl +# `csqrt`, `csqrtf`, `csqrtl` Retrieves the square root of a complex number, with a branch cut along the negative real axis. @@ -36,42 +36,42 @@ _Lcomplex csqrtl( ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The square root of *z*. The result is in the right half-plane. +The square root of *`z`*. The result is in the right half-plane. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND|none|_DOMAIN| -|- ∞|none|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | _DOMAIN | +| - INF | none | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **csqrt** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csqrt** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csqrt`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csqrt`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csqrt**, **csqrtf**, **csqrtl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csqrt`**, **`csqrtf`**, **`csqrtl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md) diff --git a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md index 2b86ee7541..a88bd27f83 100644 --- a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md +++ b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md @@ -10,7 +10,7 @@ f1_keywords: ["ctan", "ctanf", "ctanl", "complex/ctan", "complex/ctanf", "comple helpviewer_keywords: ["ctan function", "ctanf function", "ctanl function"] ms.assetid: d3cbd25c-1e93-4a6d-8154-da42921f7223 --- -# ctan, ctanf, ctanl +# `ctan`, `ctanf`, `ctanl` Retrieves the tangent of a complex number. @@ -36,42 +36,42 @@ _Lcomplex ctanl( ### Parameters -*z*\ +*`z`*\ A complex number that represents the angle, in radians. -## Return Value +## Return value -The tangent of *z*. +The tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|_DOMAIN| -|± ∞ (**tan**, **tanf**)|INVALID|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | _DOMAIN | +| ± INF (`tan`, `tanf`) | INVALID | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **ctan** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ctan** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ctan`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ctan`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ctan**, **ctanf**, **ctanl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ctan`**, **`ctanf`**, **`ctanl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md index ec29834469..0b7fa8bfce 100644 --- a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md +++ b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md @@ -10,7 +10,7 @@ f1_keywords: ["ctanh", "ctanhf", "ctanhl", "complex/ctanh", "complex/ctanhf", "c helpviewer_keywords: ["ctanh function", "ctanhl function", "ctanhf function"] ms.assetid: 807f2cd1-8740-4988-afff-5911c346385b --- -# ctanh, ctanhf, ctanhl +# `ctanh`, `ctanhf`, `ctanhl` Computes the complex hyperbolic tangent of a complex number. @@ -36,42 +36,42 @@ _Lcomplex ctanhl( ### Parameters -*z*\ +*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The complex hyperbolic tangent of *z*. +The complex hyperbolic tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|_DOMAIN| -|± ∞ (tan, tanf)|INVALID|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | _DOMAIN | +| ± INF (tan, tanf) | INVALID | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **ctanh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ctanh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ctanh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ctanh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ctanh**, **ctanhf**, **ctanhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ctanh`**, **`ctanhf`**, **`ctanhl`** | \ | \ | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md b/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md index 3d6986a827..0b2cc7c948 100644 --- a/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md +++ b/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md @@ -3,16 +3,16 @@ description: "Learn more about: ctime, _ctime32, _ctime64, _wctime, _wctime32, _ title: "ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64" ms.date: "4/2/2020" api_name: ["_ctime64", "_wctime32", "ctime", "_wctime64", "_ctime32", "_wctime", "_o__wctime32", "_o__wctime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wctime64", "_ctime32", "_tctime", "_wctime", "_wctime32", "_tctime64", "_ctime64", "ctime"] helpviewer_keywords: ["tctime64 function", "_ctime32 function", "ctime32 function", "_wctime function", "wctime64 function", "_tctime64 function", "_tctime32 function", "_ctime64 function", "_wctime64 function", "ctime function", "wctime32 function", "ctime64 function", "_wctime32 function", "_tctime function", "tctime32 function", "tctime function", "wctime function", "time, converting"] ms.assetid: 2423de37-a35c-4f0a-a378-3116bc120a9d --- -# ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64 +# `ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64` -Convert a time value to a string and adjust for local time zone settings. More secure versions of these functions are available; see [ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md). +Convert a time value to a string and adjust for local time zone settings. More secure versions of these functions are available; see [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md). ## Syntax @@ -27,24 +27,24 @@ wchar_t *_wctime64( const __time64_t *sourceTime ); ### Parameters -*sourceTime*
+*`sourceTime`*\ Pointer to stored time to convert. -## Return Value +## Return value -A pointer to the character string result. **NULL** will be returned if: +A pointer to the character string result. `NULL` is returned when: -- *sourceTime* represents a date before midnight, January 1, 1970, UTC. +- *`sourceTime`* represents a date before midnight, January 1, 1970, UTC. -- If you use **_ctime32** or **_wctime32** and *sourceTime* represents a date after 23:59:59 January 18, 2038, UTC. +- You use **`_ctime32`** or **`_wctime32`**, and *`sourceTime`* represents a date after 23:59:59 January 18, 2038, UTC. -- If you use **_ctime64** or **_wctime64** and *sourceTime* represents a date after 23:59:59, December 31, 3000, UTC. +- You use **`_ctime64`** or **`_wctime64`**, and *`sourceTime`* represents a date after 23:59:59, December 31, 3000, UTC. -**ctime** is an inline function which evaluates to **_ctime64** and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. Doing this will cause **ctime** to evaluate to **_ctime32**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`ctime`** is an inline function that evaluates to **`_ctime64`**, and `time_t` is equivalent to `__time64_t`. If you need to force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`. This macro causes **`ctime`** to evaluate to **`_ctime32`**. We don't recommend you use it, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. ## Remarks -The **ctime** function converts a time value stored as a [time_t](../../c-runtime-library/standard-types.md) value into a character string. The *sourceTime* value is usually obtained from a call to [time](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: +The **`ctime`** function converts a time value stored as a [`time_t`](../standard-types.md) value into a character string. The *`sourceTime`* value is typically obtained from a call to [`time`](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: ```Output Wed Jan 02 02:03:55 1980\n\0 @@ -52,36 +52,36 @@ Wed Jan 02 02:03:55 1980\n\0 A 24-hour clock is used. All fields have a constant width. The newline character ('\n') and the null character ('\0') occupy the last two positions of the string. -The converted character string is also adjusted according to the local time zone settings. See the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime](localtime-localtime32-localtime64.md) functions for information on configuring the local time and the [_tzset](tzset.md) function for details about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information on configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For details about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. -A call to **ctime** modifies the single statically allocated buffer used by the **gmtime** and **localtime** functions. Each call to one of these routines destroys the result of the previous call. **ctime** shares a static buffer with the **asctime** function. Thus, a call to **ctime** destroys the results of any previous call to **asctime**, **localtime**, or **gmtime**. +A call to **`ctime`** modifies the single statically allocated buffer used by the `gmtime` and `localtime` functions. Each call to one of these routines destroys the result of the previous call. **`ctime`** shares a static buffer with the `asctime` function. Thus, a call to **`ctime`** destroys the results of any previous call to `asctime`, `localtime`, or `gmtime`. -**_wctime** and **_wctime64** are the wide-character version of **ctime** and **_ctime64**; returning a pointer to wide-character string. Otherwise, **_ctime64**, **_wctime**, and **_wctime64** behave identically to **ctime**. +**`_wctime`** and **`_wctime64`** are the wide-character version of **`ctime`** and **`_ctime64`**; returning a pointer to wide-character string. Otherwise, **`_ctime64`**, **`_wctime`**, and **`_wctime64`** behave identically to **`ctime`**. -These functions validate their parameters. If *sourceTime* is a null pointer, or if the *sourceTime* value is negative, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return **NULL** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`sourceTime`* is a null pointer, or if the *`sourceTime`* value is negative, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `NULL` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tctime**|**ctime**|**ctime**|**_wctime**| -|**_tctime32**|**_ctime32**|**_ctime32**|**_wctime32**| -|**_tctime64**|**_ctime64**|**_ctime64**|**_wctime64**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tctime` | **`ctime`** | **`ctime`** | **`_wctime`** | +| `_tctime32` | **`_ctime32`** | **`_ctime32`** | **`_wctime32`** | +| `_tctime64` | **`_ctime64`** | **`_ctime64`** | **`_wctime64`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ctime**|\| -|**_ctime32**|\| -|**_ctime64**|\| -|**_wctime**|\ or \| -|**_wctime32**|\ or \| -|**_wctime64**|\ or \| +| Routine | Required header | +|---|---| +| **`ctime`** | \ | +| **`_ctime32`** | \ | +| **`_ctime64`** | \ | +| **`_wctime`** | \ or \ | +| **`_wctime32`** | \ or \ | +| **`_wctime64`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,10 +112,10 @@ The time is Wed Feb 13 16:04:43 2002 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md b/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md index bc5265e7da..efbd48aaa0 100644 --- a/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md +++ b/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md @@ -3,16 +3,16 @@ description: "Learn more about: ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wct title: "ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s" ms.date: "4/2/2020" api_name: ["_ctime64_s", "_wctime32_s", "ctime_s", "_wctime64_s", "_ctime32_s", "_wctime_s", "_o__ctime32_s", "_o__ctime64_s", "_o__wctime32_s", "_o__wctime64_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ctime64_s", "_ctime32_s", "_tctime32_s", "_ctime64_s", "_wctime_s", "_tctime_s", "_tctime64_s", "ctime_s", "ctime32_s"] helpviewer_keywords: ["_wctime32_s function", "ctime64_s function", "_tctime64_s function", "_wctime_s function", "tctime_s function", "_wctime64_s function", "ctime_s function", "ctime32_s function", "_ctime64_s function", "tctime64_s function", "wctime64_s function", "wctime_s function", "_tctime_s function", "tctime32_s function", "wctime32_s function", "time, converting", "_ctime32_s function", "_tctime32_s function"] ms.assetid: 36ac419a-8000-4389-9fd8-d78b747a009b --- -# ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s +# `ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s` -Convert a time value to a string and adjust for local time zone settings. These are versions of [ctime, _ctime64, _wctime, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a time value to a string and adjust for local time zone settings. These functions are versions of [`ctime`, `_ctime64`, `_wctime`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -74,77 +74,77 @@ errno_t _wctime64_s( ### Parameters -*buffer*
-Must be large enough to hold 26 characters. A pointer to the character string result, or **NULL** if: +*`buffer`*\ +Must be large enough to hold 26 characters. A pointer to the character string result, or `NULL` if: -- *sourceTime* represents a date before midnight, January 1, 1970, UTC. +- *`sourceTime`* represents a date before midnight, January 1, 1970, UTC. -- If you use **_ctime32_s** or **_wctime32_s** and *sourceTime* represents a date after 23:59:59 January 18, 2038, UTC. +- If you use **`_ctime32_s`** or **`_wctime32_s`** and *`sourceTime`* represents a date after 23:59:59 January 18, 2038, UTC. -- If you use **_ctime64_s** or **_wctime64_s** and *sourceTime* represents a date after 23:59:59, December 31, 3000, UTC. +- If you use **`_ctime64_s`** or **`_wctime64_s`** and *`sourceTime`* represents a date after 23:59:59, December 31, 3000, UTC. -- If you use **_ctime_s** or **_wctime_s**, these functions are wrappers to the previous functions. See the Remarks section. +- If you use **`_ctime_s`** or **`_wctime_s`**, these functions are wrappers to the previous functions. See the Remarks section. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer. -*sourceTime*
+*`sourceTime`*\ Pointer to stored time. -## Return Value +## Return value -Zero if successful. If there is a failure due to an invalid parameter, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in ERRNO.H; for a listing of these errors, see [errno](../../c-runtime-library/errno-constants.md). The actual error codes thrown for each error condition are shown in the following table. +Zero if successful. If there's a failure due to an invalid parameter, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in ERRNO.H; for a listing of these errors, see [`errno`](../errno-constants.md). The actual error codes thrown for each error condition are shown in the following table. -## Error Conditions +## Error conditions -|*buffer*|*numberOfElements*|*sourceTime*|Return|Value in *buffer*| -|--------------|------------------------|------------|------------|-----------------------| -|**NULL**|any|any|**EINVAL**|Not modified| -|Not **NULL** (points to valid memory)|0|any|**EINVAL**|Not modified| -|Not **NULL**|0< size < 26|any|**EINVAL**|Empty string| -|Not **NULL**|>= 26|NULL|**EINVAL**|Empty string| -|Not **NULL**|>= 26|< 0|**EINVAL**|Empty string| +| *`buffer`* | *`numberOfElements`* | *`sourceTime`* | Return | Value in *`buffer`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | Not modified | +| Not `NULL` (points to valid memory) | 0 | any | `EINVAL` | Not modified | +| Not `NULL` | 0< size < 26 | any | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | NULL | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | < 0 | `EINVAL` | Empty string | ## Remarks -The **ctime_s** function converts a time value stored as a [time_t](../../c-runtime-library/standard-types.md) structure into a character string. The *sourceTime* value is usually obtained from a call to [time](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: +The **`ctime_s`** function converts a time value stored as a [`time_t`](../standard-types.md) structure into a character string. The *`sourceTime`* value is typically obtained from a call to [`time`](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: -`Wed Jan 02 02:03:55 1980\n\0` +`Wed Jan 2 02:03:55 1980\n\0` A 24-hour clock is used. All fields have a constant width. The new line character ('\n') and the null character ('\0') occupy the last two positions of the string. -The converted character string is also adjusted according to the local time zone settings. See the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime32_s](localtime-s-localtime32-s-localtime64-s.md) functions for information about configuring the local time and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information on configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For details about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. -**_wctime32_s** and **_wctime64_s** are the wide-character version of **_ctime32_s** and **_ctime64_s**; returning a pointer to wide-character string. Otherwise, **_ctime64_s**, **_wctime32_s**, and **_wctime64_s** behave identically to **_ctime32_s**. +**`_wctime32_s`** and **`_wctime64_s`** are the wide-character version of **`_ctime32_s`** and **`_ctime64_s`**; returning a pointer to wide-character string. Otherwise, **`_ctime64_s`**, **`_wctime32_s`**, and **`_wctime64_s`** behave identically to **`_ctime32_s`**. -**ctime_s** is an inline function that evaluates to **_ctime64_s** and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. Doing this will cause **ctime_s** to evaluate to **_ctime32_s**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`ctime_s`** is an inline function that evaluates to **`_ctime64_s`** and `time_t` is equivalent to `__time64_t`. If you need to force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`. This macro causes **`ctime_s`** to evaluate to **`_ctime32_s`**. We don't recommend it, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tctime_s**|**ctime_s**|**ctime_s**|**_wctime_s**| -|**_tctime32_s**|**_ctime32_s**|**_ctime32_s**|**_wctime32_s**| -|**_tctime64_s**|**_ctime64_s**|**_ctime64_s**|**_wctime64_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tctime_s` | **`ctime_s`** | **`ctime_s`** | **`_wctime_s`** | +| `_tctime32_s` | **`_ctime32_s`** | **`_ctime32_s`** | **`_wctime32_s`** | +| `_tctime64_s` | **`_ctime64_s`** | **`_ctime64_s`** | **`_wctime64_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ctime_s**, **_ctime32_s**, **_ctime64_s**|\| -|**_wctime_s**, **_wctime32_s**, **_wctime64_s**|\ or \| +| Routine | Required header | +|---|---| +| **`ctime_s`**, **`_ctime32_s`**, **`_ctime64_s`** | \ | +| **`_wctime_s`**, **`_wctime32_s`**, **`_wctime64_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -182,10 +182,10 @@ The time is Fri Apr 25 13:03:39 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/cwait.md b/docs/c-runtime-library/reference/cwait.md index 86e3308cb8..aeaaad8adc 100644 --- a/docs/c-runtime-library/reference/cwait.md +++ b/docs/c-runtime-library/reference/cwait.md @@ -3,14 +3,14 @@ title: "_cwait" description: "API reference for the Microsoft Visual C runtime `_cwait()` function." ms.date: "10/23/2020" api_name: ["_cwait", "_o__cwait"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_cwait"] helpviewer_keywords: ["cwait function", "_cwait function"] ms.assetid: d9b596b5-45f4-4e03-9896-3f383cb922b8 --- -# _cwait +# `_cwait` Waits until another process terminates. @@ -30,44 +30,44 @@ intptr_t _cwait( ### Parameters *`termstat`*\ -Pointer to a buffer where the result code of the specified process will be stored, or **`NULL`**. +Pointer to a buffer where the result code of the specified process will be stored, or `NULL`. *`procHandle`*\ -The handle to the process to wait on (that is, the process that has to terminate before **_cwait** can return). +The handle to the process to wait on (that is, the process that has to terminate before **`_cwait`** can return). *`action`*\ -**`NULL`**: Ignored by Windows operating system applications; for other applications: action code to perform on *`procHandle`*. +`NULL`: Ignored by Windows operating system applications; for other applications: action code to perform on *`procHandle`*. -## Return Value +## Return value -When the specified process has successfully completed, returns the handle of the specified process and sets *`termstat`* to the result code that's returned by the specified process. Otherwise, returns -1 and sets **`errno`** as follows. +When the specified process has successfully completed, returns the handle of the specified process and sets *`termstat`* to the result code that's returned by the specified process. Otherwise, returns -1 and sets `errno` as follows. -|Value|Description| -|-----------|-----------------| -|**`ECHILD`**|No specified process exists, *`procHandle`* is invalid, or the call to the [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed.| -|**`EINVAL`**|*`action`* is invalid.| +| `errno` value | Description | +|---|---| +| `ECHILD` | No specified process exists, *`procHandle`* is invalid, or the call to the [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed. | +| `EINVAL` | *`action`* is invalid. | -For more information about these and other return codes, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_cwait`** function waits for the termination of the process ID of the specified process that's provided by *`procHandle`*. The value of *`procHandle`* that's passed to **`_cwait`** should be the value that's returned by the call to the [`_spawn`](../../c-runtime-library/spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **`_cwait`** is called, **`_cwait`** returns immediately. **`_cwait`** can be used by any process to wait for any other known process for which a valid handle (*`procHandle`*) exists. +The **`_cwait`** function waits for the termination of the process ID of the specified process that's provided by *`procHandle`*. The value of *`procHandle`* that's passed to **`_cwait`** should be the value that's returned by the call to the [`_spawn`](../spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **`_cwait`** is called, **`_cwait`** returns immediately. **`_cwait`** can be used by any process to wait for any other known process for which a valid handle (*`procHandle`*) exists. -*`termstat`* points to a buffer where the return code of the specified process will be stored. The value of *`termstat`* indicates whether the specified process terminated normally by calling the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. **`ExitProcess`** is called internally if the specified process calls **`exit`** or **`_exit`**, returns from **`main`**, or reaches the end of **`main`**. For more information about the value that's passed back through *`termstat`*, see [GetExitCodeProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **`_cwait`** is called by using a **`NULL`** value for *`termstat`*, the return code of the specified process isn't stored. +*`termstat`* points to a buffer where the return code of the specified process will be stored. The value of *`termstat`* indicates whether the specified process terminated normally by calling the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. `ExitProcess` is called internally if the specified process calls **`exit`** or **`_exit`**, returns from **`main`**, or reaches the end of **`main`**. For more information about the value that's passed back through *`termstat`*, see [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **`_cwait`** is called by using a `NULL` value for *`termstat`*, the return code of the specified process isn't stored. The *`action`* parameter is ignored by the Windows operating system because parent-child relationships aren't implemented in these environments. Unless *`procHandle`* is -1 or -2 (handles to the current process or thread), the handle will be closed. In this situation, don't use the returned handle. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_cwait`**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_cwait`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -141,5 +141,5 @@ Hi, Dad. It's Dave. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ -[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md) +[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md) diff --git a/docs/c-runtime-library/reference/cxxthrowexception.md b/docs/c-runtime-library/reference/cxxthrowexception.md index 20d460e28a..2a2a3b87b6 100644 --- a/docs/c-runtime-library/reference/cxxthrowexception.md +++ b/docs/c-runtime-library/reference/cxxthrowexception.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CxxThrowException" title: "_CxxThrowException" +description: "Learn more about: _CxxThrowException" ms.date: "11/04/2016" api_name: ["_CxxThrowException"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CxxThrowException", "_CxxThrowException"] helpviewer_keywords: ["_CxxThrowException function", "CxxThrowException function"] -ms.assetid: 0b90bef5-b7d2-46e0-88e2-59e531e01a4d --- -# _CxxThrowException +# `_CxxThrowException` Builds the exception record and calls the runtime environment to start processing the exception. @@ -18,22 +17,22 @@ Builds the exception record and calls the runtime environment to start processin ```C extern "C" void __stdcall _CxxThrowException( - void* pExceptionObject + void* pExceptionObject, _ThrowInfo* pThrowInfo ); ``` ### Parameters -*pExceptionObject*
+*`pExceptionObject`*\ The object that generated the exception. -*pThrowInfo*
+*`pThrowInfo`*\ The information that is required to process the exception. ## Remarks -This method is included in a compiler-only file that the compiler uses to process exceptions. Do not call the method directly from your code. +This method is included in a compiler-only file that the compiler uses to process exceptions. Don't call the method directly from your code. ## Requirements @@ -41,4 +40,4 @@ This method is included in a compiler-only file that the compiler uses to proces ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md index bb423593a5..b5825758e2 100644 --- a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md +++ b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md @@ -3,14 +3,14 @@ description: "Learn more about: difftime, _difftime32, _difftime64" title: "difftime, _difftime32, _difftime64" ms.date: "4/2/2020" api_name: ["_difftime32", "difftime", "_difftime64", "_o__difftime32", "_o__difftime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_difftime64", "difftime", "difftime64", "_difftime32", "difftime32"] helpviewer_keywords: ["_difftime32 function", "difftime function", "time, finding the difference", "difftime64 function", "_difftime64 function", "difftime32 function"] ms.assetid: 4cc0ac2b-fc7b-42c0-8283-8c9d10c566d0 --- -# difftime, _difftime32, _difftime64 +# `difftime`, `_difftime32`, `_difftime64` Finds the difference between two times. @@ -24,37 +24,37 @@ double _difftime64( __time64_t timeEnd, __time64_t timeStart ); ### Parameters -*timeEnd*
+*`timeEnd`*\ Ending time. -*timeStart*
+*`timeStart`*\ Beginning time. -## Return Value +## Return value -**difftime** returns the elapsed time in seconds, from *timeStart* to *timeEnd*. The value returned is a double precision floating-point number. The return value may be 0, indicating an error. +**`difftime`** returns the elapsed time in seconds, from *`timeStart`* to *`timeEnd`*. The value returned is a double precision floating-point number. The return value may be 0, indicating an error. ## Remarks -The **difftime** function computes the difference between the two supplied time values *timeStart* and *timeEnd*. +The **`difftime`** function computes the difference between the two supplied time values *`timeStart`* and *`timeEnd`*. -The time value supplied must fit within the range of **time_t**. **time_t** is a 64-bit value. Thus, the end of the range was extended from 23:59:59 January 18, 2038, UTC to 23:59:59, December 31, 3000. The lower range of **time_t** is still midnight, January 1, 1970. +The time value supplied must fit within the range of `time_t`. `time_t` is a 64-bit value. Thus, the end of the range was extended from 23:59:59 January 18, 2038, UTC to 23:59:59, December 31, 3000. The lower range of `time_t` is still midnight, January 1, 1970. -**difftime** is an inline function that evaluates to either **_difftime32** or **_difftime64** depending on whether **_USE_32BIT_TIME_T** is defined. _difftime32 and _difftime64 can be used directly to force the use of a particular size of the time type. +**`difftime`** is an inline function that evaluates to either **`_difftime32`** or **`_difftime64`** depending on whether `_USE_32BIT_TIME_T` is defined. _difftime32 and _difftime64 can be used directly to force the use of a particular size of the time type. -These functions validate their parameters. If either of the parameters is zero or negative, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return 0 and set **errno** to **EINVAL**. +These functions validate their parameters. If either of the parameters is zero or negative, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return 0 and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**difftime**|\| -|**_difftime32**|\| -|**_difftime64**|\| +| Routine | Required header | +|---|---| +| **`difftime`** | \ | +| **`_difftime32`** | \ | +| **`_difftime64`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -114,6 +114,6 @@ Program takes 3 seconds. ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Time Management](../../c-runtime-library/time-management.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Time management](../time-management.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/div.md b/docs/c-runtime-library/reference/div.md index a9e98499e6..5fb4a081e9 100644 --- a/docs/c-runtime-library/reference/div.md +++ b/docs/c-runtime-library/reference/div.md @@ -49,15 +49,15 @@ The numerator. *`denom`*\ The denominator. -## Return Value +## Return value **`div`** called by using arguments of type **`int`** returns a structure of type `div_t`, which contains the quotient and the remainder. The return value with arguments of type **`long`** is `ldiv_t`, and the return value with arguments of type **`long long`** is `lldiv_t`. The `div_t`, `ldiv_t`, and `lldiv_t` types are defined in \. ## Remarks -The **`div`** function divides *`numer`* by *`denom`* and computes the quotient and the remainder. The [`div_t`](../../c-runtime-library/standard-types.md) structure contains the quotient, `quot`, and the remainder, `rem`. The sign of the quotient is the same as the sign of the mathematical quotient. Its absolute value is the largest integer that's less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. +The **`div`** function divides *`numer`* by *`denom`* and computes the quotient and the remainder. The [`div_t`](../standard-types.md) structure contains the quotient, `quot`, and the remainder, `rem`. The sign of the quotient is the same as the sign of the mathematical quotient. Its absolute value is the largest integer that's less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. -The overloads of **`div`** that take arguments of type **`long`** or **`long long`** are only available to C++ code. The return types [`ldiv_t`](../../c-runtime-library/standard-types.md) and [`lldiv_t`](../../c-runtime-library/standard-types.md) contains members `quot` and `rem`, which have the same meanings as the members of `div_t`. +The overloads of **`div`** that take arguments of type **`long`** or **`long long`** are only available to C++ code. The return types [`ldiv_t`](../standard-types.md) and [`lldiv_t`](../standard-types.md) contains members `quot` and `rem`, which have the same meanings as the members of `div_t`. ## Requirements @@ -65,7 +65,7 @@ The overloads of **`div`** that take arguments of type **`long`** or **`long lon |--|--| | **`div`**, **`ldiv`**, **`lldiv`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -107,5 +107,5 @@ The quotient is 67, and the remainder is 5 ## See also -[Floating-point support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`imaxdiv`](imaxdiv.md) diff --git a/docs/c-runtime-library/reference/dup-dup2.md b/docs/c-runtime-library/reference/dup-dup2.md index 4505fb5261..718e1e3af7 100644 --- a/docs/c-runtime-library/reference/dup-dup2.md +++ b/docs/c-runtime-library/reference/dup-dup2.md @@ -3,16 +3,15 @@ description: "Learn more about: _dup, _dup2" title: "_dup, _dup2" ms.date: "4/2/2020" api_name: ["_dup", "_dup2", "_o__dup", "_o__dup2"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_dup2", "_dup"] helpviewer_keywords: ["_dup2 function", "dup function", "file handles [C++], duplicating", "file handles [C++], reassigning", "dup2 function", "_dup function"] -ms.assetid: 4d07e92c-0d76-4832-a770-dfec0e7a0cfa --- -# _dup, _dup2 +# `_dup`, `_dup2` -Creates a second file descriptor for an open file (**_dup**), or reassigns a file descriptor (**_dup2**). +Creates a second file descriptor for an open file (**`_dup`**), or reassigns a file descriptor (**`_dup2`**). ## Syntax @@ -23,38 +22,38 @@ int _dup2( int fd1, int fd2 ); ### Parameters -*fd*, *fd1*
+*`fd`*, *`fd1`*\ File descriptors referring to open file. -*fd2*
+*`fd2`*\ Any file descriptor. -## Return Value +## Return value -**_dup** returns a new file descriptor. **_dup2** returns 0 to indicate success. If an error occurs, each function returns -1 and sets **errno** to **EBADF** if the file descriptor is invalid or to **EMFILE** if no more file descriptors are available. In the case of an invalid file descriptor, the function also invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`_dup`** returns a new file descriptor. **`_dup2`** returns 0 to indicate success. If an error occurs, each function returns -1 and sets `errno` to `EBADF` if the file descriptor is invalid, or to `EMFILE` if no more file descriptors are available. When passed an invalid file descriptor, the function also invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_dup** and **_dup2** functions associate a second file descriptor with a currently open file. These functions can be used to associate a predefined file descriptor, such as that for **stdout**, with a different file. Operations on the file can be carried out using either file descriptor. The type of access allowed for the file is unaffected by the creation of a new descriptor. **_dup** returns the next available file descriptor for the given file. **_dup2** forces *fd2* to refer to the same file as *fd1*. If *fd2* is associated with an open file at the time of the call, that file is closed. +The **`_dup`** and **`_dup2`** functions associate a second file descriptor with a currently open file. These functions can be used to associate a predefined file descriptor, such as that for **`stdout`**, with a different file. Operations on the file can be carried out using either file descriptor. The type of access allowed for the file is unaffected by the creation of a new descriptor. **`_dup`** returns the next available file descriptor for the given file. **`_dup2`** forces *`fd2`* to refer to the same file as *`fd1`*. If *`fd2`* is associated with an open file at the time of the call, that file is closed. -Both **_dup** and **_dup2** accept file descriptors as parameters. To pass a stream (`FILE *`) to either of these functions, use [_fileno](fileno.md). The **fileno** routine returns the file descriptor currently associated with the given stream. The following example shows how to associate **stderr** (defined as `FILE *` in Stdio.h) with a file descriptor: +Both **`_dup`** and **`_dup2`** accept file descriptors as parameters. To pass a stream (`FILE *`) to either of these functions, use [`_fileno`](fileno.md). The **`fileno`** routine returns the file descriptor currently associated with the given stream. The following example shows how to associate **`stderr`** (defined as `FILE *` in `stdio.h`) with a file descriptor: ```C int cstderr = _dup( _fileno( stderr )); ``` -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_dup**|\| -|**_dup2**|\| +| Routine | Required header | +|---|---| +| **`_dup`** | `` | +| **`_dup2`** | `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -119,7 +118,7 @@ This goes to file 'data' ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_close](close.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md b/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md index a23cbff6ee..047aba34af 100644 --- a/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md +++ b/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _dupenv_s_dbg, _wdupenv_s_dbg" title: "_dupenv_s_dbg, _wdupenv_s_dbg" +description: "Learn more about: _dupenv_s_dbg, _wdupenv_s_dbg" ms.date: "11/04/2016" api_name: ["_dupenv_s_dbg", "_wdupenv_s_dbg"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tdupenv_s_dbg", "_dupenv_s_dbg", "_wdupenv_s_dbg"] helpviewer_keywords: ["_tdupenv_s_dbg function", "dupenv_s_dbg function", "_wdupenv_s_dbg function", "environment variables", "tdupenv_s_dbg function", "wdupenv_s_dbg function", "_dupenv_s_dbg function"] -ms.assetid: e3d81148-e24e-46d0-a21d-fd87b5e6256c --- -# _dupenv_s_dbg, _wdupenv_s_dbg +# `_dupenv_s_dbg`, `_wdupenv_s_dbg` -Get a value from the current environment. Versions of [_dupenv_s, _wdupenv_s](dupenv-s-wdupenv-s.md) that allocate memory with [_malloc_dbg](malloc-dbg.md) to provide additional debugging information. +Get a value from the current environment. Versions of [`_dupenv_s`, `_wdupenv_s`](dupenv-s-wdupenv-s.md) that allocate memory with [`_malloc_dbg`](malloc-dbg.md) to provide more debugging information. ## Syntax @@ -23,7 +22,7 @@ errno_t _dupenv_s_dbg( const char *varname, int blockType, const char *filename, - int linenumber + int lineNumber ); errno_t _wdupenv_s_dbg( wchar_t **buffer, @@ -31,64 +30,64 @@ errno_t _wdupenv_s_dbg( const wchar_t *varname, int blockType, const char *filename, - int linenumber + int lineNumber ); ``` ### Parameters -*buffer*
+*`buffer`*\ Buffer to store the variable's value. -*numberOfElements*
-Size of *buffer*. +*`numberOfElements`*\ +Size of *`buffer`*. -*varname*
+*`varname`*\ Environment variable name. -*blockType*
-Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file or **NULL**. +*`filename`*\ +Pointer to the name of the source file or `NULL`. -*linenumber*
-Line number in source file or **NULL**. +*`lineNumber`*\ +Line number in source file or `NULL`. -## Return Value +## Return value Zero on success, an error code on failure. -These functions validate their parameters; if *buffer* or *varname* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **errno** to **EINVAL** and return **EINVAL**. +These functions validate their parameters; if *`buffer`* or *`varname`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL`, and return `EINVAL`. -If these functions cannot allocate enough memory, they set *buffer* to **NULL** and *numberOfElements* to 0, and return **ENOMEM**. +If these functions can't allocate enough memory, they set *`buffer`* to `NULL` and *`numberOfElements`* to 0, and return `ENOMEM`. ## Remarks -The **_dupenv_s_dbg** and **_wdupenv_s_dbg** functions are identical to **_dupenv_s** and **_wdupenv_s** except that, when **_DEBUG** is defined, these functions use the debug version of [malloc](malloc.md), [_malloc_dbg](malloc-dbg.md), to allocate memory for the value of the environment variable. For information on the debugging features of **_malloc_dbg**, see [_malloc_dbg](malloc-dbg.md). +The **`_dupenv_s_dbg`** and **`_wdupenv_s_dbg`** functions are identical to `_dupenv_s` and `_wdupenv_s` except that, when `_DEBUG` is defined, these functions use the debug version of [`malloc`](malloc.md), [`_malloc_dbg`](malloc-dbg.md), to allocate memory for the value of the environment variable. For information on the debugging features of `_malloc_dbg`, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_dupenv_s** and **_wdupenv_s** are remapped to **_dupenv_s_dbg** and **_wdupenv_s_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_dupenv_s` and `_wdupenv_s` are remapped to **`_dupenv_s_dbg`** and **`_wdupenv_s_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information on block types, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tdupenv_s_dbg**|**_dupenv_s_dbg**|**_dupenv_s_dbg**|**_wdupenv_s_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tdupenv_s_dbg` | **`_dupenv_s_dbg`** | **`_dupenv_s_dbg`** | **`_wdupenv_s_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_dupenv_s_dbg**|\| -|**_wdupenv_s_dbg**|\| +| Routine | Required header | +|---|---| +| **`_dupenv_s_dbg`** | \ | +| **`_wdupenv_s_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_dupenv_s_dbg.c -#include +#include #include int main( void ) @@ -115,7 +114,7 @@ nonexistentvariable = (null) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[Environmental Constants](../../c-runtime-library/environmental-constants.md)
-[getenv_s, _wgetenv_s](getenv-s-wgetenv-s.md)
-[_putenv_s, _wputenv_s](putenv-s-wputenv-s.md)
+[Process and environment control](../process-and-environment-control.md)\ +[Environmental constants](../environmental-constants.md)\ +[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)\ +[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) diff --git a/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md b/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md index 53149e85ef..da9fb11032 100644 --- a/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md +++ b/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _dupenv_s, _wdupenv_s" title: "_dupenv_s, _wdupenv_s" +description: "Learn more about: _dupenv_s, _wdupenv_s" ms.date: "4/2/2020" api_name: ["_dupenv_s", "_wdupenv_s", "_o__dupenv_s", "_o__wdupenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["tdupenv_s", "_dupenv_s", "wdupenv_s", "dupenv_s", "_tdupenv_s", "_wdupenv_s"] helpviewer_keywords: ["_dupenv_s function", "_tdupenv_s function", "_wdupenv_s function", "environment variables", "wdupenv_s function", "dupenv_s function", "tdupenv_s function"] -ms.assetid: b729ecc2-a31d-4ccf-92a7-5accedb8f8c8 --- # `_dupenv_s`, `_wdupenv_s` @@ -34,62 +33,62 @@ errno_t _wdupenv_s( ### Parameters -*`buffer`*
+*`buffer`*\ Buffer to store the variable's value. -*`numberOfElements`*
+*`numberOfElements`*\ Size of *`buffer`*. -*`varname`*
+*`varname`*\ Environment variable name. -## Return Value +## Return value Zero on success, an error code on failure. -These functions validate their parameters; if *`buffer`* or *`varname`* is **`NULL`**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +These functions validate their parameters; if *`buffer`* or *`varname`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL` and return `EINVAL`. -If these functions cannot allocate enough memory, they set *`buffer`* to **`NULL`** and *`numberOfElements`* to 0, and return **`ENOMEM`**. +If these functions can't allocate enough memory, they set *`buffer`* to `NULL` and *`numberOfElements`* to 0, and return `ENOMEM`. ## Remarks -The **`_dupenv_s`** function searches the list of environment variables for *`varname`*. If the variable is found, **`_dupenv_s`** allocates a buffer and copies the variable's value into the buffer. The buffer's address and length are returned in *`buffer`* and *`numberOfElements`*. By allocating the buffer itself, **`_dupenv_s`** provides a more convenient alternative to [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). +The **`_dupenv_s`** function searches the list of environment variables for *`varname`*. If the variable is found, **`_dupenv_s`** allocates a buffer and copies the variable's value into the buffer. The buffer's address and length are returned in *`buffer`* and *`numberOfElements`*. Because it allocates the buffer itself, **`_dupenv_s`** provides a more convenient alternative to [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). > [!NOTE] -> It is the calling program's responsibility to free the memory by calling [`free`](free.md). +> It's the calling program's responsibility to free the memory by calling [`free`](free.md). -If the variable is not found, then *`buffer`* is set to **`NULL`**, *`numberOfElements`* is set to 0, and the return value is 0 because this situation is not considered to be an error condition. +If the variable isn't found, then *`buffer`* is set to `NULL`, *`numberOfElements`* is set to 0, and the return value is 0 because this situation isn't considered to be an error condition. -If you are not interested in the size of the buffer you can pass **`NULL`** for *`numberOfElements`*. +If you aren't interested in the size of the buffer, you can pass `NULL` for *`numberOfElements`*. -**`_dupenv_s`** is not case sensitive in the Windows operating system. **`_dupenv_s`** uses the copy of the environment pointed to by the global variable **`_environ`** to access the environment. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for a discussion of **`_environ`**. +**`_dupenv_s`** isn't case sensitive in the Windows operating system. **`_dupenv_s`** uses the copy of the environment pointed to by the global variable **`_environ`** to access the environment. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for a discussion of **`_environ`**. The value in *`buffer`* is a copy of the environment variable's value; modifying it has no effect on the environment. Use the [`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) function to modify the value of an environment variable. **`_wdupenv_s`** is a wide-character version of **`_dupenv_s`**; the arguments of **`_wdupenv_s`** are wide-character strings. The **`_wenviron`** global variable is a wide-character version of **`_environ`**. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for more on **`_wenviron`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tdupenv_s`**|**`_dupenv_s`**|**`_dupenv_s`**|**`_wdupenv_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tdupenv_s`** | **`_dupenv_s`** | **`_dupenv_s`** | **`_wdupenv_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_dupenv_s`**|``| -|**`_wdupenv_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_dupenv_s`** | `` | +| **`_wdupenv_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_dupenv_s.c -#include +#include int main( void ) { @@ -113,8 +112,8 @@ nonexistentvariable = (null) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[Environmental Constants](../../c-runtime-library/environmental-constants.md)
-[`_dupenv_s_dbg`, `_wdupenv_s_dbg`](dupenv-s-dbg-wdupenv-s-dbg.md)
-[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)
-[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md)
+[Process and environment control](../process-and-environment-control.md)\ +[Environmental constants](../environmental-constants.md)\ +[`_dupenv_s_dbg`, `_wdupenv_s_dbg`](dupenv-s-dbg-wdupenv-s-dbg.md)\ +[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)\ +[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) diff --git a/docs/c-runtime-library/reference/ecvt-s.md b/docs/c-runtime-library/reference/ecvt-s.md index ac3690bf2d..ea63b5f07a 100644 --- a/docs/c-runtime-library/reference/ecvt-s.md +++ b/docs/c-runtime-library/reference/ecvt-s.md @@ -3,100 +3,100 @@ description: "Learn more about: _ecvt_s" title: "_ecvt_s" ms.date: "4/2/2020" api_name: ["_ecvt_s", "_o__ecvt_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ecvt_s", "_ecvt_s"] helpviewer_keywords: ["_ecvt_s function", "ecvt_s function", "numbers, converting", "converting double numbers"] ms.assetid: d52fb0a6-cb91-423f-80b3-952a8955d914 --- -# _ecvt_s +# `_ecvt_s` -Converts a **`double`** number to a string. This is a version of [_ecvt](ecvt.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a **`double`** number to a string. This function is a version of [`_ecvt`](ecvt.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax ```C errno_t _ecvt_s( - char * _Buffer, - size_t _SizeInBytes, - double _Value, - int _Count, - int *_Dec, - int *_Sign + char * buffer, + size_t sizeInBytes, + double value, + int count, + int *dec, + int *sign ); template errno_t _ecvt_s( - char (&_Buffer)[size], - double _Value, - int _Count, - int *_Dec, - int *_Sign + char (&buffer)[size], + double value, + int count, + int *dec, + int *sign ); // C++ only ``` ### Parameters -*_Buffer*
+*`buffer`*\ Filled with the pointer to the string of digits, the result of the conversion. -*_SizeInBytes*
+*`sizeInBytes`*\ Size of the buffer in bytes. -*_Value*
+*`value`*\ Number to be converted. -*_Count*
+*`count`*\ Number of digits stored. -*_Dec*
+*`dec`*\ Stored decimal-point position. -*_Sign*
+*`sign`*\ Sign of the converted number. -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in Errno.h. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in Errno.h. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -In the case of an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If there's an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL`, and returns `EINVAL`. -### Error Conditions +### Error conditions -|*_Buffer*|*_SizeInBytes*|_Value|_Count|_Dec|_Sign|Return value|Value in *buffer*| -|---------------|--------------------|-------------|-------------|-----------|------------|------------------|-----------------------| -|**NULL**|any|any|any|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|<=0|any|any|any|any|**EINVAL**|Not modified.| -|any|any|any|any|**NULL**|any|**EINVAL**|Not modified.| -|any|any|any|any|any|**NULL**|**EINVAL**|Not modified.| +| *`buffer`* | *`sizeInBytes`* | *`value`* | *`count`* | *`dec`* | *`sign`* | Return value | Value in *`buffer`* | +|---|---|---|---|---|---|---|---| +| `NULL` | any | any | any | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | <=0 | any | any | any | any | `EINVAL` | Not modified. | +| any | any | any | any | `NULL` | any | `EINVAL` | Not modified. | +| any | any | any | any | any | `NULL` | `EINVAL` | Not modified. | -## Security Issues +## Security issues -**_ecvt_s** might generate an access violation if *buffer* does not point to valid memory and is not **NULL**. +**`_ecvt_s`** might generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`. ## Remarks -The **_ecvt_s** function converts a floating-point number to a character string. The *_Value* parameter is the floating-point number to be converted. This function stores up to *count* digits of *_Value* as a string and appends a null character ('\0'). If the number of digits in *_Value* exceeds *_Count*, the low-order digit is rounded. If there are fewer than *count* digits, the string is padded with zeros. +The **`_ecvt_s`** function converts a floating-point number to a character string. The *`value`* parameter is the floating-point number to be converted. This function stores up to *`count`* digits of *`value`* as a string and appends a null character ('\0'). If the number of digits in *`value`* exceeds *`count`*, the low-order digit is rounded. If there are fewer than *`count`* digits, the string is padded with zeros. -Only digits are stored in the string. The position of the decimal point and the sign of *_Value* can be obtained from *_Dec* and *_Sign* after the call. The *_Dec* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *_Sign* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *`sign`* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. -A buffer of length **_CVTBUFSIZE** is sufficient for any floating-point value. +A buffer of length `_CVTBUFSIZE` is sufficient for any floating-point value. -The difference between **_ecvt_s** and **_fcvt_s** is in the interpretation of the *_Count* parameter. **_ecvt_s** interprets *_Count* as the total number of digits in the output string, whereas **_fcvt_s** interprets *_Count* as the number of digits after the decimal point. +The difference between **`_ecvt_s`** and `_fcvt_s` is in the interpretation of the *`count`* parameter. **`_ecvt_s`** interprets *`count`* as the total number of digits in the output string, whereas `_fcvt_s` interprets *`count`* as the number of digits after the decimal point. -In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_ecvt_s**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_ecvt_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -132,9 +132,9 @@ Converted value: 12000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt](ecvt.md)
-[_fcvt_s](fcvt-s.md)
-[_gcvt_s](gcvt-s.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt_s`](fcvt-s.md)\ +[`_gcvt_s`](gcvt-s.md) diff --git a/docs/c-runtime-library/reference/ecvt.md b/docs/c-runtime-library/reference/ecvt.md index f6cb268ae2..0f26c4a704 100644 --- a/docs/c-runtime-library/reference/ecvt.md +++ b/docs/c-runtime-library/reference/ecvt.md @@ -3,16 +3,16 @@ description: "Learn more about: _ecvt" title: "_ecvt" ms.date: "4/2/2020" api_name: ["_ecvt", "_o__ecvt"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ecvt"] helpviewer_keywords: ["_ecvt function", "numbers, converting", "converting double numbers", "ecvt function"] ms.assetid: a916eb05-92d1-4b5c-8563-093acdb49dc8 --- -# _ecvt +# `_ecvt` -Converts a **`double`** number to a string. A more secure version of this function is available; see [_ecvt_s](ecvt-s.md). +Converts a **`double`** number to a string. A more secure version of this function is available; see [`_ecvt_s`](ecvt-s.md). ## Syntax @@ -27,45 +27,45 @@ char *_ecvt( ### Parameters -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits stored. -*dec*
+*`dec`*\ Stored decimal-point position. -*sign*
+*`sign`*\ Sign of the converted number. -## Return Value +## Return value -**_ecvt** returns a pointer to the string of digits; **NULL** if an error occurred. +**`_ecvt`** returns a pointer to the string of digits; `NULL` if an error occurred. ## Remarks -The **_ecvt** function converts a floating-point number to a character string. The *value* parameter is the floating-point number to be converted. This function stores up to *count* digits of *value* as a string and appends a null character ('\0'). If the number of digits in *value* exceeds *count*, the low-order digit is rounded. If there are fewer than *count* digits, the string is padded with zeros. +The **`_ecvt`** function converts a floating-point number to a character string. The *`value`* parameter is the floating-point number to be converted. This function stores up to *`count`* digits of *`value`* as a string and appends a null character ('\0'). If the number of digits in *`value`* exceeds *`count`*, the low-order digit is rounded. If there are fewer than *`count`* digits, the string is padded with zeros. -The total number of digits returned by **_ecvt** will not exceed **_CVTBUFSIZE**. +The total number of digits returned by **`_ecvt`** won't exceed `_CVTBUFSIZE`. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and *sign* after the call. The *dec* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *sign* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *`sign`* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. -The difference between **_ecvt** and **_fcvt** is in the interpretation of the *count* parameter. **_ecvt** interprets *count* as the total number of digits in the output string, whereas **_fcvt** interprets *count* as the number of digits after the decimal point. +The difference between **`_ecvt`** and `_fcvt` is in the interpretation of the *`count`* parameter. **`_ecvt`** interprets *`count`* as the total number of digits in the output string, whereas `_fcvt` interprets *`count`* as the number of digits after the decimal point. -**_ecvt** and **_fcvt** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the result of the previous call. +**`_ecvt`** and `_fcvt` use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the result of the previous call. -This function validates its parameters. If *dec* or *sign* is **NULL**, or *count* is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and **NULL** is returned. +This function validates its parameters. If *`dec`* or *`sign`* is `NULL`, or *`count`* is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to **EINVAL,** and `NULL` is returned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_ecvt**|\| +| Function | Required header | +|---|---| +| **`_ecvt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,8 +98,8 @@ source: 3.1415926535 buffer: '3141592654' decimal: 1 sign: 0 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_fcvt](fcvt.md)
-[_gcvt](gcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md) diff --git a/docs/c-runtime-library/reference/endthread-endthreadex.md b/docs/c-runtime-library/reference/endthread-endthreadex.md index d27cde9603..c452559de3 100644 --- a/docs/c-runtime-library/reference/endthread-endthreadex.md +++ b/docs/c-runtime-library/reference/endthread-endthreadex.md @@ -3,16 +3,15 @@ description: "Learn more about: _endthread, _endthreadex" title: "_endthread, _endthreadex" ms.date: "4/2/2020" api_name: ["_endthread", "_endthreadex", "_o__endthread", "_o__endthreadex"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_endthread", "endthreadex", "_endthreadex", "endthread"] helpviewer_keywords: ["_endthread function", "endthread function", "terminating threads", "endthreadex function", "_endthreadex function", "threading [C++], terminating threads"] -ms.assetid: 18a91f2f-659e-40b4-b266-ec12dcf2abf5 --- -# _endthread, _endthreadex +# `_endthread`, `_endthreadex` -Terminates a thread; **_endthread** terminates a thread that's created by **_beginthread** and **_endthreadex** terminates a thread that's created by **_beginthreadex**. +Terminates a thread; **`_endthread`** terminates a thread that's created by **`_beginthread`** and **`_endthreadex`** terminates a thread that's created by **`_beginthreadex`**. ## Syntax @@ -25,43 +24,43 @@ void _endthreadex( ### Parameters -*retval*
+*`retval`*\ Thread exit code. ## Remarks -You can call **_endthread** or **_endthreadex** explicitly to terminate a thread; however, **_endthread** or **_endthreadex** is called automatically when the thread returns from the routine passed as a parameter to **_beginthread** or **_beginthreadex**. Terminating a thread with a call to **endthread** or **_endthreadex** helps ensure proper recovery of resources allocated for the thread. +You can call **`_endthread`** or **`_endthreadex`** explicitly to terminate a thread; however, **`_endthread`** or **`_endthreadex`** is called automatically when the thread returns from the routine passed as a parameter to **`_beginthread`** or **`_beginthreadex`**. Terminating a thread with a call to **`endthread`** or **`_endthreadex`** helps ensure proper recovery of resources allocated for the thread. > [!NOTE] -> For an executable file linked with Libcmt.lib, do not call the Win32 [ExitThread](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API; this prevents the run-time system from reclaiming allocated resources. **_endthread** and **_endthreadex** reclaim allocated thread resources and then call **ExitThread**. +> For an executable file linked with Libcmt.lib, do not call the Win32 [`ExitThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API; this prevents the run-time system from reclaiming allocated resources. **`_endthread`** and **`_endthreadex`** reclaim allocated thread resources and then call `ExitThread`. -**_endthread** automatically closes the thread handle. (This behavior differs from the Win32 **ExitThread** API.) Therefore, when you use **_beginthread** and **_endthread**, do not explicitly close the thread handle by calling the Win32 [CloseHandle](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. +**`_endthread`** automatically closes the thread handle. (This behavior differs from the Win32 `ExitThread` API.) Therefore, when you use **`_beginthread`** and **`_endthread`**, don't explicitly close the thread handle by calling the Win32 [`CloseHandle`](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. -Like the Win32 **ExitThread** API, **_endthreadex** does not close the thread handle. Therefore, when you use **_beginthreadex** and **_endthreadex**, you must close the thread handle by calling the Win32 **CloseHandle** API. +Like the Win32 `ExitThread` API, **`_endthreadex`** doesn't close the thread handle. Therefore, when you use **`_beginthreadex`** and **`_endthreadex`**, you must close the thread handle by calling the Win32 `CloseHandle` API. > [!NOTE] -> **_endthread** and **_endthreadex** cause C++ destructors pending in the thread not to be called. +> **`_endthread`** and **`_endthreadex`** cause C++ destructors pending in the thread not to be called. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_endthread**|\| -|**_endthreadex**|\| +| Function | Required header | +|---|---| +| **`_endthread`** | `` | +| **`_endthreadex`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Multithreaded versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Multithreaded versions of the [C run-time libraries](../crt-library-features.md) only. ## Example -See the example for [_beginthread](beginthread-beginthreadex.md). +See the example for [`_beginthread`](beginthread-beginthreadex.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_beginthread, _beginthreadex](beginthread-beginthreadex.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_beginthread`, `_beginthreadex`](beginthread-beginthreadex.md) diff --git a/docs/c-runtime-library/reference/eof.md b/docs/c-runtime-library/reference/eof.md index f9d6643696..ebe52efa18 100644 --- a/docs/c-runtime-library/reference/eof.md +++ b/docs/c-runtime-library/reference/eof.md @@ -3,14 +3,14 @@ description: "Learn more about: _eof" title: "_eof" ms.date: "4/2/2020" api_name: ["_eof", "_o__eof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_eof"] helpviewer_keywords: ["eof function", "end of file, testing for", "_eof function", "files [C++], end of", "testing, for end-of-file", "end of file"] ms.assetid: 265703f4-d07e-4005-abf3-b1d0cdd9e0b0 --- -# _eof +# `_eof` Tests for end of file (EOF). @@ -24,26 +24,26 @@ int _eof( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to the open file. -## Return Value +## Return value -**_eof** returns 1 if the current position is end of file, or 0 if it is not. A return value of -1 indicates an error; in this case, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EBADF**, which indicates an invalid file descriptor. +**`_eof`** returns 1 if the current position is end of file, or 0 if it isn't. A return value of -1 indicates an error; in this case, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EBADF`, which indicates an invalid file descriptor. ## Remarks -The **_eof** function determines whether the end of the file associated with *fd* has been reached. +The **`_eof`** function determines whether the end of the file associated with *`fd`* has been reached. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_eof**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_eof`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -99,9 +99,9 @@ Number of bytes read = 29 ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[clearerr](clearerr.md)
-[feof](feof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Low-level I/O](../low-level-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`feof`](feof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md b/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md index 0629a5e876..ebc5633b22 100644 --- a/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md +++ b/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md @@ -3,14 +3,14 @@ title: "erf, erff, erfl, erfc, erfcf, erfcl" description: "API reference for erf, erff, erfl, erfc, erfcf, and erfcl; which computes the error function or the complementary error function of a value." ms.date: "9/1/2020" api_name: ["erff", "erfl", "erf", "erfc", "erfcf", "erfcl", "_o_erf", "_o_erfc", "_o_erfcf", "_o_erfcl", "_o_erff", "_o_erfl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["erfl", "erf", "erff", "erfc", "erfcf", "erfcl"] helpviewer_keywords: ["erfl function", "erff function", "erf function", "erfcl function", "erfcf function", "erfc function"] ms.assetid: 144d90d3-e437-41c2-a659-cd57596023b5 --- -# erf, erff, erfl, erfc, erfcf, erfcl +# `erf`, `erff`, `erfl`, `erfc`, `erfcf`, `erfcl` Computes the error function or the complementary error function of a value. @@ -53,36 +53,36 @@ long double erfcl( ### Parameters -*x*\ +*`x`*\ A floating-point value. -## Return Value +## Return value -The **erf** functions return the Gauss error function of *x*. The **erfc** functions return the complementary Gauss error function of *x*. +The **`erf`** functions return the Gauss error function of *`x`*. The **`erfc`** functions return the complementary Gauss error function of *`x`*. ## Remarks -The **erf** functions calculate the Gauss error function of *x*, which is defined as: +The **`erf`** functions calculate the Gauss error function of *`x`*, which is defined as: ![The error function of x equals two over the square root of pi times the integral from zero to x of e to the minus t squared d t. ](media/crt_erf_formula.PNG "The error function of x") -The complementary Gauss error function is defined as 1 - erf(x). The **erf** functions return a value in the range -1.0 to 1.0. There's no error return. The **erfc** functions return a value in the range 0 to 2. If *x* is too large for **erfc**, the **errno** variable is set to **ERANGE**. +The complementary Gauss error function is defined as 1 - erf(x). The **`erf`** functions return a value in the range -1.0 to 1.0. There's no error return. The **`erfc`** functions return a value in the range 0 to 2. If *`x`* is too large for **`erfc`**, the `errno` variable is set to `ERANGE`. -Because C++ allows overloading, you can call overloads of **erf** and **erfc** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **erf** and **erfc** always take and return a **`double`**. +Because C++ allows overloading, you can call **`erf`** and **`erfc`** overloads that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`erf`** and **`erfc`** always take and return a **`double`**. -If you use the \ `erf()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `erf()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**erf**, **erff**, **erfl**, **erfc**, **erfcf**, **erfcl**|\| -|**erf** macro | \ | +| Function | Required header | +|---|---| +| **`erf`**, **`erff`**, **`erfl`**, **`erfc`**, **`erfcf`**, **`erfcl`** | \ | +| **`erf`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
+[Math and floating-point support](../floating-point-support.md) diff --git a/docs/c-runtime-library/reference/execl-wexecl.md b/docs/c-runtime-library/reference/execl-wexecl.md index b69916fb53..2d3fd94167 100644 --- a/docs/c-runtime-library/reference/execl-wexecl.md +++ b/docs/c-runtime-library/reference/execl-wexecl.md @@ -10,7 +10,7 @@ f1_keywords: ["_execl", "_wexecl", "wexecl"] helpviewer_keywords: ["_execl function", "wexecl function", "_wexecl function", "execl function"] ms.assetid: 81fefb8a-0a06-4221-b2bc-be18e38e89f4 --- -# _execl, _wexecl +# `_execl`, `_wexecl` Loads and executes new child processes. @@ -36,52 +36,52 @@ intptr_t _wexecl( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to the parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|errno value|Description| -|-----------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter (one or more of the parameters was a null pointer or empty string).| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter (one or more of the parameters was a null pointer or empty string). | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | ## Remarks Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter. The first argument is the command or executable file name, and the second argument should be the same as the first. It becomes `argv[0]` in the executed process. The third argument is the first argument, `argv[1]`, of the process being executed. -The **_execl** functions validate their parameters. If either *cmdname* or *arg0* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is executed. +The **`_execl`** functions validate their parameters. If either *`cmdname`* or *`arg0`* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md) If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execl**|\|\| -|**_wexecl**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execl`** | \ | \ | +| **`_wexecl`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execle-wexecle.md b/docs/c-runtime-library/reference/execle-wexecle.md index 01b939e874..4eebea6a6c 100644 --- a/docs/c-runtime-library/reference/execle-wexecle.md +++ b/docs/c-runtime-library/reference/execle-wexecle.md @@ -10,7 +10,7 @@ f1_keywords: ["wexecle", "_execle", "_wexecle"] helpviewer_keywords: ["wexecle function", "execle function", "_wexecle function", "_execle function"] ms.assetid: 75efa9c5-96b7-4e23-acab-06258901f63a --- -# _execle, _wexecle +# `_execle`, `_wexecle` Loads and executes new child processes. @@ -38,57 +38,57 @@ intptr_t _wexecle( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space that's required for the arguments and the environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files are open. (The specified file must be opened to determine whether it is executable.)| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process was not allocated correctly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space that's required for the arguments and the environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files are open. (The specified file must be opened to determine whether it's executable.) | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process wasn't allocated correctly. | -For more information about these return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, and passes each command-line argument as a separate parameter and passes an array of pointers to environment settings. -The **_execle** functions validate their parameters. If *cmdname* or *arg0* is a null pointer or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execle`** functions validate their parameters. If *`cmdname`* or *`arg0`* is a null pointer or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execle**|\|\| -|**_wexecle**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execle`** | \ | \ | +| **`_wexecle`** | \ or \ | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execle.md b/docs/c-runtime-library/reference/execle.md index 21af98255b..860ad2858c 100644 --- a/docs/c-runtime-library/reference/execle.md +++ b/docs/c-runtime-library/reference/execle.md @@ -10,11 +10,11 @@ f1_keywords: ["execle"] helpviewer_keywords: ["execle function"] ms.assetid: 5985b615-fe90-4d1c-9c1d-13ec87c8e306 --- -# execle +# `execle` -The Microsoft-implemented POSIX function name `execle` is a deprecated alias for the [_execle](execle-wexecle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execle` is a deprecated alias for the [`_execle`](execle-wexecle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execle](execle-wexecle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execle`](execle-wexecle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execlp-wexeclp.md b/docs/c-runtime-library/reference/execlp-wexeclp.md index 42edae9d98..f10fca130e 100644 --- a/docs/c-runtime-library/reference/execlp-wexeclp.md +++ b/docs/c-runtime-library/reference/execlp-wexeclp.md @@ -10,7 +10,7 @@ f1_keywords: ["_wexeclp", "wexeclp", "_execlp"] helpviewer_keywords: ["execlp function", "_execlp function", "_wexeclp function", "wexeclp function"] ms.assetid: 7b179163-4bcd-4d6a-8baf-68f886791928 --- -# _execlp, _wexeclp +# `_execlp`, `_wexeclp` Loads and executes new child processes. @@ -36,54 +36,54 @@ intptr_t _wexeclp( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and using the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and using the `PATH` environment variable to find the file to execute. -The **_execlp** functions validate their parameters. If *cmdname* or *arg0* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execlp`** functions validate their parameters. If *`cmdname`* or *`arg0`* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execlp**|\|\| -|**_wexeclp**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execlp`** | \ | \ | +| **`_wexeclp`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execlp.md b/docs/c-runtime-library/reference/execlp.md index fcddb73c07..969b7278bf 100644 --- a/docs/c-runtime-library/reference/execlp.md +++ b/docs/c-runtime-library/reference/execlp.md @@ -10,11 +10,11 @@ f1_keywords: ["execlp"] helpviewer_keywords: ["execlp function"] ms.assetid: 68b19143-e7b1-49c6-89b5-084d0d66de9c --- -# execlp +# `execlp` -The Microsoft-implemented POSIX function name `execlp` is a deprecated alias for the [_execlp](execlp-wexeclp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execlp` is a deprecated alias for the [`_execlp`](execlp-wexeclp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execlp](execlp-wexeclp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execlp`](execlp-wexeclp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execlpe-wexeclpe.md b/docs/c-runtime-library/reference/execlpe-wexeclpe.md index 92c2828670..486aa1d97c 100644 --- a/docs/c-runtime-library/reference/execlpe-wexeclpe.md +++ b/docs/c-runtime-library/reference/execlpe-wexeclpe.md @@ -10,7 +10,7 @@ f1_keywords: ["_wexeclpe", "wexeclpe", "_execlpe"] helpviewer_keywords: ["wexeclpe function", "_wexeclpe function", "_execlpe function", "execlpe function"] ms.assetid: 07b861da-3e7e-4f1d-bb80-ad69b55e5162 --- -# _execlpe, _wexeclpe +# `_execlpe`, `_wexeclpe` Loads and executes new child processes. @@ -38,57 +38,57 @@ intptr_t _wexeclpe( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and also passing an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and also passing an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -The **_execlpe** functions validate their parameters. If either *cmdname* or *arg0* is a null pointers or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execlpe`** functions validate their parameters. If either *`cmdname`* or *`arg0`* is a null pointers or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execlpe**|\|\| -|**_wexeclpe**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execlpe`** | \ | \ | +| **`_wexeclpe`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execlpe.md b/docs/c-runtime-library/reference/execlpe.md index 5c08778fc6..f0d113390c 100644 --- a/docs/c-runtime-library/reference/execlpe.md +++ b/docs/c-runtime-library/reference/execlpe.md @@ -10,11 +10,11 @@ f1_keywords: ["execlpe"] helpviewer_keywords: ["execlpe function"] ms.assetid: 33b28785-43e3-4971-b139-33743a7c9a32 --- -# execlpe +# `execlpe` -The Microsoft-specific function name `execlpe` is a deprecated alias for the [_execlpe](execlpe-wexeclpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `execlpe` is a deprecated alias for the [`_execlpe`](execlpe-wexeclpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execlpe](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execlpe`](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execv-wexecv.md b/docs/c-runtime-library/reference/execv-wexecv.md index 9eefcc60a5..4b11b47296 100644 --- a/docs/c-runtime-library/reference/execv-wexecv.md +++ b/docs/c-runtime-library/reference/execv-wexecv.md @@ -3,14 +3,14 @@ description: "Learn more about: _execv, _wexecv" title: "_execv, _wexecv" ms.date: "4/2/2020" api_name: ["_wexecv", "_execv", "_o__execv", "_o__wexecv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execv", "_wexecv", "wexecv"] helpviewer_keywords: ["_wexecv function", "_execv function", "wexecv function", "execv function"] ms.assetid: 8dbaf7bc-9040-4316-a0c1-db7e866b52af --- -# _execv, _wexecv +# `_execv`, `_wexecv` Loads and executes new child processes. @@ -32,56 +32,56 @@ intptr_t _wexecv( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments. -The **_execv** functions validate their parameters. If *cmdname* is a null pointer, or if *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, the **_execv** functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execv`** functions validate their parameters. If *`cmdname`* is a null pointer, or if *`argv`* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, the **`_execv`** functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No process is launched. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execv**|\|\| -|**_wexecv**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execv`** | \ | \ | +| **`_wexecv`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execv.md b/docs/c-runtime-library/reference/execv.md index 423925a59d..248b1cfd9b 100644 --- a/docs/c-runtime-library/reference/execv.md +++ b/docs/c-runtime-library/reference/execv.md @@ -10,11 +10,11 @@ f1_keywords: ["execv"] helpviewer_keywords: ["execv function"] ms.assetid: b097d606-9384-427a-9a1d-707dc4ce03ae --- -# execv +# `execv` -The Microsoft-implemented POSIX function name `execv` is a deprecated alias for the [_execv](execv-wexecv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execv` is a deprecated alias for the [`_execv`](execv-wexecv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execv](execv-wexecv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execv`](execv-wexecv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execve-wexecve.md b/docs/c-runtime-library/reference/execve-wexecve.md index 2134987b05..e1561aefbc 100644 --- a/docs/c-runtime-library/reference/execve-wexecve.md +++ b/docs/c-runtime-library/reference/execve-wexecve.md @@ -3,14 +3,14 @@ description: "Learn more about: _execve, _wexecve" title: "_execve, _wexecve" ms.date: "4/2/2020" api_name: ["_execve", "_wexecve", "_o__execve", "_o__wexecve"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wexecve", "_wexecve", "_execve"] helpviewer_keywords: ["execve function", "wexecve function", "_execve function", "_wexecve function"] ms.assetid: 950d4802-a9c3-4f32-8145-a0119dd1d596 --- -# _execve, _wexecve +# `_execve`, `_wexecve` Loads and executes new child processes. @@ -34,59 +34,65 @@ intptr_t _wexecve( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and an array of pointers to environment settings. -**_execve** and **_wexecve** validate their parameters. If *cmdname* is a null pointer, or if *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +**`_execve`** and **`_wexecve`** validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execve**|\|\| -|**_wexecve**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execve`** | \ | \ | +| **`_wexecve`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execve.md b/docs/c-runtime-library/reference/execve.md index 7764e132c8..a0b1293907 100644 --- a/docs/c-runtime-library/reference/execve.md +++ b/docs/c-runtime-library/reference/execve.md @@ -10,11 +10,11 @@ f1_keywords: ["execve"] helpviewer_keywords: ["execve function"] ms.assetid: f28aabe4-fd76-422e-a0e4-80864736d245 --- -# execve +# `execve` -The Microsoft-implemented POSIX function name `execve` is a deprecated alias for the [_execve](execve-wexecve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execve` is a deprecated alias for the [`_execve`](execve-wexecve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execve](execve-wexecve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execve`](execve-wexecve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execvp-wexecvp.md b/docs/c-runtime-library/reference/execvp-wexecvp.md index 55228ac845..1236bc4ff4 100644 --- a/docs/c-runtime-library/reference/execvp-wexecvp.md +++ b/docs/c-runtime-library/reference/execvp-wexecvp.md @@ -3,14 +3,14 @@ description: "Learn more about: _execvp, _wexecvp" title: "_execvp, _wexecvp" ms.date: "4/2/2020" api_name: ["_execvp", "_wexecvp", "_o__execvp", "_o__wexecvp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execvp", "wexecvp", "_wexecvp"] helpviewer_keywords: ["_execvp function", "_wexecvp function", "wexecvp function", "execvp function"] ms.assetid: a4db15df-b204-4987-be7c-de84c3414380 --- -# _execvp, _wexecvp +# `_execvp`, `_wexecvp` Loads and executes new child processes. @@ -32,56 +32,62 @@ intptr_t _wexecvp( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and using the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and using the `PATH` environment variable to find the file to execute. -The **_execvp** functions validate their parameters. If the *cmdname* is a null pointer, or *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execvp`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execvp**|\|\| -|**_wexecvp**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execvp`** | \ | \ | +| **`_wexecvp`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execvp.md b/docs/c-runtime-library/reference/execvp.md index 8a7a40a488..4306af58b8 100644 --- a/docs/c-runtime-library/reference/execvp.md +++ b/docs/c-runtime-library/reference/execvp.md @@ -10,11 +10,11 @@ f1_keywords: ["execvp"] helpviewer_keywords: ["execvp function"] ms.assetid: a0d0e898-9f06-4aa9-94ce-3ad317318c3a --- -# execvp +# `execvp` -The Microsoft-implemented POSIX function name `execvp` is a deprecated alias for the [_execvp](execvp-wexecvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execvp` is a deprecated alias for the [`_execvp`](execvp-wexecvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execvp](execvp-wexecvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execvp`](execvp-wexecvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execvpe-wexecvpe.md b/docs/c-runtime-library/reference/execvpe-wexecvpe.md index c563d386c5..84548d549e 100644 --- a/docs/c-runtime-library/reference/execvpe-wexecvpe.md +++ b/docs/c-runtime-library/reference/execvpe-wexecvpe.md @@ -3,14 +3,14 @@ description: "Learn more about: _execvpe, _wexecvpe" title: "_execvpe, _wexecvpe" ms.date: "4/2/2020" api_name: ["_execvpe", "_wexecvpe", "_o__execvpe", "_o__wexecvpe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wexecvpe", "_wexecvpe", "_execvpe"] helpviewer_keywords: ["wexecvpe function", "execvpe function", "_wexecvpe function", "_execvpe function"] ms.assetid: c0c3c986-d9c0-4814-a96c-10f0b3092766 --- -# _execvpe, _wexecvpe +# `_execvpe`, `_wexecvpe` Loads and runs new child processes. @@ -34,58 +34,64 @@ intptr_t _wexecvpe( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space that's required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EMFILE**|Too many files are open. (The specified file must be opened to determine whether it is executable.)| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process was not allocated correctly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space that's required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EMFILE` | Too many files are open. (The specified file must be opened to determine whether it's executable.) | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process wasn't allocated correctly. | -For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, and passes an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, and passes an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -The **_execvpe** functions validate their parameters. If the *cmdname* is a null pointer, or if *argv* is a null pointer, a pointer to an empty array, or a pointer to an array that contains an empty string as the first argument, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execvpe`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execvpe**|\|\| -|**_wexecvpe**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execvpe`** | \ | \ | +| **`_wexecvpe`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execvpe.md b/docs/c-runtime-library/reference/execvpe.md index 979b2276ed..5ecc936112 100644 --- a/docs/c-runtime-library/reference/execvpe.md +++ b/docs/c-runtime-library/reference/execvpe.md @@ -10,11 +10,11 @@ f1_keywords: ["execvpe"] helpviewer_keywords: ["execvpe function"] ms.assetid: ee657071-c459-4bb6-82a2-8925c888f624 --- -# execvpe +# `execvpe` -The Microsoft-specific function name `execvpe` is a deprecated alias for the [_execvpe](execvpe-wexecvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `execvpe` is a deprecated alias for the [`_execvpe`](execvpe-wexecvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execvpe](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execvpe`](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/exit-exit-exit.md b/docs/c-runtime-library/reference/exit-exit-exit.md index 01e0c7cd8e..bcec154714 100644 --- a/docs/c-runtime-library/reference/exit-exit-exit.md +++ b/docs/c-runtime-library/reference/exit-exit-exit.md @@ -3,7 +3,7 @@ description: "Learn more about: exit, _Exit, _exit" title: "exit, _Exit, _exit" ms.date: "4/2/2020" api_name: ["_exit", "exit", "_o__exit", "_o_exit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["Exit", "_exit", "process/exit", "process/_Exit", "stdlib/exit", "stdlib/_Exit"] @@ -14,7 +14,7 @@ helpviewer_keywords: ["exit function", "_exit function", "processes, terminating Terminates the calling process. The **`exit`** function terminates it after cleanup; **`_exit`** and **`_Exit`** terminate it immediately. > [!NOTE] -> Do not use this method to shut down a Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP App lifecycle](/windows/uwp/launch-resume/app-lifecycle). For more information about UWP apps, see [Universal Windows Platform documentation](https://developer.microsoft.com/windows/apps). +> Do not use this method to shut down a Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). For more information about UWP apps, see [Universal Windows Platform documentation](https://developer.microsoft.com/windows/apps). ## Syntax @@ -32,27 +32,27 @@ void _exit( ### Parameters -*`status`*
+*`status`*\ Exit status code. ## Remarks The **`exit`**, **`_Exit`** and **`_exit`** functions terminate the calling process. The **`exit`** function calls destructors for thread-local objects, then calls—in last-in-first-out (LIFO) order—the functions that are registered by **`atexit`** and **`_onexit`**, and then flushes all file buffers before it terminates the process. The **`_Exit`** and **`_exit`** functions terminate the process without destroying thread-local objects or processing **`atexit`** or **`_onexit`** functions, and without flushing stream buffers. -Although the **`exit`**, **`_Exit`** and **`_exit`** calls do not return a value, the value in *`status`* is made available to the host environment or waiting calling process, if one exists, after the process exits. Typically, the caller sets the *`status`* value to 0 to indicate a normal exit, or to some other value to indicate an error. The *`status`* value is available to the operating-system batch command **`ERRORLEVEL`** and is represented by one of two constants: **`EXIT_SUCCESS`**, which represents a value of 0, or **`EXIT_FAILURE`**, which represents a value of 1. +Although the **`exit`**, **`_Exit`** and **`_exit`** calls don't return a value, the value in *`status`* is made available to the host environment or waiting calling process, if one exists, after the process exits. Typically, the caller sets the *`status`* value to 0 to indicate a normal exit, or to some other value to indicate an error. The *`status`* value is available to the operating-system batch command `ERRORLEVEL` and is represented by one of two constants: `EXIT_SUCCESS`, which represents a value of 0, or `EXIT_FAILURE`, which represents a value of 1. The **`exit`**, **`_Exit`**, **`_exit`**, **`quick_exit`**, **`_cexit`**, and **`_c_exit`** functions behave as follows. -|Function|Description| -|--------------|-----------------| -|**`exit`**|Performs complete C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_Exit`**|Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_exit`**|Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`quick_exit`**|Performs quick C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_cexit`**|Performs complete C library termination procedures and returns to the caller. Does not terminate the process.| -|**`_c_exit`**|Performs minimal C library termination procedures and returns to the caller. Does not terminate the process.| +| Function | Description | +|---|---| +| **`exit`** | Performs complete C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_Exit`** | Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_exit`** | Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`quick_exit`** | Performs quick C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_cexit`** | Performs complete C library termination procedures and returns to the caller. Doesn't terminate the process. | +| **`_c_exit`** | Performs minimal C library termination procedures and returns to the caller. Doesn't terminate the process. | -When you call the **`exit`**, **`_Exit`** or **`_exit`** function, the destructors for any temporary or automatic objects that exist at the time of the call are not called. An automatic object is a non-static local object defined in a function. A temporary object is an object that's created by the compiler, such as a value returned by a function call. To destroy an automatic object before you call **`exit`**, **`_Exit`**, or **`_exit`**, explicitly call the destructor for the object, as shown here: +When you call the **`exit`**, **`_Exit`** or **`_exit`** function, the destructors for any temporary or automatic objects that exist at the time of the call aren't called. An automatic object is a non-static local object defined in a function. A temporary object is an object that's created by the compiler, such as a value returned by a function call. To destroy an automatic object before you call **`exit`**, **`_Exit`**, or **`_exit`**, explicitly call the destructor for the object, as shown here: ```cpp void last_fn() {} @@ -63,17 +63,17 @@ void last_fn() {} } ``` -Do not use **`DLL_PROCESS_ATTACH`** to call **`exit`** from **`DllMain`**. To exit the **`DLLMain`** function, return **`FALSE`** from **`DLL_PROCESS_ATTACH`**. +Don't use `DLL_PROCESS_ATTACH` to call **`exit`** from `DllMain`. To exit the `DLLMain` function, return `FALSE` from `DLL_PROCESS_ATTACH`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`exit`**, **`_Exit`**, **`_exit`**|`` or ``| +| Function | Required header | +|---|---| +| **`exit`**, **`_Exit`**, **`_exit`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,12 +92,12 @@ int main( void ) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`abort`](abort.md)
-[`atexit`](atexit.md)
-[`_cexit`, `_c_exit`](cexit-c-exit.md)
-[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)
-[`_onexit`, `_onexit_m`](onexit-onexit-m.md)
-[`quick_exit`](quick-exit1.md)
-[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[`system`, `_wsystem`](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_cexit`, `_c_exit`](cexit-c-exit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`quick_exit`](quick-exit1.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/exp-expf.md b/docs/c-runtime-library/reference/exp-expf.md index e96a61e96c..ca4498aea0 100644 --- a/docs/c-runtime-library/reference/exp-expf.md +++ b/docs/c-runtime-library/reference/exp-expf.md @@ -3,7 +3,7 @@ title: "exp, expf, expl" description: "API reference for exp, expf, and expl; which calculate the exponential." ms.date: "1/15/2021" api_name: ["expf", "expl", "exp", "_o_exp", "_o_expf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_expl", "expf", "expl", "exp"] @@ -39,16 +39,16 @@ long double expl( *`x`*\ The floating-point value to exponentiate the natural logarithm base *e* by. -## Return Value +## Return value The **`exp`** functions return the exponential value of the floating-point parameter, *`x`*, if successful. That is, the result is *e**`x`*, where *e* is the base of the natural logarithm. On overflow, the function returns `INF` (infinity) and on underflow, **`exp`** returns 0. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± Quiet NaN, indeterminate|None|`_DOMAIN`| -|± Infinity|`INVALID`|`_DOMAIN`| -|x ≥ 7.097827e+002|`INEXACT+OVERFLOW`|`OVERFLOW`| -|X ≤ -7.083964e+002|`INEXACT+UNDERFLOW`|`UNDERFLOW`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± Quiet NaN, indeterminate | None | `_DOMAIN` | +| ± Infinity | `INVALID` | `_DOMAIN` | +| *`x`* ≥ 7.097827e+002 | `INEXACT`+`OVERFLOW` | `OVERFLOW` | +| *`x`* ≤ -7.083964e+002 | `INEXACT`+`UNDERFLOW` | `UNDERFLOW` | The **`exp`** function has an implementation that uses Streaming SIMD Extensions 2 (SSE2). See [`_set_SSE2_enable`](set-sse2-enable.md) for information and restrictions on using the SSE2 implementation. @@ -56,18 +56,18 @@ The **`exp`** function has an implementation that uses Streaming SIMD Extensions C++ allows overloading, so you can call overloads of **`exp`** that take a **`float`** or **`long double`** argument. In a C program, unless you're using the `` macro to call this function, **`exp`** always takes and returns a **`double`**. -If you use the `` `exp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `exp` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|---------------------|---| -|**`exp`**, **`expf`**, **`expl`**|``|`` or ``| -|**`exp`** macro| `` || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`exp`**, **`expf`**, **`expl`** | `` | `` or `` | +| **`exp`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,6 +92,6 @@ exp( 2.302585 ) = 10.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`log, logf, log10, log10f`](log-logf-log10-log10f.md)\ -[`_CIexp`](../../c-runtime-library/ciexp.md) +[Math and floating-point support](../floating-point-support.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ +[`_CIexp`](../ciexp.md) diff --git a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md index 8d1792c2aa..bf7a2e2893 100644 --- a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md +++ b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md @@ -3,14 +3,13 @@ title: "exp2, exp2f, exp2l" description: "API ref for exp2(), exp2f(), and exp2l() which compute 2 raised to the specified value." ms.date: "9/1/2020" api_name: ["exp2", "exp2f", "exp2l", "_o_exp2", "_o_exp2f", "_o_exp2l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["exp2", "math/exp2", "exp2f", "math/exp2f", "exp2l", "math/exp2l"] helpviewer_keywords: ["exp2 function", "exp2f function", "exp2l function"] -ms.assetid: 526e3e10-201a-4610-a886-533f44ece344 --- -# exp2, exp2f, exp2l +# `exp2`, `exp2f`, `exp2l` Computes 2 raised to the specified value. @@ -41,43 +40,43 @@ long double exp2l( ### Parameters -*x*\ +*`x`*\ The value of the exponent. -## Return Value +## Return value -If successful, returns the base-2 exponent of *x*, that is, 2x. Otherwise, it returns one of the following values: +If successful, returns the base-2 exponent of *`x`*, that is, 2x. Otherwise, it returns one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±0|1| -|*x* = -INFINITY|+0| -|*x* = +INFINITY|+INFINITY| -|*x* = NaN|NaN| -|Overflow range error|+HUGE_VAL, +HUGE_VALF, or +HUGE_VALL| -|Underflow range error|Correct result, after rounding| +| Issue | Return | +|---|---| +| *`x`* = ±0 | 1 | +| *`x`* = -INFINITY | +0 | +| *`x`* = +INFINITY | +INFINITY | +| *`x`* = NaN | NaN | +| Overflow range error | +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL | +| Underflow range error | Correct result, after rounding | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **exp2** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **exp2** always takes and returns a **`double`**, unless you use the macro in \. +Because C++ allows overloading, you can call overloads of **`exp2`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`exp2`** always takes and returns a **`double`**, unless you use the macro in \. -If you use the \ `exp2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `exp2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**exp2**, **expf2**, **expl2**|\|\| -|**exp2** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`exp2`**, **`expf2`**, **`expl2`** | \ | \ | +| **`exp2`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[exp, expf, expl](exp-expf.md)
-[log2, log2f, log2l](log2-log2f-log2l.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`log2`, `log2f`, `log2l`](log2-log2f-log2l.md) diff --git a/docs/c-runtime-library/reference/expand-dbg.md b/docs/c-runtime-library/reference/expand-dbg.md index ead55af3a4..5998a4195c 100644 --- a/docs/c-runtime-library/reference/expand-dbg.md +++ b/docs/c-runtime-library/reference/expand-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["expand_dbg", "_expand_dbg"] helpviewer_keywords: ["memory blocks, changing size", "expand_dbg function", "_expand_dbg function"] ms.assetid: dc58c91f-72a8-48c6-b643-fe130fb6c1fd --- -# _expand_dbg +# `_expand_dbg` Resizes a specified block of memory in the heap by expanding or contracting the block (debug version only). @@ -22,56 +22,56 @@ void *_expand_dbg( size_t newSize, int blockType, const char *filename, - int linenumber + int lineNumber ); ``` ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*newSize*
+*`newSize`*\ Requested new size for the block (in bytes). -*blockType*
-Requested type for resized block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type for resized block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested expand operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested expand operation or `NULL`. -*linenumber*
-Line number in the source file where the expand operation was requested or **NULL**. +*`lineNumber`*\ +Line number in the source file where the expand operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_expand_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`lineNumber`* parameters are only available when **`_expand_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, **_expand_dbg** returns a pointer to the resized memory block. Because the memory is not moved, the address is the same as the userData. If an error occurred or the block could not be expanded to the requested size, it returns **NULL**. If a failure occurs, **errno** is with information from the operating system about the nature of the failure. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +On successful completion, **`_expand_dbg`** returns a pointer to the resized memory block. Because the memory isn't moved, the address is the same as the userData. If an error occurred or the block couldn't be expanded to the requested size, it returns `NULL`. If a failure occurs, `errno` is with information from the operating system about the nature of the failure. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_expand_dbg** function is a debug version of the _[expand](expand.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_expand_dbg** is reduced to a call to **_expand**. Both **_expand** and **_expand_dbg** resize a memory block in the base heap, but **_expand_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +The **`_expand_dbg`** function is a debug version of the _[`expand`](expand.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_expand_dbg`** is reduced to a call to `_expand`. Both `_expand` and **`_expand_dbg`** resize a memory block in the base heap, but **`_expand_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`lineNumber`* information to determine the origin of allocation requests. -**_expand_dbg** resizes the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The resize is accomplished by either expanding or contracting the original memory block. **_expand_dbg** does not move the memory block, as does the [_realloc_dbg](realloc-dbg.md) function. +**`_expand_dbg`** resizes the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The resize is accomplished by either expanding or contracting the original memory block. **`_expand_dbg`** doesn't move the memory block, as does the [`_realloc_dbg`](realloc-dbg.md) function. -When *newSize* is greater than the original block size, the memory block is expanded. During an expansion, if the memory block cannot be expanded to accommodate the requested size, **NULL** is returned. When *newSize* is less than the original block size, the memory block is contracted until the new size is obtained. +When *`newSize`* is greater than the original block size, the memory block is expanded. During an expansion, if the memory block can't be expanded to accommodate the requested size, `NULL` is returned. When *`newSize`* is less than the original block size, the memory block is contracted until the new size is obtained. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). -This function validates its parameters. If *memblock* is a null pointer, or if size is greater than **_HEAP_MAXREQ**, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. +This function validates its parameters. If *`userData`* is a null pointer, or if size is greater than `_HEAP_MAXREQ`, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_expand_dbg**|\| +| Routine | Required header | +|---|---| +| **`_expand_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -132,5 +132,5 @@ The output of this program depends on your computer's ability to expand all the ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/expand.md b/docs/c-runtime-library/reference/expand.md index 19f6f3d7dc..dfcbe00e56 100644 --- a/docs/c-runtime-library/reference/expand.md +++ b/docs/c-runtime-library/reference/expand.md @@ -3,14 +3,14 @@ description: "Learn more about: _expand" title: "_expand" ms.date: "4/2/2020" api_name: ["_expand", "_o__expand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_bexpand", "fexpand", "expand", "nexpand", "_fexpand", "_nexpand", "bexpand", "_expand"] helpviewer_keywords: ["memory blocks, changing size", "_expand function", "expand function"] ms.assetid: 4ac55410-39c8-45c7-bccd-3f1042ae2ed3 --- -# _expand +# `_expand` Changes the size of a memory block. @@ -25,42 +25,42 @@ void *_expand( ### Parameters -*memblock*
+*`memblock`*\ Pointer to previously allocated memory block. -*size*
+*`size`*\ New size in bytes. -## Return Value +## Return value -**_expand** returns a void pointer to the reallocated memory block. **_expand**, unlike **realloc**, cannot move a block to change its size. Thus, if there is sufficient memory available to expand the block without moving it, the *memblock* parameter to **_expand** is the same as the return value. +**`_expand`** returns a void pointer to the reallocated memory block. **`_expand`**, unlike `realloc`, can't move a block to change its size. Thus, if there's sufficient memory available to expand the block without moving it, the *`memblock`* parameter to **`_expand`** is the same as the return value. -**_expand** returns **NULL** when an error is detected during its operation. For example, if **_expand** is used to shrink a memory block, it might detect corruption in the small block heap or an invalid block pointer and return **NULL**. +**`_expand`** returns `NULL` when an error is detected during its operation. For example, if **`_expand`** is used to shrink a memory block, it might detect corruption in the small block heap or an invalid block pointer and return `NULL`. -If there is insufficient memory available to expand the block to the given size without moving it, the function returns **NULL**. **_expand** never returns a block expanded to a size less than requested. If a failure occurs, **errno** indicates the nature of the failure. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If there isn't sufficient memory available to expand the block without moving it, the function returns `NULL`. **`_expand`** never returns a block expanded to a size less than requested. If a failure occurs, `errno` indicates the nature of the failure. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To check the new size of the item, use **_msize**. To get a pointer to a type other than **`void`**, use a type cast on the return value. +The return value points to a storage space that is suitably aligned for storage of any type of object. To check the new size of the item, use `_msize`. To get a pointer to a type other than **`void`**, use a type cast on the return value. ## Remarks -The **_expand** function changes the size of a previously allocated memory block by trying to expand or contract the block without moving its location in the heap. The *memblock* parameter points to the beginning of the block. The *size* parameter gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes. *memblock* should not be a block that has been freed. +The **`_expand`** function changes the size of a previously allocated memory block by trying to expand or contract the block without moving its location in the heap. The *`memblock`* parameter points to the beginning of the block. The *`size`* parameter gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes. *`memblock`* shouldn't be a block that has been freed. > [!NOTE] -> On 64-bit platforms, **_expand** might not contract the block if the new size is less than the current size; in particular, if the block was less than 16K in size and therefore allocated in the Low Fragmentation Heap, **_expand** leaves the block unchanged and returns *memblock*. +> On 64-bit platforms, **`_expand`** might not contract the block if the new size is less than the current size; in particular, if the block was less than 16K in size and therefore allocated in the Low Fragmentation Heap, **`_expand`** leaves the block unchanged and returns *`memblock`*. -When the application is linked with a debug version of the C run-time libraries, **_expand** resolves to [_expand_dbg](expand-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_expand`** resolves to [`_expand_dbg`](expand-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -This function validates its parameters. If *memblock* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. If *size* is greater than **_HEAP_MAXREQ**, **errno** is set to **ENOMEM** and the function returns **NULL**. +This function validates its parameters. If *`memblock`* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. If *`size`* is greater than `_HEAP_MAXREQ`, `errno` is set to `ENOMEM`, and the function returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_expand**|\| +| Function | Required header | +|---|---| +| **`_expand`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,9 +98,9 @@ Expanded block to 1024 bytes at 002C12BC ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[malloc](malloc.md)
-[_msize](msize.md)
-[realloc](realloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`malloc`](malloc.md)\ +[`_msize`](msize.md)\ +[`realloc`](realloc.md) diff --git a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md index 341686e3f5..838790997c 100644 --- a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md +++ b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md @@ -10,7 +10,7 @@ f1_keywords: ["expm1l", "expm1", "expm1f"] helpviewer_keywords: ["expm1f function", "expm1l function", "expm1 function"] ms.assetid: 2a4dd2d9-370c-42b0-9067-0625efa272e0 --- -# expm1, expm1f, expm1l +# `expm1`, `expm1f`, `expm1l` Computes the base-e exponential of a value, minus one. @@ -37,30 +37,30 @@ long double expm1l( ### Parameters -*x*\ +*`x`*\ The floating-point exponential value. -## Return Value +## Return value -The **expm1** functions return a floating-point value that represents ex - 1, if successful. On overflow, **expm1** returns **HUGE_VAL**, **expm1f** returns **HUGE_VALF**, **expm1l** returns **HUGE_VALL**, and **errno** is set to **ERANGE**. For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +The **`expm1`** functions return a floating-point value that represents ex - 1, if successful. On overflow, **`expm1`** returns `HUGE_VAL`, **`expm1f`** returns `HUGE_VALF`, **`expm1l`** returns `HUGE_VALL`, and `errno` is set to `ERANGE`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **expm1** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **expm1** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`expm1`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`expm1`** always takes and returns a **`double`**. -If you use the \ `expm1()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `expm1()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**expm1**, **expm1f**, **expm1l**|\| -|**expm1** macro | \ | +| Routine | Required header | +|---|---| +| **`expm1`**, **`expm1f`**, **`expm1l`** | \ | +| **`expm1`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[exp2, exp2f, exp2l](exp2-exp2f-exp2l.md)
-[pow, powf, powl](pow-powf-powl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`exp2`, `exp2f`, `exp2l`](exp2-exp2f-exp2l.md)\ +[`pow`, `powf`, `powl`](pow-powf-powl.md) diff --git a/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md b/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md index b753e77b83..99d52e6c87 100644 --- a/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md +++ b/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md @@ -3,7 +3,7 @@ title: "fabs, fabsf, fabsl" description: "API reference for fabs, fabsf, and fabsl; which calculate the absolute value of a floating-point value." ms.date: "1/15/2021" api_name: ["fabsf", "fabs", "fabsl", "_o_fabs", "_o_fabsf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fabs", "fabsf", "fabsl", "math\fabs", "math\fabsf", "math\fabsl"] @@ -40,30 +40,30 @@ long double fabsl( *`x`*\ Floating-point value. -## Return Value +## Return value -The **`fabs`** functions return the absolute value of the argument *x*. There's no error return. +The **`fabs`** functions return the absolute value of the argument *`x`*. There's no error return. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks C++ allows overloading, so you can call overloads of **`fabs`** if you include the `` header. In a C program, unless you're using the `` macro to call this function, **`fabs`** always takes and returns a **`double`**. -If you use the `` `fabs()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `fabs` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|-----------------------|---------------------------| -|**`fabs`**, **`fabsf`**, **`fabsl`**|``|`` or ``| -|**`fabs`** macro | `` || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`fabs`**, **`fabsf`**, **`fabsl`** | `` | `` or `` | +| **`fabs`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -71,6 +71,6 @@ See the example for [`abs`](abs-labs-llabs-abs64.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`abs, labs, llabs, _abs64`](abs-labs-llabs-abs64.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md)\ [`_cabs`](cabs.md) diff --git a/docs/c-runtime-library/reference/fclose-fcloseall.md b/docs/c-runtime-library/reference/fclose-fcloseall.md index ce33a4ec76..5f0cee23e6 100644 --- a/docs/c-runtime-library/reference/fclose-fcloseall.md +++ b/docs/c-runtime-library/reference/fclose-fcloseall.md @@ -3,16 +3,15 @@ description: "Learn more about: fclose, _fcloseall" title: "fclose, _fcloseall" ms.date: "4/2/2020" api_name: ["fclose", "_fcloseall", "_o__fcloseall", "_o_fclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fclose", "_fcloseall"] helpviewer_keywords: ["fclose function", "streams, closing", "_fcloseall function"] -ms.assetid: c3c6ea72-92c6-450a-a33e-3e568d2784a4 --- -# fclose, _fcloseall +# `fclose`, `_fcloseall` -Closes a stream (**fclose**) or closes all open streams (**_fcloseall**). +Closes a stream (**`fclose`**) or closes all open streams (**`_fcloseall`**). ## Syntax @@ -25,45 +24,46 @@ int _fcloseall( void ); ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**fclose** returns 0 if the stream is successfully closed. **_fcloseall** returns the total number of streams closed. Both functions return **EOF** to indicate an error. +**`fclose`** returns 0 if the stream is successfully closed. **`_fcloseall`** returns the total number of streams closed. Both functions return `EOF` to indicate an error. ## Remarks -The **fclose** function closes *stream*. If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **fclose** sets **errno** to **EINVAL** and returns **EOF**. It is recommended that the *stream* pointer always be checked prior to calling this function. +The **`fclose`** function closes *`stream`*. If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`fclose`** sets `errno` to `EINVAL` and returns `EOF`. It's recommended that you always check the *`stream`* pointer before you call this function. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The **_fcloseall** function closes all open streams except **stdin**, **stdout**, **stderr** (and, in MS-DOS, **_stdaux** and **_stdprn**). It also closes and deletes any temporary files created by **tmpfile**. In both functions, all buffers associated with the stream are flushed prior to closing. System-allocated buffers are released when the stream is closed. Buffers assigned by the user with **setbuf** and **setvbuf** are not automatically released. +The **`_fcloseall`** function closes all open streams except **`stdin`**, **`stdout`**, **`stderr`** (and, in MS-DOS, **`_stdaux`** and **`_stdprn`**). It also closes and deletes any temporary files created by **`tmpfile`**. In both functions, all buffers associated with the stream are flushed prior to closing. System-allocated buffers are released when the stream is closed. Buffers assigned by the user with **`setbuf`** and **`setvbuf`** aren't automatically released. -**Note:** When these functions are used to close a stream, the underlying file descriptor and OS file handle (or socket) are closed, as well as the stream. Thus, if the file was originally opened as a file handle or file descriptor and is closed with **fclose**, do not also call **_close** to close the file descriptor; do not call the Win32 function **CloseHandle** to close the file handle. +> [!NOTE] +> When `fclose` or `_fcloseall` functions are used to close a stream, the underlying file descriptor and OS file handle (or socket) are closed as well. Thus, if the file was originally opened as a file handle or file descriptor and is closed with **`fclose`**, don't also call **`_close`** to close the file descriptor; and don't call the Win32 function `CloseHandle` to close the file handle. -**fclose** and **_fcloseall** include code to protect against interference from other threads. For non-locking version of a **fclose**, see **_fclose_nolock**. +**`fclose`** and **`_fcloseall`** include code to protect against interference from other threads. For non-locking version of a **`fclose`**, see **`_fclose_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fclose**|\| -|**_fcloseall**|\| +| Function | Required header | +|---|---| +| **`fclose`** | `` | +| **`_fcloseall`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [fopen](fopen-wfopen.md). +See the example for [`fopen`](fopen-wfopen.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_close](close.md)
-[_fdopen, _wfdopen](fdopen-wfdopen.md)
-[fflush](fflush.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[freopen, _wfreopen](freopen-wfreopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`_close`](close.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`fflush`](fflush.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md) diff --git a/docs/c-runtime-library/reference/fclose-nolock.md b/docs/c-runtime-library/reference/fclose-nolock.md index 6a511f90e1..b03860a277 100644 --- a/docs/c-runtime-library/reference/fclose-nolock.md +++ b/docs/c-runtime-library/reference/fclose-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fclose_nolock" title: "_fclose_nolock" +description: "Learn more about: _fclose_nolock" ms.date: "4/2/2020" api_name: ["_fclose_nolock", "_o__fclose_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fclose_nolock", "_fclose_nolock"] helpviewer_keywords: ["streams, closing", "fclose_nolock function", "_fclose_nolock function"] -ms.assetid: b4af4392-5fc8-49bb-9fe2-ca7293d3ce04 --- -# _fclose_nolock +# `_fclose_nolock` -Closes a stream without thread-locking. +Closes a stream without locking. ## Syntax @@ -24,32 +23,32 @@ int _fclose_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -**fclose** returns 0 if the stream is successfully closed. Returns **EOF** to indicate an error. +**`_fclose_nolock`** returns 0 if the stream is successfully closed. Returns `EOF` to indicate an error. ## Remarks -This functions is a non-locking version of **fclose**. It is identical except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fclose`. It's identical except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fclose_nolock**|\| +| Function | Required header | +|---|---| +| **`_fclose_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_close](close.md)
-[_fdopen, _wfdopen](fdopen-wfdopen.md)
-[fflush](fflush.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[freopen, _wfreopen](freopen-wfreopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`_close`](close.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`fflush`](fflush.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md) diff --git a/docs/c-runtime-library/reference/fcloseall.md b/docs/c-runtime-library/reference/fcloseall.md index 660bcd0651..26e96ee80b 100644 --- a/docs/c-runtime-library/reference/fcloseall.md +++ b/docs/c-runtime-library/reference/fcloseall.md @@ -10,8 +10,8 @@ f1_keywords: ["fcloseall"] helpviewer_keywords: ["fcloseall function"] ms.assetid: 4f14acde-5bc5-43da-a709-7a3c559df3cf --- -# fcloseall +# `fcloseall` -The Microsoft-specific function name `fcloseall` is a deprecated alias for the [_fcloseall](fclose-fcloseall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fcloseall` is a deprecated alias for the [`_fcloseall`](fclose-fcloseall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fcloseall](fclose-fcloseall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fcloseall`](fclose-fcloseall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fcvt-s.md b/docs/c-runtime-library/reference/fcvt-s.md index f6a9fc80aa..bb29897a97 100644 --- a/docs/c-runtime-library/reference/fcvt-s.md +++ b/docs/c-runtime-library/reference/fcvt-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _fcvt_s" title: "_fcvt_s" ms.date: "4/2/2020" api_name: ["_fcvt_s", "_o__fcvt_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fcvt_s", "_fcvt_s"] helpviewer_keywords: ["fcvt_s function", "converting floating point, to strings", "floating-point functions, converting number to string", "_fcvt_s function"] ms.assetid: 48671197-1d29-4c2b-a5d8-d2368f5f68a1 --- -# _fcvt_s +# `_fcvt_s` -Converts a floating-point number to a string. This is a version of [_fcvt](fcvt.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a floating-point number to a string. This function is a version of [`_fcvt`](fcvt.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,68 +37,68 @@ errno_t _fcvt_s( ### Parameters -*buffer*
+*`buffer`*\ The supplied buffer that will hold the result of the conversion. -*sizeInBytes*
+*`sizeInBytes`*\ The size of the buffer in bytes. -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits after the decimal point. -*dec*
+*`dec`*\ Pointer to the stored decimal-point position. -*sign*
+*`sign`*\ Pointer to the stored sign indicator. -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in Errno.h. For a listing of these errors, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in `errno.h`. For a listing of these errors, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -In the case of an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +When there's an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -### Error Conditions +### Error conditions -|*buffer*|*sizeInBytes*|value|count|dec|sign|Return|Value in *buffer*| -|--------------|-------------------|-----------|-----------|---------|----------|------------|-----------------------| -|**NULL**|any|any|any|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|<=0|any|any|any|any|**EINVAL**|Not modified.| -|any|any|any|any|**NULL**|any|**EINVAL**|Not modified.| -|any|any|any|any|any|**NULL**|**EINVAL**|Not modified.| +| *`buffer`* | *`sizeInBytes`* | *`value`* | *`count`* | *`dec`* | *`sign`* | Return | Value in *`buffer`* | +|---|---|---|---|---|---|---|---| +| `NULL` | any | any | any | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | <=0 | any | any | any | any | `EINVAL` | Not modified. | +| any | any | any | any | `NULL` | any | `EINVAL` | Not modified. | +| any | any | any | any | any | `NULL` | `EINVAL` | Not modified. | ## Security Issues -**_fcvt_s** might generate an access violation if *buffer* does not point to valid memory and is not **NULL**. +**`_fcvt_s`** might generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`. ## Remarks -The **_fcvt_s** function converts a floating-point number to a null-terminated character string. The *value* parameter is the floating-point number to be converted. **_fcvt_s** stores the digits of *value* as a string and appends a null character ('\0'). The *count* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *count* places. If there are fewer than *count* digits of precision, the string is padded with zeros. +The **`_fcvt_s`** function converts a floating-point number to a null-terminated character string. The *`value`* parameter is the floating-point number to be converted. **`_fcvt_s`** stores the digits of *`value`* as a string and appends a null character ('\0'). The *`count`* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *`count`* places. If there are fewer than *`count`* digits of precision, the string is padded with zeros. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and *sign* after the call. The *dec* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *sign* points to an integer indicating the sign of *value*. The integer is set to 0 if *value* is positive and is set to a nonzero number if *value* is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *`sign`* points to an integer indicating the sign of *`value`*. The integer is set to 0 if *`value`* is positive and is set to a nonzero number if *`value`* is negative. -A buffer of length **_CVTBUFSIZE** is sufficient for any floating point value. +A buffer of length `_CVTBUFSIZE` is sufficient for any floating point value. -The difference between **_ecvt_s** and **_fcvt_s** is in the interpretation of the *count* parameter. **_ecvt_s** interprets *count* as the total number of digits in the output string, and **_fcvt_s** interprets *count* as the number of digits after the decimal point. +The difference between `_ecvt_s` and **`_fcvt_s`** is in the interpretation of the *`count`* parameter. `_ecvt_s` interprets *`count`* as the total number of digits in the output string, and **`_fcvt_s`** interprets *`count`* as the number of digits after the decimal point. -In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_fcvt_s**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_fcvt_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [C runtime libraries](../crt-library-features.md). ## Example @@ -134,9 +134,9 @@ Converted value: 120000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt_s](ecvt-s.md)
-[_gcvt_s](gcvt-s.md)
-[_fcvt](fcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt_s`](ecvt-s.md)\ +[`_gcvt_s`](gcvt-s.md)\ +[`_fcvt`](fcvt.md) diff --git a/docs/c-runtime-library/reference/fcvt.md b/docs/c-runtime-library/reference/fcvt.md index 80c781354f..a9a313c69e 100644 --- a/docs/c-runtime-library/reference/fcvt.md +++ b/docs/c-runtime-library/reference/fcvt.md @@ -3,16 +3,16 @@ description: "Learn more about: _fcvt" title: "_fcvt" ms.date: "4/2/2020" api_name: ["_fcvt", "_o__fcvt"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fcvt"] helpviewer_keywords: ["converting floating point, to strings", "_fcvt function", "floating-point functions, converting number to string", "fcvt function", "floating-point functions"] ms.assetid: 74584c88-f0dd-4907-8fca-52da5df583f5 --- -# _fcvt +# `_fcvt` -Converts a floating-point number to a string. A more secure version of this function is available; see [_fcvt_s](fcvt-s.md). +Converts a floating-point number to a string. A more secure version of this function is available; see [`_fcvt_s`](fcvt-s.md). ## Syntax @@ -27,45 +27,45 @@ char *_fcvt( ### Parameters -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits after the decimal point. -*dec*
+*`dec`*\ Pointer to the stored decimal-point position. -*sign*
+*`sign`*\ Pointer to the stored sign indicator. -## Return Value +## Return value -**_fcvt** returns a pointer to the string of digits, **NULL** on error. +**`_fcvt`** returns a pointer to the string of digits, `NULL` on error. ## Remarks -The **_fcvt** function converts a floating-point number to a null-terminated character string. The *value* parameter is the floating-point number to be converted. **_fcvt** stores the digits of *value* as a string and appends a null character ('\0'). The *count* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *count* places. If there are fewer than *count* digits of precision, the string is padded with zeros. +The **`_fcvt`** function converts a floating-point number to a null-terminated character string. The *`value`* parameter is the floating-point number to be converted. **`_fcvt`** stores the digits of *`value`* as a string and appends a null character ('\0'). The *`count`* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *`count`* places. If there are fewer than *`count`* digits of precision, the string is padded with zeros. -The total number of digits returned by **_fcvt** will not exceed **_CVTBUFSIZE**. +The total number of digits returned by **`_fcvt`** won't exceed `_CVTBUFSIZE`. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and sign after the call. The *dec* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *sign* points to an integer indicating the sign of *value*. The integer is set to 0 if *value* is positive and is set to a nonzero number if *value* is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and sign after the call. The *`dec`* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *`sign`* points to an integer indicating the sign of *`value`*. The integer is set to 0 if *`value`* is positive and is set to a nonzero number if *`value`* is negative. -The difference between **_ecvt** and **_fcvt** is in the interpretation of the *count* parameter. **_ecvt** interprets *count* as the total number of digits in the output string, whereas **_fcvt** interprets *count* as the number of digits after the decimal point. +The difference between `_ecvt` and **`_fcvt`** is in the interpretation of the *`count`* parameter. `_ecvt` interprets *`count`* as the total number of digits in the output string, whereas **`_fcvt`** interprets *`count`* as the number of digits after the decimal point. -**_ecvt** and **_fcvt** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the results of the previous call. +`_ecvt` and **`_fcvt`** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the results of the previous call. -This function validates its parameters. If *dec* or *sign* is **NULL**, or *count* is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and **NULL** is returned. +This function validates its parameters. If *`dec`* or *`sign`* is `NULL`, or *`count`* is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and `NULL` is returned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fcvt**|\| +| Function | Required header | +|---|---| +| **`_fcvt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,8 +98,8 @@ source: 3.1415926535 buffer: '31415927' decimal: 1 sign: 0 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt](ecvt.md)
-[_gcvt](gcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt`](ecvt.md)\ +[`_gcvt`](gcvt.md) diff --git a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md index 11a0b09bf5..89145b12af 100644 --- a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md +++ b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fdim", "fdimf", "fdiml", "math/fdim", "math/fdimf", "math/fdiml"] helpviewer_keywords: ["fdim function", "fdimf function", "fdiml function"] -ms.assetid: 2d4ac639-51e9-462d-84ab-fb03b06971a0 --- -# fdim, fdimf, fdiml +# `fdim`, `fdimf`, `fdiml` Determines the positive difference between the first and second values. @@ -47,50 +46,50 @@ long double fdiml( ### Parameters -*x*\ +*`x`*\ The first value. -*y*\ +*`y`*\ The second value. -## Return Value +## Return value -Returns the positive difference between *x* and *y*: +Returns the positive difference between *`x`* and *`y`*: -|Return value|Scenario| -|------------------|--------------| -|x-y|if x > y| -|0|if x <= y| +| Return value | Scenario | +|---|---| +| `x-y` | if *`x`* > *`y`* | +| 0 | if *`x`* <= *`y`* | Otherwise, may return one of the following errors: -|Issue|Return| -|-----------|------------| -|Overflow range error|+HUGE_VAL, +HUGE_VALF, or +HUGE_VALL| -|Underflow range error|correct value (after rounding)| -|*x* or *y* is NaN|NaN| +| Issue | Return | +|---|---| +| Overflow range error | +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL | +| Underflow range error | correct value (after rounding) | +| *`x`* or *`y`* is NaN | NaN | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **fdim** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fdim** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fdim`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fdim`** always takes and returns a **`double`**. -If you use the \ `fdim()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fdim()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. Except for the NaN handling, this function is equivalent to `fmax(x - y, 0)`. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fdim**, **fdimf**, **fdiml**|\|\| -|**fdim** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fdim`**, **`fdimf`**, **`fdiml`** | \ | \ | +| **`fdim`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmax, fmaxf, fmaxl](fmax-fmaxf-fmaxl.md)
-[abs, labs, llabs, _abs64](abs-labs-llabs-abs64.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmax`, `fmaxf`, `fmaxl`](fmax-fmaxf-fmaxl.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md) diff --git a/docs/c-runtime-library/reference/fdopen-wfdopen.md b/docs/c-runtime-library/reference/fdopen-wfdopen.md index d6ee061377..46191ee16c 100644 --- a/docs/c-runtime-library/reference/fdopen-wfdopen.md +++ b/docs/c-runtime-library/reference/fdopen-wfdopen.md @@ -1,16 +1,16 @@ --- description: "Learn more about: _fdopen, _wfdopen" title: "_fdopen, _wfdopen" -ms.date: "4/2/2020" +ms.date: 05/18/2022 api_name: ["_fdopen", "_wfdopen", "_o__fdopen", "_o__wfdopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tfdopen", "_fdopen", "_wfdopen", "wfdopen", "tfdopen"] +f1_keywords: ["STDIO/_fdopen", "CORECRT_WSTDIO/_wfdopen", "TCHAR/_tfdopen", "_fdopen", "_wfdopen", "_tfdopen", "wfdopen", "tfdopen"] helpviewer_keywords: ["wfdopen function", "_fdopen function", "_wfdopen function", "tfdopen function", "fdopen function", "_tfdopen function", "streams, associating with files"] ms.assetid: 262757ff-1e09-4472-a5b6-4325fc28f971 --- -# _fdopen, _wfdopen +# `_fdopen`, `_wfdopen` Associates a stream with a file that was previously opened for low-level I/O. @@ -29,81 +29,81 @@ FILE *_wfdopen( ### Parameters -*fd*
+*`fd`*\ File descriptor of the open file. -*mode*
+*`mode`*\ Type of file access. -## Return Value +## Return value -Each of these functions returns a pointer to the open stream. A null pointer value indicates an error. When an error occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set either to **EBADF**, which indicates a bad file descriptor, or **EINVAL**, which indicates that *mode* was a null pointer. +Each of these functions returns a pointer to the open stream. A null pointer value indicates an error. When an error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set either to `EBADF`, which indicates a bad file descriptor, or `EINVAL`, which indicates that *`mode`* was a null pointer. -For more information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_fdopen** function associates an I/O stream with the file that is identified by *fd*, and thus allows a file that is opened for low-level I/O to be buffered and formatted. **_wfdopen** is a wide-character version of **_fdopen**; the *mode* argument to **_wfdopen** is a wide-character string. **_wfdopen** and **_fdopen** otherwise behave identically. +The **`_fdopen`** function associates an I/O stream with the file that is identified by *`fd`*, and thus allows a file that is opened for low-level I/O to be buffered and formatted. **`_wfdopen`** is a wide-character version of **`_fdopen`**; the *`mode`* argument to **`_wfdopen`** is a wide-character string. **`_wfdopen`** and **`_fdopen`** otherwise behave identically. -File descriptors passed into **_fdopen** are owned by the returned `FILE *` stream. If **_fdopen** is successful, do not call [\_close](close.md) on the file descriptor. Calling [fclose](fclose-fcloseall.md) on the returned `FILE *` also closes the file descriptor. +File descriptors passed into **`_fdopen`** are owned by the returned `FILE *` stream. If **`_fdopen`** is successful, don't call [`_close`](close.md) on the file descriptor. Calling [`fclose`](fclose-fcloseall.md) on the returned `FILE *` also closes the file descriptor. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +The *`mode`* character string specifies the type of file access requested for the file: -|Tchar.h routine|\_UNICODE and \_MBCS not defined|\_MBCS defined|\_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfdopen**|**_fdopen**|**_fdopen**|**_wfdopen**| - -The *mode* character string specifies the type of file access requested for the file: - -| *mode* | Access | +| *`mode`* | Access | |--------|--------| -| **"r"** | Opens for reading. If the file does not exist or cannot be found, the **fopen** call fails. | -| **"w"** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | -| **"a"** | Opens for writing at the end of the file (appending). Creates the file if it does not exist. | -| **"r+"** | Opens for both reading and writing. The file must exist. | -| **"w+"** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | -| **"a+"** | Opens for reading and appending. Creates the file if it does not exist. | +| **`"r"`** | Opens for reading. If the file doesn't exist or can't be found, the **`fopen`** call fails. | +| **`"w"`** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | +| **`"a"`** | Opens for writing at the end of the file (appending). Creates the file if it doesn't exist. | +| **`"r+"`** | Opens for both reading and writing. The file must exist. | +| **`"w+"`** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | +| **`"a+"`** | Opens for reading and appending. Creates the file if it doesn't exist. | -When a file is opened with the **"a"** or **"a+"** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [fseek](fseek-fseeki64.md) or [rewind](rewind.md), but it is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten. When the **"r+"**, **"w+"**, or **"a+"** access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening [fflush](fflush.md), [fsetpos](fsetpos.md), [fseek](fseek-fseeki64.md), or [rewind](rewind.md) operation. You can specify the current position for the [fsetpos](fsetpos.md) or [fseek](fseek-fseeki64.md) operation, if you want to. +When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out. Thus, existing data can't be overwritten. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening [`fflush`](fflush.md), [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. You can specify the current position for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if you want to. -In addition to the above values, the following characters can also be included in *mode* to specify the translation mode for newline characters: +In addition to the above values, the following characters can also be included in *`mode`* to specify the translation mode for newline characters: -| *mode* modifier | Behavior | +| *`mode`* modifier | Behavior | |-----------------|----------| -| **t** | Open in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into one-line feeds (LF) on input, and LF characters are translated to CR-LF combinations on output. Also, Ctrl+Z is interpreted as an end-of-file character on input. | -| **b** | Open in binary (untranslated) mode. Any translations from **t** mode are suppressed. | -| **c** | Enable the commit flag for the associated *filename* so that the contents of the file buffer are written directly to disk if either **fflush** or **_flushall** is called. | -| **n** | Reset the commit flag for the associated *filename* to "no-commit." This is the default. It also overrides the global commit flag if you link your program with Commode.obj. The global commit flag default is "no-commit" unless you explicitly link your program with Commode.obj. | - -The **t**, **c**, and **n** *mode* options are Microsoft extensions for **fopen** and **_fdopen**. Do not use them if you want to preserve ANSI portability. - -If **t** or **b** is not given in *mode*, the default translation mode is defined by the global variable [\_fmode](../../c-runtime-library/fmode.md). If **t** or **b** is prefixed to the argument, the function fails and returns NULL. For a discussion of text and binary modes, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). - -Valid characters for the *mode* string used in **fopen** and **_fdopen** correspond to *oflag* arguments used in [\_open](open-wopen.md) and [\_sopen](sopen-wsopen.md), as shown in this table: - -|Characters in *mode* string|Equivalent *oflag* value for **_open** and **_sopen**| -|---------------------------------|---------------------------------------------------| -|**a**|**\_O\_WRONLY | \_O\_APPEND** (usually **\_O\_WRONLY | \_O\_CREAT | \_O\_APPEND**)| -|**a+**|**\_O\_RDWR | \_O\_APPEND** (usually **\_O\_RDWR | \_O\_APPEND | \_O\_CREAT** )| -|**r**|**\_O\_RDONLY**| -|**r+**|**\_O\_RDWR**| -|**w**|**\_O\_WRONLY** (usually **\_O\_WRONLY | \_O\_CREAT | \_O\_TRUNC**)| -|**w+**|**\_O\_RDWR** (usually **\_O\_RDWR | \_O\_CREAT | \_O\_TRUNC**)| -|**b**|**\_O\_BINARY**| -|**t**|**\_O\_TEXT**| -|**c**|None| -|**n**|None| +| **`t`** | Open in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into one-line feeds (LF) on input, and LF characters are translated to CR-LF combinations on output. Also, Ctrl+Z is interpreted as an end-of-file character on input. | +| **`b`** | Open in binary (untranslated) mode. Any translations from **`t`** mode are suppressed. | +| **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`Commode.obj`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`Commode.obj`*. | + +The **`t`**, **`c`**, and **`n`** *`mode`* options are Microsoft extensions for **`fopen`** and **`_fdopen`**. Don't use them if you want to preserve ANSI portability. + +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. For a discussion of text and binary modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). + +Valid characters for the *`mode`* string used in **`fopen`** and **`_fdopen`** correspond to *`oflag`* arguments used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as shown in this table: + +| Characters in *`mode`* string | Equivalent *`oflag`* value for **`_open`** and **`_sopen`** | +|--|--| +| **`a`** | `_O_WRONLY | _O_APPEND` (usually `_O_WRONLY | _O_CREAT | _O_APPEND`) | +| **`a+`** | `_O_RDWR | _O_APPEND` (usually `_O_RDWR | _O_APPEND | _O_CREAT`) | +| **`r`** | `_O_RDONLY` | +| **`r+`** | `_O_RDWR` | +| **`w`** | `_O_WRONLY` (usually `_O_WRONLY | _O_CREAT | _O_TRUNC`) | +| **`w+`** | `_O_RDWR` (usually `_O_RDWR | _O_CREAT | _O_TRUNC`) | +| **`b`** | `_O_BINARY` | +| **`t`** | `_O_TEXT` | +| **`c`** | None | +| **`n`** | None | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fdopen**|\| -|**_wfdopen**|\ or \| +| Function | Required header | C++ header | +|--|--|--| +| **`_fdopen`** | `` | `` | +| **`_wfdopen`** | `` or `` | `` | + +For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../compatibility.md). + +### Generic-text routine mappings -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| `` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_tfdopen`** | **`_fdopen`** | **`_fdopen`** | **`_wfdopen`** | ## Example @@ -157,9 +157,9 @@ Lines in file: 2 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[\_dup, \_dup2](dup-dup2.md)
-[fclose, \_fcloseall](fclose-fcloseall.md)
-[fopen, \_wfopen](fopen-wfopen.md)
-[freopen, \_wfreopen](freopen-wfreopen.md)
-[\_open, \_wopen](open-wopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`_dup`, `_dup2`](dup-dup2.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/fdopen.md b/docs/c-runtime-library/reference/fdopen.md index 549d0382de..9471513b40 100644 --- a/docs/c-runtime-library/reference/fdopen.md +++ b/docs/c-runtime-library/reference/fdopen.md @@ -10,8 +10,8 @@ f1_keywords: ["fdopen"] helpviewer_keywords: ["fdopen function"] ms.assetid: 3243c1d2-2826-4d2d-bfa2-a2da45f9cc7a --- -# fdopen +# `fdopen` -The Microsoft-implemented POSIX function name `fdopen` is a deprecated alias for the [_fdopen](fdopen-wfdopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `fdopen` is a deprecated alias for the [`_fdopen`](fdopen-wfdopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fdopen](fdopen-wfdopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fdopen`](fdopen-wfdopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/feclearexcept1.md b/docs/c-runtime-library/reference/feclearexcept1.md index 8c6e9e10ab..de74f7735a 100644 --- a/docs/c-runtime-library/reference/feclearexcept1.md +++ b/docs/c-runtime-library/reference/feclearexcept1.md @@ -10,9 +10,9 @@ f1_keywords: ["feclearexcept", "fenv/feclearexcept"] helpviewer_keywords: ["feclearexcept function"] ms.assetid: ef419da3-c248-4432-b53c-8e7a475d9533 --- -# feclearexcept +# `feclearexcept` -Attempts to clear the floating-point exception flags specified by the argument. +**`feclearexcept`** attempts to clear the floating-point exception flags specified by the argument. ## Syntax @@ -24,37 +24,37 @@ int feclearexcept( ### Parameters -*excepts*
+*`excepts`*\ The exception status flags to clear. -## Return Value +## Return value -Returns zero if *excepts* is zero, or if all the specified exceptions were successfully cleared. Otherwise, returns a nonzero value. +Returns zero if *`excepts`* is zero, or if all the specified exceptions were successfully cleared. Otherwise, it returns a nonzero value. ## Remarks -The **feclearexcept** function attempts to clear the floating point exception status flags specified by *excepts*. The function supports these exception macros, defined in fenv.h: +The **`feclearexcept`** function attempts to clear the floating point exception status flags specified by *`excepts`*. The function supports these exception macros, defined in fenv.h: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, or the bitwise OR of one or more of the supported exception macros. The result of any other argument value is undefined. +The *`excepts`* argument may be zero, or the bitwise OR of one or more of the supported exception macros. The result of any other argument value is undefined. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feclearexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feclearexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fetestexcept](fetestexcept1.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fetestexcept`](fetestexcept1.md) diff --git a/docs/c-runtime-library/reference/fegetenv1.md b/docs/c-runtime-library/reference/fegetenv1.md index 36ca31d1f1..e14e60b558 100644 --- a/docs/c-runtime-library/reference/fegetenv1.md +++ b/docs/c-runtime-library/reference/fegetenv1.md @@ -10,7 +10,7 @@ f1_keywords: ["fegetenv", "fenv/fegetenv"] helpviewer_keywords: ["fetegenv function"] ms.assetid: 68962421-6978-4b27-8e4c-ad1577830cf6 --- -# fegetenv +# `fegetenv` Stores the current floating-point environment in the specified object. @@ -24,28 +24,28 @@ int fegetenv( ### Parameters -*penv*
-Pointer to an **fenv_t** object to contain the current floating-point environment values. +*`penv`*\ +Pointer to an `fenv_t` object to contain the current floating-point environment values. -## Return Value +## Return value -Returns 0 if the floating-point environment was successfully stored in *penv*. Otherwise, returns a non-zero value. +Returns 0 if the floating-point environment was successfully stored in *`penv`*. Otherwise, it returns a non-zero value. ## Remarks -The **fegetenv** function stores the current floating-point environment in the object pointed to by *penv*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This includes the rounding direction mode and the status flags for floating-point exceptions. If *penv* does not point to a valid **fenv_t** object, subsequent behavior is undefined. +The **`fegetenv`** function stores the current floating-point environment in the object pointed to by *`penv`*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This environment includes the rounding direction mode and the status flags for floating-point exceptions. If *`penv`* doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetenv](fesetenv1.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetenv`](fesetenv1.md) diff --git a/docs/c-runtime-library/reference/fegetexceptflag2.md b/docs/c-runtime-library/reference/fegetexceptflag2.md index 144cf99831..eee0d9ff14 100644 --- a/docs/c-runtime-library/reference/fegetexceptflag2.md +++ b/docs/c-runtime-library/reference/fegetexceptflag2.md @@ -10,7 +10,7 @@ f1_keywords: ["fegetexceptflag", "fenv/fegetexceptflag"] helpviewer_keywords: ["fegetexceptflag function"] ms.assetid: 2d28f0ca-70c9-4cff-be8b-3d876eacde71 --- -# fegetexceptflag +# `fegetexceptflag` Stores the current state of the specified floating-point exception flags. @@ -25,42 +25,42 @@ int fegetexceptflag( ### Parameters -*pstatus*
-A pointer to a **fexcept_t** object to contain the current values of the exception flags specified by *excepts*. +*`pstatus`*\ +A pointer to a `fexcept_t` object to contain the current values of the exception flags specified by *`excepts`*. -*excepts*
-The floating-point exception flags to store in *pstatus*. +*`excepts`*\ +The floating-point exception flags to store in *`pstatus`*. -## Return Value +## Return value -On success, returns 0. Otherwise, returns a non-zero value. +On success, returns 0. Otherwise, it returns a non-zero value. ## Remarks -The **fegetexceptflag** function stores the current state of the floating-point exception status flags specified by *excepts* in the **fexcept_t** object pointed to by *pstatus*. *pstatus* must point to a valid **fexcept_t** object, or subsequent behavior is undefined. The **fegetexceptflag** function supports these exception macros, defined in \: +The **`fegetexceptflag`** function stores the current state of the floating-point exception status flags specified by *`excepts`* in the `fexcept_t` object pointed to by *`pstatus`*. *`pstatus`* must point to a valid `fexcept_t` object, or subsequent behavior is undefined. The **`fegetexceptflag`** function supports these exception macros, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. +The *`excepts`* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetexceptflag**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetexceptflag`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fegetround-fesetround2.md b/docs/c-runtime-library/reference/fegetround-fesetround2.md index cf1d8033a3..d771b3c7d4 100644 --- a/docs/c-runtime-library/reference/fegetround-fesetround2.md +++ b/docs/c-runtime-library/reference/fegetround-fesetround2.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fegetround", "fesetround", "fenv/fegetround", "fenv/fesetround"] helpviewer_keywords: ["fegetround function", "fesetround function"] -ms.assetid: 596af00b-be2f-4f57-b2f5-460485f9ff0b --- -# fegetround, fesetround +# `fegetround`, `fesetround` Gets or sets the current floating-point rounding mode. @@ -18,67 +17,63 @@ Gets or sets the current floating-point rounding mode. ```C int fegetround(void); - -int fesetround( - int round_mode -); +int fesetround(int round_mode); ``` ### Parameters -*round_mode*
-The rounding mode to set, as one of the floating-point rounding macros. If the value is not equal to one of the floating-point rounding macros, the rounding mode is not changed. +*`round_mode`*\ +The rounding mode to set, as one of the floating-point rounding macros. If the value isn't equal to one of the floating-point rounding macros, the rounding mode isn't changed. -## Return Value +## Return value -On success, **fegetround** returns the rounding mode as one of the floating point rounding macro values. It returns a negative value if the current rounding mode can't be determined. +On success, **`fegetround`** returns the rounding mode as one of the floating point rounding macro values. It returns a negative value if the current rounding mode can't be determined. -On success, **fesetround** returns 0. Otherwise, a non-zero value is returned. +On success, **`fesetround`** returns 0. Otherwise, a non-zero value is returned. ## Remarks -Floating-point operations can use one of several rounding modes. These control which direction the results of floating-point operations are rounded toward when the results are stored. These are the names and behaviors of the floating-point rounding macros defined in \: +Floating-point operations can use one of several rounding modes. These modes control which direction the results of floating-point operations are rounded toward when the results are stored. Here are the names and behaviors of the floating-point rounding macros defined in \: -|Macro|Description| -|-----------|-----------------| -|FE_DOWNWARD|Round towards negative infinity.| -|FE_TONEAREST|Round towards the nearest.| -|FE_TOWARDZERO|Round towards zero.| -|FE_UPWARD|Round towards positive infinity.| +| Macro | Description | +|---|---| +| `FE_DOWNWARD` | Round towards negative infinity. | +| `FE_TONEAREST` | Round towards the nearest. | +| `FE_TOWARDZERO` | Round towards zero. | +| `FE_UPWARD` | Round towards positive infinity. | -The default behavior of FE_TONEAREST is to round results midway between representable values toward the nearest value with an even (0) least significant bit. +The default behavior of `FE_TONEAREST` is to round results midway between representable values toward the nearest value with an even (0) least significant bit. The current rounding mode affects these operations: - String conversions. - - The results of floating-point arithmetic operators outside of constant expressions. - -- The library rounding functions, such as **rint** and **nearbyint**. - +- The library rounding functions, such as `rint` and `nearbyint`. - Return values from standard library mathematical functions. -The current rounding mode does not affect these operations: - -- The **trunc**, **ceil**, **floor**, and **lround** library functions. +The current rounding mode doesn't affect these operations: +- The `trunc`, `ceil`, `floor`, and `lround` library functions. - Floating-point to integer implicit casts and conversions, which always round towards zero. - - The results of floating-point arithmetic operators in constant expressions, which always round to the nearest value. -To use these functions, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use these functions, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). + +> [!IMPORTANT] +> Prior to Windows 10 version 14393, `fenv.h` defined `FE_UPWARD = 0x0100` and `FE_DOWNWARD = 0x0200`. In Windows version 14393, this header was updated to address a bug in which some APIs would interpret `FE_UPWARD` as `FE_DOWNWARD`, and vice-versa. Starting in Windows version 14393, `FE_UPWARD = 0x0200` and `FE_DOWNWARD = 0x0100`, reversing their previous values. +> If you compiled your app against an old Windows SDK version (this issue depends on SDK version, not OS version or VS version) you might encounter this issue. Update your app to target the latest Windows SDK so that the definitions of `FE_UPWARD` and `FE_DOWNWARD` are consistent with the Windows implementation. If you can't update your app to target a later Windows SDK, you can define `FE_UPWARD` as `0x0100` and `FE_DOWNWARD` as `0x0200` in your code. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetround**, **fesetround**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetround`**, **`fesetround`** | `` | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[nearbyint, nearbyintf, nearbyintl](nearbyint-nearbyintf-nearbyintl1.md)
-[rint, rintf, rintl](rint-rintf-rintl.md)
-[lrint, lrintf, lrintl, llrint, llrintf, llrintl](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`nearbyint`, `nearbyintf`, `nearbyintl`](nearbyint-nearbyintf-nearbyintl1.md)\ +[`rint`, `rintf`, `rintl`](rint-rintf-rintl.md)\ +[`lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl`](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) diff --git a/docs/c-runtime-library/reference/feholdexcept2.md b/docs/c-runtime-library/reference/feholdexcept2.md index 5addcd17fa..fbf45b3e33 100644 --- a/docs/c-runtime-library/reference/feholdexcept2.md +++ b/docs/c-runtime-library/reference/feholdexcept2.md @@ -10,7 +10,7 @@ f1_keywords: ["feholdexcept", "fenv/feholdexcept"] helpviewer_keywords: ["feholdexcept function"] ms.assetid: 88e512ae-b5d8-452c-afe9-c824cd3ef1d8 --- -# feholdexcept +# `feholdexcept` Saves the current floating-point environment in the specified object, clears the floating-point status flags, and, if possible, puts the floating-point environment into non-stop mode. @@ -24,32 +24,32 @@ int feholdexcept( ### Parameters -*penv*
-Pointer to an **fenv_t** object to contain a copy of the floating-point environment. +*`penv`*\ +Pointer to an `fenv_t` object to contain a copy of the floating-point environment. -## Return Value +## Return value Returns zero if and only if the function is able to successfully turn on non-stop floating-point exception handling. ## Remarks -The **feholdexcept** function is used to store the state of the current floating point environment in the **fenv_t** object pointed to by *penv*, and to set the environment to not interrupt execution on floating-point exceptions. This is known as non-stop mode. This mode continues until the environment is restored using [fesetenv](fesetenv1.md) or [feupdateenv](feupdateenv.md). +The **`feholdexcept`** function is used to store the state of the current floating point environment in the `fenv_t` object pointed to by *`penv`*, and to set the environment to not interrupt execution on floating-point exceptions. This mode is known as *non-stop mode*. This mode continues until the environment is restored using [`fesetenv`](fesetenv1.md) or [`feupdateenv`](feupdateenv.md). -You can use this function at the beginning of a subroutine that needs to hide one or more floating-point exceptions from the caller. To report an exception, you can simply clear the unwanted exceptions by using [feclearexcept,](feclearexcept1.md) and then end the non-stop mode with a call to **feupdateenv**. +You can use this function at the beginning of a subroutine that needs to hide one or more floating-point exceptions from the caller. To report an exception, you can clear the unwanted exceptions by using [`feclearexcept`](feclearexcept1.md), and then end the non-stop mode with a call to `feupdateenv`. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feholdexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feholdexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[feclearexcept](feclearexcept1.md)
-[fesetenv](fesetenv1.md)
-[feupdateenv](feupdateenv.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`fesetenv`](fesetenv1.md)\ +[`feupdateenv`](feupdateenv.md) diff --git a/docs/c-runtime-library/reference/feof.md b/docs/c-runtime-library/reference/feof.md index 0e982944f4..a109a3b828 100644 --- a/docs/c-runtime-library/reference/feof.md +++ b/docs/c-runtime-library/reference/feof.md @@ -3,14 +3,14 @@ description: "Learn more about: feof" title: "feof" ms.date: "4/2/2020" api_name: ["feof", "_o_feof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["feof"] helpviewer_keywords: ["end of file, testing for", "feof function"] ms.assetid: 09081eee-7c4b-4189-861f-2fad95d3ec6d --- -# feof +# `feof` Tests for end-of-file on a stream. @@ -24,30 +24,30 @@ int feof( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -The **feof** function returns a nonzero value if a read operation has attempted to read past the end of the file; it returns 0 otherwise. If the stream pointer is **NULL**, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the **feof** returns 0. +The **`feof`** function returns a nonzero value if a read operation has attempted to read past the end of the file; it returns 0 otherwise. If the stream pointer is `NULL`, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the **`feof`** returns 0. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **feof** routine (implemented both as a function and as a macro) determines whether the end of *stream* has been passed. When the end of file is passed, read operations return an end-of-file indicator until the stream is closed or until [rewind](rewind.md), **fsetpos**, [fseek](fseek-fseeki64.md), or **clearerr** is called against it. +The **`feof`** routine (implemented both as a function and as a macro) determines whether the end of *`stream`* has been passed. When the end of file is passed, read operations return an end-of-file indicator until the stream is closed or until [`rewind`](rewind.md), `fsetpos`, [`fseek`](fseek-fseeki64.md), or `clearerr` is called against it. -For example, if a file contains 10 bytes and you read 10 bytes from the file, **feof** will return 0 because, even though the file pointer is at the end of the file, you have not attempted to read beyond the end. Only after you try to read an 11th byte will **feof** return a nonzero value. +For example, if a file contains 10 bytes and you read 10 bytes from the file, **`feof`** will return 0 because, even though the file pointer is at the end of the file, you haven't attempted to read beyond the end. Only after you try to read an 11th byte will **`feof`** return a nonzero value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**feof**|\| +| Function | Required header | +|---|---| +| **`feof`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,9 +104,9 @@ Number of bytes read = 19 ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[clearerr](clearerr.md)
-[_eof](eof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`_eof`](eof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/feraiseexcept.md b/docs/c-runtime-library/reference/feraiseexcept.md index 53dfe4ba11..90eb2f4f93 100644 --- a/docs/c-runtime-library/reference/feraiseexcept.md +++ b/docs/c-runtime-library/reference/feraiseexcept.md @@ -9,7 +9,7 @@ f1_keywords: ["feraiseexcept", "fenv/feraiseexcept"] helpviewer_keywords: ["feraiseexcept function"] ms.assetid: 87e89151-83c2-4563-9a9a-45666245d437 --- -# feraiseexcept +# `feraiseexcept` Raises the specified floating-point exceptions. @@ -23,44 +23,44 @@ int feraiseexcept( ### Parameters -*excepts*
+*`excepts`*\ The floating-point exceptions to raise. -## Return Value +## Return value If all specified exceptions are raised successfully, returns 0. ## Remarks -The **feraiseexcept** function attempts to raise the floating-point exceptions specified by *excepts*. The **feraiseexcept** function supports these exception macros, defined in \: +The **`feraiseexcept`** function attempts to raise the floating-point exceptions specified by *`excepts`*. The **`feraiseexcept`** function supports these exception macros, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the exception macro values, or the bitwise OR of two or more of the supported exception macros. If one of the specified exception macros is FE_OVERFLOW or FE_UNDERFLOW, the FE_INEXACT exception may be raised as a side-effect. +The *`excepts`* argument may be zero, one of the exception macro values, or the bitwise OR of two or more of the supported exception macros. If one of the specified exception macros is `FE_OVERFLOW` or `FE_UNDERFLOW`, the `FE_INEXACT` exception may be raised as a side-effect. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). -**Microsoft-specific:** The exceptions specified in *excepts* are raised in the order FE_INVALID, FE_DIVBYZERO, FE_OVERFLOW, FE_UNDERFLOW, FE_INEXACT. However, FE_INEXACT can be raised when FE_OVERFLOW or FE_UNDERFLOW is raised, even if not specified in *excepts*. +**Microsoft-specific:** The exceptions specified in *`excepts`* are raised in the order `FE_INVALID`, `FE_DIVBYZERO`, `FE_OVERFLOW`, `FE_UNDERFLOW`, `FE_INEXACT`. However, `FE_INEXACT` can be raised when `FE_OVERFLOW` or `FE_UNDERFLOW` is raised, even if not specified in *`excepts`*. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|*feraiseexcept*|\|\| +| Function | C header | C++ header | +|---|---|---| +| `feraiseexcept` | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetexceptflag](fesetexceptflag2.md)
-[feholdexcept](feholdexcept2.md)
-[fetestexcept](fetestexcept1.md)
-[feupdateenv](feupdateenv.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetexceptflag`](fesetexceptflag2.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fetestexcept`](fetestexcept1.md)\ +[`feupdateenv`](feupdateenv.md) diff --git a/docs/c-runtime-library/reference/ferror.md b/docs/c-runtime-library/reference/ferror.md index 2d3b16c978..66e3c80610 100644 --- a/docs/c-runtime-library/reference/ferror.md +++ b/docs/c-runtime-library/reference/ferror.md @@ -3,14 +3,14 @@ description: "Learn more about: ferror" title: "ferror" ms.date: "4/2/2020" api_name: ["ferror", "_o_ferror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ferror"] helpviewer_keywords: ["ferror function", "streams, testing for errors", "errors [C++], testing for stream"] ms.assetid: 528a34bc-f2aa-4c3f-b89a-5b148e6864f7 --- -# ferror +# `ferror` Tests for an error on a stream. @@ -24,39 +24,39 @@ int ferror( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If no error has occurred on *stream*, **ferror** returns 0. Otherwise, it returns a nonzero value. If stream is **NULL**, **ferror** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns 0. +If no error has occurred on *`stream`*, **`ferror`** returns 0. Otherwise, it returns a nonzero value. If stream is `NULL`, **`ferror`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **ferror** routine (implemented both as a function and as a macro) tests for a reading or writing error on the file associated with *stream*. If an error has occurred, the error indicator for the stream remains set until the stream is closed or rewound, or until **clearerr** is called against it. +The **`ferror`** routine (implemented both as a function and as a macro) tests for a reading or writing error on the file associated with *`stream`*. If an error has occurred, the error indicator for the stream remains set until the stream is closed or rewound, or until `clearerr` is called against it. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**ferror**|\| +| Function | Required header | +|---|---| +| **`ferror`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [feof](feof.md). +See the example for [`feof`](feof.md). ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[clearerr](clearerr.md)
-[_eof](eof.md)
-[feof](feof.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`_eof`](eof.md)\ +[`feof`](feof.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/fesetenv1.md b/docs/c-runtime-library/reference/fesetenv1.md index d997c924e3..9f0535d02c 100644 --- a/docs/c-runtime-library/reference/fesetenv1.md +++ b/docs/c-runtime-library/reference/fesetenv1.md @@ -10,7 +10,7 @@ f1_keywords: ["fesetenv", "fenv/fesetenv"] helpviewer_keywords: ["fesetenv function"] ms.assetid: ffc64fff-8ea7-4d59-9e04-ff96ef8cd012 --- -# fesetenv +# `fesetenv` Sets the current floating-point environment. @@ -24,33 +24,33 @@ int fesetenv( ### Parameters -*penv*
-Pointer to a **fenv_t** object that contains a floating-point environment as set by a call to [fegetenv](fegetenv1.md) or [feholdexcept](feholdexcept2.md). You can also specify the default startup floating-point environment by using the **FE_DFL_ENV** macro. +*`penv`*\ +Pointer to a `fenv_t` object that contains a floating-point environment as set by a call to [`fegetenv`](fegetenv1.md) or [`feholdexcept`](feholdexcept2.md). You can also specify the default startup floating-point environment by using the `FE_DFL_ENV` macro. -## Return Value +## Return value -Returns 0 if the environment was successfully set. Otherwise, returns a nonzero value. +Returns 0 if the environment was successfully set. Otherwise, it returns a nonzero value. ## Remarks -The **fesetenv** function sets the current floating-point environment from the value stored in the **fenv_t** object pointed to by *penv*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This includes the rounding mode and the status flags for floating-point exceptions. If *penv* is not **FE_DFL_ENV** or does not point to a valid **fenv_t** object, subsequent behavior is undefined. +The **`fesetenv`** function sets the current floating-point environment from the value stored in the `fenv_t` object pointed to by *`penv`*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. The environment includes the rounding mode and the status flags for floating-point exceptions. If *`penv`* isn't `FE_DFL_ENV` or doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. -A call to this function sets the exception status flags that are in the *penv* object, but it does not raise those exceptions. +A call to this function sets the exception status flags that are in the *`penv`* object, but it doesn't raise those exceptions. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fesetenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fesetenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fegetenv](fegetenv1.md)
-[feclearexcept](feclearexcept1.md)
-[feholdexcept](feholdexcept2.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fegetenv`](fegetenv1.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fesetexceptflag2.md b/docs/c-runtime-library/reference/fesetexceptflag2.md index d5b6a4d7da..9ab471a018 100644 --- a/docs/c-runtime-library/reference/fesetexceptflag2.md +++ b/docs/c-runtime-library/reference/fesetexceptflag2.md @@ -10,7 +10,7 @@ f1_keywords: ["fesetexceptflag", "fenv/fesetexceptflag"] helpviewer_keywords: ["fesetexceptflag function"] ms.assetid: 2f7dad77-9e54-4097-a3e3-35176ace4de5 --- -# fesetexceptflag +# `fesetexceptflag` Sets the specified floating-point status flags in the current floating-point environment. @@ -25,42 +25,42 @@ int fesetexceptflag( ### Parameters -*pstatus*
-Pointer to an **fexcept_t** object containing the values to set the exception status flags to. The object may be set by a previous call to [fegetexceptflag](fegetexceptflag2.md). +*`pstatus`*\ +Pointer to an `fexcept_t` object containing the values to set the exception status flags to. The object may be set by a previous call to [`fegetexceptflag`](fegetexceptflag2.md). -*excepts*
+*`excepts`*\ The floating-point exception status flags to set. -## Return Value +## Return value -If all the specified exception status flags are set successfully, returns 0. Otherwise, returns a nonzero value. +If all the specified exception status flags are set successfully, returns 0. Otherwise, it returns a nonzero value. ## Remarks -The **fesetexceptflag** function sets the state of the floating-point exception status flags specified by *excepts* to the corresponding values set in the **fexcept_t** object pointed to by *pstatus*. It does not raise the exceptions. The *pstatus* pointer must point to a valid **fexcept_t** object, or subsequent behavior is undefined. The **fesetexceptflag** function supports these exception macro values in *excepts*, defined in \: +The **`fesetexceptflag`** function sets the state of the floating-point exception status flags specified by *`excepts`* to the corresponding values set in the `fexcept_t` object pointed to by *`pstatus`*. It doesn't raise the exceptions. The *`pstatus`* pointer must point to a valid `fexcept_t` object, or subsequent behavior is undefined. The **`fesetexceptflag`** function supports these exception macro values in *`excepts`*, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. +The *`excepts`* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fesetexceptflag**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fesetexceptflag`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fegetexceptflag](fegetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fegetexceptflag`](fegetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fetestexcept1.md b/docs/c-runtime-library/reference/fetestexcept1.md index 6086911b23..9022c438b8 100644 --- a/docs/c-runtime-library/reference/fetestexcept1.md +++ b/docs/c-runtime-library/reference/fetestexcept1.md @@ -10,7 +10,7 @@ f1_keywords: ["fetestexcept", "fenv/fetestexcept"] helpviewer_keywords: ["fetestexept function"] ms.assetid: ca4dc43f-5573-440d-bc19-ead7571b13dc --- -# fetestexcept +# `fetestexcept` Determines which of the specified floating-point exception status flags are currently set. @@ -24,40 +24,40 @@ int fetestexcept( ### Parameters -*excepts*
+*`excepts`*\ A bitwise OR of the floating-point status flags to test. -## Return Value +## Return value On success, returns a bitmask containing a bitwise OR of the floating-point exception macros that correspond to the exception status flags currently set. Returns 0 if none of the exceptions are set. ## Remarks -Use the fetestexcept function to determine which exceptions were raised by a floating point operation. Use the *excepts* parameter to specify which exception status flags to test. The **fetestexcept** function uses these exception macros defined in \ in *excepts* and the return value: +Use the fetestexcept function to determine which exceptions were raised by a floating point operation. Use the *`excepts`* parameter to specify which exception status flags to test. The **`fetestexcept`** function uses these exception macros defined in \ in *`excepts`* and the return value: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The specified *excepts* argument may be 0, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other *excepts* argument value is undefined. +The specified *`excepts`* argument may be 0, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other *`excepts`* argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fetestexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fetestexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[feclearexcept](feclearexcept1.md)
-[feraiseexcept](feraiseexcept.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feraiseexcept`](feraiseexcept.md) diff --git a/docs/c-runtime-library/reference/feupdateenv.md b/docs/c-runtime-library/reference/feupdateenv.md index c016f2c2f4..288e355f6b 100644 --- a/docs/c-runtime-library/reference/feupdateenv.md +++ b/docs/c-runtime-library/reference/feupdateenv.md @@ -9,7 +9,7 @@ f1_keywords: ["feupdateenv", "fenv/feupdateenv"] helpviewer_keywords: ["feupdateenv function"] ms.assetid: 3d170042-dfd5-4e4f-a55f-038cf2296cc9 --- -# feupdateenv +# `feupdateenv` Saves the currently raised floating-point exceptions, restores the specified floating-point environment state, and then raises the saved floating-point exceptions. @@ -23,30 +23,30 @@ int feupdateenv( ### Parameters -*penv*
-Pointer to a **fenv_t** object that contains a floating-point environment as set by a call to [fegetenv](fegetenv1.md) or [feholdexcept](feholdexcept2.md). You can also specify the default startup floating-point environment by using the FE_DFL_ENV macro. +*`penv`*\ +Pointer to a `fenv_t` object that contains a floating-point environment as set by a call to [`fegetenv`](fegetenv1.md) or [`feholdexcept`](feholdexcept2.md). You can also specify the default startup floating-point environment by using the `FE_DFL_ENV` macro. -## Return Value +## Return value -Returns 0 if all actions completed successfully. Otherwise, returns a nonzero value. +Returns 0 if all actions completed successfully. Otherwise, it returns a nonzero value. ## Remarks -The **feupdateenv** function performs multiple actions. First, it stores the current raised floating-point exception status flags in automatic storage. Then, it sets the current floating-point environment from the value stored in the **fenv_t** object pointed to by *penv*. If *penv* is not **FE_DFL_ENV** or does not point to a valid **fenv_t** object, subsequent behavior is undefined. Finally, **feupdateenv** raises the locally stored floating-point exceptions. +The **`feupdateenv`** function performs multiple actions. First, it stores the current raised floating-point exception status flags in automatic storage. Then, it sets the current floating-point environment from the value stored in the `fenv_t` object pointed to by *`penv`*. If *`penv`* isn't `FE_DFL_ENV` or doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. Finally, **`feupdateenv`** raises the locally stored floating-point exceptions. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feupdateenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feupdateenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[fegetenv](fegetenv1.md)
-[feclearexcept](feclearexcept1.md)
-[feholdexcept](feholdexcept2.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[`fegetenv`](fegetenv1.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fflush-nolock.md b/docs/c-runtime-library/reference/fflush-nolock.md index 289af553bd..4c83497bc9 100644 --- a/docs/c-runtime-library/reference/fflush-nolock.md +++ b/docs/c-runtime-library/reference/fflush-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fflush_nolock" title: "_fflush_nolock" +description: "Learn more about: _fflush_nolock" ms.date: "4/2/2020" api_name: ["_fflush_nolock", "_o__fflush_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fflush_nolock", "_fflush_nolock"] helpviewer_keywords: ["fflush_nolock function", "_fflush_nolock function", "streams, flushing", "flushing"] -ms.assetid: 5e33c4a1-b10c-4001-ad01-210757919291 --- -# _fflush_nolock +# `_fflush_nolock` -Flushes a stream without locking the thread. +Flushes a stream without locking. ## Syntax @@ -24,30 +23,30 @@ int _fflush_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -See [fflush](fflush.md). +See [`fflush`](fflush.md). ## Remarks -This function is a non-locking version of **fflush**. It is identical to **fflush** except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fflush`. It's identical to `fflush` except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fflush_nolock**|\| +| Function | Required header | +|---|---| +| **`_fflush_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[_flushall](flushall.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_flushall`](flushall.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fflush.md b/docs/c-runtime-library/reference/fflush.md index 09557214a8..46a2eefe19 100644 --- a/docs/c-runtime-library/reference/fflush.md +++ b/docs/c-runtime-library/reference/fflush.md @@ -3,14 +3,13 @@ description: "Learn more about: fflush" title: "fflush" ms.date: "4/2/2020" api_name: ["fflush", "_o_fflush"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fflush"] helpviewer_keywords: ["streams, flushing", "flushing", "fflush function"] -ms.assetid: 8bbc753f-dc74-4e77-b563-74da2835e92b --- -# fflush +# `fflush` Flushes a stream. @@ -24,37 +23,37 @@ int fflush( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**fflush** returns 0 if the buffer was successfully flushed. The value 0 is also returned in cases in which the specified stream has no buffer or is open for reading only. A return value of **EOF** indicates an error. +**`fflush`** returns 0 if the buffer was successfully flushed. The value 0 is also returned in cases in which the specified stream has no buffer or is open for reading only. A return value of `EOF` indicates an error. > [!NOTE] -> If **fflush** returns **EOF**, data may have been lost due to a write failure. When setting up a critical error handler, it is safest to turn buffering off with the **setvbuf** function or to use low-level I/O routines such as **_open**, **_close**, and **_write** instead of the stream I/O functions. +> If **`fflush`** returns `EOF`, data may have been lost due to a write failure. When setting up a critical error handler, it is safest to turn buffering off with the **`setvbuf`** function or to use low-level I/O routines such as **`_open`**, **`_close`**, and **`_write`** instead of the stream I/O functions. ## Remarks -The **fflush** function flushes the stream *stream*. If the stream was opened in write mode, or it was opened in update mode and the last operation was a write, the contents of the stream buffer are written to the underlying file or device and the buffer is discarded. If the stream was opened in read mode, or if the stream has no buffer, the call to **fflush** has no effect, and any buffer is retained. A call to **fflush** negates the effect of any prior call to **ungetc** for the stream. The stream remains open after the call. +The **`fflush`** function flushes the stream *`stream`*. If the stream was opened in write mode, or it was opened in update mode and the last operation was a write, **`fflush`** writes the contents of the stream buffer to the underlying file or device, and the buffer is discarded. If the stream was opened in read mode, or if the stream has no buffer, the call to **`fflush`** has no effect, and any buffer is retained. A call to **`fflush`** negates the effect of any prior call to **`ungetc`** for the stream. The stream remains open after the call. -If *stream* is **NULL**, the behavior is the same as a call to **fflush** on each open stream. All streams opened in write mode and all streams opened in update mode where the last operation was a write are flushed. The call has no effect on other streams. +If *`stream`* is `NULL`, the behavior is the same as a call to **`fflush`** on each open stream. All streams opened in write mode and all streams opened in update mode where the last operation was a write are flushed. The call has no effect on other streams. -Buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing the stream. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating-system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with COMMODE.OBJ. In the resulting executable file, calls to **_flushall** write the contents of all buffers to disk. Only **_flushall** and **fflush** are affected by COMMODE.OBJ. +Buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing the stream. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating-system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with `COMMODE.OBJ`. In the resulting executable file, calls to **`_flushall`** write the contents of all buffers to disk. Only **`_flushall`** and **`fflush`** are affected by `COMMODE.OBJ`. -For information about controlling the commit-to-disk feature, see [Stream I/O](../../c-runtime-library/stream-i-o.md), [fopen](fopen-wfopen.md), and [_fdopen](fdopen-wfdopen.md). +For information about controlling the commit-to-disk feature, see [Stream I/O](../stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). -This function locks the calling thread and is therefore thread-safe. For a non-locking version, see **_fflush_nolock**. +This function locks the calling thread and is therefore thread-safe. For a non-locking version, see **`_fflush_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fflush**|\| +| Function | Required header | +|---|---| +| **`fflush`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -108,7 +107,7 @@ User selected 5 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[_flushall](flushall.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_flushall`](flushall.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fgetc-fgetwc.md b/docs/c-runtime-library/reference/fgetc-fgetwc.md index 3cb59a03ae..d24916bb40 100644 --- a/docs/c-runtime-library/reference/fgetc-fgetwc.md +++ b/docs/c-runtime-library/reference/fgetc-fgetwc.md @@ -3,14 +3,14 @@ description: "Learn more about: fgetc, fgetwc" title: "fgetc, fgetwc" ms.date: "4/2/2020" api_name: ["fgetwc", "fgetc", "_o_fgetc", "_o_fgetwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgettc", "fgetwc", "fgetc"] helpviewer_keywords: ["fgettc function", "characters, reading", "_fgettc function", "fgetc function", "streams, reading characters from", "reading characters from streams", "fgetwc function"] ms.assetid: 13348b7b-dc86-421c-9d6c-611ca79c8338 --- -# fgetc, fgetwc +# `fgetc`, `fgetwc` Read a character from a stream. @@ -27,41 +27,41 @@ wint_t fgetwc( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**fgetc** returns the character read as an **`int`** or returns **EOF** to indicate an error or end of file. **fgetwc** returns, as a [wint_t](../../c-runtime-library/standard-types.md), the wide character that corresponds to the character read or returns **WEOF** to indicate an error or end of file. For both functions, use **feof** or **ferror** to distinguish between an error and an end-of-file condition. If a read error occurs, the error indicator for the stream is set. If *stream* is **NULL**, **fgetc** and **fgetwc** invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EOF**. +**`fgetc`** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **`fgetwc`** returns, as a [`wint_t`](../standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use `feof` or `ferror` to distinguish between an error and an end-of-file condition. If a read error occurs, the error indicator for the stream is set. If *`stream`* is `NULL`, **`fgetc`** and **`fgetwc`** invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EOF`. ## Remarks -Each of these functions reads a single character from the current position of the file associated with *stream*. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. +Each of these functions reads a single character from the current position of the file associated with *`stream`*. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. -**fgetc** is equivalent to **getc**, but is implemented only as a function, rather than as a function and a macro. +**`fgetc`** is equivalent to `getc`, but is implemented only as a function, rather than as a function and a macro. -**fgetwc** is the wide-character version of **fgetc**; it reads **c** as a multibyte character or a wide character according to whether *stream* is opened in text mode or binary mode. +**`fgetwc`** is the wide-character version of **`fgetc`**; it reads **c** as a multibyte character or a wide character when *`stream`* is opened in text mode or binary mode, respectively. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. -For more information about processing wide characters and multibyte characters in text and binary modes, see [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +For more information about processing wide characters and multibyte characters in text and binary modes, see [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_fgettc**|**fgetc**|**fgetc**|**fgetwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fgettc` | **`fgetc`** | **`fgetc`** | **`fgetwc`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fgetc**|\| -|**fgetwc**|\ or \| +| Function | Required header | +|---|---| +| **`fgetc`** | \ | +| **`fgetwc`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,6 +116,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md b/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md index 648bcbdf3f..59604586b6 100644 --- a/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md +++ b/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fgetc_nolock, _fgetwc_nolock" title: "_fgetc_nolock, _fgetwc_nolock" +description: "Learn more about: _fgetc_nolock, _fgetwc_nolock" ms.date: "4/2/2020" api_name: ["_fgetc_nolock", "_fgetwc_nolock", "_o__fgetc_nolock", "_o__fgetwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgetwc_nolock", "fgettc_nolock", "fgetwc_nolock", "_fgetc_nolock", "_fgettc_nolock", "fgetc_nolock"] helpviewer_keywords: ["fgetc_nolock function", "fgetwc_nolock function", "_fgetwc_nolock function", "characters, reading", "_fgetc_nolock function", "streams, reading characters from", "fgettc_nolock function", "reading characters from streams", "_fgettc_nolock function"] -ms.assetid: fb8e7c5b-4503-493a-879e-6a1db75aa114 --- -# _fgetc_nolock, _fgetwc_nolock +# `_fgetc_nolock`, `_fgetwc_nolock` -Reads a character from a stream without locking the thread. +Reads a character from a stream without locking. ## Syntax @@ -27,33 +26,33 @@ wint_t _fgetwc_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -See[fgetc, fgetwc](fgetc-fgetwc.md). +See[`fgetc`, `fgetwc`](fgetc-fgetwc.md). ## Remarks -**_fgetc_nolock** and **_fgetwc_nolock** are identical to **fgetc** and **fgetwc**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_fgetc_nolock`** and **`_fgetwc_nolock`** are identical to `fgetc` and `fgetwc`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettc_nolock**|**_fgetc_nolock**|**_fgetc_nolock**|**_fgetwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_fgettc_nolock`** | **`_fgetc_nolock`** | **`_fgetc_nolock`** | **`_fgetwc_nolock`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fgetc_nolock**|\| -|**_fgetwc_nolock**|\ or \| +| Function | Required header | +|---|---| +| **`_fgetc_nolock`** | \ | +| **`_fgetwc_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -107,6 +106,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md index 2f110ed4a9..31a0e36791 100644 --- a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md +++ b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md @@ -3,16 +3,16 @@ description: "Learn more about: _fgetchar, _fgetwchar" title: "_fgetchar, _fgetwchar" ms.date: "4/2/2020" api_name: ["_fgetchar", "_fgetwchar", "_o__fgetchar", "_o__fgetwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fgetwchar", "_fgettchar", "_fgetchar", "_fgetwchar", "fgettchar"] helpviewer_keywords: ["fgetwchar function", "_fgetchar function", "fgettchar function", "_fgetwchar function", "_fgettchar function", "standard input, reading from", "fgetchar function"] ms.assetid: 8bce874c-701a-41a3-b1b2-feff266fb5b9 --- -# _fgetchar, _fgetwchar +# `_fgetchar`, `_fgetwchar` -Reads a character from **stdin**. +Reads a character from `stdin`. ## Syntax @@ -21,34 +21,34 @@ int _fgetchar( void ); wint_t _fgetwchar( void ); ``` -## Return Value +## Return value -**\_fgetchar** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **\_fgetwchar** returns, as a [wint_t](../../c-runtime-library/standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use **feof** or **ferror** to distinguish between an error and an end-of-file condition. +**\_fgetchar** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **\_fgetwchar** returns, as a [`wint_t`](../standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use `feof` or `ferror` to distinguish between an error and an end-of-file condition. ## Remarks -These functions read a single character from **stdin**. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. +These functions read a single character from `stdin`. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. -**_fgetchar** is equivalent to `fgetc( stdin )`. It is also equivalent to **getchar**, but implemented only as a function, rather than as a function and a macro. **_fgetwchar** is the wide-character version of **_fgetchar**. +**`_fgetchar`** is equivalent to `fgetc( stdin )`. It's also equivalent to `getchar`, but implemented only as a function, rather than as a function and a macro. **`_fgetwchar`** is the wide-character version of **`_fgetchar`**. -These functions are not compatible with the ANSI standard. +These functions aren't compatible with the ANSI standard. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettchar**|**_fgetchar**|**_fgetchar**|**_fgetwchar**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fgettchar` | **`_fgetchar`** | **`_fgetchar`** | **`_fgetwchar`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fgetchar**|\| -|**_fgetwchar**|\ or \| +| Function | Required header | +|---|---| +| **`_fgetchar`** | \ | +| **`_fgetwchar`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**stdin**, **stdout**, and **stderr**—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—`stdin`, `stdout`, and `stderr`—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -90,6 +90,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetchar.md b/docs/c-runtime-library/reference/fgetchar.md index b28afc3c0b..ece234801c 100644 --- a/docs/c-runtime-library/reference/fgetchar.md +++ b/docs/c-runtime-library/reference/fgetchar.md @@ -10,8 +10,8 @@ f1_keywords: ["fgetchar"] helpviewer_keywords: ["fgetchar function"] ms.assetid: 2b27a6f2-d973-4d12-a66d-7e6b01e84470 --- -# fgetchar +# `fgetchar` -The Microsoft-specific function name `fgetchar` is a deprecated alias for the [_fgetchar](fgetchar-fgetwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fgetchar` is a deprecated alias for the [`_fgetchar`](fgetchar-fgetwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fgetchar](fgetchar-fgetwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fgetchar`](fgetchar-fgetwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fgetpos.md b/docs/c-runtime-library/reference/fgetpos.md index 06aea4ce3c..8f504d4477 100644 --- a/docs/c-runtime-library/reference/fgetpos.md +++ b/docs/c-runtime-library/reference/fgetpos.md @@ -3,14 +3,14 @@ description: "Learn more about: fgetpos" title: "fgetpos" ms.date: "4/2/2020" api_name: ["fgetpos", "_o_fgetpos"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fgetpos"] helpviewer_keywords: ["fgetpos function", "streams, file position indicator"] ms.assetid: bfa05c38-1135-418c-bda1-d41be51acb62 --- -# fgetpos +# `fgetpos` Gets a stream's file-position indicator. @@ -25,29 +25,29 @@ int fgetpos( ### Parameters -*stream*
+*`stream`*\ Target stream. -*pos*
+*`pos`*\ Position-indicator storage. -## Return Value +## Return value -If successful, **fgetpos** returns 0. On failure, it returns a nonzero value and sets **errno** to one of the following manifest constants (defined in STDIO.H): **EBADF**, which means the specified stream is not a valid file pointer or is not accessible, or **EINVAL**, which means the *stream* value or the value of *pos* is invalid, such as if either is a null pointer. If *stream* or *pos* is a **NULL** pointer, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If successful, **`fgetpos`** returns 0. On failure, it returns a nonzero value and sets `errno` to one of the following manifest constants (defined in STDIO.H): `EBADF`, which means the specified stream isn't a valid file pointer or isn't accessible, or `EINVAL`, which means the *`stream`* value or the value of *`pos`* is invalid, such as if either is a null pointer. If *`stream`* or *`pos`* is a `NULL` pointer, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -The **fgetpos** function gets the current value of the *stream* argument's file-position indicator and stores it in the object pointed to by *pos*. The **fsetpos** function can later use information stored in *pos* to reset the *stream* argument's pointer to its position at the time **fgetpos** was called. The *pos* value is stored in an internal format and is intended for use only by **fgetpos** and **fsetpos**. +The **`fgetpos`** function gets the current value of the *`stream`* argument's file-position indicator and stores it in the object pointed to by *`pos`*. The `fsetpos` function can later use information stored in *`pos`* to reset the *`stream`* argument's pointer to its position at the time **`fgetpos`** was called. The *`pos`* value is stored in an internal format and is intended for use only by **`fgetpos`** and `fsetpos`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fgetpos**|\| +| Function | Required header | +|---|---| +| **`fgetpos`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,5 +106,5 @@ after fsetpos: gets a stream ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fsetpos](fsetpos.md)
+[Stream I/O](../stream-i-o.md)\ +[`fsetpos`](fsetpos.md) diff --git a/docs/c-runtime-library/reference/fgets-fgetws.md b/docs/c-runtime-library/reference/fgets-fgetws.md index 79cc1afd53..0467e7281d 100644 --- a/docs/c-runtime-library/reference/fgets-fgetws.md +++ b/docs/c-runtime-library/reference/fgets-fgetws.md @@ -3,7 +3,7 @@ description: "Learn more about: fgets, fgetws" title: "fgets, fgetws" ms.date: "4/2/2020" api_name: ["fgets", "fgetws", "_o_fgets", "_o_fgetws"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgetts", "fgetws", "fgets"] @@ -31,20 +31,20 @@ wchar_t *fgetws( ### Parameters -*`str`*
+*`str`*\ Storage location for data. -*`numChars`*
+*`numChars`*\ Maximum number of characters to read. -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -Each of these functions returns *`str`*. **`NULL`** is returned to indicate an error or an end-of-file condition. Use **`feof`** or **`ferror`** to determine whether an error occurred. If *`str`* or *`stream`* is a null pointer, or *`numChars`* is less than or equal to zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`errno`** is set to **`EINVAL`** and the function returns **`NULL`**. +Each of these functions returns *`str`*. `NULL` is returned to indicate an error or an end-of-file condition. Use **`feof`** or **`ferror`** to determine whether an error occurred. If *`str`* or *`stream`* is a null pointer, or *`numChars`* is less than or equal to zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -52,24 +52,24 @@ The **`fgets`** function reads a string from the input *`stream`* argument and s **`fgetws`** is a wide-character version of **`fgets`**. -**`fgetws`** reads the wide-character argument *`str`* as a multibyte-character string or a wide-character string according to whether *`stream`* is opened in text mode or binary mode, respectively. For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +**`fgetws`** reads the wide-character argument *`str`* as a multibyte-character string or as a wide-character string when *`stream`* is opened in text mode or binary mode, respectively. For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_fgetts`**|**`fgets`**|**`fgets`**|**`fgetws`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_fgetts`** | **`fgets`** | **`fgets`** | **`fgetws`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fgets`**|``| -|**`fgetws`**|`` or ``| +| Function | Required header | +|---|---| +| **`fgets`** | `` | +| **`fgetws`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -111,7 +111,7 @@ Line one. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fputs`, `fputws`](fputs-fputws.md)
-[`gets`, `_getws`](../../c-runtime-library/gets-getws.md)
-[`puts`, `_putws`](puts-putws.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputs`, `fputws`](fputs-fputws.md)\ +[`gets`, `_getws`](../gets-getws.md)\ +[`puts`, `_putws`](puts-putws.md) diff --git a/docs/c-runtime-library/reference/filelength-filelengthi64.md b/docs/c-runtime-library/reference/filelength-filelengthi64.md index cd39c3b101..e364ec9fcd 100644 --- a/docs/c-runtime-library/reference/filelength-filelengthi64.md +++ b/docs/c-runtime-library/reference/filelength-filelengthi64.md @@ -3,14 +3,14 @@ description: "Learn more about: _filelength, _filelengthi64" title: "_filelength, _filelengthi64" ms.date: "4/2/2020" api_name: ["_filelengthi64", "_filelength", "_o__filelength", "_o__filelengthi64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_filelength", "_filelengthi64", "filelengthi64"] helpviewer_keywords: ["filelengthi64 function", "lengths, file", "filelength function", "_filelength function", "files [C++], length", "_filelengthi64 function"] ms.assetid: 3ab83d5a-543c-4079-b9d9-0abfc7da0275 --- -# _filelength, _filelengthi64 +# `_filelength`, `_filelengthi64` Gets the length of a file. @@ -27,34 +27,34 @@ __int64 _filelengthi64( ### Parameters -*fd*
+*`fd`*\ Target the file descriptor. -## Return Value +## Return value -Both **_filelength** and **_filelengthi64** return the file length, in bytes, of the target file associated with *fd*. If *fd* is an invalid file descriptor, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, both functions return -1L to indicate an error and set **errno** to **EBADF**. +Both **`_filelength`** and **`_filelengthi64`** return the file length, in bytes, of the target file associated with *`fd`*. If *`fd`* is an invalid file descriptor, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, both functions return -1L to indicate an error and set `errno` to `EBADF`. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_filelength**|\| -|**_filelengthi64**|\| +| Function | Required header | +|---|---| +| **`_filelength`** | \ | +| **`_filelengthi64`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_chsize](chsize.md). +See the example for [`_chsize`](chsize.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_chsize](chsize.md)
-[_fileno](fileno.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_stat, _wstat Functions](stat-functions.md)
+[File handling](../file-handling.md)\ +[`_chsize`](chsize.md)\ +[`_fileno`](fileno.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/filelength.md b/docs/c-runtime-library/reference/filelength.md index 0d42b7b3be..566d02a67f 100644 --- a/docs/c-runtime-library/reference/filelength.md +++ b/docs/c-runtime-library/reference/filelength.md @@ -10,8 +10,8 @@ f1_keywords: ["filelength"] helpviewer_keywords: ["filelength function"] ms.assetid: 5fbc1912-7822-498d-bbf4-8bada87cf9b9 --- -# filelength +# `filelength` -The Microsoft-specific function name `filelength` is a deprecated alias for the [_filelength](filelength-filelengthi64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `filelength` is a deprecated alias for the [`_filelength`](filelength-filelengthi64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_filelength](filelength-filelengthi64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_filelength`](filelength-filelengthi64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fileno.md b/docs/c-runtime-library/reference/fileno.md index 76a0f85671..2752c38476 100644 --- a/docs/c-runtime-library/reference/fileno.md +++ b/docs/c-runtime-library/reference/fileno.md @@ -3,14 +3,13 @@ title: "_fileno" description: "API reference for _fileno; which gets the file descriptor associated with a stream." ms.date: "4/2/2020" api_name: ["_fileno", "_o__fileno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fileno"] helpviewer_keywords: ["file handles [C++], getting from streams", "fileno function", "_fileno function", "streams, getting file handles"] -ms.assetid: 86474174-2f17-4100-bcc4-352dd976c7b5 --- -# _fileno +# `_fileno` Gets the file descriptor associated with a stream. @@ -24,31 +23,31 @@ int _fileno( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -**_fileno** returns the file descriptor. There's no error return. The result is undefined if *stream* does not specify an open file. If stream is **NULL**, **_fileno** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets **errno** to **EINVAL**. +**`_fileno`** returns the file descriptor. There's no error return. The result is undefined if *`stream`* doesn't specify an open file. If stream is `NULL`, **`_fileno`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets `errno` to `EINVAL`. -For more information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). > [!NOTE] -> If **stdout** or **stderr** is not associated with an output stream (for example, in a Windows application without a console window), the file descriptor returned is -2. In previous versions, the file descriptor returned was -1. This change allows applications to distinguish this condition from an error. +> If **`stdout`** or **`stderr`** is not associated with an output stream (for example, in a Windows application without a console window), the file descriptor returned is -2. In previous versions, the file descriptor returned was -1. This change allows applications to distinguish this condition from an error. ## Remarks -The **_fileno** routine returns the file descriptor currently associated with *stream*. This routine is implemented both as a function and as a macro. For information about choosing either implementation, see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md). +The **`_fileno`** routine returns the file descriptor currently associated with *`stream`*. This routine is implemented both as a function and as a macro. For information about choosing either implementation, see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fileno**|\| +| Function | Required header | +|---|---| +| **`_fileno`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -76,8 +75,8 @@ The file descriptor for stderr is 2 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_fdopen, _wfdopen](fdopen-wfdopen.md)
-[_filelength, _filelengthi64](filelength-filelengthi64.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[freopen, _wfreopen](freopen-wfreopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`_filelength`, `_filelengthi64`](filelength-filelengthi64.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md) diff --git a/docs/c-runtime-library/reference/findclose.md b/docs/c-runtime-library/reference/findclose.md index 3284bf7187..6d7b4d6c81 100644 --- a/docs/c-runtime-library/reference/findclose.md +++ b/docs/c-runtime-library/reference/findclose.md @@ -3,14 +3,14 @@ description: "Learn more about: _findclose" title: "_findclose" ms.date: "4/2/2020" api_name: ["_findclose", "_o__findclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_findclose", "findclose"] helpviewer_keywords: ["_findclose function", "findclose function"] ms.assetid: 9216c573-0878-444c-b5d7-cdaf16fb9163 --- -# _findclose +# `_findclose` Closes the specified search handle and releases associated resources. @@ -24,26 +24,26 @@ int _findclose( ### Parameters -*handle*
-Search handle returned by a previous call to **_findfirst**. +*`handle`*\ +The search handle returned by a previous call to `_findfirst`. -## Return Value +## Return value -If successful, **_findclose** returns 0. Otherwise, it returns -1 and sets **errno** to **ENOENT**, indicating that no more matching files could be found. +If successful, **`_findclose`** returns 0. Otherwise, it returns -1 and sets `errno` to `ENOENT`, indicating that no more matching files could be found. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_findclose**|\| +| Function | Required header | +|---|---| +| **`_findclose`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/findfirst-functions.md b/docs/c-runtime-library/reference/findfirst-functions.md index 235a55a87a..dcfbffe363 100644 --- a/docs/c-runtime-library/reference/findfirst-functions.md +++ b/docs/c-runtime-library/reference/findfirst-functions.md @@ -1,14 +1,13 @@ --- description: "Learn more about: _findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64" title: "_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64" -ms.date: "4/2/2020" +ms.date: 12/09/2022 api_name: ["_findfirst", "_wfindfirst", "_findfirst32", "_wfindfirst32", "_findfirst32i64", "_wfindfirst32i64", "_findfirst64", "_wfindfirst64", "_findfirst64i32", "_wfindfirst64i32", "_findfirsti64", "_wfindfirsti64", "_o__findfirst32", "_o__findfirst32i64", "_o__findfirst64", "_o__findfirst64i32", "_o__wfindfirst32", "_o__wfindfirst32i64", "_o__wfindfirst64", "_o__wfindfirst64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["findfirst32i64", "wfindfirst32i64", "tfindfirst64", "_findfirst64i32", "_wfindfirst32i64", "_wfindfirsti64", "wfindfirst", "_tfindfirsti64", "findfirst32", "_tfindfirst32", "_findfirsti64", "findfirst", "wfindfirst64", "wfindfirst32", "tfindfirst32", "_wfindfirst64i32", "findfirst64i32", "tfindfirst64i32", "_wfindfirst", "findfirsti64", "_findfirst32i64", "wfindfirst64i32", "_wfindfirst32", "_findfirst32", "_tfindfirst32i64", "tfindfirst", "_tfindfirst64i32", "findfirst64", "_tfindfirst", "_findfirst64", "_tfindfirst64", "tfindfirst32i64", "_findfirst", "_wfindfirst64"] helpviewer_keywords: ["_tfindfirst64 function", "_wfindfirst64i32 function", "_wfindfirst32i64 function", "wfindfirst32 function", "_findfirst function", "wfindfirst64 function", "_wfindfirst function", "_findfirst64i32 function", "wfindfirst function", "_findfirst64 function", "tfindfirst32 function", "_tfindfirst64i32 function", "findfirst function", "findfirst32i64 function", "tfindfirst64 function", "_tfindfirst32 function", "tfindfirst32i64 function", "tfindfirst64i32 function", "_wfindfirsti64 function", "_findfirst32i64 function", "findfirst32 function", "findfirsti64 function", "findfirst64i32 function", "tfindfirsti64 function", "tfindfirst function", "_wfindfirst32 function", "wfindfirsti64 function", "_tfindfirsti64 function", "_tfindfirst function", "_tfindfirst32i64 function", "findfirst64 function", "_findfirst32 function", "_findfirsti64 function", "wfindfirst32i64 function", "wfindfirst64i32 function", "_wfindfirst64 function"] -ms.assetid: 9bb46d1a-b946-47de-845a-a0b109a33ead --- # `_findfirst`, `_findfirst32`, `_findfirst32i64`, `_findfirst64`, `_findfirst64i32`, `_findfirsti64`, `_wfindfirst`, `_wfindfirst32`, `_wfindfirst32i64`, `_wfindfirst64`, `_wfindfirst64i32`, `_wfindfirsti64` @@ -69,87 +68,87 @@ intptr_t _wfindfirst64i32( ### Parameters -*`filespec`*
+*`filespec`*\ Target file specification (can include wildcard characters). -*`fileinfo`*
-File information buffer. +*`fileinfo`*\ +File information buffer. For more information about the `fileinfo` structs, see the Remarks in [Filename search functions](../filename-search-functions.md) and see [Data type mappings](../data-type-mappings.md). The structs are defined in the same header file as the function that uses them as a parameter. -## Return Value +## Return value -If successful, **`_findfirst`** returns a unique search handle identifying the file or group of files that match the *`filespec`* specification, which can be used in a subsequent call to [`_findnext`](findnext-functions.md) or to [`_findclose`](findclose.md). Otherwise, **`_findfirst`** returns -1 and sets **`errno`** to one of the following values. +If successful, **`_findfirst`** returns a unique search handle identifying the file or group of files that match the *`filespec`* specification, which can be used in a subsequent call to [`_findnext`](findnext-functions.md) or to [`_findclose`](findclose.md). Otherwise, **`_findfirst`** returns -1 and sets `errno` to one of the following values. | errno value | Condition | |-|-| -| **`EINVAL`** | Invalid parameter: *`filespec`* or *`fileinfo`* was **`NULL`**. Or, the operating system returned an unexpected error. | -| **`ENOENT`** | File specification that could not be matched. | -| **`ENOMEM`** | Insufficient memory. | -| **`EINVAL`** | Invalid file name specification or the file name given was larger than **`MAX_PATH`**. | +| `EINVAL` | Invalid parameter: *`filespec`* or *`fileinfo`* was `NULL`. Or, the operating system returned an unexpected error. | +| `ENOENT` | File specification that couldn't be matched. | +| `ENOMEM` | Insufficient memory. | +| `EINVAL` | Invalid file name specification or the file name given was larger than `MAX_PATH`. | -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -You must call [`_findclose`](findclose.md) after you are finished with either the **`_findfirst`** or [`_findnext`](findnext-functions.md) function (or any variants). This frees resources used by these functions in your application. +You must call [`_findclose`](findclose.md) after you're finished with either the **`_findfirst`** or [`_findnext`](findnext-functions.md) function (or any variants) provided the call to `_findfirst` succeeded. `_findclose` frees resources used by these functions in your application. Calling `_findclose` on an invalid handle returns `-1` and sets `errno` to `EINVAL`. -The variations of these functions that have the **`w`** prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions. +The variations of these functions that have the **`w`** prefix are wide-character versions; otherwise, they're identical to the corresponding single-byte functions. -Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numeric suffix (**`32`** or **`64`**) indicates the size of the time type; the second suffix is either **`i32`** or **`i64`**, and indicates whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The **`i32`** or **`i64`** suffix is omitted if it is the same as the size of the time type, so **`_findfirst64`** also supports 64-bit file lengths and **`_findfirst32`** supports only 32-bit file lengths. +Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numeric suffix (**`32`** or **`64`**) indicates the size of the time type; the second suffix is either **`i32`** or **`i64`**, and indicates whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The **`i32`** or **`i64`** suffix is omitted if it's the same as the size of the time type, so **`_findfirst64`** also supports 64-bit file lengths and **`_findfirst32`** supports only 32-bit file lengths. -These functions use various forms of the **`_finddata_t`** structure for the *`fileinfo`* parameter. For more information about the structure, see [Filename Search Functions](../../c-runtime-library/filename-search-functions.md). +These functions use various forms of the **`_finddata_t`** structure for the *`fileinfo`* parameter. For more information about the structure, see [Filename search functions](../filename-search-functions.md). -The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. Those that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. The ones that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this is a breaking change for an application, you might define **`_USE_32BIT_TIME_T`** to revert to the old behavior. If **`_USE_32BIT_TIME_T`** is defined, **`_findfirst`**, **`_finfirsti64`**, and their corresponding Unicode versions use a 32-bit time. +Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define `_USE_32BIT_TIME_T` to revert to the old behavior. If `_USE_32BIT_TIME_T` is defined, **`_findfirst`**, **`_findfirsti64`**, and their corresponding Unicode versions use a 32-bit time. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Time Type and File Length Type Variations of _findfirst -|Functions|**`_USE_32BIT_TIME_T`** defined?|Time type|File length type| -|---------------|----------------------------------|---------------|----------------------| -|**`_findfirst`**, **`_wfindfirst`**|Not defined|64-bit|32-bit| -|**`_findfirst`**, **`_wfindfirst`**|Defined|32-bit|32-bit| -|**`_findfirst32`**, **`_wfindfirst32`**|Not affected by the macro definition|32-bit|32-bit| -|**`_findfirst64`**, **`_wfindfirst64`**|Not affected by the macro definition|64-bit|64-bit| -|**`_findfirsti64`**, **`_wfindfirsti64`**|Not defined|64-bit|64-bit| -|**`_findfirsti64`**, **`_wfindfirsti64`**|Defined|32-bit|64-bit| -|**`_findfirst32i64`**, **`_wfindfirst32i64`**|Not affected by the macro definition|32-bit|64-bit| -|**`_findfirst64i32`**, **`_wfindfirst64i32`**|Not affected by the macro definition|64-bit|32-bit| - -### Generic-Text Routine Mappings - -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tfindfirst`**|**`_findfirst`**|**`_findfirst`**|**`_wfindfirst`**| -|**`_tfindfirst32`**|**`_findfirst32`**|**`_findfirst32`**|**`_wfindfirst32`**| -|**`_tfindfirst64`**|**`_findfirst64`**|**`_findfirst64`**|**`_wfindfirst64`**| -|**`_tfindfirsti64`**|**`_findfirsti64`**|**`_findfirsti64`**|**`_wfindfirsti64`**| -|**`_tfindfirst32i64`**|**`_findfirst32i64`**|**`_findfirst32i64`**|**`_wfindfirst32i64`**| -|**`_tfindfirst64i32`**|**`_findfirst64i32`**|**`_findfirst64i32`**|**`_wfindfirst64i32`**| +| Functions | `_USE_32BIT_TIME_T` defined? | Time type | File length type | +|---|---|---|---| +| **`_findfirst`**, **`_wfindfirst`** | Not defined | 64-bit | 32-bit | +| **`_findfirst`**, **`_wfindfirst`** | Defined | 32-bit | 32-bit | +| **`_findfirst32`**, **`_wfindfirst32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_findfirst64`**, **`_wfindfirst64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_findfirsti64`**, **`_wfindfirsti64`** | Not defined | 64-bit | 64-bit | +| **`_findfirsti64`**, **`_wfindfirsti64`** | Defined | 32-bit | 64-bit | +| **`_findfirst32i64`**, **`_wfindfirst32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_findfirst64i32`**, **`_wfindfirst64i32`** | Not affected by the macro definition | 64-bit | 32-bit | + +### Generic-text routine mappings + +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tfindfirst`** | **`_findfirst`** | **`_findfirst`** | **`_wfindfirst`** | +| **`_tfindfirst32`** | **`_findfirst32`** | **`_findfirst32`** | **`_wfindfirst32`** | +| **`_tfindfirst64`** | **`_findfirst64`** | **`_findfirst64`** | **`_wfindfirst64`** | +| **`_tfindfirsti64`** | **`_findfirsti64`** | **`_findfirsti64`** | **`_wfindfirsti64`** | +| **`_tfindfirst32i64`** | **`_findfirst32i64`** | **`_findfirst32i64`** | **`_wfindfirst32i64`** | +| **`_tfindfirst64i32`** | **`_findfirst64i32`** | **`_findfirst64i32`** | **`_wfindfirst64i32`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_findfirst`**|``| -|**`_findfirst32`**|``| -|**`_findfirst64`**|``| -|**`_findfirsti64`**|``| -|**`_findfirst32i64`**|``| -|**`_findfirst64i32`**|``| -|**`_wfindfirst`**|`` or ``| -|**`_wfindfirst32`**|`` or ``| -|**`_wfindfirst64`**|`` or ``| -|**`_wfindfirsti64`**|`` or ``| -|**`_wfindfirst32i64`**|`` or ``| -|**`_wfindfirst64i32`**|`` or ``| - -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| Function | Required header | +|---|---| +| **`_findfirst`** | `` | +| **`_findfirst32`** | `` | +| **`_findfirst64`** | `` | +| **`_findfirsti64`** | `` | +| **`_findfirst32i64`** | `` | +| **`_findfirst64i32`** | `` | +| **`_wfindfirst`** | `` or `` | +| **`_wfindfirst32`** | `` or `` | +| **`_wfindfirst64`** | `` or `` | +| **`_wfindfirsti64`** | `` or `` | +| **`_wfindfirst32i64`** | `` or `` | +| **`_wfindfirst64i32`** | `` or `` | + +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/findnext-functions.md b/docs/c-runtime-library/reference/findnext-functions.md index 71efb3b7d9..bcc7d4333b 100644 --- a/docs/c-runtime-library/reference/findnext-functions.md +++ b/docs/c-runtime-library/reference/findnext-functions.md @@ -3,16 +3,16 @@ description: "Learn more about: _findnext, _findnext32, _findnext32i64, _findnex title: "_findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64" ms.date: "4/2/2020" api_name: [_findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64, "_o__findnext32", "_o__findnext32i64", "_o__findnext64", "_o__findnext64i32", "_o__wfindnext32", "_o__wfindnext32i64", "_o__wfindnext64", "_o__wfindnext64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["findnext", "_wfindnext32i64", "_tfindnext64i32", "findnext32", "findnext32i64", "wfindnext64i32", "_wfindnext", "tfindnext64", "findnexti64", "_findnexti64", "_tfindnexti64", "_findnext64i32", "tfindnexti64", "tfindnext32", "_wfindnext64i32", "findnext64i32", "_findnext", "_tfindnext32i64", "_wfindnext64", "wfindnext", "wfindnext32", "tfindnext32i64", "_findnext64", "_tfindnext64", "_wfindnext32", "findnext64", "_findnext32i64", "tfindnext", "wfindnexti64", "tfindnext64i32", "_tfindnext32", "wfindnext32i64", "wfindnext64", "_wfindnexti64", "_tfindnext", "_findnext32"] helpviewer_keywords: ["_wfindnexti64 function", "_tfindnext32 function", "wfindnexti64 function", "_wfindnext32i64 function", "findnext32i64 function", "tfindnext64i32 function", "_tfindnext64i32 function", "_findnext function", "findnext64i32 function", "_tfindnext function", "findnext32 function", "tfindnext32 function", "_findnext32 function", "_tfindnext32i64 function", "_wfindnext function", "tfindnext function", "_findnext64 function", "findnext64 function", "_findnext64i32 function", "wfindnext32i64 function", "findnext function", "wfindnext32 function", "_wfindnext64i32 function", "findnexti64 function", "_wfindnext64 function", "_findnext32i64 function", "_findnexti64 function", "_tfindnext64 function", "wfindnext64i32 function", "tfindnexti64 function", "wfindnext64 function", "wfindnext function", "tfindnext64 function", "_wfindnext32 function", "tfindnext32i64 function", "_tfindnexti64 function"] ms.assetid: 75d97188-5add-4698-a46c-4c492378f0f8 --- -# _findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64 +# `_findnext`, `_findnext32`, `_findnext32i64`, `_findnext64`, `_findnext64i32`, `_findnexti64`, `_wfindnext`, `_wfindnext32`, `_wfindnext32i64`, `_wfindnext64`, `_wfindnext64i32`, `_wfindnexti64` -Find the next name, if any, that matches the *filespec* argument in a previous call to [_findfirst](findfirst-functions.md), and then alter the *fileinfo* structure contents accordingly. +Find the next name, if any, that matches the *`filespec`* argument in a previous call to [`_findfirst`](findfirst-functions.md), and then alter the *`fileinfo`* structure contents accordingly. ## Syntax @@ -69,84 +69,84 @@ int _wfindnext64i32( ### Parameters -*handle*
-Search handle returned by a previous call to **_findfirst**. +*`handle`*\ +The search handle returned by a previous call to `_findfirst`. -*fileinfo*
+*`fileinfo`*\ File information buffer. -## Return Value +## Return value -If successful, returns 0. Otherwise, returns -1 and sets **errno** to a value indicating the nature of the failure. Possible error codes are shown in the following table. +If successful, returns 0. Otherwise, returns -1 and sets `errno` to a value indicating the nature of the failure. Possible error codes are shown in the following table. -|errno value|Condition| -|-|-| -| **EINVAL** | Invalid parameter: *fileinfo* was **NULL**. Or, the operating system returned an unexpected error. | -| **ENOENT** | No more matching files could be found. | -| **ENOMEM** | Not enough memory or the file name's length exceeded **MAX_PATH**. | +| `errno` value | Condition | +|---|---| +| `EINVAL` | Invalid parameter: *`fileinfo`* was `NULL`. Or, the operating system returned an unexpected error. | +| `ENOENT` | No more matching files could be found. | +| `ENOMEM` | Not enough memory or the file name's length exceeded `MAX_PATH`. | -If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -You must call [_findclose](findclose.md) after you are finished using either the **_findfirst** or **_findnext** function (or any variants). This frees up resources used by these functions in your application. +You must call [`_findclose`](findclose.md) after you're finished using either the `_findfirst` or **`_findnext`** function (or any variants). `_findclose` frees up resources used by these functions in your application. -The variations of these functions with the **w** prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions. +The variations of these functions with the **w** prefix are wide-character versions; otherwise, they're identical to the corresponding single-byte functions. -Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numerical suffix (**32** or **64**) indicates the size of the time type used; the second suffix is either **i32** or **i64**, indicating whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The variations that use a 64-bit time type allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas those using 32-bit time types only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numerical suffix (**`32`** or **`64`**) indicates the size of the time type used; the second suffix is either **`i32`** or **`i64`**, indicating whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The variations that use a 64-bit time type allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas those using 32-bit time types only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -Unless you have a specific reason to use the versions that specify the time size explicitly, use **_findnext** or **_wfindnext** or, if you need to support file sizes greater than 3 GB, use **_findnexti64** or **_wfindnexti64**. All these functions use the 64-bit time type. In previous versions, these functions used a 32-bit time type. If this is a breaking change for an application, you might define **_USE_32BIT_TIME_T** to get the old behavior. If **_USE_32BIT_TIME_T** is defined, **_findnext**, **_finnexti64** and their corresponding Unicode versions use a 32-bit time. +Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findnext`** or **`_wfindnext`** or, if you need to support file sizes greater than 3 GB, use **`_findnexti64`** or **`_wfindnexti64`**. All these functions use the 64-bit time type. In previous versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define `_USE_32BIT_TIME_T` to get the old behavior. If `_USE_32BIT_TIME_T` is defined, **`_findnext`**, **`_findnexti64`** and their corresponding Unicode versions use a 32-bit time. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Time Type and File Length Type Variations of _findnext -|Functions|**_USE_32BIT_TIME_T** defined?|Time type|File length type| -|---------------|----------------------------------|---------------|----------------------| -|**_findnext**, **_wfindnext**|Not defined|64-bit|32-bit| -|**_findnext**, **_wfindnext**|Defined|32-bit|32-bit| -|**_findnext32**, **_wfindnext32**|Not affected by the macro definition|32-bit|32-bit| -|**_findnext64**, **_wfindnext64**|Not affected by the macro definition|64-bit|64-bit| -|**_findnexti64**, **_wfindnexti64**|Not defined|64-bit|64-bit| -|**_findnexti64**, **_wfindnexti64**|Defined|32-bit|64-bit| -|**_findnext32i64**, **_wfindnext32i64**|Not affected by the macro definition|32-bit|64-bit| -|**_findnext64i32**, **_wfindnext64i32**|Not affected by the macro definition|64-bit|32-bit| - -### Generic-Text Routine Mappings - -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfindnext**|**_findnext**|**_findnext**|**_wfindnext**| -|**_tfindnext32**|**_findnext32**|**_findnext32**|**_wfindnext32**| -|**_tfindnext64**|**_findnext64**|**_findnext64**|**_wfindnext64**| -|**_tfindnexti64**|**_findnexti64**|**_findnexti64**|**_wfindnexti64**| -|**_tfindnext32i64**|**_findnext32i64**|**_findnext32i64**|**_wfindnext32i64**| -|**_tfindnext64i32**|**_findnext64i32**|**_findnext64i32**|**_wfindnext64i32**| +| Functions | `_USE_32BIT_TIME_T` defined? | Time type | File length type | +|---|---|---|---| +| **`_findnext`**, **`_wfindnext`** | Not defined | 64-bit | 32-bit | +| **`_findnext`**, **`_wfindnext`** | Defined | 32-bit | 32-bit | +| **`_findnext32`**, **`_wfindnext32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_findnext64`**, **`_wfindnext64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_findnexti64`**, **`_wfindnexti64`** | Not defined | 64-bit | 64-bit | +| **`_findnexti64`**, **`_wfindnexti64`** | Defined | 32-bit | 64-bit | +| **`_findnext32i64`**, **`_wfindnext32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_findnext64i32`**, **`_wfindnext64i32`** | Not affected by the macro definition | 64-bit | 32-bit | + +### Generic-text routine mappings + +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tfindnext` | **`_findnext`** | **`_findnext`** | **`_wfindnext`** | +| `_tfindnext32` | **`_findnext32`** | **`_findnext32`** | **`_wfindnext32`** | +| `_tfindnext64` | **`_findnext64`** | **`_findnext64`** | **`_wfindnext64`** | +| `_tfindnexti64` | **`_findnexti64`** | **`_findnexti64`** | **`_wfindnexti64`** | +| **`_tfindnext32i64`** | **`_findnext32i64`** | **`_findnext32i64`** | **`_wfindnext32i64`** | +| **`_tfindnext64i32`** | **`_findnext64i32`** | **`_findnext64i32`** | **`_wfindnext64i32`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_findnext**|\| -|**_findnext32**|\| -|**_findnext64**|\| -|**_findnexti64**|\| -|**_findnext32i64**|\| -|**_findnext64i32**|\| -|**_wfindnext**|\ or \| -|**_wfindnext32**|\ or \| -|**_wfindnext64**|\ or \| -|**_wfindnexti64**|\ or \| -|**_wfindnext32i64**|\ or \| -|**_wfindnext64i32**|\ or \| - -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| Function | Required header | +|---|---| +| **`_findnext`** | \ | +| **`_findnext32`** | \ | +| **`_findnext64`** | \ | +| **`_findnexti64`** | \ | +| **`_findnext32i64`** | \ | +| **`_findnext64i32`** | \ | +| **`_wfindnext`** | \ or \ | +| **`_wfindnext32`** | \ or \ | +| **`_wfindnext64`** | \ or \ | +| **`_wfindnexti64`** | \ or \ | +| **`_wfindnext32i64`** | \ or \ | +| **`_wfindnext64i32`** | \ or \ | + +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/finite-finitef.md b/docs/c-runtime-library/reference/finite-finitef.md index 54ccf595f1..4bc7c14d38 100644 --- a/docs/c-runtime-library/reference/finite-finitef.md +++ b/docs/c-runtime-library/reference/finite-finitef.md @@ -10,7 +10,7 @@ f1_keywords: ["isfinite", "finite", "_finite", "_finitef", "math/isfinite", "mat helpviewer_keywords: ["finite function", "_finite function", "_finitef function"] ms.assetid: 5a7d7ca7-befb-4e1f-831d-28713c6eb805 --- -# isfinite, _finite, _finitef +# `isfinite`, `_finite`, `_finitef` Determines whether a floating-point value is finite. @@ -37,12 +37,12 @@ int _finitef( ### Parameters -*x*
+*`x`*\ The floating-point value to test. ## Return value -The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zero value if *x* is either a normal or subnormal finite value. They return 0 if the argument is infinite or a NaN. The C++ inline template function `isfinite` behaves the same way, but returns **`true`** or **`false`**. +The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zero value if *`x`* is either a normal or subnormal finite value. They return 0 if the argument is infinite or a NaN. The C++ inline template function `isfinite` behaves the same way, but returns **`true`** or **`false`**. ## Remarks @@ -50,18 +50,18 @@ The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zer ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -|`_finite`|\ or \|\, \, \, or \| -|`isfinite`, `_finitef`|\|\ or \| +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| `_finite` | \ or \ | \, \, \, or \ | +| `isfinite`, `_finitef` | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/floating-point-ordering.md b/docs/c-runtime-library/reference/floating-point-ordering.md index 1d8bb94251..acdf45961d 100644 --- a/docs/c-runtime-library/reference/floating-point-ordering.md +++ b/docs/c-runtime-library/reference/floating-point-ordering.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" title: "isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" +description: "Learn more about: isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" ms.date: "01/31/2019" f1_keywords: ["isgreater", "math/isgreater", "isgreaterequal", "math/isgreaterequal", "isless", "math/isless", "islessequal", "math/islessequal", "islessgreater", "math/islessgreater", "isunordered", "math/isunordered"] helpviewer_keywords: ["isgreater function", "isgreaterequal function", "isless function", "islessequal function", "islessgreater function", "isunordered function"] --- -# isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered +# `isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, `isunordered` Determines the ordering relationship between two floating-point values. @@ -43,7 +43,7 @@ int isunordered( ); /* C-only macro */ ``` -```C++ +```cpp template inline bool isgreater( FloatingType1 x, @@ -83,18 +83,18 @@ inline bool isunordered( ### Parameters -*x*, *y*
+*`x`*, *`y`*\ The floating-point values to compare. -## Return Value +## Return value -In all comparisons, infinities of the same sign compare as equal. Negative infinity is less than any finite value or positive infinity. Positive infinity is greater than any finite value or negative infinity. Zeroes are equal regardless of sign. NaNs are not less than, equal to, or greater than any value, including another NaN. +In all comparisons, infinities of the same sign compare as equal. Negative infinity is less than any finite value or positive infinity. Positive infinity is greater than any finite value or negative infinity. Zeroes are equal regardless of sign. NaNs aren't less than, equal to, or greater than any value, including another NaN. -When neither argument is a NaN, the ordering macros **isgreater**, **isgreaterequal**, **isless**, and **islessequal** return a non-zero value if the specified ordering relation between *x* and *y* holds true. These macros return 0 if either or both arguments are NaNs or if the ordering relationship is false. The function forms behave the same way, but return **`true`** or **`false`**. +When neither argument is a NaN, the ordering macros **`isgreater`**, **`isgreaterequal`**, **`isless`**, and **`islessequal`** return a non-zero value if the specified ordering relation between *`x`* and *`y`* holds true. These macros return 0 if either or both arguments are NaNs or if the ordering relationship is false. The function forms behave the same way, but return **`true`** or **`false`**. -The **islessgreater** macro returns a non-zero value if both *x* and *y* are not NaNs, and *x* is either less than or greater than *y*. It returns 0 if either or both arguments are NaNs, or if the values are equal. The function form behaves the same way, but returns **`true`** or **`false`**. +The **`islessgreater`** macro returns a non-zero value if both *`x`* and *`y`* aren't NaNs, and *`x`* is either less than or greater than *`y`*. It returns 0 if either or both arguments are NaNs, or if the values are equal. The function form behaves the same way, but returns **`true`** or **`false`**. -The **isunordered** macro returns a non-zero value if either *x*, *y*, or both are NaNs. Otherwise, it returns 0. The function form behaves the same way, but returns **`true`** or **`false`**. +The **`isunordered`** macro returns a non-zero value if either *`x`*, *`y`*, or both are NaNs. Otherwise, it returns 0. The function form behaves the same way, but returns **`true`** or **`false`**. ## Remarks @@ -102,16 +102,16 @@ These comparison operations are implemented as macros when compiled as C, and as ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -| **isgreater**, **isgreaterequal**, **isless**,
**islessequal**, **islessgreater**, **isunordered** | \ | \ or \ | +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`isgreater`**, **`isgreaterequal`**, **`isless`**,
**`islessequal`**, **`islessgreater`**, **`isunordered`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) diff --git a/docs/c-runtime-library/reference/floating-point-primitives.md b/docs/c-runtime-library/reference/floating-point-primitives.md index bd74ad4ce6..27f5ef5e1f 100644 --- a/docs/c-runtime-library/reference/floating-point-primitives.md +++ b/docs/c-runtime-library/reference/floating-point-primitives.md @@ -3,7 +3,7 @@ description: "Learn more about: Floating-point primitives" title: "Floating-point primitives" ms.date: "4/2/2020" api_name: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_fdsign", "_dpcomp", "_ldpcomp", "_fdpcomp", "_dtest", "_ldtest", "_fdtest", "_d_int", "_ld_int", "_fd_int", "_dscale", "_ldscale", "_fdscale", "_dunscale", "_ldunscale", "_fdunscale", "_dexp", "_ldexp", "_fdexp", "_dnorm", "_fdnorm", "_dpoly", "_ldpoly", "_fdpoly", "_dlog", "_ldlog", "_fdlog", "_dsin", "_ldsin", "_fdsin", "_o__d_int", "_o__dclass", "_o__dlog", "_o__dnorm", "_o__dpcomp", "_o__dpoly", "_o__dscale", "_o__dsign", "_o__dsin", "_o__dtest", "_o__dunscale", "_o__fd_int", "_o__fdclass", "_o__fdexp", "_o__fdlog", "_o__fdpcomp", "_o__fdpoly", "_o__fdscale", "_o__fdsign", "_o__fdsin", "_o__ld_int", "_o__ldclass", "_o__ldexp", "_o__ldlog", "_o__ldpcomp", "_o__ldpoly", "_o__ldscale", "_o__ldsign", "_o__ldsin", "_o__ldtest", "_o__ldunscale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_fdsign", "_dpcomp", "_ldpcomp", "_fdpcomp", "_dtest", "_ldtest", "_fdtest", "_d_int", "_ld_int", "_fd_int", "_dscale", "_ldscale", "_fdscale", "_dunscale", "_ldunscale", "_fdunscale", "_dexp", "_ldexp", "_fdexp", "_dnorm", "_fdnorm", "_dpoly", "_ldpoly", "_fdpoly", "_dlog", "_ldlog", "_fdlog", "_dsin", "_ldsin", "_fdsin"] @@ -13,9 +13,9 @@ helpviewer_keywords: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_ Microsoft-specific primitive functions that are used to implement some standard C runtime library (CRT) floating-point functions. They're documented here for completeness, but aren't recommended for use. Some of these functions are noted as unused, because they're known to have issues in precision, exception handling, and conformance to IEEE-754 behavior. They exist in the library only for backward compatibility. For correct behavior, portability, and adherence to standards, prefer the standard floating-point functions over these functions. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## _dclass, _ldclass, _fdclass +## `_dclass`, `_ldclass`, `_fdclass` ### Syntax @@ -27,24 +27,24 @@ short __cdecl _fdclass(float x); ### Parameters -*x*
+*`x`*\ Floating-point function argument. ### Remarks -These floating-point primitives implement the C versions of the CRT macro [fpclassify](fpclassify.md) for floating-point types. The classification of the argument *x* is returned as one of these constants, defined in math.h: +These floating-point primitives implement the C versions of the CRT macro [`fpclassify`](fpclassify.md) for floating-point types. The classification of the argument *`x`* is returned as one of these constants, defined in math.h: -|Value|Description| -|-----------|-----------------| -| **FP_NAN** | A quiet, signaling, or indeterminate NaN | -| **FP_INFINITE** | A positive or negative infinity | -| **FP_NORMAL** | A positive or negative normalized non-zero value | -| **FP_SUBNORMAL** | A positive or negative subnormal (denormalized) value | -| **FP_ZERO** | A positive or negative zero value | +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative subnormal (denormalized) value | +| `FP_ZERO` | A positive or negative zero value | -For additional detail, you can use the Microsoft-specific [_fpclass, _fpclassf](fpclass-fpclassf.md) functions. Use the [fpclassify](fpclassify.md) macro or function for portability. +For more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) macro or function for portability. -## _dsign, _ldsign, _fdsign +## `_dsign`, `_ldsign`, `_fdsign` ### Syntax @@ -56,12 +56,12 @@ int __cdecl _fdsign(float x); ### Parameters -*x*
+*`x`*\ Floating-point function argument. ### Remarks -These floating-point primitives implement the [signbit](signbit.md) macro or function in the CRT. They return a non-zero value if the sign bit is set in the significand (mantissa) of the argument *x*, and 0 if the sign bit is not set. +These floating-point primitives implement the [`signbit`](signbit.md) macro or function in the CRT. They return a non-zero value if the sign bit is set in the significand (mantissa) of the argument *`x`*. Otherwise, they return 0 if the sign bit isn't set. ## _dpcomp, _ldpcomp, _fdpcomp @@ -75,20 +75,20 @@ int __cdecl _fdpcomp(float x, float y); ### Parameters -*x*, *y*
+*`x`*, *`y`*\ Floating-point function arguments. ### Remarks -These floating-point primitives take two arguments, *x* and *y*, and return a value that shows their ordering relationship, expressed as the bitwise or of these constants, defined in math.h: +These floating-point primitives take two arguments, *`x`* and *`y`*, and return a value that shows their ordering relationship, expressed as the bitwise or of these constants, defined in math.h: | Value | Description | |------------|-----------------| -| **_FP_LT** | *x* can be considered less than *y* | -| **_FP_EQ** | *x* can be considered equal to *y* | -| **_FP_GT** | *x* can be considered greater than *y* | +| `_FP_LT` | *`x`* can be considered less than *`y`* | +| `_FP_EQ` | *`x`* can be considered equal to *`y`* | +| `_FP_GT` | *`x`* can be considered greater than *`y`* | -These primitives implement the [isgreater, isgreaterequal, isless, islessequal, islessgreater, and isunordered](floating-point-ordering.md) macros and functions in the CRT. +These primitives implement the [`isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, and `isunordered`](floating-point-ordering.md) macros and functions in the CRT. ## _dtest, _ldtest, _fdtest @@ -102,22 +102,22 @@ short __cdecl _fdtest(float* px); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. ### Remarks -These floating-point primitives implement the C++ versions of the CRT function [fpclassify](fpclassify.md) for floating-point types. The argument *x* is evaluated and the classification is returned as one of these constants, defined in math.h: +These floating-point primitives implement the C++ versions of the CRT function [`fpclassify`](fpclassify.md) for floating-point types. The argument *`x`* is evaluated and the classification is returned as one of these constants, defined in math.h: -|Value|Description| -|-----------|-----------------| -| **FP_NAN** | A quiet, signaling, or indeterminate NaN | -| **FP_INFINITE** | A positive or negative infinity | -| **FP_NORMAL** | A positive or negative normalized non-zero value | -| **FP_SUBNORMAL** | A positive or negative subnormal (denormalized) value | -| **FP_ZERO** | A positive or negative zero value | +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative subnormal (denormalized) value | +| `FP_ZERO` | A positive or negative zero value | -For additional detail, you can use the Microsoft-specific [_fpclass, _fpclassf](fpclass-fpclassf.md) functions. Use the [fpclassify](fpclassify.md) function for portability. +For more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) function for portability. ## _d_int, _ld_int, _fd_int @@ -131,15 +131,15 @@ short __cdecl _fd_int(float* px, short exp); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives take a pointer to a floating-point value *px* and an exponent value *exp*, and remove the fractional part of the floating-point value below the given exponent, if possible. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value in *px* otherwise. +These floating-point primitives take a pointer to a floating-point value *`px`* and an exponent value *`exp`*, and remove the fractional part of the floating-point value below the given exponent, if possible. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. ## _dscale, _ldscale, _fdscale @@ -153,15 +153,15 @@ short __cdecl _fdscale(float* px, long exp); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives take a pointer to a floating-point value *px* and an exponent value *exp*, and scale the value in *px* by 2*exp*, if possible. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value in *px* otherwise. For portability, prefer the [ldexp, ldexpf, and ldexpl](ldexp.md) functions. +These floating-point primitives take a pointer to a floating-point value *`px`* and an exponent value *`exp`*, and scale the value in *`px`* by 2*`exp`*, if possible. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. For portability, prefer the [`ldexp`, `ldexpf`, `ldexpl`](ldexp.md) functions. ## _dunscale, _ldunscale, _fdunscale @@ -175,15 +175,15 @@ short __cdecl _fdunscale(short* pexp, float* px); ### Parameters -*pexp*
+*`pexp`*\ A pointer to an exponent as an integral type. -*px*
+*`px`*\ Pointer to a floating-point argument. ### Remarks -These floating-point primitives break down the floating-point value pointed at by *px* into a significand (mantissa) and an exponent, if possible. The significand is scaled such that the absolute value is greater than or equal to 0.5 and less than 1.0. The exponent is the value *n*, where the original floating-point value is equal to the scaled significand times 2*n*. This integer exponent *n* is stored at the location pointed to by *pexp*. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value otherwise. For portability, prefer the [frexp, frexpf, frexpl](frexp.md) functions. +These floating-point primitives break down the floating-point value pointed at by *`px`* into a significand (mantissa) and an exponent, if possible. The significand is scaled such that the absolute value is greater than or equal to 0.5 and less than 1.0. The exponent is the value *`n`*, where the original floating-point value is equal to the scaled significand times 2n. This integer exponent *`n`* is stored at the location pointed to by *`pexp`*. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value otherwise. For portability, prefer the [`frexp`, `frexpf`, `frexpl`](frexp.md) functions. ## _dexp, _ldexp, _fdexp @@ -197,18 +197,18 @@ short __cdecl _fdexp(float* px, float y, long exp); ### Parameters -*y*
+*`y`*\ Floating-point function argument. -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives construct a floating-point value in the location pointed at by *px* equal to *y* * 2*exp*. The value returned is the result of **fpclassify** on the input value in *y* if it's a NaN or infinity, and on the output value in *px* otherwise. For portability, prefer the [ldexp, ldexpf, and ldexpl](ldexp.md) functions. +These floating-point primitives construct a floating-point value in the location pointed at by *`px`* equal to *`y`* * 2exp. The value returned is the result of `fpclassify` on the input value in *`y`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. For portability, prefer the [`ldexp`, `ldexpf`, `ldexpl`](ldexp.md) functions. ## _dnorm, _fdnorm @@ -221,12 +221,12 @@ short __cdecl _fdnorm(unsigned short* ps); ### Parameters -*ps*
+*`ps`*\ Pointer to the bitwise representation of a floating-point value expressed as an array of **`unsigned short`**. ### Remarks -These floating-point primitives normalize the fractional part of an underflowed floating-point value and adjust the *characteristic*, or biased exponent, to match. The value is passed as the bitwise representation of the floating-point type converted to an array of **`unsigned short`** through the `_double_val`, `_ldouble_val`, or `_float_val` type punning union declared in math.h. The return value is the result of **fpclassify** on the input floating-point value if it's a NaN or infinity, and on the output value otherwise. +These floating-point primitives normalize the fractional part of an underflowed floating-point value and adjust the *characteristic*, or biased exponent, to match. The value is passed as the bitwise representation of the floating-point type converted to an array of **`unsigned short`** through the `_double_val`, `_ldouble_val`, or `_float_val` type-punning union declared in math.h. The return value is the result of `fpclassify` on the input floating-point value if it's a NaN or infinity, and on the output value otherwise. ## _dpoly, _ldpoly, _fdpoly @@ -240,18 +240,18 @@ float __cdecl _fdpoly(float x, _float const* table, int n); ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*table*
+*`table`*\ Pointer to a table of constant coefficients for a polynomial. -*n*
+*`n`*\ Order of the polynomial to evaluate. ### Remarks -These floating-point primitives return the evaluation of *x* in the polynomial of order *n* whose coefficients are represented by the corresponding constant values in *table*. For example, if *table*\[0] = 3.0, *table*\[1] = 4.0, *table*\[2] = 5.0, and *n* = 2, it represents the polynomial 5.0x2 + 4.0x + 3.0. If this polynomial is evaluated for *x* of 2.0, the result is 31.0. These functions aren't used internally. +These floating-point primitives return the evaluation of *`x`* in the polynomial of order *`n`* whose coefficients are represented by the corresponding constant values in *`table`*. For example, if *`table[0]`* = 3.0, *`table[1]`* = 4.0, *`table[2]`* = 5.0, and *`n`* = 2, it represents the polynomial 5.0x2 + 4.0x + 3.0. If this polynomial is evaluated for *`x`* of 2.0, the result is 31.0. These functions aren't used internally. ## _dlog, _dlog, _dlog @@ -265,15 +265,15 @@ float __cdecl _fdlog(float x, int base_flag); ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*base_flag*
+*`base_flag`*\ Flag that controls the base to use, 0 for base *e* and non-zero for base 10. ### Remarks -These floating-point primitives return the natural log of *x*, ln(*x*) or log*e*(*x*), when *base_flag* is 0. They return the log base 10 of *x*, or log10(*x*), when *base_flag* is non-zero. These functions aren't used internally. For portability, prefer the functions [log, logf, logl, log10, log10f, and log10l](log-logf-log10-log10f.md). +These floating-point primitives return the natural log of *`x`* (ln(x) or log*e*(x)), when *`base_flag`* is 0. They return the log base 10 of *`x`*, or log10(x), when *`base_flag`* is non-zero. These functions aren't used internally. For portability, prefer the functions [`log`, `logf`, `logl`, `log10`, `log10f`, and `log10l`](log-logf-log10-log10f.md). ## _dsin, _ldsin, _fdsin @@ -287,33 +287,33 @@ float __cdecl _fdsin(float x, unsigned int quadrant); ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*quadrant*
+*`quadrant`*\ Quadrant offset of 0, 1, 2, or 3 to use to produce `sin`, `cos`, `-sin`, and `-cos` results. ### Remarks -These floating-point primitives return the sine of *x* offset by the *quadrant* modulo 4. Effectively, they return the sine, cosine, -sine, and -cosine of *x* when *quadrant* modulo 4 is 0, 1, 2, or 3, respectively. These functions aren't used internally. For portability, prefer the [sin, sinf, sinl](sin-sinf-sinl.md), [cos, cosf, and cosl](cos-cosf-cosl.md) functions. +These floating-point primitives return the sine of *`x`* offset by the *`quadrant`* modulo 4. Effectively, they return the sine, cosine, -sine, and -cosine of *`x`* when *`quadrant`* modulo 4 is 0, 1, 2, or 3, respectively. These functions aren't used internally. For portability, prefer the [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md), [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md) functions. ## Requirements Header: \ -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-point support](../floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
-[cos, cosf, cosl](cos-cosf-cosl.md)
-[frexp, frexpf, frexpl](frexp.md)
-[ldexp, ldexpf, and ldexpl](ldexp.md)
-[log, logf, logl, log10, log10f, log10l](log-logf-log10-log10f.md)
-[sin, sinf, sinl](sin-sinf-sinl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md)\ +[`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ +[`frexp`, `frexpf`, `frexpl`](frexp.md)\ +[`ldexp`, `ldexpf`, `ldexpl`](ldexp.md)\ +[`log`, `logf`, `logl`, `log10`, `log10f`, `log10l`](log-logf-log10-log10f.md)\ +[`sin`, `sinf`, `sinl`](sin-sinf-sinl.md) diff --git a/docs/c-runtime-library/reference/floor-floorf-floorl.md b/docs/c-runtime-library/reference/floor-floorf-floorl.md index 2f05bbc33f..fda6807505 100644 --- a/docs/c-runtime-library/reference/floor-floorf-floorl.md +++ b/docs/c-runtime-library/reference/floor-floorf-floorl.md @@ -3,14 +3,14 @@ title: "floor, floorf, floorl" description: "API reference for floor, floorf, and floorl; which calculates the floor of a value." ms.date: "9/1/2020" api_name: ["floorf", "floorl", "floor", "_o_floor", "_o_floorf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["floor", "floorl", "_floorl", "floorf"] helpviewer_keywords: ["floor function", "floorf function", "calculating floors of values", "floorl function"] ms.assetid: e9955f70-d659-414f-8050-132e13c8ff36 --- -# floor, floorf, floorl +# `floor`, `floorf`, `floorl` Calculates the floor of a value. @@ -37,35 +37,35 @@ long double floorl( ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **floor** functions return a floating-point value that represents the largest integer that is less than or equal to *x*. There's no error return. +The **`floor`** functions return a floating-point value that represents the largest integer that is less than or equal to *`x`*. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± QNAN,IND|none|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | -**floor** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [_set_SSE2_enable](set-sse2-enable.md). +**`floor`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). ## Remarks -C++ allows overloading, so you can call overloads of **floor** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **floor** always takes and returns a **`double`**. +C++ allows overloading, so you can call overloads of **`floor`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`floor`** always takes and returns a **`double`**. -If you use the \ `floor()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `floor()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**floor**, **floorf**, **floorl**|\| -|**floor** macro | \ | +| Function | Required header | +|---|---| +| **`floor`**, **`floorf`**, **`floorl`** | \ | +| **`floor`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,7 +104,7 @@ The ceil of -2.8 is -2.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[round, roundf, roundl](round-roundf-roundl.md)
-[fmod, fmodf](fmod-fmodf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md) diff --git a/docs/c-runtime-library/reference/flushall.md b/docs/c-runtime-library/reference/flushall.md index e52662a35a..504c655a09 100644 --- a/docs/c-runtime-library/reference/flushall.md +++ b/docs/c-runtime-library/reference/flushall.md @@ -3,14 +3,14 @@ title: "_flushall" description: "API reference for _flushall; which flushes all streams and clears all buffers." ms.date: "4/2/2020" api_name: ["_flushall", "_o__flushall"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_flushall"] helpviewer_keywords: ["flushall function", "flushing streams", "streams, flushing", "_flushall function"] ms.assetid: 2cd73562-6d00-4ca2-b13c-80d0ae7870b5 --- -# _flushall +# `_flushall` Flushes all streams; clears all buffers. @@ -20,29 +20,29 @@ Flushes all streams; clears all buffers. int _flushall( void ); ``` -## Return Value +## Return value -**_flushall** returns the number of open streams (input and output). There's no error return. +**`_flushall`** returns the number of open streams (input and output). There's no error return. ## Remarks -By default, the **_flushall** function writes to appropriate files the contents of all buffers associated with open output streams. All buffers associated with open input streams are cleared of their current contents. (These buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing streams.) +By default, the **`_flushall`** function writes to appropriate files the contents of all buffers associated with open output streams. All buffers associated with open input streams are cleared of their current contents. (These buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing streams.) -If a read follows a call to **_flushall**, new data is read from the input files into the buffers. All streams remain open after the call to **_flushall**. +If a read follows a call to **`_flushall`**, new data is read from the input files into the buffers. All streams remain open after the call to **`_flushall`**. -The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with Commode.obj. In the resulting executable file, calls to **_flushall** write the contents of all buffers to disk. Only **_flushall** and [fflush](fflush.md) are affected by Commode.obj. +The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with Commode.obj. In the resulting executable file, calls to **`_flushall`** write the contents of all buffers to disk. Only **`_flushall`** and [`fflush`](fflush.md) are affected by Commode.obj. -For information about controlling the commit-to-disk feature, see [Stream I/O](../../c-runtime-library/stream-i-o.md), [fopen](fopen-wfopen.md), and [_fdopen](fdopen-wfdopen.md). +For information about controlling the commit-to-disk feature, see [Stream I/O](../stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_flushall**|\| +| Function | Required header | +|---|---| +| **`_flushall`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -68,8 +68,8 @@ There were 3 streams flushed ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_commit](commit.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[fflush](fflush.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`_commit`](commit.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`fflush`](fflush.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fma-fmaf-fmal.md b/docs/c-runtime-library/reference/fma-fmaf-fmal.md index 2d0f177e3e..5c1d6f5f4b 100644 --- a/docs/c-runtime-library/reference/fma-fmaf-fmal.md +++ b/docs/c-runtime-library/reference/fma-fmaf-fmal.md @@ -1,18 +1,18 @@ --- title: "fma, fmaf, fmal" -description: "API reference for fma, fmaf, and fmal; which multiplies two values together, adds a third value, and then rounds the result, without losing any precision due to intermediary rounding." +description: "API reference for fma, fmaf, and fmal; which multiplies two values together, adds a third value, and then rounds the result, while only losing a small amount of precision due to intermediary rounding." ms.date: "9/1/2020" api_name: ["fma", "fmaf", "fmal", "_o_fma", "_o_fmaf", "_o_fmal"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fma", "fmaf", "fmal", "math/fma", "math/fmaf", "math/fmal"] helpviewer_keywords: ["fma function", "fmaf function", "fmal function"] ms.assetid: 584a6037-da1e-4e86-9f0c-97aae86de0c0 --- -# fma, fmaf, fmal +# `fma`, `fmaf`, `fmal` -Multiplies two values together, adds a third value, and then rounds the result, without losing any precision due to intermediary rounding. +Multiplies two values together, adds a third value, and then rounds the result, while only losing a small amount of precision due to intermediary rounding. ## Syntax @@ -52,53 +52,53 @@ long double fmal( ### Parameters -*x*\ +*`x`*\ The first value to multiply. -*y*\ +*`y`*\ The second value to multiply. -*z*\ +*`z`*\ The value to add. -## Return Value +## Return value -Returns `(x * y) + z`. The return value is then rounded using the current rounding format. +Returns approximately `(x * y) + z`. The return value is then rounded using the current rounding format, although in many cases, it returns incorrectly rounded results and thus the value may be inexact by up to half an ulp from the correct value. Otherwise, may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = INFINITY, *y* = 0 or

*x* = 0, *y* = INFINITY|NaN| -|*x* or *y* = exact ± INFINITY, *z* = INFINITY with the opposite sign|NaN| -|*x* or *y* = NaN|NaN| -|not (*x* = 0, *y*= indefinite) and *z* = NaN

not (*x*=indefinite, *y*=0) and *z* = NaN|NaN| -|Overflow range error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| -|Underflow range error|correct value, after rounding.| +| Issue | Return | +|---|---| +| *`x`* = INFINITY, *`y`* = 0 or

*`x`* = 0, *`y`* = INFINITY | NaN | +| *`x`* or *`y`* = exact ± INFINITY, *`z`* = INFINITY with the opposite sign | NaN | +| *`x`* or *`y`* = NaN | NaN | +| not (*`x`* = 0, *`y`*= indefinite) and *`z`* = NaN

not (*`x`*=indefinite, *`y`*=0) and *`z`* = NaN | NaN | +| Overflow range error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| Underflow range error | correct value, after rounding. | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **fma** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fma** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fma`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fma`** always takes and returns a **`double`**. -If you use the \ `fma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. This function computes the value as though it were taken to infinite precision, and then rounds the final result. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fma**, **fmaf**, **fmal**|\|\| -|**fma** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fma`**, **`fmaf`**, **`fmal`** | \ | \ | +| **`fma`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[remainder, remainderf, remainderl](remainder-remainderf-remainderl.md)
-[remquo, remquof, remquol](remquo-remquof-remquol.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`remainder`, `remainderf`, `remainderl`](remainder-remainderf-remainderl.md)\ +[`remquo`, `remquof`, `remquol`](remquo-remquof-remquol.md) diff --git a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md index ce863ac855..ccd942f672 100644 --- a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md +++ b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md @@ -10,7 +10,7 @@ f1_keywords: ["fmax", "fmaxf", "fmaxl", "math/fmax", "math/fmaxf", "math/fmaxl"] helpviewer_keywords: ["fmax function", "fmaxf function", "fmaxl function"] ms.assetid: a773ccf7-495e-4a9a-8c6d-dfb53e341e35 --- -# fmax, fmaxf, fmaxl +# `fmax`, `fmaxf`, `fmaxl` Determine the larger of two specified numeric values. @@ -47,42 +47,42 @@ long double fmaxl( ### Parameters -*x*\ +*`x`*\ The first value to compare. -*y*\ +*`y`*\ The second value to compare. -## Return Value +## Return value -If successful, returns the larger of *x* or *y*. The value returned is exact, and does not depend on any form of rounding. +If successful, returns the larger of *`x`* or *`y`*. The value returned is exact, and doesn't depend on any form of rounding. Otherwise, may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = NaN|*y*| -|*y* = NaN|*x*| -|*x* and *y* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = NaN | *`y`* | +| *`y`* = NaN | *`x`* | +| *`x`* and *`y`* = NaN | NaN | -This function does not use the errors specified in [_matherr](matherr.md). +This function doesn't use the errors specified in [`_matherr`](matherr.md). ## Remarks Because C++ allows overloading, you can call overloads of fmax that take and return `float` and `long double` types. In a C program, unless you're using the \ macro to call this function, `fmax` always takes and returns a double. -If you use the \ `fmax()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fmax()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fmax**, **fmaxf**, **fmaxl**|\|\ or \| -|**fmax** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fmax`**, **`fmaxf`**, **`fmaxl`** | \ | \ or \ | +| **`fmax`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmin, fminf, fminl](fmin-fminf-fminl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmin`, `fminf`, `fminl`](fmin-fminf-fminl.md) diff --git a/docs/c-runtime-library/reference/fmin-fminf-fminl.md b/docs/c-runtime-library/reference/fmin-fminf-fminl.md index 1d7c0035e1..e1b2093567 100644 --- a/docs/c-runtime-library/reference/fmin-fminf-fminl.md +++ b/docs/c-runtime-library/reference/fmin-fminf-fminl.md @@ -10,7 +10,7 @@ f1_keywords: ["fmin", "fminf", "fminl", "math/fmin", "math/fminf", "math/fminl"] helpviewer_keywords: ["fmin function", "fminf function", "fminl function"] ms.assetid: 1916dfb5-99c1-4b0d-aefb-513525c3f2ac --- -# fmin, fminf, fminl +# `fmin`, `fminf`, `fminl` Determines the smaller of the two specified values. @@ -47,40 +47,40 @@ long double fminl( ### Parameters -*x*\ +*`x`*\ The first value to compare. -*y*\ +*`y`*\ The second value to compare. -## Return Value +## Return value -If successful, returns the smaller of *x* or *y*. +If successful, returns the smaller of *`x`* or *`y`*. -|Input|Result| -|-----------|------------| -|*x* is NaN|*y*| -|*y* is NaN|*x*| -|*x* and *y* are NaN|NaN| +| Input | Result | +|---|---| +| *`x`* is NaN | *`y`* | +| *`y`* is NaN | *`x`* | +| *`x`* and *`y`* are NaN | NaN | -The function does not cause [_matherr](matherr.md) to be invoked, cause any floating-point exceptions, or change the value of **errno**. +The function doesn't cause [`_matherr`](matherr.md) to be invoked, cause any floating-point exceptions, or change the value of `errno`. ## Remarks -Because C++ allows overloading, you can call overloads of **fmin** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fmin** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fmin`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fmin`** always takes and returns a **`double`**. -If you use the \ `fmin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fmin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**fmin**, **fminf**, **fminl**|C: \
C++: \ or \| -|**fmin** macro | \ | +| Routine | Required header | +|---|---| +| **`fmin`**, **`fminf`**, **`fminl`** | C: \
C++: \ or \ | +| **`fmin`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmax, fmaxf, fmaxl](fmax-fmaxf-fmaxl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmax`, `fmaxf`, `fmaxl`](fmax-fmaxf-fmaxl.md) diff --git a/docs/c-runtime-library/reference/fmod-fmodf.md b/docs/c-runtime-library/reference/fmod-fmodf.md index 36acbb3f0d..ecf39a5c28 100644 --- a/docs/c-runtime-library/reference/fmod-fmodf.md +++ b/docs/c-runtime-library/reference/fmod-fmodf.md @@ -3,7 +3,7 @@ title: "fmod, fmodf, fmodl" description: "API reference for fmod, fmodf, and fmodl; which calculates the floating-point remainder." ms.date: "1/15/2021" api_name: ["fmod", "fmodf", "fmodl", "_o_fmod", "_o_fmodf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fmod", "_fmodl", "fmodf"] @@ -45,28 +45,28 @@ long double fmodl( *`x`*, *`y`*\ Floating-point values. -## Return Value +## Return value -**`fmod`** returns the floating-point remainder of *`x`* / *`y`*. If the value of *`y`* is 0.0, **`fmod`** returns a quiet NaN. For information about representation of a quiet NaN by the **`printf`** family, see [printf](printf-printf-l-wprintf-wprintf-l.md). +**`fmod`** returns the floating-point remainder of `x / y`. If the value of *`y`* is 0.0, **`fmod`** returns a quiet `NaN`. For information about representation of a quiet `NaN` by the **`printf`** family, see [`printf`](printf-printf-l-wprintf-wprintf-l.md). ## Remarks -The **`fmod`** function calculates the floating-point remainder *f* of *`x`* / *`y`* such that *`x`* = *i* \* *`y`* + *`f`*, where *`i`* is an integer, *`f`* has the same sign as *`x`*, and the absolute value of *`f`* is less than the absolute value of *`y`*. +The **`fmod`** function calculates the floating-point remainder *`f`* of `x / y` such that `x = i * y + f`, where *`i`* is an integer, *`f`* has the same sign as *`x`*, and the absolute value of *`f`* is less than the absolute value of *`y`*. C++ allows overloading, so you can call overloads of **`fmod`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`fmod`** always takes two **`double`** arguments and returns a **`double`**. -If you use the `` `fmod()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `fmod` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fmod`**, **`fmodf`**, **`fmodl`**|``| -|**`fmod`** macro | `` | +| Function | Required header | +|---|---| +| **`fmod`**, **`fmodf`**, **`fmodl`** | `` | +| **`fmod`** macro | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,8 +92,8 @@ The remainder of -10.00 / 3.00 is -1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`ceil, ceilf, ceill`](ceil-ceilf-ceill.md)\ -[`fabs, fabsf, fabsl`](fabs-fabsf-fabsl.md)\ -[`floor, floorf, floorl`](floor-floorf-floorl.md)\ -[`_CIfmod`](../../c-runtime-library/cifmod.md) +[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`_CIfmod`](../cifmod.md) diff --git a/docs/c-runtime-library/reference/fopen-s-wfopen-s.md b/docs/c-runtime-library/reference/fopen-s-wfopen-s.md index f9f8dbdd7f..6964db2b65 100644 --- a/docs/c-runtime-library/reference/fopen-s-wfopen-s.md +++ b/docs/c-runtime-library/reference/fopen-s-wfopen-s.md @@ -1,17 +1,17 @@ --- title: "fopen_s, _wfopen_s" description: "Describes the API for `fopen_s` and `_wfopen_s`" -ms.date: "2/24/2021" +ms.date: 04/27/2023 api_name: ["_wfopen_s", "fopen_s", "_o__wfopen_s", "_o_fopen_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["fopen_s", "_tfopen_s", "_wfopen_s"] +f1_keywords: ["STDIO/fopen_s", "CORECRT_WSTDIO/_wfopen_s", "TCHAR/_tfopen_s", "fopen_s", "_wfopen_s", "_tfopen_s"] helpviewer_keywords: ["_wfopen_s function", "opening files, for file I/O", "_tfopen_s function", "tfopen_s function", "wfopen_s function", "fopen_s function", "Unicode [C++], creating files", "Unicode [C++], writing files", "files [C++], opening", "Unicode [C++], files"] --- # `fopen_s`, `_wfopen_s` -Opens a file. These versions of [`fopen`, `_wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Opens a file. These versions of [`fopen`, `_wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -31,156 +31,164 @@ errno_t _wfopen_s( ### Parameters *`pFile`*\ -A pointer to the file pointer that will receive the pointer to the opened file. +A pointer to the file pointer that receives the pointer to the opened file. *`filename`*\ -Filename. +The name of the file to open. *`mode`*\ Type of access permitted. -## Return Value +## Return value -Zero if successful; an error code on failure. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful; an error code on failure. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Error Conditions +### Error conditions -|*`pFile`*|*`filename`*|*`mode`*|Return Value|Contents of *`pFile`*| -|-------------|----------------|------------|------------------|------------------------| -|**`NULL`**|any|any|**`EINVAL`**|unchanged| -|any|**`NULL`**|any|**`EINVAL`**|unchanged| -|any|any|**`NULL`**|**`EINVAL`**|unchanged| +| *`pFile`* | *`filename`* | *`mode`* | Return Value | Contents of *`pFile`* | +|--|--|--|--|--| +| `NULL` | any | any | `EINVAL` | unchanged | +| any | `NULL` | any | `EINVAL` | unchanged | +| any | any | `NULL` | `EINVAL` | unchanged | ## Remarks -Files that are opened by **`fopen_s`** and **`_wfopen_s`** aren't sharable. If you require that a file be sharable, use [`_fsopen`, `_wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, **`_SH_DENYNO`** for read/write sharing. +The **`fopen_s`** and **`_wfopen_s`** functions can't open a file for sharing. If you need to share the file, use [`_fsopen` or `_wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, use `_SH_DENYNO` for read/write sharing. -The **`fopen_s`** function opens the file that's specified by *filename*. **`_wfopen_s`** is a wide-character version of **`fopen_s`**; the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically otherwise. +The **`fopen_s`** function opens the file specified by *`filename`*. **`_wfopen_s`** is a wide-character version of **`fopen_s`** and the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically, otherwise. **`fopen_s`** accepts paths that are valid on the file system at the point of execution; UNC paths and paths that involve mapped network drives are accepted by **`fopen_s`** as long as the system that's executing the code has access to the share or mapped network drive at the time of execution. When you construct paths for **`fopen_s`**, don't make assumptions about the availability of drives, paths, or network shares in the execution environment. You can use either forward slashes (/) or backslashes (\\) as the directory separators in a path. -These functions validate their parameters. If *`pFile`*, *`filename`*, or *`mode`* is a null pointer, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions validate their parameters. If *`pFile`*, *`filename`*, or *`mode`* is a null pointer, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). -Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned and the global variable **`errno`** is set. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned, and the global variable `errno` is set. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Unicode support -**`fopen_s`** supports Unicode file streams. To open a new or existing Unicode file, pass a *ccs* flag that specifies the desired encoding to **`fopen_s`**: +**`fopen_s`** supports Unicode file streams. To open a new or existing Unicode file, pass a **`ccs`** flag that specifies the desired encoding to **`fopen_s`**, for example: -**`fopen_s(&fp, "newfile.txt", "rw, ccs=**_encoding_**");`** +**`fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");`** -Allowed values of *encoding* are **`UNICODE`**, **`UTF-8`**, and **`UTF-16LE`**. If there no value is specified for *`encoding`*, **`fopen_s`** uses ANSI encoding. +Allowed values of the **`ccs`** flag are `UNICODE`, **`UTF-8`**, and **`UTF-16LE`**. If no value is specified for **`ccs`**, **`fopen_s`** uses ANSI encoding. -If the file already exists and is opened for reading or appending, the Byte Order Mark (BOM), if present in the file, determines the encoding. The BOM encoding takes precedence over the encoding that's specified by the *`ccs`* flag. The *`ccs`* encoding is only used when no BOM is present or if the file is a new file. +If the file already exists and is opened for reading or appending, the byte order mark (BOM), if present in the file, determines the encoding. The BOM encoding takes precedence over the encoding that's specified by the **`ccs`** flag. The **`ccs`** encoding is only used when no BOM is present or if the file is a new file. > [!NOTE] -> BOM-detection only applies to files that are opened in Unicode mode; that is, by passing the *`ccs`* flag. +> BOM-detection only applies to files that are opened in Unicode mode; that is, by passing the **`ccs`** flag. -The following table summarizes the modes for various *`ccs`* flags that are given to **`fopen_s`** and for Byte Order Marks in the file. +The following table summarizes the modes for various **`ccs`** flag values that are given to **`fopen_s`** and for BOMs in the file. -### Encodings Used Based on ccs Flag and BOM +### Encodings used based on `ccs` flag and BOM -|ccs flag|No BOM (or new file)|BOM: UTF-8|BOM: UTF-16| -|----------------|----------------------------|-----------------|------------------| -|**`UNICODE`**|**`UTF-8`**|**`UTF-8`**|**`UTF-16LE`**| -|**`UTF-8`**|**`UTF-8`**|**`UTF-8`**|**`UTF-16LE`**| -|**`UTF-16LE`**|**`UTF-16LE`**|**`UTF-8`**|**`UTF-16LE`**| +| `ccs` flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 | +|--|--|--|--| +| `UNICODE` | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | +| **`UTF-8`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | +| **`UTF-16LE`** | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | Files that are opened for writing in Unicode mode have a BOM written to them automatically. -If *`mode`* is **`"a, ccs=`_encoding_`"`**, **`fopen_s`** first tries to open the file with both read access and write access. If successful, the function reads the BOM to determine the encoding for the file; if unsuccessful, the function uses the default encoding for the file. In either case, **`fopen_s`** then reopens the file with write-only access. (This applies to **`a`** mode only, not **`a+`**.) - -### Generic-Text Routine Mappings - -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tfopen_s`**|**`fopen_s`**|**`fopen_s`**|**`_wfopen_s`**| +If *`mode`* is **`"a, ccs=UNICODE"`**, **`"a, ccs=UTF-8"`**, or **`"a, ccs=UTF-16LE"`**, **`fopen_s`** first tries to open the file with both read access and write access. If successful, the function reads the BOM to determine the encoding for the file; if unsuccessful, the function uses the default encoding for the file. In either case, **`fopen_s`** then reopens the file with write-only access. (This behavior applies to **`a`** mode only, not **`a+`**.) The character string *`mode`* specifies the kind of access that's requested for the file, as follows. -|*`mode`*|Access| -|-|-| -| **`"r"`** | Opens for reading. If the file doesn't exist or cannot be found, the **`fopen_s`** call fails. | +| *`mode`* | Access | +|--|--| +| **`"r"`** | Opens for reading. If the file doesn't exist or can't be found, the **`fopen_s`** call fails. | | **`"w"`** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | | **`"a"`** | Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Creates the file if it doesn't exist. | | **`"r+"`** | Opens for both reading and writing. The file must exist. | -| **"w+"** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | +| **`"w+"`** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | | **`"a+"`** | Opens for reading and appending. The appending operation includes the removal of the EOF marker before new data is written to the file. The EOF marker isn't restored after writing is completed. Creates the file if it doesn't exist. | -When a file is opened by using the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out so that existing data cannot be overwritten. +When a file is opened by using the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out so that existing data can't be overwritten. -The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the **CTRL**+**Z** EOF marker. +The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the `CTRL`+**Z** EOF marker. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed. (The file is said to be open for "update".) However, when you switch from reading to writing, the input operation must come across an EOF marker. If there's no EOF marker, you must use an intervening call to a file-positioning function. The file-positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file-positioning function. Starting in C11, you can append **`"x"`** to **`"w"`** or **`"w+"`** to cause the function fail if the file exists, instead of overwriting it. -In addition to the values above, the following characters can be included in *`mode`* to specify the translation mode for newline characters: +In addition to the previous values, the following characters can be included in *`mode`* to specify the translation mode for newline characters: -|*`mode`* modifier|Translation mode| -|-|-| -| **`t`** | Open in text (translated) mode. | +| *`mode`* modifier | Translation mode | +|--|--| +| **`t`** | Open in text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input and LF characters are translated to CR-LF combinations on output. CTRL+Z is interpreted as an end-of-file character on input. | | **`b`** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | -In text (translated) mode, **CTRL**+**Z** is interpreted as an end-of-file character on input. In files opened for reading/writing with **`"a+"`**, **`fopen_s`** checks for a **CTRL**+**Z** at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and **`ftell`** to move within a file that ends with a **CTRL**+**Z**, may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. +In text (translated) mode, `CTRL`+**Z** is interpreted as an end-of-file character on input. For files opened for reading/writing with **`"a+"`**, **`fopen_s`** checks for a `CTRL`+**Z** at the end of the file and removes it, if possible. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file that ends with a `CTRL`+**Z**, may cause **`fseek`** to behave improperly near the end of the file. -Also, in text mode, carriage return/line feed combinations are translated into single line feeds on input, and line feed characters are translated to carriage return-line feed combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. The Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function). +Also, in text mode, carriage return/line feed (CRLF) combinations are translated into single line feed (LF) characters on input, and LF characters are translated to CRLF combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. The Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function). -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [_fmode](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -|*`mode`* modifier|Behavior| -|-|-| -| **`c`** | Enable the commit flag for the associated *filename* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | -| **`n`** | Reset the commit flag for the associated *filename* to "no-commit." This is the default. It also overrides the global commit flag if you link your program with COMMODE.OBJ. The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see [Link Options](../../c-runtime-library/link-options.md)). | -| **`n`** | Specifies that the file isn't inherited by child processes. | +| *`mode`* modifier | Behavior | +|--|--| +| **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`COMMODE.OBJ`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`COMMODE.OBJ`* (see [Link options](../link-options.md)). | +| **`N`** | Specifies that the file isn't inherited by child processes. | | **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | | **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`t`** | Specifies a file as temporary. If possible, it isn't flushed to disk. | -| **`D`** | Specifies a file as temporary. It's deleted when the last file pointer is closed. | -| **`ccs=`**_encoding_ | Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or **`UNICODE`**) for this file. Leave unspecified if you want ANSI encoding. | +| **`T`** | Specifies a file that isn't written to disk unless memory pressure requires it. | +| **`D`** | Specifies a temporary file that is deleted when the last file pointer to it is closed. | +| **`ccs=UNICODE`** | Specifies UNICODE as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. | +| **`ccs=UTF-8`** | Specifies UTF-8 as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. | +| **`ccs=UTF-16LE`** | Specifies UTF-16LE as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. | Valid characters for the *`mode`* string used in **`fopen_s`** and [`_fdopen`](fdopen-wfdopen.md) correspond to *`oflag`* arguments used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as follows. -|Characters in *`mode`* string|Equivalent *`oflag`* value for `_open`/`_sopen`| -|-------------------------------|----------------------------------------------------| -|**`a`**|**`_O_WRONLY`** | **`_O_APPEND`** (usually **`_O_WRONLY`** | **`_O_CREAT`** | **`_O_APPEND`**)| -|**`a+`**|**`_O_RDWR`** | **`_O_APPEND`** (usually **`_O_RDWR`** | **`_O_APPEND`** | **`_O_CREAT`**)| -|**`R`**|**`_O_RDONLY`**| -|**`r+`**|**`_O_RDWR`**| -|**`w`**|**`_O_WRONLY`** (usually **`_O_WRONLY`** | **`_O_CREAT`** | **_O_TRUNC**)| -|**`w+`**|**`_O_RDWR`** (usually **`_O_RDWR`** | **`_O_CREAT`** | **_O_TRUNC**)| -|**`b`**|**`_O_BINARY`**| -|**`t`**|**`_O_TEXT`**| -|**`c`**|None| -|**`n`**|None| -|**`S`**|**`_O_SEQUENTIAL`**| -|**`R`**|**`_O_RANDOM`**| -|**`t`**|**`_O_SHORTLIVED`**| -|**`D`**|**`_O_TEMPORARY`**| -|**`ccs=UNICODE`**|**`_O_WTEXT`**| -|**`ccs=UTF-8`**|**`_O_UTF8`**| -|**`ccs=UTF-16LE`**|**`_O_UTF16`**| +| Characters in *`mode`* string | Equivalent *`oflag`* value for `_open`/`_sopen` | +|--|--| +| **`a`** | `_O_WRONLY | _O_APPEND` (usually `_O_WRONLY | _O_CREAT | _O_APPEND`) | +| **`a+`** | `_O_RDWR | _O_APPEND` (usually `_O_RDWR | _O_APPEND | _O_CREAT`) | +| **`R`** | `_O_RDONLY` | +| **`r+`** | `_O_RDWR` | +| **`w`** | `_O_WRONLY` (usually `_O_WRONLY | _O_CREAT | _O_TRUNC`) | +| **`w+`** | `_O_RDWR` (usually **`_O_RDWR | _O_CREAT | _O_TRUNC`) | +| **`b`** | `_O_BINARY` | +| **`t`** | `_O_TEXT` (translated) | +| **`c`** | None | +| **`n`** | None | +| **`N`** | `_O_NOINHERIT` | +| **`D`** | `_O_TEMPORARY` | +| **`R`** | `_O_RANDOM` | +| **`S`** | `_O_SEQUENTIAL` | +| **`T`** | `_O_SHORTLIVED` | +| **`ccs=UNICODE`** | `_O_WTEXT` | +| **`ccs=UTF-8`** | `_O_UTF8` | +| **`ccs=UTF-16LE`** | `_O_UTF16` | + +The **`c`**, **`n`**, **`R`**, **`S`**, **`t`**, **`T`**, and **`D`** *`mode`* options are Microsoft extensions for `fopen_s` and `_wfopen_s` and shouldn't be used when you want ANSI portability. If you're using **`rb`** mode, memory mapped Win32 files might also be an option if you don't need to port your code, you expect to read much of the file, or you don't care about network performance. +Regarding `T` and `D`: +- `T` avoids writing the file to disk as long as memory pressure doesn't require it. For more information, see `FILE_ATTRIBUTE_TEMPORARY` in [File attribute constants](/windows/win32/fileio/file-attribute-constants), and also this blog post [It's only temporary](/archive/blogs/larryosterman/its-only-temporary). +- `D` specifies a regular file that is written to disk. The difference is that it's automatically deleted when it's closed. +You can combine `TD` to get both semantics. + ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fopen_s`**|``| -|**`_wfopen_s`**|`` or ``| +| Function | Required header | C++ header | +|--|--|--| +| **`fopen_s`** | `` | `` | +| **`_wfopen_s`** | `` or `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../compatibility.md). -## Libraries +### Generic-text routine mappings + +| `` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_tfopen_s`** | **`fopen_s`** | **`fopen_s`** | **`_wfopen_s`** | -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +## Libraries -The **`c`**, **`n`**, and **`t`** *`mode`* options are Microsoft extensions for **`fopen_s`** and [`_fdopen`](fdopen-wfdopen.md) and shouldn't be used where you want ANSI portability. +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -210,7 +218,7 @@ int main( void ) } // Open for write - err = fopen_s( &stream2, "data2", "w+" ); + err = fopen_s( &stream2, "data2", "w+, ccs=UTF-8" ); if( err == 0 ) { printf( "The file 'data2' was opened\n" ); @@ -248,7 +256,7 @@ Number of files closed by _fcloseall: 1 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`fclose`, `_fcloseall`](fclose-fcloseall.md)\ [`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`ferror`](ferror.md)\ diff --git a/docs/c-runtime-library/reference/fopen-wfopen.md b/docs/c-runtime-library/reference/fopen-wfopen.md index 564e22bc10..22d44f2421 100644 --- a/docs/c-runtime-library/reference/fopen-wfopen.md +++ b/docs/c-runtime-library/reference/fopen-wfopen.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: fopen, _wfopen" title: "fopen, _wfopen" -ms.date: "4/2/2020" +description: "Learn more about: fopen, _wfopen" +ms.date: 04/27/2023 api_name: ["_wfopen", "fopen", "_o__wfopen", "_o_fopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["fopen", "_wfopen", "_tfopen", "corecrt_wstdio/_wfopen", "stdio/fopen"] +f1_keywords: ["STDIO/fopen", "CORECRT_WSTDIO/_wfopen", "TCHAR/_tfopen", "fopen", "_wfopen", "_tfopen"] helpviewer_keywords: ["opening files, for file I/O", "wfopen function", "tfopen function", "_tfopen function", "_wfopen function", "files [C++], opening", "fopen function"] -ms.assetid: e868993f-738c-4920-b5e4-d8f2f41f933d --- # `fopen`, `_wfopen` -Opens a file. More-secure versions of these functions that perform additional parameter validation and return error codes are available; see [`fopen_s`, `_wfopen_s`](fopen-s-wfopen-s.md). +Opens a file. More-secure versions of these functions that perform more parameter validation and return error codes are available; see [`fopen_s`, `_wfopen_s`](fopen-s-wfopen-s.md). ## Syntax @@ -29,144 +28,152 @@ FILE *_wfopen( ### Parameters -*`filename`*
+*`filename`*\ File name. -*`mode`*
+*`mode`*\ Kind of access that's enabled. -## Return Value +## Return value -Each of these functions returns a pointer to the open file. A null pointer value indicates an error. If *filename* or *mode* is **NULL** or an empty string, these functions trigger the invalid parameter handler, which is described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **NULL** and set **errno** to **EINVAL**. +Each of these functions returns a pointer to the open file. A null pointer value indicates an error. If *`filename`* or *`mode`* is `NULL` or an empty string, these functions trigger the invalid parameter handler, which is described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set `errno` to `EINVAL`. -For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`fopen`** function opens the file that is specified by *filename*. By default, a narrow *filename* string is interpreted using the ANSI codepage (`CP_ACP`). In Windows Desktop applications this can be changed to the OEM codepage (`CP_OEMCP`) by using the [`SetFileApisToOEM`](/windows/win32/api/fileapi/nf-fileapi-setfileapistooem) function. You can use the [`AreFileApisANSI`](/windows/win32/api/fileapi/nf-fileapi-arefileapisansi) function to determine whether *filename* is interpreted using the ANSI or the system default OEM codepage. **`_wfopen`** is a wide-character version of **`fopen`**; the arguments to **`_wfopen`** are wide-character strings. Otherwise, **`_wfopen`** and **`fopen`** behave identically. Just using **`_wfopen`** does not affect the coded character set that is used in the file stream. +The **`fopen`** function opens the file specified by *`filename`*. By default, a narrow *`filename`* string is interpreted using the ANSI codepage (`CP_ACP`). In Windows Desktop applications, it can be changed to the OEM codepage (`CP_OEMCP`) by using the [`SetFileApisToOEM`](/windows/win32/api/fileapi/nf-fileapi-setfileapistooem) function. You can use the [`AreFileApisANSI`](/windows/win32/api/fileapi/nf-fileapi-arefileapisansi) function to determine whether *`filename`* is interpreted using the ANSI or the system default OEM codepage. **`_wfopen`** is a wide-character version of **`fopen`**; the **`_wfopen`** arguments are wide-character strings. Otherwise, **`_wfopen`** and **`fopen`** behave identically. Just using **`_wfopen`** doesn't affect the coded character set that's used in the file stream. -**`fopen`** accepts paths that are valid on the file system at the point of execution; **`fopen`** accepts UNC paths and paths that involve mapped network drives as long as the system that executes the code has access to the share or mapped drive at the time of execution. When you construct paths for **`fopen`**, make sure that drives, paths, or network shares will be available in the execution environment. You can use either forward slashes (/) or backslashes (\\) as the directory separators in a path. +**`fopen`** accepts paths that are valid on the file system at the point of execution; **`fopen`** accepts UNC paths and paths that involve mapped network drives as long as the system that executes the code has access to the share or mapped drive at the time of execution. When you construct paths for **`fopen`**, make sure that drives, paths, or network shares are available in the execution environment. You can use either forward slashes (`/`) or backslashes (`\`) as the directory separators in a path. -Always check the return value to see whether the pointer is NULL before you perform any additional operations on the file. If an error occurs, the global variable **`errno`** is set and may be used to obtain specific error information. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Always check the return value to see whether the pointer is NULL before you perform any other operations on the file. If an error occurs, the global variable `errno` is set, and may be used to obtain specific error information. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -## Unicode Support +## Unicode support -**`fopen`** supports Unicode file streams. To open a Unicode file, pass a **ccs** flag that specifies the desired encoding to **`fopen`**, as follows. +**`fopen`** supports Unicode file streams. To open a Unicode file, pass a `ccs=encoding` flag that specifies the desired encoding to **`fopen`**, as follows. -> **FILE \*fp = fopen("newfile.txt", "rt+, ccs=**_encoding_**");** +`FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");` -Allowed values of *encoding* are **UNICODE**, **UTF-8**, and **UTF-16LE**. +Allowed values for **`ccs`** encoding are `UNICODE`, **`UTF-8`**, and **`UTF-16LE`**. -When a file is opened in Unicode mode, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it is written, and the file's UTF-8-encoded content is translated into UTF-16 when it is read. An attempt to read or write an odd number of bytes in Unicode mode causes a [parameter validation](../../c-runtime-library/parameter-validation.md) error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You are responsible for any required encoding translation. +When a file is opened in Unicode mode, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a [parameter validation](../parameter-validation.md) error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If the file already exists and is opened for reading or appending, the Byte Order Mark (BOM), if it present in the file, determines the encoding. The BOM encoding takes precedence over the encoding that is specified by the **ccs** flag. The **ccs** encoding is only used when no BOM is present or the file is a new file. +If the file already exists and is opened for reading or appending, then any byte order mark (BOM) in the file determines the encoding. The BOM encoding takes precedence over the encoding specified by the **`ccs`** flag. The **`ccs`** encoding is only used when no BOM is present or the file is a new file. > [!NOTE] -> BOM detection only applies to files that are opened in Unicode mode (that is, by passing the **ccs** flag). +> BOM detection only applies to files that are opened in Unicode mode (that is, by passing the **`ccs`** flag). -The following table summarizes the modes that are used for various **ccs** flags given to **fopen** and Byte Order Marks in the file. +The following table summarizes the modes that are used for various **`ccs`** flags given to **`fopen`** and Byte Order Marks in the file. -### Encodings Used Based on ccs Flag and BOM +### Encodings used based on ccs flag and BOM -|ccs flag|No BOM (or new file)|BOM: UTF-8|BOM: UTF-16| -|----------------|----------------------------|-----------------|------------------| -|**UNICODE**|**UTF-16LE**|**UTF-8**|**UTF-16LE**| -|**UTF-8**|**UTF-8**|**UTF-8**|**UTF-16LE**| -|**UTF-16LE**|**UTF-16LE**|**UTF-8**|**UTF-16LE**| +| `ccs` flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 | +|--|--|--|--| +| `UNICODE` | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | +| **`UTF-8`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | +| **`UTF-16LE`** | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | Files opened for writing in Unicode mode have a BOM written to them automatically. -If *mode* is **a, ccs=*_encoding_***, **`fopen`** first tries to open the file by using both read and write access. If this succeeds, the function reads the BOM to determine the encoding for the file; if this fails, the function uses the default encoding for the file. In either case, **`fopen`** will then re-open the file by using write-only access. (This applies to **"a"** mode only, not to **"a+"** mode.) +If *`mode`* is **`a, ccs=encoding`** for some `encoding` value, **`fopen`** first tries to open the file by using both read and write access. If this action succeeds, the function reads the BOM to determine the encoding for the file. If it fails, the function uses the default encoding for the file. In either case, **`fopen`** reopens the file using write-only access. (This behavior applies to **`"a"`** mode only, not to **`"a+"`** mode.) + +### Generic-text routine mappings + +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_tfopen`** | **`fopen`** | **`fopen`** | **`_wfopen`** | -### Generic-Text Routine Mappings +The character string *`mode`* specifies the kind of access that is requested for the file, as follows. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tfopen`**|**`fopen`**|**`fopen`**|**`_wfopen`**| +| *`mode`* | Access | +|--|--| +| **`"r"`** | Opens for reading. If the file doesn't exist or can't be found, the **`fopen`** call fails. | +| **`"w"`** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | +| **`"a"`** | Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Creates the file if it doesn't exist. | +| **`"r+"`** | Opens for both reading and writing. The file must exist. | +| **`"w+"`** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | +| **`"a+"`** | Opens for reading and appending. The appending operation includes the removal of the EOF marker before new data is written to the file. The EOF marker isn't restored after writing is completed. Creates the file if it doesn't exist. | -The character string *mode* specifies the kind of access that is requested for the file, as follows. +When a file is opened by using the **`"a"`** access type or the **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but is always moved back to the end of the file before any write operation is performed. Therefore, existing data can't be overwritten. -|*mode*|Access| -|-|-| -| **"r"** | Opens for reading. If the file does not exist or cannot be found, the **`fopen`** call fails. | -| **"w"** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | -| **"a"** | Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Creates the file if it does not exist. | -| **"r+"** | Opens for both reading and writing. The file must exist. | -| **"w+"** | Opens an empty file for both reading and writing. If the file exists, its contents are destroyed. | -| **"a+"** | Opens for reading and appending. The appending operation includes the removal of the EOF marker before new data is written to the file. The EOF marker is not restored after writing is completed. Creates the file if it does not exist. | +The **`"a"`** mode doesn't remove the EOF marker before it appends to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. Before it appends to the file, the **`"a+"`** mode does remove the EOF marker. After appending, the MS-DOS TYPE command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the `CTRL`+**Z** EOF marker. -When a file is opened by using the **"a"** access type or the **"a+"** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but is always moved back to the end of the file before any write operation is performed. Therefore, existing data cannot be overwritten. +When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are enabled (the file is said to be open for "update"). However, when you switch from reading to writing, the input operation must encounter an EOF marker. If there's no EOF, you must use an intervening call to a file positioning function. The file positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file positioning function. -The **"a"** mode does not remove the EOF marker before it appends to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. Before it appends to the file, the **"a+"** mode does remove the EOF marker. After appending, the MS-DOS TYPE command shows all data in the file. The **"a+"** mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker. +In addition to the earlier values, the following characters can be appended to *`mode`* to specify the translation mode for newline characters. -When the **"r+"**, **"w+"**, or **"a+"** access type is specified, both reading and writing are enabled (the file is said to be open for "update"). However, when you switch from reading to writing, the input operation must encounter an EOF marker. If there is no EOF, you must use an intervening call to a file positioning function. The file positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file positioning function. +| *`mode`* modifier | Translation mode | +|--|--| +| **`t`** | Open in text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input and LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. | +| **`b`** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | -In addition to the earlier values, the following characters can be appended to *mode* to specify the translation mode for newline characters. +In text mode, `CTRL`+**Z** is interpreted as an EOF character on input. In files that are opened for reading/writing by using **`"a+"`**, **`fopen`** checks for a `CTRL`+**Z** at the end of the file and removes it, if it's possible. It's removed because using [`fseek`](fseek-fseeki64.md) and **`ftell`** to move within a file that ends with `CTRL`+**Z** may cause [`fseek`](fseek-fseeki64.md) to behave incorrectly near the end of the file. -|*mode* modifier|Translation mode| -|-|-| -| **t** | Open in text (translated) mode. | -| **b** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | +In text mode, carriage return-line feed (CRLF) combinations are translated into single line feed (LF) characters on input, and LF characters are translated to CRLF combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function). -In text mode, CTRL+Z is interpreted as an EOF character on input. In files that are opened for reading/writing by using **"a+"**, **fopen** checks for a CTRL+Z at the end of the file and removes it, if it is possible. This is done because using [`fseek`](fseek-fseeki64.md) and **ftell** to move within a file that ends with CTRL+Z may cause [`fseek`](fseek-fseeki64.md) to behave incorrectly near the end of the file. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -In text mode, carriage return-line feed combinations are translated into single line feeds on input, and line feed characters are translated to carriage return-line feed combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function). +For more information about how to use text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -If **t** or **b** is not given in *mode*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **t** or **b** is prefixed to the argument, the function fails and returns **NULL**. +The following options can be appended to *`mode`* to specify more behaviors. -For more information about how to use text and binary modes in Unicode and multibyte stream-I/O, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +| *`mode`* modifier | Behavior | +|--|--| +| **`x`** | Forces the function to fail if *`filename`* already exists. Can only be used with the "w" or "w+" specifiers. | +| **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with COMMODE.OBJ. The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see [Link options](../link-options.md)). | +| **`N`** | Specifies that the file isn't inherited by child processes. | +| **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| **`T`** | Specifies a file that isn't written to disk unless memory pressure requires it. | +| **`D`** | Specifies a temporary file that's deleted when the last file pointer to it is closed. | +| **`ccs=encoding`** | Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or `UNICODE`) for this file. Leave unspecified if you want ANSI encoding. This flag is separated from flags that precede it by a comma (`,`). For example: `FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");` | -The following options can be appended to *mode* to specify additional behaviors. +Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdopen`** correspond to *`oflag`* arguments that are used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as follows. -|*mode* modifier|Behavior| -|-|-| -| **x** | Forces the function to fail if *filename* already exists. Can only be used with the "w" or "w+" specifiers. | -| **c** | Enable the commit flag for the associated *filename* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | -| **n** | Reset the commit flag for the associated *filename* to "no-commit." This is the default. It also overrides the global commit flag if you link your program with COMMODE.OBJ. The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see [Link Options](../../c-runtime-library/link-options.md)). | -| **N** | Specifies that the file is not inherited by child processes. | -| **S** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | -| **R** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **T** | Specifies a file as temporary. If possible, it is not flushed to disk. | -| **D** | Specifies a file as temporary. It is deleted when the last file pointer is closed. | -| **ccs=**_encoding_ | Specifies the encoded character set to use (one of **UTF-8**, **UTF-16LE**, or **UNICODE**) for this file. Leave unspecified if you want ANSI encoding. | +| Characters in *`mode`* string | Equivalent *`oflag`* value for `_open`/`_sopen` | +|--|--| +| **`a`** | `_O_WRONLY | _O_APPEND` (usually `_O_WRONLY | _O_CREAT | _O_APPEND`) | +| **`a+`** | `_O_RDWR | _O_APPEND` (usually `_O_RDWR | _O_APPEND | _O_CREAT`) | +| **`r`** | `_O_RDONLY` | +| **`r+`** | `_O_RDWR` | +| **`w`** | `_O_WRONLY` (usually `_O_WRONLY | _O_CREAT | _O_TRUNC`) | +| **`w+`** | `_O_RDWR` (usually `_O_RDWR | _O_CREAT | _O_TRUNC`) | +| **`b`** | `_O_BINARY` | +| **`t`** | `_O_TEXT` (translated) | +| **`x`** | `_O_EXCL` | +| **`c`** | None | +| **`n`** | None | +| **`N`** | `_O_NOINHERIT` | +| **`S`** | `_O_SEQUENTIAL` | +| **`R`** | `_O_RANDOM` | +| **`T`** | `_O_SHORTLIVED` | +| **`D`** | `_O_TEMPORARY` | +| **`ccs=UNICODE`** | `_O_WTEXT` | +| **`ccs=UTF-8*`* | `_O_UTF8` | +| **`ccs=UTF-16LE`** | `_O_UTF16` | -Valid characters for the *mode* string that is used in **`fopen`** and **`_fdopen`** correspond to *oflag* arguments that are used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as follows. +If you're using **`rb`** mode, you don't have to port your code, and if you expect to read most of a large file or aren't concerned about network performance, you might also consider whether to use memory mapped Win32 files as an option. -|Characters in *mode* string|Equivalent *oflag* value for \_open/\_sopen| -|-------------------------------|----------------------------------------------------| -|**a**|**\_O\_WRONLY** | **\_O\_APPEND** (usually **\_O\_WRONLY** | **\_O\_CREAT** | **\_O\_APPEND**)| -|**a+**|**\_O\_RDWR** | **\_O\_APPEND** (usually **\_O\_RDWR** | **\_O\_APPEND** | **\_O\_CREAT** )| -|**r**|**\_O\_RDONLY**| -|**r+**|**\_O\_RDWR**| -|**w**|**\_O\_WRONLY** (usually **\_O\_WRONLY** | **\_O\_CREAT** | **\_O\_TRUNC**)| -|**w+**|**\_O\_RDWR** (usually **\_O\_RDWR** | **\_O\_CREAT** | **\_O\_TRUNC**)| -|**b**|**\_O\_BINARY**| -|**t**|**\_O\_TEXT**| -|**x**|**\_O\_EXCL**| -|**c**|None| -|**n**|None| -|**S**|**\_O\_SEQUENTIAL**| -|**R**|**\_O\_RANDOM**| -|**T**|**\_O\_SHORTLIVED**| -|**D**|**\_O\_TEMPORARY**| -|**ccs=UNICODE**|**\_O\_WTEXT**| -|**ccs=UTF-8**|**\_O\_UTF8**| -|**ccs=UTF-16LE**|**\_O\_UTF16**| +Regarding `T` and `D`: +- `T` avoids writing the file to disk as long as memory pressure doesn't require it. For more information, see `FILE_ATTRIBUTE_TEMPORARY` in [File attribute constants](/windows/win32/fileio/file-attribute-constants), and also this blog post [It's only temporary](/archive/blogs/larryosterman/its-only-temporary). +- `D` specifies a regular file that is written to disk. The difference is that it's automatically deleted when it's closed. +You can combine `TD` to get both semantics. -If you are using **rb** mode, you do not have to port your code, and if you expect to read most of a large file or are not concerned about network performance, you might also consider whether to use memory mapped Win32 files as an option. +The **`c`**, **`n`**, **`R`**, **`S`**, **`t`**, **`T`**, and **`D`** *`mode`* options are Microsoft extensions for `fopen` and `_wfopen` and shouldn't be used when you want ANSI portability. ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fopen`**|``| -|**`_wfopen`**|`` or ``| +| Function | Required header | +|--|--| +| **`fopen`** | `` | +| **`_wfopen`** | `` or `` | -**`_wfopen`** is a Microsoft extension. For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_wfopen`** is a Microsoft extension. For more information about compatibility, see [Compatibility](../compatibility.md). -The **c**, **n**, **t**, **S**, **R**, **T**, and **D** *mode* options are Microsoft extensions for **`fopen`** and **`_fdopen`** and should not be used where ANSI portability is desired. +The **`c`**, **`n`**, **`t`**, **`S`**, **`R`**, **`T`**, and **`D`** *`mode`* options are Microsoft extensions for **`fopen`** and **`_fdopen`** and shouldn't be used where ANSI portability is desired. ## Example 1 @@ -223,7 +230,7 @@ Number of files closed by _fcloseall: 1 ## Example 2 -The following program creates a file (or overwrites one if it exists), in text mode that has Unicode encoding. It then writes two strings into the file and closes the file. The output is a file named *_wfopen_test.xml*, which contains the data from the output section. +The following program creates a file (or overwrites one if it exists), in text mode that has Unicode encoding. It then writes two strings into the file and closes the file. The output is a file named *`_wfopen_test.xml`*, which contains the data from the output section. ```C // crt__wfopen.c @@ -281,13 +288,13 @@ int main(int argc, char** argv) ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`fclose`, `_fcloseall`](fclose-fcloseall.md)
-[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)
-[`ferror`](ferror.md)
-[`_fileno`](fileno.md)
-[`freopen`, `_wfreopen`](freopen-wfreopen.md)
-[`_open`, `_wopen`](open-wopen.md)
-[`_setmode`](setmode.md)
-[`_sopen`, `_wsopen`](sopen-wsopen.md)
+[Stream I/O](../stream-i-o.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`ferror`](ferror.md)\ +[`_fileno`](fileno.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_setmode`](setmode.md)\ +[`_sopen`, `_wsopen`](sopen-wsopen.md) diff --git a/docs/c-runtime-library/reference/fpclass-fpclassf.md b/docs/c-runtime-library/reference/fpclass-fpclassf.md index 01b12f22ec..a77c27c192 100644 --- a/docs/c-runtime-library/reference/fpclass-fpclassf.md +++ b/docs/c-runtime-library/reference/fpclass-fpclassf.md @@ -3,7 +3,7 @@ description: "Learn more about: _fpclass, _fpclassf" title: "_fpclass, _fpclassf" ms.date: "1/15/2021" api_name: ["_fpclass", "_fpclassf", "_o__fpclass", "_o__fpclassf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fpclass", "_fpclass", "_fpclassf", "math/_fpclass", "float/_fpclass", "math/_fpclassf"] @@ -30,39 +30,39 @@ int _fpclassf( *`x`*\ The floating-point value to test. -## Return Value +## Return value The **`_fpclass`** and **`_fpclassf`** functions return an integer value that indicates the floating-point classification of the argument *`x`*. The classification may have one of the following values, defined in ``. -|Value|Description| -|-----------|-----------------| -|**`_FPCLASS_SNAN`**|Signaling NaN| -|**`_FPCLASS_QNAN`**|Quiet NaN| -|**`_FPCLASS_NINF`**|Negative infinity (`-INF`)| -|**`_FPCLASS_NN`**|Negative normalized non-zero| -|**`_FPCLASS_ND`**|Negative denormalized| -|**`_FPCLASS_NZ`**|Negative zero (-0)| -|**`_FPCLASS_PZ`**|Positive 0 (+0)| -|**`_FPCLASS_PD`**|Positive denormalized| -|**`_FPCLASS_PN`**|Positive normalized non-zero| -|**`_FPCLASS_PINF`**|Positive infinity (`+INF`)| +| Value | Description | +|---|---| +| `_FPCLASS_SNAN` | Signaling NaN | +| `_FPCLASS_QNAN` | Quiet NaN | +| `_FPCLASS_NINF` | Negative infinity (`-INF`) | +| `_FPCLASS_NN` | Negative normalized non-zero | +| `_FPCLASS_ND` | Negative denormalized | +| `_FPCLASS_NZ` | Negative zero (-0) | +| `_FPCLASS_PZ` | Positive 0 (+0) | +| `_FPCLASS_PD` | Positive denormalized | +| `_FPCLASS_PN` | Positive normalized non-zero | +| `_FPCLASS_PINF` | Positive infinity (`+INF`) | ## Remarks -The **`_fpclass`** and **`_fpclassf`** functions are Microsoft-specific. They are similar to [`fpclassify`](fpclassify.md), but return more detailed information about the argument. The **`_fpclassf`** function is only available when compiled for the x64 platform. +The **`_fpclass`** and **`_fpclassf`** functions are Microsoft-specific. They're similar to [`fpclassify`](fpclassify.md), but return more detailed information about the argument. The **`_fpclassf`** function is only available when compiled for the x64 platform. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_fpclass`**, **`_fpclassf`**|``| +| Function | Required header | +|---|---| +| **`_fpclass`**, **`_fpclassf`** | `` | -For more compatibility and conformance information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility and conformance information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ [`fpclassify`](fpclassify.md) diff --git a/docs/c-runtime-library/reference/fpclassify.md b/docs/c-runtime-library/reference/fpclassify.md index e046e387ea..94f55eb792 100644 --- a/docs/c-runtime-library/reference/fpclassify.md +++ b/docs/c-runtime-library/reference/fpclassify.md @@ -9,7 +9,7 @@ f1_keywords: ["fpclassify", "math/fpclassify"] helpviewer_keywords: ["fpclassify macro", "fpclassify function"] ms.assetid: bf549499-7ff9-4a58-8692-f2d1cb6bab81 --- -# fpclassify +# `fpclassify` Returns the floating-point classification of the argument. @@ -35,34 +35,34 @@ int fpclassify( ### Parameters -*x*
+*`x`*\ The floating-point value to test. -## Return Value +## Return value -**fpclassify** returns an integer value that indicates the floating-point class of the argument *x*. This table shows the possible values returned by **fpclassify**, defined in \. +**`fpclassify`** returns an integer value that indicates the floating-point class of the argument *`x`*. This table shows the possible values returned by **`fpclassify`**, defined in \. -|Value|Description| -|-----------|-----------------| -|**FP_NAN**|A quiet, signaling, or indeterminate NaN| -|**FP_INFINITE**|A positive or negative infinity| -|**FP_NORMAL**|A positive or negative normalized non-zero value| -|**FP_SUBNORMAL**|A positive or negative denormalized value| -|**FP_ZERO**|A positive or negative zero value| +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative denormalized value | +| `FP_ZERO` | A positive or negative zero value | ## Remarks -In C, **fpclassify** is a macro; in C++, **fpclassify** is a function overloaded using argument types of **`float`**, **`double`**, or **`long double`**. In either case, the value returned depends on the effective type of the argument expression, and not on any intermediate representation. For example, a normal **`double`** or **`long double`** value can become an infinity, denormal, or zero value when converted to a **`float`**. +In C, **`fpclassify`** is a macro; in C++, **`fpclassify`** is a function overloaded using argument types of **`float`**, **`double`**, or **`long double`**. In either case, the value returned depends on the effective type of the argument expression, and not on any intermediate representation. For example, a normal **`double`** or **`long double`** value can become an infinity, denormal, or zero value when converted to a **`float`**. ## Requirements -|Function/Macro|Required header (C)|Required header (C++)| -|---------------------|---------------------------|-------------------------------| -|**fpclassify**|\|\ or \| +| Function/Macro | Required header (C) | Required header (C++) | +|---|---|---| +| **`fpclassify`** | \ | \ or \ | -The **fpclassify** macro and **fpclassify** functions conform to the ISO C99 and C++11 specifications. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`fpclassify`** macro and **`fpclassify`** functions conform to the ISO C99 and C++11 specifications. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md) diff --git a/docs/c-runtime-library/reference/fpieee-flt.md b/docs/c-runtime-library/reference/fpieee-flt.md index 2eee8eee71..a0c5b419e3 100644 --- a/docs/c-runtime-library/reference/fpieee-flt.md +++ b/docs/c-runtime-library/reference/fpieee-flt.md @@ -10,7 +10,7 @@ f1_keywords: ["fpieee_flt", "_fpieee_flt"] helpviewer_keywords: ["_fpieee_flt function", "exception handling, floating-point", "floating-point exception handling", "fpieee_flt function"] ms.assetid: 2bc4801e-0eed-4e73-b518-215da8cc9740 --- -# _fpieee_flt +# `_fpieee_flt` Invokes a user-defined trap handler for IEEE floating-point exceptions. @@ -26,41 +26,41 @@ int _fpieee_flt( ### Parameters -*excCode*
+*`excCode`*\ Exception code. -*excInfo*
+*`excInfo`*\ Pointer to the Windows NT exception information structure. -*handler*
+*`handler`*\ Pointer to the user's IEEE trap-handler routine. -## Return Value +## Return value -The return value of **_fpieee_flt** is the value returned by *handler*. As such, the IEEE filter routine might be used in the except clause of a structured exception-handling (SEH) mechanism. +The return value of **`_fpieee_flt`** is the value returned by *`handler`*. As such, the IEEE filter routine might be used in the except clause of a structured exception-handling (SEH) mechanism. ## Remarks -The **_fpieee_flt** function invokes a user-defined trap handler for IEEE floating-point exceptions and provides it with all relevant information. This routine serves as an exception filter in the SEH mechanism, which invokes your own IEEE exception handler when necessary. +The **`_fpieee_flt`** function invokes a user-defined trap handler for IEEE floating-point exceptions and provides it with all relevant information. This routine serves as an exception filter in the SEH mechanism, which invokes your own IEEE exception handler when necessary. -The **_FPIEEE_RECORD** structure, defined in Fpieee.h, contains information pertaining to an IEEE floating-point exception. This structure is passed to the user-defined trap handler by **_fpieee_flt**. +The `_FPIEEE_RECORD` structure, defined in Fpieee.h, contains information pertaining to an IEEE floating-point exception. This structure is passed to the user-defined trap handler by **`_fpieee_flt`**. -|_FPIEEE_RECORD field|Description| -|----------------------------|-----------------| -|**RoundingMode**
**Precision**|These **`unsigned int`** fields contain information about the floating-point environment at the time the exception occurred.| -|**Operation**|This **`unsigned int`** field indicates the type of operation that caused the trap. If the type is a comparison (**_FpCodeCompare**), you can supply one of the special **_FPIEEE_COMPARE_RESULT** values (as defined in Fpieee.h) in the **Result.Value** field. The conversion type (**_FpCodeConvert**) indicates that the trap occurred during a floating-point conversion operation. You can look at the **Operand1** and **Result** types to determine the type of conversion being attempted.| -|**Operand1**
**Operand2**
**Result**|These **_FPIEEE_VALUE** structures indicate the types and values of the proposed result and operands. Each structure contains these fields:

**OperandValid** - Flag indicating whether the responding value is valid.
**Format** - Data type of the corresponding value. The format type might be returned even if the corresponding value is not valid.
**Value** - Result or operand data value.| -|**Cause**
**Enable**
**Status**|**_FPIEEE_EXCEPTION_FLAGS** contains one bit field per type of floating point exception. There is a correspondence between these fields and the arguments used to mask the exceptions supplied to [_controlfp](control87-controlfp-control87-2.md). The exact meaning of each bit depends on context:

**Cause** - Each set bit indicates the particular exception that was raised.
**Enable** - Each set bit indicates that the particular exception is currently unmasked.
**Status** - Each set bit indicates that the particular exception is currently pending. This includes exceptions that have not been raised because they were masked by **_controlfp**.| +| _FPIEEE_RECORD field | Description | +|---|---| +| `RoundingMode`
`Precision` | These **`unsigned int`** fields contain information about the floating-point environment at the time the exception occurred. | +| `Operation` | This **`unsigned int`** field indicates the type of operation that caused the trap. If the type is a comparison (`_FpCodeCompare`), you can supply one of the special `_FPIEEE_COMPARE_RESULT` values (as defined in Fpieee.h) in the **Result.Value** field. The conversion type (`_FpCodeConvert`) indicates that the trap occurred during a floating-point conversion operation. You can look at the `Operand1` and `Result` types to determine the type of conversion being attempted. | +| `Operand1`
`Operand2`
`Result` | These `_FPIEEE_VALUE` structures indicate the types and values of the proposed result and operands. Each structure contains these fields:

`OperandValid` - Flag indicating whether the responding value is valid.
`Format` - Data type of the corresponding value. The format type might be returned even if the corresponding value isn't valid.
`Value` - Result or operand data value. | +| `Cause`
`Enable`
`Status` | `_FPIEEE_EXCEPTION_FLAGS` contains a bit field for each type of floating point exception. There's a correspondence between these fields and the arguments used to mask the exceptions supplied to [`_controlfp`](control87-controlfp-control87-2.md). The exact meaning of each bit depends on context:

`Cause` - Each set bit indicates the particular exception that was raised.
`Enable` - Each set bit indicates that the particular exception is currently unmasked.
`Status` - Each set bit indicates that the particular exception is currently pending, which includes exceptions that haven't been raised because they were masked by `_controlfp`. | -Pending exceptions that are disabled are raised when you enable them. This can result in undefined behavior when using **_fpieee_flt** as an exception filter. Always call [_clearfp](clear87-clearfp.md) before enabling floating point exceptions. +Pending exceptions that are disabled are raised when you enable them. These exceptions can result in undefined behavior when using **`_fpieee_flt`** as an exception filter. Always call [`_clearfp`](clear87-clearfp.md) before enabling floating point exceptions. ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fpieee_flt**|\| +| Function | Required header | +|---|---| +| **`_fpieee_flt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -131,6 +131,6 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md)
-[_controlfp_s](controlfp-s.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md)\ +[`_controlfp_s`](controlfp-s.md) diff --git a/docs/c-runtime-library/reference/fpreset.md b/docs/c-runtime-library/reference/fpreset.md index 0e1eec7e0c..fd9aa995d8 100644 --- a/docs/c-runtime-library/reference/fpreset.md +++ b/docs/c-runtime-library/reference/fpreset.md @@ -10,7 +10,7 @@ f1_keywords: ["_fpreset", "fpreset"] helpviewer_keywords: ["fpreset function", "floating-point numbers, resetting math package", "_fpreset function"] ms.assetid: f31c6a04-b464-4f07-a7c4-42133360e328 --- -# _fpreset +# `_fpreset` Resets the floating-point package. @@ -22,17 +22,17 @@ void _fpreset( void ); ## Remarks -The **_fpreset** function reinitializes the floating-point math package. **_fpreset** is usually used with **signal**, **system**, or the **_exec** or **_spawn** functions. If a program traps floating-point error signals (**SIGFPE**) with **signal**, it can safely recover from floating-point errors by invoking **_fpreset** and using **longjmp**. +The **`_fpreset`** function reinitializes the floating-point math package. **`_fpreset`** is often used with `signal`, `system`, or the `_exec` or `_spawn` functions. If a program traps floating-point error signals (`SIGFPE`) with `signal`, it can safely recover from floating-point errors by invoking **`_fpreset`** and using `longjmp`. This function is deprecated when compiling with [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime only supports the default floating-point precision. ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fpreset**|\| +| Function | Required header | +|---|---| +| **`_fpreset`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,8 +150,8 @@ Error 131: Divide by zero ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[signal](signal.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`signal`](signal.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md b/docs/c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md index a9d5954470..2d972d963a 100644 --- a/docs/c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md +++ b/docs/c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: fprintf, _fprintf_l, fwprintf, _fwprintf_l" -title: "fprintf, _fprintf_l, fwprintf, _fwprintf_l" +description: "Learn more about: fprintf, _fprintf_l, fwprintf, _ftprintf, _ftprintf_l" +title: "fprintf, _fprintf_l, fwprintf, _fwprintf_l, _ftprintf, _ftprintf_l" ms.date: "3/9/2021" -api_name: ["fwprintf", "fprintf", "_fprintf_l", "_fwprintf_l"] +api_name: ["fwprintf", "fprintf", "_fprintf_l", "_fwprintf_l", "_ftprintf", "_ftprintf_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["fprintf", "fwprintf", "_ftprintf"] -helpviewer_keywords: ["_fwprintf_l function", "fprintf function", "fprintf_l function", "_fprintf_l function", "_ftprintf function", "fwprintf function", "ftprintf_l function", "ftprintf function", "_ftprintf_l function", "print formatted data to streams", "fwprintf_l function"] +f1_keywords: ["fprintf", "fwprintf", "_ftprintf", "_fwprintf_l", "_ftprintf_l"] +helpviewer_keywords: ["fprintf function", "fprintf_l function", "_fprintf_l function", "_ftprintf function", "fwprintf function", "ftprintf_l function", "ftprintf function", "print formatted data to streams", "fwprintf_l function", "_ftprintf_l function"] --- -# `fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l` +# `fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`, `_ftprintf`, `_ftprintf_l` Print formatted data to a stream. More secure versions of these functions are available; see [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md). +For `_ftprintf` and `_ftprintf_l`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -42,55 +44,56 @@ int _fwprintf_l( ### Parameters -*`stream`*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*`format`*
+*`format`*\ Format-control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**`fprintf`** returns the number of bytes written. **`fwprintf`** returns the number of wide characters written. Each of these functions returns a negative value instead when an output error occurs. If *`stream`* or *`format`* is **`NULL`**, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **`errno`** to **`EINVAL`**. The format string is not checked for valid formatting characters as it is when using **`fprintf_s`** or **`fwprintf_s`**. +**`fprintf`** returns the number of bytes written. **`fwprintf`** returns the number of wide characters written. Each of these functions returns a negative value instead when an output error occurs. If *`stream`* or *`format`* is `NULL`, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. The format string isn't checked for valid formatting characters as it is when using **`fprintf_s`** or **`fwprintf_s`**. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -**`fprintf`** formats and prints a series of characters and values to the output *`stream`*. Each function *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. For **`fprintf`**, the *`format`* argument has the same syntax and use that it has in **`printf`**. +**`fprintf`** formats and prints a series of characters and values to the output *`stream`*. Each function *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. For **`fprintf`**, the *`format`* argument has the same syntax that it has in **`printf`**. -**`fwprintf`** is a wide-character version of **`fprintf`**; in **`fwprintf`**, *`format`* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fprintf`** does not currently support output into a UNICODE stream. +**`fwprintf`** is a wide-character version of **`fprintf`**; in **`fwprintf`**, *`format`* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fprintf`** doesn't currently support output into a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text function mappings + +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_ftprintf`**|**`fprintf`**|**`fprintf`**|**`fwprintf`**| -|**`_ftprintf_l`**|**`_fprintf_l`**|**`_fprintf_l`**|**`_fwprintf_l`**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ftprintf` | `fprintf` | `fprintf` | `fwprintf` | +| `_ftprintf_l` | `_fprintf_l` | `_fprintf_l` | `_fwprintf_l` | -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fprintf`**, **`_fprintf_l`**|``| -|**`fwprintf`**, **`_fwprintf_l`**|`` or ``| +| Function | Required header | +|---|---| +| **`fprintf`**, **`_fprintf_l`** | `` | +| **`fwprintf`**, **`_fwprintf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -131,8 +134,8 @@ this is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `_swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `_swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md b/docs/c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md index 41555638d5..8ed284f343 100644 --- a/docs/c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md +++ b/docs/c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: _fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l" +description: "Learn more about: _fprintf_p, _fprintf_p_l, _ftprintf_p, _ftprintf_p_l, _fwprintf_p, _fwprintf_p_l" title: "_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l" ms.date: "3/9/2021" api_name: ["_fwprintf_p", "_fprintf_p_l", "_fwprintf_p_l", "_fprintf_p"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_fprintf_p", "_ftprintf_p", "fwprintf_p", "_fwprintf_p", "fprintf_p", "ftprintf_p"] -helpviewer_keywords: ["fprintf_p_l function", "fprintf_p function", "_fprintf_p_l function", "_fprintf_p function", "_ftprintf_p_l function", "streams, printing formatted data to", "_fwprintf_p function", "fwprintf_p function", "_ftprintf_p function", "_fwprintf_p_l function", "ftprintf_p function", "printing [C++], formatted data to streams", "ftprintf_p_l function", "fwprintf_p_l function"] +f1_keywords: ["_fprintf_p", "_ftprintf_p", "_ftprintf_p_l", "fwprintf_p", "_fwprintf_p", "fprintf_p", "ftprintf_p", "_fwprintf_p_l"] +helpviewer_keywords: ["fprintf_p_l function", "fprintf_p function", "_fprintf_p_l function", "_fprintf_p function", "_ftprintf_p function", "_ftprintf_p_l function", "streams, printing formatted data to", "_fwprintf_p function", "fwprintf_p function", "_fwprintf_p_l function", "ftprintf_p function", "printing [C++], formatted data to streams", "ftprintf_p_l function", "fwprintf_p_l function"] --- -# _fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l +# `_fprintf_p`, `_fprintf_p_l`, `_ftprintf_p`, `_ftprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l` Prints formatted data to a stream. +For `_ftprintf_p` and `_ftprintf_p_l`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -42,55 +44,56 @@ int _fwprintf_p_l( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_fprintf_p** and **_fwprintf_p** return the number of characters written or return a negative value when an output error occurs. +**`_fprintf_p`** and **`_fwprintf_p`** return the number of characters written or return a negative value when an output error occurs. ## Remarks -**_fprintf_p** formats and prints a series of characters and values to the output *stream*. Each function *argument* (if any) is converted and output according to the corresponding format specification in *format*. For **_fprintf_p**, the *format* argument has the same syntax and use that it has in **_printf_p**. These functions support positional parameters, meaning that the order of the parameters used by the format string can be changed. For more information about positional parameters, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +**`_fprintf_p`** formats and prints a series of characters and values to the output *`stream`*. Each function *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. For **`_fprintf_p`**, the *`format`* argument has the same syntax that it has in `_printf_p`. These functions support positional parameters, meaning that the order of the parameters used by the format string can be changed. For more information about positional parameters, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_fwprintf_p** is a wide-character version of **_fprintf_p**; in **_fwprintf_p**, *format* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **_fprintf_p** doesn't currently support output into a UNICODE stream. +**`_fwprintf_p`** is a wide-character version of **`_fprintf_p`**; in **`_fwprintf_p`**, *`format`* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`_fprintf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -Like the non-secure versions (see [fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if either *stream* or *format* is a null pointer or if there are any unknown or badly formed formatting specifiers. If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +Like the non-secure versions (see [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), if either *`stream`* or *`format`* is a null pointer or if there are any unknown or badly formed formatting specifiers. If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. + +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_ftprintf_p**|**_fprintf_p**|**_fprintf_p**|**_fwprintf_p**| -|**_ftprintf_p_l**|**_fprintf_p_l**|**_fprintf_p_l**|**_fwprintf_p_l**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ftprintf_p` | `_fprintf_p` | `_fprintf_p` | `_fwprintf_p` | +| `_ftprintf_p_l` | `_fprintf_p_l` | `_fprintf_p_l` | `_fwprintf_p_l` | -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fprintf_p**, **_fprintf_p_l**|\| -|**_fwprintf_p**, **_fwprintf_p_l**|\ or \| +| Function | Required header | +|---|---| +| `_fprintf_p`, `_fprintf_p_l` | `` | +| `_fwprintf_p`, `_fwprintf_p_l` | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -138,12 +141,12 @@ this is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
-[_cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l](cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)
-[_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md)\ +[`_cprintf_p`, `_cprintf_p_l`, `_cwprintf_p`, `_cwprintf_p_l`](cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)\ +[`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) diff --git a/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md b/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md index 91a017f4e7..225ec4abc7 100644 --- a/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md +++ b/docs/c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l" -title: "fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l" +description: "Learn more about: fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l, _ftprintf_s, _ftprintf_s_l" +title: "fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l, _ftprintf_s, _ftprintf_s_l" ms.date: "3/9/2021" -api_name: ["_fprintf_s_l", "fwprintf_s", "fprintf_s", "_fwprintf_s_l"] +api_name: ["_fprintf_s_l", "fwprintf_s", "fprintf_s", "_fwprintf_s_l", "_ftprintf_s", "_ftprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ftprintf_s", "fprintf_s", "fwprintf_s"] -helpviewer_keywords: ["ftprintf_s_l function", "ftprintf_s function", "_fprintf_s_l function", "_ftprintf_s function", "_ftprintf_s_l function", "fwprintf_s_l function", "fwprintf_s function", "fprintf_s_l function", "fprintf_s function", "_fwprintf_s_l function", "print formatted data to streams"] +f1_keywords: ["_ftprintf_s", "_ftprintf_s_l", "fprintf_s", "fwprintf_s", "_fwprintf_s_l", "_ftprintf", "_ftprintf_l"] +helpviewer_keywords: ["ftprintf_s_l function", "ftprintf_s function", "_ftprintf_l function", "_fprintf_s_l function", "_ftprintf_s function", "_ftprintf_s_l function", "fwprintf_s_l function", "fwprintf_s function", "fprintf_s_l function", "fprintf_s function", "_fwprintf_s_l function", "_fwprintf_s_l function", "print formatted data to streams"] --- -# fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l +# `fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`, `_ftprintf`, `_ftprintf_l`, `_ftprintf_s`, `_ftprintf_s_l` -Print formatted data to a stream. These are versions of [fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Print formatted data to a stream. These functions are versions of [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). + +For `_ftprintf_s` and `_ftprintf_s_l`, see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -42,55 +44,56 @@ int _fwprintf_s_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*argument_list*
+*`argument_list`*\ Optional arguments to the format string. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**fprintf_s** returns the number of bytes written. **fwprintf_s** returns the number of wide characters written. Each of these functions returns a negative value instead when an output error occurs. +**`fprintf_s`** returns the number of bytes written. **`fwprintf_s`** returns the number of wide characters written. Each of these functions returns a negative value instead when an output error occurs. ## Remarks -**fprintf_s** formats and prints a series of characters and values to the output *stream*. Each argument in *argument_list* (if any) is converted and output according to the corresponding format specification in *format*. The *format* argument uses the [format specification syntax for printf and wprintf functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +**`fprintf_s`** formats and prints a series of characters and values to the output *`stream`*. Each argument in *`argument_list`* (if any) is converted and output according to the corresponding format specification in *`format`*. The *`format`* argument uses the [format specification syntax for `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -**fwprintf_s** is a wide-character version of **fprintf_s**; in **fwprintf_s**, *format* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **fprintf_s** doesn't currently support output into a UNICODE stream. +**`fwprintf_s`** is a wide-character version of **`fprintf_s`**; in **`fwprintf_s`**, *`format`* is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fprintf_s`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -Like the non-secure versions (see [fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if either *stream* or *format* is a null pointer. The format string itself is also validated. If there are any unknown or badly formed formatting specifiers, these functions generate the invalid parameter exception. In all cases, If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +Like the non-secure versions (see [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)), these functions validate their parameters and invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), if either *`stream`* or *`format`* is a `NULL` pointer. The format string itself is also validated. If there are any unknown or badly formed formatting specifiers, these functions generate the invalid parameter exception. In all cases, If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). + +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ftprintf_s**|**fprintf_s**|**fprintf_s**|**fwprintf_s**| -|**_ftprintf_s_l**|**_fprintf_s_l**|**_fprintf_s_l**|**_fwprintf_s_l**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ftprintf_s` | `fprintf_s` | `fprintf_s` | `fwprintf_s` | +| `_ftprintf_s_l` | `_fprintf_s_l` | `_fprintf_s_l` | `_fwprintf_s_l` | -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fprintf_s**, **_fprintf_s_l**|\| -|**fwprintf_s**, **_fwprintf_s_l**|\ or \| +| Function | Required header | +|---|---| +| **`fprintf_s`**, **`_fprintf_s_l`** | `` | +| **`fwprintf_s`**, **`_fwprintf_s_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -130,7 +133,7 @@ this is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) diff --git a/docs/c-runtime-library/reference/fputc-fputwc.md b/docs/c-runtime-library/reference/fputc-fputwc.md index 2cedd2bdb8..387ed71efe 100644 --- a/docs/c-runtime-library/reference/fputc-fputwc.md +++ b/docs/c-runtime-library/reference/fputc-fputwc.md @@ -3,14 +3,14 @@ description: "Learn more about: fputc, fputwc" title: "fputc, fputwc" ms.date: "4/2/2020" api_name: ["fputc", "fputwc", "_o_fputc", "_o_fputwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fputc", "fputwc", "_fputtc"] helpviewer_keywords: ["streams, writing characters to", "fputtc function", "_fputtc function", "fputwc function", "fputc function"] ms.assetid: 5a0a593d-43f4-4fa2-a401-ec4e23de4d2f --- -# fputc, fputwc +# `fputc`, `fputwc` Writes a character to a stream. @@ -29,49 +29,49 @@ wint_t fputwc( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -Each of these functions returns the character written. For **fputc**, a return value of **EOF** indicates an error. For **fputwc**, a return value of **WEOF** indicates an error. If *stream* is **NULL**, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **EOF** and set **errno** to **EINVAL**. +Each of these functions returns the character written. For **`fputc`**, a return value of `EOF` indicates an error. For **`fputwc`**, a return value of `WEOF` indicates an error. If *`stream`* is `NULL`, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, they return `EOF` and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions writes the single character *c* to a file at the position indicated by the associated file position indicator (if defined) and advances the indicator as appropriate. In the case of **fputc** and **fputwc**, the file is associated with *stream*. If the file cannot support positioning requests or was opened in append mode, the character is appended to the end of the stream. +Each of these functions writes the single character *`c`* to a file at the position indicated by the associated file position indicator, if defined. The functions advance the indicator as appropriate. In **`fputc`** and **`fputwc`**, the file is associated with *`stream`*. If the file can't support positioning requests or was opened in append mode, the character is appended to the end of the stream. -The two functions behave identically if the stream is opened in ANSI mode. **fputc** does not currently support output into a UNICODE stream. +The two functions behave identically if the stream is opened in ANSI mode. **`fputc`** doesn't currently support output into a UNICODE stream. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. For more information, see[_fputc_nolock, _fputwc_nolock](fputc-nolock-fputwc-nolock.md). +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. For more information, see[`_fputc_nolock`, `_fputwc_nolock`](fputc-nolock-fputwc-nolock.md). Routine-specific remarks follow. -|Routine|Remarks| -|-------------|-------------| -|**fputc**|Equivalent to **putc**, but implemented only as a function, rather than as a function and a macro.| -|**fputwc**|Wide-character version of **fputc**. Writes *c* as a multibyte character or a wide character according to whether *stream* is opened in text mode or binary mode.| +| Routine | Remarks | +|---|---| +| **`fputc`** | Equivalent to `putc`, but implemented only as a function, rather than as a function and a macro. | +| **`fputwc`** | Wide-character version of `fputc`. Writes *`c`* as a multibyte character or a wide character when *`stream`* is opened in text mode or binary mode, respectively. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_fputtc**|**fputc**|**fputc**|**fputwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fputtc` | **`fputc`** | **`fputc`** | **`fputwc`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fputc**|\| -|**fputwc**|\ or \| +| Function | Required header | +|---|---| +| **`fputc`** | \ | +| **`fputwc`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**stdin**, **stdout**, and **stderr**—must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—`stdin`, `stdout`, and `stderr`—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,6 +100,6 @@ This is a test of fputc!! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md b/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md index 6443430f47..ded60efc1b 100644 --- a/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md +++ b/docs/c-runtime-library/reference/fputc-nolock-fputwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fputc_nolock, _fputwc_nolock" title: "_fputc_nolock, _fputwc_nolock" +description: "Learn more about: _fputc_nolock, _fputwc_nolock" ms.date: "4/2/2020" api_name: ["_fputwc_nolock", "_fputc_nolock", "_o__fputc_nolock", "_o__fputwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fputc_nolock", "fputwc_nolock", "fputc_nolock", "fputtc_nolock", "_fputwc_nolock", "_fputtc_nolock"] helpviewer_keywords: ["streams, writing characters to", "fputwc_nolock function", "fputtc_nolock function", "_fputc_nolock function", "fputc_nolock function", "_fputtc_nolock function", "_fputwc_nolock function"] -ms.assetid: c63eb3ad-58fa-46d0-9249-9c25f815eab9 --- -# _fputc_nolock, _fputwc_nolock +# `_fputc_nolock`, `_fputwc_nolock` -Writes a character to a stream without locking the thread. +Writes a character to a stream without locking. ## Syntax @@ -29,38 +28,38 @@ wint_t _fputwc_nolock( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -Each of these functions returns the character written. For error information, see [fputc, fputwc](fputc-fputwc.md). +Each of these functions returns the character written. For error information, see [`fputc`, `fputwc`](fputc-fputwc.md). ## Remarks -**_fputc_nolock** and **_fputwc_nolock** are identical to **fputc** and **fputwc**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_fputc_nolock`** and **`_fputwc_nolock`** are identical to `fputc` and `fputwc`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -The two functions behave identically if the stream is opened in ANSI mode. **_fputc_nolock** does not currently support output into a UNICODE stream. +The two functions behave identically if the stream is opened in ANSI mode. **`_fputc_nolock`** doesn't currently support output into a UNICODE stream. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fputtc_nolock**|**_fputc_nolock**|**_fputc_nolock**|**_fputwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fputtc_nolock` | **`_fputc_nolock`** | **`_fputc_nolock`** | **`_fputwc_nolock`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fputc_nolock**|\| -|**_fputwc_nolock**|\ or \| +| Function | Required header | +|---|---| +| **`_fputc_nolock`** | \ | +| **`_fputwc_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**stdin**, **stdout**, and **stderr**—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—`stdin`, `stdout`, and `stderr`—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -89,6 +88,6 @@ This is a test of _fputc_nolock!! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/fputchar-fputwchar.md b/docs/c-runtime-library/reference/fputchar-fputwchar.md index e0dd7818c7..2f2f418820 100644 --- a/docs/c-runtime-library/reference/fputchar-fputwchar.md +++ b/docs/c-runtime-library/reference/fputchar-fputwchar.md @@ -3,16 +3,16 @@ description: "Learn more about: _fputchar, _fputwchar" title: "_fputchar, _fputwchar" ms.date: "4/2/2020" api_name: ["_fputchar", "_fputwchar", "_o__fputchar", "_o__fputwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fputtchar", "_fputwchar", "fputwchar", "_fputtchar", "_fputchar"] helpviewer_keywords: ["fputchar function", "standard output, writing to", "_fputtchar function", "fputwchar function", "_fputwchar function", "fputtchar function", "_fputchar function"] ms.assetid: b92ff600-a924-4f2b-b0e7-3097ee31bdff --- -# _fputchar, _fputwchar +# `_fputchar`, `_fputwchar` -Writes a character to **stdout**. +Writes a character to `stdout`. ## Syntax @@ -27,35 +27,35 @@ wint_t _fputwchar( ### Parameters -*c*
+*`c`*\ Character to be written. -## Return Value +## Return value -Each of these functions returns the character written. For **_fputchar**, a return value of **EOF** indicates an error. For **_fputwchar**, a return value of **WEOF** indicates an error. If c is **NULL**, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **EOF** (or **WEOF**) and set **errno** to **EINVAL**. +Each of these functions returns the character written. For **`_fputchar`**, a return value of `EOF` indicates an error. For **`_fputwchar`**, a return value of `WEOF` indicates an error. If c is `NULL`, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_fputchar`** returns `EOF` (**`_fputwchar`** returns `WEOF`), and they set `errno` to `EINVAL`. -For more information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Both of these functions writes the single character *c* to **stdout** and advances the indicator as appropriate. **_fputchar** is equivalent to `fputc( stdout )`. It is also equivalent to **putchar**, but implemented only as a function, rather than as a function and a macro. Unlike **fputc** and **putchar**, these functions are not compatible with the ANSI standard. +Both of these functions write the single character argument *`c`* to `stdout` and advance the indicator as appropriate. **`_fputchar`** is equivalent to `fputc( stdout )`. It's also equivalent to `putchar`, but implemented only as a function, rather than as a function and a macro. Unlike `fputc` and `putchar`, these functions aren't compatible with the ANSI standard. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fputtchar**|**_fputchar**|**_fputchar**|**_fputwchar**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fputtchar` | **`_fputchar`** | **`_fputchar`** | **`_fputwchar`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fputchar**|\| -|**_fputwchar**|\ or \| +| Function | Required header | +|---|---| +| **`_fputchar`** | \ | +| **`_fputwchar`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**stdin**, **stdout**, and **stderr**—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—`stdin`, `stdout`, and `stderr`—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -84,6 +84,6 @@ This is a test of _fputchar!! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/fputchar.md b/docs/c-runtime-library/reference/fputchar.md index 62d6f77587..68cbd3534e 100644 --- a/docs/c-runtime-library/reference/fputchar.md +++ b/docs/c-runtime-library/reference/fputchar.md @@ -10,8 +10,8 @@ f1_keywords: ["fputchar"] helpviewer_keywords: ["fputchar function"] ms.assetid: d6cf3492-ace9-47a7-9f7d-3c25aa8ad526 --- -# fputchar +# `fputchar` -The Microsoft-specific function name `fputchar` is a deprecated alias for the [_fputchar](fputchar-fputwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fputchar` is a deprecated alias for the [`_fputchar`](fputchar-fputwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fputchar](fputchar-fputwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fputchar`](fputchar-fputwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fputs-fputws.md b/docs/c-runtime-library/reference/fputs-fputws.md index d0baee3b21..ea1893d90f 100644 --- a/docs/c-runtime-library/reference/fputs-fputws.md +++ b/docs/c-runtime-library/reference/fputs-fputws.md @@ -3,7 +3,7 @@ description: "Learn more about: fputs, fputws" title: "fputs, fputws" ms.date: 03/02/2021 api_name: ["fputs", "fputws", "_o_fputs", "_o_fputws"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fputs", "fputws", "_fputts"] @@ -32,17 +32,17 @@ int fputws( Output string. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. ## Return value -Each of these functions returns a nonnegative value if it is successful. On an error, **`fputs`** and **`fputws`** return **`EOF`**. If *`str`* or *`stream`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and then return **`EOF`**. +Each of these functions returns a nonnegative value if it's successful. On an error, **`fputs`** and **`fputws`** return `EOF`. If *`str`* or *`stream`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and then return `EOF`. -For more information on error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions copies *`str`* to the output *`stream`* at the current position. **`fputws`** copies the wide-character argument *`str`* to *`stream`* as a multibyte-character string or a wide-character string according to whether *`stream`* is opened in text mode or binary mode, respectively. Neither function copies the terminating null character. +Each of these functions copies *`str`* to the output *`stream`* at the current position. **`fputws`** copies the wide-character argument *`str`* to *`stream`* as a multibyte-character string or a wide-character string when *`stream`* is opened in text mode or binary mode, respectively. Neither function copies the terminating null character. The two functions behave identically if the stream is opened in ANSI mode. **`fputs`** doesn't currently support output into a UNICODE stream. @@ -50,18 +50,18 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_fputts`**|**`fputs`**|**`fputs`**|**`fputws`**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_fputts`** | **`fputs`** | **`fputs`** | **`fputws`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fputs`**|\| -|**`fputws`**|\ or \| +| Function | Required header | +|---|---| +| **`fputs`** | \ | +| **`fputws`** | \ or \ | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**`stdin`**, **`stdout`**, and **`stderr`**—must be redirected before C runtime functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**`stdin`**, **`stdout`**, and **`stderr`**—must be redirected before C runtime functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -84,7 +84,7 @@ Hello world from fputs. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`fgets`, `fgetws`](fgets-fgetws.md)\ -[`gets`, `_getws`](../../c-runtime-library/gets-getws.md)\ +[`gets`, `_getws`](../gets-getws.md)\ [`puts`, `_putws`](puts-putws.md) diff --git a/docs/c-runtime-library/reference/fread-nolock-s2.md b/docs/c-runtime-library/reference/fread-nolock-s2.md index 96f38b3647..f471494eae 100644 --- a/docs/c-runtime-library/reference/fread-nolock-s2.md +++ b/docs/c-runtime-library/reference/fread-nolock-s2.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: _fread_nolock_s" title: "_fread_nolock_s2" +description: "Learn more about: _fread_nolock_s" ms.date: "4/2/2020" api_name: ["_fread_nolock_s", "_o__fread_nolock_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fread_nolock_s", "stdio/_fread_nolock_s"] -ms.assetid: 5badb9ab-11df-4e17-8162-30bda2a4572e --- -# _fread_nolock_s +# `_fread_nolock_s` -Reads data from a stream, without locking other threads. This version of [fread_nolock](fread-nolock.md) has security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads data from a stream without locking. This version of [`fread_nolock`](fread-nolock.md) has security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -27,41 +26,41 @@ size_t _fread_nolock_s( ### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -*bufferSize*
+*`bufferSize`*\ Size of the destination buffer in bytes. -*elementSize*
+*`elementSize`*\ Size of the item to read in bytes. -*elementCount*
+*`elementCount`*\ Maximum number of items to be read. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -See [fread_s](fread-s.md). +See [`fread_s`](fread-s.md). ## Remarks -This function is a non-locking version of **fread_s**. It is identical to **fread_s** except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fread_s`. It's identical to `fread_s` except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fread_nolock_s**|C: \; C++: \ or \| +| Function | Required header | +|---|---| +| **`_fread_nolock_s`** | C: \; C++: \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fwrite](fwrite.md)
-[_read](read.md)
+[Stream I/O](../stream-i-o.md)\ +[`fwrite`](fwrite.md)\ +[`_read`](read.md) diff --git a/docs/c-runtime-library/reference/fread-nolock.md b/docs/c-runtime-library/reference/fread-nolock.md index 3f738870a2..44f32e0cac 100644 --- a/docs/c-runtime-library/reference/fread-nolock.md +++ b/docs/c-runtime-library/reference/fread-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fread_nolock" title: "_fread_nolock" +description: "Learn more about: _fread_nolock" ms.date: "4/2/2020" api_name: ["_fread_nolock", "_o__fread_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fread_nolock", "fread_nolock"] helpviewer_keywords: ["reading data [C++], from input streams", "data [C++], reading from input stream", "fread_nolock function", "_fread_nolock function", "streams [C++], reading data from"] -ms.assetid: 60e4958b-1097-46f5-a77b-94af5e7dba40 --- -# _fread_nolock +# `_fread_nolock` -Reads data from a stream, without locking other threads. +Reads data from a stream without locking. ## Syntax @@ -27,38 +26,38 @@ size_t _fread_nolock( ### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -*size*
+*`size`*\ Item size in bytes. -*count*
+*`count`*\ Maximum number of items to be read. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -See [fread](fread.md). +See [`fread`](fread.md). ## Remarks -This function is a non-locking version of **fread**. It is identical to **fread** except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fread`. It's identical to `fread` except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fread_nolock**|\| +| Function | Required header | +|---|---| +| **`_fread_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fwrite](fwrite.md)
-[_read](read.md)
+[Stream I/O](../stream-i-o.md)\ +[`fwrite`](fwrite.md)\ +[`_read`](read.md) diff --git a/docs/c-runtime-library/reference/fread-s.md b/docs/c-runtime-library/reference/fread-s.md index ef84d27bca..ef3ddb3d66 100644 --- a/docs/c-runtime-library/reference/fread-s.md +++ b/docs/c-runtime-library/reference/fread-s.md @@ -3,15 +3,14 @@ description: "Learn more about: fread_s" title: "fread_s" ms.date: "4/2/2020" api_name: ["fread_s", "_o_fread_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fread_s", "stdio/fread_s"] -ms.assetid: ce735de0-f005-435d-a8f2-6f4b80ac775e --- -# fread_s +# `fread_s` -Reads data from a stream. This version of [fread](fread.md) has security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads data from a stream. This version of [`fread`](fread.md) has security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -27,42 +26,42 @@ size_t fread_s( ### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -*bufferSize*
+*`bufferSize`*\ Size of the destination buffer in bytes. -*elementSize*
+*`elementSize`*\ Size of the item to read in bytes. -*count*
+*`count`*\ Maximum number of items to be read. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**fread_s** returns the number of (whole) items that were read into the buffer, which may be less than *count* if a read error or the end of the file is encountered before *count* is reached. Use the **feof** or **ferror** function to distinguish an error from an end-of-file condition. If *size* or *count* is 0, **fread_s** returns 0 and the buffer contents are unchanged. If *stream* or *buffer* is a null pointer, **fread_s** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns 0. +**`fread_s`** returns the number of (whole) items that were read into the buffer, which may be less than *`count`* if a read error or the end of the file is encountered before *`count`* is reached. Use the **`feof`** or **`ferror`** function to distinguish an error from an end-of-file condition. If *`size`* or *`count`* is 0, **`fread_s`** returns 0 and the buffer contents are unchanged. If *`stream`* or *`buffer`* is a null pointer, **`fread_s`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. -For more information about error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **fread_s** function reads up to *count* items of *elementSize* bytes from the input *stream* and stores them in *buffer*. The file pointer that is associated with *stream* (if there is one) is increased by the number of bytes actually read. If the given stream is opened in text mode, carriage return-line feed pairs are replaced with single line feed characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item cannot be determined. +The **`fread_s`** function reads up to *`count`* items of *`elementSize`* bytes from the input *`stream`* and stores them in *`buffer`*. The file pointer that's associated with *`stream`* (if there's one) is advanced by the number of bytes **`fread_s`** read. If the given stream is opened in text mode, carriage return-line feed pairs are replaced with single line feed characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item can't be determined. -This function locks out other threads. If you require a non-locking version, use **_fread_nolock**. +This function locks out other threads. If you require a non-locking version, use **`_fread_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fread_s**|\| +| Function | Required header | +|---|---| +| **`fread_s`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -133,6 +132,6 @@ Contents of buffer after write/read: ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fwrite](fwrite.md)
-[_read](read.md)
+[Stream I/O](../stream-i-o.md)\ +[`fwrite`](fwrite.md)\ +[`_read`](read.md) diff --git a/docs/c-runtime-library/reference/fread.md b/docs/c-runtime-library/reference/fread.md index 498a53d895..81367d2a4b 100644 --- a/docs/c-runtime-library/reference/fread.md +++ b/docs/c-runtime-library/reference/fread.md @@ -3,7 +3,7 @@ description: "Learn more about: fread" title: "fread" ms.date: "4/2/2020" api_name: ["fread", "_o_fread"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fread"] @@ -27,41 +27,41 @@ size_t fread( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for data. -*`size`*
+*`size`*\ Item size in bytes. -*`count`*
+*`count`*\ Maximum number of items to be read. -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**`fread`** returns the number of full items actually read, which may be less than *`count`* if an error occurs or if the end of the file is encountered before reaching *`count`*. Use the **`feof`** or **`ferror`** function to distinguish a read error from an end-of-file condition. If *`size`* or *`count`* is 0, **`fread`** returns 0 and the buffer contents are unchanged. If *`stream`* or *`buffer`* is a null pointer, **`fread`** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns 0. +**`fread`** returns the number of full items the function read, which may be less than *`count`* if an error occurs, or if it encounters the end of the file before reaching *`count`*. Use the **`feof`** or **`ferror`** function to distinguish a read error from an end-of-file condition. If *`size`* or *`count`* is 0, **`fread`** returns 0 and the buffer contents are unchanged. If *`stream`* or *`buffer`* is a null pointer, **`fread`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys`_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`fread`** function reads up to *`count`* items of *`size`* bytes from the input *`stream`* and stores them in *`buffer`*. The file pointer associated with *`stream`* (if there is one) is increased by the number of bytes actually read. If the given stream is opened in [text mode](../../c-runtime-library/text-and-binary-mode-file-i-o.md), Windows-style newlines are converted into Unix-style newlines. That is, carriage return-line feed (CRLF) pairs are replaced by single line feed (LF) characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item cannot be determined. +The **`fread`** function reads up to *`count`* items of *`size`* bytes from the input *`stream`* and stores them in *`buffer`*. The file pointer associated with *`stream`* (if one exists) is advanced by the number of bytes **`fread`** read. If the given stream is opened in [text mode](../text-and-binary-mode-file-i-o.md), Windows-style newlines are converted into Unix-style newlines. That is, carriage return-line feed (CRLF) pairs are replaced by single line feed (LF) characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item can't be determined. -When used on a text mode stream, if the amount of data requested (that is, *`size`* \* *`count`*) is greater than or equal to the internal **`FILE`** \* buffer size (by default this is 4096 bytes, configurable by using [`setvbuf`](../../c-runtime-library/reference/setvbuf.md)), stream data is copied directly into the user-provided buffer, and newline conversion is done in that buffer. Since the converted data may be shorter than the stream data copied into the buffer, data past *`buffer`*\[*`return_value`* \* *`size`*] (where *`return_value`* is the return value from **`fread`**) may contain unconverted data from the file. For this reason, we recommend you null-terminate character data at *`buffer`*\[*`return_value`* \* *`size`*] if the intent of the buffer is to act as a C-style string. See [`fopen`](fopen-wfopen.md) for details on the effects of text mode and binary mode. +When used on a text mode stream, if the amount of data requested (that is, *`size`* \* *`count`*) is greater than or equal to the internal `FILE` \* buffer size (by default the size is 4096 bytes, configurable by using [`setvbuf`](./setvbuf.md)), stream data is copied directly into the user-provided buffer, and newline conversion is done in that buffer. Since the converted data may be shorter than the stream data copied into the buffer, data past *`buffer`*\[*`return_value`* \* *`size`*] (where *`return_value`* is the return value from **`fread`**) may contain unconverted data from the file. For this reason, we recommend you null-terminate character data at *`buffer`*\[*`return_value`* \* *`size`*] if the intent of the buffer is to act as a C-style string. See [`fopen`](fopen-wfopen.md) for details on the effects of text mode and binary mode. This function locks out other threads. If you need a non-locking version, use **`_fread_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fread`**|``| +| Function | Required header | +|---|---| +| **`fread`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -115,8 +115,8 @@ Contents of buffer = zyxwvutsrqponmlkjihgfedcb ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Text and Binary File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md)
-[`fopen`](fopen-wfopen.md)
-[`fwrite`](fwrite.md)
-[`_read`](read.md)
+[Stream I/O](../stream-i-o.md)\ +[Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md)\ +[`fopen`](fopen-wfopen.md)\ +[`fwrite`](fwrite.md)\ +[`_read`](read.md) diff --git a/docs/c-runtime-library/reference/free-dbg.md b/docs/c-runtime-library/reference/free-dbg.md index 88e437bfa0..49f863d551 100644 --- a/docs/c-runtime-library/reference/free-dbg.md +++ b/docs/c-runtime-library/reference/free-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_free_dbg", "free_dbg"] helpviewer_keywords: ["memory blocks, deallocating", "freeing memory", "_free_dbg function", "free_dbg function"] ms.assetid: fc5e8299-616d-48a0-b979-e037117278c6 --- -# _free_dbg +# `_free_dbg` Frees a block of memory in the heap (debug version only). @@ -25,35 +25,35 @@ void _free_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the allocated memory block to be freed. -*blockType*
-Type of allocated memory block to be freed: **_CLIENT_BLOCK**, **_NORMAL_BLOCK**, or **_IGNORE_BLOCK**. +*`blockType`*\ +Type of allocated memory block to be freed: `_CLIENT_BLOCK`, `_NORMAL_BLOCK`, or `_IGNORE_BLOCK`. ## Remarks -The **_free_dbg** function is a debug version of the [free](free.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_free_dbg** is reduced to a call to **free**. Both **free** and **_free_dbg** free a memory block in the base heap, but **_free_dbg** accommodates two debugging features: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions and a block type parameter to free specific allocation types. +The **`_free_dbg`** function is a debug version of the [`free`](free.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_free_dbg`** is reduced to a call to `free`. Both `free` and **`_free_dbg`** free a memory block in the base heap, but **`_free_dbg`** accommodates two debugging features: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions and a block type parameter to free specific allocation types. -**_free_dbg** performs a validity check on all specified files and block locations before performing the free operation. The application is not expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion and issues an error report if overwriting has occurred. If the **_CRTDBG_DELAY_FREE_MEM_DF** bit field of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the **_FREE_BLOCK** block type, and kept in the heap's linked list of memory blocks. +**`_free_dbg`** performs a validity check on all specified files and block locations before performing the free operation. The application isn't expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion. It issues an error report if it detects an overwrite. If the `_CRTDBG_DELAY_FREE_MEM_DF` bit field of the [`_crtDbgFlag`](../crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the `_FREE_BLOCK` block type, and kept in the heap's linked list of memory blocks. -If an error occurs in freeing the memory, **errno** is set with information from the operating system on the nature of the failure. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between calling a standard heap function and the debug version, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_free_dbg**|\| +| Routine | Required header | +|---|---| +| **`_free_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -For a sample of how to use **_free_dbg**, see [crt_dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). +For a sample of how to use **`_free_dbg`**, see [`crt_dbg2`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg2). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/free-locale.md b/docs/c-runtime-library/reference/free-locale.md index 8b2e387653..13ccc69236 100644 --- a/docs/c-runtime-library/reference/free-locale.md +++ b/docs/c-runtime-library/reference/free-locale.md @@ -3,14 +3,14 @@ description: "Learn more about: _free_locale" title: "_free_locale" ms.date: "4/2/2020" api_name: ["_free_locale", "_o__free_locale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__free_locale", "free_locale", "_free_locale"] helpviewer_keywords: ["__free_locale function", "free_locale function", "locales, freeing", "_free_locale function"] ms.assetid: 1f08d348-ab32-4028-a145-6cbd51b49af9 --- -# _free_locale +# `_free_locale` Frees a locale object. @@ -24,26 +24,26 @@ void _free_locale( ### Parameters -*locale*
+*`locale`*\ Locale object to free. ## Remarks -The **_free_locale** function is used to free the locale object obtained from a call to **_get_current_locale** or **_create_locale**. +The **`_free_locale`** function is used to free the locale object obtained from a call to `_get_current_locale` or `_create_locale`. -The previous name of this function, **__free_locale** (with two leading underscores) has been deprecated. +The previous name of this function, **`__free_locale`** (with two leading underscores) has been deprecated. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|**Routine**|Required header| -|---------------|---------------------| -|**_free_locale**|\| +| `Routine` | Required header | +|---|---| +| **`_free_locale`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_current_locale](get-current-locale.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
+[`_get_current_locale`](get-current-locale.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md) diff --git a/docs/c-runtime-library/reference/free.md b/docs/c-runtime-library/reference/free.md index a9c4409462..0e9f412d04 100644 --- a/docs/c-runtime-library/reference/free.md +++ b/docs/c-runtime-library/reference/free.md @@ -3,14 +3,13 @@ description: "Learn more about: free" title: "free" ms.date: "4/2/2020" api_name: ["free", "_o_free"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["free"] helpviewer_keywords: ["memory blocks, deallocating", "free function"] -ms.assetid: 74ded9cf-1863-432e-9306-327a42080bb8 --- -# free +# `free` Deallocates or frees a memory block. @@ -24,44 +23,44 @@ void free( ### Parameters -*memblock*
+*`memblock`*\ Previously allocated memory block to be freed. ## Remarks -The **free** function deallocates a memory block (*memblock*) that was previously allocated by a call to **calloc**, **malloc**, or **realloc**. The number of freed bytes is equivalent to the number of bytes requested when the block was allocated (or reallocated, in the case of **realloc**). If *memblock* is **NULL**, the pointer is ignored and **free** immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that was not allocated by **calloc**, **malloc**, or **realloc**) may affect subsequent allocation requests and cause errors. +The **`free`** function deallocates a memory block (*`memblock`*) that was previously allocated by a call to **`calloc`**, **`malloc`**, or **`realloc`**. The number of freed bytes is equivalent to the number of bytes requested when the block was allocated (or reallocated, for **`realloc`**). If *`memblock`* is `NULL`, the pointer is ignored, and **`free`** immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that wasn't allocated by **`calloc`**, **`malloc`**, or **`realloc`**) may affect subsequent allocation requests and cause errors. -If an error occurs in freeing the memory, **errno** is set with information from the operating system on the nature of the failure. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -After a memory block has been freed, [_heapmin](heapmin.md) minimizes the amount of free memory on the heap by coalescing the unused regions and releasing them back to the operating system. Freed memory that is not released to the operating system is restored to the free pool and is available for allocation again. +After a memory block has been freed, [`_heapmin`](heapmin.md) minimizes the amount of free memory on the heap by coalescing the unused regions and releasing them back to the operating system. Freed memory that isn't released to the operating system is restored to the free pool and is available for allocation again. -When the application is linked with a debug version of the C run-time libraries, **free** resolves to [_free_dbg](free-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`free`** resolves to [`_free_dbg`](free-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**free** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [noalias](../../cpp/noalias.md). +**`free`** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [`noalias`](../../cpp/noalias.md). -To free memory allocated with [_malloca](malloca.md), use [_freea](freea.md). +To free memory allocated with [`_malloca`](malloca.md), use [`_freea`](freea.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**free**|\ and \| +| Function | Required header | +|---|---| +| **`free`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [malloc](malloc.md). +See the example for [`malloc`](malloc.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_alloca](alloca.md)
-[calloc](calloc.md)
-[malloc](malloc.md)
-[realloc](realloc.md)
-[_free_dbg](free-dbg.md)
-[_heapmin](heapmin.md)
-[_freea](freea.md)
+[Memory allocation](../memory-allocation.md)\ +[`_alloca`](alloca.md)\ +[`calloc`](calloc.md)\ +[`malloc`](malloc.md)\ +[`realloc`](realloc.md)\ +[`_free_dbg`](free-dbg.md)\ +[`_heapmin`](heapmin.md)\ +[`_freea`](freea.md) diff --git a/docs/c-runtime-library/reference/freea.md b/docs/c-runtime-library/reference/freea.md index 8a52c19067..1e0aab4f41 100644 --- a/docs/c-runtime-library/reference/freea.md +++ b/docs/c-runtime-library/reference/freea.md @@ -10,7 +10,7 @@ f1_keywords: ["freea", "_freea"] helpviewer_keywords: ["_freea function", "freea function", "memory deallocation"] ms.assetid: dcd30584-dd9d-443b-8c4c-13237a1cecac --- -# _freea +# `_freea` Deallocates or frees a memory block. @@ -24,46 +24,46 @@ void _freea( ### Parameters -*memblock*
+*`memblock`*\ Previously allocated memory block to be freed. -## Return Value +## Return value None. ## Remarks -The **_freea** function deallocates a memory block (*memblock*) that was previously allocated by a call to [_malloca](malloca.md). **_freea** checks to see if the memory was allocated on the heap or the stack. If it was allocated on the stack, **_freea** does nothing. If it was allocated on the heap, the number of freed bytes is equivalent to the number of bytes requested when the block was allocated. If *memblock* is **NULL**, the pointer is ignored and **_freea** immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that was not allocated by **_malloca**) might affect subsequent allocation requests and cause errors. +The **`_freea`** function deallocates a memory block (*`memblock`*) that was previously allocated by a call to [`_malloca`](malloca.md). **`_freea`** checks to see if the memory was allocated on the heap or the stack. If it was allocated on the stack, **`_freea`** does nothing. If it was allocated on the heap, the number of freed bytes is equivalent to the number of bytes requested when the block was allocated. If *`memblock`* is `NULL`, the pointer is ignored, and **`_freea`** immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that wasn't allocated by `_malloca`) might affect subsequent allocation requests and cause errors. -**_freea** calls **free** internally if it finds that the memory is allocated on the heap. Whether the memory is on the heap or the stack is determined by a marker placed in memory at the address immediately preceding the allocated memory. +**`_freea`** calls `free` internally if it finds that the memory is allocated on the heap. Whether the memory is on the heap or the stack is determined by a marker placed in memory at the address immediately preceding the allocated memory. -If an error occurs in freeing the memory, **errno** is set with information from the operating system on the nature of the failure. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -After a memory block has been freed, [_heapmin](heapmin.md) minimizes the amount of free memory on the heap by coalescing the unused regions and releasing them back to the operating system. Freed memory that is not released to the operating system is restored to the free pool and is available for allocation again. +After a memory block has been freed, [`_heapmin`](heapmin.md) minimizes the amount of free memory on the heap by coalescing the unused regions and releasing them back to the operating system. Freed memory that isn't released to the operating system is restored to the free pool and is available for allocation again. -A call to **_freea** must accompany all calls to **_malloca**. It is also an error to call **_freea** twice on the same memory. When the application is linked with a debug version of the C run-time libraries, particularly with [_malloc_dbg](malloc-dbg.md) features enabled by defining **_CRTDBG_MAP_ALLOC**, it is easier to find missing or duplicated calls to **_freea**. For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +A call to **`_freea`** must accompany all calls to `_malloca`. It's also an error to call **`_freea`** twice on the same memory. When the application is linked with a debug version of the C run-time libraries, particularly with [`_malloc_dbg`](malloc-dbg.md) features enabled by defining `_CRTDBG_MAP_ALLOC`, it's easier to find missing or duplicated calls to **`_freea`**. For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**_freea** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [noalias](../../cpp/noalias.md). +**`_freea`** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [`noalias`](../../cpp/noalias.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_freea**|\ and \| +| Function | Required header | +|---|---| +| **`_freea`** | \ and \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_malloca](malloca.md). +See the example for [`_malloca`](malloca.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_malloca](malloca.md)
-[calloc](calloc.md)
-[malloc](malloc.md)
-[_malloc_dbg](malloc-dbg.md)
-[realloc](realloc.md)
-[_free_dbg](free-dbg.md)
-[_heapmin](heapmin.md)
+[Memory allocation](../memory-allocation.md)\ +[`_malloca`](malloca.md)\ +[`calloc`](calloc.md)\ +[`malloc`](malloc.md)\ +[`_malloc_dbg`](malloc-dbg.md)\ +[`realloc`](realloc.md)\ +[`_free_dbg`](free-dbg.md)\ +[`_heapmin`](heapmin.md) diff --git a/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md b/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md index 25a08e8ae8..0c87ae5621 100644 --- a/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md +++ b/docs/c-runtime-library/reference/freopen-s-wfreopen-s.md @@ -3,7 +3,7 @@ description: "Learn more about: freopen_s, _wfreopen_s" title: "freopen_s, _wfreopen_s" ms.date: "2/23/2021" api_name: ["_wfreopen_s", "freopen_s", "_o__wfreopen_s", "_o_freopen_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["freopen_s", "_tfreopen_s", "_wfreopen_s"] @@ -13,7 +13,7 @@ helpviewer_keywords: ["_tfreopen_s function", "_wfreopen_s function", "file poin Closes the file currently associated with `oldStream` and reassigns `stream` to the file specified by `fileName`. -These versions of [`freopen, _wfreopen`](freopen-wfreopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +These versions of [`freopen`, `_wfreopen`](freopen-wfreopen.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -49,31 +49,31 @@ The stream to reopen. It's flushed and any files associated with it are closed. ## Return value -Zero on success; otherwise an error code. If an error occurs, the original file is closed and **`NULL`** is written to *`stream`* unless *`stream`* is also **`NULL`** +Zero on success; otherwise an error code. If an error occurs, the original file is closed, and `NULL` is written to *`stream`* unless *`stream`* is also `NULL` -For more information about error codes, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`freopen_s`** function is typically used to attach the pre-opened streams associated with `stdin`, `stdout` and `stderr` to another file. -The **`freopen_s`** function closes the file currently associated with *`stream`* and reassigns *`stream`* to the file specified by *path*. **`_wfreopen_s`** is a wide-character version of **`freopen_s`**; the *path* and *`mode`* arguments to **`_wfreopen_s`** are wide-character strings. **`_wfreopen_s`** and **`freopen_s`** behave identically otherwise. +The **`freopen_s`** function closes the file currently associated with *`stream`* and reassigns *`stream`* to the file specified by *`path`*. **`_wfreopen_s`** is a wide-character version of **`freopen_s`**; the *`path`* and *`mode`* arguments to **`_wfreopen_s`** are wide-character strings. **`_wfreopen_s`** and **`freopen_s`** behave identically otherwise. -If any of *pFile*, *path*, *`mode`*, or *`stream`* are **`NULL`**, or if *path* is an empty string, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +If any of *`pFile`*, *`path`*, *`mode`*, or *`stream`* are `NULL`, or if *`path`* is an empty string, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|_`UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tfreopen_s`**|**`freopen_s`**|**`freopen_s`**|**`_wfreopen_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tfreopen_s`** | **`freopen_s`** | **`freopen_s`** | **`_wfreopen_s`** | **`freopen_s`** is typically used to redirect the pre-opened files **`stdin`**, **`stdout`**, and **`stderr`** to files specified by the user. The new file associated with *`stream`* is opened with *`mode`*, which is a character string specifying the type of access requested for the file, as follows: -|*`mode`*|Access| -|-|-| -| **`"r"`** | Opens for reading. If the file doesn't exist or cannot be found, the **`freopen_s`** call fails. | +| *`mode`* | Access | +|---|---| +| **`"r"`** | Opens for reading. If the file doesn't exist or can't be found, the **`freopen_s`** call fails. | | **`"w"`** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | | **`"a"`** | Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Creates the file if it doesn't exist. | | **`"r+"`** | Opens for both reading and writing. The file must exist. | @@ -82,33 +82,33 @@ By default, this function's global state is scoped to the application. To change Use the **`"w"`** and **`"w+"`** types with care, as they can destroy existing files. Starting in C11, you can append **`"x"`** to **`"w"`** or **`"w+"`** to cause the function to fail if the file exists, instead of overwriting it. -When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations take place at the end of the file. Although the file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), the file pointer is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten. +When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations take place at the end of the file. Although the file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), the file pointer is always moved back to the end of the file before any write operation is carried out. Thus, existing data can't be overwritten. The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS TYPE command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. The current position can be specified for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if you want. In addition to the above values, one of the following characters may be included in the *`mode`* string to specify the translation mode for new lines. -|*`mode`* modifier|Translation mode| -|-|-| +| *`mode`* modifier | Translation mode | +|---|---| | **`t`** | Open in text (translated) mode. | | **`b`** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | -In text (translated) mode, carriage return-line feed (CR-LF) combinations are translated into single line feed (LF) characters on input; LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or for writing and reading with **`"a+"`**, the run-time library checks for a CTRL+Z at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. Don't use the **`t`** option when you want ANSI portability because it's a Microsoft extension. +In text (translated) mode, carriage return-line feed (CR-LF) combinations are translated into single line feed (LF) characters on input; LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or for writing and reading with **`"a+"`**, the run-time library checks for a CTRL+Z at the end of the file and removes it, if possible. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. Don't use the **`t`** option when you want ANSI portability because it's a Microsoft extension. -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -For a discussion of text and binary modes, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +For a discussion of text and binary modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`freopen_s`**|``| -|**`_wfreopen_s`**|`` or ``| +| Function | Required header | +|---|---| +| **`freopen_s`** | `` | +| **`_wfreopen_s`** | `` or `` | The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -148,11 +148,11 @@ This will go to the file 'freopen.out' ## See also -[`Stream I/O`](../../c-runtime-library/stream-i-o.md)\ -[`freopen, _wfreopen`](freopen-wfreopen.md)\ -[`fclose, _fcloseall`](fclose-fcloseall.md)\ -[`_fdopen, _wfdopen`](fdopen-wfdopen.md)\ +[`Stream I/O`](../stream-i-o.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`_fileno`](fileno.md)\ -[`fopen, _wfopen`](fopen-wfopen.md)\ -[`_open, _wopen`](open-wopen.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_open`, `_wopen`](open-wopen.md)\ [`_setmode`](setmode.md) diff --git a/docs/c-runtime-library/reference/freopen-wfreopen.md b/docs/c-runtime-library/reference/freopen-wfreopen.md index 0ee80f3aaa..79b74adb3f 100644 --- a/docs/c-runtime-library/reference/freopen-wfreopen.md +++ b/docs/c-runtime-library/reference/freopen-wfreopen.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: freopen, _wfreopen" title: "freopen, _wfreopen" +description: "Learn more about: freopen, _wfreopen" ms.date: "2/23/2021" api_name: ["freopen", "_wfreopen", "_o__wfreopen", "_o_freopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wfreopen", "_tfreopen", "freopen"] @@ -11,7 +11,7 @@ helpviewer_keywords: ["_wfreopen function", "file pointers [C++], reassigning", --- # `freopen`, `_wfreopen` -Reassigns a file pointer. More secure versions of these functions are available; see [`freopen_s, _wfreopen_s`](freopen-s-wfreopen-s.md). +Reassigns a file pointer. More secure versions of the functions are available; see [`freopen_s`, `_wfreopen_s`](freopen-s-wfreopen-s.md). ## Syntax @@ -37,23 +37,23 @@ Path of new file. Type of access permitted. *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. -## Return Value +## Return value -Each of these functions returns a pointer to the newly opened file. If an error occurs, the original file is closed and the function returns a **`NULL`** pointer value. If *`path`*, *`mode`*, or *`stream`* is a null pointer, or if *filename* is an empty string, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`NULL`**. +Each of these functions returns a pointer to the newly opened file. If an error occurs, the original file is closed, and the function returns a `NULL` pointer value. If *`path`*, *`mode`*, or *`stream`* is a null pointer, or if *`filename`* is an empty string, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `NULL`. -For more information on these, and other, error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -More secure versions of these functions exist, see [`freopen_s, _wfreopen_s`](freopen-s-wfreopen-s.md). +More secure versions of these functions exist, see [`freopen_s`, `_wfreopen_s`](freopen-s-wfreopen-s.md). The **`freopen`** function closes the file currently associated with *`stream`* and reassigns *`stream`* to the file specified by *`path`*. **`_wfreopen`** is a wide-character version of **`_freopen`**; the *`path`* and *`mode`* arguments to **`_wfreopen`** are wide-character strings. **`_wfreopen`** and **`_freopen`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings | `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |--|--|--|--| @@ -61,9 +61,9 @@ By default, this function's global state is scoped to the application. To change **`freopen`** is typically used to redirect the pre-opened files **`stdin`**, **`stdout`**, and **`stderr`** to files specified by the user. The new file associated with *`stream`* is opened with *`mode`*, which is a character string specifying the type of access requested for the file, as follows: -|*`mode`*|Access| -|-|-| -| **`"r"`** | Opens for reading. If the file doesn't exist or cannot be found, the **`freopen`** call fails. | +| *`mode`* | Access | +|---|---| +| **`"r"`** | Opens for reading. If the file doesn't exist or can't be found, the **`freopen`** call fails. | | **`"w"`** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | | **`"a"`** | Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Creates the file if it doesn't exist. | | **`"r+"`** | Opens for both reading and writing. The file must exist. | @@ -72,31 +72,31 @@ By default, this function's global state is scoped to the application. To change Use the **`"w"`** and **`"w+"`** types with care, as they can destroy existing files. Starting in C11, you can append **`"x"`** to **`"w"`** or **`"w+"`** to cause the function fail if the file exists, instead of overwriting it. -When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations take place at the end of the file. Although the file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), the file pointer is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten. +When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations take place at the end of the file. Although the file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), the file pointer is always moved back to the end of the file before any write operation is carried out. Thus, existing data can't be overwritten. The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS TYPE command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. The current position can be specified for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if you want. In addition to the above values, one of the following characters may be included in the *`mode`* string to specify the translation mode for new lines. -|*`mode`* modifier|Translation mode| -|-|-| +| *`mode`* modifier | Translation mode | +|---|---| | **`t`** | Open in text (translated) mode. | | **`b`** | Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. | -In text (translated) mode, carriage return-line feed (CR-LF) combinations are translated into single line feed (LF) characters on input; LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or for writing and reading with **`"a+"`**, the run-time library checks for a CTRL+Z at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and [ftell](ftell-ftelli64.md) to move within a file may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. Don't use the **`t`** option if you want ANSI portability because it's a Microsoft extension. +In text (translated) mode, carriage return-line feed (CR-LF) combinations are translated into single line feed (LF) characters on input; LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or for writing and reading with **`"a+"`**, the run-time library checks for a CTRL+Z at the end of the file and removes it, if possible. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. Don't use the **`t`** option if you want ANSI portability because it's a Microsoft extension. -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -For a discussion of text and binary modes, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +For a discussion of text and binary modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`freopen`**|``| -|**`_wfreopen`**|`` or ``| +| Function | Required header | +|---|---| +| **`freopen`** | `` | +| **`_wfreopen`** | `` or `` | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -135,10 +135,10 @@ This will go to the file 'freopen.out' ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[`fclose, _fcloseall`](fclose-fcloseall.md)\ -[`_fdopen, _wfdopen`](fdopen-wfdopen.md)\ +[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`_fileno`](fileno.md)\ -[`fopen, _wfopen`](fopen-wfopen.md)\ -[`_open, _wopen`](open-wopen.md)\ -[`_setmode`](setmode.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_setmode`](setmode.md) diff --git a/docs/c-runtime-library/reference/frexp.md b/docs/c-runtime-library/reference/frexp.md index 8d3294297d..fa601e5e41 100644 --- a/docs/c-runtime-library/reference/frexp.md +++ b/docs/c-runtime-library/reference/frexp.md @@ -3,14 +3,14 @@ title: "frexp, frexpf, frexpl" description: "API reference for frexp, frexpf, and frexpl; which gets the mantissa and exponent of a floating-point number." ms.date: "9/1/2020" api_name: ["frexp", "_o_frexp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["frexp", "_frexpl"] helpviewer_keywords: ["_frexpl function", "mantissas, floating-point variables", "frexpl function", "exponent, floating-point numbers", "frexp function", "floating-point functions, mantissa and exponent"] ms.assetid: 9b020f2e-3967-45ec-a6a8-d467a071aa55 --- -# frexp, frexpf, frexpl +# `frexp`, `frexpf`, `frexpl` Gets the mantissa and exponent of a floating-point number. @@ -45,34 +45,34 @@ long double frexp( ### Parameters -*x*\ +*`x`*\ Floating-point value. -*expptr*\ +*`expptr`*\ Pointer to stored integer exponent. -## Return Value +## Return value -**frexp** returns the mantissa. If *x* is 0, the function returns 0 for both the mantissa and the exponent. If *expptr* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns 0. +**`frexp`** returns the mantissa. If *`x`* is 0, the function returns 0 for both the mantissa and the exponent. If *`expptr`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. ## Remarks -The **frexp** function breaks down the floating-point value (*x*) into a mantissa (*m*) and an exponent (*n*), such that the absolute value of *m* is greater than or equal to 0.5 and less than 1.0, and *x* = *m* * 2*n*. The integer exponent *n* is stored at the location pointed to by *expptr*. +The **`frexp`** function breaks down the floating-point value (*`x`*) into a mantissa (`m`) and an exponent (`n`), such that the absolute value of `m` is greater than or equal to 0.5 and less than 1.0, and *`x`* = `m` * 2`n`. The integer exponent `n` is stored at the location pointed to by *`expptr`*. -C++ allows overloading, so you can call overloads of **frexp**. In a C program, unless you're using the \ macro to call this function, **frexp** always takes a **`double`** and an **`int`** pointer and returns a **`double`**. +C++ allows overloading, so you can call overloads of **`frexp`**. In a C program, unless you're using the \ macro to call this function, **`frexp`** always takes a **`double`** and an **`int`** pointer and returns a **`double`**. -If you use the \ `frexp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `frexp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**frexp**, **frexpf**, **frexpl**|\| -|**frexp** macro | \ | +| Function | Required header | +|---|---| +| **`frexp`**, **`frexpf`**, **`frexpl`** | \ | +| **`frexp`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -101,6 +101,6 @@ frexp( 16.400000, &n ) = 0.512500, n = 5 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ldexp](ldexp.md)
-[modf, modff, modfl](modf-modff-modfl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ldexp`](ldexp.md)\ +[`modf`, `modff`, `modfl`](modf-modff-modfl.md) diff --git a/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md b/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md index bd20fa5da0..29f4769612 100644 --- a/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md +++ b/docs/c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fscanf", "fwscanf", "_ftscanf_l", "_fwscanf_l", "_ftscanf", "_fscanf_l"] helpviewer_keywords: ["fscanf function", "fwscanf function", "formatted data [C++], reading from streams", "ftscanf_l function", "_ftscanf_l function", "_fwscanf_l function", "data [CRT], reading from streams", "_fscanf_l function", "ftscanf function", "fscanf_l function", "streams [C++], reading formatted data from", "_ftscanf function", "fwscanf_l function"] -ms.assetid: 9004e978-6c5f-4bb2-98fd-51e5948933f2 --- -# fscanf, _fscanf_l, fwscanf, _fwscanf_l +# `fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l` -Read formatted data from a stream. More secure versions of these functions are available; see [fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md). +Read formatted data from a stream. More secure versions of these functions are available; see [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md). ## Syntax @@ -43,49 +42,49 @@ int _fwscanf_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **fscanf** and **fwscanf**. +Each of these functions returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`fscanf`** and **`fwscanf`**. -These functions validate their parameters. If *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **fscanf** function reads data from the current position of *stream* into the locations given by *argument* (if any). Each *argument* must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf**; see [scanf](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *format*. +The **`fscanf`** function reads data from the current position of *`stream`* into the locations given by *`argument`* (if any). Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for **`scanf`**; see [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *`format`*. -**fwscanf** is a wide-character version of **fscanf**; the format argument to **fwscanf** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **fscanf** doesn't currently support input from a UNICODE stream. +**`fwscanf`** is a wide-character version of **`fscanf`**; the format argument to **`fwscanf`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fscanf`** doesn't currently support input from a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ftscanf**|**fscanf**|**fscanf**|**fwscanf**| -|**_ftscanf_l**|**_fscanf_l**|**_fscanf_l**|**_fwscanf_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_ftscanf`** | **`fscanf`** | **`fscanf`** | **`fwscanf`** | +| **`_ftscanf_l`** | **`_fscanf_l`** | **`_fscanf_l`** | **`_fwscanf_l`** | -For more information, see [Format Specification Fields - scanf functions and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fscanf**, **_fscanf_l**|\| -|**fwscanf**, **_fwscanf_l**|\ or \| +| Function | Required header | +|---|---| +| **`fscanf`**, **`_fscanf_l`** | `` | +| **`fwscanf`**, **`_fwscanf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -148,9 +147,9 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) diff --git a/docs/c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md b/docs/c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md index 4fd8b91428..79b64e9b00 100644 --- a/docs/c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md +++ b/docs/c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md @@ -12,7 +12,7 @@ ms.assetid: b6e88194-714b-4322-be82-1cc0b343fe01 --- # `fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l` -Reads formatted data from a stream. These versions of [`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a stream. These versions of [`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -43,50 +43,50 @@ int _fwscanf_s_l( ### Parameters -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -*`format`*
+*`format`*\ Format-control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **`EOF`** for **`fscanf_s`** and **`fwscanf_s`**. +Each of these functions returns the number of fields that it successfully converts and assigns. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`fscanf_s`** and **`fwscanf_s`**. -These functions validate their parameters. If *`stream`* is an invalid file pointer, or *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EOF`** and set **`errno`** to **`EINVAL`**. +These functions validate their parameters. If *`stream`* is an invalid file pointer, or *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **`fscanf_s`** function reads data from the current position of *`stream`* into the locations that are given by *`argument`* (if any). Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *format* argument for **`scanf_s`**; see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md) for a description of *format*. **`fwscanf_s`** is a wide-character version of **`fscanf_s`**; the format argument to **`fwscanf_s`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fscanf_s`** doesn't currently support input from a UNICODE stream. +The **`fscanf_s`** function reads data from the current position of *`stream`* into the locations that are given by *`argument`* (if any). Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for **`scanf_s`**; see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md) for a description of *`format`*. **`fwscanf_s`** is a wide-character version of **`fscanf_s`**; the format argument to **`fwscanf_s`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`fscanf_s`** doesn't currently support input from a UNICODE stream. -The main difference between the more secure functions (that have the **`_s`** suffix) and the other versions is that the more secure functions require the size in characters of each **`c`**, **`C`**, **`s`**, **`S`**, and **`[`** type field to be passed as an argument immediately following the variable. For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` Width Specification](../../c-runtime-library/scanf-width-specification.md). +The main difference between the more secure functions (that have the **`_s`** suffix) and the other versions is that the more secure functions require the size in characters of each **`c`**, **`C`**, **`s`**, **`S`**, and **`[`** type field to be passed as an argument immediately following the variable. For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` Width Specification](../scanf-width-specification.md). > [!NOTE] > The size parameter is of type **`unsigned`**, not **`size_t`**. The versions of these functions that have the **`_l`** suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_ftscanf_s`**|**`fscanf_s`**|**`fscanf_s`**|**`fwscanf_s`**| -|**`_ftscanf_s_l`**|**`_fscanf_s_l`**|**`_fscanf_s_l`**|**`_fwscanf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_ftscanf_s`** | **`fscanf_s`** | **`fscanf_s`** | **`fwscanf_s`** | +| **`_ftscanf_s_l`** | **`_fscanf_s_l`** | **`_fscanf_s_l`** | **`_fwscanf_s_l`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fscanf_s`**, **`_fscanf_s_l`**|``| -|**`fwscanf_s`**, **`_fwscanf_s_l`**|`` or ``| +| Function | Required header | +|---|---| +| **`fscanf_s`**, **`_fscanf_s_l`** | `` | +| **`fwscanf_s`**, **`_fwscanf_s_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -145,9 +145,9 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)
-[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md) diff --git a/docs/c-runtime-library/reference/fseek-fseeki64.md b/docs/c-runtime-library/reference/fseek-fseeki64.md index ad5fa9b59f..89db45de4c 100644 --- a/docs/c-runtime-library/reference/fseek-fseeki64.md +++ b/docs/c-runtime-library/reference/fseek-fseeki64.md @@ -3,7 +3,7 @@ description: "Learn more about: fseek, _fseeki64" title: "fseek, _fseeki64" ms.date: "4/2/2020" api_name: ["_fseeki64", "fseek", "_o__fseeki64", "_o_fseek"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fseek", "_fseeki64"] @@ -31,28 +31,28 @@ int _fseeki64( ### Parameters -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -*`offset`*
+*`offset`*\ Number of bytes from *`origin`*. -*`origin`*
+*`origin`*\ Initial position. -## Return Value +## Return value -If successful, **`fseek`** and **`_fseeki64`** returns 0. Otherwise, it returns a nonzero value. On devices incapable of seeking, the return value is undefined. If *`stream`* is a null pointer, or if *`origin`* is not one of allowed values described below, **`fseek`** and **`_fseeki64`** invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. +If successful, **`fseek`** and **`_fseeki64`** returns 0. Otherwise, it returns a nonzero value. On devices incapable of seeking, the return value is undefined. If *`stream`* is a null pointer, or if *`origin`* isn't one of allowed values described below, **`fseek`** and **`_fseeki64`** invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. ## Remarks The **`fseek`** and **`_fseeki64`** functions moves the file pointer (if any) associated with *`stream`* to a new location that is *`offset`* bytes from *`origin`*. The next operation on the stream takes place at the new location. On a stream open for update, the next operation can be either a read or a write. The argument *`origin`* must be one of the following constants, defined in `STDIO.H`: -|origin value|Meaning| -|-|-| -| **`SEEK_CUR`** | Current position of file pointer. | -| **`SEEK_END`** | End of file. | -| **`SEEK_SET`** | Beginning of file. | +| origin value | Meaning | +|---|---| +| `SEEK_CUR` | Current position of file pointer. | +| `SEEK_END` | End of file. | +| `SEEK_SET` | Beginning of file. | You can use **`fseek`** and **`_fseeki64`** to reposition the pointer anywhere in a file. The pointer can also be positioned beyond the end of the file. **`fseek`** and **`_fseeki64`** clears the end-of-file indicator and negates the effect of any prior [`ungetc`](ungetc-ungetwc.md) calls against *`stream`*. @@ -64,22 +64,22 @@ For streams opened in text mode, **`fseek`** and **`_fseeki64`** have limited us - Seeking from the beginning of the file with an offset value returned from a call to [`ftell`](ftell-ftelli64.md) when using **`fseek`** or [`_ftelli64`](ftell-ftelli64.md) when using **`_fseeki64`**. -Also in text mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing, [`fopen`](fopen-wfopen.md) and all related routines check for a CTRL+Z at the end of the file and remove it if possible. This is done because using the combination of **`fseek`** and [`ftell`](ftell-ftelli64.md) or **`_fseeki64`** and [`_ftelli64`](ftell-ftelli64.md), to move within a file that ends with a CTRL+Z may cause **`fseek`** or **`_fseeki64`** to behave improperly near the end of the file. +Also in text mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing, [`fopen`](fopen-wfopen.md) and all related routines check for a CTRL+Z at the end of the file and remove it if possible. It's removed because using the combination of **`fseek`** and [`ftell`](ftell-ftelli64.md) or **`_fseeki64`** and [`_ftelli64`](ftell-ftelli64.md), to move within a file that ends with a CTRL+Z may cause **`fseek`** or **`_fseeki64`** to behave improperly near the end of the file. -When the CRT opens a file that begins with a Byte Order Mark (BOM), the file pointer is positioned after the BOM (that is, at the start of the file's actual content). If you have to **`fseek`** to the beginning of the file, use [`ftell`](ftell-ftelli64.md) to get the initial position and **`fseek`** to it rather than to position 0. +When the CRT opens a file that begins with a Byte Order Mark (BOM), the file pointer is positioned after the BOM. (That is, it's positioned at the start of the file's actual content). If you have to **`fseek`** to the beginning of the file, use [`ftell`](ftell-ftelli64.md) to get the initial position, and then **`fseek`** to that position rather than to position 0. This function locks out other threads during execution and is therefore thread-safe. For a non-locking version, see [`_fseek_nolock`, `_fseeki64_nolock`](fseek-nolock-fseeki64-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fseek`**|``| -|**`_fseeki64`**|``| +| Function | Required header | +|---|---| +| **`fseek`** | `` | +| **`_fseeki64`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -123,8 +123,8 @@ This is the file 'fseek.out'. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`ftell`, `_ftelli64`](ftell-ftelli64.md)
-[`_lseek`, `_lseeki64`](lseek-lseeki64.md)
-[`rewind`](rewind.md)
+[Stream I/O](../stream-i-o.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`ftell`, `_ftelli64`](ftell-ftelli64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md)\ +[`rewind`](rewind.md) diff --git a/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md b/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md index 57c97f572a..9df36b8acd 100644 --- a/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md +++ b/docs/c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fseek_nolock, _fseeki64_nolock" title: "_fseek_nolock, _fseeki64_nolock" +description: "Learn more about: _fseek_nolock, _fseeki64_nolock" ms.date: "4/2/2020" api_name: ["_fseek_nolock", "_fseeki64_nolock", "_o__fseek_nolock", "_o__fseeki64_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fseek_nolock", "_fseeki64_nolock", "fseek_nolock", "fseeki64_nolock"] helpviewer_keywords: ["_fseek_nolock function", "fseeki64_nolock function", "file pointers [C++], moving", "fseek_nolock function", "_fseeki64_nolock function", "seek file pointers"] -ms.assetid: 2dd4022e-b715-462b-b935-837561605a02 --- -# _fseek_nolock, _fseeki64_nolock +# `_fseek_nolock`, `_fseeki64_nolock` -Moves the file pointer to a specified location. +Moves the file pointer to a specified location without locking. ## Syntax @@ -31,36 +30,36 @@ int _fseeki64_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -*offset*
-Number of bytes from *origin*. +*`offset`*\ +Number of bytes from *`origin`*. -*origin*
+*`origin`*\ Initial position. -## Return Value +## Return value -Same as [fseek](fseek-fseeki64.md) and [_fseeki64](fseek-fseeki64.md), respectively. +Same as [`fseek`](fseek-fseeki64.md) and [`_fseeki64`](fseek-fseeki64.md), respectively. ## Remarks -These functions are the non-locking versions of [fseek](fseek-fseeki64.md) and [_fseeki64](fseek-fseeki64.md), respectively. These are identical to [fseek](fseek-fseeki64.md) and [_fseeki64](fseek-fseeki64.md) except that they are not protected from interference by other threads. These functions might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +These functions are the non-locking versions of [`fseek`](fseek-fseeki64.md) and [`_fseeki64`](fseek-fseeki64.md), respectively. These functions are identical to [`fseek`](fseek-fseeki64.md) and [`_fseeki64`](fseek-fseeki64.md), except that they aren't protected from interference by other threads. These functions might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fseek_nolock**, **_fseeki64_nolock**|\| +| Function | Required header | +|---|---| +| **`_fseek_nolock`**, **`_fseeki64_nolock`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[ftell, _ftelli64](ftell-ftelli64.md)
-[_lseek, _lseeki64](lseek-lseeki64.md)
-[rewind](rewind.md)
+[Stream I/O](../stream-i-o.md)\ +[`ftell`, `_ftelli64`](ftell-ftelli64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md)\ +[`rewind`](rewind.md) diff --git a/docs/c-runtime-library/reference/fsetpos.md b/docs/c-runtime-library/reference/fsetpos.md index 2ad147125d..449e44e9cc 100644 --- a/docs/c-runtime-library/reference/fsetpos.md +++ b/docs/c-runtime-library/reference/fsetpos.md @@ -3,14 +3,14 @@ description: "Learn more about: fsetpos" title: "fsetpos" ms.date: "4/2/2020" api_name: ["fsetpos", "_o_fsetpos"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fsetpos"] helpviewer_keywords: ["streams, setting position indicators", "fsetpos function"] ms.assetid: 6d19ff48-1a2b-47b3-9f23-ed0a47b5a46e --- -# fsetpos +# `fsetpos` Sets the stream-position indicator. @@ -25,37 +25,37 @@ int fsetpos( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*pos*
+*`pos`*\ Position-indicator storage. -## Return Value +## Return value -If successful, **fsetpos** returns 0. On failure, the function returns a nonzero value and sets **errno** to one of the following manifest constants (defined in ERRNO.H): **EBADF**, which means the file is not accessible or the object that *stream* points to is not a valid file structure; or **EINVAL**, which means an invalid value for *stream* or *pos* was passed. If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If successful, **`fsetpos`** returns 0. On failure, the function returns a nonzero value and sets `errno` to one of the following manifest constants (defined in ERRNO.H): `EBADF`, which means the file isn't accessible or the object that *`stream`* points to isn't a valid file structure; or `EINVAL`, which means an invalid value for *`stream`* or *`pos`* was passed. If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **fsetpos** function sets the file-position indicator for *stream* to the value of *pos*, which is obtained in a prior call to **fgetpos** against *stream*. The function clears the end-of-file indicator and undoes any effects of [ungetc](ungetc-ungetwc.md) on *stream*. After calling **fsetpos**, the next operation on *stream* may be either input or output. +The **`fsetpos`** function sets the file-position indicator for *`stream`* to the value of *`pos`*, which is obtained in a prior call to `fgetpos` against *`stream`*. The function clears the end-of-file indicator and undoes any effects of [`ungetc`](ungetc-ungetwc.md) on *`stream`*. After a call to **`fsetpos`**, the next operation on *`stream`* may be either input or output. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fsetpos**|\| +| Function | Required header | +|---|---| +| **`fsetpos`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [fgetpos](fgetpos.md). +See the example for [`fgetpos`](fgetpos.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetpos](fgetpos.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetpos`](fgetpos.md) diff --git a/docs/c-runtime-library/reference/fsopen-wfsopen.md b/docs/c-runtime-library/reference/fsopen-wfsopen.md index 86a6822994..5f2c003e22 100644 --- a/docs/c-runtime-library/reference/fsopen-wfsopen.md +++ b/docs/c-runtime-library/reference/fsopen-wfsopen.md @@ -1,14 +1,13 @@ --- description: "Learn more about: _fsopen, _wfsopen" title: "_fsopen, _wfsopen" -ms.date: "4/2/2020" +ms.date: 4/27/2023 api_name: ["_wfsopen", "_fsopen", "_o__fsopen", "_o__wfsopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wfsopen", "fsopen", "tfsopen", "_tfsopen", "_wfsopen", "_fsopen"] helpviewer_keywords: ["opening files, streams", "fsopen function", "tfsopen function", "wfsopen function", "_fsopen function", "files [C++], opening", "_tfsopen function", "_wfsopen function", "file sharing [C++]"] -ms.assetid: 5e4502ab-48a9-4bee-a263-ebac8d638dec --- # `_fsopen`, `_wfsopen` @@ -31,75 +30,81 @@ FILE *_wfsopen( ### Parameters -*`filename`*
+*`filename`*\ Name of the file to open. -*`mode`*
+*`mode`*\ Type of access permitted. -*`shflag`*
+*`shflag`*\ Type of sharing allowed. -## Return Value +## Return value -Each of these functions returns a pointer to the stream. A null pointer value indicates an error. If *`filename`* or *`mode`* is **`NULL`** or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`NULL`** and set **`errno`** to **`EINVAL`**. +Each of these functions returns a pointer to the stream. A null pointer value indicates an error. If *`filename`* or *`mode`* is `NULL` or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set `errno` to `EINVAL`. -For more information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_fsopen`** function opens the file specified by *`filename`* as a stream and prepares the file for subsequent shared reading or writing, as defined by the mode and *`shflag`* arguments. **`_wfsopen`** is a wide-character version of **`_fsopen`**; the *`filename`* and *`mode`* arguments to **`_wfsopen`** are wide-character strings. **`_wfsopen`** and **`_fsopen`** behave identically otherwise. -The character string *mode* specifies the type of access requested for the file, as shown in the following table. +The character string *`mode`* specifies the type of access requested for the file, as shown in the following table. -|Term|Definition| -|----------|----------------| -|**"`r`"**|Opens for reading. If the file does not exist or cannot be found, the **`_fsopen`** call fails.| -|**"`w`"**|Opens an empty file for writing. If the given file exists, its contents are destroyed.| -|**"`a`"**|Opens for writing at the end of the file (appending); creates the file first if it does not exist.| -|**"`r+`"**|Opens for both reading and writing. (The file must exist.)| -|**"`w+`"**|Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.| -|**"`a+`"**|Opens for reading and appending; creates the file first if it does not exist.| +| Term | Definition | +|---|---| +| **"`r`"** | Opens for reading. If the file doesn't exist or can't be found, the **`_fsopen`** call fails. | +| **"`w`"** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | +| **"`a`"** | Opens for writing at the end of the file (appending); creates the file first if it doesn't exist. | +| **"`r+`"** | Opens for both reading and writing. (The file must exist.) | +| **"`w+`"** | Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. | +| **"`a+`"** | Opens for reading and appending; creates the file first if it doesn't exist. | Use the **"`w`"** and **"`w+`"** types with care, as they can destroy existing files. -When a file is opened with the **"`a`"** or **"`a+`"** access type, all write operations occur at the end of the file. The file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten. When the **"`r+`"**, **"`w+`"**, or **"`a+`"** access type is specified, both reading and writing are allowed (the file is said to be open for update). However, when switching between reading and writing, there must be an intervening [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. The current position can be specified for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if desired. In addition to the above values, one of the following characters can be included in *`mode`* to specify the translation mode for new lines, and for file management. +When a file is opened with the **"`a`"** or **"`a+`"** access type, all write operations occur at the end of the file. The file pointer can be repositioned using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out. Thus, existing data can't be overwritten. When the **"`r+`"**, **"`w+`"**, or **"`a+`"** access type is specified, both reading and writing are allowed (the file is said to be open for update). However, when switching between reading and writing, there must be an intervening [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. The current position can be specified for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if desired. In addition to the above values, one of the following characters can be included in *`mode`* to specify the translation mode for new lines, and for file management. -|Term|Definition| -|----------|----------------| -|**`t`**|Opens a file in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input and LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading/writing, **`_fsopen`** checks for a CTRL+Z at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file that ends with a CTRL+Z might cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file.| -|**`b`**|Opens a file in binary (untranslated) mode; the above translations are suppressed.| -|**`S`**|Specifies that caching is optimized for, but not restricted to, sequential access from disk.| -|**`R`**|Specifies that caching is optimized for, but not restricted to, random access from disk.| -|**`T`**|Specifies a file as temporary. If possible, it is not flushed to disk.| -|**`D`**|Specifies a file as temporary. It is deleted when the last file pointer is closed.| +| Term | Definition | +|---|---| +| **`t`** | Opens a file in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input and LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading/writing, **`_fsopen`** checks for a CTRL+Z at the end of the file and removes it, if possible. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file that ends with a CTRL+Z might cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file. | +| **`b`** | Opens a file in binary (untranslated) mode; the above translations are suppressed. | +| **`D`** | Specifies a temporary file that's deleted when the last file pointer to it is closed. | +| **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| **`T`** | Specifies a file that isn't written to disk unless memory pressure requires it. | -If **`t`** or **`b`** is not given in *`mode`*, the translation mode is defined by the default-mode variable **`_fmode`**. If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. For a discussion of text and binary modes, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +If **`t`** or **`b`** isn't given in *`mode`*, the translation mode is defined by the default-mode variable **`_fmode`**. If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. For a discussion of text and binary modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). + +Regarding `T` and `D`: +- `T` avoids writing the file to disk as long as memory pressure doesn't require it. For more information, see `FILE_ATTRIBUTE_TEMPORARY` in [File attribute constants](/windows/win32/fileio/file-attribute-constants), and also this blog post [It's only temporary](/archive/blogs/larryosterman/its-only-temporary). +- `D` specifies a regular file that is written to disk. The difference is that it's automatically deleted when it's closed. +You can combine `TD` to get both semantics. + +`_fsopen` and `_wfsopen` are Microsoft-specific variants of [`fopen`](fopen-wfopen.md). They aren't part of the ANSI standard. For a more portable and secure function, if you don't require file sharing, consider [`_wfopen_s` or `fopen_s`](fopen-s-wfopen-s.md). The argument *`shflag`* is a constant expression consisting of one of the following manifest constants, defined in `Share.h`. -|Term|Definition| -|----------|----------------| -|**`_SH_COMPAT`**|Sets Compatibility mode for 16-bit applications.| -|**`_SH_DENYNO`**|Permits read and write access.| -|**`_SH_DENYRD`**|Denies read access to the file.| -|**`_SH_DENYRW`**|Denies read and write access to the file.| -|**`_SH_DENYWR`**|Denies write access to the file.| +| Term | Definition | +|---|---| +| `_SH_DENYNO` | Permits read and write access. | +| `_SH_DENYRD` | Denies read access to the file. | +| `_SH_DENYRW` | Denies read and write access to the file. | +| `_SH_DENYWR` | Denies write access to the file. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tfsopen`**|**`_fsopen`**|**`_fsopen`**|**`_wfsopen`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tfsopen`** | **`_fsopen`** | **`_fsopen`** | **`_wfsopen`** | ## Requirements -|Function|Required header|Optional headers| -|--------------|---------------------|----------------------| -|**`_fsopen`**|``|``

For manifest constant for *`shflag`* parameter.| -|**`_wfsopen`**|`` or ``|``

For manifest constant for *`shflag`* parameter.| +| Function | Required header | Optional headers | +|---|---|---| +| **`_fsopen`** | `` | ``

For manifest constant for *`shflag`* parameter. | +| **`_wfsopen`** | `` or `` | ``

For manifest constant for *`shflag`* parameter. | ## Example @@ -135,13 +140,13 @@ No one else in the network can write to this file until we are done. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fclose`, `_fcloseall`](fclose-fcloseall.md)
-[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)
-[`ferror`](ferror.md)
-[`_fileno`](fileno.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`freopen`, `_wfreopen`](freopen-wfreopen.md)
-[`_open`, `_wopen`](open-wopen.md)
-[`_setmode`](setmode.md)
-[`_sopen`, `_wsopen`](sopen-wsopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`ferror`](ferror.md)\ +[`_fileno`](fileno.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_setmode`](setmode.md)\ +[`_sopen`, `_wsopen`](sopen-wsopen.md) diff --git a/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md b/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md index d5994dcd59..41ce094bcc 100644 --- a/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md +++ b/docs/c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md @@ -3,14 +3,13 @@ description: "Learn more about: _fstat, _fstat32, _fstat64, _fstati64, _fstat32i title: "_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32" ms.date: "4/2/2020" api_name: ["_fstat32", "_fstat64", "_fstati64", "_fstat", "_fstat64i32", "_fstat32i64", "_o__fstat32", "_o__fstat32i64", "_o__fstat64", "_o__fstat64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstat32i64", "fstat", "fstat64i32", "_fstat64", "_fstati64", "fstat64", "_fstat32", "fstat32i64", "fstati64", "_fstat", "fstat32", "_fstat64i32"] helpviewer_keywords: ["_fstat64 function", "fstati64 function", "_fstat64i32 function", "_fstat32i64 function", "_fstat32 function", "file information", "fstat64i32 function", "fstat32 function", "fstat function", "fstat64 function", "_fstat function", "_fstati64 function", "fstat32i64 function"] -ms.assetid: 088f5e7a-9636-4cf7-ab8e-e28d2aa4280a --- -# _fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32 +# `_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32` Gets information about an open file. @@ -23,11 +22,11 @@ int _fstat( ); int _fstat32( int fd, - struct __stat32 *buffer + struct _stat32 *buffer ); int _fstat64( int fd, - struct __stat64 *buffer + struct _stat64 *buffer ); int _fstati64( int fd, @@ -45,68 +44,68 @@ int _fstat64i32( ### Parameters -*fd*
+*`fd`*\ File descriptor of the open file. -*buffer*
+*`buffer`*\ Pointer to the structure to store results. -## Return Value +## Return value -Returns 0 if the file-status information is obtained. A return value of -1 indicates an error. If the file descriptor is invalid or *buffer* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EBADF**, in the case of an invalid file descriptor, or to **EINVAL**, if *buffer* is **NULL**. +Returns 0 if the file-status information is obtained. A return value of -1 indicates an error. If the file descriptor is invalid or *`buffer`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EBADF` for an invalid file descriptor, or to `EINVAL` if *`buffer`* is `NULL`. ## Remarks -The **_fstat** function obtains information about the open file associated with *fd* and stores it in the structure pointed to by *buffer*. The **_stat** structure, defined in SYS\Stat.h, contains the following fields. +The **`_fstat`** function obtains information about the open file associated with *`fd`* and stores it in the structure pointed to by *`buffer`*. The **`_stat`** structure, defined in `SYS\Stat.h`, contains the following fields. -|Field|Meaning| -|-|-| -| **st_atime** | Time of the last file access. | -| **st_ctime** | Time of the creation of the file. | -| **st_dev** | If a device, *fd*; otherwise 0. | -| **st_mode** | Bit mask for file-mode information. The **_S_IFCHR** bit is set if *fd* refers to a device. The **_S_IFREG** bit is set if *fd* refers to an ordinary file. The read/write bits are set according to the file's permission mode. **_S_IFCHR** and other constants are defined in SYS\Stat.h. | -| **st_mtime** | Time of the last modification of the file. | -| **st_nlink** | Always 1 on non-NTFS file systems. | -| **st_rdev** | If a device, *fd*; otherwise 0. | -| **st_size** | Size of the file in bytes. | +| Field | Meaning | +|---|---| +| **`st_atime`** | Time of the last file access. | +| **`st_ctime`** | Time of the creation of the file. | +| **`st_dev`** | If a device, *`fd`*; otherwise 0. | +| **`st_mode`** | Bit mask for file-mode information. The `_S_IFCHR` bit is set if *`fd`* refers to a device. The `_S_IFREG` bit is set if *`fd`* refers to an ordinary file. The read/write bits are set according to the file's permission mode. `_S_IFCHR` and other constants are defined in `SYS\Stat.h`. | +| **`st_mtime`** | Time of the last modification of the file. | +| **`st_nlink`** | Always 1 on non-NTFS file systems. | +| **`st_rdev`** | If a device, *`fd`*; otherwise 0. | +| **`st_size`** | Size of the file in bytes. | -If *fd* refers to a device, the **st_atime**, **st_ctime**, **st_mtime**, and **st_size** fields are not meaningful. +If *`fd`* refers to a device, the **`st_atime`**, **`st_ctime`**, **`st_mtime`**, and **`st_size`** fields aren't meaningful. -Because Stat.h uses the [_dev_t](../../c-runtime-library/standard-types.md) type, which is defined in Types.h, you must include Types.h before Stat.h in your code. +Because `Stat.h` uses the [`_dev_t`](../standard-types.md) type, which is defined in `Types.h`, you must include `Types.h` before `Stat.h` in your code. -**_fstat64**, which uses the **__stat64** structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas the other functions only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +**`_fstat64`**, which uses the `_stat64` structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas the other functions only represent dates through 23:59:59 January 18, 2038, UTC. The lower bound of the date range for all these functions is Midnight, January 1, 1970. -Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file lengths. The first numerical suffix (**32** or **64**) indicates the size of the time type used; the second suffix is either **i32** or **i64**, indicating whether the file size is represented as a 32-bit or 64-bit integer. +Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file lengths. The first numerical suffix (**`32`** or **`64`**) indicates the size of the time type used; the second suffix is either **`i32`** or **`i64`**, indicating whether the file size is represented as a 32-bit or 64-bit integer. -**_fstat** is equivalent to **_fstat64i32**, and **`struct`** **_stat** contains a 64-bit time. This is true unless **_USE_32BIT_TIME_T** is defined, in which case the old behavior is in effect; **_fstat** uses a 32-bit time, and **`struct`** **_stat** contains a 32-bit time. The same is true for **_fstati64**. +Unless `_USE_32BIT_TIME_T` is defined, **`_fstat`** is equivalent to **`_fstat64i32`**, and `_stat` contains a 64-bit time. When `_USE_32BIT_TIME_T` is defined, **`_fstat`** uses a 32-bit time, and `_stat` contains a 32-bit time. The same is true for **`_fstati64`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Time Type and File Length Type Variations of _stat +### Time type and file length type variations of `_stat` -|Functions|_USE_32BIT_TIME_T defined?|Time type|File length type| -|---------------|------------------------------------|---------------|----------------------| -|**_fstat**|Not defined|64-bit|32-bit| -|**_fstat**|Defined|32-bit|32-bit| -|**_fstat32**|Not affected by the macro definition|32-bit|32-bit| -|**_fstat64**|Not affected by the macro definition|64-bit|64-bit| -|**_fstati64**|Not defined|64-bit|64-bit| -|**_fstati64**|Defined|32-bit|64-bit| -|**_fstat32i64**|Not affected by the macro definition|32-bit|64-bit| -|**_fstat64i32**|Not affected by the macro definition|64-bit|32-bit| +| Functions | `_USE_32BIT_TIME_T` defined? | Time type | File length type | +|---|---|---|---| +| **`_fstat`** | Not defined | 64-bit | 32-bit | +| **`_fstat`** | Defined | 32-bit | 32-bit | +| **`_fstat32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_fstat64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_fstati64`** | Not defined | 64-bit | 64-bit | +| **`_fstati64`** | Defined | 32-bit | 64-bit | +| **`_fstat32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_fstat64i32`** | Not affected by the macro definition | 64-bit | 32-bit | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fstat**|\ and \| -|**_fstat32**|\ and \| -|**_fstat64**|\ and \| -|**_fstati64**|\ and \| -|**_fstat32i64**|\ and \| -|**_fstat64i32**|\ and \| +| Function | Required header | +|---|---| +| **`_fstat`** | `` and `` | +| **`_fstat32`** | `` and `` | +| **`_fstat64`** | `` and `` | +| **`_fstati64`** | `` and `` | +| **`_fstat32i64`** | `` and `` | +| **`_fstat64i32`** | `` and `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -175,8 +174,8 @@ Time modified : Wed May 07 15:25:11 2003 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_access, _waccess](access-waccess.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_filelength, _filelengthi64](filelength-filelengthi64.md)
-[_stat, _wstat Functions](stat-functions.md)
+[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_filelength`, `_filelengthi64`](filelength-filelengthi64.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/ftell-ftelli64.md b/docs/c-runtime-library/reference/ftell-ftelli64.md index 6999b0129a..db0cea30ae 100644 --- a/docs/c-runtime-library/reference/ftell-ftelli64.md +++ b/docs/c-runtime-library/reference/ftell-ftelli64.md @@ -3,14 +3,13 @@ description: "Learn more about: ftell, _ftelli64" title: "ftell, _ftelli64" ms.date: "4/2/2020" api_name: ["_ftelli64", "ftell", "_o__ftelli64", "_o_ftell"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftelli64", "ftell"] helpviewer_keywords: ["ftell function", "ftelli64 function", "_ftelli64 function", "file pointers [C++], getting current position", "file pointers [C++]"] -ms.assetid: 40149cd8-65f2-42ff-b70c-68e3e918cdd7 --- -# ftell, _ftelli64 +# `ftell`, `_ftelli64` Gets the current position of a file pointer. @@ -27,35 +26,35 @@ __int64 _ftelli64( ### Parameters -*stream*
-Target **FILE** structure. +*`stream`*\ +Target `FILE` structure. -## Return Value +## Return value -**ftell** and **_ftelli64** return the current file position. The value returned by **ftell** and **_ftelli64** may not reflect the physical byte offset for streams opened in text mode, because text mode causes carriage return-line feed translation. Use **ftell** with [fseek](fseek-fseeki64.md) or **_ftelli64** with [_fseeki64](fseek-fseeki64.md) to return to file locations correctly. On error, **ftell** and **_ftelli64** invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1L and set **errno** to one of two constants, defined in ERRNO.H. The **EBADF** constant means the *stream* argument is not a valid file pointer value or does not refer to an open file. **EINVAL** means an invalid *stream* argument was passed to the function. On devices incapable of seeking (such as terminals and printers), or when *stream* does not refer to an open file, the return value is undefined. +**`ftell`** and **`_ftelli64`** return the current file position. The value returned by **`ftell`** and **`_ftelli64`** may not reflect the physical byte offset for streams opened in text mode, because text mode causes carriage return-line feed translation. Use **`ftell`** with [`fseek`](fseek-fseeki64.md) or **`_ftelli64`** with [`_fseeki64`](fseek-fseeki64.md) to return to file locations correctly. On error, **`ftell`** and **`_ftelli64`** invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1L and set `errno` to one of two constants, defined in `ERRNO.H`. The `EBADF` constant means the *`stream`* argument isn't a valid file pointer value or doesn't refer to an open file. `EINVAL` means an invalid *`stream`* argument was passed to the function. On devices incapable of seeking (such as terminals and printers), or when *`stream`* doesn't refer to an open file, the return value is undefined. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **ftell** and **_ftelli64** functions retrieve the current position of the file pointer (if any) associated with *stream*. The position is expressed as an offset relative to the beginning of the stream. +The **`ftell`** and **`_ftelli64`** functions retrieve the current position of the file pointer (if any) associated with *`stream`*. The position is expressed as an offset relative to the beginning of the stream. -Note that when a file is opened for appending data, the current file position is determined by the last I/O operation, not by where the next write would occur. For example, if a file is opened for an append and the last operation was a read, the file position is the point where the next read operation would start, not where the next write would start. (When a file is opened for appending, the file position is moved to end of file before any write operation.) If no I/O operation has yet occurred on a file opened for appending, the file position is the beginning of the file. +When a file is opened for appending data, the current file position is determined by the last I/O operation, not by where the next write would occur. For example, assume a file is opened for an append and the last operation was a read. The file position is the point where the next read operation would start, not where the next write would start. (When a file is opened for appending, the file position is moved to end of file before any write operation.) If no I/O operation has yet occurred on a file opened for appending, the file position is the beginning of the file. -In text mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing, **fopen** and all related routines check for a CTRL+Z at the end of the file and remove it if possible. This is done because using the combination of **ftell** and [fseek](fseek-fseeki64.md) or **_ftelli64** and [_fseeki64](fseek-fseeki64.md), to move within a file that ends with a CTRL+Z may cause **ftell** or **_ftelli64** to behave improperly near the end of the file. +In text mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing, **`fopen`** and all related routines check for a CTRL+Z at the end of the file and remove it if possible. It's because using the combination of **`ftell`** and [`fseek`](fseek-fseeki64.md), or **`_ftelli64`** and [`_fseeki64`](fseek-fseeki64.md), to move within a file that ends with a CTRL+Z may cause **`ftell`** or **`_ftelli64`** to behave improperly near the end of the file. -This function locks the calling thread during execution and is therefore thread-safe. For a non-locking version, see **_ftell_nolock**. +This function locks the calling thread during execution and is therefore thread-safe. For a non-locking version, see **`_ftell_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional headers| -|--------------|---------------------|----------------------| -|**ftell**|\|\| -|**_ftelli64**|\|\| +| Function | Required header | Optional headers | +|---|---|---| +| **`ftell`** | `` | `` | +| **`_ftelli64`** | `` | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -93,8 +92,8 @@ Position after trying to read 100 bytes: 100 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[fgetpos](fgetpos.md)
-[fseek, _fseeki64](fseek-fseeki64.md)
-[_lseek, _lseeki64](lseek-lseeki64.md)
+[Stream I/O](../stream-i-o.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`fgetpos`](fgetpos.md)\ +[`fseek`, `_fseeki64`](fseek-fseeki64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md) diff --git a/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md b/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md index e13c6fbf3b..7b8c51b173 100644 --- a/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md +++ b/docs/c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _ftell_nolock, _ftelli64_nolock" title: "_ftell_nolock, _ftelli64_nolock" +description: "Learn more about: _ftell_nolock, _ftelli64_nolock" ms.date: "4/2/2020" api_name: ["_ftelli64_nolock", "_ftell_nolock", "_o__ftell_nolock", "_o__ftelli64_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftelli64_nolock", "ftelli64_nolock", "ftell_nolock", "_ftell_nolock"] helpviewer_keywords: ["ftelli64_nolock function", "_ftelli64_nolock function", "_ftell_nolock function", "ftell_nolock function", "file pointers [C++], getting current position"] -ms.assetid: 84e68b0a-32f8-4c4a-90ad-3f2387685ede --- -# _ftell_nolock, _ftelli64_nolock +# `_ftell_nolock`, `_ftelli64_nolock` -Gets the current position of a file pointer, without locking the thread. +Gets the current position of a file pointer without locking. ## Syntax @@ -27,32 +26,32 @@ __int64 _ftelli64_nolock( ### Parameters -*stream*
-Target the **FILE** structure. +*`stream`*\ +Target the `FILE` structure. -## Return Value +## Return value -Same as **ftell** and **_ftelli64**. For more information, see [ftell, _ftelli64](ftell-ftelli64.md). +Same as `ftell` and `_ftelli64`. For more information, see [`ftell`, `_ftelli64`](ftell-ftelli64.md). ## Remarks -These functions are non-locking versions of **ftell** and **_ftelli64**, respectively. They are identical to **ftell** and **_ftelli64** except that they are not protected from interference by other threads. These functions might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +These functions are non-locking versions of `ftell` and `_ftelli64`, respectively. They're identical to `ftell` and `_ftelli64` except that they aren't protected from interference by other threads. These functions might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**ftell_nolock**|\|\| -|**_ftelli64_nolock**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`ftell_nolock`** | \ | \ | +| **`_ftelli64_nolock`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetpos](fgetpos.md)
-[fseek, _fseeki64](fseek-fseeki64.md)
-[_lseek, _lseeki64](lseek-lseeki64.md)
-[ftell, _ftelli64](ftell-ftelli64.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetpos`](fgetpos.md)\ +[`fseek`, `_fseeki64`](fseek-fseeki64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md)\ +[`ftell`, `_ftelli64`](ftell-ftelli64.md) diff --git a/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md b/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md index a70e6f942c..7cb0247f80 100644 --- a/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md +++ b/docs/c-runtime-library/reference/ftime-ftime32-ftime64.md @@ -3,16 +3,16 @@ description: "Learn more about: _ftime, _ftime32, _ftime64" title: "_ftime, _ftime32, _ftime64" ms.date: "4/2/2020" api_name: ["_ftime64", "_ftime", "_ftime32", "_o__ftime32", "_o__ftime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftime32", "_ftime", "_ftime64", "ftime64", "ftime", "ftime32"] helpviewer_keywords: ["ftime64 function", "_ftime64 function", "current time", "_ftime function", "ftime function", "_ftime32 function", "ftime32 function", "time, getting current"] ms.assetid: 96bc464c-3bcd-41d5-a212-8bbd836b814a --- -# _ftime, _ftime32, _ftime64 +# `_ftime`, `_ftime32`, `_ftime64` -Get the current time. More secure versions of these functions are available; see [_ftime_s, _ftime32_s, _ftime64_s](ftime-s-ftime32-s-ftime64-s.md). +Get the current time. More secure versions of these functions are available; see [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](ftime-s-ftime32-s-ftime64-s.md). ## Syntax @@ -24,37 +24,37 @@ void _ftime64( struct __timeb64 *timeptr ); ### Parameters -*timeptr*
-Pointer to a **_timeb**, **__timeb32**, or **__timeb64** structure. +*`timeptr`*\ +Pointer to a `_timeb`, `__timeb32`, or `__timeb64` structure. ## Remarks -The **_ftime** function gets the current local time and stores it in the structure pointed to by *timeptr*. The **_timeb**, **__timeb32**, and **__timeb64** structures are defined in \. They contain four fields, which are listed in the following table. +The **`_ftime`** function gets the current local time and stores it in the structure pointed to by *`timeptr`*. The `_timeb`, `__timeb32`, and `__timeb64` structures are defined in \. They contain four fields, which are listed in the following table. -|Field|Description| -|-|-| -|**dstflag**|Nonzero if daylight savings time is currently in effect for the local time zone. (See [_tzset](tzset.md) for an explanation of how daylight savings time is determined.)| -|**millitm**|Fraction of a second in milliseconds.| -|**time**|Time in seconds since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC).| -|**timezone**|Difference in minutes, moving westward, between UTC and local time. The value of **timezone** is set from the value of the global variable **_timezone** (see **_tzset**).| +| Field | Description | +|---|---| +| `dstflag` | Nonzero if daylight savings time is currently in effect for the local time zone. (See [`_tzset`](tzset.md) for an explanation of how daylight savings time is determined.) | +| `millitm` | Fraction of a second in milliseconds. | +| `time` | Time in seconds since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). | +| `timezone` | Difference in minutes, moving westward, between UTC and local time. The value of `timezone` is set from the value of the global variable `_timezone` (see `_tzset`). | -The **_ftime64** function, which uses the **__timeb64** structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **_ftime32** only represents dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +The **`_ftime64`** function, which uses the `__timeb64` structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **`_ftime32`** only represents dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -The **_ftime** function is equivalent to **_ftime64**, and **_timeb** contains a 64-bit time unless **_USE_32BIT_TIME_T** is defined, in which case the old behavior is in effect; **_ftime** uses a 32-bit time and **_timeb** contains a 32-bit time. +The **`_ftime`** function is equivalent to **`_ftime64`**, and `_timeb` contains a 64-bit time unless `_USE_32BIT_TIME_T` is defined, in which case the old behavior is in effect; **`_ftime`** uses a 32-bit time and `_timeb` contains a 32-bit time. -**_ftime** validates its parameters. If passed a null pointer as *timeptr*, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets **errno** to **EINVAL**. +**`_ftime`** validates its parameters. If passed a null pointer as *`timeptr`*, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_ftime**|\ and \| -|**_ftime32**|\ and \| -|**_ftime64**|\ and \| +| Function | Required header | +|---|---| +| **`_ftime`** | \ and \ | +| **`_ftime32`** | \ and \ | +| **`_ftime64`** | \ and \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -113,9 +113,9 @@ The time is Mon Apr 28 11:08:54.230 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md b/docs/c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md index 3496aa31fc..01d4e33c5e 100644 --- a/docs/c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md +++ b/docs/c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _ftime_s, _ftime32_s, _ftime64_s" title: "_ftime_s, _ftime32_s, _ftime64_s" ms.date: "4/2/2020" api_name: ["_ftime_s", "_ftime64_s", "_ftime32_s", "_o__ftime32_s", "_o__ftime64_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftime_s", "_ftime64_s", "ftime_s", "_ftime32_s", "ftime32_s", "ftime64_s"] helpviewer_keywords: ["ftime32_s function", "ftime_s function", "_ftime64_s function", "current time", "ftime64_s function", "time, getting current", "_ftime_s function", "_ftime32_s function"] ms.assetid: d03080d9-a520-45be-aa65-504bdb197e8b --- -# _ftime_s, _ftime32_s, _ftime64_s +# `_ftime_s`, `_ftime32_s`, `_ftime64_s` -Gets the current time. These are versions of [_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Gets the current time. These functions are versions of [`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,45 +24,45 @@ errno_t _ftime64_s( struct __timeb64 *timeptr ); ### Parameters -*timeptr*
-Pointer to a **_timeb**, **__timeb32**, or **__timeb64** structure. +*`timeptr`*\ +Pointer to a `_timeb`, `__timeb32`, or `__timeb64` structure. -## Return Value +## Return value -Zero if successful, an error code on failure. If *timeptr* is **NULL**, the return value is **EINVAL**. +Zero if successful, an error code on failure. If *`timeptr`* is `NULL`, the return value is `EINVAL`. ## Remarks -The **_ftime_s** function gets the current local time and stores it in the structure pointed to by *timeptr*. The **_timeb**, **__timeb32**, and **__timeb64** structures are defined in SYS\Timeb.h. They contain four fields, which are listed in the following table. +The **`_ftime_s`** function gets the current local time and stores it in the structure pointed to by *`timeptr`*. The `_timeb`, `__timeb32`, and `__timeb64` structures are defined in SYS\Timeb.h. They contain four fields, which are listed in the following table. -|Field|Description| -|-|-| -|**dstflag**|Nonzero if daylight savings time is currently in effect for the local time zone. (See [_tzset](tzset.md) for an explanation of how daylight savings time is determined.)| -|**millitm**|Fraction of a second in milliseconds.| -|**time**|Time in seconds since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC).| -|**timezone**|Difference in minutes, moving westward, between UTC and local time. The value of **timezone** is set from the value of the global variable **_timezone** (see **_tzset**).| +| Field | Description | +|---|---| +| `dstflag` | Nonzero if daylight savings time is currently in effect for the local time zone. (See [`_tzset`](tzset.md) for an explanation of how daylight savings time is determined.) | +| `millitm` | Fraction of a second in milliseconds. | +| `time` | Time in seconds since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). | +| `timezone` | Difference in minutes, moving westward, between UTC and local time. The value of `timezone` is set from the value of the global variable `_timezone` (see `_tzset`). | -The **_ftime64_s** function, which uses the **__timeb64** structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **_ftime32_s** only represents dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +The **`_ftime64_s`** function, which uses the `__timeb64` structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **`_ftime32_s`** only represents dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -The **_ftime_s** function is equivalent to **_ftime64_s**, and **_timeb** contains a 64-bit time, unless **_USE_32BIT_TIME_T** is defined, in which case the old behavior is in effect; **_ftime_s** uses a 32-bit time and **_timeb** contains a 32-bit time. +The **`_ftime_s`** function is equivalent to **`_ftime64_s`**, and `_timeb` contains a 64-bit time, unless `_USE_32BIT_TIME_T` is defined, in which case the old behavior is in effect; **`_ftime_s`** uses a 32-bit time and `_timeb` contains a 32-bit time. -**_ftime_s** validates its parameters. If passed a null pointer as *timeptr*, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets **errno** to **EINVAL**. +**`_ftime_s`** validates its parameters. If passed a null pointer as *`timeptr`*, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_ftime_s**|\ and \| -|**_ftime32_s**|\ and \| -|**_ftime64_s**|\ and \| +| Function | Required header | +|---|---| +| **`_ftime_s`** | \ and \ | +| **`_ftime32_s`** | \ and \ | +| **`_ftime64_s`** | \ and \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -119,9 +119,9 @@ The time is Mon Apr 28 11:08:54.230 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md b/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md index 2f5d404992..e611447e0b 100644 --- a/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md +++ b/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["wfullpath_dbg", "_wfullpath_dbg", "_fullpath_dbg", "fullpath_dbg" helpviewer_keywords: ["_fullpath_dbg function", "relative file paths", "absolute paths", "fullpath_dbg function", "_wfullpath_dbg function", "wfullpath_dbg function"] ms.assetid: 81f72f85-07da-4f5c-866a-598e0fb03f6b --- -# _fullpath_dbg, _wfullpath_dbg +# `_fullpath_dbg`, `_wfullpath_dbg` -Versions of [_fullpath, _wfullpath](fullpath-wfullpath.md) that use the debug version of **malloc** to allocate memory. +Versions of [`_fullpath`, `_wfullpath`](fullpath-wfullpath.md) that use the debug version of `malloc` to allocate memory. ## Syntax @@ -37,51 +37,51 @@ wchar_t *_wfullpath_dbg( ### Parameters -*absPath*
-Pointer to a buffer containing the absolute or full path name, or **NULL**. +*`absPath`*\ +Pointer to a buffer containing the absolute or full path name, or `NULL`. -*relPath*
+*`relPath`*\ Relative path name. -*maxLength*
-Maximum length of the absolute path name buffer (*absPath*). This length is in bytes for **_fullpath** but in wide characters (**`wchar_t`**) for **_wfullpath**. +*`maxLength`*\ +Maximum length of the absolute path name buffer (*`absPath`*). This length is in bytes for **`_fullpath_dbg`** but in wide characters (**`wchar_t`**) for **`_wfullpath_dbg`**. -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -Each function returns a pointer to a buffer containing the absolute path name (*absPath*). If there is an error (for example, if the value passed in *relPath* includes a drive letter that is not valid or cannot be found, or if the length of the created absolute path name (*absPath*) is greater than *maxLength*) the function returns **NULL**. +Each function returns a pointer to a buffer containing the absolute path name (*`absPath`*). If there's an error (for example, if the value passed in *`relPath`* includes a drive letter that isn't valid or can't be found, or if the length of the created absolute path name (*`absPath`*) is greater than *`maxLength`*) the function returns `NULL`. ## Remarks -The **_fullpath_dbg** and **_wfullpath_dbg** functions are identical to **_fullpath** and **_wfullpath** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc**, **_malloc_dbg**, to allocate memory if **NULL** is passed as the first parameter. For information on the debugging features of **_malloc_dbg**, see [_malloc_dbg](malloc-dbg.md). +The **`_fullpath_dbg`** and **`_wfullpath_dbg`** functions are identical to `_fullpath` and `_wfullpath` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc`, `_malloc_dbg`, to allocate memory if `NULL` is passed as the first parameter. For information on the debugging features of `_malloc_dbg`, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the **_CRTDBG_MAP_ALLOC** flag. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_fullpath** and **_wfullpath** are remapped to **_fullpath_dbg** and **_wfullpath_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the `_CRTDBG_MAP_ALLOC` flag. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_fullpath` and `_wfullpath` are remapped to **`_fullpath_dbg`** and **`_wfullpath_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfullpath_dbg**|**_fullpath_dbg**|**_fullpath_dbg**|**_wfullpath_dbg**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tfullpath_dbg` | **`_fullpath_dbg`** | **`_fullpath_dbg`** | **`_wfullpath_dbg`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fullpath_dbg**|\| -|**_wfullpath_dbg**|\| +| Function | Required header | +|---|---| +| **`_fullpath_dbg`** | \ | +| **`_wfullpath_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_fullpath, _wfullpath](fullpath-wfullpath.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[File handling](../file-handling.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/fullpath-wfullpath.md b/docs/c-runtime-library/reference/fullpath-wfullpath.md index a5e57aaaf9..a0ab4a786e 100644 --- a/docs/c-runtime-library/reference/fullpath-wfullpath.md +++ b/docs/c-runtime-library/reference/fullpath-wfullpath.md @@ -3,14 +3,13 @@ description: "Learn more about: _fullpath, _wfullpath" title: "_fullpath, _wfullpath" ms.date: "4/2/2020" api_name: ["_fullpath", "_wfullpath", "_o__fullpath", "_o__wfullpath"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wfullpath", "fullpath", "_wfullpath", "_fullpath"] helpviewer_keywords: ["_wfullpath function", "relative file paths", "absolute paths", "wfullpath function", "_fullpath function", "fullpath function"] -ms.assetid: 4161ec17-0d22-45dd-b07d-0222553afae9 --- -# _fullpath, _wfullpath +# `_fullpath`, `_wfullpath` Creates an absolute or full path name for the specified relative path name. @@ -31,28 +30,26 @@ wchar_t *_wfullpath( ### Parameters -*absPath*
-Pointer to a buffer containing the absolute or full path name, or **NULL**. +*`absPath`*\ +Pointer to a buffer containing the absolute or full path name, or `NULL`. -*relPath*
+*`relPath`*\ Relative path name. -*maxLength*
-Maximum length of the absolute path name buffer (*absPath*). This length is in bytes for **_fullpath** but in wide characters (**`wchar_t`**) for **_wfullpath**. +*`maxLength`*\ +Maximum length of the absolute path name buffer (*`absPath`*). This length is in bytes for **`_fullpath`** but in wide characters (**`wchar_t`**) for **`_wfullpath`**. -## Return Value +## Return value -Each of these functions returns a pointer to a buffer containing the absolute path name (*absPath*). If there is an error (for example, if the value passed in *relPath* includes a drive letter that is not valid or cannot be found, or if the length of the created absolute path name (*absPath*) is greater than *maxLength*), the function returns **NULL**. +Each of these functions returns a pointer to a buffer containing the absolute path name (*`absPath`*). If there's an error (for example, if the value passed in *`relPath`* includes a drive letter that isn't valid or can't be found, or if the length of the created absolute path name (*`absPath`*) is greater than *`maxLength`*), the function returns `NULL`. ## Remarks -The **_fullpath** function expands the relative path name in *relPath* to its fully qualified or absolute path and stores this name in *absPath*. If *absPath* is **NULL**, **malloc** is used to allocate a buffer of sufficient length to hold the path name. It is the responsibility of the caller to free this buffer. A relative path name specifies a path to another location from the current location (such as the current working directory: "."). An absolute path name is the expansion of a relative path name that states the entire path required to reach the desired location from the root of the file system. Unlike **_makepath**, **_fullpath** can be used to obtain the absolute path name for relative paths (*relPath*) that include "./" or "../" in their names. +The **`_fullpath`** function expands the relative path name in *`relPath`* to its fully qualified or absolute path and stores this name in *`absPath`*. If *`absPath`* is `NULL`, **`malloc`** is used to allocate a buffer of sufficient length to hold the path name. It's the responsibility of the caller to free this buffer. A relative path name specifies a path to another location from the current location (such as the current working directory: `.`). An absolute path name is the expansion of a relative path name that states the entire path required to reach the desired location from the root of the file system. Unlike **`_makepath`**, **`_fullpath`** can be used to obtain the absolute path name for relative paths (*`relPath`*) that include `./` or `../` in their names. -For example, to use C run-time routines, the application must include the header files that contain the declarations for the routines. Each header file include statement references the location of the file in a relative manner (from the application's working directory): +For example, to use C run-time routines, the application must include the header files that contain the declarations for the routines. Each header file `#include` directive references the location of the file in a relative manner (from the application's working directory): ```C -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). - #include ``` @@ -60,28 +57,30 @@ when the absolute path (actual file system location) of the file might be: `\\machine\shareName\msvcSrc\crt\headerFiles\stdlib.h` -**_fullpath** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **_wfullpath** is a wide-character version of **_fullpath**; the string arguments to **_wfullpath** are wide-character strings. **_wfullpath** and **_fullpath** behave identically except that **_wfullpath** does not handle multibyte-character strings. +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +**`_fullpath`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **`_wfullpath`** is a wide-character version of **`_fullpath`**; the string arguments to **`_wfullpath`** are wide-character strings. **`_wfullpath`** and **`_fullpath`** behave identically except that **`_wfullpath`** doesn't handle multibyte-character strings. -If **_DEBUG** and **_CRTDBG_MAP_ALLOC** are both defined, calls to **_fullpath** and **_wfullpath** are replaced by calls to **_fullpath_dbg** and **_wfullpath_dbg** to allow for debugging memory allocations. For more information, see [_fullpath_dbg, _wfullpath_dbg](fullpath-dbg-wfullpath-dbg.md). +If `_DEBUG` and `_CRTDBG_MAP_ALLOC` are both defined, calls to **`_fullpath`** and **`_wfullpath`** are replaced by calls to **`_fullpath_dbg`** and **`_wfullpath_dbg`**, to allow you to debug memory allocations. For more information, see [`_fullpath_dbg`, `_wfullpath_dbg`](fullpath-dbg-wfullpath-dbg.md). -This function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), if *maxlen* is less than or equal to 0. If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **NULL**. +This function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), if *`maxlen`* is less than or equal to 0. If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `NULL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfullpath**|**_fullpath**|**_fullpath**|**_wfullpath**| +| `Tchar.h` routine | `_UNICODE and _MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tfullpath`** | **`_fullpath`** | **`_fullpath`** | **`_wfullpath`** | -If the *absPath* buffer is **NULL**, **_fullpath** calls [malloc](malloc.md) to allocate a buffer and ignores the *maxLength* argument. It is the caller's responsibility to deallocate this buffer (using [free](free.md)) as appropriate. If the *relPath* argument specifies a disk drive, the current directory of this drive is combined with the path. +If the *`absPath`* buffer is `NULL`, **`_fullpath`** calls [`malloc`](malloc.md) to allocate a buffer and ignores the *`maxLength`* argument. It's the caller's responsibility to deallocate this buffer (using [`free`](free.md)) as appropriate. If the *`relPath`* argument specifies a disk drive, the current directory of this drive is combined with the path. ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fullpath**|\| -|**_wfullpath**|\ or \| +| Function | Required header | +|---|---| +| **`_fullpath`** | `` | +| **`_wfullpath`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -120,8 +119,8 @@ Full path is: C:\Documents and Settings\user\test ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md)
-[_makepath, _wmakepath](makepath-wmakepath.md)
-[_splitpath, _wsplitpath](splitpath-wsplitpath.md)
+[File handling](../file-handling.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md)\ +[`_makepath`, `_wmakepath`](makepath-wmakepath.md)\ +[`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md) diff --git a/docs/c-runtime-library/reference/futime-futime32-futime64.md b/docs/c-runtime-library/reference/futime-futime32-futime64.md index b9fcafb183..a8b3805809 100644 --- a/docs/c-runtime-library/reference/futime-futime32-futime64.md +++ b/docs/c-runtime-library/reference/futime-futime32-futime64.md @@ -3,14 +3,14 @@ description: "Learn more about: _futime, _futime32, _futime64" title: "_futime, _futime32, _futime64" ms.date: "4/2/2020" api_name: ["_futime64", "_futime32", "_futime", "_o__futime32", "_o__futime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["futime", "_futime", "futime64", "_futime64"] helpviewer_keywords: ["_futime function", "futime32 function", "futime64 function", "file modification time [C++]", "_futime64 function", "futime function", "_futime32 function"] ms.assetid: b942ce8f-5cc7-4fa8-ab47-de5965eded53 --- -# _futime, _futime32, _futime64 +# `_futime`, `_futime32`, `_futime64` Sets the modification time on an open file. @@ -33,33 +33,33 @@ int _futime64( ### Parameters -*fd*
+*`fd`*\ File descriptor to the open file. -*filetime*
+*`filetime`*\ Pointer to the structure containing the new modification date. -## Return Value +## Return value -Return 0 if successful. If an error occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and **errno** is set to **EBADF**, indicating an invalid file descriptor, or **EINVAL**, indicating an invalid parameter. +Return 0 if successful. If an error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and `errno` is set to `EBADF`, indicating an invalid file descriptor, or `EINVAL`, indicating an invalid parameter. ## Remarks -The **_futime** routine sets the modification date and the access time on the open file associated with *fd*. **_futime** is identical to [_utime](utime-utime32-utime64-wutime-wutime32-wutime64.md), except that its argument is the file descriptor of an open file, rather than the name of a file or a path to a file. The **_utimbuf** structure contains fields for the new modification date and access time. Both fields must contain valid values. **_utimbuf32** and **_utimbuf64** are identical to **_utimbuf** except for the use of the 32-bit and 64-bit time types, respectively. **_futime** and **_utimbuf** use a 64-bit time type and **_futime** is identical in behavior to **_futime64**. If you need to force the old behavior, define **_USE_32BIT_TIME_T**. Doing this causes **_futime** to be identical in behavior to **_futime32** and causes the **_utimbuf** structure to use the 32-bit time type, making it equivalent to **__utimbuf32**. +The **`_futime`** routine sets the modification date and the access time on the open file associated with *`fd`*. **`_futime`** is identical to [`_utime`](utime-utime32-utime64-wutime-wutime32-wutime64.md), except that its argument is the file descriptor of an open file, rather than the name of a file or a path to a file. The `_utimbuf` structure contains fields for the new modification date and access time. Both fields must contain valid values. `_utimbuf32` and `_utimbuf64` are identical to `_utimbuf` except for the use of the 32-bit and 64-bit time types, respectively. **`_futime`** and `_utimbuf` use a 64-bit time type and **`_futime`** is identical in behavior to **`_futime64`**. If you need to force the old behavior, define `_USE_32BIT_TIME_T`. Doing this causes **`_futime`** to be identical in behavior to **`_futime32`** and causes the `_utimbuf` structure to use the 32-bit time type, making it equivalent to `__utimbuf32`. -**_futime64**, which uses the **__utimbuf64** structure, can read and modify file dates through 23:59:59, December 31, 3000, UTC; whereas a call to **_futime32** fails if the date on the file is later than 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for these functions. +**`_futime64`**, which uses the `__utimbuf64` structure, can read and modify file dates through 23:59:59, December 31, 3000, UTC; whereas a call to **`_futime32`** fails if the date on the file is later than 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for these functions. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_futime**|\|\| -|**_futime32**|\|\| -|**_futime64**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_futime`** | \ | \ | +| **`_futime32`** | \ | \ | +| **`_futime64`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -103,7 +103,7 @@ int main( void ) Arbitrary file contents. ``` -### Sample Output +### Sample output ```Output Volume in drive Z has no label. @@ -127,4 +127,4 @@ File time modified ## See also -[Time Management](../../c-runtime-library/time-management.md)
+[Time management](../time-management.md) diff --git a/docs/c-runtime-library/reference/fwide.md b/docs/c-runtime-library/reference/fwide.md index e85921f069..71113cfe48 100644 --- a/docs/c-runtime-library/reference/fwide.md +++ b/docs/c-runtime-library/reference/fwide.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: fwide" title: "fwide" -ms.date: "11/04/2016" +description: "Learn more about: fwide" +ms.date: 11/04/2016 api_name: ["fwide"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fwide"] helpviewer_keywords: ["fwide function"] -ms.assetid: a4641f5b-d74f-4946-95d5-53a64610d28d --- -# fwide +# `fwide` Unimplemented. @@ -19,21 +18,21 @@ Unimplemented. ```C int fwide( FILE *stream, - int mode; + int mode ); ``` ### Parameters -*stream*
-Pointer to **FILE** structure (ignored). +*`stream`*\ +Pointer to `FILE` structure (ignored). -*mode*
+*`mode`*\ The new width of the stream: positive for wide character, negative for byte, zero to leave unchanged. (This value is ignored.) -## Return Value +## Return value -This function currently just returns *mode*. +This function currently just returns *`mode`*. ## Remarks @@ -41,8 +40,8 @@ The current version of this function doesn't conform to the C Standard. ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fwide**|\| +| Function | Required header | +|---|---| +| **`fwide`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/fwrite-nolock.md b/docs/c-runtime-library/reference/fwrite-nolock.md index 3dc77e036b..1f72d29198 100644 --- a/docs/c-runtime-library/reference/fwrite-nolock.md +++ b/docs/c-runtime-library/reference/fwrite-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fwrite_nolock" title: "_fwrite_nolock" +description: "Learn more about: _fwrite_nolock" ms.date: "4/2/2020" api_name: ["_fwrite_nolock", "_o__fwrite_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fwrite_nolock", "fwrite_nolock"] helpviewer_keywords: ["fwrite_nolock function", "streams, writing data to", "_fwrite_nolock function"] -ms.assetid: 2b4ec6ce-742e-4615-8407-44a0a18ec1d7 --- -# _fwrite_nolock +# `_fwrite_nolock` -Writes data to a stream, without locking the thread. +Writes data to a stream without locking. ## Syntax @@ -27,42 +26,42 @@ size_t _fwrite_nolock( ### Parameters -*buffer*
+*`buffer`*\ Pointer to the data to be written. -*size*
+*`size`*\ Item size in bytes. -*count*
+*`count`*\ Maximum number of items to be written. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -Same as [fwrite](fwrite.md). +Same as [`fwrite`](fwrite.md). ## Remarks -This function is a non-locking version of **fwrite**. It is identical to **fwrite** except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fwrite`. It's identical to `fwrite` except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fwrite_nolock**|\| +| Function | Required header | +|---|---| +| **`_fwrite_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [fread](fread.md). +See the example for [`fread`](fread.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fread](fread.md)
-[_write](write.md)
+[Stream I/O](../stream-i-o.md)\ +[`fread`](fread.md)\ +[`_write`](write.md) diff --git a/docs/c-runtime-library/reference/fwrite.md b/docs/c-runtime-library/reference/fwrite.md index 99197cc851..0770119aec 100644 --- a/docs/c-runtime-library/reference/fwrite.md +++ b/docs/c-runtime-library/reference/fwrite.md @@ -3,7 +3,7 @@ description: "Learn more about: fwrite" title: "fwrite" ms.date: "4/2/2020" api_name: ["fwrite", "_o_fwrite"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fwrite"] @@ -27,39 +27,39 @@ size_t fwrite( ### Parameters -*`buffer`*
+*`buffer`*\ Pointer to data to be written. -*`size`*
+*`size`*\ Item size, in bytes. -*`count`*
+*`count`*\ Maximum number of items to be written. -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**`fwrite`** returns the number of full items actually written, which may be less than *`count`* if an error occurs. Also, if an error occurs, the file-position indicator cannot be determined. If either *`stream`* or *`buffer`* is a null pointer, or if an odd number of bytes to be written is specified in Unicode mode, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns 0. +**`fwrite`** returns the number of full items the function writes, which may be less than *`count`* if an error occurs. Also, if an error occurs, the file-position indicator can't be determined. If either *`stream`* or *`buffer`* is a null pointer, or if an odd number of bytes to be written is specified in Unicode mode, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. ## Remarks -The **`fwrite`** function writes up to *`count`* items, of *`size`* length each, from *`buffer`* to the output *`stream`*. The file pointer associated with *`stream`* (if there is one) is incremented by the number of bytes actually written. If *`stream`* is opened in text mode, each line feed is replaced with a carriage return-line feed pair. The replacement has no effect on the return value. +The **`fwrite`** function writes up to *`count`* items, of *`size`* length each, from *`buffer`* to the output *`stream`*. The file pointer associated with *`stream`* (if there's one) is incremented by the number of bytes **`fwrite`** writes. If *`stream`* is opened in text mode, each line feed is replaced with a carriage return-line feed pair. The replacement has no effect on the return value. -When *`stream`* is opened in Unicode translation mode—for example, if *`stream`* is opened by calling **`fopen`** and using a mode parameter that includes **`ccs=UNICODE`**, **`ccs=UTF-16LE`**, or **`ccs=UTF-8`**, or if the mode is changed to a Unicode translation mode by using **`_setmode`** and a mode parameter that includes **`_O_WTEXT`**, **`_O_U16TEXT`**, or **`_O_U8TEXT`**—*buffer* is interpreted as a pointer to an array of **`wchar_t`** that contains UTF-16 data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. +When *`stream`* is opened in Unicode translation mode—for example, if *`stream`* is opened by calling **`fopen`** and using a mode parameter that includes **`ccs=UNICODE`**, **`ccs=UTF-16LE`**, or **`ccs=UTF-8`**, or if the mode is changed to a Unicode translation mode by using **`_setmode`** and a mode parameter that includes `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`—*`buffer`* is interpreted as a pointer to an array of **`wchar_t`** that contains UTF-16 data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. -Because this function locks the calling thread, it is thread-safe. For a non-locking version, see **`_fwrite_nolock`**. +Because this function locks the calling thread, it's thread-safe. For a non-locking version, see **`_fwrite_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fwrite`**|``| +| Function | Required header | +|---|---| +| **`fwrite`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -67,8 +67,8 @@ See the example for [`fread`](fread.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`_setmode`](setmode.md)
-[`fread`](fread.md)
-[`_fwrite_nolock`](fwrite-nolock.md)
-[`_write`](write.md)
+[Stream I/O](../stream-i-o.md)\ +[`_setmode`](setmode.md)\ +[`fread`](fread.md)\ +[`_fwrite_nolock`](fwrite-nolock.md)\ +[`_write`](write.md) diff --git a/docs/c-runtime-library/reference/gcvt-s.md b/docs/c-runtime-library/reference/gcvt-s.md index e660c256a8..d19f64f847 100644 --- a/docs/c-runtime-library/reference/gcvt-s.md +++ b/docs/c-runtime-library/reference/gcvt-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _gcvt_s" title: "_gcvt_s" ms.date: "4/2/2020" api_name: ["_gcvt_s", "_o__gcvt_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_gcvt_s", "gcvt_s"] helpviewer_keywords: ["_gcvt_s function", "_CVTBUFSIZE", "floating-point functions, converting number to string", "gcvt_s function", "numbers, converting to strings", "conversions, floating point to strings", "strings [C++], converting from floating point", "CVTBUFSIZE"] ms.assetid: 0a8d8a26-5940-4ae3-835e-0aa6ec1b0744 --- -# _gcvt_s +# `_gcvt_s` -Converts a floating-point value to a string. This is a version of [_gcvt](gcvt.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a floating-point value to a string. This function is a version of [`_gcvt`](gcvt.md) with security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,51 +33,51 @@ errno_t _gcvt_s( ### Parameters -*buffer*
+*`buffer`*\ Buffer to store the result of the conversion. -*sizeInBytes*
+*`sizeInBytes`*\ Size of the buffer. -*value*
+*`value`*\ Value to be converted. -*digits*
+*`digits`*\ Number of significant digits stored. -## Return Value +## Return value -Zero if successful. If a failure occurs due to an invalid parameter (see the following table for invalid values), the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in Errno.h. For a listing of these errors, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. If a failure occurs due to an invalid parameter (see the following table for invalid values), the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in Errno.h. For a listing of these errors, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Error Conditions +### Error conditions -|*buffer*|*sizeInBytes*|*value*|*digits*|Return|Value in *buffer*| -|--------------|-------------------|-------------|--------------|------------|-----------------------| -|**NULL**|any|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|zero|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|any|any|>= *sizeInBytes*|**EINVAL**|Not modified.| +| *`buffer`* | *`sizeInBytes`* | *`value`* | *`digits`* | Return | Value in *`buffer`* | +|---|---|---|---|---|---| +| `NULL` | any | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | zero | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | any | any | >= *`sizeInBytes`* | `EINVAL` | Not modified. | **Security Issues** -**_gcvt_s** can generate an access violation if *buffer* does not point to valid memory and is not **NULL**. +**`_gcvt_s`** can generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`. ## Remarks -The **_gcvt_s** function converts a floating-point *value* to a character string (which includes a decimal point and a possible sign byte) and stores the string in *buffer*. *buffer* should be large enough to accommodate the converted value plus a terminating null character, which is appended automatically. A buffer of length **_CVTBUFSIZE** is sufficient for any floating point value. If a buffer size of *digits* + 1 is used, the function will not overwrite the end of the buffer, so be sure to supply a sufficient buffer for this operation. **_gcvt_s** attempts to produce *digits* digits in decimal format. If it cannot, it produces *digits* digits in exponential format. Trailing zeros can be suppressed in the conversion. +The **`_gcvt_s`** function converts a floating-point *`value`* to a character string (which includes a decimal point and a possible sign byte) and stores the string in *`buffer`*. *`buffer`* should be large enough to accommodate the converted value plus a terminating null character, which is appended automatically. A buffer of length `_CVTBUFSIZE` is sufficient for any floating point value. If a buffer size of *`digits`* + 1 is used, the function won't overwrite the end of the buffer, so be sure to supply a sufficient buffer for this operation. **`_gcvt_s`** attempts to produce *`digits`* digits in decimal format. If it can't, it produces *`digits`* digits in exponential format. Trailing zeros can be suppressed in the conversion. -In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_gcvt_s**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_gcvt_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,9 +112,9 @@ Converted value: 1.2 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt_s](ecvt-s.md)
-[_fcvt_s](fcvt-s.md)
-[_gcvt](gcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt_s`](ecvt-s.md)\ +[`_fcvt_s`](fcvt-s.md)\ +[`_gcvt`](gcvt.md) diff --git a/docs/c-runtime-library/reference/gcvt.md b/docs/c-runtime-library/reference/gcvt.md index b8193be30a..430d67fb4b 100644 --- a/docs/c-runtime-library/reference/gcvt.md +++ b/docs/c-runtime-library/reference/gcvt.md @@ -3,16 +3,16 @@ description: "Learn more about: _gcvt" title: "_gcvt" ms.date: "4/2/2020" api_name: ["_gcvt", "_o__gcvt"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_gcvt"] helpviewer_keywords: ["_gcvt function", "_CVTBUFSIZE", "gcvt function", "floating-point functions, converting number to string", "numbers, converting to strings", "conversions, floating point to strings", "strings [C++], converting from floating point", "CVTBUFSIZE"] ms.assetid: 5761411e-c06b-409a-912f-810fe7f4bcb5 --- -# _gcvt +# `_gcvt` -Converts a floating-point value to a string, which it stores in a buffer. A more secure version of this function is available; see [_gcvt_s](gcvt-s.md). +Converts a floating-point value to a string, which it stores in a buffer. A more secure version of this function is available; see [`_gcvt_s`](gcvt-s.md). ## Syntax @@ -26,36 +26,36 @@ char *_gcvt( ### Parameters -*value*
+*`value`*\ Value to be converted. -*digits*
+*`digits`*\ Number of significant digits stored. -*buffer*
+*`buffer`*\ Storage location for the result. -## Return Value +## Return value -**_gcvt** returns a pointer to the string of digits. +**`_gcvt`** returns a pointer to the string of digits. ## Remarks -The **_gcvt** function converts a floating-point *value* to a character string (which includes a decimal point and a possible sign byte) and stores the string in *buffer*. The *buffer* should be large enough to accommodate the converted value plus a terminating null character, which is appended automatically. If a buffer size of *digits* + 1 is used, the function overwrites the end of the buffer. This is because the converted string includes a decimal point and can contain sign and exponent information. There is no provision for overflow. **_gcvt** attempts to produce *digits* digits in decimal format. If it cannot, it produces *digits* digits in exponential format. Trailing zeros might be suppressed in the conversion. +The **`_gcvt`** function converts a floating-point *`value`* to a character string (which includes a decimal point and a possible sign byte) and stores the string in *`buffer`*. The *`buffer`* should be large enough to accommodate the converted value plus a terminating null character, which is appended automatically. If a buffer size of *`digits`* + 1 is used, the function overwrites the end of the buffer. The overwrite happens because the converted string includes a decimal point and can also contain sign and exponent information. The function doesn't account for the overflow. **`_gcvt`** attempts to produce *`digits`* digits in decimal format. If it can't, it produces *`digits`* digits in exponential format. Trailing zeros might be suppressed in the conversion. -A *buffer* of length **_CVTBUFSIZE** is sufficient for any floating point value. +A *`buffer`* of length `_CVTBUFSIZE` is sufficient for any floating point value. -This function validates its parameters. If *buffer* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **NULL**. +This function validates its parameters. If *`buffer`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_gcvt**|\| +| Routine | Required header | +|---|---| +| **`_gcvt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -115,8 +115,8 @@ buffer: '-1.23456789012e-002' (19 chars) ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt](ecvt.md)
-[_fcvt](fcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt`](fcvt.md) diff --git a/docs/c-runtime-library/reference/get-current-locale.md b/docs/c-runtime-library/reference/get-current-locale.md index a00547da3b..d2a771773b 100644 --- a/docs/c-runtime-library/reference/get-current-locale.md +++ b/docs/c-runtime-library/reference/get-current-locale.md @@ -10,7 +10,7 @@ f1_keywords: ["get_current_locale", "__get_current_locale", "_get_current_locale helpviewer_keywords: ["get_current_locale function", "_get_current_locale function", "locales, getting information on", "__get_current_locale function"] ms.assetid: 572217f2-a37a-4105-a293-a250b4fabd99 --- -# _get_current_locale +# `_get_current_locale` Gets a locale object representing the current locale. @@ -20,26 +20,26 @@ Gets a locale object representing the current locale. _locale_t _get_current_locale(void); ``` -## Return Value +## Return value A locale object representing the current locale. ## Remarks -The **_get_current_locale** function gets the currently set locale for the thread and returns a locale object representing that locale. +The **`_get_current_locale`** function gets the currently set locale for the thread and returns a locale object representing that locale. -The previous name of this function, **__get_current_locale** (with two leading underscores) has been deprecated. +The previous name of this function, **`__get_current_locale`** (with two leading underscores) has been deprecated. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_current_locale**|\| +| Routine | Required header | +|---|---| +| **`_get_current_locale`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/get-daylight.md b/docs/c-runtime-library/reference/get-daylight.md index ac94af291a..6cba686071 100644 --- a/docs/c-runtime-library/reference/get-daylight.md +++ b/docs/c-runtime-library/reference/get-daylight.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_daylight" title: "_get_daylight" ms.date: "4/2/2020" api_name: ["__daylight", "_get_daylight", "_o___daylight", "_o__get_daylight"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["get_daylight", "_get_daylight"] +f1_keywords: ["TIME/_get_daylight", "_get_daylight", "get_daylight", "__daylight"] helpviewer_keywords: ["get_daylight function", "daylight saving time offset", "_get_daylight function"] ms.assetid: f85a6ba3-e187-4ca7-aed7-ffc694c8ac4c --- -# _get_daylight +# `_get_daylight` Retrieves the daylight saving time offset in hours. @@ -22,35 +22,35 @@ error_t _get_daylight( int* hours ); ### Parameters -*hours*
+*`hours`*\ The offset in hours of daylight saving time. -## Return Value +## Return value -Zero if successful or an **errno** value if an error occurs. +Zero if successful or an `errno` value if an error occurs. ## Remarks -The **_get_daylight** function retrieves the number of hours in daylight saving time as an integer. If daylight saving time is in effect, the default offset is one hour (although a few regions do observe a two-hour offset). +The **`_get_daylight`** function retrieves the number of hours in daylight saving time as an integer. If daylight saving time is in effect, the default offset is one hour (although a few regions do observe a two-hour offset). -If *hours* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If *`hours`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -We recommend you use this function instead of the macro **_daylight** or the deprecated function **__daylight**. +We recommend you use this function instead of the macro `_daylight` or the deprecated function `__daylight`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_daylight**|\| +| Routine | Required header | +|---|---| +| **`_get_daylight`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
-[_get_dstbias](get-dstbias.md)
-[_get_timezone](get-timezone.md)
-[_get_tzname](get-tzname.md)
+[Time management](../time-management.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md)\ +[`_get_dstbias`](get-dstbias.md)\ +[`_get_timezone`](get-timezone.md)\ +[`_get_tzname`](get-tzname.md) diff --git a/docs/c-runtime-library/reference/get-doserrno.md b/docs/c-runtime-library/reference/get-doserrno.md index 03eaa6b369..6763377e2e 100644 --- a/docs/c-runtime-library/reference/get-doserrno.md +++ b/docs/c-runtime-library/reference/get-doserrno.md @@ -3,16 +3,16 @@ description: "Learn more about: _get_doserrno" title: "_get_doserrno" ms.date: "4/2/2020" api_name: ["_get_doserrno", "_o__get_doserrno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_doserrno", "get_doserrno"] helpviewer_keywords: ["get_doserrno function", "_get_doserrno function"] ms.assetid: 7fec7be3-6e39-4181-846b-8ef24489361c --- -# _get_doserrno +# `_get_doserrno` -Gets the error value returned by the operating system before it is translated into an **errno** value. +Gets the error value returned by the operating system before it's translated into an `errno` value. ## Syntax @@ -24,32 +24,32 @@ errno_t _get_doserrno( ### Parameters -*pValue*
-A pointer to an integer to be filled with the current value of the **_doserrno** global macro. +*`pValue`*\ +A pointer to an integer to be filled with the current value of the `_doserrno` global macro. -## Return Value +## Return value -If **_get_doserrno** succeeds, it returns zero; if it fails, it returns an error code. If *pValue* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If **`_get_doserrno`** succeeds, it returns zero; if it fails, it returns an error code. If *`pValue`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -The **_doserrno** global macro is set to zero during CRT initialization, before process execution begins. It is set to the operating-system error value returned by any system-level function call that returns an operating-system error, and it is never reset to zero during execution. When you write code to check the error value returned by a function, always clear **_doserrno** by using [_set_doserrno](set-doserrno.md) before the function call. Because another function call may overwrite **_doserrno**, check the value by using **_get_doserrno** immediately after the function call. +The `_doserrno` global macro is set to zero during CRT initialization, before process execution begins. It's set to the operating-system error value returned by any system-level function call that returns an operating-system error, and it's never reset to zero during execution. When you write code to check the error value returned by a function, always clear `_doserrno` by using [`_set_doserrno`](set-doserrno.md) before the function call. Because another function call may overwrite `_doserrno`, check the value by using **`_get_doserrno`** immediately after the function call. -We recommend [_get_errno](get-errno.md) instead of **_get_doserrno** for portable error codes. +We recommend [`_get_errno`](get-errno.md) instead of **`_get_doserrno`** for portable error codes. -Possible values of **_doserrno** are defined in \. +Possible values of `_doserrno` are defined in \. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_get_doserrno**|\, \ (C++)|\, \ (C++)| +| Routine | Required header | Optional header | +|---|---|---| +| **`_get_doserrno`** | \, \ (C++) | \, \ (C++) | -**_get_doserrno** is a Microsoft extension. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_get_doserrno`** is a Microsoft extension. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_set_doserrno](set-doserrno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_set_doserrno`](set-doserrno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/get-dstbias.md b/docs/c-runtime-library/reference/get-dstbias.md index 3353e92cf3..8aa4be6682 100644 --- a/docs/c-runtime-library/reference/get-dstbias.md +++ b/docs/c-runtime-library/reference/get-dstbias.md @@ -3,7 +3,7 @@ description: "Learn more about: _get_dstbias" title: "_get_dstbias" ms.date: "4/2/2020" api_name: ["_get_dstbias", "__dstbias", "_o___dstbias", "_o__get_dstbias"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__dstbias", "_get_dstbias", "get_dstbias"] @@ -24,32 +24,32 @@ error_t _get_dstbias( long* seconds ); *`seconds`*\ The offset in seconds of daylight saving time. -## Return Value +## Return value -Zero if successful or an **`errno`** value if an error occurs. +Zero if successful or an `errno` value if an error occurs. ## Remarks The **`_get_dstbias`** function retrieves the number of seconds in daylight saving time as an integer. If daylight saving time is in effect, the default offset is 3600 seconds, which is the number of seconds in one hour (though a few regions do observe a two-hour offset). -If *`seconds`* is **`NULL`**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns **`EINVAL`**. +If *`seconds`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. We recommend you use this function instead of the macro **`_dstbias`** or the deprecated function **`__dstbias`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_get_dstbias`**|``| +| Routine | Required header | +|---|---| +| **`_get_dstbias`** | `` | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)\ -[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)\ +[Time management](../time-management.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md)\ [`_get_daylight`](get-daylight.md)\ [`_get_timezone`](get-timezone.md)\ [`_get_tzname`](get-tzname.md) diff --git a/docs/c-runtime-library/reference/get-errno.md b/docs/c-runtime-library/reference/get-errno.md index 70e4ff0347..746db821f7 100644 --- a/docs/c-runtime-library/reference/get-errno.md +++ b/docs/c-runtime-library/reference/get-errno.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_errno" title: "_get_errno" ms.date: "4/2/2020" api_name: ["_get_errno", "_o__get_errno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_errno"] helpviewer_keywords: ["get_errno function", "errno global variable", "_get_errno function"] ms.assetid: b3fd5ebc-f41b-4314-a2f4-2f2d79d6e740 --- -# _get_errno +# `_get_errno` Gets the current value of the errno global variable. @@ -24,18 +24,18 @@ errno_t _get_errno( ### Parameters -*pValue*
-A pointer to an integer to be filled with the current value of the **errno** variable. +*`pValue`*\ +A pointer to an integer to be filled with the current value of the `errno` variable. -## Return Value +## Return value -Returns zero if successful; an error code on failure. If *pValue* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Returns zero if successful; an error code on failure. If *`pValue`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -Possible values of **errno** are defined in Errno.h. Also, see [errno Constants](../../c-runtime-library/errno-constants.md). +Possible values of `errno` are defined in Errno.h. Also, see [`errno` constants](../errno-constants.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Example @@ -65,13 +65,13 @@ fyi, ENOENT = 2 ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_get_errno**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_get_errno`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_set_errno](set-errno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_set_errno`](set-errno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md b/docs/c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md index 85b5240762..13cf4ff6ab 100644 --- a/docs/c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md +++ b/docs/c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md @@ -10,7 +10,7 @@ f1_keywords: ["_get_FMA3_enable", "_set_FMA3_enable", "math/_get_FMA3_enable", " helpviewer_keywords: ["_get_FMA3_enable", "_set_FMA3_enable"] ms.assetid: 4c1dc4bc-e86b-451b-9211-5a2ba6c98ee4 --- -# _get_FMA3_enable, _set_FMA3_enable +# `_get_FMA3_enable`, `_set_FMA3_enable` Gets or sets a flag that specifies whether the transcendental math floating-point library functions use FMA3 instructions in code compiled for X64 platforms. @@ -23,30 +23,30 @@ int _get_FMA3_enable(); ### Parameters -*flag*
-Set to 1 to enable the FMA3 implementations of the transcendental math floating-point library functions on X64 platforms, or to 0 to use the implementations that do not use FMA3 instructions. +*`flag`*\ +Set to 1 to enable the FMA3 implementations of the transcendental math floating-point library functions on X64 platforms, or to 0 to use the implementations that don't use FMA3 instructions. -## Return Value +## Return value A non-zero value if the FMA3 implementations of the transcendental math floating-point library functions are enabled. Otherwise, zero. ## Remarks -Use the **_set_FMA3_enable** function to enable or disable the use of FMA3 instructions in the transcendental math floating-point functions in the CRT library. The return value reflects the implementation in use after the change. If the CPU does not support FMA3 instructions, this function cannot enable them in the library, and the return value is zero. Use **_get_FMA3_enable** to get the current state of the library. By default, on X64 platforms, the CRT startup code detects whether the CPU supports FMA3 instructions, and enables or disables the FMA3 implementations in the library. +Use the **`_set_FMA3_enable`** function to enable or disable the use of FMA3 instructions in the transcendental math floating-point functions in the CRT library. The return value reflects the implementation in use after the change. If the CPU doesn't support FMA3 instructions, this function can't enable them in the library, and the return value is zero. Use **`_get_FMA3_enable`** to get the current state of the library. By default, on X64 platforms, the CRT startup code detects whether the CPU supports FMA3 instructions, and enables or disables the FMA3 implementations in the library. -Because the FMA3 implementations use different algorithms, slight differences in the result of computations may be observable when the FMA3 implementations are enabled or disabled, or between computers that do or do not support FMA3. For more information, see [Floating-point migration issues](../../porting/floating-point-migration-issues.md). +The FMA3 implementations use different algorithms. Slight differences in the result of computations may be observable when the FMA3 implementations are enabled or disabled. Differences may also be observable between computers that do or don't support FMA3. For more information, see [Floating-point migration issues](../../porting/floating-point-migration-issues.md). ## Requirements -The **_set_FMA3_enable** and **_get_FMA3_enable** functions are only available in the X64 versions of the CRT. +The **`_set_FMA3_enable`** and **`_get_FMA3_enable`** functions are only available in the X64 versions of the CRT. -|Routine|Required header| -|-------------|---------------------| -|**_set_FMA3_enable**, **_get_FMA3_enable**| C: \
C++: \ or \| +| Routine | Required header | +|---|---| +| **`_set_FMA3_enable`**, **`_get_FMA3_enable`** | C: \
C++: \ or \ | -The **_set_FMA3_enable** and **_get_FMA3_enable** functions are Microsoft-specific. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_set_FMA3_enable`** and **`_get_FMA3_enable`** functions are Microsoft-specific. For compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-point support](../../c-runtime-library/floating-point-support.md)
-[Floating-point migration issues](../../porting/floating-point-migration-issues.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Floating-point migration issues](../../porting/floating-point-migration-issues.md) diff --git a/docs/c-runtime-library/reference/get-fmode.md b/docs/c-runtime-library/reference/get-fmode.md index 7d46dbd3ef..7f0cc9ab0a 100644 --- a/docs/c-runtime-library/reference/get-fmode.md +++ b/docs/c-runtime-library/reference/get-fmode.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_fmode" title: "_get_fmode" ms.date: "4/2/2020" api_name: ["_get_fmode", "_o__get_fmode"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["get_fmode", "_get_fmode"] helpviewer_keywords: ["_get_fmode function", "file translation [C++], default mode", "get_fmode function"] ms.assetid: 22ea70e2-b9b5-422d-b514-64f4beaea45c --- -# _get_fmode +# `_get_fmode` Gets the default file translation mode for file I/O operations. @@ -24,34 +24,34 @@ errno_t _get_fmode( ### Parameters -*pmode*
-A pointer to an integer to be filled with the current default mode: **_O_TEXT** or **_O_BINARY**. +*`pmode`*\ +A pointer to an integer to be filled with the current default mode: `_O_TEXT` or `_O_BINARY`. -## Return Value +## Return value -Returns zero if successful; an error code on failure. If *pmode* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **EINVAL**. +Returns zero if successful; an error code on failure. If *`pmode`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `EINVAL`. ## Remarks -The function gets the value of the [_fmode](../../c-runtime-library/fmode.md) global variable. This variable specifies the default file translation mode for both low-level and stream file I/O operations, such as **_open**, **_pipe**, **fopen**, and [freopen](freopen-wfreopen.md). +The function gets the value of the [`_fmode`](../fmode.md) global variable. This variable specifies the default file translation mode for both low-level and stream file I/O operations, such as `_open`, `_pipe`, `fopen`, and [`freopen`](freopen-wfreopen.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_get_fmode**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_get_fmode`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_set_fmode](set-fmode.md). +See the example in [`_set_fmode`](set-fmode.md). ## See also -[_fmode](../../c-runtime-library/fmode.md)
-[_set_fmode](set-fmode.md)
-[_setmode](setmode.md)
-[Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md)
+[`_fmode`](../fmode.md)\ +[`_set_fmode`](set-fmode.md)\ +[`_setmode`](setmode.md)\ +[Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) diff --git a/docs/c-runtime-library/reference/get-heap-handle.md b/docs/c-runtime-library/reference/get-heap-handle.md index 71dd826e5c..b69a578571 100644 --- a/docs/c-runtime-library/reference/get-heap-handle.md +++ b/docs/c-runtime-library/reference/get-heap-handle.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_heap_handle" title: "_get_heap_handle" ms.date: "4/2/2020" api_name: ["_get_heap_handle", "_o__get_heap_handle"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_heap_handle", "get_heap_handle"] helpviewer_keywords: ["heap functions", "memory allocation, heap memory", "_get_heap_handle function", "get_heap_handle function"] ms.assetid: a4d05049-8528-494a-8281-a470d1e1115c --- -# _get_heap_handle +# `_get_heap_handle` Returns the handle of the heap that's used by the C run-time system. @@ -20,23 +20,23 @@ Returns the handle of the heap that's used by the C run-time system. intptr_t _get_heap_handle( void ); ``` -## Return Value +## Return value Returns the handle to the Win32 heap used by the C run-time system. ## Remarks -Use this function if you want to call [HeapSetInformation](/windows/win32/api/heapapi/nf-heapapi-heapsetinformation) and enable the Low Fragmentation Heap on the CRT heap. +Use this function if you want to call [`HeapSetInformation`](/windows/win32/api/heapapi/nf-heapapi-heapsetinformation) and enable the Low Fragmentation Heap on the CRT heap. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_heap_handle**|\| +| Routine | Required header | +|---|---| +| **`_get_heap_handle`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Sample @@ -63,4 +63,4 @@ int main(void) ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md b/docs/c-runtime-library/reference/get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md index 5700abbf17..a6932cf214 100644 --- a/docs/c-runtime-library/reference/get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md +++ b/docs/c-runtime-library/reference/get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_invalid_parameter_handler, _get_thread_loca title: "_get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler" ms.date: "4/2/2020" api_name: ["_get_invalid_parameter_handler", "_get_thread_local_invalid_parameter_handler", "_o__get_invalid_parameter_handler", "_o__get_thread_local_invalid_parameter_handler"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_invalid_parameter_handler", "stdlib/_get_invalid_parameter_handler", "_get_thread_local_invalid_parameter_handler", "stdlib/_get_thread_local_invalid_parameter_handler"] helpviewer_keywords: ["_get_thread_local_invalid_parameter_handler function", "_get_invalid_parameter_handler function"] ms.assetid: a176da0e-38ca-4d99-92bb-b0e2b8072f53 --- -# _get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler +# `_get_invalid_parameter_handler`, `_get_thread_local_invalid_parameter_handler` Gets the function that is called when the CRT detects an invalid argument. @@ -21,13 +21,13 @@ _invalid_parameter_handler _get_invalid_parameter_handler(void); _invalid_parameter_handler _get_thread_local_invalid_parameter_handler(void); ``` -## Return Value +## Return value A pointer to the currently set invalid parameter handler function, or a null pointer if none has been set. ## Remarks -The **_get_invalid_parameter_handler** function gets the currently set global invalid parameter handler. It returns a null pointer if no global invalid parameter handler was set. Similarly, the **_get_thread_local_invalid_parameter_handler** gets the current thread-local invalid parameter handler of the thread it is called on, or a null pointer if no handler was set. For information about how to set global and thread-local invalid parameter handlers, see [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). +The **`_get_invalid_parameter_handler`** function gets the currently set global invalid parameter handler. It returns a null pointer if no global invalid parameter handler was set. Similarly, the **`_get_thread_local_invalid_parameter_handler`** gets the current thread-local invalid parameter handler of the thread it's called on, or a null pointer if no handler was set. For information about how to set global and thread-local invalid parameter handlers, see [`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). The returned invalid parameter handler function pointer has the following type: @@ -41,19 +41,19 @@ typedef void (__cdecl* _invalid_parameter_handler)( ); ``` -For details on the invalid parameter handler, see the prototype in [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). +For details on the invalid parameter handler, see the prototype in [`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_invalid_parameter_handler**, **_get_thread_local_invalid_parameter_handler**|C: \

C++: \ or \| +| Routine | Required header | +|---|---| +| **`_get_invalid_parameter_handler`**, **`_get_thread_local_invalid_parameter_handler`** | C: \

C++: \ or \ | -The **_get_invalid_parameter_handler** and **_get_thread_local_invalid_parameter_handler** functions are Microsoft-specific. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_get_invalid_parameter_handler`** and **`_get_thread_local_invalid_parameter_handler`** functions are Microsoft-specific. For compatibility information, see [Compatibility](../compatibility.md). ## See also -[_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md)
-[Security-Enhanced Versions of CRT Functions](../../c-runtime-library/security-enhanced-versions-of-crt-functions.md)
+[`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md)\ +[Security-enhanced versions of CRT functions](../security-enhanced-versions-of-crt-functions.md) diff --git a/docs/c-runtime-library/reference/get-osfhandle.md b/docs/c-runtime-library/reference/get-osfhandle.md index e2e6dfc186..7f6da86131 100644 --- a/docs/c-runtime-library/reference/get-osfhandle.md +++ b/docs/c-runtime-library/reference/get-osfhandle.md @@ -3,14 +3,13 @@ description: "Learn more about: _get_osfhandle" title: "_get_osfhandle" ms.date: "4/2/2020" api_name: ["_get_osfhandle", "_o__get_osfhandle"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["get_osfhandle", "_get_osfhandle"] helpviewer_keywords: ["operating systems, getting file handles", "get_osfhandle function", "_get_osfhandle function", "file handles [C++], operating system"] -ms.assetid: 0bdd728a-4fd8-410b-8c9f-01a121135196 --- -# _get_osfhandle +# `_get_osfhandle` Retrieves the operating-system file handle that is associated with the specified file descriptor. @@ -24,37 +23,37 @@ intptr_t _get_osfhandle( ### Parameters -*fd*
+*`fd`*\ An existing file descriptor. -## Return Value +## Return value -Returns an operating-system file handle if *fd* is valid. Otherwise, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, it returns **INVALID_HANDLE_VALUE** (-1). It also sets **errno** to **EBADF**, indicating an invalid file handle. To avoid a warning when the result is used as a Win32 file handle, cast it to a **HANDLE** type. +Returns an operating-system file handle if *`fd`* is valid. Otherwise, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, it returns `INVALID_HANDLE_VALUE` (-1). It also sets `errno` to `EBADF`, indicating an invalid file handle. To avoid a warning when the result is used as a Win32 file handle, cast it to a `HANDLE` type. > [!NOTE] -> When **stdin**, **stdout**, and **stderr** aren't associated with a stream (for example, in a Windows application without a console window), the file descriptor values for these streams are returned from [_fileno](fileno.md) as the special value -2. Similarly, if you use a 0, 1, or 2 as the file descriptor parameter instead of the result of a call to **_fileno**, **_get_osfhandle** also returns the special value -2 when the file descriptor is not associated with a stream, and does not set **errno**. However, this is not a valid file handle value, and subsequent calls that attempt to use it are likely to fail. +> When **`stdin`**, **`stdout`**, and **`stderr`** aren't associated with a stream (for example, in a Windows application without a console window), the file descriptor values for these streams are returned from [`_fileno`](fileno.md) as the special value -2. Similarly, if you use a 0, 1, or 2 as the file descriptor parameter instead of the result of a call to **`_fileno`**, **`_get_osfhandle`** also returns the special value -2 when the file descriptor is not associated with a stream, and does not set `errno`. However, this is not a valid file handle value, and subsequent calls that attempt to use it are likely to fail. -For more information about **EBADF** and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about `EBADF` and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -To close a file whose operating system (OS) file handle is obtained by **_get_osfhandle**, call [_close](close.md) on the file descriptor *fd*. Never call **CloseHandle** on the return value of this function. The underlying OS file handle is owned by the *fd* file descriptor, and is closed when [_close](close.md) is called on *fd*. If the file descriptor is owned by a `FILE *` stream, then calling [fclose](fclose-fcloseall.md) on that `FILE *` stream closes both the file descriptor and the underlying OS file handle. In this case, don't call [_close](close.md) on the file descriptor. +To close a file whose operating system (OS) file handle is obtained by **`_get_osfhandle`**, call [`_close`](close.md) on the file descriptor *`fd`*. Never call `CloseHandle` on the return value of this function. The underlying OS file handle is owned by the *`fd`* file descriptor, and is closed when [`_close`](close.md) is called on *`fd`*. If the file descriptor is owned by a `FILE *` stream, then calling [`fclose`](fclose-fcloseall.md) on that `FILE *` stream closes both the file descriptor and the underlying OS file handle. In this case, don't call [`_close`](close.md) on the file descriptor. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_osfhandle**|\| +| Routine | Required header | +|---|---| +| **`_get_osfhandle`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_close](close.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_dup, _dup2](dup-dup2.md)
-[_open, _wopen](open-wopen.md)
-[\_open_osfhandle](open-osfhandle.md) +[File handling](../file-handling.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_dup`, `_dup2`](dup-dup2.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_open_osfhandle`](open-osfhandle.md) diff --git a/docs/c-runtime-library/reference/get-pgmptr.md b/docs/c-runtime-library/reference/get-pgmptr.md index b2197194be..a284ad7028 100644 --- a/docs/c-runtime-library/reference/get-pgmptr.md +++ b/docs/c-runtime-library/reference/get-pgmptr.md @@ -3,16 +3,16 @@ description: "Learn more about: _get_pgmptr" title: "_get_pgmptr" ms.date: "4/2/2020" api_name: ["_get_pgmptr", "_o__get_pgmptr"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["get_pgmptr", "_get_pgmptr"] helpviewer_keywords: ["get_pgmptr function", "_get_pgmptr function", "pgmptr global variable", "_pgmptr global variable"] ms.assetid: 29f16a9f-a685-4721-add3-7fad4f67eece --- -# _get_pgmptr +# `_get_pgmptr` -Gets the current value of the **_pgmptr** global variable. +Gets the current value of the `_pgmptr` global variable. ## Syntax @@ -24,27 +24,27 @@ errno_t _get_pgmptr( ### Parameters -*pValue*
-A pointer to a string to be filled with the current value of the **_pgmptr** variable. +*`pValue`*\ +A pointer to a string to be filled with the current value of the `_pgmptr` variable. -## Return Value +## Return value -Returns zero if successful; an error code on failure. If *pValue* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Returns zero if successful; an error code on failure. If *`pValue`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -Only call **_get_pgmptr** if your program has a narrow entry point, like **main()** or **WinMain()**. The **_pgmptr** global variable contains the full path to the executable associated with the process. For more information, see [_pgmptr, _wpgmptr](../../c-runtime-library/pgmptr-wpgmptr.md). +Only call **`_get_pgmptr`** if your program has a narrow entry point, like **main()** or **WinMain()**. The `_pgmptr` global variable contains the full path to the executable associated with the process. For more information, see [`_pgmptr`, `_wpgmptr`](../pgmptr-wpgmptr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_pgmptr**|\| +| Routine | Required header | +|---|---| +| **`_get_pgmptr`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_wpgmptr](get-wpgmptr.md)
+[`_get_wpgmptr`](get-wpgmptr.md) diff --git a/docs/c-runtime-library/reference/get-printf-count-output.md b/docs/c-runtime-library/reference/get-printf-count-output.md index fb63759e5c..dfa9d74278 100644 --- a/docs/c-runtime-library/reference/get-printf-count-output.md +++ b/docs/c-runtime-library/reference/get-printf-count-output.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["get_printf_count_output", "_get_printf_count_output"] helpviewer_keywords: ["%n format", "get_printf_count_output function", "_get_printf_count_output function"] --- -# _get_printf_count_output +# `_get_printf_count_output` -Indicates whether [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)-family functions support the **%n** format. +Indicates whether [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)-family functions support the **%n** format. ## Syntax @@ -19,29 +19,29 @@ Indicates whether [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprin int _get_printf_count_output(); ``` -## Return Value +## Return value -Non-zero if **%n** is supported, 0 if **%n** is not supported. +Non-zero if **`%n`** is supported; 0 if **`%n`** isn't supported. ## Remarks -If **%n** is not supported (the default), encountering **%n** in the format string of any of the **printf** functions will invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If **%n** support is enabled (see [_set_printf_count_output](set-printf-count-output.md)) then **%n** will behave as described in [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +If **`%n`** isn't supported (the default), any **`%n`** found in the format string of one of the `printf` functions invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If **`%n`** support is enabled (see [`_set_printf_count_output`](set-printf-count-output.md)), then **`%n`** behaves as described in [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_printf_count_output**|\| +| Routine | Required header | +|---|---| +| **`_get_printf_count_output`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_set_printf_count_output](set-printf-count-output.md). +See the example for [`_set_printf_count_output`](set-printf-count-output.md). ## See also -[_set_printf_count_output](set-printf-count-output.md)
+[`_set_printf_count_output`](set-printf-count-output.md) diff --git a/docs/c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md b/docs/c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md index 8eea483df1..4f49114531 100644 --- a/docs/c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md +++ b/docs/c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_purecall_handler, _set_purecall_handler" title: "_get_purecall_handler, _set_purecall_handler" ms.date: "1/14/2021" api_name: ["_set_purecall_handler", "_set_purecall_handler_m", "_get_purecall_handler"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_purecall_handler", "_set_purecall_handler_m", "set_purecall_handler_m", "set_purecall_handler", "stdlib/_set_purecall_handler", "stdlib/_get_purecall_handler", "_get_purecall_handler"] helpviewer_keywords: ["_set_purecall_handler function", "set_purecall_handler function", "purecall_handler", "set_purecall_handler_m function", "_purecall_handler", "_set_purecall_handler_m function", "_get_purecall_handler function"] ms.assetid: 2759b878-8afa-4129-86e7-72afc2153d9c --- -# _get_purecall_handler, _set_purecall_handler +# `_get_purecall_handler`, `_set_purecall_handler` Gets or sets the error handler for a pure virtual function call. @@ -26,30 +26,30 @@ _purecall_handler __cdecl _set_purecall_handler( ### Parameters -*function*
-The function to be called when a pure virtual function is called. A **_purecall_handler** function must have a void return type. +*`function`*\ +The function to be called when a pure virtual function is called. A `_purecall_handler` function must have a void return type. -## Return Value +## Return value -The previous **_purecall_handler**. Returns **`nullptr`** if there was no previous handler. +The previous `_purecall_handler`. Returns **`nullptr`** if there was no previous handler. ## Remarks -The **_get_purecall_handler** and **_set_purecall_handler** functions are Microsoft-specific and apply only to C++ code. +The **`_get_purecall_handler`** and **`_set_purecall_handler`** functions are Microsoft-specific and apply only to C++ code. -A call to a pure virtual function is an error because it has no implementation. By default, the compiler generates code to invoke an error handler function when a pure virtual function is called, which terminates the program. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the **_purecall_handler** signature, then use **_set_purecall_handler** to make it the current handler. +A call to a pure virtual function is an error because it has no implementation. By default, the compiler generates code to invoke an error handler function when a pure virtual function is called, which terminates the program. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the `_purecall_handler` signature, then use **`_set_purecall_handler`** to make it the current handler. -Because there is only one **_purecall_handler** for each process, when you call **_set_purecall_handler** it immediately impacts all threads. The last caller on any thread sets the handler. +Because there's only one `_purecall_handler` for each process, when you call **`_set_purecall_handler`** it immediately impacts all threads. The last caller on any thread sets the handler. -To restore the default behavior, call **_set_purecall_handler** by using a **`nullptr`** argument. +To restore the default behavior, call **`_set_purecall_handler`** by using a **`nullptr`** argument. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_purecall_handler**, **_set_purecall_handler**|\ or \| +| Routine | Required header | +|---|---| +| **`_get_purecall_handler`**, **`_set_purecall_handler`** | \ or \ | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -102,5 +102,5 @@ In _purecall_handler. ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[_purecall](purecall.md)
+[Error handling](../error-handling-crt.md)\ +[`_purecall`](purecall.md) diff --git a/docs/c-runtime-library/reference/get-terminate.md b/docs/c-runtime-library/reference/get-terminate.md index 7d26d90222..a9fe9b856f 100644 --- a/docs/c-runtime-library/reference/get-terminate.md +++ b/docs/c-runtime-library/reference/get-terminate.md @@ -3,16 +3,16 @@ description: "Learn more about: _get_terminate" title: "_get_terminate" ms.date: "4/2/2020" api_name: ["_get_terminate", "_o__get_terminate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["get_terminate", "_get_terminate", "__get_terminate"] helpviewer_keywords: ["__get_terminate function", "get_terminate function", "_get_terminate function"] ms.assetid: c8f168c4-0ad5-4832-a522-dd1ef383c208 --- -# _get_terminate +# `_get_terminate` -Returns the termination routine to be called by **terminate**. +Returns the termination routine to be called by `terminate`. ## Syntax @@ -20,26 +20,26 @@ Returns the termination routine to be called by **terminate**. terminate_function _get_terminate( void ); ``` -## Return Value +## Return value -Returns a pointer to the function registered by [set_terminate](set-terminate-crt.md). If no function has been set, the return value may be used to restore the default behavior; this value may be **NULL**. +Returns a pointer to the function registered by [`set_terminate`](set-terminate-crt.md). If no function has been set, the return value may be used to restore the default behavior; this value may be `NULL`. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_terminate**|\| +| Routine | Required header | +|---|---| +| **`_get_terminate`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[set_unexpected](set-unexpected-crt.md)
-[terminate](terminate-crt.md)
-[unexpected](unexpected-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`terminate`](terminate-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/get-timezone.md b/docs/c-runtime-library/reference/get-timezone.md index b8877e2b24..9b273ddf65 100644 --- a/docs/c-runtime-library/reference/get-timezone.md +++ b/docs/c-runtime-library/reference/get-timezone.md @@ -3,14 +3,14 @@ description: "Learn more about: _get_timezone" title: "_get_timezone" ms.date: "4/2/2020" api_name: ["_get_timezone", "_o__get_timezone"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_timezone", "get_timezone"] helpviewer_keywords: ["time zones", "get_timezone function", "_get_timezone function"] ms.assetid: 30ab0838-0ae9-4a2f-bfe6-a49ee443b21e --- -# _get_timezone +# `_get_timezone` Retrieves the difference in seconds between coordinated universal time (UTC) and local time. @@ -24,33 +24,33 @@ error_t _get_timezone( ### Parameters -*seconds*
+*`seconds`*\ The difference in seconds between UTC and local time. -## Return Value +## Return value -Zero if successful or an **errno** value if an error occurs. +Zero if successful or an `errno` value if an error occurs. ## Remarks -The **_get_timezone** function retrieves the difference in seconds between UTC and local time as an integer. The default value is 28,800 seconds, for Pacific Standard Time (eight hours behind UTC). +The **`_get_timezone`** function retrieves the difference in seconds between UTC and local time as an integer. The default value is 28,800 seconds, for Pacific Standard Time (eight hours behind UTC). If you don't want the default value, call _tzset first to initialize the timezone. -If *seconds* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If *`seconds`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_timezone**|\| +| Routine | Required header | +|---|---| +| **`_get_timezone`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
-[_get_daylight](get-daylight.md)
-[_get_dstbias](get-dstbias.md)
-[_get_tzname](get-tzname.md)
+[Time management](../time-management.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md)\ +[`_get_daylight`](get-daylight.md)\ +[`_get_dstbias`](get-dstbias.md)\ +[`_get_tzname`](get-tzname.md) diff --git a/docs/c-runtime-library/reference/get-tzname.md b/docs/c-runtime-library/reference/get-tzname.md index 893bb54ff3..27d14164ee 100644 --- a/docs/c-runtime-library/reference/get-tzname.md +++ b/docs/c-runtime-library/reference/get-tzname.md @@ -1,18 +1,17 @@ --- description: "Learn more about: _get_tzname" title: "_get_tzname" -ms.date: "4/2/2020" +ms.date: 08/23/2022 api_name: ["_get_tzname", "_o__get_tzname"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_get_tzname", "get_tzname"] helpviewer_keywords: ["_get_tzname function", "time zones", "get_tzname function"] -ms.assetid: df0065ff-095f-4237-832c-2fe9ab913875 --- -# _get_tzname +# `_get_tzname` -Retrieves the character string representation of the time zone name or the daylight standard time zone name (DST). +Retrieves the character string representation of the time zone name or the daylight standard time (DST) zone name. ## Syntax @@ -27,51 +26,62 @@ errno_t _get_tzname( ### Parameters -*pReturnValue*
-The string length of *timeZoneName* including a null terminator. +*`pReturnValue`*\ +The string length of *`timeZoneName`* including a `NULL` terminator. -*timeZoneName*
-The address of a character string for the representation of the time zone name or the daylight standard time zone name (DST), depending on *index*. +*`timeZoneName`*\ +The address of a character string for the representation of the time zone name or the daylight standard time zone name (DST), depending on *`index`*. -*sizeInBytes*
-The size of the *timeZoneName* character string in bytes. +*`sizeInBytes`*\ +The size of the *`timeZoneName`* character string in bytes. -*index*
-The index of one of the two time zone names to retrieve. +*`index`*\ +The *`index`* of one of the two time zone names to retrieve. -|*index*|Contents of *timeZoneName*|*timeZoneName* default value| -|-|-|-| -|0|Time zone name|"PST"| -|1|Daylight standard time zone name|"PDT"| -|> 1 or < 0|**errno** set to **EINVAL**|not modified| +| *`index`* | Contents of *`timeZoneName`* | *`timeZoneName`* default value | +|---|---|---| +| 0 | Time zone name | `"PST"` | +| 1 | Daylight standard time zone name | `"PDT"` | +| > 1 or < 0 | `errno` set to `EINVAL` | not modified | -Unless the values are explicitly changed during run time, the default values are "PST" and "PDT" respectively. +Unless explicitly updated during runtime, `"PST"` is returned for the standard time zone and `"PDT"` for the daylight standard time zone. For more information, see the [Remarks](#remarks). -## Return Value +The time zone string isn't guaranteed to be the same between OS releases. Official time zone names can and do change. -Zero if successful, otherwise an **errno** type value. +## Return value -If either *timeZoneName* is **NULL**, or *sizeInBytes* is zero or less than zero (but not both), an invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Zero if successful, otherwise an `errno` type value. -### Error Conditions +If either *`timeZoneName`* is `NULL`, or *`sizeInBytes`* is zero or less than zero (but not both), an invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -|*pReturnValue*|*timeZoneName*|*sizeInBytes*|*index*|Return value|Contents of *timeZoneName*| -|--------------------|--------------------|-------------------|-------------|------------------|--------------------------------| -|size of TZ name|**NULL**|0|0 or 1|0|not modified| -|size of TZ name|any|> 0|0 or 1|0|TZ name| -|not modified|**NULL**|> 0|any|**EINVAL**|not modified| -|not modified|any|zero|any|**EINVAL**|not modified| -|not modified|any|> 0|> 1|**EINVAL**|not modified| +### Error conditions + +| *`pReturnValue`* | *`timeZoneName`* | *`sizeInBytes`* | *`index`* | Return value | Contents of *`timeZoneName`* | +|---|---|---|---|---|---| +| size of TZ name | `NULL` | 0 | 0 or 1 | 0 | not modified | +| size of TZ name | any | > 0 | 0 or 1 | 0 | TZ name | +| not modified | `NULL` | > 0 | any | `EINVAL` | not modified | +| not modified | any | zero | any | `EINVAL` | not modified | +| not modified | any | > 0 | > 1 | `EINVAL` | not modified | ## Remarks -The **_get_tzname** function retrieves the character string representation of the current time zone name or the daylight standard time zone name (DST) into the address of *timeZoneName* depending on the index value, along with the size of the string in *pReturnValue*. If *timeZoneName* is **NULL** and *sizeInBytes* is zero, the size of the string required to hold the specified time zone and a terminating null in bytes is returned in *pReturnValue*. The index values must be either 0 for standard time zone or 1 for daylight standard time zone; any other values of *index* have undetermined results. +The `_get_tzname` function retrieves the character string representation of the current time zone name or the daylight standard time zone name (DST) into the address of *`timeZoneName`* depending on the *`index`* value, along with the size of the string in *`pReturnValue`*. If *`timeZoneName`* is `NULL` and *`sizeInBytes`* is zero, the size of the string in bytes required to hold both the specified time zone, and a terminating `NULL`, is returned in *`pReturnValue`*. + +The *`index`* values must be either 0 for standard time zone or 1 for daylight standard time zone; any other values have undetermined results. + +By default, `"PST"` is returned for the standard time zone and `"PDT"` for the daylight standard time zone. The true time zone name is updated the first time it's needed by a function that requires time zone information, such as [`strftime`](strftime-wcsftime-strftime-l-wcsftime-l.md), [`ftime`](ftime-ftime32-ftime64.md), [`ftime_s`](ftime-s-ftime32-s-ftime64-s.md), [`mktime`](mktime-mktime32-mktime64.md), [`localtime`](localtime-localtime32-localtime64.md), and others. If a function that doesn't require time zone information isn't called prior to calling `_get_tzname`, the default values are returned unless you first explicitly update them using one of the functions mentioned, or by a call to [`tzset`](tzset.md). Also, if the `TZ` environment variable is set, it takes precedence over the time zone name reported by the OS. Even in this case, one of the functions mentioned above must be called before `_get_tzname` is called or the default time zone value will be returned. For more information about the `TZ` environment variable and the CRT, see [`_tzset`](tzset.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +> [!WARNING] +> The time zone string is not guaranteed to be the same between OS releases. Official time zone names can and do change. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Example -This sample calls **_get_tzname** to get the required buffer size to display the current Daylight standard time zone name, allocates a buffer of that size, calls **_get_tzname** again to load the name in the buffer, and prints it to the console. +This sample calls `_get_tzname` to get the required buffer size to display the current Daylight standard time zone name, allocates a buffer of that size, calls `_get_tzname` again to load the name in the buffer, and prints it to the console. + +It also calls `_tzset()` to cause the OS to update the time zone information before calling `_get_tzname()`. Otherwise, the default values are used. ```C // crt_get_tzname.c @@ -80,7 +90,7 @@ This sample calls **_get_tzname** to get the required buffer size to display the #include #include -enum TZINDEX { +enum TZindex { STD, DST }; @@ -90,17 +100,25 @@ int main() size_t tznameSize = 0; char * tznameBuffer = NULL; + _tzset(); // Update the time zone information + // Get the size of buffer required to hold DST time zone name if (_get_tzname(&tznameSize, NULL, 0, DST)) + { return 1; // Return an error value if it failed + } // Allocate a buffer for the name if (NULL == (tznameBuffer = (char *)(malloc(tznameSize)))) + { return 2; // Return an error value if it failed + } // Load the name in the buffer if (_get_tzname(&tznameSize, tznameBuffer, tznameSize, DST)) + { return 3; // Return an error value if it failed + } printf_s("The current Daylight standard time zone name is %s.\n", tznameBuffer); return 0; @@ -110,21 +128,21 @@ int main() ### Output ```Output -The current Daylight standard time zone name is PDT. +The current Daylight standard time zone name is Pacific Daylight Time. ``` ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_tzname**|\| +| Routine | Required header | +|---|---| +| `_get_tzname` | `` | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
-[_get_daylight](get-daylight.md)
-[_get_dstbias](get-dstbias.md)
-[_get_timezone](get-timezone.md)
+[Time management](../time-management.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md)\ +[`_get_daylight`](get-daylight.md)\ +[`_get_dstbias`](get-dstbias.md)\ +[`_get_timezone`](get-timezone.md) diff --git a/docs/c-runtime-library/reference/get-unexpected.md b/docs/c-runtime-library/reference/get-unexpected.md index e4f12347df..7f30743ec9 100644 --- a/docs/c-runtime-library/reference/get-unexpected.md +++ b/docs/c-runtime-library/reference/get-unexpected.md @@ -3,7 +3,7 @@ description: "Learn more about: _get_unexpected" title: "_get_unexpected" ms.date: "1/14/2021" api_name: ["_get_unexpected"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__get_unexpected", "_get_unexpected", "get_unexpected"] @@ -20,22 +20,22 @@ Returns the termination routine to be called by **`unexpected`**. unexpected_function _get_unexpected( void ); ``` -## Return Value +## Return value -Returns a pointer to the function registered by [`set_unexpected`](set-unexpected-crt.md). If no function has been set, the return value may be used to restore the default behavior; this value may be **`NULL`**. +Returns a pointer to the function registered by [`set_unexpected`](set-unexpected-crt.md). If no function has been set, the return value may be used to restore the default behavior; this value may be `NULL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_get_unexpected`**|\| +| Routine | Required header | +|---|---| +| **`_get_unexpected`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[`abort`](abort.md)
-[`set_terminate`](set-terminate-crt.md)
-[`terminate`](terminate-crt.md)
-[`unexpected`](unexpected-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`set_terminate`](set-terminate-crt.md)\ +[`terminate`](terminate-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/get-wpgmptr.md b/docs/c-runtime-library/reference/get-wpgmptr.md index eaa80ed529..29bb0b279e 100644 --- a/docs/c-runtime-library/reference/get-wpgmptr.md +++ b/docs/c-runtime-library/reference/get-wpgmptr.md @@ -3,16 +3,16 @@ description: "Learn more about: _get_wpgmptr" title: "_get_wpgmptr" ms.date: "4/2/2020" api_name: ["_get_wpgmptr", "_o__get_wpgmptr"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["get_wpgmptr", "_get_wpgmptr"] helpviewer_keywords: ["_wpgmptr global variable", "get_wpgmptr function", "wpgmptr global variable", "_get_wpgmptr function"] ms.assetid: a77cdd13-2303-4b7c-9a60-8debdbef2011 --- -# _get_wpgmptr +# `_get_wpgmptr` -Gets the current value of the **_wpgmptr** global variable. +Gets the current value of the `_wpgmptr` global variable. ## Syntax @@ -24,27 +24,27 @@ errno_t _get_wpgmptr( ### Parameters -*pValue*
-A pointer to a string to be filled with the current value of the **_wpgmptr** variable. +*`pValue`*\ +A pointer to a string to be filled with the current value of the `_wpgmptr` variable. -## Return Value +## Return value -Returns zero if successful; an error code on failure. If *pValue* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Returns zero if successful; an error code on failure. If *`pValue`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -Only call **_get_wpgmptr** if your program has a wide entry point, like **wmain()** or **wWinMain()**. The **_wpgmptr** global variable contains the full path to the executable associated with the process as a wide-character string. For more information, see [_pgmptr, _wpgmptr](../../c-runtime-library/pgmptr-wpgmptr.md). +Only call **`_get_wpgmptr`** if your program has a wide entry point, like **wmain()** or **wWinMain()**. The `_wpgmptr` global variable contains the full path to the executable associated with the process as a wide-character string. For more information, see [`_pgmptr`, `_wpgmptr`](../pgmptr-wpgmptr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_get_wpgmptr**|\| +| Routine | Required header | +|---|---| +| **`_get_wpgmptr`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_pgmptr](get-pgmptr.md)
+[`_get_pgmptr`](get-pgmptr.md) diff --git a/docs/c-runtime-library/reference/getc-getwc.md b/docs/c-runtime-library/reference/getc-getwc.md index 78d32c4f8e..1a8732167d 100644 --- a/docs/c-runtime-library/reference/getc-getwc.md +++ b/docs/c-runtime-library/reference/getc-getwc.md @@ -3,14 +3,14 @@ description: "Learn more about: getc, getwc" title: "getc, getwc" ms.date: "4/2/2020" api_name: ["getwc", "getc", "_o_getc", "_o_getwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_gettc", "getwc", "_gettchar", "getc"] helpviewer_keywords: ["characters, reading", "_gettc function", "getwchar function", "streams, reading characters from", "reading characters from streams", "getc function", "getwc function", "gettc function"] ms.assetid: 354ef514-d0c7-404b-92f5-995f6a834bb3 --- -# getc, getwc +# `getc`, `getwc` Read a character from a stream. @@ -27,44 +27,44 @@ wint_t getwc( ### Parameters -*stream*
+*`stream`*\ Input stream. -## Return Value +## Return value -Returns the character read. To indicate a read error or end-of-file condition, **getc** returns **EOF**, and **getwc** returns **WEOF**. For **getc**, use **ferror** or **feof** to check for an error or for end of file. If *stream* is **NULL**, **getc** and **getwc** invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** (or **WEOF** for **getwc**) and set **errno** to **EINVAL**. +Returns the character read. To indicate a read error or end-of-file condition, **`getc`** returns `EOF`, and **`getwc`** returns `WEOF`. For **`getc`**, use `ferror` or `feof` to check for an error or for end of file. If *`stream`* is `NULL`, **`getc`** and **`getwc`** invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` (or `WEOF` for **`getwc`**), and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each routine reads a single character from a file at the current position and increments the associated file pointer (if defined) to point to the next character. The file is associated with *stream*. +Each routine reads a single character from a file at the current position and increments the associated file pointer (if defined) to point to the next character. The file is associated with *`stream`*. -These functions lock the calling thread and are therefore thread-safe. For a non-locking version, see [_getc_nolock, _getwc_nolock](getc-nolock-getwc-nolock.md). +These functions lock the calling thread and are therefore thread-safe. For a non-locking version, see [`_getc_nolock`, `_getwc_nolock`](getc-nolock-getwc-nolock.md). Routine-specific remarks follow. -|Routine|Remarks| -|-------------|-------------| -|**getc**|Same as **fgetc**, but implemented as a function and as a macro.| -|**getwc**|Wide-character version of **getc**. Reads a multibyte character or a wide character according to whether *stream* is opened in text mode or binary mode.| +| Routine | Remarks | +|---|---| +| **`getc`** | Same as `fgetc`, but implemented as a function and as a macro. | +| **`getwc`** | Wide-character version of **`getc`**. Reads a multibyte character or a wide character according to whether *`stream`* is opened in text mode or binary mode. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_gettc**|**getc**|**getc**|**getwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettc` | **`getc`** | **`getc`** | **`getwc`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**getc**|\| -|**getwc**|\ or \| +| Routine | Required header | +|---|---| +| **`getc`** | \ | +| **`getwc`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -118,8 +118,8 @@ Input was: Line one. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[_getch, _getwch](getch-getwch.md)
-[putc, putwc](putc-putwc.md)
-[ungetc, ungetwc](ungetc-ungetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`_getch`, `_getwch`](getch-getwch.md)\ +[`putc`, `putwc`](putc-putwc.md)\ +[`ungetc`, `ungetwc`](ungetc-ungetwc.md) diff --git a/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md b/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md index 9e43fc2f47..f2ebc85b2a 100644 --- a/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md +++ b/docs/c-runtime-library/reference/getc-nolock-getwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _getc_nolock, _getwc_nolock" title: "_getc_nolock, _getwc_nolock" +description: "Learn more about: _getc_nolock, _getwc_nolock" ms.date: "4/2/2020" api_name: ["_getc_nolock", "_getwc_nolock", "_o__getc_nolock", "_o__getwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getc_nolock", "_gettc_nolock", "_getc_nolock", "getwc_nolock", "gettc_nolock", "_getwc_nolock"] helpviewer_keywords: ["characters, reading", "_getc_nolock function", "_getwc_nolock function", "getwc_nolock function", "streams, reading characters from", "reading characters from streams", "getc_nolock function", "gettc_nolock function", "_gettc_nolock function"] -ms.assetid: eb37b272-e177-41c9-b077-12ce7ffd3b88 --- -# _getc_nolock, _getwc_nolock +# `_getc_nolock`, `_getwc_nolock` -Reads a character from a stream. +Reads a character from a stream without locking. ## Syntax @@ -27,33 +26,33 @@ wint_t _getwc_nolock( ### Parameters -*stream*
+*`stream`*\ Input stream. -## Return Value +## Return value -See [getc, getwc](getc-getwc.md). +See [`getc`, `getwc`](getc-getwc.md). ## Remarks -These functions are identical to **getc** and **getwc** except that they do not lock the calling thread. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +These functions are identical to `getc` and `getwc` except that they don't lock the calling thread. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettc_nolock**|**getc_nolock**|**getc_nolock**|**getwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettc_nolock` | **`getc_nolock`** | **`getc_nolock`** | **`getwc_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**getc_nolock**|\| -|**getwc_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`getc_nolock`** | \ | +| **`getwc_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,8 +105,8 @@ Input was: Line the first. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[_getch, _getwch](getch-getwch.md)
-[putc, putwc](putc-putwc.md)
-[ungetc, ungetwc](ungetc-ungetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`_getch`, `_getwch`](getch-getwch.md)\ +[`putc`, `putwc`](putc-putwc.md)\ +[`ungetc`, `ungetwc`](ungetc-ungetwc.md) diff --git a/docs/c-runtime-library/reference/getch-getwch.md b/docs/c-runtime-library/reference/getch-getwch.md index 5a143906bf..82d45dd775 100644 --- a/docs/c-runtime-library/reference/getch-getwch.md +++ b/docs/c-runtime-library/reference/getch-getwch.md @@ -1,14 +1,13 @@ --- title: "_getch, _getwch" description: "API reference for _getch and _getwch; which get a character from the console without echo." -ms.date: "4/2/2020" +ms.date: "3/8/2023" api_name: ["_getch", "_getwch", "_o__getch", "_o__getwch"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getwch", "_getch", "_getwch"] helpviewer_keywords: ["characters, getting from console", "getch function", "_getwch function", "console, reading from", "_getch function", "getwch function"] -ms.assetid: cc116be7-cff2-4274-970f-5e7b18ccc05c --- # `_getch`, `_getwch` @@ -24,32 +23,32 @@ int _getch( void ); wint_t _getwch( void ); ``` -## Return Value +## Return value Returns the character read. There's no error return. ## Remarks -The **`_getch`** and **`_getwch`** functions read a single character from the console without echoing the character. None of these functions can be used to read CTRL+C. When reading a function key or an arrow key, each function must be called twice; the first call returns 0 or 0xE0, and the second call returns the actual key code. +The **`_getch`** and **`_getwch`** functions read a single character from the console without echoing the character. To read a function key or arrow key, each function must be called twice. The first call returns `0` or `0xE0`. The second call returns the [key scan code](/previous-versions/visualstudio/visual-studio-6.0/aa299374(v=vs.60)). -These functions lock the calling thread and are therefore thread-safe. For non-locking versions, see [`_getch_nolock`, `_getwch_nolock`](getch-nolock-getwch-nolock.md). +These functions lock the calling thread and so are thread-safe. For non-locking versions, see [`_getch_nolock`, `_getwch_nolock`](getch-nolock-getwch-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_gettch`**|**`_getch`**|**`_getch`**|**`_getwch`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_gettch`** | **`_getch`** | **`_getch`** | **`_getwch`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_getch`**|``| -|**`_getwch`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_getch`** | `` | +| **`_getwch`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -89,8 +88,8 @@ Type 'Y' when finished typing keys: Y ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[`_getche`, `_getwche`](getche-getwche.md)
-[`_cgets`, `_cgetws`](../../c-runtime-library/cgets-cgetws.md)
-[`getc`, `getwc`](getc-getwc.md)
-[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_getche`, `_getwche`](getche-getwche.md)\ +[`_cgets`, `_cgetws`](../cgets-cgetws.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) diff --git a/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md b/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md index 53aad6c6c0..61bf1a4ace 100644 --- a/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md +++ b/docs/c-runtime-library/reference/getch-nolock-getwch-nolock.md @@ -1,18 +1,17 @@ --- title: "_getch_nolock, _getwch_nolock" -description: "API reference for _getch_nolock, and _getwch_nolock; which get a character from the console without echo and without locking the thread." +description: "Learn more about: _getch_nolock, _getwch_nolock" ms.date: "4/2/2020" api_name: ["_getwch_nolock", "_getch_nolock", "_o__getch_nolock", "_o__getwch_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getch_nolock", "getwch_nolock", "getch_nolock", "_getwch_nolock", "_gettch_nolock", "gettch_nolock"] helpviewer_keywords: ["characters, getting from console", "_getwch_nolock function", "_getch_nolock function", "getwch_nolock function", "_gettch_nolock function", "console, reading from", "getch_nolock function", "gettch_nolock function"] -ms.assetid: 9d248546-26ca-482c-b0c6-55812a987e83 --- -# _getch_nolock, _getwch_nolock +# `_getch_nolock`, `_getwch_nolock` -Gets a character from the console without echo and without locking the thread. +Gets a character from the console without echo and without locking. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -24,30 +23,30 @@ int _getch_nolock( void ); wint_t _getwch_nolock( void ); ``` -## Return Value +## Return value Returns the character read. There's no error return. ## Remarks -**_getch_nolock** and **_getwch_nolock** are identical to **_getch** and **_getchw** except that they not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_getch_nolock`** and **`_getwch_nolock`** are identical to `_getch` and `_getchw` except that they not protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettch_nolock**|**_getch_nolock**|**_getch_nolock**|**_getwch_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettch_nolock` | **`_getch_nolock`** | **`_getch_nolock`** | **`_getwch_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getch_nolock**|\| -|**_getwch_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_getch_nolock`** | \ | +| **`_getwch_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,8 +86,8 @@ Type 'Y' when finished typing keys: Y ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_getche, _getwche](getche-getwche.md)
-[_cgets, _cgetws](../../c-runtime-library/cgets-cgetws.md)
-[getc, getwc](getc-getwc.md)
-[_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_getche`, `_getwche`](getche-getwche.md)\ +[`_cgets`, `_cgetws`](../cgets-cgetws.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) diff --git a/docs/c-runtime-library/reference/getch.md b/docs/c-runtime-library/reference/getch.md index dc2e0c629a..bf82f4aa74 100644 --- a/docs/c-runtime-library/reference/getch.md +++ b/docs/c-runtime-library/reference/getch.md @@ -8,13 +8,12 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getch"] helpviewer_keywords: ["getch function"] -ms.assetid: d3a0b744-d63c-4f71-960e-24e619dccd01 --- -# getch +# `getch` -The Microsoft-specific function name `getch` is a deprecated alias for the [_getch](getch-getwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `getch` is a deprecated alias for the [`_getch`](getch-getwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getch](getch-getwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getch`](getch-getwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/getchar-getwchar.md b/docs/c-runtime-library/reference/getchar-getwchar.md index 2872551077..a500748f1a 100644 --- a/docs/c-runtime-library/reference/getchar-getwchar.md +++ b/docs/c-runtime-library/reference/getchar-getwchar.md @@ -3,14 +3,13 @@ description: "Learn more about: getchar, getwchar" title: "getchar, getwchar" ms.date: "06/23/2020" api_name: ["getchar", "getwchar", "_o_getchar", "_o_getwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getwchar", "GetChar"] helpviewer_keywords: ["gettchar function", "characters, reading", "getwchar function", "_gettchar function", "standard input, reading from"] -ms.assetid: 19fda588-3e33-415c-bb60-dd73c028086a --- -# getchar, getwchar +# `getchar`, `getwchar` Reads a character from standard input. @@ -21,34 +20,34 @@ int getchar(); wint_t getwchar(); ``` -## Return Value +## Return value Returns the character read. These functions wait for input and don't return until input is available. -To indicate a read error or end-of-file condition, **getchar** returns **EOF**, and **getwchar** returns **WEOF**. For **getchar**, use **ferror** or **feof** to check for an error or for end of file. +To indicate a read error or end-of-file condition, **`getchar`** returns `EOF`, and **`getwchar`** returns `WEOF`. For **`getchar`**, use **`ferror`** or **`feof`** to check for an error or for end of file. ## Remarks -Each routine reads a single character from **stdin** and increments the associated file pointer to point to the next character. **getchar** is the same as [_fgetchar](fgetc-fgetwc.md), but it's implemented as a function and as a macro. +Each routine reads a single character from **`stdin`** and increments the associated file pointer to point to the next character. **`getchar`** is the same as [`_fgetchar`](fgetc-fgetwc.md), but it's implemented as a function and as a macro. -These functions also lock the calling thread and are thread-safe. For a non-locking version, see [_getchar_nolock, _getwchar_nolock](getchar-nolock-getwchar-nolock.md). +These functions also lock the calling thread and are thread-safe. For a non-locking version, see [`_getchar_nolock`, `_getwchar_nolock`](getchar-nolock-getwchar-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_gettchar**|**getchar**|**getchar**|**getwchar**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettchar` | **`getchar`** | **`getchar`** | **`getwchar`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**getchar**|\| -|**getwchar**|\ or \| +| Routine | Required header | +|---|---| +| **`getchar`** | `` | +| **`getwchar`** | `` or `` | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -82,9 +81,9 @@ This textInput was: This text ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[_getch, _getwch](getch-getwch.md)
-[putc, putwc](putc-putwc.md)
-[ungetc, ungetwc](ungetc-ungetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`_getch`, `_getwch`](getch-getwch.md)\ +[`putc`, `putwc`](putc-putwc.md)\ +[`ungetc`, `ungetwc`](ungetc-ungetwc.md) diff --git a/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md b/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md index 360fba40a4..2aba163479 100644 --- a/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md +++ b/docs/c-runtime-library/reference/getchar-nolock-getwchar-nolock.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _getchar_nolock, _getwchar_nolock" title: "_getchar_nolock, _getwchar_nolock" +description: "Learn more about: _getchar_nolock, _getwchar_nolock" ms.date: "11/04/2016" api_name: ["_getchar_nolock", "_getwchar_nolock"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getwchar_nolock", "_getwchar_nolock", "_getchar_nolock", "getchar_nolock"] helpviewer_keywords: ["_getwchar_nolock function", "getwchar_nolock function", "characters, reading", "_getchar_nolock function", "getchar_nolock function", "standard input, reading from"] -ms.assetid: dc49ba60-0647-4ae9-aa9a-a0618b1666de --- -# _getchar_nolock, _getwchar_nolock +# `_getchar_nolock`, `_getwchar_nolock` -Reads a character from standard input. +Reads a character from the standard input without locking. ## Syntax @@ -21,28 +20,28 @@ int _getchar_nolock( void ); wint_t _getwchar_nolock( void ); ``` -## Return Value +## Return value -See [getchar, getwchar](getchar-getwchar.md). +See [`getchar`, `getwchar`](getchar-getwchar.md). ## Remarks -**_getchar_nolock** and **_getwchar_nolock** are identical to **getchar** and **getwchar** except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_getchar_nolock`** and **`_getwchar_nolock`** are identical to `getchar` and `getwchar` except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettchar_nolock**|**_getchar_nolock**|**_getchar_nolock**|**_getwchar_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettchar_nolock` | **`_getchar_nolock`** | **`_getchar_nolock`** | **`_getwchar_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getchar_nolock**|\| -|**_getwchar_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_getchar_nolock`** | \ | +| **`_getwchar_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -77,9 +76,9 @@ This textInput was: This text ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
-[_getch, _getwch](getch-getwch.md)
-[putc, putwc](putc-putwc.md)
-[ungetc, ungetwc](ungetc-ungetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md)\ +[`_getch`, `_getwch`](getch-getwch.md)\ +[`putc`, `putwc`](putc-putwc.md)\ +[`ungetc`, `ungetwc`](ungetc-ungetwc.md) diff --git a/docs/c-runtime-library/reference/getche-getwche.md b/docs/c-runtime-library/reference/getche-getwche.md index 52c260d32c..188c2ee2e7 100644 --- a/docs/c-runtime-library/reference/getche-getwche.md +++ b/docs/c-runtime-library/reference/getche-getwche.md @@ -3,14 +3,14 @@ title: "_getche, _getwche" description: "API reference for _getche and _getwche; which get a character from the console with echo." ms.date: "4/2/2020" api_name: ["_getwche", "_getche", "_o__getche", "_o__getwche"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getwche", "_getche", "_getwche"] helpviewer_keywords: ["characters, getting from console", "_getwche function", "getche function", "console, reading from", "getwche function", "_getche function"] ms.assetid: eac978a8-c43a-4130-938f-54f12e2a0fda --- -# _getche, _getwche +# `_getche`, `_getwche` Gets a character from the console with echo. @@ -24,32 +24,32 @@ int _getche( void ); wint_t _getwche( void ); ``` -## Return Value +## Return value Returns the character read. There's no error return. ## Remarks -The **_getche** and **_getwche** functions read a single character from the console with echo, meaning that the character is displayed at the console. None of these functions can be used to read CTRL+C. When reading a function key or an arrow key, each function must be called twice; the first call returns 0 or 0xE0, and the second call returns the actual key code. +The **`_getche`** and **`_getwche`** functions read a single character from the console with echo, meaning that the character is displayed at the console. None of these functions can be used to read CTRL+C. When **`_getche`** or **`_getwche`** reads a function key or an arrow key, the function must be called twice; the first call returns 0 or 0xE0, and the second call returns the actual key code. -These functions lock the calling thread and are therefore thread-safe. For non-locking versions, see [_getche_nolock, _getwche_nolock](getche-nolock-getwche-nolock.md). +These functions lock the calling thread and are therefore thread-safe. For non-locking versions, see [`_getche_nolock`, `_getwche_nolock`](getche-nolock-getwche-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_getche**|**_getche**|**_getch**|**_getwche**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettche` | **`_getche`** | **`_getche`** | **`_getwche`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getche**|\| -|**_getwche**|\ or \| +| Routine | Required header | +|---|---| +| **`_getche`** | \ | +| **`_getwche`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -89,7 +89,7 @@ Type 'Y' when finished typing keys: abcdefyY ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cgets, _cgetws](../../c-runtime-library/cgets-cgetws.md)
-[getc, getwc](getc-getwc.md)
-[_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cgets`, `_cgetws`](../cgets-cgetws.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) diff --git a/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md b/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md index 9b84ae0feb..c9c6b7ad6f 100644 --- a/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md +++ b/docs/c-runtime-library/reference/getche-nolock-getwche-nolock.md @@ -1,18 +1,17 @@ --- title: "_getche_nolock, _getwche_nolock" -description: "API reference for _getche_nolock, and _getwche_nolock; which gets a character from the console, with echo and without locking the thread." +description: "Learn more about: _getche_nolock, _getwche_nolock" ms.date: "4/2/2020" api_name: ["_getche_nolock", "_getwche_nolock", "_o__getche_nolock", "_o__getwche_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getche_nolock", "_gettche_nolock", "_getwche_nolock", "getche_nolock", "getwche_nolock", "gettche_nolock"] helpviewer_keywords: ["characters, getting from console", "_gettche_nolock function", "getwche_nolock function", "_getche_nolock function", "getche_nolock function", "console, reading from", "_getwche_nolock function", "gettche_nolock function"] -ms.assetid: 9e853ad4-4d8a-4442-9ae5-da4b434f0b8c --- -# _getche_nolock, _getwche_nolock +# `_getche_nolock`, `_getwche_nolock` -Gets a character from the console, with echo and without locking the thread. +Gets a character from the console with echo and without locking. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -24,30 +23,30 @@ int _getche_nolock( void ); wint_t _getwche_nolock( void ); ``` -## Return Value +## Return value Returns the character read. There's no error return. ## Remarks -**_getche_nolock** and **_getwche_nolock** are identical to **_getche** and **_getwche** except that they not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_getche_nolock`** and **`_getwche_nolock`** are identical to `_getche` and `_getwche` except that they not protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_gettche_nolock**|**_getche_nolock**|**_getch_nolock**|**_getwche_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_gettche_nolock` | **`_getche_nolock`** | **`_getch_nolock`** | **`_getwche_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getche_nolock**|\| -|**_getwche_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_getche_nolock`** | \ | +| **`_getwche_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,7 +86,7 @@ Type 'Y' when finished typing keys: abcdefyY ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cgets, _cgetws](../../c-runtime-library/cgets-cgetws.md)
-[getc, getwc](getc-getwc.md)
-[_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cgets`, `_cgetws`](../cgets-cgetws.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) diff --git a/docs/c-runtime-library/reference/getche.md b/docs/c-runtime-library/reference/getche.md index db3a1b190a..f2c92353dd 100644 --- a/docs/c-runtime-library/reference/getche.md +++ b/docs/c-runtime-library/reference/getche.md @@ -10,11 +10,11 @@ f1_keywords: ["getche"] helpviewer_keywords: ["getche function"] ms.assetid: 95e62bb8-eec0-4145-b2e8-f6406849af52 --- -# getche +# `getche` -The Microsoft-specific function name `getche` is a deprecated alias for the [_getche](getche-getwche.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `getche` is a deprecated alias for the [`_getche`](getche-getwche.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getche](getche-getwche.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getche`](getche-getwche.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md b/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md index e43bf827cf..1a9d43dc61 100644 --- a/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md +++ b/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_getcwd_dbg", "_wgetcwd_dbg", "getcwd_dbg", "wgetcwd_dbg"] helpviewer_keywords: ["wgetcwd_dbg function", "working directory", "_getcwd_dbg function", "getcwd_dbg function", "current working directory", "_wgetcwd_dbg function", "directories [C++], current working"] ms.assetid: 8d5d151f-d844-4aa6-a28c-1c11a22dc00d --- -# _getcwd_dbg, _wgetcwd_dbg +# `_getcwd_dbg`, `_wgetcwd_dbg` -Debug versions of the [_getcwd, _wgetcwd](getcwd-wgetcwd.md) functions (only available during debug). +Debug versions of the [`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md) functions (only available during debug). ## Syntax @@ -35,50 +35,50 @@ wchar_t *_wgetcwd_dbg( ### Parameters -*buffer*
+*`buffer`*\ Storage location for the path. -*maxlen*
-Maximum length of the path in characters: **`char`** for **_getcwd_dbg** and **`wchar_t`** for **_wgetcwd_dbg**. +*`maxlen`*\ +Maximum length of the path in characters: **`char`** for **`_getcwd_dbg`** and **`wchar_t`** for **`_wgetcwd_dbg`**. -*blockType*
-Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested the allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -Returns a pointer to *buffer*. A **NULL** return value indicates an error, and **errno** is set either to **ENOMEM**, indicating that there is insufficient memory to allocate *maxlen* bytes (when a **NULL** argument is given as *buffer*), or to **ERANGE**, indicating that the path is longer than *maxlen* characters. +Returns a pointer to *`buffer`*. A `NULL` return value indicates an error, and `errno` is set either to `ENOMEM`, indicating that there's insufficient memory to allocate *`maxlen`* bytes (when a `NULL` argument is given as *`buffer`*), or to `ERANGE`, indicating that the path is longer than *`maxlen`* characters. -For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_getcwd_dbg** and **_wgetcwd_dbg** functions are identical to **_getcwd** and **_wgetcwd** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc** and **_malloc_dbg** to allocate memory if **NULL** is passed as the first parameter. For more information, see [_malloc_dbg](malloc-dbg.md). +The **`_getcwd_dbg`** and **`_wgetcwd_dbg`** functions are identical to `_getcwd` and `_wgetcwd` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc` and `_malloc_dbg` to allocate memory if `NULL` is passed as the first parameter. For more information, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the **_CRTDBG_MAP_ALLOC** flag. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_getcwd** and **_wgetcwd** are remapped to **_getcwd_dbg** and **_wgetcwd_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the `_CRTDBG_MAP_ALLOC` flag. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_getcwd` and `_wgetcwd` are remapped to **`_getcwd_dbg`** and **`_wgetcwd_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -## Generic-Text Routine Mappings +## Generic-text routine mapping -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetcwd_dbg**|**_getcwd_dbg**|**_getcwd_dbg**|**_wgetcwd_dbg**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tgetcwd_dbg` | **`_getcwd_dbg`** | **`_getcwd_dbg`** | **`_wgetcwd_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getcwd_dbg**|\| -|**_wgetcwd_dbg**|\| +| Routine | Required header | +|---|---| +| **`_getcwd_dbg`** | \ | +| **`_wgetcwd_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[Directory Control](../../c-runtime-library/directory-control.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[Directory control](../directory-control.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/getcwd-wgetcwd.md b/docs/c-runtime-library/reference/getcwd-wgetcwd.md index 5874f6c0ba..52d49fef4d 100644 --- a/docs/c-runtime-library/reference/getcwd-wgetcwd.md +++ b/docs/c-runtime-library/reference/getcwd-wgetcwd.md @@ -3,7 +3,7 @@ title: "_getcwd, _wgetcwd" description: C Runtime Library functions _getcwd, _wgetcwd get the current working directory. ms.date: "4/2/2020" api_name: ["_wgetcwd", "_getcwd", "_o__getcwd", "_o__wgetcwd"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getcwd", "wgetcwd", "_wgetcwd", "tgetcwd", "_tgetcwd"] @@ -35,38 +35,38 @@ Storage location for the path. *`maxlen`*\ Maximum length of the path in characters: **`char`** for **`_getcwd`** and **`wchar_t`** for **`_wgetcwd`**. -## Return Value +## Return value -Returns a pointer to *`buffer`*. A **`NULL`** return value indicates an error, and **`errno`** is set either to **`ENOMEM`**, indicating that there is insufficient memory to allocate *`maxlen`* bytes (when a **`NULL`** argument is given as *`buffer`*), or to **`ERANGE`**, indicating that the path is longer than *`maxlen`* characters. If *`maxlen`* is less than or equal to zero, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +Returns a pointer to *`buffer`*. A `NULL` return value indicates an error, and `errno` is set either to `ENOMEM`, indicating that there's insufficient memory to allocate *`maxlen`* bytes (when a `NULL` argument is given as *`buffer`*), or to `ERANGE`, indicating that the path is longer than *`maxlen`* characters. If *`maxlen`* is less than or equal to zero, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_getcwd`** function gets the full path of the current working directory for the default drive and stores it at *`buffer`*. The integer argument *`maxlen`* specifies the maximum length for the path. An error occurs if the length of the path (including the terminating null character) exceeds *`maxlen`*. The *`buffer`* argument can be **`NULL`**; a buffer of at least size *`maxlen`* (more only if necessary) is automatically allocated, using **`malloc`**, to store the path. This buffer can later be freed by calling **`free`** and passing it the **`_getcwd`** return value (a pointer to the allocated buffer). +The **`_getcwd`** function gets the full path of the current working directory for the default drive and stores it at *`buffer`*. The integer argument *`maxlen`* specifies the maximum length for the path. An error occurs if the length of the path (including the terminating null character) exceeds *`maxlen`*. The *`buffer`* argument can be `NULL`; a buffer of at least size *`maxlen`* (more only if necessary) is automatically allocated, using **`malloc`**, to store the path. This buffer can later be freed by calling **`free`** and passing it the **`_getcwd`** return value (a pointer to the allocated buffer). **`_getcwd`** returns a string that represents the path of the current working directory. If the current working directory is the root, the string ends with a backslash (`\`). If the current working directory is a directory other than the root, the string ends with the directory name and not with a backslash. **`_wgetcwd`** is a wide-character version of **`_getcwd`**; the *`buffer`* argument and return value of **`_wgetcwd`** are wide-character strings. **`_wgetcwd`** and **`_getcwd`** behave identically otherwise. -When **`_DEBUG`** and **`_CRTDBG_MAP_ALLOC`** are defined, calls to **`_getcwd`** and **`_wgetcwd`** are replaced by calls to **`_getcwd_dbg`** and **`_wgetcwd_dbg`** to allow for debugging memory allocations. For more information, see [`_getcwd_dbg`, `_wgetcwd_dbg`](getcwd-dbg-wgetcwd-dbg.md). +When `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, calls to **`_getcwd`** and **`_wgetcwd`** are replaced by calls to **`_getcwd_dbg`** and **`_wgetcwd_dbg`**, to allow you to debug memory allocations. For more information, see [`_getcwd_dbg`, `_wgetcwd_dbg`](getcwd-dbg-wgetcwd-dbg.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tgetcwd`**|**`_getcwd`**|**`_getcwd`**|**`_wgetcwd`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tgetcwd`** | **`_getcwd`** | **`_getcwd`** | **`_wgetcwd`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_getcwd`**|``| -|**`_wgetcwd`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_getcwd`** | `` | +| **`_wgetcwd`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -105,7 +105,7 @@ C:\Code ## See also -[Directory Control](../../c-runtime-library/directory-control.md)\ +[Directory control](../directory-control.md)\ [`_chdir`, `_wchdir`](chdir-wchdir.md)\ [`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ [`_rmdir`, `_wrmdir`](rmdir-wrmdir.md) diff --git a/docs/c-runtime-library/reference/getcwd.md b/docs/c-runtime-library/reference/getcwd.md index 4603a801d9..d01bdd7f37 100644 --- a/docs/c-runtime-library/reference/getcwd.md +++ b/docs/c-runtime-library/reference/getcwd.md @@ -8,13 +8,12 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getcwd"] helpviewer_keywords: ["getcwd function"] -ms.assetid: c740ab06-9ba0-4036-a025-ce3acded3ffe --- -# getcwd +# `getcwd` -The Microsoft-implemented POSIX function name `getcwd` is a deprecated alias for the [_getcwd](getcwd-wgetcwd.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `getcwd` is a deprecated alias for the [`_getcwd`](getcwd-wgetcwd.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getcwd](getcwd-wgetcwd.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getcwd`](getcwd-wgetcwd.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md b/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md index 9fb01fc5fb..4f3d1b56f7 100644 --- a/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md +++ b/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_getdcwd_dbg", "getdcwd_dbg", "_wgetdcwd_dbg", "wgetdcwd_dbg"] helpviewer_keywords: ["working directory", "_getdcwd_dbg function", "wgetdcwd_dbg function", "current working directory", "getdcwd_dbg function", "_wgetdcwd_dbg function", "directories [C++], current working"] ms.assetid: 266bf6f0-0417-497f-963d-2e0f306d9385 --- -# _getdcwd_dbg, _wgetdcwd_dbg +# `_getdcwd_dbg`, `_wgetdcwd_dbg` -Debug versions of the [_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md) functions (only available during debug). +Debug versions of the [`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md) functions (only available during debug). ## Syntax @@ -37,51 +37,51 @@ wchar_t *_wgetdcwd_dbg( ### Parameters -*drive*
+*`drive`*\ Name of the disk drive. -*buffer*
+*`buffer`*\ Storage location for the path. -*maxlen*
-Maximum length of the path in characters: **`char`** for **_getdcwd_dbg** and **`wchar_t`** for **_wgetdcwd_dbg**. +*`maxlen`*\ +Maximum length of the path in characters: **`char`** for **`_getdcwd_dbg`** and **`wchar_t`** for **`_wgetdcwd_dbg`**. -*blockType*
-Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested the allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -Returns a pointer to *buffer*. A **NULL** return value indicates an error, and **errno** is set either to **ENOMEM**, indicating that there is insufficient memory to allocate *maxlen* bytes (when a **NULL** argument is given as *buffer*), or to **ERANGE**, indicating that the path is longer than *maxlen* characters. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Returns a pointer to *`buffer`*. A `NULL` return value indicates an error, and `errno` is set either to `ENOMEM`, indicating that there's insufficient memory to allocate *`maxlen`* bytes (when a `NULL` argument is given as *`buffer`*), or to `ERANGE`, indicating that the path is longer than *`maxlen`* characters. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_getdcwd_dbg** and **_wgetdcwd_dbg** functions are identical to **_getdcwd** and **_wgetdcwd** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc** and **_malloc_dbg** to allocate memory if **NULL** is passed as the *buffer* parameter. For more information, see [_malloc_dbg](malloc-dbg.md). +The **`_getdcwd_dbg`** and **`_wgetdcwd_dbg`** functions are identical to `_getdcwd` and `_wgetdcwd` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc` and `_malloc_dbg` to allocate memory if `NULL` is passed as the *`buffer`* parameter. For more information, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the **_CRTDBG_MAP_ALLOC** flag. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_getdcwd** and **_wgetdcwd** are remapped to **_getdcwd_dbg** and **_wgetdcwd_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information, see [Types of Blocks on the Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the `_CRTDBG_MAP_ALLOC` flag. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_getdcwd` and `_wgetdcwd` are remapped to **`_getdcwd_dbg`** and **`_wgetdcwd_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd_dbg**|**_getdcwd_dbg**|**_getdcwd_dbg**|**_wgetdcwd_dbg**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tgetdcwd_dbg`** | **`_getdcwd_dbg`** | **`_getdcwd_dbg`** | **`_wgetdcwd_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdcwd_dbg**|\| -|**_wgetdcwd_dbg**|\| +| Routine | Required header | +|---|---| +| **`_getdcwd_dbg`** | \ | +| **`_wgetdcwd_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md)
-[Directory Control](../../c-runtime-library/directory-control.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md)\ +[Directory control](../directory-control.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md b/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md index ee60bc5a9c..b186869ad1 100644 --- a/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md +++ b/docs/c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _getdcwd_nolock, _wgetdcwd_nolock" title: "_getdcwd_nolock, _wgetdcwd_nolock" +description: "Learn more about: _getdcwd_nolock, _wgetdcwd_nolock" ms.date: "11/04/2016" api_name: ["_wgetdcwd_nolock", "_getdcwd_nolock"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wgetdcwd_nolock", "tgetdcwd_nolock", "wgetdcwd_nolock", "_getdcwd_nolock", "_tgetdcwd_nolock", "getdcwd_nolock"] helpviewer_keywords: ["getdcwd_nolock function", "_tgetdcwd_nolock function", "working directory", "tgetdcwd_nolock function", "_getdcwd_nolock function", "current working directory", "wgetdcwd_nolock function", "_wgetdcwd_nolock function", "directories [C++], current working"] -ms.assetid: d9bdf712-43f8-4173-8f9a-844e82beaa97 --- -# _getdcwd_nolock, _wgetdcwd_nolock +# `_getdcwd_nolock`, `_wgetdcwd_nolock` Gets the full path of the current working directory on the specified drive. @@ -34,43 +33,43 @@ wchar_t *_wgetdcwd_nolock( ### Parameters -*drive*
+*`drive`*\ Disk drive. -*buffer*
+*`buffer`*\ Storage location for the path. -*maxlen*
-Maximum length of path in characters: **`char`** for **_getdcwd** and **`wchar_t`** for **_wgetdcwd**. +*`maxlen`*\ +Maximum length of path in characters: **`char`** for **`_getdcwd_nolock`** and **`wchar_t`** for **`_wgetdcwd_nolock`**. -## Return Value +## Return value -See [_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md). +See [`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md). ## Remarks -**_getdcwd_nolock** and **_wgetdcwd_nolock** are identical to **_getdcwd** and **_wgetdcwd**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_getdcwd_nolock`** and **`_wgetdcwd_nolock`** are identical to `_getdcwd` and `_wgetdcwd`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd_nolock**|**_getdcwd_nolock**|**_getdcwd_nolock**|**_wgetdcwd_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tgetdcwd_nolock`** | **`_getdcwd_nolock`** | **`_getdcwd_nolock`** | **`_wgetdcwd_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdcwd_nolock**|\| -|**_wgetdcwd_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_getdcwd_nolock`** | \ | +| **`_wgetdcwd_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdir, _wchdir](chdir-wchdir.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdrive](getdrive.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_rmdir, _wrmdir](rmdir-wrmdir.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdrive`](getdrive.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md) diff --git a/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md b/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md index 115c7aa0d5..4b5fc98040 100644 --- a/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md +++ b/docs/c-runtime-library/reference/getdcwd-wgetdcwd.md @@ -3,14 +3,14 @@ description: "Learn more about: _getdcwd, _wgetdcwd" title: "_getdcwd, _wgetdcwd" ms.date: "4/2/2020" api_name: ["_getdcwd", "_wgetdcwd", "_o__getdcwd", "_o__wgetdcwd"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wgetdcwd", "getdcwd", "_getdcwd", "tgetdcwd", "_wgetdcwd", "_tgetdcwd"] helpviewer_keywords: ["wgetdcwd function", "working directory", "getdcwd function", "_getdcwd function", "_wgetdcwd function", "current working directory", "directories [C++], current working"] ms.assetid: 184152f5-c7b0-495b-918d-f9a6adc178bd --- -# _getdcwd, _wgetdcwd +# `_getdcwd`, `_wgetdcwd` Gets the full path of the current working directory on the specified drive. @@ -31,65 +31,65 @@ wchar_t *_wgetdcwd( ### Parameters -*drive*
+*`drive`*\ A non-negative integer that specifies the drive (0 = default drive, 1 = A, 2 = B, and so on). -If the specified drive isn't available, or the kind of drive (for example, removable, fixed, CD-ROM, RAM disk, or network drive) can't be determined, the invalid-parameter handler is invoked. For more information, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If the specified drive isn't available, the invalid parameter handler is invoked. It's also invoked when the kind of drive (for example, removable, fixed, CD-ROM, RAM disk, or network drive) can't be determined. For more information, see [Parameter validation](../parameter-validation.md). -*buffer*
-Storage location for the path, or **NULL**. +*`buffer`*\ +Storage location for the path, or `NULL`. -If **NULL** is specified, this function allocates a buffer of at least *maxlen* size by using **malloc**, and the return value of **_getdcwd** is a pointer to the allocated buffer. The buffer can be freed by calling **free** and passing it the pointer. +If `NULL` is specified, this function allocates a buffer of at least *`maxlen`* size by using `malloc`, and the return value of **`_getdcwd`** is a pointer to the allocated buffer. The buffer can be freed by calling `free` and passing it the pointer. -*maxlen*
-A nonzero positive integer that specifies the maximum length of the path, in characters: **`char`** for **_getdcwd** and **`wchar_t`** for **_wgetdcwd**. +*`maxlen`*\ +A nonzero positive integer that specifies the maximum length of the path, in characters: **`char`** for **`_getdcwd`** and **`wchar_t`** for **`_wgetdcwd`**. -If *maxlen* is less than or equal to zero, the invalid-parameter handler is invoked. For more information, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If *`maxlen`* is less than or equal to zero, the invalid-parameter handler is invoked. For more information, see [Parameter validation](../parameter-validation.md). -## Return Value +## Return value -Pointer to a string that represents the full path of the current working directory on the specified drive, or **NULL**, which indicates an error. +Pointer to a string that represents the full path of the current working directory on the specified drive, or `NULL`, which indicates an error. -If *buffer* is specified as **NULL** and there is insufficient memory to allocate *maxlen* characters, an error occurs and **errno** is set to **ENOMEM**. If the length of the path including the terminating null character exceeds *maxlen*, an error occurs, and **errno** is set to **ERANGE**. For more information about these error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If *`buffer`* is specified as `NULL` and there's insufficient memory to allocate *`maxlen`* characters, an error occurs and `errno` is set to `ENOMEM`. If the length of the path including the terminating null character exceeds *`maxlen`*, an error occurs, and `errno` is set to `ERANGE`. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_getdcwd** function gets the full path of the current working directory on the specified drive and stores it at *buffer*. If the current working directory is set to the root, the string ends with a backslash (\\). If the current working directory is set to a directory other than the root, the string ends with the name of the directory and not with a backslash. +The **`_getdcwd`** function gets the full path of the current working directory on the specified drive and stores it at *`buffer`*. If the current working directory is set to the root, the string ends with a backslash (\\). If the current working directory is set to a directory other than the root, the string ends with the name of the directory and not with a backslash. -**_wgetdcwd** is a wide-character version of **_getdcwd**, and its *buffer* parameter and return value are wide-character strings. Otherwise, **_wgetdcwd** and **_getdcwd** behave identically. +**`_wgetdcwd`** is a wide-character version of **`_getdcwd`**, and its *`buffer`* parameter and return value are wide-character strings. Otherwise, **`_wgetdcwd`** and **`_getdcwd`** behave identically. -This function is thread-safe even though it depends on **GetFullPathName**, which is itself not thread-safe. However, you can violate thread safety if your multithreaded application calls both this function and [GetFullPathName](/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew). +This function is thread-safe even though it depends on `GetFullPathName`, which is itself not thread-safe. However, you can violate thread safety if your multithreaded application calls both this function and [`GetFullPathName`](/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew). -The version of this function that has the **_nolock** suffix behaves identically to this function except that it is not thread-safe and is not protected from interference by other threads. For more information, see [_getdcwd_nolock, _wgetdcwd_nolock](getdcwd-nolock-wgetdcwd-nolock.md). +The version of this function that has the `_nolock` suffix behaves identically to this function except that it isn't thread-safe and isn't protected from interference by other threads. For more information, see [`_getdcwd_nolock`, `_wgetdcwd_nolock`](getdcwd-nolock-wgetdcwd-nolock.md). -When **_DEBUG** and **_CRTDBG_MAP_ALLOC** are defined, calls to **_getdcwd** and **_wgetdcwd** are replaced by calls to **_getdcwd_dbg** and **_wgetdcwd_dbg** so that you can debug memory allocations. For more information, see[_getdcwd_dbg, _wgetdcwd_dbg](getdcwd-dbg-wgetdcwd-dbg.md). +When `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, calls to **`_getdcwd`** and **`_wgetdcwd`** are replaced by calls to `_getdcwd_dbg` and `_wgetdcwd_dbg`, so that you can debug memory allocations. For more information, see[`_getdcwd_dbg`, `_wgetdcwd_dbg`](getdcwd-dbg-wgetdcwd-dbg.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tgetdcwd**|**_getdcwd**|**_getdcwd**|**_wgetdcwd**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tgetdcwd` | **`_getdcwd`** | **`_getdcwd`** | **`_wgetdcwd`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdcwd**|\| -|**_wgetdcwd**|\ or \| +| Routine | Required header | +|---|---| +| **`_getdcwd`** | \ | +| **`_wgetdcwd`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_getdrive](getdrive.md). +See the example in [`_getdrive`](getdrive.md). ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdir, _wchdir](chdir-wchdir.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdrive](getdrive.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_rmdir, _wrmdir](rmdir-wrmdir.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdrive`](getdrive.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md) diff --git a/docs/c-runtime-library/reference/getdiskfree.md b/docs/c-runtime-library/reference/getdiskfree.md index 24d4c570f8..9ddb84d87b 100644 --- a/docs/c-runtime-library/reference/getdiskfree.md +++ b/docs/c-runtime-library/reference/getdiskfree.md @@ -1,18 +1,17 @@ --- description: "Learn more about: _getdiskfree" title: "_getdiskfree" -ms.date: "4/2/2020" +ms.date: 05/11/2022 api_name: ["_getdiskfree", "_o__getdiskfree"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getdiskfree", "_getdiskfree"] helpviewer_keywords: ["diskfree_t type", "_getdiskfree function", "_diskfree_t type", "disk size", "getdiskfree function"] -ms.assetid: 47a3f6cf-4816-452a-8f3d-1c3ae02a0f2a --- -# _getdiskfree +# `_getdiskfree` -Uses information about a disk drive to populate a **_diskfree_t** structure. +Get information about a disk drive such as total clusters, available clusters, sectors per cluster, and bytes per sector. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -28,19 +27,19 @@ unsigned _getdiskfree( ### Parameters -*drive*
+*`drive`*\ The disk drive for which you want information. -*driveinfo*
-A **_diskfree_t** structure that will be populated with information about the drive. +*`driveinfo`*\ +A **`_diskfree_t`** structure that will be populated with information about the drive. -## Return Value +## Return value -If the function succeeds, the return value is zero. If the function fails, the return value is the error code. The value **errno** is set for any errors that are returned by the operating system. For more information about error conditions that are indicated by **errno**, see [errno Constants](../../c-runtime-library/errno-constants.md). +If the function succeeds, the return value is zero. If the function fails, the return value is the error code. The value `errno` is set for any errors that are returned by the operating system. For more information about error conditions that are indicated by `errno`, see [`errno` constants](../errno-constants.md). ## Remarks -The **_diskfree_t** structure is defined in Direct.h. +The **`_diskfree_t`** structure is defined in Direct.h. ```C struct _diskfree_t { @@ -51,17 +50,17 @@ struct _diskfree_t { }; ``` -This function validates its parameters. If the *driveinfo* pointer is **NULL** or *drive* specifies an invalid drive, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **EINVAL** and sets **errno** to **EINVAL**. Valid drives range from 0 to 26. A *drive* value of 0 specifies the current drive; thereafter, numbers map to letters of the English alphabet such that 1 indicates drive A, 3 indicates drive C, and so on. +This function validates its parameters. If the *`driveinfo`* pointer is `NULL` or *`drive`* specifies an invalid drive, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `EINVAL` and sets `errno` to `EINVAL`. Valid drives range from 0 to 26. A *`drive`* value of 0 specifies the current drive; thereafter, numbers map to letters of the English alphabet such that 1 indicates drive A, 3 indicates drive C, and so on. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdiskfree**|\| +| Routine | Required header | +|---|---| +| **`_getdiskfree`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -71,100 +70,47 @@ For more compatibility information, see [Compatibility](../../c-runtime-library/ #include #include #include -#include - -TCHAR g_szBorder[] = _T("======================================================================\n"); -TCHAR g_szTitle1[] = _T("|DRIVE|TOTAL CLUSTERS|AVAIL CLUSTERS|SECTORS / CLUSTER|BYTES / SECTOR|\n"); -TCHAR g_szTitle2[] = _T("|=====|==============|==============|=================|==============|\n"); -TCHAR g_szLine[] = _T("| A: | | | | |\n"); - -void utoiRightJustified(TCHAR* szLeft, TCHAR* szRight, unsigned uVal); - -int main(int argc, char* argv[]) { - TCHAR szMsg[4200]; - struct _diskfree_t df = {0}; - ULONG uDriveMask = _getdrives(); - unsigned uErr, uLen, uDrive; - - printf(g_szBorder); - printf(g_szTitle1); - printf(g_szTitle2); - - for (uDrive=1; uDrive<=26; ++uDrive) { - if (uDriveMask & 1) { - uErr = _getdiskfree(uDrive, &df); - memcpy(szMsg, g_szLine, sizeof(g_szLine)); - szMsg[3] = uDrive + 'A' - 1; - - if (uErr == 0) { - utoiRightJustified(szMsg+8, szMsg+19, df.total_clusters); - utoiRightJustified(szMsg+23, szMsg+34, df.avail_clusters); - utoiRightJustified(szMsg+38, szMsg+52, df.sectors_per_cluster); - utoiRightJustified(szMsg+56, szMsg+67, df.bytes_per_sector); - } - else { - uLen = FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM, NULL, - uErr, 0, szMsg+8, 4100, NULL); - szMsg[uLen+6] = ' '; - szMsg[uLen+7] = ' '; - szMsg[uLen+8] = ' '; - } - - printf(szMsg); - } - - uDriveMask >>= 1; - } - - printf(g_szBorder); -} -void utoiRightJustified(TCHAR* szLeft, TCHAR* szRight, unsigned uVal) { - TCHAR* szCur = szRight; - int nComma = 0; - - if (uVal) { - while (uVal && (szCur >= szLeft)) { - if (nComma == 3) { - *szCur = ','; - nComma = 0; - } - else { - *szCur = (uVal % 10) | 0x30; - uVal /= 10; - ++nComma; - } - - --szCur; - } - } - else { - *szCur = '0'; - --szCur; - } - - if (uVal) { - szCur = szLeft; - - while (szCur <= szRight) { - *szCur = '*'; - ++szCur; - } - } +int main(int argc, char* argv[]) +{ + ULONG uDriveMask = _getdrives(); + + for (unsigned uDrive = 1; uDrive <= 26; ++uDrive) + { + if (uDriveMask & 1) + { + struct _diskfree_t df = { 0 }; + unsigned uErr = _getdiskfree(uDrive, &df); + printf("\nDrive: %c\n", uDrive + 'A' - 1); + + if (uErr == 0) + { + printf("\tTotal clusters: %11u\n", df.total_clusters); + printf("\tAvailable clusters: %11u\n", df.avail_clusters); + printf("\tSectors per cluster: %11u\n", df.sectors_per_cluster); + printf("\tBytes per sector: %11u\n", df.bytes_per_sector); + } + else + { + WCHAR errMsg[80]; + unsigned uLen = FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM, NULL, + uErr, 0, errMsg, sizeof(errMsg), NULL); + printf("%S\n", errMsg); + } + } + uDriveMask >>= 1; + } } ``` ```Output -====================================================================== -|DRIVE|TOTAL CLUSTERS|AVAIL CLUSTERS|SECTORS / CLUSTER|BYTES / SECTOR| -|=====|==============|==============|=================|==============| -| A: | The device is not ready. | | | -| C: | 4,721,093 | 3,778,303 | 8 | 512 | -| D: | 1,956,097 | 1,800,761 | 8 | 512 | -| E: | The device is not ready. | | | -====================================================================== +Drive: C + Total clusters: 249754111 + Available clusters: 160184686 + Sectors per cluster: 8 + Bytes per sector: 512 ``` ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
+[Directory control](../directory-control.md) diff --git a/docs/c-runtime-library/reference/getdrive.md b/docs/c-runtime-library/reference/getdrive.md index 4755750372..571445fb63 100644 --- a/docs/c-runtime-library/reference/getdrive.md +++ b/docs/c-runtime-library/reference/getdrive.md @@ -3,14 +3,14 @@ description: "Learn more about: _getdrive" title: "_getdrive" ms.date: "4/2/2020" api_name: ["_getdrive", "_o__getdrive"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getdrive", "getdrive"] helpviewer_keywords: ["current disk drive", "getdrive function", "disk drives", "_getdrive function"] ms.assetid: e40631a0-8f1a-4897-90ac-e1037ff30bca --- -# _getdrive +# `_getdrive` Gets the current disk drive. @@ -23,21 +23,21 @@ Gets the current disk drive. int _getdrive( void ); ``` -## Return Value +## Return value Returns the current (default) drive (1=A, 2=B, and so on). A return value of zero means that the current path doesn't start with a letter drive name, such as a UNC path. Or, it means that an internal buffer allocation failed. If an internal allocation fails, `errno` is set to ENOMEM. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdrive**|\| +| Routine | Required header | +|---|---| +| **`_getdrive`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,7 +91,7 @@ G: (Current directory is G:\) ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdrive](chdrive.md)
-[_getcwd, _wgetcwd](getcwd-wgetcwd.md)
-[_getdcwd, _wgetdcwd](getdcwd-wgetdcwd.md)
+[Directory control](../directory-control.md)\ +[`_chdrive`](chdrive.md)\ +[`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ +[`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md) diff --git a/docs/c-runtime-library/reference/getdrives.md b/docs/c-runtime-library/reference/getdrives.md index 7c79dc77c2..2394e59be2 100644 --- a/docs/c-runtime-library/reference/getdrives.md +++ b/docs/c-runtime-library/reference/getdrives.md @@ -3,14 +3,14 @@ description: "Learn more about: _getdrives" title: "_getdrives" ms.date: "4/2/2020" api_name: ["_getdrives", "_o__getdrives"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getdrives", "_getdrives"] helpviewer_keywords: ["_getdrives function", "getdrives function", "disk drives"] ms.assetid: 869bb51f-4209-4328-846e-3aadebaceb9c --- -# _getdrives +# `_getdrives` Returns a bitmask that represents the currently available disk drives. @@ -23,21 +23,21 @@ Returns a bitmask that represents the currently available disk drives. unsigned long _getdrives( void ); ``` -## Return Value +## Return value -If the function succeeds, the return value is a bitmask that represents the currently available disk drives. Bit position 0 (the least-significant bit) is drive A, bit position 1 is drive B, bit position 2 is drive C, and so on. If the function fails, the return value is zero. To get extended error information, call **GetLastError**. +If the function succeeds, the return value is a bitmask that represents the currently available disk drives. Bit position 0 (the least-significant bit) represents drive A. Similarly, bit position 1 represents drive B, bit position 2 represents drive C, and so on. If the function fails, the return value is zero. To get extended error information, call `GetLastError`. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getdrives**|\| +| Routine | Required header | +|---|---| +| **`_getdrives`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,4 +87,4 @@ E: ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
+[Directory control](../directory-control.md) diff --git a/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md b/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md index 52a6309163..7159f16117 100644 --- a/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md +++ b/docs/c-runtime-library/reference/getenv-s-wgetenv-s.md @@ -3,17 +3,16 @@ title: "getenv_s, _wgetenv_s" description: "Describes the Microsoft C runtime library getenv_s and _wgetenv_s functions." ms.date: "4/2/2020" api_name: ["getenv_s", "_wgetenv_s", "_o__wgetenv_s", "_o_getenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getenv_s", "_tgetenv_s", "_wgetenv_s"] helpviewer_keywords: ["_tgetenv_s function", "wgetenv_s function", "_wgetenv_s function", "getenv_s function", "environment variables", "tgetenv_s function"] -ms.assetid: c3ae1ffe-d4cd-4bae-bcb1-3afa754c613a no-loc: [getenv_s, _wgetenv_s, _putenv_s, main, wmain, errno, EINVAL, ERANGE, _environ, _wenviron, _putenv, _wputenv, _tgetenv_s, _tzset, _dupenv_s, _wdupenv_s] --- -# getenv_s, _wgetenv_s +# `getenv_s`, `_wgetenv_s` -Gets a value from the current environment. These versions of [getenv, _wgetenv](getenv-wgetenv.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Gets a value from the current environment. These versions of [`getenv`, `_wgetenv`](getenv-wgetenv.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -49,72 +48,72 @@ errno_t _wgetenv_s( ### Parameters -*pReturnValue*
-The buffer size that's required, or 0 if the variable is not found. +*`pReturnValue`*\ +The buffer size that's required, or 0 if the variable isn't found. -*buffer*
+*`buffer`*\ Buffer to store the value of the environment variable. -*numberOfElements*
-Size of *buffer*. +*`numberOfElements`*\ +Size of *`buffer`*. -*varname*
+*`varname`*\ Environment variable name. -## Return Value +## Return value Zero if successful; otherwise, an error code on failure. -### Error Conditions +### Error conditions -|*pReturnValue*|*buffer*|*numberOfElements*|*varname*|Return Value| -|--------------------|--------------|------------------------|---------------|------------------| -|**NULL**|any|any|any|**EINVAL**| -|any|**NULL**|>0|any|**EINVAL**| -|any|any|any|**NULL**|**EINVAL**| +| *`pReturnValue`* | *`buffer`* | *`numberOfElements`* | *`varname`* | Return Value | +|---|---|---|---|---| +| `NULL` | any | any | any | `EINVAL` | +| any | `NULL` | >0 | any | `EINVAL` | +| any | any | any | `NULL` | `EINVAL` | -Any of these error conditions invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **errno** to **EINVAL** and return **EINVAL**. +Any of these error conditions invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL` and return `EINVAL`. -Also, if the buffer is too small, these functions return **ERANGE**. They do not invoke an invalid parameter handler. They write out the required buffer size in *pReturnValue*, and thereby enable programs to call the function again with a larger buffer. +Also, if the buffer is too small, these functions return `ERANGE`. They don't invoke an invalid parameter handler. They write out the required buffer size in *`pReturnValue`*, and thereby enable programs to call the function again with a larger buffer. ## Remarks -The **getenv_s** function searches the list of environment variables for *varname*. **getenv_s** is not case sensitive in the Windows operating system. **getenv_s** and [_putenv_s](putenv-s-wputenv-s.md) use the copy of the environment that's pointed to by the global variable **_environ** to access the environment. **getenv_s** operates only on the data structures that are accessible to the run-time library and not on the environment "segment" that's created for the process by the operating system. Therefore, programs that use the *envp* argument to [main](../../cpp/main-function-command-line-args.md) or [wmain](../../cpp/main-function-command-line-args.md) might retrieve invalid information. +The **`getenv_s`** function searches the list of environment variables for *`varname`*. **`getenv_s`** isn't case sensitive in the Windows operating system. **`getenv_s`** and [`_putenv_s`](putenv-s-wputenv-s.md) use the copy of the environment that's pointed to by the global variable **`_environ`** to access the environment. **`getenv_s`** operates only on the data structures that are accessible to the run-time library and not on the environment "segment" that's created for the process by the operating system. Therefore, programs that use the *`envp`* argument to [`main`](../../cpp/main-function-command-line-args.md) or [`wmain`](../../cpp/main-function-command-line-args.md) might retrieve invalid information. -**_wgetenv_s** is a wide-character version of **getenv_s**; the argument and return value of **_wgetenv_s** are wide-character strings. The **_wenviron** global variable is a wide-character version of **_environ**. +**`_wgetenv_s`** is a wide-character version of **`getenv_s`**; the argument and return value of **`_wgetenv_s`** are wide-character strings. The **`_wenviron`** global variable is a wide-character version of **`_environ`**. -In an MBCS program (for example, in an SBCS ASCII program), **_wenviron** is initially **NULL** because the environment is composed of multibyte-character strings. Then, on the first call to [_wputenv](putenv-wputenv.md), or on the first call to **_wgetenv_s**, if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by **_wenviron**. +In an MBCS program (for example, in an SBCS ASCII program), **`_wenviron`** is initially `NULL` because the environment is composed of multibyte-character strings. Then, on the first call to [`_wputenv`](putenv-wputenv.md), or on the first call to **`_wgetenv_s`**, if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by **`_wenviron`**. -Similarly in a Unicode (**_wmain**) program, **_environ** is initially **NULL** because the environment is composed of wide-character strings. Then, on the first call to [_putenv](putenv-wputenv.md), or on the first call to **getenv_s** if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by **_environ**. +Similarly in a Unicode (**`_wmain`**) program, **`_environ`** is initially `NULL` because the environment is composed of wide-character strings. Then, on the first call to [`_putenv`](putenv-wputenv.md), or on the first call to **`getenv_s`** if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by **`_environ`**. -When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, and this causes slower execution time. For example, when you call **_putenv**, a call to **_wputenv** is also executed automatically so that the two environment strings correspond. +When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, execution can take longer, because the run-time system must maintain both copies. For example, when you call **`_putenv`**, a call to **`_wputenv`** is also executed automatically so that the two environment strings correspond. > [!CAUTION] -> In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, the two environment versions may not correspond exactly. This happens because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. For more information, see [_environ, _wenviron](../../c-runtime-library/environ-wenviron.md). +> In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, the two environment versions may not correspond exactly. This happens because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. For more information, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] -> The **_putenv_s** and **_getenv_s** families of functions are not thread-safe. **_getenv_s** could return a string pointer while **_putenv_s** is modifying the string and thereby cause random failures. Make sure that calls to these functions are synchronized. +> The **`_putenv_s`** and **`_getenv_s`** families of functions are not thread-safe. **`_getenv_s`** could return a string pointer while **`_putenv_s`** is modifying the string and thereby cause random failures. Make sure that calls to these functions are synchronized. -In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tgetenv_s**|**getenv_s**|**getenv_s**|**_wgetenv_s**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tgetenv_s` | **`getenv_s`** | **`getenv_s`** | **`_wgetenv_s`** | -To check or change the value of the **TZ** environment variable, use **getenv_s**, **_putenv**, and **_tzset**, as required. For more information about **TZ**, see [_tzset](tzset.md) and [_daylight, _dstbias, _timezone, and _tzname](../../c-runtime-library/daylight-dstbias-timezone-and-tzname.md). +To check or change the value of the **`TZ`** environment variable, use **`getenv_s`**, **`_putenv`**, and **`_tzset`**, as required. For more information about **`TZ`**, see [`_tzset`](tzset.md) and [`_daylight`, `_dstbias`, `_timezone`, and `_tzname`](../daylight-dstbias-timezone-and-tzname.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**getenv_s**|\| -|**_wgetenv_s**|\ or \| +| Routine | Required header | +|---|---| +| **`getenv_s`** | `` | +| **`_wgetenv_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -181,7 +180,7 @@ New LIB variable is: c:\mylib;c:\yourlib ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[Environmental Constants](../../c-runtime-library/environmental-constants.md)
-[_putenv, _wputenv](putenv-wputenv.md)
-[_dupenv_s, _wdupenv_s](dupenv-s-wdupenv-s.md)
+[Process and environment control](../process-and-environment-control.md)\ +[Environmental constants](../environmental-constants.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md)\ +[`_dupenv_s`, `_wdupenv_s`](dupenv-s-wdupenv-s.md) diff --git a/docs/c-runtime-library/reference/getenv-wgetenv.md b/docs/c-runtime-library/reference/getenv-wgetenv.md index 2cc95a8b01..9fe6419a09 100644 --- a/docs/c-runtime-library/reference/getenv-wgetenv.md +++ b/docs/c-runtime-library/reference/getenv-wgetenv.md @@ -3,7 +3,7 @@ title: "getenv, _wgetenv" description: "Describes the Microsoft C runtime library getenv and _wgetenv functions." ms.date: "4/2/2020" api_name: ["getenv", "_wgetenv", "_o__wgetenv", "_o_getenv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wgetenv", "getenv", "_tgetenv"] @@ -13,7 +13,7 @@ no-loc: [getenv, _wgetenv, getenv_s, _wgetenv_s, _putenv_s, main, wmain, errno, --- # `getenv`, `_wgetenv` -Gets a value from the current environment. More secure versions of these functions are available; see [getenv_s, _wgetenv_s](getenv-s-wgetenv-s.md). +Gets a value from the current environment. More secure versions of these functions are available; see [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -31,51 +31,51 @@ wchar_t *_wgetenv( ### Parameters -*`varname`*
+*`varname`*\ Environment variable name. ## Return value -Returns a pointer to the environment table entry containing *`varname`*. It is not safe to modify the value of the environment variable using the returned pointer. Use the [`_putenv`](putenv-wputenv.md) function to modify the value of an environment variable. The return value is **`NULL`** if *`varname`* is not found in the environment table. +Returns a pointer to the environment table entry containing *`varname`*. It isn't safe to modify the value of the environment variable using the returned pointer. Use the [`_putenv`](putenv-wputenv.md) function to modify the value of an environment variable. The return value is `NULL` if *`varname`* isn't found in the environment table. ## Remarks -The **`getenv`** function searches the list of environment variables for *`varname`*. **`getenv`** is not case sensitive in the Windows operating system. **`getenv`** and **`_putenv`** use the copy of the environment pointed to by the global variable **`_environ`** to access the environment. **`getenv`** operates only on the data structures accessible to the run-time library and not on the environment "segment" created for the process by the operating system. Therefore, programs that use the *`envp`* argument to [`main`](../../cpp/main-function-command-line-args.md) or [`wmain`](../../cpp/main-function-command-line-args.md) may retrieve invalid information. +The **`getenv`** function searches the list of environment variables for *`varname`*. **`getenv`** isn't case sensitive in the Windows operating system. **`getenv`** and **`_putenv`** use the copy of the environment pointed to by the global variable **`_environ`** to access the environment. **`getenv`** operates only on the data structures accessible to the run-time library and not on the environment "segment" created for the process by the operating system. Therefore, programs that use the *`envp`* argument to [`main`](../../cpp/main-function-command-line-args.md) or [`wmain`](../../cpp/main-function-command-line-args.md) may retrieve invalid information. -If *`varname`* is **`NULL`**, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns **`NULL`**. +If *`varname`* is `NULL`, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `NULL`. **`_wgetenv`** is a wide-character version of **`getenv`**; the argument and return value of **`_wgetenv`** are wide-character strings. The **`_wenviron`** global variable is a wide-character version of **`_environ`**. -In an MBCS program (for example, in an SBCS ASCII program), **`_wenviron`** is initially **`NULL`** because the environment is composed of multibyte-character strings. Then, on the first call to [`_wputenv`](putenv-wputenv.md), or on the first call to **`_wgetenv`** if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by **`_wenviron`**. +In an MBCS program (for example, in an SBCS ASCII program), **`_wenviron`** is initially `NULL` because the environment is composed of multibyte-character strings. Then, on the first call to [`_wputenv`](putenv-wputenv.md), or on the first call to **`_wgetenv`** if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by **`_wenviron`**. -Similarly in a Unicode (**`_wmain`**) program, **`_environ`** is initially **`NULL`** because the environment is composed of wide-character strings. Then, on the first call to **`_putenv`**, or on the first call to **`getenv`** if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by **`_environ`**. +Similarly in a Unicode (**`_wmain`**) program, **`_environ`** is initially `NULL` because the environment is composed of wide-character strings. Then, on the first call to **`_putenv`**, or on the first call to **`getenv`** if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by **`_environ`**. When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, resulting in slower execution time. For example, whenever you call **`_putenv`**, a call to **`_wputenv`** is also executed automatically, so that the two environment strings correspond. > [!CAUTION] -> In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, these two environment versions may not correspond exactly. This is because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. For more information, see [`_environ`, `_wenviron`](../../c-runtime-library/environ-wenviron.md). +> In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, these two environment versions may not correspond exactly. This is because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. For more information, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] > The **`_putenv`** and **`_getenv`** families of functions are not thread-safe. **`_getenv`** could return a string pointer while **`_putenv`** is modifying the string, causing random failures. Make sure that calls to these functions are synchronized. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tgetenv`**|**`getenv`**|**`getenv`**|**`_wgetenv`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tgetenv`** | **`getenv`** | **`getenv`** | **`_wgetenv`** | -To check or change the value of the **`TZ`** environment variable, use **`getenv`**, **`_putenv`** and **`_tzset`** as necessary. For more information about **`TZ`**, see [`_tzset`](tzset.md) and [`_daylight`, `timezone`, and `_tzname`](../../c-runtime-library/daylight-dstbias-timezone-and-tzname.md). +To check or change the value of the **`TZ`** environment variable, use **`getenv`**, **`_putenv`** and **`_tzset`** as necessary. For more information about **`TZ`**, see [`_tzset`](tzset.md) and [`_daylight`, `timezone`, and `_tzname`](../daylight-dstbias-timezone-and-tzname.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`getenv`**|``| -|**`_wgetenv`**|`` or ``| +| Routine | Required header | +|---|---| +| **`getenv`** | `` | +| **`_wgetenv`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -121,6 +121,6 @@ New LIB variable is: c:\mylib;c:\yourlib ## See also -[Process and environment control](../../c-runtime-library/process-and-environment-control.md)
-[`_putenv`, `_wputenv`](putenv-wputenv.md)
-[Environmental constants](../../c-runtime-library/environmental-constants.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md)\ +[Environmental constants](../environmental-constants.md) diff --git a/docs/c-runtime-library/reference/getmaxstdio.md b/docs/c-runtime-library/reference/getmaxstdio.md index a02cd8d13e..1be8cfb47c 100644 --- a/docs/c-runtime-library/reference/getmaxstdio.md +++ b/docs/c-runtime-library/reference/getmaxstdio.md @@ -10,7 +10,7 @@ f1_keywords: ["_getmaxstdio", "getmaxstdio"] helpviewer_keywords: ["files [C++], number open", "_getmaxstdio function", "getmaxstdio function", "open files, getting number"] ms.assetid: 700ca8ce-4a8c-4e00-9467-dfa9d6b831a0 --- -# _getmaxstdio +# `_getmaxstdio` Returns the number of simultaneously open files permitted at the stream I/O level. @@ -20,21 +20,21 @@ Returns the number of simultaneously open files permitted at the stream I/O leve int _getmaxstdio( void ); ``` -## Return Value +## Return value -Returns a number that represents the number of simultaneously open files currently permitted at the **stdio** level. +Returns a number that represents the number of simultaneously open files currently permitted at the `stdio` level. ## Remarks -Use [_setmaxstdio](setmaxstdio.md) to configure the number of simultaneously open files permitted at the **stdio** level. +Use [`_setmaxstdio`](setmaxstdio.md) to configure the number of simultaneously open files permitted at the `stdio` level. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getmaxstdio**|\| +| Routine | Required header | +|---|---| +| **`_getmaxstdio`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -63,4 +63,4 @@ int main() ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
+[Stream I/O](../stream-i-o.md) diff --git a/docs/c-runtime-library/reference/getmbcp.md b/docs/c-runtime-library/reference/getmbcp.md index 267587ff57..9b88063bff 100644 --- a/docs/c-runtime-library/reference/getmbcp.md +++ b/docs/c-runtime-library/reference/getmbcp.md @@ -3,14 +3,14 @@ description: "Learn more about: _getmbcp" title: "_getmbcp" ms.date: "4/2/2020" api_name: ["_getmbcp", "_o__getmbcp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getmbcp", "getmbcp"] helpviewer_keywords: ["code pages, determining current", "_getmbcp function", "getmbcp function"] ms.assetid: 2db202d4-5c3d-4871-a0b8-ceb0b79ee7bb --- -# _getmbcp +# `_getmbcp` Retrieves the current code page. @@ -20,22 +20,22 @@ Retrieves the current code page. int _getmbcp( void ); ``` -## Return Value +## Return value Returns the current multibyte code page. A return value of 0 indicates that a single byte code page is in use. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getmbcp**|\| +| Routine | Required header | +|---|---| +| **`_getmbcp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_setmbcp](setmbcp.md)
+[`_setmbcp`](setmbcp.md) diff --git a/docs/c-runtime-library/reference/getpid.md b/docs/c-runtime-library/reference/getpid.md index 4a4cca69b8..06357dc8d4 100644 --- a/docs/c-runtime-library/reference/getpid.md +++ b/docs/c-runtime-library/reference/getpid.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getpid"] helpviewer_keywords: ["getpid function", "_getpid function", "process identification numbers"] -ms.assetid: d3e13bae-9a0c-4f33-86d3-ec9df9519285 --- -# _getpid +# `_getpid` Gets the process identification. @@ -23,21 +22,21 @@ Gets the process identification. int _getpid( void ); ``` -## Return Value +## Return value Returns the process ID obtained from the system. There's no error return. ## Remarks -The **_getpid** function obtains the process ID from the system. The process ID uniquely identifies the calling process. +The **`_getpid`** function obtains the process ID from the system. The process ID uniquely identifies the calling process. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getpid**|\| +| Routine | Required header | +|---|---| +| **`_getpid`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -64,5 +63,5 @@ Process id: 3584 ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_mktemp, _wmktemp](mktemp-wmktemp.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_mktemp`, `_wmktemp`](mktemp-wmktemp.md) diff --git a/docs/c-runtime-library/reference/gets-s-getws-s.md b/docs/c-runtime-library/reference/gets-s-getws-s.md index 01179b2d52..963b4992a7 100644 --- a/docs/c-runtime-library/reference/gets-s-getws-s.md +++ b/docs/c-runtime-library/reference/gets-s-getws-s.md @@ -3,7 +3,7 @@ description: "Learn more about: gets_s, _getws_s" title: "gets_s, _getws_s" ms.date: "4/2/2020" api_name: ["_getws_s", "gets_s", "_o__getws_s", "_o_gets_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getws_s", "gets_s"] @@ -12,7 +12,7 @@ ms.assetid: 5880c36f-122c-4061-a1a5-aeeced6fe58c --- # `gets_s`, `_getws_s` -Gets a line from the **`stdin`** stream. These versions of [`gets`, `_getws`](../../c-runtime-library/gets-getws.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Gets a line from the **`stdin`** stream. These versions of [`gets`, `_getws`](../gets-getws.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,44 +37,44 @@ wchar_t *_getws_s( wchar_t (&buffer)[size] ); // C++ only ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for input string. -*`sizeInCharacters`*
+*`sizeInCharacters`*\ The size of the buffer. -## Return Value +## Return value -Returns *`buffer`* if successful. A **`NULL`** pointer indicates an error or end-of-file condition. Use [`ferror`](ferror.md) or [`feof`](feof.md) to determine which one has occurred. +Returns *`buffer`* if successful. A `NULL` pointer indicates an error or end-of-file condition. Use [`ferror`](ferror.md) or [`feof`](feof.md) to determine which one has occurred. ## Remarks The **`gets_s`** function reads a line from the standard input stream **`stdin`** and stores it in *`buffer`*. The line consists of all characters up to and including the first newline character ('`\n`'). **`gets_s`** then replaces the newline character with a null character ('`\0`') before returning the line. In contrast, the **`fgets_s`** function retains the newline character. -If the first character read is the end-of-file character, a null character is stored at the beginning of *`buffer`* and **`NULL`** is returned. +If the first character read is the end-of-file character, a null character is stored at the beginning of *`buffer`*, and `NULL` is returned. **`_getws_s`** is a wide-character version of **`gets_s`**; its argument and return value are wide-character strings. -If *`buffer`* is **`NULL`** or *`sizeInCharacters`* is less than or equal to zero, or if the buffer is too small to contain the input line and null terminator, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`NULL`** and set errno to **`ERANGE`**. +If *`buffer`* is `NULL` or *`sizeInCharacters`* is less than or equal to zero, or if the buffer is too small to contain the input line and null terminator, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set errno to `ERANGE`. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_getts_s`**|**`gets_s`**|**`gets_s`**|**`_getws_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_getts_s` | **`gets_s`** | **`gets_s`** | **`_getws_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`gets_s`**|``| -|**`_getws_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`gets_s`** | `` | +| **`_getws_s`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -103,8 +103,8 @@ The line entered was: Hello there! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`gets`, `_getws`](../../c-runtime-library/gets-getws.md)
-[`fgets`, `fgetws`](fgets-fgetws.md)
-[`fputs`, `fputws`](fputs-fputws.md)
-[`puts`, `_putws`](puts-putws.md)
+[Stream I/O](../stream-i-o.md)\ +[`gets`, `_getws`](../gets-getws.md)\ +[`fgets`, `fgetws`](fgets-fgetws.md)\ +[`fputs`, `fputws`](fputs-fputws.md)\ +[`puts`, `_putws`](puts-putws.md) diff --git a/docs/c-runtime-library/reference/getw.md b/docs/c-runtime-library/reference/getw.md index a9bfb192ff..77cd00f26d 100644 --- a/docs/c-runtime-library/reference/getw.md +++ b/docs/c-runtime-library/reference/getw.md @@ -3,14 +3,14 @@ description: "Learn more about: _getw" title: "_getw" ms.date: "4/2/2020" api_name: ["_getw", "_o__getw"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_getw"] helpviewer_keywords: ["_getw function", "integers, getting from streams", "getw function"] ms.assetid: ef75facc-b84e-470f-9f5f-8746c90822a0 --- -# _getw +# `_getw` Gets an integer from a stream. @@ -24,26 +24,26 @@ int _getw( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -**_getw** returns the integer value read. A return value of **EOF** indicates either an error or end of file. However, because the **EOF** value is also a legitimate integer value, use **feof** or **ferror** to verify an end-of-file or error condition. If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **EOF**. +**`_getw`** returns the integer value read. A return value of `EOF` indicates either an error or end of file. However, because the `EOF` value is also a legitimate integer value, use `feof` or `ferror` to verify an end-of-file or error condition. If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `EOF`. ## Remarks -The **_getw** function reads the next binary value of type **`int`** from the file associated with *stream* and increments the associated file pointer (if there is one) to point to the next unread character. **_getw** does not assume any special alignment of items in the stream. Problems with porting can occur with **_getw** because the size of the **`int`** type and the ordering of bytes within the **`int`** type differ across systems. +The **`_getw`** function reads the next binary value of type **`int`** from the file associated with *`stream`* and increments the associated file pointer (if one exists) to point to the next unread character. **`_getw`** doesn't assume any special alignment of items in the stream. Problems with porting can occur with **`_getw`** because the size of the **`int`** type and the ordering of bytes within the **`int`** type differ across systems. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_getw**|\| +| Routine | Required header | +|---|---| +| **`_getw`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,5 +95,5 @@ First data word in file: 0x656e694c ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_putw](putw.md)
+[Stream I/O](../stream-i-o.md)\ +[`_putw`](putw.md) diff --git a/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md b/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md index 295e47e21a..1d0656b3f7 100644 --- a/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md +++ b/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md @@ -1,14 +1,13 @@ --- title: "gmtime, _gmtime32, _gmtime64" -description: "API reference for `gmtime`, `_gmtime32`, and `_gmtime64`, which convert a `time_t` value to a `tm` structure." -ms.date: "10/27/2020" +description: "API reference for gmtime, _gmtime32, and _gmtime64, which convert a time_t value." +ms.date: 02/23/2024 api_name: ["_gmtime32", "gmtime", "_gmtime64", "_o__gmtime32", "_o__gmtime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["gmtime", "_gmtime32", "_gmtime64"] helpviewer_keywords: ["gmtime32 function", "_gmtime64 function", "gmtime function", "time functions", "_gmtime32 function", "gmtime64 function", "time structure conversion"] -ms.assetid: 315501f3-477e-475d-a414-ef100ee0db27 --- # `gmtime`, `_gmtime32`, `_gmtime64` @@ -27,46 +26,43 @@ struct tm *_gmtime64( const __time64_t *sourceTime ); *`sourceTime`*\ Pointer to the stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). -## Return Value +## Return value -A pointer to a structure of type [`tm`](../../c-runtime-library/standard-types.md). The fields of the returned structure hold the evaluated value of the *`sourceTime`* argument in UTC rather than in local time. Each of the structure fields is of type `int`, as follows: +A pointer to a structure of type [`tm`](../standard-types.md). The fields of the returned structure hold the evaluated value of the *`sourceTime`* argument in UTC rather than in local time. Each of the structure fields is of type `int`, as follows: -|Field|Description| -|-|-| -|`tm_sec`|Seconds after minute (0 - 59).| -|`tm_min`|Minutes after hour (0 - 59).| -|`tm_hour`|Hours since midnight (0 - 23).| -|`tm_mday`|Day of month (1 - 31).| -|`tm_mon`|Month (0 - 11; January = 0).| -|`tm_year`|Year (current year minus 1900).| -|`tm_wday`|Day of week (0 - 6; Sunday = 0).| -|`tm_yday`|Day of year (0 - 365; January 1 = 0).| -|`tm_isdst`|Always 0 for **gmtime**.| +| Field | Description | +|---|---| +| `tm_sec` | Seconds after minute (0 - 59). | +| `tm_min` | Minutes after hour (0 - 59). | +| `tm_hour` | Hours since midnight (0 - 23). | +| `tm_mday` | Day of month (1 - 31). | +| `tm_mon` | Month (0 - 11; January = 0). | +| `tm_year` | Year (current year minus 1900). | +| `tm_wday` | Day of week (0 - 6; Sunday = 0). | +| `tm_yday` | Day of year (0 - 365; January 1 = 0). | +| `tm_isdst` | Always 0 for **`gmtime`**. | Both the 32-bit and 64-bit versions of **`gmtime`**, [`mktime`](mktime-mktime32-mktime64.md), [`mkgmtime`](mkgmtime-mkgmtime32-mkgmtime64.md), and [`localtime`](localtime-localtime32-localtime64.md) all use one common `tm` structure per thread for the conversion. Each call to one of these functions destroys the result of any previous call. If *`sourceTime`* represents a date before midnight, January 1, 1970, **`gmtime`** returns `NULL`. There's no error return. -**_gmtime64**, which uses the `__time64_t` structure, enables dates to be expressed up through 23:59:59, December 31, 3000, UTC. **`_gmtime32`** only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both functions. +**`_gmtime64`**, which uses the `__time64_t` structure, enables dates to be expressed up through 23:59:59, December 31, 3000, UTC. **`_gmtime32`** only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both functions. -**`gmtime`** is an inline function that evaluates to **`_gmtime64`**, and `time_t` is equivalent to `__time64_t` unless `_USE_32BIT_TIME_T` is defined. If you must force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`, but doing so causes **`gmtime`** to be in-lined to **`_gmtime32`** and `time_t` to be defined as `__time32_t`. We don't recommend that you do this, because it isn't allowed on 64-bit platforms. In any case, your application may fail after January 18, 2038. +**`gmtime`** is an inline function that evaluates to **`_gmtime64`**, and `time_t` is equivalent to `__time64_t` unless `_USE_32BIT_TIME_T` is defined. If you must force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`, but doing so causes **`gmtime`** to be in-lined to **`_gmtime32`** and `time_t` to be defined as `__time32_t`. We don't recommend use of `_USE_32BIT_TIME_T`, because it isn't allowed on 64-bit platforms. In any case, your application may fail after January 18, 2038. -These functions validate their parameters. If *`sourceTime`* is a null pointer, or if the *`sourceTime`* value is negative, these functions invoke an invalid parameter handler, as described in [Parameter validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return `NULL` and set `errno` to `EINVAL`. +These functions validate their parameters. If *`sourceTime`* is a `NULL` pointer, or if the *`sourceTime`* value is negative, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `NULL` and set `errno` to `EINVAL`. ## Remarks The **`_gmtime32`** function breaks down the *`sourceTime`* value and stores it in a statically allocated structure of type `tm`, defined in `TIME.H`. The value of *`sourceTime`* is typically obtained from a call to the [`time`](time-time32-time64.md) function. -> [!NOTE] -> In most cases, the target environment tries to determine whether daylight savings time is in effect. The C run-time library assumes that the United States rules for implementing the calculation of Daylight Saving Time (DST) are used. - -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|---------------------|-| -|**`gmtime`**, **`_gmtime32`**, **`_gmtime64`**|``| `` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`gmtime`**, **`_gmtime32`**, **`_gmtime64`** | `` | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -103,7 +99,7 @@ Coordinated universal time is Tue Feb 12 23:11:31 2002 ## See also -[Time Management](../../c-runtime-library/time-management.md)\ +[Time management](../time-management.md)\ [`asctime`, `_wasctime`](asctime-wasctime.md)\ [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ [`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ diff --git a/docs/c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md b/docs/c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md index 7e8e6fbe2a..9151701714 100644 --- a/docs/c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md +++ b/docs/c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md @@ -1,18 +1,17 @@ --- description: "Learn more about: gmtime_s, _gmtime32_s, _gmtime64_s" title: "gmtime_s, _gmtime32_s, _gmtime64_s" -ms.date: "4/2/2020" +ms.date: 02/23/2024 api_name: ["_gmtime32_s", "gmtime_s", "_gmtime64_s", "_o__gmtime32_s", "_o__gmtime64_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_gmtime_s", "gmtime64_s", "gmtime32_s", "_gmtime64_s", "gmtime_s", "_gmtime32_s"] helpviewer_keywords: ["gmtime_s function", "gmtime32_s function", "time functions", "gmtime64_s function", "_gmtime64_s function", "time structure conversion", "_gmtime_s function", "_gmtime32_s function"] -ms.assetid: 261c7df0-2b0c-44ba-ba61-cb83efaec60f --- -# gmtime_s, _gmtime32_s, _gmtime64_s +# `gmtime_s`, `_gmtime32_s`, `_gmtime64_s` -Converts a time value to a **tm** structure. These are versions of [_gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a time value to a `tm` structure. These functions are versions of [`_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,60 +32,57 @@ errno_t _gmtime64_s( ### Parameters -*tmDest*
-Pointer to a [tm](../../c-runtime-library/standard-types.md) structure. The fields of the returned structure hold the evaluated value of the *timer* argument in UTC rather than in local time. +*`tmDest`*\ +Pointer to a [`tm`](../standard-types.md) structure. The fields of the returned structure hold the evaluated value of the *`timer`* argument in UTC rather than in local time. -*sourceTime*
+*`sourceTime`*\ Pointer to stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in Errno.h; for a listing of these errors, see [errno](../../c-runtime-library/errno-constants.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in `Errno.h`; for a listing of these errors, see [`errno`](../errno-constants.md). -### Error Conditions +### Error conditions -|*tmDest*|*sourceTime*|Return|Value in *tmDest*| -|-----------|------------|------------|--------------------| -|**NULL**|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|**NULL**|**EINVAL**|All fields set to -1.| -|Not **NULL**|< 0|**EINVAL**|All fields set to -1.| +| *`tmDest`* | *`sourceTime`* | Return | Value in *`tmDest`* | +|---|---|---|---| +| `NULL` | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | `NULL` | `EINVAL` | All fields set to -1. | +| Not `NULL` | < 0 | `EINVAL` | All fields set to -1. | -In the case of the first two error conditions, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EINVAL**. +The first two error conditions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -The **_gmtime32_s** function breaks down the *sourceTime* value and stores it in a structure of type **tm**, defined in Time.h. The address of the structure is passed in *tmDest*. The value of *sourceTime* is usually obtained from a call to the [time](time-time32-time64.md) function. - -> [!NOTE] -> The target environment should try to determine whether daylight savings time is in effect. The C run-time library assumes the United States rules for implementing the calculation of daylight saving time . +The **`_gmtime32_s`** function breaks down the *`sourceTime`* value and stores it in a structure of type `tm`, defined in `Time.h`. The address of the structure is passed in *`tmDest`*. The value of *`sourceTime`* is often obtained from a call to the [`time`](time-time32-time64.md) function. Each of the structure fields is of type **`int`**, as shown in the following table. -|Field|Description| -|-|-| -|**tm_sec**|Seconds after minute (0 - 59).| -|**tm_min**|Minutes after hour (0 - 59).| -|**tm_hour**|Hours since midnight (0 - 23).| -|**tm_mday**|Day of month (1 - 31).| -|**tm_mon**|Month (0 - 11; January = 0).| -|**tm_year**|Year (current year minus 1900).| -|**tm_wday**|Day of week (0 - 6; Sunday = 0).| -|**tm_yday**|Day of year (0 - 365; January 1 = 0).| -|**tm_isdst**|Always 0 for **gmtime_s**.| +| Field | Description | +|---|---| +| **`tm_sec`** | Seconds after minute (0 - 59). | +| **`tm_min`** | Minutes after hour (0 - 59). | +| **`tm_hour`** | Hours since midnight (0 - 23). | +| **`tm_mday`** | Day of month (1 - 31). | +| **`tm_mon`** | Month (0 - 11; January = 0). | +| **`tm_year`** | Year (current year minus 1900). | +| **`tm_wday`** | Day of week (0 - 6; Sunday = 0). | +| **`tm_yday`** | Day of year (0 - 365; January 1 = 0). | +| **`tm_isdst`** | Always 0 for **`gmtime_s`**. | -**_gmtime64_s**, which uses the **__time64_t** structure, allows dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **gmtime32_s** only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both these functions. +**`_gmtime64_s`**, which uses the **`__time64_t`** structure, allows dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas **`gmtime32_s`** only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both these functions. -**gmtime_s** is an inline function which evaluates to **_gmtime64_s** and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. Doing this will cause **gmtime_s** to be in-lined to **_gmtime32_s**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`gmtime_s`** is an inline function that evaluates to **`_gmtime64_s`** and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. `_USE_32BIT_TIME_T` causes **`gmtime_s`** to be inlined as **`_gmtime32_s`**. We don't recommend `_USE_32BIT_TIME_T`, because your application may fail after January 18, 2038, and because it isn't allowed on 64-bit platforms. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|---------------------|-| -|**gmtime_s**, **_gmtime32_s**, **_gmtime64_s**|\|\ or \| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`gmtime_s`**, **`_gmtime32_s`**, **`_gmtime64_s`** | `` | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -134,12 +130,12 @@ Coordinated universal time is Fri Apr 25 20:12:33 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[_mkgmtime, _mkgmtime32, _mkgmtime64](mkgmtime-mkgmtime32-mkgmtime64.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`_mkgmtime`, `_mkgmtime32`, `_mkgmtime64`](mkgmtime-mkgmtime32-mkgmtime64.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/heapchk.md b/docs/c-runtime-library/reference/heapchk.md index 23370b2a80..4e77c83690 100644 --- a/docs/c-runtime-library/reference/heapchk.md +++ b/docs/c-runtime-library/reference/heapchk.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _heapchk" title: "_heapchk" +description: "Learn more about: _heapchk" ms.date: "4/2/2020" api_name: ["_heapchk", "_o__heapchk"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_heapchk", "heapchk"] helpviewer_keywords: ["debugging [CRT], heap-related problems", "consistency checking of heaps", "heapchk function", "heaps, checking consistency", "_heapchk function"] -ms.assetid: 859619a5-1e35-4f02-9e09-11d9fa266ec0 --- -# _heapchk +# `_heapchk` Runs consistency checks on the heap. @@ -20,33 +19,33 @@ Runs consistency checks on the heap. int _heapchk( void ); ``` -## Return Value +## Return value -**_heapchk** returns one of the following integer manifest constants defined in Malloc.h. +**`_heapchk`** returns one of the following integer manifest constants defined in Malloc.h. -|Return value|Condition| -|-|-| -| **_HEAPBADBEGIN** | Initial header information is bad or cannot be found. | -| **_HEAPBADNODE** | Bad node has been found or heap is damaged. | -| **_HEAPBADPTR** | Pointer into heap is not valid. | -| **_HEAPEMPTY** | Heap has not been initialized. | -| **_HEAPOK** | Heap appears to be consistent. | +| Return value | Condition | +|---|---| +| `_HEAPBADBEGIN` | Initial header information is bad or can't be found. | +| `_HEAPBADNODE` | Bad node has been found or heap is damaged. | +| `_HEAPBADPTR` | Pointer into heap isn't valid. | +| `_HEAPEMPTY` | Heap hasn't been initialized. | +| `_HEAPOK` | Heap appears to be consistent. | -In addition, if an error occurs, **_heapchk** sets **errno** to **ENOSYS**. +In addition, if an error occurs, **`_heapchk`** sets `errno` to `ENOSYS`. ## Remarks -The **_heapchk** function helps debug heap-related problems by checking for minimal consistency of the heap. If the operating system does not support **_heapchk**(for example, Windows 98), the function returns **_HEAPOK** and sets **errno** to **ENOSYS**. +The **`_heapchk`** function helps debug heap-related problems by checking for minimal consistency of the heap. If the operating system doesn't support **`_heapchk`** (for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_heapchk**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapchk`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -93,8 +92,8 @@ OK - heap is fine ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_heapadd](../../c-runtime-library/heapadd.md)
-[_heapmin](heapmin.md)
-[_heapset](../../c-runtime-library/heapset.md)
-[_heapwalk](heapwalk.md)
+[Memory allocation](../memory-allocation.md)\ +[`_heapadd`](../heapadd.md)\ +[`_heapmin`](heapmin.md)\ +[`_heapset`](../heapset.md)\ +[`_heapwalk`](heapwalk.md) diff --git a/docs/c-runtime-library/reference/heapmin.md b/docs/c-runtime-library/reference/heapmin.md index c2586e2855..f5f5e5671a 100644 --- a/docs/c-runtime-library/reference/heapmin.md +++ b/docs/c-runtime-library/reference/heapmin.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _heapmin" title: "_heapmin" +description: "Learn more about: _heapmin" ms.date: "4/2/2020" api_name: ["_heapmin", "_o__heapmin"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_heapmin", "heapmin"] helpviewer_keywords: ["heap memory", "minimizing heaps", "memory, releasing", "heaps, releasing unused memory", "_heapmin function", "heapmin function"] -ms.assetid: c0bccdf6-2d14-4d7b-a7ff-d6a17bdb410f --- -# _heapmin +# `_heapmin` Releases unused heap memory to the operating system. @@ -20,32 +19,32 @@ Releases unused heap memory to the operating system. int _heapmin( void ); ``` -## Return Value +## Return value -If successful, **_heapmin** returns 0; otherwise, the function returns -1 and sets **errno** to **ENOSYS**. +If successful, **`_heapmin`** returns 0; otherwise, the function returns -1 and sets `errno` to `ENOSYS`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_heapmin** function minimizes the heap by releasing unused heap memory to the operating system. If the operating system does not support **_heapmin**(for example, Windows 98), the function returns -1 and sets **errno** to **ENOSYS**. +The **`_heapmin`** function minimizes the heap by releasing unused heap memory to the operating system. If the operating system doesn't support **`_heapmin`** (for example, Windows 98), the function returns -1 and sets `errno` to `ENOSYS`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_heapmin**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapmin`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[free](free.md)
-[_heapadd](../../c-runtime-library/heapadd.md)
-[_heapchk](heapchk.md)
-[_heapset](../../c-runtime-library/heapset.md)
-[_heapwalk](heapwalk.md)
-[malloc](malloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`free`](free.md)\ +[`_heapadd`](../heapadd.md)\ +[`_heapchk`](heapchk.md)\ +[`_heapset`](../heapset.md)\ +[`_heapwalk`](heapwalk.md)\ +[`malloc`](malloc.md) diff --git a/docs/c-runtime-library/reference/heapwalk.md b/docs/c-runtime-library/reference/heapwalk.md index 4a4b4c4b96..451669de78 100644 --- a/docs/c-runtime-library/reference/heapwalk.md +++ b/docs/c-runtime-library/reference/heapwalk.md @@ -10,7 +10,7 @@ f1_keywords: ["heapwalk", "_heapwalk"] helpviewer_keywords: ["debugging [CRT], heap-related problems", "heapwalk function", "_heapwalk function"] ms.assetid: 2df67649-fb00-4570-a8b1-a4eca5738744 --- -# _heapwalk +# `_heapwalk` Traverses the heap and returns information about the next entry. @@ -25,45 +25,45 @@ int _heapwalk( _HEAPINFO *entryinfo ); ### Parameters -*entryinfo*
+*`entryinfo`*\ Buffer to contain heap information. -## Return Value +## Return value -**_heapwalk** returns one of the following integer manifest constants defined in Malloc.h. +**`_heapwalk`** returns one of the following integer manifest constants defined in Malloc.h. -|Return value|Meaning| -|-|-| -|**_HEAPBADBEGIN**| Initial header information invalid or not found.| -|**_HEAPBADNODE**| Heap damaged or bad node found.| -|**_HEAPBADPTR**| The **_pentry** field of the **_HEAPINFO** structure does not contain a valid pointer into the heap or *entryinfo* is a null pointer.| -|**_HEAPEND**| End of the heap reached successfully.| -|**_HEAPEMPTY**| Heap not initialized.| -|**_HEAPOK**| No errors so far; *entryinfo* is updated with information about the next heap entry.| +| Return value | Meaning | +|---|---| +| `_HEAPBADBEGIN` | Initial header information invalid or not found. | +| `_HEAPBADNODE` | Heap damaged or bad node found. | +| `_HEAPBADPTR` | The `_pentry` field of the `_HEAPINFO` structure doesn't contain a valid pointer into the heap or *`entryinfo`* is a null pointer. | +| `_HEAPEND` | End of the heap reached successfully. | +| `_HEAPEMPTY` | Heap not initialized. | +| `_HEAPOK` | No errors so far; *`entryinfo`* is updated with information about the next heap entry. | -In addition, if an error occurs, **_heapwalk** sets **errno** to **ENOSYS**. +In addition, if an error occurs, **`_heapwalk`** sets `errno` to `ENOSYS`. ## Remarks -The **_heapwalk** function helps debug heap-related problems in programs. The function walks through the heap, traversing one entry per call, and returns a pointer to a structure of type **_HEAPINFO** that contains information about the next heap entry. The **_HEAPINFO** type, defined in Malloc.h, contains the following elements. +The **`_heapwalk`** function helps debug heap-related problems in programs. The function walks through the heap, traversing one entry per call, and returns a pointer to a structure of type `_HEAPINFO` that contains information about the next heap entry. The `_HEAPINFO` type, defined in Malloc.h, contains the following elements. -|Field|Meaning| -|-|-| -|`int *_pentry`|Heap entry pointer.| -|`size_t _size`|Size of the heap entry.| -|`int _useflag`|Flag that indicates whether the heap entry is in use.| +| Field | Meaning | +|---|---| +| `int *_pentry` | Heap entry pointer. | +| `size_t _size` | Size of the heap entry. | +| `int _useflag` | Flag that indicates whether the heap entry is in use. | -A call to **_heapwalk** that returns **_HEAPOK** stores the size of the entry in the **_size** field and sets the **_useflag** field to either **_FREEENTRY** or **_USEDENTRY** (both are constants defined in Malloc.h). To obtain this information about the first entry in the heap, pass **_heapwalk** a pointer to a **_HEAPINFO** structure whose **_pentry** member is **NULL**. If the operating system does not support **_heapwalk**(for example, Windows 98), the function returns **_HEAPEND** and sets **errno** to **ENOSYS**. +A call to **`_heapwalk`** that returns `_HEAPOK` stores the size of the entry in the `_size` field and sets the `_useflag` field to either `_FREEENTRY` or `_USEDENTRY` (both are constants defined in Malloc.h). To obtain this information about the first entry in the heap, pass **`_heapwalk`** a pointer to a `_HEAPINFO` structure whose `_pentry` member is `NULL`. If the operating system doesn't support **`_heapwalk`**, the function returns `_HEAPEND` and sets `errno` to `ENOSYS`. -This function validates its parameter. If *entryinfo* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **_HEAPBADPTR**. +This function validates its parameter. If *`entryinfo`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `_HEAPBADPTR`. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_heapwalk**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapwalk`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,8 +150,8 @@ OK - end of heap ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_heapadd](../../c-runtime-library/heapadd.md)
-[_heapchk](heapchk.md)
-[_heapmin](heapmin.md)
-[_heapset](../../c-runtime-library/heapset.md)
+[Memory allocation](../memory-allocation.md)\ +[`_heapadd`](../heapadd.md)\ +[`_heapchk`](heapchk.md)\ +[`_heapmin`](heapmin.md)\ +[`_heapset`](../heapset.md) diff --git a/docs/c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md b/docs/c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md index 0ad4f55351..d447ac7df1 100644 --- a/docs/c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md +++ b/docs/c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md @@ -3,14 +3,14 @@ title: "hypot, hypotf, hypotl, _hypot, _hypotf, _hypotl" description: "API reference for hypot, hypotf, hypotl, _hypot, _hypotf, and _hypotl; which calculate the hypotenuse." ms.date: "9/1/2020" api_name: ["_hypotf", "hypot", "hypotf", "_hypot", "_hypotl", "hypotl", "_o__hypot", "_o__hypotf", "_o_hypot"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["hypotf", "hypotl", "_hypotl", "hypot", "_hypot", "_hypotf"] helpviewer_keywords: ["hypotenuse calculation", "hypot function", "hypotf function", "triangles, calculating hypotenuse", "hypotl function", "calculating hypotenuses", "_hypot function"] ms.assetid: 6a13887f-bd53-43fc-9d77-5b42d6e49925 --- -# hypot, hypotf, hypotl, _hypot, _hypotf, _hypotl +# `hypot`, `hypotf`, `hypotl`, `_hypot`, `_hypotf`, `_hypotl` Calculates the hypotenuse. @@ -46,33 +46,33 @@ long double _hypotl( ### Parameters -*x*, *y*\ +*`x`*, *`y`*\ Floating-point values. -## Return Value +## Return value -If successful, **hypot** returns the length of the hypotenuse; on overflow, **hypot** returns INF (infinity) and the **errno** variable is set to **ERANGE**. You can use **_matherr** to modify error handling. +If successful, **`hypot`** returns the length of the hypotenuse; on overflow, **`hypot`** returns INF (infinity) and the `errno` variable is set to `ERANGE`. You can use `_matherr` to modify error handling. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **hypot** functions calculate the length of the hypotenuse of a right triangle, given the length of the two sides *x* and *y* (in other words, the square root of *x*2 + *y*2). +The **`hypot`** functions calculate the length of the hypotenuse of a right triangle, given the length of the two sides *`x`* and *`y`* (in other words, the square root of *`x`*2 + *`y`*2). The versions of the functions that have leading underscores are provided for compatibility with earlier standards. Their behavior is identical to the versions that don't have leading underscores. We recommend using the versions without leading underscores for new code. -If you use the \ `hypot()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `hypot()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**hypot**, **hypotf**, **hypotl**, **_hypot**, **_hypotf**, **_hypotl**|\| -|**hypot** macro | \ | +| Routine | Required header | +|---|---| +| **`hypot`**, **`hypotf`**, **`hypotl`**, **`_hypot`**, **`_hypotf`**, **`_hypotl`** | \ | +| **`hypot`** macro | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,6 +98,6 @@ If a right triangle has sides 3.0 and 4.0, its hypotenuse is 5.0 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_cabs](cabs.md)
-[_matherr](matherr.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_cabs`](cabs.md)\ +[`_matherr`](matherr.md) diff --git a/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md b/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md index 5d800550d7..b75d22d40b 100644 --- a/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md +++ b/docs/c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md @@ -10,7 +10,7 @@ f1_keywords: ["ilogb", "ilogbf", "ilogbl", "math/ilogb", "math/ilogbf", "math/il helpviewer_keywords: ["ilogb function", "ilogbf function", "ilogbl function"] ms.assetid: 9ef19d57-1caa-41d5-8233-2faad3562fcb --- -# ilogb, ilogbf, ilogbl +# `ilogb`, `ilogbf`, `ilogbl` Retrieves an integer that represents the unbiased base-2 exponent of the specified value. @@ -42,41 +42,41 @@ int ilogbl( ### Parameters -*x*\ +*`x`*\ The specified value. -## Return Value +## Return value -If successful, return the base-2 exponent of *x* as a **`signed int`** value. +If successful, these functions return the base-2 exponent of *`x`* as a **`signed int`** value. -Otherwise, returns one of the following values, defined in \: +Otherwise, the functions return one of the following values, defined in \: -|Input|Result| -|-----------|------------| -|±0|FP_ILOGB0| -|±inf, ±nan, indefinite|FP_ILOGBNAN| +| Input | Result | +|---|---| +| ±0 | `FP_ILOGB0` | +| ± INF, ± NAN, IND | `FP_ILOGBNAN` | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **ilogb** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **ilogb** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`ilogb`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`ilogb`** always takes and returns a **`double`**. -If you use the \ `ilogb()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `ilogb()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -Calling this function is similar to calling the equivalent **logb** function, then casting the return value to **`int`**. +Calling this function is similar to calling the equivalent `logb` function, then casting the return value to **`int`**. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ilogb**, **ilogbf**, **ilogbl**|\|\| -|**ilogb** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`ilogb`**, **`ilogbf`**, **`ilogbl`** | \ | \ | +| **`ilogb`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[frexp](frexp.md)
-[logb, logbf, logbl, _logb, _logbf](logb-logbf-logbl-logb-logbf.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`frexp`](frexp.md)\ +[`logb`, `logbf`, `logbl`, `_logb`, `_logbf`](logb-logbf-logbl-logb-logbf.md) diff --git a/docs/c-runtime-library/reference/imaxabs.md b/docs/c-runtime-library/reference/imaxabs.md index f7d094bb38..ee9fa1fc50 100644 --- a/docs/c-runtime-library/reference/imaxabs.md +++ b/docs/c-runtime-library/reference/imaxabs.md @@ -10,7 +10,7 @@ f1_keywords: ["imaxabs"] helpviewer_keywords: ["imaxabs function"] ms.assetid: de2566a3-1415-4e9a-91b5-7ac3a49ebf5e --- -# imaxabs +# `imaxabs` Calculates the absolute value of an integer of any size. @@ -24,27 +24,27 @@ intmax_t imaxabs( ### Parameters -*n*
+*`n`*\ Integer value. -## Return Value +## Return value -The **imaxabs** function returns the absolute value of the argument. There's no error return. +The **`imaxabs`** function returns the absolute value of the argument. There's no error return. > [!NOTE] -> Because the range of negative integers that can be represented by using **intmax_t** is larger than the range of positive integers that can be represented, it's possible to supply an argument to **imaxabs** that can't be converted. If the absolute value of the argument cannot be represented by the return type, the behavior of **imaxabs** is undefined. +> Because the range of negative integers that can be represented by using `intmax_t` is larger than the range of positive integers that can be represented, it's possible to supply an argument to **`imaxabs`** that can't be converted. If the absolute value of the argument cannot be represented by the return type, the behavior of **`imaxabs`** is undefined. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**imaxabs**|\| +| Routine | Required header | +|---|---| +| **`imaxabs`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -72,8 +72,8 @@ The absolute value of -9223372036854775806 is 9223372036854775806 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[abs, labs, llabs, _abs64](abs-labs-llabs-abs64.md)
-[_cabs](cabs.md)
-[fabs, fabsf, fabsl](fabs-fabsf-fabsl.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md)\ +[`_cabs`](cabs.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md) diff --git a/docs/c-runtime-library/reference/imaxdiv.md b/docs/c-runtime-library/reference/imaxdiv.md index c52da1af66..23e748400d 100644 --- a/docs/c-runtime-library/reference/imaxdiv.md +++ b/docs/c-runtime-library/reference/imaxdiv.md @@ -10,7 +10,7 @@ f1_keywords: ["imaxdiv"] helpviewer_keywords: ["imaxdiv function"] ms.assetid: 7d90126f-fdc2-4986-9cdf-94e4c9123d26 --- -# imaxdiv +# `imaxdiv` Computes the quotient and the remainder of two integer values of any size as a single operation. @@ -25,27 +25,27 @@ imaxdiv_t imaxdiv( ### Parameters -*numer*
+*`numer`*\ The numerator. -*denom*
+*`denom`*\ The denominator. -## Return Value +## Return value -**imaxdiv** called with arguments of type [intmax_t](../../c-runtime-library/standard-types.md) returns a structure of type [imaxdiv_t](../../c-runtime-library/standard-types.md) that comprises the quotient and the remainder. +**`imaxdiv`**, called with arguments of type [`intmax_t`](../standard-types.md), returns a structure of type [`imaxdiv_t`](../standard-types.md) that comprises the quotient and the remainder. ## Remarks -The **imaxdiv** function divides *numer* by *denom* and thereby computes the quotient and the remainder. The **imaxdiv_t** structure contains the quotient, **intmax_t** **quot**, and the remainder, **intmax_t** **rem**. The sign of the quotient is the same as that of the mathematical quotient. Its absolute value is the largest integer that is less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. +The **`imaxdiv`** function divides *`numer`* by *`denom`* and thereby computes the quotient and the remainder. The `imaxdiv_t` structure contains the quotient, `intmax_t` `quot`, and the remainder, `intmax_t` **`rem`**. The sign of the quotient is the same as the sign of the mathematical quotient. Its absolute value is the largest integer that's less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**imaxdiv**|\| +| Routine | Required header | +|---|---| +| **`imaxdiv`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -84,6 +84,6 @@ results in a quotient of 1079252848505, and a remainder of 5170 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[div](div.md)
-[ldiv, lldiv](./div.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`div`](div.md)\ +[`ldiv`, `lldiv`](./div.md) diff --git a/docs/c-runtime-library/reference/initterm-initterm-e.md b/docs/c-runtime-library/reference/initterm-initterm-e.md index c031a4a9d9..3063706706 100644 --- a/docs/c-runtime-library/reference/initterm-initterm-e.md +++ b/docs/c-runtime-library/reference/initterm-initterm-e.md @@ -10,7 +10,7 @@ f1_keywords: ["_initterm_e", "initterm", "_initterm", "initterm_e"] helpviewer_keywords: ["initterm function", "initterm_e function", "_initterm function", "_initterm_e function"] ms.assetid: 85131efe-c747-429a-8897-bcdedb000172 --- -# _initterm, _initterm_e +# `_initterm`, `_initterm_e` Internal methods that walk a table of function pointers and initialize them. @@ -25,21 +25,21 @@ void __cdecl _initterm( ); int __cdecl _initterm_e( - PVFV *, - PVFV * + PIFV *, + PIFV * ); ``` -## Return Value +## Return value A non-zero error code if an initialization fails and throws an error; 0 if no error occurs. ## Remarks -These methods are only called internally during the initialization of a C++ program. Do not call these methods in a program. +These methods are only called internally during the initialization of a C++ program. Don't call these methods in a program. -When these methods walk a table of function entries, they skip **NULL** entries and continue. +When these methods walk a table of function entries, they skip `NULL` entries and continue. ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/invalid-parameter-functions.md b/docs/c-runtime-library/reference/invalid-parameter-functions.md index 0bbc02863b..8cd25d6787 100644 --- a/docs/c-runtime-library/reference/invalid-parameter-functions.md +++ b/docs/c-runtime-library/reference/invalid-parameter-functions.md @@ -3,13 +3,12 @@ description: "Learn more about: _invalid_parameter, _invalid_parameter_noinfo, _ title: "_invalid_parameter, _invalid_parameter_noinfo, _invalid_parameter_noinfo_noreturn, _invoke_watson" ms.date: "4/2/2020" api_name: ["_invalid_parameter", "_invalid_parameter_noinfo", "_invalid_parameter_noinfo_noreturn", "_invoke_watson", "_o__invalid_parameter_noinfo", "_o__invalid_parameter_noinfo_noreturn"] -api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CORECRT/_invalid_parameter", "_invalid_parameter", "CORECRT/_invalid_parameter_noinfo", "_invalid_parameter_noinfo", "CORECRT/_invalid_parameter_noinfo_noreturn", "_invalid_parameter_noinfo_noreturn", "CORECRT/_invoke_watson", "_invoke_watson"] -ms.assetid: a4d6f1fd-ce56-4783-8719-927151a7a814 --- -# _invalid_parameter, _invalid_parameter_noinfo, _invalid_parameter_noinfo_noreturn, _invoke_watson +# `_invalid_parameter`, `_invalid_parameter_noinfo`, `_invalid_parameter_noinfo_noreturn`, `_invoke_watson` These functions are used by the C Runtime Library to handle non-valid parameters passed to CRT Library functions. Your code may also use these functions to support default or customizable handling of non-valid parameters. @@ -41,48 +40,48 @@ _invoke_watson( ## Parameters -*expression*
-A string representing the source code parameter expression that is not valid. +*`expression`*\ +A string representing the source code parameter expression that isn't valid. -*function_name*
+*`function_name`*\ The name of the function that called the handler. -*file_name*
+*`file_name`*\ The source code file where the handler was called. -*line_number*
+*`line_number`*\ The line number in the source code where the handler was called. -*reserved*
+*`reserved`*\ Unused. -## Return Value +## Return value -These functions do not return a value. The **_invalid_parameter_noinfo_noreturn** and **_invoke_watson** functions do not return to the caller, and in some cases, **_invalid_parameter** and **_invalid_parameter_noinfo** may not return to the caller. +These functions don't return a value. The **`_invalid_parameter_noinfo_noreturn`** and **`_invoke_watson`** functions don't return to the caller, and in some cases, **`_invalid_parameter`** and **`_invalid_parameter_noinfo`** may not return to the caller. ## Remarks -When C runtime library functions are passed non-valid parameters, the library functions call an *invalid parameter handler*, a function that may be specified by the programmer to do any of several things. For example, it may report the issue to the user, write to a log, break in a debugger, terminate the program, or do nothing at all. If no function is specified by the programmer, a default handler, **_invoke_watson**, is called. +When C runtime library functions are passed non-valid parameters, the library functions call an *invalid parameter handler*, a function that may be specified by the programmer to do any of several things. For example, it may report the issue to the user, write to a log, break in a debugger, terminate the program, or do nothing at all. If no function is specified by the programmer, a default handler, **`_invoke_watson`**, is called. -By default, when a non-valid parameter is identified in debug code, CRT library functions call the function **_invalid_parameter** using verbose parameters. In non-debug code, the **_invalid_parameter_noinfo** function is called, which calls the **_invalid_parameter** function using empty parameters. If the non-debug CRT library function requires program termination, the **_invalid_parameter_noinfo_noreturn** function is called, which calls the **_invalid_parameter** function using empty parameters, followed by a call to the **_invoke_watson** function to force program termination. +By default, when a non-valid parameter is identified in debug code, CRT library functions call the function **`_invalid_parameter`** using verbose parameters. In non-debug code, the **`_invalid_parameter_noinfo`** function is called, which calls the **`_invalid_parameter`** function using empty parameters. If the non-debug CRT library function requires program termination, the **`_invalid_parameter_noinfo_noreturn`** function is called, which calls the **`_invalid_parameter`** function using empty parameters, followed by a call to the **`_invoke_watson`** function to force program termination. -The **_invalid_parameter** function checks whether a user-defined invalid parameter handler was set, and if so, calls it. For example, if a user-defined thread-local handler was set by a call to [set_thread_local_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) in the current thread, it is called, then the function returns. Otherwise, if a user-defined global invalid parameter handler was set by a call to [set_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md), it is called, then the function returns. Otherwise, the default handler **_invoke_watson** is called. The default behavior of **_invoke_watson** is to terminate the program. User-defined handlers may terminate or return. We recommend that user-defined handlers terminate the program unless recovery is certain. +The **`_invalid_parameter`** function checks whether a user-defined invalid parameter handler was set, and if so, calls it. For example, if a user-defined thread-local handler was set by a call to [`set_thread_local_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) in the current thread, it's called, then the function returns. Otherwise, if a user-defined global invalid parameter handler was set by a call to [`set_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md), it's called, then the function returns. Otherwise, the default handler **`_invoke_watson`** is called. The default behavior of **`_invoke_watson`** is to terminate the program. User-defined handlers may terminate or return. We recommend that user-defined handlers terminate the program unless recovery is certain. -When the default handler **_invoke_watson** is called, if the processor supports a [__fastfail](../../intrinsics/fastfail.md) operation, it is invoked using a parameter of **FAST_FAIL_INVALID_ARG** and the process terminates. Otherwise, a fast fail exception is raised, which can be caught by an attached debugger. If the process is allowed to continue, it is terminated by a call to the Windows **TerminateProcess** function using an exception code status of **STATUS_INVALID_CRUNTIME_PARAMETER**. +When the default handler **`_invoke_watson`** is called, if the processor supports a [`__fastfail`](../../intrinsics/fastfail.md) operation, it's invoked using a parameter of `FAST_FAIL_INVALID_ARG` and the process terminates. Otherwise, a fast fail exception is raised, which can be caught by an attached debugger. If the process is allowed to continue, it's terminated by a call to the Windows `TerminateProcess` function using an exception code status of `STATUS_INVALID_CRUNTIME_PARAMETER`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|------------------| -|**_invalid_parameter**, **_invalid_parameter_noinfo**, **_invalid_parameter_noinfo_noreturn**, **_invoke_watson**|\| +| Function | Required header | +|---|---| +| **`_invalid_parameter`**, **`_invalid_parameter_noinfo`**, **`_invalid_parameter_noinfo_noreturn`**, **`_invoke_watson`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler](get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md)
-[_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md)
-[Parameter Validation](../../c-runtime-library/parameter-validation.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_get_invalid_parameter_handler`, `_get_thread_local_invalid_parameter_handler`](get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md)\ +[`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`](set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md)\ +[Parameter validation](../parameter-validation.md) diff --git a/docs/c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md b/docs/c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md index ebf4bd92fe..3ad194f700 100644 --- a/docs/c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md +++ b/docs/c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isalnum, iswalnum, _isalnum_l, _iswalnum_l" title: "isalnum, iswalnum, _isalnum_l, _iswalnum_l" ms.date: "4/2/2020" api_name: ["_iswalnum_l", "_isalnum_l", "iswalnum", "isalnum", "_o_isalnum", "_o_iswalnum"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_istalnum_l", "_iswalnum_l", "iswalnum", "_isalnum_l", "isalnum", "_istalnum"] helpviewer_keywords: ["_istalnum function", "_ismbcalnum_l function", "iswalnum function", "isalnum function", "istalnum function", "_isalnum_l function", "_istalnum_l function", "_iswalnum_l function"] ms.assetid: 0dc51306-ade8-4944-af27-e4176fc89093 --- -# isalnum, iswalnum, _isalnum_l, _iswalnum_l +# `isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l` Determines whether an integer represents an alphanumeric character. @@ -25,44 +25,44 @@ int _iswalnum_l( wint_t c, _locale_t locale ); ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of an alphanumeric character. **isalnum** returns a nonzero value if either **isalpha** or **isdigit** is nonzero for *c*, that is, if *c* is within the ranges A - Z, a - z, or 0 - 9. **iswalnum** returns a nonzero value if either **iswalpha** or **iswdigit** is nonzero for *c*. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of an alphanumeric character. **`isalnum`** returns a nonzero value if either `isalpha` or `isdigit` is nonzero for *`c`*, that is, if *`c`* is within the ranges A - Z, a - z, or 0 - 9. **`iswalnum`** returns a nonzero value if either `iswalpha` or `iswdigit` is nonzero for *`c`*. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -The behavior of **isalnum** and **_isalnum_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isalnum`** and **`_isalnum_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istalnum**|**isalnum**|[_ismbcalnum](ismbcalnum-functions.md)|**iswalnum**| -|**_istalnum_l**|**_isalnum_l**|**_ismbcalnum_l**|**_iswalnum_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istalnum` | **`isalnum`** | [`_ismbcalnum`](ismbcalnum-functions.md) | **`iswalnum`** | +| **`_istalnum_l`** | **`_isalnum_l`** | **`_ismbcalnum_l`** | **`_iswalnum_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isalnum**|\| -|**iswalnum**|\ or \| -|**_isalnum_l**|\| -|**_iswalnum_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isalnum`** | \ | +| **`iswalnum`** | \ or \ | +| **`_isalnum_l`** | \ | +| **`_iswalnum_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md b/docs/c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md index a63cd40cc0..925042ca3f 100644 --- a/docs/c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md +++ b/docs/c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isalpha, iswalpha, _isalpha_l, _iswalpha_l" title: "isalpha, iswalpha, _isalpha_l, _iswalpha_l" ms.date: "4/2/2020" api_name: ["iswalpha", "_iswalpha_l", "isalpha", "_isalpha_l", "_o_isalpha", "_o_iswalpha"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_istalpha", "_ismbcalpha_l", "isalpha", "_isalpha_l", "iswalpha", "_istalpha_l", "_iswalpha_l"] helpviewer_keywords: ["_iswalpha_l function", "_isalpha_l function", "_ismbcalpha_l function", "_istalpha_l function", "_ismbcalpha function", "isalpha function", "iswalpha function", "istalpha function", "_istalpha function"] ms.assetid: ed6cc2be-c4b0-4475-87ac-bc06d8c23064 --- -# isalpha, iswalpha, _isalpha_l, _iswalpha_l +# `isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l` Determines whether an integer represents an alphabetic character. @@ -35,44 +35,44 @@ int _iswalpha_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ The locale to use instead of the current locale. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of an alphabetic character. **isalpha** returns a nonzero value if *c* is within the ranges A - Z or a - z. **iswalpha** returns a nonzero value only for wide characters for which [iswupper](isupper-isupper-l-iswupper-iswupper-l.md) or **iswlower** is nonzero; that is, for any wide character that is one of an implementation-defined set for which none of **iswcntrl**, **iswdigit**, **iswpunct**, or **iswspace** is nonzero. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of an alphabetic character. **`isalpha`** returns a nonzero value if *`c`* is within the ranges A - Z or a - z. **`iswalpha`** returns a nonzero value only for wide characters for which [`iswupper`](isupper-isupper-l-iswupper-iswupper-l.md) or `iswlower` is nonzero; that is, for any wide character that is one of an implementation-defined set for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -The behavior of **isalpha** and **_isalpha_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isalpha`** and **`_isalpha_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istalpha**|**isalpha**|**_ismbcalpha**|**iswalpha**| -|**_istalpha_l**|**_isalpha_l**|**_ismbcalpha_l**|**_iswalpha_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istalpha` | **`isalpha`** | **`_ismbcalpha`** | **`iswalpha`** | +| `_istalpha_l` | **`_isalpha_l`** | **`_ismbcalpha_l`** | **`_iswalpha_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isalpha**|\| -|**iswalpha**|\ or \| -|**_isalpha_l**|\| -|**_iswalpha_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isalpha`** | \ | +| **`iswalpha`** | \ or \ | +| **`_isalpha_l`** | \ | +| **`_iswalpha_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isascii-isascii-iswascii.md b/docs/c-runtime-library/reference/isascii-isascii-iswascii.md index 79b9de1c7a..6e19c5b19e 100644 --- a/docs/c-runtime-library/reference/isascii-isascii-iswascii.md +++ b/docs/c-runtime-library/reference/isascii-isascii-iswascii.md @@ -3,7 +3,7 @@ description: "Learn more about: isascii, __isascii, iswascii" title: "isascii, __isascii, iswascii" ms.date: "4/2/2020" api_name: ["iswascii", "__isascii", "_o_iswascii"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswascii", "istascii", "__isascii", "_istascii", "isascii", "ctype/isascii", "ctype/__isascii", "corecrt_wctype/iswascii"] @@ -29,10 +29,10 @@ int iswascii( ### Parameters -*`c`*
+*`c`*\ Integer to test. -## Return Value +## Return value Each of these routines returns nonzero if *`c`* is a particular representation of an ASCII character. **`__isascii`** returns a nonzero value if *`c`* is an ASCII character (in the range 0x00 - 0x7F). **`iswascii`** returns a nonzero value if *`c`* is a wide-character representation of an ASCII character. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. @@ -44,23 +44,23 @@ For backward compatibility, **`isascii`** is implemented as a macro only if [`__ By default, this function's global state is scoped to the application. To change this scope, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_istascii`**|**`__isascii`**|**`__isascii`**|**`iswascii`**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_istascii`** | **`__isascii`** | **`__isascii`** | **`iswascii`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`isascii`**, **`__isascii`**|C: \

C++: \ or \| -|**`iswascii`**|C: \, \, or \

C++: \, \, \, \, or \| +| Routine | Required header | +|---|---| +| **`isascii`**, **`__isascii`** | C: \

C++: \ or \ | +| **`iswascii`** | C: \, \, or \

C++: \, \, \, \, or \ | -The **`isascii`**, **`__isascii`**, and **`iswascii`** functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`isascii`**, **`__isascii`**, and **`iswascii`** functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[`is`, `isw` Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isatty.md b/docs/c-runtime-library/reference/isatty.md index 0bb7e37c72..f519466ad9 100644 --- a/docs/c-runtime-library/reference/isatty.md +++ b/docs/c-runtime-library/reference/isatty.md @@ -3,14 +3,14 @@ description: "Learn more about: _isatty" title: "_isatty" ms.date: "4/2/2020" api_name: ["_isatty", "_o__isatty"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_isatty"] helpviewer_keywords: ["isatty function", "character device checking", "_isatty function", "checking character devices"] ms.assetid: 9f1b2e87-0cd7-4079-b187-f2b7ca15fcbe --- -# _isatty +# `_isatty` Determines whether a file descriptor is associated with a character device. @@ -22,32 +22,32 @@ int _isatty( int fd ); ### Parameters -*fd*
+*`fd`*\ File descriptor that refers to the device to be tested. -## Return Value +## Return value -**_isatty** returns a nonzero value if the descriptor is associated with a character device. Otherwise, **_isatty** returns 0. +**`_isatty`** returns a nonzero value if the descriptor is associated with a character device. Otherwise, **`_isatty`** returns 0. ## Remarks -The **_isatty** function determines whether *fd* is associated with a character device (a terminal, console, printer, or serial port). +The **`_isatty`** function determines whether *`fd`* is associated with a character device (a terminal, console, printer, or serial port). -This function validates the *fd* parameter. If *fd* is a bad file pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets **errno** to **EBADF**. +This function validates the *`fd`* parameter. If *`fd`* is a bad file pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets `errno` to `EBADF`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_isatty**|\| +| Routine | Required header | +|---|---| +| **`_isatty`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -69,7 +69,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output stdout has not been redirected to a file @@ -77,4 +77,4 @@ stdout has not been redirected to a file ## See also -[File Handling](../../c-runtime-library/file-handling.md)
+[File handling](../file-handling.md) diff --git a/docs/c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md b/docs/c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md index a753a1c56d..060de16da2 100644 --- a/docs/c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md +++ b/docs/c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md @@ -3,13 +3,13 @@ description: "Learn more about: isblank, iswblank, _isblank_l, _iswblank_l" title: "isblank, iswblank, _isblank_l, _iswblank_l" ms.date: "4/2/2020" api_name: ["isblank", "_isblank_l", "iswblank", "_iswblank_l", "_o_isblank", "_o_iswblank"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_iswblank_l", "isblank", "_istblank_l", "_istblank", "_isblank_l", "iswblank"] ms.assetid: 33ce96c0-f387-411a-8283-c3d2a69e56bd --- -# isblank, iswblank, _isblank_l, _iswblank_l +# `isblank`, `iswblank`, `_isblank_l`, `_iswblank_l` Determines whether an integer represents a blank character. @@ -34,44 +34,44 @@ int _iswblank_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a space or horizontal tab character, or is one of a locale-specific set of characters that are used to separate words within a line of text. **isblank** returns a nonzero value if *c* is a space character (0x20) or horizontal tab character (0x09). The result of the test condition for the **isblank** functions depends on the **LC_CTYPE** category setting of the locale; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The versions of these functions that do not have the **_l** suffix use the current locale for any locale-dependent behavior; the versions that do have the **_l** suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these routines returns nonzero if *`c`* is a particular representation of a space or horizontal tab character, or is one of a locale-specific set of characters that are used to separate words within a line of text. **`isblank`** returns a nonzero value if *`c`* is a space character (0x20) or horizontal tab character (0x09). The result of the test condition for the **`isblank`** functions depends on the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the `_l` suffix use the current locale for any locale-dependent behavior; the versions that do have the `_l` suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -**iswblank** returns a nonzero value if *c* is a wide character that corresponds to a standard space or horizontal tab character. +**`iswblank`** returns a nonzero value if *`c`* is a wide character that corresponds to a standard space or horizontal tab character. -The behavior of **isblank** and **_isblank_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isblank`** and **`_isblank_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istblank**|**isblank**|[_ismbcblank](ismbcgraph-functions.md)|**iswblank**| -|**_istblank_l**|**_isblank_l**|[_ismbcblank_l](ismbcgraph-functions.md)|**_iswblank_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istblank` | **`isblank`** | [`_ismbcblank`](ismbcgraph-functions.md) | **`iswblank`** | +| **`_istblank_l`** | **`_isblank_l`** | [`_ismbcblank_l`](ismbcgraph-functions.md) | **`_iswblank_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isblank**|\| -|**iswblank**|\ or \| -|**_isblank_l**|\| -|**_iswblank_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isblank`** | \ | +| **`iswblank`** | \ or \ | +| **`_isblank_l`** | \ | +| **`_iswblank_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md b/docs/c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md index f4157e1f96..824ccd0046 100644 --- a/docs/c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md +++ b/docs/c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md @@ -3,14 +3,14 @@ description: "Learn more about: iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l" title: "iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l" ms.date: "4/2/2020" api_name: ["iscntrl", "_iswcntrl_l", "_iscntrl_l", "iswcntrl", "_o_iscntrl", "_o_iswcntrl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_istcntrl_l", "_iswcntrl_l", "iswcntrl", "_iscntrl_l", "iscntrl", "_istcntrl"] helpviewer_keywords: ["iscntrl function", "_iscntrl_l function", "_iswcntrl_l function", "_istcntrl function", "istcntrl function", "iswcntrl function", "_istcntrl_l function"] ms.assetid: 616eebf9-aed4-49ba-ba2c-8677c8fe6fb5 --- -# iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l +# `iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l` Determines whether an integer represents a control character. @@ -35,44 +35,44 @@ int _iswcntrl_l( ### Parameters -*c*
+*`c`*\ Integer to test -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a control character. **iscntrl** returns a nonzero value if *c* is a control character (0x00 - 0x1F or 0x7F). **iswcntrl** returns a nonzero value if *c* is a control wide character. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a control character. **`iscntrl`** returns a nonzero value if *`c`* is a control character (0x00 - 0x1F or 0x7F). **`iswcntrl`** returns a nonzero value if *`c`* is a control wide character. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -The behavior of **iscntrl** and **_iscntrl_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`iscntrl`** and **`_iscntrl_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istcntrl**|**iscntrl**|**iscntrl**|**iswcntrl**| -|**_istcntrl_l**|**_iscntrl_l**|**_iscntrl_l**|**_iswcntrl_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istcntrl` | **`iscntrl`** | **`iscntrl`** | **`iswcntrl`** | +| `_istcntrl_l` | **`_iscntrl_l`** | **`_iscntrl_l`** | **`_iswcntrl_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**iscntrl**|\| -|**iswcntrl**|\ or \| -|**_iscntrl_l**|\| -|**_iswcntrl_l**|\ or \| +| Routine | Required header | +|---|---| +| **`iscntrl`** | \ | +| **`iswcntrl`** | \ or \ | +| **`_iscntrl_l`** | \ | +| **`_iswcntrl_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/iscsym-functions.md b/docs/c-runtime-library/reference/iscsym-functions.md index bbd33003ed..d61385de39 100644 --- a/docs/c-runtime-library/reference/iscsym-functions.md +++ b/docs/c-runtime-library/reference/iscsym-functions.md @@ -10,7 +10,7 @@ f1_keywords: ["_iswcsym_l", "_iswcsymf_l", "iscsymf", "iswcsymf", "__iswcsym", " helpviewer_keywords: ["iscsymf_l function", "iswsym_l function", "_iswcsym_l function", "iscsym_l function", "_iscsymf_l function", "_iswcsymf_l function", "_iscsym_l function", "__iscsym function", "__iswcsymf function", "iswsymf_l function", "__iscsymf function", "__iswcsym function", "iscsym function", "iscsymf function"] ms.assetid: 944dfb99-f2b8-498c-9f55-dbcf370d0a2c --- -# iscsym, iscsymf, __iscsym, __iswcsym, __iscsymf, __iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l +# `iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l` Determine if an integer represents a character that may be used in an identifier. @@ -51,32 +51,32 @@ int _iswcsymf_l( ### Parameters -*c*
-Integer to test. *c* should be in the range of 0-255 for the narrow character version of the function. +*`c`*\ +Integer to test. *`c`* should be in the range of 0-255 for the narrow character version of the function. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Both **__iscsym** and **__iswcsym** return a nonzero value if *c* is a letter, underscore, or digit. Both **__iscsymf** and **__iswcsymf** return a nonzero value if *c* is a letter or an underscore. Each of these routines returns 0 if *c* does not satisfy the test condition. The versions of these functions with the **_l** suffix are identical except that they use the *locale* passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +Both **`__iscsym`** and **`__iswcsym`** return a nonzero value if *`c`* is a letter, underscore, or digit. Both **`__iscsymf`** and **`__iswcsymf`** return a nonzero value if *`c`* is a letter or an underscore. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. The versions of these functions with the `_l` suffix are identical except that they use the *`locale`* passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). ## Remarks These routines are defined as macros unless the preprocessor macro _CTYPE_DISABLE_MACROS is defined. When you use the macro versions of these routines, the arguments can be evaluated more than once. Be careful when you use expressions that have side effects within the argument list. -For backward compatibility, **iscsym** and **iscsymf** are defined as macros only when [`__STDC__`](../../preprocessor/predefined-macros.md) is not defined or is defined as 0; otherwise they are undefined. +For backward compatibility, **`iscsym`** and **`iscsymf`** are defined as macros only when [`__STDC__`](../../preprocessor/predefined-macros.md) isn't defined or is defined as 0; otherwise they're undefined. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**iscsym**, **iscsymf**, **__iscsym**, **__iswcsym**, **__iscsymf**, **__iswcsymf**, **_iscsym_l**, **_iswcsym_l**, **_iscsymf_l**, **_iswcsymf_l**|C: \

C++: \ or \| +| Routine | Required header | +|---|---| +| **`iscsym`**, **`iscsymf`**, **`__iscsym`**, **`__iswcsym`**, **`__iscsymf`**, **`__iswcsymf`**, **`_iscsym_l`**, **`_iswcsym_l`**, **`_iscsymf_l`**, **`_iswcsymf_l`** | C: \

C++: \ or \ | -The **iscsym**, **iscsymf**, **__iscsym**, **__iswcsym**, **__iscsymf**, **__iswcsymf**, **_iscsym_l**, **_iswcsym_l**, **_iscsymf_l**, and **_iswcsymf_l** routines are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`iscsym`**, **`iscsymf`**, **`__iscsym`**, **`__iswcsym`**, **`__iscsymf`**, **`__iswcsymf`**, **`_iscsym_l`**, **`_iswcsym_l`**, **`_iscsymf_l`**, and **`_iswcsymf_l`** routines are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md b/docs/c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md index cf8966dbf7..04552abfba 100644 --- a/docs/c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md +++ b/docs/c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _isctype, iswctype, _isctype_l, _iswctype_l" title: "_isctype, iswctype, _isctype_l, _iswctype_l" ms.date: "4/2/2020" api_name: ["_isctype_l", "iswctype", "_iswctype_l", "_isctype", "_o__isctype", "_o__isctype_l", "_o__iswctype_l", "_o_iswctype"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswctype", "_isctype", "_isctype_l", "_iswctype", "isctype", "iswctype_l", "isctype_l", "_iswctype_l"] helpviewer_keywords: ["isctype_l function", "iswctype_l function", "iswctype function", "_isctype function", "_isctype_l function", "_iswctype_l function", "isctype function", "_iswctype function"] ms.assetid: cf7509b7-12fc-4d95-8140-ad2eb98173d3 --- -# _isctype, iswctype, _isctype_l, _iswctype_l +# `_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l` -Tests *c* for the ctype property specified by the *desc* argument. For each valid value of *desc*, there is an equivalent wide-character classification routine. +Tests *`c`* for the `ctype` property specified by the *`desc`* argument. For each valid value of *`desc`*, there's an equivalent wide-character classification routine. ## Syntax @@ -39,49 +39,49 @@ int _iswctype_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*desc*
-Property to test for. This is normally retrieved using ctype or [wctype](wctype.md). +*`desc`*\ +Property to test for. The property is normally retrieved using `ctype` or [`wctype`](wctype.md). -*locale*
+*`locale`*\ The locale to use for any locale-dependent tests. -## Return Value +## Return value -**_isctype** and **iswctype** return a nonzero value if *c* has the property specified by *desc* in the current locale or 0 if it does not. The versions of these functions with the **_l** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_isctype`** and **`iswctype`** return a nonzero value if *`c`* has the property specified by *`desc`* in the current locale. Otherwise, they return 0. The versions of these functions with the `_l` suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **_isctype** and **_isctype_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`_isctype`** and **`_isctype_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|n/a|**_isctype**|n/a|**_iswctype**| -|n/a|**_isctype_l**|n/a|**_iswctype_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| n/a | **`_isctype`** | n/a | **`_iswctype`** | +| n/a | **`_isctype_l`** | n/a | **`_iswctype_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_isctype**|\| -|**iswctype**|\ or \| -|**_isctype_l**|\| -|**_iswctype_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_isctype`** | \ | +| **`iswctype`** | \ or \ | +| **`_isctype_l`** | \ | +| **`_iswctype_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md b/docs/c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md index 069fba6039..aca2271b21 100644 --- a/docs/c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md +++ b/docs/c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isdigit, iswdigit, _isdigit_l, _iswdigit_l" title: "isdigit, iswdigit, _isdigit_l, _iswdigit_l" ms.date: "4/2/2020" api_name: ["_isdigit_l", "iswdigit", "_iswdigit_l", "isdigit", "_o_isdigit", "_o_iswdigit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_iswdigit_l", "_isdigit_l", "iswdigit", "isdigit", "_istdigit", "_istdigit_l"] helpviewer_keywords: ["iswdigit function", "iswdigit_l function", "_iswdigit_l function", "_istdigit_l function", "_istdigit function", "istdigit function", "isdigit function", "isdigit_l function", "_ismbcdigit_l function", "_isdigit_l function"] ms.assetid: 350b0093-843a-47b0-954e-c1776e8a3853 --- -# isdigit, iswdigit, _isdigit_l, _iswdigit_l +# `isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l` Determines whether an integer represents a decimal-digit character. @@ -35,44 +35,44 @@ int _iswdigit_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a decimal-digit character. **isdigit** returns a nonzero value if *c* is a decimal digit (0 - 9). **iswdigit** returns a nonzero value if *c* is a wide character that corresponds to a decimal-digit character. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a decimal-digit character. **`isdigit`** returns a nonzero value if *`c`* is a decimal digit (0 - 9). **`iswdigit`** returns a nonzero value if *`c`* is a wide character that corresponds to a decimal-digit character. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **isdigit** and **_isdigit_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isdigit`** and **`_isdigit_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istdigit**|**isdigit**|[_ismbcdigit](ismbcalnum-functions.md)|**iswdigit**| -|**_istdigit_l**|**_isdigit_l**|[_ismbcdigit_l](ismbcalnum-functions.md)|**_iswdigit_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istdigit` | **`isdigit`** | [`_ismbcdigit`](ismbcalnum-functions.md) | **`iswdigit`** | +| `_istdigit_l` | **`_isdigit_l`** | [`_ismbcdigit_l`](ismbcalnum-functions.md) | **`_iswdigit_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isdigit**|\| -|**iswdigit**|\ or \| -|**_isdigit_l**|\| -|**_iswdigit_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isdigit`** | \ | +| **`iswdigit`** | \ or \ | +| **`_isdigit_l`** | \ | +| **`_iswdigit_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md b/docs/c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md index 23693a6e44..4b1886e00d 100644 --- a/docs/c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md +++ b/docs/c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isgraph, iswgraph, _isgraph_l, _iswgraph_l" title: "isgraph, iswgraph, _isgraph_l, _iswgraph_l" ms.date: "4/2/2020" api_name: ["isgraph", "iswgraph", "_iswgraph_l", "_isgraph_l", "_o_isgraph", "_o_iswgraph"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_isgraph_l", "_iswgraph_l", "Isgraph", "_istgraph_l", "_istgraph", "iswgraph"] helpviewer_keywords: ["isgraph function", "_istgraph_l function", "istgraph function", "_isgraph_l function", "iswgraph function", "_iswgraph_l function", "_istgraph function", "_ismbcgraph_l function"] ms.assetid: 531a5f34-4302-4d0a-8a4f-b7ea150ad941 --- -# isgraph, iswgraph, _isgraph_l, _iswgraph_l +# `isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l` Determines whether an integer represents a graphical character. @@ -35,41 +35,41 @@ int _iswgraph_l( ### Parameters -*c*
+*`c`*\ Integer to test. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a printable character other than a space. **isgraph** returns a nonzero value if *c* is a printable character other than a space. **iswgraph** returns a nonzero value if *c* is a printable wide character other than a wide character space. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a printable character other than a space. **`isgraph`** returns a nonzero value if *`c`* is a printable character other than a space. **`iswgraph`** returns a nonzero value if *`c`* is a printable wide character other than a wide character space. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **isgraph** and **_isgraph_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isgraph`** and **`_isgraph_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istgraph**|**isgraph**|[_ismbcgraph](ismbcgraph-functions.md)|**iswgraph**| -|**_istgraph_l**|**_isgraph_l**|[_ismbcgraph_l](ismbcgraph-functions.md)|**_iswgraph_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istgraph` | **`isgraph`** | [`_ismbcgraph`](ismbcgraph-functions.md) | **`iswgraph`** | +| **`_istgraph_l`** | **`_isgraph_l`** | [`_ismbcgraph_l`](ismbcgraph-functions.md) | **`_iswgraph_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isgraph**|\| -|**iswgraph**|\ or \| -|**_isgraph_l**|\| -|**_iswgraph_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isgraph`** | \ | +| **`iswgraph`** | \ or \ | +| **`_isgraph_l`** | \ | +| **`_iswgraph_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isinf.md b/docs/c-runtime-library/reference/isinf.md index cbc03623e7..50165ca0ea 100644 --- a/docs/c-runtime-library/reference/isinf.md +++ b/docs/c-runtime-library/reference/isinf.md @@ -5,7 +5,7 @@ ms.date: "01/31/2019" f1_keywords: ["isinf", "math/isinf"] helpviewer_keywords: ["isinf function"] --- -# isinf +# `isinf` Determines whether a floating-point value is an infinity. @@ -24,30 +24,30 @@ inline bool isinf( ### Parameters -*x*
+*`x`*\ The floating-point value to test. ## Return value -**isinf** returns a nonzero value (**`true`** in C++ code) if the argument *x* is a positive or negative infinity. **isinf** returns 0 (**`false`** in C++ code) if the argument is finite or a NAN. Both normal and subnormal floating-point values are considered finite. +**`isinf`** returns a nonzero value (**`true`** in C++ code) if the argument *`x`* is a positive or negative infinity. **`isinf`** returns 0 (**`false`** in C++ code) if the argument is finite or a NAN. Both normal and subnormal floating-point values are considered finite. ## Remarks -**isinf** is a macro when compiled as C, and an inline template function when compiled as C++. +**`isinf`** is a macro when compiled as C, and an inline template function when compiled as C++. ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -|**isinf**|\|\ or \| +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`isinf`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md b/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md index fb242dad8e..3b26b85e0a 100644 --- a/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md +++ b/docs/c-runtime-library/reference/isleadbyte-isleadbyte-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isleadbyte, _isleadbyte_l" title: "isleadbyte, _isleadbyte_l" ms.date: "4/2/2020" api_name: ["_isleadbyte_l", "isleadbyte", "_o__isleadbyte_l", "_o_isleadbyte"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_istleadbyte", "_isleadbyte_l", "isleadbyte"] helpviewer_keywords: ["lead bytes", "_isleadbyte_l function", "_istleadbyte function", "istleadbyte function", "isleadbyte function"] ms.assetid: 3b2bcf09-d82b-4803-9e80-59d04942802a --- -# isleadbyte, _isleadbyte_l +# `isleadbyte`, `_isleadbyte_l` Determines whether a character is the lead byte of a multibyte character. @@ -26,40 +26,40 @@ int _isleadbyte_l( int c ); ### Parameters -*c*
+*`c`*\ Integer to test. -## Return Value +## Return value -**isleadbyte** returns a nonzero value if the argument satisfies the test condition or 0 if it does not. In the "C" locale and in single-byte character set (SBCS) locales, **isleadbyte** always returns 0. +**`isleadbyte`** returns a nonzero value if the argument satisfies the test condition. Otherwise, it returns 0. In the "C" locale and in single-byte character set (SBCS) locales, **`isleadbyte`** always returns 0. ## Remarks -The **isleadbyte** macro returns a nonzero value if its argument is the first byte of a multibyte character. **isleadbyte** produces a meaningful result for any integer argument from -1 (**EOF**) to **UCHAR_MAX** (0xFF), inclusive. +The **`isleadbyte`** macro returns a nonzero value if its argument is the first byte of a multibyte character. **`isleadbyte`** produces a meaningful result for any integer argument from -1 (`EOF`) to `UCHAR_MAX` (0xFF), inclusive. -The expected argument type of **isleadbyte** is **`int`**; if a signed character is passed, the compiler may convert it to an integer by sign extension, yielding unpredictable results. +The expected argument type of **`isleadbyte`** is **`int`**; if a signed character is passed, the compiler may convert it to an integer by sign extension, yielding unpredictable results. -The version of this function with the **_l** suffix is identical except that it uses the locale passed in instead of the current locale for its locale-dependent behavior. +The version of this function with the `_l` suffix is identical except that it uses the locale passed in instead of the current locale for its locale-dependent behavior. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istleadbyte**|Always returns false|**_isleadbyte**|Always returns false| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_istleadbyte`** | Always returns false | **`_isleadbyte`** | Always returns false | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isleadbyte**|\| -|**_isleadbyte_l**|\| +| Routine | Required header | +|---|---| +| **`isleadbyte`** | \ | +| **`_isleadbyte_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[Locale](../locale.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md b/docs/c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md index 3a3f1af565..f95d12c979 100644 --- a/docs/c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md +++ b/docs/c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: islower, iswlower, _islower_l, _iswlower_l" title: "islower, iswlower, _islower_l, _iswlower_l" -ms.date: "4/2/2020" +description: "Learn more about: islower, iswlower, _islower_l, _iswlower_l" +ms.date: 4/2/2020 api_name: ["iswlower", "_islower_l", "islower", "_iswlower_l", "_o_islower", "_o_iswlower"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_istlower", "islower", "_ismbclower_l", "_liswlower_l", "_istlower_l", "_iswlower_l", "_islower _l", "_islower_l", "iswlower"] helpviewer_keywords: ["_islower _l function", "_ismbclower_l function", "islower function", "_iswlower_l function", "_liswlower_l function", "_istlower_l function", "istlower function", "_istlower function", "iswlower function", "_islower_l function"] -ms.assetid: fcc3b70a-2b47-45fd-944d-e5c1942e6457 --- -# islower, iswlower, _islower_l, _iswlower_l +# `islower`, `iswlower`, `_islower_l`, `_iswlower_l` Determines whether an integer represents a lowercase character. @@ -35,44 +34,44 @@ int _iswlower_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a lowercase character. **islower** returns a nonzero value if *c* is a lowercase character (a - z). **iswlower** returns a nonzero value if *c* is a wide character that corresponds to a lowercase letter, or if *c* is one of an implementation-defined set of wide characters for which none of **iswcntrl**, **iswdigit**, **iswpunct**, or **iswspace** is nonzero. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a lowercase character. **`islower`** returns a nonzero value if *`c`* is a lowercase character (a - z). **`iswlower`** returns a nonzero value if *`c`* is a wide character that corresponds to a lowercase letter, or if *`c`* is one of an implementation-defined set of wide characters for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **islower** and **_islower_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`islower`** and **`_islower_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istlower**|**islower**|[_ismbclower](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**iswlower**| -|**_istlower_l**|`_islower _l`|[_ismbclower_l](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**_liswlower_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istlower` | **`islower`** | [`_ismbclower`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | **`iswlower`** | +| **`_istlower_l`** | `_islower_l` | [`_ismbclower_l`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | **`_liswlower_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**islower**|\| -|**iswlower**|\ or \| -|**_islower_l**|\| -|**_swlower_l**|\ or \| +| Routine | Required header | +|---|---| +| **`islower`** | `` | +| **`iswlower`** | `` or `` | +| **`_islower_l`** | `` | +| **`_swlower_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md b/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md index 5899c6e19f..b878787497 100644 --- a/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md +++ b/docs/c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbalnum, _ismbbalnum_l" title: "_ismbbalnum, _ismbbalnum_l" ms.date: "4/2/2020" api_name: ["_ismbbalnum", "_ismbbalnum_l", "_o__ismbbalnum", "_o__ismbbalnum_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbalnum", "ismbbalnum", "_ismbbalnum_l", "ismbbalnum_l"] helpviewer_keywords: ["_ismbbalnum_l function", "ismbbalnum function", "ismbbalnum_l function", "_ismbbalnum function"] ms.assetid: 8025de50-a871-49fd-9ae6-f437b47aa987 --- -# _ismbbalnum, _ismbbalnum_l +# `_ismbbalnum`, `_ismbbalnum_l` Determines whether a specified multibyte character is alpha or numeric. @@ -27,40 +27,40 @@ int _ismbbalnum_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbalnum** returns a nonzero value if the expression: +**`_ismbbalnum`** returns a nonzero value when the expression: `isalnum(c) || _ismbbkalnum(c)` -is nonzero for *c*, or 0 if it is not. +is nonzero for *`c`*, or 0 when the expression is zero. -The version of this function with the **_l** suffix is identical except that it uses the locale passed in instead of the current locale for its locale-dependent behavior. +The version of this function with the `_l` suffix is identical except that it uses the locale passed in instead of the current locale for its locale-dependent behavior. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbalnum**|\| -|**_ismbbalnum_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbalnum`** | \ | +| **`_ismbbalnum_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md b/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md index b07a8e01b9..99b3d7f08f 100644 --- a/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md +++ b/docs/c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbalpha, _ismbbalpha_l" title: "_ismbbalpha, _ismbbalpha_l" ms.date: "4/2/2020" api_name: ["_ismbbalpha", "_ismbbalpha_l", "_o__ismbbalpha", "_o__ismbbalpha_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbbalpha", "ismbbalpha_l", "_ismbbalpha", "_ismbbalpha_l"] helpviewer_keywords: ["ismbbalpha function", "ismbbalpha_l function", "_ismbbalpha function", "_ismbbalpha_l function"] ms.assetid: 8e54cb92-fc2b-41f5-8ab4-b22ac8aa9ad0 --- -# _ismbbalpha, _ismbbalpha_l +# `_ismbbalpha`, `_ismbbalpha_l` Determines whether a specified multibyte character is alpha. @@ -27,38 +27,38 @@ int _ismbbalpha_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbalpha** returns a nonzero value if the expression: +**`_ismbbalpha`** returns a nonzero value when the expression: `isalpha(c) || _ismbbkalnum(c)` -is nonzero for *c*, or 0 if it is not. **_ismbbalpha** uses the current locale for any locale-dependent character settings. **_ismbbalpha_l** is identical except that it uses the locale passed in. +is nonzero for *`c`*, or 0 when the expression is zero. **`_ismbbalpha`** uses the current locale for any locale-dependent character settings. **`_ismbbalpha_l`** is identical except that it uses the locale passed in. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbalpha**|\| -|**_ismbbalpha_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbalpha`** | \ | +| **`_ismbbalpha_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md b/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md index 8c7a0a68e6..e6c3aba12d 100644 --- a/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md +++ b/docs/c-runtime-library/reference/ismbbblank-ismbbblank-l.md @@ -3,12 +3,12 @@ description: "Learn more about: _ismbbblank, _ismbbblank_l" title: "_ismbbblank, _ismbbblank_l" ms.date: "4/2/2020" api_name: ["_ismbbblank_l", "_ismbbblank", "_o__ismbbblank", "_o__ismbbblank_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] ms.assetid: d21b2e41-7206-41f5-85bb-9c9ab4f3e21b --- -# _ismbbblank, _ismbbblank_l +# `_ismbbblank`, `_ismbbblank_l` Determines whether a specified multibyte character is a blank character. @@ -29,30 +29,30 @@ int _ismbbblank_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbblank** returns a nonzero value if *c* represents a space (0x20) character, a horizontal tab (0x09) character, or a locale-specific character that's used to separate words within a line of text for which **isspace** is true; otherwise, returns 0. **_ismbbblank** uses the current locale for any locale-dependent behavior. **_ismbbblank_l** is identical except that it instead uses the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbblank`** returns a nonzero value if *`c`* represents a space (0x20) character, a horizontal tab (0x09) character, or a locale-specific character that's used to separate words within a line of text for which `isspace` is true; otherwise, returns 0. **`_ismbbblank`** uses the current locale for any locale-dependent behavior. **`_ismbbblank_l`** is identical except that it instead uses the locale that's passed in. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbblank**|\| -|**_ismbbblank_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbblank`** | \ | +| **`_ismbbblank_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md b/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md index 068db7f83a..7c2284d1da 100644 --- a/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md +++ b/docs/c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbgraph, _ismbbgraph_l" title: "_ismbbgraph, _ismbbgraph_l" ms.date: "4/2/2020" api_name: ["_ismbbgraph_l", "_ismbbgraph", "_o__ismbbgraph", "_o__ismbbgraph_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbgraph", "_ismbbgraph_l", "ismbbgraph", "ismbbgraph_l"] helpviewer_keywords: ["_ismbbgraph_l function", "ismbbgraph_l function", "_ismbbgraph function", "ismbbgraph function"] ms.assetid: b60db718-134f-4796-acc1-592d0b9efbb7 --- -# _ismbbgraph, _ismbbgraph_l +# `_ismbbgraph`, `_ismbbgraph_l` Determines whether a particular multibyte character is a graphical character. @@ -28,38 +28,38 @@ int _ismbbgraph_l ( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns a nonzero value if the expression: +Returns a nonzero value when the expression: `isctype(c, ( _PUNCT | _UPPER | _LOWER | _DIGIT )) || _ismbbkprint(c)` -is nonzero for *c*, or 0 if it is not. **_ismbbgraph** uses the current locale for any locale-dependent behavior. **_ismbbgraph_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +is nonzero for *`c`*, or 0 when it's zero. **`_ismbbgraph`** uses the current locale for any locale-dependent behavior. **`_ismbbgraph_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbgraph**|\| -|**_ismbbgraph_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbgraph`** | \ | +| **`_ismbbgraph_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md b/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md index 30107b861c..7f966b356b 100644 --- a/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md +++ b/docs/c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbkalnum, _ismbbkalnum_l" title: "_ismbbkalnum, _ismbbkalnum_l" ms.date: "4/2/2020" api_name: ["_ismbbkalnum", "_ismbbkalnum_l", "_o__ismbbkalnum", "_o__ismbbkalnum_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbkalnum", "ismbbkalnum", "ismbbkalnum_l", "_ismbbkalnum_l"] helpviewer_keywords: ["_ismbbkalnum_l function", "ismbbkalnum_l function", "_ismbbkalnum function", "ismbbkalnum function"] ms.assetid: e1d70e7b-29d0-469c-9d93-442b99de22ac --- -# _ismbbkalnum, _ismbbkalnum_l +# `_ismbbkalnum`, `_ismbbkalnum_l` Determines whether a particular multibyte character is a non-ASCII text symbol. @@ -28,30 +28,30 @@ int _ismbbkalnum_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbkalnum** returns a nonzero value if the integer *c* is a non-ASCII text symbol other than punctuation, or 0 if it is not. **_ismbbkalnum** uses the current locale for locale-dependent character information. **_ismbbkalnum_l** is identical to **_ismbbkalnum** except that it takes the locale as a parameter. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbkalnum`** returns a nonzero value if the integer *`c`* is a non-ASCII text symbol other than punctuation. Otherwise, it returns 0. **`_ismbbkalnum`** uses the current locale for locale-dependent character information. **`_ismbbkalnum_l`** is identical to **`_ismbbkalnum`** except that it takes the locale as a parameter. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbkalnum**|\| -|**_ismbbkalnum_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbkalnum`** | \ | +| **`_ismbbkalnum_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md b/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md index b4bd52230e..857d850c45 100644 --- a/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md +++ b/docs/c-runtime-library/reference/ismbbkana-ismbbkana-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbkana, _ismbbkana_l" title: "_ismbbkana, _ismbbkana_l" ms.date: "4/2/2020" api_name: ["_ismbbkana_l", "_ismbbkana", "_o__ismbbkana", "_o__ismbbkana_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbkana_l", "ismbbkana_l", "ismbbkana", "_ismbbkana"] helpviewer_keywords: ["_ismbbkana_l function", "_ismbbkana function", "ismbbkana function", "ismbbkana_l function"] ms.assetid: 64d4eb4a-205a-40ef-be35-ff9d77fabbaf --- -# _ismbbkana, _ismbbkana_l +# `_ismbbkana`, `_ismbbkana_l` Tests for a katakana symbol and is specific to code page 932. @@ -28,30 +28,30 @@ int _ismbbkana_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbkana** returns a nonzero value if the integer *c* is a katakana symbol or 0 if it is not. **_ismbbkana** uses the current locale for locale-dependent character information. **_ismbbkana_l** is identical except that it uses the locale object passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbkana`** returns a nonzero value if the integer *`c`* is a katakana symbol. Otherwise, it returns 0. **`_ismbbkana`** uses the current locale for locale-dependent character information. **`_ismbbkana_l`** is identical except that it uses the locale object passed in. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbkana**|\| -|**_ismbbkana_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbkana`** | \ | +| **`_ismbbkana_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md b/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md index 6a4f3c4f7c..9729e54d27 100644 --- a/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md +++ b/docs/c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbkprint, _ismbbkprint_l" title: "_ismbbkprint, _ismbbkprint_l" ms.date: "4/2/2020" api_name: ["_ismbbkprint", "_ismbbkprint_l", "_o__ismbbkprint", "_o__ismbbkprint_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbkprint_l", "ismbbkprint", "_ismbbkprint", "ismbbkprint_l"] helpviewer_keywords: ["_ismbbkprint function", "ismbbkprint_l function", "ismbbkprint function", "_ismbbkprint_l function"] ms.assetid: 8d1d3258-1e34-4365-81ed-97c95de25475 --- -# _ismbbkprint, _ismbbkprint_l +# `_ismbbkprint`, `_ismbbkprint_l` Determines whether a particular multibyte character is a punctuation symbol. @@ -28,30 +28,30 @@ int _ismbbkprint_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbkprint** returns a nonzero value if the integer *c* is a non-ASCII text or non-ASCII punctuation symbol or 0 if it is not. For example, in code page 932 only, **_ismbbkprint** tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF). **_ismbbkprint** uses the current locale for locale-dependent character settings. **_ismbbkprint_l** is identical except that it uses the locale passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbkprint`** returns a nonzero value if the integer *`c`* is a non-ASCII text or non-ASCII punctuation symbol. Otherwise, it returns 0. For example, in code page 932 only, **`_ismbbkprint`** tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF). **`_ismbbkprint`** uses the current locale for locale-dependent character settings. **`_ismbbkprint_l`** is identical except that it uses the locale passed in. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbkprint**|\| -|**_ismbbkprint_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbkprint`** | \ | +| **`_ismbbkprint_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md b/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md index 32df5ae05a..74c2980319 100644 --- a/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md +++ b/docs/c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbkpunct, _ismbbkpunct_l" title: "_ismbbkpunct, _ismbbkpunct_l" ms.date: "4/2/2020" api_name: ["_ismbbkpunct_l", "_ismbbkpunct", "_o__ismbbkpunct", "_o__ismbbkpunct_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbbkpunct_l", "_ismbbkpunct_l", "ismbbkpunct", "_ismbbkpunct"] helpviewer_keywords: ["_ismbbkpunct_l function", "ismbbkpunct_l function", "ismbbkpunct function", "_ismbbkpunct function"] ms.assetid: a04c59cd-5ca7-4296-bec0-2b0d7f04edd0 --- -# _ismbbkpunct, _ismbbkpunct_l +# `_ismbbkpunct`, `_ismbbkpunct_l` Checks whether a multibyte character is a punctuation character. @@ -28,30 +28,30 @@ int _ismbbkpunct_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbkpunct** returns a nonzero value if the integer *c* is a non-ASCII punctuation symbol, or 0 if it is not. For example, in code page 932 only, **_ismbbkpunct** tests for katakana punctuation. **_ismbbkpunct** uses the current locale for any locale-dependent character settings. **_ismbbkpunct_l** is identical except that it uses the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbkpunct`** returns a nonzero value if the integer *`c`* is a non-ASCII punctuation symbol. Otherwise, it returns 0. For example, in code page 932 only, **`_ismbbkpunct`** tests for katakana punctuation. **`_ismbbkpunct`** uses the current locale for any locale-dependent character settings. **`_ismbbkpunct_l`** is identical except that it uses the locale that's passed in. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbkpunct**|\| -|**_ismbbkpunct_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbkpunct`** | \ | +| **`_ismbbkpunct_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md b/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md index 2faba9f4ef..5b3385b50f 100644 --- a/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md +++ b/docs/c-runtime-library/reference/ismbblead-ismbblead-l.md @@ -3,14 +3,14 @@ title: "_ismbblead, _ismbblead_l" description: "Describes the Microsoft C Runtime Library (CRT) _ismbblead and _ismbblead_l functions." ms.date: "4/2/2020" api_name: ["_ismbblead_l", "_ismbblead", "_o__ismbblead", "_o__ismbblead_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbblead_l", "istlead", "_ismbblead", "_ismbblead_l", "ismbblead", "_istlead"] helpviewer_keywords: ["_ismbblead_l function", "ismbblead function", "_ismbblead function", "istlead function", "ismbblead_l function", "_istlead function"] ms.assetid: 2abc6f75-ed5c-472e-bfd0-e905a1835ccf --- -# _ismbblead, _ismbblead_l +# `_ismbblead`, `_ismbblead_l` Tests a character to determine whether it's a lead byte of a multibyte character. @@ -28,47 +28,47 @@ int _ismbblead_l( ### Parameters -*c*\ +*`c`*\ Integer to be tested. -*locale*\ +*`locale`*\ Locale to use. ## Return value -Returns a nonzero value if the integer *c* is the first byte of a multibyte character. +Returns a nonzero value if the integer *`c`* is the first byte of a multibyte character. ## Remarks Multibyte characters consist of a lead byte followed by a trailing byte. Lead bytes are distinguished by being in a particular range for a given character set. For example, in code page 932 only, lead bytes range from 0x81 - 0x9F and 0xE0 - 0xFC. -**_ismbblead** uses the current locale for locale-dependent behavior. **_ismbblead_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbblead`** uses the current locale for locale-dependent behavior. **`_ismbblead_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -When the locale is UTF-8, **_ismbblead** and **_ismbblead_l** always return 0 (false), whether *c* is a lead byte or not. +When the locale is UTF-8, **`_ismbblead`** and **`_ismbblead_l`** always return 0 (false), whether *`c`* is a lead byte or not. -**_ismbblead** and **_ismbblead_l** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **mbrlen** instead. +**`_ismbblead`** and **`_ismbblead_l`** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use `mbrlen` instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_istlead**|Always returns false|**_ismbblead**|Always returns false| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istlead` | Always returns false | **`_ismbblead`** | Always returns false | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_ismbblead**|\ or \|\,* \, \| -|**_ismbblead_l**|\ or \|\,* \, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_ismbblead`** | \ or \ | \,* \, \ | +| **`_ismbblead_l`** | \ or \ | \,* \, \ | \* For manifest constants for the test conditions. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte classification](../../c-runtime-library/byte-classification.md)\ -[_ismbb routines](../../c-runtime-library/ismbb-routines.md)\ -[mbrlen](mbrlen.md) +[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md)\ +[`mbrlen`](mbrlen.md) diff --git a/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md b/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md index 40e941cf50..64bd200169 100644 --- a/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md +++ b/docs/c-runtime-library/reference/ismbbprint-ismbbprint-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbprint, _ismbbprint_l" title: "_ismbbprint, _ismbbprint_l" ms.date: "4/2/2020" api_name: ["_ismbbprint_l", "_ismbbprint", "_o__ismbbprint", "_o__ismbbprint_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbprint_l", "_ismbbprint", "ismbbprint", "ismbbprint_l"] helpviewer_keywords: ["ismbbprint_l function", "ismbbprint function", "_ismbbprint function", "_ismbbprint_l function"] ms.assetid: d08a061c-18a8-48f2-a75d-bff4870aec9d --- -# _ismbbprint, _ismbbprint_l +# `_ismbbprint`, `_ismbbprint_l` Determines whether a specified multibyte character is a print character. @@ -28,34 +28,34 @@ int _ismbbprint_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbprint** returns a nonzero value if the expression: +**`_ismbbprint`** returns a nonzero value when the expression: `isprint(c) || _ismbbkprint(c)` -is nonzero for *c*, or 0 if it is not. **_ismbbprint** uses the current locale for any locale-dependent behavior. **_ismbbprint_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +is nonzero for *`c`*, or 0 when it isn't. **`_ismbbprint`** uses the current locale for any locale-dependent behavior. **`_ismbbprint_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbprint**|\| -|**_ismbbprint_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbprint`** | \ | +| **`_ismbbprint_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md b/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md index adaca9d77d..4b740e1afa 100644 --- a/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md +++ b/docs/c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbpunct, _ismbbpunct_l" title: "_ismbbpunct, _ismbbpunct_l" ms.date: "4/2/2020" api_name: ["_ismbbpunct", "_ismbbpunct_l", "_o__ismbbpunct", "_o__ismbbpunct_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbbpunct", "ismbbpunct_l", "_ismbbpunct_l", "_ismbbpunct"] helpviewer_keywords: ["ismbbpunct function", "_ismbbpunct function", "ismbbpunct_l function", "_ismbbpunct_l function"] ms.assetid: 1976c9d3-7d1a-415f-ac52-2715c7bb56eb --- -# _ismbbpunct, _ismbbpunct_l +# `_ismbbpunct`, `_ismbbpunct_l` Determines whether a particular character is a punctuation character. @@ -28,30 +28,30 @@ int _ismbbpunct_l( ### Parameters -*c*
+*`c`*\ Integer to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_ismbbpunct** returns a nonzero value if the integer *c* is a non-ASCII punctuation symbol. **_ismbbpunct** uses the current locale for any locale-dependent character settings. **_ismbbpunct_l** is identical except that it uses the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbpunct`** returns a nonzero value if the integer *`c`* is a non-ASCII punctuation symbol. **`_ismbbpunct`** uses the current locale for any locale-dependent character settings. **`_ismbbpunct_l`** is identical except that it uses the locale that's passed in. For more information, see [Locale](../locale.md). ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbbpunct**|\| -|**_ismbbpunct_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbbpunct`** | \ | +| **`_ismbbpunct_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md b/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md index 8feeb15289..f50c7e7500 100644 --- a/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md +++ b/docs/c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbbtrail, _ismbbtrail_l" title: "_ismbbtrail, _ismbbtrail_l" ms.date: "4/2/2020" api_name: ["_ismbbtrail", "_ismbbtrail_l", "_o__ismbbtrail", "_o__ismbbtrail_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbbtrail", "ismbbtrail", "_ismbbtrail_l", "ismbbtrail_l"] helpviewer_keywords: ["ismbbtrail_l function", "_ismbbtrail function", "_ismbbtrail_l function", "ismbbtrail function"] ms.assetid: dfdd0292-960b-4c1d-bf11-146e0fc80247 --- -# _ismbbtrail, _ismbbtrail_l +# `_ismbbtrail`, `_ismbbtrail_l` Determines whether a byte is a trailing byte of a multibyte character. @@ -28,34 +28,34 @@ int _ismbbtrail_l( ### Parameters -*c*
+*`c`*\ The integer to be tested. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_ismbbtrail** returns a nonzero value if the integer *c* is the second byte of a multibyte character. For example, in code page 932 only, valid ranges are 0x40 to 0x7E and 0x80 to 0xFC. +**`_ismbbtrail`** returns a nonzero value if the integer *`c`* is the second byte of a multibyte character. For example, in code page 932 only, valid ranges are 0x40 to 0x7E and 0x80 to 0xFC. ## Remarks -**_ismbbtrail** uses the current locale for locale-dependent behavior. **_ismbbtrail_l** is identical except that it uses the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_ismbbtrail`** uses the current locale for locale-dependent behavior. **`_ismbbtrail_l`** is identical except that it uses the locale that's passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_ismbbtrail**|\ or \|\,* \, \| -|**_ismbbtrail_l**|\ or \|\,* \, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_ismbbtrail`** | \ or \ | \,* \, \ | +| **`_ismbbtrail_l`** | \ or \ | \,* \, \ | \* For manifest constants for the test conditions. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Byte classification](../byte-classification.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbcalnum-functions.md b/docs/c-runtime-library/reference/ismbcalnum-functions.md index 1732330203..068dd49041 100644 --- a/docs/c-runtime-library/reference/ismbcalnum-functions.md +++ b/docs/c-runtime-library/reference/ismbcalnum-functions.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbca title: "_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l" ms.date: "4/2/2020" api_name: ["_ismbcalpha", "_ismbcalnum", "_ismbcdigit", "_ismbcalnum_l", "_ismbcdigit_l", "_ismbcalpha_l", "_o__ismbcalnum", "_o__ismbcalnum_l", "_o__ismbcalpha", "_o__ismbcalpha_l", "_o__ismbcdigit", "_o__ismbcdigit_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbcdigit", "ismbcalnum_l", "_ismbcdigit_l", "_ismbcalpha", "ismbcalnum", "ismbcdigit", "ismbcalpha", "_ismbcalnum_l", "_ismbcalnum", "ismbcdigit_l"] helpviewer_keywords: ["ismbcalpha function", "_ismbcalnum function", "ismbcdigit_l function", "_ismbcalnum_l function", "_ismbcdigit function", "ismbcalnum function", "_ismbcalpha_l function", "ismbcdigit function", "_ismbcalpha function", "_ismbcdigit_l function", "ismbcalnum_l function", "ismbcalpha_l function"] ms.assetid: 12d57925-aebe-46e0-80b0-82b84c4c31ec --- -# _ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l +# `_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l` Checks whether a multibyte character is an alphanumeric, alpha, or digit character. @@ -51,43 +51,43 @@ int _ismbcdigit_l ### Parameters -*c*
+*`c`*\ Character to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition or 0 if it does not. If *c*<= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`*<= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. ## Remarks Each of these routines tests a given multibyte character for a given condition. -The versions of these functions with the **_l** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the `_l` suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|**_ismbcalnum**, **_ismbcalnum_l**|Alphanumeric|Returns nonzero if and only if *c* is a single-byte representation of an ASCII English letter: See examples for **_ismbcdigit** and **_ismbcalpha**.| -|**_ismbcalpha**, **_ismbcalpha_l**|Alphabetic|Returns nonzero if and only if *c* is a single-byte representation of an ASCII English letter: 0x41<=*c*<=0x5A or 0x61<=*c*<=0x7A; or a katakana letter: 0xA6<=*c*<=0xDF.| -|**_ismbcdigit**, **_ismbcdigit**|Digit|Returns nonzero if and only if *c* is a single-byte representation of an ASCII digit: 0x30<=*c*<=0x39.| +| Routine | Test condition | Code page 932 example | +|---|---|---| +| **`_ismbcalnum`**, **`_ismbcalnum_l`** | Alphanumeric | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII English letter: See examples for **`_ismbcdigit`** and **`_ismbcalpha`**. | +| **`_ismbcalpha`**, **`_ismbcalpha_l`** | Alphabetic | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII English letter: 0x41<=*`c`*<=0x5A or 0x61<=*`c`*<=0x7A; or a katakana letter: 0xA6<=*`c`*<=0xDF. | +| **`_ismbcdigit`**, **`_ismbcdigit_l`** | Digit | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII digit: 0x30<=*`c`*<=0x39. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbcalnum**, **_ismbcalnum_l**|\| -|**_ismbcalpha**, **_ismbcalpha_l**|\| -|**_ismbcdigit**, **_ismbcdigit_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbcalnum`**, **`_ismbcalnum_l`** | \ | +| **`_ismbcalpha`**, **`_ismbcalpha_l`** | \ | +| **`_ismbcdigit`**, **`_ismbcdigit_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbcgraph-functions.md b/docs/c-runtime-library/reference/ismbcgraph-functions.md index e9573266e8..3358a70bca 100644 --- a/docs/c-runtime-library/reference/ismbcgraph-functions.md +++ b/docs/c-runtime-library/reference/ismbcgraph-functions.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcp title: "_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l" ms.date: "4/2/2020" api_name: ["_ismbcpunct_l", "_ismbcblank", "_ismbcprint", "_ismbcgraph_l", "_ismbcblank_l", "_ismbcpunct", "_ismbcprint_l", "_ismbcspace_l", "_ismbcspace", "_ismbcgraph", "_o__ismbcblank", "_o__ismbcblank_l", "_o__ismbcgraph", "_o__ismbcgraph_l", "_o__ismbcprint", "_o__ismbcprint_l", "_o__ismbcpunct", "_o__ismbcpunct_l", "_o__ismbcspace", "_o__ismbcspace_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbcspace", "_ismbcgraph", "_ismbcpunct", "ismbcspace_l", "ismbcgraph", "_ismbcgraph_l", "_ismbcprint", "_ismbcspace_l", "ismbcprint", "ismbcgraph_l", "ismbcspace", "ismbcpunct"] helpviewer_keywords: ["ismbcspace_l function", "_ismbcprint_l function", "ismbcspace function", "ismbcpunct function", "_ismbcspace_l function", "_ismbcprint function", "ismbcprint function", "_ismbcgraph function", "ismbcgraph_l function", "_ismbcpunct_l function", "ismbcpunct_l function", "ismbcprint_l function", "_ismbcpunct function", "ismbcgraph function", "_ismbcgraph_l function", "_ismbcspace function"] ms.assetid: 8e0a5f47-ba64-4411-92a3-3c525d16e3be --- -# _ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l +# `_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l` Determines whether character is a graphical character, a display character, a punctuation character, or a space character. @@ -59,58 +59,58 @@ int _ismbcspace_l( ### Parameters -*c*
+*`c`*\ Character to be determined. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition, or 0 if it does not. If *c* <= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`* <= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. -The versions of these functions are identical, except that the ones that have the **_l** suffix use the locale that's passed in for their locale-dependent behavior, instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions are identical, except that the ones that have the `_l` suffix use the locale that's passed in for their locale-dependent behavior, instead of the current locale. For more information, see [Locale](../locale.md). ## Remarks Each of these functions tests a given multibyte character for a given condition. -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|**_ismbcgraph**|Graphic|Returns nonzero if and only if *c* is a single-byte representation of any ASCII or katakana printable character except a white space ( ).| -|**_ismbcprint**|Printable|Returns nonzero if and only if *c* is a single-byte representation of any ASCII or katakana printable character including a white space ( ).| -|**_ismbcpunct**|Punctuation|Returns nonzero if and only if *c* is a single-byte representation of any ASCII or katakana punctuation character.| -|**_ismbcblank**|Space or horizontal tab|Returns nonzero if and only if *c* is a space or horizontal tab character: *c*=0x20 or *c*=0x09.| -|**_ismbcspace**|White space|Returns nonzero if and only if *c* is a white-space character: *c*=0x20 or 0x09<=*c*<=0x0D.| +| Routine | Test condition | Code page 932 example | +|---|---|---| +| **`_ismbcgraph`** | Graphic | Returns nonzero if and only if *`c`* is a single-byte representation of any ASCII or katakana printable character except a white space. | +| **`_ismbcprint`** | Printable | Returns nonzero if and only if *`c`* is a single-byte representation of any ASCII or katakana printable character including a white space. | +| **`_ismbcpunct`** | Punctuation | Returns nonzero if and only if *`c`* is a single-byte representation of any ASCII or katakana punctuation character. | +| **`_ismbcblank`** | Space or horizontal tab | Returns nonzero if and only if *`c`* is a space or horizontal tab character: *`c`*=0x20 or *`c`*=0x09. | +| **`_ismbcspace`** | White space | Returns nonzero if and only if *`c`* is a white-space character: *`c`*=0x20 or 0x09<=*`c`*<=0x0D. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbcgraph**|\| -|**_ismbcgraph_l**|\| -|**_ismbcprint**|\| -|**_ismbcprint_l**|\| -|**_ismbcpunct**|\| -|**_ismbcpunct_l**|\| -|**_ismbcblank**|\| -|**_ismbcblank_l**|\| -|**_ismbcspace**|\| -|**_ismbcspace_l**|\| - -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| Routine | Required header | +|---|---| +| **`_ismbcgraph`** | \ | +| **`_ismbcgraph_l`** | \ | +| **`_ismbcprint`** | \ | +| **`_ismbcprint_l`** | \ | +| **`_ismbcpunct`** | \ | +| **`_ismbcpunct_l`** | \ | +| **`_ismbcblank`** | \ | +| **`_ismbcblank_l`** | \ | +| **`_ismbcspace`** | \ | +| **`_ismbcspace_l`** | \ | + +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md b/docs/c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md index c5ee2f97cd..082cd1c8b4 100644 --- a/docs/c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md +++ b/docs/c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbchira, _ismbchira_l, _ismbckata, _ismbckata title: "_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l" ms.date: "4/2/2020" api_name: ["_ismbckata", "_ismbchira_l", "_ismbchira", "_ismbckata_l", "_o__ismbchira", "_o__ismbchira_l", "_o__ismbckata", "_o__ismbckata_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbckata_l", "_ismbckata_l", "ismbckata", "ismbchira", "_ismbckata", "ismbchira_l", "_ismbchira_l", "_ismbchira"] helpviewer_keywords: ["_ismbckata function", "_ismbchira function", "_ismbckata_l function", "Katakana", "ismbchira function", "_ismbchira_l function", "ismbchira_l function", "ismbdkata_l function", "Hiragana", "ismbckata function"] ms.assetid: 2db388a2-be31-489b-81c8-f6bf3f0582d3 --- -# _ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l +# `_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l` **Code Page 932 Specific functions** @@ -38,48 +38,48 @@ int _ismbckata_l( ### Parameters -*c*
+*`c`*\ Character to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition or 0 if it does not. If *c* <= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`* <= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. ## Remarks Each of these functions tests a given multibyte character for a given condition. -The versions of these functions with the **_l** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the `_l` suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -|Routine|Test condition (code page 932 only)| -|-------------|-------------------------------------------| -|**_ismbchira**|Double-byte Hiragana: 0x829F<=*c*<=0x82F1.| -|**_ismbchira_l**|Double-byte Hiragana: 0x829F<=*c*<=0x82F1.| -|**_ismbckata**|Double-byte katakana: 0x8340<=*c*<=0x8396.| -|**_ismbckata_l**|Double-byte katakana: 0x8340<=*c*<=0x8396.| +| Routine | Test condition (code page 932 only) | +|---|---| +| **`_ismbchira`** | Double-byte Hiragana: 0x829F<=*`c`*<=0x82F1. | +| **`_ismbchira_l`** | Double-byte Hiragana: 0x829F<=*`c`*<=0x82F1. | +| **`_ismbckata`** | Double-byte katakana: 0x8340<=*`c`*<=0x8396. | +| **`_ismbckata_l`** | Double-byte katakana: 0x8340<=*`c`*<=0x8396. | **End Code Page 932 Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbchira**|\| -|**_ismbchira_l**|\| -|**_ismbckata**|\| -|**_ismbckata_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbchira`** | \ | +| **`_ismbchira_l`** | \ | +| **`_ismbckata`** | \ | +| **`_ismbckata_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md b/docs/c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md index b6a7470c59..388ac76afa 100644 --- a/docs/c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md +++ b/docs/c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ism title: "_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l" ms.date: "4/2/2020" api_name: ["_ismbcl2", "_ismbcl1", "_ismbcl0", "_ismbcl2_l", "_ismbcl1_l", "_ismbcl0_l", "_o__ismbcl0", "_o__ismbcl0_l", "_o__ismbcl1", "_o__ismbcl1_l", "_o__ismbcl2", "_o__ismbcl2_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbcl0", "_ismbcl1_l", "_ismbcl0", "ismbcl1", "ismbcl0_l", "_ismbcl2_l", "ismbcl2", "ismbcl1_l", "_ismbcl1", "_ismbcl0_l", "_ismbcl2", "ismbcl2_l"] helpviewer_keywords: ["_ismbcl0_l function", "_ismbcl2 function", "_ismbcl1_l function", "ismbcl2 function", "_ismbcl1 function", "ismbcl0_l function", "ismbcl2_l function", "ismbcl1_l function", "ismbcl0 function", "ismbcl1 function", "_ismbcl2_l function", "_ismbcl0 function"] ms.assetid: ee15ebd1-462c-4a43-95f3-6735836d626a --- -# _ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l +# `_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l` **Code Page 932 Specific functions**, using the current locale or a specified LC_CTYPE conversion state category. @@ -45,52 +45,52 @@ int _ismbcl2_l( ### Parameters -*c*
+*`c`*\ Character to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition or 0 if it does not. If *c* <= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`* <= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. ## Remarks Each of these functions tests a given multibyte character for a given condition. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -|Routine|Test condition (code page 932 only)| -|-------------|-------------------------------------------| -|**_ismbcl0**|JIS non-Kanji: 0x8140<=*c*<=0x889E.| -|**_ismbcl0_l**|JIS non-Kanji: 0x8140<=*c*<=0x889E.| -|**_ismbcl1**|JIS level-1: 0x889F<=*c*<=0x9872.| -|**_ismbcl1_l**|JIS level-1: 0x889F<=*c*<=0x9872.| -|**_ismbcl2**|JIS level-2: 0x989F<=*c*<=0xEAA4.| -|**_ismbcl2_l**|JIS level-2: 0x989F<=*c*<=0xEAA4.| +| Routine | Test condition (code page 932 only) | +|---|---| +| **`_ismbcl0`** | JIS non-Kanji: 0x8140<=*`c`*<=0x889E. | +| **`_ismbcl0_l`** | JIS non-Kanji: 0x8140<=*`c`*<=0x889E. | +| **`_ismbcl1`** | JIS level-1: 0x889F<=*`c`*<=0x9872. | +| **`_ismbcl1_l`** | JIS level-1: 0x889F<=*`c`*<=0x9872. | +| **`_ismbcl2`** | JIS level-2: 0x989F<=*`c`*<=0xEAA4. | +| **`_ismbcl2_l`** | JIS level-2: 0x989F<=*`c`*<=0xEAA4. | -The functions check that the specified value *c* matches the test conditions described above, but do not check that *c* is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [_ismbbtrail](ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. +The functions check that the specified value *`c`* matches the test conditions described above, but don't check that *`c`* is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [`_ismbbtrail`](ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. **End Code Page 932 Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbcl0**|\| -|**_ismbcl0_l**|\| -|**_ismbcl1**|\| -|**_ismbcl1_l**|\| -|**_ismbcl2**|\| -|**_ismbcl2_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbcl0`** | \ | +| **`_ismbcl0_l`** | \ | +| **`_ismbcl1`** | \ | +| **`_ismbcl1_l`** | \ | +| **`_ismbcl2`** | \ | +| **`_ismbcl2_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md b/docs/c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md index 0c4e5cf981..d9dab358dd 100644 --- a/docs/c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md +++ b/docs/c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbc title: "_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l" ms.date: "4/2/2020" api_name: ["_ismbclegal_l", "_ismbclegal", "_ismbcsymbol", "_ismbcsymbol_l", "_o__ismbclegal", "_o__ismbclegal_l", "_o__ismbcsymbol", "_o__ismbcsymbol_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ismbcsymbol_l", "_ismbcsymbol_l", "_ismbcsymbol", "_ismbclegal_l", "_ismbclegal", "ismbclegal_l", "ismbcsymbol", "ismbclegal"] helpviewer_keywords: ["ismbcsymbol function", "ismbclegal_l function", "_istlegal_l function", "istlegal function", "_istlegal function", "_ismbcsymbol function", "_ismbclegal_l function", "ismbclegal function", "ismbcsymbol_l function", "_ismbclegal function", "_ismbcsymbol_l function", "istlegal_l function"] ms.assetid: 31bf1ea5-b56f-4e28-b21e-b49a2cf93ffc --- -# _ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l +# `_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l` Checks whether a multibyte character is a legal or symbol character. @@ -38,48 +38,48 @@ int _ismbcsymbol_l( ### Parameters -*c*
+*`c`*\ Character to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition or 0 if it does not. If *c*<= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`*<= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. ## Remarks Each of these functions tests a given multibyte character for a given condition. -The versions of these functions with the **_l** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the `_l` suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|**_ismbclegal**|Valid multibyte|Returns nonzero if and only if the first byte of *c* is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC.| -|**_ismbcsymbol**|Multibyte symbol|Returns nonzero if and only if 0x8141<=*c*<=0x81AC.| +| Routine | Test condition | Code page 932 example | +|---|---|---| +| **`_ismbclegal`** | Valid multibyte | Returns nonzero if and only if the first byte of *`c`* is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC. | +| **`_ismbcsymbol`** | Multibyte symbol | Returns nonzero if and only if 0x8141<=*`c`*<=0x81AC. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_istlegal**|Always returns false|**_ismbclegal**|Always returns false.| -|**_istlegal_l**|Always returns false|**_ismbclegal_l**|Always returns false.| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istlegal` | Always returns false | **`_ismbclegal`** | Always returns false. | +| `_istlegal_l` | Always returns false | **`_ismbclegal_l`** | Always returns false. | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbclegal**, **_ismbclegal_l**|\| -|**_ismbcsymbol**, **_ismbcsymbol_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbclegal`**, **`_ismbclegal_l`** | \ | +| **`_ismbcsymbol`**, **`_ismbcsymbol_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md b/docs/c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md index ebafbb921f..0efbdf592e 100644 --- a/docs/c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md +++ b/docs/c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbclower, _ismbclower_l, _ismbcupper, _ismbcu title: "_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l" ms.date: "4/2/2020" api_name: ["_ismbclower", "_ismbclower_l", "_ismbcupper_l", "_ismbcupper", "_o__ismbclower", "_o__ismbclower_l", "_o__ismbcupper", "_o__ismbcupper_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbcupper", "_ismbclower"] helpviewer_keywords: ["_ismbcupper function", "ismbclower function", "_ismbclower_l function", "ismbcupper_l function", "_ismbclower function", "ismbcupper function", "ismbclower_l function", "_ismbcupper_l function"] ms.assetid: 17d89587-65bc-477c-ba8f-a84e63cf59e7 --- -# _ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l +# `_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l` Checks whether a multibyte character is lowercase or uppercase. @@ -38,47 +38,47 @@ int _ismbcupper_l( ### Parameters -*c*
+*`c`*\ Character to be tested. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a nonzero value if the character satisfies the test condition or 0 if it does not. If *c*<= 255 and there is a corresponding **_ismbb** routine (for example, **_ismbcalnum** corresponds to **_ismbbalnum**), the result is the return value of the corresponding **_ismbb** routine. +Each of these routines returns a nonzero value if the character satisfies the test condition. Otherwise, they return 0. If *`c`*<= 255 and there's a corresponding `_ismbb` routine (for example, **`_ismbcalnum`** corresponds to `_ismbbalnum`), the result is the return value of the corresponding `_ismbb` routine. ## Remarks Each of these functions tests a given multibyte character for a given condition. -The versions of these functions with the **_l** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the `_l` suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|**_ismbclower**|Lowercase alphabetic|Returns nonzero if and only if *c* is a single-byte representation of an ASCII lowercase English letter: 0x61<=*c*<=0x7A.| -|**_ismbclower_l**|Lowercase alphabetic|Returns nonzero if and only if *c* is a single-byte representation of an ASCII lowercase English letter: 0x61<=*c*<=0x7A.| -|**_ismbcupper**|Uppercase alphabetic|Returns nonzero if and only if *c* is a single-byte representation of an ASCII uppercase English letter: 0x41<=*c*<=0x5A.| -|**_ismbcupper_l**|Uppercase alphabetic|Returns nonzero if and only if *c* is a single-byte representation of an ASCII uppercase English letter: 0x41<=*c*<=0x5A.| +| Routine | Test condition | Code page 932 example | +|---|---|---| +| **`_ismbclower`** | Lowercase alphabetic | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII lowercase English letter: 0x61<=*`c`*<=0x7A. | +| **`_ismbclower_l`** | Lowercase alphabetic | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII lowercase English letter: 0x61<=*`c`*<=0x7A. | +| **`_ismbcupper`** | Uppercase alphabetic | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII uppercase English letter: 0x41<=*`c`*<=0x5A. | +| **`_ismbcupper_l`** | Uppercase alphabetic | Returns nonzero if and only if *`c`* is a single-byte representation of an ASCII uppercase English letter: 0x41<=*`c`*<=0x5A. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ismbclower**|\| -|**_ismbclower_l**|\| -|**_ismbcupper**|\| -|**_ismbcupper_l**|\| +| Routine | Required header | +|---|---| +| **`_ismbclower`** | \ | +| **`_ismbclower_l`** | \ | +| **`_ismbcupper`** | \ | +| **`_ismbcupper_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md b/docs/c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md index 39a191a74f..3270a2428f 100644 --- a/docs/c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md +++ b/docs/c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _ismbslead, _ismbstrail, _ismbslead_l, _ismbstra title: "_ismbslead, _ismbstrail, _ismbslead_l, _ismbstrail_l" ms.date: "4/2/2020" api_name: ["_ismbstrail", "_ismbslead_l", "_ismbslead", "_ismbstrail_l", "_o__ismbslead", "_o__ismbslead_l", "_o__ismbstrail", "_o__ismbstrail_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ismbslead", "ismbs", "ismbslead_l", "_ismbs", "ismbstrail_l", "ismbslead", "_ismbstrail", "_ismbstrail_l", "ismbstrail", "_ismbslead_l"] helpviewer_keywords: ["ismbstrail function", "_ismbslead function", "ismbslead function", "ismbslead_l function", "_ismbstrail function", "_ismbslead_l function", "ismbstrail_l function", "_ismbstrail_l function"] ms.assetid: 86d2cd7a-3cff-443a-b713-14cc17a231e9 --- -# _ismbslead, _ismbstrail, _ismbslead_l, _ismbstrail_l +# `_ismbslead`, `_ismbstrail`, `_ismbslead_l`, `_ismbstrail_l` Performs context-sensitive tests for multibyte-character-string lead bytes and trail bytes and determines whether a given substring pointer points to a lead byte or a trail byte. @@ -42,43 +42,43 @@ int _ismbstrail_l( ### Parameters -*str*
+*`str`*\ Pointer to the start of the string or the previous known lead byte. -*current*
+*`current`*\ Pointer to the position in the string to be tested. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_ismbslead** returns -1 if the character is a lead byte and **_ismbstrail** returns -1 if the character is a trail byte. If the input strings are valid but are not a lead byte or trail byte, these functions return zero. If either argument is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **NULL** and set **errno** to **EINVAL**. +**`_ismbslead`** returns -1 if the character is a lead byte and **`_ismbstrail`** returns -1 if the character is a trail byte. If the input strings are valid but aren't a lead byte or trail byte, these functions return zero. If either argument is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set `errno` to `EINVAL`. ## Remarks -**_ismbslead** and **_ismbstrail** are slower than the **_ismbblead** and **_ismbbtrail** versions because they take the string context into account. +**`_ismbslead`** and **`_ismbstrail`** are slower than the **`_ismbblead`** and **`_ismbbtrail`** versions because they take the string context into account. -The versions of these functions that have the **_l** suffix are identical except that for their locale-dependent behavior they use the locale that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix are identical except that for their locale-dependent behavior they use the locale that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_ismbslead**|\ or \|\,* \, \| -|**_ismbstrail**|\ or \|\,* \, \| -|**_ismbslead_l**|\ or \|\,* \, \| -|**_ismbstrail_l**|\ or \|\,* \, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_ismbslead`** | \ or \ | \,* \, \ | +| **`_ismbstrail`** | \ or \ | \,* \, \ | +| **`_ismbslead_l`** | \ or \ | \,* \, \ | +| **`_ismbstrail_l`** | \ or \ | \,* \, \ | \* For manifest constants for the test conditions. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[_ismbc Routines](../../c-runtime-library/ismbc-routines.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Character classification](../character-classification.md)\ +[`_ismbc` routines](../ismbc-routines.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/isnan-isnan-isnanf.md b/docs/c-runtime-library/reference/isnan-isnan-isnanf.md index 46c6807865..c0815b33fc 100644 --- a/docs/c-runtime-library/reference/isnan-isnan-isnanf.md +++ b/docs/c-runtime-library/reference/isnan-isnan-isnanf.md @@ -7,12 +7,12 @@ api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvc api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_isnan", "isnan", "math/isnan", "math/_isnan", "math/_isnanf", "_isnanf"] -helpviewer_keywords: ["NAN (not a number)", "_isnan function", "IEEE floating-point representation", "Not a Number (NANs)", "isnan function"] +helpviewer_keywords: ["NaN (not a number)", "_isnan function", "IEEE floating-point representation", "Not a Number (NaNs)", "isnan function"] ms.assetid: 391fbc5b-89a4-4fba-997e-68f1131caf82 --- -# isnan, _isnan, _isnanf +# `isnan`, `_isnan`, `_isnanf` -Tests if a floating-point value is not a number (NAN). +Tests if a floating-point value is a NaN ("Not a Number"). ## Syntax @@ -37,37 +37,37 @@ bool isnan( ### Parameters -*x*
+*`x`*\ The floating-point value to test. -## Return Value +## Return value -In C, the **isnan** macro and the **_isnan** and **_isnanf** functions return a non-zero value if the argument *x* is a NAN; otherwise they return 0. +In C, the **`isnan`** macro and the **`_isnan`** and **`_isnanf`** functions return a non-zero value if the argument *`x`* is a NaN; otherwise they return 0. -In C++, the **isnan** template function returns **`true`** if the argument *x* is a NaN; otherwise it returns **`false`**. +In C++, the **`isnan`** template function returns **`true`** if the argument *`x`* is a NaN; otherwise it returns **`false`**. ## Remarks -Because a NaN value does not compare as equal to any other NaN value, you must use one of these functions or macros to detect one. A NaN is generated when the result of a floating-point operation can't be represented in IEEE-754 floating-point format for the specified type. For information about how a NaN is represented for output, see [printf](printf-printf-l-wprintf-wprintf-l.md). +Because a NaN value doesn't compare as equal to itself or to any other NaN value, to detect one, you must use one of these functions or macros. A NaN is generated when the result of a floating-point operation can't be represented in IEEE-754 floating-point format for the specified type. For information about how a NaN is represented for output, see [`printf`](printf-printf-l-wprintf-wprintf-l.md). -When compiled as C++, the **isnan** macro is not defined, and an **isnan** template function is defined instead. It behaves the same way as the macro, but returns a value of type **`bool`** instead of an integer. +When compiled as C++, the **`isnan`** macro isn't defined, and an **`isnan`** template function is defined instead. It behaves the same way as the macro, but returns a value of type **`bool`** instead of an integer. -The **_isnan** and **_isnanf** functions are Microsoft-specific. The **_isnanf** function is only available when compiled for x64. +The **`_isnan`** and **`_isnanf`** functions are Microsoft-specific. The **`_isnanf`** function is only available when compiled for x64. ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------------|-------------------------------| -|**isnan**, **_isnanf**|\|\ or \| -|**_isnan**|\|\ or \| +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`isnan`**, **`_isnanf`** | \ | \ or \ | +| **`_isnan`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/isnormal.md b/docs/c-runtime-library/reference/isnormal.md index f356d3ad0a..2ca56bdc5c 100644 --- a/docs/c-runtime-library/reference/isnormal.md +++ b/docs/c-runtime-library/reference/isnormal.md @@ -5,7 +5,7 @@ ms.date: "01/31/2019" f1_keywords: ["isnormal", "math/isnormal"] helpviewer_keywords: ["isnormal function"] --- -# isnormal +# `isnormal` Determines whether a floating-point value is a normal value. @@ -24,29 +24,29 @@ inline bool isnormal( ### Parameters -*x*
+*`x`*\ The floating-point value to test. ## Return value -**isnormal** returns a nonzero value (**`true`** in C++ code) if the argument *x* is neither zero, subnormal, infinite, nor a NaN. Otherwise, **isnormal** returns 0 (**`false`** in C++ code). +**`isnormal`** returns a nonzero value (**`true`** in C++ code) if the argument *`x`* isn't zero, subnormal, infinite, or a NaN. Otherwise, **`isnormal`** returns 0 (**`false`** in C++ code). ## Remarks -**isnormal** is a macro when compiled as C, and an inline function template when compiled as C++. +**`isnormal`** is a macro when compiled as C, and an inline function template when compiled as C++. ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -|**isnormal**|\|\ or \| +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`isnormal`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) diff --git a/docs/c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md b/docs/c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md index 964b76fba0..f8be7c4b3b 100644 --- a/docs/c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md +++ b/docs/c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isprint, iswprint, _isprint_l, _iswprint_l" title: "isprint, iswprint, _isprint_l, _iswprint_l" ms.date: "4/2/2020" api_name: ["iswprint", "isprint", "_isprint_l", "_iswprint_l", "_o_isprint", "_o_iswprint"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswprint", "_istprint", "isprint"] helpviewer_keywords: ["_istprint function", "iswprint function", "_iswprint_l function", "isprint_l function", "istprint function", "isprint function", "iswprint_l function", "_isprint_l function"] ms.assetid: a8bbcdb0-e8d0-4d8c-ae4e-56d3bdee6ca3 --- -# isprint, iswprint, _isprint_l, _iswprint_l +# `isprint`, `iswprint`, `_isprint_l`, `_iswprint_l` Determines whether an integer represents a printable character. @@ -35,43 +35,43 @@ int _iswprint_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a printable character. **isprint** returns a nonzero value if *c* is a printable character—this includes the space character (0x20 - 0x7E). **iswprint** returns a nonzero value if *c* is a printable wide character—this includes the space wide character. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a printable character. **`isprint`** returns a nonzero value if *`c`* is a printable character (0x20 - 0x7E), including the space character. **`iswprint`** returns a nonzero value if *`c`* is a printable wide character, including the space wide character. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The result of the test condition for these functions depends on the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions that do not have the **_l** suffix use the current locale for any locale-dependent behavior; the versions that do have the **_l** suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The result of the test condition for these functions depends on the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the `_l` suffix use the current locale for any locale-dependent behavior; the versions that do have the `_l` suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -The behavior of **isprint** and **_isprint_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isprint`** and **`_isprint_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_unicode defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istprint**|**isprint**|[_ismbcprint](ismbcgraph-functions.md)|**iswprint**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istprint` | **`isprint`** | [`_ismbcprint`](ismbcgraph-functions.md) | **`iswprint`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isprint**|\| -|**iswprint**|\ or \| -|**_isprint_l**|\| -|**_iswprint_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isprint`** | \ | +| **`iswprint`** | \ or \ | +| **`_isprint_l`** | \ | +| **`_iswprint_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md b/docs/c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md index 766d5c0e00..e39dc2e29a 100644 --- a/docs/c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md +++ b/docs/c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md @@ -3,14 +3,14 @@ description: "Learn more about: ispunct, iswpunct, _ispunct_l, _iswpunct_l" title: "ispunct, iswpunct, _ispunct_l, _iswpunct_l" ms.date: "4/2/2020" api_name: ["ispunct", "_iswpunct_l", "iswpunct", "_ispunct_l", "_o_ispunct", "_o_iswpunct"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswpunct", "_istpunct", "ispunct"] helpviewer_keywords: ["_istpunct function", "_ispunct_l function", "iswpunct function", "ispunct function", "istpunct function", "ispunct_l function", "_iswpunct_l function", "iswpunct_l function"] ms.assetid: 94403240-85c8-40a4-9c2b-e3e95c729c76 --- -# ispunct, iswpunct, _ispunct_l, _iswpunct_l +# `ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l` Determines whether an integer represents a punctuation character. @@ -35,43 +35,43 @@ int _iswpunct_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a punctuation character. **ispunct** returns a nonzero value for any printable character that is not a space character or a character for which **isalnum** is nonzero. **iswpunct** returns a nonzero value for any printable wide character that is neither the space wide character nor a wide character for which **iswalnum** is nonzero. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a punctuation character. **`ispunct`** returns a nonzero value for any printable character that isn't a space character or a character for which `isalnum` is nonzero. **`iswpunct`** returns a nonzero value for any printable wide character that isn't the space wide character or a wide character for which `iswalnum` is nonzero. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The result of the test condition for the **ispunct** function depends on the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions that do not have the **_l** suffix use the current locale for any locale-dependent behavior; the versions that do have the **_l** suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The result of the test condition for the **`ispunct`** function depends on the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the `_l` suffix use the current locale for any locale-dependent behavior; the versions that do have the `_l` suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -The behavior of **ispunct** and **_ispunct_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`ispunct`** and **`_ispunct_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istpunct**|**ispunct**|[_ismbcpunct](ismbcgraph-functions.md)|**iswpunct**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istpunct` | **`ispunct`** | [`_ismbcpunct`](ismbcgraph-functions.md) | **`iswpunct`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ispunct**|\| -|**iswpunct**|\ or \| -|**_ispunct_l**|\| -|**_iswpunct_l**|\ or \| +| Routine | Required header | +|---|---| +| **`ispunct`** | \ | +| **`iswpunct`** | \ or \ | +| **`_ispunct_l`** | \ | +| **`_iswpunct_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md b/docs/c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md index f4fbfb36c3..6896041898 100644 --- a/docs/c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md +++ b/docs/c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isspace, iswspace, _isspace_l, _iswspace_l" title: "isspace, iswspace, _isspace_l, _iswspace_l" ms.date: "4/2/2020" api_name: ["iswspace", "_isspace_l", "_iswspace_l", "isspace", "_o_isspace", "_o_iswspace"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswspace", "_istspace", "isspace"] helpviewer_keywords: ["iswspace function", "isspace function", "_iswspace_l function", "_isspace_l function", "iswspace_l function", "isspace_l function", "_istspace function", "istspace function"] ms.assetid: b851e0c0-36bb-4dac-a1a3-533540939035 --- -# isspace, iswspace, _isspace_l, _iswspace_l +# `isspace`, `iswspace`, `_isspace_l`, `_iswspace_l` Determines whether an integer represents a space character. @@ -35,43 +35,43 @@ int _iswspace_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a space character. **isspace** returns a nonzero value if *c* is a white-space character (0x09 - 0x0D or 0x20). The result of the test condition for the **isspace** function depends on the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions that do not have the **_l** suffix use the current locale for any locale-dependent behavior; the versions that do have the **_l** suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these routines returns nonzero if *`c`* is a particular representation of a space character. **`isspace`** returns a nonzero value if *`c`* is a white-space character (0x09 - 0x0D or 0x20). The result of the test condition for the **`isspace`** function depends on the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the `_l` suffix use the current locale for any locale-dependent behavior; the versions that do have the `_l` suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -**iswspace** returns a nonzero value if *c* is a wide character that corresponds to a standard white-space character. +**`iswspace`** returns a nonzero value if *`c`* is a wide character that corresponds to a standard white-space character. -The behavior of **isspace** and **_isspace_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isspace`** and **`_isspace_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_** **istspace**|**isspace**|[_ismbcspace](ismbcgraph-functions.md)|**iswspace**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istspace` | **`isspace`** | [`_ismbcspace`](ismbcgraph-functions.md) | **`iswspace`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isspace**|\| -|**iswspace**|\ or \| -|**_isspace_l**|\| -|**_iswspace_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isspace`** | \ | +| **`iswspace`** | \ or \ | +| **`_isspace_l`** | \ | +| **`_iswspace_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md b/docs/c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md index 42f4caeb4f..990f1271bb 100644 --- a/docs/c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md +++ b/docs/c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isupper, _isupper_l, iswupper, _iswupper_l" title: "isupper, _isupper_l, iswupper, _iswupper_l" ms.date: "4/2/2020" api_name: ["isupper", "iswupper", "_iswupper_l", "_isupper_l", "_o_isupper", "_o_iswupper"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["isupper", "_istupper", "iswupper"] helpviewer_keywords: ["istupper function", "iswupper function", "isupper_l function", "_isupper_l function", "iswupper_l function", "_istupper function", "_iswupper_l function", "isupper function"] ms.assetid: da2bcc9f-241c-48c0-9a0e-ad273827e16a --- -# isupper, _isupper_l, iswupper, _iswupper_l +# `isupper`, `_isupper_l`, `iswupper`, `_iswupper_l` Determines whether an integer represents an uppercase character. @@ -35,44 +35,44 @@ int _iwsupper_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of an uppercase letter. **isupper** returns a nonzero value if *c* is an uppercase character (A - Z). **iswupper** returns a nonzero value if *c* is a wide character that corresponds to an uppercase letter, or if *c* is one of an implementation-defined set of wide characters for which none of **iswcntrl**, **iswdigit**, **iswpunct**, or **iswspace** is nonzero. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of an uppercase letter. **`isupper`** returns a nonzero value if *`c`* is an uppercase character (A - Z). **`iswupper`** returns a nonzero value if *`c`* is a wide character that corresponds to an uppercase letter, or if *`c`* is one of an implementation-defined set of wide characters for which none of `iswcntrl`, `iswdigit`, `iswpunct`, or `iswspace` is nonzero. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -The versions of these functions that have the **_l** suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **isupper** and **_isupper_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isupper`** and **`_isupper_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istupper**|**isupper**|[_ismbcupper](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**iswupper**| -|**_istupper_l**|**_isupper_l**|[_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|**_iswupper_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istupper` | **`isupper`** | [`_ismbcupper`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | **`iswupper`** | +| `_istupper_l` | **`_isupper_l`** | [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | **`_iswupper_l`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isupper**|\| -|**_isupper_l**|\| -|**iswupper**|\ or \| -|**_iswupper_l**|\| +| Routine | Required header | +|---|---| +| **`isupper`** | \ | +| **`_isupper_l`** | \ | +| **`iswupper`** | \ or \ | +| **`_iswupper_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md b/docs/c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md index 7e0232dbd4..7f51b1e90e 100644 --- a/docs/c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md +++ b/docs/c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md @@ -3,14 +3,14 @@ description: "Learn more about: isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l" title: "isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l" ms.date: "4/2/2020" api_name: ["_iswxdigit_l", "iswxdigit", "isxdigit", "_isxdigit_l", "_o_iswxdigit", "_o_isxdigit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["iswxdigit", "isxdigit", "_istxdigit"] helpviewer_keywords: ["isxdigit function", "istxdigit function", "_iswxdigit_l function", "_istxdigit function", "_isxdigit_l function", "iswxdigit_l function", "isxdigit_l function", "hexadecimal characters", "iswxdigit function"] ms.assetid: c8bc5146-0b58-4e3f-bee3-f2318dd0f829 --- -# isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l +# `isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l` Determines whether an integer represents a character that is a hexadecimal digit. @@ -35,45 +35,45 @@ int _iswxdigit_l( ### Parameters -*c*
+*`c`*\ Integer to test. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns nonzero if *c* is a particular representation of a hexadecimal digit. **isxdigit** returns a nonzero value if *c* is a hexadecimal digit (A - F, a - f, or 0 - 9). **iswxdigit** returns a nonzero value if *c* is a wide character that corresponds to a hexadecimal digit character. Each of these routines returns 0 if *c* does not satisfy the test condition. +Each of these routines returns nonzero if *`c`* is a particular representation of a hexadecimal digit. **`isxdigit`** returns a nonzero value if *`c`* is a hexadecimal digit (A - F, a - f, or 0 - 9). **`iswxdigit`** returns a nonzero value if *`c`* is a wide character that corresponds to a hexadecimal digit character. Each of these routines returns 0 if *`c`* doesn't satisfy the test condition. -For the "C" locale, the **iswxdigit** function does not support Unicode full-width hexadecimal characters. +For the "C" locale, the **`iswxdigit`** function doesn't support Unicode full-width hexadecimal characters. -The versions of these functions that have the **_l** suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions that have the `_l` suffix use the locale that's passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -The behavior of **isxdigit** and **_isxdigit_l** is undefined if *c* is not EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *c* is not one of these values, the functions raise an assertion. +The behavior of **`isxdigit`** and **`_isxdigit_l`** is undefined if *`c`* isn't EOF or in the range 0 through 0xFF, inclusive. When a debug CRT library is used and *`c`* isn't one of these values, the functions raise an assertion. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_istxdigit**|**isxdigit**|**isxdigit**|**iswxdigit**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_istxdigit` | **`isxdigit`** | **`isxdigit`** | **`iswxdigit`** | ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**isxdigit**|\| -|**iswxdigit**|\ or \| -|**_isxdigit_l**|\| -|**_iswxdigit_l**|\ or \| +| Routine | Required header | +|---|---| +| **`isxdigit`** | \ | +| **`iswxdigit`** | \ or \ | +| **`_isxdigit_l`** | \ | +| **`_iswxdigit_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Character Classification](../../c-runtime-library/character-classification.md)
-[Locale](../../c-runtime-library/locale.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
+[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[`is`, `isw` routines](../is-isw-routines.md) diff --git a/docs/c-runtime-library/reference/itoa-itow.md b/docs/c-runtime-library/reference/itoa-itow.md index f62c01af57..1f03714208 100644 --- a/docs/c-runtime-library/reference/itoa-itow.md +++ b/docs/c-runtime-library/reference/itoa-itow.md @@ -3,12 +3,11 @@ title: "_itoa, _itow functions" description: "API reference for _itoa, and _itow; which convert an integer to a string." ms.date: "4/2/2020" api_name: ["itoa", "_itoa", "ltoa", "_ltoa", "ultoa", "_ultoa", "_i64toa", "_ui64toa", "_itow", "_ltow", "_ultow", "_i64tow", "_ui64tow", "_o__i64toa", "_o__i64tow", "_o__itoa", "_o__itow", "_o__ltoa", "_o__ltow", "_o__ui64toa", "_o__ui64tow", "_o__ultoa", "_o__ultow"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_itoa", "_ltoa", "_ultoa", "_i64toa", "_ui64toa", "_itow", "_ltow", "_ultow", "_i64tow", "_ui64tow", "itoa", "ltoa", "ultoa", "i64toa", "ui64toa", "itow", "ltow", "ultow", "i64tow", "ui64tow", "itot", "_itot", "ltot", "_ltot", "ultot", "_ultot", "i64tot", "_i64tot", "ui64tot", "_ui64tot", "_MAX_ITOSTR_BASE16_COUNT", "_MAX_ITOSTR_BASE10_COUNT", "_MAX_ITOSTR_BASE8_COUNT", "_MAX_ITOSTR_BASE2_COUNT", "_MAX_LTOSTR_BASE16_COUNT", "_MAX_LTOSTR_BASE10_COUNT", "_MAX_LTOSTR_BASE8_COUNT", "_MAX_LTOSTR_BASE2_COUNT", "_MAX_ULTOSTR_BASE16_COUNT", "_MAX_ULTOSTR_BASE10_COUNT", "_MAX_ULTOSTR_BASE8_COUNT", "_MAX_ULTOSTR_BASE2_COUNT", "_MAX_I64TOSTR_BASE16_COUNT", "_MAX_I64TOSTR_BASE10_COUNT", "_MAX_I64TOSTR_BASE8_COUNT", "_MAX_I64TOSTR_BASE2_COUNT", "_MAX_U64TOSTR_BASE16_COUNT", "_MAX_U64TOSTR_BASE10_COUNT", "_MAX_U64TOSTR_BASE8_COUNT", "_MAX_U64TOSTR_BASE2_COUNT"] helpviewer_keywords: ["_itot function", "ui64toa function", "_ui64toa function", "converting integers", "itot function", "_i64tow function", "_i64toa function", "_itow function", "ui64tow function", "integers, converting", "itoa function", "_ui64tow function", "i64tow function", "itow function", "i64toa function", "converting numbers, to strings", "_itoa function"] -ms.assetid: 46592a00-77bb-4e73-98c0-bf629d96cea6 --- # `itoa`, `_itoa`, `ltoa`, `_ltoa`, `ultoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `_ultow`, `_i64tow`, `_ui64tow` @@ -69,45 +68,45 @@ wchar_t * _ui64tow( unsigned long long value, wchar_t (&buffer)[size], ### Parameters -*`value`*
+*`value`*\ Number to be converted. -*`buffer`*
+*`buffer`*\ Buffer that holds the result of the conversion. -*`radix`*
+*`radix`*\ The base to use for the conversion of *`value`*, which must be in the range 2-36. -*`size`*
+*`size`*\ Length of the buffer in units of the character type. This parameter is inferred from the *`buffer`* argument in C++. -## Return Value +## Return value Each of these functions returns a pointer to *`buffer`*. There's no error return. ## Remarks -The **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, and **`_ui64toa`** functions convert the digits of the given *`value`* argument to a null-terminated character string and store the result (up to 33 characters for **`_itoa`**, **`_ltoa`**, and **`_ultoa`**, and 65 for **`_i64toa`** and **`_ui64toa`**) in *`buffer`*. If *`radix`* equals 10 and *value* is negative, the first character of the stored string is the minus sign (**-**). The **`_itow`**, **`_ltow`**, **`_ultow`**, **`_i64tow`**, and **`_ui64tow`** functions are wide-character versions of **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, and **`_ui64toa`**, respectively. +The **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, and **`_ui64toa`** functions convert the digits of the given *`value`* argument to a null-terminated character string and store the result (up to 33 characters for **`_itoa`**, **`_ltoa`**, and **`_ultoa`**, and 65 for **`_i64toa`** and **`_ui64toa`**) in *`buffer`*. If *`radix`* equals 10 and *`value`* is negative, the first character of the stored string is the minus sign (**-**). The **`_itow`**, **`_ltow`**, **`_ultow`**, **`_i64tow`**, and **`_ui64tow`** functions are wide-character versions of **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, and **`_ui64toa`**, respectively. > [!IMPORTANT] -> These functions can write past the end of a buffer that is too small. To prevent buffer overruns, ensure that *buffer* is large enough to hold the converted digits plus the trailing null-character and a sign character. Misuse of these functions can cause serious security issues in your code. +> These functions can write past the end of a buffer that is too small. To prevent buffer overruns, ensure that *`buffer`* is large enough to hold the converted digits plus the trailing null-character and a sign character. Misuse of these functions can cause serious security issues in your code. -Because of their potential for security issues, by default, these functions cause deprecation warning [C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md): **This function or variable may be unsafe. Consider using *`safe_function`* instead. To disable deprecation, use `_CRT_SECURE_NO_WARNINGS`.** We recommend you change your source code to use the *`safe_function`* suggested by the warning message. The more secure functions do not write more characters than the specified buffer size. For more information, see [`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md). +Because of their potential for security issues, by default, these functions cause deprecation warning [C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md): **This function or variable may be unsafe. Consider using *`safe_function`* instead. To disable deprecation, use `_CRT_SECURE_NO_WARNINGS`.** We recommend you change your source code to use the *`safe_function`* suggested by the warning message. The more secure functions don't write more characters than the specified buffer size. For more information, see [`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md). -To use these functions without the deprecation warning, define the **`_CRT_SECURE_NO_WARNINGS`** preprocessor macro before including any CRT headers. You can do this on the command line in a developer command prompt by adding the **`/D_CRT_SECURE_NO_WARNINGS`** compiler option to the **`cl`** command. Otherwise, define the macro in your source files. If you use precompiled headers, define the macro at the top of the precompiled header include file, *`pch.h`* (*`stdafx.h`* in Visual Studio 2017 and earlier). To define the macro in your source code, use a **`#define`** directive before you include any CRT header, as in this example: +To use these functions without the deprecation warning, define the `_CRT_SECURE_NO_WARNINGS` preprocessor macro before including any CRT headers. You can define it by adding the **`/D_CRT_SECURE_NO_WARNINGS`** compiler option to the **`cl`** command. Otherwise, define the macro in your source files. If you use precompiled headers, define the macro at the top of the precompiled header include file, *`pch.h`* (*`stdafx.h`* in Visual Studio 2017 and earlier). To define the macro in your source code, use a **`#define`** directive before you include any CRT header, as in this example: ```C -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). - #define _CRT_SECURE_NO_WARNINGS 1 #include ``` -In C++, these functions have template overloads that invoke their safer counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke their safer counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). + +By default, these functions' global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -The POSIX names **`itoa`**, **`ltoa`**, and **`ultoa`** exist as aliases for the **`_itoa`**, **`_ltoa`**, and **`_ultoa`** functions. The POSIX names are deprecated because they do not follow the implementation-specific global function name conventions of ISO C. By default, these functions cause deprecation warning [C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md): **The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name:** *`new_name`*. We recommend you change your source code to use the safer versions of these functions, **`_itoa_s`**, **`_ltoa_s`**, or **`_ultoa_s`**. For more information, see [`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md). +The POSIX names **`itoa`**, **`ltoa`**, and **`ultoa`** exist as aliases for the **`_itoa`**, **`_ltoa`**, and **`_ultoa`** functions. The POSIX names are deprecated because they don't follow the implementation-specific global function name conventions of ISO C. By default, these functions cause deprecation warning [C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md): **The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name:** *`new_name`*. We recommend you change your source code to use the safer versions of these functions, **`_itoa_s`**, **`_ltoa_s`**, or **`_ultoa_s`**. For more information, see [`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md). -For source code portability, you may prefer to retain the POSIX names in your code. To use these functions without the deprecation warning, define both the **`_CRT_NONSTDC_NO_WARNINGS`** and **`_CRT_SECURE_NO_WARNINGS`** preprocessor macros before including any CRT headers. You can do this on the command line in a developer command prompt by adding the **`/D_CRT_SECURE_NO_WARNINGS`** and **`/D_CRT_NONSTDC_NO_WARNINGS`** compiler options to the **`cl`** command. Otherwise, define the macros in your source files. If you use precompiled headers, define the macros at the top of the precompiled header include file. To define the macros in your source code, use **`#define`** directives before you include any CRT header, as in this example: +For source code portability, you may prefer to retain the POSIX names in your code. To use these functions without the deprecation warning, define both the `_CRT_NONSTDC_NO_WARNINGS` and `_CRT_SECURE_NO_WARNINGS` preprocessor macros before including any CRT headers. You can define them by adding the **`/D_CRT_SECURE_NO_WARNINGS`** and **`/D_CRT_NONSTDC_NO_WARNINGS`** compiler options to the **`cl`** command. Otherwise, define the macros in your source files. If you use precompiled headers, define the macros at the top of the precompiled header include file. To define the macros in your source code, use **`#define`** directives before you include any CRT header, as in this example: ```C #define _CRT_NONSTDC_NO_WARNINGS 1 @@ -117,17 +116,17 @@ For source code portability, you may prefer to retain the POSIX names in your co ### Maximum conversion count macros -To help you create secure buffers for conversions, the CRT includes some convenient macros. These define the size of the buffer required to convert the longest possible value of each integer type, including the null terminator and sign character, for several common bases. To ensure that your conversion buffer is large enough to receive any conversion in the base specified by *`radix`*, use one of these defined macros when you allocate the buffer. This helps to prevent buffer overrun errors when you convert integral types to strings. These macros are defined when you include either stdlib.h or wchar.h in your source. +To help you create secure buffers for conversions, the CRT includes some convenient macros. These macros define the size of the buffer required to convert the longest possible value of each integer type, including the null terminator and sign character, for several common bases. To ensure that your conversion buffer is large enough to receive any conversion in the base specified by *`radix`*, use one of these defined macros when you allocate the buffer. The macros help you prevent buffer overrun errors when you convert integral types to strings. These macros are defined when you include either stdlib.h or wchar.h in your source. To use one of these macros in a string conversion function, declare your conversion buffer of the appropriate character type and use the macro value for the integer type and base as the buffer dimension. This table lists the macros that are appropriate for each function for the listed bases: -|Functions|radix|Macros| -|-|-|-| -|**`_itoa`**, **`_itow`**|16
10
8
2|**`_MAX_ITOSTR_BASE16_COUNT`**
**`_MAX_ITOSTR_BASE10_COUNT`**
**`_MAX_ITOSTR_BASE8_COUNT`**
**`_MAX_ITOSTR_BASE2_COUNT`**| -|**`_ltoa`**, **`_ltow`**|16
10
8
2|**`_MAX_LTOSTR_BASE16_COUNT`**
**`_MAX_LTOSTR_BASE10_COUNT`**
**`_MAX_LTOSTR_BASE8_COUNT`**
**`_MAX_LTOSTR_BASE2_COUNT`**| -|**`_ultoa`**, **`_ultow`**|16
10
8
2|**`_MAX_ULTOSTR_BASE16_COUNT`**
**`_MAX_ULTOSTR_BASE10_COUNT`**
**`_MAX_ULTOSTR_BASE8_COUNT`**
**`_MAX_ULTOSTR_BASE2_COUNT`**| -|**`_i64toa`**, **`_i64tow`**|16
10
8
2|**`_MAX_I64TOSTR_BASE16_COUNT`**
**`_MAX_I64TOSTR_BASE10_COUNT`**
**`_MAX_I64TOSTR_BASE8_COUNT`**
**`_MAX_I64TOSTR_BASE2_COUNT`**| -|**`_ui64toa`**, **`_ui64tow`**|16
10
8
2|**`_MAX_U64TOSTR_BASE16_COUNT`**
**`_MAX_U64TOSTR_BASE10_COUNT`**
**`_MAX_U64TOSTR_BASE8_COUNT`**
**`_MAX_U64TOSTR_BASE2_COUNT`**| +| Functions | radix | Macros | +|---|---|---| +| **`_itoa`**, **`_itow`** | 16
10
8
2 | `_MAX_ITOSTR_BASE16_COUNT`
`_MAX_ITOSTR_BASE10_COUNT`
`_MAX_ITOSTR_BASE8_COUNT`
`_MAX_ITOSTR_BASE2_COUNT` | +| **`_ltoa`**, **`_ltow`** | 16
10
8
2 | `_MAX_LTOSTR_BASE16_COUNT`
`_MAX_LTOSTR_BASE10_COUNT`
`_MAX_LTOSTR_BASE8_COUNT`
`_MAX_LTOSTR_BASE2_COUNT` | +| **`_ultoa`**, **`_ultow`** | 16
10
8
2 | `_MAX_ULTOSTR_BASE16_COUNT`
`_MAX_ULTOSTR_BASE10_COUNT`
`_MAX_ULTOSTR_BASE8_COUNT`
`_MAX_ULTOSTR_BASE2_COUNT` | +| **`_i64toa`**, **`_i64tow`** | 16
10
8
2 | `_MAX_I64TOSTR_BASE16_COUNT`
`_MAX_I64TOSTR_BASE10_COUNT`
`_MAX_I64TOSTR_BASE8_COUNT`
`_MAX_I64TOSTR_BASE2_COUNT` | +| **`_ui64toa`**, **`_ui64tow`** | 16
10
8
2 | `_MAX_U64TOSTR_BASE16_COUNT`
`_MAX_U64TOSTR_BASE10_COUNT`
`_MAX_U64TOSTR_BASE8_COUNT`
`_MAX_U64TOSTR_BASE2_COUNT` | This example uses a conversion count macro to define a buffer large enough to contain an **`unsigned long long`** in base 2: @@ -137,33 +136,33 @@ This example uses a conversion count macro to define a buffer large enough to co int main() { wchar_t buffer[_MAX_U64TOSTR_BASE2_COUNT]; - std:wcout << _ui64tow(0xFFFFFFFFFFFFFFFFull, buffer, 2) << std::endl; + std::wcout << _ui64tow(0xFFFFFFFFFFFFFFFFull, buffer, 2) << std::endl; } ``` -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_itot`**|**`_itoa`**|**`_itoa`**|**`_itow`**| -|**`_ltot`**|**`_ltoa`**|**`_ltoa`**|**`_ltow`**| -|**`_ultot`**|**`_ultoa`**|**`_ultoa`**|**`_ultow`**| -|**`_i64tot`**|**`_i64toa`**|**`_i64toa`**|**`_i64tow`**| -|**`_ui64tot`**|**`_ui64toa`**|**`_ui64toa`**|**`_ui64tow`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_itot` | **`_itoa`** | **`_itoa`** | **`_itow`** | +| `_ltot` | **`_ltoa`** | **`_ltoa`** | **`_ltow`** | +| `_ultot` | **`_ultoa`** | **`_ultoa`** | **`_ultow`** | +| `_i64tot` | **`_i64toa`** | **`_i64toa`** | **`_i64tow`** | +| `_ui64tot` | **`_ui64toa`** | **`_ui64toa`** | **`_ui64tow`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`itoa`**, **`ltoa`**, **`ultoa`**|``| -|**`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, **`_ui64toa`**|``| -|**`_itow`**, **`_ltow`**, **`_ultow`**, **`_i64tow`**, **`_ui64tow`**|`` or ``| +| Routine | Required header | +|---|---| +| **`itoa`**, **`ltoa`**, **`ultoa`** | `` | +| **`_itoa`**, **`_ltoa`**, **`_ultoa`**, **`_i64toa`**, **`_ui64toa`** | `` | +| **`_itow`**, **`_ltow`**, **`_ultow`**, **`_i64tow`**, **`_ui64tow`** | `` or `` | -These functions and macros are Microsoft-specific. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions and macros are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This sample demonstrates the use of some of the integer conversion functions. Note the use of the **`_CRT_SECURE_NO_WARNINGS`** macro to silence warning C4996. +This sample demonstrates the use of some of the integer conversion functions. Note the use of the `_CRT_SECURE_NO_WARNINGS` macro to silence warning C4996. ```C // crt_itoa.c @@ -240,5 +239,5 @@ base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 cha ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md)
+[Data conversion](../data-conversion.md)\ +[`_itoa_s`, `_itow_s` functions](itoa-s-itow-s.md) diff --git a/docs/c-runtime-library/reference/itoa-s-itow-s.md b/docs/c-runtime-library/reference/itoa-s-itow-s.md index 74c8dd8bf6..bd52ce7408 100644 --- a/docs/c-runtime-library/reference/itoa-s-itow-s.md +++ b/docs/c-runtime-library/reference/itoa-s-itow-s.md @@ -3,7 +3,7 @@ description: "Learn more about: _itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_ title: "_itoa_s, _itow_s functions" ms.date: "4/2/2020" api_name: ["_itoa_s", "_ltoa_s", "_ultoa_s", "_i64toa_s", "_ui64toa_s", "_itow_s", "_ltow_s", "_ultow_s", "_i64tow_s", "_ui64tow_s", "_o__i64toa_s", "_o__i64tow_s", "_o__itoa_s", "_o__itow_s", "_o__ltoa_s", "_o__ltow_s", "_o__ui64toa_s", "_o__ui64tow_s", "_o__ultoa_s", "_o__ultow_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_itoa_s", "_ltoa_s", "_ultoa_s", "_i64toa_s", "_ui64toa_s", "_itow_s", "_ltow_s", "_ultow_s", "_i64tow_s", "_ui64tow_s", "_itot_s", "_ltot_s", "_ultot_s", "_i64tot_s", "_ui64tot_s", "itoa_s", "ltoa_s", "ultoa_s", "i64toa_s", "ui64toa_s", "itow_s", "ltow_s", "ultow_s", "i64tow_s", "ui64tow_s", "itot_s", "ltot_s", "ultot_s", "i64tot_s", "ui64tot_s"] @@ -12,7 +12,7 @@ ms.assetid: eb746581-bff3-48b5-a973-bfc0a4478ecf --- # `_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s` -Converts an integer to a string. These are versions of the [`_itoa`, `_itow` functions](itoa-itow.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts an integer to a string. These functions are versions of the [`_itoa`, `_itow` functions](itoa-itow.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -59,69 +59,69 @@ errno_t _ultow_s( unsigned long value, wchar_t (&buffer)[size], int radix ); ### Parameters -*`value`*
+*`value`*\ Number to be converted. -*`buffer`*
+*`buffer`*\ Output buffer that holds the result of the conversion. -*`size`*
+*`size`*\ Size of *`buffer`* in characters or wide characters. -*`radix`*
+*`radix`*\ The radix or numeric base to use to convert *`value`*, which must be in the range 2-36. ## Return value -Zero if successful; an error code on failure. If any of the following conditions applies, the function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +Zero if successful; an error code on failure. If any of the following conditions applies, the function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ### Error conditions -|value|buffer|size|radix|Return| -|-----------|------------|----------------------|-----------|------------| -|any|**`NULL`**|any|any|**`EINVAL`**| -|any|any|<=0|any|**`EINVAL`**| -|any|any|<= length of the result string required|any|**`EINVAL`**| -|any|any|any|*`radix`* < 2 or *`radix`* > 36|**`EINVAL`**| +| value | buffer | size | radix | Return | +|---|---|---|---|---| +| any | `NULL` | any | any | `EINVAL` | +| any | any | <=0 | any | `EINVAL` | +| any | any | <= length of the result string required | any | `EINVAL` | +| any | any | any | *`radix`* < 2 or *`radix`* > 36 | `EINVAL` | ### Security issues -These functions can generate an access violation if *`buffer`* does not point to valid memory and is not **`NULL`**, or if the length of the buffer is not long enough to hold the result string. +These functions can generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`, or if the length of the buffer isn't long enough to hold the result string. ## Remarks Except for the parameters and return value, the **`_itoa_s`** and **`_itow_s`** function families have the same behavior as the corresponding less secure **`_itoa`** and **`_itow`** versions. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). The CRT includes convenient macros to define the size of the buffer required to convert the longest possible value of each integer type, including the null terminator and sign character, for several common bases. For information, see [Maximum conversion count macros](itoa-itow.md#maximum-conversion-count-macros). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_itot_s`**|**`_itoa_s`**|**`_itoa_s`**|**`_itow_s`**| -|**`_ltot_s`**|**`_ltoa_s`**|**`_ltoa_s`**|**`_ltow_s`**| -|**`_ultot_s`**|**`_ultoa_s`**|**`_ultoa_s`**|**`_ultow_s`**| -|**`_i64tot_s`**|**`_i64toa_s`**|**`_i64toa_s`**|**`_i64tow_s`**| -|**`_ui64tot_s`**|**`_ui64toa_s`**|**`_ui64toa_s`**|**`_ui64tow_s`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_itot_s` | **`_itoa_s`** | **`_itoa_s`** | **`_itow_s`** | +| `_ltot_s` | **`_ltoa_s`** | **`_ltoa_s`** | **`_ltow_s`** | +| `_ultot_s` | **`_ultoa_s`** | **`_ultoa_s`** | **`_ultow_s`** | +| `_i64tot_s` | **`_i64toa_s`** | **`_i64toa_s`** | **`_i64tow_s`** | +| `_ui64tot_s` | **`_ui64toa_s`** | **`_ui64toa_s`** | **`_ui64tow_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_itoa_s`**, **`_ltoa_s`**, **`_ultoa_s`**, **`_i64toa_s`**, **`_ui64toa_s`**|``| -|**`_itow_s`**, **`_ltow_s`**, **`_ultow_s`**, **`_i64tow_s`**, **`_ui64tow_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_itoa_s`**, **`_ltoa_s`**, **`_ultoa_s`**, **`_i64toa_s`**, **`_ui64toa_s`** | `` | +| **`_itow_s`**, **`_ltow_s`**, **`_ultow_s`**, **`_i64tow_s`**, **`_ui64tow_s`** | `` or `` | -These functions are Microsoft-specific. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This sample demonstrates the use of a few of the integer conversion functions. Note that the [`_countof`](countof-macro.md) macro only works to determine buffer size when the array declaration is visible to the compiler, and not for parameters that have decayed to pointers. +This sample demonstrates the use of a few of the integer conversion functions. The [`_countof`](countof-macro.md) macro only works to determine buffer size when the array declaration is visible to the compiler, and not for parameters that have decayed to pointers. ```C // crt_itoa_s.c @@ -191,5 +191,5 @@ base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 cha ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[`_itoa`, `_itow` functions](itoa-itow.md)
+[Data conversion](../data-conversion.md)\ +[`_itoa`, `_itow` functions](itoa-itow.md) diff --git a/docs/c-runtime-library/reference/j0-j1-jn.md b/docs/c-runtime-library/reference/j0-j1-jn.md index cb433e020b..4d7acdfc7c 100644 --- a/docs/c-runtime-library/reference/j0-j1-jn.md +++ b/docs/c-runtime-library/reference/j0-j1-jn.md @@ -10,8 +10,8 @@ f1_keywords: ["jn", "j1", "j0"] helpviewer_keywords: ["jn function", "j1 function", "j0 function"] ms.assetid: ec8a9512-aacb-423c-a845-fc8927e6e21d --- -# j0, j1, jn +# `j0`, `j1`, `jn` -The Microsoft-implemented POSIX function names `j0`, `j1`, and `jn` are deprecated aliases for the [_j0, _j1, and _jn](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `j0`, `j1`, and `jn` are deprecated aliases for the [`_j0`, `_j1`, and `_jn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_j0, _j1, and _jn](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_j0`, `_j1`, and `_jn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/kbhit.md b/docs/c-runtime-library/reference/kbhit.md index 9c7062aa9a..3d89e65caa 100644 --- a/docs/c-runtime-library/reference/kbhit.md +++ b/docs/c-runtime-library/reference/kbhit.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _kbhit" title: "_kbhit" +description: "Learn more about: _kbhit" ms.date: "4/2/2020" api_name: ["_kbhit", "_o__kbhit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_kbhit", "conio/_kbhit"] helpviewer_keywords: ["keyboard input", "user input, checking for keyboard", "kbhit function", "console", "console, checking", "keyboards, keyboard input", "_kbhit function", "keyboards, checking input"] -ms.assetid: e82a1cc9-bbec-4150-b678-a7e433220fe4 --- # `_kbhit` @@ -20,11 +19,10 @@ Checks the console for keyboard input. ## Syntax ```C - int _kbhit( void ); ``` -## Return Value +## Return value **`_kbhit`** returns a nonzero value if a key has been pressed. Otherwise, it returns 0. @@ -32,19 +30,19 @@ int _kbhit( void ); The **`_kbhit`** function checks the console for a recent keystroke. If the function returns a nonzero value, a keystroke is waiting in the buffer. The program can then call **`_getch`** or **`_getche`** to get the keystroke. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_kbhit`**|``| +| Routine | Required header | +|---|---| +| **`_kbhit`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -71,7 +69,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! @@ -80,4 +78,4 @@ Key struck was 'q' ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
+[Console and port I/O](../console-and-port-i-o.md) diff --git a/docs/c-runtime-library/reference/ldexp.md b/docs/c-runtime-library/reference/ldexp.md index 5d447889a6..8cb4fae046 100644 --- a/docs/c-runtime-library/reference/ldexp.md +++ b/docs/c-runtime-library/reference/ldexp.md @@ -3,14 +3,14 @@ title: "ldexp, ldexpf, ldexpl" description: "API reference for ldexp, ldexpf, and ldexpl; which multiplies a floating-point number by an integral power of two." ms.date: "9/1/2020" api_name: ["ldexp", "ldexpf", "ldexpl", "_ldexpl", "_o_ldexp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ldexp", "ldexpf", "ldexpl", "_ldexpl"] helpviewer_keywords: ["calculating real numbers", "computing real numbers", "mantissas, floating-point variables", "ldexp function", "ldexpf function", "ldexpl function", "exponent, floating-point numbers", "floating-point functions, mantissa and exponent"] ms.assetid: aa7f5310-3879-4f63-ae74-86a39fbdedfa --- -# ldexp, ldexpf, ldexpl +# `ldexp`, `ldexpf`, `ldexpl` Multiplies a floating-point number by an integral power of two. @@ -43,34 +43,34 @@ long double ldexp( ### Parameters -*x*\ +*`x`*\ Floating-point value. -*exp*\ +*`exp`*\ Integer exponent. -## Return Value +## Return value -The **ldexp** functions return the value of *x* \* 2*exp* if successful. On overflow, and depending on the sign of *x*, **ldexp** returns +/- **HUGE_VAL**; the **errno** value is set to **ERANGE**. +The **`ldexp`** functions return the value of *`x`* \* 2*`exp`* if successful. On overflow, and depending on the sign of *`x`*, **`ldexp`** returns +/- `HUGE_VAL`; the `errno` value is set to `ERANGE`. -For more information about **errno** and possible error return values, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about `errno` and possible error return values, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **ldexp** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **ldexp** always takes a **`double`** and an **`int`** and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`ldexp`** that take **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`ldexp`** always takes a **`double`** and an **`int`** and returns a **`double`**. -If you use the \ `ldexp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `ldexp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ldexp**, **ldexpf**, **ldexpl**|\|\| -|**ldexp** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`ldexp`**, **`ldexpf`**, **`ldexpl`** | \ | \ | +| **`ldexp`** macro | \ | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,6 +98,6 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[frexp](frexp.md)
-[modf, modff, modfl](modf-modff-modfl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`frexp`](frexp.md)\ +[`modf`, `modff`, `modfl`](modf-modff-modfl.md) diff --git a/docs/c-runtime-library/reference/lfind-s.md b/docs/c-runtime-library/reference/lfind-s.md index dff27ec135..24ceae8760 100644 --- a/docs/c-runtime-library/reference/lfind-s.md +++ b/docs/c-runtime-library/reference/lfind-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _lfind_s" title: "_lfind_s" ms.date: "4/2/2020" api_name: ["_lfind_s", "_o__lfind_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["lfind_s", "_lfind_s"] helpviewer_keywords: ["linear searching", "keys, finding in arrays", "lfind_s function", "arrays [CRT], searching", "searching, linear", "_lfind_s function"] ms.assetid: f1d9581d-5c9d-4222-a31c-a6dfafefa40d --- -# _lfind_s +# `_lfind_s` -Performs a linear search for the specified key. A version of [_lfind](lfind.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Performs a linear search for the specified key. A version of [`_lfind`](lfind.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -29,54 +29,54 @@ void *_lfind_s( ### Parameters -*key*
+*`key`*\ Object to search for. -*base*
+*`base`*\ Pointer to the base of search data. -*number*
+*`number`*\ Number of array elements. -*size*
+*`size`*\ Size of array elements in bytes. -*compare*
-Pointer to comparison routine. The first parameter is the *context* pointer. The second parameter is a pointer to key for search. The third parameter is a pointer to array element to be compared with key. +*`compare`*\ +Pointer to comparison routine. The first parameter is the *`context`* pointer. The second parameter is a pointer to key for search. The third parameter is a pointer to array element to be compared with key. -*context*
+*`context`*\ A pointer to an object that might be accessed in the comparison function. -## Return Value +## Return value -If the key is found, **_lfind_s** returns a pointer to the element of the array at *base* that matches *key*. If the key is not found, **_lfind_s** returns **NULL**. +If the key is found, **`_lfind_s`** returns a pointer to the element of the array at *`base`* that matches *`key`*. If the key isn't found, **`_lfind_s`** returns `NULL`. -If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. +If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -### Error Conditions +### Error conditions -|key|base|compare|num|size|errno| -|---------|----------|-------------|---------|----------|-----------| -|**NULL**|any|any|any|any|**EINVAL**| -|any|**NULL**|any|!= 0|any|**EINVAL**| -|any|any|any|any|zero|**EINVAL**| -|any|any|**NULL**|an|any|**EINVAL**| +| *`key`* | *`base`* | *`compare`* | *`number`* | *`size`* | `errno` | +|---|---|---|---|---|---| +| `NULL` | any | any | any | any | `EINVAL` | +| any | `NULL` | any | != 0 | any | `EINVAL` | +| any | any | any | any | zero | `EINVAL` | +| any | any | `NULL` | an | any | `EINVAL` | ## Remarks -The **_lfind_s** function performs a linear search for the value *key* in an array of *number* elements, each of *width* bytes. Unlike **bsearch_s**, **_lfind_s** does not require the array to be sorted. The *base* argument is a pointer to the base of the array to be searched. The *compare* argument is a pointer to a user-supplied routine that compares two array elements and then returns a value specifying their relationship. **_lfind_s** calls the *compare* routine one or more times during the search, passing the *context* pointer and pointers to two array elements on each call. The *compare* routine must compare the elements then return nonzero (meaning that the elements are different) or 0 (meaning the elements are identical). +The **`_lfind_s`** function performs a linear search for the value *`key`* in an array of *`number`* elements, each of *`size`* bytes. Unlike `bsearch_s`, **`_lfind_s`** doesn't require the array to be sorted. The *`base`* argument is a pointer to the base of the array to be searched. The *`compare`* argument is a pointer to a user-supplied routine that compares two array elements and then returns a value specifying their relationship. **`_lfind_s`** calls the *`compare`* routine one or more times during the search, passing the *`context`* pointer and pointers to two array elements on each call. The *`compare`* routine must compare the elements then return nonzero (meaning that the elements are different) or 0 (meaning the elements are identical). -**_lfind_s** is similar to **_lfind** except for the addition of the *context* pointer to the arguments of the comparison function and the parameter list of the function. The *context* pointer can be useful if the searched data structure is part of an object and the *compare* function needs to access members of the object. The *compare* function can cast the void pointer into the appropriate object type and access members of that object. The addition of the *context* parameter makes **_lfind_s** more secure because additional context can be used to avoid reentrancy bugs associated with using static variables to make data available to the *compare* function. +**`_lfind_s`** is similar to **`_lfind`** except for the addition of the *`context`* pointer to the arguments of the comparison function and the parameter list of the function. The *`context`* pointer can be useful if the searched data structure is part of an object and the *`compare`* function needs to access members of the object. The *`compare`* function can cast the void pointer into the appropriate object type and access members of that object. The addition of the *`context`* parameter makes **`_lfind_s`** more secure because extra context can be used to avoid reentrancy bugs associated with using static variables to make data available to the *`compare`* function. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lfind_s**|\| +| Routine | Required header | +|---|---| +| **`_lfind_s`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -160,8 +160,8 @@ weit found ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[bsearch_s](bsearch-s.md)
-[_lsearch_s](lsearch-s.md)
-[qsort_s](qsort-s.md)
-[_lfind](lfind.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`bsearch_s`](bsearch-s.md)\ +[`_lsearch_s`](lsearch-s.md)\ +[`qsort_s`](qsort-s.md)\ +[`_lfind`](lfind.md) diff --git a/docs/c-runtime-library/reference/lfind.md b/docs/c-runtime-library/reference/lfind.md index be734ae9c6..e51bfcf381 100644 --- a/docs/c-runtime-library/reference/lfind.md +++ b/docs/c-runtime-library/reference/lfind.md @@ -3,16 +3,16 @@ description: "Learn more about: _lfind" title: "_lfind" ms.date: "4/2/2020" api_name: ["_lfind", "_o__lfind"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_lfind"] helpviewer_keywords: ["linear searching", "lfind function", "arrays [CRT], searching", "searching, linear", "finding keys in arrays", "_lfind function"] ms.assetid: a40ece70-1674-4b75-94bd-9f57cfff18f2 --- -# _lfind +# `_lfind` -Performs a linear search for the specified key. A more secure version of this function is available; see [_lfind_s](lfind-s.md). +Performs a linear search for the specified key. A more secure version of this function is available; see [`_lfind_s`](lfind-s.md). ## Syntax @@ -28,40 +28,40 @@ void *_lfind( ### Parameters -*key*
+*`key`*\ Object to search for. -*base*
+*`base`*\ Pointer to the base of search data. -*number*
+*`number`*\ Number of array elements. -*width*
+*`width`*\ Width of array elements. -*compare*
+*`compare`*\ Pointer to comparison routine. The first parameter is a pointer to key for search. The second parameter is a pointer to array element to be compared with key. -## Return Value +## Return value -If the key is found, **_lfind** returns a pointer to the element of the array at *base* that matches *key*. If the key is not found, **_lfind** returns **NULL**. +If the key is found, **`_lfind`** returns a pointer to the element of the array at *`base`* that matches *`key`*. If the key isn't found, **`_lfind`** returns `NULL`. ## Remarks -The **_lfind** function performs a linear search for the value *key* in an array of *number* elements, each of *width* bytes. Unlike **bsearch**, **_lfind** does not require the array to be sorted. The *base* argument is a pointer to the base of the array to be searched. The *compare* argument is a pointer to a user-supplied routine that compares two array elements and then returns a value specifying their relationship. **_lfind** calls the *compare* routine one or more times during the search, passing pointers to two array elements on each call. The *compare* routine must compare the elements and then return nonzero (meaning the elements are different) or 0 (meaning the elements are identical). +The **`_lfind`** function performs a linear search for the value *`key`* in an array of *`number`* elements, each of *`width`* bytes. Unlike `bsearch`, **`_lfind`** doesn't require the array to be sorted. The *`base`* argument is a pointer to the base of the array to be searched. The *`compare`* argument is a pointer to a user-supplied routine that compares two array elements and then returns a value specifying their relationship. **`_lfind`** calls the *`compare`* routine one or more times during the search, passing pointers to two array elements on each call. The *`compare`* routine must compare the elements and then return nonzero (meaning the elements are different) or 0 (meaning the elements are identical). -This function validates its parameters. If *compare*, *key* or *number* is **NULL**, or if *base* is **NULL** and *number* is nonzero, or if *width* is less than zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. +This function validates its parameters. If *`compare`*, *`key`* or *`number`* is `NULL`, or if *`base`* is `NULL` and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lfind**|\| +| Routine | Required header | +|---|---| +| **`_lfind`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -102,8 +102,8 @@ Hello found ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[_lfind_s](lfind-s.md)
-[bsearch](bsearch.md)
-[_lsearch](lsearch.md)
-[qsort](qsort.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`_lfind_s`](lfind-s.md)\ +[`bsearch`](bsearch.md)\ +[`_lsearch`](lsearch.md)\ +[`qsort`](qsort.md) diff --git a/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md b/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md index c2015fba47..e23d3050a2 100644 --- a/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md +++ b/docs/c-runtime-library/reference/lgamma-lgammaf-lgammal.md @@ -3,14 +3,14 @@ title: "lgamma, lgammaf, lgammal" description: "API reference for lgamma, lgammaf, and lgammal; which determines the natural logarithm of the absolute value of the gamma function of the specified value." ms.date: "9/1/2020" api_name: ["lgamma", "lgammaf", "lgammal", "_o_lgamma", "_o_lgammaf", "_o_lgammal"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["lgamma", "lgammaf", "lgammal", "math/lgamma", "math/lgammaf", "math/lgammal"] helpviewer_keywords: ["lgamma function", "lgammal function", "lgammaf function"] ms.assetid: 6e326c58-7077-481a-a329-c82ae56ae9e6 --- -# lgamma, lgammaf, lgammal +# `lgamma`, `lgammaf`, `lgammal` Determines the natural logarithm of the absolute value of the gamma function of the specified value. @@ -28,44 +28,44 @@ long double lgamma( long double x ); //C++ only ### Parameters -*x*\ +*`x`*\ The value to compute. -## Return Value +## Return value -If successful, return the natural logarithm of the absolute value of the gamma function of *x*. +If successful, return the natural logarithm of the absolute value of the gamma function of *`x`*. -|Issue|Return| -|-----------|------------| -|*x* = NaN|NaN| -|*x* = ±0|+INFINITY| -|*x*= negative integer|+INFINITY| -|±INFINITY|+INFINITY| -|pole error|+HUGE_VAL, +HUGE_VALF, or +HUGE_VALL| -|overflow range error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| +| Issue | Return | +|---|---| +| *`x`* = NaN | NaN | +| *`x`* = ±0 | +INFINITY | +| *`x`*= negative integer | +INFINITY | +| ±INFINITY | +INFINITY | +| pole error | +`HUGE_VAL`, +`HUGE_VALF`, or +`HUGE_VALL` | +| overflow range error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **lgamma** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **lgamma** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`lgamma`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`lgamma`** always takes and returns a **`double`**. -If you use the \ `lgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `lgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. If x is a rational number, this function returns the logarithm of the factorial of (x - 1). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**lgamma**, **lgammaf**, **lgammal**|\|\| -|**lgamma** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`lgamma`**, **`lgammaf`**, **`lgammal`** | \ | \ | +| **`lgamma`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[tgamma, tgammaf, tgammal](tgamma-tgammaf-tgammal.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`tgamma`, `tgammaf`, `tgammal`](tgamma-tgammaf-tgammal.md) diff --git a/docs/c-runtime-library/reference/localeconv.md b/docs/c-runtime-library/reference/localeconv.md index 6b5361aae1..6a309dfaa6 100644 --- a/docs/c-runtime-library/reference/localeconv.md +++ b/docs/c-runtime-library/reference/localeconv.md @@ -3,14 +3,14 @@ description: "Learn more about: localeconv" title: "localeconv" ms.date: "4/2/2020" api_name: ["localeconv", "_o_localeconv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["localeconv"] helpviewer_keywords: ["lconv type", "localeconv function", "locales, getting information on"] ms.assetid: 7ecdb1f2-88f5-4037-a0e7-c754ab003660 --- -# localeconv +# `localeconv` Gets detailed information on locale settings. @@ -20,66 +20,66 @@ Gets detailed information on locale settings. struct lconv *localeconv( void ); ``` -## Return Value +## Return value -**localeconv** returns a pointer to a filled-in object of type [struct lconv](../../c-runtime-library/standard-types.md). The values contained in the object are copied from the locale settings in thread-local storage, and can be overwritten by subsequent calls to **localeconv**. Changes made to the values in this object do not modify the locale settings. Calls to [setlocale](setlocale-wsetlocale.md) with *category* values of **LC_ALL**, **LC_MONETARY**, or **LC_NUMERIC** overwrite the contents of the structure. +**`localeconv`** returns a pointer to a filled-in object of type [`struct lconv`](../standard-types.md). The values contained in the object are copied from the locale settings in thread-local storage, and can be overwritten by subsequent calls to **`localeconv`**. Changes made to the values in this object don't modify the locale settings. Calls to [`setlocale`](setlocale-wsetlocale.md) with *`category`* values of `LC_ALL`, `LC_MONETARY`, or `LC_NUMERIC` overwrite the contents of the structure. ## Remarks -The **localeconv** function gets detailed information about numeric formatting for the current locale. This information is stored in a structure of type **lconv**. The **lconv** structure, defined in LOCALE.H, contains the following members: - -|Field|Meaning| -|-|-| -decimal_point,
_W_decimal_point|Pointer to decimal-point character for nonmonetary quantities. -thousands_sep,
_W_thousands_sep|Pointer to character that separates groups of digits to left of decimal point for nonmonetary quantities. -grouping|Pointer to a **`char`**-sized integer that contains the size of each group of digits in nonmonetary quantities. -int_curr_symbol,
_W_int_curr_symbol|Pointer to international currency symbol for current locale. First three characters specify alphabetic international currency symbol as defined in the *ISO 4217 Codes for the Representation of Currency and Funds* standard. Fourth character (immediately preceding null character) separates international currency symbol from monetary quantity. -currency_symbol,
_W_currency_symbol|Pointer to local currency symbol for current locale. -mon_decimal_point,
_W_mon_decimal_point|Pointer to decimal-point character for monetary quantities. -mon_thousands_sep,
_W_mon_thousands_sep|Pointer to separator for groups of digits to left of decimal place in monetary quantities. -mon_grouping|Pointer to a **`char`**-sized integer that contains the size of each group of digits in monetary quantities. -positive_sign,
_W_positive_sign|String denoting sign for nonnegative monetary quantities. -negative_sign,
_W_negative_sign|String denoting sign for negative monetary quantities. -int_frac_digits|Number of digits to right of decimal point in internationally formatted monetary quantities. -frac_digits|Number of digits to right of decimal point in formatted monetary quantities. -p_cs_precedes|Set to 1 if currency symbol precedes value for nonnegative formatted monetary quantity. Set to 0 if symbol follows value. -p_sep_by_space|Set to 1 if currency symbol is separated by space from value for nonnegative formatted monetary quantity. Set to 0 if there is no space separation. -n_cs_precedes|Set to 1 if currency symbol precedes value for negative formatted monetary quantity. Set to 0 if symbol succeeds value. -n_sep_by_space|Set to 1 if currency symbol is separated by space from value for negative formatted monetary quantity. Set to 0 if there is no space separation. -p_sign_posn|Position of positive sign in nonnegative formatted monetary quantities. -n_sign_posn|Position of positive sign in negative formatted monetary quantities. - -Except as specified, members of the **lconv** structure that have `char *` and `wchar_t *` versions are pointers to strings. Any of these that equals **""** (or **L""** for **`wchar_t`** \*) is either of zero length or not supported in the current locale. Note that **decimal_point** and **_W_decimal_point** are always supported and of nonzero length. - -The **`char`** members of the structure are small nonnegative numbers, not characters. Any of these that equals **CHAR_MAX** is not supported in the current locale. - -The values of **grouping** and **mon_grouping** are interpreted according to the following rules: - -- **CHAR_MAX** - Do not perform any further grouping. +The **`localeconv`** function gets detailed information about numeric formatting for the current locale. This information is stored in a structure of type `lconv`. The `lconv` structure, defined in LOCALE.H, contains the following members: + +| Field | Meaning | +|---|---| +| `decimal_point`,
`_W_decimal_point` | Pointer to decimal-point character for nonmonetary quantities. | +| `thousands_sep`,
`_W_thousands_sep` | Pointer to character that separates groups of digits to left of decimal point for nonmonetary quantities. | +| `grouping` | Pointer to a **`char`**-sized integer that contains the size of each group of digits in nonmonetary quantities. | +| `int_curr_symbol`,
`_W_int_curr_symbol` | Pointer to international currency symbol for current locale. First three characters specify alphabetic international currency symbol as defined in the *ISO 4217 Codes for the Representation of Currency and Funds* standard. Fourth character (immediately preceding null character) separates international currency symbol from monetary quantity. | +| `currency_symbol`,
`_W_currency_symbol` | Pointer to local currency symbol for current locale. | +| `mon_decimal_point`,
`_W_mon_decimal_point` | Pointer to decimal-point character for monetary quantities. | +| `mon_thousands_sep`,
`_W_mon_thousands_sep` | Pointer to separator for groups of digits to left of decimal place in monetary quantities. | +| `mon_grouping` | Pointer to a **`char`**-sized integer that contains the size of each group of digits in monetary quantities. | +| `positive_sign`,
`_W_positive_sign` | String denoting sign for nonnegative monetary quantities. | +| `negative_sign`,
`_W_negative_sign` | String denoting sign for negative monetary quantities. | +| `int_frac_digits` | Number of digits to right of decimal point in internationally formatted monetary quantities. | +| `frac_digits` | Number of digits to right of decimal point in formatted monetary quantities. | +| `p_cs_precedes` | Set to 1 if currency symbol precedes value for nonnegative formatted monetary quantity. Set to 0 if symbol follows value. | +| `p_sep_by_space` | Set to 1 if currency symbol is separated by space from value for nonnegative formatted monetary quantity. Set to 0 if there's no space separation. | +| `n_cs_precedes` | Set to 1 if currency symbol precedes value for negative formatted monetary quantity. Set to 0 if symbol succeeds value. | +| `n_sep_by_space` | Set to 1 if currency symbol is separated by space from value for negative formatted monetary quantity. Set to 0 if there's no space separation. | +| `p_sign_posn` | In nonnegative formatted monetary quantities, position of the positive sign. | +| `n_sign_posn` | In negative formatted monetary quantities, position of the positive sign. | + +Except as specified, members of the `lconv` structure that have `char *` and `wchar_t *` versions are pointers to strings. Any member that equals **`""`** (or **`L""`** for `wchar_t *`) is either of zero length, or not supported in the current locale. Both `decimal_point` and `_W_decimal_point` are always supported and have a nonzero length. + +The **`char`** members of the structure are small non-negative numbers, not characters. Any member that equals `CHAR_MAX` isn't supported in the current locale. + +The values of `grouping` and `mon_grouping` are interpreted according to the following rules: + +- `CHAR_MAX` - Don't perform any further grouping. - 0 - Use previous element for each of remaining digits. -- *n* - Number of digits that make up current group. Next element is examined to determine size of next group of digits before current group. +- *`n`* - Number of digits that make up current group. Next element is examined to determine size of next group of digits before current group. -The values for **int_curr_symbol** are interpreted according to the following rules: +The values for `int_curr_symbol` are interpreted according to the following rules: - The first three characters specify the alphabetic international currency symbol as defined in the *ISO 4217 Codes for the Representation of Currency and Funds* standard. - The fourth character (immediately preceding the null character) separates the international currency symbol from the monetary quantity. -The values for **p_cs_precedes** and **n_cs_precedes** are interpreted according to the following rules (the **n_cs_precedes** rule is in parentheses): +The values for `p_cs_precedes` and `n_cs_precedes` are interpreted according to the following rules (the `n_cs_precedes` rule is in parentheses): - 0 - Currency symbol follows value for nonnegative (negative) formatted monetary value. - 1 - Currency symbol precedes value for nonnegative (negative) formatted monetary value. -The values for **p_sep_by_space** and **n_sep_by_space** are interpreted according to the following rules (the **n_sep_by_space** rule is in parentheses): +The values for `p_sep_by_space` and `n_sep_by_space` are interpreted according to the following rules (the `n_sep_by_space` rule is in parentheses): - 0 - Currency symbol is separated from value by space for nonnegative (negative) formatted monetary value. -- 1 - There is no space separation between currency symbol and value for nonnegative (negative) formatted monetary value. +- 1 - There's no space separation between currency symbol and value for nonnegative (negative) formatted monetary value. -The values for **p_sign_posn** and **n_sign_posn** are interpreted according to the following rules: +The values for `p_sign_posn` and `n_sign_posn` are interpreted according to the following rules: - 0 - Parentheses surround quantity and currency symbol. @@ -91,24 +91,24 @@ The values for **p_sign_posn** and **n_sign_posn** are interpreted according to - 4 - Sign string immediately follows currency symbol. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**localeconv**|\| +| Routine | Required header | +|---|---| +| **`localeconv`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[setlocale](../../preprocessor/setlocale.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](strftime-wcsftime-strftime-l-wcsftime-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[`setlocale`](../../preprocessor/setlocale.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md b/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md index c64463e823..746082c2ad 100644 --- a/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md +++ b/docs/c-runtime-library/reference/localtime-localtime32-localtime64.md @@ -3,7 +3,7 @@ description: "Learn more about: localtime, _localtime32, _localtime64" title: "localtime, _localtime32, _localtime64" ms.date: "4/2/2020" api_name: ["_localtime64", "_localtime32", "localtime", "_o__localtime32", "_o__localtime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["localtime64", "_localtime64", "localtime32", "localtime", "_localtime32"] @@ -24,12 +24,12 @@ struct tm *_localtime64( const __time64_t *sourceTime ); ### Parameters -*`sourceTime`*
+*`sourceTime`*\ Pointer to stored time. -## Return Value +## Return value -Return a pointer to the structure result, or **`NULL`** if the date passed to the function is: +Return a pointer to the structure result, or `NULL` if the date passed to the function is: - Before midnight, January 1, 1970. @@ -39,46 +39,46 @@ Return a pointer to the structure result, or **`NULL`** if the date passed to th **`_localtime64`**, which uses the **`__time64_t`** structure, allows dates to be expressed up through 23:59:59, December 31, 3000, coordinated universal time (UTC), whereas **`_localtime32`** represents dates through 23:59:59 January 18, 2038, UTC. -**`localtime`** is an inline function which evaluates to **`_localtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. Doing this will cause **`localtime`** to evaluate to **`_localtime32`**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`localtime`** is an inline function that evaluates to **`_localtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. `_USE_32BIT_TIME_T` causes **`localtime`** to evaluate to **`_localtime32`**. We don't recommend `_USE_32BIT_TIME_T`, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. -The fields of the structure type [`tm`](../../c-runtime-library/standard-types.md) store the following values, each of which is an **`int`**: +The fields of the structure type [`tm`](../standard-types.md) store the following values, each of which is an **`int`**: -|Field|Description| -|-|-| -|**`tm_sec`**|Seconds after minute (0 - 59).| -|**`tm_min`**|Minutes after hour (0 - 59).| -|**`tm_hour`**|Hours since midnight (0 - 23).| -|**`tm_mday`**|Day of month (1 - 31).| -|**`tm_mon`**|Month (0 - 11; January = 0).| -|**`tm_year`**|Year (current year minus 1900).| -|**`tm_wday`**|Day of week (0 - 6; Sunday = 0).| -|**`tm_yday`**|Day of year (0 - 365; January 1 = 0).| -|**`tm_isdst`**|Positive value if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative value if status of daylight saving time is unknown.| +| Field | Description | +|---|---| +| **`tm_sec`** | Seconds after minute (0 - 59). | +| **`tm_min`** | Minutes after hour (0 - 59). | +| **`tm_hour`** | Hours since midnight (0 - 23). | +| **`tm_mday`** | Day of month (1 - 31). | +| **`tm_mon`** | Month (0 - 11; January = 0). | +| **`tm_year`** | Year (current year minus 1900). | +| **`tm_wday`** | Day of week (0 - 6; Sunday = 0). | +| **`tm_yday`** | Day of year (0 - 365; January 1 = 0). | +| **`tm_isdst`** | Positive value if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative value if status of daylight saving time is unknown. | If the **`TZ`** environment variable is set, the C run-time library assumes rules appropriate to the United States for implementing the calculation of daylight-saving time (DST). ## Remarks -The **`localtime`** function converts a time stored as a [`time_t`](../../c-runtime-library/standard-types.md) value and stores the result in a structure of type [`tm`](../../c-runtime-library/standard-types.md). The **`long`** value *`sourceTime`* represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is usually obtained from the [`time`](time-time32-time64.md) function. +The **`localtime`** function converts a time stored as a [`time_t`](../standard-types.md) value and stores the result in a structure of type [`tm`](../standard-types.md). The **`long`** value *`sourceTime`* represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is often obtained from the [`time`](time-time32-time64.md) function. Both the 32-bit and 64-bit versions of [`gmtime`](gmtime-gmtime32-gmtime64.md), [`mktime`](mktime-mktime32-mktime64.md), [`mkgmtime`](mkgmtime-mkgmtime32-mkgmtime64.md), and **`localtime`** all use a single **`tm`** structure per thread for the conversion. Each call to one of these routines destroys the result of the previous call. -**`localtime`** corrects for the local time zone if the user first sets the global environment variable **`TZ`**. When **`TZ`** is set, three other environment variables (**`_timezone`**, **`_daylight`**, and **`_tzname`**) are automatically set as well. If the **`TZ`** variable is not set, **`localtime`** attempts to use the time zone information specified in the Date/Time application in Control Panel. If this information cannot be obtained, PST8PDT, which signifies the Pacific Time Zone, is used by default. See [`_tzset`](tzset.md) for a description of these variables. **`TZ`** is a Microsoft extension and not part of the ANSI standard definition of **`localtime`**. +**`localtime`** corrects for the local time zone if the user first sets the global environment variable **`TZ`**. When **`TZ`** is set, three other environment variables (**`_timezone`**, **`_daylight`**, and **`_tzname`**) are automatically set as well. If the **`TZ`** variable isn't set, **`localtime`** attempts to use the time zone information specified in the Date/Time application in Control Panel. If this information can't be obtained, PST8PDT, which signifies the Pacific Time Zone, is used by default. See [`_tzset`](tzset.md) for a description of these variables. **`TZ`** is a Microsoft extension and not part of the ANSI standard definition of **`localtime`**. > [!NOTE] > The target environment should try to determine whether daylight saving time is in effect. -These functions validate their parameters. If *`sourceTime`* is a null pointer, or if the *`sourceTime`* value is negative, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return **`NULL`** and set **`errno`** to **`EINVAL`**. +These functions validate their parameters. If *`sourceTime`* is a null pointer, or if the *`sourceTime`* value is negative, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `NULL` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|---------------------|-| -|**`localtime`**, **`_localtime32`**, **`_localtime64`**|``|`` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`localtime`**, **`_localtime32`**, **`_localtime64`** | `` | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,11 +125,11 @@ Tue Feb 12 10:05:58 AM ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[`asctime`, `_wasctime`](asctime-wasctime.md)
-[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)
-[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)
-[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)
-[`time`, `_time32`, `_time64`](time-time32-time64.md)
-[`_tzset`](tzset.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md b/docs/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md index fde4e1b636..64aebc449d 100644 --- a/docs/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md +++ b/docs/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md @@ -3,7 +3,7 @@ description: "Learn more about: localtime_s, _localtime32_s, _localtime64_s" title: "localtime_s, _localtime32_s, _localtime64_s" ms.date: "4/2/2020" api_name: ["_localtime64_s", "_localtime32_s", "localtime_s", "_o__localtime32_s", "_o__localtime64_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_localtime32_s", "localtime32_s", "localtime_s", "localtime64_s", "_localtime64_s"] @@ -12,7 +12,7 @@ ms.assetid: 842d1dc7-d6f8-41d3-b340-108d4b90df54 --- # `localtime_s`, `_localtime32_s`, `_localtime64_s` -Converts a **`time_t`** time value to a **`tm`** structure, and corrects for the local time zone. These are versions of [`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a **`time_t`** time value to a **`tm`** structure, and corrects for the local time zone. These functions are versions of [`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,64 +33,64 @@ errno_t _localtime64_s( ### Parameters -*`tmDest`*
+*`tmDest`*\ Pointer to the time structure to be filled in. -*`sourceTime`*
+*`sourceTime`*\ Pointer to the stored time. -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in *`Errno.h`*. For a listing of these errors, see [`errno`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in *`Errno.h`*. For a listing of these errors, see [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Error Conditions +### Error conditions -|*`tmDest`*|*`sourceTime`*|Return value|Value in *`tmDest`*|Invokes invalid parameter handler| -|-----------|------------|------------------|--------------------|---------------------------------------| -|**`NULL`**|any|**`EINVAL`**|Not modified|Yes| -|Not **`NULL`** (points to valid memory)|**`NULL`**|**`EINVAL`**|All fields set to -1|Yes| -|Not **`NULL`** (points to valid memory)|less than 0 or greater than **`_MAX__TIME64_T`**|**`EINVAL`**|All fields set to -1|No| +| *`tmDest`* | *`sourceTime`* | Return value | Value in *`tmDest`* | Invokes invalid parameter handler | +|---|---|---|---|---| +| `NULL` | any | `EINVAL` | Not modified | Yes | +| Not `NULL` (points to valid memory) | `NULL` | `EINVAL` | All fields set to -1 | Yes | +| Not `NULL` (points to valid memory) | less than 0 or greater than `_MAX__TIME64_T` | `EINVAL` | All fields set to -1 | No | -In the case of the first two error conditions, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +The first two error conditions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -The **`localtime_s`** function converts a time stored as a [`time_t`](../../c-runtime-library/standard-types.md) value and stores the result in a structure of type [`tm`](../../c-runtime-library/standard-types.md). The **`time_t`** value *`sourceTime`* represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is usually obtained from the [`time`](time-time32-time64.md) function. +The **`localtime_s`** function converts a time stored as a [`time_t`](../standard-types.md) value and stores the result in a structure of type [`tm`](../standard-types.md). The **`time_t`** value *`sourceTime`* represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is often obtained from the [`time`](time-time32-time64.md) function. -**`localtime_s`** corrects for the local time zone if the user first sets the global environment variable **`TZ`**. When **`TZ`** is set, three other environment variables (**`_timezone`**, **`_daylight`**, and **`_tzname`**) are automatically set as well. If the **`TZ`** variable is not set, **`localtime_s`** attempts to use the time zone information specified in the Date/Time application in Control Panel. If this information cannot be obtained, PST8PDT, which signifies the Pacific time zone, is used by default. See [`_tzset`](tzset.md) for a description of these variables. **`TZ`** is a Microsoft extension and not part of the ANSI standard definition of **`localtime`**. +**`localtime_s`** corrects for the local time zone if the user first sets the global environment variable **`TZ`**. When **`TZ`** is set, three other environment variables (**`_timezone`**, **`_daylight`**, and **`_tzname`**) are automatically set as well. If the **`TZ`** variable isn't set, **`localtime_s`** attempts to use the time zone information specified in the Date/Time application in Control Panel. If this information can't be obtained, PST8PDT, which signifies the Pacific time zone, is used by default. See [`_tzset`](tzset.md) for a description of these variables. **`TZ`** is a Microsoft extension and not part of the ANSI standard definition of **`localtime`**. > [!NOTE] > The target environment should try to determine whether daylight saving time is in effect. **`_localtime64_s`**, which uses the **`__time64_t`** structure, allows dates to be expressed up through 23:59:59, January 18, 3001, coordinated universal time (UTC), whereas **`_localtime32_s`** represents dates through 23:59:59 January 18, 2038, UTC. -**`localtime_s`** is an inline function which evaluates to **`_localtime64_s`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. Doing this will cause **`localtime_s`** to evaluate to **`_localtime32_s`**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`localtime_s`** is an inline function that evaluates to **`_localtime64_s`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`, which causes **`localtime_s`** to evaluate to **`_localtime32_s`**. We don't recommend `_USE_32BIT_TIME_T`, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. -The fields of the structure type [`tm`](../../c-runtime-library/standard-types.md) store the following values, each of which is an **`int`**. +The fields of the structure type [`tm`](../standard-types.md) store the following values, each of which is an **`int`**. -|Field|Description| -|-|-| -|**`tm_sec`**|Seconds after minute (0 - 59).| -|**`tm_min`**|Minutes after hour (0 - 59).| -|**`tm_hour`**|Hours since midnight (0 - 23).| -|**`tm_mday`**|Day of month (1 - 31).| -|**`tm_mon`**|Month (0 - 11; January = 0).| -|**`tm_year`**|Year (current year minus 1900).| -|**`tm_wday`**|Day of week (0 - 6; Sunday = 0).| -|**`tm_yday`**|Day of year (0 - 365; January 1 = 0).| -|**`tm_isdst`**|Positive value if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative value if status of daylight saving time is unknown.| +| Field | Description | +|---|---| +| **`tm_sec`** | Seconds after minute (0 - 59). | +| **`tm_min`** | Minutes after hour (0 - 59). | +| **`tm_hour`** | Hours since midnight (0 - 23). | +| **`tm_mday`** | Day of month (1 - 31). | +| **`tm_mon`** | Month (0 - 11; January = 0). | +| **`tm_year`** | Year (current year minus 1900). | +| **`tm_wday`** | Day of week (0 - 6; Sunday = 0). | +| **`tm_yday`** | Day of year (0 - 365; January 1 = 0). | +| **`tm_isdst`** | Positive value if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative value if status of daylight saving time is unknown. | If the **`TZ`** environment variable is set, the C run-time library assumes rules appropriate to the United States for implementing the calculation of daylight saving time (DST). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|---------------------|-| -|**`localtime_s`**, **`_localtime32_s`**, **`_localtime64_s`**|``|`` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`localtime_s`**, **`_localtime32_s`**, **`_localtime64_s`** | `` | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -147,11 +147,11 @@ Fri Apr 25 01:19:27 PM ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)
-[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)
-[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)
-[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)
-[`time`, `_time32`, `_time64`](time-time32-time64.md)
-[`_tzset`](tzset.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/lock-file.md b/docs/c-runtime-library/reference/lock-file.md index bce549960b..d280928b8f 100644 --- a/docs/c-runtime-library/reference/lock-file.md +++ b/docs/c-runtime-library/reference/lock-file.md @@ -3,16 +3,16 @@ description: "Learn more about: _lock_file" title: "_lock_file" ms.date: "4/2/2020" api_name: ["_lock_file", "_o__lock_file"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_lock_file", "lock_file"] helpviewer_keywords: ["file locking [C++]", "_lock_file function", "lock_file function"] ms.assetid: 75c7e0e6-efff-4747-b6ed-9bcf2b0894c3 --- -# _lock_file +# `_lock_file` -Locks a **FILE** object to ensure consistency for threads accessing the **FILE** object concurrently. +Locks a `FILE` object to ensure consistency for threads accessing the `FILE` object concurrently. ## Syntax @@ -22,22 +22,22 @@ void _lock_file( FILE* file ); ### Parameters -*file*
+*`file`*\ File handle. ## Remarks -The **_lock_file** function locks the **FILE** object specified by *file*. The underlying file is not locked by **_lock_file**. Use [_unlock_file](unlock-file.md) to release the lock on the file. Calls to **_lock_file** and **_unlock_file** must be matched in a thread. +The **`_lock_file`** function locks the `FILE` object specified by *`file`*. The underlying file isn't locked by **`_lock_file`**. Use [`_unlock_file`](unlock-file.md) to release the lock on the file. Calls to **`_lock_file`** and **`_unlock_file`** must be matched in a thread. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lock_file**|\| +| Routine | Required header | +|---|---| +| **`_lock_file`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,7 +116,7 @@ eFciornsdt ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
-[_unlock_file](unlock-file.md)
+[File handling](../file-handling.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_unlock_file`](unlock-file.md) diff --git a/docs/c-runtime-library/reference/locking.md b/docs/c-runtime-library/reference/locking.md index 3f5ac0a2e3..0a5c13a75c 100644 --- a/docs/c-runtime-library/reference/locking.md +++ b/docs/c-runtime-library/reference/locking.md @@ -3,14 +3,14 @@ description: "Learn more about: _locking" title: "_locking" ms.date: "4/2/2020" api_name: ["_locking", "_o__locking"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_locking"] helpviewer_keywords: ["locking function", "bytes [C++], locking file", "files [C++], locking bytes", "files [C++], locking", "_locking function"] ms.assetid: 099aaac1-d4ca-4827-aed6-24dff9844150 --- -# _locking +# `_locking` Locks or unlocks bytes of a file. @@ -26,57 +26,57 @@ int _locking( ### Parameters -*fd*
+*`fd`*\ File descriptor. -*mode*
+*`mode`*\ Locking action to perform. -*nbytes*
+*`nbytes`*\ Number of bytes to lock. -## Return Value +## Return value -**_locking** returns 0 if successful. A return value of -1 indicates failure, in which case [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is set to one of the following values. +**`_locking`** returns 0 if successful. A return value of -1 indicates failure, in which case [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is set to one of the following values. -|errno value|Condition| -|-|-| -| **EACCES** | Locking violation (file already locked or unlocked). | -| **EBADF** | Invalid file descriptor. | -| **EDEADLOCK** | Locking violation. Returned when the **_LK_LOCK** or **_LK_RLCK** flag is specified and the file cannot be locked after 10 attempts. | -| **EINVAL** | An invalid argument was given to **_locking**. | +| `errno` value | Condition | +|---|---| +| `EACCES` | Locking violation (file already locked or unlocked). | +| `EBADF` | Invalid file descriptor. | +| `EDEADLOCK` | Locking violation. Returned when the `_LK_LOCK` or `_LK_RLCK` flag is specified and the file can't be locked after 10 attempts. | +| `EINVAL` | An invalid argument was given to **`_locking`**. | -If the failure is due to a bad parameter, such as an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If the failure is due to a bad parameter, such as an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). ## Remarks -The **_locking** function locks or unlocks *nbytes* bytes of the file specified by *fd*. Locking bytes in a file prevents access to those bytes by other processes. All locking or unlocking begins at the current position of the file pointer and proceeds for the next *nbytes* bytes. It is possible to lock bytes past end of file. +The **`_locking`** function locks or unlocks *`nbytes`* bytes of the file specified by *`fd`*. Locking bytes in a file prevents access to those bytes by other processes. All locking or unlocking begins at the current position of the file pointer and proceeds for the next *`nbytes`* bytes. It's possible to lock bytes past end of file. -*mode* must be one of the following manifest constants, which are defined in Locking.h. +*`mode`* must be one of the following manifest constants, which are defined in Locking.h. -|*mode* value|Effect| -|-|-| -| **_LK_LOCK** | Locks the specified bytes. If the bytes cannot be locked, the program immediately tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, the constant returns an error. | -| **_LK_NBLCK** | Locks the specified bytes. If the bytes cannot be locked, the constant returns an error. | -| **_LK_NBRLCK** | Same as **_LK_NBLCK**. | -| **_LK_RLCK** | Same as **_LK_LOCK**. | -| **_LK_UNLCK** | Unlocks the specified bytes, which must have been previously locked. | +| *`mode`* value | Effect | +|---|---| +| `_LK_LOCK` | Locks the specified bytes. If the bytes can't be locked, the program immediately tries again after 1 second. If the bytes can't be locked after 10 attempts, the constant returns an error. | +| `_LK_NBLCK` | Locks the specified bytes. If the bytes can't be locked, the constant returns an error. | +| `_LK_NBRLCK` | Same as `_LK_NBLCK`. | +| `_LK_RLCK` | Same as `_LK_LOCK`. | +| `_LK_UNLCK` | Unlocks the specified bytes, which must have been previously locked. | -Multiple regions of a file that do not overlap can be locked. A region being unlocked must have been previously locked. **_locking** does not merge adjacent regions; if two locked regions are adjacent, each region must be unlocked separately. Regions should be locked only briefly and should be unlocked before closing a file or exiting the program. +Multiple regions of a file that don't overlap can be locked. A region being unlocked must have been previously locked. **`_locking`** doesn't merge adjacent regions; if two locked regions are adjacent, each region must be unlocked separately. Regions should be locked only briefly and should be unlocked before closing a file or exiting the program. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_locking**|\ and \|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_locking`** | \ and \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -135,7 +135,7 @@ int main( void ) The first thirty bytes of this file will be locked. ``` -## Sample Output +## Sample output ```Output No one can change these bytes while I'm reading them @@ -145,6 +145,6 @@ Now I'm done. Do what you will with them ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
+[File handling](../file-handling.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/log-logf-log10-log10f.md b/docs/c-runtime-library/reference/log-logf-log10-log10f.md index d3ef3b370a..4ff277f7b0 100644 --- a/docs/c-runtime-library/reference/log-logf-log10-log10f.md +++ b/docs/c-runtime-library/reference/log-logf-log10-log10f.md @@ -3,7 +3,7 @@ title: "log, logf, logl, log10, log10f, log10l" description: "API reference for log, logf, logl, log10, log10f, and log10l; which calculate logarithms." ms.date: "9/1/2020" api_name: ["log10f", "logf", "log10", "log", "log10l", "logl", "_o_log", "_o_log10", "_o_log10f", "_o_logf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["logf", "logl", "_log10l", "log", "_logl", "log10f", "log10l", "log10"] @@ -36,15 +36,15 @@ long double log10(long double x); // C++ only *`x`*\ Value whose logarithm is to be found. -## Return Value +## Return value The **`log`** functions return the natural logarithm (base *`e`*) of *`x`* if successful. The **`log10`** functions return the base-10 logarithm. If *`x`* is negative, these functions return an indefinite (`IND`), by default. If *`x`* is 0, they return infinity (`INF`). -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± `QNAN`, `IND`|none|`_DOMAIN`| -|± 0|`ZERODIVIDE`|`_SING`| -|*`x < 0`*|`INVALID`|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| ± 0 | `ZERODIVIDE` | `_SING` | +| *`x < 0`* | `INVALID` | `_DOMAIN` | **`log`** and **`log10`** have an implementation that uses Streaming SIMD Extensions 2 (SSE2). See [`_set_SSE2_enable`](set-sse2-enable.md) for information and restrictions on using the SSE2 implementation. @@ -52,18 +52,18 @@ The **`log`** functions return the natural logarithm (base *`e`*) of *`x`* if su C++ allows overloading, so you can call overloads of **`log`** and **`log10`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`log`** and **`log10`** always take and return a **`double`**. -If you use the ` log()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the ` log()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`log`**, **`logf`**, **`logl`**, **`log10`**, **`log10f`**, **`log10l`**|``| -|**`log`** macro | `` | +| Routine | Required header | +|---|---| +| **`log`**, **`logf`**, **`logl`**, **`log10`**, **`log10f`**, **`log10l`** | `` | +| **`log`** macro | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,9 +122,9 @@ Log base 2 of 65536.000000 is 16.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md) \ -[`exp`, `expf`, `expl`](exp-expf.md) \ -[`_matherr`](matherr.md) \ -[`pow`, `powf`, `powl`](pow-powf-powl.md) \ -[`_CIlog`](../../c-runtime-library/cilog.md) \ -[`_CIlog10`](../../c-runtime-library/cilog10.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`_matherr`](matherr.md)\ +[`pow`, `powf`, `powl`](pow-powf-powl.md)\ +[`_CIlog`](../cilog.md)\ +[`_CIlog10`](../cilog10.md) diff --git a/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md b/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md index fa015db530..4b73bb4062 100644 --- a/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md +++ b/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md @@ -1,90 +1,78 @@ --- title: "log1p, log1pf, log1pl2" description: "API reference for log1p, log1pf, log1pl2; which compute the natural logarithm of 1 plus the specified value." -ms.date: "9/1/2020" +ms.date: "2/1/2023" api_name: ["log1p", "log1pf", "log1pl", "_o_log1p", "_o_log1pf", "_o_log1pl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["log1p", "log1pf", "log1pl", "math/log1p", "math/log1pf", "math/log1pl"] helpviewer_keywords: ["log1p function", "log1pf function", "log1pl function"] -ms.assetid: a40d965d-b4f6-42f4-ba27-2395546f7c12 --- -# log1p, log1pf, log1pl +# `log1p`, `log1pf`, `log1pl` Computes the natural logarithm of 1 plus the specified value. ## Syntax ```C -double log1p( - double x -); -float log1pf( - float x -); -long double log1pl( - long double x -); +double log1p(double x); +float log1pf(float x); +long double log1pl(long double x); #define log1p(X) // Requires C11 or higher -float log1p( - float x -); //C++ only - -long double log1p( - long double x -); //C++ only +float log1p(float x); //C++ only +long double log1p(long double x); //C++ only ``` ### Parameters -*x*\ +*`x`*\ The floating-point argument. -## Return Value +## Return value -If successful, returns the natural (base-*e*) log of (*x* + 1). +If successful, returns the natural (base-*e*) log of (*`x`* + 1). Otherwise, may return one of the following values: -|Input|Result|SEH exception|errno| -|-----------|------------|-------------------|-----------| -|+inf|+inf||| -|Denormals|Same as input|UNDERFLOW|| -|±0|Same as input||| -|-1|-inf|DIVBYZERO|ERANGE| -|< -1|nan|INVALID|EDOM| -|-inf|nan|INVALID|EDOM| -|±SNaN|Same as input|INVALID|| -|±QNaN, indefinite|Same as input||| +| Input | Result | SEH exception | errno | +|---|---|---|---| +| +INF | +INF | | | +| Denormals | Same as input | `UNDERFLOW` | | +| ±0 | Same as input | | | +| -1 | -INF | `DIVBYZERO` | `ERANGE` | +| < -1 | NaN | `INVALID` | `EDOM` | +| -INF | NaN | `INVALID` | `EDOM` | +| ±SNaN | Same as input | `INVALID` | | +| ±QNaN, indefinite | Same as input | | | -The **errno** value is set to ERANGE if *x* = -1. The **errno** value is set to **EDOM** if *x* < -1. +The `errno` value is set to ERANGE if *`x`* = -1. The `errno` value is set to `EDOM` if *`x`* < -1. ## Remarks -The **log1p** functions may be more accurate than using `log(x + 1)` when *x* is near 0. +The **`log1p`** functions may be more accurate than using `log(x + 1)` when *`x`* is near 0. -Because C++ allows overloading, you can call overloads of **log1p** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **log1p** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`log1p`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`log1p`** always takes and returns a **`double`**. -If you use the \ `log1p()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `` `log1p()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -If *x* is a natural number, this function returns the logarithm of the factorial of (*x* - 1). +Where *`x`* is a natural number, this function returns the base e logarithm of *`x`* + 1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**log1p**, **log1pf**, **log1pl**|\|\| -|**log1p** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`log1p`**, **`log1pf`**, **`log1pl`** | `` | `` | +| **`log1p`** macro | `` | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)\ -[log2, log2f, log2l](log2-log2f-log2l.md)\ -[log, logf, log10, log10f](log-logf-log10-log10f.md) +[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`log2`, `log2f`, `log2l`](log2-log2f-log2l.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/reference/log2-log2f-log2l.md b/docs/c-runtime-library/reference/log2-log2f-log2l.md index 855e6f92fb..9a70db2e0c 100644 --- a/docs/c-runtime-library/reference/log2-log2f-log2l.md +++ b/docs/c-runtime-library/reference/log2-log2f-log2l.md @@ -3,12 +3,12 @@ title: "log2, log2f, log2l" description: "API reference for log2, log2f, and log2l; which determine the binary (base-2) logarithm of the specified value." ms.date: "9/1/2020" api_name: ["log2", "log2l", "log2f", "_o_log2", "_o_log2f", "_o_log2l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] ms.assetid: 94d11b38-70b7-4d3a-94ac-523153c92b2e --- -# log2, log2f, log2l +# `log2`, `log2f`, `log2l` Determines the binary (base-2) logarithm of the specified value. @@ -40,44 +40,44 @@ long double log2l( ### Parameters -*x*\ +*`x`*\ The value to determine the base-2 logarithm of. -## Return Value +## Return value -On success, returns return log2 *x*. +On success, the functions return the base-2 log of *`x`*. -Otherwise, may return one of the following values: +Otherwise, the functions may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* < 0|NaN| -|*x* = ±0|-INFINITY| -|*x* = 1|+0| -|+INFINITY|+INFINITY| -|NaN|NaN| -|domain error|NaN| -|pole error|-HUGE_VAL, -HUGE_VALF, or -HUGE_VALL| +| Issue | Return | +|---|---| +| *`x`* < 0 | NaN | +| *`x`* = ±0 | -INFINITY | +| *`x`* = 1 | +0 | +| +INFINITY | +INFINITY | +| NaN | NaN | +| domain error | NaN | +| pole error | -`HUGE_VAL`, -`HUGE_VALF`, or -`HUGE_VALL` | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -If *x* is an integer, this function essentially returns the zero-based index of the most significant 1 bit of *x*. +If *`x`* is an integer, this function essentially returns the zero-based index of the most significant 1 bit of *`x`*. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**log2**, **log2f**, **log2l**|\|\| -|**log2** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`log2`**, **`log2f`**, **`log2l`** | \ | \ | +| **`log2`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[exp2, exp2f, exp2l](exp2-exp2f-exp2l.md)
-[log, logf, log10, log10f](log-logf-log10-log10f.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`exp2`, `exp2f`, `exp2l`](exp2-exp2f-exp2l.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md b/docs/c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md index e7e3e71d9c..30a4afeca7 100644 --- a/docs/c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md +++ b/docs/c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md @@ -3,7 +3,7 @@ title: "logb, logbf, logbl, _logb, _logbf" description: "API reference for logb, logbf, logbl, _logb, and _logbf; which extract the exponent value of a floating-point argument." ms.date: "1/15/2021" api_name: ["logb", "_logb", "_logbl", "logbf", "_logbf", "logbl", "_o__logb", "_o_logb", "_o_logbf", "_o_logbl", "_o__logbf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["logb", "logbl", "_logb", "_logbf", "logbf"] @@ -45,7 +45,7 @@ float _logbf( *`x`*\ A floating-point value. -## Return Value +## Return value **`logb`** returns the unbiased exponent value of *`x`* as a signed integer represented as a floating-point value. @@ -55,30 +55,30 @@ The **`logb`** functions extract the exponential value of the floating-point arg Because C++ allows overloading, you can call overloads of **`logb`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`logb`** always takes and returns a **`double`**. -If you use the `` `logb()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `logb` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|`± QNAN`,`IND`|None|`_DOMAIN`| -|± 0|`ZERODIVIDE`|`_SING`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | None | `_DOMAIN` | +| ± 0 | `ZERODIVIDE` | `_SING` | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_logb`**|``| -|**`logb`**, **`logbf`**, **`logbl`**, **`_logbf`**|``| -|**`logb`** macro | `` | +| Routine | Required header | +|---|---| +| **`_logb`** | `` | +| **`logb`**, **`logbf`**, **`logbl`**, **`_logbf`** | `` | +| **`logb`** macro | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`frexp`](frexp.md) diff --git a/docs/c-runtime-library/reference/longjmp.md b/docs/c-runtime-library/reference/longjmp.md index 5c23d5eb6e..da78b65d11 100644 --- a/docs/c-runtime-library/reference/longjmp.md +++ b/docs/c-runtime-library/reference/longjmp.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: longjmp" title: "longjmp" +description: "Learn more about: longjmp" ms.date: "1/14/2021" api_name: ["longjmp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["longjmp"] helpviewer_keywords: ["restoring stack environment and execution locale", "longjmp function"] -ms.assetid: 0e13670a-5130-45c1-ad69-6862505b7a2f --- -# longjmp +# `longjmp` Restores the stack environment and execution locale set by a `setjmp` call. @@ -25,33 +24,33 @@ void longjmp( ### Parameters -*env*
+*`env`*\ Variable in which environment is stored. -*value*
+*`value`*\ Value to be returned to `setjmp` call. ## Remarks -The **longjmp** function restores a stack environment and execution locale previously saved in *env* by `setjmp`. `setjmp` and **longjmp** provide a way to execute a nonlocal **`goto`**; they are typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal call and return conventions. +The **`longjmp`** function restores a stack environment and execution locale previously saved in *`env`* by `setjmp`. `setjmp` and **`longjmp`** provide a way to execute a nonlocal **`goto`**; they're typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal call and return conventions. -A call to `setjmp` causes the current stack environment to be saved in *env*. A subsequent call to **longjmp** restores the saved environment and returns control to the point immediately following the corresponding `setjmp` call. Execution resumes as if *value* had just been returned by the `setjmp` call. The values of all variables (except register variables) that are accessible to the routine receiving control contain the values they had when **longjmp** was called. The values of register variables are unpredictable. The value returned by `setjmp` must be nonzero. If *value* is passed as 0, the value 1 is substituted in the actual return. +A call to `setjmp` causes the current stack environment to be saved in *`env`*. A subsequent call to **`longjmp`** restores the saved environment and returns control to the point immediately following the corresponding `setjmp` call. Execution resumes as if *`value`* had been returned by the `setjmp` call. The values of all variables (except register variables) that are accessible to the routine receiving control contain the values they had when **`longjmp`** was called. The values of register variables are unpredictable. The value returned by `setjmp` must be nonzero. If *`value`* is passed as 0, the value 1 is substituted in the actual return. **Microsoft Specific** -In Microsoft C++ code on Windows, **longjmp** uses the same stack-unwinding semantics as exception-handling code. It is safe to use in the same places that C++ exceptions can be raised. However, this usage is not portable, and comes with some important caveats. +In Microsoft C++ code on Windows, **`longjmp`** uses the same stack-unwinding semantics as exception-handling code. It's safe to use in the same places that C++ exceptions can be raised. However, this usage isn't portable, and comes with some important caveats. -Only call **longjmp** before the function that called `setjmp` returns; otherwise the results are unpredictable. +Only call **`longjmp`** before the function that called `setjmp` returns; otherwise the results are unpredictable. -Observe the following restrictions when using **longjmp**: +Observe the following restrictions when using **`longjmp`**: -- Do not assume that the values of the register variables will remain the same. The values of register variables in the routine calling `setjmp` may not be restored to the proper values after **longjmp** is executed. +- Don't assume that the values of the register variables will remain the same. The values of register variables in the routine calling `setjmp` may not be restored to the proper values after **`longjmp`** is executed. -- Do not use **longjmp** to transfer control out of an interrupt-handling routine unless the interrupt is caused by a floating-point exception. In this case, a program may return from an interrupt handler via **longjmp** if it first reinitializes the floating-point math package by calling [_fpreset](fpreset.md). +- Don't use **`longjmp`** to transfer control out of an interrupt-handling routine unless the interrupt is caused by a floating-point exception. In this case, a program may return from an interrupt handler via **`longjmp`** if it first reinitializes the floating-point math package by calling [`_fpreset`](fpreset.md). -- Do not use **longjmp** to transfer control from a callback routine invoked directly or indirectly by Windows code. +- Don't use **`longjmp`** to transfer control from a callback routine invoked directly or indirectly by Windows code. -- If the code is compiled by using **/EHs** or **/EHsc** and the function that contains the **longjmp** call is **`noexcept`** then local objects in that function may not be destructed during the stack unwind. +- If the code is compiled by using **/EHs** or **/EHsc**, and the function that contains the **`longjmp`** call is **`noexcept`**, then local objects in that function may not be destructed during the stack unwind. **END Microsoft Specific** @@ -63,17 +62,17 @@ For more information, see [Using setjmp and longjmp](../../cpp/using-setjmp-long ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**longjmp**|\| +| Routine | Required header | +|---|---| +| **`longjmp`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_fpreset](fpreset.md). +See the example for [`_fpreset`](fpreset.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[setjmp](setjmp.md) +[Process and environment control](../process-and-environment-control.md)\ +[`setjmp`](setjmp.md) diff --git a/docs/c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md b/docs/c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md index b79fab17f7..9c9b491590 100644 --- a/docs/c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md +++ b/docs/c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md @@ -3,14 +3,14 @@ title: "lrint, lrintf, lrintl, llrint, llrintf, llrintl" description: "API reference for lrint(), lrintf(), lrintl(), llrint(), llrintf(), and llrintl(); which rounds the specified floating-point value to the nearest integral value, by using the current rounding mode and direction." ms.date: "9/1/2020" api_name: ["lrint", "lrintl", "lrintf", "llrint", "llrintf", "llrintl", "_o_llrint", "_o_llrintf", "_o_llrintl", "_o_lrint", "_o_lrintf", "_o_lrintl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["lrint", "lrintf", "lrintl", "llrint", "llrintf", "llrintl", "math/lrint", "math/lrintf", "math/lrintl", "math/llrint", "math/llrintf", "math/llrintl"] helpviewer_keywords: ["lrint function", "lrintf function", "lrintl function", "llrint function", "llrintf function", "llrintl function"] ms.assetid: 28ccd5b3-5e6f-434f-997d-a21d51b8ce7f --- -# lrint, lrintf, lrintl, llrint, llrintf, llrintl +# `lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl` Rounds the specified floating-point value to the nearest integral value, by using the current rounding mode and direction. @@ -62,38 +62,38 @@ long long int llrintl( ### Parameters -*x*\ +*`x`*\ The value to round. -## Return Value +## Return value -If successful, returns the rounded integral value of *x*. +If successful, returns the rounded integral value of *`x`*. -|Issue|Return| -|-----------|------------| -|*x* is outside the range of the return type

*x* = ±∞

*x* = NaN|Raises **FE_INVALID** and returns zero (0).| +| Issue | Return | +|---|---| +| *`x`* is outside the range of the return type

*`x`* = ±INF

*`x`* = NaN | Raises `FE_INVALID` and returns zero (0). | ## Remarks -Because C++ allows overloading, you can call overloads of **lrint** and **llrint** that take **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **lrint** and **llrint** always take a **`double`**. +Because C++ allows overloading, you can call overloads of **`lrint`** and **`llrint`** that take **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`lrint`** and **`llrint`** always take a **`double`**. -If you use the \ `llrint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `llrint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -If *x* does not represent the floating-point equivalent of an integral value, these functions raise **FE_INEXACT**. +If *`x`* doesn't represent the floating-point equivalent of an integral value, these functions raise `FE_INEXACT`. **Microsoft-specific**: When the result is outside the range of the return type, or when the parameter is a NaN or infinity, the return value is implementation defined. The Microsoft compiler returns a zero (0) value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**lrint**, **lrintf**, **lrintl**, **llrint**, **llrintf**, **llrintl**|\|\| -|**lrint** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`lrint`**, **`lrintf`**, **`lrintl`**, **`llrint`**, **`llrintf`**, **`llrintl`** | \ | \ | +| **`lrint`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md) +[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/lrotl-lrotr.md b/docs/c-runtime-library/reference/lrotl-lrotr.md index 5ecdeb9ab1..1cef2be703 100644 --- a/docs/c-runtime-library/reference/lrotl-lrotr.md +++ b/docs/c-runtime-library/reference/lrotl-lrotr.md @@ -10,9 +10,9 @@ f1_keywords: ["lrotr", "lrotl", "_lrotr", "_lrotl"] helpviewer_keywords: ["lrotl function", "bits", "_lrotr function", "lrotr function", "rotating bits", "_lrotl function", "bits, rotating"] ms.assetid: d42f295b-35f9-49d2-9ee4-c66896ffe68e --- -# _lrotl, _lrotr +# `_lrotl`, `_lrotr` -Rotates bits to the left (**_lrotl**) or right (**_lrotr**). +Rotates bits to the left (**`_lrotl`**) or right (**`_lrotr`**). ## Syntax @@ -23,27 +23,27 @@ unsigned long _lrotr( unsigned long value, int shift ); ### Parameters -*value*
+*`value`*\ Value to be rotated. -*shift*
-Number of bits to shift *value*. +*`shift`*\ +Number of bits to shift *`value`*. -## Return Value +## Return value Both functions return the rotated value. There's no error return. ## Remarks -The **_lrotl** and **_lrotr** functions rotate *value* by *shift* bits. **_lrotl** rotates the value left, toward more significant bits. **_lrotr** rotates the value right, toward less significant bits. Both functions wrap bits rotated off one end of *value* to the other end. +The **`_lrotl`** and **`_lrotr`** functions rotate *`value`* by *`shift`* bits. **`_lrotl`** rotates the value left, toward more significant bits. **`_lrotr`** rotates the value right, toward less significant bits. Both functions wrap bits rotated off one end of *`value`* to the other end. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lrotl**, **_lrotr**|\| +| Routine | Required header | +|---|---| +| **`_lrotl`**, **`_lrotr`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -71,5 +71,5 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_rotl, _rotl64, _rotr, _rotr64](rotl-rotl64-rotr-rotr64.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_rotl`, `_rotl64`, `_rotr`, `_rotr64`](rotl-rotl64-rotr-rotr64.md) diff --git a/docs/c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md b/docs/c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md index ceea5dedfe..4233c51110 100644 --- a/docs/c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md +++ b/docs/c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md @@ -3,14 +3,14 @@ title: "lround, lroundf, lroundl, llround, llroundf, llroundl" description: "API reference for lround, lroundf, lroundl, llround, llroundf, and llroundl; which rounds a floating-point value to the nearest integer." ms.date: "9/1/2020" api_name: ["llround", "llroundf", "llroundl", "lroundf", "lround", "lroundl", "_o_llround", "_o_llroundf", "_o_llroundl", "_o_lround", "_o_lroundf", "_o_lroundl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["lround", "lroundl", "llroundl", "llround", "lroundf", "llroundf"] helpviewer_keywords: ["lround function", "llroundl function", "llround function", "lroundf function", "llroundf function", "lroundl function"] ms.assetid: cfb88a35-54c6-469f-85af-f7d695dcfdd8 --- -# lround, lroundf, lroundl, llround, llroundf, llroundl +# `lround`, `lroundf`, `lroundl`, `llround`, `llroundf`, `llroundl` Rounds a floating-point value to the nearest integer. @@ -52,33 +52,33 @@ long long llroundl( ### Parameters -*x*\ +*`x`*\ The floating-point value to round. -## Return Value +## Return value -The **lround** and **llround** functions return the nearest **`long`** or **`long long`** integer to *x*. Halfway values are rounded away from zero, regardless of the setting of the floating-point rounding mode. There's no error return. +The **`lround`** and **`llround`** functions return the nearest **`long`** or **`long long`** integer to *`x`*. Halfway values are rounded away from zero, regardless of the setting of the floating-point rounding mode. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **QNAN**, **IND**|none|**_DOMAIN**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks -Because C++ allows overloading, you can call overloads of **lround** or **llround** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **lround** and **llround** always take and return a **`double`**. +Because C++ allows overloading, you can call **`lround`** or **`llround`** overloads that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`lround`** and **`llround`** always take and return a **`double`**. -If you use the \ `lround()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `lround()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**lround**, **lroundf**, **lroundl**, **llround**, **llroundf**, **llroundl**|\| -|**lround** macro | \ | +| Routine | Required header | +|---|---| +| **`lround`**, **`lroundf`**, **`lroundl`**, **`llround`**, **`llroundf`**, **`llroundl`** | \ | +| **`lround`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -118,11 +118,11 @@ lroundl(-3.500000) is -4 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[fmod, fmodf](fmod-fmodf.md)
-[lrint, lrintf, lrintl, llrint, llrintf, llrintl](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)
-[round, roundf, roundl](round-roundf-roundl.md)
-[nearbyint, nearbyintf, nearbyintl](nearbyint-nearbyintf-nearbyintl1.md)
-[rint, rintf, rintl](rint-rintf-rintl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl`](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md)\ +[`nearbyint`, `nearbyintf`, `nearbyintl`](nearbyint-nearbyintf-nearbyintl1.md)\ +[`rint`, `rintf`, `rintl`](rint-rintf-rintl.md) diff --git a/docs/c-runtime-library/reference/lsearch-s.md b/docs/c-runtime-library/reference/lsearch-s.md index ace108415c..2c640e31da 100644 --- a/docs/c-runtime-library/reference/lsearch-s.md +++ b/docs/c-runtime-library/reference/lsearch-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _lsearch_s" title: "_lsearch_s" ms.date: "4/2/2020" api_name: ["_lsearch_s", "_o__lsearch_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_lsearch_s", "lsearch_s"] helpviewer_keywords: ["linear searching", "values, searching for", "keys, finding in arrays", "arrays [CRT], searching", "searching, linear", "_lsearch_s function", "lsearch_s function"] ms.assetid: d2db0635-be7a-4799-8660-255f14450882 --- -# _lsearch_s +# `_lsearch_s` -Performs a linear search for a value. A version of [_lsearch](lsearch.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Performs a linear search for a value. A version of [`_lsearch`](lsearch.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -29,60 +29,60 @@ void *_lsearch_s( ### Parameters -*key*
+*`key`*\ Object to search for. -*base*
+*`base`*\ Pointer to the base of array to be searched. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Size of each array element in bytes. -*compare*
+*`compare`*\ Pointer to the comparison routine. The second parameter is a pointer to the key for search. The third parameter is a pointer to an array element to be compared with the key. -*context*
+*`context`*\ A pointer to an object that might be accessed in the comparison function. -## Return Value +## Return value -If *key* is found, **_lsearch_s** returns a pointer to the element of the array at *base* that matches *key*. If *key* is not found, **_lsearch_s** returns a pointer to the newly added item at the end of the array. +If *`key`* is found, **`_lsearch_s`** returns a pointer to the element of the array at *`base`* that matches *`key`*. If *`key`* isn't found, **`_lsearch_s`** returns a pointer to the newly added item at the end of the array. -If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, then **errno** is set to **EINVAL** and the function returns **NULL**. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, then `errno` is set to `EINVAL` and the function returns `NULL`. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Error Conditions +### Error conditions -|*key*|*base*|*compare*|*number*|*size*|**errno**| -|-----------|------------|---------------|-----------|------------|-------------| -|**NULL**|any|any|any|any|**EINVAL**| -|any|**NULL**|any|!= 0|any|**EINVAL**| -|any|any|any|any|zero|**EINVAL**| -|any|any|**NULL**|an|any|**EINVAL**| +| *`key`* | *`base`* | *`compare`* | *`number`* | *`size`* | `errno` | +|---|---|---|---|---|---| +| `NULL` | any | any | any | any | `EINVAL` | +| any | `NULL` | any | != 0 | any | `EINVAL` | +| any | any | any | any | zero | `EINVAL` | +| any | any | `NULL` | an | any | `EINVAL` | ## Remarks -The **_lsearch_s** function performs a linear search for the value *key* in an array of *number* elements, each of *width* bytes. Unlike **bsearch_s**, **_lsearch_s** does not require the array to be sorted. If *key* is not found, then **_lsearch_s** adds it to the end of the array and increments *number*. +The **`_lsearch_s`** function performs a linear search for the value *`key`* in an array of *`number`* elements, each of *`size`* bytes. Unlike `bsearch_s`, **`_lsearch_s`** doesn't require the array to be sorted. If *`key`* isn't found, then **`_lsearch_s`** adds it to the end of the array and increments *`number`*. -The *compare* function is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. The *compare* function also takes the pointer to the context as the first argument. **_lsearch_s** calls *compare* one or more times during the search, passing pointers to two array elements on each call. *compare* must compare the elements and then return either nonzero (meaning the elements are different) or 0 (meaning the elements are identical). +The *`compare`* function is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. The *`compare`* function also takes the pointer to the context as the first argument. **`_lsearch_s`** calls *`compare`* one or more times during the search, passing pointers to two array elements on each call. *`compare`* must compare the elements and then return either nonzero (meaning the elements are different) or 0 (meaning the elements are identical). -The *context* pointer can be useful if the searched data structure is part of an object and the *compare* function needs to access members of the object. For example, code in the *compare* function can cast the void pointer into the appropriate object type and access members of that object. The addition of the *context* pointer makes **_lsearch_s** more secure because additional context can be used to avoid reentrancy bugs associated with using static variables to make data available to the *compare* function. +The *`context`* pointer can be useful if the searched data structure is part of an object and the *`compare`* function needs to access members of the object. For example, code in the *`compare`* function can cast the void pointer into the appropriate object type and access members of that object. The addition of the *`context`* pointer makes **`_lsearch_s`** more secure because extra context can be used to avoid reentrancy bugs associated with using static variables to make data available to the *`compare`* function. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lsearch_s**|\| +| Routine | Required header | +|---|---| +| **`_lsearch_s`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[bsearch_s](bsearch-s.md)
-[_lfind_s](lfind-s.md)
-[_lsearch](lsearch.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`bsearch_s`](bsearch-s.md)\ +[`_lfind_s`](lfind-s.md)\ +[`_lsearch`](lsearch.md) diff --git a/docs/c-runtime-library/reference/lsearch.md b/docs/c-runtime-library/reference/lsearch.md index 77efb404dd..f54546f733 100644 --- a/docs/c-runtime-library/reference/lsearch.md +++ b/docs/c-runtime-library/reference/lsearch.md @@ -3,16 +3,16 @@ description: "Learn more about: _lsearch" title: "_lsearch" ms.date: "4/2/2020" api_name: ["_lsearch", "_o__lsearch"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_lsearch"] helpviewer_keywords: ["_lsearch function", "values, searching for", "keys, finding in arrays", "arrays [CRT], searching", "linear searches", "searching, linear", "lsearch function"] ms.assetid: 8200f608-159a-46f0-923b-1a37ee1af7e0 --- -# _lsearch +# `_lsearch` -Performs a linear search for a value; adds to end of list if not found. A more secure version of this function is available; see [_lsearch_s](lsearch-s.md). +Performs a linear search for a value; adds to end of list if not found. A more secure version of this function is available; see [`_lsearch_s`](lsearch-s.md). ## Syntax @@ -28,42 +28,42 @@ void *_lsearch( ### Parameters -*key*
+*`key`*\ Object to search for. -*base*
+*`base`*\ Pointer to the base of array to be searched. -*number*
+*`number`*\ Number of elements. -*width*
+*`width`*\ Width of each array element. -*compare*
+*`compare`*\ Pointer to the comparison routine. The first parameter is a pointer to the key for search. The second parameter is a pointer to an array element to be compared with the key. -## Return Value +## Return value -If the key is found, **_lsearch** returns a pointer to the element of the array at *base* that matches *key*. If the key is not found, **_lsearch** returns a pointer to the newly added item at the end of the array. +If the key is found, **`_lsearch`** returns a pointer to the element of the array at *`base`* that matches *`key`*. If the key isn't found, **`_lsearch`** returns a pointer to the newly added item at the end of the array. ## Remarks -The **_lsearch** function performs a linear search for the value *key* in an array of *number* elements, each of *width* bytes. Unlike **bsearch**, **_lsearch** does not require the array to be sorted. If *key* is not found, **_lsearch** adds it to the end of the array and increments *number*. +The **`_lsearch`** function performs a linear search for the value *`key`* in an array of *`number`* elements, each of *`width`* bytes. Unlike **`bsearch`**, **`_lsearch`** doesn't require the array to be sorted. If *`key`* isn't found, **`_lsearch`** adds it to the end of the array and increments *`number`*. -The *compare* argument is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **_lsearch** calls the *compare* routine one or more times during the search, passing pointers to two array elements on each call. *compare* must compare the elements and return either nonzero (meaning the elements are different) or 0 (meaning the elements are identical). +The *`compare`* argument is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **`_lsearch`** calls the *`compare`* routine one or more times during the search, passing pointers to two array elements on each call. *`compare`* must compare the elements and return either nonzero (meaning the elements are different) or 0 (meaning the elements are identical). -This function validates its parameters. If *compare*, *key* or *number* is **NULL**, or if *base* is **NULL** and *number* is nonzero, or if *width* is less than zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. +This function validates its parameters. If *`compare`*, *`key`* or *`number`* is `NULL`, or if *`base`* is `NULL` and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lsearch**|\| +| Routine | Required header | +|---|---| +| **`_lsearch`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -109,7 +109,7 @@ wordlist after _lsearch: hello thanks bye extra ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[bsearch](bsearch.md)
-[_lfind](lfind.md)
-[_lsearch_s](lsearch-s.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`bsearch`](bsearch.md)\ +[`_lfind`](lfind.md)\ +[`_lsearch_s`](lsearch-s.md) diff --git a/docs/c-runtime-library/reference/lseek-lseeki64.md b/docs/c-runtime-library/reference/lseek-lseeki64.md index 5a5bf13a54..ee4015926d 100644 --- a/docs/c-runtime-library/reference/lseek-lseeki64.md +++ b/docs/c-runtime-library/reference/lseek-lseeki64.md @@ -3,14 +3,14 @@ description: "Learn more about: _lseek, _lseeki64" title: "_lseek, _lseeki64" ms.date: "4/2/2020" api_name: ["_lseeki64", "_lseek", "_o__lseek", "_o__lseeki64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_lseeki64", "_lseek", "lseeki64"] helpviewer_keywords: ["lseek function", "_lseek function", "_lseeki64 function", "lseeki64 function", "file pointers [C++], moving", "seek file pointers"] ms.assetid: aba8a768-d40e-48c3-b38e-473dbd782f93 --- -# _lseek, _lseeki64 +# `_lseek`, `_lseeki64` Moves a file pointer to the specified location. @@ -31,47 +31,47 @@ __int64 _lseeki64( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to an open file. -*offset*
-Number of bytes from *origin*. +*`offset`*\ +Number of bytes from *`origin`*. -*origin*
+*`origin`*\ Initial position. -## Return Value +## Return value -**_lseek** returns the offset, in bytes, of the new position from the beginning of the file. **_lseeki64** returns the offset in a 64-bit integer. The function returns -1L to indicate an error. If passed an invalid parameter, such as a bad file descriptor, or the value for *origin* is invalid or the position specified by *offset* is before the beginning of the file, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EBADF** and return -1L. On devices incapable of seeking (such as terminals and printers), the return value is undefined. +**`_lseek`** returns the offset, in bytes, of the new position from the beginning of the file. **`_lseeki64`** returns the offset in a 64-bit integer. The function returns -1L to indicate an error. If passed an invalid parameter, such as a bad file descriptor, or the value for *`origin`* is invalid or the position specified by *`offset`* is before the beginning of the file, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EBADF` and return -1L. On devices incapable of seeking (such as terminals and printers), the return value is undefined. -For more information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_lseek** function moves the file pointer associated with *fd* to a new location that is *offset* bytes from *origin*. The next operation on the file occurs at the new location. The *origin* argument must be one of the following constants, which are defined in Stdio.h. +The **`_lseek`** function moves the file pointer associated with *`fd`* to a new location that is *`offset`* bytes from *`origin`*. The next operation on the file occurs at the new location. The *`origin`* argument must be one of the following constants, which are defined in Stdio.h. -|*origin* value| Description | -|-|-| -| **SEEK_SET** | Beginning of the file. | -| **SEEK_CUR** | Current position of the file pointer. | -| **SEEK_END** | End of file. | +| *`origin`* value | Description | +|---|---| +| `SEEK_SET` | Beginning of the file. | +| `SEEK_CUR` | Current position of the file pointer. | +| `SEEK_END` | End of file. | -You can use **_lseek** to reposition the pointer anywhere in a file or beyond the end of the file. +You can use **`_lseek`** to reposition the pointer anywhere in a file or beyond the end of the file. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_lseek**|\| -|**_lseeki64**|\| +| Routine | Required header | +|---|---| +| **`_lseek`** | \ | +| **`_lseeki64`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -145,6 +145,6 @@ Position for end of file seek = 57 ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[fseek, _fseeki64](fseek-fseeki64.md)
-[_tell, _telli64](tell-telli64.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`fseek`, `_fseeki64`](fseek-fseeki64.md)\ +[`_tell`, `_telli64`](tell-telli64.md) diff --git a/docs/c-runtime-library/reference/lseek.md b/docs/c-runtime-library/reference/lseek.md index 9054789dda..2f3681358d 100644 --- a/docs/c-runtime-library/reference/lseek.md +++ b/docs/c-runtime-library/reference/lseek.md @@ -10,8 +10,8 @@ f1_keywords: ["lseek"] helpviewer_keywords: ["lseek function"] ms.assetid: 137d7741-5c2e-443e-811a-6a01417fcae7 --- -# lseek +# `lseek` -The Microsoft-implemented POSIX function name `lseek` is a deprecated alias for the [_lseek](lseek-lseeki64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `lseek` is a deprecated alias for the [`_lseek`](lseek-lseeki64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_lseek](lseek-lseeki64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_lseek`](lseek-lseeki64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md b/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md index 440f6d3470..58f567f5be 100644 --- a/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md +++ b/docs/c-runtime-library/reference/makepath-s-wmakepath-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _makepath_s, _wmakepath_s" title: "_makepath_s, _wmakepath_s" ms.date: "4/2/2020" api_name: ["_wmakepath_s", "_makepath_s", "_o__makepath_s", "_o__wmakepath_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wmakepath_s", "makepath_s", "_makepath_s", "wmakepath_s"] helpviewer_keywords: ["_makepath_s function", "wmakepath_s function", "paths", "_wmakepath_s function", "makepath_s function"] ms.assetid: 4405e43c-3d63-4697-bb80-9b8dcd21d027 --- -# _makepath_s, _wmakepath_s +# `_makepath_s`, `_wmakepath_s` -Creates a path name from components. These are versions of [_makepath, _wmakepath](makepath-wmakepath.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates a path name from components. These functions are versions of [`_makepath`, `_wmakepath`](makepath-wmakepath.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -53,68 +53,68 @@ errno_t _wmakepath_s( ### Parameters -*path*
+*`path`*\ Full path buffer. -*sizeInWords*
+*`sizeInWords`*\ Size of the buffer in words. -*sizeInBytes*
+*`sizeInBytes`*\ Size of the buffer in bytes. -*drive*
-Contains a letter (A, B, and so on) corresponding to the desired drive and an optional trailing colon. **_makepath_s** inserts the colon automatically in the composite path if it is missing. If *drive* is **NULL** or points to an empty string, no drive letter appears in the composite *path* string. +*`drive`*\ +Contains a letter (A, B, and so on) corresponding to the desired drive and an optional trailing colon. **`_makepath_s`** inserts the colon automatically in the composite path if it's missing. If *`drive`* is `NULL` or points to an empty string, no drive letter appears in the composite *`path`* string. -*dir*
-Contains the path of directories, not including the drive designator or the actual file name. The trailing slash is optional, and either a forward slash (/) or a backslash (\\) or both might be used in a single *dir* argument. If no trailing slash (/ or \\) is specified, it is inserted automatically. If *dir* is **NULL** or points to an empty string, no directory path is inserted in the composite *path* string. +*`dir`*\ +Contains the path of directories, not including the drive designator or the actual file name. The trailing slash is optional, and either a forward slash (/) or a backslash (\\) or both might be used in a single *`dir`* argument. If no trailing slash (/ or \\) is specified, it's inserted automatically. If *`dir`* is `NULL` or points to an empty string, no directory path is inserted in the composite *`path`* string. -*fname*
-Contains the base file name without any file name extensions. If *fname* is **NULL** or points to an empty string, no filename is inserted in the composite *path* string. +*`fname`*\ +Contains the base file name without any file name extensions. If *`fname`* is `NULL` or points to an empty string, no filename is inserted in the composite *`path`* string. -*ext*
-Contains the actual file name extension, with or without a leading period (.). **_makepath_s** inserts the period automatically if it does not appear in *ext*. If *ext* is **NULL** or points to an empty string, no extension is inserted in the composite *path* string. +*`ext`*\ +Contains the actual file name extension, with or without a leading period (.). **`_makepath_s`** inserts the period automatically if it doesn't appear in *`ext`*. If *`ext`* is `NULL` or points to an empty string, no extension is inserted in the composite *`path`* string. -## Return Value +## Return value Zero if successful; an error code on failure. -### Error Conditions +### Error conditions -|*path*|*sizeInWords* / *sizeInBytes*|Return|Contents of *path*| -|------------|------------------------------------|------------|------------------------| -|**NULL**|any|**EINVAL**|not modified| -|any|<= 0|**EINVAL**|not modified| +| *`path`* | *`sizeInWords`* / *`sizeInBytes`* | Return | Contents of *`path`* | +|---|---|---|---| +| `NULL` | any | `EINVAL` | not modified | +| any | <= 0 | `EINVAL` | not modified | -If any of the above error conditions occurs, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the functions returns **EINVAL**. **NULL** is allowed for the parameters *drive*, *fname*, and *ext*. For information about the behavior when these parameters are null pointers or empty strings, see the Remarks section. +If any of the above error conditions occurs, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the functions returns `EINVAL`. `NULL` is allowed for the parameters *`drive`*, *`fname`*, and *`ext`*. For information about the behavior when these parameters are null pointers or empty strings, see the Remarks section. ## Remarks -The **_makepath_s** function creates a composite path string from individual components, storing the result in *path*. The *path* might include a drive letter, directory path, file name, and file name extension. **_wmakepath_s** is a wide-character version of **_makepath_s**; the arguments to **_wmakepath_s** are wide-character strings. **_wmakepath_s** and **_makepath_s** behave identically otherwise. +The **`_makepath_s`** function creates a composite path string from individual components, storing the result in *`path`*. The *`path`* might include a drive letter, directory path, file name, and file name extension. **`_wmakepath_s`** is a wide-character version of **`_makepath_s`**; the arguments to **`_wmakepath_s`** are wide-character strings. **`_wmakepath_s`** and **`_makepath_s`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmakepath_s**|**_makepath_s**|**_makepath_s**|**_wmakepath_s**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tmakepath_s` | **`_makepath_s`** | **`_makepath_s`** | **`_wmakepath_s`** | -The *path* argument must point to an empty buffer large enough to hold the complete path. The composite *path* must be no larger than the **_MAX_PATH** constant, defined in Stdlib.h. +The *`path`* argument must point to an empty buffer large enough to hold the complete path. The composite *`path`* must be no larger than the `_MAX_PATH` constant, defined in Stdlib.h. -If path is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). In addition, **errno** is set to **EINVAL**. **NULL** values are allowed for all other parameters. +If path is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). In addition, `errno` is set to `EINVAL`. `NULL` values are allowed for all other parameters. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_makepath_s**|\| -|**_wmakepath_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_makepath_s`** | \ | +| **`_wmakepath_s`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -168,7 +168,7 @@ Path extracted with _splitpath_s: ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_fullpath, _wfullpath](fullpath-wfullpath.md)
-[_splitpath_s, _wsplitpath_s](splitpath-s-wsplitpath-s.md)
-[_makepath, _wmakepath](makepath-wmakepath.md)
+[File handling](../file-handling.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md)\ +[`_makepath`, `_wmakepath`](makepath-wmakepath.md) diff --git a/docs/c-runtime-library/reference/makepath-wmakepath.md b/docs/c-runtime-library/reference/makepath-wmakepath.md index f760d370ac..131f189359 100644 --- a/docs/c-runtime-library/reference/makepath-wmakepath.md +++ b/docs/c-runtime-library/reference/makepath-wmakepath.md @@ -3,16 +3,16 @@ description: "Learn more about: _makepath, _wmakepath" title: "_makepath, _wmakepath" ms.date: "4/2/2020" api_name: ["_makepath", "_wmakepath", "_o__makepath", "_o__wmakepath"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wmakepath", "_tmakepath", "makepath", "tmakepath", "wmakepath", "_makepath"] helpviewer_keywords: ["_makepath function", "wmakepath function", "makepath function", "_tmakepath function", "paths", "_wmakepath function", "tmakepath function"] ms.assetid: 5930b197-a7b8-46eb-8519-2841a58cd026 --- -# _makepath, _wmakepath +# `_makepath`, `_wmakepath` -Create a path name from components. More secure versions of these functions are available; see [_makepath_s, _wmakepath_s](makepath-s-wmakepath-s.md). +Create a path name from components. More secure versions of these functions are available; see [`_makepath_s`, `_wmakepath_s`](makepath-s-wmakepath-s.md). ## Syntax @@ -35,47 +35,47 @@ void _wmakepath( ### Parameters -*path*
+*`path`*\ Full path buffer. -*drive*
-Contains a letter (A, B, and so on) corresponding to the desired drive and an optional trailing colon. **_makepath** inserts the colon automatically in the composite path if it is missing. If *drive* is **NULL** or points to an empty string, no drive letter appears in the composite *path* string. +*`drive`*\ +Contains a letter (A, B, and so on) corresponding to the desired drive and an optional trailing colon. **`_makepath`** inserts the colon automatically in the composite path if it's missing. If *`drive`* is `NULL` or points to an empty string, no drive letter appears in the composite *`path`* string. -*dir*
-Contains the path of directories, not including the drive designator or the actual file name. The trailing slash is optional, and either a forward slash (/) or a backslash (\\) or both might be used in a single *dir* argument. If no trailing slash (/ or \\) is specified, it is inserted automatically. If *dir* is **NULL** or points to an empty string, no directory path is inserted in the composite *path* string. +*`dir`*\ +Contains the path of directories, not including the drive designator or the actual file name. The trailing slash is optional, and either a forward slash (**`/`**) or a backslash (**`\`**) or both might be used in a single *`dir`* argument. If no trailing slash (**`/`** or **`\`**) is specified, it's inserted automatically. If *`dir`* is `NULL` or points to an empty string, no directory path is inserted in the composite *`path`* string. -*fname*
-Contains the base file name without any file name extensions. If *fname* is **NULL** or points to an empty string, no filename is inserted in the composite *path* string. +*`fname`*\ +Contains the base file name without any file name extensions. If *`fname`* is `NULL` or points to an empty string, no filename is inserted in the composite *`path`* string. -*ext*
-Contains the actual file name extension, with or without a leading period (.). **_makepath** inserts the period automatically if it does not appear in *ext*. If *ext* is **NULL** or points to an empty string, no extension is inserted in the composite *path* string. +*`ext`*\ +Contains the actual file name extension, with or without a leading period (**`.`**). **`_makepath`** inserts the period automatically if it doesn't appear in *`ext`*. If *`ext`* is `NULL` or points to an empty string, no extension is inserted in the composite *`path`* string. ## Remarks -The **_makepath** function creates a composite path string from individual components, storing the result in *path*. The *path* might include a drive letter, directory path, filename, and filename extension. **_wmakepath** is a wide-character version of **_makepath**; the arguments to **_wmakepath** are wide-character strings. **_wmakepath** and **_makepath** behave identically otherwise. +The **`_makepath`** function creates a composite path string from individual components, storing the result in *`path`*. The *`path`* might include a drive letter, directory path, filename, and filename extension. **`_wmakepath`** is a wide-character version of **`_makepath`**; the arguments to **`_wmakepath`** are wide-character strings. **`_wmakepath`** and **`_makepath`** behave identically otherwise. -**Security Note** Use a null-terminated string. To avoid buffer overrun, the null-terminated string must not exceed the size of the *path* buffer. **_makepath** does not ensure that the length of the composite path string does not exceed **_MAX_PATH**. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** Use a null-terminated string. To avoid buffer overrun, the null-terminated string must not exceed the size of the *`path`* buffer. **`_makepath`** doesn't ensure that the length of the composite path string doesn't exceed `_MAX_PATH`. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmakepath**|**_makepath**|**_makepath**|**_wmakepath**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tmakepath` | **`_makepath`** | **`_makepath`** | **`_wmakepath`** | -The *path* argument must point to an empty buffer large enough to hold the complete path. The composite *path* must be no larger than the **_MAX_PATH** constant, defined in Stdlib.h. +The *`path`* argument must point to an empty buffer large enough to hold the complete path. The composite *`path`* must be no larger than the `_MAX_PATH` constant, defined in Stdlib.h. -If path is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). In addition, **errno** is set to **EINVAL**. **NULL** values are allowed for all other parameters. +If path is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). In addition, `errno` is set to `EINVAL`. `NULL` values are allowed for all other parameters. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_makepath**|\| -|**_wmakepath**|\ or \| +| Routine | Required header | +|---|---| +| **`_makepath`** | \ | +| **`_wmakepath`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -117,7 +117,7 @@ Path extracted with _splitpath: ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_fullpath, _wfullpath](fullpath-wfullpath.md)
-[_splitpath, _wsplitpath](splitpath-wsplitpath.md)
-[_makepath_s, _wmakepath_s](makepath-s-wmakepath-s.md)
+[File handling](../file-handling.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md)\ +[`_makepath_s`, `_wmakepath_s`](makepath-s-wmakepath-s.md) diff --git a/docs/c-runtime-library/reference/malloc-dbg.md b/docs/c-runtime-library/reference/malloc-dbg.md index c1247cac4d..9de32b3c52 100644 --- a/docs/c-runtime-library/reference/malloc-dbg.md +++ b/docs/c-runtime-library/reference/malloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["malloc_dbg", "_malloc_dbg"] helpviewer_keywords: ["malloc_dbg function", "memory allocation", "_malloc_dbg function"] ms.assetid: c97eca51-140b-4461-8bd2-28965b49ecdb --- -# _malloc_dbg +# `_malloc_dbg` -Allocates a block of memory in the heap with additional space for a debugging header and overwrite buffers (debug version only). +Allocates a block of memory in the heap with extra space for a debugging header and overwrite buffers (debug version only). ## Syntax @@ -27,52 +27,52 @@ void *_malloc_dbg( ### Parameters -*size*
+*`size`*\ Requested size of the memory block (in bytes). -*blockType*
-Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested the allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_malloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_malloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function returns a pointer to the user portion of the allocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [malloc](malloc.md) function. +On successful completion, this function returns a pointer to the user portion of the allocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [`malloc`](malloc.md) function. ## Remarks -**_malloc_dbg** is a debug version of the [malloc](malloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_malloc_dbg** is reduced to a call to **malloc**. Both **malloc** and **_malloc_dbg** allocate a block of memory in the base heap, but **_malloc_dbg** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +**`_malloc_dbg`** is a debug version of the [`malloc`](malloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_malloc_dbg`** is reduced to a call to `malloc`. Both `malloc` and **`_malloc_dbg`** allocate a block of memory in the base heap, but **`_malloc_dbg`** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_malloc_dbg** allocates the memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_malloc_dbg`** allocates the memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_malloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_malloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_malloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_malloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -For a sample of how to use **_malloc_dbg**, see [crt_dbg1](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). +For a sample of how to use **`_malloc_dbg`**, see [`crt_dbg1`](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt/crt_dbg1). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[malloc](malloc.md)
-[_calloc_dbg](calloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`malloc`](malloc.md)\ +[`_calloc_dbg`](calloc-dbg.md) diff --git a/docs/c-runtime-library/reference/malloc.md b/docs/c-runtime-library/reference/malloc.md index e24a158cd7..959948becb 100644 --- a/docs/c-runtime-library/reference/malloc.md +++ b/docs/c-runtime-library/reference/malloc.md @@ -3,7 +3,7 @@ description: "Learn more about: malloc" title: "malloc" ms.date: "4/2/2020" api_name: ["malloc", "_o_malloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["malloc"] @@ -24,25 +24,25 @@ void *malloc( ### Parameters -*`size`*
+*`size`*\ Bytes to allocate. -## Return Value +## Return value -**`malloc`** returns a void pointer to the allocated space, or **`NULL`** if there is insufficient memory available. To return a pointer to a type other than **`void`**, use a type cast on the return value. The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object that has an alignment requirement less than or equal to that of the fundamental alignment. (In Visual C++, the fundamental alignment is the alignment that's required for a **`double`**, or 8 bytes. In code that targets 64-bit platforms, it’s 16 bytes.) Use [`_aligned_malloc`](aligned-malloc.md) to allocate storage for objects that have a larger alignment requirement—for example, the SSE types [`__m128`](../../cpp/m128.md) and **`__m256`**, and types that are declared by using `__declspec(align( n ))` where **`n`** is greater than 8. If *`size`* is 0, **`malloc`** allocates a zero-length item in the heap and returns a valid pointer to that item. Always check the return from **`malloc`**, even if the amount of memory requested is small. +**`malloc`** returns a void pointer to the allocated space, or `NULL` if there's insufficient memory available. To return a pointer to a type other than **`void`**, use a type cast on the return value. The storage space pointed to by the return value is suitably aligned for storage of any type of object that has an alignment requirement less than or equal to that of the fundamental alignment. (In Visual C++, the fundamental alignment is the alignment that's required for a **`double`**, or 8 bytes. In code that targets 64-bit platforms, it's 16 bytes.) Use [`_aligned_malloc`](aligned-malloc.md) to allocate storage for objects that have a larger alignment requirement—for example, the SSE types [`__m128`](../../cpp/m128.md) and **`__m256`**, and types that are declared by using `__declspec(align( n ))` where **`n`** is greater than 8. If *`size`* is 0, **`malloc`** allocates a zero-length item in the heap and returns a valid pointer to that item. Always check the return from **`malloc`**, even if the amount of memory requested is small. ## Remarks The **`malloc`** function allocates a memory block of at least *`size`* bytes. The block may be larger than *`size`* bytes because of the space that's required for alignment and maintenance information. -**`malloc`** sets **`errno`** to **`ENOMEM`** if a memory allocation fails or if the amount of memory requested exceeds **`_HEAP_MAXREQ`**. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`malloc`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). The startup code uses **`malloc`** to allocate storage for the **`_environ`**, *`envp`*, and *`argv`* variables. The following functions and their wide-character counterparts also call **`malloc`**. :::row::: :::column span=""::: [`calloc`](calloc.md)\ - [`_exec` functions](../../c-runtime-library/exec-wexec-functions.md)\ + [`_exec` functions](../exec-wexec-functions.md)\ [`fgetc`](fgetc-fgetwc.md)\ [`_fgetchar`](fgetc-fgetwc.md)\ [`fgets`](fgets-fgetws.md)\ @@ -62,7 +62,7 @@ The startup code uses **`malloc`** to allocate storage for the **`_environ`**, * [`getchar`](getc-getwc.md)\ [`_getcwd`](getcwd-wgetcwd.md)\ [`_getdcwd`](getcwd-wgetcwd.md)\ - [`gets`](../../c-runtime-library/gets-getws.md) + [`gets`](../gets-getws.md) :::column-end::: :::column span=""::: [`_getw`](getw.md)\ @@ -78,7 +78,7 @@ The startup code uses **`malloc`** to allocate storage for the **`_environ`**, * :::column span=""::: [`_searchenv`](searchenv-wsearchenv.md)\ [`setvbuf`](setvbuf.md)\ - [`_spawn` functions](../../c-runtime-library/spawn-wspawn-functions.md)\ + [`_spawn` functions](../spawn-wspawn-functions.md)\ [`_strdup`](strdup-wcsdup-mbsdup.md)\ [`system`](system-wsystem.md)\ [`_tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ @@ -88,25 +88,25 @@ The startup code uses **`malloc`** to allocate storage for the **`_environ`**, * :::column-end::: :::row-end::: -The C++ [`_set_new_mode`](set-new-mode.md) function sets the new handler mode for **`malloc`**. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`malloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call `_set_new_mode(1)` early in your program, or link with `NEWMODE.OBJ` (see [Link Options](../../c-runtime-library/link-options.md)). +The C++ [`_set_new_mode`](set-new-mode.md) function sets the new handler mode for **`malloc`**. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`malloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call `_set_new_mode(1)` early in your program, or link with `NEWMODE.OBJ` (see [Link options](../link-options.md)). -When the application is linked with a debug version of the C run-time libraries, **`malloc`** resolves to [`_malloc_dbg`](malloc-dbg.md). For more information about how the heap is managed during the debugging process, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`malloc`** resolves to [`_malloc_dbg`](malloc-dbg.md). For more information about how the heap is managed during the debugging process, see [CRT debug heap details](../crt-debug-heap-details.md). -**`malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`; this means that the function is guaranteed not to modify global variables, and that the pointer returned is not aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). +**`malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`. These attributes mean that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`malloc`**|`` and ``| +| Routine | Required header | +|---|---| +| **`malloc`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -147,8 +147,8 @@ Memory freed ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[`calloc`](calloc.md)
-[`free`](free.md)
-[`realloc`](realloc.md)
-[`_aligned_malloc`](aligned-malloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`realloc`](realloc.md)\ +[`_aligned_malloc`](aligned-malloc.md) diff --git a/docs/c-runtime-library/reference/malloca.md b/docs/c-runtime-library/reference/malloca.md index fda73f4a37..56b67ffeb9 100644 --- a/docs/c-runtime-library/reference/malloca.md +++ b/docs/c-runtime-library/reference/malloca.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _malloca" title: "_malloca" -ms.date: "11/04/2016" +description: "Learn more about: _malloca" +ms.date: 11/04/2016 api_name: ["_malloca"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["malloca", "_malloca"] helpviewer_keywords: ["memory allocation, stack", "malloca function", "_malloca function"] -ms.assetid: 293992df-cfca-4bc9-b313-0a733a6bb936 --- -# _malloca +# `_malloca` -Allocates memory on the stack. This is a version of [_alloca](alloca.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Allocates memory on the stack. This function is a version of [`_alloca`](alloca.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,41 +23,41 @@ void *_malloca( ### Parameters -*size*
+*`size`*\ Bytes to be allocated from the stack. -## Return Value +## Return value -The **_malloca** routine returns a **`void`** pointer to the allocated space, which is guaranteed to be suitably aligned for storage of any type of object. If *size* is 0, **_malloca** allocates a zero-length item and returns a valid pointer to that item. +The **`_malloca`** routine returns a **`void`** pointer to the allocated space, which is suitably aligned for storage of any type of object. If *`size`* is 0, **`_malloca`** allocates a zero-length item and returns a valid pointer to that item. -If *size* is greater than **_ALLOCA_S_THRESHOLD**, then **_malloca** attempts to allocate on the heap, and returns a null pointer if the space can't be allocated. If *size* is less than or equal to **_ALLOCA_S_THRESHOLD**, then **_malloca** attempts to allocate on the stack, and a stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured Exception Handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH) to catch this exception. +If *`size`* is greater than `_ALLOCA_S_THRESHOLD`, then **`_malloca`** attempts to allocate on the heap, and returns a null pointer if the space can't be allocated. If *`size`* is less than or equal to `_ALLOCA_S_THRESHOLD`, then **`_malloca`** attempts to allocate on the stack, and a stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH) to catch this exception. ## Remarks -**_malloca** allocates *size* bytes from the program stack or the heap if the request exceeds a certain size in bytes given by **_ALLOCA_S_THRESHOLD**. The difference between **_malloca** and **_alloca** is that **_alloca** always allocates on the stack, regardless of the size. Unlike **_alloca**, which does not require or permit a call to **free** to free the memory so allocated, **_malloca** requires the use of [_freea](freea.md) to free memory. In debug mode, **_malloca** always allocates memory from the heap. +**`_malloca`** allocates *`size`* bytes from the program stack or the heap if the request exceeds a certain size in bytes given by `_ALLOCA_S_THRESHOLD`. The difference between **`_malloca`** and **`_alloca`** is that **`_alloca`** always allocates on the stack, regardless of the size. Unlike **`_alloca`**, which doesn't require or permit a call to **`free`** to free the memory so allocated, **`_malloca`** requires the use of [`_freea`](freea.md) to free memory. In debug mode, **`_malloca`** always allocates memory from the heap. -There are restrictions to explicitly calling **_malloca** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that is not based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows NT structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **_malloca** in any of the following scenarios results in program failure during the return to the calling EH routine: +There are restrictions to explicitly calling **`_malloca`** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that isn't based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows NT structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **`_malloca`** in any of the following scenarios results in program failure during the return to the calling EH routine: -- Windows NT SEH exception filter expression: **`__except`** (`_malloca ()` ) +- Windows SEH exception filter expression: **`__except`** (`_malloca ()`) -- Windows NT SEH final exception handler: **`__finally`** {`_malloca ()` } +- Windows SEH final exception handler: **`__finally`** {`_malloca ()` } - C++ EH catch clause expression -However, **_malloca** can be called directly from within an EH routine or from an application-supplied callback that gets invoked by one of the EH scenarios previously listed. +However, **`_malloca`** can be called directly from within an EH routine or from an application-supplied callback that gets invoked by one of the EH scenarios previously listed. > [!IMPORTANT] -> In Windows XP, if **_malloca** is called inside a try/catch block, you must call [_resetstkoflw](resetstkoflw.md) in the catch block. +> In Windows, if **`_malloca`** is called inside a `try/catch` block, you must call [`_resetstkoflw`](resetstkoflw.md) in the catch block. -In addition to the above restrictions, when using the [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option, **_malloca** cannot be used in **`__except`** blocks. For more information, see [/clr Restrictions](../../build/reference/clr-restrictions.md). +In addition to the above restrictions, when using the [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option, **`_malloca`** can't be used in **`__except`** blocks. For more information, see [`/clr` Restrictions](../../build/reference/clr-restrictions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_malloca**|\| +| Routine | Required header | +|---|---| +| **`_malloca`** | `` | -## Example: malloca +## Example: `_malloca` ```C // crt_malloca_simple.c @@ -78,7 +77,7 @@ int main() } ``` -## Example: malloca exception +## Example: `_malloca` exception ```C // crt_malloca_exception.c @@ -144,7 +143,7 @@ int main() 1000 ``` -### Sample Output +### Sample output ```Output Enter the number of bytes to allocate using _malloca: 1000 @@ -152,8 +151,8 @@ Enter the number of bytes to allocate using _malloca: 1000 ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[malloc](malloc.md)
-[realloc](realloc.md)
-[_resetstkoflw](resetstkoflw.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`malloc`](malloc.md)\ +[`realloc`](realloc.md)\ +[`_resetstkoflw`](resetstkoflw.md) diff --git a/docs/c-runtime-library/reference/matherr.md b/docs/c-runtime-library/reference/matherr.md index 45cbb55ca0..78e0ea89b4 100644 --- a/docs/c-runtime-library/reference/matherr.md +++ b/docs/c-runtime-library/reference/matherr.md @@ -1,43 +1,45 @@ --- description: "Learn more about: _matherr" title: "_matherr" -ms.date: "04/05/2018" +ms.date: "04/18/2012" api_name: ["_matherr"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_matherr", "matherr"] helpviewer_keywords: ["_matherr function", "matherr function"] -ms.assetid: b600d66e-165a-4608-a856-8fb418d46760 --- -# _matherr +# `_matherr` Handles math errors. ## Syntax ```C -int _matherr( struct _exception * except ); +int _matherr(struct _exception *except); ``` ### Parameters -*except*
+*`except`*\ Pointer to the structure containing error information. -## Return Value +## Return value -**_matherr** returns 0 to indicate an error, or a nonzero value to indicate success. If **_matherr** returns 0, an error message can be displayed and **errno** is set to an appropriate error value. If **_matherr** returns a nonzero value, no error message is displayed and **errno** remains unchanged. +**`_matherr`** returns 0 to indicate an error, or a nonzero value to indicate success: -For more information about return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +- If **`_matherr`** returns 0, an error message can be displayed and `errno` is set to an appropriate error value. +- If **`_matherr`** returns a nonzero value, no error message is displayed, and `errno` remains unchanged. + +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_matherr** function processes errors generated by the floating-point functions of the math library. These functions call **_matherr** when an error is detected. +The **`_matherr`** function processes errors generated by the floating-point functions of the math library. These functions call **`_matherr`** when an error is detected. This interaction isn't impacted by the [floating-point mode of the compiler](../../build/reference/fp-specify-floating-point-behavior.md) or the [floating point control word](./control87-controlfp-control87-2.md). Since **`_matherr`** is a library function, math [intrinsic functions](../../intrinsics/compiler-intrinsics.md) won't call it. -For special error handling, you can provide a different definition of **_matherr**. If you use the dynamically linked version of the C run-time library (CRT), you can replace the default **_matherr** routine in a client executable with a user-defined version. However, you cannot replace the default **_matherr** routine in a DLL client of the CRT DLL. +For special error handling, you can provide a different definition of **`_matherr`**. If you use the dynamically linked version of the C run-time library (CRT), you can replace the default **`_matherr`** routine in a client executable with a user-defined version. However, you can't replace the default **`_matherr`** routine in a DLL client of the CRT DLL. -When an error occurs in a math routine, **_matherr** is called with a pointer to an **_exception** type structure (defined in \) as an argument. The **_exception** structure contains the following elements. +When an error occurs in a math routine, **`_matherr`** is called with a pointer to an **`_exception`** type structure (defined in ``) as an argument. The **`_exception`** structure contains the following elements. ```C struct _exception @@ -50,36 +52,36 @@ struct _exception }; ``` -The **type** member specifies the type of math error. It is one of the following values, defined in \: +The **`type`** member specifies the type of math error. It's one of the following values, defined in ``: -|Macro|Meaning| -|-|-| -| **_DOMAIN** | Argument domain error | -| **_SING** | Argument singularity | -| **_OVERFLOW** | Overflow range error | -| **_PLOSS** | Partial loss of significance | -| **_TLOSS** | Total loss of significance | -| **_UNDERFLOW** | The result is too small to be represented. (This condition is not currently supported.) | +| Macro | Description | +|---|---| +| `_DOMAIN` | Argument domain error | +| `_SING` | Argument singularity | +| `_OVERFLOW` | Overflow range error | +| `_PLOSS` | Partial loss of significance | +| `_TLOSS` | Total loss of significance | +| `_UNDERFLOW` | The result is too small to be represented. (This condition isn't currently supported.) | -The structure member **name** is a pointer to a null-terminated string containing the name of the function that caused the error. The structure members **arg1** and **arg2** specify the values that caused the error. If only one argument is given, it is stored in **arg1**. +The structure member **`name`** is a pointer to a null-terminated string containing the name of the function that caused the error. The structure members **`arg1`** and **`arg2`** specify the values that caused the error. If only one argument is given, it's stored in **`arg1`**. -The default return value for the given error is **retval**. If you change the return value, it must specify whether an error actually occurred. +The default return value for the given error is **`retval`**. If you change the return value, it must specify whether an error actually occurred. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_matherr**|\| +| Routine | Required header | +|---|---| +| **`_matherr`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C -// crt_matherr.c -/* illustrates writing an error routine for math -* functions. The error function must be: -* _matherr +/* crt_matherr.c +* Illustrates writing an error routine for math +* functions. +* The error handling function must be named _matherr */ #include @@ -102,27 +104,27 @@ int main() * returns the natural or base-10 logarithm of the absolute value * of the argument and suppresses the usual error message. */ -int _matherr( struct _exception *except ) +int _matherr(struct _exception *except) { /* Handle _DOMAIN errors for log or log10. */ - if( except->type == _DOMAIN ) + if (except->type == _DOMAIN) { - if( strcmp( except->name, "log" ) == 0 ) + if (strcmp(except->name, "log") == 0) { - except->retval = log( -(except->arg1) ); - printf( "Special: using absolute value: %s: _DOMAIN " - "error\n", except->name ); + except->retval = log(-(except->arg1)); + printf("Special: using absolute value: %s: _DOMAIN " + "error\n", except->name); return 1; } - else if( strcmp( except->name, "log10" ) == 0 ) + else if (strcmp(except->name, "log10") == 0) { - except->retval = log10( -(except->arg1) ); - printf( "Special: using absolute value: %s: _DOMAIN " - "error\n", except->name ); + except->retval = log10(-(except->arg1)); + printf("Special: using absolute value: %s: _DOMAIN " + "error\n", except->name); return 1; } } - printf( "Normal: " ); + printf("Normal: "); return 0; /* Else use the default actions */ } ``` @@ -137,4 +139,4 @@ Normal: log( 0.0 ) = -inf ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
+[Math and floating-point support](../floating-point-support.md) diff --git a/docs/c-runtime-library/reference/max.md b/docs/c-runtime-library/reference/max.md index e5560931b2..c29fbe00f2 100644 --- a/docs/c-runtime-library/reference/max.md +++ b/docs/c-runtime-library/reference/max.md @@ -10,7 +10,7 @@ f1_keywords: ["max", "__max"] helpviewer_keywords: ["max macro", "maximum macro", "__max macro"] ms.assetid: 05c936f6-0e22-45d6-a58d-4bc102e9dae2 --- -# __max +# `__max` A preprocessor macro that returns the larger of two values. @@ -22,30 +22,30 @@ A preprocessor macro that returns the larger of two values. ### Parameters -*a*, *b*
+*`a`*, *`b`*\ Values of any numeric type to be compared. -## Return Value +## Return value -**__max** returns the larger of its arguments. +**`__max`** returns the larger of its arguments. ## Remarks -The **__max** macro compares two values and returns the value of the larger one. The arguments can be of any numeric data type, signed or unsigned. Both arguments and the return value must be of the same data type. +The **`__max`** macro compares two values and returns the value of the larger one. The arguments can be of any numeric data type, signed or unsigned. Both arguments and the return value must be of the same data type. -The argument returned is evaluated twice by the macro. This can lead to unexpected results if the argument is an expression that alters its value when it is evaluated, such as `*p++`. +The argument returned is evaluated twice by the macro. Double evaluation can lead to unexpected results if the argument is an expression that alters its value when it's evaluated, such as `*p++`. ## Requirements -|Macro|Required header| -|-------------|---------------------| -|**__max**|\| +| Macro | Required header | +|---|---| +| **`__max`** | \ | ## Example -For more information, see the example for [__min](min.md). +For more information, see the example for [`__min`](min.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[__min](min.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`__min`](min.md) diff --git a/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md b/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md index 2755bbed30..8d42683acf 100644 --- a/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md +++ b/docs/c-runtime-library/reference/mbbtombc-mbbtombc-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbbtombc, _mbbtombc_l" title: "_mbbtombc, _mbbtombc_l" ms.date: "4/2/2020" api_name: ["_mbbtombc_l", "_mbbtombc", "_o__mbbtombc", "_o__mbbtombc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbbtombc_l", "_mbbtombc", "mbbtombc_l", "mbbtombc"] helpviewer_keywords: ["mbbtombc_l function", "mbbtombc function", "_mbbtombc_l function", "_mbbtombc function"] ms.assetid: 78593389-b0fc-43b6-8c1f-2a6bf702d64e --- -# _mbbtombc, _mbbtombc_l +# `_mbbtombc`, `_mbbtombc_l` Converts a single-byte multibyte character to a corresponding double-byte multibyte character. @@ -31,36 +31,36 @@ unsigned int _mbbtombc_l( ### Parameters -*c*
+*`c`*\ Single-byte character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -If **_mbbtombc** successfully converts *c*, it returns a multibyte character; otherwise, it returns *c*. +If **`_mbbtombc`** successfully converts *`c`*, it returns a multibyte character; otherwise, it returns *`c`*. ## Remarks -The **_mbbtombc** function converts a given single-byte multibyte character to a corresponding double-byte multibyte character. Characters must be within the range 0x20 - 0x7E or 0xA1 - 0xDF to be converted. +The **`_mbbtombc`** function converts a given single-byte multibyte character to a corresponding double-byte multibyte character. Characters must be within the range 0x20 - 0x7E or 0xA1 - 0xDF to be converted. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of this function are identical, except that **_mbbtombc** uses the current locale for this locale-dependent behavior and **_mbbtombc_l** instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of this function are identical, except that **`_mbbtombc`** uses the current locale for this locale-dependent behavior and **`_mbbtombc_l`** instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -In earlier versions, **_mbbtombc** was named **hantozen**. For new code, use **_mbbtombc**. +In earlier versions, **`_mbbtombc`** was named `hantozen`. For new code, use **`_mbbtombc`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbbtombc**|\| -|**_mbbtombc_l**|\| +| Routine | Required header | +|---|---| +| **`_mbbtombc`** | \ | +| **`_mbbtombc_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[_mbctombb, _mbctombb_l](mbctombb-mbctombb-l.md)
+[Data conversion](../data-conversion.md)\ +[`_mbctombb`, `_mbctombb_l`](mbctombb-mbctombb-l.md) diff --git a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md index 39d1104bc2..d3e9461cbe 100644 --- a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md +++ b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbbtype, _mbbtype_l" title: "_mbbtype, _mbbtype_l" ms.date: "4/2/2020" api_name: ["_mbbtype", "_mbbtype_l", "_o__mbbtype", "_o__mbbtype_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbbtype_l", "mbbtype", "mbbtype_l", "_mbbtype"] helpviewer_keywords: ["_mbbtype function", "_mbbtype_l function", "mbbtype function", "mbbtype_l function"] ms.assetid: b8e34b40-842a-4298-aa39-0bd2d8e51c2a --- -# _mbbtype, _mbbtype_l +# `_mbbtype`, `_mbbtype_l` Returns the byte type, based on the previous byte. @@ -33,48 +33,48 @@ int _mbbtype_l( ### Parameters -*c*
+*`c`*\ The character to test. -*type*
+*`type`*\ The type of byte to test for. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_mbbtype** returns the type of byte in a string. This decision is context-sensitive, as specified by the value of *type*, which provides the control test condition. *type* is the type of the previous byte in the string. The manifest constants in the following table are defined in Mbctype.h. +**`_mbbtype`** returns the type of byte in a string. This decision is context-sensitive, as specified by the value of *`type`*, which provides the control test condition. *`type`* is the type of the previous byte in the string. The manifest constants in the following table are defined in Mbctype.h. -|Value of *type*|**_mbbtype** tests for|Return value|*c*| -|---------------------|--------------------------|------------------|---------| -|Any value except 1|Valid single byte or lead byte|**_MBC_SINGLE** (0)|Single byte (0x20 - 0x7E, 0xA1 - 0xDF)| -|Any value except 1|Valid single byte or lead byte|**_MBC_LEAD** (1)|Lead byte of multibyte character (0x81 - 0x9F, 0xE0 - 0xFC)| -|Any value except 1|Valid single-byte or lead byte|**_MBC_ILLEGAL**

( -1)|Invalid character (any value except 0x20 - 0x7E, 0xA1 - 0xDF, 0x81 - 0x9F, 0xE0 - 0xFC| -|1|Valid trail byte|**_MBC_TRAIL** (2)|Trailing byte of multibyte character (0x40 - 0x7E, 0x80 - 0xFC)| -|1|Valid trail byte|**_MBC_ILLEGAL**

( -1)|Invalid character (any value except 0x20 - 0x7E, 0xA1 - 0xDF, 0x81 - 0x9F, 0xE0 - 0xFC| +| Value of *`type`* | **`_mbbtype`** tests for | Return value | *`c`* | +|---|---|---|---| +| Any value except 1 | Valid single byte or lead byte | `_MBC_SINGLE` (0) | Single byte (0x20 - 0x7E, 0xA1 - 0xDF) | +| Any value except 1 | Valid single byte or lead byte | `_MBC_LEAD` (1) | Lead byte of multibyte character (0x81 - 0x9F, 0xE0 - 0xFC) | +| Any value except 1 | Valid single-byte or lead byte | `_MBC_ILLEGAL` (-1) | Invalid character: not single or lead (0x00 - 0x1F, 0x7F, 0x80, 0xA0, 0xFD, 0xFE, 0xFF) | +| 1 | Valid trail byte | `_MBC_TRAIL` (2) | Trailing byte of multibyte character (0x40 - 0x7E, 0x80 - 0xFC) | +| 1 | Valid trail byte | `_MBC_ILLEGAL` (-1) | Invalid character: not trailing (0x00 - 0x3F, 0x7F, 0xFD, 0xFE, 0xFF) | ## Remarks -The **_mbbtype** function determines the type of a byte in a multibyte character. If the value of *type* is any value except 1, **_mbbtype** tests for a valid single-byte or lead byte of a multibyte character. If the value of *type* is 1, **_mbbtype** tests for a valid trail byte of a multibyte character. +The **`_mbbtype`** function determines the type of a byte in a multibyte character. If the value of *`type`* is any value except 1, **`_mbbtype`** tests for a valid single-byte or lead byte of a multibyte character. If the value of *`type`* is 1, **`_mbbtype`** tests for a valid trail byte of a multibyte character. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The **_mbbtype** version of this function uses the current locale for this locale-dependent behavior; the **_mbbtype_l** version is identical except that it use the locale parameter that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The **`_mbbtype`** version of this function uses the current locale for this locale-dependent behavior; the **`_mbbtype_l`** version is identical except that it uses the locale parameter that's passed in instead. For more information, see [Locale](../locale.md). -In earlier versions, **_mbbtype** was named **chkctype**. For new code, use **_mbbtype** instead. +In earlier versions, **`_mbbtype`** was named `chkctype`. For new code, use **`_mbbtype`** instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_mbbtype**|\|\*| -|**_mbbtype_l**|\|\*| +| Routine | Required header | Optional header | +|---|---|---| +| **`_mbbtype`** | \ | \* | +| **`_mbbtype_l`** | \ | \* | \* For definitions of manifest constants that are used as return values. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
+[Byte classification](../byte-classification.md) diff --git a/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md b/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md index 2d4f79c12a..c5866e886e 100644 --- a/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md +++ b/docs/c-runtime-library/reference/mbccpy-mbccpy-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbccpy, _mbccpy_l" title: "_mbccpy, _mbccpy_l" ms.date: "4/2/2020" api_name: ["_mbccpy", "_mbccpy_l", "_o__mbccpy", "_o__mbccpy_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbccpy", "tccpy", "ftccpy", "mbccpy", "_tccpy", "_ftccpy"] helpviewer_keywords: ["_tccpy function", "_tccpy_l function", "tccpy_l function", "tccpy function", "mbccpy function", "_mbccpy_l function", "_mbccpy function", "mbccpy_l function"] ms.assetid: 13f4de6e-7792-41ac-b319-dd9b135433aa --- -# _mbccpy, _mbccpy_l +# `_mbccpy`, `_mbccpy_l` -Copies a multibyte character from one string to another string. More secure versions of these functions are available; see [_mbccpy_s, _mbccpy_s_l](mbccpy-s-mbccpy-s-l.md). +Copies a multibyte character from one string to another string. More secure versions of these functions are available; see [`_mbccpy_s`, `_mbccpy_s_l`](mbccpy-s-mbccpy-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -33,45 +33,45 @@ void _mbccpy_l( ### Parameters -*dest*
+*`dest`*\ Copy destination. -*src*
+*`src`*\ Multibyte character to copy. -*locale*
+*`locale`*\ Locale to use. ## Remarks -The **_mbccpy** function copies one multibyte character from *src* to *dest*. +The **`_mbccpy`** function copies one multibyte character from *`src`* to *`dest`*. -This function validates its parameters. If **_mbccpy** is passed a null pointer for *dest* or *src*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL**. +This function validates its parameters. If **`_mbccpy`** is passed a null pointer for *`dest`* or *`src`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`. -**_mbccpy** uses the current locale for any locale-dependent behavior. **_mbccpy_l** is identical to **_mbccpy** except that **_mbccpy_l** uses the locale passed in for any locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbccpy`** uses the current locale for any locale-dependent behavior. **`_mbccpy_l`** is identical to **`_mbccpy`** except that **`_mbccpy_l`** uses the locale passed in for any locale-dependent behavior. For more information, see [Locale](../locale.md). -**Security Note** Use a null-terminated string. The null-terminated string must not exceed the size of the destination buffer. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. +**Security Note** Use a null-terminated string. The null-terminated string must not exceed the size of the destination buffer. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tccpy**|Maps to macro or inline function|**_mbccpy**|Maps to macro or inline function| -|**_tccpy_l**|n/a|**_mbccpy_l**|n/a| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tccpy` | Maps to macro or inline function | **`_mbccpy`** | Maps to macro or inline function | +| `_tccpy_l` | n/a | **`_mbccpy_l`** | n/a | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbccpy**|\| -|**_mbccpy_l**|\| +| Routine | Required header | +|---|---| +| **`_mbccpy`** | \ | +| **`_mbccpy_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
+[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md) diff --git a/docs/c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md b/docs/c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md index b032daaaf6..7c63020000 100644 --- a/docs/c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md +++ b/docs/c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbccpy_s, _mbccpy_s_l" title: "_mbccpy_s, _mbccpy_s_l" ms.date: "4/2/2020" api_name: ["_mbccpy_s", "_mbccpy_s_l", "_o__mbccpy_s", "_o__mbccpy_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbccpy_s_l", "mbccpy_s_l", "mbccpy_s", "_mbccpy_s"] helpviewer_keywords: ["tccpy_s_l function", "_tccpy_s function", "_mbccpy_s function", "mbccpy_s function", "tccpy_s function", "mbccpy_s_l function", "_tccpy_s_l function", "_mbccpy_s_l function"] ms.assetid: b6e965fa-53c1-4ec3-85ef-a1c4b4f2b2da --- -# _mbccpy_s, _mbccpy_s_l +# `_mbccpy_s`, `_mbccpy_s_l` -Copies one multibyte character from a string to another string. These versions of [_mbccpy, _mbccpy_l](mbccpy-mbccpy-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies one multibyte character from a string to another string. These versions of [`_mbccpy`, `_mbccpy_l`](mbccpy-mbccpy-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -50,65 +50,65 @@ errno_t _mbccpy_s_l( ### Parameters -*dest*
+*`dest`*\ Copy destination. -*buffSizeInBytes*
+*`buffSizeInBytes`*\ Size of the destination buffer. -*pCopied*
-Filled with the number of bytes copied (1 or 2 if successful). Pass **NULL** if you don't care about the number. +*`pCopied`*\ +Filled with the number of bytes copied (1 or 2 if successful). Pass `NULL` if you don't care about the number. -*src*
+*`src`*\ Multibyte character to copy. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Zero if successful; an error code on failure. If *src* or *dest* is **NULL**, or if more than **buffSizeinBytes** bytes would be copied to *dest*, then the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return **EINVAL** and **errno** is set to **EINVAL**. +Zero if successful; an error code on failure. If *`src`* or *`dest`* is `NULL`, or if more than `buffSizeinBytes` bytes would be copied to *`dest`*, then the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `EINVAL`, and `errno` is set to `EINVAL`. ## Remarks -The **_mbccpy_s** function copies one multibyte character from *src* to *dest*. If *src* does not point to the lead byte of a multibyte character as determined by an implicit call to [_ismbblead](ismbblead-ismbblead-l.md), then the single byte that *src* points to is copied. If *src* points to a lead byte but the following byte is 0 and thus invalid, then 0 is copied to *dest*, **errno** is set to **EILSEQ**, and the function returns **EILSEQ**. +The **`_mbccpy_s`** function copies one multibyte character from *`src`* to *`dest`*. If *`src`* doesn't point to the lead byte of a multibyte character as determined by an implicit call to [`_ismbblead`](ismbblead-ismbblead-l.md), then the single byte that *`src`* points to is copied. If *`src`* points to a lead byte, but the following byte is 0 and thus invalid, then 0 is copied to *`dest`*, `errno` is set to `EILSEQ`, and the function returns `EILSEQ`. -**_mbccpy_s** does not append a null terminator; however, if *src* points to a null character, then that null is copied to *dest* (this is just a regular single-byte copy). +**`_mbccpy_s`** doesn't append a null terminator; however, if *`src`* points to a null character, then that null is copied to *`dest`* (as a regular single-byte copy). -The value in *pCopied* is filled with the number of bytes copied. Possible values are 1 and 2 if the operation is successful. If **NULL** is passed in, this parameter is ignored. +The value in *`pCopied`* is filled with the number of bytes copied. Possible values are 1 and 2 if the operation is successful. If `NULL` is passed in, this parameter is ignored. -|*src*|copied to *dest*|*pCopied*|Return value| -|-----------|----------------------|---------------|------------------| -|non-lead-byte|non-lead-byte|1|0| -|0|0|1|0| -|lead-byte followed by non-0|lead-byte followed by non-0|2|0| -|lead-byte followed by 0|0|1|**EILSEQ**| +| *`src`* | copied to *`dest`* | *`pCopied`* | Return value | +|---|---|---|---| +| non-lead-byte | non-lead-byte | 1 | 0 | +| 0 | 0 | 1 | 0 | +| lead-byte followed by non-0 | lead-byte followed by non-0 | 2 | 0 | +| lead-byte followed by 0 | 0 | 1 | `EILSEQ` | -Note that the second row is just a special case of the first. Also note that the table assumes *buffSizeInBytes* >= *pCopied*. +The second row is just a special case of the first row. The table assumes *`buffSizeInBytes`* >= *`pCopied`*. -**_mbccpy_s** uses the current locale for any locale-dependent behavior. **_mbccpy_s_l** is identical to **_mbccpy_s** except that **_mbccpy_s_l** uses the locale passed in for any locale-dependent behavior. +**`_mbccpy_s`** uses the current locale for any locale-dependent behavior. **`_mbccpy_s_l`** is identical to **`_mbccpy_s`** except that **`_mbccpy_s_l`** uses the locale passed in for any locale-dependent behavior. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tccpy_s**|Maps to macro or inline function.|**_mbccpy_s**|Maps to macro or inline function.| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tccpy_s` | Maps to macro or inline function. | **`_mbccpy_s`** | Maps to macro or inline function. | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbccpy_s**|\| -|**_mbccpy_s_l**|\| +| Routine | Required header | +|---|---| +| **`_mbccpy_s`** | \ | +| **`_mbccpy_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
+[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md) diff --git a/docs/c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md b/docs/c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md index 1ceb56341b..8cc7cb139d 100644 --- a/docs/c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md +++ b/docs/c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbc title: "_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l" ms.date: "4/2/2020" api_name: ["_mbcjistojms", "_mbcjmstojis", "_mbcjistojms_l", "_mbcjmstojis_l", "_o__mbcjistojms", "_o__mbcjistojms_l", "_o__mbcjmstojis", "_o__mbcjmstojis_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbcjistojms", "_mbcjistojms", "_mbcjistojms_l", "_mbcjmstojis_l", "_mbcjmstojis", "mbcjmstojis_l", "mbcjistojms_l", "mbcjmstojis"] helpviewer_keywords: ["_mbcjmstojis_l function", "_mbcjistojms function", "mbcjmstojis function", "_mbcjistojms_l function", "_mbcjmstojis function", "mbcjistojms function", "mbcjmstojis_l function", "mbcjistojms_l function"] ms.assetid: dece5127-b337-40a4-aa10-53320a2c9432 --- -# _mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l +# `_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l` Converts between Japan Industry Standard (JIS) and Japan Microsoft (JMS) characters. @@ -38,42 +38,42 @@ unsigned int _mbcjmstojis_l( ### Parameters -*c*
+*`c`*\ Character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value On Japanese locale, these functions return a converted character or return 0 if no conversion is possible. On a non-Japanese locale, these functions return the character passed in. ## Remarks -The **_mbcjistojms** function converts a Japan Industry Standard (JIS) character to a Microsoft Kanji (Shift JIS) character. The character is converted only if the lead and trail bytes are in the range 0x21 - 0x7E. If the lead or trial byte is outside this range, **errno** is set to **EILSEQ**. For more information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +The **`_mbcjistojms`** function converts a Japan Industry Standard (JIS) character to a Microsoft Kanji (Shift JIS) character. The character is converted only if the lead and trail bytes are in the range 0x21 - 0x7E. If the lead or trial byte is outside this range, `errno` is set to `EILSEQ`. For more information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The **_mbcjmstojis** function converts a Shift JIS character to a JIS character. The character is converted only if the lead byte is in the range 0x81 - 0x9F or 0xE0 - 0xFC and the trail byte is in the range 0x40 - 0x7E or 0x80 - 0xFC. Note that some code points in that range do not have a character assigned and so cannot be converted. +The **`_mbcjmstojis`** function converts a Shift JIS character to a JIS character. The character is converted only if the lead byte is in the range 0x81 - 0x9F or 0xE0 - 0xFC and the trail byte is in the range 0x40 - 0x7E or 0x80 - 0xFC. Some code points in that range don't have a character assigned, and so can't be converted. -The value *c* should be a 16-bit value whose upper 8 bits represent the lead byte of the character to convert and whose lower 8 bits represent the trail byte. +The value *`c`* should be a 16-bit value whose upper 8 bits represent the lead byte of the character to convert and whose lower 8 bits represent the trail byte. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In earlier versions, **_mbcjistojms** and **_mbcjmstojis** were called **jistojms** and **jmstojis**, respectively. **_mbcjistojms**, **_mbcjistojms_l**, **_mbcjmstojis** and **_mbcjmstojis_l** should be used instead. +In earlier versions, **`_mbcjistojms`** and **`_mbcjmstojis`** were called `jistojms` and `jmstojis`, respectively. **`_mbcjistojms`**, **`_mbcjistojms_l`**, **`_mbcjmstojis`** and **`_mbcjmstojis_l`** should be used instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbcjistojms**|\| -|**_mbcjistojms_l**|\| -|**_mbcjmstojis**|\| -|**_mbcjmstojis_l**|\| +| Routine | Required header | +|---|---| +| **`_mbcjistojms`** | \ | +| **`_mbcjistojms_l`** | \ | +| **`_mbcjmstojis`** | \ | +| **`_mbcjmstojis_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[_ismbb Routines](../../c-runtime-library/ismbb-routines.md)
+[Data conversion](../data-conversion.md)\ +[`_ismbb` routines](../ismbb-routines.md) diff --git a/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md b/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md index f83b95cb6f..8ecf52189c 100644 --- a/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md +++ b/docs/c-runtime-library/reference/mbclen-mblen-mblen-l.md @@ -3,14 +3,14 @@ title: "_mbclen, mblen, _mblen_l, _mbclen_l" description: "Describes the Microsoft C Runtime Library (CRT) _mbclen, mblen, _mblen_l, and _mbclen_l functions." ms.date: "4/2/2020" api_name: ["_mbclen", "mblen", "_mblen_l", "_mbclen_l", "_o__mbclen", "_o__mbclen_l", "_o__mblen_l", "_o_mblen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mblen", "ftclen", "_mbclen", "_mbclen_l", "tclen", "_ftclen", "_tclen", "mbclen"] helpviewer_keywords: ["tclen function", "_mblen_l function", "_tclen function", "mblen_l function", "_mbclen function", "_mbclen_l function", "mbclen function", "mblen function"] ms.assetid: d5eb92a0-b7a3-464a-aaf7-9890a8e3ed70 --- -# _mbclen, mblen, _mblen_l, _mbclen_l +# `_mbclen`, `mblen`, `_mblen_l`, `_mbclen_l` Gets the length and determines the validity of a multibyte character. @@ -40,51 +40,51 @@ int _mblen_l( ### Parameters -*c*\ +*`c`*\ Multibyte character. -*mbstr*\ +*`mbstr`*\ Address of a multibyte-character byte sequence. -*count*\ +*`count`*\ Number of bytes to check. -*locale*\ +*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbclen** and **_mbclen_l** return 1 or 2, according to the length of the multibyte character *c*. The functions always return 1 for UTF-8, whether *c* is multibyte or not. There's no error return for **_mbclen**. +**`_mbclen`** and **`_mbclen_l`** return 1 or 2, according to the length of the multibyte character *`c`*. The functions always return 1 for UTF-8, whether *`c`* is multibyte or not. There's no error return for **`_mbclen`**. -If *mbstr* isn't **NULL**, **mblen** and **_mblen_l** return the length, in bytes, of the multibyte character. The **mblen** and **_mblen_l** functions work correctly on UTF-8, and may return a value between 1 and 3. When *mbstr* is **NULL** (or it points to the wide-character null character), **mblen** and **_mblen_l** return 0. The object that *mbstr* points to must form a valid multibyte character within the first *count* characters, or **mblen** and **_mblen_l** return -1. +If *`mbstr`* isn't `NULL`, **`mblen`** and **`_mblen_l`** return the length, in bytes, of the multibyte character. The **`mblen`** and **`_mblen_l`** functions work correctly on UTF-8, and may return a value between 1 and 3. When *`mbstr`* is `NULL` (or it points to the wide-character null character), **`mblen`** and **`_mblen_l`** return 0. The object that *`mbstr`* points to must form a valid multibyte character within the first *`count`* characters, or **`mblen`** and **`_mblen_l`** return -1. ## Remarks -The **_mbclen** function returns the length, in bytes, of the multibyte character *c*. If *c* doesn't point to the lead byte of a multibyte character (as determined by an implicit call to [_ismbblead](ismbblead-ismbblead-l.md), the result of **_mbclen** is unpredictable. +The **`_mbclen`** function returns the length, in bytes, of the multibyte character *`c`*. If *`c`* doesn't point to the lead byte of a multibyte character (as determined by an implicit call to [`_ismbblead`](ismbblead-ismbblead-l.md), the result of **`_mbclen`** is unpredictable. -**mblen** returns the length in bytes of *mbstr* if it's a valid multibyte character. It also determines multibyte-character validity associated with the code page. **mblen** examines *count* or fewer bytes contained in *mbstr*, but not more than **MB_CUR_MAX** bytes. +**`mblen`** returns the length in bytes of *`mbstr`* if it's a valid multibyte character. It also determines multibyte-character validity associated with the code page. **`mblen`** examines *`count`* or fewer bytes contained in *`mbstr`*, but not more than `MB_CUR_MAX` bytes. -The output value is affected by the **LC_CTYPE** category setting of the locale. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior. The **_l** suffixed versions behave the same, but they use the locale parameter passed in instead. For more information, see [setlocale](setlocale-wsetlocale.md) and [Locale](../../c-runtime-library/locale.md). +The output value is affected by the `LC_CTYPE` category setting of the locale. The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior. The **`_l`** suffixed versions behave the same, but they use the locale parameter passed in instead. For more information, see [`setlocale`](setlocale-wsetlocale.md) and [Locale](../locale.md). -**_mbclen**, **_mblen_l**, and **_mbclen_l** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **mblen** or **mbrlen** instead. +**`_mbclen`**, **`_mblen_l`**, and **`_mbclen_l`** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **`mblen`** or **`mbrlen`** instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tclen**|Maps to macro or inline function|**_mbclen**|Maps to macro or inline function| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tclen` | Maps to macro or inline function | **`_mbclen`** | Maps to macro or inline function | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbclen**|\| -|**mblen**|\| -|**_mblen_l**|\| +| Routine | Required header | +|---|---| +| **`_mbclen`** | \ | +| **`mblen`** | \ | +| **`_mblen_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -127,9 +127,9 @@ Length in bytes of NULL multibyte character 0: 0 ## See also -[Character Classification](../../c-runtime-library/character-classification.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ -[_mbccpy, _mbccpy_l](mbccpy-mbccpy-l.md)\ -[mbrlen](mbrlen.md)\ -[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) +[Character classification](../character-classification.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbccpy`, `_mbccpy_l`](mbccpy-mbccpy-l.md)\ +[`mbrlen`](mbrlen.md)\ +[`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) diff --git a/docs/c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md b/docs/c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md index 2ea33d05ac..d5fa9ae943 100644 --- a/docs/c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md +++ b/docs/c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbctohira, _mbctohira_l, _mbctokata, _mbctokata title: "_mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l" ms.date: "4/2/2020" api_name: ["_mbctohira", "_mbctohira_l", "_mbctokata", "_mbctokata_l", "_o__mbctohira", "_o__mbctohira_l", "_o__mbctokata", "_o__mbctokata_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbctokata", "mbctohira", "_mbctohira", "_mbctohira_l", "mbctokata", "mbctokata_l", "mbctohira_l", "_mbctokata_l"] helpviewer_keywords: ["_mbctokata function", "_mbctokata_l function", "_mbctohira_l function", "mbctohira_l function", "mbctohira function", "mbctokata_l function", "_mbctohira function", "mbctokata function"] ms.assetid: f949afd7-44d4-4f08-ac8f-1fef2c915a1c --- -# _mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l +# `_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l` Converts between hiragana and katakana characters. @@ -38,45 +38,45 @@ unsigned int _mbctokata_l( ### Parameters -*c*
+*`c`*\ Multibyte character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns the converted character *c*, if possible. Otherwise it returns the character *c* unchanged. +Each of these functions returns the converted character *`c`*, if possible. Otherwise it returns the character *`c`* unchanged. ## Remarks -The **_mbctohira** and **_mbctokata** functions test a character *c* and, if possible, apply one of the following conversions. +The **`_mbctohira`** and **`_mbctokata`** functions test a character *`c`* and, if possible, apply one of the following conversions. -|Routines|Converts| -|--------------|--------------| -|**_mbctohira**, **_mbctohira_l**|Multibyte katakana to multibyte hiragana.| -|**_mbctokata**, **_mbctokata_l**|Multibyte hiragana to multibyte katakana.| +| Routines | Converts | +|---|---| +| **`_mbctohira`**, **`_mbctohira_l`** | Multibyte katakana to multibyte hiragana. | +| **`_mbctokata`**, **`_mbctokata_l`** | Multibyte hiragana to multibyte katakana. | -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **_l** suffix use the current locale for this locale-dependent behavior and the ones that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale for this locale-dependent behavior and the ones that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). -In earlier versions, **_mbctohira** was named **jtohira** and **_mbctokata** was named **jtokata**. For new code, use the new names. +In earlier versions, **`_mbctohira`** was named `jtohira` and **`_mbctokata`** was named `jtokata`. For new code, use the new names. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbctohira**|\| -|**_mbctohira_l**|\| -|**_mbctokata**|\| -|**_mbctokata_l**|\| +| Routine | Required header | +|---|---| +| **`_mbctohira`** | \ | +| **`_mbctohira_l`** | \ | +| **`_mbctokata`** | \ | +| **`_mbctokata_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)
-[_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)
-[_mbctombb, _mbctombb_l](mbctombb-mbctombb-l.md)
+[Data conversion](../data-conversion.md)\ +[`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)\ +[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)\ +[`_mbctombb`, `_mbctombb_l`](mbctombb-mbctombb-l.md) diff --git a/docs/c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md b/docs/c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md index 02866501dc..0c5454f788 100644 --- a/docs/c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md +++ b/docs/c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbctolower, _mbctolower_l, _mbctoupper, _mbctou title: "_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l" ms.date: "4/2/2020" api_name: ["_mbctolower_l", "_mbctoupper_l", "_mbctoupper", "_mbctolower", "_o__mbctolower", "_o__mbctolower_l", "_o__mbctoupper", "_o__mbctoupper_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbctoupper_l", "mbctolower_l", "_mbctolower", "_mbctolower_l", "_mbctoupper", "mbctoupper", "mbctolower", "_mbctoupper_l"] helpviewer_keywords: ["_mbctolower function", "mbctolower_l function", "totupper function", "_mbctoupper function", "totlower function", "_mbctoupper_l function", "mbctolower function", "_totupper function", "_mbctolower_l function", "mbctoupper_l function", "_totlower function", "mbctoupper function"] ms.assetid: 787fab71-3224-4ed7-bc93-4dcd8023fc54 --- -# _mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l +# `_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l` Tests and converts the case of a multibyte character. @@ -38,53 +38,53 @@ unsigned int _mbctoupper_l( ### Parameters -*c*
+*`c`*\ Multibyte character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns the converted character *c*, if possible. Otherwise it returns the character *c* unchanged. +Each of these functions returns the converted character *`c`*, if possible. Otherwise it returns the character *`c`* unchanged. ## Remarks -The functions test a character *c* and, if possible, apply one of the following conversions. +The functions test a character *`c`* and, if possible, apply one of the following conversions. -|Routines|Converts| -|--------------|--------------| -|**_mbctolower**, **_mbctolower_l**|Uppercase character to lowercase character.| -|**_mbctoupper**, **_mbctoupper_l**|Lowercase character to uppercase character.| +| Routines | Converts | +|---|---| +| **`_mbctolower`**, **`_mbctolower_l`** | Uppercase character to lowercase character. | +| **`_mbctoupper`**, **`_mbctoupper_l`** | Lowercase character to uppercase character. | -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The version of this function without the **_l** suffix uses the current locale for this locale-dependent behavior; the version with the **_l** suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The version of this function without the `_l` suffix uses the current locale for this locale-dependent behavior; the version with the `_l` suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In previous versions, **_mbctolower** was called **jtolower**, and **_mbctoupper** was called **jtoupper**. For new code, use the new names instead. +In previous versions, **`_mbctolower`** was called `jtolower`, and **`_mbctoupper`** was called `jtoupper`. For new code, use the new names instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_totlower**|**tolower**|**_mbctolower**|**towlower**| -|**_totlower_l**|**_tolower_l**|**_mbctolower_l**|**_towlower_t**| -|**_totupper**|**toupper**|**_mbctoupper**|**towupper**| -|**_totupper_l**|**toupper_l**|**_mbctoupper_l**|**_towupper_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_totlower` | `tolower` | **`_mbctolower`** | `towlower` | +| `_totlower_l` | `_tolower_l` | **`_mbctolower_l`** | `_towlower_t` | +| `_totupper` | `toupper` | **`_mbctoupper`** | `towupper` | +| `_totupper_l` | `toupper_l` | **`_mbctoupper_l`** | `_towupper_l` | ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**_mbctolower**, **_mbctolower_l**|\| -|**_mbctoupper**, **_mbctoupper_l**|\| +| Routines | Required header | +|---|---| +| **`_mbctolower`**, **`_mbctolower_l`** | \ | +| **`_mbctoupper`**, **`_mbctoupper_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[_mbbtombc, _mbbtombc_l](mbbtombc-mbbtombc-l.md)
-[_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)
-[_mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l](mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)
-[_mbctombb, _mbctombb_l](mbctombb-mbctombb-l.md)
+[Data conversion](../data-conversion.md)\ +[`_mbbtombc`, `_mbbtombc_l`](mbbtombc-mbbtombc-l.md)\ +[`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)\ +[`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)\ +[`_mbctombb`, `_mbctombb_l`](mbctombb-mbctombb-l.md) diff --git a/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md b/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md index 149fd41c88..ad418a3194 100644 --- a/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md +++ b/docs/c-runtime-library/reference/mbctombb-mbctombb-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbctombb, _mbctombb_l" title: "_mbctombb, _mbctombb_l" ms.date: "4/2/2020" api_name: ["_mbctombb_l", "_mbctombb", "_o__mbctombb", "_o__mbctombb_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbctombb_l", "_mbctombb", "mbctombb_l", "mbctombb"] helpviewer_keywords: ["_mbctombb function", "mbctombb_l function", "mbctombb function", "_mbctombb_l function"] ms.assetid: d90970b8-71ff-4586-b6a2-f9ceb811f776 --- -# _mbctombb, _mbctombb_l +# `_mbctombb`, `_mbctombb_l` Converts a double-byte multibyte character to a corresponding single-byte multibyte character. @@ -31,39 +31,39 @@ unsigned int _mbctombb_l( ### Parameters -*c*
+*`c`*\ Multibyte character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -If successful, **_mbctombb** and **_mbctombb_l** returns the single-byte character that corresponds to *c*; otherwise it returns *c*. +If successful, **`_mbctombb`** and **`_mbctombb_l`** returns the single-byte character that corresponds to *`c`*; otherwise it returns *`c`*. ## Remarks -The **_mbctombb** and **_mbctombb_l** functions convert a given multibyte character to a corresponding single-byte multibyte character. Characters must correspond to single-byte characters within the range 0x20 - 0x7E or 0xA1 - 0xDF to be converted. +The **`_mbctombb`** and **`_mbctombb_l`** functions convert a given multibyte character to a corresponding single-byte multibyte character. Characters must correspond to single-byte characters within the range 0x20 - 0x7E or 0xA1 - 0xDF to be converted. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The version of this function without the **_l** suffix uses the current locale for this locale-dependent behavior; the version with the **_l** suffix is identical except that it use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The version of this function without the `_l` suffix uses the current locale for this locale-dependent behavior; the version with the `_l` suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In previous versions, **_mbctombb** was called **zentohan**. Use **_mbctombb** instead. +In previous versions, **`_mbctombb`** was called `zentohan`. Use **`_mbctombb`** instead. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbctombb**|\| -|**_mbctombb_l**|\| +| Routine | Required header | +|---|---| +| **`_mbctombb`** | \ | +| **`_mbctombb_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[_mbbtombc, _mbbtombc_l](mbbtombc-mbbtombc-l.md)
-[_mbcjistojms, _mbcjistojms_l, _mbcjmstojis, _mbcjmstojis_l](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)
-[_mbctohira, _mbctohira_l, _mbctokata, _mbctokata_l](mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)
-[_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l](mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)
+[Data conversion](../data-conversion.md)\ +[`_mbbtombc`, `_mbbtombc_l`](mbbtombc-mbbtombc-l.md)\ +[`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)\ +[`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)\ +[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) diff --git a/docs/c-runtime-library/reference/mbrlen.md b/docs/c-runtime-library/reference/mbrlen.md index 70c4654cae..9a51c3d704 100644 --- a/docs/c-runtime-library/reference/mbrlen.md +++ b/docs/c-runtime-library/reference/mbrlen.md @@ -3,14 +3,14 @@ description: "Learn more about: mbrlen" title: "mbrlen" ms.date: "4/2/2020" api_name: ["mbrlen", "_o_mbrlen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbrlen"] helpviewer_keywords: ["mbrlen function"] ms.assetid: dde8dee9-e091-4c4c-81b3-639808885ae1 --- -# mbrlen +# `mbrlen` Determine the number of bytes that are required to complete a multibyte character in the current locale, with the capability of restarting in the middle of a multibyte character. @@ -26,53 +26,53 @@ size_t mbrlen( ### Parameters -*str*
+*`str`*\ Pointer to the next byte to inspect in a multibyte character string. -*count*
+*`count`*\ The maximum number of bytes to inspect. -*mbstate*
-Pointer to the current shift state of the initial byte of *str*. +*`mbstate`*\ +Pointer to the current shift state of the initial byte of *`str`*. -## Return Value +## Return value One of the following values: | Value | Description | |--|--| -| 0 | The next *count* or fewer bytes complete the multibyte character that represents the wide null character. | -| 1 to *count*, inclusive | The next *count* or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character. | -| (size_t)(-2) | The next *count* bytes contribute to an incomplete but potentially valid multibyte character and all *count* bytes have been processed. | -| (size_t)(-1) | An encoding error occurred. The next *count* or fewer bytes do not contribute to a complete and valid multibyte character. In this case, **errno** is set to EILSEQ and the conversion state in *mbstate* is unspecified. | +| 0 | The next *`count`* or fewer bytes complete the multibyte character that represents the wide null character. | +| 1 to *`count`*, inclusive | The next *`count`* or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character. | +| (size_t)(-2) | The next *`count`* bytes contribute to an incomplete but potentially valid multibyte character and all *`count`* bytes have been processed. | +| (size_t)(-1) | An encoding error occurred. The next *`count`* or fewer bytes don't contribute to a complete and valid multibyte character. In this case, `errno` is set to EILSEQ and the conversion state in *`mbstate`* is unspecified. | ## Remarks -The **mbrlen** function inspects at most *count* bytes starting with the byte pointed to by *str* to determine the number of bytes that are required to complete the next multibyte character, including any shift sequences. It is equivalent to the call `mbrtowc(NULL, str, count, &mbstate)` where *mbstate* is either a user-provided **mbstate_t** object, or a static internal object provided by the library. +The **`mbrlen`** function inspects at most *`count`* bytes starting with the byte pointed to by *`str`* to determine the number of bytes that are required to complete the next multibyte character, including any shift sequences. It's equivalent to the call `mbrtowc(NULL, str, count, &mbstate)` where *`mbstate`* is either a user-provided `mbstate_t` object, or a static internal object provided by the library. -The **mbrlen** function saves and uses the shift state of an incomplete multibyte character in the *mbstate* parameter. This gives **mbrlen** the capability of restarting in the middle of a multibyte character if need be, examining at most *count* bytes. If *mbstate* is a null pointer, **mbrlen** uses an internal, static **mbstate_t** object to store the shift state. Because the internal **mbstate_t** object is not thread-safe, we recommend that you always allocate and pass your own *mbstate* parameter. +The **`mbrlen`** function saves and uses the shift state of an incomplete multibyte character in the *`mbstate`* parameter. It's why **`mbrlen`**can restart in the middle of a multibyte character, if needed, and examine at most *`count`* bytes. If *`mbstate`* is a null pointer, **`mbrlen`** uses an internal, static `mbstate_t` object to store the shift state. Because the internal `mbstate_t` object isn't thread-safe, we recommend that you always allocate and pass your own *`mbstate`* parameter. -The **mbrlen** function differs from [_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md) by its restartability. The shift state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use **wcsrlen** instead of **wcslen** if a subsequent call to **wcsrtombs** is used instead of **wcstombs**. +The **`mbrlen`** function differs from [`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md) by its restartability. The shift state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use `wcsrlen` instead of `wcslen` if a subsequent call to `wcsrtombs` is used instead of `wcstombs`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|not applicable|not applicable|**mbrlen**|not applicable| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| not applicable | not applicable | **`mbrlen`** | not applicable | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbrlen**|\| +| Routine | Required header | +|---|---| +| **`mbrlen`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This example shows how the interpretation of multibyte characters depends on the current code page, and demonstrates the resuming capability of **mbrlen**. +This example shows how the interpretation of multibyte characters depends on the current code page, and demonstrates the resuming capability of **`mbrlen`**. ```C // crt_mbrlen.c @@ -134,5 +134,5 @@ Character count: 25 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md) diff --git a/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md b/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md index bb14a8ab52..f30c701ea5 100644 --- a/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md +++ b/docs/c-runtime-library/reference/mbrtoc16-mbrtoc323.md @@ -3,14 +3,14 @@ description: "Learn more about: mbrtoc16, mbrtoc32" title: "mbrtoc16, mbrtoc323" ms.date: "4/2/2020" api_name: ["mbrtoc16", "mbrtoc32", "_o_mbrtoc16", "_o_mbrtoc32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbrtoc16", "mbrtoc32", "uchar/mbrtoc16", "uchar/mbrtoc32"] helpviewer_keywords: ["mbrtoc16 function", "mbrtoc32 function"] ms.assetid: 099ade4d-56f7-4e61-8b45-493f1d7a64bd --- -# mbrtoc16, mbrtoc32 +# `mbrtoc16`, `mbrtoc32` Translates the first UTF-8 multibyte character in a string into the equivalent UTF-16 or UTF-32 character. @@ -34,56 +34,56 @@ size_t mbrtoc32( ### Parameters -*destination*\ +*`destination`*\ Pointer to the **`char16_t`** or **`char32_t`** equivalent of the UTF-8 multibyte character to convert. If null, the function doesn't store a value. -*source*\ +*`source`*\ Pointer to the UTF-8 multibyte character string to convert. -*max_bytes*\ -The maximum number of bytes in *source* to examine for a character to convert. This argument should be a value between one and the number of bytes, including any null terminator, remaining in *source*. +*`max_bytes`*\ +The maximum number of bytes in *`source`* to examine for a character to convert. This argument should be a value between one and the number of bytes, including any null terminator, remaining in *`source`*. -*state*\ -Pointer to a **mbstate_t** conversion state object used to interpret the UTF-8 multibyte string to one or more output characters. +*`state`*\ +Pointer to a `mbstate_t` conversion state object used to interpret the UTF-8 multibyte string to one or more output characters. ## Return value -On success, returns the value of the first of these conditions that applies, given the current *state* value: +On success, returns the value of the first of these conditions that applies, given the current *`state`* value: -|Value|Condition| -|-----------|---------------| -|0|The next *max_bytes* or fewer characters converted from *source* correspond to the null wide character, which is the value stored if *destination* isn't null.

*state* contains the initial shift state.| -|Between 1 and *max_bytes*, inclusive|The value returned is the number of bytes of *source* that complete a valid multibyte character. The converted wide character is stored if *destination* isn't null.| -|-3|The next wide character resulting from a previous call to the function has been stored in *destination* if *destination* isn't null. No bytes from *source* are consumed by this call to the function.

When *source* points to a UTF-8 multibyte character that requires more than one wide character to represent (for example, a surrogate pair), then the *state* value is updated so that the next function call writes out the additional character.| -|-2|The next *max_bytes* bytes represent an incomplete, but potentially valid, UTF-8 multibyte character. No value is stored in *destination*. This result can occur if *max_bytes* is zero.| -|-1|An encoding error has occurred. The next *max_bytes* or fewer bytes do not contribute to a complete and valid UTF-8 multibyte character. No value is stored in *destination*.

**EILSEQ** is stored in **errno** and the conversion state value *state* is unspecified.| +| Value | Condition | +|---|---| +| 0 | The next *`max_bytes`* or fewer characters converted from *`source`* correspond to the null wide character, which is the value stored if *`destination`* isn't null.

*`state`* contains the initial shift state. | +| Between 1 and *`max_bytes`*, inclusive | The value returned is the number of bytes of *`source`* that complete a valid multibyte character. The converted wide character is stored if *`destination`* isn't null. | +| -3 | The next wide character resulting from a previous call to the function has been stored in *`destination`* if *`destination`* isn't null. No bytes from *`source`* are consumed by this call to the function.

When *`source`* points to a UTF-8 multibyte character that requires more than one wide character to represent (for example, a surrogate pair), then the *`state`* value is updated so that the next function call writes out the extra character. | +| -2 | The next *`max_bytes`* bytes represent an incomplete, but potentially valid, UTF-8 multibyte character. No value is stored in *`destination`*. This result can occur if *`max_bytes`* is zero. | +| -1 | An encoding error has occurred. The next *`max_bytes`* or fewer bytes don't contribute to a complete and valid UTF-8 multibyte character. No value is stored in *`destination`*.

`EILSEQ` is stored in `errno` and the conversion state value *`state`* is unspecified. | ## Remarks -The **mbrtoc16** function reads up to *max_bytes* bytes from *source* to find the first complete, valid UTF-8 multibyte character, and then stores the equivalent UTF-16 character in *destination*. If the character requires more than one UTF-16 output character, such as a surrogate pair, then the *state* value is set to store the next UTF-16 character in *destination* on the next call to **mbrtoc16**. The **mbrtoc32** function is identical, but output is stored as a UTF-32 character. +The **`mbrtoc16`** function reads up to *`max_bytes`* bytes from *`source`* to find the first complete, valid UTF-8 multibyte character, and then stores the equivalent UTF-16 character in *`destination`*. If the character requires more than one UTF-16 output character, such as a surrogate pair, then the *`state`* value is set to store the next UTF-16 character in *`destination`* on the next call to **`mbrtoc16`**. The **`mbrtoc32`** function is identical, but output is stored as a UTF-32 character. -If *source* is null, these functions return the equivalent of a call made using arguments of **NULL** for *destination*, `""` (an empty, null-terminated string) for *source*, and 1 for *max_bytes*. The passed values of *destination* and *max_bytes* are ignored. +If *`source`* is null, these functions return the equivalent of a call made using arguments of `NULL` for *`destination`*, `""` (an empty, null-terminated string) for *`source`*, and 1 for *`max_bytes`*. The passed values of *`destination`* and *`max_bytes`* are ignored. -If *source* isn't null, the function starts at the beginning of the string and inspects up to *max_bytes* bytes to determine the number of bytes required to complete the next UTF-8 multibyte character, including any shift sequences. If the examined bytes contain a valid and complete UTF-8 multibyte character, the function converts the character into the equivalent 16-bit or 32-bit wide character or characters. If *destination* isn't null, the function stores the first (and possibly only) result character in destination. If additional output characters are required, a value is set in *state*, so that subsequent calls to the function output the additional characters and return the value -3. If no more output characters are required, then *state* is set to the initial shift state. +If *`source`* isn't null, the function starts at the beginning of the string and inspects up to *`max_bytes`* bytes to determine the number of bytes required to complete the next UTF-8 multibyte character, including any shift sequences. If the examined bytes contain a valid and complete UTF-8 multibyte character, the function converts the character into the equivalent 16-bit or 32-bit wide character or characters. If *`destination`* isn't null, the function stores the first (and possibly only) result character in destination. If extra output characters are required, a value is set in *`state`*, so that subsequent calls to the function output the extra characters and return the value -3. If no more output characters are required, then *`state`* is set to the initial shift state. -To convert non-UTF-8 multibyte characters to UTF-16 LE characters, use the [mbrtowc](mbrtowc.md), [mbtowc, or _mbtowc_l](mbtowc-mbtowc-l.md) functions. +To convert non-UTF-8 multibyte characters to UTF-16 LE characters, use the [`mbrtowc`](mbrtowc.md), [mbtowc, or _mbtowc_l](mbtowc-mbtowc-l.md) functions. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**mbrtoc16**, **mbrtoc32**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`mbrtoc16`**, **`mbrtoc32`** | \ | \ | -For additional compatibility information, see [Compatibility](../compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also [Data conversion](../data-conversion.md)\ [Locale](../locale.md)\ [Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ -[c16rtomb, c32rtomb](c16rtomb-c32rtomb1.md)\ -[mbrtowc](mbrtowc.md)\ -[mbsrtowcs](mbsrtowcs.md)\ -[mbsrtowcs_s](mbsrtowcs-s.md) +[`c16rtomb`, `c32rtomb`](c16rtomb-c32rtomb1.md)\ +[`mbrtowc`](mbrtowc.md)\ +[`mbsrtowcs`](mbsrtowcs.md)\ +[`mbsrtowcs_s`](mbsrtowcs-s.md) diff --git a/docs/c-runtime-library/reference/mbrtowc.md b/docs/c-runtime-library/reference/mbrtowc.md index 62414f9ee5..7c64576e18 100644 --- a/docs/c-runtime-library/reference/mbrtowc.md +++ b/docs/c-runtime-library/reference/mbrtowc.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: mbrtowc" title: "mbrtowc" -ms.date: "4/2/2020" +description: "Learn more about: mbrtowc" +ms.date: 4/2/2020 api_name: ["mbrtowc", "_o_mbrtowc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbrtowc"] helpviewer_keywords: ["mbrtowc function"] -ms.assetid: a1e87fcc-6de0-4ca1-bf26-508d28490286 --- -# mbrtowc +# `mbrtowc` Convert a multibyte character in the current locale into the equivalent wide character, with the capability of restarting in the middle of a multibyte character. @@ -27,47 +26,47 @@ size_t mbrtowc( ### Parameters -*wchar*
+*`wchar`*\ Address of a wide character to receive the converted wide character string (type **`wchar_t`**). This value can be a null pointer if no return wide character is required. -*mbchar*
+*`mbchar`*\ Address of a sequence of bytes (a multibyte character). -*count*
+*`count`*\ Number of bytes to check. -*mbstate*
-Pointer to conversion state object. If this value is a null pointer, the function uses a static internal conversion state object. Because the internal **mbstate_t** object is not thread-safe, we recommend that you always pass your own *mbstate* argument. +*`mbstate`*\ +Pointer to conversion state object. If this value is a null pointer, the function uses a static internal conversion state object. Because the internal `mbstate_t` object isn't thread-safe, we recommend that you always pass your own *`mbstate`* argument. -## Return Value +## Return value One of the following values: 0 -The next *count* or fewer bytes complete the multibyte character that represents the null wide character, which is stored in *wchar*, if *wchar* is not a null pointer. +The next *`count`* or fewer bytes complete the multibyte character that represents the null wide character, which is stored in *`wchar`*, if *`wchar`* isn't a null pointer. -1 to *count*, inclusive -The next *count* or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character. The wide character equivalent is stored in *wchar*, if *wchar* is not a null pointer. +1 to *`count`*, inclusive +The next *`count`* or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character. The wide character equivalent is stored in *`wchar`*, if *`wchar`* isn't a null pointer. (size_t)(-1) -An encoding error occurred. The next *count* or fewer bytes do not contribute to a complete and valid multibyte character. In this case, **errno** is set to EILSEQ and the conversion shift state in *mbstate* is unspecified. +An encoding error occurred. The next *`count`* or fewer bytes don't contribute to a complete and valid multibyte character. In this case, `errno` is set to EILSEQ and the conversion shift state in *`mbstate`* is unspecified. (size_t)(-2) -The next *count* bytes contribute to an incomplete but potentially valid multibyte character, and all *count* bytes have been processed. No value is stored in *wchar*, but *mbstate* is updated to restart the function. +The next *`count`* bytes contribute to an incomplete but potentially valid multibyte character, and all *`count`* bytes have been processed. No value is stored in *`wchar`*, but *`mbstate`* is updated to restart the function. ## Remarks -If *mbchar* is a null pointer, the function is equivalent to the call: +If *`mbchar`* is a null pointer, the function is equivalent to the call: `mbrtowc(NULL, "", 1, &mbstate)` -In this case, the value of the arguments *wchar* and *count* are ignored. +In this case, the values of the *`wchar`* and *`count`* arguments are ignored. -If *mbchar* is not a null pointer, the function examines *count* bytes from *mbchar* to determine the required number of bytes that are required to complete the next multibyte character. If the next character is valid, the corresponding multibyte character is stored in *wchar* if it is not a null pointer. If the character is the corresponding wide null character, the resulting state of *mbstate* is the initial conversion state. +If *`mbchar`* isn't a null pointer, the function examines *`count`* bytes from *`mbchar`* to determine the required number of bytes that are required to complete the next multibyte character. If the next character is valid, the corresponding multibyte character is stored in *`wchar`* if it isn't a null pointer. If the character is the corresponding wide null character, the resulting state of *`mbstate`* is the initial conversion state. -The **mbrtowc** function differs from [mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use **wcsrlen** instead of **wcslen** if a subsequent call to **wcsrtombs** is used instead of **wcstombs**. +The **`mbrtowc`** function differs from [`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use `wcsrlen` instead of `wcslen` if a subsequent call to `wcsrtombs` is used instead of `wcstombs`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Example @@ -100,7 +99,7 @@ int Sample(char* szIn, wchar_t* wcOut, int nMax) szLocal = setlocale(LC_ALL, "French_Canada.1252"); if (!szLocal) { - printf("The fuction setlocale(LC_ALL, \"French_Canada.1252\") failed!\n"); + printf("The function setlocale(LC_ALL, \"French_Canada.1252\") failed!\n"); return 1; } @@ -110,7 +109,7 @@ int Sample(char* szIn, wchar_t* wcOut, int nMax) // from a previous call to setlocale. if (_setmbcp(_MB_CP_SBCS) == -1) { - printf("The fuction _setmbcp(_MB_CP_SBCS) failed!"); + printf("The function _setmbcp(_MB_CP_SBCS) failed!"); return 1; } @@ -179,7 +178,7 @@ int main(int argc, char* argv[]) } ``` -### Sample Output +### Sample output ```Output Locale set to: "French_Canada.1252" @@ -190,12 +189,12 @@ WC String: AaBbCcÜïα∩≡xXyYzZ ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbrtowc**|\| +| Routine | Required header | +|---|---| +| **`mbrtowc`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md b/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md index 69c58a80c5..33819daf2c 100644 --- a/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md +++ b/docs/c-runtime-library/reference/mbsbtype-mbsbtype-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbsbtype, _mbsbtype_l" title: "_mbsbtype, _mbsbtype_l" ms.date: "4/2/2020" api_name: ["_mbsbtype_l", "_mbsbtype", "_o__mbsbtype", "_o__mbsbtype_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsbtype", "mbsbtype_l", "_mbsbtype_l", "_mbsbtype"] helpviewer_keywords: ["_mbsbtype function", "mbsbtype function", "_mbsbtype_l function", "mbsbtype_l function"] ms.assetid: 0d5dd91a-d32d-4f98-ac57-98dfc9e98eac --- -# _mbsbtype, _mbsbtype_l +# `_mbsbtype`, `_mbsbtype_l` Returns the type of byte within a string. @@ -33,47 +33,47 @@ int _mbsbtype_l( ### Parameters -*mbstr*
+*`mbstr`*\ Address of a sequence of multibyte characters. -*count*
+*`count`*\ Byte offset from head of string. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsbtype** and **_mbsbtype_l** returns an integer value indicating the result of the test on the specified byte. The manifest constants in the following table are defined in Mbctype.h. +**`_mbsbtype`** and **`_mbsbtype_l`** returns an integer value indicating the result of the test on the specified byte. The manifest constants in the following table are defined in Mbctype.h. -|Return value|Byte type| -|------------------|---------------| -|**_MBC_SINGLE** (0)|Single-byte character. For example, in code page 932, **_mbsbtype** returns 0 if the specified byte is within the range 0x20 - 0x7E or 0xA1 - 0xDF.| -|**_MBC_LEAD** (1)|Lead byte of multibyte character. For example, in code page 932, **_mbsbtype** returns 1 if the specified byte is within the range 0x81 - 0x9F or 0xE0 - 0xFC.| -|**_MBC_TRAIL** (2)|Trailing byte of multibyte character. For example, in code page 932, **_mbsbtype** returns 2 if the specified byte is within the range 0x40 - 0x7E or 0x80 - 0xFC.| -|**_MBC_ILLEGAL** (-1)|**NULL** string, invalid character, or null byte found before the byte at offset *count* in *mbstr*.| +| Return value | Byte type | +|---|---| +| `_MBC_SINGLE` (0) | Single-byte character. For example, in code page 932, **`_mbsbtype`** returns 0 if the specified byte is within the range 0x20 - 0x7E or 0xA1 - 0xDF. | +| `_MBC_LEAD` (1) | Lead byte of multibyte character. For example, in code page 932, **`_mbsbtype`** returns 1 if the specified byte is within the range 0x81 - 0x9F or 0xE0 - 0xFC. | +| `_MBC_TRAIL` (2) | Trailing byte of multibyte character. For example, in code page 932, **`_mbsbtype`** returns 2 if the specified byte is within the range 0x40 - 0x7E or 0x80 - 0xFC. | +| `_MBC_ILLEGAL` (-1) | `NULL` string, invalid character, or null byte found before the byte at offset *`count`* in *`mbstr`*. | ## Remarks -The **_mbsbtype** function determines the type of a byte in a multibyte character string. The function examines only the byte at offset *count* in *mbstr*, ignoring invalid characters before the specified byte. +The **`_mbsbtype`** function determines the type of a byte in a multibyte character string. The function examines only the byte at offset *`count`* in *`mbstr`*, ignoring invalid characters before the specified byte. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The version of this function without the **_l** suffix uses the current locale for this locale-dependent behavior; the version with the **_l** suffix is identical except that it use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The version of this function without the `_l` suffix uses the current locale for this locale-dependent behavior; the version with the `_l` suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -If the input string is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **_MBC_ILLEGAL**. +If the input string is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `_MBC_ILLEGAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_mbsbtype**|\|\*| -|**_mbsbtype_l**|\|\*| +| Routine | Required header | Optional header | +|---|---|---| +| **`_mbsbtype`** | \ | \* | +| **`_mbsbtype_l`** | \ | \* | \* For manifest constants used as return values. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
+[Byte classification](../byte-classification.md) diff --git a/docs/c-runtime-library/reference/mbsinit.md b/docs/c-runtime-library/reference/mbsinit.md index 5b6a3150ac..ffaee02222 100644 --- a/docs/c-runtime-library/reference/mbsinit.md +++ b/docs/c-runtime-library/reference/mbsinit.md @@ -10,7 +10,7 @@ f1_keywords: ["mbsinit"] helpviewer_keywords: ["mbsinit function"] ms.assetid: 4618555b-baaa-4d04-93fa-36abae411034 --- -# mbsinit +# `mbsinit` Tracks the state of a multibyte character conversion. @@ -24,16 +24,16 @@ int mbsinit( ### Parameters -*ps*
-A pointer to an [mbstate_t](../../c-runtime-library/standard-types.md) variable. +*`ps`*\ +A pointer to an [`mbstate_t`](../standard-types.md) variable. -## Return Value +## Return value -Nonzero if *ps* is **NULL** or if not in the middle of a conversion. +Nonzero if *`ps`* is `NULL` or if not in the middle of a conversion. ## Remarks -When using one of the ANSI functions that takes an **mbstate_t** pointer, passing the address of your **mbstate_t** will return information about whether the last byte in the buffer was converted. +When using one of the ANSI functions that takes an `mbstate_t` pointer, passing the address of your `mbstate_t` will return information about whether the last byte in the buffer was converted. The appropriate code page needs to be installed to support your multibyte characters. @@ -131,7 +131,7 @@ int main(int argc, char* argv[]) } ``` -### Sample Output +### Sample output ```Output Locale set to: "Japanese_Japan.932" @@ -145,4 +145,4 @@ WC String: AaBbCcxXyYzZ ## See also -[Byte Classification](../../c-runtime-library/byte-classification.md)
+[Byte classification](../byte-classification.md) diff --git a/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md b/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md index e5e8778cf4..2c05c0dc72 100644 --- a/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md +++ b/docs/c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbsnbcat, _mbsnbcat_l" title: "_mbsnbcat, _mbsnbcat_l" ms.date: "4/2/2020" api_name: ["_mbsnbcat_l", "_mbsnbcat", "_o__mbsnbcat", "_o__mbsnbcat_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbcat", "mbsnbcat_l", "_mbsnbcat", "_mbsnbcat_l"] helpviewer_keywords: ["tcsncat_l function", "_tcsncat function", "mbsnbcat_l function", "mbsnbcat function", "_mbsnbcat_l function", "_tcsncat_l function", "_mbsnbcat function", "tcsncat function"] ms.assetid: aa0f1d30-0ddd-48d1-88eb-c6884b20fd91 --- -# _mbsnbcat, _mbsnbcat_l +# `_mbsnbcat`, `_mbsnbcat_l` -Appends, at most, the first **n** bytes of one multibyte-character string to another. More secure versions of these functions are available; see [_mbsnbcat_s, _mbsnbcat_s_l](mbsnbcat-s-mbsnbcat-s-l.md). +Appends, at most, the first **n** bytes of one multibyte-character string to another. More secure versions of these functions are available; see [`_mbsnbcat_s`, `_mbsnbcat_s_l`](mbsnbcat-s-mbsnbcat-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -48,59 +48,59 @@ unsigned char *_mbsnbcat_l( ### Parameters -*dest*
+*`dest`*\ Null-terminated multibyte-character destination string. -*src*
+*`src`*\ Null-terminated multibyte-character source string. -*count*
-Number of bytes from *src* to append to *dest*. +*`count`*\ +Number of bytes from *`src`* to append to *`dest`*. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsnbcat** returns a pointer to the destination string. No return value is reserved to indicate an error. +**`_mbsnbcat`** returns a pointer to the destination string. No return value is reserved to indicate an error. ## Remarks -The **_mbsnbcat** function appends, at most, the first *count* bytes of *src* to *dest*. If the byte immediately preceding the null character in *dest* is a lead byte, the initial byte of *src* overwrites this lead byte. Otherwise, the initial byte of *src* overwrites the terminating null character of *dest*. If a null byte appears in *src* before *count* bytes are appended, **_mbsnbcat** appends all bytes from *src*, up to the null character. If *count* is greater than the length of *src*, the length of *src* is used in place of *count*. The resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. +The **`_mbsnbcat`** function appends, at most, the first *`count`* bytes of *`src`* to *`dest`*. If the byte immediately preceding the null character in *`dest`* is a lead byte, the initial byte of *`src`* overwrites this lead byte. Otherwise, the initial byte of *`src`* overwrites the terminating null character of *`dest`*. If a null byte appears in *`src`* before *`count`* bytes are appended, **`_mbsnbcat`** appends all bytes from *`src`*, up to the null character. If *`count`* is greater than the length of *`src`*, the length of *`src`* is used in place of *`count`*. The resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The **_mbsnbcat** version of the function uses the current locale for this locale-dependent behavior; the **_mbsnbcat_l** version is identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsnbcat`** version of the function uses the current locale for this locale-dependent behavior; the **`_mbsnbcat_l`** version is identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -**Security Note** Use a null-terminated string. The null-terminated string must not exceed the size of the destination buffer. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** Use a null-terminated string. The null-terminated string must not exceed the size of the destination buffer. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -If *dest* or *src* is **NULL**, the function will generate an invalid parameter error, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function returns **EINVAL** and sets **errno** to **EINVAL**. +If *`dest`* or *`src`* is `NULL`, the function will generate an invalid parameter error, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function returns `EINVAL` and sets `errno` to `EINVAL`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsncat**|[strncat](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)|**_mbsnbcat**|[wcsncat](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)| -|**_tcsncat_l**|**_strncat_l**|**_mbsnbcat_l**|**_wcsncat_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncat` | [`strncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) | **`_mbsnbcat`** | [`wcsncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) | +| `_tcsncat_l` | `_strncat_l` | **`_mbsnbcat_l`** | `_wcsncat_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcat**|\| -|**_mbsnbcat_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcat`** | \ | +| **`_mbsnbcat_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md)
-[_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)
-[_mbsnbcpy, _mbsnbcpy_l](mbsnbcpy-mbsnbcpy-l.md)
-[_mbsnbicmp, _mbsnbicmp_l](mbsnbicmp-mbsnbicmp-l.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[_mbsnbcat_s, _mbsnbcat_s_l](mbsnbcat-s-mbsnbcat-s-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)\ +[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`_mbsnbcat_s`, `_mbsnbcat_s_l`](mbsnbcat-s-mbsnbcat-s-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md b/docs/c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md index 6cf57f7896..97c101be2d 100644 --- a/docs/c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md +++ b/docs/c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md @@ -3,7 +3,7 @@ title: "`_mbsnbcat_s`, `_mbsnbcat_s_l`" description: "API description for the Microsoft Visual C++ `_mbsnbcat_s`, and `_mbsnbcat_s_l` functions" ms.date: "12/2/2020" api_name: ["_mbsnbcat_s_l", "_mbsnbcat_s", "_o__mbsnbcat_s", "_o__mbsnbcat_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbsnbcat_s", "mbsnbcat_s", "_mbsnbcat_s_l", "mbsnbcat_s_l"] @@ -12,7 +12,7 @@ ms.assetid: 2c9e9be7-d979-4a54-8ada-23428b6648a9 --- # `_mbsnbcat_s`, `_mbsnbcat_s_l` -Appends to a multibyte character string, at most, the first **n** bytes of another multibyte-character string. These are versions of [`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md) that have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Appends to a multibyte character string, at most, the first **n** bytes of another multibyte-character string. These functions are versions of [`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md) that have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -65,51 +65,51 @@ Number of bytes from *`src`* to append to *`dest`*. *`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; otherwise, an error code. -### Error Conditions +### Error conditions -|**`dest`**|*`sizeInBytes`*|*`src`*|Return value| -|------------|-------------------|-----------|------------------| -|**`NULL`**|any|any|**`EINVAL`**| -|Any|<= 0|any|**`EINVAL`**| -|Any|any|**`NULL`**|**`EINVAL`**| +| **`dest`** | *`sizeInBytes`* | *`src`* | Return value | +|---|---|---|---| +| `NULL` | any | any | `EINVAL` | +| Any | <= 0 | any | `EINVAL` | +| Any | any | `NULL` | `EINVAL` | -If any of the error conditions occurs, the function generates an invalid parameter error, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function returns **`EINVAL`** and sets **errno** to **`EINVAL`**. +If any of the error conditions occurs, the function generates an invalid parameter error, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function returns `EINVAL` and sets `errno` to `EINVAL`. ## Remarks The **`_mbsnbcat_s`** function appends to *`dest`*, at most, the first *`count`* bytes of *`src`*. If the byte that immediately precedes the null character in *`dest`* is a lead byte, it's overwritten by the initial byte of *`src`*. Otherwise, the initial byte of *`src`* overwrites the terminating null character of *`dest`*. If a null byte appears in *`src`* before *`count`* bytes are appended, **`_mbsnbcat_s`** appends all bytes from *`src`*, up to the null character. If *`count`* is greater than the length of *`src`*, the length of *`src`* is used in place of *`count`*. The resulting string is terminated by a null character. If copying takes place between strings that overlap, the behavior is undefined. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale and the ones that do have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale and the ones that do have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). -In C++, the use of these functions is simplified by template overloads. The overloads can infer buffer length automatically which eliminates the need to specify a size argument, and they can automatically use their newer, more secure functions to replace older, less-secure functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, the use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a size argument, and they can automatically use the newer, more secure functions to replace older, less-secure functions. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tcsncat_s`**|[strncat_s](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)|**`_mbsnbcat_s`**|[wcsncat_s](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)| -|**`_tcsncat_s_l`**|**`_strncat_s_l`**|**`_mbsnbcat_s_l`**|**`_wcsncat_s_l`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncat_s` | [`strncat_s`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) | **`_mbsnbcat_s`** | [`wcsncat_s`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) | +| `_tcsncat_s_l` | **`_strncat_s_l`** | **`_mbsnbcat_s_l`** | **`_wcsncat_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_mbsnbcat_s`**|\| -|**`_mbsnbcat_s_l`**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcat_s`** | \ | +| **`_mbsnbcat_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ +[String manipulation](../string-manipulation-crt.md)\ [`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ [`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)\ [`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ diff --git a/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md b/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md index 57b4588b40..f8d3825534 100644 --- a/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md +++ b/docs/c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbsnbcmp, _mbsnbcmp_l" title: "_mbsnbcmp, _mbsnbcmp_l" ms.date: "4/2/2020" api_name: ["_mbsnbcmp", "_mbsnbcmp_l", "_o__mbsnbcmp", "_o__mbsnbcmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbcmp", "tcsnbmp", "_mbsnbcmp_l", "mbsnbcmp_l", "_mbsnbcmp"] helpviewer_keywords: ["mbsnbcmp_l function", "mbsnbcmp function", "tcsncmp function", "_mbsnbcmp_l function", "_tcsncmp function", "_mbsnbcmp function"] ms.assetid: dbc99e50-cf85-4e57-a13f-067591f18ac8 --- -# _mbsnbcmp, _mbsnbcmp_l +# `_mbsnbcmp`, `_mbsnbcmp_l` Compares the first **n** bytes of two multibyte-character strings. @@ -35,54 +35,54 @@ int _mbsnbcmp_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ The strings to compare. -*count*
+*`count`*\ The number of bytes to compare. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -The return value indicates the ordinal relationship between the substrings of *string1* and *string2*. +The return value indicates the ordinal relationship between the substrings of *`string1`* and *`string2`*. -|Return value|Description| -|------------------|-----------------| -|< 0|*string1* substring is less than *string2* substring.| -|0|*string1* substring is identical to *string2* substring.| -|> 0|*string1* substring is greater than *string2* substring.| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring is less than *`string2`* substring. | +| 0 | *`string1`* substring is identical to *`string2`* substring. | +| > 0 | *`string1`* substring is greater than *`string2`* substring. | -On a parameter validation error, **_mbsnbcmp** and **_mbsnbcmp_l** return **_NLSCMPERROR**, which is defined in \ and \. +On a parameter validation error, **`_mbsnbcmp`** and **`_mbsnbcmp_l`** return `_NLSCMPERROR`, which is defined in \ and \. ## Remarks -The **_mbsnbcmp** functions compare at most the first *count* bytes in *string1* and *string2* and return a value that indicates the relationship between the substrings. **_mbsnbcmp** is a case-sensitive version of **_mbsnbicmp**. Unlike **_mbsnbcoll**, **_mbsnbcmp** is not affected by the collation order of the locale. **_mbsnbcmp** recognizes multibyte-character sequences according to the current multibyte [code page](../../c-runtime-library/code-pages.md). +The **`_mbsnbcmp`** functions compare at most the first *`count`* bytes in *`string1`* and *`string2`* and return a value that indicates the relationship between the substrings. **`_mbsnbcmp`** is a case-sensitive version of **`_mbsnbicmp`**. Unlike `_mbsnbcoll`, **`_mbsnbcmp`** isn't affected by the collation order of the locale. **`_mbsnbcmp`** recognizes multibyte-character sequences according to the current multibyte [code page](../code-pages.md). -**_mbsnbcmp** resembles **_mbsncmp**, except that **_mbsncmp** compares strings by characters rather than by bytes. +**`_mbsnbcmp`** resembles **`_mbsncmp`**, except that **`_mbsncmp`** compares strings by characters rather than by bytes. -The output value is affected by the **LC_CTYPE** category setting of the locale, which specifies the lead bytes and trailing bytes of multibyte characters. For more information, see [setlocale](setlocale-wsetlocale.md). The **_mbsnbcmp** function uses the current locale for this locale-dependent behavior. The **_mbsnbcmp_l** function is identical except that it uses the *locale* parameter instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the `LC_CTYPE` category setting of the locale, which specifies the lead bytes and trailing bytes of multibyte characters. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsnbcmp`** function uses the current locale for this locale-dependent behavior. The **`_mbsnbcmp_l`** function is identical except that it uses the *`locale`* parameter instead. For more information, see [Locale](../locale.md). -If either *string1* or *string2* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return **_NLSCMPERROR** and **errno** is set to **EINVAL**. +If either *`string1`* or *`string2`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `_NLSCMPERROR`, and `errno` is set to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|---------------------------------------|--------------------|-----------------------| -|**_tcsncmp**|[strncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)|**_mbsnbcmp**|[wcsncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)| -|**_tcsncmp_l**|[strncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)|**_mbsnbcml**|[wcsncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncmp` | [`strncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) | **`_mbsnbcmp`** | [`wcsncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) | +| `_tcsncmp_l` | [`strncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) | **`_mbsnbcml`** | [`wcsncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcmp**|\| -|**_mbsnbcmp_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcmp`** | \ | +| **`_mbsnbcmp_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ Result: String 1 is equal to string 2 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_mbsnbicmp, _mbsnbicmp_l](mbsnbicmp-mbsnbicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md b/docs/c-runtime-library/reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md index 4a1b89b8e3..667ca6c6b9 100644 --- a/docs/c-runtime-library/reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md +++ b/docs/c-runtime-library/reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbico title: "_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l" ms.date: "4/2/2020" api_name: ["_mbsnbicoll_l", "_mbsnbcoll_l", "_mbsnbcoll", "_mbsnbicoll", "_o__mbsnbcoll", "_o__mbsnbcoll_l", "_o__mbsnbicoll", "_o__mbsnbicoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbsnbcoll", "_mbsnbcoll_l", "_mbsnbicoll", "mbsnbcoll_l"] helpviewer_keywords: ["_mbsnbcoll_l function", "mbsnbcoll_l function", "_mbsnbcoll function", "_tcsnicoll function", "mbsnbcoll function", "mbsnbicoll_l function", "mbsnbicoll function", "_tcsncoll function", "_mbsnbicoll function", "_mbsnbicoll_l function", "_tcsncoll_l function", "_tcsnicoll_l function"] ms.assetid: d139ed63-ccba-4458-baa2-61cbcef03e94 --- -# _mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l +# `_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l` -Compares *n* bytes of two multibyte-character strings by using multibyte code-page information. +Compares *`n`* bytes of two multibyte-character strings by using multibyte code-page information. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -46,65 +46,65 @@ int _mbsnbicoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Strings to compare. -*count*
+*`count`*\ Number of bytes to compare. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -The return value indicates the relation of the substrings of *string1* and *string2*. +The return value indicates the relation of the substrings of *`string1`* and *`string2`*. -|Return value|Description| -|------------------|-----------------| -|< 0|*string1* substring less than *string2* substring.| -|0|*string1* substring identical to *string2* substring.| -|> 0|*string1* substring greater than *string2* substring.| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring less than *`string2`* substring. | +| 0 | *`string1`* substring identical to *`string2`* substring. | +| > 0 | *`string1`* substring greater than *`string2`* substring. | -If *string1* or *string2* is **NULL** or *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. To use **_NLSCMPERROR**, include either String.h or Mbstring.h. +If *`string1`* or *`string2`* is `NULL` or *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. To use `_NLSCMPERROR`, include either String.h or Mbstring.h. ## Remarks -Each of these functions collates, at most, the first *count* bytes in *string1* and *string2* and returns a value indicating the relationship between the resulting substrings of *string1* and *string2*. If the final byte in the substring of *string1* or *string2* is a lead byte, it is not included in the comparison; these functions compare only complete characters in the substrings. **_mbsnbicoll** is a case-insensitive version of **_mbsnbcoll**. Like [_mbsnbcmp](mbsnbcmp-mbsnbcmp-l.md) and [_mbsnbicmp](mbsnbicmp-mbsnbicmp-l.md), **_mbsnbcoll** and **_mbsnbicoll** collate the two multibyte-character strings according to the lexicographic order specified by the multibyte [code page](../../c-runtime-library/code-pages.md) currently in use. +Each of these functions collates, at most, the first *`count`* bytes in *`string1`* and *`string2`* and returns a value indicating the relationship between the resulting substrings of *`string1`* and *`string2`*. If the final byte in the substring of *`string1`* or *`string2`* is a lead byte, it isn't included in the comparison; these functions compare only complete characters in the substrings. **`_mbsnbicoll`** is a case-insensitive version of **`_mbsnbcoll`**. Like [`_mbsnbcmp`](mbsnbcmp-mbsnbcmp-l.md) and [`_mbsnbicmp`](mbsnbicmp-mbsnbicmp-l.md), **`_mbsnbcoll`** and **`_mbsnbicoll`** collate the two multibyte-character strings according to the lexicographic order specified by the multibyte [code page](../code-pages.md) currently in use. -For some code pages and corresponding character sets, the order of characters in the character set might differ from the lexicographic character order. In the "C" locale, this is not the case: the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison of strings by bytes in such an instance, use **_mbsnbcoll** rather than **_mbsnbcmp**; to check only for string equality, use **_mbsnbcmp**. +For some code pages and corresponding character sets, the order of characters in the character set might differ from the lexicographic character order. In the "C" locale, the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison of strings by bytes in such an instance, use **`_mbsnbcoll`** rather than `_mbsnbcmp`; to check only for string equality, use `_mbsnbcmp`. -Because the **coll** functions collate strings lexicographically for comparison, whereas the **cmp** functions simply test for string equality, the **coll** functions are much slower than the corresponding **cmp** versions. Therefore, the **coll** functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the comparison. +Because the `coll` functions collate strings lexicographically for comparison, whereas the `cmp` functions simply test for string equality, the `coll` functions are much slower than the corresponding `cmp` versions. Therefore, the `coll` functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the comparison. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsncoll**|[_strncoll](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|**_mbsnbcoll**|[_wcsncoll](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)| -|**_tcsncoll_l**|[_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|**_mbsnbcoll_l**|[_wcsncoll_l](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)| -|**_tcsnicoll**|[_strnicoll](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|**_mbsnbicoll**|[_wcsnicoll](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)| -|**_tcsnicoll_l**|[_strnicoll_l](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|**_mbsnbicoll_l**|[_wcsnicoll_l](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncoll` | [`_strncoll`](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | **`_mbsnbcoll`** | [`_wcsncoll`](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | +| `_tcsncoll_l` | [`_strncoll_l`](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | **`_mbsnbcoll_l`** | [`_wcsncoll_l`](strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | +| `_tcsnicoll` | [`_strnicoll`](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | **`_mbsnbicoll`** | [`_wcsnicoll`](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | +| `_tcsnicoll_l` | [`_strnicoll_l`](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | **`_mbsnbicoll_l`** | [`_wcsnicoll_l`](strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcoll**|\| -|**_mbsnbcoll_l**|\| -|**_mbsnbicoll**|\| -|**_mbsnbicoll_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcoll`** | \ | +| **`_mbsnbcoll_l`** | \ | +| **`_mbsnbicoll`** | \ | +| **`_mbsnbicoll_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md)
-[_mbsnbicmp, _mbsnbicmp_l](mbsnbicmp-mbsnbicmp-l.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md b/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md index b82f2d22de..6aed00467a 100644 --- a/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md +++ b/docs/c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbsnbcpy, _mbsnbcpy_l" title: "_mbsnbcpy, _mbsnbcpy_l" ms.date: "4/2/2020" api_name: ["_mbsnbcpy", "_mbsnbcpy_l", "_o__mbsnbcpy", "_o__mbsnbcpy_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbcpy", "_mbsnbcpy", "mbsnbcpy_l", "_mbsnbcpy_l"] helpviewer_keywords: ["mbsnbcpy function", "_mbsnbcpy_l function", "_mbsnbcpy function", "_tcsncpy function", "tcsncpy_l function", "_tcsncpy_l function", "mbsnbcpy_l function", "tcsncpy function"] ms.assetid: 83d17b50-3cbf-4df9-bce8-3b6d52f85d04 --- -# _mbsnbcpy, _mbsnbcpy_l +# `_mbsnbcpy`, `_mbsnbcpy_l` -Copies **n** bytes of a string to a destination string. More secure versions of these functions are available—see [_mbsnbcpy_s, _mbsnbcpy_s_l](mbsnbcpy-s-mbsnbcpy-s-l.md). +Copies **n** bytes of a string to a destination string. More secure versions of these functions are available—see [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](mbsnbcpy-s-mbsnbcpy-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -48,58 +48,58 @@ unsigned char * _mbsnbcpy_l( ### Parameters -*strDest*
+*`strDest`*\ Destination for the character string to be copied. -*strSource*
+*`strSource`*\ Character string to be copied. -*count*
+*`count`*\ Number of bytes to be copied. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsnbcpy** returns a pointer to the destination character string. No return value is reserved to indicate an error. +**`_mbsnbcpy`** returns a pointer to the destination character string. No return value is reserved to indicate an error. ## Remarks -The **_mbsnbcpy** function copies *count* bytes from *strSource* to *strDest*. If *count* exceeds the size of *strDest* or the source and destination strings overlap, the behavior of **_mbsnbcpy** is undefined. +The **`_mbsnbcpy`** function copies *`count`* bytes from *`strSource`* to *`strDest`*. If *`count`* exceeds the size of *`strDest`* or the source and destination strings overlap, the behavior of **`_mbsnbcpy`** is undefined. -If *strSource* or *strDest* is a null pointer, this function invokes the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **NULL** and sets **errno** to **EINVAL**. +If *`strSource`* or *`strDest`* is a null pointer, this function invokes the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that those that don't have the **_l** suffix use the current locale and the versions that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale and the versions that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used to execute arbitrary attacker code, which can cause an unwarranted elevation of privilege and compromise the system. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used to execute arbitrary attacker code, which can cause an unwarranted elevation of privilege and compromise the system. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsncpy**|[strncpy](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)|**_mbsnbcpy**|[wcsncpy](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)| -|**_tcsncpy_l**|**_strncpy_l**|**_mbsnbcp_l**|**_wcsncpy_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy` | [`strncpy`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) | **`_mbsnbcpy`** | [`wcsncpy`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) | +| `_tcsncpy_l` | `_strncpy_l` | **`_mbsnbcp_l`** | `_wcsncpy_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcpy**|\| -|**_mbsnbcpy_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcpy`** | \ | +| **`_mbsnbcpy_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md)
-[_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md b/docs/c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md index ff4b5398c7..e04964f294 100644 --- a/docs/c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md +++ b/docs/c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbsnbcpy_s, _mbsnbcpy_s_l" title: "_mbsnbcpy_s, _mbsnbcpy_s_l" ms.date: "4/2/2020" api_name: ["_mbsnbcpy_s_l", "_mbsnbcpy_s", "_o__mbsnbcpy_s", "_o__mbsnbcpy_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbcpy_s_l", "_mbsnbcpy_s", "mbsnbcpy_s", "_mbsnbcpy_s_l"] helpviewer_keywords: ["_mbsnbcpy_s function", "tcsncpy_s function", "mbsnbcpy_s_l function", "_tcsncpy_s_l function", "mbsnbcpy_s function", "tcsncpy_s_l function", "_mbsnbcpy_s_l function", "_tcsncpy_s function"] ms.assetid: dfff64ab-fe6f-49c4-99ba-75014e2b0cd6 --- -# _mbsnbcpy_s, _mbsnbcpy_s_l +# `_mbsnbcpy_s`, `_mbsnbcpy_s_l` -Copies **n** bytes of a string to a destination string. These versions of [_mbsnbcpy, _mbsnbcpy_l](mbsnbcpy-mbsnbcpy-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies **n** bytes of a string to a destination string. These versions of [`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -50,62 +50,62 @@ errno_t _mbsnbcpy_s_l( ### Parameters -*strDest*
+*`strDest`*\ Destination for character string to be copied. -*sizeInBytes*
+*`sizeInBytes`*\ Destination buffer size. -*strSource*
+*`strSource`*\ Character string to be copied. -*count*
+*`count`*\ Number of bytes to be copied. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Zero if successful; **EINVAL** if a bad parameter was passed in. +Zero if successful; `EINVAL` if a bad parameter was passed in. ## Remarks -The **_mbsnbcpy_s** function copies *count* bytes from *strSource* to *strDest*. If *count* exceeds the size of *strDest*, either of the input strings is a null pointer, or *sizeInBytes* or *count* is 0, the function invokes the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns **EINVAL**. If the source and destination strings overlap, the behavior of **_mbsnbcpy_s** is undefined. +The **`_mbsnbcpy_s`** function copies *`count`* bytes from *`strSource`* to *`strDest`*. If *`count`* exceeds the size of *`strDest`*, either of the input strings is a null pointer, or *`sizeInBytes`* or *`count`* is 0, the function invokes the invalid parameter handler as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns `EINVAL`. If the source and destination strings overlap, the behavior of **`_mbsnbcpy_s`** is undefined. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). > [!NOTE] -> Unlike the non-secure version of this function, **_mbsnbcpy_s** does not do any null padding and always null terminates the string. +> Unlike the non-secure version of this function, **`_mbsnbcpy_s`** does not do any null padding and always null terminates the string. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsncpy_s**|**_strncpy_s**|**_mbsnbcpy_s**|**_wcsncpy_s**| -|**_tcsncpy_s_l**|**_strncpy_s_l**|**_mbsnbcpy_s_l**|**_wcsncpy_s_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy_s` | `_strncpy_s` | **`_mbsnbcpy_s`** | `_wcsncpy_s` | +| `_tcsncpy_s_l` | `_strncpy_s_l` | **`_mbsnbcpy_s_l`** | `_wcsncpy_s_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcpy_s**|\| -|**_mbsnbcpy_s_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcpy_s`** | \ | +| **`_mbsnbcpy_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md)
-[_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)
-[_mbsnbicmp, _mbsnbicmp_l](mbsnbicmp-mbsnbicmp-l.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md b/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md index 05b06aa23d..0144586281 100644 --- a/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md +++ b/docs/c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _mbsnbicmp, _mbsnbicmp_l" title: "_mbsnbicmp, _mbsnbicmp_l" ms.date: "4/2/2020" api_name: ["_mbsnbicmp_l", "_mbsnbicmp", "_o__mbsnbicmp", "_o__mbsnbicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbsnbicmp", "mbsnbicmp", "mbsnbicmp_l", "_mbsnbicmp_l"] helpviewer_keywords: ["_tcsnicmp_l function", "_strnicmp function", "mbsnbicmp_l function", "_wcsnicmp_l function", "_mbsnbicmp function", "_mbsnbicmp_l function", "_tcsnicmp function", "_strnicmp_l function", "mbsnbicmp function", "_wcsnicmp function"] ms.assetid: ddb44974-8b0c-42f0-90d0-56c9350bae0c --- -# _mbsnbicmp, _mbsnbicmp_l +# `_mbsnbicmp`, `_mbsnbicmp_l` Compares **n** bytes of two multibyte-character strings, and ignores case. @@ -29,60 +29,60 @@ int _mbsnbicmp( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*count*
+*`count`*\ Number of bytes to compare. -## Return Value +## Return value The return value indicates the relationship between the substrings. -|Return value|Description| -|------------------|-----------------| -|< 0|*string1* substring less than *string2* substring.| -|0|*string1* substring identical to *string2* substring.| -|> 0|*string1* substring greater than *string2* substring.| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring less than *`string2`* substring. | +| 0 | *`string1`* substring identical to *`string2`* substring. | +| > 0 | *`string1`* substring greater than *`string2`* substring. | -On an error, **_mbsnbicmp** returns **_NLSCMPERROR**, which is defined in String.h and Mbstring.h. +On an error, **`_mbsnbicmp`** returns `_NLSCMPERROR`, which is defined in String.h and Mbstring.h. ## Remarks -The **_mbsnbicmp** function performs an ordinal comparison of at most the first *count* bytes of *string1* and *string2*. The comparison is performed by converting each character to lowercase; [_mbsnbcmp](mbsnbcmp-mbsnbcmp-l.md) is a case-sensitive version of **_mbsnbicmp**. The comparison ends if a terminating null character is reached in either string before *count* characters are compared. If the strings are equal when a terminating null character is reached in either string before *count* characters are compared, the shorter string is lesser. +The **`_mbsnbicmp`** function performs an ordinal comparison of at most the first *`count`* bytes of *`string1`* and *`string2`*. The comparison is performed by converting each character to lowercase; [`_mbsnbcmp`](mbsnbcmp-mbsnbcmp-l.md) is a case-sensitive version of **`_mbsnbicmp`**. The comparison ends if a terminating null character is reached in either string before *`count`* characters are compared. If the strings are equal when a terminating null character is reached in either string before *`count`* characters are compared, the shorter string is lesser. -**_mbsnbicmp** is similar to [_mbsnbcmp](mbsnbcmp-mbsnbcmp-l.md), except that it compares strings up to *count* bytes instead of by characters. +**`_mbsnbicmp`** is similar to [`_mbsnbcmp`](mbsnbcmp-mbsnbcmp-l.md), except that it compares strings up to *`count`* bytes instead of by characters. -Two strings containing characters located between 'Z' and 'a' in the ASCII table ('[', '\\', ']', '^', '_', and '\`') compare differently, depending on their case. For example, the two strings "ABCDE" and "ABCD^" compare one way if the comparison is lowercase ("abcde" > "abcd^") and the other way ("ABCDE" < "ABCD^") if it is uppercase. +Two strings containing characters located between 'Z' and 'a' in the ASCII table ('[', '\\', ']', '^', '_', and '\`') compare differently, depending on their case. For example, the two strings "ABCDE" and "ABCD^" compare one way if the comparison is lowercase ("abcde" > "abcd^") and the other way ("ABCDE" < "ABCD^") if it's uppercase. -**_mbsnbicmp** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. It is not affected by the current locale setting. +**`_mbsnbicmp`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. It isn't affected by the current locale setting. -If either *string1* or *string2* is a null pointer, **_mbsnbicmp** invokes the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **_NLSCMPERROR** and sets **errno** to **EINVAL**. +If either *`string1`* or *`string2`* is a null pointer, **`_mbsnbicmp`** invokes the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `_NLSCMPERROR` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnicmp**|**_strnicmp**|**_mbsnbicmp**|**_wcsnicmp**| -|**_tcsnicmp_l**|**_strnicmp_l**|**_mbsnbicmp_l**|**_wcsnicmp_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnicmp` | `_strnicmp` | **`_mbsnbicmp`** | `_wcsnicmp` | +| `_tcsnicmp_l` | `_strnicmp_l` | **`_mbsnbicmp_l`** | `_wcsnicmp_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbicmp**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbicmp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md). +See the example for [`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_mbsnbcmp, _mbsnbcmp_l](mbsnbcmp-mbsnbcmp-l.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md b/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md index f4f20bdd4e..1a84efa6e2 100644 --- a/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md +++ b/docs/c-runtime-library/reference/mbsnbset-mbsnbset-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _mbsnbset, _mbsnbset_l" title: "_mbsnbset, _mbsnbset_l" ms.date: "4/2/2020" api_name: ["_mbsnbset", "_mbsnbset_l", "_o__mbsnbset", "_o__mbsnbset_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbset", "mbsnbset_l", "_mbsnbset", "_mbsnbset_l"] helpviewer_keywords: ["tcsnset function", "_tcsnset_l function", "_mbsnbset function", "_tcsnset function", "_mbsnbset_l function", "mbsnbset_l function", "tcsnset_l function", "mbsnbset function"] ms.assetid: 8e46ef75-9a56-42d2-a522-a08450c67c19 --- -# _mbsnbset, _mbsnbset_l +# `_mbsnbset`, `_mbsnbset_l` -Sets the first **n** bytes of a multibyte-character string to a specified character. More secure versions of these functions are available; see [_mbsnbset_s, _mbsnbset_s_l](mbsnbset-s-mbsnbset-s-l.md). +Sets the first **n** bytes of a multibyte-character string to a specified character. More secure versions of these functions are available; see [`_mbsnbset_s`, `_mbsnbset_s_l`](mbsnbset-s-mbsnbset-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -35,51 +35,51 @@ unsigned char *_mbsnbset_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*c*
+*`c`*\ Single-byte or multibyte-character setting. -*count*
+*`count`*\ Number of bytes to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsnbset** returns a pointer to the altered string. +**`_mbsnbset`** returns a pointer to the altered string. ## Remarks -The **_mbsnbset** and **_mbsnbset_l** functions set, at most, the first *count* bytes of *str* to *c*. If *count* is greater than the length of *str*, the length of *str* is used instead of *count*. If *c* is a multibyte character and cannot be set entirely into the last byte specified by *count*, the last byte is padded with a blank character. **_mbsnbset** and **_mbsnbset_l** does not place a terminating null at the end of *str*. +The **`_mbsnbset`** and **`_mbsnbset_l`** functions set, at most, the first *`count`* bytes of *`str`* to *`c`*. If *`count`* is greater than the length of *`str`*, the length of *`str`* is used instead of *`count`*. If *`c`* is a multibyte character and can't be set entirely into the last byte specified by *`count`*, the last byte is padded with a blank character. **`_mbsnbset`** and **`_mbsnbset_l`** doesn't place a terminating null at the end of *`str`*. -**_mbsnbset** and **_mbsnbset_l** is similar to **_mbsnset**, except that it sets *count* bytes rather than *count* characters of *c*. +**`_mbsnbset`** and **`_mbsnbset_l`** is similar to **`_mbsnset`**, except that it sets *`count`* bytes rather than *`count`* characters of *`c`*. -If *str* is **NULL** or *count* is zero, this function generates an invalid parameter exception as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. Also, if *c* is not a valid multibyte character, **errno** is set to **EINVAL** and a space is used instead. +If *`str`* is `NULL` or *`count`* is zero, this function generates an invalid parameter exception as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. Also, if *`c`* isn't a valid multibyte character, `errno` is set to `EINVAL` and a space is used instead. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The **_mbsnbset** version of this function uses the current locale for this locale-dependent behavior; the **_mbsnbset_l** version is identical except that it use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsnbset`** version of this function uses the current locale for this locale-dependent behavior; the **`_mbsnbset_l`** version is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnset**|**_strnset**|**_mbsnbset**|**_wcsnset**| -|**_tcsnset_l**|**_strnset_l**|**_mbsnbset_l**|**_wcsnset_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset` | `_strnset` | **`_mbsnbset`** | `_wcsnset` | +| `_tcsnset_l` | `_strnset_l` | **`_mbsnbset_l`** | `_wcsnset_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbset**|\| -|**_mbsnbset_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbset`** | \ | +| **`_mbsnbset_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -109,7 +109,7 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md b/docs/c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md index 29958debe1..9fa6a973f5 100644 --- a/docs/c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md +++ b/docs/c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _mbsnbset_s, _mbsnbset_s_l" title: "_mbsnbset_s, _mbsnbset_s_l" -ms.date: "4/2/2020" +description: "Learn more about: _mbsnbset_s, _mbsnbset_s_l" +ms.date: 4/2/2020 api_name: ["_mbsnbset_s_l", "_mbsnbset_s", "_o__mbsnbset_s", "_o__mbsnbset_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsnbset_s", "_mbsnbset_s_l", "_mbsnbset_s", "mbsnbset_s_l"] helpviewer_keywords: ["tcsnset_s function", "mbsnbset_s function", "mbsnbset_s_l function", "_mbsnbset_s_l function", "_tcsnset_s_l function", "_mbsnbset_s function", "_tcsnset_s function", "tcsnset_s_l function"] -ms.assetid: 811f92c9-cc31-4bbd-8017-2d1bfc6fb96f --- -# _mbsnbset_s, _mbsnbset_s_l +# `_mbsnbset_s`, `_mbsnbset_s_l` -Sets the first **n** bytes of a multibyte-character string to a specified character. These versions of [_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Sets the first **n** bytes of a multibyte-character string to a specified character. These versions of [`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -50,56 +49,56 @@ errno_t _mbsnbset_s_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*size*
+*`size`*\ The size of the string buffer. -*c*
+*`c`*\ Single-byte or multibyte-character setting. -*count*
+*`count`*\ Number of bytes to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; otherwise, an error code. ## Remarks -The **_mbsnbset_s** and **_mbsnbset_s_l** functions set, at most, the first *count* bytes of *str* to *c*. If *count* is greater than the length of *str*, the length of *str* is used instead of *count*. If *c* is a multibyte character and cannot be set entirely into the last byte that's specified by *count*, the last byte is padded with a blank character. **_mbsnbset_s** and **_mbsnbset_s_l** do not place a terminating null at the end of *str*. +The **`_mbsnbset_s`** and **`_mbsnbset_s_l`** functions set, at most, the first *`count`* bytes of *`str`* to *`c`*. If *`count`* is greater than the length of *`str`*, the length of *`str`* is used instead of *`count`*. If *`c`* is a multibyte character and can't be set entirely into the last byte that's specified by *`count`*, the last byte is padded with a blank character. **`_mbsnbset_s`** and **`_mbsnbset_s_l`** don't place a terminating null at the end of *`str`*. -**_mbsnbset_s** and **_mbsnbset_s_l** resemble **_mbsnset**, except that they set *count* bytes rather than *count* characters of *c*. +**`_mbsnbset_s`** and **`_mbsnbset_s_l`** resemble `_mbsnset`, except that they set *`count`* bytes rather than *`count`* characters of *`c`*. -If *str* is **NULL** or *count* is zero, this function generates an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. Also, if *c* is not a valid multibyte character, **errno** is set to **EINVAL** and a space is used instead. +If *`str`* is `NULL` or *`count`* is zero, this function generates an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. Also, if *`c`* isn't a valid multibyte character, `errno` is set to `EINVAL` and a space is used instead. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The **_mbsnbset_s** version of this function uses the current locale for this locale-dependent behavior; the **_mbsnbset_s_l** version is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsnbset_s`** version of this function uses the current locale for this locale-dependent behavior; the **`_mbsnbset_s_l`** version is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnset_s**|**_strnset_s**|**_mbsnbset_s**|**_wcsnset_s**| -|**_tcsnset_s_l**|`_strnset_s _l`|**_mbsnbset_s_l**|**_wcsnset_s_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset_s` | `_strnset_s` | **`_mbsnbset_s`** | `_wcsnset_s` | +| `_tcsnset_s_l` | `_strnset_s_l` | **`_mbsnbset_s_l`** | `_wcsnset_s_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbset_s**|\| -|**_mbsnbset_s_l**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbset_s`** | `` | +| **`_mbsnbset_s_l`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -127,7 +126,7 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/mbsrtowcs-s.md b/docs/c-runtime-library/reference/mbsrtowcs-s.md index d9fb029546..1146d7229b 100644 --- a/docs/c-runtime-library/reference/mbsrtowcs-s.md +++ b/docs/c-runtime-library/reference/mbsrtowcs-s.md @@ -3,16 +3,16 @@ description: "Learn more about: mbsrtowcs_s" title: "mbsrtowcs_s" ms.date: "4/2/2020" api_name: ["mbsrtowcs_s", "_o_mbsrtowcs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsrtowcs_s"] helpviewer_keywords: ["mbsrtowcs_s function"] ms.assetid: 4ee084ec-b15d-4e5a-921d-6584ec3b5a60 --- -# mbsrtowcs_s +# `mbsrtowcs_s` -Convert a multibyte character string in the current locale to its wide character string representation. A version of [mbsrtowcs](mbsrtowcs.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a multibyte character string in the current locale to its wide character string representation. A version of [`mbsrtowcs`](mbsrtowcs.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,86 +37,86 @@ errno_t mbsrtowcs_s( ### Parameters -*pReturnValue*
+*`pReturnValue`*\ The number of characters converted. -*wcstr*
+*`wcstr`*\ Address of buffer to store the resulting converted wide character string. -*sizeInWords*
-The size of *wcstr* in words (wide characters). +*`sizeInWords`*\ +The size of *`wcstr`* in words (wide characters). -*mbstr*
+*`mbstr`*\ Indirect pointer to the location of the multibyte character string to be converted. -*count*
-The maximum number of wide characters to store in the *wcstr* buffer, not including the terminating null, or [_TRUNCATE](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of wide characters to store in the *`wcstr`* buffer, not including the terminating null, or [`_TRUNCATE`](../truncate.md). -*mbstate*
-A pointer to an **mbstate_t** conversion state object. If this value is a null pointer, a static internal conversion state object is used. Because the internal **mbstate_t** object is not thread-safe, we recommend that you always pass your own *mbstate* parameter. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. If this value is a null pointer, a static internal conversion state object is used. Because the internal `mbstate_t` object isn't thread-safe, we recommend that you always pass your own *`mbstate`* parameter. -## Return Value +## Return value Zero if conversion is successful, or an error code on failure. -|Error condition|Return value and **errno**| -|---------------------|------------------------------| -|*wcstr* is a null pointer and *sizeInWords* > 0|**EINVAL**| -|*mbstr* is a null pointer|**EINVAL**| -|The string indirectly pointed to by *mbstr* contains a multibyte sequence that is not valid for the current locale.|**EILSEQ**| -|The destination buffer is too small to contain the converted string (unless *count* is **_TRUNCATE**; for more information, see Remarks)|**ERANGE**| +| Error condition | Return value and `errno` | +|---|---| +| *`wcstr`* is a null pointer and *`sizeInWords`* > 0 | `EINVAL` | +| *`mbstr`* is a null pointer | `EINVAL` | +| The string indirectly pointed to by *`mbstr`* contains a multibyte sequence that isn't valid for the current locale. | `EILSEQ` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; for more information, see Remarks) | `ERANGE` | -If any one of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets **errno** as indicated in the table. +If any one of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks -The **mbsrtowcs_s** function converts a string of multibyte characters indirectly pointed to by *mbstr* into wide characters stored in the buffer pointed to by *wcstr*, by using the conversion state contained in *mbstate*. The conversion will continue for each character until one of these conditions is met: +The **`mbsrtowcs_s`** function converts a string of multibyte characters indirectly pointed to by *`mbstr`* into wide characters stored in the buffer pointed to by *`wcstr`*, by using the conversion state contained in *`mbstate`*. The conversion will continue for each character until one of these conditions is met: - A multibyte null character is encountered - An invalid multibyte character is encountered -- The number of wide characters stored in the *wcstr* buffer equals *count*. +- The number of wide characters stored in the *`wcstr`* buffer equals *`count`*. -The destination string *wcstr* is always null-terminated, even in the case of an error, unless *wcstr* is a null pointer. +The destination string *`wcstr`* is always null-terminated, even when there's an error, unless *`wcstr`* is a null pointer. -If *count* is the special value [_TRUNCATE](../../c-runtime-library/truncate.md), **mbsrtowcs_s** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), **`mbsrtowcs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. -If **mbsrtowcs_s** successfully converts the source string, it puts the size in wide characters of the converted string and the null terminator into `*pReturnValue`, provided *pReturnValue* is not a null pointer. This occurs even if the *wcstr* argument is a null pointer and lets you determine the required buffer size. Note that if *wcstr* is a null pointer, *count* is ignored. +If **`mbsrtowcs_s`** successfully converts the source string, it puts the size in wide characters of the converted string and the null terminator into `*pReturnValue`, provided *`pReturnValue`* isn't a null pointer. The size is calculated even if the *`wcstr`* argument is a null pointer, which lets you determine the required buffer size. If *`wcstr`* is a null pointer, *`count`* is ignored. -If *wcstr* is not a null pointer, the pointer object pointed to by *mbstr* is assigned a null pointer if conversion stopped because a terminating null character was reached. Otherwise, it is assigned the address just past the last multibyte character converted, if any. This allows a subsequent function call to restart conversion where this call stopped. +If *`wcstr`* isn't a null pointer, the pointer object pointed to by *`mbstr`* is assigned a null pointer if conversion stopped because a terminating null character was reached. Otherwise, it's assigned the address just past the last multibyte character converted, if any. It allows a subsequent function call to restart conversion where this call stopped. -If *mbstate* is a null pointer, the library internal **mbstate_t** conversion state static object is used. Because this internal static object is not thread-safe, we recommend that you pass your own *mbstate* value. +If *`mbstate`* is a null pointer, the library internal `mbstate_t` conversion state static object is used. Because this internal static object isn't thread-safe, we recommend that you pass your own *`mbstate`* value. -If **mbsrtowcs_s** encounters a multibyte character that is not valid in the current locale, it puts -1 in `*pReturnValue`, sets the destination buffer *wcstr* to an empty string, sets **errno** to **EILSEQ**, and returns **EILSEQ**. +If **`mbsrtowcs_s`** encounters a multibyte character that isn't valid in the current locale, it puts -1 in `*pReturnValue`, sets the destination buffer *`wcstr`* to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. -If the sequences pointed to by *mbstr* and *wcstr* overlap, the behavior of **mbsrtowcs_s** is undefined. **mbsrtowcs_s** is affected by the LC_TYPE category of the current locale. +If the sequences pointed to by *`mbstr`* and *`wcstr`* overlap, the behavior of **`mbsrtowcs_s`** is undefined. **`mbsrtowcs_s`** is affected by the `LC_TYPE` category of the current locale. > [!IMPORTANT] -> Ensure that *wcstr* and *mbstr* do not overlap, and that *count* correctly reflects the number of multibyte characters to convert. +> Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of multibyte characters to convert. -The **mbsrtowcs_s** function differs from [mbstowcs_s, _mbstowcs_s_l](mbstowcs-s-mbstowcs-s-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use **mbsrlen** instead of **mbslen**, if a subsequent call to **mbsrtowcs_s** is used instead of **mbstowcs_s**. +The **`mbsrtowcs_s`** function differs from [`mbstowcs_s`, `_mbstowcs_s_l`](mbstowcs-s-mbstowcs-s-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use `mbsrlen` instead of `mbslen`, if a subsequent call to **`mbsrtowcs_s`** is used instead of **`mbstowcs_s`**. -In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the requirement to specify a size argument) and they can automatically replace older, non-secure functions by using their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the requirement to specify a size argument) and they can automatically replace older, non-secure functions by using the newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **mbsrtowcs_s** function is multithread safe if no function in the current thread calls **setlocale** as long as this function is executing and the *mbstate* argument is not a null pointer. +The **`mbsrtowcs_s`** function is multithread safe if no function in the current thread calls `setlocale` as long as this function is executing and the *`mbstate`* argument isn't a null pointer. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbsrtowcs_s**|\| +| Routine | Required header | +|---|---| +| **`mbsrtowcs_s`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbrtowc](mbrtowc.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[mbstowcs_s, _mbstowcs_s_l](mbstowcs-s-mbstowcs-s-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbrtowc`](mbrtowc.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`mbstowcs_s`, `_mbstowcs_s_l`](mbstowcs-s-mbstowcs-s-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/mbsrtowcs.md b/docs/c-runtime-library/reference/mbsrtowcs.md index ad04fd33e6..7d9e232b4f 100644 --- a/docs/c-runtime-library/reference/mbsrtowcs.md +++ b/docs/c-runtime-library/reference/mbsrtowcs.md @@ -3,16 +3,16 @@ description: "Learn more about: mbsrtowcs" title: "mbsrtowcs" ms.date: "4/2/2020" api_name: ["mbsrtowcs", "_o_mbsrtowcs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsrtowcs"] helpviewer_keywords: ["mbsrtowcs function"] ms.assetid: f3a29de8-e36e-425b-a7fa-a258e6d7909d --- -# mbsrtowcs +# `mbsrtowcs` -Converts a multibyte character string in the current locale to a corresponding wide character string, with the capability of restarting in the middle of a multibyte character. A more secure version of this function is available; see [mbsrtowcs_s](mbsrtowcs-s.md). +Converts a multibyte character string in the current locale to a corresponding wide character string, with the capability of restarting in the middle of a multibyte character. A more secure version of this function is available; see [`mbsrtowcs_s`](mbsrtowcs-s.md). ## Syntax @@ -34,56 +34,56 @@ size_t mbsrtowcs( ### Parameters -*wcstr*
+*`wcstr`*\ Address to store the resulting converted wide character string. -*mbstr*
+*`mbstr`*\ Indirect pointer to the location of the multibyte character string to convert. -*count*
-The maximum number of characters (not bytes) to convert and store in *wcstr*. +*`count`*\ +The maximum number of characters (not bytes) to convert and store in *`wcstr`*. -*mbstate*
-A pointer to an **mbstate_t** conversion state object. If this value is a null pointer, a static internal conversion state object is used. Because the internal **mbstate_t** object is not thread-safe, we recommend that you always pass your own *mbstate* parameter. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. If this value is a null pointer, a static internal conversion state object is used. Because the internal `mbstate_t` object isn't thread-safe, we recommend that you always pass your own *`mbstate`* parameter. -## Return Value +## Return value -Returns the number of characters successfully converted, not including the terminating null character, if any. Returns (size_t)(-1) if an error occurred, and sets **errno** to EILSEQ. +Returns the number of characters successfully converted, not including the terminating null character, if any. Returns (size_t)(-1) if an error occurred, and sets `errno` to `EILSEQ`. ## Remarks -The **mbsrtowcs** function converts a string of multibyte characters indirectly pointed to by *mbstr*, into wide characters stored in the buffer pointed to by *wcstr*, by using the conversion state contained in *mbstate*. The conversion continues for each character until either a terminating null multibyte character is encountered, a multibyte sequence that does not correspond to a valid character in the current locale is encountered, or until *count* characters have been converted. If **mbsrtowcs** encounters the multibyte null character ('\0') either before or when *count* occurs, it converts it to a 16-bit terminating null character and stops. +The **`mbsrtowcs`** function converts a string of multibyte characters indirectly pointed to by *`mbstr`*, into wide characters stored in the buffer pointed to by *`wcstr`*, by using the conversion state contained in *`mbstate`*. The conversion continues for each character until either a terminating null multibyte character is encountered, a multibyte sequence that doesn't correspond to a valid character in the current locale is encountered, or until *`count`* characters have been converted. If **`mbsrtowcs`** encounters the multibyte null character ('\0') either before or when *`count`* occurs, it converts it to a 16-bit terminating null character and stops. -Thus, the wide character string at *wcstr* is null-terminated only if **mbsrtowcs** encounters a multibyte null character during conversion. If the sequences pointed to by *mbstr* and *wcstr* overlap, the behavior of **mbsrtowcs** is undefined. **mbsrtowcs** is affected by the LC_TYPE category of the current locale. +Thus, the wide character string at *`wcstr`* is null-terminated only if **`mbsrtowcs`** encounters a multibyte null character during conversion. If the sequences pointed to by *`mbstr`* and *`wcstr`* overlap, the behavior of **`mbsrtowcs`** is undefined. **`mbsrtowcs`** is affected by the `LC_TYPE` category of the current locale. -The **mbsrtowcs** function differs from [mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use **mbsrlen** instead of **mbslen**, if a subsequent call to **mbsrtowcs** is used instead of **mbstowcs**. +The **`mbsrtowcs`** function differs from [`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use `mbsrlen` instead of `mbslen`, if a subsequent call to **`mbsrtowcs`** is used instead of `mbstowcs`. -If *wcstr* is not a null pointer, the pointer object pointed to by *mbstr* is assigned a null pointer if conversion stopped because a terminating null character was reached. Otherwise, it is assigned the address just past the last multibyte character converted, if any. This allows a subsequent function call to restart conversion where this call stopped. +If *`wcstr`* isn't a null pointer, the pointer object pointed to by *`mbstr`* is assigned a null pointer if conversion stopped because a terminating null character was reached. Otherwise, it's assigned the address just past the last multibyte character converted, if any. It allows a subsequent function call to restart conversion where this call stopped. -If the *wcstr* argument is a null pointer, the *count* argument is ignored and **mbsrtowcs** returns the required size in wide characters for the destination string. If *mbstate* is a null pointer, the function uses a non-thread-safe static internal **mbstate_t** conversion state object. If the character sequence *mbstr* does not have a corresponding multibyte character representation, a -1 is returned and the **errno** is set to **EILSEQ**. +If the *`wcstr`* argument is a null pointer, the *`count`* argument is ignored, and **`mbsrtowcs`** returns the required size in wide characters for the destination string. If *`mbstate`* is a null pointer, the function uses a non-thread-safe static internal `mbstate_t` conversion state object. If the character sequence *`mbstr`* doesn't have a corresponding multibyte character representation, a -1 is returned, and `errno` is set to `EILSEQ`. -If *mbstr* isa null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns -1. +If *`mbstr`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns -1. -In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **mbsrtowcs** function is multithread safe as long as no function in the current thread calls **setlocale** as long as this function is executing and the *mbstate* argument is not a null pointer. +The **`mbsrtowcs`** function is multithread safe as long as no function in the current thread calls `setlocale` as long as this function is executing and the *`mbstate`* argument isn't a null pointer. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbsrtowcs**|\| +| Routine | Required header | +|---|---| +| **`mbsrtowcs`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbrtowc](mbrtowc.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbrtowc`](mbrtowc.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md b/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md index d6417b1378..3a81ca0571 100644 --- a/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md +++ b/docs/c-runtime-library/reference/mbstowcs-mbstowcs-l.md @@ -3,16 +3,15 @@ description: "Learn more about: mbstowcs, _mbstowcs_l" title: "mbstowcs, _mbstowcs_l" ms.date: "4/2/2020" api_name: ["mbstowcs", "_mbstowcs_l", "_o__mbstowcs_l", "_o_mbstowcs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbstowcs"] helpviewer_keywords: ["_mbstowcs_l function", "mbstowcs_l function", "mbstowcs function"] -ms.assetid: 96696b27-e068-4eeb-8006-3f7a0546ae6d --- -# mbstowcs, _mbstowcs_l +# `mbstowcs`, `_mbstowcs_l` -Converts a sequence of multibyte characters to a corresponding sequence of wide characters. More secure versions of these functions are available; see [mbstowcs_s, _mbstowcs_s_l](mbstowcs-s-mbstowcs-s-l.md). +Converts a sequence of multibyte characters to a corresponding sequence of wide characters. More secure versions of these functions are available; see [`mbstowcs_s`, `_mbstowcs_s_l`](mbstowcs-s-mbstowcs-s-l.md). ## Syntax @@ -45,47 +44,47 @@ size_t _mbstowcs_l( ### Parameters -*wcstr*
+*`wcstr`*\ The address of a sequence of wide characters. -*mbstr*
+*`mbstr`*\ The address of a sequence of null terminated multibyte characters. -*count*
+*`count`*\ The maximum number of multibyte characters to convert. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -If **mbstowcs** successfully converts the source string, it returns the number of converted multibyte characters. If the *wcstr* argument is **NULL**, the function returns the required size (in wide characters) of the destination string. If **mbstowcs** encounters an invalid multibyte character, it returns -1. If the return value is *count*, the wide-character string is not null-terminated. +If **`mbstowcs`** successfully converts the source string, it returns the number of converted multibyte characters. If the *`wcstr`* argument is `NULL`, the function returns the required size (in wide characters) of the destination string. If **`mbstowcs`** encounters an invalid multibyte character, it returns -1. If the return value is *`count`*, the wide-character string isn't null-terminated. > [!IMPORTANT] -> Ensure that *wcstr* and *mbstr* do not overlap, and that *count* correctly reflects the number of multibyte characters to convert. +> Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of multibyte characters to convert. ## Remarks -The **mbstowcs** function converts up to a maximum number of *count* multibyte characters pointed to by *mbstr* to a string of corresponding wide characters that are determined by the current locale. It stores the resulting wide-character string at the address represented by *wcstr*. The result is similar to a series of calls to [mbtowc](mbtowc-mbtowc-l.md). If **mbstowcs** encounters the single-byte null character ('\0') either before or when *count* occurs, it converts the null character to a wide-character null character (L'\0') and stops. Thus the wide-character string at *wcstr* is null-terminated only if a null character is encountered during conversion. If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior is undefined. +The **`mbstowcs`** function converts up to a maximum number of *`count`* multibyte characters pointed to by *`mbstr`* to a string of corresponding wide characters that are determined by the current locale. It stores the resulting wide-character string at the address represented by *`wcstr`*. The result is similar to a series of calls to [`mbtowc`](mbtowc-mbtowc-l.md). If **`mbstowcs`** encounters the single-byte null character ('\0') either before or when *`count`* occurs, it converts the null character to a wide-character null character (`L'\0'`) and stops. Thus the wide-character string at *`wcstr`* is null-terminated only if a null character is encountered during conversion. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior is undefined. -If the *wcstr* argument is **NULL**, **mbstowcs** returns the number of wide characters that would result from conversion, not including a null terminator. The source string must be null-terminated for the correct value to be returned. If you need the resulting wide character string to be null-terminated, add one to the returned value. +If the *`wcstr`* argument is `NULL`, **`mbstowcs`** returns the number of wide characters that would result from conversion, not including a null terminator. The source string must be null-terminated for the correct value to be returned. If you need the resulting wide character string to be null-terminated, add one to the returned value. -If the *mbstr* argument is **NULL**, or if *count* is > **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, errno is set to **EINVAL** and the function returns -1. +If the *`mbstr`* argument is `NULL`, or if *`count`* is > `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns -1. -**mbstowcs** uses the current locale for any locale-dependent behavior; **_mbstowcs_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`mbstowcs`** uses the current locale for any locale-dependent behavior; **`_mbstowcs_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbstowcs**|\| -|**_mbstowcs_l**|\| +| Routine | Required header | +|---|---| +| **`mbstowcs`** | `` | +| **`_mbstowcs_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -184,11 +183,11 @@ Convert back to wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[MultiByteToWideChar](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) diff --git a/docs/c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md b/docs/c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md index 372059e220..1518d807c2 100644 --- a/docs/c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md +++ b/docs/c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md @@ -3,7 +3,7 @@ description: "Learn more about: mbstowcs_s, _mbstowcs_s_l" title: "mbstowcs_s, _mbstowcs_s_l" ms.date: "4/2/2020" api_name: ["_mbstowcs_s_l", "mbstowcs_s", "_o__mbstowcs_s_l", "_o_mbstowcs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbstowcs_s_l", "mbstowcs_s"] @@ -12,7 +12,7 @@ ms.assetid: 2fbda953-6918-498f-b440-3e7b21ed65a4 --- # `mbstowcs_s`, `_mbstowcs_s_l` -Converts a sequence of multibyte characters to a corresponding sequence of wide characters. Versions of [`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a sequence of multibyte characters to a corresponding sequence of wide characters. Versions of [`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -51,36 +51,36 @@ errno_t _mbstowcs_s_l( ### Parameters -*`pReturnValue`*
+*`pReturnValue`*\ The number of characters converted. -*`wcstr`*
+*`wcstr`*\ Address of buffer for the resulting converted wide character string. -*`sizeInWords`*
+*`sizeInWords`*\ The size of the *`wcstr`* buffer in words. -*`mbstr`*
+*`mbstr`*\ The address of a sequence of null terminated multibyte characters. -*`count`*
-The maximum number of wide characters to store in the *`wcstr`* buffer, not including the terminating null, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of wide characters to store in the *`wcstr`* buffer, not including the terminating null, or [`_TRUNCATE`](../truncate.md). -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **`errno`**| -|---------------------|------------------------------| -|*`wcstr`* is **`NULL`** and *`sizeInWords`* > 0|**`EINVAL`**| -|*`mbstr`* is **`NULL`**|**`EINVAL`**| -|The destination buffer is too small to contain the converted string (unless *`count`* is **`_TRUNCATE`**; see Remarks below)|**`ERANGE`**| -|*`wcstr`* is not **`NULL`** and *`sizeInWords`* == 0|**`EINVAL`**| +| Error condition | Return value and `errno` | +|---|---| +| *`wcstr`* is `NULL` and *`sizeInWords`* > 0 | `EINVAL` | +| *`mbstr`* is `NULL` | `EINVAL` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; see Remarks below) | `ERANGE` | +| *`wcstr`* isn't `NULL` and *`sizeInWords`* == 0 | `EINVAL` | -If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets **`errno`** as indicated in the table. +If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks @@ -92,41 +92,41 @@ The **`mbstowcs_s`** function converts a string of multibyte characters pointed - The number of wide characters stored in the *`wcstr`* buffer equals *`count`*. -The destination string is always null-terminated (even in the case of an error). +The destination string is always null-terminated (even if there's an error). -If *`count`* is the special value [`_TRUNCATE`](../../c-runtime-library/truncate.md), then **`mbstowcs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), then **`mbstowcs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. -If **`mbstowcs_s`** successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into `*pReturnValue` (provided *`pReturnValue`* is not **`NULL`**). This occurs even if the *`wcstr`* argument is **`NULL`** and provides a way to determine the required buffer size. Note that if *`wcstr`* is **`NULL`**, *count* is ignored, and *`sizeInWords`* must be 0. +If **`mbstowcs_s`** successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into `*pReturnValue` (provided *`pReturnValue`* isn't `NULL`). The size is calculated even if the *`wcstr`* argument is `NULL`, and provides a way to determine the required buffer size. If *`wcstr`* is `NULL`, *`count`* is ignored, and *`sizeInWords`* must be 0. -If **`mbstowcs_s`** encounters an invalid multibyte character, it puts 0 in `*pReturnValue`, sets the destination buffer to an empty string, sets **`errno`** to **`EILSEQ`**, and returns **`EILSEQ`**. +If **`mbstowcs_s`** encounters an invalid multibyte character, it puts 0 in `*pReturnValue`, sets the destination buffer to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. If the sequences pointed to by *`mbstr`* and *`wcstr`* overlap, the behavior of **`mbstowcs_s`** is undefined. > [!IMPORTANT] > Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of multibyte characters to convert. -**`mbstowcs_s`** uses the current locale for any locale-dependent behavior; **`_mbstowcs_s_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`mbstowcs_s`** uses the current locale for any locale-dependent behavior; **`_mbstowcs_s_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`mbstowcs_s`**|``| -|**`_mbstowcs_s_l`**|``| +| Routine | Required header | +|---|---| +| **`mbstowcs_s`** | `` | +| **`_mbstowcs_s_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)
-[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)
-[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)
-[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) diff --git a/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md b/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md index cf22d85595..87c65a7d84 100644 --- a/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md +++ b/docs/c-runtime-library/reference/mbtowc-mbtowc-l.md @@ -3,14 +3,14 @@ description: "Learn more about: mbtowc, _mbtowc_l" title: "mbtowc, _mbtowc_l" ms.date: "4/2/2020" api_name: ["mbtowc", "_mbtowc_l", "_o__mbtowc_l", "_o_mbtowc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbtowc"] helpviewer_keywords: ["mbtowc function", "_mbtowc_l function", "mbtowc_l function"] ms.assetid: dfd1c8a7-e73a-4307-9353-53b70b45d4d1 --- -# mbtowc, _mbtowc_l +# `mbtowc`, `_mbtowc_l` Convert a multibyte character to a corresponding wide character. @@ -32,40 +32,40 @@ int _mbtowc_l( ### Parameters -*wchar*
+*`wchar`*\ Address of a wide character (type **`wchar_t`**). -*mbchar*
+*`mbchar`*\ Address of a sequence of bytes (a multibyte character). -*count*
+*`count`*\ Number of bytes to check. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -If **mbchar** is not **NULL** and if the object that *mbchar* points to forms a valid multibyte character, **mbtowc** returns the length in bytes of the multibyte character. If *mbchar* is **NULL** or the object that it points to is a wide-character null character (L'\0'), the function returns 0. If the object that *mbchar* points to does not form a valid multibyte character within the first *count* characters, it returns -1. +If `mbchar` isn't `NULL`, and if *`mbchar`* points to a valid multibyte character, **`mbtowc`** returns the length in bytes of the multibyte character. If *`mbchar`* is `NULL` or points to a wide-character null character (L'\0'), the function returns 0. If the object that *`mbchar`* points to doesn't form a valid multibyte character within the first *`count`* characters, it returns -1. ## Remarks -The **mbtowc** function converts *count* or fewer bytes pointed to by *mbchar*, if *mbchar* is not **NULL**, to a corresponding wide character. **mbtowc** stores the resulting wide character at *wchar,* if *wchar* is not **NULL**. **mbtowc** does not examine more than **MB_CUR_MAX** bytes. **mbtowc** uses the current locale for locale-dependent behavior; **_mbtowc_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`mbtowc`** function converts *`count`* or fewer bytes pointed to by *`mbchar`*, if *`mbchar`* isn't `NULL`, to a corresponding wide character. **`mbtowc`** stores the resulting wide character at *wchar,* if *`wchar`* isn't `NULL`. **`mbtowc`** doesn't examine more than `MB_CUR_MAX` bytes. **`mbtowc`** uses the current locale for locale-dependent behavior; **`_mbtowc_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mbtowc**|\| -|**_mbtowc_l**|\| +| Routine | Required header | +|---|---| +| **`mbtowc`** | \ | +| **`_mbtowc_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -125,10 +125,10 @@ Attempt to convert a NULL pointer to a wide character: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[MultiByteToWideChar](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
+[Data conversion](../data-conversion.md)\ +[MultiByteToWideChar](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) diff --git a/docs/c-runtime-library/reference/memccpy.md b/docs/c-runtime-library/reference/memccpy.md index 8881065263..b742d4e784 100644 --- a/docs/c-runtime-library/reference/memccpy.md +++ b/docs/c-runtime-library/reference/memccpy.md @@ -10,7 +10,7 @@ f1_keywords: ["_memccpy"] helpviewer_keywords: ["_memccpy function", "memccpy function"] ms.assetid: 9a2337df-6e85-4eba-b247-dd0532f45ddb --- -# _memccpy +# `_memccpy` Copies characters from a buffer. @@ -27,39 +27,39 @@ void *_memccpy( ### Parameters -*dest*
+*`dest`*\ Pointer to the destination. -*src*
+*`src`*\ Pointer to the source. -*c*
+*`c`*\ Last character to copy. -*count*
+*`count`*\ Number of characters. -## Return Value +## Return value -If the character *c* is copied, **_memccpy** returns a pointer to the char in *dest* that immediately follows the character. If *c* is not copied, it returns **NULL**. +If the character *`c`* is copied, **`_memccpy`** returns a pointer to the char in *`dest`* that immediately follows the character. If *`c`* isn't copied, it returns `NULL`. ## Remarks -The **_memccpy** function copies 0 or more characters of *src* to *dest*, halting when the character *c* has been copied or when *count* characters have been copied, whichever comes first. +The **`_memccpy`** function copies zero or more characters of *`src`* to *`dest`*, halting when the character *`c`* has been copied or when *`count`* characters have been copied, whichever comes first. -**Security Note** Make sure that the destination buffer is the same size or larger than the source buffer. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** Make sure that the destination buffer is the same size or larger than the source buffer. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_memccpy**|\ or \| +| Routine | Required header | +|---|---| +| **`_memccpy`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -97,8 +97,8 @@ Length: 25 characters ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[memchr, wmemchr](memchr-wmemchr.md)
-[memcmp, wmemcmp](memcmp-wmemcmp.md)
-[memcpy, wmemcpy](memcpy-wmemcpy.md)
-[memset, wmemset](memset-wmemset.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`memchr`, `wmemchr`](memchr-wmemchr.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ +[`memset`, `wmemset`](memset-wmemset.md) diff --git a/docs/c-runtime-library/reference/memchr-wmemchr.md b/docs/c-runtime-library/reference/memchr-wmemchr.md index c3b8def893..0a5ff9b1eb 100644 --- a/docs/c-runtime-library/reference/memchr-wmemchr.md +++ b/docs/c-runtime-library/reference/memchr-wmemchr.md @@ -3,14 +3,14 @@ description: "Learn more about: memchr, wmemchr" title: "memchr, wmemchr" ms.date: "1/14/2021" api_name: ["wmemchr", "memchr"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["memchr", "wmemchr"] helpviewer_keywords: ["memchr function", "wmemchr function"] ms.assetid: 5a348581-28f1-4256-8434-687245f7fc9f --- -# memchr, wmemchr +# `memchr`, `wmemchr` Find characters in a buffer. @@ -51,37 +51,37 @@ const wchar_t *wmemchr( ### Parameters -*buffer*
+*`buffer`*\ Pointer to buffer. -*c*
+*`c`*\ Character to look for. -*count*
+*`count`*\ Number of characters to check. -## Return Value +## Return value -If successful, returns a pointer to the first location of *c* in *buffer*. Otherwise it returns NULL. +If successful, returns a pointer to the first location of *`c`* in *`buffer`*. Otherwise it returns NULL. ## Remarks -`memchr` and `wmemchr` look for the first occurrence of *c* in the first *count* characters of *buffer*. It stops when it finds *c* or when it has checked the first *count* characters. +`memchr` and `wmemchr` look for the first occurrence of *`c`* in the first *`count`* characters of *`buffer`*. It stops when it finds *`c`* or when it has checked the first *`count`* characters. -In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro \_CRT\_CONST\_CORRECT\_OVERLOADS is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads in C++, define the symbol \_CONST\_RETURN. +In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads in C++, define the symbol `_CONST_RETURN`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`memchr`|\ or \| -|`wmemchr`|\| +| Routine | Required header | +|---|---| +| `memchr` | \ or \ | +| `wmemchr` | \ | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -128,9 +128,9 @@ Result: r found at position 12 ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[_memccpy](memccpy.md)
-[memcmp, wmemcmp](memcmp-wmemcmp.md)
-[memcpy, wmemcpy](memcpy-wmemcpy.md)
-[memset, wmemset](memset-wmemset.md)
-[strchr, wcschr, _mbschr, _mbschr_l](strchr-wcschr-mbschr-mbschr-l.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`_memccpy`](memccpy.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](strchr-wcschr-mbschr-mbschr-l.md) diff --git a/docs/c-runtime-library/reference/memcmp-wmemcmp.md b/docs/c-runtime-library/reference/memcmp-wmemcmp.md index 5b2c28b514..6b4ae96e46 100644 --- a/docs/c-runtime-library/reference/memcmp-wmemcmp.md +++ b/docs/c-runtime-library/reference/memcmp-wmemcmp.md @@ -3,7 +3,7 @@ description: "Learn more about: memcmp, wmemcmp" title: "memcmp, wmemcmp" ms.date: "1/14/2021" api_name: ["memcmp", "wmemcmp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["memcmp", "wmemcmp"] @@ -31,24 +31,24 @@ int wmemcmp( ### Parameters -*`buffer1`*
+*`buffer1`*\ First buffer. -*`buffer2`*
+*`buffer2`*\ Second buffer. -*`count`*
+*`count`*\ Number of characters to compare. (Compares bytes for **`memcmp`**, wide characters for **`wmemcmp`**). -## Return Value +## Return value The return value indicates the relationship between the buffers. -|Return value|Relationship of first *`count`* characters of `buf1` and `buf2`| -|------------------|---------------------------------------------------------------| -|< 0|*`buffer1`* less than *`buffer2`*| -|0|*`buffer1`* identical to *`buffer2`*| -|> 0|*`buffer1`* greater than *`buffer2`*| +| Return value | Relationship of first *`count`* characters of `buf1` and `buf2` | +|---|---| +| < 0 | *`buffer1`* less than *`buffer2`* | +| 0 | *`buffer1`* identical to *`buffer2`* | +| > 0 | *`buffer1`* greater than *`buffer2`* | ## Remarks @@ -56,16 +56,16 @@ Compares the first *`count`* characters of *`buffer1`* and *`buffer2`* and retur ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`memcmp`**|`` or ``| -|**`wmemcmp`**|``| +| Routine | Required header | +|---|---| +| **`memcmp`** | `` or `` | +| **`wmemcmp`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time library](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time library](../crt-library-features.md). ## Example @@ -117,10 +117,10 @@ int_arr1 is equal to int_arr2. ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[`_memccpy`](memccpy.md)
-[`memchr`, `wmemchr`](memchr-wmemchr.md)
-[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)
-[`memset`, `wmemset`](memset-wmemset.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`_memccpy`](memccpy.md)\ +[`memchr`, `wmemchr`](memchr-wmemchr.md)\ +[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) diff --git a/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md b/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md index ab9d64fb85..fbbc8ace41 100644 --- a/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md +++ b/docs/c-runtime-library/reference/memcpy-s-wmemcpy-s.md @@ -3,7 +3,7 @@ description: "Learn more about: memcpy_s, wmemcpy_s" title: "memcpy_s, wmemcpy_s" ms.date: "4/2/2020" api_name: ["memcpy_s", "wmemcpy_s", "_o_memcpy_s", "_o_wmemcpy_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wmemcpy_s", "memcpy_s"] @@ -12,7 +12,7 @@ ms.assetid: 5504e20a-83d9-4063-91fc-3f55f7dabe99 --- # `memcpy_s`, `wmemcpy_s` -Copies bytes between buffers. These are versions of [`memcpy`, `wmemcpy`](memcpy-wmemcpy.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies bytes between buffers. These functions are versions of [`memcpy`, `wmemcpy`](memcpy-wmemcpy.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,47 +33,47 @@ errno_t wmemcpy_s( ### Parameters -*`dest`*
+*`dest`*\ New buffer. -*`destSize`*
+*`destSize`*\ Size of the destination buffer, in bytes for `memcpy_s` and wide characters (`wchar_t`) for `wmemcpy_s`. -*`src`*
+*`src`*\ Buffer to copy from. -*`count`*
+*`count`*\ Number of characters to copy. -## Return Value +## Return value Zero if successful; an error code on failure. -### Error Conditions +### Error conditions -|*`dest`*|*`destSize`*|*`src`*|*`count`*|Return value|Contents of *`dest`*| -|------------|----------------|-----------|---|------------------|------------------------| -|any|any|any|0|0|Not modified| -|**`NULL`**|any|any|non-zero|**`EINVAL`**|Not modified| -|any|any|**`NULL`**|non-zero|**`EINVAL`**|*`dest`* is zeroed out| -|any|< *`count`*|any|non-zero|**`ERANGE`**|*`dest`* is zeroed out| +| *`dest`* | *`destSize`* | *`src`* | *`count`* | Return value | Contents of *`dest`* | +|---|---|---|---|---|---| +| any | any | any | 0 | 0 | Not modified | +| `NULL` | any | any | non-zero | `EINVAL` | Not modified | +| any | any | `NULL` | non-zero | `EINVAL` | *`dest`* is zeroed out | +| any | < *`count`* | any | non-zero | `ERANGE` | *`dest`* is zeroed out | ## Remarks -**`memcpy_s`** copies *`count`* bytes from *`src`* to *`dest`*; **`wmemcpy_s`** copies *`count`* wide characters (two bytes). If the source and destination overlap, the behavior of **`memcpy_s`** is undefined. Use **`memmove_s`** to handle overlapping regions. +**`memcpy_s`** copies *`count`* bytes from *`src`* to *`dest`*; **`wmemcpy_s`** copies *`count`* wide characters. If the source and destination regions overlap, the behavior of **`memcpy_s`** is undefined. Use **`memmove_s`** to handle overlapping regions. -These functions validate their parameters. If *`count`* is non-zero and *`dest`* or *`src`* is a null pointer, or *`destSize`* is smaller than *`count`*, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** or **`ERANGE`** and set **`errno`** to the return value. +These functions validate their parameters. If *`count`* is non-zero and *`dest`* or *`src`* is a null pointer, or *`destSize`* is smaller than *`count`*, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` or `ERANGE`, and set `errno` to the return value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`memcpy_s`**|`` or ``| -|**`wmemcpy_s`**|``| +| Routine | Required header | +|---|---| +| **`memcpy_s`** | `` or `` | +| **`wmemcpy_s`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -117,12 +117,12 @@ int main() ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[`_memccpy`](memccpy.md)
-[`memchr`, `wmemchr`](memchr-wmemchr.md)
-[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)
-[`memmove`, `wmemmove`](memmove-wmemmove.md)
-[`memset`, `wmemset`](memset-wmemset.md)
-[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`_memccpy`](memccpy.md)\ +[`memchr`, `wmemchr`](memchr-wmemchr.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`memmove`, `wmemmove`](memmove-wmemmove.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) diff --git a/docs/c-runtime-library/reference/memcpy-wmemcpy.md b/docs/c-runtime-library/reference/memcpy-wmemcpy.md index 1ed50b8929..4572322b81 100644 --- a/docs/c-runtime-library/reference/memcpy-wmemcpy.md +++ b/docs/c-runtime-library/reference/memcpy-wmemcpy.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: memcpy, wmemcpy" title: "memcpy, wmemcpy" +description: "Learn more about: memcpy, wmemcpy" ms.date: "1/14/2021" api_name: ["memcpy", "wmemcpy"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wmemcpy", "memcpy"] helpviewer_keywords: ["wmemcpy function", "memcpy function"] -ms.assetid: 34abb90b-bffb-46dc-a2f3-a5e9940839d6 --- # `memcpy`, `wmemcpy` @@ -40,23 +39,23 @@ Buffer to copy from. *`count`*\ Number of characters to copy. -## Return Value +## Return value The value of *`dest`*. ## Remarks -**`memcpy`** copies *`count`* bytes from *`src`* to *`dest`*; **`wmemcpy`** copies *`count`* wide characters (two bytes). If the source and destination overlap, the behavior of **`memcpy`** is undefined. Use **`memmove`** to handle overlapping regions. +**`memcpy`** copies *`count`* bytes from *`src`* to *`dest`*; **`wmemcpy`** copies *`count`* wide characters. If the source and destination regions overlap, the behavior of **`memcpy`** is undefined. Use **`memmove`** to handle overlapping regions. > [!IMPORTANT] -> Make sure that the destination buffer is the same size or larger than the source buffer. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Make sure that the destination buffer is large enough to accommodate the number of copied characters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > [!IMPORTANT] -> Because so many buffer overruns, and thus potential security exploits, have been traced to improper usage of **`memcpy`**, this function is listed among the "banned" functions by the Security Development Lifecycle (SDL). You may observe that some VC++ library classes continue to use **`memcpy`**. Furthermore, you may observe that the VC++ compiler optimizer sometimes emits calls to **`memcpy`**. The Visual C++ product is developed in accordance with the SDL process, and thus usage of this banned function has been closely evaluated. In the case of library use of it, the calls have been carefully scrutinized to ensure that buffer overruns will not be allowed through these calls. In the case of the compiler, sometimes certain code patterns are recognized as identical to the pattern of **`memcpy`**, and are thus replaced with a call to the function. In such cases, the use of **`memcpy`** is no more unsafe than the original instructions would have been; they have simply been optimized to a call to the performance-tuned **`memcpy`** function. Just as the use of "safe" CRT functions doesn’t guarantee safety (they just make it harder to be unsafe), the use of "banned" functions doesn’t guarantee danger (they just require greater scrutiny to ensure safety). +> Because so many buffer overruns, and thus potential security exploits, have been traced to improper usage of **`memcpy`**, this function is listed among the "banned" functions by the Security Development Lifecycle (SDL). You may observe that some VC++ library classes continue to use **`memcpy`**. Furthermore, you may observe that the VC++ compiler optimizer sometimes emits calls to **`memcpy`**. The Visual C++ product is developed in accordance with the SDL process, and thus usage of this banned function has been closely evaluated. In the case of library use of it, the calls have been carefully scrutinized to ensure that buffer overruns will not be allowed through these calls. In the case of the compiler, sometimes certain code patterns are recognized as identical to the pattern of **`memcpy`**, and are thus replaced with a call to the function. In such cases, the use of **`memcpy`** is no more unsafe than the original instructions would have been; they have simply been optimized to a call to the performance-tuned **`memcpy`** function. Just as the use of "safe" CRT functions doesn't guarantee safety (they just make it harder to be unsafe), the use of "banned" functions doesn't guarantee danger (they just require greater scrutiny to ensure safety). > > Because **`memcpy`** usage by the VC++ compiler and libraries has been so carefully scrutinized, these calls are permitted within code that otherwise conforms with the SDL. **`memcpy`** calls introduced in application source code only conform with the SDL when that use has been reviewed by security experts. -The **`memcpy`** and **`wmemcpy`** functions are only deprecated if the constant **`_CRT_SECURE_DEPRECATE_MEMORY`** is defined before the include statement, as in the example below: +The **`memcpy`** and **`wmemcpy`** functions are only deprecated if the constant `_CRT_SECURE_DEPRECATE_MEMORY` is defined before the `#include` statement, as in the following examples: ```C #define _CRT_SECURE_DEPRECATE_MEMORY @@ -72,12 +71,12 @@ or ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`memcpy`**|`` or ``| -|**`wmemcpy`**|``| +| Routine | Required header | +|---|---| +| **`memcpy`** | `` or `` | +| **`wmemcpy`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -85,11 +84,11 @@ See [`memmove`](memmove-wmemmove.md) for a sample of how to use **`memcpy`**. ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)\ +[Buffer manipulation](../buffer-manipulation.md)\ [`_memccpy`](memccpy.md)\ [`memchr`, `wmemchr`](memchr-wmemchr.md)\ [`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ [`memmove`, `wmemmove`](memmove-wmemmove.md)\ [`memset`, `wmemset`](memset-wmemset.md)\ [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)\ -[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) diff --git a/docs/c-runtime-library/reference/memicmp-memicmp-l.md b/docs/c-runtime-library/reference/memicmp-memicmp-l.md index bd32e12a42..a22a2f0a85 100644 --- a/docs/c-runtime-library/reference/memicmp-memicmp-l.md +++ b/docs/c-runtime-library/reference/memicmp-memicmp-l.md @@ -3,14 +3,14 @@ description: "Learn more about: _memicmp, _memicmp_l" title: "_memicmp, _memicmp_l" ms.date: "4/2/2020" api_name: ["_memicmp_l", "_memicmp", "_o__memicmp", "_o__memicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_memicmp", "memicmp_l", "_memicmp_l"] helpviewer_keywords: ["memicmp function", "_memicmp function", "memicmp_l function", "_memicmp_l function"] ms.assetid: 0a6eb945-4077-4f84-935d-1aaebe8db8cb --- -# _memicmp, _memicmp_l +# `_memicmp`, `_memicmp_l` Compares characters in two buffers (case-insensitive). @@ -32,47 +32,47 @@ int _memicmp_l( ### Parameters -*buffer1*
+*`buffer1`*\ First buffer. -*buffer2*
+*`buffer2`*\ Second buffer. -*count*
+*`count`*\ Number of characters. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value indicates the relationship between the buffers. -|Return value|Relationship of first count bytes of buf1 and buf2| -|------------------|--------------------------------------------------------| -|< 0|*buffer1* less than *buffer2*.| -|0|*buffer1* identical to *buffer2*.| -|> 0|*buffer1* greater than *buffer2*.| -|**_NLSCMPERROR**|An error occurred.| +| Return value | Relationship of first count bytes of buf1 and buf2 | +|---|---| +| < 0 | *`buffer1`* less than *`buffer2`*. | +| 0 | *`buffer1`* identical to *`buffer2`*. | +| > 0 | *`buffer1`* greater than *`buffer2`*. | +| `_NLSCMPERROR` | An error occurred. | ## Remarks -The **_memicmp** function compares the first *count* characters of the two buffers *buffer1* and *buffer2* byte by byte. The comparison is not case-sensitive. +The **`_memicmp`** function compares the first *`count`* characters of the two buffers *`buffer1`* and *`buffer2`* byte by byte. The comparison isn't case-sensitive. -If either *buffer1* or *buffer2* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **_NLSCMPERROR** and sets **errno** to **EINVAL**. +If either *`buffer1`* or *`buffer2`* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `_NLSCMPERROR` and sets `errno` to `EINVAL`. -**_memicmp** uses the current locale for locale-dependent behavior; **_memicmp_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_memicmp`** uses the current locale for locale-dependent behavior; **`_memicmp_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_memicmp**|\ or \| -|**_memicmp_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_memicmp`** | \ or \ | +| **`_memicmp_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -111,11 +111,11 @@ First is equal to second. ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[_memccpy](memccpy.md)
-[memchr, wmemchr](memchr-wmemchr.md)
-[memcmp, wmemcmp](memcmp-wmemcmp.md)
-[memcpy, wmemcpy](memcpy-wmemcpy.md)
-[memset, wmemset](memset-wmemset.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`_memccpy`](memccpy.md)\ +[`memchr`, `wmemchr`](memchr-wmemchr.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) diff --git a/docs/c-runtime-library/reference/memicmp.md b/docs/c-runtime-library/reference/memicmp.md index 5dce2412d5..925b0346a5 100644 --- a/docs/c-runtime-library/reference/memicmp.md +++ b/docs/c-runtime-library/reference/memicmp.md @@ -10,8 +10,8 @@ f1_keywords: ["memicmp"] helpviewer_keywords: ["memicmp function"] ms.assetid: 45362e9c-7c64-41e9-92bb-7d4999a8635b --- -# memicmp +# `memicmp` -The Microsoft-specific function name `memicmp` is a deprecated alias for the [_memicmp](memicmp-memicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `memicmp` is a deprecated alias for the [`_memicmp`](memicmp-memicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_memicmp](memicmp-memicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_memicmp`](memicmp-memicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md b/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md index 18a0e4b45d..35504364a0 100644 --- a/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md +++ b/docs/c-runtime-library/reference/memmove-s-wmemmove-s.md @@ -3,16 +3,16 @@ description: "Learn more about: memmove_s, wmemmove_s" title: "memmove_s, wmemmove_s" ms.date: "4/2/2020" api_name: ["wmemmove_s", "memmove_s", "_o_wmemmove_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wmemmove_s", "memmove_s"] helpviewer_keywords: ["wmemmove_s function", "memmove_s function"] ms.assetid: a17619e4-1307-4bb0-98c6-77f8c68dab2d --- -# memmove_s, wmemmove_s +# `memmove_s`, `wmemmove_s` -Moves one buffer to another. These are versions of [memmove, wmemmove](memmove-wmemmove.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Moves one buffer to another. These functions are versions of [`memmove`, `wmemmove`](memmove-wmemmove.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,46 +33,46 @@ errno_t wmemmove_s( ### Parameters -*dest*
+*`dest`*\ Destination object. -*numberOfElements*
+*`numberOfElements`*\ Size of the destination buffer. -*src*
+*`src`*\ Source object. -*count*
-Number of bytes (**memmove_s**) or characters (**wmemmove_s**) to copy. +*`count`*\ +Number of bytes (**`memmove_s`**) or characters (**`wmemmove_s`**) to copy. -## Return Value +## Return value Zero if successful; an error code on failure -### Error Conditions +### Error conditions -|*dest*|*numberOfElements*|*src*|Return value|Contents of *dest*| -|------------|------------------------|-----------|------------------|------------------------| -|**NULL**|any|any|**EINVAL**|not modified| -|any|any|**NULL**|**EINVAL**|not modified| -|any|< *count*|any|**ERANGE**|not modified| +| *`dest`* | *`numberOfElements`* | *`src`* | Return value | Contents of *`dest`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | not modified | +| any | < *`count`* | any | `ERANGE` | not modified | ## Remarks -Copies *count* bytes of characters from *src* to *dest*. If some regions of the source area and the destination overlap, **memmove_s** ensures that the original source bytes in the overlapping region are copied before being overwritten. +Copies *`count`* bytes of characters from *`src`* to *`dest`*. If some portions of the source and the destination regions overlap, **`memmove_s`** ensures that the original source bytes in the overlapping region are copied before being overwritten. -If *dest* or if *src* is a null pointer, or if the destination string is too small, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **EINVAL** and set **errno** to **EINVAL**. +If *`dest`* or if *`src`* is a null pointer, or if the destination string is too small, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**memmove_s**|\| -|**wmemmove_s**|\| +| Routine | Required header | +|---|---| +| **`memmove_s`** | \ | +| **`wmemmove_s`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,10 +112,10 @@ After: 0012345789 ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
-[_memccpy](memccpy.md)
-[memcpy, wmemcpy](memcpy-wmemcpy.md)
-[strcpy_s, wcscpy_s, _mbscpy_s](strcpy-s-wcscpy-s-mbscpy-s.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
+[Buffer manipulation](../buffer-manipulation.md)\ +[`_memccpy`](memccpy.md)\ +[`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) diff --git a/docs/c-runtime-library/reference/memmove-wmemmove.md b/docs/c-runtime-library/reference/memmove-wmemmove.md index e3d761dab7..00c3f732e4 100644 --- a/docs/c-runtime-library/reference/memmove-wmemmove.md +++ b/docs/c-runtime-library/reference/memmove-wmemmove.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: memmove, wmemmove" title: "memmove, wmemmove" +description: "Learn more about: memmove, wmemmove" ms.date: "1/14/2021" api_name: ["memmove", "wmemmove"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["memmove", "wmemmove"] @@ -39,17 +39,17 @@ Source object. *`count`*\ Number of bytes (**`memmove`**) or characters (**`wmemmove`**) to copy. -## Return Value +## Return value The value of *`dest`*. ## Remarks -Copies *`count`* bytes (**`memmove`**) or characters (**`wmemmove`**) from *`src`* to *`dest`*. If some regions of the source area and the destination overlap, both functions ensure that the original source bytes in the overlapping region are copied before being overwritten. +Copies *`count`* bytes (**`memmove`**) or characters (**`wmemmove`**) from *`src`* to *`dest`*. If some portions of the source and the destination regions overlap, both functions ensure that the original source bytes in the overlapping region are copied before being overwritten. -**Security Note** Make sure that the destination buffer is the same size or larger than the source buffer. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** Make sure that the destination buffer is large enough to accommodate the number of moved characters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -The **`memmove`** and **`wmemmove`** functions will only be deprecated if the constant **`_CRT_SECURE_DEPRECATE_MEMORY`** is defined before the inclusion statement in order for the functions to be deprecated, such as in the example below: +The **`memmove`** and **`wmemmove`** functions are only deprecated if the constant `_CRT_SECURE_DEPRECATE_MEMORY` is defined before the `#include` statement, as shown in the following example: ```C #define _CRT_SECURE_DEPRECATE_MEMORY @@ -65,12 +65,12 @@ or ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`memmove`**|``| -|**`wmemmove`**|``| +| Routine | Required header | +|---|---| +| **`memmove`** | `` | +| **`wmemmove`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -110,8 +110,8 @@ New string: aaaabb ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)\ +[Buffer manipulation](../buffer-manipulation.md)\ [`_memccpy`](memccpy.md)\ [`memcpy`, `wmemcpy`](memcpy-wmemcpy.md)\ [`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ -[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) diff --git a/docs/c-runtime-library/reference/memset-wmemset.md b/docs/c-runtime-library/reference/memset-wmemset.md index bfb1a0f8fb..ac7a395bc9 100644 --- a/docs/c-runtime-library/reference/memset-wmemset.md +++ b/docs/c-runtime-library/reference/memset-wmemset.md @@ -3,7 +3,7 @@ title: "memset, wmemset" description: "Learn more about: memset, wmemset" ms.date: "11/29/2021" api_name: ["wmemset", "memset", "_o_memset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["memset", "wmemset"] @@ -39,7 +39,7 @@ Character to set. *`count`*\ Number of characters. -## Return Value +## Return value The value of *`dest`*. @@ -47,22 +47,22 @@ The value of *`dest`*. Sets the first *`count`* characters of *`dest`* to the character *`c`*. -**Security Note** Make sure that the destination buffer has enough room for at least *`count`* characters. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** Make sure that the destination buffer has enough room for at least *`count`* characters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`memset`**|`` or ``| -|**`wmemset`**|``| +| Routine | Required header | +|---|---| +| **`memset`** | `` or `` | +| **`wmemset`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -122,7 +122,7 @@ After: **** is a test of the wmemset function ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)\ +[Buffer manipulation](../buffer-manipulation.md)\ [`_memccpy`](memccpy.md)\ [`memchr`, `wmemchr`](memchr-wmemchr.md)\ [`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ diff --git a/docs/c-runtime-library/reference/min.md b/docs/c-runtime-library/reference/min.md index 6e24398902..d6e3fbfd16 100644 --- a/docs/c-runtime-library/reference/min.md +++ b/docs/c-runtime-library/reference/min.md @@ -10,7 +10,7 @@ f1_keywords: ["__min", "min", "_min"] helpviewer_keywords: ["__min macro", "min macro", "minimum macro", "_min macro"] ms.assetid: 2037f26c-b48a-4a69-8870-22519f052a3c --- -# __min +# `__min` A preprocessor macro that returns the smaller of two values. @@ -22,24 +22,24 @@ A preprocessor macro that returns the smaller of two values. ### Parameters -*a*, *b*
+*`a`*, *`b`*\ Values of any type that the **<** operator works on. -## Return Value +## Return value The smaller of the two arguments. ## Remarks -The **__min** macro compares two values and returns the value of the smaller one. The arguments can be of any numeric data type, signed or unsigned. Both arguments and the return value must be of the same data type. +The **`__min`** macro compares two values and returns the value of the smaller one. The arguments can be of any numeric data type, signed or unsigned. Both arguments and the return value must be of the same data type. -The argument returned is evaluated twice by the macro. This can lead to unexpected results if the argument is an expression that alters its value when it is evaluated, such as `*p++`. +The argument returned is evaluated twice by the macro. Double evaluation can lead to unexpected results if the argument is an expression that alters its value when it's evaluated, such as `*p++`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**__min**|\| +| Routine | Required header | +|---|---| +| **`__min`** | \ | ## Example @@ -66,5 +66,5 @@ The smaller of 10 and 21 is 10 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[__max](max.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`__max`](max.md) diff --git a/docs/c-runtime-library/reference/mkdir-wmkdir.md b/docs/c-runtime-library/reference/mkdir-wmkdir.md index cafc8fef5e..f01bf458e6 100644 --- a/docs/c-runtime-library/reference/mkdir-wmkdir.md +++ b/docs/c-runtime-library/reference/mkdir-wmkdir.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _mkdir, _wmkdir" title: "_mkdir, _wmkdir" +description: "Learn more about: _mkdir, _wmkdir" ms.date: "4/2/2020" api_name: ["_wmkdir", "_mkdir", "_o__mkdir", "_o__wmkdir"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mkdir", "tmkdir", "_tmkdir", "wmkdir", "_wmkdir"] helpviewer_keywords: ["_wmkdir function", "folders [C++], creating", "wmkdir function", "directories [C++], creating", "mkdir function", "tmkdir function", "_mkdir function", "_tmkdir function"] -ms.assetid: 7f22d01d-63a5-4712-a6e7-d34878b2d840 --- # `_mkdir`, `_wmkdir` @@ -17,7 +16,6 @@ Creates a new directory. ## Syntax ```C - int _mkdir( const char *dirname ); @@ -28,45 +26,45 @@ int _wmkdir( ### Parameters -*`dirname`*
+*`dirname`*\ Path for a new directory. -## Return Value +## Return value -Each of these functions returns the value 0 if the new directory was created. On an error, the function returns -1 and sets **`errno`** as follows. +Each of these functions returns the value 0 if the new directory was created. On an error, the function returns -1 and sets `errno` as follows. -**`EEXIST`** Directory was not created because *`dirname`* is the name of an existing file, directory, or device. +`EEXIST` Directory wasn't created because *`dirname`* is the name of an existing file, directory, or device. -**`ENOENT`** Path was not found. +`ENOENT` Path wasn't found. -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_mkdir`** function creates a new directory with the specified *`dirname`*. **`_mkdir`** can create only one new directory per call, so only the last component of *`dirname`* can name a new directory. **`_mkdir`** does not translate path delimiters. In Windows NT, both the backslash ( \\) and the forward slash (/ ) are valid path delimiters in character strings in run-time routines. +The **`_mkdir`** function creates a new directory with the specified *`dirname`*. **`_mkdir`** can create only one new directory per call, so only the last component of *`dirname`* can name a new directory. **`_mkdir`** doesn't translate path delimiters. In Windows NT, both the backslash (**`\`**) and the forward slash (**`/`**) are valid path delimiters in character strings in run-time routines. **`_wmkdir`** is a wide-character version of **`_mkdir`**; the *`dirname`* argument to **`_wmkdir`** is a wide-character string. **`_wmkdir`** and **`_mkdir`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tmkdir`**|**`_mkdir`**|**`_mkdir`**|**`_wmkdir`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tmkdir` | **`_mkdir`** | **`_mkdir`** | **`_wmkdir`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_mkdir`**|``| -|**`_wmkdir`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_mkdir`** | `` | +| **`_wmkdir`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -93,7 +91,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Directory '\testtmp' was successfully created @@ -111,6 +109,6 @@ Directory '\testtmp' was successfully removed ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[`_chdir`, `_wchdir`](chdir-wchdir.md)
-[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_rmdir`, `_wrmdir`](rmdir-wrmdir.md) diff --git a/docs/c-runtime-library/reference/mkdir.md b/docs/c-runtime-library/reference/mkdir.md index fe7715310e..da03a098b2 100644 --- a/docs/c-runtime-library/reference/mkdir.md +++ b/docs/c-runtime-library/reference/mkdir.md @@ -8,10 +8,9 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mkdir"] helpviewer_keywords: ["mkdir function"] -ms.assetid: 0a212890-181e-45d0-988d-e0f301fcdeb8 --- -# mkdir +# `mkdir` -The Microsoft-implemented POSIX function name `mkdir` is a deprecated alias for the [_mkdir](mkdir-wmkdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `mkdir` is a deprecated alias for the [`_mkdir`](mkdir-wmkdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_mkdir](mkdir-wmkdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_mkdir`](mkdir-wmkdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md b/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md index 36100cf69a..c692db9900 100644 --- a/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md +++ b/docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md @@ -3,7 +3,7 @@ title: "_mkgmtime, _mkgmtime32, _mkgmtime64" description: "Describes the _mkgmtime, _mkgmtime32, and _mkgmtime64 C Runtime library functions, and gives examples of how to use them." ms.date: 09/22/2021 api_name: ["_mkgmtime32", "_mkgmtime64", "_mkgmtime", "_o__mkgmtime32", "_o__mkgmtime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mkgmtime64", "mkgmtime32", "_mkgmtime32", "mkgmtime", "mkgmtime64", "_mkgmtime"] @@ -32,7 +32,7 @@ __time64_t _mkgmtime64( *`timeptr`*\ A pointer to the UTC time as a **`struct tm`** to convert. -## Return Value +## Return value A quantity of type **`__time32_t`** or **`__time64_t`** representing the number of seconds elapsed since midnight, January 1, 1970, in Coordinated Universal Time (UTC). If the date is out of range (see the Remarks section) or the input can't be interpreted as a valid time, the return value is -1. @@ -40,11 +40,11 @@ A quantity of type **`__time32_t`** or **`__time64_t`** representing the number The **`_mkgmtime32`** and **`_mkgmtime64`** functions convert a UTC time to a **`__time32_t`** or **`__time64_t`** type representing the time in UTC. To convert a local time to UTC time, use **`mktime`**, **`_mktime32`**, and **`_mktime64`** instead. -**_mkgmtime** is an inline function that evaluates to **`_mkgmtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **`time_t`**. It's not allowed at all on 64-bit platforms. +**`_mkgmtime`** is an inline function that evaluates to **`_mkgmtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **`time_t`**. It's not allowed at all on 64-bit platforms. The time structure passed in is changed as follows, in the same way as it's changed by the **`_mktime`** functions: the **`tm_wday`** and **`tm_yday`** fields are set to new values based on the values of **`tm_mday`** and **`tm_year`**. Because the time is assumed to be UTC, the **`tm_isdst`** field is ignored. -The range of the **`_mkgmtime32`** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **`_mkgmtime64`** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **`_mkgmtime`** depends on whether **`_USE_32BIT_TIME_T`** is defined. When it's not defined, which is the default, the range is the same as **`_mkgmtime64`**. Otherwise, the range is limited to the 32-bit range of **`_mkgmtime32`**. +The range of the **`_mkgmtime32`** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **`_mkgmtime64`** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **`_mkgmtime`** depends on whether `_USE_32BIT_TIME_T` is defined. When it's not defined, which is the default, the range is the same as **`_mkgmtime64`**. Otherwise, the range is limited to the 32-bit range of **`_mkgmtime32`**. Both **`gmtime`** and **`localtime`** use a common static buffer for the conversion. If you supply this buffer to **`_mkgmtime`**, the previous contents are destroyed. @@ -141,7 +141,7 @@ t.tm_yday = 42 ## See also -[Time Management](../../c-runtime-library/time-management.md)\ +[Time management](../time-management.md)\ [`asctime`, `_wasctime`](asctime-wasctime.md)\ [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ [`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ diff --git a/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md b/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md index 8aebe8df75..177b5e35e5 100644 --- a/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md +++ b/docs/c-runtime-library/reference/mktemp-s-wmktemp-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _mktemp_s, _wmktemp_s" title: "_mktemp_s, _wmktemp_s" ms.date: "4/2/2020" api_name: ["_mktemp_s", "_wmktemp_s", "_o__mktemp_s", "_o__wmktemp_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wmktemp_s", "mktemp_s", "_mktemp_s", "_wmktemp_s"] helpviewer_keywords: ["_tmktemp_s function", "mktemp_s function", "_wmktemp_s function", "_mktemp_s function", "files [C++], temporary", "tmktemp_s function", "wmktemp_s function", "temporary files [C++]"] ms.assetid: 92a7e269-7f3d-4c71-bad6-14bc827a451d --- -# _mktemp_s, _wmktemp_s +# `_mktemp_s`, `_wmktemp_s` -Creates a unique file name. These are versions of [_mktemp, _wmktemp](mktemp-wmktemp.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates a unique file name. These functions are versions of [`_mktemp`, `_wmktemp`](mktemp-wmktemp.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,70 +37,70 @@ errno_t _wmktemp_s( ### Parameters -*nameTemplate*
+*`nameTemplate`*\ File name pattern. -*sizeInChars*
-Size of the buffer in single-byte characters in **_mktemp_s**; wide characters in **_wmktemp_s**, including the null terminator. +*`sizeInChars`*\ +Size of the buffer in single-byte characters in **`_mktemp_s`**; wide characters in **`_wmktemp_s`**, including the null terminator. -## Return Value +## Return value Both of these functions return zero on success; an error code on failure. -### Error Conditions +### Error conditions -|*nameTemplate*|*sizeInChars*|Return value|New value in *nameTemplate*| -|----------------|-------------------|----------------------|-------------------------------| -|**NULL**|any|**EINVAL**|**NULL**| -|Incorrect format (see Remarks section for correct format)|any|**EINVAL**|empty string| -|any|<= number of X's|**EINVAL**|empty string| +| *`nameTemplate`* | *`sizeInChars`* | Return value | New value in *`nameTemplate`* | +|---|---|---|---| +| `NULL` | any | `EINVAL` | `NULL` | +| Incorrect format (see Remarks section for correct format) | any | `EINVAL` | empty string | +| any | <= number of X characters | `EINVAL` | empty string | -If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the functions returns **EINVAL**. +If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the functions returns `EINVAL`. ## Remarks -The **_mktemp_s** function creates a unique file name by modifying the *nameTemplate* argument, so that after the call, the *nameTemplate* pointer points to a string containing the new file name. **_mktemp_s** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use by the run-time system. **_wmktemp_s** is a wide-character version of **_mktemp_s**; the argument of **_wmktemp_s** is a wide-character string. **_wmktemp_s** and **_mktemp_s** behave identically otherwise, except that **_wmktemp_s** does not handle multibyte-character strings. +The **`_mktemp_s`** function creates a unique file name by modifying the *`nameTemplate`* argument, so that after the call, the *`nameTemplate`* pointer points to a string containing the new file name. **`_mktemp_s`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use by the run-time system. **`_wmktemp_s`** is a wide-character version of **`_mktemp_s`**; the argument of **`_wmktemp_s`** is a wide-character string. **`_wmktemp_s`** and **`_mktemp_s`** behave identically otherwise, except that **`_wmktemp_s`** doesn't handle multibyte-character strings. -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmktemp_s**|**_mktemp_s**|**_mktemp_s**|**_wmktemp_s**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tmktemp_s` | **`_mktemp_s`** | **`_mktemp_s`** | **`_wmktemp_s`** | -The *nameTemplate* argument has the form **baseXXXXXX**, where *base* is the part of the new file name that you supply and each X is a placeholder for a character supplied by **_mktemp_s**. Each placeholder character in *nameTemplate* must be an uppercase X. **_mktemp_s** preserves *base* and replaces the first trailing X with an alphabetic character. **_mktemp_s** replaces the following trailing X's with a five-digit value; this value is a unique number identifying the calling process, or in multithreaded programs, the calling thread. +The *`nameTemplate`* argument has the form *`baseXXXXXX`*, where *`base`* is the part of the new file name that you supply and each X is a placeholder for a character supplied by **`_mktemp_s`**. Each placeholder character in *`nameTemplate`* must be an uppercase X. **`_mktemp_s`** preserves *`base`* and replaces the first trailing X with an alphabetic character. **`_mktemp_s`** replaces the X characters that follow with a five-digit value. This value is a unique number that identifies the calling process, or in multithreaded programs, the calling thread. -Each successful call to **_mktemp_s** modifies *nameTemplate*. In each subsequent call from the same process or thread with the same *nameTemplate* argument, **_mktemp_s** checks for file names that match names returned by **_mktemp_s** in previous calls. If no file exists for a given name, **_mktemp_s** returns that name. If files exist for all previously returned names, **_mktemp_s** creates a new name by replacing the alphabetic character it used in the previously returned name with the next available lowercase letter, in order, from 'a' through 'z'. For example, if *base* is: +Each successful call to **`_mktemp_s`** modifies *`nameTemplate`*. In each subsequent call from the same process or thread with the same *`nameTemplate`* argument, **`_mktemp_s`** checks for file names that match names returned by **`_mktemp_s`** in previous calls. If no file exists for a given name, **`_mktemp_s`** returns that name. If files exist for all previously returned names, **`_mktemp_s`** creates a new name by replacing the alphabetic character it used in the previously returned name with the next available lowercase letter, in order, from 'a' through 'z'. For example, if *`base`* is: -> **fn** +> **`fn`** -and the five-digit value supplied by **_mktemp_s** is 12345, the first name returned is: +and the five-digit value supplied by **`_mktemp_s`** is 12345, the first name returned is: -> **fna12345** +> **`fna12345`** -If this name is used to create file FNA12345 and this file still exists, the next name returned on a call from the same process or thread with the same *base* for *nameTemplate* is: +If this name is used to create file FNA12345 and this file still exists, the next name returned on a call from the same process or thread with the same *`base`* for *`nameTemplate`* is: -> **fnb12345** +> **`fnb12345`** -If FNA12345 does not exist, the next name returned is again: +If FNA12345 doesn't exist, the next name returned is again: -> **fna12345** +> **`fna12345`** -**_mktemp_s** can create a maximum of 26 unique file names for any given combination of *base* and *nameTemplate* values. Therefore, FNZ12345 is the last unique file name **_mktemp_s** can create for the *base* and *nameTemplate* values used in this example. +**`_mktemp_s`** can create a maximum of 26 unique file names for any given combination of *`base`* and *`nameTemplate`* values. Therefore, FNZ12345 is the last unique file name **`_mktemp_s`** can create for the *`base`* and *`nameTemplate`* values used in this example. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mktemp_s**|\| -|**_wmktemp_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_mktemp_s`** | \ | +| **`_wmktemp_s`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -146,7 +146,7 @@ int main() } ``` -### Sample Output +### Sample output ```Output Unique filename is fna03188 @@ -158,11 +158,11 @@ Unique filename is fne03188 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[_getmbcp](getmbcp.md)
-[_getpid](getpid.md)
-[_open, _wopen](open-wopen.md)
-[_setmbcp](setmbcp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
-[tmpfile_s](tmpfile-s.md)
+[File handling](../file-handling.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_getpid`](getpid.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_setmbcp`](setmbcp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ +[`tmpfile_s`](tmpfile-s.md) diff --git a/docs/c-runtime-library/reference/mktemp-wmktemp.md b/docs/c-runtime-library/reference/mktemp-wmktemp.md index 491523626e..651c61c016 100644 --- a/docs/c-runtime-library/reference/mktemp-wmktemp.md +++ b/docs/c-runtime-library/reference/mktemp-wmktemp.md @@ -3,16 +3,16 @@ description: "Learn more about: _mktemp, _wmktemp" title: "_mktemp, _wmktemp" ms.date: "4/2/2020" api_name: ["_wmktemp", "_mktemp", "_o__mktemp", "_o__wmktemp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tmktemp", "wmktemp", "tmktemp", "_wmktemp", "_mktemp"] helpviewer_keywords: ["_wmktemp function", "_mktemp function", "files [C++], temporary", "tmktemp function", "_tmktemp function", "wmktemp function", "mktemp function", "temporary files [C++]"] ms.assetid: 055eb539-a8c2-4a7d-be54-f5b6d1eb5c85 --- -# _mktemp, _wmktemp +# `_mktemp`, `_wmktemp` -Creates a unique file name. More secure versions of these functions are available; see [_mktemp_s, _wmktemp_s](mktemp-s-wmktemp-s.md). +Creates a unique file name. More secure versions of these functions are available; see [`_mktemp_s`, `_wmktemp_s`](mktemp-s-wmktemp-s.md). ## Syntax @@ -35,57 +35,57 @@ wchar_t *_wmktemp( ### Parameters -*nameTemplate*
+*`nameTemplate`*\ File name pattern. -## Return Value +## Return value -Each of these functions returns a pointer to the modified nameTemplate. The function returns **NULL** if *nameTemplate* is badly formed or no more unique names can be created from the given nameTemplate. +Each of these functions returns a pointer to the modified nameTemplate. The function returns `NULL` if *`nameTemplate`* is badly formed or no more unique names can be created from the given nameTemplate. ## Remarks -The **_mktemp** function creates a unique file name by modifying the *nameTemplate* argument. **_mktemp** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use by the run-time system. **_wmktemp** is a wide-character version of **_mktemp**; the argument and return value of **_wmktemp** are wide-character strings. **_wmktemp** and **_mktemp** behave identically otherwise, except that **_wmktemp** does not handle multibyte-character strings. +The **`_mktemp`** function creates a unique file name by modifying the *`nameTemplate`* argument. **`_mktemp`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use by the run-time system. **`_wmktemp`** is a wide-character version of **`_mktemp`**; the argument and return value of **`_wmktemp`** are wide-character strings. **`_wmktemp`** and **`_mktemp`** behave identically otherwise, except that **`_wmktemp`** doesn't handle multibyte-character strings. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tmktemp**|**_mktemp**|**_mktemp**|**_wmktemp**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tmktemp` | **`_mktemp`** | **`_mktemp`** | **`_wmktemp`** | -The *nameTemplate* argument has the form *base*XXXXXX, where *base* is the part of the new file name that you supply and each X is a placeholder for a character supplied by **_mktemp**. Each placeholder character in *nameTemplate* must be an uppercase X. **_mktemp** preserves *base* and replaces the first trailing X with an alphabetic character. **_mktemp** replaces the following trailing X's with a five-digit value; this value is a unique number identifying the calling process, or in multithreaded programs, the calling thread. +The *`nameTemplate`* argument has the form *`baseXXXXXX`*, where *`base`* is the part of the new file name that you supply and each X is a placeholder for a character supplied by **`_mktemp`**. Each placeholder character in *`nameTemplate`* must be an uppercase X. **`_mktemp`** preserves *`base`* and replaces the first trailing X with an alphabetic character. **`_mktemp`** replaces the trailing X characters with a five-digit value. This value is a unique number that identifies the calling process, or in multithreaded programs, the calling thread. -Each successful call to **_mktemp** modifies *nameTemplate*. In each subsequent call from the same process or thread with the same *nameTemplate* argument, **_mktemp** checks for file names that match names returned by **_mktemp** in previous calls. If no file exists for a given name, **_mktemp** returns that name. If files exist for all previously returned names, **_mktemp** creates a new name by replacing the alphabetic character it used in the previously returned name with the next available lowercase letter, in order, from 'a' through 'z'. For example, if *base* is: +Each successful call to **`_mktemp`** modifies *`nameTemplate`*. In each subsequent call from the same process or thread with the same *`nameTemplate`* argument, **`_mktemp`** checks for file names that match names returned by **`_mktemp`** in previous calls. If no file exists for a given name, **`_mktemp`** returns that name. If files exist for all previously returned names, **`_mktemp`** creates a new name by replacing the alphabetic character it used in the previously returned name with the next available lowercase letter, in order, from 'a' through 'z'. For example, if *`base`* is: -> **fn** +> **`fn`** -and the five-digit value supplied by **_mktemp** is 12345, the first name returned is: +and the five-digit value supplied by **`_mktemp`** is 12345, the first name returned is: -> **fna12345** +> **`fna12345`** -If this name is used to create file FNA12345 and this file still exists, the next name returned on a call from the same process or thread with the same *base* for *nameTemplate* is: +If this name is used to create file FNA12345 and this file still exists, the next name returned on a call from the same process or thread with the same *`base`* for *`nameTemplate`* is: -> **fnb12345** +> **`fnb12345`** -If FNA12345 does not exist, the next name returned is again: +If FNA12345 doesn't exist, the next name returned is again: -> **fna12345** +> **`fna12345`** -**_mktemp** can create a maximum of 26 unique file names for any given combination of *base* and *nameTemplate* values. Therefore, FNZ12345 is the last unique file name **_mktemp** can create for the *base* and *nameTemplate* values used in this example. +**`_mktemp`** can create a maximum of 26 unique file names for any given combination of *`base`* and *`nameTemplate`* values. Therefore, FNZ12345 is the last unique file name **`_mktemp`** can create for the *`base`* and *`nameTemplate`* values used in this example. -On failure, **errno** is set. If *nameTemplate* has an invalid format (for example, fewer than 6 X's), **errno** is set to **EINVAL**. If **_mktemp** is unable to create a unique name because all 26 possible file names already exist, **_mktemp** sets nameTemplate to an empty string and returns **EEXIST**. +On failure, `errno` is set. If *`nameTemplate`* has an invalid format (for example, fewer than six X characters), `errno` is set to `EINVAL`. If **`_mktemp`** is unable to create a unique name because all 26 possible file names already exist, **`_mktemp`** sets nameTemplate to an empty string and returns `EEXIST`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mktemp**|\| -|**_wmktemp**|\ or \| +| Routine | Required header | +|---|---| +| **`_mktemp`** | \ | +| **`_wmktemp`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -175,11 +175,11 @@ Out of unique filenames. ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[_getmbcp](getmbcp.md)
-[_getpid](getpid.md)
-[_open, _wopen](open-wopen.md)
-[_setmbcp](setmbcp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
-[tmpfile](tmpfile.md)
+[File handling](../file-handling.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_getpid`](getpid.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_setmbcp`](setmbcp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ +[`tmpfile`](tmpfile.md) diff --git a/docs/c-runtime-library/reference/mktemp.md b/docs/c-runtime-library/reference/mktemp.md index 13c68d0444..7ab3f79942 100644 --- a/docs/c-runtime-library/reference/mktemp.md +++ b/docs/c-runtime-library/reference/mktemp.md @@ -10,8 +10,8 @@ f1_keywords: ["mktemp"] helpviewer_keywords: ["mktemp function"] ms.assetid: b58cba60-034f-4e63-b312-ccbcd489d0a7 --- -# mktemp +# `mktemp` -The Microsoft-specific function name `mktemp` is a deprecated alias for the [_mktemp](mktemp-wmktemp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `mktemp` is a deprecated alias for the [`_mktemp`](mktemp-wmktemp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_mktemp](mktemp-wmktemp.md) or the security-enhanced [_mktemp_s](mktemp-s-wmktemp-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_mktemp`](mktemp-wmktemp.md) or the security-enhanced [`_mktemp_s`](mktemp-s-wmktemp-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md b/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md index 6e0d15c33d..51d9a4265a 100644 --- a/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md +++ b/docs/c-runtime-library/reference/mktime-mktime32-mktime64.md @@ -3,14 +3,13 @@ description: "Learn more about: mktime, _mktime32, _mktime64" title: "mktime, _mktime32, _mktime64" ms.date: "4/2/2020" api_name: ["_mktime32", "mktime", "_mktime64", "_o__mktime32", "_o__mktime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mktime", "_mktime64"] helpviewer_keywords: ["_mktime32 function", "mktime function", "time functions", "mktime64 function", "converting times", "mktime32 function", "_mktime64 function", "time, converting"] -ms.assetid: 284ed5d4-7064-48a2-bd50-15effdae32cf --- -# mktime, _mktime32, _mktime64 +# `mktime`, `_mktime32`, `_mktime64` Convert the local time to a calendar value. @@ -30,24 +29,24 @@ __time64_t _mktime64( ### Parameters -*timeptr*
-Pointer to time structure; see [asctime](asctime-wasctime.md). +*`timeptr`*\ +Pointer to time structure; see [`asctime`](asctime-wasctime.md). -## Return Value +## Return value -**_mktime32** returns the specified calendar time encoded as a value of type [time_t](../../c-runtime-library/standard-types.md). If *timeptr* references a date before midnight, January 1, 1970, or if the calendar time cannot be represented, **_mktime32** returns -1 cast to type **time_t**. When using **_mktime32** and if *timeptr* references a date after 23:59:59 January 18, 2038, Coordinated Universal Time (UTC), it will return -1 cast to type **time_t**. +**`_mktime32`** returns the specified calendar time encoded as a value of type [`time_t`](../standard-types.md). If *`timeptr`* references a date before midnight, January 1, 1970, or if the calendar time can't be represented, **`_mktime32`** returns -1 cast to type **`time_t`**. When using **`_mktime32`** and if *`timeptr`* references a date after 23:59:59 January 18, 2038, Coordinated Universal Time (UTC), it will return -1 cast to type **`time_t`**. -**_mktime64** will return -1 cast to type **__time64_t** if *timeptr* references a date after 23:59:59, December 31, 3000, UTC. +**`_mktime64`** will return -1 cast to type **`__time64_t`** if *`timeptr`* references a date after 23:59:59, December 31, 3000, UTC. ## Remarks -The **mktime**, **_mktime32** and **_mktime64** functions convert the supplied time structure (possibly incomplete) pointed to by *timeptr* into a fully defined structure with normalized values and then converts it to a **time_t** calendar time value. The converted time has the same encoding as the values returned by the [time](time-time32-time64.md) function. The original values of the **tm_wday** and **tm_yday** components of the *timeptr* structure are ignored, and the original values of the other components are not restricted to their normal ranges. +The **`mktime`**, **`_mktime32`** and **`_mktime64`** functions convert the supplied time structure (possibly incomplete) pointed to by *`timeptr`* into a fully defined structure with normalized values and then converts it to a **`time_t`** calendar time value. The converted time has the same encoding as the values returned by the [`time`](time-time32-time64.md) function. The original values of the **`tm_wday`** and **`tm_yday`** components of the *`timeptr`* structure are ignored, and the original values of the other components aren't restricted to their normal ranges. -**mktime** is an inline function that is equivalent to **_mktime64**, unless **_USE_32BIT_TIME_T** is defined, in which case it is equivalent to **_mktime32**. +**`mktime`** is an inline function that is equivalent to **`_mktime64`**, unless `_USE_32BIT_TIME_T` is defined, in which case it's equivalent to **`_mktime32`**. -After an adjustment to UTC, **_mktime32** handles dates from midnight, January 1, 1970, to 23:59:59 January 18, 2038, UTC. **_mktime64** handles dates from midnight, January 1, 1970 to 23:59:59, December 31, 3000. This adjustment may cause these functions to return -1 (cast to **time_t**, **__time32_t** or **__time64_t**) even though the date you specify is within range. For example, if you are in Cairo, Egypt, which is two hours ahead of UTC, two hours will first be subtracted from the date you specify in *timeptr*; this may now put your date out of range. +After an adjustment to UTC, **`_mktime32`** handles dates from midnight, January 1, 1970, to 23:59:59 January 18, 2038, UTC. **`_mktime64`** handles dates from midnight, January 1, 1970 to 23:59:59, December 31, 3000. This adjustment may cause these functions to return -1 (cast to **`time_t`**, **`__time32_t`** or **`__time64_t`**) even though the date you specify is within range. For example, if you are in Cairo, Egypt, which is two hours ahead of UTC, two hours will first be subtracted from the date you specify in *`timeptr`*; the subtraction may now put your date out of range. -These functions may be used to validate and fill in a tm structure. If successful, these functions set the values of **tm_wday** and **tm_yday** as appropriate and set the other components to represent the specified calendar time, but with their values forced to the normal ranges. The final value of **tm_mday** is not set until **tm_mon** and **tm_year** are determined. When specifying a **tm** structure time, set the **tm_isdst** field to: +These functions may be used to validate and fill in a `tm` structure. If successful, these functions set the values of **`tm_wday`** and **`tm_yday`** as appropriate and set the other components to represent the specified calendar time, but with their values forced to the normal ranges. The final value of **`tm_mday`** isn't set until **`tm_mon`** and **`tm_year`** are determined. When specifying a **`tm`** structure time, set the **`tm_isdst`** field to: - Zero (0) to indicate that standard time is in effect. @@ -55,27 +54,27 @@ These functions may be used to validate and fill in a tm structure. If successfu - A value less than zero to have the C run-time library code compute whether standard time or daylight saving time is in effect. -The C run-time library will determine the daylight savings time behavior from the [TZ](tzset.md) environment variable. If **TZ** is not set, the Win32 API call [GetTimeZoneInformation](/windows/win32/api/timezoneapi/nf-timezoneapi-gettimezoneinformation) is used to get the daylight savings time information from the operating system. If this fails, the library assumes the United States' rules for implementing the calculation of daylight saving time are used. **tm_isdst** is a required field. If not set, its value is undefined and the return value from these functions is unpredictable. If *timeptr* points to a **tm** structure returned by a previous call to [asctime](asctime-wasctime.md), [gmtime](gmtime-gmtime32-gmtime64.md), or [localtime](localtime-localtime32-localtime64.md) (or variants of these functions), the **tm_isdst** field contains the correct value. +The C run-time library will determine the daylight savings time behavior from the [`TZ`](tzset.md) environment variable. If **`TZ`** isn't set, the Win32 API call [`GetTimeZoneInformation`](/windows/win32/api/timezoneapi/nf-timezoneapi-gettimezoneinformation) is used to get the daylight savings time information from the operating system. If the call fails, the library assumes the United States' rules for implementing the calculation of daylight saving time are used. **`tm_isdst`** is a required field. If not set, its value is undefined and the return value from these functions is unpredictable. If *`timeptr`* points to a **`tm`** structure returned by a previous call to [`asctime`](asctime-wasctime.md), [`gmtime`](gmtime-gmtime32-gmtime64.md), or [`localtime`](localtime-localtime32-localtime64.md) (or variants of these functions), the **`tm_isdst`** field contains the correct value. -Note that **gmtime** and **localtime** (and **_gmtime32**, **_gmtime64**, **_localtime32**, and **_localtime64**) use a single buffer per thread for the conversion. If you supply this buffer to **mktime**, **_mktime32** or **_mktime64**, the previous contents are destroyed. +The **`gmtime`** and **`localtime`** (and **`_gmtime32`**, **`_gmtime64`**, **`_localtime32`**, and **`_localtime64`**) functions use a single buffer per thread for the conversion. If you supply this buffer to **`mktime`**, **`_mktime32`** or **`_mktime64`**, the previous contents are destroyed. -These functions validate their parameter. If *timeptr* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +These functions validate their parameter. If *`timeptr`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**mktime**|\| -|**_mktime32**|\| -|**_mktime64**|\| +| Routine | Required header | +|---|---| +| **`mktime`** | `` | +| **`_mktime32`** | `` | +| **`_mktime64`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -110,7 +109,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Current time is Fri Apr 25 13:34:07 2003 @@ -120,9 +119,9 @@ In 20 days the time will be Thu May 15 13:34:07 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[_mkgmtime, _mkgmtime32, _mkgmtime64](mkgmtime-mkgmtime32-mkgmtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`_mkgmtime`, `_mkgmtime32`, `_mkgmtime64`](mkgmtime-mkgmtime32-mkgmtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/modf-modff-modfl.md b/docs/c-runtime-library/reference/modf-modff-modfl.md index 1036949874..80f2a849e4 100644 --- a/docs/c-runtime-library/reference/modf-modff-modfl.md +++ b/docs/c-runtime-library/reference/modf-modff-modfl.md @@ -3,7 +3,7 @@ title: "modf, modff, modfl" description: "API reference for modf, modff, and modfl; which split a floating-point value into fractional and integer parts." ms.date: "1/15/2021" api_name: ["modff", "modf", "modfl", "_o_modf", "_o_modff"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["modff", "_modfl", "modf", "modfl", "math/modf", "math/modff", "math/modfl"] @@ -34,27 +34,27 @@ Floating-point value. *`intptr`*\ Pointer to stored integer portion. -## Return Value +## Return value This function returns the signed fractional portion of *`x`*. There's no error return. ## Remarks -The **modf** functions break down the floating-point value *`x`* into fractional and integer parts, each of which has the same sign as *`x`*. The signed fractional portion of *`x`* is returned. The integer portion is stored as a floating-point value at *`intptr`*. +The **`modf`** functions break down the floating-point value *`x`* into fractional and integer parts, each of which has the same sign as *`x`*. The signed fractional portion of *`x`* is returned. The integer portion is stored as a floating-point value at *`intptr`*. -**modf** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). See [`_set_SSE2_enable`](set-sse2-enable.md) for information and restrictions on using the SSE2 implementation. +**`modf`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). See [`_set_SSE2_enable`](set-sse2-enable.md) for information and restrictions on using the SSE2 implementation. C++ allows overloading, so you can call overloads of **`modf`** that take and return **`float`** or **`long double`** parameters. In a C program, **`modf`** always takes two double values and returns a double value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`modf`**, **`modff`**, **`modfl`**|C: ``

C++: , `` or ``| +| Routine | Required header | +|---|---| +| **`modf`**, **`modff`**, **`modfl`** | C: ``

C++: , `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -82,6 +82,6 @@ For -14.876543, the fraction is -0.876543 and the integer is -14 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`frexp`](frexp.md)\ [`ldexp`](ldexp.md) diff --git a/docs/c-runtime-library/reference/msize-dbg.md b/docs/c-runtime-library/reference/msize-dbg.md index 2d36d246e4..01ea05ea49 100644 --- a/docs/c-runtime-library/reference/msize-dbg.md +++ b/docs/c-runtime-library/reference/msize-dbg.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_msize_dbg", "msize_dbg"] helpviewer_keywords: ["memory blocks", "_msize_dbg function", "msize_dbg function"] -ms.assetid: a333f4b6-f8a2-4e61-bb69-cb34063b8cef --- -# _msize_dbg +# `_msize_dbg` Calculates the size of a block of memory in the heap (debug version only). @@ -25,35 +24,35 @@ size_t _msize_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the memory block for which to determine the size. -*blockType*
-Type of the specified memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Type of the specified memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -## Return Value +## Return value -On successful completion, **_msize_dbg** returns the size (in bytes) of the specified memory block; otherwise it returns **NULL**. +On successful completion, **`_msize_dbg`** returns the size (in bytes) of the specified memory block; otherwise it returns `NULL`. ## Remarks -**_msize_dbg** is a debug version of the _[msize](msize.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_msize_dbg** is reduced to a call to **_msize**. Both **_msize** and **_msize_dbg** calculate the size of a memory block in the base heap, but **_msize_dbg** adds two debugging features: It includes the buffers on either side of the user portion of the memory block in the returned size and it allows size calculations for specific block types. +**`_msize_dbg`** is a debug version of the _[`msize`](msize.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_msize_dbg`** is reduced to a call to `_msize`. Both `_msize` and **`_msize_dbg`** calculate the size of a memory block in the base heap, but **`_msize_dbg`** adds two debugging features: It includes the buffers on either side of the user portion of the memory block in the returned size and it allows size calculations for specific block types. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and the debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). -This function validates its parameter. If *memblock* is a null pointer, **_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer, **`_msize_dbg`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1 (18,446,744,073,709,551,615 unsigned). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_msize_dbg**|\| +| Routine | Required header | +|---|---| +| **`_msize_dbg`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -116,5 +115,5 @@ Size of block after _realloc_dbg of 40 more longs: 320 ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/msize.md b/docs/c-runtime-library/reference/msize.md index ffd147adb4..b5d1cad10b 100644 --- a/docs/c-runtime-library/reference/msize.md +++ b/docs/c-runtime-library/reference/msize.md @@ -1,16 +1,15 @@ --- description: "Learn more about: _msize" title: "_msize" -ms.date: "4/2/2020" +ms.date: 07/26/2024 api_name: ["_msize", "_o__msize"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["msize", "_msize"] helpviewer_keywords: ["memory blocks", "msize function", "_msize function"] -ms.assetid: 02b1f89e-d0d7-4f12-938a-9eeba48a0f88 --- -# _msize +# `_msize` Returns the size of a memory block allocated in the heap. @@ -24,43 +23,43 @@ size_t _msize( ### Parameters -*memblock*
+*`memblock`*\ Pointer to the memory block. -## Return Value +## Return value -**_msize** returns the size (in bytes) as an unsigned integer. +**`_msize`** returns the size (in bytes) as an unsigned integer. ## Remarks -The **_msize** function returns the size, in bytes, of the memory block allocated by a call to **calloc**, **malloc**, or **realloc**. +The **`_msize`** function returns the size, in bytes, of the memory block allocated by a call to **`calloc`**, **`malloc`**, or **`realloc`**. -When the application is linked with a debug version of the C run-time libraries, **_msize** resolves to [_msize_dbg](msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_msize`** resolves to [`_msize_dbg`](msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -This function validates its parameter. If *memblock* is a null pointer, **_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a `NULL` pointer, **`_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1 (18,446,744,073,709,551,615 unsigned). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_msize**|\| +| Routine | Required header | +|---|---| +| **`_msize`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [realloc](realloc.md). +See the example for [`realloc`](realloc.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[_expand](expand.md)
-[malloc](malloc.md)
-[realloc](realloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`_expand`](expand.md)\ +[`malloc`](malloc.md)\ +[`realloc`](realloc.md) diff --git a/docs/c-runtime-library/reference/nan-nanf-nanl.md b/docs/c-runtime-library/reference/nan-nanf-nanl.md index 39baaf3cb8..a47582fbe3 100644 --- a/docs/c-runtime-library/reference/nan-nanf-nanl.md +++ b/docs/c-runtime-library/reference/nan-nanf-nanl.md @@ -3,14 +3,14 @@ description: "Learn more about: nan, nanf, nanl" title: "nan, nanf, nanl" ms.date: "4/2/2020" api_name: ["nanf", "nan", "nanl", "_o_nan", "_o_nanf", "_o_nanl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nan", "nanl", "nanf"] helpviewer_keywords: ["nan function", "nanf function", "nanl function"] ms.assetid: 790e9158-80ab-43e0-8f5a-096198553fd9 --- -# nan, nanf, nanl +# `nan`, `nanf`, `nanl` Returns a quiet NaN value. @@ -24,31 +24,31 @@ long double nanl( const char* input ); ### Parameters -*input*
+*`input`*\ A string value. -## Return Value +## Return value -The **nan** functions return a quiet NaN value. +The **`nan`** functions return a quiet NaN value. ## Remarks -The **nan** functions return a floating-point value that corresponds to a quiet (non-signalling) NaN. The *input* value is ignored. For information about how a NaN is represented for output, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +The **`nan`** functions return a floating-point value that corresponds to a quiet (non-signalling) NaN. The *`input`* value is ignored. For information about how a NaN is represented for output, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**nan**, **nanf**, **nanl**|\|\ or \| +| Function | C header | C++ header | +|---|---|---| +| **`nan`**, **`nanf`**, **`nanl`** | \ | \ or \ | ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md index d36068eec7..17a159e822 100644 --- a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md +++ b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md @@ -3,14 +3,14 @@ title: "nearbyint, nearbyintf, nearbyintl" description: "API reference for nearbyint, nearbyintf, and nearbyintl; which rounds the specified floating-point value to an integer, and returns that value in a floating-point format." ms.date: "9/1/2020" api_name: ["nearbyint", "nearbyintf", "nearbyintl", "_o_nearbyint", "_o_nearbyintf", "_o_nearbyintl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nearbyint", "nearbyintf", "nearbyintl", "math/nearbyint", "math/narbyintf", "math/narbyintl"] helpviewer_keywords: ["nearbyint function", "nearbyintf function", "nearbyintl function"] ms.assetid: dd39cb68-96b0-434b-820f-6ff2ea65584f --- -# nearbyint, nearbyintf, nearbyintl +# `nearbyint`, `nearbyintf`, `nearbyintl` Rounds the specified floating-point value to an integer, and returns that value in a floating-point format. @@ -28,43 +28,43 @@ long double nearbyint( long double x ); //C++ only ### Parameters -*x*\ +*`x`*\ The value to round. -## Return Value +## Return value -If successful, returns *x*, rounded to the nearest integer, using the current rounding format as reported by [fegetround](fegetround-fesetround2.md). Otherwise, the function may return one of the following values: +If successful, returns *`x`*, rounded to the nearest integer, using the current rounding format as reported by [`fegetround`](fegetround-fesetround2.md). Otherwise, the function may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±INFINITY|±INFINITY, unmodified| -|*x* = ±0|±0, unmodified| -|*x* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = ±INFINITY | ±INFINITY, unmodified | +| *`x`* = ±0 | ±0, unmodified | +| *`x`* = NaN | NaN | -Errors are not reported through [_matherr](matherr.md); specifically, this function does not report any **FE_INEXACT** exceptions. +Errors aren't reported through [`_matherr`](matherr.md); specifically, this function doesn't report any `FE_INEXACT` exceptions. ## Remarks -The primary difference between this function and [rint](rint-rintf-rintl.md) is that this function does not raise the inexact floating point exception. +The primary difference between this function and [`rint`](rint-rintf-rintl.md) is that this function doesn't raise the inexact floating point exception. Because the maximum floating-point values are exact integers, this function will never overflow by itself; rather, the output may overflow the return value, depending on which version of the function you use. -C++ allows overloading, so you can call overloads of **nearbyint** that take and return **`float`** or **`long double`** parameters. In a C program, unless you're using the \ macro to call this function, **nearbyint** always takes two double values and returns a double value. +C++ allows overloading, so you can call overloads of **`nearbyint`** that take and return **`float`** or **`long double`** parameters. In a C program, unless you're using the \ macro to call this function, **`nearbyint`** always takes two double values and returns a double value. -If you use the \ `nearbyint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `nearbyint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**nearbyint**, **nearbyintf**, **nearbyintl**|\|\ or \| -|**nearbyint** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`nearbyint`**, **`nearbyintf`**, **`nearbyintl`** | \ | \ or \ | +| **`nearbyint`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[Math and floating-point support](../floating-point-support.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[Math and floating-point support](../floating-point-support.md) diff --git a/docs/c-runtime-library/reference/nextafter-functions.md b/docs/c-runtime-library/reference/nextafter-functions.md index b02d6828a2..f4945d818e 100644 --- a/docs/c-runtime-library/reference/nextafter-functions.md +++ b/docs/c-runtime-library/reference/nextafter-functions.md @@ -3,7 +3,7 @@ title: "nextafter, nextafterf, nextafterl, _nextafter, _nextafterf, nexttoward, description: "API reference for nextafter, nextafterf, nextafterl, _nextafter, _nextafterf, nexttoward, nexttowardf, and nexttowardl; which return the next representable floating-point value." ms.date: "1/15/2021" api_name: ["nextafterf", "_nextafterf", "nextafter", "nextafterl", "_nextafter", "nexttoward", "nexttowardf", "nexttowardl", "_o__nextafter", "_o_nextafter", "_o_nextafterf", "_o_nextafterl", "_o_nexttoward", "_o_nexttowardf", "_o_nexttowardl", "_o__nextafterf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nextafter", "_nextafter", "nextafterf", "nextafterl", "_nextafterf", "math/nextafter", "math/nextafterf", "math/nextafterl", "nexttoward", "nexttowardf", "nexttowardl", "math/nexttoward", "math/nexttowardf", "math/nexttowardl"] @@ -46,9 +46,9 @@ The floating-point value to start from. *`y`*\ The floating-point value to go towards. -## Return Value +## Return value -Returns the next representable floating-point value of the return type after *`x`* in the direction of *`y`*. If *`x`* and *`y`* are equal, the function returns *`y`*, converted to the return type, with no exception triggered. If *`x`* is not equal to *`y`*, and the result is a denormal or zero, the **`FE_UNDERFLOW`** and **`FE_INEXACT`** floating-point exception states are set, and the correct result is returned. If either *`x`* or *`y`* is a NAN, then the return value is one of the input NANs. If *`x`* is finite and the result is infinite or not representable in the type, a correctly signed infinity or NAN is returned, the **`FE_OVERFLOW`** and **`FE_INEXACT`** floating-point exception states are set, and **`errno`** is set to **`ERANGE`**. +Returns the next representable floating-point value of the return type after *`x`* in the direction of *`y`*. If *`x`* and *`y`* are equal, the function returns *`y`*, converted to the return type, with no exception triggered. If *`x`* isn't equal to *`y`*, and the result is a denormal or zero, the `FE_UNDERFLOW` and `FE_INEXACT` floating-point exception states are set, and the correct result is returned. If either *`x`* or *`y`* is a NAN, then the return value is one of the input NANs. If *`x`* is finite and the result is infinite or not representable in the type, a correctly signed infinity or NAN is returned, the `FE_OVERFLOW` and `FE_INEXACT` floating-point exception states are set, and `errno` is set to `ERANGE`. ## Remarks @@ -56,23 +56,23 @@ The **`nextafter`** and **`nexttoward`** function families are equivalent, excep Because C++ allows overloading, if you include `` you can call overloads of **`nextafter`** and **`nexttoward`** that return **`float`** and **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`nextafter`** and **`nexttoward`** always return **`double`**. -If you use the `` `nextafter()` or `nexttoward()`macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `nextafter` or `nexttoward` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -The **_nextafter** and **_nextafterf** functions are Microsoft-specific. The **_nextafterf** function is only available when compiling for x64. +The **`_nextafter`** and **`_nextafterf`** functions are Microsoft-specific. The **`_nextafterf`** function is only available when compiling for x64. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------------|-------------------------------| -|**`nextafter`**, **`nextafterf`**, **`nextafterl`**, **`_nextafterf`**, **`nexttoward`**, **`nexttowardf`**, **`nexttowardl`**|``|`` or ``| -|**`_nextafter`**|``|`` or ``| -|**`nextafter`** macro, **`nexttoward`** macro| `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`nextafter`**, **`nextafterf`**, **`nextafterl`**, **`_nextafterf`**, **`nexttoward`**, **`nexttowardf`**, **`nexttowardl`** | `` | `` or `` | +| **`_nextafter`** | `` | `` or `` | +| **`nextafter`** macro, **`nexttoward`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md) diff --git a/docs/c-runtime-library/reference/norm-normf-norml1.md b/docs/c-runtime-library/reference/norm-normf-norml1.md index e86dff978c..5115c675ab 100644 --- a/docs/c-runtime-library/reference/norm-normf-norml1.md +++ b/docs/c-runtime-library/reference/norm-normf-norml1.md @@ -10,7 +10,7 @@ f1_keywords: ["norm", "normf", "norml", "complex/norm", "complex/normf", "comple helpviewer_keywords: ["norm function", "normf function", "norml function"] ms.assetid: 9786ecfe-0019-4553-b378-0af6c691e15c --- -# norm, normf, norml +# `norm`, `normf`, `norml` Retrieves the squared magnitude of a complex number. @@ -29,31 +29,31 @@ long double norm( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The squared magnitude of *z*. +The squared magnitude of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **norm** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, **norm** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`norm`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, **`norm`** always takes a `_Dcomplex` value and returns a **`double`** value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**norm**, **normf**, **norml**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`norm`**, **`normf`**, **`norml`** | \ | \ | -The **_Fcomplex**, **_Dcomplex**, and **_Lcomplex** types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The `_Fcomplex`, `_Dcomplex`, and `_Lcomplex` types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/not-eq.md b/docs/c-runtime-library/reference/not-eq.md index 99a9fae214..90877cd219 100644 --- a/docs/c-runtime-library/reference/not-eq.md +++ b/docs/c-runtime-library/reference/not-eq.md @@ -1,55 +1,59 @@ --- description: "Learn more about: not_eq" title: "not_eq" -ms.date: "11/04/2016" +ms.date: 08/09/2024 api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["not_eq", "std::not_eq", "std.not_eq"] +f1_keywords: ["ISO646/not_eq", "not_eq", "std::not_eq", "std.not_eq"] helpviewer_keywords: ["not_eq function"] -ms.assetid: d87ad299-8b50-4393-a57f-06f70e1f23fb --- -# not_eq +# `not_eq` -An alternative to the != operator. +An alternative spelling for the **`!=`** operator. ## Syntax ```C - #define not_eq != ``` ## Remarks -The macro yields the operator !=. +C++: +- **`not_eq`** can be used as alternative to **`!=`**. The [`/permissive-`](../../build/reference/permissive-standards-conformance.md) or [`/Za`](../../build/reference/za-ze-disable-language-extensions.md) compiler option is required. +- Including `` or `` is deprecated. You can use the alternative spelling without including any header files. +- There's no alternative spelling for **`==`**. + +C: +- **`not_eq`** is an alternative spelling for **`!=`**. It is provided as a macro in ``, which you must `#include`. +- There's no alternative spelling for **`==`**. ## Example ```cpp -// iso646_not_eq.cpp // compile with: /EHsc #include #include int main( ) { - using namespace std; - int a = 0, b = 1; - - if (a != b) - cout << "a is not equal to b" << endl; - - if (a not_eq b) - cout << "a is not equal to b" << endl; + int x = 1, y = 2; + + // not_eq is available in C++ and C + // This example is for C++, so no header file is needed to use not_eq + // When compiling for C, #include to use not_eq + if (x not_eq y) + { + std::cout << "Not equal\n"; + } } ``` ```Output -a is not equal to b -a is not equal to b +Not equal ``` ## Requirements -**Header:** \ +**Header:** `` is necessary if you are compiling for C. \ No newline at end of file diff --git a/docs/c-runtime-library/reference/not.md b/docs/c-runtime-library/reference/not.md index 19dfab113a..a878828337 100644 --- a/docs/c-runtime-library/reference/not.md +++ b/docs/c-runtime-library/reference/not.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: not" title: "not" +description: "Learn more about: not" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::not", "std.not", "Not"] +f1_keywords: ["std::not", "std.not", "ISO646/not", "not"] helpviewer_keywords: ["not function"] -ms.assetid: d2ddbd5c-33c0-4aff-8961-feac155b4ba1 --- -# not +# `not` -An alternative to the ! operator. +An alternative to the **`!`** operator. ## Syntax ```C - #define not ! ``` ## Remarks -The macro yields the operator !. +The macro yields the operator **`!`**. ## Example diff --git a/docs/c-runtime-library/reference/offsetof-macro.md b/docs/c-runtime-library/reference/offsetof-macro.md index 7ebcc5cd60..1d200208d6 100644 --- a/docs/c-runtime-library/reference/offsetof-macro.md +++ b/docs/c-runtime-library/reference/offsetof-macro.md @@ -9,7 +9,7 @@ f1_keywords: ["offsetof"] helpviewer_keywords: ["structure members, offset", "offsetof macro"] ms.assetid: f3b4eb16-a882-4d38-afc9-eebd976a7352 --- -# offsetof Macro +# `offsetof` Macro Retrieves the offset of a member from the beginning of its parent structure. @@ -24,35 +24,35 @@ size_t offsetof( ### Parameters -*structName*
+*`structName`*\ Name of the parent data structure. -*memberName*
+*`memberName`*\ Name of the member in the parent data structure for which to determine the offset. -## Return Value +## Return value -**offsetof** returns the offset in bytes of the specified member from the beginning of its parent data structure. It is undefined for bit fields. +**`offsetof`** returns the offset in bytes of the specified member from the beginning of its parent data structure. It's undefined for bit fields. ## Remarks -The **offsetof** macro returns the offset in bytes of *memberName* from the beginning of the structure specified by *structName* as a value of type **size_t**. You can specify types with the **`struct`** keyword. +The **`offsetof`** macro returns the offset in bytes of *`memberName`* from the beginning of the structure specified by *`structName`* as a value of type `size_t`. You can specify types with the **`struct`** keyword. > [!NOTE] -> **offsetof** is not a function and cannot be described using a C prototype. +> **`offsetof`** is not a function and cannot be described using a C prototype. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**offsetof**|\| +| Routine | Required header | +|---|---| +| **`offsetof`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/onexit-onexit-m.md b/docs/c-runtime-library/reference/onexit-onexit-m.md index fcbfd85e5b..304be260d3 100644 --- a/docs/c-runtime-library/reference/onexit-onexit-m.md +++ b/docs/c-runtime-library/reference/onexit-onexit-m.md @@ -10,7 +10,7 @@ f1_keywords: ["_onexit", "onexit_m", "onexit", "_onexit_m"] helpviewer_keywords: ["onexit function", "registry, registering exit routines", "_onexit_m function", "onexit_m function", "_onexit function", "registering exit routines", "registering to be called on exit"] ms.assetid: 45743298-0e2f-46cf-966d-1ca44babb443 --- -# _onexit, _onexit_m +# `_onexit`, `_onexit_m` Registers a routine to be called at exit time. @@ -27,28 +27,28 @@ _onexit_t_m _onexit_m( ### Parameters -*function*
+*`function`*\ Pointer to a function to be called at exit. -## Return Value +## Return value -**_onexit** returns a pointer to the function if successful or **NULL** if there is no space to store the function pointer. +**`_onexit`** returns a pointer to the function if successful or `NULL` if there's no space to store the function pointer. ## Remarks -The **_onexit** function is passed the address of a function (*function*) to be called when the program terminates normally. Successive calls to **_onexit** create a register of functions that are executed in LIFO (last-in-first-out) order. The functions passed to **_onexit** cannot take parameters. +The **`_onexit`** function is passed the address of a function (*`function`*) to be called when the program terminates normally. Successive calls to **`_onexit`** create a register of functions that are executed in LIFO (last-in-first-out) order. The functions passed to **`_onexit`** can't take parameters. -In the case when **_onexit** is called from within a DLL, routines registered with **_onexit** run on a DLL's unloading after **DllMain** is called with DLL_PROCESS_DETACH. +In the case when **`_onexit`** is called from within a DLL, routines registered with **`_onexit`** run when the DLL is unloaded, after `DllMain` is called with `DLL_PROCESS_DETACH`. -**_onexit** is a Microsoft extension. For ANSI portability, use [atexit](atexit.md). The **_onexit_m** version of the function is for mixed mode use. +**`_onexit`** is a Microsoft extension. For ANSI portability, use [`atexit`](atexit.md). The **`_onexit_m`** version of the function is for mixed mode use. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_onexit**|\| +| Routine | Required header | +|---|---| +| **`_onexit`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,7 +104,7 @@ This is executed next. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[__dllonexit](../../c-runtime-library/dllonexit.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`__dllonexit`](../dllonexit.md) diff --git a/docs/c-runtime-library/reference/open-osfhandle.md b/docs/c-runtime-library/reference/open-osfhandle.md index 3d5c6f0461..6ea534a28c 100644 --- a/docs/c-runtime-library/reference/open-osfhandle.md +++ b/docs/c-runtime-library/reference/open-osfhandle.md @@ -3,14 +3,13 @@ description: "Learn more about: _open_osfhandle" title: "_open_osfhandle" ms.date: "4/2/2020" api_name: ["_open_osfhandle", "_o__open_osfhandle"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_open_osfhandle", "open_osfhandle"] helpviewer_keywords: ["open_osfhandle function", "file handles [C++], associating", "_open_osfhandle function"] -ms.assetid: 30d94df4-7868-4667-a401-9eb67ecb7855 --- -# _open_osfhandle +# `_open_osfhandle` Associates a C run-time file descriptor with an existing operating system file handle. @@ -25,42 +24,42 @@ int _open_osfhandle ( ### Parameters -*osfhandle*
+*`osfhandle`*\ Operating system file handle. -*flags*
+*`flags`*\ Types of operations allowed. -## Return Value +## Return value -If successful, **_open_osfhandle** returns a C run-time file descriptor. Otherwise, it returns -1. +If successful, **`_open_osfhandle`** returns a C run-time file descriptor. Otherwise, it returns -1. ## Remarks -The **_open_osfhandle** function allocates a C run-time file descriptor. It associates this file descriptor with the operating system file handle specified by *osfhandle*. To avoid a compiler warning, cast the *osfhandle* argument from **HANDLE** to **intptr_t**. The *flags* argument is an integer expression formed from one or more of the manifest constants defined in \. You can use the bitwise-OR operator ( **|** ) to combine two or more manifest constants to form the *flags* argument. +The **`_open_osfhandle`** function allocates a C run-time file descriptor. It associates this file descriptor with the operating system file handle specified by *`osfhandle`*. To avoid a compiler warning, cast the *`osfhandle`* argument from `HANDLE` to **`intptr_t`**. The *`flags`* argument is an integer expression formed from one or more of the manifest constants defined in ``. You can use the bitwise "or" (`|`) operator to combine two or more manifest constants to form the *`flags`* argument. -These manifest constants are defined in \: +These manifest constants are defined in ``: | Constant | Description | |--|--| -| **\_O\_APPEND** | Positions a file pointer to the end of the file before every write operation. | -| **\_O\_RDONLY** | Opens the file for reading only. | -| **\_O\_TEXT** | Opens the file in text (translated) mode. | -| **\_O\_WTEXT** | Opens the file in Unicode (translated UTF-16) mode. | +| `_O_APPEND` | Positions a file pointer to the end of the file before every write operation. | +| `_O_RDONLY` | Opens the file for reading only. | +| `_O_TEXT` | Opens the file in ANSI text (translated) mode. | +| `_O_WTEXT` | Opens the file in Unicode (translated UTF-16) mode. | -The **_open_osfhandle** call transfers ownership of the Win32 file handle to the file descriptor. To close a file opened by using **_open_osfhandle**, call [\_close](close.md). The underlying OS file handle is also closed by a call to **_close**. Don't call the Win32 function **CloseHandle** on the original handle. If the file descriptor is owned by a `FILE *` stream, then a call to [fclose](fclose-fcloseall.md) closes both the file descriptor and the underlying handle. In this case, don't call **_close** on the file descriptor or **CloseHandle** on the original handle. +The **`_open_osfhandle`** call transfers ownership of the Win32 file handle to the file descriptor. To close a file opened by using **`_open_osfhandle`**, call [`_close`](close.md). The underlying OS file handle is also closed by a call to **`_close`**. Don't call the Win32 function `CloseHandle` on the original handle. If the file descriptor is owned by a `FILE *` stream, then a call to [`fclose`](fclose-fcloseall.md) closes both the file descriptor and the underlying handle. In this case, don't call **`_close`** on the file descriptor or `CloseHandle` on the original handle. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_open_osfhandle**|\| +| Routine | Required header | +|---|---| +| **`_open_osfhandle`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[\_get_osfhandle](get-osfhandle.md) +[File handling](../file-handling.md)\ +[`_get_osfhandle`](get-osfhandle.md) diff --git a/docs/c-runtime-library/reference/open-wopen.md b/docs/c-runtime-library/reference/open-wopen.md index 58b0f687cf..6b72d3b25f 100644 --- a/docs/c-runtime-library/reference/open-wopen.md +++ b/docs/c-runtime-library/reference/open-wopen.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _open, _wopen" title: "_open, _wopen" -ms.date: "11/04/2016" +ms.date: 05/18/2022 api_name: ["_open", "_wopen"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wopen", "_topen", "_open"] +f1_keywords: ["CORECRT_IO/_open", "CORECRT_WIO/_wopen", "TCHAR/_topen", "_open", "_wopen", "_topen"] helpviewer_keywords: ["opening files, for file I/O", "topen function", "_open function", "_topen function", "_wopen function", "files [C++], opening", "wopen function", "open function"] ms.assetid: 13f6a0c3-d1aa-450d-a7aa-74abc91b163e --- @@ -31,95 +31,95 @@ int _wopen( ### Parameters -*`filename`*
+*`filename`*\ File name. -*`oflag`*
+*`oflag`*\ The kind of operations allowed. -*`pmode`*
+*`pmode`*\ Permission mode. -## Return Value +## Return value -Each of these functions returns a file descriptor for the opened file. A return value of -1 indicates an error; in that case **`errno`** is set to one of the following values. +Each of these functions returns a file descriptor for the opened file. A return value of -1 indicates an error; in that case `errno` is set to one of the following values. -|errno value|Condition| -|-|-| -| **`EACCES`** | Tried to open a read-only file for writing, file's sharing mode does not allow the specified operations, or the given path is a directory. | -| **`EEXIST`** | **`_O_CREAT`** and **`_O_EXCL`** flags specified, but *`filename`* already exists. | -| **`EINVAL`** | Invalid *`oflag`* or *`pmode`* argument. | -| **`EMFILE`** | No more file descriptors are available (too many files are open). | -| **`ENOENT`** | File or path not found. | +| `errno` value | Condition | +|--|--| +| `EACCES` | Tried to open a read-only file for writing, file's sharing mode doesn't allow the specified operations, or the given path is a directory. | +| `EEXIST` | `_O_CREAT` and `_O_EXCL` flags specified, but *`filename`* already exists. | +| `EINVAL` | Invalid *`oflag`* or *`pmode`* argument. | +| `EMFILE` | No more file descriptors are available (too many files are open). | +| `ENOENT` | File or path not found. | -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_open`** function opens the file specified by *`filename`* and prepares it for reading or writing, as specified by *`oflag`*. **`_wopen`** is a wide-character version of **`_open`**; the *`filename`* argument to **`_wopen`** is a wide-character string. **`_wopen`** and **`_open`** behave identically otherwise. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_topen`**|**`_open`**|**`_open`**|**`_wopen`**| +| `` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_topen`** | **`_open`** | **`_open`** | **`_wopen`** | *`oflag`* is an integer expression formed from one or more of the following manifest constants or constant combinations, which are defined in ``. -|*`oflag`* constant|Behavior| -|-|-| -| **`_O_APPEND`** | Moves the file pointer to the end of the file before every write operation. | -| **`_O_BINARY`** | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | -| **`_O_CREAT`** | Creates a file and opens it for writing. Has no effect if the file specified by *filename* exists. The *pmode* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | **`_O_SHORT_LIVED`** | Creates a file as temporary and if possible does not flush to disk. The *pmode* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | `_O_EXCL` | Returns an error value if a file specified by *filename* exists. Applies only when used with **`_O_CREAT`**. | -| **`_O_NOINHERIT`** | Prevents creation of a shared file descriptor. | -| **`_O_RANDOM`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`_O_RDONLY`** | Opens a file for reading only. Cannot be specified with **`_O_RDWR`** or **`_O_WRONLY`**. | -| **`_O_RDWR`** | Opens a file for both reading and writing. Cannot be specified with **`_O_RDONLY`** or **`_O_WRONLY`**. | -| **`_O_SEQUENTIAL`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | -| **`_O_TEXT`** | Opens a file in text (translated) mode. (For more information, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | -| **`_O_TRUNC`** | Opens a file and truncates it to zero length; the file must have write permission. Cannot be specified with **`_O_RDONLY`**. **`_O_TRUNC`** used with **`_O_CREAT`** opens an existing file or creates a file. **Note:** The **`_O_TRUNC`** flag destroys the contents of the specified file. | -| **`_O_WRONLY`** | Opens a file for writing only. Cannot be specified with **`_O_RDONLY`** or **`_O_RDWR`**. | -| **`_O_U16TEXT`** | Opens a file in Unicode UTF-16 mode. | -| **`_O_U8TEXT`** | Opens a file in Unicode UTF-8 mode. | -| **`_O_WTEXT`** | Opens a file in Unicode mode. | +| *`oflag`* constant | Behavior | +|--|--| +| `_O_APPEND` | Moves the file pointer to the end of the file before every write operation. | +| `_O_BINARY` | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | +| `_O_CREAT` | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_SHORT_LIVED`** | Creates a file as temporary and if possible doesn't flush to disk. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when `_O_CREAT` is specified. To preserve legacy behavior for app-compatibility, other processes aren't prevented from deleting this file. | +| **`_O_CREAT | _O_EXCL`** | Returns an error value if a file specified by *`filename`* exists. Applies only when used with `_O_CREAT`. | +| `_O_NOINHERIT` | Prevents creation of a shared file descriptor. | +| `_O_RANDOM` | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| `_O_RDONLY` | Opens a file for reading only. Can't be specified with `_O_RDWR` or `_O_WRONLY`. | +| `_O_RDWR` | Opens a file for both reading and writing. Can't be specified with `_O_RDONLY` or `_O_WRONLY`. | +| `_O_SEQUENTIAL` | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| `_O_TEXT` | Opens a file in ANSI text (translated) mode. (For more information, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | +| `_O_TRUNC` | Opens a file and truncates it to zero length; the file must have write permission. Can't be specified with `_O_RDONLY`. `_O_TRUNC` used with `_O_CREAT` opens an existing file or creates a file. **Note:** The `_O_TRUNC` flag destroys the contents of the specified file. | +| `_O_WRONLY` | Opens a file for writing only. Can't be specified with `_O_RDONLY` or `_O_RDWR`. | +| `_O_U16TEXT` | Opens a file in Unicode UTF-16 mode. | +| `_O_U8TEXT` | Opens a file in Unicode UTF-8 mode. | +| `_O_WTEXT` | Opens a file in Unicode mode. | -To specify the file access mode, you must specify either **`_O_RDONLY`**, **`_O_RDWR`**, or **`_O_WRONLY`**. There is no default value for the access mode. +To specify the file access mode, you must specify either `_O_RDONLY`, `_O_RDWR`, or `_O_WRONLY`. There's no default value for the access mode. -If **`_O_WTEXT`** is used to open a file for reading, **`_open`** reads the beginning of the file and checks for a byte order mark (BOM). If there is a BOM, the file is treated as UTF-8 or UTF-16LE, depending on the BOM. If no BOM is present, the file is treated as ANSI. When a file is opened for writing by using **`_O_WTEXT`**, UTF-16 is used. Regardless of any previous setting or byte order mark, if **`_O_U8TEXT`** is used, the file is always opened as UTF-8; if **`_O_U16TEXT`** is used, the file is always opened as UTF-16. +If `_O_WTEXT` is used to open a file for reading, **`_open`** reads the beginning of the file and checks for a byte order mark (BOM). If there's a BOM, the file is treated as UTF-8 or UTF-16LE, depending on the BOM. If no BOM is present, the file is treated as ANSI. When a file is opened for writing by using `_O_WTEXT`, UTF-16 is used. Regardless of any previous setting or byte order mark, if `_O_U8TEXT` is used, the file is always opened as UTF-8; if `_O_U16TEXT` is used, the file is always opened as UTF-16. -When a file is opened in Unicode mode by using **`_O_WTEXT`**, **`_O_U8TEXT`**, or **`_O_U16TEXT`**, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it is written, and the file's UTF-8-encoded content is translated into UTF-16 when it is read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You are responsible for any required encoding translation. +When a file is opened in Unicode mode by using `_O_WTEXT`, `_O_U8TEXT`, or `_O_U16TEXT`, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If **`_open`** is called with **`_O_WRONLY`** | **`_O_APPEND`** (append mode) and **`_O_WTEXT`**, **`_O_U16TEXT`**, or **`_O_U8TEXT`**, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. +If **`_open`** is called with **`_O_WRONLY | _O_APPEND`** (append mode) and `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. -When two or more manifest constants are used to form the *`oflag`* argument, the constants are combined with the bitwise-OR operator ( **|** ). For a discussion of binary and text modes, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +When two or more manifest constants are used to form the *`oflag`* argument, the constants are combined with the bitwise-OR operator ( **`|`** ). For a discussion of binary and text modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). -The *`pmode`* argument is required only when **`_O_CREAT`** is specified. If the file already exists, *`pmode`* is ignored. Otherwise, *`pmode`* specifies the file permission settings, which are set when the new file is closed the first time. **`_open`** applies the current file-permission mask to *`pmode`* before the permissions are set. (For more information, see [`_umask`](umask.md).) *`pmode`* is an integer expression that contains one or both of the following manifest constants, which are defined in ``. +The *`pmode`* argument is required only when `_O_CREAT` is specified. If the file already exists, *`pmode`* is ignored. Otherwise, *`pmode`* specifies the file permission settings, which are set when the new file is closed the first time. **`_open`** applies the current file-permission mask to *`pmode`* before the permissions are set. (For more information, see [`_umask`](umask.md).) *`pmode`* is an integer expression that contains one or both of the following manifest constants, which are defined in ``. -|*`pmode`*|Meaning| -|-|-| -| **`_S_IREAD`** | Only reading permitted. | -| **`_S_IWRITE`** | Writing permitted. (In effect, permits reading and writing.) | -| **`_S_IREAD`** | **`_S_IWRITE`** | Reading and writing permitted. | +| *`pmode`* | Meaning | +|--|--| +| `_S_IREAD` | Only reading permitted. | +| `_S_IWRITE` | Writing permitted. (In effect, permits reading and writing.) | +| **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they are joined with the bitwise-OR operator ( **|** ). In Windows, all files are readable; write-only permission is not available. Therefore, the modes **`_S_IWRITE`** and **`_S_IREAD`** | **`_S_IWRITE`** are equivalent. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). In Windows, all files are readable; write-only permission isn't available. Therefore, the modes `_S_IWRITE` and `_S_IREAD` | `_S_IWRITE` are equivalent. -If a value other than some combination of **`_S_IREAD`** and **`_S_IWRITE`** is specified for *`pmode`*—even if it would specify a valid *`pmode`* in another operating system—or if any value other than the allowed *`oflag`* values is specified, the function generates an assertion in Debug mode and invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. +If a value other than some combination of `_S_IREAD` and `_S_IWRITE` is specified for *`pmode`*—even if it would specify a valid *`pmode`* in another operating system—or if any value other than the allowed *`oflag`* values is specified, the function generates an assertion in Debug mode and invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_open`**|``|``, ``, ``| -|**`_wopen`**|`` or ``|``, ``, ``| +| Function | Required header | Optional header | +|--|--|--| +| **`_open`** | `` | ``, ``, `` | +| **`_wopen`** | `` or `` | ``, ``, `` | -**`_open`** and **`_wopen`** are Microsoft extensions. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_open`** and **`_wopen`** are Microsoft extensions. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -150,8 +150,9 @@ int main( void ) _close( fh1 ); } - fh2 = _open( "CRT_OPEN.OUT", _O_WRONLY | _O_CREAT, _S_IREAD | - _S_IWRITE ); // C4996 + fh2 = _open( "CRT_OPEN.OUT", + _O_WRONLY | _O_CREAT, + _S_IREAD | _S_IWRITE ); // C4996 if( fh2 == -1 ) perror( "Open failed on output file" ); else @@ -171,10 +172,10 @@ Open succeeded on output file ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[`_chmod`, `_wchmod`](chmod-wchmod.md)
-[`_close`](close.md)
-[`_creat`, `_wcreat`](creat-wcreat.md)
-[`_dup`, `_dup2`](dup-dup2.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`_sopen`, `_wsopen`](sopen-wsopen.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_dup`, `_dup2`](dup-dup2.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_sopen`, `_wsopen`](sopen-wsopen.md) diff --git a/docs/c-runtime-library/reference/open.md b/docs/c-runtime-library/reference/open.md index d1f53a77b7..26fa2bd93f 100644 --- a/docs/c-runtime-library/reference/open.md +++ b/docs/c-runtime-library/reference/open.md @@ -10,8 +10,8 @@ f1_keywords: ["open"] helpviewer_keywords: ["open function"] ms.assetid: e3139118-4da2-434b-a551-fcf3fccf49b5 --- -# open +# `open` -The Microsoft-implemented POSIX function name `open` is a deprecated alias for the [_open](open-wopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `open` is a deprecated alias for the [`_open`](open-wopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_open](open-wopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_open`](open-wopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/or-eq.md b/docs/c-runtime-library/reference/or-eq.md index fa634f070a..86d34f9fb7 100644 --- a/docs/c-runtime-library/reference/or-eq.md +++ b/docs/c-runtime-library/reference/or-eq.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: or_eq" title: "or_eq" +description: "Learn more about: or_eq" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::or_eq", "or_eq", "std.or_eq"] +f1_keywords: ["std::or_eq", "ISO646/or_eq", "or_eq", "std.or_eq"] helpviewer_keywords: ["or_eq function"] -ms.assetid: 1eb92464-ed58-40d8-a30e-f0a6aa2f4318 --- -# or_eq +# `or_eq` -An alternative to the |= operator. +An alternative to the `|=` operator. ## Syntax ```C - #define or_eq |= ``` ## Remarks -The macro yields the operator |=. +The macro yields the operator `|=`. ## Example diff --git a/docs/c-runtime-library/reference/or.md b/docs/c-runtime-library/reference/or.md index 73ebb76e8e..43c77e35ed 100644 --- a/docs/c-runtime-library/reference/or.md +++ b/docs/c-runtime-library/reference/or.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::or", "std.or", "Or"] +f1_keywords: ["std::or", "std.or", "ISO646/or", "or"] helpviewer_keywords: ["or function"] ms.assetid: 6523b3ac-0a18-44ec-9e9a-b9bab8525ead --- -# or +# `or` -An alternative to the || operator. +An alternative to the **`||`** operator. ## Syntax ```C - #define or || ``` ## Remarks -The macro yields the operator ||. +The macro yields the operator **`||`**. ## Example diff --git a/docs/c-runtime-library/reference/pclose.md b/docs/c-runtime-library/reference/pclose.md index 088c5b80c3..55e048e73b 100644 --- a/docs/c-runtime-library/reference/pclose.md +++ b/docs/c-runtime-library/reference/pclose.md @@ -3,14 +3,14 @@ description: "Learn more about: _pclose" title: "_pclose" ms.date: "4/2/2020" api_name: ["_pclose", "_o__pclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_pclose", "pclose"] helpviewer_keywords: ["_pclose function", "pclose function", "pipes, closing"] ms.assetid: e2e31a9e-ba3a-4124-bcbb-c4040110b3d3 --- -# _pclose +# `_pclose` Waits for a new command processor and closes the stream on the associated pipe. @@ -27,35 +27,35 @@ FILE *stream ### Parameters -*stream*
-Return value from the previous call to **_popen**. +*`stream`*\ +Return value from the previous call to `_popen`. -## Return Value +## Return value -Returns the exit status of the terminating command processor, or -1 if an error occurs. The format of the return value is the same as that for **_cwait**, except the low-order and high-order bytes are swapped. If stream is **NULL**, **_pclose** sets **errno** to **EINVAL** and returns -1. +Returns the exit status of the terminating command processor, or -1 if an error occurs. The format of the return value is the same as for `_cwait`, except the low-order and high-order bytes are swapped. If stream is `NULL`, **`_pclose`** sets `errno` to `EINVAL` and returns -1. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_pclose** function looks up the process ID of the command processor (Cmd.exe) started by the associated **_popen** call, executes a [_cwait](cwait.md) call on the new command processor, and closes the stream on the associated pipe. +The **`_pclose`** function looks up the process ID of the command processor (Cmd.exe) started by the associated `_popen` call, executes a [`_cwait`](cwait.md) call on the new command processor, and closes the stream on the associated pipe. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_pclose**|\| +| Routine | Required header | +|---|---| +| **`_pclose`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_pipe](pipe.md)
-[_popen, _wpopen](popen-wpopen.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_pipe`](pipe.md)\ +[`_popen`, `_wpopen`](popen-wpopen.md) diff --git a/docs/c-runtime-library/reference/perror-wperror.md b/docs/c-runtime-library/reference/perror-wperror.md index d89b6de519..f7e0a8f4d0 100644 --- a/docs/c-runtime-library/reference/perror-wperror.md +++ b/docs/c-runtime-library/reference/perror-wperror.md @@ -3,14 +3,14 @@ description: "Learn more about: perror, _wperror" title: "perror, _wperror" ms.date: "4/2/2020" api_name: ["_wperror", "perror", "_o__wperror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wperror", "_tperror", "perror"] helpviewer_keywords: ["_tperror function", "tperror function", "wperror function", "error messages, printing", "printing error messages", "_wperror function", "perror function"] ms.assetid: 34fce792-16fd-4673-9849-cd88b54b6cd5 --- -# perror, _wperror +# `perror`, `_wperror` Print an error message. @@ -27,41 +27,41 @@ void _wperror( ### Parameters -*message*
+*`message`*\ String message to print. ## Remarks -The **perror** function prints an error message to **stderr**. **_wperror** is a wide-character version of **_perror**; the *message* argument to **_wperror** is a wide-character string. **_wperror** and **_perror** behave identically otherwise. +The **`perror`** function prints an error message to `stderr`. **`_wperror`** is a wide-character version of **`_perror`**; the *`message`* argument to **`_wperror`** is a wide-character string. **`_wperror`** and **`_perror`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tperror**|**perror**|**perror**|**_wperror**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tperror` | **`perror`** | **`perror`** | **`_wperror`** | -*message* is printed first, followed by a colon, then by the system error message for the last library call that produced the error, and finally by a newline character. If *message* is a null pointer or a pointer to a null string, **perror** prints only the system error message. +*`message`* is printed first, followed by a colon, then by the system error message for the last library call that produced the error, and finally by a newline character. If *`message`* is a null pointer or a pointer to a null string, **`perror`** prints only the system error message. -The error number is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) (defined in ERRNO.H). The system error messages are accessed through the variable [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **perror** prints the appropriate error message using the **errno** value as an index to **_sys_errlist**. The value of the variable [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **_sys_errlist** array. +The error number is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md) (defined in ERRNO.H). The system error messages are accessed through the variable [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **`perror`** prints the appropriate error message using the `errno` value as an index to **`_sys_errlist`**. The value of the variable [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **`_sys_errlist`** array. -For accurate results, call **perror** immediately after a library routine returns with an error. Otherwise, subsequent calls can overwrite the **errno** value. +For accurate results, call **`perror`** immediately after a library routine returns an error. Otherwise, subsequent calls can overwrite the `errno` value. -In the Windows operating system, some **errno** values listed in ERRNO.H are unused. These values are reserved for use by the UNIX operating system. See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for a listing of **errno** values used by the Windows operating system. **perror** prints an empty string for any **errno** value not used by these platforms. +In the Windows operating system, some `errno` values listed in ERRNO.H are unused. These values are reserved for use by the UNIX operating system. See [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) for a listing of `errno` values used by the Windows operating system. **`perror`** prints an empty string for any `errno` value not used by these platforms. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**perror**|\ or \| -|**_wperror**|\ or \| +| Routine | Required header | +|---|---| +| **`perror`** | \ or \ | +| **`_wperror`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -113,7 +113,7 @@ _strerror says open failed: No such file or directory ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[clearerr](clearerr.md)
-[ferror](ferror.md)
-[strerror, _strerror, _wcserror, \__wcserror](strerror-strerror-wcserror-wcserror.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](strerror-strerror-wcserror-wcserror.md) diff --git a/docs/c-runtime-library/reference/pipe.md b/docs/c-runtime-library/reference/pipe.md index 76c9dadd6f..084b7d4666 100644 --- a/docs/c-runtime-library/reference/pipe.md +++ b/docs/c-runtime-library/reference/pipe.md @@ -3,14 +3,13 @@ description: "Learn more about: _pipe" title: "_pipe" ms.date: "4/2/2020" api_name: ["_pipe", "_o__pipe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["pipe", "_pipe"] helpviewer_keywords: ["pipes, creating", "_pipe function", "pipes", "pipe function"] -ms.assetid: 8d3e9800-4041-44b5-9e93-2df0b0354a75 --- -# _pipe +# `_pipe` Creates a pipe for reading and writing. @@ -29,62 +28,62 @@ int _pipe( ### Parameters -*pfds*
+*`pfds`*\ Pointer to an array of two **`int`** to hold read and write file descriptors. -*psize*
+*`psize`*\ Amount of memory to reserve. -*textmode*
+*`textmode`*\ File mode. -## Return Value +## Return value -Returns 0 if successful. Returns -1 to indicate an error. On error, **errno** is set to one of these values: +Returns 0 if successful. Returns -1 to indicate an error. On error, `errno` is set to one of these values: -- **EMFILE**, which indicates that no more file descriptors are available. +- `EMFILE`, which indicates that no more file descriptors are available. -- **ENFILE**, which indicates a system-file-table overflow. +- `ENFILE`, which indicates a system-file-table overflow. -- **EINVAL**, which indicates that either the array *pfds* is a null pointer or that an invalid value for *textmode* was passed in. +- `EINVAL`, which indicates that either the array *`pfds`* is a null pointer or that an invalid value for *`textmode`* was passed in. -For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_pipe** function creates a *pipe*, which is an artificial I/O channel that a program uses to pass information to other programs. A pipe resembles a file because it has a file pointer, a file descriptor, or both, and it can be read from or written to by using the Standard Library input and output functions. However, a pipe does not represent a specific file or device. Instead, it represents temporary storage in memory that is independent of the program's own memory and is controlled entirely by the operating system. +The **`_pipe`** function creates a *pipe*, which is an artificial I/O channel that a program uses to pass information to other programs. A pipe resembles a file, because it has a file pointer, a file descriptor, or both. And, it can be read from or written to by using the Standard Library input and output functions. However, a pipe doesn't represent a specific file or device. Instead, it represents temporary storage in memory that is independent of the program's own memory and is controlled entirely by the operating system. -**_pipe** resembles **_open** but opens the pipe for reading and writing and returns two file descriptors instead of one. The program can use both sides of the pipe or close the one that it doesn't need. For example, the command processor in Windows creates a pipe when it executes a command such as **PROGRAM1** | **PROGRAM2**. +**`_pipe`** resembles **`_open`** but opens the pipe for reading and writing and returns two file descriptors instead of one. The program can use both sides of the pipe or close the one that it doesn't need. For example, the command processor in Windows creates a pipe when it executes a command such as **`PROGRAM1 | PROGRAM2`**. -The standard output descriptor of **PROGRAM1** is attached to the pipe's write descriptor. The standard input descriptor of **PROGRAM2** is attached to the pipe's read descriptor. This eliminates the need to create temporary files to pass information to other programs. +The standard output descriptor of `PROGRAM1` is attached to the pipe's write descriptor. The standard input descriptor of `PROGRAM2` is attached to the pipe's read descriptor. This attachment eliminates the need to create temporary files to pass information to other programs. -The **_pipe** function returns two file descriptors to the pipe in the *pfds* argument. The element *pfds*[0] contains the read descriptor, and the element *pfds*[1] contains the write descriptor. Pipe file descriptors are used in the same way as other file descriptors. (The low-level input and output functions **_read** and **_write** can read from and write to a pipe.) To detect the end-of-pipe condition, check for a **_read** request that returns 0 as the number of bytes read. +The **`_pipe`** function returns two file descriptors to the pipe in the *`pfds`* argument. The element *`pfds`*[0] contains the read descriptor, and the element *`pfds`*[1] contains the write descriptor. Pipe file descriptors are used in the same way as other file descriptors. (The low-level input and output functions **`_read`** and **`_write`** can read from and write to a pipe.) To detect the end-of-pipe condition, check for a **`_read`** request that returns 0 as the number of bytes read. -The *psize* argument specifies the amount of memory, in bytes, to reserve for the pipe. The *textmode* argument specifies the translation mode for the pipe. The manifest constant **_O_TEXT** specifies a text translation, and the constant **_O_BINARY** specifies binary translation. (See [fopen, _wfopen](fopen-wfopen.md) for a description of text and binary modes.) If the *textmode* argument is 0, **_pipe** uses the default translation mode that's specified by the default-mode variable [_fmode](../../c-runtime-library/fmode.md). +The *`psize`* argument specifies the amount of memory, in bytes, to reserve for the pipe. The *`textmode`* argument specifies the translation mode for the pipe. The manifest constant `_O_TEXT` specifies an ANSI text translation, and the constant `_O_BINARY` specifies binary translation. (See [`fopen`, `_wfopen`](fopen-wfopen.md) for a description of text and binary modes.) If the *`textmode`* argument is 0, **`_pipe`** uses the default translation mode that's specified by the default-mode variable [`_fmode`](../fmode.md). -In multithreaded programs, no locking is performed. The file descriptors that are returned are newly opened and should not be referenced by any thread until after the **_pipe** call is complete. +In multithreaded programs, no locking is performed. The file descriptors that are returned are newly opened and shouldn't be referenced by any thread until after the **`_pipe`** call is complete. -To use the **_pipe** function to communicate between a parent process and a child process, each process must have only one descriptor open on the pipe. The descriptors must be opposites: if the parent has a read descriptor open, then the child must have a write descriptor open. The easiest way to do this is to bitwise or (**|**) the **_O_NOINHERIT** flag with *textmode*. Then, use **_dup** or **_dup2** to create an inheritable copy of the pipe descriptor that you want to pass to the child. Close the original descriptor, and then spawn the child process. On returning from the spawn call, close the duplicate descriptor in the parent process. For more information, see example 2 later in this article. +To use the **`_pipe`** function to communicate between a parent process and a child process, each process must have only one descriptor open on the pipe. The descriptors must be opposites: if the parent has a read descriptor open, then the child must have a write descriptor open. It's easiest to use a bitwise "or" (**`|`**) on the `_O_NOINHERIT` flag with *`textmode`*. Then, use **`_dup`** or **`_dup2`** to create an inheritable copy of the pipe descriptor that you want to pass to the child. Close the original descriptor, and then spawn the child process. On returning from the spawn call, close the duplicate descriptor in the parent process. For more information, see example 2 later in this article. -In the Windows operating system, a pipe is destroyed when all of its descriptors have been closed. (If all read descriptors on the pipe have been closed, then writing to the pipe causes an error.) All read and write operations on the pipe wait until there is enough data or enough buffer space to complete the I/O request. +In the Windows operating system, a pipe is destroyed when all of its descriptors have been closed. (If all read descriptors on the pipe have been closed, then writing to the pipe causes an error.) All read and write operations on the pipe wait until there's enough data or enough buffer space to complete the I/O request. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_pipe**|\|\,1 \2| +| Routine | Required header | Optional header | +|---|---|---| +| **`_pipe`** | `` | ``,1 ``2 | -1 For **_O_BINARY** and **_O_TEXT** definitions. +1 For `_O_BINARY` and `_O_TEXT` definitions. -2 **errno** definitions. +2 `errno` definitions. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example 1 @@ -106,7 +105,6 @@ enum PIPES { READ, WRITE }; /* Constants 0 and 1 for READ and WRITE */ int main( int argc, char *argv[] ) { - int fdpipe[2]; char hstr[20]; int pid, problem, c; @@ -193,7 +191,7 @@ Dad, the square root of 8000 is 89.44. ## Example 2 -This is a basic filter application. It spawns the application crt_pipe_beeper after it creates a pipe that directs the spawned application's stdout to the filter. The filter removes ASCII 7 (beep) characters. +The sample code is a basic filter application. It spawns the application `crt_pipe_beeper` after it creates a pipe that directs the spawned application's `stdout` to the filter. The filter removes ASCII 7 (beep) characters. ```C // crt_pipe_beeper.c @@ -322,5 +320,5 @@ This is speaker beep number 10... ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_open, _wopen](open-wopen.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/popen-wpopen.md b/docs/c-runtime-library/reference/popen-wpopen.md index f3ae62644d..251723ea13 100644 --- a/docs/c-runtime-library/reference/popen-wpopen.md +++ b/docs/c-runtime-library/reference/popen-wpopen.md @@ -1,14 +1,13 @@ --- title: "_popen, _wpopen" description: "A reference for the Microsoft C runtime (CRT) library functions _popen and _wpopen." -ms.date: "4/2/2020" +ms.date: "1/25/2023" api_name: ["_popen", "_wpopen", "_o__popen", "_o__wpopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["tpopen", "popen", "wpopen", "_popen", "_wpopen", "_tpopen"] helpviewer_keywords: ["tpopen function", "pipes, creating", "_popen function", "_tpopen function", "popen function", "wpopen function", "_wpopen function"] -ms.assetid: eb718ff2-c87d-4bd4-bd2e-ba317c3d6973 no-loc: [_popen, _wpopen, _tpopen, _doserrno, errno, _sys_errlist, _sys_nerr, EINVAL] --- # `_popen`, `_wpopen` @@ -41,51 +40,51 @@ Mode of the returned stream. ## Return value -Returns a stream associated with one end of the created pipe. The other end of the pipe is associated with the spawned command's standard input or standard output. The functions return **`NULL`** on an error. If the error is caused by an invalid parameter, **`errno`** is set to **`EINVAL`**. See the Remarks section for valid modes. +Returns a stream associated with one end of the created pipe. The other end of the pipe is associated with the spawned command's standard input or standard output. The functions return `NULL` on an error. If the error is caused by an invalid parameter, `errno` is set to `EINVAL`. See the Remarks section for valid modes. -For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_popen`** function creates a pipe. It then asynchronously executes a spawned copy of the command processor, and uses *`command`* as the command line. The character string *`mode`* specifies the type of access requested, as follows. -|Access mode|Description| -|-|-| -|**"r"**|The calling process can read the spawned command's standard output using the returned stream.| -|**"w"**|The calling process can write to the spawned command's standard input using the returned stream.| -|**"b"**|Open in binary mode.| -|**"t"**|Open in text mode.| +| Access mode | Description | +|---|---| +| **"`r`"** | The calling process can read the spawned command's standard output using the returned stream. | +| **"`w`"** | The calling process can write to the spawned command's standard input using the returned stream. | +| **"`b`"** | Open in binary mode. | +| **"`t`"** | Open in text mode. | > [!NOTE] -> If used in a Windows program, the **`_popen`** function returns an invalid file pointer that causes the program to stop responding indefinitely. **`_popen`** works properly in a console application. To create a Windows application that redirects input and output, see [Creating a Child Process with Redirected Input and Output](/windows/win32/ProcThread/creating-a-child-process-with-redirected-input-and-output) in the Windows SDK. +> If used in a Windows program, the **`_popen`** function returns an invalid file pointer that causes the program to stop responding indefinitely. **`_popen`** works properly in a console application. To create a Windows application that redirects input and output, see [Creating a child process with redirected input and output](/windows/win32/ProcThread/creating-a-child-process-with-redirected-input-and-output) in the Windows SDK. -**`_wpopen`** is a wide-character version of **`_popen`**; the *path* argument to **`_wpopen`** is a wide-character string. **`_wpopen`** and **`_popen`** behave identically otherwise. +**`_wpopen`** is a wide-character version of **`_popen`**; the *`path`* argument to **`_wpopen`** is a wide-character string. **`_wpopen`** and **`_popen`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tpopen`**|**`_popen`**|**`_popen`**|**`_wpopen`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tpopen` | **`_popen`** | **`_popen`** | **`_wpopen`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_popen`**|``| -|**`_wpopen`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_popen`** | `` | +| **`_wpopen`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example ```C -// crt_popen.c +// popen.c /* This program uses _popen and _pclose to receive a * stream of text from a system process. */ @@ -93,36 +92,39 @@ All versions of the [C run-time libraries](../../c-runtime-library/crt-library-f #include #include -int main( void ) +int main(void) { - - char psBuffer[128]; - FILE *pPipe; - - /* Run DIR so that it writes its output to a pipe. Open this - * pipe with read text attribute so that we can read it - * like a text file. - */ - - if( (pPipe = _popen( "dir *.c /on /p", "rt" )) == NULL ) - exit( 1 ); - - /* Read pipe until end of file, or an error occurs. */ - - while(fgets(psBuffer, 128, pPipe)) - { - puts(psBuffer); - } - - /* Close pipe and print return value of pPipe. */ - if (feof( pPipe)) - { - printf( "\nProcess returned %d\n", _pclose( pPipe ) ); - } - else - { - printf( "Error: Failed to read the pipe to the end.\n"); - } + char psBuffer[128]; + FILE* pPipe; + + /* Run DIR so that it writes its output to a pipe. Open this + * pipe with read text attribute so that we can read it + * like a text file. + */ + + if ((pPipe = _popen("dir *.c /on /p", "rt")) == NULL) + { + exit(1); + } + + /* Read pipe until end of file, or an error occurs. */ + + while (fgets(psBuffer, 128, pPipe)) + { + puts(psBuffer); + } + + int endOfFileVal = feof(pPipe); + int closeReturnVal = _pclose(pPipe); + + if (endOfFileVal) + { + printf("\nProcess returned %d\n", closeReturnVal); + } + else + { + printf("Error: Failed to read the pipe to the end.\n"); + } } ``` @@ -143,6 +145,6 @@ Process returned 0 ## See also -[Process and environment control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`_pclose`](pclose.md)\ [`_pipe`](pipe.md) diff --git a/docs/c-runtime-library/reference/posix-chsize.md b/docs/c-runtime-library/reference/posix-chsize.md index b71b2b63e9..e956ed5935 100644 --- a/docs/c-runtime-library/reference/posix-chsize.md +++ b/docs/c-runtime-library/reference/posix-chsize.md @@ -10,8 +10,8 @@ f1_keywords: ["chsize"] helpviewer_keywords: ["chsize function"] ms.assetid: f94d62f6-b539-4cbf-bf99-b81d081b4216 --- -# chsize +# `chsize` -The Microsoft-specific function name `chsize` is a deprecated alias for the [_chsize](chsize.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `chsize` is a deprecated alias for the [`_chsize`](chsize.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_chsize](chsize.md) or the security-enhanced [_chsize_s](chsize-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_chsize`](chsize.md) or the security-enhanced [`_chsize_s`](chsize-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-close.md b/docs/c-runtime-library/reference/posix-close.md index 4ae588f0d4..6252af1673 100644 --- a/docs/c-runtime-library/reference/posix-close.md +++ b/docs/c-runtime-library/reference/posix-close.md @@ -10,8 +10,8 @@ f1_keywords: ["close"] helpviewer_keywords: ["close function"] ms.assetid: c79689f4-9c86-4a4a-a256-d22e3498f55d --- -# close +# `close` -The Microsoft-implemented POSIX function name `close` is a deprecated alias for the [_close](close.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `close` is a deprecated alias for the [`_close`](close.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_close](close.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_close`](close.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-cwait.md b/docs/c-runtime-library/reference/posix-cwait.md index a075885647..2fc975f4e7 100644 --- a/docs/c-runtime-library/reference/posix-cwait.md +++ b/docs/c-runtime-library/reference/posix-cwait.md @@ -10,11 +10,11 @@ f1_keywords: ["cwait"] helpviewer_keywords: ["cwait function"] ms.assetid: 1ad1ab19-02e5-4155-94ca-f02c2d5a90a6 --- -# cwait +# `cwait` -The Microsoft-specific function name `cwait` is a deprecated alias for the [_cwait](cwait.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cwait` is a deprecated alias for the [`_cwait`](cwait.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_cwait](cwait.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_cwait`](cwait.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-dup-dup2.md b/docs/c-runtime-library/reference/posix-dup-dup2.md index 8493deb995..8ca5d6a2d9 100644 --- a/docs/c-runtime-library/reference/posix-dup-dup2.md +++ b/docs/c-runtime-library/reference/posix-dup-dup2.md @@ -10,8 +10,8 @@ f1_keywords: ["dup", "dup2"] helpviewer_keywords: ["dup function", "dup2 function"] ms.assetid: c7572170-47ff-4e0d-b9c3-10f0ab0ba40a --- -# dup, dup2 +# `dup`, `dup2` -The Microsoft-implemented POSIX function names `dup` and `dup2` are deprecated aliases for the [_dup](dup-dup2.md) and [_dup2](dup-dup2.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `dup` and `dup2` are deprecated aliases for the [`_dup`](dup-dup2.md) and [`_dup2`](dup-dup2.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_dup](dup-dup2.md) and [_dup2](dup-dup2.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_dup`](dup-dup2.md) and [`_dup2`](dup-dup2.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-ecvt.md b/docs/c-runtime-library/reference/posix-ecvt.md index 9c02ed49d4..3c059f61b0 100644 --- a/docs/c-runtime-library/reference/posix-ecvt.md +++ b/docs/c-runtime-library/reference/posix-ecvt.md @@ -10,8 +10,8 @@ f1_keywords: ["ecvt"] helpviewer_keywords: ["ecvt function"] ms.assetid: a24fccea-033a-4cc7-b120-4fd0f525a7e3 --- -# ecvt +# `ecvt` -The Microsoft-specific function name `ecvt` is a deprecated alias for the [_ecvt](ecvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `ecvt` is a deprecated alias for the [`_ecvt`](ecvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_ecvt](ecvt.md) or the security-enhanced [_ecvt_s](ecvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_ecvt`](ecvt.md) or the security-enhanced [`_ecvt_s`](ecvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-eof.md b/docs/c-runtime-library/reference/posix-eof.md index e0ff5e79aa..4a08973881 100644 --- a/docs/c-runtime-library/reference/posix-eof.md +++ b/docs/c-runtime-library/reference/posix-eof.md @@ -10,8 +10,8 @@ f1_keywords: ["eof"] helpviewer_keywords: ["eof function"] ms.assetid: 2e8fb55b-b736-46a6-be5e-15f8876a714f --- -# eof +# `eof` -The Microsoft-specific function name `eof` is a deprecated alias for the [_eof](eof.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `eof` is a deprecated alias for the [`_eof`](eof.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_eof](eof.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_eof`](eof.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-fcvt.md b/docs/c-runtime-library/reference/posix-fcvt.md index ecab0f6c04..232bf20f64 100644 --- a/docs/c-runtime-library/reference/posix-fcvt.md +++ b/docs/c-runtime-library/reference/posix-fcvt.md @@ -10,8 +10,8 @@ f1_keywords: ["fcvt"] helpviewer_keywords: ["fcvt function"] ms.assetid: 1f748ad0-e186-400e-af8e-80d4431523d7 --- -# fcvt +# `fcvt` -The Microsoft-specific function name `fcvt` is a deprecated alias for the [_fcvt](fcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fcvt` is a deprecated alias for the [`_fcvt`](fcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fcvt](fcvt.md) or the security-enhanced [_fcvt_s](fcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fcvt`](fcvt.md) or the security-enhanced [`_fcvt_s`](fcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-fileno.md b/docs/c-runtime-library/reference/posix-fileno.md index 9331d44a2b..68fcf83d80 100644 --- a/docs/c-runtime-library/reference/posix-fileno.md +++ b/docs/c-runtime-library/reference/posix-fileno.md @@ -10,8 +10,8 @@ f1_keywords: ["fileno"] helpviewer_keywords: ["fileno function"] ms.assetid: 8f33e1e0-0dc8-4311-b690-ec6e577a64b5 --- -# fileno +# `fileno` -The Microsoft-implemented POSIX function name `fileno` is a deprecated alias for the [_fileno](fileno.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `fileno` is a deprecated alias for the [`_fileno`](fileno.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fileno](fileno.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fileno`](fileno.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-flushall.md b/docs/c-runtime-library/reference/posix-flushall.md index b2e53a526b..c6695ac843 100644 --- a/docs/c-runtime-library/reference/posix-flushall.md +++ b/docs/c-runtime-library/reference/posix-flushall.md @@ -10,8 +10,8 @@ f1_keywords: ["flushall"] helpviewer_keywords: ["flushall function"] ms.assetid: 481429ae-3980-4233-9495-a3ee56e7c838 --- -# flushall +# `flushall` -The Microsoft-specific function name `flushall` is a deprecated alias for the [_flushall](flushall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `flushall` is a deprecated alias for the [`_flushall`](flushall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_flushall](flushall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_flushall`](flushall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-gcvt.md b/docs/c-runtime-library/reference/posix-gcvt.md index f954e02fa6..c73d36d26f 100644 --- a/docs/c-runtime-library/reference/posix-gcvt.md +++ b/docs/c-runtime-library/reference/posix-gcvt.md @@ -10,8 +10,8 @@ f1_keywords: ["gcvt"] helpviewer_keywords: ["gcvt function"] ms.assetid: 913478fd-ef22-4dee-b558-ff2bd6d72f3d --- -# gcvt +# `gcvt` -The Microsoft-specific function name `gcvt` is a deprecated alias for the [_gcvt](gcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `gcvt` is a deprecated alias for the [`_gcvt`](gcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_gcvt](gcvt.md) or the security-enhanced [_gcvt_s](gcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_gcvt`](gcvt.md) or the security-enhanced [`_gcvt_s`](gcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-getpid.md b/docs/c-runtime-library/reference/posix-getpid.md index f7685f8610..1875662a34 100644 --- a/docs/c-runtime-library/reference/posix-getpid.md +++ b/docs/c-runtime-library/reference/posix-getpid.md @@ -8,13 +8,12 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["getpid"] helpviewer_keywords: ["getpid function"] -ms.assetid: 4eaabab4-362b-429f-854e-ae4941919824 --- -# getpid +# `getpid` -The Microsoft-implemented POSIX function name `getpid` is a deprecated alias for the [_getpid](getpid.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `getpid` is a deprecated alias for the [`_getpid`](getpid.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getpid](getpid.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getpid`](getpid.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-getw.md b/docs/c-runtime-library/reference/posix-getw.md index 1c26fcd4b6..e233127536 100644 --- a/docs/c-runtime-library/reference/posix-getw.md +++ b/docs/c-runtime-library/reference/posix-getw.md @@ -10,8 +10,8 @@ f1_keywords: ["getw"] helpviewer_keywords: ["getw function"] ms.assetid: d3c347a4-3ff1-403b-8d02-2dd3b429bb5f --- -# getw +# `getw` -The Microsoft-specific function name `getw` is a deprecated alias for the [_getw](getw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `getw` is a deprecated alias for the [`_getw`](getw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getw](getw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getw`](getw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-isatty.md b/docs/c-runtime-library/reference/posix-isatty.md index 73151ae8e7..4e1f70a71f 100644 --- a/docs/c-runtime-library/reference/posix-isatty.md +++ b/docs/c-runtime-library/reference/posix-isatty.md @@ -10,8 +10,8 @@ f1_keywords: ["isatty"] helpviewer_keywords: ["isatty function"] ms.assetid: 610d0b09-a1db-41ef-9f45-a2c6076b4683 --- -# isatty +# `isatty` -The Microsoft-implemented POSIX function name `isatty` is a deprecated alias for the [_isatty](isatty.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `isatty` is a deprecated alias for the [`_isatty`](isatty.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_isatty](isatty.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_isatty`](isatty.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-kbhit.md b/docs/c-runtime-library/reference/posix-kbhit.md index 315579e00f..c502ee6542 100644 --- a/docs/c-runtime-library/reference/posix-kbhit.md +++ b/docs/c-runtime-library/reference/posix-kbhit.md @@ -10,11 +10,11 @@ f1_keywords: ["kbhit"] helpviewer_keywords: ["kbhit function"] ms.assetid: 73f1eed7-b3ef-4887-8ec6-755367de1d7d --- -# kbhit +# `kbhit` -The Microsoft-specific function name `kbhit` is a deprecated alias for the [_kbhit](kbhit.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `kbhit` is a deprecated alias for the [`_kbhit`](kbhit.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_kbhit](kbhit.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_kbhit`](kbhit.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-lfind.md b/docs/c-runtime-library/reference/posix-lfind.md index 52dafe6523..8972ef7872 100644 --- a/docs/c-runtime-library/reference/posix-lfind.md +++ b/docs/c-runtime-library/reference/posix-lfind.md @@ -10,8 +10,8 @@ f1_keywords: ["lfind"] helpviewer_keywords: ["lfind function"] ms.assetid: 2528e787-94b6-4740-8a8d-6efc276d1f42 --- -# lfind +# `lfind` -The Microsoft-implemented POSIX function name `lfind` is a deprecated alias for the [_lfind](lfind.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `lfind` is a deprecated alias for the [`_lfind`](lfind.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_lfind](lfind.md) or security-enhanced [_lfind_s](lfind-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_lfind`](lfind.md) or security-enhanced [`_lfind_s`](lfind-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-locking.md b/docs/c-runtime-library/reference/posix-locking.md index 3252601bae..aabcf9346a 100644 --- a/docs/c-runtime-library/reference/posix-locking.md +++ b/docs/c-runtime-library/reference/posix-locking.md @@ -10,8 +10,8 @@ f1_keywords: ["locking"] helpviewer_keywords: ["locking function"] ms.assetid: 1db15308-543e-44cf-a26f-5539f8e4fb2f --- -# locking +# `locking` -The Microsoft-specific function name `locking` is a deprecated alias for the [_locking](locking.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `locking` is a deprecated alias for the [`_locking`](locking.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_locking](locking.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_locking`](locking.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-lsearch.md b/docs/c-runtime-library/reference/posix-lsearch.md index 3a98aad87f..ddd2f426a5 100644 --- a/docs/c-runtime-library/reference/posix-lsearch.md +++ b/docs/c-runtime-library/reference/posix-lsearch.md @@ -10,8 +10,8 @@ f1_keywords: ["lsearch"] helpviewer_keywords: ["lsearch function"] ms.assetid: 130da3fc-904a-4375-b0ab-79bfea8a455f --- -# lsearch +# `lsearch` -The Microsoft-implemented POSIX function name `lsearch` is a deprecated alias for the [_lsearch](lsearch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `lsearch` is a deprecated alias for the [`_lsearch`](lsearch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_lsearch](lsearch.md) or security-enhanced [_lsearch_s](lsearch-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_lsearch`](lsearch.md) or security-enhanced [`_lsearch_s`](lsearch-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-memccpy.md b/docs/c-runtime-library/reference/posix-memccpy.md index a94f6bade8..f72ef7307b 100644 --- a/docs/c-runtime-library/reference/posix-memccpy.md +++ b/docs/c-runtime-library/reference/posix-memccpy.md @@ -10,8 +10,8 @@ f1_keywords: ["memccpy"] helpviewer_keywords: ["memccpy function"] ms.assetid: e9951812-2b69-43e9-bbee-a0001bce4d80 --- -# memccpy +# `memccpy` -The Microsoft-implemented POSIX function name `memccpy` is a deprecated alias for the [_memccpy](memccpy.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `memccpy` is a deprecated alias for the [`_memccpy`](memccpy.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_memccpy](memccpy.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_memccpy`](memccpy.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-putw.md b/docs/c-runtime-library/reference/posix-putw.md index 8182a13dca..a270ffda48 100644 --- a/docs/c-runtime-library/reference/posix-putw.md +++ b/docs/c-runtime-library/reference/posix-putw.md @@ -10,8 +10,8 @@ f1_keywords: ["putw"] helpviewer_keywords: ["putw function"] ms.assetid: a004fbb6-7643-4f3f-9ee1-87a23154d49a --- -# putw +# `putw` -The Microsoft-specific function name `putw` is a deprecated alias for the [_putw](putw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `putw` is a deprecated alias for the [`_putw`](putw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putw](putw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putw`](putw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-read.md b/docs/c-runtime-library/reference/posix-read.md index 46b774c8ae..d3487d5b9d 100644 --- a/docs/c-runtime-library/reference/posix-read.md +++ b/docs/c-runtime-library/reference/posix-read.md @@ -10,8 +10,8 @@ f1_keywords: ["read"] helpviewer_keywords: ["read function"] ms.assetid: 9e0eead4-d38c-4f65-87f5-f6c12da40ead --- -# read +# `read` -The Microsoft-implemented POSIX function name `read` is a deprecated alias for the [_read](read.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `read` is a deprecated alias for the [`_read`](read.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_read](read.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_read`](read.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-rmtmp.md b/docs/c-runtime-library/reference/posix-rmtmp.md index 801434b958..845eacdd75 100644 --- a/docs/c-runtime-library/reference/posix-rmtmp.md +++ b/docs/c-runtime-library/reference/posix-rmtmp.md @@ -10,8 +10,8 @@ f1_keywords: ["rmtmp"] helpviewer_keywords: ["rmtmp function"] ms.assetid: d79f0364-39e8-42fb-a73a-63c22a646cd8 --- -# rmtmp +# `rmtmp` -The Microsoft-specific function name `rmtmp` is a deprecated alias for the [_rmtmp](rmtmp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `rmtmp` is a deprecated alias for the [`_rmtmp`](rmtmp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_rmtmp](rmtmp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_rmtmp`](rmtmp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-setmode.md b/docs/c-runtime-library/reference/posix-setmode.md index 6b4d755748..064dc32a70 100644 --- a/docs/c-runtime-library/reference/posix-setmode.md +++ b/docs/c-runtime-library/reference/posix-setmode.md @@ -10,8 +10,8 @@ f1_keywords: ["setmode"] helpviewer_keywords: ["setmode function"] ms.assetid: cb959d9e-09f3-45af-8943-85f4ca0d3f5a --- -# setmode +# `setmode` -The Microsoft-specific function name `setmode` is a deprecated alias for the [_setmode](setmode.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `setmode` is a deprecated alias for the [`_setmode`](setmode.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_setmode](setmode.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_setmode`](setmode.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-swab.md b/docs/c-runtime-library/reference/posix-swab.md index fd9e0270e9..26edc6cd63 100644 --- a/docs/c-runtime-library/reference/posix-swab.md +++ b/docs/c-runtime-library/reference/posix-swab.md @@ -10,8 +10,8 @@ f1_keywords: ["swab"] helpviewer_keywords: ["swab function"] ms.assetid: fb8b7137-420d-4485-bb65-e1ec68602905 --- -# swab +# `swab` -The Microsoft-implemented POSIX function name `swab` is a deprecated alias for the [_swab](swab.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `swab` is a deprecated alias for the [`_swab`](swab.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_swab](swab.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_swab`](swab.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-tzset.md b/docs/c-runtime-library/reference/posix-tzset.md index 2508c322e6..8e65277eca 100644 --- a/docs/c-runtime-library/reference/posix-tzset.md +++ b/docs/c-runtime-library/reference/posix-tzset.md @@ -10,11 +10,11 @@ f1_keywords: ["tzset"] helpviewer_keywords: ["tzset function"] ms.assetid: c3afa5d0-cb15-4163-9181-fafb962c95aa --- -# tzset +# `tzset` -The Microsoft-implemented POSIX function name `tzset` is a deprecated alias for the [_tzset](tzset.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `tzset` is a deprecated alias for the [`_tzset`](tzset.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tzset](tzset.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tzset`](tzset.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-umask.md b/docs/c-runtime-library/reference/posix-umask.md index ea9f5322f2..91fa5134cf 100644 --- a/docs/c-runtime-library/reference/posix-umask.md +++ b/docs/c-runtime-library/reference/posix-umask.md @@ -10,8 +10,8 @@ f1_keywords: ["umask"] helpviewer_keywords: ["umask function"] ms.assetid: d2f697fc-08d5-4b70-9dd5-df3f5bb8b754 --- -# umask +# `umask` -The Microsoft-implemented POSIX function name `umask` is a deprecated alias for the [_umask](umask.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `umask` is a deprecated alias for the [`_umask`](umask.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_umask](umask.md) or security-enhanced [_umask_s](umask-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_umask`](umask.md) or security-enhanced [`_umask_s`](umask-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-write.md b/docs/c-runtime-library/reference/posix-write.md index c6fba512ec..7c80fce32a 100644 --- a/docs/c-runtime-library/reference/posix-write.md +++ b/docs/c-runtime-library/reference/posix-write.md @@ -6,12 +6,12 @@ api_name: ["write"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["write"] +f1_keywords: ["CORECRT_IO/write", "write"] helpviewer_keywords: ["write function"] ms.assetid: 1cbf112e-b9ef-4df6-993a-83abd4213acd --- -# write +# `write` -The Microsoft-implemented POSIX function name `write` is a deprecated alias for the [_write](write.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `write` is a deprecated alias for the [`_write`](write.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_write](write.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_write`](write.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/pow-powf-powl.md b/docs/c-runtime-library/reference/pow-powf-powl.md index 506a379c7f..bedf5a9dcf 100644 --- a/docs/c-runtime-library/reference/pow-powf-powl.md +++ b/docs/c-runtime-library/reference/pow-powf-powl.md @@ -1,9 +1,9 @@ --- title: "pow, powf, powl" -description: "API reference for pow, powf, and powl; which calculate raising to a power." +description: "API reference for pow, powf, and powl; which calculate exponents." ms.date: "08/31/2020" api_name: ["powl", "pow", "powf", "_o_pow", "_o_powf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["powl", "pow", "_powl", "powf"] @@ -37,40 +37,40 @@ Base. *`y`*\ Exponent. -## Return Value +## Return value Returns the value of *`x`**`y`*. No error message is printed on overflow or underflow. -|Values of x and y|Return value of pow| -|-----------------------|-------------------------| -|*x* != 0.0 and *y* == 0.0|1| -|*x* == 0.0 and *y* == 0.0|1| -|*x* == 0.0 and *y* < 0|INF| +| Values of *`x`* and *`y`* | Return value of **`pow`** | +|---|---| +| *`x`* != 0.0 and *`y`* == 0.0 | 1 | +| *`x`* == 0.0 and *`y`* == 0.0 | 1 | +| *`x`* == 0.0 and *`y`* < 0 | INF | ## Remarks -**`pow`** does not recognize integral floating-point values greater than 264 (for example, 1.0E100). +**`pow`** doesn't recognize integral floating-point values greater than 264 (for example, 1.0E100). **`pow`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). Because C++ allows overloading, you can call any of the various overloads of **`pow`**. In a C program, unless you're using the `` macro to call this function, **`pow`** always takes two **`double`** values and returns a **`double`** value. -If you use the `` `pow()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `pow` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. The `pow(int, int)` overload is no longer available. If you use this overload, the compiler may emit [C2668](../../error-messages/compiler-errors-2/compiler-error-c2668.md). To avoid this problem, cast the first parameter to **`double`**, **`float`**, or **`long double`**. -Originally, the `pow(T, int)` overloads would unroll the `pow` call into a sequence of inline multiplication operations. While this was faster, it was also significantly less accurate and was removed in Visual Studio 2015 Update 1. For more information, see [Conformance Improvements in Visual Studio 2015 Update 1](../../porting/visual-cpp-what-s-new-2003-through-2015.md). +Originally, the `pow(T, int)` overloads unrolled the `pow` call into a sequence of inline multiplication operations. While it was faster, it was also much less accurate. This implementation was removed in Visual Studio 2015 Update 1. For more information, see [Conformance improvements in Visual Studio 2015 Update 1](../../porting/visual-cpp-what-s-new-2003-through-2015.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-|-|-| -|**`pow`**, **`powf`**, **`powl`**|``|`` or ``| -|**`pow`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`pow`**, **`powf`**, **`powl`** | `` | `` or `` | +| **`pow`** macro | `` | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,8 +95,8 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[`exp`, `expf`, `expl`](exp-expf.md)
-[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)
-[`sqrt`, `sqrtf`, `sqrtl`](sqrt-sqrtf-sqrtl.md)
-[`_CIpow`](../../c-runtime-library/cipow.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ +[`sqrt`, `sqrtf`, `sqrtl`](sqrt-sqrtf-sqrtl.md)\ +[`_CIpow`](../cipow.md) diff --git a/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md b/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md index a5838e4630..3d909d9397 100644 --- a/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md +++ b/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["wprintf_p", "_wprintf_p", "printf_p_l", "_printf_p", "printf_p", "_wprintf_p_l", "_printf_p_l", "wprintf_p_l"] helpviewer_keywords: ["printf_p function", "printf_p_l function", "wprintf_p function", "wprintf_p_l function", "_tprintf_p_l function", "_wprintf_p function", "_wprintf_p_l function", "_printf_p function", "tprintf_p_l function", "_printf_p_l function"] --- -# _printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l +# `_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l` Prints formatted output to the standard output stream, and enables specification of the order in which parameters are used in the format string. @@ -38,49 +38,49 @@ int _wprintf_p_l( ### Parameters -*format*
+*`format`*\ Format control. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns the number of characters printed or a negative value if an error occurs. ## Remarks -The **_printf_p** function formats and prints a series of characters and values to the standard output stream, **stdout**. If arguments follow the *format* string, the *format* string must contain specifications that determine the output format for the arguments (see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)). +The **`_printf_p`** function formats and prints a series of characters and values to the standard output stream, `stdout`. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments (see [printf_p Positional Parameters](../printf-p-positional-parameters.md)). -The difference between **_printf_p** and **printf_s** is that **_printf_p** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +The difference between **`_printf_p`** and `printf_s` is that **`_printf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_wprintf_p** is the wide-character version of **_printf_p**; they behave identically if the stream is opened in ANSI mode. **_printf_p** doesn't currently support output into a UNICODE stream. +**`_wprintf_p`** is the wide-character version of **`_printf_p`**; they behave identically if the stream is opened in ANSI mode. **`_printf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. +> Ensure that *`format`* is not a user-defined string. -If *format* or *argument* are **NULL**, or of the format string contains invalid formatting characters, **_printf_p** and **_wprintf_p** functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **errno** to **EINVAL**. +If *`format`* or *`argument`* are `NULL`, or of the format string contains invalid formatting characters, **`_printf_p`** and **`_wprintf_p`** functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tprintf_p**|**_printf_p**|**_printf_p**|**_wprintf_p**| -|**_tprintf_p_l**|**_printf_p_l**|**_printf_p_l**|**_wprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tprintf_p` | **`_printf_p`** | **`_printf_p`** | **`_wprintf_p`** | +| `_tprintf_p_l` | **`_printf_p_l`** | **`_printf_p_l`** | **`_wprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_printf_p**, **_printf_p_l**|\| -|**_wprintf_p**, **_wprintf_p_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_printf_p`**, **`_printf_p_l`** | \ | +| **`_wprintf_p`**, **`_wprintf_p_l`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -117,16 +117,16 @@ Width specifiers: Hello ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md b/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md index 821e36650c..9754b1c51f 100644 --- a/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md +++ b/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md @@ -38,26 +38,26 @@ int _wprintf_l( ### Parameters -*`format`*
+*`format`*\ Format control. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of characters printed, or a negative value if an error occurs. If *`format`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. If **`EOF`** (0xFFFF) is encountered in *`argument`*, the function returns -1. +Returns the number of characters printed, or a negative value if an error occurs. If *`format`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. If `EOF` (0xFFFF) is encountered in *`argument`*, the function returns -1. -For information on **`errno`** and error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on `errno` and error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`printf`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. **`printf`** and [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md) behave identically except that **`printf`** writes output to **`stdout`** rather than to a destination of type **`FILE`**. +The **`printf`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. **`printf`** and [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md) behave identically except that **`printf`** writes output to **`stdout`** rather than to a destination of type `FILE`. -**`wprintf`** is a wide-character version of **`printf`**; *`format`* is a wide-character string. **`wprintf`** and **`printf`** behave identically if the stream is opened in ANSI mode. **`printf`** does not currently support output into a UNICODE stream. +**`wprintf`** is a wide-character version of **`printf`**; *`format`* is a wide-character string. **`wprintf`** and **`printf`** behave identically if the stream is opened in ANSI mode. **`printf`** doesn't currently support output into a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. @@ -74,26 +74,26 @@ Line one Line two ``` -[Format specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**%**) and are read left to right. When **`printf`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications. +[Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**%**) and are read left to right. When **`printf`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there aren't enough arguments for all the format specifications. > [!IMPORTANT] > Ensure that *`format`* is not a user-defined string. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tprintf`**|**`printf`**|**`printf`**|**`wprintf`**| -|**`_tprintf_l`**|**`_printf_l`**|**`_printf_l`**|**`_wprintf_l`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tprintf`** | **`printf`** | **`printf`** | **`wprintf`** | +| **`_tprintf_l`** | **`_printf_l`** | **`_printf_l`** | **`_wprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`printf`**, **`_printf_l`**|``| -|**`wprintf`**, **`_wprintf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`printf`**, **`_printf_l`** | `` | +| **`wprintf`**, **`_wprintf_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -157,7 +157,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Integer formats: @@ -186,13 +186,13 @@ Address as: 0012FF3C ## See also -[Format Specification Syntax: `printf` and `wprintf` Functions](../format-specification-syntax-printf-and-wprintf-functions.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[`_set_output_format`](../../c-runtime-library/set-output-format.md)
+[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_set_output_format`](../set-output-format.md) diff --git a/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md b/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md index 0b7c70f5b5..be7f7d3340 100644 --- a/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md +++ b/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md @@ -11,7 +11,7 @@ helpviewer_keywords: ["wprintf_s function", "tprintf_s function", "_tprintf_s fu --- # `printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l` -Prints formatted output to the standard output stream. These versions of [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Prints formatted output to the standard output stream. These versions of [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -38,16 +38,16 @@ int _wprintf_s_l( ### Parameters -*`format`*
+*`format`*\ Format control. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns the number of characters printed, or a negative value if an error occurs. @@ -55,22 +55,22 @@ Returns the number of characters printed, or a negative value if an error occurs The **`printf_s`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. -The main difference between **`printf_s`** and **`printf`** is that **`printf_s`** checks the format string for valid formatting characters, whereas **`printf`** only checks if the format string is a null pointer. If either check fails, an invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. +The main difference between **`printf_s`** and **`printf`** is that **`printf_s`** checks the format string for valid formatting characters, whereas **`printf`** only checks if the format string is a null pointer. If either check fails, an invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. -For information on **`errno`** and error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on `errno` and error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**`printf_s`** and **`fprintf_s`** behave identically except that **`printf_s`** writes output to **`stdout`** rather than to a destination of type **`FILE`**. For more information, see [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md). +**`printf_s`** and **`fprintf_s`** behave identically except that **`printf_s`** writes output to **`stdout`** rather than to a destination of type `FILE`. For more information, see [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md). **`wprintf_s`** is a wide-character version of **`printf_s`**; *`format`* is a wide-character string. **`wprintf_s`** and **`printf_s`** behave identically if the stream is opened in ANSI mode. **`printf_s`** doesn't currently support output into a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tprintf_s`**|**`printf_s`**|**`printf_s`**|**`wprintf_s`**| -|**`_tprintf_s_l`**|**`_printf_s_l`**|**`_printf_s_l`**|**`_wprintf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tprintf_s` | **`printf_s`** | **`printf_s`** | **`wprintf_s`** | +| `_tprintf_s_l` | **`_printf_s_l`** | **`_printf_s_l`** | **`_wprintf_s_l`** | The *`format`* argument consists of ordinary characters, escape sequences, and (if arguments follow *`format`*) format specifications. The ordinary characters and escape sequences are copied to **`stdout`** in order of their appearance. For example, the line @@ -85,24 +85,23 @@ Line one Line two ``` -[Format specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**`%`**) and are read left to right. When **`printf_s`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications. +[Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**`%`**) and are read left to right. When **`printf_s`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there aren't enough arguments for all the format specifications. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`printf_s`**, **`_printf_s_l`**|``| -|**`wprintf_s`**, **`_wprintf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`printf_s`**, **`_printf_s_l`** | `` | +| **`wprintf_s`**, **`_wprintf_s_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -154,7 +153,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Integer formats: @@ -183,11 +182,11 @@ Address as: 0012FF78 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/purecall.md b/docs/c-runtime-library/reference/purecall.md index 16a8898a92..b673b89065 100644 --- a/docs/c-runtime-library/reference/purecall.md +++ b/docs/c-runtime-library/reference/purecall.md @@ -3,14 +3,14 @@ description: "Learn more about: _purecall" title: "_purecall" ms.date: "4/2/2020" api_name: ["_purecall", "_o__purecall"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["purecall", "_purecall"] helpviewer_keywords: ["_purecall function", "purecall function"] ms.assetid: 56135d9b-3403-4e22-822d-e714523801cc --- -# _purecall +# `_purecall` The default pure virtual function call error handler. The compiler generates code to call this function when a pure virtual member function is called. @@ -22,17 +22,17 @@ extern "C" int __cdecl _purecall(); ## Remarks -The **_purecall** function is a Microsoft-specific implementation detail of the Microsoft C++ compiler. This function is not intended to be called by your code directly, and it has no public header declaration. It is documented here because it is a public export of the C Runtime Library. +The **`_purecall`** function is a Microsoft-specific implementation detail of the Microsoft C++ compiler. This function isn't intended to be called by your code directly, and it has no public header declaration. It's documented here because it's a public export of the C Runtime Library. -A call to a pure virtual function is an error because it has no implementation. The compiler generates code to invoke the **_purecall** error handler function when a pure virtual function is called. By default, **_purecall** terminates the program. Before terminating, the **_purecall** function invokes a **_purecall_handler** function if one has been set for the process. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the **_purecall_handler** signature, then use [_set_purecall_handler](get-purecall-handler-set-purecall-handler.md) to make it the current handler. +A call to a pure virtual function is an error because it has no implementation. The compiler generates code to invoke the **`_purecall`** error handler function when a pure virtual function is called. By default, **`_purecall`** terminates the program. Before the **`_purecall`** function terminates, it invokes a `_purecall_handler` function, if one has been set for the process. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the `_purecall_handler` signature, then use [`_set_purecall_handler`](get-purecall-handler-set-purecall-handler.md) to make it the current handler. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -The **_purecall** function does not have a header declaration. The **_purecall_handler** typedef is defined in \. +The **`_purecall`** function doesn't have a header declaration. The `_purecall_handler` typedef is defined in \. ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_get_purecall_handler, _set_purecall_handler](get-purecall-handler-set-purecall-handler.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_get_purecall_handler`, `_set_purecall_handler`](get-purecall-handler-set-purecall-handler.md) diff --git a/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md b/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md index 1d5d566b01..6c629ae81f 100644 --- a/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md +++ b/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _putc_nolock, _putwc_nolock" title: "_putc_nolock, _putwc_nolock" +description: "Learn more about: _putc_nolock, _putwc_nolock" ms.date: "4/2/2020" api_name: ["_putc_nolock", "_putwc_nolock", "_o__putc_nolock", "_o__putwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_puttc_nolock", "puttc_nolock", "putwc_nolock", "_putwc_nolock", "_putc_nolock", "putc_nolock"] helpviewer_keywords: ["puttc_nolock function", "putc_nolock function", "_putc_nolock function", "streams, writing characters to", "characters, writing", "putwc_nolock function", "_puttc_nolock function", "_putwc_nolock function"] -ms.assetid: 3cfc7f21-c9e8-4b7f-b0fb-af0d4d85e7e1 --- -# _putc_nolock, _putwc_nolock +# `_putc_nolock`, `_putwc_nolock` -Writes a character to a stream without locking the thread. +Writes a character to a stream without locking. ## Syntax @@ -29,42 +28,42 @@ wint_t _putwc_nolock( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value See **putc, putwc**. ## Remarks -**_putc_nolock** and **_putwc_nolock** are identical to the versions without the **_nolock** suffix except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_putc_nolock`** and **`_putwc_nolock`** are identical to the versions without the `_nolock` suffix except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -**_putwc_nolock** is the wide-character version of **_putc_nolock**; the two functions behave identically if the stream is opened in ANSI mode. **_putc_nolock** doesn't currently support output into a UNICODE stream. +**`_putwc_nolock`** is the wide-character version of **`_putc_nolock`**; the two functions behave identically if the stream is opened in ANSI mode. **`_putc_nolock`** doesn't currently support output into a UNICODE stream. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttc_nolock**|**_putc_nolock**|**_putc_nolock**|**_putwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttc_nolock` | **`_putc_nolock`** | **`_putc_nolock`** | **`_putwc_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putc_nolock**|\| -|**_putwc_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_putc_nolock`** | \ | +| **`_putwc_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -99,6 +98,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putc-putwc.md b/docs/c-runtime-library/reference/putc-putwc.md index c9715a2658..9d4bc87c31 100644 --- a/docs/c-runtime-library/reference/putc-putwc.md +++ b/docs/c-runtime-library/reference/putc-putwc.md @@ -3,14 +3,14 @@ description: "Learn more about: putc, putwc" title: "putc, putwc" ms.date: "4/2/2020" api_name: ["putwc", "putc", "_o_putc", "_o_putwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_puttc", "putwc", "putc"] helpviewer_keywords: ["streams, writing characters to", "characters, writing", "putwc function", "putc function", "_puttc function", "puttc function"] ms.assetid: a37b2e82-9d88-4565-8190-ff8d04c0ddb9 --- -# putc, putwc +# `putc`, `putwc` Writes a character to a stream. @@ -29,44 +29,44 @@ wint_t putwc( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -Returns the character written. To indicate an error or end-of-file condition, **putc** and **putchar** return **EOF**; **putwc** and **putwchar** return **WEOF**. For all four routines, use [ferror](ferror.md) or [feof](feof.md) to check for an error or end of file. If passed a null pointer for *stream*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** or **WEOF** and set **errno** to **EINVAL**. +Returns the character written. To indicate an error or end-of-file condition, **`putc`** and `putchar` return `EOF`; **`putwc`** and `putwchar` return `WEOF`. For all four routines, use [`ferror`](ferror.md) or [`feof`](feof.md) to check for an error or end of file. If passed a null pointer for *`stream`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` or `WEOF`, and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **putc** routine writes the single character *c* to the output *stream* at the current position. Any integer can be passed to **putc**, but only the lower 8 bits are written. The **putchar** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **putc** and **putchar** are similar to **fputc** and **_fputchar**, respectively, but are implemented both as functions and as macros (see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md)). **putwc** and **putwchar** are wide-character versions of **putc** and **putchar**, respectively. **putwc** and **putc** behave identically if the stream is opened in ANSI mode. **putc** doesn't currently support output into a UNICODE stream. +The **`putc`** routine writes the single character *`c`* to the output *`stream`* at the current position. Any integer can be passed to **`putc`**, but only the lower 8 bits are written. The `putchar` routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **`putc`** and `putchar` are similar to `fputc` and `_fputchar`, respectively, but are implemented both as functions and as macros (see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md)). **`putwc`** and `putwchar` are wide-character versions of **`putc`** and `putchar`, respectively. **`putwc`** and **`putc`** behave identically if the stream is opened in ANSI mode. **`putc`** doesn't currently support output into a UNICODE stream. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. For more information, see **_putc_nolock, _putwc_nolock**. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. For more information, see **_putc_nolock, _putwc_nolock**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_puttc**|**putc**|**putc**|**putwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttc` | **`putc`** | **`putc`** | **`putwc`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**putc**|\| -|**putwc**|\ or \| +| Routine | Required header | +|---|---| +| **`putc`** | \ | +| **`putwc`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -101,6 +101,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md b/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md index 6eef9c8b1c..d97eb45b18 100644 --- a/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md +++ b/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _putch_nolock, _putwch_nolock" title: "_putch_nolock, _putwch_nolock" +description: "Learn more about: _putch_nolock, _putwch_nolock" ms.date: "4/2/2020" api_name: ["_putwch_nolock", "_putch_nolock", "_o__putch_nolock", "_o__putwch_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putch_nolock", "_puttch_nolock", "putch_nolock", "putwch_nolock", "_putwch_nolock"] helpviewer_keywords: ["putwch_nolock function", "puttch_nolock function", "characters, writing", "putch_nolock function", "_putch_nolock function", "_puttch_nolock function", "console, writing characters to", "_putwch_nolock function"] -ms.assetid: edbc811d-bac6-47fa-a872-fe4f3a1590b0 --- -# _putch_nolock, _putwch_nolock +# `_putch_nolock`, `_putwch_nolock` -Writes a character to the console without locking the thread. +Writes a character to the console without locking. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -30,40 +29,40 @@ wchar_t c ### Parameters -*c*
+*`c`*\ Character to be output. -## Return Value +## Return value -Returns *c* if successful. If **_putch_nolock** fails, it returns **EOF**; if **_putwch_nolock** fails, it returns **WEOF**. +Returns *`c`* if successful. If **`_putch_nolock`** fails, it returns `EOF`; if **`_putwch_nolock`** fails, it returns `WEOF`. ## Remarks -**_putch_nolock** and **_putwch_nolock** are identical to **_putch** and **_putwch**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_putch_nolock`** and **`_putwch_nolock`** are identical to `_putch` and `_putwch`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch_nolock**|**_putch_nolock**|**_putch_nolock**|**_putwch_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttch_nolock` | **`_putch_nolock`** | **`_putch_nolock`** | **`_putwch_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putch_nolock**|\| -|**_putwch_nolock**|\| +| Routine | Required header | +|---|---| +| **`_putch_nolock`** | \ | +| **`_putwch_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/putch-putwch.md b/docs/c-runtime-library/reference/putch-putwch.md index 6e73309cfc..eb94136fbe 100644 --- a/docs/c-runtime-library/reference/putch-putwch.md +++ b/docs/c-runtime-library/reference/putch-putwch.md @@ -3,14 +3,14 @@ description: "Learn more about: _putch, _putwch" title: "_putch, _putwch" ms.date: "4/2/2020" api_name: ["_putwch", "_putch", "_o__putch", "_o__putwch"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putch", "putwch", "_putwch"] helpviewer_keywords: ["_putch function", "characters, writing", "putwch function", "_putwch function", "putch function", "console, writing characters to"] ms.assetid: 3babc7cf-e333-405d-8449-c788d61d51aa --- -# _putch, _putwch +# `_putch`, `_putwch` Writes a character to the console. @@ -31,46 +31,46 @@ wint_t _putwch( ### Parameters -*c*
+*`c`*\ Character to be output. -## Return Value +## Return value -Returns *c* if successful. If **_putch** fails, it returns **EOF**; if **_putwch** fails, it returns **WEOF**. +Returns *`c`* if successful. If **`_putch`** fails, it returns `EOF`; if **`_putwch`** fails, it returns `WEOF`. ## Remarks -These functions write the character *c* directly, without buffering, to the console. In Windows NT, **_putwch** writes Unicode characters using the current console locale setting. +These functions write the character *`c`* directly, without buffering, to the console. In Windows NT, **`_putwch`** writes Unicode characters using the current console locale setting. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. For more information, see **_putch_nolock**, **_putwch_nolock**. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. For more information, see [`_putch_nolock`, `_putwch_nolock`](./putch-nolock-putwch-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch**|**_putch**|**_putch**|**_putwch**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttch` | **`_putch`** | **`_putch`** | **`_putwch`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putch**|\| -|**_putwch**|\| +| Routine | Required header | +|---|---| +| **`_putch`** | \ | +| **`_putwch`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [_getch](getch-getwch.md). +See the example for [`_getch`](getch-getwch.md). ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/putch.md b/docs/c-runtime-library/reference/putch.md index 85549a6af1..2edfdc788b 100644 --- a/docs/c-runtime-library/reference/putch.md +++ b/docs/c-runtime-library/reference/putch.md @@ -10,11 +10,11 @@ f1_keywords: ["putch"] helpviewer_keywords: ["putch function"] ms.assetid: 81e733e5-770e-4c7a-b7e4-8e66da109f92 --- -# putch +# `putch` -The Microsoft-specific function name `putch` is a deprecated alias for the [_putch](putch-putwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `putch` is a deprecated alias for the [`_putch`](putch-putwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putch](putch-putwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putch`](putch-putwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md b/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md index ba566fcb51..6fe752c348 100644 --- a/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md +++ b/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _putchar_nolock, _putwchar_nolock" title: "_putchar_nolock, _putwchar_nolock" +description: "Learn more about: _putchar_nolock, _putwchar_nolock" ms.date: "11/04/2016" api_name: ["_putchar_nolock", "_putwchar_nolock"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["putwchar_nolock", "_puttchar_nolock", "_putchar_nolock", "_putwchar_nolock", "putchar_nolock"] helpviewer_keywords: ["_puttchar_nolock function", "putchar_nolock function", "characters, writing", "standard output, writing to", "putwchar_nolock function", "_putchar_nolock function", "_putwchar_nolock function", "puttchar_nolock function"] -ms.assetid: 9ac68092-bfc3-4352-b486-c3e780220575 --- -# _putchar_nolock, _putwchar_nolock +# `_putchar_nolock`, `_putwchar_nolock` -Writes a character to **stdout** without locking the thread. +Writes a character to `stdout` without locking. ## Syntax @@ -27,35 +26,35 @@ wint_t _putwchar_nolock( ### Parameters -*c*
+*`c`*\ Character to be written. -## Return Value +## Return value See **putchar, putwchar**. ## Remarks -**putchar_nolock** and **_putwchar_nolock** are identical to the versions without the **_nolock** suffix except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`putchar_nolock`** and **`_putwchar_nolock`** are identical to the versions without the `_nolock` suffix except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttchar_nolock**|**_putchar_nolock**|**_putchar_nolock**|**_putwchar_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttchar_nolock` | **`_putchar_nolock`** | **`_putchar_nolock`** | **`_putwchar_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putchar_nolock**|\| -|**_putwchar_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_putchar_nolock`** | \ | +| **`_putwchar_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -89,6 +88,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md) diff --git a/docs/c-runtime-library/reference/putchar-putwchar.md b/docs/c-runtime-library/reference/putchar-putwchar.md index 378d4d7331..19f13eeb18 100644 --- a/docs/c-runtime-library/reference/putchar-putwchar.md +++ b/docs/c-runtime-library/reference/putchar-putwchar.md @@ -3,16 +3,16 @@ description: "Learn more about: putchar, putwchar" title: "putchar, putwchar" ms.date: "4/2/2020" api_name: ["putchar", "putwchar", "_o_putchar", "_o_putwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["putchar", "putwchar", "_puttchar"] helpviewer_keywords: ["putchar function", "_puttchar function", "characters, writing", "standard output, writing to", "putwchar function"] ms.assetid: 93657c7f-cca1-4032-8e3a-cd6ab6193748 --- -# putchar, putwchar +# `putchar`, `putwchar` -Writes a character to **stdout**. +Writes a character to `stdout`. ## Syntax @@ -27,41 +27,41 @@ wint_t putwchar( ### Parameters -*c*
+*`c`*\ Character to be written. -## Return Value +## Return value -Returns the character written. To indicate an error or end-of-file condition, **putc** and **putchar** return **EOF**; **putwc** and **putwchar** return **WEOF**. For all four routines, use [ferror](ferror.md) or [feof](feof.md) to check for an error or end of file. If passed a null pointer for *stream*, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **EOF** or **WEOF** and set **errno** to **EINVAL**. +Returns the character written. To indicate an error or end-of-file condition, `putc` and **`putchar`** return `EOF`; `putwc` and **`putwchar`** return `WEOF`. For all four routines, use [`ferror`](ferror.md) or [`feof`](feof.md) to check for an error or end of file. If passed a null pointer for *`stream`*, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, they return `EOF` or `WEOF`, and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **putc** routine writes the single character *c* to the output *stream* at the current position. Any integer can be passed to **putc**, but only the lower 8 bits are written. The **putchar** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **putc** and **putchar** are similar to **fputc** and **_fputchar**, respectively, but are implemented both as functions and as macros (see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md)). **putwc** and **putwchar** are wide-character versions of **putc** and **putchar**, respectively. +The `putc` routine writes the single character *`c`* to the output *`stream`* at the current position. Any integer can be passed to `putc`, but only the lower 8 bits are written. The **`putchar`** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. `putc` and **`putchar`** are similar to `fputc` and `_fputchar`, respectively, but are implemented both as functions and as macros (see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md)). `putwc` and **`putwchar`** are wide-character versions of `putc` and **`putchar`**, respectively. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_puttchar**|**putchar**|**putchar**|**putwchar**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttchar` | **`putchar`** | **`putchar`** | **`putwchar`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**putchar**|\| -|**putwchar**|\ or \| +| Routine | Required header | +|---|---| +| **`putchar`** | \ | +| **`putwchar`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -95,6 +95,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putenv-s-wputenv-s.md b/docs/c-runtime-library/reference/putenv-s-wputenv-s.md index b65903655f..6437099f5c 100644 --- a/docs/c-runtime-library/reference/putenv-s-wputenv-s.md +++ b/docs/c-runtime-library/reference/putenv-s-wputenv-s.md @@ -1,22 +1,23 @@ --- description: "Learn more about: _putenv_s, _wputenv_s" -title: "_putenv_s, _wputenv_s" +title: "_putenv_s, _wputenv_s, _tputenv_s" ms.date: "4/2/2020" -api_name: ["_wputenv_s", "_putenv_s", "_o__putenv_s", "_o__wputenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_wputenv_s", "_putenv_s", "_tputenv_s", "_o__putenv_s", "_o__wputenv_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["putenv_s", "wputenv_s", "_wputenv_s", "_putenv_s"] -helpviewer_keywords: ["wputenv_s function", "_putenv_s function", "environment variables, deleting", "putenv_s function", "_wputenv_s function", "environment variables, creating", "environment variables, modifying"] -ms.assetid: fbf51225-a8da-4b9b-9d7c-0b84ef72df18 +f1_keywords: ["putenv_s", "wputenv_s", "_wputenv_s", "_putenv_s", "_tputenv_s"] +helpviewer_keywords: ["wputenv_s function", "_putenv_s function", "environment variables, deleting", "putenv_s function", "_wputenv_s function", "environment variables, creating", "environment variables, modifying", "_tputenv_s function"] --- -# _putenv_s, _wputenv_s +# `_putenv_s`, `_wputenv_s`, `_tputenv_s` -Creates, modifies, or removes environment variables. These are versions of [_putenv, _wputenv](putenv-wputenv.md) but have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates, modifies, or removes environment variables. These functions are versions of [`_putenv`, `_wputenv`](putenv-wputenv.md) that have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +For `_tputenv_s`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -32,63 +33,65 @@ errno_t _wputenv_s( ### Parameters -*varname*
+*`varname`*\ The environment variable name. -*value_string*
+*`value_string`*\ The value to set the environment variable to. -## Return Value +## Return value Returns 0 if successful, or an error code. -### Error Conditions +### Error conditions -|*varname*|*value_string*|Return value| -|------------|-------------|------------------| -|**NULL**|any|**EINVAL**| -|any|**NULL**|**EINVAL**| +| *`varname`* | *`value_string`* | Return value | +|---|---|---| +| `NULL` | any | `EINVAL` | +| any | `NULL` | `EINVAL` | -If one of the error conditions occurs, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EINVAL** and set **errno** to **EINVAL**. +If one of the error conditions occurs, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. ## Remarks -The **_putenv_s** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **_wputenv_s** is a wide-character version of **_putenv_s**; the *envstring* argument to **_wputenv_s** is a wide-character string. +The **`_putenv_s`** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **`_wputenv_s`** is a wide-character version of **`_putenv_s`**; the *`envstring`* argument to **`_wputenv_s`** is a wide-character string. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tputenv_s**|**_putenv_s**|**_putenv_s**|**_wputenv_s**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tputenv_s` | `_putenv_s` | `_putenv_s` | `_wputenv_s` | -*varname* is the name of the environment variable to be added or modified and *value_string* is the variable's value. If *varname* is already part of the environment, its value is replaced by *value_string*; otherwise, the new *varname* variable and its *value_string* are added to the environment. You can remove a variable from the environment by specifying an empty string (that is, "") for *value_string*. +*`varname`* is the name of the environment variable to be added or modified and *`value_string`* is the variable's value. If *`varname`* is already part of the environment, its value is replaced by *`value_string`*; otherwise, the new *`varname`* variable and its *`value_string`* are added to the environment. You can remove a variable from the environment by specifying an empty string (that is, `""`) for *`value_string`*. -**_putenv_s** and **_wputenv_s** affect only the environment that is local to the current process; you cannot use them to modify the command-level environment. These functions operate only on data structures that are accessible to the run-time library and not on the environment "segment" that the operating system creates for a process. When the current process terminates, the environment reverts to the level of the calling process, which in most cases is the operating-system level. However, the modified environment can be passed to any new processes that are created by **_spawn**, **_exec**, or **system**, and these new processes get any new items that are added by **_putenv_s** and **_wputenv_s**. +**`_putenv_s`** and **`_wputenv_s`** affect only the environment that is local to the current process; you can't use them to modify the command-level environment. These functions operate only on data structures that are accessible to the run-time library and not on the environment "segment" that the operating system creates for a process. When the current process terminates, the environment reverts to the level of the calling process, which in most cases is the operating-system level. However, the modified environment can be passed to any new processes that are created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items that are added by **`_putenv_s`** and **`_wputenv_s`**. -Do not change an environment entry directly; instead, use **_putenv_s** or **_wputenv_s** to change it. In particular, directly freeing elements of the **_environ[]** global array might cause invalid memory to be addressed. +Don't change an environment entry directly; instead, use **`_putenv_s`** or **`_wputenv_s`** to change it. In particular, directly freeing elements of the **`_environ[]`** global array might cause invalid memory to be addressed. -**getenv** and **_putenv_s** use the global variable **_environ** to access the environment table; **_wgetenv** and **_wputenv_s** use **_wenviron**. **_putenv_s** and **_wputenv_s** may change the value of **_environ** and **_wenviron**, and thereby invalidate the *envp* argument to **main** and the **_wenvp** argument to **wmain**. Therefore, it is safer to use **_environ** or **_wenviron** to access the environment information. For more information about the relationship of **_putenv_s** and **_wputenv_s** to global variables, see [_environ, _wenviron](../../c-runtime-library/environ-wenviron.md). +**`getenv`** and **`_putenv_s`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv_s`** use **`_wenviron`**. **`_putenv_s`** and **`_wputenv_s`** may change the value of **`_environ`** and **`_wenviron`**, and thereby invalidate the *`envp`* argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relationship of **`_putenv_s`** and **`_wputenv_s`** to global variables, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] -> The **_putenv_s** and **_getenv_s** families of functions are not thread-safe. **_getenv_s** could return a string pointer while **_putenv_s** is modifying the string, and thereby cause random failures. Make sure that calls to these functions are synchronized. +> The **`_putenv_s`** and **`_getenv_s`** families of functions are not thread-safe. **`_getenv_s`** could return a string pointer while **`_putenv_s`** is modifying the string, and thereby cause random failures. Make sure that calls to these functions are synchronized. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putenv_s**|\| -|**_wputenv_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_putenv_s`** | `` | +| **`_wputenv_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -For a sample that shows how to use **_putenv_s**, see [getenv_s, _wgetenv_s](getenv-s-wgetenv-s.md). +For a sample that shows how to use **`_putenv_s`**, see [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_searchenv, _wsearchenv](searchenv-wsearchenv.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) diff --git a/docs/c-runtime-library/reference/putenv-wputenv.md b/docs/c-runtime-library/reference/putenv-wputenv.md index 6597359a16..943fa19760 100644 --- a/docs/c-runtime-library/reference/putenv-wputenv.md +++ b/docs/c-runtime-library/reference/putenv-wputenv.md @@ -3,16 +3,15 @@ description: "Learn more about: _putenv, _wputenv" title: "_putenv, _wputenv" ms.date: "4/2/2020" api_name: ["_putenv", "_wputenv", "_o__putenv", "_o__wputenv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tputenv", "_wputenv", "_putenv", "wputenv", "tputenv"] helpviewer_keywords: ["_putenv function", "environment variables, deleting", "putenv function", "tputenv function", "environment variables, creating", "wputenv function", "_wputenv function", "_tputenv function", "environment variables, modifying"] -ms.assetid: 9ba9b7fd-276e-45df-8420-d70c4204b8bd --- -# _putenv, _wputenv +# `_putenv`, `_wputenv` -Creates, modifies, or removes environment variables. More secure versions of these functions are available; see [_putenv_s, _wputenv_s](putenv-s-wputenv-s.md). +Creates, modifies, or removes environment variables. More secure versions of these functions are available; see [`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -30,51 +29,51 @@ int _wputenv( ### Parameters -*envstring*
+*`envstring`*\ Environment-string definition. -## Return Value +## Return value -Return 0 if successful or -1 in the case of an error. +The functions return 0 if successful, or -1 if there's an error. ## Remarks -The **_putenv** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **_wputenv** is a wide-character version of **_putenv**; the *envstring* argument to **_wputenv** is a wide-character string. +The **`_putenv`** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **`_wputenv`** is a wide-character version of **`_putenv`**; the *`envstring`* argument to **`_wputenv`** is a wide-character string. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tputenv**|**_putenv**|**_putenv**|**_wputenv**| +| `Tchar.h` routine | `_UNICODE and _MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tputenv` | **`_putenv`** | **`_putenv`** | **`_wputenv`** | -The *envstring* argument must be a pointer to a string of the form *varname*=*value_string*, where *varname* is the name of the environment variable to be added or modified and *value_string* is the variable's value. If *varname* is already part of the environment, its value is replaced by *value_string*; otherwise, the new *varname* variable and its *value_string* value are added to the environment. You can remove a variable from the environment by specifying an empty *value_string*, or in other words, by specifying only *varname*=. +The *`envstring`* argument must be a pointer to a string of the form *`varname=value_string`*, where *`varname`* is the name of the environment variable to be added or modified and *`value_string`* is the variable's value. If *`varname`* is already part of the environment, its value is replaced by *`value_string`*; otherwise, the new *`varname`* variable and its *`value_string`* value are added to the environment. You can remove a variable from the environment by specifying an empty *`value_string`*, or in other words, by specifying only *`varname`*=. -**_putenv** and **_wputenv** affect only the environment that is local to the current process; you cannot use them to modify the command-level environment. That is, these functions operate only on data structures accessible to the run-time library and not on the environment segment created for a process by the operating system. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level). However, the modified environment can be passed to any new processes created by **_spawn**, **_exec**, or **system**, and these new processes get any new items added by **_putenv** and **_wputenv**. +**`_putenv`** and **`_wputenv`** affect only the environment that is local to the current process; you can't use them to modify the command-level environment. That is, these functions operate only on data structures accessible to the run-time library. They don't operate on the environment segment created for a process by the operating system. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level). However, the modified environment can be passed to any new processes created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items added by **`_putenv`** and **`_wputenv`**. -Do not change an environment entry directly: instead, use **_putenv** or **_wputenv** to change it. In particular, direct freeing elements of the **_environ[]** global array might lead to invalid memory being addressed. +Don't change an environment entry directly: instead, use **`_putenv`** or **`_wputenv`** to change it. In particular, direct freeing elements of the **`_environ[]`** global array might lead to invalid memory being addressed. -**getenv** and **_putenv** use the global variable **_environ** to access the environment table; **_wgetenv** and **_wputenv** use **_wenviron**. **_putenv** and **_wputenv** might change the value of **_environ** and **_wenviron**, thus invalidating the **_envp** argument to **main** and the **_wenvp** argument to **wmain**. Therefore, it is safer to use **_environ** or **_wenviron** to access the environment information. For more information about the relation of **_putenv** and **_wputenv** to global variables, see [_environ, _wenviron](../../c-runtime-library/environ-wenviron.md). +**`_getenv`** and **`_putenv`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv`** use **`_wenviron`**. **`_putenv`** and **`_wputenv`** might change the value of **`_environ`** and **`_wenviron`**, thus invalidating the **`_envp`** argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relation of **`_putenv`** and **`_wputenv`** to global variables, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] -> The **_putenv** and **_getenv** families of functions are not thread-safe. **_getenv** could return a string pointer while **_putenv** is modifying the string, causing random failures. Make sure that calls to these functions are synchronized. +> The **`_putenv`** and **`_getenv`** families of functions are not thread-safe. **`_getenv`** could return a string pointer while **`_putenv`** is modifying the string, causing random failures. Make sure that calls to these functions are synchronized. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putenv**|\| -|**_wputenv**|\ or \| +| Routine | Required header | +|---|---| +| **`_putenv`** | `` | +| **`_wputenv`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -For a sample of how to use **_putenv**, see [getenv, _wgetenv](getenv-wgetenv.md). +For a sample of how to use **`_putenv`**, see [`getenv`, `_wgetenv`](getenv-wgetenv.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_searchenv, _wsearchenv](searchenv-wsearchenv.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) diff --git a/docs/c-runtime-library/reference/putenv.md b/docs/c-runtime-library/reference/putenv.md index 92499d53ef..ced02af37e 100644 --- a/docs/c-runtime-library/reference/putenv.md +++ b/docs/c-runtime-library/reference/putenv.md @@ -10,11 +10,11 @@ f1_keywords: ["putenv"] helpviewer_keywords: ["putenv function"] ms.assetid: 1dc49ef3-6b12-484c-8e60-7048bcc999f1 --- -# putenv +# `putenv` -The Microsoft-implemented POSIX function name `putenv` is a deprecated alias for the [_putenv](putenv-wputenv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `putenv` is a deprecated alias for the [`_putenv`](putenv-wputenv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putenv](putenv-wputenv.md) or security-enhanced [_putenv_s](putenv-s-wputenv-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putenv`](putenv-wputenv.md) or security-enhanced [`_putenv_s`](putenv-s-wputenv-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/puts-putws.md b/docs/c-runtime-library/reference/puts-putws.md index 1c9ad50eed..c7a68163da 100644 --- a/docs/c-runtime-library/reference/puts-putws.md +++ b/docs/c-runtime-library/reference/puts-putws.md @@ -3,16 +3,16 @@ description: "Learn more about: puts, _putws" title: "puts, _putws" ms.date: "4/2/2020" api_name: ["_putws", "puts", "_o__putws", "_o_puts"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putts", "_putws", "puts"] helpviewer_keywords: ["strings [C++], writing", "_putts function", "standard output, writing to", "putws function", "puts function", "putts function", "_putws function"] ms.assetid: 32dada12-ed45-40ac-be06-3feeced9ecd6 --- -# puts, _putws +# `puts`, `_putws` -Writes a string to **stdout**. +Writes a string to `stdout`. ## Syntax @@ -27,43 +27,43 @@ int _putws( ### Parameters -*str*
+*`str`*\ Output string. -## Return Value +## Return value -Returns a nonnegative value if successful. If **puts** fails, it returns **EOF**; if **_putws** fails, it returns **WEOF**. If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **errno** to **EINVAL** and return **EOF** or **WEOF**. +Returns a nonnegative value if successful. If **`puts`** fails, it returns `EOF`; if **`_putws`** fails, it returns `WEOF`. If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL` and return `EOF` or `WEOF`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **puts** function writes *str* to the standard output stream **stdout**, replacing the string's terminating null character ('\0') with a newline character ('\n') in the output stream. +The **`puts`** function writes *`str`* to the standard output stream `stdout`, replacing the string's terminating null character ('\0') with a newline character ('\n') in the output stream. -**_putws** is the wide-character version of **puts**; the two functions behave identically if the stream is opened in ANSI mode. **puts** doesn't currently support output into a UNICODE stream. +**`_putws`** is the wide-character version of **`puts`**; the two functions behave identically if the stream is opened in ANSI mode. **`puts`** doesn't currently support output into a UNICODE stream. -**_putwch** writes Unicode characters using the current CONSOLE LOCALE setting. +`_putwch` writes Unicode characters using the current CONSOLE LOCALE setting. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_putts**|**puts**|**puts**|**_putws**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_putts` | **`puts`** | **`puts`** | **`_putws`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**puts**|\| -|**_putws**|\| +| Routine | Required header | +|---|---| +| **`puts`** | \ | +| **`_putws`** | \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -87,6 +87,6 @@ Hello world from puts! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputs, fputws](fputs-fputws.md)
-[fgets, fgetws](fgets-fgetws.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputs`, `fputws`](fputs-fputws.md)\ +[`fgets`, `fgetws`](fgets-fgetws.md) diff --git a/docs/c-runtime-library/reference/putw.md b/docs/c-runtime-library/reference/putw.md index b8f32d74a6..3f5bd5725d 100644 --- a/docs/c-runtime-library/reference/putw.md +++ b/docs/c-runtime-library/reference/putw.md @@ -3,14 +3,14 @@ description: "Learn more about: _putw" title: "_putw" ms.date: "4/2/2020" api_name: ["_putw", "_o__putw"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putw"] helpviewer_keywords: ["integers, writing to streams", "putw function", "streams, writing integers to", "_putw function"] ms.assetid: 83d63644-249d-4a39-87e5-3b7aa313968d --- -# _putw +# `_putw` Writes an integer to a stream. @@ -25,35 +25,35 @@ int _putw( ### Parameters -*binint*
+*`binint`*\ Binary integer to be output. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -Returns the value written. A return value of **EOF** might indicate an error. Because **EOF** is also a legitimate integer value, use **ferror** to verify an error. If *stream* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EOF**. +Returns the value written. A return value of `EOF` might indicate an error. Because `EOF` is also a legitimate integer value, use `ferror` to verify an error. If *`stream`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EOF`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_putw** function writes a binary value of type **`int`** to the current position of *stream.* **_putw** does not affect the alignment of items in the stream nor does it assume any special alignment. **_putw** is primarily for compatibility with previous libraries. Portability problems might occur with **_putw** because the size of an **`int`** and the ordering of bytes within an **`int`** differ across systems. +The **`_putw`** function writes a binary value of type **`int`** to the current position of *stream.* **`_putw`** doesn't affect the alignment of items in the stream nor does it assume any special alignment. **`_putw`** is primarily for compatibility with previous libraries. Portability problems might occur with **`_putw`** because the size of an **`int`** and the ordering of bytes within an **`int`** differ across systems. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putw**|\| +| Routine | Required header | +|---|---| +| **`_putw`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -95,5 +95,5 @@ Wrote ten words ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getw](getw.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getw`](getw.md) diff --git a/docs/c-runtime-library/reference/qsort-s.md b/docs/c-runtime-library/reference/qsort-s.md index 5011d7297c..d5703f65c0 100644 --- a/docs/c-runtime-library/reference/qsort-s.md +++ b/docs/c-runtime-library/reference/qsort-s.md @@ -3,16 +3,16 @@ description: "Learn more about: qsort_s" title: "qsort_s" ms.date: "4/2/2020" api_name: ["qsort_s", "_o_qsort_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["qsort_s"] helpviewer_keywords: ["arrays [C++], sorting", "quick-sort algorithm", "qsort_s function", "sorting arrays"] ms.assetid: 6ee817b0-4408-4355-a5d4-6605e419ab91 --- -# qsort_s +# `qsort_s` -Performs a quick sort. A version of [qsort](qsort.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Performs a quick sort. A version of [`qsort`](qsort.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -28,24 +28,24 @@ void qsort_s( ### Parameters -*base*
+*`base`*\ Start of target array. -*number*
+*`number`*\ Array size in elements. -*width*
+*`width`*\ Element size in bytes. -*compare*
-Comparison function. The first argument is the *context* pointer. The second argument is a pointer to the *key* for the search. The third argument is a pointer to the array element to be compared with *key*. +*`compare`*\ +Comparison function. The first argument is the *`context`* pointer. The second argument is a pointer to the *`key`* for the search. The third argument is a pointer to the array element to be compared with *`key`*. -*context*
-A pointer to a context, which can be any object that the *compare* routine needs to access. +*`context`*\ +A pointer to a context, which can be any object that the *`compare`* routine needs to access. ## Remarks -The **qsort_s** function implements a quick-sort algorithm to sort an array of *number* elements, each of *width* bytes. The argument *base* is a pointer to the base of the array to be sorted. **qsort_s** overwrites this array with the sorted elements. The argument *compare* is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **qsort_s** calls the *compare* routine one or more times during the sort, passing pointers to two array elements on each call: +The **`qsort_s`** function implements a quick-sort algorithm to sort an array of *`number`* elements, each of *`width`* bytes. The argument *`base`* is a pointer to the base of the array to be sorted. **`qsort_s`** overwrites this array with the sorted elements. The argument *`compare`* is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **`qsort_s`** calls the *`compare`* routine one or more times during the sort, passing pointers to two array elements on each call: ```C compare( context, (void *) & elem1, (void *) & elem2 ); @@ -53,42 +53,42 @@ compare( context, (void *) & elem1, (void *) & elem2 ); The routine must compare the elements and then return one of the following values: -|Return value|Description| -|------------------|-----------------| -|< 0|**elem1** less than **elem2**| -|0|**elem1** equivalent to **elem2**| -|> 0|**elem1** greater than **elem2**| +| Return value | Description | +|---|---| +| < 0 | *element 1* less than *element 2* | +| 0 | *element 1* equivalent to *element 2* | +| > 0 | *element 1* greater than *element 2* | The array is sorted in increasing order, as defined by the comparison function. To sort an array in decreasing order, reverse the sense of "greater than" and "less than" in the comparison function. -If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, then the function returns and **errno** is set to **EINVAL**. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, then the function returns, and `errno` is set to `EINVAL`. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Error Conditions +### Error conditions -|key|base|compare|num|width|errno| -|---------|----------|-------------|---------|-----------|-----------| -|**NULL**|any|any|any|any|**EINVAL**| -|any|**NULL**|any|!= 0|any|**EINVAL**| -|any|any|any|any|<= 0|**EINVAL**| -|any|any|**NULL**|any|any|**EINVAL**| +| key | base | compare | num | width | errno | +|---|---|---|---|---|---| +| `NULL` | any | any | any | any | `EINVAL` | +| any | `NULL` | any | != 0 | any | `EINVAL` | +| any | any | any | any | <= 0 | `EINVAL` | +| any | any | `NULL` | any | any | `EINVAL` | -**qsort_s** has the same behavior as **qsort** but has the *context* parameter and sets **errno**. By passing a *context* parameter, comparison functions can use an object pointer to access object functionality or other information not accessible through an element pointer. The addition of the *context* parameter makes **qsort_s** more secure because *context* can be used to avoid reentrancy bugs introduced by using static variables to make shared information available to the *compare* function. +**`qsort_s`** has the same behavior as `qsort` but has the *`context`* parameter and sets `errno`. The *`context`* parameter allows comparison functions to use an object pointer to access object functionality or other information not accessible through an element pointer. The addition of the *`context`* parameter makes **`qsort_s`** more secure because *`context`* can be used to avoid reentrancy bugs introduced by using static variables to make shared information available to the *`compare`* function. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**qsort_s**|\ and \| +| Routine | Required header | +|---|---| +| **`qsort_s`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [C runtime libraries](../crt-library-features.md). ## Example -The following example demonstrates how to use the *context* parameter in the **qsort_s** function. The *context* parameter makes it easier to perform thread-safe sorts. Instead of using static variables that must be synchronized to ensure thread safety, pass a different *context* parameter in each sort. In this example, a locale object is used as the *context* parameter. +The following example demonstrates how to use the *`context`* parameter in the **`qsort_s`** function. The *`context`* parameter makes it easier to perform thread-safe sorts. Instead of using static variables that must be synchronized to ensure thread safety, pass a different *`context`* parameter in each sort. In this example, a locale object is used as the *`context`* parameter. ```cpp // crt_qsort_s.cpp @@ -227,7 +227,7 @@ int main( ) } ``` -### Sample Output +### Sample output ```Output Unsorted input: @@ -242,7 +242,7 @@ table tablet tableux ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[bsearch_s](bsearch-s.md)
-[_lsearch_s](lsearch-s.md)
-[qsort](qsort.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`bsearch_s`](bsearch-s.md)\ +[`_lsearch_s`](lsearch-s.md)\ +[`qsort`](qsort.md) diff --git a/docs/c-runtime-library/reference/qsort.md b/docs/c-runtime-library/reference/qsort.md index c97420b03d..9364fefb82 100644 --- a/docs/c-runtime-library/reference/qsort.md +++ b/docs/c-runtime-library/reference/qsort.md @@ -1,18 +1,17 @@ --- title: "qsort" description: "Describes the Microsoft C runtime quick sort API `qsort`" -ms.date: "10/23/2020" +ms.date: "8/2/2023" api_name: ["qsort", "_o_qsort"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["qsort"] helpviewer_keywords: ["qsort function", "quick-sort algorithm", "sorting arrays", "arrays [CRT], sorting"] -ms.assetid: d6cb33eb-d209-485f-8d41-229eb743c027 --- -# qsort +# `qsort` -Performs a quick sort. A more secure version of this function is available; see [qsort_s](qsort-s.md). +Performs a quick sort. A more secure version of this function is available; see [`qsort_s`](qsort-s.md). ## Syntax @@ -46,30 +45,30 @@ The **`qsort`** function implements a quick-sort algorithm to sort an array of * **`qsort`** calls the *`compare`* routine one or more times during the sort, and passes pointers to two array elements on each call. If *`compare`* indicates two elements are the same, their order in the resulting sorted array is unspecified. ```C -compare( (void *) & elem1, (void *) & elem2 ); +compare(const void *elem1, const void *elem2); ``` The routine compares the elements and returns one of the following values. -|Compare function return value|Description| -|-----------------------------------|-----------------| -|< 0|**`elem1`** less than **`elem2`**| -|0|**`elem1`** equivalent to **`elem2`**| -|> 0|**`elem1`** greater than **`elem2`**| +| Compare function return value | Description | +|---|---| +| < 0 | **`elem1`** less than **`elem2`** | +| 0 | **`elem1`** equivalent to **`elem2`** | +| > 0 | **`elem1`** greater than **`elem2`** | The array is sorted in increasing order, as defined by the comparison function. To sort an array in decreasing order, reverse the sense of "greater than" and "less than" in the comparison function. -This function validates its parameters. If *`compare`* or *`number`* is **`NULL`**, or if *`base`* is **`NULL`** and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns and **`errno`** is set to **`EINVAL`**. +This function validates its parameters. If *`compare`* or *`number`* is `NULL`, or if *`base`* is `NULL` and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns, and `errno` is set to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`qsort`**|\ and \| +| Routine | Required header | +|---|---| +| **`qsort`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -117,6 +116,6 @@ boy deserves every favor good ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)\ +[Searching and sorting](../searching-and-sorting.md)\ [`bsearch`](bsearch.md)\ [`_lsearch`](lsearch.md) diff --git a/docs/c-runtime-library/reference/query-new-handler.md b/docs/c-runtime-library/reference/query-new-handler.md index 62f280d87d..d78494f3fa 100644 --- a/docs/c-runtime-library/reference/query-new-handler.md +++ b/docs/c-runtime-library/reference/query-new-handler.md @@ -10,9 +10,9 @@ f1_keywords: ["_query_new_handler", "query_new_handler"] helpviewer_keywords: ["query_new_handler function", "handler routines", "error handling", "_query_new_handler function"] ms.assetid: 9a84b5c3-fe33-4c01-83a0-be87dc3ec518 --- -# _query_new_handler +# `_query_new_handler` -Returns the address of the current new handler routine. +Returns the address of the current **`new`** handler routine. ## Syntax @@ -22,27 +22,27 @@ _PNH _query_new_handler( ); ``` -## Return Value +## Return value -Returns the address of the current new handler routine as set by **_set_new_handler**. +Returns the address of the current **`new`** handler routine as set by `_set_new_handler`. ## Remarks -The C++ **_query_new_handler** function returns the address of the current exception-handling function set by the C++ [_set_new_handler](set-new-handler.md) function. **_set_new_handler** is used to specify an exception-handling function that is to gain control if the **`new`** operator fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. +The C++ **`_query_new_handler`** function returns the address of the current exception-handling function set by the C++ [`_set_new_handler`](set-new-handler.md) function. `_set_new_handler` is used to specify an exception-handling function that is to gain control if the **`new`** operator fails to allocate memory. For more information, see the discussion of the [`new` and `delete` operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_query_new_handler**|\| +| Routine | Required header | +|---|---| +| **`_query_new_handler`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[free](free.md)
+[Memory allocation](../memory-allocation.md)\ +[`free`](free.md) diff --git a/docs/c-runtime-library/reference/query-new-mode.md b/docs/c-runtime-library/reference/query-new-mode.md index 72e4d3ef34..d5feb921c3 100644 --- a/docs/c-runtime-library/reference/query-new-mode.md +++ b/docs/c-runtime-library/reference/query-new-mode.md @@ -10,9 +10,9 @@ f1_keywords: ["query_new_mode", "_query_new_mode"] helpviewer_keywords: ["query_new_mode function", "handler modes", "_query_new_mode function"] ms.assetid: e185c5f9-b73b-4257-8eff-b47648374768 --- -# _query_new_mode +# `_query_new_mode` -Returns an integer indicating the new handler mode set by **_set_new_mode** for **malloc**. +Returns an integer indicating the **`new`** handler mode set by `_set_new_mode` for `malloc`. ## Syntax @@ -22,30 +22,30 @@ int _query_new_mode( ); ``` -## Return Value +## Return value -Returns the current new handler mode, namely 0 or 1, for **malloc**. A return value of 1 indicates that, on failure to allocate memory, **malloc** calls the new handler routine; a return value of 0 indicates that it does not. +Returns the current **`new`** handler mode, namely 0 or 1, for `malloc`. A return value of 1 indicates that, on failure to allocate memory, `malloc` calls the **`new`** handler routine; a return value of 0 indicates that it doesn't. ## Remarks -The C++ **_query_new_mode** function returns an integer that indicates the new handler mode that is set by the C++ [_set_new_mode](set-new-mode.md) function for [malloc](malloc.md). The new handler mode indicates whether, on failure to allocate memory, **malloc** is to call the new handler routine as set by [_set_new_handler](set-new-handler.md). By default, **malloc** does not call the new handler routine on failure. You can use **_set_new_mode** to override this behavior so that on failure **malloc** calls the new handler routine in the same way that the **`new`** operator does when it fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. +The C++ **`_query_new_mode`** function returns an integer that indicates the **`new`** handler mode that is set by the C++ [`_set_new_mode`](set-new-mode.md) function for [`malloc`](malloc.md). The **`new`** handler mode indicates whether, on failure to allocate memory, `malloc` is to call the **`new`** handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, `malloc` doesn't call the **`new`** handler routine on failure. You can use `_set_new_mode` to override this behavior so that on failure `malloc` calls the **`new`** handler routine in the same way that the **`new`** operator does when it fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_query_new_mode**|\| +| Routine | Required header | +|---|---| +| **`_query_new_mode`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[realloc](realloc.md)
-[_query_new_handler](query-new-handler.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`realloc`](realloc.md)\ +[`_query_new_handler`](query-new-handler.md) diff --git a/docs/c-runtime-library/reference/quick-exit1.md b/docs/c-runtime-library/reference/quick-exit1.md index ee93627429..77eba98477 100644 --- a/docs/c-runtime-library/reference/quick-exit1.md +++ b/docs/c-runtime-library/reference/quick-exit1.md @@ -10,7 +10,7 @@ f1_keywords: ["quick_exit", "process/quick_exit", "stdlib/quick_exit"] helpviewer_keywords: ["quick_exit function"] ms.assetid: ecfbdae6-01c4-45fa-aaeb-b368e1de2a9c --- -# quick_exit +# `quick_exit` Causes normal program termination to occur. @@ -24,36 +24,36 @@ __declspec(noreturn) void quick_exit( ### Parameters -*status*
+*`status`*\ The status code to return to the host environment. -## Return Value +## Return value -The **quick_exit** function cannot return to its caller. +The **`quick_exit`** function can't return to its caller. ## Remarks -The **quick_exit** function causes normal program termination. It calls no functions registered by **atexit**, **_onexit** or signal handlers registered by the **signal** function. Behavior is undefined if **quick_exit** is called more than once, or if the **exit** function is also called. +The **`quick_exit`** function causes normal program termination. It calls no functions registered by `atexit`, `_onexit` or signal handlers registered by the `signal` function. Behavior is undefined if **`quick_exit`** is called more than once, or if the `exit` function is also called. -The **quick_exit** function calls, in last-in, first-out (LIFO) order, the functions registered by **at_quick_exit**, except for those functions already called when the function was registered. Behavior is undefined if a [longjmp](longjmp.md) call is made during a call to a registered function that would terminate the call to the function. +The **`quick_exit`** function calls, in last-in, first-out (LIFO) order, the functions registered by `at_quick_exit`, except for those functions already called when the function was registered. Behavior is undefined if a [`longjmp`](longjmp.md) call is made during a call to a registered function that would terminate the call to the function. -After the registered functions have been called, **quick_exit** invokes **_Exit** by using the *status* value to return control to the host environment. +After the registered functions have been called, **`quick_exit`** invokes `_Exit` by using the *`status`* value to return control to the host environment. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**quick_exit**|\ or \| +| Routine | Required header | +|---|---| +| **`quick_exit`** | \ or \ | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/raise.md b/docs/c-runtime-library/reference/raise.md index 469d8528f7..e3fe3e05b6 100644 --- a/docs/c-runtime-library/reference/raise.md +++ b/docs/c-runtime-library/reference/raise.md @@ -3,18 +3,18 @@ description: "Learn more about: raise" title: "raise" ms.date: "4/2/2020" api_name: ["raise", "_o_raise"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["Raise"] helpviewer_keywords: ["signals, sending to executing programs", "raise function", "signals", "programs [C++], sending signals to executing programs"] --- -# raise +# `raise` Sends a signal to the executing program. > [!NOTE] -> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -26,40 +26,40 @@ int raise( ### Parameters -*sig*
+*`sig`*\ Signal to be raised. -## Return Value +## Return value -If successful, **raise** returns 0. Otherwise, it returns a nonzero value. +If successful, **`raise`** returns 0. Otherwise, it returns a nonzero value. ## Remarks -The **raise** function sends *sig* to the executing program. If a previous call to **signal** has installed a signal-handling function for *sig*, **raise** executes that function. If no handler function has been installed, the default action associated with the signal value *sig* is taken, as follows. +The **`raise`** function sends *`sig`* to the executing program. If a previous call to `signal` has installed a signal-handling function for *`sig`*, **`raise`** executes that function. If no handler function has been installed, the default action associated with the signal value *`sig`* is taken, as follows. -|Signal|Meaning|Default| -|------------|-------------|-------------| -|**SIGABRT**|Abnormal termination|Terminates the calling program with exit code 3| -|**SIGFPE**|Floating-point error|Terminates the calling program| -|**SIGILL**|Illegal instruction|Terminates the calling program| -|**SIGINT**|CTRL+C interrupt|Terminates the calling program| -|**SIGSEGV**|Illegal storage access|Terminates the calling program| -|**SIGTERM**|Termination request sent to the program|Ignores the signal| +| Signal | Description | Default behavior | +|---|---|---| +| `SIGABRT` | Abnormal termination | Terminates the calling program with exit code 3 | +| `SIGFPE` | Floating-point error | Terminates the calling program | +| `SIGILL` | Illegal instruction | Terminates the calling program | +| `SIGINT` | CTRL+C interrupt | Terminates the calling program | +| `SIGSEGV` | Illegal storage access | Terminates the calling program | +| `SIGTERM` | Termination request sent to the program | Ignores the signal | -If the argument is not a valid signal as specified above, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If not handled, the function sets **errno** to **EINVAL** and returns a nonzero value. +If the argument isn't a valid signal as specified above, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If not handled, the function sets `errno` to `EINVAL` and returns a nonzero value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**raise**|\| +| Routine | Required header | +|---|---| +| **`raise`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[signal](signal.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`signal`](signal.md) diff --git a/docs/c-runtime-library/reference/rand-s.md b/docs/c-runtime-library/reference/rand-s.md index 28de721e49..427578e5e0 100644 --- a/docs/c-runtime-library/reference/rand-s.md +++ b/docs/c-runtime-library/reference/rand-s.md @@ -3,15 +3,15 @@ description: "Learn more about: rand_s" title: "rand_s" ms.date: "4/2/2020" api_name: ["rand_s", "_o_rand_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["rand_s"] +f1_keywords: ["STDLIB/rand_s", "rand_s"] helpviewer_keywords: ["generating pseudorandom numbers", "random numbers, cryptographically secure", "random numbers, generating", "rand_s function", "numbers, pseudorandom", "cryptographically secure random numbers", "pseudorandom numbers", "numbers, generating pseudorandom"] --- -# rand_s +# `rand_s` -Generates a pseudorandom number. This is a more secure version of the function [rand](rand.md), with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Generates a pseudorandom number. This function is a more secure version of the function [`rand`](rand.md), with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -21,35 +21,35 @@ errno_t rand_s(unsigned int* randomValue); ### Parameters -*randomValue*
+*`randomValue`*\ A pointer to an integer to hold the generated value. -## Return Value +## Return value -Zero if successful, otherwise, an error code. If the input pointer _randomValue_ is a null pointer, the function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **EINVAL** and sets **errno** to **EINVAL**. If the function fails for any other reason, *_randomValue_ is set to 0. +Zero if successful, otherwise, an error code. If the input pointer `_randomValue_` is a `NULL` pointer, the function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `EINVAL` and sets `errno` to `EINVAL`. If the function fails for any other reason, `*_randomValue_` is set to 0. ## Remarks -The **rand_s** function writes a pseudorandom integer in the range 0 to **UINT_MAX** to the input pointer. The **rand_s** function uses the operating system to generate cryptographically secure random numbers. It does not use the seed generated by the [srand](srand.md) function, nor does it affect the random number sequence used by [rand](rand.md). +The **`rand_s`** function writes a pseudorandom integer in the range 0 to `UINT_MAX` to the input pointer. The **`rand_s`** function uses the operating system to generate cryptographically secure random numbers. It doesn't use the seed generated by the [`srand`](srand.md) function, nor does it affect the random number sequence used by [`rand`](rand.md). -The **rand_s** function requires that constant **_CRT_RAND_S** be defined prior to the inclusion statement for the function to be declared, as in the following example: +The `_CRT_RAND_S` constant must be defined before the `stdlib.h` header for the **`rand_s`** function is included, as shown in the following example: -```C -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). +```C #define _CRT_RAND_S #include ``` -**rand_s** depends on the [RtlGenRandom](/windows/win32/api/ntsecapi/nf-ntsecapi-rtlgenrandom) API, which is only available in Windows XP and later. +**`rand_s`** depends on the [`RtlGenRandom`](/windows/win32/api/ntsecapi/nf-ntsecapi-rtlgenrandom) API, which is only available in Windows XP and later. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**rand_s**|\| +| Routine | Required header | +|---|---| +| **`rand_s`** | `` | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Example @@ -58,8 +58,8 @@ For more information, see [Compatibility](../../c-runtime-library/compatibility. // This program illustrates how to generate random // integer or floating point numbers in a specified range. -// Remembering to define _CRT_RAND_S prior -// to inclusion statement. +// Remember to define _CRT_RAND_S before you include +// stdlib.h. #define _CRT_RAND_S #include @@ -101,7 +101,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output 10 @@ -129,6 +129,6 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[rand](rand.md)
-[srand](srand.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`rand`](rand.md)\ +[`srand`](srand.md) diff --git a/docs/c-runtime-library/reference/rand.md b/docs/c-runtime-library/reference/rand.md index 3fc18adbcc..2c065c0b39 100644 --- a/docs/c-runtime-library/reference/rand.md +++ b/docs/c-runtime-library/reference/rand.md @@ -3,10 +3,10 @@ title: "rand" description: "API reference for rand, which generates a pseudorandom number by using a well-known and fully reproducible algorithm." ms.date: "7/7/2021" api_name: ["rand", "_o_rand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["rand"] +f1_keywords: ["STDLIB/rand", "rand"] helpviewer_keywords: ["generating pseudorandom numbers", "random numbers, generating", "numbers, pseudorandom", "rand function", "pseudorandom numbers", "numbers, generating pseudorandom"] --- # `rand` @@ -19,25 +19,25 @@ Generates a pseudorandom number. A more programmatically secure version of this int rand(void); ``` -## Return Value +## Return value **`rand`** returns a pseudorandom number, as described above. There's no error return. ## Remarks -The **`rand`** function returns a pseudorandom integer in the range 0 to **`RAND_MAX`** (32767). Use the [`srand`](srand.md) function to seed the pseudorandom-number generator before calling **`rand`**. +The **`rand`** function returns a pseudorandom integer in the range 0 to `RAND_MAX` (32767). Use the [`srand`](srand.md) function to seed the pseudorandom-number generator before calling **`rand`**. The **`rand`** function generates a well-known sequence and isn't appropriate for use as a cryptographic function. For more cryptographically secure random number generation, use [`rand_s`](rand-s.md) or the functions declared in the C++ Standard Library in [``](../../standard-library/random.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`rand`**|``| +| Routine | Required header | +|---|---| +| **`rand`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -72,7 +72,7 @@ void RangedRandDemo(int range_min, int range_max, int n) // generating random numbers across a large range using the method below. // The approach below also may result in a non-uniform distribution. // More robust random number functionality is available in the C++ header. - // See https://docs.microsoft.com/cpp/standard-library/random + // See https://learn.microsoft.com/cpp/standard-library/random int r = ((double)rand() / RAND_MAX) * (range_max - range_min) + range_min; printf(" %6d\n", r); } @@ -120,7 +120,7 @@ Random number in a range demo ==== ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`srand`](srand.md)\ [`rand_s`](rand-s.md)\ [C++ `` library](../../standard-library/random.md) diff --git a/docs/c-runtime-library/reference/read.md b/docs/c-runtime-library/reference/read.md index 8d2abf6367..2e7096eca6 100644 --- a/docs/c-runtime-library/reference/read.md +++ b/docs/c-runtime-library/reference/read.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _read" title: "_read" +description: "Learn more about: _read" ms.date: "4/2/2020" api_name: ["_read", "_o__read"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_read"] helpviewer_keywords: ["data [CRT]", "_read function", "read function", "data [C++], reading", "reading data [C++]", "files [C++], reading"] -ms.assetid: 2ce9c433-57ad-47fe-9ac1-4a7d4c883d30 --- -# _read +# `_read` Reads data from a file. @@ -26,44 +25,44 @@ int _read( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to the open file. -*buffer*
+*`buffer`*\ Storage location for data. -*buffer_size*
+*`buffer_size`*\ Maximum number of bytes to read. -## Return Value +## Return value -**_read** returns the number of bytes read, which might be less than *buffer_size* if there are fewer than *buffer_size* bytes left in the file, or if the file was opened in text mode. In text mode, each carriage return-line feed pair `\r\n` is replaced with a single line feed character `\n`. Only the single line feed character is counted in the return value. The replacement does not affect the file pointer. +**`_read`** returns the number of bytes read, which might be less than *`buffer_size`* if there are fewer than *`buffer_size`* bytes left in the file, or if the file was opened in text mode. In text mode, each carriage return-line feed pair `\r\n` is replaced with a single line feed character `\n`. Only the single line feed character is counted in the return value. The replacement doesn't affect the file pointer. -If the function tries to read at end of file, it returns 0. If *fd* is not valid, the file isn't open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **errno** to **EBADF**. +If the function tries to read at end of file, it returns 0. If *`fd`* isn't valid, the file isn't open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EBADF`. -If *buffer* is **NULL**, or if *buffer_size* > **INT_MAX**, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and **errno** is set to **EINVAL**. +If *`buffer`* is `NULL`, or if *`buffer_size`* > `INT_MAX`, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and `errno` is set to `EINVAL`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_read** function reads a maximum of *buffer_size* bytes into *buffer* from the file associated with *fd*. The read operation begins at the current position of the file pointer associated with the given file. After the read operation, the file pointer points to the next unread character. +The **`_read`** function reads a maximum of *`buffer_size`* bytes into *`buffer`* from the file associated with *`fd`*. The read operation begins at the current position of the file pointer associated with the given file. After the read operation, the file pointer points to the next unread character. -If the file was opened in text mode, the read terminates when **_read** encounters a CTRL+Z character, which is treated as an end-of-file indicator. Use [_lseek](lseek-lseeki64.md) to clear the end-of-file indicator. +If the file was opened in text mode, the read terminates when **`_read`** encounters a CTRL+Z character, which is treated as an end-of-file indicator. Use [`_lseek`](lseek-lseeki64.md) to clear the end-of-file indicator. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_read**|\| +| Routine | Required header | +|---|---| +| **`_read`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -120,8 +119,8 @@ Read 19 bytes from file ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_creat, _wcreat](creat-wcreat.md)
-[fread](fread.md)
-[_open, _wopen](open-wopen.md)
-[_write](write.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`fread`](fread.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_write`](write.md) diff --git a/docs/c-runtime-library/reference/realloc-dbg.md b/docs/c-runtime-library/reference/realloc-dbg.md index f782ea0c5d..7fe5026780 100644 --- a/docs/c-runtime-library/reference/realloc-dbg.md +++ b/docs/c-runtime-library/reference/realloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_realloc_dbg", "realloc_dbg"] helpviewer_keywords: ["reallocating memory blocks", "realloc_dbg function", "memory blocks, reallocating", "memory, reallocating", "_realloc_dbg function"] ms.assetid: 7c3cb780-51ed-4d9c-9929-cdde606d846a --- -# _realloc_dbg +# `_realloc_dbg` Reallocates a specified block of memory in the heap by moving and/or resizing the block (debug version only). @@ -28,54 +28,54 @@ void *_realloc_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*newSize*
+*`newSize`*\ Requested size for the reallocated block (bytes). -*blockType*
-Requested type for the reallocated block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type for the reallocated block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested the **realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the `realloc` operation or `NULL`. -*linenumber*
-Line number in the source file where the **realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the `realloc` operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_realloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_realloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [realloc](realloc.md) function. +On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [`realloc`](realloc.md) function. ## Remarks -**_realloc_dbg** is a debug version of the [realloc](realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_realloc_dbg** is reduced to a call to **realloc**. Both **realloc** and **_realloc_dbg** reallocate a memory block in the base heap, but **_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +**`_realloc_dbg`** is a debug version of the [`realloc`](realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_realloc_dbg`** is reduced to a call to `realloc`. Both `realloc` and **`_realloc_dbg`** reallocate a memory block in the base heap, but **`_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in both moving the original memory block to a different location in the heap, and changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -**_realloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_realloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -See the example in the [_msize_dbg](msize-dbg.md) topic. +See the example in the [`_msize_dbg`](msize-dbg.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/realloc.md b/docs/c-runtime-library/reference/realloc.md index 4414bb1251..164743a684 100644 --- a/docs/c-runtime-library/reference/realloc.md +++ b/docs/c-runtime-library/reference/realloc.md @@ -3,7 +3,7 @@ title: "realloc" description: "API reference for realloc(); which reallocates memory blocks." ms.date: "9/11/2020" api_name: ["realloc", "_o_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_brealloc", "_nrealloc", "realloc", "_frealloc"] @@ -31,13 +31,13 @@ Pointer to previously allocated memory block. *`size`*\ New size in bytes. -## Return Value +## Return value **`realloc`** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. -If there is not enough available memory to expand the block to the given size, the original block is left unchanged, and **`NULL`** is returned. +If there isn't enough available memory to expand the block to the given size, the original block is left unchanged, and `NULL` is returned. -If *`size`* is zero, then the block pointed to by *`memblock`* is freed; the return value is **`NULL`**, and *`memblock`* is left pointing at a freed block. +If *`size`* is zero, then the block pointed to by *`memblock`* is freed; the return value is `NULL`, and *`memblock`* is left pointing at a freed block. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. @@ -46,33 +46,33 @@ The return value points to a storage space that is suitably aligned for storage > [!NOTE] > **`realloc`** hasn't been updated to implement C17 behavior because the new behavior isn't compatible with the Windows operating system. -The **`realloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is **`NULL`**, **`realloc`** behaves the same way as **`malloc`** and allocates a new block of *`size`* bytes. If *`memblock`* is not **`NULL`**, it should be a pointer returned by a previous call to **`calloc`**, **`malloc`**, or **`realloc`**. +The **`realloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is `NULL`, **`realloc`** behaves the same way as **`malloc`** and allocates a new block of *`size`* bytes. If *`memblock`* isn't `NULL`, it should be a pointer returned by a previous call to **`calloc`**, **`malloc`**, or **`realloc`**. -The *`size`* argument gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a new memory location, the pointer returned by **`realloc`** is not guaranteed to be the pointer passed through the *`memblock`* argument. **`realloc`** does not zero newly allocated memory in the case of buffer growth. +The *`size`* argument gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a new memory location, the pointer returned by **`realloc`** isn't guaranteed to be the pointer passed through the *`memblock`* argument. **`realloc`** doesn't zero newly allocated memory if there's buffer growth. -**`realloc`** sets **`errno`** to **`ENOMEM`** if the memory allocation fails or if the amount of memory requested exceeds **`_HEAP_MAXREQ`**. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`realloc`** sets `errno` to `ENOMEM` if the memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**`realloc`** calls **`malloc`** in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`realloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call +**`realloc`** calls **`malloc`** in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`realloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call ```C _set_new_mode(1); ``` -early in ones program, or link with NEWMODE.OBJ (see [Link Options](../../c-runtime-library/link-options.md)). +early in ones program, or link with NEWMODE.OBJ (see [Link options](../link-options.md)). -When the application is linked with a debug version of the C run-time libraries, **`realloc`** resolves to [`_realloc_dbg`](realloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`realloc`** resolves to [`_realloc_dbg`](realloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**`realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned is not aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). +**`realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`realloc`**|`` and ``| +| Routine | Required header | +|---|---| +| **`realloc`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -123,7 +123,7 @@ Size of block after realloc of 1000 more longs: 8000 ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`calloc`](calloc.md)\ [`free`](free.md)\ [`malloc`](malloc.md) diff --git a/docs/c-runtime-library/reference/recalloc-dbg.md b/docs/c-runtime-library/reference/recalloc-dbg.md index 471f9b30b9..66707f8e61 100644 --- a/docs/c-runtime-library/reference/recalloc-dbg.md +++ b/docs/c-runtime-library/reference/recalloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["recalloc_dbg", "_recalloc_dbg"] helpviewer_keywords: ["_recalloc_dbg function", "recalloc_dbg function"] ms.assetid: 43c3e9b2-be6d-4508-9b0f-3220c8a47ca3 --- -# _recalloc_dbg +# `_recalloc_dbg` Reallocates an array and initializes its elements to 0 (debug version only). @@ -29,54 +29,54 @@ void *_recalloc_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*number*
+*`number`*\ Requested number of memory blocks. -*size*
+*`size`*\ Requested size of each memory block (bytes). -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -*filename*
-Pointer to name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where allocation operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_recalloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_recalloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [_recalloc](recalloc.md) function. +On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [`_recalloc`](recalloc.md) function. ## Remarks -**_recalloc_dbg** is a debug version of the [_recalloc](recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_recalloc_dbg** is reduced to a call to **_recalloc**. Both **_recalloc** and **_recalloc_dbg** reallocate a memory block in the base heap, but **_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +**`_recalloc_dbg`** is a debug version of the [`_recalloc`](recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_recalloc_dbg`** is reduced to a call to `_recalloc`. Both `_recalloc` and **`_recalloc_dbg`** reallocate a memory block in the base heap, but **`_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_recalloc_dbg** reallocates the specified memory block with slightly more space than the requested size (*number* * *size*) which might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. The user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_recalloc_dbg`** reallocates the specified memory block with slightly more space than the requested size (*`number`* * *`size`*) which might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in both moving the original memory block to a different location in the heap, and changing the size of the memory block. The user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. -**_recalloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails; **EINVAL** is returned if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_recalloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails; `EINVAL` is returned if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_recalloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/recalloc.md b/docs/c-runtime-library/reference/recalloc.md index 1ffc279717..09cd09dea3 100644 --- a/docs/c-runtime-library/reference/recalloc.md +++ b/docs/c-runtime-library/reference/recalloc.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: _recalloc" title: "_recalloc" +description: "Learn more about: _recalloc" ms.date: "4/2/2020" api_name: ["_recalloc", "_o__recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_recalloc", "recalloc"] helpviewer_keywords: ["_recalloc function", "recalloc function"] -ms.assetid: 1db8305a-3f03-418c-8844-bf9149f63046 --- -# _recalloc +# `_recalloc` -A combination of **realloc** and **calloc**. Reallocates an array in memory and initializes its elements to 0. +A combination of `realloc` and `calloc`. Reallocates an array in memory and initializes its elements to 0. ## Syntax ```C void *_recalloc( - void *memblock + void *memblock, size_t num, size_t size ); @@ -26,34 +25,34 @@ void *_recalloc( ### Parameters -*memblock*
+*`memblock`*\ Pointer to previously allocated memory block. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -## Return Value +## Return value -**_recalloc** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. +**`_recalloc`** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. -If there is not enough available memory to expand the block to the given size, the original block is left unchanged, and **NULL** is returned. +If there isn't enough available memory to expand the block to the given size, the original block is left unchanged, and `NULL` is returned. -If the requested size is zero, then the block pointed to by *memblock* is freed; the return value is **NULL**, and *memblock* is left pointing at a freed block. +If the requested size is zero, then the block pointed to by *`memblock`* is freed; the return value is `NULL`, and *`memblock`* is left pointing at a freed block. -The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. +The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. ## Remarks -The **_recalloc** function changes the size of an allocated memory block. The *memblock* argument points to the beginning of the memory block. If *memblock* is **NULL**, **_recalloc** behaves the same way as [calloc](calloc.md) and allocates a new block of *number* * *size* bytes. Each element is initialized to 0. If *memblock* is not **NULL**, it should be a pointer returned by a previous call to **calloc**, [malloc](malloc.md), or [realloc](realloc.md). +The **`_recalloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is `NULL`, **`_recalloc`** behaves the same way as [`calloc`](calloc.md) and allocates a new block of *`number`* * *`size`* bytes. Each element is initialized to 0. If *`memblock`* isn't `NULL`, it should be a pointer returned by a previous call to `calloc`, [`malloc`](malloc.md), or [`realloc`](realloc.md). -Because the new block can be in a new memory location, the pointer returned by **_recalloc** is not guaranteed to be the pointer passed through the *memblock* argument. +Because the new block can be in a new memory location, the pointer returned by **`_recalloc`** isn't guaranteed to be the pointer passed through the *`memblock`* argument. -**_recalloc** sets **errno** to **ENOMEM** if the memory allocation fails or if the amount of memory requested exceeds **_HEAP_MAXREQ**. For information on this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_recalloc`** sets `errno` to `ENOMEM` if the memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**recalloc** calls **realloc** in order to use the C++ [_set_new_mode](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **realloc** is to call the new handler routine as set by [_set_new_handler](set-new-handler.md). By default, **realloc** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **_recalloc** fails to allocate memory, **realloc** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call +**`recalloc`** calls `realloc` in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, `realloc` is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, `realloc` doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`_recalloc`** fails to allocate memory, `realloc` calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call ```C _set_new_mode(1); @@ -61,25 +60,25 @@ _set_new_mode(1); early in the program, or link with NEWMODE.OBJ. -When the application is linked with a debug version of the C run-time libraries, **_recalloc** resolves to [_recalloc_dbg](recalloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_recalloc`** resolves to [`_recalloc_dbg`](recalloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**_recalloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_recalloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_recalloc**|\ and \| +| Routine | Required header | +|---|---| +| **`_recalloc`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_recalloc_dbg](recalloc-dbg.md)
-[_aligned_recalloc](aligned-recalloc.md)
-[_aligned_offset_recalloc](aligned-offset-recalloc.md)
-[free](free.md)
-[Link Options](../../c-runtime-library/link-options.md)
+[Memory allocation](../memory-allocation.md)\ +[`_recalloc_dbg`](recalloc-dbg.md)\ +[`_aligned_recalloc`](aligned-recalloc.md)\ +[`_aligned_offset_recalloc`](aligned-offset-recalloc.md)\ +[`free`](free.md)\ +[Link options](../link-options.md) diff --git a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md index c6c52bdd6d..2d6f85d7ed 100644 --- a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md +++ b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md @@ -3,14 +3,14 @@ title: "remainder, remainderf, remainderl" description: "API reference for remainder, remainderf, and remainderl; which compute the remainder of the quotient of two floating-point values, rounded to the nearest integral value." ms.date: "9/1/2020" api_name: ["remainderl", "remainder", "remainderf", "_o_remainder", "_o_remainderf", "_o_remainderl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remainderf", "remainder", "remainderl"] helpviewer_keywords: ["remainderf", "remainderl", "remainder"] ms.assetid: 5f721fb3-8b78-4597-9bc0-ca9bcd1f1d0e --- -# remainder, remainderf, remainderl +# `remainder`, `remainderf`, `remainderl` Computes the remainder of the quotient of two floating-point values, rounded to the nearest integral value. @@ -28,34 +28,34 @@ long double remainder( long double x, long double y ); /* C++ only */ ### Parameters -*x*\ +*`x`*\ The numerator. -*y*\ +*`y`*\ The denominator. -## Return Value +## Return value -The floating-point remainder of *x* / *y*. If the value of *y* is 0.0, **remainder** returns a quiet NaN. For information about the representation of a quiet NaN by the **printf** family, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +The floating-point remainder of *`x`* / *`y`*. If the value of *`y`* is 0.0, **`remainder`** returns a quiet NaN. For information about the representation of a quiet NaN by the `printf` family, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). ## Remarks -The **remainder** functions calculate the floating-point remainder *r* of *x* / *y* such that *x* = *n* \* *y* + *r*, where *n*is the integer nearest in value to *x* / *y* and *n*is even whenever | *n* - *x* / *y* | = 1/2. When *r* = 0, *r* has the same sign as *x*. +The **`remainder`** functions calculate the floating-point remainder `r` of `x / y` such that `x = n * y + r`, where `n` is the integer nearest in value to `x / y` and `n` is even whenever `|n - x / y| = 1/2`. When `r = 0`, `r` has the same sign as *`x`*. -Because C++ allows overloading, you can call overloads of **remainder** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **remainder** always takes two **`double`** arguments and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`remainder`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`remainder`** always takes two **`double`** arguments and returns a **`double`**. -If you use the \ `remainder()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `remainder()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------|-| -|**remainder**, **remainderf**, **remainderl**|\|\ or \| -|**remainder** macro | \ || +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`remainder`**, **`remainderf`**, **`remainderl`** | \ | \ or \ | +| **`remainder`** macro | \ | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -81,8 +81,8 @@ The remainder of -10.00 / 3.00 is -1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[ldiv, lldiv](./div.md)\ -[imaxdiv](imaxdiv.md)\ -[fmod, fmodf](fmod-fmodf.md)\ -[remquo, remquof, remquol](remquo-remquof-remquol.md) +[Math and floating-point support](../floating-point-support.md)\ +[`ldiv`, `lldiv`](./div.md)\ +[`imaxdiv`](imaxdiv.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`remquo`, `remquof`, `remquol`](remquo-remquof-remquol.md) diff --git a/docs/c-runtime-library/reference/remove-wremove.md b/docs/c-runtime-library/reference/remove-wremove.md index 738698e9fc..d2d7cac153 100644 --- a/docs/c-runtime-library/reference/remove-wremove.md +++ b/docs/c-runtime-library/reference/remove-wremove.md @@ -3,14 +3,13 @@ description: "Learn more about: remove, _wremove" title: "remove, _wremove" ms.date: "4/2/2020" api_name: ["_wremove", "remove", "_o__wremove", "_o_remove"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remove", "_wremove", "_tremove"] helpviewer_keywords: ["tremove function", "_wremove function", "files [C++], deleting", "_tremove function", "files [C++], removing", "wremove function", "remove function"] -ms.assetid: b6345ec3-3289-4645-93a4-28b9e478cc19 --- -# remove, _wremove +# `remove`, `_wremove` Delete a file. @@ -27,39 +26,39 @@ int _wremove( ### Parameters -*path*
+*`path`*\ Path of file to be removed. -## Return Value +## Return value -Each of these functions returns 0 if the file is successfully deleted. Otherwise, it returns -1 and sets **errno** either to **EACCES** to indicate that the path specifies a read-only file, specifies a directory, or the file is open, or to **ENOENT** to indicate that the filename or path was not found. +Each of these functions returns 0 if the file is successfully deleted. Otherwise, it returns -1 and sets `errno` either to `EACCES` to indicate that the path specifies a read-only file, specifies a directory, or the file is open, or to `ENOENT` to indicate that the filename or path wasn't found. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these and other return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **remove** function deletes the file specified by *path.* **_wremove** is a wide-character version of **_remove**; the *path* argument to **_wremove** is a wide-character string. **_wremove** and **_remove** behave identically otherwise. All handles to a file must be closed before it can be deleted. +The **`remove`** function deletes the file specified by *`path`.* **`_wremove`** is a wide-character version of **`_remove`**; the *`path`* argument to **`_wremove`** is a wide-character string. **`_wremove`** and **`_remove`** behave identically otherwise. All handles to a file must be closed before it can be deleted. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tremove**|**remove**|**remove**|**_wremove**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tremove` | **`remove`** | **`remove`** | **`_wremove`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**remove**|\ or \| -|**_wremove**|\ or \| +| Routine | Required header | +|---|---| +| **`remove`** | `` or `` | +| **`_wremove`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -78,13 +77,13 @@ int main( void ) } ``` -### Input: crt_remove.txt +### Input: `crt_remove.txt` ```Input This file will be deleted. ``` -### Sample Output +### Sample output ```Output Deleted 'CRT_REMOVE.TXT' @@ -92,5 +91,5 @@ Deleted 'CRT_REMOVE.TXT' ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_unlink, _wunlink](unlink-wunlink.md)
+[File handling](../file-handling.md)\ +[`_unlink`, `_wunlink`](unlink-wunlink.md) diff --git a/docs/c-runtime-library/reference/remquo-remquof-remquol.md b/docs/c-runtime-library/reference/remquo-remquof-remquol.md index dbf6489667..f6236f9679 100644 --- a/docs/c-runtime-library/reference/remquo-remquof-remquol.md +++ b/docs/c-runtime-library/reference/remquo-remquof-remquol.md @@ -1,18 +1,17 @@ --- title: "remquo, remquof, remquol" -description: "API reference for remquo, remquof, and remquol; which compute the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a location that's specified in a parameter." +description: "API reference for remquo, remquof, and remquol, which compute the remainder of two integer values, and store the sign and approximate magnitude of the quotient." ms.date: "9/1/2020" api_name: ["remquof", "remquo", "remquol", "_o_remquo", "_o_remquof", "_o_remquol"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remquof", "remquol", "remquo"] helpviewer_keywords: ["remquol function", "remquof function", "remquo function"] -ms.assetid: a1d3cb8b-8027-4cd3-8deb-04eb17f299fc --- -# remquo, remquof, remquol +# `remquo`, `remquof`, `remquol` -Computes the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a location that's specified in a parameter. +Computes the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a parameter. ## Syntax @@ -28,37 +27,37 @@ long double remquo( long double numer, long double denom, int* quo ); /* C++ onl ### Parameters -*numer*\ +*`numer`*\ The numerator. -*denom*\ +*`denom`*\ The denominator. -*quo*\ +*`quo`*\ A pointer to an integer to store a value that has the sign and approximate magnitude of the quotient. -## Return Value +## Return value -**remquo** returns the floating-point remainder of *x* / *y*. If the value of *y* is 0.0, **remquo** returns a quiet NaN. For information about the representation of a quiet NaN by the **printf** family, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +**`remquo`** returns the floating-point remainder of *`x`* / *`y`*. If the value of *`y`* is 0.0, **`remquo`** returns a quiet NaN. For information about the representation of a quiet NaN by the `printf` family, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). ## Remarks -The **remquo** function calculates the floating-point remainder *f* of *x* / *y* such that *x* = *i* \* *y* + *f*, where *i* is an integer, *f* has the same sign as *x*, and the absolute value of *f* is less than the absolute value of *y*. +The **`remquo`** function calculates the floating-point remainder `f` of *`x`* / *`y`* such that *`x`* = `n` \* *`y`* + *`f`*, where `n` is an integer, `f` has the same sign as *`x`*, and the absolute value of `f` is less than the absolute value of *`y`*. -C++ allows overloading, so you can call overloads of **remquo** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **remquo** always takes two **`double`** arguments and returns a **`double`**. +C++ allows overloading, so you can call overloads of **`remquo`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`remquo`** always takes two **`double`** arguments and returns a **`double`**. -If you use the \ `remquo()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `remquo()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------|-| -|**remquo**, **remquof**, **remquol**|\|\ or \| -|**remquo** macro | \ || +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`remquo`**, **`remquof`**, **`remquol`** | \ | \ or \ | +| **`remquo`** macro | \ | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,8 +86,8 @@ Approximate signed quotient is -3 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ldiv, lldiv](./div.md)
-[imaxdiv](imaxdiv.md)
-[fmod, fmodf](fmod-fmodf.md)
-[remainder, remainderf, remainderl](remainder-remainderf-remainderl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ldiv`, `lldiv`](./div.md)\ +[`imaxdiv`](imaxdiv.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`remainder`, `remainderf`, `remainderl`](remainder-remainderf-remainderl.md) diff --git a/docs/c-runtime-library/reference/rename-wrename.md b/docs/c-runtime-library/reference/rename-wrename.md index b5b29e4e1c..bfab5461de 100644 --- a/docs/c-runtime-library/reference/rename-wrename.md +++ b/docs/c-runtime-library/reference/rename-wrename.md @@ -3,7 +3,7 @@ description: "Learn more about: rename, _wrename" title: "rename, _wrename" ms.date: "4/2/2020" api_name: ["rename", "_wrename", "_o__wrename", "_o_rename"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wrename", "_trename", "Rename"] @@ -29,50 +29,50 @@ int _wrename( ### Parameters -*`oldname`*
+*`oldname`*\ Pointer to old name. -*`newname`*
+*`newname`*\ Pointer to new name. -## Return Value +## Return value -Each of these functions returns 0 if it is successful. On an error, the function returns a nonzero value and sets **`errno`** to one of the following values: +Each of these functions returns 0 if it's successful. On an error, the function returns a nonzero value and sets `errno` to one of the following values: -|errno value|Condition| -|-|-| -| **`EACCES`** | File or directory specified by *`newname`* already exists or could not be created (invalid path); or *`oldname`* is a directory and *`newname`* specifies a different path. | -| **`ENOENT`** | File or path specified by *`oldname`* not found. | -| **`EINVAL`** | Name contains invalid characters. | +| `errno` value | Condition | +|---|---| +| `EACCES` | File or directory specified by *`newname`* already exists or couldn't be created (invalid path); or *`oldname`* is a directory and *`newname`* specifies a different path. | +| `ENOENT` | File or path specified by *`oldname`* not found. | +| `EINVAL` | Name contains invalid characters. | -For other possible return values, see [`_doserrno`, `_errno`, `syserrlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For other possible return values, see [`_doserrno`, `_errno`, `syserrlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`rename`** function renames the file or directory specified by *`oldname`* to the name given by *`newname`*. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use **`rename`** to move a file from one directory or device to another by giving a different path in the *`newname`* argument. However, you cannot use **`rename`** to move a directory. Directories can be renamed, but not moved. +The **`rename`** function renames the file or directory specified by *`oldname`* to the name given by *`newname`*. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use **`rename`** to move a file from one directory or device to another by giving a different path in the *`newname`* argument. However, you can't use **`rename`** to move a directory. Directories can be renamed, but not moved. **`_wrename`** is a wide-character version of **`_rename`**; the arguments to **`_wrename`** are wide-character strings. **`_wrename`** and **`_rename`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_trename`**|**`rename`**|**`rename`**|**`_wrename`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_trename` | **`rename`** | **`rename`** | **`_wrename`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`rename`**|`` or ``| -|**`_wrename`**|`` or ``| +| Routine | Required header | +|---|---| +| **`rename`** | `` or `` | +| **`_wrename`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -108,4 +108,4 @@ File 'CRT_RENAMER.OBJ' renamed to 'CRT_RENAMER.JBO' ## See also -[File Handling](../../c-runtime-library/file-handling.md)
+[File handling](../file-handling.md) diff --git a/docs/c-runtime-library/reference/resetstkoflw.md b/docs/c-runtime-library/reference/resetstkoflw.md index f79dceafce..89923dcc00 100644 --- a/docs/c-runtime-library/reference/resetstkoflw.md +++ b/docs/c-runtime-library/reference/resetstkoflw.md @@ -3,7 +3,7 @@ description: "Learn more about: _resetstkoflw" title: "_resetstkoflw" ms.date: "1/14/2021" api_name: ["_resetstkoflw", "_o__resetstkoflw"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["resetstkoflw", "_resetstkoflw"] @@ -23,7 +23,7 @@ Recovers from stack overflow. int _resetstkoflw( void ); ``` -## Return Value +## Return value Nonzero if the function succeeds, zero if it fails. @@ -31,27 +31,27 @@ Nonzero if the function succeeds, zero if it fails. The **`_resetstkoflw`** function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the **`_resetstkoflw`** function isn't called, there are no guard pages after the previous exception. The next time that there's a stack overflow, there are no exceptions at all and the process terminates without warning. -If a thread in an application causes an **`EXCEPTION_STACK_OVERFLOW`** exception, the thread has left its stack in a damaged state. This is in contrast to other exceptions such as **`EXCEPTION_ACCESS_VIOLATION`** or **`EXCEPTION_INT_DIVIDE_BY_ZERO`**, where the stack isn't damaged. The stack is set to an arbitrarily small value when the program is first loaded. The stack then grows on demand to meet the needs of the thread. This is implemented by placing a page with PAGE_GUARD access at the end of the current stack. For more information, see [Creating Guard Pages](/windows/win32/Memory/creating-guard-pages). +If a thread in an application causes an `EXCEPTION_STACK_OVERFLOW` exception, the thread has left its stack in a damaged state. This exception is different from other exceptions such as `EXCEPTION_ACCESS_VIOLATION` or `EXCEPTION_INT_DIVIDE_BY_ZERO`, where the stack isn't damaged. The stack is set to an arbitrarily small value when the program is first loaded. The stack then grows on demand to meet the needs of the thread. On-demand growth is implemented by placing a page with `PAGE_GUARD` access at the end of the current stack. For more information, see [Creating guard pages](/windows/win32/Memory/creating-guard-pages). When the code causes the stack pointer to point to an address on this page, an exception occurs and the system does the following three things: -- Removes the PAGE_GUARD protection on the guard page so that the thread can read and write data to the memory. +- Removes the `PAGE_GUARD` protection on the guard page so that the thread can read and write data to the memory. - Allocates a new guard page that is located one page below the last one. - Reruns the instruction that raised the exception. -In this way, the system can increase the size of the stack for the thread automatically. Each thread in a process has a maximum stack size. The stack size is set at compile time by the [`/STACK` (Stack Allocations)](../../build/reference/stack-stack-allocations.md), or by the [`STACKSIZE`](../../build/reference/stacksize.md) statement in the `.def` file for the project. +In this way, the system can increase the size of the stack for the thread automatically. Each thread in a process has a maximum stack size. The stack size is set at compile time by the [`/STACK` (Stack Allocations)](../../build/reference/stack-stack-allocations.md) option, or by the [`STACKSIZE`](../../build/reference/stacksize.md) statement in the `.def` file for the project. When this maximum stack size is exceeded, the system does the following three things: - Removes the PAGE_GUARD protection on the guard page, as previously described. -- Tries to allocate a new guard page below the last one. However, this fails because the maximum stack size has been exceeded. +- Tries to allocate a new guard page below the last one. However, the allocation fails because the maximum stack size has been exceeded. - Raises an exception so that the thread can handle it in the exception block. -At that point, the stack no longer has a guard page. The next time that the program grows the stack all the way to the end, where there should be a guard page, the program writes beyond the end of the stack and causes an access violation. +At that point, the stack no longer has a guard page. The next time the program grows the stack to where it writes beyond the end of the stack, it causes an access violation. Call **`_resetstkoflw`** to restore the guard page whenever recovery is done after a stack overflow exception. This function can be called from inside the main body of an **`__except`** block or outside an **`__except`** block. However, there are some restrictions on when it should be used. **`_resetstkoflw`** shouldn't be called from: @@ -69,23 +69,23 @@ At these points, the stack isn't yet sufficiently unwound. Stack overflow exceptions are generated as structured exceptions, not C++ exceptions, so **`_resetstkoflw`** isn't useful in an ordinary **`catch`** block because it won't catch a stack overflow exception. However, if [`_set_se_translator`](set-se-translator.md) is used to implement a structured exception translator that throws C++ exceptions (as in the second example), a stack overflow exception results in a C++ exception that can be handled by a C++ catch block. -It isn't safe to call **`_resetstkoflw`** in a C++ catch block that is reached from an exception thrown by the structured exception translator function. In this case, the stack space isn't freed and the stack pointer isn't reset until outside the catch block, even though destructors have been called for any destructible objects before the catch block. This function shouldn't be called until the stack space is freed and the stack pointer has been reset. Therefore, it should be called only after exiting the catch block. As little stack space as possible should be used in the catch block because a stack overflow that occurs in the catch block that is itself attempting to recover from a previous stack overflow isn't recoverable and can cause the program to stop responding as the overflow in the catch block triggers an exception that itself is handled by the same catch block. +It isn't safe to call **`_resetstkoflw`** in a C++ catch block that is reached from an exception thrown by the structured exception translator function. In this case, the stack space isn't freed and the stack pointer isn't reset until outside the catch block, even though destructors have been called for any destructible objects before the catch block. This function shouldn't be called until the stack space is freed and the stack pointer has been reset. Therefore, it should be called only after exiting the catch block. As little stack space as possible should be used in the catch block. A stack overflow that occurs in the catch block that is itself attempting to recover from a previous stack overflow isn't recoverable. It can cause the program to stop responding, as the overflow in the catch block triggers an exception that itself is handled by the same catch block. -There are situations where **`_resetstkoflw`** can fail even if used in a correct location, such as within an **`__except`** block. If, even after unwinding the stack, there's still not enough stack space left to execute **`_resetstkoflw`** without writing into the last page of the stack, **`_resetstkoflw`** fails to reset the last page of the stack as the guard page and returns 0, indicating failure. Safe usage of this function should include checking the return value instead of assuming that the stack is safe to use. +There are situations where **`_resetstkoflw`** can fail even if used in a correct location, such as within an **`__except`** block. There may not be enough stack space left to execute **`_resetstkoflw`** without writing into the last page of the stack, even after unwinding the stack. Then, **`_resetstkoflw`** fails to reset the last page of the stack as the guard page, and returns 0, indicating failure. Safe usage of this function should include checking the return value instead of assuming that the stack is safe to use. -Structured exception handling won't catch a **`STATUS_STACK_OVERFLOW`** exception when the application is compiled with **`/clr`** (see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md)). +Structured exception handling won't catch a `STATUS_STACK_OVERFLOW` exception when the application is compiled with **`/clr`** (see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md)). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_resetstkoflw`**|\| +| Routine | Required header | +|---|---| +| **`_resetstkoflw`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [CRT Library Features](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [CRT library features](../crt-library-features.md). ## Example @@ -285,4 +285,4 @@ Recovered from stack overflow and allocated 100,000 bytes using _alloca. ## See also -[`_alloca`](alloca.md)
+[`_alloca`](alloca.md) diff --git a/docs/c-runtime-library/reference/rewind.md b/docs/c-runtime-library/reference/rewind.md index 2ff050d3aa..5ece09a4f8 100644 --- a/docs/c-runtime-library/reference/rewind.md +++ b/docs/c-runtime-library/reference/rewind.md @@ -3,14 +3,14 @@ description: "Learn more about: rewind" title: "rewind" ms.date: "4/2/2020" api_name: ["rewind", "_o_rewind"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["rewind"] helpviewer_keywords: ["rewind function", "repositioning file pointers", "file pointers [C++], repositioning", "file pointers [C++]"] ms.assetid: 1a460ce1-28d8-4b5e-83a6-633dca29c28a --- -# rewind +# `rewind` Repositions the file pointer to the beginning of a file. @@ -24,36 +24,36 @@ void rewind( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. ## Remarks -The **rewind** function repositions the file pointer associated with *stream* to the beginning of the file. A call to **rewind** is similar to +The **`rewind`** function repositions the file pointer associated with *`stream`* to the beginning of the file. A call to **`rewind`** is similar to -**(void) fseek(** _stream_**, 0L, SEEK_SET );** +`(void) fseek(stream, 0L, SEEK_SET );` -However, unlike [fseek](fseek-fseeki64.md), **rewind** clears the error indicators for the stream as well as the end-of-file indicator. Also, unlike [fseek](fseek-fseeki64.md), **rewind** does not return a value to indicate whether the pointer was successfully moved. +However, unlike [`fseek`](fseek-fseeki64.md), **`rewind`** clears both the error indicators for the stream and the end-of-file indicator. Also, unlike [`fseek`](fseek-fseeki64.md), **`rewind`** doesn't return a value to indicate whether the pointer was successfully moved. -To clear the keyboard buffer, use **rewind** with the stream **stdin**, which is associated with the keyboard by default. +To clear the keyboard buffer, use **`rewind`** with the stream `stdin`, which is associated with the keyboard by default. -If stream is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns and **errno** is set to **EINVAL**. +If stream is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**rewind**|\| +| Routine | Required header | +|---|---| +| **`rewind`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -97,4 +97,4 @@ The values read are: 1 and -37 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
+[Stream I/O](../stream-i-o.md) diff --git a/docs/c-runtime-library/reference/rint-rintf-rintl.md b/docs/c-runtime-library/reference/rint-rintf-rintl.md index d5a9617c5b..9b129700c9 100644 --- a/docs/c-runtime-library/reference/rint-rintf-rintl.md +++ b/docs/c-runtime-library/reference/rint-rintf-rintl.md @@ -3,14 +3,14 @@ title: "rint, rintf, rintl" description: "API reference for rint, rintf, and rintl; which round a floating-point value to the nearest integer in floating-point format." ms.date: "9/1/2020" api_name: ["rintf", "rintl", "rint", "_o_rint", "_o_rintf", "_o_rintl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["rintf", "rintl", "rint"] helpviewer_keywords: ["rintf function", "rint function", "rintl function"] ms.assetid: 312ae3e6-278c-459a-9393-11b8f87d9184 --- -# rint, rintf, rintl +# `rint`, `rintf`, `rintl` Rounds a floating-point value to the nearest integer in floating-point format. @@ -28,34 +28,34 @@ long double rint( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ The floating-point value to round. -## Return Value +## Return value -The **rint** functions return a floating-point value that represents the nearest integer to *x*. Halfway values are rounded according to the current setting of the floating-point rounding mode, the same as the **nearbyint** functions. Unlike the **nearbyint** functions, the **rint** functions may raise the **FE_INEXACT** floating-point exception if the result differs in value from the argument. There's no error return. +The **`rint`** functions return a floating-point value that represents the nearest integer to *`x`*. Halfway values are rounded according to the current setting of the floating-point rounding mode, the same as the `nearbyint` functions. Unlike the `nearbyint` functions, the **`rint`** functions may raise the `FE_INEXACT` floating-point exception if the result differs in value from the argument. There's no error return. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|none| -|Denormals|EXCEPTION_FLT_UNDERFLOW|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | none | +| Denormals | `EXCEPTION_FLT_UNDERFLOW` | none | ## Remarks -Because C++ allows overloading, you can call overloads of **rint** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **rint** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`rint`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`rint`** always takes and returns a **`double`**. -If you use the \ `rint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `rint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**rint**, **rintf**, **rintl**|\|\| -|**rint** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`rint`**, **`rintf`**, **`rintl`** | \ | \ | +| **`rint`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,11 +95,11 @@ rintl(-2.500000) is -3 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[fmod, fmodf](fmod-fmodf.md)
-[lrint, lrintf, lrintl, llrint, llrintf, llrintl](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)
-[lround, lroundf, lroundl, llround, llroundf, llroundl](lround-lroundf-lroundl-llround-llroundf-llroundl.md)
-[nearbyint, nearbyintf, nearbyintl](nearbyint-nearbyintf-nearbyintl1.md)
-[rint](rint-rintf-rintl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl`](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)\ +[`lround`, `lroundf`, `lroundl`, `llround`, `llroundf`, `llroundl`](lround-lroundf-lroundl-llround-llroundf-llroundl.md)\ +[`nearbyint`, `nearbyintf`, `nearbyintl`](nearbyint-nearbyintf-nearbyintl1.md)\ +[`rint`](rint-rintf-rintl.md) diff --git a/docs/c-runtime-library/reference/rmdir-wrmdir.md b/docs/c-runtime-library/reference/rmdir-wrmdir.md index 1b03190bfb..ea688d7995 100644 --- a/docs/c-runtime-library/reference/rmdir-wrmdir.md +++ b/docs/c-runtime-library/reference/rmdir-wrmdir.md @@ -3,14 +3,14 @@ description: "Learn more about: _rmdir, _wrmdir" title: "_rmdir, _wrmdir" ms.date: "4/2/2020" api_name: ["_wrmdir", "_rmdir", "_o__rmdir", "_o__wrmdir"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["trmdir", "_trmdir", "wrmdir", "_rmdir", "_wrmdir"] helpviewer_keywords: ["_rmdir function", "directories [C++], deleting", "rmdir function", "directories [C++], removing", "trmdir function", "_trmdir function", "_wrmdir function", "wrmdir function"] ms.assetid: 652c2a5a-b0ac-4493-864e-1edf484333c5 --- -# _rmdir, _wrmdir +# `_rmdir`, `_wrmdir` Deletes a directory. @@ -27,54 +27,54 @@ int _wrmdir( ### Parameters -*dirname*
+*`dirname`*\ Path of the directory to be removed. -## Return Value +## Return value -Each of these functions returns 0 if the directory is successfully deleted. A return value of -1 indicates an error and **errno** is set to one of the following values: +Each of these functions returns 0 if the directory is successfully deleted. A return value of -1 indicates an error and `errno` is set to one of the following values: -|errno value|Condition| -|-|-| -| **ENOTEMPTY** | Given path is not a directory, the directory is not empty, or the directory is either the current working directory or the root directory. | -| **ENOENT** | Path is invalid. | -| **EACCES** | A program has an open handle to the directory. | +| `errno` value | Condition | +|---|---| +| `ENOTEMPTY` | Given path isn't a directory, the directory isn't empty, or the directory is either the current working directory or the root directory. | +| `ENOENT` | Path is invalid. | +| `EACCES` | A program has an open handle to the directory. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_rmdir** function deletes the directory specified by *dirname*. The directory must be empty, and it must not be the current working directory or the root directory. +The **`_rmdir`** function deletes the directory specified by *`dirname`*. The directory must be empty, and it must not be the current working directory or the root directory. -**_wrmdir** is a wide-character version of **_rmdir**; the *dirname* argument to **_wrmdir** is a wide-character string. **_wrmdir** and **_rmdir** behave identically otherwise. +**`_wrmdir`** is a wide-character version of **`_rmdir`**; the *`dirname`* argument to **`_wrmdir`** is a wide-character string. **`_wrmdir`** and **`_rmdir`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_trmdir**|**_rmdir**|**_rmdir**|**_wrmdir**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_trmdir` | **`_rmdir`** | **`_rmdir`** | **`_wrmdir`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rmdir**|\| -|**_wrmdir**|\ or \| +| Routine | Required header | +|---|---| +| **`_rmdir`** | \ | +| **`_wrmdir`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [_mkdir](mkdir-wmkdir.md). +See the example for [`_mkdir`](mkdir-wmkdir.md). ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdir, _wchdir](chdir-wchdir.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md) diff --git a/docs/c-runtime-library/reference/rmdir.md b/docs/c-runtime-library/reference/rmdir.md index 0d5d7ec157..856ee7479b 100644 --- a/docs/c-runtime-library/reference/rmdir.md +++ b/docs/c-runtime-library/reference/rmdir.md @@ -10,8 +10,8 @@ f1_keywords: ["rmdir"] helpviewer_keywords: ["rmdir function"] ms.assetid: 03a0aff4-f66c-42a9-bee9-84c46f994952 --- -# rmdir +# `rmdir` -The Microsoft-implemented POSIX function name `rmdir` is a deprecated alias for the [_rmdir](rmdir-wrmdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `rmdir` is a deprecated alias for the [`_rmdir`](rmdir-wrmdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_rmdir](rmdir-wrmdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_rmdir`](rmdir-wrmdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/rmtmp.md b/docs/c-runtime-library/reference/rmtmp.md index cf26adf0e9..7fac6abd1a 100644 --- a/docs/c-runtime-library/reference/rmtmp.md +++ b/docs/c-runtime-library/reference/rmtmp.md @@ -1,55 +1,53 @@ --- -description: "Learn more about: _rmtmp" title: "_rmtmp" +description: "Learn more about: _rmtmp" ms.date: "4/2/2020" api_name: ["_rmtmp", "_o__rmtmp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_rmtmp"] helpviewer_keywords: ["removing temporary files", "_rmtmp function", "files [C++], temporary", "rmtmp function", "files [C++], removing", "temporary files [C++], removing"] -ms.assetid: 7419501e-2587-4f2a-b469-0dca07f84736 --- -# _rmtmp +# `_rmtmp` Removes temporary files. ## Syntax ```C - int _rmtmp( void ); ``` -## Return Value +## Return value -**_rmtmp** returns the number of temporary files closed and deleted. +**`_rmtmp`** returns the number of temporary files closed and deleted. ## Remarks -The **_rmtmp** function cleans up all temporary files in the current directory. The function removes only those files created by **tmpfile**; use it only in the same directory in which the temporary files were created. +The **`_rmtmp`** function cleans up all temporary files in the current directory. The function removes only those files created by `tmpfile`; use it only in the same directory in which the temporary files were created. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rmtmp**|\| +| Routine | Required header | +|---|---| +| **`_rmtmp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [tmpfile](tmpfile.md). +See the example for [`tmpfile`](tmpfile.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_flushall](flushall.md)
-[tmpfile](tmpfile.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_flushall`](flushall.md)\ +[`tmpfile`](tmpfile.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md b/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md index f78d40eab9..c095e8cada 100644 --- a/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md +++ b/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md @@ -8,16 +8,14 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_rotr64", "rotl64", "_rotl64", "rotr64", "rotr", "_rotr", "_rotl", "rotl"] helpviewer_keywords: ["rotl64 function", "_rotl function", "rotr function", "rotr64 function", "_rotr function", "rotl function", "_rotl64 function", "rotating bits", "_rotr64 function", "bits, rotating"] -ms.assetid: cfce439b-366f-4584-8ab1-d527b13fcfc6 --- -# _rotl, _rotl64, _rotr, _rotr64 +# `_rotl`, `_rotl64`, `_rotr`, `_rotr64` -Rotates bits to the left (**_rotl**) or right (**_rotr**). +Rotates bits to the left (**`_rotl`**) or right (**`_rotr`**). ## Syntax ```C - unsigned int _rotl( unsigned int value, int shift @@ -38,32 +36,32 @@ unsigned __int64 _rotr64( ### Parameters -*value*
+*`value`*\ Value to be rotated. -*shift*
+*`shift`*\ Number of bits to shift. -## Return Value +## Return value The rotated value. There's no error return. ## Remarks -The **_rotl** and **_rotr** functions rotate the unsigned *value* by *shift* bits. **_rotl** rotates the value left. **_rotr** rotates the value right. Both functions wrap bits rotated off one end of *value* to the other end. +The **`_rotl`** and **`_rotr`** functions rotate the unsigned *`value`* by *`shift`* bits. **`_rotl`** rotates the value left. **`_rotr`** rotates the value right. Both functions wrap bits rotated off one end of *`value`* to the other end. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rotl**, **_rotl64**|\| -|**_rotr**, **_rotr64**|\| +| Routine | Required header | +|---|---| +| **`_rotl`**, **`_rotl64`** | \ | +| **`_rotr`**, **`_rotr64`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -103,5 +101,5 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_lrotl, _lrotr](lrotl-lrotr.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_lrotl`, `_lrotr`](lrotl-lrotr.md) diff --git a/docs/c-runtime-library/reference/round-roundf-roundl.md b/docs/c-runtime-library/reference/round-roundf-roundl.md index 4237a2ac2a..a5a0f37b5f 100644 --- a/docs/c-runtime-library/reference/round-roundf-roundl.md +++ b/docs/c-runtime-library/reference/round-roundf-roundl.md @@ -3,7 +3,7 @@ title: "round, roundf, roundl" description: "API reference for round, roundf, and roundl; which round a floating-point value to the nearest integer value." ms.date: "09/25/2020" api_name: ["round", "roundl", "roundf", "_o_round", "_o_roundf", "_o_roundl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["roundf", "roundl", "round"] @@ -40,30 +40,30 @@ long double roundl( *`x`*\ The floating-point value to round. -## Return Value +## Return value The **`round`** functions return a floating-point value that represents the nearest integer to *`x`*. Halfway values are rounded away from zero, regardless of the setting of the floating-point rounding mode. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`round`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`round`** always takes and returns a **`double`**. -If you use the `` `round()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `round` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`round`**, **`roundf`**, **`roundl`**|``| -|**`round`** macro | `` | +| Routine | Required header | +|---|---| +| **`round`**, **`roundf`**, **`roundl`** | `` | +| **`round`** macro | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -117,7 +117,7 @@ roundl(-2.499999900000000163657887242152355611324310302734375) is -2 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ [`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ [`fmod`, `fmodf`](fmod-fmodf.md)\ diff --git a/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md b/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md index 6c41dbef60..e143c539a1 100644 --- a/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md +++ b/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md @@ -9,19 +9,17 @@ f1_keywords: ["RPT3", "RPTF4", "_RPT4", "RPT1", "_RPTF0", "RPTF3", "_RPTF4", "RP helpviewer_keywords: ["debugging [CRT], using macros", "_RPTW3 macro", "_RPT0 macro", "RPTW4 macro", "_RPTF3 macro", "_RPTW4 macro", "RPTF4 macro", "RPTFW2 macro", "RPTW macros", "RPT1 macro", "_RPTF macros", "RPTFW3 macro", "_RPTW0 macro", "_RPTF0 macro", "macros, debugging with", "_RPTW2 macro", "RPTF3 macro", "RPT3 macro", "RPT0 macro", "_RPT macros", "RPTW3 macro", "_RPTFW macros", "debug reporting macros", "RPTF macros", "RPT macros", "_RPTW macros", "RPTF2 macro", "_RPTF1 macro", "_RPT1 macro", "_RPT4 macro", "_RPTFW2 macro", "_RPTFW1 macro", "RPTF0 macro", "_RPT2 macro", "RPTFW macros", "_RPTW1 macro", "_RPTFW0 macro", "RPT4 macro", "_RPT3 macro", "_RPTFW3 macro", "_RPTF4 macro", "_RPTFW4 macro", "_RPTF2 macro", "RPTW0 macro", "RPTFW4 macro", "RPTFW0 macro", "RPTW2 macro", "RPTF1 macro", "RPT2 macro", "RPTFW1 macro", "RPTW1 macro"] ms.assetid: a5bf8b30-57f7-4971-8030-e773b7a1ae13 --- -# _RPT, _RPTF, _RPTW, _RPTFW Macros +# `_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` Macros -Tracks an application's progress by generating a debug report (debug version only). Note that *n* specifies the number of arguments in *args* and can be 0, 1, 2, 3, 4, or 5. +Tracks an application's progress by generating a debug report (debug version only). The `n` suffix specifies the number of arguments in *`args`*, and can be 0, 1, 2, 3, 4, or 5. ## Syntax ```C -_RPT - n - ( +_RPTn( reportType, format, -...[args] + ...[args] ); _RPTFn( reportType, @@ -42,60 +40,60 @@ _RPTFWn( ### Parameters -*reportType*
-Report type: **_CRT_WARN**, **_CRT_ERROR**, or **_CRT_ASSERT**. +*`reportType`*\ +Report type: `_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`. -*format*
+*`format`*\ Format-control string used to create the user message. -*args*
-Substitution arguments used by *format*. +*`args`*\ +Substitution arguments used by *`format`*. ## Remarks -All these macros take the *reportType* and *format* parameters. In addition, they might also take up to four additional arguments, signified by the number appended to the macro name. For example, **_RPT0** and **_RPTF0** take no additional arguments, **_RPT1** and **_RPTF1** take *arg1*, **_RPT2** and **_RPTF2** take *arg1* and **arg2**, and so on. +All these macros take the *`reportType`* and *`format`* parameters. In addition, they might also take up to four more arguments, signified by the number appended to the macro name. For example, **`_RPT0`** and **`_RPTF0`** take no more arguments, **`_RPT1`** and **`_RPTF1`** take *`arg1`*, **`_RPT2`** and **`_RPTF2`** take *`arg1`* and *`arg2`*, and so on. -The **_RPT** and **_RPTF** macros are similar to the [printf](printf-printf-l-wprintf-wprintf-l.md) function, because they can be used to track an application's progress during the debugging process. However, these macros are more flexible than **printf** because they do not need to be enclosed in **#ifdef** statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [_DEBUG](../../c-runtime-library/debug.md) macro; the **_RPT** and **_RPTF** macros are only available when the **_DEBUG** flag is defined. When **_DEBUG** is not defined, calls to these macros are removed during preprocessing. +The `_RPT` and `_RPTF` macros are similar to the [`printf`](printf-printf-l-wprintf-wprintf-l.md) function, because they can be used to track an application's progress during the debugging process. However, these macros are more flexible than `printf` because they don't need to be enclosed in **#ifdef** statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [`_DEBUG`](../debug.md) macro; the `_RPT` and `_RPTF` macros are only available when the `_DEBUG` flag is defined. When `_DEBUG` isn't defined, calls to these macros are removed during preprocessing. -The **_RPTW** and **_RPTFW** macros are wide-character versions of these macros. They are like **wprintf** and take wide-character strings as arguments. +The `_RPTW` and `_RPTFW` macros are wide-character versions of these macros. They are like `wprintf` and take wide-character strings as arguments. -The **_RPT** macros call the [_CrtDbgReport](crtdbgreport-crtdbgreportw.md) function to generate a debug report with a user message. The **_RPTW** macros call the **_CrtDbgReportW** function to generate the same report with wide characters. The **_RPTF** and **_RPTFW** macros create a debug report with the source file and line number where the report macro was called, in addition to the user message. The user message is created by substituting the **arg**[*n*] arguments into the *format* string, using the same rules defined by the [printf](printf-printf-l-wprintf-wprintf-l.md) function. +The `_RPT` macros call the [`_CrtDbgReport`](crtdbgreport-crtdbgreportw.md) function to generate a debug report with a user message. The `_RPTW` macros call the `_CrtDbgReportW` function to generate the same report with wide characters. The `_RPTF` and `_RPTFW` macros create a debug report with the source file and line number where the report macro was called, in addition to the user message. The user message is created by substituting the *`arg[n]`* arguments into the *`format`* string, using the same rules defined by the [`printf`](printf-printf-l-wprintf-wprintf-l.md) function. -**_CrtDbgReport** or **_CrtDbgReportW** generates the debug report and determines its destinations based on the current report modes and file defined for *reportType*. The [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md) functions are used to define the destinations for each report type. +`_CrtDbgReport` or `_CrtDbgReportW` generates the debug report and determines its destinations based on the current report modes and file defined for *`reportType`*. The [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions are used to define the destinations for each report type. -If an **_RPT** macro is called and neither **_CrtSetReportMode** nor **_CrtSetReportFile** has been called, messages are displayed as follows. +If an `_RPT` macro is called, and `_CrtSetReportMode` and `_CrtSetReportFile` haven't been called, messages are displayed as follows: -|Report type|Output destination| -|-----------------|------------------------| -|**_CRT_WARN**|Warning text is not displayed.| -|**_CRT_ERROR**|A pop-up window. Same as if `_CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_WNDW);` had been specified.| -|**_CRT_ASSERT**|Same as **_CRT_ERROR**.| +| Report type | Output destination | +|---|---| +| `_CRT_WARN` | Warning text isn't displayed. | +| `_CRT_ERROR` | A pop-up window. Same as if `_CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_WNDW);` had been specified. | +| `_CRT_ASSERT` | Same as `_CRT_ERROR`. | -When the destination is a debug message window and the user chooses the **Retry** button, **_CrtDbgReport** or **_CrtDbgReportW** returns 1, causing these macros to start the debugger, provided that just-in-time (JIT) debugging is enabled. For more information about using these macros as a debugging error handling mechanism, see [Using Macros for Verification and Reporting](/visualstudio/debugger/macros-for-reporting). +When the destination is a debug message window and the user chooses the **Retry** button, `_CrtDbgReport` or `_CrtDbgReportW` returns 1. This return value causes these macros to start the debugger, if just-in-time (JIT) debugging is enabled. For more information about using these macros as a debugging error handling mechanism, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). -Two other macros exist that generate a debug report. The [_ASSERT](assert-asserte-assert-expr-macros.md) macro generates a report, but only when its expression argument evaluates to FALSE. [_ASSERTE](assert-asserte-assert-expr-macros.md) is exactly like **_ASSERT**, but includes the failed expression in the generated report. +Two other macros exist that generate a debug report. The [`_ASSERT`](assert-asserte-assert-expr-macros.md) macro generates a report, but only when its expression argument evaluates to `FALSE`. [`_ASSERTE`](assert-asserte-assert-expr-macros.md) is exactly like `_ASSERT`, but includes the failed expression in the generated report. ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**_RPT** macros|\| -|**_RPTF** macros|\| -|**_RPTW** macros|\| -|**_RPTFW** macros|\| +| Macro | Required header | +|---|---| +| `_RPT` macros | \ | +| `_RPTF` macros | \ | +| `_RPTW` macros | \ | +| `_RPTFW` macros | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. -Although these are macros and are obtained by including Crtdbg.h, the application must link with one of the debug libraries because these macros call other run-time functions. +Although these macros are available when you include `crtdbg.h`, to run, the application must link with one of the debug libraries, because these macros call other run-time functions. ## Example -See the example in the [_ASSERT](assert-asserte-assert-expr-macros.md) topic. +See the example in the [`_ASSERT`](assert-asserte-assert-expr-macros.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/rtc-geterrdesc.md b/docs/c-runtime-library/reference/rtc-geterrdesc.md index 978b40ea92..74eb5e7194 100644 --- a/docs/c-runtime-library/reference/rtc-geterrdesc.md +++ b/docs/c-runtime-library/reference/rtc-geterrdesc.md @@ -10,7 +10,7 @@ f1_keywords: ["RTC_GetErrDesc", "_RTC_GetErrDesc"] helpviewer_keywords: ["run-time errors", "_RTC_GetErrDesc function", "RTC_GetErrDesc function"] ms.assetid: 7994ec2b-5488-4fd4-806d-a166c9a9f927 --- -# _RTC_GetErrDesc +# `_RTC_GetErrDesc` Returns a brief description of a run-time error check (RTC) type. @@ -24,26 +24,26 @@ const char * _RTC_GetErrDesc( ### Parameters -*errnum*
-A number between zero and one less than the value returned by **_RTC_NumErrors**. +*`errnum`*\ +A number between zero and one less than the value returned by `_RTC_NumErrors`. -## Return Value +## Return value -A character string that contains a short description of one of the error types detected by the run-time error check system. If error is less than zero or greater than or equal to the value returned by [_RTC_NumErrors](rtc-numerrors.md), **_RTC_GetErrDesc** returns **NULL**. +A character string that contains a short description of one of the error types detected by the run-time error check system. If error is less than zero or greater than or equal to the value returned by [`_RTC_NumErrors`](rtc-numerrors.md), **`_RTC_GetErrDesc`** returns `NULL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_GetErrDesc**|\| +| Routine | Required header | +|---|---| +| **`_RTC_GetErrDesc`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_NumErrors](rtc-numerrors.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_NumErrors`](rtc-numerrors.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-numerrors.md b/docs/c-runtime-library/reference/rtc-numerrors.md index adc69743fb..f2428d8e7a 100644 --- a/docs/c-runtime-library/reference/rtc-numerrors.md +++ b/docs/c-runtime-library/reference/rtc-numerrors.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _RTC_NumErrors" title: "_RTC_NumErrors" +description: "Learn more about: _RTC_NumErrors" ms.date: "11/04/2016" api_name: ["_RTC_NumErrors"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,36 +8,34 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_RTC_NumErrors", "RTC_NumErrors"] helpviewer_keywords: ["run-time errors", "_RTC_NumErrors function", "RTC_NumErrors function"] -ms.assetid: 7e82adae-38e2-4f8b-bc0b-37bda8109fd1 --- -# _RTC_NumErrors +# `_RTC_NumErrors` -Returns the total number of errors that can be detected by run-time error checks (RTC). You can use this number as the control in a **`for`** loop, where each value in the loop is passed to [_RTC_GetErrDesc](rtc-geterrdesc.md). +Returns the total number of errors that can be detected by run-time error checks (RTC). You can use this number as the control in a **`for`** loop, where each value in the loop is passed to [`_RTC_GetErrDesc`](rtc-geterrdesc.md). ## Syntax ```C - int _RTC_NumErrors( void ); ``` -## Return Value +## Return value An integer whose value represents the total number of errors that can be detected by the Visual C++ run-time error checks. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_NumErrors**|\| +| Routine | Required header | +|---|---| +| **`_RTC_NumErrors`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_GetErrDesc](rtc-geterrdesc.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_GetErrDesc`](rtc-geterrdesc.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrorfunc.md b/docs/c-runtime-library/reference/rtc-seterrorfunc.md index be9e6e6c44..decf0fe6e5 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfunc.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfunc.md @@ -10,9 +10,9 @@ f1_keywords: ["RTC_SetErrorFunc", "_RTC_SetErrorFunc"] helpviewer_keywords: ["RTC_SetErrorFunc function", "_RTC_SetErrorFunc function"] ms.assetid: b2292722-0d83-4092-83df-3d5b19880666 --- -# _RTC_SetErrorFunc +# `_RTC_SetErrorFunc` -Designates a function as the handler for reporting run-time error checks (RTCs). This function is deprecated; use **_RTC_SetErrorFuncW** instead. +Designates a function as the handler for reporting run-time error checks (RTCs). This function is deprecated; use `_RTC_SetErrorFuncW` instead. ## Syntax @@ -24,30 +24,30 @@ _RTC_error_fn _RTC_SetErrorFunc( ### Parameters -*function*
+*`function`*\ The address of the function that will handle run-time error checks. -## Return Value +## Return value -The previously defined error function. If there is no previously defined function, returns **NULL**. +The previously defined error function. If there's no previously defined function, returns `NULL`. ## Remarks -Do not use this function; instead, use **_RTC_SetErrorFuncW**. It is retained only for backward compatibility. +Don't use this function; instead, use `_RTC_SetErrorFuncW`. It's retained only for backward compatibility. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorFunc**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorFunc`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md index 28fe0f94e8..5505a8b542 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md @@ -10,7 +10,7 @@ f1_keywords: ["_RTC_SetErrorFuncW", "RTC_SetErrorFuncW"] helpviewer_keywords: ["run-time errors", "RTC_SetErrorFuncW function", "_RTC_error_fnW typedef", "_RTC_SetErrorFuncW function", "RTC_error_fnW typedef"] ms.assetid: b3e0d71f-1bd3-4c37-9ede-2f638eb3c81a --- -# _RTC_SetErrorFuncW +# `_RTC_SetErrorFuncW` Designates a function as the handler for the reporting of run-time error checks (RTCs). @@ -24,26 +24,26 @@ _RTC_error_fnW _RTC_SetErrorFuncW( ### Parameters -*function*
+*`function`*\ The address of the function that will handle run-time error checks. -## Return Value +## Return value -The previously defined error function; or **NULL** if there is no previously defined function. +The previously defined error function; or `NULL` if there's no previously defined function. ## Remarks -In new code, use only **_RTC_SetErrorFuncW**. **_RTC_SetErrorFunc** is only included in the library for backward compatibility. +In new code, use only **`_RTC_SetErrorFuncW`**. `_RTC_SetErrorFunc` is only included in the library for backward compatibility. -The **_RTC_SetErrorFuncW** callback applies only to the component that it was linked in, but not globally. +The **`_RTC_SetErrorFuncW`** callback applies only to the component that it was linked in, but not globally. -Make sure that the address that you pass to **_RTC_SetErrorFuncW** is that of a valid error handling function. +Make sure that the address that you pass to **`_RTC_SetErrorFuncW`** is that of a valid error handling function. -If an error has been assigned a type of -1 by using [_RTC_SetErrorType](rtc-seterrortype.md), the error handling function is not called. +If an error has been assigned a type of -1 by using [`_RTC_SetErrorType`](rtc-seterrortype.md), the error handling function isn't called. -Before you can call this function, you must first call one of the run-time error-check initialization functions. For more information, see [Using Run-Time Checks Without the C Run-Time Library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library). +Before you can call this function, you must first call one of the run-time error-check initialization functions. For more information, see [Using runtime checks without the C runtime library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library). -**_RTC_error_fnW** is defined as follows: +`_RTC_error_fnW` is defined as follows: ```cpp typedef int (__cdecl * _RTC_error_fnW)( @@ -57,36 +57,36 @@ typedef int (__cdecl * _RTC_error_fnW)( where: -*errorType*
-The type of error that's specified by [_RTC_SetErrorType](rtc-seterrortype.md). +*`errorType`*\ +The type of error that's specified by [`_RTC_SetErrorType`](rtc-seterrortype.md). -*filename*
+*`filename`*\ The source file where the failure occurred, or null if no debug information is available. -*linenumber*
-The line in *filename* where the failure occurred, or 0 if no debug information is available. +*`linenumber`*\ +The line in *`filename`* where the failure occurred, or 0 if no debug information is available. -*moduleName*
+*`moduleName`*\ The DLL or executable name where the failure occurred. -*format*
-printf style string to display an error message, using the remaining parameters. The first argument of the VA_ARGLIST is the RTC Error number that occurred. +*`format`*\ +printf style string to display an error message, using the remaining parameters. The first argument of the `VA_ARGLIST` is the RTC Error number that occurred. -For an example that shows how to use **_RTC_error_fnW**, see [Native Run-Time Checks Customization](/visualstudio/debugger/native-run-time-checks-customization). +For an example that shows how to use `_RTC_error_fnW`, see [Native runtime checks customization](/visualstudio/debugger/native-run-time-checks-customization). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorFuncW**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorFuncW`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrortype.md b/docs/c-runtime-library/reference/rtc-seterrortype.md index 67c4707734..29ed6bd05d 100644 --- a/docs/c-runtime-library/reference/rtc-seterrortype.md +++ b/docs/c-runtime-library/reference/rtc-seterrortype.md @@ -10,7 +10,7 @@ f1_keywords: ["RTC_SetErrorType", "_RTC_SetErrorType"] helpviewer_keywords: ["run-time errors", "RTC_SetErrorType function", "_RTC_SetErrorType function"] ms.assetid: f5f99be7-d357-4b11-b8f5-ddd3428f2b06 --- -# _RTC_SetErrorType +# `_RTC_SetErrorType` Associates an error that is detected by run-time error checks (RTCs) with a type. Your error handler processes how to output errors of the specified type. @@ -25,37 +25,37 @@ int _RTC_SetErrorType( ### Parameters -*errnum*
-A number between zero and one less than the value returned by [_RTC_NumErrors](rtc-numerrors.md). +*`errnum`*\ +A number between zero and one less than the value returned by [`_RTC_NumErrors`](rtc-numerrors.md). -*ErrType*
-A value to assign to this *errnum*. For example, you might use **_CRT_ERROR**. If you are using **_CrtDbgReport** as your error handler, *ErrType* can only be one of the symbols defined in [_CrtSetReportMode](crtsetreportmode.md). If you have your own error handler ([_RTC_SetErrorFunc](rtc-seterrorfunc.md)), you can have as many *ErrType*s as there are *errnum*s. +*`ErrType`*\ +A value to assign to this *`errnum`*. For example, you might use `_CRT_ERROR`. If you're using `_CrtDbgReport` as your error handler, *`ErrType`* can only be one of the symbols defined in [`_CrtSetReportMode`](crtsetreportmode.md). If you have your own error handler ([`_RTC_SetErrorFunc`](rtc-seterrorfunc.md)), you can have as many *`ErrType`* values as there are *`errnum`* values. -An *ErrType* of _RTC_ERRTYPE_IGNORE has special meaning to **_CrtSetReportMode**; the error is ignored. +An *`ErrType`* of `_RTC_ERRTYPE_IGNORE` has special meaning to `_CrtSetReportMode`; the error is ignored. -## Return Value +## Return value -The previous value for the error type *type*. +The previous value for the error type replaced by *`ErrType`*. ## Remarks -By default, all errors are set to *ErrType* = 1, which corresponds to **_CRT_ERROR**. For more information about the default error types such as **_CRT_ERROR**, see [_CrtDbgReport](crtdbgreport-crtdbgreportw.md). +By default, all errors are set to *`ErrType`* = 1, which corresponds to `_CRT_ERROR`. For more information about the default error types such as `_CRT_ERROR`, see [`_CrtDbgReport`](crtdbgreport-crtdbgreportw.md). -Before you can call this function, you must first call one of the run-time error check initialization functions; see [Using Run-Time Checks without the C Run-Time Library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library) +Before you can call this function, you must first call one of the run-time error check initialization functions; see [Using runtime checks without the C runtime library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library) ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorType**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorType`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_GetErrDesc](rtc-geterrdesc.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_GetErrDesc`](rtc-geterrdesc.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/scalb.md b/docs/c-runtime-library/reference/scalb.md index cf5629f13b..f4754e7857 100644 --- a/docs/c-runtime-library/reference/scalb.md +++ b/docs/c-runtime-library/reference/scalb.md @@ -3,7 +3,7 @@ description: "Learn more about: _scalb, _scalbf" title: "_scalb, _scalbf" ms.date: "1/15/2021" api_name: ["_scalb", "_scalbf", "_o__scalb", "_o__scalbf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["scalb", "_scalb", "_scalbf"] @@ -34,27 +34,27 @@ Double-precision, floating-point value. *`exp`*\ Long integer exponent. -## Return Value +## Return value -Returns an exponential value if successful. On overflow (depending on the sign of *`x`*), **`_scalb`** returns +/- **`HUGE_VAL`**; the **`errno`** variable is set to **`ERANGE`**. +Returns an exponential value if successful. On overflow (depending on the sign of *`x`*), **`_scalb`** returns +/- `HUGE_VAL`; the `errno` variable is set to `ERANGE`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_scalb`** function calculates the value of *`x`* \* 2*`exp`*. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_scalb`**, **`_scalbf`**|``| +| Routine | Required header | +|---|---| +| **`_scalb`**, **`_scalbf`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`ldexp`](ldexp.md) diff --git a/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md b/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md index 04c178a560..53eccc387b 100644 --- a/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md +++ b/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md @@ -3,16 +3,16 @@ title: "scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl" description: "API reference for scalbn, scalbnf, scalbnl, scalbln, scalblnf, and scalblnl; which multiplies a floating-point number by an integral power of `FLT_RADIX`." ms.date: "9/1/2020" api_name: ["scalblnl", "scalbnl", "scalbnf", "scalblnf", "scalbn", "scalbln", "_o_scalbln", "_o_scalblnf", "_o_scalblnl", "_o_scalbn", "_o_scalbnf", "_o_scalbnl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["scalblnf", "scalbnl", "scalblnl", "scalbln", "scalbn", "scalbnf"] helpviewer_keywords: ["scalbn function", "scalbln function", "scalblnl function", "scalbnl function", "scalbnf function", "scalblnf function"] ms.assetid: df2f1543-8e39-4af4-a5cf-29307e64807d --- -# scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl +# `scalbn`, `scalbnf`, `scalbnl`, `scalbln`, `scalblnf`, `scalblnl` -Multiplies a floating-point number by an integral power of FLT_RADIX. +Multiplies a floating-point number by an integral power of `FLT_RADIX`. ## Syntax @@ -68,36 +68,36 @@ long double scalbln( ### Parameters -*x*\ +*`x`*\ Floating-point value. -*exp*\ +*`exp`*\ Integer exponent. -## Return Value +## Return value -The **scalbn** functions return the value of *x* \* **FLT_RADIX**exp when successful. On overflow (depending on the sign of *x*), **scalbn** returns +/- **HUGE_VAL**; the **errno** value is set to **ERANGE**. +The **`scalbn`** functions return the value of *`x`* \* `FLT_RADIX`exp when successful. On overflow (depending on the sign of *`x`*), **`scalbn`** returns +/- `HUGE_VAL`; the `errno` value is set to `ERANGE`. -For more information about **errno** and possible error return values, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about `errno` and possible error return values, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -**FLT_RADIX** is defined in \ as the native floating-point radix; on binary systems, it has a value of 2, and **scalbn** is equivalent to [ldexp](ldexp.md). +`FLT_RADIX` is defined in \ as the native floating-point radix; on binary systems, it has a value of 2, and **`scalbn`** is equivalent to [`ldexp`](ldexp.md). -Because C++ allows overloading, you can call overloads of **scalbn** and **scalbln** that take and return **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **scalbn** always takes a **`double`** and an **`int`** and returns a **`double`**, and **scalbln** always takes a **`double`** and a **`long`** and returns a **`double`**. +Because C++ allows overloading, you can call **`scalbn`** and **`scalbln`** overloads that take and return **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`scalbn`** always takes a **`double`** and an **`int`** and returns a **`double`**, and **`scalbln`** always takes a **`double`** and a **`long`** and returns a **`double`**. -If you use the \ `scalbn()` or `scalbln` macros, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `scalbn()` or `scalbln` macros, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**scalbn**, **scalbnf**, **scalbnl**, **scalbln**, **scalblnf**, **scalblnl**|\|\| -|**scalbn() or scalbln** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`scalbn`**, **`scalbnf`**, **`scalbnl`**, **`scalbln`**, **`scalblnf`**, **`scalblnl`** | \ | \ | +| **`scalbn`** or **`scalbln`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,7 +125,7 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[frexp](frexp.md)
-[ldexp](ldexp.md)
-[modf, modff, modfl](modf-modff-modfl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`frexp`](frexp.md)\ +[`ldexp`](ldexp.md)\ +[`modf`, `modff`, `modfl`](modf-modff-modfl.md) diff --git a/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md b/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md index 7bf889d61d..db73e93f9d 100644 --- a/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md +++ b/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md @@ -12,7 +12,7 @@ ms.assetid: 42cafcf7-52d6-404a-80e4-b056a7faf2e5 --- # `scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l` -Reads formatted data from the standard input stream. These versions of [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the standard input stream. These versions of [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -39,30 +39,30 @@ int _wscanf_s_l( ### Parameters -*`format`*
+*`format`*\ Format control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates no fields were assigned. The return value is **EOF** for an error, or if the end-of-file character or the end-of-string character is found in the first attempt to read a character. If *format* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`scanf_s`** and **`wscanf_s`** return **EOF** and set **`errno`** to **`EINVAL`**. +Returns the number of fields successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates no fields were assigned. The return value is `EOF` for an error, or if the end-of-file character or the end-of-string character is found in the first attempt to read a character. If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`scanf_s`** and **`wscanf_s`** return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`scanf_s`** function reads data from the standard input stream, **`stdin`**, and writes it into *`argument`*. Each *`argument`* must be a pointer to a variable type that corresponds to the type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. -**`wscanf_s`** is a wide-character version of **`scanf_s`**; the *format* argument to **`wscanf_s`** is a wide-character string. **`wscanf_s`** and **`scanf_s`** behave identically if the stream is opened in ANSI mode. **`scanf_s`** doesn't currently support input from a UNICODE stream. +**`wscanf_s`** is a wide-character version of **`scanf_s`**; the *`format`* argument to **`wscanf_s`** is a wide-character string. **`wscanf_s`** and **`scanf_s`** behave identically if the stream is opened in ANSI mode. **`scanf_s`** doesn't currently support input from a UNICODE stream. -The versions of these functions that have the **_l** suffix are identical, except they use the *`locale`* parameter instead of the current thread locale. +The versions of these functions that have the `_l` suffix are identical, except they use the *`locale`* parameter instead of the current thread locale. -Unlike **`scanf`** and **`wscanf`**, **`scanf_s`** and **`wscanf_s`** require you to specify buffer sizes for some parameters. Specify the sizes for all **`c`**, **`C`**, **`s`**, **`S`**, or string control set **`[]`** parameters. The buffer size in characters is passed as an additional parameter. It immediately follows the pointer to the buffer or variable. For example, if you're reading a string, the buffer size for that string is passed as follows: +Unlike **`scanf`** and **`wscanf`**, **`scanf_s`** and **`wscanf_s`** require you to specify buffer sizes for some parameters. Specify the sizes for all **`c`**, **`C`**, **`s`**, **`S`**, or string control set **`[]`** parameters. The buffer size in characters is passed as another parameter. It immediately follows the pointer to the buffer or variable. For example, if you're reading a string, the buffer size for that string is passed as follows: ```C char s[10]; @@ -97,25 +97,25 @@ char c[4]; scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated ``` -For more information, see [`scanf` Width Specification](../../c-runtime-library/scanf-width-specification.md). +For more information, see [`scanf` Width Specification](../scanf-width-specification.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tscanf_s`**|**`scanf_s`**|**`scanf_s`**|**`wscanf_s`**| -|**`_tscanf_s_l`**|**`_scanf_s_l`**|**`_scanf_s_l`**|**`_wscanf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tscanf_s` | **`scanf_s`** | **`scanf_s`** | **`wscanf_s`** | +| `_tscanf_s_l` | **`_scanf_s_l`** | **`_scanf_s_l`** | **`_wscanf_s_l`** | -For more information, see [Format Specification Fields: `scanf` and `wscanf` Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`scanf_s`**, **`_scanf_s_l`**|``| -|**`wscanf_s`**, **`_wscanf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`scanf_s`**, **`_scanf_s_l`** | `` | +| **`wscanf_s`**, **`_wscanf_s_l`** | `` or `` | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles **`stdin`**, **`stdout`**, and **`stderr`** must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles **`stdin`**, **`stdout`**, and **`stderr`** must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -166,10 +166,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md b/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md index abf517c7c8..2cc46c3217 100644 --- a/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md +++ b/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md @@ -12,10 +12,10 @@ ms.assetid: 73eac607-117f-4be4-9ff0-4afd9cf3c848 --- # `scanf`, `_scanf_l`, `wscanf`, `_wscanf_l` -Reads formatted data from the standard input stream. More secure versions of these function are available; see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). +Reads formatted data from the standard input stream. More secure versions of these functions are available; see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see Linker Error LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). ## Syntax @@ -42,51 +42,51 @@ int _wscanf_l( ### Parameters -*`format`*
+*`format`*\ Format control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. +Returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. -If *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EOF`** and set **`errno`** to **`EINVAL`**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`scanf`** function reads data from the standard input stream **`stdin`** and writes the data into the location given by *`argument`*. Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When reading a string with **`scanf`**, always specify a width for the **`%s`** format (for example, **"`%32s`"** instead of **"`%s`"**); otherwise, improperly formatted input can easily cause a buffer overrun. Alternately, consider using [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) or [`fgets`](fgets-fgetws.md). +> When reading a string with **`scanf`**, always specify a width for the **`%s`** format (for example, `%32s` instead of `%s`); otherwise, improperly formatted input can easily cause a buffer overrun. Alternately, consider using [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) or [`fgets`](fgets-fgetws.md). **`wscanf`** is a wide-character version of **`scanf`**; the *`format`* argument to **`wscanf`** is a wide-character string. **`wscanf`** and **`scanf`** behave identically if the stream is opened in ANSI mode. **`scanf`** doesn't currently support input from a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tscanf`**|**`scanf`**|**`scanf`**|**`wscanf`**| -|**`_tscanf_l`**|**`_scanf_l`**|**`_scanf_l`**|**`_wscanf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tscanf`** | **`scanf`** | **`scanf`** | **`wscanf`** | +| **`_tscanf_l`** | **`_scanf_l`** | **`_scanf_l`** | **`_wscanf_l`** | -For more information, see [Format Specification Fields — scanf functions and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`scanf`**, *`*_scanf_l`**|``| -|**`wscanf`**, **`_wscanf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`scanf`**, **`_scanf_l`** | `` | +| **`wscanf`**, **`_wscanf_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -128,10 +128,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md b/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md index 2303645c16..8456b644e9 100644 --- a/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md +++ b/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["_scwprintf_p_l", "_sctprintf_p", "scprintf_p_l", "scprintf_p", "_sctprintf_p_l", "scwprintf_p", "_scprintf_p_l", "scwprintf_p_l", "_scprintf_p", "_scwprintf_p"] helpviewer_keywords: ["sctprintf_p_l function", "_scwprintf_p_l function", "scprintf_p_l function", "_scprintf_p function", "_scprintf_p_l function", "scprintf_p function", "sctprintf_p function", "_scwprintf_p function", "_sctprintf_p function", "scwprintf_p function", "scwprintf_p_l function", "_sctprintf_p_l function"] --- -# _scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l +# `_scprintf_p`, `_scprintf_p_l`, `_scwprintf_p`, `_scwprintf_p_l` Returns the number of characters in the formatted string, with the ability to specify the order in which parameters are used in the format string. @@ -38,55 +38,54 @@ int _scwprintf_p _l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_scwprintf_p** performs the same function for wide characters. +Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_scwprintf_p`** performs the same function for wide characters. -The difference between **_scprintf_p** and **_scprintf** is that **_scprintf_p** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +The difference between **`_scprintf_p`** and `_scprintf` is that **`_scprintf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf_p**|**_scprintf_p**|**_scprintf_p**|**_scwprintf_p**| -|**_sctprintf_p_l**|**_scprintf_p_l**|**_scprintf_p_l**|**_scwprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sctprintf_p` | **`_scprintf_p`** | **`_scprintf_p`** | **`_scwprintf_p`** | +| `_sctprintf_p_l` | **`_scprintf_p_l`** | **`_scprintf_p_l`** | **`_scwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_scprintf_p**, **_scprintf_p_l**|\| -|**_scwprintf_p**, **_scwprintf_p_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_scprintf_p`**, **`_scprintf_p_l`** | \ | +| **`_scwprintf_p`**, **`_scwprintf_p_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_scprintf, _scprintf_l, _scwprintf, _scwprintf_l](scprintf-scprintf-l-scwprintf-scwprintf-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l`](scprintf-scprintf-l-scwprintf-scwprintf-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) diff --git a/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md b/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md index c05c00ba7a..49789f506d 100644 --- a/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md +++ b/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["scprintf", "_scprintf_l", "_scwprintf_l", "_scprintf", "scwprintf", "_scwprintf", "scprintf_l", "_sctprintf_l", "scwprintf_l", "_sctprintf"] helpviewer_keywords: ["scprintf function", "sctprintf_l function", "scwprintf_l function", "_scwprintf_l function", "_sctprintf_l function", "sctprintf function", "_scwprintf function", "_scprintf_l function", "_sctprintf function", "scprintf_l function", "formatted text [C++]", "_scprintf function", "scwprintf function"] --- -# _scprintf, _scprintf_l, _scwprintf, _scwprintf_l +# `_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l` Returns the number of characters in the formatted string. @@ -38,52 +38,51 @@ int _scwprintf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_scwprintf** performs the same function for wide characters. +Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_scwprintf`** performs the same function for wide characters. -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf**|**_scprintf**|**_scprintf**|**_scwprintf**| -|**_sctprintf_l**|**_scprintf_l**|**_scprintf_l**|**_scwprintf_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sctprintf` | **`_scprintf`** | **`_scprintf`** | **`_scwprintf`** | +| `_sctprintf_l` | **`_scprintf_l`** | **`_scprintf_l`** | **`_scwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_scprintf**, **_scprintf_l**|\| -|**_scwprintf**, **_scwprintf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_scprintf`**, **`_scprintf_l`** | \ | +| **`_scwprintf`**, **`_scwprintf_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,9 +121,9 @@ The value of Pi is calculated to be 3.141593. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md b/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md index 278069237f..dd5d360542 100644 --- a/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md +++ b/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _searchenv_s, _wsearchenv_s" title: "_searchenv_s, _wsearchenv_s" ms.date: "4/2/2020" api_name: ["_wsearchenv_s", "_searchenv_s", "_o__searchenv_s", "_o__wsearchenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_searchenv_s", "_wsearchenv_s", "wsearchenv_s", "searchenv_s"] helpviewer_keywords: ["tsearchenv_s function", "files [C++], finding", "buffers [C++], buffer overruns", "environment paths, searching for files", "wsearchenv_s function", "searchenv_s function", "_tsearchenv_s function", "buffer overruns", "buffers [C++], avoiding overruns", "_wsearchenv_s function", "_searchenv_s function", "environment paths"] ms.assetid: 47f9fc29-250e-4c09-b52e-9e9f0ef395ca --- -# _searchenv_s, _wsearchenv_s +# `_searchenv_s`, `_wsearchenv_s` -Searches for a file by using environment paths. These versions of [_searchenv, _wsearchenv](searchenv-wsearchenv.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Searches for a file by using environment paths. These versions of [`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -48,62 +48,62 @@ errno_t _wsearchenv_s( ### Parameters -*filename*
+*`filename`*\ Name of the file to search for. -*varname*
+*`varname`*\ Environment to search. -*pathname*
+*`pathname`*\ Buffer to store the complete path. -*numberOfElements*
-Size of the *pathname* buffer. +*`numberOfElements`*\ +Size of the *`pathname`* buffer. -## Return Value +## Return value Zero if successful; an error code on failure. -If *filename* is an empty string, the return value is **ENOENT**. +If *`filename`* is an empty string, the return value is `ENOENT`. -### Error Conditions +### Error conditions -|*filename*|*varname*|*pathname*|*numberOfElements*|Return value|Contents of *pathname*| -|----------------|---------------|----------------|------------------------|------------------|----------------------------| -|any|any|**NULL**|any|**EINVAL**|n/a| -|**NULL**|any|any|any|**EINVAL**|not changed| -|any|any|any|<= 0|**EINVAL**|not changed| +| *`filename`* | *`varname`* | *`pathname`* | *`numberOfElements`* | Return value | Contents of *`pathname`* | +|---|---|---|---|---|---| +| any | any | `NULL` | any | `EINVAL` | n/a | +| `NULL` | any | any | any | `EINVAL` | not changed | +| any | any | any | <= 0 | `EINVAL` | not changed | -If any of these error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EINVAL**. +If any of these error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -The **_searchenv_s** routine searches for the target file in the specified domain. The *varname* variable can be any environment or user-defined variable that specifies a list of directory paths, such as **PATH**, **LIB**, and **INCLUDE**. Because **_searchenv_s** is case-sensitive, *varname* should match the case of the environment variable. If *varname* does not match the name of an environment variable defined in the process's environment, the function returns zero and the *pathname* variable is unchanged. +The **`_searchenv_s`** routine searches for the target file in the specified domain. The *`varname`* variable can be any environment or user-defined variable that specifies a list of directory paths, such as `PATH`, `LIB`, and `INCLUDE`. Because **`_searchenv_s`** is case-sensitive, *`varname`* should match the case of the environment variable. If *`varname`* doesn't match the name of an environment variable defined in the process's environment, the function returns zero, and the *`pathname`* variable is unchanged. -The routine searches first for the file in the current working directory. If it does not find the file, it looks next through the directories specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *pathname*. If the *filename* file is not found, *pathname* contains an empty null-terminated string. +The routine searches first for the file in the current working directory. If it doesn't find the file, it looks next through the directories specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *`pathname`*. If the *`filename`* file isn't found, *`pathname`* contains an empty null-terminated string. -The *pathname* buffer should be at least **_MAX_PATH** characters long to accommodate the full length of the constructed path name. Otherwise, **_searchenv_s** might overrun the *pathname* buffer resulting in unexpected behavior. +The *`pathname`* buffer should be at least `_MAX_PATH` characters long to accommodate the full length of the constructed path name. Otherwise, **`_searchenv_s`** might overrun the *`pathname`* buffer resulting in unexpected behavior. -**_wsearchenv_s** is a wide-character version of **_searchenv_s**; the arguments to **_wsearchenv_s** are wide-character strings. **_wsearchenv_s** and **_searchenv_s** behave identically otherwise. +**`_wsearchenv_s`** is a wide-character version of **`_searchenv_s`**; the arguments to **`_wsearchenv_s`** are wide-character strings. **`_wsearchenv_s`** and **`_searchenv_s`** behave identically otherwise. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv_s**|**_searchenv_s**|**_searchenv_s**|**_wsearchenv_s**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsearchenv_s` | **`_searchenv_s`** | **`_searchenv_s`** | **`_wsearchenv_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_searchenv_s**|\| -|**_wsearchenv_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_searchenv_s`** | \ | +| **`_wsearchenv_s`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -143,7 +143,7 @@ C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_searchenv, _wsearchenv](searchenv-wsearchenv.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_putenv, _wputenv](putenv-wputenv.md)
+[Directory control](../directory-control.md)\ +[`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md) diff --git a/docs/c-runtime-library/reference/searchenv-wsearchenv.md b/docs/c-runtime-library/reference/searchenv-wsearchenv.md index 4b2ab642c6..2ca6602eaf 100644 --- a/docs/c-runtime-library/reference/searchenv-wsearchenv.md +++ b/docs/c-runtime-library/reference/searchenv-wsearchenv.md @@ -3,16 +3,16 @@ description: "Learn more about: _searchenv, _wsearchenv" title: "_searchenv, _wsearchenv" ms.date: "4/2/2020" api_name: ["_searchenv", "_wsearchenv", "_o__searchenv", "_o__wsearchenv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wsearchenv", "_tsearchenv", "wsearchenv", "_searchenv", "searchenv"] helpviewer_keywords: ["_wsearchenv function", "files [C++], finding", "_searchenv function", "tsearchenv function", "environment paths, searching for files", "_tsearchenv function", "wsearchenv function", "searchenv function", "environment paths"] ms.assetid: 9c944a27-d326-409b-aee6-410e8762d9d3 --- -# _searchenv, _wsearchenv +# `_searchenv`, `_wsearchenv` -Uses environment paths to search for a file. More secure versions of these functions are available; see [_searchenv_s, _wsearchenv_s](searchenv-s-wsearchenv-s.md). +Uses environment paths to search for a file. More secure versions of these functions are available; see [`_searchenv_s`, `_wsearchenv_s`](searchenv-s-wsearchenv-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -46,49 +46,49 @@ void _wsearchenv( ### Parameters -*filename*
+*`filename`*\ Name of the file to search for. -*varname*
+*`varname`*\ Environment to search. -*pathname*
+*`pathname`*\ Buffer to store the complete path. ## Remarks -The **_searchenv** routine searches for the target file in the specified domain. The *varname* variable can be any environment or user-defined variable—for example, **PATH**, **LIB**, or **INCLUDE**—that specifies a list of directory paths. Because **_searchenv** is case-sensitive, *varname* should match the case of the environment variable. +The **`_searchenv`** routine searches for the target file in the specified domain. The *`varname`* variable can be any environment or user-defined variable—for example, `PATH`, `LIB`, or `INCLUDE`—that specifies a list of directory paths. Because **`_searchenv`** is case-sensitive, *`varname`* should match the case of the environment variable. -The routine first searches for the file in the current working directory. If it does not find the file, it looks through the directories that are specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *pathname*. If the *filename* file is not found, *pathname* contains an empty null-terminated string. +The routine first searches for the file in the current working directory. If it doesn't find the file, it looks through the directories that are specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *`pathname`*. If the *`filename`* file isn't found, *`pathname`* contains an empty null-terminated string. -The *pathname* buffer should be at least **_MAX_PATH** characters long to accommodate the full length of the constructed path name. Otherwise, **_searchenv** might overrun the *pathname* buffer and cause unexpected behavior. +The *`pathname`* buffer should be at least `_MAX_PATH` characters long to accommodate the full length of the constructed path name. Otherwise, **`_searchenv`** might overrun the *`pathname`* buffer and cause unexpected behavior. -**_wsearchenv** is a wide-character version of **_searchenv**, and the arguments to **_wsearchenv** are wide-character strings. **_wsearchenv** and **_searchenv** behave identically otherwise. +**`_wsearchenv`** is a wide-character version of **`_searchenv`**, and the arguments to **`_wsearchenv`** are wide-character strings. **`_wsearchenv`** and **`_searchenv`** behave identically otherwise. -If *filename* is an empty string, these functions return **ENOENT**. +If *`filename`* is an empty string, these functions return `ENOENT`. -If *filename* or *pathname* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`filename`* or *`pathname`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For more information about **errno** and error codes, see [errno Constants](../../c-runtime-library/errno-constants.md). +For more information about `errno` and error codes, see [`errno` constants](../errno-constants.md). -In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv**|**_searchenv**|**_searchenv**|**_wsearchenv**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsearchenv` | **`_searchenv`** | **`_searchenv`** | **`_wsearchenv`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_searchenv**|\| -|**_wsearchenv**|\ or \| +| Routine | Required header | +|---|---| +| **`_searchenv`** | \ | +| **`_wsearchenv`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -124,7 +124,7 @@ C:\Program Files\Microsoft Visual Studio 8\VC\BIN\CL.EXE ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_putenv, _wputenv](putenv-wputenv.md)
-[_searchenv_s, _wsearchenv_s](searchenv-s-wsearchenv-s.md)
+[Directory control](../directory-control.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md)\ +[`_searchenv_s`, `_wsearchenv_s`](searchenv-s-wsearchenv-s.md) diff --git a/docs/c-runtime-library/reference/security-init-cookie.md b/docs/c-runtime-library/reference/security-init-cookie.md index be28d44be2..d7a8743b59 100644 --- a/docs/c-runtime-library/reference/security-init-cookie.md +++ b/docs/c-runtime-library/reference/security-init-cookie.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["security_init_cookie", "__security_init_cookie"] helpviewer_keywords: ["security cookie [C++]", "__security_init_cookie function", "security_init_cookie function", "global security cookie"] -ms.assetid: 32119905-0897-4a1c-84ca-bffd16c9b2af --- -# __security_init_cookie +# `__security_init_cookie` Initializes the global security cookie. @@ -24,9 +23,9 @@ void __security_init_cookie(void); The global security cookie is used for buffer overrun protection in code compiled with [/GS (Buffer Security Check)](../../build/reference/gs-buffer-security-check.md) and in code that uses exception handling. On entry to an overrun-protected function, the cookie is put on the stack, and on exit, the value on the stack is compared with the global cookie. Any difference between them indicates that a buffer overrun has occurred and causes immediate termination of the program. -Normally, **__security_init_cookie** is called by the CRT when it is initialized. If you bypass CRT initialization—for example, if you use [/ENTRY](../../build/reference/entry-entry-point-symbol.md) to specify an entry-point—then you must call **__security_init_cookie** yourself. If **__security_init_cookie** is not called, the global security cookie is set to a default value and buffer overrun protection is compromised. Because an attacker can exploit this default cookie value to defeat the buffer overrun checks, we recommend that you always call **__security_init_cookie** when you define your own entry point. +Normally, **`__security_init_cookie`** is called by the CRT when it's initialized. If you bypass CRT initialization—for example, if you use [`/ENTRY`](../../build/reference/entry-entry-point-symbol.md) to specify an entry-point—then you must call **`__security_init_cookie`** yourself. If **`__security_init_cookie`** isn't called, the global security cookie is set to a default value, and buffer overrun protection is compromised. Because an attacker can exploit this default cookie value to defeat the buffer overrun checks, we recommend that you always call **`__security_init_cookie`** when you define your own entry point. -The call to **__security_init_cookie** must be made before any overrun-protected function is entered; otherwise a spurious buffer overrun will be detected. For more information, see [C Runtime Error R6035](../../error-messages/tool-errors/c-runtime-error-r6035.md). +The call to **`__security_init_cookie`** must be made before any overrun-protected function is entered; otherwise a spurious buffer overrun will be detected. For more information, see [C Runtime Error R6035](../../error-messages/tool-errors/c-runtime-error-r6035.md). ## Example @@ -34,11 +33,11 @@ See the examples in [C Runtime Error R6035](../../error-messages/tool-errors/c-r ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**__security_init_cookie**|\| +| Routine | Required header | +|---|---| +| **`__security_init_cookie`** | `` | -**__security_init_cookie** is a Microsoft extension to the standard C Runtime Library. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`__security_init_cookie`** is a Microsoft extension to the standard C Runtime Library. For compatibility information, see [Compatibility](../compatibility.md). ## See also diff --git a/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md b/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md index bd7906b5c9..f25e172109 100644 --- a/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md +++ b/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md @@ -3,14 +3,14 @@ description: "Learn more about: _seh_filter_dll, _seh_filter_exe" title: "_seh_filter_dll, _seh_filter_exe" ms.date: "4/2/2020" api_name: ["_XcptFilter", "_seh_filter_dll", "_seh_filter_exe", "_o__seh_filter_dll", "_o__seh_filter_exe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["XcptFilter", "_XcptFilter", "_seh_filter_dll", "_seh_filter_exe", "corecrt_startup/_seh_filter_exe", "corecrt_startup/_seh_filter_dll"] helpviewer_keywords: ["XcptFilter function", "_XcptFilter function", "_seh_filter_dll function", "_seh_filter_exe function"] ms.assetid: 747e5963-3a12-4bf5-b5c4-d4c1b6068e15 --- -# _seh_filter_dll, _seh_filter_exe +# `_seh_filter_dll`, `_seh_filter_exe` Identifies the exception and the related action to be taken. @@ -18,24 +18,24 @@ Identifies the exception and the related action to be taken. ```C int __cdecl _seh_filter_dll( - unsigned long _ExceptionNum, - struct _EXCEPTION_POINTERS* _ExceptionPtr + unsigned long exceptionNum, + struct _EXCEPTION_POINTERS* exceptionPtr ); int __cdecl _seh_filter_exe( - unsigned long _ExceptionNum, - struct _EXCEPTION_POINTERS* _ExceptionPtr + unsigned long exceptionNum, + struct _EXCEPTION_POINTERS* exceptionPtr ); ``` ### Parameters -*_ExceptionNum*
+*`exceptionNum`*\ The identifier for the exception. -*_ExceptionPtr*
+*`exceptionPtr`*\ A pointer to the exception information. -## Return Value +## Return value An integer that indicates the action to be taken, based on the result of exception processing. @@ -43,20 +43,20 @@ An integer that indicates the action to be taken, based on the result of excepti These methods are called by the exception-filter expression of the [try-except Statement](../../cpp/try-except-statement.md). The method consults a constant internal table to identify the exception and determine the appropriate action, as shown here. The exception numbers are defined in winnt.h and the signal numbers are defined in signal.h. -|Exception Number (unsigned long)|Signal Number| -|----------------------------------------|-------------------| -|STATUS_ACCESS_VIOLATION|SIGSEGV| -|STATUS_ILLEGAL_INSTRUCTION|SIGILL| -|STATUS_PRIVILEGED_INSTRUCTION|SIGILL| -|STATUS_FLOAT_DENORMAL_OPERAND|SIGFPE| -|STATUS_FLOAT_DIVIDE_BY_ZERO|SIGFPE| -|STATUS_FLOAT_INEXACT_RESULT|SIGFPE| -|STATUS_FLOAT_INVALID_OPERATION|SIGFPE| -|STATUS_FLOAT_OVERFLOW|SIGFPE| -|STATUS_FLOAT_STACK_CHECK|SIGFPE| -|STATUS_FLOAT_UNDERFLOW|SIGFPE| - -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +| Exception number (unsigned long) | Signal number | +|---|---| +| `STATUS_ACCESS_VIOLATION` | `SIGSEGV` | +| `STATUS_ILLEGAL_INSTRUCTION` | `SIGILL` | +| `STATUS_PRIVILEGED_INSTRUCTION` | `SIGILL` | +| `STATUS_FLOAT_DENORMAL_OPERAND` | `SIGFPE` | +| `STATUS_FLOAT_DIVIDE_BY_ZERO` | `SIGFPE` | +| `STATUS_FLOAT_INEXACT_RESULT` | `SIGFPE` | +| `STATUS_FLOAT_INVALID_OPERATION` | `SIGFPE` | +| `STATUS_FLOAT_OVERFLOW` | `SIGFPE` | +| `STATUS_FLOAT_STACK_CHECK` | `SIGFPE` | +| `STATUS_FLOAT_UNDERFLOW` | `SIGFPE` | + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements @@ -64,4 +64,4 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/set-abort-behavior.md b/docs/c-runtime-library/reference/set-abort-behavior.md index 6eaa4d5551..957edb7430 100644 --- a/docs/c-runtime-library/reference/set-abort-behavior.md +++ b/docs/c-runtime-library/reference/set-abort-behavior.md @@ -1,20 +1,20 @@ --- description: "Learn more about: _set_abort_behavior" title: "_set_abort_behavior" -ms.date: "4/2/2020" +ms.date: 07/07/2022 api_name: ["_set_abort_behavior", "_o__set_abort_behavior"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_set_abort_behavior", "set_abort_behavior"] +f1_keywords: ["STDLIB/_set_abort_behavior", "_set_abort_behavior", "set_abort_behavior"] helpviewer_keywords: ["aborting programs", "_set_abort_behavior function", "set_abort_behavior function"] --- -# _set_abort_behavior +# `_set_abort_behavior` Specifies the action to be taken when a program is abnormally terminated. > [!NOTE] -> Do not use the [abort](abort.md) function to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use the [`abort`](abort.md) function to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -27,29 +27,31 @@ unsigned int _set_abort_behavior( ### Parameters -*flags*
-New value of the [abort](abort.md) flags. +*`flags`*\ +New value of the `abort` flags. -*mask*
-Mask for the [abort](abort.md) flags bits to set. +*`mask`*\ +Mask for the `abort` flags bits to set. -## Return Value +## Return value The old value of the flags. ## Remarks -There are two [abort](abort.md) flags: **_WRITE_ABORT_MSG** and **_CALL_REPORTFAULT**. **_WRITE_ABORT_MSG** determines whether a helpful text message is printed when a program is abnormally terminated. The message states that the application has called the [abort](abort.md) function. The default behavior is to print the message. **_CALL_REPORTFAULT**, if set, specifies that a Watson crash dump is generated and reported when [abort](abort.md) is called. By default, crash dump reporting is enabled in non-DEBUG builds. +There are two [`abort`](abort.md) flags: `_WRITE_ABORT_MSG` and `_CALL_REPORTFAULT`. `_WRITE_ABORT_MSG` determines whether a helpful text message is printed when a program is abnormally terminated. The message states that the application has called the `abort` function. The default behavior is to print the message. `_CALL_REPORTFAULT`, if set, invokes the Windows Error Reporting Service mechanism (formerly known as Dr. Watson) to report failures to Microsoft when `abort` is called. By default, crash dump reporting is enabled in non-DEBUG builds. If the Windows error reporting handler isn't invoked, then `abort` calls [`_exit`](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` doesn't flush stream buffers or do `atexit`/`_onexit` processing. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +For Windows compatibility reasons, when `abort` calls `_exit`, it may invoke the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API, which in turn allows DLL termination routines to run. Destructors aren't run in the executable, but the same may not be true of DLLs loaded in the executable's process space. This behavior doesn't strictly conform to the C++ standard. To immediately terminate a process including any DLLs, use the Windows [`TerminateProcess`](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminateprocess) API. You can also register an abort signal handler that invokes `TerminateProcess` for standard-compliant behavior. Compliant behavior may come at some cost in Windows compatibility. + +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_abort_behavior**|\| +| Routine | Required header | +|--|--| +| **`_set_abort_behavior`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -74,4 +76,4 @@ Suppressing the abort message. If successful, this message will be the only outp ## See also -[abort](abort.md)
+[`abort`](abort.md) diff --git a/docs/c-runtime-library/reference/set-controlfp.md b/docs/c-runtime-library/reference/set-controlfp.md index 5da13d46c5..b7cfc47680 100644 --- a/docs/c-runtime-library/reference/set-controlfp.md +++ b/docs/c-runtime-library/reference/set-controlfp.md @@ -10,7 +10,7 @@ f1_keywords: ["set_controlfp", "_set_controlfp"] helpviewer_keywords: ["set_controlfp function", "floating-point functions, setting control word", "_set_controlfp function"] ms.assetid: e0689d50-f68a-4028-a9c1-fb23eedee4ad --- -# _set_controlfp +# `_set_controlfp` Sets the floating-point control word. @@ -25,32 +25,32 @@ void __cdecl _set_controlfp( ### Parameters -*newControl*
+*`newControl`*\ New control-word bit values. -*mask*
+*`mask`*\ Mask for new control-word bits to set. -## Return Value +## Return value None. ## Remarks -The **_set_controlfp** function is similar to **_control87**, but it only sets the floating-point control word to *newControl*. The bits in the values indicate the floating-point control state. The floating-point control state allows the program to change the precision, rounding, and infinity modes in the floating-point math package. You can also mask or unmask floating-point exceptions using **_set_controlfp**. For more information, see [_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md). +The **`_set_controlfp`** function is similar to `_control87`, but it only sets the floating-point control word to *`newControl`*. The bits in the values indicate the floating-point control state. The floating-point control state allows the program to change the precision, rounding, and infinity modes in the floating-point math package. You can also mask or unmask floating-point exceptions using **`_set_controlfp`**. For more information, see [`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md). This function is deprecated when compiling with [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime only supports the default floating-point precision. ## Requirements -|Routine|Required header|Compatibility| -|-------------|---------------------|-------------------| -|**_set_controlfp**|\|x86 processor only| +| Routine | Required header | Compatibility | +|---|---|---| +| **`_set_controlfp`** | \ | x86 processor only | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_clear87, _clearfp](clear87-clearfp.md)
-[_status87, _statusfp, _statusfp2](status87-statusfp-statusfp2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_status87`, `_statusfp`, `_statusfp2`](status87-statusfp-statusfp2.md) diff --git a/docs/c-runtime-library/reference/set-doserrno.md b/docs/c-runtime-library/reference/set-doserrno.md index 6e3161cb1c..f6a0914ae6 100644 --- a/docs/c-runtime-library/reference/set-doserrno.md +++ b/docs/c-runtime-library/reference/set-doserrno.md @@ -3,16 +3,16 @@ description: "Learn more about: _set_doserrno" title: "_set_doserrno" ms.date: "4/2/2020" api_name: ["_set_doserrno", "_o__set_doserrno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_doserrno", "set_doserrno"] helpviewer_keywords: ["_set_doserrno function", "doserrno global variable", "set_doserrno function", "_doserrno global variable"] ms.assetid: 8686c159-3797-4705-a53e-7457869ca6f3 --- -# _set_doserrno +# `_set_doserrno` -Sets the value of the [_doserrno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) global variable. +Sets the value of the [`_doserrno`](../errno-doserrno-sys-errlist-and-sys-nerr.md) global variable. ## Syntax @@ -22,10 +22,10 @@ errno_t _set_doserrno( int error_value ); ### Parameters -*error_value*
-The new value of **_doserrno**. +*`error_value`*\ +The new value of `_doserrno`. -## Return Value +## Return value Returns zero if successful. @@ -33,17 +33,17 @@ Returns zero if successful. Possible values are defined in Errno.h. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_doserrno**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_doserrno`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_doserrno](get-doserrno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_get_doserrno`](get-doserrno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/set-errno.md b/docs/c-runtime-library/reference/set-errno.md index 44f0deceda..ed95b0eda6 100644 --- a/docs/c-runtime-library/reference/set-errno.md +++ b/docs/c-runtime-library/reference/set-errno.md @@ -3,16 +3,16 @@ description: "Learn more about: _set_errno" title: "_set_errno" ms.date: "4/2/2020" api_name: ["_set_errno", "_o__set_errno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_errno", "_set_errno"] helpviewer_keywords: ["errno global variable", "set_errno function", "_set_errno function"] ms.assetid: d338914a-1894-4cf3-ae45-f2c4eb26590b --- -# _set_errno +# `_set_errno` -Set the value of the **errno** global variable. +Set the value of the `errno` global variable. ## Syntax @@ -22,18 +22,18 @@ errno_t _set_errno( int error_value ); ### Parameters -*error_value*
-The new value of **errno**. +*`error_value`*\ +The new value of `errno`. -## Return Value +## Return value Returns zero if successful. ## Remarks -Possible values are defined in Errno.h. Also, see [errno Constants](../../c-runtime-library/errno-constants.md). +Possible values are defined in Errno.h. Also, see [`errno` constants](../errno-constants.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Example @@ -55,13 +55,13 @@ Oops: Illegal byte sequence ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_errno**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_errno`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_errno](get-errno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_get_errno`](get-errno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/set-error-mode.md b/docs/c-runtime-library/reference/set-error-mode.md index 17cabeeeeb..cdbce0d93f 100644 --- a/docs/c-runtime-library/reference/set-error-mode.md +++ b/docs/c-runtime-library/reference/set-error-mode.md @@ -10,9 +10,9 @@ f1_keywords: ["set_error_mode", "_set_error_mode"] helpviewer_keywords: ["_set_error_mode function", "set_error_mode function"] ms.assetid: f0807be5-73d1-4a32-a701-3c9bdd139c5c --- -# _set_error_mode +# `_set_error_mode` -Modifies **__error_mode** to determine a non-default location where the C runtime writes an error message for an error that might end the program. +Modifies `__error_mode` to determine a non-default location where the C runtime writes an error message for an error that might end the program. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -27,35 +27,35 @@ int _set_error_mode( ### Parameters -*mode_val*
+*`mode_val`*\ Destination of error messages. -## Return Value +## Return value Returns the old setting or -1 if an error occurs. ## Remarks -Controls the error output sink by setting the value of **__error_mode**. For example, you can direct output to a standard error or use the **MessageBox** API. +Controls the error output sink by setting the value of `__error_mode`. For example, you can direct output to a standard error or use the `MessageBox` API. -The *mode_val* parameter can be set to one of the following values. +The *`mode_val`* parameter can be set to one of the following values. -|Value|Description| -|---------------|-----------------| -|**_OUT_TO_DEFAULT**|Error sink is determined by **__app_type**.| -|**_OUT_TO_STDERR**|Error sink is a standard error.| -|**_OUT_TO_MSGBOX**|Error sink is a message box.| -|**_REPORT_ERRMODE**|Report the current **__error_mode** value.| +| Value | Description | +|---|---| +| `_OUT_TO_DEFAULT` | Error sink is determined by `__app_type`. | +| `_OUT_TO_STDERR` | Error sink is a standard error. | +| `_OUT_TO_MSGBOX` | Error sink is a message box. | +| `_REPORT_ERRMODE` | Report the current `__error_mode` value. | -If a value other than those listed is passed in, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_set_error_mode** sets **errno** to **EINVAL** and returns -1. +If a value is passed in other than the listed ones, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_set_error_mode`** sets `errno` to `EINVAL` and returns -1. -When it's used with an [assert](assert-macro-assert-wassert.md), **_set_error_mode** displays the failed statement in the dialog box and gives you the option of choosing the **Ignore** button so that you can continue to run the program. +When it's used with an [`assert`](assert-macro-assert-wassert.md), **`_set_error_mode`** displays the statement that failed in the dialog box, and gives you the option of choosing the **Ignore** button, so that you can continue to run the program. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_error_mode**|\| +| Routine | Required header | +|---|---| +| **`_set_error_mode`** | \ | ## Example @@ -81,4 +81,4 @@ Please contact the application's support team for more information. ## See also -[assert Macro, _assert, _wassert](assert-macro-assert-wassert.md)
+[assert Macro, _assert, _wassert](assert-macro-assert-wassert.md) diff --git a/docs/c-runtime-library/reference/set-fmode.md b/docs/c-runtime-library/reference/set-fmode.md index e2a8410d3f..8082bfd373 100644 --- a/docs/c-runtime-library/reference/set-fmode.md +++ b/docs/c-runtime-library/reference/set-fmode.md @@ -3,14 +3,14 @@ description: "Learn more about: _set_fmode" title: "_set_fmode" ms.date: "4/2/2020" api_name: ["_set_fmode", "_o__set_fmode"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_fmode", "set_fmode"] helpviewer_keywords: ["file translation [C++], default mode", "_set_fmode function", "file translation [C++], setting mode", "set_fmode function"] ms.assetid: f80eb9c7-733b-4652-a9bc-6b3790a35f12 --- -# _set_fmode +# `_set_fmode` Sets the default file translation mode for file I/O operations. @@ -24,28 +24,28 @@ errno_t _set_fmode( ### Parameters -*mode*
-The file translation mode desired: **_O_TEXT** or **_O_BINARY**. +*`mode`*\ +The file translation mode desired: `_O_TEXT` or `_O_BINARY`. -## Return Value +## Return value -Returns zero if successful, an error code on failure. If *mode* is not **_O_TEXT** or **_O_BINARY** or **_O_WTEXT**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Returns zero if successful, an error code on failure. If *`mode`* isn't `_O_TEXT` or `_O_BINARY` or `_O_WTEXT`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -The function sets the [_fmode](../../c-runtime-library/fmode.md) global variable. This variable specifies the default file translation mode for the file I/O operations **_open** and **_pipe**. +The function sets the [`_fmode`](../fmode.md) global variable. This variable specifies the default file translation mode for the file I/O operations `_open` and `_pipe`. -**_O_TEXT** and **_O_BINARY** are defined in Fcntl.h. **EINVAL** is defined in Errno.h. +`_O_TEXT` and `_O_BINARY` are defined in Fcntl.h. `EINVAL` is defined in Errno.h. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_fmode**|\|\, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_fmode`** | \ | \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,7 +112,7 @@ A B C D E F G H I J K L ## See also -[_fmode](../../c-runtime-library/fmode.md)
-[_get_fmode](get-fmode.md)
-[_setmode](setmode.md)
-[Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md)
+[`_fmode`](../fmode.md)\ +[`_get_fmode`](get-fmode.md)\ +[`_setmode`](setmode.md)\ +[Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) diff --git a/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md b/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md index 239612d92e..62c3ec01d4 100644 --- a/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md +++ b/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md @@ -3,14 +3,14 @@ title: "_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_hand description: "API reference for _set_invalid_parameter_handler, and _set_thread_local_invalid_parameter_handler; which set a function to be called when the CRT detects an invalid argument." ms.date: "4/2/2020" api_name: ["_set_invalid_parameter_handler", "_set_thread_local_invalid_parameter_handler", "_o__set_invalid_parameter_handler", "_o__set_thread_local_invalid_parameter_handler"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_invalid_parameter_handler", "_set_invalid_parameter_handler", "_set_thread_local_invalid_parameter_handler"] helpviewer_keywords: ["invalid parameter handler", "set_invalid_parameter_handler function", "_set_invalid_parameter_handler function", "_set_thread_local_invalid_parameter_handler function"] ms.assetid: c0e67934-1a41-4016-ad8e-972828f3ac11 --- -# _set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler +# `_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler` Sets a function to be called when the CRT detects an invalid argument. @@ -27,18 +27,18 @@ _invalid_parameter_handler _set_thread_local_invalid_parameter_handler( ### Parameters -*pNew*
+*`pNew`*\ The function pointer to the new invalid parameter handler. -## Return Value +## Return value A pointer to the invalid parameter handler before the call. ## Remarks -Many C runtime functions check the validity of arguments passed to them. If an invalid argument is passed, the function can set the **errno** error number or return an error code. In such cases, the invalid parameter handler is also called. The C runtime supplies a default global invalid parameter handler that terminates the program and displays a runtime error message. You can use the **_set_invalid_parameter_handler** to set your own function as the global invalid parameter handler. The C runtime also supports a thread-local invalid parameter handler. If a thread-local parameter handler is set in a thread by using **_set_thread_local_invalid_parameter_handler**, the C runtime functions called from the thread use that handler instead of the global handler. Only one function can be specified as the global invalid argument handler at a time. Only one function can be specified as the thread-local invalid argument handler per thread, but different threads can have different thread-local handlers. This allows you to change the handler used in one part of your code without affecting the behavior of other threads. +Many C runtime functions check the validity of arguments passed to them. If an invalid argument is passed, the function can set the `errno` error number or return an error code. In such cases, the invalid parameter handler is also called. The C runtime supplies a default global invalid parameter handler that terminates the program and displays a runtime error message. You can use the **`_set_invalid_parameter_handler`** to set your own function as the global invalid parameter handler. The C runtime also supports a thread-local invalid parameter handler. If a thread-local parameter handler is set in a thread by using **`_set_thread_local_invalid_parameter_handler`**, the C runtime functions called from the thread use that handler instead of the global handler. Only one function can be specified as the global invalid argument handler at a time. Only one function can be specified as the thread-local invalid argument handler per thread, but different threads can have different thread-local handlers. Thread local handlers allow you to change the handler used in one part of your code without affecting the behavior of other threads. -When the runtime calls the invalid parameter function, it usually means that a nonrecoverable error occurred. The invalid parameter handler function you supply should save any data it can and then abort. It should not return control to the main function unless you're confident that the error is recoverable. +When the runtime calls the invalid parameter function, it usually means that a nonrecoverable error occurred. The invalid parameter handler function you supply should save any data it can and then abort. It shouldn't return control to the main function unless you're confident that the error is recoverable. The invalid parameter handler function must have the following prototype: @@ -52,21 +52,21 @@ void _invalid_parameter( ); ``` -The *expression* argument is a wide string representation of the argument expression that raised the error. The *function* argument is the name of the CRT function that received the invalid argument. The *file* argument is the name of the CRT source file that contains the function. The *line* argument is the line number in that file. The last argument is reserved. The parameters all have the value **NULL** unless a debug version of the CRT library is used. +The *`expression`* argument is a wide string representation of the argument expression that raised the error. The *`function`* argument is the name of the CRT function that received the invalid argument. The *`file`* argument is the name of the CRT source file that contains the function. The *`line`* argument is the line number in that file. The last argument is reserved. The parameters all have the value `NULL` unless a debug version of the CRT library is used. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_invalid_parameter_handler**, **_set_thread_local_invalid_parameter_handler**|C: \

C++: \ or \| +| Routine | Required header | +|---|---| +| **`_set_invalid_parameter_handler`**, **`_set_thread_local_invalid_parameter_handler`** | C: \

C++: \ or \ | -The **_set_invalid_parameter_handler** and **_set_thread_local_invalid_parameter_handler** functions are Microsoft-specific. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_set_invalid_parameter_handler`** and **`_set_thread_local_invalid_parameter_handler`** functions are Microsoft-specific. For compatibility information, see [Compatibility](../compatibility.md). ## Example -In the following example, an invalid parameter error handler is used to print the function that received the invalid parameter and the file and line in CRT sources. When the debug CRT library is used, invalid parameter errors also raise an assertion, which is disabled in this example using [_CrtSetReportMode](crtsetreportmode.md). +In the following example, an invalid parameter error handler is used to print the function that received the invalid parameter and the file and line in CRT sources. When the debug CRT library is used, invalid parameter errors also raise an assertion, which is disabled in this example using [`_CrtSetReportMode`](crtsetreportmode.md). ```C // crt_set_invalid_parameter_handler.c @@ -112,6 +112,6 @@ Expression: format != nullptr ## See also -[_get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler](get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md)
-[Security-Enhanced Versions of CRT Functions](../../c-runtime-library/security-enhanced-versions-of-crt-functions.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_get_invalid_parameter_handler`, `_get_thread_local_invalid_parameter_handler`](get-invalid-parameter-handler-get-thread-local-invalid-parameter-handler.md)\ +[Security-enhanced versions of CRT functions](../security-enhanced-versions-of-crt-functions.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/set-new-handler.md b/docs/c-runtime-library/reference/set-new-handler.md index 9a22802654..4218bf3374 100644 --- a/docs/c-runtime-library/reference/set-new-handler.md +++ b/docs/c-runtime-library/reference/set-new-handler.md @@ -1,18 +1,18 @@ --- description: "Learn more about: _set_new_handler" title: "_set_new_handler" -ms.date: "4/2/2020" +ms.date: 05/21/2022 api_name: ["_set_new_handler", "_o__set_new_handler"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_new_handler", "set_new_handler"] helpviewer_keywords: ["_set_new_handler function", "set_new_handler function", "error handling", "transferring control to error handler"] ms.assetid: 1d1781b6-5cf8-486a-b430-f365e0bb023f --- -# _set_new_handler +# `_set_new_handler` -Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory. +Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory. The Microsoft C++ compiler uses this function to implement [`std::set_new_handler`](../../standard-library/new-functions.md#set_new_handler) in the standard library. ## Syntax @@ -22,27 +22,25 @@ _PNH _set_new_handler( _PNH pNewHandler ); ### Parameters -*pNewHandler*
-Pointer to the application-supplied memory handling function. An argument of 0 causes the new handler to be removed. +*`pNewHandler`*\ +Pointer to the application-supplied memory handling function. An argument of 0 or `nullptr` causes the new handler to be removed. -## Return Value +## Return value -Returns a pointer to the previous exception handling function registered by **_set_new_handler**, so that the previous function can be restored later. If no previous function has been set, the return value can be used to restore the default behavior; this value can be **NULL**. +Returns a pointer to the previous exception handling function registered by **`_set_new_handler`**, so that the previous function can be restored later. If no previous function has been set, the return value can be used to restore the default behavior. This value can be `nullptr` or 0. ## Remarks -The C++ **_set_new_handler** function specifies an exception-handling function that gains control if the **`new`** operator fails to allocate memory. If **`new`** fails, the run-time system automatically calls the exception-handling function that was passed as an argument to **_set_new_handler**. **_PNH**, defined in New.h, is a pointer to a function that returns type **`int`** and takes an argument of type **size_t**. Use **size_t** to specify the amount of space to be allocated. +The C++ **`_set_new_handler`** function specifies an exception-handling function that gains control if the **`new`** operator fails to allocate memory. If **`new`** fails, the run-time system automatically calls the exception-handling function that was passed as an argument to **`_set_new_handler`**. `_PNH`, defined in ``, is a pointer to a function that returns type **`int`** and takes an argument of type **`size_t`**. Use **`size_t`** to specify the amount of space to be allocated. -There is no default handler. +There's no default handler. -**_set_new_handler** is essentially a garbage-collection scheme. The run-time system retries allocation each time your function returns a nonzero value and fails if your function returns 0. +**`_set_new_handler`** is essentially a garbage-collection scheme. The run-time system retries allocation each time your function returns a nonzero value and fails if your function returns 0. -An occurrence of the **_set_new_handler** function in a program registers the exception-handling function specified in the argument list with the run-time system: +An occurrence of the **`_set_new_handler`** function in a program registers the exception-handling function specified in the argument list with the run-time system: ```cpp -// set_new_handler1.cpp -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). - +// _set_new_handler1.cpp #include int handle_program_memory_depletion( size_t ) @@ -57,7 +55,9 @@ int main( void ) } ``` -You can save the function address that was last passed to the **_set_new_handler** function and reinstate it later: +By default, the **`_set_new_handler`** function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). + +You can save the function address that was last passed to the **`_set_new_handler`** function and reinstate it later: ```cpp _PNH old_handler = _set_new_handler( my_handler ); @@ -68,81 +68,109 @@ You can save the function address that was last passed to the **_set_new_handler // . . . ``` -The C++ [_set_new_mode](set-new-mode.md) function sets the new handler mode for [malloc](malloc.md). The new handler mode indicates whether, on failure, **malloc** is to call the new handler routine as set by **_set_new_handler**. By default, **malloc** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **malloc** fails to allocate memory, **malloc** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call: +The C++ [`_set_new_mode`](set-new-mode.md) function sets the new handler mode for [`malloc`](malloc.md). The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by **`_set_new_handler`**. By default, **`malloc`** doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`malloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call `_set_new_mode(1);` early in your program or link with *`newmode.obj`*. -```cpp -_set_new_mode(1); -``` +If a user-defined `operator new` is provided, the new handler functions aren't automatically called on failure. -early in your program or link with Newmode.obj. +For more information, see [`new`](../../cpp/new-operator-cpp.md) and [`delete`](../../cpp/delete-operator-cpp.md) in the *C++ Language Reference*. -If a user-defined `operator new` is provided, the new handler functions are not automatically called on failure. - -For more information, see [new](../../cpp/new-operator-cpp.md) and [delete](../../cpp/delete-operator-cpp.md) in the *C++ Language Reference*. - -There is a single **_set_new_handler** handler for all dynamically linked DLLs or executables; even if you call **_set_new_handler** your handler might be replaced by another or that you are replacing a handler set by another DLL or executable. +There's a single **`_set_new_handler`** handler for all dynamically linked DLLs or executables in a single process. Even if you call **`_set_new_handler`**, your handler might be replaced by another. Or, your new handler may replace a handler set by another DLL or executable in your process. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_new_handler**|\| +| Function | Required header | +|--|--| +| **`_set_new_handler`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -In this example, when the allocation fails, control is transferred to MyNewHandler. The argument passed to MyNewHandler is the number of bytes requested. The value returned from MyNewHandler is a flag indicating whether allocation should be retried: a nonzero value indicates that allocation should be retried, and a zero value indicates that allocation has failed. +In this example, when the allocation fails, control is transferred to `MyNewHandler`. The argument passed to `MyNewHandler` is the number of bytes requested. The value returned from `MyNewHandler` is a flag indicating whether allocation should be retried: a nonzero value indicates that allocation should be retried, and a zero value indicates that allocation has failed. ```cpp // crt_set_new_handler.cpp -// compile with: /c -#include +// Build for x86. +// WARNING: This code intentionally allocates memory until an allocation fails. +// Running this code can cause your system to become non-responsive. +#include +#include #include -#define BIG_NUMBER 0x1fffffff -int coalesced = 0; +static const int Big_number = 0x03FFFFFF; + +struct MemoryHog { + int pork[Big_number]; +}; + +class MemoryReserve { + MemoryHog* reserved = nullptr; +public: + MemoryReserve() { + reserved = new MemoryHog(); + } + ~MemoryReserve() noexcept { + if (reserved != nullptr) + delete reserved; + } + bool free_reserve() noexcept { + if (reserved != nullptr) { + delete reserved; + reserved = nullptr; + return true; // return true if memory freed + } + return false; // reserved memory exhausted. + } +}; + +// Global singleton for a MemoryReserve object +static MemoryReserve reserve{}; -int CoalesceHeap() -{ - coalesced = 1; // Flag RecurseAlloc to stop - // do some work to free memory - return 0; -} // Define a function to be called if new fails to allocate memory. -int MyNewHandler( size_t size ) +int MyNewHandler(size_t /* unused */) { - printf("Allocation failed. Coalescing heap.\n"); - - // Call a function to recover some heap space. - return CoalesceHeap(); + // Call a function to recover some heap space. Return 1 on success. + if (reserve.free_reserve()) { + std::cerr << "MyNewHandler: Released reserved memory.\n"; + return 1; + } + std::cerr << "MyNewHandler: Reserved memory exhausted.\n"; + return 0; } -int RecurseAlloc() { - int *pi = new int[BIG_NUMBER]; - if (!coalesced) - RecurseAlloc(); - return 0; +static const int max_depth = 16; // recursion depth limiter +static int depth = 0; + +void RecurseAlloc() { + MemoryHog* piggy = new MemoryHog{}; + if (++depth < max_depth) // Recurse until memory exhausted or max_depth + RecurseAlloc(); + depth--; + delete piggy; + return; } int main() { - // Set the failure handler for new to be MyNewHandler. - _set_new_handler( MyNewHandler ); - RecurseAlloc(); + try { + _set_new_handler(MyNewHandler); // Set handler for new. + RecurseAlloc(); + } + catch (std::bad_alloc& ex) { + std::cerr << "bad_alloc caught: " << ex.what() << '\n'; + } } -``` - -```Output -Allocation failed. Coalescing heap. -This application has requested the Runtime to terminate it in an unusual way. -Please contact the application's support team for more information. +/* Output: +MyNewHandler: Released reserved memory. +MyNewHandler: Reserved memory exhausted. +bad_alloc caught: bad allocation +*/ ``` ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[realloc](realloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`realloc`](realloc.md) diff --git a/docs/c-runtime-library/reference/set-new-mode.md b/docs/c-runtime-library/reference/set-new-mode.md index a6f89b2231..ab84d28e69 100644 --- a/docs/c-runtime-library/reference/set-new-mode.md +++ b/docs/c-runtime-library/reference/set-new-mode.md @@ -3,16 +3,16 @@ description: "Learn more about: _set_new_mode" title: "_set_new_mode" ms.date: "4/2/2020" api_name: ["_set_new_mode", "_o__set_new_mode"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_new_mode", "_set_new_mode"] helpviewer_keywords: ["handler modes", "_set_new_mode function", "set_new_mode function"] ms.assetid: 4d14039a-e54e-4689-8c70-74a4b9834768 --- -# _set_new_mode +# `_set_new_mode` -Sets a new handler mode for **malloc**. +Sets a **`new`** handler mode for `malloc`. ## Syntax @@ -22,40 +22,40 @@ int _set_new_mode( int newhandlermode ); ### Parameters -*newhandlermode*
-New handler mode for **malloc**; valid value is 0 or 1. +*`newhandlermode`*\ +**`new`** handler mode for `malloc`; valid value is 0 or 1. -## Return Value +## Return value -Returns the previous handler mode set for **malloc**. A return value of 1 indicates that, on failure to allocate memory, **malloc** previously called the new handler routine; a return value of 0 indicates that it did not. If the *newhandlermode* argument does not equal 0 or 1, returns -1. +Returns the previous handler mode set for `malloc`. A return value of 1 indicates that, on failure to allocate memory, `malloc` previously called the **`new`** handler routine; a return value of 0 indicates that it didn't. If the *`newhandlermode`* argument doesn't equal 0 or 1, returns -1. ## Remarks -The C++ **_set_new_mode** function sets the new handler mode for [malloc](malloc.md). The new handler mode indicates whether, on failure, **malloc** is to call the new handler routine as set by [_set_new_handler](set-new-handler.md). By default, **malloc** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **malloc** fails to allocate memory, **malloc** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. For more information, see the [new](../../cpp/new-operator-cpp.md) and [delete](../../cpp/delete-operator-cpp.md) operators in the *C++ Language Reference*. To override the default, call: +The C++ **`_set_new_mode`** function sets the **`new`** handler mode for [`malloc`](malloc.md). The **`new`** handler mode indicates whether, on failure, `malloc` is to call the **`new`** handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, `malloc` doesn't call the **`new`** handler routine on failure to allocate memory. You can override this default behavior so that, when `malloc` fails to allocate memory, `malloc` calls the **`new`** handler routine in the same way that the **`new`** operator does when it fails for the same reason. For more information, see the [`new`](../../cpp/new-operator-cpp.md) and [`delete`](../../cpp/delete-operator-cpp.md) operators in the *C++ Language Reference*. To override the default, call: ```cpp _set_new_mode(1); ``` -early in your program or link with Newmode.obj (see [Link Options](../../c-runtime-library/link-options.md)). +early in your program or link with Newmode.obj (see [Link options](../link-options.md)). -This function validates its parameter. If *newhandlermode* is anything other than 0 or 1, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, _set_new_mode returns -1 and sets **errno** to `EINVAL`. +This function validates its parameter. If *`newhandlermode`* is anything other than 0 or 1, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, _set_new_mode returns -1 and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_new_mode**|\| +| Routine | Required header | +|---|---| +| **`_set_new_mode`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[realloc](realloc.md)
-[_query_new_handler](query-new-handler.md)
-[_query_new_mode](query-new-mode.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`realloc`](realloc.md)\ +[`_query_new_handler`](query-new-handler.md)\ +[`_query_new_mode`](query-new-mode.md) diff --git a/docs/c-runtime-library/reference/set-printf-count-output.md b/docs/c-runtime-library/reference/set-printf-count-output.md index 1ca1c0c4bb..dece4a5147 100644 --- a/docs/c-runtime-library/reference/set-printf-count-output.md +++ b/docs/c-runtime-library/reference/set-printf-count-output.md @@ -10,9 +10,9 @@ f1_keywords: ["set_printf_count_output", "_set_printf_count_output"] helpviewer_keywords: ["%n format", "set_printf_count_output function", "_set_printf_count_output function"] ms.assetid: d8259ec5-764e-42d0-9169-72172e95163b --- -# _set_printf_count_output +# `_set_printf_count_output` -Enable or disable support of the **%n** format in [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)-family functions. +Enable or disable support of the **%n** format in [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)-family functions. ## Syntax @@ -24,24 +24,24 @@ int _set_printf_count_output( ### Parameters -*enable*
+*`enable`*\ A non-zero value to enable **%n** support, 0 to disable **%n** support. -## Property Value/Return Value +## Property value or return value The state of **%n** support before calling this function: non-zero if **%n** support was enabled, 0 if it was disabled. ## Remarks -Because of security reasons, support for the **%n** format specifier is disabled by default in **printf** and all its variants. If **%n** is encountered in a **printf** format specification, the default behavior is to invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). Calling **_set_printf_count_output** with a non-zero argument will cause **printf**-family functions to interpret **%n** as described in [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +Because of security reasons, support for the **%n** format specifier is disabled by default in `printf` and all its variants. If **%n** is encountered in a `printf` format specification, the default behavior is to invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). Calling **`_set_printf_count_output`** with a non-zero argument will cause `printf`-family functions to interpret **%n** as described in [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_printf_count_output**|\| +| Routine | Required header | +|---|---| +| **`_set_printf_count_output`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -72,4 +72,4 @@ i = 5 ## See also -[_get_printf_count_output](get-printf-count-output.md)
+[`_get_printf_count_output`](get-printf-count-output.md) diff --git a/docs/c-runtime-library/reference/set-se-translator.md b/docs/c-runtime-library/reference/set-se-translator.md index d44f75d74a..a52026c5df 100644 --- a/docs/c-runtime-library/reference/set-se-translator.md +++ b/docs/c-runtime-library/reference/set-se-translator.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _set_se_translator" title: "_set_se_translator" +description: "Learn more about: _set_se_translator" ms.date: "1/14/2021" api_name: ["_set_se_translator"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_se_translator", "set_se_translator"] helpviewer_keywords: ["set_se_translator function", "exception handling, changing", "_set_se_translator function"] -ms.assetid: 280842bc-d72a-468b-a565-2d3db893ae0f --- # `_set_se_translator` @@ -27,7 +26,7 @@ _se_translator_function _set_se_translator( *`seTransFunction`*\ Pointer to a C structured exception translator function that you write. -## Return Value +## Return value Returns a pointer to the previous translator function registered by **`_set_se_translator`**, so that the previous function can be restored later. If no previous function has been set, the return value can be used to restore the default behavior; this value can be **`nullptr`**. @@ -35,35 +34,35 @@ Returns a pointer to the previous translator function registered by **`_set_se_t The **`_set_se_translator`** function provides a way to handle Win32 exceptions (C structured exceptions) as C++ typed exceptions. To allow each C exception to be handled by a C++ **`catch`** handler, first define a C exception wrapper class that can be used, or derived from, to attribute a specific class type to a C exception. To use this class, install a custom C exception translator function that is called by the internal exception-handling mechanism each time a C exception is raised. Within your translator function, you can throw any typed exception that can be caught by a matching C++ **`catch`** handler. -You must use [`/EHa`](../../build/reference/eh-exception-handling-model.md) when using **_set_se_translator**. +You must use the [`/EHa`](../../build/reference/eh-exception-handling-model.md) option when you use **`_set_se_translator`**. To specify a custom translation function, call **`_set_se_translator`** using the name of your translation function as its argument. The translator function that you write is called once for each function invocation on the stack that has **`try`** blocks. There's no default translator function. -Your translator function should do no more than throw a C++ typed exception. If it does anything in addition to throwing (such as writing to a log file, for example) your program might not behave as expected because the number of times the translator function is invoked is platform-dependent. +Your translator function should do no more than throw a C++ typed exception. If it does anything in addition to throwing (such as writing to a log file, for example) your program might not behave as expected because the number of invocations of the translator function is platform-dependent. In a multithreaded environment, translator functions are maintained separately for each thread. Each new thread needs to install its own translator function. Thus, each thread is in charge of its own translation handling. **`_set_se_translator`** is specific to one thread--another DLL can install a different translation function. -The *seTransFunction* function that you write must be a native-compiled function (not compiled with /clr). It must take an unsigned integer and a pointer to a Win32 **`_EXCEPTION_POINTERS`** structure as arguments. The arguments are the return values of calls to the Win32 API **`GetExceptionCode`** and **`GetExceptionInformation`** functions, respectively. +The *`seTransFunction`* function that you write must be a native-compiled function (not compiled with `/clr`). It must take an unsigned integer and a pointer to a Win32 `_EXCEPTION_POINTERS` structure as arguments. The arguments are the return values of calls to the Win32 API `GetExceptionCode` and `GetExceptionInformation` functions, respectively. ```cpp typedef void (__cdecl *_se_translator_function)(unsigned int, struct _EXCEPTION_POINTERS* ); ``` -For **_set_se_translator**, there are implications when dynamically linking to the CRT; another DLL in the process might call **_set_se_translator** and replace your handler with its own. +For **`_set_se_translator`**, there are implications when dynamically linking to the CRT; another DLL in the process might call **`_set_se_translator`** and replace your handler with its own. -When using **_set_se_translator** from managed code (code compiled with /clr) or mixed native and managed code, be aware that the translator affects exceptions generated in native code only. Any managed exceptions generated in managed code (such as when raising `System::Exception`) aren't routed through the translator function. Exceptions raised in managed code using the Win32 function **RaiseException** or caused by a system exception like a divide by zero exception are routed through the translator. +When you use **`_set_se_translator`** from managed code (code compiled with `/clr`) or mixed native and managed code, the translator affects exceptions generated in native code only. Any managed exceptions generated in managed code (such as when raising `System::Exception`) aren't routed through the translator function. Exceptions raised in managed code using the Win32 function `RaiseException` or caused by a system exception like a divide by zero exception are routed through the translator. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_se_translator**|\| +| Routine | Required header | +|---|---| +| **`_set_se_translator`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -## Example: Catch __try exception error +## Example: Catch `__try` exception error -This sample wraps the calls to set a structured exception translator and to restore the old one in an RAII class, `Scoped_SE_Translator`. This class lets you introduce a scope-specific translator as a single declaration. The class destructor restores the original translator when control leaves the scope. +This sample wraps the calls to set a structured exception translator and to restore the old one in an `RAII` class, `Scoped_SE_Translator`. This class lets you introduce a scope-specific translator as a single declaration. The class destructor restores the original translator when control leaves the scope. ```cpp // crt_settrans.cpp @@ -134,9 +133,9 @@ In __finally Caught a __try exception, error c0000094. ``` -## Example: Catch SE_Exception error +## Example: Catch `SE_Exception` error -Although the functionality provided by **_set_se_translator** isn't available in managed code, it's possible to use this mapping in native code, even if that native code is in a compilation under the **/clr** switch, as long as the native code is indicated using `#pragma unmanaged`. If a structured exception is being thrown in managed code that is to be mapped, the code that generates and handles the exception must be marked `#pragma unmanaged`. The following code shows a possible use. For more information, see [Pragma Directives and the __Pragma Keyword](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). +Although the functionality provided by **`_set_se_translator`** isn't available in managed code, it's possible to use this mapping in native code, even if that native code is in a compilation under the **`/clr`** switch, as long as the native code is indicated using `#pragma unmanaged`. If a structured exception is being thrown in managed code that is to be mapped, the code that generates and handles the exception must be marked `#pragma unmanaged`. The following code shows a possible use. For more information, see [Pragma directives and the `__pragma` and `_Pragma` keywords](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). ```cpp // crt_set_se_translator_clr.cpp @@ -209,8 +208,8 @@ Caught SE_Exception, error c0000094 ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)\ +[Exception handling routines](../exception-handling-routines.md)\ [`set_terminate`](set-terminate-crt.md)\ [`set_unexpected`](set-unexpected-crt.md)\ [`terminate`](terminate-crt.md)\ -[`unexpected`](unexpected-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/set-sse2-enable.md b/docs/c-runtime-library/reference/set-sse2-enable.md index 518a2c9282..abf620f2a6 100644 --- a/docs/c-runtime-library/reference/set-sse2-enable.md +++ b/docs/c-runtime-library/reference/set-sse2-enable.md @@ -10,9 +10,9 @@ f1_keywords: ["_set_SSE2_enable", "set_SSE2_enable"] helpviewer_keywords: ["_set_SSE2_enable function", "Streaming SIMD Extensions 2 instructions", "set_SSE2_enable function"] ms.assetid: 55db895d-fc1e-475a-9110-b781a9bb51c5 --- -# _set_SSE2_enable +# `_set_SSE2_enable` -Enables or disables the use of Streaming SIMD Extensions 2 (SSE2) instructions in CRT math routines. (This function is not available on x64 architectures because SSE2 is enabled by default.) +Enables or disables the use of Streaming SIMD Extensions 2 (SSE2) instructions in CRT math routines. (This function isn't available on x64 architectures because SSE2 is enabled by default.) ## Syntax @@ -24,47 +24,47 @@ int _set_SSE2_enable( ### Parameters -*flag*
+*`flag`*\ 1 to enable the SSE2 implementation; 0 to disable the SSE2 implementation. By default, SSE2 implementation is enabled on processors that support it. -## Return Value +## Return value Nonzero if SSE2 implementation is enabled; zero if SSE2 implementation is disabled. ## Remarks -The following functions have SSE2 implementations that can be enabled by using **_set_SSE2_enable**: +The following functions have SSE2 implementations that can be enabled by using **`_set_SSE2_enable`**: -- [atan](atan-atanf-atanl-atan2-atan2f-atan2l.md) +- [`atan`](atan-atanf-atanl-atan2-atan2f-atan2l.md) -- [ceil](ceil-ceilf-ceill.md) +- [`ceil`](ceil-ceilf-ceill.md) -- [exp](exp-expf.md) +- [`exp`](exp-expf.md) -- [floor](floor-floorf-floorl.md) +- [`floor`](floor-floorf-floorl.md) -- [log](log-logf-log10-log10f.md) +- [`log`](log-logf-log10-log10f.md) -- [log10](log-logf-log10-log10f.md) +- [`log10`](log-logf-log10-log10f.md) -- [modf](modf-modff-modfl.md) +- [`modf`](modf-modff-modfl.md) -- [pow](pow-powf-powl.md) +- [`pow`](pow-powf-powl.md) -The SSE2 implementations of these functions might give slightly different answers than the default implementations, because SSE2 intermediate values are 64-bit floating-point quantities but the default implementation intermediate values are 80-bit floating-point quantities. +The SSE2 implementations of these functions might give slightly different answers than the default implementations. SSE2 intermediate values are 64-bit floating-point quantities, but the default implementation intermediate values are 80-bit floating-point quantities. > [!NOTE] -> If you use the [/Oi (Generate Intrinsic Functions)](../../build/reference/oi-generate-intrinsic-functions.md) compiler option to compile the project, it may appear that **_set_SSE2_enable** has no effect. The **/Oi** compiler option gives the compiler the authority to use intrinsics to replace CRT calls; this behavior overrides the effect of **_set_SSE2_enable**. If you want to guarantee that **/Oi** does not override **_set_SSE2_enable**, use **/Oi-** to compile your project. This might also be good practice when you use other compiler switches that imply **/Oi**. +> If you use the [/Oi (Generate Intrinsic Functions)](../../build/reference/oi-generate-intrinsic-functions.md) compiler option to compile the project, it may appear that **`_set_SSE2_enable`** has no effect. The **/Oi** compiler option gives the compiler the authority to use intrinsics to replace CRT calls; this behavior overrides the effect of **`_set_SSE2_enable`**. If you want to guarantee that **/Oi** does not override **`_set_SSE2_enable`**, use **/Oi-** to compile your project. This might also be good practice when you use other compiler switches that imply **/Oi**. -The SSE2 implementation is only used if all exceptions are masked. Use [_control87, _controlfp](control87-controlfp-control87-2.md) to mask exceptions. +The SSE2 implementation is only used if all exceptions are masked. Use [`_control87`, `_controlfp`](control87-controlfp-control87-2.md) to mask exceptions. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_SSE2_enable**|\| +| Routine | Required header | +|---|---| +| **`_set_SSE2_enable`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,4 +91,4 @@ SSE2 enabled. ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../crt-library-features.md) diff --git a/docs/c-runtime-library/reference/set-terminate-crt.md b/docs/c-runtime-library/reference/set-terminate-crt.md index 446313ddbe..24be5c6068 100644 --- a/docs/c-runtime-library/reference/set-terminate-crt.md +++ b/docs/c-runtime-library/reference/set-terminate-crt.md @@ -3,16 +3,16 @@ description: "Learn more about: set_terminate (CRT)" title: "set_terminate (CRT)" ms.date: "4/2/2020" api_name: ["set_terminate", "_o_set_terminate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_terminate"] helpviewer_keywords: ["set_terminate function", "terminate function", "exception handling, termination"] ms.assetid: 3ff1456a-7898-44bc-9266-a328a80b6006 --- -# set_terminate (CRT) +# `set_terminate` (CRT) -Installs your own termination routine to be called by **terminate**. +Installs your own termination routine to be called by `terminate`. ## Syntax @@ -22,49 +22,49 @@ terminate_function set_terminate( terminate_function termFunction ); ### Parameters -*termFunction*
+*`termFunction`*\ Pointer to a terminate function that you write. -## Return Value +## Return value -Returns a pointer to the previous function registered by **set_terminate** so that the previous function can be restored later. If no previous function has been set, the return value may be used to restore the default behavior; this value may be **NULL**. +Returns a pointer to the previous function registered by **`set_terminate`** so that the previous function can be restored later. If no previous function has been set, the return value may be used to restore the default behavior; this value may be `NULL`. ## Remarks -The **set_terminate** function installs *termFunction* as the function called by **terminate**. **set_terminate** is used with C++ exception handling and may be called at any point in your program before the exception is thrown. **terminate** calls [abort](abort.md) by default. You can change this default by writing your own termination function and calling **set_terminate** with the name of your function as its argument. **terminate** calls the last function given as an argument to **set_terminate**. After performing any desired cleanup tasks, *termFunction* should exit the program. If it does not exit (if it returns to its caller), [abort](abort.md) is called. +The **`set_terminate`** function installs *`termFunction`* as the function called by `terminate`. **`set_terminate`** is used with C++ exception handling and may be called at any point in your program before the exception is thrown. `terminate` calls [`abort`](abort.md) by default. You can change this default by writing your own termination function and calling **`set_terminate`** with the name of your function as its argument. `terminate` calls the last function given as an argument to **`set_terminate`**. After it performs any desired cleanup tasks, *`termFunction`* should exit the program. If it doesn't exit (if it returns to its caller), [`abort`](abort.md) is called. In a multithreaded environment, terminate functions are maintained separately for each thread. Each new thread needs to install its own terminate function. Thus, each thread is in charge of its own termination handling. -The **terminate_function** type is defined in EH.H as a pointer to a user-defined termination function, *termFunction* that returns **`void`**. Your custom function *termFunction* can take no arguments and should not return to its caller. If it does, [abort](abort.md) is called. An exception may not be thrown from within *termFunction*. +The `terminate_function` type is defined in EH.H as a pointer to a user-defined termination function, *`termFunction`* that returns **`void`**. Your custom function *`termFunction`* can take no arguments and shouldn't return to its caller. If it does, [`abort`](abort.md) is called. An exception may not be thrown from within *`termFunction`*. ```cpp typedef void ( *terminate_function )( ); ``` > [!NOTE] -> The **set_terminate** function only works outside the debugger. +> The **`set_terminate`** function only works outside the debugger. -There is a single **set_terminate** handler for all dynamically linked DLLs or EXEs; even if you call **set_terminate** your handler may be replaced by another, or you may be replacing a handler set by another DLL or EXE. +There's a single **`set_terminate`** handler for all dynamically linked DLLs or EXEs; even if you call **`set_terminate`** your handler may be replaced by another, or you may be replacing a handler set by another DLL or EXE. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**set_terminate**|\| +| Routine | Required header | +|---|---| +| **`set_terminate`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [terminate](terminate-crt.md). +See the example for [`terminate`](terminate-crt.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[_get_terminate](get-terminate.md)
-[set_unexpected](set-unexpected-crt.md)
-[terminate](terminate-crt.md)
-[unexpected](unexpected-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`_get_terminate`](get-terminate.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`terminate`](terminate-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/set-unexpected-crt.md b/docs/c-runtime-library/reference/set-unexpected-crt.md index e77638ac30..8b5ee60a84 100644 --- a/docs/c-runtime-library/reference/set-unexpected-crt.md +++ b/docs/c-runtime-library/reference/set-unexpected-crt.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: set_unexpected (CRT)" title: "set_unexpected (CRT)" +description: "Learn more about: set_unexpected (CRT)" ms.date: "1/14/2021" api_name: ["set_unexpected"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_unexpected"] helpviewer_keywords: ["set_unexpected function", "unexpected function", "exception handling, termination"] -ms.assetid: ebcef032-4771-48e5-88aa-2a1ab8750aa6 --- # `set_unexpected` (CRT) @@ -25,13 +24,13 @@ unexpected_function set_unexpected( unexpected_function unexpFunction ); *`unexpFunction`*\ Pointer to a function that you write to replace the **`unexpected`** function. -## Return Value +## Return value -Returns a pointer to the previous termination function registered by **`_set_unexpected`** so that the previous function can be restored later. If no previous function has been set, the return value may be used to restore the default behavior; this value may be **`NULL`**. +Returns a pointer to the previous termination function registered by **`_set_unexpected`** so that the previous function can be restored later. If no previous function has been set, the return value may be used to restore the default behavior; this value may be `NULL`. ## Remarks -The **`set_unexpected`** function installs *unexpFunction* as the function called by **`unexpected`**. **`unexpected`** is not used in the current C++ exception-handling implementation. The **`unexpected_function`** type is defined in EH.H as a pointer to a user-defined unexpected function, *unexpFunction* that returns **`void`**. Your custom *unexpFunction* function should not return to its caller. +The **`set_unexpected`** function installs *`unexpFunction`* as the function called by **`unexpected`**. **`unexpected`** isn't used in the current C++ exception-handling implementation. The **`unexpected_function`** type is defined in EH.H as a pointer to a user-defined unexpected function, *`unexpFunction`* that returns **`void`**. Your custom *`unexpFunction`* function shouldn't return to its caller. ```cpp typedef void ( *unexpected_function )( ); @@ -43,23 +42,23 @@ Unlike the custom termination function installed by a call to **`set_terminate`* In a multithreaded environment, unexpected functions are maintained separately for each thread. Each new thread needs to install its own unexpected function. Thus, each thread is in charge of its own unexpected handling. -In the current Microsoft implementation of C++ exception handling, **`unexpected`** calls **`terminate`** by default and is never called by the exception-handling run-time library. There is no particular advantage to calling **`unexpected`** rather than **`terminate`**. +In the current Microsoft implementation of C++ exception handling, **`unexpected`** calls **`terminate`** by default and is never called by the exception-handling run-time library. There's no particular advantage to calling **`unexpected`** rather than **`terminate`**. -There is a single **`set_unexpected`** handler for all dynamically linked DLLs or EXEs; even if you call **`set_unexpected`** your handler may be replaced by another or that you are replacing a handler set by another DLL or EXE. +There's a single **`set_unexpected`** handler for all dynamically linked DLLs or EXEs; even if you call **`set_unexpected`** your handler may be replaced by another or that you're replacing a handler set by another DLL or EXE. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`set_unexpected`**|``| +| Routine | Required header | +|---|---| +| **`set_unexpected`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)\ +[Exception handling routines](../exception-handling-routines.md)\ [`abort`](abort.md)\ [`_get_unexpected`](get-unexpected.md)\ [`set_terminate`](set-terminate-crt.md)\ [`terminate`](terminate-crt.md)\ -[`unexpected`](unexpected-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/setbuf.md b/docs/c-runtime-library/reference/setbuf.md index 7905273cef..119e609b2d 100644 --- a/docs/c-runtime-library/reference/setbuf.md +++ b/docs/c-runtime-library/reference/setbuf.md @@ -3,16 +3,16 @@ description: "Learn more about: setbuf" title: "setbuf" ms.date: "4/2/2020" api_name: ["setbuf", "_o_setbuf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setbuf"] helpviewer_keywords: ["setbuf function", "stream buffering"] ms.assetid: 13beda22-7b56-455d-8a6c-f2eb636885b9 --- -# setbuf +# `setbuf` -Controls stream buffering. This function is deprecated; use [setvbuf](setvbuf.md) instead. +Controls stream buffering. This function is deprecated; use [`setvbuf`](setvbuf.md) instead. ## Syntax @@ -25,27 +25,27 @@ void setbuf( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*buffer*
+*`buffer`*\ User-allocated buffer. ## Remarks -The **setbuf** function controls buffering for *stream*. The *stream* argument must refer to an open file that hasn't been read or written. If the *buffer* argument is **NULL**, the stream is unbuffered. If not, the buffer must point to a character array of length **BUFSIZ**, where **BUFSIZ** is the buffer size as defined in STDIO.H. The user-specified buffer, instead of the default system-allocated buffer for the given stream, is used for I/O buffering. The **stderr** stream is unbuffered by default, but you can use **setbuf** to assign buffers to **stderr**. +The **`setbuf`** function controls buffering for *`stream`*. The *`stream`* argument must refer to an open file that hasn't been read or written. If the *`buffer`* argument is `NULL`, the stream is unbuffered. If not, the buffer must point to a character array of length `BUFSIZ`, where `BUFSIZ` is the buffer size as defined in STDIO.H. The user-specified buffer, instead of the default system-allocated buffer for the given stream, is used for I/O buffering. The `stderr` stream is unbuffered by default, but you can use **`setbuf`** to assign buffers to `stderr`. -**setbuf** has been replaced by [setvbuf](setvbuf.md), which is the preferred routine for new code. Unlike **setvbuf**, **setbuf** has no way of reporting errors. **setvbuf** also lets you control both the buffering mode and the buffer size. **setbuf** exists for compatibility with existing code. +**`setbuf`** has been replaced by [`setvbuf`](setvbuf.md), which is the preferred routine for new code. Unlike `setvbuf`, **`setbuf`** has no way of reporting errors. `setvbuf` also lets you control both the buffering mode and the buffer size. **`setbuf`** exists for compatibility with existing code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**setbuf**|\| +| Routine | Required header | +|---|---| +| **`setbuf`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,8 +88,8 @@ stream2 buffering disabled ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[fflush](fflush.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`fflush`](fflush.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/setjmp.md b/docs/c-runtime-library/reference/setjmp.md index ad4a103540..bee226945b 100644 --- a/docs/c-runtime-library/reference/setjmp.md +++ b/docs/c-runtime-library/reference/setjmp.md @@ -3,7 +3,7 @@ title: "setjmp" description: "API reference for setjmp; which saves the current state of the program." ms.date: "1/14/2021" api_name: ["setjmp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setjmp"] @@ -27,9 +27,9 @@ int setjmp( *`env`*\ Variable in which environment is stored. -## Return Value +## Return value -Returns 0 after saving the stack environment. If **`setjmp`** returns because of a `longjmp` call, it returns the *value* argument of `longjmp`, or if the *value* argument of `longjmp` is 0, **`setjmp`** returns 1. There's no error return. +Returns 0 after saving the stack environment. If **`setjmp`** returns because of a `longjmp` call, it returns the *`value`* argument of `longjmp`, or if the *`value`* argument of `longjmp` is 0, **`setjmp`** returns 1. There's no error return. ## Remarks @@ -53,11 +53,11 @@ For more information, see [Using `setjmp` and `longjmp`](../../cpp/using-setjmp- ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`setjmp`**|\| +| Routine | Required header | +|---|---| +| **`setjmp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -65,5 +65,5 @@ See the example for [`_fpreset`](fpreset.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`longjmp`](longjmp.md) diff --git a/docs/c-runtime-library/reference/setlocale-wsetlocale.md b/docs/c-runtime-library/reference/setlocale-wsetlocale.md index 7b970bab45..99991d91a3 100644 --- a/docs/c-runtime-library/reference/setlocale-wsetlocale.md +++ b/docs/c-runtime-library/reference/setlocale-wsetlocale.md @@ -1,9 +1,9 @@ --- title: "setlocale, _wsetlocale" description: "Describes the Microsoft C runtime (CRT) library functions setlocale and _wsetlocale." -ms.date: "6/8/2021" +ms.date: 01/04/2024 api_name: ["_wsetlocale", "setlocale", "_o__wsetlocale", "_o_setlocale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wsetlocale", "_tsetlocale", "setlocale"] @@ -12,7 +12,7 @@ no-loc: [setlocale, _wsetlocale] --- # `setlocale`, `_wsetlocale` -Sets or retrieves the run-time locale. +Set or retrieve the run-time locale. ## Syntax @@ -21,6 +21,7 @@ char *setlocale( int category, const char *locale ); + wchar_t *_wsetlocale( int category, const wchar_t *locale @@ -37,9 +38,20 @@ Locale specifier. ## Return value -If a valid *`locale`* and *`category`* are given, returns a pointer to the string associated with the specified *`locale`* and *`category`*. If the *`locale`* or *`category`* isn't valid, returns a null pointer, and the current locale settings of the program are unchanged. +If a valid *`locale`* and *`category`* are given, the functions return a pointer to the string associated with the specified *`locale`* and *`category`*. +If the *`locale`* argument is `NULL`, the functions return the current locale. + +If an invalid argument is passed to either function, the return value is `NULL`. +The behavior for invalid arguments is as follows: + +|Function | Invalid parameter | Invalid handler invoked as described in [Parameter validation](../parameter-validation.md)| Sets `errno` | +|---------|---------|---------| +| `setlocale` | *`category`* | yes | yes | +| `setlocale` | *`locale`* | no | no | +| `_wsetlocale` | *`category`* | yes | yes | +| `_wsetlocale` | *`locale`* | no | no | -For example, the call +The call: ```C setlocale( LC_ALL, "en-US" ); @@ -51,44 +63,44 @@ sets all categories, returning only the string en-US ``` -You can copy the string returned by `setlocale` to restore that part of the program's locale information. Global or thread local storage is used for the string returned by `setlocale`. Later calls to `setlocale` overwrite the string, which invalidates string pointers returned by earlier calls. +You can copy the string returned by **`setlocale`** to restore that part of the program's locale information. Global or thread local storage is used for the string returned by **`setlocale`**. Later calls to **`setlocale`** overwrite the string, which invalidates string pointers returned by earlier calls. ## Remarks -Use the `setlocale` function to set, change, or query some or all of the current program locale information specified by *`locale`* and *`category`*. *`locale`* refers to the locality (country/region and language) for which you can customize certain aspects of your program. Some locale-dependent categories include the formatting of dates and the display format for monetary values. If you set *`locale`* to the default string for a language that has multiple forms supported on your computer, you should check the `setlocale` return value to see which language is in effect. For example, if you set *`locale`* to "chinese" the return value could be either "chinese-simplified" or "chinese-traditional". +Use the **`setlocale`** function to set, change, or query some or all of the current program locale information specified by *`locale`* and *`category`*. *`locale`* refers to the locality (country/region and language) for which you can customize certain aspects of your program. Some locale-dependent categories include the formatting of dates and the display format for monetary values. If you set *`locale`* to the default string for a language that has multiple forms supported on your computer, you should check the **`setlocale`** return value to see which language is in effect. For example, if you set *`locale`* to `"chinese"` the return value could be either `"chinese-simplified"` or `"chinese-traditional"`. -`_wsetlocale` is a wide-character version of `setlocale`; the *`locale`* argument and return value of `_wsetlocale` are wide-character strings. `_wsetlocale` and `setlocale` behave identically otherwise. +**`_wsetlocale`** is a wide-character version of **`setlocale`**; the *`locale`* argument and return value of **`_wsetlocale`** are wide-character strings. **`_wsetlocale`** and **`setlocale`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tsetlocale`|`setlocale`|`setlocale`|`_wsetlocale`| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsetlocale` | **`setlocale`** | **`setlocale`** | **`_wsetlocale`** | The *`category`* argument specifies the parts of a program's locale information that are affected. The macros used for *`category`* and the parts of the program they affect are as follows: -|*category* flag|Affects| -|-|-| +| *`category`* flag | Affects | +|---|---| | `LC_ALL` | All categories, as listed below. | | `LC_COLLATE` | The `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll`, and `wcsxfrm` functions. | | `LC_CTYPE` | The character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected). | | `LC_MONETARY` | Monetary-formatting information returned by the `localeconv` function. | -| `LC_NUMERIC` | Decimal-point character for the formatted output routines (such as `printf`), for the data-conversion routines, and for the non-monetary formatting information returned by `localeconv`. In addition to the decimal-point character, `LC_NUMERIC` sets the thousands separator and the grouping control string returned by [`localeconv`](localeconv.md). | +| `LC_NUMERIC` | Decimal-point character for the formatted output routines (such as `printf`), for the data-conversion routines, and for the nonmonetary formatting information returned by `localeconv`. In addition to the decimal-point character, `LC_NUMERIC` sets the thousands separator and the grouping control string returned by [`localeconv`](localeconv.md). | | `LC_TIME` | The `strftime` and `wcsftime` functions. | -This function validates the category parameter. If the category parameter isn't one of the values given in the previous table, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns `NULL`. +This function validates the category parameter. If the category parameter isn't one of the values given in the previous table, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns `NULL`. -The *`locale`* argument is a pointer to a string that specifies the locale. For information about the format of the *`locale`* argument, see [Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md). If *`locale`* points to an empty string, the locale is the implementation-defined native environment. A value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that all `char` data types are 1 byte and that their value is always less than 256. +The *`locale`* argument is a pointer to a string that specifies the locale. For information about the format of the *`locale`* argument, see [Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md). If *`locale`* points to an empty string, the locale is the implementation-defined native environment. A value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that all `char` data types are 1 byte and that their value is always less than 256. At program startup, the equivalent of the following statement is executed: `setlocale( LC_ALL, "C" );` -The *`locale`* argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. The set of available locale names, languages, country/region codes, and code pages includes all those supported by the Windows NLS API. The set of locale names supported by `setlocale` are described in [Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md). The set of language and country/region strings supported by `setlocale` are listed in [Language Strings](../../c-runtime-library/language-strings.md) and [Country/Region Strings](../../c-runtime-library/country-region-strings.md). We recommend the locale name form for performance and for maintainability of locale strings embedded in code or serialized to storage. The locale name strings are less likely to be changed by an operating system update than the language and country/region name form. +The *`locale`* argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. The available locale names, languages, country/region codes, and code pages include all the ones supported by the Windows NLS API. The set of locale names supported by **`setlocale`** is described in [Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md). The set of language and country/region strings supported by **`setlocale`** are listed in [Language strings](../language-strings.md) and [Country/Region strings](../country-region-strings.md). We recommend the locale name form for performance and for maintainability of locale strings embedded in code or serialized to storage. The locale name strings are less likely to be changed by an operating system update than the language and country/region name form. -A null pointer that's passed as the *`locale`* argument tells `setlocale` to query instead of to set the international environment. If the *`locale`* argument is a null pointer, the program's current locale setting isn't changed. Instead, `setlocale` returns a pointer to the string that's associated with the *`category`* of the thread's current locale. If the *`category`* argument is `LC_ALL`, the function returns a string that indicates the current setting of each category, separated by semicolons. For example, the sequence of calls +A null pointer that's passed as the *`locale`* argument tells **`setlocale`** to query instead of to set the international environment. If the *`locale`* argument is a null pointer, the program's current locale setting isn't changed. Instead, **`setlocale`** returns a pointer to the string that's associated with the *`category`* of the thread's current locale. If the *`category`* argument is `LC_ALL`, the function returns a string that indicates the current setting of each category, separated by semicolons. For example, the sequence of calls ```C // Set all categories and return "en-US" @@ -144,7 +156,7 @@ The following examples pertain to the `LC_ALL` category. Either of the strings " - `setlocale( LC_ALL, "" );` - Sets the locale to the language that's indicated by *``*, and uses the default country/region for the specified language and the user-default ANSI code page for that country/region as obtained from the host operating system. For example, the following calls to `setlocale` are functionally equivalent: + Sets the locale to the language that's indicated by *``*, and uses the default country/region for the specified language and the user-default ANSI code page for that country/region as obtained from the host operating system. For example, the following calls to **`setlocale`** are functionally equivalent: `setlocale( LC_ALL, "en-US" );` @@ -158,7 +170,7 @@ The following examples pertain to the `LC_ALL` category. Either of the strings " Sets the code page to the value indicated by *``*, together with the default country/region and language (as defined by the host operating system) for the specified code page. -The category must be either `LC_ALL` or `LC_CTYPE` to effect a change of code page. For example, if the default country/region and language of the host operating system are "`United States`" and "`English`", the following two calls to `setlocale` are functionally equivalent: +The category must be either `LC_ALL` or `LC_CTYPE` to effect a change of code page. For example, if the default country/region and language of the host operating system are "`United States`" and "`English`", the following two calls to **`setlocale`** are functionally equivalent: `setlocale( LC_ALL, ".1252" );` @@ -166,11 +178,11 @@ The category must be either `LC_ALL` or `LC_CTYPE` to effect a change of code pa For more information, see the [`setlocale`](../../preprocessor/setlocale.md) pragma directive in the [C/C++ Preprocessor Reference](../../preprocessor/c-cpp-preprocessor-reference.md). -The function [`_configthreadlocale`](configthreadlocale.md) is used to control whether `setlocale` affects the locale of all threads in a program or only the locale of the calling thread. +The function [`_configthreadlocale`](configthreadlocale.md) is used to control whether **`setlocale`** affects the locale of all threads in a program or only the locale of the calling thread. -## UTF-8 Support +## UTF-8 support -Starting in Windows 10 version 1803 (10.0.17134.0), the Universal C Runtime supports using a UTF-8 code page. This means that `char` strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use `".UTF8"` as the code page when using `setlocale`. For example, `setlocale(LC_ALL, ".UTF8")` will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page. +Starting in Windows 10 version 1803 (10.0.17134.0), the Universal C Runtime supports using a UTF-8 code page. The change means that `char` strings passed to C runtime functions can expect strings in the UTF-8 encoding. To enable UTF-8 mode, use `".UTF8"` as the code page when using **`setlocale`**. For example, `setlocale(LC_ALL, ".UTF8")` uses the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page. The string to specify UTF-8 mode is: @@ -187,24 +199,24 @@ The following examples show how to specify the UTF-8 string: `"en_us.utf8"`\ `"ja_JP.Utf-8"` -After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string, whereas previously there wasn't a locale setting available to do this. +After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string. Previously, there wasn't a locale setting available to do this translation. -UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 before running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) in that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8. +UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 before running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) in that folder returns a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page isn't set to UTF-8. -The following aspects of the C Runtime can't use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md). +The following aspects of the C Runtime can't use UTF-8 because they're set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md). -Previous to this support, [`mbrtoc16`, `mbrtoc32`](../reference/mbrtoc16-mbrtoc323.md), [`c16rtomb`, and `c32rtomb`](../reference/c16rtomb-c32rtomb1.md) existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as `wchar_t` on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via `setlocale`. +Previous to this support, [`mbrtoc16`, `mbrtoc32`](../reference/mbrtoc16-mbrtoc323.md), [`c16rtomb`, and `c32rtomb`](../reference/c16rtomb-c32rtomb1.md) existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as `wchar_t` on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via **`setlocale`**. To use this feature on an OS prior to Windows 10, you must use [app-local deployment](../../windows/universal-crt-deployment.md#local-deployment) or link statically using version 1803 (10.0.17134.0) of the Windows SDK or later. For Windows 10 operating systems prior to 1803 (10.0.17134.0), only static linking is supported. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`setlocale`|``| -|`_wsetlocale`|`` or ``| +| Routine | Required header | +|---|---| +| **`setlocale`** | `` | +| **`_wsetlocale`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -246,9 +258,8 @@ int get_date(unsigned char* str) return 0; } -// This thread sets its locale to the argument -// and prints the date. -uintptr_t __stdcall SecondThreadFunc( void* pArguments ) +// This thread sets its locale to the argument and prints the date. +unsigned __stdcall SecondThreadFunc(void* pArguments) { unsigned char str[BUFF_SIZE]; char * locale = (char *)pArguments; @@ -286,7 +297,7 @@ int main() // Create the second thread with a German locale. // Our thread function takes an argument of the locale to use. hThread = (HANDLE)_beginthreadex( NULL, 0, &SecondThreadFunc, - "de-DE", 0, &threadID ); + (void*)"de-DE", 0, &threadID ); if (get_date(str) == 0) { @@ -304,25 +315,25 @@ int main() ```Output The thread locale is now set to en-US. -The time in en-US locale is: 'Wednesday, May 12, 2004' +The date in en-US locale is: 'Thursday, January 4, 2024' The thread locale is now set to de-DE. -The time in de-DE locale is: 'Mittwoch, 12. Mai 2004' +The date in de-DE locale is: 'Donnerstag, 4. Januar 2024' ``` ## See also -[Locale Names, Languages, and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md)\ +[Locale names, Languages, and Country/Region strings](../locale-names-languages-and-country-region-strings.md)\ [`_configthreadlocale`](configthreadlocale.md)\ [`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Locale](../locale.md)\ [`localeconv`](localeconv.md)\ [`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)\ [`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ [`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ [`_setmbcp`](setmbcp.md)\ -[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)\ +[`strcoll` functions](../strcoll-functions.md)\ [`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](strftime-wcsftime-strftime-l-wcsftime-l.md)\ [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)\ [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ diff --git a/docs/c-runtime-library/reference/setmaxstdio.md b/docs/c-runtime-library/reference/setmaxstdio.md index 3444b56ba7..d7d3b227fe 100644 --- a/docs/c-runtime-library/reference/setmaxstdio.md +++ b/docs/c-runtime-library/reference/setmaxstdio.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setmaxstdio", "_setmaxstdio"] helpviewer_keywords: ["maximum open files", "_setmaxstdio function", "setmaxstdio function", "open files, maximum"] -ms.assetid: 9e966875-9ff5-47c4-9b5f-e79e83b70249 --- -# _setmaxstdio +# `_setmaxstdio` Sets a maximum for the number of simultaneously open files at the stream I/O level. @@ -24,40 +23,40 @@ int _setmaxstdio( ### Parameters -*new_max*
+*`new_max`*\ New maximum for the number of simultaneously open files at the stream I/O level. -## Return Value +## Return value -Returns *new_max* if successful; -1 otherwise. +Returns *`new_max`* if successful; -1 otherwise. -If *new_max* is less than **_IOB_ENTRIES**, or greater than the maximum number of handles available in the operating system, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets **errno** to **EINVAL**. +If *`new_max`* is less than `_IOB_ENTRIES`, or greater than the maximum number of handles available in the operating system, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_setmaxstdio** function changes the maximum value for the number of files that may be open simultaneously at the stream I/O level. +The **`_setmaxstdio`** function changes the maximum value for the number of files that may be open simultaneously at the stream I/O level. -C run-time I/O now supports up to 8,192 files open simultaneously at the [low I/O level](../../c-runtime-library/low-level-i-o.md). This level includes files opened and accessed using the **_open**, **_read**, and **_write** family of I/O functions. By default, up to 512 files can be open simultaneously at the [stream I/O level](../../c-runtime-library/stream-i-o.md). This level includes files opened and accessed using the **fopen**, **fgetc**, and **fputc** family of functions. The limit of 512 open files at the stream I/O level can be increased to a maximum of 8,192 by use of the **_setmaxstdio** function. +C run-time I/O now supports up to 8,192 files open simultaneously at the [low I/O level](../low-level-i-o.md). This level includes files opened and accessed using the **`_open`**, **`_read`**, and **`_write`** family of I/O functions. By default, up to 512 files can be open simultaneously at the [stream I/O level](../stream-i-o.md). This level includes files opened and accessed using the **`fopen`**, **`fgetc`**, and **`fputc`** family of functions. The limit of 512 open files at the stream I/O level can be increased to a maximum of 8,192 by use of the **`_setmaxstdio`** function. -Because stream I/O-level functions, such as **fopen**, are built on top of the low I/O-level functions, the maximum of 8,192 is a hard upper limit for the number of simultaneously open files accessed through the C run-time library. +Because stream I/O-level functions, such as **`fopen`**, are built on top of the low I/O-level functions, the maximum of 8,192 is a hard upper limit for the number of simultaneously open files accessed through the C run-time library. > [!NOTE] > This upper limit might be beyond what's supported by a particular Win32 platform and configuration. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_setmaxstdio**|\| +| Routine | Required header | +|---|---| +| **`_setmaxstdio`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See [_getmaxstdio](getmaxstdio.md) for an example of using **_setmaxstdio**. +See [`_getmaxstdio`](getmaxstdio.md) for an example of using **`_setmaxstdio`**. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
+[Stream I/O](../stream-i-o.md) diff --git a/docs/c-runtime-library/reference/setmbcp.md b/docs/c-runtime-library/reference/setmbcp.md index 6169e72df5..38652bcd82 100644 --- a/docs/c-runtime-library/reference/setmbcp.md +++ b/docs/c-runtime-library/reference/setmbcp.md @@ -3,14 +3,14 @@ description: "Learn more about: _setmbcp" title: "_setmbcp" ms.date: "4/2/2020" api_name: ["_setmbcp", "_o__setmbcp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_setmbcp", "setmbcp"] helpviewer_keywords: ["setmbcp function", "_setmbcp function", "multibyte code pages"] ms.assetid: cfde53b5-0b73-4684-81b1-a8d3aafc85de --- -# _setmbcp +# `_setmbcp` Sets a new multibyte code page. @@ -24,42 +24,42 @@ int _setmbcp( ### Parameters -*codepage*
+*`codepage`*\ New code page setting for locale-independent multibyte routines. -## Return Value +## Return value -Returns 0 if the code page is set successfully. If an invalid code page value is supplied for *codepage*, returns -1 and the code page setting is unchanged. Sets **errno** to **EINVAL** if a memory allocation failure occurs. +Returns 0 if the code page is set successfully. If an invalid code page value is supplied for *`codepage`*, returns -1 and the code page setting is unchanged. Sets `errno` to `EINVAL` if a memory allocation failure occurs. ## Remarks -The **_setmbcp** function specifies a new multibyte code page. By default, the run-time system automatically sets the multibyte code page to the system-default ANSI code page. The multibyte code page setting affects all multibyte routines that are not locale dependent. However, it is possible to instruct **_setmbcp** to use the code page defined for the current locale (see the following list of manifest constants and associated behavior results). For a list of the multibyte routines that are dependent on the locale code page rather than the multibyte code page, see [Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md). +The **`_setmbcp`** function specifies a new multibyte code page. By default, the run-time system automatically sets the multibyte code page to the system-default ANSI code page. The multibyte code page setting affects all multibyte routines that aren't locale dependent. However, it's possible to instruct **`_setmbcp`** to use the code page defined for the current locale (see the following list of manifest constants and associated behavior results). For a list of the multibyte routines that are dependent on the locale code page rather than the multibyte code page, see [Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md). -The *codepage* argument can be set to any of the following values: +The *`codepage`* argument can be set to any of the following values: -- **_MB_CP_ANSI** Use ANSI code page obtained from operating system at program startup. +- `_MB_CP_ANSI` Use ANSI code page obtained from operating system at program startup. -- **_MB_CP_LOCALE** Use the current locale's code page obtained from a previous call to [setlocale](setlocale-wsetlocale.md). +- `_MB_CP_LOCALE` Use the current locale's code page obtained from a previous call to [`setlocale`](setlocale-wsetlocale.md). -- **_MB_CP_OEM** Use OEM code page obtained from operating system at program startup. +- `_MB_CP_OEM` Use OEM code page obtained from operating system at program startup. -- **_MB_CP_SBCS** Use single-byte code page. When the code page is set to **_MB_CP_SBCS**, a routine such as [_ismbblead](ismbblead-ismbblead-l.md) always returns false. +- `_MB_CP_SBCS` Use single-byte code page. When the code page is set to `_MB_CP_SBCS`, a routine such as [`_ismbblead`](ismbblead-ismbblead-l.md) always returns false. -- **_MB_CP_UTF8** Use UTF-8. When the code page is set to **_MB_CP_UTF8**, a routine such as [_ismbblead](ismbblead-ismbblead-l.md) always returns false. +- `_MB_CP_UTF8` Use UTF-8. When the code page is set to `_MB_CP_UTF8`, a routine such as [`_ismbblead`](ismbblead-ismbblead-l.md) always returns false. -- Any other valid code page value, regardless of whether the value is an ANSI, OEM, or other operating-system-supported code page (except UTF-7, which is not supported). +- Any other valid code page value, regardless of whether the value is an ANSI, OEM, or other operating-system-supported code page (except UTF-7, which isn't supported). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_setmbcp**|\| +| Routine | Required header | +|---|---| +| **`_setmbcp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_getmbcp](getmbcp.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
+[`_getmbcp`](getmbcp.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/reference/setmode.md b/docs/c-runtime-library/reference/setmode.md index f91a152ed5..009bc3bdff 100644 --- a/docs/c-runtime-library/reference/setmode.md +++ b/docs/c-runtime-library/reference/setmode.md @@ -3,7 +3,7 @@ description: "Learn more about: _setmode" title: "_setmode" ms.date: "4/2/2020" api_name: ["_setmode", "_o__setmode"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_setmode"] @@ -25,25 +25,25 @@ int _setmode ( ### Parameters -*`fd`*
+*`fd`*\ File descriptor. -*`mode`*
+*`mode`*\ New translation mode. -## Return Value +## Return value If successful, returns the previous translation mode. -If invalid parameters are passed to this function, the invalid-parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets **`errno`** to either **`EBADF`**, which indicates an invalid file descriptor, or **`EINVAL`**, which indicates an invalid *`mode`* argument. +If invalid parameters are passed to this function, the invalid-parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets `errno` to either `EBADF`, which indicates an invalid file descriptor, or `EINVAL`, which indicates an invalid *`mode`* argument. -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_setmode`** function sets to *`mode`* the translation mode of the file given by *`fd`*. Passing **`_O_TEXT`** as *`mode`* sets text (that is, translated) mode. Carriage return-line feed (CR-LF) combinations are translated into a single line feed character on input. Line feed characters are translated into CR-LF combinations on output. Passing **`_O_BINARY`** sets binary (untranslated) mode, in which these translations are suppressed. +The **`_setmode`** function sets to *`mode`* the translation mode of the file given by *`fd`*. Passing `_O_TEXT` as *`mode`* sets ANSI text (that is, translated) mode. Carriage return-line feed (CR-LF) combinations are translated into a single line feed character on input. Line feed characters are translated into CR-LF combinations on output. Passing `_O_BINARY` sets binary (untranslated) mode, in which these translations are suppressed. -You can also pass **`_O_U16TEXT`**, **`_O_U8TEXT`**, or **`_O_WTEXT`** to enable Unicode mode, as demonstrated in the second example later in this document. +You can also pass `_O_U16TEXT`, `_O_U8TEXT`, or `_O_WTEXT` to enable Unicode mode, as demonstrated in the second example later in this document. > [!CAUTION] > Unicode mode is for wide print functions (for example, `wprintf`) and is not supported for narrow print functions. Use of a narrow print function on a Unicode mode stream triggers an assert. @@ -53,15 +53,15 @@ You can also pass **`_O_U16TEXT`**, **`_O_U8TEXT`**, or **`_O_WTEXT`** to enable > [!CAUTION] > If you write data to a file stream, explicitly flush the code by using [`fflush`](fflush.md) before you use **`_setmode`** to change the mode. If you do not flush the code, you might get unexpected behavior. If you have not written data to the stream, you do not have to flush the code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional Headers| -|-------------|---------------------|----------------------| -|**`_setmode`**|``|``| +| Routine | Required header | Optional Headers | +|---|---|---| +| **`_setmode`** | `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use `_setmode` to change stdin @@ -113,8 +113,8 @@ int main(void) { ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_creat`, `_wcreat`](creat-wcreat.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`_open`, `_wopen`](open-wopen.md)
-[`_set_fmode`](set-fmode.md)
+[File handling](../file-handling.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_set_fmode`](set-fmode.md) diff --git a/docs/c-runtime-library/reference/setvbuf.md b/docs/c-runtime-library/reference/setvbuf.md index 1621dd2a79..167b178aab 100644 --- a/docs/c-runtime-library/reference/setvbuf.md +++ b/docs/c-runtime-library/reference/setvbuf.md @@ -3,14 +3,14 @@ description: "Learn more about: setvbuf" title: "setvbuf" ms.date: "4/2/2020" api_name: ["setvbuf", "_o_setvbuf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setvbuf"] helpviewer_keywords: ["controlling stream buffering", "stream buffering", "setvbuf function"] ms.assetid: 6aa5aa37-3408-4fa0-992f-87f9f9c4baea --- -# setvbuf +# `setvbuf` Controls stream buffering and buffer size. @@ -27,51 +27,51 @@ int setvbuf( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*buffer*
+*`buffer`*\ User-allocated buffer. -*mode*
+*`mode`*\ Mode of buffering. -*size*
-Buffer size in bytes. Allowable range: 2 <= *size* <= INT_MAX (2147483647). Internally, the value supplied for *size* is rounded down to the nearest multiple of 2. +*`size`*\ +Buffer size in bytes. Allowable range: 2 <= *`size`* <= INT_MAX (2147483647). Internally, the value supplied for *`size`* is rounded down to the nearest multiple of 2. -## Return Value +## Return value Returns 0 if successful. -If *stream* is **NULL**, or if *mode* or *size* is not within a valid change, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets **errno** to **EINVAL**. +If *`stream`* is `NULL`, or if *`mode`* or *`size`* isn't within a valid change, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **setvbuf** function allows the program to control both buffering and buffer size for *stream*. *stream* must refer to an open file that has not undergone an I/O operation since it was opened. The array pointed to by *buffer* is used as the buffer, unless it is **NULL**, in which case **setvbuf** uses an automatically allocated buffer of length *size*/2 \* 2 bytes. +The **`setvbuf`** function allows the program to control both buffering and buffer size for *`stream`*. *`stream`* must refer to an open file that hasn't undergone an I/O operation since it was opened. The array pointed to by *`buffer`* is used as the buffer, unless *`buffer`* is `NULL`, in which case **`setvbuf`** uses an automatically allocated buffer of length *`size`*/2 \* 2 bytes. -The mode must be **_IOFBF**, **_IOLBF**, or **_IONBF**. If *mode* is **_IOFBF** or **_IOLBF**, then *size* is used as the size of the buffer. If *mode* is **_IONBF**, the stream is unbuffered and *size* and *buffer* are ignored. Values for *mode* and their meanings are: +The mode must be `_IOFBF`, `_IOLBF`, or `_IONBF`. If *`mode`* is `_IOFBF` or `_IOLBF`, then *`size`* is used as the size of the buffer. If *`mode`* is `_IONBF`, the stream is unbuffered, and both *`size`* and *`buffer`* are ignored. Values for *`mode`* and their meanings are: -|*mode* value|Meaning| -|-|-| -| **_IOFBF** | Full buffering; that is, *buffer* is used as the buffer and *size* is used as the size of the buffer. If *buffer* is **NULL**, an automatically allocated buffer *size* bytes long is used. | -| **_IOLBF** | For some systems, this provides line buffering. However, for Win32, the behavior is the same as **_IOFBF** - Full Buffering. | -| **_IONBF** | No buffer is used, regardless of *buffer* or *size*. | +| *`mode`* value | Meaning | +|---|---| +| `_IOFBF` | Full buffering; that is, *`buffer`* is used as the buffer and *`size`* is used as the size of the buffer. If *`buffer`* is `NULL`, this mode uses an automatically allocated buffer that's *`size`* bytes long. | +| `_IOLBF` | For some systems, this mode provides line buffering. However, for Win32, the behavior is the same as `_IOFBF` - Full Buffering. | +| `_IONBF` | No buffer is used, regardless of *`buffer`* or *`size`*. | -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**setvbuf**|\| +| Routine | Required header | +|---|---| +| **`setvbuf`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -112,8 +112,8 @@ int main( void ) ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[fflush](fflush.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[setbuf](setbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`fflush`](fflush.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`setbuf`](setbuf.md) diff --git a/docs/c-runtime-library/reference/signal.md b/docs/c-runtime-library/reference/signal.md index d831ccda15..ad4bd650a1 100644 --- a/docs/c-runtime-library/reference/signal.md +++ b/docs/c-runtime-library/reference/signal.md @@ -14,7 +14,7 @@ helpviewer_keywords: ["signal function"] Sets interrupt signal handling. > [!IMPORTANT] -> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -24,81 +24,81 @@ void __cdecl *signal(int sig, int (*func)(int, int)); ### Parameters -*`sig`*
+*`sig`*\ Signal value. -*`func`*
-The second parameter is a pointer to the function to be executed. The first parameter is a signal value and the second parameter is a sub-code that can be used when the first parameter is **`SIGFPE`**. +*`func`*\ +The second parameter is a pointer to the function to be executed. The first parameter is a signal value, and the second parameter is a subcode that can be used when the first parameter is `SIGFPE`. -## Return Value +## Return value -**`signal`** returns the previous value of func that's associated with the given signal. For example, if the previous value of *`func`* was **`SIG_IGN`**, the return value is also **`SIG_IGN`**. A return value of **`SIG_ERR`** indicates an error; in that case, **`errno`** is set to **`EINVAL`**. +**`signal`** returns the previous value of func that's associated with the given signal. For example, if the previous value of *`func`* was `SIG_IGN`, the return value is also `SIG_IGN`. A return value of `SIG_ERR` indicates an error; in that case, `errno` is set to `EINVAL`. -See [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information about return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`signal`** function enables a process to choose one of several ways to handle an interrupt signal from the operating system. The *`sig`* argument is the interrupt to which **`signal`** responds; it must be one of the following manifest constants, which are defined in **`SIGNAL.H`**. -|*`sig`* value|Description| -|-----------------|-----------------| -|**`SIGABRT`**|Abnormal termination| -|**`SIGFPE`**|Floating-point error| -|**`SIGILL`**|Illegal instruction| -|**`SIGINT`**|CTRL+C signal| -|**`SIGSEGV`**|Illegal storage access| -|**`SIGTERM`**|Termination request| +| *`sig`* value | Description | +|---|---| +| `SIGABRT` | Abnormal termination | +| `SIGFPE` | Floating-point error | +| `SIGILL` | Illegal instruction | +| `SIGINT` | CTRL+C signal | +| `SIGSEGV` | Illegal storage access | +| `SIGTERM` | Termination request | -If *`sig`* is not one of the above values, the invalid parameter handler is invoked, as defined in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, this function sets **`errno`** to **`EINVAL`** and returns **`SIG_ERR`**. +If *`sig`* isn't one of the above values, the invalid parameter handler is invoked, as defined in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `SIG_ERR`. By default, **`signal`** terminates the calling program with exit code 3, regardless of the value of *`sig`*. > [!NOTE] -> **`SIGINT`** is not supported for any Win32 application. When a CTRL+C interrupt occurs, Win32 operating systems generate a new thread to specifically handle that interrupt. This can cause a single-thread application, such as one in UNIX, to become multithreaded and cause unexpected behavior. +> `SIGINT` is not supported for any Win32 application. When a CTRL+C interrupt occurs, Win32 operating systems generate a new thread to specifically handle that interrupt. This can cause a single-thread application, such as one in UNIX, to become multithreaded and cause unexpected behavior. -The *`func`* argument is an address to a signal handler that you write, or to one of the predefined constants **`SIG_DFL`** or **`SIG_IGN`**, which are also defined in SIGNAL.H. If *`func`* is a function, it is installed as the signal handler for the given signal. The signal handler's prototype requires one formal argument, *`sig`*, of type **`int`**. The operating system provides the actual argument through *`sig`* when an interrupt occurs; the argument is the signal that generated the interrupt. Therefore, you can use the six manifest constants (listed in the preceding table) in your signal handler to determine which interrupt occurred and take appropriate action. For example, you can call **`signal`** twice to assign the same handler to two different signals, and then test the *`sig`* argument in the handler to take different actions based on the signal received. +The *`func`* argument is an address to a signal handler that you write, or to one of the predefined [signal action constants](../signal-action-constants.md) `SIG_DFL` or `SIG_IGN`, which are also defined in SIGNAL.H. If *`func`* is a function, it's installed as the signal handler for the given signal. The signal handler's prototype requires one formal argument, *`sig`*, of type **`int`**. The operating system provides the actual argument through *`sig`* when an interrupt occurs; the argument is the signal that generated the interrupt. Therefore, you can use the six manifest constants (listed in the preceding table) in your signal handler to determine which interrupt occurred and take appropriate action. For example, you can call **`signal`** twice to assign the same handler to two different signals, and then test the *`sig`* argument in the handler to take different actions based on the signal received. -If you are testing for floating-point exceptions (**`SIGFPE`**), *`func`* points to a function that takes an optional second argument that is one of several manifest constants, defined in `FLOAT.H`, of the form **`FPE_xxx`**. When a **`SIGFPE`** signal occurs, you can test the value of the second argument to determine the kind of floating-point exception and then take appropriate action. This argument and its possible values are Microsoft extensions. +If you're testing for floating-point exceptions (`SIGFPE`), *`func`* points to a function that takes an optional second argument that is one of several manifest constants, defined in `FLOAT.H`, of the form `FPE_xxx`. When a `SIGFPE` signal occurs, you can test the value of the second argument to determine the kind of floating-point exception, and then take appropriate action. This argument and its possible values are Microsoft extensions. -For floating-point exceptions, the value of *`func`* is not reset when the signal is received. To recover from floating-point exceptions, use try/except clauses to surround the floating point operations. It's also possible to recover by using [`setjmp`](setjmp.md) with [`longjmp`](longjmp.md). In either case, the calling process resumes execution and leaves the floating-point state of the process undefined. +For floating-point exceptions, the value of *`func`* isn't reset when the signal is received. To recover from floating-point exceptions, use try/except clauses to surround the floating point operations. It's also possible to recover by using [`setjmp`](setjmp.md) with [`longjmp`](longjmp.md). In either case, the calling process resumes execution and leaves the floating-point state of the process undefined. -If the signal handler returns, the calling process resumes execution immediately following the point at which it received the interrupt signal. This is true regardless of the kind of signal or operating mode. +If the signal handler returns, the calling process resumes execution immediately following the point at which it received the interrupt signal, regardless of the kind of signal or operating mode. -Before the specified function is executed, the value of *`func`* is set to **`SIG_DFL`**. The next interrupt signal is treated as described for **`SIG_DFL`**, unless an intervening call to **`signal`** specifies otherwise. You can use this feature to reset signals in the called function. +Before the specified function is executed, the value of *`func`* is set to `SIG_DFL`. The next interrupt signal is treated as described for `SIG_DFL`, unless an intervening call to **`signal`** specifies otherwise. You can use this feature to reset signals in the called function. -Because signal-handler routines are usually called asynchronously when an interrupt occurs, your signal-handler function may get control when a run-time operation is incomplete and in an unknown state. The following list summarizes the restrictions that determine which functions you can use in your signal-handler routine. +Because signal-handler routines are often called asynchronously when an interrupt occurs, your signal-handler function may get control when a run-time operation is incomplete and in an unknown state. The following list summarizes the restrictions that determine which functions you can use in your signal-handler routine. -- Do not issue low-level or **`STDIO.H`** I/O routines (for example, **`printf`** or **`fread`**). +- Don't issue low-level or **`STDIO.H`** I/O routines (for example, **`printf`** or **`fread`**). -- Do not call heap routines or any routine that uses the heap routines (for example, **`malloc`**, **`_strdup`**, or **`_putenv`**). See [`malloc`](malloc.md) for more information. +- Don't call heap routines or any routine that uses the heap routines (for example, **`malloc`**, **`_strdup`**, or **`_putenv`**). For more information, see [`malloc`](malloc.md). -- Do not use any function that generates a system call (for example, **`_getcwd`** or **`time`**). +- Don't use any function that generates a system call (for example, **`_getcwd`** or **`time`**). -- Do not use **`longjmp`** unless the interrupt is caused by a floating-point exception (that is, *`sig`* is **`SIGFPE`**). In this case, first reinitialize the floating-point package by using a call to **`_fpreset`**. +- Don't use **`longjmp`** unless the interrupt is caused by a floating-point exception (that is, *`sig`* is `SIGFPE`). In this case, first reinitialize the floating-point package by using a call to **`_fpreset`**. -- Do not use any overlay routines. +- Don't use any overlay routines. -A program must contain floating-point code if it is to trap the **`SIGFPE`** exception by using the function. If your program does not have floating-point code and requires the run-time library's signal-handling code, just declare a volatile double and initialize it to zero: +A program must contain floating-point code if it's to trap the `SIGFPE` exception by using the function. If your program doesn't have floating-point code and requires the run-time library's signal-handling code, just declare a volatile double and initialize it to zero: ```C volatile double d = 0.0f; ``` -The **`SIGILL`** and **`SIGTERM`** signals are not generated under Windows. They are included for ANSI compatibility. Therefore, you can set signal handlers for these signals by using **`signal`**, and you can also explicitly generate these signals by calling [`raise`](raise.md). +The `SIGILL` and `SIGTERM` signals aren't generated under Windows. They're included for ANSI compatibility. Therefore, you can set signal handlers for these signals by using **`signal`**, and you can also explicitly generate these signals by calling [`raise`](raise.md). -Signal settings are not preserved in spawned processes that are created by calls to [`_exec`](../../c-runtime-library/exec-wexec-functions.md) or [`_spawn`](../../c-runtime-library/spawn-wspawn-functions.md) functions. The signal settings are reset to the default values in the new process. +Signal settings aren't preserved in spawned processes that are created by calls to [`_exec`](../exec-wexec-functions.md) or [`_spawn`](../spawn-wspawn-functions.md) functions. The signal settings are reset to the default values in the new process. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`signal`**|``| +| Routine | Required header | +|---|---| +| **`signal`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -The following example shows how to use **`signal`** to add some custom behavior to the **`SIGABRT`** signal. For additional information about abort behavior, see [`_set_abort_behavior`](set-abort-behavior.md). +The following example shows how to use **`signal`** to add some custom behavior to the `SIGABRT` signal. For more information about abort behavior, see [`_set_abort_behavior`](set-abort-behavior.md). ```C // crt_signal.c @@ -141,9 +141,9 @@ R6010 ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`abort`](abort.md)
-[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)
-[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)
-[`_fpreset`](fpreset.md)
-[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_fpreset`](fpreset.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md) diff --git a/docs/c-runtime-library/reference/signbit.md b/docs/c-runtime-library/reference/signbit.md index 13f7967a2e..7030b5d1bf 100644 --- a/docs/c-runtime-library/reference/signbit.md +++ b/docs/c-runtime-library/reference/signbit.md @@ -5,7 +5,7 @@ ms.date: "01/31/2019" f1_keywords: ["signbit", "math/signbit"] helpviewer_keywords: ["signbit function"] --- -# signbit +# `signbit` Determines whether a floating-point value is negative. @@ -31,30 +31,30 @@ inline bool signbit( ### Parameters -*x*
+*`x`*\ The floating-point value to test. ## Return value -**signbit** returns a non-zero value (**`true`** in C++) if the argument *x* is negative or negative infinity. It returns 0 (**`false`** in C++) if the argument is non-negative, positive infinity, or a NAN. +**`signbit`** returns a non-zero value (**`true`** in C++) if the argument *`x`* is negative or negative infinity. It returns 0 (**`false`** in C++) if the argument is non-negative, positive infinity, or a NAN. ## Remarks -**signbit** is a macro when compiled as C, and an overloaded inline function when compiled as C++. +**`signbit`** is a macro when compiled as C, and an overloaded inline function when compiled as C++. ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -|**signbit**|\|\ or \| +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`signbit`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) diff --git a/docs/c-runtime-library/reference/sin-sinf-sinl.md b/docs/c-runtime-library/reference/sin-sinf-sinl.md index 601d354fa5..841be1e4a4 100644 --- a/docs/c-runtime-library/reference/sin-sinf-sinl.md +++ b/docs/c-runtime-library/reference/sin-sinf-sinl.md @@ -3,7 +3,7 @@ title: "sin, sinf, sinl" description: "API reference for sin, sinf, and sinl; which calculate the sine of a floating-point value." ms.date: "08/31/2020" api_name: ["sinl", "sinf", "sin", "_o_sin", "_o_sinf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_sinl", "sinf", "sinl", "sin"] @@ -36,29 +36,29 @@ Angle in radians. The **`sin`** functions return the sine of *`x`*. If *`x`* is greater than or equal to 263, or less than or equal to -263, a loss of significance in the result occurs. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± `QNAN`,`IND`|None|`_DOMAIN`| -|± ∞ (`sin`, `sinf`, `sinl`)|`INVALID`|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | None | `_DOMAIN` | +| ± INF (`sin`, `sinf`, `sinl`) | `INVALID` | `_DOMAIN` | -For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Because C++ allows overloading, you can call overloads of **`sin`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`sin`** always takes and returns **`double`**. -If you use the ` sin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the ` sin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-|-|-| -|**`sin`**, **`sinf`**, **`sinl`**|``|`` or ``| -|**`sin()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`sin`**, **`sinf`**, **`sinl`** | `` | `` or `` | +| **`sin`** macro | `` | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -90,10 +90,10 @@ cos( 1.570796 ) = 0.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ [`tan`, `tanf`, `tanl`](tan-tanf-tanl.md)\ -[`_CIsin`](../../c-runtime-library/cisin.md)\ +[`_CIsin`](../cisin.md) diff --git a/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md b/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md index 37c1d5a347..3a4456374e 100644 --- a/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md +++ b/docs/c-runtime-library/reference/sinh-sinhf-sinhl.md @@ -3,7 +3,7 @@ title: "sinh, sinhf, sinhl" description: "API reference for calculating the hyperbolic sine of a floating-point value." ms.date: "1/15/2021" api_name: ["sinh", "sinhl", "sinhf", "sinhl", "_o_sinh", "_o_sinhf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["sinh", "sinhf", "sinhl"] @@ -30,33 +30,33 @@ long double sinh(long double x); // C++ only *`x`*\ Angle in radians. -## Return Value +## Return value -The **`sinh`** functions return the hyperbolic sine of *`x`*. By default, if the result is too large, **`sinh`** sets **`errno`** to **`ERANGE`** and returns ±**`HUGE_VAL`**. +The **`sinh`** functions return the hyperbolic sine of *`x`*. By default, if the result is too large, **`sinh`** sets `errno` to `ERANGE` and returns ±`HUGE_VAL`. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± `QNAN`,`IND`|None|`_DOMAIN`| -||x| ≥ 7.104760e+002|`OVERFLOW+INEXACT`|`OVERFLOW`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | None | `_DOMAIN` | +| `|x| ≥ 7.104760e+002` | `OVERFLOW`+`INEXACT` | `OVERFLOW` | -For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Because C++ allows overloading, you can call overloads of **`sinh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`sinh`** always takes and returns **`double`**. -If you use the `` `sinh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `sinh` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-|-|-| -|**`sinh`**, **`sinhf`**, **`sinhl`**|``|`` or ``| -|**`sinh()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`sinh`**, **`sinhf`**, **`sinhl`** | `` | `` or `` | +| **`sinh`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -89,7 +89,7 @@ cosh( 1.570796 ) = 2.509178 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ [`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ [`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ diff --git a/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md b/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md index 74f0dd6f78..548a9fccf6 100644 --- a/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md +++ b/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md @@ -1,7 +1,7 @@ --- description: "Learn more about: _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l" title: "_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l" -ms.date: "3/9/2021" +ms.date: 06/27/2023 api_name: ["_snprintf_s", "_snprintf_s_l", "_snwprintf_s", "_snwprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] @@ -11,7 +11,7 @@ helpviewer_keywords: ["_snprintf_s_l function", "_snwprintf_s_l function", "_snt --- # `_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l` -Writes formatted data to a string. These are versions of [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Writes formatted data to a string. These functions are versions of [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) with security enhancements described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -23,6 +23,7 @@ int _snprintf_s( const char *format [, argument] ... ); + int _snprintf_s_l( char *buffer, size_t sizeOfBuffer, @@ -31,6 +32,7 @@ int _snprintf_s_l( _locale_t locale [, argument] ... ); + int _snwprintf_s( wchar_t *buffer, size_t sizeOfBuffer, @@ -38,6 +40,7 @@ int _snwprintf_s( const wchar_t *format [, argument] ... ); + int _snwprintf_s_l( wchar_t *buffer, size_t sizeOfBuffer, @@ -46,6 +49,7 @@ int _snwprintf_s_l( _locale_t locale [, argument] ... ); + template int _snprintf_s( char (&buffer)[size], @@ -53,6 +57,7 @@ int _snprintf_s( const char *format [, argument] ... ); // C++ only + template int _snwprintf_s( wchar_t (&buffer)[size], @@ -64,67 +69,86 @@ int _snwprintf_s( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for the output. -*`sizeOfBuffer`*
-The size of the storage location for output. Size in **`bytes`** for **`_snprintf_s`** or size in **`words`** for **`_snwprintf_s`**. +*`sizeOfBuffer`*\ +The size of the storage location for output. Size in **bytes** for the functions that take `char`, and **words** for those that take `wchar_t`. -*`count`*
-Maximum number of characters to store, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +Maximum number of characters to write. For the functions that take `wchar_t`, it's the maximum number of wide characters to write. Or [`_TRUNCATE`](../truncate.md). -*`format`*
+*`format`*\ Format-control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**`_snprintf_s`** returns the number of characters stored in *`buffer`*, not counting the terminating null character. **`_snwprintf_s`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. +The number of characters written, not including the terminating `NULL`. A negative value is returned if an output error occurs. See [Behavior summary](#behavior-summary) for details. -If the storage required to store the data and a terminating null exceeds *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set **`errno`** to **`ERANGE`**, and return -1. +## Remarks -If *`buffer`* or *`format`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. +The **`_snprintf_s`** function formats and stores *`count`* or fewer characters in *`buffer`* and appends a terminating `NULL`. Each argument (if any) is converted and output according to the corresponding format specification in *`format`*. The formatting is consistent with the **`printf`** family of functions; see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). If copying occurs between strings that overlap, the behavior is undefined. -For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +### Behavior summary -## Remarks +For the following table: -The **`_snprintf_s`** function formats and stores *`count`* or fewer characters in *`buffer`* and appends a terminating null. Each argument (if any) is converted and output according to the corresponding format specification in *`format`*. The formatting is consistent with the **`printf`** family of functions; see [Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). If copying occurs between strings that overlap, the behavior is undefined. +-Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). -If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md), then **`_snprintf_s`** writes as much of the string as will fit in *`buffer`* while leaving room for a terminating null. If the entire string (with terminating null) fits in *`buffer`*, then **`_snprintf_s`** returns the number of characters written (not including the terminating null); otherwise, **`_snprintf_s`** returns -1 to indicate that truncation occurred. +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler | +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string.| The number of characters written, not including the terminating `NULL`. | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ` (42) | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ` (42) | No | +| `buffer == NULL` and `sizeOfBuffer == 0` and `count == 0` | No data is written. | 0 | N/A | No | +| `buffer == NULL` and either `sizeOfBuffer != 0` or `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | +| `buffer != NULL` and `sizeOfBuffer == 0` | No data is written. | -1 | `EINVAL` (22) | Yes | +| `count == 0`| A `NULL` is placed at the beginning of the buffer. | -1 | N/A | No | +| `count < 0`| Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count`* characters are written and a terminating `NULL` is appended. | -1 | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` and `count != _TRUNCATE` | If execution continues after invalid parameter handler executes, sets `errno`, sets `buffer[0] == NULL`, and returns a negative value. | -1 | `ERANGE` (34) | Yes | +| `count == _TRUNCATE` and `len >= sizeOfBuffer` | Writes as much of the string as fits in *`buffer`* and a terminating `NULL`. | -1 | N/A | No | +| `count == _TRUNCATE` and `len < sizeOfBuffer` | Writes the entire string into *`buffer`* with a terminating `NULL`. | Number of characters written, not including the terminating `NULL`. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). > [!IMPORTANT] > Ensure that *`format`* is not a user-defined string. > -> > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). **`_snwprintf_s`** is a wide-character version of **`_snprintf_s`**; the pointer arguments to **`_snwprintf_s`** are wide-character strings. Detection of encoding errors in **`_snwprintf_s`** might differ from that in **`_snprintf_s`**. **`_snwprintf_s`**, like **`swprintf_s`**, writes output to a string rather than to a destination of type **`FILE`**. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings |`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| +|---|---|---|---| |**`_sntprintf_s`**|**`_snprintf_s`**|**`_snprintf_s`**|**`_snwprintf_s`**| |**`_sntprintf_s_l`**|**`_snprintf_s_l`**|**`_snprintf_s_l`**|**`_snwprintf_s_l`**| ## Requirements |Routine|Required header| -|-------------|---------------------| +|---|---| |**`_snprintf_s`**, **`_snprintf_s_l`**|``| |**`_snwprintf_s`**, **`_snwprintf_s_l`**|`` or ``| -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -256,10 +280,10 @@ Invalid parameter handler invoked: ("Buffer too small", 0) ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md b/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md index cfe357ab0e..6043ec459e 100644 --- a/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md +++ b/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md @@ -1,7 +1,7 @@ --- title: "snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l" description: "API reference for snprintf, _snprintf, _snprintf_l, _snwprintf, and _snwprintf_; which write formatted data to a string." -ms.date: "3/9/2021" +ms.date: 06/27/2023 api_name: ["_snwprintf", "_snprintf", "_snprintf_l", "_snwprintf_l", "snprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] @@ -22,12 +22,14 @@ int snprintf( const char *format [, argument] ... ); + int _snprintf( char *buffer, size_t count, const char *format [, argument] ... ); + int _snprintf_l( char *buffer, size_t count, @@ -35,12 +37,14 @@ int _snprintf_l( _locale_t locale [, argument] ... ); + int _snwprintf( wchar_t *buffer, size_t count, const wchar_t *format [, argument] ... ); + int _snwprintf_l( wchar_t *buffer, size_t count, @@ -48,6 +52,7 @@ int _snwprintf_l( _locale_t locale [, argument] ... ); + template int _snprintf( char (&buffer)[size], @@ -55,6 +60,7 @@ int _snprintf( const char *format [, argument] ... ); // C++ only + template int _snprintf_l( char (&buffer)[size], @@ -63,6 +69,7 @@ int _snprintf_l( _locale_t locale [, argument] ... ); // C++ only + template int _snwprintf( wchar_t (&buffer)[size], @@ -70,6 +77,7 @@ int _snwprintf( const wchar_t *format [, argument] ... ); // C++ only + template int _snwprintf_l( wchar_t (&buffer)[size], @@ -82,71 +90,95 @@ int _snwprintf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for the output. -*`count`*
-Maximum number of characters to store. +*`count`*\ +Maximum number of characters to write. For the functions that take `wchar_t`, it's the maximum number of wide characters to write. -*`format`*
+*`format`*\ Format-control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
-The locale to use. +*`locale`*\ +The locale to use to format the output. + +For more information, see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -For more information, see [Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +## Return value -## Return Value +The number of characters that which would have been written to the buffer if `count` was ignored. The count doesn't include the terminating `NULL` character. -Let **`len`** be the length of the formatted data string, not including the terminating null. Both **`len`** and **`count`** are the number of characters for **`snprintf`** and **`_snprintf`**, and the number of wide characters for **`_snwprintf`**. +Let **`len`** be the length of the formatted data string, not including the terminating `NULL`.\ +For all functions, if `len < count`, then **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and the number of characters written, not including the terminating `NULL`, is returned. -For all functions, if **`len`** < *`count`*, **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and **`len`** is returned. +The wide character versions of these functions return the number of wide characters written, not including the terminating `NULL`. -The **`snprintf`** function truncates the output when **`len`** is greater than or equal to *`count`*, by placing a null-terminator at `buffer[count-1]`. The value returned is **`len`**, the number of characters that would have been output if *`count`* was large enough. The **`snprintf`** function returns a negative value if an encoding error occurs. +See [Behavior summary](#behavior-summary) for details. -For all functions other than **`snprintf`**, if **`len`** = *`count`*, **`len`** characters are stored in *`buffer`*, no null-terminator is appended, and **`len`** is returned. If **`len`** > *`count`*, *`count`* characters are stored in *`buffer`*, no null-terminator is appended, and a negative value is returned. +## Remarks -If *`buffer`* is a null pointer and *`count`* is zero, **`len`** is returned as the count of characters required to format the output, not including the terminating null. To make a successful call with the same *`argument`* and *`locale`* parameters, allocate a buffer holding at least **`len`** + 1 characters. +Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`snprintf`** is no longer identical to **`_snprintf`**. The **`snprintf`** behavior is now C99 standard conformant. The difference is that if you run out of buffer, `snprintf` null-terminates the end of the buffer and returns the number of characters that would have been required whereas `_snprintf` doesn't null-terminate the buffer and returns -1. Also, `_snprintf()` includes one more character in the output because it doesn't null-terminate the buffer. -If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +- **`snprintf`** and the **`_snprintf`** family of functions format and store *`count`* or fewer characters in *`buffer`*. +- **`snprintf`** always stores a terminating `NULL` character, truncating the output if necessary. +- If **`snprintf`** returns a value > *`count`* - 1, the output has been truncated. +- The **`_snprintf`** family of functions only appends a terminating `NULL` character if the formatted string length is strictly less than *`count`* characters. +- Each *`argument`* (if any) is converted and is output according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). If copying occurs between strings that overlap, the behavior is undefined. -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +### Behavior summary -## Remarks +For the following table: -The **`snprintf`** function and the **`_snprintf`** family of functions format and store *`count`* or fewer characters in *`buffer`*. The **`snprintf`** function always stores a terminating null character, truncating the output if necessary. The **`_snprintf`** family of functions only appends a terminating null character if the formatted string length is strictly less than *`count`* characters. Each *`argument`* (if any) is converted and is output according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). If copying occurs between strings that overlap, the behavior is undefined. +- Let `sizeOfBuffer` be the size of `buffer`. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). + +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler | +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string. | The number of characters written. | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops, a `NULL` is placed at the beginning of the buffer. | -1 | `EILSEQ` (42) | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ` (42) | No | +| `buffer == NULL` and `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | +| `count == 0` | The number of characters that would have been written, not including the terminating `NULL`. You can use this result to allocate sufficient buffer space for the string and a terminating `NULL`, and then call the function again to fill the buffer. | N/A | No | +| `count < 0`| Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count-1`* characters are written followed by a null-terminator. | The number of characters that would have been written had `count` matched the number of characters to output, not including the null-terminator. | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` | Unsafe: Overwrites the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). > [!IMPORTANT] -> Ensure that *`format`* is not a user-defined string. Because the **`_snprintf`** functions do not guarantee null termination—in particular, when the return value is *`count`*—make sure that they are followed by code that adds the null terminator. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. Because the **`_snprintf`** functions do not guarantee null termination—in particular, when the return value is *`count`*—make sure that they are followed by code that adds the null terminator. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`snprintf`** is no longer identical to **`_snprintf`**. The **`snprintf`** function behavior is now C99 standard conformant. - -**`_snwprintf`** is a wide-character version of **`_snprintf`**; the pointer arguments to **`_snwprintf`** are wide-character strings. Detection of encoding errors in **`_snwprintf`** might differ from that in **`_snprintf`**. **`_snwprintf`**, just like **`swprintf`**, writes output to a string instead of a destination of type **`FILE`**. +**`_snwprintf`** is a wide-character version of **`_snprintf`**; the pointer arguments to **`_snwprintf`** are wide-character strings. Detection of encoding errors in **`_snwprintf`** might differ from the detection in **`_snprintf`**. **`_snwprintf`**, just like **`swprintf`**, writes output to a string instead of a destination of type `FILE`. The versions of these functions that have the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, these functions have template overloads that invoke their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_sntprintf`**|**`_snprintf`**|**`_snprintf`**|**`_snwprintf`**| -|**`_sntprintf_l`**|**`_snprintf_l`**|**`_snprintf_l`**|**`_snwprintf_l`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sntprintf` | **`_snprintf`** | **`_snprintf`** | **`_snwprintf`** | +| `_sntprintf_l` | **`_snprintf_l`** | **`_snprintf_l`** | **`_snwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`snprintf`**, **`_snprintf`**, **`_snprintf_l`**|``| -|**`_snwprintf`**, **`_snwprintf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`snprintf`**, **`_snprintf`**, **`_snprintf_l`** | `` | +| **`_snwprintf`**, **`_snwprintf_l`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -263,10 +295,10 @@ character count = 69 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md b/docs/c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md index 5b7c23ac43..5b5fe1eb53 100644 --- a/docs/c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md +++ b/docs/c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md @@ -10,9 +10,9 @@ f1_keywords: ["_sntscanf_s", "snscanf_s", "_snwscanf_s_l", "sntscanf_s_l", "snws helpviewer_keywords: ["_snscanf_s_l function", "snwscanf_s function", "_snwscanf_s function", "sntscanf_s_l function", "sntscanf_s function", "_snwscanf_s_l function", "_snscanf_s function", "snscanf_s_l function", "strings [C++], reading data from", "_sntscanf_s_l function", "reading data, strings", "snscanf_s function", "strings [C++], reading", "_sntscanf_s function", "snwscanf_s_l function"] ms.assetid: 72356653-7362-461a-af73-597b9c0a8094 --- -# _snscanf_s, _snscanf_s_l, _snwscanf_s, _snwscanf_s_l +# `_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l` -Reads formatted data of a specified length from a string. These are versions of [_snscanf, _snscanf_l, _snwscanf, _snwscanf_l](snscanf-snscanf-l-snwscanf-snwscanf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data of a specified length from a string. These functions are versions of [`_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l`](snscanf-snscanf-l-snwscanf-snwscanf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -43,55 +43,55 @@ int __cdecl _snwscanf_s_l( ### Parameters -*input*
+*`input`*\ Input string to examine. -*length*
-Number of characters to examine in *input*. +*`length`*\ +Number of characters to examine in *`input`*. -*format*
+*`format`*\ One or more format specifiers. -*locale*
+*`locale`*\ The locale to use. -*argument_list*
+*`argument_list`*\ Optional arguments to be assigned according to the format string. -## Return Value +## Return value -Both of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. For more information, see [sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md). +Both of these functions return the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. For more information, see [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md). -If *input* or *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +If *`input`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -This function is like **sscanf_s** except that it provides the ability to specify a fixed number of characters to examine from the input string. For more information, see [sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md). +This function is like `sscanf_s`, except that it lets you specify a fixed number of characters to examine from the input string. For more information, see [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md). -The buffer size parameter is required with the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Type Field Characters](../../c-runtime-library/scanf-type-field-characters.md). +The buffer size parameter is required with the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Type Field Characters](../scanf-type-field-characters.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sntscanf_s**|**_snscanf_s**|**_snscanf_s**|**_snwscanf_s**| -|**_sntscanf_s_l**|**_snscanf_s_l**|**_snscanf_s_l**|**_snwscanf_s_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sntscanf_s` | **`_snscanf_s`** | **`_snscanf_s`** | **`_snwscanf_s`** | +| `_sntscanf_s_l` | **`_snscanf_s_l`** | **`_snscanf_s_l`** | **`_snwscanf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_snscanf_s**, **_snscanf_s_l**|\| -|**_snwscanf_s**, **_snwscanf_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_snscanf_s`**, **`_snscanf_s_l`** | \ | +| **`_snwscanf_s`**, **`_snwscanf_s_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -130,4 +130,4 @@ _snwscanf_s converted 2 fields: 15 and 12.000000 ## See also -[scanf Width Specification](../../c-runtime-library/scanf-width-specification.md)
+[scanf Width Specification](../scanf-width-specification.md) diff --git a/docs/c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md b/docs/c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md index a08e358e24..332bc229ee 100644 --- a/docs/c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md +++ b/docs/c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md @@ -10,9 +10,9 @@ f1_keywords: ["_snscanf", "_snscanf_l", "_snwscanf", "snscanf_l", "snscanf", "_s helpviewer_keywords: ["snscanf_l function", "snwscanf function", "_sntscanf_l function", "sntscanf function", "_snwscanf_l function", "_sntscanf function", "_snscanf_l function", "sntscanf_l function", "strings [C++], reading data from", "snscanf function", "snwscanf_l function", "_snwscanf function", "reading data, strings", "strings [C++], reading", "_snscanf function"] ms.assetid: da1ac890-f905-4cd7-954b-3c90957b5551 --- -# _snscanf, _snscanf_l, _snwscanf, _snwscanf_l +# `_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l` -Reads formatted data of a specified length from a string. More secure versions of these functions are available; see [_snscanf_s, _snscanf_s_l, _snwscanf_s, _snwscanf_s_l](snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md). +Reads formatted data of a specified length from a string. More secure versions of these functions are available; see [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md). ## Syntax @@ -47,50 +47,50 @@ int __cdecl _snwscanf_l( ### Parameters -*input*
+*`input`*\ Input string to examine. -*length*
-Number of characters to examine in *input*. +*`length`*\ +Number of characters to examine in *`input`*. -*format*
+*`format`*\ One or more format specifiers. -*...*
-Optional variables that will be used to store the values extracted from the input string by the format specifiers in *format*. +*`...`*\ +Optional variables that will be used to store the values extracted from the input string by the format specifiers in *`format`*. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Both of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. For more information, see [sscanf](sscanf-sscanf-l-swscanf-swscanf-l.md). +Both of these functions return the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. For more information, see [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md). -If *input* or *format* is a **NULL** pointer, or if *length* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +If *`input`* or *`format`* is a `NULL` pointer, or if *`length`* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -This function is like **sscanf** except that it provides the ability to specify a fixed number of characters to examine from the input string. For more information, see [sscanf](sscanf-sscanf-l-swscanf-swscanf-l.md). +This function is like `sscanf`, except that it lets you specify a fixed number of characters to examine from the input string. For more information, see [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sntscanf**|**_snscanf**|**_snscanf**|**_snwscanf**| -|**_sntscanf_l**|**_snscanf_l**|**_snscanf_l**|**_snwscanf_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sntscanf` | **`_snscanf`** | **`_snscanf`** | **`_snwscanf`** | +| `_sntscanf_l` | **`_snscanf_l`** | **`_snscanf_l`** | **`_snwscanf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_snscanf**, **_snscanf_l**|\| -|**_snwscanf**, **_snwscanf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_snscanf`**, **`_snscanf_l`** | \ | +| **`_snwscanf`**, **`_snwscanf_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -127,4 +127,4 @@ _snwscanf converted 2 fields: 15 and 12.000000 ## See also -[scanf Width Specification](../../c-runtime-library/scanf-width-specification.md)
+[scanf Width Specification](../scanf-width-specification.md) diff --git a/docs/c-runtime-library/reference/sopen-s-wsopen-s.md b/docs/c-runtime-library/reference/sopen-s-wsopen-s.md index 041d552695..04f2bd984a 100644 --- a/docs/c-runtime-library/reference/sopen-s-wsopen-s.md +++ b/docs/c-runtime-library/reference/sopen-s-wsopen-s.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _sopen_s, _wsopen_s" title: "_sopen_s, _wsopen_s" -ms.date: "4/2/2020" +description: "Learn more about: _sopen_s, _wsopen_s" +ms.date: 05/18/2022 api_name: ["_sopen_s", "_wsopen_s", "_o__sopen_s", "_o__wsopen_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_sopen_s", "wsopen_s", "_wsopen_s", "sopen_s"] +f1_keywords: ["CORECRT_IO/_sopen_s", "CORECRT_WIO/_wsopen_s", "TCHAR/_tsopen_s", "_sopen_s", "_wsopen_s", "_tsopen_s", "sopen_s", "wsopen_s"] helpviewer_keywords: ["sopen_s function", "_wsopen_s function", "wsopen_s function", "opening files, for sharing", "files [C++], opening", "_sopen_s function", "files [C++], sharing"] -ms.assetid: 059a0084-d08c-4973-9174-55e391b72aa2 --- # `_sopen_s`, `_wsopen_s` -Opens a file for sharing. These versions of [`_sopen` and `_wsopen`](sopen-wsopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Opens a file for sharing. These versions of [`_sopen` and `_wsopen`](sopen-wsopen.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -29,114 +28,114 @@ errno_t _wsopen_s( const wchar_t *filename, int oflag, int shflag, - int pmode, + int pmode ); ``` ### Parameters -*`pfh`*
-The file handle, or -1 in the case of an error. +*`pfh`*\ +The file handle, or -1 if there's an error. -*`filename`*
+*`filename`*\ File name. -*`oflag`*
+*`oflag`*\ The kind of operations allowed. -*`shflag`*
+*`shflag`*\ The kind of sharing allowed. -*`pmode`*
+*`pmode`*\ Permission setting. -## Return Value +## Return value -A nonzero return value indicates an error; in that case **`errno`** is set to one of the following values. +A nonzero return value indicates an error; in that case `errno` is set to one of the following values. -|errno value|Condition| -|-|-| -| **`EACCES`** | The given path is a directory, or the file is read-only, but an open-for-writing operation was attempted. | -| **`EEXIST`** | **`_O_CREAT`** and **`_O_EXCL`** flags were specified, but *`filename`* already exists. | -| **`EINVAL`** | Invalid *`oflag`*, *`shflag`*, or *`pmode`* argument, or *`pfh`* or *`filename`* was a null pointer. | -| **`EMFILE`** | No more file descriptors available. | -| **`ENOENT`** | File or path not found. | +| `errno` value | Condition | +|--|--| +| `EACCES` | The given path is a directory, or the file is read-only, but an open-for-writing operation was attempted. | +| `EEXIST` | `_O_CREAT` and `_O_EXCL` flags were specified, but *`filename`* already exists. | +| `EINVAL` | Invalid *`oflag`*, *`shflag`*, or *`pmode`* argument, or *`pfh`* or *`filename`* was a null pointer. | +| `EMFILE` | No more file descriptors available. | +| `ENOENT` | File or path not found. | -If an invalid argument is passed to the function, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`errno`** is set to **`EINVAL`** and **`EINVAL`** is returned. +If an invalid argument is passed to the function, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and `EINVAL` is returned. -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -In the case of an error, -1 is returned through *`pfh`* (unless *`pfh`* is a null pointer). +If there's an error, -1 is returned through *`pfh`* (unless *`pfh`* is a null pointer). ## Remarks The **`_sopen_s`** function opens the file specified by *`filename`* and prepares the file for shared reading or writing, as defined by *`oflag`* and *`shflag`*. **`_wsopen_s`** is a wide-character version of **`_sopen_s`**; the *`filename`* argument to **`_wsopen_s`** is a wide-character string. **`_wsopen_s`** and **`_sopen_s`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tsopen_s`**|**`_sopen_s`**|**`_sopen_s`**|**`_wsopen_s`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_tsopen_s`** | **`_sopen_s`** | **`_sopen_s`** | **`_wsopen_s`** | -The integer expression *oflag* is formed by combining one or more manifest constants, which are defined in ``. When two or more constants form the argument *`oflag`*, they are combined with the bitwise-OR operator ( **|** ). +The integer expression *`oflag`* is formed by combining one or more manifest constants, which are defined in ``. When two or more constants form the argument *`oflag`*, they're combined with the bitwise-OR operator ( **`|`** ). -|*oflag* constant|Behavior| -|-|-| -| **`_O_APPEND`** | Moves the file pointer to the end of the file before every write operation. | -| **`_O_BINARY`** | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | -| **`_O_CREAT`** | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | **`_O_SHORT_LIVED`** | Creates a file as temporary and if possible does not flush to disk. The *`pmode`* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT`** | `_O_EXCL` | Returns an error value if a file specified by *`filename`* exists. Applies only when used with **`_O_CREAT`**. | -| **`_O_NOINHERIT`** | Prevents creation of a shared file descriptor. | -| **`_O_RANDOM`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`_O_RDONLY`** | Opens a file for reading only. Cannot be specified with **`_O_RDWR`** or **`_O_WRONLY`**. | -| **`_O_RDWR`** | Opens a file for both reading and writing. Cannot be specified with **`_O_RDONLY`** or **`_O_WRONLY`**. | -| **`_O_SEQUENTIAL`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | -| **`_O_TEXT`** | Opens a file in text (translated) mode. (For more information, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | -| **`_O_TRUNC`** | Opens a file and truncates it to zero length; the file must have write permission. Cannot be specified with **`_O_RDONLY`**. **`_O_TRUNC`** used with **`_O_CREAT`** opens an existing file or creates a file. **Note:** The **`_O_TRUNC`** flag destroys the contents of the specified file. | -| **`_O_WRONLY`** | Opens a file for writing only. Cannot be specified with **`_O_RDONLY`** or **`_O_RDWR`**. | -| **`_O_U16TEXT`** | Opens a file in Unicode UTF-16 mode. | -| **`_O_U8TEXT`** | Opens a file in Unicode UTF-8 mode. | -| **`_O_WTEXT`** | Opens a file in Unicode mode. | +| *`oflag`* constant | Behavior | +|--|--| +| `_O_APPEND` | Moves the file pointer to the end of the file before every write operation. | +| `_O_BINARY` | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | +| `_O_CREAT` | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_SHORT_LIVED`** | Creates a file as temporary and if possible doesn't flush to disk. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when `_O_CREAT` is specified. To preserve legacy behavior for app-compatibility, other processes aren't prevented from deleting this file. | +| **`_O_CREAT | _O_EXCL`** | Returns an error value if a file specified by *`filename`* exists. Applies only when used with `_O_CREAT`. | +| `_O_NOINHERIT` | Prevents creation of a shared file descriptor. | +| `_O_RANDOM` | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| `_O_RDONLY` | Opens a file for reading only. Can't be specified with `_O_RDWR` or `_O_WRONLY`. | +| `_O_RDWR` | Opens a file for both reading and writing. Can't be specified with `_O_RDONLY` or `_O_WRONLY`. | +| `_O_SEQUENTIAL` | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| `_O_TEXT` | Opens a file in ANSI text (translated) mode. (For more information, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | +| `_O_TRUNC` | Opens a file and truncates it to zero length; the file must have write permission. Can't be specified with `_O_RDONLY`. `_O_TRUNC` used with `_O_CREAT` opens an existing file or creates a file. **Note:** The `_O_TRUNC` flag destroys the contents of the specified file. | +| `_O_WRONLY` | Opens a file for writing only. Can't be specified with `_O_RDONLY` or `_O_RDWR`. | +| `_O_U16TEXT` | Opens a file in Unicode UTF-16 mode. | +| `_O_U8TEXT` | Opens a file in Unicode UTF-8 mode. | +| `_O_WTEXT` | Opens a file in Unicode mode. | -To specify the file access mode, you must specify either **`_O_RDONLY`**, **`_O_RDWR`**, or **`_O_WRONLY`**. There is no default value for the access mode. +To specify the file access mode, you must specify either `_O_RDONLY`, `_O_RDWR`, or `_O_WRONLY`. There's no default value for the access mode. -When a file is opened in Unicode mode by using **`_O_WTEXT`**, **`_O_U8TEXT`**, or **`_O_U16TEXT`**, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it is written, and the file's UTF-8-encoded content is translated into UTF-16 when it is read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You are responsible for any required encoding translation. +When a file is opened in Unicode mode by using `_O_WTEXT`, `_O_U8TEXT`, or `_O_U16TEXT`, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If **`_sopen_s`** is called with **`_O_WRONLY`** | **`_O_APPEND`** (append mode) and **`_O_WTEXT`**, **`_O_U16TEXT`**, or **`_O_U8TEXT`**, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. +If **`_sopen_s`** is called with **`_O_WRONLY | _O_APPEND`** (append mode) and `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. The argument *`shflag`* is a constant expression that consists of one of the following manifest constants, which are defined in ``. -|*`shflag`* constant|Behavior| -|-|-| -| **`_SH_DENYRW`** | Denies read and write access to a file. | -| **`_SH_DENYWR`** | Denies write access to a file. | -| **`_SH_DENYRD`** | Denies read access to a file. | -| **`_SH_DENYNO`** | Permits read and write access. | +| *`shflag`* constant | Behavior | +|--|--| +| `_SH_DENYRW` | Denies read and write access to a file. | +| `_SH_DENYWR` | Denies write access to a file. | +| `_SH_DENYRD` | Denies read access to a file. | +| `_SH_DENYNO` | Permits read and write access. | -The *`pmode`* argument is always required, unlike in **`_sopen`**. When you specify **`_O_CREAT`**, if the file does not exist, *`pmode`* specifies the file's permission settings, which are set when the new file is closed the first time. Otherwise, *`pmode`* is ignored. *`pmode`* is an integer expression that contains one or both of the manifest constants **`_S_IWRITE`** and **`_S_IREAD`**, which are defined in ``. When both constants are given, they are combined with the bitwise-OR operator. The meaning of *`pmode`* is as follows. +The *`pmode`* argument is always required, unlike in **`_sopen`**. When you specify `_O_CREAT`, if the file doesn't exist, *`pmode`* specifies the file's permission settings, which are set when the new file is closed the first time. Otherwise, *`pmode`* is ignored. *`pmode`* is an integer expression that contains one or both of the manifest constants `_S_IWRITE` and `_S_IREAD`, which are defined in ``. When both constants are given, they're combined with the bitwise-OR operator. The meaning of *`pmode`* is as follows. -|*`pmode`*|Meaning| -|-|-| -| **`_S_IREAD`** | Only reading permitted. | -| **`_S_IWRITE`** | Writing permitted. (In effect, permits reading and writing.) | -| **`_S_IREAD`** | **`_S_IWRITE`** | Reading and writing permitted. | +| *`pmode`* | Meaning | +|--|--| +| `_S_IREAD` | Only reading permitted. | +| `_S_IWRITE` | Writing permitted. (In effect, permits reading and writing.) | +| **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -If write permission is not given, the file is read-only. In the Windows operating system, all files are readable; it is not possible to give write-only permission. Therefore, the modes **`_S_IWRITE`** and **`_S_IREAD`** | **`_S_IWRITE`** are equivalent. +If write permission isn't given, the file is read-only. In the Windows operating system, all files are readable; it isn't possible to give write-only permission. Therefore, the modes `_S_IWRITE` and **`_S_IREAD | _S_IWRITE`** are equivalent. **`_sopen_s`** applies the current file-permission mask to *`pmode`* before the permissions are set. (See [`_umask`](umask.md).) ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_sopen_s`**|``|``, ``, ``, ``| -|**`_wsopen_s`**|`` or ``|``, ``, ``, ``| +| Function | Required header | Optional header | +|--|--|--| +| **`_sopen_s`** | `` | ``, ``, ``, `` | +| **`_wsopen_s`** | `` or `` | ``, ``, ``, `` | -**`_sopen_s`** and **`_wsopen_s`** are Microsoft extensions. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_sopen_s`** and **`_wsopen_s`** are Microsoft extensions. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -144,9 +143,9 @@ See the example for [`_locking`](locking.md). ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[`_close`](close.md)
-[`_creat`, `_wcreat`](creat-wcreat.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`_fsopen`, `_wfsopen`](fsopen-wfsopen.md)
-[`_open`, `_wopen`](open-wopen.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fsopen`, `_wfsopen`](fsopen-wfsopen.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/sopen-wsopen.md b/docs/c-runtime-library/reference/sopen-wsopen.md index b36dd33e1e..c3e9b3a0aa 100644 --- a/docs/c-runtime-library/reference/sopen-wsopen.md +++ b/docs/c-runtime-library/reference/sopen-wsopen.md @@ -1,18 +1,18 @@ --- description: "Learn more about: _sopen, _wsopen" title: "_sopen, _wsopen" -ms.date: "4/2/2020" +ms.date: 05/18/2022 api_name: ["_sopen", "_wsopen", "_o__sopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wsopen", "wsopen", "_sopen", "_tsopen"] +f1_keywords: ["CORECRT_IO/_sopen", "CORECRT_WIO/_wsopen", "TCHAR/_tsopen", "_sopen", "_wsopen", "_tsopen", "sopen", "wsopen"] helpviewer_keywords: ["sopen function", "sharing files", "opening files, for sharing", "_sopen function", "wsopen function", "files [C++], opening", "files [C++], sharing", "_wsopen function"] ms.assetid: a9d4cccf-06e9-414d-96fa-453fca88cc1f --- -# _sopen, _wsopen +# `_sopen`, `_wsopen` -Opens a file for sharing. More secure versions of these functions are available: see [_sopen_s, _wsopen_s](sopen-s-wsopen-s.md). +Opens a file for sharing. More secure versions of these functions are available: see [`_sopen_s`, `_wsopen_s`](sopen-s-wsopen-s.md). ## Syntax @@ -33,113 +33,113 @@ int _wsopen( ### Parameters -*filename*
+*`filename`*\ File name. -*oflag*
+*`oflag`*\ The kind of operations allowed. -*shflag*
+*`shflag`*\ The kind of sharing allowed. -*pmode*
+*`pmode`*\ Permission setting. -## Return Value +## Return value Each of these functions returns a file descriptor for the opened file. -If *filename* or *oflag* is a **NULL** pointer, or if *oflag* or *shflag* is not within a valid range of values, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to one of the following values. +If *`filename`* or *`oflag`* is a `NULL` pointer, or if *`oflag`* or *`shflag`* isn't within a valid range of values, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to one of the following values. -|errno value|Condition| -|-|-| -| **EACCES** | The given path is a directory, or the file is read-only, but an open-for-writing operation was attempted. | -| **EEXIST** | **_O_CREAT** and **_O_EXCL** flags were specified, but *filename* already exists. | -| **EINVAL** | Invalid *oflag* or *shflag* argument. | -| **EMFILE** | No more file descriptors are available. | -| **ENOENT** | File or path is not found. | +| `errno` value | Condition | +|--|--| +| `EACCES` | The given path is a directory, or the file is read-only, but an open-for-writing operation was attempted. | +| `EEXIST` | `_O_CREAT` and `_O_EXCL` flags were specified, but *`filename`* already exists. | +| `EINVAL` | Invalid *`oflag`* or *`shflag`* argument. | +| `EMFILE` | No more file descriptors are available. | +| `ENOENT` | File or path isn't found. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_sopen** function opens the file specified by *filename* and prepares the file for shared reading or writing, as defined by *oflag* and *shflag*. **_wsopen** is a wide-character version of **_sopen**; the *filename* argument to **_wsopen** is a wide-character string. **_wsopen** and **_sopen** behave identically otherwise. +The **`_sopen`** function opens the file specified by *`filename`* and prepares the file for shared reading or writing, as defined by *`oflag`* and *`shflag`*. **`_wsopen`** is a wide-character version of **`_sopen`**; the *`filename`* argument to **`_wsopen`** is a wide-character string. **`_wsopen`** and **`_sopen`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsopen**|**_sopen**|**_sopen**|**_wsopen**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|--|--|--|--| +| **`_tsopen`** | **`_sopen`** | **`_sopen`** | **`_wsopen`** | -The integer expression *oflag* is formed by combining one or more of the following manifest constants, which are defined in \. When two or more constants form the argument *oflag*, they are combined with the bitwise-OR operator ( **|** ). +The integer expression *`oflag`* is formed by combining one or more of the following manifest constants, which are defined in ``. When two or more constants form the argument *`oflag`*, they're combined with the bitwise-OR operator ( **`|`** ). -|*oflag* constant|Behavior| -|-|-| -| **_O_APPEND** | Moves the file pointer to the end of the file before every write operation. | -| **_O_BINARY** | Opens the file in binary (untranslated) mode. (See [fopen](fopen-wfopen.md) for a description of binary mode.) | -| **_O_CREAT** | Creates a file and opens it for writing. Has no effect if the file specified by *filename* exists. The *pmode* argument is required when **_O_CREAT** is specified. | -| **_O_CREAT** | **_O_SHORT_LIVED** | Creates a file as temporary and if possible does not flush to disk. The *pmode* argument is required when **_O_CREAT** is specified. | -| **_O_CREAT** | **_O_TEMPORARY** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **_O_CREAT** is specified. | -| **_O_CREAT** | `_O_EXCL` | Returns an error value if a file specified by *filename* exists. Applies only when used with **_O_CREAT**. | -| **_O_NOINHERIT** | Prevents creation of a shared file descriptor. | -| **_O_RANDOM** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **_O_RDONLY** | Opens a file for reading only. Cannot be specified with **_O_RDWR** or **_O_WRONLY**. | -| **_O_RDWR** | Opens a file for both reading and writing. Cannot be specified with **_O_RDONLY** or **_O_WRONLY**. | -| **_O_SEQUENTIAL** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | -| **_O_TEXT** | Opens a file in text (translated) mode. (For more information, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [fopen](fopen-wfopen.md).) | -| **_O_TRUNC** | Opens a file and truncates it to zero length; the file must have write permission. Cannot be specified with **_O_RDONLY**. **_O_TRUNC** used with **_O_CREAT** opens an existing file or creates a file. **Note:** The **_O_TRUNC** flag destroys the contents of the specified file. | -| **_O_WRONLY** | Opens a file for writing only. Cannot be specified with **_O_RDONLY** or **_O_RDWR**. | -| **_O_U16TEXT** | Opens a file in Unicode UTF-16 mode. | -| **_O_U8TEXT** | Opens a file in Unicode UTF-8 mode. | -| **_O_WTEXT** | Opens a file in Unicode mode. | +| *`oflag`* constant | Behavior | +|--|--| +| `_O_APPEND` | Moves the file pointer to the end of the file before every write operation. | +| `_O_BINARY` | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | +| `_O_CREAT` | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_SHORT_LIVED`** | Creates a file as temporary and if possible doesn't flush to disk. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when `_O_CREAT` is specified. To preserve legacy behavior for app-compatibility, other processes aren't prevented from deleting this file. | +| **`_O_CREAT | _O_EXCL`** | Returns an error value if a file specified by *`filename`* exists. Applies only when used with `_O_CREAT`. | +| `_O_NOINHERIT` | Prevents creation of a shared file descriptor. | +| `_O_RANDOM` | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| `_O_RDONLY` | Opens a file for reading only. Can't be specified with `_O_RDWR` or `_O_WRONLY`. | +| `_O_RDWR` | Opens a file for both reading and writing. Can't be specified with `_O_RDONLY` or `_O_WRONLY`. | +| `_O_SEQUENTIAL` | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| `_O_TEXT` | Opens a file in ANSI text (translated) mode. (For more information, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | +| `_O_TRUNC` | Opens a file and truncates it to zero length; the file must have write permission. Can't be specified with `_O_RDONLY`. `_O_TRUNC` used with `_O_CREAT` opens an existing file or creates a file. **Note:** The `_O_TRUNC` flag destroys the contents of the specified file. | +| `_O_WRONLY` | Opens a file for writing only. Can't be specified with `_O_RDONLY` or `_O_RDWR`. | +| `_O_U16TEXT` | Opens a file in Unicode UTF-16 mode. | +| `_O_U8TEXT` | Opens a file in Unicode UTF-8 mode. | +| `_O_WTEXT` | Opens a file in Unicode mode. | -To specify the file access mode, you must specify either **_O_RDONLY**, **_O_RDWR**, or **_O_WRONLY**. There is no default value for the access mode. +To specify the file access mode, you must specify either `_O_RDONLY`, `_O_RDWR`, or `_O_WRONLY`. There's no default value for the access mode. -When a file is opened in Unicode mode by using **_O_WTEXT**, **_O_U8TEXT**, or **_O_U16TEXT**, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it is written, and the file's UTF-8-encoded content is translated into UTF-16 when it is read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You are responsible for any required encoding translation. +When a file is opened in Unicode mode by using `_O_WTEXT`, `_O_U8TEXT`, or `_O_U16TEXT`, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If **_sopen** is called with **_O_WRONLY** | **_O_APPEND** (append mode) and **_O_WTEXT**, **_O_U16TEXT**, or **_O_U8TEXT**, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. +If **`_sopen`** is called with `_O_WRONLY` | `_O_APPEND` (append mode) and `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. -The argument *shflag* is a constant expression consisting of one of the following manifest constants, which are defined in \. +The argument *`shflag`* is a constant expression consisting of one of the following manifest constants, which are defined in ``. -|*shflag* constant|Behavior| -|-|-| -| **_SH_DENYRW** | Denies read and write access to a file. | -| **_SH_DENYWR** | Denies write access to a file. | -| **_SH_DENYRD** | Denies read access to a file. | -| **_SH_DENYNO** | Permits read and write access. | +| *`shflag`* constant | Behavior | +|--|--| +| `_SH_DENYRW` | Denies read and write access to a file. | +| `_SH_DENYWR` | Denies write access to a file. | +| `_SH_DENYRD` | Denies read access to a file. | +| `_SH_DENYNO` | Permits read and write access. | -The *pmode* argument is required only when **_O_CREAT** is specified. If the file does not exist, *pmode* specifies the file's permission settings, which are set when the new file is closed the first time. Otherwise, *pmode* is ignored. *pmode* is an integer expression that contains one or both of the manifest constants **_S_IWRITE** and **_S_IREAD**, which are defined in \. When both constants are given, they are combined with the bitwise-OR operator. The meaning of *pmode* is as follows. +The *`pmode`* argument is required only when `_O_CREAT` is specified. If the file doesn't exist, *`pmode`* specifies the file's permission settings, which are set when the new file is closed the first time. Otherwise, *`pmode`* is ignored. *`pmode`* is an integer expression that contains one or both of the manifest constants `_S_IWRITE` and `_S_IREAD`, which are defined in ``. When both constants are given, they're combined with the bitwise-OR operator. The meaning of *`pmode`* is as follows. -|*pmode*|Meaning| -|-|-| -| **_S_IREAD** | Only reading permitted. | -| **_S_IWRITE** | Writing permitted. (In effect, permits reading and writing.) | -| **_S_IREAD** | **_S_IWRITE** | Reading and writing permitted. | +| *`pmode`* | Meaning | +|--|--| +| `_S_IREAD` | Only reading permitted. | +| `_S_IWRITE` | Writing permitted. (In effect, permits reading and writing.) | +| **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -If write permission is not given, the file is read-only. In the Windows operating system, all files are readable; it is not possible to give write-only permission. Therefore, the modes **_S_IWRITE** and **_S_IREAD** | **_S_IWRITE** are equivalent. +If write permission isn't given, the file is read-only. In the Windows operating system, all files are readable; it isn't possible to give write-only permission. Therefore, the modes `_S_IWRITE` and **`_S_IREAD | _S_IWRITE`** are equivalent. -**_sopen** applies the current file-permission mask to *pmode* before the permissions are set. (See [_umask](umask.md).) +**`_sopen`** applies the current file-permission mask to *`pmode`* before the permissions are set. For more information, see [`_umask`](umask.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_sopen**|\|\, \, \, \| -|**_wsopen**|\ or \|\, \, \, \| +| Function | Required header | Optional header | +|--|--|--| +| **`_sopen`** | `` | ``, ``, ``, `` | +| **`_wsopen`** | `` or `` | ``, ``, ``, `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_locking](locking.md). +See the example for [`_locking`](locking.md). ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_close](close.md)
-[_creat, _wcreat](creat-wcreat.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[_fsopen, _wfsopen](fsopen-wfsopen.md)
-[_open, _wopen](open-wopen.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`_close`](close.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fsopen`, `_wfsopen`](fsopen-wfsopen.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/sopen.md b/docs/c-runtime-library/reference/sopen.md index 324b2d8d17..f0d4fede70 100644 --- a/docs/c-runtime-library/reference/sopen.md +++ b/docs/c-runtime-library/reference/sopen.md @@ -10,8 +10,8 @@ f1_keywords: ["sopen"] helpviewer_keywords: ["sopen function"] ms.assetid: 1ce0b707-0c9e-4942-8467-ce7f6cd68acc --- -# sopen +# `sopen` -The Microsoft-specific function name `sopen` is a deprecated alias for the [_sopen](sopen-wsopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `sopen` is a deprecated alias for the [`_sopen`](sopen-wsopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_sopen](sopen-wsopen.md) or the security-enhanced [_sopen_s](sopen-s-wsopen-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_sopen`](sopen-wsopen.md) or the security-enhanced [`_sopen_s`](sopen-s-wsopen-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/spawnl-wspawnl.md b/docs/c-runtime-library/reference/spawnl-wspawnl.md index 6fcd0d4116..8cbc9171a7 100644 --- a/docs/c-runtime-library/reference/spawnl-wspawnl.md +++ b/docs/c-runtime-library/reference/spawnl-wspawnl.md @@ -10,7 +10,7 @@ f1_keywords: ["wspawnl", "_wspawnl", "_spawnl"] helpviewer_keywords: ["spawnl function", "processes, creating", "_spawnl function", "processes, executing new", "_wspawnl function", "wspawnl function", "process creation"] ms.assetid: dd4584c9-7173-4fc5-b93a-6e7d3c2316d7 --- -# _spawnl, _wspawnl +# `_spawnl`, `_wspawnl` Creates and executes a new process. @@ -40,30 +40,30 @@ intptr_t _wspawnl( ### Parameters -*mode*
+*`mode`*\ Execution mode for the calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, *arg1*, ... *argn*
-List of pointers to arguments. The *arg0* argument is usually a pointer to *cmdname*. The arguments *arg1* through *argn* are pointers to the character strings forming the new argument list. Following *argn*, there must be a **NULL** pointer to mark the end of the argument list. +*`arg0`*, *`arg1`*, ... *`argN`*\ +List of pointers to arguments. The *`arg0`* argument is usually a pointer to *`cmdname`*. The arguments *`arg1`* through *`argN`* are pointers to the character strings forming the new argument list. Following *`argN`*, there must be a `NULL` pointer to mark the end of the argument list. -## Return Value +## Return value -The return value from a synchronous **_spawnl** or **_wspawnl** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnl** or **_wspawnl** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnl`** or **`_wspawnl`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnl`** or **`_wspawnl`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |--|--| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -These functions validate their parameters. If either *cmdname* or *arg0* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`arg0`* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. ## Remarks @@ -71,27 +71,27 @@ Each of these functions creates and executes a new process, passing each command ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnl**|\| -|**_wspawnl**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnl`** | \ | +| **`_wspawnl`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnl.md b/docs/c-runtime-library/reference/spawnl.md index 77596e47d7..d925222caf 100644 --- a/docs/c-runtime-library/reference/spawnl.md +++ b/docs/c-runtime-library/reference/spawnl.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnl"] helpviewer_keywords: ["spawnl function"] ms.assetid: ae762de9-e761-4fb7-bb63-b7904ed09a98 --- -# spawnl +# `spawnl` -The Microsoft-specific function name `spawnl` is a deprecated alias for the [_spawnl](spawnl-wspawnl.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnl` is a deprecated alias for the [`_spawnl`](spawnl-wspawnl.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnl](spawnl-wspawnl.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnl`](spawnl-wspawnl.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnle-wspawnle.md b/docs/c-runtime-library/reference/spawnle-wspawnle.md index af3c868219..74aeaa3b39 100644 --- a/docs/c-runtime-library/reference/spawnle-wspawnle.md +++ b/docs/c-runtime-library/reference/spawnle-wspawnle.md @@ -10,7 +10,7 @@ f1_keywords: ["_spawnle", "wspawnle", "_wspawnle"] helpviewer_keywords: ["spawnle function", "processes, creating", "_wspawnle function", "processes, executing new", "process creation", "wspawnle function", "_spawnle function"] ms.assetid: 80308892-2815-49b1-8cca-53894c366f5a --- -# _spawnle, _wspawnle +# `_spawnle`, `_wspawnle` Creates and executes a new process. @@ -42,61 +42,61 @@ intptr_t _wspawnle( ### Parameters -*mode*
+*`mode`*\ Execution mode for the calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, *arg1*, ... *argn*
-List of pointers to arguments. The *arg0* argument is usually a pointer to *cmdname*. The arguments *arg1* through *argn* are pointers to the character strings forming the new argument list. Following *argn*, there must be a **NULL** pointer to mark the end of the argument list. +*`arg0`*, *`arg1`*, ... *`argN`*\ +List of pointers to arguments. The *`arg0`* argument is usually a pointer to *`cmdname`*. The arguments *`arg1`* through *`argN`* are pointers to the character strings forming the new argument list. Following *`argN`*, there must be a `NULL` pointer to mark the end of the argument list. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -The return value from a synchronous **_spawnle** or **_wspawnle** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnle** or **_wspawnle** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnle`** or **`_wspawnle`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnle`** or **`_wspawnle`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |--|--| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions creates and executes a new process, passing each command-line argument as a separate parameter and also passing an array of pointers to environment settings. -These functions validate their parameters. If either *cmdname* or *arg0* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`arg0`* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnle**|\| -|**_wspawnle**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnle`** | \ | +| **`_wspawnle`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnle.md b/docs/c-runtime-library/reference/spawnle.md index 6ce095df9e..49df386050 100644 --- a/docs/c-runtime-library/reference/spawnle.md +++ b/docs/c-runtime-library/reference/spawnle.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnle"] helpviewer_keywords: ["spawnle function"] ms.assetid: 7c90cfdd-dcee-4ea6-b709-cd0f7598b0fe --- -# spawnle +# `spawnle` -The Microsoft-specific function name `spawnle` is a deprecated alias for the [_spawnle](spawnle-wspawnle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnle` is a deprecated alias for the [`_spawnle`](spawnle-wspawnle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnle](spawnle-wspawnle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnle`](spawnle-wspawnle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnlp-wspawnlp.md b/docs/c-runtime-library/reference/spawnlp-wspawnlp.md index c310da4a8c..d12f2116a1 100644 --- a/docs/c-runtime-library/reference/spawnlp-wspawnlp.md +++ b/docs/c-runtime-library/reference/spawnlp-wspawnlp.md @@ -10,7 +10,7 @@ f1_keywords: ["_wspawnlp", "wspawnlp", "_spawnlp"] helpviewer_keywords: ["wspawnlp function", "_spawnlp function", "processes, creating", "processes, executing new", "_wspawnlp function", "process creation", "spawnlp function"] ms.assetid: 74fc6e7a-4f24-4103-9387-7177875875e6 --- -# _spawnlp, _wspawnlp +# `_spawnlp`, `_wspawnlp` Creates and executes a new process. @@ -40,58 +40,58 @@ intptr_t _wspawnlp( ### Parameters -*mode*
+*`mode`*\ Execution mode for the calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, *arg1*, ... *argn*
-List of pointers to arguments. The *arg0* argument is usually a pointer to *cmdname*. The arguments *arg1* through *argn* are pointers to the character strings forming the new argument list. Following *argn*, there must be a **NULL** pointer to mark the end of the argument list. +*`arg0`*, *`arg1`*, ... *`argN`*\ +List of pointers to arguments. The *`arg0`* argument is usually a pointer to *`cmdname`*. The arguments *`arg1`* through *`argN`* are pointers to the character strings forming the new argument list. Following *`argN`*, there must be a `NULL` pointer to mark the end of the argument list. -## Return Value +## Return value -The return value from a synchronous **_spawnlp** or **_wspawnlp** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnlp** or **_wspawnlp** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnlp`** or **`_wspawnlp`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnlp`** or **`_wspawnlp`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions creates and executes a new process, passing each command-line argument as a separate parameter and using the **PATH** environment variable to find the file to execute. +Each of these functions creates and executes a new process, passing each command-line argument as a separate parameter and using the `PATH` environment variable to find the file to execute. -These functions validate their parameters. If either *cmdname* or *arg0* is an empty string or a null pointer, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`arg0`* is an empty string or a null pointer, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnlp**|\| -|**_wspawnlp**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnlp`** | \ | +| **`_wspawnlp`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnlp.md b/docs/c-runtime-library/reference/spawnlp.md index 3567582639..359d34891d 100644 --- a/docs/c-runtime-library/reference/spawnlp.md +++ b/docs/c-runtime-library/reference/spawnlp.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnlp"] helpviewer_keywords: ["spawnlp function"] ms.assetid: 560da96f-4902-4620-8a92-0d128ecaa001 --- -# spawnlp +# `spawnlp` -The Microsoft-specific function name `spawnlp` is a deprecated alias for the [_spawnlp](spawnlp-wspawnlp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnlp` is a deprecated alias for the [`_spawnlp`](spawnlp-wspawnlp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnlp](spawnlp-wspawnlp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnlp`](spawnlp-wspawnlp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md b/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md index 1887c78deb..ba64988fa6 100644 --- a/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md +++ b/docs/c-runtime-library/reference/spawnlpe-wspawnlpe.md @@ -10,7 +10,7 @@ f1_keywords: ["_wspawnlpe", "_spawnlpe", "wspawnlpe"] helpviewer_keywords: ["_wspawnlpe function", "wspawnlpe function", "processes, creating", "spawnlpe function", "_spawnlpe function", "processes, executing new", "process creation"] ms.assetid: e171ebfa-70e7-4c44-8331-2a291fc17bd6 --- -# _spawnlpe, _wspawnlpe +# `_spawnlpe`, `_wspawnlpe` Creates and executes a new process. @@ -42,61 +42,61 @@ intptr_t _wspawnlpe( ### Parameters -*mode*
+*`mode`*\ Execution mode for the calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, *arg1*, ... *argn*
-List of pointers to arguments. The *arg0* argument is typically a pointer to *cmdname*. The arguments *arg1* through *argn* are pointers to the character strings that form the new argument list. Following *argn*, there must be a **NULL** pointer to mark the end of the argument list. +*`arg0`*, *`arg1`*, ... *`argN`*\ +List of pointers to arguments. The *`arg0`* argument is typically a pointer to *`cmdname`*. The arguments *`arg1`* through *`argN`* are pointers to the character strings that form the new argument list. Following *`argN`*, there must be a `NULL` pointer to mark the end of the argument list. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -The return value from a synchronous **_spawnlpe** or **_wspawnlpe** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnlpe** or **_wspawnlpe** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically uses a nonzero argument to call the **exit** routine. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit caused by an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnlpe`** or **`_wspawnlpe`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnlpe`** or **`_wspawnlpe`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically uses a nonzero argument to call the `exit` routine. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit caused by an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions creates and executes a new process, passes each command-line argument as a separate parameter, and passes an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions creates and executes a new process, passes each command-line argument as a separate parameter, and passes an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -These functions validate their parameters. If either *cmdname* or *arg0* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`arg0`* is an empty string or a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnlpe**|\| -|**_wspawnlpe**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnlpe`** | \ | +| **`_wspawnlpe`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnlpe.md b/docs/c-runtime-library/reference/spawnlpe.md index 6a97e015b1..42fe6e7b82 100644 --- a/docs/c-runtime-library/reference/spawnlpe.md +++ b/docs/c-runtime-library/reference/spawnlpe.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnlpe"] helpviewer_keywords: ["spawnlpe function"] ms.assetid: 379143a7-f3d0-41de-83cc-2b4321146390 --- -# spawnlpe +# `spawnlpe` -The Microsoft-specific function name `spawnlpe` is a deprecated alias for the [_spawnlpe](spawnlpe-wspawnlpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnlpe` is a deprecated alias for the [`_spawnlpe`](spawnlpe-wspawnlpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnlpe](spawnlpe-wspawnlpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnlpe`](spawnlpe-wspawnlpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnv-wspawnv.md b/docs/c-runtime-library/reference/spawnv-wspawnv.md index 1f9b2ec7b9..bdd1f4a3c0 100644 --- a/docs/c-runtime-library/reference/spawnv-wspawnv.md +++ b/docs/c-runtime-library/reference/spawnv-wspawnv.md @@ -3,14 +3,14 @@ description: "Learn more about: _spawnv, _wspawnv" title: "_spawnv, _wspawnv" ms.date: "4/2/2020" api_name: ["_wspawnv", "_spawnv", "_o__spawnv", "_o__wspawnv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wspawnv", "_spawnv", "_wspawnv"] helpviewer_keywords: ["wspawnv function", "processes, creating", "_spawnv function", "processes, executing new", "process creation", "_wspawnv function", "spawnv function"] ms.assetid: 72360ef4-dfa9-44c1-88c1-b3ecb660aa7d --- -# _spawnv, _wspawnv +# `_spawnv`, `_wspawnv` Creates and executes a new process. @@ -34,60 +34,60 @@ intptr_t _wspawnv( ### Parameters -*mode*
+*`mode`*\ Execution mode for the calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*argv*
-Array of pointers to arguments. The argument *argv*[0] is usually a pointer to a path in real mode or to the program name in protected mode, and *argv*[1] through *argv*[**n**] are pointers to the character strings forming the new argument list. The argument *argv*[**n** +1] must be a **NULL** pointer to mark the end of the argument list. +*`argv`*\ +Array of pointers to arguments. The argument *`argv[0]`* is usually a pointer to a path in real mode or to the program name in protected mode, and *`argv[1]`* through *`argv[n]`* are pointers to the character strings forming the new argument list. The argument *`argv[n+1]`* must be a `NULL` pointer to mark the end of the argument list. -## Return Value +## Return value -The return value from a synchronous **_spawnv** or **_wspawnv** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnv** or **_wspawnv** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnv`** or **`_wspawnv`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnv`** or **`_wspawnv`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions creates and executes a new process, passing an array of pointers to command-line arguments. -These functions validate their parameters. If either *cmdname* or *argv* is a null pointer, or if *argv* points to null pointer, or *argv*[0] is an empty string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`argv`* is a null pointer, or if *`argv`* points to null pointer, or *`argv[0]`* is an empty string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnv**|\ or \| -|**_wspawnv**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnv`** | \ or \ | +| **`_wspawnv`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnv.md b/docs/c-runtime-library/reference/spawnv.md index 4df5a81eee..567364c5fd 100644 --- a/docs/c-runtime-library/reference/spawnv.md +++ b/docs/c-runtime-library/reference/spawnv.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnv"] helpviewer_keywords: ["spawnv function"] ms.assetid: 6f9b247c-1524-4c24-b846-6925fe22f1cd --- -# spawnv +# `spawnv` -The Microsoft-specific function name `spawnv` is a deprecated alias for the [_spawnv](spawnv-wspawnv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnv` is a deprecated alias for the [`_spawnv`](spawnv-wspawnv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnv](spawnv-wspawnv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnv`](spawnv-wspawnv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnve-wspawnve.md b/docs/c-runtime-library/reference/spawnve-wspawnve.md index 5aa6034816..0806e4f23e 100644 --- a/docs/c-runtime-library/reference/spawnve-wspawnve.md +++ b/docs/c-runtime-library/reference/spawnve-wspawnve.md @@ -3,14 +3,14 @@ description: "Learn more about: _spawnve, _wspawnve" title: "_spawnve, _wspawnve" ms.date: "4/2/2020" api_name: ["_spawnve", "_wspawnve", "_o__spawnve", "_o__wspawnve"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wspawnve", "_spawnve", "_wspawnve"] helpviewer_keywords: ["_spawnve function", "spawnve function", "wspawnve function", "processes, creating", "_wspawnve function", "processes, executing new", "process creation"] ms.assetid: 26d1713d-b551-4f21-a07b-e9891a2ae6cf --- -# _spawnve, _wspawnve +# `_spawnve`, `_wspawnve` Creates and executes a new process. @@ -36,63 +36,63 @@ intptr_t _wspawnve( ### Parameters -*mode*
+*`mode`*\ Execution mode for a calling process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*argv*
-Array of pointers to arguments. The argument *argv*[0] is usually a pointer to a path in real mode or to the program name in protected mode, and *argv*[1] through *argv*[**n**] are pointers to the character strings forming the new argument list. The argument *argv*[**n** +1] must be a **NULL** pointer to mark the end of the argument list. +*`argv`*\ +Array of pointers to arguments. The argument *`argv[0]`* is usually a pointer to a path in real mode or to the program name in protected mode, and *`argv[1]`* through *`argv[n]`* are pointers to the character strings forming the new argument list. The argument *`argv[n+1]`* must be a `NULL` pointer to mark the end of the argument list. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -The return value from a synchronous **_spawnve** or **_wspawnve** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnve** or **_wspawnve** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values. +The return value from a synchronous **`_spawnve`** or **`_wspawnve`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnve`** or **`_wspawnve`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values. | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions creates and executes a new process, passing an array of pointers to command-line arguments and an array of pointers to environment settings. -These functions validate their parameters. If either *cmdname* or *argv* is a null pointer, or if *argv* points to null pointer, or *argv*[0] is an empty string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`argv`* is a null pointer, or if *`argv`* points to null pointer, or *`argv[0]`* is an empty string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnve**|\ or \| -|**_wspawnve**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnve`** | \ or \ | +| **`_wspawnve`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnve.md b/docs/c-runtime-library/reference/spawnve.md index 73a77e7475..5bddb17dbd 100644 --- a/docs/c-runtime-library/reference/spawnve.md +++ b/docs/c-runtime-library/reference/spawnve.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnve"] helpviewer_keywords: ["spawnve function"] ms.assetid: 39507df8-f15f-45fb-b2b6-01359272b147 --- -# spawnve +# `spawnve` -The Microsoft-specific function name `spawnve` is a deprecated alias for the [_spawnve](spawnve-wspawnve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnve` is a deprecated alias for the [`_spawnve`](spawnve-wspawnve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnve](spawnve-wspawnve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnve`](spawnve-wspawnve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnvp-wspawnvp.md b/docs/c-runtime-library/reference/spawnvp-wspawnvp.md index b6e8050c01..1dfd293d66 100644 --- a/docs/c-runtime-library/reference/spawnvp-wspawnvp.md +++ b/docs/c-runtime-library/reference/spawnvp-wspawnvp.md @@ -3,14 +3,14 @@ description: "Learn more about: _spawnvp, _wspawnvp" title: "_spawnvp, _wspawnvp" ms.date: "4/2/2020" api_name: ["_wspawnvp", "_spawnvp", "_o__spawnvp", "_o__wspawnvp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wspawnvp", "_spawnvp", "wspawnvp"] helpviewer_keywords: ["wspawnvp function", "processes, creating", "_wspawnvp function", "processes, executing new", "spawnvp function", "process creation", "_spawnvp function"] ms.assetid: 8d8774ec-6ad4-4680-a5aa-440cde1e0249 --- -# _spawnvp, _wspawnvp +# `_spawnvp`, `_wspawnvp` Creates a process and executes it. @@ -34,60 +34,60 @@ intptr_t _wspawnvp( ### Parameters -*mode*
+*`mode`*\ Execution mode for calling the process. -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*argv*
-Array of pointers to arguments. The argument *argv*[0] is usually a pointer to a path in real mode or to the program name in protected mode, and *argv*[1] through *argv*[**n**] are pointers to the character strings that form the new argument list. The argument *argv*[**n** +1] must be a **NULL** pointer to mark the end of the argument list. +*`argv`*\ +Array of pointers to arguments. The argument *`argv[0]`* is usually a pointer to a path in real mode or to the program name in protected mode, and *`argv[1]`* through *`argv[n]`* are pointers to the character strings forming the new argument list. The argument *`argv[n+1]`* must be a `NULL` pointer to mark the end of the argument list. -## Return Value +## Return value -The return value from a synchronous **_spawnvp** or **_wspawnvp** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnvp** or **_wspawnvp** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically uses a nonzero argument to call the **exit** routine. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values: +The return value from a synchronous **`_spawnvp`** or **`_wspawnvp`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnvp`** or **`_wspawnvp`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically uses a nonzero argument to call the `exit` routine. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values: | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -For more information about these, and other, return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions creates a new process and executes it, and passes an array of pointers to command-line arguments and uses the **PATH** environment variable to find the file to execute. +Each of these functions creates a new process and executes it, and passes an array of pointers to command-line arguments and uses the `PATH` environment variable to find the file to execute. -These functions validate their parameters. If either *cmdname* or *argv* is a null pointer, or if *argv* points to null pointer, or *argv*[0] is an empty string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`argv`* is a null pointer, or if *`argv`* points to null pointer, or *`argv[0]`* is an empty string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnvp**|\ or \| -|**_wspawnvp**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnvp`** | \ or \ | +| **`_wspawnvp`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnvp.md b/docs/c-runtime-library/reference/spawnvp.md index 0605fc845b..5dccb599f4 100644 --- a/docs/c-runtime-library/reference/spawnvp.md +++ b/docs/c-runtime-library/reference/spawnvp.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnvp"] helpviewer_keywords: ["spawnvp function"] ms.assetid: 25d3896d-1934-4453-ae8b-4fb5480a2657 --- -# spawnvp +# `spawnvp` -The Microsoft-specific function name `spawnvp` is a deprecated alias for the [_spawnvp](spawnvp-wspawnvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnvp` is a deprecated alias for the [`_spawnvp`](spawnvp-wspawnvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnvp](spawnvp-wspawnvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnvp`](spawnvp-wspawnvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md b/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md index d1e00b721c..70de67c31e 100644 --- a/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md +++ b/docs/c-runtime-library/reference/spawnvpe-wspawnvpe.md @@ -3,14 +3,14 @@ description: "Learn more about: _spawnvpe, _wspawnvpe" title: "_spawnvpe, _wspawnvpe" ms.date: "4/2/2020" api_name: ["_spawnvpe", "_wspawnvpe", "_o__spawnvpe", "_o__wspawnvpe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_spawnvpe", "wspawnvpe", "_wspawnvpe"] helpviewer_keywords: ["_wspawnvpe function", "processes, creating", "_spawnvpe function", "processes, executing new", "wspawnvpe function", "process creation", "spawnvpe function"] ms.assetid: 3db6394e-a955-4837-97a1-fab1db1e6092 --- -# _spawnvpe, _wspawnvpe +# `_spawnvpe`, `_wspawnvpe` Creates and executes a new process. @@ -36,61 +36,61 @@ intptr_t _wspawnvpe( ### Parameters -*mode*
+*`mode`*\ Execution mode for calling process -*cmdname*
+*`cmdname`*\ Path of file to be executed -*argv*
-Array of pointers to arguments. The argument *argv*[0] is usually a pointer to a path in real mode or to the program name in protected mode, and *argv*[1] through *argv*[**n**] are pointers to the character strings forming the new argument list. The argument *argv*[**n** +1] must be a **NULL** pointer to mark the end of the argument list. +*`argv`*\ +Array of pointers to arguments. The argument *`argv[0]`* is usually a pointer to a path in real mode or to the program name in protected mode, and *`argv[1]`* through *`argv[n]`* are pointers to the character strings forming the new argument list. The argument *`argv[n+1]`* must be a `NULL` pointer to mark the end of the argument list. -*envp*
+*`envp`*\ Array of pointers to environment settings -## Return Value +## Return value -The return value from a synchronous **_spawnvpe** or **_wspawnvpe** (**_P_WAIT** specified for *mode*) is the exit status of the new process. The return value from an asynchronous **_spawnvpe** or **_wspawnvpe** (**_P_NOWAIT** or **_P_NOWAITO** specified for *mode*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the **exit** routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process is not started). In this case, **errno** is set to one of the following values: +The return value from a synchronous **`_spawnvpe`** or **`_wspawnvpe`** (`_P_WAIT` specified for *`mode`*) is the exit status of the new process. The return value from an asynchronous **`_spawnvpe`** or **`_wspawnvpe`** (`_P_NOWAIT` or `_P_NOWAITO` specified for *`mode`*) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically calls the `exit` routine with a nonzero argument. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, `errno` is set to one of the following values: | Value | Description | |-|-| -| **E2BIG** | Argument list exceeds 1024 bytes. | -| **EINVAL** | *mode* argument is invalid. | -| **ENOENT** | File or path is not found. | -| **ENOEXEC** | Specified file is not executable or has invalid executable-file format. | -| **ENOMEM** | Not enough memory is available to execute the new process. | +| `E2BIG` | Argument list exceeds 1024 bytes. | +| `EINVAL` | *`mode`* argument is invalid. | +| `ENOENT` | File or path isn't found. | +| `ENOEXEC` | Specified file isn't executable or has invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process. | -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions creates and executes a new process, passing an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions creates and executes a new process, passing an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -These functions validate their parameters. If either *cmdname* or *argv* is a null pointer, or if *argv* points to null pointer, or *argv*[0] is an empty string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions set **errno** to **EINVAL**, and return -1. No new process is spawned. +These functions validate their parameters. If either *`cmdname`* or *`argv`* is a null pointer, or if *`argv`* points to null pointer, or *`argv[0]`* is an empty string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions set `errno` to `EINVAL`, and return -1. No new process is spawned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_spawnvpe**|\ or \| -|**_wspawnvpe**|\ or \| +| Routine | Required header | +|---|---| +| **`_spawnvpe`** | \ or \ | +| **`_wspawnvpe`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md). +See the example in [`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md). ## See also -[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_flushall](flushall.md)
-[_getmbcp](getmbcp.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_setmbcp](setmbcp.md)
-[system, _wsystem](system-wsystem.md)
+[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_setmbcp`](setmbcp.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/spawnvpe.md b/docs/c-runtime-library/reference/spawnvpe.md index c5b1b8fb48..fd27850d99 100644 --- a/docs/c-runtime-library/reference/spawnvpe.md +++ b/docs/c-runtime-library/reference/spawnvpe.md @@ -10,11 +10,11 @@ f1_keywords: ["spawnvpe"] helpviewer_keywords: ["spawnvpe function"] ms.assetid: be16bf98-5059-4c33-be00-7524142a017e --- -# spawnvpe +# `spawnvpe` -The Microsoft-specific function name `spawnvpe` is a deprecated alias for the [_spawnvpe](spawnvpe-wspawnvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `spawnvpe` is a deprecated alias for the [`_spawnvpe`](spawnvpe-wspawnvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_spawnvpe](spawnvpe-wspawnvpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_spawnvpe`](spawnvpe-wspawnvpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md b/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md index 01b4b89c0e..20522192c3 100644 --- a/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md +++ b/docs/c-runtime-library/reference/splitpath-s-wsplitpath-s.md @@ -3,7 +3,7 @@ description: "Learn more about: _splitpath_s, _wsplitpath_s" title: "_splitpath_s, _wsplitpath_s" ms.date: "4/2/2020" api_name: ["_wsplitpath_s", "_splitpath_s", "_o__splitpath_s", "_o__wsplitpath_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wsplitpath_s", "splitpath_s", "_splitpath_s", "wsplitpath_s"] @@ -12,7 +12,7 @@ ms.assetid: 30fff3e2-cd00-4eb6-b5a2-65db79cb688b --- # `_splitpath_s`, `_wsplitpath_s` -Breaks a path name into components. These are versions of [`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Breaks a path name into components. These functions are versions of [`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -59,92 +59,92 @@ errno_t _wsplitpath_s( ### Parameters -*`path`*
+*`path`*\ Full path. -*`drive`*
-Drive letter, followed by a colon (**`:`**). You can pass **`NULL`** for this parameter if you do not need the drive letter. +*`drive`*\ +Drive letter, followed by a colon (**`:`**). You can pass `NULL` for this parameter if you don't need the drive letter. -*`driveNumberOfElements`*
-The size of the *`drive`* buffer in single-byte or wide characters. If *`drive`* is **`NULL`**, this value must be 0. +*`driveNumberOfElements`*\ +The size of the *`drive`* buffer in single-byte or wide characters. If *`drive`* is `NULL`, this value must be 0. -*`dir`*
-Directory path, including trailing slash. Forward slashes ( **`/`** ), backslashes ( **`\\`** ), or both may be used. You can pass **`NULL`** for this parameter if you do not need the directory path. +*`dir`*\ +Directory path, including trailing slash. Forward slashes ( **`/`** ), backslashes ( **`\\`** ), or both may be used. You can pass `NULL` for this parameter if you don't need the directory path. -*`dirNumberOfElements`*
-The size of the *dir* buffer in single-byte or wide characters. If *`dir`* is **`NULL`**, this value must be 0. +*`dirNumberOfElements`*\ +The size of the *`dir`* buffer in single-byte or wide characters. If *`dir`* is `NULL`, this value must be 0. -*`fname`*
-Base filename (without extension). You can pass **`NULL`** for this parameter if you do not need the filename. +*`fname`*\ +Base filename (without extension). You can pass `NULL` for this parameter if you don't need the filename. -*`nameNumberOfElements`*
-The size of the *`fname`* buffer in single-byte or wide characters. If *`fname`* is **`NULL`**, this value must be 0. +*`nameNumberOfElements`*\ +The size of the *`fname`* buffer in single-byte or wide characters. If *`fname`* is `NULL`, this value must be 0. -*`ext`*
-Filename extension, including leading period (**`.`**). You can pass **`NULL`** for this parameter if you do not need the filename extension. +*`ext`*\ +Filename extension, including leading period (**`.`**). You can pass `NULL` for this parameter if you don't need the filename extension. -*`extNumberOfElements`*
-The size of *`ext`* buffer in single-byte or wide characters. If *`ext`* is **`NULL`**, this value must be 0. +*`extNumberOfElements`*\ +The size of *`ext`* buffer in single-byte or wide characters. If *`ext`* is `NULL`, this value must be 0. -## Return Value +## Return value Zero if successful; an error code on failure. -### Error Conditions +### Error conditions -|Condition|Return Value| -|---------------|------------------| -|*`path`* is **`NULL`**|**`EINVAL`**| -|*`drive`* is **`NULL`**, *`driveNumberOfElements`* is non-zero|**`EINVAL`**| -|*`drive`* is non-**`NULL`**, *`driveNumberOfElements`* is zero|**`EINVAL`**| -|*`dir`* is **`NULL`**, *`dirNumberOfElements`* is non-zero|**`EINVAL`**| -|*`dir`* is non-**`NULL`**, *`dirNumberOfElements`* is zero|**`EINVAL`**| -|*`fname`* is **`NULL`**, *`nameNumberOfElements`* is non-zero|**`EINVAL`**| -|*`fname`* is non-**`NULL`**, *`nameNumberOfElements`* is zero|**`EINVAL`**| -|*`ext`* is **`NULL`**, *`extNumberOfElements`* is non-zero|**`EINVAL`**| -|*`ext`* is non-**`NULL`**, *`extNumberOfElements`* is zero|**`EINVAL`**| +| Condition | Return value | +|---|---| +| *`path`* is `NULL` | `EINVAL` | +| *`drive`* is `NULL`, *`driveNumberOfElements`* is non-zero | `EINVAL` | +| *`drive`* is non-`NULL`, *`driveNumberOfElements`* is zero | `EINVAL` | +| *`dir`* is `NULL`, *`dirNumberOfElements`* is non-zero | `EINVAL` | +| *`dir`* is non-`NULL`, *`dirNumberOfElements`* is zero | `EINVAL` | +| *`fname`* is `NULL`, *`nameNumberOfElements`* is non-zero | `EINVAL` | +| *`fname`* is non-`NULL`, *`nameNumberOfElements`* is zero | `EINVAL` | +| *`ext`* is `NULL`, *`extNumberOfElements`* is non-zero | `EINVAL` | +| *`ext`* is non-`NULL`, *`extNumberOfElements`* is zero | `EINVAL` | -If any of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +If any of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. -If any of the buffers is too short to hold the result, these functions clear all the buffers to empty strings, set **`errno`** to **`ERANGE`**, and return **`ERANGE`**. +If any of the buffers is too short to hold the result, these functions clear all the buffers to empty strings, set `errno` to `ERANGE`, and return `ERANGE`. ## Remarks The **`_splitpath_s`** function breaks a path into its four components. **`_splitpath_s`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **`_wsplitpath_s`** is a wide-character version of **`_splitpath_s`**; the arguments to **`_wsplitpath_s`** are wide-character strings. These functions behave identically otherwise -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tsplitpath_s`**|**`_splitpath_s`**|**`_splitpath_s`**|**`_wsplitpath_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsplitpath_s` | **`_splitpath_s`** | **`_splitpath_s`** | **`_wsplitpath_s`** | -Each component of the full path is stored in a separate buffer; the manifest constants **`_MAX_DRIVE`**, **`_MAX_DIR`**, **`_MAX_FNAME`**, and **`_MAX_EXT`** (defined in `STDLIB.H`) specify the maximum allowable size for each file component. File components larger than the corresponding manifest constants cause heap corruption. +Each component of the full path is stored in a separate buffer; the manifest constants `_MAX_DRIVE`, `_MAX_DIR`, `_MAX_FNAME`, and `_MAX_EXT` (defined in `STDLIB.H`) specify the maximum allowable size for each file component. File components larger than the corresponding manifest constants cause heap corruption. The following table lists the values of the manifest constants. -|Name|Value| -|----------|-----------| -|`_MAX_DRIVE`|3| -|`_MAX_DIR`|256| -|`_MAX_FNAME`|256| -|`_MAX_EXT`|256| +| Name | Value | +|---|---| +| `_MAX_DRIVE` | 3 | +| `_MAX_DIR` | 256 | +| `_MAX_FNAME` | 256 | +| `_MAX_EXT` | 256 | -If the full path does not contain a component (for example, a filename), **`_splitpath_s`** assigns an empty string to the corresponding buffer. +If the full path doesn't contain a component (for example, a filename), **`_splitpath_s`** assigns an empty string to the corresponding buffer. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_splitpath_s`**|``| -|**`_wsplitpath_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_splitpath_s`** | `` | +| **`_wsplitpath_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -152,9 +152,9 @@ See the example for [`_makepath_s`, `_wmakepath_s`](makepath-s-wmakepath-s.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md)
-[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)
-[`_getmbcp`](getmbcp.md)
-[`_makepath`, `_wmakepath`](makepath-wmakepath.md)
-[`_setmbcp`](setmbcp.md)
+[File handling](../file-handling.md)\ +[`_splitpath`, `_wsplitpath`](splitpath-wsplitpath.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_makepath`, `_wmakepath`](makepath-wmakepath.md)\ +[`_setmbcp`](setmbcp.md) diff --git a/docs/c-runtime-library/reference/splitpath-wsplitpath.md b/docs/c-runtime-library/reference/splitpath-wsplitpath.md index 8e9451dda0..f11ecc1e6d 100644 --- a/docs/c-runtime-library/reference/splitpath-wsplitpath.md +++ b/docs/c-runtime-library/reference/splitpath-wsplitpath.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _splitpath, _wsplitpath" title: "_splitpath, _wsplitpath" -ms.date: "4/2/2020" +description: "Learn more about: _splitpath, _wsplitpath" +ms.date: 11/30/2023 api_name: ["_wsplitpath", "_splitpath", "_o__splitpath", "_o__wsplitpath"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wsplitpath", "_splitpath", "splitpath", "_wsplitpath", "_tsplitpath"] helpviewer_keywords: ["_splitpath function", "pathnames", "wsplitpath function", "splitpath function", "_wsplitpath function", "tsplitpath function", "path names", "_tsplitpath function"] -ms.assetid: 32bd76b5-1385-4ee8-a64c-abcb541cd2e4 --- # `_splitpath`, `_wsplitpath` -Break a path name into components. More secure versions of these functions are available, see [`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md). +Break a path into components. For more secure versions of these functions are available, see [`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md). ## Syntax @@ -35,62 +34,62 @@ void _wsplitpath( ### Parameters -*`path`*
+*`path`*\ Full path. -*`drive`*
-Drive letter, followed by a colon (**:**). You can pass **`NULL`** for this parameter if you do not need the drive letter. +*`drive`*\ +Drive letter, followed by a colon (**:**). You can pass `NULL` for this parameter if you don't need the drive letter. -*`dir`*
-Directory path, including trailing slash. Forward slashes ( **/** ), backslashes ( **\\** ), or both may be used. You can pass **`NULL`** for this parameter if you do not need the directory path. +*`dir`*\ +Directory path, including trailing slash. Forward slashes (`/`), backslashes (`\`), or both may be used. Pass `NULL` for this parameter if you don't need the directory path. -*`fname`*
-Base filename (no extension). You can pass **`NULL`** for this parameter if you do not need the filename. +*`fname`*\ +Base filename (no extension). Pass `NULL` for this parameter if you don't need the filename. -*`ext`*
-Filename extension, including leading period (**.**). You can pass **`NULL`** for this parameter if you do not need the filename extension. +*`ext`*\ +Filename extension, including leading period (`.`). Pass `NULL` for this parameter if you don't need the filename extension. ## Remarks The **`_splitpath`** function breaks a path into its four components. **`_splitpath`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. **`_wsplitpath`** is a wide-character version of **`_splitpath`**; the arguments to **`_wsplitpath`** are wide-character strings. These functions behave identically otherwise. -**Security Note** These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). More secure versions of these functions are available; see [`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md). +**Security Note** These functions are subject to buffer overrun. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). More secure versions of these functions are available; see [`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tsplitpath`**|**`_splitpath`**|**`_splitpath`**|**`_wsplitpath`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsplitpath` | **`_splitpath`** | **`_splitpath`** | **`_wsplitpath`** | -Each component of the full path is stored in a separate buffer; the manifest constants **`_MAX_DRIVE`**, **`_MAX_DIR`**, **`_MAX_FNAME`**, and **`_MAX_EXT`** (defined in `STDLIB.H`) specify the maximum size for each file component. File components that are larger than the corresponding manifest constants cause heap corruption. +Each component of the full path is stored in a separate buffer; the manifest constants `_MAX_DRIVE`, `_MAX_DIR`, `_MAX_FNAME`, and `_MAX_EXT` (defined in `STDLIB.H`) specify the maximum size for each file component. File components that are larger than the corresponding manifest constants cause heap corruption. Each buffer must be as large as its corresponding manifest constant to avoid potential buffer overrun. The following table lists the values of the manifest constants. -|Name|Value| -|----------|-----------| -|**`_MAX_DRIVE`**|3| -|**`_MAX_DIR`**|256| -|**`_MAX_FNAME`**|256| -|**`_MAX_EXT`**|256| +| Name | Value | +|---|---| +| `_MAX_DRIVE` | 3 | +| `_MAX_DIR` | 256 | +| `_MAX_FNAME` | 256 | +| `_MAX_EXT` | 256 | -If the full path does not contain a component (for example, a filename), **`_splitpath`** assigns empty strings to the corresponding buffers. +If the full path doesn't contain a component (for example, a filename), **`_splitpath`** assigns empty strings to the corresponding buffers. -You can pass **`NULL`** to **`_splitpath`** for any parameter other than *path* that you do not need. +You can pass `NULL` to **`_splitpath`** for any parameter other than *`path`* that you don't need. -If *`path`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`errno`** is set to **`EINVAL`** and the function returns **`EINVAL`**. +If *`path`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_splitpath`**|``| -|**`_wsplitpath`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_splitpath`** | `` | +| **`_wsplitpath`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,9 +97,9 @@ See the example for [`_makepath`](makepath-wmakepath.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)
-[`_getmbcp`](getmbcp.md)
-[`_makepath`, `_wmakepath`](makepath-wmakepath.md)
-[`_setmbcp`](setmbcp.md)
-[`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md)
+[File handling](../file-handling.md)\ +[`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_makepath`, `_wmakepath`](makepath-wmakepath.md)\ +[`_setmbcp`](setmbcp.md)\ +[`_splitpath_s`, `_wsplitpath_s`](splitpath-s-wsplitpath-s.md) diff --git a/docs/c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md b/docs/c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md index 91d18e5f49..030e72c577 100644 --- a/docs/c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md +++ b/docs/c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md @@ -46,53 +46,53 @@ int _swprintf_p_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output -*`sizeOfBuffer`*
+*`sizeOfBuffer`*\ Maximum number of characters to store. -*`format`*
+*`format`*\ Format-control string. -*`argument_list`*
+*`argument_list`*\ Optional arguments to the format string. -*`locale`*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value The number of characters written, or -1 if an error occurred. ## Remarks -The **`_sprintf_p`** function formats and stores a series of characters and values in *`buffer`*. Each argument in the *`argument_list`* (if any) is converted and output according to the corresponding format specification in *`format`*. The *format* argument uses the [format specification syntax for `printf` and `wprintf` functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. The difference between **`_sprintf_p`** and **`sprintf_s`** is that **`_sprintf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [`printf_p` Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +The **`_sprintf_p`** function formats and stores a series of characters and values in *`buffer`*. Each argument in the *`argument_list`* (if any) is converted and output according to the corresponding format specification in *`format`*. The *`format`* argument uses the [format specification syntax for `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. The difference between **`_sprintf_p`** and **`sprintf_s`** is that **`_sprintf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [`printf_p` Positional Parameters](../printf-p-positional-parameters.md). -**`_swprintf_p`** is a wide-character version of **`_sprintf_p`**; the pointer arguments to **`_swprintf_p`** are wide-character strings. Detection of encoding errors in **`_swprintf_p`** may differ from that in **`_sprintf_p`**. **`_swprintf_p`** and **`fwprintf_p`** behave identically except that **`_swprintf_p`** writes output to a string rather than to a destination of type **`FILE`**, and **`_swprintf_p`** requires the *`count`* parameter to specify the maximum number of characters to be written. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +**`_swprintf_p`** is a wide-character version of **`_sprintf_p`**; the pointer arguments to **`_swprintf_p`** are wide-character strings. Detection of encoding errors in **`_swprintf_p`** may differ from the detection in **`_sprintf_p`**. **`_swprintf_p`** and **`fwprintf_p`** behave identically except that **`_swprintf_p`** writes output to a string rather than to a destination of type `FILE`, and **`_swprintf_p`** requires the *`count`* parameter to specify the maximum number of characters to be written. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -**`_sprintf_p`** returns the number of bytes stored in *`buffer`*, not counting the terminating null character. **`_swprintf_p`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. If *`buffer`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +**`_sprintf_p`** returns the number of bytes stored in *`buffer`*, not counting the terminating null character. **`_swprintf_p`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. If *`buffer`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stprintf_p`**|**`_sprintf_p`**|**`_sprintf_p`**|**`_swprintf_p`**| -|**`_stprintf_p_l`**|**`_sprintf_p_l`**|**`_sprintf_p_l`**|**`_swprintf_p_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stprintf_p` | **`_sprintf_p`** | **`_sprintf_p`** | **`_swprintf_p`** | +| `_stprintf_p_l` | **`_sprintf_p_l`** | **`_sprintf_p_l`** | **`_swprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_sprintf_p`**, **`_sprintf_p_l`**|``| -|**`_swprintf_p`**, **`_swprintf_p_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_sprintf_p`**, **`_sprintf_p_l`** | `` | +| **`_swprintf_p`**, **`_swprintf_p_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use `_sprintf_p` to format data @@ -171,14 +171,14 @@ Wrote -1 characters ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[`printf_p` Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
+[Stream I/O](../stream-i-o.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`printf_p` Positional Parameters](../printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md b/docs/c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md index ebc16c9b94..5e3ff04ff2 100644 --- a/docs/c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md +++ b/docs/c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md @@ -9,9 +9,9 @@ topic_type: ["apiref"] f1_keywords: ["swprintf_s", "sprintf_s", "stdio/sprintf_s", "stdio/swprintf_s", "stdio/_sprintf_s_l", "stdio/_swprintf_s_l", "_sprintf_s_l", "_swprintf_s_l"] helpviewer_keywords: ["stprintf_s function", "stprintf_s_l function", "swprintf_s_l function", "sprintf_s function", "swprintf_s function", "_swprintf_s_l function", "sprintf_s_l function", "_stprintf_s_l function", "_stprintf_s function", "_sprintf_s_l function", "formatted text [C++]"] --- -# sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l +# `sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l` -Write formatted data to a string. These are versions of [sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted data to a string. These functions are versions of [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -58,61 +58,61 @@ int swprintf_s( ### Parameters -*buffer*
+*`buffer`*\ Storage location for output -*sizeOfBuffer*
+*`sizeOfBuffer`*\ Maximum number of characters to store. -*format*
+*`format`*\ Format-control string -*...*
+*`...`*\ Optional arguments to be formatted -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters written, or -1 if an error occurred. If *buffer* or *format* is a null pointer, **sprintf_s** and **swprintf_s** return -1 and set **errno** to **EINVAL**. +The number of characters written, or -1 if an error occurred. If *`buffer`* or *`format`* is a null pointer, **`sprintf_s`** and **`swprintf_s`** return -1 and set `errno` to `EINVAL`. -**sprintf_s** returns the number of bytes stored in *buffer*, not counting the terminating null character. **swprintf_s** returns the number of wide characters stored in *buffer*, not counting the terminating null wide character. +**`sprintf_s`** returns the number of bytes stored in *`buffer`*, not counting the terminating null character. **`swprintf_s`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. ## Remarks -The **sprintf_s** function formats and stores a series of characters and values in *buffer*. Each *argument* (if any) is converted and output according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. +The **`sprintf_s`** function formats and stores a series of characters and values in *`buffer`*. Each *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. -One main difference between **sprintf_s** and [sprintf](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) is that **sprintf_s** checks the format string for valid formatting characters, whereas [sprintf](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) only checks if the format string or buffer are **NULL** pointers. If either check fails, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **errno** to **EINVAL**. +One main difference between **`sprintf_s`** and [`sprintf`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) is that **`sprintf_s`** checks the format string for valid formatting characters, whereas [`sprintf`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) only checks if the format string or buffer are `NULL` pointers. If either check fails, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. -The other main difference between **sprintf_s** and [sprintf](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) is that **sprintf_s** takes a length parameter specifying the size of the output buffer in characters. If the buffer is too small for the formatted text, including the terminating null, then the buffer is set to an empty string by placing a null character at *buffer*[0], and the invalid parameter handler is invoked. Unlike **_snprintf**, **sprintf_s** guarantees that the buffer will be null-terminated unless the buffer size is zero. +The other main difference between **`sprintf_s`** and [`sprintf`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) is that **`sprintf_s`** takes a length parameter specifying the size of the output buffer in characters. If the buffer is too small for the formatted text, including the terminating null, then the buffer is set to an empty string by placing a null character at *`buffer[0]`*, and the invalid parameter handler is invoked. Unlike `_snprintf`, **`sprintf_s`** guarantees that the buffer will be null-terminated unless the buffer size is zero. -**swprintf_s** is a wide-character version of **sprintf_s**; the pointer arguments to **swprintf_s** are wide-character strings. Detection of encoding errors in **swprintf_s** may differ from that in **sprintf_s**. The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +**`swprintf_s`** is a wide-character version of **`sprintf_s`**; the pointer arguments to **`swprintf_s`** are wide-character strings. Detection of encoding errors in **`swprintf_s`** may differ from the detection in **`sprintf_s`**. The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically, which eliminates the need to specify a size argument, and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a size argument. And, they can automatically replace older, non-secure functions with newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -There are versions of **sprintf_s** that offer additional control over what happens if the buffer is too small. For more information, see [_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l](snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md). +There are versions of **`sprintf_s`** that offer more control over what happens if the buffer is too small. For more information, see [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_stprintf_s**|**sprintf_s**|**sprintf_s**|**swprintf_s**| -|**_stprintf_s_l**|**_sprintf_s_l**|**_sprintf_s_l**|**_swprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stprintf_s` | **`sprintf_s`** | **`sprintf_s`** | **`swprintf_s`** | +| `_stprintf_s_l` | **`_sprintf_s_l`** | **`_sprintf_s_l`** | **`_swprintf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**sprintf_s**, **_sprintf_s_l**|C: \

C++: \ or \| -|**swprintf_s**, **_swprintf_s_l**|C: \ or \

C++: \, \, \ or \| +| Routine | Required header | +|---|---| +| **`sprintf_s`**, **`_sprintf_s_l`** | C: \

C++: \ or \ | +| **`swprintf_s`**, **`_swprintf_s_l`** | C: \ or \

C++: \, \, \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use sprintf_s to format data @@ -176,10 +176,10 @@ wrote -1 characters ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md b/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md index a80186727b..960c47657c 100644 --- a/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md +++ b/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l" +description: "Learn more about: sprintf, _sprintf_l, swprintf, _swprintf, _swprintf_l, __swprintf_l" title: "sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l" ms.date: "3/9/2021" -api_name: ["__swprintf_l", "sprintf", "_sprintf_l", "_swprintf_l", "swprintf"] +api_name: ["__swprintf_l", "sprintf", "_sprintf_l", "_swprintf_l", "swprintf", "_swprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_stprintf_l", "__swprintf_l", "sprintf_l", "swprintf", "_sprintf_l", "sprintf", "_stprintf", "stprintf_l"] -helpviewer_keywords: ["_swprintf_l function", "_stprintf function", "__swprintf_l function", "stprintf function", "sprintf function", "_sprintf_l function", "_stprintf_l function", "swprintf function", "strings [C++], writing to", "_CRT_NON_CONFORMING_SWPRINTFS", "swprintf_l function", "stprintf_l function", "sprintf_l function", "formatted text [C++]"] +f1_keywords: ["_stprintf_l", "__swprintf_l", "sprintf_l", "_swprintf", "swprintf", "_sprintf_l", "sprintf", "_stprintf", "stprintf_l"] +helpviewer_keywords: ["_swprintf_l function", "_stprintf function", "__swprintf_l function", "stprintf function", "sprintf function", "_sprintf_l function", "_stprintf_l function", "swprintf function", "_swprintf function", "strings [C++], writing to", "_CRT_NON_CONFORMING_SWPRINTFS", "swprintf_l function", "stprintf_l function", "sprintf_l function", "formatted text [C++]"] --- -# `sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l` +# `sprintf`, `_sprintf_l`, `swprintf`, `_swprintf`, `_swprintf_l`, `__swprintf_l` Write formatted data to a string. More secure versions of some of these functions are available; see [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md). The secure versions of **`swprintf`** and **`_swprintf_l`** take the size of the buffer as a parameter. @@ -21,18 +21,27 @@ int sprintf( const char *format [, argument] ... ); + int _sprintf_l( char *buffer, const char *format, _locale_t locale [, argument] ... ); + int swprintf( wchar_t *buffer, size_t count, const wchar_t *format [, argument]... ); + +int _swprintf( + wchar_t *buffer, + const wchar_t *format [, + argument]... +); + int _swprintf_l( wchar_t *buffer, size_t count, @@ -40,18 +49,21 @@ int _swprintf_l( _locale_t locale [, argument] ... ); + int __swprintf_l( wchar_t *buffer, const wchar_t *format, _locale_t locale [, argument] ... ); + template int sprintf( char (&buffer)[size], const char *format [, argument] ... ); // C++ only + template int _sprintf_l( char (&buffer)[size], @@ -63,26 +75,26 @@ int _sprintf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output -*`count`*
+*`count`*\ Maximum number of characters to store in the Unicode version of this function. -*`format`*
+*`format`*\ Format-control string -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters written, or -1 if an error occurred. If *`buffer`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +The number of characters written, or -1 if an error occurred. If *`buffer`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. **`sprintf`** returns the number of bytes stored in *`buffer`*, not counting the terminating null character. **`swprintf`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. @@ -91,31 +103,31 @@ The number of characters written, or -1 if an error occurred. If *`buffer`* or * The **`sprintf`** function formats and stores a series of characters and values in *`buffer`*. Each *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> Using **`sprintf`**, there is no way to limit the number of characters written, which means that code using **`sprintf`** is susceptible to buffer overruns. Consider using the related function [`_snprintf`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), which specifies a maximum number of characters to write to *`buffer`*, or use [`_scprintf`](scprintf-scprintf-l-scwprintf-scwprintf-l.md) to determine how large a buffer is required. Also, ensure that *`format`* is not a user-defined string. +> Using **`sprintf`**, there is no way to limit the number of characters written, which means that code using **`sprintf`** is susceptible to buffer overruns. Consider using the related function [`snprintf`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), which specifies a maximum number of characters to write to *`buffer`*, or use [`_scprintf`](scprintf-scprintf-l-scwprintf-scwprintf-l.md) to determine how large a buffer is required. Also, ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -**`swprintf`** is a wide-character version of **`sprintf`**; the pointer arguments to **`swprintf`** are wide-character strings. Detection of encoding errors in **`swprintf`** may differ from **`sprintf`**. **`swprintf`** and **`fwprintf`** behave identically except **`swprintf`** writes output to a string rather than to a destination of type **`FILE`**, and **`swprintf`** requires the *count* parameter to specify the maximum number of characters to write. The versions of these functions with the **`_l`** suffix are identical except they use the locale parameter passed in instead of the current thread locale. +**`swprintf`** is a wide-character version of **`sprintf`**; the pointer arguments to **`swprintf`** are wide-character strings. Detection of encoding errors in **`swprintf`** may differ from **`sprintf`**. **`swprintf`** and **`fwprintf`** behave identically except **`swprintf`** writes output to a string rather than to a destination of type `FILE`, and **`swprintf`** requires the *`count`* parameter to specify the maximum number of characters to write. The versions of these functions with the **`_l`** suffix are identical except they use the locale parameter passed in instead of the current thread locale. -**`swprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define **`_CRT_NON_CONFORMING_SWPRINTFS`**. In a future version, the old behavior may be removed, so code should be changed to use the new conformant behavior. +Before the signature for `swprintf` was standardized, a version shipped in an older Microsoft C runtime library that didn't take the character count parameter. The older version is still available in the Microsoft C runtime library, but it's deprecated and was renamed `_swprintf()`. For code that was written against the older signature, define `_CRT_NON_CONFORMING_SWPRINTFS`, which maps calls to `swprintf` to `_swprintf`. In a future version, the old behavior may be removed, so code should be changed to use the new conformant behavior. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stprintf`**|**`sprintf`**|**`sprintf`**|**`_swprintf`**| -|**`_stprintf_l`**|**`_sprintf_l`**|**`_sprintf_l`**|**`__swprintf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_stprintf`** | **`sprintf`** | **`sprintf`** | **`_swprintf`** | +| **`_stprintf_l`** | **`_sprintf_l`** | **`_sprintf_l`** | **`__swprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sprintf`**, **`_sprintf_l`**|``| -|**`swprintf`**, **`_swprintf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sprintf`**, **`_sprintf_l`** | `` | +| **`swprintf`**, **`_swprintf`**, **`_swprintf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use `sprintf` to format data @@ -180,9 +192,9 @@ wrote -1 characters ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md index e8e0e4ef6c..ef2221147e 100644 --- a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md +++ b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md @@ -3,7 +3,7 @@ title: "sqrt, sqrtf, sqrtl" description: "API reference for sqrt, sqrtf, and sqrtl; which calculate a square root of a floating point number." ms.date: "08/31/2020" api_name: ["sqrtl", "sqrtf", "sqrt", "_o_sqrt", "_o_sqrtf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["sqrt", "sqrtf", "_sqrtl"] @@ -43,28 +43,28 @@ Non-negative floating-point value Because C++ allows overloading, you can call overloads of **`sqrt`** that take **`float`** or **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`sqrt`** always takes and returns **`double`**. -If you use the ` sqrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the ` sqrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## Return Value +## Return value The **`sqrt`** functions return the square-root of *`x`*. By default, if *`x`* is negative, **`sqrt`** returns an indefinite `NaN`. -|Input|SEH Exception|**`_matherr`** Exception| -|-----------|-------------------|--------------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| -|- ∞|none|`_DOMAIN`| -|`x<0`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| - INF | none | `_DOMAIN` | +| `x < 0` | none | `_DOMAIN` | ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**`sqrt`**, **`sqrtf`**, **`sqrtl`**|``|``| -|**`sqrt()`** macro | `` || +| Function | C header | C++ header | +|---|---|---| +| **`sqrt`**, **`sqrtf`**, **`sqrtl`** | `` | `` | +| **`sqrt`** macro | `` | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -93,8 +93,8 @@ The square root of 45.35 is 6.73 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`exp`, `expf`, `expl`](exp-expf.md)\ [`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ [`pow`, `powf`, `powl`](pow-powf-powl.md)\ -[`_CIsqrt`](../../c-runtime-library/cisqrt.md)\ +[`_CIsqrt`](../cisqrt.md) diff --git a/docs/c-runtime-library/reference/srand.md b/docs/c-runtime-library/reference/srand.md index 12f40bdd2e..018def508b 100644 --- a/docs/c-runtime-library/reference/srand.md +++ b/docs/c-runtime-library/reference/srand.md @@ -3,15 +3,15 @@ description: "Learn more about: srand" title: "srand" ms.date: "4/2/2020" api_name: ["srand", "_o_srand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["srand"] +f1_keywords: ["STDLIB/srand", "srand"] helpviewer_keywords: ["random starting point", "random starting point, setting", "random numbers, generating", "srand function", "numbers, pseudorandom", "numbers, random", "pseudorandom numbers", "starting points, setting random", "starting points"] --- -# srand +# `srand` -Sets the starting seed value for the pseudorandom number generator used by the **rand** function. +Sets the starting seed value for the pseudorandom number generator used by the **`rand`** function. ## Syntax @@ -23,28 +23,28 @@ void srand( ### Parameters -*seed*
+*`seed`*\ Seed for pseudorandom number generation ## Remarks -The **srand** function sets the starting point for generating a series of pseudorandom integers in the current thread. To reinitialize the generator to create the same sequence of results, call the **srand** function and use the same *seed* argument again. Any other value for *seed* sets the generator to a different starting point in the pseudorandom sequence. **rand** retrieves the pseudorandom numbers that are generated. Calling **rand** before any call to **srand** generates the same sequence as calling **srand** with *seed* passed as 1. +The **`srand`** function sets the starting point for generating a series of pseudorandom integers in the current thread. To reinitialize the generator to create the same sequence of results, call the **`srand`** function and use the same *`seed`* argument again. Any other value for *`seed`* sets the generator to a different starting point in the pseudorandom sequence. **`rand`** retrieves the pseudorandom numbers that are generated. Calling **`rand`** before any call to **`srand`** generates the same sequence as calling **`srand`** with *`seed`* passed as 1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**srand**|\| +| Routine | Required header | +|---|---| +| **`srand`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [rand](rand.md). +See the example for [`rand`](rand.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[rand](rand.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`rand`](rand.md) diff --git a/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md b/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md index 93e7f319c4..36b42b032c 100644 --- a/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md +++ b/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md @@ -12,7 +12,7 @@ ms.assetid: 956e65c8-00a5-43e8-a2f2-0f547ac9e56c --- # `sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l` -Reads formatted data from a string. These versions of [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a string. These versions of [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -43,38 +43,38 @@ int _swscanf_s_l( ### Parameters -*`buffer`*
+*`buffer`*\ Stored data -*`format`*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **`EOF`** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *`buffer`* or *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`** +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL` -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`sscanf_s`** function reads data from *`buffer`* into the location that's given by each *`argument`*. The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in *format*. Unlike the less secure version [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md), a buffer size parameter is required when you use the type field characters **`c`**, **`C`**, **`s`**, **`S`**, or string control sets that are enclosed in **`[]`**. The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. For example, if you are reading into a string, the buffer size for that string is passed as follows: +The **`sscanf_s`** function reads data from *`buffer`* into the location that's given by each *`argument`*. The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in *`format`*. Unlike the less secure version [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md), a buffer size parameter is required when you use the type field characters **`c`**, **`C`**, **`s`**, **`S`**, or string control sets that are enclosed in **`[]`**. The buffer size in characters must be supplied as an extra parameter immediately after each buffer parameter that requires it. For example, if you're reading into a string, the buffer size for that string is passed as follows: ```C wchar_t ws[10]; swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9 ``` -The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. -In the case of characters, a single character may be read as follows: +A single character may be read as follows: ```C wchar_t wc; @@ -88,32 +88,32 @@ char c[4]; sscanf_s(input, "%4c", &c, (unsigned)_countof(c)); // not null terminated ``` -For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` Type Field Characters](../../c-runtime-library/scanf-type-field-characters.md). +For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` type field characters](../scanf-type-field-characters.md). > [!NOTE] > The size parameter is of type **`unsigned`**, not **`size_t`**. When compiling for 64-bit targets, use a static cast to convert **`_countof`** or **`sizeof`** results to the correct size. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the **`scanf_s`** function. If copying occurs between strings that overlap, the behavior is undefined. -**`swscanf_s`** is a wide-character version of **`sscanf_s`**; the arguments to **`swscanf_s`** are wide-character strings. **`sscanf_s`** does not handle multibyte hexadecimal characters. **`swscanf_s`** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf_s`** and **`sscanf_s`** behave identically. +**`swscanf_s`** is a wide-character version of **`sscanf_s`**; the arguments to **`swscanf_s`** are wide-character strings. **`sscanf_s`** doesn't handle multibyte hexadecimal characters. **`swscanf_s`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf_s`** and **`sscanf_s`** behave identically. The versions of these functions that have the **`_l`** suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stscanf_s`**|**`sscanf_s`**|**`sscanf_s`**|**`swscanf_s`**| -|**`_stscanf_s_l`**|**`_sscanf_s_l`**|**`_sscanf_s_l`**|**`_swscanf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stscanf_s` | **`sscanf_s`** | **`sscanf_s`** | **`swscanf_s`** | +| `_stscanf_s_l` | **`_sscanf_s_l`** | **`_sscanf_s_l`** | **`_swscanf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sscanf_s`**, **`_sscanf_s_l`**|``| -|**`swscanf_s`**, **`_swscanf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sscanf_s`**, **`_sscanf_s_l`** | `` | +| **`swscanf_s`**, **`_swscanf_s_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -157,8 +157,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) diff --git a/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md b/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md index 7a35644c1a..e51dab81d4 100644 --- a/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md +++ b/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md @@ -43,54 +43,54 @@ int _swscanf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Stored data -*`format`*
-Format-control string. For more information, see [Format Specifications](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification syntax](../format-specification-fields-scanf-and-wscanf-functions.md). -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use -## Return Value +## Return value -Each of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **`EOF`** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *`buffer`* or *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`sscanf`** function reads data from *`buffer`* into the location given by each *`argument`*. Every *`argument`* must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the **`scanf`** function. If copying takes place between strings that overlap, the behavior is undefined. -For information about scanf type field characters, see [`scanf` Type Field Characters](../scanf-type-field-characters.md). For information about scanf format specification fields, see [Format Specification Fields](../format-specification-fields-scanf-and-wscanf-functions.md). +For information about scanf type field characters, see [`scanf` type field characters](../scanf-type-field-characters.md). For information about scanf format specification fields, see [Format specification fields](../format-specification-fields-scanf-and-wscanf-functions.md). > [!IMPORTANT] > When reading a string with **`sscanf`**, always specify a width for the **`%s`** format (for example, **"`%32s`"** instead of **"`%s`"**); otherwise, improperly formatted input can easily cause a buffer overrun. -**`swscanf`** is a wide-character version of **`sscanf`**; the arguments to **`swscanf`** are wide-character strings. **`sscanf`** does not handle multibyte hexadecimal characters. **`swscanf`** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf`** and **`sscanf`** behave identically. +**`swscanf`** is a wide-character version of **`sscanf`**; the arguments to **`swscanf`** are wide-character strings. **`sscanf`** doesn't handle multibyte hexadecimal characters. **`swscanf`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf`** and **`sscanf`** behave identically. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stscanf`**|**`sscanf`**|**`sscanf`**|**`swscanf`**| -|**`_stscanf_l`**|**`_sscanf_l`**|**`_sscanf_l`**|**`_swscanf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stscanf` | **`sscanf`** | **`sscanf`** | **`swscanf`** | +| `_stscanf_l` | **`_sscanf_l`** | **`_sscanf_l`** | **`_swscanf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sscanf`**, **`_sscanf_l`**|``| -|**`swscanf`**, **`_swscanf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sscanf`**, **`_sscanf_l`** | `` | +| **`swscanf`**, **`_swscanf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -135,8 +135,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) diff --git a/docs/c-runtime-library/reference/stat-functions.md b/docs/c-runtime-library/reference/stat-functions.md index 06d84d656f..b1a5efc58f 100644 --- a/docs/c-runtime-library/reference/stat-functions.md +++ b/docs/c-runtime-library/reference/stat-functions.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32, _wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32" title: "_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32, _wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32" -ms.date: "4/2/2020" +description: "Learn more about: _stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32, _wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32" +ms.date: "5/25/2023" api_name: ["_wstat64", "_stati64", "_stat32", "_stat32i64", "_stat", "_wstati64", "_wstat32", "_wstat64i32", "_wstat", "_stat64", "_stat64i32", "_wstat32i64", "_o__stat32", "_o__stat32i64", "_o__stat64", "_o__stat64i32", "_o__wstat32", "_o__wstat32i64", "_o__wstat64", "_o__wstat64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tstat32", "tstat", "_tstat64i32", "tstati64", "_wstat64", "_wstat32", "wstati64", "tstat64", "_stati64", "_wstat", "wstat64i32", "stat32i64", "tstat32i64", "_tstat", "_wstati64", "_tstati64", "_wstat32i64", "wstat32", "_wstat64i32", "_stat", "_tstat32", "stat64i32", "wstat64", "stat", "_stat32i64", "_stat32", "stati64", "wstat", "_stat64i32", "stat32", "_tstat32i64", "tstat64i32", "_tstat64", "_stat64", "stat/_stat", "stat/_stat32", "stat/_stat64", "stat/_stati64", "stat/_stat32i64", "stat/_stat64i32", "stat/_wstat", "stat/_wstat32", "stat/_wstat64", "stat/_wstati64", "stat/_wstat32i64", "stat/_wstat64i32"] +f1_keywords: ["stat/_stat", "stat/_stat32", "stat/_stat32i64", "stat/_stat64", "stat/_stat64i32", "stat/_stati64", "stat/__stat64", "TCHAR/_tstat", "TCHAR/_tstat32", "TCHAR/_tstat32i64", "TCHAR/_tstat64", "TCHAR/_tstat64i32", "TCHAR/_tstati64", "stat/_wstat", "stat/_wstat32", "stat/_wstat32i64", "stat/_wstat64", "stat/_wstat64i32", "stat/_wstati64", "_stat", "_stat32", "_stat32i64", "_stat64", "_stat64i32", "_stati64", "__stat64", "_tstat", "_tstat32", "_tstat32i64", "_tstat64", "_tstat64i32", "_tstati64", "_wstat", "_wstat32", "_wstat32i64", "_wstat64", "_wstat64i32", "_wstati64", "stat", "stat32", "stat32i64", "stat64", "stat64i32", "stati64", "tstat", "tstat32", "tstat32i64", "tstat64", "tstat64i32", "tstati64", "wstat", "wstat32", "wstat32i64", "wstat64", "wstat64i32", "wstati64"] helpviewer_keywords: ["files [C++], status information", "_stat function", "_wstat function", "_stat64i32 function", "tstat function", "_tstat64i32 function", "_stati64 function", "_stat64 function", "tstati64 function", "wstati64 function", "wstat64 function", "_wstat64i32 function", "_tstat32i64 function", "_stat32i64 function", "stat function", "status of files", "_tstat32 function", "tstat64 function", "_wstat64 function", "_tstat function", "_stat32 function", "wstat function", "_wstat32i64 function", "_tstati64 function", "_wstat32 function", "stat64 function", "stati64 function", "_wstati64 function", "_tstat64 function", "files [C++], getting status information"] -ms.assetid: 99a75ae6-ff26-47ad-af70-5ea7e17226a5 --- # `_stat`, `_stat32`, `_stat64`, `_stati64`, `_stat32i64`, `_stat64i32`, `_wstat`, `_wstat32`, `_wstat64`, `_wstati64`, `_wstat32i64`, `_wstat64i32` @@ -69,86 +68,87 @@ int _wstat64i32( ### Parameters -*`path`*
+*`path`*\ Pointer to a string containing the path of existing file or directory. -*`buffer`*
+*`buffer`*\ Pointer to structure that stores results. -## Return Value +## Return value -Each of these functions returns 0 if the file-status information is obtained. A return value of -1 indicates an error, in which case **`errno`** is set to **`ENOENT`**, indicating that the filename or path could not be found. A return value of **`EINVAL`** indicates an invalid parameter; **`errno`** is also set to **`EINVAL`** in this case. +Each of these functions returns 0 if the file-status information is obtained. A return value of -1 indicates an error, in which case `errno` is set to `ENOENT`, indicating that the filename or path couldn't be found. A return value of `EINVAL` indicates an invalid parameter; `errno` is also set to `EINVAL` in this case. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The date stamp on a file can be represented if it is later than midnight, January 1, 1970, and before 23:59:59, December 31, 3000, UTC, unless you use **`_stat32`** or **`_wstat32`**, or have defined **`_USE_32BIT_TIME_T`**, in which case the date can be represented only until 23:59:59 January 18, 2038, UTC. +The date stamp on a file can be represented if it's later than midnight, January 1, 1970, and before 23:59:59, December 31, 3000, UTC, unless you use **`_stat32`** or **`_wstat32`**, or have defined `_USE_32BIT_TIME_T`, in which case the date can be represented only until 23:59:59 January 18, 2038, UTC. ## Remarks The **`_stat`** function obtains information about the file or directory specified by *`path`* and stores it in the structure pointed to by *`buffer`*. **`_stat`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. -**`_wstat`** is a wide-character version of **`_stat`**; the *`path`* argument to **`_wstat`** is a wide-character string. **`_wstat`** and **`_stat`** behave identically except that **`_wstat`** does not handle multibyte-character strings. +**`_wstat`** is a wide-character version of **`_stat`**; the *`path`* argument to **`_wstat`** is a wide-character string. **`_wstat`** and **`_stat`** behave identically except that **`_wstat`** doesn't handle multibyte-character strings. -Variations of these functions support 32- or 64-bit time types, and 32- or 64-bit file lengths. The first numerical suffix (**32** or **64**) indicates the size of the time type used; the second suffix is either **i32** or **i64**, indicating whether the file size is represented as a 32-bit or 64-bit integer. +Variations of these functions support 32-bit or 64-bit time types, and 32-bit or 64-bit file lengths. The first numerical suffix (**`32`** or **`64`**) indicates the size of the time type used; the second suffix is either **`i32`** or **`i64`**, indicating whether the file size is represented as a 32-bit or 64-bit integer. -**`_stat`** is equivalent to **`_stat64i32`**, and **`struct`** **`_stat`** contains a 64-bit time. This is true unless **`_USE_32BIT_TIME_T`** is defined, in which case the old behavior is in effect; **`_stat`** uses a 32-bit time, and **`struct`** **`_stat`** contains a 32-bit time. The same is true for **`_stati64`**. +**`_stat`** is equivalent to **`_stat64i32`**, and **`struct _stat`** contains a 64-bit time, unless `_USE_32BIT_TIME_T` is defined, in which case the old behavior is in effect; **`_stat`** uses a 32-bit time, and **`struct _stat`** contains a 32-bit time. The same is true for **`_stati64`**. > [!NOTE] > **`_wstat`** does not work with Windows Vista symbolic links. In these cases, **`_wstat`** will always report a file size of 0. **`_stat`** does work correctly with symbolic links. +> The `_stat` family of functions use `CreateFile` in Visual Studio 2015, instead of `FindFirstFile` as in Visual Studio 2013 and earlier. This means that `_stat` on a path ending with a slash succeeds if the path refers to a directory, as opposed to before when the function would error with `errno` set to `ENOENT`. -This function validates its parameters. If either *`path`* or *`buffer`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +This function validates its parameters. If either *`path`* or *`buffer`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Time Type and File Length Type Variations of `_stat` +### Time type and file length type variations of `_stat` -|Functions|_USE_32BIT_TIME_T defined?|Time type|File length type| -|---------------|------------------------------------|---------------|----------------------| -|**`_stat`**, **`_wstat`**|Not defined|64-bit|32-bit| -|**`_stat`**, **`_wstat`**|Defined|32-bit|32-bit| -|**`_stat32`**, **`_wstat32`**|Not affected by the macro definition|32-bit|32-bit| -|**`_stat64`**, **`_wstat64`**|Not affected by the macro definition|64-bit|64-bit| -|**`_stati64`**, **`_wstati64`**|Not defined|64-bit|64-bit| -|**`_stati64`**, **`_wstati64`**|Defined|32-bit|64-bit| -|**`_stat32i64`**, **`_wstat32i64`**|Not affected by the macro definition|32-bit|64-bit| -|**`_stat64i32`**, **`_wstat64i32`**|Not affected by the macro definition|64-bit|32-bit| +| Functions | `_USE_32BIT_TIME_T` defined | Time type | File length type | +|---|---|---|---| +| **`_stat`**, **`_wstat`** | Not defined | 64-bit | 32-bit | +| **`_stat`**, **`_wstat`** | Defined | 32-bit | 32-bit | +| **`_stat32`**, **`_wstat32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_stat64`**, **`_wstat64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_stati64`**, **`_wstati64`** | Not defined | 64-bit | 64-bit | +| **`_stati64`**, **`_wstati64`** | Defined | 32-bit | 64-bit | +| **`_stat32i64`**, **`_wstat32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_stat64i32`**, **`_wstat64i32`** | Not affected by the macro definition | 64-bit | 32-bit | -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tstat`**|**`_stat`**|**`_stat`**|**`_wstat`**| -|**`_tstat64`**|**`_stat64`**|**`_stat64`**|**`_wstat64`**| -|**`_tstati64`**|**`_stati64`**|**`_stati64`**|**`_wstati64`**| -|**`_tstat32i64`**|**`_stat32i64`**|**`_stat32i64`**|**`_wstat32i64`**| -|**`_tstat64i32`**|**`_stat64i32`**|**`_stat64i32`**|**`_wstat64i32`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstat` | **`_stat`** | **`_stat`** | **`_wstat`** | +| `_tstat64` | **`_stat64`** | **`_stat64`** | **`_wstat64`** | +| `_tstati64` | **`_stati64`** | **`_stati64`** | **`_wstati64`** | +| `_tstat32i64` | **`_stat32i64`** | **`_stat32i64`** | **`_wstat32i64`** | +| `_tstat64i32` | **`_stat64i32`** | **`_stat64i32`** | **`_wstat64i32`** | The **`_stat`** structure, defined in **`SYS\STAT.H`**, includes the following fields. -|Field|Description| -|-|-| +| Field | Description | +|---|---| | **`st_gid`** | Numeric identifier of group that owns the file (UNIX-specific) This field will always be zero on Windows systems. A redirected file is classified as a Windows file. | | **`st_atime`** | Time of last access of file. Valid on NTFS but not on FAT formatted disk drives. | | **`st_ctime`** | Time of creation of file. Valid on NTFS but not on FAT formatted disk drives. | | **`st_dev`** | Drive number of the disk containing the file (same as **`st_rdev`**). | | **`st_ino`** | Number of the information node (the **`inode`**) for the file (UNIX-specific). On UNIX file systems, the **`inode`** describes the file date and time stamps, permissions, and content. When files are hard-linked to one another, they share the same **`inode`**. The **`inode`**, and therefore **`st_ino`**, has no meaning in the FAT, HPFS, or NTFS file systems. | -| **`st_mode`** | Bit mask for file-mode information. The **`_S_IFDIR`** bit is set if *`path`* specifies a directory; the **`_S_IFREG`** bit is set if *`path`* specifies an ordinary file or a device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension. | +| **`st_mode`** | Bit mask for file-mode information. The `_S_IFDIR` bit is set if *`path`* specifies a directory; the `_S_IFREG` bit is set if *`path`* specifies an ordinary file or a device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension. | | **`st_mtime`** | Time of last modification of file. | | **`st_nlink`** | Always 1 on non-NTFS file systems. | | **`st_rdev`** | Drive number of the disk containing the file (same as **`st_dev`**). | | **`st_size`** | Size of the file in bytes; a 64-bit integer for variations with the **`i64`** suffix. | | **`st_uid`** | Numeric identifier of user who owns file (UNIX-specific). This field will always be zero on Windows systems. A redirected file is classified as a Windows file. | -If *`path`* refers to a device, the **`st_size`**, various time fields, **`st_dev`**, and **`st_rdev`** fields in the **`_stat`** structure are meaningless. Because **`STAT.H`** uses the [`_dev_t`](../../c-runtime-library/standard-types.md) type that is defined in **`TYPES.H`**, you must include **`TYPES.H`** before **`STAT.H`** in your code. +If *`path`* refers to a device, the **`st_size`**, various time fields, **`st_dev`**, and **`st_rdev`** fields in the **`_stat`** structure are meaningless. Because **`STAT.H`** uses the [`_dev_t`](../standard-types.md) type that is defined in **`TYPES.H`**, you must include **`TYPES.H`** before **`STAT.H`** in your code. ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`_stat`**, **`_stat32`**, **`_stat64`**, **`_stati64`**, **`_stat32i64`**, **`_stat64i32`**|`` followed by ``|``| -|**`_wstat`**, **`_wstat32`**, **`_wstat64`**, **`_wstati64`**, **`_wstat32i64`**, **`_wstat64i32`**|`` followed by `` or ``|``| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_stat`**, **`_stat32`**, **`_stat64`**, **`_stati64`**, **`_stat32i64`**, **`_stat64i32`** | `` followed by `` | `` | +| **`_wstat`**, **`_wstat32`**, **`_wstat64`**, **`_wstati64`**, **`_wstat32i64`**, **`_wstat64i32`** | `` followed by `` or `` | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -215,8 +215,8 @@ Time modified : Thu Feb 07 14:39:36 2002 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_access`, `_waccess`](access-waccess.md)
-[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[`_getmbcp`](getmbcp.md)
-[`_setmbcp`](setmbcp.md)
+[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_setmbcp`](setmbcp.md) diff --git a/docs/c-runtime-library/reference/static-assert-macro.md b/docs/c-runtime-library/reference/static-assert-macro.md index 0e09a119ff..2ecae09083 100644 --- a/docs/c-runtime-library/reference/static-assert-macro.md +++ b/docs/c-runtime-library/reference/static-assert-macro.md @@ -9,9 +9,9 @@ f1_keywords: ["_STATIC_ASSERT"] helpviewer_keywords: ["_STATIC_ASSERT macro"] ms.assetid: 89b0350c-2c2f-4be6-9786-8b1f0780a5da --- -# _STATIC_ASSERT Macro +# `_STATIC_ASSERT` macro -Evaluate an expression at compile time and generate an error when the result is **FALSE**. +Evaluate an expression at compile time and generate an error when the result is `FALSE`. ## Syntax @@ -23,16 +23,16 @@ _STATIC_ASSERT( ### Parameters -*booleanExpression*
-Expression (including pointers) that evaluates to nonzero (**TRUE**) or 0 (**FALSE**). +*`booleanExpression`*\ +Expression (including pointers) that evaluates to nonzero (`TRUE`) or 0 (`FALSE`). ## Remarks -This macro resembles the [_ASSERT and _ASSERTE macros](assert-asserte-assert-expr-macros.md), except that *booleanExpression* is evaluated at compile time instead of at runtime. If *booleanExpression* evaluates to **FALSE** (0), [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) is generated. +This macro resembles the [`_ASSERT` and `_ASSERTE` macros](assert-asserte-assert-expr-macros.md), except that *`booleanExpression`* is evaluated at compile time instead of at runtime. If *`booleanExpression`* evaluates to `FALSE` (0), [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) is generated. ## Example -In this example, we check whether the [sizeof](../../c-language/sizeof-operator-c.md) an **`int`** is larger than or equal to 2 bytes and whether the [sizeof](../../c-language/sizeof-operator-c.md) a **`long`** is 1 byte. The program will not compile and it will generate [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) because a **`long`** is larger than 1 byte. +In this example, we check whether the [`sizeof`](../../c-language/sizeof-operator-c.md) an **`int`** is larger than or equal to 2 bytes and whether the [`sizeof`](../../c-language/sizeof-operator-c.md) a **`long`** is 1 byte. The program won't compile and it will generate [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) because a **`long`** is larger than 1 byte. ```C // crt__static_assert.c @@ -54,11 +54,11 @@ int main() ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**_STATIC_ASSERT**|\| +| Macro | Required header | +|---|---| +| **`_STATIC_ASSERT`** | \ | ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_ASSERT, _ASSERTE, _ASSERT_EXPR Macros](assert-asserte-assert-expr-macros.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` macros](assert-asserte-assert-expr-macros.md) diff --git a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md index 0dec6287d7..3dee203f57 100644 --- a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md +++ b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md @@ -10,7 +10,7 @@ f1_keywords: ["_statusfp2", "_statusfp", "statusfp2", "_status87", "status87", " helpviewer_keywords: ["floating-point functions, getting status word", "floating-point numbers, status word", "status87 function", "status word, getting floating point", "statusfp function", "_statusfp function", "_statusfp2 function", "statusfp2 function", "_status87 function", "floating-point functions", "status word"] ms.assetid: 7ef963fa-b1fb-429d-94d6-fbf282ab7432 --- -# _status87, _statusfp, _statusfp2 +# `_status87`, `_statusfp`, `_statusfp2` Gets the floating-point status word. @@ -24,33 +24,33 @@ void _statusfp2(unsigned int *px86, unsigned int *pSSE2) ### Parameters -*px86*
+*`px86`*\ This address is filled with the status word for the x87 floating-point unit. -*pSSE2*
+*`pSSE2`*\ This address is filled with the status word for the SSE2 floating-point unit. -## Return Value +## Return value -For **_status87** and **_statusfp**, the bits in the value that's returned indicate the floating-point status. See the FLOAT.H include file for a definition of the bits that are returned by **_statusfp**. Many math library functions modify the floating-point status word, with unpredictable results. Optimization can reorder, combine, and eliminate floating-point operations around calls to **_status87**, **_statusfp**, and related functions. Use the [/Od (Disable (Debug))](../../build/reference/od-disable-debug.md) compiler option or the [fenv_access](../../preprocessor/fenv-access.md) pragma directive to prevent optimizations that reorder floating-point operations. Return values from **_clearfp** and **_statusfp**, and also the return parameters of **_statusfp2**, are more reliable if fewer floating-point operations are performed between known states of the floating-point status word. +For **`_status87`** and **`_statusfp`**, the bits in the value that's returned indicate the floating-point status. See the FLOAT.H include file for a definition of the bits that are returned by **`_statusfp`**. Many math library functions modify the floating-point status word, with unpredictable results. Optimization can reorder, combine, and eliminate floating-point operations around calls to **`_status87`**, **`_statusfp`**, and related functions. Use the [/Od (Disable (Debug))](../../build/reference/od-disable-debug.md) compiler option or the [`fenv_access`](../../preprocessor/fenv-access.md) pragma directive to prevent optimizations that reorder floating-point operations. Return values from `_clearfp` and **`_statusfp`**, and also the return parameters of **`_statusfp2`**, are more reliable if fewer floating-point operations are performed between known states of the floating-point status word. ## Remarks -The **_statusfp** function gets the floating-point status word. The status word is a combination of the floating-point processor status and other conditions detected by the floating-point exception handler—for example, floating-point stack overflow and underflow. Unmasked exceptions are checked for before the contents of the status word are returned. This means that the caller is informed of pending exceptions. On x86 platforms, **_statusfp** returns a combination of the x87 and SSE2 floating-point status. On x64 platforms, the status that's returned is based on the SSE’s MXCSR status. On ARM platforms, **_statusfp** returns status from the FPSCR register. +The **`_statusfp`** function gets the floating-point status word. The status word is a combination of the floating-point processor status and other conditions detected by the floating-point exception handler—for example, floating-point stack overflow and underflow. Unmasked exceptions are checked for before the contents of the status word are returned. In other words, the caller is informed of pending exceptions. On x86 platforms, **`_statusfp`** returns a combination of the x87 and SSE2 floating-point status. On x64 platforms, the status that's returned is based on the SSE's MXCSR status. On ARM64 platforms, **`_statusfp`** returns status from the FPSCR register. -**_statusfp** is a platform-independent, portable version of **_status87**. It is identical to **_status87** on Intel (x86) platforms and is also supported by the x64 and ARM platforms. To ensure that your floating-point code is portable to all architectures, use **_statusfp**. If you are only targeting x86 platforms, you can use either **_status87** or **_statusfp**. +**`_statusfp`** is a platform-independent, portable version of **`_status87`**. It's identical to **`_status87`** on Intel (x86) platforms and is also supported by the x64 and ARM64 platforms. To ensure that your floating-point code is portable to all architectures, use **`_statusfp`**. If you're only targeting x86 platforms, you can use either **`_status87`** or **`_statusfp`**. -We recommend **_statusfp2** for chips (such as the Pentium IV) that have both an x87 and an SSE2 floating-point processor. For **_statusfp2**, the addresses are filled by using the floating-point status word for both the x87 or the SSE2 floating-point processor. For a chip that supports x87 and SSE2 floating-point processors, EM_AMBIGUOUS is set to 1 if **_statusfp** or **_controlfp** is used and the action was ambiguous because it could refer to the x87 or the SSE2 floating-point status word. The **_statusfp2** function is only supported on x86 platforms. +We recommend **`_statusfp2`** for chips (such as the Pentium IV) that have both an x87 and an SSE2 floating-point processor. For **`_statusfp2`**, the addresses are filled by using the floating-point status word for both the x87 or the SSE2 floating-point processor. For a chip that supports x87 and SSE2 floating-point processors, `EM_AMBIGUOUS` is set to 1 if **`_statusfp`** or `_controlfp` is used and the action was ambiguous because it could refer to the x87 or the SSE2 floating-point status word. The **`_statusfp2`** function is only supported on x86 platforms. -These functions are not useful for [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime (CLR) only supports the default floating-point precision. +These functions aren't useful for [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime (CLR) only supports the default floating-point precision. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_status87**, **_statusfp**, **_statusfp2**|\| +| Routine | Required header | +|---|---| +| **`_status87`**, **`_statusfp`**, **`_statusfp2`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,6 +100,6 @@ Status = 0x00080003 - inexact, underflow, denormal ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_clear87, _clearfp](clear87-clearfp.md)
-[_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md) diff --git a/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md b/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md index 985cda5c69..261fe9e805 100644 --- a/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md +++ b/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l" title: "strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l" ms.date: "4/2/2020" api_name: ["strcat_s", "_mbscat_s", "_mbscat_s_l", "wcscat_s", "_o__mbscat_s", "_o__mbscat_s_l", "_o_strcat_s", "_o_wcscat_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcat_s", "wcscat_s", "_mbscat_s", "_mbscat_s_l"] @@ -12,7 +12,7 @@ ms.assetid: 0f2f9901-c5c5-480b-98bc-f8f690792fc0 --- # `strcat_s`, `wcscat_s`, `_mbscat_s`, `_mbscat_s_l` -Appends a string. These versions of [`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Appends a string. These versions of [`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbscat_s`** and **`_mbscat_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -66,35 +66,35 @@ errno_t _mbscat_s_l( ### Parameters -*`strDestination`*
+*`strDestination`*\ Null-terminated destination string buffer. -*`numberOfElements`*
+*`numberOfElements`*\ Size of the destination string buffer. -*`strSource`*
+*`strSource`*\ Null-terminated source string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; an error code on failure. -### Error Conditions +### Error conditions -|*`strDestination`*|*`numberOfElements`*|*`strSource`*|Return value|Contents of *`strDestination`*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**`NULL`** or unterminated|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`strDestination[0]`* set to 0| -|any|0, or too small|any|**`ERANGE`**|*`strDestination[0]`* set to 0| +| *`strDestination`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDestination`* | +|---|---|---|---|---| +| `NULL` or unterminated | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`strDestination[0]`* set to 0 | +| any | 0, or too small | any | `ERANGE` | *`strDestination[0]`* set to 0 | ## Remarks The **`strcat_s`** function appends *`strSource`* to *`strDestination`* and terminates the resulting string with a null character. The initial character of *`strSource`* overwrites the terminating null character of *`strDestination`*. The behavior of **`strcat_s`** is undefined if the source and destination strings overlap. -Note that the second parameter is the total size of the buffer, not the remaining size: +The second parameter is the total size of the buffer, not the remaining size: ```C char buf[16]; @@ -103,33 +103,33 @@ strcat_s(buf, 16, " End"); // Correct strcat_s(buf, 16 - strlen(buf), " End"); // Incorrect ``` -**`wcscat_s`** and **`_mbscat_s`** are wide-character and multibyte-character versions of **`strcat_s`**. The arguments and return value of **`wcscat_s`** are wide-character strings; those of **`_mbscat_s`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscat_s`** and **`_mbscat_s`** are wide-character and multibyte-character versions of **`strcat_s`**. The arguments and return value of **`wcscat_s`** are wide-character strings. The arguments and return value of **`_mbscat_s`** are multibyte-character strings. These three functions behave identically otherwise. -If *`strDestination`* is a null pointer, or is not null-terminated, or if *`strSource`* is a **`NULL`** pointer, or if the destination string is too small, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** and set **`errno`** to **`EINVAL`**. +If *`strDestination`* is a null pointer, or isn't null-terminated, or if *`strSource`* is a `NULL` pointer, or if the destination string is too small, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. -The versions of functions that have the **`_l`** suffix have the same behavior, but use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of functions that have the **`_l`** suffix have the same behavior, but use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscat_s`**|**`strcat_s`**|**`_mbscat_s`**|**`wcscat_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscat_s` | **`strcat_s`** | **`_mbscat_s`** | **`wcscat_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcat_s`**|``| -|**`wcscat_s`**|`` or ``| -|**`_mbscat_s`**|``| +| Routine | Required header | +|---|---| +| **`strcat_s`** | `` | +| **`wcscat_s`** | `` or `` | +| **`_mbscat_s`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ See the code example in [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s- ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md b/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md index 16e09f9486..5e202c05d3 100644 --- a/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md +++ b/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md @@ -51,13 +51,13 @@ unsigned char *_mbscat( ### Parameters -*`strDestination`*
+*`strDestination`*\ Null-terminated destination string. -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value Each of these functions returns the destination string (*`strDestination`*). No return value is reserved to indicate an error. @@ -66,27 +66,27 @@ Each of these functions returns the destination string (*`strDestination`*). No The **`strcat`** function appends *`strSource`* to *`strDestination`* and terminates the resulting string with a null character. The initial character of *`strSource`* overwrites the terminating null character of *`strDestination`*. The behavior of **`strcat`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> Because **`strcat`** does not check for sufficient space in *strDestination* before appending *strSource*, it is a potential cause of buffer overruns. Consider using [`strncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) instead. +> Because **`strcat`** does not check for sufficient space in *`strDestination`* before appending *`strSource`*, it is a potential cause of buffer overruns. Consider using [`strncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) instead. -**`wcscat`** and **`_mbscat`** are wide-character and multibyte-character versions of **`strcat`**. The arguments and return value of **`wcscat`** are wide-character strings; those of **`_mbscat`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscat`** and **`_mbscat`** are wide-character and multibyte-character versions of **`strcat`**. The arguments and return value of **`wcscat`** are wide-character strings. The arguments and return value of **`_mbscat`** are multibyte-character strings. These three functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscat`**|**`strcat`**|**`_mbscat`**|**`wcscat`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscat` | **`strcat`** | **`_mbscat`** | **`wcscat`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcat`**|``| -|**`wcscat`**|`` or ``| -|**`_mbscat`**|``| +| Routine | Required header | +|---|---| +| **`strcat`** | `` | +| **`wcscat`** | `` or `` | +| **`_mbscat`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -94,10 +94,10 @@ See the example for [`strcpy`](strcpy-wcscpy-mbscpy.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md b/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md index 0ef51d2e0a..13e43ded7c 100644 --- a/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md +++ b/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strchr, wcschr, _mbschr, _mbschr_l" title: "strchr, wcschr, _mbschr, _mbschr_l" ms.date: "4/2/2020" api_name: ["strchr", "wcschr", "_mbschr_l", "_mbschr", "_o__mbschr", "_o__mbschr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcschr", "strchr", "wcschr", "_tcschr", "_mbschr"] @@ -15,7 +15,7 @@ ms.assetid: 2639905d-e983-43b7-b885-abef32cfac43 Finds a character in a string, by using the current locale or a specified `LC_CTYPE` conversion-state category. > [!IMPORTANT] -> `_mbschr` and `_mbschr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbschr`** and **`_mbschr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,47 +75,46 @@ const unsigned char *_mbschr_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated source string. -*`c`*
+*`c`*\ Character to be located. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns a pointer to the first occurrence of *`c`* in *`str`*, or `NULL` if *`c`* is not found. +Each of these functions returns a pointer to the first occurrence of *`c`* in *`str`*, or `NULL` if *`c`* isn't found. ## Remarks -The `strchr` function finds the first occurrence of *`c`* in *`str`*, or it returns `NULL` if *`c`* is not found. The null terminating character is included in the search. +The **`strchr`** function finds the first occurrence of *`c`* in *`str`*, or it returns `NULL` if *`c`* isn't found. The null terminating character is included in the search. -`wcschr`, `_mbschr` and `_mbschr_l` are wide-character and multibyte-character versions of `strchr`. The arguments and return value of `wcschr` are wide-character strings; those of `_mbschr` are multibyte-character strings. `_mbschr` recognizes multibyte-character sequences. Also, if the string is a null pointer, `_mbschr` invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `_mbschr` returns `NULL` and sets `errno` to `EINVAL`. `strchr` and `wcschr` do not validate their parameters. These three functions behave identically otherwise. +**`wcschr`**, **`_mbschr`** and **`_mbschr_l`** are wide-character and multibyte-character versions of **`strchr`**. The arguments and return value of **`wcschr`** are wide-character strings. The arguments and return value of **`_mbschr`** are multibyte-character strings. **`_mbschr`** recognizes multibyte-character sequences. Also, if the string is a null pointer, **`_mbschr`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbschr`** returns `NULL` and sets `errno` to `EINVAL`. **`strchr`** and **`wcschr`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcschr`|`strchr`|`_mbschr`|`wcschr`| -|**_n/a**|**n/a**|`_mbschr_l`|**n/a**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcschr` | **`strchr`** | **`_mbschr`** | **`wcschr`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strchr`|``| -|`wcschr`|`` or ``| -|`_mbschr`, `_mbschr_l`|``| +| Routine | Required header | +|---|---| +| **`strchr`** | `` | +| **`wcschr`** | `` or `` | +| **`_mbschr`**, **`_mbschr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -176,14 +175,14 @@ Result: last r found at position 30 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](strstr-wcsstr-mbsstr-mbsstr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](strstr-wcsstr-mbsstr-mbsstr-l.md) diff --git a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md index 7379b15b38..683b59764e 100644 --- a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md +++ b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md @@ -3,7 +3,7 @@ description: "Learn more about: strcmp, wcscmp, _mbscmp, _mbscmp_l" title: "strcmp, wcscmp, _mbscmp, _mbscmp_l" ms.date: "4/2/2020" api_name: ["wcscmp", "_mbscmp", "_mbscmp_l", "strcmp", "_o__mbscmp", "_o__mbscmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbscmp", "_mbscmp_l", "wcscmp", "strcmp", "_tcscmp", "_ftcscmp"] @@ -41,37 +41,37 @@ int _mbscmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value for each of these functions indicates the ordinal relation of *`string1`* to *`string2`*. -|Value|Relationship of `string1` to `string2`| -|-----------|----------------------------------------| -|< 0|*`string1`* is less than *`string2`*| -|0|*`string1`* is identical to *`string2`*| -|> 0|*`string1`* is greater than *`string2`*| +| Value | Relationship of `string1` to `string2` | +|---|---| +| < 0 | *`string1`* is less than *`string2`* | +| 0 | *`string1`* is identical to *`string2`* | +| > 0 | *`string1`* is greater than *`string2`* | -On a parameter validation error, **`_mbscmp`** and **`_mbscmp_l`** return **`_NLSCMPERROR`**, which is defined in `` and ``. +On a parameter validation error, **`_mbscmp`** and **`_mbscmp_l`** return `_NLSCMPERROR`, which is defined in `` and ``. ## Remarks -The **`strcmp`** function performs an ordinal comparison of *`string1`* and *`string2`* and returns a value that indicates their relationship. **`wcscmp`** and **`_mbscmp`** are, respectively, wide-character and multibyte-character versions of **`strcmp`**. **`_mbscmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns **`_NLSCMPERROR`** on an error. **`_mbscmp_l`** has the same behavior, but uses the locale parameter that's passed in instead of the current locale. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). Also, if *`string1`* or *`string2`* is a null pointer, **`_mbscmp`** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbscmp`** and **`_mbscmp_l`** return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. **`strcmp`** and **`wcscmp`** do not validate their parameters. These functions behave identically otherwise. +The **`strcmp`** function performs an ordinal comparison of *`string1`* and *`string2`* and returns a value that indicates their relationship. **`wcscmp`** and **`_mbscmp`** are, respectively, wide-character and multibyte-character versions of **`strcmp`**. **`_mbscmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. **`_mbscmp_l`** has the same behavior, but uses the locale parameter that's passed in instead of the current locale. For more information, see [Code pages](../code-pages.md). Also, if *`string1`* or *`string2`* is a null pointer, **`_mbscmp`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbscmp`** and **`_mbscmp_l`** return `_NLSCMPERROR` and set `errno` to `EINVAL`. **`strcmp`** and **`wcscmp`** don't validate their parameters. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscmp`**|**`strcmp`**|**`_mbscmp`**|**`wcscmp`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscmp` | **`strcmp`** | **`_mbscmp`** | **`wcscmp`** | -The **`strcmp`** functions differ from the **`strcoll`** functions in that **`strcmp`** comparisons are ordinal, and are not affected by locale. **`strcoll`** compares strings lexicographically by using the **`LC_COLLATE`** category of the current locale. For more information about the **`LC_COLLATE`** category, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). +The **`strcmp`** functions differ from the **`strcoll`** functions in that **`strcmp`** comparisons are ordinal, and aren't affected by locale. **`strcoll`** compares strings lexicographically by using the `LC_COLLATE` category of the current locale. For more information about the `LC_COLLATE` category, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). In the "C" locale, the order of characters in the character set (ASCII character set) is the same as the lexicographic character order. However, in other locales, the order of characters in the character set may differ from the lexicographic order. For example, in certain European locales, the character '`a`' (value 0x61) comes before the character '`ä`' (value 0xE4) in the character set, but the character '`ä`' comes in front of the character '`a`' lexicographically. @@ -81,17 +81,17 @@ The **`strcmp`** functions are case-sensitive. **`_stricmp`**, **`_wcsicmp`**, a ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcmp`**|``| -|**`wcscmp`**|`` or ``| -|**`_mbscmp`**|``| +| Routine | Required header | +|---|---| +| **`strcmp`** | `` | +| **`wcscmp`** | `` or `` | +| **`_mbscmp`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -144,13 +144,13 @@ Compare strings: ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)
-[`_memicmp`, `_memicmp_`l](memicmp-memicmp-l.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strcmpi.md b/docs/c-runtime-library/reference/strcmpi.md index 9541964928..3e80b441e2 100644 --- a/docs/c-runtime-library/reference/strcmpi.md +++ b/docs/c-runtime-library/reference/strcmpi.md @@ -10,8 +10,8 @@ f1_keywords: ["strcmpi"] helpviewer_keywords: ["strcmpi function"] ms.assetid: 74206b2f-9bca-4d32-9cdc-93cb94c2aaa1 --- -# strcmpi +# `strcmpi` -The Microsoft-specific function name `strcmpi` is a deprecated alias for the [_stricmp](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `strcmpi` is a deprecated alias for the [`_stricmp`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_stricmp](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_stricmp`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md b/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md index d917bdde48..653c50ba6f 100644 --- a/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md +++ b/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll title: "strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l" ms.date: "4/2/2020" api_name: ["wcscoll", "_mbscoll", "_mbscoll_l", "strcoll", "_strcoll_l", "_wcscoll_l", "_o__mbscoll", "_o__mbscoll_l", "_o__strcoll_l", "_o__wcscoll_l", "_o_strcoll", "_o_wcscoll"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcscoll", "_mbscoll", "_tcscoll", "_ftcscoll"] +f1_keywords: ["STRING/strcoll", "CORECRT_WSTRING/wcscoll", "MBSTRING/_mbscoll", "TCHAR/_tcscoll", "TCHAR/_ftcscoll", "STRING/_strcoll_l", "CORECRT_WSTRING/_wcscoll_l", "MBSTRING/_mbscoll_l", "TCHAR/_tcscoll_l", "strcoll", "wcscoll", "_mbscoll", "_tcscoll", "_ftcscoll", "_strcoll_l", "_wcscoll_l", "_mbscoll_l", "_tcscoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "mbscoll function", "wcscoll_l function", "ftcscoll function", "wcscoll function", "_strcoll_l function", "tcscoll function", "_ftcscoll function", "_tcscoll function", "_wcscoll_l function", "_mbscoll function", "strcoll_l function", "strcoll functions", "strings [C++], comparing by code page"] ms.assetid: 900a7540-c7ec-4c2f-b292-7a85f63e3fe8 --- -# strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l +# `strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l` -Compares strings by using the current locale or a specified LC_COLLATE conversion-state category. +Compares strings by using the current locale or a specified `LC_COLLATE` conversion-state category. > [!IMPORTANT] -> **_mbscoll** and **_mbscoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbscoll`** and **`_mbscoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,62 +51,62 @@ int _mbscoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of *string1* to *string2*, as follows. +Each of these functions returns a value indicating the relationship of *`string1`* to *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -Each of these functions returns **_NLSCMPERROR** on an error. To use **_NLSCMPERROR**, include either STRING.H or MBSTRING.H. **wcscoll** can fail if either *string1* or *string2* is **NULL** or contains wide-character codes outside the domain of the collating sequence. When an error occurs, **wcscoll** may set **errno** to **EINVAL**. To check for an error on a call to **wcscoll**, set **errno** to 0 and then check **errno** after calling **wcscoll**. +Each of these functions returns `_NLSCMPERROR` on an error. To use `_NLSCMPERROR`, include either STRING.H or MBSTRING.H. **`wcscoll`** can fail if either *`string1`* or *`string2`* is `NULL` or contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`wcscoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`wcscoll`**, set `errno` to 0 and then check `errno` after calling **`wcscoll`**. ## Remarks -Each of these functions performs a case-sensitive comparison of *string1* and *string2* according to the code page currently in use. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. +Each of these functions performs a case-sensitive comparison of *`string1`* and *`string2`* according to the code page currently in use. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or if *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or if *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -The comparison of the two strings is a locale-dependent operation since each locale has different rules for ordering characters. The versions of these functions without the **_l** suffix use the current thread's locale for this locale-dependent behavior; the versions with the **_l** suffix are identical to the corresponding function without the suffix except that they use the locale passed in as a parameter instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The comparison of the two strings is a locale-dependent operation since each locale has different rules for ordering characters. The versions of these functions without the `_l` suffix use the current thread's locale for this locale-dependent behavior; the versions with the `_l` suffix are identical to the corresponding function without the suffix except that they use the locale passed in as a parameter instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscoll**|**strcoll**|**_mbscoll**|**wcscoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscoll` | **`strcoll`** | **`_mbscoll`** | **`wcscoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strcoll**|\| -|**wcscoll**|\, \| -|**_mbscoll**, **_mbscoll_l**|\| -|**_strcoll_l**|\| -|**_wcscoll_l**|\, \| +| Routine | Required header | +|---|---| +| **`strcoll`** | \ | +| **`wcscoll`** | \, \ | +| **`_mbscoll`**, **`_mbscoll_l`** | \ | +| **`_strcoll_l`** | \ | +| **`_wcscoll_l`** | \, \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md b/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md index 9fff08fc53..0871f968a5 100644 --- a/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md +++ b/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l" title: "strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l" ms.date: "5/28/2020" api_name: ["wcscpy_s", "_mbscpy_s", "_mbscpy_s_l", "strcpy_s", "_o__mbscpy_s", "_o__mbscpy_s_l", "_o_strcpy_s", "_o_wcscpy_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcpy_s", "_mbscpy_s", "_mbscpy_s_l", "_tcscpy_s", "wcscpy_s"] @@ -12,7 +12,7 @@ ms.assetid: 611326f3-7929-4a5d-a465-a4683af3b053 --- # `strcpy_s`, `wcscpy_s`, `_mbscpy_s`, `_mbscpy_s_l` -Copies a string. These versions of [`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies a string. These versions of [`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbscpy_s`** and **`_mbscpy_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -70,61 +70,61 @@ errno_t _mbscpy_s_l( ### Parameters -*`dest`*
+*`dest`*\ Location of the destination string buffer. -*`dest_size`*
-Size of the destination string buffer in **`char`** units for narrow and multi-byte functions, and **`wchar_t`** units for wide functions. This value must be greater than zero and not greater than **`RSIZE_MAX`**. Ensure that this size accounts for the terminating `NULL` following the string. +*`dest_size`*\ +Size of the destination string buffer in **`char`** units for narrow and multi-byte functions, and **`wchar_t`** units for wide functions. This value must be greater than zero and not greater than `RSIZE_MAX`. Ensure that this size accounts for the terminating `NULL` following the string. -*`src`*
+*`src`*\ Null-terminated source string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; otherwise, an error. -### Error Conditions +### Error conditions -|*`dest`*|*`dest_size`*|*`src`*|Return value|Contents of *`dest`*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**`NULL`**|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`dest[0]`* set to 0| -|any|0, or too small|any|**`ERANGE`**|*`dest[0]`* set to 0| +| *`dest`* | *`dest_size`* | *`src`* | Return value | Contents of *`dest`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`dest[0]`* set to 0 | +| any | 0, or too small | any | `ERANGE` | *`dest[0]`* set to 0 | ## Remarks The **`strcpy_s`** function copies the contents in the address of *`src`*, including the terminating null character, to the location that's specified by *`dest`*. The destination string must be large enough to hold the source string and its terminating null character. The behavior of **`strcpy_s`** is undefined if the source and destination strings overlap. -**`wcscpy_s`** is the wide-character version of **`strcpy_s`**, and **`_mbscpy_s`** is the multibyte-character version. The arguments of **`wcscpy_s`** are wide-character strings; those of **`_mbscpy_s`** and **`_mbscpy_s_l`** are multibyte-character strings. These functions behave identically otherwise. **`_mbscpy_s_l`** is identical to **`_mbscpy_s`** except that it uses the locale parameter passed in instead of the current locale. For more information, see [`locale`](../../c-runtime-library/locale.md). +**`wcscpy_s`** is the wide-character version of **`strcpy_s`**, and **`_mbscpy_s`** is the multibyte-character version. The arguments of **`wcscpy_s`** are wide-character strings. The arguments of **`_mbscpy_s`** and **`_mbscpy_s_l`** are multibyte-character strings. These functions behave identically otherwise. **`_mbscpy_s_l`** is identical to **`_mbscpy_s`** except that it uses the locale parameter passed in instead of the current locale. For more information, see [`locale`](../locale.md). -If *`dest`* or *`src`* is a null pointer, or if the destination string size *`dest_size`* is too small, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** and set **`errno`** to **`EINVAL`** when *`dest`* or *`src`* is a null pointer, and they return **`ERANGE`** and set **`errno`** to **`ERANGE`** when the destination string is too small. +If *`dest`* or *`src`* is a null pointer, or if the destination string size *`dest_size`* is too small, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL` when *`dest`* or *`src`* is a null pointer, and they return `ERANGE` and set `errno` to `ERANGE` when the destination string is too small. Upon successful execution, the destination string is always null-terminated. -In C++, use of these functions is simplified by template overloads that can infer buffer length automatically so that you don't have to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads that can infer buffer length automatically, so that you don't have to specify a size argument. And, they can automatically replace older, less-secure functions with newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscpy_s`**|**`strcpy_s`**|**`_mbscpy_s`**|**`wcscpy_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcscpy_s`** | **`strcpy_s`** | **`_mbscpy_s`** | **`wcscpy_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcpy_s`**|``| -|**`wcscpy_s`**|`` or ``| -|**`_mbscpy_s`**|``| +| Routine | Required header | +|---|---| +| **`strcpy_s`** | `` | +| **`wcscpy_s`** | `` or `` | +| **`_mbscpy_s`** | `` | -These functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -158,7 +158,7 @@ int main(void) stringBuffer = Hello world from strcpy_s and strcat_s! ``` -When building C++ code, the template versions may be easier to use. +When you're building C++ code, the template versions may be easier to use. ```cpp // crt_wcscpy_s.cpp @@ -191,12 +191,12 @@ stringBuffer = Hello world from wcscpy_s and wcscat_s! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strcat`, `wcscat`, `_mbscat`, `_mbscat_l`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`, `_mbscmp_l`](strcmp-wcscmp-mbscmp.md)
-[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`, `_mbscat_l`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`, `_mbscmp_l`](strcmp-wcscmp-mbscmp.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md b/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md index 761afc699f..1e5a1b6689 100644 --- a/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md +++ b/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md @@ -3,7 +3,7 @@ description: "Learn more about: strcpy, wcscpy, _mbscpy" title: "strcpy, wcscpy, _mbscpy" ms.date: "4/2/2020" api_name: ["strcpy", "wcscpy", "_mbscpy", "_o_wcscpy"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbscpy", "_ftcscpy", "wcscpy", "_tcscpy", "strcpy"] @@ -51,44 +51,44 @@ unsigned char *_mbscpy( ### Parameters -*`strDestination`*
+*`strDestination`*\ Destination string. -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value Each of these functions returns the destination string. No return value is reserved to indicate an error. ## Remarks -The **`strcpy`** function copies *strSource*, including the terminating null character, to the location that's specified by *`strDestination`*. The behavior of **`strcpy`** is undefined if the source and destination strings overlap. +The **`strcpy`** function copies *`strSource`*, including the terminating null character, to the location that's specified by *`strDestination`*. The behavior of **`strcpy`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> Because **`strcpy`** does not check for sufficient space in *strDestination* before it copies *`strSource`*, it is a potential cause of buffer overruns. Therefore, we recommend that you use [`strcpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) instead. +> Because **`strcpy`** does not check for sufficient space in *`strDestination`* before it copies *`strSource`*, it is a potential cause of buffer overruns. Therefore, we recommend that you use [`strcpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) instead. -**`wcscpy`** and **`_mbscpy`** are, respectively, wide-character and multibyte-character versions of **`strcpy`**. The arguments and return value of **`wcscpy`** are wide-character strings; those of **`_mbscpy`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscpy`** and **`_mbscpy`** are, respectively, wide-character and multibyte-character versions of **`strcpy`**. The arguments and return value of **`wcscpy`** are wide-character strings. The arguments and return value of **`_mbscpy`** are multibyte-character strings. These three functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscpy`**|**`strcpy`**|**`_mbscpy`**|**`wcscpy`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscpy` | **`strcpy`** | **`_mbscpy`** | **`wcscpy`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcpy`**|``| -|**`wcscpy`**|`` or ``| -|**`_mbscpy`**|``| +| Routine | Required header | +|---|---| +| **`strcpy`** | `` | +| **`wcscpy`** | `` or `` | +| **`_mbscpy`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -127,12 +127,12 @@ String = Hello world from strcpy and strcat! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md b/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md index 1a6fcbcc87..879e9482a2 100644 --- a/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md +++ b/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strcspn, wcscspn, _mbscspn, _mbscspn_l" title: "strcspn, wcscspn, _mbscspn, _mbscspn_l" ms.date: "4/2/2020" api_name: ["_mbscspn_l", "wcscspn", "_mbscspn", "strcspn", "_o__mbscspn", "_o__mbscspn_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcspn", "_mbscspn", "wcscspn", "_ftcscspn", "_tcscspn"] helpviewer_keywords: ["strings [C++], searching", "ftcscspn function", "strcspn function", "_mbscspn function", "mbscspn_l function", "wcscspn function", "tcscspn function", "_ftcscspn function", "_mbscspn_l function", "mbscspn function", "_tcscspn function"] ms.assetid: f73f51dd-b533-4e46-ba29-d05c553708a6 --- -# strcspn, wcscspn, _mbscspn, _mbscspn_l +# `strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l` Returns the index of the first occurrence in a string, of a character that belongs to a set of characters. > [!IMPORTANT] -> **_mbschr** and **_mbschr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> `_mbschr` and `_mbschr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,47 +41,46 @@ size_t _mbscspn_l( ### Parameters -*str*
+*`str`*\ Null-terminated searched string. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -These functions return the index of the first character in *str* that is in *strCharSet*. If none of the characters in *str* is in *strCharSet*, then the return value is the length of *str*. +These functions return the index of the first character in *`str`* that is in *`strCharSet`*. If none of the characters in *`str`* is in *`strCharSet`*, then the return value is the length of *`str`*. No return value is reserved to indicate an error. ## Remarks -**wcscspn** and **_mbscspn** are wide-character and multibyte-character versions of **strcspn**. The arguments of **wcscspn** are wide-character strings; those of **_mbscspn** are multibyte-character strings. +**`wcscspn`** and **`_mbscspn`** are wide-character and multibyte-character versions of **`strcspn`**. The arguments of **`wcscspn`** are wide-character strings. The arguments and return value of **`_mbscspn`** are multibyte-character strings. -**_mbscspn** validates its parameters. If either *str* or *strCharSet* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets **errno** to **EINVAL**. **strcspn** and **wcscspn** do not validate their parameters. These three functions behave identically otherwise. +**`_mbscspn`** validates its parameters. If either *`str`* or *`strCharSet`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets `errno` to `EINVAL`. **`strcspn`** and **`wcscspn`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscspn**|**strcspn**|**_mbscspn**|**wcscspn**| -|n/a|n/a|**_mbscspn_l**|n/a| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscspn` | **`strcspn`** | **`_mbscspn`** | **`wcscspn`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strcspn**|\| -|**wcscspn**|\ or \| -|**_mbscspn**, **_mbscspn_l**|\| +| Routine | Required header | +|---|---| +| **`strcspn`** | \ | +| **`wcscspn`** | \ or \ | +| **`_mbscspn`**, **`_mbscspn_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -119,12 +118,12 @@ strcspn( "", "" ) = 0 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md b/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md index c2273bfe38..765db82612 100644 --- a/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md +++ b/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md @@ -3,16 +3,16 @@ title: "_strdate_s, _wstrdate_s" description: "_strdate_s and _wstrdate_s are secure CRT versions of the _strdate and _wstrdate functions that put the current date in a buffer." ms.date: "4/2/2020" api_name: ["_strdate_s", "_wstrdate_s", "_o__strdate_s", "_o__wstrdate_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strdate_s", "wstrdate_s", "_wstrdate_s", "strdate_s", "_tstrdate_s"] helpviewer_keywords: ["dates, copying", "tstrdate_s function", "wstrdate_s function", "_tstrdate_s function", "strdate_s function", "copying dates", "_strdate_s function", "_wstrdate_s function"] ms.assetid: d41d8ea9-e5ce-40d4-864e-1ac29b455991 --- -# _strdate_s, _wstrdate_s +# `_strdate_s`, `_wstrdate_s` -Copy the current system date to a buffer. These functions are versions of [_strdate, _wstrdate](strdate-wstrdate.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copy the current system date to a buffer. These functions are versions of [`_strdate`, `_wstrdate`](strdate-wstrdate.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,70 +37,70 @@ errno_t _wstrdate_s( ### Parameters -*buffer*\ +*`buffer`*\ A pointer to a buffer to put the formatted date string. -*size*\ +*`size`*\ Size of the buffer in character units. ## Return value -Zero if successful. The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see table below for the exact errors generated by this function. For more information on error codes, see [errno](../../c-runtime-library/errno-constants.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see table below for the exact errors generated by this function. For more information on error codes, see [`errno`](../errno-constants.md). ## Error conditions -|*buffer*|*size*|Return|Contents of *buffer*| -|--------------|------------------------|------------|--------------------------| -|**NULL**|(any)|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0 < *size* < 9|**EINVAL**|Empty string| -|Not **NULL** (pointing to valid buffer)|*size* >= 9|0|Current date formatted as specified in the remarks| +| *`buffer`* | *`size`* | Return | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | (any) | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 < *`size`* < 9 | `EINVAL` | Empty string | +| Not `NULL` (pointing to valid buffer) | *`size`* >= 9 | 0 | Current date formatted as specified in the remarks | ## Security issues -Passing in an invalid, non-NULL value for *buffer* results in an access violation if the *size* parameter is greater than nine. +If you pass in an invalid, non-NULL value for *`buffer`*, it results in an access violation if the *`size`* parameter is greater than nine. -Passing a value for *size* greater than the actual size of *buffer* results in a buffer overrun. +Passing a value for *`size`* greater than the actual size of *`buffer`* results in a buffer overrun. ## Remarks -These functions provide more secure versions of **_strdate** and **_wstrdate**. The **_strdate_s** function copies the current system date to the buffer pointed to by *buffer*. It's formatted `mm/dd/yy`, where `mm` is the two-digit month, `dd` is the two-digit day, and `yy` is the last two digits of the year. For example, the string `12/05/99` represents December 5, 1999. The buffer must be at least nine characters long. +These functions provide more secure versions of `_strdate` and `_wstrdate`. The **`_strdate_s`** function copies the current system date to the buffer pointed to by *`buffer`*. It's formatted `mm/dd/yy`, where `mm` is the two-digit month, `dd` is the two-digit day, and `yy` is the last two digits of the year. For example, the string `12/05/99` represents December 5, 1999. The buffer must be at least nine characters long. -**_wstrdate_s** is a wide-character version of **_strdate_s**; the argument and return value of **_wstrdate_s** are wide-character strings. These functions behave identically otherwise. +**`_wstrdate_s`** is a wide-character version of **`_strdate_s`**; the argument and return value of **`_wstrdate_s`** are wide-character strings. These functions behave identically otherwise. -When *buffer* is a **NULL** pointer, or *size* is fewer than nine characters, the invalid parameter handler is invoked. It's described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1. They set **errno** to **EINVAL** if the buffer is **NULL** or if *size* is less than or equal to 0. Or, they set **errno** to **ERANGE** if *size* is less than 9. +When *`buffer`* is a `NULL` pointer, or *`size`* is fewer than nine characters, the invalid parameter handler is invoked. It's described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1. They set `errno` to `EINVAL` if the buffer is `NULL` or if *`size`* is less than or equal to 0. Or, they set `errno` to `ERANGE` if *`size`* is less than 9. -In C++, use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a *size* argument. And, they can automatically replace non-secure functions with their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a *`size`* argument. And, they can automatically replace non-secure functions with their newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mapping: -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate_s**|**_strdate_s**|**_strdate_s**|**_wstrdate_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrdate_s` | **`_strdate_s`** | **`_strdate_s`** | **`_wstrdate_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| -|**_strdate_s**|\| +| Routine | Required header | +|---|---| +| **`_strdate`** | \ | +| **`_wstrdate`** | \ or \ | +| **`_strdate_s`** | \ | ## Example -See the example for [time](time-time32-time64.md). +See the example for [`time`](time-time32-time64.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)\ -[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)\ -[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ -[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)\ -[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)\ -[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)\ -[time, _time32, _time64](time-time32-time64.md)\ -[_tzset](tzset.md) +[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strdate-wstrdate.md b/docs/c-runtime-library/reference/strdate-wstrdate.md index 4f8422d4b2..8f2570b92f 100644 --- a/docs/c-runtime-library/reference/strdate-wstrdate.md +++ b/docs/c-runtime-library/reference/strdate-wstrdate.md @@ -3,16 +3,16 @@ description: "Learn more about: _strdate, _wstrdate" title: "_strdate, _wstrdate" ms.date: "4/2/2020" api_name: ["_strdate", "_wstrdate", "_o__strdate", "_o__wstrdate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tstrdate", "wstrdate", "_wstrdate", "_strdate", "strdate"] helpviewer_keywords: ["strdate function", "dates, copying", "tstrdate function", "_wstrdate function", "wstrdate function", "_strdate function", "_tstrdate function", "copying dates"] ms.assetid: de8e4097-58f8-42ba-9dcd-cb4d9a9f1696 --- -# _strdate, _wstrdate +# `_strdate`, `_wstrdate` -Copy current system date to a buffer. More secure versions of these functions are available; see [_strdate_s, _wstrdate_s](strdate-s-wstrdate-s.md). +Copy current system date to a buffer. More secure versions of these functions are available; see [`_strdate_s`, `_wstrdate_s`](strdate-s-wstrdate-s.md). ## Syntax @@ -35,41 +35,41 @@ wchar_t *_wstrdate( ### Parameters -*datestr*
+*`datestr`*\ A pointer to a buffer containing the formatted date string. -## Return Value +## Return value -Each of these functions returns a pointer to the resulting character string *datestr*. +Each of these functions returns a pointer to the resulting character string *`datestr`*. ## Remarks -More secure versions of these functions are available; see [_strdate_s, _wstrdate_s](strdate-s-wstrdate-s.md). It is recommended that the more secure functions be used wherever possible. +More secure versions of these functions are available; see [`_strdate_s`, `_wstrdate_s`](strdate-s-wstrdate-s.md). It's recommended that the more secure functions be used wherever possible. -The **_strdate** function copies the current system date to the buffer pointed to by *datestr*, formatted **mm**/**dd**/**yy**, where **mm** is two digits representing the month, **dd** is two digits representing the day, and **yy** is the last two digits of the year. For example, the string **12/05/99** represents December 5, 1999. The buffer must be at least 9 bytes long. +The **`_strdate`** function copies the current system date to the buffer pointed to by *`datestr`*, formatted *mm/dd/yy*, where *mm* is two digits representing the month, *dd* is two digits representing the day, and *yy* is the last two digits of the year. For example, the string *`12/05/99`* represents December 5, 1999. The buffer must be at least 9 bytes long. -If *datestr* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`datestr`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -**_wstrdate** is a wide-character version of **_strdate**; the argument and return value of **_wstrdate** are wide-character strings. These functions behave identically otherwise. +**`_wstrdate`** is a wide-character version of **`_strdate`**; the argument and return value of **`_wstrdate`** are wide-character strings. These functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate**|**_strdate**|**_strdate**|**_wstrdate**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrdate` | **`_strdate`** | **`_strdate`** | **`_wstrdate`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| +| Routine | Required header | +|---|---| +| **`_strdate`** | \ | +| **`_wstrdate`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -99,11 +99,11 @@ OS date: 04/25/03 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md b/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md index 1687ad4ed6..2321d881fb 100644 --- a/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md +++ b/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strdec, _wcsdec, _mbsdec, _mbsdec_l" title: "_strdec, _wcsdec, _mbsdec, _mbsdec_l" ms.date: "4/2/2020" api_name: ["_wcsdec", "_strdec", "_mbsdec", "_mbsdec_l", "_o__mbsdec", "_o__mbsdec_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strdec", "mbsdec_l", "strdec", "_mbsdec", "_mbsdec_l", "mbsdec", "wcsdec", "_wcsdec"] helpviewer_keywords: ["mbsdec_l function", "mbsdec function", "tcsdec function", "_tcsdec function", "_strdec function", "_wcsdec function", "_mbsdec_l function", "strdec function", "wcsdec function", "_mbsdec function"] ms.assetid: ae37c223-800f-48a9-ae8e-38c8d20af2dd --- -# _strdec, _wcsdec, _mbsdec, _mbsdec_l +# `_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l` Moves a string pointer back one character. > [!IMPORTANT] -> **mbsdec** and **mbsdec_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsdec`** and **`_mbsdec_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,56 +41,56 @@ unsigned char *_mbsdec_l( ### Parameters -*start*
-Pointer to any character (or for **_mbsdec** and **_mbsdec_l**, the first byte of any multibyte character) in the source string; *start* must precede *current* in the source string. +*`start`*\ +Pointer to any character (or for **`_mbsdec`** and **`_mbsdec_l`**, the first byte of any multibyte character) in the source string; *`start`* must precede *`current`* in the source string. -*current*
-Pointer to any character (or for **_mbsdec** and **_mbsdec_l**, the first byte of any multibyte character) in the source string; *current* must follow *start* in the source string. +*`current`*\ +Pointer to any character (or for **`_mbsdec`** and **`_mbsdec_l`**, the first byte of any multibyte character) in the source string; *`current`* must follow *`start`* in the source string. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsdec**, **_mbsdec_l**, **_strdec**, and **_wcsdec** each return a pointer to the character that immediately precedes *current*; **_mbsdec** returns **NULL** if the value of *start* is greater than or equal to that of *current*. **_tcsdec** maps to one of these functions and its return value depends on the mapping. +**`_mbsdec`**, **`_mbsdec_l`**, **`_strdec`**, and **`_wcsdec`** each return a pointer to the character that immediately precedes *`current`*; **`_mbsdec`** returns `NULL` if the value of *`start`* is greater than or equal to that of *`current`*. `_tcsdec` maps to one of these functions and its return value depends on the mapping. ## Remarks -The **_mbsdec** and **_mbsdec_l** functions return a pointer to the first byte of the multibyte character that immediately precedes *current* in the string that contains *start*. +The **`_mbsdec`** and **`_mbsdec_l`** functions return a pointer to the first byte of the multibyte character that immediately precedes *`current`* in the string that contains *`start`*. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. **_mbsdec** recognizes multibyte-character sequences according to the locale that's currently in use, while **_mbsdec_l** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`_mbsdec`** recognizes multibyte-character sequences according to the locale that's currently in use, while **`_mbsdec_l`** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -If *start* or *current* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **EINVAL** and sets **errno** to **EINVAL**. +If *`start`* or *`current`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `EINVAL` and sets `errno` to `EINVAL`. > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsdec**|**_strdec**|**_mbsdec**|**_wcsdec**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdec` | **`_strdec`** | **`_mbsdec`** | **`_wcsdec`** | -**_strdec** and **_wcsdec** are single-byte-character and wide-character versions of **_mbsdec** and **_mbsdec_l**. **_strdec** and **_wcsdec** are provided only for this mapping and should not be used otherwise. +**`_strdec`** and **`_wcsdec`** are single-byte-character and wide-character versions of **`_mbsdec`** and **`_mbsdec_l`**. **`_strdec`** and **`_wcsdec`** are provided only for this mapping and shouldn't be used otherwise. -For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_mbsdec**|\|\| -|**_mbsdec_l**|\|\| -|**_strdec**|\|| -|**_wcsdec**|\|| +| Routine | Required header | Optional header | +|---|---|---| +| **`_mbsdec`** | \ | \ | +| **`_mbsdec_l`** | \ | \ | +| **`_strdec`** | \ | | +| **`_wcsdec`** | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -The following example shows a use of **_tcsdec**. +The following example shows a use of `_tcsdec`. ```cpp // crt_tcsdec.cpp @@ -116,7 +116,7 @@ int main() } ``` -The following example shows a use of **_mbsdec**. +The following example shows a use of **`_mbsdec`**. ```cpp // crt_mbsdec.cpp @@ -145,7 +145,7 @@ int main() ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md index a445f75214..7f5a94682a 100644 --- a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md +++ b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_wcsdup_dbg", "strdup_dbg", "_strdup_dbg", "wcsdup_dbg"] helpviewer_keywords: ["_wcsdup_dbg function", "stdup_dbg function", "copying strings", "duplicating strings", "strings [C++], copying", "strings [C++], duplicating", "_strdup_dbg function", "wcsdup_dbg function"] ms.assetid: 681db70c-d124-43ab-b83e-5eeea9035097 --- -# _strdup_dbg, _wcsdup_dbg +# `_strdup_dbg`, `_wcsdup_dbg` -Versions of [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) that use the debug version of **malloc**. +Versions of [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) that use the debug version of `malloc`. ## Syntax @@ -33,48 +33,48 @@ wchar_t *_wcsdup_dbg( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated source string. -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to name of source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -Each of these functions returns a pointer to the storage location for the copied string or **NULL** if storage cannot be allocated. +Each of these functions returns a pointer to the storage location for the copied string or `NULL` if storage can't be allocated. ## Remarks -The **_strdup_dbg** and **_wcsdup_dbg** functions are identical to **_strdup** and **_wcsdup** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc**, **_malloc_dbg**, to allocate memory for the duplicated string. For information on the debugging features of **_malloc_dbg**, see [_malloc_dbg](malloc-dbg.md). +The **`_strdup_dbg`** and **`_wcsdup_dbg`** functions are identical to `_strdup` and `_wcsdup` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc`, `_malloc_dbg`, to allocate memory for the duplicated string. For information on the debugging features of `_malloc_dbg`, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_strdup** and **_wcsdup** are remapped to **_strdup_dbg** and **_wcsdup_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_strdup` and `_wcsdup` are remapped to **`_strdup_dbg`** and **`_wcsdup_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information on block types, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsdup_dbg**|**_strdup_dbg**|**_mbsdup**|**_wcsdup_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdup_dbg` | **`_strdup_dbg`** | `_mbsdup` | **`_wcsdup_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdup_dbg**, **_wcsdup_dbg**|\| +| Routine | Required header | +|---|---| +| **`_strdup_dbg`**, **`_wcsdup_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All debug versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All debug versions of the [C run-time libraries](../crt-library-features.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strdup, _wcsdup, _mbsdup](strdup-wcsdup-mbsdup.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strdup`, `_wcsdup`, `_mbsdup`](strdup-wcsdup-mbsdup.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md index b48d493950..f6bf0213c3 100644 --- a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md +++ b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md @@ -3,7 +3,7 @@ description: "Learn more about: _strdup, _wcsdup, _mbsdup" title: "_strdup, _wcsdup, _mbsdup" ms.date: "4/2/2020" api_name: ["_strdup", "_mbsdup", "_wcsdup", "_o__strdup", "_o__wcsdup"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsdup", "mbsdup", "_mbsdup", "_strdup", "_ftcsdup", "_wcsdup"] @@ -33,40 +33,40 @@ unsigned char *_mbsdup( ### Parameters -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value -Each of these functions returns a pointer to the storage location for the copied string or **`NULL`** if storage cannot be allocated. +Each of these functions returns a pointer to the storage location for the copied string or `NULL` if storage can't be allocated. ## Remarks -The **`_strdup`** function calls [`malloc`](malloc.md) to allocate storage space for a copy of *strSource* and then copies *strSource* to the allocated space. +The **`_strdup`** function calls [`malloc`](malloc.md) to allocate storage space for a copy of *`strSource`* and then copies *`strSource`* to the allocated space. -**`_wcsdup`** and **`_mbsdup`** are wide-character and multibyte-character versions of **`_strdup`**. The arguments and return value of **`_wcsdup`** are wide-character strings; those of **`_mbsdup`** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsdup`** and **`_mbsdup`** are wide-character and multibyte-character versions of **`_strdup`**. The arguments and return value of **`_wcsdup`** are wide-character strings. The arguments and return value of **`_mbsdup`** are multibyte-character strings. These three functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsdup`**|**`_strdup`**|**`_mbsdup`**|**`_wcsdup`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdup` | **`_strdup`** | **`_mbsdup`** | **`_wcsdup`** | -Because **`_strdup`** calls **`malloc`** to allocate storage space for the copy of *strSource*, it is good practice always to release this memory by calling the [`free`](free.md) routine on the pointer that's returned by the call to **`_strdup`**. +Because **`_strdup`** calls **`malloc`** to allocate storage space for the copy of *`strSource`*, it's good practice always to release this memory by calling the [`free`](free.md) routine on the pointer that's returned by the call to **`_strdup`**. -If **`_DEBUG`** and **`_CRTDBG_MAP_ALLOC`** are defined, **`_strdup`** and **`_wcsdup`** are replaced by calls to **`_strdup_dbg`** and **`_wcsdup_dbg`** to allow for debugging memory allocations. For more information, see [`_strdup_dbg`, `_wcsdup_dbg`](strdup-dbg-wcsdup-dbg.md). +If `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, **`_strdup`** and **`_wcsdup`** are replaced by calls to **`_strdup_dbg`** and **`_wcsdup_dbg`**, to allow for debugging memory allocations. For more information, see [`_strdup_dbg`, `_wcsdup_dbg`](strdup-dbg-wcsdup-dbg.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_strdup`**|``| -|**`_wcsdup`**|`` or ``| -|**`_mbsdup`**|``| +| Routine | Required header | +|---|---| +| **`_strdup`** | `` | +| **`_wcsdup`** | `` or `` | +| **`_mbsdup`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -94,13 +94,13 @@ Copy: This is the buffer text ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memset`, `wmemset`](memset-wmemset.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strdup-wcsdup.md b/docs/c-runtime-library/reference/strdup-wcsdup.md index 66c3b71fe1..16871efb49 100644 --- a/docs/c-runtime-library/reference/strdup-wcsdup.md +++ b/docs/c-runtime-library/reference/strdup-wcsdup.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsdup", "strdup"] helpviewer_keywords: ["wcsdup function", "strdup function"] ms.assetid: c9ac0935-b525-4e95-8a64-396fc7e34ee9 --- -# strdup, wcsdup +# `strdup`, `wcsdup` -The Microsoft-implemented POSIX function names `strdup` and `wcsdup` are deprecated aliases for the [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `strdup` and `wcsdup` are deprecated aliases for the [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md b/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md index ef9acd5eae..e0cb870b10 100644 --- a/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md +++ b/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md @@ -1,18 +1,17 @@ --- title: "strerror_s, _strerror_s, _wcserror_s, __wcserror_s" description: "Functions with security enhancements to get a system error message or print a user-supplied error message." -ms.date: "09/25/2020" +ms.date: 05/31/2023 api_name: ["__wcserror_s", "_strerror_s", "_wcserror_s", "strerror_s", "_o__strerror_s", "_o__wcserror_s", "_o_strerror_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcserror_s", "__wcserror_s", "_tcserror_s", "_wcserror_s", "tcserror_s", "strerror_s", "_strerror_s"] helpviewer_keywords: ["__wcserror_s function", "error messages, printing", "tcserror_s function", "printing error messages", "strerror_s function", "_wcserror_s function", "_tcserror_s function", "_strerror_s function", "wcserror_s function", "error messages, getting"] -ms.assetid: 9e5b15a0-efe1-4586-b7e3-e1d7c31a03d6 --- -# strerror_s, _strerror_s, _wcserror_s, __wcserror_s +# `strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s` -Get a system error message (**strerror_s**, **_wcserror_s**) or print a user-supplied error message (**_strerror_s**, **__wcserror_s**). These are versions of [strerror, _strerror, _wcserror, \__wcserror](strerror-strerror-wcserror-wcserror.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Get a system error message (**`strerror_s`**, **`_wcserror_s`**) or print a user-supplied error message (**`_strerror_s`**, **`__wcserror_s`**). These functions are versions of [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](strerror-strerror-wcserror-wcserror.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -64,37 +63,37 @@ errno_t __wcserror_s( ### Parameters -*buffer*\ +*`buffer`*\ Buffer to hold error string. -*sizeInBytes*\ +*`sizeInBytes`*\ The number of bytes in the buffer. -*sizeInWords*\ +*`sizeInWords`*\ The number of words in the buffer. -*errnum*\ +*`errnum`*\ Error number. -*strErrMsg*\ +*`strErrMsg`*\ User-supplied message. -## Return Value +## Return value Zero if successful, an error code on failure. ### Error conditions -|*buffer*|*sizeInBytes/sizeInWords*|*strErrMsg*|Contents of *buffer*| -|--------------|------------------------|-----------------|--------------------------| -|**NULL**|any|any|n/a| -|any|0|any|not modified| +| *`buffer`* | *`sizeInBytes`*/*`sizeInWords`* | *`strErrMsg`* | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | any | any | n/a | +| any | 0 | any | not modified | ## Remarks -The **strerror_s** function is thread-safe. +The **`strerror_s`** function is thread-safe. -The **strerror_s** function maps *errnum* to an error-message string, returning the string in *buffer*. **_strerror_s** doesn't take the error number; it uses the current value of **errno** to determine the appropriate message. Neither **strerror_s** nor **_strerror_s** actually prints the message: For that, you need to call an output function such as [fprintf](fprintf-fprintf-l-fwprintf-fwprintf-l.md): +The **`strerror_s`** function maps *`errnum`* to an error-message string, returning the string in *`buffer`*. **`_strerror_s`** doesn't take the error number; it uses the current value of `errno` to determine the appropriate message. The message isn't printed or displayed by **`strerror_s`** or **`_strerror_s`**. To output the message, you need to call an output function such as [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md): ```C if (( _access( "datafile",2 )) == -1 ) @@ -104,46 +103,46 @@ if (( _access( "datafile",2 )) == -1 ) } ``` -If *strErrMsg* is **NULL**, **_strerror_s** returns a string in *buffer* that contains the system error message for the last library call that produced an error. The error-message string is terminated by the newline character ('\n'). If *strErrMsg* isn't equal to **NULL**, then **_strerror_s** returns a string in *buffer* that contains (in order) your string message, a colon, a space, the system error message for the last library call that produced an error, and a newline character. Your string message can be, at most, 94 characters long. +If *`strErrMsg`* is `NULL`, **`_strerror_s`** returns a string in *`buffer`* that contains the system error message for the last library call that produced an error. If *`strErrMsg`* isn't equal to `NULL`, then **`_strerror_s`** returns a string in *`buffer`* that contains (in order) your string message, a colon, a space, the system error message for the last library call that produced an error. Your string message can be, at most, 94 characters long. -These functions truncate the error message if its length exceeds the size of the buffer - 1. The resulting string in *buffer* will always be null-terminated. +These functions truncate the error message if its length exceeds the size of the buffer - 1. The resulting string in *`buffer`* is always null-terminated. -The actual error number for **_strerror_s** is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). The system error messages are accessed through the variable [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **_strerror_s** accesses the appropriate error message by using the **errno** value as an index to the variable **_sys_errlist**. The value of the variable [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **_sys_errlist** array. To produce accurate results, call **_strerror_s** immediately after a library routine returns with an error. Otherwise, subsequent calls to **strerror_s** or **_strerror_s** can overwrite the **errno** value. +The actual error number for **`_strerror_s`** is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md). The system error messages are accessed through the variable [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **`_strerror_s`** accesses the appropriate error message by using the `errno` value as an index to the variable `_sys_errlist`. The value of the variable [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the `_sys_errlist` array. To produce accurate results, call **`_strerror_s`** immediately after a library routine return with an error. Otherwise, subsequent calls to **`strerror_s`** or **`_strerror_s`** can overwrite the `errno` value. -**_wcserror_s** and **__wcserror_s** are wide-character versions of **strerror_s** and **_strerror_s**, respectively. +**`_wcserror_s`** and **`__wcserror_s`** are wide-character versions of **`strerror_s`** and **`_strerror_s`**, respectively. -These functions validate their parameters. If buffer is **NULL** or if the size parameter is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their parameters. If buffer is `NULL` or if the size parameter is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. -**_strerror_s**, **_wcserror_s**, and **__wcserror_s** aren't part of the ANSI definition but are instead Microsoft extensions to it. Don't use them where portability is desired; for ANSI compatibility, use **strerror_s** instead. +**`_strerror_s`**, **`_wcserror_s`**, and **`__wcserror_s`** aren't part of the ANSI definition but are instead Microsoft extensions to it. Don't use them where portability is desired; for ANSI compatibility, use **`strerror_s`** instead. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror_s**|**strerror_s**|**strerror_s**|**_wcserror_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcserror_s` | **`strerror_s`** | **`strerror_s`** | **`_wcserror_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strerror_s**, **_strerror_s**|\| -|**_wcserror_s**, **__wcserror_s**|\ or \| +| Routine | Required header | +|---|---| +| **`strerror_s`**, **`_strerror_s`** | \ | +| **`_wcserror_s`**, **`__wcserror_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [perror](perror-wperror.md). +See the example for [`perror`](perror-wperror.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[clearerr](clearerr.md)\ -[ferror](ferror.md)\ -[perror, _wperror](perror-wperror.md) +[String manipulation](../string-manipulation-crt.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md b/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md index b0fd0d7852..234fd6914f 100644 --- a/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md +++ b/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md @@ -1,18 +1,17 @@ --- title: "strerror, _strerror, _wcserror, __wcserror" description: "Describes the Microsoft C Runtime Library (CRT) functions strerror, _strerror, _wcserror, and __wcserror." -ms.date: "4/2/2020" +ms.date: "5/31/2023" api_name: ["strerror", "_strerror", "_wcserror", "__wcserror", "_o___wcserror", "_o__strerror", "_o__wcserror", "_o_strerror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__sys_errlist", "wcserror", "_strerror", "__wcserror", "strerror", "__sys_nerr", "_tcserror", "_wcserror", "tcserror"] helpviewer_keywords: ["strerror function", "_strerror function", "__sys_errlist", "wcserror function", "error messages, printing", "__sys_nerr", "tcserror function", "printing error messages", "_wcserror function", "_tcserror function", "__wcserror function", "error messages, getting"] -ms.assetid: 27b72255-f627-43c0-8836-bcda8b003e14 --- -# strerror, _strerror, _wcserror, __wcserror +# `strerror`, `_strerror`, `_wcserror`, `__wcserror` -Gets a system error message string (**strerror**, **_wcserror**) or formats a user-supplied error message string (**_strerror**, **__wcserror**). More secure versions of these functions are available; see [strerror_s, _strerror_s, _wcserror_s, \__wcserror_s](strerror-s-strerror-s-wcserror-s-wcserror-s.md). +Gets a system error message string (**`strerror`**, **`_wcserror`**) or formats a user-supplied error message string (**`_strerror`**, **`__wcserror`**). More secure versions of these functions are available; see [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](strerror-s-strerror-s-wcserror-s-wcserror-s.md). ## Syntax @@ -32,10 +31,10 @@ wchar_t * __wcserror( ### Parameters -*errnum*\ +*`errnum`*\ Error number. -*strErrMsg*\ +*`strErrMsg`*\ User-supplied message. ## Return value @@ -44,48 +43,48 @@ All of these functions return a pointer to an error-message string, in a thread- ## Remarks -The **strerror** function maps *errnum* to an error-message string and returns a pointer to the string. The **strerror** and **_strerror** functions don't actually print the message. To print, call an output function such as [fprintf](fprintf-fprintf-l-fwprintf-fwprintf-l.md): +The **`strerror`** function maps *`errnum`* to an error-message string and returns a pointer to the string. The **`strerror`** and **`_strerror`** functions don't actually print the message. To print, call an output function such as [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md): ```C if (( _access( "datafile", 2 )) == -1 ) fprintf( stderr, _strerror(NULL) ); ``` -If *strErrMsg* is passed as **NULL**, **_strerror** returns a pointer to a string. It contains the system error message for the last library call that produced an error. The error-message string is terminated by the newline character ('\n'). When *strErrMsg* isn't **NULL**, the string contains, in order: your *strErrMsg* string, a colon, a space, the system error message, and a newline character. Your string message can be, at most, 94 characters long, in either narrow (**_strerror**) or wide (**__wcserror**) characters. +If *`strErrMsg`* is passed as `NULL`, **`_strerror`** returns a pointer to a string. It contains the system error message for the last library call that produced an error. If you call `__wcserror`, the error-message string is terminated by the newline character (`'\n'`). The other functions don't add `'\n'`. When *`strErrMsg`* isn't `NULL`, the string contains, in order: your *`strErrMsg`* string, a colon, a space, the system error message. Your string message can be, at most, 94 characters long, in either narrow (**`_strerror`**) or wide (**`__wcserror`**) characters. -The actual error number for **_strerror** is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). To produce accurate results, call **_strerror** immediately after a library routine returns an error. Otherwise, later calls to library routines may overwrite the **errno** value. +The actual error number for **`_strerror`** is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md). To produce accurate results, call **`_strerror`** immediately after a library routine returns an error. Otherwise, later calls to library routines may overwrite the `errno` value. -**_wcserror** and **__wcserror** are wide-character versions of **strerror** and **_strerror**, respectively. +**`_wcserror`** and **`__wcserror`** are wide-character versions of **`strerror`** and **`_strerror`**, respectively. -**_strerror**, **_wcserror**, and **__wcserror** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **strerror** instead. +**`_strerror`**, **`_wcserror`**, and **`__wcserror`** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **`strerror`** instead. -To get error strings, we recommend **strerror** or **_wcserror** instead of the deprecated macros [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) and [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) and the deprecated internal functions **__sys_errlist** and **__sys_nerr**. +To get error strings, we recommend **`strerror`** or **`_wcserror`** instead of the deprecated macros [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md) and [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) and the deprecated internal functions `__sys_errlist` and `__sys_nerr`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror**|**strerror**|**strerror**|**_wcserror**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcserror` | **`strerror`** | **`strerror`** | **`_wcserror`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strerror**|\| -|**_strerror**|\| -|**_wcserror**, **__wcserror**|\| +| Routine | Required header | +|---|---| +| **`strerror`** | \ | +| **`_strerror`** | \ | +| **`_wcserror`**, **`__wcserror`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [perror](perror-wperror.md). +See the example for [`perror`](perror-wperror.md). ## See also -[String manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[clearerr](clearerr.md)\ -[ferror](ferror.md)\ -[perror, _wperror](perror-wperror.md) +[String manipulation](../string-manipulation-crt.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md b/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md index 4a8ee18bae..9d253c5cf2 100644 --- a/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md +++ b/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strftime, wcsftime, _strftime_l, _wcsftime_l" title: "strftime, wcsftime, _strftime_l, _wcsftime_l" ms.date: "4/2/2020" api_name: ["strftime", "_wcsftime_l", "_strftime_l", "wcsftime", "_o__strftime_l", "_o__wcsftime_l", "_o_strftime", "_o_wcsftime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsftime", "strftime", "wcsftime", "_strftime_l", "_wcsftime_l"] @@ -47,111 +47,111 @@ size_t _wcsftime_l( ### Parameters -*`strDest`*
+*`strDest`*\ Output string. -*`maxsize`*
+*`maxsize`*\ Size of the *`strDest`* buffer, measured in characters (**`char`** or **`wchar_t`**). -*`format`*
+*`format`*\ Format-control string. -*`timeptr`*
+*`timeptr`*\ **`tm`** data structure. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value **`strftime`** returns the number of characters placed in *`strDest`* and **`wcsftime`** returns the corresponding number of wide characters. If the total number of characters, including the terminating null, is more than *`maxsize`*, both **`strftime`** and **`wcsftime`** return 0 and the contents of *`strDest`* are indeterminate. -The number of characters in *`strDest`* is equal to the number of literal characters in *`format`* as well as any characters that may be added to *`format`* via formatting codes. The terminating null of a string is not counted in the return value. +The number of characters in *`strDest`* is equal to the number of literal characters in *`format`*, plus any characters that may be added to *`format`* via formatting codes. The terminating null of a string isn't counted in the return value. ## Remarks The **`strftime`** and **`wcsftime`** functions format the **`tm`** time value in *`timeptr`* according to the supplied *`format`* argument and store the result in the buffer *`strDest`*. At most, *`maxsize`* characters are placed in the string. For a description of the fields in the *`timeptr`* structure, see [`asctime`](asctime-wasctime.md). **`wcsftime`** is the wide-character equivalent of **`strftime`**; its string-pointer argument points to a wide-character string. These functions behave identically otherwise. -This function validates its parameters. If *`strDest`*, *`format`*, or *`timeptr`* is a null pointer, or if the **`tm`** data structure addressed by *`timeptr`* is invalid (for example, if it contains out of range values for the time or date), or if the *`format`* string contains an invalid formatting code, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets **`errno`** to **`EINVAL`**. +This function validates its parameters. If *`strDest`*, *`format`*, or *`timeptr`* is a null pointer, or if the **`tm`** data structure addressed by *`timeptr`* is invalid (for example, if it contains out of range values for the time or date), or if the *`format`* string contains an invalid formatting code, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsftime`**|**`strftime`**|**`strftime`**|**`wcsftime`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcsftime`** | **`strftime`** | **`strftime`** | **`wcsftime`** | -The *`format`* argument consists of one or more codes; as in **`printf`**, the formatting codes are preceded by a percent sign (**`%`**). Characters that do not begin with **`%`** are copied unchanged to *`strDest`*. The **`LC_TIME`** category of the current locale affects the output formatting of **`strftime`**. (For more information on **`LC_TIME`**, see [`setlocale`](setlocale-wsetlocale.md).) The **`strftime`** and **`wcsftime`** functions use the currently set locale. The **`_strftime_l`** and **`_wcsftime_l`** versions of these functions are identical except that they take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The *`format`* argument consists of one or more codes; as in **`printf`**, the formatting codes are preceded by a percent sign (**`%`**). Characters that don't begin with **`%`** are copied unchanged to *`strDest`*. The `LC_TIME` category of the current locale affects the output formatting of **`strftime`**. (For more information on `LC_TIME`, see [`setlocale`](setlocale-wsetlocale.md).) The **`strftime`** and **`wcsftime`** functions use the currently set locale. The **`_strftime_l`** and **`_wcsftime_l`** versions of these functions are identical except that they take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). The **`strftime`** functions support these formatting codes: -|Code|Replacement string| -|-|-| -|**`%a`**|Abbreviated weekday name in the locale| -|**`%A`**|Full weekday name in the locale| -|**`%b`**|Abbreviated month name in the locale| -|**`%B`**|Full month name in the locale| -|**`%c`**|Date and time representation appropriate for locale| -|**`%C`**|The year divided by 100 and truncated to an integer, as a decimal number (00−99)| -|**`%d`**|Day of month as a decimal number (01 - 31)| -|**`%D`**|Equivalent to **`%m/%d/%y`**| -|**`%e`**|Day of month as a decimal number (1 - 31), where single digits are preceded by a space| -|**`%F`**|Equivalent to **`%Y-%m-%d`**| -|**`%g`**|The last 2 digits of the ISO 8601 week-based year as a decimal number (00 - 99)| -|**`%G`**|The ISO 8601 week-based year as a decimal number| -|**`%h`**|Abbreviated month name (equivalent to **`%b`**)| -|**`%H`**|Hour in 24-hour format (00 - 23)| -|**`%I`**|Hour in 12-hour format (01 - 12)| -|**`%j`**|Day of the year as a decimal number (001 - 366)| -|**`%m`**|Month as a decimal number (01 - 12)| -|**`%M`**|Minute as a decimal number (00 - 59)| -|**`%n`**|A newline character (**`\n`**)| -|**`%p`**|The locale's A.M./P.M. indicator for 12-hour clock| -|**`%r`**|The locale's 12-hour clock time| -|**`%R`**|Equivalent to **`%H:%M`**| -|**`%S`**|Second as a decimal number (00 - 59)| -|**`%t`**|A horizontal tab character (**`\t`**)| -|**`%T`**|Equivalent to **`%H:%M:%S`**, the ISO 8601 time format| -|**`%u`**|ISO 8601 weekday as a decimal number (1 - 7; Monday is 1)| -|**`%U`**|Week number of the year as a decimal number (00 - 53), where the first Sunday is the first day of week 1| -|**`%V`**|ISO 8601 week number as a decimal number (00 - 53)| -|**`%w`**|Weekday as a decimal number (0 - 6; Sunday is 0)| -|**`%W`**|Week number of the year as a decimal number (00 - 53), where the first Monday is the first day of week 1| -|**`%x`**|Date representation for the locale| -|**`%X`**|Time representation for the locale| -|**`%y`**|Year without century, as decimal number (00 - 99)| -|**`%Y`**|Year with century, as decimal number| -|**`%z`**|The offset from UTC in ISO 8601 format; no characters if time zone is unknown| -|**`%Z`**|Either the locale's time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown| -|**`%%`**|Percent sign| +| Code | Replacement string | +|---|---| +| **`%a`** | Abbreviated weekday name in the locale | +| **`%A`** | Full weekday name in the locale | +| **`%b`** | Abbreviated month name in the locale | +| **`%B`** | Full month name in the locale | +| **`%c`** | Date and time representation appropriate for locale | +| **`%C`** | The year divided by 100 and truncated to an integer, as a decimal number (00−99) | +| **`%d`** | Day of month as a decimal number (01 - 31) | +| **`%D`** | Equivalent to **`%m/%d/%y`** | +| **`%e`** | Day of month as a decimal number (1 - 31), where single digits are preceded by a space | +| **`%F`** | Equivalent to **`%Y-%m-%d`** | +| **`%g`** | The last 2 digits of the ISO 8601 week-based year as a decimal number (00 - 99) | +| **`%G`** | The ISO 8601 week-based year as a decimal number | +| **`%h`** | Abbreviated month name (equivalent to **`%b`**) | +| **`%H`** | Hour in 24-hour format (00 - 23) | +| **`%I`** | Hour in 12-hour format (01 - 12) | +| **`%j`** | Day of the year as a decimal number (001 - 366) | +| **`%m`** | Month as a decimal number (01 - 12) | +| **`%M`** | Minute as a decimal number (00 - 59) | +| **`%n`** | A newline character (**`\n`**) | +| **`%p`** | The locale's A.M./P.M. indicator for 12-hour clock | +| **`%r`** | The locale's 12-hour clock time | +| **`%R`** | Equivalent to **`%H:%M`** | +| **`%S`** | Second as a decimal number (00 - 59) | +| **`%t`** | A horizontal tab character (**`\t`**) | +| **`%T`** | Equivalent to **`%H:%M:%S`**, the ISO 8601 time format | +| **`%u`** | ISO 8601 weekday as a decimal number (1 - 7; Monday is 1) | +| **`%U`** | Week number of the year as a decimal number (00 - 53), where the first Sunday is the first day of week 1 | +| **`%V`** | ISO 8601 week number as a decimal number (00 - 53) | +| **`%w`** | Weekday as a decimal number (0 - 6; Sunday is 0) | +| **`%W`** | Week number of the year as a decimal number (00 - 53), where the first Monday is the first day of week 1 | +| **`%x`** | Date representation for the locale | +| **`%X`** | Time representation for the locale | +| **`%y`** | Year without century, as decimal number (00 - 99) | +| **`%Y`** | Year with century, as decimal number | +| **`%z`** | The offset from UTC in ISO 8601 format; no characters if time zone is unknown | +| **`%Z`** | Either the locale's time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown | +| **`%%`** | Percent sign | As in the **`printf`** function, the **`#`** flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows. -|Format code|Meaning| -|-----------------|-------------| -|**`%#a`**, **`%#A`**, **`%#b`**, **`%#B`**, **`%#g`**, **`%#G`**, **`%#h`**, **`%#n`**, **`%#p`**, **`%#t`**, **`%#u`**, **`%#w`**, **`%#X`**, **`%#z`**, **`%#Z`**, **`%#%`**|**`#`** flag is ignored.| -|**`%#c`**|Long date and time representation, appropriate for the locale. For example: "Tuesday, March 14, 1995, 12:41:29".| -|**`%#x`**|Long date representation, appropriate to the locale. For example: "Tuesday, March 14, 1995".| -|**`%#d`**, **`%#D`**, **`%#e`**, **`%#F`**, **`%#H`**, **`%#I`**, **`%#j`**, **`%#m`**, **`%#M`**, **`%#r`**, **`%#R`**, **`%#S`**, **`%#T`**, **`%#U`**, **`%#V`**, **`%#W`**, **`%#y`**, **`%#Y`**|Remove leading zeros or spaces (if any).| +| Format code | Meaning | +|---|---| +| **`%#a`**, **`%#A`**, **`%#b`**, **`%#B`**, **`%#g`**, **`%#G`**, **`%#h`**, **`%#n`**, **`%#p`**, **`%#t`**, **`%#u`**, **`%#w`**, **`%#X`**, **`%#z`**, **`%#Z`**, **`%#%`** | **`#`** flag is ignored. | +| **`%#c`** | Long date and time representation, appropriate for the locale. For example: "Tuesday, March 14, 1995, 12:41:29". | +| **`%#x`** | Long date representation, appropriate to the locale. For example: "Tuesday, March 14, 1995". | +| **`%#d`**, **`%#D`**, **`%#e`**, **`%#F`**, **`%#H`**, **`%#I`**, **`%#j`**, **`%#m`**, **`%#M`**, **`%#r`**, **`%#R`**, **`%#S`**, **`%#T`**, **`%#U`**, **`%#V`**, **`%#W`**, **`%#y`**, **`%#Y`** | Remove leading zeros or spaces (if any). | -The ISO 8601 week and week-based year produced by **`%V`**, **`%g`**, and **`%G`**, uses a week that begins on Monday, where week 1 is the week that contains January 4th, which is the first week that includes at least four days of the year. If the first Monday of the year is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year. For those days, **`%V`** is replaced by 53, and both **`%g`** and **`%G`** are replaced by the digits of the preceding year. +The ISO 8601 week and week-based year produced by **`%V`**, **`%g`**, and **`%G`**, uses a week that begins on Monday. Week 1 is the week that contains the fourth day of January, which is the first week that includes at least four days of the year. If the first Monday of the year is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year. For those days, **`%V`** is replaced by 53, and both **`%g`** and **`%G`** are replaced by the digits of the preceding year. > [!NOTE] -> When using one of the `strftime` functions with a `tm` pointer returned from `gmtime`, the values printed via the `%Z` and `%z` specifiers will not be accurate. This is because the `tm` struct as specified by the C Standard does not contain the information for time zone name nor offset. Instead, the timezone information is populated via the global variables [`_timezone` and `_dstbias`](../../c-runtime-library/daylight-dstbias-timezone-and-tzname.md). +> When using one of the `strftime` functions with a `tm` pointer returned from `gmtime`, the values printed via the `%Z` and `%z` specifiers will not be accurate. This is because the `tm` struct as specified by the C Standard does not contain the information for time zone name nor offset. Instead, the timezone information is populated via the global variables [`_timezone` and `_dstbias`](../daylight-dstbias-timezone-and-tzname.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strftime`**|``| -|**`wcsftime`**|`` or ``| -|**`_strftime_l`**|``| -|**`_wcsftime_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`strftime`** | `` | +| **`wcsftime`** | `` or `` | +| **`_strftime_l`** | `` | +| **`_wcsftime_l`** | `` or `` | -The **`_strftime_l`** and **`_wcsftime_l`** functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_strftime_l`** and **`_wcsftime_l`** functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -159,10 +159,10 @@ See the example for [`time`](time-time32-time64.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[Time Management](../../c-runtime-library/time-management.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`localeconv`](localeconv.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[Time management](../time-management.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md b/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md index 8e16c0c2fe..a2a5dcd563 100644 --- a/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md +++ b/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md @@ -3,7 +3,7 @@ description: "Learn more about: _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsic title: "_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l" ms.date: "4/2/2020" api_name: ["_stricmp_l", "_mbsicmp", "_wcsicmp", "_mbsicmp_l", "_stricmp", "_wcsicmp_l", "_o__mbsicmp", "_o__mbsicmp_l", "_o__stricmp", "_o__stricmp_l", "_o__wcsicmp", "_o__wcsicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsicmp", "_stricmp", "wcsicmp_l", "_wcsicmp", "_tcsicmp", "_strcmpi", "stricmp_l", "_mbsicmp", "_fstricmp", "mbsicmp_l", "mbsicmp"] @@ -51,27 +51,27 @@ int _mbsicmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value indicates the relation of *`string1`* to *`string2`* as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*`string1`* less than *`string2`*| -|0|*`string1`* identical to *`string2`*| -|> 0|*`string1`* greater than *`string2`*| +| Return value | Description | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -On an error, **`_mbsicmp`** returns **`_NLSCMPERROR`**, which is defined in `` and ``. +On an error, **`_mbsicmp`** returns `_NLSCMPERROR`, which is defined in `` and ``. ## Remarks -The **`_stricmp`** function ordinally compares *`string1`* and *`string2`* after converting each character to lowercase, and returns a value indicating their relationship. **`_stricmp`** differs from **`_stricoll`** in that the **`_stricmp`** comparison is only affected by **`LC_CTYPE`**, which determines which characters are upper and lowercase. The **`_stricoll`** function compares strings according to both the **`LC_CTYPE`** and **`LC_COLLATE`** categories of the locale, which includes both the case and the collation order. For more information about the **`LC_COLLATE`** category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale Categories](../../c-runtime-library/locale-categories.md). The versions of these functions without the **`_l`** suffix use the current locale for locale-dependent behavior. The versions with the suffix are identical except that they use the locale passed in instead. If the locale has not been set, the C locale is used. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_stricmp`** function compares *`string1`* and *`string2`* after converting each character to lowercase, and returns a value indicating their relationship. **`_stricmp`** differs from **`_stricoll`** in that the **`_stricmp`** comparison is only affected by `LC_CTYPE`, which determines which characters are upper and lowercase. The **`_stricoll`** function compares strings according to both the `LC_CTYPE` and `LC_COLLATE` categories of the locale, which includes both the case and the collation order. For more information about the `LC_COLLATE` category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale categories](../locale-categories.md). The versions of these functions without the **`_l`** suffix use the current locale for locale-dependent behavior. The versions with the suffix are identical except that they use the locale passed in instead. If the locale hasn't been set, the C locale is used. For more information, see [Locale](../locale.md). > [!NOTE] > **`_stricmp`** is equivalent to **`_strcmpi`**. They can be used interchangeably but **`_stricmp`** is the preferred standard. @@ -84,15 +84,15 @@ To illustrate when case conversion by **`_stricmp`** affects the outcome of a co If the [`strcmp`](strcmp-wcscmp-mbscmp.md) function is used instead of **`_stricmp`**, `JOHN_HENRY` will be greater than `JOHNSTON`. -**`_wcsicmp`** and **`_mbsicmp`** are wide-character and multibyte-character versions of **`_stricmp`**. The arguments and return value of **`_wcsicmp`** are wide-character strings; those of **`_mbsicmp`** are multibyte-character strings. **`_mbsicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns **`_NLSCMPERROR`** on an error. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). These three functions behave identically otherwise. +**`_wcsicmp`** and **`_mbsicmp`** are wide-character and multibyte-character versions of **`_stricmp`**. The arguments and return value of **`_wcsicmp`** are wide-character strings. The arguments and return value of **`_mbsicmp`** are multibyte-character strings. **`_mbsicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. For more information, see [Code pages](../code-pages.md). These three functions behave identically otherwise. -**`_wcsicmp`** and **`wcscmp`** behave identically except that **`wcscmp`** does not convert its arguments to lowercase before comparing them. **`_mbsicmp`** and **`_mbscmp`** behave identically except that **`_mbscmp`** does not convert its arguments to lowercase before comparing them. +**`_wcsicmp`** and **`wcscmp`** behave identically except that **`wcscmp`** doesn't convert its arguments to lowercase before comparing them. **`_mbsicmp`** and **`_mbscmp`** behave identically except that **`_mbscmp`** doesn't convert its arguments to lowercase before comparing them. -You will need to call [`setlocale`](setlocale-wsetlocale.md) for **`_wcsicmp`** to work with Latin 1 characters. The C locale is in effect by default, so, for example, ä will not compare equal to Ä. Call **`setlocale`** with any locale other than the C locale before the call to **`_wcsicmp`**. The following sample demonstrates how **`_wcsicmp`** is sensitive to the locale: +You'll need to call [`setlocale`](setlocale-wsetlocale.md) for **`_wcsicmp`** to work with Latin 1 characters. The C locale is in effect by default, so, for example, ä won't compare equal to Ä. Call **`setlocale`** with any locale other than the C locale before the call to **`_wcsicmp`**. The following sample demonstrates how **`_wcsicmp`** is sensitive to the locale: ```C // crt_stricmp_locale.c -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). #include #include @@ -108,23 +108,23 @@ int main() { An alternative is to call [`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md) and pass the returned locale object as a parameter to **`_wcsicmp_l`**. -All of these functions validate their parameters. If either *`string1`* or *`string2`* are null pointers, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* are null pointers, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsicmp`**|**`_stricmp`**|**`_mbsicmp`**|**`_wcsicmp`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsicmp` | **`_stricmp`** | **`_mbsicmp`** | **`_wcsicmp`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_stricmp`**, **`_stricmp_l`**|``| -|**`_wcsicmp`**, **`_wcsicmp_l`**|`` or ``| -|**`_mbsicmp`**, **`_mbsicmp_l`**|``| +| Routine | Required header | +|---|---| +| **`_stricmp`**, **`_stricmp_l`** | `` | +| **`_wcsicmp`**, **`_wcsicmp_l`** | `` or `` | +| **`_mbsicmp`**, **`_mbsicmp_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -177,13 +177,13 @@ Compare strings: ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)
-[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md b/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md index fa1fa5f9b9..c5ed7b742d 100644 --- a/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md +++ b/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _w title: "_stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l" ms.date: "4/2/2020" api_name: ["_mbsicoll_l", "_stricoll_l", "_mbsicoll", "_wcsicoll_l", "_wcsicoll", "_stricoll", "_o__mbsicoll", "_o__mbsicoll_l", "_o__stricoll", "_o__stricoll_l", "_o__wcsicoll", "_o__wcsicoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["stricoll", "_stricoll", "_wcsicoll", "mbsicoll_l", "_mbsicoll", "_ftcsicoll", "wcsicoll_l", "_tcsicoll", "mbsicoll", "stricoll_l"] +f1_keywords: ["STRING/_stricoll", "CORECRT_WSTRING/_wcsicoll", "MBSTRING/_mbsicoll", "TCHAR/_tcsicoll", "TCHAR/_ftcsicoll", "STRING/_stricoll_l", "CORECRT_WSTRING/_wcsicoll_l", "MBSTRING/_mbsicoll_l", "TCHAR/_tcsicoll_l", "_stricoll", "_wcsicoll", "_mbsicoll", "_tcsicoll", "_ftcsicoll", "_stricoll_l", "_wcsicoll_l", "_mbsicoll_l", "_tcsicoll_l", "stricoll", "mbsicoll", "stricoll_l", "wcsicoll_l", "mbsicoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "_ftcsicoll function", "_mbsicoll_l function", "_mbsicoll function", "mbsicoll function", "stricoll function", "tcsicoll function", "string comparison [C++], culture-specific", "_tcsicoll function", "_stricoll function", "_stricoll_l function", "_wcsicoll function", "mbsicoll_l function", "stricoll_l function", "strings [C++], comparing by code page", "ftcsicoll function"] ms.assetid: 8ec93016-5a49-49d2-930f-721566661d82 --- -# _stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l +# `_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsicoll** and **_mbsicoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsicoll`** and **`_mbsicoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,61 +51,61 @@ int _mbsicoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of *string1* to *string2*, as follows. +Each of these functions returns a value indicating the relationship of *`string1`* to *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| -|**_NLSCMPERROR**|An error occurred.| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | +| `_NLSCMPERROR` | An error occurred. | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either \ or \. **_wcsicoll** can fail if either *string1* or *string2* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **_wcsicoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsicoll**, set **errno** to 0 and then check **errno** after calling **_wcsicoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either \ or \. **`_wcsicoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`_wcsicoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsicoll`**, set `errno` to 0 and then check `errno` after calling **`_wcsicoll`**. ## Remarks -Each of these functions performs a case-insensitive comparison of *string1* and *string2* according to the code page currently in use. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. +Each of these functions performs a case-insensitive comparison of *`string1`* and *`string2`* according to the code page currently in use. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. -**_stricmp** differs from **_stricoll** in that the **_stricmp** comparison is affected by **LC_CTYPE**, whereas the **_stricoll** comparison is according to the **LC_CTYPE** and **LC_COLLATE** categories of the locale. For more information on the **LC_COLLATE** category, see [setlocale](setlocale-wsetlocale.md) and [Locale Categories](../../c-runtime-library/locale-categories.md). The versions of these functions without the **_l** suffix use the current locale; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +`_stricmp` differs from **`_stricoll`** in that the `_stricmp` comparison is affected by `LC_CTYPE`, whereas the **`_stricoll`** comparison is according to the `LC_CTYPE` and `LC_COLLATE` categories of the locale. For more information on the `LC_COLLATE` category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale categories](../locale-categories.md). The versions of these functions without the `_l` suffix use the current locale; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* are **NULL** pointers, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* are `NULL` pointers, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsicoll**|**_stricoll**|**_mbsicoll**|**_wcsicoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsicoll` | **`_stricoll`** | **`_mbsicoll`** | **`_wcsicoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_stricoll**, **_stricoll_l**|\| -|**_wcsicoll**, **_wcsicoll_l**|\, \| -|**_mbsicoll**, **_mbsicoll_l**|\| +| Routine | Required header | +|---|---| +| **`_stricoll`**, **`_stricoll_l`** | \ | +| **`_wcsicoll`**, **`_wcsicoll_l`** | \, \ | +| **`_mbsicoll`**, **`_mbsicoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md b/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md index 1a25f8da08..57008d5678 100644 --- a/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md +++ b/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strinc, _wcsinc, _mbsinc, _mbsinc_l" title: "_strinc, _wcsinc, _mbsinc, _mbsinc_l" ms.date: "4/2/2020" api_name: ["_mbsinc", "_wcsinc", "_mbsinc_l", "_strinc", "_o__mbsinc", "_o__mbsinc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsinc_l", "_strinc", "strinc", "_mbsinc", "_wcsinc", "wcsinc", "mbsinc", "_mbsinc_l"] helpviewer_keywords: ["_mbsinc function", "wcsinc function", "mbsinc_l function", "_strinc function", "strinc function", "_mbsinc_l function", "mbsinc function", "_wcsinc function", "_tcsinc function", "tcsinc function"] ms.assetid: 54685943-8e2c-45e9-a559-2d94930dc6b4 --- -# _strinc, _wcsinc, _mbsinc, _mbsinc_l +# `_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l` Advances a string pointer by one character. > [!IMPORTANT] -> **_mbsinc** and **_mbsinc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsinc`** and **`_mbsinc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -39,43 +39,43 @@ unsigned char *_mbsinc_l( ### Parameters -*current*
+*`current`*\ Character pointer. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a pointer to the character that immediately follows *current*. +Each of these routines returns a pointer to the character that immediately follows *`current`*. ## Remarks -The **_mbsinc** function returns a pointer to the first byte of the multibyte character that immediately follows *current*. **_mbsinc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) that's currently in use; **_mbsinc_l** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_mbsinc`** function returns a pointer to the first byte of the multibyte character that immediately follows *`current`*. **`_mbsinc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) that's currently in use; **`_mbsinc_l`** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -The generic-text function **_tcsinc**, defined in Tchar.h, maps to **_mbsinc** if **_MBCS** has been defined, or to **_wcsinc** if **_UNICODE** has been defined. Otherwise, **_tcsinc** maps to **_strinc**. **_strinc** and **_wcsinc** are single-byte-character and wide-character versions of **_mbsinc**. **_strinc** and **_wcsinc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +The generic-text function `_tcsinc`, defined in Tchar.h, maps to **`_mbsinc`** if `_MBCS` has been defined, or to **`_wcsinc`** if `_UNICODE` has been defined. Otherwise, `_tcsinc` maps to **`_strinc`**. **`_strinc`** and **`_wcsinc`** are single-byte-character and wide-character versions of **`_mbsinc`**. **`_strinc`** and **`_wcsinc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -If *current* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **EINVAL** and sets **errno** to **EINVAL**. +If *`current`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `EINVAL` and sets `errno` to `EINVAL`. > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsinc**|\| -|**_mbsinc_l**|\| -|**_strinc**|\| -|**_wcsinc**|\| +| Routine | Required header | +|---|---| +| **`_mbsinc`** | \ | +| **`_mbsinc_l`** | \ | +| **`_strinc`** | \ | +| **`_wcsinc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md b/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md index 4e1f666899..73cda48cad 100644 --- a/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md +++ b/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _ title: "strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l" ms.date: "4/2/2020" api_name: ["_mbslen", "_mbslen_l", "_mbstrlen", "wcslen", "_mbstrlen_l", "strlen", "_o__mbslen", "_o__mbslen_l", "_o__mbstrlen", "_o__mbstrlen_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbstrlen", "wcslen", "_tcslen", "_ftcslen", "strlen", "_mbslen"] @@ -44,13 +44,13 @@ size_t _mbstrlen_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Each of these functions returns the number of characters in *`str`*, excluding the terminal null. No return value is reserved to indicate an error, except for **`_mbstrlen`** and **`_mbstrlen_l`**, which return `((size_t)(-1))` if the string contains an invalid multibyte character. @@ -58,32 +58,32 @@ Each of these functions returns the number of characters in *`str`*, excluding t **`strlen`** interprets the string as a single-byte character string, so its return value is always equal to the number of bytes, even if the string contains multibyte characters. **`wcslen`** is a wide-character version of **`strlen`**; the argument of **`wcslen`** is a wide-character string and the count of characters is in wide (two-byte) characters. **`wcslen`** and **`strlen`** behave identically otherwise. -**Security Note** These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcslen`**|**`strlen`**|**`strlen`**|**`wcslen`**| -|**`_tcsclen`**|**`strlen`**|**`_mbslen`**|**`wcslen`**| -|**`_tcsclen_l`**|**`strlen`**|**`_mbslen_l`**|**`wcslen`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslen` | **`strlen`** | **`strlen`** | **`wcslen`** | +| `_tcsclen` | **`strlen`** | **`_mbslen`** | **`wcslen`** | +| `_tcsclen_l` | **`strlen`** | **`_mbslen_l`** | **`wcslen`** | -**`_mbslen`** and **`_mbslen_l`** return the number of multibyte characters in a multibyte-character string but they do not test for multibyte-character validity. **`_mbstrlen`** and **`_mbstrlen_l`** test for multibyte-character validity and recognize multibyte-character sequences. If the string passed to **`_mbstrlen`** or **`_mbstrlen_l`** contains an invalid multibyte character for the code page, the function returns -1 and sets **`errno`** to **`EILSEQ`**. +**`_mbslen`** and **`_mbslen_l`** return the number of multibyte characters in a multibyte-character string but they don't test for multibyte-character validity. **`_mbstrlen`** and **`_mbstrlen_l`** test for multibyte-character validity and recognize multibyte-character sequences. If the string passed to **`_mbstrlen`** or **`_mbstrlen_l`** contains an invalid multibyte character for the code page, the function returns -1 and sets `errno` to `EILSEQ`. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strlen`**|``| -|**`wcslen`**|`` or ``| -|**`_mbslen`**, **`_mbslen_l`**|``| -|**`_mbstrlen`**, **`_mbstrlen_l`**|``| +| Routine | Required header | +|---|---| +| **`strlen`** | `` | +| **`wcslen`** | `` or `` | +| **`_mbslen`**, **`_mbslen_l`** | `` | +| **`_mbstrlen`**, **`_mbstrlen_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,14 +150,14 @@ Bytes in 'ABCァD' : 6 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md b/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md index ffda71534d..41dd865686 100644 --- a/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md +++ b/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, title: "_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l" ms.date: "4/2/2020" api_name: ["_strlwr_s_l", "_mbslwr_s_l", "_mbslwr_s", "_wcslwr_s", "_strlwr_s", "_wcslwr_s_l", "_o__mbslwr_s", "_o__mbslwr_s_l", "_o__strlwr_s", "_o__strlwr_s_l", "_o__wcslwr_s", "_o__wcslwr_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strlwr_s_l", "_strlwr_s", "mbslwr_s_l", "strlwr_s_l", "_wcslwr_s", "strlwr_s", "mbslwr_s", "_wcslwr_s_l", "wcslwr_s_l", "_tcslwr_s", "_tcslwr_s_l", "_mbslwr_s_l", "wcslwr_s", "_mbslwr_s"] helpviewer_keywords: ["_tcslwr_s function", "wcslwr_s function", "_mbslwr_s function", "_wcslwr_s function", "strlwr_s_l function", "mbslwr_s_l function", "_strlwr_s function", "string conversion [C++], case", "strlwr_s function", "wcslwr_s_l function", "_tcslwr_s_l function", "mbslwr_s function", "strings [C++], case", "_wcslwr_s_l function", "converting case, CRT functions", "_strlwr_s_l function", "_mbslwr_s_l function", "case, converting", "tcslwr_s function", "tcslwr_s_l function", "strings [C++], converting case"] ms.assetid: 4883d31b-bdac-4049-83a1-91dfdeceee79 --- -# _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l +# `_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l` -Converts a string to lowercase, by using the current locale or a locale object that's passed in. These versions of [_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a string to lowercase, by using the current locale or a locale object that's passed in. These versions of [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbslwr_s** and **_mbslwr_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbslwr_s`** and **`_mbslwr_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -78,49 +78,49 @@ errno_t _wcslwr_s_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to convert to lowercase. -*numberOfElements*
+*`numberOfElements`*\ Size of the buffer. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful; a non-zero error code on failure. -These functions validate their parameters. If *str* is not a valid null-terminated string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. If *numberOfElements* is less than the length of the string, the functions also return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`str`* isn't a valid null-terminated string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. If *`numberOfElements`* is less than the length of the string, the functions also return `EINVAL` and set `errno` to `EINVAL`. ## Remarks -The **_strlwr_s** function converts, in place, any uppercase letters in *str* to lowercase. **_mbslwr_s** is a multi-byte character version of **_strlwr_s**. **_wcslwr_s** is a wide-character version of **_strlwr_s**. +The **`_strlwr_s`** function converts, in place, any uppercase letters in *`str`* to lowercase. **`_mbslwr_s`** is a multi-byte character version of **`_strlwr_s`**. **`_wcslwr_s`** is a wide-character version of **`_strlwr_s`**. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcslwr_s**|**_strlwr_s**|**_mbslwr_s**|**_wcslwr_s**| -|**_tcslwr_s_l**|**_strlwr_s_l**|**_mbslwr_s_l**|**_wcslwr_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslwr_s` | **`_strlwr_s`** | **`_mbslwr_s`** | **`_wcslwr_s`** | +| `_tcslwr_s_l` | **`_strlwr_s_l`** | **`_mbslwr_s_l`** | **`_wcslwr_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strlwr_s**, **_strlwr_s_l**|\| -|**_mbslwr_s**, **_mbslwr_s_l**|\| -|**_wcslwr_s**, **_wcslwr_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_strlwr_s`**, **`_strlwr_s_l`** | \ | +| **`_mbslwr_s`**, **`_mbslwr_s_l`** | \ | +| **`_wcslwr_s`**, **`_wcslwr_s_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -162,7 +162,7 @@ Upper: THE STRING TO END ALL STRINGS! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) diff --git a/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md b/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md index 8ce41f53d4..0592f466da 100644 --- a/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md +++ b/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, title: "_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l" ms.date: "4/2/2020" api_name: ["_strlwr_l", "_strlwr", "_wcslwr_l", "_mbslwr_l", "_wcslwr", "_mbslwr", "_o__mbslwr", "_o__mbslwr_l", "_o__strlwr", "_o__strlwr_l", "_o__wcslwr", "_o__wcslwr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strlwr", "wcslwr_l", "_ftcslwr", "mbslwr_l", "_mbslwr", "_wcslwr", "strlwr_l", "_tcslwr", "mbslwr"] helpviewer_keywords: ["tcslwr function", "_strlwr function", "converting case", "string conversion [C++], case", "mbslwr function", "_strlwr_l function", "strlwr_l function", "_wcslwr function", "ftcslwr function", "strings [C++], case", "_tcslwr_l function", "_wcslwr_l function", "wcslwr_l function", "mbslwr_l function", "tcslwr_l function", "_tcslwr function", "converting case, CRT functions", "_ftcslwr function", "_mbslwr function", "case, converting", "strings [C++], converting case", "_mbslwr_l function"] ms.assetid: d279181d-2e7d-401f-ab44-6e7c2786a046 --- -# _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l +# `_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l` -Converts a string to lowercase. More secure versions of these functions are available; see [_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md). +Converts a string to lowercase. More secure versions of these functions are available; see [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md). > [!IMPORTANT] -> **_mbslwr** and **_mbslwr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbslwr`** and **`_mbslwr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -72,44 +72,44 @@ unsigned char *_mbslwr_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to convert to lowercase. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Each of these functions returns a pointer to the converted string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument. No return value is reserved to indicate an error. ## Remarks -The **_strlwr** function converts any uppercase letters in *str* to lowercase as determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for their locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_strlwr`** function converts any uppercase letters in *`str`* to lowercase as determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for their locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -The **_wcslwr** and **_mbslwr** functions are wide-character and multibyte-character versions of **_strlwr**. The argument and return value of **_wcslwr** are wide-character strings; those of **_mbslwr** are multibyte-character strings. These three functions behave identically otherwise. +The **`_wcslwr`** and **`_mbslwr`** functions are wide-character and multibyte-character versions of **`_strlwr`**. The argument and return value of **`_wcslwr`** are wide-character strings. The argument and return value of **`_mbslwr`** are multibyte-character strings. These three functions behave identically otherwise. -If *str* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set **errno** to **EINVAL**. +If *`str`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set `errno` to `EINVAL`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcslwr**|**_strlwr**|**_mbslwr**|**_wcslwr**| -|**_tcslwr_l**|**_strlwr_l**|**_mbslwr_l**|**_wcslwr_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslwr` | **`_strlwr`** | **`_mbslwr`** | **`_wcslwr`** | +| `_tcslwr_l` | **`_strlwr_l`** | **`_mbslwr_l`** | **`_wcslwr_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strlwr**, **_strlwr_l**|\| -|**_wcslwr**, **_wcslwr_l**|\ or \| -|**_mbslwr**, **_mbslwr_l**|\| +| Routine | Required header | +|---|---| +| **`_strlwr`**, **`_strlwr_l`** | \ | +| **`_wcslwr`**, **`_wcslwr_l`** | \ or \ | +| **`_mbslwr`**, **`_mbslwr_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -149,6 +149,6 @@ Upper: THE STRING TO END ALL STRINGS! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) diff --git a/docs/c-runtime-library/reference/strlwr-wcslwr.md b/docs/c-runtime-library/reference/strlwr-wcslwr.md index e3e3f281e2..4584af826b 100644 --- a/docs/c-runtime-library/reference/strlwr-wcslwr.md +++ b/docs/c-runtime-library/reference/strlwr-wcslwr.md @@ -10,8 +10,8 @@ f1_keywords: ["wcslwr", "strlwr"] helpviewer_keywords: ["strlwr function", "wcslwr function"] ms.assetid: b9274824-4365-4674-b656-823c89653656 --- -# strlwr, wcslwr +# `strlwr`, `wcslwr` -The Microsoft-specific function names `strlwr` and `wcslwr` are deprecated aliases for the [_strlwr and _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strlwr` and `wcslwr` are deprecated aliases for the [`_strlwr` and `_wcslwr`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strlwr or _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) or the security-enhanced [_strlwr_s and _wcslwr_s](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [_strlwr or _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) or the security-enhanced [`_strlwr_s` and `_wcslwr_s`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md b/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md index 4a7faa8c6e..80f787fd85 100644 --- a/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md +++ b/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l title: "strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l" ms.date: "3/25/2021" api_name: ["_wcsncat_s_l", "wcsncat_s", "_mbsncat_s_l", "_mbsncat_s", "strncat_s", "_strncat_s_l", "_o__mbsncat_s", "_o__mbsncat_s_l", "_o_strncat_s", "_o_wcsncat_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strncat_s_l", "_mbsncat_s_l", "_tcsncat_s", "wcsncat_s", "wcsncat_s_l", "strncat_s", "_mbsncat_s", "_tcsncat_s_l"] helpviewer_keywords: ["concatenating strings", "_mbsncat_s function", "mbsncat_s_l function", "_tcsncat_s function", "_mbsncat_s_l function", "strncat_s function", "strings [C++], appending", "strncat_s_l function", "string concatenation [C++]", "_tcsncat_s_l function", "wcsncat_s function", "appending strings", "wcsncat_s_l function", "mbsncat_s function"] ms.assetid: de77eca2-4d9c-4e66-abf2-a95fefc21e5a --- -# strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l +# `strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l` -Appends characters to a string. These versions of [strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Appends characters to a string. These versions of [`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsncat_s** and **_mbsncat_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncat_s`** and **`_mbsncat_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -102,38 +102,38 @@ errno_t _mbsncat_s_l( ### Parameters -*strDest*
+*`strDest`*\ Null-terminated destination string. -*numberOfElements*
+*`numberOfElements`*\ Size of the destination buffer. -*strSource*
+*`strSource`*\ Null-terminated source string. -*count*
-Number of characters to append, or [_TRUNCATE](../../c-runtime-library/truncate.md). +*`count`*\ +Number of characters to append, or [`_TRUNCATE`](../truncate.md). -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns 0 if successful, an error code on failure. -### Error Conditions +### Error conditions -|*strDestination*|*numberOfElements*|*strSource*|Return value|Contents of *strDestination*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**NULL** or unterminated|any|any|**EINVAL**|not modified| -|any|any|**NULL**|**EINVAL**|not modified| -|any|0, or too small|any|**ERANGE**|not modified| +| *`strDestination`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDestination`* | +|---|---|---|---|---| +| `NULL` or unterminated | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | not modified | +| any | 0, or too small | any | `ERANGE` | not modified | ## Remarks -These functions try to append the first *D* characters of *strSource* to the end of *strDest*, where *D* is the lesser of *count* and the length of *strSource*. If appending those *D* characters will fit within *strDest* (whose size is given as *numberOfElements*) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of *strDest*, and a new terminating null is appended; otherwise, *strDest*[0] is set to the null character and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions try to append the first `D` characters of *`strSource`* to the end of *`strDest`*, where `D` is the lesser of *`count`* and the length of *`strSource`*. If appending those `D` characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of *`strDest`*, and a new terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -There is an exception to the above paragraph. If *count* is [_TRUNCATE](../../c-runtime-library/truncate.md), then as much of *strSource* as will fit is appended to *strDest* while still leaving room to append a terminating null. +There's an exception to the above paragraph. If *`count`* is [`_TRUNCATE`](../truncate.md), then as much of *`strSource`* as will fit is appended to *`strDest`* while still leaving room to append a terminating null. For example, @@ -143,9 +143,9 @@ strncpy_s(dst, _countof(dst), "12", 2); strncat_s(dst, _countof(dst), "34567", 3); ``` -means that we're asking **strncat_s** to append three characters to two characters in a buffer five characters long; this would leave no space for the null terminator, hence **strncat_s** zeroes out the string and calls the invalid parameter handler. +means that we're asking **`strncat_s`** to append three characters to two characters in a buffer five characters long; it would leave no space for the null terminator, so **`strncat_s`** zeroes out the string, and calls the invalid parameter handler. -If truncation behavior is needed, use **_TRUNCATE** or adjust the *count* parameter accordingly: +If truncation behavior is needed, use `_TRUNCATE` or adjust the *`count`* parameter accordingly: ```C strncat_s(dst, _countof(dst), "34567", _TRUNCATE); @@ -159,36 +159,36 @@ strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1); In all cases, the resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. -If *strSource* or *strDest* is **NULL**, or *numberOfElements* is zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns **EINVAL** without modifying its parameters. +If *`strSource`* or *`strDest`* is `NULL`, or *`numberOfElements`* is zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns `EINVAL` without modifying its parameters. -**wcsncat_s** and **_mbsncat_s** are wide-character and multibyte-character versions of **strncat_s**. The string arguments and return value of **wcsncat_s** are wide-character strings; those of **_mbsncat_s** are multibyte-character strings. These three functions behave identically otherwise. +**`wcsncat_s`** and **`_mbsncat_s`** are wide-character and multibyte-character versions of **`strncat_s`**. The string arguments and return value of **`wcsncat_s`** are wide-character strings. The arguments and return value of **`_mbsncat_s`** are multibyte-character strings. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale. For more information, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncat_s**|**strncat_s**|**_mbsnbcat_s**|**wcsncat_s**| -|**_tcsncat_s_l**|**_strncat_s_l**|**_mbsnbcat_s_l**|**_wcsncat_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncat_s` | **`strncat_s`** | **`_mbsnbcat_s`** | **`wcsncat_s`** | +| `_tcsncat_s_l` | **`_strncat_s_l`** | **`_mbsnbcat_s_l`** | **`_wcsncat_s_l`** | -**_strncat_s_l** and **_wcsncat_s_l** have no locale dependence; they're are only provided for **_tcsncat_s_l**. +**`_strncat_s_l`** and **`_wcsncat_s_l`** have no locale dependence; they're only provided for **`_tcsncat_s_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strncat_s**|\| -|**wcsncat_s**|\ or \| -|**_mbsncat_s**, **_mbsncat_s_l**|\| +| Routine | Required header | +|---|---| +| **`strncat_s`** | \ | +| **`wcsncat_s`** | \ or \ | +| **`_mbsncat_s`**, **`_mbsncat_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -329,16 +329,16 @@ Invalid parameter handler invoked: (L"Buffer is too small" && 0) ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md b/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md index 6d4f57cb24..53ae6ad1df 100644 --- a/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md +++ b/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" title: "strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" +description: "Learn more about: strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" ms.date: "1/20/2021" api_name: ["strncat", "_strncat_l", "_mbsncat", "_mbsncat_l", "wcsncat", "wcsncat_l", "_o__mbsncat", "_o__mbsncat_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsncat_l", "_wcsncat_l", "_tcsnccat_l", "_mbsncat", "_strncat_l", "strncat", "_tcsnccat", "_mbsncat_l", "_ftcsncat", "wcsncat", "_tcsncat"] helpviewer_keywords: ["concatenating strings", "ftcsncat function", "tcsncat_l function", "_tcsnccat_l function", "_tcsncat function", "strncat function", "_ftcsncat function", "mbsncat function", "mbsncat_l function", "strings [C++], appending", "wcsncat function", "tcsnccat function", "tcsnccat_l function", "_tcsnccat function", "string concatenation [C++]", "appending strings", "characters [C++], appending to strings", "_mbsncat function", "_tcsncat_l function", "_mbsncat_l function", "tcsncat function"] --- -# strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l +# `strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l` -Appends characters of a string. More secure versions of these functions are available, see `[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) . +Appends characters of a string. More secure versions of these functions are available; see [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md). > [!IMPORTANT] -> **`_mbsncat`** and **`_mbsncat_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncat`** and **`_mbsncat_l`** can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -81,7 +81,7 @@ Number of characters to append. *`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the destination string. No return value is reserved to indicate an error. @@ -90,20 +90,20 @@ Returns a pointer to the destination string. No return value is reserved to indi The **`strncat`** function appends, at most, the first *`count`* characters of *`strSource`* to *`strDest`*. The initial character of *`strSource`* overwrites the terminating null character of *`strDest`*. If a null character appears in *`strSource`* before *`count`* characters are appended, **`strncat`** appends all characters from *`strSource`*, up to the null character. If *`count`* is greater than the length of *`strSource`*, the length of *`strSource`* is used in place of *`count`*. In all cases, the resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> **`strncat`** does not check for sufficient space in *`strDest`*; it is therefore a potential cause of buffer overruns. Keep in mind that *`count`* limits the number of characters appended; it is not a limit on the size of *`strDest`*. See the example below. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> **`strncat`** does not check for sufficient space in *`strDest`*; it is therefore a potential cause of buffer overruns. Keep in mind that *`count`* limits the number of characters appended; it is not a limit on the size of *`strDest`*. See the example below. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -**`wcsncat`** and **`_mbsncat`** are wide-character and multibyte-character versions of **`strncat`**. The string arguments and return value of **`wcsncat`** are wide-character strings; those of **`_mbsncat`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcsncat`** and **`_mbsncat`** are wide-character and multibyte-character versions of **`strncat`**. The string arguments and return value of **`wcsncat`** are wide-character strings. The string arguments and return value of **`_mbsncat`** are multibyte-character strings. These three functions behave identically otherwise. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings | `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | -|--|--|--|--| +|---|---|---|---| | **`_tcsncat`** | **`strncat`** | **`_mbsnbcat`** | **`wcsncat`** | | **`_tcsncat_l`** | **`_strncat_l`** | **`_mbsnbcat_l`** | **`_wcsncat_l`** | @@ -112,14 +112,14 @@ By default, this function's global state is scoped to the application. To change ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncat`**|\| -|**`wcsncat`**|\ or \| -|**`_mbsncat`**|\| -|**`_mbsncat_l`**|\| +| Routine | Required header | +|---|---| +| **`strncat`** | \ | +| **`wcsncat`** | \ or \ | +| **`_mbsncat`** | \ | +| **`_mbsncat_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -168,20 +168,20 @@ After BadAppend : This is the initial string!Extra text to add to (47 chars) After GoodAppend: This is the initial string!Extra text t (39 chars) ``` -Note that **BadAppend** caused a buffer overrun. +You can see that `BadAppend` caused a buffer overrun. ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[`_mbsnbcat, _mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ -[`strcat, wcscat, _mbscat`](strcat-wcscat-mbscat.md)\ -[`strcmp, wcscmp, _mbscmp`](strcmp-wcscmp-mbscmp.md)\ -[`strcpy, wcscpy, _mbscpy`](strcpy-wcscpy-mbscpy.md)\ -[`strncmp, wcsncmp, _mbsncmp, _mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ -[`strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ -[`_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ -[`strrchr, wcsrchr, _mbsrchr, _mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ -[`_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ -[`strspn, wcsspn, _mbsspn, _mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md b/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md index 84d81d578b..78e1b172c5 100644 --- a/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md +++ b/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strncmp, wcsncmp, _mbsncmp, _mbsncmp_l" title: "strncmp, wcsncmp, _mbsncmp, _mbsncmp_l" ms.date: "4/2/2020" api_name: ["strncmp", "_mbsncmp", "wcsncmp", "_mbsncmp_l", "_o__mbsncmp", "_o__mbsncmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsnccmp", "_ftcsncmp", "_tcsncmp", "_tcsnccmp", "strncmp", "_mbsncmp", "wcsncmp"] @@ -49,57 +49,56 @@ int _mbsncmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Strings to compare. -*`count`*
+*`count`*\ Number of characters to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value indicates the relation of the substrings of *`string1`* and *`string2`* as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*`string1`* substring less than *`string2`* substring| -|0|*`string1`* substring identical to *`string2`* substring| -|> 0|*`string1`* substring greater than *`string2`* substring| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring less than *`string2`* substring | +| 0 | *`string1`* substring identical to *`string2`* substring | +| > 0 | *`string1`* substring greater than *`string2`* substring | -On a parameter validation error, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR*`*, which is defined in `` and ``. +On a parameter validation error, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR`**, which is defined in `` and ``. ## Remarks The **`strncmp`** function performs an ordinal comparison of at most the first *`count`* characters in *`string1`* and *`string2`* and returns a value indicating the relationship between the substrings. **`strncmp`** is a case-sensitive version of **`_strnicmp`**. **`wcsncmp`** and **`_mbsncmp`** are case-sensitive versions of **`_wcsnicmp`** and **`_mbsnicmp`**. -**`wcsncmp`** and **`_mbsncmp`** are wide-character and multibyte-character versions of **`strncmp`**. The arguments of **`wcsncmp`** are wide-character strings; those of **`_mbsncmp`** are multibyte-character strings. **`_mbsncmp`** recognizes multibyte-character sequences according to a multibyte code page and returns **`_NLSCMPERROR`** on an error. +**`wcsncmp`** and **`_mbsncmp`** are wide-character and multibyte-character versions of **`strncmp`**. The arguments of **`wcsncmp`** are wide-character strings. The arguments of **`_mbsncmp`** are multibyte-character strings. **`_mbsncmp`** recognizes multibyte-character sequences according to a multibyte code page and returns `_NLSCMPERROR` on an error. -Also, **`_mbsncmp`** and **`_mbsncmp_l`** validate parameters. If *`string1`* or *`string2`* is a null pointer and *`count`* is not equal to 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. **`strncmp`** and **`wcsncmp`** do not validate their parameters. These functions behave identically otherwise. +Also, **`_mbsncmp`** and **`_mbsncmp_l`** validate parameters. If *`string1`* or *`string2`* is a null pointer and *`count`* isn't equal to 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsncmp`** and **`_mbsncmp_l`** return `_NLSCMPERROR` and set `errno` to `EINVAL`. **`strncmp`** and **`wcsncmp`** don't validate their parameters. These functions behave identically otherwise. -The comparison behavior of **`_mbsncmp`** and **`_mbsncmp_l`** is affected by the setting of the **`LC_CTYPE`** category setting of the locale. This controls detection of leading and trailing bytes of multibyte characters. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsncmp`** function uses the current locale for this locale-dependent behavior. The **`_mbsncmp_l`** function is identical except that it uses the *locale* parameter instead. For more information, see [Locale](../../c-runtime-library/locale.md). If the locale is a single-byte locale, the behavior of these functions is identical to **`strncmp`**. +The comparison behavior of **`_mbsncmp`** and **`_mbsncmp_l`** is affected by the setting of the `LC_CTYPE` category setting of the locale. This controls detection of leading and trailing bytes of multibyte characters. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsncmp`** function uses the current locale for this locale-dependent behavior. The **`_mbsncmp_l`** function is identical except that it uses the *`locale`* parameter instead. For more information, see [Locale](../locale.md). If the locale is a single-byte locale, the behavior of these functions is identical to **`strncmp`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsnccmp`**|**`strncmp`**|**`_mbsncmp`**|**`wcsncmp`**| -|**`_tcsncmp`**|**`strncmp`**|**`_mbsnbcmp`**|**`wcsncmp`**| -|**`_tccmp`**|Maps to macro or inline function|**`_mbsncmp`**|Maps to macro or inline function| -|**not applicable**|**not applicable**|**`_mbsncmp_l`**|**not applicable**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnccmp` | **`strncmp`** | **`_mbsncmp`** | **`wcsncmp`** | +| `_tcsncmp` | **`strncmp`** | **`_mbsnbcmp`** | **`wcsncmp`** | +| `_tccmp` | Maps to macro or inline function | **`_mbsncmp`** | Maps to macro or inline function | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncmp`**|``| -|**`wcsncmp`**|`` or ``| -|**`_mbsncmp`**, **`_mbsncmp_l`**|``| +| Routine | Required header | +|---|---| +| **`strncmp`** | `` | +| **`wcsncmp`** | `` or `` | +| **`_mbsncmp`**, **`_mbsncmp_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -152,14 +151,14 @@ Result: String 1 is equal to string 2 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)
-[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md b/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md index 76335ff106..2c9cdcfed2 100644 --- a/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md +++ b/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" title: "_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" +description: "Learn more about: _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" ms.date: "4/2/2020" api_name: ["_mbsnbcnt_l", "_mbsnccnt", "_wcsncnt", "_strncnt", "_mbsnccnt_l", "_mbsnbcnt", "_o__mbsnbcnt", "_o__mbsnbcnt_l", "_o__mbsnccnt", "_o__mbsnccnt_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbsnbcnt", "wcsncnt", "_tcsnbcnt", "_mbsnccnt", "_ftcsnbcnt", "mbsnbcnt", "strncnt", "mbsnbcnt_l", "mbsnccnt_l", "mbsnccnt", "_strncnt", "_wcsncnt"] helpviewer_keywords: ["_strncnt function", "_mbsnbcnt function", "_mbsnbcnt_l function", "_mbsnccnt_l function", "mbsnbcnt_l function", "mbsnbcnt function", "tcsnbcnt function", "mbsnccnt_l function", "strncnt function", "_tcsnbcnt function", "mbsnccnt function", "wcsncnt function", "_mbsnccnt function", "_wcsncnt function"] -ms.assetid: 2a022e9e-a307-4acb-a66b-e56e5357f848 --- -# _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l +# `_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l` Returns the number of characters or bytes within a specified count. > [!IMPORTANT] -> **_mbsnbcnt**, **_mbsnbcnt_l**, **_mbsnccnt**, and **_mbsnccnt_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnbcnt`**, **`_mbsnbcnt_l`**, **`_mbsnccnt`**, and **`_mbsnccnt_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -50,63 +49,63 @@ size_t _mbsnccnt_l( ### Parameters -*str*
+*`str`*\ String to be examined. -*count*
-Number of characters or bytes to be examined in *str*. +*`count`*\ +Number of characters or bytes to be examined in *`str`*. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsnbcnt** and **_mbsnbcnt_l** return the number of bytes found in the first *count* of multibyte characters of *str*. **_mbsnccnt** and **_mbsnccnt_l** return the number of characters found in the first *count* of bytes of *str*. If a null character is encountered before the examination of *str* has completed, they return the number of bytes or characters found before the null character. If *str* consists of fewer than *count* characters or bytes, they return the number of characters or bytes in the string. If *count* is less than zero, they return 0. In previous versions, these functions had a return value of type **`int`** rather than **size_t**. +**`_mbsnbcnt`** and **`_mbsnbcnt_l`** return the number of bytes found in the first *`count`* of multibyte characters of *`str`*. **`_mbsnccnt`** and **`_mbsnccnt_l`** return the number of characters found in the first *`count`* of bytes of *`str`*. If a null character is encountered before the examination of *`str`* has completed, they return the number of bytes or characters found before the null character. If *`str`* consists of fewer than *`count`* characters or bytes, they return the number of characters or bytes in the string. If *`count`* is less than zero, they return 0. In previous versions, these functions had a return value of type **`int`** rather than `size_t`. -**_strncnt** returns the number of characters in the first *count* bytes of the single-byte string *str*. **_wcsncnt** returns the number of characters in the first *count* wide characters of the wide-character string *str*. +**`_strncnt`** returns the number of characters in the first *`count`* bytes of the single-byte string *`str`*. **`_wcsncnt`** returns the number of characters in the first *`count`* wide characters of the wide-character string *`str`*. ## Remarks -**_mbsnbcnt** and **_mbsnbcnt_l** count the number of bytes found in the first *count* of multibyte characters of *str*. **_mbsnbcnt** and **_mbsnbcnt_l** replace **mtob** and should be used in place of **mtob**. +**`_mbsnbcnt`** and **`_mbsnbcnt_l`** count the number of bytes found in the first *`count`* of multibyte characters of *`str`*. **`_mbsnbcnt`** and **`_mbsnbcnt_l`** replace `mtob` and should be used in place of `mtob`. -**_mbsnccnt** and **_mbsnccnt_l** count the number of characters found in the first *count* of bytes of *str*. If **_mbsnccnt** and **_mbsnccnt_l** encounter a null character in the second byte of a double-byte character, the first byte is also considered to be null and is not included in the returned count value. **_mbsnccnt** and **_mbsnccnt_l** replace **btom** and should be used in place of **btom**. +**`_mbsnccnt`** and **`_mbsnccnt_l`** count the number of characters found in the first *`count`* of bytes of *`str`*. If **`_mbsnccnt`** and **`_mbsnccnt_l`** encounter a null character in the second byte of a double-byte character, the first byte is also considered to be null and isn't included in the returned count value. **`_mbsnccnt`** and **`_mbsnccnt_l`** replace `btom` and should be used in place of `btom`. -If *str* is a **NULL** pointer or is *count* is 0, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), **errno** is set to **EINVAL**, and the function returns 0. +If *`str`* is a `NULL` pointer or is *`count`* is 0, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md), `errno` is set to `EINVAL`, and the function returns 0. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|-------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnbcnt**|**_strncnt**|**_mbsnbcnt**|**_wcsncnt**| -|**_tcsnccnt**|**_strncnt**|**_mbsnbcnt**|n/a| -|**_wcsncnt**|n/a|n/a|**_mbsnbcnt**| -|**_wcsncnt**|n/a|n/a|**_mbsnccnt**| -|n/a|n/a|**_mbsnbcnt_l**|**_mbsnccnt_l**| +| Routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnbcnt` | **`_strncnt`** | **`_mbsnbcnt`** | **`_wcsncnt`** | +| `_tcsnccnt` | **`_strncnt`** | **`_mbsnbcnt`** | n/a | +| **`_wcsncnt`** | n/a | n/a | **`_mbsnbcnt`** | +| **`_wcsncnt`** | n/a | n/a | **`_mbsnccnt`** | +| n/a | n/a | **`_mbsnbcnt_l`** | **`_mbsnccnt_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcnt**|\| -|**_mbsnbcnt_l**|\| -|**_mbsnccnt**|\| -|**_mbsnccnt_l**|\| -|**_strncnt**|\| -|**_wcsncnt**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcnt`** | \ | +| **`_mbsnbcnt_l`** | \ | +| **`_mbsnccnt`** | \ | +| **`_mbsnccnt_l`** | \ | +| **`_strncnt`** | \ | +| **`_wcsncnt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_mbsnbcnt.c -#include -#include +#include +#include int main( void ) { @@ -129,7 +128,7 @@ The first 10 characters are single-byte. ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md) diff --git a/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md b/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md index 064cecd0ad..7e9c9b6a52 100644 --- a/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md +++ b/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _w title: "_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l" ms.date: "4/2/2020" api_name: ["_strncoll", "_mbsncoll_l", "_wcsncoll", "_wcsncoll_l", "_mbsncoll", "_strncoll_l", "_o__mbsncoll", "_o__mbsncoll_l", "_o__strncoll", "_o__strncoll_l", "_o__wcsncoll", "_o__wcsncoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["mbsncoll_l", "strncoll", "_wcsncoll", "_tcsnccoll", "_ftcsnccoll", "wcsncoll", "_mbsncoll", "wcsncoll_l", "strncoll_l", "_ftcsncoll", "_strncoll", "_tcsncoll", "mbsncoll"] +f1_keywords: ["STRING/_strncoll", "MBSTRING/_mbsncoll", "CORECRT_WSTRING/_wcsncoll", "TCHAR/_tcsncoll", "TCHAR/_tcsnccoll", "TCHAR/_ftcsncoll", "TCHAR/_ftcsnccoll", "STRING/_strncoll_l", "MBSTRING/_mbsncoll_l", "CORECRT_WSTRING/_wcsncoll_l", "TCHAR/_tcsncoll_l", "_strncoll", "_mbsncoll", "_wcsncoll", "_tcsncoll", "_tcsnccoll", "_ftcsncoll", "_ftcsnccoll", "_strncoll_l", "_mbsncoll_l", "_wcsncoll_l", "_tcsncoll_l", "strncoll", "mbsncoll", "wcsncoll", "tcsncoll", "tcsnccoll", "ftcsncoll", "ftcsnccoll", "strncoll_l", "mbsncoll_l", "wcsncoll_l", "tcsncoll_l"] helpviewer_keywords: ["_strncoll_l function", "code pages, using for string comparisons", "_strncoll function", "_mbsncoll function", "ftcsncoll function", "strncoll function", "_ftcsncoll function", "strncoll_l function", "wcsncoll function", "mbsncoll function", "_tcsncoll function", "_tcsnccoll function", "wcsncoll_l function", "tcsnccoll function", "mbsncoll_l function", "_mbsncoll_l function", "tcsncoll function", "_wcsncoll function", "strings [C++], comparing by code page", "_ftcsnccoll function", "ftcsnccoll function", "_wcsncoll_l function"] ms.assetid: e659a5a4-8afe-4033-8e72-17ffd4bdd8e9 --- -# _strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l +# `_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsncoll** and **_mbsncoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncoll`** and **`_mbsncoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,62 +57,62 @@ int _mbsncoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*count*
+*`count`*\ The number of characters to compare. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value that indicates the relationship of the substrings of *string1* and *string2*, as follows. +Each of these functions returns a value that indicates the relationship of the substrings of *`string1`* and *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* is less than *string2*.| -|0|*string1* is identical to *string2*.| -|> 0|*string1* is greater than *string2*.| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* is less than *`string2`*. | +| 0 | *`string1`* is identical to *`string2`*. | +| > 0 | *`string1`* is greater than *`string2`*. | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either STRING.h or MBSTRING.h. **_wcsncoll** can fail if either *string1* or *string2* contains wide-character codes that are outside the domain of the collating sequence. When an error occurs, **_wcsncoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsncoll**, set **errno** to 0 and then check **errno** after you call **_wcsncoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either STRING.h or MBSTRING.h. **`_wcsncoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes that are outside the domain of the collating sequence. When an error occurs, **`_wcsncoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsncoll`**, set `errno` to 0, and then check `errno` after the **`_wcsncoll`** call. ## Remarks -Each of these functions performs a case-sensitive comparison of the first *count* characters in *string1* and *string2*, according to the code page that's currently in use. Use these functions only when there is a difference between the character set order and the lexicographic character order in the code page, and when this difference is of interest for the string comparison. The character set order is locale-dependent. The versions of these functions that don't have the **_l** suffix use the current locale, but the versions that have the **_l** suffix use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these functions performs a case-sensitive comparison of the first *`count`* characters in *`string1`* and *`string2`*, according to the code page that's currently in use. Use these functions only when there's a difference between the character set order and the lexicographic character order in the code page, and when this difference matters for the string comparison. The character set order is locale-dependent. The versions of these functions that don't have the `_l` suffix use the current locale, but the versions that have the `_l` suffix use the locale that's passed in. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnccoll**|**_strncoll**|**_mbsncoll**|**_wcsncoll**| -|**_tcsncoll**|**_strncoll**|[_mbsnbcoll](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)|**_wcsncoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnccoll` | **`_strncoll`** | **`_mbsncoll`** | **`_wcsncoll`** | +| `_tcsncoll` | **`_strncoll`** | [`_mbsnbcoll`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md) | **`_wcsncoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strncoll**, **_strncoll_l**|\| -|**_wcsncoll**, **_wcsncoll_l**|\ or \| -|**_mbsncoll**, **_mbsncoll_l**|\| +| Routine | Required header | +|---|---| +| **`_strncoll`**, **`_strncoll_l`** | \ | +| **`_wcsncoll`**, **`_wcsncoll_l`** | \ or \ | +| **`_mbsncoll`**, **`_mbsncoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md b/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md index 72e600d5ad..784bbae4d5 100644 --- a/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md +++ b/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md @@ -1,22 +1,23 @@ --- description: "Learn more about: strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l" -title: "strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l" +title: "strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l, _tcsncpy_s, _tcsncpy_s_l, _tcsnccpy_s, _tcsnccpy_s_l" ms.date: "4/2/2020" -api_name: ["_mbsncpy_s_l", "wcsncpy_s", "_strncpy_s_l", "strncpy_s", "_mbsncpy_s", "_wcsncpy_s_l", "_o__mbsncpy_s", "_o__mbsncpy_s_l", "_o_strncpy_s", "_o_wcsncpy_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_mbsncpy_s_l", "wcsncpy_s", "_strncpy_s_l", "strncpy_s", "_mbsncpy_s", "_wcsncpy_s_l", "_o__mbsncpy_s", "_o__mbsncpy_s_l", "_o_strncpy_s", "_o_wcsncpy_s", "_tcsnccpy_s", "_tcsnccpy_s_l", "_tcsncpy_s", "_tcsncpy_s_l"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcsncpy_s", "_wcsncpy_s_l", "strncpy_s", "_strncpy_s_l", "wcsncpy_s", "_tcsncpy_s_l"] -helpviewer_keywords: ["_wcsncpy_s_l function", "_mbsnbcpy_s function", "_tcsncpy_s_l function", "mbsncpy_s function", "strncpy_s_l function", "_strncpy_s_l function", "strncpy_s function", "mbsncpy_s_l function", "wcsncpy_s function", "copying strings", "strings [C++], copying", "_mbsnbcpy_s_l function", "_tcsncpy_s function", "wcsncpy_s_l function"] -ms.assetid: a971c800-94d1-4d88-92f3-a2fe236a4546 +f1_keywords: ["_tcsncpy_s", "_wcsncpy_s_l", "strncpy_s", "_strncpy_s_l", "wcsncpy_s", "_tcsncpy_s_l", "_tcsnccpy_s", "_tcsnccpy_s_l"] +helpviewer_keywords: ["_wcsncpy_s_l function", "_mbsnbcpy_s function", "_tcsncpy_s_l function", "mbsncpy_s function", "strncpy_s_l function", "_strncpy_s_l function", "strncpy_s function", "mbsncpy_s_l function", "wcsncpy_s function", "_tcsnccpy_s function", "copying strings", "strings [C++], copying", "_mbsnbcpy_s_l function", "_tcsncpy_s function", "wcsncpy_s_l function", "_tcsnccpy_s_l function"] --- -# `strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l` +# `strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`, `_tcsncpy_s`, `_tcsncpy_s_l`, `_tcsnccpy_s`, `_tcsnccpy_s_l` -Copies characters of one string to another. These versions of [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies characters of one string to another. These versions of [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbsncpy_s`** and **`_mbsncpy_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +For `_tcsnccpy_s`, `_tcsnccpy_s_l`, `_tcsnccpy_s`, and `_tcsnccpy_s_l` see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -102,39 +103,39 @@ errno_t _mbsncpy_s_l( ### Parameters -*`strDest`*
+*`strDest`*\ Destination string. -*`numberOfElements`*
+*`numberOfElements`*\ The size of the destination string, in characters. -*`strSource`*
+*`strSource`*\ Source string. -*`count`*
-Number of characters to be copied, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +Number of characters to be copied, or [`_TRUNCATE`](../truncate.md). -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Zero if successful, **`STRUNCATE`** if truncation occurred, otherwise an error code. +Zero if successful, `STRUNCATE` if truncation occurred, otherwise an error code. -### Error Conditions +### Error conditions -|*`strDest`*|*`numberOfElements`*|*`strSource`*|Return value|Contents of *`strDest`*| -|---------------|------------------------|-----------------|------------------|---------------------------| -|**`NULL`**|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`strDest[0]`* set to 0| -|any|0|any|**`EINVAL`**|not modified| -|not **`NULL`**|too small|any|**`ERANGE`**|*`strDest[0]`* set to 0| +| *`strDest`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDest`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`strDest[0]`* set to 0 | +| any | 0 | any | `EINVAL` | not modified | +| not `NULL` | too small | any | `ERANGE` | *`strDest[0]`* set to 0 | ## Remarks -These functions try to copy the first *`D`* characters of *`strSource`* to *`strDest`*, where *`D`* is the lesser of *`count`* and the length of *`strSource`*. If those *`D`* characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are copied and a terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions try to copy the first *`D`* characters of *`strSource`* to *`strDest`*, where *`D`* is the lesser of *`count`* and the length of *`strSource`*. If those *`D`* characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are copied and a terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -There is an exception to the above paragraph. If *`count`* is **`_TRUNCATE`**, then as much of *`strSource`* as will fit into *`strDest`* is copied while still leaving room for the terminating null which is always appended. +There's an exception to the above paragraph. If *`count`* is `_TRUNCATE`, then as much of *`strSource`* as will fit into *`strDest`* is copied while still leaving room for the terminating null, which is always appended. For example, @@ -143,50 +144,54 @@ char dst[5]; strncpy_s(dst, 5, "a long string", 5); ``` -means that we are asking **`strncpy_s`** to copy five characters into a buffer five bytes long; this would leave no space for the null terminator, hence **`strncpy_s`** zeroes out the string and calls the invalid parameter handler. +means that **`strncpy_s`** copies five characters into a 5-byte buffer. This copy would leave no space for the null terminator, so **`strncpy_s`** zeroes out the string, and calls the invalid parameter handler. -If truncation behavior is needed, use **`_TRUNCATE`** or (*`size`* - 1): +If truncation behavior is needed, use `_TRUNCATE` or (*`size`* - 1): ```C strncpy_s(dst, 5, "a long string", _TRUNCATE); strncpy_s(dst, 5, "a long string", 4); ``` -Note that unlike **`strncpy`**, if *`count`* is greater than the length of *`strSource`*, the destination string is NOT padded with null characters up to length *`count`*. +Unlike **`strncpy`**, if *`count`* is greater than the length of *`strSource`*, the destination string is NOT padded with null characters up to length *`count`*. The behavior of **`strncpy_s`** is undefined if the source and destination strings overlap. -If *`strDest`* or *`strSource`* is **`NULL`**, or *`numberOfElements`* is 0, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns **`EINVAL`** and sets **`errno`** to **`EINVAL`**. +If *`strDest`* or *`strSource`* is `NULL`, or *`numberOfElements`* is 0, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns `EINVAL` and sets `errno` to `EINVAL`. **`wcsncpy_s`** and **`_mbsncpy_s`** are wide-character and multibyte-character versions of **`strncpy_s`**. The arguments and return value of **`wcsncpy_s`** and **`mbsncpy_s`** do vary accordingly. These six functions behave identically otherwise. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsncpy_s`**|**`strncpy_s`**|**`_mbsnbcpy_s`**|**`wcsncpy_s`**| -|**`_tcsncpy_s_l`**|**`_strncpy_s_l`**|**`_mbsnbcpy_s_l`**|**`_wcsncpy_s_l`**| +| `tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy_s` | **`strncpy_s`** | **`_mbsnbcpy_s`** | **`wcsncpy_s`** | +| `_tcsncpy_s_l` | **`_strncpy_s_l`** | **`_mbsnbcpy_s_l`** | **`_wcsncpy_s_l`** | +| `_tcsnccpy_s` | **`strncpy_s`** | **`_mbsncpy_s`** | **`_wcsncpy_s`** | +| `_tcsnccpy_s_l` | **`_strncpy_s_l`** | **`_mbsncpy_s_l`** | **`_wcsncpy_s_l`** | > [!NOTE] -> **`_strncpy_s_l`**, **`_wcsncpy_s_l`** and **`_mbsncpy_s_l`** have no locale dependence and are provided just for **`_tcsncpy_s_l`** and are not intended to be called directly. +> **`_strncpy_s_l`**, **`_wcsncpy_s_l`** and **`_mbsncpy_s_l`** have no locale dependence. They're provided just for `_tcsncpy_s_l` and aren't intended to be called directly. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncpy_s`**, **`_strncpy_s_l`**|``| -|**`wcsncpy_s`**, **`_wcsncpy_s_l`**|`` or ``| -|**`_mbsncpy_s`**, **`_mbsncpy_s_l`**|``| +| Routine | Required header | +|---|---| +| **`strncpy_s`**, **`_strncpy_s_l`** | `` | +| **`wcsncpy_s`**, **`_wcsncpy_s_l`** | `` or `` | +| **`_mbsncpy_s`**, **`_mbsncpy_s_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Copy chars to a buffer @@ -361,16 +366,16 @@ After strncpy_s (with null-termination): ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)
-[`strcat_s`, `wcscat_s`, `_mbscat_s`](strcat-s-wcscat-s-mbscat-s.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)
-[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ +[`strcat_s`, `wcscat_s`, `_mbscat_s`](strcat-s-wcscat-s-mbscat-s.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md b/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md index 9fc144bc70..5d7b9d4a72 100644 --- a/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md +++ b/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsnc title: "strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l" ms.date: "4/2/2020" api_name: ["strncpy", "_strncpy_l", "_mbsncpy", "wcsncpy", "_mbsncpy_l", "_wcsncpy_l", "_o__mbsncpy", "_o__mbsncpy_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrncpy", "strncpy", "_ftcsncpy", "_tcsnccpy_l", "_tcsnccpy", "_mbsncpy", "wcsncpy", "_tcsncpy", "_strncpy_l", "_mbsncpy_l", "_wcsncpy_l"] @@ -96,58 +96,58 @@ unsigned char *_mbsncpy_l( ### Parameters -*`strDest`*
+*`strDest`*\ Destination string. -*`strSource`*
+*`strSource`*\ Source string. -*`count`*
+*`count`*\ Number of characters to be copied. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns *`strDest`*. No return value is reserved to indicate an error. ## Remarks -The **`strncpy`** function copies the initial *`count`* characters of *`strSource`* to *`strDest`* and returns *`strDest`*. If *`count`* is less than or equal to the length of *`strSource`*, a null character is not appended automatically to the copied string. If *`count`* is greater than the length of *`strSource`*, the destination string is padded with null characters up to length *`count`*. The behavior of **`strncpy`** is undefined if the source and destination strings overlap. +The **`strncpy`** function copies the initial *`count`* characters of *`strSource`* to *`strDest`* and returns *`strDest`*. If *`count`* is less than or equal to the length of *`strSource`*, a null character isn't appended automatically to the copied string. If *`count`* is greater than the length of *`strSource`*, the destination string is padded with null characters up to length *`count`*. The behavior of **`strncpy`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> **`strncpy`** does not check for sufficient space in *`strDest`*; this makes it a potential cause of buffer overruns. The *`count`* argument limits the number of characters copied; it is not a limit on the size of *`strDest`*. See the following example. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> **`strncpy`** does not check for sufficient space in *`strDest`*; this makes it a potential cause of buffer overruns. The *`count`* argument limits the number of characters copied; it is not a limit on the size of *`strDest`*. See the following example. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -If *`strDest`* or *`strSource`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`strDest`* or *`strSource`* is a `NULL` pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. **`wcsncpy`** and **`_mbsncpy`** are wide-character and multibyte-character versions of **`strncpy`**. The arguments and return value of **`wcsncpy`** and **`_mbsncpy`** vary accordingly. These six functions behave identically otherwise. -The versions of these functions with the **`_l`** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the **`_l`** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsncpy`**|**`strncpy`**|**`_mbsnbcpy`**|**`wcsncpy`**| -|**`_tcsncpy_l`**|**`_strncpy_l`**|**`_mbsnbcpy_l`**|**`_wcsncpy_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy` | **`strncpy`** | **`_mbsnbcpy`** | **`wcsncpy`** | +| `_tcsncpy_l` | **`_strncpy_l`** | **`_mbsnbcpy_l`** | **`_wcsncpy_l`** | > [!NOTE] > **`_strncpy_l`** and **`_wcsncpy_l`** have no locale dependence; they are provided just for **`_tcsncpy_l`** and are not intended to be called directly. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncpy`**|``| -|**`wcsncpy`**|`` or ``| -|**`_mbsncpy`**, **`_mbsncpy_l`**|``| +| Routine | Required header | +|---|---| +| **`strncpy`** | `` | +| **`wcsncpy`** | `` or `` | +| **`_mbsncpy`**, **`_mbsncpy_l`** | `` | -For additional platform compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more platform compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -220,18 +220,18 @@ The layout of automatic variables and the level of error detection and code prot ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) diff --git a/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md b/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md index e43f9c5fe0..dfb9505274 100644 --- a/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md +++ b/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l" title: "_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l" ms.date: "4/2/2020" api_name: ["_strnextc", "_mbsnextc_l", "_mbsnextc", "_wcsnextc", "_o__mbsnextc", "_o__mbsnextc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strnextc", "tcsnextc", "_mbsnextc_l", "_mbsnextc", "mbsnextc_l", "ftcsnextc", "mbsnextc", "_tcsnextc", "_wcsnextc", "_ftcsnextc", "_strnextc", "wcsnextc"] helpviewer_keywords: ["_mbsnextc function", "_tcsnextc function", "_wcsnextc function", "tcsnextc function", "strnextc function", "mbsnextc function", "_strnextc function", "_mbsnextc_l function", "mbsnextc_l function", "wcsnextc function"] ms.assetid: e3086173-9eb5-4540-a23a-5d866bd05340 --- -# _strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l +# `_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l` Finds the next character in a string. > [!IMPORTANT] -> **_mbsnextc** and **_mbsnextc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnextc`** and **`_mbsnextc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -37,52 +37,52 @@ unsigned int _mbsnextc_l( ### Parameters -*str*
+*`str`*\ Source string. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns the integer value of the next character in *str*. +Each of these functions returns the integer value of the next character in *`str`*. ## Remarks -The **_mbsnextc** function returns the integer value of the next multibyte character in *str*, without advancing the string pointer. **_mbsnextc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. +The **`_mbsnextc`** function returns the integer value of the next multibyte character in *`str`*, without advancing the string pointer. **`_mbsnextc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. -If *str* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns 0. +If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns 0. -**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnextc**|**_strnextc**|**_mbsnextc**|**_wcsnextc**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnextc` | **`_strnextc`** | **`_mbsnextc`** | **`_wcsnextc`** | -**_strnextc** and **_wcsnextc** are single-byte-character string and wide-character string versions of **_mbsnextc**. **_wcsnextc** returns the integer value of the next wide character in *str*; **_strnextc** returns the integer value of the next single-byte character in *str*. **_strnextc** and **_wcsnextc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strnextc`** and **`_wcsnextc`** are single-byte-character string and wide-character string versions of **`_mbsnextc`**. **`_wcsnextc`** returns the integer value of the next wide character in *`str`*; **`_strnextc`** returns the integer value of the next single-byte character in *`str`*. **`_strnextc`** and **`_wcsnextc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsnextc_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsnextc_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnextc**|\| -|**_mbsnextc_l**|\| -|**_strnextc**|\| -|**_wcsnextc**|\| +| Routine | Required header | +|---|---| +| **`_mbsnextc`** | \ | +| **`_mbsnextc_l`** | \ | +| **`_strnextc`** | \ | +| **`_wcsnextc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md b/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md index c8eb33cb84..8b95d93fba 100644 --- a/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md +++ b/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _w title: "_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l" ms.date: "4/2/2020" api_name: ["_wcsnicmp", "_strnicmp_l", "_wcsnicmp_l", "_strnicmp", "_mbsnicmp", "_mbsnicmp_l", "_o__mbsnicmp", "_o__mbsnicmp_l", "_o__strnicmp", "_o__strnicmp_l", "_o__wcsnicmp", "_o__wcsnicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcsnicmp_l", "_strnicmp", "_ftcsnicmp", "mbsnicmp_l", "_ftcsncicmp", "mbsnicmp", "_tcsncicmp", "_mbsnicmp", "_tcsnicmp", "strnicmp_l", "_wcsnicmp", "_wcsnicmp_l", "CORECRT_WSTRING/_wcsnicmp", "CORECRT_WSTRING/_wcsnicmp_l", "string/_strnicmp", "string/_strnicmp_l"] helpviewer_keywords: ["tcsnicmp function", "_tcsncicmp function", "_mbsnicmp_l function", "mbsnicmp_l function", "wcsnicmp_l function", "wcsnicmp function", "string comparison [C++], lowercase", "ftcsnicmp function", "strnicmp_l function", "strncmp function", "_strnicmp function", "strings [C++], comparing characters of", "_wcsnicmp_l function", "tcsncicmp function", "string comparison [C++], strncmp function", "_mbsnicmp function", "ftcsncicmp function", "_tcsnicmp function", "_ftcsncicmp function", "_strnicmp_l function", "_ftcsnicmp function", "characters [C++], comparing", "mbsnicmp function", "_wcsnicmp function"] ms.assetid: df6e5037-4039-4c85-a0a6-21d4ef513966 --- -# _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l +# `_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l` Compares the specified number of characters of two strings without regard to case. > [!IMPORTANT] -> **_mbsnicmp** and **_mbsnicmp_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnicmp`** and **`_mbsnicmp_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,70 +57,70 @@ int _mbsnicmp_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*count*
+*`count`*\ Number of characters to compare. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Indicates the relationship between the substrings, as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*string1* substring is less than *string2* substring.| -|0|*string1* substring is identical to *string2* substring.| -|> 0|*string1* substring is greater than *string2* substring.| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring is less than *`string2`* substring. | +| 0 | *`string1`* substring is identical to *`string2`* substring. | +| > 0 | *`string1`* substring is greater than *`string2`* substring. | -On a parameter validation error, these functions return **_NLSCMPERROR**, which is defined in \ and \. +On a parameter validation error, these functions return `_NLSCMPERROR`, which is defined in \ and \. ## Remarks -The **_strnicmp** function ordinally compares, at most, the first *count* characters of *string1* and *string2*. The comparison is performed without regard to case by converting each character to lowercase. **_strnicmp** is a case-insensitive version of **strncmp**. The comparison ends if a terminating null character is reached in either string before *count* characters are compared. If the strings are equal when a terminating null character is reached in either string before *count* characters are compared, the shorter string is lesser. +The **`_strnicmp`** function compares, at most, the first *`count`* characters of *`string1`* and *`string2`*. The comparison is performed without regard to case by converting each character to lowercase. **`_strnicmp`** is a case-insensitive version of **`strncmp`**. The comparison ends if a terminating null character is reached in either string before *`count`* characters are compared. If the strings are equal when a terminating null character is reached in either string before *`count`* characters are compared, the shorter string is lesser. -The characters from 91 to 96 in the ASCII table ('[', '\\', ']', '^', '_', and '\`') evaluate as less than any alphabetic character. This ordering is identical to that of **stricmp**. +The characters from 91 to 96 in the ASCII table ('[', '\\', ']', '^', '_', and '\`') evaluate as less than any alphabetic character. This ordering is identical to that of **`stricmp`**. -**_wcsnicmp** and **_mbsnicmp** are wide-character and multibyte-character versions of **_strnicmp**. The arguments of **_wcsnicmp** are wide-character strings; those of **_mbsnicmp** are multibyte-character strings. **_mbsnicmp** recognizes multibyte-character sequences according to the current multibyte code page and returns **_NLSCMPERROR** on an error. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). These three functions behave identically otherwise. These functions are affected by the locale setting—the versions that don't have the **_l** suffix use the current locale for their locale-dependent behavior; the versions that do have the **_l** suffix instead use the *locale* that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_wcsnicmp`** and **`_mbsnicmp`** are wide-character and multibyte-character versions of **`_strnicmp`**. The arguments of **`_wcsnicmp`** are wide-character strings. The arguments of **`_mbsnicmp`** are multibyte-character strings. **`_mbsnicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. For more information, see [Code pages](../code-pages.md). These three functions behave identically otherwise. These functions are affected by the locale setting—the versions that don't have the `_l` suffix use the current locale for their locale-dependent behavior; the versions that do have the `_l` suffix instead use the *`locale`* that's passed in. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncicmp**|**_strnicmp**|**_mbsnicmp**|**_wcsnicmp**| -|**_tcsnicmp**|**_strnicmp**|**_mbsnbicmp**|**_wcsnicmp**| -|**_tcsncicmp_l**|**_strnicmp_l**|**_mbsnicmp_l**|**_wcsnicmp_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncicmp` | **`_strnicmp`** | **`_mbsnicmp`** | **`_wcsnicmp`** | +| `_tcsnicmp` | **`_strnicmp`** | **`_mbsnbicmp`** | **`_wcsnicmp`** | +| `_tcsncicmp_l` | **`_strnicmp_l`** | **`_mbsnicmp_l`** | **`_wcsnicmp_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnicmp**, **_strnicmp_l**|\| -|**_wcsnicmp**, **_wcsnicmp_l**|\ or \| -|**_mbsnicmp**, **_mbsnicmp_l**|\| +| Routine | Required header | +|---|---| +| **`_strnicmp`**, **`_strnicmp_l`** | \ | +| **`_wcsnicmp`**, **`_wcsnicmp_l`** | \ or \ | +| **`_mbsnicmp`**, **`_mbsnicmp_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md). +See the example for [`strncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md b/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md index a6cb2a2b07..3a9aea37f4 100644 --- a/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md +++ b/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsnicmp", "strnicmp"] helpviewer_keywords: ["strnicmp function", "wcsnicmp function"] ms.assetid: 01324ee4-0bd9-43e9-b2a3-53d180270a64 --- -# strnicmp, wcsnicmp +# `strnicmp`, `wcsnicmp` -The Microsoft-specific function names `strnicmp` and `wcsnicmp` are deprecated aliases for the [_strnicmp and _wcsnicmp](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strnicmp` and `wcsnicmp` are deprecated aliases for the [`_strnicmp` and `_wcsnicmp`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strnicmp and _wcsnicmp](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strnicmp` and `_wcsnicmp`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md b/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md index a7ed2d8322..b529a0df1b 100644 --- a/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md +++ b/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l title: "_strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l" ms.date: "4/2/2020" api_name: ["_mbsnicoll_l", "_mbsnicoll", "_wcsnicoll_l", "_strnicoll", "_strnicoll_l", "_wcsnicoll", "_o__mbsnicoll", "_o__mbsnicoll_l", "_o__strnicoll", "_o__strnicoll_l", "_o__wcsnicoll", "_o__wcsnicoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcshicoll_l", "_ftcsncicoll", "strnicoll_l", "_wcsnicoll", "mbsnicoll_l", "_strnicoll", "mbsnicoll", "_ftcsnicoll", "wcsnicoll", "_tcsnicoll", "_mbsnicoll", "strinicoll", "_tcsncicoll"] +f1_keywords: ["STRING/_strnicoll", "MBSTRING/_mbsnicoll", "CORECRT_WSTRING/_wcsnicoll", "TCHAR/_tcsnicoll", "TCHAR/_tcsncicoll", "TCHAR/_ftcsncicoll", "TCHAR/_ftcsnicoll", "STRING/_strnicoll_l", "MBSTRING/_mbsnicoll_l", "CORECRT_WSTRING/_wcsnicoll_l", "TCHAR/_tcsnicoll_l", "_strnicoll", "_mbsnicoll", "_wcsnicoll", "_tcsnicoll", "_tcsncicoll", "_ftcsncicoll", "_ftcsnicoll", "_strnicoll_l", "_mbsnicoll_l", "_wcsnicoll_l", "_tcsnicoll_l", "strnicoll", "mbsnicoll", "wcsnicoll", "tcsnicoll", "tcsncicoll", "ftcsncicoll", "ftcsnicoll", "strnicoll_l", "mbsnicoll_l", "wcsnicoll_l", "tcsnicoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "ftcsncicoll function", "mbsnicoll_l function", "_ftcsnicoll function", "mbsnicoll function", "_tcsnicoll function", "_wcsnicoll_l function", "_mbsnicoll function", "tcsncicoll function", "strnicoll function", "_ftcsncicoll function", "wcsnicoll_l function", "_mbsnicoll_l function", "_tcsncicoll function", "strnicoll_l function", "wcsnicoll function", "_strnicoll_l function", "_wcsnicoll function", "ftcsnicoll function", "strings [C++], comparing by code page", "tcsnicoll function", "_strnicoll function"] ms.assetid: abf0c569-725b-428d-9ff2-924f430104b4 --- -# _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l +# `_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsnicoll** and **_mbsnicoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnicoll`** and **`_mbsnicoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,63 +57,63 @@ int _mbsnicoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare -*count*
+*`count`*\ Number of characters to compare -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of the substrings of *string1* and *string2*, as follows. +Each of these functions returns a value indicating the relationship of the substrings of *`string1`* and *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| +| Return value | Relationship of string1 to string2 | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either STRING.H or MBSTRING.H. **_wcsnicoll** can fail if either *string1* or *string2* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **_wcsnicoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsnicoll**, set **errno** to 0 and then check **errno** after calling **_wcsnicoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either STRING.H or MBSTRING.H. **`_wcsnicoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`_wcsnicoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsnicoll`**, set `errno` to 0 and then check `errno` after calling **`_wcsnicoll`**. ## Remarks -Each of these functions performs a case-insensitive comparison of the first *count* characters in *string1* and *string2* according to the code page. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the code page and this difference is of interest for the string comparison. The versions of these functions without the **_l** suffix use the current locale and code page. The versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these functions performs a case-insensitive comparison of the first *`count`* characters in *`string1`* and *`string2`* according to the code page. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the code page and this difference is of interest for the string comparison. The versions of these functions without the `_l` suffix use the current locale and code page. The versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or if count is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or if count is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncicoll**|**_strnicoll**|**_mbsnbicoll**|**_wcsnicoll**| -|**_tcsnicoll**|**_strnicoll**|[_mbsnbicoll](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)|**_wcsnicoll**| -|**_tcsnicoll_l**|**_strnicoll_l**|**_mbsnbicoll_l**|**_wcsnicoll_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncicoll` | **`_strnicoll`** | **`_mbsnbicoll`** | **`_wcsnicoll`** | +| `_tcsnicoll` | **`_strnicoll`** | [`_mbsnbicoll`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md) | **`_wcsnicoll`** | +| `_tcsnicoll_l` | **`_strnicoll_l`** | **`_mbsnbicoll_l`** | **`_wcsnicoll_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnicoll**, **_strnicoll_l**|\| -|**_wcsnicoll**, **_wcsnicoll_l**|\ or \| -|**_mbsnicoll**, **_mbsnicoll_l**|\| +| Routine | Required header | +|---|---| +| **`_strnicoll`**, **`_strnicoll_l`** | \ | +| **`_wcsnicoll`**, **`_wcsnicoll_l`** | \ or \ | +| **`_mbsnicoll`**, **`_mbsnicoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md b/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md index 653c6b743f..b8d17fe1ca 100644 --- a/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md +++ b/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strninc, _wcsninc, _mbsninc, _mbsninc_l" title: "_strninc, _wcsninc, _mbsninc, _mbsninc_l" ms.date: "4/2/2020" api_name: ["_mbsninc", "_mbsninc_l", "_wcsninc", "_strninc", "_o__mbsninc", "_o__mbsninc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strninc", "wcsninc", "mbsninc_l", "_strninc", "_tcsninc", "mbsninc", "_mbsninc_l", "_ftcsninc", "_wcsninc", "_mbsninc"] helpviewer_keywords: ["_mbsninc_l function", "mbsninc function", "_strninc function", "tcsninc function", "wcsninc function", "_mbsninc function", "strninc function", "_wcsninc function", "mbsninc_l function", "_tcsninc function"] ms.assetid: 6caace64-f9e4-48c0-afa8-ea51824ad723 --- -# _strninc, _wcsninc, _mbsninc, _mbsninc_l +# `_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l` Advances a string pointer by **n** characters. > [!IMPORTANT] -> **_mbsninc** and **_mbsninc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsninc`** and **`_mbsninc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,51 +41,51 @@ unsigned char *_mbsninc( ### Parameters -*str*
+*`str`*\ Source string. -*count*
+*`count`*\ Number of characters to increment a string pointer. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a pointer to *str* after *str* has been incremented by *count* characters or **NULL** if the supplied pointer is **NULL**. If *count* is greater than or equal to the number of characters in *str*, the result is undefined. +Each of these routines returns a pointer to *`str`* after *`str`* has been incremented by *`count`* characters or `NULL` if the supplied pointer is `NULL`. If *`count`* is greater than or equal to the number of characters in *`str`*, the result is undefined. ## Remarks -The **_mbsninc** function increments *str* by *count* multibyte characters. **_mbsninc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. +The **`_mbsninc`** function increments *`str`* by *`count`* multibyte characters. **`_mbsninc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsninc**|**_strninc**|**_mbsninc**|**_wcsninc**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsninc` | **`_strninc`** | **`_mbsninc`** | **`_wcsninc`** | -**_strninc** and **_wcsninc** are single-byte-character string and wide-character string versions of **_mbsninc**. **_wcsninc** and **_strninc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strninc`** and **`_wcsninc`** are single-byte-character string and wide-character string versions of **`_mbsninc`**. **`_wcsninc`** and **`_strninc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsninc_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsninc_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsninc**|\| -|**_mbsninc_l**|\| -|**_strninc**|\| -|**_wcsninc**|\| +| Routine | Required header | +|---|---| +| **`_mbsninc`** | \ | +| **`_mbsninc_l`** | \ | +| **`_strninc`** | \ | +| **`_wcsninc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md) diff --git a/docs/c-runtime-library/reference/strnlen-strnlen-s.md b/docs/c-runtime-library/reference/strnlen-strnlen-s.md index d7a1217fa9..d74f2d71dc 100644 --- a/docs/c-runtime-library/reference/strnlen-strnlen-s.md +++ b/docs/c-runtime-library/reference/strnlen-strnlen-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen title: "strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l" ms.date: "4/2/2020" api_name: ["wcsnlen", "strnlen_s", "_mbstrnlen", "_mbsnlen_l", "_mbstrnlen_l", "strnlen", "wcsnlen_s", "_mbsnlen", "_o__mbsnlen", "_o__mbsnlen_l", "_o__mbstrnlen", "_o__mbstrnlen_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcsnlen", "strnlen_s", "_mbsnlen", "_mbsnlen_l", "_tcsnlen", "_tcscnlen", "_mbstrnlen_l", "wcsnlen_s", "_mbstrnlen", "strnlen", "_tcscnlen_l"] @@ -12,10 +12,10 @@ ms.assetid: cc05ce1c-72ea-4ae4-a7e7-4464e56e5f80 --- # `strnlen`, `strnlen_s`, `wcsnlen`, `wcsnlen_s`, `_mbsnlen`, `_mbsnlen_l`, `_mbstrnlen`, `_mbstrnlen_l` -Gets the length of a string by using the current locale or one that has been passed in. These are more secure versions of [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md). +Gets the length of a string by using the current locale or one that has been passed in. These functions are more secure versions of [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md). > [!IMPORTANT] -> **`_mbsnlen`**, **`_mbsnlen_l`**, **`_mbstrnlen`**, and **`_mbstrnlen_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnlen`**, **`_mbsnlen_l`**, **`_mbstrnlen`**, and **`_mbstrnlen_l`** can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -58,18 +58,18 @@ size_t _mbstrnlen_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string. -*`numberOfElements`*
+*`numberOfElements`*\ The size of the string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -These functions return the number of characters in the string, not including the terminating null character. If there is no null terminator within the first *`numberOfElements`* bytes of the string (or wide characters for **`wcsnlen`**), then *`numberOfElements`* is returned to indicate the error condition; null-terminated strings have lengths that are strictly less than *`numberOfElements`*. +These functions return the number of characters in the string, not including the terminating null character. If there's no null terminator within the first *`numberOfElements`* bytes of the string (or wide characters for **`wcsnlen`**), then *`numberOfElements`* is returned to indicate the error condition; null-terminated strings have lengths that are strictly less than *`numberOfElements`*. **`_mbstrnlen`** and **`_mbstrnlen_l`** return -1 if the string contains an invalid multibyte character. @@ -80,36 +80,36 @@ These functions return the number of characters in the string, not including the Each of these functions returns the number of characters in *`str`*, not including the terminating null character. However, **`strnlen`** and **`strnlen_s`** interpret the string as a single-byte character string and therefore, the return value is always equal to the number of bytes, even if the string contains multibyte characters. **`wcsnlen`** and **`wcsnlen_s`** are wide-character versions of **`strnlen`** and **`strnlen_s`** respectively; the arguments for **`wcsnlen`** and **`wcsnlen_s`** are wide-character strings and the count of characters are in wide-character units. Otherwise, **`wcsnlen`** and **`strnlen`** behave identically, as do **`strnlen_s`** and **`wcsnlen_s`**. -**`strnlen`**, **`wcsnlen`**, and **`_mbsnlen`** do not validate their parameters. If *`str`* is **`NULL`**, an access violation occurs. +**`strnlen`**, **`wcsnlen`**, and **`_mbsnlen`** don't validate their parameters. If *`str`* is `NULL`, an access violation occurs. -**`strnlen_s`** and **`wcsnlen_s`** validate their parameters. If *`str`* is **`NULL`**, the functions return 0. +**`strnlen_s`** and **`wcsnlen_s`** validate their parameters. If *`str`* is `NULL`, the functions return 0. -**`_mbstrnlen`** also validates its parameters. If *`str`* is **`NULL`**, or if *`numberOfElements`* is greater than **`INT_MAX`**, **`_mbstrnlen`** generates an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbstrnlen`** sets **`errno`** to **`EINVAL`** and returns -1. +**`_mbstrnlen`** also validates its parameters. If *`str`* is `NULL`, or if *`numberOfElements`* is greater than `INT_MAX`, **`_mbstrnlen`** generates an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbstrnlen`** sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsnlen`**|**`strnlen`**|**`strnlen`**|**`wcsnlen`**| -|**`_tcscnlen`**|**`strnlen`**|**`_mbsnlen`**|**`wcsnlen`**| -|**`_tcscnlen_l`**|**`strnlen`**|**`_mbsnlen_l`**|**`wcsnlen`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnlen` | **`strnlen`** | **`strnlen`** | **`wcsnlen`** | +| `_tcscnlen` | **`strnlen`** | **`_mbsnlen`** | **`wcsnlen`** | +| `_tcscnlen_l` | **`strnlen`** | **`_mbsnlen_l`** | **`wcsnlen`** | -**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it does not test for multibyte-character validity. **`_mbstrnlen`** tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to **`_mbstrnlen`** contains an invalid multibyte character, **`errno`** is set to **`EILSEQ`**. +**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it doesn't test for multibyte-character validity. **`_mbstrnlen`** tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to **`_mbstrnlen`** contains an invalid multibyte character, `errno` is set to `EILSEQ`. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior and the versions that have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior and the versions that have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strnlen`**, **`strnlen_s`**|``| -|**`wcsnlen`**, **`wcsnlen_s`**|`` or ``| -|**`_mbsnlen`**, **`_mbsnlen_l`**|``| -|**`_mbstrnlen`**, **`_mbstrnlen_l`**|``| +| Routine | Required header | +|---|---| +| **`strnlen`**, **`strnlen_s`** | `` | +| **`wcsnlen`**, **`wcsnlen_s`** | `` or `` | +| **`_mbsnlen`**, **`_mbsnlen_l`** | `` | +| **`_mbstrnlen`**, **`_mbstrnlen_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -151,14 +151,14 @@ Length: 100 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md b/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md index 56de094843..e7d55e8de2 100644 --- a/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md +++ b/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md @@ -1,21 +1,22 @@ --- description: "Learn more about: _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l" -title: "_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l" +title: "_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l, _tcsnset_s, _tcsncset_s, _tcsncset_s_l" ms.date: "4/2/2020" -api_name: ["_mbsnset_s_l", "_strnset_s", "_mbsnset_s", "_strnset_s_l", "_wcsnset_s_l", "_wcsnset_s", "_o__mbsnset_s", "_o__mbsnset_s_l", "_o__strnset_s", "_o__wcsnset_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_mbsnset_s_l", "_strnset_s", "_mbsnset_s", "_strnset_s_l", "_wcsnset_s_l", "_wcsnset_s", "_o__mbsnset_s", "_o__mbsnset_s_l", "_o__strnset_s", "_o__wcsnset_s", "_tcsncset_s", "_tcsncset_s_l", "_tcsnset_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbsnset_s_l", "wcsnset_s", "_tcsnset_s_l", "_wcsnset_s", "_mbsnset_s", "_wcsnset_s_l", "_strnset_s_l", "strnset_s_l", "_tcsnset_s", "_strnset_s", "strnset_s", "mbsnset_s_l", "mbsnset_s", "wcsnset_s_l"] -helpviewer_keywords: ["tcsnset_s function", "mbsnset_s_l function", "initializing characters", "wcsnset_s function", "mbsnset_s function", "_tcsnset_s_l function", "_strnset_s_l function", "_mbsnset_s function", "strnset_s_l function", "_tcsnset_s function", "_strnset_s function", "tcsnset_s_l function", "_mbsnset_s_l function", "strnset_s function", "_wcsnset_s function"] -ms.assetid: 9cf1b321-b5cb-4469-b285-4c07cfbd8813 +f1_keywords: ["_mbsnset_s_l", "wcsnset_s", "_tcsnset_s", "_tcsnset_s_l", "_wcsnset_s", "_mbsnset_s", "_wcsnset_s_l", "_strnset_s_l", "strnset_s_l", "_strnset_s", "strnset_s", "mbsnset_s_l", "mbsnset_s", "wcsnset_s_l", "_tcsncset_s", "_tcsncset_s_l"] +helpviewer_keywords: ["tcsnset_s function", "mbsnset_s_l function", "initializing characters", "wcsnset_s function", "mbsnset_s function", "_tcsnset_s function", "_tcsnset_s_l function", "_strnset_s_l function", "_mbsnset_s function", "strnset_s_l function", "_strnset_s function", "tcsnset_s_l function", "_mbsnset_s_l function", "strnset_s function", "_wcsnset_s function", "_tcsncset_s function", "_tcsncset_s_l function"] --- -# _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l +# `_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`, `_tcsnset_s`, `_tcsncset_s`, `_tcsncset_s_l` -Initializes characters of a string to a given character. These versions of [_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Initializes characters of a string to a given character. These versions of [`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsnset_s** and **_mbsnset_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnset_s`** and **`_mbsnset_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). + +For `_tcsnset_s`, `_tcsnset_s_l`, `_tcsncset_s`, and `_tcsncset_s_l` see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -63,57 +64,61 @@ errno_t _mbsnset_s_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*numberOfElements*
-The size of the *str* buffer. +*`numberOfElements`*\ +The size of the *`str`* buffer. -*c*
+*`c`*\ Character setting. -*count*
+*`count`*\ Number of characters to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful, otherwise an error code. -These functions validate their arguments. If *str* is not a valid null-terminated string or the size argument is less than or equal to 0, then the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return an error code and set **errno** to that error code. The default error code is **EINVAL** if a more specific value does not apply. +These functions validate their arguments. If *`str`* isn't a valid null-terminated string or the size argument is less than or equal to 0, then the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return an error code and set `errno` to that error code. The default error code is `EINVAL` if a more specific value doesn't apply. ## Remarks -These functions set, at most, the first *count* characters of *str* to *c*. If *count* is greater than the size of *str*, the size of *str* is used instead of *count*. An error occurs if *count* is greater than *numberOfElements* and both those parameters are greater than the size of *str*. +These functions set, at most, the first *`count`* characters of *`str`* to *`c`*. If *`count`* is greater than the size of *`str`*, the size of *`str`* is used instead of *`count`*. An error occurs if *`count`* is greater than *`numberOfElements`* and both those parameters are greater than the size of *`str`*. + +**`_wcsnset_s`** and **`_mbsnset_s`** are wide-character and multibyte-character versions of **`_strnset_s`**. The string argument of **`_wcsnset_s`** is a wide-character string; that of **`_mbsnset_s`** is a multibyte-character string. These three functions behave identically otherwise. -**_wcsnset_s** and **_mbsnset_s** are wide-character and multibyte-character versions of **_strnset_s**. The string argument of **_wcsnset_s** is a wide-character string; that of **_mbsnset_s** is amultibyte-character string. These three functions behave identically otherwise. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The debug library versions of these functions first fill the buffer with `0xFE`. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset_s**|**_strnset_s**|**_mbsnbset_s**|**_wcsnset_s**| -|**_tcsnset_s_l**|**_strnset_s_l**|**_mbsnbset_s_l**|**_wcsnset_s_l**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset_s` | `_strnset_s` | `_mbsnbset_s` | `_wcsnset_s` | +| `_tcsnset_s_l` | `_strnset_s_l` | `_mbsnbset_s_l` | `_wcsnset_s_l` | +| `_tcsncset_s` | `_strnset_s` | `_mbsnset_s` | `_wcsnset_s` | +| `_tcsncset_s_l` | `_strnset_s_l` | `_mbsnset_s_l` | `_wcsnset_s_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnset_s**|\| -|**_strnset_s_l**|\| -|**_wcsnset_s**|\ or \| -|**_wcsnset_s_l**|\| -|**_mbsnset_s**, **_mbsnset_s_l**|\| +| Routine | Required header | +|---|---| +| **`_strnset_s`** | `` | +| **`_strnset_s_l`** | `` | +| **`_wcsnset_s`** | `` or `` | +| **`_wcsnset_s_l`** | `` | +| **`_mbsnset_s`**, **`_mbsnset_s_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -139,10 +144,10 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md b/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md index 7f22dc0b85..7b6266e535 100644 --- a/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md +++ b/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbs title: "_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l" ms.date: "4/2/2020" api_name: ["_mbsnset", "_strnset", "_mbsnset_l", "_wcsnset_l", "_wcsnset", "_strnset_l", "_o__mbsnset", "_o__mbsnset_l", "_o__wcsnset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsncset_l", "mbsnset_l", "_tcsnset_l", "_fstrnset", "_wcsnset_l", "_ftcsnset", "wcsnset_l", "_mbsnset_l", "_strnset", "_tcsnset", "_strnset_l", "mbsnset", "strnset_l", "_mbsnset", "_wcsnset", "_tcsncset"] helpviewer_keywords: ["_wcsnset function", "strnset_l function", "tcsnset function", "tcsncset function", "characters [C++], initializing to formats", "mbsnset function", "_tcsnset_l function", "_mbsnset function", "_strnset function", "_tcsncset_l function", "mbsnset_l function", "_tcsnset function", "initializing characters", "_tcsncset function", "ftcsnset function", "wcsnset_l function", "_ftcsnset function", "_wcsnset_l function", "_fstrnset function", "_mbsnset_l function", "_strnset_l function", "fstrnset function", "strings [C++], initializing", "tcsnset_l function"] ms.assetid: 3f306489-5763-48e5-b939-aefee7c94ef5 --- -# _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l +# `_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l` -Initializes characters of a string to a given character. More secure versions of these functions exist; see [_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md). +Initializes characters of a string to a given character. More secure versions of these functions exist; see [`_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md). > [!IMPORTANT] -> **_mbsnset** and **_mbsnset_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnset`** and **`_mbsnset_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,52 +57,52 @@ unsigned char *_mbsnset_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*c*
+*`c`*\ Character setting. -*count*
+*`count`*\ Number of characters to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. ## Remarks -The **_strnset** function sets, at most, the first *count* characters of *str* to *c* (converted to **`char`**). If *count* is greater than the length of *str*, the length of *str* is used instead of *count*. +The **`_strnset`** function sets, at most, the first *`count`* characters of *`str`* to *`c`* (converted to **`char`**). If *`count`* is greater than the length of *`str`*, the length of *`str`* is used instead of *`count`*. -**_wcsnset** and **_mbsnset** are wide-character and multibyte-character versions of **_strnset**. The string arguments and return value of **_wcsnset** are wide-character strings; those of **_mbsnset** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsnset`** and **`_mbsnset`** are wide-character and multibyte-character versions of **`_strnset`**. The string arguments and return value of **`_wcsnset`** are wide-character strings. The string arguments and return value of **`_mbsnset`** are multibyte-character strings. These three functions behave identically otherwise. -**_mbsnset** validates its parameters; if *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, **_mbsnset** returns **NULL** and sets **errno** to **EINVAL**. **_strnset** and **_wcsnset** do not validate their parameters. +**`_mbsnset`** validates its parameters; if *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbsnset`** returns `NULL` and sets `errno` to `EINVAL`. **`_strnset`** and **`_wcsnset`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset**|**_strnset**|**_mbsnbset**|**_wcsnset**| -|**_tcsnset_l**|**_strnset_l**|**_mbsnbset_l**|**_wcsnset_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset` | **`_strnset`** | **`_mbsnbset`** | **`_wcsnset`** | +| `_tcsnset_l` | **`_strnset_l`** | **`_mbsnbset_l`** | **`_wcsnset_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnset**|\| -|**_strnset_l**|\| -|**_wcsnset**|\ or \| -|**_wcsnset_l**|\| -|**_mbsnset**, **_mbsnset_l**|\| +| Routine | Required header | +|---|---| +| **`_strnset`** | \ | +| **`_strnset_l`** | \ | +| **`_wcsnset`** | \ or \ | +| **`_wcsnset_l`** | \ | +| **`_mbsnset`**, **`_mbsnset_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -130,10 +130,10 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strnset-wcsnset.md b/docs/c-runtime-library/reference/strnset-wcsnset.md index e7b45b8119..4447d81397 100644 --- a/docs/c-runtime-library/reference/strnset-wcsnset.md +++ b/docs/c-runtime-library/reference/strnset-wcsnset.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsnset", "strnset"] helpviewer_keywords: ["strnset function", "wcsnset function"] ms.assetid: e7868ac9-dc34-4606-bd3c-0fb2e7c51631 --- -# strnset, wcsnset +# `strnset`, `wcsnset` -The Microsoft-specific function names `strnset` and `wcsnset` are deprecated aliases for the [_strnset and _wcsnset](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strnset` and `wcsnset` are deprecated aliases for the [`_strnset` and `_wcsnset`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strnset and _wcsnset](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) or the security-enhanced [_strnset_s and _wcsnset_s](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strnset` and `_wcsnset`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) or the security-enhanced [`_strnset_s` and `_wcsnset_s`](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md b/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md index a80c54a7ac..cf9a197477 100644 --- a/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md +++ b/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l" title: "strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l" ms.date: "4/2/2020" api_name: ["_mbspbrk", "wcspbrk", "_mbspbrk_l", "strpbrk", "_o__mbspbrk", "_o__mbspbrk_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrpbrk", "_mbspbrk", "strpbrk", "_tcspbrk", "_ftcspbrk", "wcspbrk"] helpviewer_keywords: ["fstrpbrk function", "_ftcspbrk function", "_mbspbrk_l function", "strpbrk function", "_fstrpbrk function", "mbspbrk function", "characters [C++], scanning strings", "_tcspbrk function", "wcspbrk function", "ftcspbrk function", "character sets [C++], scanning strings for characters", "strings [C++], scanning", "tcspbrk function", "_mbspbrk function", "mbspbrk_l function"] ms.assetid: 80b504f7-a167-4dde-97ad-4ae3000dc810 --- -# strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l +# `strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l` Scans strings for characters in specified character sets. > [!IMPORTANT] -> `_mbspbrk` and `_mbspbrk_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbspbrk`** and **`_mbspbrk_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,51 +75,51 @@ const unsigned char *_mbspbrk_l( ### Parameters -*str*
+*`str`*\ Null-terminated, searched string. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the first occurrence of any character from *strCharSet* in *str*, or a NULL pointer if the two string arguments have no characters in common. +Returns a pointer to the first occurrence of any character from *`strCharSet`* in *`str`*, or a `NULL` pointer if the two string arguments have no characters in common. ## Remarks -The `strpbrk` function returns a pointer to the first occurrence of a character in *str* that belongs to the set of characters in *strCharSet*. The search does not include the terminating null character. +The **`strpbrk`** function returns a pointer to the first occurrence of a character in *`str`* that belongs to the set of characters in *`strCharSet`*. The search doesn't include the terminating null character. -`wcspbrk` and `_mbspbrk` are wide-character and multibyte-character versions of `strpbrk`. The arguments and return value of `wcspbrk` are wide-character strings; those of `_mbspbrk` are multibyte-character strings. +**`wcspbrk`** and **`_mbspbrk`** are wide-character and multibyte-character versions of **`strpbrk`**. The arguments and return value of **`wcspbrk`** are wide-character strings. The arguments and return value of **`_mbspbrk`** are multibyte-character strings. -`_mbspbrk` validates its parameters. If *str* or *strCharSet* is NULL, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `_mbspbrk` returns NULL and sets `errno` to EINVAL. `strpbrk` and `wcspbrk` do not validate their parameters. These three functions behave identically otherwise. +**`_mbspbrk`** validates its parameters. If *`str`* or *`strCharSet`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbspbrk`** returns `NULL` and sets `errno` to `EINVAL`. **`strpbrk`** and **`wcspbrk`** don't validate their parameters. These three functions behave identically otherwise. -`_mbspbrk` is similar to `_mbscspn` except that `_mbspbrk` returns a pointer rather than a value of type [size_t](../../c-runtime-library/standard-types.md). +**`_mbspbrk`** is similar to `_mbscspn` except that **`_mbspbrk`** returns a pointer rather than a value of type [`size_t`](../standard-types.md). -In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro _CRT_CONST_CORRECT_OVERLOADS is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol _CONST_RETURN. +In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -The output value is affected by the setting of the LC_CTYPE category setting of the locale; for more information, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the version with the **_l** suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the version with the `_l` suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcspbrk`|`strpbrk`|`_mbspbrk`|`wcspbrk`| -|**n/a**|**n/a**|`_mbspbrk_l`|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcspbrk` | **`strpbrk`** | **`_mbspbrk`** | **`wcspbrk`** | +| **n/a** | **n/a** | **`_mbspbrk_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strpbrk`|\| -|`wcspbrk`|\ or \| -|`_mbspbrk`, `_mbspbrk_l`|\| +| Routine | Required header | +|---|---| +| **`strpbrk`** | \ | +| **`wcspbrk`** | \ or \ | +| **`_mbspbrk`**, **`_mbspbrk_l`** | \ | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -157,9 +157,9 @@ int main( void ) ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcspn, wcscspn, _mbscspn, _mbscspn_l](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[strchr, wcschr, _mbschr, _mbschr_l](strchr-wcschr-mbschr-mbschr-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](strchr-wcschr-mbschr-mbschr-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md b/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md index c1c16e62f5..9c8d760c68 100644 --- a/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md +++ b/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" title: "strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" +description: "Learn more about: strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" ms.date: "4/2/2020" api_name: ["strrchr", "wcsrchr", "_mbsrchr", "_mbsrchr_l", "_o__mbsrchr", "_o__mbsrchr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsrchr", "_ftcsrchr", "strrchr", "wcsrchr", "_mbsrchr"] @@ -14,7 +14,7 @@ helpviewer_keywords: ["_mbsrchr function", "tcsrchr function", "mbsrchr_l functi Scans a string for the last occurrence of a character. > [!IMPORTANT] -> `_mbsrchr` and `_mbsrchr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsrchr`** and **`_mbsrchr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -83,52 +83,52 @@ Character to be located. *`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the last occurrence of *`c`* in *`str`*, or `NULL` if *`c`* is not found. +Returns a pointer to the last occurrence of *`c`* in *`str`*, or `NULL` if *`c`* isn't found. ## Remarks -The `strrchr` function finds the last occurrence of *`c`* (converted to **`char`**) in *`str`*. The search includes the terminating `NULL` character. +The **`strrchr`** function finds the last occurrence of *`c`* (converted to **`char`**) in *`str`*. The search includes the terminating `NULL` character. -`wcsrchr` and `_mbsrchr` are wide-character and multibyte-character versions of `strrchr`. The arguments and return value of `wcsrchr` are wide-character strings; those of `_mbsrchr` are multibyte-character strings. +**`wcsrchr`** and **`_mbsrchr`** are wide-character and multibyte-character versions of **`strrchr`**. The arguments and return value of **`wcsrchr`** are wide-character strings. The arguments and return value of **`_mbsrchr`** are multibyte-character strings. In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -`_mbsrchr` validates its parameters. If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and `_mbsrchr` returns 0. `strrchr` and `wcsrchr` do not validate their parameters. These three functions behave identically otherwise. +**`_mbsrchr`** validates its parameters. If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and **`_mbsrchr`** returns 0. **`strrchr`** and **`wcsrchr`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcsrchr`|`strrchr`|`_mbsrchr`|`wcsrchr`| -|**n/a**|**n/a**|`_mbsrchr_l`|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsrchr` | **`strrchr`** | **`_mbsrchr`** | **`wcsrchr`** | +| **n/a** | **n/a** | **`_mbsrchr_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strrchr`|``| -|`wcsrchr`|`` or ``| -|`_mbsrchr`, `_mbsrchr_l`|``| +| Routine | Required header | +|---|---| +| **`strrchr`** | `` | +| **`wcsrchr`** | `` or `` | +| **`_mbsrchr`**, **`_mbsrchr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example -For an example of using `strrchr`, see [`strchr`](strchr-wcschr-mbschr-mbschr-l.md). +For an example of using **`strrchr`**, see [`strchr`](strchr-wcschr-mbschr-mbschr-l.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ [`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](strchr-wcschr-mbschr-mbschr-l.md)\ [`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ [`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ [`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ -[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md b/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md index b37c90bb3b..b2a3b77d3b 100644 --- a/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md +++ b/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strrev, _wcsrev, _mbsrev, _mbsrev_l" title: "_strrev, _wcsrev, _mbsrev, _mbsrev_l" ms.date: "4/2/2020" api_name: ["_wcsrev", "_mbsrev", "_strrev", "_mbsrev_l", "_o__mbsrev", "_o__mbsrev_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strrev", "_ftcsrev", "_tcsrev", "mbsrev", "mbsrev_l", "_wcsrev_fstrrev", "_mbsrev"] helpviewer_keywords: ["_mbsrev_l function", "characters [C++], switching", "_mbsrev function", "strrev function", "_ftcsrev function", "strings [C++], reversing", "wcsrev function", "_strrev function", "mbsrev_l function", "reversing characters in strings", "ftcsrev function", "characters [C++], reversing order", "_wcsrev function", "mbsrev function", "tcsrev function", "_tcsrev function"] ms.assetid: 87863e89-4fa0-421c-af48-25d8516fe72f --- -# _strrev, _wcsrev, _mbsrev, _mbsrev_l +# `_strrev`, `_wcsrev`, `_mbsrev`, `_mbsrev_l` Reverses the characters of a string. > [!IMPORTANT] -> **_mbsrev** and **_mbsrev_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsrev`** and **`_mbsrev_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -37,45 +37,45 @@ unsigned char *_mbsrev_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to reverse. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. No return value is reserved to indicate an error. ## Remarks -The **_strrev** function reverses the order of the characters in *str*. The terminating null character remains in place. **_wcsrev** and **_mbsrev** are wide-character and multibyte-character versions of **_strrev**. The arguments and return value of **_wcsrev** are wide-character strings; those of **_mbsrev** are multibyte-character strings. For **_mbsrev**, the order of bytes in each multibyte character in *str* is not changed. These three functions behave identically otherwise. +The **`_strrev`** function reverses the order of the characters in *`str`*. The terminating null character remains in place. **`_wcsrev`** and **`_mbsrev`** are wide-character and multibyte-character versions of **`_strrev`**. The arguments and return value of **`_wcsrev`** are wide-character strings. The arguments and return value of **`_mbsrev`** are multibyte-character strings. For **`_mbsrev`**, the order of bytes in each multibyte character in *`str`* isn't changed. These three functions behave identically otherwise. -**_mbsrev** validates its parameters. If either *string1* or *string2* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_mbsrev** returns **NULL** and sets **errno** to **EINVAL**. **_strrev** and **_wcsrev** do not validate their parameters. +**`_mbsrev`** validates its parameters. If either *`string1`* or *`string2`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsrev`** returns `NULL` and sets `errno` to `EINVAL`. **`_strrev`** and **`_wcsrev`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **_l** suffix use the current locale and the ones that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale and the ones that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsrev**|**_strrev**|**_mbsrev**|**_wcsrev**| -|**n/a**|**n/a**|**_mbsrev_l**|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsrev` | **`_strrev`** | **`_mbsrev`** | **`_wcsrev`** | +| **n/a** | **n/a** | **`_mbsrev_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strrev**|\| -|**_wcsrev**|\ or \| -|**_mbsrev**, **_mbsrev_l**|\| +| Routine | Required header | +|---|---| +| **`_strrev`** | \ | +| **`_wcsrev`** | \ or \ | +| **`_mbsrev`**, **`_mbsrev_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -109,8 +109,8 @@ The string "Able was I ere I saw Elba" is a palindrome ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strrev-wcsrev.md b/docs/c-runtime-library/reference/strrev-wcsrev.md index 5a0d2c1812..a0dbe0251c 100644 --- a/docs/c-runtime-library/reference/strrev-wcsrev.md +++ b/docs/c-runtime-library/reference/strrev-wcsrev.md @@ -10,8 +10,8 @@ f1_keywords: ["strrev", "wcsrev"] helpviewer_keywords: ["strrev function", "wcsrev function"] ms.assetid: 89e05854-a9ce-4fb7-993d-a9831cd7edf2 --- -# strrev, wcsrev +# `strrev`, `wcsrev` -The Microsoft-specific function names `strrev` and `wcsrev` are deprecated aliases for the [_strrev and _wcsrev](strrev-wcsrev-mbsrev-mbsrev-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strrev` and `wcsrev` are deprecated aliases for the [`_strrev` and `_wcsrev`](strrev-wcsrev-mbsrev-mbsrev-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strrev and _wcsrev](strrev-wcsrev-mbsrev-mbsrev-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strrev` and `_wcsrev`](strrev-wcsrev-mbsrev-mbsrev-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md b/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md index 363596b6ad..e5081eaae0 100644 --- a/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md +++ b/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, title: "_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l" ms.date: "4/2/2020" api_name: ["_wcsset_s", "_wcsset_s_l", "_strset_s", "_mbsset_s_l", "_strset_s_l", "_mbsset_s", "_o__mbsset_s", "_o__mbsset_s_l", "_o__strset_s", "_o__wcsset_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wcsset_s_l", "strset_s", "_mbsset_s", "mbsset_s", "_strset_s", "_mbsset_s_l", "strset_s_l", "_wcsset_s", "mbsset_s_l", "wcsset_s_l", "wcsset_s", "_strset_s_l", "_tcsset_s_l", "_tcsset_s"] helpviewer_keywords: ["mbsset_s_l function", "wcsset_s function", "_mbsset_s function", "tcsset_s function", "strset_s_l function", "characters [C++], setting", "_wcsset_s_l function", "_strset_s function", "strset_s function", "wcsset_s_l function", "strings [C++], setting characters", "_strset_s_l function", "_mbsset_s_l function", "_wcsset_s function", "tcsset_s_l function", "_tcsset_s_l function", "_tcsset_s function", "mbsset_s function"] ms.assetid: dceb2909-6b41-4792-acb7-888e45bb8b35 --- -# _strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l +# `_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l` -Sets characters of a string to a character. These versions of [_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Sets characters of a string to a character. These versions of [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsset_s** and **_mbsset_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsset_s`** and **`_mbsset_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,52 +57,52 @@ errno_t _mbsset_s_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to be set. -*numberOfElements*
-The size of the *str* buffer. +*`numberOfElements`*\ +The size of the *`str`* buffer. -*c*
+*`c`*\ Character setting. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful, otherwise an error code. -These functions validate their arguments. If *str* is a null pointer, or the *numberOfElements* argument is less than or equal to 0, or the block passed in is not null-terminated, then the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their arguments. If *`str`* is a null pointer, or the *`numberOfElements`* argument is less than or equal to 0, or the block passed in isn't null-terminated, then the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. ## Remarks -The **_strset_s** function sets all the characters of *str* to *c* (converted to **`char`**), except the terminating null character. **_wcsset_s** and **_mbsset_s** are wide-character and multibyte-character versions of **_strset_s**. The data types of the arguments and return values vary accordingly. These functions behave identically otherwise. +The **`_strset_s`** function sets all the characters of *`str`* to *`c`* (converted to **`char`**), except the terminating null character. **`_wcsset_s`** and **`_mbsset_s`** are wide-character and multibyte-character versions of **`_strset_s`**. The data types of the arguments and return values vary accordingly. These functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsset_s**|**_strset_s**|**_mbsset_s**|**_wcsset_s**| -|**_tcsset_s_l**|**_strset_s_l**|**_mbsset_s_l**|**_wcsset_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsset_s` | **`_strset_s`** | **`_mbsset_s`** | **`_wcsset_s`** | +| `_tcsset_s_l` | **`_strset_s_l`** | **`_mbsset_s_l`** | **`_wcsset_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strset_s**|\| -|**_strset_s_l**|\| -|**_wcsset_s**|\ or \| -|**_wcsset_s_l**|\| -|**_mbsset_s**, **_mbsset_s_l**|\| +| Routine | Required header | +|---|---| +| **`_strset_s`** | \ | +| **`_strset_s_l`** | \ | +| **`_wcsset_s`** | \ or \ | +| **`_wcsset_s_l`** | \ | +| **`_mbsset_s`**, **`_mbsset_s_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -128,12 +128,12 @@ After: ******************************* ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[memset, wmemset](memset-wmemset.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) diff --git a/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md b/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md index e8265942b8..9b1e2d0055 100644 --- a/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md +++ b/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strset, _strset_l, _wcsset, _wcsset_l, _mbsset, title: "_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l" ms.date: "4/2/2020" api_name: ["_wcsset", "_mbsset", "_strset_l", "_strset", "_wcsset_l", "_mbsset_l", "_o__mbsset", "_o__mbsset_l", "_o__wcsset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsset", "_strset_l", "_mbsset", "_strset", "mbsset_l", "strset_l", "_wcsset", "_ftcsset", "wcsset_l", "_tcsset_l", "_mbsset_l", "_wcsset_l", "_fstrset", "_tcsset"] helpviewer_keywords: ["_wcsset_l function", "_tcsset function", "wcsset_l function", "_ftcsset function", "characters [C++], setting", "_strset function", "ftcsset function", "strings [C++], setting characters", "mbsset function", "tcsset_l function", "_fstrset function", "mbsset_l function", "strset_l function", "_wcsset function", "_mbsset function", "_mbsset_l function", "tcsset function", "_strset_l function", "fstrset function", "_tcsset_l function"] ms.assetid: c42ded42-2ed9-4f06-a0a9-247ba305473a --- -# _strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l +# `_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l` -Sets characters of a string to a character. More secure versions of these functions are available; see [_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md). +Sets characters of a string to a character. More secure versions of these functions are available; see [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md). > [!IMPORTANT] -> **_mbsset** and **_mbsset_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsset`** and **`_mbsset_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,50 +51,50 @@ unsigned char *_mbsset_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to be set. -*c*
+*`c`*\ Character setting. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. ## Remarks -The **_strset** function sets all characters (except the terminating null character) of *str* to *c*, converted to **`char`**. **_wcsset** and **_mbsset_l** are wide-character and multibyte-character versions of **_strset**, and the data types of the arguments and return values vary accordingly. These functions behave identically otherwise. +The **`_strset`** function sets all characters (except the terminating null character) of *`str`* to *`c`*, converted to **`char`**. **`_wcsset`** and **`_mbsset_l`** are wide-character and multibyte-character versions of **`_strset`**, and the data types of the arguments and return values vary accordingly. These functions behave identically otherwise. -**_mbsset** validates its parameters. If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_mbsset** returns **NULL** and sets **errno** to **EINVAL**. **_strset** and **_wcsset** do not validate their parameters. +**`_mbsset`** validates its parameters. If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsset`** returns `NULL` and sets `errno` to `EINVAL`. **`_strset`** and **`_wcsset`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **_l** suffix use the current locale and the ones that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale and the ones that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsset**|**_strset**|**_mbsset**|**_wcsset**| -|**_tcsset_l**|**_strset_l**|**_mbsset_l**|**_wcsset_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsset` | **`_strset`** | **`_mbsset`** | **`_wcsset`** | +| `_tcsset_l` | **`_strset_l`** | **`_mbsset_l`** | **`_wcsset_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strset**|\| -|**_strset_l**|\| -|**_wcsset**|\ or \| -|**_wcsset_l**|\| -|**_mbsset**, **_mbsset_l**|\| +| Routine | Required header | +|---|---| +| **`_strset`** | \ | +| **`_strset_l`** | \ | +| **`_wcsset`** | \ or \ | +| **`_wcsset_l`** | \ | +| **`_mbsset`**, **`_mbsset_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,12 +122,12 @@ After: ******************************* ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[memset, wmemset](memset-wmemset.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) diff --git a/docs/c-runtime-library/reference/strset-wcsset.md b/docs/c-runtime-library/reference/strset-wcsset.md index ce34622ab8..3d54b5a7cc 100644 --- a/docs/c-runtime-library/reference/strset-wcsset.md +++ b/docs/c-runtime-library/reference/strset-wcsset.md @@ -10,6 +10,6 @@ f1_keywords: ["strset", "wcsset"] helpviewer_keywords: ["wcsset function", "strset function"] ms.assetid: 20e132d8-4b6c-4341-b1eb-8e19b46047e2 --- -# strset, wcsset +# `strset`, `wcsset` -These functions are deprecated. Use the ISO C++ conformant [_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) or security-enhanced [_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) instead. +These functions are deprecated. Use the ISO C++ conformant [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) or security-enhanced [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) instead. diff --git a/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md b/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md index cbce390bad..676ade2b01 100644 --- a/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md +++ b/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strspn, wcsspn, _mbsspn, _mbsspn_l" title: "strspn, wcsspn, _mbsspn, _mbsspn_l" ms.date: "4/2/2020" api_name: ["_mbsspn_l", "wcsspn", "strspn", "_mbsspn", "_o__mbsspn", "_o__mbsspn_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsspn", "wcsspn", "_mbsspn", "_tcsspn", "strspn"] helpviewer_keywords: ["wcsspn function", "strings [C++], searching", "mbsspn function", "tcsspn function", "strspn function", "substrings, finding", "_mbsspn_l function", "ftcsspn function", "_mbsspn function", "_ftcsspn function", "mbsspn_l function", "_tcsspn function"] ms.assetid: d077284a-809f-4068-959e-c6d6262677eb --- -# strspn, wcsspn, _mbsspn, _mbsspn_l +# `strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l` -Returns the index of the first character, in a string, that does not belong to a set of characters. +Returns the index of the first character in a string that doesn't belong to a specified set of characters. > [!IMPORTANT] -> **_mbsspn** and **_mbsspn_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsspn`** and **`_mbsspn_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,45 +41,45 @@ size_t _mbsspn_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to search. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns an integer value specifying the length of the substring in *str* that consists entirely of characters in *strCharSet*. If *str* begins with a character not in *strCharSet*, the function returns 0. +Returns an integer value specifying the length of the substring in *`str`* that consists entirely of characters in *`strCharSet`*. If *`str`* begins with a character not in *`strCharSet`*, the function returns 0. ## Remarks -The **strspn** function returns the index of the first character in *str* that does not belong to the set of characters in *strCharSet*. The search does not include terminating null characters. +The **`strspn`** function returns the index of the first character in *`str`* that doesn't belong to the set of characters in *`strCharSet`*. The search doesn't include terminating null characters. -**wcsspn** and **_mbsspn** are wide-character and multibyte-character versions of **strspn**. The arguments of **wcsspn** are wide-character strings; those of **_mbsspn** are multibyte-character strings. **_mbsspn** validates its parameters. If *str* or *strCharSet* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, **_mbspn** sets **errno** to **EINVAL** and returns 0. **strspn** and **wcsspn** do not validate their parameters. These three functions behave identically otherwise. +**`wcsspn`** and **`_mbsspn`** are wide-character and multibyte-character versions of **`strspn`**. The arguments of **`wcsspn`** are wide-character strings. The arguments of **`_mbsspn`** are multibyte-character strings. **`_mbsspn`** validates its parameters. If *`str`* or *`strCharSet`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbspn`** sets `errno` to `EINVAL` and returns 0. **`strspn`** and **`wcsspn`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsspn**|**strspn**|**_mbsspn**|**wcsspn**| -|**n/a**|**n/a**|**_mbsspn_l**|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsspn` | **`strspn`** | **`_mbsspn`** | **`wcsspn`** | +| **n/a** | **n/a** | **`_mbsspn_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strspn**|\| -|**wcsspn**|\ or \| -|**_mbsspn**, **_mbsspn_l**|\| +| Routine | Required header | +|---|---| +| **`strspn`** | \ | +| **`wcsspn`** | \ or \ | +| **`_mbsspn`**, **`_mbsspn_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -110,13 +110,13 @@ The portion of 'cabbage' containing only a, b, or c is 5 bytes long ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l](strspnp-wcsspnp-mbsspnp-mbsspnp-l.md)
-[strcspn, wcscspn, _mbscspn, _mbscspn_l](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l`](strspnp-wcsspnp-mbsspnp-mbsspnp-l.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md b/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md index 7eff7011b6..519b5dcc50 100644 --- a/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md +++ b/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l" title: "_strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l" ms.date: "4/2/2020" api_name: ["_mbsspnp", "_wcsspnp", "_mbsspnp_l", "_strspnp", "_o__mbsspnp", "_o__mbsspnp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsspnp", "_mbsspnp", "strspnp", "_ftcsspnp", "_mbsspnp_l", "wcsspnp", "mbsspnp_l", "_wcsspnp", "_strspnp", "mbsspnp"] helpviewer_keywords: ["_strspnp function", "_wcsspnp function", "_mbsspnp_l function", "strspnp function", "mbsspnp function", "wcsspnp function", "_mbsspnp function", "mbsspnp_l function", "_tcsspnp function", "tcsspnp function"] ms.assetid: 1ce18100-2edd-4c3b-af8b-53f204d80233 --- -# _strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l +# `_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l` -Returns a pointer to the first character in a given string that is not in another given string. +Returns a pointer to the first character in a given string that isn't in another given string. > [!IMPORTANT] -> **_mbsspnp** and **_mbsspnp_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsspnp`** and **`_mbsspnp_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,46 +41,46 @@ unsigned char *_mbsspnp_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to search. -*charset*
+*`charset`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_strspnp**, **_wcsspnp**, and **_mbsspnp** return a pointer to the first character in *str* that does not belong to the set of characters in *charset*. Each of these functions returns **NULL** if *str* consists entirely of characters from *charset*. For each of these routines, no return value is reserved to indicate an error. +**`_strspnp`**, **`_wcsspnp`**, and **`_mbsspnp`** return a pointer to the first character in *`str`* that doesn't belong to the set of characters in *`charset`*. Each of these functions returns `NULL` if *`str`* consists entirely of characters from *`charset`*. For each of these routines, no return value is reserved to indicate an error. ## Remarks -The **_mbsspnp** function returns a pointer to the multibyte character that is the first character in *str* that does not belong to the set of characters in *charset*. **_mbsspnp** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. The search does not include terminating null characters. +The **`_mbsspnp`** function returns a pointer to the multibyte character that is the first character in *`str`* that doesn't belong to the set of characters in *`charset`*. **`_mbsspnp`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. The search doesn't include terminating null characters. -If either *str* or *charset* is a null pointer, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **NULL** and sets **errno** to **EINVAL**. +If either *`str`* or *`charset`* is a null pointer, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsspnp**|**_strspnp**|**_mbsspnp**|**_wcsspnp**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsspnp` | **`_strspnp`** | **`_mbsspnp`** | **`_wcsspnp`** | -**_strspnp** and **_wcsspnp** are single-byte character and wide-character versions of **_mbsspnp**. **_strspnp** and **_wcsspnp** behave identically to **_mbsspnp** otherwise; they are provided only for this mapping and should not be used for any other reason. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strspnp`** and **`_wcsspnp`** are single-byte character and wide-character versions of **`_mbsspnp`**. **`_strspnp`** and **`_wcsspnp`** behave identically to **`_mbsspnp`** otherwise; they're provided only for this mapping and shouldn't be used for any other reason. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsspnp_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsspnp_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsspnp**|\| -|**_strspnp**|\| -|**_wcsspnp**|\| +| Routine | Required header | +|---|---| +| **`_mbsspnp`** | \ | +| **`_strspnp`** | \ | +| **`_wcsspnp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,12 +106,12 @@ abbage ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md b/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md index d25146b66f..d3d44af252 100644 --- a/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md +++ b/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strstr, wcsstr, _mbsstr, _mbsstr_l" title: "strstr, wcsstr, _mbsstr, _mbsstr_l" ms.date: "4/2/2020" api_name: ["_mbsstr", "wcsstr", "_mbsstr_l", "strstr", "_o__mbsstr", "_o__mbsstr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrstr", "_ftcsstr", "strstr", "wcsstr", "_mbsstr", "_tcsstr"] @@ -15,7 +15,7 @@ ms.assetid: 03d70c3f-2473-45cb-a5f8-b35beeb2748a Returns a pointer to the first occurrence of a search string in a string. > [!IMPORTANT] -> `_mbsstr` and `_mbsstr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsstr`** and **`_mbsstr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,48 +75,48 @@ const unsigned char *_mbsstr_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string to search. -*`strSearch`*
+*`strSearch`*\ Null-terminated string to search for. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the first occurrence of *`strSearch`* in *`str`*, or **`NULL`** if *`strSearch`* does not appear in *`str`*. If *`strSearch`* points to a string of zero length, the function returns *`str`*. +Returns a pointer to the first occurrence of *`strSearch`* in *`str`*, or `NULL` if *`strSearch`* doesn't appear in *`str`*. If *`strSearch`* points to a string of zero length, the function returns *`str`*. ## Remarks -The `strstr` function returns a pointer to the first occurrence of *`strSearch`* in *`str`*. The search does not include terminating null characters. `wcsstr` is the wide-character version of `strstr` and `_mbsstr` is the multibyte-character version. The arguments and return value of `wcsstr` are wide-character strings; those of `_mbsstr` are multibyte-character strings. `_mbsstr` validates its parameters. If *`str`* or *`strSearch`* is NULL, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, `_mbsstr` sets `errno` to `EINVAL` and returns 0. `strstr` and `wcsstr` do not validate their parameters. These three functions behave identically otherwise. +The **`strstr`** function returns a pointer to the first occurrence of *`strSearch`* in *`str`*. The search doesn't include terminating null characters. **`wcsstr`** is the wide-character version of **`strstr`** and **`_mbsstr`** is the multibyte-character version. The arguments and return value of **`wcsstr`** are wide-character strings. The arguments and return value of **`_mbsstr`** are multibyte-character strings. **`_mbsstr`** validates its parameters. If *`str`* or *`strSearch`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbsstr`** sets `errno` to `EINVAL` and returns 0. **`strstr`** and **`wcsstr`** don't validate their parameters. These three functions behave identically otherwise. > [!IMPORTANT] -> These functions might incur a threat from a buffer overrun problem. Buffer overrun problems can be used to attack a system because they can allow the execution of arbitrary code, which can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might incur a threat from a buffer overrun problem. Buffer overrun problems can be used to attack a system because they can allow the execution of arbitrary code, which can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload that takes a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -The output value is affected by the locale-category setting of `LC_CTYPE`; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that do not have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that have the **`_l`** suffix are identical except that they instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the locale-category setting of `LC_CTYPE`; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that have the **`_l`** suffix are identical except that they instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcsstr`|`strstr`|`_mbsstr`|`wcsstr`| -|**n/a**|**n/a**|`_mbsstr_l`|**n/a**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsstr` | **`strstr`** | **`_mbsstr`** | **`wcsstr`** | +| **n/a** | **n/a** | **`_mbsstr_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strstr`|``| -|`wcsstr`|`` or ``| -|`_mbsstr`, `_mbsstr_l`|``| +| Routine | Required header | +|---|---| +| **`strstr`** | `` | +| **`wcsstr`** | `` or `` | +| **`_mbsstr`**, **`_mbsstr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -157,12 +157,12 @@ lazy found at position 36 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`basic_string::find`](../../standard-library/basic-string-class.md#find)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`basic_string::find`](../../standard-library/basic-string-class.md#find) diff --git a/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md b/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md index ef15b7288d..c0ad6eb80e 100644 --- a/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md +++ b/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _strtime_s, _wstrtime_s" title: "_strtime_s, _wstrtime_s" ms.date: "4/2/2020" api_name: ["_wstrtime_s", "_strtime_s", "_o__strtime_s", "_o__wstrtime_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wstrtime_s", "strtime_s", "wstrtime_s", "_strtime_s"] helpviewer_keywords: ["wstrtime_s function", "copying time to buffers", "strtime_s function", "_wstrtime_s function", "time, copying", "_strtime_s function"] ms.assetid: 42acf013-c334-485d-b610-84c0af8a46ec --- -# _strtime_s, _wstrtime_s +# `_strtime_s`, `_wstrtime_s` -Copy the current time to a buffer. These are versions of [_strtime, _wstrtime](strtime-wstrtime.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copy the current time to a buffer. These functions are versions of [`_strtime`, `_wstrtime`](strtime-wstrtime.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,59 +37,59 @@ errno_t _wstrtime_s( ### Parameters -*buffer*
+*`buffer`*\ A buffer, at least 10 bytes long, where the time will be written. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer. -## Return Value +## Return value Zero if successful. -If an error condition occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). The return value is an error code if there is a failure. Error codes are defined in ERRNO.H; see the following table for the exact errors generated by this function. For more information on error codes, see [errno Constants](../../c-runtime-library/errno-constants.md). +If an error condition occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see the following table for the exact errors generated by this function. For more information on error codes, see [`errno` constants](../errno-constants.md). -### Error Conditions +### Error conditions -|*buffer*|*numberOfElements*|Return|Contents of *buffer*| -|--------------|------------------------|------------|--------------------------| -|**NULL**|(any)|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0 < size < 9|**EINVAL**|Empty string| -|Not **NULL** (pointing to valid buffer)|Size > 9|0|Current time formatted as specified in the remarks| +| *`buffer`* | *`numberOfElements`* | Return | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | (any) | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 < size < 9 | `EINVAL` | Empty string | +| Not `NULL` (pointing to valid buffer) | Size > 9 | 0 | Current time formatted as specified in the remarks | -## Security Issues +## Security issues -Passing in an invalid non-**NULL** value for the buffer will result in an access violation if the *numberOfElements* parameter is greater than 9. +Passing in an invalid non-`NULL` value for the buffer will result in an access violation if the *`numberOfElements`* parameter is greater than 9. -Passing a value for *numberOfElements* that is greater than the actual size of the buffer will result in buffer overrun. +Passing a value for *`numberOfElements`* that is greater than the actual size of the buffer will result in buffer overrun. ## Remarks -These functions provide more secure versions of [_strtime](strtime-wstrtime.md) and [_wstrtime](strtime-wstrtime.md). The **_strtime_s** function copies the current local time into the buffer pointed to by *timestr*. The time is formatted as **hh:mm:ss** where **hh** is two digits representing the hour in 24-hour notation, **mm** is two digits representing the minutes past the hour, and **ss** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds past 6 P.M. The buffer must be at least 9 bytes long; the actual size is specified by the second parameter. +These functions provide more secure versions of [`_strtime`](strtime-wstrtime.md) and [`_wstrtime`](strtime-wstrtime.md). The **`_strtime_s`** function copies the current local time into the buffer pointed to by *`buffer`*. The time is formatted as **hh:mm:ss** where **`hh`** is two digits representing the hour in 24-hour notation, **`mm`** is two digits representing the minutes past the hour, and **`ss`** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds after 6 P.M. The buffer must be at least 9 bytes long; the actual size is specified by the second parameter. -**_wstrtime** is a wide-character version of **_strtime**; the argument and return value of **_wstrtime** are wide-character strings. These functions behave identically otherwise. +**`_wstrtime_s`** is a wide-character version of **`_strtime_s`**; the argument and return value of **`_wstrtime_s`** are wide-character strings. These functions behave identically otherwise. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping: +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime_s**|**_strtime_s**|**_strtime_s**|**_wstrtime_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrtime_s` | **`_strtime_s`** | **`_strtime_s`** | **`_wstrtime_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtime_s**|\| -|**_wstrtime_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_strtime_s`** | \ | +| **`_wstrtime_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -136,11 +136,11 @@ OS date: 04/25/03 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strtime-wstrtime.md b/docs/c-runtime-library/reference/strtime-wstrtime.md index a06657ee51..a23a103124 100644 --- a/docs/c-runtime-library/reference/strtime-wstrtime.md +++ b/docs/c-runtime-library/reference/strtime-wstrtime.md @@ -3,16 +3,16 @@ description: "Learn more about: _strtime, _wstrtime" title: "_strtime, _wstrtime" ms.date: "4/2/2020" api_name: ["_wstrtime", "_strtime", "_o__strtime", "_o__wstrtime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wstrtime", "_strtime", "wstrtime", "strtime", "_tstrtime"] helpviewer_keywords: ["strtime function", "_strtime function", "_wstrtime function", "copying time to buffers", "wstrtime function", "tstrtime function", "_tstrtime function", "time, copying"] ms.assetid: 9e538161-cf49-44ec-bca5-c0ab0b9e4ca3 --- -# _strtime, _wstrtime +# `_strtime`, `_wstrtime` -Copy the time to a buffer. More secure versions of these functions are available; see [_strtime_s, _wstrtime_s](strtime-s-wstrtime-s.md). +Copy the time to a buffer. More secure versions of these functions are available; see [`_strtime_s`, `_wstrtime_s`](strtime-s-wstrtime-s.md). ## Syntax @@ -35,37 +35,37 @@ wchar_t *_wstrtime( ### Parameters -*timestr*
+*`timestr`*\ Time string. -## Return Value +## Return value -Returns a pointer to the resulting character string *timestr*. +Returns a pointer to the resulting character string *`timestr`*. ## Remarks -The **_strtime** function copies the current local time into the buffer pointed to by *timestr*. The time is formatted as **hh:mm:ss** where **hh** is two digits representing the hour in 24-hour notation, **mm** is two digits representing the minutes past the hour, and **ss** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds past 6 P.M. The buffer must be at least 9 bytes long. +The **`_strtime`** function copies the current local time into the buffer pointed to by *`timestr`*. The time is formatted as *`hh:mm:ss`*, where *`hh`* is two digits that represent the hour in 24-hour notation. *`mm`* is two digits for the minutes past the hour, and *`ss`* is two digits for seconds. For example, the string *`18:23:44`* represents 23 minutes and 44 seconds after 6 P.M. The buffer must be at least 9 bytes long. -**_wstrtime** is a wide-character version of **_strtime**; the argument and return value of **_wstrtime** are wide-character strings. These functions behave identically otherwise. If *timestr* is a **NULL** pointer or if *timestr* is formatted incorrectly, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the exception is allowed to continue, these functions return a **NULL** and set **errno** to **EINVAL** if *timestr* was a **NULL** or set **errno** to **ERANGE** if *timestr* is formatted incorrectly. +**`_wstrtime`** is a wide-character version of **`_strtime`**; the argument and return value of **`_wstrtime`** are wide-character strings. These functions behave identically otherwise. If *`timestr`* is a `NULL` pointer or if *`timestr`* is formatted incorrectly, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If the exception is allowed to continue, these functions return a `NULL`, and set `errno` to `EINVAL` if *`timestr`* was a `NULL` or set `errno` to `ERANGE` if *`timestr`* is formatted incorrectly. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime**|**_strtime**|**_strtime**|**_wstrtime**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrtime` | **`_strtime`** | **`_strtime`** | **`_wstrtime`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtime**|\| -|**_wstrtime**|\ or \| +| Routine | Required header | +|---|---| +| **`_strtime`** | \ | +| **`_wstrtime`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,11 +91,11 @@ The current time is 14:21:44 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md b/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md index 435cf99c5e..568751bf38 100644 --- a/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md +++ b/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md @@ -3,14 +3,13 @@ title: "strtod, _strtod_l, wcstod, _wcstod_l" description: "API reference for strtod, _strtod_l, wcstod, and _wcstod_l; which convert strings to a double-precision value." ms.date: "08/27/2020" api_name: ["wcstod", "_wcstod_l", "_strtod_l", "strtod", "_o__strtod_l", "_o__wcstod_l", "_o_strtod", "_o_wcstod"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcstod", "strtod", "wcstod", "_strtod_l", "_wcstod_l", "stdlib/strtod", "corecrt_wstdlib/wcstod", "stdlib/_strtod_l", "corecrt_wstdlib/_wcstod_l"] helpviewer_keywords: ["wcstod_l function", "tcstod_l function", "_tcstod_l function", "strtod function", "_wcstod_l function", "wcstod function", "strtod_l function", "tcstod function", "_tcstod function", "_strtod_l function", "string conversion, to floating point values"] -ms.assetid: 0444f74a-ba2a-4973-b7f0-1d77ba88c6ed --- -# strtod, _strtod_l, wcstod, _wcstod_l +# `strtod`, `_strtod_l`, `wcstod`, `_wcstod_l` Convert strings to a double-precision value. @@ -30,7 +29,7 @@ double wcstod( const wchar_t *strSource, wchar_t **endptr ); -double wcstod_l( +double _wcstod_l( const wchar_t *strSource, wchar_t **endptr, _locale_t locale @@ -39,77 +38,77 @@ double wcstod_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to character that stops scan. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtod** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-**HUGE_VAL**. The sign of **HUGE_VAL** matches the sign of the value that can't be represented. **strtod** returns `0` if no conversion can be performed or an underflow occurs. +**`strtod`** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-`HUGE_VAL`. The sign of `HUGE_VAL` matches the sign of the value that can't be represented. **`strtod`** returns `0` if no conversion can be performed or an underflow occurs. -**wcstod** returns values analogously to **strtod**: +**`wcstod`** returns values analogously to **`strtod`**: -- For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. -- If there are invalid parameters, **errno** is set to **EINVAL** and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +- For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. +- If there are invalid parameters, `errno` is set to `EINVAL` and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information on this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each function converts the input string *strSource* to a **`double`**. The **strtod** function converts *strSource* to a double-precision value. **strtod** stops reading the string *strSource* at the first character it can't recognize as part of a number. This character may be the terminating null character. **wcstod** is a wide-character version of **strtod**; its *strSource* argument is a wide-character string. These functions behave identically otherwise. +Each function converts the input string *`strSource`* to a **`double`**. The **`strtod`** function converts *`strSource`* to a double-precision value. **`strtod`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating null character. **`wcstod`** is a wide-character version of **`strtod`**; its *`strSource`* argument is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstod**|**strtod**|**strtod**|**wcstod**| -|**_tcstod_l**|**_strtod_l**|**_strtod_l**|**_wcstod_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcstod`** | **`strtod`** | **`strtod`** | **`wcstod`** | +| **`_tcstod_l`** | **`_strtod_l`** | **`_strtod_l`** | **`_wcstod_l`** | -The **LC_NUMERIC** category setting of the current locale determines recognition of the radix point character in *strSource*. For more information, see [setlocale](setlocale-wsetlocale.md). The functions without the **_l** suffix use the current locale; **_strtod_l** is identical to **_strtod** except the former uses the *locale* passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines recognition of the radix point character in *`strSource`*. For more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtod_l`** is identical to **`_strtod`** except the former uses the *`locale`* passed in instead. For more information, see [Locale](../locale.md). -If *endptr* isn't **NULL**, a pointer to the character that stopped the scan is stored at the location pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. -**strtod** expects *strSource* to point to a string of one of the following forms: +**`strtod`** expects *`strSource`* to point to a string of one of the following forms: -[*whitespace*] [*sign*] {*digits* [*radix* *digits*] | *radix* *digits*} [{**e** | **E**} [*sign*] *digits*] -[*whitespace*] [*sign*] {**0x** | **0X**} {*hexdigits* [*radix* *hexdigits*] | *radix* *hexdigits*} [{**p** | **P**} [*sign*] *digits*] -[*whitespace*] [*sign*] {**INF** | **INFINITY**} -[*whitespace*] [*sign*] **NAN** [*sequence*] +[*`whitespace`*] [*`sign`*] {*`digits`* [*`radix`* *`digits`*] | *`radix`* *`digits`*} [{**`e`** | **`E`**} [*`sign`*] *`digits`*]\ +[*`whitespace`*] [*`sign`*] {**`0x`** | **`0X`**} {*`hexdigits`* [*`radix`* *`hexdigits`*] | *`radix`* *`hexdigits`*} [{**`p`** | **`P`**} [*`sign`*] *`digits`*]\ +[*`whitespace`*] [*`sign`*] {**`INF`** | **`INFINITY`**}\ +[*`whitespace`*] [*`sign`*] **`NAN`** [*`sequence`*] -The optional leading *whitespace* may consist of space and tab characters, which are ignored.\ -*sign* is either plus (+) or minus (-).\ -*digits* are one or more decimal digits.\ -*hexdigits* are one or more hexadecimal digits.\ -*radix* is the radix point character, either a period (.) in the default "C" locale, or the locale-specific value if the current locale is different or when *locale* is specified.\ - A *sequence* is a sequence of alphanumeric or underscore characters. +The optional leading *`whitespace`* may consist of space and tab characters, which are ignored.\ +*`sign`* is either plus (+) or minus (-).\ +*`digits`* are one or more decimal digits.\ +*`hexdigits`* are one or more hexadecimal digits.\ +*`radix`* is the radix point character, either a period (.) in the default "C" locale, or the locale-specific value if the current locale is different or when *`locale`* is specified.\ + A *`sequence`* is a sequence of alphanumeric or underscore characters. In both decimal and hexadecimal number forms, if no digits appear before the radix point character, at least one must appear after the radix point character. -In the decimal form, the decimal digits can be followed by an exponent, which consists of an introductory letter (**e** or **E**) and an optionally signed integer. +In the decimal form, the decimal digits can be followed by an exponent, which consists of an introductory letter (**`e`** or **`E`**) and an optionally signed integer. -In the hexadecimal form, the hexadecimal digits can be followed by an exponent, which consists of an introductory letter (**p** or **P**) and an optionally signed decimal integer that represents the exponent as a power of 2. +In the hexadecimal form, the hexadecimal digits can be followed by an exponent, which consists of an introductory letter (**`p`** or **`P`**) and an optionally signed decimal integer that represents the exponent as a power of 2. In either form, if there isn't an exponent part or a radix point character, a radix point character is assumed to follow the last digit in the string. -Case is ignored in both the **INF** and **NAN** forms. The first character that doesn't fit one of these forms stops the scan. +Case is ignored in both the **`INF`** and **`NAN`** forms. The first character that doesn't fit one of these forms stops the scan. -The UCRT versions of these functions don't support conversion of Fortran-style (**d** or **D**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. The UCRT versions support hexadecimal strings and round-tripping of INF and NAN values, which weren't supported in earlier versions. This can also cause breaking changes in your code. For example, the string "0x1a" would be interpreted by **strtod** as 0.0 in previous versions, but as 26.0 in the UCRT version. +The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. The UCRT versions support hexadecimal strings and round-tripping of `INF` and `NAN` values, which weren't supported in earlier versions. This support can also cause breaking changes in your code. For example, the string "`0x1a`" would be interpreted by **`strtod`** as 0.0 in previous versions, but as 26.0 in the UCRT version. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtod**, **_strtod_l**|C: `` C++: `` or `` | -|**wcstod**, **_wcstod_l**|C: `` or `` C++: ``, ``, or `` | +| Routine | Required header | +|---|---| +| **`strtod`**, **`_strtod_l`** | C: `` C++: `` or `` | +| **`wcstod`**, **`_wcstod_l`** | C: `` or `` C++: ``, ``, or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -124,37 +123,54 @@ For additional compatibility information, see [Compatibility](../../c-runtime-li #include #include -int main( void ) +int main(void) { - char *string, *stopstring; - double x; - long l; - int base; - unsigned long ul; - - string = "3.1415926This stopped it"; - x = strtod( string, &stopstring ); - printf( "string = %s\n", string ); - printf(" strtod = %f\n", x ); - printf(" Stopped scan at: %s\n\n", stopstring ); - - string = "-10110134932This stopped it"; - l = strtol( string, &stopstring, 10 ); - printf( "string = %s\n", string ); - printf(" strtol = %ld\n", l ); - printf(" Stopped scan at: %s\n\n", stopstring ); - - string = "10110134932"; - printf( "string = %s\n", string ); - - // Convert string using base 2, 4, and 8: - for( base = 2; base <= 8; base *= 2 ) - { - // Convert the string: - ul = strtoul( string, &stopstring, base ); - printf( " strtol = %ld (base %d)\n", ul, base ); - printf( " Stopped scan at: %s\n", stopstring ); - } + char *string, *stopstring; + double x; + long l; + int base; + unsigned long ul; + + string = "3.1415926This stopped it"; + x = strtod(string, &stopstring); + printf("string = %s\n", string); + printf(" strtod = %f\n", x); + printf(" Stopped scan at: %s\n\n", stopstring); + + string = "-10110134932This stopped it"; + l = strtol(string, &stopstring, 10); + printf("string = %s\n", string); + printf(" strtol = %ld\n", l); + printf(" Stopped scan at: %s\n\n", stopstring); + + string = "10110134932"; + printf("string = %s\n", string); + + // Convert string using base 2, 4, and 8: + for (base = 2; base <= 8; base *= 2) + { + // Convert the string: + ul = strtoul(string, &stopstring, base); + printf(" strtol = %ld (base %d)\n", ul, base); + printf(" Stopped scan at: %s\n", stopstring); + } + + // NaN + x = strtod("+nan", &stopstring); + printf("\n%f\n", x); + + // INF + x = strtod("-INF", &stopstring); + printf("\n%f\n", x); + + // e - exponent + x = strtod("1.18973e+49", &stopstring); + printf("\n%f\n", x); + + // doesn't handle Fortran style + x = strtod("1.18973d+49", &stopstring); + printf("\n%f\n", x); + printf("No Fortran style support. Stopped parsing at %s\n", stopstring); } ``` @@ -174,18 +190,27 @@ string = 10110134932 Stopped scan at: 4932 strtol = 2134108 (base 8) Stopped scan at: 932 + +nan + +-inf + +11897299999999999421285862642874618947301378359296.000000 + +1.189730 +No Fortran style support. Stopped parsing at d+49 ``` ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[localeconv](localeconv.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`localeconv`](localeconv.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md b/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md index 9ee3df1137..016a7fa54c 100644 --- a/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md +++ b/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtof, _strtof_l, wcstof, _wcstof_l" title: "strtof, _strtof_l, wcstof, _wcstof_l" ms.date: "4/2/2020" api_name: ["_strtof_l", "wcstof", "strtof", "_wcstof_l", "_o__strtof_l", "_o__wcstof_l", "_o_strtof", "_o_wcstof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcstof", "_tcstof_l", "stdlib/strtof", "strtof", "stdlib/_strtof_l", "_strtof_l", "corecrt_wstdlib/wcstof", "wcstof", "corecrt_wstdlib/_wcstof_l", "_wcstof_l"] helpviewer_keywords: ["_strtof_l function", "_tcstof function", "_wcstof_l function", "wcstof function", "_tcstof_l function", "strtof function"] ms.assetid: 52221b46-876d-4fcc-afb1-97512c17a43b --- -# strtof, _strtof_l, wcstof, _wcstof_l +# `strtof`, `_strtof_l`, `wcstof`, `_wcstof_l` Converts strings to a single-precision floating-point value. @@ -39,56 +39,56 @@ float wcstof_l( ## Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtof** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-**HUGE_VALF**. The sign of **HUGE_VALF** matches the sign of the value that cannot be represented. **strtof** returns 0 if no conversion can be performed or an underflow occurs. +**`strtof`** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-`HUGE_VALF`. The sign of `HUGE_VALF` matches the sign of the value that can't be represented. **`strtof`** returns 0 if no conversion can be performed or an underflow occurs. -**wcstof** returns values analogously to **strtof**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`wcstof`** returns values analogously to **`strtof`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each function converts the input string *strSource* to a **`float`**. The **strtof** function converts *strSource* to a single-precision value. **strtof** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character. **wcstof** is a wide-character version of **strtof**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +Each function converts the input string *`strSource`* to a **`float`**. The **`strtof`** function converts *`strSource`* to a single-precision value. **`strtof`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating null character. **`wcstof`** is a wide-character version of **`strtof`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstof**|**strtof**|**strtof**|**wcstof**| -|**_tcstof_l**|**_strtof_l**|**_strtof_l**|**_wcstof_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstof` | **`strtof`** | **`strtof`** | **`wcstof`** | +| `_tcstof_l` | **`_strtof_l`** | **`_strtof_l`** | **`_wcstof_l`** | -The **LC_NUMERIC** category setting of the current locale determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; the ones that have the suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; the ones that have the suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtof** expects *strSource* to point to a string of the following form: +**`strtof`** expects *`strSource`* to point to a string of the following form: -[*whitespace*] [*sign*] [*digits*] [__.__*digits*] [{**e** | **E**} [*sign*] *digits*] +[*`whitespace`*] [*`sign`*] [*`digits`*] [.*`digits`*] [{**`e`** | **`E`**} [*`sign`*] *`digits`*] -A *whitespace* may consist of space and tab characters, which are ignored; *sign* is either plus (**+**) or minus (**-**); and *digits* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**e** or **E**) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`sign`* is either plus (**`+`**) or minus (**`-`**); and *`digits`* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**`e`** or **`E`**) and an optionally signed integer. If no exponent part or radix character appears, a radix character is assumed to follow the last digit in the string. The first character that doesn't fit this form stops the scan. -The UCRT versions of these functions do not support conversion of Fortran-style (**d** or **D**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. +The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtof**, **_strtof_l**|C: \ C++: \ or \| -|**wcstof**, **_wcstof_l**|C: \ or \ C++: \, \ or \| +| Routine | Required header | +|---|---| +| **`strtof`**, **`_strtof_l`** | C: \ C++: \ or \ | +| **`wcstof`**, **`_wcstof_l`** | C: \ or \ C++: \, \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,15 +122,15 @@ string = 3.14159This stopped it ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[localeconv](localeconv.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`localeconv`](localeconv.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md b/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md index a1667808b9..f53343d45c 100644 --- a/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md +++ b/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md @@ -1,16 +1,16 @@ --- description: "Learn more about: _strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l" title: "_strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l" -ms.date: "4/2/2020" +ms.date: 05/18/2022 api_name: ["_strtoi64", "_strtoi64_l", "_wcstoi64_l", "_wcstoi64", "_o__strtoi64", "_o__strtoi64_l", "_o__wcstoi64", "_o__wcstoi64_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_strtoi64", "strtoi64", "_stroi64_l", "_wcstoi64_l", "wcstoi64_l", "_wcstoi64", "wcstoi64", "strtoi64_l"] +f1_keywords: ["CRT_OPEN/_strtoi64", "CRT_OPEN/_stroi64_l", "CORECRT_WSTDLIB/_wcstoi64", "CORECRT_WSTDLIB/_wcstoi64_l", "TCHAR/_tcstoi64", "TCHAR/_tcstoi64_l", "_strtoi64", "_stroi64_l", "_wcstoi64", "_wcstoi64_l", "_tcstoi64", "_tcstoi64_l", "strtoi64", "strtoi64_l", "wcstoi64", "wcstoi64_l"] helpviewer_keywords: ["_strtoi64 function", "_wcstoi64 function", "_strtoi64_l function", "string conversion, to integers", "_wcstoi64_l function", "strtoi64_l function", "wcstoi64 function", "strtoi64 function", "wcstoi64_l function"] ms.assetid: ea2abc50-7bfe-420e-a46b-703c3153593a --- -# _strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l +# `_strtoi64`, `_wcstoi64`, `_strtoi64_l`, `_wcstoi64_l` Convert a string to an **`__int64`** value. @@ -43,67 +43,67 @@ __int64 _wcstoi64_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to character that stops scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_strtoi64** returns the value represented in the string *strSource*, except when the representation would cause an overflow, in which case it returns **_I64_MAX** or **_I64_MIN**. The function will return 0 if no conversion can be performed. **_wcstoi64** returns values analogously to **strtoi64**. +**`_strtoi64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns `_I64_MAX` or `_I64_MIN`. The function will return 0 if no conversion can be performed. **`_wcstoi64`** returns values analogously to **`_strtoi64`**. -**_I64_MAX** and **_I64_MIN** are defined in LIMITS.H. +`_I64_MAX` and `_I64_MIN` are defined in LIMITS.H. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_strtoi64** function converts *strSource* to an **`__int64`**. Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character greater than or equal to *base*. **_wcstoi64** is a wide-character version of **_strtoi64**; its *strSource* argument is a wide-character string. These functions behave identically otherwise. +The **`_strtoi64`** function converts *`strSource`* to an **`__int64`**. Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character greater than or equal to *`base`*. **`_wcstoi64`** is a wide-character version of **`_strtoi64`**; its *`strSource`* argument is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoi64**|**_strtoi64**|**_strtoi64**|**_wcstoi64**| -|**_tcstoi64_l**|**_strtoi64_l**|**_strtoi64_l**|**_wcstoi64_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| ****`_tcstoi64`**** | **`_strtoi64`** | **`_strtoi64`** | **`_wcstoi64`** | +| ****`_tcstoi64_l`**** | **`_strtoi64_l`** | **`_strtoi64_l`** | **`_wcstoi64_l`** | -The locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale](setlocale-wsetlocale.md). The functions without the _l suffix use the current locale; **_strtoi64_l** and **_wcstoi64_l** are identical to the corresponding function without the **_l** suffix except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoi64_l`** and **`_wcstoi64_l`** are identical to the corresponding function without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. -**_strtoi64** expects *strSource* to point to a string of the following form: +**`_strtoi64`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*`digits`* \| *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored; *digits* are one or more decimal digits; *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *strSource* are used to determine the base. If the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtoi64**, **_strtoi64_l**|\| -|**_wcstoi64**, **_wcstoi64_l**|\ or \| +| Function | Required header | +|---|---| +| **`_strtoi64`**, **`_strtoi64_l`** | `` | +| **`_wcstoi64`**, **`_wcstoi64_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md b/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md index a68383b42a..288b4dcce8 100644 --- a/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md +++ b/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" title: "strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" -ms.date: "11/04/2016" +description: "Learn more about: strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" +ms.date: 11/04/2016 api_name: ["wcstoimax", "_wcstoimax_l", "_strtoimax_l", "strtoimax"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcstoimax", "_tcstoimax", "strtoimax", "_wcstoimax_l", "_strtoimax_l", "_tcstoimax_l"] -helpviewer_keywords: ["strtoimax funciton", "conversion functions", "_strtoimax_l function", "_wcstoimax_l function", "wcstoimax function"] -ms.assetid: 4530d3dc-aaac-4a76-b7cf-29ae3c98d0ae +helpviewer_keywords: ["strtoimax function", "conversion functions", "_strtoimax_l function", "_wcstoimax_l function", "wcstoimax function"] --- -# strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l +# `strtoimax`, `_strtoimax_l`, `wcstoimax`, `_wcstoimax_l` Converts a string to an integer value of the largest supported signed integer type. @@ -43,66 +42,66 @@ intmax_t _wcstoimax_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtoimax** returns the value that's represented in the string *strSource*, except when the representation would cause an overflow—in that case, it returns **INTMAX_MAX** or **INTMAX_MIN**, and **errno** is set to **ERANGE**. The function returns 0 if no conversion can be performed. **wcstoimax** returns values analogously to **strtoimax**. +**`strtoimax`** returns the value that's represented in the string *`strSource`*, except when the representation would cause an overflow—in that case, it returns `INTMAX_MAX` or `INTMAX_MIN`, and `errno` is set to `ERANGE`. The function returns 0 if no conversion can be performed. **`wcstoimax`** returns values analogously to **`strtoimax`**. -**INTMAX_MAX** and **INTMAX_MIN** are defined in stdint.h. +`INTMAX_MAX` and `INTMAX_MIN` are defined in stdint.h. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **strtoimax** function converts *strSource* to an **intmax_t**. The wide-character version of **strtoimax** is **wcstoimax**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. +The **`strtoimax`** function converts *`strSource`* to an `intmax_t`. The wide-character version of **`strtoimax`** is **`wcstoimax`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. -The locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; **_strtoimax_l** and **_wcstoimax_l** are identical to the corresponding functions that don't have the **_l** suffix except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; **`_strtoimax_l`** and **`_wcstoimax_l`** are identical to the corresponding functions that don't have the `_l` suffix except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoimax**|**strtoimax**|**strtoimax**|**wcstoimax**| -|**_tcstoimax_l**|**strtoimax_l**|**_strtoimax_l**|**_wcstoimax_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoimax` | **`strtoimax`** | **`strtoimax`** | **`wcstoimax`** | +| `_tcstoimax_l` | **`strtoimax_l`** | **`_strtoimax_l`** | **`_wcstoimax_l`** | -**strtoimax** expects *strSource* to point to a string of the following form: +**`strtoimax`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored; *digits* are one or more decimal digits; *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`digits`* are one or more decimal digits; *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoimax**, **_strtoimax_l**, **wcstoimax**, **_wcstoimax_l**|\| +| Routine | Required header | +|---|---| +| **`strtoimax`**, **`_strtoimax_l`**, **`wcstoimax`**, **`_wcstoimax_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l](strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoumax`, `_strtoumax_l`, `wcstoumax`, `_wcstoumax_l`](strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md b/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md index 742b04f48d..4f0db782fa 100644 --- a/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md +++ b/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _m title: "strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l" ms.date: "4/2/2020" api_name: ["_wcstok_s_l", "_mbstok_s_l", "_mbstok_s", "strtok_s", "wcstok_s", "_strtok_s_l", "_o__mbstok_s", "_o__mbstok_s_l", "_o_strtok_s", "_o_wcstok_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcstok_s_l", "_wcstok_s_l", "_tcstok_s", "_mbstok_s_l", "strtok_s", "wcstok_s", "_mbstok_s", "_strtok_s_l"] +f1_keywords: ["STRING/strtok_s", "TCHAR/_strtok_s_l", "MBSTRING/_mbstok_s", "MBSTRING/_mbstok_s_l", "CORECRT_WSTRING/wcstok_s", "TCHAR/_wcstok_s_l", "TCHAR/_tcstok_s", "TCHAR/_tcstok_s_l", "strtok_s", "_strtok_s_l", "_mbstok_s", "_mbstok_s_l", "wcstok_s", "_wcstok_s_l", "_tcstok_s", "_tcstok_s_l"] helpviewer_keywords: ["_strtok_s_l function", "_mbstok_s_l function", "strings [C++], searching", "mbstok_s_l function", "wcstok_s_l function", "_wcstok_s_l function", "_tcstok_s function", "_tcstok_s_l function", "strtok_s_l function", "wcstok_s function", "tokens, finding in strings", "mbstok_s function", "_mbstok_s function", "strtok_s function"] ms.assetid: 7696c972-f83b-4617-8c82-95973e9fdb46 --- # `strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l` -Finds the next token in a string, by using the current locale or a locale that's passed in. These versions of [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Finds the next token in a string, by using the current locale or a locale that's passed in. These versions of [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbstok_s`** and **`_mbstok_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -62,65 +62,65 @@ unsigned char* _mbstok_s_l( ### Parameters -*`str`*
+*`str`*\ A string containing the token or tokens to find. -*`delimiters`*
+*`delimiters`*\ The set of delimiter characters to use. -*`context`*
+*`context`*\ Used to store position information between calls to the function. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns a pointer to the next token found in *`str`*. Returns **`NULL`** when no more tokens are found. Each call modifies *`str`* by substituting a null character for the first delimiter that occurs after the returned token. +Returns a pointer to the next token found in *`str`*. Returns `NULL` when no more tokens are found. Each call modifies *`str`* by substituting a null character for the first delimiter that occurs after the returned token. -### Error Conditions +### Error conditions -|*`str`*|*`delimiters`*|*`context`*|Return value|**`errno`**| -|----------------|------------------|---------------|------------------|-------------| -|**`NULL`**|any|pointer to a null pointer|**`NULL`**|**`EINVAL`**| -|any|**`NULL`**|any|**`NULL`**|**`EINVAL`**| -|any|any|**`NULL`**|**`NULL`**|**`EINVAL`**| +| *`str`* | *`delimiters`* | *`context`* | Return value | `errno` | +|---|---|---|---|---| +| `NULL` | any | pointer to a null pointer | `NULL` | `EINVAL` | +| any | `NULL` | any | `NULL` | `EINVAL` | +| any | any | `NULL` | `NULL` | `EINVAL` | -If *`str`* is **`NULL`** but *`context`* is a pointer to a valid context pointer, there's no error. +If *`str`* is `NULL` but *`context`* is a pointer to a valid context pointer, there's no error. ## Remarks -The **`strtok_s`** family of functions finds the next token in *`str`*. The set of characters in *`delimiters`* specifies possible delimiters of the token to be found in *`str`* on the current call. **`wcstok_s`** and **`_mbstok_s`** are wide-character and multibyte-character versions of **`strtok_s`**. The arguments and return values of **`wcstok_s`** and **`_wcstok_s_l`** are wide-character strings; those of **`_mbstok_s`** and **`_mbstok_s_l`** are multibyte-character strings. These functions behave identically otherwise. +The **`strtok_s`** family of functions finds the next token in *`str`*. The set of characters in *`delimiters`* specifies possible delimiters of the token to be found in *`str`* on the current call. **`wcstok_s`** and **`_mbstok_s`** are wide-character and multibyte-character versions of **`strtok_s`**. The arguments and return values of **`wcstok_s`** and **`_wcstok_s_l`** are wide-character strings. The arguments and return values of **`_mbstok_s`** and **`_mbstok_s_l`** are multibyte-character strings. These functions behave identically otherwise. -This function validates its parameters. When an error condition occurs, as in the Error Conditions table, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`NULL`**. +This function validates its parameters. When an error condition occurs, as in the Error Conditions table, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `NULL`. -On the first call to **`strtok_s`**, the function skips leading delimiters and returns a pointer to the first token in *`str`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`str`* by a series of calls to **`strtok_s`**. Each call to **`strtok_s`** modifies *`str`* by inserting a null character after the token returned by that call. The *`context`* pointer keeps track of which string is being read and where in the string the next token is to be read. To read the next token from *`str`*, call **`strtok_s`** with a **`NULL`** value for the *`str`* argument, and pass the same *`context`* parameter. The **`NULL`** *`str`* argument causes **`strtok_s`** to search for the next token in the modified *`str`*. The *`delimiters`* argument can take any value from one call to the next so that the set of delimiters may vary. +On the first call to **`strtok_s`**, the function skips leading delimiters and returns a pointer to the first token in *`str`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`str`* by a series of calls to **`strtok_s`**. Each call to **`strtok_s`** modifies *`str`* by inserting a null character after the token returned by that call. The *`context`* pointer keeps track of which string is being read and where in the string the next token is to be read. To read the next token from *`str`*, call **`strtok_s`** with a `NULL` value for the *`str`* argument, and pass the same *`context`* parameter. The `NULL` *`str`* argument causes **`strtok_s`** to search for the next token in the modified *`str`*. The *`delimiters`* argument can take any value from one call to the next so that the set of delimiters may vary. Since the *`context`* parameter supersedes the static buffers used in **`strtok`** and **`_strtok_l`**, it's possible to parse two strings simultaneously in the same thread. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). -The versions of these functions without the **`_l`** suffix use the current thread locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they instead use the locale specified by the *`locale`* parameter. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions without the **`_l`** suffix use the current thread locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they instead use the locale specified by the *`locale`* parameter. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## Requirements +### Generic-text routine mappings -|Routine|Required header| -|-------------|---------------------| -|**`strtok_s`**|``| -|**`_strtok_s_l`**|``| -|**`wcstok_s`**,
**`_wcstok_s_l`**|`` or ``| -|**`_mbstok_s`**,
**`_mbstok_s_l`**|``| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstok_s` | **`strtok_s`** | **`_mbstok_s`** | **`wcstok_s`** | +| `_tcstok_s_l` | **`_strtok_s_l`** | **`_mbstok_s_l`** | **`_wcstok_s_l`** | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +## Requirements -### Generic-Text Routine Mappings +| Routine | Required header | +|---|---| +| **`strtok_s`** | `` | +| **`_strtok_s_l`** | `` | +| **`wcstok_s`**,
**`_wcstok_s_l`** | `` or `` | +| **`_mbstok_s`**,
**`_mbstok_s_l`** | `` | -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstok_s`**|**`strtok_s`**|**`_mbstok_s`**|**`wcstok_s`**| -|**`_tcstok_s_l`**|**`_strtok_s_l`**|**`_mbstok_s_l`**|**`_wcstok_s_l`**| +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -190,8 +190,8 @@ tokens ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md b/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md index ee2e7d6a29..00ad10086c 100644 --- a/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md +++ b/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md @@ -3,10 +3,10 @@ description: "Learn more about: strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _ title: "strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l" ms.date: "6/24/2020" api_name: ["_mbstok_l", "_mbstok", "wcstok", "_mbstok", "strtok", "_wcstok_l", "_o__mbstok", "_o__mbstok_l", "_o_strtok", "_o_wcstok"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbstok", "strtok", "_tcstok", "wcstok"] +f1_keywords: ["STRING/strtok", "TCHAR/_strtok_l", "MBSTRING/_mbstok", "MBSTRING/_mbstok_l", "CORECRT_WSTRING/wcstok", "TCHAR/_wcstok_l", "TCHAR/_tcstok", "TCHAR/_tcstok_l", "strtok", "strtok_l", "_mbstok", "_mbstok_l", "wcstok", "_wcstok_l", "_tcstok", "_tcstok_l"] helpviewer_keywords: ["mbstok_l function", "strings [C++], searching", "tcstok function", "_tcstok function", "_strtok_l function", "strtok function", "mbstok function", "wcstok_l function", "_mbstok function", "tcstok_l function", "tokens, finding in strings", "_mbstok_l function", "wcstok function", "_wcstok_l function", "_tcstok_l function", "strtok_l function"] ms.assetid: 904cb734-f0d7-4d77-ba81-4791ddf461ae --- @@ -24,12 +24,12 @@ char *strtok( char *strToken, const char *strDelimit ); -char *strtok_l( +char *_strtok_l( char *strToken, const char *strDelimit, _locale_t locale ); -wchar_t *wcstok( +wchar_t *wcstok( /* Non-standard, define _CRT_NON_CONFORMING_WCSTOK to use */ wchar_t *strToken, const wchar_t *strDelimit ); @@ -38,7 +38,7 @@ wchar_t *wcstok( const wchar_t *strDelimit, wchar_t **context ); -wchar_t *wcstok_l( +wchar_t *_wcstok_l( wchar_t *strToken, const wchar_t *strDelimit, _locale_t locale @@ -56,59 +56,59 @@ unsigned char *_mbstok_l( ### Parameters -*`strToken`*
+*`strToken`*\ String containing token or tokens. -*`strDelimit`*
+*`strDelimit`*\ Set of delimiter characters. -*`locale`*
+*`locale`*\ Locale to use. -*`context`*
+*`context`*\ Points to memory used to store the internal state of the parser so that the parser can continue from where it left off the next time you call **`wcstok`**. -## Return Value +## Return value -Returns a pointer to the next token found in *`strToken`*. The functions return **`NULL`** when no more tokens are found. Each call modifies *`strToken`* by substituting a null character for the first delimiter that occurs after the returned token. +Returns a pointer to the next token found in *`strToken`*. The functions return `NULL` when no more tokens are found. Each call modifies *`strToken`* by substituting a null character for the first delimiter that occurs after the returned token. ## Remarks -The **`strtok`** function finds the next token in *`strToken`*. The set of characters in *`strDelimit`* specifies possible delimiters of the token to be found in *`strToken`* on the current call. **`wcstok`** and **`_mbstok`** are wide-character and multibyte-character versions of **`strtok`**. The arguments and return value of **`wcstok`** are wide-character strings; those of **`_mbstok`** are multibyte-character strings. These three functions behave identically otherwise. +The **`strtok`** function finds the next token in *`strToken`*. The set of characters in *`strDelimit`* specifies possible delimiters of the token to be found in *`strToken`* on the current call. **`wcstok`** and **`_mbstok`** are wide-character and multibyte-character versions of **`strtok`**. The arguments and return value of **`wcstok`** are wide-character strings. The argumets and return value of **`_mbstok`** are multibyte-character strings. These three functions behave identically otherwise. -The two argument version of **`wcstok`** is not standard. If you need to use that version, you'll need to define `_CRT_NON_CONFORMING_WCSTOK` before you `#include ` (or `#include `). +The two argument version of **`wcstok`** isn't standard. If you need to use that version, you'll need to define `_CRT_NON_CONFORMING_WCSTOK` before you `#include ` (or `#include `). > [!IMPORTANT] -> These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -On the first call to **`strtok`**, the function skips leading delimiters and returns a pointer to the first token in *`strToken`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`strToken`* by a series of calls to **`strtok`**. Each call to **`strtok`** modifies *`strToken`* by inserting a null character after the **`token`** returned by that call. To read the next token from *`strToken`*, call **`strtok`** with a **`NULL`** value for the *`strToken`* argument. The **`NULL`** *`strToken`* argument causes **`strtok`** to search for the next token in the modified *`strToken`*. The *`strDelimit`* argument can take any value from one call to the next so that the set of delimiters may vary. +On the first call to **`strtok`**, the function skips leading delimiters and returns a pointer to the first token in *`strToken`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`strToken`* by a series of calls to **`strtok`**. Each call to **`strtok`** modifies *`strToken`* by inserting a null character after the **`token`** returned by that call. To read the next token from *`strToken`*, call **`strtok`** with a `NULL` value for the *`strToken`* argument. The `NULL` *`strToken`* argument causes **`strtok`** to search for the next token in the modified *`strToken`*. The *`strDelimit`* argument can take any value from one call to the next so that the set of delimiters may vary. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). -The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). > [!NOTE] > Each function uses a thread-local static variable for parsing the string into tokens. Therefore, multiple threads can simultaneously call these functions without undesirable effects. However, within a single thread, interleaving calls to one of these functions is highly likely to produce data corruption and inaccurate results. When parsing different strings, finish parsing one string before starting to parse the next. Also, be aware of the potential for danger when calling one of these functions from within a loop where another function is called. If the other function ends up using one of these functions, an interleaved sequence of calls will result, triggering data corruption. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstok`**|**`strtok`**|**`_mbstok`**|**`wcstok`**| -|**`_tcstok`**|**`_strtok_l`**|**`_mbstok_l`**|**`_wcstok_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstok` | **`strtok`** | **`_mbstok`** | **`wcstok`** | +| `_tcstok` | **`_strtok_l`** | **`_mbstok_l`** | **`_wcstok_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strtok`**|``| -|**`wcstok`**|`` or ``| -|**`_wcstok_l`**|``| -|**`_mbstok`**, **`_mbstok_l`**|``| +| Routine | Required header | +|---|---| +| **`strtok`** | `` | +| **`wcstok`** | `` or `` | +| **`_wcstok_l`** | `` | +| **`_mbstok`**, **`_mbstok_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -158,8 +158,8 @@ tokens ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md b/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md index 7399a4b814..4ae62a70e1 100644 --- a/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md +++ b/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md @@ -3,15 +3,14 @@ description: "Learn more about: strtol, wcstol, _strtol_l, _wcstol_l" title: "strtol, wcstol, _strtol_l, _wcstol_l" ms.date: "4/2/2020" api_name: ["strtol", "wcstol", "_strtol_l", "_wcstol_l", "_o__strtol_l", "_o__wcstol_l", "_o_strtol", "_o_wcstol"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wcstol_l", "strtol", "_tcstol", "wcstol", "_strtol_l", "_tcstol_l"] +f1_keywords: ["STDLIB/strtol", "STDLIB/_strtol_l", "CORECRT_WSTDLIB/wcstol", "CORECRT_WSTDLIB/_wcstol_l", "TCHAR/_tcstol", "TCHAR/_tcstol_l", "strtol", "_strtol_l", "wcstol", "_wcstol_l", "_tcstol", "_tcstol_l"] helpviewer_keywords: ["wcstol function", "wcstol_l function", "_tcstol function", "string conversion, to integers", "tcstol function", "strtol_l function", "_wcstol_l function", "_strtol_l function", "strtol function"] -ms.assetid: 1787c96a-f283-4a83-9325-33cfc1c7e240 no-loc: [strtol, wcstol, _strtol_l, _wcstol_l, LONG_MAX, LONG_MIN, errno, ERANGE, EINVAL, LC_NUMERIC, _tcstol, _tcstol_l, localeconv, setlocale, _wsetlocale, strtod, _strtod_l, wcstod, _wcstod_l, strtoll, _strtoll_l, wcstoll, _wcstoll_l, strtoul, _strtoul_l, wcstoul, _wcstoul_l, atof, _atof_l, _wtof, _wtof_l] --- -# strtol, wcstol, _strtol_l, _wcstol_l +# `strtol`, `wcstol`, `_strtol_l`, `_wcstol_l` Convert strings to a **`long`** integer value. @@ -44,70 +43,70 @@ long _wcstol_l( ### Parameters -*string*\ +*`string`*\ Null-terminated string to convert. -*end_ptr*\ -An output parameter, set to point to the character after the last interpreted character. Ignored, if **NULL**. +*`end_ptr`*\ +An output parameter, set to point to the character after the last interpreted character. Ignored, if `NULL`. -*base*\ +*`base`*\ Number base to use. -*locale*\ +*`locale`*\ Locale to use. -## Return Value +## Return value -**strtol**, **wcstol**, **_strtol_l**, and **_wcstol_l** return the value represented in *string*. They return 0 if no conversion is possible. When the representation would cause an overflow, they return **LONG_MAX** or **LONG_MIN**. +**`strtol`**, **`wcstol`**, **`_strtol_l`**, and **`_wcstol_l`** return the value represented in *`string`*. They return 0 if no conversion is possible. When the representation would cause an overflow, they return `LONG_MAX` or `LONG_MIN`. -**errno** is set to **ERANGE** if overflow or underflow occurs. It's set to **EINVAL** if *string* is **NULL**. Or, if *base* is nonzero and less than 2, or greater than 36. For more information on **ERANGE**, **EINVAL**, and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +`errno` is set to `ERANGE` if overflow or underflow occurs. It's set to `EINVAL` if *`string`* is `NULL`. Or, if *`base`* is nonzero and less than 2, or greater than 36. For more information on `ERANGE`, `EINVAL`, and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **strtol**, **wcstol**, **_strtol_l**, and **_wcstol_l** functions convert *string* to a **`long`**. They stop reading *string* at the first character not recognized as part of a number. It may be the terminating-null character, or the first alphanumeric character greater than or equal to *base*. +The **`strtol`**, **`wcstol`**, **`_strtol_l`**, and **`_wcstol_l`** functions convert *`string`* to a **`long`**. They stop reading *`string`* at the first character not recognized as part of a number. It may be the terminating-null character, or the first alphanumeric character greater than or equal to *`base`*. -**wcstol** and **_wcstol_l** are wide-character versions of **strtol** and **_strtol_l**. Their *string* argument is a wide-character string. These functions behave identically to **strtol** and **_strtol_l** otherwise. The locale's **LC_NUMERIC** category setting determines recognition of the radix character (the fractional marker or decimal point) in *string*. The functions **strtol** and **wcstol** use the current locale. **_strtol_l** and **_wcstol_l** use the locale passed in instead. For more information, see [setlocale] and [Locale](../../c-runtime-library/locale.md). +**`wcstol`** and **`_wcstol_l`** are wide-character versions of **`strtol`** and **`_strtol_l`**. Their *`string`* argument is a wide-character string. These functions behave identically to **`strtol`** and **`_strtol_l`** otherwise. The locale's `LC_NUMERIC` category setting determines recognition of the radix character (the fractional marker or decimal point) in *`string`*. The functions **`strtol`** and **`wcstol`** use the current locale. **`_strtol_l`** and **`_wcstol_l`** use the locale passed in instead. For more information, see [`setlocale`] and [Locale](../locale.md). -When *end_ptr* is **NULL**, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *end_ptr*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *string* is then stored at the location pointed to by *end_ptr*. +When *`end_ptr`* is `NULL`, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *`end_ptr`*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *`string`* is then stored at the location pointed to by *`end_ptr`*. -**strtol** expects *string* to point to a string of the following form: +**`strtol`** expects *`string`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*alphanumerics*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`alphanumerics`*] -Square brackets (`[ ]`) surround optional elements. Curly braces and a vertical bar (`{ | }`) surround alternatives for a single element. *whitespace* may consist of space and tab characters, which are ignored. *alphanumerics* are decimal digits or the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *base* is between 2 and 36, then it's used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *string* are used to determine the base. If the first character is 0, and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35. The scan only allows letters whose values are less than *base*. The first character outside the range of the base stops the scan. For example, suppose *string* starts with "01". If *base* is 0, the scanner assumes it's an octal integer. An '8' or '9' character stops the scan. +Square brackets (`[ ]`) surround optional elements. Curly braces and a vertical bar (`{ | }`) surround alternatives for a single element. *`whitespace`* may consist of space and tab characters, which are ignored. *`alphanumerics`* are decimal digits or the letters `'a'` through `'z'` (or `'A'` through `'Z'`). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is `0`, the initial characters of the string pointed to by *`string`* are used to determine the base. If the first character is `0`, and the second character isn't `'x'` or `'X'`, the string is interpreted as an octal integer. If the first character is `'0'` and the second character is `'x'` or `'X'`, the string is interpreted as a hexadecimal integer. If the first character is `'1'` through `'9'`, the string is interpreted as a decimal integer. The letters `'a'` through `'z'` (or `'A'` through `'Z'`) are assigned the values 10 through 35. The scan only allows letters whose values are less than *`base`*. The first character outside the range of the base stops the scan. For example, suppose *`string`* starts with `"01"`. If *`base`* is `0`, the scanner assumes it's an octal integer. An `'8'` or `'9'` character stops the scan. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstol**|**strtol**|**strtol**|**wcstol**| -|**_tcstol_l**|**_strtol_l**|**_strtol_l**|**_wcstol_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstol` | **`strtol`** | **`strtol`** | **`wcstol`** | +| `_tcstol_l` | **`_strtol_l`** | **`_strtol_l`** | **`_wcstol_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtol**|\| -|**wcstol**|\ or \| -|**_strtol_l**|\| -|**_wcstol_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtol`** | `` | +| **`wcstol`** | `` or `` | +| **`_strtol_l`** | `` | +| **`_wcstol_l`** | `` or `` | -The **_strtol_l** and **_wcstol_l** functions are Microsoft-specific, not part of the Standard C library. For additional compatibility information, see [Compatibility](../compatibility.md). +The **`_strtol_l`** and **`_wcstol_l`** functions are Microsoft-specific, not part of the Standard C library. For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also [Data conversion](../data-conversion.md)\ [Locale](../locale.md)\ -[localeconv](localeconv.md)\ -[setlocale, _wsetlocale](setlocale-wsetlocale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ [String to numeric value functions](../string-to-numeric-value-functions.md)\ -[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)\ -[strtoll, _strtoll_l, wcstoll, _wcstoll_l](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ -[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ -[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md) +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l`](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md b/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md index 76d35f8835..e24182d5b5 100644 --- a/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md +++ b/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md @@ -3,13 +3,13 @@ description: "Learn more about: strtold, _strtold_l, wcstold, _wcstold_l" title: "strtold, _strtold_l, wcstold, _wcstold_l" ms.date: "4/2/2020" api_name: ["wcstold", "strtold", "_strtold_l", "_wcstold_l", "_o__strtold_l", "_o__wcstold_l", "_o_strtold", "_o_wcstold"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcstold_l", "_wcstold_l", "_tcstold", "strtold", "_strtold_l", "wcstold"] +f1_keywords: ["STDLIB/strtold", "STDLIB/_strtold_l", "CORECRT_WSTDLIB/wcstold", "CORECRT_WSTDLIB/_wcstold_l", "TCHAR/_tcstold", "TCHAR/_tcstold_l", "strtold", "_strtold_l", "wcstold", "_wcstold_l", "_tcstold", "_tcstold_l"] ms.assetid: 928c0c9a-bc49-445b-8822-100eb5954115 --- -# strtold, _strtold_l, wcstold, _wcstold_l +# `strtold`, `_strtold_l`, `wcstold`, `_wcstold_l` Converts strings to a long double-precision floating-point value. @@ -38,54 +38,54 @@ long double wcstold_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtold** returns the value of the floating-point number as a **`long double`**, except when the representation would cause an overflow—in that case, the function returns +/-**HUGE_VALL**. The sign of **HUGE_VALL** matches the sign of the value that cannot be represented. **strtold** returns 0 if no conversion can be performed or an underflow occurs. +**`strtold`** returns the value of the floating-point number as a **`long double`**, except when the representation would cause an overflow—in that case, the function returns +/-`HUGE_VALL`. The sign of `HUGE_VALL` matches the sign of the value that can't be represented. **`strtold`** returns 0 if no conversion can be performed or an underflow occurs. -**wcstold** returns values analogously to **strtold**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`wcstold`** returns values analogously to **`strtold`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each function converts the input string *strSource* to a **`long double`**. The **strtold** function stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character. The wide-character version of **strtold** is **wcstold**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +Each function converts the input string *`strSource`* to a **`long double`**. The **`strtold`** function stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character. The wide-character version of **`strtold`** is **`wcstold`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstold**|**strtold**|**strtold**|**wcstold**| -|**_tcstold_l**|**_strtold_l**|**_strtold_l**|**_wcstold_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstold` | **`strtold`** | **`strtold`** | **`wcstold`** | +| `_tcstold_l` | **`_strtold_l`** | **`_strtold_l`** | **`_wcstold_l`** | -The **LC_NUMERIC** category setting of the current locale determines the recognition of the radix character in *strSource*. For more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions without the **_l** suffix use the current locale; **_strtold_l** and **_wcstold_l** are identical to **_strtold** and **_wcstold** except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines the recognition of the radix character in *`strSource`*. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions without the `_l` suffix use the current locale; **`_strtold_l`** and **`_wcstold_l`** are identical to **`_strtold`** and **`_wcstold`** except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtold** expects *strSource* to point to a string of the following form: +**`strtold`** expects *`strSource`* to point to a string of the following form: -[*whitespace*] [*sign*] [*digits*] [.*digits*] [ {**d** | **D** | **e** | **E**}[*sign*]*digits*] +> \[*`whitespace`*\]\[*`sign`*\]\[*`digits`*\]\[.*`digits`*\]\[{**`d`** | **`D`** | **`e`** | **`E`**}\[*`sign`*\]*`digits`*\] -A *whitespace* may consist of space and tab characters, which are ignored; *sign* is either plus (**+**) or minus (**-**); and *digits* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**d**, **D**, **e**, or **E**) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`sign`* is either plus (**`+`**) or minus (**`-`**); and *`digits`* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**`d`**, **`D`**, **`e`**, or **`E`**) and an optionally signed integer. If no exponent part or radix character appears, a radix character is assumed to follow the last digit in the string. The first character that doesn't fit this form stops the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtold**, **_strtold_l**|\| -|**wcstold**, **_wcstold_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtold`**, **`_strtold_l`** | \ | +| **`wcstold`**, **`_wcstold_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -120,15 +120,15 @@ string = 3.1415926535898This stopped it ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[localeconv](localeconv.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`localeconv`](localeconv.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md b/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md index 925f54ad33..0460b9509d 100644 --- a/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md +++ b/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtoll, _strtoll_l, wcstoll, _wcstoll_l" title: "strtoll, _strtoll_l, wcstoll, _wcstoll_l" ms.date: "4/2/2020" api_name: ["strtoll", "wcstoll", "_strtoll_l", "_wcstoll_l", "_o__strtoll_l", "_o__wcstoll_l", "_o_strtoll", "_o_wcstoll"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_strtoll_l", "_tcstoll_l", "_tcstoll", "_wcstoll_l", "strtoll", "wcstoll"] +f1_keywords: ["STDLIB/strtoll", "STDLIB/_strtoll_l", "CORECRT_WSTDLIB/wcstoll", "CORECRT_WSTDLIB/_wcstoll_l", "TCHAR/_tcstoll", "TCHAR/_tcstoll_l", "strtoll", "_strtoll_l", "wcstoll", "_wcstoll_l", "_tcstoll", "_tcstoll_l"] helpviewer_keywords: ["_tcstoll_l function", "_wcstoll_l function", "strtoll function", "wcstoll function", "_tcstoll function", "_strtoll_l function"] ms.assetid: e2d05dcf-d3b2-4291-9e60-dee77e540fd7 --- -# strtoll, _strtoll_l, wcstoll, _wcstoll_l +# `strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l` Converts a string to a **`long long`** value. @@ -43,68 +43,68 @@ long long _wcstoll_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtoll** returns the value that's represented in the string *strSource*, except when the representation would cause an overflow—in that case, it returns **LLONG_MAX** or **LLONG_MIN**. The function returns 0 if no conversion can be performed. **wcstoll** returns values analogously to **strtoll**. +**`strtoll`** returns the value that's represented in the string *`strSource`*, except when the representation would cause an overflow—in that case, it returns `LLONG_MAX` or `LLONG_MIN`. The function returns 0 if no conversion can be performed. **`wcstoll`** returns values analogously to **`strtoll`**. -**LLONG_MAX** and **LLONG_MIN** are defined in LIMITS.H. +`LLONG_MAX` and `LLONG_MIN` are defined in LIMITS.H. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **strtoll** function converts *strSource* to a **`long long`**. Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. **wcstoll** is a wide-character version of **strtoll**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +The **`strtoll`** function converts *`strSource`* to a **`long long`**. Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. **`wcstoll`** is a wide-character version of **`strtoll`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoll**|**strtoll**|**strtoll**|**wcstoll**| -|**_tcstoll_l**|**_strtoll_l**|**_strtoll_l**|**_wcstoll_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoll` | **`strtoll`** | **`strtoll`** | **`wcstoll`** | +| `_tcstoll_l` | **`_strtoll_l`** | **`_strtoll_l`** | **`_wcstoll_l`** | -The locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; **_strtoll_l** and **_wcstoll_l** are identical to the corresponding functions that don't have the suffix, except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; **`_strtoll_l`** and **`_wcstoll_l`** are identical to the corresponding functions that don't have the suffix, except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtoll** expects *strSource* to point to a string of the following form: +**`strtoll`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored; *digits* are one or more decimal digits; *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`digits`* are one or more decimal digits; *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoll**, **_strtoll_l**|\| -|**wcstoll**, **_wcstoll_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoll`**, **`_strtoll_l`** | \ | +| **`wcstoll`**, **`_wcstoll_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md b/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md index 94d5501004..bc63db4b83 100644 --- a/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md +++ b/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md @@ -1,16 +1,16 @@ --- description: "Learn more about: _strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l" title: "_strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l" -ms.date: "4/2/2020" +ms.date: 05/18/2022 api_name: ["_strtoui64", "_strtoui64_l", "_wcstoui64", "_wcstoui64_l", "_o__strtoui64", "_o__strtoui64_l", "_o__wcstoui64", "_o__wcstoui64_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wcstoui64_l", "strtoui64_l", "wcstoui64", "_wcstoui64", "_strtoui64_l", "strtoui64", "_strtoui64", "wcstoui64_l"] +f1_keywords: ["CRT_OPEN/_strtoui64", "CRT_OPEN/_strtoui64_l", "STDLIB/_strtoui64", "STDLIB/_strtoui64_l", "CORECRT_WSTDLIB/_wcstoui64", "CORECRT_WSTDLIB/_wcstoui64_l", "TCHAR/_tcstoui64", "TCHAR/_tcstoui64_l", "_strtoui64", "_strtoui64_l", "_wcstoui64", "_wcstoui64_l", "_tcstoui64", "_tcstoui64_l", "strtoui64", "strtoui64_l", "wcstoui64", "wcstoui64_l"] helpviewer_keywords: ["_strtoui64_l function", "_wcstoui64_l function", "string conversion, to integers", "wcstoui64_l function", "_strtoui64 function", "_wcstoui64 function", "wcstoui64 function", "strtoui64_l function", "strtoui64 function"] ms.assetid: 7fcb537e-4554-4ceb-a5b6-bc09244e72ef --- -# _strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l +# `_strtoui64`, `_wcstoui64`, `_strtoui64_l`, `_wcstoui64_l` Convert a string to an **`unsigned __int64`** value. @@ -33,7 +33,7 @@ unsigned __int64 _strtoui64_l( int base, _locale_t locale ); -unsigned __int64 _wcstoui64( +unsigned __int64 _wcstoui64_l( const wchar_t *strSource, wchar_t **endptr, int base, @@ -43,63 +43,63 @@ unsigned __int64 _wcstoui64( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to character that stops scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_strtoui64** returns the value represented in the string *strSource*, except when the representation would cause an overflow, in which case it returns **_UI64_MAX**. **_strtoui64** returns 0 if no conversion can be performed. +**`_strtoui64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns `_UI64_MAX`. **`_strtoui64`** returns 0 if no conversion can be performed. -**_UI64_MAX** is defined in LIMITS.H. +`_UI64_MAX` is defined in `LIMITS.H`. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information on return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_strtoui64** function converts *strSource* to an **`unsigned __int64`**. **_wcstoui64** is a wide-character version of **_strtoui64**; its *strSource* argument is a wide-character string. Otherwise these functions behave identically. +The **`_strtoui64`** function converts *`strSource`* to an **`unsigned __int64`**. **`_wcstoui64`** is a wide-character version of **`_strtoui64`**; its *`strSource`* argument is a wide-character string. Otherwise these functions behave identically. -Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character greater than or equal to *base*. +Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character greater than or equal to *`base`*. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoui64**|**_strtoui64**|**_strtoui64**|**_wstrtoui64**| -|**_tcstoui64_l**|**_strtoui64_l**|**_strtoui64_l**|**_wstrtoui64_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoui64` | **`_strtoui64`** | **`_strtoui64`** | **`_wcstoui64`** | +| `_tcstoui64_l` | **`_strtoui64_l`** | **`_strtoui64_l`** | **`_wcstoui64_l`** | -The current locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale](setlocale-wsetlocale.md). The functions without the _l suffix use the current locale; **_strtoui64_l** and **_wcstoui64_l** are identical to the corresponding functions without the **_l** suffix except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The current locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoui64_l`** and **`_wcstoui64_l`** are identical to the corresponding functions without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. -**_strtoui64** expects *strSource* to point to a string of the following form: +**`_strtoui64`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*`digits`* \| *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *strSource* are used to determine the base. If the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtoui64**|\| -|**_wcstoui64**|\ or \| -|**_strtoui64_l**|\| -|**_wcstoui64_l**|\ or \| +| Function | Required header | +|--|--| +| **`_strtoui64`** | `` | +| **`_wcstoui64`** | `` or `` | +| **`_strtoui64_l`** | `` | +| **`_wcstoui64_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -123,11 +123,11 @@ u = 18446744073709551615 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md b/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md index beef87e356..7584413c40 100644 --- a/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md +++ b/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md @@ -3,14 +3,13 @@ description: "Learn more about: strtoul, _strtoul_l, wcstoul, _wcstoul_l" title: "strtoul, _strtoul_l, wcstoul, _wcstoul_l" ms.date: "4/2/2020" api_name: ["_wcstoul_l", "_strtoul_l", "strtoul", "wcstoul", "_o__strtoul_l", "_o__wcstoul_l", "_o_strtoul", "_o_wcstoul"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strtoul", "_tcstoul", "wcstoul"] +f1_keywords: ["STDLIB/strtoul", "STDLIB/_strtoul_l", "CORECRT_WSTDLIB/wcstoul", "CORECRT_WSTDLIB/_wcstoul_l", "TCHAR/_tcstoul", "TCHAR/_tcstoul_l", "strtoul", "_strtoul_l", "wcstoul", "_wcstoul_l", "_tcstoul", "_tcstoul_l"] helpviewer_keywords: ["_wcstoul_l function", "_tcstoul function", "_strtoul_l function", "string conversion, to integers", "wcstoul function", "strtoul function", "wcstoul_l function", "strtoul_l function", "tcstoul function"] -ms.assetid: 38f2afe8-8178-4e0b-8bbe-d5c6ad66e3ab --- -# strtoul, _strtoul_l, wcstoul, _wcstoul_l +# `strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l` Convert strings to an unsigned long-integer value. @@ -43,71 +42,71 @@ unsigned long _wcstoul_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to character that stops scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**strtoul** returns the converted value, if any, or **ULONG_MAX** on overflow. **strtoul** returns 0 if no conversion can be performed. **wcstoul** returns values analogously to **strtoul**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. +**`strtoul`** returns the converted value, if any, or `ULONG_MAX` on overflow. **`strtoul`** returns 0 if no conversion can be performed. **`wcstoul`** returns values analogously to **`strtoul`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions converts the input string *strSource* to an **`unsigned long`**. +Each of these functions converts the input string *`strSource`* to an **`unsigned long`**. -**strtoul** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character greater than or equal to *base*. The **LC_NUMERIC** category setting of the locale determines recognition of the radix character in *strSource*; for more information, see [setlocale](setlocale-wsetlocale.md). **strtoul** and **wcstoul** use the current locale; **_strtoul_l** and **_wcstoul_l** are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoul`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating `NULL`, or it may be the first numeric character greater than or equal to *`base`*. The `LC_NUMERIC` category setting of the locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). **`strtoul`** and **`wcstoul`** use the current locale; **`_strtoul_l`** and **`_wcstoul_l`** are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. -**wcstoul** is a wide-character version of **strtoul**; its *strSource* argument is a wide-character string. Otherwise these functions behave identically. +**`wcstoul`** is a wide-character version of **`strtoul`**; its *`strSource`* argument is a wide-character string. Otherwise these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoul**|**strtoul**|**strtoul**|**wcstoul**| -|**_tcstoul_l**|**strtoul_l**|**_strtoul_l**|**_wcstoul_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoul` | **`strtoul`** | **`strtoul`** | **`wcstoul`** | +| `_tcstoul_l` | **`strtoul_l`** | **`_strtoul_l`** | **`_wcstoul_l`** | -**strtoul** expects *strSource* to point to a string of the following form: +**`strtoul`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> `[whitespace] [{+ | -}] [0 [{ x | X }]] [digits | letters]` -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *strSource* are used to determine the base. If the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. **strtoul** allows a plus (**+**) or minus (**-**) sign prefix; a leading minus sign indicates that the return value is negated. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters `a` through `z` (or `A` through `Z`). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is 0 and the second character isn't `x` or `X`, the string is interpreted as an octal integer. If the first character is '0' and the second character is `x` or `X`, the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters `a` through `z` (or `A` through `Z`) are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. **`strtoul`** allows a plus (**`+`**) or minus (**`-`**) sign prefix; a leading minus sign indicates that the return value is negated. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoul**|\| -|**wcstoul**|\ or \| -|**_strtoul_l**|\| -|**_wcstoul_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoul`** | `` | +| **`wcstoul`** | `` or `` | +| **`_strtoul_l`** | `` | +| **`_wcstoul_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md b/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md index 09adf3a924..58bde7c901 100644 --- a/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md +++ b/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtoull, _strtoull_l, wcstoull, _wcstoull_l" title: "strtoull, _strtoull_l, wcstoull, _wcstoull_l" ms.date: "4/2/2020" api_name: ["_strtoull_l", "_wcstoull_l", "strtoull", "wcstoull", "_o__strtoull_l", "_o__wcstoull_l", "_o_strtoull", "_o_wcstoull"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wcstoull_l", "_tcstoull", "_tcstoull_l", "wcstoull", "_strtoull_l", "strtoull"] +f1_keywords: ["STDLIB/strtoull", "STDLIB/_strtoull_l", "CORECRT_WSTDLIB/wcstoull", "CORECRT_WSTDLIB/_wcstoull_l", "TCHAR/_tcstoull", "TCHAR/_tcstoull_l", "strtoull", "_strtoull_l", "wcstoull", "_wcstoull_l", "_tcstoull", "_tcstoull_l"] helpviewer_keywords: ["strtoull function", "_tcstoull_l function", "_tcstoull function", "_wcstoull_l function", "_strtoull_l function", "wcstoull function"] ms.assetid: 36dac1cc-e901-40a0-8802-63562d6d01df --- -# strtoull, _strtoull_l, wcstoull, _wcstoull_l +# `strtoull`, `_strtoull_l`, `wcstoull`, `_wcstoull_l` Converts strings to an **`unsigned long long`** integer value. @@ -43,73 +43,73 @@ unsigned long long _wcstoull_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**strtoull** returns the converted value, if any, or **ULLONG_MAX** on overflow. **strtoull** returns 0 if no conversion can be performed. **wcstoull** returns values analogously to **strtoull**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. +**`strtoull`** returns the converted value, if any, or `ULLONG_MAX` on overflow. **`strtoull`** returns 0 if no conversion can be performed. **`wcstoull`** returns values analogously to **`strtoull`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions converts the input string *strSource* to an **`unsigned long long`** integer value. +Each of these functions converts the input string *`strSource`* to an **`unsigned long long`** integer value. -**strtoull** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. The setting of the **LC_NUMERIC** category of the locale determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). **strtoull** and **wcstoull** use the current locale; **_strtoull_l** and **_wcstoull_l** instead use the locale that's passed in but are identical otherwise. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoull`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. The setting of the `LC_NUMERIC` category of the locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`strtoull`** and **`wcstoull`** use the current locale; **`_strtoull_l`** and **`_wcstoull_l`** instead use the locale that's passed in but are identical otherwise. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**wcstoull** is a wide-character version of **strtoull** and its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +**`wcstoull`** is a wide-character version of **`strtoull`** and its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoull**|**strtoull**|**strtoull**|**wcstoull**| -|**_tcstoull_l**|**strtoull_l**|**_strtoull_l**|**_wcstoull_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoull` | **`strtoull`** | **`strtoull`** | **`wcstoull`** | +| `_tcstoull_l` | **`strtoull_l`** | **`_strtoull_l`** | **`_wcstoull_l`** | -**strtoull** expects *strSource* to point to a string of the following form: +**`strtoull`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. **strtoull** allows a plus sign (**+**) or minus sign (**-**) prefix; a leading minus sign indicates that the return value is negated. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. **`strtoull`** allows a plus sign (**`+`**) or minus sign (**`-`**) prefix; a leading minus sign indicates that the return value is negated. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoull**|\| -|**wcstoull**|\ or \| -|**_strtoull_l**|\| -|**_wcstoull_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoull`** | \ | +| **`wcstoull`** | \ or \ | +| **`_strtoull_l`** | \ | +| **`_wcstoull_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoll, _strtoll_l, wcstoll, _wcstoll_l](strtoll-strtoll-l-wcstoll-wcstoll-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l`](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md b/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md index 06c20c89c1..39b89feffc 100644 --- a/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md +++ b/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md @@ -6,11 +6,11 @@ api_name: ["_wcstoumax_l", "_strtoumax_l", "wcstoumax", "strtoumax"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstoumax", "_tcstoumax", "_strtoumax_l", "_wcstoumax_l", "_tcstoumax_l", "strtoumax"] +f1_keywords: ["INTTYPES/strtoumax", "INTTYPES/_strtoumax_l", "INTTYPES/wcstoumax", "INTTYPES/_wcstoumax_l", "TCHAR/_tcstoumax", "TCHAR/_tcstoumax_l", "strtoumax", "_strtoumax_l", "wcstoumax", "_wcstoumax_l", "_tcstoumax", "_tcstoumax_l"] helpviewer_keywords: ["_strtoumax_l function", "conversion functions", "wcstoumax function", "_wcstoumax_l function", "strtoumax function"] ms.assetid: 566769f9-495b-4508-b9c6-02217a578897 --- -# strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l +# `strtoumax`, `_strtoumax_l`, `wcstoumax`, `_wcstoumax_l` Converts strings to an integer value of the largest supported unsigned integer type. @@ -43,72 +43,69 @@ uintmax_t _wcstoumax_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**strtoumax** returns the converted value, if any, or **UINTMAX_MAX** on overflow. **strtoumax** returns 0 if no conversion can be performed. **wcstoumax** returns values analogously to **strtoumax**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. +**`strtoumax`** returns the converted value, if any, or `UINTMAX_MAX` on overflow. **`strtoumax`** returns 0 if no conversion can be performed. **`wcstoumax`** returns values analogously to **`strtoumax`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions converts the input string *strSource* to a **uintmax_t** integer value. +Each of these functions converts the input string *`strSource`* to a `uintmax_t` integer value. -**strtoumax** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. The **LC_NUMERIC** category setting of the locale determines the recognition of the radix character in *strSource*. For more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). **strtoumax** and **wcstoumax** use the current locale; **_strtoumax_l** and **_wcstoumax_l** are identical except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoumax`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. The `LC_NUMERIC` category setting of the locale determines the recognition of the radix character in *`strSource`*. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`strtoumax`** and **`wcstoumax`** use the current locale; **`_strtoumax_l`** and **`_wcstoumax_l`** are identical except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -The wide-character version of **strtoumax** is **wcstoumax**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +The wide-character version of **`strtoumax`** is **`wcstoumax`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoumax**|**strtoumax**|**strtoumax**|**wcstoumax**| -|**_tcstoumax_l**|**strtoumax_l**|**_strtoumax_l**|**_wcstoumax_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoumax` | **`strtoumax`** | **`strtoumax`** | **`wcstoumax`** | +| `_tcstoumax_l` | **`strtoumax_l`** | **`_strtoumax_l`** | **`_wcstoumax_l`** | -**strtoumax** expects *strSource* to point to a string of the following form: +**`strtoumax`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. **strtoumax** allows a plus sign (**+**) or minus sign (**-**) prefix; a leading minus sign indicates that the return value is the two’s complement of the absolute value of the converted string. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. **`strtoumax`** allows a plus sign (**`+`**) or minus sign (**`-`**) prefix; a leading minus sign indicates that the return value is the two's complement of the absolute value of the converted string. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoumax**|\| -|**wcstoumax**|\ or \| -|**_strtoumax_l**|\| -|**_wcstoumax_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoumax`**, **`wcstoumax`**, **`_strtoumax_l`**, **`_wcstoumax_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l](strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoll, _strtoll_l, wcstoll, _wcstoll_l](strtoll-strtoll-l-wcstoll-wcstoll-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtoimax`, `_strtoimax_l`, `wcstoimax`, `_wcstoimax_l`](strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l`](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md b/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md index aa6ec6677f..9f490cf61e 100644 --- a/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md +++ b/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, title: "_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l" ms.date: "4/2/2020" api_name: ["_strupr_s", "_strupr_s_l", "_mbsupr_s", "_wcsupr_s_l", "_mbsupr_s_l", "_wcsupr_s", "_o__mbsupr_s", "_o__mbsupr_s_l", "_o__strupr_s", "_o__strupr_s_l", "_o__wcsupr_s", "_o__wcsupr_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strupr_s", "mbsupr_s", "wcsupr_s", "_mbsupr_s_l", "mbsupr_s_l", "wcsupr_s_l", "_wcsupr_s", "_tcsupr_s_l", "_mbsupr_s", "_tcsupr_s", "strupr_s_l", "_wcsupr_s_l", "_strupr_s", "_strupr_s_l"] +f1_keywords: ["_strupr_s", "_strupr_s_l", "_mbsupr_s", "_mbsupr_s_l", "_wcsupr_s", "_wcsupr_s_l", "_tcsupr_s", "_tcsupr_s_l"] helpviewer_keywords: ["mbsupr_s_l function", "strupr_s_l function", "_wcsupr_s_l function", "_tcsupr_s_l function", "mbsupr_s function", "_wcsupr_s function", "uppercase, converting strings to", "tcsupr_s function", "string conversion [C++], case", "strupr_s function", "wcsupr_s_l function", "_mbsupr_s function", "_mbsupr_s_l function", "_strupr_s_l function", "tcsupr_s_l function", "strings [C++], case", "converting case, CRT functions", "_tcsupr_s function", "strings [C++], converting case", "_strupr_s function", "wcsupr_s function"] ms.assetid: 82d3a273-9f6f-4a26-9560-919d891e4581 --- -# _strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l +# `_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l` -Converts a string to uppercase, by using the current locale or a specified locale that's passed in. These versions of [_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a string to uppercase, by using the current locale or a specified locale that's passed in. These versions of [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsupr_s** and **_mbsupr_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsupr_s`** and **`_mbsupr_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -78,56 +78,56 @@ errno_t _mbsupr_s_l( ### Parameters -*str*
+*`str`*\ String to capitalize. -*numberOfElements*
+*`numberOfElements`*\ Size of the buffer. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful; a non-zero error code on failure. -These functions validate their parameters. If *str* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. If *numberOfElements* is less than the length of the string, the functions return **ERANGE** and set **errno** to **ERANGE**. +These functions validate their parameters. If *`str`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. If *`numberOfElements`* is less than the length of the string, the functions return `ERANGE` and set `errno` to `ERANGE`. ## Remarks -The **_strupr_s** function converts, in place, each lowercase letter in *str* to uppercase. **_wcsupr_s** is the wide-character version of **_strupr_s**. **_mbsupr_s** is the multi-byte character version of **_strupr_s**. +The **`_strupr_s`** function converts, in place, each lowercase letter in *`str`* to uppercase. **`_wcsupr_s`** is the wide-character version of **`_strupr_s`**. **`_mbsupr_s`** is the multi-byte character version of **`_strupr_s`**. -The conversion is determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale; the visions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The conversion is determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale; the visions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsupr_s**|**_strupr_s**|**_mbsupr_s**|**_wcsupr_s**| -|**_tcsupr_s_l**|**_strupr_s_l**|**_mbsupr_s_l**|**_wcsupr_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsupr_s` | **`_strupr_s`** | **`_mbsupr_s`** | **`_wcsupr_s`** | +| `_tcsupr_s_l` | **`_strupr_s_l`** | **`_mbsupr_s_l`** | **`_wcsupr_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strupr_s**, **_strupr_s_l**|\| -|**_wcsupr_s**, **_wcsupr_s_l**, **_mbsupr_s**, **_mbsupr_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_strupr_s`**, **`_strupr_s_l`** | \ | +| **`_wcsupr_s`**, **`_wcsupr_s_l`**, **`_mbsupr_s`**, **`_mbsupr_s_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) . +See the example for [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) . ## See also -[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)
+[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) diff --git a/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md b/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md index b4ba8693af..3e7ba39f46 100644 --- a/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md +++ b/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md @@ -3,19 +3,19 @@ description: "Learn more about: _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_ title: "_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr" ms.date: "4/2/2020" api_name: ["_mbsupr_l", "_mbsupr", "_strupr_l", "_wcsupr", "_wcsupr_l", "_strupr", "_o__mbsupr", "_o__mbsupr_l", "_o__strupr", "_o__strupr_l", "_o__wcsupr", "_o__wcsupr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbsupr", "_ftcsupr", "mbsupr", "_tcsupr", "strupr_l", "_fstrupr", "_strupr", "mbsupr_l", "_wcsupr"] +f1_keywords: ["STRING/_strupr", "STRING/_strupr_l", "MBSTRING/_mbsupr", "MBSTRING/_mbsupr_l", "CORECRT_WSTRING/_wcsupr", "CORECRT_WSTRING/_wcsupr_l", "TCHAR/_tcsupr", "TCHAR/_tcsupr_l", "_strupr", "_strupr_l", "_mbsupr", "_mbsupr_l", "_wcsupr", "_wcsupr_l", "_tcsupr", "_tcsupr_l", "_ftcsupr", "_fstrupr"] helpviewer_keywords: ["tcsupr_l function", "mbsupr function", "strupr function", "uppercase, converting strings to", "wcsupr function", "_wcsupr function", "string conversion [C++], case", "ftcsupr function", "_ftcsupr function", "_wcsupr_l function", "wcsupr_l function", "strings [C++], case", "tcsupr function", "_tcsupr_l function", "_fstrupr function", "_strupr_l function", "_mbsupr_l function", "converting case, CRT functions", "fstrupr function", "mbsupr_l function", "strupr_l function", "_strupr function", "_mbsupr function", "_tcsupr function", "strings [C++], converting case"] ms.assetid: caac8f16-c233-41b6-91ce-575ec7061b77 --- -# _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr +# `_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr` -Converts a string to uppercase. More secure versions of these functions are available; see [_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md). +Converts a string to uppercase. More secure versions of these functions are available; see [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md). > [!IMPORTANT] -> **_mbsupr** and **_mbsupr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsupr`** and **`_mbsupr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -72,51 +72,51 @@ unsigned char *_mbsupr_l( ### Parameters -*str*
+*`str`*\ String to capitalize. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns a pointer to the altered string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument. No return value is reserved to indicate an error. ## Remarks -The **_strupr** function converts, in place, each lowercase letter in *str* to uppercase. The conversion is determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_strupr`** function converts, in place, each lowercase letter in *`str`* to uppercase. The conversion is determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -**_wcsupr** and **_mbsupr** are wide-character and multibyte-character versions of **_strupr**. The argument and return value of **_wcsupr** are wide-character strings; those of **_mbsupr** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsupr`** and **`_mbsupr`** are wide-character and multibyte-character versions of **`_strupr`**. The argument and return value of **`_wcsupr`** are wide-character strings. The argument and return value of **`_mbsupr`** are multibyte-character strings. These three functions behave identically otherwise. -If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set **errno** to **EINVAL**. +If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set `errno` to `EINVAL`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsupr**|**_strupr**|**_mbsupr**|**_wcsupr**| -|**_tcsupr_l**|**_strupr_l**|**_mbsupr_l**|**_wcsupr_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsupr` | **`_strupr`** | **`_mbsupr`** | **`_wcsupr`** | +| `_tcsupr_l` | **`_strupr_l`** | **`_mbsupr_l`** | **`_wcsupr_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strupr**, **_strupr_l**|\| -|**_wcsupr**, **_wcsupr_l**|\ or \| -|**_mbsupr**, **_mbsupr_l**|\| +| Routine | Required header | +|---|---| +| **`_strupr`**, **`_strupr_l`** | \ | +| **`_wcsupr`**, **`_wcsupr_l`** | \ or \ | +| **`_mbsupr`**, **`_mbsupr_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_strlwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md). +See the example for [`_strlwr`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) diff --git a/docs/c-runtime-library/reference/strupr-wcsupr.md b/docs/c-runtime-library/reference/strupr-wcsupr.md index a299292679..1b25726e49 100644 --- a/docs/c-runtime-library/reference/strupr-wcsupr.md +++ b/docs/c-runtime-library/reference/strupr-wcsupr.md @@ -6,12 +6,12 @@ api_name: ["strupr", "wcsupr"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strupr", "wcsupr"] +f1_keywords: ["STRING/strupr", "CORECRT_WSTRING/wcsupr", "strupr", "wcsupr"] helpviewer_keywords: ["strupr function", "wcsupr function"] ms.assetid: 17dfe1cd-3b09-4702-9f89-2207f44953e6 --- -# strupr, wcsupr +# `strupr`, `wcsupr` -The Microsoft-specific function names `strupr` and `wcsupr` are deprecated aliases for the [_strupr and _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strupr` and `wcsupr` are deprecated aliases for the [`_strupr` and `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strupr and _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) or the security-enhanced [_strupr_s and _wcsupr_s](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strupr` and `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) or the security-enhanced [`_strupr_s` and `_wcsupr_s`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md b/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md index 6c1fcd5341..793aca693f 100644 --- a/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md +++ b/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l" title: "strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l" ms.date: "4/2/2020" api_name: ["strxfrm", "_wcsxfrm_l", "_strxfrm_l", "wcsxfrm", "_o__strxfrm_l", "_o__wcsxfrm_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strxfrm", "_tcsxfrm", "wcsxfrm"] +f1_keywords: ["STRING/strxfrm", "STRING/_strxfrm_l", "CORECRT_WSTRING/wcsxfrm", "CORECRT_WSTRING/_wcsxfrm_l", "TCHAR/_tcsxfrm", "TCHAR/_tcsxfrm_l", "strxfrm", "_strxfrm_l", "wcsxfrm", "_wcsxfrm_l", "_tcsxfrm", "_tcsxfrm_l"] helpviewer_keywords: ["strxfrm_l function", "_tcsxfrm function", "_strxfrm_l function", "strxfrm function", "wcsxfrm_l function", "wcsxfrm function", "string comparison [C++], transforming strings", "tcsxfrm function", "strings [C++], comparing locale", "_wcsxfrm_l function"] ms.assetid: 6ba8e1f6-4484-49aa-83b8-bc2373187d9e --- -# strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l +# `strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l` Transform a string based on locale-specific information. @@ -43,52 +43,52 @@ size_t wcsxfrm_l( ### Parameters -*strDest*
+*`strDest`*\ Destination string. -*strSource*
+*`strSource`*\ Source string. -*count*
-Maximum number of characters to place in *strDest*. +*`count`*\ +Maximum number of characters to place in *`strDest`*. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the length of the transformed string, not counting the terminating null character. If the return value is greater than or equal to *count*, the content of *strDest* is unpredictable. On an error, each function sets **errno** and returns **INT_MAX**. For an invalid character, **errno** is set to **EILSEQ**. +Returns the length of the transformed string, not counting the terminating null character. If the return value is greater than or equal to *`count`*, the content of *`strDest`* is unpredictable. On an error, each function sets `errno` and returns `INT_MAX`. For an invalid character, `errno` is set to `EILSEQ`. ## Remarks -The **strxfrm** function transforms the string pointed to by *strSource* into a new collated form that is stored in *strDest*. No more than *count* characters, including the null character, are transformed and placed into the resulting string. The transformation is made using the locale's **LC_COLLATE** category setting. For more information on **LC_COLLATE**, see [setlocale](setlocale-wsetlocale.md). **strxfrm** uses the current locale for its locale-dependent behavior; **_strxfrm_l** is identical except that it uses the locale passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`strxfrm`** function transforms the string pointed to by *`strSource`* into a new collated form that is stored in *`strDest`*. No more than *`count`* characters, including the null character, are transformed and placed into the resulting string. The transformation is made using the locale's `LC_COLLATE` category setting. For more information on `LC_COLLATE`, see [`setlocale`](setlocale-wsetlocale.md). **`strxfrm`** uses the current locale for its locale-dependent behavior; **`_strxfrm_l`** is identical except that it uses the locale passed in instead of the current locale. For more information, see [Locale](../locale.md). -After the transformation, a call to **strcmp** with the two transformed strings yields results identical to those of a call to **strcoll** applied to the original two strings. As with **strcoll** and **stricoll**, **strxfrm** automatically handles multibyte-character strings as appropriate. +After the transformation, a call to `strcmp` with the two transformed strings yields results identical to the results of a call to `strcoll` applied to the original two strings. As with `strcoll` and `stricoll`, **`strxfrm`** automatically handles multibyte-character strings as appropriate. -**wcsxfrm** is a wide-character version of **strxfrm**; the string arguments of **wcsxfrm** are wide-character pointers. For **wcsxfrm**, after the string transformation, a call to **wcscmp** with the two transformed strings yields results identical to those of a call to **wcscoll** applied to the original two strings. **wcsxfrm** and **strxfrm** behave identically otherwise. **wcsxfrm** uses the current locale for its locale-dependent behavior; **_wcsxfrm_l** uses the locale passed in instead of the current locale. +**`wcsxfrm`** is a wide-character version of **`strxfrm`**; the string arguments of **`wcsxfrm`** are wide-character pointers. For **`wcsxfrm`**, after the string transformation, a call to `wcscmp` with the two transformed strings yields results identical to the results of a call to `wcscoll` applied to the original two strings. **`wcsxfrm`** and **`strxfrm`** behave identically otherwise. **`wcsxfrm`** uses the current locale for its locale-dependent behavior; **`_wcsxfrm_l`** uses the locale passed in instead of the current locale. -These functions validate their parameters. If *strSource* is a null pointer, or *strDest* is a **NULL** pointer (unless count is zero), or if *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **INT_MAX**. +These functions validate their parameters. If *`strSource`* is a null pointer, or *`strDest`* is a `NULL` pointer (unless count is zero), or if *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `INT_MAX`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsxfrm**|**strxfrm**|**strxfrm**|**wcsxfrm**| -|**_tcsxfrm_l**|**_strxfrm_l**|**_strxfrm_l**|**_wcsxfrm_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsxfrm` | **`strxfrm`** | **`strxfrm`** | **`wcsxfrm`** | +| `_tcsxfrm_l` | **`_strxfrm_l`** | **`_strxfrm_l`** | **`_wcsxfrm_l`** | In the "C" locale, the order of the characters in the character set (ASCII character set) is the same as the lexicographic order of the characters. However, in other locales, the order of characters in the character set may differ from the lexicographic character order. For example, in certain European locales, the character 'a' (value 0x61) precedes the character '&\#x00E4;' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. -In locales for which the character set and the lexicographic character order differ, use **strxfrm** on the original strings and then **strcmp** on the resulting strings to produce a lexicographic string comparison according to the current locale's **LC_COLLATE** category setting. Thus, to compare two strings lexicographically in the above locale, use **strxfrm** on the original strings, then **strcmp** on the resulting strings. Alternately, you can use **strcoll** rather than **strcmp** on the original strings. +In locales for which the character set and the lexicographic character order differ, use **`strxfrm`** on the original strings and then `strcmp` on the resulting strings to produce a lexicographic string comparison according to the current locale's `LC_COLLATE` category setting. Thus, to compare two strings lexicographically in the above locale, use **`strxfrm`** on the original strings, then `strcmp` on the resulting strings. Alternately, you can use `strcoll` rather than `strcmp` on the original strings. -**strxfrm** is basically a wrapper around [LCMapString](/windows/win32/api/winnls/nf-winnls-lcmapstringw) with **LCMAP_SORTKEY**. +**`strxfrm`** is basically a wrapper around [`LCMapString`](/windows/win32/api/winnls/nf-winnls-lcmapstringw) with `LCMAP_SORTKEY`. -The value of the following expression is the size of the array needed to hold the **strxfrm** transformation of the source string: +The value of the following expression is the size of the array needed to hold the **`strxfrm`** transformation of the source string: `1 + strxfrm( NULL, string, 0 )` -In the "C" locale only, **strxfrm** is equivalent to the following: +In the "C" locale only, **`strxfrm`** is equivalent to the following function calls: ```C strncpy( _string1, _string2, _count ); @@ -97,22 +97,22 @@ return( strlen( _string1 ) ); ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strxfrm**|\| -|**wcsxfrm**|\ or \| -|**_strxfrm_l**|\| -|**_wcsxfrm_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strxfrm`** | \ | +| **`wcsxfrm`** | \ or \ | +| **`_strxfrm_l`** | \ | +| **`_wcsxfrm_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
+[Data conversion](../data-conversion.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) diff --git a/docs/c-runtime-library/reference/swab.md b/docs/c-runtime-library/reference/swab.md index 334aa10867..2eb748ef51 100644 --- a/docs/c-runtime-library/reference/swab.md +++ b/docs/c-runtime-library/reference/swab.md @@ -3,14 +3,14 @@ description: "Learn more about: _swab" title: "_swab" ms.date: "4/2/2020" api_name: ["_swab", "stdlib/_swab", "_o__swab"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_swab", "stdlib/_swab"] +f1_keywords: ["STDLIB/_swab", "_swab"] helpviewer_keywords: ["_swab function", "swapping bytes", "swab function", "bytes, swapping"] ms.assetid: 017142f2-050c-4f6a-8b49-6b094f58ec94 --- -# _swab +# `_swab` Swaps bytes. @@ -26,34 +26,34 @@ void _swab( ## Parameters -*src*
+*`src`*\ Data to be copied and swapped. -*dest*
+*`dest`*\ Storage location for swapped data. -*n*
+*`n`*\ Number of bytes to be copied and swapped. ## Return value -The **swab** function does not return a value. The function sets **errno** to **EINVAL** if either the *src* or *dest* pointer is null or *n* is less than zero, and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +The **`swab`** function doesn't return a value. The function sets `errno` to `EINVAL` if either the *`src`* or *`dest`* pointer is null or *`n`* is less than zero, and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this and other return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -If *n* is even, the **_swab** function copies *n* bytes from *src*, swaps each pair of adjacent bytes, and stores the result at *dest*. If *n* is odd, **_swab** copies and swaps the first *n*-1 bytes of *src*, and the final byte is not copied. The **_swab** function is typically used to prepare binary data for transfer to a machine that uses a different byte order. +If *`n`* is even, the **`_swab`** function copies *`n`* bytes from *`src`*, swaps each pair of adjacent bytes, and stores the result at *`dest`*. If *`n`* is odd, **`_swab`** copies and swaps the first *`n`*-1 bytes of *`src`*, and the final byte isn't copied. The **`_swab`** function is typically used to prepare binary data for transfer to a machine that uses a different byte order. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_swab**|C: \ C++: \ or \| +| Routine | Required header | +|---|---| +| **`_swab`** | C: \ C++: \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -84,4 +84,4 @@ After: BADCFEHGJILKNMPORQTSVUXWZY ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
+[Buffer manipulation](../buffer-manipulation.md) diff --git a/docs/c-runtime-library/reference/system-wsystem.md b/docs/c-runtime-library/reference/system-wsystem.md index 8d4972c5f8..7afde9d491 100644 --- a/docs/c-runtime-library/reference/system-wsystem.md +++ b/docs/c-runtime-library/reference/system-wsystem.md @@ -3,10 +3,10 @@ description: "Learn more about: system, _wsystem" title: "system, _wsystem" ms.date: "4/2/2020" api_name: ["system", "_wsystem", "_o__wsystem", "_o_system"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tsystem", "_wsystem"] +f1_keywords: ["PROCESS/system", "CORECRT_WPROCESS/_wsystem", "TCHAR/_tsystem", "system", "_wsystem", "_tsystem"] helpviewer_keywords: ["_wsystem function", "wsystem function", "tsystem function", "_tsystem function", "system function", "commands, executing", "command interpreter"] ms.assetid: 7d3df2b6-f742-49ce-bf52-012b0aee3df5 --- @@ -30,46 +30,46 @@ int _wsystem( ### Parameters -*`command`*
+*`command`*\ The command to be executed. -## Return Value +## Return value -If *`command`* is **`NULL`** and the command interpreter is found, returns a nonzero value. If the command interpreter is not found, returns 0 and sets **`errno`** to **`ENOENT`**. If *`command`* is not **`NULL`**, **`system`** returns the value that is returned by the command interpreter. It returns the value 0 only if the command interpreter returns the value 0. A return value of -1 indicates an error, and **`errno`** is set to one of the following values: +If *`command`* is `NULL` and the command interpreter is found, returns a nonzero value. If the command interpreter isn't found, returns 0 and sets `errno` to `ENOENT`. If *`command`* isn't `NULL`, **`system`** returns the value that is returned by the command interpreter. It returns the value 0 only if the command interpreter returns the value 0. A return value of -1 indicates an error, and `errno` is set to one of the following values: | Value | Description | |-|-| -| **`E2BIG`** | The argument list (which is system-dependent) is too big. | -| **`ENOENT`** | The command interpreter cannot be found. | -| **`ENOEXEC`** | The command-interpreter file cannot be executed because the format is not valid. | -| **`ENOMEM`** | Not enough memory is available to execute command; or available memory has been corrupted; or a non-valid block exists, which indicates that the process that's making the call was not allocated correctly. | +| `E2BIG` | The argument list (which is system-dependent) is too large. | +| `ENOENT` | The command interpreter can't be found. | +| `ENOEXEC` | The command-interpreter file can't be executed because the format isn't valid. | +| `ENOMEM` | Not enough memory is available to execute command; or available memory has been corrupted; or a non-valid block exists, which indicates that the calling process has been allocated incorrectly. | -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information about these return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`system`** function passes *`command`* to the command interpreter, which executes the string as an operating-system command. **`system`** uses the **`COMSPEC`** and **`PATH`** environment variables to locate the command-interpreter file CMD.exe. If *`command`* is **`NULL`**, the function just checks whether the command interpreter exists. +The **`system`** function passes *`command`* to the command interpreter, which executes the string as an operating-system command. **`system`** uses the `COMSPEC` and `PATH` environment variables to locate the command-interpreter file CMD.exe. If *`command`* is `NULL`, the function just checks whether the command interpreter exists. You must explicitly flush, by using [`fflush`](fflush.md) or [`_flushall`](flushall.md), or close any stream before you call **`system`**. **`_wsystem`** is a wide-character version of **`system`**; the *`command`* argument to **`_wsystem`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tsystem`**|**`system`**|**`system`**|**`_wsystem`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tsystem`** | **`system`** | **`system`** | **`_wsystem`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`system`**|`` or ``| -|**`_wsystem`**|`` or `` or ``| +| Routine | Required header | +|---|---| +| **`system`** | `` or `` | +| **`_wsystem`** | `` or `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -102,8 +102,8 @@ Line two. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)
-[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)
-[`_flushall`](flushall.md)
-[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md) diff --git a/docs/c-runtime-library/reference/tan-tanf-tanl.md b/docs/c-runtime-library/reference/tan-tanf-tanl.md index 368112080c..815d0b95a9 100644 --- a/docs/c-runtime-library/reference/tan-tanf-tanl.md +++ b/docs/c-runtime-library/reference/tan-tanf-tanl.md @@ -3,11 +3,11 @@ title: "tan, tanf, tanl" description: "API reference for tan, tanf, and tanl; which calculate the tangent of a floating-point value." ms.date: "1/15/2021" api_name: ["tan", "tanf", "tanl", "_o_tan", "_o_tanf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tan", "tanf", "_tanl", "tanl"] -helpviewer_keywords: ["tanl function", "_tanl function", "tan function", "calculating tangents", "tangent", "tanf function", "trigonometric functions"] +f1_keywords: ["CORECRT_MATH/tan", "CORECRT_MATH/tanf", "CORECRT_MATH/tanl", "tan", "tanf", "tanl"] +helpviewer_keywords: ["tanl function", "tan function", "calculating tangents", "tangent", "tanf function", "trigonometric functions"] ms.assetid: 36cc0ce8-9c80-4653-b354-ddb3b378b6bd --- # `tan`, `tanf`, `tanl` @@ -37,27 +37,27 @@ Angle in radians. The **`tan`** functions return the tangent of *`x`*. If *`x`* is greater than or equal to 263, or less than or equal to -263, a loss of significance in the result occurs. -|Input|SEH exception|**`Matherr`** exception| -|-----------|-------------------|-------------------------| -|`± QNAN`,`IND`|none|`_DOMAIN`| -|`± INF`|**INVALID**|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| ± INF | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`tan`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`tan`** always takes and returns **`double`**. -If you use the `` `tan()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `tan` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`tan`**, **`tanf`**, **`tanl`**|``|`` or ``| -|**`tan()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`tan`**, **`tanf`**, **`tanl`** | `` | `` or `` | +| **`tan`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -85,10 +85,10 @@ tan( 0.785398 ) = 1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md)\ -[`_CItan`](../../c-runtime-library/citan.md) +[`_CItan`](../citan.md) diff --git a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md index 759de42856..de71ee3178 100644 --- a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md +++ b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md @@ -3,11 +3,11 @@ title: "tanh, tanhf, tanhl" description: "API reference for tanh, tanhf, and tanhl; which calculate the hyperbolic tangent of a floating-point value." ms.date: "1/15/2021" api_name: ["tanh", "tanhf", "tanhl", "_o_tanh", "_o_tanhf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tanh", "tanhf", "tanhl", "_tanhl"] -helpviewer_keywords: ["tanhl function", "_tanhl function", "tanh function", "tanhf function", "trigonometric functions", "hyperbolic functions"] +f1_keywords: ["CORECRT_MATH/tanh", "CORECRT_MATH/tanhf", "CORECRT_MATH/tanhl", "tanh", "tanhf", "tanhl"] +helpviewer_keywords: ["tanhl function", "tanh function", "tanhf function", "trigonometric functions", "hyperbolic functions"] --- # `tanh`, `tanhf`, `tanhl` @@ -36,26 +36,26 @@ Angle in radians. The **`tanh`** functions return the hyperbolic tangent of *`x`*. There's no error return. -|Input|SEH exception|**`Matherr`** exception| -|-----------|-------------------|-------------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`tanh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`tanh`** always takes and returns **`double`**. -If you use the `` `tanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `tanh` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C)| -|-------------|---------------------|-| -|**`tanh`**, **`tanhf`**, **`tanhl`**|``|`` or ``| -|**`tanh()`** macro | `` || +| Routine | Required header (C) | Required header (C) | +|---|---|---| +| **`tanh`**, **`tanhf`**, **`tanhl`** | `` | `` or `` | +| **`tanh`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,7 +87,7 @@ tanh( 1.000000 ) = 0.761594 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ [`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ [`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ diff --git a/docs/c-runtime-library/reference/tell-telli64.md b/docs/c-runtime-library/reference/tell-telli64.md index 5b3bf23a8e..9e7cc0ff45 100644 --- a/docs/c-runtime-library/reference/tell-telli64.md +++ b/docs/c-runtime-library/reference/tell-telli64.md @@ -3,14 +3,14 @@ description: "Learn more about: _tell, _telli64" title: "_tell, _telli64" ms.date: "4/2/2020" api_name: ["_telli64", "_tell", "_o__tell", "_o__telli64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["telli64", "_telli64", "_tell"] +f1_keywords: ["CORECRT_IO/_tell", "CORECRT_IO/_telli64", "_tell", "_telli64"] helpviewer_keywords: ["tell function", "file pointers [C++], getting", "_tell function", "file pointers [C++]", "telli64 function", "_telli64 function"] ms.assetid: 1500e8f9-8fec-4253-9eec-ec66125dfc9b --- -# _tell, _telli64 +# `_tell`, `_telli64` Get the position of the file pointer. @@ -27,30 +27,30 @@ __int64 _telli64( ### Parameters -*handle*
+*`handle`*\ File descriptor referring to open file. -## Return Value +## Return value The current position of the file pointer. On devices incapable of seeking, the return value is undefined. -A return value of -1L indicates an error. If *handle* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EBADF** and return -1L. +A return value of -1L indicates an error. If *`handle`* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EBADF` and return -1L. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_tell** function gets the current position of the file pointer (if any) associated with the *handle* argument. The position is expressed as the number of bytes from the beginning of the file. For the **_telli64** function, this value is expressed as a 64-bit integer. +The **`_tell`** function gets the current position of the file pointer (if any) associated with the *`handle`* argument. The position is expressed as the number of bytes from the beginning of the file. For the **`_telli64`** function, this value is expressed as a 64-bit integer. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tell**, **_telli64**|\| +| Routine | Required header | +|---|---| +| **`_tell`**, **`_telli64`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,6 +100,6 @@ Current file position is: 20 ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[ftell, _ftelli64](ftell-ftelli64.md)
-[_lseek, _lseeki64](lseek-lseeki64.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`ftell`, `_ftelli64`](ftell-ftelli64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md) diff --git a/docs/c-runtime-library/reference/tell.md b/docs/c-runtime-library/reference/tell.md index 6b7f179c7f..3c48b55f02 100644 --- a/docs/c-runtime-library/reference/tell.md +++ b/docs/c-runtime-library/reference/tell.md @@ -6,12 +6,12 @@ api_name: ["tell"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tell"] +f1_keywords: ["CORECRT_IO/tell", "tell"] helpviewer_keywords: ["tell function"] ms.assetid: 3a92a40d-f472-4545-a493-f57c340ee798 --- -# tell +# `tell` -The Microsoft-specific function name `tell` is a deprecated alias for the [_tell](tell-telli64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `tell` is a deprecated alias for the [`_tell`](tell-telli64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tell](tell-telli64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tell`](tell-telli64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md b/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md index a91537e7de..296d21e43e 100644 --- a/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md +++ b/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md @@ -6,13 +6,13 @@ api_name: ["_wtempnam_dbg", "_tempnam_dbg"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wtempnam_dbg", "tempnam_dbg", "_tempnam_dbg", "_wtempnam_dbg"] +f1_keywords: ["CRTDBG/_tempnam_dbg", "CRTDBG/_wtempnam_dbg", "_tempnam_dbg", "_wtempnam_dbg"] helpviewer_keywords: ["file names [C++], creating temporary", "tempnam_dbg function", "temporary files, creating", "file names [C++], temporary", "wtempnam_dbg function", "_tempnam_dbg function", "_wtempnam_dbg function"] ms.assetid: e3760bb4-bb01-4808-b689-2c45af56a170 --- -# _tempnam_dbg, _wtempnam_dbg +# `_tempnam_dbg`, `_wtempnam_dbg` -Function versions of [_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) that use the debug version of **malloc**, **_malloc_dbg**. +Function versions of [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) that use the debug version of `malloc`, `_malloc_dbg`. ## Syntax @@ -35,50 +35,50 @@ wchar_t *_wtempnam_dbg( ### Parameters -*dir*
-The path used in the file name if there is no TMP environment variable, or if TMP is not a valid directory. +*`dir`*\ +The path used in the file name if there's no TMP environment variable, or if TMP isn't a valid directory. -*prefix*
-The string that will be pre-pended to names returned by **_tempnam**. +*`prefix`*\ +The string that will be pre-pended to names returned by `_tempnam`. -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to name of source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -Each function returns a pointer to the name generated or **NULL** if there is a failure. Failure can occur if there is an invalid directory name specified in the TMP environment variable and in the *dir* parameter. +Each function returns a pointer to the name generated or `NULL` if there's a failure. Failure can occur if there's an invalid directory name specified in the TMP environment variable and in the *`dir`* parameter. > [!NOTE] -> **free** (or **free_dbg**) does need to be called for pointers allocated by **_tempnam_dbg** and **_wtempnam_dbg**. +> `free` (or `free_dbg`) does need to be called for pointers allocated by **`_tempnam_dbg`** and **`_wtempnam_dbg`**. ## Remarks -The **_tempnam_dbg** and **_wtempnam_dbg** functions are identical to **_tempnam** and **_wtempnam** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc** and **_malloc_dbg**, to allocate memory if **NULL** is passed as the first parameter. For more information, see [_malloc_dbg](malloc-dbg.md). +The **`_tempnam_dbg`** and **`_wtempnam_dbg`** functions are identical to `_tempnam` and `_wtempnam` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc` and `_malloc_dbg`, to allocate memory if `NULL` is passed as the first parameter. For more information, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_tempnam** and **_wtempnam** are remapped to **_tempnam_dbg** and **_wtempnam_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_tempnam` and `_wtempnam` are remapped to **`_tempnam_dbg`** and **`_wtempnam_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttempnam_dbg**|**_tempnam_dbg**|**_tempnam_dbg**|**_wtempnam_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttempnam_dbg` | **`_tempnam_dbg`** | **`_tempnam_dbg`** | **`_wtempnam_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tempnam_dbg**, **_wtempnam_dbg**|\| +| Routine | Required header | +|---|---| +| **`_tempnam_dbg`**, **`_wtempnam_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ +[Stream I/O](../stream-i-o.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md b/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md index 663e24764b..10e1de817a 100644 --- a/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md +++ b/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md @@ -6,13 +6,13 @@ api_name: ["_wtempnam", "_wtmpnam", "tmpnam", "_tempnam"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wtempnam", "_wtmpnam", "wtmpnam", "tmpnam", "_wtempnam", "_tempnam"] +f1_keywords: ["STDIO/tmpnam", "STDIO/_tempnam", "CORECRT_WSTDIO/_wtmpnam", "CORECRT_WSTDIO/_wtempnam", "TCHAR/_ttmpnam", "TCHAR/_ttempnam", "tmpnam", "_tempnam", "_wtmpnam", "_wtempnam", "_ttmpnam", "_ttempnam"] helpviewer_keywords: ["wtempnam function", "file names [C++], creating temporary", "_tempnam function", "ttmpnam function", "tmpnam function", "tempnam function", "wtmpnam function", "temporary files, creating", "file names [C++], temporary", "_ttmpnam function", "_wtmpnam function", "_wtempnam function"] ms.assetid: 3ce75f0f-5e30-42a6-9791-8d7cbfe70fca --- -# _tempnam, _wtempnam, tmpnam, _wtmpnam +# `_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam` -Generate names you can use to create temporary files. More secure versions of some of these functions are available; see [tmpnam_s, _wtmpnam_s](tmpnam-s-wtmpnam-s.md). +Generate names you can use to create temporary files. More secure versions of some of these functions are available; see [`tmpnam_s`, `_wtmpnam_s`](tmpnam-s-wtmpnam-s.md). ## Syntax @@ -35,58 +35,58 @@ wchar_t *_wtmpnam( ### Parameters -*prefix*
-The string that will be pre-pended to names returned by **_tempnam**. +*`prefix`*\ +The string that's prepended to names returned by **`_tempnam`**. -*dir*
-The path used in the file name if there is no TMP environment variable, or if TMP is not a valid directory. +*`dir`*\ +The path used in the file name if there's no TMP environment variable, or if TMP isn't a valid directory. -*str*
-Pointer that will hold the generated name and will be identical to the name returned by the function. This is a convenient way to save the generated name. +*`str`*\ +Pointer that holds the generated name, identical to the name returned by the function. It's a convenient way to save the generated name. -## Return Value +## Return value -Each of these functions returns a pointer to the name generated or **NULL** if there is a failure. Failure can occur if you attempt more than **TMP_MAX** (see STDIO.H) calls with **tmpnam** or if you use **_tempnam** and there is an invalid directory name specified in the TMP environment variable and in the *dir* parameter. +Each of these functions returns a pointer to the name generated or `NULL` if there's a failure. Failure can occur if you attempt more than `TMP_MAX` (see STDIO.H) calls with **`tmpnam`** or if you use **`_tempnam`** and there's an invalid directory name specified in the `TMP` environment variable and in the *`dir`* parameter. > [!NOTE] -> The pointers returned by **tmpnam** and **_wtmpnam** point to internal static buffers. [free](free.md) should not be called to deallocate those pointers. **free** needs to be called for pointers allocated by **_tempnam** and **_wtempnam**. +> The pointers returned by **`tmpnam`** and **`_wtmpnam`** point to internal static buffers. [`free`](free.md) should not be called to deallocate those pointers. `free` needs to be called for pointers allocated by **`_tempnam`** and **`_wtempnam`**. ## Remarks -Each of these functions returns the name of a file that does not currently exist. **tmpnam** returns a name that's unique in the designated Windows temporary directory returned by [GetTempPathW](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). **\_tempnam** generates a unique name in a directory other than the designated one. Note than when a file name is pre-pended with a backslash and no path information, such as \fname21, this indicates that the name is valid for the current working directory. +Each of these functions returns the name of a file that doesn't currently exist. **`tmpnam`** returns a name that's unique in the designated Windows temporary directory returned by [`GetTempPathW`](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). **`_tempnam`** generates a unique name in a directory other than the designated one. When a file name is prepended with a backslash and no path information, such as `\fname21`, it indicates that the name is valid for the current working directory. -For **tmpnam**, you can store this generated file name in *str*. If *str* is **NULL**, then **tmpnam** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **tmpnam** consists of a program-generated file name and, after the first call to **tmpnam**, a file extension of sequential numbers in base 32 (.1-.vvu, when **TMP_MAX** in STDIO.H is 32,767). +For **`tmpnam`**, you can store this generated file name in *`str`*. If *`str`* is `NULL`, then **`tmpnam`** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **`tmpnam`** consists of a program-generated file name and, after the first call to **`tmpnam`**, a file extension of sequential numbers in base 32 (.1-.vvu, when `TMP_MAX` in STDIO.H is 32,767). -**_tempnam** will generate a unique file name for a directory chosen by the following rules: +**`_tempnam`** generates a unique file name for a directory chosen by the following rules: -- If the TMP environment variable is defined and set to a valid directory name, unique file names will be generated for the directory specified by TMP. +- If the TMP environment variable is defined and set to a valid directory name, unique file names are generated for the directory specified by TMP. -- If the TMP environment variable is not defined or if it is set to the name of a directory that does not exist, **_tempnam** will use the *dir* parameter as the path for which it will generate unique names. +- If the TMP environment variable isn't defined or if it's set to the name of a directory that doesn't exist, **`_tempnam`** uses the *`dir`* parameter as the path for which it generates unique names. -- If the TMP environment variable is not defined or if it is set to the name of a directory that does not exist, and if *dir* is either **NULL** or set to the name of a directory that does not exist, **_tempnam** will use the current working directory to generate unique names. Currently, if both TMP and *dir* specify names of directories that do not exist, the **_tempnam** function call will fail. +- If the TMP environment variable isn't defined or if it's set to the name of a directory that doesn't exist, and if *`dir`* is either `NULL` or set to the name of a directory that doesn't exist, **`_tempnam`** uses the current working directory to generate unique names. Currently, if both TMP and *`dir`* specify names of directories that don't exist, the **_tempnam** function call fails. -The name returned by **_tempnam** will be a concatenation of *prefix* and a sequential number, which will combine to create a unique file name for the specified directory. **_tempnam** generates file names that have no extension. **_tempnam** uses [malloc](malloc.md) to allocate space for the filename; the program is responsible for freeing this space when it is no longer needed. +The name returned by **`_tempnam`** is a concatenation of *`prefix`* and a sequential number, which combine to create a unique file name for the specified directory. **`_tempnam`** generates file names that have no extension. **`_tempnam`** uses [`malloc`](malloc.md) to allocate space for the filename; the program is responsible for freeing this space when it's no longer needed. -**_tempnam** and **tmpnam** automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **_wtempnam** is a wide-character version of **_tempnam**; the arguments and return value of **_wtempnam** are wide-character strings. **_wtempnam** and **_tempnam** behave identically except that **_wtempnam** does not handle multibyte-character strings. **_wtmpnam** is a wide-character version of **tmpnam**; the argument and return value of **_wtmpnam** are wide-character strings. **_wtmpnam** and **tmpnam** behave identically except that **_wtmpnam** does not handle multibyte-character strings. +**`_tempnam`** and **`tmpnam`** automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **`_wtempnam`** is a wide-character version of **`_tempnam`**; the arguments and return value of **`_wtempnam`** are wide-character strings. **`_wtempnam`** and **`_tempnam`** behave identically except that **`_wtempnam`** doesn't handle multibyte-character strings. **`_wtmpnam`** is a wide-character version of **`tmpnam`**; the argument and return value of **`_wtmpnam`** are wide-character strings. **`_wtmpnam`** and **`tmpnam`** behave identically except that **`_wtmpnam`** doesn't handle multibyte-character strings. -If **_DEBUG** and **_CRTDBG_MAP_ALLOC** are defined, **_tempnam** and **_wtempnam** are replaced by calls to [_tempnam_dbg and _wtempnam_dbg](tempnam-dbg-wtempnam-dbg.md). +If `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, **`_tempnam`** and **`_wtempnam`** are replaced by calls to [`_tempnam_dbg` and `_wtempnam_dbg`](tempnam-dbg-wtempnam-dbg.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam**|**tmpnam**|**tmpnam**|**_wtmpnam**| -|**_ttempnam**|**_tempnam**|**_tempnam**|**_wtempnam**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttmpnam` | **`tmpnam`** | **`tmpnam`** | **`_wtmpnam`** | +| `_ttempnam` | **`_tempnam`** | **`_tempnam`** | **`_wtempnam`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tempnam**|\| -|**_wtempnam**, **_wtmpnam**|\ or \| -|**tmpnam**|\| +| Routine | Required header | +|---|---| +| **`_tempnam`** | \ | +| **`_wtempnam`**, **`_wtmpnam`** | \ or \ | +| **`tmpnam`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -135,7 +135,7 @@ int main(void) printf("Could not remove TMP environment variable.\n"); } - // With TMP unset, we will use C:\tmp as the temporary directory. + // With TMP unset, we'll use C:\tmp as the temporary directory. // Create a temporary filename in C:\tmp with prefix "stq". if ((name3 = _tempnam("c:\\tmp", "stq")) != NULL) { printf("%s is safe to use as a temporary file.\n", name3); @@ -161,9 +161,9 @@ c:\tmp\stq3 is safe to use as a temporary file. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getmbcp](getmbcp.md)
-[malloc](malloc.md)
-[_setmbcp](setmbcp.md)
-[tmpfile](tmpfile.md)
-[tmpfile_s](tmpfile-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getmbcp`](getmbcp.md)\ +[`malloc`](malloc.md)\ +[`_setmbcp`](setmbcp.md)\ +[`tmpfile`](tmpfile.md)\ +[`tmpfile_s`](tmpfile-s.md) diff --git a/docs/c-runtime-library/reference/tempnam.md b/docs/c-runtime-library/reference/tempnam.md index 6584eeedf1..230f6c67c2 100644 --- a/docs/c-runtime-library/reference/tempnam.md +++ b/docs/c-runtime-library/reference/tempnam.md @@ -6,12 +6,12 @@ api_name: ["tempnam"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tempnam"] +f1_keywords: ["STDIO/tempnam", "tempnam"] helpviewer_keywords: ["tempnam function"] ms.assetid: 42446733-f131-470f-b4d0-96918becab11 --- -# tempnam +# `tempnam` -The Microsoft-implemented POSIX function name `tempnam` is a deprecated alias for the [_tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `tempnam` is a deprecated alias for the [`_tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/terminate-crt.md b/docs/c-runtime-library/reference/terminate-crt.md index 3b0796229f..cda2e499e5 100644 --- a/docs/c-runtime-library/reference/terminate-crt.md +++ b/docs/c-runtime-library/reference/terminate-crt.md @@ -3,16 +3,16 @@ description: "Learn more about: terminate (CRT)" title: "terminate (CRT)" ms.date: "4/2/2020" api_name: ["terminate", "_o_terminate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["terminate"] +f1_keywords: ["CORECRT_TERMINATE/terminate", "EH/terminate", "terminate"] helpviewer_keywords: ["terminate function", "exception handling, termination"] ms.assetid: 90e67402-08e9-4b2a-962c-66a8afd3ccb4 --- -# terminate (CRT) +# `terminate` (CRT) -Calls [abort](abort.md) or a function you specify using **set_terminate**. +Calls [`abort`](abort.md) or a function you specify using `set_terminate`. ## Syntax @@ -22,25 +22,25 @@ void terminate( void ); ## Remarks -The **terminate** function is used with C++ exception handling and is called in the following cases: +The **`terminate`** function is used with C++ exception handling and is called in the following cases: -- A matching catch handler cannot be found for a thrown C++ exception. +- A matching catch handler can't be found for a thrown C++ exception. - An exception is thrown by a destructor function during stack unwind. - The stack is corrupted after throwing an exception. -**terminate** calls [abort](abort.md) by default. You can change this default by writing your own termination function and calling **set_terminate** with the name of your function as its argument. **terminate** calls the last function given as an argument to **set_terminate**. For more information, see [Unhandled C++ Exceptions](../../cpp/unhandled-cpp-exceptions.md). +**`terminate`** calls [`abort`](abort.md) by default. You can change this default by writing your own termination function and calling `set_terminate` with the name of your function as its argument. **`terminate`** calls the last function given as an argument to `set_terminate`. For more information, see [Unhandled C++ Exceptions](../../cpp/unhandled-cpp-exceptions.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**terminate**|\| +| Routine | Required header | +|---|---| +| **`terminate`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -90,9 +90,9 @@ term_func() was called by terminate(). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[_set_se_translator](set-se-translator.md)
-[set_terminate](set-terminate-crt.md)
-[set_unexpected](set-unexpected-crt.md)
-[unexpected](unexpected-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`_set_se_translator`](set-se-translator.md)\ +[`set_terminate`](set-terminate-crt.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md index e2a68366dd..eb9595efd4 100644 --- a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md +++ b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md @@ -3,14 +3,14 @@ title: "tgamma, tgammaf, tgammal" description: "API reference for tgamma, tgammaf, and tgammal; which determine the gamma function of the specified value." ms.date: "9/1/2020" api_name: ["tgamma", "tgammaf", "tgammal", "_o_tgamma", "_o_tgammaf", "_o_tgammal"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tgamma", "tgammaf", "tgammal", "math/tgamma", "math/tgammaf", "math/tgammal"] +f1_keywords: ["CORECRT_MATH/tgamma", "CORECRT_MATH/tgammaf", "CORECRT_MATH/tgammal", "tgamma", "tgammaf", "tgammal"] helpviewer_keywords: ["tgamma function", "tgammaf function", "tgammal function"] ms.assetid: f1bd2681-8af2-48a9-919d-5358fd068acd --- -# tgamma, tgammaf, tgammal +# `tgamma`, `tgammaf`, `tgammal` Determines the gamma function of the specified value. @@ -42,49 +42,49 @@ long double tgamma( ### Parameters -*x*\ +*`x`*\ The value to find the gamma of. -## Return Value +## Return value -If successful, returns the gamma of *x*. +If successful, returns the gamma of *`x`*. -A range error may occur if the magnitude of *x* is too large or too small for the data type. A domain error or range error may occur if *x* <= 0. +A range error may occur if the magnitude of *`x`* is too large or too small for the data type. A domain error or range error may occur if *`x`* <= 0. -|Issue|Return| -|-----------|------------| -|x = ±0|±INFINITY| -|x = negative integer|NaN| -|x = -INFINITY|NaN| -|x = +INFINITY|+INFINITY| -|x = NaN|NaN| -|domain error|NaN| -|pole error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| -|overflow range error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| -|underflow range error|the correct value, after rounding.| +| Issue | Return | +|---|---| +| *`x`* = ±0 | ±INFINITY | +| *`x`* = negative integer | NaN | +| *`x`* = -INFINITY | NaN | +| *`x`* = +INFINITY | +INFINITY | +| *`x`* = NaN | NaN | +| domain error | NaN | +| pole error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| overflow range error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| underflow range error | the correct value, after rounding. | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **tgamma** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **tgamma** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`tgamma`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`tgamma`** always takes and returns a **`double`**. -If you use the \ `tgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `tgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. If x is a natural number, this function returns the factorial of (x-1). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**tgamma**, **tgammaf**, **tgammal**|\|\| -|**tgamma** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`tgamma`**, **`tgammaf`**, **`tgammal`** | \ | \ | +| **`tgamma`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[lgamma, lgammaf, lgammal](lgamma-lgammaf-lgammal.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`lgamma`, `lgammaf`, `lgammal`](lgamma-lgammaf-lgammal.md) diff --git a/docs/c-runtime-library/reference/time-time32-time64.md b/docs/c-runtime-library/reference/time-time32-time64.md index 1eacd1fbe2..782e7aa835 100644 --- a/docs/c-runtime-library/reference/time-time32-time64.md +++ b/docs/c-runtime-library/reference/time-time32-time64.md @@ -6,7 +6,7 @@ api_name: ["time", "_time64", "_time32"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["time", "_time64", "time/time", "time/_time32", "time/_time64", "_time32"] +f1_keywords: ["TIME/time", "TIME/_time32", "TIME/_time64", "time", "_time32", "_time64"] helpviewer_keywords: ["time32 function", "_time32 function", "_time64 function", "time functions", "system time", "time64 function"] ms.assetid: 280e00f2-2b93-4ece-94cd-e048484c6cc7 --- @@ -24,26 +24,26 @@ __time64_t _time64( __time64_t *destTime ); ### Parameters -*`destTime`*
+*`destTime`*\ Pointer to the storage location for time. -## Return Value +## Return value -Returns the time as seconds elapsed since midnight, January 1, 1970, or -1 in the case of an error. +Returns the time as seconds elapsed since midnight, January 1, 1970, or -1 if there's an error. ## Remarks -The **`time`** function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Coordinated Universal Time (UTC), according to the system clock. The return value is stored in the location given by *`destTime`*. This parameter may be **`NULL`**, in which case the return value is not stored. +The **`time`** function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Coordinated Universal Time (UTC), according to the system clock. The return value is stored in the location given by *`destTime`*. This parameter may be `NULL`, in which case the return value isn't stored. -**`time`** is a wrapper for **`_time64`** and **`time_t`** is, by default, equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. This is not recommended because your application may fail after January 18, 2038; the use of this macro is not allowed on 64-bit platforms. +**`time`** is a wrapper for **`_time64`** and **`time_t`** is, by default, equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define `_USE_32BIT_TIME_T`. We don't recommend `_USE_32BIT_TIME_T`, because your application may fail after January 18, 2038; the use of this macro isn't allowed on 64-bit platforms. ## Requirements -|Routine|Required C header|Required C++ header| -|-------|------|---------------------| -|**`time`**, **`_time32`**, **`_time64`**|``|`` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`time`**, **`_time32`**, **`_time64`** | `` | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -199,12 +199,12 @@ Today is Friday, day 25 of April in the year 2003. ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[`asctime`, `_wasctime`](asctime-wasctime.md)
-[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)
-[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)
-[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)
-[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)
-[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)
-[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)
-[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md b/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md index cad2b00f40..e14e404ae6 100644 --- a/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md +++ b/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md @@ -3,14 +3,14 @@ description: "Learn more about: timespec_get, _timespec32_get, _timespec64_get" title: "timespec_get, _timespec32_get, _timespec64_get1" ms.date: "4/2/2020" api_name: ["timespec_get", "_timespec32_get", "_timespec64_get", "_o__timespec32_get", "_o__timespec64_get"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["timespec_get", "_timespec32_get", "_timespec64_get", "time/timespec_get", "time/_timespec32_get", "time/_timespec64_get", "timespec", "_timespec32", "_timespec64"] +f1_keywords: ["TIME/timespec_get", "TIME/_timespec32_get", "TIME/_timespec64_get", "TIME/timespec", "TIME/_timespec32", "TIME/_timespec64", "timespec_get", "_timespec32_get", "_timespec64_get", "timespec", "_timespec32", "_timespec64"] helpviewer_keywords: ["timespec_get function", "_timespec32_get function", "_timespec64_get function"] ms.assetid: ed757258-b4f2-4c1d-a91b-22ea6ffce4ab --- -# timespec_get, _timespec32_get, _timespec64_get +# `timespec_get`, `_timespec32_get`, `_timespec64_get` Sets the interval pointed to by the first argument to the current calendar time, based on the specified time base. @@ -33,45 +33,45 @@ int _timespec64_get( ### Parameters -*time_spec*
+*`time_spec`*\ Pointer to a struct that is set to the time in seconds and nanoseconds since the start of the epoch. -*base*
+*`base`*\ A non-zero implementation-specific value that specifies the time base. -## Return Value +## Return value -The value of *base* if successful, otherwise it returns zero. +The value of *`base`* if successful, otherwise it returns zero. ## Remarks -The **timespec_get** functions set the current time in the struct pointed to by the *time_spec* argument. All versions of this struct have two members, **tv_sec** and **tv_nsec**. The **tv_sec** value is set to the whole number of seconds and **tv_nsec** to the integral number of nanoseconds, rounded to the resolution of the system clock, since the start of the epoch specified by *base*. +The **`timespec_get`** functions set the current time in the struct pointed to by the *`time_spec`* argument. All versions of this struct have two members, `tv_sec` and `tv_nsec`. The `tv_sec` value is set to the whole number of seconds and `tv_nsec` to the integral number of nanoseconds, rounded to the resolution of the system clock, since the start of the epoch specified by *`base`*. **Microsoft Specific** -These functions support only **TIME_UTC** as the *base* value. This sets the *time_spec* value to the number of seconds and nanoseconds since the epoch start, Midnight, January 1, 1970, Coordinated Universal Time (UTC). In a **`struct`** **_timespec32**, **tv_sec** is a **__time32_t** value. In a **`struct`** **_timespec64**, **tv_sec** is a **__time64_t** value. In a **`struct`** **timespec**, **tv_sec** is a **time_t** type, which is 32 bits or 64 bits in length depending on whether the preprocessor macro _USE_32BIT_TIME_T is defined. The **timespec_get** function is an inline function that calls **_timespec32_get** if _USE_32BIT_TIME_T is defined; otherwise it calls **_timespec64_get**. +These functions support only `TIME_UTC` as the *`base`* value. `TIME_UTC` sets the *`time_spec`* value to the number of seconds and nanoseconds since the epoch start, Midnight, January 1, 1970, Coordinated Universal Time (UTC). In a `_timespec32`, `tv_sec` is a `__time32_t` value. In a `_timespec64`, `tv_sec` is a `__time64_t` value. In a `timespec`, `tv_sec` is a `time_t` type, which is 32 bits or 64 bits in length depending on whether the preprocessor macro _USE_32BIT_TIME_T is defined. The **`timespec_get`** function is an inline function that calls **`_timespec32_get`** if `_USE_32BIT_TIME_T` is defined; otherwise it calls **`_timespec64_get`**. **End Microsoft Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**timespec_get**, **_timespec32_get**, **_timespec64_get**|C: \, C++: \ or \| +| Routine | Required header | +|---|---| +| **`timespec_get`**, **`_timespec32_get`**, **`_timespec64_get`** | C: \, C++: \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/tmpfile-s.md b/docs/c-runtime-library/reference/tmpfile-s.md index 788969ad75..d71b77dcea 100644 --- a/docs/c-runtime-library/reference/tmpfile-s.md +++ b/docs/c-runtime-library/reference/tmpfile-s.md @@ -3,16 +3,16 @@ description: "Learn more about: tmpfile_s" title: "tmpfile_s" ms.date: "4/2/2020" api_name: ["tmpfile_s", "_o_tmpfile_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpfile_s"] +f1_keywords: ["STDIO/tmpfile_s", "tmpfile_s"] helpviewer_keywords: ["temporary files", "tmpfile_s function", "temporary files, creating"] ms.assetid: 50879c69-215e-425a-a2a3-8b5467121eae --- -# tmpfile_s +# `tmpfile_s` -Creates a temporary file. It is a version of [tmpfile](tmpfile.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates a temporary file. It's a version of [`tmpfile`](tmpfile.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,38 +24,38 @@ errno_t tmpfile_s( ### Parameters -*pFilePtr*
+*`pFilePtr`*\ The address of a pointer to store the address of the generated pointer to a stream. -## Return Value +## Return value Returns 0 if successful, an error code on failure. -### Error Conditions +### Error conditions -|*pFilePtr*|**Return Value**|**Contents of** *pFilePtr*| -|----------------|----------------------|---------------------------------| -|**NULL**|**EINVAL**|not changed| +| *`pFilePtr`* | Return value | Contents of *`pFilePtr`* | +|---|---|---| +| `NULL` | `EINVAL` | not changed | -If the above parameter validation error occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the return value is **EINVAL**. +If the above parameter validation error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and the return value is `EINVAL`. ## Remarks -The **tmpfile_s** function creates a temporary file and puts a pointer to that stream in the *pFilePtr* argument. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [tmpnam_s](tmpnam-s-wtmpnam-s.md) or [tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) in conjunction with [fopen](fopen-wfopen.md). +The **`tmpfile_s`** function creates a temporary file and puts a pointer to that stream in the *`pFilePtr`* argument. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [`tmpnam_s`](tmpnam-s-wtmpnam-s.md) or [`tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with [`fopen`](fopen-wfopen.md). -If the file cannot be opened, **tmpfile_s** writes **NULL** to the *pFilePtr* parameter. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when **_rmtmp** is called, assuming that the current working directory does not change. The temporary file is opened in **w+b** (binary read/write) mode. +If the file can't be opened, **`tmpfile_s`** writes `NULL` to the *`pFilePtr`* parameter. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when `_rmtmp` is called, assuming that the current working directory doesn't change. The temporary file is opened in **w+b** (binary read/write) mode. -Failure can occur if you attempt more than **TMP_MAX_S** (see STDIO.H) calls with **tmpfile_s**. +Failure can occur if you attempt more than `TMP_MAX_S` (see STDIO.H) calls with **`tmpfile_s`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpfile_s**|\| +| Routine | Required header | +|---|---| +| **`tmpfile_s`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -101,6 +101,6 @@ Temporary file 3 was created ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_rmtmp](rmtmp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_rmtmp`](rmtmp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/tmpfile.md b/docs/c-runtime-library/reference/tmpfile.md index 28b33f49bb..53f2b59e95 100644 --- a/docs/c-runtime-library/reference/tmpfile.md +++ b/docs/c-runtime-library/reference/tmpfile.md @@ -6,13 +6,13 @@ api_name: ["tmpfile"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpfile"] +f1_keywords: ["STDIO/tmpfile", "tmpfile"] helpviewer_keywords: ["temporary files", "tmpfile function", "temporary files, creating"] ms.assetid: c4a4dc24-70da-438d-ae4e-98352d88e375 --- -# tmpfile +# `tmpfile` -Creates a temporary file. This function is deprecated because a more secure version is available; see [tmpfile_s](tmpfile-s.md). +Creates a temporary file. This function is deprecated because a more secure version is available; see [`tmpfile_s`](tmpfile-s.md). ## Syntax @@ -20,25 +20,25 @@ Creates a temporary file. This function is deprecated because a more secure vers FILE *tmpfile( void ); ``` -## Return Value +## Return value -If successful, **tmpfile** returns a stream pointer. Otherwise, it returns a **NULL** pointer. +If successful, **`tmpfile`** returns a stream pointer. Otherwise, it returns a `NULL` pointer. ## Remarks -The **tmpfile** function creates a temporary file and returns a pointer to that stream. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [tmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) or [tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) in conjunction with [fopen](fopen-wfopen.md). +The **`tmpfile`** function creates a temporary file and returns a pointer to that stream. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [`tmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) or [`tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with [`fopen`](fopen-wfopen.md). -If the file cannot be opened, **tmpfile** returns a **NULL** pointer. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when **_rmtmp** is called, assuming that the current working directory does not change. The temporary file is opened in **w+b** (binary read/write) mode. +If the file can't be opened, **`tmpfile`** returns a `NULL` pointer. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when `_rmtmp` is called, assuming that the current working directory doesn't change. The temporary file is opened in **w+b** (binary read/write) mode. -Failure can occur if you attempt more than TMP_MAX (see STDIO.H) calls with **tmpfile**. +Failure can occur if you attempt more than TMP_MAX (see STDIO.H) calls with **`tmpfile`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpfile**|\| +| Routine | Required header | +|---|---| +| **`tmpfile`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -81,6 +81,6 @@ Temporary file 3 was created ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_rmtmp](rmtmp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_rmtmp`](rmtmp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md index 0d97268951..bb547ff8fe 100644 --- a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md +++ b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md @@ -3,16 +3,16 @@ description: "Learn more about: tmpnam_s, _wtmpnam_s" title: "tmpnam_s, _wtmpnam_s" ms.date: "4/2/2020" api_name: ["tmpnam_s", "_wtmpnam_s", "_o__wtmpnam_s", "_o_tmpnam_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpnam_s", "_wtmpnam_s", "L_tmpnam_s"] +f1_keywords: ["STDIO/tmpnam_s", "CORECRT_WSTDIO/_wtmpnam_s", "TCHAR/_ttmpnam_s", "STDIO/L_tmpnam_s", "tmpnam_s", "_wtmpnam_s", "_ttmpnam_s", "L_tmpnam_s"] helpviewer_keywords: ["tmpnam_s function", "file names [C++], creating temporary", "_wtmpnam_s function", "L_tmpnam_s constant", "temporary files, creating", "file names [C++], temporary", "wtmpnam_s function"] ms.assetid: e70d76dc-49f5-4aee-bfa2-f1baa2bcd29f --- -# tmpnam_s, _wtmpnam_s +# `tmpnam_s`, `_wtmpnam_s` -Generate names you can use to create temporary files. These are versions of [tmpnam and _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Generate names you can use to create temporary files. These functions are versions of [`tmpnam` and `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,51 +37,51 @@ errno_t _wtmpnam_s( ### Parameters -*str*
-Pointer that will hold the generated name. +*`str`*\ +[out] Pointer that holds the generated name. -*sizeInChars*
-The size of the buffer in characters. +*`sizeInChars`*\ +[in] The size of the buffer in characters. -## Return Value +## Return value Both of these functions return 0 if successful or an error number on failure. -### Error Conditions +### Error conditions -| *str* | *sizeInChars* | **Return Value** | **Contents of** *str* | +| *`str`* | *`sizeInChars`* | Return value | Contents of *`str`* | |--|--|--|--| -| **NULL** | any | **EINVAL** | not modified | -| not **NULL** (points to valid memory) | too short | **ERANGE** | not modified | +| `NULL` | any | `EINVAL` | not modified | +| not `NULL` (points to valid memory) | too short | `ERANGE` | not modified | -If *str* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EINVAL**. +If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -Each of these functions returns the name of a file that does not currently exist. **tmpnam_s** returns a name unique in the designated Windows temporary directory returned by [GetTempPathW](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). Note than when a file name is pre-pended with a backslash and no path information, such as \fname21, this indicates that the name is valid for the current working directory. +Each of these functions returns the name of a file that doesn't currently exist. **`tmpnam_s`** returns a name unique in the designated Windows temporary directory returned by [`GetTempPathW`](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). When a file name is prepended with a backslash and no path information, such as `\fname21`, it indicates that the name is valid for the current working directory. -For **tmpnam_s**, you can store this generated file name in *str*. The maximum length of a string returned by **tmpnam_s** is **L_tmpnam_s**, defined in STDIO.H. If *str* is **NULL**, then **tmpnam_s** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **tmpnam_s** consists of a program-generated file name and, after the first call to **tmpnam_s**, a file extension of sequential numbers in base 32 (.1-.1vvvvvu, when **TMP_MAX_S** in STDIO.H is **INT_MAX**). +For **`tmpnam_s`**, you can store this generated file name in *`str`*. The maximum length of a string returned by **`tmpnam_s`** is `L_tmpnam_s`, defined in STDIO.H. If *`str`* is `NULL`, then **`tmpnam_s`** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **`tmpnam_s`** consists of a program-generated file name and, after the first call to **`tmpnam_s`**, a file extension of sequential numbers in base 32 (.1-.1vvvvvu, when `TMP_MAX_S` in STDIO.H is `INT_MAX`). -**tmpnam_s** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **_wtmpnam_s** is a wide-character version of **tmpnam_s**; the argument and return value of **_wtmpnam_s** are wide-character strings. **_wtmpnam_s** and **tmpnam_s** behave identically except that **_wtmpnam_s** does not handle multibyte-character strings. +**`tmpnam_s`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **`_wtmpnam_s`** is a wide-character version of **`tmpnam_s`**; the argument and return value of **`_wtmpnam_s`** are wide-character strings. **`_wtmpnam_s`** and **`tmpnam_s`** behave identically except that **`_wtmpnam_s`** doesn't handle multibyte-character strings. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam_s**|**tmpnam_s**|**tmpnam_s**|**_wtmpnam_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttmpnam_s` | **`tmpnam_s`** | **`tmpnam_s`** | **`_wtmpnam_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpnam_s**|\| -|**_wtmpnam_s**|\ or \| +| Routine | Required header | +|---|---| +| **`tmpnam_s`** | \ | +| **`_wtmpnam_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -136,8 +136,8 @@ C:\Users\LocalUser\AppData\Local\Temp\u19q8.e is safe to use as a temporary file ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getmbcp](getmbcp.md)
-[malloc](malloc.md)
-[_setmbcp](setmbcp.md)
-[tmpfile_s](tmpfile-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getmbcp`](getmbcp.md)\ +[`malloc`](malloc.md)\ +[`_setmbcp`](setmbcp.md)\ +[`tmpfile_s`](tmpfile-s.md) diff --git a/docs/c-runtime-library/reference/toascii-toascii.md b/docs/c-runtime-library/reference/toascii-toascii.md index 5a4197c3b7..590d1ddca7 100644 --- a/docs/c-runtime-library/reference/toascii-toascii.md +++ b/docs/c-runtime-library/reference/toascii-toascii.md @@ -6,11 +6,11 @@ api_name: ["__toascii"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__toascii", "toascii", "ctype/toascii", "ctype/__toascii"] +f1_keywords: ["CTYPE/toascii", "CTYPE/__toascii", "__toascii", "toascii"] helpviewer_keywords: ["toascii function", "string conversion, to ASCII characters", "__toascii function", "ASCII characters, converting to"] ms.assetid: a07c0608-b0e2-4da2-a20c-7b64d6a9b77c --- -# toascii, __toascii +# `toascii`, `__toascii` Converts characters to 7-bit ASCII by truncation. @@ -25,29 +25,29 @@ int __toascii( ### Parameters -*c*
+*`c`*\ Character to convert. -## Return Value +## Return value -**__toascii** converts the value of *c* to the 7-bit ASCII range and returns the result. There is no return value reserved to indicate an error. +**`__toascii`** converts the value of *`c`* to the 7-bit ASCII range and returns the result. There's no return value reserved to indicate an error. ## Remarks -The **__toascii** routine converts the given character to an ASCII character by truncating it to the low-order 7 bits. No other transformation is applied. +The **`__toascii`** routine converts the given character to an ASCII character by truncating it to the low-order 7 bits. No other transformation is applied. -The **__toascii** routine is defined as a macro unless the preprocessor macro _CTYPE_DISABLE_MACROS is defined. For backward compatibility, **toascii** is defined as a macro only when [`__STDC__`](../../preprocessor/predefined-macros.md) is not defined or is defined as 0; otherwise it is undefined. +The **`__toascii`** routine is defined as a macro unless the preprocessor macro `_CTYPE_DISABLE_MACROS` is defined. For backward compatibility, **`toascii`** is defined as a macro only when [`__STDC__`](../../preprocessor/predefined-macros.md) isn't defined or is defined as 0; otherwise it's undefined. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**toascii**, **__toascii**|C: \

C++: \ or \| +| Routine | Required header | +|---|---| +| **`toascii`**, **`__toascii`** | C: \

C++: \ or \ | -The **toascii** macro is a POSIX extension, and **__toascii** is a Microsoft-specific implementation of the POSIX extension. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`toascii`** macro is a POSIX extension, and **`__toascii`** is a Microsoft-specific implementation of the POSIX extension. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
+[Data conversion](../data-conversion.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md) diff --git a/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md b/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md index 03095cd028..1bdcdc5a05 100644 --- a/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md +++ b/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md @@ -3,14 +3,14 @@ description: "Learn more about: tolower, _tolower, towlower, _tolower_l, _towlow title: "tolower, _tolower, towlower, _tolower_l, _towlower_l" ms.date: "4/2/2020" api_name: ["_tolower_l", "towlower", "tolower", "_tolower", "_towlower_l", "_o__tolower", "_o__tolower_l", "_o__towlower_l", "_o_tolower", "_o_towlower"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_totlower", "tolower", "_tolower", "towlower"] +f1_keywords: ["CTYPE/tolower", "CTYPE/_tolower", "CTYPE/_tolower_l", "CORECRT_WCTYPE/towlower", "CORECRT_WCTYPE/_towlower_l", "TCHAR/_totlower", "TCHAR/_totlower_l", "tolower", "_tolower", "_tolower_l", "towlower", "_towlower_l", "_totlower", "_totlower_l"] helpviewer_keywords: ["tolower_l function", "_tolower_l function", "totlower function", "string conversion, to different characters", "lowercase, converting to", "tolower function", "string conversion, case", "towlower function", "_tolower function", "_totlower function", "towlower_l function", "case, converting", "characters, converting", "_towlower_l function"] ms.assetid: 86e0fc02-94ae-4472-9631-bf8e96f67b92 --- -# tolower, _tolower, towlower, _tolower_l, _towlower_l +# `tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l` Converts a character to lowercase. @@ -38,52 +38,52 @@ int _towlower_l( ### Parameters -*c*
+*`c`*\ Character to convert. -*locale*
+*`locale`*\ Locale to use for locale-specific translation. -## Return Value +## Return value -Each of these routines converts a copy of *c* to lower case if the conversion is possible, and returns the result. There is no return value reserved to indicate an error. +Each of these routines converts a copy of *`c`* to lower case if the conversion is possible, and returns the result. There's no return value reserved to indicate an error. ## Remarks -Each of these routines converts a given uppercase letter to a lowercase letter if it is possible and relevant. The case conversion of **towlower** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the **_l** suffix use the currently set locale. The versions of these functions that have the **_l** suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these routines converts a given uppercase letter to a lowercase letter if it's possible and relevant. The case conversion of **`towlower`** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the `_l` suffix use the currently set locale. The versions of these functions that have the `_l` suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). -In order for **_tolower** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [isupper](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. +In order for **`_tolower`** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) and [`isupper`](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_totlower**|**tolower**|**_mbctolower**|**towlower**| -|**_totlower_l**|**_tolower_l**|**_mbctolower_l**|**_towlower_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_totlower` | **`tolower`** | `_mbctolower` | **`towlower`** | +| `_totlower_l` | **`_tolower_l`** | `_mbctolower_l` | **`_towlower_l`** | > [!NOTE] -> **_tolower_l** and **_towlower_l** have no locale dependence and are not meant to be called directly. They are provided for internal use by **_totlower_l**. +> **`_tolower_l`** and **`_towlower_l`** have no locale dependence and are not meant to be called directly. They are provided for internal use by **`_totlower_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tolower**|\| -|**_tolower**|\| -|**towlower**|\ or \| +| Routine | Required header | +|---|---| +| **`tolower`** | \ | +| **`_tolower`** | \ | +| **`towlower`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [to Functions](../../c-runtime-library/to-functions.md). +See the example in [`to` functions](../to-functions.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[Data conversion](../data-conversion.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md b/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md index ee174af35d..0e89d73c47 100644 --- a/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md +++ b/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md @@ -3,14 +3,13 @@ description: "Learn more about: toupper, _toupper, towupper, _toupper_l, _towupp title: "toupper, _toupper, towupper, _toupper_l, _towupper_l" ms.date: "4/2/2020" api_name: ["_toupper_l", "towupper", "toupper", "_towupper_l", "_toupper", "_o__toupper", "_o__toupper_l", "_o__towupper_l", "_o_toupper", "_o_towupper"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["towupper", "_toupper", "_totupper", "toupper"] +f1_keywords: ["CTYPE/toupper", "CTYPE/_toupper", "CTYPE/_toupper_l", "CORECRT_WCTYPE/towupper", "CORECRT_WCTYPE/_towupper_l", "TCHAR/_totupper", "TCHAR/_totupper_l", "toupper", "_toupper", "_toupper_l", "towupper", "_towupper_l", "_totupper", "_totupper_l"] helpviewer_keywords: ["_toupper function", "towupper function", "uppercase, converting strings to", "totupper function", "string conversion, to different characters", "towupper_l function", "toupper_l function", "string conversion, case", "_toupper_l function", "_towupper_l function", "_totupper function", "case, converting", "characters, converting", "toupper function"] -ms.assetid: cdef1b0f-b19c-4d11-b7d2-cf6334c9b6cc --- -# toupper, _toupper, towupper, _toupper_l, _towupper_l +# `toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l` Convert character to uppercase. @@ -38,59 +37,55 @@ int _towupper_l( ### Parameters -*c*
+*`c`*\ Character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines converts a copy of *c*, if possible, and returns the result. +Each of these routines converts a copy of *`c`*, if possible, and returns the result. -If *c* is a wide character for which **iswlower** is nonzero and there is a corresponding wide character for which [iswupper](isupper-isupper-l-iswupper-iswupper-l.md) is nonzero, **towupper** returns the corresponding wide character; otherwise, **towupper** returns *c* unchanged. +If *`c`* is a wide character for which `iswlower` is nonzero and there's a corresponding wide character for which [`iswupper`](isupper-isupper-l-iswupper-iswupper-l.md) is nonzero, **`towupper`** returns the corresponding wide character; otherwise, **`towupper`** returns *`c`* unchanged. -There is no return value reserved to indicate an error. - -In order for **toupper** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [islower](islower-iswlower-islower-l-iswlower-l.md) must both return nonzero. +There's no return value reserved to indicate an error. ## Remarks -Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **towupper** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the **_l** suffix use the currently set locale. The versions of these functions with the **_l** suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). - -In order for **toupper** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [isupper](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. +Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **`towupper`** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the `_l` suffix use the currently set locale. The versions of these functions with the `_l` suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). -[Data Conversion Routines](../../c-runtime-library/data-conversion.md) +For **`toupper`** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) must return nonzero. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_totupper**|**toupper**|**_mbctoupper**|**towupper**| -|**_totupper_l**|**_toupper_l**|**_mbctoupper_l**|**_towupper_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_totupper` | **`toupper`** | **`_mbctoupper`** | **`towupper`** | +| `_totupper_l` | **`_toupper_l`** | **`_mbctoupper_l`** | **`_towupper_l`** | > [!NOTE] -> **_toupper_l** and **_towupper_l** have no locale dependence and are not meant to be called directly. They are provided for internal use by **_totupper_l**. +> **`_toupper_l`** and **`_towupper_l`** have no locale dependence and are not meant to be called directly. They are provided for internal use by **`_totupper_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**toupper**|\| -|**_toupper**|\| -|**towupper**|\ or \| +| Routine | Required header | +|---|---| +| **`toupper`** | \ | +| **`_toupper`** | \ | +| **`towupper`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [to Functions](../../c-runtime-library/to-functions.md). +See the example in [`to` functions](../to-functions.md). ## See also -[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/towctrans.md b/docs/c-runtime-library/reference/towctrans.md index 617720b5bb..6cf88abded 100644 --- a/docs/c-runtime-library/reference/towctrans.md +++ b/docs/c-runtime-library/reference/towctrans.md @@ -6,11 +6,11 @@ api_name: ["towctrans"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["towctrans"] +f1_keywords: ["WCTYPE/towctrans", "towctrans"] helpviewer_keywords: ["towctrans function"] ms.assetid: 1ed1e70d-7b31-490f-a7d9-42564b5924ca --- -# towctrans +# `towctrans` Transforms a character. @@ -25,32 +25,32 @@ wint_t towctrans( ### Parameters -*c*
+*`c`*\ The character you want to transform. -*category*
-An identifier that contains the return value of [wctrans](wctrans.md). +*`category`*\ +An identifier that contains the return value of [`wctrans`](wctrans.md). -## Return Value +## Return value -The character *c*, after **towctrans** used the transform rule in *category*. +The character *`c`*, after **`towctrans`** used the transform rule in *`category`*. ## Remarks -The value of *category* must have been returned by an earlier successful call to [wctrans](wctrans.md). +The value of *`category`* must have been returned by an earlier successful call to [`wctrans`](wctrans.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**towctrans**|\| +| Routine | Required header | +|---|---| +| **`towctrans`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See **wctrans** for a sample that uses **towctrans**. +See `wctrans` for a sample that uses **`towctrans`**. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
+[Data conversion](../data-conversion.md) diff --git a/docs/c-runtime-library/reference/trunc-truncf-truncl.md b/docs/c-runtime-library/reference/trunc-truncf-truncl.md index eddefce960..19c7bc0414 100644 --- a/docs/c-runtime-library/reference/trunc-truncf-truncl.md +++ b/docs/c-runtime-library/reference/trunc-truncf-truncl.md @@ -6,11 +6,11 @@ api_name: ["trunc", "truncf", "truncl"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["trunc", "truncf", "truncl", "math/trunc", "math/truncf", "math/truncl"] +f1_keywords: ["CORECRT_MATH/trunc", "CORECRT_MATH/truncf", "CORECRT_MATH/truncl", "math/trunc", "math/truncf", "math/truncl", "trunc", "truncf", "truncl"] helpviewer_keywords: ["trunc function", "truncf function", "truncl function"] ms.assetid: de2038ac-ac0b-483e-870c-e8992dcd4fd0 --- -# trunc, truncf, truncl +# `trunc`, `truncf`, `truncl` Determines the nearest integer that is less than or equal to the specified floating-point value. @@ -27,45 +27,45 @@ float trunc( float x ); //C++ only ### Parameters -*x*\ +*`x`*\ The value to truncate. -## Return Value +## Return value -If successful, returns an integer value of *x*, rounded towards zero. +If successful, the functions return an integer value of *`x`*, rounded towards zero. -Otherwise, may return one of the following: +Otherwise, the functions may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±INFINITY|x| -|*x* = ±0|x| -|*x* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = ±INFINITY | x | +| *`x`* = ±0 | x | +| *`x`* = NaN | NaN | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **trunc** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **trunc** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`trunc`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`trunc`** always takes and returns a **`double`**. -If you use the \ `trunc()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `trunc()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -Because the largest floating-point values are exact integers, this function will not overflow on its own. However, you may cause the function to overflow by returning a value into an integer type. +Because the largest floating-point values are exact integers, this function won't overflow on its own. However, you may cause the function to overflow by returning a value into an integer type. You can also round down by implicitly converting from floating-point to integral; however, doing so is limited to the values that can be stored in the target type. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**trunc**, **truncf**, **truncl**|\|\| -|**trunc** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`trunc`**, **`truncf`**, **`truncl`** | \ | \ | +| **`trunc`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[round, roundf, roundl](round-roundf-roundl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md) diff --git a/docs/c-runtime-library/reference/tzset.md b/docs/c-runtime-library/reference/tzset.md index 1dfc4e1b3a..23fcafc53d 100644 --- a/docs/c-runtime-library/reference/tzset.md +++ b/docs/c-runtime-library/reference/tzset.md @@ -3,14 +3,14 @@ description: "Learn more about: _tzset" title: "_tzset" ms.date: "4/2/2020" api_name: ["_tzset", "_o__tzset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tzset"] +f1_keywords: ["TIME/_tzset", "_tzset"] helpviewer_keywords: ["_tzset function", "time environment variables", "environment variables, setting time"] ms.assetid: 3f6ed537-b414-444d-b272-5dd377481930 --- -# _tzset +# `_tzset` Sets time environment variables. @@ -25,56 +25,56 @@ void _tzset( void ); ## Remarks -The **_tzset** function uses the current setting of the environment variable **TZ** to assign values to three global variables: **_daylight**, **_timezone**, and **_tzname**. These variables are used by the [_ftime](ftime-ftime32-ftime64.md) and [localtime](localtime-localtime32-localtime64.md) functions to make corrections from coordinated universal time (UTC) to local time, and by the [time](time-time32-time64.md) function to compute UTC from system time. Use the following syntax to set the **TZ** environment variable: +The **`_tzset`** function uses the current setting of the environment variable **`TZ`** to assign values to three global variables: `_daylight`, `_timezone`, and `_tzname`. These variables are used by the [`_ftime`](ftime-ftime32-ftime64.md) and [`localtime`](localtime-localtime32-localtime64.md) functions to make corrections from coordinated universal time (UTC) to local time, and by the [`time`](time-time32-time64.md) function to compute UTC from system time. Use the following syntax to set the **`TZ`** environment variable: -> **set TZ=**_tzn_ \[**+**|**-**]*hh*\[**:**_mm_\[**:**_ss_] ][*dzn*] +> **`set TZ=`***`tzn`* \[**`+`**|**`-`**]*`hh`*\[**`:`***`mm`*\[**:***`ss`*] ][*`dzn`*] - *tzn* \ + *`tzn`* \ Three-letter time-zone name, such as PST. You must specify the correct offset from local time to UTC. - *hh* \ + *`hh`* \ Difference in hours between UTC and local time. Sign (+) optional for positive values. - *mm* \ - Minutes. Separated from *hh* by a colon (**:**). + *`mm`* \ + Minutes. Separated from *`hh`* by a colon (**`:`**). - *ss* \ - Seconds. Separated from *mm* by a colon (**:**). + *`ss`* \ + Seconds. Separated from *`mm`* by a colon (**`:`**). - *dzn* \ - Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set **TZ** without a value for *dzn*. The C run-time library assumes the United States' rules for implementing the calculation of daylight saving time (DST). + *`dzn`* \ + Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set **`TZ`** without a value for *`dzn`*. The C run-time library assumes the United States' rules for implementing the calculation of daylight saving time (DST). > [!NOTE] > Take care in computing the sign of the time difference. Because the time difference is the offset from local time to UTC (rather than the reverse), its sign may be the opposite of what you might intuitively expect. For time zones ahead of UTC, the time difference is negative; for those behind UTC, the difference is positive. -For example, to set the **TZ** environment variable to correspond to the current time zone in Germany, enter the following on the command line: +For example, to set the **`TZ`** environment variable to correspond to the current time zone in Germany, enter this command on the command line: > **set TZ=GST-1GDT** -This command uses GST to indicate German standard time, assumes that UTC is one hour behind Germany (or in other words, that Germany is one hour ahead of UTC), and assumes that Germany observes daylight-saving time. +This command uses GST to indicate German standard time. It assumes that UTC is one hour behind Germany (or in other words, that Germany is one hour ahead of UTC). And, it assumes that Germany observes daylight-saving time. -If the **TZ** value is not set, **_tzset** attempts to use the time zone information specified by the operating system. In the Windows operating system, this information is specified in the Date/Time application in Control Panel. If **_tzset** cannot obtain this information, it uses PST8PDT by default, which signifies the Pacific Time zone. +If the **`TZ`** value isn't set, **`_tzset`** attempts to use the time zone information specified by the operating system. In the Windows operating system, this information is specified in the Date/Time application in Control Panel. If **`_tzset`** can't obtain this information, it uses PST8PDT by default, which signifies the Pacific Time zone. -Based on the **TZ** environment variable value, the following values are assigned to the global variables **_daylight**, **_timezone**, and **_tzname** when **_tzset** is called: +Based on the **`TZ`** environment variable value, the following values are assigned to the global variables `_daylight`, `_timezone`, and `_tzname` when **`_tzset`** is called: -|Global variable|Description|Default value| -|---------------------|-----------------|-------------------| -|**_daylight**|Nonzero value if a daylight-saving-time zone is specified in **TZ** setting; otherwise, 0.|1| -|**_timezone**|Difference in seconds between local time and UTC.|28800 (28800 seconds equals 8 hours)| -|**_tzname**[0]|String value of time-zone name from **TZ** environmental variable; empty if **TZ** has not been set.|PST| -|**_tzname**[1]|String value of daylight-saving-time zone; empty if daylight-saving-time zone is omitted from **TZ** environmental variable.|PDT| +| Global variable | Description | Default value | +|---|---|---| +| `_daylight` | Nonzero value if a daylight-saving-time zone is specified in **`TZ`** setting; otherwise, 0. | 1 | +| `_timezone` | Difference in seconds between local time and UTC. | 28800 (28,800 seconds equals 8 hours) | +| `_tzname[0]` | String value of time-zone name from **`TZ`** environmental variable; empty if **`TZ`** hasn't been set. | PST | +| `_tzname[1]` | String value of daylight-saving-time zone; empty if daylight-saving-time zone is omitted from **`TZ`** environmental variable. | PDT | -The default values shown in the preceding table for **_daylight** and the **_tzname** array correspond to "PST8PDT." If the DST zone is omitted from the **TZ** environmental variable, the value of **_daylight** is 0 and the [_ftime](ftime-ftime32-ftime64.md), [gmtime](gmtime-gmtime32-gmtime64.md), and [localtime](localtime-localtime32-localtime64.md) functions return 0 for their DST flags. +The default values shown in the preceding table for `_daylight` and the `_tzname` array correspond to "PST8PDT." If the DST zone is omitted from the **`TZ`** environmental variable, the value of `_daylight` is 0 and the [`_ftime`](ftime-ftime32-ftime64.md), [`gmtime`](gmtime-gmtime32-gmtime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions return 0 for their DST flags. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tzset**|\| +| Routine | Required header | +|---|---| +| **`_tzset`** | \ | -The **_tzset** function is Microsoft-specific. For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_tzset`** function is Microsoft-specific. For more information, see [Compatibility](../compatibility.md). ## Example @@ -113,10 +113,10 @@ _tzname[0] = Pacific Standard Time ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/umask-s.md b/docs/c-runtime-library/reference/umask-s.md index 3f00a2026f..04e1a094fa 100644 --- a/docs/c-runtime-library/reference/umask-s.md +++ b/docs/c-runtime-library/reference/umask-s.md @@ -1,74 +1,74 @@ --- description: "Learn more about: _umask_s" title: "_umask_s" -ms.date: "4/2/2020" +ms.date: 05/18/2022 api_name: ["_umask_s", "_o__umask_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unmask_s", "_umask_s"] +f1_keywords: ["CORECRT_IO/_umask_s", "_umask_s", "umask_s"] helpviewer_keywords: ["masks, file-permission-setting", "_umask_s function", "masks", "file permissions [C++]", "umask_s function", "files [C++], permission settings for"] ms.assetid: 70898f61-bf2b-4d8d-8291-0ccaa6d33145 --- -# _umask_s +# `_umask_s` -Sets the default file-permission mask. A version of [_umask](umask.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Sets the default file-permission mask. A version of [`_umask`](umask.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax ```C errno_t _umask_s( int mode, - int * pOldMode + int* pOldMode ); ``` ### Parameters -*mode*
+*`mode`*\ Default permission setting. -*pOldMode*
+*`pOldMode`*\ The previous value of the permission setting. -## Return Value +## Return value -Returns an error code if *mode* does not specify a valid mode or the *pOldMode* pointer is **NULL**. +Returns an error code if *`mode`* doesn't specify a valid mode or the *`pOldMode`* pointer is `NULL`. -### Error Conditions +### Error conditions -|*mode*|*pOldMode*|Return value|Contents of *pOldMode*| -|------------|----------------|----------------------|--------------------------------| -|any|**NULL**|**EINVAL**|not modified| -|invalid mode|any|**EINVAL**|not modified| +| *`mode`* | *`pOldMode`* | Return value | Contents of *`pOldMode`* | +|--|--|--|--| +| any | `NULL` | `EINVAL` | not modified | +| invalid mode | any | `EINVAL` | not modified | -If one of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_umask_s** returns **EINVAL** and sets **errno** to **EINVAL**. +If one of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_umask_s`** returns `EINVAL` and sets `errno` to `EINVAL`. ## Remarks -The **_umask_s** function sets the file-permission mask of the current process to the mode specified by *mode*. The file-permission mask modifies the permission setting of new files created by **_creat**, **_open**, or **_sopen**. If a bit in the mask is 1, the corresponding bit in the file's requested permission value is set to 0 (disallowed). If a bit in the mask is 0, the corresponding bit is left unchanged. The permission setting for a new file is not set until the file is closed for the first time. +The **`_umask_s`** function sets the file-permission mask of the current process to the mode specified by *`mode`*. The file-permission mask modifies the permission setting of new files created by **`_creat`**, **`_open`**, or **`_sopen`**. If a bit in the mask is 1, the corresponding bit in the file's requested permission value is set to 0 (disallowed). If a bit in the mask is 0, the corresponding bit is left unchanged. The permission setting for a new file isn't set until the file is closed for the first time. -The integer expression *pmode* contains one or both of the following manifest constants, defined in SYS\STAT.H: +The integer expression *`mode`* contains one or both of the following manifest constants, defined in `SYS\STAT.H`: -|*pmode*|Description| -|-|-| -|**_S_IWRITE**|Writing permitted.| -|**_S_IREAD**|Reading permitted.| -|**_S_IREAD** \| **_S_IWRITE**|Reading and writing permitted.| +| *`mode`* | Description | +|--|--| +| `_S_IWRITE` | Writing permitted. | +| `_S_IREAD` | Reading permitted. | +| **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they are joined with the bitwise-OR operator ( **|** ). If the *mode* argument is **_S_IREAD**, reading is not allowed (the file is write-only). If the *mode* argument is **_S_IWRITE**, writing is not allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. Note that with MS-DOS and the Windows operating systems, all files are readable; it is not possible to give write-only permission. Therefore, setting the read bit with **_umask_s** has no effect on the file's modes. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`mode`* argument is `_S_IREAD`, reading isn't allowed (the file is write-only). If the *`mode`* argument is `_S_IWRITE`, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask_s`** has no effect on the file's modes. -If *pmode* is not a combination of one of the manifest constants or incorporates an alternate set of constants, the function will simply ignore those. +If *`mode`* isn't a combination of one of the manifest constants or incorporates an alternate set of constants, the function ignores them. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_umask_s**|\ and \ and \| +| Function | Required header | +|--|--| +| **`_umask_s`** | `` and `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,10 +106,10 @@ Oldmask = 0x0000 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_open, _wopen](open-wopen.md)
-[_umask](umask.md)
+[File handling](../file-handling.md)\ +[Low-level I/O](../low-level-i-o.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_umask`](umask.md) diff --git a/docs/c-runtime-library/reference/umask.md b/docs/c-runtime-library/reference/umask.md index cb9daca746..015b0b81ea 100644 --- a/docs/c-runtime-library/reference/umask.md +++ b/docs/c-runtime-library/reference/umask.md @@ -3,16 +3,16 @@ title: "_umask" description: "API reference for _umask; which sets the default file-permission mask." ms.date: "4/2/2020" api_name: ["_umask", "_o__umask"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_umask"] +f1_keywords: ["CORECRT_IO/_umask", "_umask"] helpviewer_keywords: ["masks, file-permission-setting", "_umask function", "masks", "umask function", "file permissions [C++]", "files [C++], permission settings for"] ms.assetid: 5e9a13ba-5321-4536-8721-6afb6f4c8483 --- -# _umask +# `_umask` -Sets the default file-permission mask. See [_umask_s](umask-s.md) for a more secure version of this function." +Sets the default file-permission mask. For a more secure version of this function, see [`_umask_s`](umask-s.md) . ## Syntax @@ -22,42 +22,42 @@ int _umask( int pmode ); ### Parameters -*pmode*
+*`pmode`*\ Default permission setting. -## Return Value +## Return value -**_umask** returns the previous value of *pmode*. There's no error return. +**`_umask`** returns the previous value of *`pmode`*. There's no error return. ## Remarks -The **_umask** function sets the file-permission mask of the current process to the mode specified by *pmode*. The file-permission mask modifies the permission setting of new files created by **_creat**, **_open**, or **_sopen**. If a bit in the mask is 1, the corresponding bit in the file's requested permission value is set to 0 (disallowed). If a bit in the mask is 0, the corresponding bit is left unchanged. The permission setting for a new file is not set until the file is closed for the first time. +The **`_umask`** function sets the file-permission mask of the current process to the mode specified by *`pmode`*. The file-permission mask modifies the permission setting of new files created by **`_creat`**, **`_open`**, or **`_sopen`**. If a bit in the mask is 1, the corresponding bit in the file's requested permission value is set to 0 (disallowed). If a bit in the mask is 0, the corresponding bit is left unchanged. The permission setting for a new file isn't set until the file is closed for the first time. -The integer expression *pmode* contains one or both of the following manifest constants, defined in SYS\STAT.H: +The integer expression *`pmode`* contains one or both of the following manifest constants, defined in `SYS\STAT.H`: -|*pmode*|Description| -|-|-| -| **_S_IWRITE** | Writing permitted. | -| **_S_IREAD** | Reading permitted. | -| **_S_IREAD** | **_S_IWRITE** | Reading and writing permitted. | +| *`pmode`* | Description | +|--|--| +| `_S_IWRITE` | Writing permitted. | +| `_S_IREAD` | Reading permitted. | +| **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they are joined with the bitwise-OR operator ( **|** ). If the *pmode* argument is **_S_IREAD**, reading is not allowed (the file is write-only). If the *pmode* argument is **_S_IWRITE**, writing is not allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. Note that with MS-DOS and the Windows operating systems, all files are readable; it is not possible to give write-only permission. Therefore, setting the read bit with **_umask** has no effect on the file's modes. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`pmode`* argument is `_S_IREAD`, reading isn't allowed (the file is write-only). If the *`pmode`* argument is `_S_IWRITE`, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask`** has no effect on the file's modes. -If *pmode* is not a combination of one of the manifest constants or incorporates an alternate set of constants, the function will simply ignore those. +If *`pmode`* isn't a combination of one of the manifest constants or incorporates an alternate set of constants, the function ignores them. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_umask**|\, \, \| +| Function | Required header | +|--|--| +| **`_umask`** | ``, ``, `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -90,9 +90,9 @@ Oldmask = 0x0000 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
-[_open, _wopen](open-wopen.md)
+[File handling](../file-handling.md)\ +[Low-level I/O](../low-level-i-o.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ +[`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/uncaught-exception.md b/docs/c-runtime-library/reference/uncaught-exception.md index 00c1d2c8da..52c7a6c349 100644 --- a/docs/c-runtime-library/reference/uncaught-exception.md +++ b/docs/c-runtime-library/reference/uncaught-exception.md @@ -3,25 +3,24 @@ description: "Learn more about: __uncaught_exception" title: "__uncaught_exception" ms.date: "1/14/2021" api_name: ["__uncaught_exception"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__uncaught_exception"] +f1_keywords: ["EH/__uncaught_exception"] helpviewer_keywords: ["__uncaught_exception"] ms.assetid: 4d9b75c6-c9c7-4876-b761-ea9ab1925e96 --- -# __uncaught_exception +# `__uncaught_exception` -Indicates whether one or more exceptions have been thrown, but have not yet been handled by the corresponding **`catch`** block of a [try-catch](../../cpp/try-throw-and-catch-statements-cpp.md) statement. +Indicates whether one or more exceptions have been thrown, but haven't yet been handled by the corresponding **`catch`** block of a [try-catch](../../cpp/try-throw-and-catch-statements-cpp.md) statement. ## Syntax ```cpp -bool __uncaught_exception( - ); +bool __uncaught_exception(); ``` -## Return Value +## Return value **`true`** from the time an exception is thrown in a **`try`** block until the matching **`catch`** block is initialized; otherwise, **`false`**. @@ -29,10 +28,10 @@ bool __uncaught_exception( ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__uncaught_exception|eh.h| +| Routine | Required header | +|---|---| +| **`__uncaught_exception`** | `` | ## See also -[try, throw, and catch Statements (C++)](../../cpp/try-throw-and-catch-statements-cpp.md)
+[try, throw, and catch Statements (C++)](../../cpp/try-throw-and-catch-statements-cpp.md) diff --git a/docs/c-runtime-library/reference/unexpected-crt.md b/docs/c-runtime-library/reference/unexpected-crt.md index 0127f10759..a1fabd706f 100644 --- a/docs/c-runtime-library/reference/unexpected-crt.md +++ b/docs/c-runtime-library/reference/unexpected-crt.md @@ -3,10 +3,10 @@ description: "Learn more about: unexpected (CRT)" title: "unexpected (CRT)" ms.date: "1/14/2021" api_name: ["unexpected"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unexpected"] +f1_keywords: ["EH/unexpected"] helpviewer_keywords: ["unexpected function"] ms.assetid: 2f873763-15ad-4556-a924-dcf28f2b52b4 --- @@ -26,17 +26,17 @@ The **`unexpected`** routine isn't used with the current implementation of C++ e ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`unexpected`**|``| +| Routine | Required header | +|---|---| +| **`unexpected`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[_set_se_translator](set-se-translator.md)
-[set_terminate](set-terminate-crt.md)
-[set_unexpected](set-unexpected-crt.md)
-[terminate](terminate-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`_set_se_translator`](set-se-translator.md)\ +[`set_terminate`](set-terminate-crt.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`terminate`](terminate-crt.md) diff --git a/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md b/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md index e50a89d868..eba0a2a049 100644 --- a/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md +++ b/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _ungetc_nolock, _ungetwc_nolock" title: "_ungetc_nolock, _ungetwc_nolock" +description: "Learn more about: _ungetc_nolock, _ungetwc_nolock" ms.date: "4/2/2020" api_name: ["_ungetwc_nolock", "_ungetc_nolock", "_o__ungetc_nolock", "_o__ungetwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungettc_nolock", "ungetwc_nolock", "ungetc_nolock", "_ungetc_nolock", "_ungetwc_nolock"] +f1_keywords: ["STDIO/_ungetc_nolock", "CORECRT_WSTDIO/_ungetwc_nolock", "TCHAR/_ungettc_nolock", "_ungetc_nolock", "_ungetwc_nolock", "_ungettc_nolock"] helpviewer_keywords: ["_ungettc_nolock function", "_ungetwc_nolock function", "characters, pushing back onto stream", "_ungetc_nolock function", "ungetwc_nolock function", "ungettc_nolock function", "ungetc_nolock function"] -ms.assetid: aa02d5c2-1be1-46d2-a8c4-b61269e9d465 --- -# _ungetc_nolock, _ungetwc_nolock +# `_ungetc_nolock`, `_ungetwc_nolock` -Pushes a character back onto the stream. +Pushes a character back onto the stream without locking. ## Syntax @@ -29,41 +28,41 @@ wint_t _ungetwc_nolock( ### Parameters -*c*
+*`c`*\ Character to be pushed. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If successful, each of these functions returns the character argument *c*. If *c* cannot be pushed back or if no character has been read, the input stream is unchanged and **_ungetc_nolock** returns **EOF**; **_ungetwc_nolock** returns **WEOF**. If *stream* is **NULL**, **EOF** or **WEOF** is returned and **errno** is set to **EINVAL**. +If successful, each of these functions returns the character argument *`c`*. If *`c`* can't be pushed back or if no character has been read, the input stream is unchanged and **`_ungetc_nolock`** returns `EOF`; **`_ungetwc_nolock`** returns `WEOF`. If *`stream`* is `NULL`, `EOF` or `WEOF` is returned, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -These functions are non-locking versions of **ungetc** and **ungetwc**. The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +These functions are non-locking versions of `ungetc` and `ungetwc`. The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc_nolock**|**_ungetc_nolock**|**_ungetc_nolock**|**_ungetwc_nolock**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettc_nolock` | **`_ungetc_nolock`** | **`_ungetc_nolock`** | **`_ungetwc_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ungetc_nolock**|\| -|**_ungetwc_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_ungetc_nolock`** | \ | +| **`_ungetwc_nolock`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/ungetc-ungetwc.md b/docs/c-runtime-library/reference/ungetc-ungetwc.md index dba46d89f7..fe97a8b26f 100644 --- a/docs/c-runtime-library/reference/ungetc-ungetwc.md +++ b/docs/c-runtime-library/reference/ungetc-ungetwc.md @@ -3,14 +3,14 @@ description: "Learn more about: ungetc, ungetwc" title: "ungetc, ungetwc" ms.date: "4/2/2020" api_name: ["ungetwc", "ungetc", "_o_ungetc", "_o_ungetwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungettc", "ungetwc", "ungetc"] +f1_keywords: ["STDIO/ungetc", "CORECRT_WSTDIO/ungetwc", "TCHAR/_ungettc", "ungetc", "ungetwc", "_ungettc"] helpviewer_keywords: ["ungetwc function", "ungettc function", "characters, pushing back onto stream", "_ungettc function", "ungetc function"] ms.assetid: e0754f3a-b4c6-408f-90c7-e6387b830d84 --- -# ungetc, ungetwc +# `ungetc`, `ungetwc` Pushes a character back onto the stream. @@ -29,46 +29,46 @@ wint_t ungetwc( ### Parameters -*c*
+*`c`*\ Character to be pushed. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If successful, each of these functions returns the character argument *c*. If *c* cannot be pushed back or if no character has been read, the input stream is unchanged and **ungetc** returns **EOF**; **ungetwc** returns **WEOF**. If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **EOF** or **WEOF** is returned and **errno** is set to **EINVAL**. +If successful, each of these functions returns the character argument *`c`*. If *`c`* can't be pushed back or if no character has been read, the input stream is unchanged and **`ungetc`** returns `EOF`; **`ungetwc`** returns `WEOF`. If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `EOF` or `WEOF` is returned, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **ungetc** function pushes the character *c* back onto *stream* and clears the end-of-file indicator. The stream must be open for reading. A subsequent read operation on *stream* starts with *c*. An attempt to push **EOF** onto the stream using **ungetc** is ignored. +The **`ungetc`** function pushes the character *`c`* back onto *`stream`* and clears the end-of-file indicator. The stream must be open for reading. A subsequent read operation on *`stream`* starts with *`c`*. An attempt to push `EOF` onto the stream using **`ungetc`** is ignored. -Characters placed on the stream by **ungetc** may be erased if **fflush**, [fseek](fseek-fseeki64.md), **fsetpos**, or [rewind](rewind.md) is called before the character is read from the stream. The file-position indicator will have the value it had before the characters were pushed back. The external storage corresponding to the stream is unchanged. On a successful **ungetc** call against a text stream, the file-position indicator is unspecified until all the pushed-back characters are read or discarded. On each successful **ungetc** call against a binary stream, the file-position indicator is decremented; if its value was 0 before a call, the value is undefined after the call. +Characters placed on the stream by **`ungetc`** may be erased if `fflush`, [`fseek`](fseek-fseeki64.md), `fsetpos`, or [`rewind`](rewind.md) is called before the character is read from the stream. The file-position indicator will have the value it had before the characters were pushed back. The external storage corresponding to the stream is unchanged. On a successful **`ungetc`** call against a text stream, the file-position indicator is unspecified until all the pushed-back characters are read or discarded. On each successful **`ungetc`** call against a binary stream, the file-position indicator is decremented; if its value was 0 before a call, the value is undefined after the call. -Results are unpredictable if **ungetc** is called twice without a read or file-positioning operation between the two calls. After a call to **fscanf**, a call to **ungetc** may fail unless another read operation (such as **getc**) has been performed. This is because **fscanf** itself calls **ungetc**. +Results are unpredictable if **`ungetc`** is called twice without a read or file-positioning operation between the two calls. After a call to `fscanf`, a call to **`ungetc`** may fail unless another read operation (such as `getc`) has been performed, because `fscanf` itself calls **`ungetc`**. -**ungetwc** is a wide-character version of **ungetc**. However, on each successful **ungetwc** call against a text or binary stream, the value of the file-position indicator is unspecified until all pushed-back characters are read or discarded. +**`ungetwc`** is a wide-character version of **`ungetc`**. However, on each successful **`ungetwc`** call against a text or binary stream, the value of the file-position indicator is unspecified until all pushed-back characters are read or discarded. -These functions are thread-safe and lock sensitive data during execution. For a non-locking version, see [_ungetc_nolock, _ungetwc_nolock](ungetc-nolock-ungetwc-nolock.md). +These functions are thread-safe and lock sensitive data during execution. For a non-locking version, see [`_ungetc_nolock`, `_ungetwc_nolock`](ungetc-nolock-ungetwc-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc**|**ungetc**|**ungetc**|**ungetwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettc` | **`ungetc`** | **`ungetc`** | **`ungetwc`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ungetc**|\| -|**ungetwc**|\ or \| +| Routine | Required header | +|---|---| +| **`ungetc`** | \ | +| **`ungetwc`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,6 +106,6 @@ Next character in stream = 'a' ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md b/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md index 35b0e27295..5c15bfbf42 100644 --- a/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md +++ b/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" title: "_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" +description: "Learn more about: _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" ms.date: "4/2/2020" api_name: ["_ungetch_nolock", "_ungetwch_nolock", "_ungetwch", "_ungetch", "_o__ungetch", "_o__ungetch_nolock", "_o__ungetwch", "_o__ungetwch_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungetch_nolock", "ungetwch", "ungetch_nolock", "_ungetwch", "ungetwch_nolock", "_ungetch", "_ungettch_nolock", "_ungettch", "_ungetwch_nolock"] +f1_keywords: ["CONIO/_ungetch", "CONIO/_ungetch_nolock", "CORECRT_WCONIO/_ungetwch", "CORECRT_WCONIO/_ungetwch_nolock", "TCHAR/_ungettch", "TCHAR/_ungettch_nolock", "_ungetch", "_ungetch_nolock", "_ungetwch", "_ungetwch_nolock", "_ungettch", "_ungettch_nolock"] helpviewer_keywords: ["_ungetch function", "ungetwch function", "characters, pushing back to console", "_ungettch_nolock function", "ungettch function", "_ungettch function", "ungetch_nolock function", "ungettch_nolock function", "_ungetwch_nolock function", "_ungetch_nolock function", "ungetwch_nolock function", "_ungetwch function"] -ms.assetid: 70ae71c6-228c-4883-a57d-de6d5f873825 --- -# _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock +# `_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock` Pushes back the last character that's read from the console. @@ -36,36 +35,36 @@ wint_t _ungetwch_nolock( ### Parameters -*c*
+*`c`*\ Character to be pushed. -## Return Value +## Return value -Both functions return the character *c* if successful. If there is an error, **_ungetch** returns a value of **EOF** and **_ungetwch** returns **WEOF**. +Both functions return the character *`c`* if successful. If there's an error, **`_ungetch`** returns a value of `EOF` and **`_ungetwch`** returns `WEOF`. ## Remarks -These functions push the character *c* back to the console, causing *c* to be the next character read by **_getch** or **_getche** (or **_getwch** or **_getwche**). **_ungetch** and **_ungetwch** fail if they are called more than once before the next read. The *c* argument may not be **EOF** (or **WEOF**). +These functions push the character *`c`* back to the console, causing *`c`* to be the next character read by `_getch` or `_getche` (or `_getwch` or `_getwche`). **`_ungetch`** and **`_ungetwch`** fail if they're called more than once before the next read. The *`c`* argument may not be `EOF` (or `WEOF`). -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettch**|**_ungetch**|**_ungetch**|**_ungetwch**| -|**_ungettch_nolock**|**_ungetch_nolock**|**_ungetch_nolock**|**_ungetwch_nolock**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettch` | **`_ungetch`** | **`_ungetch`** | **`_ungetwch`** | +| `_ungettch_nolock` | **`_ungetch_nolock`** | **`_ungetch_nolock`** | **`_ungetwch_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ungetch**, **_ungetch_nolock**|\| -|**_ungetwch**, **_ungetwch_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_ungetch`**, **`_ungetch_nolock`** | \ | +| **`_ungetwch`**, **`_ungetwch_nolock`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -111,6 +110,6 @@ Whitetoken = White ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/ungetch.md b/docs/c-runtime-library/reference/ungetch.md index 7b67fd45ac..668a233b35 100644 --- a/docs/c-runtime-library/reference/ungetch.md +++ b/docs/c-runtime-library/reference/ungetch.md @@ -6,15 +6,15 @@ api_name: ["ungetch"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["ungetch"] +f1_keywords: ["CONIO/ungetch", "ungetch"] helpviewer_keywords: ["ungetch function"] ms.assetid: 6921232f-6317-41cd-948b-91d56a11bc0e --- -# ungetch +# `ungetch` -The Microsoft-specific function name `ungetch` is a deprecated alias for the [_ungetch](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `ungetch` is a deprecated alias for the [`_ungetch`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_ungetch](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_ungetch`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/unlink-wunlink.md b/docs/c-runtime-library/reference/unlink-wunlink.md index 84be18664b..2a0dba15a7 100644 --- a/docs/c-runtime-library/reference/unlink-wunlink.md +++ b/docs/c-runtime-library/reference/unlink-wunlink.md @@ -3,14 +3,14 @@ description: "Learn more about: _unlink, _wunlink" title: "_unlink, _wunlink" ms.date: "4/2/2020" api_name: ["_unlink", "_wunlink", "_o__unlink", "_o__wunlink"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tunlink", "_unlink", "wunlink", "_wunlink"] +f1_keywords: ["CORECRT_IO/_unlink", "CORECRT_WIO/_wunlink", "TCHAR/_tunlink", "_unlink", "_wunlink", "_tunlink"] helpviewer_keywords: ["files [C++], deleting", "_wunlink function", "wunlink function", "unlink function", "_unlink function", "tunlink function", "files [C++], removing", "_tunlink function"] ms.assetid: 5e4f5f1b-1e99-4391-9b18-9ac63c32fae8 --- -# _unlink, _wunlink +# `_unlink`, `_wunlink` Delete a file. @@ -27,37 +27,37 @@ int _wunlink( ### Parameters -*filename*
+*`filename`*\ Name of file to remove. -## Return Value +## Return value -Each of these functions returns 0 if successful. Otherwise, the function returns -1 and sets **errno** to **EACCES**, which means the path specifies a read-only file or a directory, or to **ENOENT**, which means the file or path is not found. +Each of these functions returns 0 if successful. Otherwise, the function returns -1 and sets `errno` to `EACCES`, which means the path specifies a read-only file or a directory, or to `ENOENT`, which means the file or path isn't found. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_unlink** function deletes the file specified by *filename*. **_wunlink** is a wide-character version of **_unlink**; the *filename* argument to **_wunlink** is a wide-character string. These functions behave identically otherwise. +The **`_unlink`** function deletes the file specified by *`filename`*. **`_wunlink`** is a wide-character version of **`_unlink`**; the *`filename`* argument to **`_wunlink`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tunlink**|**_unlink**|**_unlink**|**_wunlink**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tunlink` | **`_unlink`** | **`_unlink`** | **`_wunlink`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_unlink**|\ and \| -|**_wunlink**|\ or \| +| Routine | Required header | +|---|---| +| **`_unlink`** | \ and \ | +| **`_wunlink`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -## Code Example +## Code example This program uses _unlink to delete CRT_UNLINK.TXT. @@ -81,7 +81,7 @@ int main( void ) This file will be deleted. ``` -### Sample Output +### Sample output ```Output Deleted 'CRT_UNLINK.TXT' @@ -89,6 +89,6 @@ Deleted 'CRT_UNLINK.TXT' ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_close](close.md)
-[remove, _wremove](remove-wremove.md)
+[File handling](../file-handling.md)\ +[`_close`](close.md)\ +[`remove`, `_wremove`](remove-wremove.md) diff --git a/docs/c-runtime-library/reference/unlink.md b/docs/c-runtime-library/reference/unlink.md index 98863f4473..58c351ba3a 100644 --- a/docs/c-runtime-library/reference/unlink.md +++ b/docs/c-runtime-library/reference/unlink.md @@ -6,12 +6,12 @@ api_name: ["unlink"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unlink"] +f1_keywords: ["CORECRT_IO/unlink", "unlink"] helpviewer_keywords: ["unlink function"] ms.assetid: 2cd82055-5770-48be-88ee-4b2c70541c46 --- -# unlink +# `unlink` -The Microsoft-implemented POSIX function name `unlink` is a deprecated alias for the [_unlink](unlink-wunlink.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `unlink` is a deprecated alias for the [`_unlink`](unlink-wunlink.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_unlink](unlink-wunlink.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_unlink`](unlink-wunlink.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/unlock-file.md b/docs/c-runtime-library/reference/unlock-file.md index f37d5498d8..af13c9ba9f 100644 --- a/docs/c-runtime-library/reference/unlock-file.md +++ b/docs/c-runtime-library/reference/unlock-file.md @@ -3,14 +3,14 @@ description: "Learn more about: _unlock_file" title: "_unlock_file" ms.date: "4/2/2020" api_name: ["_unlock_file", "_o__unlock_file"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_unlock_file", "unlock_file"] +f1_keywords: ["STDIO/_unlock_file", "_unlock_file"] helpviewer_keywords: ["files [C++], unlocking", "unlock_file function", "_unlock_file function", "unlocking files"] ms.assetid: cf380a51-6d3a-4f38-bd64-2d4fb57b4369 --- -# _unlock_file +# `_unlock_file` Unlocks a file, allowing other processes to access the file. @@ -24,26 +24,26 @@ void _unlock_file( ### Parameters -*file*
+*`file`*\ File handle. ## Remarks -The **_unlock_file** function unlocks the file specified by *file*. Unlocking a file allows access to the file by other processes. This function should not be called unless **_lock_file** was previously called on the *file* pointer. Calling **_unlock_file** on a file that isn't locked may result in a deadlock. For an example, see [_lock_file](lock-file.md). +The **`_unlock_file`** function unlocks the file specified by *`file`*. Unlocking a file allows access to the file by other processes. This function shouldn't be called unless `_lock_file` was previously called on the *`file`* pointer. Calling **`_unlock_file`** on a file that isn't locked may result in a deadlock. For an example, see [`_lock_file`](lock-file.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_unlock_file**|\| +| Routine | Required header | +|---|---| +| **`_unlock_file`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
-[_lock_file](lock-file.md)
+[File handling](../file-handling.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_lock_file`](lock-file.md) diff --git a/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md b/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md index ed2a5e043e..d5a82ee0b6 100644 --- a/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md +++ b/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md @@ -3,14 +3,14 @@ description: "Learn more about: _utime, _utime32, _utime64, _wutime, _wutime32, title: "_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64" ms.date: "4/2/2020" api_name: ["_utime64", "_utime", "_wutime", "_wutime64", "_wutime32", "_utime32", "_o__utime32", "_o__utime64", "_o__wutime32", "_o__wutime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tutime", "_utime64", "wutime", "utime32", "wutime64", "_utime", "wutime32", "_wutime", "utime", "utime64", "_wutime64", "_utime32", "_tutime64", "_wutime32"] +f1_keywords: ["UTIME/_utime", "UTIME/_utime32", "UTIME/_utime64", "UTIME/_wutime", "UTIME/_wutime32", "UTIME/_wutime64", "TCHAR/_tutime", "TCHAR/_tutime32", "TCHAR/_tutime64", "_utime", "_utime32", "_utime64", "_wutime", "_wutime32", "_wutime64", "_tutime", "_tutime32", "_tutime64"] helpviewer_keywords: ["tutime function", "utime32 function", "utime64 function", "_utime function", "_tutime32 function", "time [C++], file modification", "wutime function", "_wutime function", "_wutime32 function", "_tutime64 function", "_tutime function", "files [C++], modification time", "_wutime64 function", "_utime32 function", "utime function", "_utime64 function", "wutime64 function", "wutime32 function", "tutime64 function", "tutime32 function"] ms.assetid: 8d482d40-19b9-4591-bfee-5d7f601d1a9e --- -# _utime, _utime32, _utime64, _wutime, _wutime32, _wutime64 +# `_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64` Set the file modification time. @@ -45,67 +45,67 @@ int _wutime64( ### Parameters -*filename*
+*`filename`*\ Pointer to a string that contains the path or filename. -*times*
+*`times`*\ Pointer to stored time values. -## Return Value +## Return value -Each of these functions returns 0 if the file-modification time was changed. A return value of -1 indicates an error. If an invalid parameter is passed, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and **errno** is set to one of the following values: +Each of these functions returns 0 if the file-modification time was changed. A return value of -1 indicates an error. If an invalid parameter is passed, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1, and `errno` is set to one of the following values: -|errno value|Condition| -|-|-| -| **EACCES** | Path specifies directory or read-only file | -| **EINVAL** | Invalid *times* argument | -| **EMFILE** | Too many open files (the file must be opened to change its modification time) | -| **ENOENT** | Path or filename not found | +| `errno` value | Condition | +|---|---| +| `EACCES` | Path specifies directory or read-only file | +| `EINVAL` | Invalid *`times`* argument | +| `EMFILE` | Too many open files (the file must be opened to change its modification time) | +| `ENOENT` | Path or filename not found | -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The date can be changed for a file if the change date is after midnight, January 1, 1970, and before the end date of the function used. **_utime** and **_wutime** use a 64-bit time value, so the end date is 23:59:59, December 31, 3000, UTC. If **_USE_32BIT_TIME_T** is defined to force the old behavior, the end date is 23:59:59 January 18, 2038, UTC. **_utime32** or **_wutime32** use a 32-bit time type regardless of whether **_USE_32BIT_TIME_T** is defined, and always have the earlier end date. **_utime64** or **_wutime64** always use the 64-bit time type, so these functions always support the later end date. +The date can be changed for a file if the change date is after midnight, January 1, 1970, and before the end date of the function used. **`_utime`** and **`_wutime`** use a 64-bit time value, so the end date is 23:59:59, December 31, 3000, UTC. If `_USE_32BIT_TIME_T` is defined to force the old behavior, the end date is 23:59:59 January 18, 2038, UTC. **`_utime32`** or **`_wutime32`** use a 32-bit time type regardless of whether `_USE_32BIT_TIME_T` is defined, and always have the earlier end date. **`_utime64`** or **`_wutime64`** always use the 64-bit time type, so these functions always support the later end date. ## Remarks -The **_utime** function sets the modification time for the file specified by *filename*. The process must have write access to the file in order to change the time. In the Windows operating system, you can change the access time and the modification time in the **_utimbuf** structure. If *times* is a **NULL** pointer, the modification time is set to the current local time. Otherwise, *times* must point to a structure of type **_utimbuf**, defined in SYS\UTIME.H. +The **`_utime`** function sets the modification time for the file specified by *`filename`*. The process must have write access to the file in order to change the time. In the Windows operating system, you can change the access time and the modification time in the `_utimbuf` structure. If *`times`* is a `NULL` pointer, the modification time is set to the current local time. Otherwise, *`times`* must point to a structure of type `_utimbuf`, defined in SYS\UTIME.H. -The **_utimbuf** structure stores file access and modification times used by **_utime** to change file-modification dates. The structure has the following fields, which are both of type **time_t**: +The **`_utimbuf`** structure stores file access and modification times used by **`_utime`** to change file-modification dates. The structure has the following fields, which are both of type `time_t`: | Field | Description | -|-------|---| -| **actime** | Time of file access | -| **modtime** | Time of file modification | +|---|---| +| **`actime`** | Time of file access | +| **`modtime`** | Time of file modification | -Specific versions of the **_utimbuf** structure (**_utimebuf32** and **__utimbuf64**) are defined using the 32-bit and 64-bit versions of the time type. These are used in the 32-bit and 64-bit specific versions of this function. **_utimbuf** itself by default uses a 64-bit time type unless **_USE_32BIT_TIME_T** is defined. +Specific versions of the `_utimbuf` structure (`__utimbuf32` and `__utimbuf64`) are defined using the 32-bit and 64-bit versions of the time type. These structures are used in the 32-bit and 64-bit specific versions of this function. `_utimbuf` itself by default uses a 64-bit time type unless `_USE_32BIT_TIME_T` is defined. -**_utime** is identical to **_futime** except that the *filename* argument of **_utime** is a filename or a path to a file, rather than a file descriptor of an open file. +`_utime` is identical to `_futime` except that the *`filename`* argument of **`_utime`** is a filename or a path to a file, rather than a file descriptor of an open file. -**_wutime** is a wide-character version of **_utime**; the *filename* argument to **_wutime** is a wide-character string. These functions behave identically otherwise. +**`_wutime`** is a wide-character version of **`_utime`**; the *`filename`* argument to **`_wutime`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tutime**|**_utime**|**_utime**|**_wutime**| -|**_tutime32**|**_utime32**|**_utime32**|**_wutime32**| -|**_tutime64**|**_utime64**|**_utime64**|**_wutime64**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tutime` | **`_utime`** | **`_utime`** | **`_wutime`** | +| `_tutime32` | **`_utime32`** | **`_utime32`** | **`_wutime32`** | +| `_tutime64` | **`_utime64`** | **`_utime64`** | **`_wutime64`** | ## Requirements -|Routine|Required headers|Optional headers| -|-------------|----------------------|----------------------| -|**_utime**, **_utime32**, **_utime64**|\|\| -|**_utime64**|\|\| -|**_wutime**|\ or \|\| +| Routine | Required headers | Optional headers | +|---|---|---| +| **`_utime`**, **`_utime32`**, **`_utime64`** | \ | \ | +| **`_utime64`** | \ | \ | +| **`_wutime`** | \ or \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program uses **_utime** to set the file-modification time to the current time. +This program uses **`_utime`** to set the file-modification time to the current time. ```C // crt_utime.c @@ -152,7 +152,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Volume in drive C has no label. @@ -176,13 +176,13 @@ Directory of C:\test ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[_futime, _futime32, _futime64](futime-futime32-futime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[_stat, _wstat Functions](stat-functions.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`_futime`, `_futime32`, `_futime64`](futime-futime32-futime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`_stat`, `_wstat` functions](stat-functions.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md b/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md index 7d42033407..a8f051d5ae 100644 --- a/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md +++ b/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md @@ -6,7 +6,7 @@ api_name: ["va_arg", "va_end", "va_copy", "va_start"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["va_arg", "va_start", "va_list", "va_alist", "va_dcl", "va_copy", "va_end"] +f1_keywords: ["STDARG/va_arg", "STDARG/va_copy", "STDARG/va_end", "VADEFS/va_list", "STDARG/va_start", "va_alist", "va_arg", "va_copy", "va_dcl", "va_end", "va_list", "va_start"] helpviewer_keywords: ["variable argument lists, accessing", "va_start macro", "va_arg macro", "va_end macro", "arguments [C++], argument lists", "va_list macro", "va_dcl macro", "va_alist macro", "va_copy macro"] ms.assetid: a700dbbd-bfe5-4077-87b6-3a07af74a907 --- @@ -39,24 +39,24 @@ void va_start( ### Parameters -*`type`*
+*`type`*\ Type of argument to be retrieved. -*`arg_ptr`*
+*`arg_ptr`*\ Pointer to the list of arguments. -*`dest`*
+*`dest`*\ Pointer to the list of arguments to be initialized from *`src`* -*`src`*
+*`src`*\ Pointer to the initialized list of arguments to copy to *`dest`*. -*`prev_param`*
+*`prev_param`*\ Parameter that precedes the first optional argument. -## Return Value +## Return value -**`va_arg`** returns the current argument. **`va_copy`**, **`va_start`** and **`va_end`** do not return values. +**`va_arg`** returns the current argument. **`va_copy`**, **`va_start`** and **`va_end`** don't return values. ## Remarks @@ -72,12 +72,12 @@ The C standard macros, defined in `STDARG.H`, are used as follows: - **`va_copy`** makes a copy of a list of arguments in its current state. The *`src`* parameter must already be initialized with **`va_start`**; it may have been updated with **`va_arg`** calls, but must not have been reset with **`va_end`**. The next argument that's retrieved by **`va_arg`** from *`dest`* is the same as the next argument that's retrieved from *`src`*. -- After all arguments have been retrieved, **`va_end`** resets the pointer to **`NULL`**. **`va_end`** must be called on each argument list that's initialized with **`va_start`** or **`va_copy`** before the function returns. +- After all arguments have been retrieved, **`va_end`** resets the pointer to `NULL`. **`va_end`** must be called on each argument list that's initialized with **`va_start`** or **`va_copy`** before the function returns. > [!NOTE] > The macros in VARARGS.H are deprecated and are retained only for backwards compatibility with code that was written before the ANSI C89 standard. In all other cases, use the macros in STDARGS.H. -When they are compiled by using [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md), programs that use these macros may generate unexpected results because of differences between native and common language runtime (CLR) type systems. Consider this program: +When they're compiled by using [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md), programs that use these macros may generate unexpected results because of differences between native and common language runtime (CLR) type systems. Consider this program: ```C #include @@ -109,7 +109,7 @@ int main() } ``` -Notice that **`testit`** expects its second parameter to be either an **`int`** or a **`char*`**. The arguments being passed are 0xffffffff (an **`unsigned int`**, not an **`int`**) and **`NULL`** (actually an **`int`**, not a **`char*`**). When the program is compiled for native code, it produces this output: +Notice that **`testit`** expects its second parameter to be either an **`int`** or a **`char*`**. The arguments being passed are 0xffffffff (an **`unsigned int`**, not an **`int`**) and `NULL` (actually an **`int`**, not a **`char*`**). When the program is compiled for native code, it produces this output: ```Output -1 @@ -125,7 +125,7 @@ Notice that **`testit`** expects its second parameter to be either an **`int`** ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -194,5 +194,5 @@ Deviation is: 0.000000 ## See also -[Argument Access](../../c-runtime-library/argument-access.md)
-[`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)
+[Argument access](../argument-access.md)\ +[`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) diff --git a/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md b/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md index c8cc18d5d1..5a40fed9d7 100644 --- a/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md +++ b/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md @@ -6,10 +6,10 @@ api_name: ["_vcprintf_p", "_vcwprintf_p_l", "_vcprintf_p_l", "_vcwprintf_p"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vcwprintf_p", "vcprintf_p_l", "_vcprintf_p", "_vcprintf_p_l", "vcwprintf_p_l", "vcprintf_p", "_vcwprintf_p", "_vcwprintf_p_l"] +f1_keywords: ["CONIO/_vcprintf_p", "CONIO/_vcprintf_p_l", "CORECRT_WCONIO/_vcwprintf_p", "CORECRT_WCONIO/_vcwprintf_p_l", "TCHAR/_vtcprintf_p", "TCHAR/_vtcprintf_p_l", "_vcprintf_p", "_vcprintf_p_l", "_vcwprintf_p", "_vcwprintf_p_l", "_vtcprintf_p", "_vtcprintf_p_l"] helpviewer_keywords: ["_vtcprintf_p_l function", "vcprintf_p_l function", "_vcprintf_p_l function", "vtcprintf_p_l function", "vcprintf_p function", "_vcwprintf_p function", "_vcprintf_p function", "vcwprintf_p function", "vcwprintf_p_l function", "vtcprintf_p function", "_vcwprintf_p_l function", "_vtcprintf_p function"] --- -# _vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l +# `_vcprintf_p`, `_vcprintf_p_l`, `_vcwprintf_p`, `_vcwprintf_p_l` Writes formatted output to the console by using a pointer to a list of arguments, and supports positional parameters in the format string. @@ -41,51 +41,51 @@ int _vcwprintf_p_l( ### Parameters -*format*
+*`format`*\ The format specification. -*argptr*
+*`argptr`*\ A pointer to a list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters that are written, or a negative value if an output error occurs. If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and -1 is returned. +The number of characters that are written, or a negative value if an output error occurs. If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and -1 is returned. ## Remarks -Each of these functions takes a pointer to an argument list, and then uses the **_putch** function to format and write the given data to the console. (**_vcwprintf_p** uses **_putwch** instead of **_putch**. **_vcwprintf_p** is the wide-character version of **_vcprintf_p**. It takes a wide-character string as an argument.) +Each of these functions takes a pointer to an argument list, and then uses the `_putch` function to format and write the given data to the console. (**`_vcwprintf_p`** uses `_putwch` instead of `_putch`. **`_vcwprintf_p`** is the wide-character version of **`_vcprintf_p`**. It takes a wide-character string as an argument.) -The versions of these functions that have the **_l** suffix are identical except that they use the locale parameter that's passed in instead of the current locale. +The versions of these functions that have the `_l` suffix are identical except that they use the locale parameter that's passed in instead of the current locale. -Each *argument* (if any) is converted and is output according to the corresponding format specification in *format*. The format specification supports positional parameters so that you can specify the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each *`argument`* (if any) is converted and is output according to the corresponding format specification in *`format`*. The format specification supports positional parameters so that you can specify the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -These functions do not translate line-feed characters into carriage return-line feed (CR-LF) combinations when they are output. +These functions don't translate line-feed characters on output into carriage return-line feed (CR-LF) combinations. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -These functions validate the input pointer and the format string. If *format* or *argument* is **NULL**, or if the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +These functions validate the input pointer and the format string. If *`format`* or *`argument`* is `NULL`, or if the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_vtcprintf_p**|**_vcprintf_p**|**_vcprintf_p**|**_vcwprintf_p**| -|**_vtcprintf_p_l**|**_vcprintf_p_l**|**_vcprintf_p_l**|**_vcwprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf_p` | **`_vcprintf_p`** | **`_vcprintf_p`** | **`_vcwprintf_p`** | +| `_vtcprintf_p_l` | **`_vcprintf_p_l`** | **`_vcprintf_p_l`** | **`_vcwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_vcprintf_p**, **_vcprintf_p_l**|\ and \| -|**_vcwprintf_p**, **_vcwprintf_p_l**|\ and \| +| Routine | Required header | +|---|---| +| **`_vcprintf_p`**, **`_vcprintf_p_l`** | \ and \ | +| **`_vcwprintf_p`**, **`_vcwprintf_p_l`** | \ and \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -123,7 +123,7 @@ parameter 2 = 222; parameter 1 = one ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md b/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md index 7bc6adf20d..5c37e0a97a 100644 --- a/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md @@ -6,12 +6,12 @@ api_name: ["_vcprintf_s", "_vcprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vcprintf_s", "vcwprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l", "_vcprintf_s_l", "_vtcprintf_s", "vcwprintf_s", "vcprintf_s_l", "_vcprintf_s"] +f1_keywords: ["CONIO/_vcprintf_s", "CONIO/_vcprintf_s_l", "CORECRT_WCONIO/_vcwprintf_s", "CORECRT_WCONIO/_vcwprintf_s_l", "TCHAR/_vtcprintf_s", "TCHAR/_vtcprintf_s_l", "_vcprintf_s", "_vcprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l", "_vtcprintf_s", "_vtcprintf_s_l"] helpviewer_keywords: ["_vtcprintf_s_l function", "_vcwprintf_s_l function", "_vtcprintf_s function", "vtcprintf_s_l function", "vcprintf_s_l function", "_vcprintf_s function", "_vcwprintf_s function", "vcwprintf_s_l function", "vcwprintf_s function", "vcprintf_s function", "_vcprintf_s_l function", "vtcprintf_s function", "formatted text [C++]"] --- -# _vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l +# `_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l` -Writes formatted output to the console by using a pointer to a list of arguments. These versions of [_vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l](vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Writes formatted output to the console by using a pointer to a list of arguments. These versions of [`_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l`](vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -19,21 +19,21 @@ Writes formatted output to the console by using a pointer to a list of arguments ## Syntax ```C -int _vcprintf( - const char* format, +int _vcprintf_s( + char const* const format, va_list argptr ); -int _vcprintf( - const char* format, +int _vcprintf_s_l( + char const* const format, _locale_t locale, va_list argptr ); int _vcwprintf_s( - const wchar_t* format, + wchar_t const* const format, va_list argptr ); int _vcwprintf_s_l( - const wchar_t* format, + wchar_t const* const format, _locale_t locale, va_list argptr ); @@ -41,49 +41,49 @@ int _vcwprintf_s_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to the list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value The number of characters written, or a negative value if an output error occurs. -Like the less secure versions of these functions, if *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). Additionally, unlike the less secure versions of these functions, if *format* does not specify a valid format, an invalid parameter exception is generated. If execution is allowed to continue, these functions return an error code and set **errno** to that error code. The default error code is **EINVAL** if a more specific value does not apply. +Like the less secure versions of these functions, if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). Additionally, unlike the less secure versions of these functions, if *`format`* doesn't specify a valid format, an invalid parameter exception is generated. If execution is allowed to continue, these functions return an error code and set `errno` to that error code. The default error code is `EINVAL` if a more specific value doesn't apply. ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the console. **_vcwprintf_s** is the wide-character version of **_vcprintf_s**. It takes a wide-character string as an argument. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the console. **`_vcwprintf_s`** is the wide-character version of **`_vcprintf_s`**. It takes a wide-character string as an argument. -The versions of these functions that have the **_l** suffix are identical except that they use the locale parameter that's passed in instead of the current locale. +The versions of these functions that have the `_l` suffix are identical except that they use the locale parameter that's passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf_s**|**_vcprintf_s**|**_vcprintf_s**|**_vcwprintf_s**| -|**_vtcprintf_s_l**|**_vcprintf_s_l**|**_vcprintf_s_l**|**_vcwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf_s` | **`_vcprintf_s`** | **`_vcprintf_s`** | **`_vcwprintf_s`** | +| `_vtcprintf_s_l` | **`_vcprintf_s_l`** | **`_vcprintf_s_l`** | **`_vcwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vcprintf_s**, **_vcprintf_s_l**|\ and \|\*| -|**_vcwprintf_s**, **_vcwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vcprintf_s`**, **`_vcprintf_s_l`** | \ and \ | \* | +| **`_vcwprintf_s`**, **`_vcwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -121,10 +121,10 @@ int main() ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md b/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md index 6136b8332a..48dc1f6a5f 100644 --- a/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md +++ b/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md @@ -6,12 +6,12 @@ api_name: ["_vcwprintf", "_vcprintf_l", "_vcwprintf_l", "_vcprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vcwprintf_l", "_vtcprintf", "vcwprintf", "_vcwprintf", "vcprintf_l", "_vcprintf_l", "_vcprintf", "vcprintf", "vcwprintf_l"] +f1_keywords: ["CONIO/_vcprintf", "CONIO/_vcprintf_l", "CORECRT_WCONIO/_vcwprintf", "CORECRT_WCONIO/_vcwprintf_l", "TCHAR/_vtcprintf", "TCHAR/_vtcprintf_l", "_vcprintf", "_vcprintf_l", "_vcwprintf", "_vcwprintf_l", "_vtcprintf", "_vtcprintf_l"] helpviewer_keywords: ["vcwprintf function", "_vcwprintf_l function", "_vcprintf function", "_vcprintf_l function", "vtcprintf_l function", "vcprintf function", "vcprintf_l function", "_vtcprintf function", "_vcwprintf function", "_vtcprintf_l function", "vcwprintf_l function", "vtcprintf function", "formatted text [C++]"] --- -# _vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l +# `_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l` -Writes formatted output to the console by using a pointer to a list of arguments. More secure versions of these functions are available, see [_vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l](vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md). +Writes formatted output to the console by using a pointer to a list of arguments. More secure versions of these functions are available, see [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -41,48 +41,49 @@ int _vcwprintf_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters written, or a negative value if an output error occurs. If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and -1 is returned. +The number of characters written, or a negative value if an output error occurs. If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and -1 is returned. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to the console. **_vcwprintf** is the wide-character version of **_vcprintf**. It takes a wide-character string as an argument. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to the console. **`_vcwprintf`** is the wide-character version of **`_vcprintf`**. It takes a wide-character string as an argument. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf**|**_vcprintf**|**_vcprintf**|**_vcwprintf**| -|**_vtcprintf_l**|**_vcprintf_l**|**_vcprintf_l**|**_vcwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf` | **`_vcprintf`** | **`_vcprintf`** | **`_vcwprintf`** | +| `_vtcprintf_l` | **`_vcprintf_l`** | **`_vcprintf_l`** | **`_vcwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vcprintf**, **_vcprintf_l**|\ and \|\*| -|**_vcwprintf**, **_vcwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vcprintf`**, **`_vcprintf_l`** | \ and \ | \* | +| **`_vcwprintf`**, **`_vcwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -118,10 +119,10 @@ int main() ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md b/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md index 4bcf50a866..0d8c50f0a3 100644 --- a/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md +++ b/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md @@ -6,10 +6,10 @@ api_name: ["_vfprintf_p", "_vfwprintf_p", "_vfprintf_p_l", "_vfwprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vfwprintf_p_l", "_vfprintf_p", "vfwprintf_p_l", "vfwprintf_p", "vfprintf_p_l", "_vfwprintf_p", "_vftprintf_p", "_vfprintf_p_l", "vfprintf_p"] +f1_keywords: ["STDIO/_vfprintf_p", "STDIO/_vfprintf_p_l", "CORECRT_WSTDIO/_vfwprintf_p", "CORECRT_WSTDIO/_vfwprintf_p_l", "TCHAR/_vftprintf_p", "TCHAR/_vftprintf_p_l", "_vfprintf_p", "_vfprintf_p_l", "_vfwprintf_p", "_vfwprintf_p_l", "_vftprintf_p", "_vftprintf_p_l"] helpviewer_keywords: ["vfprintf_p_l function", "_vftprintf_p_l function", "_vfprintf_p function", "vfprintf_p function", "vftprintf_p_l function", "_vfprintf_p_l function", "_vftprintf_p function", "_vfwprintf_p_l function", "vfwprintf_p_l function", "_vfwprintf_p function", "vftprintf_p function", "formatted text [C++]", "vfwprintf_p function"] --- -# _vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l +# `_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l` Write formatted output using a pointer to a list of arguments, with the ability to specify the order that arguments are used in the format string. @@ -42,65 +42,65 @@ int _vfwprintf_p_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vfprintf_p** and **_vfwprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vfprintf_p`** and **`_vfwprintf_p`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. These functions differ from the **_vfprint_s** and **_vfwprint_s** versions only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. These functions differ from the `_vfprint_s` and `_vfwprint_s` versions only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_vfwprintf_p** is the wide-character version of **_vprintf_p**; the two functions behave identically if the stream is opened in ANSI mode. **_vprintf_p** doesn't currently support output into a UNICODE stream. +**`_vfwprintf_p`** is the wide-character version of **`_vprintf_p`**; the two functions behave identically if the stream is opened in ANSI mode. **`_vprintf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -If either *stream* or *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If either *`stream`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf_p**|**_vfprintf_p**|**_vfprintf_p**|**_vfwprintf_p**| -|**_vftprintf_p_l**|**_vfprintf_p_l**|**_vfprintf_p_l**|**_vfwprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf_p` | **`_vfprintf_p`** | **`_vfprintf_p`** | **`_vfwprintf_p`** | +| `_vftprintf_p_l` | **`_vfprintf_p_l`** | **`_vfprintf_p_l`** | **`_vfwprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vfprintf_p**, **_vfprintf_p_l**|\ and \|\*| -|**_vfwprintf_p**, **_vfwprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vfprintf_p`**, **`_vfprintf_p_l`** | \ and \ | \* | +| **`_vfwprintf_p`**, **`_vfwprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l](vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) diff --git a/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md b/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md index b79108ae39..ffb2bfde12 100644 --- a/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md @@ -6,12 +6,12 @@ api_name: ["vfwprintf_s", "_vfprintf_s_l", "vfprintf_s", "_vfwprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vftprintf_s", "vfwprintf_s", "vfprintf_s"] +f1_keywords: ["STDIO/vfprintf_s", "STDIO/_vfprintf_s_l", "CORECRT_WSTDIO/vfwprintf_s", "CORECRT_WSTDIO/_vfwprintf_s_l", "TCHAR/_vftprintf_s", "TCHAR/_vftprintf_s_l", "vfprintf_s", "_vfprintf_s_l", "vfwprintf_s", "_vfwprintf_s_l", "_vftprintf_s", "_vftprintf_s_l"] helpviewer_keywords: ["vfprintf_s_l function", "vfwprintf_s_l function", "vfwprintf_s function", "_vfprintf_s_l function", "_vfwprintf_s_l function", "vftprintf_s_l function", "vfprintf_s function", "_vftprintf_s_l function", "formatted text [C++]", "_vftprintf_s function"] --- -# vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l +# `vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l` -Write formatted output using a pointer to a list of arguments. These are versions of [vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -42,63 +42,63 @@ int _vfwprintf_s_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vfprintf_s** and **vfwprintf_s** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *stream* or *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vfprintf_s`** and **`vfwprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *`stream`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. -These functions differ from the non-secure versions only in that the secure versions check that the *format* string contains valid formatting characters. +These functions differ from the non-secure versions only in that the secure versions check that the *`format`* string contains valid formatting characters. -**vfwprintf_s** is the wide-character version of **vfprintf_s**; the two functions behave identically if the stream is opened in ANSI mode. **vfprintf_s** doesn't currently support output into a UNICODE stream. +**`vfwprintf_s`** is the wide-character version of **`vfprintf_s`**; the two functions behave identically if the stream is opened in ANSI mode. **`vfprintf_s`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf_s**|**vfprintf_s**|**vfprintf_s**|**vfwprintf_s**| -|**_vftprintf_s_l**|**_vfprintf_s_l**|**_vfprintf_s_l**|**_vfwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf_s` | **`vfprintf_s`** | **`vfprintf_s`** | **`vfwprintf_s`** | +| `_vftprintf_s_l` | **`_vfprintf_s_l`** | **`_vfprintf_s_l`** | **`_vfwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vfprintf_s**, **_vfprintf_s_l**|\ and \|\*| -|**vfwprintf_s**, **_vfwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vfprintf_s`**, **`_vfprintf_s_l`** | \ and \ | \* | +| **`vfwprintf_s`**, **`_vfwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md b/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md index f1a4211619..f4860772c9 100644 --- a/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md +++ b/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md @@ -6,12 +6,12 @@ api_name: ["_vfprintf_l", "vfprintf", "vfwprintf", "_vfwprintf_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfwprintf", "_vftprintf", "vfprintf"] +f1_keywords: ["STDIO/vfprintf", "STDIO/_vfprintf_l", "CORECRT_WSTDIO/vfwprintf", "CORECRT_WSTDIO/_vfwprintf_l", "TCHAR/_vftprintf", "TCHAR/_vftprintf_l", "vfprintf", "_vfprintf_l", "vfwprintf", "_vfwprintf_l", "_vftprintf", "_vftprintf_l"] helpviewer_keywords: ["_vfwprintf_l function", "_vftprintf function", "vfprintf function", "_vftprintf_l function", "vfprintf_l function", "vftprintf_l function", "vfwprintf_l function", "vftprintf function", "vfwprintf function", "_vfprintf_l function", "formatted text [C++]"] --- -# vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l +# `vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l` -Write formatted output using a pointer to a list of arguments. More secure versions of these functions exist; see [vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md). +Write formatted output using a pointer to a list of arguments. More secure versions of these functions exist; see [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md). ## Syntax @@ -42,61 +42,61 @@ int _vfwprintf_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vfprintf** and **vfwprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vfprintf`** and **`vfwprintf`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *`stream`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. -**vfwprintf** is the wide-character version of **vfprintf**; the two functions behave identically if the stream is opened in ANSI mode. **vfprintf** doesn't currently support output into a UNICODE stream. +**`vfwprintf`** is the wide-character version of **`vfprintf`**; the two functions behave identically if the stream is opened in ANSI mode. **`vfprintf`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf**|**vfprintf**|**vfprintf**|**vfwprintf**| -|**_vftprintf_l**|**_vfprintf_l**|**_vfprintf_l**|**_vfwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf` | **`vfprintf`** | **`vfprintf`** | **`vfwprintf`** | +| `_vftprintf_l` | **`_vfprintf_l`** | **`_vfprintf_l`** | **`_vfwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vfprintf**, **_vfprintf_l**|\ and \|\*| -|**vfwprintf**, **_vfwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vfprintf`**, **`_vfprintf_l`** | \ and \ | \* | +| **`vfwprintf`**, **`_vfwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md b/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md index c544c87d2f..4f1a7f8930 100644 --- a/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md +++ b/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vfscanf_s", "vfwscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfscanf_s", "vfwscanf_s", "_vftscanf_s"] +f1_keywords: ["STDIO/vfscanf_s", "CORECRT_WSTDIO/vfwscanf_s", "TCHAR/_vftscanf_s", "vfscanf_s", "vfwscanf_s", "_vftscanf_s"] ms.assetid: 9b0133f0-9a18-4581-b24b-3b72683ad432 --- -# vfscanf_s, vfwscanf_s +# `vfscanf_s`, `vfwscanf_s` -Reads formatted data from a stream. These versions of vfscanf, vfwscanf have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a stream. These versions of vfscanf, vfwscanf have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -30,44 +30,44 @@ int vfwscanf_s( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **vfscanf_s** and **vfwscanf_s**. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`vfscanf_s`** and **`vfwscanf_s`**. -These functions validate their parameters. If *stream* is an invalid file pointer, or *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* is an invalid file pointer, or *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **vfscanf_s** function reads data from the current position of *stream* into the locations that are given by the *arglist* argument list (if any). Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf_s**; see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md) for a description of *format*. **vfwscanf_s** is a wide-character version of **vfscanf_s**; the format argument to **vfwscanf_s** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **vfscanf_s** doesn't currently support input from a UNICODE stream. +The **`vfscanf_s`** function reads data from the current position of *`stream`* into the locations that are given by the *`arglist`* argument list (if any). Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for `scanf_s`; see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md) for a description of *`format`*. **`vfwscanf_s`** is a wide-character version of **`vfscanf_s`**; the format argument to **`vfwscanf_s`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`vfscanf_s`** doesn't currently support input from a UNICODE stream. -The main difference between the more secure functions (that have the **_s** suffix) and the other versions is that the more secure functions require the size in characters of each **c**, **C**, **s**, **S**, and **[** type field to be passed as an argument immediately following the variable. For more information, see [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +The main difference between the more secure functions (that have the **`_s`** suffix) and the other versions is that the more secure functions require the size in characters of each **`c`**, **`C`**, **`s`**, **`S`**, and **`[`** type field to be passed as an argument immediately following the variable. For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` width specification](../scanf-width-specification.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf_s**|**vfscanf_s**|**vfscanf_s**|**vfwscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftscanf_s` | **`vfscanf_s`** | **`vfscanf_s`** | **`vfwscanf_s`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**vfscanf_s**|\| -|**vfwscanf_s**|\ or \| +| Function | Required header | +|---|---| +| **`vfscanf_s`** | \ | +| **`vfwscanf_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -139,10 +139,10 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[vfscanf, vfwscanf](vfscanf-vfwscanf.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`vfscanf`, `vfwscanf`](vfscanf-vfwscanf.md) diff --git a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md index 996c9b964f..152140dd56 100644 --- a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md +++ b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md @@ -6,12 +6,12 @@ api_name: ["vfwscanf", "vfscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfwscanf", "_vftscanf", "vfscanf"] +f1_keywords: ["STDIO/vfscanf", "CORECRT_WSTDIO/vfwscanf", "TCHAR/_vftscanf", "vfscanf", "vfwscanf", "_vftscanf"] ms.assetid: c06450ef-03f1-4d24-a8ac-d2dd98847918 --- -# vfscanf, vfwscanf +# `vfscanf`, `vfwscanf` -Reads formatted data from a stream. More secure versions of these functions are available; see [vfscanf_s, vfwscanf_s](vfscanf-s-vfwscanf-s.md). +Reads formatted data from a stream. More secure versions of these functions are available; see [`vfscanf_s`, `vfwscanf_s`](vfscanf-s-vfwscanf-s.md). ## Syntax @@ -30,43 +30,43 @@ int vfwscanf( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that are read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **vfscanf** and **vfwscanf**. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that are read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`vfscanf`** and **`vfwscanf`**. -These functions validate their parameters. If *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **vfscanf** function reads data from the current position of *stream* into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf**; see [scanf](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *format*. +The **`vfscanf`** function reads data from the current position of *`stream`* into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for `scanf`; see [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *`format`*. -**vfwscanf** is a wide-character version of **vfscanf**; the format argument to **vfwscanf** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **vfscanf** doesn't support input from a UNICODE stream. +**`vfwscanf`** is a wide-character version of **`vfscanf`**; the format argument to **`vfwscanf`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`vfscanf`** doesn't support input from a UNICODE stream. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf**|**vfscanf**|**vfscanf**|**vfwscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftscanf` | **`vfscanf`** | **`vfscanf`** | **`vfwscanf`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**vfscanf**|\| -|**vfwscanf**|\ or \| +| Function | Required header | +|---|---| +| **`vfscanf`** | \ | +| **`vfwscanf`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
-[vfscanf_s, vfwscanf_s](vfscanf-s-vfwscanf-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)\ +[`vfscanf_s`, `vfwscanf_s`](vfscanf-s-vfwscanf-s.md) diff --git a/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md b/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md index d469f73b45..e3ea98113a 100644 --- a/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md +++ b/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md @@ -6,10 +6,10 @@ api_name: ["_vwprintf_p", "_vprintf_p", "_vprintf_p_l", "_vwprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vwprintf_p_l", "vprintf_p", "_vprintf_p_l", "_vwprintf_p", "vprintf_p_l", "vwprintf_p_l", "vwprintf_p", "vtprintf_p", "_vtprintf_p", "_vprintf_p"] +f1_keywords: ["STDIO/_vprintf_p", "STDIO/_vprintf_p_l", "CORECRT_WSTDIO/_vwprintf_p","CORECRT_WSTDIO/_vwprintf_p_l", "TCHAR/_vtprintf_p", "TCHAR/_vtprintf_p_l", "_vprintf_p", "_vprintf_p_l", "_vwprintf_p", "_vwprintf_p_l", "_vtprintf_p", "_vtprintf_p_l"] helpviewer_keywords: ["_vtprintf_p_l function", "_vtprintf_p function", "vtprintf_p function", "_vwprintf_p function", "_vwprintf_p_l function", "_vprintf_p function", "_vprintf_p_l function", "vprintf_p_l function", "vwprintf_p function", "vprintf_p function", "vtprintf_p_l function", "vwprintf_p_l function", "formatted text [C++]"] --- -# _vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l +# `_vprintf_p`, `_vprintf_p_l`, `_vwprintf_p`, `_vwprintf_p_l` Writes formatted output by using a pointer to a list of arguments, and enables specification of the order in which the arguments are used. @@ -38,62 +38,62 @@ int _vwprintf_p_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vprintf_p** and **_vwprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vprintf_p`** and **`_vwprintf_p`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. These functions differ from **vprintf_s** and **vwprintf_s** only in that they support the ability to specify the order in which the arguments are used. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. These functions differ from `vprintf_s` and `vwprintf_s` only in that they support the ability to specify the order in which the arguments are used. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_vwprintf_p** is the wide-character version of **_vprintf_p**; the two functions behave identically if the stream is opened in ANSI mode. **_vprintf_p** doesn't currently support output into a UNICODE stream. +**`_vwprintf_p`** is the wide-character version of **`_vprintf_p`**; the two functions behave identically if the stream is opened in ANSI mode. **`_vprintf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf_p**|**_vprintf_p**|**_vprintf_p**|**_vwprintf_p**| -|**_vtprintf_p_l**|**_vprintf_p_l**|**_vprintf_p_l**|**_vwprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf_p` | **`_vprintf_p`** | **`_vprintf_p`** | **`_vwprintf_p`** | +| `_vtprintf_p_l` | **`_vprintf_p_l`** | **`_vprintf_p_l`** | **`_vwprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vprintf_p**, **_vprintf_p_l**|\ and \|\*| -|**_vwprintf_p**, **_vwprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vprintf_p`**, **`_vprintf_p_l`** | \ and \ | \* | +| **`_vwprintf_p`**, **`_vwprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
-[vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)\ +[`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md b/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md index 90a77d0fe2..9b7f90e5ef 100644 --- a/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md @@ -6,12 +6,12 @@ api_name: ["_vwprintf_s_l", "vwprintf_s", "_vprintf_s_l", "vprintf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vprintf_s", "vwprintf_s", "_vtprintf_s"] +f1_keywords: ["STDIO/vprintf_s", "STDIO/_vprintf_s_l", "CORECRT_WSTDIO/vwprintf_s", "CORECRT_WSTDIO/_vwprintf_s_l", "TCHAR/_vtprintf_s", "TCHAR/_vtprintf_s_l", "vprintf_s", "_vprintf_s_l", "vwprintf_s", "_vwprintf_s_l", "_vtprintf_s", "_vtprintf_s_l"] helpviewer_keywords: ["vwprintf_s_l function", "_vwprintf_s_l function", "vwprintf_s function", "_vtprintf_s_l function", "vprintf_s_l function", "vtprintf_s_l function", "_vtprintf_s function", "vtprintf_s function", "_vprintf_s_l function", "formatted text [C++]", "vprintf_s function"] --- -# vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l +# `vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l` -Writes formatted output by using a pointer to a list of arguments. These versions of [vprintf, _vprintf_l, vwprintf, _vwprintf_l](vprintf-vprintf-l-vwprintf-vwprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Writes formatted output by using a pointer to a list of arguments. These versions of [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](vprintf-vprintf-l-vwprintf-vwprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -38,60 +38,60 @@ int _vwprintf_s_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vprintf_s** and **vwprintf_s** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vprintf_s`** and **`vwprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. -The secure versions of these functions differ from **vprintf** and **vwprintf** only in that the secure versions check that the format string contains valid formatting characters. +The secure versions of these functions differ from `vprintf` and `vwprintf` only in that the secure versions check that the format string contains valid formatting characters. -**vwprintf_s** is the wide-character version of **vprintf_s**; the two functions behave identically if the stream is opened in ANSI mode. **vprintf_s** doesn't currently support output into a UNICODE stream. +**`vwprintf_s`** is the wide-character version of **`vprintf_s`**; the two functions behave identically if the stream is opened in ANSI mode. **`vprintf_s`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf_s**|**vprintf_s**|**vprintf_s**|**vwprintf_s**| -|**_vtprintf_s_l**|**_vprintf_s_l**|**_vprintf_s_l**|**_vwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf_s` | **`vprintf_s`** | **`vprintf_s`** | **`vwprintf_s`** | +| `_vtprintf_s_l` | **`_vprintf_s_l`** | **`_vprintf_s_l`** | **`_vwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vprintf_s**, **_vprintf_s_l**|\ and \|\*| -|**vwprintf_s**, **_vwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vprintf_s`**, **`_vprintf_s_l`** | \ and \ | \* | +| **`vwprintf_s`**, **`_vwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md b/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md index 229fa135a7..4575ef26d7 100644 --- a/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md +++ b/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md @@ -6,12 +6,12 @@ api_name: ["vprintf", "_vwprintf_l", "_vprintf_l", "vwprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vwprintf", "_vtprintf"] +f1_keywords: ["STDIO/vprintf", "STDIO/_vprintf_l", "CORECRT_WSTDIO/vwprintf", "CORECRT_WSTDIO/_vwprintf_l", "TCHAR/_vtprintf", "TCHAR/_vtprintf_l", "vprintf", "_vprintf_l", "vwprintf", "_vwprintf_l", "_vtprintf", "_vtprintf_l"] helpviewer_keywords: ["vwprintf function", "_vwprintf_l function", "vwprintf_l function", "_vtprintf function", "vtprintf_l function", "vprintf function", "_vprintf_l function", "vprintf_l function", "vtprintf function", "_vtprintf_l function", "formatted text [C++]"] --- -# vprintf, _vprintf_l, vwprintf, _vwprintf_l +# `vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l` -Writes formatted output by using a pointer to a list of arguments. More secure versions of these functions are available, see [vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l](vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md). +Writes formatted output by using a pointer to a list of arguments. More secure versions of these functions are available, see [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md). ## Syntax @@ -38,58 +38,58 @@ int _vwprintf_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vprintf** and **vwprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vprintf`** and **`vwprintf`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. -**vwprintf** is the wide-character version of **vprintf**; the two functions behave identically if the stream is opened in ANSI mode. **vprintf** doesn't currently support output into a UNICODE stream. +**`vwprintf`** is the wide-character version of **`vprintf`**; the two functions behave identically if the stream is opened in ANSI mode. **`vprintf`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Invalid format strings are detected and result in an error. +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Invalid format strings are detected and result in an error. > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf**|**vprintf**|**vprintf**|**vwprintf**| -|**_vtprintf_l**|**_vprintf_l**|**_vprintf_l**|**_vwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf` | **`vprintf`** | **`vprintf`** | **`vwprintf`** | +| `_vtprintf_l` | **`_vprintf_l`** | **`_vprintf_l`** | **`_vwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vprintf**, **_vprintf_l**|\ and \|\*| -|**vwprintf**, **_vwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vprintf`**, **`_vprintf_l`** | \ and \ | \* | +| **`vwprintf`**, **`_vwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md b/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md index 9e2330b935..4494f96ba1 100644 --- a/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md +++ b/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vscanf_s", "vwscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vtscanf_s", "vscanf_s", "vwscanf_s"] +f1_keywords: ["STDIO/vscanf_s", "CORECRT_WSTDIO/vwscanf_s", "TCHAR/_vtscanf_s", "vscanf_s", "vwscanf_s", "_vtscanf_s"] ms.assetid: 23a1c383-5b01-4887-93ce-534a1e38ed93 --- -# vscanf_s, vwscanf_s +# `vscanf_s`, `vwscanf_s` -Reads formatted data from the standard input stream. These versions of [vscanf, vwscanf](vscanf-vwscanf.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the standard input stream. These versions of [`vscanf`, `vwscanf`](vscanf-vwscanf.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -28,49 +28,49 @@ int vwscanf_s( ### Parameters -*format*
+*`format`*\ Format control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error, or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character. If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **vscanf_s** and **vwscanf_s** return **EOF** and set **errno** to **EINVAL**. +Returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error, or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character. If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`vscanf_s`** and **`vwscanf_s`** return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vscanf_s** function reads data from the standard input stream **stdin** and writes the data into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. If copying occurs between strings that overlap, the behavior is undefined. +The **`vscanf_s`** function reads data from the standard input stream `stdin` and writes the data into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. -**vwscanf_s** is a wide-character version of **vscanf_s**; the *format* argument to **vwscanf_s** is a wide-character string. **vwscanf_s** and **vscanf_s** behave identically if the stream is opened in ANSI mode. **vscanf_s** doesn't support input from a UNICODE stream. +**`vwscanf_s`** is a wide-character version of **`vscanf_s`**; the *`format`* argument to **`vwscanf_s`** is a wide-character string. **`vwscanf_s`** and **`vscanf_s`** behave identically if the stream is opened in ANSI mode. **`vscanf_s`** doesn't support input from a UNICODE stream. -Unlike **vscanf** and **vwscanf**, **vscanf_s** and **vwscanf_s** require the buffer size to be specified for all input parameters of type **c**, **C**, **s**, **S**, or string control sets that are enclosed in **[]**. The buffer size in characters is passed as an additional parameter immediately following the pointer to the buffer or variable. The buffer size in characters for a **`wchar_t`** string is not the same as the size in bytes. +Unlike `vscanf` and `vwscanf`, **`vscanf_s`** and **`vwscanf_s`** require the buffer size to be specified for all input parameters of type **c**, **C**, **s**, **S**, or string control sets that are enclosed in **[]**. The buffer size in characters is passed as another parameter immediately following the pointer to the buffer or variable. The buffer size in characters for a **`wchar_t`** string isn't the same as the size in bytes. -The buffer size includes the terminating null. You can use a width-specification field to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. You can use a width-specification field to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. > [!NOTE] -> The *size* parameter is of type **`unsigned`**, not **size_t**. +> The *`size`* parameter is of type **`unsigned`**, not `size_t`. -For more information, see [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +For more information, see [scanf Width Specification](../scanf-width-specification.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf_s**|**vscanf_s**|**vscanf_s**|**vwscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtscanf_s` | **`vscanf_s`** | **`vscanf_s`** | **`vwscanf_s`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vscanf_s**|\| -|**wscanf_s**|\ or \| +| Routine | Required header | +|---|---| +| **`vscanf_s`** | \ | +| **`wscanf_s`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[vscanf, vwscanf](vscanf-vwscanf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`vscanf`, `vwscanf`](vscanf-vwscanf.md) diff --git a/docs/c-runtime-library/reference/vscanf-vwscanf.md b/docs/c-runtime-library/reference/vscanf-vwscanf.md index ecf9c7b21f..043913e4b2 100644 --- a/docs/c-runtime-library/reference/vscanf-vwscanf.md +++ b/docs/c-runtime-library/reference/vscanf-vwscanf.md @@ -6,12 +6,12 @@ api_name: ["vscanf", "vwscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vscanf", "vwscanf", "_vtscanf"] +f1_keywords: ["STDIO/vscanf", "CORECRT_WSTDIO/vwscanf", "TCHAR/_vtscanf", "vscanf", "vwscanf", "_vtscanf"] ms.assetid: d1df595b-11bc-4682-9441-a92616301e3b --- -# vscanf, vwscanf +# `vscanf`, `vwscanf` -Reads formatted data from the standard input stream. More secure versions of these function are available; see [vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md). +Reads formatted data from the standard input stream. More secure versions of these functions are available; see [`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md). ## Syntax @@ -28,45 +28,45 @@ int vwscanf( ### Parameters -*format*
+*`format`*\ Format control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. +Returns the number of fields that are successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vscanf** function reads data from the standard input stream **stdin** and writes the data into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. If copying occurs between strings that overlap, the behavior is undefined. +The **`vscanf`** function reads data from the standard input stream `stdin` and writes the data into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When you use **vscanf** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. As an alternative, you can use [vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md) or [fgets](fgets-fgetws.md). +> When you use **`vscanf`** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. As an alternative, you can use [`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md) or [`fgets`](fgets-fgetws.md). -**vwscanf** is a wide-character version of **vscanf**; the *format* argument to **vwscanf** is a wide-character string. **vwscanf** and **vscanf** behave identically if the stream is opened in ANSI mode. **vscanf** doesn't support input from a UNICODE stream. +**`vwscanf`** is a wide-character version of **`vscanf`**; the *`format`* argument to **`vwscanf`** is a wide-character string. **`vwscanf`** and **`vscanf`** behave identically if the stream is opened in ANSI mode. **`vscanf`** doesn't support input from a UNICODE stream. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf**|**vscanf**|**vscanf**|**vwscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtscanf` | **`vscanf`** | **`vscanf`** | **`vwscanf`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vscanf**|\| -|**vwscanf**|\ or \| +| Routine | Required header | +|---|---| +| **`vscanf`** | \ | +| **`vwscanf`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,11 +125,11 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md) diff --git a/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md b/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md index 0e483b59b8..6f6910fcf6 100644 --- a/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md +++ b/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: _vscprintf_p, _vscprintf_p_l, _vscwprintf_p, _vscwprintf_p_l" title: "_vscprintf_p, _vscprintf_p_l, _vscwprintf_p, _vscwprintf_p_l" +description: "Learn more about: _vscprintf_p, _vscprintf_p_l, _vscwprintf_p, _vscwprintf_p_l" ms.date: "10/21/2021" api_name: ["_vscprintf_p_l", "_vscprintf_p", "_vscwprintf_p_l", "_vscwprintf_p"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vscprintf_p", "_vscprintf_p_l", "vscwprintf_p", "vscprintf_p", "vscwprintf_p_l", "_vscwprintf_p_l", "vscprintf_p_l", "_vscwprintf_p"] +f1_keywords: ["STDIO/_vscprintf_p", "STDIO/_vscprintf_p_l", "CORECRT_WSTDIO/_vscwprintf_p", "CORECRT_WSTDIO/_vscwprintf_p_l", "TCHAR/_vsctprintf_p", "TCHAR/_vsctprintf_p_l", "_vscprintf_p", "_vscprintf_p_l", "_vscwprintf_p", "_vscwprintf_p_l", "_vsctprintf_p", "_vsctprintf_p_l"] helpviewer_keywords: ["vscprintf_p function", "_vsctprintf_p_l function", "vscwprintf_p_l function", "_vscwprintf_p_l function", "_vscprintf_p function", "vsctprintf_p function", "_vscprintf_p_l function", "_vscwprintf_p function", "vscwprintf_p function", "vsctprintf_p_l function", "_vsctprintf_p function", "vscprintf_p_l function"] --- # `_vscprintf_p`, `_vscprintf_p_l`, `_vscwprintf_p`, `_vscwprintf_p_l` @@ -47,39 +47,42 @@ Pointer to list of arguments. *`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**`_vscprintf_p`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **`_vscwprintf_p`** performs the same function for wide characters. +**`_vscprintf_p`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_vscwprintf_p`** performs the same function for wide characters. ## Remarks -These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that they support the ability to specify the order in which the arguments are used. For more information, see [`printf_p` Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that they support the ability to specify the order in which the arguments are used. For more information, see [`printf_p` Positional Parameters](../printf-p-positional-parameters.md). The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **`errno`** to **`EINVAL`**. +Return Value is the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. + +If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] -> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsctprintf_p`**|**`_vscprintf_p`**|**`_vscprintf_p`**|**`_vscwprintf_p`**| -|**`_vsctprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscwprintf_p_l`**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_vsctprintf_p`** | **`_vscprintf_p`** | **`_vscprintf_p`** | **`_vscwprintf_p`** | +| **`_vsctprintf_p_l`** | **`_vscprintf_p_l`** | **`_vscprintf_p_l`** | **`_vscwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_vscprintf_p`**, **`_vscprintf_p_l`**|``| -|**`_vscwprintf_p`**, **`_vscwprintf_p_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_vscprintf_p`**, **`_vscprintf_p_l`** | `` | +| **`_vscwprintf_p`**, **`_vscwprintf_p_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,6 +90,6 @@ See the example for [`vsprintf`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswpr ## See also -[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)\ +[`vprintf` functions](../vprintf-functions.md)\ [`_scprintf_p`, `_scprintf_p_l`, `_scwprintf_p`, `_scwprintf_p_l`](scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md)\ -[`_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)\ +[`_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) diff --git a/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md b/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md index 4d999679dc..ac02613e06 100644 --- a/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md +++ b/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md @@ -6,10 +6,10 @@ api_name: ["_vscprintf", "_vscprintf_l", "_vscwprintf_l", "_vscwprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vscprintf_l", "vscwpeintf", "_vscwprintf", "_vsctprintf", "_vscprintf", "vscwprintf_l", "vscprintf", "_vscwprintf_l"] +f1_keywords: ["STDIO/_vscprintf", "STDIO/_vscprintf_l", "CORECRT_WSTDIO/_vscwprintf", "CORECRT_WSTDIO/_vscwprintf_l", "TCHAR/_vsctprintf", "TCHAR/_vsctprintf_l", "_vscprintf", "_vscprintf_l", "_vscwprintf", "_vscwprintf_l", "_vsctprintf", "_vsctprintf_l"] helpviewer_keywords: ["vsctprintf function", "_vscprintf_l function", "_vsctprintf_l function", "_vsctprintf function", "_vscwprintf_l function", "vscwprintf_l function", "_vscprintf function", "_vscwprintf function", "vscwprintf function", "vsctprintf_l function", "formatted text [C++]", "vscprintf function", "vscprintf_l function"] --- -# _vscprintf, _vscprintf_l, _vscwprintf, _vscwprintf_l +# `_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l` Returns the number of characters in the formatted string using a pointer to a list of arguments. @@ -38,59 +38,62 @@ int _vscwprintf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vscprintf** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_vscwprintf** performs the same function for wide characters. +**`_vscprintf`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_vscwprintf`** performs the same function for wide characters. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Return Value is the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. + +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). > [!IMPORTANT] -> Ensure that if *format* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vsctprintf**|**_vscprintf**|**_vscprintf**|**_vscwprintf**| -|**_vsctprintf_l**|**_vscprintf_l**|**_vscprintf_l**|**_vscwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsctprintf` | **`_vscprintf`** | **`_vscprintf`** | **`_vscwprintf`** | +| `_vsctprintf_l` | **`_vscprintf_l`** | **`_vscprintf_l`** | **`_vscwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_vscprintf**, **_vscprintf_l**|\| -|**_vscwprintf**, **_vscwprintf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_vscprintf`**, **`_vscprintf_l`** | \ | +| **`_vscwprintf`**, **`_vscwprintf_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [vsprintf](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md). +See the example for [`vsprintf`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md index 954e77bb95..096bc62882 100644 --- a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md @@ -1,17 +1,17 @@ --- description: "Learn more about: vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l" title: "vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l" -ms.date: "3/9/2021" +ms.date: 06/27/2023 api_name: ["_vsnwprintf_s", "_vsnwprintf_s_l", "_vsnprintf_s", "vsnprintf_s", "_vsnprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vsnprintf_s", "_vsntprintf_s", "_vsnwprintf_s"] +f1_keywords: ["STDIO/vsnprintf_s", "STDIO/_vsnprintf_s", "CORECRT_WSTDIO/_vsnwprintf_s", "TCHAR/_vsntprintf_s", "STDIO/_vsnprintf_s_l", "CORECRT_WSTDIO/_vsnwprintf_s_l", "TCHAR/_vsntprintf_s_l", "vsnprintf_s", "_vsnprintf_s", "_vsnwprintf_s", "_vsntprintf_s", "_vsnprintf_s_l", "_vsnwprintf_s_l", "_vsntprintf_s_l"] helpviewer_keywords: ["vsnwprintf_s function", "_vsntprintf_s function", "_vsntprintf_s_l function", "vsntprintf_s function", "vsnwprintf_s_l function", "vsnprintf_s_l function", "vsntprintf_s_l function", "_vsnwprintf_s_l function", "_vsnprintf_s function", "vsnprintf_s function", "_vsnprintf_s_l function", "_vsnwprintf_s function", "formatted text [C++]"] --- # `vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l` -Write formatted output using a pointer to a list of arguments. These are versions of [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -23,6 +23,7 @@ int vsnprintf_s( const char *format, va_list argptr ); + int _vsnprintf_s( char *buffer, size_t sizeOfBuffer, @@ -30,6 +31,7 @@ int _vsnprintf_s( const char *format, va_list argptr ); + int _vsnprintf_s_l( char *buffer, size_t sizeOfBuffer, @@ -38,6 +40,7 @@ int _vsnprintf_s_l( _locale_t locale, va_list argptr ); + int _vsnwprintf_s( wchar_t *buffer, size_t sizeOfBuffer, @@ -45,6 +48,7 @@ int _vsnwprintf_s( const wchar_t *format, va_list argptr ); + int _vsnwprintf_s_l( wchar_t *buffer, size_t sizeOfBuffer, @@ -53,6 +57,7 @@ int _vsnwprintf_s_l( _locale_t locale, va_list argptr ); + template int _vsnprintf_s( char (&buffer)[size], @@ -60,6 +65,7 @@ int _vsnprintf_s( const char *format, va_list argptr ); // C++ only + template int _vsnwprintf_s( wchar_t (&buffer)[size], @@ -71,88 +77,101 @@ int _vsnwprintf_s( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output. -*`sizeOfBuffer`*
-The size of the *`buffer`* for output, as the character count. +*`sizeOfBuffer`*\ +The size of the *`buffer`* for output. Size in **bytes** for the functions that take `char`, and **words** for those that take `wchar_t`. -*`count`*
-Maximum number of characters to write (not including the terminating null), or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +Maximum number of characters to write not including the terminating `NULL`. For the functions that take `wchar_t`, it's the number of wide characters to write. Or [`_TRUNCATE`](../truncate.md). -*`format`*
+*`format`*\ Format specification. -*`argptr`*
+*`argptr`*\ Pointer to list of arguments. -*`locale`*
-The locale to use. - -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). - -## Return Value +*`locale`*\ +The locale to use when formatting the output. -**`vsnprintf_s`**, **`_vsnprintf_s`** and **`_vsnwprintf_s`** return the number of characters written, not including the terminating null, or a negative value if either truncation of the data or an output error occurs. +For more information, see [Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md). -* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written and the number of characters is returned. +## Return value -* If *`count`* is less than *`sizeOfBuffer`* but the data exceeds *`count`* characters, then the first *`count`* characters are written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. +The number of characters written, not including the terminating `NULL`, or a negative value if an output error occurs. -* If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data equals or exceeds *`sizeOfBuffer`*, then as much of the string as will fit in *`buffer`* (with terminating null) is written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. - -* If *`count`* is equal to or exceeds *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. - -* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *buffer* to an empty string, set **`errno`** to **`ERANGE`**, and return -1. - -* If *`buffer`* or *`format`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. - -### Error Conditions - -|**Condition**|Return|**`errno`**| -|-----------------|------------|-------------| -|*`buffer`* is **`NULL`**|-1|**`EINVAL`**| -|*`format`* is **`NULL`**|-1|**`EINVAL`**| -|*`count`* <= 0|-1|**`EINVAL`**| -|*`sizeOfBuffer`* too small (and *`count`* != **`_TRUNCATE`**)|-1 (and *`buffer`* set to an empty string)|**`ERANGE`**| +See [Behavior summary](#behavior-summary) for details. ## Remarks -**`vsnprintf_s`** is identical to **`_vsnprintf_s`**. **`vsnprintf_s`** is included for conformance to the ANSI standard. **`_vnsprintf`** is retained for backward compatibility. - -Each of these functions takes a pointer to an argument list, then formats and writes up to *`count`* characters of the given data to the memory pointed to by *`buffer`* and appends a terminating null. +Each of these functions takes a pointer to an argument list, then formats and writes up to *`count`* characters of the given data to the memory pointed to by *`buffer`* and appends a terminating `NULL`. -If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md), then these functions write as much of the string as will fit in *`buffer`* while leaving room for a terminating null. If the entire string (with terminating null) fits in *`buffer`*, then these functions return the number of characters written (not including the terminating null); otherwise, these functions return -1 to indicate that truncation occurred. +In debug builds, the remaining `sizeOfBuffer` bytes following the terminating `NULL` are filled with 'xFE' as described in [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +**`vsnprintf_s`** is identical to **`_vsnprintf_s`** and is included for conformance to the ANSI standard. **`_vnsprintf`** is retained for backward compatibility. + +### Behavior summary + +For the following table: + +- Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). + +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler| +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string | The number of characters written | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ (42)` | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ (42)` | No | +| `buffer == NULL` and `sizeOfBuffer == 0` and `count == 0` | No data is written. | 0 | N/A | No | +| `buffer == NULL` and either `sizeOfBuffer != 0` or `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value.| -1 | `EINVAL` (22) | Yes | +| `buffer != NULL` and `sizeOfBuffer == 0` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | +| `buffer != NULL` and `sizeOfBuffer != 0` and `count == 0` | The buffer is `NULL` terminated. | -1 | N/A | No | +| `count == 0`| Doesn't write any data and returns the number of characters that would have been written, not including the terminating `NULL`. | The number of characters that would have been written not including the terminating `NULL`. | N/A | No | +| `count < 0` | Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count`* characters are written. | -1 | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` and `count != _TRUNCATE` | If execution continues after invalid parameter handler executes, sets `errno`, sets `buffer[0] == NULL`, and returns a negative value. | -1 | `ERANGE` (34) | Yes | +| `count == _TRUNCATE` and `len >= sizeOfBuffer` | Writes as much of the string as fits in *`buffer`*, including the terminating `NULL`. | -1 | N/A | No | +| `count == _TRUNCATE` and `len < sizeOfBuffer` | Writes the entire string into *`buffer`* with terminating `NULL`. | Number of characters written. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). + > [!IMPORTANT] -> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). > [!NOTE] -> To ensure that there is room for the terminating null, be sure that *`count`* is strictly less than the buffer length, or use **`_TRUNCATE`**. +> To ensure that there is room for the terminating `NULL`, be sure that *`count`* is strictly less than the buffer length, or use `_TRUNCATE`. + +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +> [!TIP] +> If you get an undefined external `_vsnprintf_s` error and are using the Universal C Runtime, add `legacy_stdio_definitions.lib` to the set of libraries to link. The Universal C Runtime doesn't export this function directly and is instead defined inline in ``. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md#libraries) and [Visual Studio 2015 conformance changes](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsntprintf_s`**|**`_vsnprintf_s`**|**`_vsnprintf_s`**|**`_vsnwprintf_s`**| -|**`_vsntprintf_s_l`**|**`_vsnprintf_s_l`**|**`_vsnprintf_s_l`**|**`_vsnwprintf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsntprintf_s` | **`_vsnprintf_s`** | **`_vsnprintf_s`** | **`_vsnwprintf_s`** | +| `_vsntprintf_s_l` | **`_vsnprintf_s_l`** | **`_vsnprintf_s_l`** | **`_vsnwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`vsnprintf_s`**|`` and ``|``*| -|**`_vsnprintf_s`**, **`_vsnprintf_s_l`**|`` and ``|``*| -|**`_vsnwprintf_s`**, **`_vsnwprintf_s_l`**|`` or ``, and ``|``*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsnprintf_s`** | `` and `` | ``* | +| **`_vsnprintf_s`**, **`_vsnprintf_s_l`** | `` and `` | ``* | +| **`_vsnwprintf_s`**, **`_vsnwprintf_s_l`** | `` or ``, and `` | ``* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -188,9 +207,9 @@ nSize: -1, buff: Hi there! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md index 15b2afda7d..1f94c8f59a 100644 --- a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md @@ -1,12 +1,12 @@ --- title: "vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l" description: "API reference for vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, and _vsnwprintf_l; which write formatted output using a pointer to a list of arguments." -ms.date: "3/9/2021" +ms.date: 06/27/2023 api_name: ["_vsnprintf", "_vsnprintf_l", "_vsnwprintf", "_vsnwprintf_l", "_vsnprintf", "_vsnprintf;", "vsnprintf; _vsnprintf", "_vsnwprintf;", "_vsnprintf_l;", "_vsnwprintf_l;"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vsnprintf", "_vsnwprintf", "_vsntprintf", "vsnprintf", "stdio/vsnprintf", "stdio/_vsnprintf", "stdio/_vsnprintf_l", "stdio/_vsnwprintf", "stdio/_vsnwprintf_l", "_vsnprintf_l", "_vsnwprintf_l"] +f1_keywords: ["STDIO/vsnprintf", "STDIO/_vsnprintf", "CORECRT_WSTDIO/_vsnwprintf", "TCHAR/_vsntprintf", "STDIO/_vsnprintf_l", "CORECRT_WSTDIO/_vsnwprintf_l", "TCHAR/_vsntprintf_l", "vsnprintf", "_vsnprintf", "_vsnwprintf", "_vsntprintf", "_vsnprintf_l", "_vsnwprintf_l", "_vsntprintf_l"] helpviewer_keywords: ["vsntprintf function", "_vsnwprintf_l function", "vsnwprintf_l function", "vsntprintf_l function", "_vsntprintf function", "_vsnprintf_l function", "vsnprintf function", "_vsntprintf_l function", "vsnprintf_l function", "_vsnwprintf function", "_vsnprintf function", "formatted text [C++]", "vsnwprintf function"] --- # `vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l` @@ -22,12 +22,14 @@ int vsnprintf( const char *format, va_list argptr ); + int _vsnprintf( char *buffer, size_t count, const char *format, va_list argptr ); + int _vsnprintf_l( char *buffer, size_t count, @@ -35,12 +37,14 @@ int _vsnprintf_l( _locale_t locale, va_list argptr ); + int _vsnwprintf( wchar_t *buffer, size_t count, const wchar_t *format, va_list argptr ); + int _vsnwprintf_l( wchar_t *buffer, size_t count, @@ -48,6 +52,7 @@ int _vsnwprintf_l( _locale_t locale, va_list argptr ); + template int vsnprintf( char (&buffer)[size], @@ -55,6 +60,7 @@ int vsnprintf( const char *format, va_list argptr ); // C++ only + template int _vsnprintf( char (&buffer)[size], @@ -62,6 +68,7 @@ int _vsnprintf( const char *format, va_list argptr ); // C++ only + template int _vsnprintf_l( char (&buffer)[size], @@ -70,6 +77,7 @@ int _vsnprintf_l( _locale_t locale, va_list argptr ); // C++ only + template int _vsnwprintf( wchar_t (&buffer)[size], @@ -77,6 +85,7 @@ int _vsnwprintf( const wchar_t *format, va_list argptr ); // C++ only + template int _vsnwprintf_l( wchar_t (&buffer)[size], @@ -89,69 +98,89 @@ int _vsnwprintf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output. -*`count`*
-Maximum number of characters to write. +*`count`*\ +Maximum number of characters to write. For the functions that take `wchar_t`, it's the number of wide characters to write. -*`format`*
+*`format`*\ Format specification. -*`argptr`*
+*`argptr`*\ Pointer to list of arguments. -*`locale`*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The **`vsnprintf`** function returns the number of characters that are written, not counting the terminating null character. If the buffer size specified by *`count`* isn't sufficiently large to contain the output specified by *`format`* and *`argptr`*, the return value of **`vsnprintf`** is the number of characters that would be written, not counting the null character, if *`count`* were sufficiently large. If the return value is greater than *`count`* - 1, the output has been truncated. A return value of -1 indicates that an encoding error has occurred. +The number of characters written, not including the terminating `NULL`, or a negative value if an output error occurs. -Both **`_vsnprintf`** and **`_vsnwprintf`** functions return the number of characters written if the number of characters to write is less than or equal to *`count`*. If the number of characters to write is greater than *`count`*, these functions return -1 indicating that output has been truncated. - -The value returned by all these functions doesn't include the terminating null, whether one is written or not. - -- If *`count`* is zero and *`buffer`* is **`NULL`**, the value returned is the number of characters the functions would write. The value does not take into account a terminating **`NULL`**. You can use this result to allocate sufficient buffer space for the string and its terminating null, and then call the function again to fill the buffer. -- If *`count`* is zero but *`buffer`* isn't **`NULL`**, nothing is written and the function returns `-1`. -- If *`format`* is **`NULL`**, or if *`buffer`* is **`NULL`** and *count* isn't equal to zero, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +See [Behavior summary](#behavior-summary) for details. ## Remarks -Each of these functions takes a pointer to an argument list, then formats the data, and writes up to *`count`* characters to the memory pointed to by *`buffer`*. The **`vsnprintf`** function always writes a null terminator, even if it truncates the output. When using **`_vsnprintf`** and **`_vsnwprintf`**, the buffer will be null-terminated only if there's room at the end (that is, if the number of characters to write is less than *`count`*). +Each of these functions takes a pointer to an argument list, then formats the data, and writes up to *`count`* characters to the memory pointed to by *`buffer`*. The **`vsnprintf`** function always writes a null terminator, even if it truncates the output. When you use **`_vsnprintf`** and **`_vsnwprintf`**, the buffer is null-terminated only if there's room at the end (that is, if the number of characters to write is less than *`count`*). + +Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`vsnprintf`** is no longer identical to **`_vsnprintf`**. The **`vsnprintf`** function conforms to the C99 standard; **`_vsnprintf`** is kept for backward compatibility with older code. The difference is that if you run out of buffer, `vsnprintf` null-terminates the end of the buffer and returns the number of characters that would have been required, while `_vsnprintf` doesn't null-terminate the buffer and returns -1. Also, `_vsnprintf()` includes one more character in the output because it doesn't null-terminate the buffer. > [!IMPORTANT] -> To prevent certain kinds of security risks, ensure that *format* isn't a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> To prevent certain kinds of security risks, ensure that *`format`* isn't a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). > [!NOTE] > To ensure that there's room for the terminating null when calling **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`**, be sure that *`count`* is strictly less than the buffer length and initialize the buffer to null prior to calling the function. > -> Because **`vsnprintf`** always writes the terminating null, the *count* parameter may be equal to the size of the buffer. - -Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`vsnprintf`** is no longer identical to **`_vsnprintf`**. The **`vsnprintf`** function conforms to the C99 standard; **`_vnsprintf`** is kept for backward compatibility with older Visual Studio code. +> Because **`vsnprintf`** always writes a terminating null, the *`count`* parameter may be equal to the size of the buffer. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). + +### Behavior summary + +For the following table: + +- Let `sizeOfBuffer` be the size of `buffer`. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). + +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler| +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string. | The number of characters written, not counting the terminating null character. | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ` (42) | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ` (42) | No | +| `buffer == NULL` and `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value.| -1 | `EINVAL` (22) | Yes | +| `buffer == NULL` and `count == 0` | No data is written | The number of characters that would have been written, not including the terminating `NULL`. You can use this result to allocate sufficient buffer space for the string and a terminating `NULL`, and then call the function again to fill the buffer. | N/A | No | +| `count == 0` | No data is written | -1 | `ERANGE` (34) | No | +| `count < 0`| Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written. | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count-1`* characters are written followed by a null-terminator. | The number of characters that would have been written had `count` matched the number of characters to output, not including the null-terminator. | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` | Unsafe: overwrites the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsntprintf`**|**`_vsnprintf`**|**`_vsnprintf`**|**`_vsnwprintf`**| -|**`_vsntprintf_l`**|**`_vsnprintf_l`**|**`_vsnprintf_l`**|**`_vsnwprintf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsntprintf` | **`_vsnprintf`** | **`_vsnprintf`** | **`_vsnwprintf`** | +| `_vsntprintf_l` | **`_vsnprintf_l`** | **`_vsnprintf_l`** | **`_vsnwprintf_l`** | ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------------|-------------------------------| -|**`vsnprintf`**, **`_vsnprintf`**, **`_vsnprintf_l`**|``|`` or ``| -|**`_vsnwprintf`**, **`_vsnwprintf_l`**|`` or ``|``, ``, ``, or ``| +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`vsnprintf`**, **`_vsnprintf`**, **`_vsnprintf_l`** | `` | `` or `` | +| **`_vsnwprintf`**, **`_vsnwprintf_l`** | `` or `` | ``, ``, ``, or `` | -The **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`** functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`** functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use wide characters with `_vsnwprintf()` @@ -233,10 +262,10 @@ nSize: 10, buff: Hi there! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md b/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md index 35fe461896..75116027f6 100644 --- a/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md +++ b/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md @@ -6,10 +6,10 @@ api_name: ["_vsprintf_p", "_vswprintf_p", "_vsprintf_p_l", "_vswprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vsprintf_p", "_vswprintf_p", "_vstprintf_p", "vswprintf_p", "_vsprintf_p", "vstprintf_p"] +f1_keywords: ["STDIO/_vsprintf_p", "CORECRT_WSTDIO/_vswprintf_p", "TCHAR/_vstprintf_p", "STDIO/_vsprintf_p_l", "CORECRT_WSTDIO/_vswprintf_p_l", "TCHAR/_vstprintf_p_l", "_vsprintf_p", "_vswprintf_p", "_vstprintf_p", "_vsprintf_p_l", "_vswprintf_p_l", "_vstprintf_p_l"] helpviewer_keywords: ["vstprintf_p_l function", "_vsprintf_p_l function", "_vstprintf_p function", "vsprintf_p_l function", "_vswprintf_p function", "vswprintf_p function", "vsprintf_p function", "vswprintf_p_l function", "_vswprintf_p_l function", "vstprintf_p function", "formatted text [C++]", "_vsprintf_p function", "_vstprintf_p_l function"] --- -# _vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l +# `_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l` Write formatted output using a pointer to a list of arguments, with the ability to specify the order in which the arguments are used. @@ -46,58 +46,60 @@ int _vswprintf_p_l( ### Parameters -*buffer*
+*`buffer`*\ Storage location for output. -*sizeInBytes*
-Size of *buffer* in characters. +*`sizeInBytes`*\ +Size of *`buffer`* in characters. -*count*
+*`count`*\ Maximum number of characters to store, in the UNICODE version of this function. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_vsprintf_p** and **_vswprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vsprintf_p`** and **`_vswprintf_p`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. +If the *`buffer`* is a `NULL` pointer and *`sizeInBytes`* or *`count`* are zero, functions return the number of characters that would have been written not including the terminating `NULL`. +If the *`buffer`* is valid and *`sizeInBytes`* or *`count`* are zero, returns -1. ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *buffer*. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *`buffer`*. -These functions differ from the **vsprintf_s** and **vswprintf_s** only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from the `vsprintf_s` and `vswprintf_s` only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If the *buffer* or *format* parameters are **NULL** pointers, if count is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If the *`buffer`* or *`format`* parameters are `NULL` pointers, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstprintf_p**|**_vsprintf_p**|**_vsprintf_p**|**_vswprintf_p**| -|**_vstprintf_p_l**|**_vsprintf_p_l**|**_vsprintf_p_l**|**_vswprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf_p` | **`_vsprintf_p`** | **`_vsprintf_p`** | **`_vswprintf_p`** | +| `_vstprintf_p_l` | **`_vsprintf_p_l`** | **`_vsprintf_p_l`** | **`_vswprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vsprintf_p**, **_vsprintf_p_l**|\ and \|\*| -|**_vswprintf_p**, **_vswprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vsprintf_p`**, **`_vsprintf_p_l`** | \ and \ | \* | +| **`_vswprintf_p`**, **`_vswprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,10 +152,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md b/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md index fd7c5f92f2..991b132063 100644 --- a/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md +++ b/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md @@ -1,17 +1,19 @@ --- description: "Learn more about: vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l" -title: "vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l" +title: "vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l, _vstprintf_s, _vstprintf_s_l" ms.date: "3/9/2021" -api_name: ["_vswprintf_s_l", "vsprintf_s", "vswprintf_s", "_vsprintf_s_l"] +api_name: ["_vswprintf_s_l", "vsprintf_s", "vswprintf_s", "_vsprintf_s_l", _vstprintf_s, _vstprintf_s_l] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vswprintf_s", "vsprintf_s", "_vstprintf_s"] +f1_keywords: ["CORECRT_WSTDIO/vswprintf_s", "STDIO/vsprintf_s", "TCHAR/_vstprintf_s", "vswprintf_s", "vsprintf_s", "_vstprintf_s", "_vstprintf_s_l", "_vswprintf_s_l"] helpviewer_keywords: ["_vstprintf_s_l function", "vsprintf_s_l function", "_vstprintf_s function", "vswprintf_s function", "vstprintf_s function", "vstprintf_s_l function", "vswprintf_s_l function", "vsprintf_s function", "_vsprintf_s_l function", "formatted text [C++]", "_vswprintf_s_l function"] --- -# vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l +# `vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`, `_vstprintf_s`, `_vstprintf_s_l` -Write formatted output using a pointer to a list of arguments. These functions are versions of [vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, \__vswprintf_l](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, \`__vswprintf_l`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). + +For `_vstprintf_s` and `_vstprintf_s_l`, see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -58,59 +60,61 @@ int vswprintf_s( ### Parameters -*buffer*
+*`buffer`*\ Storage location for output. -*numberOfElements*
-Size of *buffer* in characters. +*`numberOfElements`*\ +Size of *`buffer`* in characters. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**vsprintf_s** and **vswprintf_s** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *buffer* or *format* is a null pointer, if *numberOfElements* is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vsprintf_s`** and **`vswprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a null pointer, if *`numberOfElements`* is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *buffer*. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *`buffer`*. -**vswprintf_s** conforms to the ISO C Standard for **vswprintf**, which requires the second parameter, *count*, of type **size_t**. +**`vswprintf_s`** conforms to the ISO C Standard for **`vswprintf`**, which requires the second parameter, *`count`*, of type **`size_t`**. -These functions differ from the non-secure versions only in that the secure versions support positional parameters. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from the non-secure versions only in that the secure versions support positional parameters. For more information, see [`printf_p` Positional Parameters](../printf-p-positional-parameters.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, using these functions is simplified by template overloads. The overloads can infer buffer length automatically, eliminating the need to specify a size argument. And, they can automatically replace non-secure functions with their secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads. The overloads can infer buffer length automatically, eliminating the need to specify a size argument. And, they can automatically replace non-secure functions with their secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text function mappings + +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstprintf_s**|**vsprintf_s**|**vsprintf_s**|**vswprintf_s**| -|**_vstprintf_s_l**|**_vsprintf_s_l**|**_vsprintf_s_l**|**_vswprintf_s_l**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf_s` | `vsprintf_s` | `vsprintf_s` | `vswprintf_s` | +| `_vstprintf_s_l` | `_vsprintf_s_l` | `_vsprintf_s_l` | `_vswprintf_s_l` | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vsprintf_s**, **_vsprintf_s_l**|\ and \|\*| -|**vswprintf_s**, **_vswprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsprintf_s`**, **`_vsprintf_s_l`** | `` and `` | `*` | +| **`vswprintf_s`**, **`_vswprintf_s_l`** | `` or ``, and `` | `*` | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -157,10 +161,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md) +[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md index b152b51921..b3296103ad 100644 --- a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md +++ b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md @@ -6,12 +6,12 @@ api_name: ["_vswprintf_l", "_vsprintf_l", "vsprintf", "vswprintf", "__vswprintf_ api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vstprintf", "vswprintf", "_vstprintf", "vsprintf", "__vswprintf_l", "_vsprintf_l", "_vswprintf_l", "vswprintf_l"] +f1_keywords: ["CORECRT_WSTDIO/vswprintf", "TCHAR/_vstprintf", "STDIO/vsprintf", "CORECRT_WSTDIO/__vswprintf_l", "STDIO/_vsprintf_l", "CORECRT_WSTDIO/_vswprintf_l", "vswprintf", "_vstprintf", "vsprintf", "__vswprintf_l", "_vsprintf_l", "_vswprintf_l"] helpviewer_keywords: ["__vswprintf_l function", "_vstprintf_l function", "formatted text", "vstprintf_l function", "_vswprintf_l function", "vsprintf_l function", "buffers, avoiding overruns", "buffer overruns", "vswprintf_l function", "buffers, buffer overruns", "vstprintf function", "_vsprintf_l function", "vswprintf function", "vsprintf function", "_vstprintf function"] --- -# vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l +# `vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l` -Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). +Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). ## Syntax @@ -76,58 +76,62 @@ int _vswprintf_l( ### Parameters -*buffer*\ +*`buffer`*\ Storage location for output. -*count*\ +*`count`*\ Maximum number of characters to store, in the wide string versions of this function. -*format*\ +*`format`*\ Format specification. -*argptr*\ +*`argptr`*\ Pointer to list of arguments. -*locale*\ +*`locale`*\ The locale to use. -## Return Value +## Return value -**vsprintf** and **vswprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *buffer* or *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +**`vsprintf`** and **`vswprintf`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a `NULL` pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If *`buffer`* is a `NULL` pointer and *`count`* is zero, **`vswprintf`** and **`_vswprintf_l`** return the number of characters that would have been written not including the terminating NULL. + +If *`buffer`* is valid and *`count`* is zero, **`vswprintf`** and **`_vswprintf_l`** return -1. The contents of *`buffer`* are unchanged. + +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *buffer*. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *`buffer`*. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Using **vsprintf**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [_vsnprintf](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [_vscprintf](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Using **`vsprintf`**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [`_vsnprintf`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [`_vscprintf`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). -**vswprintf** conforms to the ISO C Standard, which requires the second parameter, *count*, of type **size_t**. To force the old nonstandard behavior, define **_CRT_NON_CONFORMING_SWPRINTFS**. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. +**`vswprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define `_CRT_NON_CONFORMING_SWPRINTFS`. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstprintf**|**vsprintf**|**vsprintf**|**vswprintf**| -|**_vstprintf_l**|**_vsprintf_l**|**_vsprintf_l**|**_vswprintf_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf` | **`vsprintf`** | **`vsprintf`** | **`vswprintf`** | +| `_vstprintf_l` | **`_vsprintf_l`** | **`_vsprintf_l`** | **`_vswprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vsprintf**, **_vsprintf_l**|\ and \|\*| -|**vswprintf**, **_vswprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsprintf`**, **`_vsprintf_l`** | `` and `` | ``* | +| **`vswprintf`**, **`_vswprintf_l`** | `` or ``, and `` | ``* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -180,10 +184,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[vprintf Functions](../../c-runtime-library/vprintf-functions.md)\ -[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ -[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ -[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)\ -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ -[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md) +[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md b/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md index d0f8aac3d1..2ba236d426 100644 --- a/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md +++ b/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vswscanf_s", "vsscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vsscanf_s", "vswscanf_s", "_vstscanf_s"] +f1_keywords: ["STDIO/vsscanf_s", "CORECRT_WSTDIO/vswscanf_s", "TCHAR/_vstscanf_s", "vsscanf_s", "vswscanf_s", "_vstscanf_s"] ms.assetid: 7b732e68-c6f4-4579-8917-122f5a7876e1 --- -# vsscanf_s, vswscanf_s +# `vsscanf_s`, `vswscanf_s` -Reads formatted data from a string. These versions of [vsscanf, vswscanf](vsscanf-vswscanf.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a string. These versions of [`vsscanf`, `vswscanf`](vsscanf-vswscanf.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -30,52 +30,52 @@ int vswscanf_s( ### Parameters -*buffer*
+*`buffer`*\ Stored data -*format*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *buffer* or *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vsscanf_s** function reads data from *buffer* into the locations that are given by each argument in the *arglist* argument list. The arguments in the argument list specify pointers to variables that have a type that corresponds to a type specifier in *format*. Unlike the less secure version **vsscanf**, a buffer size parameter is required when you use the type field characters **c**, **C**, **s**, **S**, or string-control sets that are enclosed in **[]**. The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. +The **`vsscanf_s`** function reads data from *`buffer`* into the locations that are given by each argument in the *`arglist`* argument list. The arguments in the argument list specify pointers to variables that have a type that corresponds to a type specifier in *`format`*. Unlike the less secure version **`vsscanf`**, a buffer size parameter is required when you use the type field characters **c**, **C**, **s**, **S**, or string-control sets that are enclosed in **[]**. The buffer size in characters must be supplied as another parameter immediately after each buffer parameter that requires it. -The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. -For more information, see [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Type Field Characters](../../c-runtime-library/scanf-type-field-characters.md). +For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Type Field Characters](../scanf-type-field-characters.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -The *format* argument controls the interpretation of the input fields and has the same form and function as the *format* argument for the **scanf_s** function. If copying occurs between strings that overlap, the behavior is undefined. +The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the `scanf_s` function. If copying occurs between strings that overlap, the behavior is undefined. -**vswscanf_s** is a wide-character version of **vsscanf_s**; the arguments to **vswscanf_s** are wide-character strings. **vsscanf_s** does not handle multibyte hexadecimal characters. **vswscanf_s** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **vswscanf_s** and **vsscanf_s** behave identically. +**`vswscanf_s`** is a wide-character version of **`vsscanf_s`**; the arguments to **`vswscanf_s`** are wide-character strings. **`vsscanf_s`** doesn't handle multibyte hexadecimal characters. **`vswscanf_s`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`vswscanf_s`** and **`vsscanf_s`** behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf_s**|**vsscanf_s**|**vsscanf_s**|**vswscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstscanf_s` | **`vsscanf_s`** | **`vsscanf_s`** | **`vswscanf_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vsscanf_s**|\| -|**vswscanf_s**|\ or \| +| Routine | Required header | +|---|---| +| **`vsscanf_s`** | \ | +| **`vswscanf_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -131,9 +131,9 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[vsscanf, vswscanf](vsscanf-vswscanf.md)
+[Stream I/O](../stream-i-o.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vsscanf`, `vswscanf`](vsscanf-vswscanf.md) diff --git a/docs/c-runtime-library/reference/vsscanf-vswscanf.md b/docs/c-runtime-library/reference/vsscanf-vswscanf.md index 118fbd3d9a..456e5cf8ad 100644 --- a/docs/c-runtime-library/reference/vsscanf-vswscanf.md +++ b/docs/c-runtime-library/reference/vsscanf-vswscanf.md @@ -6,13 +6,13 @@ api_name: ["vsscanf", "vswscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vstscanf", "vsscanf", "vswscanf"] +f1_keywords: ["TCHAR/_vstscanf", "STDIO/vsscanf", "CORECRT_WSTDIO/vswscanf", "_vstscanf", "vsscanf", "vswscanf"] helpviewer_keywords: ["vswscanf function", "vsscanf function"] ms.assetid: e96180f2-df46-423d-b4eb-0a49ab819bde --- -# vsscanf, vswscanf +# `vsscanf`, `vswscanf` -Reads formatted data from a string. More secure versions of these functions are available; see [vsscanf_s, vswscanf_s](vsscanf-s-vswscanf-s.md). +Reads formatted data from a string. More secure versions of these functions are available; see [`vsscanf_s`, `vswscanf_s`](vsscanf-s-vswscanf-s.md). ## Syntax @@ -31,46 +31,46 @@ int vswscanf( ### Parameters -*buffer*
+*`buffer`*\ Stored data -*format*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *buffer* or *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vsscanf** function reads data from *buffer* into the locations that are given by each argument in the *arglist* argument list. Every argument in the list must be a pointer to a variable that has a type that corresponds to a type specifier in *format*. The *format* argument controls the interpretation of the input fields and has the same form and function as the *format* argument for the **scanf** function. If copying takes place between strings that overlap, the behavior is undefined. +The **`vsscanf`** function reads data from *`buffer`* into the locations that are given by each argument in the *`arglist`* argument list. Every argument in the list must be a pointer to a variable that has a type that corresponds to a type specifier in *`format`*. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the `scanf` function. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When you use **vsscanf** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. +> When you use **`vsscanf`** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. -**vswscanf** is a wide-character version of **vsscanf**; the arguments to **vswscanf** are wide-character strings. **vsscanf** does not handle multibyte hexadecimal characters. **vswscanf** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **vswscanf** and **vsscanf** behave identically. +**`vswscanf`** is a wide-character version of **`vsscanf`**; the arguments to **`vswscanf`** are wide-character strings. **`vsscanf`** doesn't handle multibyte hexadecimal characters. **`vswscanf`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`vswscanf`** and **`vsscanf`** behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf**|**vsscanf**|**vsscanf**|**vswscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstscanf` | **`vsscanf`** | **`vsscanf`** | **`vswscanf`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vsscanf**|\| -|**vswscanf**|\ or \| +| Routine | Required header | +|---|---| +| **`vsscanf`** | \ | +| **`vswscanf`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,8 +125,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[vsscanf_s, vswscanf_s](vsscanf-s-vswscanf-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vsscanf_s`, `vswscanf_s`](vsscanf-s-vswscanf-s.md) diff --git a/docs/c-runtime-library/reference/wcrtomb-s.md b/docs/c-runtime-library/reference/wcrtomb-s.md index d618624470..3f0b1ca8b4 100644 --- a/docs/c-runtime-library/reference/wcrtomb-s.md +++ b/docs/c-runtime-library/reference/wcrtomb-s.md @@ -3,16 +3,16 @@ description: "Learn more about: wcrtomb_s" title: "wcrtomb_s" ms.date: "4/2/2020" api_name: ["wcrtomb_s", "_o_wcrtomb_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcrtomb_s"] +f1_keywords: ["WCHAR/wcrtomb_s", "wcrtomb_s"] helpviewer_keywords: ["wide characters, converting", "wcrtomb_s function", "multibyte characters", "characters, converting"] ms.assetid: 9a8a1bd0-1d60-463d-a3a2-d83525eaf656 --- -# wcrtomb_s +# `wcrtomb_s` -Convert a wide character into its multibyte character representation. A version of [wcrtomb](wcrtomb.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a wide character into its multibyte character representation. A version of [`wcrtomb`](wcrtomb.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -35,40 +35,40 @@ errno_t wcrtomb_s( ### Parameters -*pReturnValue*
+*`pReturnValue`*\ Returns the number of bytes written or -1 if an error occurred. -*mbchar*
+*`mbchar`*\ The resulting multibyte converted character. -*sizeOfmbchar*
-The size of the *mbchar* variable in bytes. +*`sizeOfmbchar`*\ +The size of the *`mbchar`* variable in bytes. -*wchar*
+*`wchar`*\ A wide character to convert. -*mbstate*
-A pointer to an **mbstate_t** object. +*`mbstate`*\ +A pointer to an `mbstate_t` object. -## Return Value +## Return value -Returns zero or an **errno** value if an error occurs. +Returns zero or an `errno` value if an error occurs. ## Remarks -The **wcrtomb_s** function converts a wide character, beginning in the specified conversion state contained in *mbstate*, from the value contained in *wchar*, into the address represented by *mbchar*. The *pReturnValue* value will be the number of bytes converted, but no more than **MB_CUR_MAX** bytes, or an -1 if an error occurred. +The **`wcrtomb_s`** function converts a wide character, beginning in the specified conversion state contained in *`mbstate`*, from the value contained in *`wchar`*, into the address represented by *`mbchar`*. The *`pReturnValue`* value will be the number of bytes converted, but no more than `MB_CUR_MAX` bytes, or an -1 if an error occurred. -If *mbstate* is null, the internal **mbstate_t** conversion state is used. If the character contained in *wchar* does not have a corresponding multibyte character, the value of *pReturnValue* will be -1 and the function will return the **errno** value of **EILSEQ**. +If *`mbstate`* is null, the internal `mbstate_t` conversion state is used. If the character contained in *`wchar`* doesn't have a corresponding multibyte character, the value of *`pReturnValue`* is -1, and the function returns the `errno` value of `EILSEQ`. -The **wcrtomb_s** function differs from [wctomb_s, _wctomb_s_l](wctomb-s-wctomb-s-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcslen**, if a subsequent call to **wcsrtombs_s** were used instead of **wcstombs_s**. +The **`wcrtomb_s`** function differs from [`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcslen`, if a subsequent call to `wcsrtombs_s` were used instead of `wcstombs_s`. -In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcrtomb_s** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is null. +The **`wcrtomb_s`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* is null. ## Example @@ -116,13 +116,13 @@ The corresponding wide character "Q" was converted to a the "Q" multibyte charac ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcrtomb_s**|\| +| Routine | Required header | +|---|---| +| **`wcrtomb_s`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcrtomb.md b/docs/c-runtime-library/reference/wcrtomb.md index 9b622df552..a88c83cdbe 100644 --- a/docs/c-runtime-library/reference/wcrtomb.md +++ b/docs/c-runtime-library/reference/wcrtomb.md @@ -3,16 +3,16 @@ description: "Learn more about: wcrtomb" title: "wcrtomb" ms.date: "4/2/2020" api_name: ["wcrtomb", "_o_wcrtomb"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcrtomb"] +f1_keywords: ["WCHAR/wcrtomb", "wcrtomb"] helpviewer_keywords: ["wide characters, converting", "wcrtomb function", "multibyte characters", "characters, converting"] ms.assetid: 717f1b21-2705-4b7f-b6d0-82adc5224340 --- -# wcrtomb +# `wcrtomb` -Convert a wide character into its multibyte character representation. A more secure version of this function is available; see [wcrtomb_s](wcrtomb-s.md). +Convert a wide character into its multibyte character representation. A more secure version of this function is available; see [`wcrtomb_s`](wcrtomb-s.md). ## Syntax @@ -32,34 +32,34 @@ size_t wcrtomb( ### Parameters -*mbchar*
+*`mbchar`*\ The resulting multibyte converted character. -*wchar*
+*`wchar`*\ A wide character to convert. -*mbstate*
-A pointer to an **mbstate_t** object. +*`mbstate`*\ +A pointer to an `mbstate_t` object. -## Return Value +## Return value Returns the number of bytes required to represent the converted multibyte character, otherwise a -1 if an error occurs. ## Remarks -The **wcrtomb** function converts a wide character, beginning in the specified conversion state contained in *mbstate*, from the value contained in *wchar*, into the address represented by *mbchar*. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than **MB_CUR_MAX** bytes. +The **`wcrtomb`** function converts a wide character, beginning in the specified conversion state contained in *`mbstate`*, from the value contained in *`wchar`*, into the address represented by *`mbchar`*. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than `MB_CUR_MAX` bytes. -If *mbstate* is null, the internal **mbstate_t** object containing the conversion state of *mbchar* is used. If the character sequence *wchar* does not have a corresponding multibyte character representation, a -1 is returned and the **errno** is set to **EILSEQ**. +If *`mbstate`* is null, the internal `mbstate_t` object containing the conversion state of *`mbchar`* is used. If the character sequence *`wchar`* doesn't have a corresponding multibyte character representation, a -1 is returned, and the `errno` is set to `EILSEQ`. -The **wcrtomb** function differs from [wctomb, _wctomb_l](wctomb-wctomb-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcsnlen**, if a subsequent call to **wcsrtombs** were used instead of **wcstombs**. +The **`wcrtomb`** function differs from [`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcsnlen`, if a subsequent call to `wcsrtombs` were used instead of `wcstombs`. -In C++, this function has a template overload that invokes the newer, secure counterparts of this function. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, this function has a template overload that invokes the newer, secure counterparts of this function. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcrtomb** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and while the *mbstate* is null. +The **`wcrtomb`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and while the *`mbstate`* is null. ## Example @@ -106,13 +106,13 @@ The corresponding wide character "Q" was converted to the "Q" multibyte characte ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcrtomb**|\| +| Routine | Required header | +|---|---| +| **`wcrtomb`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcsicoll.md b/docs/c-runtime-library/reference/wcsicoll.md index f235899e39..5e73d3af12 100644 --- a/docs/c-runtime-library/reference/wcsicoll.md +++ b/docs/c-runtime-library/reference/wcsicoll.md @@ -6,12 +6,12 @@ api_name: ["wcsicoll"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsicoll"] +f1_keywords: ["CORECRT_WSTRING/wcsicoll", "wcsicoll"] helpviewer_keywords: ["wcsicoll function"] ms.assetid: d049022d-cf60-467f-842b-9a508d9aeaff --- -# wcsicoll +# `wcsicoll` -The Microsoft-specific function name `wcsicoll` is a deprecated alias for the [_wcsicoll](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `wcsicoll` is a deprecated alias for the [`_wcsicoll`](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_wcsicoll](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_wcsicoll`](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/wcsrtombs-s.md b/docs/c-runtime-library/reference/wcsrtombs-s.md index bab32985cd..a56efa3cd5 100644 --- a/docs/c-runtime-library/reference/wcsrtombs-s.md +++ b/docs/c-runtime-library/reference/wcsrtombs-s.md @@ -3,16 +3,16 @@ description: "Learn more about: wcsrtombs_s" title: "wcsrtombs_s" ms.date: "4/2/2020" api_name: ["wcsrtombs_s", "_o_wcsrtombs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsrtombs_s"] +f1_keywords: ["WCHAR/wcsrtombs_s", "wcsrtombs_s"] helpviewer_keywords: ["string conversion, wide characters", "wcsrtombs_s function", "wide characters, strings"] ms.assetid: 9dccb766-113c-44bb-9b04-07a634dddec8 --- -# wcsrtombs_s +# `wcsrtombs_s` -Convert a wide character string to its multibyte character string representation. A version of [wcsrtombs](wcsrtombs.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a wide character string to its multibyte character string representation. A version of [`wcsrtombs`](wcsrtombs.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,68 +37,68 @@ errno_t wcsrtombs_s( ### Parameters -*pReturnValue*
+*`pReturnValue`*\ The size in bytes of the converted string, including the null terminator. -*mbstr*
+*`mbstr`*\ The address of a buffer for the resulting converted multibyte character string. -*sizeInBytes*
-The size in bytes of the *mbstr* buffer. +*`sizeInBytes`*\ +The size in bytes of the *`mbstr`* buffer. -*wcstr*
+*`wcstr`*\ Points to the wide character string to be converted. -*count*
-The maximum number of bytes to be stored in the *mbstr* buffer, or [_TRUNCATE](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of bytes to be stored in the *`mbstr`* buffer, or [`_TRUNCATE`](../truncate.md). -*mbstate*
-A pointer to an **mbstate_t** conversion state object. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. -## Return Value +## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **errno**| -|---------------------|------------------------------| -|*mbstr* is **NULL** and *sizeInBytes* > 0|**EINVAL**| -|*wcstr* is **NULL**|**EINVAL**| -|The destination buffer is too small to contain the converted string (unless *count* is **_TRUNCATE**; see Remarks below)|**ERANGE**| +| Error condition | Return value and `errno` | +|---|---| +| *`mbstr`* is `NULL` and *`sizeInBytes`* > 0 | `EINVAL` | +| *`wcstr`* is `NULL` | `EINVAL` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; see Remarks below) | `ERANGE` | -If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets **errno** as indicated in the table. +If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks -The **wcsrtombs_s** function converts a string of wide characters pointed to by *wcstr* into multibyte characters stored in the buffer pointed to by *mbstr*, using the conversion state contained in *mbstate*. The conversion will continue for each character until one of these conditions is met: +The **`wcsrtombs_s`** function converts a string of wide characters pointed to by *`wcstr`* into multibyte characters stored in the buffer pointed to by *`mbstr`*, using the conversion state contained in *`mbstate`*. The conversion will continue for each character until one of these conditions is met: - A null wide character is encountered -- A wide character that cannot be converted is encountered +- A wide character that can't be converted is encountered -- The number of bytes stored in the *mbstr* buffer equals *count*. +- The number of bytes stored in the *`mbstr`* buffer equals *`count`*. -The destination string is always null-terminated (even in the case of an error). +The destination string is always null-terminated (even if there's an error). -If *count* is the special value [_TRUNCATE](../../c-runtime-library/truncate.md), then **wcsrtombs_s** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), then **`wcsrtombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. -If **wcsrtombs_s** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into `*pReturnValue` (provided *pReturnValue* is not **NULL**). This occurs even if the *mbstr* argument is **NULL** and provides a way to determine the required buffer size. Note that if *mbstr* is **NULL**, *count* is ignored. +If **`wcsrtombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into `*pReturnValue` (provided *`pReturnValue`* isn't `NULL`). The size is calculated even if the *`mbstr`* argument is `NULL`; it provides a way to determine the required buffer size. If *`mbstr`* is `NULL`, *`count`* is ignored. -If **wcsrtombs_s** encounters a wide character it cannot convert to a multibyte character, it puts -1 in *\*pReturnValue*, sets the destination buffer to an empty string, sets **errno** to **EILSEQ**, and returns **EILSEQ**. +If **`wcsrtombs_s`** encounters a wide character it can't convert to a multibyte character, it puts -1 in *\*`pReturnValue`*, sets the destination buffer to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. -If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcsrtombs_s** is undefined. **wcsrtombs_s** is affected by the LC_TYPE category of the current locale. +If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcsrtombs_s`** is undefined. **`wcsrtombs_s`** is affected by the LC_TYPE category of the current locale. > [!IMPORTANT] -> Ensure that *wcstr* and *mbstr* do not overlap, and that *count* correctly reflects the number of wide characters to convert. +> Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of wide characters to convert. -The **wcsrtombs_s** function differs from [wcstombs_s, _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcslen**, if a subsequent call to **wcsrtombs_s** were used instead of **wcstombs_s**. +The **`wcsrtombs_s`** function differs from [`wcstombs_s`, `_wcstombs_s_l`](wcstombs-s-wcstombs-s-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcslen`, if a subsequent call to **`wcsrtombs_s`** were used instead of `wcstombs_s`. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcsrtombs_s** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is null. +The **`wcsrtombs_s`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* is null. ## Example @@ -149,17 +149,17 @@ The string was successfully converted. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcsrtombs_s**|\| +| Routine | Required header | +|---|---| +| **`wcsrtombs_s`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[wcrtomb](wcrtomb.md)
-[wcrtomb_s](wcrtomb-s.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`wcrtomb`](wcrtomb.md)\ +[`wcrtomb_s`](wcrtomb-s.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcsrtombs.md b/docs/c-runtime-library/reference/wcsrtombs.md index 97f603bc0b..9df3eb44ee 100644 --- a/docs/c-runtime-library/reference/wcsrtombs.md +++ b/docs/c-runtime-library/reference/wcsrtombs.md @@ -3,16 +3,16 @@ description: "Learn more about: wcsrtombs" title: "wcsrtombs" ms.date: "4/2/2020" api_name: ["wcsrtombs", "_o_wcsrtombs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsrtombs"] +f1_keywords: ["WCHAR/wcsrtombs", "wcsrtombs"] helpviewer_keywords: ["wcsrtombs function", "string conversion, wide characters", "wide characters, strings"] ms.assetid: a8d21fec-0d36-4085-9d81-9b1c61c7259d --- -# wcsrtombs +# `wcsrtombs` -Convert a wide character string to its multibyte character string representation. A more secure version of this function is available; see [wcsrtombs_s](wcsrtombs-s.md). +Convert a wide character string to its multibyte character string representation. A more secure version of this function is available; see [`wcsrtombs_s`](wcsrtombs-s.md). ## Syntax @@ -34,39 +34,39 @@ size_t wcsrtombs( ### Parameters -*mbstr*
+*`mbstr`*\ The resulting converted multibyte character string's address location. -*wcstr*
+*`wcstr`*\ Indirectly points to the location of the wide character string to be converted. -*count*
-The number of character to be converted. +*`count`*\ +The number of characters to be converted. -*mbstate*
-A pointer to an **mbstate_t** conversion state object. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. -## Return Value +## Return value Returns the number of bytes successfully converted, not including the null terminating null byte (if any), otherwise a -1 if an error occurred. ## Remarks -The **wcsrtombs** function converts a string of wide characters, beginning in the specified conversion state contained in *mbstate*, from the values indirect pointed to in *wcstr*, into the address of *mbstr*. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in *count*. If **wcsrtombs** encounters the wide-character null character (L'\0') either before or when *count* occurs, it converts it to an 8-bit 0 and stops. +The **`wcsrtombs`** function converts a string of wide characters, beginning in the specified conversion state contained in *`mbstate`*, from the values indirect pointed to in *`wcstr`*, into the address of *`mbstr`*. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in *`count`*. If **`wcsrtombs`** encounters the wide-character null character (L'\0') either before or when *`count`* occurs, it converts it to an 8-bit 0 and stops. -Thus, the multibyte character string at *mbstr* is null-terminated only if **wcsrtombs** encounters a wide character null character during conversion. If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcsrtombs** is undefined. **wcsrtombs** is affected by the LC_TYPE category of the current locale. +Thus, the multibyte character string at *`mbstr`* is null-terminated only if **`wcsrtombs`** encounters a wide character null character during conversion. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcsrtombs`** is undefined. **`wcsrtombs`** is affected by the LC_TYPE category of the current locale. -The **wcsrtombs** function differs from [wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcsnlen**, if a subsequent call to **wcsrtombs** were used instead of **wcstombs**. +The **`wcsrtombs`** function differs from [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcsnlen`, if a subsequent call to **`wcsrtombs`** were used instead of `wcstombs`. -If the *mbstr* argument is **NULL**, **wcsrtombs** returns the required size in bytes of the destination string. If *mbstate* is null, the internal **mbstate_t** conversion state is used. If the character sequence *wchar* does not have a corresponding multibyte character representation, a -1 is returned and the **errno** is set to **EILSEQ**. +If the *`mbstr`* argument is `NULL`, **`wcsrtombs`** returns the required size in bytes of the destination string. If *`mbstate`* is null, the internal `mbstate_t` conversion state is used. If the character sequence *`wchar`* doesn't have a corresponding multibyte character representation, a -1 is returned, and the `errno` is set to `EILSEQ`. -In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcsrtombs** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is not null. +The **`wcsrtombs`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* isn't null. ## Example @@ -116,17 +116,17 @@ The string was successfuly converted. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcsrtombs**|\| +| Routine | Required header | +|---|---| +| **`wcsrtombs`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[wcrtomb](wcrtomb.md)
-[wcrtomb_s](wcrtomb-s.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`wcrtomb`](wcrtomb.md)\ +[`wcrtomb_s`](wcrtomb-s.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md b/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md index 62abbb9f8f..058ddb9ccb 100644 --- a/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md +++ b/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md @@ -3,15 +3,15 @@ description: "Learn more about: wcstombs_s, _wcstombs_s_l" title: "wcstombs_s, _wcstombs_s_l" ms.date: 09/30/2021 api_name: ["_wcstombs_s_l", "wcstombs_s", "_o__wcstombs_s_l", "_o_wcstombs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstombs_s", "_wcstombs_s_l"] +f1_keywords: ["STDLIB/wcstombs_s", "STDLIB/_wcstombs_s_l", "wcstombs_s", "_wcstombs_s_l"] helpviewer_keywords: ["wcstombs_s function", "string conversion, wide characters", "wide characters, converting", "_wcstombs_s_l function", "wcstombs_s_l function", "characters, converting", "string conversion, multibyte character strings"] --- # `wcstombs_s`, `_wcstombs_s_l` -Converts a sequence of wide characters to a corresponding sequence of multibyte characters. A version of [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a sequence of wide characters to a corresponding sequence of multibyte characters. A version of [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -53,35 +53,35 @@ errno_t _wcstombs_s_l( ### Parameters -*`pReturnValue`*
+*`pReturnValue`*\ The size in bytes of the converted string, including the null terminator. -*`mbstr`*
+*`mbstr`*\ The address of a buffer for the resulting converted multibyte character string. -*`sizeInBytes`*
+*`sizeInBytes`*\ The size in bytes of the *`mbstr`* buffer. -*`wcstr`*
+*`wcstr`*\ Points to the wide character string to be converted. -*`count`*
-The maximum number of bytes to store in the *`mbstr`* buffer, not including the terminating null character, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of bytes to store in the *`mbstr`* buffer, not including the terminating null character, or [`_TRUNCATE`](../truncate.md). -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **`errno`**| -|---------------------|------------------------------| -|*`mbstr`* is **`NULL`** and *`sizeInBytes`* > 0|**`EINVAL`**| -|*`wcstr`* is **`NULL`**|**`EINVAL`**| -|The destination buffer is too small to contain the converted string (unless *`count`* is **`_TRUNCATE`**; see Remarks below)|**`ERANGE`**| +| Error condition | Return value and `errno` | +|---|---| +| *`mbstr`* is `NULL` and *`sizeInBytes`* > 0 | `EINVAL` | +| *`wcstr`* is `NULL` | `EINVAL` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; see Remarks below) | `ERANGE` | -If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets **`errno`** as indicated in the table. +If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks @@ -89,36 +89,36 @@ The **`wcstombs_s`** function converts a string of wide characters pointed to by - A null wide character is encountered -- A wide character that cannot be converted is encountered +- A wide character that can't be converted is encountered - The number of bytes stored in the *`mbstr`* buffer equals *`count`*. -The destination string is always null-terminated (even in the case of an error). +The destination string is always null-terminated (even if there's an error). -If *`count`* is the special value [`_TRUNCATE`](../../c-runtime-library/truncate.md), then **`wcstombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. If the string is truncated, the return value is **`STRUNCATE`**, and the conversion is considered successful. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), then **`wcstombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. If the string is truncated, the return value is `STRUNCATE`, and the conversion is considered successful. -If **`wcstombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *`*pReturnValue`* (provided *`pReturnValue`* is not **`NULL`**). This occurs even if the *`mbstr`* argument is **`NULL`** and provides a way to determine the required buffer size. Note that if *`mbstr`* is **`NULL`**, *`count`* is ignored. +If **`wcstombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *`*pReturnValue`* (provided *`pReturnValue`* isn't `NULL`). The size is calculated even if the *`mbstr`* argument is `NULL`; it provides a way to determine the required buffer size. If *`mbstr`* is `NULL`, *`count`* is ignored. -If **`wcstombs_s`** encounters a wide character it cannot convert to a multibyte character, it puts 0 in *`*ReturnValue`*, sets the destination buffer to an empty string, sets **`errno`** to **`EILSEQ`**, and returns **`EILSEQ`**. +If **`wcstombs_s`** encounters a wide character it can't convert to a multibyte character, it puts 0 in *`*ReturnValue`*, sets the destination buffer to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcstombs_s`** is undefined. > [!IMPORTANT] > Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of wide characters to convert. -**`wcstombs_s`** uses the current locale for any locale-dependent behavior; **`_wcstombs_s_l`** is identical to **`wcstombs`** except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wcstombs_s`** uses the current locale for any locale-dependent behavior; **`_wcstombs_s_l`** is identical to **`wcstombs`** except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`wcstombs_s`**|``| +| Routine | Required header | +|---|---| +| **`wcstombs_s`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -168,10 +168,10 @@ Convert wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)
-[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)
-[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)
-[`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md)
-[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md index 770089354d..cd259d2102 100644 --- a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md +++ b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md @@ -3,16 +3,15 @@ description: "Learn more about: wcstombs, _wcstombs_l" title: "wcstombs, _wcstombs_l" ms.date: "4/2/2020" api_name: ["wcstombs", "_wcstombs_l", "_o__wcstombs_l", "_o_wcstombs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstombs", "_wcstombs_l"] +f1_keywords: ["STDLIB/wcstombs", "STDLIB/_wcstombs_l", "wcstombs", "_wcstombs_l"] helpviewer_keywords: ["_wcstombs_l function", "wcstombs function", "string conversion, wide characters", "wide characters, converting", "wcstombs_l function", "characters, converting", "string conversion, multibyte character strings"] -ms.assetid: 91234252-9ea1-423a-af99-e9d0ce4a40e3 --- -# wcstombs, _wcstombs_l +# `wcstombs`, `_wcstombs_l` -Converts a sequence of wide characters to a corresponding sequence of multibyte characters. More secure versions of these functions are available; see [wcstombs_s, _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md). +Converts a sequence of wide characters to a corresponding sequence of multibyte characters. More secure versions of these functions are available; see [`wcstombs_s`, `_wcstombs_s_l`](wcstombs-s-wcstombs-s-l.md). ## Syntax @@ -45,50 +44,52 @@ size_t _wcstombs_l( ### Parameters -*mbstr*
+*`mbstr`*\ The address of a sequence of multibyte characters. -*wcstr*
+*`wcstr`*\ The address of a sequence of wide characters. -*count*
+*`count`*\ The maximum number of bytes that can be stored in the multibyte output string. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -If **wcstombs** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating null (if any). If the *mbstr* argument is **NULL**, **wcstombs** returns the required size in bytes of the destination string. If **wcstombs** encounters a wide character it cannot convert to a multibyte character, it returns -1 cast to type **size_t** and sets **errno** to **EILSEQ**. +If **`wcstombs`** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating `NULL` (if any). If the *`mbstr`* argument is `NULL`, **`wcstombs`** returns the required size in bytes of the destination string. If **`wcstombs`** encounters a wide character it can't convert to a multibyte character, it returns -1 cast to type **`size_t`** and sets `errno` to `EILSEQ`. ## Remarks -The **wcstombs** function converts the wide-character string pointed to by *wcstr* to the corresponding multibyte characters and stores the results in the *mbstr* array. The *count* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *mbstr*). In general, it is not known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two. If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character null), the result is guaranteed to fit. +The **`wcstombs`** function converts the wide-character string pointed to by *`wcstr`* to the corresponding multibyte characters and stores the results in the *`mbstr`* array. The *`count`* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *`mbstr`*). In general, it isn't known how many bytes will be required when converting a wide-character string. Some wide characters will require only a single byte in the output string; others require 2 bytes. If there are 2 bytes in the multibyte output string for every wide character in the input string (including the wide character `NULL`), the result is guaranteed to fit. -If **wcstombs** encounters the wide-character null character (L'\0') either before or when *count* occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at *mbstr* is null-terminated only if **wcstombs** encounters a wide-character null character during conversion. If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcstombs** is undefined. +Starting in Windows 10 version 1803 (10.0.17134.0), the Universal C Runtime supports using a UTF-8 code page. Use `wcstombs(NULL, wcstr, 0)` to get the correct size that you'll need for the conversion because assuming that you'll need two bytes for every wide character may not be enough. For more information about UTF-8 support, see [UTF-8 support](setlocale-wsetlocale.md) -If the *mbstr* argument is **NULL**, **wcstombs** returns the required size in bytes of the destination string. +If **`wcstombs`** encounters the wide-character `NULL` character (L'\0') either before or when *`count`* occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at *`mbstr`* is null-terminated only if **`wcstombs`** encounters a wide-character `NULL` character during conversion. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcstombs`** is undefined. -**wcstombs** validates its parameters. If *wcstr* is **NULL**, or if *count* is greater than **INT_MAX**, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function sets **errno** to **EINVAL** and returns -1. +If the *`mbstr`* argument is `NULL`, **`wcstombs`** returns the required size in bytes of the destination string. -**wcstombs** uses the current locale for any locale-dependent behavior; **_wcstombs_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wcstombs`** validates its parameters. If *`wcstr`* is `NULL`, or if *`count`* is greater than `INT_MAX`, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +**`wcstombs`** uses the current locale for any locale-dependent behavior; **`_wcstombs_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcstombs**|\| -|**_wcstombs_l**|\| +| Routine | Required header | +|---|---| +| **`wcstombs`** | `` | +| **`_wcstombs_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program illustrates the behavior of the **wcstombs** function. +This program illustrates the behavior of the **`wcstombs`** function. ```C // crt_wcstombs.c @@ -130,10 +131,10 @@ Convert wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctob.md b/docs/c-runtime-library/reference/wctob.md index 72be225e5c..70b552de85 100644 --- a/docs/c-runtime-library/reference/wctob.md +++ b/docs/c-runtime-library/reference/wctob.md @@ -3,14 +3,14 @@ description: "Learn more about: wctob" title: "wctob" ms.date: "4/2/2020" api_name: ["wctob", "_o_wctob"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctob"] +f1_keywords: ["WCHAR/wctob", "wctob"] helpviewer_keywords: ["wide characters, converting", "wctob function", "characters, converting"] ms.assetid: 46aec98b-c2f2-4e9d-9d89-7db99ba8a9a6 --- -# wctob +# `wctob` Determines if a wide character corresponds to a multibyte character and returns its multibyte character representation. @@ -24,32 +24,32 @@ int wctob( ### Parameters -*wchar*
+*`wchar`*\ Value to translate. -## Return Value +## Return value -If **wctob** successfully converts a wide character, it returns its multibyte character representation, only if the multibyte character is exactly one byte long. If **wctob** encounters a wide character it cannot convert to a multibyte character or the multibyte character is not exactly one byte long, it returns a -1. +If **`wctob`** successfully converts a wide character, it returns its multibyte character representation only if the multibyte character is a single byte long. If **`wctob`** encounters a wide character it can't convert to a multibyte character, or if the multibyte character isn't a single byte long, it returns -1. ## Remarks -The **wctob** function converts a wide character contained in *wchar* to the corresponding multibyte character passed by the return **`int`** value, if the multibyte character is exactly one byte long. +The **`wctob`** function converts a wide character contained in *`wchar`* to the corresponding multibyte character passed by the **`int`** return value, if the multibyte character is a single byte long. -If **wctob** was unsuccessful and no corresponding multibyte character was found, the function sets **errno** to **EILSEQ** and returns -1. +If **`wctob`** was unsuccessful and no corresponding multibyte character was found, the function sets `errno` to `EILSEQ` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctob**|\| +| Routine | Required header | +|---|---| +| **`wctob`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program illustrates the behavior of the **wcstombs** function. +This program illustrates the behavior of the `wctob` function. ```C // crt_wctob.c @@ -83,10 +83,10 @@ Determined the corresponding multibyte character to be "A". ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md b/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md index 943cd74ed2..5158493a59 100644 --- a/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md +++ b/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: wctomb_s, _wctomb_s_l" title: "wctomb_s, _wctomb_s_l" ms.date: "4/2/2020" api_name: ["_wctomb_s_l", "wctomb_s", "_o__wctomb_s_l", "_o_wctomb_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctomb_s", "_wctomb_s_l"] +f1_keywords: ["STDLIB/wctomb_s", "STDLIB/_wctomb_s_l", "wctomb_s", "_wctomb_s_l"] helpviewer_keywords: ["wctomb_s function", "wctomb_s_l function", "string conversion, wide characters", "wide characters, converting", "_wctomb_s_l function", "characters, converting", "string conversion, multibyte character strings"] ms.assetid: 7e94a888-deed-4dbd-b5e9-d4a0455538b8 --- -# wctomb_s, _wctomb_s_l +# `wctomb_s`, `_wctomb_s_l` -Converts a wide character to the corresponding multibyte character. A version of [wctomb, _wctomb_l](wctomb-wctomb-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a wide character to the corresponding multibyte character. A version of [`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -34,57 +34,59 @@ errno_t _wctomb_s_l( ### Parameters -*pRetValue*
+*`pRetValue`*\ The number of bytes, or a code indicating the result. -*mbchar*
+*`mbchar`*\ The address of a multibyte character. -*sizeInBytes*
-Size of the buffer *mbchar*. +*`sizeInBytes`*\ +Size of the buffer *`mbchar`*. -*wchar*
-A wide character. +*`wchar`*\ +The wide character to convert. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful, an error code on failure. Error Conditions -|*mbchar*|*sizeInBytes*|Return value|*pRetValue*| -|--------------|-------------------|------------------|-----------------| -|**NULL**|>0|**EINVAL**|not modified| -|any|>**INT_MAX**|**EINVAL**|not modified| -|any|too small|**EINVAL**|not modified| +| *`mbchar`* | *`sizeInBytes`* | Return value | *`pRetValue`* | +|---|---|---|---| +| `NULL` | >0 | `EINVAL` | not modified | +| any | >`INT_MAX` | `EINVAL` | not modified | +| any | too small | `EINVAL` | not modified | + +If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `wctomb` returns `EINVAL` and sets `errno` to `EINVAL`. -If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **wctomb** returns **EINVAL** and sets **errno** to **EINVAL**. +The return value [`EILSEQ`](../errno-constants.md) indicates that the value passed via the parameter `wchar` is not a valid wide character. ## Remarks -The **wctomb_s** function converts its *wchar* argument to the corresponding multibyte character and stores the result at *mbchar*. You can call the function from any point in any program. +The **`wctomb_s`** function converts its *`wchar`* argument to the corresponding multibyte character and stores the result at *`mbchar`*. You can call the function from any point in any program. -If **wctomb_s** converts the wide character to a multibyte character, it puts the number of bytes (which is never greater than **MB_CUR_MAX**) in the wide character into the integer pointed to by *pRetValue*. If *wchar* is the wide-character null character (L'\0'), **wctomb_s** fills *pRetValue* with 1. If the target pointer *mbchar* is **NULL**, **wctomb_s** puts 0 in *pRetValue*. If the conversion is not possible in the current locale, **wctomb_s** puts -1 in *pRetValue*. +If **`wctomb_s`** converts the wide character to a multibyte character, it puts the number of bytes (which is never greater than `MB_CUR_MAX`) in the wide character into the integer pointed to by *`pRetValue`*. If *`wchar`* is the wide-character null character (L'\0'), **`wctomb_s`** fills *`pRetValue`* with 1. If the target pointer *`mbchar`* is `NULL`, **`wctomb_s`** puts 0 in *`pRetValue`*. If the conversion isn't possible in the current locale, **`wctomb_s`** puts -1 in *`pRetValue`*. -**wctomb_s** uses the current locale for locale-dependent information; **_wctomb_s_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wctomb_s`** uses the current locale for locale-dependent information; **`_wctomb_s_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctomb_s**|\| -|**_wctomb_s_l**|\| +| Routine | Required header | +|---|---| +| **`wctomb_s`** | \ | +| **`_wctomb_s_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program illustrates the behavior of the **wctomb** function. +This program illustrates the behavior of the **`wctomb_s`** function. ```cpp // crt_wctomb_s.cpp @@ -112,10 +114,10 @@ Convert a wide character: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctomb-wctomb-l.md b/docs/c-runtime-library/reference/wctomb-wctomb-l.md index ff7dea146e..003b081d84 100644 --- a/docs/c-runtime-library/reference/wctomb-wctomb-l.md +++ b/docs/c-runtime-library/reference/wctomb-wctomb-l.md @@ -3,16 +3,16 @@ description: "Learn more about: wctomb, _wctomb_l" title: "wctomb, _wctomb_l" ms.date: "4/2/2020" api_name: ["_wctomb_l", "wctomb", "_o__wctomb_l", "_o_wctomb"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctomb"] +f1_keywords: ["STDLIB/wctomb", "STDLIB/_wctomb_l", "wctomb", "_wctomb_l"] helpviewer_keywords: ["string conversion, wide characters", "wide characters, converting", "_wctomb_l function", "wctomb function", "wctomb_l function", "characters, converting", "string conversion, multibyte character strings"] ms.assetid: 4a543f0e-5516-4d81-8ff2-3c5206f02ed5 --- -# wctomb, _wctomb_l +# `wctomb`, `_wctomb_l` -Convert a wide character to the corresponding multibyte character. More secure versions of these functions are available; see [wctomb_s, _wctomb_s_l](wctomb-s-wctomb-s-l.md). +Convert a wide character to the corresponding multibyte character. More secure versions of these functions are available; see [`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md). ## Syntax @@ -30,31 +30,31 @@ int _wctomb_l( ### Parameters -*mbchar*
+*`mbchar`*\ The address of a multibyte character. -*wchar*
+*`wchar`*\ A wide character. -## Return Value +## Return value -If **wctomb** converts the wide character to a multibyte character, it returns the number of bytes (which is never greater than **MB_CUR_MAX**) in the wide character. If *wchar* is the wide-character null character (L'\0'), **wctomb** returns 1. If the target pointer *mbchar* is **NULL**, **wctomb** returns 0. If the conversion is not possible in the current locale, **wctomb** returns -1 and **errno** is set to **EILSEQ**. +If **`wctomb`** converts the wide character to a multibyte character, it returns the number of bytes (which is never greater than `MB_CUR_MAX`) in the wide character. If *`wchar`* is the wide-character null character (L'\0'), **`wctomb`** returns 1. If the target pointer *`mbchar`* is `NULL`, **`wctomb`** returns 0. If the conversion isn't possible in the current locale, **`wctomb`** returns -1 and `errno` is set to `EILSEQ`. ## Remarks -The **wctomb** function converts its *wchar* argument to the corresponding multibyte character and stores the result at *mbchar*. You can call the function from any point in any program. **wctomb** uses the current locale for any locale-dependent behavior; **_wctomb_l** is identical to **wctomb** except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`wctomb`** function converts its *`wchar`* argument to the corresponding multibyte character and stores the result at *`mbchar`*. You can call the function from any point in any program. **`wctomb`** uses the current locale for any locale-dependent behavior; **`_wctomb_l`** is identical to **`wctomb`** except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -**wctomb** validates its parameters. If *mbchar* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns -1. +**`wctomb`** validates its parameters. If *`mbchar`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctomb**|\| +| Routine | Required header | +|---|---| +| **`wctomb`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,10 +88,10 @@ Convert a wide character: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctrans.md b/docs/c-runtime-library/reference/wctrans.md index 47bcc79860..7bcac2489a 100644 --- a/docs/c-runtime-library/reference/wctrans.md +++ b/docs/c-runtime-library/reference/wctrans.md @@ -6,11 +6,11 @@ api_name: ["wctrans"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctrans"] +f1_keywords: ["WCTYPE/wctrans", "wctrans"] helpviewer_keywords: ["character codes, wctrans", "characters, codes", "characters, converting", "wctrans function"] ms.assetid: 215404bf-6d60-489c-9ae9-880e6b586162 --- -# wctrans +# `wctrans` Determines a mapping from one set of character codes to another. @@ -24,31 +24,31 @@ wctrans_t wctrans( ### Parameters -*property*
+*`property`*\ A string that specifies one of the valid transformations. -## Return Value +## Return value -If the **LC_CTYPE** category of the current locale does not define a mapping whose name matches the property string *property*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [towctrans](towctrans.md). +If the `LC_CTYPE` category of the current locale doesn't define a mapping whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). ## Remarks This function determines a mapping from one set of character codes to another. -The following pairs of calls have the same behavior in all locales, but it is possible to define additional mappings even in the "C" locale: +The following pairs of calls have the same behavior in all locales, but it's possible to define more mappings even in the "C" locale: -|Function|Same As| -|--------------|-------------| -|tolower(c)|towctrans(c, wctrans("towlower"))| -|towupper(c)|towctrans(c, wctrans("toupper"))| +| Function | Same As | +|---|---| +| `tolower(c)` | `towctrans(c, wctrans("towlower"))` | +| `towupper(c)` | `towctrans(c, wctrans("toupper"))` | ## Requirements -|Routine|Required Header| -|-------------|---------------------| -|**wctrans**|\| +| Routine | Required Header | +|---|---| +| **`wctrans`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,5 +88,5 @@ int main() ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
+[Data conversion](../data-conversion.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/reference/wctype.md b/docs/c-runtime-library/reference/wctype.md index 43bdf52c27..123b547d78 100644 --- a/docs/c-runtime-library/reference/wctype.md +++ b/docs/c-runtime-library/reference/wctype.md @@ -6,7 +6,7 @@ api_name: ["wctype"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctype"] +f1_keywords: ["WCTYPE/wctype", "wctype"] helpviewer_keywords: ["wctype function", "wide characters"] --- # `wctype` @@ -26,37 +26,37 @@ wctype_t wctype( *`property`*\ Property string. -## Return Value +## Return value -If the **`LC_CTYPE`** category of the current locale doesn't define a classification rule whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). +If the `LC_CTYPE` category of the current locale doesn't define a classification rule whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). ## Remarks -The function determines a classification rule for wide-character codes. The following pairs of calls have the same behavior in all locales (but an implementation can define additional classification rules even in the "C" locale): - -|Function|Same as| -|--------------|-------------| -|`iswalnum(c)`|`iswctype(c, wctype( "alnum" ))`| -|`iswalpha(c)`|`iswctype(c, wctype( "alpha" ))`| -|`iswcntrl(c)`|`iswctype(c, wctype( "cntrl" ))`| -|`iswdigit(c)`|`iswctype(c, wctype( "digit" ))`| -|`iswgraph(c)`|`iswctype(c, wctype( "graph" ))`| -|`iswlower(c)`|`iswctype(c, wctype( "lower" ))`| -|`iswprint(c)`|`iswctype(c, wctype( "print" ))`| -|`iswpunct(c)`|`iswctype(c, wctype( "punct" ))`| -|`iswspace(c)`|`iswctype(c, wctype( "space" ))`| -|`iswupper(c)`|`iswctype(c, wctype( "upper" ))`| -|`iswxdigit(c)`|`iswctype(c, wctype( "xdigit" ))`| +The function determines a classification rule for wide-character codes. The following pairs of calls have the same behavior in all locales (but an implementation can define more classification rules even in the "C" locale): + +| Function | Same as | +|---|---| +| `iswalnum(c)` | `iswctype(c, wctype( "alnum" ))` | +| `iswalpha(c)` | `iswctype(c, wctype( "alpha" ))` | +| `iswcntrl(c)` | `iswctype(c, wctype( "cntrl" ))` | +| `iswdigit(c)` | `iswctype(c, wctype( "digit" ))` | +| `iswgraph(c)` | `iswctype(c, wctype( "graph" ))` | +| `iswlower(c)` | `iswctype(c, wctype( "lower" ))` | +| `iswprint(c)` | `iswctype(c, wctype( "print" ))` | +| `iswpunct(c)` | `iswctype(c, wctype( "punct" ))` | +| `iswspace(c)` | `iswctype(c, wctype( "space" ))` | +| `iswupper(c)` | `iswctype(c, wctype( "upper" ))` | +| `iswxdigit(c)` | `iswctype(c, wctype( "xdigit" ))` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`wctype`|``| +| Routine | Required header | +|---|---| +| **`wctype`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ +[Data conversion](../data-conversion.md)\ [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/reference/write.md b/docs/c-runtime-library/reference/write.md index 49f0553e64..f21ee87c4d 100644 --- a/docs/c-runtime-library/reference/write.md +++ b/docs/c-runtime-library/reference/write.md @@ -3,14 +3,13 @@ description: "Learn more about: _write" title: "_write" ms.date: "4/2/2020" api_name: ["_write", "_o__write"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_write"] +f1_keywords: ["CORECRT_IO/_write", "_write"] helpviewer_keywords: ["_write function", "write function", "files [C++], writing to"] -ms.assetid: 7b868c33-766f-4e1a-95a7-e8d25f0604c4 --- -# _write +# `_write` Writes data to a file. @@ -26,40 +25,40 @@ int _write( ### Parameters -*fd*
+*`fd`*\ File descriptor of file into which data is written. -*buffer*
+*`buffer`*\ Data to be written. -*count*
+*`count`*\ Number of bytes. -## Return Value +## Return value -If successful, **_write** returns the number of bytes written. If the actual space remaining on the disk is less than the size of the buffer the function is trying to write to the disk, **_write** fails and does not flush any of the buffer's contents to the disk. A return value of -1 indicates an error. If invalid parameters are passed, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and **errno** is set to one of three values: **EBADF**, which means the file descriptor is invalid or the file is not opened for writing; **ENOSPC**, which means there is not enough space left on the device for the operation; or **EINVAL**, which means that *buffer* was a null pointer or that an odd *count* of bytes was passed to be written to a file in Unicode mode. +If successful, **`_write`** returns the number of bytes written. If the actual space remaining on the disk is less than the size of the buffer the function is trying to write to the disk, **`_write`** fails and doesn't flush any of the buffer's contents to the disk. A return value of -1 indicates an error. If invalid parameters are passed, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and `errno` is set to one of three values: `EBADF`, which means the file descriptor is invalid or the file isn't opened for writing; `ENOSPC`, which means there isn't enough space left on the device for the operation; or `EINVAL`, which means that *`buffer`* was a null pointer, or that an odd *`count`* of bytes was passed in Unicode mode. -For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). If the file is opened in text mode, each line feed character is replaced with a carriage return-line feed pair in the output. The replacement doesn't affect the return value. -When the file is opened in Unicode translation mode—for example, if *fd* is opened by using **_open** or **_sopen** and a mode parameter that includes **_O_WTEXT**, **_O_U16TEXT**, or **_O_U8TEXT**, or if it's opened by using **fopen** and a mode parameter that includes **ccs=UNICODE**, **ccs=UTF-16LE**, or **ccs=UTF-8**, or if the mode is changed to a Unicode translation mode by using **_setmode**—*buffer* is interpreted as a pointer to an array of **`wchar_t`** that contains **UTF-16** data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. +When the file is opened in Unicode translation mode—for example, if *`fd`* is opened by using **`_open`** or **`_sopen`** and a mode parameter that includes `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, or if it's opened by using **`fopen`** and a mode parameter that includes **`ccs=UNICODE`**, **`ccs=UTF-16LE`**, or **`ccs=UTF-8`**, or if the mode is changed to a Unicode translation mode by using **`_setmode`**—*`buffer`* is interpreted as a pointer to an array of **`wchar_t`** that contains **`UTF-16`** data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. ## Remarks -The **_write** function writes *count* bytes from *buffer* into the file associated with *fd*. The write operation begins at the current position of the file pointer (if any) associated with the given file. If the file is open for appending, the operation begins at the current end of the file. After the write operation, the file pointer is increased by the number of bytes written. +The **`_write`** function writes *`count`* bytes from *`buffer`* into the file associated with *`fd`*. The write operation begins at the current position of the file pointer (if any) associated with the given file. If the file is open for appending, the operation begins at the current end of the file. After the write operation, the file pointer is increased by the number of bytes written. -When writing to files opened in text mode, **_write** treats a CTRL+Z character as the logical end of file. When writing to a device, **_write** treats a CTRL+Z character in the buffer as an output terminator. +When it writes to files opened in text mode, **`_write`** treats a CTRL+Z character as the logical end of file. When it writes to a device, **`_write`** treats a CTRL+Z character in the buffer as an output terminator. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_write**|\| +| Routine | Required header | +|---|---| +| **`_write`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -121,8 +120,8 @@ Wrote 36 bytes to file. ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[fwrite](fwrite.md)
-[_open, _wopen](open-wopen.md)
-[_read](read.md)
-[_setmode](setmode.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`fwrite`](fwrite.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_read`](read.md)\ +[`_setmode`](setmode.md) diff --git a/docs/c-runtime-library/reference/xor-eq.md b/docs/c-runtime-library/reference/xor-eq.md index 1c53b39e11..4a9898a2c2 100644 --- a/docs/c-runtime-library/reference/xor-eq.md +++ b/docs/c-runtime-library/reference/xor-eq.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std.xor_eq", "xor_eq", "std::xor_eq"] +f1_keywords: ["std.xor_eq", "xor_eq", "std::xor_eq", "ISO646/xor_eq"] helpviewer_keywords: ["xor_eq function"] ms.assetid: eca4b6b4-b77a-4d44-a09a-5a7e69fdb56c --- -# xor_eq +# `xor_eq` -An alternative to the ^= operator. +An alternative to the **`^=`** operator. ## Syntax ```C - #define xor_eq ^= ``` ## Remarks -The macro yields the operator ^=. +The macro yields the operator **`^=`**. ## Example diff --git a/docs/c-runtime-library/reference/xor.md b/docs/c-runtime-library/reference/xor.md index 9a84a5b2af..1bc78efb8d 100644 --- a/docs/c-runtime-library/reference/xor.md +++ b/docs/c-runtime-library/reference/xor.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::xor", "std.xor"] +f1_keywords: ["std::xor", "std.xor", "ISO646/xor"] helpviewer_keywords: ["xor function"] ms.assetid: 0fe9554b-d87b-4487-92ed-366c6dc21df2 --- -# xor +# `xor` -An alternative to the ^ operator. +An alternative to the **`^`** operator. ## Syntax ```C - #define xor ^ ``` ## Remarks -The macro yields the operator ^. +The macro yields the operator **`^`**. ## Example @@ -40,7 +39,7 @@ int main( ) result= a ^ b; cout << result << endl; - result= a xor_eq b; + result= a xor b; cout << result << endl; } ``` diff --git a/docs/c-runtime-library/reference/y0-y1-yn.md b/docs/c-runtime-library/reference/y0-y1-yn.md index 77991781ee..6b3d311152 100644 --- a/docs/c-runtime-library/reference/y0-y1-yn.md +++ b/docs/c-runtime-library/reference/y0-y1-yn.md @@ -6,12 +6,12 @@ api_name: ["y1", "yn", "y0"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["yn", "y1", "y0"] +f1_keywords: ["CORECRT_MATH/yn", "CORECRT_MATH/y1", "CORECRT_MATH/y0", "yn", "y1", "y0"] helpviewer_keywords: ["y0 function", "y1 function", "yn function"] ms.assetid: e14215f3-53d4-4ae8-816e-4c1ec2019316 --- -# y0, y1, yn +# `y0`, `y1`, `yn` -The Microsoft-implemented POSIX function names `y0`, `y1`, and `yn` are deprecated aliases for the [_y0, _y1, and _yn](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `y0`, `y1`, and `yn` are deprecated aliases for the [`_y0`, `_y1`, and `_yn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_y0, _y1, and _yn](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_y0`, `_y1`, and `_yn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/required-and-optional-header-files.md b/docs/c-runtime-library/required-and-optional-header-files.md index d0abc8a319..679afb5450 100644 --- a/docs/c-runtime-library/required-and-optional-header-files.md +++ b/docs/c-runtime-library/required-and-optional-header-files.md @@ -7,18 +7,18 @@ f1_keywords: ["c.headers"] helpviewer_keywords: ["include files, required in run time", "header files, required in run time"] ms.assetid: f64d0bf5-e2c3-4b42-97d0-443b3d901d9f --- -# Required and Optional Header Files +# Required and optional header files -The description of each run-time routine includes a list of the required and optional include, or header (.H), files for that routine. Required header files need to be included to obtain the function declaration for the routine or a definition used by another routine called internally. Optional header files are usually included to take advantage of predefined constants, type definitions, or inline macros. The following table lists some examples of optional header file contents: +The description of each run-time routine includes a list of the required and optional include, or header (.H), files for that routine. Required header files need to be included to obtain the function declaration for the routine or a definition used by another routine called internally. Optional header files are often included to take advantage of predefined constants, type definitions, or inline macros. The following table lists some examples of optional header file contents: -|Definition|Example| -|----------------|-------------| -|Macro definition|If a library routine is implemented as a macro, the macro definition may be in a header file other than the header file for the original routine. For instance, the `_toupper` macro is defined in the header file CTYPE.H, while the function `toupper` is declared in STDLIB.H.| -|Predefined Constant|Many library routines refer to constants that are defined in header files. For instance, the `_open` routine uses constants such as `_O_CREAT`, which is defined in the header file FCNTL.H.| -|Type definition|Some library routines return a structure or take a structure as an argument. For example, stream input/output routines use a structure of type `FILE`, which is defined in STDIO.H.| +| Definition | Example | +|---|---| +| Macro definition | If a library routine is implemented as a macro, the macro definition may be in a header file other than the header file for the original routine. For instance, the `_toupper` macro is defined in the header file CTYPE.H, while the function `toupper` is declared in STDLIB.H. | +| Predefined Constant | Many library routines refer to constants that are defined in header files. For instance, the `_open` routine uses constants such as `_O_CREAT`, which is defined in the header file FCNTL.H. | +| Type definition | Some library routines return a structure or take a structure as an argument. For example, stream input/output routines use a structure of type `FILE`, which is defined in STDIO.H. | -The run-time library header files provide function declarations in the ANSI/ISO C standard recommended style. The compiler performs type checking on any routine reference that occurs after its associated function declaration. Function declarations are especially important for routines that return a value of some type other than **`int`**, which is the default. Routines that do not specify their appropriate return value in their declaration will be considered by the compiler to return an **`int`**, which can cause unexpected results. See [Type Checking](../c-runtime-library/type-checking-crt.md) for more information. +The run-time library header files provide function declarations in the ANSI/ISO C standard recommended style. The compiler performs type checking on any routine reference that occurs after its associated function declaration. Function declarations are especially important for routines that return a value of some type other than **`int`**, which is the default. Routines that don't specify their appropriate return value in their declaration will be considered by the compiler to return an **`int`**, which can cause unexpected results. For more information, see [Type checking](./type-checking-crt.md). ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/robustness.md b/docs/c-runtime-library/robustness.md index b6547f231f..0ea11d6d2f 100644 --- a/docs/c-runtime-library/robustness.md +++ b/docs/c-runtime-library/robustness.md @@ -9,16 +9,16 @@ ms.assetid: 7f1a87f8-eff9-4b76-ae9b-d133d3de6adf Use the following C run-time library functions to improve the robustness of your program. -## Run-Time Robustness Functions +## Run-time robustness functions -|Function|Use| -|--------------|---------| -|[_set_new_handler](../c-runtime-library/reference/set-new-handler.md)|Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory.| -|[_set_se_translator](../c-runtime-library/reference/set-se-translator.md)|Handles Win32 exceptions (C structured exceptions) as C++ typed exceptions.| -|[set_terminate](../c-runtime-library/reference/set-terminate-crt.md)|Installs your own termination function to be called by [terminate](../c-runtime-library/reference/terminate-crt.md).| -|[set_unexpected](../c-runtime-library/reference/set-unexpected-crt.md)|Installs your own termination function to be called by [unexpected](../c-runtime-library/reference/unexpected-crt.md).| +| Function | Use | +|---|---| +| [`_set_new_handler`](./reference/set-new-handler.md) | Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory. | +| [`_set_se_translator`](./reference/set-se-translator.md) | Handles Win32 exceptions (C structured exceptions) as C++ typed exceptions. | +| [`set_terminate`](./reference/set-terminate-crt.md) | Installs your own termination function to be called by [`terminate`](./reference/terminate-crt.md). | +| [`set_unexpected`](./reference/set-unexpected-crt.md) | Installs your own termination function to be called by [`unexpected`](./reference/unexpected-crt.md). | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[SetUnhandledExceptionFilter](/windows/win32/api/errhandlingapi/nf-errhandlingapi-setunhandledexceptionfilter)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[`SetUnhandledExceptionFilter`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-setunhandledexceptionfilter) diff --git a/docs/c-runtime-library/routine-mappings.md b/docs/c-runtime-library/routine-mappings.md index 1a89b74b20..087515c0cd 100644 --- a/docs/c-runtime-library/routine-mappings.md +++ b/docs/c-runtime-library/routine-mappings.md @@ -1,261 +1,264 @@ --- -description: "Learn more about: Routine Mappings" -title: "Routine Mappings" +description: "Learn more about: Microsoft specific generic-text functions and the CRT functions they map to." +title: "Generic-text function mappings" ms.date: "11/04/2016" -helpviewer_keywords: ["_tWinMain", "TCHAR.H data types, list of routine mappings", "generic-text mappings"] -ms.assetid: 38f33d3b-0f7b-430d-8a4f-75e27c6f1c42 +ms.author: twhitney +api_name: ["foo",] +f1_keywords: ["_cgetts", "_cgetts_s", "_cputts", "_fgettc", "_fgettchar", "_fgetts", "_fputtc", "_fputtchar", "_fputts", "_ftscanf", "_ftscanf_s", "_gettc", "_gettch", "_gettchar", "_gettche", "_getts", "_getts_s", "_istalnum", "_istalpha", "_istascii", "_istcntrl", "_istdigit", "_istgraph", "_istlead", "_istleadbyte", "_istlegal", "_istlower", "_istprint", "_istpunct", "_istspace", "_istupper", "_istxdigit", "_itot", "_itot_s", "_ltot", "_ltot_s", "_puttc", "_puttch", "_puttchar", "_putts", "_sctprintf", "_sntprintf", "_sntprintf_s", "_sntscanf", "_sntscanf_s", "_stprintf", "_stprintf_s", "_stscanf", "_stscanf_s", "_taccess", "_tasctime", "_tasctime_s", "_tccmp", "_tccpy", "_tccpy_s", "_tchdir", "_tclen", "_tchmod", "_tcprintf", "_tcprintf_s", "_tcreat", "_tcscanf", "_tcscanf_s", "_tcscat", "_tcscat_s", "_tcschr", "_tcsclen", "_tcsclen_s", "_tcscmp", "_tcscoll", "_tcscpy", "_tcscpy_s", "_tcscspn", "_tcsdec", "_tcsdup", "_tcserror", "_tcserror_s", "_tcsftime", "_tcsicmp", "_tcsicoll", "_tcsinc", "_tcslen", "_tcslwr", "_tcslwr_s", "_tcsnbcnt", "_tcsncat", "_tcsncat_s", "_tcsnccat", "_tcsnccmp", "_tcsnccmp_s", "_tcsnccoll", "_tcsncmp", "_tcsnccnt", "_tcsnccpy", "_tcsncicmp", "_tcsncicoll", "_tcsncpy", "_tcsncset", "_tcsnextc", "_tcsnicmp", "_tcsnicoll", "_tcsninc", "_tcsnccnt", "_tcsnset", "_tcspbrk", "_tcsspnp", "_tcsrchr", "_tcsrev", "_tcsset", "_tcsspn", "_tcsstr", "_tcstod", "_tcstoi64", "_tcstok", "_tcstok_s", "_tcstol", "_tcstoui64", "_tcstoul", "_tcsupr", "_tcsupr_s", "_tcsxfrm", "_tctime", "_tctime_s", "_tctime32", "_tctime32_s", "_tctime64", "_tctime64_s", "_texecl", "_texecle", "_texeclp", "_texeclpe", "_texecv", "_texecve", "_texecvp", "_texecvpe", "_tfdopen", "_tfindfirst", "_tfindnext", "_tfindnext32", "_tfindnext64", "_tfindnexti64", "_tfindnexti6432", "_tfindnext32i64", "_tfopen", "_tfopen_s", "_tfreopen", "_tfreopen_s", "_tfsopen", "_tfullpath", "_tgetcwd", "_tgetdcwd", "_tgetenv", "_tgetenv_s", "_tmain", "_tmakepath", "_tmakepath_s", "_tmkdir", "_tmktemp", "_tmktemp_s", "_topen", "_topen_s", "_totlower", "_totupper", "_tperror", "_tpopen", "_tprintf", "_tprintf_s", "_tputenv", "_tremove", "_trename", "_trmdir", "_tsearchenv", "_tsearchenv_s", "_tscanf", "_tscanf_s", "_tsetlocale", "_tsopen", "_tsopen_s", "_tspawnl", "_tspawnle", "_tspawnlp", "_tspawnlpe", "_tspawnv", "_tspawnve", "_tspawnvp", "_tspawnvpe", "_tsplitpath", "_tstat", "_tstat32", "_tstati32", "_tstat64", "_tstati64", "_tstof", "_tstoi", "_tstoi64", "_tstol", "_tstrdate", "_tstrdate_s", "_tstrtime", "_tstrtime_s", "_tsystem", "_ttempnam", "_ttmpnam", "_ttmpnam_s", "_ttoi", "_ttoi64", "_ttol", "_tunlink", "_tutime", "_tutime32", "_tutime64", "_tWinMain", "_ui64tot", "_ui64tot_s", "_ultot", "_ultot_s", "_ungettc", "_ungettch", "_vftprintf", "_vftprintf_s", "_vsctprintf", "_vsctprintf_s", "_vsntprintf", "_vsntprintf_s", "_vstprintf", "_vtprintf", "_vtprintf_s"] +helpviewer_keywords: ["_tWinMain", "TCHAR.H functions, list of generic-text function mappings", "generic-text mappings", "_cgetts function", "_cgetts_s function", "_cputts function", "_fgettc function", "_fgettchar function", "_fgetts function", "_fputtc function", "_fputtchar function", "_fputts function", "_ftscanf function", "_ftscanf_s function", "_gettc function", "_gettch function", "_gettchar function", "_gettche function", "_getts function", "_getts_s function", "_istalnum function", "_istalpha function", "_istascii function", "_istcntrl function", "_istdigit function", "_istgraph function", "_istlead function", "_istleadbyte function", "_istlegal function", "_istlower function", "_istprint function", "_istpunct function", "_istspace function", "_istupper function", "_istxdigit function", "_itot function", "_itot_s function", "_ltot function", "_ltot_s function", "_puttc function", "_puttch function", "_puttchar function", "_putts function", "_sctprintf function", "_sntprintf function", "_sntprintf_s function", "_sntscanf function", "_sntscanf_s function", "_stprintf function", "_stprintf_s function", "_stscanf function", "_stscanf_s function", "_taccess function", "_tasctime function", "_tasctime_s function", "_tccmp function", "_tccpy function", "_tccpy_s function", "_tchdir function", "_tclen function", "_tchmod function", "_tcprintf function", "_tcprintf_s function", "_tcreat function", "_tcscanf function", "_tcscanf_s function", "_tcscat function", "_tcscat_s function", "_tcschr function", "_tcsclen function", "_tcsclen_s function", "_tcscmp function", "_tcscoll function", "_tcscpy function", "_tcscpy_s function", "_tcscspn function", "_tcsdec function", "_tcsdup function", "_tcserror function", "_tcserror_s function", "_tcsftime function", "_tcsicmp function", "_tcsicoll function", "_tcsinc function", "_tcslen function", "_tcslwr function", "_tcslwr_s function", "_tcsnbcnt function", "_tcsncat function", "_tcsncat_s function", "_tcsnccat function", "_tcsnccmp function", "_tcsnccmp_s function", "_tcsnccoll function", "_tcsncmp function", "_tcsnccnt function", "_tcsnccpy function", "_tcsncicmp function", "_tcsncicoll function", "_tcsncpy function", "_tcsncset function", "_tcsnextc function", "_tcsnicmp function", "_tcsnicoll function", "_tcsninc function", "_tcsnccnt function", "_tcsnset function", "_tcspbrk function", "_tcsspnp function", "_tcsrchr function", "_tcsrev function", "_tcsset function", "_tcsspn function", "_tcsstr function", "_tcstod function", "_tcstoi64 function", "_tcstok function", "_tcstok_s function", "_tcstol function", "_tcstoui64 function", "_tcstoul function", "_tcsupr function", "_tcsupr_s function", "_tcsxfrm function", "_tctime function", "_tctime_s function", "_tctime32 function", "_tctime32_s function", "_tctime64 function", "_tctime64_s function", "_texecl function", "_texecle function", "_texeclp function", "_texeclpe function", "_texecv function", "_texecve function", "_texecvp function", "_texecvpe function", "_tfdopen function", "_tfindfirst function", "_tfindnext function", "_tfindnext32 function", "_tfindnext64 function", "_tfindnexti64 function", "_tfindnexti6432 function", "_tfindnext32i64 function", "_tfopen function", "_tfopen_s function", "_tfreopen function", "_tfreopen_s function", "_tfsopen function", "_tfullpath function", "_tgetcwd function", "_tgetdcwd function", "_tgetenv function", "_tgetenv_s function", "_tmain function", "_tmakepath function", "_tmakepath_s function", "_tmkdir function", "_tmktemp function", "_tmktemp_s function", "_topen function", "_topen_s function", "_totlower function", "_totupper function", "_tperror function", "_tpopen function", "_tprintf function", "_tprintf_s function", "_tputenv function", "_tremove function", "_trename function", "_trmdir function", "_tsearchenv function", "_tsearchenv_s function", "_tscanf function", "_tscanf_s function", "_tsetlocale function", "_tsopen function", "_tsopen_s function", "_tspawnl function", "_tspawnle function", "_tspawnlp function", "_tspawnlpe function", "_tspawnv function", "_tspawnve function", "_tspawnvp function", "_tspawnvpe function", "_tsplitpath function", "_tstat function", "_tstat32 function", "_tstati32 function", "_tstat64 function", "_tstati64 function", "_tstof function", "_tstoi function", "_tstoi64 function", "_tstol function", "_tstrdate function", "_tstrdate_s function", "_tstrtime function", "_tstrtime_s function", "_tsystem function", "_ttempnam function", "_ttmpnam function", "_ttmpnam_s function", "_ttoi function", "_ttoi64 function", "_ttol function", "_tunlink function", "_tutime function", "_tutime32 function", "_tutime64 function", "_tWinMain function", "_ui64tot function", "_ui64tot_s function", "_ultot function", "_ultot_s function", "_ungettc function", "_ungettch function", "_vftprintf function", "_vftprintf_s function", "_vsctprintf function", "_vsctprintf_s function", "_vsntprintf function", "_vsntprintf_s function", "_vstprintf function", "_vtprintf function", "_vtprintf_s function"] --- -# Routine Mappings +# Generic-text function mappings -The generic-text routine mappings are defined in TCHAR.H. `_tccpy` and `_tclen` map to functions in the MBCS model; they are mapped to macros or inline functions in the SBCS and Unicode models for completeness. For information on a generic text routine, see the help topic about the corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. +The generic-text routine mappings are defined in `TCHAR.H`. `_tccpy` and `_tclen` map to functions in the MBCS model; they're mapped to macros or inline functions in the SBCS and Unicode models for completeness. For information on a generic text routine, see the help article about the corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. -More specific information about individual routines listed in the left column in the following table is not available in this documentation. However, you can easily look up the information on a corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. Use the **Search** command on the **Help** menu to look up any generic-text routine listed below. +More specific information about individual routines listed in the left column in the following table isn't available in this documentation. However, you can easily look up the information on a corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. Use the **Search** command on the **Help** menu to look up any generic-text routine listed below. -For related information, see [Generic-Text Mappings in TCHAR.H](../text/generic-text-mappings-in-tchar-h.md). +For related information, see [Generic-text mappings in tchar.h](../text/generic-text-mappings-in-tchar-h.md). -### Generic-Text Routine Mappings +### Function mappings -|Generic-text routine name|SBCS (_UNICODE & MBCS not defined)|_MBCS defined|_UNICODE defined| -|--------------------------------|-------------------------------------------|--------------------|-----------------------| -|`_cgetts`|`_cgets`|`_cgets`|`_cgetws`| -|`_cgetts_s`|`_cgets_s`|`_cgets_s`|`_cgetws_s`| -|`_cputts`|`_cputs`|`_cputs`|`_cputws`| -|`_fgettc`|`fgetc`|`fgetc`|`fgetwc`| -|`_fgettchar`|`_fgetchar`|`_fgetchar`|`_fgetwchar`| -|`_fgetts`|`fgets`|`fgets`|`fgetws`| -|`_fputtc`|`fputc`|`fputc`|`fputwc`| -|`_fputtchar`|`_fputchar`|`_fputchar`|`_fputwchar`| -|`_fputts`|`fputs`|`fputs`|`fputws`| -|`_ftprintf`|`fprintf`|`fprintf`|`fwprintf`| -|`_ftprintf_s`|`fprintf_s`|`fprintf_s`|`fwprintf_s`| -|`_ftscanf`|`fscanf`|`fscanf`|`fwscanf`| -|`_ftscanf_s`|`fscanf_s`|`fscanf_s`|`fwscanf_s`| -|`_gettc`|`getc`|`getc`|`getwc`| -|`_gettch`|`_getch`|`_getch`|`_getwch`| -|`_gettchar`|`getchar`|`getchar`|`getwchar`| -|`_gettche`|`_getche`|`_getche`|`_getwche`| -|`_getts`|`gets`|`gets`|`getws`| -|`_getts_s`|`gets_s`|`gets_s`|`getws_s`| -|`_istalnum`|`isalnum`|`_ismbcalnum`|`iswalnum`| -|`_istalpha`|`isalpha`|`_ismbcalpha`|`iswalpha`| -|`_istascii`|`isascii`|`isascii`|`iswascii`| -|`_istcntrl`|`iscntrl`|`iscntrl`|`iswcntrl`| -|`_istdigit`|`isdigit`|`_ismbcdigit`|`iswdigit`| -|`_istgraph`|`isgraph`|`_ismbcgraph`|`iswgraph`| -|`_istlead`|Always returns false|`_ismbblead`|Always returns false| -|`_istleadbyte`|Always returns false|`isleadbyte`|Always returns false| -|`_istlegal`|Always returns true|`_ismbclegal`|Always returns true| -|`_istlower`|`islower`|`_ismbclower`|`iswlower`| -|`_istprint`|`isprint`|`_ismbcprint`|`iswprint`| -|`_istpunct`|`ispunct`|`_ismbcpunct`|`iswpunct`| -|`_istspace`|`isspace`|`_ismbcspace`|`iswspace`| -|`_istupper`|`isupper`|`_ismbcupper`|`iswupper`| -|`_istxdigit`|`isxdigit`|`isxdigit`|`iswxdigit`| -|`_itot`|`_itoa`|`_itoa`|`_itow`| -|`_itot_s`|`_itoa_s`|`_itoa_s`|`_itow_s`| -|`_ltot`|`_ltoa`|`_ltoa`|`_ltow`| -|`_ltot_s`|`_ltoa_s`|`_ltoa_s`|`_ltow_s`| -|`_puttc`|`putc`|`putc`|`putwc`| -|`_puttch`|`_putch`|`_putch`|`_putwch`| -|`_puttchar`|`putchar`|`putchar`|`putwchar`| -|`_putts`|`puts`|`puts`|`_putws`| -|`_sctprintf`|`_scprintf`|`_scprintf`|`_scwprintf`| -|`_sntprintf`|`_snprintf`|`_snprintf`|`_snwprintf`| -|`_sntprintf_s`|`_snprintf_s`|`_snprintf_s`|`_snwprintf_s`| -|`_sntscanf`|`_snscanf`|`_snscanf`|`_snwscanf`| -|`_sntscanf_s`|`_snscanf_s`|`_snscanf_s`|`_snwscanf_s`| -|`_stprintf`|`sprintf`|`sprintf`|`swprintf`| -|`_stprintf_s`|`sprintf_s`|`sprintf_s`|`swprintf_s`| -|`_stscanf`|`sscanf`|`sscanf`|`swscanf`| -|`_stscanf_s`|`sscanf_s`|`sscanf_s`|`swscanf_s`| -|`_taccess`|`_access`|`_access`|`_waccess`| -|`_taccess_s`|`_access_s`|`_access_s`|`_waccess_s`| -|`_tasctime`|`asctime`|`asctime`|`_wasctime`| -|`_tasctime_s`|`asctime_s`|`asctime_s`|`_wasctime_s`| -|`_tccmp`|Maps to macro or inline function|`_mbsncmp`|Maps to macro or inline function| -|`_tccpy`|Maps to macro or inline function|`_mbccpy`|Maps to macro or inline function| -|`_tccpy_s`|`strcpy_s`|`_mbccpy_s`|`wcscpy_s`| -|`_tchdir`|`_chdir`|`_chdir`|`_wchdir`| -|`_tclen`|Maps to macro or inline function|`_mbclen`|Maps to macro or inline function| -|`_tchmod`|`_chmod`|`_chmod`|`_wchmod`| -|`_tcprintf`|`_cprintf`|`_cprintf`|`_cwprintf`| -|`_tcprintf_s`|`_cprintf_s`|`_cprintf_s`|`_cwprintf_s`| -|`_tcreat`|`_creat`|`_creat`|`_wcreat`| -|`_tcscanf`|`_cscanf`|`_cscanf`|`_cwscanf`| -|`_tcscanf_s`|`_cscanf_s`|`_cscanf_s`|`_cwscanf_s`| -|`_tcscat`|`strcat`|`_mbscat`|`wcscat`| -|`_tcscat_s`|`strcat_s`|`_mbscat_s`|`wcscat_s`| -|`_tcschr`|`strchr`|`_mbschr`|`wcschr`| -|`_tcsclen`|`strlen`|`_mbslen`|`wcslen`| -|`_tcsclen_s`|`strlen_s`|`_mbslen_s`|`wcslen_s`| -|`_tcscmp`|`strcmp`|`_mbscmp`|`wcscmp`| -|`_tcscoll`|`strcoll`|`_mbscoll`|`wcscoll`| -|`_tcscpy`|`strcpy`|`_mbscpy`|`wcscpy`| -|`_tcscpy_s`|`strcpy_s`|`_mbscpy_s`|`wcscpy_s`| -|`_tcscspn`|`strcspn`|`_mbscspn`|`wcscspn`| -|`_tcsdec`|`_strdec`|`_mbsdec`|`_wcsdec`| -|`_tcsdup`|`_strdup`|`_mbsdup`|`_wcsdup`| -|`_tcserror`|`strerror`|`strerror`|`_wcserror`| -|`_tcserror_s`|`strerror_s`|`strerror_s`|`_wcserror_s`| -|`_tcsftime`|`strftime`|`strftime`|`wcsftime`| -|`_tcsicmp`|`_stricmp`|`_mbsicmp`|`_wcsicmp`| -|`_tcsicoll`|`_stricoll`|`_mbsicoll`|`_wcsicoll`| -|`_tcsinc`|`_strinc`|`_mbsinc`|`_wcsinc`| -|`_tcslen`|`strlen`|`strlen`|`wcslen`| -|`_tcslwr`|`_strlwr`|`_mbslwr`|`_wcslwr`| -|`_tcslwr_s`|`_strlwr_s`|`_mbslwr_s`|`_wcslwr_s`| -|`_tcsnbcnt`|`_strncnt`|`_mbsnbcnt`|`_wcsncnt`| -|`_tcsncat`|`strncat`|`_mbsnbcat`|`wcsncat`| -|`_tcsncat_s`|`strncat_s`|`_mbsnbcat_s`|`wcsncat_s`| -|`_tcsnccat`|`strncat`|`_mbsncat`|`wcsncat`| -|`_tcsnccmp`|`strncmp`|`_mbsncmp`|`wcsncmp`| -|`_tcsnccmp_s`|`strncmp_s`|`_mbsncmp_s`|`wcsncmp_s`| -|`_tcsnccoll`|`_strncoll`|`_mbsncoll`|`_wcsncoll`| -|`_tcsncmp`|`strncmp`|`_mbsnbcmp`|`wcsncmp`| -|`_tcsnccnt`|`_strncnt`|`_mbsnccnt`|`_wcsncnt`| -|`_tcsnccpy`|`strncpy`|`_mbsncpy`|`wcsncpy`| -|`_tcsnccpy_s`|`strncpy_s`|`_mbsncpy_s`|`wcsncpy_s`| -|`_tcsncicmp`|`_strnicmp`|`_mbsnicmp`|`_wcsnicmp`| -|`_tcsncicoll`|`_strnicoll`|`_mbsnicoll`|`_wcsnicoll`| -|`_tcsncpy`|`strncpy`|`_mbsnbcpy`|`wcsncpy`| -|`_tcsncpy_s`|`strncpy_s`|`_mbsnbcpy_s`|`wcsncpy_s`| -|`_tcsncset`|`_strnset`|`_mbsnset`|`_wcsnset`| -|`_tcsnextc`|`_strnextc`|`_mbsnextc`|`_wcsnextc`| -|`_tcsnicmp`|`_strnicmp`|`_mbsnbicmp`|`_wcsnicmp`| -|`_tcsnicoll`|`_strnicoll`|`_mbsnbicoll`|`_wcsnicoll`| -|`_tcsninc`|`_strninc`|`_mbsninc`|`_wcsninc`| -|`_tcsnccnt`|`_strncnt`|`_mbsnccnt`|`_wcsncnt`| -|`_tcsnset`|`_strnset`|`_mbsnbset`|`_wcsnset`| -|`_tcspbrk`|`strpbrk`|`_mbspbrk`|`wcspbrk`| -|`_tcsspnp`|`_strspnp`|`_mbsspnp`|`_wcsspnp`| -|`_tcsrchr`|`strrchr`|`_mbsrchr`|`wcsrchr`| -|`_tcsrev`|`_strrev`|`_mbsrev`|`_wcsrev`| -|`_tcsset`|`_strset`|`_mbsset`|`_wcsset`| -|`_tcsspn`|`strspn`|`_mbsspn`|`wcsspn`| -|`_tcsstr`|`strstr`|`_mbsstr`|`wcsstr`| -|`_tcstod`|`strtod`|`strtod`|`wcstod`| -|`_tcstoi64`|`_strtoi64`|`_strtoi64`|`_wcstoi64`| -|`_tcstok`|`strtok`|`_mbstok`|`wcstok`| -|`_tcstok_s`|`strtok_s`|`_mbstok_s`|`wcstok_s`| -|`_tcstol`|`strtol`|`strtol`|`wcstol`| -|`_tcstoui64`|`_strtoui64`|`_strtoui64`|`_wcstoui64`| -|`_tcstoul`|`strtoul`|`strtoul`|`wcstoul`| -|`_tcsupr`|`_strupr`|`_mbsupr`|`_wcsupr`| -|`_tcsupr_s`|`_strupr_s`|`_mbsupr_s`|`_wcsupr_s`| -|`_tcsxfrm`|`strxfrm`|`strxfrm`|`wcsxfrm`| -|`_tctime`|`ctime`|`ctime`|`_wctime`| -|`_tctime_s`|`ctime_s`|`ctime_s`|`_wctime_s`| -|`_tctime32`|`_ctime32`|`_ctime32`|`_wctime32`| -|`_tctime32_s`|`_ctime32_s`|`_ctime32_s`|`_wctime32_s`| -|`_tctime64`|`_ctime64`|`_ctime64`|`_wctime64`| -|`_tctime64_s`|`_ctime64_s`|`_ctime64_s`|`_wctime64_s`| -|`_texecl`|`_execl`|`_execl`|`_wexecl`| -|`_texecle`|`_execle`|`_execle`|`_wexecle`| -|`_texeclp`|`_execlp`|`_execlp`|`_wexeclp`| -|`_texeclpe`|`_execlpe`|`_execlpe`|`_wexeclpe`| -|`_texecv`|`_execv`|`_execv`|`_wexecv`| -|`_texecve`|`_execve`|`_execve`|`_wexecve`| -|`_texecvp`|`_execvp`|`_execvp`|`_wexecvp`| -|`_texecvpe`|`_execvpe`|`_execvpe`|`_wexecvpe`| -|`_tfdopen`|`_fdopen`|`_fdopen`|`_wfdopen`| -|`_tfindfirst`|`_findfirst`|`_findfirst`|`_wfindfirst`| -|`_tfindnext`|`_findnext`|`_findnext`|`_wfindnext`| -|`_tfindnext32`|`_findnext32`|`_findnext32`|`_wfindnext32`| -|`_tfindnext64`|`_findnext64`|`_findnext64`|`_wfindnext64`| -|`_tfindnexti64`|`_findnexti64`|`_findnexti64`|`_wfindnexti64`| -|`_tfindnexti6432`|`_findnexti6432`|`_findnexti6432`|`_wfindnexti6432`| -|`_tfindnext32i64`|`_findnext32i64`|`_findnext32i64`|`_wfindnext32i64`| -|`_tfopen`|`fopen`|`fopen`|`_wfopen`| -|`_tfopen_s`|`fopen_s`|`fopen_s`|`_wfopen_s`| -|`_tfreopen`|`freopen`|`freopen`|`_wfreopen`| -|`_tfreopen_s`|`freopen_s`|`freopen_s`|`_wfreopen_s`| -|`_tfsopen`|`_fsopen`|`_fsopen`|`_wfsopen`| -|`_tfullpath`|`_fullpath`|`_fullpath`|`_wfullpath`| -|`_tgetcwd`|`_getcwd`|`_getcwd`|`_wgetcwd`| -|`_tgetdcwd`|`_getdcwd`|`_getdcwd`|`_wgetdcwd`| -|`_tgetenv`|`getenv`|`getenv`|`_wgetenv`| -|`_tgetenv_s`|`getenv_s`|`getenv_s`|`_wgetenv_s`| -|`_tmain`|`main`|`main`|`wmain`| -|`_tmakepath`|`_makepath`|`_makepath`|`_wmakepath`| -|`_tmakepath_s`|`_makepath_s`|`_makepath_s`|`_wmakepath_s`| -|`_tmkdir`|`_mkdir`|`_mkdir`|`_wmkdir`| -|`_tmktemp`|`_mktemp`|`_mktemp`|`_wmktemp`| -|`_tmktemp_s`|`_mktemp_s`|`_mktemp_s`|`_wmktemp_s`| -|`_topen`|`_open`|`_open`|`_wopen`| -|`_topen_s`|`_open_s`|`_open_s`|`_wopen_s`| -|`_totlower`|`tolower`|`_mbctolower`|`towlower`| -|`_totupper`|`toupper`|`_mbctoupper`|`towupper`| -|`_tperror`|`perror`|`perror`|`_wperror`| -|`_tpopen`|`_popen`|`_popen`|`_wpopen`| -|`_tprintf`|`printf`|`printf`|`wprintf`| -|`_tprintf_s`|`printf_s`|`printf_s`|`wprintf_s`| -|`_tputenv`|`_putenv`|`_putenv`|`_wputenv`| -|`_tputenv_s`|`_putenv_s`|`_putenv_s`|`_wputenv_s`| -|`_tremove`|`remove`|`remove`|`_wremove`| -|`_trename`|`rename`|`rename`|`_wrename`| -|`_trmdir`|`_rmdir`|`_rmdir`|`_wrmdir`| -|`_tsearchenv`|`_searchenv`|`_searchenv`|`_wsearchenv`| -|`_tsearchenv_s`|`_searchenv_s`|`_searchenv_s`|`_wsearchenv_s`| -|`_tscanf`|`scanf`|`scanf`|`wscanf`| -|`_tscanf_s`|`scanf_s`|`scanf_s`|`wscanf_s`| -|`_tsetlocale`|`setlocale`|`setlocale`|`_wsetlocale`| -|`_tsopen`|`_sopen`|`_sopen`|`_wsopen`| -|`_tsopen_s`|`_sopen_s`|`_sopen_s`|`_wsopen_s`| -|`_tspawnl`|`_spawnl`|`_spawnl`|`_wspawnl`| -|`_tspawnle`|`_spawnle`|`_spawnle`|`_wspawnle`| -|`_tspawnlp`|`_spawnlp`|`_spawnlp`|`_wspawnlp`| -|`_tspawnlpe`|`_spawnlpe`|`_spawnlpe`|`_wspawnlpe`| -|`_tspawnv`|`_spawnv`|`_spawnv`|`_wspawnv`| -|`_tspawnve`|`_spawnve`|`_spawnve`|`_wspawnve`| -|`_tspawnvp`|`_spawnvp`|`_spawnvp`|`_wspawnvp`| -|`_tspawnvpe`|`_spawnvpe`|`_spawnvpe`|`_wspawnvpe`| -|`_tsplitpath`|`_splitpath`|`_splitpath`|`_wsplitpath`| -|`_tstat`|`_stat`|`_stat`|`_wstat`| -|`_tstat32`|`_stat32`|`_stat32`|`_wstat32`| -|`_tstati32`|`_stati32`|`_stati32`|`_wstati32`| -|`_tstat64`|`_stat64`|`_stat64`|`_wstat64`| -|`_tstati64`|`_stati64`|`_stati64`|`_wstati64`| -|`_tstof`|`atof`|`atof`|`_wtof`| -|`_tstoi`|`atoi`|`atoi`|`_wtoi`| -|`_tstoi64`|`_atoi64`|`_atoi64`|`_wtoi64`| -|`_tstol`|`atol`|`atol`|`_wtol`| -|`_tstrdate`|`_strdate`|`_strdate`|`_wstrdate`| -|`_tstrdate_s`|`_strdate_s`|`_strdate_s`|`_wstrdate_s`| -|`_tstrtime`|`_strtime`|`_strtime`|`_wstrtime`| -|`_tstrtime_s`|`_strtime_s`|`_strtime_s`|`_wstrtime_s`| -|`_tsystem`|`system`|`system`|`_wsystem`| -|`_ttempnam`|`_tempnam`|`_tempnam`|`_wtempnam`| -|`_ttmpnam`|`tmpnam`|`tmpnam`|`_wtmpnam`| -|`_ttmpnam_s`|`tmpnam_s`|`tmpnam_s`|`_wtmpnam_s`| -|`_ttoi`|`atoi`|`atoi`|`_wtoi`| -|`_ttoi64`|`_atoi64`|`_atoi64`|`_wtoi64`| -|`_ttol`|`atol`|`atol`|`_wtol`| -|`_tunlink`|`_unlink`|`_unlink`|`_wunlink`| -|`_tutime`|`_utime`|`_utime`|`_wutime`| -|`_tutime32`|`_utime32`|`_utime32`|`_wutime32`| -|`_tutime64`|`_utime64`|`_utime64`|`_wutime64`| -|`_tWinMain`|`WinMain`|`WinMain`|`wWinMain`| -|`_ui64tot`|`_ui64toa`|`_ui64toa`|`_ui64tow`| -|`_ui64tot_s`|`_ui64toa_s`|`_ui64toa_s`|`_ui64tow_s`| -|`_ultot`|`_ultoa`|`_ultoa`|`_ultow`| -|`_ultot_s`|`_ultoa_s`|`_ultoa_s`|`_ultow_s`| -|`_ungettc`|`ungetc`|`ungetc`|`ungetwc`| -|`_ungettch`|`_ungetch`|`_ungetch`|`_ungetwch`| -|`_vftprintf`|`vfprintf`|`vfprintf`|`vfwprintf`| -|`_vftprintf_s`|`vfprintf_s`|`vfprintf_s`|`vfwprintf_S`| -|`_vsctprintf`|`_vscprintf`|`_vscprintf`|`_vscwprintf`| -|`_vsctprintf_s`|`_vscprintf_s`|`_vscprintf_s`|`_vscwprintf_S`| -|`_vsntprintf`|`_vsnprintf`|`_vsnprintf`|`_vsnwprintf`| -|`_vsntprintf_s`|`_vsnprintf_s`|`_vsnprintf_s`|`_vsnwprintf_s`| -|`_vstprintf`|`vsprintf`|`vsprintf`|`vswprintf`| -|`_vstprintf_s`|`vsprintf_s`|`vsprintf_s`|`vswprintf_s`| -|`_vtprintf`|`vprintf`|`vprintf`|`vwprintf`| -|`_vtprintf_s`|`vprintf_s`|`vprintf_s`|`vwprintf_s`| +| Generic-text routine name | `SBCS` (`_UNICODE` and `MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cgetts` | `_cgets` | `_cgets` | `_cgetws` | +| `_cgetts_s` | `_cgets_s` | `_cgets_s` | `_cgetws_s` | +| `_cputts` | `_cputs` | `_cputs` | `_cputws` | +| `_fgettc` | `fgetc` | `fgetc` | `fgetwc` | +| `_fgettchar` | `_fgetchar` | `_fgetchar` | `_fgetwchar` | +| `_fgetts` | `fgets` | `fgets` | `fgetws` | +| `_fputtc` | `fputc` | `fputc` | `fputwc` | +| `_fputtchar` | `_fputchar` | `_fputchar` | `_fputwchar` | +| `_fputts` | `fputs` | `fputs` | `fputws` | +| `_ftprintf` | `fprintf` | `fprintf` | `fwprintf` | +| `_ftprintf_l` | `_fprintf_l` | `_fprintf_l` | `_fwprintf_l` | +| `_ftprintf_s` | `fprintf_s` | `fprintf_s` | `fwprintf_s` | +| `_ftscanf` | `fscanf` | `fscanf` | `fwscanf` | +| `_ftscanf_s` | `fscanf_s` | `fscanf_s` | `fwscanf_s` | +| `_gettc` | `getc` | `getc` | `getwc` | +| `_gettch` | `_getch` | `_getch` | `_getwch` | +| `_gettchar` | `getchar` | `getchar` | `getwchar` | +| `_gettche` | `_getche` | `_getche` | `_getwche` | +| `_getts` | `gets` | `gets` | `getws` | +| `_getts_s` | `gets_s` | `gets_s` | `getws_s` | +| `_istalnum` | `isalnum` | `_ismbcalnum` | `iswalnum` | +| `_istalpha` | `isalpha` | `_ismbcalpha` | `iswalpha` | +| `_istascii` | `isascii` | `isascii` | `iswascii` | +| `_istcntrl` | `iscntrl` | `iscntrl` | `iswcntrl` | +| `_istdigit` | `isdigit` | `_ismbcdigit` | `iswdigit` | +| `_istgraph` | `isgraph` | `_ismbcgraph` | `iswgraph` | +| `_istlead` | Always returns false | `_ismbblead` | Always returns false | +| `_istleadbyte` | Always returns false | `isleadbyte` | Always returns false | +| `_istlegal` | Always returns true | `_ismbclegal` | Always returns true | +| `_istlower` | `islower` | `_ismbclower` | `iswlower` | +| `_istprint` | `isprint` | `_ismbcprint` | `iswprint` | +| `_istpunct` | `ispunct` | `_ismbcpunct` | `iswpunct` | +| `_istspace` | `isspace` | `_ismbcspace` | `iswspace` | +| `_istupper` | `isupper` | `_ismbcupper` | `iswupper` | +| `_istxdigit` | `isxdigit` | `isxdigit` | `iswxdigit` | +| `_itot` | `_itoa` | `_itoa` | `_itow` | +| `_itot_s` | `_itoa_s` | `_itoa_s` | `_itow_s` | +| `_ltot` | `_ltoa` | `_ltoa` | `_ltow` | +| `_ltot_s` | `_ltoa_s` | `_ltoa_s` | `_ltow_s` | +| `_puttc` | `putc` | `putc` | `putwc` | +| `_puttch` | `_putch` | `_putch` | `_putwch` | +| `_puttchar` | `putchar` | `putchar` | `putwchar` | +| `_putts` | `puts` | `puts` | `_putws` | +| `_sctprintf` | `_scprintf` | `_scprintf` | `_scwprintf` | +| `_sntprintf` | `_snprintf` | `_snprintf` | `_snwprintf` | +| `_sntprintf_s` | `_snprintf_s` | `_snprintf_s` | `_snwprintf_s` | +| `_sntscanf` | `_snscanf` | `_snscanf` | `_snwscanf` | +| `_sntscanf_s` | `_snscanf_s` | `_snscanf_s` | `_snwscanf_s` | +| `_stprintf` | `sprintf` | `sprintf` | `swprintf` | +| `_stprintf_s` | `sprintf_s` | `sprintf_s` | `swprintf_s` | +| `_stscanf` | `sscanf` | `sscanf` | `swscanf` | +| `_stscanf_s` | `sscanf_s` | `sscanf_s` | `swscanf_s` | +| `_taccess` | `_access` | `_access` | `_waccess` | +| `_taccess_s` | `_access_s` | `_access_s` | `_waccess_s` | +| `_tasctime` | `asctime` | `asctime` | `_wasctime` | +| `_tasctime_s` | `asctime_s` | `asctime_s` | `_wasctime_s` | +| `_tccmp` | Maps to macro or inline function | `_mbsncmp` | Maps to macro or inline function | +| `_tccpy` | Maps to macro or inline function | `_mbccpy` | Maps to macro or inline function | +| `_tccpy_s` | `strcpy_s` | `_mbccpy_s` | `wcscpy_s` | +| `_tchdir` | `_chdir` | `_chdir` | `_wchdir` | +| `_tclen` | Maps to macro or inline function | `_mbclen` | Maps to macro or inline function | +| `_tchmod` | `_chmod` | `_chmod` | `_wchmod` | +| `_tcprintf` | `_cprintf` | `_cprintf` | `_cwprintf` | +| `_tcprintf_s` | `_cprintf_s` | `_cprintf_s` | `_cwprintf_s` | +| `_tcreat` | `_creat` | `_creat` | `_wcreat` | +| `_tcscanf` | `_cscanf` | `_cscanf` | `_cwscanf` | +| `_tcscanf_s` | `_cscanf_s` | `_cscanf_s` | `_cwscanf_s` | +| `_tcscat` | `strcat` | `_mbscat` | `wcscat` | +| `_tcscat_s` | `strcat_s` | `_mbscat_s` | `wcscat_s` | +| `_tcschr` | `strchr` | `_mbschr` | `wcschr` | +| `_tcsclen` | `strlen` | `_mbslen` | `wcslen` | +| `_tcsclen_s` | `strlen_s` | `_mbslen_s` | `wcslen_s` | +| `_tcscmp` | `strcmp` | `_mbscmp` | `wcscmp` | +| `_tcscoll` | `strcoll` | `_mbscoll` | `wcscoll` | +| `_tcscpy` | `strcpy` | `_mbscpy` | `wcscpy` | +| `_tcscpy_s` | `strcpy_s` | `_mbscpy_s` | `wcscpy_s` | +| `_tcscspn` | `strcspn` | `_mbscspn` | `wcscspn` | +| `_tcsdec` | `_strdec` | `_mbsdec` | `_wcsdec` | +| `_tcsdup` | `_strdup` | `_mbsdup` | `_wcsdup` | +| `_tcserror` | `strerror` | `strerror` | `_wcserror` | +| `_tcserror_s` | `strerror_s` | `strerror_s` | `_wcserror_s` | +| `_tcsftime` | `strftime` | `strftime` | `wcsftime` | +| `_tcsicmp` | `_stricmp` | `_mbsicmp` | `_wcsicmp` | +| `_tcsicoll` | `_stricoll` | `_mbsicoll` | `_wcsicoll` | +| `_tcsinc` | `_strinc` | `_mbsinc` | `_wcsinc` | +| `_tcslen` | `strlen` | `strlen` | `wcslen` | +| `_tcslwr` | `_strlwr` | `_mbslwr` | `_wcslwr` | +| `_tcslwr_s` | `_strlwr_s` | `_mbslwr_s` | `_wcslwr_s` | +| `_tcsnbcnt` | `_strncnt` | `_mbsnbcnt` | `_wcsncnt` | +| `_tcsncat` | `strncat` | `_mbsnbcat` | `wcsncat` | +| `_tcsncat_s` | `strncat_s` | `_mbsnbcat_s` | `wcsncat_s` | +| `_tcsnccat` | `strncat` | `_mbsncat` | `wcsncat` | +| `_tcsnccmp` | `strncmp` | `_mbsncmp` | `wcsncmp` | +| `_tcsnccmp_s` | `strncmp_s` | `_mbsncmp_s` | `wcsncmp_s` | +| `_tcsnccoll` | `_strncoll` | `_mbsncoll` | `_wcsncoll` | +| `_tcsncmp` | `strncmp` | `_mbsnbcmp` | `wcsncmp` | +| `_tcsnccnt` | `_strncnt` | `_mbsnccnt` | `_wcsncnt` | +| `_tcsnccpy` | `strncpy` | `_mbsncpy` | `wcsncpy` | +| `_tcsnccpy_s` | `strncpy_s` | `_mbsncpy_s` | `wcsncpy_s` | +| `_tcsncicmp` | `_strnicmp` | `_mbsnicmp` | `_wcsnicmp` | +| `_tcsncicoll` | `_strnicoll` | `_mbsnicoll` | `_wcsnicoll` | +| `_tcsncpy` | `strncpy` | `_mbsnbcpy` | `wcsncpy` | +| `_tcsncpy_s` | `strncpy_s` | `_mbsnbcpy_s` | `wcsncpy_s` | +| `_tcsncset` | `_strnset` | `_mbsnset` | `_wcsnset` | +| `_tcsnextc` | `_strnextc` | `_mbsnextc` | `_wcsnextc` | +| `_tcsnicmp` | `_strnicmp` | `_mbsnbicmp` | `_wcsnicmp` | +| `_tcsnicoll` | `_strnicoll` | `_mbsnbicoll` | `_wcsnicoll` | +| `_tcsninc` | `_strninc` | `_mbsninc` | `_wcsninc` | +| `_tcsnccnt` | `_strncnt` | `_mbsnccnt` | `_wcsncnt` | +| `_tcsnset` | `_strnset` | `_mbsnbset` | `_wcsnset` | +| `_tcspbrk` | `strpbrk` | `_mbspbrk` | `wcspbrk` | +| `_tcsspnp` | `_strspnp` | `_mbsspnp` | `_wcsspnp` | +| `_tcsrchr` | `strrchr` | `_mbsrchr` | `wcsrchr` | +| `_tcsrev` | `_strrev` | `_mbsrev` | `_wcsrev` | +| `_tcsset` | `_strset` | `_mbsset` | `_wcsset` | +| `_tcsspn` | `strspn` | `_mbsspn` | `wcsspn` | +| `_tcsstr` | `strstr` | `_mbsstr` | `wcsstr` | +| `_tcstod` | `strtod` | `strtod` | `wcstod` | +| `_tcstoi64` | `_strtoi64` | `_strtoi64` | `_wcstoi64` | +| `_tcstok` | `strtok` | `_mbstok` | `wcstok` | +| `_tcstok_s` | `strtok_s` | `_mbstok_s` | `wcstok_s` | +| `_tcstol` | `strtol` | `strtol` | `wcstol` | +| `_tcstoui64` | `_strtoui64` | `_strtoui64` | `_wcstoui64` | +| `_tcstoul` | `strtoul` | `strtoul` | `wcstoul` | +| `_tcsupr` | `_strupr` | `_mbsupr` | `_wcsupr` | +| `_tcsupr_s` | `_strupr_s` | `_mbsupr_s` | `_wcsupr_s` | +| `_tcsxfrm` | `strxfrm` | `strxfrm` | `wcsxfrm` | +| `_tctime` | `ctime` | `ctime` | `_wctime` | +| `_tctime_s` | `ctime_s` | `ctime_s` | `_wctime_s` | +| `_tctime32` | `_ctime32` | `_ctime32` | `_wctime32` | +| `_tctime32_s` | `_ctime32_s` | `_ctime32_s` | `_wctime32_s` | +| `_tctime64` | `_ctime64` | `_ctime64` | `_wctime64` | +| `_tctime64_s` | `_ctime64_s` | `_ctime64_s` | `_wctime64_s` | +| `_texecl` | `_execl` | `_execl` | `_wexecl` | +| `_texecle` | `_execle` | `_execle` | `_wexecle` | +| `_texeclp` | `_execlp` | `_execlp` | `_wexeclp` | +| `_texeclpe` | `_execlpe` | `_execlpe` | `_wexeclpe` | +| `_texecv` | `_execv` | `_execv` | `_wexecv` | +| `_texecve` | `_execve` | `_execve` | `_wexecve` | +| `_texecvp` | `_execvp` | `_execvp` | `_wexecvp` | +| `_texecvpe` | `_execvpe` | `_execvpe` | `_wexecvpe` | +| `_tfdopen` | `_fdopen` | `_fdopen` | `_wfdopen` | +| `_tfindfirst` | `_findfirst` | `_findfirst` | `_wfindfirst` | +| `_tfindnext` | `_findnext` | `_findnext` | `_wfindnext` | +| `_tfindnext32` | `_findnext32` | `_findnext32` | `_wfindnext32` | +| `_tfindnext64` | `_findnext64` | `_findnext64` | `_wfindnext64` | +| `_tfindnexti64` | `_findnexti64` | `_findnexti64` | `_wfindnexti64` | +| `_tfindnexti6432` | `_findnexti6432` | `_findnexti6432` | `_wfindnexti6432` | +| `_tfindnext32i64` | `_findnext32i64` | `_findnext32i64` | `_wfindnext32i64` | +| `_tfopen` | `fopen` | `fopen` | `_wfopen` | +| `_tfopen_s` | `fopen_s` | `fopen_s` | `_wfopen_s` | +| `_tfreopen` | `freopen` | `freopen` | `_wfreopen` | +| `_tfreopen_s` | `freopen_s` | `freopen_s` | `_wfreopen_s` | +| `_tfsopen` | `_fsopen` | `_fsopen` | `_wfsopen` | +| `_tfullpath` | `_fullpath` | `_fullpath` | `_wfullpath` | +| `_tgetcwd` | `_getcwd` | `_getcwd` | `_wgetcwd` | +| `_tgetdcwd` | `_getdcwd` | `_getdcwd` | `_wgetdcwd` | +| `_tgetenv` | `getenv` | `getenv` | `_wgetenv` | +| `_tgetenv_s` | `getenv_s` | `getenv_s` | `_wgetenv_s` | +| `_tmain` | `main` | `main` | `wmain` | +| `_tmakepath` | `_makepath` | `_makepath` | `_wmakepath` | +| `_tmakepath_s` | `_makepath_s` | `_makepath_s` | `_wmakepath_s` | +| `_tmkdir` | `_mkdir` | `_mkdir` | `_wmkdir` | +| `_tmktemp` | `_mktemp` | `_mktemp` | `_wmktemp` | +| `_tmktemp_s` | `_mktemp_s` | `_mktemp_s` | `_wmktemp_s` | +| `_topen` | `_open` | `_open` | `_wopen` | +| `_topen_s` | `_open_s` | `_open_s` | `_wopen_s` | +| `_totlower` | `tolower` | `_mbctolower` | `towlower` | +| `_totupper` | `toupper` | `_mbctoupper` | `towupper` | +| `_tperror` | `perror` | `perror` | `_wperror` | +| `_tpopen` | `_popen` | `_popen` | `_wpopen` | +| `_tprintf` | `printf` | `printf` | `wprintf` | +| `_tprintf_s` | `printf_s` | `printf_s` | `wprintf_s` | +| `_tputenv` | `_putenv` | `_putenv` | `_wputenv` | +| `_tputenv_s` | `_putenv_s` | `_putenv_s` | `_wputenv_s` | +| `_tremove` | `remove` | `remove` | `_wremove` | +| `_trename` | `rename` | `rename` | `_wrename` | +| `_trmdir` | `_rmdir` | `_rmdir` | `_wrmdir` | +| `_tsearchenv` | `_searchenv` | `_searchenv` | `_wsearchenv` | +| `_tsearchenv_s` | `_searchenv_s` | `_searchenv_s` | `_wsearchenv_s` | +| `_tscanf` | `scanf` | `scanf` | `wscanf` | +| `_tscanf_s` | `scanf_s` | `scanf_s` | `wscanf_s` | +| `_tsetlocale` | `setlocale` | `setlocale` | `_wsetlocale` | +| `_tsopen` | `_sopen` | `_sopen` | `_wsopen` | +| `_tsopen_s` | `_sopen_s` | `_sopen_s` | `_wsopen_s` | +| `_tspawnl` | `_spawnl` | `_spawnl` | `_wspawnl` | +| `_tspawnle` | `_spawnle` | `_spawnle` | `_wspawnle` | +| `_tspawnlp` | `_spawnlp` | `_spawnlp` | `_wspawnlp` | +| `_tspawnlpe` | `_spawnlpe` | `_spawnlpe` | `_wspawnlpe` | +| `_tspawnv` | `_spawnv` | `_spawnv` | `_wspawnv` | +| `_tspawnve` | `_spawnve` | `_spawnve` | `_wspawnve` | +| `_tspawnvp` | `_spawnvp` | `_spawnvp` | `_wspawnvp` | +| `_tspawnvpe` | `_spawnvpe` | `_spawnvpe` | `_wspawnvpe` | +| `_tsplitpath` | `_splitpath` | `_splitpath` | `_wsplitpath` | +| `_tstat` | `_stat` | `_stat` | `_wstat` | +| `_tstat32` | `_stat32` | `_stat32` | `_wstat32` | +| `_tstati32` | `_stati32` | `_stati32` | `_wstati32` | +| `_tstat64` | `_stat64` | `_stat64` | `_wstat64` | +| `_tstati64` | `_stati64` | `_stati64` | `_wstati64` | +| `_tstof` | `atof` | `atof` | `_wtof` | +| `_tstoi` | `atoi` | `atoi` | `_wtoi` | +| `_tstoi64` | `_atoi64` | `_atoi64` | `_wtoi64` | +| `_tstol` | `atol` | `atol` | `_wtol` | +| `_tstrdate` | `_strdate` | `_strdate` | `_wstrdate` | +| `_tstrdate_s` | `_strdate_s` | `_strdate_s` | `_wstrdate_s` | +| `_tstrtime` | `_strtime` | `_strtime` | `_wstrtime` | +| `_tstrtime_s` | `_strtime_s` | `_strtime_s` | `_wstrtime_s` | +| `_tsystem` | `system` | `system` | `_wsystem` | +| `_ttempnam` | `_tempnam` | `_tempnam` | `_wtempnam` | +| `_ttmpnam` | `tmpnam` | `tmpnam` | `_wtmpnam` | +| `_ttmpnam_s` | `tmpnam_s` | `tmpnam_s` | `_wtmpnam_s` | +| `_ttoi` | `atoi` | `atoi` | `_wtoi` | +| `_ttoi64` | `_atoi64` | `_atoi64` | `_wtoi64` | +| `_ttol` | `atol` | `atol` | `_wtol` | +| `_tunlink` | `_unlink` | `_unlink` | `_wunlink` | +| `_tutime` | `_utime` | `_utime` | `_wutime` | +| `_tutime32` | `_utime32` | `_utime32` | `_wutime32` | +| `_tutime64` | `_utime64` | `_utime64` | `_wutime64` | +| `_tWinMain` | `WinMain` | `WinMain` | `wWinMain` | +| `_ui64tot` | `_ui64toa` | `_ui64toa` | `_ui64tow` | +| `_ui64tot_s` | `_ui64toa_s` | `_ui64toa_s` | `_ui64tow_s` | +| `_ultot` | `_ultoa` | `_ultoa` | `_ultow` | +| `_ultot_s` | `_ultoa_s` | `_ultoa_s` | `_ultow_s` | +| `_ungettc` | `ungetc` | `ungetc` | `ungetwc` | +| `_ungettch` | `_ungetch` | `_ungetch` | `_ungetwch` | +| `_vftprintf` | `vfprintf` | `vfprintf` | `vfwprintf` | +| `_vftprintf_s` | `vfprintf_s` | `vfprintf_s` | `vfwprintf_S` | +| `_vsctprintf` | `_vscprintf` | `_vscprintf` | `_vscwprintf` | +| `_vsctprintf_s` | `_vscprintf_s` | `_vscprintf_s` | `_vscwprintf_S` | +| `_vsntprintf` | `_vsnprintf` | `_vsnprintf` | `_vsnwprintf` | +| `_vsntprintf_s` | `_vsnprintf_s` | `_vsnprintf_s` | `_vsnwprintf_s` | +| `_vstprintf` | `vsprintf` | `vsprintf` | `vswprintf` | +| `_vstprintf_s` | `vsprintf_s` | `vsprintf_s` | `vswprintf_s` | +| `_vtprintf` | `vprintf` | `vprintf` | `vwprintf` | +| `_vtprintf_s` | `vprintf_s` | `vprintf_s` | `vwprintf_s` | ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/rtdynamiccast.md b/docs/c-runtime-library/rtdynamiccast.md index 47de02d92b..791143e7c0 100644 --- a/docs/c-runtime-library/rtdynamiccast.md +++ b/docs/c-runtime-library/rtdynamiccast.md @@ -3,49 +3,48 @@ description: "Learn more about: __RTDynamicCast" title: "__RTDynamicCast" ms.date: "1/14/2021" api_name: ["__RTDynamicCast"] -api_location: ["msvcr90.dll", "msvcr110.dll", "msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr110.dll", "msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__RTDynamicCast"] +f1_keywords: ["RTTIDATA/__RTDynamicCast", "__RTDynamicCast"] helpviewer_keywords: ["__RTDynamicCast"] -ms.assetid: 56aa2d7a-aa47-46ef-830d-e37175611239 --- -# __RTDynamicCast +# `__RTDynamicCast` -Runtime implementation of the [dynamic_cast](../cpp/dynamic-cast-operator.md) operator. +Runtime implementation of the [`dynamic_cast`](../cpp/dynamic-cast-operator.md) operator. ## Syntax ```cpp -PVOID __RTDynamicCast ( +PVOID __RTDynamicCast( PVOID inptr, LONG VfDelta, PVOID SrcType, PVOID TargetType, BOOL isReference - ) throw(...) +) throw(...) ``` #### Parameters -*inptr*
+*`inptr`*\ Pointer to a polymorphic object. -*VfDelta*
+*`VfDelta`*\ Offset of virtual function pointer in object. -*SrcType*
+*`SrcType`*\ Static type of object pointed to by the `inptr` parameter. -*TargetType*
+*`TargetType`*\ Intended result of cast. -*isReference*
+*`isReference`*\ **`true`** if input is a reference; **`false`** if input is a pointer. -## Return Value +## Return value -Pointer to the appropriate sub-object, if successful; otherwise, **NULL**. +Pointer to the appropriate subobject if successful; otherwise, `NULL`. ## Exceptions @@ -57,6 +56,6 @@ Converts `inptr` to an object of type `TargetType`. The type of `inptr` must be ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__RTDynamicCast|rtti.h| +| Routine | Required header | +|---|---| +| **`__RTDynamicCast`** | `` | diff --git a/docs/c-runtime-library/run-time-error-checking.md b/docs/c-runtime-library/run-time-error-checking.md index 90bfd33b54..29ce32a4e1 100644 --- a/docs/c-runtime-library/run-time-error-checking.md +++ b/docs/c-runtime-library/run-time-error-checking.md @@ -12,16 +12,16 @@ Use the following functions to customize the way your program does runtime error ## Runtime error checking functions -|Function|Use| -|--------------|---------| -|[_RTC_GetErrDesc](../c-runtime-library/reference/rtc-geterrdesc.md)|Returns a brief description of a runtime error check type.| -|[_RTC_NumErrors](../c-runtime-library/reference/rtc-numerrors.md)|Returns the total number of errors that can be detected by runtime error checks.| -|[_RTC_SetErrorFunc](../c-runtime-library/reference/rtc-seterrorfunc.md)|Designates a function as the handler for reporting runtime error checks.| -|[_RTC_SetErrorType](../c-runtime-library/reference/rtc-seterrortype.md)|Associates an error that is detected by runtime error checks with a type.| +| Function | Use | +|---|---| +| [`_RTC_GetErrDesc`](./reference/rtc-geterrdesc.md) | Returns a brief description of a runtime error check type. | +| [`_RTC_NumErrors`](./reference/rtc-numerrors.md) | Returns the total number of errors that can be detected by runtime error checks. | +| [`_RTC_SetErrorFunc`](./reference/rtc-seterrorfunc.md) | Designates a function as the handler for reporting runtime error checks. | +| [`_RTC_SetErrorType`](./reference/rtc-seterrortype.md) | Associates an error that is detected by runtime error checks with a type. | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ [/RTC (Runtime error checks)](../build/reference/rtc-run-time-error-checks.md)\ -[runtime_checks](../preprocessor/runtime-checks.md)\ -[Debug routines](../c-runtime-library/debug-routines.md) +[`runtime_checks`](../preprocessor/runtime-checks.md)\ +[Debug routines](./debug-routines.md) diff --git a/docs/c-runtime-library/run-time-routines-by-category.md b/docs/c-runtime-library/run-time-routines-by-category.md index 82114a3308..9fe6744b4a 100644 --- a/docs/c-runtime-library/run-time-routines-by-category.md +++ b/docs/c-runtime-library/run-time-routines-by-category.md @@ -13,36 +13,30 @@ This section lists Universal C runtime (UCRT) library routines by category. For The main categories of UCRT library routines are: -:::row::: - :::column span=""::: - [Argument Access](../c-runtime-library/argument-access.md)\ - [Buffer Manipulation](../c-runtime-library/buffer-manipulation.md)\ - [Byte Classification](../c-runtime-library/byte-classification.md)\ - [Character Classification](../c-runtime-library/character-classification.md)\ - [Complex math support](../c-runtime-library/complex-math-support.md)\ - [Data Alignment](../c-runtime-library/data-alignment.md)\ - [Data Conversion](../c-runtime-library/data-conversion.md)\ - [Debug Routines](../c-runtime-library/debug-routines.md)\ - [Directory Control](../c-runtime-library/directory-control.md)\ - [Error Handling](../c-runtime-library/error-handling-crt.md)\ - [Exception Handling Routines](../c-runtime-library/exception-handling-routines.md)\ - [File Handling](../c-runtime-library/file-handling.md) - :::column-end::: - :::column span=""::: - [Floating-Point Support](../c-runtime-library/floating-point-support.md)\ - [Input and Output](../c-runtime-library/input-and-output.md)\ - [Internationalization](../c-runtime-library/internationalization.md)\ - [Memory Allocation](../c-runtime-library/memory-allocation.md)\ - [Process and Environment Control](../c-runtime-library/process-and-environment-control.md)\ - [Robustness](../c-runtime-library/robustness.md)\ - [Run-Time Error Checking](../c-runtime-library/run-time-error-checking.md)\ - [Searching and Sorting](../c-runtime-library/searching-and-sorting.md)\ - [String Manipulation](../c-runtime-library/string-manipulation-crt.md)\ - [System Calls](../c-runtime-library/system-calls.md)\ - [Time Management](../c-runtime-library/time-management.md) - :::column-end::: -:::row-end::: +- [Argument access](./argument-access.md) +- [Buffer manipulation](./buffer-manipulation.md) +- [Byte classification](./byte-classification.md) +- [Character classification](./character-classification.md) +- [Complex math support](./complex-math-support.md) +- [Data alignment](./data-alignment.md) +- [Data conversion](./data-conversion.md) +- [Debug routines](./debug-routines.md) +- [Directory control](./directory-control.md) +- [Error handling](./error-handling-crt.md) +- [Exception handling routines](./exception-handling-routines.md) +- [File handling](./file-handling.md) +- [Math and floating-point support](./floating-point-support.md) +- [Input and output](./input-and-output.md) +- [Internationalization](./internationalization.md) +- [Memory allocation](./memory-allocation.md) +- [Process and environment control](./process-and-environment-control.md) +- [Robustness](./robustness.md) +- [Runtime error checking](./run-time-error-checking.md) +- [Searching and sorting](./searching-and-sorting.md) +- [String manipulation](./string-manipulation-crt.md) +- [System calls](./system-calls.md) +- [Time management](./time-management.md) ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
+[C runtime library reference](./c-run-time-library-reference.md) diff --git a/docs/c-runtime-library/sal-annotations.md b/docs/c-runtime-library/sal-annotations.md index 40aaed2477..1307e5f0a2 100644 --- a/docs/c-runtime-library/sal-annotations.md +++ b/docs/c-runtime-library/sal-annotations.md @@ -6,12 +6,12 @@ ms.topic: "conceptual" helpviewer_keywords: ["__z annotation", "ref annotation", "_opt annotation", "__checkreturn annotatioin", "__deref_opt annotation", "deref_opt annotation", "__deref annotation", "__in annotation", "annotations [C++]", "z annotation", "_inout annotation", "__ref annotation", "full annotation", "_in annotation", "_ref annotation", "__out annotation", "_ecount annotation", "SAL annotations", "__opt annotation", "inout annotation", "in annotation", "_CA_SHOULD_CHECK_RETURN", "__bcount annotation", "_full annotation", "_bcount annotation", "deref annotation", "part annotation", "_out annotation", "__nz annotation", "__part annotation", "opt annotation", "__full annotation", "_nz annotation", "_z annotation", "out annotation", "__ecount annotation", "__inout annotation", "SAL annotations, _CA_SHOULD_CHECK_RETURN", "_deref_opt annotation", "_deref annotation", "nz annotation", "_part annotation", "ecount annotation", "bcount annotation"] ms.assetid: 81893638-010c-41a0-9cb3-666fe360f3e0 --- -# SAL Annotations +# SAL annotations -If you examine the library header files, you may notice some unusual annotations, for example, `_In_z` and `_Out_z_cap_(_Size)`. These are examples of the Microsoft source-code annotation language (SAL), which provides a set of annotations to describe how a function uses its parameters, for example, the assumptions it makes about them and the guarantees it makes on finishing. The header file \ defines the annotations. +If you examine the library header files, you may notice some unusual annotations, for example, `_In_z` and `_Out_z_cap_(_Size)`. These annotations are examples of the Microsoft source-code annotation language (SAL). SAL provides a set of annotations to describe how a function uses its parameters and return type. For example, it indicates the assumptions it makes about them and the guarantees it makes on finishing. The header file \ defines the annotations. -For more information about using SAL annotations in Visual Studio, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +For more information about using SAL annotations in Visual Studio, see [Using SAL annotations to reduce C/C++ code defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/sbcs-and-mbcs-data-types.md b/docs/c-runtime-library/sbcs-and-mbcs-data-types.md index baad2737c2..71473d9c2b 100644 --- a/docs/c-runtime-library/sbcs-and-mbcs-data-types.md +++ b/docs/c-runtime-library/sbcs-and-mbcs-data-types.md @@ -3,28 +3,28 @@ title: "SBCS and MBCS Data Types" description: "How to represent single and multibyte characters in the Microsoft C runtime." ms.topic: "conceptual" ms.date: "04/11/2018" -f1_keywords: ["MBCS", "SBCS"] +f1_keywords: ["_MBCS", "MBCS", "SBCS"] helpviewer_keywords: ["SBCS and MBCS data types", "data types [C], MBCS and SBCS"] ms.assetid: 4c3ef9da-e397-48d4-800e-49dba36db171 --- -# SBCS and MBCS Data Types +# SBCS and MBCS data types -Any Microsoft MBCS run-time library routine that handles only 1 multibyte character or 1 byte of a multibyte character expects an **`unsigned int`** argument (where 0x00 <= character value <= 0xFFFF and 0x00 <= byte value <= 0xFF). An MBCS routine that handles multibyte bytes or characters in a string context expects a multibyte-character string to be represented as an **`unsigned char`** pointer. +Any Microsoft MBCS run-time library routine that handles only a single multibyte character, or a single byte of a multibyte character, expects an **`unsigned int`** argument (where 0x0000 <= character value <= 0xFFFF and 0x00 <= byte value <= 0xFF). An MBCS routine that handles multibyte bytes or characters in a string context expects a multibyte-character string to be represented as an **`unsigned char`** pointer. > [!CAUTION] > Each byte of a multibyte character can be represented in an 8-bit **`char`**. However, an SBCS or MBCS single-byte character of type **`char`** with a value greater than 0x7F is negative. When such a character is converted directly to an **`int`** or a **`long`**, the result is sign-extended by the compiler and can therefore yield unexpected results. It's best to represent a byte of a multibyte character as an 8-bit **`unsigned char`**. Or, to avoid a negative result, convert a single-byte character of type **`char`** to an **`unsigned char`** before converting it to an **`int`** or a **`long`**. -Because some SBCS string-handling functions take (signed) **`char`**\* parameters, a type mismatch compiler warning will result when **_MBCS** is defined. There are three ways to avoid this warning, listed in order of efficiency: +Because some SBCS string-handling functions take (signed) **`char`**\* parameters, a type mismatch compiler warning will result when `_MBCS` is defined. There are three ways to avoid this warning, listed in order of efficiency: -1. Use the type-safe inline functions in TCHAR.H. This is the default behavior. +1. Use the type-safe inline functions in TCHAR.H. This behavior is the default. -1. Use the direct macros in TCHAR.H by defining **_MB_MAP_DIRECT** on the command line. If you do this, you must manually match types. This is the fastest method but isn't type-safe. +1. Use the direct macros in TCHAR.H by defining `_MB_MAP_DIRECT` on the command line. If you do, you must manually match types. This method is the fastest but isn't type-safe. -1. Use the type-safe statically linked library functions in TCHAR.H. To do so, define the constant **_NO_INLINING** on the command line. This is the slowest method, but the most type-safe. +1. Use the type-safe statically linked library functions in TCHAR.H. To do so, define the constant `_NO_INLINING` on the command line. This method is the slowest, but the most type-safe. ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/scanf-type-field-characters.md b/docs/c-runtime-library/scanf-type-field-characters.md index 9401c8ae34..f8fbb3cff2 100644 --- a/docs/c-runtime-library/scanf-type-field-characters.md +++ b/docs/c-runtime-library/scanf-type-field-characters.md @@ -3,35 +3,34 @@ description: "Learn more about: scanf Type Field Characters" title: "scanf Type Field Characters" ms.date: "11/04/2016" helpviewer_keywords: ["scanf function, type field characters"] -ms.assetid: 5d546a84-715b-44ca-b1c5-bbe997f9ff62 --- -# scanf Type Field Characters +# `scanf` type field characters The following information applies to any of the `scanf` family of functions, including the secure versions, such as `scanf_s`. The `type` character is the only required format field; it appears after any optional format fields. The `type` character determines whether the associated argument is interpreted as a character, string, or number. -### Type Characters for scanf functions - -|Character|Type of input expected|Type of argument|Size argument in secure version?| -|---------------|----------------------------|----------------------|--------------------------------------| -|`c`|Character. When used with `scanf` functions, specifies single-byte character; when used with `wscanf` functions, specifies wide character. White-space characters that are ordinarily skipped are read when `c` is specified. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`.|Pointer to **`char`** when used with `scanf` functions, pointer to **`wchar_t`** when used with `wscanf` functions.|Required. Size does not include space for a null terminator.| -|`C`|Opposite size character. When used with `scanf` functions, specifies wide character; when used with `wscanf` functions, specifies single-byte character. White-space characters that are ordinarily skipped are read when `C` is specified. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`.|Pointer to **`wchar_t`** when used with `scanf` functions, pointer to **`char`** when used with `wscanf` functions.|Required. Size argument does not include space for a null terminator.| -|`d`|Decimal integer.|Pointer to **`int`**.|No.| -|`i`|An integer. Hexadecimal if the input string begins with "0x" or "0X", octal if the string begins with "0", otherwise decimal.|Pointer to **`int`**.|No.| -|`o`|Octal integer.|Pointer to **`int`**.|No.| -|`p`|A pointer address in hexadecimal digits. The maximum number of digits read depends on the size of a pointer (32 or 64 bits), which depends on the machine architecture. "0x" or "0X" are accepted as prefixes.|Pointer to **`void*`**.|No.| -|`u`|Unsigned decimal integer.|Pointer to **`unsigned int`**.|No.| -|`x`|Hexadecimal integer.|Pointer to **`int`**.|No.| -|`e`, `E`, `f`, `F`, `g`, `G`|Floating-point value consisting of optional sign (+ or -), series of one or more decimal digits containing decimal point, and optional exponent ("e" or "E") followed by an optionally signed integer value.|Pointer to **`float`**.|No.| -|`a`, `A`|Floating-point value consisting of a series of one or more hexadecimal digits containing an optional decimal point, and an exponent ("p" or "P") followed by a decimal value.|Pointer to **`float`**.|No.| -|`n`|No input read from stream or buffer.|Pointer to **`int`**, into which is stored number of characters successfully read from stream or buffer up to that point in current call to `scanf` functions or `wscanf` functions.|No.| -|`s`|String, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [scanf Width Specification](../c-runtime-library/scanf-width-specification.md).|When used with `scanf` functions, signifies single-byte character array; when used with `wscanf` functions, signifies wide-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended.|Required. Size includes space for a null terminator.| -|`S`|Opposite-size character string, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [scanf Width Specification](../c-runtime-library/scanf-width-specification.md).|When used with `scanf` functions, signifies wide-character array; when used with `wscanf` functions, signifies single-byte-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended.|Required. Size includes space for a null terminator.| - -The size arguments, if required, should be passed in the parameter list immediately following the argument they apply to. For example, the following code: - -``` +### `type` Characters for `scanf` functions + +| Character | Type of input expected | Type of argument | Size argument in secure version? | +|---|---|---|---| +| `c` | Character. When used with `scanf` functions, specifies single-byte character; when used with `wscanf` functions, specifies wide character. White-space characters that are ordinarily skipped are read when `c` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`. | Pointer to **`char`** when used with `scanf` functions, pointer to **`wchar_t`** when used with `wscanf` functions. | Required. Size doesn't include space for a null terminator. | +| `C` | Opposite size character. When used with `scanf` functions, specifies wide character; when used with `wscanf` functions, specifies single-byte character. White-space characters that are ordinarily skipped are read when `C` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`. | Pointer to **`wchar_t`** when used with `scanf` functions, pointer to **`char`** when used with `wscanf` functions. | Required. Size argument doesn't include space for a null terminator. | +| `d` | Decimal integer. | Pointer to **`int`**. | No. | +| `i` | An integer. Hexadecimal if the input string begins with "0x" or "0X", octal if the string begins with "0", otherwise decimal. | Pointer to **`int`**. | No. | +| `o` | Octal integer. | Pointer to **`int`**. | No. | +| `p` | A pointer address in hexadecimal digits. The maximum number of digits read depends on the size of a pointer (32 bits or 64 bits), which depends on the machine architecture. "0x" or "0X" are accepted as prefixes. | Pointer to **`void*`**. | No. | +| `u` | Unsigned decimal integer. | Pointer to **`unsigned int`**. | No. | +| `x` | Hexadecimal integer. | Pointer to **`int`**. | No. | +| `e`, `E`, `f`, `F`, `g`, `G` | Floating-point value consisting of optional sign (+ or -), series of one or more decimal digits containing decimal point, and optional exponent ("e" or "E") followed by an optionally signed integer value. | Pointer to **`float`**. | No. | +| `a`, `A` | Floating-point value consisting of a series of one or more hexadecimal digits containing an optional decimal point, and an exponent ("p" or "P") followed by a decimal value. | Pointer to **`float`**. | No. | +| `n` | No input read from stream or buffer. | Pointer to **`int`**, into which is stored number of characters successfully read from stream or buffer up to that point in current call to `scanf` functions or `wscanf` functions. | No. | +| `s` | String, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](./scanf-width-specification.md). | When used with `scanf` functions, signifies single-byte character array; when used with `wscanf` functions, signifies wide-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended. | Required. Size includes space for a null terminator. | +| `S` | Opposite-size character string, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](./scanf-width-specification.md). | When used with `scanf` functions, signifies wide-character array; when used with `wscanf` functions, signifies single-byte-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended. | Required. Size includes space for a null terminator. | + +The size arguments, if necessary, should be passed in the parameter list immediately following the argument they apply to. For example, the following code: + +```C char string1[11], string2[9]; scanf_s("%10s %8s", string1, 11, string2, 9); ``` @@ -40,15 +39,15 @@ reads a string with a maximum length of 10 into `string1`, and a string with a m The format string can handle single-byte or wide character input regardless of whether the single-byte character or wide-character version of the function is used. Thus, to read single-byte or wide characters with `scanf` functions and `wscanf` functions, use format specifiers as follows. -|To read character as|Use this function|With these format specifiers| -|--------------------------|-----------------------|----------------------------------| -|single byte|`scanf` functions|`c`, `hc`, or `hC`| -|single byte|`wscanf` functions|`C`, `hc`, or `hC`| -|wide|`wscanf` functions|`c`, `lc`, or `lC`| -|wide|`scanf` functions|`C`, `lc`, or `lC`| +| To read character as | Use this function | With these format specifiers | +|---|---|---| +| single byte | `scanf` functions | `c`, `hc`, or `hC` | +| single byte | `wscanf` functions | `C`, `hc`, or `hC` | +| wide | `wscanf` functions | `c`, `lc`, or `lC` | +| wide | `scanf` functions | `C`, `lc`, or `lC` | To scan strings with `scanf` functions, and `wscanf` functions, use the above table with format type-specifiers `s` and `S` instead of `c` and `C`. ## See also -[scanf, _scanf_l, wscanf, _wscanf_l](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md) diff --git a/docs/c-runtime-library/scanf-width-specification.md b/docs/c-runtime-library/scanf-width-specification.md index b92ecd9166..10def004d7 100644 --- a/docs/c-runtime-library/scanf-width-specification.md +++ b/docs/c-runtime-library/scanf-width-specification.md @@ -26,33 +26,33 @@ If the *`width`* field isn't used, `scanf_s` attempts to read the entire token i ## The size prefix -The optional prefixes **`h`**, **`hh`**, **`l`**, **`ll`**, **`I64`**, and **`L`** indicate the size of the `argument` (long or short, single-byte character or wide character, depending upon the type character that they modify). These format-specification characters are used with type characters in `scanf` or `wscanf` functions to specify interpretation of arguments as shown in the following table. The type prefix **`I64`** is a Microsoft extension and isn't compatible with Standard C. The type characters and their meanings are described in the "Type Characters for scanf functions" table in [`scanf` Type Field Characters](../c-runtime-library/scanf-type-field-characters.md). +The optional prefixes **`h`**, **`hh`**, **`l`**, **`ll`**, **`I64`**, and **`L`** indicate the size of the `argument` (long or short, single-byte character or wide character, depending upon the type character that they modify). These format-specification characters are used with type characters in `scanf` or `wscanf` functions to specify interpretation of arguments as shown in the following table. The type prefix **`I64`** is a Microsoft extension and isn't compatible with Standard C. The type characters and their meanings are described in the "Type Characters for scanf functions" table in [`scanf` type field characters](./scanf-type-field-characters.md). > [!NOTE] > The **`h`**, **`l`**, and **`L`** prefixes are Microsoft extensions when used with data of type **`char`**. ### Size prefixes for `scanf` and `wscanf` format-type specifiers -|To specify|Use prefix|With type specifier| -|----------------|----------------|-------------------------| -|**`double`**|**`l`**|**`e`**, **`E`**, **`f`**, **`g`**, or **`G`**| -|**`long double`** (same as **`double`**)|**`L`**|**`e`**, **`E`**, **`f`**, **`g`**, or **`G`**| -|**`long int`**|**`l`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`long unsigned int`**|**`l`**|**`u`**| -|**`long long`**|**`ll`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`short int`**|**`h`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`short unsigned int`**|**`h`**|**`u`**| -|**`char`**|**`hh`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`unsigned char`**|**`hh`**|**`u`**| -|**`int64`**|**`I64`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|Single-byte character with `scanf`|**`h`**|**`c`** or **`C`**| -|Single-byte character with `wscanf`|**`h`**|**`c`** or **`C`**| -|Wide character with `scanf`|**`l`**|**`c`** or **`C`**| -|Wide character with `wscanf`|**`l`**|**`c`**, or **`C`**| -|Single-byte character string with `scanf`|**`h`**|**`s`** or **`S`**| -|Single-byte character string with `wscanf`|**`h`**|**`s`** or **`S`**| -|Wide character string with `scanf`|**`l`**|**`s`** or **`S`**| -|Wide character string with `wscanf`|**`l`**|**`s`** or **`S`**| +| To specify | Use prefix | With type specifier | +|---|---|---| +| **`double`** | **`l`** | **`e`**, **`E`**, **`f`**, **`g`**, or **`G`** | +| **`long double`** (same as **`double`**) | **`L`** | **`e`**, **`E`**, **`f`**, **`g`**, or **`G`** | +| **`long int`** | **`l`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`long unsigned int`** | **`l`** | **`u`** | +| **`long long`** | **`ll`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`short int`** | **`h`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`short unsigned int`** | **`h`** | **`u`** | +| **`char`** | **`hh`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`unsigned char`** | **`hh`** | **`u`** | +| **`int64`** | **`I64`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| Single-byte character with `scanf` | **`h`** | **`c`** or **`C`** | +| Single-byte character with `wscanf` | **`h`** | **`c`** or **`C`** | +| Wide character with `scanf` | **`l`** | **`c`** or **`C`** | +| Wide character with `wscanf` | **`l`** | **`c`**, or **`C`** | +| Single-byte character string with `scanf` | **`h`** | **`s`** or **`S`** | +| Single-byte character string with `wscanf` | **`h`** | **`s`** or **`S`** | +| Wide character string with `scanf` | **`l`** | **`s`** or **`S`** | +| Wide character string with `wscanf` | **`l`** | **`s`** or **`S`** | The following examples use **`h`** and **`l`** with `scanf_s` functions and `wscanf_s` functions: @@ -89,7 +89,7 @@ For whatever reason, when the `scanf` function stops reading an input field, the ## See also -[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)
-[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[Format Specification Fields: `scanf` and `wscanf` Functions](../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md)
-[`scanf` Type Field Characters](../c-runtime-library/scanf-type-field-characters.md)
+[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[Format specification fields: `scanf` and `wscanf` functions](./format-specification-fields-scanf-and-wscanf-functions.md)\ +[`scanf` type field characters](./scanf-type-field-characters.md) diff --git a/docs/c-runtime-library/searching-and-sorting.md b/docs/c-runtime-library/searching-and-sorting.md index 1eb7dbdb23..706301f3b0 100644 --- a/docs/c-runtime-library/searching-and-sorting.md +++ b/docs/c-runtime-library/searching-and-sorting.md @@ -5,23 +5,23 @@ ms.date: "11/04/2016" helpviewer_keywords: ["sorting data", "data [CRT], searching", "searching [C++], CRT search functions", "searching [C++]"] ms.assetid: 15e984f0-e155-46f5-8542-51c458792f54 --- -# Searching and Sorting +# Searching and sorting Use the following functions for searching and sorting. -## Searching and Sorting Functions +## Searching and sorting functions -|Function|Search or Sort| -|--------------|--------------------| -|[bsearch](../c-runtime-library/reference/bsearch.md)|Binary search| -|[bsearch_s](../c-runtime-library/reference/bsearch-s.md)|A more secure version of **bsearch**| -|[_lfind](../c-runtime-library/reference/lfind.md)|Linear search for given value| -|[_lfind_s](../c-runtime-library/reference/lfind-s.md)|A more secure version of **_lfind**| -|[_lsearch](../c-runtime-library/reference/lsearch.md)|Linear search for given value, which is added to array if not found| -|[_lsearch_s](../c-runtime-library/reference/lsearch-s.md)|A more secure version of **_lsearch**| -|[qsort](../c-runtime-library/reference/qsort.md)|Quick sort| -|[qsort_s](../c-runtime-library/reference/qsort-s.md)|A more secure version of **qsort**| +| Function | Search or Sort | +|---|---| +| [`bsearch`](./reference/bsearch.md) | Binary search | +| [`bsearch_s`](./reference/bsearch-s.md) | A more secure version of `bsearch` | +| [`_lfind`](./reference/lfind.md) | Linear search for given value | +| [`_lfind_s`](./reference/lfind-s.md) | A more secure version of `_lfind` | +| [`_lsearch`](./reference/lsearch.md) | Linear search for given value, which is added to array if not found | +| [`_lsearch_s`](./reference/lsearch-s.md) | A more secure version of `_lsearch` | +| [`qsort`](./reference/qsort.md) | Quick sort | +| [`qsort_s`](./reference/qsort-s.md) | A more secure version of `qsort` | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/secure-template-overloads.md b/docs/c-runtime-library/secure-template-overloads.md index 6b42b4911c..865c43c2ab 100644 --- a/docs/c-runtime-library/secure-template-overloads.md +++ b/docs/c-runtime-library/secure-template-overloads.md @@ -7,7 +7,7 @@ f1_keywords: ["_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES", "_CRT_SECURE_CPP_OVERLO helpviewer_keywords: ["_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES", "_CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES", "_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT", "secure template overloads"] ms.assetid: 562741d0-39c0-485e-8529-73d740f29f8f --- -# Secure Template Overloads +# Secure template overloads Microsoft has deprecated many C Runtime library (CRT) functions in favor of security-enhanced versions. For example, `strcpy_s` is the more secure replacement for `strcpy`. The deprecated functions are common sources of security bugs, because they don't prevent operations that can overwrite memory. By default, the compiler produces a deprecation warning when you use one of these functions. The CRT provides C++ template overloads for these functions to help ease the transition to the more secure variants. @@ -25,7 +25,7 @@ char szBuf[10]; strcpy_s(szBuf, 10, "test"); // security-enhanced _s function ``` -The template overloads provide additional choices. If you define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` to 1, this enables template overloads of standard CRT functions that call the more secure variants automatically. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is 1, then no changes to your code are necessary. Behind the scenes, the call to `strcpy` is changed to a call to `strcpy_s` with the size argument supplied automatically. +The template overloads provide more choices. If you define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` to 1, it enables template overloads of standard CRT functions that call the more secure variants automatically. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is 1, then no changes to your code are necessary. Behind the scenes, the call to `strcpy` is changed to a call to `strcpy_s` with the size argument supplied automatically. ```cpp #define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 @@ -36,7 +36,7 @@ char szBuf[10]; strcpy(szBuf, "test"); // ==> strcpy_s(szBuf, 10, "test") ``` -The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` doesn't affect the functions that take a count, such as `strncpy`. To enable template overloads for the count functions, define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` to 1. Before doing so, however, make sure that your code passes the count of characters, not the size of the buffer (a common mistake). Also, code that explicitly writes a null terminator at the end of the buffer after the function call is unnecessary if the secure variant is called. If you need truncation behavior, see [_TRUNCATE](../c-runtime-library/truncate.md). +The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` doesn't affect the functions that take a count, such as `strncpy`. To enable template overloads for the count functions, define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` to 1. Before doing so, however, make sure that your code passes the count of characters, not the size of the buffer (a common mistake). Also, code that explicitly writes a null terminator at the end of the buffer after the function call is unnecessary if the secure variant is called. If you need truncation behavior, see [`_TRUNCATE`](./truncate.md). > [!NOTE] > The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` requires that `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is also defined as 1. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` is defined as 1 and `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is defined as 0, the application will not perform any template overloads. @@ -56,7 +56,7 @@ Only the name of the function needs to be changed (by adding "_s"); the template By default, `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` and `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` are defined as 0 (disabled) and `_CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES` is defined as 1 (enabled). -These template overloads only work for static arrays. Dynamically allocated buffers require additional source code changes. Revisiting the above examples: +The template overloads only work for static arrays. Dynamically allocated buffers require other source code changes. Revisiting the above examples: ```cpp #define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 @@ -68,7 +68,7 @@ strcpy(szBuf, "test"); // still deprecated; change it to // strcpy_s(szBuf, 10, "test"); ``` -And this: +And this example: ```cpp #define _CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES 1 @@ -82,5 +82,5 @@ strcpy_s(szBuf, "test"); // doesn't compile; change it to ## See also -[Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md)
-[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Security features in the CRT](./security-features-in-the-crt.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md b/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md index d86139ec35..30a570fbaa 100644 --- a/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md +++ b/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md @@ -5,92 +5,92 @@ ms.date: "03/21/2018" helpviewer_keywords: ["security [CRT]", "security-enhanced CRT", "CRT, security enhancements"] ms.assetid: f87e5a01-4cb2-4379-9e8f-d4693828c55a --- -# Security-Enhanced Versions of CRT Functions +# Security-enhanced versions of CRT functions -More secure versions of run-time library routines are available. For further information concerning security enhancements in the CRT, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). +More secure versions of run-time library routines are available. For more information about security enhancements in the CRT, see [Security features in the CRT](./security-features-in-the-crt.md). ## Secure functions -|CRT Function|Security enhanced function|Use| -|------------------|--------------------------------|---------| -|[_access, _waccess](../c-runtime-library/reference/access-waccess.md)|[_access_s, _waccess_s](../c-runtime-library/reference/access-s-waccess-s.md)|Determine file-access permission| -|[_alloca](../c-runtime-library/reference/alloca.md)|[_malloca](../c-runtime-library/reference/malloca.md)|Allocate memory on the stack| -|[asctime, _wasctime](../c-runtime-library/reference/asctime-wasctime.md)|[asctime_s, _wasctime_s](../c-runtime-library/reference/asctime-s-wasctime-s.md)|Convert time from type `struct tm` to character string| -|[bsearch](../c-runtime-library/reference/bsearch.md)|[bsearch_s](../c-runtime-library/reference/bsearch-s.md)|Perform a binary search of a sorted array| -|[_cgets, _cgetws](../c-runtime-library/cgets-cgetws.md)|[_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md)|Get a character string from the console| -|[_chsize](../c-runtime-library/reference/chsize.md)|[_chsize_s](../c-runtime-library/reference/chsize-s.md)|Change the size of a file| -|[clearerr](../c-runtime-library/reference/clearerr.md)|[clearerr_s](../c-runtime-library/reference/clearerr-s.md)|Reset the error indicator for a stream| -|[_control87, _controlfp, \__control87_2](../c-runtime-library/reference/control87-controlfp-control87-2.md)|[_controlfp_s](../c-runtime-library/reference/controlfp-s.md)|Get and set the floating-point control word| -|[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|[_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](../c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)|Format and print to the console| -|[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](../c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md)|[_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](../c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)|Read formatted data from the console| -|[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)|[_ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)|Convert time from type `time_t`, `__time32_t` or `__time64_t` to character string| -|[_ecvt](../c-runtime-library/reference/ecvt.md)|[_ecvt_s](../c-runtime-library/reference/ecvt-s.md)|Convert a **`double`** number to a string| -|[_fcvt](../c-runtime-library/reference/fcvt.md)|[_fcvt_s](../c-runtime-library/reference/fcvt-s.md)|Converts a floating-point number to a string| -|[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)|[fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md)|Open a file| -|[fprintf, _fprintf_l, fwprintf, _fwprintf_l](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)|Print formatted data to a stream| -|[fread](../c-runtime-library/reference/fread.md)|[fread_s](../c-runtime-library/reference/fread-s.md)|Read from a file| -|[_fread_nolock](../c-runtime-library/reference/fread-nolock.md)|[_fread_nolock_s](../c-runtime-library/reference/fread-nolock-s2.md)|Read from a file without using a multi-thread write lock| -|[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)|[freopen_s, _wfreopen_s](../c-runtime-library/reference/freopen-s-wfreopen-s.md)|Reopen the file| -|[fscanf, _fscanf_l, fwscanf, _fwscanf_l](../c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md)|[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](../c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)|Read formatted data from a stream| -|[_ftime, _ftime32, _ftime64](../c-runtime-library/reference/ftime-ftime32-ftime64.md)|[_ftime_s, _ftime32_s, _ftime64_s](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md)|Get the current time| -|[_gcvt](../c-runtime-library/reference/gcvt.md)|[_gcvt_s](../c-runtime-library/reference/gcvt-s.md)|Convert a floating-point value to a string, and store it in a buffer| -|[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md)|[getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)|Get a value from the current environment.| -|[gets, getws](../c-runtime-library/gets-getws.md)|[gets_s, _getws_s](../c-runtime-library/reference/gets-s-getws-s.md)|Get a line from the `stdin` stream| -|[gmtime, _gmtime32, _gmtime64](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)|[_gmtime32_s, _gmtime64_s](../c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md)|Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm`| -|[itoa, _itoa, ltoa, _ltoa, ultoa, _ultoa, _i64toa, _ui64toa, _itow, _ltow, _ultow, _i64tow, _ui64tow](../c-runtime-library/reference/itoa-itow.md)|[_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s, _itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s](../c-runtime-library/reference/itoa-s-itow-s.md)|Convert an integral type to a string| -|[_lfind](../c-runtime-library/reference/lfind.md)|[_lfind_s](../c-runtime-library/reference/lfind-s.md)|Perform a linear search for the specified key| -|[localtime, _localtime32, _localtime64](../c-runtime-library/reference/localtime-localtime32-localtime64.md)|[localtime_s, _localtime32_s, _localtime64_s](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md)|Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` with local correction| -|[_lsearch](../c-runtime-library/reference/lsearch.md)|[_lsearch_s](../c-runtime-library/reference/lsearch-s.md)|Perform a linear search for a value; adds to end of list if not found| -|[_makepath, _wmakepath](../c-runtime-library/reference/makepath-wmakepath.md)|[_makepath_s, _wmakepath_s](../c-runtime-library/reference/makepath-s-wmakepath-s.md)|Create a path name from components| -|[_mbccpy, _mbccpy_l](../c-runtime-library/reference/mbccpy-mbccpy-l.md)|[_mbccpy_s, _mbccpy_s_l](../c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md)|Copy a multibyte character from one string to another string| -|[_mbsnbcat, _mbsnbcat_l](../c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md)|[_mbsnbcat_s, _mbsnbcat_s_l](../c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md)|Append, at most, the first *n* bytes of one multibyte character string to another| -|[_mbsnbcpy, _mbsnbcpy_l](../c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md)|[_mbsnbcpy_s, _mbsnbcpy_s_l](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md)|Copy *n* bytes of a string to a destination string| -|[_mbsnbset, _mbsnbset_l](../c-runtime-library/reference/mbsnbset-mbsnbset-l.md)|[_mbsnbset_s, _mbsnbset_s_l](../c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md)|Set the first *n* bytes of a string to a specified character| -|[mbsrtowcs](../c-runtime-library/reference/mbsrtowcs.md)|[mbsrtowcs_s](../c-runtime-library/reference/mbsrtowcs-s.md)|Convert a multibyte character string to a corresponding wide character string| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md)|[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert a sequence of multibyte characters to a corresponding sequence of wide characters| -|[memcpy, wmemcpy](../c-runtime-library/reference/memcpy-wmemcpy.md)|[memcpy_s, wmemcpy_s](../c-runtime-library/reference/memcpy-s-wmemcpy-s.md)|Copy characters between buffers| -|[memmove, wmemmove](../c-runtime-library/reference/memmove-wmemmove.md)|[memmove_s, wmemmove_s](../c-runtime-library/reference/memmove-s-wmemmove-s.md)|Move one buffer to another| -|[_mktemp, _wmktemp](../c-runtime-library/reference/mktemp-wmktemp.md)|[_mktemp_s, _wmktemp_s](../c-runtime-library/reference/mktemp-s-wmktemp-s.md)|Create a unique filename| -|[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)|Print formatted output to the standard output stream| -|[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md)|[_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md)|Create, modify, or remove environment variables| -|[qsort](../c-runtime-library/reference/qsort.md)|[qsort_s](../c-runtime-library/reference/qsort-s.md)|Perform a quick sort| -|[rand](../c-runtime-library/reference/rand.md)|[rand_s](../c-runtime-library/reference/rand-s.md)|Generate a pseudorandom number| -|[scanf, _scanf_l, wscanf, _wscanf_l](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)|[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)|Read formatted data from the standard input stream| -|[_searchenv, _wsearchenv](../c-runtime-library/reference/searchenv-wsearchenv.md)|[_searchenv_s, _wsearchenv_s](../c-runtime-library/reference/searchenv-s-wsearchenv-s.md)|Search for a file using environment paths| -|[snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)|[_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md)|Write formatted data to a string| -|[_snscanf, _snscanf_l, _snwscanf, _snwscanf_l](../c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md)|[_snscanf_s, _snscanf_s_l, _snwscanf_s, _snwscanf_s_l](../c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md)|Read formatted data of a specified length from a string.| -|[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)|[_sopen_s, _wsopen_s](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open a file for sharing| -|[_splitpath, _wsplitpath](../c-runtime-library/reference/splitpath-wsplitpath.md)|[_splitpath_s, _wsplitpath_s](../c-runtime-library/reference/splitpath-s-wsplitpath-s.md)|Break a path name into components| -|[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)|Write formatted data to a string| -|[sscanf, _sscanf_l, swscanf, _swscanf_l](../c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md)|[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](../c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)|Read formatted data from a string| -|[strcat, wcscat, _mbscat](../c-runtime-library/reference/strcat-wcscat-mbscat.md)|[strcat_s, wcscat_s, _mbscat_s](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)|Append a string| -|[strcpy, wcscpy, _mbscpy](../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md)|[strcpy_s, wcscpy_s, _mbscpy_s](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)|Copy a string| -|[_strdate, _wstrdate](../c-runtime-library/reference/strdate-wstrdate.md)|[_strdate_s, _wstrdate_s](../c-runtime-library/reference/strdate-s-wstrdate-s.md)|Return current system date as string| -|[strerror, _strerror, _wcserror, \__wcserror](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)|[strerror_s, _strerror_s, _wcserror_s, \__wcserror_s](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)|Get a system error message (`strerror`, `_wcserror`) or print a user-supplied error message (`_strerror`, `__wcserror`)| -|[_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](../c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md)|[_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](../c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert a string to lowercase| -|[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](../c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)|[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)|Append characters to a string| -|[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](../c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)|[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)|Copy characters of one string to another| -|[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](../c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)|[_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l](../c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md)|Set the first n characters of a string to the specified character| -|[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)|[_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](../c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md)|Set all the characters of a string to the specified character| -|[_strtime, _wstrtime](../c-runtime-library/reference/strtime-wstrtime.md)|[_strtime_s, _wstrtime_s](../c-runtime-library/reference/strtime-s-wstrtime-s.md)|Return current system time as string| -|[strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l](../c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md)|[strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l](../c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md)|Find the next token in a string, using the current locale or a locale passed in| -|[_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](../c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md)|[_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](../c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert a string to uppercase| -|[tmpfile](../c-runtime-library/reference/tmpfile.md)|[tmpfile_s](../c-runtime-library/reference/tmpfile-s.md)|Create a temporary file| -|[_tempnam, _wtempnam, tmpnam, _wtmpnam](../c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md)|[tmpnam_s, _wtmpnam_s](../c-runtime-library/reference/tmpnam-s-wtmpnam-s.md)|Generate names you can use to create temporary files| -|[_umask](../c-runtime-library/reference/umask.md)|[_umask_s](../c-runtime-library/reference/umask-s.md)|Set the default file-permission mask| -|[_vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l](../c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md)|[_vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l](../c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md)|Write formatted output to the console using a pointer to a list of arguments| -|[vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)|[vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](../c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vfscanf, vfwscanf](../c-runtime-library/reference/vfscanf-vfwscanf.md)|[vfscanf_s, vfwscanf_s](../c-runtime-library/reference/vfscanf-s-vfwscanf-s.md)|Read formatted data from a stream| -|[vprintf, _vprintf_l, vwprintf, _vwprintf_l](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)|[vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l](../c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vscanf, vwscanf](../c-runtime-library/reference/vscanf-vwscanf.md)|[vscanf_s, vwscanf_s](../c-runtime-library/reference/vscanf-s-vwscanf-s.md)|Read formatted data from the standard input stream| -|[vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md)|[vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, \__vswprintf_l](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)|[vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vsscanf, vswscanf](../c-runtime-library/reference/vsscanf-vswscanf.md)|[vsscanf_s, vswscanf_s](../c-runtime-library/reference/vsscanf-s-vswscanf-s.md)|Read formatted data from a string| -|[wcrtomb](../c-runtime-library/reference/wcrtomb.md)|[wcrtomb_s](../c-runtime-library/reference/wcrtomb-s.md)|Convert a wide character into its multibyte character representation| -|[wcsrtombs](../c-runtime-library/reference/wcsrtombs.md)|[wcsrtombs_s](../c-runtime-library/reference/wcsrtombs-s.md)|Convert a wide character string to its multibyte character string representation| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md)|[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert a sequence of wide characters to a corresponding sequence of multibyte characters| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md)|[wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert a wide character to the corresponding multibyte character| +| CRT Function | Security enhanced function | Use | +|---|---|---| +| [`_access`, `_waccess`](./reference/access-waccess.md) | [`_access_s`, `_waccess_s`](./reference/access-s-waccess-s.md) | Determine file-access permission | +| [`_alloca`](./reference/alloca.md) | [`_malloca`](./reference/malloca.md) | Allocate memory on the stack | +| [`asctime`, `_wasctime`](./reference/asctime-wasctime.md) | [`asctime_s`, `_wasctime_s`](./reference/asctime-s-wasctime-s.md) | Convert time from type `struct tm` to character string | +| [`bsearch`](./reference/bsearch.md) | [`bsearch_s`](./reference/bsearch-s.md) | Perform a binary search of a sorted array | +| [`_cgets`, `_cgetws`](./cgets-cgetws.md) | [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | Get a character string from the console | +| [`_chsize`](./reference/chsize.md) | [`_chsize_s`](./reference/chsize-s.md) | Change the size of a file | +| [`clearerr`](./reference/clearerr.md) | [`clearerr_s`](./reference/clearerr-s.md) | Reset the error indicator for a stream | +| [`_control87`, `_controlfp`, `__control87_2`](./reference/control87-controlfp-control87-2.md) | [`_controlfp_s`](./reference/controlfp-s.md) | Get and set the floating-point control word | +| [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](./reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) | Format and print to the console | +| [`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](./reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md) | [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](./reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md) | Read formatted data from the console | +| [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) | [`_ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](./reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md) | Convert time from type `time_t`, `__time32_t` or `__time64_t` to character string | +| [`_ecvt`](./reference/ecvt.md) | [`_ecvt_s`](./reference/ecvt-s.md) | Convert a **`double`** number to a string | +| [`_fcvt`](./reference/fcvt.md) | [`_fcvt_s`](./reference/fcvt-s.md) | Converts a floating-point number to a string | +| [`fopen`, `_wfopen`](./reference/fopen-wfopen.md) | [`fopen_s`, `_wfopen_s`](./reference/fopen-s-wfopen-s.md) | Open a file | +| [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](./reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) | Print formatted data to a stream | +| [`fread`](./reference/fread.md) | [`fread_s`](./reference/fread-s.md) | Read from a file | +| [`_fread_nolock`](./reference/fread-nolock.md) | [`_fread_nolock_s`](./reference/fread-nolock-s2.md) | Read from a file without using a multi-thread write lock | +| [`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md) | [`freopen_s`, `_wfreopen_s`](./reference/freopen-s-wfreopen-s.md) | Reopen the file | +| [`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](./reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md) | [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](./reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) | Read formatted data from a stream | +| [`_ftime`, `_ftime32`, `_ftime64`](./reference/ftime-ftime32-ftime64.md) | [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](./reference/ftime-s-ftime32-s-ftime64-s.md) | Get the current time | +| [`_gcvt`](./reference/gcvt.md) | [`_gcvt_s`](./reference/gcvt-s.md) | Convert a floating-point value to a string, and store it in a buffer | +| [`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md) | [`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md) | Get a value from the current environment. | +| [`gets`, `getws`](./gets-getws.md) | [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md) | Get a line from the `stdin` stream | +| [`gmtime`, `_gmtime32`, `_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md) | [`_gmtime32_s`, `_gmtime64_s`](./reference/gmtime-s-gmtime32-s-gmtime64-s.md) | Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` | +| [`itoa`, `_itoa`, `ltoa`, `_ltoa`, `ultoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `_ultow`, `_i64tow`, `_ui64tow`](./reference/itoa-itow.md) | [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](./reference/itoa-s-itow-s.md) | Convert an integral type to a string | +| [`_lfind`](./reference/lfind.md) | [`_lfind_s`](./reference/lfind-s.md) | Perform a linear search for the specified key | +| [`localtime`, `_localtime32`, `_localtime64`](./reference/localtime-localtime32-localtime64.md) | [`localtime_s`, `_localtime32_s`, `_localtime64_s`](./reference/localtime-s-localtime32-s-localtime64-s.md) | Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` with local correction | +| [`_lsearch`](./reference/lsearch.md) | [`_lsearch_s`](./reference/lsearch-s.md) | Perform a linear search for a value; adds to end of list if not found | +| [`_makepath`, `_wmakepath`](./reference/makepath-wmakepath.md) | [`_makepath_s`, `_wmakepath_s`](./reference/makepath-s-wmakepath-s.md) | Create a path name from components | +| [`_mbccpy`, `_mbccpy_l`](./reference/mbccpy-mbccpy-l.md) | [`_mbccpy_s`, `_mbccpy_s_l`](./reference/mbccpy-s-mbccpy-s-l.md) | Copy a multibyte character from one string to another string | +| [`_mbsnbcat`, `_mbsnbcat_l`](./reference/mbsnbcat-mbsnbcat-l.md) | [`_mbsnbcat_s`, `_mbsnbcat_s_l`](./reference/mbsnbcat-s-mbsnbcat-s-l.md) | Append at most the first *n* bytes of one multibyte character string to another | +| [`_mbsnbcpy`, `_mbsnbcpy_l`](./reference/mbsnbcpy-mbsnbcpy-l.md) | [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](./reference/mbsnbcpy-s-mbsnbcpy-s-l.md) | Copy *n* bytes of a string to a destination string | +| [`_mbsnbset`, `_mbsnbset_l`](./reference/mbsnbset-mbsnbset-l.md) | [`_mbsnbset_s`, `_mbsnbset_s_l`](./reference/mbsnbset-s-mbsnbset-s-l.md) | Set the first *n* bytes of a string to a specified character | +| [`mbsrtowcs`](./reference/mbsrtowcs.md) | [`mbsrtowcs_s`](./reference/mbsrtowcs-s.md) | Convert a multibyte character string to a corresponding wide character string | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md) | [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert a sequence of multibyte characters to a corresponding sequence of wide characters | +| [`memcpy`, `wmemcpy`](./reference/memcpy-wmemcpy.md) | [`memcpy_s`, `wmemcpy_s`](./reference/memcpy-s-wmemcpy-s.md) | Copy characters between buffers | +| [`memmove`, `wmemmove`](./reference/memmove-wmemmove.md) | [`memmove_s`, `wmemmove_s`](./reference/memmove-s-wmemmove-s.md) | Move one buffer to another | +| [`_mktemp`, `_wmktemp`](./reference/mktemp-wmktemp.md) | [`_mktemp_s`, `_wmktemp_s`](./reference/mktemp-s-wmktemp-s.md) | Create a unique filename | +| [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md) | [`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) | Print formatted output to the standard output stream | +| [`_putenv`, `_wputenv`](./reference/putenv-wputenv.md) | [`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md) | Create, modify, or remove environment variables | +| [`qsort`](./reference/qsort.md) | [`qsort_s`](./reference/qsort-s.md) | Perform a quick sort | +| [`rand`](./reference/rand.md) | [`rand_s`](./reference/rand-s.md) | Generate a pseudorandom number | +| [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md) | [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) | Read formatted data from the standard input stream | +| [`_searchenv`, `_wsearchenv`](./reference/searchenv-wsearchenv.md) | [`_searchenv_s`, `_wsearchenv_s`](./reference/searchenv-s-wsearchenv-s.md) | Search for a file using environment paths | +| [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](./reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) | [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](./reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) | Write formatted data to a string | +| [`_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l`](./reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md) | [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](./reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md) | Read formatted data of a specified length from a string. | +| [`_sopen`, `_wsopen`](./reference/sopen-wsopen.md) | [`_sopen_s`, `_wsopen_s`](./reference/sopen-s-wsopen-s.md) | Open a file for sharing | +| [`_splitpath`, `_wsplitpath`](./reference/splitpath-wsplitpath.md) | [`_splitpath_s`, `_wsplitpath_s`](./reference/splitpath-s-wsplitpath-s.md) | Break a path name into components | +| [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](./reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) | Write formatted data to a string | +| [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](./reference/sscanf-sscanf-l-swscanf-swscanf-l.md) | [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](./reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) | Read formatted data from a string | +| [`strcat`, `wcscat`, `_mbscat`](./reference/strcat-wcscat-mbscat.md) | [`strcat_s`, `wcscat_s`, `_mbscat_s`](./reference/strcat-s-wcscat-s-mbscat-s.md) | Append a string | +| [`strcpy`, `wcscpy`, `_mbscpy`](./reference/strcpy-wcscpy-mbscpy.md) | [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](./reference/strcpy-s-wcscpy-s-mbscpy-s.md) | Copy a string | +| [`_strdate`, `_wstrdate`](./reference/strdate-wstrdate.md) | [`_strdate_s`, `_wstrdate_s`](./reference/strdate-s-wstrdate-s.md) | Return current system date as string | +| [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](./reference/strerror-strerror-wcserror-wcserror.md) | [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) | Get a system error message (`strerror`, `_wcserror`) or print a user-supplied error message (`_strerror`, `__wcserror`) | +| [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](./reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) | [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](./reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) | Convert a string to lowercase | +| [`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](./reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) | [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](./reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) | Append characters to a string | +| [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](./reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) | [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](./reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) | Copy characters of one string to another | +| [`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](./reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) | [`_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`](./reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) | Set the first n characters of a string to the specified character | +| [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](./reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) | [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](./reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) | Set all the characters of a string to the specified character | +| [`_strtime`, `_wstrtime`](./reference/strtime-wstrtime.md) | [`_strtime_s`, `_wstrtime_s`](./reference/strtime-s-wstrtime-s.md) | Return current system time as string | +| [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](./reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) | [`strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l`](./reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md) | Find the next token in a string, using the current locale or a locale passed in | +| [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](./reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) | [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](./reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) | Convert a string to uppercase | +| [`tmpfile`](./reference/tmpfile.md) | [`tmpfile_s`](./reference/tmpfile-s.md) | Create a temporary file | +| [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](./reference/tempnam-wtempnam-tmpnam-wtmpnam.md) | [`tmpnam_s`, `_wtmpnam_s`](./reference/tmpnam-s-wtmpnam-s.md) | Generate names you can use to create temporary files | +| [`_umask`](./reference/umask.md) | [`_umask_s`](./reference/umask-s.md) | Set the default file-permission mask | +| [`_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l`](./reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) | [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](./reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md) | Write formatted output to the console using a pointer to a list of arguments | +| [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) | [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](./reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vfscanf`, `vfwscanf`](./reference/vfscanf-vfwscanf.md) | [`vfscanf_s`, `vfwscanf_s`](./reference/vfscanf-s-vfwscanf-s.md) | Read formatted data from a stream | +| [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) | [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](./reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vscanf`, `vwscanf`](./reference/vscanf-vwscanf.md) | [`vscanf_s`, `vwscanf_s`](./reference/vscanf-s-vwscanf-s.md) | Read formatted data from the standard input stream | +| [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](./reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) | [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](./reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) | [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](./reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vsscanf`, `vswscanf`](./reference/vsscanf-vswscanf.md) | [`vsscanf_s`, `vswscanf_s`](./reference/vsscanf-s-vswscanf-s.md) | Read formatted data from a string | +| [`wcrtomb`](./reference/wcrtomb.md) | [`wcrtomb_s`](./reference/wcrtomb-s.md) | Convert a wide character into its multibyte character representation | +| [`wcsrtombs`](./reference/wcsrtombs.md) | [`wcsrtombs_s`](./reference/wcsrtombs-s.md) | Convert a wide character string to its multibyte character string representation | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md) | [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert a sequence of wide characters to a corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md) | [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert a wide character to the corresponding multibyte character | ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/security-features-in-the-crt.md b/docs/c-runtime-library/security-features-in-the-crt.md index d84f1b777d..06117a37fd 100644 --- a/docs/c-runtime-library/security-features-in-the-crt.md +++ b/docs/c-runtime-library/security-features-in-the-crt.md @@ -3,65 +3,80 @@ title: "Security Features in the CRT" description: "An overview of secure CRT functions in the Microsoft C runtime." ms.date: "09/29/2020" ms.topic: "conceptual" -f1_keywords: ["_CRT_SECURE_NO_DEPRECATE", "_CRT_NONSTDC_NO_WARNINGS", "_CRT_SECURE_NO_WARNINGS"] +f1_keywords: ["_CRT_SECURE_NO_DEPRECATE", "_CRT_NONSTDC_NO_DEPRECATE", "_CRT_NONSTDC_NO_WARNINGS", "_CRT_SECURE_NO_WARNINGS"] helpviewer_keywords: ["security deprecation warnings [C++]", "CRT_NONSTDC_NO_DEPRECATE", "buffers [C++], buffer overruns", "deprecation warnings (security-related), disabling", "_CRT_NONSTDC_NO_WARNINGS", "security [CRT]", "_CRT_SECURE_NO_WARNINGS", "_CRT_NONSTDC_NO_DEPRECATE", "_CRT_SECURE_NO_DEPRECATE", "security-enhanced CRT", "CRT_SECURE_NO_WARNINGS", "CRT_SECURE_NO_DEPRECATE", "deprecation warnings (security-related)", "buffer overruns", "CRT_NONSTDC_NO_WARNINGS", "CRT, security enhancements", "parameters [C++], validation"] -ms.assetid: d9568b08-9514-49cd-b3dc-2454ded195a3 --- # Security Features in the CRT -Many old CRT functions have newer, more secure versions. If a secure function exists, the older, less secure version is marked as deprecated and the new version has the `_s` ("secure") suffix. +Many old CRT functions have newer, more secure versions. If a secure function exists, the older, less secure version is marked as deprecated. The new version has the `_s` ("secure") suffix. -In this context, "deprecated" means using the function's isn't recommended. It doesn't mean the function is scheduled to be removed from the CRT. +In this context, "deprecated" means that use of the function isn't recommended. It doesn't mean the function will be removed from the CRT. -The secure functions don't prevent or correct security errors. Instead, they catch errors when they occur. They do additional checks for error conditions. If there is an error, they invoke an error handler (see [Parameter Validation](../c-runtime-library/parameter-validation.md)). +The secure functions don't prevent or correct security errors. Instead, they catch errors when they occur. They do extra checks for error conditions. If there's an error, they invoke an error handler (see [Parameter validation](./parameter-validation.md)). -For example, the `strcpy` function can't tell if the string it's copying is too large for the destination buffer. Its secure counterpart, `strcpy_s`, takes the size of the buffer as a parameter. So it can determine if a buffer overrun will occur. If you use `strcpy_s` to copy 11 characters into a 10 character buffer, that is an error on your part; `strcpy_s` can't correct your mistake. But it can detect your error and inform you by invoking the invalid parameter handler. +For example, the `strcpy` function can't tell if the string it copies is too large for the destination buffer. Its secure counterpart, `strcpy_s`, takes the size of the buffer as a parameter. So, it can determine if a buffer overrun will occur. If you use `strcpy_s` to copy 11 characters into a 10 character buffer, that's an error on your part; `strcpy_s` can't correct your mistake. But it can detect your error and inform you by invoking the invalid parameter handler. ## Eliminating deprecation warnings -There are several ways to eliminate deprecation warnings for the older, less secure functions. The simplest is simply to define `_CRT_SECURE_NO_WARNINGS` or use the [warning](../preprocessor/warning.md) pragma. Either will disable deprecation warnings, but the security issues that caused the warnings still exist. It's better to leave deprecation warnings enabled and take advantage of the new CRT security features. +There are several ways to eliminate deprecation warnings for the older, less secure functions. The simplest is simply to define `_CRT_SECURE_NO_WARNINGS` or use the [`warning`](../preprocessor/warning.md) pragma. Either disables deprecation warnings, but the security issues that caused the warnings still exist. It's better to leave deprecation warnings enabled and take advantage of the new CRT security features. -In C++, the easiest way to do that is to use [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). This will eliminate deprecation warnings, in many cases, by replacing calls to deprecated functions with calls to secure versions of those functions. For example, consider this deprecated call to `strcpy`: +In C++, the easiest way to eliminate the deprecation warnings is to use [Secure template overloads](./secure-template-overloads.md). The overloads eliminate deprecation warnings in many cases. They replace calls to deprecated functions with calls to secure versions of the functions. For example, consider this deprecated call to `strcpy`: -``` +```cpp char szBuf[10]; strcpy(szBuf, "test"); // warning: deprecated ``` -Defining `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 eliminates the warning by changing the `strcpy` call to `strcpy_s`, which prevents buffer overruns. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). +Defining `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 eliminates the warning by changing the `strcpy` call to `strcpy_s`, which prevents buffer overruns. For more information, see [Secure template overloads](./secure-template-overloads.md). For those deprecated functions without secure template overloads, you should definitely consider manually updating your code to use the secure versions. -Another source of deprecation warnings, unrelated to security, is the POSIX functions. Replace POSIX function names with their standard equivalents (for example, change [access](../c-runtime-library/reference/access-crt.md) to [_access](../c-runtime-library/reference/access-waccess.md)), or disable POSIX-related deprecation warnings by defining `_CRT_NONSTDC_NO_WARNINGS`. For more information, see [Compatibility](compatibility.md). +Another source of deprecation warnings, unrelated to security, is the POSIX functions. Replace POSIX function names with their standard equivalents (for example, change [`access`](./reference/access-crt.md) to [`_access`](./reference/access-waccess.md)), or disable POSIX-related deprecation warnings by defining `_CRT_NONSTDC_NO_WARNINGS`. For more information, see [Compatibility](compatibility.md). -## Additional Security Features +## More security features Some of the security features include: -- `Parameter Validation`. Secure functions, and many of their unsecure counterparts, validate parameters. Validation may include: +- **Parameter Validation** + + Secure functions, and many of their unsecure counterparts, validate parameters. Validation may include: - - Checking for **NULL** values. + - Checking for `NULL` values. - Checking enumerated values for validity. - Checking that integral values are in valid ranges. -- For more information, see [Parameter Validation](../c-runtime-library/parameter-validation.md). + For more information, see [Parameter validation](./parameter-validation.md). + + A handler for invalid parameters is also accessible to the developer. When a function encounters an invalid parameter, instead of asserting and exiting the application, the CRT allows you to check these problems via [`_set_invalid_parameter_handler` or `_set_thread_local_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). + +- **Sized Buffers** + + You must pass the buffer size to any secure function that writes to a buffer. The secure versions validate that the buffer is large enough before writing to it. The validation helps avoid dangerous buffer overrun errors that could allow malicious code to execute. These functions usually return an `errno` error code and invoke the invalid parameter handler if the size of the buffer is too small. Functions that read from input buffers, such as `gets`, have secure versions that require you to specify a maximum size. + + The debug versions of *some* security-enhanced CRT functions fill the buffer passed to them with a special character (0xFE). This fill character helps to find cases where the incorrect size was passed to the function. Unfortunately, it also reduces performance. To improve performance, use **`_CrtSetDebugFillThreshold`** to disable buffer-filling. For more information, and a list of functions that have this behavior, see [`_CrtSetDebugFillThreshold`](./reference/crtsetdebugfillthreshold.md). + +- **Null termination** + + Some functions that left potentially nonterminated strings have secure versions, which ensure that strings are properly null-terminated. + +- **Enhanced error reporting** -- A handler for invalid parameters is also accessible to the developer. When a function encounters an invalid parameter, instead of asserting and exiting the application, the CRT allows you to check these problems via [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). + The secure functions return error codes with more error information than was available with the preexisting functions. The secure functions and many of the preexisting functions now set `errno` and often return an `errno` code type as well, to provide better error reporting. -- `Sized Buffers`. You must pass the buffer size to any secure function that writes to a buffer. The secure versions validate that the buffer is large enough before writing to it. Which helps avoid dangerous buffer overrun errors that could allow malicious code to execute. These functions usually return an `errno` error code and invoke the invalid parameter handler if the size of the buffer is too small. Functions that read from input buffers, such as `gets`, have secure versions that require you to specify a maximum size. +- **Filesystem security** -- `Null termination`. Some functions that left potentially non-terminated strings have secure versions, which ensure that strings are properly null-terminated. + Secure file I/O APIs support secure file access in the default case. -- `Enhanced error reporting`. The secure functions return error codes with more error information than was available with the pre-existing functions. The secure functions and many of the pre-existing functions now set `errno` and often return an `errno` code type as well, to provide better error reporting. +- **Windows security** -- `Filesystem security`. Secure file I/O APIs support secure file access in the default case. + Secure process APIs enforce security policies and allow ACLs to be specified. -- `Windows security`. Secure process APIs enforce security policies and allow ACLs to be specified. +- **Format string syntax checking** -- `Format string syntax checking`. Invalid strings are detected, for example, using incorrect type field characters in `printf` format strings. + Invalid strings are detected, for example, when you use incorrect type field characters in `printf` format strings. ## See also -[Parameter Validation](../c-runtime-library/parameter-validation.md)
-[Secure Template Overloads](../c-runtime-library/secure-template-overloads.md)
-[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Parameter validation](./parameter-validation.md)\ +[Secure template overloads](./secure-template-overloads.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/set-app-type.md b/docs/c-runtime-library/set-app-type.md index dec1f9fef1..6b7666c279 100644 --- a/docs/c-runtime-library/set-app-type.md +++ b/docs/c-runtime-library/set-app-type.md @@ -3,13 +3,13 @@ description: "Learn more about: _set_app_type" title: "_set_app_type" ms.date: "4/2/2020" api_name: ["_set_app_type", "_o__set_app_type"] -api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_set_app_type", "corecrt_startup/_set_app_type"] +f1_keywords: ["_set_app_type", "corecrt_startup/_set_app_type", "corecrt_startup/_crt_app_type", "corecrt_startup/_crt_unknown_app", "corecrt_startup/_crt_console_app", "corecrt_startup/_crt_gui_app"] ms.assetid: 1e7fe786-b587-4116-8c05-f7d762350100 --- -# _set_app_type +# `_set_app_type` An internal function used at startup to tell the CRT whether the app is a console app or a GUI app. @@ -30,23 +30,23 @@ void __cdecl _set_app_type( ## Parameters -*appType*
+*`appType`*\ A value that indicates the application type. The possible values are: -|Value|Description| -|----------------|-----------------| -|_crt_unknown_app|Unknown application type.| -|_crt_console_app|Console (command-line) application.| -|_crt_gui_app|GUI (Windows) application.| +| Value | Description | +|---|---| +| `_crt_unknown_app` | Unknown application type. | +| `_crt_console_app` | Console (command-line) application. | +| `_crt_gui_app` | GUI (Windows) application. | ## Remarks -Normally, you do not need to call this function. It is part of the C runtime startup code that executes before `main` is called in your app. +Normally, you don't need to call this function. It's part of the C runtime startup code that executes before `main` is called in your app. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_set_app_type|process.h| +| Routine | Required header | +|---|---| +| **`_set_app_type`** | `` | diff --git a/docs/c-runtime-library/set-output-format.md b/docs/c-runtime-library/set-output-format.md index 15fabff324..551c5d90e0 100644 --- a/docs/c-runtime-library/set-output-format.md +++ b/docs/c-runtime-library/set-output-format.md @@ -10,7 +10,7 @@ f1_keywords: ["set_output_format", "_set_output_format"] helpviewer_keywords: ["_TWO_DIGIT_EXPONENT constant", "output formatting", "TWO_DIGIT_EXPONENT constant", "_set_output_format function", "set_output_format function"] ms.assetid: 1cb48df8-44b4-4400-bd27-287831d6b3ff --- -# _set_output_format +# `_set_output_format` Customizes output formats used by formatted I/O functions. @@ -19,7 +19,7 @@ Customizes output formats used by formatted I/O functions. ## Syntax -``` +```C unsigned int _set_output_format( unsigned int format ); @@ -27,7 +27,7 @@ unsigned int _set_output_format( #### Parameters -*format*
+*`format`*\ [in] An value representing the format to use. ## Return value @@ -36,19 +36,19 @@ The previous output format. ## Remarks -`_set_output_format` is used to configure the output of formatted I/O functions such as [printf_s](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md). At present, the only formatting convention that can be changed by this function is the number of digits displayed in exponents in the output of floating point numbers. +**`_set_output_format`** is used to configure the output of formatted I/O functions such as [`printf_s`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md). The only formatting convention that can be changed by this function is the number of digits displayed in exponents in the output of floating point numbers. -By default, the output of floating point numbers by functions such as `printf_s`, `wprintf_s`, and related functions in the Visual C++ Standard C library prints three digits for the exponent, even if three digits are not required to represent the value of the exponent. Zeroes are used to pad the value to three digits. `_set_output_format` allows you to change this behavior so that only two digits are printed in the exponent unless a third digit is required by the size of the exponent. +By default, the output of floating point numbers by functions such as `printf_s`, `wprintf_s`, and related functions in the Visual C++ Standard C library prints three digits for the exponent, even if three digits aren't required to represent the value of the exponent. Zeroes are used to pad the value to three digits. **`_set_output_format`** allows you to change this behavior so that only two digits are printed in the exponent unless a third digit is required by the size of the exponent. To enable two-digit exponents, call this function with the parameter `_TWO_DIGIT_EXPONENT`, as shown in the example. To disable two digit exponents, call this function with an argument of 0. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_set_output_format`|\| +| Routine | Required header | +|---|---| +| **`_set_output_format`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## Example @@ -102,5 +102,5 @@ int main() ## See also -[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)
-[_get_output_format](../c-runtime-library/get-output-format.md) +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`_get_output_format`](./get-output-format.md) diff --git a/docs/c-runtime-library/setjmp3.md b/docs/c-runtime-library/setjmp3.md index 18242e77c0..05fbacbc02 100644 --- a/docs/c-runtime-library/setjmp3.md +++ b/docs/c-runtime-library/setjmp3.md @@ -3,7 +3,7 @@ description: "Learn more about: _setjmp3" title: "_setjmp3" ms.date: "1/14/2021" api_name: ["_setjmp3"] -api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr110.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr110.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setjmp3", "_setjmp3"] @@ -16,7 +16,7 @@ Internal CRT function. A new implementation of the `setjmp` function. ## Syntax -``` +```C int _setjmp3( OUT jmp_buf env, int count, @@ -30,12 +30,12 @@ int _setjmp3( [out] Address of the buffer for storing state information. *`count`*\ -[in] The number of additional `DWORD`s of information that are stored in the `optional parameters`. +[in] The number of `DWORD`s of information stored in the `optional parameters`. *`optional parameters`*\ -[in] Additional data pushed down by the `setjmp` intrinsic. The first `DWORD` is a function pointer that is used to unwind extra data and return to a nonvolatile register state. The second `DWORD` is the try level to be restored. Any further data is saved in the generic data array in the `jmp_buf`. +[in] Extra data pushed down by the `setjmp` intrinsic. The first `DWORD` is a function pointer that is used to unwind extra data and return to a nonvolatile register state. The second `DWORD` is the try level to be restored. Any further data is saved in the generic data array in the `jmp_buf`. -## Return Value +## Return value Always returns 0. @@ -47,5 +47,5 @@ Don't use this function in a C++ program. It's an intrinsic function that doesn' ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)\ -[`setjmp`](../c-runtime-library/reference/setjmp.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`setjmp`](./reference/setjmp.md) diff --git a/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md b/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md index fa329705e8..b725aaed44 100644 --- a/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md +++ b/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md @@ -10,7 +10,7 @@ f1_keywords: ["___unguarded_readlc_active_add_func", "___setlc_active_func"] helpviewer_keywords: ["___setlc_active_func", "___unguarded_readlc_active_add_func"] ms.assetid: 605ec4e3-81e5-4ece-935a-f434768cc702 --- -# ___setlc_active_func, ___unguarded_readlc_active_add_func +# `___setlc_active_func`, `___unguarded_readlc_active_add_func` OBSOLETE. The CRT exports these internal functions only to preserve binary compatibility. @@ -21,20 +21,20 @@ int ___setlc_active_func(void); int * ___unguarded_readlc_active_add_func(void); ``` -## Return Value +## Return value -The value returned is not significant. +The value returned isn't significant. ## Remarks -Although the internal CRT functions `___setlc_active_func` and `___unguarded_readlc_active_add_func` are obsolete and no longer used, they are exported by the CRT library to preserve binary compatibility. The original purpose of `___setlc_active_func` was to return the number of currently active calls to the `setlocale` function. The original purpose of `___unguarded_readlc_active_add_func` was to return the number of functions that referenced the locale without locking it. +Although the internal CRT functions **`___setlc_active_func`** and **`___unguarded_readlc_active_add_func`** are obsolete and no longer used, they're exported by the CRT library to preserve binary compatibility. The original purpose of **`___setlc_active_func`** was to return the number of currently active calls to the `setlocale` function. The original purpose of **`___unguarded_readlc_active_add_func`** was to return the number of functions that referenced the locale without locking it. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___setlc_active_func`, `___unguarded_readlc_active_add_func`|none| +| Routine | Required header | +|---|---| +| **`___setlc_active_func`**, **`___unguarded_readlc_active_add_func`** | none | ## See also -[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/setusermatherr.md b/docs/c-runtime-library/setusermatherr.md index e04c346680..16a9bc0757 100644 --- a/docs/c-runtime-library/setusermatherr.md +++ b/docs/c-runtime-library/setusermatherr.md @@ -10,9 +10,9 @@ f1_keywords: ["__setusermatherr"] helpviewer_keywords: ["__setusermatherr"] ms.assetid: f306818d-381a-4d68-8739-71b92bacb5ea --- -# __setusermatherr +# `__setusermatherr` -Specifies a user-supplied rountine to handle math errors, instead of the [_matherr](../c-runtime-library/reference/matherr.md) routine. +Specifies a user-supplied routine to handle math errors, instead of the [`_matherr`](./reference/matherr.md) routine. ## Syntax @@ -24,15 +24,15 @@ void __setusermatherr( #### Parameters -*pf*
+*`pf`*\ Pointer to an implementation of `_matherr` that is supplied by the user. -The type of the *pf* parameter is declared as `typedef int (__cdecl * _HANDLE_MATH_ERROR)(struct _exception *)`. +The type of the *`pf`* parameter is declared as `typedef int (__cdecl * _HANDLE_MATH_ERROR)(struct _exception *)`. ## Remarks ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__setusermatherr|matherr.c| +| Routine | Required header | +|---|---| +| **`__setusermatherr`** | `matherr.c` | diff --git a/docs/c-runtime-library/setvbuf-constants.md b/docs/c-runtime-library/setvbuf-constants.md index a4a2f00503..06386d05fb 100644 --- a/docs/c-runtime-library/setvbuf-constants.md +++ b/docs/c-runtime-library/setvbuf-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: setvbuf Constants" title: "setvbuf Constants" ms.date: "11/04/2016" -f1_keywords: ["_IOFBF", "_IONBF", "_IOLBF"] +f1_keywords: ["STDIO/_IOFBF", "STDIO/_IONBF", "STDIO/_IOLBF", "_IOFBF", "_IONBF", "_IOLBF"] helpviewer_keywords: ["_IOFBF constant", "IOFBF constant", "IONBF constant", "_IOLBF constant", "IOLBF constant", "_IONBF constant"] ms.assetid: a6ec4dd5-1f24-498c-871a-e874cd28d33c --- -# setvbuf Constants +# `setvbuf` constants ## Syntax -``` +```C #include ``` @@ -20,13 +20,13 @@ These constants represent the type of buffer for `setvbuf`. The possible values are given by the following manifest constants: -|Constant|Meaning| -|--------------|-------------| -|`_IOFBF`|Full buffering: Buffer specified in call to `setvbuf` is used and its size is as specified in `setvbuf` call. If buffer pointer is **NULL**, automatically allocated buffer of specified size is used.| -|`_IOLBF`|Same as `_IOFBF`.| -|`_IONBF`|No buffer is used, regardless of arguments in call to `setvbuf`.| +| Constant | Meaning | +|---|---| +| `_IOFBF` | Full buffering: Buffer specified in call to `setvbuf` is used and its size is as specified in `setvbuf` call. If buffer pointer is `NULL`, automatically allocated buffer of specified size is used. | +| `_IOLBF` | Same as `_IOFBF`. | +| `_IONBF` | No buffer is used, regardless of arguments in call to `setvbuf`. | ## See also -[setbuf](../c-runtime-library/reference/setbuf.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`setbuf`](./reference/setbuf.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/sharing-constants.md b/docs/c-runtime-library/sharing-constants.md index 13eb899f29..11c84f2d81 100644 --- a/docs/c-runtime-library/sharing-constants.md +++ b/docs/c-runtime-library/sharing-constants.md @@ -2,36 +2,36 @@ description: "Learn more about: Sharing Constants" title: "Sharing Constants" ms.date: "11/04/2016" -f1_keywords: ["_SH_DENYNO", "_SH_DENYRD", "_SH_DENYRW", "_SH_DENYWR", "_SH_COMPAT"] -helpviewer_keywords: ["_SH_DENYRW constant", "SH_DENYRD constant", "_SH_COMPAT constant", "_SH_DENYRD constant", "SH_DENYRW constant", "sharing constants", "SH_DENYNO constant", "_SH_DENYWR constant", "SH_DENYWR constant", "_SH_DENYNO constant", "SH_COMPAT constant"] +f1_keywords: ["CORECRT_SHARE/_SH_DENYNO", "CORECRT_SHARE/_SH_DENYRD", "CORECRT_SHARE/_SH_DENYRW", "CORECRT_SHARE/_SH_DENYWR", "CORECRT_SHARE/_SH_SECURE", "_SH_DENYNO", "_SH_DENYRD", "_SH_DENYRW", "_SH_DENYWR", "_SH_SECURE"] +helpviewer_keywords: ["_SH_DENYRW constant", "SH_DENYRD constant", "_SH_SECURE constant", "_SH_DENYRD constant", "SH_DENYRW constant", "sharing constants", "SH_DENYNO constant", "_SH_DENYWR constant", "SH_DENYWR constant", "_SH_DENYNO constant", "SH_SECURE constant"] ms.assetid: 95fadc3a-55dc-473d-98b5-e8211900465d --- -# Sharing Constants +# Sharing constants Constants for file-sharing modes. ## Syntax -``` +```C #include ``` ## Remarks -The *shflag* argument determines the sharing mode, which consists of one or more manifest constants. These can be combined with the *oflag* arguments (see [File Constants](../c-runtime-library/file-constants.md)). +The *`shflag`* argument determines the sharing mode, which consists of one or more manifest constants. These constants can be combined with the *`oflag`* arguments (see [File constants](./file-constants.md)). The following table lists the constants and their meanings: -|Constant|Meaning| -|--------------|-------------| -|`_SH_DENYRW`|Denies read and write access to file| -|`_SH_DENYWR`|Denies write access to file| -|`_SH_DENYRD`|Denies read access to file| -|`_SH_DENYNO`|Permits read and write access| -|`_SH_SECURE`|Sets secure mode (shared read, exclusive write access).| +| Constant | Meaning | +|---|---| +| `_SH_DENYRW` | Denies read and write access to file | +| `_SH_DENYWR` | Denies write access to file | +| `_SH_DENYRD` | Denies read access to file | +| `_SH_DENYNO` | Permits read and write access | +| `_SH_SECURE` | Sets secure mode (shared read, exclusive write access). | ## See also -[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/signal-action-constants.md b/docs/c-runtime-library/signal-action-constants.md index be53b6bb85..17d063de1c 100644 --- a/docs/c-runtime-library/signal-action-constants.md +++ b/docs/c-runtime-library/signal-action-constants.md @@ -2,17 +2,17 @@ description: "Learn more about: signal Action Constants" title: "signal Action Constants" ms.date: "11/04/2016" -f1_keywords: ["SIG_IGN", "SIG_DFL"] +f1_keywords: ["SIGNAL/SIG_IGN", "SIGNAL/SIG_DFL", "SIGNAL/SIG_GET", "SIGNAL/SIG_SGE", "SIGNAL/SIG_ACK", "SIGNAL/SIG_ERR", "SIG_IGN", "SIG_DFL", "SIG_GET", "SIG_SGE", "SIG_ACK", "SIG_ERR"] helpviewer_keywords: ["signal action constants", "SIG_IGN constant", "SIG_DFL constant"] ms.assetid: c3cb4f15-d39e-4d9d-84f9-0d33e3eb5993 --- -# signal Action Constants +# `signal` action constants The action taken when the interrupt signal is received depends on the value of `func`. ## Syntax -``` +```C #include ``` @@ -20,15 +20,16 @@ The action taken when the interrupt signal is received depends on the value of ` The `func` argument must be either a function address or one of the manifest constants listed below and defined in SIGNAL.H. -|Constant|Description| -|-|-| -| `SIG_DFL` | Uses system-default response. If the calling program uses stream I/O, buffers created by the run-time library are not flushed. | -| `SIG_IGN` | Ignores interrupt signal. This value should never be given for `SIGFPE`, since the floating-point state of the process is left undefined. | -| `SIG_SGE` | Indicates an error occurred in the signal. | -| `SIG_ACK` | Indicates an acknowledgement was received. | -| `SIG_ERR` | A return type from a signal indicating an error has occurred. | +| Constant | Description | +|---|---| +| `SIG_DFL` | Uses system-default response. If the calling program uses stream I/O, buffers created by the run-time library aren't flushed. | +| `SIG_IGN` | Ignores interrupt signal. This value should never be given for `SIGFPE`, since the floating-point state of the process is left undefined. | +| `SIG_GET` | Returns the current value of the signal. | +| `SIG_SGE` | Indicates an error occurred in the signal. | +| `SIG_ACK` | Indicates an acknowledgment was received. | +| `SIG_ERR` | A return type from a signal indicating an error has occurred. | ## See also -[signal](../c-runtime-library/reference/signal.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`signal`](./reference/signal.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/signal-constants.md b/docs/c-runtime-library/signal-constants.md index 5982962d58..24d35116ca 100644 --- a/docs/c-runtime-library/signal-constants.md +++ b/docs/c-runtime-library/signal-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: signal Constants" title: "signal Constants" ms.date: "11/04/2016" -f1_keywords: ["SIGTERM", "SIGFPE", "SIGABRT", "SIGILL", "SIGINT", "SIGSEGV"] +f1_keywords: ["SIGNAL/SIGTERM", "SIGNAL/SIGFPE", "SIGNAL/SIGABRT", "SIGNAL/SIGILL", "SIGNAL/SIGINT", "SIGNAL/SIGSEGV", "SIGNAL/SIGABRT_COMPAT", "SIGTERM", "SIGFPE", "SIGABRT", "SIGILL", "SIGINT", "SIGSEGV", "SIGABRT_COMPAT"] helpviewer_keywords: ["SIGTERM constant", "SIGABRT constant", "SIGSEGV constant", "SIGFPE constant", "SIGINT constant", "signal constants", "SIGILL constant"] ms.assetid: a3b39281-dae7-4e44-8d68-e6a610c669dd --- -# signal Constants +# `signal` constants ## Syntax -``` +```C #include ``` @@ -18,19 +18,19 @@ ms.assetid: a3b39281-dae7-4e44-8d68-e6a610c669dd The `sig` argument must be one of the manifest constants listed below (defined in SIGNAL.H). -|Constant|Description| -|-|-| -|SIGABRT|Abnormal termination. The default action terminates the calling program with exit code 3. | -|SIGABRT_COMPAT|Same as SIGABRT. For compatibility with other platforms. | -|SIGFPE|Floating-point error, such as overflow, division by zero, or invalid operation. The default action terminates the calling program. | -|SIGILL|Illegal instruction. The default action terminates the calling program. | -|SIGINT|CTRL+C interrupt. The default action terminates the calling program with exit code 3. | -|SIGSEGV|Illegal storage access. The default action terminates the calling program. | -|SIGTERM|Termination request sent to the program. The default action terminates the calling program with exit code 3. | -|SIG_ERR|A return type from a signal indicating an error has occurred. | +| Constant | Description | +|---|---| +| `SIGABRT` | Abnormal termination. The default action terminates the calling program with exit code 3. | +| `SIGABRT_COMPAT` | Same meaning as `SIGABRT`. For compatibility with other platforms. | +| `SIGFPE` | Floating-point error, such as overflow, division by zero, or invalid operation. The default action terminates the calling program. | +| `SIGILL` | Illegal instruction. The default action terminates the calling program. | +| `SIGINT` | CTRL+C interrupt. The default action terminates the calling program with exit code 3. | +| `SIGSEGV` | Illegal storage access. The default action terminates the calling program. | +| `SIGTERM` | Termination request sent to the program. The default action terminates the calling program with exit code 3. | +| `SIG_ERR` | A return type from a signal indicating an error has occurred. | ## See also -[signal](../c-runtime-library/reference/signal.md)
-[raise](../c-runtime-library/reference/raise.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`signal`](./reference/signal.md)\ +[`raise`](./reference/raise.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md b/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md index 78287e07f8..7828ab3cc9 100644 --- a/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md +++ b/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md @@ -6,16 +6,16 @@ ms.date: "11/04/2016" helpviewer_keywords: ["SBCS (single byte character set)", "MBCS [C++], about MBCS", "character sets [C++], multibyte", "character sets [C++], single byte"] ms.assetid: 2cbc78ea-33c0-4cfb-b0df-7ce2458431ce --- -# Single-Byte and Multibyte Character Sets +# Single-byte and multibyte character sets -The ASCII character set defines characters in the range 0x00 - 0x7F. There are a number of other character sets, primarily European, that define the characters within the range 0x00 - 0x7F identically to the ASCII character set and also define an extended character set from 0x80 - 0xFF. An 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set as well as the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than can be represented in a single-byte coding scheme, and so require multibyte-character set (MBCS) encoding. +The ASCII character set defines characters in the range 0x00 - 0x7F. There are many other character sets, primarily European, that define the characters within the range 0x00 - 0x7F identically to the ASCII character set and also define an extended character set from 0x80 - 0xFF. An 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set and the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than can be represented in a single-byte coding scheme, and so require multibyte-character set (MBCS) encoding. > [!NOTE] -> Many SBCS routines in the Microsoft run-time library handle multibyte bytes, characters, and strings as appropriate. Many multibyte-character sets define the ASCII character set as a subset. In many multibyte character sets, each character in the range 0x00 - 0x7F is identical to the character that has the same value in the ASCII character set. For example, in both ASCII and MBCS character strings, the one-byte null character ('\0') has value 0x00 and indicates the terminating null character. +> Many Microsoft run-time library SBCS routines handle multibyte bytes, characters, and strings as appropriate. Many multibyte-character sets define the ASCII character set as a subset. In many multibyte character sets, each character in the range 0x00 - 0x7F is identical to the character that has the same value in the ASCII character set. For example, in both ASCII and MBCS character strings, the one-byte null character ('\0') has value 0x00 and indicates the terminating null character. -A multibyte character set can consist of both one-byte and two-byte characters. A multibyte-character string can contain a mixture of single-byte and double-byte characters. A two-byte multibyte character has a lead byte and a trail byte. In a particular multibyte-character set, the lead bytes fall within a certain range, as do the trail bytes. When these ranges overlap, you may need to evaluate the context to determine whether a given byte is functioning as a lead byte or a trail byte. +A multibyte character set can consist of both 1-byte and 2-byte characters. A multibyte-character string can contain a mixture of single-byte and double-byte characters. A two-byte multibyte character has a lead byte and a trail byte. In a particular multibyte-character set, the lead bytes fall within a certain range, as do the trail bytes. When these ranges overlap, you may need to evaluate the context to determine whether a given byte is functioning as a lead byte or a trail byte. ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/spawn-constants.md b/docs/c-runtime-library/spawn-constants.md index b0bc3d8242..0be2e3c4d4 100644 --- a/docs/c-runtime-library/spawn-constants.md +++ b/docs/c-runtime-library/spawn-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: spawn Constants" title: "spawn Constants" ms.date: "11/04/2016" -f1_keywords: ["_P_NOWAIT", "_P_OVERLAY", "_P_WAIT", "_P_DETACH", "_P_NOWAITO"] +f1_keywords: ["PROCESS/_P_NOWAIT", "PROCESS/_P_OVERLAY", "PROCESS/_P_WAIT", "PROCESS/_P_DETACH", "PROCESS/_P_NOWAITO", "_P_NOWAIT", "_P_OVERLAY", "_P_WAIT", "_P_DETACH", "_P_NOWAITO"] helpviewer_keywords: ["_P_OVERLAY constant", "P_DETACH constant", "P_OVERLAY constant", "P_NOWAIT constant", "_P_DETACH constant", "_P_NOWAIT constant", "_P_NOWAITO constant", "P_NOWAITO constant", "spawn constants", "P_WAIT constant", "_P_WAIT constant"] ms.assetid: e0533e88-d362-46fc-b53c-5f193226d879 --- -# spawn Constants +# `spawn` constants ## Syntax -``` +```C #include ``` @@ -18,14 +18,14 @@ ms.assetid: e0533e88-d362-46fc-b53c-5f193226d879 The `mode` argument determines the action taken by the calling process before and during a spawn operation. The following values for `mode` are possible: -|Constant|Meaning| -|--------------|-------------| -|`_P_OVERLAY`|Overlays calling process with new process, destroying calling process (same effect as `_exec` calls).| -|`_P_WAIT`|Suspends calling thread until execution of new process is complete (synchronous `_spawn`).| -|`_P_NOWAIT`, `_P_NOWAITO`|Continues to execute calling process concurrently with new process (asynchronous `_spawn`).| -|`_P_DETACH`|Continues to execute calling process; new process is run in background with no access to console or keyboard. Calls to `_cwait` against new process will fail. This is an asynchronous `_spawn`.| +| Constant | Meaning | +|---|---| +| `_P_OVERLAY` | Overlays calling process with new process, destroying calling process (same effect as `_exec` calls). | +| `_P_WAIT` | Suspends calling thread until execution of new process is complete (synchronous `_spawn`). | +| `_P_NOWAIT`, `_P_NOWAITO` | Continues to execute calling process concurrently with new process (asynchronous `_spawn`). | +| `_P_DETACH` | Continues to execute calling process; new process is run in background with no access to console or keyboard. Calls to `_cwait` against new process will fail. This `_spawn` is asynchronous. | ## See also -[_spawn, _wspawn Functions](../c-runtime-library/spawn-wspawn-functions.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_spawn`, `_wspawn` functions](./spawn-wspawn-functions.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/spawn-wspawn-functions.md b/docs/c-runtime-library/spawn-wspawn-functions.md index ab8ed5fe0c..97667c5c00 100644 --- a/docs/c-runtime-library/spawn-wspawn-functions.md +++ b/docs/c-runtime-library/spawn-wspawn-functions.md @@ -2,111 +2,101 @@ description: "Learn more about: _spawn, _wspawn Functions" title: "_spawn, _wspawn Functions" ms.date: "11/04/2016" -api_location: ["msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr90.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] f1_keywords: ["_spawn", "_tspawnlp", "_tspawnlpe", "_tspawnve", "_tspawnvp", "_tspawnvpe", "_tspawnl", "spawn", "_tspawnv", "_tspawnle", "wspawn"] helpviewer_keywords: ["_tspawnve function", "_spawn functions", "_tspawnlpe function", "tspawnvpe function", "processes, creating", "tspawnve function", "_tspawnvp function", "spawn functions", "tspawnl function", "tspawnlp function", "_tspawnvpe function", "_tspawnl function", "tspawnvp function", "tspawnv function", "processes, executing new", "_tspawnv function", "tspawnle function", "process creation", "_tspawnlp function", "tspawnlpe function", "_tspawnle function"] -ms.assetid: bb47c703-5216-4e09-8023-8cf25bbf2cf9 --- -# _spawn, _wspawn Functions +# `_spawn`, `_wspawn` functions Each of the `_spawn` functions creates and executes a new process: -:::row::: - :::column span=""::: - [_spawnl, _wspawnl](../c-runtime-library/reference/spawnl-wspawnl.md)\ - [_spawnle, _wspawnle](../c-runtime-library/reference/spawnle-wspawnle.md)\ - [_spawnlp, _wspawnlp](../c-runtime-library/reference/spawnlp-wspawnlp.md)\ - [_spawnlpe, _wspawnlpe](../c-runtime-library/reference/spawnlpe-wspawnlpe.md)\ - :::column-end::: - :::column span=""::: - [_spawnv, _wspawnv](../c-runtime-library/reference/spawnv-wspawnv.md)\ - [_spawnve, _wspawnve](../c-runtime-library/reference/spawnve-wspawnve.md)\ - [_spawnvp, _wspawnvp](../c-runtime-library/reference/spawnvp-wspawnvp.md)\ - [_spawnvpe, _wspawnvpe](../c-runtime-library/reference/spawnvpe-wspawnvpe.md)\ - :::column-end::: -:::row-end::: +[`_spawnl`, `_wspawnl`](./reference/spawnl-wspawnl.md)\ +[`_spawnle`, `_wspawnle`](./reference/spawnle-wspawnle.md)\ +[`_spawnlp`, `_wspawnlp`](./reference/spawnlp-wspawnlp.md)\ +[`_spawnlpe`, `_wspawnlpe`](./reference/spawnlpe-wspawnlpe.md)\ +[`_spawnv`, `_wspawnv`](./reference/spawnv-wspawnv.md)\ +[`_spawnve`, `_wspawnve`](./reference/spawnve-wspawnve.md)\ +[`_spawnvp`, `_wspawnvp`](./reference/spawnvp-wspawnvp.md)\ +[`_spawnvpe`, `_wspawnvpe`](./reference/spawnvpe-wspawnvpe.md) The letters at the end of the function name determine the variation. -|Letter|Variant| -|-|-| -| `e` | `envp`, array of pointers to environment settings, is passed to new process. | -| `l` | Command-line arguments are passed individually to `_spawn` function. This suffix is typically used when a number of parameters to a new process is known in advance. | -| `p` | `PATH` environment variable is used to find the file to execute. | -| `v` | `argv`, array of pointers to command-line arguments, is passed to `_spawn` function. This suffix is typically used when a number of parameters to a new process is variable. | +| Letter | Variant | +|---|---| +| `e` | `envp`, array of pointers to environment settings, is passed to new process. | +| `l` | Command-line arguments are passed individually to `_spawn` function. This suffix is typically used when some parameters to a new process are known in advance. | +| `p` | `PATH` environment variable is used to find the file to execute. | +| `v` | `argv`, array of pointers to command-line arguments, is passed to `_spawn` function. This suffix is typically used when several parameters to a new process are variable. | ## Remarks -The `_spawn` functions each create and execute a new process. They automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wspawn` functions are wide-character versions of the `_spawn` functions; they do not handle multibyte-character strings. Otherwise, the `_wspawn` functions behave identically to their `_spawn` counterparts. +The `_spawn` functions each create and execute a new process. They automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wspawn` functions are wide-character versions of the `_spawn` functions; they don't handle multibyte-character strings. Otherwise, the `_wspawn` functions behave identically to their `_spawn` counterparts. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_tspawnl`|`_spawnl`|`_spawnl`|`_wspawnl`| -|`_tspawnle`|`_spawnle`|`_spawnle`|`_wspawnle`| -|`_tspawnlp`|`_spawnlp`|`_spawnlp`|`_wspawnlp`| -|`_tspawnlpe`|`_spawnlpe`|`_spawnlpe`|`_wspawnlpe`| -|`_tspawnv`|`_spawnv`|`_spawnv`|`_wspawnv`| -|`_tspawnve`|`_spawnve`|`_spawnve`|`_wspawnve`| -|`_tspawnvp`|`_spawnvp`|`_spawnvp`|`_wspawnvp`| -|`_tspawnvpe`|`_spawnvpe`|`_spawnvpe`|`_wspawnvpe`| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tspawnl` | `_spawnl` | `_spawnl` | `_wspawnl` | +| `_tspawnle` | `_spawnle` | `_spawnle` | `_wspawnle` | +| `_tspawnlp` | `_spawnlp` | `_spawnlp` | `_wspawnlp` | +| `_tspawnlpe` | `_spawnlpe` | `_spawnlpe` | `_wspawnlpe` | +| `_tspawnv` | `_spawnv` | `_spawnv` | `_wspawnv` | +| `_tspawnve` | `_spawnve` | `_spawnve` | `_wspawnve` | +| `_tspawnvp` | `_spawnvp` | `_spawnvp` | `_wspawnvp` | +| `_tspawnvpe` | `_spawnvpe` | `_spawnvpe` | `_wspawnvpe` | -Enough memory must be available for loading and executing the new process. The `mode` argument determines the action taken by the calling process before and during `_spawn`. The following values for `mode` are defined in Process.h: +Enough memory must be available for loading and executing the new process. The `mode` argument determines the action taken by the calling process before and during `_spawn`. The following values for `mode` are defined in `Process.h`: -|Value|Description| -|-|-| -| `_P_OVERLAY` | Overlays a calling process with a new process, destroying the calling process (same effect as `_exec` calls). | -| `_P_WAIT` | Suspends a calling thread until execution of the new process is complete (synchronous `_spawn`). | -| `_P_NOWAIT` or `_P_NOWAITO` | Continues to execute a calling process concurrently with the new process (asynchronous `_spawn`). | -| `_P_DETACH` | Continues to execute the calling process; the new process is run in the background with no access to the console or keyboard. Calls to `_cwait` against the new process fail (asynchronous `_spawn`). | +| Value | Description | +|---|---| +| `_P_OVERLAY` | Overlays a calling process with a new process, destroying the calling process (same effect as `_exec` calls). | +| `_P_WAIT` | Suspends a calling thread until execution of the new process is complete (synchronous `_spawn`). | +| `_P_NOWAIT` or `_P_NOWAITO` | Continues to execute a calling process concurrently with the new process (asynchronous `_spawn`). | +| `_P_DETACH` | Continues to execute the calling process; the new process is run in the background with no access to the console or keyboard. Calls to `_cwait` against the new process fail (asynchronous `_spawn`). | -The `cmdname` argument specifies the file that is executed as the new process and can specify a full path (from the root), a partial path (from the current working directory), or just a file name. If `cmdname` does not have a file name extension or does not end with a period (.), the `_spawn` function first tries the .com file name extension and then the .exe file name extension, the .bat file name extension, and finally the .cmd file name extension. +The `cmdname` argument specifies the file that is executed as the new process and can specify a full path (from the root), a partial path (from the current working directory), or just a file name. If `cmdname` doesn't have a file name extension or doesn't end with a period (.), the `_spawn` function first tries the .com file name extension and then the .exe file name extension, the .bat file name extension, and finally the .cmd file name extension. If `cmdname` has a file name extension, only that extension is used. If `cmdname` ends with a period, the `_spawn` call searches for `cmdname` with no file name extension. The `_spawnlp`, `_spawnlpe`, `_spawnvp`, and `_spawnvpe` functions search for `cmdname` (using the same procedures) in the directories specified by the `PATH` environment variable. -If `cmdname` contains a drive specifier or any slashes (that is, if it is a relative path), the `_spawn` call searches only for the specified file; no path searching is done. +If `cmdname` contains a drive specifier or any slashes (that is, if it's a relative path), the `_spawn` call searches only for the specified file; no path searching is done. In the past, some of these functions set `errno` to zero on success; the current behavior is to leave `errno` untouched on success, as specified by the C standard. If you need to emulate the old behavior, set `errno` to zero just before calling these functions. > [!NOTE] > To ensure proper overlay initialization and termination, do not use the `setjmp` or `longjmp` function to enter or leave an overlay routine. -## Arguments for the Spawned Process +## Arguments for the spawned process -To pass arguments to the new process, give one or more pointers to character strings as arguments in the `_spawn` call. These character strings form the argument list for the spawned process. The combined length of the strings forming the argument list for the new process must not exceed 1024 bytes. The terminating null character ('\0') for each string is not included in the count, but space characters (automatically inserted to separate arguments) are included. +To pass arguments to the new process, give one or more pointers to character strings as arguments in the `_spawn` call. These character strings form the argument list for the spawned process. The combined length of the strings forming the argument list for the new process must not exceed 1024 bytes. The terminating null character ('\0') for each string isn't included in the count, but space characters (automatically inserted to separate arguments) are included. > [!NOTE] > Spaces embedded in strings may cause unexpected behavior; for example, passing `_spawn` the string `"hi there"` will result in the new process getting two arguments, `"hi"` and `"there"`. If the intent was to have the new process open a file named "hi there", the process would fail. You can avoid this by quoting the string: `"\"hi there\""`. > [!IMPORTANT] -> Do not pass user input to `_spawn` without explicitly checking its content. `_spawn` will result in a call to [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) so keep in mind that unqualified path names could lead to potential security vulnerabilities. +> Do not pass user input to `_spawn` without explicitly checking its content. `_spawn` will result in a call to [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) so keep in mind that unqualified path names could lead to potential security vulnerabilities. -You can pass argument pointers as separate arguments (in `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe`) or as an array of pointers (in `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe`). You must pass at least one argument, `arg0` or `argv`[0], to the spawned process. By convention, this argument is the name of the program as you would type it on the command line. A different value does not produce an error. +You can pass argument pointers as separate arguments (in `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe`) or as an array of pointers (in `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe`). You must pass at least one argument, `arg0` or `argv[0]`, to the spawned process. By convention, this argument is the name of the program as you would type it on the command line. A different value doesn't produce an error. -The `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe` calls are typically used in cases where the number of arguments is known in advance. The `arg0` argument is usually a pointer to `cmdname`. The arguments `arg1` through `argn` are pointers to the character strings forming the new argument list. Following `argn`, there must be a **NULL** pointer to mark the end of the argument list. +The `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe` calls are typically used in cases where the number of arguments is known in advance. The `arg0` argument is usually a pointer to `cmdname`. The arguments `arg1` through `argn` are pointers to the character strings forming the new argument list. Following `argn`, there must be a `NULL` pointer to mark the end of the argument list. -The `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe` calls are useful when there is a variable number of arguments to the new process. Pointers to the arguments are passed as an array, `argv`*.* The argument `argv`[0] is usually a pointer to a path in real mode or to the program name in protected mode, and `argv`[1] through `argv`[`n`] are pointers to the character strings forming the new argument list. The argument `argv`[`n` +1] must be a **NULL** pointer to mark the end of the argument list. +The `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe` calls are useful when there's a variable number of arguments to the new process. Pointers to the arguments are passed as an array, `argv`*.* The argument `argv[0]` is usually a pointer to a path in real mode or to the program name in protected mode, and `argv[1]` through `argv[n]` are pointers to the character strings forming the new argument list. The argument `argv[n +1]` must be a `NULL` pointer to mark the end of the argument list. ## Environment of the Spawned Process -Files that are open when a `_spawn` call is made remain open in the new process. In the `_spawnl`, `_spawnlp`, `_spawnv`, and `_spawnvp` calls, the new process inherits the environment of the calling process. You can use the `_spawnle`, `_spawnlpe`, `_spawnve`, and `_spawnvpe` calls to alter the environment for the new process by passing a list of environment settings through the `envp` argument. The argument `envp` is an array of character pointers, each element (except the final element) of which points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME`=`value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (Note that `value` is not enclosed in double quotation marks.) The final element of the `envp` array should be **NULL**. When `envp` itself is **NULL**, the spawned process inherits the environment settings of the parent process. +Files that are open when a `_spawn` call is made remain open in the new process. In the `_spawnl`, `_spawnlp`, `_spawnv`, and `_spawnvp` calls, the new process inherits the environment of the calling process. You can use the `_spawnle`, `_spawnlpe`, `_spawnve`, and `_spawnvpe` calls to alter the environment for the new process by passing a list of environment settings through the `envp` argument. The argument `envp` is an array of character pointers, each element (except the final element) of which points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME`=`value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (The `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be `NULL`. When `envp` itself is `NULL`, the spawned process inherits the environment settings of the parent process. -The `_spawn` functions can pass all information about open files, including the translation mode, to the new process. This information is passed in real mode through the `C_FILE_INFO` entry in the environment. The startup code normally processes this entry and then deletes it from the environment. However, if a `_spawn` function spawns a non-C process, this entry remains in the environment. Printing the environment shows graphics characters in the definition string for this entry because the environment information is passed in binary form in real mode. It should not have any other effect on normal operations. In protected mode, the environment information is passed in text form and therefore contains no graphics characters. +The `_spawn` functions can pass all information about open files, including the translation mode, to the new process. This information is passed in real mode through the `C_FILE_INFO` entry in the environment. The startup code normally processes this entry and then deletes it from the environment. However, if a `_spawn` function spawns a non-C process, this entry remains in the environment. Printing the environment shows graphics characters in the definition string for this entry because the environment information is passed in binary form in real mode. It shouldn't have any other effect on normal operations. In protected mode, the environment information is passed in text form and therefore contains no graphics characters. You must explicitly flush (using `fflush` or `_flushall`) or close any stream before calling a `_spawn` function. -New processes created by calls to `_spawn` routines do not preserve signal settings. Instead, the spawned process resets signal settings to the default. +New processes created by calls to `_spawn` routines don't preserve signal settings. Instead, the spawned process resets signal settings to the default. ## Redirecting Output -If you are calling `_spawn` from a DLL or a GUI application and want to redirect the output to a pipe, you have two options: +If you're calling `_spawn` from a DLL or a GUI application and want to redirect the output to a pipe, you have two options: -- Use the Win32 API to create a pipe, then call [AllocConsole](/windows/console/allocconsole), set the handle values in the startup structure, and call [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). +- Use the Win32 API to create a pipe, then call [`AllocConsole`](/windows/console/allocconsole), set the handle values in the startup structure, and call [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). -- Call [_popen, _wpopen](../c-runtime-library/reference/popen-wpopen.md) which will create a pipe and invoke the app using **cmd.exe /c** (or **command.exe /c**). +- Call [`_popen` or `_wpopen`](./reference/popen-wpopen.md), which will create a pipe and invoke the app using **`cmd.exe /c`** (or **`command.exe /c`**). ## Example @@ -193,13 +183,13 @@ from SPAWN! ## See also -[Process and Environment Control](../c-runtime-library/process-and-environment-control.md)
-[abort](../c-runtime-library/reference/abort.md)
-[atexit](../c-runtime-library/reference/atexit.md)
-[_exec, _wexec Functions](../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](../c-runtime-library/reference/exit-exit-exit.md)
-[_flushall](../c-runtime-library/reference/flushall.md)
-[_getmbcp](../c-runtime-library/reference/getmbcp.md)
-[_onexit, _onexit_m](../c-runtime-library/reference/onexit-onexit-m.md)
-[_setmbcp](../c-runtime-library/reference/setmbcp.md)
-[system, _wsystem](../c-runtime-library/reference/system-wsystem.md) +[Process and environment control](./process-and-environment-control.md)\ +[`abort`](./reference/abort.md)\ +[`atexit`](./reference/atexit.md)\ +[`_exec`, `_wexec` functions](./exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_flushall`](./reference/flushall.md)\ +[`_getmbcp`](./reference/getmbcp.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md)\ +[`_setmbcp`](./reference/setmbcp.md)\ +[`system`, `_wsystem`](./reference/system-wsystem.md) diff --git a/docs/c-runtime-library/standard-types.md b/docs/c-runtime-library/standard-types.md index 037336c552..f5e544a7d2 100644 --- a/docs/c-runtime-library/standard-types.md +++ b/docs/c-runtime-library/standard-types.md @@ -1,97 +1,97 @@ --- description: "Learn more about: Standard Types" title: "Standard Types" -ms.date: "11/04/2016" -f1_keywords: ["__time64_t", "_diskfree_t", "_CRT_DUMP_CLIENT", "_fsize_t", "__timeb64", "File", "__utimeb64", "jmp_buf", "__finddata64_t", "_wfinddata_t", "_finddata_t", "utimbuf64", "wint_t", "wctrans_t", "wctype_t", "_HFILE", "_secerr_handler_func", "clock_t", "fpos_t", "_dev_t", "time64_t", "wfinddata64_t", "stat64", "ldiv_t", "_EXCEPTION_POINTERS", "terminate_function", "size_t", "timeb64", "tm", "_HEAPINFO", "unexpected_function", "_CrtMemState", "_se_translator_function", "sig_atomic_t", "_CRT_REPORT_HOOK", "_complex", "_w_finddatai64_t", "_timeb", "_onexit_t", "_RTC_ErrorNumber", "lconv", "_PNH", "_off_t", "ptrdiff_t", "time_t", "_FPIEEE_RECORD", "_exception", "__w_finddata64_t", "__stat64", "_utimbuf", "__utimbuf64", "div_t", "_CRT_ALLOC_HOOK", "int8_t", "uint8_t", "int16_t", "uint16_t", "int32_t", "uint32_t", "int64_t", "int_least8_t", "uint_least8_t", "int_least16_t", "uint_least16_t", "int_least32_t", "uint_least32_t", "int_least64_t", "uint_least64_t", "int_fast8_t", "uint_fast8_t", "int_fast16_t", "uint_fast16_t", "int_fast32_t", "uint_fast32_t", "int_fast64_t", "uint_fast64_t", "intmax_t", "uintmax_t"] -helpviewer_keywords: ["__timeb64 type", "tm type", "clock_t type", "intptr_t type", "diskfree_t type", "wctype_t type", "CRT_DUMP_CLIENT type", "sig_atomic_t type", "_PNH type", "time_t type", "wfinddata_t type", "timeb64", "CRT, standard types", "wint_t type", "_RTC_ErrorNumber type", "_diskfree_t type", "_dev_t type", "_wfinddata_t type", "HFILE type", "__utimbuf64 type", "div_t type", "_onexit_t type", "_secerr_handler_func type", "FPIEEE_RECORD type", "HEAPINFO type", "PNH type", "_CRT_ALLOC_HOOK type", "_se_translater_function type", "va_list type", "wctrans_t type", "secerr_handler_func type", "_locale_t type", "timeb type", "lconv type", "utimbuf type", "dev_t type", "unexpected_function typedef", "_complex type", "_off_t type", "off_t type", "RTC_ErrorNumber type", "_FPIEEE_RECORD type", "exception type", "_CRT_REPORT_HOOK type", "_HEAPINFO type", "ldiv_t type", "terminate_function type", "uintptr_t type", "_CRT_DUMP_CLIENT type", "_utimbuf type", "wfinddatai64_t type", "fpos_t type", "wchar_t type", "CRT_ALLOC_HOOK type", "_HFILE type", "__time64_t type", "_timeb type", "CrtMemState type", "__finddata64_t type", "_exception type", "stat type", "onexit_t type", "FILE constant", "_stat type", "finddata_t type", "__wfinddata64_t type", "ptrdiff_t type", "complex types", "_wfinddatai64_t type", "_EXCEPTION_POINTERS type", "jmp_buf type", "se_translater_function type", "size_t type", "EXCEPTION_POINTERS type", "__stat64 type", "_fsize_t type", "CRT_REPORT_HOOK type", "_finddata_t type"] +ms.date: 01/26/2023 +f1_keywords: ["CORECRT_IO/__finddata64_t", "CORECRT_IO/_finddata_t", "CORECRT_MATH/_complex", "CORECRT_MATH/_exception", "CORECRT_STARTUP/_EXCEPTION_POINTERS", "CORECRT_STARTUP/_onexit_t", "CORECRT_TERMINATE/terminate_function", "CORECRT_WIO/_fsize_t", "CORECRT_WIO/_wfinddata_t", "CORECRT_WIO/_wfinddata64_t", "CORECRT_WIO/_wfinddatai64_t", "CORECRT_WSTDIO/FILE", "CORECRT_WTIME/tm", "CORECRT/__time64_t", "CORECRT/time_t", "CORECRT/wctype_t", "CORECRT/wint_t", "CRTDBG/_CRT_ALLOC_HOOK", "CRTDBG/_CRT_DUMP_CLIENT", "CRTDBG/_CRT_REPORT_HOOK", "CRTDBG/_CrtMemState", "CRTDBG/_HFILE", "DIRECT/_diskfree_t", "EH/_se_translator_function", "EH/unexpected_function", "FPIEEE/_FPIEEE_RECORD", "LOCALE/lconv", "MALLOC/_HEAPINFO", "NEW/_PNH", "RTCAPI/_RTC_ErrorNumber", "SETJMP/jmp_buf", "SIGNAL/sig_atomic_t", "STDINT/int_fast16_t", "STDINT/int_fast32_t", "STDINT/int_fast64_t", "STDINT/int_fast8_t", "STDINT/int_least16_t", "STDINT/int_least32_t", "STDINT/int_least64_t", "STDINT/int_least8_t", "STDINT/int16_t", "STDINT/int32_t", "STDINT/int64_t", "STDINT/int8_t", "STDINT/intmax_t", "STDINT/uint_fast16_t", "STDINT/uint_fast32_t", "STDINT/uint_fast64_t", "STDINT/uint_fast8_t", "STDINT/uint_least16_t", "STDINT/uint_least32_t", "STDINT/uint_least64_t", "STDINT/uint_least8_t", "STDINT/uint16_t", "STDINT/uint32_t", "STDINT/uint64_t", "STDINT/uint8_t", "STDINT/uintmax_t", "STDIO/fpos_t", "STDLIB/div_t", "STDLIB/ldiv_t", "TIME/clock_t", "TIMEB/__timeb64", "TIMEB/_timeb", "TYPES/_dev_t", "TYPES/_off_t", "UTIME/__utimbuf64", "UTIME/_utimbuf", "VCRUNTIME/ptrdiff_t", "VCRUNTIME/size_t", "WCTYPE/wctrans_t", "__finddata64_t", "_finddata_t", "_complex", "_exception", "_EXCEPTION_POINTERS", "_onexit_t", "terminate_function", "_fsize_t", "_wfinddata_t", "_wfinddata64_t", "_wfinddatai64_t", "FILE", "tm", "__time64_t", "time_t", "wctype_t", "wint_t", "_CRT_ALLOC_HOOK", "_CRT_DUMP_CLIENT", "_CRT_REPORT_HOOK", "_CrtMemState", "_HFILE", "_diskfree_t", "_se_translator_function", "unexpected_function", "_FPIEEE_RECORD", "lconv", "_HEAPINFO", "_PNH", "_RTC_ErrorNumber", "jmp_buf", "sig_atomic_t", "int_fast16_t", "int_fast32_t", "int_fast64_t", "int_fast8_t", "int_least16_t", "int_least32_t", "int_least64_t", "int_least8_t", "int16_t", "int32_t", "int64_t", "int8_t", "intmax_t", "uint_fast16_t", "uint_fast32_t", "uint_fast64_t", "uint_fast8_t", "uint_least16_t", "uint_least32_t", "uint_least64_t", "uint_least8_t", "uint16_t", "uint32_t", "uint64_t", "uint8_t", "uintmax_t", "fpos_t", "div_t", "ldiv_t", "clock_t", "__timeb64", "_timeb", "_dev_t", "_off_t", "__utimbuf64", "_utimbuf", "ptrdiff_t", "size_t", "wctrans_t"] +helpviewer_keywords: ["__timeb64 type", "tm type", "clock_t type", "intptr_t type", "diskfree_t type", "wctype_t type", "CRT_DUMP_CLIENT type", "sig_atomic_t type", "_PNH type", "time_t type", "wfinddata_t type", "timeb64", "CRT, standard types", "wint_t type", "_RTC_ErrorNumber type", "_diskfree_t type", "_dev_t type", "_wfinddata_t type", "HFILE type", "__utimbuf64 type", "div_t type", "_onexit_t type", "_secerr_handler_func type", "FPIEEE_RECORD type", "HEAPINFO type", "PNH type", "_CRT_ALLOC_HOOK type", "_se_translater_function type", "va_list type", "wctrans_t type", "secerr_handler_func type", "_locale_t type", "timeb type", "lconv type", "utimbuf type", "dev_t type", "unexpected_function typedef", "_complex type", "_off_t type", "off_t type", "RTC_ErrorNumber type", "_FPIEEE_RECORD type", "exception type", "_CRT_REPORT_HOOK type", "_HEAPINFO type", "ldiv_t type", "terminate_function type", "uintptr_t type", "_CRT_DUMP_CLIENT type", "_utimbuf type", "wfinddatai64_t type", "fpos_t type", "wchar_t type", "CRT_ALLOC_HOOK type", "_HFILE type", "__time64_t type", "_timeb type", "CrtMemState type", "__finddata64_t type", "_exception type", "stat type", "onexit_t type", "FILE constant", "_stat type", "finddata_t type", "_wfinddata64_t type", "ptrdiff_t type", "complex types", "_wfinddatai64_t type", "_EXCEPTION_POINTERS type", "jmp_buf type", "se_translater_function type", "size_t type", "EXCEPTION_POINTERS type", "__stat64 type", "_fsize_t type", "CRT_REPORT_HOOK type", "_finddata_t type"] ms.assetid: 23312dd2-4a6a-4d70-9b48-2a5d0d8c9f28 --- -# Standard Types +# Standard types The Microsoft run-time library defines the following standard types and typedefs. ### Fixed-width integral types (`stdint.h`) -|Name|Equivalent built-in type| -|----------|-------------------------------| -|`int8_t`, `uint8_t`|`signed char`, `unsigned char`| -|`int16_t`, `uint16_t`|`short`, `unsigned short`| -|`int32_t`, `uint32_t`|`int`, `unsigned int`| -|`int64_t`, `uint64_t`|`long long`, `unsigned long long`| -|`int_least8_t`, `uint_least8_t`|`signed char`, `unsigned char`| -|`int_least16_t`, `uint_least16_t`|`short`, `unsigned short`| -|`int_least32_t`, `uint_least32_t`|`int`, `unsigned int`| -|`int_least64_t`, `uint_least64_t`|`long long`, `unsigned long long`| -|`int_fast8_t`, `uint_fast8_t`|`signed char`, `unsigned char`| -|`int_fast16_t`, `uint_fast16_t`|`int`, `unsigned int`| -|`int_fast32_t`, `uint_fast32_t`|`int`, `unsigned int`| -|`int_fast64_t`, `uint_fast64_t`|`long long`, `unsigned long long`| -|`intmax_t`, `uintmax_t`|`long long`, `unsigned long long`| +| Name | Equivalent built-in type | +|---|---| +| `int8_t`, `uint8_t` | `signed char`, `unsigned char` | +| `int16_t`, `uint16_t` | `short`, `unsigned short` | +| `int32_t`, `uint32_t` | `int`, `unsigned int` | +| `int64_t`, `uint64_t` | `long long`, `unsigned long long` | +| `int_least8_t`, `uint_least8_t` | `signed char`, `unsigned char` | +| `int_least16_t`, `uint_least16_t` | `short`, `unsigned short` | +| `int_least32_t`, `uint_least32_t` | `int`, `unsigned int` | +| `int_least64_t`, `uint_least64_t` | `long long`, `unsigned long long` | +| `int_fast8_t`, `uint_fast8_t` | `signed char`, `unsigned char` | +| `int_fast16_t`, `uint_fast16_t` | `int`, `unsigned int` | +| `int_fast32_t`, `uint_fast32_t` | `int`, `unsigned int` | +| `int_fast64_t`, `uint_fast64_t` | `long long`, `unsigned long long` | +| `intmax_t`, `uintmax_t` | `long long`, `unsigned long long` | -|Type|Description|Declared in| -|----------|-----------------|-----------------| -|`clock_t` (long)|Stores time values; used by [`clock`](../c-runtime-library/reference/clock.md).|`TIME.H`| -|`_complex` structure|Stores real and imaginary parts of complex numbers; used by [`_cabs`](../c-runtime-library/reference/cabs.md).|`MATH.H`| -|`_CRT_ALLOC_HOOK`|A type define for the user-defined hook function. Used in [`_CrtSetAllocHook`](../c-runtime-library/reference/crtsetallochook.md).|`CRTDBG.H`| -|`_CRT_DUMP_CLIENT`,

`_CRT_DUMP_CLIENT_M`|A type define for a call-back function that will get called in [`_CrtMemDumpAllObjectsSince`](../c-runtime-library/reference/crtmemdumpallobjectssince.md).|`CRTDBG.H`| -|`_CrtMemState` structure|Provides information about the current state of the C run-time debug heap.|`CRTDBG.H`| -|`_CRT_REPORT_HOOK`,

`_CRT_REPORT_HOOKW`,

`_CRT_REPORT_HOOKW_M`|A type define for a call-back function that will get called in [`_CrtDbgReport`](../c-runtime-library/reference/crtdbgreport-crtdbgreportw.md).

The parameters for this function are: report type, output message and the return value from the call-back function.|`CRTDBG.H`| -|`dev_t`, `_dev_t` short or unsigned integer|Represents device handles.|`SYS\TYPES.H`| -|`_diskfree_t` structure|Contains information about a disk drive. Used by [`_getdiskfree`](../c-runtime-library/reference/getdiskfree.md)**.**|`DOS.H` and `DIRECT.H`| -|`div_t`, `ldiv_t` and `lldiv_t` structures|Store values returned by [`div`](reference/div.md), [`ldiv`](./reference/div.md), and [`lldiv`](./reference/div.md), respectively.|`STDLIB.H`| -|`errno_t` integer|Used for a function return type or parameter that deals with the error codes of `errno`.|`STDDEF.H`,

`CRTDEFS.H`| -|`_exception` structure|Stores error information for [`_matherr`](../c-runtime-library/reference/matherr.md).|`MATH.H`| -|`_EXCEPTION_POINTERS`|Contains an exception record. See [`EXCEPTION_POINTERS`](/windows/win32/api/winnt/ns-winnt-exception_pointers) for more information.|`FPIEEE.H`| -|`FILE` structure|Stores information about current state of stream; used in all stream I/O operations.|`STDIO.H`| -|`_finddata_t`, `_wfinddata_t`, `_finddata32_t`, `_wfinddata32_t`, `_finddatai64_t`, `_wfinddatai64_t`, `__finddata64_t`, `__wfinddata64_t`, `__finddata32i64_t`, `__wfinddata32i64_t`, `__finddata64i32_t`, `__wfinddata64i32_t` structures|Store file-attribute information returned by [`_findfirst`, `_wfindfirst`, and related functions](../c-runtime-library/reference/findfirst-functions.md) and [`_findnext`, `_wfindnext` and related functions](../c-runtime-library/reference/findnext-functions.md). See [Filename Search Functions](../c-runtime-library/filename-search-functions.md) for information on structure members.|`IO.H`, `WCHAR.H`| -|`_FPIEEE_RECORD` structure|Contains information pertaining to IEEE floating-point exception; passed to user-defined trap handler by [`_fpieee_flt`](../c-runtime-library/reference/fpieee-flt.md).|`FPIEEE.H`| -|`fpos_t` (`long integer`, **`__int64`**, or structure, depending on the target platform)|Used by [`fgetpos`](../c-runtime-library/reference/fgetpos.md) and [`fsetpos`](../c-runtime-library/reference/fsetpos.md) to record information for uniquely specifying every position within a file.|`STDIO.H`| -|`_fsize_t` (`unsigned long integer`)|Used to represent the size of a file.|`IO.H`,

`WCHAR.H`| -|`_HEAPINFO` structure|Contains information about next heap entry for [`_heapwalk`](../c-runtime-library/reference/heapwalk.md).|`MALLOC.H`| -|`_HFILE` (void \*)|An operating system file handle.|`CRTDBG.H`| -|`imaxdiv_t`|The type of value that's returned by the [`imaxdiv`](../c-runtime-library/reference/imaxdiv.md) function, containing both the quotient and the remainder.|`inttypes.h`| -|`ino_t`, `_ino_t` (`unsigned short`)|For returning status information.|`WCHAR.H`| -|`intmax_t`|A signed integer type capable of representing any value of any signed integer type.|stdint.h| -|`intptr_t` (`long integer` or **`__int64`**, depending on the target platform)|Stores a pointer (or `HANDLE`) on both Win32 and Win64 platforms.|`STDDEF.H` and other include files| -|`jmp_buf` array|Used by [`setjmp`](../c-runtime-library/reference/setjmp.md) and [`longjmp`](../c-runtime-library/reference/longjmp.md) to save and restore program environment.|`SETJMP.H`| -|`lconv` structure|Contains formatting rules for numeric values in different countries/regions. Used by [`localeconv`](../c-runtime-library/reference/localeconv.md).|`LOCALE.H`| -|`_LDOUBLE`,

`_LONGDOUBLE`,

`_LDBL12` (long double or an unsigned char array)|Use to represent a long double value.|`STDLIB.H`| -|`_locale_t` structure|Stores current locale values; used in all locale specific C run-time libraries.|`CRTDEFS.H`| -|`mbstate_t`|Tracks the state of a multibyte character conversion.|`WCHAR.H`| -|`off_t`, `_off_t` `long integer`|Represents file-offset value.|`WCHAR.H`, `SYS\TYPES.H`| -|`_onexit_t`,

`_onexit_m_t` pointer|Returned by [`_onexit`, `_onexit_m`](../c-runtime-library/reference/onexit-onexit-m.md).|`STDLIB.H`| -|`_PNH` pointer to function|Type of argument to [`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md).|`NEW.H`| -|`ptrdiff_t` (long integer or **`__int64`**, depending on the target platform)|Result of subtraction of two pointers.|`CRTDEFS.H`| -|`_purecall_handler`,

`_purecall_handler_m`|A type define for a call-back function that is called when a pure virtual function is called. Used by [`_get_purecall_handler`, _set_purecall_handler](../c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md). A `_purecall_handler` function should have a void return type.|`STDLIB.H`| -|`_RTC_error_fn` type define|A type define for a function that will handle run-time error checks. Used in [_RTC_SetErrorFunc](../c-runtime-library/reference/rtc-seterrorfunc.md).|`RTCAPI.H`| -|`_RTC_error_fnW` type define|A type define for a function that will handle run-time error checks. Used in [`_RTC_SetErrorFuncW`](../c-runtime-library/reference/rtc-seterrorfuncw.md).|`RTCAPI.H`| -|`_RTC_ErrorNumber` enumeration|Defines error conditions for [`_RTC_GetErrDesc`](../c-runtime-library/reference/rtc-geterrdesc.md) and [`_RTC_SetErrorType`](../c-runtime-library/reference/rtc-seterrortype.md).|`RTCAPI.H`| -|`_se_translator_function`|A type define for a call-back function that translates an exception. The first parameter is the exception code and the second parameter is the exception record. Used by [`_set_se_translator`](../c-runtime-library/reference/set-se-translator.md).|`EH.H`| -|`sig_atomic_t` integer|Type of object that can be modified as atomic entity, even in presence of asynchronous interrupts; used with [`signal`](../c-runtime-library/reference/signal.md).|`SIGNAL.H`| -|`size_t` (`unsigned __int64` or `unsigned integer`, depending on the target platform)|Result of **`sizeof`** operator.|`CRTDEFS.H` and other include files| -|`_stat` structure|Contains file-status information returned by [`_stat`](../c-runtime-library/reference/stat-functions.md) and [`_fstat`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md).|`SYS\STAT.H`| -|`__stat64` structure|Contains file-status information returned by [`_fstat64`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md) and [`_stat64`](../c-runtime-library/reference/stat-functions.md), and [`_wstat64`](../c-runtime-library/reference/stat-functions.md).|`SYS\STAT.H`| -|`_stati64` structure|Contains file-status information returned by [`_fstati64`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md), [`_stati64`](../c-runtime-library/reference/stat-functions.md), and [`_wstati64`](../c-runtime-library/reference/stat-functions.md).|`SYS\STAT.H`| -|`terminate_function` type define|A type define for a call-back function that is called when [`terminate`](../c-runtime-library/reference/terminate-crt.md) is called. Used by [`set_terminate`](../c-runtime-library/reference/set-terminate-crt.md).|`EH.H`| -|`time_t` (`__int64` or `long integer`)|Represents time values in [`mktime`](../c-runtime-library/reference/mktime-mktime32-mktime64.md), [`time`](../c-runtime-library/reference/time-time32-time64.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, _wctime32_s, _wctime64_s](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) and [`gmtime`, `_gmtime32`, `_gmtime64`](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md). The number of seconds since January 1, 1970, 0:00 UTC. If `_USE_32BIT_TIME_T` is defined, `time_t` is a long integer. If not defined, it is a 64-bit integer.|`TIME.H`,

`SYS\STAT.H`,

`SYS\TIMEB.H`| -|`__time32_t` (`long integer`)|Represents time values in [`mktime`, `_mktime32`, `_mktime64`](../c-runtime-library/reference/mktime-mktime32-mktime64.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`gmtime`, `_gmtime32`, `_gmtime64`](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md) and [`localtime`, `_localtime32`, `_localtime64`](../c-runtime-library/reference/localtime-localtime32-localtime64.md).|`CRTDEFS.H`, `SYS\STAT.H`,

`SYS\TIMEB.H`| -|`__time64_t` (**`__int64`**)|Represents time values in [`mktime`, `_mktime32`, `_mktime64`](../c-runtime-library/reference/mktime-mktime32-mktime64.md), [`_ctime64`, `_wctime64`](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`_gmtime64`](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md), [`_localtime64`](../c-runtime-library/reference/localtime-localtime32-localtime64.md) and [`_time64`](../c-runtime-library/reference/time-time32-time64.md).|`TIME.H`,

`SYS\STAT.H`,

`SYS\TIMEB.H`| -|`_timeb` structure|Used by [`_ftime`](../c-runtime-library/reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md) to store current system time.|`SYS\TIMEB.H`| -|`__timeb32` structure|Used by [`_ftime`, `_ftime32`, `_ftime64`](../c-runtime-library/reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md) to store current system time.|`SYS\TIMEB.H`| -|`__timeb64` structure|Used by [`_ftime64`](../c-runtime-library/reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md) to store current system time.|`SYS\TIMEB.H`| -|`tm` structure|Used by [`asctime`, `_wasctime`](../c-runtime-library/reference/asctime-wasctime.md), [`asctime_s`, `_wasctime_s`](../c-runtime-library/reference/asctime-s-wasctime-s.md), [`gmtime`, `_gmtime32`, `_gmtime64`](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md), [`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](../c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md), [`localtime`, `_localtime32`, `_localtime64`](../c-runtime-library/reference/localtime-localtime32-localtime64.md), [`localtime_s`, `_localtime32_s`, `_localtime64_s`](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md), [`mktime`, `_mktime32`, `_mktime64`](../c-runtime-library/reference/mktime-mktime32-mktime64.md) and [`strftime`, `wcsftime`, _strftime_l, _wcsftime_l](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md) to store and retrieve time information.|`TIME.H`| -|`uintmax_t`|An `unsigned integer` type capable of representing any value of any `unsigned integer` type.|`stdint.h`| -|`uintptr_t` (`long integer` or **`__int64`**, depending on the target platform)|An `unsigned integer` or `unsigned __int64` version of `intptr_t`.|`STDDEF.H` and other include files| -|`unexpected_function`|A type define for a call-back function that is called when [`unexpected`](../c-runtime-library/reference/unexpected-crt.md) is called. Used by [`set_unexpected`](../c-runtime-library/reference/set-unexpected-crt.md).|`EH.H`| -|`_utimbuf` structure|Stores file access and modification times used by [`_utime`, `_wutime`](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [`_futime`, `_futime32`, `_futime64`](../c-runtime-library/reference/futime-futime32-futime64.md) to change file-modification dates.|`SYS\UTIME.H`| -|`_utimbuf32` structure|Stores file access and modification times used by [`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [`_futime`, `_futime32`, `_futime64`](../c-runtime-library/reference/futime-futime32-futime64.md) to change file-modification dates.|`SYS\UTIME.H`| -|`__utimbuf64` structure|Used by [`_utime64`, `_wutime64`](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [_futime64](../c-runtime-library/reference/futime-futime32-futime64.md) to store the current time.|`SYS\UTIME.H`| -|`va_list` structure|Used to hold information needed by [`va_arg`](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) and [`va_end`](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) macros. Called function declares variable of type `va_list` that can be passed as argument to another function.|`STDARG.H`,

`CRTDEFS.H`| -|**`wchar_t`** wide character|Useful for writing portable programs for international markets.|`STDDEF.H`, `STDLIB.H`,

`CRTDEFS.H`,

`SYS\STAT.H`| -|`wctrans_t` integer|Represents locale-specific character mappings.|`WCTYPE.H`| -|`wctype_t` integer|Can represent all characters of any language character set.|`WCHAR.H`,

`CRTDEFS.H`| -|`wint_t` integer|Type of data object that can hold any wide character or wide end-of-file value.|`WCHAR.H`,

`CRTDEFS.H`| +| Type | Description | Declared in | +|---|---|---| +| `clock_t` (long) | Stores time values; used by [`clock`](./reference/clock.md). | `TIME.H` | +| `_complex` structure | Stores real and imaginary parts of complex numbers; used by [`_cabs`](./reference/cabs.md). | `MATH.H` | +| `_CRT_ALLOC_HOOK` | A type definition for the user-defined hook function. Used in [`_CrtSetAllocHook`](./reference/crtsetallochook.md). | `CRTDBG.H` | +| `_CRT_DUMP_CLIENT`,

`_CRT_DUMP_CLIENT_M` | A type definition for a call-back function that will get called in [`_CrtMemDumpAllObjectsSince`](./reference/crtmemdumpallobjectssince.md). | `CRTDBG.H` | +| `_CrtMemState` structure | Provides information about the current state of the C run-time debug heap. | `CRTDBG.H` | +| `_CRT_REPORT_HOOK`,

`_CRT_REPORT_HOOKW`,

`_CRT_REPORT_HOOKW_M` | A type definition for a call-back function that will get called in [`_CrtDbgReport`](./reference/crtdbgreport-crtdbgreportw.md).

The parameters for this function are: report type, output message and the return value from the call-back function. | `CRTDBG.H` | +| `dev_t`, `_dev_t` short or unsigned integer | Represents device handles. | `SYS\TYPES.H` | +| `_diskfree_t` structure | Contains information about a disk drive. Used by [`_getdiskfree`](./reference/getdiskfree.md)**.** | `DOS.H` and `DIRECT.H` | +| `div_t`, `ldiv_t` and `lldiv_t` structures | Store values returned by [`div`](reference/div.md), [`ldiv`](./reference/div.md), and [`lldiv`](./reference/div.md), respectively. | `STDLIB.H` | +| `errno_t` integer | Used for a function return type or parameter that deals with the error codes of `errno`. | `STDDEF.H`,

`CRTDEFS.H` | +| `_exception` structure | Stores error information for [`_matherr`](./reference/matherr.md). | `MATH.H` | +| `_EXCEPTION_POINTERS` | Contains an exception record. For more information, see [`EXCEPTION_POINTERS`](/windows/win32/api/winnt/ns-winnt-exception_pointers). | `FPIEEE.H` | +| `FILE` structure | Stores information about current state of stream; used in all stream I/O operations. | `STDIO.H` | +| `_finddata_t`, `_wfinddata_t`, `_finddata32_t`, `_wfinddata32_t`, `_finddatai64_t`, `_wfinddatai64_t`, `__finddata64_t`, `_wfinddata64_t`, `__finddata32i64_t`, `__wfinddata32i64_t`, `__finddata64i32_t`, `__wfinddata64i32_t` structures | Store file-attribute information returned by [`_findfirst`, `_wfindfirst`, and related functions](./reference/findfirst-functions.md) and [`_findnext`, `_wfindnext` and related functions](./reference/findnext-functions.md). See [Filename search functions](./filename-search-functions.md) for information on structure members. | `IO.H`, `WCHAR.H` | +| `_FPIEEE_RECORD` structure | Contains information pertaining to IEEE floating-point exception; passed to user-defined trap handler by [`_fpieee_flt`](./reference/fpieee-flt.md). | `FPIEEE.H` | +| `fpos_t` (`long integer`, **`__int64`**, or structure, depending on the target platform) | Used by [`fgetpos`](./reference/fgetpos.md) and [`fsetpos`](./reference/fsetpos.md) to record information for uniquely specifying every position within a file. | `STDIO.H` | +| `_fsize_t` (`unsigned long integer`) | Used to represent the size of a file. | `IO.H`,

`WCHAR.H` | +| `_HEAPINFO` structure | Contains information about next heap entry for [`_heapwalk`](./reference/heapwalk.md). | `MALLOC.H` | +| `_HFILE` (void \*) | An operating system file handle. | `CRTDBG.H` | +| `imaxdiv_t` | The type of value that's returned by the [`imaxdiv`](./reference/imaxdiv.md) function, containing both the quotient and the remainder. | `inttypes.h` | +| `ino_t`, `_ino_t` (`unsigned short`) | For returning status information. | `WCHAR.H` | +| `intmax_t` | A signed integer type capable of representing any value of any signed integer type. | stdint.h | +| `intptr_t` (`long integer` or **`__int64`**, depending on the target platform) | Stores a pointer (or `HANDLE`) on both Win32 and Win64 platforms. | `STDDEF.H` and other include files | +| `jmp_buf` array | Used by [`setjmp`](./reference/setjmp.md) and [`longjmp`](./reference/longjmp.md) to save and restore program environment. | `SETJMP.H` | +| `lconv` structure | Contains formatting rules for numeric values in different countries/regions. Used by [`localeconv`](./reference/localeconv.md). | `LOCALE.H` | +| `_LDOUBLE`,

`_LONGDOUBLE`,

`_LDBL12` (long double or an unsigned char array) | Use to represent a long double value. | `STDLIB.H` | +| `_locale_t` structure | Stores current locale values; used in all locale specific C run-time libraries. | `CRTDEFS.H` | +| `mbstate_t` | Tracks the state of a multibyte character conversion. | `WCHAR.H` | +| `off_t`, `_off_t` `long integer` | Represents file-offset value. | `WCHAR.H`, `SYS\TYPES.H` | +| `_onexit_t`,

`_onexit_m_t` pointer | Returned by [`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md). | `STDLIB.H` | +| `_PNH` pointer to function | Type of argument to [`_set_new_handler`](./reference/set-new-handler.md). | `NEW.H` | +| `ptrdiff_t` (long integer or **`__int64`**, depending on the target platform) | Result of subtraction of two pointers. | `CRTDEFS.H` | +| `_purecall_handler`,

`_purecall_handler_m` | A type definition for a call-back function that is called when a pure virtual function is called. Used by [`_get_purecall_handler`, _set_purecall_handler](./reference/get-purecall-handler-set-purecall-handler.md). A `_purecall_handler` function should have a void return type. | `STDLIB.H` | +| `_RTC_error_fn` type definition | A type definition for a function that will handle run-time error checks. Used in [`_RTC_SetErrorFunc`](./reference/rtc-seterrorfunc.md). | `RTCAPI.H` | +| `_RTC_error_fnW` type definition | A type definition for a function that will handle run-time error checks. Used in [`_RTC_SetErrorFuncW`](./reference/rtc-seterrorfuncw.md). | `RTCAPI.H` | +| `_RTC_ErrorNumber` enumeration | Defines error conditions for [`_RTC_GetErrDesc`](./reference/rtc-geterrdesc.md) and [`_RTC_SetErrorType`](./reference/rtc-seterrortype.md). | `RTCAPI.H` | +| `_se_translator_function` | A type definition for a call-back function that translates an exception. The first parameter is the exception code and the second parameter is the exception record. Used by [`_set_se_translator`](./reference/set-se-translator.md). | `EH.H` | +| `sig_atomic_t` integer | Type of object that can be modified as atomic entity, even in presence of asynchronous interrupts; used with [`signal`](./reference/signal.md). | `SIGNAL.H` | +| `size_t` (`unsigned __int64` or `unsigned integer`, depending on the target platform) | Result of **`sizeof`** operator. | `CRTDEFS.H` and other include files | +| `_stat` structure | Contains file-status information returned by [`_stat`](./reference/stat-functions.md) and [`_fstat`](./reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md). | `SYS\STAT.H` | +| `__stat64` structure | Contains file-status information returned by [`_fstat64`](./reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md) and [`_stat64`](./reference/stat-functions.md), and [`_wstat64`](./reference/stat-functions.md). | `SYS\STAT.H` | +| `_stati64` structure | Contains file-status information returned by [`_fstati64`](./reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md), [`_stati64`](./reference/stat-functions.md), and [`_wstati64`](./reference/stat-functions.md). | `SYS\STAT.H` | +| `terminate_function` type definition | A type definition for a call-back function that is called when [`terminate`](./reference/terminate-crt.md) is called. Used by [`set_terminate`](./reference/set-terminate-crt.md). | `EH.H` | +| `time_t` (`__int64` or `long integer`) | Represents time values in [`mktime`](./reference/mktime-mktime32-mktime64.md), [`time`](./reference/time-time32-time64.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, _wctime32_s, _wctime64_s](./reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) and [`gmtime`, `_gmtime32`, `_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md). The number of seconds since January 1, 1970, 0:00 UTC. If `_USE_32BIT_TIME_T` is defined, `time_t` is a long integer. If not defined, it's a 64-bit integer. | `TIME.H`,

`SYS\STAT.H`,

`SYS\TIMEB.H` | +| `__time32_t` (`long integer`) | Represents time values in [`mktime`, `_mktime32`, `_mktime64`](./reference/mktime-mktime32-mktime64.md), [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](./reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`gmtime`, `_gmtime32`, `_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md) and [`localtime`, `_localtime32`, `_localtime64`](./reference/localtime-localtime32-localtime64.md). | `CRTDEFS.H`, `SYS\STAT.H`,

`SYS\TIMEB.H` | +| `__time64_t` (**`__int64`**) | Represents time values in [`mktime`, `_mktime32`, `_mktime64`](./reference/mktime-mktime32-mktime64.md), [`_ctime64`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](./reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md), [`_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md), [`_localtime64`](./reference/localtime-localtime32-localtime64.md) and [`_time64`](./reference/time-time32-time64.md). | `TIME.H`,

`SYS\STAT.H`,

`SYS\TIMEB.H` | +| `_timeb` structure | The [`_ftime`](./reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](./reference/ftime-s-ftime32-s-ftime64-s.md) functions use it to store current system time. | `SYS\TIMEB.H` | +| `__timeb32` structure | The [`_ftime`, `_ftime32`, `_ftime64`](./reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](./reference/ftime-s-ftime32-s-ftime64-s.md) functions use it to store current system time. | `SYS\TIMEB.H` | +| `__timeb64` structure | The [`_ftime64`](./reference/ftime-ftime32-ftime64.md) and [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](./reference/ftime-s-ftime32-s-ftime64-s.md) functions use it to store current system time. | `SYS\TIMEB.H` | +| `tm` structure | The [`asctime`, `_wasctime`](./reference/asctime-wasctime.md), [`asctime_s`, `_wasctime_s`](./reference/asctime-s-wasctime-s.md), [`gmtime`, `_gmtime32`, `_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md), [`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](./reference/gmtime-s-gmtime32-s-gmtime64-s.md), [`localtime`, `_localtime32`, `_localtime64`](./reference/localtime-localtime32-localtime64.md), [`localtime_s`, `_localtime32_s`, `_localtime64_s`](./reference/localtime-s-localtime32-s-localtime64-s.md), [`mktime`, `_mktime32`, `_mktime64`](./reference/mktime-mktime32-mktime64.md) and [`strftime`, `wcsftime`, _strftime_l, _wcsftime_l](./reference/strftime-wcsftime-strftime-l-wcsftime-l.md) functions use it to store and retrieve time information. | `TIME.H` | +| `uintmax_t` | An `unsigned integer` type capable of representing any value of any `unsigned integer` type. | `stdint.h` | +| `uintptr_t` (`long integer` or **`__int64`**, depending on the target platform) | An `unsigned integer` or `unsigned __int64` version of `intptr_t`. | `STDDEF.H` and other include files | +| `unexpected_function` | A type definition for a call-back function that is called when [`unexpected`](./reference/unexpected-crt.md) is called. Used by [`set_unexpected`](./reference/set-unexpected-crt.md). | `EH.H` | +| `_utimbuf` structure | Stores file access and modification times used by [`_utime`, `_wutime`](./reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [`_futime`, `_futime32`, `_futime64`](./reference/futime-futime32-futime64.md) to change file-modification dates. | `SYS\UTIME.H` | +| `_utimbuf32` structure | Stores file access and modification times used by [`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](./reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [`_futime`, `_futime32`, `_futime64`](./reference/futime-futime32-futime64.md) to change file-modification dates. | `SYS\UTIME.H` | +| `__utimbuf64` structure | The [`_utime64`, `_wutime64`](./reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) and [`_futime64`](./reference/futime-futime32-futime64.md) functions use it to store the current time. | `SYS\UTIME.H` | +| `va_list` structure | Used to hold information needed by [`va_arg`](./reference/va-arg-va-copy-va-end-va-start.md) and [`va_end`](./reference/va-arg-va-copy-va-end-va-start.md) macros. Called function declares variable of type `va_list` that can be passed as argument to another function. | `STDARG.H`,

`CRTDEFS.H` | +| **`wchar_t`** wide character | Useful for writing portable programs for international markets. | `STDDEF.H`, `STDLIB.H`,

`CRTDEFS.H`,

`SYS\STAT.H` | +| `wctrans_t` integer | Represents locale-specific character mappings. | `WCTYPE.H` | +| `wctype_t` integer | Can represent all characters of any language character set. | `WCHAR.H`,

`CRTDEFS.H` | +| `wint_t` integer | Type of data object that can hold any wide character or wide end-of-file value. | `WCHAR.H`,

`CRTDEFS.H` | ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md) +[C runtime library reference](./c-run-time-library-reference.md) diff --git a/docs/c-runtime-library/stat-structure-st-mode-field-constants.md b/docs/c-runtime-library/stat-structure-st-mode-field-constants.md index 974e7bdaf0..2447bd7997 100644 --- a/docs/c-runtime-library/stat-structure-st-mode-field-constants.md +++ b/docs/c-runtime-library/stat-structure-st-mode-field-constants.md @@ -2,37 +2,37 @@ description: "Learn more about: _stat Structure st_mode Field Constants" title: "_stat Structure st_mode Field Constants" ms.date: "11/04/2016" -f1_keywords: ["S_IFCHR", "S_IFDIR", "_S_IWRITE", "S_IFMT", "_S_IFDIR", "_S_IREAD", "S_IEXEC", "_S_IEXEC", "_S_IFMT", "S_IWRITE", "S_IFREG", "S_IREAD", "_S_IFCHR", "_S_IFREG"] +f1_keywords: ["STAT/S_IFCHR", "STAT/S_IFDIR", "STAT/_S_IWRITE", "STAT/S_IFMT", "STAT/_S_IFDIR", "STAT/_S_IREAD", "STAT/S_IEXEC", "STAT/_S_IEXEC", "STAT/_S_IFMT", "STAT/S_IWRITE", "STAT/S_IFREG", "STAT/S_IREAD", "STAT/_S_IFCHR", "STAT/_S_IFREG", "S_IFCHR", "S_IFDIR", "_S_IWRITE", "S_IFMT", "_S_IFDIR", "_S_IREAD", "S_IEXEC", "_S_IEXEC", "_S_IFMT", "S_IWRITE", "S_IFREG", "S_IREAD", "_S_IFCHR", "_S_IFREG"] helpviewer_keywords: ["S_IFDIR constant", "stat structure", "S_IWRITE constant", "S_IEXEC constant", "_S_IFREG constant", "S_IREAD constant", "stat structure, constants", "_S_IFMT constant", "st_mode field constants", "S_IFMT constant", "_S_IEXEC constant", "_S_IWRITE constant", "_S_IFDIR constant", "S_IFREG constant", "S_IFCHR constant", "_S_IREAD constant", "_S_IFCHR constant"] ms.assetid: fd462004-7563-4766-8443-30b0a86174b6 --- -# _stat Structure st_mode Field Constants +# `_stat` structure `st_mode` field constants ## Syntax -``` +```C #include ``` ## Remarks -These constants are used to indicate file type in the **st_mode** field of the [_stat structure](../c-runtime-library/standard-types.md). +These constants are used to indicate file type in the `st_mode` field of the [`_stat` structure](./standard-types.md). The bit mask constants are described below: -|Constant|Meaning| -|--------------|-------------| -|`_S_IFMT`|File type mask| -|`_S_IFDIR`|Directory| -|`_S_IFCHR`|Character special (indicates a device if set)| -|`_S_IFREG`|Regular| -|`_S_IREAD`|Read permission, owner| -|`_S_IWRITE`|Write permission, owner| -|`_S_IEXEC`|Execute/search permission, owner| +| Constant | Meaning | +|---|---| +| `_S_IFMT` | File type mask | +| `_S_IFDIR` | Directory | +| `_S_IFCHR` | Character special (indicates a device if set) | +| `_S_IFREG` | Regular | +| `_S_IREAD` | Read permission, owner | +| `_S_IWRITE` | Write permission, owner | +| `_S_IEXEC` | Execute/search permission, owner | ## See also -[_stat, _wstat Functions](../c-runtime-library/reference/stat-functions.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[Standard Types](../c-runtime-library/standard-types.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_stat`, `_wstat` functions](./reference/stat-functions.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](./reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[Standard types](./standard-types.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/stdin-stdout-stderr.md b/docs/c-runtime-library/stdin-stdout-stderr.md index 08f6e5127a..b88b099b36 100644 --- a/docs/c-runtime-library/stdin-stdout-stderr.md +++ b/docs/c-runtime-library/stdin-stdout-stderr.md @@ -1,41 +1,39 @@ --- -description: "Learn more about: stdin, stdout, stderr" +description: "Learn more about the definitions of: stdin, stdout, stderr" title: "stdin, stdout, stderr" -ms.date: "10/23/2018" -f1_keywords: ["stdin", "stderr", "stdout"] +ms.date: "7/24/2023" +f1_keywords: ["CORECRT_WSTDIO/stdin", "CORECRT_WSTDIO/stderr", "CORECRT_WSTDIO/stdout", "stdin", "stderr", "stdout"] helpviewer_keywords: ["stdout function", "standard output stream", "standard error stream", "stdin function", "standard input stream", "stderr function"] -ms.assetid: badd4735-596d-4498-857c-ec8b7e670e4c --- # `stdin`, `stdout`, `stderr` ## Syntax -``` -FILE *stdin; -FILE *stdout; -FILE *stderr; -#include +```C +#define stdin /* implementation defined */ +#define stdout /* implementation defined */ +#define stderr /* implementation defined */ ``` ## Remarks -These are standard streams for input, output, and error output. +The **`stdin`**, **`stdout`**, and **`stderr`** global constant pointers are standard streams for input, output, and error output. By default, standard input is read from the keyboard, while standard output and standard error are printed to the screen. The following stream pointers are available to access the standard streams: -|Pointer|Stream| -|-------------|------------| -|`stdin`|Standard input| -|`stdout`|Standard output| -|`stderr`|Standard error| +| Pointer | Stream | +|---|---| +| **`stdin`** | Standard input | +| **`stdout`** | Standard output | +| **`stderr`** | Standard error | -These pointers can be used as arguments to functions. Some functions, such as [`getchar`](../c-runtime-library/reference/getchar-getwchar.md) and [`putchar`](../c-runtime-library/reference/putchar-putwchar.md), use `stdin` and `stdout` automatically. +These pointers can be used as arguments to functions. Some functions, such as [`getchar`](./reference/getchar-getwchar.md) and [`putchar`](./reference/putchar-putwchar.md), use **`stdin`** and **`stdout`** automatically. -These pointers are constants, and cannot be assigned new values. The [`freopen`](../c-runtime-library/reference/freopen-wfreopen.md) function can be used to redirect the streams to disk files or to other devices. The operating system allows you to redirect a program's standard input and output at the command level. +These pointers are constants, and can't be assigned new values. The [`freopen`](./reference/freopen-wfreopen.md) function can be used to redirect the streams to disk files or to other devices. The operating system allows you to redirect a program's standard input and output at the command level. ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Stream I/O](./stream-i-o.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/strcoll-functions.md b/docs/c-runtime-library/strcoll-functions.md index 145891ee63..9677b6a42e 100644 --- a/docs/c-runtime-library/strcoll-functions.md +++ b/docs/c-runtime-library/strcoll-functions.md @@ -2,44 +2,40 @@ description: "Learn more about: strcoll Functions" title: "strcoll Functions" ms.date: "11/04/2016" -api_location: ["msvcr120.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["strcoll"] helpviewer_keywords: ["code pages, using for string comparisons", "string comparison [C++], culture-specific", "strcoll functions", "strings [C++], comparing by code page"] ms.assetid: c09eeff3-8aba-4cfb-a524-752436d85573 --- -# strcoll Functions +# `strcoll` functions -Each of the `strcoll` and `wcscoll` functions compares two strings according to the `LC_COLLATE` category setting of the locale code page currently in use. Each of the `_mbscoll` functions compares two strings according to the multibyte code page currently in use. Use the `coll` functions for string comparisons when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the comparison. Use the corresponding `cmp` functions to test only for string equality. +Each of the `strcoll` and `wcscoll` functions compares two strings according to the `LC_COLLATE` category setting of the locale code page currently in use. Each of the `_mbscoll` functions compares two strings according to the multibyte code page currently in use. Use the `coll` functions for string comparisons when there's a difference between the character set order and the lexicographic character order in the current code page if the difference is of interest for the comparison. Use the corresponding `cmp` functions to test only for string equality. ### strcoll Functions -|SBCS|Unicode|MBCS|Description| -|----------|-------------|----------|-----------------| -|[strcoll](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|[wcscoll](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|[_mbscoll](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|Collate two strings| -|[_stricoll](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|[_wcsicoll](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|[_mbsicoll](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|Collate two strings (case insensitive)| -|[_strncoll](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|[_wcsncoll](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|[_mbsncoll](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|Collate first `count` characters of two strings| -|[_strnicoll](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|[_wcsnicoll](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|[_mbsnicoll](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Collate first `count` characters of two strings (case-insensitive)| +| SBCS | Unicode | MBCS | Description | +|---|---|---|---| +| [`strcoll`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md) | [`wcscoll`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md) | [`_mbscoll`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md) | Collate two strings | +| [`_stricoll`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) | [`_wcsicoll`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) | [`_mbsicoll`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) | Collate two strings (case insensitive) | +| [`_strncoll`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | [`_wcsncoll`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | [`_mbsncoll`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | Collate first `count` characters of two strings | +| [`_strnicoll`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | [`_wcsnicoll`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | [`_mbsnicoll`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | Collate first `count` characters of two strings (case-insensitive) | ## Remarks -The single-byte character (SBCS) versions of these functions (`strcoll`, `stricoll`, `_strncoll`, and `_strnicoll`) compare `string1` and `string2` according to the `LC_COLLATE` category setting of the current locale. These functions differ from the corresponding `strcmp` functions in that the `strcoll` functions use locale code page information that provides collating sequences. For string comparisons in locales in which the character set order and the lexicographic character order differ, the `strcoll` functions should be used rather than the corresponding `strcmp` functions. For more information on `LC_COLLATE`, see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). +The single-byte character (SBCS) versions of these functions (`strcoll`, `stricoll`, `_strncoll`, and `_strnicoll`) compare `string1` and `string2` according to the `LC_COLLATE` category setting of the current locale. These functions differ from the corresponding `strcmp` functions in that the `strcoll` functions use locale code page information that provides collating sequences. For string comparisons in locales in which the character set order and the lexicographic character order differ, the `strcoll` functions should be used rather than the corresponding `strcmp` functions. For more information on `LC_COLLATE`, see [`setlocale`](./reference/setlocale-wsetlocale.md). -For some code pages and corresponding character sets, the order of characters in the character set may differ from the lexicographic character order. In the "C" locale, this is not the case: the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison in such an instance, use `strcoll` rather than `strcmp`. Alternatively, you can use `strxfrm` on the original strings, then use `strcmp` on the resulting strings. +For some code pages and corresponding character sets, the order of characters in the character set may differ from the lexicographic character order. In the "C" locale, it isn't the case: the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison in such an instance, use `strcoll` rather than `strcmp`. Alternatively, you can use `strxfrm` on the original strings, then use `strcmp` on the resulting strings. `strcoll`, `stricoll`, `_strncoll`, and `_strnicoll` automatically handle multibyte-character strings according to the locale code page currently in use, as do their wide-character (Unicode) counterparts. The multibyte-character (MBCS) versions of these functions, however, collate strings on a character basis according to the multibyte code page currently in use. -Because the `coll` functions collate strings lexicographically for comparison, whereas the `cmp` functions simply test for string equality, the `coll` functions are much slower than the corresponding `cmp` versions. Therefore, the `coll` functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. +Because the `coll` functions collate strings lexicographically for comparison, whereas the `cmp` functions simply test for string equality, the `coll` functions are much slower than the corresponding `cmp` versions. Therefore, the `coll` functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. ## See also -[Locale](../c-runtime-library/locale.md)
-[String Manipulation](../c-runtime-library/string-manipulation-crt.md)
-[localeconv](../c-runtime-library/reference/localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](../c-runtime-library/reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](../c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](../c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) +[Locale](./locale.md)\ +[String manipulation](./string-manipulation-crt.md)\ +[`localeconv`](./reference/localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](./reference/mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](./reference/strcmp-wcscmp-mbscmp.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](./reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](./reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/stream-i-o.md b/docs/c-runtime-library/stream-i-o.md index eadad7f8f9..e91fcfdda2 100644 --- a/docs/c-runtime-library/stream-i-o.md +++ b/docs/c-runtime-library/stream-i-o.md @@ -1,91 +1,89 @@ --- -description: "Learn more about: Stream I/O" title: "Stream I/O" -ms.date: "11/04/2016" +description: "Learn more about: Stream I/O" +ms.date: 11/04/2016 helpviewer_keywords: ["I/O routines, stream I/O", "I/O [CRT], stream", "stream I/O"] -ms.assetid: dc7874d3-a91b-456a-9015-4748bb358217 --- # Stream I/O These functions process data in different sizes and formats, from single characters to large data structures. They also provide buffering, which can improve performance. The default size of a stream buffer is 4K. These routines affect only buffers created by the run-time library routines, and have no effect on buffers created by the operating system. -## Stream I/O Routines +## Stream I/O routines -|Routine|Use| -|-------------|---------| -|[`clearerr`](../c-runtime-library/reference/clearerr.md), [`clearerr_s`](../c-runtime-library/reference/clearerr-s.md)|Clear error indicator for stream| -|[`fclose`](../c-runtime-library/reference/fclose-fcloseall.md)|Close stream| -|[`_fcloseall`](../c-runtime-library/reference/fclose-fcloseall.md)|Close all open streams except **`stdin`**, **`stdout`**, and **`stderr`**| -|[`_fdopen`, `wfdopen`](../c-runtime-library/reference/fdopen-wfdopen.md)|Associate stream with file descriptor of open file| -|[`feof`](../c-runtime-library/reference/feof.md)|Test for end of file on stream| -|[`ferror`](../c-runtime-library/reference/ferror.md)|Test for error on stream| -|[`fflush`](../c-runtime-library/reference/fflush.md)|Flush stream to buffer or storage device| -|[`fgetc`, `fgetwc`](../c-runtime-library/reference/fgetc-fgetwc.md)|Read character from stream (function versions of **`getc`** and **`getwc`**)| -|[`_fgetchar`, `_fgetwchar`](../c-runtime-library/reference/fgetc-fgetwc.md)|Read character from **`stdin`** (function versions of **`getchar`** and **`getwchar`**)| -|[`fgetpos`](../c-runtime-library/reference/fgetpos.md)|Get position indicator of stream| -|[`fgets`, `fgetws`](../c-runtime-library/reference/fgets-fgetws.md)|Read string from stream| -|[`_fileno`](../c-runtime-library/reference/fileno.md)|Get file descriptor associated with stream| -|[`_flushall`](../c-runtime-library/reference/flushall.md)|Flush all streams to buffer or storage device| -|[`fopen`, `_wfopen`](../c-runtime-library/reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](../c-runtime-library/reference/fopen-s-wfopen-s.md)|Open stream| -|[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)|Write formatted data to stream| -|[fputc, fputwc](../c-runtime-library/reference/fputc-fputwc.md)|Write a character to a stream (function versions of **`putc`** and **`putwc`**)| -|[`_fputchar`, `_fputwchar`](../c-runtime-library/reference/fputc-fputwc.md)|Write character to **`stdout`** (function versions of **`putchar`** and **`putwchar`**)| -|[`fputs`, `fputws`](../c-runtime-library/reference/fputs-fputws.md)|Write string to stream| -|[`fread`](../c-runtime-library/reference/fread.md)|Read unformatted data from stream| -|[`freopen`, `_wfreopen`](../c-runtime-library/reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](../c-runtime-library/reference/freopen-s-wfreopen-s.md)|Reassign **`FILE`** stream pointer to new file or device| -|[`fscanf`, `fwscanf`](../c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](../c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)|Read formatted data from stream| -|[`fseek`, `_fseeki64`](../c-runtime-library/reference/fseek-fseeki64.md)|Move file position to given location| -|[`fsetpos`](../c-runtime-library/reference/fsetpos.md)|Set position indicator of stream| -|[`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md)|Open stream with file sharing| -|[`ftell`, `_ftelli64`](../c-runtime-library/reference/ftell-ftelli64.md)|Get current file position| -|[`fwrite`](../c-runtime-library/reference/fwrite.md)|Write unformatted data items to stream| -|[`getc`, `getwc`](../c-runtime-library/reference/getc-getwc.md)|Read character from stream (macro versions of **`fgetc`** and **`fgetwc`**)| -|[`getchar`, `getwchar`](../c-runtime-library/reference/getc-getwc.md)|Read character from **`stdin`** (macro versions of **`fgetchar`** and **`fgetwchar`**)| -|[`_getmaxstdio`](../c-runtime-library/reference/getmaxstdio.md)|Returns the number of simultaneously open files permitted at the stream I/O level.| -|[`gets_s`, `_getws_s`](../c-runtime-library/reference/gets-s-getws-s.md)|Read line from **`stdin`**| -|[`_getw`](../c-runtime-library/reference/getw.md)|Read binary **`int`** from stream| -|[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md),[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)|Write formatted data to **`stdout`**| -|[`putc`, `putwc`](../c-runtime-library/reference/putc-putwc.md)|Write character to a stream (macro versions of **`fputc`** and **`fputwc`**)| -|[`putchar`, `putwchar`](../c-runtime-library/reference/putc-putwc.md)|Write character to **`stdout`** (macro versions of **`fputchar`** and **`fputwchar`**)| -|[`puts`, `_putws`](../c-runtime-library/reference/puts-putws.md)|Write line to stream| -|[`_putw`](../c-runtime-library/reference/putw.md)|Write binary **`int`** to stream| -|[`rewind`](../c-runtime-library/reference/rewind.md)|Move file position to beginning of stream| -|[`_rmtmp`](../c-runtime-library/reference/rmtmp.md)|Remove temporary files created by **`tmpfile`**| -|[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md),[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)|Read formatted data from **`stdin`**| -|[`setbuf`](../c-runtime-library/reference/setbuf.md)|Control stream buffering| -|[`_setmaxstdio`](../c-runtime-library/reference/setmaxstdio.md)|Set a maximum for the number of simultaneously open files at the stream I/O level.| -|[`setvbuf`](../c-runtime-library/reference/setvbuf.md)|Control stream buffering and buffer size| -|[`_snprintf`, `_snwprintf`](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md)|Write formatted data of specified length to string| -|[`_snscanf`, `_snwscanf`](../c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md), [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](../c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md)|Read formatted data of a specified length from the standard input stream.| -|[`sprintf`, `swprintf`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md), [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)|Write formatted data to string| -|[`sscanf`, `swscanf`](../c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md), [`sscanf_s`, _sscanf_s_l, `swscanf_s`, `_swscanf_s_l`](../c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)|Read formatted data from string| -|[`_tempnam`, `_wtempnam`](../c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md)|Generate temporary filename in given directory| -|[`tmpfile`](../c-runtime-library/reference/tmpfile.md), [`tmpfile_s`](../c-runtime-library/reference/tmpfile-s.md)|Create temporary file| -|[`tmpnam`, `_wtmpnam`](../c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md), [`tmpnam_s`, `_wtmpnam_s`](../c-runtime-library/reference/tmpnam-s-wtmpnam-s.md)|Generate temporary filename| -|[`ungetc`, `ungetwc`](../c-runtime-library/reference/ungetc-ungetwc.md)|Push character back onto stream| -|[`_vcprintf`, `_vcwprintf`](../c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md), [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](../c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md)|Write formatted data to the console.| -|[`vfprintf`, `vfwprintf`](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](../c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)|Write formatted data to stream| -|[`vprintf`, `vwprintf`](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md), [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](../c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md)|Write formatted data to **`stdout`**| -|[`_vsnprintf`, `_vsnwprintf`](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md), [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md)|Write formatted data of specified length to buffer| -|[`vsprintf`, `vswprintf`](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md), [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)|Write formatted data to buffer| +| Routine | Use | +|---|---| +| [`clearerr`](reference/clearerr.md), [`clearerr_s`](reference/clearerr-s.md) | Clear error indicator for stream | +| [`fclose`](reference/fclose-fcloseall.md) | Close stream | +| [`_fcloseall`](reference/fclose-fcloseall.md) | Close all open streams except **`stdin`**, **`stdout`**, and **`stderr`** | +| [`_fdopen`, `wfdopen`](reference/fdopen-wfdopen.md) | Associate stream with file descriptor of open file | +| [`feof`](reference/feof.md) | Test for end of file on stream | +| [`ferror`](reference/ferror.md) | Test for error on stream | +| [`fflush`](reference/fflush.md) | Flush stream to buffer or storage device | +| [`fgetc`, `fgetwc`](reference/fgetc-fgetwc.md) | Read character from stream (function versions of **`getc`** and **`getwc`**) | +| [`_fgetchar`, `_fgetwchar`](reference/fgetc-fgetwc.md) | Read character from **`stdin`** (function versions of **`getchar`** and **`getwchar`**) | +| [`fgetpos`](reference/fgetpos.md) | Get position indicator of stream | +| [`fgets`, `fgetws`](reference/fgets-fgetws.md) | Read string from stream | +| [`_fileno`](reference/fileno.md) | Get file descriptor associated with stream | +| [`_flushall`](reference/flushall.md) | Flush all streams to buffer or storage device | +| [`fopen`, `_wfopen`](reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](reference/fopen-s-wfopen-s.md) | Open stream | +| [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) | Write formatted data to stream | +| [`fputc`, `fputwc`](reference/fputc-fputwc.md) | Write a character to a stream (function versions of **`putc`** and **`putwc`**) | +| [`_fputchar`, `_fputwchar`](reference/fputc-fputwc.md) | Write character to **`stdout`** (function versions of **`putchar`** and **`putwchar`**) | +| [`fputs`, `fputws`](reference/fputs-fputws.md) | Write string to stream | +| [`fread`](reference/fread.md) | Read unformatted data from stream | +| [`freopen`, `_wfreopen`](reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](reference/freopen-s-wfreopen-s.md) | Reassign `FILE` stream pointer to new file or device | +| [`fscanf`, `fwscanf`](reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) | Read formatted data from stream | +| [`fseek`, `_fseeki64`](reference/fseek-fseeki64.md) | Move file position to given location | +| [`fsetpos`](reference/fsetpos.md) | Set position indicator of stream | +| [`_fsopen`, `_wfsopen`](reference/fsopen-wfsopen.md) | Open stream with file sharing | +| [`ftell`, `_ftelli64`](reference/ftell-ftelli64.md) | Get current file position | +| [`fwrite`](reference/fwrite.md) | Write unformatted data items to stream | +| [`getc`, `getwc`](reference/getc-getwc.md) | Read character from stream (macro versions of **`fgetc`** and **`fgetwc`**) | +| [`getchar`, `getwchar`](reference/getc-getwc.md) | Read character from **`stdin`** (macro versions of **`fgetchar`** and **`fgetwchar`**) | +| [`_getmaxstdio`](reference/getmaxstdio.md) | Returns the number of simultaneously open files permitted at the stream I/O level. | +| [`gets_s`, `_getws_s`](reference/gets-s-getws-s.md) | Read line from **`stdin`** | +| [`_getw`](reference/getw.md) | Read binary **`int`** from stream | +| [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](reference/printf-printf-l-wprintf-wprintf-l.md), [`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) | Write formatted data to **`stdout`** | +| [`putc`, `putwc`](reference/putc-putwc.md) | Write character to a stream (macro versions of **`fputc`** and **`fputwc`**) | +| [`putchar`, `putwchar`](reference/putc-putwc.md) | Write character to **`stdout`** (macro versions of **`fputchar`** and **`fputwchar`**) | +| [`puts`, `_putws`](reference/puts-putws.md) | Write line to stream | +| [`_putw`](reference/putw.md) | Write binary **`int`** to stream | +| [`rewind`](reference/rewind.md) | Move file position to beginning of stream | +| [`_rmtmp`](reference/rmtmp.md) | Remove temporary files created by **`tmpfile`** | +| [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](reference/scanf-scanf-l-wscanf-wscanf-l.md), [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) | Read formatted data from **`stdin`** | +| [`setbuf`](reference/setbuf.md) | Control stream buffering | +| [`_setmaxstdio`](reference/setmaxstdio.md) | Set a maximum for the number of simultaneously open files at the stream I/O level. | +| [`setvbuf`](reference/setvbuf.md) | Control stream buffering and buffer size | +| [`_snprintf`, `_snwprintf`](reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) | Write formatted data of specified length to string | +| [`_snscanf`, `_snwscanf`](reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md), [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md) | Read formatted data of a specified length from the standard input stream. | +| [`sprintf`, `swprintf`](reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md), [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) | Write formatted data to string | +| [`sscanf`, `swscanf`](reference/sscanf-sscanf-l-swscanf-swscanf-l.md), [`sscanf_s`, _sscanf_s_l, `swscanf_s`, `_swscanf_s_l`](reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) | Read formatted data from string | +| [`_tempnam`, `_wtempnam`](reference/tempnam-wtempnam-tmpnam-wtmpnam.md) | Generate temporary filename in given directory | +| [`tmpfile`](reference/tmpfile.md), [`tmpfile_s`](reference/tmpfile-s.md) | Create temporary file | +| [`tmpnam`, `_wtmpnam`](reference/tempnam-wtempnam-tmpnam-wtmpnam.md), [`tmpnam_s`, `_wtmpnam_s`](reference/tmpnam-s-wtmpnam-s.md) | Generate temporary filename | +| [`ungetc`, `ungetwc`](reference/ungetc-ungetwc.md) | Push character back onto stream | +| [`_vcprintf`, `_vcwprintf`](reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md), [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md) | Write formatted data to the console. | +| [`vfprintf`, `vfwprintf`](reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md) | Write formatted data to stream | +| [`vprintf`, `vwprintf`](reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md), [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md) | Write formatted data to **`stdout`** | +| [`_vsnprintf`, `_vsnwprintf`](reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md), [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) | Write formatted data of specified length to buffer | +| [`vsprintf`, `vswprintf`](reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md), [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) | Write formatted data to buffer | When a program begins execution, the startup code automatically opens several streams: standard input (pointed to by **`stdin`**), standard output (pointed to by **`stdout`**), and standard error (pointed to by **`stderr`**). These streams are directed to the console (keyboard and screen) by default. Use **`freopen`** to redirect **`stdin`**, **`stdout`**, or **`stderr`** to a disk file or a device. -Files opened using the stream routines are buffered by default. The **`stdout`** and **`stderr`** functions are flushed whenever they are full or, if you are writing to a character device, after each library call. If a program terminates abnormally, output buffers may not be flushed, resulting in loss of data. Use **`fflush`** or **`_flushall`** to ensure that the buffer associated with a specified file or all open buffers are flushed to the operating system, which can cache data before writing it to disk. The commit-to-disk feature ensures that the flushed buffer contents are not lost in the event of a system failure. +Files opened using the stream routines are buffered by default. The **`stdout`** and **`stderr`** functions are flushed whenever they're full or, if you're writing to a character device, after each library call. If a program terminates abnormally, output buffers may not be flushed, resulting in loss of data. Use **`fflush`** or **`_flushall`** to ensure that the buffer associated with a specified file is flushed to the operating system, or all open buffers are flushed. The operating system can cache data before writing it to disk. The commit-to-disk feature ensures that the flushed buffer contents aren't lost if there's a system failure. There are two ways to commit buffer contents to disk: - Link with the file COMMODE.OBJ to set a global commit flag. The default setting of the global flag is **`n`**, for "no-commit." - - Set the mode flag to **`c`** with **`fopen`** or **`_fdopen`**. Any file specifically opened with either the **`c`** or the **`n`** flag behaves according to the flag, regardless of the state of the global commit/no-commit flag. -If your program does not explicitly close a stream, the stream is automatically closed when the program terminates. However, you should close a stream when your program finishes with it, as the number of streams that can be open at one time is limited. See [`_setmaxstdio`](../c-runtime-library/reference/setmaxstdio.md) for information on this limit. +If your program doesn't explicitly close a stream, the stream is automatically closed when the program terminates. However, you should close a stream when your program finishes with it, as the number of streams that can be open at one time is limited. See [`_setmaxstdio`](reference/setmaxstdio.md) for information on this limit. -Input can follow output directly only with an intervening call to **`fflush`** or to a file-positioning function (**`fseek`**, **`fsetpos`**, or **`rewind`**). Output can follow input without an intervening call to a file-positioning function if the input operation encounters the end of the file. +Input can follow output directly only with an intervening call to **`fflush`** or to a file-positioning function (**`fseek`**, **`fsetpos`**, or **`rewind`**). Input can be followed by output without an intervening call to a file-positioning function, if the input operation encounters the end of the file. ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Input and output](input-and-output.md)\ +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/stream-states.md b/docs/c-runtime-library/stream-states.md index 3acfcd1901..d973da51e1 100644 --- a/docs/c-runtime-library/stream-states.md +++ b/docs/c-runtime-library/stream-states.md @@ -5,36 +5,36 @@ ms.date: "11/19/2018" helpviewer_keywords: ["streams, states"] ms.assetid: 5f28c968-f132-403f-968c-8417ff315e52 --- -# Stream States +# Stream states The valid states, and state transitions, for a stream are shown in the following figure. -![Stream state diagram.](../c-runtime-library/media/stream.gif "Stream state diagram") +![Stream state diagram.](./media/stream.gif "Stream state diagram") Each of the circles denotes a stable state. Each of the lines denotes a transition that can occur as the result of a function call that operates on the stream. Five groups of functions can cause state transitions. Functions in the first three groups are declared in \: -- The byte read functions — [fgetc](../c-runtime-library/reference/fgetc-fgetwc.md), [fgets](../c-runtime-library/reference/fgets-fgetws.md), [fread](../c-runtime-library/reference/fread.md), [fscanf](../c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [getc](../c-runtime-library/reference/getc-getwc.md), [getchar](../c-runtime-library/reference/getc-getwc.md), [gets](../c-runtime-library/gets-getws.md), [scanf](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md), and [ungetc](../c-runtime-library/reference/ungetc-ungetwc.md) +- The byte read functions: [`fgetc`](./reference/fgetc-fgetwc.md), [`fgets`](./reference/fgets-fgetws.md), [`fread`](./reference/fread.md), [`fscanf`](./reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [`getc`](./reference/getc-getwc.md), [`getchar`](./reference/getc-getwc.md), [`gets`](./gets-getws.md), [`scanf`](./reference/scanf-scanf-l-wscanf-wscanf-l.md), and [`ungetc`](./reference/ungetc-ungetwc.md) -- The byte write functions — [fprintf](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [fputc](../c-runtime-library/reference/fputc-fputwc.md), [fputs](../c-runtime-library/reference/fputs-fputws.md), [fwrite](../c-runtime-library/reference/fwrite.md), [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md), [putc](../c-runtime-library/reference/putc-putwc.md), [putchar](../c-runtime-library/reference/putc-putwc.md), [puts](../c-runtime-library/reference/puts-putws.md), [vfprintf](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), and [vprintf](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) +- The byte write functions: [`fprintf`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [`fputc`](./reference/fputc-fputwc.md), [`fputs`](./reference/fputs-fputws.md), [`fwrite`](./reference/fwrite.md), [`printf`](./reference/printf-printf-l-wprintf-wprintf-l.md), [`putc`](./reference/putc-putwc.md), [`putchar`](./reference/putc-putwc.md), [`puts`](./reference/puts-putws.md), [`vfprintf`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), and [`vprintf`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) -- The position functions — [fflush](../c-runtime-library/reference/fflush.md), [fseek](../c-runtime-library/reference/fseek-fseeki64.md), [fsetpos](../c-runtime-library/reference/fsetpos.md), and [rewind](../c-runtime-library/reference/rewind.md) +- The position functions: [`fflush`](./reference/fflush.md), [`fseek`](./reference/fseek-fseeki64.md), [`fsetpos`](./reference/fsetpos.md), and [`rewind`](./reference/rewind.md) Functions in the remaining two groups are declared in \: -- The wide read functions — [fgetwc](../c-runtime-library/reference/fgetc-fgetwc.md), [fgetws](../c-runtime-library/reference/fgets-fgetws.md), [fwscanf](../c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [getwc](../c-runtime-library/reference/getc-getwc.md), [getwchar](../c-runtime-library/reference/getc-getwc.md), [ungetwc](../c-runtime-library/reference/ungetc-ungetwc.md), and [wscanf](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md), +- The wide read functions: [`fgetwc`](./reference/fgetc-fgetwc.md), [`fgetws`](./reference/fgets-fgetws.md), [`fwscanf`](./reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md), [`getwc`](./reference/getc-getwc.md), [`getwchar`](./reference/getc-getwc.md), [`ungetwc`](./reference/ungetc-ungetwc.md), and [`wscanf`](./reference/scanf-scanf-l-wscanf-wscanf-l.md), -- The wide write functions — [fwprintf](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [fputwc](../c-runtime-library/reference/fputc-fputwc.md), [fputws](../c-runtime-library/reference/fputs-fputws.md), [putwc](../c-runtime-library/reference/putc-putwc.md), [putwchar](../c-runtime-library/reference/fputc-fputwc.md), [vfwprintf](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), [vwprintf](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md), and [wprintf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md), +- The wide write functions: [`fwprintf`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md), [`fputwc`](./reference/fputc-fputwc.md), [`fputws`](./reference/fputs-fputws.md), [`putwc`](./reference/putc-putwc.md), [`putwchar`](./reference/fputc-fputwc.md), [`vfwprintf`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md), [`vwprintf`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md), and [`wprintf`](./reference/printf-printf-l-wprintf-wprintf-l.md), The state diagram shows that you must call one of the position functions between most write and read operations: -- You cannot call a read function if the last operation on the stream was a write. +- You can't call a read function if the last operation on the stream was a write. -- You cannot call a write function if the last operation on the stream was a read, unless that read operation set the end-of-file indicator. +- You can't call a write function if the last operation on the stream was a read, unless that read operation set the end-of-file indicator. Finally, the state diagram shows that a position operation never decreases the number of valid function calls that can follow. ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md) +[Files and streams](./files-and-streams.md) diff --git a/docs/c-runtime-library/string-manipulation-crt.md b/docs/c-runtime-library/string-manipulation-crt.md index 5ebb20987b..6ce3a07f7c 100644 --- a/docs/c-runtime-library/string-manipulation-crt.md +++ b/docs/c-runtime-library/string-manipulation-crt.md @@ -5,60 +5,60 @@ ms.date: "11/04/2016" f1_keywords: ["c.strings"] helpviewer_keywords: ["strings [C++], manipulating", "string manipulation", "manipulating strings"] --- -# String Manipulation (CRT) +# String manipulation (CRT) -These routines operate on null-terminated single-byte character, wide-character, and multibyte-character strings. Use the buffer-manipulation routines, described in [Buffer Manipulation](../c-runtime-library/buffer-manipulation.md), to work with character arrays that do not end with a `NULL` character. +These routines operate on null-terminated single-byte character, wide-character, and multibyte-character strings. Use the buffer-manipulation routines, described in [Buffer manipulation](./buffer-manipulation.md), to work with character arrays that don't end with a `NULL` character. -## String-Manipulation Routines +## String-manipulation routines -|Routine|Use| -|-------------|---------| -|[`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md), [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md), [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md), [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Compare two character strings using code page information (**`_mbsicoll`** and **`_mbsnicoll`** are case-insensitive)| -|[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](../c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md)|Move string pointer back one character| -|[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](../c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md)|Advance string pointer by one character| -|[`_mbsnbcat`, `_mbsnbcat_l`](../c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md), [`_mbsnbcat_s`, `_mbsnbcat_s_l`](../c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md)|Append, at most, first *n* bytes of one character string to another| -|[`_mbsnbcmp`, `_mbsnbcmp_l`](../c-runtime-library/reference/mbsnbcmp-mbsnbcmp-l.md)|Compare first *n* bytes of two character strings| -|[`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](../c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)|Return number of character bytes within supplied character count| -|[`_mbsnbcpy`, `_mbsnbcpy_l`](../c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md), [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md)|Copy *n* bytes of string| -|[`_mbsnbicmp`, `_mbsnbicmp_l`](../c-runtime-library/reference/mbsnbicmp-mbsnbicmp-l.md)|Compare *n* bytes of two character strings, ignoring case| -|[`_mbsnbset`, `_mbsnbset_l`](../c-runtime-library/reference/mbsnbset-mbsnbset-l.md)|Set first *n* bytes of character string to specified character| -|[`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](../c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md)|Return number of characters within supplied byte count| -|[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](../c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)|Find next character in string| -|[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](../c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md)|Advance string pointer by *n* characters| -|[`_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l`](../c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md)|Return pointer to first character in given string that is not in another given string| -|[`_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l`](../c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md)|Return the number of characters in a formatted string| -|[`_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l`](../c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md), [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](../c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md)|Read formatted data of a specified length from the standard input stream.| -|[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](../c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md), [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](../c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)|Read formatted data of a specified length from the standard input stream.| -|[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `\__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md), [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md), [`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](../c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)|Write formatted data to a string| -|[`strcat`, `wcscat`, `_mbscat`](../c-runtime-library/reference/strcat-wcscat-mbscat.md), [`strcat_s`, `wcscat_s`, `_mbscat_s`](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)|Append one string to another| -|[`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](../c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md)|Find first occurrence of specified character in string| -|[`strcmp`, `wcscmp`, `_mbscmp`](../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md)|Compare two strings| -|[`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md), [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md), [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md), [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Compare two strings using current locale code page information (**`_stricoll`**, **`_wcsicoll`**, **`_strnicoll`**, and **`_wcsnicoll`** are case-insensitive)| -|[`strcpy`, `wcscpy`, `_mbscpy`](../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md), [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)|Copy one string to another| -|[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](../c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md)|Find first occurrence of character from specified character set in string| -|[`_strdup`, `_wcsdup`, `_mbsdup`](../c-runtime-library/reference/strdup-wcsdup-mbsdup.md), [`_strdup_dbg`, `_wcsdup_dbg`](../c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md)|Duplicate string| -|[`strerror`, `_strerror`, `_wcserror`, `\__wcserror`](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md), [`strerror_s`, `_strerror_s`, `_wcserror_s`, `\__wcserror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)|Map error number to message string| -|[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)|Format date-and-time string| -|[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](../c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)|Compare two strings without regard to case| -|[`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md), [`strnlen`, `strnlen_s`, `wcsnlen`, `wcsnlen_s`, `_mbsnlen`, `_mbsnlen_l`, `_mbstrnlen`, `_mbstrnlen_l`](../c-runtime-library/reference/strnlen-strnlen-s.md)|Find length of string| -|[`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](../c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md), [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](../c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert string to lowercase| -|[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](../c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md), [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)|Append characters of string| -|[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](../c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)|Compare characters of two strings| -|[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](../c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md), [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)|Copy characters of one string to another| -|[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](../c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)|Compare characters of two strings without regard to case| -|[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](../c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)|Set first *n* characters of string to specified character| -|[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](../c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)|Find first occurrence of character from one string in another string| -|[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](../c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)|Find last occurrence of given character in string| -|[`_strrev`, `_wcsrev`, `_mbsrev`, `_mbsrev_l`](../c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md)|Reverse string| -|[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)|Set all characters of string to specified character| -|[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](../c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md)|Find first occurrence in a string of a character not found in another string| -|[`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](../c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md)|Find first occurrence of specified string in another string| -|[`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](../c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md), [`strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l`](../c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md)|Find next token in string| -|[`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](../c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md), [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](../c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert string to uppercase| -|[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form based on locale-specific information| -|[`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `\__vswprintf_l`](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md), [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md), [`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)|Write formatted output using a pointer to a list of arguments| -|[`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md), [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| +| Routine | Use | +|---|---| +| [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md), [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md), [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md), [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | Compare two character strings using code page information (**`_mbsicoll`** and **`_mbsnicoll`** are case-insensitive) | +| [`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](./reference/strdec-wcsdec-mbsdec-mbsdec-l.md) | Move string pointer back one character | +| [`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](./reference/strinc-wcsinc-mbsinc-mbsinc-l.md) | Advance string pointer by one character | +| [`_mbsnbcat`, `_mbsnbcat_l`](./reference/mbsnbcat-mbsnbcat-l.md), [`_mbsnbcat_s`, `_mbsnbcat_s_l`](./reference/mbsnbcat-s-mbsnbcat-s-l.md) | Append, at most, first *n* bytes of one character string to another | +| [`_mbsnbcmp`, `_mbsnbcmp_l`](./reference/mbsnbcmp-mbsnbcmp-l.md) | Compare first *n* bytes of two character strings | +| [`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](./reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md) | Return number of character bytes within supplied character count | +| [`_mbsnbcpy`, `_mbsnbcpy_l`](./reference/mbsnbcpy-mbsnbcpy-l.md), [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](./reference/mbsnbcpy-s-mbsnbcpy-s-l.md) | Copy *n* bytes of string | +| [`_mbsnbicmp`, `_mbsnbicmp_l`](./reference/mbsnbicmp-mbsnbicmp-l.md) | Compare *n* bytes of two character strings, ignoring case | +| [`_mbsnbset`, `_mbsnbset_l`](./reference/mbsnbset-mbsnbset-l.md) | Set first *n* bytes of character string to specified character | +| [`_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l`](./reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md) | Return number of characters within supplied byte count | +| [`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](./reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md) | Find next character in string | +| [`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](./reference/strninc-wcsninc-mbsninc-mbsninc-l.md) | Advance string pointer by *n* characters | +| [`_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l`](./reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md) | Return pointer to first character in given string that isn't in another given string | +| [`_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l`](./reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md) | Return the number of characters in a formatted string | +| [`_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l`](./reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md), [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](./reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md) | Read formatted data of a specified length from the standard input stream. | +| [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](./reference/sscanf-sscanf-l-swscanf-swscanf-l.md), [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](./reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) | Read formatted data of a specified length from the standard input stream. | +| [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md), [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](./reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md), [`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](./reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) | Write formatted data to a string | +| [`strcat`, `wcscat`, `_mbscat`](./reference/strcat-wcscat-mbscat.md), [`strcat_s`, `wcscat_s`, `_mbscat_s`](./reference/strcat-s-wcscat-s-mbscat-s.md) | Append one string to another | +| [`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](./reference/strchr-wcschr-mbschr-mbschr-l.md) | Find first occurrence of specified character in string | +| [`strcmp`, `wcscmp`, `_mbscmp`](./reference/strcmp-wcscmp-mbscmp.md) | Compare two strings | +| [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](./reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md), [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](./reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md), [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](./reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md), [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](./reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | Compare two strings using current locale code page information (**`_stricoll`**, **`_wcsicoll`**, **`_strnicoll`**, and **`_wcsnicoll`** are case-insensitive) | +| [`strcpy`, `wcscpy`, `_mbscpy`](./reference/strcpy-wcscpy-mbscpy.md), [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](./reference/strcpy-s-wcscpy-s-mbscpy-s.md) | Copy one string to another | +| [`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](./reference/strcspn-wcscspn-mbscspn-mbscspn-l.md) | Find first occurrence of character from specified character set in string | +| [`_strdup`, `_wcsdup`, `_mbsdup`](./reference/strdup-wcsdup-mbsdup.md), [`_strdup_dbg`, `_wcsdup_dbg`](./reference/strdup-dbg-wcsdup-dbg.md) | Duplicate string | +| [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](./reference/strerror-strerror-wcserror-wcserror.md), [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) | Map error number to message string | +| [`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](./reference/strftime-wcsftime-strftime-l-wcsftime-l.md) | Format date-and-time string | +| [`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](./reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) | Compare two strings without regard to case | +| [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](./reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md), [`strnlen`, `strnlen_s`, `wcsnlen`, `wcsnlen_s`, `_mbsnlen`, `_mbsnlen_l`, `_mbstrnlen`, `_mbstrnlen_l`](./reference/strnlen-strnlen-s.md) | Find length of string | +| [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](./reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md), [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](./reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) | Convert string to lowercase | +| [`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](./reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md), [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](./reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) | Append characters of string | +| [`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](./reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) | Compare characters of two strings | +| [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](./reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md), [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](./reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) | Copy characters of one string to another | +| [`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](./reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) | Compare characters of two strings without regard to case | +| [`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](./reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) | Set first *n* characters of string to specified character | +| [`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](./reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md) | Find first occurrence of character from one string in another string | +| [`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](./reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) | Find last occurrence of given character in string | +| [`_strrev`, `_wcsrev`, `_mbsrev`, `_mbsrev_l`](./reference/strrev-wcsrev-mbsrev-mbsrev-l.md) | Reverse string | +| [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](./reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) | Set all characters of string to specified character | +| [`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](./reference/strspn-wcsspn-mbsspn-mbsspn-l.md) | Find first occurrence in a string of a character not found in another string | +| [`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](./reference/strstr-wcsstr-mbsstr-mbsstr-l.md) | Find first occurrence of specified string in another string | +| [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](./reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md), [`strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l`](./reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md) | Find next token in string | +| [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](./reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md), [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](./reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) | Convert string to uppercase | +| [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) | Transform string into collated form based on locale-specific information | +| [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md), [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](./reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md), [`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](./reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](./reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md), [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](./reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/string-to-numeric-value-functions.md b/docs/c-runtime-library/string-to-numeric-value-functions.md index 8c699ebf2b..2bc2e86709 100644 --- a/docs/c-runtime-library/string-to-numeric-value-functions.md +++ b/docs/c-runtime-library/string-to-numeric-value-functions.md @@ -1,83 +1,79 @@ --- -description: "Learn more about: String to Numeric Value Functions" -title: "String to Numeric Value Functions" -ms.date: "11/04/2016" -api_location: ["msvcr80.dll", "msvcr110.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_tcstoui64", "_tcstoi64"] +description: "Learn more about: String to numeric value functions" +title: "String to numeric value functions" +ms.date: 05/18/2022 helpviewer_keywords: ["parsing, numeric strings", "string conversion, to numeric values"] ms.assetid: 11cbd9ce-033b-4914-bf66-029070e7e385 --- -# String to Numeric Value Functions +# String to numeric value functions -- [strtod, _strtod_l, wcstod, _wcstod_l](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md) +- [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](./reference/strtod-strtod-l-wcstod-wcstod-l.md) -- [strtol, wcstol, _strtol_l, _wcstol_l](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md) +- [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](./reference/strtol-wcstol-strtol-l-wcstol-l.md) -- [strtoul, _strtoul_l, wcstoul, _wcstoul_l](../c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) +- [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](./reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) -- [_strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l](../c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md) +- [`_strtoi64`, `_wcstoi64`, `_strtoi64_l`, `_wcstoi64_l`](./reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md) -- [_strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l](../c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md) +- [`_strtoui64`, `_wcstoui64`, `_strtoui64_l`, `_wcstoui64_l`](./reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md) ## Remarks -Each function in the **strtod** family converts a null-terminated string to a numeric value. The available functions are listed in the following table. +Each function in the **`strto*`** family converts a null-terminated string to a numeric value. The available functions are listed in the following table. -|Function|Description| -|--------------|-----------------| -|`strtod`|Convert string to double-precision floating point value| -|`strtol`|Convert string to long integer| -|`strtoul`|Convert string to unsigned long integer| -|`_strtoi64`|Convert string to 64-bit **`__int64`** integer| -|`_strtoui64`|Convert string to unsigned 64-bit **`__int64`** integer| +| Function | Description | +|--|--| +| `strtod` | Convert string to double-precision floating point value | +| `strtol` | Convert string to long integer | +| `strtoul` | Convert string to unsigned long integer | +| `_strtoi64` | Convert string to 64-bit `__int64` integer | +| `_strtoui64` | Convert string to unsigned 64-bit `__int64` integer | `wcstod`, `wcstol`, `wcstoul`, and `_wcstoi64` are wide-character versions of `strtod`, `strtol`, `strtoul`, and `_strtoi64`, respectively. The string argument to each of these wide-character functions is a wide-character string; each function behaves identically to its single-byte-character counterpart otherwise. -The `strtod` function takes two arguments: the first is the input string, and the second a pointer to the character which ends the conversion process. `strtol`, `strtoul`, **_strtoi64** and **_strtoui64** take a third argument as the number base to use in the conversion process. +The `strtod` function takes two arguments: the first is the input string, and the second a pointer to the character that ends the conversion process. `strtol`, `strtoul`, `_strtoi64` and `_strtoui64` take a third argument as the number base to use in the conversion process. -The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. Each function stops reading the string at the first character it cannot recognize as part of a number. This may be the terminating null character. For `strtol`, `strtoul`, `_strtoi64`, and `_strtoui64`, this terminating character can also be the first numeric character greater than or equal to the user-supplied number base. +The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. Each function stops reading the string at the first character it can't recognize as part of a number. This character may be the terminating null character. For `strtol`, `strtoul`, `_strtoi64`, and `_strtoui64`, this terminating character can also be the first numeric character greater than or equal to the user-supplied number base. -If the user-supplied pointer to an end-of-conversion character is not set to **NULL** at call time, a pointer to the character that stopped the scan will be stored there instead. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of the string pointer is stored at that address. +If the user-supplied pointer to an end-of-conversion character isn't set to `NULL` or `nullptr` at call time, a pointer to the character that stopped the scan will be stored there instead. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of the string pointer is stored at that address. `strtod` expects a string of the following form: -[*whitespace*] [*sign*] [`digits`] [**.**`digits`] [ {**d** | **D** | **e** | **E**}[*sign*]`digits`] +[*`whitespace`*] [*`sign`*] [`digits`] [**`.`**`digits`] [{**`d`** \| **`D`** \| **`e`** \| **`E`**}[*`sign`*]`digits`] -A *whitespace* may consist of space or tab characters, which are ignored; *sign* is either plus (**+**) or minus (**-**); and `digits` are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**d**, **D**, **e**, or **E**) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan. +A *`whitespace`* may consist of space or tab characters, which are ignored; *`sign`* is either plus (**`+`**) or minus (**`-`**); and `digits` are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**`d`**, **`D`**, **`e`**, or **`E`**) and an optionally signed integer. If no exponent part or radix character appears, a radix character is assumed to follow the last digit in the string. The first character that doesn't fit this form stops the scan. The `strtol`, `strtoul`, `_strtoi64`, and `_strtoui64` functions expect a string of the following form: -[*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [`digits`] +[*`whitespace`*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [`digits`] -If the base argument is between 2 and 36, then it is used as the base of the number. If it is 0, the initial characters referenced to by the end-of-conversion pointer are used to determine the base. If the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer; otherwise, it is interpreted as a decimal number. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. `strtoul` and `_strtoui64` allow a plus (**+**) or minus (**-**) sign prefix; a leading minus sign indicates that the return value is negated. +If the base argument is between 2 and 36, then it's used as the base of the number. If it's 0, the initial characters referenced to by the end-of-conversion pointer are used to determine the base. If the first character is 0 and the second character isn't 'x' or 'X', the string is interpreted as an octal integer; otherwise, it's interpreted as a decimal number. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. `strtoul` and `_strtoui64` allow a plus (**`+`**) or minus (**`-`**) sign prefix; a leading minus sign indicates that the return value is negated. -The output value is affected by the setting of the `LC_NUMERIC` category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The output value is affected by the setting of the `LC_NUMERIC` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. -When the value returned by these functions would cause an overflow or underflow, or when conversion is not possible, special case values are returned as shown: +When the value returned by these functions would cause an overflow or underflow, or when conversion isn't possible, special case values are returned as shown: -|Function|Condition|Value returned| -|--------------|---------------|--------------------| -|`strtod`|Overflow|+/- `HUGE_VAL`| -|`strtod`|Underflow or no conversion|0| -|`strtol`|+ Overflow|**LONG_MAX**| -|`strtol`|- Overflow|**LONG_MIN**| -|`strtol`|Underflow or no conversion|0| -|`_strtoi64`|+ Overflow|**_I64_MAX**| -|`_strtoi64`|- Overflow|**_I64_MIN**| -|`_strtoi64`|No conversion|0| -|`_strtoui64`|Overflow|**_UI64_MAX**| -|`_strtoui64`|No conversion|0| +| Function | Condition | Value returned | +|--|--|--| +| `strtod` | Overflow | +/- `HUGE_VAL` | +| `strtod` | Underflow or no conversion | 0 | +| `strtol` | + Overflow | `LONG_MAX` | +| `strtol` | - Overflow | `LONG_MIN` | +| `strtol` | Underflow or no conversion | 0 | +| `_strtoi64` | + Overflow | `_I64_MAX` | +| `_strtoi64` | - Overflow | `_I64_MIN` | +| `_strtoi64` | No conversion | 0 | +| `_strtoui64` | Overflow | `_UI64_MAX` | +| `_strtoui64` | No conversion | 0 | -**_I64_MAX**, _**I64_MIN**, and **_UI64_MAX** are defined in LIMITS.H. +`_I64_MAX`, `_I64_MIN`, and `_UI64_MAX` are defined in ``. `wcstod`, `wcstol`, `wcstoul`, `_wcstoi64`, and `_wcstoui64` are wide-character versions of `strtod`, `strtol`, `strtoul`, `_strtoi64`, and `_strtoui64`, respectively; the pointer to an end-of-conversion argument to each of these wide-character functions is a wide-character string. Otherwise, each of these wide-character functions behaves identically to its single-byte-character counterpart. ## See also -[Data Conversion](../c-runtime-library/data-conversion.md)
-[Locale](../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Floating-Point Support](../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md) +[Data conversion](./data-conversion.md)\ +[Locale](./locale.md)\ +[Interpretation of multibyte-character sequences](./interpretation-of-multibyte-character-sequences.md)\ +[Math and floating-point support](./floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](./reference/atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/system-calls.md b/docs/c-runtime-library/system-calls.md index d796ab2b9d..050ca9ac2b 100644 --- a/docs/c-runtime-library/system-calls.md +++ b/docs/c-runtime-library/system-calls.md @@ -6,21 +6,21 @@ f1_keywords: ["c.system"] helpviewer_keywords: ["Windows [C++], system calls", "system calls"] ms.assetid: 0255f2ec-a5a0-487e-8b09-9dad001d81ed --- -# System Calls +# System calls The following functions are Windows operating system calls. -## System Call Functions +## System call functions -|Function|Use| -|--------------|---------| -|[`_findclose`](../c-runtime-library/reference/findclose.md)|Release resources from previous find operations| -|[`_findfirst`, `_findfirst32`, `_findfirst64`, `_findfirsti64`, `_findfirst32i64`, `_findfirst64i32`, `_wfindfirst`, `_wfindfirst32`, `_wfindfirst64`, `_wfindfirsti64`, `_wfindfirst32i64`, `_wfindfirst64i32`](../c-runtime-library/reference/findfirst-functions.md)|Find file with specified attributes| -|[`_findnext`, `_findnext32`, `_findnext64`, `_findnexti64`, `_findnext32i64`, `_findnext64i32`, `_wfindnext`, `_wfindnext32`, `_wfindnexti64`, `_wfindnext64`, `_wfindnexti64`](../c-runtime-library/reference/findnext-functions.md)|Find next file with specified attributes| +| Function | Use | +|---|---| +| [`_findclose`](./reference/findclose.md) | Release resources from previous find operations | +| [`_findfirst`, `_findfirst32`, `_findfirst64`, `_findfirsti64`, `_findfirst32i64`, `_findfirst64i32`, `_wfindfirst`, `_wfindfirst32`, `_wfindfirst64`, `_wfindfirsti64`, `_wfindfirst32i64`, `_wfindfirst64i32`](./reference/findfirst-functions.md) | Find file with specified attributes | +| [`_findnext`, `_findnext32`, `_findnext64`, `_findnexti64`, `_findnext32i64`, `_findnext64i32`, `_wfindnext`, `_wfindnext32`, `_wfindnexti64`, `_wfindnext64`, `_wfindnexti64`](./reference/findnext-functions.md) | Find next file with specified attributes | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[File Handling](../c-runtime-library/file-handling.md)
-[Directory Control](../c-runtime-library/directory-control.md)
-[Low-Level I/O](../c-runtime-library/low-level-i-o.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[File handling](./file-handling.md)\ +[Directory control](./directory-control.md)\ +[Low-level I/O](./low-level-i-o.md) diff --git a/docs/c-runtime-library/text-and-binary-mode-file-i-o.md b/docs/c-runtime-library/text-and-binary-mode-file-i-o.md index 14be5d9be9..f21bfaef2a 100644 --- a/docs/c-runtime-library/text-and-binary-mode-file-i-o.md +++ b/docs/c-runtime-library/text-and-binary-mode-file-i-o.md @@ -5,19 +5,19 @@ ms.date: "04/11/2018" helpviewer_keywords: ["files [C++], open functions", "I/O [CRT], text files", "functions [CRT], file access", "binary access, binary mode file I/O", "translation, modes", "I/O [CRT], binary", "text files, I/O", "I/O [CRT], translation modes", "translation modes (file I/O)", "binary access"] ms.assetid: 3196e321-8b87-4609-b302-cd6f3c516051 --- -# Text and Binary Mode File I/O +# Text and binary mode file I/O -File I/O operations take place in one of two translation modes, *text* or *binary*, depending on the mode in which the file is opened. Data files are usually processed in text mode. To control the file translation mode, one can: +File I/O operations take place in one of two translation modes, *text* or *binary*, depending on the mode in which the file is opened. Data files are often processed in text mode. To control the file translation mode, one can: - Retain the current default setting and specify the alternative mode only when you open selected files. -- Use the function [_set_fmode](../c-runtime-library/reference/set-fmode.md) to change the default mode for newly opened files. Use [_get_fmode](../c-runtime-library/reference/get-fmode.md) to find the current default mode. The initial default setting is text mode (**_O_TEXT**). +- Use the function [`_set_fmode`](./reference/set-fmode.md) to change the default mode for newly opened files. Use [`_get_fmode`](./reference/get-fmode.md) to find the current default mode. The initial default setting is ANSI text mode (`_O_TEXT`). -- Change the default translation mode directly by setting the global variable [_fmode](../c-runtime-library/fmode.md) in your program. The function **_set_fmode** sets the value of this variable, but it can also be set directly. +- Change the default translation mode directly by setting the global variable [`_fmode`](./fmode.md) in your program. The function `_set_fmode` sets the value of this variable, but it can also be set directly. -When you call a file-open function such as [_open](../c-runtime-library/reference/open-wopen.md), [fopen](../c-runtime-library/reference/fopen-wfopen.md), [fopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md), [freopen](../c-runtime-library/reference/freopen-wfreopen.md), [freopen_s](../c-runtime-library/reference/freopen-s-wfreopen-s.md), [_fsopen](../c-runtime-library/reference/fsopen-wfsopen.md) or [_sopen_s](../c-runtime-library/reference/sopen-s-wsopen-s.md), you can override the current default setting of **_fmode** by specifying the appropriate argument to the function [_set_fmode](../c-runtime-library/reference/set-fmode.md). The **stdin**, **stdout**, and **stderr** streams always open in text mode by default; you can also override this default when opening any of these files. Use [_setmode](../c-runtime-library/reference/setmode.md) to change the translation mode using the file descriptor after the file is open. +When you call a file-open function such as [`_open`](./reference/open-wopen.md), [`fopen`](./reference/fopen-wfopen.md), [`fopen_s`](./reference/fopen-s-wfopen-s.md), [`freopen`](./reference/freopen-wfreopen.md), [`freopen_s`](./reference/freopen-s-wfreopen-s.md), [`_fsopen`](./reference/fsopen-wfsopen.md) or [`_sopen_s`](./reference/sopen-s-wsopen-s.md), you can override the current default setting of `_fmode` by specifying the appropriate argument to the function [`_set_fmode`](./reference/set-fmode.md). The `stdin`, `stdout`, and `stderr` streams always open in text mode by default; you can also override this default when opening any of these files. Use [`_setmode`](./reference/setmode.md) to change the translation mode using the file descriptor after the file is open. ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Input and output](./input-and-output.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/text-and-binary-streams.md b/docs/c-runtime-library/text-and-binary-streams.md index 75d5b56c8b..5150344ec6 100644 --- a/docs/c-runtime-library/text-and-binary-streams.md +++ b/docs/c-runtime-library/text-and-binary-streams.md @@ -6,27 +6,27 @@ ms.topic: "conceptual" helpviewer_keywords: ["binary streams", "text streams"] ms.assetid: 57035e4a-955d-4e04-a560-fcf67ce68b4e --- -# Text and Binary Streams +# Text and binary streams -A text stream consists of one or more lines of text that can be written to a text-oriented display so that they can be read. When reading from a text stream, the program reads an `NL` (newline) at the end of each line. When writing to a text stream, the program writes an `NL` to signal the end of a line. To match differing conventions among target environments for representing text in files, the library functions can alter the number and representations of characters transmitted between the program and a text stream. +A text stream consists of one or more lines of text that can be written to a text-oriented display so that they can be read. When it reads from a text stream, the program reads a newline at the end of each line. When it writes to a text stream, the program writes a newline to signal the end of a line. To match differing conventions among target environments for representing text in files, the library functions can alter the number and representations of characters transmitted between the program and a text stream. -Positioning within a text stream is limited. You can obtain the current file-position indicator by calling [fgetpos](../c-runtime-library/reference/fgetpos.md) or [ftell](../c-runtime-library/reference/ftell-ftelli64.md). You can position a text stream at a position obtained this way, or at the beginning or end of the stream, by calling [fsetpos](../c-runtime-library/reference/fsetpos.md) or [fseek](../c-runtime-library/reference/fseek-fseeki64.md). Any other change of position might well be not supported. +Positioning within a text stream is limited. You can obtain the current file-position indicator by calling [`fgetpos`](./reference/fgetpos.md) or [`ftell`](./reference/ftell-ftelli64.md). You can position a text stream at a position obtained this way, or at the beginning or end of the stream, by calling [`fsetpos`](./reference/fsetpos.md) or [`fseek`](./reference/fseek-fseeki64.md). Any other change of position might well be not supported. For maximum portability, the program shouldn't write: - Empty files. - Space characters at the end of a line. -- Partial lines (by omitting the `NL` at the end of a file). -- characters other than the printable characters, NL, and `HT` (horizontal tab). +- Partial lines (by omitting the newline at the end of a file). +- Characters other than the printable characters, newline, and horizontal tab. -If you follow these rules, the sequence of characters you read from a text stream (either as byte or multibyte characters) will match the sequence of characters you wrote to the text stream when you created the file. Otherwise, the library functions can remove a file you create if the file is empty when you close it. Or they can alter or delete characters you write to the file. +If you follow these rules, the sequence of characters you read from a text stream will match the sequence of characters you wrote, whether as bytes or as multibyte characters. Otherwise, the library functions can remove a file you create if the file is empty when you close it. Or, they can alter or delete characters you write to the file. -A binary stream consists of one or more bytes of arbitrary information. You can write the value stored in an arbitrary object to a (byte-oriented) binary stream and read exactly what was stored in the object when you wrote it. The library functions don't alter the bytes you transmit between the program and a binary stream. They can, however, append an arbitrary number of `NULL` bytes to the file that you write with a binary stream. The program must deal with these additional `NULL` bytes at the end of the binary stream. +A binary stream consists of one or more bytes of arbitrary information. You can write the value stored in an arbitrary object to a (byte-oriented) binary stream and read exactly what was stored in the object when you wrote it. The library functions don't alter the bytes you transmit between the program and a binary stream. They can, however, append an arbitrary number of `NULL` bytes to the file that you write with a binary stream. The program must deal with these extra `NULL` bytes at the end of the binary stream. -Positioning within a binary stream is well-defined, except for positioning relative to the end of the stream. You can obtain and alter the current file-position indicator the same as for a text stream. The offsets used by [ftell](../c-runtime-library/reference/ftell-ftelli64.md) and [fseek](../c-runtime-library/reference/fseek-fseeki64.md) count bytes from the beginning of the stream (which is byte zero), so integer arithmetic on these offsets yields predictable results. +Positioning within a binary stream is well-defined, except for positioning relative to the end of the stream. You can obtain and alter the current file-position indicator the same as for a text stream. The offsets used by [`ftell`](./reference/ftell-ftelli64.md) and [`fseek`](./reference/fseek-fseeki64.md) count bytes from the beginning of the stream (which is byte zero), so integer arithmetic on these offsets yields predictable results. A byte stream treats a file as a sequence of bytes. Within the program, the stream looks like the same sequence of bytes, except for the possible alterations described above. ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md) +[Files and streams](./files-and-streams.md) diff --git a/docs/c-runtime-library/tgmath.md b/docs/c-runtime-library/tgmath.md index fb33998c7f..dff2a61f16 100644 --- a/docs/c-runtime-library/tgmath.md +++ b/docs/c-runtime-library/tgmath.md @@ -10,7 +10,7 @@ helpviewer_keywords: ["CRT tgmath.h"] For ISO C Standard 11 (C11) and later, the `` header, in addition to including `` and ``, provides macros that invoke a corresponding math function based on the types of the parameters. -C runtime library math functions come in real and complex variants. Each variant comes in three flavors, depending on the type of the argument: `float`, `double`, and `long double`. Because C doesn't support overloading like C++ does, each variant has a different name. For example, to get the absolute value of a real floating-point value, you'd call either `fabsf`, `fabs`, or `fabsl` depending on whether you're passing a `float`, `double`, or `long double` value, respectively. To get the complex absolute value, you'd call one of `cabsf`, `cabs`, or `cabsl` depending on whether you're passing a `float`, `double`, and `long double` complex value, respectively. If the arguments do not match any of the above mentioned types, the function is chosen as though the arguments were doubles. +C runtime library math functions come in real and complex variants. Each variant comes in three flavors, depending on the type of the argument: `float`, `double`, and `long double`. Because C doesn't support overloading like C++ does, each variant has a different name. For example, to get the absolute value of a real floating-point value, you'd call either `fabsf`, `fabs`, or `fabsl` depending on whether you're passing a `float`, `double`, or `long double` value, respectively. To get the complex absolute value, you'd call one of `cabsf`, `cabs`, or `cabsl` depending on whether you're passing a `float`, `double`, and `long double` complex value, respectively. If the arguments don't match any of the above mentioned types, the function is chosen as though the arguments were doubles. `` contains macros that simplify the selection of the right math function to call. The macros examine the type they're passed and then call the right function. For example, the `sqrt` macro binds `sqrt(9.9f)` to `sqrtf()`, but it binds `sqrt(9.9)` to `sqrt()`. If at least one macro argument for a generic parameter is complex, then the macro binds to a complex function; otherwise, it invokes a real function. @@ -20,68 +20,68 @@ These macros are in their own header so that programs written using the `` and what they expand to. `modf` isn't included in this table because it doesn't have a corresponding type-generic macro because it isn't clear how to make it safe without complicating type resolution. -|Macro |Real
`float` | Real
`double` | Real
`long double` | Complex
`float` | Complex
`double` | Complex
`long double` | -|---------|---------|---------|---------|---------|---------|---------| -`acos` | [`acosf`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`acos`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`acosl`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`cacosf`](reference/cacos-cacosf-cacosl.md) | [`cacos`](reference/cacos-cacosf-cacosl.md) | [`cacosl`](reference/cacos-cacosf-cacosl.md) | -`acosh` | [`acoshf`](reference/acosh-acoshf-acoshl.md) | [`acosh`](reference/acosh-acoshf-acoshl.md) | [`acoshl`](reference/acosh-acoshf-acoshl.md) | [`cacoshf`](reference/cacosh-cacoshf-cacoshl.md) | [`cacosh`](reference/cacosh-cacoshf-cacoshl.md) | [`cacoshl`](reference/cacosh-cacoshf-cacoshl.md) | -`asin` | [`asinf`](reference/asin-asinf-asinl.md) | [`asin`](reference/asin-asinf-asinl.md) | [`asinl`](reference/asin-asinf-asinl.md) | [`casinf`](reference/casin-casinf-casinl.md) | [`casin`](reference/casin-casinf-casinl.md) | [`casinl`](reference/casin-casinf-casinl.md) | -`asinh` | [`asinhf`](reference/asin-asinf-asinl.md) | [`asinh`](reference/asin-asinf-asinl.md) | [`asinhl`](reference/asin-asinf-asinl.md) | [`casinhf`](reference/casinh-casinhf-casinhl.md) | [`casinh`](reference/casinh-casinhf-casinhl.md) | [`casinhl`](reference/casinh-casinhf-casinhl.md) | -`atan` | [`atanf`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atanl`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`catanf`](reference/catan-catanf-catanl.md) | [`catan`](reference/catan-catanf-catanl.md) | [`catanl`](reference/catan-catanf-catanl.md) | -`atanh` | [`atanhf`](reference/atanh-atanhf-atanhl.md) | [`atanh`](reference/atanh-atanhf-atanhl.md) | [`atanhl`](reference/atanh-atanhf-atanhl.md) | [`catanhf`](reference/catanh-catanhf-catanhl.md) | [`catanh`](reference/catanh-catanhf-catanhl.md) | [`catanhl`](reference/catanh-catanhf-catanhl.md) | -`cos` | [`cosf`](reference/cos-cosf-cosl.md) | [`cos`](reference/cos-cosf-cosl.md) | [`cosl`](reference/cos-cosf-cosl.md) | [`ccosf`](reference/ccos-ccosf-ccosl.md) | [`ccos`](reference/ccos-ccosf-ccosl.md) | [`ccosl`](reference/ccos-ccosf-ccosl.md) | -`cosh` | [`coshf`](reference/cosh-coshf-coshl.md) | [`cosh`](reference/cosh-coshf-coshl.md) | [`coshl`](reference/cosh-coshf-coshl.md) | [`ccoshf`](reference/ccosh-ccoshf-ccoshl.md) | [`ccosh`](reference/ccosh-ccoshf-ccoshl.md) | [`ccoshl`](reference/ccosh-ccoshf-ccoshl.md) | -`exp` | [`expf`](reference/exp-expf.md) | [`exp`](reference/exp-expf.md) | [`expl`](reference/exp-expf.md) | [`cexpf`](reference/cexp-cexpf-cexpl.md) | [`cexp`](reference/cexp-cexpf-cexpl.md) | [`cexpl`](reference/cexp-cexpf-cexpl.md) | -`fabs` | [`fabsf`](reference/fabs-fabsf-fabsl.md) | [`fabs`](reference/fabs-fabsf-fabsl.md) | [`fabsl`](reference/fabs-fabsf-fabsl.md) | [`cabsf`](reference/cabs-cabsf-cabsl.md) | [`cabs`](reference/cabs-cabsf-cabsl.md) | [`cabsl`](reference/cabs-cabsf-cabsl.md) | -`log` | [`logf`](reference/log-logf-log10-log10f.md) | [`log`](reference/log-logf-log10-log10f.md) | [`logl`](reference/log-logf-log10-log10f.md) | [`clogf`](reference/clog-clogf-clogl.md) | [`clog`](reference/clog-clogf-clogl.md) | [`clogl`](reference/clog-clogf-clogl.md) | -`pow` | [`powf`](reference/pow-powf-powl.md) | [`pow`](reference/pow-powf-powl.md) | [`powl`](reference/pow-powf-powl.md) | [`cpowf`](reference/cpow-cpowf-cpowl.md) | [`cpow`](reference/cpow-cpowf-cpowl.md) | [`cpowl`](reference/cpow-cpowf-cpowl.md) | -`sin` | [`sinf`](reference/sin-sinf-sinl.md) | [`sin`](reference/sin-sinf-sinl.md) | [`sinl`](reference/sin-sinf-sinl.md) | [`csinf`](reference/csin-csinf-csinl.md) | [`csin`](reference/csin-csinf-csinl.md) | [`csinl`](reference/csin-csinf-csinl.md) | -`sinh` | [`sinhf`](reference/sinh-sinhf-sinhl.md) | [`sinh`](reference/sinh-sinhf-sinhl.md) | [`sinhl`](reference/sinh-sinhf-sinhl.md) | [`csinhf`](reference/csinh-csinhf-csinhl.md) | [`csinh`](reference/csinh-csinhf-csinhl.md) | [`csinhl`](reference/csinh-csinhf-csinhl.md) | -`sqrt` | [`sqrtf`](reference/sqrt-sqrtf-sqrtl.md) | [`sqrt`](reference/sqrt-sqrtf-sqrtl.md) | [`sqrtl`](reference/sqrt-sqrtf-sqrtl.md) | [`csqrtf`](reference/csqrt-csqrtf-csqrtl.md) | [`csqrt`](reference/csqrt-csqrtf-csqrtl.md) | [`csqrtl`](reference/csqrt-csqrtf-csqrtl.md) | -`tan` | [`tanf`](reference/tan-tanf-tanl.md) | [`tan`](reference/tan-tanf-tanl.md) | [`tanl`](reference/tan-tanf-tanl.md) | [`ctanf`](reference/ctan-ctanf-ctanl.md) | [`ctan`](reference/ctan-ctanf-ctanl.md) | [`ctanl`](reference/ctan-ctanf-ctanl.md) | -`tanh` | [`tanhf`](reference/tanh-tanhf-tanhl.md) | [`tanh`](reference/tanh-tanhf-tanhl.md) | [`tanhl`](reference/tanh-tanhf-tanhl.md) | [`ctanhf`](reference/ctanh-ctanhf-ctanhl.md) | [`ctanh`](reference/ctanh-ctanhf-ctanhl.md) | [`ctanhl`](reference/ctanh-ctanhf-ctanhl.md) | -`atan2` | [`atan2f`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan2`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan2l`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | - | - | - | -`cbrt` | [`cbrtf`](reference/cbrt-cbrtf-cbrtl.md) | [`cbrt`](reference/cbrt-cbrtf-cbrtl.md) | [`cbrtl`](reference/cbrt-cbrtf-cbrtl.md) | - | - | - | -`ceil` | [`ceilf`](reference/ceil-ceilf-ceill.md) | [`ceil`](reference/ceil-ceilf-ceill.md) | [`ceill`](reference/ceil-ceilf-ceill.md) | - | - | - | -`copysign` | [`copysignf`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | [`copysign`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | [`copysignl`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | - | - | - | -`erf` | [`erff`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erf`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfl`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | - | - | - | -`erfc` | [`erfcf`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfc`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfcl`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | - | - | - | -`exp2` | [`exp2f`](reference/exp2-exp2f-exp2l.md) | [`exp2`](reference/exp2-exp2f-exp2l.md) | [`exp2l`](reference/exp2-exp2f-exp2l.md) | - | - | - | -`expm1` | [`expm1f`](reference/expm1-expm1f-expm1l.md) | [`expm1`](reference/expm1-expm1f-expm1l.md) | [`expm1l`](reference/expm1-expm1f-expm1l.md) | - | - | - | -`fdim` | [`fdimf`](reference/fdim-fdimf-fdiml.md) | [`fdim`](reference/fdim-fdimf-fdiml.md) | [`fdiml`](reference/fdim-fdimf-fdiml.md) | - | - | - | -`floor` | [`floorf`](reference/floor-floorf-floorl.md) | [`floor`](reference/floor-floorf-floorl.md) | [`floorl`](reference/floor-floorf-floorl.md) | - | - | - | -`fma` | [`fmaf`](reference/fma-fmaf-fmal.md) | [`fma`](reference/fma-fmaf-fmal.md) | [`fmal`](reference/fma-fmaf-fmal.md) | - | - | - | -`fmax` | [`fmaxf`](reference/fmax-fmaxf-fmaxl.md) | [`fmax`](reference/fmax-fmaxf-fmaxl.md) | [`fmaxl`](reference/fmax-fmaxf-fmaxl.md) | - | - | - | -`fmin` | [`fminf`](reference/fmin-fminf-fminl.md) | [`fmin`](reference/fmin-fminf-fminl.md) | [`fminl`](reference/fmin-fminf-fminl.md) | - | - | - | -`fmod` | [`fmodf`](reference/fmod-fmodf.md) | [`fmod`](reference/fmod-fmodf.md) | [`fmodl`](reference/fmod-fmodf.md) | - | - | - | -`frexp` | [`frexpf`](reference/frexp.md) | [`frexp`](reference/frexp.md) | [`frexpl`](reference/frexp.md) | - | - | - | -`hypot` | [`hypotf`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | [`hypot`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | [`hypotl`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | - | - | - | -`ilogb` | [`ilogbf`](reference/ilogb-ilogbf-ilogbl2.md) | [`ilogb`](reference/ilogb-ilogbf-ilogbl2.md) | [`ilogbl`](reference/ilogb-ilogbf-ilogbl2.md) | - | - | - | -`ldexp` | [`ldexpf`](reference/ldexp.md) | [`ldexp`](reference/ldexp.md) | [`ldexpl`](reference/ldexp.md) | - | - | - | -`lgamma` | [`lgammaf`](reference/lgamma-lgammaf-lgammal.md) | [`lgamma`](reference/lgamma-lgammaf-lgammal.md) | [`lgammal`](reference/lgamma-lgammaf-lgammal.md) | - | - | - | -`llrint` | [`llrintf`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`llrint`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`llrintl`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | - | - | - | -`llround` | [`llroundf`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`llround`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`llroundl`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | - | - | - | -`log10` | [`log10f`](reference/log-logf-log10-log10f.md) | [`log10`](reference/log-logf-log10-log10f.md) | [`log10l`](reference/log-logf-log10-log10f.md) | - | - | - | -`log1p` | [`log1pf`](reference/log1p-log1pf-log1pl2.md) | [`log1p`](reference/log1p-log1pf-log1pl2.md) | [`log1pl`](reference/log1p-log1pf-log1pl2.md) | - | - | - | -`log2` | [`log2f`](reference/log2-log2f-log2l.md) | [`log2`](reference/log2-log2f-log2l.md) | [`log2l`](reference/log2-log2f-log2l.md) | - | - | - | -`logb` | [`logbf`](reference/logb-logbf-logbl-logb-logbf.md) | [`logb`](reference/logb-logbf-logbl-logb-logbf.md) | [`logbl`](reference/logb-logbf-logbl-logb-logbf.md) | - | - | - | -`lrint` | [`lrintf`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`lrint`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`lrintl`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | - | - | - | -`lround` | [`lroundf`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`lround`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`lroundl`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | - | - | - | -`nearbyint` | [`nearbyintf`](reference/nearbyint-nearbyintf-nearbyintl1.md) | [`nearbyint`](reference/nearbyint-nearbyintf-nearbyintl1.md) | [`nearbyintl`](reference/nearbyint-nearbyintf-nearbyintl1.md) | - | - | - | -`nextafter` | [`nextafterf`](reference/nextafter-functions.md) | [`nextafter`](reference/nextafter-functions.md) | [`nextafterl`](reference/nextafter-functions.md) | - | - | - | -`nexttoward` | [`nexttowardf`](reference/nextafter-functions.md) | [`nexttoward`](reference/nextafter-functions.md) | [`nexttowardl`](reference/nextafter-functions.md) | - | - | - | -`remainder` | [`remainderf`](reference/remainder-remainderf-remainderl.md) | [`remainder`](reference/remainder-remainderf-remainderl.md) | [`remainderl`](reference/remainder-remainderf-remainderl.md) | - | - | - | -`remquo` | [`remquof`](reference/remquo-remquof-remquol.md) | [`remquo`](reference/remquo-remquof-remquol.md) | [`remquol`](reference/remquo-remquof-remquol.md) | - | - | - | -`rint` | [`rintf`](reference/rint-rintf-rintl.md) | [`rint`](reference/rint-rintf-rintl.md) | [`rintl`](reference/rint-rintf-rintl.md) | - | - | - | -`round` | [`roundf`](reference/round-roundf-roundl.md) | [`round`](reference/round-roundf-roundl.md) | [`roundl`](reference/round-roundf-roundl.md) | - | - | - | -`scalbln` | [`scalblnf`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbln`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalblnl`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | - | - | - | -`scalbn` | [`scalbnf`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbn`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbnl`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | - | - | - | -`tgamma` | [`tgammaf`](reference/tgamma-tgammaf-tgammal.md) | [`tgamma`](reference/tgamma-tgammaf-tgammal.md) | [`tgammal`](reference/tgamma-tgammaf-tgammal.md) | - | - | - | -`trunc` | [`truncf`](reference/trunc-truncf-truncl.md) | [`trunc`](reference/trunc-truncf-truncl.md) | [`truncl`](reference/trunc-truncf-truncl.md) | - | - | - | -`carg` | - | - | - | [`cargf`](reference/carg-cargf-cargl.md) | [`carg`](reference/carg-cargf-cargl.md) | [`cargl`](reference/carg-cargf-cargl.md) | -`conj` | - | - | - | [`conjf`](reference/conj-conjf-conjl.md) | [`conj`](reference/conj-conjf-conjl.md) | [`conjl`](reference/conj-conjf-conjl.md) | -`creal` | - | - | - | [`crealf`](reference/creal-crealf-creall.md) | [`creal`](reference/creal-crealf-creall.md) | [`creall`](reference/creal-crealf-creall.md) | -`cimag` | - | - | - | [`cimagf`](reference/cimag-cimagf-cimagl.md) | [`cimag`](reference/cimag-cimagf-cimagl.md) | [`cimagl`](reference/cimag-cimagf-cimagl.md) | -`cproj` | - | - | - | [`cprojf`](reference/cproj-cprojf-cprojl.md) | [`cproj`](reference/cproj-cprojf-cprojl.md) | [`cprojl`](reference/cproj-cprojf-cprojl.md) | +| Macro | Real
`float` | Real
`double` | Real
`long double` | Complex
`float` | Complex
`double` | Complex
`long double` | +|---|---|---|---|---|---|---| +| `acos` | [`acosf`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`acos`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`acosl`](reference/mbsnbicmp-mbsnbicmp-l.md) | [`cacosf`](reference/cacos-cacosf-cacosl.md) | [`cacos`](reference/cacos-cacosf-cacosl.md) | [`cacosl`](reference/cacos-cacosf-cacosl.md) | +| `acosh` | [`acoshf`](reference/acosh-acoshf-acoshl.md) | [`acosh`](reference/acosh-acoshf-acoshl.md) | [`acoshl`](reference/acosh-acoshf-acoshl.md) | [`cacoshf`](reference/cacosh-cacoshf-cacoshl.md) | [`cacosh`](reference/cacosh-cacoshf-cacoshl.md) | [`cacoshl`](reference/cacosh-cacoshf-cacoshl.md) | +| `asin` | [`asinf`](reference/asin-asinf-asinl.md) | [`asin`](reference/asin-asinf-asinl.md) | [`asinl`](reference/asin-asinf-asinl.md) | [`casinf`](reference/casin-casinf-casinl.md) | [`casin`](reference/casin-casinf-casinl.md) | [`casinl`](reference/casin-casinf-casinl.md) | +| `asinh` | [`asinhf`](reference/asin-asinf-asinl.md) | [`asinh`](reference/asin-asinf-asinl.md) | [`asinhl`](reference/asin-asinf-asinl.md) | [`casinhf`](reference/casinh-casinhf-casinhl.md) | [`casinh`](reference/casinh-casinhf-casinhl.md) | [`casinhl`](reference/casinh-casinhf-casinhl.md) | +| `atan` | [`atanf`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atanl`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`catanf`](reference/catan-catanf-catanl.md) | [`catan`](reference/catan-catanf-catanl.md) | [`catanl`](reference/catan-catanf-catanl.md) | +| `atanh` | [`atanhf`](reference/atanh-atanhf-atanhl.md) | [`atanh`](reference/atanh-atanhf-atanhl.md) | [`atanhl`](reference/atanh-atanhf-atanhl.md) | [`catanhf`](reference/catanh-catanhf-catanhl.md) | [`catanh`](reference/catanh-catanhf-catanhl.md) | [`catanhl`](reference/catanh-catanhf-catanhl.md) | +| `cos` | [`cosf`](reference/cos-cosf-cosl.md) | [`cos`](reference/cos-cosf-cosl.md) | [`cosl`](reference/cos-cosf-cosl.md) | [`ccosf`](reference/ccos-ccosf-ccosl.md) | [`ccos`](reference/ccos-ccosf-ccosl.md) | [`ccosl`](reference/ccos-ccosf-ccosl.md) | +| `cosh` | [`coshf`](reference/cosh-coshf-coshl.md) | [`cosh`](reference/cosh-coshf-coshl.md) | [`coshl`](reference/cosh-coshf-coshl.md) | [`ccoshf`](reference/ccosh-ccoshf-ccoshl.md) | [`ccosh`](reference/ccosh-ccoshf-ccoshl.md) | [`ccoshl`](reference/ccosh-ccoshf-ccoshl.md) | +| `exp` | [`expf`](reference/exp-expf.md) | [`exp`](reference/exp-expf.md) | [`expl`](reference/exp-expf.md) | [`cexpf`](reference/cexp-cexpf-cexpl.md) | [`cexp`](reference/cexp-cexpf-cexpl.md) | [`cexpl`](reference/cexp-cexpf-cexpl.md) | +| `fabs` | [`fabsf`](reference/fabs-fabsf-fabsl.md) | [`fabs`](reference/fabs-fabsf-fabsl.md) | [`fabsl`](reference/fabs-fabsf-fabsl.md) | [`cabsf`](reference/cabs-cabsf-cabsl.md) | [`cabs`](reference/cabs-cabsf-cabsl.md) | [`cabsl`](reference/cabs-cabsf-cabsl.md) | +| `log` | [`logf`](reference/log-logf-log10-log10f.md) | [`log`](reference/log-logf-log10-log10f.md) | [`logl`](reference/log-logf-log10-log10f.md) | [`clogf`](reference/clog-clogf-clogl.md) | [`clog`](reference/clog-clogf-clogl.md) | [`clogl`](reference/clog-clogf-clogl.md) | +| `pow` | [`powf`](reference/pow-powf-powl.md) | [`pow`](reference/pow-powf-powl.md) | [`powl`](reference/pow-powf-powl.md) | [`cpowf`](reference/cpow-cpowf-cpowl.md) | [`cpow`](reference/cpow-cpowf-cpowl.md) | [`cpowl`](reference/cpow-cpowf-cpowl.md) | +| `sin` | [`sinf`](reference/sin-sinf-sinl.md) | [`sin`](reference/sin-sinf-sinl.md) | [`sinl`](reference/sin-sinf-sinl.md) | [`csinf`](reference/csin-csinf-csinl.md) | [`csin`](reference/csin-csinf-csinl.md) | [`csinl`](reference/csin-csinf-csinl.md) | +| `sinh` | [`sinhf`](reference/sinh-sinhf-sinhl.md) | [`sinh`](reference/sinh-sinhf-sinhl.md) | [`sinhl`](reference/sinh-sinhf-sinhl.md) | [`csinhf`](reference/csinh-csinhf-csinhl.md) | [`csinh`](reference/csinh-csinhf-csinhl.md) | [`csinhl`](reference/csinh-csinhf-csinhl.md) | +| `sqrt` | [`sqrtf`](reference/sqrt-sqrtf-sqrtl.md) | [`sqrt`](reference/sqrt-sqrtf-sqrtl.md) | [`sqrtl`](reference/sqrt-sqrtf-sqrtl.md) | [`csqrtf`](reference/csqrt-csqrtf-csqrtl.md) | [`csqrt`](reference/csqrt-csqrtf-csqrtl.md) | [`csqrtl`](reference/csqrt-csqrtf-csqrtl.md) | +| `tan` | [`tanf`](reference/tan-tanf-tanl.md) | [`tan`](reference/tan-tanf-tanl.md) | [`tanl`](reference/tan-tanf-tanl.md) | [`ctanf`](reference/ctan-ctanf-ctanl.md) | [`ctan`](reference/ctan-ctanf-ctanl.md) | [`ctanl`](reference/ctan-ctanf-ctanl.md) | +| `tanh` | [`tanhf`](reference/tanh-tanhf-tanhl.md) | [`tanh`](reference/tanh-tanhf-tanhl.md) | [`tanhl`](reference/tanh-tanhf-tanhl.md) | [`ctanhf`](reference/ctanh-ctanhf-ctanhl.md) | [`ctanh`](reference/ctanh-ctanhf-ctanhl.md) | [`ctanhl`](reference/ctanh-ctanhf-ctanhl.md) | +| `atan2` | [`atan2f`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan2`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | [`atan2l`](reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | - | - | - | +| `cbrt` | [`cbrtf`](reference/cbrt-cbrtf-cbrtl.md) | [`cbrt`](reference/cbrt-cbrtf-cbrtl.md) | [`cbrtl`](reference/cbrt-cbrtf-cbrtl.md) | - | - | - | +| `ceil` | [`ceilf`](reference/ceil-ceilf-ceill.md) | [`ceil`](reference/ceil-ceilf-ceill.md) | [`ceill`](reference/ceil-ceilf-ceill.md) | - | - | - | +| `copysign` | [`copysignf`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | [`copysign`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | [`copysignl`](reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | - | - | - | +| `erf` | [`erff`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erf`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfl`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | - | - | - | +| `erfc` | [`erfcf`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfc`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | [`erfcl`](reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | - | - | - | +| `exp2` | [`exp2f`](reference/exp2-exp2f-exp2l.md) | [`exp2`](reference/exp2-exp2f-exp2l.md) | [`exp2l`](reference/exp2-exp2f-exp2l.md) | - | - | - | +| `expm1` | [`expm1f`](reference/expm1-expm1f-expm1l.md) | [`expm1`](reference/expm1-expm1f-expm1l.md) | [`expm1l`](reference/expm1-expm1f-expm1l.md) | - | - | - | +| `fdim` | [`fdimf`](reference/fdim-fdimf-fdiml.md) | [`fdim`](reference/fdim-fdimf-fdiml.md) | [`fdiml`](reference/fdim-fdimf-fdiml.md) | - | - | - | +| `floor` | [`floorf`](reference/floor-floorf-floorl.md) | [`floor`](reference/floor-floorf-floorl.md) | [`floorl`](reference/floor-floorf-floorl.md) | - | - | - | +| `fma` | [`fmaf`](reference/fma-fmaf-fmal.md) | [`fma`](reference/fma-fmaf-fmal.md) | [`fmal`](reference/fma-fmaf-fmal.md) | - | - | - | +| `fmax` | [`fmaxf`](reference/fmax-fmaxf-fmaxl.md) | [`fmax`](reference/fmax-fmaxf-fmaxl.md) | [`fmaxl`](reference/fmax-fmaxf-fmaxl.md) | - | - | - | +| `fmin` | [`fminf`](reference/fmin-fminf-fminl.md) | [`fmin`](reference/fmin-fminf-fminl.md) | [`fminl`](reference/fmin-fminf-fminl.md) | - | - | - | +| `fmod` | [`fmodf`](reference/fmod-fmodf.md) | [`fmod`](reference/fmod-fmodf.md) | [`fmodl`](reference/fmod-fmodf.md) | - | - | - | +| `frexp` | [`frexpf`](reference/frexp.md) | [`frexp`](reference/frexp.md) | [`frexpl`](reference/frexp.md) | - | - | - | +| `hypot` | [`hypotf`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | [`hypot`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | [`hypotl`](reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | - | - | - | +| `ilogb` | [`ilogbf`](reference/ilogb-ilogbf-ilogbl2.md) | [`ilogb`](reference/ilogb-ilogbf-ilogbl2.md) | [`ilogbl`](reference/ilogb-ilogbf-ilogbl2.md) | - | - | - | +| `ldexp` | [`ldexpf`](reference/ldexp.md) | [`ldexp`](reference/ldexp.md) | [`ldexpl`](reference/ldexp.md) | - | - | - | +| `lgamma` | [`lgammaf`](reference/lgamma-lgammaf-lgammal.md) | [`lgamma`](reference/lgamma-lgammaf-lgammal.md) | [`lgammal`](reference/lgamma-lgammaf-lgammal.md) | - | - | - | +| `llrint` | [`llrintf`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`llrint`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`llrintl`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | - | - | - | +| `llround` | [`llroundf`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`llround`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`llroundl`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | - | - | - | +| `log10` | [`log10f`](reference/log-logf-log10-log10f.md) | [`log10`](reference/log-logf-log10-log10f.md) | [`log10l`](reference/log-logf-log10-log10f.md) | - | - | - | +| `log1p` | [`log1pf`](reference/log1p-log1pf-log1pl2.md) | [`log1p`](reference/log1p-log1pf-log1pl2.md) | [`log1pl`](reference/log1p-log1pf-log1pl2.md) | - | - | - | +| `log2` | [`log2f`](reference/log2-log2f-log2l.md) | [`log2`](reference/log2-log2f-log2l.md) | [`log2l`](reference/log2-log2f-log2l.md) | - | - | - | +| `logb` | [`logbf`](reference/logb-logbf-logbl-logb-logbf.md) | [`logb`](reference/logb-logbf-logbl-logb-logbf.md) | [`logbl`](reference/logb-logbf-logbl-logb-logbf.md) | - | - | - | +| `lrint` | [`lrintf`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`lrint`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | [`lrintl`](reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | - | - | - | +| `lround` | [`lroundf`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`lround`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | [`lroundl`](reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | - | - | - | +| `nearbyint` | [`nearbyintf`](reference/nearbyint-nearbyintf-nearbyintl1.md) | [`nearbyint`](reference/nearbyint-nearbyintf-nearbyintl1.md) | [`nearbyintl`](reference/nearbyint-nearbyintf-nearbyintl1.md) | - | - | - | +| `nextafter` | [`nextafterf`](reference/nextafter-functions.md) | [`nextafter`](reference/nextafter-functions.md) | [`nextafterl`](reference/nextafter-functions.md) | - | - | - | +| `nexttoward` | [`nexttowardf`](reference/nextafter-functions.md) | [`nexttoward`](reference/nextafter-functions.md) | [`nexttowardl`](reference/nextafter-functions.md) | - | - | - | +| `remainder` | [`remainderf`](reference/remainder-remainderf-remainderl.md) | [`remainder`](reference/remainder-remainderf-remainderl.md) | [`remainderl`](reference/remainder-remainderf-remainderl.md) | - | - | - | +| `remquo` | [`remquof`](reference/remquo-remquof-remquol.md) | [`remquo`](reference/remquo-remquof-remquol.md) | [`remquol`](reference/remquo-remquof-remquol.md) | - | - | - | +| `rint` | [`rintf`](reference/rint-rintf-rintl.md) | [`rint`](reference/rint-rintf-rintl.md) | [`rintl`](reference/rint-rintf-rintl.md) | - | - | - | +| `round` | [`roundf`](reference/round-roundf-roundl.md) | [`round`](reference/round-roundf-roundl.md) | [`roundl`](reference/round-roundf-roundl.md) | - | - | - | +| `scalbln` | [`scalblnf`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbln`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalblnl`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | - | - | - | +| `scalbn` | [`scalbnf`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbn`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | [`scalbnl`](reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | - | - | - | +| `tgamma` | [`tgammaf`](reference/tgamma-tgammaf-tgammal.md) | [`tgamma`](reference/tgamma-tgammaf-tgammal.md) | [`tgammal`](reference/tgamma-tgammaf-tgammal.md) | - | - | - | +| `trunc` | [`truncf`](reference/trunc-truncf-truncl.md) | [`trunc`](reference/trunc-truncf-truncl.md) | [`truncl`](reference/trunc-truncf-truncl.md) | - | - | - | +| `carg` | - | - | - | [`cargf`](reference/carg-cargf-cargl.md) | [`carg`](reference/carg-cargf-cargl.md) | [`cargl`](reference/carg-cargf-cargl.md) | +| `conj` | - | - | - | [`conjf`](reference/conj-conjf-conjl.md) | [`conj`](reference/conj-conjf-conjl.md) | [`conjl`](reference/conj-conjf-conjl.md) | +| `creal` | - | - | - | [`crealf`](reference/creal-crealf-creall.md) | [`creal`](reference/creal-crealf-creall.md) | [`creall`](reference/creal-crealf-creall.md) | +| `cimag` | - | - | - | [`cimagf`](reference/cimag-cimagf-cimagl.md) | [`cimag`](reference/cimag-cimagf-cimagl.md) | [`cimagl`](reference/cimag-cimagf-cimagl.md) | +| `cproj` | - | - | - | [`cprojf`](reference/cproj-cprojf-cprojl.md) | [`cproj`](reference/cproj-cprojf-cprojl.md) | [`cprojl`](reference/cproj-cprojf-cprojl.md) | ## Requirements diff --git a/docs/c-runtime-library/time-management.md b/docs/c-runtime-library/time-management.md index c2fc597da4..619798b3cc 100644 --- a/docs/c-runtime-library/time-management.md +++ b/docs/c-runtime-library/time-management.md @@ -1,43 +1,42 @@ --- -description: "Learn more about: Time Management" title: "Time Management" -ms.date: "11/04/2016" +description: "Learn more about: Time Management" +ms.date: 11/04/2016 helpviewer_keywords: ["dates, run-time library members", "time, time management", "date functions", "time functions"] -ms.assetid: 93599220-c011-45d5-978f-12182abfdd2f --- -# Time Management +# Time management Use these functions to get the current time and convert, adjust, and store it as necessary. The current time is the system time. -The **_ftime** and **localtime** routines use the **TZ** environment variable. If **TZ** is not set, the run-time library attempts to use the time-zone information specified by the operating system. If this information is unavailable, these functions use the default value of PST8PDT. For more information on **TZ**, see [_tzset](../c-runtime-library/reference/tzset.md); also see [_daylight, timezone, and _tzname](../c-runtime-library/daylight-dstbias-timezone-and-tzname.md). - -### Time Routines - -|Function|Use| -|--------------|---------| -|[asctime, _wasctime](../c-runtime-library/reference/asctime-wasctime.md), [asctime_s, _wasctime_s](../c-runtime-library/reference/asctime-s-wasctime-s.md)|Convert time from type **struct tm** to character string. The versions of these functions with the **_s** suffix are more secure.| -|[clock](../c-runtime-library/reference/clock.md)|Return elapsed wall-clock time for process.| -|[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [_ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)|Convert time from type **time_t**, **__time32_t** or **__time64_t** to character string. The versions of these functions with the **_s** suffix are more secure.| -|[difftime, _difftime32, _difftime64](../c-runtime-library/reference/difftime-difftime32-difftime64.md)|Compute difference between two times.| -|[_ftime, _ftime32, _ftime64](../c-runtime-library/reference/ftime-ftime32-ftime64.md),[_ftime_s, _ftime32_s, _ftime64_s](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md)|Store current system time in variable of type **struct _timeb** or type **struct __timeb64** The versions of these functions with the **_s** suffix are more secure.| -|[_futime, _futime32, _futime64](../c-runtime-library/reference/futime-futime32-futime64.md)|Set modification time on open file| -|[gmtime, _gmtime32, _gmtime64](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md), [gmtime_s, _gmtime32_s, _gmtime64_s](../c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md)|Convert time from type **time_t** to **struct tm** or from type **__time64_t** to **struct tm**.The versions of these functions with the **_s** suffix are more secure.| -|[localtime, _localtime32, _localtime64](../c-runtime-library/reference/localtime-localtime32-localtime64.md), [localtime_s, _localtime32_s, _localtime64_s](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md)|Convert time from type **time_t** to **struct tm** or from type **__time64_t** to **struct tm** with local correction. The versions of these functions with the **_s** suffix are more secure.| -|[_mkgmtime, _mkgmtime32, _mkgmtime64](../c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md)|Convert time to calendar value in Greenwich Mean Time.| -|[mktime, _mktime32, _mktime64](../c-runtime-library/reference/mktime-mktime32-mktime64.md)|Convert time to calendar value.| -|[_strdate, _wstrdate](../c-runtime-library/reference/strdate-wstrdate.md), [_strdate_s, _wstrdate_s](../c-runtime-library/reference/strdate-s-wstrdate-s.md)|Return current system date as string. The versions of these functions with the **_s** suffix are more secure.| -|[strftime, wcsftime, _strftime_l, _wcsftime_l](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)|Format date-and-time string for international use.| -|[_strtime, _wstrtime](../c-runtime-library/reference/strtime-wstrtime.md), [_strtime_s, _wstrtime_s](../c-runtime-library/reference/strtime-s-wstrtime-s.md)|Return current system time as string. The versions of these functions with the **_s** suffix are more secure.| -|[time, _time32, _time64](../c-runtime-library/reference/time-time32-time64.md)|Get current system time as type **time_t**, **__time32_t** or as type **__time64_t**.| -|[_tzset](../c-runtime-library/reference/tzset.md)|Set external time variables from environment time variable **TZ**.| -|[_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md)|Set modification time for specified file using either current time or time value stored in structure.| +The **`_ftime`** and **`localtime`** routines use the **`TZ`** environment variable. If **`TZ`** isn't set, the run-time library attempts to use the time-zone information specified by the operating system. If this information is unavailable, these functions use the default value of PST8PDT. For more information on **`TZ`**, see [`_tzset`](reference/tzset.md); also see [`_daylight`, `timezone`, and `_tzname`](daylight-dstbias-timezone-and-tzname.md). + +### Time routines + +| Function | Use | +|---|---| +| [`asctime`, `_wasctime`](reference/asctime-wasctime.md), [`asctime_s`, `_wasctime_s`](reference/asctime-s-wasctime-s.md) | Convert time from type **`struct tm`** to character string. The versions of these functions with the **`_s`** suffix are more secure. | +| [`clock`](reference/clock.md) | Return elapsed wall-clock time for process. | +| [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md), [`_ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md) | Convert time from type **`time_t`**, **`__time32_t`** or **`__time64_t`** to character string. The versions of these functions with the **`_s`** suffix are more secure. | +| [`difftime`, `_difftime32`, `_difftime64`](reference/difftime-difftime32-difftime64.md) | Compute difference between two times. | +| [`_ftime`, `_ftime32`, `_ftime64`](reference/ftime-ftime32-ftime64.md), [`_ftime_s`, `_ftime32_s`, _ftime64_s](reference/ftime-s-ftime32-s-ftime64-s.md) | Store current system time in variable of type **`struct _timeb`** or type **`struct __timeb64`** The versions of these functions with the **`_s`** suffix are more secure. | +| [`_futime`, `_futime32`, `_futime64`](reference/futime-futime32-futime64.md) | Set modification time on open file | +| [`gmtime`, `_gmtime32`, `_gmtime64`](reference/gmtime-gmtime32-gmtime64.md), [`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](reference/gmtime-s-gmtime32-s-gmtime64-s.md) | Convert time from type **`time_t`** to **`struct tm`** or from type **`__time64_t`** to **`struct tm`**. The versions of these functions with the **`_s`** suffix are more secure. | +| [`localtime`, `_localtime32`, `_localtime64`](reference/localtime-localtime32-localtime64.md), [`localtime_s`, `_localtime32_s`, `_localtime64_s`](reference/localtime-s-localtime32-s-localtime64-s.md) | Convert time from type **`time_t`** to **`struct tm`** or from type **`__time64_t`** to **`struct tm`** with local correction. The versions of these functions with the **`_s`** suffix are more secure. | +| [`_mkgmtime`, `_mkgmtime32`, `_mkgmtime64`](reference/mkgmtime-mkgmtime32-mkgmtime64.md) | Convert time to calendar value in Greenwich Mean Time. | +| [`mktime`, `_mktime32`, `_mktime64`](reference/mktime-mktime32-mktime64.md) | Convert time to calendar value. | +| [`_strdate`, `_wstrdate`](reference/strdate-wstrdate.md), [`_strdate_s`, `_wstrdate_s`](reference/strdate-s-wstrdate-s.md) | Return current system date as string. The versions of these functions with the **`_s`** suffix are more secure. | +| [`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](reference/strftime-wcsftime-strftime-l-wcsftime-l.md) | Format date-and-time string for international use. | +| [`_strtime`, `_wstrtime`](reference/strtime-wstrtime.md), [`_strtime_s`, `_wstrtime_s`](reference/strtime-s-wstrtime-s.md) | Return current system time as string. The versions of these functions with the **`_s`** suffix are more secure. | +| [`time`, `_time32`, `_time64`](reference/time-time32-time64.md) | Get current system time as type **`time_t`**, **`__time32_t`** or as type **`__time64_t`**. | +| [`_tzset`](reference/tzset.md) | Set external time variables from environment time variable **`TZ`**. | +| [`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) | Set modification time for specified file using either current time or time value stored in structure. | > [!NOTE] -> In all versions of Microsoft C/C++ except Microsoft C/C++ version 7.0, and in all versions of Visual C++, the time function returns the current time as the number of seconds elapsed since midnight on January 1, 1970. In Microsoft C/C++ version 7.0, **time** returned the current time as the number of seconds elapsed since midnight on December 31, 1899. +> In all versions of Microsoft C/C++ except Microsoft C/C++ version 7.0, and in all versions of Visual C++, the time function returns the current time as the number of seconds elapsed since midnight on January 1, 1970. In Microsoft C/C++ version 7.0, **`time`** returned the current time as the number of seconds elapsed since midnight on December 31, 1899. > [!NOTE] -> In versions of Visual C++ and Microsoft C/C++ before Visual Studio 2005, **time_t** was a **`long int`** (32 bits) and hence could not be used for dates past 3:14:07 January 19, 2038, UTC. **time_t** is now equivalent to **__time64_t** by default, but defining **_USE_32BIT_TIME_T** changes **time_t** to **__time32_t** and forces many time functions to call versions that take the 32-bit **time_t**. For more information, see [Standard Types](../c-runtime-library/standard-types.md) and comments in the documentation for the individual time functions. +> In versions of Visual C++ and Microsoft C/C++ before Visual Studio 2005, **`time_t`** was a **`long int`** (32 bits) and hence could not be used for dates past 3:14:07 January 19, 2038, UTC. **`time_t`** is now equivalent to **`__time64_t`** by default, but defining `_USE_32BIT_TIME_T` changes **`time_t`** to **`__time32_t`** and forces many time functions to call versions that take the 32-bit **`time_t`**. For more information, see [Standard types](standard-types.md) and comments in the documentation for the individual time functions. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/tmp-max-l-tmpnam.md b/docs/c-runtime-library/tmp-max-l-tmpnam.md index ffdb4b615b..7e323d2ed0 100644 --- a/docs/c-runtime-library/tmp-max-l-tmpnam.md +++ b/docs/c-runtime-library/tmp-max-l-tmpnam.md @@ -2,22 +2,22 @@ description: "Learn more about: TMP_MAX, L_tmpnam" title: "TMP_MAX, L_tmpnam" ms.date: "11/04/2016" -f1_keywords: ["TMP_MAX", "L_tmpnam"] +f1_keywords: ["STDIO/TMP_MAX", "STDIO/TMP_MAX_S", "STDIO/_TMP_MAX_S", "STDIO/L_tmpnam", "TMP_MAX", "TMP_MAX_S", "_TMP_MAX_S", "L_tmpnam"] helpviewer_keywords: ["temporary files, length", "L_tmpnam constant", "TMP_MAX constant"] ms.assetid: ab19fd0c-b5b7-49f7-b23d-da9dfbcf0c1f --- -# TMP_MAX, L_tmpnam +# `TMP_MAX`, `L_tmpnam` ## Syntax -``` +```C #include ``` ## Remarks -`TMP_MAX` is the maximum number of unique filenames that the `tmpnam` function can generate. `L_tmpnam` is the length of temporary filenames generated by `tmpnam`. +`TMP_MAX` is the maximum number of unique filenames that the `tmpnam` function can generate. `L_tmpnam` is the length of temporary filenames generated by `tmpnam`. For more information, see [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](./reference/tempnam-wtempnam-tmpnam-wtmpnam.md). `TMP_MAX_S` and `_TMP_MAX_S` are synonyms of `TMP_MAX` for use with the related secure functions [`tmpnam_s`, `_wtmpnam_s`](./reference/tmpnam-s-wtmpnam-s.md). ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/to-functions.md b/docs/c-runtime-library/to-functions.md index e2fe50deed..3cd86e5a53 100644 --- a/docs/c-runtime-library/to-functions.md +++ b/docs/c-runtime-library/to-functions.md @@ -1,59 +1,50 @@ --- description: "Learn more about: to Functions" title: "to Functions" -ms.date: "11/04/2016" -api_location: ["msvcr120.dll", "msvcr90.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcr100.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["To"] +ms.date: 06/15/2023 helpviewer_keywords: ["to functions", "string conversion, to different characters", "string conversion, case", "lowercase, converting strings", "uppercase, converting strings", "case, converting", "characters, converting"] -ms.assetid: f636a4c6-8c9f-4be2-baac-064f9dbae300 --- -# to Functions +# `to` functions -Each of the **to** functions and its associated macro, if any, converts a single character to another character. +Each of the **`to`** functions and its associated macro, if any, converts a single character to another character. -[__toascii](../c-runtime-library/reference/toascii-toascii.md)\ -[tolower, _tolower, towlower](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md)\ -[toupper, _toupper, towupper](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md) +[`__toascii`](./reference/toascii-toascii.md)\ +[`tolower`, `_tolower`, `towlower`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md)\ +[`toupper`, `_toupper`, `towupper`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md) ## Remarks -The **to** functions and macro conversions are as follows. +The **`to`** functions and macro conversions are as follows. -|Routine|Macro|Description| -|-------------|-----------|-----------------| -|`__toascii`|`__toascii`|Converts `c` to ASCII character| -|`tolower`|`tolower`|Converts `c` to lowercase if appropriate| -|`_tolower`|`_tolower`|Converts `c` to lowercase| -|`towlower`|None|Converts `c` to corresponding wide-character lowercase letter| -|`toupper`|`toupper`|Converts `c` to uppercase if appropriate| -|`_toupper`|`_toupper`|Converts `c` to uppercase| -|`towupper`|None|Converts c to corresponding wide-character uppercase letter| +| Routine | Macro | Description | +|---|---|---| +| `__toascii` | `__toascii` | Converts `c` to ASCII character | +| `tolower` | `tolower` | Converts `c` to lowercase if appropriate | +| `_tolower` | `_tolower` | Converts `c` to lowercase | +| `towlower` | None | Converts `c` to corresponding wide-character lowercase letter | +| `toupper` | `toupper` | Converts `c` to uppercase if appropriate | +| `_toupper` | `_toupper` | Converts `c` to uppercase | +| `towupper` | None | Converts c to corresponding wide-character uppercase letter | -To use the function versions of the **to** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or do not include CTYPE.H. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in STDLIB.H. +To use the function versions of the **`to`** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or don't include `CTYPE.H`. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in `STDLIB.H`. The `__toascii` routine sets all but the low-order 7 bits of `c` to 0, so that the converted value represents a character in the ASCII character set. If `c` already represents an ASCII character, `c` is unchanged. The `tolower` and `toupper` routines: - Are dependent on the `LC_CTYPE` category of the current locale (`tolower` calls `isupper` and `toupper` calls `islower`). - - Convert `c` if `c` represents a convertible letter of the appropriate case in the current locale and the opposite case exists for that locale. Otherwise, `c` is unchanged. The `_tolower` and `_toupper` routines: - Are locale-independent, much faster versions of `tolower` and **toupper.** - - Can be used only when **isascii(**`c`**)** and either **isupper(**`c`**)** or **islower(**`c`**)**, respectively, are nonzero. - -- Have undefined results if `c` is not an ASCII letter of the appropriate case for converting. +- Have undefined results if `c` isn't an ASCII letter of the appropriate case for converting. The `towlower` and `towupper` functions return a converted copy of `c` if and only if both of the following conditions are nonzero. Otherwise, `c` is unchanged. - `c` is a wide character of the appropriate case (that is, for which `iswupper` or **iswlower,** respectively, is nonzero). - -- There is a corresponding wide character of the target case (that is, for which `iswlower` or **iswupper,** respectively, is nonzero). +- There's a corresponding wide character of the target case (that is, for which `iswlower` or **iswupper,** respectively, is nonzero). ## Example @@ -67,8 +58,9 @@ The `towlower` and `towupper` functions return a converted copy of `c` if and on #include #include +#include -char msg[] = "Some of THESE letters are Capitals."; +char msg[] = "Some of THESE letters are Uppercase."; char *p; int main( void ) @@ -89,12 +81,12 @@ int main( void ) ``` ```Output -Some of THESE letters are Capitals. -sOME OF these LETTERS ARE cAPITALS. +Some of THESE letters are Uppercase. +sOME OF these LETTERS ARE uPPERCASE. ``` ## See also -[Data Conversion](../c-runtime-library/data-conversion.md)
-[Locale](../c-runtime-library/locale.md)
-[is, isw Routines](../c-runtime-library/is-isw-routines.md) +[Data conversion](./data-conversion.md)\ +[`Locale`](./locale.md)\ +[`is`, `isw` routines](./is-isw-routines.md) diff --git a/docs/c-runtime-library/toc.yml b/docs/c-runtime-library/toc.yml index fbcbac882f..4eb9c708b3 100644 --- a/docs/c-runtime-library/toc.yml +++ b/docs/c-runtime-library/toc.yml @@ -36,6 +36,17 @@ items: href: ../c-runtime-library/stream-states.md - name: Recommendations for choosing between functions and macros href: ../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md + - name: CRT debugging + items: + - name: CRT debugging techniques + href: ../c-runtime-library/crt-debugging-techniques.md + - name: CRT debug heap details + href: ../c-runtime-library/crt-debug-heap-details.md + - name: Debug versions of heap allocation functions + href: ../c-runtime-library/debug-versions-of-heap-allocation-functions.md + - name: Find memory leaks using the CRT library + href: ../c-runtime-library/find-memory-leaks-using-the-crt-library.md + href: ../c-runtime-library/type-checking-crt.md - name: Type checking (CRT) href: ../c-runtime-library/type-checking-crt.md - name: Direction flag @@ -374,7 +385,7 @@ items: href: ../c-runtime-library/data-type-mappings.md - name: Constant and global variable mappings href: ../c-runtime-library/constant-and-global-variable-mappings.md - - name: Routine mappings + - name: Generic-text function mappings href: ../c-runtime-library/routine-mappings.md - name: Locale names, languages, and country-region strings expanded: false @@ -464,9 +475,9 @@ items: href: ../c-runtime-library/reference/abs-labs-llabs-abs64.md - name: access (CRT) href: ../c-runtime-library/reference/access-crt.md - - name: _access, _waccess + - name: _access, _waccess, taccess_s href: ../c-runtime-library/reference/access-waccess.md - - name: _access_s, _waccess_s + - name: _access_s, _waccess_s, _taccess_s href: ../c-runtime-library/reference/access-s-waccess-s.md - name: acos, acosf, acosl href: ../c-runtime-library/reference/acos-acosf-acosl.md @@ -934,11 +945,11 @@ items: href: ../c-runtime-library/reference/fpieee-flt.md - name: _fpreset href: ../c-runtime-library/reference/fpreset.md - - name: fprintf, _fprintf_l, fwprintf, _fwprintf_l + - name: fprintf, _fprintf_l, fwprintf, _fwprintf_l, _ftprintf, _ftprintf_l href: ../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md - - name: _fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l + - name: _fprintf_p, _fprintf_p_l, _ftprintf_p, _ftprintf_p_l, _fwprintf_p, _fwprintf_p_l href: ../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md - - name: fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l + - name: fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l, _ftprintf, _ftprintf_l, _ftprintf_s, _ftprintf_s_l href: ../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md - name: fputc, fputwc href: ../c-runtime-library/reference/fputc-fputwc.md @@ -1446,7 +1457,7 @@ items: href: ../c-runtime-library/reference/putenv.md - name: _putenv, _wputenv href: ../c-runtime-library/reference/putenv-wputenv.md - - name: _putenv_s, _wputenv_s + - name: _putenv_s, _wputenv_s, _tputenv_s href: ../c-runtime-library/reference/putenv-s-wputenv-s.md - name: puts, _putws href: ../c-runtime-library/reference/puts-putws.md @@ -1726,7 +1737,7 @@ items: href: ../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md - name: strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l href: ../c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md - - name: strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l + - name: strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l, _tcsncpy_s, _tcsncpy_s_l, _tcsnccpy_s, _tcsnccpy_s_l href: ../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md - name: _strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l href: ../c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md @@ -1744,7 +1755,7 @@ items: href: ../c-runtime-library/reference/strnset-wcsnset.md - name: _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l href: ../c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md - - name: _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l + - name: _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l, _tcsnset_s, _tcsncset_s, _tcsncset_s_l href: ../c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md - name: strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l href: ../c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md @@ -1918,7 +1929,7 @@ items: href: ../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md - name: _vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l href: ../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md - - name: vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l + - name: vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l, _vstprintf_s, _vstprintf_s_l href: ../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md - name: vsscanf, vswscanf href: ../c-runtime-library/reference/vsscanf-vswscanf.md diff --git a/docs/c-runtime-library/translation-mode-constants.md b/docs/c-runtime-library/translation-mode-constants.md index 4ad5e13064..b50e64e560 100644 --- a/docs/c-runtime-library/translation-mode-constants.md +++ b/docs/c-runtime-library/translation-mode-constants.md @@ -2,36 +2,39 @@ description: "Learn more about: Translation Mode Constants" title: "Translation Mode Constants" ms.date: "11/04/2016" -f1_keywords: ["_O_BINARY", "_O_TEXT", "_O_RAW"] -helpviewer_keywords: ["O_BINARY constant", "O_TEXT constant", "O_RAW constant", "_O_TEXT constant", "_O_RAW constant", "translation constants", "_O_BINARY constant", "translation, constants", "translation, modes", "translation modes (file I/O)"] +f1_keywords: ["FCNTL/_O_BINARY", "FCNTL/_O_TEXT", "FCNTL/_O_WTEXT", "FCNTL/_O_U16TEXT", "FCNTL/_O_U8TEXT", "FCNTL/_O_RAW", "_O_BINARY", "_O_TEXT", "_O_WTEXT", "_O_U16TEXT", "_O_U8TEXT", "_O_RAW"] +helpviewer_keywords: ["_O_BINARY constant", "_O_TEXT constant", "_O_WTEXT constant", "_O_U16TEXT constant", "_O_U8TEXT constant", "_O_RAW constant", "translation constants", "translation, constants", "translation, modes", "translation modes (file I/O)"] ms.assetid: a5993bf4-7e7a-47f9-83c3-e46332b85579 --- -# Translation Mode Constants +# Translation mode constants ## Syntax -``` +```C #include ``` ## Remarks -The `_O_BINARY` and `_O_TEXT` manifest constants determine the translation mode for files (`_open` and `_sopen`) or the translation mode for streams (`_setmode`). +The `_O_BINARY`, `_O_TEXT`, `_O_WTEXT`, `_O_U16TEXT`, and `_O_U8TEXT` manifest constants determine the translation mode for files (`_open` and `_sopen`) or the translation mode for streams (`_setmode`). The allowed values are: -|Value|Description| -|-|-| -`_O_TEXT` | Opens file in text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into a single line feed (LF) on input. Line feed characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading, and for reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. This is done because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. -`_O_BINARY` | Opens file in binary (untranslated) mode. The above translations are suppressed. -`_O_RAW` | Same as `_O_BINARY`. Supported for C 2.0 compatibility. +| Value | Description | +|---|---| +| `_O_TEXT` | Opens file in ANSI text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into a single line feed (LF) on input. Line feed characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading, and for reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. It's removed because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. | +| `_O_WTEXT` | Opens file in UTF-16 text (translated) mode. The wide-character versions of the text translations of `_O_TEXT` are supported. | +| `_O_U16TEXT` | Opens file in UTF-16 no BOM text (translated) mode. The wide-character versions of the text translations of `_O_TEXT` are supported. | +| `_O_U8TEXT` | Opens file in UTF-8 no BOM text (translated) mode. The text translations of `_O_TEXT` are supported. | +| `_O_BINARY` | Opens file in binary (untranslated) mode. The above translations are suppressed. | +| `_O_RAW` | Same as `_O_BINARY`. Supported for C 2.0 compatibility. | -For more information, see [Text and Binary Mode File I/O](../c-runtime-library/text-and-binary-mode-file-i-o.md) and [File Translation](../c-runtime-library/file-translation-constants.md). +For more information, see [Text and binary mode file I/O](./text-and-binary-mode-file-i-o.md) and [File translation constants](./file-translation-constants.md). ## See also -[_open, _wopen](../c-runtime-library/reference/open-wopen.md)
-[_pipe](../c-runtime-library/reference/pipe.md)
-[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[_setmode](../c-runtime-library/reference/setmode.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_open`, `_wopen`](./reference/open-wopen.md)\ +[`_pipe`](./reference/pipe.md)\ +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[`_setmode`](./reference/setmode.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/truncate.md b/docs/c-runtime-library/truncate.md index cd9163a0fa..cb8dffc0d7 100644 --- a/docs/c-runtime-library/truncate.md +++ b/docs/c-runtime-library/truncate.md @@ -2,17 +2,16 @@ description: "Learn more about: _TRUNCATE" title: "_TRUNCATE" ms.date: "11/04/2016" -f1_keywords: ["_TRUNCATE", "TRUNCATE"] +f1_keywords: ["_TRUNCATE", "CORECRT/_TRUNCATE"] helpviewer_keywords: ["TRUNCATE constant", "_TRUNCATE constant"] -ms.assetid: ad093dbf-1aa5-4bd2-9268-efc68afd8434 --- -# _TRUNCATE +# `_TRUNCATE` Specifies string truncation behavior. ## Syntax -``` +```C #include ``` @@ -20,39 +19,39 @@ Specifies string truncation behavior. `_TRUNCATE` enables truncation behavior when passed as the `count` parameter to these functions: -[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](./reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](./reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) -[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md) +[`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) -[mbsrtowcs_s](../c-runtime-library/reference/mbsrtowcs-s.md) +[`mbsrtowcs_s`](./reference/mbsrtowcs-s.md) -[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md) +[`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) -[wcsrtombs_s](../c-runtime-library/reference/wcsrtombs-s.md) +[`wcsrtombs_s`](./reference/wcsrtombs-s.md) -[_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) +[`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](./reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) -[vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) +[`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](./reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) -If the destination buffer is too small to hold the entire string, the normal behavior of these functions is to treat it as an error situation (see [Parameter Validation](../c-runtime-library/parameter-validation.md)). However, if string truncation is enabled by passing `_TRUNCATE`, these functions will copy only as much of the string as will fit, leaving the destination buffer null-terminated, and return successfully. +If the destination buffer is too small to hold the entire string, the normal behavior of these functions is to treat it as an error situation (see [Parameter validation](./parameter-validation.md)). However, if string truncation is enabled by passing `_TRUNCATE`, these functions will copy only as much of the string as will fit, leaving the destination buffer null-terminated, and return successfully. String truncation changes the return values of the affected functions. The following functions return 0 if no truncation occurs, or `STRUNCATE` if truncation does occur: -[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](./reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](./reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) -[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md) +[`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) -[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md) +[`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) -The following functions return the number of characters copied if no truncation occurs, or -1 if truncation does occur (matching the behavior of the original snprintf functions): +The following functions return the number of characters copied if no truncation occurs, or -1 if truncation does occur (matching the behavior of the original `snprintf` functions): -[_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) +[`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](./reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) -[vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) +[`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](./reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) ## Example @@ -79,4 +78,4 @@ truncation occurred! ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/type-checking-crt.md b/docs/c-runtime-library/type-checking-crt.md index 7837ce8daf..4652c3c0c2 100644 --- a/docs/c-runtime-library/type-checking-crt.md +++ b/docs/c-runtime-library/type-checking-crt.md @@ -6,22 +6,22 @@ f1_keywords: ["c.types"] helpviewer_keywords: ["checking type", "variable argument functions", "type checking"] ms.assetid: 1ba7590b-d1c0-4636-b6a0-e231395abdad --- -# Type Checking (CRT) +# Type checking (CRT) The compiler performs limited type checking on functions that can take a variable number of arguments, as follows: -|Function call|Type-checked arguments| -|-------------------|-----------------------------| -|`_cprintf_s`, `_cscanf_s`, `printf_s`, `scanf_s`|First argument (format string)| -|`fprintf_s`, `fscanf_s`, `sprintf_s`, `sscanf_s`|First two arguments (file or buffer and format string)| -|`_snprintf_s`|First three arguments (file or buffer, count, and format string)| -|`_open`|First two arguments (path and `_open` flag)| -|`_sopen_s`|First three arguments (path, `_open` flag, and sharing mode)| -|`_execl`, `_execle`, `_execlp`, `_execlpe`|First two arguments (path and first argument pointer)| -|`_spawnl`, `_spawnle`, `_spawnlp`, `_spawnlpe`|First three arguments (mode flag, path, and first argument pointer)| +| Function call | Type-checked arguments | +|---|---| +| `_cprintf_s`, `_cscanf_s`, `printf_s`, `scanf_s` | First argument (format string) | +| `fprintf_s`, `fscanf_s`, `sprintf_s`, `sscanf_s` | First two arguments (file or buffer and format string) | +| `_snprintf_s` | First three arguments (file or buffer, count, and format string) | +| `_open` | First two arguments (path and `_open` flag) | +| `_sopen_s` | First three arguments (path, `_open` flag, and sharing mode) | +| `_execl`, `_execle`, `_execlp`, `_execlpe` | First two arguments (path and first argument pointer) | +| `_spawnl`, `_spawnle`, `_spawnlp`, `_spawnlpe` | First three arguments (mode flag, path, and first argument pointer) | The compiler performs the same limited type checking on the wide-character counterparts of these functions. ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/tzname-max.md b/docs/c-runtime-library/tzname-max.md index eff3aba492..f756ca17a6 100644 --- a/docs/c-runtime-library/tzname-max.md +++ b/docs/c-runtime-library/tzname-max.md @@ -6,18 +6,18 @@ f1_keywords: ["TZNAME_MAX"] helpviewer_keywords: ["TZNAME_MAX constant"] ms.assetid: e2286cb8-751d-4557-9650-5c4b98a8f7be --- -# TZNAME_MAX +# `TZNAME_MAX` -**Obsolete**. The maximum permissible string length for a time zone name variable. This macro was defined in \ in Visual Studio 2012 and earlier versions. It is not defined in Visual Studio 2013 and later versions. To get the length required to hold the current time zone name, use [_get_tzname](../c-runtime-library/reference/get-tzname.md). +**Obsolete**. The maximum permissible string length for a time zone name variable. This macro was defined in \ in Visual Studio 2012 and earlier versions. It isn't defined in Visual Studio 2013 and later versions. To get the length required to hold the current time zone name, use [`_get_tzname`](./reference/get-tzname.md). ## Syntax -``` +```C #include ``` ## See also -[Environmental Constants](../c-runtime-library/environmental-constants.md)
-[Global Constants](../c-runtime-library/global-constants.md)
-[_get_tzname](../c-runtime-library/reference/get-tzname.md) +[Environmental constants](./environmental-constants.md)\ +[Global constants](./global-constants.md)\ +[`_get_tzname`](./reference/get-tzname.md) diff --git a/docs/c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md b/docs/c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md index bfddf80ae3..c6c1034d8e 100644 --- a/docs/c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md +++ b/docs/c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md @@ -6,11 +6,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["stream I/O routines", "I/O [CRT], unicode stream", "Unicode, stream I/O routines", "Unicode stream I/O"] ms.assetid: 68be0c3e-a9e6-4fd5-b34a-1b5207f0e7d6 --- -# Unicode Stream I/O in Text and Binary Modes +# Unicode stream I/O in text and binary modes -When a Unicode stream I/O routine (such as **fwprintf**, **fwscanf**, **fgetwc**, **fputwc**, **fgetws**, or **fputws**) operates on a file that is open in text mode (the default), two kinds of character conversions take place: +When a Unicode stream I/O routine (such as `fwprintf`, `fwscanf`, `fgetwc`, `fputwc`, `fgetws`, or `fputws`) operates on a file that is open in text mode (the default), two kinds of character conversions take place: -- Unicode-to-MBCS or MBCS-to-Unicode conversion. When a Unicode stream-I/O function operates in text mode, the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **mbtowc** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **wctomb** function). +- Unicode-to-MBCS or MBCS-to-Unicode conversion. When a Unicode stream-I/O function operates in text mode, the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the `mbtowc` function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the `wctomb` function). - Carriage return-line feed (CR-LF) translation. This translation occurs before the MBCS - Unicode conversion (for Unicode stream input functions) and after the Unicode - MBCS conversion (for Unicode stream output functions). During input, each carriage return-line feed combination is translated into a single line feed character. During output, each line feed character is translated into a carriage return-line feed combination. @@ -18,5 +18,5 @@ However, when a Unicode stream-I/O function operates in binary mode, the file is ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[Input and Output](../c-runtime-library/input-and-output.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[Input and output](./input-and-output.md) diff --git a/docs/c-runtime-library/unicode-the-wide-character-set.md b/docs/c-runtime-library/unicode-the-wide-character-set.md index d575d5ff12..9fbde6648e 100644 --- a/docs/c-runtime-library/unicode-the-wide-character-set.md +++ b/docs/c-runtime-library/unicode-the-wide-character-set.md @@ -6,9 +6,9 @@ ms.date: "11/04/2016" helpviewer_keywords: ["Unicode [C++], wide character set", "wide characters [C++], Unicode"] ms.assetid: b6a05a21-59a5-4d30-8c85-2dbe185f7a74 --- -# Unicode: The Wide-Character Set +# Unicode: The wide-character set -A wide character is a 2-byte multilingual character code. Any character in use in modern computing worldwide, including technical symbols and special publishing characters, can be represented according to the Unicode specification as a wide character. Developed and maintained by a large consortium that includes Microsoft, the Unicode standard is now widely accepted. +A wide character is a 2-byte multilingual character code. Any character in use in modern computing worldwide, including technical symbols and special publishing characters, can be represented according to the Unicode specification as one or more wide characters. Developed and maintained by a large consortium that includes Microsoft, the Unicode standard is now widely accepted. A wide character is of type **`wchar_t`**. A wide-character string is represented as a **`wchar_t[]`** array. You point to the array with a `wchar_t*` pointer. @@ -20,5 +20,5 @@ Generally, wide characters use more space in memory than multibyte characters. B ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/unix.md b/docs/c-runtime-library/unix.md index a063d6356b..5d63b80fd2 100644 --- a/docs/c-runtime-library/unix.md +++ b/docs/c-runtime-library/unix.md @@ -22,4 +22,4 @@ If you plan to port your programs to UNIX, follow these guidelines: ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/unlock.md b/docs/c-runtime-library/unlock.md index 7cfd64eb49..996c026ec1 100644 --- a/docs/c-runtime-library/unlock.md +++ b/docs/c-runtime-library/unlock.md @@ -10,7 +10,7 @@ f1_keywords: ["unlock", "_unlock"] helpviewer_keywords: ["unlock function", "_unlock function"] ms.assetid: 2eda2507-a134-4997-aa12-f2f8cb319e14 --- -# _unlock +# `_unlock` Releases a multi-thread lock. @@ -27,7 +27,7 @@ void __cdecl _unlock( #### Parameters -*locknum*
+*`locknum`*\ [in] The identifier of the lock to release. ## Requirements @@ -36,5 +36,5 @@ void __cdecl _unlock( ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[_lock](../c-runtime-library/lock.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`_lock`](./lock.md) diff --git a/docs/c-runtime-library/using-generic-text-mappings.md b/docs/c-runtime-library/using-generic-text-mappings.md index 62d8c5a02c..357e8f4a54 100644 --- a/docs/c-runtime-library/using-generic-text-mappings.md +++ b/docs/c-runtime-library/using-generic-text-mappings.md @@ -7,19 +7,19 @@ f1_keywords: ["_UNICODE"] helpviewer_keywords: ["_TXCHAR type", "TINT type", "_TCHAR type", "TSCHAR type", "TEXT type", "TCHAR type", "TCHAR.H data types, mappings defined in", "generic-text data types", "_TINT type", "TUCHAR type", "_UNICODE constant", "TXCHAR type", "generic-text mappings", "_TSCHAR type", "T type", "mappings, generic-text", "_TUCHAR type", "MBCS data type", "_MBCS data type", "_TEXT type", "UNICODE constant", "_T type"] ms.assetid: 2848121c-e51f-4b9b-a2e6-833ece4b0cb3 --- -# Using Generic-Text Mappings +# Using generic-text mappings **Microsoft Specific** -To simplify code development for various international markets, the Microsoft run-time library provides Microsoft-specific "generic-text" mappings for many data types, routines, and other objects. These mappings are defined in TCHAR.H. You can use these name mappings to write generic code that can be compiled for any of the three kinds of character sets: ASCII (SBCS), MBCS, or Unicode, depending on a manifest constant you define using a `#define` statement. Generic-text mappings are Microsoft extensions that are not ANSI compatible. +To simplify code development for various international markets, the Microsoft run-time library provides Microsoft-specific "generic-text" mappings for many data types, routines, and other objects. These mappings are defined in TCHAR.H. You can use these name mappings to write generic code that can be compiled for any of the three kinds of character sets: ASCII (SBCS), MBCS, or Unicode, depending on a manifest constant you define using a `#define` statement. Generic-text mappings are Microsoft extensions that aren't ANSI compatible. -### Preprocessor Directives for Generic-Text Mappings +### Preprocessor directives for generic-text mappings -|#define|Compiled version|Example| -|--------------|----------------------|-------------| -|`_UNICODE`|Unicode (wide-character)|`_tcsrev` maps to `_wcsrev`| -|`_MBCS`|Multibyte-character|`_tcsrev` maps to `_mbsrev`| -|None (the default: neither `_UNICODE` nor `_MBCS` defined)|SBCS (ASCII)|`_tcsrev` maps to `strrev`| +| `#define` | Compiled version | Example | +|---|---|---| +| `_UNICODE` | Unicode (wide-character) | `_tcsrev` maps to `_wcsrev` | +| `_MBCS` | Multibyte-character | `_tcsrev` maps to `_mbsrev` | +| None (the default: both `_UNICODE` and `_MBCS` not defined) | SBCS (ASCII) | `_tcsrev` maps to `strrev` | For example, the generic-text function `_tcsrev`, defined in TCHAR.H, maps to `mbsrev` if `MBCS` has been defined in your program, or to `_wcsrev` if `_UNICODE` has been defined. Otherwise `_tcsrev` maps to `strrev`. @@ -27,53 +27,53 @@ The generic-text data type `_TCHAR`, also defined in TCHAR.H, maps to type **`ch ### Generic-Text Data Type Mappings -|Generic-text data type name|SBCS (_UNICODE, _MBCS not defined)|_MBCS defined|_UNICODE defined| -|----------------------------------|--------------------------------------------|--------------------|-----------------------| -|`_TCHAR`|**`char`**|**`char`**|**`wchar_t`**| -|`_TINT`|**`int`**|**`int`**|`wint_t`| -|`_TSCHAR`|**`signed char`**|**`signed char`**|**`wchar_t`**| -|`_TUCHAR`|**`unsigned char`**|**`unsigned char`**|**`wchar_t`**| -|`_TXCHAR`|**`char`**|**`unsigned char`**|**`wchar_t`**| -|`_T` or `_TEXT`|No effect (removed by preprocessor)|No effect (removed by preprocessor)|`L` (converts following character or string to its Unicode counterpart)| +| Generic-text data type name | SBCS (_UNICODE, _MBCS not defined) | _MBCS defined | _UNICODE defined | +|---|---|---|---| +| `_TCHAR` | **`char`** | **`char`** | **`wchar_t`** | +| `_TINT` | **`int`** | **`int`** | `wint_t` | +| `_TSCHAR` | **`signed char`** | **`signed char`** | **`wchar_t`** | +| `_TUCHAR` | **`unsigned char`** | **`unsigned char`** | **`wchar_t`** | +| `_TXCHAR` | **`char`** | **`unsigned char`** | **`wchar_t`** | +| `_T` or `_TEXT` | No effect (removed by preprocessor) | No effect (removed by preprocessor) | `L` (converts following character or string to its Unicode counterpart) | -For a complete list of generic-text mappings of routines, variables, and other objects, see [Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md). +For a complete list of generic-text mappings of routines, variables, and other objects, see [Generic-text mappings](./generic-text-mappings.md). The following code fragments illustrate the use of `_TCHAR` and `_tcsrev` for mapping to the MBCS, Unicode, and SBCS models. -``` +```C _TCHAR *RetVal, *szString; RetVal = _tcsrev(szString); ``` If `MBCS` has been defined, the preprocessor maps the preceding fragment to the following code: -``` +```C char *RetVal, *szString; RetVal = _mbsrev(szString); ``` If `_UNICODE` has been defined, the preprocessor maps the same fragment to the following code: -``` +```C wchar_t *RetVal, *szString; RetVal = _wcsrev(szString); ``` -If neither `_MBCS` nor `_UNICODE` has been defined, the preprocessor maps the fragment to single-byte ASCII code, as follows: +If both `_MBCS` and `_UNICODE` haven't been defined, the preprocessor maps the fragment to single-byte ASCII code, as follows: -``` +```C char *RetVal, *szString; RetVal = strrev(szString); ``` -Thus you can write, maintain, and compile a single source code file to run with routines that are specific to any of the three kinds of character sets. +These macros let you write, maintain, and compile a single source code file using routines specific to all three kinds of character sets. **END Microsoft Specific** ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md) diff --git a/docs/c-runtime-library/using-tchar-h-data-types-with-mbcs.md b/docs/c-runtime-library/using-tchar-h-data-types-with-mbcs.md index 3d9adc922b..2a18a51678 100644 --- a/docs/c-runtime-library/using-tchar-h-data-types-with-mbcs.md +++ b/docs/c-runtime-library/using-tchar-h-data-types-with-mbcs.md @@ -6,15 +6,15 @@ ms.date: "11/04/2016" helpviewer_keywords: ["TCHAR.H data types", "MBCS data type", "_MBCS data type"] ms.assetid: 48f471e7-9d2b-4a39-b841-16a0e15c0a18 --- -# Using TCHAR.H Data Types with _MBCS +# Using tchar.h data types with _MBCS **Microsoft Specific** -As the table of generic-text routine mappings indicates (see [Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)), when the manifest constant **_MBCS** is defined, a given generic-text routine maps to one of the following kinds of routines: +As the table of generic-text routine mappings indicates (see [Generic-text mappings](./generic-text-mappings.md)), when the manifest constant `_MBCS` is defined, a given generic-text routine will map to one of the following kinds of routines: -- An SBCS routine that handles multibyte bytes, characters, and strings appropriately. In this case, the string arguments are expected to be of type `char*`. For example, **_tprintf** maps to **printf**; the string arguments to **printf** are of type `char*`. If you use the **_TCHAR** generic-text data type for your string types, the formal and actual parameter types for **printf** match because `_TCHAR*` maps to `char*`. +- An SBCS routine that handles multibyte bytes, characters, and strings appropriately. In this case, the string arguments are expected to be of type `char*`. For example, `_tprintf` maps to `printf`; the string arguments to `printf` are of type `char*`. If you use the `_TCHAR` generic-text data type for your string types, the formal and actual parameter types for `printf` match because `_TCHAR*` maps to `char*`. -- An MBCS-specific routine. In this case, the string arguments are expected to be of type `unsigned char*`. For example, **_tcsrev** maps to **_mbsrev**, which expects and returns a string of type `unsigned char*`. Again, if you use the **_TCHAR** generic-text data type for your string types, there's a potential type conflict because **_TCHAR** maps to type **`char`**. +- An MBCS-specific routine. In this case, the string arguments are expected to be of type `unsigned char*`. For example, `_tcsrev` maps to `_mbsrev`, which expects and returns a string of type `unsigned char*`. Again, if you use the `_TCHAR` generic-text data type for your string types, there's a potential type conflict because `_TCHAR` maps to type **`char`**. Following are three solutions for preventing this type conflict (and the C compiler warnings or C++ compiler errors that would result): @@ -24,7 +24,7 @@ Following are three solutions for preventing this type conflict (and the C compi char *_tcsrev(char *); ``` - In the default case, the prototype for **_tcsrev** maps to **_mbsrev** through a thunk in LIBC.LIB. This changes the types of the **_mbsrev** incoming parameters and outgoing return value from `_TCHAR*` (such as `char*`) to `unsigned char*`. This method ensures type matching when you're using **_TCHAR**, but it's relatively slow because of the function call overhead. + In the default case, the prototype for `_tcsrev` maps to `_mbsrev` through a thunk in LIBC.LIB. This thunk changes the types of the `_mbsrev` incoming parameters and outgoing return value from `_TCHAR*` (such as `char*`) to `unsigned char*`. This method ensures type matching when you're using `_TCHAR`, but it's relatively slow because of the function call overhead. - Use function inlining by incorporating the following preprocessor statement in your code. @@ -32,14 +32,14 @@ Following are three solutions for preventing this type conflict (and the C compi #define _USE_INLINING ``` - This method causes an inline function thunk, provided in TCHAR.H, to map the generic-text routine directly to the appropriate MBCS routine. The following code excerpt from TCHAR.H provides an example of how this is done. + This method causes an inline function thunk, provided in TCHAR.H, to map the generic-text routine directly to the appropriate MBCS routine. The following code excerpt from TCHAR.H provides an example of how it's done. ```C __inline char *_tcsrev(char *_s1) {return (char *)_mbsrev((unsigned char *)_s1);} ``` - If you can use inlining, this is the best solution, because it guarantees type matching and has no additional time cost. + If you can use inlining, it's the best solution, because it guarantees type matching and has no extra time cost. - Use "direct mapping" by incorporating the following preprocessor statement in your code. @@ -53,11 +53,11 @@ Following are three solutions for preventing this type conflict (and the C compi #define _tcschr _mbschr ``` -When you take this approach, be careful to ensure that appropriate data types are used for string arguments and string return values. You can use type casting to ensure proper type matching or you can use the **_TXCHAR** generic-text data type. **_TXCHAR** maps to type **`char`** in SBCS code but maps to type **`unsigned char`** in MBCS code. For more information about generic-text macros, see [Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md). +When you take this approach, be careful to ensure that appropriate data types are used for string arguments and string return values. You can use type casting to ensure proper type matching or you can use the `_TXCHAR` generic-text data type. `_TXCHAR` maps to type **`char`** in SBCS code but maps to type **`unsigned char`** in MBCS code. For more information about generic-text macros, see [Generic-text mappings](./generic-text-mappings.md). **END Microsoft Specific** ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/vprintf-functions.md b/docs/c-runtime-library/vprintf-functions.md index 03109f3c9a..6119ea7428 100644 --- a/docs/c-runtime-library/vprintf-functions.md +++ b/docs/c-runtime-library/vprintf-functions.md @@ -1,30 +1,25 @@ --- -description: "Learn more about: vprintf Functions" title: "vprintf Functions" +description: "Learn more about: vprintf Functions" ms.date: "11/04/2016" -api_location: ["msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["vprintf"] -helpviewer_keywords: ["vprintf function", "formatted text [C++]"] -ms.assetid: 02ac7c51-eab1-4bf0-bf4c-77065e3fa744 +helpviewer_keywords: ["vprintf functions", "formatted text [C++]"] --- -# vprintf Functions +# `vprintf` functions -Each of the `vprintf` functions takes a pointer to an argument list, then formats and writes the given data to a particular destination. The functions differ in the parameter validation performed, whether the functions take wide or single-byte character strings, the output destination, and the support for specifying the order in which parameters are used in the format string. +Each of the `vprintf` functions takes a pointer to an argument list, then formats and writes the given data to a particular destination. The functions differ in several ways: in the parameter validation, whether the functions take single-byte or wide character strings, the output destination, and the support for specifying the order parameters are used in the format string. -[_vcprintf, _vcwprintf](../c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md)\ -[vfprintf, vfwprintf](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)\ -[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](../c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)\ -[vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](../c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)\ -[vprintf, vwprintf](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)\ -[_vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l](../c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md)\ -[vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l](../c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md)\ -[_vscprintf, _vscprintf_l, _vscwprintf, _vscwprintf_l](../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)\ -[_vsnprintf, _vsnwprintf](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) -[vsprintf, vswprintf](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)\ -[_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l](../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)\ -[vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) +[`_vcprintf`, `_vcwprintf`](./reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md)\ +[`vfprintf`, `vfwprintf`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)\ +[`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](./reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)\ +[`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](./reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)\ +[`vprintf`, `vwprintf`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)\ +[`_vprintf_p`, `_vprintf_p_l`, `_vwprintf_p`, `_vwprintf_p_l`](./reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md)\ +[`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](./reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md)\ +[`_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l`](./reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)\ +[`_vsnprintf`, `_vsnwprintf`](./reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md)\ +[`vsprintf`, `vswprintf`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)\ +[`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](./reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)\ +[`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](./reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) ## Remarks @@ -32,52 +27,52 @@ The `vprintf` functions are similar to their counterpart functions as listed in These functions format data for output to destinations as follows. -|Function|Counterpart function|Output destination|Parameter Validation|Positional Parameter Support| -|--------------|--------------------------|------------------------|--------------------------|----------------------------------| -|`_vcprintf`|[_cprintf](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|console|Check for null.|no| -|`_vcwprintf`|[_cwprintf](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|console|Check for null.|no| -|`vfprintf`|[fprintf](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|*Stream*|Check for null.|no| -|**vfprintf_p**|[fprintf_p](../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)|*Stream*|Check for null and valid format.|yes| -|`vfprintf_s`|[fprintf_s](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)|*Stream*|Check for null and valid format.|no| -|`vfwprintf`|[fwprintf](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|*Stream*|Check for null.|no| -|**vfwprintf_p**|[fwprintf_p](../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)|*Stream*|Check for null and valid format.|yes| -|`vfwprintf_s`|[fwprintf_s](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)|*Stream*|Check for null and valid format.|no| -|`vprintf`|[printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|`Stdout`|Check for null.|no| -|**vprintf_p**|[printf_p](../c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)|`Stdout`|Check for null and valid format.|yes| -|`vprintf_s`|[printf_s](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)|`Stdout`|Check for null and valid format.|no| -|`vwprintf`|[wprintf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|`Stdout`|Check for null.|no| -|**vwprintf_p**|[wprintf_p](../c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)|`Stdout`|Check for null and valid format.|yes| -|`vwprintf_s`|[wprintf_s](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)|`Stdout`|Check for null and valid format.|no| -|**vsprintf**|[sprintf](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| -|**vsprintf_p**|[sprintf_p](../c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)|memory pointed to by *buffer*|Check for null and valid format.|yes| -|`vsprintf_s`|[sprintf_s](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)|memory pointed to by *buffer*|Check for null and valid format.|no| -|`vswprintf`|[swprintf](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| -|**vswprintf_p**|[swprintf_p](../c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)|memory pointed to by *buffer*|Check for null and valid format.|yes| -|`vswprintf_s`|[swprintf_s](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)|memory pointed to by *buffer*|Check for null and valid format.|no| -|`_vscprintf`|[_vscprintf](../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| -|`_vscwprintf`|[_vscwprintf](../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| -|`_vsnprintf`|[_snprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| -|`_vsnwprintf`|[_snwprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)|memory pointed to by *buffer*|Check for null.|no| +| Function | Counterpart function | Output destination | Parameter Validation | Positional Parameter Support | +|---|---|---|---|---| +| `_vcprintf` | [`_cprintf`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | console | Check for null. | no | +| `_vcwprintf` | [`_cwprintf`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | console | Check for null. | no | +| `vfprintf` | [`fprintf`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | *`stream`* | Check for null. | no | +| `vfprintf_p` | [`fprintf_p`](./reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md) | *`stream`* | Check for null and valid format. | yes | +| `vfprintf_s` | [`fprintf_s`](./reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) | *`stream`* | Check for null and valid format. | no | +| `vfwprintf` | [`fwprintf`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | *`stream`* | Check for null. | no | +| `vfwprintf_p` | [`fwprintf_p`](./reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md) | *`stream`* | Check for null and valid format. | yes | +| `vfwprintf_s` | [`fwprintf_s`](./reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) | *`stream`* | Check for null and valid format. | no | +| `vprintf` | [`printf`](./reference/printf-printf-l-wprintf-wprintf-l.md) | `stdout` | Check for null. | no | +| `vprintf_p` | [`printf_p`](./reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) | `stdout` | Check for null and valid format. | yes | +| `vprintf_s` | [`printf_s`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) | `stdout` | Check for null and valid format. | no | +| `vwprintf` | [`wprintf`](./reference/printf-printf-l-wprintf-wprintf-l.md) | `stdout` | Check for null. | no | +| `vwprintf_p` | [`wprintf_p`](./reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) | `stdout` | Check for null and valid format. | yes | +| `vwprintf_s` | [`wprintf_s`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) | `stdout` | Check for null and valid format. | no | +| `vsprintf` | [`sprintf`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | +| `vsprintf_p` | [`sprintf_p`](./reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) | memory pointed to by *`buffer`* | Check for null and valid format. | yes | +| `vsprintf_s` | [`sprintf_s`](./reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) | memory pointed to by *`buffer`* | Check for null and valid format. | no | +| `vswprintf` | [`swprintf`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | +| `vswprintf_p` | [`swprintf_p`](./reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) | memory pointed to by *`buffer`* | Check for null and valid format. | yes | +| `vswprintf_s` | [`swprintf_s`](./reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) | memory pointed to by *`buffer`* | Check for null and valid format. | no | +| `_vscprintf` | [`_vscprintf`](./reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | +| `_vscwprintf` | [`_vscwprintf`](./reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | +| `_vsnprintf` | [`_snprintf`](./reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | +| `_vsnwprintf` | [`_snwprintf`](./reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) | memory pointed to by *`buffer`* | Check for null. | no | -The `argptr` argument has type `va_list`, which is defined in VARARGS.H and STDARG.H. The `argptr` variable must be initialized by **va_start,** and may be reinitialized by subsequent `va_arg` calls; `argptr` then points to the beginning of a list of arguments that are converted and transmitted for output according to the corresponding specifications in the *format* argument. *format* has the same form and function as the *format* argument for [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md). None of these functions invokes `va_end`. For a more complete description of each `vprintf` function, see the description of its counterpart function as listed in the preceding table. +The `argptr` argument has type `va_list`, which is defined in VARARGS.H and STDARG.H. The `argptr` variable must be initialized by **va_start,** and may be reinitialized by subsequent `va_arg` calls; `argptr` then points to the beginning of a list of arguments that are converted and transmitted for output according to the corresponding specifications in the *`format`* argument. *`format`* has the same form and function as the *`format`* argument for [`printf`](./reference/printf-printf-l-wprintf-wprintf-l.md). None of these functions invoke `va_end`. For a more complete description of each `vprintf` function, see the description of its counterpart function as listed in the preceding table. -`_vsnprintf` differs from **vsprintf** in that it writes no more than *count* bytes to *buffer*. +`_vsnprintf` differs from `vsprintf` in that it writes no more than *`count`* bytes to *`buffer`*. -The versions of these functions with the **w** infix in the name are wide-character versions of the corresponding functions without the **w** infix; in each of these wide-character functions, *buffer* and *format* are wide-character strings. Otherwise, each wide-character function behaves identically to its SBCS counterpart function. +The versions of these functions with the **w** infix in the name are wide-character versions of the corresponding functions without the **w** infix; in each of these wide-character functions, *`buffer`* and *`format`* are wide-character strings. Otherwise, each wide-character function behaves identically to its SBCS counterpart function. -The versions of these functions with **_s** and **_p** suffixes are the more secure versions. These versions validate the format strings and will generate an exception if the format string is not well formed (for example, if invalid formatting characters are used). +The versions of these functions with **`_s`** and **`_p`** suffixes are the more secure versions. These versions validate the format strings. They'll generate an exception if the format string isn't well formed (for example, if invalid formatting characters are used). -The versions of these functions with the **_p** suffix provide the ability to specify the order in which the supplied arguments are substituted in the format string. For more information, see [printf_p Positional Parameters](../c-runtime-library/printf-p-positional-parameters.md). +The versions of these functions with the **`_p`** suffix let you specify the order in which the supplied arguments are substituted in the format string. For more information, see [printf_p Positional Parameters](./printf-p-positional-parameters.md). -For **vsprintf**, `vswprintf`, `_vsnprintf` and `_vsnwprintf`, if copying occurs between strings that overlap, the behavior is undefined. +For `vsprintf`, `vswprintf`, `_vsnprintf` and `_vsnwprintf`, if copying occurs between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). If using the secure versions of these functions (either the **_s** or **_p** suffixes), a user-supplied format string could trigger an invalid parameter exception if the user-supplied string contains invalid formatting characters. +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). If using the secure versions of these functions (either the **`_s`** or **`_p`** suffixes), a user-supplied format string could trigger an invalid parameter exception if the user-supplied string contains invalid formatting characters. ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) +[Stream I/O](./stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](./reference/va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/wait-child-wait-grandchild.md b/docs/c-runtime-library/wait-child-wait-grandchild.md index fe07213635..26a92d87ec 100644 --- a/docs/c-runtime-library/wait-child-wait-grandchild.md +++ b/docs/c-runtime-library/wait-child-wait-grandchild.md @@ -2,15 +2,15 @@ description: "Learn more about: _WAIT_CHILD, _WAIT_GRANDCHILD" title: "_WAIT_CHILD, _WAIT_GRANDCHILD" ms.date: "11/04/2016" -f1_keywords: ["_WAIT_GRANDCHILD", "WAIT_CHILD", "WAIT_GRANDCHILD", "_WAIT_CHILD"] +f1_keywords: ["PROCESS/_WAIT_CHILD", "PROCESS/_WAIT_GRANDCHILD", "_WAIT_CHILD", "_WAIT_GRANDCHILD"] helpviewer_keywords: ["WAIT_CHILD constant", "WAIT_GRANDCHILD constant", "_WAIT_CHILD constant", "_WAIT_GRANDCHILD constant"] ms.assetid: 7acd96fa-d118-4339-bb00-e5afaf286945 --- -# _WAIT_CHILD, _WAIT_GRANDCHILD +# `_WAIT_CHILD`, `_WAIT_GRANDCHILD` ## Syntax -``` +```C #include ``` @@ -18,12 +18,12 @@ ms.assetid: 7acd96fa-d118-4339-bb00-e5afaf286945 The `_cwait` function can be used by any process to wait for any other process (if the process ID is known). The action argument can be one of the following values: -|Constant|Meaning| -|--------------|-------------| -|`_WAIT_CHILD`|Calling process waits until specified new process terminates.| -|`_WAIT_GRANDCHILD`|Calling process waits until specified new process, and all processes created by that new process, terminate.| +| Constant | Meaning | +|---|---| +| `_WAIT_CHILD` | Calling process waits until specified new process terminates. | +| `_WAIT_GRANDCHILD` | Calling process waits until specified new process, and all processes created by that new process, terminate. | ## See also -[_cwait](../c-runtime-library/reference/cwait.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_cwait`](./reference/cwait.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/wchar-max.md b/docs/c-runtime-library/wchar-max.md index 165fea2232..2cc4f93793 100644 --- a/docs/c-runtime-library/wchar-max.md +++ b/docs/c-runtime-library/wchar-max.md @@ -2,20 +2,20 @@ description: "Learn more about: WCHAR_MAX" title: "WCHAR_MAX" ms.date: "11/04/2016" -f1_keywords: ["WCHAR_MAX"] +f1_keywords: ["WCHAR/WCHAR_MAX", "WCHAR_MAX"] helpviewer_keywords: ["WCHAR_MAX constant"] ms.assetid: 2b5f8bfd-9098-47fc-be8f-598a0c975ed4 --- -# WCHAR_MAX +# `WCHAR_MAX` Maximum value for type **`wchar_t`**. ## Syntax -``` +```C #include ``` ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/wchar-min.md b/docs/c-runtime-library/wchar-min.md index 062fcc478c..5aaeae92ae 100644 --- a/docs/c-runtime-library/wchar-min.md +++ b/docs/c-runtime-library/wchar-min.md @@ -2,20 +2,20 @@ description: "Learn more about: WCHAR_MIN" title: "WCHAR_MIN" ms.date: "11/04/2016" -f1_keywords: ["WCHAR_MIN"] +f1_keywords: ["WCHAR/WCHAR_MIN", "WCHAR_MIN"] helpviewer_keywords: ["WCHAR_MIN constant"] ms.assetid: f2d192d7-4412-483f-9839-c29e4f174b83 --- -# WCHAR_MIN +# `WCHAR_MIN` Minimum value for type **`wchar_t`**. ## Syntax -``` +```C #include ``` ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/windows-platforms-crt.md b/docs/c-runtime-library/windows-platforms-crt.md index 0b060b3cd7..a0dc765866 100644 --- a/docs/c-runtime-library/windows-platforms-crt.md +++ b/docs/c-runtime-library/windows-platforms-crt.md @@ -5,13 +5,27 @@ ms.date: "02/02/2018" helpviewer_keywords: ["CRT, compatibility", "backward compatibility [C++], C run-time libraries", "compatibility [C++], C run-time libraries", "MBCS [C++], Win32 platforms", "operating systems [C++]", "Unicode [C++], Win32 platforms"] ms.assetid: 0aacaf45-6dc4-4908-bd52-57abac7b39f6 --- -# Windows Platforms (CRT) +# Windows platforms (CRT) -The C run-time libraries for Visual Studio support current versions of Windows and Windows Server, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, and Windows Vista, and optionally support Windows XP Service Pack 3 (SP3) for x86, Windows XP Service Pack 2 (SP2) for x64, and Windows Server 2003 Service Pack 2 (SP2) for both x86 and x64. All of these operating systems support the Windows desktop API (Win32) and provide Unicode support. In addition, any Win32 application can use a multibyte character set (MBCS). +:::moniker range="msvc-140" + +The C run-time libraries for Visual Studio support all versions of Windows and Windows Server that are still in extended support. Visual Studio 2015 supports Windows 8 and 8.1, Windows Server 2012, Windows 7, Windows Server 2008, and Windows Vista. It optionally supports Windows XP Service Pack 3 (SP3) for x86, Windows XP Service Pack 2 (SP2) for x64, and Windows Server 2003 Service Pack 2 (SP2) for both x86 and x64. All of these operating systems support the Windows desktop API (Win32) and provide Unicode support. In addition, any Win32 application can use a multibyte character set (MBCS). + +:::moniker-end + +:::moniker range=">=msvc-150" + +The C run-time libraries for Visual Studio support all versions of Windows and Windows Server that are still in extended support. Libraries are available for x86, x64, and ARM64. All of these operating systems support the Windows desktop API (Win32) and provide Unicode support. In addition, any Win32 application can use a multibyte character set (MBCS). + +:::moniker-end + +:::moniker range="msvc-150" > [!NOTE] > The default installation of the **Desktop development with C++** workload in Visual Studio 2017 does not include support for Windows XP and Windows Server 2003 development. You must install the optional component **Windows XP support for C++** to enable a Windows XP platform toolset. +:::moniker-end + ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/windows-runtime-unsupported-crt-functions.md b/docs/c-runtime-library/windows-runtime-unsupported-crt-functions.md index f0bb28a8ae..53d51eb826 100644 --- a/docs/c-runtime-library/windows-runtime-unsupported-crt-functions.md +++ b/docs/c-runtime-library/windows-runtime-unsupported-crt-functions.md @@ -5,13 +5,13 @@ ms.date: "11/04/2016" helpviewer_keywords: ["unsupported CRT functions, Windows Runtime", "Windows Runtime, unsupported CRT functions"] ms.assetid: bb8386d6-0ef8-460c-88d8-addff009b6f1 --- -# Windows Runtime Unsupported CRT Functions +# Windows Runtime unsupported CRT functions -Many C run-time (CRT) APIs can’t be used in Universal Windows Platform (UWP) apps that execute in the Windows Runtime. These apps are built by using the /ZW compiler flag. For a list of unsupported CRT functions, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +Many C run-time (CRT) APIs can't be used in Universal Windows Platform (UWP) apps that execute in the Windows Runtime. These apps are built by using the /ZW compiler flag. For a list of unsupported CRT functions, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). -All CRT APIs are described in the [Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md) section of the documentation. +All CRT APIs are described in the [Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) section of the documentation. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md b/docs/c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md index 40388b4e07..9ad209bb4e 100644 --- a/docs/c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md +++ b/docs/c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md @@ -12,9 +12,9 @@ UWP apps don't support the following CRT features: - Most CRT functions that are related to unsupported functionality. - For example, a UWP app cannot create a process by using the **exec** and **spawn** families of routines. + For example, a UWP app can't create a process by using the `exec` and `spawn` families of routines. - When a CRT function is not supported in a UWP app, that fact is noted in its reference article. + When a CRT function isn't supported in a UWP app, that fact is noted in its reference article. - Most multibyte character and string functions. @@ -30,13 +30,13 @@ UWP apps don't support the following CRT features: - An app that's built by using the [/MDd](../build/reference/md-mt-ld-use-run-time-library.md) compiler option. - That is, a debug, multithread, and DLL-specific version of the CRT. Such an app is not supported on the Windows Runtime. + That is, a debug, multithread, and DLL-specific version of the CRT. Such an app isn't supported on the Windows Runtime. -For a complete list of CRT functions that are not available in a UWP app and suggestions for alternative functions, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +For a complete list of CRT functions that aren't available in a UWP app and suggestions for alternative functions, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## See also -[Compatibility](../c-runtime-library/compatibility.md)
-[Windows Runtime Unsupported CRT Functions](../c-runtime-library/windows-runtime-unsupported-crt-functions.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Compatibility](./compatibility.md)\ +[Windows Runtime unsupported CRT functions](./windows-runtime-unsupported-crt-functions.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ [Create a Universal Windows Platform console app](/windows/uwp/launch-resume/console-uwp) diff --git a/docs/cloud/cloud-and-web-programming-in-visual-cpp.md b/docs/cloud/cloud-and-web-programming-in-visual-cpp.md index 8ae34ccfbc..f2c9b0519b 100644 --- a/docs/cloud/cloud-and-web-programming-in-visual-cpp.md +++ b/docs/cloud/cloud-and-web-programming-in-visual-cpp.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: Cloud and Web Programming in Visual C++" title: "Cloud and Web Programming in Visual C++" +description: "Learn more about: Cloud and Web Programming in Visual C++" ms.date: "05/14/2019" -ms.assetid: b63611f1-9723-44d0-ba7f-c3ebef341313 ms.topic: "overview" ms.custom: intro-overview --- @@ -43,7 +42,7 @@ In C++, you have several options for connecting to the web and the cloud. - [Windows::Web::Http::HttpClient](/uwp/api/windows.web.http.httpclient) - A Windows Runtime HTTP client class modeled on the .NET Framework class of the same name in the System.Web namespace. `HttpClient` fully supports asynchronous upload and download over HTTP, and pipeline filters that enable the insertion of custom HTTP handlers into the pipeline. The Windows SDK includes sample filters for metered networks, OAuth authentication, and more. For apps that target only Universal Windows Platform, we recommend that you use the `Windows::Web:HttpClient` class. + A Windows Runtime HTTP client class modeled on the .NET Framework class of the same name in the System.Web namespace. `HttpClient` fully supports asynchronous upload and download over HTTP, and pipeline filters that enable the insertion of custom HTTP handlers into the pipeline. The Windows SDK includes sample filters for metered networks, OAuth authentication, and more. For apps that target only Universal Windows Platform, we recommend that you use the `Windows::Web::Http::HttpClient` class. - [IXMLHTTPRequest2 interface](/windows/win32/api/msxml6/nn-msxml6-ixmlhttprequest2) @@ -55,6 +54,6 @@ In C++, you have several options for connecting to the web and the cloud. ## See also -[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)
-[Microsoft Azure C and C++ Developer Center](https://azure.microsoft.com/develop/cpp/)
+[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)\ +[Microsoft Azure C and C++ Developer Center](https://azure.microsoft.com/develop/cpp/)\ [Networks and web services (UWP)](/windows/uwp/networking/) diff --git a/docs/code-quality/annotating-locking-behavior.md b/docs/code-quality/annotating-locking-behavior.md index 8b1f8bb236..a362074bad 100644 --- a/docs/code-quality/annotating-locking-behavior.md +++ b/docs/code-quality/annotating-locking-behavior.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Annotating Locking Behavior" title: Annotating Locking Behavior -ms.date: 11/04/2016 +ms.date: 08/24/2022 ms.topic: "conceptual" f1_keywords: - "_Releases_nonreentrant_lock_" @@ -33,15 +33,15 @@ ms.assetid: 07769c25-9b97-4ab7-b175-d1c450308d7a To avoid concurrency bugs in your multithreaded program, always follow an appropriate locking discipline and use SAL annotations. -Concurrency bugs are notoriously hard to reproduce, diagnose, and debug because they are non-deterministic. Reasoning about thread interleaving is difficult at best, and becomes impractical when you are designing a body of code that has more than a few threads. Therefore, it's good practice to follow a locking discipline in your multithreaded programs. For example, obeying a lock order while acquiring multiple locks helps avoid deadlocks, and acquiring the proper guarding lock before accessing a shared resource helps prevent race conditions. +Concurrency bugs are notoriously hard to reproduce, diagnose, and debug because they're nondeterministic. Reasoning about thread interleaving is difficult at best, and becomes impractical when you're designing a body of code that has more than a few threads. Therefore, it's good practice to follow a locking discipline in your multithreaded programs. For example, obeying a lock order while acquiring multiple locks helps avoid deadlocks, and acquiring the proper guarding lock before accessing a shared resource helps prevent race conditions. -Unfortunately, seemingly simple locking rules can be surprisingly hard to follow in practice. A fundamental limitation in today's programming languages and compilers is that they do not directly support the specification and analysis of concurrency requirements. Programmers have to rely on informal code comments to express their intentions about how they use locks. +Unfortunately, seemingly simple locking rules can be surprisingly hard to follow in practice. A fundamental limitation in today's programming languages and compilers is that they don't directly support the specification and analysis of concurrency requirements. Programmers have to rely on informal code comments to express their intentions about how they use locks. Concurrency SAL annotations are designed to help you specify locking side effects, locking responsibility, data guardianship, lock order hierarchy, and other expected locking behavior. By making implicit rules explicit, SAL concurrency annotations provide a consistent way for you to document how your code uses locking rules. Concurrency annotations also enhance the ability of code analysis tools to find race conditions, deadlocks, mismatched synchronization operations, and other subtle concurrency errors. ## General Guidelines -By using annotations, you can state the contracts that are implied by function definitions between implementations (callees) and clients (callers), and express invariants and other properties of the program that can further improve analysis. +By using annotations, you can state the contracts that are implied by function definitions between implementations (callees) and clients (callers). You can also express invariants and other properties of the program that can further improve analysis. SAL supports many different kinds of locking primitives—for example, critical sections, mutexes, spin locks, and other resource objects. Many concurrency annotations take a lock expression as a parameter. By convention, a lock is denoted by the path expression of the underlying lock object. @@ -51,7 +51,7 @@ Some thread ownership rules to keep in mind: - Mutexes and critical sections are counted locks that have clear thread ownership. -- Semaphores and events are counted locks that do not have clear thread ownership. +- Semaphores and events are counted locks that don't have clear thread ownership. ## Locking Annotations @@ -64,13 +64,13 @@ The following table lists the locking annotations. |`_Acquires_nonreentrant_lock_(expr)`|The lock that's named by `expr` is acquired. An error is reported if the lock is already held.| |`_Acquires_shared_lock_(expr)`|Annotates a function and indicates that in post state the function increments by one the shared lock count of the lock object that's named by `expr`.| |`_Create_lock_level_(name)`|A statement that declares the symbol `name` to be a lock level so that it may be used in the annotations `_Has_Lock_level_` and `_Lock_level_order_`.| -|`_Has_lock_kind_(kind)`|Annotates any object to refine the type information of a resource object. Sometimes a common type is used for different kinds of resources and the overloaded type is not sufficient to distinguish the semantic requirements among various resources. Here's a list of pre-defined `kind` parameters:

`_Lock_kind_mutex_`
Lock kind ID for mutexes.

`_Lock_kind_event_`
Lock kind ID for events.

`_Lock_kind_semaphore_`
Lock kind ID for semaphores.

`_Lock_kind_spin_lock_`
Lock kind ID for spin locks.

`_Lock_kind_critical_section_`
Lock kind ID for critical sections.| +|`_Has_lock_kind_(kind)`|Annotates any object to refine the type information of a resource object. Sometimes a common type is used for different kinds of resources and the overloaded type isn't sufficient to distinguish the semantic requirements among various resources. Here's a list of predefined `kind` parameters:

`_Lock_kind_mutex_`
Lock kind ID for mutexes.

`_Lock_kind_event_`
Lock kind ID for events.

`_Lock_kind_semaphore_`
Lock kind ID for semaphores.

`_Lock_kind_spin_lock_`
Lock kind ID for spin locks.

`_Lock_kind_critical_section_`
Lock kind ID for critical sections.| |`_Has_lock_level_(name)`|Annotates a lock object and gives it the lock level of `name`.| |`_Lock_level_order_(name1, name2)`|A statement that gives the lock ordering between `name1` and `name2`. Locks that have level `name1` must be acquired before locks that have level `name2`.| -|`_Post_same_lock_(expr1, expr2)`|Annotates a function and indicates that in post state the two locks, `expr1` and `expr2`, are treated as if they are the same lock object.| +|`_Post_same_lock_(dst, src)`|Annotates a function and indicates that in post state the two locks, `dst` and `src`, are treated as if they're the same lock object, by applying lock properties from `src` to `dst`.| |`_Releases_exclusive_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the exclusive lock count of the lock object that's named by `expr`.| |`_Releases_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the lock count of the lock object that's named by `expr`.| -|`_Releases_nonreentrant_lock_(expr)`|The lock that's named by `expr` is released. An error is reported if the lock is not currently held.| +|`_Releases_nonreentrant_lock_(expr)`|The lock that's named by `expr` is released. An error is reported if the lock isn't currently held.| |`_Releases_shared_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the shared lock count of the lock object that's named by `expr`.| |`_Requires_lock_held_(expr)`|Annotates a function and indicates that in pre state the lock count of the object that's named by `expr` is at least one.| |`_Requires_lock_not_held_(expr)`|Annotates a function and indicates that in pre state the lock count of the object that's named by `expr` is zero.| @@ -80,7 +80,7 @@ The following table lists the locking annotations. ## SAL Intrinsics For Unexposed Locking Objects -Certain lock objects are not exposed by the implementation of the associated locking functions. The following table lists SAL intrinsic variables that enable annotations on functions that operate on those unexposed lock objects. +Certain lock objects aren't exposed by the implementation of the associated locking functions. The following table lists SAL intrinsic variables that enable annotations on functions that operate on those unexposed lock objects. |Annotation|Description| |----------------|-----------------| @@ -97,21 +97,21 @@ The following table lists the annotations for shared data access. |----------------|-----------------| |`_Guarded_by_(expr)`|Annotates a variable and indicates that whenever the variable is accessed, the lock count of the lock object that's named by `expr` is at least one.| |`_Interlocked_`|Annotates a variable and is equivalent to `_Guarded_by_(_Global_interlock_)`.| -|`_Interlocked_operand_`|The annotated function parameter is the target operand of one of the various Interlocked functions. Those operands must have specific additional properties.| +|`_Interlocked_operand_`|The annotated function parameter is the target operand of one of the various Interlocked functions. Those operands must have other specific properties.| |`_Write_guarded_by_(expr)`|Annotates a variable and indicates that whenever the variable is modified, the lock count of the lock object that's named by `expr` is at least one.| ## Smart Lock and RAII Annotations -Smart locks typically wrap native locks and manage their lifetime. The following table lists annotations that can be used with smart locks and RAII coding patterns with support for `move` semantics. +Smart locks typically wrap native locks and manage their lifetime. The following table lists annotations that can be used with smart locks and Resource Acquisition Is Initialization (RAII) coding patterns with support for `move` semantics. |Annotation|Description| |----------------|-----------------| -|`_Analysis_assume_smart_lock_acquired_`|Tells the analyzer to assume that a smart lock has been acquired. This annotation expects a reference lock type as its parameter.| -|`_Analysis_assume_smart_lock_released_`|Tells the analyzer to assume that a smart lock has been released. This annotation expects a reference lock type as its parameter.| -|`_Moves_lock_(target, source)`|Describes `move constructor` operation which transfers lock state from the `source` object to the `target`. The `target` is considered a newly constructed object, so any state it had before is lost and replaced by the `source` state. The `source` is also reset to a clean state with no lock counts or aliasing target, but aliases pointing to it remain unchanged.| -|`_Replaces_lock_(target, source)`|Describes `move assignment operator` semantics where the target lock is released before transferring the state from the source. This can be regarded as a combination of `_Moves_lock_(target, source)` preceded by a `_Releases_lock_(target)`.| -|`_Swaps_locks_(left, right)`|Describes the standard `swap` behavior which assumes that objects `left` and `right` exchange their state. The state exchanged includes lock count and aliasing target, if present. Aliases that point to the `left` and `right` objects remain unchanged.| -|`_Detaches_lock_(detached, lock)`|Describes a scenario in which a lock wrapper type allows dissociation with its contained resource. This is similar to how `std::unique_ptr` works with its internal pointer: it allows programmers to extract the pointer and leave its smart pointer container in a clean state. Similar logic is supported by `std::unique_lock` and can be implemented in custom lock wrappers. The detached lock retains its state (lock count and aliasing target, if any), while the wrapper is reset to contain zero lock count and no aliasing target, while retaining its own aliases. There's no operation on lock counts (releasing and acquiring). This annotation behaves exactly as `_Moves_lock_` except that the detached argument should be **`return`** rather than **`this`**.| +|`_Analysis_assume_smart_lock_acquired_(lock)`|Tells the analyzer to assume that a smart lock was acquired. This annotation expects a reference lock type as its parameter.| +|`_Analysis_assume_smart_lock_released_(lock)`|Tells the analyzer to assume that a smart lock was released. This annotation expects a reference lock type as its parameter.| +|`_Moves_lock_(target, source)`|Describes a `move constructor` operation, which transfers lock state from the `source` object to the `target`. The `target` is considered a newly constructed object, so any state it had before is lost and replaced by the `source` state. The `source` is also reset to a clean state with no lock counts or aliasing target, but aliases pointing to it remain unchanged.| +|`_Replaces_lock_(target, source)`|Describes `move assignment operator` semantics where the target lock is released before transferring the state from the source. You can regard it as a combination of `_Moves_lock_(target, source)` preceded by a `_Releases_lock_(target)`.| +|`_Swaps_locks_(left, right)`|Describes the standard `swap` behavior, which assumes that objects `left` and `right` exchange their state. The state exchanged includes lock count and aliasing target, if present. Aliases that point to the `left` and `right` objects remain unchanged.| +|`_Detaches_lock_(detached, lock)`|Describes a scenario in which a lock wrapper type allows dissociation with its contained resource. It's similar to how `std::unique_ptr` works with its internal pointer: it allows programmers to extract the pointer and leave its smart pointer container in a clean state. Similar logic is supported by `std::unique_lock` and can be implemented in custom lock wrappers. The detached lock retains its state (lock count and aliasing target, if any), while the wrapper is reset to contain zero lock count and no aliasing target, while retaining its own aliases. There's no operation on lock counts (releasing and acquiring). This annotation behaves exactly as `_Moves_lock_` except that the detached argument should be **`return`** rather than **`this`**.| ## See also diff --git a/docs/code-quality/annotating-structs-and-classes.md b/docs/code-quality/annotating-structs-and-classes.md index f58ce2ad82..1c19f33cdd 100644 --- a/docs/code-quality/annotating-structs-and-classes.md +++ b/docs/code-quality/annotating-structs-and-classes.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Annotating Structs and Classes" title: Annotating Structs and Classes +description: "Learn more about: Annotating Structs and Classes" ms.date: 06/28/2019 ms.topic: "conceptual" f1_keywords: @@ -19,7 +19,6 @@ f1_keywords: - "_Field_size_full_" - "_Field_size_full_opt_" - "_Field_z_" -ms.assetid: b8278a4a-c86e-4845-aa2a-70da21a1dd52 --- # Annotating Structs and Classes @@ -52,13 +51,11 @@ You can annotate struct and class members by using annotations that act like inv Applies to struct or class declaration. Indicates that a valid object of that type may be larger than the declared type, with the number of bytes being specified by `size`. For example: ```cpp - typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... }; - ``` The buffer size in bytes of a parameter `pM` of type `MyStruct *` is then taken to be: @@ -97,7 +94,7 @@ Notes for this example: - `_Field_z_` is equivalent to `_Null_terminated_`. `_Field_z_` for the name field specifies that the name field is a null-terminated string. - `_Field_range_` for `bufferSize` specifies that the value of `bufferSize` should be within 1 and `MaxBufferSize` (both inclusive). -- The end results of the `_Struct_size_bytes_` and `_Field_size_` annotations are equivalent. For structures or classes that have a similar layout, `_Field_size_` is easier to read and maintain, because it has fewer references and calculations than the equivalent `_Struct_size_bytes_` annotation. `_Field_size_` doesn’t require conversion to the byte size. If byte size is the only option, for example, for a void pointer field, `_Field_size_bytes_` can be used. If both `_Struct_size_bytes_` and `_Field_size_` exist, both will be available to tools. It is up to the tool what to do if the two annotations disagree. +- The end results of the `_Struct_size_bytes_` and `_Field_size_` annotations are equivalent. For structures or classes that have a similar layout, `_Field_size_` is easier to read and maintain, because it has fewer references and calculations than the equivalent `_Struct_size_bytes_` annotation. `_Field_size_` doesn't require conversion to the byte size. If byte size is the only option, for example, for a void pointer field, `_Field_size_bytes_` can be used. If both `_Struct_size_bytes_` and `_Field_size_` exist, both will be available to tools. It is up to the tool what to do if the two annotations disagree. ## See also diff --git a/docs/code-quality/best-practices-and-examples-sal.md b/docs/code-quality/best-practices-and-examples-sal.md index db4efb4f09..320b8100d3 100644 --- a/docs/code-quality/best-practices-and-examples-sal.md +++ b/docs/code-quality/best-practices-and-examples-sal.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: Best Practices and Examples (SAL)" -title: Best Practices and Examples (SAL) -ms.date: 11/04/2016 +description: "Learn more about: Best practices and examples (SAL)" +title: Best practices and examples (SAL) +ms.date: 03/30/2023 ms.topic: "conceptual" --- -# Best Practices and Examples (SAL) +# Best practices and examples (SAL) Here are some ways to get the most out of the Source Code Annotation Language (SAL) and avoid some common problems. -## \_In\_ +## `_In_` -If the function is supposed to write to the element, use `_Inout_` instead of `_In_`. This is particularly relevant in cases of automated conversion from older macros to SAL. Prior to SAL, many programmers used macros as comments—macros that were named `IN`, `OUT`, `IN_OUT`, or variants of these names. Although we recommend that you convert these macros to SAL, we also urge you to be careful when you convert them because the code might have changed since the original prototype was written and the old macro might no longer reflect what the code does. Be especially careful about the `OPTIONAL` comment macro because it is frequently placed incorrectly—for example, on the wrong side of a comma. +If the function is supposed to write to the element, use `_Inout_` instead of `_In_`. This is relevant in cases of automated conversion from older macros to SAL. Prior to SAL, many programmers used macros as comments—macros that were named `IN`, `OUT`, `IN_OUT`, or variants of these names. Although we recommend that you convert these macros to SAL, we also urge you to be careful when you convert them because the code might have changed since the original prototype was written and the old macro might no longer reflect what the code does. Be especially careful about the `OPTIONAL` comment macro because it's frequently placed incorrectly—for example, on the wrong side of a comma. ```cpp +#include // Incorrect void Func1(_In_ int *p1) @@ -24,7 +25,10 @@ void Func1(_In_ int *p1) } // Correct -void Func2(_Inout_ PCHAR p1) +// _Out_opt_ because the function tolerates NULL as a valid argument, i.e. +// no error is returned. If the function didn't check p1 for NULL, then +// _Out_ would be the better choice +void Func2(_Out_opt_ PCHAR p1) { if (p1 == NULL) return; @@ -33,11 +37,12 @@ void Func2(_Inout_ PCHAR p1) } ``` -## \_opt\_ +## `_opt_` -If the caller is not allowed to pass in a null pointer, use `_In_` or `_Out_` instead of `_In_opt_` or `_Out_opt_`. This applies even to a function that checks its parameters and returns an error if it is NULL when it should not be. Although having a function check its parameter for unexpected NULL and return gracefully is a good defensive coding practice, it does not mean that the parameter annotation can be of an optional type (`_*Xxx*_opt_`). +If the caller isn't allowed to pass in a null pointer, use `_In_` or `_Out_` instead of `_In_opt_` or `_Out_opt_`. This applies even to a function that checks its parameters and returns an error if it's `NULL` when it shouldn't be. Although having a function check its parameter for unexpected `NULL` and return gracefully is a good defensive coding practice, it doesn't mean that the parameter annotation can be of an optional type (`_*Xxx*_opt_`). ```cpp +#include // Incorrect void Func1(_Out_opt_ int *p1) @@ -52,15 +57,16 @@ void Func2(_Out_ int *p1) } ``` -## \_Pre\_defensive\_ and \_Post\_defensive\_ +## `_Pre_defensive_` and `_Post_defensive_` -If a function appears at a trust boundary, we recommend that you use the `_Pre_defensive_` annotation. The "defensive" modifier modifies certain annotations to indicate that, at the point of call, the interface should be checked strictly, but in the implementation body it should assume that incorrect parameters might be passed. In that case, `_In_ _Pre_defensive_` is preferred at a trust boundary to indicate that although a caller will get an error if it attempts to pass NULL, the function body will be analyzed as if the parameter might be NULL, and any attempts to de-reference the pointer without first checking it for NULL will be flagged. A `_Post_defensive_` annotation is also available, for use in callbacks where the trusted party is assumed to be the caller and the untrusted code is the called code. +If a function appears at a trust boundary, we recommend that you use the `_Pre_defensive_` annotation. The "defensive" modifier modifies certain annotations to indicate that, at the point of call, the interface should be checked strictly, but in the implementation body it should assume that incorrect parameters might be passed. In that case, `_In_ _Pre_defensive_` is preferred at a trust boundary to indicate that although a caller gets an error if it attempts to pass `NULL`, the function body is analyzed as if the parameter might be `NULL`, and any attempts to dereference the pointer without first checking it for `NULL` are flagged. A `_Post_defensive_` annotation is also available, for use in callbacks where the trusted party is assumed to be the caller and the untrusted code is the called code. -## \_Out\_writes\_ +## `_Out_writes_` The following example demonstrates a common misuse of `_Out_writes_`. ```cpp +#include // Incorrect void Func1(_Out_writes_(size) CHAR *pb, @@ -68,11 +74,12 @@ void Func1(_Out_writes_(size) CHAR *pb, ); ``` -The annotation `_Out_writes_` signifies that you have a buffer. It has `cb` bytes allocated, with the first byte initialized on exit. This annotation is not strictly wrong and it is helpful to express the allocated size. However, it does not tell how many elements are initialized by the function. +The annotation `_Out_writes_` signifies that you have a buffer. It has `cb` bytes allocated, with the first byte initialized on exit. This annotation isn't strictly wrong and it's helpful to express the allocated size. However, it doesn't tell how many elements the function initializes. The next example shows three correct ways to fully specify the exact size of the initialized portion of the buffer. ```cpp +#include // Correct void Func1(_Out_writes_to_(size, *pCount) CHAR *pb, @@ -89,11 +96,12 @@ void Func3(_Out_writes_(size) PSTR pb, ); ``` -## \_Out\_ PSTR +## `_Out_ PSTR` -The use of `_Out_ PSTR` is almost always wrong. This is interpreted as having an output parameter that points to a character buffer and it is NULL-terminated. +The use of `_Out_ PSTR` is almost always wrong. This combination is interpreted as having an output parameter that points to a character buffer and the buffer is null-terminated. ```cpp +#include // Incorrect void Func1(_Out_ PSTR pFileName, size_t n); @@ -102,13 +110,14 @@ void Func1(_Out_ PSTR pFileName, size_t n); void Func2(_Out_writes_(n) PSTR wszFileName, size_t n); ``` -An annotation like `_In_ PCSTR` is common and useful. It points to an input string that has NULL termination because the precondition of `_In_` allows the recognition of a NULL-terminated string. +An annotation like `_In_ PCSTR` is common and useful. It points to an input string that has null termination because the precondition of `_In_` allows the recognition of a null-terminated string. -## \_In\_ WCHAR* p +## `_In_ WCHAR* p` -`_In_ WCHAR* p` says that there is an input pointer `p` that points to one character. However, in most cases, this is probably not the specification that is intended. Instead, what is probably intended is the specification of a NULL-terminated array; to do that, use `_In_ PWSTR`. +`_In_ WCHAR* p` says that there's an input pointer `p` that points to one character. However, in most cases, this is probably not the specification that is intended. Instead, what is probably intended is the specification of a null-terminated array; to do that, use `_In_ PWSTR`. ```cpp +#include // Incorrect void Func1(_In_ WCHAR* wszFileName); @@ -117,9 +126,11 @@ void Func1(_In_ WCHAR* wszFileName); void Func2(_In_ PWSTR wszFileName); ``` -Missing the proper specification of NULL termination is common. Use the appropriate `STR` version to replace the type, as shown in the following example. +Missing the proper specification of null termination is common. Use the appropriate `STR` version to replace the type, as shown in the following example. ```cpp +#include +#include // Incorrect BOOL StrEquals1(_In_ PCHAR p1, _In_ PCHAR p2) @@ -134,11 +145,12 @@ BOOL StrEquals2(_In_ PSTR p1, _In_ PSTR p2) } ``` -## \_Out\_range\_ +## `_Out_range_` -If the parameter is a pointer and you want to express the range of the value of the element that is pointed to by the pointer, use `_Deref_out_range_` instead of `_Out_range_`. In the following example, the range of *pcbFilled is expressed, not pcbFilled. +If the parameter is a pointer and you want to express the range of the value of the element that's pointed to by the pointer, use `_Deref_out_range_` instead of `_Out_range_`. In the following example, the range of *pcbFilled is expressed, not pcbFilled. ```cpp +#include // Incorrect void Func1( @@ -155,13 +167,14 @@ void Func2( ); ``` -`_Deref_out_range_(0, cbSize)` is not strictly required for some tools because it can be inferred from `_Out_writes_to_(cbSize,*pcbFilled)`, but it is shown here for completeness. +`_Deref_out_range_(0, cbSize)` isn't strictly required for some tools because it can be inferred from `_Out_writes_to_(cbSize,*pcbFilled)`, but it's shown here for completeness. -## Wrong context in \_When\_ +## Wrong context in `_When_` Another common mistake is to use post-state evaluation for preconditions. In the following example, `_Requires_lock_held_` is a precondition. ```cpp +#include // Incorrect _When_(return == 0, _Requires_lock_held_(p->cs)) @@ -172,11 +185,11 @@ _When_(flag == 0, _Requires_lock_held_(p->cs)) int Func2(_In_ MyData *p, int flag); ``` -The expression `result` refers to a post-state value that is not available in pre-state. +The expression `return` refers to a post-state value that isn't available in pre-state. -## TRUE in \_Success\_ +## `TRUE` in `_Success_` -If the function succeeds when the return value is nonzero, use `return != 0` as the success condition instead of `return == TRUE`. Nonzero does not necessarily mean equivalence to the actual value that the compiler provides for `TRUE`. The parameter to `_Success_` is an expression, and the following expressions are evaluated as equivalent: `return != 0`, `return != false`, `return != FALSE`, and `return` with no parameters or comparisons. +If the function succeeds when the return value is nonzero, use `return != 0` as the success condition instead of `return == TRUE`. Nonzero doesn't necessarily mean equivalence to the actual value that the compiler provides for `TRUE`. The parameter to `_Success_` is an expression, and the following expressions are evaluated as equivalent: `return != 0`, `return != false`, `return != FALSE`, and `return` with no parameters or comparisons. ```cpp // Incorrect @@ -194,9 +207,10 @@ BOOL WINAPI TryEnterCriticalSection( ## Reference variable -For a reference variable, the previous version of SAL used the implied pointer as the annotation target and required the addition of a `__deref` to annotations that attached to a reference variable. This version uses the object itself and does not require the additional `_Deref_`. +For a reference variable, the previous version of SAL used the implied pointer as the annotation target and required the addition of a `__deref` to annotations that attached to a reference variable. This version uses the object itself and doesn't require `_Deref_`. ```cpp +#include // Incorrect void Func1( @@ -216,6 +230,7 @@ void Func2( The following example shows a common problem in return value annotations. ```cpp +#include // Incorrect _Out_opt_ void *MightReturnNullPtr1(); @@ -224,15 +239,15 @@ _Out_opt_ void *MightReturnNullPtr1(); _Ret_maybenull_ void *MightReturnNullPtr2(); ``` -In this example, `_Out_opt_` says that the pointer might be NULL as part of the precondition. However, preconditions cannot be applied to the return value. In this case, the correct annotation is `_Ret_maybenull_`. +In this example, `_Out_opt_` says that the pointer might be `NULL` as part of the precondition. However, preconditions can't be applied to the return value. In this case, the correct annotation is `_Ret_maybenull_`. ## See also -[Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md) -[Understanding SAL](../code-quality/understanding-sal.md) -[Annotating Function Parameters and Return Values](../code-quality/annotating-function-parameters-and-return-values.md) -[Annotating Function Behavior](../code-quality/annotating-function-behavior.md) -[Annotating Structs and Classes](../code-quality/annotating-structs-and-classes.md) -[Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md) -[Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md) -[Intrinsic Functions](../code-quality/intrinsic-functions.md) +[Using SAL annotations to reduce C/C++ code defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md)\ +[Understanding SAL](../code-quality/understanding-sal.md)\ +[Annotating function parameters and return values](../code-quality/annotating-function-parameters-and-return-values.md)\ +[Annotating function behavior](../code-quality/annotating-function-behavior.md)\ +[Annotating structs and classes](../code-quality/annotating-structs-and-classes.md)\ +[Annotating locking behavior](../code-quality/annotating-locking-behavior.md)\ +[Specifying when and where an annotation applies](../code-quality/specifying-when-and-where-an-annotation-applies.md)\ +[Intrinsic functions](../code-quality/intrinsic-functions.md) diff --git a/docs/code-quality/build-reliable-secure-programs.md b/docs/code-quality/build-reliable-secure-programs.md new file mode 100644 index 0000000000..83f1605db1 --- /dev/null +++ b/docs/code-quality/build-reliable-secure-programs.md @@ -0,0 +1,456 @@ +--- +title: Build reliable and secure C++ programs +description: "Learn more about: Building reliable and secure C++ programs by applying NISTIR 8397 guidelines." +ms.date: 04/25/2025 +ms.topic: "conceptual" +--- + +# Build reliable and secure C++ programs + +The United States government publication [NISTIR 8397: Guidelines on Minimum Standards for Developer Verification of Software](https://nvlpubs.nist.gov/nistpubs/ir/2021/NIST.IR.8397.pdf) contains excellent guidance on how to build reliable and secure software in any programming language. + +This document follows the same structure as NISTIR 8397. Each section: +- summarizes how to use Microsoft developer products for C++ and other languages to meet that section's security needs, and +- provides guidance to get the most value in each area. + +## 2.1 Threat modeling + +**Summary** + +Threat modeling is a valuable process, especially when applied in a way that scales to meet your development needs and that reduces noise. + +**Recommendations** + +Threat modeling should be one part of your dynamic Security Development Lifecycle (SDL). We suggest that for your product as a whole, for a specific feature, or for a major design or implementation change: + +- Have a solid, dynamic SDL that allows for early engagement with developer teams and rightsizing of approach. +- Apply threat modeling in a targeted way. Apply threat modeling to all features, but tactically start with exposed, complex or critical features. Do apply it regularly instead as part of a top-down product review. +- Apply threat modeling early (as with all security requirements), when there's still opportunity to change the design. Also, threat models serve as an input to other processes, such as attack surface reduction or designing for security. Threat models that are created later are at best "surveys" for pen test (penetration testing) or areas that need security testing such as fuzzing. After you create a baseline threat model, plan to continue iterating on it as the attack surface changes. +- Use asset inventory and compliance to appropriately track what makes up a product, and track security artifacts (including threat models) along with the assets they apply to. This approach enables better automated risk assessment and focusing of security efforts on the specific components or features that change. +- **In Azure**, the Microsoft Threat Modeling Tool was updated in 2022 for Azure development. For more information, see [Microsoft Threat Modeling Tool overview - Azure](/azure/security/develop/threat-modeling-tool) + +**Supporting factors and practices** + +To properly apply threat modeling and avoid underuse/overuse, we have found that the following core concepts need to be addressed first. + +*Development approach* + +First, understand the team's development approach. For teams with agile development workflows that push dozens of changes to production daily, it's not practical or reasonable to require a threat model update for every functional change. Instead, from the start when writing a feature's functional requirements, consider including a security requirements questionnaire. The questionnaire should focus on specific questions about the feature to determine what future aspects of your SDL apply. For example: +- Does the feature make a major change in design of how we provide customer isolation in a multitenant environment? If so, consider performing a full threat model. +- Does a new feature allow file uploads? If so, perhaps what's more appropriate is a web application security assessment. +- Is this change primarily just a functional UI change? If so, perhaps nothing is needed beyond your traditional automated tooling. + +The security questionnaire results inform which SDL techniques to tie to which unit of development. It also informs development partners of the feature's SDL timelines, so they can collaborate at the right times. + +*Product inventory* + +Second, maintain a strong asset inventory of the products you're tasked with assessing. Products are growing in complexity. It's common to write software for connected devices that have: +- sensors (such as passenger rail and vehicles), +- bus-based networks that talk to other components in the vehicle (such as CANBUS or PROFIBUS), +- wireless/cellular/Bluetooth for communication with customer devices and cloud back ends, +- machine learning in the cloud feeding back into the device or a fleet management application, +- and more. + +In such complex products, threat modeling is critical. Having a strong asset inventory lets you view the entire product stack to see the complete picture, and to see the key places that need to be evaluated for how a new or changed feature impacts product security. + +*Granularity and integration* + +Establish systems to measure compliance using clear metrics. +- Regularly measure compliance for feature level development. Feature compliance generally should be measured with higher frequency and smaller granularity, sometimes even on the developer's system or at code commit/merge time. +- Periodically evaluate security for the broader product in which a feature or component is being consumed. Broader evaluations typically are done with lower frequency and broader granularity, such as at module or system testing time. + +*Scale* + +Keep a proper asset inventory system that captures and preserves security artifacts and the output of threat model reviews. Having a clear inventory lets you evaluate review outputs for patterns, and make intelligent decisions on how to refine the product security program regularly. + +Try to combine requirements-phase security questionnaires, threat modeling results, security assessment results, and results from automated tools. Combining them enables you to automate a viewpoint of relative risk of a given product, ideally as a "dashboard," to inform your security teams what to focus on to get the best value out of the threat modeling. + +## 2.2 Automated testing + +**Summary** + +Automated tests are an important way to ensure the quality and safety of your code. They're an integral piece in supporting other areas mentioned in this document, such as Threat Modeling. When paired with other secure coding practices, they help to protect against bugs and vulnerabilities being introduced into the codebase. + +**Key attributes** + +Tests should be reliable, consistent, and isolated. These tests should cover as much of the code as possible. All new features and bug fixes should have corresponding tests to ensure the long-term security and reliability of the code when possible. Run automated tests regularly and in as many environments as possible, to ensure they get run and that they cover all areas: + +- The first place they should run is on the machine that is making the changes. Running tests is most easily done within the IDE that is being used for editing, or as a script on the command line as the developer makes the changes. +- The next place they should run is as part of the pull request commit/merge process. +- The last place to run tests is as part of a Continuous Integration and Continuous Deployment (CI/CD) pipeline, or on your release candidate builds. + +The scope of the tests should increase at each step, with the last step providing full coverage for anything the other steps might miss. + +**Continuous use and maintenance** + +Test reliability is an important part of maintaining the effectiveness of the testing suite. Test failures should be assigned and investigated, with potential security issues getting high priority and getting updated within a prompt and predetermined timeframe. Ignoring test failures shouldn't be a common practice, but should require strong justification and approval. Test failures due to issues within the test suite itself should be treated the same as other failures, to prevent a lapse in coverage in which product issues could be missed. + +**Kinds of tests, especially unit tests** + +There are several types of automated tests, and while not all are applicable to all applications, a good test suite contains a selection of several different types. Code Based Test Cases such as unit tests are the most common and most integral, being applicable to all applications and intentionally covering as many code paths as possible for correctness. These tests should be small, quick, and not affect the state of the machine, so that the full suite of tests can be run quickly and often. If possible, run tests on many machines that have different hardware setups to catch problems that aren't reproducible on a single type of machine. + +**Visual Studio** + +Visual Studio Test Explorer natively supports many of the most popular C++ testing frameworks, and has options to install extensions for more frameworks. This flexibility is helpful for running a subset of tests covering the code you're working on, and makes it easy to debug test failures as they arise. Visual Studio also makes it easy to set up new test suites for existing projects, and provides helpful tools such as CodeLens to make it easier to manage these tests. For more information about writing, running, and managing C/C++ tests with Visual Studio, see [Write unit tests for C/C++ - Visual Studio (Windows)](/visualstudio/test/writing-unit-tests-for-c-cpp). + +**In Azure and GitHub CI/CD** + +Tests that do deeper verification and take longer to run, such as static analysis, component detection, and so on, are good candidates for pull request testing or continuous integration testing. Azure DevOps and GitHub [Actions](https://docs.github.com/en/actions) make it easy to run validations automatically and block code checkins if a validation fails. Automated enforcement helps ensure that all code being checked in is secure based on these more rigorous checks being run. Azure Pipelines and Azure DevOps Build Validation are described here: + +- [Git branch policies and settings - Azure Repos](/azure/devops/repos/git/branch-policies#build-validation) +- [Defining the mergeability of pull requests | GitHub Docs](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests) + +## 2.3 Code-based, or static, analysis + +**Summary** Static code/binary analysis should be enabled by default, to be secure by default. Static analysis analyzes a program for required safety and security policies at the time it's being built, not at execution time when an exploit can occur on the customer's machine. Static analysis can analyze the program in source code form or in compiled executable form. + +**Recommendations** Microsoft recommends that you: + +- Enable static analysis for all C++ programs, for both the input source code (before compilation) and the executable binaries (after compilation). "Enable" might mean to run analysis during each build on the developer's machine, or as a separate build to inspect the code later or as a checkin requirement. +- Incorporate static analysis into CI pipelines as a form of testing. +- Static analysis by definition comes with false positives, and be prepared to incorporate that fact into your quality feedback loop. Be quick to enable all low-false-positive warnings up front. Then be proactive to gradually increase the number of rules for which your code base compiles warning-clean as you regularly add more rules that flag important bugs at the expense of gradually higher false positives (initially, before the code base has been cleaned for those rules too). +- Always use the latest supported versions of Visual Studio, and set up your engineering environment to quickly consume the latest patch releases as soon as they become available, without delaying to the next development stage/cycle. + +**Key tools** Be aware of and use the following: + +- [Code analysis documentation - C++ and .NET](/visualstudio/code-quality/) +- [`/analyze` - Visual C++ compiler](../build/reference/analyze-code-analysis.md) +- [`/W4` and `/WX` - Visual C++ compiler](../build/reference/compiler-option-warning-level.md) +- [Use the C++ Core Guidelines Checkers](using-the-cpp-core-guidelines-checkers.md) +- [CodeQL | GitHub](https://codeql.github.com/) +- [Binskim user guide | GitHub](https://github.com/microsoft/binskim/blob/main/docs/UserGuide.md) +- See also (Windows only): [SAL annotations](../c-runtime-library/sal-annotations.md) + +Notes: + +- `/analyze` enables static analysis of C++ code at compile time to identify critical security and reliability code vulnerabilities. It should be enabled throughout a C++ program's entire development timeline. Start by enabling at least the "Microsoft Native Recommended" by default as a minimum baseline. Then consult the documentation for how to specify more rules, especially the C++ Core Guidelines rules, as required by your engineering policies. The source code Static Analysis capability is available in both the Visual C++ IDE and in the command-line Build Tools. +- `/W4` and `/WX` should be enabled wherever possible, to ensure you compile your code cleanly at high warning levels (`W4`) and treat warnings as errors that must be fixed (`WX`). These options enable finding uninitialized data errors that other static analysis tools can't check, because the errors only become visible after the compiler back-end performs interprocedural analysis and inlining. +- BinSkim binary analysis ensures that projects enable a broad range of security features. BinSkim generates PDBs and other outputs that make it easier to verify chain-of-custody and to respond efficiently to security issues. Microsoft recommends running the BinSkim tool to analyze all executable binaries (`.sys`, `.dll` or `.exe`) produced for or consumed by your programs. The BinSkim User Guide includes a list of supported security standards. Microsoft recommends that you fix all issues reported as "errors" by the BinSkim tool. Issues reported as "warnings" should be evaluated selectively, because resolving them can have performance implications or might not be necessary. + +**In Azure and GitHub CI/CD** Microsoft recommends always enabling source code and binary static analysis in release CI/CD scenarios. Run source analysis immediately on the local developer's machine, or at least for every commit or pull request, to catch source bugs as early as possible and minimize overall costs. Binary level bugs tend to be introduced more slowly, so it might be sufficient to run binary analysis in less frequent prerelease CI/CD scenarios (such as nightly or weekly builds). + +## 2.4 Review for hardcoded secrets + +**Summary** + +Don't hardcode secrets within software. You can find and remove secrets from the source code efficiently by using reliable tools that can scan your entire source code base. Once you find secrets, move them to a safe place following the guideline for secure storage and use of secrets. + +**Problem** + +"Secrets" means entities that establish identity and provide access to resources, or that are used to sign or encrypt sensitive data. Examples include passwords, storage keys, connection strings, and private keys. It's tempting to keep secrets in the software product so they can be readily obtained when needed by the software. However, these hardcoded secrets can lead to severe or catastrophic security incidents as they're easily discovered and can be used to compromise your service and data. + +**Prevention** + +Secrets hardcoded in source code (as plain text or encrypted blob) are a security vulnerability. Here are general guidelines on how to avoid secrets in the source code: + +- Use a precheckin tool to scan and catch potential hardcoded secrets in code prior submitting to source control. +- Don't put clear text credentials in source code or configuration files. +- Don't store clear text credentials in SharePoint, OneNote, file shares, and so on. Or share them via email, IM, and so on. +- Don't encrypt a secret with an easily discoverable decryption key. For example, don't store a PFX file along with a file that contains its password. +- Don't encrypt a secret with a weak decryption. For example, don't encrypt a PFX file with a weak or common password. +- Avoid putting encrypted credentials in source code. Instead, use placeholders in your source, and let your deployment system replace them with secrets from approved stores. +- Apply the same principles to secrets in environments such as testing, staging, and so on, as you do in production deployments. Adversaries often target nonproduction systems as they're less well managed, then use them to pivot into production. +- Don't share secrets between deployments (for example, testing, staging, production). + +While not directly related to hardcoded secrets, also remember securing secrets for your test, development, and production: + +- Rotate your secrets periodically and whenever they might have been exposed. Having a demonstrated ability to rotate/redeploy secrets is evidence of a secure system. More notably, the absence of this capability is even stronger evidence of an inevitable vulnerability. +- Don't give in to the common developer rationale that "my test credentials don't create risk." In practice, they nearly always do. +- Consider moving away from secrets (for example, passwords, bearer keys) entirely in preference of RBAC/identity-driven solutions as a good engineering solution that can sidestep secret mismanagement entirely. + +**Detection** + +Legacy components of your product might contain hidden hardcoded secrets in their source code. Sometimes secrets from developers' desktop machines can creep into remote branch and merge into the release branch, leaking secrets unintentionally. To discover secrets that might be hiding in your source code, you can use tools that can scan your code for hardcoded secrets: + +- [Microsoft sarif-pattern-matcher tool](https://github.com/microsoft/sarif-pattern-matcher) + +**Remediation** + +When credentials are found in your source code, the immediate urgent need is to invalidate the exposed key and perform a risk analysis based on exposure. Even if your system needs to stay running, you can enable a secret manager for remediation using these steps: + +1. If remediation allows switching over to managed identities, or requires dropping in a secret manager such as Azure Key Vault (AKV), do that first. Then redeploy with the updated identity or key. +1. Invalidate the exposed secret. +1. Perform auditing/risk assessment of potential damage due to compromise. + +To safeguard cryptographic keys and other secrets used by cloud apps and services, use [Azure Key Vault](https://azure.microsoft.com/products/key-vault) with an appropriate access policy. + +If an exposure compromises certain customer data/PII, it might require other compliance/reporting requirements. + +Remove the now-invalidated secrets from your source code, and replace them with alternative methods that don't expose the secrets directly in your source code. Look for opportunities to eliminate secrets where possible by using tools like Azure AD. You can update your authentication methods to take advantage of managed identities via Azure Active Directory). Only use approved stores to store and manage secrets such as Azure Key Vault (AKV). For more information, see: + +- [Azure AD: Implementing autorotation using Azure Active Directory](https://eng.ms/docs/products/onecert-certificates-key-vault-and-dsms/key-vault-dsms/autorotationandecr/scenarios/aad) + +**Azure DevOps (AzDO)** + +AzDO users can scan their code through GitHub Advanced Security for Azure DevOps (GHAzDO). GHAzDO also allows users to prevent secret exposures by enabling Push Protection on their repositories, catching potential exposures before they're ever leaked. For more information on how to detect hardcoded secrets in code in Azure DevOps, see *Secret Scanning for GitHub Advanced Security for Azure DevOps* in each of the following links: + +- [GitHub advanced security for Azure DevOps](https://azure.microsoft.com/products/devops/github-advanced-security) +- [Secret Scanning for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-secret-scanning) +- [Microsoft Defender for DevOps Preview](https://www.microsoft.com/security/business/cloud-security/microsoft-defender-devops) + +**In GitHub** + +Secret scanning is available on GitHub.com in two forms: + +- *Secret scanning alerts for partners.* Runs automatically on all public repositories. Any strings that match patterns that were provided by secret scanning partners are reported directly to the relevant partner. +- *Secret scanning alerts for users.* You can enable and configure extra scanning for repositories owned by organizations that use GitHub Enterprise Cloud and have a license for GitHub Advanced Security. These tools also support private and internal repositories. + +GitHub provides known patterns of secrets for partners and users that can be configured to meet your needs. For more information, please see: + +- [Secret scanning patterns](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets-for-user-alerts) +- [About secret scanning in GitHub](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/about-secret-scanning) + +> [!NOTE] +> GitHub Advanced Security for Azure DevOps brings the same secret scanning, dependency scanning and CodeQL code scanning solutions already available for GitHub users and natively integrates them into Azure DevOps to protect your Azure Repos and Pipelines. + +**Additional resources** + +- [Credential Scanning | Microsoft Code With Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/CI-CD/dev-sec-ops/secrets-management/credential_scanning/). +- [detect-secrets: Credential scanning tool | GitHub](https://microsoft.github.io/code-with-engineering-playbook/CI-CD/dev-sec-ops/secrets-management/recipes/detect-secrets/) - an aptly named module for detecting secrets within a code base. +- [Running detect-secrets in Azure Pipelines](https://microsoft.github.io/code-with-engineering-playbook/CI-CD/dev-sec-ops/secrets-management/recipes/detect-secrets-ado/). +- [Git-secrets | GitHub awslabs](https://github.com/awslabs/git-secrets) - prevents you from committing passwords and other sensitive information to a git repository. +- [Secrets Management | Microsoft Code with Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/CI-CD/dev-sec-ops/secrets-management/) - provides general guidelines on how secrets should be managed. + +## 2.5 Run with language- and OS-provided checks and protection + +**Summary** + +Binary hardening is done by applying compile-time security controls. These include mitigations that: +- prevent exploitable vulnerabilities in code, +- enable runtime detections that trigger security defenses on exploitation, and +- enable data production and archiving to help limit the damage caused by security incidents. + +Binary consumers must opt into Windows security features to gain the full benefit of hardening. + +Microsoft provides a set of facilities specific to C++ projects to help developers write and ship safer and more secure code. C++ developers should also adhere to security standards common to languages that generate executable code. Microsoft maintains BinSkim, a public OSS binary checker that helps enforce use of many protections described in this section. For more information about BinSkim, see [Binskim user guide | GitHub](https://github.com/microsoft/binskim/blob/main/docs/UserGuide.md) + +Binary-level controls differ according to where they're applied in the engineering process. You should distinguish among compiler and linker options that: are strictly compile time, alter code generation with run-time overhead, and alter code generation to achieve compatibility with OS protections. + +Developer settings should prefer to enable as much static analysis as possible, enable production of private data to accelerate debugging, and so on. Release builds should be tuned to an appropriate combination of security, performance, and other code generation concerns. Release processes must be configured to properly generate and manage public vs. privately consumed build data (for example, public vs. private symbols). + +**Stay current: Always use up-to-date compilers and tools** + +Compile all code with current toolsets to benefit from up-to-date language support, static analysis, code generation and security controls. Because compilers impact every generated component, the potential for regression on tool update is relatively high. Using outdated compilers creates a particular risk for corrective action while responding to a security incident, because teams might not have enough time to upgrade compilers. Microsoft recommends that teams develop the facility to regularly refresh and test compiler updates. + +**Use secure development methods, language versions, frameworks/APIs** + +Code should utilize development methodologies, language versions, framework, APIs, and so on, that minimize risk by fostering safety and simplicity in C++, including: + +- See [C++ Core Guidelines' Guideline Support Library (GSL)](https://github.com/isocpp/CppCoreGuidelines) for guidance to write modern, safe, and consistent C++ code that follows best practices and avoids common pitfalls. +- See [Microsoft GSL implementation](https://github.com/microsoft/GSL) for functions and types that the C++ Core Guidelines suggest you use. +- Resource-safe C++ containers, C runtime library (CRT) memory overflow protections: Prefer [`std::vector`](../standard-library/vector-class.md) and [`std::string`](../standard-library/string.md), which are resource-safe. If you must use C data, use the [secure versions of CRT functions](../c-runtime-library/security-features-in-the-crt.md), which are designed to help prevent memory corruption due to buffer misuse and undefined language behaviors. +- The [SafeInt library](../safeint/safeint-library.md) protects against integer overflow in mathematical and comparison operations. + +**Consume secure dependencies** + +Binaries shouldn't link to insecure libraries and dependencies. Development teams should track all external dependencies and resolve CVEs/identified security vulnerabilities in these components by updating to more secure versions when subject to those vulnerabilities. + +**Maximize code provenance guarantees and efficiency of security response** + +Compilation should enable strong code provenance guarantees to help detect and prevent introduction of backdoors and other malicious code. The resulting data, also critical to debugging and investigation, should be archived for all software releases to drive efficient security response if they're compromised. The following compiler switches generate information that is critical to a security response: + +- [`/ZH:SHA_SHA256` in Visual C++](../build/reference/zh.md) - Ensures that a cryptographically secure algorithm is used to generate all PDB source file hashes. +- [`/Zi`, `/ZI` (Debug Information Format) in Visual C++](../build/reference/z7-zi-zi-debug-information-format.md) - In addition to publishing stripped symbols for collecting crash data and other public use scenarios, ensure that builds produce and archive private PDBs for all released binaries. Binary analysis tools require full symbols to verify whether many security mitigations were enabled at compile-time. Private symbols are critical in security response, and lower debugging and investigation costs when engineers are racing to assess and limit damage when an exploit happens. +- [`/SOURCELINK` in Visual C++ Linker - Include Sourcelink file in PDB](../build/reference/sourcelink.md): Source link is a language- and source-control agnostic system providing source debugging for binaries. Source debugging greatly increases the efficiency the range of prerelease security validations and post-release incident response. + +**Enable compiler errors to prevent issues at code authoring time** + +Compilation should enable security-relevant compiler checks as breaking errors, for example: +- [`/sdl` in Visual C++ - Enable additional security checks](https://aka.ms/AdditionalSecurityChecks) elevates many security-relevant warnings into errors and enables advanced secure code-generation features. +- [BinSkim BA2007.EnableCriticalCompilerWarnings | GitHub](https://github.com/microsoft/binskim/blob/main/src/BinSkim.Rules/PERules/BA2007.EnableCriticalCompilerWarnings.cs) maintains a list of Microsoft-recommended C/C++ compiler warnings that should always be enabled and elevated to errors. + +**Mark binaries as compatible with OS runtime security mitigations** + +Compiler and linker settings should opt into code generation features that detect and mitigate malicious code execution, including: +- Stack corruption prevention + - [`/SAFESEH` - Image has safe exception handlers](https://aka.ms/SafeExceptionHandlers) - Produces a table of the image's safe exception handlers for x86 binaries. + - [`/GS` - Buffer Security Check](https://aka.ms/BufferSecurityCheck) - Detects some buffer overruns that overwrite return addresses, exception handler addresses or certain types of parameters. +- Position independent code execution + - [`/DYNAMICBASE` - Use Address Space Layout Randomization](https://aka.ms/ASLR) - Generates executable images that can be randomly rebased at load time. + - [`/HIGHENTROPVA` and `/LARGEADDRESSAWARE` - Support 64-bit ASLR, and Handle large addresses](https://aka.ms/HEVA) - Enables use of entire 64-bit address space for image rebasing. +- Code flow integrity + - [`/guard:cf` - Enable Control Flow Guard](https://aka.ms/ControlFlowGuard) - Inserts runtime verifications for indirect call targets. + - [`/CETCOMPAT` - CET shadow stack compatible](https://aka.ms/CETShadowStack) - Marks an executable image as compatible with Microsoft's implementation of Intel's [Control-flow Enforcement Technology (CET)](https://www.intel.com/content/www/us/en/developer/articles/technical/technical-look-control-flow-enforcement-technology.html) Shadow Stack feature. + - [`/guard:ehcont` - Enable EH continuation metadata](../build/reference/guard-enable-eh-continuation-metadata.md) - Generates a list of safe relative virtual addresses (RVA) of all exception handling continuation targets. +- Data execution prevention + - [`/NXCOMPAT` - Compatible with Data Execution Prevention](https://aka.ms/DataExecutionPrevention) - Marks a 32-bit executable image as compatible with the [Windows Data Execution Prevention (DEP)](https://support.microsoft.com/topic/what-is-data-execution-prevention-dep-60dabc2b-90db-45fc-9b18-512419135817) feature. 64-bit builds are compatible with DEP by default.) + +**Prevent sensitive information disclosure** + +Compiler settings should opt into sensitive information discovery prevention. In recent years, researchers have uncovered unintended information leakage that originates with hardware features such as speculative execution. + +At the software level, confidential data might be transmitted to attackers if unexpectedly leaked. Failure to zero-initialize buffers and other buffer misuse might leak private confidential data to attackers that call trusted API. This class of problem best handled by enabling extra static analysis and using secure resource containers as described previously. + +- [`/Qspectre` - Mitigate speculative execution side-channel attacks](https://aka.ms/SpectreMitigations) - Inserts barrier instructions that help prevent the disclosure of sensitive data produced by speculative execution. These mitigations should be enabled for code that stores sensitive data in memory and operates across a trust boundary. Microsoft always recommends measuring performance impact against appropriate benchmarks when enabling Spectre-mitigations due to the possibility of introducing runtime checks in performance-critical blocks or loops. These code paths can disable mitigations via the [`spectre(nomitigation)`](../cpp/spectre.md) `declspec` modifier. Projects that enable `/Qspectre` should also link to libraries that are also compiled with these mitigations, including the Microsoft runtime libraries. + +## 2.6 Black box test cases + +**Summary** + +Black box tests don't rely on knowing the tested component's inner workings. Black box tests are designed to test the end-to-end functionality of the features in the product at any layer or level. Black box tests can be functional tests, UI tests, performance tests, and integration tests. Black box tests are valuable for measuring general reliability and functional correctness, and ensuring that the product behaves as expected. + +**Relation to other sections** + +These types of requirement-based tests are useful for validating the assumptions made in the Threat Model and covering potential threats as brought up in that section. These tests are useful for testing the integration between separate components of the product, especially ones that are across trust boundaries as described in the threat model. Black box test cases are also useful for testing all kinds of edge cases for user input validation. Testing known edge cases and error cases are both useful. Fuzzing is also useful to test less obvious cases. + +**Automation and regression** + +Run these tests regularly, and compare the results to previous runs to catch breaking changes or performance regressions. Also, running these tests on many different machines and installation setups can help cover any issues that might arise from different architectures or setup changes. + +**Crash dumps** + +These tests help find issues with reliability, being able to test many different scenarios that might run into crashes, hangs, deadlocks, and so on. By collecting crash dumps as part of test failures, you can import the dumps directly into Visual Studio to further investigate what parts of the code are hitting these issues. If you run functional tests from within Visual Studio, you can easily replicate and debug failures by seeing exactly where inside the black box the test fails, and you can test fixes quickly. + +To get started with debugging tests, see [Debug unit tests with Test Explorer - Visual Studio (Windows)](/visualstudio/test/debug-unit-tests-with-test-explorer) + +**In Azure** + +Azure DevOps can also help manage and validate these tests with the use of Test Plans. These tests can be used to ensure approval with manual validation, and to run automated tests associated with product requirements. More information on Azure Test Plans and using them to run automated testing can be found here: +- [What is Azure Test Plans? Manual, exploratory, and automated test tools. - Azure Test Plans](/azure/devops/test/overview) +- [Run automated tests from test plans - Azure Test Plans](/azure/devops/test/run-automated-tests-from-test-hub) + +## 2.7 Code-based test cases + +**Summary** + +Code-based test cases are an integral part of maintaining the security and reliability of your product. These tests should be small and fast and shouldn't have an impact on each other so they can be run in parallel. Code-based tests are easy for developers to run locally on their development machine anytime they make changes to the code without worrying about slowing down their development cycle. + +**Types, and relation to other sections** + +Common types of code-based test cases include: +- unit tests, +- parameterized tests to cover functions with multiple input types, +- component tests to keep each test component separate, and +- mock testing to validate parts of the code that communicate with other services, without expanding the scope of the test to include those services themselves. + +These tests are based on the internal code that is written, whereas black box tests are based on the external functional requirements of the product. + +**Goal** + +Through these tests, the goal is to achieve a high level of test coverage over your code. You should actively track this coverage and where gaps exist. As you add more tests that exercise more code paths, the overall confidence in your code's security and reliability increases. + +**Visual Studio** + +The test explorer tools in Visual Studio make it easy to run these tests frequently and get feedback on pass/fail rates and failure locations quickly. Many of the test frameworks also support CodeLens features to see the test status at the location of the test itself, making adding and maintaining the suite of tests easier. The Test Explorer also makes managing these tests easy, allowing for test groups, custom test playlists, filtering, sorting, searching, and more. + +For more information, see: + +- [Unit testing fundamentals - Visual Studio (Windows)](/visualstudio/test/unit-test-basics) - an introduction and overview +- [Run unit tests with Test Explorer - Visual Studio (Windows)](/visualstudio/test/run-unit-tests-with-test-explorer#group-and-filter-the-test-list) - a deeper look at what's available to help manage the potentially large set of unit tests with the Test Explorer + +Visual Studio also comes with tools for tracking the code coverage. These tools enable you to ensure that code changes you make are covered by existing tests, or to add new tests to cover new and untested code paths. The tools also show the code coverage percentage to ensure it's maintained above a target level for confidence in overall code quality. + +For information about these tools, see [Code coverage testing - Visual Studio (Windows)](/visualstudio/test/using-code-coverage-to-determine-how-much-code-is-being-tested) + +**In Azure** + +Azure DevOps can also help in tracking code coverage results for the whole product as part of the build pipeline process. For more information, see [Review code coverage - Azure Pipelines](/azure/devops/pipelines/test/review-code-coverage-results). + +## 2.8 Historical test cases + +**Summary** + +Historical test cases, also known as regression test cases, prevent old issues from resurfacing again and increase the overall test coverage of the product. You should ensure that when a bug is fixed the project also adds a corresponding test case. Over time, as fixes are made, the overall robustness of the testing suite will keep improving, giving better assurances of reliability and security. + +**Key qualities, and relation to other sections** + +Since they test for bug regressions, these tests should be quick and easy to run, so they can run alongside the [Code Based Test Cases](#27-code-based-test-cases) and contribute to the overall code coverage of the product. Along with this, using real examples from customers to inspire new test cases is a great way to improve coverage and quality of tests. + +**Visual Studio** + +Visual Studio lets you easily add tests to the suite while making the changes to fix the bug, and quickly run the tests and code coverage to ensure all new cases get considered. Referencing the bug ID from your issue tracking system in your code where you write the test is a good way to connect regression tests to the corresponding issues. Prefer to use Azure Boards and test plans together with Visual Studio: +- to associate tests, test cases, and issues; and +- to track of all aspects of an issue and its corresponding tests. + +For more information, see: +- [Associate automated tests with test cases - Azure Test Plans](/azure/devops/test/associate-automated-test-with-test-case) +- [Link work items to other objects - Azure DevOps](/azure/devops/organizations/notifications/add-links-to-work-items) + +Eventually, integrating these tests into the unit testing area that is supposed to cover the code section helps keep the test suite organized and easier to manage. You can use the Test Explorer's test grouping to effectively track the tests that belong together. For more information, see [Run unit tests with Test Explorer - Visual Studio (Windows)](/visualstudio/test/run-unit-tests-with-test-explorer#group-and-filter-the-test-list) + +## 2.9 Fuzzing + +**Summary** +Fuzzing (also known as fuzz testing) is an automated software testing technique that involves providing invalid, unexpected, or random data as input to a program. The program is then monitored for exceptions such as crashes, failing built-in or compiler injected code assertions and potential memory leaks. + +**Guidance** + +Use fuzzing on all software that might process untrusted inputs that an attacker could control. If you're building a new application and its associated test suite, include fuzzing for key modules as early as possible. Running fuzzing for the first time on a piece of software nearly always uncovers actual vulnerabilities that were previously unknown. Once you start fuzzing, never stop. + +**Relation to other sections** + +When fuzzing reports a failure, it always naturally provides a reproducible test case that demonstrates the bug. This test case can be reproduced, resolved, and then added to the Historical Test Cases. + +When using both sanitizers such as [Address Sanitizer (ASan)](../sanitizers/asan.md) and fuzzing: +- First run your normal tests with sanitizers enabled to see if there are issues, then once the code is sanitizer-clean start fuzzing. +- For C or C++, there are compilers that automate injection of runtime assertions and meta-data that enable ASan. When compiled for ASan, the resulting binaries link with a runtime library that can precisely diagnose [15+ categories of memory safety errors](../sanitizers/asan.md#error-types) with zero false positives. For C or C++ when you have source, use [LibFuzzer](https://www.llvm.org/docs/LibFuzzer.html), which requires ASan to be enabled first. +- For libraries written in Java, C#, Python, Rust, and so on, use the [AFL++ framework](https://aflplus.plus/). + +**Key qualities** + +- Fuzzing finds vulnerabilities often missed by static program analysis, exhaustive feature testing and manual code inspection. +- Fuzzing is an effective way to find security and reliability bugs in software, so much so that the [Microsoft Security Development Lifecycle](https://www.microsoft.com/securityengineering/sdl/) requires fuzzing at every untrusted interface of every product (see also Threat Modeling). +- Always use fuzzing for software that might process untrusted inputs. +- Fuzzing is effective for standalone applications with large data parsers. + +**Azure and GitHub CI/CD** + +Modify your build(s) to support continuous creation of executables that use LibFuzzer or AFL++. You can add extra computing resources required for fuzzing at services like OSS-Fuzz. + +## 2.10 Web Application Scanning + +**Summary** + +Within the scope of Microsoft Visual C++ on Windows, Microsoft recommends: + +- Prefer TypeScript, JavaScript, and ASP.NET for web applications. +- Don't write web extensions in C++. Microsoft has deprecated ActiveX. +- When code is compiled to Emscripten/WASM, it's no longer C++ and other tools apply. +- Microsoft provides [RESTler, a stateful REST API fuzzer](https://github.com/microsoft/restler-fuzzer). + +**Overview and key qualities** + +A web application scanner explores a web application by crawling through its web pages and examines it for security vulnerabilities. This crawl involves the automatic generation of malicious inputs and evaluation of the application's responses. Critically, web application scanning must cover/support: + +- Catalogs all web apps in your network, including new and unknown ones, and scales from a handful of apps to thousands. +- Deep scanning for software versions, SOAP and REST API services and APIs used by mobile devices. +- Insertion of security primitives into application development and deployment in DevOps environments. These primitives work with the crawler. +- Malware detection. + +## 2.11 Check Included Software Components + +**Summary** + +Handle your C++ code the same as code written in other programming languages, and apply any Software Composition Analysis (SCA) and Origin Analysis (OA) tooling adopted by your company to your C++ code. Workflows and security scanning should be designed as part of CI/CD (continuous integration and continuous delivery) systems. + +**Upstream defense** + +To mitigate the risk of attacks on upstream dependencies, third party sources/components should be stored on an enterprise-controlled asset, against which SCA and OA tools are run. +- Tools should scan and alert when vulnerabilities are identified (including public databases) such as: [Home | CVE](https://www.cve.org/) +- Run static analysis on all software components included in your application/repo to identify vulnerable code patterns. + +**Dependency defense** + +Perform and maintain an audit of dependencies to validate that all such occurrences are accounted for and covered by your SCA and OA tools. +- Components should be regularly audited and updated to the latest verified versions. +- Package feed dependencies. +- SCA/OA tools cover and audit all package dependencies that come from a single feed. + +**SBOM** + +Produce an SBOM (software bill of materials) with your product listing all dependencies such as: +- origin (for example, URL (Uniform Resource Locator)) +- version +- consistency (for example, SHA-256 source hash), and other means for validating consistency such as deterministic builds. +- Require and audit SBOM files in software dependencies or produced as part of a build including OSS (open-source software). +- Microsoft is standardizing on and recommends [SPDX (Software Package Data Exchange) version 2.2 or later | Linux Foundation](https://spdx.dev/specifications/) as the SBOM document format. +- Build determinism can be used to independently produce bit-wise identical binaries and provide independent verifications of integrity: + - First-party or third-party attestation of reproducibility + - Other techniques such as binary signing via a trusted certificate source can also provide some assurances of binary integrity. + +**Additional resources** + +Microsoft solutions include the following guidance and products: +- [Microsoft Supply Chain Platform | Microsoft](https://www.microsoft.com/microsoft-cloud/solutions/microsoft-supply-chain-platform) +- [Secure your software supply chain | GitHub Security](https://github.com/features/security/software-supply-chain) +- [vcpkg](/vcpkg/) - vcpkg private registries allow redirection of OSS acquisition to Enterprise-controlled resources for acquiring sources for a dependency, to minimize risk of upstream or over-the-wire attacks. diff --git a/docs/code-quality/c1250.md b/docs/code-quality/c1250.md index 8f26a64706..26582cfe00 100644 --- a/docs/code-quality/c1250.md +++ b/docs/code-quality/c1250.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1250" -title: C1250 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1250"] +description: "Learn more about: Fatal error C1250" +title: Fatal error C1250 +ms.date: 10/04/2022 +f1_keywords: ["C1250", "FATALERROR_UnableToLoadPlugin"] helpviewer_keywords: ["C1250"] ms.assetid: 3f2385d7-e0d6-4574-8cea-342e82d0aea4 --- -# C1250 +# Fatal error C1250 -> warning C1250: Unable to load plug-in. +> Unable to load plug-in '*plugin-name*'. -The Code Analysis tool reports this warning when there is an internal error in the plugin, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1251.md b/docs/code-quality/c1251.md index c24156a79e..ca58d7858b 100644 --- a/docs/code-quality/c1251.md +++ b/docs/code-quality/c1251.md @@ -1,12 +1,13 @@ --- -description: "Learn more about: C1251" -title: C1251 -ms.date: 11/04/2016 -ms.topic: reference +description: "Learn more about: Fatal error C1251" +title: Fatal error C1251 +ms.date: 10/04/2022 +f1_keywords: ["C1251", "FATALERROR_UnableToLoadModel"] +helpviewer_keywords: ["C1251"] ms.assetid: 0b46e0a5-c290-48d8-ba4e-f526ae68993b --- -# C1251 +# Fatal error C1251 -> warning C1251: Unable to load models. +> Unable to load models. -The Code Analysis tool reports this warning when there is an internal error in the model file, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the model file, not in the code being analyzed. diff --git a/docs/code-quality/c1252.md b/docs/code-quality/c1252.md index 1e1edee1e3..4cdf0a1612 100644 --- a/docs/code-quality/c1252.md +++ b/docs/code-quality/c1252.md @@ -1,14 +1,17 @@ --- -description: "Learn more about: C1252" -title: C1252 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1252"] +description: "Learn more about: Fatal error C1252" +title: Fatal error C1252 +ms.date: 10/04/2022 +f1_keywords: ["C1252", "FATALERROR_CircularDependency"] helpviewer_keywords: ["C1252"] ms.assetid: e88bf199-890d-4582-bb5c-c1238797145b --- -# C1252 +# Fatal error C1252 -> warning C1252: Circular or missing dependency between plugins: requires GUID +> Circular or missing dependency between plugins: '*plugin-name*' requires GUID '*globally-unique-identifier*' -The Code Analysis tool reports this warning when there is an internal error with plugin dependencies, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the plugin dependencies. It's not caused by an issue in the code being analyzed. + +In some cases, it's possible to work around this issue by disabling the **Enable Code Analysis on Build** property. To disable this build property, open the Property pages dialog for your project. In the **Solution Explorer** window, right-click on the project (not the solution) and select **Properties** in the shortcut menu. Set the **Configuration** to **All Configurations** and the **Platform** to **All Platforms**. Open the **Configuration Properties** > **Code Analysis** > **General** property page. Modify the **Enable Code Analysis on Build** property to **No**. Choose **OK** to save your changes, and then save your project files. Rebuild your project to verify that the issue no longer occurs. + +If the issue continues, you can report it to Microsoft. For more information on how to report an issue, see [How to report a problem with the Visual C++ toolset or documentation](../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). diff --git a/docs/code-quality/c1253.md b/docs/code-quality/c1253.md index 665fad98cf..3276546314 100644 --- a/docs/code-quality/c1253.md +++ b/docs/code-quality/c1253.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1253" -title: C1253 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1253"] +description: "Learn more about: Fatal error C1253" +title: Fatal error C1253 +ms.date: 10/04/2022 +f1_keywords: ["C1253", "FATALERROR_UnableToLoadModelFile"] helpviewer_keywords: ["C1253"] ms.assetid: 21a4062f-fde8-40e5-8dbd-6f892926d3d2 --- -# C1253 +# Fatal error C1253 -> warning C1253: Unable to load model file. +> Unable to load model file. -The Code Analysis tool reports this warning when there is an internal error in the model file, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the model file, not in the code being analyzed. diff --git a/docs/code-quality/c1254.md b/docs/code-quality/c1254.md index c54bb70116..e584d07eee 100644 --- a/docs/code-quality/c1254.md +++ b/docs/code-quality/c1254.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1254" -title: C1254 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1254"] +description: "Learn more about: Fatal error C1254" +title: Fatal error C1254 +ms.date: 10/04/2022 +f1_keywords: ["C1254", "FATALERROR_PluginVersionMismatch"] helpviewer_keywords: ["C1254"] ms.assetid: cb1377cf-869e-432d-941f-71f77134f97a --- -# C1254 +# Fatal error C1254 -> warning C1254: Plugin version mismatch : version doesn't match the version of the PREfast driver +> Plugin version mismatch: '*module*' version '*version-number*' doesn't match the version '*version-number*' of the PREfast driver -The Code Analysis tool reports this warning when there is an internal error with the plugin version, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error with the plugin version, not in the code being analyzed. diff --git a/docs/code-quality/c1255.md b/docs/code-quality/c1255.md index 883029a8fd..9480c693e1 100644 --- a/docs/code-quality/c1255.md +++ b/docs/code-quality/c1255.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1255" -title: C1255 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1255"] +description: "Learn more about: Fatal error C1255" +title: Fatal error C1255 +ms.date: 10/04/2022 +f1_keywords: ["C1255", "FATALERROR_PCHSyncLost"] helpviewer_keywords: ["C1255"] ms.assetid: a97da6bd-06dc-42bf-9158-0de1ebb90d4a --- -# C1255 +# Fatal error C1255 -> warning C1255: PCH data for plugin has incorrect length. +> PCH data for plugin '*plugin-name*' has incorrect length. -The Code Analysis tool reports this warning when there is an internal error in the tool, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the tool, not in the code being analyzed. diff --git a/docs/code-quality/c1256.md b/docs/code-quality/c1256.md index ac9492478b..54a456fa9e 100644 --- a/docs/code-quality/c1256.md +++ b/docs/code-quality/c1256.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1256" -title: C1256 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1256"] +description: "Learn more about: Fatal error C1256" +title: Fatal error C1256 +ms.date: 10/04/2022 +f1_keywords: ["C1256", "FATALERROR_PCHInconsistent"] helpviewer_keywords: ["C1256"] ms.assetid: 4d65e495-f9d9-435c-ba51-1cf5b4cc2309 --- -# C1256 +# Fatal error C1256 -> warning C1256: PCH must be both written and read. +> '*plugin-name*': PCH must be both written and read. -The Code Analysis tool reports this warning when there is an internal error in the tool, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the tool, not in the code being analyzed. diff --git a/docs/code-quality/c1257.md b/docs/code-quality/c1257.md index bea6022a24..c104af70b7 100644 --- a/docs/code-quality/c1257.md +++ b/docs/code-quality/c1257.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C1257" -title: C1257 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1257"] +description: "Learn more about: Fatal error C1257" +title: Fatal error C1257 +ms.date: 10/04/2022 +f1_keywords: ["C1257", "FATALERROR_InitFailure"] helpviewer_keywords: ["C1257"] ms.assetid: 38d3ec05-01ba-42b3-aac6-077e92bf2ded --- -# C1257 +# Fatal error C1257 -> warning C1257: Plugin Initialization Failure. +> '*Plugin-name*': Initialization Failure. -The Code Analysis tool reports this warning when there is an internal error in the plugin, not in the code being analyzed. +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1258.md b/docs/code-quality/c1258.md new file mode 100644 index 0000000000..accca5c1d8 --- /dev/null +++ b/docs/code-quality/c1258.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal error C1258" +title: Fatal error C1258 +ms.date: 10/04/2022 +f1_keywords: ["C1258", "FATALERROR_SaveToXmlFailed"] +helpviewer_keywords: ["C1258"] +--- +# Fatal error C1258 + +> Failed to save XML Log file '*filename*'. *Message*. + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1259.md b/docs/code-quality/c1259.md new file mode 100644 index 0000000000..0d22874e87 --- /dev/null +++ b/docs/code-quality/c1259.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal error C1259" +title: Fatal error C1259 +ms.date: 10/04/2022 +f1_keywords: ["C1259", "FATALERROR_FatalError"] +helpviewer_keywords: ["C1259"] +--- +# Fatal error C1259 + +> A fatal error was issued by a plugin. + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1260.md b/docs/code-quality/c1260.md new file mode 100644 index 0000000000..6cf3642c1d --- /dev/null +++ b/docs/code-quality/c1260.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal error C1260" +title: Fatal error C1260 +ms.date: 10/04/2022 +f1_keywords: ["C1260", "FATALERROR_DuplicateId"] +helpviewer_keywords: ["C1260"] +--- +# Fatal error C1260 + +> The plugins '*plugin-1*' and '*plugin-2*' share the same id. It is not supported to load the same plugin twice. + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c26100.md b/docs/code-quality/c26100.md index b15fa6d5b3..f3ab41f020 100644 --- a/docs/code-quality/c26100.md +++ b/docs/code-quality/c26100.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C26100" -title: C26100 +description: "Learn more about: Warning C26100" +title: Warning C26100 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C26100"] +f1_keywords: ["C26100", "RACE_CONDITION", "__WARNING_RACE_CONDITION"] helpviewer_keywords: ["C26100"] ms.assetid: 470ab2b2-5b55-424f-b192-3863a773c892 --- -# C26100 +# Warning C26100 -> warning C26100: Race condition. Variable \ should be protected by lock \. +> Race condition. Variable '*var*' should be protected by lock '*lock*'. + +## Remarks The `_Guarded_by_` annotation in the code specifies the lock to use to guard a shared variable. Warning C26100 is generated when the guard contract is violated. +Code analysis name: `RACE_CONDITION` + ## Examples -The following example generates warning C26100 because there is a violation of the `_Guarded_by_` contract. +The following example generates warning C26100 because there's a violation of the `_Guarded_by_` contract. ```cpp CRITICAL_SECTION gCS; diff --git a/docs/code-quality/c26101.md b/docs/code-quality/c26101.md index 8d881597a8..aefe6357eb 100644 --- a/docs/code-quality/c26101.md +++ b/docs/code-quality/c26101.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C26101" -title: C26101 +description: "Learn more about: Warning C26101" +title: Warning C26101 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26101"] helpviewer_keywords: ["C26101"] ms.assetid: 86046553-09ec-40ce-82b3-fd641928f0b0 --- -# C26101 +# Warning C26101 -> warning C26101: Failing to use interlocked operation properly for variable \. +> Failing to use interlocked operation properly for variable '*var*'. -Windows APIs offer a variety of interlocked operations. Annotation `_Interlocked_` specifies that a variable should only be accessed through an interlocked operation. Warning C26101 is issued when an access is not consistent with the `_Interlocked_` annotation. +Windows APIs offer various interlocked operations. Annotation `_Interlocked_` specifies that a variable should only be accessed through an interlocked operation. Warning C26101 is issued when a variable access isn't consistent with the `_Interlocked_` annotation. ## Example -The following example generates warning C26101 because there is a violation of the `_Interlocked_` contract. +The following example generates warning C26101 because there's a violation of the `_Interlocked_` contract. ```cpp CRITICAL_SECTION cs; diff --git a/docs/code-quality/c26105.md b/docs/code-quality/c26105.md index 749ff32dbe..72dbc32d32 100644 --- a/docs/code-quality/c26105.md +++ b/docs/code-quality/c26105.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C26105" -title: C26105 +description: "Learn more about: Warning C26105" +title: Warning C26105 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26105"] helpviewer_keywords: ["C26105"] ms.assetid: 5558a3db-0513-43b4-8579-ccdc17e2b92f --- -# C26105 +# Warning C26105 -> warning C26105: Lock order violation. Acquiring lock \ with level \ causes order inversion. +> Lock order violation. Acquiring lock '*lock*' with level '*level*' causes order inversion. Concurrency SAL supports *lock levels*. To declare a lock level, which is denoted by a string literal without double quotes, use `_Create_lock_level_`. You can impose an order of acquisition between two lock levels by using the annotation `_Set_lock_level_order_(A,B)`, which states that locks that have level `A` must be acquired before locks that have level `B`. To establish a lock order hierarchy (a partial order among lock levels), use multiple `_Set_lock_level_order_` annotations. To associate a lock with a lock level, use the `_Set_lock_level_` annotation when you declare the lock. Warning C26105 is issued when a lock ordering violation is detected. ## Example -The following example generates warning C26105 because there is a lock order inversion in the function `OrderInversion`. +The following example generates warning C26105 because there's a lock order inversion in the function `OrderInversion`. ```cpp _Create_lock_level_(MutexLockLevel); diff --git a/docs/code-quality/c26110.md b/docs/code-quality/c26110.md index 90238930a8..d1981b1576 100644 --- a/docs/code-quality/c26110.md +++ b/docs/code-quality/c26110.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C26110" -title: C26110 +description: "Learn more about: Warning C26110" +title: Warning C26110 ms.date: 10/01/2019 -ms.topic: reference f1_keywords: ["C26110"] helpviewer_keywords: ["C26110"] ms.assetid: d82b79ec-6d7f-438b-bd6a-da874a3e08e5 --- -# C26110 +# Warning C26110 -> warning C26110: Caller failing to hold lock \ before calling function \. +> Caller failing to hold lock '*lock*' before calling function '*func*'. -When a lock is required, make sure to clarify whether the function itself or its caller should acquire the lock. Warning C26110 is issued when there is a violation of the `_Requires_lock_held_` annotation, or other lock-related annotations. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md) +When a lock is required, make sure to clarify whether the function itself, or its caller, should acquire the lock. Warning C26110 is issued when there's a violation of the `_Requires_lock_held_` annotation, or other lock-related annotations. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md) ## Example diff --git a/docs/code-quality/c26111.md b/docs/code-quality/c26111.md index 9b09995f93..5fdbec7c47 100644 --- a/docs/code-quality/c26111.md +++ b/docs/code-quality/c26111.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C26111" -title: C26111 +description: "Learn more about: Warning C26111" +title: Warning C26111 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26111"] helpviewer_keywords: ["C26111"] ms.assetid: 85fc740a-3bbb-41b8-a848-95e243a08da9 --- -# C26111 +# Warning C26111 -> warning C26111: Caller failing to release lock \ before calling function \. +> Caller failing to release lock '*lock*' before calling function '*func*'. -The annotation `_Requires_lock_not_held_` imposes a precondition that the lock count for the specified lock cannot be greater than zero when the function is called. Warning C26111 is issued when a function fails to release the lock before it calls another function. +The annotation `_Requires_lock_not_held_` imposes a precondition that the lock count for the specified lock can't be greater than zero when the function is called. Warning C26111 is issued when a function fails to release the lock before it calls another function. ## Example diff --git a/docs/code-quality/c26112.md b/docs/code-quality/c26112.md index 9b0990c8d2..7794bf4ef5 100644 --- a/docs/code-quality/c26112.md +++ b/docs/code-quality/c26112.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26112" -title: C26112 +description: "Learn more about: Warning C26112" +title: Warning C26112 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26112"] helpviewer_keywords: ["C26112"] ms.assetid: 926de738-b9b0-43d7-9137-ab2daa44ad4d --- -# C26112 +# Warning C26112 -> warning C26112: Caller cannot hold any lock before calling \. +> Caller cannot hold any lock before calling '*func*'. The annotation `_Requires_no_locks_held_` imposes a precondition that the caller must not hold any lock while it calls the function. Warning C26112 is issued when a function fails to release all locks before it calls another function. diff --git a/docs/code-quality/c26115.md b/docs/code-quality/c26115.md index 410c812ae8..402dd0aea9 100644 --- a/docs/code-quality/c26115.md +++ b/docs/code-quality/c26115.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: C26115" -title: C26115 +description: "Learn more about: Warning C26115" +title: Warning C26115 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26115"] helpviewer_keywords: ["C26115"] ms.assetid: 3977a2bb-d1fe-4510-89dd-07fdc69e911c --- -# C26115 +# Warning C26115 -> warning C26115: Failing to release lock \ in function \. +> Failing to release lock '*lock*' in function '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. -You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26115 is issued when a function introduces an orphaned lock. +You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26115 is issued when a function introduces an orphaned lock. ## Example -The following example generates warning C26115 because there is an orphaned lock in a function that is not annotated with `_Acquires_lock_`. +The following example generates warning C26115 because there's an orphaned lock in a function that isn't annotated with `_Acquires_lock_`. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26116.md b/docs/code-quality/c26116.md index c01fc2a5fa..5282963f53 100644 --- a/docs/code-quality/c26116.md +++ b/docs/code-quality/c26116.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C26116" -title: C26116 +description: "Learn more about: Warning C26116" +title: Warning C26116 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26116"] helpviewer_keywords: ["C26116"] ms.assetid: 43e99d2c-405e-4913-b6bd-47f5858b2877 --- -# C26116 +# Warning C26116 -> warning C26116: Failing to acquire or to hold lock \ in \. +> Failing to acquire or to hold lock '*lock*' in '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock.You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it does not acquire a lock, or when a function is annotated with `_Requires_lock_held` and releases the lock. +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it doesn't acquire a lock, or when a function is annotated with `_Requires_lock_held` and releases the lock. ## Example -The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but does not acquire it. The function `DoesNotHoldLock` generates the warning because it is annotated with `_Requires_lock_held` and does not hold it. +The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but doesn't acquire it. The function `DoesNotHoldLock` generates the warning because it's annotated with `_Requires_lock_held` and doesn't hold it. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26117.md b/docs/code-quality/c26117.md index 892d8507df..235b47f14f 100644 --- a/docs/code-quality/c26117.md +++ b/docs/code-quality/c26117.md @@ -1,24 +1,22 @@ --- -description: "Learn more about: C26117" -title: C26117 +description: "Learn more about: Warning C26117" +title: Warning C26117 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26117"] helpviewer_keywords: ["C26117"] ms.assetid: cc7ebc8d-9826-4cad-a4d5-2d3ad5896734 --- -# C26117 +# Warning C26117 -> warning C26117: Releasing unheld lock \ in function \. +> Releasing unheld lock '*lock*' in function '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock.You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26117 is issued when a function that has not been annotated with `_Releases_lock_` releases a lock that it doesn't hold, because the function must own the lock before it releases it. +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26117 is issued when a function that hasn't been annotated with `_Releases_lock_` releases a lock that it doesn't hold, because the function must own the lock before it releases it. ## Examples -The following example generates warning C26117 because the function `ReleaseUnheldLock` releases a lock that it doesn't necessarily hold—the state of `flag` is ambiguous—and there is no annotation that specifies that it should. +The following example generates warning C26117 because the function `ReleaseUnheldLock` releases a lock that it doesn't necessarily hold—the state of `flag` is ambiguous—and there's no annotation that specifies that it should. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; @@ -38,7 +36,6 @@ void ReleaseUnheldLock(DATA* p) The following code fixes the problem by guaranteeing that the released lock is also acquired under the same conditions. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; diff --git a/docs/code-quality/c26130.md b/docs/code-quality/c26130.md index 77bd55296e..fb1912520c 100644 --- a/docs/code-quality/c26130.md +++ b/docs/code-quality/c26130.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C26130" -title: C26130 +description: "Learn more about: Warning C26130" +title: Warning C26130 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26130"] helpviewer_keywords: ["C26130"] ms.assetid: 535e2356-bc84-4549-983d-7d29aee2249c --- -# C26130 +# Warning C26130 -> warning C26130: Missing annotation \_Requires\_lock\_held\_(\) or \_No\_competing\_thread\_ at function \. Otherwise it could be a race condition. Variable \ should be protected by lock \. +> Missing annotation \_Requires\_lock\_held\_('*lock*') or \_No\_competing\_thread\_ at function '*func*'. Otherwise it could be a race condition. Variable '*var*' should be protected by lock '*lock*'. -Warning C26130 is issued when the analyzer detects a potential race condition but infers that the function is likely to be run in a single threaded mode, for example, when the function is in the initialization stage based on certain heuristics. +Warning C26130 is issued when the analyzer detects a potential race condition but infers that the function is likely to be run in a single threaded mode. For example, when the function is in the initialization stage, based on certain heuristics. ## Examples @@ -30,7 +29,7 @@ void Init(DATA* p) } ``` -If the previous code is guaranteed to be operated in a single threaded mode, annotate the function by using `_No_competing_thread_`, as shown in the following example. +If the previous code is guaranteed to operate in single-threaded mode, annotate the function by using `_No_competing_thread_`, as shown in the following example. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26132.md b/docs/code-quality/c26132.md new file mode 100644 index 0000000000..390903a605 --- /dev/null +++ b/docs/code-quality/c26132.md @@ -0,0 +1,73 @@ +--- +title: Warning C26132 +description: Documentation on static analysis warning C26132 +author: Rastaban +ms.author: philc +ms.service: visual-cpp +ms.topic: article +ms.date: 02/11/2025 +--- +# Warning C26132 + +> Variable '*variable name*' should be protected by '*lock 1*', but '*lock 2*' is held instead. Possible annotation mismatch. + +The analyzer issues Warning C26132 when it detects that a lock, which is annotated to protect a value, isn't held while accessing the value. However, a related lock is held. The code may be thread-safe, so you might need to update the annotations. + +This diagnostic usually doesn't indicate a bug in the code, but rather a mismatch between the annotations and the actual locking behavior. If so, the diagnostic should be resolved as there may be other static analysis issues that aren't being reported due to the inconsistent annotations. + +## Examples + +In the following example, C26132 is emitted when `data` is used. + + The annotation specifies that `customLock01` should protect the variable `data`, but `CustomLockAcquire` is responsible for acquiring the related lock `customLock01->cs`. + +```cpp +#include +struct CustomLock +{ + int cs; // "Critical Section" lock +}; + +_Acquires_exclusive_lock_(criticalSection->cs) // notice the `->` indirection +void CustomLockAcquire(CustomLock* criticalSection); + +_Releases_lock_(criticalSection->cs) // notice the `->` indirection +void CustomLockRelease(CustomLock* criticalSection); + +// global lock +CustomLock customLock01; + +void Initialize(_Guarded_by_(customLock01) int* data) +{ + CustomLockAcquire(&customLock01); + *data = 1; // C26132 + CustomLockRelease(&customLock01); +} +``` + +In this example, the `Initialize` function is thread-safe and behaves as designed, but that design isn't correctly reflected in the concurrency SAL annotations. Fix by adjusting the annotations on the custom locking functions to use `criticalSection` rather than `criticalSection->cs`. The warning could also be fixed by changing the `_Guarded_by_` annotation from `customLock01` to `customLock01.cs`. + +```cpp +#include +struct CustomLock +{ + int cs; // "Critical Section" lock +}; + +_Acquires_exclusive_lock_(criticalSection) +void CustomLockAcquire(CustomLock* criticalSection); + +_Releases_lock_(criticalSection) +void CustomLockRelease(CustomLock* criticalSection); + +// global lock +CustomLock customLock01; + +void Initialize(_Guarded_by_(customLock01) int* data) +{ + CustomLockAcquire(&customLock01); + *data = 1; + CustomLockRelease(&customLock01); +} +``` + diff --git a/docs/code-quality/c26133.md b/docs/code-quality/c26133.md new file mode 100644 index 0000000000..0074674044 --- /dev/null +++ b/docs/code-quality/c26133.md @@ -0,0 +1,76 @@ +--- +title: Warning C26133 +description: Documentation on static analysis warning C26133 +author: Rastaban +ms.author: philc +ms.service: visual-cpp +ms.topic: article +ms.date: 02/19/2025 +--- +# Warning C26133 + +> Caller failing to hold lock '*lock 1*' before calling function '*function name*', but '*lock 2*' is held instead. Possible annotation mismatch. + +Warning C26133 is issued when the analyzer detects that the lock required to call a function isn't held when the function is called. However, another lock that appears to be related is held. It's possible the code is thread-safe, and the annotations need to be updated. + +This diagnostic usually doesn't indicate a bug in the code, but rather a mismatch between the annotations and the actual locking behavior. If so, the diagnostic should be resolved as there may be other static analysis issues that aren't being reported due to the inconsistent annotations. + +## Examples + +In the following example, C26133 is emitted when `DoTaskWithCustomLock` is called. + +> warning C26133: Caller failing to hold lock 'customLock01' before calling function 'DoTaskWithCustomLock', but '(&customLock01)->cs' is held instead. Possible annotation mismatch. + +```cpp +#include + +struct CustomLock +{ + int cs; // "Critical Section" +}; + +_Acquires_exclusive_lock_(criticalSection->cs) // notice the `->` indirection +void CustomLockAcquire(CustomLock* criticalSection); + +_Releases_lock_(criticalSection->cs) // notice the `->` indirection +void CustomLockRelease(CustomLock* criticalSection); + +CustomLock customLock01; + +_Requires_lock_held_(customLock01) void DoTaskWithCustomLock(); + +void DoTask() +{ + CustomLockAcquire(&customLock01); + DoTaskWithCustomLock(); // C26133 + CustomLockRelease(&customLock01); +} +``` + +In this example, the `DoTask` function is thread-safe and behaves as designed, but that design isn't correctly reflected in the concurrency SAL annotations. Fix by adjusting the annotations on the custom locking functions to use `criticalSection` rather than `criticalSection->cs`. The warning could also be fixed by changing the `_Requires_lock_held_` annotation from `customLock01` to `customLock01.cs`. + +```cpp +#include + +struct CustomLock +{ + int cs; // "Critical Section" +}; + +_Acquires_exclusive_lock_(criticalSection) +void CustomLockAcquire(CustomLock* criticalSection); + +_Releases_lock_(criticalSection) +void CustomLockRelease(CustomLock* criticalSection); + +CustomLock customLock01; + +_Requires_lock_held_(customLock01) void DoTaskWithCustomLock(); + +void DoTask() +{ + CustomLockAcquire(&customLock01); + DoTaskWithCustomLock(); + CustomLockRelease(&customLock01); +} +``` \ No newline at end of file diff --git a/docs/code-quality/c26135.md b/docs/code-quality/c26135.md index 973d72eb86..96db147d01 100644 --- a/docs/code-quality/c26135.md +++ b/docs/code-quality/c26135.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C26135" -title: C26135 +description: "Learn more about: Warning C26135" +title: Warning C26135 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26135"] helpviewer_keywords: ["C26135"] ms.assetid: e9515189-8d21-473b-89f4-8b92ebd3a4f1 --- -# C26135 +# Warning C26135 -> warning C26135: Missing annotation \ at function \. +> Missing annotation '*annotation*' at function '*func*'. -Warning C26135 is issued when the analyzer infers that a function is a lock wrapper function that has a lock acquire or lock release side effect. If the code is not intended to be a wrapper function, then either the lock is leaking (if the lock is being acquired) or it is being released incorrectly (if the lock is being released). +Warning C26135 is issued when the analyzer infers that a function is a lock wrapper function that has a "lock acquire" or "lock release" side effect. If the code isn't intended to be a wrapper function, then either the lock is leaking (if it's being acquired), or it's being released incorrectly (if the lock is being released). ## Examples @@ -26,14 +25,14 @@ typedef struct _DATA void MyEnter(DATA* p) { // Warning C26135: - // Missing side effect annotation _Acquires_lock_(&p->cs) + // Missing side effect annotation _Acquires_lock_(p->cs) EnterCriticalSection(&p->cs); } void MyLeave(DATA* p) { // warning C26135: - // Missing side effect annotation _Releases_lock_(&p->cs) + // Missing side effect annotation _Releases_lock_(p->cs) LeaveCriticalSection(&p->cs); } ``` diff --git a/docs/code-quality/c26138.md b/docs/code-quality/c26138.md index 9f28d7c766..08c847a5b0 100644 --- a/docs/code-quality/c26138.md +++ b/docs/code-quality/c26138.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26138" -title: C26138 +description: "Learn more about: Warning C26138" +title: Warning C26138 ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26138"] +f1_keywords: ["C26138", "SUSPENDED_WITH_LOCK"] helpviewer_keywords: ["C26138"] -author: sunnychatterjee -ms.author: sunnych --- -# C26138 +# Warning C26138 -> warning C26138: Suspending a coroutine while holding lock \. +> Suspending a coroutine while holding lock '*lock*'. + +## Remarks Warning C26138 warns when a coroutine is suspended while holding a lock. In general, we can't know how long will a coroutine remain in the suspended state so this pattern may result in longer critical sections than expected. +Code analysis name: `SUSPENDED_WITH_LOCK` + ## Examples The following code will generate C26138. ```cpp - #include #include #include @@ -48,7 +48,6 @@ generator mutex_acquiring_generator_report_once() { The following code will correct these warnings. ```cpp - #include #include #include diff --git a/docs/code-quality/c26140.md b/docs/code-quality/c26140.md index 80e2289c6a..dd11953d3e 100644 --- a/docs/code-quality/c26140.md +++ b/docs/code-quality/c26140.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26140" -title: C26140 +description: "Learn more about: Warning C26140" +title: Warning C26140 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26140"] helpviewer_keywords: ["C26140"] ms.assetid: a0b521b4-0c2f-470a-8904-f7bbb8014536 --- -# C26140 +# Warning C26140 -> warning C26140: Undefined lock kind \ in annotation \ on lock \. +> Undefined lock kind '*lock*' in annotation '*annotation*' on lock '*lock*'. ## Example diff --git a/docs/code-quality/c26160.md b/docs/code-quality/c26160.md index 13d5294d86..2d8df17126 100644 --- a/docs/code-quality/c26160.md +++ b/docs/code-quality/c26160.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26160" -title: C26160 +description: "Learn more about: Warning C26160" +title: Warning C26160 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26160"] helpviewer_keywords: ["C26160"] ms.assetid: e6518687-36b4-4eae-a732-758881638295 --- -# C26160 +# Warning C26160 -> warning C26160: Caller possibly failing to hold lock \ before calling function \. +> Caller possibly failing to hold lock '*lock*' before calling function '*func*'. Warning C26160 resembles warning [C26110](../code-quality/c26110.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +17,6 @@ Warning C26160 resembles warning [C26110](../code-quality/c26110.md) except that The following code generates warning C26160. ```cpp - struct Account { _Guarded_by_(cs) int balance; @@ -50,7 +48,6 @@ struct Account The following code shows a solution to the previous example. ```cpp - struct Account { _Guarded_by_(cs) int balance; diff --git a/docs/code-quality/c26165.md b/docs/code-quality/c26165.md index 0d82647c21..973b4745d9 100644 --- a/docs/code-quality/c26165.md +++ b/docs/code-quality/c26165.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26165" -title: C26165 +description: "Learn more about: Warning C26165" +title: Warning C26165 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26165"] helpviewer_keywords: ["C26165"] ms.assetid: a1d89bd6-08f3-4215-8a0c-b8ecfeb0cffc --- -# C26165 +# Warning C26165 -> warning C26165: Possibly failing to release lock \ in function \. +> Possibly failing to release lock '*lock*' in function '*func*'. Warning C26165 resembles warning [C26115](../code-quality/c26115.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +17,6 @@ Warning C26165 resembles warning [C26115](../code-quality/c26115.md) except that The following code generates warning C26165. ```cpp - _Create_lock_level_(LockLevelOne); _Create_lock_level_(LockLevelTwo); @@ -46,7 +44,6 @@ void testLockLevelledStruct(LockLevelledStruct* s) // Warning C26165 To correct this warning, change the previous example to the following. ```cpp - _Create_lock_level_(LockLevelOne); _Create_lock_level_(LockLevelTwo); diff --git a/docs/code-quality/c26166.md b/docs/code-quality/c26166.md index 88fc282f7b..04809e0a94 100644 --- a/docs/code-quality/c26166.md +++ b/docs/code-quality/c26166.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26166" -title: C26166 +description: "Learn more about: Warning C26166" +title: Warning C26166 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26166"] helpviewer_keywords: ["C26166"] ms.assetid: a3d21838-07da-40f6-8d2e-1ada72765af2 --- -# C26166 +# Warning C26166 -> warning C26166: Possibly failing to acquire or to hold lock \ in function \. +> Possibly failing to acquire or to hold lock '*lock*' in function '*func*'. Warning C26166 resembles warning [C26116](../code-quality/c26116.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +17,6 @@ Warning C26166 resembles warning [C26116](../code-quality/c26116.md) except that The following code shows code that will generate warning C26166. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; diff --git a/docs/code-quality/c26167.md b/docs/code-quality/c26167.md index bb1a860575..8e7eea235b 100644 --- a/docs/code-quality/c26167.md +++ b/docs/code-quality/c26167.md @@ -1,24 +1,22 @@ --- -description: "Learn more about: C26167" -title: C26167 +description: "Learn more about: Warning C26167" +title: Warning C26167 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26167"] helpviewer_keywords: ["C26167"] ms.assetid: 5a3d767f-31fa-45e0-8c9b-1aa776acaa45 --- -# C26167 +# Warning C26167 -> warning C26167: Possibly releasing unheld lock \ in function \. +> Possibly releasing unheld lock '*lock*' in function '*func*'. Warning C26167 resembles warning [C26117](../code-quality/c26117.md) except that the confidence level is lower. For example, the function may contain annotation errors. ## Examples -The following code will generate C26167, as well as C26110. +The following code will generate C26167 and C26110. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; @@ -35,7 +33,6 @@ void ReleaseUnheldLock(DATA* p) { // Warning C26167 The following code will correct these warnings. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; diff --git a/docs/code-quality/c26400.md b/docs/code-quality/c26400.md index 93c9add39d..ccdd3a65e3 100644 --- a/docs/code-quality/c26400.md +++ b/docs/code-quality/c26400.md @@ -1,22 +1,26 @@ --- -title: C26400 +title: Warning C26400 description: "Describes the Microsoft C/C++ code analysis warning C26400, its causes, and how to address it." ms.date: 10/23/2020 -f1_keywords: ["C26400"] +f1_keywords: ["C26400", "NO_RAW_POINTER_ASSIGNMENT"] helpviewer_keywords: ["C26400"] --- -# C26400 NO_RAW_POINTER_ASSIGNMENT +# Warning C26400 -This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*)*, which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner` if their results are assigned to raw pointers. The idea here is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). +> Do not assign the result of an allocation or a function call with an `owner` return value to a raw pointer, use `owner` instead (i.11) + +## Remarks + +This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*), which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner` if their results are assigned to raw pointers. The idea is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). The easiest way to fix this warning is to use **`auto`** declaration if the resource is assigned immediately at the variable declaration. If this fix isn't possible, then we suggest that you use the type `gsl::owner`. The **`auto`** declarations initialized with operator **`new`** are "owners" because we assume that the result of any allocation is implicitly an owner pointer. We transfer this assumption to the **`auto`** variable and treat it as `owner`. If this check flags a call to a function that returns `owner`, it may be an indication of a legitimate bug in the code. Basically, it points to a place where the code leaks an explicit notion of ownership (and maybe the resource itself). -## Remarks - This rule currently checks only local variables. If you assign an allocation to a formal parameter, global variable, class member, and so on, it's not flagged. Appropriate coverage of such scenarios is planned for future work. +Code analysis name: `NO_RAW_POINTER_ASSIGNMENT` + ## Example 1: Simple allocation ```cpp diff --git a/docs/code-quality/c26401.md b/docs/code-quality/c26401.md index 0c1da704aa..023338c378 100644 --- a/docs/code-quality/c26401.md +++ b/docs/code-quality/c26401.md @@ -1,18 +1,23 @@ --- -title: C26401 +title: Warning C26401 ms.date: 12/14/2020 -ms.topic: "conceptual" -f1_keywords: ["C26401"] +f1_keywords: ["C26401", "DONT_DELETE_NON_OWNER"] helpviewer_keywords: ["C26401"] ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b description: CppCoreCheck rule C26401 enforces C++ Core Guidelines I.11 --- -# C26401 DONT_DELETE_NON_OWNER +# Warning C26401 -This check detects places where moving to `owner` can be a good option for the first stage of refactoring. Like C26400, it enforces rules I.11 and R.3, but focuses on the "release" portion of the pointer lifetime. It warns on any call to operator **`delete`** if its target isn't an `owner` or an implicitly assumed owner. For more information about **`auto`** declarations, see [C26400](c26400.md). This check includes expressions that refer to global variables, formal parameters, and so on. +> Do not delete a raw pointer that is not an `owner` (i.11) + +## Remarks + +This check detects code where moving to `owner` can be a good option for the first stage of refactoring. Like C26400, it enforces rules I.11 and R.3, but focuses on the "release" portion of the pointer lifetime. It warns on any call to operator **`delete`** if its target isn't an `owner` or an implicitly assumed owner. For more information about **`auto`** declarations, see [C26400](c26400.md). This check includes expressions that refer to global variables, formal parameters, and so on. Warnings C26400 and C26401 always occur with [C26409](c26409.md), but they're more appropriate for scenarios where immediate migration to smart pointers isn't feasible. In such cases, the `owner` concept can be adopted first, and C26409 may be temporarily suppressed. +Code analysis name: `DONT_DELETE_NON_OWNER` + ## See also [C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i11-never-transfer-ownership-by-a-raw-pointer-t-or-reference-t) @@ -46,7 +51,7 @@ void function() } ``` -There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: +There's a C++ idiom that triggers this warning: `delete this`. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: ```cpp class MyReferenceCountingObject final @@ -58,7 +63,7 @@ public: ref_count_--; if (ref_count_ == 0) { - [[gsl::suppress(i.11)]] + [[gsl::suppress("i.11")]] delete this; } } diff --git a/docs/code-quality/c26402.md b/docs/code-quality/c26402.md index 828a1cbb93..b79483f914 100644 --- a/docs/code-quality/c26402.md +++ b/docs/code-quality/c26402.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT" -title: C26402 +description: "Learn more about: Warning C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT" +title: Warning C26402 ms.date: 08/20/2020 -ms.topic: "conceptual" -f1_keywords: ["C26402"] +f1_keywords: ["C26402", "DONT_HEAP_ALLOCATE_MOVABLE_RESULT"] helpviewer_keywords: ["C26402"] ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b --- -# C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT +# Warning C26402 > `Return a scoped object instead of a heap-allocated if it has a move constructor (r.3).` @@ -17,7 +16,7 @@ To avoid confusion about whether a pointer owns an object, a function that retur ## Example -This example shows a function, `bad_example`, that raises warning C26409. It also shows how function `good_example` doesn't cause this issue. +This example shows a `bad_example` function that raises warning C26409. It also shows how function `good_example` doesn't cause this issue. ```cpp // C26402.cpp diff --git a/docs/code-quality/c26403.md b/docs/code-quality/c26403.md index d688d724cf..2501899487 100644 --- a/docs/code-quality/c26403.md +++ b/docs/code-quality/c26403.md @@ -1,27 +1,32 @@ --- -description: "Learn more about: C26403 RESET_OR_DELETE_OWNER" -title: C26403 +description: "Learn more about: Warning C26403 RESET_OR_DELETE_OWNER" +title: Warning C26403 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26403"] +f1_keywords: ["C26403", "RESET_OR_DELETE_OWNER"] helpviewer_keywords: ["C26403"] ms.assetid: 7e14868d-df86-4df3-98d3-71b1e80ba14e --- -# C26403 RESET_OR_DELETE_OWNER +# Warning C26403 -Owner pointers are like unique pointers: they own a resource exclusively, and manage release of the resource, as well as its transfers to other owners. This check validates that a local owner pointer properly maintains its resource through all execution paths in a function. If the resource was not transferred to another owner, or was not explicitly release, the checker warns, and points to the declaration of the pointer variable. +> Reset or explicitly delete an `owner` pointer '*variable*' (r.3) + +Owner pointers are like unique pointers: they own a resource exclusively, and manage release of the resource, or its transfers to other owners. This check validates that a local owner pointer properly maintains its resource through all execution paths in a function. If the resource wasn't transferred to another owner, or wasn't explicitly release, the checker warns, and points to the declaration of the pointer variable. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). ## Remarks -- Currently this check doesn’t give the exact path which fails to release the resource. This behavior may be improved in future releases. It may be difficult to find exact location for a fix. The better approach is to try to replace plain pointers in complex functions with unique pointers to avoid any risks. +- Currently this check doesn't give the exact path that fails to release the resource. This behavior may be improved in future releases. It may be difficult to find exact location for a fix. The better approach is to try to replace plain pointers in complex functions with unique pointers to avoid any risks. + +- The check may discard an over-complicated function in order to not block code analysis. Generally, the complexity of functions should be maintained under some reasonable threshold. We may consider adding a local complexity check to the C++ Core Guidelines module if there's clear demand for it. This limitation is applicable to other rules that are sensitive to data flow. + +- The warning may fire on clearly false positive cases where memory is deleted only after the null check of a pointer. These false positives are the result of a current limitation of the tool's API, but it may be improved in future. -- The check may discard an over-complicated function in order to not block code analysis. Generally, the complexity of functions should be maintained under some reasonable threshold. We may consider adding a local complexity check to the C++ Core Guidelines module if there is clear demand for it. This limitation is applicable to other rules which are sensitive to data flow. +Code analysis name: `RESET_OR_DELETE_OWNER` -- The warning may fire on clearly false positive cases where memory is deleted only after the nullness check of a pointer. This is the result of a current limitation of the tool’s API, but it may be improved in future. +## Example -## Example 1: Missing cleanup during error handling +Missing cleanup during error handling: ```cpp gsl::owner sequence = GetRandomSequence(); // C26403 diff --git a/docs/code-quality/c26404.md b/docs/code-quality/c26404.md index 53274f5dad..f37ed895fb 100644 --- a/docs/code-quality/c26404.md +++ b/docs/code-quality/c26404.md @@ -1,18 +1,24 @@ --- -description: "Learn more about: C26404 DONT_DELETE_INVALID" -title: C26404 +description: "Learn more about: Warning C26404 DONT_DELETE_INVALID" +title: Warning C26404 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26404"] +f1_keywords: ["C26404", "DONT_DELETE_INVALID"] helpviewer_keywords: ["C26404"] ms.assetid: 94afb700-3f3b-40db-8afc-2481935360c2 --- -# C26404 DONT_DELETE_INVALID +# Warning C26404 -Once owner pointer releases or transfers its resource, it gets into an "invalid" state. -Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer. +> Do not delete an `owner` which may be in invalid state (r.3) -## Example 1: Deleting an owner after transferring its value +## Remarks + +Once an owner pointer releases or transfers its resource, it gets into an "invalid" state. Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer. + +Code analysis name: `DONT_DELETE_INVALID` + +## Example 1 + +Deleting an owner after transferring its value: ```cpp gsl::owner validState = nullptr; @@ -22,7 +28,9 @@ if (!IsValid(state)) delete state; // C26404 ``` -## Example 2: Deleting an uninitialized owner +## Example 2 + +Deleting an uninitialized owner: ```cpp gsl::owner message; diff --git a/docs/code-quality/c26405.md b/docs/code-quality/c26405.md index 4fb63a8631..cf14b63ea6 100644 --- a/docs/code-quality/c26405.md +++ b/docs/code-quality/c26405.md @@ -1,17 +1,24 @@ --- -description: "Learn more about: C26405 DONT_ASSIGN_TO_VALID" -title: C26405 +description: "Learn more about: Warning C26405 DONT_ASSIGN_TO_VALID" +title: Warning C26405 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26405"] +f1_keywords: ["C26405", "DONT_ASSIGN_TO_VALID"] helpviewer_keywords: ["C26405"] ms.assetid: 2034d961-3ec5-4184-bbef-aa792e4c03c0 --- -# C26405 DONT_ASSIGN_TO_VALID +# Warning C26405 -If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn’t release resources). For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning). +> Do not assign to an `owner` which may be in valid state (r.3) -## Example 1: Overwriting an owner in a loop +## Remarks + +If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn't release resources). For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning). + +Code analysis name: `DONT_ASSIGN_TO_VALID` + +## Example 1 + +Overwriting an owner in a loop: ```cpp gsl::owner shape = nullptr; diff --git a/docs/code-quality/c26406.md b/docs/code-quality/c26406.md index 9f9090494b..1dc0b113bf 100644 --- a/docs/code-quality/c26406.md +++ b/docs/code-quality/c26406.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C26406 DONT_ASSIGN_RAW_TO_OWNER" -title: C26406 +description: "Learn more about: Warning C26406 DONT_ASSIGN_RAW_TO_OWNER" +title: Warning C26406 ms.date: 08/18/2020 -ms.topic: "conceptual" -f1_keywords: ["C26406"] +f1_keywords: ["C26406", "DONT_ASSIGN_RAW_TO_OWNER"] helpviewer_keywords: ["C26406"] ms.assetid: 02fb8e23-1989-4e24-a5a5-e30f71d00325 --- -# C26406 DONT_ASSIGN_RAW_TO_OWNER +# Warning C26406 + +> Do not assign a raw pointer to an `owner` (r.3) This warning enforces R.3 from the C++ Core Guidelines. For more information, see [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning). ## Remarks -Owners are initialized from allocations or from other owners. This warning occurs when you assign a value from a raw pointer to an owner pointer. Raw pointers don’t guarantee ownership transfer; the original owner may still hold the resource and attempt to release it. It's okay to assign a value from an owner to a raw pointer. Raw pointers are valid clients to access resources, but not to manage them. +Owners are initialized from allocations or from other owners. This warning occurs when you assign a value from a raw pointer to an owner pointer. Raw pointers don't guarantee ownership transfer; the original owner may still hold the resource and attempt to release it. It's okay to assign a value from an owner to a raw pointer. Raw pointers are valid clients to access resources, but not to manage them. + +Code analysis name: `DONT_ASSIGN_RAW_TO_OWNER` + +## Example -## Example 1: Using address of object +Using address of object: This sample attempts to assign ownership of the address of `defaultSocket` to owner pointer `socket`: diff --git a/docs/code-quality/c26407.md b/docs/code-quality/c26407.md index 88184142c2..d082e56681 100644 --- a/docs/code-quality/c26407.md +++ b/docs/code-quality/c26407.md @@ -1,25 +1,28 @@ --- -title: C26407 +title: Warning C26407 description: "Reference for Visual Studio C++ Core Guidelines code analysis warning C26407." ms.date: 08/18/2020 -ms.topic: "conceptual" -f1_keywords: ["C26407"] +f1_keywords: ["C26407", "DONT_HEAP_ALLOCATE_UNNECESSARILY"] helpviewer_keywords: ["C26407"] ms.assetid: 5539907a-bfa0-40db-82a6-b860c97209e1 --- -# C26407 DONT_HEAP_ALLOCATE_UNNECESSARILY +# Warning C26407 -To avoid unnecessary use of pointers, we try to detect common patterns of local allocations. For example, we detect when the result of a call to operator **`new`** is stored in a local variable and later explicitly deleted. This supports the [C++ Core Guidelines rule R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r5-prefer-scoped-objects-dont-heap-allocate-unnecessarily): *Prefer scoped objects, don't heap-allocate unnecessarily*. To fix the issue, use an RAII type instead of a raw pointer, and allow it to deal with resources. Obviously, it isn't necessary to create a wrapper type to allocate a single object. Instead, a local variable of the object's type would work better. +> Prefer scoped objects, don't heap-allocate unnecessarily (r.5) + +To avoid unnecessary use of pointers, we try to detect common patterns of local allocations. For example, we detect when the result of a call to operator **`new`** is stored in a local variable and later explicitly deleted. This check supports the [C++ Core Guidelines rule R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r5-prefer-scoped-objects-dont-heap-allocate-unnecessarily): *Prefer scoped objects, don't heap-allocate unnecessarily*. To fix the issue, use an RAII type instead of a raw pointer, and allow it to deal with resources. Obviously, it isn't necessary to create a wrapper type to allocate a single object. Instead, a local variable of the object's type would work better. ## Remarks -- To reduce the number of warnings, code analysis only detects this pattern for owner pointers. So, it's necessary to mark owners properly first. We can easily extend this to cover raw pointers if we receive feedback on the Visual Studio C++ [Developer Community](https://aka.ms/feedback/suggest?space=62) from customers in support of such scenarios. +- To reduce the number of warnings, code analysis only detects this pattern for owner pointers. So, it's necessary to mark owners properly first. We can easily extend this analysis to cover raw pointers if we receive feedback on the Visual Studio C++ [Developer Community](https://aka.ms/feedback/suggest?space=62) from customers in support of such scenarios. + +- The *scoped object* term may be a bit misleading. In general, we suggest you use either a local variable whose lifetime is automatically managed, or a smart object that efficiently manages dynamic resources. Smart objects can do heap allocations, but it's not explicit in the code. -- The *scoped object* term may be a bit misleading. In general, we suggest you use either a local variable whose lifetime is automatically managed, or a smart object that efficiently manages dynamic resources. Smart objects can of course do heap allocations, but it's not explicit in the code. +- If the warning fires on array allocation, which is often needed for dynamic buffers, you can fix it by using standard containers, or `std::unique_pointer`. -- If the warning fires on array allocation, (which is usually needed for dynamic buffers), you can fix it by using standard containers, or `std::unique_pointer`. +- The pattern is detected only for local variables. We don't warn in cases where an allocation is assigned to, say, a global variable and then deleted in the same function. -- The pattern is detected only for local variables. We don’t warn in cases where an allocation is assigned to, say, a global variable and then deleted in the same function. +Code analysis name: `DONT_HEAP_ALLOCATE_UNNECESSARILY` ## Example 1: Unnecessary object allocation on heap diff --git a/docs/code-quality/c26408.md b/docs/code-quality/c26408.md index ae507ff456..159c8cbfb0 100644 --- a/docs/code-quality/c26408.md +++ b/docs/code-quality/c26408.md @@ -1,21 +1,24 @@ --- -title: C26408 +title: Warning C26408 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26408"] +f1_keywords: ["C26408", "NO_MALLOC_FREE"] helpviewer_keywords: ["C26408"] ms.assetid: 55b0706f-1107-41c1-8ad0-c9e1e86a3b8c description: CppCoreCheck rule that enforces C++ Core Guidelines R.10 --- -# C26408 NO_MALLOC_FREE +# Warning C26408 -This warning flags places where `malloc` or `free` is invoked explicitly in accordance to R.10: Avoid `malloc` and `free`. One potential fix for such warnings would be to use [std::make_unique](../standard-library/memory-functions.md#make_unique) to avoid explicit creation and destruction of objects. If such a fix is not acceptable, operator [new and delete](../cpp/new-and-delete-operators.md) should be preferred. In some cases, if exceptions are not welcome, `malloc` and `free` can be replaced with the nothrow version of operators `new` and `delete`. +> Avoid `malloc()` and `free()`, prefer the `nothrow` version of `new` with `delete` (r.10) + +This warning flags places where `malloc` or `free` is invoked explicitly in accordance to R.10: Avoid `malloc` and `free`. One potential fix for such warnings would be to use [std::make_unique](../standard-library/memory-functions.md#make_unique) to avoid explicit creation and destruction of objects. If such a fix isn't acceptable, operator [new and delete](../cpp/new-and-delete-operators.md) should be preferred. In some cases, if exceptions aren't welcome, `malloc` and `free` can be replaced with the nothrow version of operators `new` and `delete`. ## Remarks -- To detect malloc() we check if a call invokes a global function with name "malloc" or "std::malloc". The function must return a pointer to **`void`** and accept one parameter of unsigned integral type. +- To detect `malloc()`, we check if a call invokes a global function named `malloc` or `std::malloc`. The function must return a pointer to **`void`** and accept one parameter of unsigned integral type. + +- To detect `free()`, we check global functions named `free` or `std::free` that return no result and accept one parameter, which is a pointer to **`void`**. -- To detect free() we check global functions with names "free" or "std::free" which return no result and accept one parameter, which is a pointer to **`void`**. +Code analysis name: `NO_MALLOC_FREE` ## See also diff --git a/docs/code-quality/c26409.md b/docs/code-quality/c26409.md index 81344c1b46..a0dc4a4f3d 100644 --- a/docs/code-quality/c26409.md +++ b/docs/code-quality/c26409.md @@ -1,20 +1,18 @@ --- +title: Warning C26409 description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete." -title: C26409 ms.date: 12/14/2020 -ms.topic: "conceptual" -f1_keywords: ["C26409"] +f1_keywords: ["C26409", "NO_NEW_DELETE"] helpviewer_keywords: ["C26409"] -ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37 --- -# C26409 NO_NEW_DELETE +# Warning C26409 -> `Avoid calling new and delete explicitly, use std::make_unique instead (r.11).` +> Avoid calling `new` and `delete` explicitly, use `std::make_unique` instead (r.11). Even if code is clean of calls to `malloc` and `free`, we still suggest that you consider better options than explicit use of operators [`new` and `delete`](../cpp/new-and-delete-operators.md). **C++ Core Guidelines**:\ -[R.11: Avoid calling new and delete explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly) +[R.11: Avoid calling `new` and `delete` explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly) The ultimate fix is to use smart pointers and appropriate factory functions, such as [`std::make_unique`](../standard-library/memory-functions.md#make_unique). @@ -22,6 +20,8 @@ The ultimate fix is to use smart pointers and appropriate factory functions, suc - The checker warns on calls to any kind of operator **`new`** or **`delete`**: scalar, vector, overloaded versions (global and class-specific), and placement versions. The placement **`new`** case may require some clarifications in the Core Guidelines for suggested fixes, and may be omitted in the future. +Code analysis name: `NO_NEW_DELETE` + ## Examples This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead. @@ -36,7 +36,7 @@ void f(int i) } ``` -There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: +There's a C++ idiom that triggers this warning: `delete this`. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: ```cpp class MyReferenceCountingObject final @@ -48,7 +48,7 @@ public: ref_count_--; if (ref_count_ == 0) { - [[gsl::suppress(i.11)]] + [[gsl::suppress("i.11")]] delete this; } } diff --git a/docs/code-quality/c26410.md b/docs/code-quality/c26410.md index ea44343787..ea77c9e0df 100644 --- a/docs/code-quality/c26410.md +++ b/docs/code-quality/c26410.md @@ -1,23 +1,28 @@ --- -description: "Learn more about: C26410 NO_REF_TO_CONST_UNIQUE_PTR" -title: C26410 +description: "Learn more about: Warning C26410 NO_REF_TO_CONST_UNIQUE_PTR" +title: Warning C26410 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26410"] +f1_keywords: ["C26410", "NO_REF_TO_CONST_UNIQUE_PTR"] helpviewer_keywords: ["C26410"] ms.assetid: d1547faf-96c6-48da-90f5-841154d0e878 --- -# C26410 NO_REF_TO_CONST_UNIQUE_PTR +# Warning C26410 + +> The parameter '*parameter*' is a reference to const unique pointer, use `const T*` or `const T&` instead (r.32) Generally, references to const unique pointer are meaningless. They can safely be replaced by a raw reference or a pointer. This warning enforces [C++ Core Guidelines rule R.32](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r32-take-a-unique_ptrwidget-parameter-to-express-that-a-function-assumes-ownership-of-a-widget). ## Remarks -- Unique pointer checks have rather broad criteria to identify smart pointers. The [C++ Core Guidelines rule R.31](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r31-if-you-have-non-std-smart-pointers-follow-the-basic-pattern-from-std): *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type which defines either operator-> or operator\*; a copy-able type (shared pointer) must have either public copy constructor or overloaded assignment operator which deals with a non-R-value reference parameter. +- Unique pointer checks have rather broad criteria to identify smart pointers. The [C++ Core Guidelines rule R.31](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r31-if-you-have-non-std-smart-pointers-follow-the-basic-pattern-from-std): *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type that defines either `operator->` or `operator*`. A copy-able type (shared pointer) must have either a public copy constructor or an overloaded assignment operator that deals with a non-Rvalue reference parameter. + +- Template code may produce noisy warnings. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed. + +Code analysis name: `NO_REF_TO_CONST_UNIQUE_PTR` -- Template code may produce a lot of noise. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed. +## Example -## Example 1: Unnecessary reference +Unnecessary reference: ```cpp std::vector> roots = GetRoots(); diff --git a/docs/code-quality/c26411.md b/docs/code-quality/c26411.md index a18594bc5b..d0ff131460 100644 --- a/docs/code-quality/c26411.md +++ b/docs/code-quality/c26411.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: C26411 NO_REF_TO_UNIQUE_PTR" -title: C26411 +description: "Learn more about: Warning C26411 NO_REF_TO_UNIQUE_PTR" +title: Warning C26411 ms.date: 08/19/2020 -ms.topic: "conceptual" -f1_keywords: ["C26411"] +f1_keywords: ["C26411", "NO_REF_TO_UNIQUE_PTR"] helpviewer_keywords: ["C26411"] ms.assetid: 5134e51e-8b92-4ee7-94c3-022e318a0e24 --- -# C26411 NO_REF_TO_UNIQUE_PTR +# Warning C26411 -When you pass a unique pointer to a function by reference, it implies that its resource may be released or transferred inside the function. If the function uses its parameter only to access the resource, it's safe to pass a raw pointer or a reference. For additional information, see [C++ Core Guidelines rule R.33](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r33-take-a-unique_ptrwidget-parameter-to-express-that-a-function-reseats-thewidget): *Take a unique_ptr\& parameter to express that a function reseats the widget*. +> The parameter '*parameter*' is a reference to unique pointer and it is never reassigned or reset, use `T*` or `T&` instead (r.33) + +When you pass a unique pointer to a function by reference, it implies that its resource may be released or transferred inside the function. If the function uses its parameter only to access the resource, it's safe to pass a raw pointer or a reference. For more information, see [C++ Core Guidelines rule R.33](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r33-take-a-unique_ptrwidget-parameter-to-express-that-a-function-reseats-thewidget): *Take a unique_ptr\& parameter to express that a function reseats the widget*. ## Remarks @@ -17,10 +18,12 @@ When you pass a unique pointer to a function by reference, it implies that its r - The heuristic to detect `release` or `reset` access to the unique pointer is naive. We only detect calls to assignment operators and to functions named `reset` (case-insensitive). Obviously, this detection doesn't cover all possible cases of smart pointer modifications. (For example, it doesn't detect `std::swap`, or any special non-**`const`** function in a custom smart pointer). We expect this warning may produce many false positives on custom types, and in some scenarios dealing with standard unique pointers. We expect to improve the heuristic as we implement more checks focused on smart pointers. -- The fact that smart pointers are often templates brings an interesting limitation. The compiler isn't required to process template code in templates if it's not used. In code that makes limited use of smart pointer interfaces, the checker may produce unexpected results. The checker can't properly identify semantics of the template type, because some functions may never get used. For the standard `std::unique_ptr`, this limitation is mitigated by recognizing the type's name. This may be extended in future to cover more well-known smart pointers. +- The fact that smart pointers are often templates brings an interesting limitation. The compiler isn't required to process template code in templates if it's not used. In code that makes limited use of smart pointer interfaces, the checker may produce unexpected results. The checker can't properly identify semantics of the template type, because some functions may never get used. For the standard `std::unique_ptr`, this limitation is mitigated by recognizing the type's name. This analysis may be extended in the future to cover more well-known smart pointers. - Lambda expressions that do implicit capture-by-reference may lead to surprising warnings about references to unique pointers. Currently, all captured reference parameters in lambdas are reported, regardless of whether they're reset or not. A future release may extend the heuristic to correlate lambda fields and lambda parameters. +Code analysis name: `NO_REF_TO_UNIQUE_PTR` + ## Example: Unnecessary reference ```cpp diff --git a/docs/code-quality/c26414.md b/docs/code-quality/c26414.md index 494b2ea93e..d33427adcb 100644 --- a/docs/code-quality/c26414.md +++ b/docs/code-quality/c26414.md @@ -1,18 +1,16 @@ --- -title: C26414 +title: Warning C26414 description: "Reference for Visual Studio C++ Core Guidelines code analysis warning C26414." ms.date: 01/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26414"] +f1_keywords: ["C26414", "RESET_LOCAL_SMART_PTR"] helpviewer_keywords: ["C26414"] -ms.assetid: dd875d0c-6752-4491-a533-3e8831795fbc --- -# C26414 RESET_LOCAL_SMART_PTR +# Warning C26414 > "Move, copy, reassign or reset a local smart pointer." **C++ Core Guidelines**:\ -[R.5: Prefer scoped objects, don't heap-allocate unnecessarily](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-scoped) +[R.5: Prefer scoped objects, don't heap-allocate unnecessarily](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r5-prefer-scoped-objects-dont-heap-allocate-unnecessarily) Smart pointers are convenient for dynamic resource management, but they're not always necessary. For example, it may be easier and more efficient to manage a local dynamic buffer by using a standard container. You may not need dynamic allocation at all for single objects, for example, if they never outlive their creator function. They can be replaced with local variables. Smart pointers become handy when a scenario requires a change of ownership. For example, when you reassign a dynamic resource multiple times, or in multiple paths. They're also useful for resources obtained from external code. And, when smart pointers are used to extend the lifetime of a resource. @@ -20,7 +18,7 @@ Smart pointers are convenient for dynamic resource management, but they're not a This check recognizes both the standard `std::unique_pointer` and `std::shared_pointer` templates, and user-defined types that are likely intended to be smart pointers. Such types are expected to define the following operations: -- overloaded dereference or member access operators, that are public and not marked as deleted; +- overloaded dereference or member access operators that are public and not marked as deleted; - a public destructor that isn't deleted or defaulted. That includes destructors explicitly defined as empty. @@ -28,9 +26,11 @@ The type `Microsoft::WRL::ComPtr` behaves as a shared pointer, but it's often us This check looks for explicit local allocations assigned to smart pointers, to identify if scoped variables could work as an alternative. Both direct calls to operator `new`, and special functions like `std::make_unique` and `std::make_shared`, are interpreted as direct allocations. +Code analysis name: `RESET_LOCAL_SMART_PTR` + ## Example -Dynamic buffer +Dynamic buffer: ```cpp void unpack_and_send(const frame &f) @@ -41,7 +41,7 @@ void unpack_and_send(const frame &f) } ``` -Dynamic buffer – replaced by container +Dynamic buffer replaced by container: ```cpp void unpack_and_send(const frame &f) diff --git a/docs/code-quality/c26415.md b/docs/code-quality/c26415.md index bff20f1527..8dfc40ae41 100644 --- a/docs/code-quality/c26415.md +++ b/docs/code-quality/c26415.md @@ -1,29 +1,28 @@ --- -description: "Learn more about: C26415 SMART_PTR_NOT_NEEDED" -title: C26415 +description: "Learn more about: Warning C26415 SMART_PTR_NOT_NEEDED" +title: Warning C26415 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26415"] +f1_keywords: ["C26415", "SMART_PTR_NOT_NEEDED"] helpviewer_keywords: ["C26415"] ms.assetid: 4165f70a-78ae-4a03-b256-c4bd74b02d09 --- -# C26415 SMART_PTR_NOT_NEEDED +# Warning C26415 -"Smart pointer parameter is used only to access contained pointer. Use T* or T& instead." +> Smart pointer parameter is used only to access contained pointer. Use T* or T& instead. **C++ Core Guidelines**: [R.30](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r30-take-smart-pointers-as-parameters-only-to-explicitly-express-lifetime-semantics): Take smart pointers as parameters only to explicitly express lifetime semantics -Using a smart pointer type to pass data to a function indicates that the target function needs to manage the lifetime of the contained object. However, if the function only uses the smart pointer to access the contained object and never actually calls any code that may lead to its deallocation (that is, never affect its lifetime), there is usually no need to complicate the interface with smart pointers. A plain pointer or reference to the contained object is preferred. +Using a smart pointer type to pass data to a function indicates that the target function needs to manage the lifetime of the contained object. However, say the function only uses the smart pointer to access the contained object and never actually calls any code that may lead to its deallocation (that is, never affects its lifetime). Then there's usually no need to complicate the interface with smart pointers. A plain pointer or reference to the contained object is preferred. ## Remarks -This check covers a majority of scenarios that also cause C26410, C26415, C26417, and C26418. It is better to clean up SMART_PTR_NOT_NEEDED first and then switch to edge cases for shared or unique pointers. For more focused cleanup, this warning can be disabled. +This check covers most scenarios that also cause C26410, C26415, C26417, and C26418. It's better to clean up SMART_PTR_NOT_NEEDED first and then switch to edge cases for shared or unique pointers. For more focused cleanup, this warning can be disabled. In addition to the standard std::unqiue_pointer and std::shared_pointer templates, this check recognizes user-defined types that are likely intended to be smart pointers. Such types are expected to define the following operations: - Overloaded dereference or member access operators that are public and not marked as deleted. -- Public destructor that's not deleted or defaulted. This includes destructors that are explicitly defined empty. +- Public destructor that's not deleted or defaulted, including destructors that are explicitly defined empty. Interpretation of the operations that can affect the lifetime of contained objects is broad and includes: diff --git a/docs/code-quality/c26416.md b/docs/code-quality/c26416.md index 007443126c..1bd6192adc 100644 --- a/docs/code-quality/c26416.md +++ b/docs/code-quality/c26416.md @@ -1,34 +1,33 @@ --- -description: "Learn more about: C26416 NO_RVALUE_REF_SHARED_PTR" -title: C26416 +description: "Learn more about: Warning C26416 NO_RVALUE_REF_SHARED_PTR" +title: Warning C26416 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26416"] +f1_keywords: ["C26416", "NO_RVALUE_REF_SHARED_PTR"] helpviewer_keywords: ["C26416"] ms.assetid: f158207b-45cf-44cf-8e4b-b5b75b56ea0e --- -# C26416 NO_RVALUE_REF_SHARED_PTR +# Warning C26416 > Shared pointer parameter is passed by rvalue reference. Pass by value instead. **C++ Core Guidelines**: [R.34](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r34-take-a-shared_ptrwidget-parameter-to-express-that-a-function-is-part-owner): Take a shared_ptr\ parameter to express that a function is part owner -Passing a shared pointer by rvalue reference is usually unnecessary. Unless it is an implementation of move semantics for a shared pointer type itself, shared pointer objects can be safely passed by value. Using rvalue reference may be also an indication that unique pointer is more appropriate since it clearly transfers unique ownership from caller to callee. +Passing a shared pointer by rvalue reference is rarely necessary. Unless it's an implementation of move semantics for a shared pointer type itself, shared pointer objects can be safely passed by value. Using rvalue reference may be also an indication that unique pointer is more appropriate since it clearly transfers unique ownership from caller to callee. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. ## Examples -questionable constructor optimization +Questionable constructor optimization: ```cpp action::action(std::shared_ptr &&t) noexcept // C26416 @@ -40,7 +39,7 @@ action::action(std::shared_ptr &t) noexcept // also C26417 LVALUE_ {} ``` -questionable constructor optimization - simplified +Questionable constructor optimization - simplified: ```cpp action::action(std::shared_ptr t) noexcept diff --git a/docs/code-quality/c26417.md b/docs/code-quality/c26417.md index 02f6623f84..7659d01250 100644 --- a/docs/code-quality/c26417.md +++ b/docs/code-quality/c26417.md @@ -1,36 +1,35 @@ --- -description: "Learn more about: C26417 NO_LVALUE_REF_SHARED_PTR" -title: C26417 +description: "Learn more about: Warning C26417 NO_LVALUE_REF_SHARED_PTR" +title: Warning C26417 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26417"] +f1_keywords: ["C26417", "NO_LVALUE_REF_SHARED_PTR"] helpviewer_keywords: ["C26417"] ms.assetid: 0e09fcc6-f9eb-4404-b51e-5815705c6afb --- -# C26417 NO_LVALUE_REF_SHARED_PTR +# Warning C26417 > Shared pointer parameter is passed by reference and not reset or reassigned. Use T* or T& instead. **C++ Core Guidelines**: [R.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r35-take-a-shared_ptrwidget-parameter-to-express-that-a-function-might-reseat-the-shared-pointer): Take a shared_ptr\& parameter to express that a function might reseat the shared pointer -Passing shared pointers by reference may be useful in scenarios where callee code updates target of the smart pointer object and its caller expects to see such update. Using a reference solely to reduce costs of passing a shared pointer is questionable. If callee code only accesses target object and never manages its lifetime, it is safer to pass raw pointer or reference, rather than to expose resource management details. +Passing shared pointers by reference may be useful in scenarios where called code updates the target of the smart pointer object, and its caller expects to see such updates. Using a reference solely to reduce costs of passing a shared pointer is questionable. If called code only accesses the target object and never manages its lifetime, it's safer to pass a raw pointer or reference, rather than to expose resource management details. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. - The action of resetting or reassigning is interpreted in a more generic way: - any call to a non-constant function on a shared pointer can potentially reset the pointer; -- any call to a function which accepts a reference to a non-constant shared pointer can potentially reset or reassign that pointer. +- any call to a function that accepts a reference to a non-constant shared pointer can potentially reset or reassign that pointer. ## Examples diff --git a/docs/code-quality/c26418.md b/docs/code-quality/c26418.md index 7c5c2eb469..d1a07d1b8d 100644 --- a/docs/code-quality/c26418.md +++ b/docs/code-quality/c26418.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR" -title: C26418| Microsoft Docs +description: "Learn more about: Warning C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR" +title: Warning C26418 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26418"] +f1_keywords: ["C26418", "NO_VALUE_OR_CONST_REF_SHARED_PTR"] helpviewer_keywords: ["C26418"] ms.assetid: d2c84a40-8a5d-4018-92c2-6498cdd9b541 --- -# C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR +# Warning C26418 > Shared pointer parameter is not copied or moved. Use T* or T& instead. **C++ Core Guidelines**: [R.36](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r36-take-a-const-shared_ptrwidget-parameter-to-express-that-it-might-retain-a-reference-count-to-the-object-): Take a const shared_ptr\& parameter to express that it might retain a reference count to the object -If shared pointer parameter is passed by value or reference to a constant object it is expected that function will take control of its target object’s lifetime without affecting of the caller. The code should either copy or move the shared pointer parameter to another shared pointer object or pass it further to other code by invoking functions which accept shared pointers. If this is not the case, then plain pointer or reference may be feasible. +If a shared pointer parameter is passed by value or by reference to a constant object, the function is expected to take control of the target object's lifetime without affecting the caller. The code should either copy or move the shared pointer parameter to another shared pointer object, or pass it along to other code by invoking functions that accept shared pointers. Otherwise, a plain pointer or reference may be feasible. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. ## Examples diff --git a/docs/code-quality/c26426.md b/docs/code-quality/c26426.md index 0b9877fbff..818d76d22d 100644 --- a/docs/code-quality/c26426.md +++ b/docs/code-quality/c26426.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: C26426 NO_GLOBAL_INIT_CALLS" -title: C26426 +description: "Learn more about: Warning C26426 NO_GLOBAL_INIT_CALLS" +title: Warning C26426 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26426"] +f1_keywords: ["C26426", "NO_GLOBAL_INIT_CALLS"] helpviewer_keywords: ["C26426"] ms.assetid: 6fb5f6d2-b097-47f8-8b49-f2fd4e9bef0e --- -# C26426 NO_GLOBAL_INIT_CALLS +# Warning C26426 -"Global initializer calls a non-constexpr function." +> Global initializer calls a non-constexpr function '*symbol*' (i.22) + +## C++ Core Guidelines -**C++ Core Guidelines**: [I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects -The order of execution of initializers for global objects may be inconsistent or undefined. This can lead to issues that are hard to reproduce and investigate. To avoid such problems, global initializers should not depend on external code that's executed at run time and can potentially depend on data that's not yet initialized. This rule flags cases where global objects call functions to obtain their initial values. +The order of execution of initializers for global objects may be inconsistent or undefined, which can lead to issues that are hard to reproduce and investigate. To avoid such problems, global initializers shouldn't depend on external code that's executed at run time, and that may depend on data that's not yet initialized. This rule flags cases where global objects call functions to obtain their initial values. ## Remarks -- The rule ignores calls to constexpr functions or intrinsic functions on assumption that these either will be calculated at compile time or guarantee predictable execution at run time. +- The rule ignores calls to `constexpr` functions or intrinsic functions on the assumption that these calls either will be calculated at compile time or guarantee predictable execution at run time. -- Calls to inline functions are still flagged since the checker doesn’t attempt to analyze their implementation. +- Calls to inline functions are still flagged, since the checker doesn't attempt to analyze their implementation. -- This rule can be noisy in many common scenarios where a variable of a user-defined type (or standard container) is initialized globally: this is often due to calls to constructors and destructors. This is still a valid warning since it points to places where unpredictable behavior may exist or future changes in external code may introduce instability. +- This rule can be noisy in many common scenarios where a variable of a user-defined type (or a standard container) is initialized globally. It's often due to calls to constructors and destructors. It's still a valid warning, since it points to places where unpredictable behavior may exist or where future changes in external code may introduce instability. - Static class members are considered global, so their initializers are also checked. +Code analysis name: `NO_GLOBAL_INIT_CALLS` + ## Examples -external version check +External version check: ```cpp // api.cpp @@ -42,7 +44,7 @@ int get_api_version() noexcept; bool is_legacy_mode = get_api_version() <= API_LEGACY_VERSION; // C26426, also stale value ``` -external version check – made more reliable +External version check made more reliable: ```cpp // api.cpp diff --git a/docs/code-quality/c26427.md b/docs/code-quality/c26427.md index 97f63d5b5c..556e26de75 100644 --- a/docs/code-quality/c26427.md +++ b/docs/code-quality/c26427.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26427 NO_GLOBAL_INIT_EXTERNS" -title: C26427 +description: "Learn more about: Warning C26427 NO_GLOBAL_INIT_EXTERNS" +title: Warning C26427 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26427"] +f1_keywords: ["C26427", "NO_GLOBAL_INIT_EXTERNS"] helpviewer_keywords: ["C26427"] ms.assetid: 8fb95a44-8704-45b1-bc55-eccd59b1db2f --- -# C26427 NO_GLOBAL_INIT_EXTERNS +# Warning C26427 -"Global initializer accesses extern object." +> Global initializer accesses extern object '*symbol*' (i.22) **C++ Core Guidelines**: [I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects @@ -20,14 +19,16 @@ Global objects may be initialized in an inconsistent or undefined order, which m An object is deemed **`extern`** if it conforms to the following rules: -- it's a global variable marked with **`extern`** specifier or it is a static member of a class; +- it's a global variable marked with **`extern`** specifier or it's a static member of a class; - it's not in an anonymous namespace; - it's not marked as **`const`**; - Static class members are considered global, so their initializers are also checked. +Code analysis name: `NO_GLOBAL_INIT_EXTERNS` + ## Example -external version check +External version check: ```cpp // api.cpp @@ -38,7 +39,7 @@ extern int api_version; bool is_legacy_mode = api_version <= API_LEGACY_VERSION; // C26427, also stale value ``` -external version check – made more reliable +External version check made more reliable: ```cpp // api.cpp diff --git a/docs/code-quality/c26429.md b/docs/code-quality/c26429.md index de8800ee3f..9543595243 100644 --- a/docs/code-quality/c26429.md +++ b/docs/code-quality/c26429.md @@ -1,35 +1,39 @@ --- -description: "Learn more about: C26429 USE_NOTNULL" -title: C26429 +description: "Learn more about: Warning C26429 USE_NOTNULL" +title: Warning C26429 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26429"] +f1_keywords: ["C26429", "USE_NOTNULL"] helpviewer_keywords: ["C26429"] ms.assetid: 4e1c74d5-7307-436c-927b-f74ae863282c - --- -# C26429 USE_NOTNULL +# Warning C26429 -"Symbol is never tested for nullness, it can be marked as gsl::not_null." +> Symbol is never tested for nullness, it can be marked as `gsl::not_null`. **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a `not_null` to indicate that "null" isn't a valid value -It is a common practice to use asserts to enforce assumptions about validity of pointer values. The problem with asserts is that they do not expose assumptions through the interface (e.g. in return types or parameters). Asserts are also harder to maintain and keep in sync with other code changes. The recommendation is to use gsl::not_null from the Guidelines Support Library as a marker of resources which should never have null value. The rule USE_NOTNULL helps to identify places that omit checks for nullness and hence can be updated to use gsl::not_null. +It's a common practice to use asserts to enforce assumptions about the validity of pointer values. The problem is, asserts don't expose assumptions through the interface (such as in return types or parameters). Asserts are also harder to maintain and keep in sync with other code changes. The recommendation is to use `gsl::not_null` from the Guidelines Support Library to mark resources that should never have a null value. The rule `USE_NOTNULL` helps to identify places that omit checks for null and hence can be updated to use `gsl::not_null`. ## Remarks -- The logic of the rule requires code to dereference a pointer variable so that nullness check (or enforcement of non-null value) would be justified. So, warning will be emitted only if pointers are dereferenced and never tested for nullness. - - Current implementation handles only plain pointers (or their aliases) and doesn’t detect smart pointers even though gsl::not_null can be applied to smart pointers as well. - - A variable is marked as checked for nullness when it is used in the following contexts: - - as a symbol expression in a branch condition, e.g. "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression which evaluates to zero. - - The rule doesn’t have full dataflow tracking and can produce incorrect results in cases where indirect checks are used (e.g. when intermediate variable holds null value and later used in comparison). +The logic of the rule requires code to dereference a pointer variable so that a null check (or enforcement of a non-null value) would be justified. So, warnings are emitted only if pointers are dereferenced and never tested for null. + +The current implementation handles only plain pointers (or their aliases) and doesn't detect smart pointers, even though `gsl::not_null` can be applied to smart pointers as well. + +A variable is marked as checked for null when it's used in the following contexts: + +- as a symbol expression in a branch condition, for example, `if (p) { ... }`; +- non-bitwise logical operations; +- comparison operations where one operand is a constant expression that evaluates to zero. + +The rule doesn't have full dataflow tracking. It can produce incorrect results in cases where indirect checks are used (such as when an intermediate variable holds a null value and is later used in a comparison). + +Code analysis name: `USE_NOTNULL` ## Example -hidden expectation +Hidden expectation: ```cpp using client_collection = gsl::span; @@ -46,7 +50,7 @@ void keep_alive(const connection *connection) // C26429 } ``` -hidden expectation – clarified by gsl::not_null +Hidden expectation clarified by `gsl::not_null`: ```cpp using client_collection = gsl::span>; diff --git a/docs/code-quality/c26430.md b/docs/code-quality/c26430.md index e3a54f4e0b..230352b2e9 100644 --- a/docs/code-quality/c26430.md +++ b/docs/code-quality/c26430.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: C26430 TEST_ON_ALL_PATHS" -title: C26430 +description: "Learn more about: Warning C26430 TEST_ON_ALL_PATHS" +title: Warning C26430 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26430"] +f1_keywords: ["C26430", "TEST_ON_ALL_PATHS"] helpviewer_keywords: ["C26430"] ms.assetid: 3dca2626-8102-4eed-8ff3-73eb3d5c328c - --- -# C26430 TEST_ON_ALL_PATHS +# Warning C26430 -"Symbol is not tested for nullness on all paths." +> Symbol is not tested for nullness on all paths. **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" isn't a valid value -If code ever checks nullness of pointer variables it should do this consistently and validate pointers on all paths. Sometimes overaggressive checking for nullness is still better than possibility of a hard crash in one of the complicated branches. Ideally such code should be refactored to be less complex (by splitting into multiple functions) and to rely on markers like gsl::not_null (see Guidelines Support Library) to isolate parts of algorithm that can make safe assumption about valid pointer values. The rule TEST_ON_ALL_PATHS helps to find places where nullness checks are either inconsistent (hence assumptions may require review) or actual bugs where potential null value can bypass nullness check in some of the code paths. +If code ever checks pointer variables for null, it should do so consistently and validate pointers on all paths. Sometimes overaggressive checking for null is still better than the possibility of a hard crash in one of the complicated branches. Ideally, such code should be refactored to be less complex (by splitting it into multiple functions), and to rely on markers like `gsl::not_null`. These markers allow the code to isolate parts of the algorithm that can make safe assumptions about valid pointer values. The rule `TEST_ON_ALL_PATHS` helps to find places where null checks are inconsistent (meaning assumptions may require review). Or, it finds actual bugs where a potential null value can bypass null checks in some of the code paths. ## Remarks -- This rule expects that code dereferences a pointer variable so that nullness check (or enforcement of non-null value) would be justified. If there is no dereference, the rule is suspended. - - Current implementation handles only plain pointers (or their aliases) and doesn’t detect smart pointers even though nullness checks are applicable to smart pointers as well. - - A variable is marked as checked for nullness when it is used in the following contexts: - - as a symbol expression in a branch condition, e.g. "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression which evaluates to zero. - - The rule doesn’t have full data flow tracking and can produce incorrect results in cases where indirect checks are used (e.g. when intermediate variable holds null value and later used in comparison). - - Implicit nullness checks are assumed when pointer value is assigned from: - - an allocation performed with throwing operator new; - - a pointer obtained from type marked with gsl::not_null. +This rule expects that code dereferences a pointer variable so that a null check (or enforcement of a non-null value) would be justified. If there's no dereference, the rule is suspended. + +The current implementation handles only plain pointers (or their aliases) and doesn't detect smart pointers, even though null checks are applicable to smart pointers as well. + +A variable is marked as checked for null when it's used in the following contexts: + +- as a symbol expression in a branch condition, for example, in `if (p) { ... }`; +- in non-bitwise logical operations; +- in comparison operations where one operand is a constant expression that evaluates to zero. + +Implicit null checks are assumed when a pointer value is assigned from: + +- an allocation performed with throwing `operator new`; +- a pointer obtained from a type marked with `gsl::not_null`. ## Example @@ -63,3 +65,36 @@ void merge_states(gsl::not_null left, gsl::not_null The type of expression '*expr*' is already `gsl::not_null`. Do not test it for nullness (f.23) **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" isn't a valid value -The marker type gsl::not_null from Guidelines Support Library is used to clearly indicate values that are never null pointers. It causes a hard failure if such assumption is not held at run time. So, obviously, there is no need to check for nullness if expression evaluates to a result of type gsl::not_null. +The marker type `gsl::not_null` from the Guidelines Support Library is used to clearly indicate values that are never null pointers. It causes a hard failure if the assumption doesn't hold at run time. So, obviously, there's no need to check for null if an expression evaluates to a result of type `gsl::not_null`. ## Remarks -- Since gsl::not_null itself is a thin pointer wrapper class, the rule actually tracks temporary variables that hold results from calls to the overloaded conversion operator (which returns contained pointer object). Such logic makes this rule applicable to expressions that involve variables and eventually have result of the gsl::not_null type. But it currently skips expressions that contain function calls returning gsl::not_null. - - Current heuristic for nullness checks detects the following contexts: - - symbol expression in a branch condition, for example "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression that evaluates to zero. +Since `gsl::not_null` itself is a thin pointer wrapper class, the rule actually tracks temporary variables that hold results from calls to the overloaded conversion operator (which returns contained pointer objects). Such logic makes this rule applicable to expressions that involve variables and eventually have a result of the `gsl::not_null` type. However, it currently skips expressions that contain function calls returning `gsl::not_null`. + +The current heuristic for null checks detects the following contexts: + +- a symbol expression in a branch condition, for example `if (p) { ... }`; +- non-bitwise logical operations; +- comparison operations where one operand is a constant expression that evaluates to zero. + +Code analysis name: `DONT_TEST_NOTNULL` ## Example -unnecessary null checks reveal questionable logic +Unnecessary null checks reveal questionable logic: ```cpp class type { @@ -58,7 +60,7 @@ public: }; ``` -unnecessary null checks reveal questionable logic - reworked +Unnecessary null checks reveal questionable logic, reworked: ```cpp //... diff --git a/docs/code-quality/c26432.md b/docs/code-quality/c26432.md index d98e920d65..b9de0b8929 100644 --- a/docs/code-quality/c26432.md +++ b/docs/code-quality/c26432.md @@ -1,32 +1,34 @@ --- -title: C26432 +title: Warning C26432 description: "Microsoft C++ Code Analysis warning C26432 for the C++ Core Guidelines case C.21." ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26432"] +f1_keywords: ["C26432", "DEFINE_OR_DELETE_SPECIAL_OPS"] helpviewer_keywords: ["C26432"] -ms.assetid: f587b05a-5c69-4176-baa6-fcb79d228b24 --- -# C26432 DEFINE_OR_DELETE_SPECIAL_OPS +# Warning C26432 > `If you define or delete any default operation in the type 'type-name', define or delete them all (c.21).` **C++ Core Guidelines**:\ -[C.21: If you define or =delete any default operation, define or =delete them all](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c21-if-you-define-or-delete-any-default-operation-define-or-delete-them-all) +[C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c21-if-you-define-or-delete-any-copy-move-or-destructor-function-define-or-delete-them-all) Special operations such as constructors are assumed to alter the behavior of types so they rely more on language mechanisms to automatically enforce specific scenarios. The canonical example is resource management. If you explicitly define, default, or delete any of these special operations, it signals you want to avoid any special handling of a type. It's inconsistent to leave the other operations unspecified, that is, implicitly defined as deleted by the compiler. ## Remarks -- This check implements the *rule of five*, which treats the following operations as special: - - copy constructors, - - move constructors, - - copy assignment operators, - - move assignment operators, and - - destructors. -- The rule doesn't check if operations are defined in the same way. It's okay to mix deleted and defaulted operations with explicitly defined ones. However, you must specify all of them if you specify any of them. -- Access levels aren't important and can also be mixed. -- The warning flags the first non-static function definition of a type, once per type. +This check implements the *rule of five*, which treats the following operations as special: + +- copy constructors, +- move constructors, +- copy assignment operators, +- move assignment operators, and +- destructors. + +The rule doesn't check if operations are defined in the same way. It's okay to mix deleted and defaulted operations with explicitly defined ones. However, you must specify all of them if you specify any of them. + +Access levels aren't important and can also be mixed. + +The warning flags the first non-static function definition of a type, once per type. ## Example diff --git a/docs/code-quality/c26433.md b/docs/code-quality/c26433.md index 6f7553f7f9..ed350b445d 100644 --- a/docs/code-quality/c26433.md +++ b/docs/code-quality/c26433.md @@ -1,28 +1,29 @@ --- -description: "Learn more about: C26433 OVERRIDE_EXPLICITLY" -title: C26433 -keywords: C26433 +description: "Learn more about: Warning C26433 OVERRIDE_EXPLICITLY" +title: Warning C26433 ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26433"] +f1_keywords: ["C26433", "OVERRIDE_EXPLICITLY"] helpviewer_keywords: ["C26433"] -dev_langs: ["C++"] --- -# C26433 OVERRIDE_EXPLICITLY +# Warning C26433 -Function should be marked with `override` +> Function should be marked with `override` ## C++ Core Guidelines [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) -It's not required by the compiler to clearly state that a virtual function overrides its base. Not specifying `override` can cause subtle issues during maintenance if the virtual specification ever changes in the class hierarchy. It also lowers readability and makes an interface's polymorphic behavior less obvious. If a function is clearly marked as `override`, it enables the compiler to check consistency of the interface and help to spot issues before they manifest themselves at run time. +It's not required by the compiler to clearly state that a virtual function overrides its base. Not specifying `override` can cause subtle issues during maintenance if the virtual specification ever changes in the class hierarchy. It also lowers readability and makes an interface's polymorphic behavior less obvious. If a function is clearly marked as `override`, the compiler can check the consistency of the interface, and help to spot issues before they manifest themselves at run time. ## Notes -1. This rule isn't applicable to destructors. Destructors have their own virtuality specifics. -1. The rule doesn't flag functions explicitly marked as `final`, which is itself a special variety of virtual specifier. -1. Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still correct. +This rule isn't applicable to destructors. Destructors have their own virtuality specifics. + +The rule doesn't flag functions explicitly marked as `final`, which is itself a special variety of virtual specifier. + +Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still correct. + +Code analysis name: `OVERRIDE_EXPLICITLY` ## Example: Implicit overriding diff --git a/docs/code-quality/c26434.md b/docs/code-quality/c26434.md index 72041cdace..0bdfe9d173 100644 --- a/docs/code-quality/c26434.md +++ b/docs/code-quality/c26434.md @@ -1,15 +1,13 @@ --- -title: C26434 +title: Warning C26434 description: "Microsoft C++ Code Analysis warning C26434 for the C++ Core Guidelines case C.128." ms.date: 08/21/2020 -ms.topic: "conceptual" -f1_keywords: ["C26434"] +f1_keywords: ["C26434", "DONT_HIDE_METHODS"] helpviewer_keywords: ["C26434"] -ms.assetid: 7f66477f-da66-444a-a6e3-44513d7d7e31 --- -# C26434 DONT_HIDE_METHODS +# Warning C26434 -> `Function 'derived::function' hides a non-virtual function 'base::function' (c.128).` +> Function 'derived::function' hides a non-virtual function 'base::function' (c.128). ## C++ Core Guidelines @@ -17,7 +15,7 @@ ms.assetid: 7f66477f-da66-444a-a6e3-44513d7d7e31 ## Remarks -When you introduce a function that has the same name as a non-virtual function in a base class, you may get unexpected behavior. It's like introducing a variable name which conflicts with a name from an outer scope. For example, you may have intended to override a base class function. If the signatures of the functions don't match, the override you intended may turn into an overload instead. In general, name hiding is dangerous and error-prone. +When you introduce a function that has the same name as a non-virtual function in a base class, you may get unexpected behavior. It's like introducing a variable name that conflicts with a name from an outer scope. For example, you may have intended to override a base class function. If the signatures of the functions don't match, the override you intended may turn into an overload instead. In general, name hiding is dangerous and error-prone. In the Core Guidelines checks: @@ -45,5 +43,4 @@ struct Derived : Base void not_virtual() noexcept {} // C26434, hides a non-virtual function virtual void not_virtual(int i) noexcept {} // C26434, and parameters ignored }; - ``` diff --git a/docs/code-quality/c26435.md b/docs/code-quality/c26435.md index 5aee50571a..ab4ec78c93 100644 --- a/docs/code-quality/c26435.md +++ b/docs/code-quality/c26435.md @@ -1,16 +1,13 @@ --- -description: "Learn more about: C26435 SINGLE_VIRTUAL_SPECIFICATION" -title: C26435 -keywords: C26435 +description: "Learn more about: Warning C26435 SINGLE_VIRTUAL_SPECIFICATION" +title: Warning C26435 ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26435"] +f1_keywords: ["C26435", "SINGLE_VIRTUAL_SPECIFICATION"] helpviewer_keywords: ["C26435"] -dev_langs: ["C++"] --- -# C26435 SINGLE_VIRTUAL_SPECIFICATION +# Warning C26435 -"Function should specify exactly one of 'virtual', 'override', or 'final'." +> The virtual function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final' (c.128) ## C++ Core Guidelines @@ -19,14 +16,16 @@ dev_langs: ["C++"] To improve readability, the kind of virtual behavior should be stated clearly and without unnecessary redundancy. Even though multiple virtual specifiers can be used simultaneously, it's better to specify one at a time to emphasize the most important aspect of virtual behavior. The following order of importance is apparent: - plain virtual function; -- virtual function which explicitly overrides its base; -- virtual function which overrides its base and provides the final implementation in the current inheritance chain. +- virtual function that explicitly overrides its base; +- virtual function that overrides its base and provides the final implementation in the current inheritance chain. ## Notes - This rule skips destructors since they have special rules regarding virtuality. - Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still appropriate. +Code analysis name: `SINGLE_VIRTUAL_SPECIFICATION` + ## Example: Redundant specifier ```cpp @@ -42,6 +41,9 @@ public: void Draw() override final { // C26435, only 'final' is necessary. //... } + virtual void DrawCircumference() final { // C26435, should be neither 'virtual' nor 'final'. + //... + } }; ``` diff --git a/docs/code-quality/c26436.md b/docs/code-quality/c26436.md index 3953b42665..222d58fb20 100644 --- a/docs/code-quality/c26436.md +++ b/docs/code-quality/c26436.md @@ -1,24 +1,26 @@ --- -title: C26436 +title: Warning C26436 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26436"] +f1_keywords: ["C26436", "NEED_VIRTUAL_DTOR"] helpviewer_keywords: ["C26436"] ms.assetid: 82d14d5d-5c5d-4e27-bdc8-268f9973a312 description: CppCoreCheck rule that enforces C++ Core Guidelines C.35 --- -# C26436 NEED_VIRTUAL_DTOR +# Warning C26436 -"The type with a virtual function needs either public virtual or protected nonvirtual destructor." +> The type '*symbol*' with a virtual function needs either public virtual or protected non-virtual destructor (c.35) [**C++ Core Guidelines**: C.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c35-a-base-class-destructor-should-be-either-public-and-virtual-or-protected-and-non-virtual): A base class destructor should be either public and virtual, or protected and nonvirtual -If a class defines a virtual function it becomes polymorphic, which implies that derived classes can change its behavior including resource management and destruction logic. Because client code may call polymorphic types via pointers to base classes, there is no way a client can explicitly choose which behavior is appropriate without downcasting. To make sure that resources are managed consistently and destruction occurs according to the actual type's rules it is recommended to define a public virtual destructor. If the type hierarchy is designed to disallow client code to destroy objects directly, destructors should be defined as protected non-virtual. +If a class defines a virtual function it becomes polymorphic, which implies that derived classes can change its behavior including resource management and destruction logic. Because client code may call polymorphic types via pointers to base classes, there's no way a client can explicitly choose which behavior is appropriate without downcasting. To make sure that resources are managed consistently and destruction occurs according to the actual type's rules, you should define a public virtual destructor. If the type hierarchy is designed to disallow client code to destroy objects directly, destructors should be defined as protected non-virtual. ## Remarks -- The warning shows up on the first virtual function definition of a type (it can be a virtual destructor if it is not public), once per type. - - Since definition can be placed separately from declaration, it may not always have any of the virtual specifiers. But the warning is still valid – it checks the actual 'virtuality' of a function. +- The warning shows up on the first virtual function definition of a type (it can be a virtual destructor if it isn't public), once per type. + +- Since a definition can be placed separately from a declaration, it may not always have any of the virtual specifiers. But the warning is still valid: it checks the actual 'virtuality' of a function. + +Code analysis name: `NEED_VIRTUAL_DTOR` ## Example @@ -31,7 +33,7 @@ namespace no_destructor } ``` -The warning does not appear when the base class has either a virtual public destructor or a protected non-virtual destructor. +The warning doesn't appear when the base class has either a virtual public destructor or a protected non-virtual destructor. ```cpp namespace virtual_destructor diff --git a/docs/code-quality/c26437.md b/docs/code-quality/c26437.md index 4c4bf445b9..2f96db0776 100644 --- a/docs/code-quality/c26437.md +++ b/docs/code-quality/c26437.md @@ -1,33 +1,30 @@ --- -description: "Learn more about: C26437 DONT_SLICE" -title: C26437 -ms.date: 10/07/2019 -ms.topic: "conceptual" -f1_keywords: ["C26437"] +title: Warning C26437 +description: "Learn more about: Warning C26437 DONT_SLICE" +ms.date: 05/17/2023 +f1_keywords: ["C26437", "DONT_SLICE"] helpviewer_keywords: ["C26437"] -ms.assetid: ed2f55bc-a6d8-4cc4-8069-5c96e581a96a - --- -# C26437 DONT_SLICE +# Warning C26437 -"Do not slice." +> Do not slice. **C++ Core Guidelines**: -[ES.63: Don't slice](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-slice) +[ES.63: Don't slice](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es63-dont-slice) -[Slicing](https://en.wikipedia.org/wiki/Object_slicing) is allowed by compiler and can be viewed as a special case of dangerous implicit cast. Even if it is done intentionally and doesn’t lead to immediate issues, it is still highly discouraged since it makes code rather unmaintainable by forcing additional requirements on related data types. This is especially true if types are polymorphic or involve resource management. +The language allows [slicing](https://en.wikipedia.org/wiki/Object_slicing) and can be viewed as a special case of a dangerous implicit cast. Even if it's done intentionally and doesn't lead to immediate issues, it's still highly discouraged. It makes code harder to change, by forcing extra requirements on related data types. It's especially true if types are polymorphic or involve resource management. ## Remarks -- This rule would warn not only on explicit assignments, but also on implicit slicing which happens when result gets returned from current function or data passed as arguments to other functions. - - Warnings would also flag cases where assignment doesn’t involve real data slicing (e.g. if types are empty or don’t make any dangerous data manipulations). Such warnings should still be addressed to prevent any undesirable regressions if types data or behavior changes in future. +This rule warns not only on explicit assignments, but also on implicit slicing. Implicit slicing happens when a result gets returned from the current function, or when data gets passed to other functions. + +The rule also flags cases where an assignment doesn't involve real data slicing (for example, if types are empty or don't make any dangerous data manipulations). Such warnings should still be fixed to prevent any undesirable regressions if data types or behaviors change in the future. ## Example -slicing points to outdated +In the next code example, we read `id_ex`, but the caller of the function will only get a slice of the object: ```cpp -interface struct id { int value; }; @@ -46,7 +43,7 @@ bool read_id(stream &s, id &v) { } ``` -slicing points to outdated, interface - corrected +To fix the issue, update the function to use the correct types: ```cpp // ... diff --git a/docs/code-quality/c26438.md b/docs/code-quality/c26438.md index a5b0371fc5..e6c696ca31 100644 --- a/docs/code-quality/c26438.md +++ b/docs/code-quality/c26438.md @@ -1,16 +1,14 @@ --- -description: "Learn more about: C26438 NO_GOTO" -title: C26438 +description: "Learn more about: Warning C26438 NO_GOTO" +title: Warning C26438 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26438"] +f1_keywords: ["C26438", "NO_GOTO"] helpviewer_keywords: ["C26438"] ms.assetid: c7b3f59c-fb2f-4816-bda4-0fad23c80d83 - --- -# C26438 NO_GOTO +# Warning C26438 -"Avoid **`goto`**." +> Avoid `goto` (es.76) **C++ Core Guidelines**:\ [ES.76](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es76-avoid-goto): Avoid goto @@ -19,9 +17,11 @@ The use of **`goto`** is widely considered a dangerous and error-prone practice. ## Remarks -- This rule warns on any occurrence of **`goto`**, even if it happens in dead code, except template code that's never used and consequently ignored by compiler. +- This rule warns on any occurrence of **`goto`**, even if it happens in dead code, except template code that's never used and so is ignored by the compiler. - Warnings can multiply when a macro contains **`goto`**. Current reporting mechanisms point to all instances where such a macro gets expanded. It can often be fixed in one place by changing the macro, or avoiding its use in favor of more maintainable mechanisms. +Code analysis name: `NO_GOTO` + ## Example 'goto clean-up' in macro @@ -47,7 +47,7 @@ end: } ``` -'goto clean-up' in macro - replaced with gsl::finally +'goto clean-up' in macro, replaced with `gsl::finally` ```cpp void poll(connection &c) diff --git a/docs/code-quality/c26439.md b/docs/code-quality/c26439.md index b68822de7f..85e7499a1e 100644 --- a/docs/code-quality/c26439.md +++ b/docs/code-quality/c26439.md @@ -1,39 +1,40 @@ --- -title: C26439 -ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26439"] -helpviewer_keywords: ["C26439"] -ms.assetid: 9df2a1b0-ea94-4884-9d28-c1522ec33a1b +title: Warning C26439 description: CppCoreCheck rule C26439 that enforces C++ Core Guidelines F.6 +ms.date: 05/17/2023 +f1_keywords: ["C26439", "SPECIAL_NOEXCEPT"] +helpviewer_keywords: ["C26439"] --- -# C26439 SPECIAL_NOEXCEPT +# Warning C26439 + +> This kind of function may not throw. Declare it 'noexcept'. + +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f6-if-your-function-must-not-throw-declare-it-noexcept) -"This kind of function may not throw. Declare it 'noexcept'." +Some operations should never throw exceptions. Their implementations should be reliable and should handle possible errors conditions gracefully. They shouldn't use exceptions to indicate failure. This rule flags cases where such operations aren't explicitly marked as `noexcept`, which means that they may throw exceptions and consumers can't make assumptions about its reliability. -[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept +It's important for these functions to be reliable as they're often used as building blocks to implement functions with [exception safety guarantees](https://en.cppreference.com/w/cpp/language/exceptions). A move constructor that throws will force Standard Template Library (STL) containers to fall back to copy operations, reducing runtime performance. -Some kinds of operations should never cause exceptions. Their implementations should be reliable and should handle possible errors conditions gracefully. They should never use exceptions to indicate failure. This rule flags cases where such operations are not explicitly marked as 'noexcept' which means that they may throw exceptions and cannot convey assumptions about their reliability. +Code analysis name: `SPECIAL_NOEXCEPT` ## Remarks -- Special kinds of operations are the following: +- Special kinds of operations: - destructors; - - default constructors; - move constructors and move assignment operators; - - standard functions with move semantics: std::move and std::swap. -- Non-standard and outdated specifiers like throw() or declspec(nothrow) are not equivalent to 'noexcept'. -- Explicit specifiers noexcept(false) and noexcept(true) are respected appropriately. -- The warning may still appear for operations that are marked as constexpr. This may change in future releases. + - standard functions with move semantics: `std::move` and `std::swap`. + +- Nonstandard and outdated specifiers like `throw()` or `declspec(nothrow)` aren't equivalent to `noexcept`. + +- Explicit specifiers `noexcept(false)` and `noexcept(true)` are respected appropriately. ## Example -All functions except the destructor will warn because they are missing noexcept. +The tool warns on all functions except the destructor because they're missing `noexcept`. ```cpp struct S { - S() {} // C26455, Default constructor may not throw. Declare it 'noexcept' ~S() {} S(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6) @@ -44,12 +45,11 @@ struct S }; ``` -With noexcept decorating the same structure, all warnings are removed. +With `noexcept` decorating the same structure, all warnings are removed. ```cpp struct S { - S() noexcept {} ~S() {} S(S&& s) noexcept {/*impl*/} @@ -59,3 +59,8 @@ struct S S& operator=(const S& s) noexcept {/*impl*/} }; ``` + +## See also + +[C26455](c26455.md)\ +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f6-if-your-function-must-not-throw-declare-it-noexcept) diff --git a/docs/code-quality/c26440.md b/docs/code-quality/c26440.md index df691de7f1..edeb1db827 100644 --- a/docs/code-quality/c26440.md +++ b/docs/code-quality/c26440.md @@ -1,34 +1,33 @@ --- -title: C26440 +title: Warning C26440 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26440"] +f1_keywords: ["C26440", "DECLARE_NOEXCEPT"] helpviewer_keywords: ["C26440"] ms.assetid: b6d2b188-35cc-4de2-878c-6f97d5a2444a description: CppCoreCheck rule C26440 that enforces C++ Core Guidelines F.6 --- -# C26440 DECLARE_NOEXCEPT +# Warning C26440 -"Function can be declared 'noexcept'." +> Function can be declared 'noexcept'. -[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept +[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it `noexcept` -If code is not supposed to cause any exceptions, it should be marked as such by using the 'noexcept' specifier. This would help to simplify error handling on the client code side, as well as enable compiler to do additional optimizations. +If code isn't supposed to cause any exceptions, it should be marked by using the `noexcept` specifier. This annotation helps to simplify error handling on the client code side, and enables the compiler to do more optimizations. ## Remarks - A function is considered non-throwing if: - - it has no explicit throw statements; - - function calls in its body, if any, invoke only functions that unlikely to throw: constexpr or functions marked with any exception specification which entails non-throwing behavior (this includes some non-standard specifications). -- Non-standard and outdated specifiers like throw() or declspec(nothrow) are not equivalent to 'noexcept'. -- Explicit specifiers noexcept(false) and noexcept(true) are respected appropriately. -- Functions marked as constexpr are not supposed to cause exceptions and are not analyzed. + - it has no explicit `throw` statements; + - function calls in its body, if any, invoke only functions that are unlikely to throw: `constexpr` or functions marked with any exception specification that entails non-throwing behavior (including some non-standard specifications). +- Non-standard and outdated specifiers like `throw()` or `__declspec(nothrow)` aren't equivalent to `noexcept`. +- Explicit specifiers `noexcept(false)` and `noexcept(true)` are respected appropriately. +- Functions marked as `constexpr` aren't supposed to cause exceptions and aren't analyzed. - The rule also applies to lambda expressions. -- The logic doesn't consider recursive calls as potentially non-throwing. This may change in the future. +- The logic doesn't consider recursive calls as potentially non-throwing. This logic may change in the future. ## Example -All functions except the destructor will warn because they are missing noexcept. +All functions except the destructor will warn because they're missing noexcept. ```cpp struct S diff --git a/docs/code-quality/c26441.md b/docs/code-quality/c26441.md index 9acc844920..c2f5dc91b8 100644 --- a/docs/code-quality/c26441.md +++ b/docs/code-quality/c26441.md @@ -1,57 +1,68 @@ --- -description: "Learn more about: C26441 NO_UNNAMED_GUARDS" -title: C26441 -ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26441"] +title: Warning C26441 +description: "Learn more about: Warning C26441 NO_UNNAMED_GUARDS." +ms.date: 5/11/2023 +f1_keywords: ["C26441", "NO_UNNAMED_GUARDS"] helpviewer_keywords: ["C26441"] -ms.assetid: f923c422-ed01-4644-b40b-93f15fc5bb93 - --- -# C26441 NO_UNNAMED_GUARDS +# Warning C26441 -"Guard objects must be named." +> Guard objects must be named (cp.44) -**C++ Core Guidelines**: -[CP.44](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#cp44-remember-to-name-your-lock_guards-and-unique_locks): Remember to name your lock_guards and unique_locks +## C++ Core Guidelines -The standard library provides a few useful classes which help to control concurrent access to resources. Objects of such types lock exclusive access for the duration of their lifetime. This implies that every lock object must be named, i.e. have clearly defined lifetime which spans through the period in which access operations are executed. So, failing to assign a lock object to a variable is a mistake which is effectively disables locking mechanism (because temporary variables are transient). This rule tries to catch simple cases of such unintended behavior. +[CP.44: Remember to name your `lock_guard`s and `unique_lock`s](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#cp44-remember-to-name-your-lock_guards-and-unique_locks) ## Remarks -- Only standard lock types are tracked: std::scoped_lock, std::unique_lock, and std::lock_quard. - - Only simple calls to constructors are analyzed. More complex initializer expression may lead to inaccurate results, but this is rather an unusual scenario. - - Locks passed as arguments to function calls or returned as results of function calls are ignored. - - Locks created as temporaries but assigned to named references to extend their lifetime are ignored. +The standard library provides locks to help control concurrent access to resources during their lifetime. When you declare a lock object without a name, the compiler creates a temporary object that's immediately destructed rather than one that lives to the end of the enclosing scope. So, failure to assign a lock object to a variable is a mistake that effectively disables the locking mechanism (because temporary variables are transient). This rule catches simple cases of such unintended behavior. + +This diagnostic only analyzes the standard lock types `std::scoped_lock`, `std::unique_lock`, and `std::lock_guard`. Warning [C26444](c26444.md) covers other unnamed RAII types. + +The analyzer only analyzes simple calls to constructors. More complex initializer expressions may lead to inaccurate results in the form of missed warnings. The analyzer ignores locks passed as arguments to function calls or returned from function calls. It's unable to determine if those locks are deliberately trying to protect that function call or if their [lifetime should be extended](https://abseil.io/tips/107). To provide similar protection for types returned by a function call, annotate them with `[[nodiscard]]`. You can also annotate constructors with `[[nodiscard]]` to avoid unnamed objects of that type: + +```cpp +struct X { [[nodiscard]] X(); }; + +void f() { + X{}; // warning C4834 +} +``` + + The analyzer ignores locks created as temporaries but assigned to named references to extend their lifetime. + +Code analysis name: `NO_UNNAMED_GUARDS` ## Example -missing scoped variable +In this example, the name of the scoped lock is missing. ```cpp -void print_diagnostic(gsl::string_span<> text) +void print_diagnostic(std::string_view text) { auto stream = get_diagnostic_stream(); if (stream) { std::lock_guard{ diagnostic_mutex_ }; // C26441 write_line(stream, text); - // ... } } ``` -missing scoped variable - corrected +To fix the error, give a name to the lock, which extends its lifetime. ```cpp -void print_diagnostic(gsl::string_span<> text) +void print_diagnostic(std::string_view text) { auto stream = get_diagnostic_stream(); if (stream) { std::lock_guard lock{ diagnostic_mutex_ }; write_line(stream, text); - // ... } } ``` + +## See also + +[C26444](C26444.md) diff --git a/docs/code-quality/c26443.md b/docs/code-quality/c26443.md index 9538b58553..090995ebda 100644 --- a/docs/code-quality/c26443.md +++ b/docs/code-quality/c26443.md @@ -1,17 +1,13 @@ --- -title: C26443 -keywords: C26443 +title: Warning C26443 ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26443"] +f1_keywords: ["C26443", "NO_EXPLICIT_DTOR_OVERRIDE"] helpviewer_keywords: ["C26443"] -dev_langs: ["C++"] -description: Rule concerning overriding destructors +description: Warning C26443 Rule concerning overriding destructors --- +# Warning C26443 -# C26443 NO_EXPLICIT_DTOR_OVERRIDE - -"Overriding destructor should not use explicit 'override' or 'virtual' specifiers." +> Overriding destructor should not use explicit 'override' or 'virtual' specifiers. This warning was removed in Visual Studio 16.8 to reflect [changes to C.128 in the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/pull/1448). @@ -27,6 +23,8 @@ The current consensus on the Core Guidelines is to exclude destructors from the - Destructors can still use the 'final' specifier because of its special semantics. - Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still appropriate. +Code analysis name: `NO_EXPLICIT_DTOR_OVERRIDE` + ## Example: Explicit 'override' ```cpp diff --git a/docs/code-quality/c26444.md b/docs/code-quality/c26444.md index 883d9547a6..cc020442fe 100644 --- a/docs/code-quality/c26444.md +++ b/docs/code-quality/c26444.md @@ -1,54 +1,49 @@ --- -description: "Learn more about: C26444 NO_UNNAMED_RAII_OBJECTS" -title: C26444 -keywords: C26444 -ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26444"] +title: Warning C26444 +description: "Learn more about: Warning C26444 NO_UNNAMED_RAII_OBJECTS." +ms.date: 05/11/2023 +f1_keywords: ["C26444", "NO_UNNAMED_RAII_OBJECTS"] helpviewer_keywords: ["C26444"] -dev_langs: ["C++"] --- -# C26444 NO_UNNAMED_RAII_OBJECTS +# Warning C26444 -Avoid unnamed objects with custom construction and destruction. +> Don't try to declare a local variable with no name (es.84). ## C++ Core Guidelines -[ES.84: Don't (try to) declare a local variable with no name](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-noname) +[ES.84: Don't try to declare a local variable with no name](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es84-dont-try-to-declare-a-local-variable-with-no-name) -Unnamed (that is, temporary) objects with non-trivial behavior may point to either (a) inefficient code that allocates and immediately throws away resources or (b) to the code that unintentionally ignores non-primitive data. Sometimes it may also indicate plainly wrong declaration. +An unnamed variable declaration creates a temporary object that is discarded at the end of the statement. Such temporary objects with nontrivial behavior may point to either inefficient code that allocates and immediately throws away resources or to the code that unintentionally ignores nonprimitive data. Sometimes it may also indicate plainly wrong declaration. -## Notes +## Remarks -- This rule detects types with non-deleted destructors. Keep in mind that destructors can be compiler generated. -- The warning can flag code that is not compiler generated and that invokes either a non-default constructor of a RAII type or a function that returns an object of such type. This warning helps to detect ignored call results in addition to wrong declarations. -- The logic skips temporaries if they are used in higher-level expressions. One example is temporaries that are passed as arguments or used to invoke a function. -- The standard library implementation may have different versions of destruction logic for some types (for example, containers). This can produce noisy warnings on debug builds because it is customary to ignore iterators returned from calls like [std::vector::insert](../standard-library/vector-class.md#insert). While such warnings are not actionable in the majority of cases, they are legitimate in pointing to the place where some non-obvious work is done in temporary objects. +- This rule detects types with a hand-written destructor or a compiler-generated destructor that transitively calls a hand-written destructor. +- This rule can flag code that invokes a nontrivial constructor of an RAII type. +- The logic skips temporaries if they're used in higher-level expressions. One example is temporaries that are passed as arguments or used to invoke a function. -## Example: Ignored call result +Code analysis name: `NO_UNNAMED_RAII_OBJECTS` + +## Examples ```cpp -std::string ToTraceMessage(State &state); -void SaveState(State &state) +struct A { A(int i); ~A(); }; +void Foo() { - // ... - ToTraceMessage(state); // C26444, should we do something with the result of this call? + A{42}; // warning C26444: Don't try to declare a local variable with no name (es.84). } +``` -Example: Ignored call result - fixed. -std::cerr << ToTraceMessage(state); +To fix the issue, convert the temporary object to a local. -Example: Unexpected lifetime. -void SplitCache() +```cpp +struct A { A(int i); ~A(); }; +void Foo() { - gsl::finally([] { RestoreCache(); }); // C26444, RestoreCache is invoked immediately! - //... + A guard{42}; // OK. } - -Example: Unexpected lifetime - fixed. -const auto _ = gsl::finally([] { RestoreCache(); }); ``` ## See also -[ES.84: Don't (try to) declare a local variable with no name](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C26441](C26441.md)\ +[ES.84: Don't try to declare a local variable with no name](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es84-dont-try-to-declare-a-local-variable-with-no-name) diff --git a/docs/code-quality/c26445.md b/docs/code-quality/c26445.md index 1ba9d9c2fe..2602c8bfa5 100644 --- a/docs/code-quality/c26445.md +++ b/docs/code-quality/c26445.md @@ -1,12 +1,13 @@ --- -description: "Learn more about: C26445 NO_SPAN_REF" -title: C26445 +description: "Learn more about: Warning C26445 NO_SPAN_REF" +title: Warning C26445 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26445"] +f1_keywords: ["C26445", "NO_SPAN_REF"] helpviewer_keywords: ["C26445"] --- -# C26445 NO_SPAN_REF +# Warning C26445 + +> Do not assign `gsl::span` or `std::string_view` to a reference. They are cheap to construct and are not owners of the underlying data. (gsl.view) A reference to `gsl::span` or `std::string_view` may be an indication of a lifetime issue. @@ -14,7 +15,7 @@ A reference to `gsl::span` or `std::string_view` may be an indication of a lifet [GSL.view: Views](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views) -This rule catches subtle lifetime issues that may occur in code migrated from standard containers to new span and view types. Such types can be considered as "references to buffers." Using a reference to a span or view creates an additional layer of indirection. Such indirection is often unnecessary and can be confusing for maintainers. Spans are cheap to copy and can be returned by value from function calls. Obviously, such call results should never be referenced. +This rule catches subtle lifetime issues that may occur in code migrated from standard containers to new span and view types. Such types can be considered as "references to buffers." Using a reference to a span or view creates an extra layer of indirection. Such indirection is often unnecessary and can be confusing for maintainers. Spans are cheap to copy and can be returned by value from function calls. Obviously, such call results should never be referenced. ## Remarks @@ -22,13 +23,17 @@ This rule catches subtle lifetime issues that may occur in code migrated from st - Currently warnings are emitted only on declarations and return statements. This rule may be extended in future to also flag function parameters. - The implementation of this rule is lightweight doesn't attempt to trace actual lifetimes. Using of references may still make sense in some scenarios. In such cases, false positives can safely be suppressed. -## Example: Reference to a temporary +Code analysis name: `NO_SPAN_REF` + +## Example + +Reference to a temporary: ```cpp // Old API - uses string reference to avoid data copy. const std::string& get_working_directory() noexcept; -// New API – after migration to C++17 it uses string view. +// New API - after migration to C++17 it uses string view. std::string_view get_working_directory() noexcept; // ... diff --git a/docs/code-quality/c26446.md b/docs/code-quality/c26446.md index e78fef3e36..39091ddfde 100644 --- a/docs/code-quality/c26446.md +++ b/docs/code-quality/c26446.md @@ -1,14 +1,13 @@ --- -title: C26446 +title: Warning C26446 description: "Microsoft C++ Code Analysis warning C26446 for the C++ Core Guidelines case Bounds.4." ms.date: 08/21/2010 -ms.topic: reference -f1_keywords: ["C26446"] +f1_keywords: ["C26446", "USE_GSL_AT"] helpviewer_keywords: ["C26446"] --- -# C26446 USE_GSL_AT +# Warning C26446 -> `Prefer to use gsl::at() instead of unchecked subscript operator (bounds.4).` +> Prefer to use gsl::at() instead of unchecked subscript operator (bounds.4). C++ Core Guidelines: [Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile). @@ -21,11 +20,11 @@ This rule helps to find places where potentially unchecked access is performed v - Access to arrays of known size is flagged when a non-constant index is used in a subscript operator. Constant indices are handled by [C26483 STATIC_INDEX_OUT_OF_RANGE](c26483.md). - The logic to warn on overloaded `operator[]` calls is more complex: - If the index is non-integral, the call is ignored. This also handles indexing in standard maps, since parameters in such operators are passed by reference. - - If the operator is marked as non-throwing (by using **`noexcept`**, **`throw()`**, or **`__declspec(nothrow)`**), the call is flagged. We assume that if the subscript operator never throws exceptions, it either doesn’t perform range checks or these checks are obscure. + - If the operator is marked as non-throwing (by using **`noexcept`**, **`throw()`**, or **`__declspec(nothrow)`**), the call is flagged. We assume that if the subscript operator never throws exceptions, it either doesn't perform range checks or these checks are obscure. - If the operator isn't marked as non-throwing, it may be flagged if it comes from an STL container that also defines a conventional `at()` member function. Such functions are detected by simple name matching. - - The rule doesn’t warn on calls to standard `at()` functions. These functions are safe; replacing them with `gsl::at()` wouldn't bring much value. + - The rule doesn't warn on calls to standard `at()` functions. These functions are safe; replacing them with `gsl::at()` wouldn't bring much value. - Indexing into `std::basic_string_view<>` is unsafe, so a warning is issued. Replace the standard `string_view` by using `gsl::basic_string_span<>`, which is always bounds-checked. -- The implementation doesn’t consider range checks that user code may have somewhere in loops or branches. Accuracy here is traded for performance. In general, you can often replace explicit range checks by using more reliable iterators or more concise enhanced **`for`**-loops. +- The implementation doesn't consider range checks that user code may have somewhere in loops or branches. Here, accuracy is traded for performance. In general, you can often replace explicit range checks by using more reliable iterators or more concise enhanced **`for`**-loops. ## Example diff --git a/docs/code-quality/c26447.md b/docs/code-quality/c26447.md index 7595b29a59..8c4c2ef820 100644 --- a/docs/code-quality/c26447.md +++ b/docs/code-quality/c26447.md @@ -1,12 +1,11 @@ --- -title: C26447 +title: Warning C26447 description: "Microsoft C++ Code Analysis warning C26447 for the C++ Core Guidelines case F.6." ms.date: 08/25/2020 -ms.topic: reference -f1_keywords: ["C26447"] +f1_keywords: ["C26447", "DONT_THROW_IN_NOEXCEPT"] helpviewer_keywords: ["C26447"] --- -# C26447 DONT_THROW_IN_NOEXCEPT +# Warning C26447 > The function is declared `noexcept` but calls function *function_name* that may throw exceptions (f.6). @@ -19,7 +18,7 @@ This rule amends another rule, [C26440 DECLARE_NOEXCEPT](c26440.md), which tries - The Microsoft C++ compiler already handles straightforward violations like **`throw`** statements in the function body (see [C4297](../error-messages/compiler-warnings/compiler-warning-level-1-c4297.md)). - The rule focuses only on function calls. It flags targets that aren't **`constexpr`** and that can potentially throw exceptions. In other words, they aren't marked explicitly as non-throwing by using **`noexcept`**, **`__declspec(nothrow)`**, or **throw()**. -- The compiler-generated target functions are skipped to reduce noise since exception specifications are not always provided by the compiler. +- The compiler-generated target functions are skipped to reduce noise since exception specifications aren't always provided by the compiler. - The checker also skips special kinds of target functions we expect you to implement as **`noexcept`**; this rule is enforced by [C26439 SPECIAL_NOEXCEPT](c26439.md). ## Example diff --git a/docs/code-quality/c26448.md b/docs/code-quality/c26448.md index 7b75d26211..6173ec82b5 100644 --- a/docs/code-quality/c26448.md +++ b/docs/code-quality/c26448.md @@ -1,29 +1,32 @@ --- -description: "Learn more about: C26448 USE_GSL_FINALLY" -title: C26448 +description: "Learn more about: Warning C26448 USE_GSL_FINALLY" +title: Warning C26448 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26448"] +f1_keywords: ["C26448", "USE_GSL_FINALLY"] helpviewer_keywords: ["C26448"] --- -# C26448 USE_GSL_FINALLY +# Warning C26448 -Consider using `gsl::finally` if final action is intended. +> Consider using `gsl::finally` if final action is intended (gsl.util) C++ Core Guidelines: [GSL.util: Utilities](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-utilities) The Guidelines Support Library provides a convenient utility to implement the *final action* concept. Since the C++ language doesn't support **try-finally** constructs, it became common to implement custom cleanup types that would invoke arbitrary actions on destruction. The `gsl::finally` utility is implemented in this way and provides a more uniform way to perform final actions across a code base. -There are also cases where final actions are performed in an old-fashioned C-style way by using **`goto`** statements (which is generally discouraged by [C26438 NO_GOTO](c26438.md)). It is hard to detect the exact intention in code that heavily uses **`goto`**, but some heuristics can help to find better candidates for cleanup. +There are also cases where final actions are performed in an old-fashioned C-style way by using **`goto`** statements (which is discouraged by [C26438 NO_GOTO](c26438.md)). It's hard to detect the exact intention in code that heavily uses **`goto`**, but some heuristics can help to find better candidates for cleanup. ## Remarks -- This rule is very lightweight and uses label names to guess about opportunities to use final action objects. +- This rule is lightweight and uses label names to guess about opportunities to use final action objects. - Label names that can raise a warning contain words like "end", "final", "clean", and so on. -- Warnings appear at the **`goto`** statements. You may see verbose output on some occasions, but this may help in prioritizing code depending on its complexity. -- This rule always goes in pair with [C26438 NO_GOTO](c26438.md). Depending on the priorities, one of these can be disabled. +- Warnings appear at the **`goto`** statements. You may see verbose output on some occasions, but the output may help in prioritizing code, depending on its complexity. +- This rule always goes in pair with [C26438 NO_GOTO](c26438.md). Depending on the priorities, one of these rules can be disabled. -## Example: Cleanup with multiple goto statements +Code analysis name: `USE_GSL_FINALLY` + +## Example + +Cleanup with multiple goto statements: ```cpp void poll(connection_info info) @@ -48,7 +51,7 @@ end: } ``` -## Example: Cleanup with multiple goto statements replaced by gsl::finally +Cleanup with multiple goto statements replaced by `gsl::finally`: ```cpp void poll(connection_info info) diff --git a/docs/code-quality/c26449.md b/docs/code-quality/c26449.md index 002d926f47..85de9ef0c3 100644 --- a/docs/code-quality/c26449.md +++ b/docs/code-quality/c26449.md @@ -1,38 +1,46 @@ --- -description: "Learn more about: C26449 NO_SPAN_FROM_TEMPORARY" -title: C26449 -ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26449"] +title: Warning C26449 +description: "Learn more about: Warning C26449 NO_SPAN_FROM_TEMPORARY." +ms.date: 05/11/2023 +f1_keywords: ["C26449", "NO_SPAN_FROM_TEMPORARY"] helpviewer_keywords: ["C26449"] --- -# C26449 NO_SPAN_FROM_TEMPORARY +# Warning C26449 -`gsl::span` or `std::string_view` created from a temporary will be invalid when the temporary is invalidated. +> `gsl::span` or `std::string_view` created from a temporary will be invalid when the temporary is invalidated (gsl.view) -C++ Core Guidelines: [GSL.view: Views](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views). +C++ Core Guidelines: [GSL.view: Views](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#gslview-views). -Spans and views are convenient and lightweight types that allow to reference memory buffers. But they must be used carefully: while their interface looks similar to standard containers, their behavior is more like the behavior of pointers and references. They do not own data and must never be constructed from temporary buffers. This check focuses on cases where source data is temporary, while span or view is not. There is another check which handles slightly different scenario involving span references: [C26445 NO_SPAN_REF](c26445.md). Both rules can help to avoid subtle but dangerous mistakes made when legacy code gets modernized and adopts spans or views. +Spans and views are convenient and lightweight types that allow you to reference memory buffers. But they must be used carefully: while their interface looks similar to standard containers, their behavior is more like the behavior of pointers and references. They don't own data and must never be constructed from temporary buffers. This check focuses on cases where source data is temporary, while a span or view isn't. This rule can help to avoid subtle but dangerous mistakes made when legacy code gets modernized and adopts spans or views. There's another check that handles a slightly different scenario involving span references: [C26445 NO_SPAN_REF](c26445.md). + +Consider using [C26815](c26815.md) and [C26816](c26816.md). Those warnings are more general versions of this warning. ## Remarks -- This rule warns on places where constructors get invoked for spans or views and the source data buffer belongs to a temporary object created in the same statement. This includes: +- This rule warns on places where constructors get invoked for spans or views and the source data buffer belongs to a temporary object created in the same statement. This check includes: - implicit conversions in return statements; - implicit conversions in ternary operators; - explicit conversions in `static_cast` expressions; - function calls that return containers by value. -- Temporaries created for function call arguments are not flagged. It is safe to pass spans from such temporaries if target functions don’t retain data pointers in external variables. + +- Temporaries created for function call arguments aren't flagged. It's safe to pass spans from such temporaries if target functions don't retain data pointers in external variables. + - If spans or views are themselves temporaries, the rule skips them. + - Data tracking in the checker has certain limitations; therefore complex scenarios involving multiple or obscure reassignments may not be handled. -## Example: Subtle difference in result types +Code analysis name: `NO_SPAN_FROM_TEMPORARY` + +## Example + +Subtle difference in result types: ```cpp // Returns a predefined collection. Keeps data alive. gsl::span get_seed_sequence() noexcept; -// Returns a generated collection. Doesn’t own new data. -const std::vector get_next_sequence(gsl::span); +// Returns a generated collection. Doesn't own new data. +std::vector get_next_sequence(gsl::span); void run_batch() { @@ -44,3 +52,9 @@ void run_batch() } } ``` + +To fix the issue, make sure the view is created from an object that lives at least as long as the view itself. Sometimes a solution can be achieved by copying the data, other times some APIs need to be redesigned to share a reference to an object that lives long enough instead of returning a temporary copy. + +## See also +[C26815](c26815.md)\ +[C26816](c26816.md) \ No newline at end of file diff --git a/docs/code-quality/c26450.md b/docs/code-quality/c26450.md index 6a6b26bf5b..66044efb23 100644 --- a/docs/code-quality/c26450.md +++ b/docs/code-quality/c26450.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Arithmetic overflow: '%operator%' operation causes overflow at compile time. Use a wider type to store the operands" -title: C26450 -keywords: C26450 -ms.date: 01/08/2017 -ms.topic: "reference" -f1_keywords: ["C26450"] +title: Warning C26450 +description: "Describes the causes of MSVC code analysis warning C26450 and how to fix it." +ms.date: 05/11/2023 +f1_keywords: ["C26450", "RESULT_OF_ARITHMETIC_OPERATION_PROVABLY_LOSSY"] helpviewer_keywords: ["C26450"] -dev_langs: ["C++"] --- -# Arithmetic overflow: '%operator%' operation causes overflow at compile time. Use a wider type to store the operands +# Warning C26450 -This warning indicates that an arithmetic operation was provably lossy at compile time. This can be asserted when the operands are all compile-time constants. Currently, we check left shift, multiplication, addition, and subtraction operations for such overflows. +> Arithmetic overflow: '*operator*' operation causes overflow at compile time. Use a wider type to store the operands (io.1) -Note: C4307 is a similar check in the Microsoft C++ compiler. +## Remarks -## Example 1 +This warning indicates that an arithmetic operation was provably lossy at compile time. It can be asserted when the operands are all compile-time constants. Currently, we check left shift, multiplication, addition, and subtraction operations for such overflows. + +Warning [C4307](../error-messages/compiler-warnings/compiler-warning-level-2-c4307.md) is a similar check in the Microsoft C++ compiler. + +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_PROVABLY_LOSSY` + +## Examples ```cpp int multiply() @@ -33,59 +36,15 @@ long long multiply() { const int a = INT_MAX; const int b = 2; - long long c = (long long)a * b; // OK - return c; -} -``` - -## Example 2 - -```cpp -int add() -{ - const int a = INT_MAX; - const int b = 2; - int c = a + b; // C26450 reported here - return c; -} -``` - -To correct this warning, use the following code: - -```cpp -long long add() -{ - const int a = INT_MAX; - const int b = 2; - long long c = (long long)a + b; // OK - return c; -} -``` - -## Example 3 - -```cpp -int subtract() -{ - const int a = -INT_MAX; - const int b = 2; - int c = a - b; // C26450 reported here - return c; -} -``` - -To correct this warning, use the following code. - -```cpp -long long subtract() -{ - const int a = -INT_MAX; - const int b = 2; - long long c = (long long)a - b; // OK + long long c = static_cast(a) * b; // OK return c; } ``` ## See also -[ES.103: Don't overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow) +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.103: Don't overflow](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es103-dont-overflow) diff --git a/docs/code-quality/c26451.md b/docs/code-quality/c26451.md index f925524710..0067e42718 100644 --- a/docs/code-quality/c26451.md +++ b/docs/code-quality/c26451.md @@ -1,15 +1,13 @@ --- -title: C26451 +title: Warning C26451 description: "Describes the causes of MSVC code analysis warning C26451, and shows how to fix it." -ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26451"] +ms.date: 05/11/2023 +f1_keywords: ["C26451", "RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE"] helpviewer_keywords: ["C26451"] -dev_langs: ["C++"] --- # Warning C26451 -> Arithmetic overflow: Using operator '*operator*' on a *size-a* byte value and then casting the result to a *size-b* byte value. Cast the value to the wider type before calling operator '*operator*' to avoid overflow +> Arithmetic overflow: Using operator '*operator*' on a *size-a* byte value and then casting the result to a *size-b* byte value. Cast the value to the wider type before calling operator '*operator*' to avoid overflow (io.2) This warning indicates incorrect behavior that results from integral promotion rules and types larger than the ones in which arithmetic is typically performed. @@ -17,14 +15,16 @@ This warning indicates incorrect behavior that results from integral promotion r Code analysis detects when an integral value gets shifted left, multiplied, added, or subtracted, and the result gets cast to a wider integral type. If the operation overflows the narrower integral type, then data is lost. You can prevent this loss by casting the value to a wider type before the arithmetic operation. -## Example 1 +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE` + +## Examples The following code generates this warning: ```cpp void leftshift(int i) noexcept { - unsigned __int64 x; + unsigned long long x; x = i << 31; // C26451 reported here // code @@ -36,55 +36,17 @@ To correct this warning, use the following code: ```cpp void leftshift(int i) noexcept { - unsigned __int64 x; - x = static_cast(i) << 31; // OK + unsigned long long x; + x = static_cast(i) << 31; // OK // code } ``` -## Example 2 - -```cpp -void somefunc(__int64 /* y */) noexcept -{} - -void callsomefunc(int x) noexcept -{ - somefunc(x * 2); // C26451 reported here -} -``` - -To correct this warning, use the following code: - -```cpp -void callsomefunc(int x) noexcept -{ - somefunc(static_cast<__int64>(x) * 2); // OK -} -``` - -## Example 3 - -```cpp -__int64 add(int x) noexcept -{ - constexpr auto value = 2; - return x += value; // C26451 reported here -} -``` - -To correct this warning, use the following code: - -```cpp -__int64 add(int x) noexcept -{ - constexpr auto value = 2; - const __int64 y = static_cast<__int64>(x) + value; // OK - return y; -} -``` - ## See also -- [ES.103: Don't overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow) +[C26450](c26450.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.103: Don't overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow) diff --git a/docs/code-quality/c26452.md b/docs/code-quality/c26452.md index bccb98e203..0f529f60ce 100644 --- a/docs/code-quality/c26452.md +++ b/docs/code-quality/c26452.md @@ -1,23 +1,26 @@ --- -title: C26452 +title: Warning C26452 description: "Describes causes of MSVC Code analysis warning C26452, and how to fix the issue." ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26452"] +f1_keywords: ["C26452", "SHIFT_COUNT_NEGATIVE_OR_TOO_BIG"] helpviewer_keywords: ["C26452"] -dev_langs: ["C++"] --- # Warning C26452 -> Arithmetic overflow: Left shift count is negative or greater than or equal to the operand size, which is undefined behavior +> Arithmetic overflow: Left shift count is negative or greater than or equal to the operand size, which is undefined behavior (io.3) + +## Remarks This warning indicates the shift count is negative, or greater than or equal to the number of bits in the shifted operand. Either case results in undefined behavior. -C4293 is a similar check in the Microsoft C++ compiler. + +Warning [C4293](../error-messages/compiler-warnings/compiler-warning-level-1-c4293.md) is a similar check in the Microsoft C++ compiler. + +Code analysis name: `SHIFT_COUNT_NEGATIVE_OR_TOO_BIG` ## Example ```cpp -unsigned __int64 combine(unsigned lo, unsigned hi) +unsigned long long combine(unsigned lo, unsigned hi) { return (hi << 32) | lo; // C26252 here } @@ -26,7 +29,7 @@ unsigned __int64 combine(unsigned lo, unsigned hi) To correct this warning, use the following code: ```cpp -unsigned __int64 combine(unsigned lo, unsigned hi) +unsigned long long combine(unsigned lo, unsigned hi) { return (static_cast(hi) << 32) | lo; // OK } @@ -34,4 +37,9 @@ unsigned __int64 combine(unsigned lo, unsigned hi) ## See also -[ES.102: Use signed types for arithmetic](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-unsigned) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.101: Use unsigned types for bit manipulation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es101-use-unsigned-types-for-bit-manipulation)\ +[ES.102: Use signed types for arithmetic](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es102-use-signed-types-for-arithmetic) diff --git a/docs/code-quality/c26453.md b/docs/code-quality/c26453.md index ee2388594f..32a7064209 100644 --- a/docs/code-quality/c26453.md +++ b/docs/code-quality/c26453.md @@ -1,17 +1,19 @@ --- -title: C26453 +title: Warning C26453 description: "Describes the causes of MSVC code analysis warning C26453, and shows how to fix it." -ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26453"] +ms.date: 05/11/2023 +f1_keywords: ["C26453", "LEFTSHIFT_NEGATIVE_SIGNED_NUMBER"] helpviewer_keywords: ["C26453"] -dev_langs: ["C++"] --- # Warning C26453 -> Arithmetic overflow: Left shift of a negative signed number is undefined behavior +> Arithmetic overflow: Left shift of a negative signed number is undefined behavior (io.4) -This warning indicates the code left shifts a negative signed integral value, which is non-portable and triggers implementation defined behavior. +## Remarks + +This warning indicates the code left shifts a negative signed integral value, which is nonportable and triggers implementation defined behavior. + +Code analysis name: `LEFTSHIFT_NEGATIVE_SIGNED_NUMBER` ## Example @@ -29,7 +31,7 @@ To correct this warning, use the following code: ```cpp void leftshift(int shiftCount) { - const auto result = static_cast(-1) << shiftCount; // OK + const auto result = ~0u << shiftCount; // OK // code } @@ -37,4 +39,9 @@ void leftshift(int shiftCount) ## See also -[ES.102: Use signed types for arithmetic](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-unsigned) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26454](c26454.md)\ +[ES.101: Use unsigned types for bit manipulation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es101-use-unsigned-types-for-bit-manipulation)\ +[ES.102: Use signed types for arithmetic](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es102-use-signed-types-for-arithmetic) diff --git a/docs/code-quality/c26454.md b/docs/code-quality/c26454.md index 433e831923..77b21092ec 100644 --- a/docs/code-quality/c26454.md +++ b/docs/code-quality/c26454.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: Arithmetic overflow: '%operator%' operation produces a negative unsigned result at compile time" -title: C26454 -keywords: C26454 +title: Warning C26454 +description: "Learn more about: Arithmetic overflow: 'operator' operation produces a negative unsigned result at compile time" ms.date: 01/08/2017 -ms.topic: "reference" -f1_keywords: ["C26454"] +f1_keywords: ["C26454", "RESULT_OF_ARITHMETIC_OPERATION_NEGATIVE_UNSIGNED"] helpviewer_keywords: ["C26454"] -dev_langs: ["C++"] --- -# Arithmetic overflow: '%operator%' operation produces a negative unsigned result at compile time +# Warning C26454 - This warning indicates that the subtraction operation produces a negative result which was evaluated in an unsigned context. This can result in unintended overflows. +> Arithmetic overflow: '*operator*' operation produces a negative unsigned result at compile time + +## Remarks + +This warning indicates that the subtraction operation produces a negative result that was evaluated in an unsigned context, which can result in unintended overflows. + +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_NEGATIVE_UNSIGNED` ## Example @@ -34,4 +37,8 @@ unsigned int negativeunsigned() ## See also -[ES.106: Don't try to avoid negative values by using unsigned](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nonnegative) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[ES.106: Don't try to avoid negative values by using `unsigned`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es106-dont-try-to-avoid-negative-values-by-using-unsigned) diff --git a/docs/code-quality/c26455.md b/docs/code-quality/c26455.md index 113e42efc9..617f0cedd5 100644 --- a/docs/code-quality/c26455.md +++ b/docs/code-quality/c26455.md @@ -1,22 +1,26 @@ --- -description: "Learn more about: C26455 DEFAULT_CTOR_NOEXCEPT" -title: C26455 -ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26455"] +title: Warning C26455 +description: "Learn more about the C26455 DEFAULT_CTOR_NOEXCEPT" +ms.date: 04/29/2022 +f1_keywords: ["C26455", "DEFAULT_CTOR_NOEXCEPT"] helpviewer_keywords: ["C26455"] -ms.assetid: 27e86063-d969-49d8-8912-dcc2dc57249f author: kylereedmsft ms.author: kylereed +ms.custom: kr2b-contr-experiment --- -# C26455 DEFAULT_CTOR_NOEXCEPT +# Warning C26455 -The C++ Core Guidelines suggest that default constructors shouldn't do anything that can throw. If the default constructor is allowed to throw, operations such as move and swap will also throw which is undesirable because move and swap should always succeed. Parameterized constructors may throw. +> Default constructor should not throw. Declare it '`noexcept`' (f.6) + +The C++ Core Guidelines suggest that default constructors shouldn't do anything that can throw. When the default constructor can throw, all code that relies on a properly instantiated object may also throw. ## Remarks Consider the default constructors of the STL types, like `std::vector`. In these implementations, the default constructors initialize internal state without making allocations. In the `std::vector` case, the size is set to 0 and the internal pointer is set to `nullptr`. The same pattern should be followed for all default constructors. +Code analysis name: `DEFAULT_CTOR_NOEXCEPT` + ## See also -- [C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-noexcept) +[C26439](./c26439.md)\ +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f6-if-your-function-must-not-throw-declare-it-noexcept) diff --git a/docs/code-quality/c26456.md b/docs/code-quality/c26456.md index bcca57a746..0abedce51b 100644 --- a/docs/code-quality/c26456.md +++ b/docs/code-quality/c26456.md @@ -1,16 +1,24 @@ --- -description: "Learn more about: C26456 DONT_HIDE_OPERATORS" -title: C26456 -ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26456"] +description: "Learn more about the C26456 DONT_HIDE_OPERATORS C++ Core Guidelines Checker warning. Hiding base methods is error prone and makes code harder to read." +title: Warning C26456 +ms.date: 04/29/2022 +f1_keywords: ["C26456", "DONT_HIDE_OPERATORS"] helpviewer_keywords: ["C26456"] ms.assetid: 3a3ad636-0938-40b5-93ce-169322e2ff23 author: kylereedmsft ms.author: kylereed +ms.custom: kr2b-contr-experiment --- -# C26456 DONT_HIDE_OPERATORS +# Warning C26456 + +> Operator '*symbol_1*' hides a non-virtual operator '*symbol_2*' (c.128) + +## Remarks Hiding base methods that aren't virtual is error prone and makes code harder to read. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c128-virtual-functions-should-specify-exactly-one-of-virtual-override-or-final) +Code analysis name: `DONT_HIDE_OPERATORS` + +## See also + +[C++ Core Guideline c.128](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c128-virtual-functions-should-specify-exactly-one-of-virtual-override-or-final) diff --git a/docs/code-quality/c26457.md b/docs/code-quality/c26457.md index f7fab2b4c2..e1a5560feb 100644 --- a/docs/code-quality/c26457.md +++ b/docs/code-quality/c26457.md @@ -1,17 +1,27 @@ --- -description: "Learn more about: C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST" -title: C26457 +description: "Learn more about: Warning C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST" +title: Warning C26457 ms.date: 3/1/2021 -f1_keywords: ["C26457"] +f1_keywords: ["C26457", "USE_STD_IGNORE_INSTEAD_OF_VOID_CAST"] helpviewer_keywords: ["C26457"] --- -# C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST +# Warning C26457 -Excerpt from the [C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es48-avoid-casts): +> `(void)` should not be used to ignore return values, use '`std::ignore =`' instead (es.48) + +## Remarks + +Excerpt from the [C++ Core Guideline ES.48](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es48-avoid-casts): > Never cast to `(void)` to ignore a `[[nodiscard]]` return value. If you deliberately want to discard such a result, first think hard about whether that is really a good idea (there is usually a good reason the author of the function or of the return type used `[[nodiscard]]` in the first place). If you still think it's appropriate and your code reviewer agrees, use `std::ignore =` to turn off the warning which is simple, portable, and easy to grep. -```C++ +Code analysis name: `USE_STD_IGNORE_INSTEAD_OF_VOID_CAST` + +## Example + +Use `std::ignore` instead of cast to `void`: + +```cpp struct S{}; [[nodiscard]] S getS(); diff --git a/docs/code-quality/c26459.md b/docs/code-quality/c26459.md new file mode 100644 index 0000000000..0bd5855921 --- /dev/null +++ b/docs/code-quality/c26459.md @@ -0,0 +1,43 @@ +--- +description: "Learn more about: Warning C26459" +title: Warning C26459 +ms.date: 4/10/2024 +f1_keywords: ["C26459", "NO_RAW_POINTER_IN_STL_RANGE_CHECKED"] +helpviewer_keywords: ["C26459"] +--- +# Warning C26459 + +> You called an STL function '%function%' with a raw pointer parameter at position '%position%' that may be unsafe - this relies on the caller to check that the passed values are correct. Consider wrapping your range in a gsl::span and pass as a span iterator (stl.1) + +## Remarks + +Out of bound writes are one of the leading causes of remote code execution vulnerabilities. One remedy is to use bounds checked data structures like `gsl::span`. This warning identifies cases where Standard Template Library (STL) algorithms operate on raw pointers as output ranges. Raw pointers aren't bounds checked. To prevent vulnerabilities, use `gsl::span` instead. + +Code analysis name: `NO_RAW_POINTER_IN_STL_RANGE_CHECKED` + +## Example + +The following code demonstrates undefined behavior because there isn't any bounds checking and `copy_if` writes beyond the provided storage. + +```cpp +void f() +{ + std::vector myints = { 10, 20, 30, 40, 50, 60, 70 }; + int mydestinationArr[7] = { 10, 20, 80 }; + + std::copy_if(myints.begin(), myints.end(), mydestinationArr, [](int i) { return !(i<0); }); // Warning: C26459 +} +``` + +To fix the warning, use `gsl::span` to make sure the output range is bounds checked: + +```cpp +void f() +{ + std::vector myints = { 10, 20, 30, 40, 50, 60, 70 }; + int mydestinationArr[7] = { 10, 20, 80 }; + gsl::span mySpan{mydestinationArr}; + + std::copy_if(myints.begin(), myints.end(), mySpan.begin(), [](int i) { return !(i<0); }); // No warning +} +``` \ No newline at end of file diff --git a/docs/code-quality/c26460.md b/docs/code-quality/c26460.md index da0cb686db..2307b0d592 100644 --- a/docs/code-quality/c26460.md +++ b/docs/code-quality/c26460.md @@ -1,20 +1,19 @@ --- -title: C26460 +title: Warning C26460 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26460"] +f1_keywords: ["C26460", "USE_CONST_REFERENCE_ARGUMENTS"] helpviewer_keywords: ["C26460"] description: CppCoreCheck rule that enforces C++ Core Guidelines Con.3 --- -# C26460 USE_CONST_REFERENCE_ARGUMENTS +# Warning C26460 -The reference argument '%argument%' for function '%function%' can be marked as `const` (con.3). +> The reference argument '*argument*' for function '*function*' can be marked as `const` (con.3). -Passing an object by reference indicates that the function has the potential modify the object. If that is not the intent of the function, it is better to mark the argument as a const reference. +## Remarks -## See also +Passing an object by reference indicates that the function has the potential modify the object. If that isn't the intent of the function, it's better to mark the argument as a const reference. -[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +Code analysis name: `USE_CONST_REFERENCE_ARGUMENTS` ## Example @@ -25,7 +24,6 @@ struct MyStruct void MemberFn2(); }; - void Function1_Helper(const MyStruct&); void Function1(MyStruct& myStruct) // C26460, see comments below. { @@ -38,3 +36,7 @@ void Function2(MyStruct& myStruct) myStruct.MemberFn2(); // MemberFn2 is non-const and has the potential to modify data } ``` + +## See also + +[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). diff --git a/docs/code-quality/c26461.md b/docs/code-quality/c26461.md index 72d51e3ec8..85cd180b56 100644 --- a/docs/code-quality/c26461.md +++ b/docs/code-quality/c26461.md @@ -1,20 +1,19 @@ --- -title: C26461 +title: Warning C26461 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26461"] +f1_keywords: ["C26461", "USE_CONST_POINTER_ARGUMENTS"] helpviewer_keywords: ["C26461"] description: CppCoreCheck rule that enforces C++ Core Guidelines con.3 --- -# C26461 USE_CONST_POINTER_ARGUMENTS: +# Warning C26461 -The pointer argument '%argument%' for function '%function%' can be marked as a pointer to `const` (con.3). +> The pointer argument '*argument*' for function '*function*' can be marked as a pointer to `const` (con.3). -A function with a `T*` argument has the potential to modify the value of the object. If that is not the intent of the function, it is better to make the pointer a `const T*` instead. +## Remarks -## See also +A function with a `T*` argument has the potential to modify the value of the object. If that isn't the intent of the function, it's better to make the pointer a `const T*` instead. -[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +Code analysis name: `USE_CONST_POINTER_ARGUMENTS` ## Example @@ -43,3 +42,7 @@ void Function2(MyStruct* myStruct) myStruct->MemberFn2(); // The member function is non-const, so no C26461 will be issued } ``` + +## See also + +[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). diff --git a/docs/code-quality/c26462.md b/docs/code-quality/c26462.md index 9fcc483ff0..f39a230769 100644 --- a/docs/code-quality/c26462.md +++ b/docs/code-quality/c26462.md @@ -1,20 +1,19 @@ --- -title: C26462 +title: Warning C26462 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26462"] +f1_keywords: ["C26462", "USE_CONST_POINTER_FOR_VARIABLE"] helpviewer_keywords: ["C26462"] description: CppCoreCheck rule C26462 that enforces C++ Core Guidelines Con.4 --- -# C26462 USE_CONST_POINTER_FOR_VARIABLE +# Warning C26462 -The value pointed to by '%variable%' is assigned only once, mark it as a pointer to `const` (con.4). +> The value pointed to by '*variable*' is assigned only once, mark it as a pointer to `const` (con.4). -Pointers to variables whose values remain unchanged should be marked as const. +## Remarks -## See also +Pointers to variables whose values remain unchanged should be marked as `const`. -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +Code analysis name: `USE_CONST_POINTER_FOR_VARIABLE` ## Example @@ -29,3 +28,7 @@ void function1(int* ptr) useVal(*p); } ``` + +## See also + +[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). diff --git a/docs/code-quality/c26463.md b/docs/code-quality/c26463.md index 55459cb339..a23cd9d028 100644 --- a/docs/code-quality/c26463.md +++ b/docs/code-quality/c26463.md @@ -1,19 +1,20 @@ --- -title: C26463 +title: Warning C26463 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26463"] +f1_keywords: ["C26463", "USE_CONST_FOR_ELEMENTS"] helpviewer_keywords: ["C26463"] description: CppCoreCheck placeholder warning C26463 for future con.4 enforcement --- -# C26463 USE_CONST_FOR_ELEMENTS +# Warning C26463 -The elements of array '%array%' are assigned only once, mark elements `const` (con.4) +> The elements of array '%array%' are assigned only once, mark elements `const` (con.4) -## See also +## Remarks -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +- This rule is currently not implemented in CppCoreCheck. -## Remark +Code analysis name: `USE_CONST_FOR_ELEMENTS` -- This rule is currently not implemented in CppCoreCheck. +## See also + +[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). diff --git a/docs/code-quality/c26464.md b/docs/code-quality/c26464.md index a280783c5d..c96634aba1 100644 --- a/docs/code-quality/c26464.md +++ b/docs/code-quality/c26464.md @@ -1,19 +1,20 @@ --- -title: C26464 +title: Warning C26464 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26464"] +f1_keywords: ["C26464", "USE_CONST_POINTER_FOR_ELEMENTS"] helpviewer_keywords: ["C26464"] description: CppCoreCheck placeholder warning C26464 for future con.4 enforcement --- -# C26464 USE_CONST_POINTER_FOR_ELEMENTS +# Warning C26464 -The values pointed to by elements of array '%array%' are assigned only once, mark elements as pointer to `const` (con.4). - -## See also - -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +> The values pointed to by elements of array '*array*' are assigned only once, mark elements as pointer to `const` (con.4). ## Remarks - This rule is currently not implemented in CppCoreCheck. + +Code analysis name: `USE_CONST_POINTER_FOR_ELEMENTS` + +## See also + +[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). diff --git a/docs/code-quality/c26465.md b/docs/code-quality/c26465.md index 7b0a27fb45..d6b7fa8316 100644 --- a/docs/code-quality/c26465.md +++ b/docs/code-quality/c26465.md @@ -1,14 +1,13 @@ --- -title: C26465 +title: Warning C26465 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26465"] +f1_keywords: ["C26465", "NO_CONST_CAST_UNNECESSARY"] helpviewer_keywords: ["C26465"] description: CppCoreCheck rule C26465 that enforces C++ Core Guidelines Type.3 --- -# C26465 NO_CONST_CAST_UNNECESSARY +# Warning C26465 -Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. +> Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. ## See also diff --git a/docs/code-quality/c26466.md b/docs/code-quality/c26466.md index a6d419fe93..13c4d70db4 100644 --- a/docs/code-quality/c26466.md +++ b/docs/code-quality/c26466.md @@ -1,14 +1,13 @@ --- -title: C26466 +title: Warning C26466 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26466"] +f1_keywords: ["C26466", "NO_STATIC_DOWNCAST_POLYMORPHIC"] helpviewer_keywords: ["C26466"] description: CppCoreCheck rule that enforces C++ Core Guidelines Type.2 --- -# C26466 NO_STATIC_DOWNCAST_POLYMORPHIC +# Warning C26466 -Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. +> Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. ## See also diff --git a/docs/code-quality/c26471.md b/docs/code-quality/c26471.md index deaa79b91c..e525394288 100644 --- a/docs/code-quality/c26471.md +++ b/docs/code-quality/c26471.md @@ -1,18 +1,17 @@ --- -title: C26471 +title: Warning C26471 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26471"] +f1_keywords: ["C26471", "NO_REINTERPRET_CAST_FROM_VOID_PTR"] helpviewer_keywords: ["C26471"] description: CppCoreCheck rule C26471 that enforces C++ Core Guidelines Type.1 --- -# C26471 NO_REINTERPRET_CAST_FROM_VOID_PTR +# Warning C26471 -Don't use `reinterpret_cast`. A cast from void* can use `static_cast`. +> Don't use `reinterpret_cast`. A cast from `void*` can use `static_cast` (type.1) -## See also +## Remarks -[C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast) +Code analysis name: `NO_REINTERPRET_CAST_FROM_VOID_PTR` ## Example @@ -27,3 +26,7 @@ void function(void* pValue) } } ``` + +## See also + +[C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast) diff --git a/docs/code-quality/c26472.md b/docs/code-quality/c26472.md index 2b64d60e6b..3a18f09f0e 100644 --- a/docs/code-quality/c26472.md +++ b/docs/code-quality/c26472.md @@ -1,31 +1,32 @@ --- -description: "Learn more about: C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION" -title: C26472 +description: "Learn more about: Warning C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION" +title: Warning C26472 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26472"] +f1_keywords: ["C26472", "NO_CASTS_FOR_ARITHMETIC_CONVERSION"] helpviewer_keywords: ["C26472"] ms.assetid: 51e215a7-0e0a-4e6c-bff1-805bf5b1af29 --- -# C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION +# Warning C26472 -"Don't use a static_cast for arithmetic conversions. Use brace initialization, gsl::narrow_cast, or gsl::narrow." +> Don't use a static_cast for arithmetic conversions. Use brace initialization, `gsl::narrow_cast`, or `gsl::narrow`. **C++ Core Guidelines**: [Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts -This rule helps to find places where static casts are used to convert between integral types. These casts are unsafe because the compiler would not warn if any data loss occurs. Brace initializers are better for the cases where constants are used, and a compiler error is desired. There are also utilities from the Guidelines Support Library that help to describe intentions clearly: +This rule helps to find places where static casts are used to convert between integral types. These casts are unsafe because the compiler wouldn't warn if any data loss occurs. Brace initializers are better for the cases where constants are used, and a compiler error is desired. There are also utilities from the Guidelines Support Library that help to describe intentions clearly: -- gsl::narrow ensures lossless conversion and causes run-time crash if it is not possible. -- gsl::narrow_cast clearly states that conversion can lose data and it is acceptable. +- `gsl::narrow` ensures lossless conversion and throws `gsl::narrowing_error` if it's not possible. +- `gsl::narrow_cast` clearly states that conversion can lose data and it's acceptable. ## Remarks -- This rule is implemented only for static_casts. Using of C-style casts is generally discouraged. +- This rule is implemented only for static casts. Using of C-style casts is discouraged. + +Code analysis name: `NO_CASTS_FOR_ARITHMETIC_CONVERSION` ## Example -unhandled unexpected data +Unhandled unexpected data: ```cpp rgb from_24bit(std::uint32_t v) noexcept { @@ -37,7 +38,7 @@ rgb from_24bit(std::uint32_t v) noexcept { } ``` -unhandled unexpected data – safer version +Unhandled unexpected data, safer version: ```cpp rgb from_24bit(std::uint32_t v) noexcept { diff --git a/docs/code-quality/c26473.md b/docs/code-quality/c26473.md index 2e61b7b4ef..6ff7913be8 100644 --- a/docs/code-quality/c26473.md +++ b/docs/code-quality/c26473.md @@ -1,25 +1,23 @@ --- -description: "Learn more about: C26473 NO_IDENTITY_CAST" -title: C26473 +description: "Learn more about: Warning C26473 NO_IDENTITY_CAST" +title: Warning C26473 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26473"] +f1_keywords: ["C26473", "NO_IDENTITY_CAST"] helpviewer_keywords: ["C26473"] ms.assetid: d88aaa57-0003-421f-8377-4e6a5c27f2df - --- -# C26473 NO_IDENTITY_CAST +# Warning C26473 -"Don't cast between pointer types where the source type and the target type are the same." +> Don't cast between pointer types where the source type and the target type are the same. **C++ Core Guidelines**: [Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts -This rule helps to remove unnecessary or suspicious casts. Obviously, when type is converted to itself, such conversion is ineffective, yet the fact that the cast is used may indicate subtle design issue or a potential for regression if types change in future. It is always safer to use as few casts as possible. +This rule helps to remove unnecessary or suspicious casts. Obviously, when a type is converted to itself, such a conversion is ineffective. Yet the fact that the cast is used may indicate a subtle design issue or a potential for regression if types change in future. It's always safer to use as few casts as possible. ## Remarks -- This rule is implemented for static and reinterpret casts and checks only pointer types. +- This rule is implemented for static casts and reinterpret casts, and checks only pointer types. ## Example diff --git a/docs/code-quality/c26474.md b/docs/code-quality/c26474.md index fe113b6b28..30fbf70bef 100644 --- a/docs/code-quality/c26474.md +++ b/docs/code-quality/c26474.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C26474 NO_IMPLICIT_CAST" -title: C26474 +description: "Learn more about: Warning C26474 NO_IMPLICIT_CAST" +title: Warning C26474 ms.date: 08/11/2020 -ms.topic: "conceptual" -f1_keywords: ["C26474"] +f1_keywords: ["C26474", "NO_IMPLICIT_CAST"] helpviewer_keywords: ["C26474"] ms.assetid: 1e23a8e6-97fa-47f5-a279-b52aa2efafa4 --- -# C26474 NO_IMPLICIT_CAST +# Warning C26474 -"Don't cast between pointer types when the conversion could be implicit." +> Don't cast between pointer types when the conversion could be implicit. **C++ Core Guidelines**:\ [Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts diff --git a/docs/code-quality/c26475.md b/docs/code-quality/c26475.md index 8cb02c74a3..b3856c661f 100644 --- a/docs/code-quality/c26475.md +++ b/docs/code-quality/c26475.md @@ -1,43 +1,45 @@ --- -description: "Learn more about: C26475 NO_FUNCTION_STYLE_CASTS" -title: C26475 -ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26475"] +description: "Learn more about: Warning C26475 NO_FUNCTION_STYLE_CASTS" +title: Warning C26475 +ms.date: 06/29/2022 +f1_keywords: ["C26475", "NO_FUNCTION_STYLE_CASTS"] helpviewer_keywords: ["C26475"] ms.assetid: 4ed71cf8-f155-4961-b4fe-77feb3b880c3 --- -# C26475 NO_FUNCTION_STYLE_CASTS +# Warning C26475 -"Do not use function style C-casts." +> Do not use function style C-casts. **C++ Core Guidelines**: [ES.49](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es49-if-you-must-use-a-cast-use-a-named-cast): If you must use a cast, use a named cast -Function-style casts (for example, `int(1.1)`) are another incarnation of C-style casts (like `(int)1.1`), which have questionable safety. Specifically, the compiler doesn’t try to check if any data loss can occur either in C-casts or in function casts. In both cases, it's better either to avoid casting or to use brace initializer if possible. If neither works, static casts may be suitable, but it is still better to use utilities from the Guidelines Support Library: +Function-style casts (for example, `int(1.1)`) are another form of C-style casts (like `(int)1.1`), which have questionable safety. Specifically, the compiler doesn't try to check if any data loss can occur either in C-casts or in function casts. In both cases, it's better either to avoid casting or to use a braced initializer if possible. If neither works, static casts may be suitable, but it's still better to use utilities from the Guidelines Support Library: -- gsl::narrow ensures lossless conversion and causes run-time crash if it is not possible. -- gsl::narrow_cast clearly states that conversion can lose data and it is acceptable. +- `gsl::narrow` ensures lossless conversion and throws `gsl::narrowing_error` if it's not possible. +- `gsl::narrow_cast` clearly states that conversion can lose data and it's acceptable. ## Remarks -- This rule fires only for constants of primitive types. These are the cases where compiler can clearly detect data loss and emit error if brace initializer is used. The cases that would require run-time execution are flagged by C26493 NO_CSTYLE_CAST. -- Default initializers are not flagged (for example `int()`). +- This rule fires only for constants of primitive types. The compiler can clearly detect data loss in these cases and emits an error if a braced initializer is used. The cases that would require run-time execution are flagged by [C26493 NO_CSTYLE_CAST](./c26493.md). + +- Default initializers aren't flagged (for example `int()`). ## Example -dangerous conversion +Dangerous conversion example: ```cpp constexpr auto planck_constant = float( 6.62607004082e-34 ); // C26475 ``` +Compiler error for dangerous conversion, detecting potential data loss: + ```cpp -dangerous conversion – detecting potential data loss constexpr auto planck_constant = float{ 6.62607004082e-34 }; // Error C2397 ``` +To correct the dangerous conversion, use an appropriately sized primitive type: + ```cpp -dangerous conversion – corrected constexpr auto planck_constant = double{ 6.62607004082e-34 }; ``` diff --git a/docs/code-quality/c26476.md b/docs/code-quality/c26476.md index 69c3ef7646..d942009432 100644 --- a/docs/code-quality/c26476.md +++ b/docs/code-quality/c26476.md @@ -1,16 +1,24 @@ --- -description: "Learn more about: C26476 USE_VARIANT" -title: C26476 -ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26476"] +description: "Learn more about the C26476 USE_VARIANT C++ Core Guidelines Checker warning. Use a type-safe alternative to union, which is preferred in modern code." +title: Warning C26476 +ms.date: 04/29/2022 +f1_keywords: ["C26476", "USE_VARIANT"] helpviewer_keywords: ["C26476"] ms.assetid: bb2b3b26-9a84-4d81-8bae-ad9a5577c8a6 author: kylereedmsft ms.author: kylereed +ms.custom: kr2b-contr-experiment --- -# C26476 USE_VARIANT +# Warning C26476 + +> Expression/symbol '*name*' uses a naked union '*union*' with multiple type pointers: Use variant instead (type.7) + +## Remarks `std::variant` provides a type-safe alternative to `union` and should be preferred in modern code. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ru-naked) +Code analysis name: `USE_VARIANT` + +## See also + +[C++ Core Guideline C.181](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ru-naked) diff --git a/docs/code-quality/c26477.md b/docs/code-quality/c26477.md index 72446dd4a1..fe713f5618 100644 --- a/docs/code-quality/c26477.md +++ b/docs/code-quality/c26477.md @@ -1,16 +1,24 @@ --- -description: "Learn more about: C26477 USE_NULLPTR_NOT_CONSTANT" -title: C26477 -ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26477"] +description: "Learn more about the C26477 USE_NULLPTR_NOT_CONSTANT C++ Core Guidelines Checker warning. The nullptr value allows overloads with special null handling." +title: Warning C26477 +ms.date: 04/29/2022 +f1_keywords: ["C26477", "USE_NULLPTR_NOT_CONSTANT"] helpviewer_keywords: ["C26477"] ms.assetid: d5395efc-5eb2-4e82-9b45-fcd5ff4577bf author: kylereedmsft ms.author: kylereed +ms.custom: kr2b-contr-experiment --- -# C26477 USE_NULLPTR_NOT_CONSTANT +# Warning C26477 + +> Use '`nullptr`' rather than 0 or NULL (es.47) + +## Remarks `nullptr` has a special type `nullptr_t` that allows overloads with special null handling. Using `0` or `NULL` in place of `nullptr` bypasses the type safety and deduction that `nullptr` provides. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nullptr) +Code analysis name: `USE_NULLPTR_NOT_CONSTANT` + +## See also + +[C++ Core Guideline ES.47](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nullptr) diff --git a/docs/code-quality/c26478.md b/docs/code-quality/c26478.md index 68a0e6d53d..ddaff2f01b 100644 --- a/docs/code-quality/c26478.md +++ b/docs/code-quality/c26478.md @@ -1,20 +1,23 @@ --- +title: Warning C26478 description: "Learn more about: Warning C26478: Don't use std::move on constant variables. (es.56)" -title: c26478 -keywords: c26478 -ms.date: 07/15/2019 -ms.topic: reference -f1_keywords: ["C26478"] +ms.date: 10/12/2023 +f1_keywords: ["C26478", "NO_MOVE_OP_ON_CONST"] helpviewer_keywords: ["C26478"] -dev_langs: ["C++"] --- -# Warning C26478: Don't use std::move on constant variables. (es.56) +# Warning C26478 -This warning is to indicate that the use of std::move not consistent with how std::move is intended to be used. +> Don't use `std::move` on constant variables. (es.56) -When called on a const object, std::move returns a copy of the object, which is likely not the developer's intent. +## Remarks -## Example 1 +This warning is to indicate that the use of `std::move` not consistent with how `std::move` is intended to be used. + +Because `const` objects can't be moved, calling `std::move` on them has no effect. This pattern can result in unintended copies. + +Code analysis name: `NO_MOVE_OP_ON_CONST` + +## Example ```cpp struct node @@ -30,23 +33,8 @@ void foo(const node& n) } ``` -An assignment operator or using the passed in parameter will prevent this warning from being issued and will adequately serve the developer's use case. - -## Example 2 - -```cpp -struct s; - -template -void bar(T t){}; - -void foo() -{ - const s s1; - bar(std::move(s1)); // C26478 reported here -} -``` +To fix the issue, remove the redundant `std::move`. ## See also -[ES.56 - Write std::move() only when you need to explicitly move an object to another scope](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es56-write-stdmove-only-when-you-need-to-explicitly-move-an-object-to-another-scope) +[ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es56-write-stdmove-only-when-you-need-to-explicitly-move-an-object-to-another-scope) diff --git a/docs/code-quality/c26479.md b/docs/code-quality/c26479.md new file mode 100644 index 0000000000..4612d6fea0 --- /dev/null +++ b/docs/code-quality/c26479.md @@ -0,0 +1,42 @@ +--- +title: Warning C26479 +description: "Learn more about: Warning C26479: Don't use std::move to return a local variable. (f.48)" +ms.date: 10/12/2023 +f1_keywords: ["C26479", "NO_MOVE_RET_ON_LOCALS"] +helpviewer_keywords: ["C26479"] +--- +# Warning C26479 + +> Don't use std::move to return a local variable. (f.48) + +## Remarks + +The `return` statement is the last use of a local variable, so the compiler uses move semantics to return it whenever possible. +Adding a `std::move` is redundant in this scenario. Moreover, redundant `std::move`s can prevent copy elision. + +Code analysis name: `NO_MOVE_RET_ON_LOCALS` + +## Example 1 + +```cpp +S foo() +{ + S local1{}; + return std::move(local1); // Warning: C26479 +} +``` + +To fix this issue, remove the redundant `std::move`: + +```cpp +S foo() +{ + S local1{}; + return local1; // No warning +} +``` + +## See also + +[F.48: Don't `return std::move(local)`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f48-dont-return-stdmovelocal)\ +[ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es56-write-stdmove-only-when-you-need-to-explicitly-move-an-object-to-another-scope) diff --git a/docs/code-quality/c26481.md b/docs/code-quality/c26481.md index c0003e1eb8..051b2c96ee 100644 --- a/docs/code-quality/c26481.md +++ b/docs/code-quality/c26481.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C26481 NO_POINTER_ARITHMETIC" -title: C26481 +description: "Learn more about: Warning C26481 NO_POINTER_ARITHMETIC" +title: Warning C26481 ms.date: 04/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26481"] +f1_keywords: ["C26481", "NO_POINTER_ARITHMETIC"] helpviewer_keywords: ["C26481"] ms.assetid: 4fd8694d-b45b-4163-b2d5-88c4889d00ed --- -# C26481 NO_POINTER_ARITHMETIC +# Warning C26481 -> warning C26481: Don't use pointer arithmetic. Use span instead (bounds.1). +> Don't use pointer arithmetic. Use span instead (bounds.1). ## Remarks This check supports the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rule [I.13](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-array): *Do not pass an array as a single pointer*. Whenever raw pointers are used in arithmetic operations they should be replaced with safer kinds of buffers, such as `span` or `vector`. -This check is more restrictive than I.13: it doesn’t skip `zstring` or `czstring` types. +This check is more restrictive than I.13: it doesn't skip `zstring` or `czstring` types. C26481 and [C26485](c26485.md) come from the [Bounds Safety Profile](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. diff --git a/docs/code-quality/c26482.md b/docs/code-quality/c26482.md index 36e607c406..e360a51d10 100644 --- a/docs/code-quality/c26482.md +++ b/docs/code-quality/c26482.md @@ -1,14 +1,13 @@ --- -title: C26482 +title: Warning C26482 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26482"] +f1_keywords: ["C26482", "NO_DYNAMIC_ARRAY_INDEXING"] helpviewer_keywords: ["C26482"] description: CppCoreCheck rule C26482 that enforces C++ Core Guidelines Bounds.2 --- -# C26482 NO_DYNAMIC_ARRAY_INDEXING +# Warning C26482 -Only index into arrays using constant expressions. +> Only index into arrays using constant expressions. ## See also diff --git a/docs/code-quality/c26483.md b/docs/code-quality/c26483.md index c41fbc206a..5e031b2448 100644 --- a/docs/code-quality/c26483.md +++ b/docs/code-quality/c26483.md @@ -1,14 +1,13 @@ --- -title: C26483 +title: Warning C26483 +description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26483"] +f1_keywords: ["C26483", "STATIC_INDEX_OUT_OF_RANGE"] helpviewer_keywords: ["C26483"] -description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 --- -# C26483 STATIC_INDEX_OUT_OF_RANGE +# Warning C26483 -Value %value% is outside the bounds (0, %bound%) of variable '%variable%'. Only index into arrays using constant expressions that are within bounds of the array (bounds.2). +> Value '*value*' is outside the bounds (0, '*bound*') of variable '*variable*'. Only index into arrays using constant expressions that are within bounds of the array (bounds.2). ## See also @@ -25,5 +24,4 @@ void function() int arr2[] { 1, 2, 3 }; arr2[3] = 4; // C26483, 3 is outside the bounds of the array } - ``` diff --git a/docs/code-quality/c26485.md b/docs/code-quality/c26485.md index 89e9224931..e0aa010236 100644 --- a/docs/code-quality/c26485.md +++ b/docs/code-quality/c26485.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C26485 NO_ARRAY_TO_POINTER_DECAY" -title: C26485 +description: "Learn more about: Warning C26485 NO_ARRAY_TO_POINTER_DECAY" +title: Warning C26485 ms.date: 04/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26485"] +f1_keywords: ["C26485", "NO_ARRAY_TO_POINTER_DECAY"] helpviewer_keywords: ["C26485"] ms.assetid: 8915ad2d-7fd6-4bbc-abe4-0b3292ea2170 --- -# C26485 NO_ARRAY_TO_POINTER_DECAY +# Warning C26485 -> warning C26485: Expression '*array-name*': No array to pointer decay (bounds.3). +> Expression '*array-name*': No array to pointer decay (bounds.3). ## Remarks -Like [C26481](c26481.md), this check helps to enforce the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rule [I.13](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-array): *Do not pass an array as a single pointer*. The rule detects places where static array type information is lost from decay to a raw pointer. The `zstring` and `czstring` types are not excluded. +Like [C26481](c26481.md), this check helps to enforce the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rule [I.13](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-array): *Do not pass an array as a single pointer*. The rule detects places where static array type information is lost from decay to a raw pointer. The `zstring` and `czstring` types aren't excluded. C26481 and C26485 come from the [Bounds Safety Profile](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. diff --git a/docs/code-quality/c26486.md b/docs/code-quality/c26486.md index a77e0a84ad..bc06d1ef91 100644 --- a/docs/code-quality/c26486.md +++ b/docs/code-quality/c26486.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION" -title: C26486 -ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26486"] +description: "Learn more about the C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION C++ Core Guidelines Checker warning. Don't pass an invalid pointer as a parameter." +title: Warning C26486 +ms.date: 04/29/2022 +f1_keywords: ["C26486", "LIFETIMES_FUNCTION_PRECONDITION_VIOLATION"] helpviewer_keywords: ["C26486"] ms.assetid: d5395efc-5eb2-4e82-9b45-fcd5ff4577bf author: kylereedmsft ms.author: kylereed +ms.custom: kr2b-contr-experiment --- -# C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION +# Warning C26486 -Don't pass a pointer that may be invalid (dangling) as a parameter to a function. +> Don't pass a pointer that may be invalid (dangling) as a parameter to a function. ```cpp void use(int*); @@ -36,6 +36,8 @@ The Lifetime guidelines from the C++ core guidelines outline a contract that cod - Never return (either formal return or out parameter) any pointer from a function. - Never pass an invalid (dangling) pointer to any function. +Code analysis name: `LIFETIMES_FUNCTION_PRECONDITION_VIOLATION` + ## See also - [C++ Core Guidelines Lifetimes Paper](https://github.com/isocpp/CppCoreGuidelines/blob/master/docs/Lifetime.pdf) diff --git a/docs/code-quality/c26487.md b/docs/code-quality/c26487.md index 7a53a57f8b..801d46b9ce 100644 --- a/docs/code-quality/c26487.md +++ b/docs/code-quality/c26487.md @@ -1,15 +1,14 @@ --- -title: C26487 +title: Warning C26487 description: "Reference for Visual Studio C++ code analysis warning C26487 from the C++ Core Guidelines." ms.date: 01/30/2020 -ms.topic: "conceptual" -f1_keywords: ["C26487"] +f1_keywords: ["C26487", "LIFETIMES_FUNCTION_POSTCONDITION_VIOLATION"] helpviewer_keywords: ["C26487"] ms.assetid: 2b0dbec3-c963-4437-8218-933717c1db98 --- -# C26487 LIFETIMES_FUNCTION_POSTCONDITION_VIOLATION +# Warning C26487 -Don't allow a function to return an invalid pointer, either through a formal return statement or through output parameters. +> Don't allow a function to return an invalid pointer, either through a formal return statement or through output parameters. ```cpp int* ex1(int a) diff --git a/docs/code-quality/c26488.md b/docs/code-quality/c26488.md index 8e108982fc..a54608facb 100644 --- a/docs/code-quality/c26488.md +++ b/docs/code-quality/c26488.md @@ -1,17 +1,15 @@ --- -description: "Learn more about: C26488 LIFETIMES_DEREF_NULL_POINTER" -title: C26488 +title: Warning C26488 +description: "Learn more about: Warning C26488 LIFETIMES_DEREF_NULL_POINTER" ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26488"] +f1_keywords: ["C26488", "LIFETIMES_DEREF_NULL_POINTER"] helpviewer_keywords: ["C26488"] -ms.assetid: 2ade0d31-f259-49de-8676-cce6092fabfc author: kylereedmsft ms.author: kylereed --- -# C26488 LIFETIMES_DEREF_NULL_POINTER +# Warning C26488 -Don't dereference a pointer that may be null. +> Don't dereference a pointer that may be null. ```cpp void ex1() @@ -29,9 +27,9 @@ void ex1() The Lifetime guidelines from the C++ core guidelines outline a contract that code can follow which will enable more thorough static memory leak and dangling pointer detection. The basic ideas behind the guidelines are: -1) Never dereference an invalid (dangling) or known-null pointer -2) Never return (either formal return or out parameter) any pointer from a function. -3) Never pass an invalid (dangling) pointer to any function. +1. Never dereference an invalid (dangling) or known-null pointer. +1. Never return (either formal return or out parameter) any pointer from a function. +1. Never pass an invalid (dangling) pointer to any function. ## See also diff --git a/docs/code-quality/c26489.md b/docs/code-quality/c26489.md index 2723776bed..85df9e569a 100644 --- a/docs/code-quality/c26489.md +++ b/docs/code-quality/c26489.md @@ -1,17 +1,15 @@ --- -description: "Learn more about: C26489 LIFETIMES_DEREF_INVALID_POINTER" -title: C26489 +title: Warning C26489 +description: "Learn more about: Warning C26489 LIFETIMES_DEREF_INVALID_POINTER" ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26489"] +f1_keywords: ["C26489", "LIFETIMES_DEREF_INVALID_POINTER"] helpviewer_keywords: ["C26489"] -ms.assetid: 15983d4f-f615-42e7-8521-ee094b87d066 author: kylereedmsft ms.author: kylereed --- -# C26489 LIFETIMES_DEREF_INVALID_POINTER +# Warning C26489 -Don't dereference a pointer that may be invalid. +> Don't dereference a pointer that may be invalid. ```cpp int ex1() @@ -31,9 +29,9 @@ int ex1() The Lifetime guidelines from the C++ core guidelines outline a contract that code can follow which will enable more thorough static memory leak and dangling pointer detection. The basic ideas behind the guidelines are: -1) Never dereference an invalid (dangling) or known-null pointer -2) Never return (either formal return or out parameter) any pointer from a function. -3) Never pass an invalid (dangling) pointer to any function. +1. Never dereference an invalid (dangling) or known-null pointer. +1. Never return (either formal return or out parameter) any pointer from a function. +1. Never pass an invalid (dangling) pointer to any function. ## See also diff --git a/docs/code-quality/c26490.md b/docs/code-quality/c26490.md index b81adfe5ee..48e766138e 100644 --- a/docs/code-quality/c26490.md +++ b/docs/code-quality/c26490.md @@ -1,14 +1,13 @@ --- -title: C26490 +title: Warning C26490 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26490"] +f1_keywords: ["C26490", "NO_REINTERPRET_CAST"] helpviewer_keywords: ["C26490"] description: CppCoreCheck rule C26490 that enforces C++ Core Guidelines Type.1 --- -# C26490 NO_REINTERPRET_CAST +# Warning C26490 -Don't use `reinterpret_cast`. +> Don't use `reinterpret_cast`. ## See also diff --git a/docs/code-quality/c26491.md b/docs/code-quality/c26491.md index a486684bf4..b55c5b0f32 100644 --- a/docs/code-quality/c26491.md +++ b/docs/code-quality/c26491.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: C26491 NO_STATIC_DOWNCAST" -title: C26491 +description: "Learn more about: Warning C26491 NO_STATIC_DOWNCAST" +title: Warning C26491 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26491"] +f1_keywords: ["C26491", "NO_STATIC_DOWNCAST"] helpviewer_keywords: ["C26491"] --- -# C26491 NO_STATIC_DOWNCAST +# Warning C26491 -Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +> Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). diff --git a/docs/code-quality/c26492.md b/docs/code-quality/c26492.md index 5e9ef50e4b..2e6ede538f 100644 --- a/docs/code-quality/c26492.md +++ b/docs/code-quality/c26492.md @@ -1,14 +1,13 @@ --- -title: C26492 +title: Warning C26492 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26492"] +f1_keywords: ["C26492", "NO_CONST_CAST"] helpviewer_keywords: ["C26492"] description: CppCoreCheck rule C26492 that enforces C++ Core Guidelines Type.3 --- -# C26492 NO_CONST_CAST +# Warning C26492 -Don't use `const_cast` to cast away `const`. +> Don't use `const_cast` to cast away `const`. ## See also diff --git a/docs/code-quality/c26493.md b/docs/code-quality/c26493.md index 136eee26a6..34d7225070 100644 --- a/docs/code-quality/c26493.md +++ b/docs/code-quality/c26493.md @@ -1,14 +1,13 @@ --- -title: C26493 +title: Warning C26493 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26493"] +f1_keywords: ["C26493", "NO_CSTYLE_CAST"] helpviewer_keywords: ["C26493"] description: CppCoreCheck rule that enforces C++ Core Guidelines Type.4 --- -# C26493 NO_CSTYLE_CAST +# Warning C26493 -Don't use C-style casts. +> Don't use C-style casts. ## See also diff --git a/docs/code-quality/c26494.md b/docs/code-quality/c26494.md index 941794a77a..7ed21fb002 100644 --- a/docs/code-quality/c26494.md +++ b/docs/code-quality/c26494.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C26494 VAR_USE_BEFORE_INIT" -title: C26494 +title: Warning C26494 +description: "Learn more about: Warning C26494 VAR_USE_BEFORE_INIT." ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26494"] +f1_keywords: ["C26494", "VAR_USE_BEFORE_INIT"] helpviewer_keywords: ["C26494"] --- -# C26494 VAR_USE_BEFORE_INIT +# Warning C26494 -Variable '%variable%' is uninitialized. Always initialize an object. +> Variable '*variable*' is uninitialized. Always initialize an object. -## See also +## Remarks -[C++ Core Guidelines Type.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +This check requires local variables to be initialized at the declaration or in the following statement. ## Example @@ -24,3 +23,19 @@ void function() std::cout << myVal; // C6001 } ``` + +To fix the issue, initialize the variable at the declaration. + +```cpp +#include +void function() +{ + int myVal{}; + std::cout << myVal; +} +``` + +## See also + +[ES.20: Always initialize an object](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es20-always-initialize-an-object)\ +[Pro.safety: Type-safety profile](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#prosafety-type-safety-profile) diff --git a/docs/code-quality/c26495.md b/docs/code-quality/c26495.md index 2ebf6ece1b..f99e5697b8 100644 --- a/docs/code-quality/c26495.md +++ b/docs/code-quality/c26495.md @@ -1,35 +1,44 @@ --- -title: C26495 -ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26495"] +title: Warning C26495 +description: "CppCoreCheck rule that enforces C++ Core Guidelines Type.6." +ms.date: 05/11/2023 +f1_keywords: ["C26495", "MEMBER_UNINIT", "__WARNING_MEMBER_UNINIT"] helpviewer_keywords: ["C26495"] -description: CppCoreCheck rule that enforces C++ Core Guidelines Type.6 --- -# C26495 MEMBER_UNINIT +# Warning C26495 -Variable '%variable%' is uninitialized. Always initialize a member variable (type.6). +> Variable '*variable*' is uninitialized. Always initialize a member variable (type.6). -## See also +## Remarks + +A member variable isn't initialized by a constructor or by an initializer. Make sure all variables are initialized by the end of construction. For more information, see C++ Core Guidelines [Type.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type) and [C.48](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c48-prefer-in-class-initializers-to-member-initializers-in-constructors-for-constant-initializers). -C++ Core Guidelines [Type.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type) and [C.48](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c48-prefer-in-class-initializers-to-member-initializers-in-constructors-for-constant-initializers) +This check is intra-procedural. Whenever there's a function call to a nonconst member function, the check assumes that this member function initializes all of the members. This heuristic can result in missed errors and is in place to avoid false positive results. Moreover, when a member is passed by nonconst reference to a function, the check assumes that the function initializes the member. + +Code analysis name: `MEMBER_UNINIT` ## Example +The following sample generates warning C26495 because the member variable `value` isn't initialized when a `MyStruct` object is created. + ```cpp struct MyStruct { int value; - MyStruct() {}; // C26495, MyStruct::value is uninitialized + MyStruct() {} // C26495, MyStruct::value is uninitialized }; ``` -To fix the warning, add in-class initializers to all of the member variables. See the above linked C++ Core Guidelines pages for additional information. +To resolve the issue, you can add in-class initialization to all of the member variables. ```cpp struct MyStruct { - int value{}; - MyStruct() {}; // no warning, MyStruct::value is set via default member initialization + int value{}; // empty brace initializer sets value to 0 + MyStruct() {} // no warning, MyStruct::value is set via default member initialization }; ``` + +## See also + +[C26494](c26494.md) \ No newline at end of file diff --git a/docs/code-quality/c26496.md b/docs/code-quality/c26496.md index 37cf413164..b5ad576328 100644 --- a/docs/code-quality/c26496.md +++ b/docs/code-quality/c26496.md @@ -1,12 +1,11 @@ --- -title: C26496 +title: Warning C26496 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26496"] +f1_keywords: ["C26496", "USE_CONST_FOR_VARIABLE"] helpviewer_keywords: ["C26496"] description: CppCoreCheck rule C26496 that enforces C++ Core Guidelines Con.4 --- -# C26496 USE_CONST_FOR_VARIABLE +# Warning C26496 > The variable '*variable*' is assigned only once, mark it as `const`. diff --git a/docs/code-quality/c26497.md b/docs/code-quality/c26497.md index 40cb974f20..7a7cd3fc6c 100644 --- a/docs/code-quality/c26497.md +++ b/docs/code-quality/c26497.md @@ -1,12 +1,11 @@ --- -title: C26497 +title: Warning C26497 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26497"] +f1_keywords: ["C26497", "USE_CONSTEXPR_FOR_FUNCTION"] helpviewer_keywords: ["C26497"] description: CppCoreCheck rule that enforces C++ Core Guidelines F.4 --- -# C26497 USE_CONSTEXPR_FOR_FUNCTION +# Warning C26497 > This function *function-name* could be marked `constexpr` if compile-time evaluation is desired (f.4). diff --git a/docs/code-quality/c26498.md b/docs/code-quality/c26498.md index 4b26c617e7..e495372145 100644 --- a/docs/code-quality/c26498.md +++ b/docs/code-quality/c26498.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" -title: C26498 +title: Warning C26498 +description: "Learn more about: Warning C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" ms.date: 08/18/2020 -ms.topic: reference -f1_keywords: ["C26498"] +f1_keywords: ["C26498", "USE_CONSTEXPR_FOR_FUNCTIONCALL"] helpviewer_keywords: ["C26498"] --- -# C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL +# Warning C26498 -This rule helps to enforce Con.5 from the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con5-use-constexpr-for-values-that-can-be-computed-at-compile-time): use constexpr for values that can be computed at compile time. +> The function '*function*' is constexpr, mark variable '*variable*' constexpr if compile-time evaluation is desired (con.5) + +This rule helps to enforce [Con.5: Use `constexpr` for values that can be computed at compile time](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#con5-use-constexpr-for-values-that-can-be-computed-at-compile-time) in the C++ Core Guidelines. ## Remarks The warning is triggered by assigning the result of a **`constexpr`** function to any non-**`constexpr`** variable whose value doesn't change after the initial assignment. +Code analysis name: `USE_CONSTEXPR_FOR_FUNCTIONCALL` + ## Example -This sample code shows where C26498 may appear, and how to avoid it: +This sample code shows where C26498 may appear: ```cpp constexpr int getMyValue() @@ -33,3 +36,28 @@ void foo() val3 = val3 * val2; } ``` + +To fix the issues, mark `val1` and `val2` **`constexpr`**: + +```cpp +constexpr int getMyValue() +{ + return 1; +} + +void foo() +{ + constexpr int val0 = getMyValue(); // OK + constexpr int val1 = getMyValue(); // OK + constexpr int val2 = getMyValue(); // OK + int val3 = getMyValue(); // OK + val3 = val3 * val2; +} +``` + + +## See also + +[C26497](c26407.md)\ +[C26814](c26814.md)\ +[Con.5: Use `constexpr` for values that can be computed at compile time](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#con5-use-constexpr-for-values-that-can-be-computed-at-compile-time) diff --git a/docs/code-quality/c26800.md b/docs/code-quality/c26800.md index b35a1b7640..1052f0f0db 100644 --- a/docs/code-quality/c26800.md +++ b/docs/code-quality/c26800.md @@ -1,25 +1,54 @@ --- -description: "Learn more about: C26800" -title: C26800 +title: Warning C26800 +description: "Learn more about: Warning C26800" ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26800"] +f1_keywords: ["C26800", "USE_OF_A_MOVED_FROM_OBJECT"] helpviewer_keywords: ["C26800"] -author: sunnychatterjee -ms.author: sunnych --- -# C26800 +# Warning C26800 -> warning C26800: Use of a moved from object: \. +> Use of a moved from object: '*object*'. -Warning C26800 is triggered when variable is used after it has been moved from. A variable is considered moved from after it was passed to a function as rvalue reference. There are some legitimate exceptions for uses such as assignment, destruction, and some state resetting functions such as std::vector::clear. +## Remarks -## Examples +Warning C26800 is triggered when a variable is used after it has been moved from. A variable is considered moved from after it's passed to a function as rvalue reference. There are some exceptions for assignment, destruction, and some state resetting functions such as `std::vector::clear`. After using a state resetting function, we're free to use the variable. This check only reasons about the local variables. + +The following methods are considered state resetting methods: +- Functions with the following case-insensitive substring in their name: `clear`, `clean`, `reset`, `free`, `destroy`, `release`, `dealloc`, `assign` +- Overloaded assignment operators, destructor -The following code will generate C26800. +This check respects the `std::swap` operation: ```cpp +void f() { + Y y1, y2; + consume(std::move(y1)); + std::swap(y1, y2); + y1.method(); // OK, valid after swap. + y2.method(); // warning C26800 +} +``` +The check also supports the `try_emplace` operations in STL that conditionally move its argument: + +```cpp +int g() { + std::map m; + Y val; + auto emplRes = m.try_emplace(1, std::move(val)); + if (!emplRes.second) { + val.method(); // No C26800, val was not moved because the insertion did not happen. + } +} +``` + +Code analysis name: `USE_OF_A_MOVED_FROM_OBJECT` + +## Examples + +The following code generates C26800. + +```cpp #include struct X { @@ -37,14 +66,13 @@ void use_cref(const T&); void test() { X x1; X x2 = std::move(x1); - use_cref(x1); // @expected(26800) + use_cref(x1); // warning C26800 } ``` -The following code will not generate C26800. +The following code doesn't generate C26800. ```cpp - #include struct MoveOnly { diff --git a/docs/code-quality/c26810.md b/docs/code-quality/c26810.md index b43faab362..95c9c83644 100644 --- a/docs/code-quality/c26810.md +++ b/docs/code-quality/c26810.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26810" -title: C26810 -ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26810"] +title: Warning C26810 +description: "Learn more about: Warning C26810." +ms.date: 05/11/2023 +f1_keywords: ["C26810", "COROUTINES_USE_AFTER_FREE_CAPTURE"] helpviewer_keywords: ["C26810"] -author: sunnychatterjee -ms.author: sunnych --- -# C26810 +# Warning C26810 -> warning C26810: Lifetime of captured variable \ might end by the time the coroutine is resumed. +> Lifetime of captured variable '*var*' might end by the time the coroutine is resumed. -Warning C26810 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +## Remarks + +Warning C26810 is triggered when a variable might be used after its lifetime ended in a resumed coroutine. + +Code analysis name: `COROUTINES_USE_AFTER_FREE_CAPTURE` ## Example -The following code will generate C26810. +The following code generates C26810. ```cpp - #include #include @@ -48,6 +48,22 @@ void bad_lambda_example1() } ``` +To fix this warning, consider using by-value arguments instead of captures: + +```cpp +void bad_lambda_example1() +{ + int x = 5; + auto good = [](int x) -> std::future { + co_await ManualControl{g_suspended_coro}; + printf("%d\n", x); + }; + good(x); +} +``` + +Alternatively, if the coroutine is guaranteed to live shorter than the lambda object, use `gsl::suppress` to suppress the warning and document the lifetime contracts in a comment. + ## See also -- [C26811](../code-quality/c26811.md) +[C26811](c26811.md) diff --git a/docs/code-quality/c26811.md b/docs/code-quality/c26811.md index eb9c6ec0e4..ebdc5bcc40 100644 --- a/docs/code-quality/c26811.md +++ b/docs/code-quality/c26811.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26811" -title: C26811 -ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26811"] +title: Warning C26811 +description: "Learn more about: Warning C26811." +ms.date: 05/11/2023 +f1_keywords: ["C26811", "COROUTINES_USE_AFTER_FREE_PARAM"] helpviewer_keywords: ["C26811"] -author: sunnychatterjee -ms.author: sunnych --- -# C26811 +# Warning C26811 -> warning C26811: Lifetime of the memory referenced by parameter \ might end by the time the coroutine is resumed. +> Lifetime of the memory referenced by parameter '*var*' might end by the time the coroutine is resumed. -Warning C26811 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +## Remarks + +Warning C26811 is triggered when a variable might be used after its lifetime ended in a resumed coroutine. + +Code analysis name: `COROUTINES_USE_AFTER_FREE_PARAM` ## Example -The following code will generate C26811. +The following code generates C26811. ```cpp - #include #include @@ -44,6 +44,18 @@ std::future async_coro(int &a) } ``` +To fix this warning, consider taking the argument by value: + +```cpp +std::future async_coro(int a) +{ + co_await ManualControl{g_suspended_coro}; + ++a; +} +``` + +Alternatively, when the lifetime of `a` is guaranteed to outlive the lifetime of the coroutine, suppress the warning using `gsl::suppress` and document the lifetime contracts of the code. + ## See also -- [C26810](../code-quality/c26810.md) +[C26810](c26810.md) diff --git a/docs/code-quality/c26812.md b/docs/code-quality/c26812.md index d1110bad76..f5b54e1086 100644 --- a/docs/code-quality/c26812.md +++ b/docs/code-quality/c26812.md @@ -1,34 +1,35 @@ --- -description: "Learn more about: C26812" -title: c26812 -keywords: c26812 -ms.date: 07/15/2019 -ms.topic: reference -f1_keywords: ["C26812"] +description: "Learn more about: Warning C26812" +title: Warning C26812 +ms.date: 02/14/2022 +f1_keywords: ["C26812", "PreferScopedEnum"] helpviewer_keywords: ["C26812"] -dev_langs: ["C++"] --- -# C26812 +# Warning C26812 -> Warning C26812: Prefer 'enum class' over 'enum' (Enum.3) +> The enum type '*type-name*' is unscoped. Prefer 'enum class' over 'enum' (Enum.3) -The enum type *type-name* is unscoped. Prefer 'enum class' over 'enum' (Enum.3) +## Remarks + +Prefer `enum class` over `enum` to prevent pollution in the global namespace. + +Code analysis name: `PreferScopedEnum` ## Example -The following example is from the C++ Core Guidelines +The following example is from the C++ Core Guidelines: ```cpp void Print_color(int color); -enum Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF }; // C26812 reported here -enum Product_info { Red = 0, Purple = 1, Blue = 2 }; // C26812 reported here +enum Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF }; +enum Product_info { Red = 0, Purple = 1, Blue = 2 }; Web_color webby = Web_color::blue; // Clearly at least one of these calls is buggy. -Print_color(webby); -Print_color(Product_info::Blue); +Print_color(webby); // C26812 +Print_color(Product_info::Blue); // C26812 ``` These warnings are corrected by declaring the enum as enum class: @@ -36,8 +37,8 @@ These warnings are corrected by declaring the enum as enum class: ```cpp void Print_color(int color); -enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF }; // no C26812 -enum class Product_info { red = 0, purple = 1, blue = 2 }; // no C26812 +enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF }; +enum class Product_info { Red = 0, Purple = 1, Blue = 2 }; Web_color webby = Web_color::blue; Print_color(webby); // Error: cannot convert Web_color to int. @@ -46,4 +47,4 @@ Print_color(Product_info::Red); // Error: cannot convert Product_info to int. ## See also -[Enum.3 Prefer enum class over enum](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#enum3-prefer-class-enums-over-plain-enums ) +[Enum.3 Prefer enum class over enum](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#enum3-prefer-class-enums-over-plain-enums) diff --git a/docs/code-quality/c26813.md b/docs/code-quality/c26813.md new file mode 100644 index 0000000000..eabce1bfec --- /dev/null +++ b/docs/code-quality/c26813.md @@ -0,0 +1,48 @@ +--- +title: Warning C26813 +description: "Learn more about: Warning C26813" +ms.date: 05/17/2022 +f1_keywords: ["C26813", "USE_BITWISE_AND_TO_CHEK_ENUM_FLAGS", "USE_BITWISE_AND_TO_CHECK_ENUM_FLAGS"] +helpviewer_keywords: ["C26813"] +--- +# Warning C26813 + +> Use 'bitwise and' to check if a flag is set + +## Remarks + +Most `enum` types with power of two member values are intended to be used as bit flags. As a result, you rarely want to compare these flags for equality. Instead, extract the bits you're interested in by using bitwise operations. + +Code analysis name: `USE_BITWISE_AND_TO_CHEK_ENUM_FLAGS` + +## Example + +```cpp +enum BitWise +{ + A = 1, + B = 2, + C = 4 +}; + +void useEqualsWithBitwiseEnum(BitWise a) +{ + if (a == B) // Warning C26813: Use 'bitwise and' to check if a flag is set + return; +} +``` + +To fix the warning, use bitwise operations: + +```cpp +void useEqualsWithBitwiseEnum(BitWise a) +{ + if (a & B) // Fixed. + return; +} +``` + +## See also + +[C26827](./c26827.md)\ +[C26828](./c26828.md) diff --git a/docs/code-quality/c26814.md b/docs/code-quality/c26814.md index eeb77e1c86..0727406c7d 100644 --- a/docs/code-quality/c26814.md +++ b/docs/code-quality/c26814.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C26814" -title: c26814 -keywords: c26814 +description: "Learn more about: Warning C26814" +title: Warning C26814 ms.date: 07/15/2019 -ms.topic: reference -f1_keywords: ["C26814"] +f1_keywords: ["C26814", "USE_CONSTEXPR_RATHER_THAN_CONST"] helpviewer_keywords: ["C26814"] -dev_langs: ["C++"] --- -# C26814 +# Warning C26814 -> Warning C26814: Use constexpr for constants whose value is known at compile time. (Con.5) -The const variable '%variable%' can be computed at compile time. Consider using constexpr (con.5) +> The const variable '*variable*' can be computed at compile time. Consider using `constexpr` (con.5) + +## Remarks + +Use `constexpr` for constants whose value is known at compile time. (Con.5) + +Code analysis name: `USE_CONSTEXPR_RATHER_THAN_CONST` ## Example diff --git a/docs/code-quality/c26815.md b/docs/code-quality/c26815.md index 811812568c..5a8c319b65 100644 --- a/docs/code-quality/c26815.md +++ b/docs/code-quality/c26815.md @@ -1,21 +1,29 @@ --- -description: "Learn more about: Warning C26815 The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65)" -title: c26815 -keywords: c26815 +title: Warning C26815 +description: "Learn more about: Warning C26815." author: Rastaban ms.author: philc ms.date: 01/27/2020 -ms.topic: reference -f1_keywords: ["C26815"] +f1_keywords: ["C26815", "LIFETIME_LOCAL_USE_AFTER_FREE_TEMP"] helpviewer_keywords: ["C26815"] -dev_langs: ["C++"] --- -# Warning C26815 The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65) +# Warning C26815 -There is a dangling pointer that is the result of an unnamed temporary that has been destroyed. +> The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65) + +## Remarks + +The created pointer or view refers to an unnamed temporary object that is destroyed at the end of the statement. The pointer or view will dangle. + +This check recognizes views and owners from the C++ Standard Template Library (STL). To teach this check about user-authored types, use the `[[msvc::lifetimebound]]` annotation. +The `[[msvc::lifetimebound]]` support is new in MSVC 17.7. + +Code analysis name: `LIFETIME_LOCAL_USE_AFTER_FREE_TEMP` ## Example +Consider the following code compiled in a C++ version before C++23: + ```cpp std::optional> getTempOptVec(); @@ -33,6 +41,11 @@ void views() // Oops, the 's' suffix turns the string literal into a temporary std::string. std::string_view value("This is a std::string"s); // warning C26815 } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +void f() { + int& r = Y{}.get(); // warning C26815 +} ``` These warnings can be fixed by extending the lifetime of the temporary object. @@ -54,8 +67,15 @@ void views() // Fixed by changing to a constant string literal. std::string_view value("This is a string literal"); } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +void f() { + Y y{}; + int& r = y.get(); +} ``` ## See also -[ES.65: Don't dereference an invalid pointer](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-deref) +[C26816](c26816.md)\ +[ES.65: Don't dereference an invalid pointer](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es65-dont-dereference-an-invalid-pointer) diff --git a/docs/code-quality/c26816.md b/docs/code-quality/c26816.md index 768f918df4..f60d02ef09 100644 --- a/docs/code-quality/c26816.md +++ b/docs/code-quality/c26816.md @@ -1,20 +1,26 @@ --- -description: "Learn more about: Warning C26816 The pointer points to memory allocated on the stack (ES.65)" -title: c26816 -keywords: c26816 +title: Warning C26816 +description: "Learn more about: Warning C26816." author: Rastaban ms.author: philc ms.date: 01/27/2020 -ms.topic: reference -f1_keywords: ["C26816"] +f1_keywords: ["C26816", "LIFETIME_LOCAL_USE_AFTER_FREE_STACK"] helpviewer_keywords: ["C26816"] -dev_langs: ["C++"] --- -# Warning C26816 The pointer points to memory allocated on the stack (ES.65) +# Warning C26816 -The pointer points to a variable that is allocated on the stack. When the variable goes out of scope it is cleaned up, which causes the pointer to be invalid. +> The pointer points to memory allocated on the stack (ES.65) -## Example +## Remarks + +The pointer points to a variable that is allocated on the stack. When the variable goes out of scope it's cleaned up, which causes the pointer to be invalid. + +This check recognizes views and owners from the C++ Standard Template Library (STL). To teach this check about user-authored types, use the `[[msvc::lifetimebound]]` annotation. +The `[[msvc::lifetimebound]]` support is new in MSVC 17.7. + +Code analysis name: `LIFETIME_LOCAL_USE_AFTER_FREE_STACK` + +## Examples ```cpp // In this example, std::string is being used internally because the implementer felt it was easier to @@ -24,7 +30,13 @@ const char *danglingRawPtrFromLocal() { // interesting string initialization here - return s.c_str(); // Oops, The pointer points to memory allocated on the stack + return s.c_str(); // Oops, The pointer points to memory that will be cleaned up upon return. Warning C26816. +} + +struct Y { int& get() [[msvc::lifetimebound]]; }; +int& f() { + Y y; + return y.get(); // Warning C26826 } ``` @@ -39,8 +51,15 @@ std::string danglingRawPtrFromLocal() { return s; } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +int f() { + Y y; + return y.get(); +} ``` ## See also -[ES.65: Don't dereference an invalid pointer](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-deref) +[C26815](c26815.md)\ +[ES.65: Don't dereference an invalid pointer](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es65-dont-dereference-an-invalid-pointer) diff --git a/docs/code-quality/c26817.md b/docs/code-quality/c26817.md index 11e462699e..3e66b660cf 100644 --- a/docs/code-quality/c26817.md +++ b/docs/code-quality/c26817.md @@ -1,16 +1,15 @@ --- -title: C26817 +title: Warning C26817 description: "Reference for Microsoft C++ Code Analysis warning C26817 in Visual Studio." -ms.date: 02/24/2020 -ms.topic: "reference" +ms.date: 10/12/2023 f1_keywords: ["C26817"] helpviewer_keywords: ["C26817"] --- -# C26817 +# Warning C26817 > Potentially expensive copy of variable *name* in range-for loop. Consider making it a const reference (es.71). -For more information, see [ES.71 notes](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#note-214) in the C++ Core Guidelines. +For more information, see [ES.71: Prefer a range-`for`-statement to a `for`-statement when there is a choice](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es71-prefer-a-range-for-statement-to-a-for-statement-when-there-is-a-choice) in the C++ Core Guidelines. ## Example @@ -26,7 +25,7 @@ class MyComplexType { void expensive_function(std::vector& complex_vector_ref) { - for (auto item: complex_vector_ref) + for (auto item: complex_vector_ref) // Warning: C26817 { // At each iteration, item gets a copy of the next element // ... @@ -39,9 +38,7 @@ void expensive_function(std::vector& complex_vector_ref) } ``` -This behavior is fine for scalars (pointers, arithmetic types, and so on), but for larger types, the copying may become expensive. - -## Solution +The warning is ignoring some types that are cheap to copy like for scalars (pointers, arithmetic types, and so on). To fix this issue, if the loop variable isn't mutated anywhere in the loop, make it a const reference: @@ -68,4 +65,4 @@ void less_expensive_function(std::vector& complex_vector_ref) } ``` -The **`const`** keyword makes the loop variable immutable. Use of a non-const reference may cause potentially unwanted side effects in the original container elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable. +The **`const`** keyword makes the loop variable immutable. Use of a non-const reference makes it possible to inadvertently use the reference to modify the container's elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable. diff --git a/docs/code-quality/c26818.md b/docs/code-quality/c26818.md index cac9a5c97b..aed557b6ad 100644 --- a/docs/code-quality/c26818.md +++ b/docs/code-quality/c26818.md @@ -1,12 +1,12 @@ --- -title: C26818 +title: Warning C26818 description: "Reference for Microsoft C++ Code Analysis warning C26818 in Visual Studio." ms.date: 04/22/2020 f1_keywords: ["C26818"] helpviewer_keywords: ["C26818"] no-loc: [ default, int, char ] --- -# C26818 +# Warning C26818 > Switch statement does not cover all cases. Consider adding a 'default' label (es.79). diff --git a/docs/code-quality/c26819.md b/docs/code-quality/c26819.md index 28c85110ed..fea652f765 100644 --- a/docs/code-quality/c26819.md +++ b/docs/code-quality/c26819.md @@ -1,12 +1,11 @@ --- -title: C26819 +title: Warning C26819 description: "Reference for Microsoft C++ Code Analysis warning C26819 in Visual Studio." ms.date: 04/22/2020 -ms.topic: "reference" f1_keywords: ["C26819"] helpviewer_keywords: ["C26819"] --- -# C26819 +# Warning C26819 > Unannotated fallthrough between switch labels (es.78). @@ -14,11 +13,11 @@ helpviewer_keywords: ["C26819"] This check covers implicit fallthrough in switch statements. Implicit fallthrough is when control flow transfers from one switch case directly into a following switch case without the use of the `[[fallthrough]];` statement. This warning is raised when an implicit fallthrough is detected in a switch case containing at least one statement. -For more information, see [ES.78: Don't rely on implicit fallthrough in `switch` statements](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-break) in the C++ Core Guidelines. +For more information, see [ES.78: Don't rely on implicit fallthrough in `switch` statements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es78-dont-rely-on-implicit-fallthrough-in-switch-statements) in the C++ Core Guidelines. ## Example -In this sample, implicit fallthrough occurs from a non-empty switch case into a following case. +In this sample, implicit fallthrough occurs from a nonempty `switch` `case` into a following `case`. ```cpp void fn1(); @@ -28,10 +27,10 @@ void foo(int a) { switch (a) { - case 0: // implicit fallthrough from case 0 to case 1 is OK because case 0 is empty + case 0: // implicit fallthrough from case 0 to case 1 is OK because case 0 is empty case 1: fn1(); // implicit fallthrough from case 1 into case 2 - case 2: + case 2: // Warning C26819. fn2(); break; default: @@ -40,8 +39,6 @@ void foo(int a) } ``` -## Solution - To fix this issue, insert a `[[fallthrough]];` statement where the fallthrough occurs. ```cpp @@ -87,3 +84,7 @@ void foo(int a) } } ``` + +## See also + +[ES.78: Don't rely on implicit fallthrough in `switch` statements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es78-dont-rely-on-implicit-fallthrough-in-switch-statements) diff --git a/docs/code-quality/c26820.md b/docs/code-quality/c26820.md index 865640ad16..133edaf130 100644 --- a/docs/code-quality/c26820.md +++ b/docs/code-quality/c26820.md @@ -1,17 +1,17 @@ --- -title: C26820 +title: Warning C26820 description: "Reference for Microsoft C++ Code Analysis warning C26820 in Visual Studio." -ms.date: 04/07/2020 +ms.date: 10/12/2023 f1_keywords: ["C26820"] helpviewer_keywords: ["C26820"] --- -# C26820 +# Warning C26820 -> Assigning by value when a const-reference would suffice, use const auto& instead (p.9). +> This is a potentially expensive copy operation. Consider using a reference unless a copy is required (p.9) -For more information, see [P.9: Don't waste time or space](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#p9-dont-waste-time-or-space) in the C++ Core Guidelines. +For more information, see [P.9: Don't waste time or space](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#p9-dont-waste-time-or-space) in the C++ Core Guidelines. -This check covers non-obvious and easy-to-miss behavior when assigning a reference to a variable marked **`auto`**. The type of the **`auto`** variable is resolved to a value rather than a reference, and an implicit copy is made. +This check covers nonobvious and easy-to-miss behavior when assigning a reference to a variable marked **`auto`**. The type of the **`auto`** variable is resolved to a value rather than a reference, and an implicit copy is made. ## Remarks diff --git a/docs/code-quality/c26822.md b/docs/code-quality/c26822.md new file mode 100644 index 0000000000..fd661eafff --- /dev/null +++ b/docs/code-quality/c26822.md @@ -0,0 +1,44 @@ +--- +title: Warning C26822 +description: "Describes the Microsoft C/C++ code analysis warning C26822, its causes, and how to address it." +ms.date: 06/27/2022 +f1_keywords: ["C26822", "NULLPTR_DEREFERENCE"] +helpviewer_keywords: ["C26822"] +--- +# Warning C26822 + +> Dereferencing a null pointer '*variable*' (lifetime.1) + +## Remarks + +Dereferencing a null pointer is frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces the value of a pointer to be null and sees that pointer get dereferenced, it will emit a `C26822` warning. You can also enable [C26823](../code-quality/c26823.md) for a stricter analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. + +## Example + +```cpp +void f(int *p) { + if (p == nullptr) + *p = 42; // warning: C26822 +} + +void assign_to_gsl_notnull() { + int* p = nullptr; + auto q = gsl::make_not_null(p); // C26822 warning +} +``` + +To solve this warning, make sure there's no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: + +```cpp +_Notnull_ int *get_my_ptr(); +gsl::not_null get_my_ptr2(); + +void local_analysis(int *p) { + _Analysis_assume_(p != nullptr); + *p = 42; +} + +void local_analysis2(_In_ int *p) { + int a = *p; +} +``` diff --git a/docs/code-quality/c26823.md b/docs/code-quality/c26823.md new file mode 100644 index 0000000000..0ac7318a8a --- /dev/null +++ b/docs/code-quality/c26823.md @@ -0,0 +1,45 @@ +--- +title: Warning C26823 +description: "Describes the Microsoft C/C++ code analysis warning C26823, its causes, and how to address it." +ms.date: 06/27/2022 +f1_keywords: ["C26823", "NULLPTR_DEREFERENCE_MAYBE"] +helpviewer_keywords: ["C26823"] +--- +# Warning C26823 + +> Dereferencing a possibly null pointer '*variable*' (lifetime.1) + +## Remarks + +Dereferencing a null pointer is frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces that the value of a pointer might be null and sees that pointer get dereferenced, it will emit a `C26823` warning. You can enable [C26822](../code-quality/c26822.md) only for a more permissive analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. + +## Example + +```cpp +void invalidate(int **pp); +void condition_null_dereference_invalidated(int* p) +{ + if (p) + return; + + invalidate(&p); + // The call above could reset the value of `p`, thus the low confidence warning. + *p = 5; // warning: C26823 +} +``` + +To solve this warning, make sure there's no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: + +```cpp +_Notnull_ int *get_my_ptr(); +gsl::not_null get_my_ptr2(); + +void local_analysis(int *p) { + _Analysis_assume_(p != nullptr); + *p = 42; +} + +void local_analysis2(_In_ int *p) { + int a = *p; +} +``` diff --git a/docs/code-quality/c26824.md b/docs/code-quality/c26824.md new file mode 100644 index 0000000000..0513c2c3f2 --- /dev/null +++ b/docs/code-quality/c26824.md @@ -0,0 +1,25 @@ +--- +title: Warning C26824 +description: "Describes the Microsoft C/C++ code analysis warning C26824, its causes, and how to address it." +ms.date: 06/27/2022 +f1_keywords: ["C26824", "NULLPTR_POSTCONDITION_VIOLATION"] +helpviewer_keywords: ["C26824"] +--- +# Warning C26824 + +> Postcondition for null pointer '*variable*' requires it to be non-null (lifetime.1) + +## Remarks + +Dereferencing a null pointer is a frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a null pointer returned from a function that has a contract forbidding such an operation, it will emit a `C26824` warning. You can also enable [C26825](../code-quality/c26825.md) for a stricter analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). + +## Example + +```cpp +void postcondition_conditional(bool b, _When_(b == true, _Outptr_) int** p) { + if (b == true) + *p = nullptr; // C26824 warning +} +``` + +To solve this warning, make sure there's no null pointer returned from the annotated function. Or, change the annotations to reflect the behavior of the function. diff --git a/docs/code-quality/c26825.md b/docs/code-quality/c26825.md new file mode 100644 index 0000000000..7945aeb3d0 --- /dev/null +++ b/docs/code-quality/c26825.md @@ -0,0 +1,24 @@ +--- +title: Warning C26825 +description: "Describes the Microsoft C/C++ code analysis warning C26825, its causes, and how to address it." +ms.date: 06/27/2022 +f1_keywords: ["C26825", "NULLPTR_POSTCONDITION_VIOLATION_MAYBE"] +helpviewer_keywords: ["C26825"] +--- +# Warning C26825 + +> Postcondition for possibly null pointer '*variable*' requires it to be non-null (lifetime.1) + +## Remarks + +Dereferencing a null pointer is a frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a potentially null pointer returned from a function that has a contract forbidding such operation, it will emit a `C26825` warning. You can enable [C26824](../code-quality/c26824.md) only for a more permissive analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). + +## Example + +```cpp +void postcondition_conditional(int *q, _Outptr_ int** p) { + *p = q; // C26825 warning +} +``` + +To solve this warning, make sure there's no null pointer returned from the annotated function. Or, change the annotations to reflect the behavior of the function. diff --git a/docs/code-quality/c26826.md b/docs/code-quality/c26826.md index 0dcfd82712..47fd2d9e8d 100644 --- a/docs/code-quality/c26826.md +++ b/docs/code-quality/c26826.md @@ -1,15 +1,15 @@ --- -title: C26826 +title: Warning C26826 description: "Reference for Microsoft C++ Code Analysis warning C26826 in Visual Studio." ms.date: 10/25/2021 f1_keywords: ["C26826"] helpviewer_keywords: ["C26826"] --- -# C26826 +# Warning C26826 > Don't use C-style variable arguments (f.55). -For more information, see [F.55: Don't use `va_arg` arguments](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#F-varargs) in the C++ Core Guidelines. +For more information, see [F.55: Don't use `va_arg` arguments](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f55-dont-use-va_arg-arguments) in the C++ Core Guidelines. ## Remarks @@ -41,6 +41,7 @@ int main() { ``` Alternatives to C-style variable arguments include: + - function overloading - variadic templates - `std::variant` arguments diff --git a/docs/code-quality/c26827.md b/docs/code-quality/c26827.md new file mode 100644 index 0000000000..7f80abb532 --- /dev/null +++ b/docs/code-quality/c26827.md @@ -0,0 +1,57 @@ +--- +title: Warning C26827 +description: "Learn more about: Warning C26827" +ms.date: 05/17/2023 +f1_keywords: ["C26827", "ALMOST_BITWISE_ENUM"] +helpviewer_keywords: ["C26827"] +--- +# Warning C26827 + +> Did you forget to initialize an enum, or intend to use another type? + +## Remarks + +Most `enum` types used in bitwise operations are expected to have members with values of powers of two. This warning attempts to find cases where a value wasn't given explicitly to an enumeration constant. It also finds cases where the wrong enumeration type may have been used inadvertently. + +Code analysis name: `ALMOST_BITWISE_ENUM` + +## Example + +The following sample code causes warning C26827: + +```cpp +enum class AlmostBitWise +{ + A = 1, + B = 2, + C = 4, + D +}; + +int almostBitwiseEnums(AlmostBitWise a, bool cond) +{ + return (int)a|(int)AlmostBitWise::A; // Warning C26827: Did you forget to initialize an enum, or intend to use another type? +} +``` + +To fix the warning, initialize the enumeration constant to the correct value, or use the correct enumeration type in the operation. + +```cpp +enum class AlmostBitWise +{ + A = 1, + B = 2, + C = 4, + D = 8 +}; + +int almostBitwiseEnums(AlmostBitWise a, bool cond) +{ + return (int)a|(int)AlmostBitWise::A; // No warning. +} +``` + +## See also + +[C26813](./c26813.md)\ +[C26828](./c26828.md) diff --git a/docs/code-quality/c26828.md b/docs/code-quality/c26828.md new file mode 100644 index 0000000000..5c0a9d474d --- /dev/null +++ b/docs/code-quality/c26828.md @@ -0,0 +1,63 @@ +--- +title: Warning C26828 +description: "Learn more about: Warning C26828" +ms.date: 05/17/2023 +f1_keywords: ["C26828", "MIXING_OVERLAPPING_ENUMS"] +helpviewer_keywords: ["C26828"] +--- +# Warning C26828 + +> Different enum types have overlapping values. Did you want to use another enum constant here? + +## Remarks + +Most of the time, a single enumeration type describes all the bit flags that you can use for an option. If you use two different enumeration types that have overlapping values in the same bitwise expression, the chances are good those enumeration types weren't designed for use together. + +Code analysis name: `MIXING_OVERLAPPING_ENUMS` + +## Example + +The following sample code causes warning C26828: + +```cpp +enum BitWiseA +{ + A = 1, + B = 2, + C = 4 +}; + +enum class BitWiseB +{ + AA = 1, + BB = 2, + CC = 4, + All = 7 +}; + +int overlappingBitwiseEnums(BitWiseA a) +{ + return (int)a|(int)BitWiseB::AA; // Warning C26828: Different enum types have overlapping values. Did you want to use another enum constant here? +} +``` + +To fix the warning, make sure enumeration types designed for use together have no overlapping values. Or, make sure all the related options are in a single enumeration type. + +```cpp +enum BitWiseA +{ + A = 1, + B = 2, + C = 4 +}; + +int overlappingBitwiseEnums(BitWiseA a) +{ + return (int)a|(int)BitWiseA::A; // No warning. +} +``` + +## See also + +[C26813](./c26813.md)\ +[C26827](./c26827.md) diff --git a/docs/code-quality/c26829.md b/docs/code-quality/c26829.md new file mode 100644 index 0000000000..a19bd224a3 --- /dev/null +++ b/docs/code-quality/c26829.md @@ -0,0 +1,30 @@ +--- +title: Warning C26829 +description: "Describes the Microsoft C/C++ code analysis warning C26829, its causes, and how to address it." +ms.date: 06/23/2022 +f1_keywords: ["C26829", "UNWRAP_EMPTY_OPTIONAL"] +helpviewer_keywords: ["C26829"] +--- +# Warning C26829 + +> Empty optional '*variable*' is unwrapped + +## Remarks + +Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where a `std::optional` is known to be empty and unwrapped. You can also enable [C26830](../code-quality/c26830.md), [C26859](../code-quality/c26859.md), and [C26860](../code-quality/c26860.md) for a stricter analysis. + +## Example + +```cpp +void f(std::optional maybeEmpty) +{ + std::optional empty; + std::optional nonEmpty{5}; + *nonEmpty = 42; // No warning + *empty = 42; // warning: C26829 + if (!maybeEmpty) + *maybeEmpty = 42; // warning: C26829 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. Alternatively, use the `value` method and make sure you handle the `std::bad_optional_access` exception. diff --git a/docs/code-quality/c26830.md b/docs/code-quality/c26830.md new file mode 100644 index 0000000000..686b4b1712 --- /dev/null +++ b/docs/code-quality/c26830.md @@ -0,0 +1,31 @@ +--- +title: Warning C26830 +description: "Describes the Microsoft C/C++ code analysis warning C26830, its causes, and how to address it." +ms.date: 06/23/2022 +f1_keywords: ["C26830", "UNWRAP_EMPTY_OPTIONAL_MAYBE"] +helpviewer_keywords: ["C26830"] +--- +# Warning C26830 + +> Potentially empty optional '*variable*' is unwrapped + +## Remarks + +Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where a `std::optional` isn't checked for emptiness before unwrap operations. You can enable [C26829](../code-quality/c26829.md) only for a more permissive analysis. + +## Example + +```cpp +std::optional getOptional(); + +void f(std::optional maybeEmpty) +{ + if (maybeEmpty) + *maybeEmpty = 42; // No warning + *maybeEmpty = 5; // warning: C26830 + std::optional o = getOptional(); + *o = 42; // warning: C26830 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. Alternatively, use the `value` method and make sure you handle the `std::bad_optional_access` exception. \ No newline at end of file diff --git a/docs/code-quality/c26831.md b/docs/code-quality/c26831.md new file mode 100644 index 0000000000..fba6057d2f --- /dev/null +++ b/docs/code-quality/c26831.md @@ -0,0 +1,63 @@ +--- +title: Warning C26831 +description: "Describes the Microsoft C/C++ code analysis warning C26831, its causes, and how to address it." +ms.date: 03/20/2023 +f1_keywords: ["C26831", "ALLOCATION_POTENTIAL_OVERFLOW"] +helpviewer_keywords: ["C26831"] +--- +# Warning `C26831` + +> Allocation size might be the result of a numerical overflow + +## Remarks + +This warning reports that the size specified for an allocation may be the result of a numerical overflow. For example: + +```cpp +void *SmallAlloc(int); + +void foo(int i, int j) +{ + int* p = (int*)SmallAlloc(i + j); // Warning: C26831 + p[i] = 5; +} +``` + +If `i+j` overflows, `SmallAlloc` returns a buffer that is smaller than expected. That will likely lead to out of bounds attempts to access the buffer later on. This code pattern can result in remote code execution vulnerabilities. + +The check applies to common allocation functions like `new`, `malloc`, and `VirtualAlloc`. The check also applies to custom allocator functions that have `alloc` (case insensitive) in the function name. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +This warning is available in Visual Studio 2022 version 17.7 and later versions. + +## Example + +To fix the previous code example in which `i+j` might overflow, introduce a check to make sure it won't. For example: + +```cpp +void *SmallAlloc(int); + +void foo(int i, int j) +{ + if (i < 0 || j < 0 ) + { + return; + } + + if (i > 100 || j > 100) + { + return; + } + + int* p = (int*)SmallAlloc(i + j); + p[i] = 5; +} +``` + +## See also + +[`C26832`](c26832.md)\ +[`C26833`](c26833.md)\ +[`C26838`](c26838.md)\ +[`C26839`](c26839.md) \ No newline at end of file diff --git a/docs/code-quality/c26832.md b/docs/code-quality/c26832.md new file mode 100644 index 0000000000..adf379b5ca --- /dev/null +++ b/docs/code-quality/c26832.md @@ -0,0 +1,58 @@ +--- +title: Warning C26832 +description: "Describes the Microsoft C/C++ code analysis warning C26832, its causes, and how to address it." +ms.date: 03/20/2023 +f1_keywords: ["C26832", "ALLOCATION_POTENTIAL_OVERFLOW_AFTER_CAST"] +helpviewer_keywords: ["C26832"] +--- +# Warning `C26832` + +> Allocation size is the result of a narrowing conversion that could result in overflow + +## Remarks + +This warning reports that the size specified for an allocation may be the result of a narrowing conversion that results in a numerical overflow. For example: + +```cpp +void* SmallAlloc(int); + +void foo(unsigned short i, unsigned short j) +{ + unsigned short size = i + j; + + int* p = (int*)SmallAlloc(size); // Warning: C26832 + p[i] = 5; +} +``` + +In the expression `i + j`, both `i` and `j` are promoted to integers, and the result of the addition is stored in a temporary integer. Then, the temporary integer is implicitly cast to an `unsigned short` before the value is stored in `size`. The cast to `unsigned short` might overflow, in which case `SmallAlloc` may return a smaller buffer than expected. That will likely lead to out of bounds attempts to access the buffer later on. This code pattern can result in remote code execution vulnerabilities + +This check applies to common allocation functions like `new`, `malloc`, and `VirtualAlloc`. The check also applies to custom allocator functions that have `alloc` (case insensitive) in the function name. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +This warning is available in Visual Studio 2022 version 17.7 and later versions. + +## Example + +To fix the previous code example in which `i+j` might overflow, introduce a check to make sure it won't. For example: + +```cpp +void *SmallAlloc(int); + +void foo(unsigned short i, unsigned short j) +{ + if (i > 100 || j > 100) + return; + + unsigned short size = i + j; + + int* p = (int*)SmallAlloc(size); + p[i] = 5; +} +``` + +## See also + +[`C26831`](c26831.md)\ +[`C26833`](c26833.md) \ No newline at end of file diff --git a/docs/code-quality/c26833.md b/docs/code-quality/c26833.md new file mode 100644 index 0000000000..f751948098 --- /dev/null +++ b/docs/code-quality/c26833.md @@ -0,0 +1,70 @@ +--- +title: Warning C26833 +description: "Describes the Microsoft C/C++ code analysis warning C26833, its causes, and how to address it." +ms.date: 03/20/2023 +f1_keywords: ["C26833", "ALLOCATION_POTENTIAL_OVERFLOW_BEFORE_CHECK"] +helpviewer_keywords: ["C26833"] +--- +# Warning `C26833` + +> Allocation size might be the result of a numerical overflow before the bound check + +## Remarks + +This warning reports that the size specified for an allocation may be the result of a numerical overflow. For example: + +```cpp +void* SmallAlloc(int); + +void foo(unsigned i, unsigned j) +{ + unsigned size = i + j; + + if (size > 50) + { + return; + } + + int* p = (int*)SmallAlloc(size + 5); // Warning: C26833 + p[j] = 5; +} +``` + +The check for `size > 50` is too late. If `i + j` overflows, it produces a small value that passes the check. Then, `SmallAlloc` allocates a buffer smaller than expected. That will likely lead to out of bounds attempts to access the buffer later on. This code pattern can result in remote code execution vulnerabilities. + +This check applies to common allocation functions like `new`, `malloc`, and `VirtualAlloc`. The check also applies to custom allocator functions that have `alloc` (case insensitive) in the function name. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +This warning is available in Visual Studio 2022 version 17.7 and later versions. + +## Example + +To fix the previous code example, make sure `i+j` can't overflow. For example: + +```cpp +void* SmallAlloc(int); + +void foo(unsigned i, unsigned j) +{ + if (i > 100 || j > 100) + { + return; + } + + unsigned size = i + j; + + if (size > 50) + { + return; + } + + int* p = (int*)SmallAlloc(size + 5); + p[j] = 5; +} +``` + +## See also + +[`C26831`](c26831.md)\ +[`C26832`](c26832.md) \ No newline at end of file diff --git a/docs/code-quality/c26835.md b/docs/code-quality/c26835.md new file mode 100644 index 0000000000..1070ca73fd --- /dev/null +++ b/docs/code-quality/c26835.md @@ -0,0 +1,45 @@ +--- +title: Warning C26835 +description: "Describes the Microsoft C/C++ code analysis warning C26835, its causes, and how to address it." +ms.date: 03/20/2023 +f1_keywords: ["C26835", "RTL_COMPARE_MEMORY_MISUSE"] +helpviewer_keywords: ["C26835"] +--- +# Warning `C26835` + +> `RtlCompareMemory` returns the number of matching bytes. Consider replacing this call with `RtlEqualMemory` + +## Remarks + +When `RtlCompareMemory`'s return value is treated as a boolean, it evaluates to true when there is at least 1 equal byte before finding a difference. Moreover, comparing the result of `RtlCompareMemory` to 0 evaluates to false if there is at least 1 matching byte. This behavior may be unexpected because it's different from other comparison functions such as `strcmp`, making the code harder to understand. To check for equality, consider using `RtlEqualMemory` instead. + +This warning is available in Visual Studio 2022 version 17.7 and later versions. + +## Example + +```cpp +int foo(const void* ptr) +{ + if (RtlCompareMemory("test", ptr, 5) == 0) // C26835 + { + // ... + } +} +``` + +To fix the issue, verify if the original intention was to check for equality and replace the function call with `RtlEqualMemory`: + +```cpp +int foo(const void* ptr) +{ + if (RtlEqualMemory("test", ptr, 5)) // C26835 + { + // ... + } +} +``` + +## See also + +[`RtlEqualMemory` macro (`wdm.h`)](/windows-hardware/drivers/ddi/wdm/nf-wdm-rtlequalmemory)\ +[`RtlCompareMemory` function (`wdm.h`)](/windows-hardware/drivers/ddi/wdm/nf-wdm-rtlcomparememory) \ No newline at end of file diff --git a/docs/code-quality/c26837.md b/docs/code-quality/c26837.md new file mode 100644 index 0000000000..2be95d94db --- /dev/null +++ b/docs/code-quality/c26837.md @@ -0,0 +1,143 @@ +--- +title: Warning C26837 +description: "Learn more about: Warning C26837" +ms.date: 11/29/2023 +f1_keywords: ["C26837", "INTERLOCKED_COMPARE_EXCHANGE_MISUSE", "__WARNING_INTERLOCKED_COMPARE_EXCHANGE_MISUSE"] +helpviewer_keywords: ["C26837"] +--- +# Warning C26837 + +> Value for the comparand `comp` for function `func` has been loaded from the destination location `dest` through non-volatile read. + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +The [`InterlockedCompareExchange`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function, and its derivatives such as [`InterlockedCompareExchangePointer`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchangepointer), perform an atomic compare-and-exchange operation on the specified values. If the `Destination` value is equal to the `Comparand` value, the *exchange* value is stored in the address specified by `Destination`. Otherwise, no operation is performed. The `interlocked` functions provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. This function is atomic with respect to calls to other `interlocked` functions. Misuse of these functions can generate object code that behaves differently than you expect because optimization can change the behavior of the code in unexpected ways. + +Consider the following code: + +```cpp +#include + +bool TryLock(__int64* plock) +{ + __int64 lock = *plock; + return (lock & 1) && + _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; +} +``` + +The intent of this code is: + +1. Read the current value from the `plock` pointer. +1. Check if this current value has the least significant bit set. +1. If it does have least significant bit set, clear the bit while preserving the other bits of the current value. + +To accomplish this, a copy of the current value is read from the `plock` pointer and saved to a stack variable `lock`. `lock` is used three times: + +1. First, to check if the least-significant bit is set. +1. Second, as the `Comparand` value to `InterlockedCompareExchange64`. +1. Finally, in the comparison of the return value from `InterlockedCompareExchange64` + +This assumes that the current value saved to the stack variable is read once at the start of the function and doesn't change. This is necessary because the current value is first checked before attempting the operation, then explicitly used as the `Comparand` in `InterlockedCompareExchange64`, and finally used to compare the return value from `InterlockedCompareExchange64`. + +Unfortunately, the previous code can be compiled into assembly that behaves differently than from what you expect from the source code. Compile the previous code with the Microsoft Visual C++ (MSVC) compiler and the [`/O1`](../build/reference/o1-o2-minimize-size-maximize-speed.md) option and inspect the resultant assembly code to see how the value of the lock for each of the references to `lock` is obtained. The MSVC compiler version v19.37 produces assembly code that looks like: + +```x86asm +plock$ = 8 +bool TryLock(__int64 *) PROC ; TryLock, COMDAT + mov r8b, 1 + test BYTE PTR [rcx], r8b + je SHORT $LN3@TryLock + mov rdx, QWORD PTR [rcx] + mov rax, QWORD PTR [rcx] + and rdx, -2 + lock cmpxchg QWORD PTR [rcx], rdx + je SHORT $LN4@TryLock +$LN3@TryLock: + xor r8b, r8b +$LN4@TryLock: + mov al, r8b + ret 0 +bool TryLock(__int64 *) ENDP ; TryLock +``` + +`rcx` holds the value of the parameter `plock`. Rather than make a copy of the current value on the stack, the assembly code is re-reading the value from `plock` every time. This means the value could be different each time it's read. This invalidates the sanitization that the developer is performing. The value is re-read from `plock` after it's verified that it has its least-significant bit set. Because it's re-read after this validation is performed, the new value might no longer have the least-significant bit set. Under a race condition, this code might behave as if it successfully obtained the specified lock when it was already locked by another thread. + +The compiler is allowed to remove or add memory reads or writes as long as the behavior of the code isn't altered. To prevent the compiler from making such changes, force reads to be `volatile` when you read the value from memory and cache it in a variable. Objects that are declared as `volatile` aren't used in certain optimizations because their values can change at any time. The generated code always reads the current value of a `volatile` object when it's requested, even if a previous instruction asked for a value from the same object. The reverse also applies for the same reason. The value of the `volatile` object isn't read again unless requested. For more information about `volatile`, see [`volatile`](..\cpp\volatile-cpp.md). For example: + +```cpp +#include + +bool TryLock(__int64* plock) +{ + __int64 lock = *static_cast(plock); + return (lock & 1) && + _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; +} +``` + +Compile this code with same [`/O1`](../build/reference/o1-o2-minimize-size-maximize-speed.md) option as before. The generated assembly no longer reads `plock` for use of the cached value in `lock`. + +For more examples of how the code can be fixed, see [Example](#example). + +Code analysis name: `INTERLOCKED_COMPARE_EXCHANGE_MISUSE` + +## Example + +The compiler might optimize the following code to read `plock` multiple times instead of using the cached value in `lock`: + +```cpp +#include + +bool TryLock(__int64* plock) +{ + __int64 lock = *plock; + return (lock & 1) && + _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; +} +``` + +To fix the problem, force reads to be `volatile` so that the compiler doesn't optimize code to read successively from the same memory unless explicitly instructed. This prevents the optimizer from introducing unexpected behavior. + +The first method to treat memory as `volatile` is to take the destination address as `volatile` pointer: + +```cpp +#include + +bool TryLock(volatile __int64* plock) +{ + __int64 lock = *plock; + return (lock & 1) && + _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; +} +``` + +The second method is using `volatile` read from the destination address. There are a few different ways to do this: + +- Casting the pointer to `volatile` pointer before dereferencing the pointer +- Creating a `volatile` pointer from the provided pointer +- Using `volatile` read helper functions. + +For example: + +```cpp +#include + +bool TryLock(__int64* plock) +{ + __int64 lock = ReadNoFence64(plock); + return (lock & 1) && + _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; +} +``` + +## Heuristics + +This rule is enforced by detecting if the value in the `Destination` of the `InterlockedCompareExchange` function, or any of its derivatives, is loaded through a non-`volatile` read, and then used as the `Comparand` value. However, it doesn't explicitly check if the loaded value is used to determine the *exchange* value. It assumes the *exchange* value is related to the `Comparand` value. + +## See also + +[`InterlockedCompareExchange` function (winnt.h)](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange)\ +[`_InterlockedCompareExchange` intrinsic functions](../intrinsics/interlockedcompareexchange-intrinsic-functions.md) diff --git a/docs/code-quality/c26838.md b/docs/code-quality/c26838.md new file mode 100644 index 0000000000..652ec704cd --- /dev/null +++ b/docs/code-quality/c26838.md @@ -0,0 +1,62 @@ +--- +title: Warning C26838 +description: Learn about Microsoft C++ code analysis warning C26838. +author: Rastaban +ms.author: philc +ms.topic: reference +ms.date: 1/10/2025 +--- +# Warning C26838 + +> Allocation size is the result of a signed to unsigned narrowing conversion that could result in overflow if the signed value is negative. + +This warning was added in Visual Studio 2022 version 17.13. + +## Remarks + +Reports that the size specified for an allocation may be the result of the conversion of a possibly negative signed value to an unsigned value. For example: + +```cpp +void* CustomAlloc(size_t); + +int* CreateIntArray(int numberOfElements) +{ + int* p = (int*)CustomAlloc(numberOfElements * sizeof(int)); // Warning: C26838 + + return p; +} +``` + +The expression `numberOfElements * sizeof(int)`, `numberOfElements` is signed and `sizeof(int)` is unsigned. On 64-bit machines, `numberOfElements` is promoted to an unsigned value when multiplied +by `sizeof(int)`. When `numberOfElements` is negative, the resulting value may overflow or have unexpected results when passed to `CustomAlloc`. + +This check applies to common allocation functions like `new`, `malloc`, and `VirtualAlloc`. The check also applies to custom allocator functions that have `alloc` (case insensitive) in the function name. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +## Example + +To fix the previous code example in which `numberOfElements * sizeof(int)` might overflow due to a negative signed value, introduce a check to ensure it won't. For example: + +```cpp +void* CustomAlloc(size_t); + +int* CreateIntArray(int numberOfElements) +{ + if (numberOfElements < 0) + return nullptr; + + int* p = (int*)CustomAlloc(numberOfElements * sizeof(int)); + // ... + return p; +} +``` + +In the previous example, checking for a negative value addresses the `C26832` warning. Depending on the size of the types involved, this check may result in a different warning such as [`C26831`](c26831.md). For example, on a 32-bit system, both `int` and `size_t` are 32 bits, so the result of the multiplication can still overflow without negative values. + +## See also + +[`C26831`](c26831.md)\ +[`C26832`](c26832.md)\ +[`C26833`](c26833.md)\ +[`C26833`](c26839.md) \ No newline at end of file diff --git a/docs/code-quality/c26839.md b/docs/code-quality/c26839.md new file mode 100644 index 0000000000..96d47c6df2 --- /dev/null +++ b/docs/code-quality/c26839.md @@ -0,0 +1,53 @@ +--- +title: Warning C26839 +description: Learn about Microsoft C++ code analysis warning C26839. +author: Rastaban +ms.author: philc +ms.topic: reference +ms.date: 1/10/2025 +--- +# Warning C26839 + +> Array new allocation size is the result of a signed to unsigned narrowing conversion that could result in overflow if the signed value is negative. + +This warning was added in Visual Studio 2022 version 17.13. + +## Remarks + +Reports that the size specified for an array `new` allocation may be the result of the conversion of a possibly negative signed value to an unsigned value. For example: + +```cpp +int* CreateIntArray(int size) +{ + int* intArray = new int[size]; + return intArray; +} +``` + +The expression `new int[size]`, `size` is signed. The compiler converts the signed value to an unsigned value to calculate how many bytes to be allocated for the array. When `size` is negative, the result of that calculation may overflow or have unexpected results when passed to `new`. + +This check is the same as [`C26838`](c26838.md), but applies only to `new T[]`. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +## Example + +To fix the previous code example in which the size calculation might overflow due to a negative signed value, introduce a check to ensure it won't. For example: + +```cpp +int* CreateIntArray(int size) +{ + if (size < 0) + return nullptr; + + int* intArray = new int[size]; + return intArray; +} +``` + +## See also + +[`C26831`](c26831.md)\ +[`C26832`](c26832.md)\ +[`C26838`](c26833.md)\ +[`C26838`](c26838.md) \ No newline at end of file diff --git a/docs/code-quality/c26859.md b/docs/code-quality/c26859.md new file mode 100644 index 0000000000..23e1980b8c --- /dev/null +++ b/docs/code-quality/c26859.md @@ -0,0 +1,30 @@ +--- +title: Warning C26859 +description: "Describes the Microsoft C/C++ code analysis warning C26859, its causes, and how to address it." +ms.date: 12/15/2022 +f1_keywords: ["C26859", "UNWRAP_EMPTY_OPTIONAL_VALUE"] +helpviewer_keywords: ["C26859"] +--- +# Warning C26859 + +> Empty optional '*variable*' is unwrapped, will throw exception + +## Remarks + +Unwrapping empty `std::optional` values via the `value` method will throw an exception. Such operation can result in a crash when the exception isn't handled. This check will attempt to find cases where a `std::optional` is known to be empty and unwrapped using the `value` method. You can also enable [C26829](../code-quality/c26829.md), [C26830](../code-quality/c26830.md), and [C26860](../code-quality/c26860.md) for a stricter analysis. + +## Example + +```cpp +void f(std::optional maybeEmpty) +{ + std::optional empty; + std::optional nonEmpty{5}; + nonEmpty.value() = 42; // No warning + empty.value() = 42; // warning: C26859 + if (!maybeEmpty) + maybeEmpty.value() = 42; // warning: C26859 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. diff --git a/docs/code-quality/c26860.md b/docs/code-quality/c26860.md new file mode 100644 index 0000000000..6bae85a25e --- /dev/null +++ b/docs/code-quality/c26860.md @@ -0,0 +1,31 @@ +--- +title: Warning C26860 +description: "Describes the Microsoft C/C++ code analysis warning C26860, its causes, and how to address it." +ms.date: 12/15/2022 +f1_keywords: ["C26860", "UNWRAP_EMPTY_OPTIONAL_VALUE_MAYBE"] +helpviewer_keywords: ["C26860"] +--- +# Warning C26860 + +> Potentially empty optional '*variable*' is unwrapped, may throw exception + +## Remarks + +Unwrapping empty `std::optional` values via the `value` method will throw an exception. Such operation can result in a crash when the exception isn't handled. This check will attempt to find cases where a `std::optional` isn't checked for emptiness before unwrapping it via the `value` method. You can enable [C26829](../code-quality/c26829.md), and [C26859](../code-quality/c26859.md) only for a more permissive analysis. + +## Example + +```cpp +std::optional getOptional(); + +void f(std::optional maybeEmpty) +{ + if (maybeEmpty) + maybeEmpty.value() = 42; // No warning + maybeEmpty.value() = 5; // warning: C26860 + std::optional o = getOptional(); + o.value() = 42; // warning: C26860 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. diff --git a/docs/code-quality/c26861.md b/docs/code-quality/c26861.md new file mode 100644 index 0000000000..2346fa7afd --- /dev/null +++ b/docs/code-quality/c26861.md @@ -0,0 +1,69 @@ +--- +description: "Learn more about: Warning C26861" +title: Warning C26861 +ms.date: 11/29/2023 +f1_keywords: ["C26861", "DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK", "__WARNING_DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK"] +helpviewer_keywords: ["C26861"] +--- +# Warning C26861 + +> Field of a date-time object `var` has been modified without proper leap year checking: `expr` + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +In the Gregorian calendar, every year exactly divisible by four is a leap year--except for years that are exactly divisible by 100. The centurial years are also leap years if they're exactly divisible by 400. + +A leap year bug occurs when software doesn't account for this leap year logic, or uses flawed logic. The can affect reliability, availability, or even the security of the affected system. + +It isn't safe to add or subtract some number to or from the year, month, or day field of a date-time object without taking leap years into account. This calculation is commonly performed to determine the expiration date for a certificate, for example. On many dates, a naive calculation may produce the desired result. However, when the result is February 29 (a leap day) and the year isn't a leap year, the result is invalid. + +For example, adding a year to 2020-01-31 produces 2021-01-31. But adding a year to 2020-02-29 produces 2021-02-29, which isn't a valid date because 2021 isn't a leap year. + +Be cautious when manipulating variables that represent date values. Handle leap years and leap days properly, or use an API or library that handles date arithmetic safely. + +Code analysis name: `DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK` + +## Example + +The following code advances the system time by a year by incrementing the year field of the date-time object representing the system time. However, it can produce an invalid date-time object if the date was February 29 before the modification, because the next year isn't a leap year: + +```cpp +SYSTEMTIME st; +GetSystemTime(&st); +st.wYear++; // warning C26861 +``` + +To avoid creating an invalid date-time object due to a leap year, check if the resulting date is still valid and make the necessary adjustments to make it valid, as in this example: + +```cpp +SYSTEMTIME st; +GetSystemTime(&st); +st.wYear++; +if (st.wMonth == 2 && st.wDay == 29) +{ + // move back a day when landing on Feb 29 in a non-leap year + bool isLeapYear = st.wYear % 4 == 0 && (st.wYear % 100 != 0 || st.wYear % 400 == 0); + if (!isLeapYear) + { + st.wDay = 28; + } +} +``` + +## Heuristics + +Currently, this rule only recognizes the Windows `SYSTEMTIME` struct and C `tm` struct. + +This rule employs a simplified heuristic to find potentially risky changes and reports warnings unless there's appropriate leap year or leap day checking. It doesn't try to verify if the leap year or leap day checking is performed correctly for the modified date-time object. + +This rule is an opt-in rule, which means that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see: [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md). + +## See also + +[C6393](c6393.md)\ +[C6394](c6394.md)\ +[C26862](c26862.md)\ +[C26863](c26863.md)\ +[C26864](c26864.md) diff --git a/docs/code-quality/c26862.md b/docs/code-quality/c26862.md new file mode 100644 index 0000000000..f56e78753c --- /dev/null +++ b/docs/code-quality/c26862.md @@ -0,0 +1,64 @@ +--- +description: "Learn more about: Warning C26862" +title: Warning C26862 +ms.date: 11/29/2023 +f1_keywords: ["C26862", "INCOMPLETE_DATETIME_CONVERSION", "__WARNING_INCOMPLETE_DATETIME_CONVERSION"] +helpviewer_keywords: ["C26862"] +--- +# Warning C26862 + +> A date-time object `var` has been created from a different type of date-time object but conversion was incomplete: `expr` + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +Proper enforcement of leap year and leap day handling rules require tracking the proper conversion between date-time objects of different types such as the Windows `SYSTEMTIME` struct and the C `tm` struct. Different date-time types may have different bases for the year, month, and day fields. For example, `SYSTEMTIME` has a 0-based year, but 1-based month and day fields. On the other hand, `tm` has a 1900-based year, a 0-based month, and a 1-based day fields. To convert an object of one of these types to an object of another type, the year, month, and day fields must be adjusted appropriately. + +Code analysis name: `INCOMPLETE_DATETIME_CONVERSION` + +## Example + +The following code tries to convert an instance of `tm` into an instance of `SYSTEMTIME`. It makes the necessary adjustment to the year field, but doesn't properly adjust the month field: + +```cpp +#include +#include + +void ConvertTmToSystemTime1b(const tm& tm) +{ + SYSTEMTIME st; + st.wYear = tm.tm_year + 1900; + st.wMonth = tm.tm_mon; // C26862, Adjustment is missing + st.wDay = tm.tm_mday; +} +``` + +To fix this problem, adjust the month and year fields: + +```cpp +#include +#include + +void ConvertTmToSystemTime(const tm& tm) +{ + SYSTEMTIME st; + st.wYear = tm.tm_year + 1900; + st.wMonth = tm.tm_mon + 1; + st.wDay = tm.tm_mday; +} +``` + +## Heuristics + +This rule only recognizes the Windows `SYSTEMTIME` struct and the C `tm` struct. + +This rule is an opt-in rule, meaning that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md). + +## See also + +[C6393](c6393.md)\ +[C6394](c6394.md)\ +[C26861](c26861.md)\ +[C26863](c26863.md)\ +[C26864](c26864.md) diff --git a/docs/code-quality/c26863.md b/docs/code-quality/c26863.md new file mode 100644 index 0000000000..169368c8df --- /dev/null +++ b/docs/code-quality/c26863.md @@ -0,0 +1,83 @@ +--- +description: "Learn more about: Warning C26863" +title: Warning C26863 +ms.date: 11/29/2023 +f1_keywords: ["C26863", "DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED", "__WARNING_DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED"] +helpviewer_keywords: ["C26863"] +--- +# Warning C26863 + +> Return value from a date-time handling function `func` is ignored + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +It's important to verify the return value of a function that transforms a date structure when the year, month, or date input argument was manipulated without proper leap year handling. Otherwise, the function may have failed and execution continues with an output parameter containing invalid data. + +The following is a list of the functions that this warning covers: + +- [`FileTimeToSystemTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-filetimetosystemtime) +- [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime) +- [`SystemTimeToTzSpecificLocalTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetotzspecificlocaltime) +- [`SystemTimeToTzSpecificLocalTimeEx`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetotzspecificlocaltimeex) +- [`TzSpecificLocalTimeToSystemTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime) +- [`TzSpecificLocalTimeToSystemTimeEx`](/windows/win32/api/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex) +- [`RtlLocalTimeToSystemTime`](/windows/win32/api/winternl/nf-winternl-rtllocaltimetosystemtime) +- [`RtlTimeToSecondsSince1970`](/windows/win32/api/winternl/nf-winternl-rtltimetosecondssince1970) + +Code analysis name: `DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED` + +## Example + +The following code tries to get current system time, advance the month field by one month, and get the file time that corresponds to the updated system time via [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime). However, [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime) might fail, as the updated system time may become invalid: + +```cpp +#include + +void foo() +{ + FILETIME ft; + SYSTEMTIME st; + GetSystemTime(&st); + st.wMonth++; // Advance month by one + // Get the file time + SystemTimeToFileTime(&st, &ft); // C26863 +} +``` + +To fix the problem, always check the return value from date-time manipulation functions and handle failures appropriately: + +```cpp +#include + +void foo() +{ + FILETIME ft; + SYSTEMTIME st; + GetSystemTime(&st); + + st.wMonth++; // Advance month by one + // Get file time + if (SystemTimeToFileTime(&st, &ft)) + { + // Use file time + } +} +``` + +## Heuristics + +This rule only recognizes the Windows `SYSTEMTIME` struct and the C `tm` struct. + +This rule is enforced regardless of whether the input arguments were validated before calling these functions. If all the input arguments are validated before calling the function, this rule can report false warning. + +This rule is an opt-in rule, meaning that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md). + +## See also + +[C6393](c6393.md)\ +[C6394](c6394.md)\ +[C26861](c26861.md)\ +[C26862](c26862.md)\ +[C26864](c26864.md) diff --git a/docs/code-quality/c26864.md b/docs/code-quality/c26864.md new file mode 100644 index 0000000000..0df5d94644 --- /dev/null +++ b/docs/code-quality/c26864.md @@ -0,0 +1,83 @@ +--- +description: "Learn more about: Warning C26864" +title: Warning C26864 +ms.date: 11/29/2023 +f1_keywords: ["C26864", "DATETIME_MANIPULATION_ASSUMING_365_DAYS_WITHOUT_LEAPYEAR_CHECK", "__WARNING_DATETIME_MANIPULATION_ASSUMING_365_DAYS_WITHOUT_LEAPYEAR_CHECK"] +helpviewer_keywords: ["C26864"] +--- +# Warning C26864 + +> Day field of a date-time object `var` has been modified assuming 365 days per year without proper leap year checking: `expr` + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +In the Gregorian calendar, every year exactly divisible by four is a leap year--except for years that are exactly divisible by 100. The centurial years are also leap years if they're exactly divisible by 400. + +A leap year bug occurs when software doesn't account for this leap year logic, or uses flawed logic. The can affect reliability, availability, or even the security of the affected system. + +You must take leap years into account when you perform arithmetic operations on a variable that represents a date. It's not safe to assume that a year is 365 days long. A leap year has 366 days because of the 'leap day' added as a 29th day in February. + +To correctly advance a year, determine whether the time span contains a leap day, then perform the calculation using the correct number of days. It's better if the year is directly advanced, with an appropriate leap day check on the resulting date. Alternatively, use an established library routine that handles leap years correctly. + +Code analysis name: `DATETIME_MANIPULATION_ASSUMING_365_DAYS_WITHOUT_LEAPYEAR_CHECK` + +## Example + +The following code tries to get current system time, advance the day by one year by adding 365 days to the day field, and adjusting the date per leap year rule. However, the result may not fall on the same month/date of the next year: + +```cpp +#include + +void foo() +{ + SYSTEMTIME st; + + GetSystemTime(&st); + + // Advance a year by adding 365 days + st.wDay += 365; // C26864 +} +``` + +To fix this problem, advance the year field directly and adjust the date per the leap year rule: + +```cpp +#include + +void foo() +{ + SYSTEMTIME st; + GetSystemTime(&st); + + st.wYear++; // Advance a year + + // Adjust the date + if (st.wMonth == 2 && st.wDay == 29) + { + // Move back a day when landing on Feb 29 in a non-leap year + bool isLeapYear = st.wYear % 4 == 0 && (st.wYear % 100 != 0 || st.wYear % 400 == 0); + if (!isLeapYear) + { + st.wDay = 28; + } + } +} +``` + +## Heuristics + +This rule only recognizes the Windows `SYSTEMTIME` struct and C `tm` struct. + +This rule is enforced if the date field is directly modified by 365 days. It doesn't consider if the value of date field is assigned to another variable and then manipulated, and so can miss equivalent mistakes. + +This rule is an opt-in rule, meaning that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md). + +## See also + +[C6393](c6393.md)\ +[C6394](c6394.md)\ +[C26861](c26861.md)\ +[C26862](c26862.md)\ +[C26863](c26863.md) diff --git a/docs/code-quality/c28020.md b/docs/code-quality/c28020.md index e94476bc7d..927e462bda 100644 --- a/docs/code-quality/c28020.md +++ b/docs/code-quality/c28020.md @@ -1,16 +1,32 @@ --- -description: "Learn more about: C28020" -title: C28020 -ms.date: 11/04/2016 -ms.topic: reference +title: Warning C28020 +description: "Learn more about: Warning C28020" +ms.date: 03/25/2025 f1_keywords: ["C28020"] helpviewer_keywords: ["C28020"] -ms.assetid: 3612185a-0858-4ba9-b795-4a0681073cf7 --- -# C28020 +# Warning C28020 -> warning C28020: The expression \ is not true at this call +> The expression '*expr*' is not true at this call. -This warning is reported when the \_Satisfies\_ expression listed is not true. Frequently this indicates an incorrect parameter. +This warning is reported when the `_Satisfies_` expression listed isn't true. Frequently, the warning indicates an incorrect parameter. -If this occurs on a function declaration, the annotations indicate an impossible condition. +If this warning occurs on a function declaration, the annotations indicate an impossible condition. + +## Example + +The following example generates C28020: + +```cpp +#include + +int func(_In_range_(0, 10) int value) +{ + return value; +} + +int main() +{ + func(11); // C28020 +} +``` diff --git a/docs/code-quality/c28021.md b/docs/code-quality/c28021.md index d5162d3e0c..bb8b0d3657 100644 --- a/docs/code-quality/c28021.md +++ b/docs/code-quality/c28021.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28021" -title: C28021 +description: "Learn more about: Warning C28021" +title: Warning C28021 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28021"] helpviewer_keywords: ["C28021"] ms.assetid: 4cc205d2-d44d-4d44-9ece-0a4673617096 --- -# C28021 +# Warning C28021 -> warning C28021: The parameter \ being annotated with \ must be a pointer +> The parameter '*param*' being annotated with '*annotation*' must be a pointer -This warning is reported when the object being annotated is not a pointer type. This annotation cannot be used with **`void`** or integral types. +This warning is reported when the object being annotated is not a pointer type. This annotation can't be used with **`void`** or integral types. diff --git a/docs/code-quality/c28022.md b/docs/code-quality/c28022.md index 22ff0d3a26..ebc089c6bc 100644 --- a/docs/code-quality/c28022.md +++ b/docs/code-quality/c28022.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28022" -title: C28022 +description: "Learn more about: Warning C28022" +title: Warning C28022 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28022"] helpviewer_keywords: ["C28022"] ms.assetid: 9cef31e0-54f3-4b56-8c97-abb0ea1b98f7 --- -# C28022 +# Warning C28022 -> warning C28022: The function class(es) \ on this function do not match the function class(es) \ on the typedef used to define it. +> The function class(es) '*classlist1*' on this function do not match the function class(es) '*classlist2*' on the typedef used to define it. -This warning is reported when there is an error in the annotations. Both the typedef and the function itself have `_Function_class_` annotations, but they do not match. If both are used they must match. +This warning is reported when there's an error in the annotations. Both the typedef and the function itself have `_Function_class_` annotations, but they don't match. If both are used, they must match. diff --git a/docs/code-quality/c28023.md b/docs/code-quality/c28023.md index 52cc502958..4daf46bd60 100644 --- a/docs/code-quality/c28023.md +++ b/docs/code-quality/c28023.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28023" -title: C28023 +description: "Learn more about: Warning C28023" +title: Warning C28023 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28023"] helpviewer_keywords: ["C28023"] ms.assetid: c59986a8-8712-4d58-b415-ec08b4daf66f --- -# C28023 +# Warning C28023 -> warning C28023: The function being assigned or passed should have a `_Function_class_` annotation for at least one of the class(es) in: \ +> The function being assigned or passed should have a `_Function_class_` annotation for at least one of the class(es) in: '*classlist*' -This warning is usually reported when only one function class is in use and a callback of the appropriate type is not declared. +This warning is often reported when only one function class is in use and a callback of the appropriate type isn't declared. -This warning is issued when the function on the left side of the assignment (or of the implied assignment, if this is a function call) is annotated to indicate that it is a driver-specific function type that uses the `_Function_class_` annotation or a typedef that contains such an annotation. The function on the right side of the assignment does not have a `_Function_class_` annotation. The function on the right should be annotated to be of the same type as the function on the left. This is usually best done by adding the declaration \ \ before the current first declaration of \. +This warning is issued when the function on the left side of the assignment (or of the implied assignment, if it's a function call) is annotated to indicate that it's a driver-specific function type that uses the `_Function_class_` annotation, or a typedef that contains such an annotation. The function on the right side of the assignment doesn't have a `_Function_class_` annotation. The function on the right should be annotated to be of the same type as the function on the left. Often the best approach is to place the declaration \ \ before the current first declaration of \. diff --git a/docs/code-quality/c28024.md b/docs/code-quality/c28024.md index e6ab50209a..d99fce5b37 100644 --- a/docs/code-quality/c28024.md +++ b/docs/code-quality/c28024.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28024" -title: C28024 +description: "Learn more about: Warning C28024" +title: Warning C28024 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28024"] helpviewer_keywords: ["C28024"] ms.assetid: b74fad50-0a2e-43d7-ba5e-e9432aa9f7c8 --- -# C28024 +# Warning C28024 -> warning C28024: The function pointer being assigned to is annotated with the function class \, which is not contained in the function class(es) \. +> The function pointer being assigned to is annotated with the function class '*class*', which is not contained in the function class(es) '*classlist*'. -This warning is reported when both functions were annotated with a function class, but the classes do not match. +This warning is reported when both functions were annotated with a function class, but the classes don't match. -this warning is issued when a function pointer has a `_Function_class_` annotation that specifies that only functions of a particular functional class should be assigned to it. In an assignment or implied assignment in a function call, the source and target must be of the same function class, but the function classes do not match. +This warning is issued when a function pointer has a `_Function_class_` annotation that specifies that only functions of a particular functional class should be assigned to it. In an assignment or implied assignment in a function call, the source and target must be of the same function class, but the function classes don't match. diff --git a/docs/code-quality/c28039.md b/docs/code-quality/c28039.md index c58ae3a9b3..cd7fabc682 100644 --- a/docs/code-quality/c28039.md +++ b/docs/code-quality/c28039.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28039" -title: C28039 +description: "Learn more about: Warning C28039" +title: Warning C28039 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28039"] helpviewer_keywords: ["C28039"] ms.assetid: 36cd63fe-1f0a-4f1c-a40b-5d52e22f19b3 --- -# C28039 +# Warning C28039 -> warning C28039: The type of actual parameter \ should exactly match the type \ +> The type of actual parameter '*operand*' should exactly match the type '*typename*' -This warning is usually reported when an enum formal was not passed a member of the enum, but may also be used for other types. +This warning is reported when an `enum` formal wasn't passed a member of the `enum`, but may also be used for other types. -Because C permits enums to be used interchangeably, and interchangeably with constants, it is easy to pass the wrong enum value to a function without an error. +Because C permits `enum` types to be used interchangeably, and interchangeably with constants, it's easy to pass the wrong `enum` value to a function without an error. -For enum types, if the type of an enum parameter is annotated with `_Enum_is_bitflag_`, arithmetic is permitted on the parameter. Otherwise the parameter must be of exactly the correct type. If a constant is strictly required, warning C28137 may also apply. +For `enum` types, if the type of an `enum` parameter is annotated with `_Enum_is_bitflag_`, arithmetic is permitted on the parameter. Otherwise the parameter must be of exactly the correct type. If a constant is strictly required, warning C28137 may also apply. This rule can be used for other parameter types as well; see the function documentation for why the types must match exactly. diff --git a/docs/code-quality/c28103.md b/docs/code-quality/c28103.md index dd3dc8e423..0385a09b5e 100644 --- a/docs/code-quality/c28103.md +++ b/docs/code-quality/c28103.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28103" -title: C28103 +description: "Learn more about: Warning C28103" +title: Warning C28103 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28103"] helpviewer_keywords: ["C28103"] ms.assetid: e39c464d-1049-4ff4-a62b-9cad9d3f6fee --- -# C28103 +# Warning C28103 -> warning C28103: Leaking resource +> Leaking resource -The specified object contains a resource that has not been freed. A function being called has been annotated with `__drv_acquiresResource` or `__drv_acquiresResourceGlobal` and this warning indicates that the resource named in the annotation was not freed. +The specified object contains a resource that hasn't been freed. A function being called has been annotated with `__drv_acquiresResource` or `__drv_acquiresResourceGlobal` and this warning indicates that the resource named in the annotation wasn't freed. ## Example @@ -31,4 +30,4 @@ if (NT_SUCCESS(res)) } ``` -If this warning is reported as a false positive, the most likely cause is that the function that releases the resource is not annotated with `__drv_releasesResource` or `__drv_releasesResourceGlobal`. Note that if you are using wrapper functions for system functions, the wrapper functions should use the same annotations that the system functions do. Currently, many system functions are annotated in the model file, so the annotations are not visible in the header files. +If this warning is reported as a false positive, the most likely cause is that the function that releases the resource isn't annotated with `__drv_releasesResource` or `__drv_releasesResourceGlobal`. If you're using wrapper functions for system functions, the wrapper functions should use the same annotations that the system functions do. Currently, many system functions are annotated in the model file, so the annotations aren't visible in the header files. diff --git a/docs/code-quality/c28104.md b/docs/code-quality/c28104.md index 36a6681efc..cc2b632cfe 100644 --- a/docs/code-quality/c28104.md +++ b/docs/code-quality/c28104.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28104" -title: C28104 +description: "Learn more about: Warning C28104" +title: Warning C28104 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28104"] helpviewer_keywords: ["C28104"] ms.assetid: 0dda7e70-7c63-4b6b-a3fc-adad0815f7f4 --- -# C28104 +# Warning C28104 -> warning C28104: Resource that should have been acquired before function exit was not acquired +> Resource that should have been acquired before function exit was not acquired -A function that is intended to acquire a resource before it exits has exited without acquiring the resource. This warning indicates that the function is annotated with `__drv_acquiresResource` but does not return having actually acquired the resource. If this function is a wrapper function, a path through the function did not reach the wrapped function. If the failure to reach the wrapped function is because the function returned an error and did not actually acquire the resource, you might need to use a conditional annotation (`__drv_when`). +A function that is intended to acquire a resource before it exits has exited without acquiring the resource. This warning indicates that the function is annotated with `__drv_acquiresResource` but doesn't return having actually acquired the resource. If this function is a wrapper function, a path through the function didn't reach the wrapped function. If the failure to reach the wrapped function is because the function returned an error and didn't actually acquire the resource, you might need to use a conditional annotation (`__drv_when`). -If this function actually implements the acquisition of the resource, it might not be possible for PFD to detect that the resource is acquired. In that case, use a `#pragma` warning to suppress the error. You can probably place the `#pragma` on the line preceding the `{` that begins the function body. The calling functions still need the annotation, but the Code Analysis tool will not be able to detect that the resource was acquired. +If this function actually implements the acquisition of the resource, it might not be possible for PFD to detect that the resource is acquired. In that case, use a `#pragma` warning to suppress the error. You can probably place the `#pragma` on the line preceding the `{` that begins the function body. The calling functions still need the annotation, but the Code Analysis tool won't be able to detect that the resource was acquired. ## Example diff --git a/docs/code-quality/c28105.md b/docs/code-quality/c28105.md index 7cb9f24835..defa523432 100644 --- a/docs/code-quality/c28105.md +++ b/docs/code-quality/c28105.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28105" -title: C28105 +description: "Learn more about: Warning C28105" +title: Warning C28105 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28105"] helpviewer_keywords: ["C28105"] ms.assetid: 5afdec78-30eb-470c-980f-93d0cb3e74cc --- -# C28105 +# Warning C28105 -> warning C28105: Leaking resource due to an exception +> Leaking resource due to an exception -The specified resource is not freed when an exception is raised. The statement specified by the path can raise an exception. This warning is similar to warning [C28103](../code-quality/c28103.md), except that in this case an exception is involved. +The specified resource isn't freed when an exception is raised. The statement specified by the path can raise an exception. This warning is similar to warning [C28103](../code-quality/c28103.md), except that in this case an exception is involved. ## Example diff --git a/docs/code-quality/c28106.md b/docs/code-quality/c28106.md index d99f64db6e..4cad2d6efb 100644 --- a/docs/code-quality/c28106.md +++ b/docs/code-quality/c28106.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28106" -title: C28106 +description: "Learn more about: Warning C28106" +title: Warning C28106 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28106"] helpviewer_keywords: ["C28106"] ms.assetid: 362ee78e-b1d8-4991-bfd0-c465d084bd58 --- -# C28106 +# Warning C28106 -> warning C28106: Variable already holds resource possibly causing leak +> Variable already holds resource possibly causing leak -A variable that contains a resource is used in a context in which a new value can be placed in the variable. If this occurs, the resource can be lost and not properly freed, causing a resource leak. +A variable that contains a resource is used in a context in which a new value can be placed in the variable. If such placement occurs, the original resource can be lost and not properly freed, causing a resource leak. ## Example diff --git a/docs/code-quality/c28107.md b/docs/code-quality/c28107.md index 3e1deff100..4ccb0d2aa0 100644 --- a/docs/code-quality/c28107.md +++ b/docs/code-quality/c28107.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28107" -title: C28107 +description: "Learn more about: Warning C28107" +title: Warning C28107 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28107"] helpviewer_keywords: ["C28107"] ms.assetid: aa8158be-d3f4-4e7e-918b-b04a910ce658 --- -# C28107 +# Warning C28107 -> warning C28107: Resource must be held when calling function +> Resource must be held when calling function -A resource that the program must acquire before calling the function was not acquired when the function was called. As a result, the function call will fail. This warning is reported only when resources are acquired and released in the same function. +A resource that the program must acquire before calling the function wasn't acquired when the function was called. As a result, the function call will fail. This warning is reported only when resources are acquired and released in the same function. ## Example diff --git a/docs/code-quality/c28108.md b/docs/code-quality/c28108.md index ca0ffd3106..c9df1a23cd 100644 --- a/docs/code-quality/c28108.md +++ b/docs/code-quality/c28108.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28108" -title: C28108 +description: "Learn more about: Warning C28108" +title: Warning C28108 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28108"] helpviewer_keywords: ["C28108"] ms.assetid: 6b931114-640e-43ea-b781-cd256e9163c7 --- -# C28108 +# Warning C28108 -> warning C28108: Variable holds an unexpected resource +> Variable holds an unexpected resource The resource that the driver is using is in the expected C language type, but has a different semantic type. diff --git a/docs/code-quality/c28109.md b/docs/code-quality/c28109.md index 6a39e9d6b0..05c8bf6f3b 100644 --- a/docs/code-quality/c28109.md +++ b/docs/code-quality/c28109.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28109" -title: C28109 +description: "Learn more about: Warning C28109" +title: Warning C28109 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28109"] helpviewer_keywords: ["C28109"] ms.assetid: 32e4a493-8a51-4b27-b599-6271cd8d834a --- -# C28109 +# Warning C28109 -> warning C28109: Variable cannot be held at the time function is called +> Variable cannot be held at the time function is called -The program is holding a resource that should not be held when it is calling this function. Typically, it indicates that the resource was unintentionally acquired twice. The Code Analysis tool reports this warning when resources are acquired and released in the same function. +The program is holding a resource that shouldn't be held when it's calling this function. Typically, it indicates that the resource was unintentionally acquired twice. The Code Analysis tool reports this warning when resources are acquired and released in the same function. ## Example diff --git a/docs/code-quality/c28112.md b/docs/code-quality/c28112.md index 44278db5a4..530ab51bc0 100644 --- a/docs/code-quality/c28112.md +++ b/docs/code-quality/c28112.md @@ -1,34 +1,41 @@ --- -description: "Learn more about: C28112" -title: C28112 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28112"] +title: Warning C28112 +description: "Learn more about: Warning C28112" +ms.date: 08/25/2022 +f1_keywords: ["C28112", "INTERLOCKED_ACCESS", "__WARNING_INTERLOCKED_ACCESS"] helpviewer_keywords: ["C28112"] -ms.assetid: 2720a5dc-84e9-4f78-a8c7-a320c9f9216b --- -# C28112 +# Warning C28112 -> warning C28112: A variable which is accessed via an Interlocked function must always be accessed via an Interlocked function +> A variable (*parameter-name*) which is accessed via an Interlocked function must always be accessed via an Interlocked function. See line *line-number*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way. -See line *[number]*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way. +A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. -A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance. +## Remarks + +`InterlockedXxx` functions are intended to provide atomic operations, but are only atomic with respect to other `InterlockedXxx` functions. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance. + +Code analysis name: `INTERLOCKED_ACCESS` ## Example -The following code example generates this warning: +The following code generates this warning: ```cpp -inter_var --; -... +inter_var--; +//code InterlockedIncrement(&inter_var); ``` -The following code example avoids this warning: +The following code corrects this warning by strictly accessing `inter_var` through `InterlockedXxx` functions: ```cpp InterlockedDecrement(&inter_var); -... +//code InterlockedIncrement(&inter_var); ``` + +## See Also + +[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement)\ +[InterlockedDecrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockeddecrement) diff --git a/docs/code-quality/c28113.md b/docs/code-quality/c28113.md index 6b43e2ebba..984d5cf84f 100644 --- a/docs/code-quality/c28113.md +++ b/docs/code-quality/c28113.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: C28113" -title: C28113 +description: "Learn more about: Warning C28113" +title: Warning C28113 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28113"] helpviewer_keywords: ["C28113"] ms.assetid: c3f4f143-6985-4274-a87a-59c21a82d67a --- -# C28113 +# Warning C28113 -> warning C28113: Accessing a local variable via an Interlocked function +> Accessing a local variable via an Interlocked function The driver is using an Interlocked executive support routine, such as [InterlockedDecrement](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-interlockeddecrement), to access a local variable. -Although drivers are permitted to pass the address of a local variable to another function, and then use an interlocked function to operate on that variable, it's important to verify that the stack will not be swapped out to disk unexpectedly and that the variable has the correct life time across all threads that might use it. +Although drivers are permitted to pass the address of a local variable to another function, and then use an interlocked function to operate on that variable, it's important to verify that the stack won't be swapped out to disk unexpectedly and that the variable has the correct life time across all threads that might use it. ## Example -Typically, the return value of an Interlocked executive support routine is used in subsequent computations, instead of the input arguments. Also, the Interlocked routines only protect the first (leftmost) argument. Using an Interlocked routine in the following way does not protect the value of global and often serves no purpose. +Typically, the return value of an Interlocked executive support routine is used in subsequent computations, instead of the input arguments. Also, the Interlocked routines only protect the first (leftmost) argument. Using an Interlocked routine in the following way doesn't protect the value of global and often serves no purpose. ```cpp InterlockedExchange(&local, global) diff --git a/docs/code-quality/c28125.md b/docs/code-quality/c28125.md index 6027db0c13..05ccc90635 100644 --- a/docs/code-quality/c28125.md +++ b/docs/code-quality/c28125.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28125" -title: C28125 +description: "Learn more about: Warning C28125" +title: Warning C28125 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28125"] helpviewer_keywords: ["C28125"] ms.assetid: 3f7b8db4-6a64-4480-919e-3f3ceca7f948 --- -# C28125 +# Warning C28125 -> warning C28125: The function must be called from within a try/except block +> The function must be called from within a try/except block -The driver is calling a function that must be called from within a try/except block, such as [ProbeForRead](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforread), [ProbeForWrite](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforwrite), [MmProbeAndLockPages](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-mmprobeandlockpages). +The driver is calling a function that must be called from within a try/except block, such as [`ProbeForRead`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforread), [`ProbeForWrite`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforwrite), or [`MmProbeAndLockPages`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-mmprobeandlockpages). ## Example diff --git a/docs/code-quality/c28137.md b/docs/code-quality/c28137.md index f4237d177b..5696900588 100644 --- a/docs/code-quality/c28137.md +++ b/docs/code-quality/c28137.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28137" -title: C28137 +description: "Learn more about: Warning C28137" +title: Warning C28137 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28137"] helpviewer_keywords: ["C28137"] ms.assetid: 34420007-6a73-4f09-bdf7-8d923eef9654 --- -# C28137 +# Warning C28137 -> warning C28137: The variable argument should instead be a (literal) constant +> The variable argument should instead be a (literal) constant This warning is reported when a function call is missing a required (literal) constant. Consult the documentation for the function. diff --git a/docs/code-quality/c28138.md b/docs/code-quality/c28138.md index bc8db136a3..03614ce446 100644 --- a/docs/code-quality/c28138.md +++ b/docs/code-quality/c28138.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28138" -title: C28138 +description: "Learn more about: Warning C28138" +title: Warning C28138 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28138"] helpviewer_keywords: ["C28138"] ms.assetid: d8c455db-1fa0-426c-9846-545f1dfe57bd --- -# C28138 +# Warning C28138 -> warning C28138: The constant argument should instead be variable +> The constant argument should instead be variable This warning is reported in a function call that expects a variable or a non-constant expression, but the call includes a constant. For information about the function and its parameter, consult the WDK documentation of the function. @@ -29,4 +28,4 @@ To correct this warning, use a pointer to the port address. READ_PORT_UCHAR(PortAddress); ``` -There are a few older devices for which a constant parameter is acceptable with the READ_PORT and WRITE_PORT family of functions. When those devices receive this warning, the warning can be suppressed or ignored. However, any new devices should not assume a constant hardware address. +There are a few older devices for which a constant parameter is acceptable with the READ_PORT and WRITE_PORT family of functions. When those devices receive this warning, the warning can be suppressed or ignored. However, any new devices shouldn't assume a constant hardware address. diff --git a/docs/code-quality/c28159.md b/docs/code-quality/c28159.md index 99eb40a523..05fbe31944 100644 --- a/docs/code-quality/c28159.md +++ b/docs/code-quality/c28159.md @@ -1,34 +1,34 @@ --- -description: "Learn more about: C28159" -title: C28159 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28159"] +title: Warning C28159 +description: "Learn more about: Warning C28159" +ms.date: 09/08/2022 +f1_keywords: ["C28159", "USE_OTHER_FUNCTION", "__WARNING_USE_OTHER_FUNCTION"] helpviewer_keywords: ["C28159"] -ms.assetid: fab6cd58-0985-4ef6-89a2-64ed04297437 --- -# C28159 +# Warning C28159 -> warning C28159: Consider using another function instead. +> Consider using *`function_name_1`* instead of *`function_name_2`*. Reason: *reason* -This warning is reported for Drivers is suggesting that you use a preferred function call that is semantically equivalent to the function that the driver is calling. This is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional a `__drv_when`() annotation) to flag a bad coding practice. +This warning occurs when you use a function that is semantically equivalent to an alternative, preferred function call. + +## Remarks + +C28159 is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional `__drv_when`() annotation) to flag a bad coding practice. + +Code analysis name: `USE_OTHER_FUNCTION` ## Example -The following code example generates this warning: +The following code example generates this warning. This issue is due to the use of `OemToChar`, which doesn't validate the buffer size: ```cpp char buff[MAX_PATH]; - -// if strlen(input) > MAX_PATH -// leads to buffer overrun -OemToChar(buff, input); +OemToChar(buff, input); // If strlen(input) > MAX_PATH, this call leads to buffer overrun ``` -The following code example avoids this warning: +The following code example avoids this warning by using the recommended alternative `OemToCharBuff`, which takes in the destination buffer size and limits the copy appropriately: ```cpp char buff[MAX_PATH]; - OemToCharBuff(buff, input, MAX_PATH); ``` diff --git a/docs/code-quality/c28160.md b/docs/code-quality/c28160.md index 682724e3ca..eeee7046da 100644 --- a/docs/code-quality/c28160.md +++ b/docs/code-quality/c28160.md @@ -1,14 +1,18 @@ --- -description: "Learn more about: C28160" -title: C28160 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28160"] +title: Warning C28160 +description: "Learn more about: Warning C28160" +ms.date: 09/08/2022 +f1_keywords: ["C28160", "ERROR", "__WARNING_ERROR"] helpviewer_keywords: ["C28160"] -ms.assetid: cab15f6b-909c-4cc8-81a0-c24ac7c91c7c --- -# C28160 +# Warning C28160 -> warning C28160: Error annotation +> Error annotation: *reason* -This warning is reported when a `__drv_error` annotation has been encountered. This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters. +This warning is reported when a `__drv_error` annotation has been encountered. + +## Remarks + +This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters. + +Code analysis name: `ERROR` diff --git a/docs/code-quality/c28163.md b/docs/code-quality/c28163.md index 5ba3fb4600..365185fab7 100644 --- a/docs/code-quality/c28163.md +++ b/docs/code-quality/c28163.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28163" -title: C28163 +description: "Learn more about: Warning C28163" +title: Warning C28163 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28163"] helpviewer_keywords: ["C28163"] ms.assetid: 24fecbde-1c96-4a45-82f7-9f47cfc0ef11 --- -# C28163 +# Warning C28163 -> warning C28163: The function should never be called from within a try/except block +> The function should never be called from within a try/except block This warning is reported when a function is of a type that should never be enclosed in a `try/except` block is found in a `try/except` block. The code analysis tool found at least one path in which the function called was within a `try/except` block. diff --git a/docs/code-quality/c28164.md b/docs/code-quality/c28164.md index 63b9cf0a5b..8a79c33c96 100644 --- a/docs/code-quality/c28164.md +++ b/docs/code-quality/c28164.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C28164" -title: C28164 +description: "Learn more about: Warning C28164" +title: Warning C28164 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28164"] helpviewer_keywords: ["C28164"] ms.assetid: 13327bf3-3f12-4226-85cf-48e215d01c1d --- -# C28164 +# Warning C28164 -> warning C28164: The argument is being passed to a function that expects a pointer to an object (not a pointer to a pointer) +> The argument is being passed to a function that expects a pointer to an object (not a pointer to a pointer) This warning is reported when a pointer to a pointer is used in a call to a function that is expecting a pointer to an object. -The function takes a `PVOID` in this position. Usually, this indicates that `&pXXX` was used when `pXXX` is required. +The function takes a `PVOID` in this position. Usually, it indicates that `&pXXX` was used when `pXXX` is required. -Some *polymorphic functions* (functions that can evaluate to, and be applied to, values of different types) are implemented in C by using a `PVOID` argument that takes any pointer type. However, this allows the programmer to code a pointer to a pointer without causing a compiler error, even when this type is not appropriate. +Some *polymorphic functions* (functions that can evaluate to, and be applied to, values of different types) are implemented in C by using a `PVOID` argument that takes any pointer type. However, this allows the programmer to code a pointer to a pointer without causing a compiler error, even when this type isn't appropriate. ## Example diff --git a/docs/code-quality/c28182.md b/docs/code-quality/c28182.md index e48ff38521..6a2ce93dfe 100644 --- a/docs/code-quality/c28182.md +++ b/docs/code-quality/c28182.md @@ -1,27 +1,26 @@ --- -description: "Learn more about: C28182" -title: C28182 +description: "Learn more about: Warning C28182" +title: Warning C28182 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28182"] helpviewer_keywords: ["C28182"] ms.assetid: efec8b1f-8994-4a09-aaaf-6afaadfde883 --- -# C28182 +# Warning C28182 -> warning C28182: Dereferencing NULL pointer. +> Dereferencing NULL pointer. - **Additional information**: *\* contains the same NULL value as *\* did *\* + **Additional information**: *\* contains the same NULL value as *\* did. *\* The code analysis tool reports this warning when it confirms that the pointer can be NULL. If there are unconfirmed instances where the error might occur earlier in the trace, the code analysis tool adds the line number of the first instance to the warning message so that you can change the code to address all instances. - *\* is confirmed to be potentially NULL. *\* contains the same value as *pointer2* and is being dereferenced. Because these pointers may be at very different places in the code, both are reported so that you can determine why the code analysis tool is reporting this warning. + *\* is confirmed to be potentially NULL. *\* contains the same value as *pointer2* and is being dereferenced. Because these pointers may be at different places in the code, both are reported so that you can determine why the code analysis tool is reporting this warning. If an unconfirmed earlier instance of the condition exists, then *\* is replaced by this text: "See line *\* for an earlier location where this can occur." ## Examples -The following example shows code that could cause the code analysis tool to generate this warning message. In this example, the code analysis tool determines that `pNodeFree` is NULL in the **`if`** statement, and the code path into the body of the **`if`** is taken. However, because `nBlockSize` is potentially zero, the body of the **`for`** statement is not executed and `pNodeFree` is left unmodified. `pNodeFree` is then assigned to `pNode`, and `pNode` is used while a NULL dereference could occur. +The following example shows code that could cause the code analysis tool to generate this warning message. In this example, the code analysis tool determines that `pNodeFree` is NULL in the **`if`** statement, and the code path into the body of the **`if`** is taken. However, because `nBlockSize` is potentially zero, the body of the **`for`** statement isn't executed and `pNodeFree` is left unmodified. `pNodeFree` is then assigned to `pNode`, and `pNode` is used while a NULL dereference could occur. ```cpp typedef struct xlist { diff --git a/docs/code-quality/c28183.md b/docs/code-quality/c28183.md index b1860b1776..157f157111 100644 --- a/docs/code-quality/c28183.md +++ b/docs/code-quality/c28183.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28183" -title: C28183 +description: "Learn more about: Warning C28183" +title: Warning C28183 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28183"] helpviewer_keywords: ["C28183"] ms.assetid: 50519e92-575a-4349-9167-5740f66933bf --- -# C28183 +# Warning C28183 -> warning C28183: The argument could be one value, and is a copy of the value found in the pointer +> The argument could be one value, and is a copy of the value found in the pointer -This warning indicates that this value is unexpected in the current context. This warning usually appears when a `NULL` value is passed as an argument to a function that does not permit it. The value was actually found in the specified variable, and the argument is a copy of that variable. +This warning indicates that this value is unexpected in the current context. This warning usually appears when a `NULL` value is passed as an argument to a function that doesn't permit it. The value was actually found in the specified variable, and the argument is a copy of that variable. -The Code Analysis tool reports this warning at the first point where it can definitively determine that the pointer is `NULL` or that it contains an illegal value. However, it is often the case that the error could actually occur earlier in the trace. When this happens, the Code Analysis tool will also give the line number of the first possible instance -- usually at a location where it could not definitively determine that the warning was appropriate. In those cases, the earlier location where this can occur is appended to the warning message. Typically, a code change should occur at or before that line number, rather than at the point of report. +The Code Analysis tool reports this warning at the first point where it can definitively determine that the pointer is `NULL` or that it contains an illegal value. However, it's often the case that the error could actually occur earlier in the trace. When it happens, the Code Analysis tool will also give the line number of the first possible instance, usually at a location where it couldn't definitively determine that the warning was appropriate. In those cases, the earlier location where it can occur is appended to the warning message. Typically, a code change should occur at or before that line number, rather than at the point of report. ## Example diff --git a/docs/code-quality/c28193.md b/docs/code-quality/c28193.md index f5f1f23508..858dad1558 100644 --- a/docs/code-quality/c28193.md +++ b/docs/code-quality/c28193.md @@ -1,25 +1,24 @@ --- -description: "Learn more about: C28193" -title: C28193 +description: "Learn more about: Warning C28193" +title: Warning C28193 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28193"] helpviewer_keywords: ["C28193"] ms.assetid: 1db205f2-618c-4285-98b5-641b3ad8f10f --- -# C28193 +# Warning C28193 -> warning C28193: The variable holds a value that must be examined +> The variable holds a value that must be examined -This warning indicates that the calling function is not checking the value of the specified variable, which was supplied by a function. The returned value is annotated with the `_Check_return_` annotation, but the calling function is either not using the value or is overwriting the value without examining it. +This warning indicates that the calling function isn't checking the value of the specified variable, which was supplied by a function. The returned value is annotated with the `_Check_return_` annotation, but the calling function is either not using the value or is overwriting the value without examining it. -This warning is similar to warning [C6031](../code-quality/c6031.md), but it is reported only when the code does not test or examine the value of the variable, such as by using it in a comparison. Simply assigning the value is not considered to be a sufficient examination to avoid this warning. Aliasing the result out of the function is considered a sufficient examination, but the result itself should be annotated with `_Check_return_`. +This warning is similar to warning [C6031](../code-quality/c6031.md), but it's reported only when the code doesn't test or examine the value of the variable, such as by using it in a comparison. Simply assigning the value isn't considered to be a sufficient examination to avoid this warning. Aliasing the result out of the function is considered a sufficient examination, but the result itself should be annotated with `_Check_return_`. -Certain functions (such as `strlen`) exist almost exclusively for their return value, so it makes sense for them to have the `_Check_return_` annotation. For these functions, the Code Analysis tool might report this warning when the return value is unused. This usually indicates that the code is incorrect, for example, it might contain residual code that could be deleted. However, in some rare instances, the return value is intentionally not used. The most common of these instances is where a string length is returned but not actually used before some other test is made. That other test causes a path to be simulated where the string length ends up being unused. When this happens, the code can be correct, but it might be inefficient. +Certain functions (such as `strlen`) exist almost exclusively for their return value, so it makes sense for them to have the `_Check_return_` annotation. For these functions, the Code Analysis tool might report this warning when the return value is unused. This warning usually indicates that the code is incorrect, for example, it might contain residual code that could be deleted. However, in some rare instances, the return value is intentionally not used. The most common of these instances is where a string length is returned but not actually used before some other test is made. That other test causes a path to be simulated where the string length ends up being unused. When this happens, the code can be correct, but it might be inefficient. There are two primary strategies for dealing with these cases where the return value is unused: -Reorder the code so that the string length is only returned along the path where it is needed. +Reorder the code so that the string length is only returned along the path where it's needed. Use a `#pragma` warning to suppress the warning--if by reordering the code, you would make the code too complex or otherwise less useful. diff --git a/docs/code-quality/c28194.md b/docs/code-quality/c28194.md index 76c040011a..157b9863e7 100644 --- a/docs/code-quality/c28194.md +++ b/docs/code-quality/c28194.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28194" -title: C28194 +description: "Learn more about: Warning C28194" +title: Warning C28194 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28194"] helpviewer_keywords: ["C28194"] ms.assetid: 311c9390-b056-4f6a-a06f-a4aded66df9f --- -# C28194 +# Warning C28194 -> warning C28194: The function was declared as aliasing the value in variable and exited without doing so +> The function was declared as aliasing the value in variable and exited without doing so -This warning indicates that the function prototype for the function being analyzed has a `__drv_isAliased` annotation, which indicates that it will *alias* the specified argument (that is, assign the value in a way that it will survive returning from the function). However, the function does not alias the argument along the path that is indicated by the annotation. Most functions that alias a variable save its value to a global data structure. +This warning indicates that the function prototype for the function being analyzed has a `__drv_isAliased` annotation, which indicates that it will *alias* the specified argument (that is, assign the value in a way that it will survive returning from the function). However, the function doesn't alias the argument along the path that is indicated by the annotation. Most functions that alias a variable save its value to a global data structure. diff --git a/docs/code-quality/c28195.md b/docs/code-quality/c28195.md index 91906d16d7..c89ed73413 100644 --- a/docs/code-quality/c28195.md +++ b/docs/code-quality/c28195.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28195" -title: C28195 +description: "Learn more about: Warning C28195" +title: Warning C28195 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28195"] helpviewer_keywords: ["C28195"] ms.assetid: 89524043-215e-4932-8079-ca2084d32963 --- -# C28195 +# Warning C28195 -> warning C28195: The function was declared as acquiring memory in a variable and exited without doing so +> The function was declared as acquiring memory in a variable and exited without doing so -This warning indicates that the function prototype for the function being analyzed has a `__drv_acquiresMemory` annotation. The `__drv_acquiresMemory` annotation indicates that the function acquires memory in the designated result location, but in at least one path, the function did not acquire the memory. Note that the Code Analysis tool will not recognize the actual implementation of a memory allocator (involving address arithmetic) and will not recognize that memory is allocated (although many wrappers will be recognized). In this case, the Code Analysis tool does not recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` warning on the line that precedes the opening brace `{` of the function body +This warning indicates that the function prototype for the function being analyzed has a `__drv_allocatesMem` annotation. The `__drv_allocatesMem` annotation indicates that the function acquires memory in the designated result location, but in at least one path, the function didn't acquire the memory. The Code Analysis tool won't recognize the actual implementation of a memory allocator (involving address arithmetic) and won't recognize that memory is allocated (although many wrappers will be recognized). In this case, the Code Analysis tool doesn't recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` warning on the line that precedes the opening brace `{` of the function body diff --git a/docs/code-quality/c28196.md b/docs/code-quality/c28196.md index a8571b9fed..388766230a 100644 --- a/docs/code-quality/c28196.md +++ b/docs/code-quality/c28196.md @@ -1,14 +1,53 @@ --- -description: "Learn more about: C28196" -title: C28196 +title: Warning C28196 +description: "Learn more about: Warning C28196" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28196"] +f1_keywords: ["C28196", "RETURNING_BAD_RESULT", "__WARNING_RETURNING_BAD_RESULT"] helpviewer_keywords: ["C28196"] -ms.assetid: 5ee89e96-2796-4316-a64c-702463ca1374 --- -# C28196 +# Warning C28196 -> warning C28196: The requirement is not satisfied. (The expression does not evaluate to true.) +> The requirement is not satisfied. (The expression does not evaluate to true.) -This warning indicates that the function prototype for the function being analyzed has a `__notnull`, `__null` or `__drv_valueIs` on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation. +This warning indicates that the function being analyzed has a `__notnull`, `__null`, `__drv_valueIs` or similar annotation on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation. + +## Remarks + +Annotations like `__notnull` describe invariants about `_Out_` parameters and return values, which serves both as documentation and as a sanity check for the author of the function. Warning C28196 indicates a mismatch between the annotations and the actual behavior of the function. The warning can be useful for discovering cases where a function might behave unexpectedly for certain input values. It's then up to the author to decide what the intended behavior of the function is and either adapt the annotations or the implementation accordingly. + +## Examples + +The following function causes warning C28196 because it's annotated with `_Ret_notnull_` even though some code paths return a null pointer. + +```cpp +#include + +_Ret_notnull_ +Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) { + if (index >= len) { + return nullptr; + } + + return items + index; +} +``` + +To resolve this issue, refine the annotation to accurately reflect the function's behavior. + +```cpp +#include + +_When_(index < len, _Ret_notnull_) +Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) { + if (index >= len) { + return nullptr; + } + + return items + index; +} +``` + +## See also + +[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md)\ +[Specifying When and Where an Annotation Applies](./specifying-when-and-where-an-annotation-applies.md) diff --git a/docs/code-quality/c28197.md b/docs/code-quality/c28197.md index 13b11f6295..0688cd6846 100644 --- a/docs/code-quality/c28197.md +++ b/docs/code-quality/c28197.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C28197" -title: C28197 +description: "Learn more about: Warning C28197" +title: Warning C28197 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28197"] helpviewer_keywords: ["C28197"] ms.assetid: b685f4c1-9bd1-4ca3-a2b6-6eb87877b5db --- -# C28197 +# Warning C28197 -> warning C28197: Possibly leaking memory +> Possibly leaking memory This warning is reported for both memory and resource leaks when the resource is potentially aliased to another location. -The *pointer* points to allocated memory or to another allocated resource that was not explicitly freed. This warning is usually due to inadequate annotations on the called function, although inadequate annotations on the calling function can also make this more likely. +The *pointer* points to allocated memory or to another allocated resource that wasn't explicitly freed. This warning is usually due to inadequate annotations on the called function, although inadequate annotations on the calling function can also make this warning more likely. -This warning can be reported on function exit if an input argument has a `__drv_freesMem` or `__drv_aliasesMem` annotation. This warning typically indicates either a valid leak or that a function called by the current function needs additional annotation. +This warning can be reported on function exit if an input argument has a `__drv_freesMem` or `__drv_aliasesMem` annotation. This warning typically indicates either a valid leak or that a function called by the current function needs more annotation. In particular, the absence of the basic `_In_` and `_Out_` annotations make this warning fairly likely, although the `__drv_aliasesMem` and `__drv_freesMem` annotations might be needed as well. A false positive is a likely result of a missing `_In_` annotation. diff --git a/docs/code-quality/c28198.md b/docs/code-quality/c28198.md index 89cdde546d..56ee969a23 100644 --- a/docs/code-quality/c28198.md +++ b/docs/code-quality/c28198.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28198" -title: C28198 +description: "Learn more about: Warning C28198" +title: Warning C28198 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28198"] helpviewer_keywords: ["C28198"] ms.assetid: 8bad4acb-712c-43f5-81d1-45d92092d4c5 --- -# C28198 +# Warning C28198 -> warning C28198: Possibly leaking memory due to an exception. +> Possibly leaking memory due to an exception. -This warning indicates that allocated memory is not being freed after an exception is raised. The statement at the end of the path can raise an exception. The memory was passed to a function that might have saved a copy to be freed later. +This warning indicates that allocated memory isn't being freed after an exception is raised. The statement at the end of the path can raise an exception. The memory was passed to a function that might have saved a copy to be freed later. -This warning is very similar to warning [C28197](../code-quality/c28197.md). The annotations that are recommended for use with warning [C28197](../code-quality/c28197.md) can also be used here. +This warning is similar to warning [C28197](../code-quality/c28197.md). The annotations that are recommended for use with warning [C28197](../code-quality/c28197.md) can also be used here. ## Example diff --git a/docs/code-quality/c28199.md b/docs/code-quality/c28199.md index 3a30c2beea..46d9128a79 100644 --- a/docs/code-quality/c28199.md +++ b/docs/code-quality/c28199.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28199" -title: C28199 +description: "Learn more about: Warning C28199" +title: Warning C28199 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28199"] helpviewer_keywords: ["C28199"] ms.assetid: a1f0fb4a-65d6-4bd1-8b4f-8a7ae8c47123 --- -# C28199 +# Warning C28199 -> warning C28199: Using possibly uninitialized memory +> Using possibly uninitialized memory This message indicates that the variable has had its address taken but no assignment to it has been discovered. -The specified variable is being used without being explicitly initialized, but at some point its address was taken, indicating that it might be initialized invisibly to the Code Analysis tool. +The specified variable is used without being explicitly initialized, but at some point its address was taken, indicating that it might be initialized invisibly to the Code Analysis tool. This warning can be mistaken if the variable is initialized outside of the function. -The Code Analysis tool reports this warning on function exit if a parameter has an `_Out_` or `_Inout_` annotation and the variable is not initialized. +The Code Analysis tool reports this warning on function exit if a parameter has an `_Out_` or `_Inout_` annotation and the variable isn't initialized. diff --git a/docs/code-quality/c28202.md b/docs/code-quality/c28202.md index 9c91a1901c..c8dfd3ce57 100644 --- a/docs/code-quality/c28202.md +++ b/docs/code-quality/c28202.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28202" -title: C28202 +description: "Learn more about: Warning C28202" +title: Warning C28202 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28202"] helpviewer_keywords: ["C28202"] ms.assetid: 05abbda7-c656-4f2b-bd4a-93805cf80a77 --- -# C28202 +# Warning C28202 -> warning C28202: Illegal reference to non-static member +> Illegal reference to non-static member -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28203.md b/docs/code-quality/c28203.md index e2a46ab772..33f43345e0 100644 --- a/docs/code-quality/c28203.md +++ b/docs/code-quality/c28203.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28203" -title: C28203 +description: "Learn more about: Warning C28203" +title: Warning C28203 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28203"] helpviewer_keywords: ["C28203"] ms.assetid: 20b98be6-0fc2-4712-9090-41201d80155e --- -# C28203 +# Warning C28203 -> warning C28203: Ambiguous reference to class member. Could be \ or \ +> Ambiguous reference to class member. Could be '*name1*' or '*name2*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28204.md b/docs/code-quality/c28204.md index c33372c726..aba49b5603 100644 --- a/docs/code-quality/c28204.md +++ b/docs/code-quality/c28204.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28204" -title: C28204 +description: "Learn more about: Warning C28204" +title: Warning C28204 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28204"] helpviewer_keywords: ["C28204"] ms.assetid: e614e33f-4ba3-4c68-ae0c-3a667d64b044 --- -# C28204 +# Warning C28204 -> warning C28204: \ : Only one of this overload and the one at \(\) are annotated for \: both or neither must be annotated. +> \ : Only one of this overload and the one at '*filename*'('*line*') are annotated for '*paramname*': both or neither must be annotated. -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28205.md b/docs/code-quality/c28205.md index 28488d2066..59f081c596 100644 --- a/docs/code-quality/c28205.md +++ b/docs/code-quality/c28205.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: C28205" -title: C28205 -ms.date: 11/04/2016 -ms.topic: reference +description: "Learn more about: Warning C28205" +title: Warning C28205 +ms.date: 06/29/2022 f1_keywords: ["C28205"] helpviewer_keywords: ["C28205"] ms.assetid: 3d802885-bdb8-47cb-9108-527a328a0774 --- -# C28205 +# Warning C28205 -> warning C28205: function> : `_Success_` or `_On_failure_` used in an illegal context +> '*function*': `_Success_` or `_On_failure_` used in an illegal context The `_Success_` and `_On_failure_` annotations can only be used on function return values. ## Examples +This sample shows how the warning finds a misplaced SAL annotation: + ```cpp -#include +#include // Oops, _Success_ is not valid in parameter lists, should be moved to return value. bool GetValue( _Success_(return != false) _Out_ int *pInt, bool flag) @@ -30,8 +31,10 @@ bool GetValue( _Success_(return != false) _Out_ int *pInt, bool flag) } ``` +To correct the issue, move the SAL annotation to the return value: + ```cpp -#include +#include _Success_(return != false) bool GetValue(_Out_ int *pInt, bool flag) @@ -45,4 +48,6 @@ bool GetValue(_Out_ int *pInt, bool flag) } ``` -[Understanding Sal](understanding-sal.md) +## See also + +[Understanding SAL](understanding-sal.md) diff --git a/docs/code-quality/c28206.md b/docs/code-quality/c28206.md index 8a5f3de3de..ed1a9f956e 100644 --- a/docs/code-quality/c28206.md +++ b/docs/code-quality/c28206.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28206" -title: C28206 +description: "Learn more about: Warning C28206" +title: Warning C28206 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28206"] helpviewer_keywords: ["C28206"] ms.assetid: 27500f97-fe59-452c-8d9c-4258cb44764c --- -# C28206 +# Warning C28206 -> warning C28206: \ : left operand points to a struct, use `->` +> \ : left operand points to a struct, use `->` This warning is reported when the struct pointer dereference notation `->` was expected. diff --git a/docs/code-quality/c28207.md b/docs/code-quality/c28207.md index cdef20f96f..5bba7531ec 100644 --- a/docs/code-quality/c28207.md +++ b/docs/code-quality/c28207.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28207" -title: C28207 +description: "Learn more about: Warning C28207" +title: Warning C28207 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28207"] helpviewer_keywords: ["C28207"] ms.assetid: 057d88cf-d3c7-4d70-9d3a-f3b1b4d194ff --- -# C28207 +# Warning C28207 -> warning C28207: \: left operand is a struct, use . +> \: left operand is a struct, use . This warning is reported when a struct dereference dot (.) was expected. diff --git a/docs/code-quality/c28208.md b/docs/code-quality/c28208.md index ce205b2e40..1a9dc76e94 100644 --- a/docs/code-quality/c28208.md +++ b/docs/code-quality/c28208.md @@ -1,14 +1,40 @@ --- -description: "Learn more about: C28208" -title: C28208 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28208"] +description: "Learn more about: Warning C28208" +title: Warning C28208 +ms.date: 10/03/2022 +f1_keywords: ["C28208", "FUNCTION_TYPE_REDECLARATION", "__WARNING_FUNCTION_TYPE_REDECLARATION"] helpviewer_keywords: ["C28208"] ms.assetid: e9a8ce37-3b05-4202-b078-5570ae496d1d --- -# C28208 +# Warning C28208 -> warning C28208: Function \ was previously defined with a different parameter list at \(\). Some analysis tools will yield incorrect results +> Function *function_name* was previously defined with a different parameter list at *file_name*(*line_number*). Some analysis tools will yield incorrect results -This warning is reported when a function's known definition doesn't match another occurrence. +## Remarks + +This warning almost always accompanies [Compiler Warning (level 1) C4028](../error-messages/compiler-warnings/compiler-warning-level-1-c4028.md). Both warn of a mismatch between the parameters of a function's declaration and its definition. However, this specific error indicates a more niche case than C4028. C28208 indicates not only that a mismatch exists, but that it also can cause issues with analysis tools. This warning most notably occurs when the mismatch exists between a `typedef` function pointer and the definition of that function. This warning is demonstrated in the example below. + +Code analysis name: `FUNCTION_TYPE_REDECLARATION` + +## Example + +The following code generates C28208. `test_type` declares `my_test1` and `my_test2` to take a `void*` parameter, but the definition of `my_test1` takes an `int*` parameter instead. `my_test2` avoids this issue because the definition parameters match the declaration parameters. + +```cpp +// c28208_example.h +typedef void test_type(void*); +``` + +```cpp +// c28208_example.cpp +#include "c28208_example.h" +test_type my_test1; +test_type my_test2; +void my_test1(int* x){}; // Generates C28208 +void my_test2(void* x){}; // Doesn't generate C28208 + +int main() +{ + // Code +} +``` diff --git a/docs/code-quality/c28209.md b/docs/code-quality/c28209.md index 87d2f04d3a..461e21a7b9 100644 --- a/docs/code-quality/c28209.md +++ b/docs/code-quality/c28209.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28209" -title: C28209 +description: "Learn more about: Warning C28209" +title: Warning C28209 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28209"] helpviewer_keywords: ["C28209"] ms.assetid: 245b5fa5-ef64-4c2b-b469-35e184a1fc7d --- -# C28209 +# Warning C28209 -> warning C28209: The declaration for symbol has a conflicting declaration +> The declaration for symbol has a conflicting declaration This warning indicates an incorrectly constructed annotation declaration. This warning should never occur in normal use. diff --git a/docs/code-quality/c28210.md b/docs/code-quality/c28210.md index ba55995c44..4a3ca1068d 100644 --- a/docs/code-quality/c28210.md +++ b/docs/code-quality/c28210.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28210" -title: C28210 +description: "Learn more about: Warning C28210" +title: Warning C28210 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28210"] helpviewer_keywords: ["C28210"] ms.assetid: 653ed499-2b51-413b-b510-e3bc842981b4 --- -# C28210 +# Warning C28210 -> warning C28210: Annotations for the `_On_failure_` context must not be in explicit pre context +> Annotations for the `_On_failure_` context must not be in explicit pre context -Annotations `_On_failure_` must be explicitly or implicitly indicated in `__post` context, that is, to be applied after the function returns. Use `_drv_out` to ensure this. +Annotations `_On_failure_` must be explicitly or implicitly indicated in `__post` context, that is, to be applied after the function returns. Use `_drv_out` to ensure this annotation is indicated. diff --git a/docs/code-quality/c28211.md b/docs/code-quality/c28211.md index 8486bf15c9..30c7b1f97d 100644 --- a/docs/code-quality/c28211.md +++ b/docs/code-quality/c28211.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28211" -title: C28211 +description: "Learn more about: Warning C28211" +title: Warning C28211 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28211"] helpviewer_keywords: ["C28211"] ms.assetid: ce14ba26-daaf-47e0-940f-60073faa93b0 --- -# C28211 +# Warning C28211 -> warning C28211: Static context name expected for SAL_context +> Static context name expected for SAL_context This warning indicates that the operand to the `_Static_context_` annotation must be the name of a tool-defined context. This warning should never occur in normal use. diff --git a/docs/code-quality/c28212.md b/docs/code-quality/c28212.md index dcae67f520..e9231b8147 100644 --- a/docs/code-quality/c28212.md +++ b/docs/code-quality/c28212.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28212" -title: C28212 +description: "Learn more about: Warning C28212" +title: Warning C28212 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28212"] helpviewer_keywords: ["C28212"] ms.assetid: 77046589-0135-490a-b760-a0b9a962c665 --- -# C28212 +# Warning C28212 -> warning C28212: Pointer expression expected for annotation +> Pointer expression expected for annotation This warning indicates that the numbered parameter to an annotation (not the function being annotated) is expected to be a pointer or array type, but some other type was encountered. The annotation needs to be corrected. diff --git a/docs/code-quality/c28213.md b/docs/code-quality/c28213.md index 587d95bb32..0703a653b8 100644 --- a/docs/code-quality/c28213.md +++ b/docs/code-quality/c28213.md @@ -1,45 +1,72 @@ --- -description: "Learn more about: C28213" -title: C28213 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28213"] +description: "Learn more about: Warning C28213" +title: Warning C28213 +ms.date: 02/07/2023 +f1_keywords: ["C28213", "BAD_USEHEADER", "__WARNING_BAD_USEHEADER"] helpviewer_keywords: ["C28213"] -ms.assetid: e141a12a-4c46-47eb-aa9d-a6444472cfaa --- -# C28213 +# Warning C28213 -> warning C28213: The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration. +> The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration. -`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function. If no earlier declaration can be found, or if the current declaration makes changes to the annotations than this warning is emitted. +## Remarks -## Example +`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function. If it can't find an earlier declaration, or if the current declaration makes changes to the annotations, it emits this warning. `_Use_decl_annotations_` also lets you remove all other annotations from the definition, and uses the declaration annotations for analysis of the function. + +This diagnostic is frequently a side effect of refactoring or fixing other warnings by adjusting the annotations on a function. To fix the issue, use the same annotations at the other locations. To determine the correct set of annotations, look at the behavior in the function definition. In most cases, this behavior is intentional and the annotations to the function should reflect it. For more information on SAL annotations, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +It's important for the annotations to match between the declarations and the definition of a function. When the analysis tools analyze the call site of the function, they use the declaration annotations. If the declaration and definition don't match, the static analysis tools may produce incorrect results. When you fix this warning, it's common for your changes to have cascading effects as the tool reanalyzes the source with updated information. + +If this diagnostic occurs because the analyzer couldn't find a previous declaration in the translation unit, the most likely cause is a missing `#include` directive. To resolve this issue when you intentionally don't include the header file, verify that the annotations in the declaration and definition match, and remove the `_Use_decl_annotations_` annotation. Be careful when you don't include a header file, as the two sets of annotations may get out of sync in the future. + +Code analysis name: `BAD_USEHEADER` + +## Examples + +The following code generates C28160. The `buffer` parameter annotation doesn't match between the two files. + +*From example.h:* ```cpp -// from example.h -void example_func(_Out_writes_(n) char* buffer, int n); +void addNullTerminate(_Out_writes_(n) char* buffer, int n); +``` + +*From example.cpp:* -// from example.cpp +```cpp _Use_decl_annotations_ -void example_func(_Out_writes_z_(n) char* buffer, int n) +void addNullTerminate(_Out_writes_z_(n) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` -The `buffer` parameter annotation does not match between the two files. This can be fixed by either changing the annotation so they match at all locations, or by removing all annotations except `_Use_decl_annotations_` from the function definition. In this example `_Out_writes_z_` appears to be correct so we will move that to the function declaration in the header file. +Examine the function definition to determine what the correct annotations should be. In this case, `_Out_writes_z_(n)` appears to be correct, so we move that annotation to the function declaration in the header file. This change resolves the issue because the annotations in the declaration and definition now match. + +*From example.h:* ```cpp +void addNullTerminate(_Out_writes_z_(n) char* buffer, int n); +``` + +Now we can remove the buffer annotation on the definition to simplify future maintenance (although this step is optional). -// from example.h -void example_func(_Out_writes_z_(n) char* buffer, int n); +*From example.cpp:* -// from example.cpp +```cpp _Use_decl_annotations_ -void example_func(char* buffer, int n) +void addNullTerminate(char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` + +In real world code, it's not usually as clear which annotation is correct. For more information and guidance, see [using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +## See also + +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md)\ +[C28252](C28252.md)\ +[C28253](C28253.md)\ +[C28301](C28301.md) diff --git a/docs/code-quality/c28214.md b/docs/code-quality/c28214.md index 5dd26dcc4e..63c2046d2e 100644 --- a/docs/code-quality/c28214.md +++ b/docs/code-quality/c28214.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28214" -title: C28214 +description: "Learn more about: Warning C28214" +title: Warning C28214 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28214"] helpviewer_keywords: ["C28214"] ms.assetid: dceacf19-9813-4e4c-9aa3-889227a93e08 --- -# C28214 +# Warning C28214 -> warning C28214: Attribute parameter names must be p1...p9 +> Attribute parameter names must be p1...p9 This warning indicates that when you construct an annotation declaration, the parameter names are limited to p1...p9. This warning should never occur in normal use. diff --git a/docs/code-quality/c28215.md b/docs/code-quality/c28215.md index 74b5b4fbff..8faccbd7cb 100644 --- a/docs/code-quality/c28215.md +++ b/docs/code-quality/c28215.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28215" -title: C28215 +description: "Learn more about: Warning C28215" +title: Warning C28215 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28215"] helpviewer_keywords: ["C28215"] ms.assetid: 47f51185-66f8-4b9c-b614-1d275b388729 --- -# C28215 +# Warning C28215 -> warning C28215: The typefix cannot be applied to a parameter that already has a typefix +> The typefix cannot be applied to a parameter that already has a typefix -Applying a `__typefix` annotation to a parameter that already has that annotation is an error. The `__typefix` annotations are used only in a few special cases and this warning is not expected to be seen in normal use. +Applying a `__typefix` annotation to a parameter that already has that annotation is an error. The `__typefix` annotations are used only in a few special cases. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28216.md b/docs/code-quality/c28216.md index c6eec79b18..7b29988b81 100644 --- a/docs/code-quality/c28216.md +++ b/docs/code-quality/c28216.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28216" -title: C28216 +description: "Learn more about: Warning C28216" +title: Warning C28216 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28216"] helpviewer_keywords: ["C28216"] ms.assetid: 627f0280-915b-49b7-9086-43bd0835c919 --- -# C28216 +# Warning C28216 -> warning C28216: The \_Check\_return\_ annotation only applies to post-conditions for the specific function parameter. +> The \_Check\_return\_ annotation only applies to post-conditions for the specific function parameter. The `_Check_return_` annotation has been applied in a context other than `__post`; it may need a `__post` (or `__drv_out`) modifier, or it may be placed incorrectly. diff --git a/docs/code-quality/c28217.md b/docs/code-quality/c28217.md index 875eaae082..48b1464978 100644 --- a/docs/code-quality/c28217.md +++ b/docs/code-quality/c28217.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28217" -title: C28217 +description: "Learn more about: Warning C28217" +title: Warning C28217 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28217"] helpviewer_keywords: ["C28217"] ms.assetid: 681fc502-b4d2-45a2-8a9e-7323e6860626 --- -# C28217 +# Warning C28217 -> warning C28217: For function, the number of parameters to annotation does not match that found at file +> For function, the number of parameters to annotation does not match that found at file -The annotations on the current line and on the line in the message are inconsistent. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +The annotations on the current line and on the line in the message are inconsistent. This inconsistency shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28218.md b/docs/code-quality/c28218.md index 88ad73cf48..1347548f67 100644 --- a/docs/code-quality/c28218.md +++ b/docs/code-quality/c28218.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28218" -title: C28218 +description: "Learn more about: Warning C28218" +title: Warning C28218 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28218"] helpviewer_keywords: ["C28218"] ms.assetid: 3810c606-c43f-47e6-beee-a6ee089ab66a --- -# C28218 +# Warning C28218 -> warning C28218: For function parameter, the annotation's parameter does not match that found at file +> For function parameter, the annotation's parameter does not match that found at file -The annotations on the current line and on the line in the message are inconsistent. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +The annotations on the current line and on the line in the message are inconsistent. This inconsistency shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28219.md b/docs/code-quality/c28219.md index 04f38c2aa6..cfe7fed7c4 100644 --- a/docs/code-quality/c28219.md +++ b/docs/code-quality/c28219.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28219" -title: C28219 +description: "Learn more about: Warning C28219" +title: Warning C28219 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28219"] helpviewer_keywords: ["C28219"] ms.assetid: f8b4fca4-8bba-4720-ae79-f4619161a85e --- -# C28219 +# Warning C28219 -> warning C28219: Member of enumeration expected for annotation the parameter in the annotation +> Member of enumeration expected for annotation the parameter in the annotation -A parameter to an annotation is expected to be a member of the named **`enum`** type, and some other symbol was encountered; use a member of that **`enum`** type. This usually indicates an incorrectly coded annotation macro. +A parameter to an annotation is expected to be a member of the named **`enum`** type, and some other symbol was encountered; use a member of that **`enum`** type. This warning usually indicates an incorrectly coded annotation macro. diff --git a/docs/code-quality/c28220.md b/docs/code-quality/c28220.md index c2751bce11..e0c6984868 100644 --- a/docs/code-quality/c28220.md +++ b/docs/code-quality/c28220.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28220" -title: C28220 +description: "Learn more about: Warning C28220" +title: Warning C28220 ms.date: 12/17/2019 -ms.topic: reference f1_keywords: ["C28220"] helpviewer_keywords: ["C28220"] ms.assetid: 64ff46fe-7ce7-491a-b0bb-484500b0267a --- -# C28220 +# Warning C28220 -> warning C28220: Integer expression expected for annotation '\' +> Integer expression expected for annotation '*annotation*' -This warning indicates that an integer expression was expected as an annotation parameter, but an incompatible type was used instead. It can be caused by trying to use a SAL annotation macro that does not fit the current scenario. +This warning indicates that an integer expression was expected as an annotation parameter, but an incompatible type was used instead. It can be caused by trying to use a SAL annotation macro that doesn't fit the current scenario. ## Example @@ -28,7 +27,7 @@ void f(_In_reads_(last) const int *buffer, const int *last) } ``` -In this example the intent of the developer was to indicate that `buffer` would be read up to the `last` element. The `_In_reads_` annotation does not fix the scenario because it is used to indicate a buffer size in number of elements. The correct annotation here is `_In_reads_to_ptr_`, which indicates the end of the buffer with a pointer. +In this example, the intent of the developer was to indicate that `buffer` would be read up to the `last` element. The `_In_reads_` annotation doesn't fix the scenario because it's used to indicate a buffer size in number of elements. The correct annotation is `_In_reads_to_ptr_`, which indicates the end of the buffer with a pointer. If there was no `_to_ptr_` equivalent to the annotation used, then the warning could have been addressed by converting the `last` pointer into a size value with `(buffer - size)` in the annotation. diff --git a/docs/code-quality/c28221.md b/docs/code-quality/c28221.md index 5185aa210f..c5983849aa 100644 --- a/docs/code-quality/c28221.md +++ b/docs/code-quality/c28221.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28221" -title: C28221 +description: "Learn more about: Warning C28221" +title: Warning C28221 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28221"] helpviewer_keywords: ["C28221"] ms.assetid: 06277429-1c19-4729-8abc-69ae90eb1e4e --- -# C28221 +# Warning C28221 -> warning C28221: String expression expected for the parameter in the annotation +> String expression expected for the parameter in the annotation -This warning indicates that a parameter to an annotation is expected to be a string, and some other type was encountered. This usually indicates an incorrectly coded annotation macro and is not expected to be seen in normal use. +This warning indicates that a parameter to an annotation is expected to be a string, and some other type was encountered. This warning usually indicates an incorrectly coded annotation macro, and we don't expect it to be seen in normal use. diff --git a/docs/code-quality/c28222.md b/docs/code-quality/c28222.md index bfc44941f9..c387786961 100644 --- a/docs/code-quality/c28222.md +++ b/docs/code-quality/c28222.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28222" -title: C28222 +description: "Learn more about: Warning C28222" +title: Warning C28222 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28222"] helpviewer_keywords: ["C28222"] ms.assetid: 28c21fab-ffa4-4153-8145-a2da2cb8fbe8 --- -# C28222 +# Warning C28222 -> warning C28222: \_Yes\_, \_No\_, or \_Maybe\_ expected for annotation +> \_Yes\_, \_No\_, or \_Maybe\_ expected for annotation -This warning indicates that a parameter to an annotation is expected to be one of the symbols `_Yes_`, `_No_`, or `_Maybe_`, and some other symbol was encountered. This usually indicates an incorrectly coded annotation macro. +This warning indicates that a parameter to an annotation is expected to be one of the symbols `_Yes_`, `_No_`, or `_Maybe_`, and some other symbol was encountered. This warning usually indicates an incorrectly coded annotation macro. diff --git a/docs/code-quality/c28223.md b/docs/code-quality/c28223.md index 09025bac07..73e8c613f6 100644 --- a/docs/code-quality/c28223.md +++ b/docs/code-quality/c28223.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28223" -title: C28223 +description: "Learn more about: Warning C28223" +title: Warning C28223 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28223"] helpviewer_keywords: ["C28223"] ms.assetid: 4c1a2421-5846-46bb-bc39-5aa38e3760a5 --- -# C28223 +# Warning C28223 -> warning C28223: Did not find expected Token/identifier for annotation, parameter +> Did not find expected Token/identifier for annotation, parameter -This warning indicates that a parameter to an annotation is expected to be an identifier, and some other symbol was encountered. This usually indicates an incorrectly coded annotation macro. The use of C or C++ keywords in this position will cause this error. +This warning indicates that a parameter to an annotation is expected to be an identifier, and some other symbol was encountered. This warning usually indicates an incorrectly coded annotation macro. The use of C or C++ keywords in this position will cause this error. diff --git a/docs/code-quality/c28224.md b/docs/code-quality/c28224.md index 4fa26670c1..773c0fa54f 100644 --- a/docs/code-quality/c28224.md +++ b/docs/code-quality/c28224.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28224" -title: C28224 +description: "Learn more about: Warning C28224" +title: Warning C28224 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28224"] helpviewer_keywords: ["C28224"] ms.assetid: 44d5c30f-46b2-463b-bf4f-038523b945a1 --- -# C28224 +# Warning C28224 -> warning C28224: Annotation requires parameters +> Annotation requires parameters -This warning indicates that the named annotation is used without parameters and at least one parameter is required. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +This warning indicates that the named annotation is used without parameters and at least one parameter is required. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28225.md b/docs/code-quality/c28225.md index b3d8d29e18..05a14b5d0c 100644 --- a/docs/code-quality/c28225.md +++ b/docs/code-quality/c28225.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28225" -title: C28225 +description: "Learn more about: Warning C28225" +title: Warning C28225 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28225"] helpviewer_keywords: ["C28225"] ms.assetid: 8b5de42e-8969-46c0-a022-430f3135f707 --- -# C28225 +# Warning C28225 -> warning C28225: Did not find the correct number of required parameters in annotation +> Did not find the correct number of required parameters in annotation -This warning indicates that the named annotation is used with the incorrect number of parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that the named annotation is used with the incorrect number of parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28226.md b/docs/code-quality/c28226.md index d5711bd9ad..9609d7bd21 100644 --- a/docs/code-quality/c28226.md +++ b/docs/code-quality/c28226.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28226" -title: C28226 +description: "Learn more about: Warning C28226" +title: Warning C28226 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28226"] helpviewer_keywords: ["C28226"] ms.assetid: 2c1f1987-5012-413a-a268-12880e6024ee --- -# C28226 +# Warning C28226 -> warning C28226: Annotation cannot also be a PrimOp (in current declaration) +> Annotation cannot also be a PrimOp (in current declaration) -This warning indicates that the named annotation is being declared as a PrimOp, and also was previously declared as a normal annotation. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +This warning indicates that the named annotation is being declared as a PrimOp, and also was previously declared as a normal annotation. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28227.md b/docs/code-quality/c28227.md index 57c16bec9b..1001294623 100644 --- a/docs/code-quality/c28227.md +++ b/docs/code-quality/c28227.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28227" -title: C28227 +description: "Learn more about: Warning C28227" +title: Warning C28227 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28227"] helpviewer_keywords: ["C28227"] ms.assetid: be7b212b-41c2-45e8-85d1-807d86e92311 --- -# C28227 +# Warning C28227 -> warning C28227: Annotation cannot also be a PrimOp (see prior declaration) +> Annotation cannot also be a PrimOp (see prior declaration) -This warning indicates that the named annotation is being declared as an ordinary annotation, and also was previously declared as a PrimOp. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that the named annotation is being declared as an ordinary annotation, and also was previously declared as a PrimOp. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28228.md b/docs/code-quality/c28228.md index 954cf7cc77..9b7cc61699 100644 --- a/docs/code-quality/c28228.md +++ b/docs/code-quality/c28228.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28228" -title: C28228 +description: "Learn more about: Warning C28228" +title: Warning C28228 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28228"] helpviewer_keywords: ["C28228"] ms.assetid: 2e5aea19-808e-4489-9692-bcde046d8f55 --- -# C28228 +# Warning C28228 -> warning C28228: Annotation parameter: cannot use type in annotations +> Annotation parameter: cannot use type in annotations -This warning indicates that a parameter is of type that is not supported. Annotations can only use a limited set of types as parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that a parameter is of type that isn't supported. Annotations can only use a limited set of types as parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28229.md b/docs/code-quality/c28229.md index 90b33f4ccd..d78ecc7d09 100644 --- a/docs/code-quality/c28229.md +++ b/docs/code-quality/c28229.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28229" -title: C28229 +description: "Learn more about: Warning C28229" +title: Warning C28229 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28229"] helpviewer_keywords: ["C28229"] ms.assetid: 29137cc9-81ac-416c-b56b-4ad9886d68f8 --- -# C28229 +# Warning C28229 -> warning C28229: Annotation does not support parameters +> Annotation does not support parameters -This warning indicates that an annotation was used with a parameter when the annotation is declared without parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that an annotation was used with a parameter when the annotation is declared without parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28230.md b/docs/code-quality/c28230.md index 67ca8b4537..2ec2e28c5e 100644 --- a/docs/code-quality/c28230.md +++ b/docs/code-quality/c28230.md @@ -1,17 +1,16 @@ --- -title: C28230 +title: Warning C28230 description: "Understand the causes of Microsoft C/C++ code analysis warning C28230, and learn how to fix them." ms.date: 10/23/2020 -ms.topic: reference f1_keywords: ["C28230"] helpviewer_keywords: ["C28230"] ms.assetid: 124b17ed-ae47-42c7-bec5-e8e7210af899 --- -# C28230 +# Warning C28230 -> warning C28230: The type of parameter has no member. +> The type of parameter has no member. -This warning indicates that an argument to an annotation attempts to access a member of a **`struct`**, **`class`**, or **`union`** that does not exist. This warning will also be emitted if a parameter tries to call a member function of the object. +This warning indicates that an argument to an annotation attempts to access a member of a **`struct`**, **`class`**, or **`union`** that doesn't exist. This warning will also be emitted if a parameter tries to call a member function of the object. ## Example @@ -35,7 +34,7 @@ void f(_Out_writes_(value.usefulmember) int *buffer, MyStruct value) } ``` -In this example the spelling just needs to be corrected. +In this example, the spelling just needs to be corrected. ```cpp void f(_Out_writes_(value.usefulMember) int *buffer, MyStruct value) diff --git a/docs/code-quality/c28231.md b/docs/code-quality/c28231.md index 7836abf6b0..6b410ce743 100644 --- a/docs/code-quality/c28231.md +++ b/docs/code-quality/c28231.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28231" -title: C28231 +description: "Learn more about: Warning C28231" +title: Warning C28231 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28231"] helpviewer_keywords: ["C28231"] ms.assetid: d1cb9c55-5a4f-40c0-9908-9285cb78a50a --- -# C28231 +# Warning C28231 -> warning C28231: Annotation is only valid on array +> Annotation is only valid on array This warning indicates that an argument to an annotation should be an array, and some other type was encountered. diff --git a/docs/code-quality/c28232.md b/docs/code-quality/c28232.md index c4bcd148fe..f72fd7a171 100644 --- a/docs/code-quality/c28232.md +++ b/docs/code-quality/c28232.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28232" -title: C28232 +description: "Learn more about: Warning C28232" +title: Warning C28232 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28232"] helpviewer_keywords: ["C28232"] ms.assetid: c616b978-02fa-4a0b-8532-d4249369bca1 --- -# C28232 +# Warning C28232 -> warning C28232: \_Pre\_, \_Post\_, or \_Deref\_ not applied to any annotation +> \_Pre\_, \_Post\_, or \_Deref\_ not applied to any annotation -This warning indicates that a `_Pre_`, `_Post_`, or `_Deref_` operator appears in an annotation expression without a subsequent functional annotation; the modifier was ignored, but this indicates an incorrectly coded annotation. +This warning indicates that a `_Pre_`, `_Post_`, or `_Deref_` operator appears in an annotation expression without a subsequent functional annotation; the modifier was ignored, but this warning indicates an incorrectly coded annotation. diff --git a/docs/code-quality/c28233.md b/docs/code-quality/c28233.md index 1f3940d2e3..686c5efd51 100644 --- a/docs/code-quality/c28233.md +++ b/docs/code-quality/c28233.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28233" -title: C28233 +description: "Learn more about: Warning C28233" +title: Warning C28233 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28233"] +f1_keywords: ["C28233", "BLOCK_QUALIFIER"] helpviewer_keywords: ["C28233"] ms.assetid: 07a6a54d-8da8-4a2a-aa7f-2cbd11f8fc9a --- -# C28233 +# Warning C28233 -> warning C28233: pre, post, or deref applied to a block +> Pre, post, or deref applied to a block diff --git a/docs/code-quality/c28234.md b/docs/code-quality/c28234.md index 5a945eb644..f4a37123c1 100644 --- a/docs/code-quality/c28234.md +++ b/docs/code-quality/c28234.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28234" -title: C28234 +description: "Learn more about: Warning C28234" +title: Warning C28234 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28234"] helpviewer_keywords: ["C28234"] ms.assetid: 5bd48232-3738-4d01-a48b-f3f57a288a6a --- -# C28234 +# Warning C28234 -> warning C28234: \_At\_ expression does not apply to current function +> \_At\_ expression does not apply to current function -This warning indicates that the value of an `_At_` expression does not identify an accessible object. +This warning indicates that the value of an `_At_` expression doesn't identify an accessible object. diff --git a/docs/code-quality/c28235.md b/docs/code-quality/c28235.md index 32b838c272..664dbf6d0a 100644 --- a/docs/code-quality/c28235.md +++ b/docs/code-quality/c28235.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28235" -title: C28235 +description: "Learn more about: Warning C28235" +title: Warning C28235 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28235"] helpviewer_keywords: ["C28235"] ms.assetid: 46e71e11-dda6-44b3-9f6e-8a3c956f7364 --- -# C28235 +# Warning C28235 -> warning C28235: The function cannot stand alone as an annotation +> The function cannot stand alone as an annotation -This warning indicates that an attempt was made to use a function that was not declared to be an annotation in an annotation context. This includes using a primitive operation (PrimOp) in a standalone context. This should not be possible if the standard macros are being used for annotations. This warning is not expected to be seen in typical use. +This warning indicates that an attempt was made to use a function that wasn't declared to be an annotation in an annotation context. This includes using a primitive operation (PrimOp) in a standalone context. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28236.md b/docs/code-quality/c28236.md index 5d22517865..b3641ad5e2 100644 --- a/docs/code-quality/c28236.md +++ b/docs/code-quality/c28236.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28236" -title: C28236 +description: "Learn more about: Warning C28236" +title: Warning C28236 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28236"] helpviewer_keywords: ["C28236"] ms.assetid: 6c2761fe-1121-4d54-b973-6c53f0f3080a --- -# C28236 +# Warning C28236 -> warning C28236: The annotation cannot be used in an expression +> The annotation cannot be used in an expression -This warning indicates that an attempt was made to use a function declared to be an annotation in an expression context. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that an attempt was made to use a function declared to be an annotation in an expression context. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28237.md b/docs/code-quality/c28237.md index f630bc8afc..bcf0630a12 100644 --- a/docs/code-quality/c28237.md +++ b/docs/code-quality/c28237.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28237" -title: C28237 +description: "Learn more about: Warning C28237" +title: Warning C28237 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28237"] helpviewer_keywords: ["C28237"] ms.assetid: d33cb4b6-a061-4927-bfab-e25e352af97b --- -# C28237 +# Warning C28237 -> warning C28237: The annotation on parameter is no longer supported +> The annotation on parameter is no longer supported -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28238.md b/docs/code-quality/c28238.md index 6051b95fd0..325fb6cecc 100644 --- a/docs/code-quality/c28238.md +++ b/docs/code-quality/c28238.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28238" -title: C28238 +description: "Learn more about: Warning C28238" +title: Warning C28238 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28238"] helpviewer_keywords: ["C28238"] ms.assetid: e2e67617-652d-44dd-aff7-cce25f81b9f1 --- -# C28238 +# Warning C28238 -> warning C28238: The annotation on parameter has more than one of value, stringValue, and longValue. Use paramn=xxx +> The annotation on parameter has more than one of value, stringValue, and longValue. Use paramn=xxx -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28239.md b/docs/code-quality/c28239.md index 8ad366263d..0045271c93 100644 --- a/docs/code-quality/c28239.md +++ b/docs/code-quality/c28239.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28239" -title: C28239 +description: "Learn more about: Warning C28239" +title: Warning C28239 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28239"] helpviewer_keywords: ["C28239"] ms.assetid: 3b9aeb08-a538-4ab0-a52f-d9e5c9c6bf00 --- -# C28239 +# Warning C28239 -> warning C28239: The annotation on parameter has both value, stringValue, or longValue; and paramn=xxx. Use only paramn=xxx +> The annotation on parameter has both value, stringValue, or longValue; and paramn=xxx. Use only paramn=xxx -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28240.md b/docs/code-quality/c28240.md index 34411aae51..60fb884be5 100644 --- a/docs/code-quality/c28240.md +++ b/docs/code-quality/c28240.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28240" -title: C28240 +description: "Learn more about: Warning C28240" +title: Warning C28240 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28240"] helpviewer_keywords: ["C28240"] ms.assetid: fb40abdd-c082-4ee4-bbb1-cee3e089267a --- -# C28240 +# Warning C28240 -> warning C28240: The annotation on parameter has param2 but no param1 +> The annotation on parameter has param2 but no param1 -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28241.md b/docs/code-quality/c28241.md index 8975a1b682..97d32e715c 100644 --- a/docs/code-quality/c28241.md +++ b/docs/code-quality/c28241.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28241" -title: C28241 +description: "Learn more about: Warning C28241" +title: Warning C28241 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28241"] helpviewer_keywords: ["C28241"] ms.assetid: b8fc340d-84b7-43a9-bfb1-00845154939c --- -# C28241 +# Warning C28241 -> warning C28241: The annotation for function on parameter is not recognized +> The annotation for function on parameter is not recognized -An unrecognized annotation name was used. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +An unrecognized annotation name was used. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28243.md b/docs/code-quality/c28243.md index 2735d310c1..c0e5087bf7 100644 --- a/docs/code-quality/c28243.md +++ b/docs/code-quality/c28243.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28243" -title: C28243 +description: "Learn more about: Warning C28243" +title: Warning C28243 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28243"] helpviewer_keywords: ["C28243"] ms.assetid: a5c57acc-704b-45fe-bed2-4eb1aa8d3d8f --- -# C28243 +# Warning C28243 -> warning C28243: The annotation for function on parameter requires more dereferences than the actual type annotated allows +> The annotation for function on parameter requires more dereferences than the actual type annotated allows The number of `__deref` operators on an annotation is more than the number of levels of pointer defined by the parameter type. Correct this warning by changing either the number in the annotation or the pointer levels of the parameter referenced. diff --git a/docs/code-quality/c28244.md b/docs/code-quality/c28244.md index fdb12ce5f1..ddd7f5dc0a 100644 --- a/docs/code-quality/c28244.md +++ b/docs/code-quality/c28244.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28244" -title: C28244 +description: "Learn more about: Warning C28244" +title: Warning C28244 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28244"] helpviewer_keywords: ["C28244"] ms.assetid: 9fc03940-0810-4693-a1cd-1e03b4681fb9 --- -# C28244 +# Warning C28244 -> warning C28244: The annotation for function has an unparseable parameter/external annotation +> The annotation for function has an unparseable parameter/external annotation -This should currently not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28245.md b/docs/code-quality/c28245.md index 861a2dc449..1f8bf3ce22 100644 --- a/docs/code-quality/c28245.md +++ b/docs/code-quality/c28245.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28245" -title: C28245 +description: "Learn more about: Warning C28245" +title: Warning C28245 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28245"] helpviewer_keywords: ["C28245"] ms.assetid: fabd3338-51f4-4b81-a333-e4fed203bc72 --- -# C28245 +# Warning C28245 -> warning C28245: The annotation for function annotates 'this' on a non-member-function +> The annotation for function annotates 'this' on a non-member-function -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28246.md b/docs/code-quality/c28246.md index cbefa3f860..abf7d57ad7 100644 --- a/docs/code-quality/c28246.md +++ b/docs/code-quality/c28246.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28246" -title: C28246 +description: "Learn more about: Warning C28246" +title: Warning C28246 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28246"] helpviewer_keywords: ["C28246"] ms.assetid: 66a297ab-19fc-4985-8738-0a92f8d1d5cc --- -# C28246 +# Warning C28246 -> warning C28246: The annotation for function '\' - parameter '\' does not match the type of the parameter +> The annotation for function '*name*' - parameter '*parameter*' does not match the type of the parameter -A __deref operator was applied to a non-pointer type when creating an annotation. +A `__deref` operator was applied to a non-pointer type when creating an annotation. diff --git a/docs/code-quality/c28250.md b/docs/code-quality/c28250.md index 92e878e507..f67dd8dead 100644 --- a/docs/code-quality/c28250.md +++ b/docs/code-quality/c28250.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: C28250" -title: C28250 +description: "Learn more about: Warning C28250" +title: Warning C28250 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28250"] helpviewer_keywords: ["C28250"] ms.assetid: 8f405533-fbc3-4ba6-b169-a4c9288acd9a --- -# C28250 +# Warning C28250 -> warning C28250: Inconsistent annotation for function: the prior instance has an error. +> Inconsistent annotation for function: the prior instance has an error. Note: There are several prototypes for this function. This warning compares the first prototype with instance number \. If a declaration is made using a **`typedef`**, the line where the **`typedef`** appears is more useful than the line of the declaration. -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, each declaration is checked pairwise. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, each declaration is checked pairwise. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28251.md b/docs/code-quality/c28251.md index 9842467750..3139b8bd87 100644 --- a/docs/code-quality/c28251.md +++ b/docs/code-quality/c28251.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28251" -title: C28251 +description: "Learn more about: Warning C28251" +title: Warning C28251 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28251"] helpviewer_keywords: ["C28251"] ms.assetid: 9335ad9a-4650-41d2-a2c2-0474d7346472 --- -# C28251 +# Warning C28251 -> warning C28251: Inconsistent annotation for function: this instance has an error +> Inconsistent annotation for function: this instance has an error -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28252.md b/docs/code-quality/c28252.md index 0a863defa7..81586e5f4c 100644 --- a/docs/code-quality/c28252.md +++ b/docs/code-quality/c28252.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28252" -title: C28252 +description: "Learn more about: Warning C28252" +title: Warning C28252 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28252"] helpviewer_keywords: ["C28252"] ms.assetid: 58407fc3-ef27-4905-bc03-caf07b907cc4 --- -# C28252 +# Warning C28252 -> warning C28252: Inconsistent annotation for function: parameter has another annotation on this instance +> Inconsistent annotation for function: parameter has another annotation on this instance -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28253.md b/docs/code-quality/c28253.md index 2bd4287917..6dfd0c4686 100644 --- a/docs/code-quality/c28253.md +++ b/docs/code-quality/c28253.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28253" -title: C28253 +description: "Learn more about: Warning C28253" +title: Warning C28253 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28253"] helpviewer_keywords: ["C28253"] ms.assetid: df049e53-aab7-4914-b5f6-81ebe8ee989b --- -# C28253 +# Warning C28253 -> warning C28253: Inconsistent annotation for function: parameter has another annotations on this instance +> Inconsistent annotation for function: parameter has another annotations on this instance -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28254.md b/docs/code-quality/c28254.md index 8196abf4ef..892b526c9d 100644 --- a/docs/code-quality/c28254.md +++ b/docs/code-quality/c28254.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28254" -title: C28254 +description: "Learn more about: Warning C28254" +title: Warning C28254 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28254"] +f1_keywords: ["C28254", "DYNAMIC_CAST"] helpviewer_keywords: ["C28254"] ms.assetid: ac8a6d6d-4e8f-4e90-8d90-4c107e245b53 --- -# C28254 +# Warning C28254 -> warning C28254: dynamic_cast<>() is not supported in annotations +> `dynamic_cast<>()` is not supported in annotations -The C++ **`dynamic_cast`** operator cannot be used in annotations. +The C++ **`dynamic_cast`** operator can't be used in annotations. diff --git a/docs/code-quality/c28262.md b/docs/code-quality/c28262.md index 670ccc107e..bff5e7dbde 100644 --- a/docs/code-quality/c28262.md +++ b/docs/code-quality/c28262.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28262" -title: C28262 +description: "Learn more about: Warning C28262" +title: Warning C28262 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28262"] helpviewer_keywords: ["C28262"] ms.assetid: 58e130b7-c466-411f-84a0-502898e3e9e6 --- -# C28262 +# Warning C28262 -> warning C28262: A syntax error in the annotation was found in function \ for annotation \ +> A syntax error in the annotation was found in function '*function*' for annotation '*name*' diff --git a/docs/code-quality/c28263.md b/docs/code-quality/c28263.md index c2483ccaaa..93a3524308 100644 --- a/docs/code-quality/c28263.md +++ b/docs/code-quality/c28263.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C28263" -title: C28263 +description: "Learn more about: Warning C28263" +title: Warning C28263 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28263"] helpviewer_keywords: ["C28263"] ms.assetid: 5b75fb56-8fc9-43ad-a00d-a28dc6cf6fca --- -# C28263 +# Warning C28263 -> warning C28263: A syntax error in a conditional annotation was found for Intrinsic annotation +> A syntax error in a conditional annotation was found for Intrinsic annotation The Code Analysis tool reports this warning when the return value for the specified function has a conditional value. This warning indicates an error in the annotations, not in the code being analyzed. If the function declaration is in a header file, the annotation should be corrected so that it matches the header file. The result list for the function and parameter specified has multiple unconditional values. -Typically, this indicates that more than one unconditional `_Null_` or `__drv_valueIs` annotations have been used to specify a result value. +Typically, this warning indicates that more than one unconditional `_Null_` or `__drv_valueIs` annotations have been used to specify a result value. diff --git a/docs/code-quality/c28267.md b/docs/code-quality/c28267.md index c3823f014f..ceb6cf1c98 100644 --- a/docs/code-quality/c28267.md +++ b/docs/code-quality/c28267.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28267" -title: C28267 +description: "Learn more about: Warning C28267" +title: Warning C28267 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28267"] helpviewer_keywords: ["C28267"] ms.assetid: 3f32f302-842d-43df-bb28-e90b24021ae9 --- -# C28267 +# Warning C28267 -> warning C28267: A syntax error in the annotations was found annotation \ in the function \. +> A syntax error in the annotations was found for function '*function-name*', for annotation '*annotation-name*': *reason*. diff --git a/docs/code-quality/c28272.md b/docs/code-quality/c28272.md index d55950b6df..7801077573 100644 --- a/docs/code-quality/c28272.md +++ b/docs/code-quality/c28272.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28272" -title: C28272 +description: "Learn more about: Warning C28272" +title: Warning C28272 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28272"] helpviewer_keywords: ["C28272"] ms.assetid: 0288be83-d0aa-488c-9097-cb33bd423033 --- -# C28272 +# Warning C28272 -> warning C28272: The annotation for function, parameter when examining is inconsistent with the function declaration +> The annotation for function '*function-name*', parameter '*parameter-name*' when examining '*clue*' is inconsistent with the function declaration -This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with those appearing on a declaration. The two annotations should be resolved to match. +This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with the ones appearing on a declaration. The two annotations should be resolved to match. diff --git a/docs/code-quality/c28273.md b/docs/code-quality/c28273.md index 6f93b9694d..208eb97a06 100644 --- a/docs/code-quality/c28273.md +++ b/docs/code-quality/c28273.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28273" -title: C28273 +description: "Learn more about: Warning C28273" +title: Warning C28273 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28273"] helpviewer_keywords: ["C28273"] ms.assetid: 3115995b-5734-425f-91ef-115293bfb862 --- -# C28273 +# Warning C28273 -> warning C28273: For function, the clues are inconsistent with the function declaration +> For function '*function-name*', the clues are inconsistent with the function declaration -This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with those appearing on a declaration. The two annotations should be resolved to match. +This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with the ones appearing on a declaration. The two annotations should be resolved to match. diff --git a/docs/code-quality/c28275.md b/docs/code-quality/c28275.md index 47d839e7c7..935b1abdac 100644 --- a/docs/code-quality/c28275.md +++ b/docs/code-quality/c28275.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28275" -title: C28275 +description: "Learn more about: Warning C28275" +title: Warning C28275 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28275"] helpviewer_keywords: ["C28275"] ms.assetid: fb3ee99d-9855-45e6-aebd-f2174a85c481 --- -# C28275 +# Warning C28275 -> warning C28275: The parameter to \_Macro\_value\_ is null +> The parameter to \_Macro\_value\_ is null -This warning indicates that there is an internal error in the model file, not in the code being analyzed. The *macroValue* function was called without a parameter. +This warning indicates that there's an internal error in the model file, not in the code being analyzed. The *macroValue* function was called without a parameter. diff --git a/docs/code-quality/c28278.md b/docs/code-quality/c28278.md index 1db293b6f0..901ee8e558 100644 --- a/docs/code-quality/c28278.md +++ b/docs/code-quality/c28278.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C28278" -title: C28278 +description: "Learn more about: Warning C28278" +title: Warning C28278 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28278"] helpviewer_keywords: ["C28278"] ms.assetid: fbfe2256-022f-4251-8397-d3e5511632e2 --- -# C28278 +# Warning C28278 -> warning C28278: Function name appears with no prototype in scope. +> Function name appears with no prototype in scope. This warning typically indicates that a `__deref` is needed to apply the `__return` annotation to the value returned. The Code Analysis tool reports this warning when a function without a declaration was called, and the analysis that can be performed is limited because the declaration contains important information. -The C language permits (but discourages) the use of a function for which no prototype has been declared. A function definition or a function declaration (prototype) should appear before the first use of the function. This warning indicates that a function without a declaration was called, and the analysis that can be performed is limited because declaration contains important information. If the function declaration were to contain annotations, the function declaration is even more useful to the Code Analysis tool. +The C language permits (but discourages) the use of a function for which no prototype has been declared. A function definition or a function declaration (prototype) should appear before the first use of the function. This warning indicates that a function without a declaration was called, and the analysis that can be performed is limited because declaration contains important information. If the function declaration contains annotations, the function declaration is even more useful to the Code Analysis tool. diff --git a/docs/code-quality/c28279.md b/docs/code-quality/c28279.md index 2c92db7b3e..7a2922ea5b 100644 --- a/docs/code-quality/c28279.md +++ b/docs/code-quality/c28279.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28279" -title: C28279 +description: "Learn more about: Warning C28279" +title: Warning C28279 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28279"] helpviewer_keywords: ["C28279"] ms.assetid: 10e2bbd9-84c9-4f52-94ba-722e9fef0b5e --- -# C28279 +# Warning C28279 -> warning C28279: For symbol, a 'begin' was found without a matching 'end' +> For symbol, a 'begin' was found without a matching 'end' The annotation language supports a begin and end (`{` and `}` in C) construct, and the pairing has gotten unbalanced. This situation can be avoided if the macros are used. diff --git a/docs/code-quality/c28280.md b/docs/code-quality/c28280.md index 775143c497..c7b78317c3 100644 --- a/docs/code-quality/c28280.md +++ b/docs/code-quality/c28280.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28280" -title: C28280 +description: "Learn more about: Warning C28280" +title: Warning C28280 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28280"] helpviewer_keywords: ["C28280"] ms.assetid: f9c989e3-c11d-4742-9e9c-db49096ef099 --- -# C28280 +# Warning C28280 -> warning C28280: For symbol, an 'end' was found without a matching 'begin' +> For symbol, an 'end' was found without a matching 'begin' The annotation language supports a begin and an end (`{` and `}` in C) construct, and the pairing has gotten unbalanced. This situation can be avoided if the macros are used. diff --git a/docs/code-quality/c28282.md b/docs/code-quality/c28282.md index 95edd40828..381f066b76 100644 --- a/docs/code-quality/c28282.md +++ b/docs/code-quality/c28282.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28282" -title: C28282 +description: "Learn more about: Warning C28282" +title: Warning C28282 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28282"] helpviewer_keywords: ["C28282"] ms.assetid: 36ffd1c6-722e-492f-aa91-650b705511c5 --- -# C28282 +# Warning C28282 -> warning C28282: Format Strings must be in preconditions +> Format Strings must be in preconditions -This warning indicates that a `__drv_formatString` annotation is found, which is not in a `_Pre_` (`__drv_in`) annotation (function parameters are by default `_Pre_`). Check whether the annotation used in an explicit block with a `_Post_` (`__drv_out`) annotation. If so, remove the annotation from any enclosing block that has put it in a `_Post_` context. +This warning indicates that a `__drv_formatString` annotation is found, which isn't in a `_Pre_` (`__drv_in`) annotation (function parameters are by default `_Pre_`). Check whether the annotation used in an explicit block with a `_Post_` (`__drv_out`) annotation. If so, remove the annotation from any enclosing block that has put it in a `_Post_` context. diff --git a/docs/code-quality/c28283.md b/docs/code-quality/c28283.md index 0c58488a30..7b265029cf 100644 --- a/docs/code-quality/c28283.md +++ b/docs/code-quality/c28283.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28283" -title: C28283 +description: "Learn more about: Warning C28283" +title: Warning C28283 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28283"] helpviewer_keywords: ["C28283"] ms.assetid: 061d7818-6826-4e6f-8f9c-a6ed687ee1b3 --- -# C28283 +# Warning C28283 -> warning C28283: For symbol, the specified size specification is not yet supported +> For symbol, the specified size specification is not yet supported The warning indicates that the size specification "sentinel" annotation received a value other than zero. Essentially, the caller tried to say that the string is terminated by a character other than binary zero. diff --git a/docs/code-quality/c28284.md b/docs/code-quality/c28284.md index 35028ee67c..e08a870bed 100644 --- a/docs/code-quality/c28284.md +++ b/docs/code-quality/c28284.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28284" -title: C28284 +description: "Learn more about: Warning C28284" +title: Warning C28284 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28284"] helpviewer_keywords: ["C28284"] ms.assetid: 11dd24b0-7057-4fe8-919e-b61cf3674fea --- -# C28284 +# Warning C28284 -> warning C28284: For symbol, Predicates are currently not supported for non-function symbols +> For symbol, Predicates are currently not supported for non-function symbols This warning indicates that a conditional annotation (predicate, `__drv_when`) was found on something other than a function. diff --git a/docs/code-quality/c28285.md b/docs/code-quality/c28285.md index dedc06f6e9..d3603284c4 100644 --- a/docs/code-quality/c28285.md +++ b/docs/code-quality/c28285.md @@ -1,35 +1,35 @@ --- -description: "Learn more about: C28285" -title: C28285 -ms.date: 12/17/2019 -ms.topic: reference -f1_keywords: ["C28285"] +description: "Learn more about: Warning C28285" +title: Warning C28285 +ms.date: 09/22/2022 +f1_keywords: ["C28285", "SPEC_INVALID_SYNTAX2", "__WARNING_SPEC_INVALID_SYNTAX2"] helpviewer_keywords: ["C28285"] ms.assetid: 6197eb0f-7e1e-4c3e-b097-1f6481405994 --- -# C28285 +# Warning C28285 -> warning C28285: For function 'function_name', syntax error in 'annotation' +> For function '*function-name*', syntax error in '*annotation*' -The Code Analysis tool reports this warning for syntax errors in the SAL annotation. The SAL parser will recover by discarding the malformed annotation. +## Remarks + +The Code Analysis tool reports this warning for syntax errors in the SAL annotation. The SAL parser will recover by discarding the malformed annotation. Double check the documentation for the SAL annotations being used and try to simplify the annotation. You shouldn't use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you're using that layer, then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`. For more information, see [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md). ## Example +The following code generates this warning. The argument `(2,n)` is malformed and will cause a C28285 warning after the `_Out_writes_z_` macro is expanded. + ```cpp -// The argument '(n,2)' is malformed and will cause a C28285 warning after the _Out_writes_z_ macro is expanded. void example_func(_Out_writes_z_((2,n)) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` -Double check the documentation to the SAL annotations being used and try to simplify the annotation. You should not use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you are using that layer then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`. See [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md) for more information. +The following code remediates this warning by correcting the malformed annotation ```cpp void example_func(_Out_writes_z_(n) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` diff --git a/docs/code-quality/c28286.md b/docs/code-quality/c28286.md index f46720281a..61c5cfb967 100644 --- a/docs/code-quality/c28286.md +++ b/docs/code-quality/c28286.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28286" -title: C28286 +description: "Learn more about: Warning C28286" +title: Warning C28286 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28286"] helpviewer_keywords: ["C28286"] ms.assetid: dce3c45f-3632-407d-b9ac-8a37b3ce21a4 --- -# C28286 +# Warning C28286 -> warning C28286: For function, syntax error near the end +> For function, syntax error near the end The Code Analysis tool reports this warning when a probable error is encountered in the model file. A few source file errors can also cause such errors. diff --git a/docs/code-quality/c28287.md b/docs/code-quality/c28287.md index f87e5ec7eb..efec973fbb 100644 --- a/docs/code-quality/c28287.md +++ b/docs/code-quality/c28287.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28287" -title: C28287 +description: "Learn more about: Warning C28287" +title: Warning C28287 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28287"] helpviewer_keywords: ["C28287"] ms.assetid: b0edc1b6-ad52-4512-a1ee-90180f800d44 --- -# C28287 +# Warning C28287 -> warning C28287: For function, syntax Error in \_At\_() annotation (unrecognized parameter name) +> For function, syntax Error in \_At\_() annotation (unrecognized parameter name) -The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression cannot be interpreted in the current context. This might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. +The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression can't be interpreted in the current context. Reasons might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. diff --git a/docs/code-quality/c28288.md b/docs/code-quality/c28288.md index d5c8d406c2..4d359b1269 100644 --- a/docs/code-quality/c28288.md +++ b/docs/code-quality/c28288.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28288" -title: C28288 +description: "Learn more about: Warning C28288" +title: Warning C28288 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28288"] helpviewer_keywords: ["C28288"] ms.assetid: 3995f210-e797-434c-bc1c-db10b42da3ac --- -# C28288 +# Warning C28288 -> warning C28288: For function, syntax Error in \_At\_() annotation (invalid parameter name) +> For function, syntax Error in \_At\_() annotation (invalid parameter name) -The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression cannot be interpreted in the current context. This might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. +The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression can't be interpreted in the current context. Reasons might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. diff --git a/docs/code-quality/c28289.md b/docs/code-quality/c28289.md index 58f99f72d8..0cee202775 100644 --- a/docs/code-quality/c28289.md +++ b/docs/code-quality/c28289.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28289" -title: C28289 +description: "Learn more about: Warning C28289" +title: Warning C28289 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28289"] helpviewer_keywords: ["C28289"] ms.assetid: 13af34f6-c8b0-4751-9df5-251322073fff --- -# C28289 +# Warning C28289 -> warning C28289: For function: ReadableTo or WritableTo did not have a limit-spec as a parameter +> For function: ReadableTo or WritableTo did not have a limit-spec as a parameter The Code Analysis tool reports this warning when the function/parameter annotation is miscoded as noted. diff --git a/docs/code-quality/c28290.md b/docs/code-quality/c28290.md index 1d8a32a470..f01f88a591 100644 --- a/docs/code-quality/c28290.md +++ b/docs/code-quality/c28290.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28290" -title: C28290 +description: "Learn more about: Warning C28290" +title: Warning C28290 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28290"] helpviewer_keywords: ["C28290"] ms.assetid: 33c22d66-fce4-4670-99d4-7bd147dd05d0 --- -# C28290 +# Warning C28290 -> warning C28290: the annotation for function contains more Externals than the actual number of parameters +> The annotation for function contains more Externals than the actual number of parameters The Code Analysis tool reports this warning when the annotation for the function contains more Externals than the actual number of parameters. diff --git a/docs/code-quality/c28291.md b/docs/code-quality/c28291.md index 5e768d9545..346c9e49f6 100644 --- a/docs/code-quality/c28291.md +++ b/docs/code-quality/c28291.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28291" -title: C28291 +description: "Learn more about: Warning C28291" +title: Warning C28291 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28291"] helpviewer_keywords: ["C28291"] ms.assetid: 92157d55-d8d2-4c3e-9240-c5d8923631f6 --- -# C28291 +# Warning C28291 -> warning C28291: Post null/notnull at deref level 0 is meaningless for function \ at param \ +> Post null/notnull at deref level 0 is meaningless for function '*x*' at param '*number*' -The Code Analysis tool reports this warning when the post condition of a dereference level-zero parameter is specified to have a null/non-null property. This error occurs because a value at dereference level zero cannot change. +The Code Analysis tool reports this warning when the post condition of a dereference level-zero parameter is specified to have a null/non-null property. This error occurs because a value at dereference level zero can't change. diff --git a/docs/code-quality/c28300.md b/docs/code-quality/c28300.md index a3c853ea27..38dec826cb 100644 --- a/docs/code-quality/c28300.md +++ b/docs/code-quality/c28300.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28300" -title: C28300 +description: "Learn more about: Warning C28300" +title: Warning C28300 ms.date: 12/17/2019 -ms.topic: reference f1_keywords: ["C28300"] helpviewer_keywords: ["C28300"] ms.assetid: 29430cff-c5b8-4759-8898-055dc1c4597f --- -# C28300 +# Warning C28300 -> warning C28300: : Expression operands of incompatible types for operator +> : Expression operands of incompatible types for operator This warning fires a SAL annotation contains an expression containing incompatible types. @@ -32,7 +31,7 @@ void f(_In_reads_(10 + value) int *buffer, MyUnion value) } ``` -In the previous example the developer forgot to access the appropriate member variable. In other cases you may need to fix the error with an explicit cast. +In the previous example, the developer forgot to access the appropriate member variable. In other cases, you may need to fix the error with an explicit cast. ```cpp void f(_In_reads_(10 + value.length) int *buffer, MyUnion value) diff --git a/docs/code-quality/c28301.md b/docs/code-quality/c28301.md index 5c26d4f356..dd41694f88 100644 --- a/docs/code-quality/c28301.md +++ b/docs/code-quality/c28301.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28301" -title: C28301 +description: "Learn more about: Warning C28301" +title: Warning C28301 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28301"] helpviewer_keywords: ["C28301"] ms.assetid: bef85fd0-dc76-4981-bd64-618317e97a38 --- -# C28301 +# Warning C28301 -> warning C28301: No annotations for first declaration of \.\ See \(\). \ +> No annotations for first declaration of '*function*'.'*note1*' See '*filename*'('*line*'). '*note2*' -This warning is reported when annotations were not found at the first declaration of a given function. +This warning is reported when annotations weren't found at the first declaration of a given function. diff --git a/docs/code-quality/c28302.md b/docs/code-quality/c28302.md index 70f7c0a5cc..81f4f296b4 100644 --- a/docs/code-quality/c28302.md +++ b/docs/code-quality/c28302.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28302" -title: C28302 -ms.date: 11/04/2016 -ms.topic: reference +description: "Learn more about: Warning C28302" +title: Warning C28302 +ms.date: 06/29/2022 f1_keywords: ["C28302"] helpviewer_keywords: ["C28302"] ms.assetid: 288316e1-f7ea-4c73-a1e6-8f6fe645fbaf --- -# C28302 +# Warning C28302 -> warning C28302: For C++ reference-parameter , an extra `_Deref_` operator was found on \. +> For C++ reference-parameter '*parameter_name*', an extra `_Deref_` operator was found on '*annotation*'. -This warning is reported when an extra level of `_Deref_` is used on a parameter of a reference type such as `T &a`. A common mistake when using SAL1 annotations is to use `__deref` on a reference type. Reference types are understood by SAL so all annotations are already applied to the underlying type. This is typically not an issue in SAL2 because the free-floating `__deref` annotation was removed. If the intention is to apply an annotation to a sub-type then you should instead use the SAL2 `_AT_` or `_Outref_` annotations. +This warning is reported when an extra level of `_Deref_` is used on a parameter of a reference type such as `T &a`. A common mistake when using SAL1 annotations is to use `__deref` on a reference type. Reference types are understood by SAL, so all annotations are already applied to the underlying type. It's typically not an issue in SAL2 because the free-floating `__deref` annotation was removed. If you intend to apply an annotation to a subtype, then you should instead use the SAL2 `_AT_` or `_Outref_` annotations. ## Example @@ -27,7 +26,13 @@ void func() } ``` +To address the issue, update to SAL2 annotations: + ```cpp -// Fix warning switching to SAL2 syntax which has annotations that better describe what the function does. +// Fix warning by switching to SAL2 syntax which has annotations that better describe what the function does. void f( _Outref_result_buffer_(size) int *& buffer); ``` + +## See also + +[Understanding SAL](understanding-sal.md) diff --git a/docs/code-quality/c28303.md b/docs/code-quality/c28303.md index b661800ef8..9ac04b56bb 100644 --- a/docs/code-quality/c28303.md +++ b/docs/code-quality/c28303.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28303" -title: C28303 +description: "Learn more about: Warning C28303" +title: Warning C28303 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28303"] helpviewer_keywords: ["C28303"] ms.assetid: 0b314abd-6082-43fb-bba3-a9edb5a7bf19 --- -# C28303 +# Warning C28303 -> warning C28303: For C++ reference-parameter , an ambiguous `_Deref_` operator was found on \. +> For C++ reference-parameter , an ambiguous `_Deref_` operator was found on '*annotation*'. This warning similar to warning C28302 and is reported when an extra level of `_Deref_` is used on a parameter. -SAL2 does not require the use of an extra level of `_Deref_` when dealing with reference parameters. This particular annotation is ambiguous as to which level of dereference is intended to be annotated. It may be necessary to use `_At_` to reference the specific object to be annotated. +SAL2 doesn't require the use of an extra level of `_Deref_` when dealing with reference parameters. This particular annotation is ambiguous as to which level of dereference is intended to be annotated. It may be necessary to use `_At_` to reference the specific object to be annotated. ## Example @@ -29,7 +28,7 @@ The above annotation could be interpreted either as: - a reference to a pointer to an array (of n) integers (SAL2 interpretation) - Either of the following can correct this warning: + Either of the following changes can correct this warning: ```cpp void ref(_Out_writes_(n) int **&buff, int &n) diff --git a/docs/code-quality/c28304.md b/docs/code-quality/c28304.md index e00b915e01..8e6b84c97b 100644 --- a/docs/code-quality/c28304.md +++ b/docs/code-quality/c28304.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28304" -title: C28304 +description: "Learn more about: Warning C28304" +title: Warning C28304 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28304"] helpviewer_keywords: ["C28304"] ms.assetid: 5bc7f593-dfc3-4172-a403-97bdf7be4885 --- -# C28304 +# Warning C28304 -> warning C28304: For C++ reference-parameter , an improperly placed `_Notref_` operator was found applied to \. +> For C++ reference-parameter , an improperly placed `_Notref_` operator was found applied to '*token*'. The `_Notref_` operator should only be used in special circumstances involving C++ reference parameters and only in system-provided macros. It must be immediately followed by a `_Deref_` operator or a functional annotation. diff --git a/docs/code-quality/c28305.md b/docs/code-quality/c28305.md index 64688a7e8d..17bd8083dd 100644 --- a/docs/code-quality/c28305.md +++ b/docs/code-quality/c28305.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28305" -title: C28305 +description: "Learn more about: Warning C28305" +title: Warning C28305 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28305"] helpviewer_keywords: ["C28305"] ms.assetid: c9495d3f-aa11-4695-ab8d-1d2194da9ce3 --- -# C28305 +# Warning C28305 -> warning C28305: An error while parsing \ was discovered. +> An error while parsing '*token*' was discovered. This warning is reported when the expression containing the specified token is ill-formed. diff --git a/docs/code-quality/c28306.md b/docs/code-quality/c28306.md index fc72b5838f..0462d5856d 100644 --- a/docs/code-quality/c28306.md +++ b/docs/code-quality/c28306.md @@ -1,14 +1,17 @@ --- -description: "Learn more about: C28306" -title: C28306 +description: "Learn more about: Warning C28306" +title: Warning C28306 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28306"] helpviewer_keywords: ["C28306"] ms.assetid: 64517b10-c8b3-4100-953b-278eab624369 --- -# C28306 +# Warning C28306 -> warning C28306: The annotation on parameter is obsolescent +> The annotation on parameter is obsolescent Use `_String_length_` with the appropriate SAL2 annotation instead. + +## See also + +[Intrinsic Functions](./intrinsic-functions.md) diff --git a/docs/code-quality/c28307.md b/docs/code-quality/c28307.md index 16801c99f8..28d5af3d02 100644 --- a/docs/code-quality/c28307.md +++ b/docs/code-quality/c28307.md @@ -1,14 +1,17 @@ --- -description: "Learn more about: C28307" -title: C28307 +description: "Learn more about: Warning C28307" +title: Warning C28307 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28307"] helpviewer_keywords: ["C28307"] ms.assetid: e86a14cc-9ff1-4bad-9d85-93c739704ab8 --- -# C28307 +# Warning C28307 -> warning C28307: The annotation on parameter is obsolescent +> The annotation on parameter is obsolescent Use `_String_length_` with the appropriate SAL2 annotation instead. + +## See also + +[Intrinsic Functions](./intrinsic-functions.md) diff --git a/docs/code-quality/c28308.md b/docs/code-quality/c28308.md index 1ee8e1e2a2..c4ceffa743 100644 --- a/docs/code-quality/c28308.md +++ b/docs/code-quality/c28308.md @@ -1,22 +1,50 @@ --- -description: "Learn more about: C28308" -title: C28308 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28308"] +description: "Learn more about: Warning C28308" +title: Warning C28308 +ms.date: 03/07/2023 +f1_keywords: ["C28308", "BAD_FORMAT_ARGUMENT_POSITION", "__WARNING_BAD_FORMAT_ARGUMENT_POSITION"] helpviewer_keywords: ["C28308"] -ms.assetid: 2be46de3-844e-4cd6-a97f-d5c12ac9dc31 --- -# C28308 +# Warning C28308 -> warning C28308: The format list argument position specified by the annotation is incorrect. +> The format list argument position specified by the annotation is incorrect. -The format list argument position must be either a parameter name, or an integer offset that's in the parameter list, or zero. +## Remarks -The second parameter to `IsFormatString2` (`where`) can be in one of two forms: +This warning indicates a `_*_format_strings_param(position)` SAL annotation is specifying an invalid position for the first parameter to the format string. The annotation helps the checker verify `printf` style formatting strings passed to the function. Other format string validity checks that rely on this annotation won't run as a result of this warning. -- A parameter name, which is taken as the first argument to the format string. +The `_*_format_strings_param(position)` SAL annotation is attached to the formatting string argument. `position` must be in one of these forms: -- An offset (`n`) relative to the format-string parameter. +- An identifier, which is taken as the first argument to the format string. When the identifier isn't the name of a parameter to the function, a warning is emitted. +- A positive integer offset relative to the format-string parameter where `1` is the next parameter. When the offset is out of bounds for the parameters, a warning is emitted. +- The value `0`, which is interpreted as the `...` parameter. When the function isn't variadic, a warning is emitted. - In the second form, the first format-string parameter is the `n`-th argument after the format string. If `n` is zero, an ellipsis is specified as the parameter. Specifying an offset of zero without specifying the ellipsis as the first format-string parameter will cause an error. +One limitation of this check, is that it's run at the function call site and not at the declaration. This limitation is a side effect of the lazy evaluation of SAL annotations. + +## Examples + +In this example, there's a specialized function for logging coordinates. The params annotation specifies the `...` parameter, which doesn't exist. + +```cpp +void LogCoordinate(_Printf_format_string_params_(0) _In_ char *format, int x, int y); + +void func(int x, int y) +{ + LogCoordinate("(%d, %d)", x, y); +} +``` + +This issue is fixed by changing the annotated position to `x` or `1`. To determine the correct value for your code, check the behavior of the called function. + +```cpp +void LogCoordinate(_Printf_format_string_params_(1) _In_ char *format, int x, int y); + +void func(int x, int y) +{ + LogCoordinate("(%d, %d)", x, y); +} +``` + +## See also + +[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md) diff --git a/docs/code-quality/c28309.md b/docs/code-quality/c28309.md index 90102f769b..b5fc4d73a5 100644 --- a/docs/code-quality/c28309.md +++ b/docs/code-quality/c28309.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28309" -title: C28309 +description: "Learn more about: Warning C28309" +title: Warning C28309 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28309"] helpviewer_keywords: ["C28309"] ms.assetid: b3039b80-8623-42f5-8b46-6665e7ba7762 --- -# C28309 +# Warning C28309 -> warning C28309: : Annotation operands must be integer/enum/pointer types. Void operands and C++ overloaded operators are not supported. Floats are approximated as integers. Types: \. +> : Annotation operands must be integer/enum/pointer types. Void operands and C++ overloaded operators are not supported. Floats are approximated as integers. Types: '*typelist*'. You've tried to use a void or a function in an annotation expression, and Code Analysis can't handle it. This error typically occurs when an `operator==` that's implemented as a function is used, but other cases may also occur. Examine the types in \ for clues about what's wrong. diff --git a/docs/code-quality/c28310.md b/docs/code-quality/c28310.md index f700b869ee..30aa4d8244 100644 --- a/docs/code-quality/c28310.md +++ b/docs/code-quality/c28310.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28310" -title: C28310 +title: Warning C28310 +description: "Learn more about: Warning C28310" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28310"] -ms.assetid: 51054ca8-01b6-454b-9853-f05f1c817b18 +helpviewer_keywords: ["C28310"] --- -# C28310 +# Warning C28310 -> warning C28310: The annotation on \ \ has no SAL version. +> The annotation on '*function*' '*parameter*' has no SAL version. -All SAL annotations used in source code should have an annotation version applied by the use of SAL_name. This needs to be corrected in the macro definition. +All SAL annotations used in source code should have an annotation version applied by the use of SAL_name. This issue needs to be corrected in the macro definition. This warning is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. diff --git a/docs/code-quality/c28311.md b/docs/code-quality/c28311.md index 6ca8410a9c..9d72006cae 100644 --- a/docs/code-quality/c28311.md +++ b/docs/code-quality/c28311.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28311" -title: C28311 +title: Warning C28311 +description: "Learn more about: Warning C28311" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28311"] -ms.assetid: 2c76e07a-4418-40ef-8a77-c62774bc3677 +helpviewer_keywords: ["C28311"] --- -# C28311 +# Warning C28311 -> warning C28311: The annotation on \ \ is an obsolescent version of SAL. +> The annotation on '*function*' '*parameter*' is an obsolescent version of SAL. -The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning is not emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. +The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning isn't emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. ## See also diff --git a/docs/code-quality/c28312.md b/docs/code-quality/c28312.md index d9b81cb87d..852d5bec16 100644 --- a/docs/code-quality/c28312.md +++ b/docs/code-quality/c28312.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28312" -title: C28312 +title: Warning C28312 +description: "Learn more about: Warning C28312" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28312"] -ms.assetid: 19828546-33c9-4373-b7df-2a362ca12637 +helpviewer_keywords: ["C28312"] --- -# C28312 +# Warning C28312 -> warning C28312: The annotation on the repeated declaration of \ \ is an obsolescent version of SAL. +> The annotation on the repeated declaration of '*function*' '*parameter*' is an obsolescent version of SAL. -The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning is not emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. +The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning isn't emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. ## See also diff --git a/docs/code-quality/c28350.md b/docs/code-quality/c28350.md index 2e1c8badbd..ef1ffff5ea 100644 --- a/docs/code-quality/c28350.md +++ b/docs/code-quality/c28350.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28350" -title: C28350 +description: "Learn more about: Warning C28350" +title: Warning C28350 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28350"] helpviewer_keywords: ["C28350"] ms.assetid: 912475d6-3856-4bff-86e4-e7bdce21410c --- -# C28350 +# Warning C28350 -> warning C28350: The annotation \ describes a situation that is not conditionally applicable. +> The annotation '*annotation*' describes a situation that is not conditionally applicable. Usually this warning is generated when an annotation is applied where the C/C++ type is being inspected. diff --git a/docs/code-quality/c28351.md b/docs/code-quality/c28351.md index 017692a1f2..b3a45785e0 100644 --- a/docs/code-quality/c28351.md +++ b/docs/code-quality/c28351.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28351" -title: C28351 +description: "Learn more about: Warning C28351" +title: Warning C28351 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28351"] helpviewer_keywords: ["C28351"] ms.assetid: 3535daab-cab1-4167-b860-d6748d8357b5 --- -# C28351 +# Warning C28351 -> warning C28351: The annotation \ describes where a dynamic value (a variable) cannot be used in the condition. +> The annotation '*annotation*' describes where a dynamic value (a variable) cannot be used in the condition. This warning is reported when an annotation is applied where the C/C++ type is being inspected. diff --git a/docs/code-quality/c33001.md b/docs/code-quality/c33001.md index e07584a303..679ffc1e04 100644 --- a/docs/code-quality/c33001.md +++ b/docs/code-quality/c33001.md @@ -1,24 +1,36 @@ --- -title: c33001 +title: Warning C33001 description: C33001 warning for VARIANTs -keywords: c33001 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33001"] +f1_keywords: ["C33001", "VARIANTCLEAR_UNINITIALIZED"] helpviewer_keywords: ["C33001"] -dev_langs: ["C++"] --- -# C33001 +# Warning C33001 -> Warning C33001: VARIANT 'var' was cleared when it was uninitialized (expression 'expr') +> VARIANT '*var*' was cleared when it was uninitialized (expression '*expr*') -This warning is triggered when an uninitialized VARIANT is passed to an API such as VariantClear -that expects an initialized VARIANT. +## Remarks + +This warning is triggered when an uninitialized `VARIANT` is passed to an API, such as `VariantClear`, that clears the object. Initialize the `VARIANT` before passing it to these functions so it can be properly cleared. + +This warning applies to these functions: + +* `VariantClear` +* `PropVariantClear` +* `VariantCopy` +* `VariantCopyInd` +* `VariantChangeType` +* `VariantChangeTypeEx` +* `DestroyPropVariant` + +Code analysis name: `VARIANTCLEAR_UNINITIALIZED` ## Example +The following code causes warning C33001: + ```cpp #include @@ -33,11 +45,11 @@ HRESULT foo(bool some_condition) //... } - VariantClear(&var); // C33001 + VariantClear(&var); // C33001 } ``` -These warnings are corrected by ensuring VariantClear is called only for a properly initialized VARIANT: +In this example, the warning is corrected by calling `VariantClear` only after `var` has been initialized: ```cpp #include @@ -51,12 +63,12 @@ HRESULT foo(bool some_condition) //... VariantInit(&var); //... - VariantClear(&var); // C33001 + VariantClear(&var); // OK } } ``` ## See also -[C33004](./c33004.md) +[C33004](./c33004.md)\ [C33005](./c33005.md) diff --git a/docs/code-quality/c33004.md b/docs/code-quality/c33004.md index 51f70675f1..44486d8ffc 100644 --- a/docs/code-quality/c33004.md +++ b/docs/code-quality/c33004.md @@ -1,24 +1,27 @@ --- -title: c33004 +title: Warning C33004 description: C33004 warning for VARIANTs -keywords: c33004 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33004"] +f1_keywords: ["C33004", "VARIANTCLEAR_UNINITOUTPARAM"] helpviewer_keywords: ["C33004"] -dev_langs: ["C++"] --- -# C33004 +# Warning C33004 -> Warning C33004: VARIANT 'var', which is marked as _Out_ was cleared before being initialized (expression 'expr') +> VARIANT '*var*', which is marked as `_Out_` was cleared before being initialized (expression '*expr*') -This warning is triggered when a VARIANT parameter with \_Out\_ SAL annotation, which may haven't been -initialized on input, is passed to an API such as VariantClear that expects an initialized VARIANT. +## Remarks + +This warning is triggered when a `VARIANT` parameter with `_Out_` SAL annotation may not have been +initialized on input, and is then passed to an API such as `VariantClear` that expects an initialized `VARIANT`. + +Code analysis name: `VARIANTCLEAR_UNINITOUTPARAM` ## Example +The following sample code causes warning C33004: + ```cpp #include @@ -46,5 +49,5 @@ void t2(_Out_ VARIANT* pv) ## See also -[C33001](./c33001.md) +[C33001](./c33001.md)\ [C33005](./c33005.md) diff --git a/docs/code-quality/c33005.md b/docs/code-quality/c33005.md index 9c69e08d18..41509513e3 100644 --- a/docs/code-quality/c33005.md +++ b/docs/code-quality/c33005.md @@ -1,24 +1,26 @@ --- -title: c33005 +title: Warning C33005 description: C33005 warning for VARIANTs -keywords: c33005 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33005"] +f1_keywords: ["C33005", "VARIANTCLEAR_UNINITFUNCPARAM"] helpviewer_keywords: ["C33005"] -dev_langs: ["C++"] --- -# C33005 +# Warning C33005 -> Warning C33005: VARIANT 'var' was provided as an input or input/output parameter but was not initialized (expression 'expr') +> VARIANT '*var*' was provided as an `_In_` or `_InOut_` parameter but was not initialized (expression '*expr*') -This warning is triggered when an uninitialized VARIANT is passed to a function as input-only or input/output -parameter - for example, a pass-by-refrence parameter without an \_Out\_ SAL annotation. +## Remarks + +This warning is triggered when an uninitialized `VARIANT` is passed to a function as an input-only or input/output parameter. For example, a pass-by-reference parameter without an `_Out_` SAL annotation. + +Code analysis name: `VARIANTCLEAR_UNINITFUNCPARAM` ## Example +The following sample code causes warning C33005: + ```cpp #include @@ -33,7 +35,7 @@ void foo() } ``` -These warnings are corrected by ensuring to initialize the VARIANT before passing it to a function +To correct these warnings, initialize the `VARIANT` before passing it to a function as input-only or input/output. ```cpp @@ -53,5 +55,5 @@ void foo() ## See also -[C33001](./c33001.md) +[C33001](./c33001.md)\ [C33004](./c33004.md) diff --git a/docs/code-quality/c33010.md b/docs/code-quality/c33010.md index 5fa8865836..e4c4a598df 100644 --- a/docs/code-quality/c33010.md +++ b/docs/code-quality/c33010.md @@ -1,28 +1,27 @@ --- -title: c33010 +title: Warning C33010 description: C33010 warning for enums -keywords: c33010 author: hwisungi ms.author: hwisungi -ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33010"] +ms.date: 09/08/2022 +f1_keywords: ["C33010", "UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX"] helpviewer_keywords: ["C33010"] -dev_langs: ["C++"] --- -# C33010 +# Warning C33010 -> Warning C33010: Unchecked lower bound for enum 'enum' used as index. +> Unchecked lower bound for enum 'enum' used as index. -This warning is triggered for an enum that is used as an index into an array, -if the upper bound is checked for its value, but not the lower bound. +This warning is triggered if an enum is both used as an index into an array and isn't checked on the lower bound. + +## Remarks + +Code using enumerated types as indexes for arrays will often check for the upper bound in order to ensure the index isn't out of range. Because an enum variable is signed by default, it can have a negative value. A negative array index can allow arbitrary memory to be read, used, or even executed. + +Code analysis name: `UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX` ## Example -Code using enumerated types as indexes for arrays will often check for the upper bound -in order to ensure the index is not out of range. Because an enum variable is signed by default, -it can have a negative value. If it is used as an index into an array of values or an array of function pointers, -a negative value can allow arbitrary memory to be read, used, or even executed. +The following code generates this warning. `idx` is used as an index to access `functions`, but the lower bound is never checked. ```cpp typedef void (*PFN)(); @@ -41,14 +40,13 @@ void foo(Index idx, PFN(&functions)[5]) if (idx > Index::Max) return; - auto pfn = functions[static_cast(idx)]; // C33010 + auto pfn = functions[static_cast(idx)]; if (pfn != nullptr) (*pfn)(); - // ...... } ``` -These warnings are corrected by checking the index value for lower bound as well: +The following code remediates this warning by checking the lower bound as well to ensure `idx` isn't negative: ```cpp typedef void (*PFN)(); @@ -67,10 +65,34 @@ void foo(Index idx, PFN(&functions)[5]) if (idx < Index::Zero || idx > Index::Max) return; - auto pfn = functions[static_cast(idx)]; // OK + auto pfn = functions[static_cast(idx)]; + if (pfn != nullptr) + (*pfn)(); +} +``` + +Alternatively, the issue can be fixed by choosing an underlying type for `Index` that is unsigned. Because an unsigned value is always positive, it is sufficient to only check the upper bound. + +```cpp +typedef void (*PFN)(); + +enum class Index : unsigned int +{ + Zero, + One, + Two, + Three, + Max +}; + +void foo(Index idx, PFN(&functions)[5]) +{ + if (idx > Index::Max) + return; + + auto pfn = functions[static_cast(idx)]; if (pfn != nullptr) (*pfn)(); - // ...... } ``` diff --git a/docs/code-quality/c33011.md b/docs/code-quality/c33011.md index 880d7adb02..f2087f89c8 100644 --- a/docs/code-quality/c33011.md +++ b/docs/code-quality/c33011.md @@ -1,27 +1,26 @@ --- -title: c33011 +title: Warning C33011 description: C33011 warning for enums -keywords: c33011 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33011"] +f1_keywords: ["C33011", "UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX"] helpviewer_keywords: ["C33011"] -dev_langs: ["C++"] --- -# C33011 +# Warning C33011 -> Warning C33011: Unchecked upper bound for enum 'enum' used as index. +> Unchecked upper bound for enum 'enum' used as index. + +## Remarks This warning is triggered for an enum that is used as an index into an array, if the lower bound is checked for its value, but not the upper bound. +Code analysis name: `UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX` + ## Example -Code that uses enumerated types as indexes for arrays must check the enum value for both lower and -upper bounds. If the enum value is checked only for the lower bound before used to index into an array of values -or an array of function pointers, then it can allow arbitrary memory to be read, used, or even executed. +Code that uses enumerated types as indexes for arrays must check the enum value for both lower and upper bounds. If the enum value is checked only for the lower bound before used to index into an array of values (or an array of function pointers), then it can allow arbitrary memory to be read, used, or even executed. ```cpp typedef void (*PFN)(); diff --git a/docs/code-quality/c33020.md b/docs/code-quality/c33020.md index 456bdc80ce..77b698be2a 100644 --- a/docs/code-quality/c33020.md +++ b/docs/code-quality/c33020.md @@ -1,23 +1,26 @@ --- -title: c33020 +title: Warning C33020 description: C33020 warning for HRESULTs -keywords: c33020 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33020"] +f1_keywords: ["C33020", "HRESULT_LIKELY_INCORRECT_USAGE"] helpviewer_keywords: ["C33020"] -dev_langs: ["C++"] --- -# C33020 +# Warning C33020 -> Warning C33020: Likely incorrect HRESULT usage detected. +> Likely incorrect HRESULT usage detected. -This is high-confidence warning indicating that HRESULT-returning function returns FALSE. +## Remarks + +This warning is a high-confidence indication that an HRESULT-returning function returns `FALSE`. + +Code analysis name: `HRESULT_LIKELY_INCORRECT_USAGE` ## Example +The following sample code causes warning C33020: + ```cpp #include @@ -28,7 +31,7 @@ HRESULT foo() } ``` -These warnings are corrected by using proper HRESULT value: +These warnings are corrected by using the proper HRESULT value: ```cpp #include diff --git a/docs/code-quality/c33022.md b/docs/code-quality/c33022.md index 3979bd0ff3..c8385b9a16 100644 --- a/docs/code-quality/c33022.md +++ b/docs/code-quality/c33022.md @@ -1,24 +1,26 @@ --- -title: c33022 +title: Warning C33022 description: C33022 warning for HRESULTs -keywords: c33022 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33022"] +f1_keywords: ["C33022", "HRESULT_USAGE_LOW_CONFIDENCE"] helpviewer_keywords: ["C33022"] -dev_langs: ["C++"] --- -# C33022 +# Warning C33022 -> Warning C33022: Potentially incorrect HRESULT usage detected (low confidence) +> Potentially incorrect HRESULT usage detected (low confidence) -This is low-confidence warning for a function that returns HRESULT, if there is "FALSE" -somewhere along the line that eventually returns it or assigns it to a variable that is returned. +## Remarks + +This warning is a low-confidence indicator for a function that returns HRESULT, that there's a `FALSE` that is either eventually returned, or it's assigned to a variable that is returned. + +Code analysis name: `HRESULT_USAGE_LOW_CONFIDENCE` ## Example +The following sample code causes warning C33022: + ```cpp #include diff --git a/docs/code-quality/c6001.md b/docs/code-quality/c6001.md index 5e03036809..755bb88cb3 100644 --- a/docs/code-quality/c6001.md +++ b/docs/code-quality/c6001.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6001" -title: C6001 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6001"] +description: "Learn more about: Warning C6001" +title: Warning C6001 +ms.date: 10/04/2022 +f1_keywords: ["C6001", "USING_UNINIT_VAR", "__WARNING_USING_UNINIT_VAR"] helpviewer_keywords: ["C6001"] -ms.assetid: 55e779f1-7295-48f7-8ce1-b43898b36cd8 --- -# C6001 +# Warning C6001 -> warning C6001: using uninitialized memory \ +> Using uninitialized memory '*variable*'. -This warning is reported when an uninitialized local variable is used before it is assigned a value. This could lead to unpredictable results. You should always initialize variables before use. +## Remarks + +This warning is reported when an uninitialized local variable is used before it's assigned a value. This usage could lead to unpredictable results. You should always initialize variables before use. + +Code analysis name: `USING_UNINIT_VAR` ## Example -The following code generates this warning because variable `i` is only initialized if `b` is true; otherwise an uninitialized `i` is returned: +The following code generates this warning because variable `i` is only initialized if `b` is true: ```cpp int f( bool b ) @@ -34,7 +36,49 @@ To correct this warning, initialize the variable as shown in the following code: ```cpp int f( bool b ) { - int i= -1; + int i = -1; + + if ( b ) + { + i = 0; + } + return i; +} +``` + +## Heuristics + +The following example shows that passing a variable to a function by reference causes the compiler to assume that it's initialized: + +```cpp +void init( int& i ); + +int f( bool b ) +{ + int i; + + init(i); + + if ( b ) + { + i = 0; + } + return i; // i is assumed to be initialized because it's passed by reference to init() +} +``` + +This supports the pattern of passing a pointer to a variable into an initialization function. + +This heuristic can lead to false negatives because many functions expect pointers that point to initialized data. Use [SAL annotations](annotating-function-parameters-and-return-values.md), such as `_In_` and `_Out_`, to describe the function's behavior. The following example calls a function that expects its argument to be initialized, so a warning is generated: + +```cpp +void use( _In_ int& i ); + +int f( bool b ) +{ + int i; + + use(i); // uninitialized variable warning because of the _In_ annotation on use() if ( b ) { diff --git a/docs/code-quality/c6011.md b/docs/code-quality/c6011.md index 6ff3d15d1a..2094f73796 100644 --- a/docs/code-quality/c6011.md +++ b/docs/code-quality/c6011.md @@ -1,18 +1,21 @@ --- -title: C6011 +title: Warning C6011 description: "Reference for Visual Studio C++ code analysis warning C6011." -ms.date: 03/23/2020 -ms.topic: reference -f1_keywords: ["C6011"] +ms.date: 10/04/2022 +f1_keywords: ["C6011", "DEREF_NULL_PTR", "__WARNING_DEREF_NULL_PTR"] helpviewer_keywords: ["C6011"] ms.assetid: 54b7bc2b-b8f5-43fc-a9a3-8189b03f249a --- -# C6011 +# Warning C6011 -> warning C6011: dereferencing NULL pointer \ +> Dereferencing NULL pointer '*pointer-name*'. + +## Remarks This warning indicates that your code dereferences a potentially null pointer. If the pointer value is invalid, the result is undefined. To resolve the issue, validate the pointer before use. +Code analysis name: `DEREF_NULL_PTR` + ## Example The following code generates this warning because a call to `malloc` might return null if insufficient memory is available: @@ -59,12 +62,35 @@ void f([Pre(Null=Yes)] char* pc) } ``` -The careless use of `malloc` and `free` leads to memory leaks and exceptions. To minimize these kinds of leaks and exception problems altogether, avoid allocating raw memory yourself. Instead, use the mechanisms provided by the C++ Standard Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The careless use of `malloc` and `free` leads to memory leaks and exceptions. To minimize these kinds of leaks and exception problems altogether, avoid allocating raw memory yourself. Instead, use the mechanisms provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and [`vector`](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). + +## Heuristics + +A heuristic used to reduce the number of warnings in legacy code assumes that a pointer is non-`NULL` unless there is evidence that it is `NULL`. In the examples we've seen so far, pointers returned by `malloc` or `new` might be `NULL` because allocation might fail. Another characteristic that the analysis engine uses as evidence of nullability is if the program explicitly checks for `NULL`. This is illustrated in the following examples: + +```cpp +void f(int* n) +{ + *n = 1; // Does not warn, n is assumed to be non-null +} + +void f(int* n) +{ + if (n) { + (*n)++; + } + *n = 1; // Warns because the earlier conditional shows that n might be null +} +``` + +In the second case, the user can fix the warning by moving the `*n = 1` line inside the if block. ## See also - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [NULL](../c-runtime-library/null-crt.md) +- [`NULL`](../c-runtime-library/null-crt.md) - [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) -- [malloc](../c-runtime-library/reference/malloc.md) -- [free](../c-runtime-library/reference/free.md) +- [`malloc`](../c-runtime-library/reference/malloc.md) +- [`free`](../c-runtime-library/reference/free.md) +- [`new` operator](../cpp/new-operator-cpp.md) +- [`delete` operator](../cpp/delete-operator-cpp.md) diff --git a/docs/code-quality/c6014.md b/docs/code-quality/c6014.md index 62e9a6ef12..9806124fb8 100644 --- a/docs/code-quality/c6014.md +++ b/docs/code-quality/c6014.md @@ -1,21 +1,30 @@ --- -description: "Learn more about: C6014" -title: C6014 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6014"] +description: "Learn more about: Warning C6014" +title: Warning C6014 +ms.date: 10/03/2022 +f1_keywords: ["C6014", "MEMORY_LEAK", "__WARNING_MEMORY_LEAK"] helpviewer_keywords: ["C6014"] ms.assetid: ef76ec88-74d2-4a3b-b6fe-4b0851ab3372 --- -# C6014 +# Warning C6014 -> warning C6014: Leaking memory. +> Leaking memory '*pointer-name*'. -This warning indicates that the specified pointer points to allocated memory or some other allocated resource that has not been freed. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +This warning indicates that the specified pointer points to allocated memory or some other allocated resource that hasn't been freed. + +## Remarks + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +This warning is reported for both memory and resource leaks when the resource is commonly *aliased* to another location. Memory is aliased when a pointer to the memory escapes the function by using an `_Out_` parameter annotation, global variable, or return value. This warning can be reported on function exit if the argument is annotated that its release is expected. + +Code Analysis won't recognize the actual implementation of a memory allocator (involving address arithmetic) and won't recognize that memory is allocated (although many wrappers will be recognized). In this case, the analyzer doesn't recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma warning(disable: 6014)` directive on the line that precedes the opening brace `{` of the function body. + +Code analysis name: `MEMORY_LEAK` ## Examples -The following code generates this warning: +The following code generates warning C6014: ```cpp // cl.exe /analyze /EHsc /nologo /W4 @@ -72,11 +81,7 @@ int main( ) } ``` -This warning is reported for both memory and resource leaks when the resource is commonly *aliased* to another location. Memory is aliased when a pointer to the memory escapes the function by means of an `_Out_` parameter annotation, global variable, or return value. This warning can be reported on function exit if the argument is annotated as having been expected to be released. - -Note that Code Analysis will not recognize the actual implementation of a memory allocator (involving address arithmetic) and will not recognize that memory is allocated (although many wrappers will be recognized). In this case, the analyzer does not recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` directive on the line that precedes the opening brace `{` of the function body. - -To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ```cpp // cl.exe /analyze /EHsc /nologo /W4 @@ -92,7 +97,6 @@ const int TEST_DATA [ARRAYSIZE] = {10,20,30,40,50,60,70,80,90,100}; void f( ) { - unique_ptr p(new int[ARRAYSIZE]); std::copy(begin(TEST_DATA), end(TEST_DATA), p.get()); @@ -110,4 +114,4 @@ int main( ) ## See also -[C6211](../code-quality/c6211.md) +[Warning C6211](../code-quality/c6211.md) diff --git a/docs/code-quality/c6029.md b/docs/code-quality/c6029.md index 8f502d08fe..729f39ab08 100644 --- a/docs/code-quality/c6029.md +++ b/docs/code-quality/c6029.md @@ -1,80 +1,92 @@ --- -description: "Learn more about: C6029" -title: C6029 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6029"] +title: Warning C6029 +description: "Learn more about: Warning C6029" +ms.date: 2/07/2023 +f1_keywords: ["C6029", "USING_TAINTED_DATA", "__WARNING_USING_TAINTED_DATA"] helpviewer_keywords: ["C6029"] -ms.assetid: 07f89261-1b77-4597-9f34-12ce5d569b60 --- -# C6029 +# Warning C6029 -> warning C6029: possible buffer overrun in call to \: use of unchecked value +> Possible buffer overrun in call to '*function*' -This warning indicates that a function that takes a buffer and a size is being passed a unchecked size. The data read-in from some external source has not been verified to see whether it is smaller than the buffer size. An attacker might intentionally specify a much larger than expected value for the size, which will lead to a buffer overrun. +Possible buffer overrun in called function due to an unchecked buffer length/size parameter. -Generally, whenever you read data from an untrusted external source, make sure to verify it for validity. It is usually appropriate to verify the size to make sure it is in the expected range. +## Remarks + +This warning indicates that code passes an unchecked size to a function that takes a buffer and a size. The code doesn't verify that the data read from some external source is smaller than the buffer size. An attacker might intentionally specify a larger than expected value for the size, which can lead to a buffer overrun. Generally, whenever you read data from an untrusted external source, make sure to verify it for validity. It's appropriate to verify the size to make sure it's in the expected range. + +Code analysis name: `USING_TAINTED_DATA` ## Example -The following code generates this warning by calling the annotated function [ReadFile](/windows/desktop/api/fileapi/nf-fileapi-readfile) two times. After the first call, the Post attribute property marks the second parameter value untrusted. Therefore, passing an untrusted value in the second call to `ReadFile` generates this warning as shown in the following code: +The following code generates this warning when it calls the annotated function `std::fread` two times. The code uses the first call to determine the length of the data to read in later calls. After the first call, analysis marks `dataSize` as coming from an untrusted source. Therefore, when the code passes the untrusted value to the second `std::fread` call, the analyzer generates this warning. A malicious actor could modify the file and cause the call to `std::fread` to overflow the `buffer` array. In real world code, you should also handle error recovery based on the return value of `std::fread`. For simplicity, these examples intentionally leave out error recovery code. ```cpp +void processData(FILE* file) +{ + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; + + // Read length data from the beginning of the file + fread(&dataSize, sizeof(uint8_t), 1, file); + // Read the rest of the data based on the dataSize + fread(buffer, sizeof(uint32_t), dataSize, file); +} +``` -#include "windows.h" +The fix for the issue depends on the nature of the data and the behavior of the annotated function that triggers the diagnostic. For more information, see the documentation for that function. A straightforward fix is to check the size before the second call to `std::fread`. In the next example, we throw an exception to terminate the function. Most real-world code would instead have an error recovery strategy that's specific to the scenario. -bool f(HANDLE hFile) +```cpp +void processData(FILE* file) { - char buff[MAX_PATH]; + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; - DWORD cbLen; - DWORD cbRead; + fread(&dataSize, sizeof(uint32_t), 1, file); - // Read the number of byte to read (cbLen). - if (!ReadFile (hFile, &cbLen, sizeof (cbLen), &cbRead, NULL)) - { - return false; - } - // Read the bytes - if (!ReadFile (hFile, buff, cbLen, &cbRead, NULL)) // warning C6029 + if (dataSize > MAX_BUFFER_SIZE) { - return false; + throw std::runtime_error("file data unexpected size"); } - return true; + fread(buffer, sizeof(uint32_t), dataSize, file); } ``` -To correct this warning, check the buffer size as shown in the following code: +In `std::fread` and similar functions, the code may need to read large amounts of data. To handle large data, you can allocate the size of the buffer dynamically after the size becomes known. Or, you can call `std::fread` multiple times as needed to read in the rest of the data. If you allocate the buffer dynamically, we recommend you put a limit on the size to avoid introducing an out-of-memory exploit for large values. We don't use this approach in our example because it's already bounded by the size of `uint8_t`. ```cpp -bool f(HANDLE hFile) +void processDataDynamic(FILE* file) { - char buff[MAX_PATH]; + uint8_t dataSize = 0; + fread(&dataSize, sizeof(uint8_t), 1, file); + + // Vector with `dataSize` default initialized objects + std::vector vecBuffer(dataSize); - DWORD cbLen; - DWORD cbRead; + fread(&vecBuffer[0], sizeof(uint32_t), dataSize, file); +} +void processDataMultiple(FILE* file) +{ + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; - // Read the number of byte to read (cbLen). - if (!ReadFile (hFile, &cbLen, sizeof (cbLen), &cbRead, NULL)) - { - return false; - } - // Ensure that there's enough space in the buffer to read that many bytes. - if (cbLen > sizeof(buff)) - { - return false; - } - // Read the bytes - if (!ReadFile (hFile, buff, cbLen, &cbRead, NULL)) // warning C6029 + fread(&dataSize, sizeof(uint32_t), 1, file); + + while( dataSize > 0 ) { - return false; + size_t readSize = dataSize > MAX_BUFFER_SIZE ? MAX_BUFFER_SIZE : dataSize; + readSize = fread(buffer, sizeof(uint32_t), readSize, file); + dataSize = dataSize - readSize; + // Process the data in `buffer`... } - - return true; } ``` ## See also -- [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6030.md b/docs/code-quality/c6030.md new file mode 100644 index 0000000000..d839858cfa --- /dev/null +++ b/docs/code-quality/c6030.md @@ -0,0 +1,39 @@ +--- +title: Warning C6030 +description: "Describes C++ Code Analysis warning C6030 and how to resolve it." +ms.date: 03/10/2023 +f1_keywords: ["C6030", "USE_ATTRIBUTE_NORETURN", "__WARNING_USE_ATTRIBUTE_NORETURN"] +helpviewer_keywords: ["C6030"] +--- + +# Warning C6030 + +> Use attribute [[noreturn]] over __declspec(noreturn) in function '*function-name*' + +## Remarks + +This warning suggests using the C++11 standard attribute [`[[noreturn]]`](../cpp/attributes.md#noreturn) in place of the declspec variant [`__declspec(noreturn)`](../cpp/noreturn.md). The standard attribute provides better cross-platform support because it doesn't rely on language extensions. + +This warning is off by default and isn't part of the `All Rules` rule set. To enable this warning, it must be added to the rule set file being used. + +This check is available in Visual Studio 2022 version 17.0 and later versions. + +Code analysis name: `USE_ATTRIBUTE_NORETURN` + +## Example + +The following code generates C6030: + +```cpp +__declspec(noreturn) void terminate_application(); +``` + +Fix the issue by using the `[[noreturn]]` attribute: + +```cpp +[[noreturn]] void terminate_application(); +``` + +## See also + +[Use Rule Sets to Specify the C++ Rules to Run](./using-rule-sets-to-specify-the-cpp-rules-to-run.md) diff --git a/docs/code-quality/c6031.md b/docs/code-quality/c6031.md index 010c322ebe..541fca4ba5 100644 --- a/docs/code-quality/c6031.md +++ b/docs/code-quality/c6031.md @@ -1,56 +1,62 @@ --- -title: C6031 +title: Warning C6031 description: "Describes C++ Code Analysis warning C6031 and how to resolve it." -ms.date: 03/16/2020 -ms.topic: reference -f1_keywords: ["C6031"] +ms.date: 4/5/2024 +f1_keywords: ["C6031", "RETVAL_IGNORED_FUNC_COULD_FAIL", "__WARNING_RETVAL_IGNORED_FUNC_COULD_FAIL"] helpviewer_keywords: ["C6031"] -ms.assetid: 59e1ef0a-b3ca-4ffa-bcb3-ad2bd22ece22 --- -# C6031 +# Warning C6031 -> warning C6031: return value ignored: *called-function* could return unexpected value +> Return value ignored: '*called-function*' could return unexpected value -This warning indicates the caller doesn't check a function's return value for failure. Depending on which function is being called, this defect can lead to seemingly random program misbehavior. That includes crashes and data corruptions in error conditions or low-resource situations. +## Remarks + +Warning C6031 indicates the caller doesn't check a function's return value for failure. Depending on which function is being called, this defect can lead to seemingly random program misbehavior. That includes crashes and data corruptions in error conditions or low-resource situations. In general, it isn't safe to assume that calls to functions requiring disk, network, memory, or other resources will succeed. The caller should always check the return value and handle error cases appropriately. Also consider using the `_Must_inspect_result_` annotation, which checks that the value is examined in a useful way. +This warning applies to both C and C++ code. + +Code analysis name: `RETVAL_IGNORED_FUNC_COULD_FAIL` + ## Example -The following code generates this warning: +The following code generates warning C6031: -```cpp +```c #include -void f( ) +int main() { - fopen( "test.c", "r" ); // C4996, C6031 return value ignored + fopen("test.c", "r"); // C4996, C6031 return value ignored // code ... } ``` To correct this warning, check the return value of the function as shown in the following code: -```cpp +```c #include -void f( ) +int main() { - FILE *stream; - if ( (stream = fopen( "test.c", "r" )) == NULL ) + FILE* stream; + if ((stream = fopen("test.c", "r")) == NULL) + { return; + } // code ... } ``` The following code uses safe function `fopen_s` to correct this warning: -```cpp +```c #include -void f( ) +int main() { - FILE *stream; + FILE* stream; errno_t err; - if ( (err = fopen_s( &stream, "test.c", "r" )) !=0 ) + if ((err = fopen_s(&stream, "test.c", "r")) != 0) { // code ... } @@ -61,11 +67,14 @@ This warning is also generated if the caller ignores the return value of a funct ```cpp #include -_Check_return_ bool func(); +_Check_return_ bool func() +{ + return true; +} -void test_f() +int main() { - func(); // Warning C6031 + func(); } ``` @@ -73,25 +82,31 @@ To correct the previous warning, check the return value as shown in the followin ```cpp #include -_Check_return_ bool func(); +_Check_return_ bool func() +{ + return true; +} -void test_f() +int main() { - if ( func() ) { + if (func()) + { // code ... } } ``` -In cases where it is necessary to ignore the return value of a function, assign the returned value to `std::ignore`. Assigning to `std::ignore` clearly indicates developer intent and helps in future code maintenance. +In cases where it's necessary to ignore the return value of a function, assign the returned value to `std::ignore`. Assigning to `std::ignore` clearly indicates developer intent and helps in future code maintenance. ```cpp #include #include +#include #include -void f() + +int main() { - std::srand(static_cast(std::time(nullptr))); // set initial seed value to system clock + std::srand(static_cast(std::time(nullptr))); // set initial seed value to system clock std::ignore = std::rand(); // Discard the first result as the few random results are always small. // ... } diff --git a/docs/code-quality/c6053.md b/docs/code-quality/c6053.md index e5ba91e854..426980c787 100644 --- a/docs/code-quality/c6053.md +++ b/docs/code-quality/c6053.md @@ -1,26 +1,28 @@ --- -description: "Learn more about: C6053" -title: C6053 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6053"] +description: "Learn more about: Warning C6053" +title: Warning C6053 +ms.date: 10/04/2022 +f1_keywords: ["C6053", "MISSING_ZERO_TERMINATION1", "__WARNING_MISSING_ZERO_TERMINATION1"] helpviewer_keywords: ["C6053"] ms.assetid: 8e25566a-e3b9-470a-820d-64221a877c53 --- -# C6053 +# Warning C6053 -> warning C6053: call to \ may not zero-terminate string \ +> Call to '*function*' may not zero-terminate string '*variable*'. -This warning indicates that the specified function has been called in such a way that the resulting string might not be zero-terminated. This defect might cause an exploitable buffer overrun or crash. This warning is also generated if an annotated function expects a null terminated string is passed a string that is not null terminated. +## Remarks -Most C standard library and Win32 string handling functions require and produce zero-terminated strings. A few 'counted string' functions (including `strncpy`, `wcsncpy`, `_mbsncpy`, `_snprintf`, and `snwprintf`) do not produce zero-terminated strings if they exactly fill their buffer. In this case, a subsequent call to a string function that expects a zero-terminated string will go beyond the end of the buffer looking for the zero. The program should make sure that the string ends with a zero. In general, you should pass a length to the 'counted string' function one smaller than the size of the buffer and then explicitly assign zero to the last character in the buffer. +This warning indicates that the specified function has been called in such a way that the resulting string might not be zero-terminated. This defect might cause an exploitable buffer overrun or crash. This warning is also generated if an annotated function expects a null-terminated string, but you pass a non-null-terminated string. + +Most C standard library and Win32 string handling functions require and produce zero-terminated strings. A few 'counted string' functions (including `strncpy`, `wcsncpy`, `_mbsncpy`, `_snprintf`, and `snwprintf`) don't produce zero-terminated strings if they exactly fill their buffer. In this case, a subsequent call to a string function that expects a zero-terminated string will go beyond the end of the buffer looking for the zero. The program should make sure that the string ends with a zero. In general, you should pass a length to the 'counted string' function one smaller than the size of the buffer and then explicitly assign zero to the last character in the buffer. + +Code analysis name: `MISSING_ZERO_TERMINATION1` ## Examples The following sample code generates this warning: ```cpp - #include #define MAX 15 @@ -37,7 +39,6 @@ size_t f( ) To correct this warning, zero-terminate the string as shown in the following sample code: ```cpp - #include #define MAX 15 @@ -55,7 +56,6 @@ size_t f( ) The following sample code corrects this warning using safe string manipulation `strncpy_s` function: ```cpp - #include #define MAX 15 @@ -69,9 +69,11 @@ size_t f( ) } ``` -You should note that this warning is sometimes reported on certain idioms guaranteed to be safe in practice. Because of the frequency and potential consequences of this defect, the analysis tool is biased in favor of finding potential issues instead of its typical bias of reducing noise. +## Heuristics + +This warning is sometimes reported on certain idioms guaranteed to be safe in practice. Because of the frequency and potential consequences of this defect, the analysis tool is biased in favor of finding potential issues instead of its typical bias of reducing noise. ## See also - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) diff --git a/docs/code-quality/c6054.md b/docs/code-quality/c6054.md index 8abfba08f3..511c7f6bfa 100644 --- a/docs/code-quality/c6054.md +++ b/docs/code-quality/c6054.md @@ -1,26 +1,27 @@ --- -title: C6054 +title: Warning C6054 description: "Reference guide to Microsoft C++ code analysis warning C6054." -ms.date: 04/22/2020 -ms.topic: reference -f1_keywords: ["C6054"] +ms.date: 10/04/2022 +f1_keywords: ["C6054", "MISSING_ZERO_TERMINATION2", "__WARNING_MISSING_ZERO_TERMINATION2"] helpviewer_keywords: ["C6054"] ms.assetid: d573a5c1-7e74-402b-92e6-8085f967aa50 --- -# C6054 +# Warning C6054 -> warning C6054: string \ may not be zero-terminated +> String '*variable*' may not be zero-terminated. ## Remarks This warning indicates that a function that requires a zero-terminated string was passed a non-zero terminated string. A function that expects a zero-terminated string could look for the zero beyond the end of the buffer. This defect might cause an exploitable buffer overrun error or crash. The program should make sure the string passed in ends with a zero. +Code analysis name: `MISSING_ZERO_TERMINATION2` + ## Example The following code generates this warning: ```cpp -// C6054_bad.cpp +// Warning C6054_bad.cpp // Compile using: cl /W4 /EHsc /c /analyze C6054_bad.cpp #include @@ -51,5 +52,5 @@ void g ( ) ## See also -- [C6053](../code-quality/c6053.md) +- [Warning C6053](../code-quality/c6053.md) - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6059.md b/docs/code-quality/c6059.md index f8c1c0c7b0..d78c0f3f74 100644 --- a/docs/code-quality/c6059.md +++ b/docs/code-quality/c6059.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6059" -title: C6059 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6059"] +description: "Learn more about: Warning C6059" +title: Warning C6059 +ms.date: 12/14/2023 +f1_keywords: ["C6059", "BAD_CONCATENATION", "__WARNING_BAD_CONCATENATION"] helpviewer_keywords: ["C6059"] ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093 --- -# C6059 +# Warning C6059 -> warning C6059: Incorrect length parameter in call to \. Pass the number of remaining characters, not the buffer size of \ +> Incorrect length parameter in call to '*function*'. Pass the number of remaining characters, not the buffer size of '*variable*'. -This warning indicates that a call to a string concatenation function is probably passing an incorrect value for the number of characters to concatenate. This defect might cause an exploitable buffer overrun or crash. A common cause of this defect is passing the buffer size, instead of the remaining number of characters in the buffer, to the string manipulation function. +## Remarks + +This warning indicates that a call to a string concatenation function is probably passing an incorrect value for the number of characters to concatenate. This defect might cause an exploitable buffer overrun or crash. A common cause of this defect is passing the buffer size (instead of the remaining number of characters in the buffer) to the string manipulation function. + +This warning helps identify the common error of sending the size of the target buffer instead of the size of the data. It does so by detecting when the size used to allocate the buffer is passed, unchanged, to the function putting data in the buffer. + +Code analysis name: `BAD_CONCATENATION` ## Example -The following code generates this warning: +The following code generates warning C6059: ```cpp #include @@ -24,12 +29,12 @@ The following code generates this warning: void f( ) { char szTarget[MAX]; - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; - strncpy(szTarget,szCity, MAX); + strncpy(szTarget, szCity, MAX); szTarget[MAX -1] = '\0'; - strncat(szTarget, szState, MAX); //wrong size + strncat(szTarget, szState, MAX); // wrong size // code ... } ``` @@ -43,30 +48,30 @@ To correct this warning, use the correct number of characters to concatenate as void f( ) { char szTarget[MAX]; - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; - strncpy(szTarget,szCity, MAX); + strncpy(szTarget, szCity, MAX); szTarget[MAX -1] = '\0'; strncat(szTarget, szState, MAX - strlen(szTarget)); // correct size // code ... } ``` -To correct this warning using the safe string manipulation function, see the following code: +To correct this warning using the safe string manipulation functions `strncpy_s` and `strncat_s`, see the following code: ```cpp #include void f( ) { - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; size_t nTargetSize = strlen(szState) + strlen(szCity) + 1; char *szTarget= new char[nTargetSize]; - strncpy_s(szTarget, nTargetSize, szCity,strlen(szCity)); + strncpy_s(szTarget, nTargetSize, szCity, strlen(szCity)); strncat_s(szTarget, nTargetSize, szState, nTargetSize - strlen(szTarget)); // code ... @@ -74,7 +79,49 @@ void f( ) } ``` +## Heuristics + +This analysis detects when the target buffer size is passed unmodified into the length parameter of the string manipulation function. This warning isn't given if some other value is passed as the length parameter, even if that value is incorrect. + +Consider the following code that generates warning C6059: + +```cpp +#include +#define MAX 25 + +void f( ) +{ + char szTarget[MAX]; + const char *szState ="Washington"; + const char *szCity="Redmond, "; + + strncpy(szTarget, szCity, MAX); + szTarget[MAX -1] = '\0'; + strncat(szTarget, szState, MAX); // wrong size + // code ... +} +``` + +The warning goes away by changing the `MAX` argument to `strncat` to `MAX - 1`, even though the length calculation is still incorrect. + +```cpp +#include +#define MAX 25 + +void f( ) +{ + char szTarget[MAX]; + const char *szState ="Washington"; + const char *szCity="Redmond, "; + + strncpy(szTarget, szCity, MAX); + szTarget[MAX -1] = '\0'; + strncat(szTarget, szState, MAX - 1); // wrong size, but no warning + // code ... +} +``` + ## See also -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -- [strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) diff --git a/docs/code-quality/c6063.md b/docs/code-quality/c6063.md index bd9058ce89..e84940d4b2 100644 --- a/docs/code-quality/c6063.md +++ b/docs/code-quality/c6063.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6063" -title: C6063 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6063"] +description: "Learn more about: Warning C6063" +title: Warning C6063 +ms.date: 2/22/2023 +f1_keywords: ["C6063", "MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6063"] -ms.assetid: 9a4b0684-6c13-4242-a1ab-97980b6cfdc4 --- -# C6063 +# Warning C6063 -> warning C6063: missing string argument to \ corresponding to conversion specifier \ +> Missing string argument to '*function*' that corresponds to conversion specifier '*number*'. -This warning indicates that not enough arguments are being provided to match a format string; at least one of the missing arguments is a string. This defect can cause crashes and buffer overflows (if the called function is of the `sprintf` family), as well as potentially incorrect output. +## Remarks + +This warning indicates that not enough arguments are being provided to match a format string. At least one of the missing arguments is a string. This defect can cause crashes and buffer overflows (if the called function is of the `sprintf` family), and also potentially incorrect output. + +Code analysis name: `MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION` ## Example The following code generates this warning: ```cpp -#include +#include void f( ) { char buff[15]; @@ -26,10 +28,10 @@ void f( ) } ``` -To correct this warning, provide additional arguments as shown in the following code: +To correct this warning, remove the unused format specifier or provide the required arguments as shown in the following code: ```cpp -#include +#include void f( ) { char buff[15]; @@ -40,7 +42,7 @@ void f( ) The following code corrects this warning using safe string manipulation function: ```cpp -#include +#include void f( ) { char buff[15]; @@ -50,4 +52,5 @@ void f( ) ## See also +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) diff --git a/docs/code-quality/c6064.md b/docs/code-quality/c6064.md index 8243a635fa..645f77ff24 100644 --- a/docs/code-quality/c6064.md +++ b/docs/code-quality/c6064.md @@ -1,59 +1,51 @@ --- -description: "Learn more about: C6064" -title: C6064 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6064"] +description: "Learn more about: Warning C6064" +title: Warning C6064 +ms.date: 2/07/2023 +f1_keywords: ["C6064", "MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6064"] -ms.assetid: d8f126aa-b093-440e-820f-65b8e6cffaba --- -# C6064 +# Warning C6064 -> warning C6064: missing integer argument to \ corresponding to conversion specifier \ +> Missing integer argument to '*function-name*' corresponding to conversion specifier '*number*' -This warning indicates that not enough arguments are being provided to match a format string and one of the missing arguments is an integer. This defect can cause incorrect output. +This warning indicates that the code doesn't provide enough arguments to match a format string and one of the missing arguments is an integer. -## Example +## Remarks -The following code generates this warning because an incorrect number of arguments were used in call to `sprintf` and the missing argument was an integer: +This defect is likely to cause incorrect output and, in more dangerous cases, can lead to stack overflow. -```cpp -#include -void f( ) -{ - char buff[15]; - char *string="Hello, World"; +Code analysis name: `MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION` - sprintf(buff,"%s %d", string); -} -``` +## Example -To correct this warning, specify missing arguments as shown in the following code: +The following code generates this warning because it uses an incorrect number of arguments in the call to `sprintf_s` and the missing argument is an integer. If the unsafe function `sprintf` was used instead of the safer variant `sprintf_s`, this code would likely cause a stack overflow instead of just an unexpected output: ```cpp -#include -void f( ) +void f() { - char buff[15]; - char *string = "Hello, World"; - - sprintf(buff,"%s %d",string, strlen(string)); + char buff[8]; + const char *string="Hello"; + sprintf_s(buff, sizeof(buff), "%s %d", string); // Attempts to print "Hello " + // followed by a number up to eleven characters long, depending on the garbage + // found on the stack. Any number other than a single non-negative digit can't + // fit in the 8 char buffer and leave room for the trailing null. If sprintf + // had been used instead, it would overflow. } ``` -The following code uses safe string manipulation function, `sprintf_s` to correct this warning: +To correct this warning, specify missing arguments or adjust the format string. In this example, we add the missing integer value. ```cpp -#include -void f( ) +void f() { - char buff[15]; - char *string="Hello World"; - - sprintf_s(buff,sizeof(buff),"%s %d", string, strlen(string)); + char buff[8]; + const char *string = "Hello"; + sprintf_s(buff, sizeof(buff), "%s %d", string, strlen(string)); } ``` ## See also -[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4473](../error-messages/compiler-warnings/c4473.md) diff --git a/docs/code-quality/c6065.md b/docs/code-quality/c6065.md new file mode 100644 index 0000000000..20ea8e8145 --- /dev/null +++ b/docs/code-quality/c6065.md @@ -0,0 +1,46 @@ +--- +description: "Learn more about: Warning C6065" +title: Warning C6065 +ms.date: 2/22/2023 +f1_keywords: ["C6065", "MISSING_COUNTED_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__MISSING_COUNTED_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] +helpviewer_keywords: ["C6065"] +--- +# Warning C6065 + +> warning C6065: Missing pointer to '*string type*' argument to '*function*' that corresponds to argument 'number' + +## Remarks + +This warning indicates that there's a mismatch between the format specifiers in a string and the types of the associated parameters. The format specifier indicates that at least one of the mismatched arguments should be a pointer to a counted string such as `UNICODE_STRING` or `ANSI_STRING` but it not. This defect can cause crashes, buffer overflows, and potentially incorrect output. + +To fix this warning, determine if the format specifier or the argument matches the intended behavior and modify the other to match. When modifying the format specifier for a counted string, it's recommended to explicitly use the size prefix such as `%wZ` or `%hZ` rather than `%Z` due to compatibility issues between C runtimes (CRT). For more information on CRT compatibility, see the `%Z` row in the [Type field characters documentation](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md#type-field-characters). + +Code analysis name: `MISSING_COUNTED_STRING_ARGUMENT_TO_FORMAT_FUNCTION` + +## Example + +The following code generates this warning because the value passed to printf isn't a pointer: + +```cpp +int PrintDiagnostic(UNICODE_STRING u) +{ + printf("%wZ", u); +} +``` + +In this example, we fix the warning by changing the passed in parameter to be a pointer: + +```cpp +int PrintDiagnostic(UNICODE_STRING u) +{ + printf("%wZ", &u); +} +``` + +## See also + +[format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string)\ +[`ANSI_STRING/_STRING`](/windows/win32/api/ntdef/ns-ntdef-string)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md) diff --git a/docs/code-quality/c6066.md b/docs/code-quality/c6066.md index d2f755aa6e..8ae5f79902 100644 --- a/docs/code-quality/c6066.md +++ b/docs/code-quality/c6066.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6066" -title: C6066 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6066"] +description: "Learn more about: Warning C6066" +title: Warning C6066 +ms.date: 3/02/2023 +f1_keywords: ["C6066", "NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6066"] -ms.assetid: f03c9cf1-d8eb-4731-a66a-da7c924616fb --- -# C6066 +# Warning C6066 -> warning C6066: non-pointer passed as parameter \ when pointer is required in call to \ +> Non-pointer passed as parameter(*number*) when pointer is required in call to '*function*'. -This warning indicates that the format string specifies that a pointer is required, for example, a `%n` or `%p` specification for printf or a `%d` for `scanf`, but a non-pointer is being passed. This defect is likely to cause a crash or corruption of some form. +## Remarks + +This warning indicates that the format string specifies that a pointer is required, but a non-pointer is being passed. A pointer is required, for example, when you use a `%n` or `%p` specification for `printf`, or a `%d` for `scanf`. This defect is likely to cause a crash or corruption of some form. + +Code analysis name: `NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION` ## Example @@ -29,8 +31,7 @@ void f( ) void g( int i ) { - int result; - result = scanf( "%d", i ); // warning C6066 + int result = scanf( "%d", i ); // warning C6066 // code ... } ``` @@ -44,41 +45,38 @@ To correct this warning, the following code passes correct parameters to the `sp void f( ) { char buff[MAX]; - sprintf( buff, "%s %p %d", "Hello, World!", buff, MAX ); // pass buff // code ... } void g( int i ) { - int result; - // code ... - result = scanf( "%d", &i ); // pass the address of i + int result = scanf( "%d", &i ); // pass the address of i // code ... } ``` -The following code use safe string manipulation functions — `sprintf_s` and `scanf_s` — to correct this warning: +The following code uses safe string manipulation functions `sprintf_s` and `scanf_s` to correct this warning: ```cpp void f( ) { char buff[MAX]; - sprintf_s( buff, sizeof(buff), "%s %p %d", "Hello, World!", buff, MAX ); // code ... } void g( int i ) { - int result; - // code ... - result = scanf_s( "%d", &i ); + int result = scanf_s( "%d", &i ); // code ... } ``` -This warning is typically reported because an integer has been used for a `%p` format instead of a pointer. Using an integer in this instance is not portable to 64-bit computers. +This warning is typically reported because an integer has been used for a `%p` format instead of a pointer. Using an integer in this instance isn't portable to 64-bit computers. ## See also -- [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) -- [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6067.md b/docs/code-quality/c6067.md index 9cf2b51d2d..0a181ff13a 100644 --- a/docs/code-quality/c6067.md +++ b/docs/code-quality/c6067.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6067" -title: C6067 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6067"] +description: "Learn more about: Warning C6067" +title: Warning C6067 +ms.date: 3/02/2023 +f1_keywords: ["C6067", "NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6067"] -ms.assetid: 6fbaee53-daaa-4ba5-9b11-2a8066d86240 --- -# C6067 +# Warning C6067 -> warning C6067: parameter \ in call to \ must be the address of the string +> Parameter '*number*' in call to '*function*' must be the address of the string + +## Remarks This warning indicates a mismatch between the format specifier and the function parameter. Even though the warning suggests using the address of the string, you must check the type of parameter a function expects before correcting the problem. For example, a `%s` specification for `printf` requires a string argument, but a `%s` specification in `scanf` requires an address of the string. This defect is likely to cause a crash or corruption of some form. +Code analysis name: `NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION` + ## Example The following code generates this warning because an integer is passed instead of a string: @@ -25,7 +27,7 @@ The following code generates this warning because an integer is passed instead o void f_defective() { char *str = "Hello, World!"; - printf("String:\n %s", 1); // warning + printf("String:\n %s", 1); // code ... } ``` @@ -97,6 +99,9 @@ void f_safe() ## See also -- [sprintf\_s, \_sprintf\_s\_l, swprintf\_s, \_swprintf\_s\_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) -- [printf, \_printf\_l, wprintf, \_wprintf\_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) -- [scanf\_s, \_scanf\_s\_l, wscanf\_s, \_wscanf\_s\_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[sprintf\_s, \_sprintf\_s\_l, swprintf\_s, \_swprintf\_s\_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[printf, \_printf\_l, wprintf, \_wprintf\_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)\ +[scanf\_s, \_scanf\_s\_l, wscanf\_s, \_wscanf\_s\_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6101.md b/docs/code-quality/c6101.md index 6294816d29..ee653b08a8 100644 --- a/docs/code-quality/c6101.md +++ b/docs/code-quality/c6101.md @@ -1,14 +1,86 @@ --- -description: "Learn more about: C6101" -title: C6101 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6101"] +description: "Learn more about: Warning C6101" +title: Warning C6101 +ms.date: 02/7/2023 +f1_keywords: ["C6101", "RETURN_UNINIT_VAR", "__WARNING_RETURN_UNINIT_VAR"] helpviewer_keywords: ["C6101"] -ms.assetid: 8546367c-5de5-479a-a231-c15c0aa89ef1 --- -# C6101 +# Warning C6101 -> warning C6101: Returning uninitialized memory +> Returning uninitialized memory '*parameter-name*'. -A successful path through the function does not set the named `_Out_` parameter. This message is generated based on SAL annotations that indicate that the function in question always succeeds. A function that doesn't return a success/failure indication should set all of its `_Out_` parameters because the analyzer assumes that the `_Out_` parameter is uninitialized data before the function is called, and that the function will set the parameter so that it's no longer uninitialized. If the function does indicate success/failure, then the `_Out_` parameter doesn't have to be set in the case of failure, and you can detect and avoid the uninitialized location. In either case, the objective is to avoid the reading of an uninitialized location. If the function sometimes doesn't touch an `_Out_` parameter that's subsequently used, then the parameter should be initialized before the function call and be marked with the `_Inout_` annotation, or the more explicit `_Pre_null_` or `_Pre_satisfies_()` when appropriate. "Partial success" can be handled with the `_When_` annotation. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +A successful path through the function doesn't set the `_Out_` annotated parameter. + +## Remarks + +The purpose of this warning is to avoid the use of uninitialized values by callers of the function. The analyzer assumes callers don't initialize any parameters annotated with `_Out_` before the function call, and checks that the function initializes them. The analyzer doesn't emit this warning if the function returns a value that indicates it had an error or wasn't successful. To fix this issue, make sure to initialize the `_Out_` parameter under all successful return paths. The error message contains the line numbers of an example path that doesn't initialize the parameter. + +If the initialization behavior is by design, then incorrect or missing SAL annotations are a likely cause for the warning. You can typically resolve these cases in one of two ways: Either change `_Out_` to a more appropriate annotation, or use the `_Success_()` annotation to help define the success/error states of the function. It's important for the static analysis tools to have correct annotations on the function when analyzing the call sites of the function. + +### Fix by changes to parameter annotations + +If the parameter should already be in an initialized state and the function conditionally modifies it, then the `_Inout_` annotation may be more appropriate. If no other high level annotation fits the intended behavior, you can use low level annotations such as `_Pre_null_`, `_Pre_satisfies_()`, and `_Post_satisfies_()` that provide extra flexibility and control over the expected state of the parameter. For more information on parameter annotations, see [Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md). + +### Fix by defining successful return paths + +The analyzer only emits this warning when the code doesn't initialize an `_Out_` parameter in the success paths of the function. If there's no `_Success_` annotation and no function return type annotation, then it considers all return paths successful. For more information on `_Success_` and similar annotations, see [Success/Failure annotations](./annotating-function-behavior.md#successfailure-annotations). + +Code analysis name: `RETURN_UNINIT_VAR` + +## Example + +The following code generates this warning. Because the function returns `void`, the analyzer considers all paths successful. In this case, the correct fix would probably be to adjust the logic of the `if` statement, but in real world code it's typically not as straightforward and the solution depends on the intended behavior of the function. + +```cpp +#include +void AlwaysInit(_Out_ int* output, int input) // : warning C6101: Returning uninitialized memory '*p'.: Lines: 2, 4, 9, 14, 2 +{ + if( input > 0 ) + { + *output = input; + return; + } + else if( input < 0 ) + { + *output = 0; + return; + } + return; // Oops, input was 0 +} +``` + +To make the solution more interesting, we assume that it isn't valid to initialize `output` when `input` is `0`. One approach is to modify the function return value to a different type, such as `bool`. Then, add a `_Success_` annotation to define the successful return paths. + +```cpp +_Success_(return == true) +bool InitNotZero(_Out_ int* output, int input) +{ + if( input > 0 ) + { + *output = input; + return true; + } + else if( input < 0 ) + { + *output = 0; + return true; + } + return false; +} +``` + +If this pattern is common in your codebase, you can add the annotation to the return type. Error codes such as HRESULT from the Windows SDK give you the behavior of the `_Success_` annotation without needing to add it to each function. If you already use an annotated type as a return type and want to override the behavior, then add the annotation to the function, as shown in the previous example. + +```cpp +using SuccessWhenTrue = _Success_(return == true) bool; + +SuccessWhenTrue InitNotZero(_Out_ int* output, int input) +{ + // ... +} +``` + +## See also + +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to Reduce C/C++ Code Defects](./using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6102.md b/docs/code-quality/c6102.md index a1abbc5157..9c35f2bc5a 100644 --- a/docs/code-quality/c6102.md +++ b/docs/code-quality/c6102.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C6102" -title: C6102 +title: Warning C6102 +description: "Learn more about: Warning C6102" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6102"] -ms.assetid: cfd49a8c-df46-48de-8dcb-02ecf2450034 +helpviewer_keywords: ["C6102"] --- -# C6102 +# Warning C6102 -> warning C6102: Using \ from failed function call at line \. +> Using '*variable*' from failed function call at line '*location*'. -This warning is reported instead of [C6001](../code-quality/c6001.md) when a variable is not set because it was marked as an `_Out_` parameter on a prior function call that failed. +This warning is reported instead of [C6001](../code-quality/c6001.md) when a variable isn't set because it was marked as an `_Out_` parameter on a prior function call that failed. -The problem might be that the prior called function is not completely annotated. It may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation. +The problem might be that the prior called function isn't fully annotated. It may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation. ## See also diff --git a/docs/code-quality/c6103.md b/docs/code-quality/c6103.md index 2a24fa43d1..6c9dfdcfcd 100644 --- a/docs/code-quality/c6103.md +++ b/docs/code-quality/c6103.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C6103" -title: C6103 +title: Warning C6103 +description: "Learn more about: Warning C6103" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6103"] -ms.assetid: 22d1ab35-31a3-4ba9-8ef4-7a64bce66621 +helpviewer_keywords: ["C6103"] --- -# C6103 +# Warning C6103 -> warning C6103: Returning \ from failed function call at line \. +> Returning '*variable*' from failed function call at line '*location*'. A successful path through the function is returning a variable that was used as an `_Out_` parameter to an internal function call that failed. -The problem might be that the called function and the calling function are not completely annotated. The called function may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation, and the calling function may require a `_Success_` annotation. Another possible cause for this warning is that the `_Success_` annotation on the called function is incorrect. +The problem might be that the called function and the calling function aren't fully annotated. The called function may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation, and the calling function may require a `_Success_` annotation. Another possible cause for this warning is that the `_Success_` annotation on the called function is incorrect. ## See also diff --git a/docs/code-quality/c6200.md b/docs/code-quality/c6200.md index f8f0234c51..2106582d1a 100644 --- a/docs/code-quality/c6200.md +++ b/docs/code-quality/c6200.md @@ -1,46 +1,73 @@ --- -description: "Learn more about: C6200" -title: C6200 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6200"] +description: "Learn more about: Warning C6200" +title: Warning C6200 +ms.date: 08/16/2022 +f1_keywords: ["C6200", "INDEX_EXCEEDS_MAX_NONSTACK", "__WARNING_INDEX_EXCEEDS_MAX_NONSTACK"] helpviewer_keywords: ["C6200"] ms.assetid: bbeb159b-4e97-4317-9a07-bb83cd03069a --- -# C6200 +# Warning C6200 -> warning C6200: index \ is out of valid index range \ to \ for non-stack buffer \ +> Index '*index*' is out of valid index range '*min*' to '*max*' for nonstack buffer '*parameter-name*' -This warning indicates that an integer offset into the specified array exceeds the maximum bounds of that array. This defect might cause random behavior or crashes. +This warning indicates that an integer offset into the specified nonstack array exceeds the maximum bounds of that array, causing undefined behavior and potentially crashes. + +## Remarks One common cause of this defect is using the size of an array as an index into the array. Because C/C++ array indexing is zero-based, the maximum legal index into an array is one less than the number of array elements. +Code analysis name: `INDEX_EXCEEDS_MAX_NONSTACK` + ## Example -The following code generates this warning because the **`for`** loop exceeds the index range: +The following code generates this warning. This issue stems from the **`for`** loop exceeding the index range, attempting to access index 14 (the 15th element) when index 13 (the 14th element) is the last: ```cpp -int buff[14]; // array of 0..13 elements void f() { - for (int i=0; i<=14;i++) // i exceeds the index - { - buff[i]= 0; // warning C6200 - // code... - } + int* buff = new int[14]; // array of 0..13 elements + for (int i = 0; i <= 14; i++) // i exceeds the index + { + buff[i] = 0; // warning C6200 + } + delete[] buff; } ``` To correct both warnings, use correct array size as shown in the following code: ```cpp -int buff[14]; // array of 0..13 elements void f() { - for ( int i=0; i < 14; i++) // loop stops when i < 14 - { - buff[i]= 0; // initialize buffer - // code... - } + int* buff = new int[14]; // array of 0..13 elements + for (int i = 0; i < 14; i++) // i == 13 on the final iteration + { + buff[i] = 0; // initialize buffer + } + delete[] buff; } ``` + +## Heuristics + +Code analysis can't always prove whether an array index is in range. This can happen, for example, when the index is computed from a complex expression, including those expressions that call into other functions. In these cases, code analysis may fall back on other clues to determine the range an array index expression may fall into. + +For example, consider the following function that uses `rand()` in index calculations as a stand-in for a function call that code analysis can't analyze: + +```cpp +#include + +void f() +{ + int* buff = new int[14]; + for (int i = 1; i < 14; i++) + { + buff[rand()] = 0; // no warning, nothing is known about the return value of rand() + buff[rand() % 15] = 0; // warning C6200, rand() % 15 is known to be in the range 0..14 and index 14 is out of bounds + buff[rand() % 14] = 0; // no warning, rand() % 14 is known to be in the range 0..13 + } + delete[] buff; +} +``` + +Code analysis doesn't warn with just `rand()` because it doesn't have any information about its return value. On the other hand, `rand() % 15` and `rand() % 14` provide hints as to the range of the return value of `rand()` and code analysis can use that information to determine that the index is out of bounds in the first case but not the second. diff --git a/docs/code-quality/c6201.md b/docs/code-quality/c6201.md index 69b122ae80..85118a0503 100644 --- a/docs/code-quality/c6201.md +++ b/docs/code-quality/c6201.md @@ -1,46 +1,52 @@ --- -description: "Learn more about: C6201" -title: C6201 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6201"] +description: "Learn more about: Warning C6201" +title: Warning C6201 +ms.date: 11/17/2023 +f1_keywords: ["C6201", "INDEX_EXCEEDS_MAX", "__WARNING_INDEX_EXCEEDS_MAX"] helpviewer_keywords: ["C6201"] -ms.assetid: eefbbd77-007c-4f28-95f6-6de5ee6a27db --- -# C6201 +# Warning C6201 -> warning C6201: buffer overrun for \, which is possibly stack allocated: index \ is out of valid index range \ to \ +> Index '*index-name*' is out of valid index range '*minimum*' to '*maximum*' for possibly stack allocated buffer '*variable*' -This warning indicates that an integer offset into the specified stack array exceeds the maximum bounds of that array. This defect might cause random behavior or crashes. +This warning indicates that an integer offset into the specified stack array exceeds the maximum bounds of that array. It might potentially cause stack overflow errors, undefined behavior, or crashes. + +## Remarks One common cause of this defect is using an array's size as an index into the array. Because C/C++ array indexing is zero-based, the maximum legal index into an array is one less than the number of array elements. +Code analysis name: `INDEX_EXCEEDS_MAX` + ## Example -The following code generates this warning because the array index is out of the valid range: +The following code generates warning C6201. The **`for`** loop condition exceeds the valid index range for `buff` when it sets `i` to 14, which is one element past the end: ```cpp -void f( ) +void f() { - int buff[25]; - for (int i=0; i <= 25; i++) // i exceeds array bound - { - buff[i]=0; // initialize i - // code ... - } + int buff[14]; // array of 0..13 elements + for (int i = 0; i <= 14; i++) // i == 14 exceeds the bounds + { + buff[i] = 0; // initialize buffer + } } ``` -To correct both warnings, use the correct array size as shown in the following code: +To correct the warning, make sure the index stays in bounds. The following code shows the corrected loop condition: ```cpp -void f( ) +void f() { - int buff[25]; - for (int i=0; i < 25; i++) - { - buff[i]=0; // initialize i - // code ... - } + int buff[14]; // array of 0..13 elements + for (int i = 0; i < 14; i++) // i == 13 on the final iteration + { + buff[i]= 0; // initialize buffer + } } ``` + +## Heuristics + +This analysis is limited to stack-allocated arrays. It doesn't consider, for example, arrays passed into the function with a Microsoft source code annotation language ([SAL](understanding-sal.md))-annotated length. + +This analysis can't catch all possible out of bounds indices because not all arithmetic can be precisely analyzed. It's tuned to report cases where it can guarantee an out of bounds index is possible. The absence of a warning doesn't mean the index is guaranteed to be in bounds. diff --git a/docs/code-quality/c6211.md b/docs/code-quality/c6211.md index c162cbb675..10fe4fad3b 100644 --- a/docs/code-quality/c6211.md +++ b/docs/code-quality/c6211.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6211" -title: C6211 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6211"] +description: "Learn more about: Warning C6211" +title: Warning C6211 +ms.date: 10/03/2022 +f1_keywords: ["C6211", "MEMORY_LEAK_EXCEPTION", "__WARNING_MEMORY_LEAK_EXCEPTION"] helpviewer_keywords: ["C6211"] ms.assetid: 9b68243b-534c-4a05-b789-bb155dfcba1e --- -# C6211 +# Warning C6211 -> warning C6211: Leaking memory \ due to an exception. Consider using a local catch block to clean up memory +> Leaking memory '*pointer*' due to an exception. Consider using a local catch block to clean up memory -This warning indicates that allocated memory is not being freed when an exception is thrown. The statement at the end of the path could throw an exception. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +This warning indicates that allocated memory isn't freed when an exception is thrown. The statement at the end of the path could throw an exception. + +## Remarks + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +Code analysis name: `MEMORY_LEAK_EXCEPTION` ## Example -The following code generates this warning because an exception could be thrown during the second allocation and thereby leak the first allocation, or an exception could be thrown somewhere in the code that's represented by the "`code ...`" comment and thereby leak both allocations. +The following code generates warning C6211 because an exception could be thrown during the second allocation and thereby leak the first allocation. Or, an exception could be thrown somewhere in the code that's represented by the "`code ...`" comment and thereby leak both allocations. ```cpp // cl.exe /analyze /c /EHsc /nologo /W4 @@ -70,7 +75,7 @@ void f() } ``` -To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ```cpp // cl.exe /analyze /c /EHsc /nologo /W4 @@ -107,4 +112,4 @@ void f( ) ## See also -[C++ Exception Handling](../cpp/exception-handling-in-visual-cpp.md) +[C++ exception handling](../cpp/exception-handling-in-visual-cpp.md) diff --git a/docs/code-quality/c6214.md b/docs/code-quality/c6214.md index 5bfd7b0c83..81284cb8b7 100644 --- a/docs/code-quality/c6214.md +++ b/docs/code-quality/c6214.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6214" -title: C6214 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6214"] +description: "Learn more about: Warning C6214" +title: Warning C6214 +ms.date: 10/03/2022 +f1_keywords: ["C6214", "CAST_HRESULT_TO_BOOL", "__WARNING_CAST_HRESULT_TO_BOOL"] helpviewer_keywords: ["C6214"] ms.assetid: 233e2395-61c1-4a3b-a54b-f19a9ffc31a8 --- -# C6214 +# Warning C6214 -> warning C6214: cast between semantically different integer types: HRESULT to a Boolean type +> Cast between semantically different integer types: HRESULT to a Boolean type -This warning indicates that an `HRESULT` is being cast to a Boolean type. The success value (`S_OK`) of an `HRESULT` equals 0. However, 0 indicates failure for a Boolean type. Casting an `HRESULT` to a Boolean type and then using it in a test expression will yield an incorrect result. Sometimes, this warning occurs if an `HRESULT` is being stored in a Boolean variable. Any comparison that uses the Boolean variable to test for `HRESULT` success or failure could lead to incorrect results. +This warning indicates that an `HRESULT` is being cast to a Boolean type. The success value (`S_OK`) of an `HRESULT` equals 0. However, 0 indicates failure for a Boolean type. Casting an `HRESULT` to a Boolean type and then using it in a test expression will yield an incorrect result. + +## Remarks + +Sometimes, this warning occurs if an `HRESULT` is being stored in a Boolean variable. Any comparison that uses the Boolean variable to test for `HRESULT` success or failure could lead to incorrect results. + +Code analysis name: `CAST_HRESULT_TO_BOOL` ## Example -The following code generates this warning: +The following code generates warning C6214: ```cpp #include @@ -66,10 +71,10 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. Usually, the `SUCCEEDED` or `FAILED` macro should be used to test the value of an `HRESULT`. -For more information, see one of the following topics: +For more information, see one of the following articles: -[SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) +[`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) -[FAILED](/windows/desktop/api/winerror/nf-winerror-failed) +[`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) -To leverage modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To make use of modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6215.md b/docs/code-quality/c6215.md index a332c868c3..9e58ca0e1f 100644 --- a/docs/code-quality/c6215.md +++ b/docs/code-quality/c6215.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6215" -title: C6215 +description: "Learn more about: Warning C6215" +title: Warning C6215 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6215"] +f1_keywords: ["C6215", "CAST_BOOL_TO_HRESULT", "__WARNING_CAST_BOOL_TO_HRESULT"] helpviewer_keywords: ["C6215"] ms.assetid: f20cc258-9c0f-4eaa-828d-74f76580ca78 --- -# C6215 +# Warning C6215 -> warning C6215: cast between semantically different integer types: a Boolean type to HRESULT +> Cast between semantically different integer types: a Boolean type to HRESULT This warning indicates that a Boolean is being cast to an `HRESULT`. Boolean types indicate success by a non-zero value, whereas success (`S_OK`) in `HRESULT` is indicated by a value of 0. Casting a Boolean type to an `HRESULT` and then using it in a test expression will yield an incorrect result. +## Remarks + This warning frequently occurs when a Boolean is used as an argument to `SUCCEEDED` or `FAILED` macro, which explicitly casts their arguments to an `HRESULT`. +Code analysis name: `CAST_BOOL_TO_HRESULT` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6216.md b/docs/code-quality/c6216.md index d8f4d7463f..4f7cb22742 100644 --- a/docs/code-quality/c6216.md +++ b/docs/code-quality/c6216.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: C6216" -title: C6216 +description: "Learn more about: Warning C6216" +title: Warning C6216 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6216"] +f1_keywords: ["C6216", "COMPILER_INSERTED_CAST_BOOL_TO_HRESULT", "__WARNING_COMPILER_INSERTED_CAST_BOOL_TO_HRESULT"] helpviewer_keywords: ["C6216"] ms.assetid: d5c4dcf9-bfd7-4604-804f-9cc41b08d060 --- -# C6216 +# Warning C6216 -> warning C6216: compiler-inserted cast between semantically different integral types: a Boolean type to HRESULT +> Compiler-inserted cast between semantically different integral types: a Boolean type to HRESULT -A Boolean type is being used as an `HRESULT` without being explicitly cast. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. This means a Boolean false value used as an `HRESULT` would indicate `S_OK`, which is frequently a mistake. +A Boolean type is being used as an `HRESULT` without being explicitly cast. + +## Remarks + +Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. A Boolean `false` value used as an `HRESULT` would indicate `S_OK`, which is frequently a mistake. + +Code analysis name: `COMPILER_INSERTED_CAST_BOOL_TO_HRESULT` ## Example diff --git a/docs/code-quality/c6217.md b/docs/code-quality/c6217.md index aa5952e472..410cfb0fa5 100644 --- a/docs/code-quality/c6217.md +++ b/docs/code-quality/c6217.md @@ -1,21 +1,27 @@ --- -description: "Learn more about: C6217" -title: C6217 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6217"] +description: "Learn more about: Warning C6217" +title: Warning C6217 +ms.date: 2/07/2023 +f1_keywords: ["C6217", "TESTING_HRESULT_WITH_NOT", "__WARNING_TESTING_HRESULT_WITH_NOT"] helpviewer_keywords: ["C6217"] -ms.assetid: 93ac7ce2-c27b-4b3a-9a98-72f26fcf1def --- -# C6217 +# Warning C6217 -> warning C6217: Implicit cast between semantically different integer types: testing HRESULT with 'not'. Consider using [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) or [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macro instead. +> Implicit cast between semantically different integer types: testing HRESULT with 'not'. Consider using [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) or [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macro instead. -This warning indicates that an `HRESULT` is being tested with the not (`!`) operator. A success (`S_OK`) in `HRESULT` is indicated by a value of 0. However, 0 indicates failure for a Boolean type. Testing `HRESULT` with the not operator (`!`) to determine which code block to run can cause following the wrong code path. This will lead to unwanted results. +## Remarks + +This warning indicates that the code tests an `HRESULT` with the logical-not (`!`) operator. A value of 0 (the value defined for `S_OK`) indicates success in an `HRESULT`. However, 0 also indicates failure for a Boolean type. If you test an `HRESULT` with the logical-not operator (`!`) to determine which code block to run, it can cause incorrect behavior or code that confuses future maintainers. + +To verify whether an `HRESULT` is a success or failure, use the `SUCCEEDED` or `FAILED` macros instead. + +This warning works for both `HRESULT` and `SCODE` types. + +Code analysis name: `TESTING_HRESULT_WITH_NOT` ## Example -The following code generates this warning because the not operator is used to determine success or failure of an `HRESULT` value. In this case, wrong code path is executed because `( !hr )` runs the failure code: +The following code generates this warning because it uses the logical-not (`!`) operator to determine success or failure of an `HRESULT` value. In this case, the code executes the wrong code path because an `HRESULT` of 0 indicates success, so `( !hr )` incorrectly runs the failure code: ```cpp #include @@ -35,7 +41,7 @@ void f( ) } ``` -To correct this warning, the following code uses `FAILED` macro to look for failure: +To correct this warning, the following code uses a `FAILED` macro to check for failure: ```cpp #include @@ -55,8 +61,7 @@ void f( ) } ``` -For this warning, the `SCODE` type is equivalent to `HRESULT`. - -The typical success value of HRESULT (`S_OK`) is **`false`** when it is tested as a Boolean. +## See also -To verify whether `HRESULT` is a success, use the `SUCCEEDED` macro instead. +[`SUCCEEDED` macro](/windows/desktop/api/winerror/nf-winerror-succeeded)\ +[`FAILED` macro](/windows/desktop/api/winerror/nf-winerror-failed) diff --git a/docs/code-quality/c6219.md b/docs/code-quality/c6219.md index 2447d4eca6..0533f90512 100644 --- a/docs/code-quality/c6219.md +++ b/docs/code-quality/c6219.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6219" -title: C6219 +description: "Learn more about: Warning C6219" +title: Warning C6219 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6219"] +f1_keywords: ["C6219", "COMPARING_HRESULT_TO_ONE", "__WARNING_COMPARING_HRESULT_TO_ONE"] helpviewer_keywords: ["C6219"] ms.assetid: 889a2de8-c0dc-4e8e-a46b-735384202675 --- -# C6219 +# Warning C6219 -> warning C6219: Implicit cast between semantically different integer types: comparing HRESULT to 1 or TRUE. Consider using [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) or [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macro instead +> Implicit cast between semantically different integer types: comparing HRESULT to 1 or TRUE. Consider using [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) or [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macro instead -This warning indicates an `HRESULT` is being compared with an explicit, non-`HRESULT` value of one (1). This comparison is likely to lead to incorrect results, because the typical success value of `HRESULT` (`S_OK`) is 0. If you compare this value to a Boolean type it's implicitly converted to false. +## Remarks + +This warning indicates an `HRESULT` is being compared with an explicit, non-`HRESULT` value of one (1). This comparison is likely to lead to incorrect results, because the typical success value of `HRESULT` (`S_OK`) is 0. If you compare this value to a Boolean type, it's implicitly converted to `false`. + +Code analysis name: `COMPARING_HRESULT_TO_ONE` ## Example diff --git a/docs/code-quality/c6220.md b/docs/code-quality/c6220.md index ea3f5d6a19..aa09af7c41 100644 --- a/docs/code-quality/c6220.md +++ b/docs/code-quality/c6220.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6220" -title: C6220 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6220"] +description: "Learn more about: Warning C6220" +title: Warning C6220 +ms.date: 10/03/2022 +f1_keywords: ["C6220", "COMPARING_HRESULT_TO_MINUS_ONE", "__WARNING_COMPARING_HRESULT_TO_MINUS_ONE"] helpviewer_keywords: ["C6220"] ms.assetid: a13524f4-0a1f-4670-b830-70b06e4d39d2 --- -# C6220 +# Warning C6220 -> warning C6220 - Implicit cast between semantically different integer types: comparing HRESULT to -1. Consider using SUCCEEDED or FAILED macro instead +> Implicit cast between semantically different integer types: comparing HRESULT to -1. Consider using `SUCCEEDED` or `FAILED` macro instead -This warning indicates that an `HRESULT` is being compared with an explicit, non-`HRESULT` value of -1, which is not a well-formed `HRESULT`. A failure in `HRESULT` (`E_FAIL`) is not represented by a -1. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. +This warning indicates that an `HRESULT` is being compared with an explicit, non-`HRESULT` value of -1, which isn't a well-formed `HRESULT`. + +## Remarks + +A failure in `HRESULT` (`E_FAIL`) isn't represented by a -1. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. + +Code analysis name: `COMPARING_HRESULT_TO_MINUS_ONE` ## Example -In most cases, this warning is caused by the code mistakenly expecting that a function that should return an `HRESULT` instead returns an integer, by using -1 as a failure value. The following code sample generates this warning: +In most cases, warning C6220 is caused by code that mistakenly expects a function to return an integer, and to use -1 as a failure value, but instead the function returns an `HRESULT`. The following code sample generates this warning: ```cpp #include @@ -39,7 +44,7 @@ HRESULT f( ) } ``` -It is best to use the `SUCCEEDED` or `FAILED` macro to test the value of an `HRESULT`. To correct this warning, use the following code: +It's best to use the `SUCCEEDED` or `FAILED` macro to test the value of an `HRESULT`. To correct this warning, use the following code: ```cpp #include @@ -67,6 +72,6 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. Explicit comparison is appropriate to check for specific `HRESULT` values, such as, `E_FAIL`. Otherwise, use the `SUCCEEDED` or `FAILED` macros. -For more information, see [SUCCEEDED Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [FAILED Macro](/windows/win32/api/winerror/nf-winerror-failed). +For more information, see [`SUCCEEDED` Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [`FAILED` Macro](/windows/win32/api/winerror/nf-winerror-failed). -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6221.md b/docs/code-quality/c6221.md index 7869db2cbd..4a6dc472a4 100644 --- a/docs/code-quality/c6221.md +++ b/docs/code-quality/c6221.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6221" -title: C6221 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6221"] +description: "Learn more about: Warning C6221" +title: Warning C6221 +ms.date: 10/03/2022 +f1_keywords: ["C6221", "COMPARING_HRESULT_TO_INT", "__WARNING_COMPARING_HRESULT_TO_INT"] helpviewer_keywords: ["C6221"] ms.assetid: b07989b7-f50f-46e0-8ed8-d9269b3d3580 --- -# C6221 +# Warning C6221 -> warning C6221: Implicit cast between semantically different integer types: comparing HRESULT to an integer. Consider using SUCCEEDED or FAILED macros instead +> Implicit cast between semantically different integer types: comparing HRESULT to an integer. Consider using `SUCCEEDED` or `FAILED` macros instead -This warning indicates that an `HRESULT` is being compared to an integer other than zero. A success in `HRESULT` (`S_OK`) is represented by a 0. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. It is often caused by mistakenly expecting a function to return an integer when it actually returns an `HRESULT`. +This warning indicates that an `HRESULT` is being compared to an integer other than zero. + +## Remarks + +A success in an `HRESULT` (`S_OK`) is represented by a 0. Therefore, an implicit cast of an `HRESULT` to an integer generates an incorrect value and is likely to lead to the wrong result. The error is often caused by mistakenly expecting a function to return an integer when it actually returns an `HRESULT`. + +Code analysis name: `COMPARING_HRESULT_TO_INT` ## Example -The following code generates this warning by comparing `HRESULT` against an integer value: +The following code generates warning C6221 by comparing an `HRESULT` against an integer value: ```cpp #include @@ -65,6 +70,6 @@ HRESULT f( ) For this warning, the `SCODE` type is equivalent to `HRESULT`. -For more information, see [SUCCEEDED Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [FAILED Macro](/windows/win32/api/winerror/nf-winerror-failed). +For more information, see [`SUCCEEDED` Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [`FAILED` Macro](/windows/win32/api/winerror/nf-winerror-failed). -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6225.md b/docs/code-quality/c6225.md index 0a3326757a..67997f7dec 100644 --- a/docs/code-quality/c6225.md +++ b/docs/code-quality/c6225.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6225" -title: C6225 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6225"] +description: "Learn more about: Warning C6225" +title: Warning C6225 +ms.date: 10/03/2022 +f1_keywords: ["C6225", "ASSIGNING_ONE_TO_HRESULT", "__WARNING_ASSIGNING_ONE_TO_HRESULT"] helpviewer_keywords: ["C6225"] ms.assetid: 2d98ffec-9842-4cd1-b1a9-9ac9d1d2a136 --- -# C6225 +# Warning C6225 -> warning C6225: Implicit cast between semantically different integer types: assigning 1 or TRUE to HRESULT. Consider using S_FALSE instead +> Implicit cast between semantically different integer types: assigning 1 or `TRUE` to `HRESULT`. Consider using `S_FALSE` instead -This warning indicates that an `HRESULT` is being assigned or initialized with a value of an explicit 1. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. This warning is frequently caused by accidental confusion of Boolean and `HRESULT` types. To indicate success, the symbolic constant `S_OK` should be used. +This warning indicates that an `HRESULT` is being assigned or initialized with a value of an explicit 1. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. + +## Remarks + +This warning is frequently caused by accidental confusion of Boolean and `HRESULT` types. To indicate success, the symbolic constant `S_OK` should be used. + +Code analysis name: `ASSIGNING_ONE_TO_HRESULT` ## Example -In the following code, assignment of `HRESULT` generates this warning: +In the following code, assignment of `HRESULT` generates warning C6225: ```cpp #include @@ -59,10 +64,10 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. To indicate failure, `E_FAIL`, or another constant, should be used. -For more information see one of the following topics: +For more information, see one of the following articles: -[SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) +[`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) -[FAILED](/windows/desktop/api/winerror/nf-winerror-failed) +[`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) -To leverage modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To make use of modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6226.md b/docs/code-quality/c6226.md index e732e6e66a..2a7ed4d40a 100644 --- a/docs/code-quality/c6226.md +++ b/docs/code-quality/c6226.md @@ -1,19 +1,24 @@ --- -description: "Learn more about: C6226" -title: C6226 +description: "Learn more about: Warning C6226" +title: Warning C6226 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6226"] +f1_keywords: ["C6226", "ASSIGNING_MINUS_ONE_TO_HRESULT", "__WARNING_ASSIGNING_MINUS_ONE_TO_HRESULT"] helpviewer_keywords: ["C6226"] ms.assetid: c18aa576-b316-4f11-b48f-f5183fa49c7c --- -# C6226 +# Warning C6226 -> warning C6226: Implicit cast between semantically different integer types: assigning -1 to HRESULT. Consider using E_FAIL instead. +> Implicit cast between semantically different integer types: assigning -1 to HRESULT. Consider using E_FAIL instead. -This warning indicates that an `HRESULT` is assigned or initialized to an explicit value of -1. This warning is frequently caused by accidental confusion of integer and `HRESULT` types. To indicate success, use the symbolic constant `S_OK` instead. To indicate failure, use the symbolic constants that start with E_*constant*, such as `E_FAIL`. +This warning indicates that an `HRESULT` is assigned or initialized to an explicit value of -1. -For more information, see the [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) and [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macros. +## Remarks + +This warning is frequently caused by accidental confusion of integer and `HRESULT` types. To indicate success, use the symbolic constant `S_OK` instead. To indicate failure, use the symbolic constants that start with E_*constant*, such as `E_FAIL`. + +For more information, see the [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) and [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macros. + +Code analysis name: `ASSIGNING_MINUS_ONE_TO_HRESULT` ## Example diff --git a/docs/code-quality/c6230.md b/docs/code-quality/c6230.md index 8e620ef7f4..69c8b13048 100644 --- a/docs/code-quality/c6230.md +++ b/docs/code-quality/c6230.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6230" -title: C6230 +description: "Learn more about: Warning C6230" +title: Warning C6230 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6230"] +f1_keywords: ["C6230", "USING_HRESULT_IN_BOOLEAN_CONTEXT", "__WARNING_USING_HRESULT_IN_BOOLEAN_CONTEXT"] helpviewer_keywords: ["C6230"] ms.assetid: aa91291d-cdc5-4720-89d4-194ce0557e99 --- -# C6230 +# Warning C6230 -> warning C6230: implicit cast between semantically different integer types: using HRESULT in a Boolean context +> Implicit cast between semantically different integer types: using HRESULT in a Boolean context + +## Remarks This warning indicates that a bare `HRESULT` is used in a context where a Boolean result is expected, such as an **`if`** statement. This test is likely to yield incorrect results. For example, the typical success value for `HRESULT` (`S_OK`) is false when it's tested as a Boolean. +Code analysis name: `USING_HRESULT_IN_BOOLEAN_CONTEXT` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6235.md b/docs/code-quality/c6235.md index c7ee95d2df..3259ac77f3 100644 --- a/docs/code-quality/c6235.md +++ b/docs/code-quality/c6235.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6235" -title: C6235 +description: "Learn more about: Warning C6235" +title: Warning C6235 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6235"] +f1_keywords: ["C6235", "NONZEROLOGICALOR", "__WARNING_NONZEROLOGICALOR"] helpviewer_keywords: ["C6235"] ms.assetid: e225955e-0bb5-43a4-a83d-83290e209df4 --- -# C6235 +# Warning C6235 -> warning C6235: (\ || \) is always a non-zero constant +> ('*non-zero constant*' \|\| '*expression*') is always a non-zero constant -This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-or operation that occurs in a test context. The right side of the logical-or operation is not evaluated because the resulting expression always evaluates to true. This is referred to as "short-circuit evaluation." +This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-or operation that occurs in a test context. The right side of the logical-or operation isn't evaluated because the resulting expression always evaluates to true. This language feature is referred to as "short-circuit evaluation." -A non-zero constant value, other than one, suggests that the bitwise-AND operator (`&`) may have been intended. This warning is not generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths, but it is generated if the non-zero constant evaluates to 1, for example 1+0. +## Remarks + +A non-zero constant value, other than one, suggests that the bitwise-AND operator (`&`) may have been intended. This warning isn't generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths. However, it's generated if the non-zero constant evaluates to 1, for example `1+0`. + +Code analysis name: `NONZEROLOGICALOR` ## Example diff --git a/docs/code-quality/c6236.md b/docs/code-quality/c6236.md index 0f752ac985..b75a4c1904 100644 --- a/docs/code-quality/c6236.md +++ b/docs/code-quality/c6236.md @@ -1,23 +1,26 @@ --- -description: "Learn more about: C6236" -title: C6236 +description: "Learn more about: Warning C6236" +title: Warning C6236 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6236"] +f1_keywords: ["C6236", "LOGICALORNONZERO", "__WARNING_LOGICALORNONZERO"] helpviewer_keywords: ["C6236"] ms.assetid: 3d5ae268-6f40-4c45-a483-b5b0e6a808fc --- -# C6236 +# Warning C6236 -> warning C6236: (\ || \) is always a non-zero constant +> ('*expression*' \|\| '*non-zero constant*') is always a non-zero constant -This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical OR operation that occurs in a test context. Logically, this implies that the test is redundant and can be removed safely. Alternatively, it suggests that the programmer may have intended to use a different operator, for example, the equality (`==`), bitwise-AND (`&`) or bitwise-XOR (`^`) operator, to test for a specific value or flag. +This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical OR operation that occurs in a test context. Logically, it implies that the test is redundant and can be removed safely. Alternatively, it suggests that the programmer may have intended to use a different operator, for example, the equality (`==`), bitwise-AND (`&`) or bitwise-XOR (`^`) operator, to test for a specific value or flag. -This warning is not generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths at compile time. However, the warning is generated if the non-zero constant is formed by an expression that evaluates to 1, for example, 1 + 0. +## Remarks + +This warning isn't generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths at compile time. However, the warning is generated if the non-zero constant is formed by an expression that evaluates to 1, for example, 1 + 0. + +Code analysis name: `LOGICALORNONZERO` ## Example -This code shows how warning C6236 can appear. Because `INPUT_TYPE` is not 0, the expression `n || INPUT_TYPE` is always non-zero, and the **`else`** clause is never executed. However, `INPUT_TYPE` is a constant with a value other than one, which suggests that it is meant as a value for comparison: +This code shows how warning C6236 can appear. Because `INPUT_TYPE` isn't 0, the expression `n || INPUT_TYPE` is always non-zero, and the **`else`** clause is never executed. However, `INPUT_TYPE` is a constant with a value other than one, which suggests that it's meant as a value for comparison: ```cpp #define INPUT_TYPE 2 diff --git a/docs/code-quality/c6237.md b/docs/code-quality/c6237.md index 9cb3a4602a..e80bb7c8e2 100644 --- a/docs/code-quality/c6237.md +++ b/docs/code-quality/c6237.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: C6237" -title: C6237 +description: "Learn more about: Warning C6237" +title: Warning C6237 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6237"] +f1_keywords: ["C6237", "ZEROLOGICALANDLOSINGSIDEEFFECTS", "__WARNING_ZEROLOGICALANDLOSINGSIDEEFFECTS"] helpviewer_keywords: ["C6237"] ms.assetid: a18d8630-e4d6-4132-b976-c1f3e7c5c3f0 --- -# C6237 +# Warning C6237 -> warning C6237: (\ && \) is always zero. \ is never evaluated and may have side effects +> ('*zero*' && '*expression*') is always zero. '*expression*' is never evaluated and may have side effects -This warning indicates that a constant value of zero was detected on the left side of a logical-and operation that occurs in a test context. The resulting expression always evaluates to false. Therefore, the right side of the logical-AND operation is not evaluated. This is referred to as "short-circuit evaluation." +This warning indicates that a constant value of zero was detected on the left side of a logical-and operation that occurs in a test context. The resulting expression always evaluates to false. Therefore, the right side of the logical-AND operation isn't evaluated. This language feature is referred to as "short-circuit evaluation." -You should examine the right side of the expression carefully to ensure that any side effects such as assignment, function call, increment, and decrement operations needed for proper functionality are not affected by the short-circuit evaluation. +## Remarks + +You should examine the right side of the expression carefully: Ensure that any side effects such as assignment, function call, increment, and decrement operations needed for proper functionality aren't affected by the short-circuit evaluation. The expression (`0 && n`) produces no side effects and is commonly used to selectively choose code paths. +Code analysis name: `ZEROLOGICALANDLOSINGSIDEEFFECTS` + ## Example The following code shows various code samples that generate this warning: diff --git a/docs/code-quality/c6239.md b/docs/code-quality/c6239.md index 7abc7ca7f2..de5189b9b3 100644 --- a/docs/code-quality/c6239.md +++ b/docs/code-quality/c6239.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6239" -title: C6239 +description: "Learn more about: Warning C6239" +title: Warning C6239 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6239"] +f1_keywords: ["C6239", "NONZEROLOGICALAND", "__WARNING_NONZEROLOGICALAND"] helpviewer_keywords: ["C6239"] ms.assetid: c80e02bc-ff54-4fde-8c1c-5852853bed24 --- -# C6239 +# Warning C6239 -> warning C6239: (\ && \) always evaluates to the result of \. Did you intend to use the bitwise-and operator? +> ('*non-zero constant*' && '*expression*') always evaluates to the result of '*expression*'. Did you intend to use the bitwise-and operator? This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-AND operation that occurs in a test context. For example, the expression `( 2 && n )` is reduced to `(!!n)`, which is the Boolean value of `n`. -This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used, and is not generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. +## Remarks + +This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used, and isn't generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. + +Code analysis name: `NONZEROLOGICALAND` ## Example diff --git a/docs/code-quality/c6240.md b/docs/code-quality/c6240.md index 6ba52d6372..1e44d46db2 100644 --- a/docs/code-quality/c6240.md +++ b/docs/code-quality/c6240.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6240" -title: C6240 +description: "Learn more about: Warning C6240" +title: Warning C6240 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6240"] +f1_keywords: ["C6240", "LOGICALANDNONZERO", "__WARNING_LOGICALANDNONZERO"] helpviewer_keywords: ["C6240"] ms.assetid: b9412ae4-622d-4aed-8c34-b67db1ccd48a --- -# C6240 +# Warning C6240 -> warning C6240: (\ && \) always evaluates to the result of \. Did you intend to use the bitwise-and operator? +> ('*expression*' && '*non-zero constant*') always evaluates to the result of '*expression*'. Did you intend to use the bitwise-and operator? This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical-and operation that occurs in a test context. For example, the expression `(n && 3)` reduces to `(!!n)`, which is the Boolean value of `n`. -This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used. It is not generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. +## Remarks + +This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used. It isn't generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. + +Code analysis name: `LOGICALANDNONZERO` ## Example @@ -50,7 +53,7 @@ void f(int n) } else { - puts("bitmak false"); + puts("bitmask false"); } } ``` diff --git a/docs/code-quality/c6242.md b/docs/code-quality/c6242.md index a3f9208b2d..cdb9a7534c 100644 --- a/docs/code-quality/c6242.md +++ b/docs/code-quality/c6242.md @@ -1,22 +1,25 @@ --- -title: C6242 +title: Warning C6242 description: "Describes Microsoft C/C++ compiler warning C6242." ms.date: 08/24/2020 -ms.topic: reference -f1_keywords: ["C6242"] +f1_keywords: ["C6242", "LOCALUNWINDFORCED", "__WARNING_LOCALUNWINDFORCED"] helpviewer_keywords: ["C6242"] ms.assetid: 523d46ce-8370-434c-a752-2e3a18cca9a5 --- -# C6242 +# Warning C6242 -> warning C6242: A jump out of this try-block forces local unwind. Incurs severe performance penalty +> A jump out of this try-block forces local unwind. Incurs severe performance penalty This warning indicates that a jump statement causes control-flow to leave the protected block of a `try-finally` other than by fall-through. +## Remarks + Leaving the protected block of a `try-finally` other than by falling through from the last statement requires local unwind to occur. Local unwind typically requires approximately 1000 machine instructions, so it's detrimental to performance. Use **`__leave`** to exit the protected block of a try-finally. +Code analysis name: `LOCALUNWINDFORCED` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6244.md b/docs/code-quality/c6244.md index e5307d9995..b37d7c116d 100644 --- a/docs/code-quality/c6244.md +++ b/docs/code-quality/c6244.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6244" -title: C6244 +description: "Learn more about: Warning C6244" +title: Warning C6244 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6244"] +f1_keywords: ["C6244", "LOCALDECLHIDESGLOBAL", "__WARNING_LOCALDECLHIDESGLOBAL"] helpviewer_keywords: ["C6244"] ms.assetid: ce2c853d-3354-40f2-a8c5-569f6e4bfc0a --- -# C6244 +# Warning C6244 -> warning C6244: local declaration of \ hides previous declaration at \ of \ +> Local declaration of '*variable*' hides previous declaration at '*line*' of '*file*' -This warning indicates that a declaration has the same name as a declaration at an outer scope and hides the previous declaration. You will not be able to refer to the previous declaration from inside the local scope. Any intended use of the previous declaration will end up using the local declaration This warning only identifies a scope overlap and not lifetime overlap. +## Remarks + +This warning indicates that a declaration has the same name as a declaration at an outer scope and hides the previous declaration. You won't be able to refer to the previous declaration from inside the local scope. Any intended use of the previous declaration will end up using the local declaration. This warning only identifies a scope overlap and not lifetime overlap. + +Code analysis name: `LOCALDECLHIDESGLOBAL` ## Example diff --git a/docs/code-quality/c6246.md b/docs/code-quality/c6246.md index 609d8f57e0..7e4e33f786 100644 --- a/docs/code-quality/c6246.md +++ b/docs/code-quality/c6246.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6246" -title: C6246 +description: "Learn more about: Warning C6246" +title: Warning C6246 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6246"] +f1_keywords: ["C6246", "LOCALDECLHIDESLOCAL", "__WARNING_LOCALDECLHIDESLOCAL"] helpviewer_keywords: ["C6246"] ms.assetid: cd895cdb-ab3b-4671-ab43-419228fbf980 --- -# C6246 +# Warning C6246 -> warning C6246: Local declaration of \ hides declaration of same name in outer scope. Additional Information: See previous declaration at \. +> Local declaration of '*variable*' hides declaration of same name in outer scope. Additional Information: See previous declaration at '*location*'. + +## Remarks This warning indicates that two declarations have the same name at local scope. The name at outer scope is hidden by the declaration at the inner scope. Any intended use of the outer scope declaration will result in the use of local declaration. +Code analysis name: `LOCALDECLHIDESLOCAL` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6248.md b/docs/code-quality/c6248.md index 029f5b0829..f91fd895f4 100644 --- a/docs/code-quality/c6248.md +++ b/docs/code-quality/c6248.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C6248" -title: C6248 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6248"] +description: "Learn more about: Warning C6248" +title: Warning C6248 +ms.date: 08/16/2022 +f1_keywords: ["C6248", "__WARNING_CREATINGNULLDACL", "CREATINGNULLDACL"] helpviewer_keywords: ["C6248"] ms.assetid: 75743622-7a79-4fe8-81b9-dbdfa1a12f3d --- -# C6248 +# Warning C6248 -> warning C6248: setting a SECURITY_DESCRIPTOR's DACL to NULL will result in an unprotected object +> Setting a SECURITY_DESCRIPTOR's DACL to NULL will result in an unprotected object. -This warning identifies a call that sets a SECURITY_DESCRIPTOR's DACL field to null. If the DACL that belongs to the security descriptor of an object is set to NULL, a null DACL is created. A null DACL grants full access to any user who requests it; normal security checking is not performed with respect to the object. A null DACL should not be confused with an empty DACL. An empty DACL is a properly allocated and initialized DACL that contains no ACEs. An empty DACL grants no access to the object it is assigned to. +## Remarks -Objects that have null DACLs can have their security descriptors altered by malicious users so that no one has access to the object. +If the DACL that belongs to the security descriptor of an object is set to NULL, a null DACL is created. A null DACL grants full access to any user who requests it; normal security checking isn't performed with respect to the object. A null DACL shouldn't be confused with an empty DACL. An empty DACL is a properly allocated and initialized DACL that contains no ACEs. An empty DACL grants no access to the object it's assigned to. Objects that have null DACLs can have their security descriptors altered by malicious users, making it so that no one has access to the object. Even in a situation where everyone needs access to an object, only administrators should be able to alter that object's security. If only the creator needs access to an object, a DACL shouldn't be set on the object; the system will choose an appropriate default. -Even if everyone needs access to an object, the object should be secured so that only administrators can alter its security. If only the creator needs access to an object, a DACL should not be set on the object; the system will choose an appropriate default. +Code analysis name: `CREATINGNULLDACL` ## Example @@ -36,4 +35,4 @@ void f( PSECURITY_DESCRIPTOR pSecurityDescriptor ) } ``` -To see a complete example on how to create security descriptor, see [Creating a Security Descriptor for a New Object in C++](/windows/desktop/SecAuthZ/creating-a-security-descriptor-for-a-new-object-in-c--). For more information, see [Creating a DACL](/windows/desktop/SecBP/creating-a-dacl). +To see a complete example on how to create security descriptor, see [Creating a Security Descriptor for a New Object in C++](/windows/desktop/SecAuthZ/creating-a-security-descriptor-for-a-new-object-in-c--). For more information on creating DACLs, see [Creating a DACL](/windows/desktop/SecBP/creating-a-dacl). diff --git a/docs/code-quality/c6250.md b/docs/code-quality/c6250.md index e0ef462fd5..c57c22512c 100644 --- a/docs/code-quality/c6250.md +++ b/docs/code-quality/c6250.md @@ -1,27 +1,30 @@ --- -description: "Learn more about: C6250" -title: C6250 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6250"] +description: "Learn more about: Warning C6250" +title: Warning C6250 +ms.date: 10/03/2022 +f1_keywords: ["C6250", "WIN32UNRELEASEDVADS", "__WARNING_WIN32UNRELEASEDVADS"] helpviewer_keywords: ["C6250"] ms.assetid: 6949c9c5-e8bd-4f95-bc80-42073a293357 --- -# C6250 +# Warning C6250 -> warning C6250: Calling \ VirtualFree without the MEM_RELEASE flag may free memory but not address descriptors (VADs); results in address space leaks +> Calling 'VirtualFree' without the MEM_RELEASE flag may free memory but not address descriptors (VADs); results in address space leaks -This warning indicates that a call to `VirtualFree` without the `MEM_RELEASE` flag only decommits the pages, and does not release them. To decommit and release pages, use `MEM_RELEASE` flag in call to `VirtualFree`. If any pages in the region are committed, the function first decommits and then releases them. After this operation, the pages are in the free state. If you specify this flag, `dwSize` must be zero, and `lpAddress` must point to the base address returned by the `VirtualAlloc` function when the region was reserved. The function fails if either of these conditions is not met. +This warning indicates that a call to `VirtualFree` without the `MEM_RELEASE` flag only decommits the pages, and doesn't release them. To both decommit and release pages, use the `MEM_RELEASE` flag in the call to `VirtualFree`. If any pages in the region are committed, the function first decommits and then releases them. After this operation, the pages are in the free state. If you specify this flag, `dwSize` must be zero, and `lpAddress` must point to the base address returned by the `VirtualAlloc` function when the region was reserved. The function fails if either of these conditions isn't met. + +## Remarks You can ignore this warning if your code later frees the address space by calling `VirtualFree` with the `MEM_RELEASE` flag. -For more information see [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) and [VirtualFree](/windows/win32/api/memoryapi/nf-memoryapi-virtualfree). +For more information, see [`VirtualAlloc`](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) and [`VirtualFree`](/windows/win32/api/memoryapi/nf-memoryapi-virtualfree). + +The use of `VirtualAlloc` and `VirtualFree` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -The use of VirtualAlloc and VirtualFree have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +Code analysis name: `WIN32UNRELEASEDVADS` ## Example -The following sample code generates this warning: +The following sample code generates warning C6250: ```cpp #include diff --git a/docs/code-quality/c6255.md b/docs/code-quality/c6255.md index cfe09c1718..43f53740ce 100644 --- a/docs/code-quality/c6255.md +++ b/docs/code-quality/c6255.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: C6255" -title: C6255 +description: "Learn more about: Warning C6255" +title: Warning C6255 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6255"] +f1_keywords: ["C6255", "UNPROTECTEDUSEOFALLOCA", "__WARNING_UNPROTECTEDUSEOFALLOCA"] helpviewer_keywords: ["C6255"] ms.assetid: bb6430b2-782a-4410-a8e1-609df06007de --- -# C6255 +# Warning C6255 -> warning C6255: _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead +> _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead -This warning indicates that a call to `_alloca` has been detected outside of local exception handling. `_alloca` should always be called from within the protected range of an exception handler because it can raise a stack overflow exception on failure. If possible, instead of using `_alloca`, consider using `_malloca` which is a more secure version of `_alloca`. +This warning indicates that a call to `_alloca` has been detected outside of local exception handling. + +## Remarks + +`_alloca` should always be called from within the protected range of an exception handler because it can raise a stack overflow exception on failure. If possible, instead of using `_alloca`, consider using `_malloca`, which is a more secure version of `_alloca`. + +Code analysis name: `UNPROTECTEDUSEOFALLOCA` ## Example diff --git a/docs/code-quality/c6258.md b/docs/code-quality/c6258.md index 5b2d1df7d3..c6c0716a6d 100644 --- a/docs/code-quality/c6258.md +++ b/docs/code-quality/c6258.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6258" -title: C6258 +description: "Learn more about: Warning C6258" +title: Warning C6258 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6258"] +f1_keywords: ["C6258", "USINGTERMINATETHREAD", "__WARNING_USINGTERMINATETHREAD"] helpviewer_keywords: ["C6258"] ms.assetid: 62f3eed7-d9cd-46eb-8c38-0bc4f647941f --- -# C6258 +# Warning C6258 -> warning C6258: using TerminateThread does not allow proper thread clean up. +> Using `TerminateThread` does not allow proper thread clean up. -This warning indicates that a call to TerminateThread has been detected. +This warning indicates that a call to `TerminateThread` has been detected. -TerminateThread is a dangerous function that should only be used in the most extreme cases. For more information about problems associated with TerminateThread call, see [TerminateThread function](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminatethread). +## Remarks + +`TerminateThread` is a dangerous function that should only be used in the most extreme cases. For more information about problems associated with TerminateThread call, see [`TerminateThread` function](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminatethread). + +Code analysis name: `USINGTERMINATETHREAD` ## To properly terminate threads diff --git a/docs/code-quality/c6259.md b/docs/code-quality/c6259.md index ad982abffa..6819a938cd 100644 --- a/docs/code-quality/c6259.md +++ b/docs/code-quality/c6259.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6259" -title: C6259 +description: "Learn more about: Warning C6259" +title: Warning C6259 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6259"] +f1_keywords: ["C6259", "DEADCODEINBITORLIMITEDSWITCH", "__WARNING_DEADCODEINBITORLIMITEDSWITCH"] helpviewer_keywords: ["C6259"] ms.assetid: a370bfd2-6634-402c-84c7-3d83fa0009b7 --- -# C6259 +# Warning C6259 -> warning C6259: labeled code is unreachable: (\ & \) in switch-expr cannot evaluate to \ +> Labeled code is unreachable: ('*expression*' & '*constant*') in switch-expr cannot evaluate to '*case-label*' -This warning indicates unreachable code caused by the result of a bitwise-AND (`&`) comparison in a switch expression. The case statement that matches the constant in the switch expression is only reachable; all other case statements are not reachable. +## Remarks + +This warning indicates unreachable code caused by the result of a bitwise-AND (`&`) comparison in a switch expression. Only the case statement that matches the constant in the switch expression is reachable; all other case statements aren't reachable. + +Code analysis name: `DEADCODEINBITORLIMITEDSWITCH` ## Example -The following sample code generates this warning because the 'switch' expression `(rand() & 3)` cannot evaluate to case label (`case 4`): +The following sample code generates this warning because the 'switch' expression `(rand() & 3)` can't evaluate to case label (`case 4`): ```cpp #include diff --git a/docs/code-quality/c6260.md b/docs/code-quality/c6260.md index 47d270bac0..ed76507258 100644 --- a/docs/code-quality/c6260.md +++ b/docs/code-quality/c6260.md @@ -1,24 +1,29 @@ --- -description: "Learn more about: C6260" -title: C6260 +description: "Learn more about: Warning C6260" +title: Warning C6260 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6260"] +f1_keywords: ["C6260", "USEOFBYTEAREA", "__WARNING_USEOFBYTEAREA"] helpviewer_keywords: ["C6260"] ms.assetid: 9cbedfcb-32b2-4fe4-99f7-a2d4a7f4422a --- -# C6260 +# Warning C6260 -> warning C6260: sizeof * sizeof is almost always wrong, did you intend to use a character count or a byte count? +> `sizeof` * `sizeof` is almost always wrong, did you intend to use a character count or a byte count? -This warning indicates that the results of two **`sizeof`** operations have been multiplied together. The C/C++ **`sizeof`** operator returns the number of bytes of storage an object uses. It is typically incorrect to multiply it by another **`sizeof`** operation; usually one is interested in the number of bytes in an object or the number of elements in an array (for example the number of wide-characters in an array). +This warning indicates that the results of two **`sizeof`** operations have been multiplied together. -There is some unintuitive behavior associated with **`sizeof`** operator. For example, in C, the `sizeof ('\0') == 4,` because a character is of an integral type. In C++, the type of a character literal is **`char`**, so `sizeof ('\0') == 1`. However, in both C and C++, the following is true: +## Remarks + +The C/C++ **`sizeof`** operator returns the number of bytes of storage an object uses. It's typically incorrect to multiply it by another **`sizeof`** operation. Usually, you're interested in the number of bytes in an object or the number of elements in an array (for example, the number of wide-characters in an array). + +There's some unintuitive behavior associated with **`sizeof`** operator. For example, in C, `sizeof ('\0') == 4`, because a character is of an integral type. In C++, the type of a character literal is **`char`**, so `sizeof ('\0') == 1`. However, in both C and C++, the following relation is true: ```cpp -sizeof ("\0") == 2. +sizeof ("\0") == 2 ``` +Code analysis name: `USEOFBYTEAREA` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6262.md b/docs/code-quality/c6262.md index bee4faf570..775784567c 100644 --- a/docs/code-quality/c6262.md +++ b/docs/code-quality/c6262.md @@ -1,14 +1,13 @@ --- -title: C6262 +title: Warning C6262 description: "Visual Studio C++ Code Analysis warning C6262 description and resolution." ms.date: 10/14/2020 -ms.topic: reference -f1_keywords: ["C6262"] +f1_keywords: ["C6262", "EXCESSIVESTACKUSAGE", "__WARNING_EXCESSIVESTACKUSAGE"] helpviewer_keywords: ["C6262"] --- -# C6262 +# Warning C6262 -> warning C6262: Function uses *constant_1* bytes of stack: exceeds /analyze:stacksize *constant_2*. Consider moving some data to heap +> Function uses *constant_1* bytes of stack: exceeds /analyze:stacksize *constant_2*. Consider moving some data to heap ## Remarks @@ -18,6 +17,8 @@ To correct the problem behind this warning, you can either move some data to the For kernel-mode code—for example, in driver projects—the value of *constant_2* is set to 1 KB. Well-written drivers should have few functions that approach this value, and changing the limit downward may be desirable. The same general techniques that are used for user-mode code to reduce the stack size can be adapted to kernel-mode code. +Code analysis name: `EXCESSIVESTACKUSAGE` + ## Adjust the stack size to suppress the warning You can use the [`/analyze:stacksize`](../build/reference/analyze-code-analysis.md) command-line option to change the value for *constant_2*, but increasing it introduces a risk that an error may not be reported. diff --git a/docs/code-quality/c6263.md b/docs/code-quality/c6263.md index dcaf889c92..a232723446 100644 --- a/docs/code-quality/c6263.md +++ b/docs/code-quality/c6263.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6263" -title: C6263 +description: "Learn more about: Warning C6263" +title: Warning C6263 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6263"] +f1_keywords: ["C6263", "USINGALLOCAINLOOP", "__WARNING_USINGALLOCAINLOOP"] helpviewer_keywords: ["C6263"] ms.assetid: bc360ad7-5f59-4480-a642-6c7e6beeb5f6 --- -# C6263 +# Warning C6263 -> warning C6263: using _alloca in a loop; this can quickly overflow stack +> Using _alloca in a loop; this can quickly overflow stack -This warning indicates that calling _alloca inside a loop to allocate memory can cause stack overflow. _alloca allocates memory from the stack, but that memory is only freed when the calling function exits. Stack, even in user-mode, is limited, and failure to commit a page of stack causes a stack overflow exception. The `_resetstkoflw` function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the `_resetstkoflw` function is not called, there is no guard page after the previous exception. The next time that there is a stack overflow, there are no exceptions at all and the process terminates without warning. +## Remarks -You should avoid calling `_alloca` inside a loop if either the allocation size or the iteration count is unknown because it might cause stack overflow. In these cases, consider other options such as, heap memory, or [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) classes. +This warning indicates that calling `_alloca` inside a loop to allocate memory can cause stack overflow. `_alloca` allocates memory from the stack, but that memory is only freed when the calling function exits. Stack, even in user-mode, is limited, and failure to commit a page of stack causes a stack overflow exception. The `_resetstkoflw` function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the `_resetstkoflw` function isn't called, there's no guard page after the previous exception. The next time that there's a stack overflow, there are no exceptions at all and the process terminates without warning. + +You should avoid calling `_alloca` inside a loop if either the allocation size or the iteration count is unknown because it might cause stack overflow. In these cases, consider other options such as heap memory or [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) classes. + +Code analysis name: `USINGALLOCAINLOOP` ## Example diff --git a/docs/code-quality/c6268.md b/docs/code-quality/c6268.md index 6fccb810ac..49ae372e51 100644 --- a/docs/code-quality/c6268.md +++ b/docs/code-quality/c6268.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: C6268" -title: C6268 +description: "Learn more about: Warning C6268" +title: Warning C6268 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6268"] +f1_keywords: ["C6268", "MISPARENTHESIZED_CASTS", "__WARNING_MISPARENTHESIZED_CASTS"] helpviewer_keywords: ["C6268"] ms.assetid: fd81e00a-de2f-498b-b3fe-53ce056042d7 --- -# C6268 +# Warning C6268 -> warning C6268: Incorrect order of operations: (\)(\)x + y. Possible missing parentheses in (\)((\)x + y) +> Incorrect order of operations: ('*TYPE1*')('*TYPE2*')x + y. Possible missing parentheses in ('*TYPE1*')(('*TYPE2*')x + y) This warning indicates that a complex cast expression might involve a precedence problem when performing pointer arithmetic. Because casts group more closely than binary operators, the result might not be what the programmer intended. In some cases, this defect causes incorrect behavior or a program crash. +## Remarks + In an expression such as: ```cpp @@ -31,15 +32,17 @@ is equivalent to: ((int *)(char *)p) + offset ``` -and so the offset is interpreted as an offset in integers. In other words, it is equivalent to: +and so the offset is interpreted as an offset in integers. In other words, it's equivalent to: ```cpp (int *)((char *)p + (offset * sizeof(int))) ``` -which is not likely to be what the programmer intended. +which isn't likely to be what the programmer intended. + +Depending on the relative sizes of the two types, this offset can lead to a buffer overrun. -Depending on the relative sizes of the two types, this can lead to a buffer overrun. +Code analysis name: `MISPARENTHESIZED_CASTS` ## Example diff --git a/docs/code-quality/c6269.md b/docs/code-quality/c6269.md index c4f80b47d3..d910880ed7 100644 --- a/docs/code-quality/c6269.md +++ b/docs/code-quality/c6269.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: C6269" -title: C6269 +description: "Learn more about: Warning C6269" +title: Warning C6269 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6269"] +f1_keywords: ["C6269", "POINTER_DEREF_DISCARDED", "__WARNING_POINTER_DEREF_DISCARDED"] helpviewer_keywords: ["C6269"] ms.assetid: a01fa7fa-fc6c-4af7-ac8c-585e44e60cca --- -# C6269 +# Warning C6269 -> warning C6269: possible incorrect order of operations: dereference ignored +> Possible incorrect order of operations: dereference ignored This warning indicates that the result of a pointer dereference is being ignored, which raises the question of why the pointer is being dereferenced in the first place. +## Remarks + The compiler will correctly optimize away the gratuitous dereference. In some cases, however, this defect may reflect a precedence or logic error. One common cause for this defect is an expression statement of the form: @@ -21,7 +22,9 @@ One common cause for this defect is an expression statement of the form: *p++; ``` -If the intent of this statement is simply to increment the pointer `p`, then dereference is unnecessary; however, if the intent is to increment the location that `p` is pointing to, then the program will not behave as intended because `p++` construct is interpreted as `(p++)` instead of `(*p)++`. +If the intent of this statement is simply to increment the pointer `p`, then dereference is unnecessary; however, if the intent is to increment the location that `p` is pointing to, then the program won't behave as intended because `p++` construct is interpreted as `(p++)` instead of `(*p)++`. + +Code analysis name: `POINTER_DEREF_DISCARDED` ## Example diff --git a/docs/code-quality/c6270.md b/docs/code-quality/c6270.md index 730f6edab9..6a23a7f305 100644 --- a/docs/code-quality/c6270.md +++ b/docs/code-quality/c6270.md @@ -1,59 +1,45 @@ --- -description: "Learn more about: C6270" -title: C6270 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6270"] +description: "Learn more about: Warning C6270" +title: Warning C6270 +ms.date: 3/03/2023 +f1_keywords: ["C6270", "MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6270"] -ms.assetid: 34467f6e-98cf-489c-ae5e-c08a744d86c3 --- -# C6270 +# Warning C6270 -> warning C6270: missing float argument to \: add a float argument corresponding to conversion specifier \ +> Missing float argument to '*function-name*': add a float argument corresponding to conversion specifier '*number*' -This warning indicates that not enough arguments are being provided to match a format string; at least one of the missing arguments is a floating-point number. This defect can lead to crashes, in addition to potentially incorrect output. +## Remarks -## Example - -The following code generates this warning: +This warning indicates that not enough arguments are provided to match a format string. At least one of the missing arguments is a floating-point number. This defect can lead to crashes, in addition to potentially incorrect output. -```cpp -#include -#include +Code analysis name: `MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` -void f() -{ - char buff [25]; - sprintf(buff,"%s %f","pi:"); -} -``` +## Example -To correct this warning, pass the missing argument as shown in the following code: +The following code generates warning C6270. `sprintf_s` expects a second float argument as denoted by `%f` but none is provided: ```cpp -#include -#include - void f() { - char buff [25]; - sprintf(buff,"%s %f","pi:",3.1415); + char buff[25]; + sprintf_s(buff, sizeof(buff), "%s %f", "pi: "); } ``` -The following sample code uses the safe string manipulation function, `sprintf_s`, to correct this warning: +To correct this warning, pass the missing float argument as shown in the following code: ```cpp -#include -#include - void f() { - char buff [25]; - sprintf_s( buff, 25,"%s %f", "pi:",3.1415 ); + char buff[25]; + sprintf_s(buff, sizeof(buff), "%s %f", "pi: ", 3.14159); } ``` ## See also -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4473](../error-messages/compiler-warnings/C4473.md) diff --git a/docs/code-quality/c6271.md b/docs/code-quality/c6271.md index 61234c98f2..29c2626788 100644 --- a/docs/code-quality/c6271.md +++ b/docs/code-quality/c6271.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6271" -title: C6271 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6271"] +description: "Learn more about: Warning C6271" +title: Warning C6271 +ms.date: 3/06/2023 +f1_keywords: ["C6271", "EXTRA_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_EXTRA_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6271"] -ms.assetid: 24703b17-5bdc-4f97-a56a-b2ea48bacc43 --- -# C6271 +# Warning C6271 -> warning C6271: extra argument passed to \: parameter \ is not used by the format string +> Extra argument passed to '*function*' -This warning indicates that additional arguments are being provided beyond those specified by the format string. By itself, this defect will not have any visible effect although it indicates that the programmer's intent is not reflected in the code. +## Remarks + +This warning indicates that extra arguments are being provided beyond the ones specified by the format string. By itself, this defect doesn't have any visible effect although it indicates that the programmer's intent isn't reflected in the code. + +Code analysis name: `EXTRA_ARGUMENT_TO_FORMAT_FUNCTION` ## Example @@ -19,27 +21,25 @@ The following sample code generates this warning: ```cpp #include -#include void f() { char buff[5]; - sprintf(buff,"%d",1,2); + sprintf(buff, "%d", 1, 2); } ``` -To correct this warning, use the following sample code: +To correct this warning, remove the unused parameter or modify the format string to take it into account: ```cpp #include -#include void f() { char buff[5]; - sprintf(buff,"%d, %d",1,2); + sprintf(buff, "%d, %d", 1, 2); } ``` @@ -47,16 +47,18 @@ The following sample code calls the safe string manipulation function, `sprintf_ ```cpp #include -#include void f() { char buff[5]; - sprintf_s( buff, 5,"%s %d", 1,2 ); //safe version + sprintf_s( buff, 5, "%d %d", 1, 2 ); //safe version } ``` ## See also -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4474](../error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md) diff --git a/docs/code-quality/c6272.md b/docs/code-quality/c6272.md index d491300543..5a25de9b99 100644 --- a/docs/code-quality/c6272.md +++ b/docs/code-quality/c6272.md @@ -1,65 +1,47 @@ --- -description: "Learn more about: C6272" -title: C6272 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6272"] +description: "Learn more about: Warning C6272" +title: Warning C6272 +ms.date: 03/07/2023 +f1_keywords: ["C6272", "NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6272"] -ms.assetid: b63937ac-fbb2-45ec-936a-641c156e6355 --- -# C6272 +# Warning C6272 -> warning C6272: non-float passed as argument \ when float is required in call to \ +> Non-float passed as argument '*number*' when float is required in call to '*function-name*' -This warning indicates that the format string specifies that a float is required, for example, a `%f` or `%g` specification for `printf,` but a non-float such as an integer or string is being passed. This defect is likely to result in incorrect output; however, in certain circumstances it could result in a crash. +## Remarks -## Example - -The following code generates this warning: +This warning indicates that the format string specifies that a float is required. For example, a `%f` or `%g` specification for `printf`, but a non-float such as an integer or string is being passed. This defect can lead to crashes, in addition to potentially incorrect output. -```cpp -#include -#include +Code analysis name: `NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` -void f() -{ - char buff[5]; - int i=5; - - sprintf(buff,"%s %f","a",i); -} -``` +## Example -To correct this warning, use `%i` instead of `%f` specification as shown in the following code: +The following code generates this warning. `%f` indicates a float is expected, but the integer `i` is passed instead: ```cpp -#include -#include - void f() { - char buff[5]; - int i=5; - - sprintf(buff,"%s %i","a",i); + char buff[5]; + int i=5; + sprintf_s(buff, sizeof(buff), "%s %f", "a", i); } ``` -The following code uses the safe string manipulation function, `sprintf_s`, to correct this warning: +To correct this warning, change the format specifier or modify the parameters passed to the function. In this example, we correct this warning by using `%i` instead of `%f`. ```cpp -#include -#include - void f() { - char buff[5]; - int i=5; - - sprintf_s(buff,5,"%s %i","a",i); // safe version + char buff[5]; + int i=5; + sprintf_s(buff, sizeof(buff), "%s %i", "a", i); } ``` ## See also -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6273.md b/docs/code-quality/c6273.md index b982363981..7bf741fbf4 100644 --- a/docs/code-quality/c6273.md +++ b/docs/code-quality/c6273.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6273" -title: C6273 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6273"] +description: "Learn more about: Warning C6273" +title: Warning C6273 +ms.date: 03/07/2023 +f1_keywords: ["C6273", "NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6273"] -ms.assetid: e780e504-8b8d-4d61-b15f-4859133134ad --- -# C6273 +# Warning C6273 -> warning C6273 - non-integer passed as parameter \ when integer is required in call to \: if a pointer value is being passed, %p should be used +> Non-integer passed as parameter '*number*' when an integer is required in call to '*function*' -This warning indicates that the format string specifies an integer, for example, a `%d`, length or precedence specification for `printf` but a non-integer such as a **`float`**, string, or **`struct`** is being passed as a parameter. This defect is likely to result in incorrect output. +## Remarks + +This warning indicates that the format string specifier in a `printf` like function is expecting an integer type, but a non-integer such as a **`float`**, string, or **`struct`** is being passed instead. This warning checks integer type specifiers like `%d`, and width/precision specifier that use integers like `%*.*f`. This defect is likely to result in incorrect output. + +Code analysis name: `NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION` ## Example @@ -19,7 +21,6 @@ The following code generates this warning because an integer is required instead ```cpp #include -#include void f_defective() { @@ -30,11 +31,10 @@ void f_defective() } ``` -The following code uses an integer cast to correct this warning: +The following code uses an integer cast to correct this warning. Alternatively it could have corrected the warning by modifying the format specifier to match the type. ```cpp #include -#include void f_corrected() { @@ -49,7 +49,6 @@ The following code uses safe string manipulation function, `sprintf_s`, to corre ```cpp #include -#include void f_safe() { @@ -60,8 +59,10 @@ void f_safe() } ``` -This warning is not applicable on Windows 9x and Windows NT version 4 because %p is not supported on these platforms. +This warning isn't applicable on Windows 9x and Windows NT version 4 because %p isn't supported on these platforms. ## See also -[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6274.md b/docs/code-quality/c6274.md index dac1500712..7941289172 100644 --- a/docs/code-quality/c6274.md +++ b/docs/code-quality/c6274.md @@ -1,30 +1,30 @@ --- -description: "Learn more about: C6274" -title: C6274 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6274"] +description: "Learn more about: Warning C6274" +title: Warning C6274 +ms.date: 03/07/2023 +f1_keywords: ["C6274", "NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6274"] -ms.assetid: d32f1c67-edf1-4d03-9103-133272631948 --- -# C6274 +# Warning C6274 -> warning C6274: non-character passed as parameter \ when character is required in call to \ +> Non-character passed as parameter '*number*' when character is required in call to '*function*' + +## Remarks This warning indicates that the format string specifies that a character is required (for example, a `%c` or `%C` specification) but a non-integer such as a float, string, or struct is being passed. This defect is likely to cause incorrect output. +Code analysis name: `NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION` + ## Example The following code generates this warning: ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf(buff,"%c",str); } ``` @@ -33,12 +33,10 @@ To correct this warning, use the following code: ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf(buff,"%c",str[0]); } ``` @@ -47,12 +45,15 @@ The following code uses safe string manipulation function, `sprintf_s`, to corre ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf_s(buff,5,"%c", str[0]); } ``` + +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md) diff --git a/docs/code-quality/c6276.md b/docs/code-quality/c6276.md index 883b0c5c21..88eb047af5 100644 --- a/docs/code-quality/c6276.md +++ b/docs/code-quality/c6276.md @@ -1,59 +1,49 @@ --- -description: "Learn more about: C6276" -title: C6276 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6276"] +description: "Learn more about: Warning C6276" +title: Warning C6276 +ms.date: 09/28/2022 +f1_keywords: ["C6276", "CHAR_TO_WCHAR_CAST", "__WARNING_CHAR_TO_WCHAR_CAST"] helpviewer_keywords: ["C6276"] ms.assetid: 88f288da-da81-4d32-ab0f-be9d01a2606a --- -# C6276 +# Warning C6276 -> warning C6276: Cast between semantically different string types: char* to wchar_t\*. Use of invalid string can lead to undefined behavior +> Cast between semantically different string types. Use of invalid string can lead to undefined behavior. -This warning indicates a potentially incorrect cast from an ANSI string (`char_t*`) to a UNICODE string (`wchar_t *`). Because UNICODE strings have a character size of 2 bytes, this cast might yield strings that are not correctly terminated. Using such strings with the wcs* library of functions could cause buffer overruns and access violations. +This warning indicates a potentially incorrect cast from a narrow character string (`char*`) to a wide character string (`wchar_t*`). -## Example +## Remarks -The following code generates this warning: +Because the Microsoft compiler implements wide strings with a character size of 2 bytes, casting from a narrow string might produce strings that aren't correctly terminated. If you use such strings with the `wcs*` functions in the runtime library, they could cause buffer overruns and access violations. -```cpp -#include -VOID f() -{ - WCHAR szBuffer[8]; - LPWSTR pSrc; +Code analysis name: `CHAR_TO_WCHAR_CAST` - pSrc = (LPWSTR)"a"; - wcscpy(szBuffer, pSrc); -} -``` +## Example -The following code corrects this warning by appending the letter L to represent the ASCII character as a wide character: +The following code generates warning C6276. It's caused by an improper cast of the narrow string "a" (2 bytes, one for the 'a' and one for the null terminator) to a wide string (a 2-byte wide character 'a' with no null terminator): ```cpp #include -VOID f() +void f() { - WCHAR szBuffer[8]; - LPWSTR pSrc; - - pSrc = L"a"; - wcscpy(szBuffer, pSrc); + WCHAR szBuffer[8]; + LPWSTR pSrc; + pSrc = (LPWSTR)"a"; + wcscpy_s(szBuffer, pSrc); } ``` -The following code uses the safe string manipulation function, `wcscpy_s`, to correct this warning: +The following code corrects this warning. It removes the problem cast and adds an `L` prefix to the string to define it as a properly terminated wide character string: ```cpp #include -VOID f() +void f() { - WCHAR szBuffer[8]; - LPWSTR pSrc; - pSrc = L"a"; - wcscpy_s(szBuffer,8,pSrc); + WCHAR szBuffer[8]; + LPWSTR pSrc; + pSrc = L"a"; + wcscpy_s(szBuffer, pSrc); } ``` diff --git a/docs/code-quality/c6277.md b/docs/code-quality/c6277.md index 188abb3be4..c01fd781f8 100644 --- a/docs/code-quality/c6277.md +++ b/docs/code-quality/c6277.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6277" -title: C6277 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6277"] +description: "Learn more about: Warning C6277" +title: Warning C6277 +ms.date: 09/28/2022 +f1_keywords: ["C6277", "CREATEPROCESS_ESCAPE", "__WARNING_CREATEPROCESS_ESCAPE"] helpviewer_keywords: ["C6277"] ms.assetid: 2b41252a-68c2-4e92-b005-0458db5f4430 --- -# C6277 +# Warning C6277 -> warning C6277: NULL application name with an unquoted path in call to \: results in a security vulnerability if the path contains spaces +> NULL application name with an unquoted path in call to '*function-name*': results in a security vulnerability if the path contains spaces -This warning indicates that the application name parameter is null and there might be spaces in the executable path name. In this case, unless the executable name is "fully qualified," there is likely to be a security problem. A malicious user might insert a rogue executable with the same name earlier in the path. To correct this warning, you can specify the application name instead of passing null or if you do pass null for the application name, use quotation marks around the executable path. +This warning indicates that the application name parameter is null and that there might be spaces in the executable path name. + +## Remarks + +Unless the executable name is fully qualified, there's likely to be a security problem. A malicious user could insert a rogue executable with the same name earlier in the path. To correct this warning, you can specify the application name instead of passing null. Alternatively, if you do pass null for the application name, use quotation marks around the executable path. + +Code analysis name: `CREATEPROCESS_ESCAPE` ## Example -The following sample code generates this warning because the application name parameter is null, and the executable path name has a space in it; there is a risk that a different executable could be run because of the way the function parses spaces. For more information, see [CreateProcess](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa). +The following sample code generates warning C6277. The warning is caused by the NULL application name and from the executable path name having a space. Due to how the function parses spaces, there's a risk that a different executable could be run. For more information, see [`CreateProcessA`](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa). ```cpp #include diff --git a/docs/code-quality/c6278.md b/docs/code-quality/c6278.md index 38d7e2cd4a..8ae400a83c 100644 --- a/docs/code-quality/c6278.md +++ b/docs/code-quality/c6278.md @@ -1,31 +1,36 @@ --- -description: "Learn more about: C6278" -title: C6278 -ms.date: 10/16/2019 -ms.topic: reference -f1_keywords: ["C6278"] +description: "Learn more about: Warning C6278" +title: Warning C6278 +ms.date: 10/03/2022 +f1_keywords: ["C6278", "ARRAY_NEW_DELETE_MISMATCH", "__WARNING_ARRAY_NEW_DELETE_MISMATCH"] helpviewer_keywords: ["C6278"] ms.assetid: 5cc3c393-c48a-4f91-9f38-03d7868be5e5 --- -# C6278 +# Warning C6278 -> warning C6278: \ is allocated with array new [], but deleted with scalar delete. Destructors will not be called +> '*variable*' is allocated with array new [], but deleted with scalar delete. Destructors will not be called. -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array **new []** operator, but freed it with the scalar **`delete`** operator. This is undefined behavior according to the C++ standard and the Microsoft C++ implementation. There are at least three reasons that this is likely to cause problems: +## Remarks -- The constructors for the individual objects in the array are invoked, but the destructors are not invoked. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array **`new []`** operator, but freed it with the scalar **`delete`** operator. This usage is undefined behavior according to the C++ standard and the Microsoft C++ implementation. -- If global, or class-specific, **operator new** and **operator delete** are not compatible with **operator new[]** and **operator delete[]**, unexpected results are likely to occur. +There are at least three reasons that this mismatch is likely to cause problems: -- It is always risky to rely on undefined behavior. +- The constructors for the individual objects in the array are invoked, but the destructors aren't invoked. -The exact ramifications of this defect are difficult to predict. It might result in leaks for classes with destructors that perform memory de-allocation; inconsistent behavior for classes with destructors that perform some semantically significant operation; or memory corruptions and crashes when operators have been overridden. In other cases the mismatch might be unimportant, depending on the implementation of the compiler and its libraries. Analysis tool cannot always distinguish between these situations. +- If global, or class-specific, **`operator new`** and **`operator delete`** aren't compatible with **`operator new[]`** and **`operator delete[]`**, unexpected results are likely to occur. -If memory is allocated with array **new []**, it should be typically be freed with array **delete[]**. +- It's always risky to rely on undefined behavior. + +The exact ramifications of this defect are difficult to predict. It might result in leaks for classes with destructors that perform memory de-allocation. It could cause inconsistent behavior for classes with destructors that perform some semantically significant operation, or memory corruptions and crashes when operators have been overridden. In other cases the mismatch might be unimportant, depending on the implementation of the compiler and its libraries. Analysis tools can't always distinguish between these situations. + +If memory is allocated with array **`new []`**, it should be freed with array **`delete[]`**. + +Code analysis name: `ARRAY_NEW_DELETE_MISMATCH` ## Example -The following sample code generates this warning: +The following sample code generates warning C6278: ```cpp class A @@ -52,6 +57,6 @@ void f( ) } ``` -If the underlying object in the array is a primitive type such as **`int`**, **`float`**, **`enum`**, or pointer, there are no destructors to be called. In these cases warning [C6283](../code-quality/c6283.md) is reported instead. +If the underlying object in the array is a primitive type such as **`int`**, **`float`**, **`enum`**, or pointer, there are no destructors to call. In these cases, warning [C6283](../code-quality/c6283.md) is reported instead. -The use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6279.md b/docs/code-quality/c6279.md index 55cf9c4b97..ab28f2ecd1 100644 --- a/docs/code-quality/c6279.md +++ b/docs/code-quality/c6279.md @@ -1,29 +1,28 @@ --- -description: "Learn more about: C6279" -title: C6279 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6279"] +description: "Learn more about: Warning C6279" +title: Warning C6279 +ms.date: 10/03/2022 +f1_keywords: ["C6279", "NEW_ARRAY_DELETE_MISMATCH", "__WARNING_NEW_ARRAY_DELETE_MISMATCH"] helpviewer_keywords: ["C6279"] ms.assetid: 0af88b58-35df-456f-8c02-e8eeffe3b7de --- -# C6279 +# Warning C6279 -> warning C6279: \ is allocated with scalar new, deleted with array delete [] +> '*variable-name*' is allocated with scalar new, deleted with array delete [] -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the scalar **`new`** operator, but freed it with the array **delete []** operator. If memory is allocated with scalar **`new`**, it should typically be freed with scalar **`delete`**. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the scalar `new` operator, but freed it with the array `delete[]` operator. If memory is allocated with scalar `new`, it should typically be freed with scalar `delete`. -There are at least three reasons that this is likely to cause problems: +## Remarks -- The constructors for the individual objects in the array are not invoked, although the destructors are. +The exact ramifications of this defect are difficult to predict. It might cause random behavior or crashes due to usage of uninitialized memory as constructors aren't invoked. Or, it might cause memory allocations and crashes in situations where operators have been overridden. The analysis tool doesn't currently distinguish between these situations. -- If global (or class-specific) **operator new** and **operator delete** are not compatible with **operator new[]** and **operator delete[]**, unexpected results are likely to occur. +To avoid these kinds of allocation problems altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -The exact ramifications of this defect are difficult to predict. It might cause random behavior or crashes due to usage of uninitialized memory because constructors are not invoked. Or, it might cause memory allocations and crashes in situations where operators have been overridden. In rare cases, the mismatch might be unimportant. Analysis tool does not currently distinguish between these situations. +Code analysis name: `NEW_ARRAY_DELETE_MISMATCH` ## Example -The following code generates this warning: +The following code generates warning C6279. `A` is allocated using `new` but deleted using `delete[]`: ```cpp class A @@ -31,27 +30,30 @@ class A // members }; -void f ( ) +void f() { - A *pA = new A; - //code ... - delete[] pA; + A *pA = new A; + //code ... + delete[] pA; } ``` -To correct this warning, use the following code: +The following code avoids this warning by using `delete` instead: ```cpp -void f( ) +class A +{ + // members +}; + +void f() { - A *pA = new A; - //code ... - delete pA; + A *pA = new A; + //code ... + delete pA; } ``` -To avoid these kinds of allocation problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). - ## See also -- [C6014](../code-quality/c6014.md) +- [C6014](c6014.md) diff --git a/docs/code-quality/c6280.md b/docs/code-quality/c6280.md index 47e2083196..f03214777d 100644 --- a/docs/code-quality/c6280.md +++ b/docs/code-quality/c6280.md @@ -1,25 +1,31 @@ --- -description: "Learn more about: C6280" -title: C6280 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6280"] +description: "Learn more about: Warning C6280" +title: Warning C6280 +ms.date: 10/03/2022 +f1_keywords: ["C6280", "MEMORY_ALLOCATION_MISMATCH", "__WARNING_MEMORY_ALLOCATION_MISMATCH"] helpviewer_keywords: ["C6280"] ms.assetid: b91f2966-0876-4c9b-843a-e142f35be864 --- -# C6280 +# Warning C6280 -> warning C6280: \ is allocated with \, but deleted with \ +> '*variable-name*' is allocated with '*function-name-1*', but deleted with '*function-name-2*' -This warning indicates that the calling function has inconsistently allocated memory by using a function from one memory allocation family and freed it by using a function from another memory allocation family. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +This warning indicates that the calling function has inconsistently allocated memory by using a function from one family and freed it by using a function from another. -For example, this warning would be produced if memory is allocated by using `malloc` but freed by using `GlobalFree` or **`delete`**. In the specific cases of mismatches between array `new[]` and scalar **`delete`**, more precise warnings are reported instead of this one. +## Remarks + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +For example, this warning would be produced if memory is allocated by using `malloc` but freed by using `GlobalFree` or `delete`. In the specific cases of mismatches between array `new[]` and scalar `delete`, more precise warnings are reported instead of this one. + +Code analysis name: `MEMORY_ALLOCATION_MISMATCH` ## Example -The following sample code generates this warning. +The following sample code generates this warning. `pInt` is allocated using `calloc` but is freed using the mismatched function `delete`: ```cpp +// C6280a_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -34,9 +40,10 @@ void f(int arraySize) } ``` -To correct this warning, use this code: +The following code avoids this warning by using the deallocation function `free`, the match to `calloc`: ```cpp +// C6280a_no_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -51,11 +58,14 @@ void f(int arraySize) } ``` -Different API definitions can use different heaps. For example, `GlobalAlloc` uses the system heap, and `free` uses the process heap. This is likely to cause memory corruptions and crashes. +Different API definitions can use different heaps. For example, `GlobalAlloc` uses the system heap, and `free` uses the process heap. This issue is likely to cause memory corruptions and crashes. + +These inconsistencies apply to the `new`/`delete` and `malloc`/`free` memory allocation mechanisms. To avoid these kinds of potential inconsistencies altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -These inconsistencies apply to the **`new`**/**`delete`** and `malloc`/`free` memory allocation mechanisms. To avoid these kinds of potential inconsistencies altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The following code avoids this problem entirely by using `unique_ptr`: ```cpp +// C6280b_no_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -79,11 +89,11 @@ void f(int arraySize) ## See also -- [calloc](../c-runtime-library/reference/calloc.md) -- [malloc](../c-runtime-library/reference/malloc.md) -- [free](../c-runtime-library/reference/free.md) -- [operator new](../cpp/new-operator-cpp.md) -- [delete Operator](../cpp/delete-operator-cpp.md) -- [shared_ptr](../standard-library/shared-ptr-class.md) -- [unique_ptr](../standard-library/unique-ptr-class.md) -- [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) +[`calloc`](../c-runtime-library/reference/calloc.md)\ +[`malloc`](../c-runtime-library/reference/malloc.md)\ +[`free`](../c-runtime-library/reference/free.md)\ +[`operator new`](../cpp/new-operator-cpp.md)\ +[`delete` Operator](../cpp/delete-operator-cpp.md)\ +[`shared_ptr`](../standard-library/shared-ptr-class.md)\ +[`unique_ptr`](../standard-library/unique-ptr-class.md)\ +[Smart pointers](../cpp/smart-pointers-modern-cpp.md) diff --git a/docs/code-quality/c6281.md b/docs/code-quality/c6281.md index 4aa6af6034..f16c015ee5 100644 --- a/docs/code-quality/c6281.md +++ b/docs/code-quality/c6281.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6281" -title: C6281 +description: "Learn more about: Warning C6281" +title: Warning C6281 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6281"] +f1_keywords: ["C6281", "BITWISERELATIONPRECEDENCEERROR", "__WARNING_BITWISERELATIONPRECEDENCEERROR"] helpviewer_keywords: ["C6281"] ms.assetid: d0182269-8403-486b-ac3f-325522871bb1 --- -# C6281 +# Warning C6281 -> warning C6281 - incorrect order of operations: relational operators have higher precedence than bitwise operators +> Incorrect order of operations: relational operators have higher precedence than bitwise operators -This warning indicates a possible error in the operator precedence. This might produce incorrect results. You should check the precedence and use parentheses to clarify the intent. Relational operators (\<, >, \<=, >=, ==, != ) have higher precedence than bitwise operators (& | ^). +## Remarks + +This warning indicates a possible error in the operator precedence, which might produce incorrect results. You should check the precedence and use parentheses to clarify the intent. Relational operators (`<`, `>`, `<=`, `>=`, `==`, `!=`) have higher precedence than bitwise operators (`&`, `|`, `^`). + +Code analysis name: `BITWISERELATIONPRECEDENCEERROR` ## Example diff --git a/docs/code-quality/c6282.md b/docs/code-quality/c6282.md index 292d6ec6e7..c48e616632 100644 --- a/docs/code-quality/c6282.md +++ b/docs/code-quality/c6282.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6282" -title: C6282 +description: "Learn more about: Warning C6282" +title: Warning C6282 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6282"] +f1_keywords: ["C6282", "ASSIGNMENTREPLACESTEST", "__WARNING_ASSIGNMENTREPLACESTEST"] helpviewer_keywords: ["C6282"] ms.assetid: 7dc153d5-fb9f-424a-8afa-4e2661efa51c --- -# C6282 +# Warning C6282 -> warning C6282: Incorrect operator: assignment of constant in Boolean context. Consider using '==' instead +> Incorrect operator: assignment of constant in Boolean context. Consider using '==' instead + +## Remarks This warning indicates that an assignment of a constant to a variable was detected in a test context. Assignment of a constant to a variable in a test context is almost always incorrect. Replace the `=` with `==`, or remove the assignment from the test context to resolve this warning. +Code analysis name: `ASSIGNMENTREPLACESTEST` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6283.md b/docs/code-quality/c6283.md index f6ba994030..436a46f1f5 100644 --- a/docs/code-quality/c6283.md +++ b/docs/code-quality/c6283.md @@ -1,42 +1,45 @@ --- -description: "Learn more about: C6283" -title: C6283 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6283"] +description: "Learn more about: Warning C6283" +title: Warning C6283 +ms.date: 10/03/2022 +f1_keywords: ["C6283", "PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH", "__WARNING_PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH"] helpviewer_keywords: ["C6283"] ms.assetid: 7760d32e-6d71-4c81-a6d2-719c9c76c2bb --- -# C6283 +# Warning C6283 -> warning C6283: \ is allocated with array new [], but deleted with scalar delete +> '*variable-name*' is allocated with array new [], but deleted with scalar delete -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array `new []` operator, but freed it with the scalar **`delete`** operator. This defect might cause leaks, memory corruptions, and, in situations where operators have been overridden, crashes. If memory is allocated with array `new []`, it should typically be freed with array `delete[]`. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array `new []` operator, but freed it with the scalar `delete` operator. + +## Remarks + +This defect might cause leaks, memory corruptions, and, in situations where operators have been overridden, crashes. If memory is allocated with array `new []`, it should typically be freed with array `delete[]`. + +Warning C6283 only applies to arrays of primitive types such as integers or characters. If elements of the array are objects of class type then warning [C6278](../code-quality/c6278.md) is issued. + +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). + +Code analysis name: `PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH` ## Example -The following code generates this warning: +The following code generates warning C6283. `str` is allocated using `new ...[...]` but is freed using the mismatched function `delete`: ```cpp void f( ) { - char *str = new char[50]; - // code ... - delete str; + char *str = new char[50]; + delete str; } ``` -To correct this warning, use the following code: +The following code remediates this warning by using the matching function `delete[]`: ```cpp void f( ) { - char *str = new char[50]; - // code ... - delete[] str; + char *str = new char[50]; + delete[] str; } ``` - -Warning C6283 only applies to arrays of primitive types such as, integers or characters. If elements of the array are objects of class type then warning [C6278](../code-quality/c6278.md) is issued. - -The use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6284.md b/docs/code-quality/c6284.md index 519f650903..4c29d20e33 100644 --- a/docs/code-quality/c6284.md +++ b/docs/code-quality/c6284.md @@ -1,28 +1,27 @@ --- -description: "Learn more about: C6284" -title: C6284 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6284"] +description: "Learn more about: Warning C6284" +title: Warning C6284 +ms.date: 03/07/2023 +f1_keywords: ["C6284", "OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6284"] -ms.assetid: f3633df6-2978-4899-8c0b-b495bd869e1a --- -# C6284 +# Warning C6284 -> warning C6284: object passed as parameter when string is required in call to \ +> Object passed as parameter when string is required in call to '*function\*' -This warning indicates that there is a mismatch between the format specifier and the type being used in a `printf`-style function. The format specifier is a C style String type such as `%s` or `%ws`, and the argument matched with it is an object type. +## Remarks -This defect might produce incorrect output or crash. +This warning indicates that there's a mismatch between the format specifier and the type being used in a `printf`-style function. The format specifier is a C style String type such as `%s` or `%ws`, and the argument is a class/struct/union type. This defect can lead to crashes, in addition to potentially incorrect output. -This is frequently due to forgetting to convert an object string type such as `std::string`, `CComBSTR` or `bstr_t` into the C style string the `printf`-style function expects. If this is the case then the fix is to add the appropriate conversion to the type. This is needed because the parameters to `printf`-style functions are essentially untyped so no automatic conversion occurs. +This defect is frequently due to forgetting to convert an object string type such as `std::string`, `CComBSTR` or `bstr_t` into the C style string the `printf`-style function expects. If so, then the fix is to add the appropriate conversion to the type. The conversion is needed because the variadic parameters to `printf`-style functions are untyped, so no automatic conversion occurs. + +Code analysis name: `OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION` ## Example ```cpp #include #include -#include void f() { @@ -31,7 +30,7 @@ void f() std::string str{"World"}; // Oops, %ws and %s require C-style strings but CComBSTR and std::strings are being passed instead - sprintf(buff,"%ws %s",bstrValue, str); + sprintf(buff, "%ws %s", bstrValue, str); } ``` @@ -40,7 +39,6 @@ Fix the warning by adding the appropriate conversions: ```cpp #include #include -#include void f() { @@ -49,11 +47,13 @@ void f() std::string str{"World"}; // Fixed by adding a static_cast to the CComBSTR and calling c_str() on the std::string - sprintf(buff,"%ws %s",static_cast(bstrValue), str.c_str()); + sprintf(buff, "%ws %s", static_cast(bstrValue), str.c_str()); } ``` ## See also -- [static_cast Operator](../cpp/static-cast-operator.md) -- [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) +[`static_cast` Operator](../cpp/static-cast-operator.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C4840](../error-messages/compiler-warnings/compiler-warning-level-4-c4840.md) diff --git a/docs/code-quality/c6285.md b/docs/code-quality/c6285.md index 03410e822a..44221b6a57 100644 --- a/docs/code-quality/c6285.md +++ b/docs/code-quality/c6285.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6285" -title: C6285 +description: "Learn more about: Warning C6285" +title: Warning C6285 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6285"] +f1_keywords: ["C6285", "LOGICALOROFCONSTANTS", "__WARNING_LOGICALOROFCONSTANTS"] helpviewer_keywords: ["C6285"] ms.assetid: f5bc6d3d-d33b-42c8-98d2-92ec8ab17193 --- -# C6285 +# Warning C6285 -> warning C6285: (\ || \) is always a non-zero constant. Did you intend to use the bitwise-and operator? +> ('*non-zero constant*' \|\| '*non-zero constant*') is always a non-zero constant. Did you intend to use the bitwise-and operator? This warning indicates that two constant values, both greater than one, were detected as arguments to a logical-or operation that occurs in a test context. This expression is always TRUE. +## Remarks + Constant values greater than one suggest that the arguments to logical-or could be bit fields. Consider whether a bitwise operator might be a more appropriate operator in this case. +Code analysis name: `LOGICALOROFCONSTANTS` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6286.md b/docs/code-quality/c6286.md index fa95e54211..aeedbe05d5 100644 --- a/docs/code-quality/c6286.md +++ b/docs/code-quality/c6286.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6286" -title: C6286 +description: "Learn more about: Warning C6286" +title: Warning C6286 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6286"] +f1_keywords: ["C6286", "NONZEROLOGICALORLOSINGSIDEEFFECTS", "__WARNING_NONZEROLOGICALORLOSINGSIDEEFFECTS"] helpviewer_keywords: ["C6286"] ms.assetid: c79c5d4a-c02b-4b98-891a-d79e471f9da7 --- -# C6286 +# Warning C6286 -> warning C6286: (\ || \) is always a non-zero constant. \ is never evaluated and may have side effects +> ('*non-zero constant*' \|\| '*expression*') is always a non-zero constant. '*expression*' is never evaluated and may have side effects -This warning indicates that a non-zero constant was detected on the left side of a logical-or operation that occurs in a test context. The resulting expression always evaluates to TRUE. In addition, the right side of the expression appears to have side effects, and they will be lost. +## Remarks -This warning indicates that you may want to examine the right side of the expression carefully to ensure that any side effects needed for proper functionality are not lost. +This warning indicates that a non-zero constant was detected on the left side of a logical-or operation that occurs in a test context. The resulting expression always evaluates to TRUE. In addition, the right side of the expression appears to have side effects, and they'll be lost. -The `(!0 || `) construction is commonly used to force execution of a controlled block. +You may want to examine the right side of the expression carefully to ensure that any side effects needed for proper functionality aren't lost. + +The `(!0 || )` construction is commonly used to force execution of a controlled block. + +Code analysis name: `NONZEROLOGICALORLOSINGSIDEEFFECTS` ## Example @@ -70,4 +73,4 @@ void f() ## See also -[Logical OR Operator: ||](../cpp/logical-or-operator-pipe-pipe.md) +[Logical OR Operator: \|\|](../cpp/logical-or-operator-pipe-pipe.md) diff --git a/docs/code-quality/c6287.md b/docs/code-quality/c6287.md index 8d670ee2d4..2847f5e85e 100644 --- a/docs/code-quality/c6287.md +++ b/docs/code-quality/c6287.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6287" -title: C6287 +description: "Learn more about: Warning C6287" +title: Warning C6287 ms.date: 12/17/2019 -ms.topic: reference -f1_keywords: ["C6287"] +f1_keywords: ["C6287", "REDUNDANTTEST", "__WARNING_REDUNDANTTEST"] helpviewer_keywords: ["C6287"] ms.assetid: 9cb12641-8853-413a-b89e-f8b32c8dc5d3 --- -# C6287 +# Warning C6287 -> warning C6287: redundant code: the left and right subexpressions are identical +> Redundant code: the left and right subexpressions are identical -This warning is emitted when an expression contains redundant logic. The warning can indicate a logic error. For example, accidentally using the wrong variable. It might also be a redundant test that can be removed. Inspect the code to verify that there is no logic error. +## Remarks + +This warning is emitted when an expression contains redundant logic. The warning can indicate a logic error. For example, accidentally using the wrong variable. It might also be a redundant test that can be removed. Inspect the code to verify that there's no logic error. + +Code analysis name: `REDUNDANTTEST` ## Example diff --git a/docs/code-quality/c6288.md b/docs/code-quality/c6288.md index 875cdd30ec..ffa9ae3b71 100644 --- a/docs/code-quality/c6288.md +++ b/docs/code-quality/c6288.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6288" -title: C6288 +description: "Learn more about: Warning C6288" +title: Warning C6288 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6288"] +f1_keywords: ["C6288", "MUTUALINCLUSIONOVERANDISFALSE", "__WARNING_MUTUALINCLUSIONOVERANDISFALSE"] helpviewer_keywords: ["C6288"] ms.assetid: 3856b80a-c9f2-4e86-97fc-c913b0186788 --- -# C6288 +# Warning C6288 -> warning C6288: Incorrect operator: mutual inclusion over && is always zero. Did you intent to use || instead? +> Incorrect operator: mutual inclusion over && is always zero. Did you intend to use \|\| instead? -This warning indicates that in a test expression, a variable is being tested against two different constants and the result depends on both conditions being true. The code in these cases indicates that the programmer's intent is not captured correctly. It is important to examine the code and correct the problem; otherwise your code will not behave the way you expected it to. +## Remarks -This problem is generally caused by using `&&`; in place of `||`, but can also be caused by using `==` where `!=` was intended. +This warning indicates that in a test expression, a variable is being tested against two different constants. The result depends on both conditions being true, which is impossible. The code in these cases indicates that the programmer's intent isn't captured correctly. It's important to examine the code and correct the problem. Otherwise, your code won't behave the way you expected it to. + +This problem is often caused by using `&&`; in place of `||`, but can also be caused by using `==` where `!=` was intended. + +Code analysis name: `MUTUALINCLUSIONOVERANDISFALSE` ## Example @@ -47,4 +50,4 @@ void f(int x) } ``` -The analysis tool does not warn if the expression has side effects. +The analysis tool doesn't warn if the expression has side effects. diff --git a/docs/code-quality/c6289.md b/docs/code-quality/c6289.md index ab7c412697..c5d8c1e205 100644 --- a/docs/code-quality/c6289.md +++ b/docs/code-quality/c6289.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6289" -title: C6289 +description: "Learn more about: Warning C6289" +title: Warning C6289 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6289"] +f1_keywords: ["C6289", "MUTUALEXCLUSIONOVERORISTRUE", "__WARNING_MUTUALEXCLUSIONOVERORISTRUE"] helpviewer_keywords: ["C6289"] ms.assetid: 0fe09974-7577-468b-91a0-62dbe915443e --- -# C6289 +# Warning C6289 -> warning C6289: Incorrect operator: mutual exclusion over || is always a non-zero constant. Did you intend to use && instead? +> Incorrect operator: mutual exclusion over `||` is always a non-zero constant. Did you intend to use `&&` instead? -This warning indicates that in a test expression a variable is being tested against two different constants and the result depends on either condition being true. This always evaluates to true. +## Remarks -This problem is generally caused by using `||` in place of `&&`, but can also be caused by using `!=` where `==` was intended. +This warning indicates that in a test expression a variable is being tested as unequal to two different constants. The result depends on either condition being true, but it always evaluates to true. + +This problem is often caused by using `||` in place of `&&`, but can also be caused by using `!=` where `==` was intended. + +Code analysis name: `MUTUALEXCLUSIONOVERORISTRUE` ## Example diff --git a/docs/code-quality/c6290.md b/docs/code-quality/c6290.md index a278c37cb1..2557e2d286 100644 --- a/docs/code-quality/c6290.md +++ b/docs/code-quality/c6290.md @@ -1,21 +1,22 @@ --- -description: "Learn more about: C6290" -title: C6290 +description: "Learn more about: Warning C6290" +title: Warning C6290 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6290"] +f1_keywords: ["C6290", "LOGICALNOTBITWISEAND", "__WARNING_LOGICALNOTBITWISEAND"] helpviewer_keywords: ["C6290"] ms.assetid: 96a1acc4-724b-4b56-b091-661ddcc03884 --- -# C6290 +# Warning C6290 -> warning C6290: Bitwise operation on logical result: ! has higher precedence than &. Use && or (!(x & y)) instead +> Bitwise operation on logical result: ! has higher precedence than &. Use && or (!(x & y)) instead This warning indicates possible confusion in the use of an operator or an operator precedence. +## Remarks + The `!` operator yields a Boolean result, and it has higher precedence than the `&`. The bitwise-and (&) operator takes two arithmetic arguments. Therefore, one of the following errors has been detected: -- The expression is mis-parenthesised: +- The expression is mis-parenthesized: Because the result of `!` is Boolean (zero or one), an attempt to test that two variables have bits in common will only end up testing that the lowest bit is present in the right side: `((!8) & 1) == 0`. @@ -25,9 +26,11 @@ The `!` operator yields a Boolean result, and it has higher precedence than the - The binary operator `&` is incorrect, and should instead be `&&`: - While `&` can sometimes be interchanged with `&&`, it is not equivalent because it forces evaluation of the right side of the expression. Certain side effects in this type of expression can be terminal. + While `&` can sometimes be interchanged with `&&`, it isn't equivalent because it forces evaluation of the right side of the expression. Certain side effects in this type of expression can be terminal. + +It's difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. -It is difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. +Code analysis name: `LOGICALNOTBITWISEAND` ## Example diff --git a/docs/code-quality/c6291.md b/docs/code-quality/c6291.md index 0c87534151..9e2421a92b 100644 --- a/docs/code-quality/c6291.md +++ b/docs/code-quality/c6291.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C6291" -title: C6291 +description: "Learn more about: Warning C6291" +title: Warning C6291 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6291"] +f1_keywords: ["C6291", "LOGICALNOTBITWISEOR", "__WARNING_LOGICALNOTBITWISEOR"] helpviewer_keywords: ["C6291"] ms.assetid: d0457386-e403-43fa-b959-5b6a495fab42 --- -# C6291 +# Warning C6291 -> warning C6291: Bitwise operation on logical result: ! has higher precedence than |. Use || or (!(x | y)) instead +> Bitwise operation on logical result: ! has higher precedence than \|. Use \|\| or (!(x \| y)) instead The `!` operator yields a Boolean result, and the `|` (bitwise-or) operator takes two arithmetic arguments. The `!` operator also has higher precedence than `|`. Therefore, one of the following errors has been detected: -- The expression is mis-parenthesised: +- The expression is mis-parenthesized: Because the result of `!` is Boolean (zero or one), an attempt to test that two variables have bits set will only end up testing that the lowest bit is present in the right side: `((!x) | y) != (!(x | y))` when `x == 0` and `y == 1`. @@ -25,14 +24,16 @@ Therefore, one of the following errors has been detected: - The binary operator `|` is incorrect, and should instead be `||`: - Even though `|` can sometimes be interchanged with `||`, it is not equivalent because it forces evaluation of the right side of the expression. Certain side-effects in this type of expression can be terminal: `(!p | (*p == '\0'))`, when `p == NULL`, we must dereference it to evaluate the other half of the expression. + Even though `|` can sometimes be interchanged with `||`, it isn't equivalent because it forces evaluation of the right side of the expression. Certain side-effects in this type of expression can be terminal: `(!p | (*p == '\0'))`, when `p == NULL`, we must dereference it to evaluate the other half of the expression. -This warning is not reported if the `!` operator is on the right side of the `|` operator because this case is typically just the relatively harmless case of an incorrect operator. +This warning isn't reported if the `!` operator is on the right side of the `|` operator because this case is typically just the relatively harmless case of an incorrect operator. -It is difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. +It's difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. This warning always indicates possible confusion in the use of an operator or operator precedence. +Code analysis name: `LOGICALNOTBITWISEOR` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6292.md b/docs/code-quality/c6292.md index 0991c5685c..9b1926a741 100644 --- a/docs/code-quality/c6292.md +++ b/docs/code-quality/c6292.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6292" -title: C6292 +description: "Learn more about: Warning C6292" +title: Warning C6292 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6292"] +f1_keywords: ["C6292", "LOOP_COUNTS_UP_FROM_MAX", "__WARNING_LOOP_COUNTS_UP_FROM_MAX"] helpviewer_keywords: ["C6292"] ms.assetid: 23998c78-ebd7-4ba1-a391-7b31b170f8fe --- -# C6292 +# Warning C6292 -> warning C6292: ill-defined for-loop: counts up from maximum +> Ill-defined for-loop: counts up from maximum + +## Remarks This warning indicates that a for-loop might not function as intended. It occurs when a loop counts up from a maximum, but has a lower termination condition. This loop will terminate only after integer overflow occurs. +Code analysis name: `LOOP_COUNTS_UP_FROM_MAX` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6293.md b/docs/code-quality/c6293.md index e5f6233630..ae4618266c 100644 --- a/docs/code-quality/c6293.md +++ b/docs/code-quality/c6293.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6293" -title: C6293 +description: "Learn more about: Warning C6293" +title: Warning C6293 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6293"] +f1_keywords: ["C6293", "LOOP_INDEX_GOES_NEGATIVE", "__WARNING_LOOP_INDEX_GOES_NEGATIVE"] helpviewer_keywords: ["C6293"] ms.assetid: 24a475f6-fd93-4778-856a-9dd7941f7520 --- -# C6293 +# Warning C6293 -> warning C6293: Ill-defined for-loop: counts down from minimum +> Ill-defined for-loop: counts down from minimum + +## Remarks This warning indicates that a for-loop might not function as intended. It occurs when a loop counts down from a minimum, but has a higher termination condition. -A signed —or unsigned—index variable together with a negative increment will cause the loop to count negative until an overflow occurs. This will terminate the loop. +A signed or unsigned index variable, together with a negative increment, will cause the loop to count negative until an overflow occurs, which will terminate the loop. + +Code analysis name: `LOOP_INDEX_GOES_NEGATIVE` ## Example diff --git a/docs/code-quality/c6294.md b/docs/code-quality/c6294.md index 2dc5b09202..c67163e3f5 100644 --- a/docs/code-quality/c6294.md +++ b/docs/code-quality/c6294.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6294" -title: C6294 +description: "Learn more about: Warning C6294" +title: Warning C6294 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6294"] +f1_keywords: ["C6294", "LOOP_BODY_NEVER_EXECUTED", "__WARNING_LOOP_BODY_NEVER_EXECUTED"] helpviewer_keywords: ["C6294"] ms.assetid: 1171d76f-b862-416d-b7c0-7a29be5c132d --- -# C6294 +# Warning C6294 -> warning C6294: Ill-defined for-loop: initial condition does not satisfy test. Loop body not executed +> Ill-defined for-loop: initial condition does not satisfy test. Loop body not executed -This warning indicates that a for-loop cannot be executed because the terminating condition is true. This warning suggests that the programmer's intent is not correctly captured. +## Remarks + +This warning indicates that a for-loop can't be executed because the terminating condition is true. This warning suggests that the programmer's intent isn't correctly captured. + +Code analysis name: `LOOP_BODY_NEVER_EXECUTED` ## Example diff --git a/docs/code-quality/c6295.md b/docs/code-quality/c6295.md index 8896b62044..f0c587ef8e 100644 --- a/docs/code-quality/c6295.md +++ b/docs/code-quality/c6295.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6295" -title: C6295 +description: "Learn more about: Warning C6295" +title: Warning C6295 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6295"] +f1_keywords: ["C6295", "INFINITE_LOOP", "__WARNING_INFINITE_LOOP"] helpviewer_keywords: ["C6295"] ms.assetid: 64e890ee-b688-4487-938d-3928762b83a4 --- -# C6295 +# Warning C6295 -> warning C6295: Ill-defined for-loop: \ values are of the range "min" to "max". Loop executed indefinitely +> Ill-defined for-loop: '*variable*' values are of the range "min" to "max". Loop executed indefinitely + +## Remarks This warning indicates that a for-loop might not function as intended. The for-loop tests an unsigned value against zero (0) with >=. The result is always true, therefore the loop is infinite. +Code analysis name: `INFINITE_LOOP` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6296.md b/docs/code-quality/c6296.md index 365e75a8f1..e6f7da0340 100644 --- a/docs/code-quality/c6296.md +++ b/docs/code-quality/c6296.md @@ -1,44 +1,35 @@ --- -description: "Learn more about: C6296" -title: C6296 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6296"] +title: Warning C6296 +description: "Learn more about: Warning C6296" +ms.date: 03/30/2025 +f1_keywords: ["C6296", "LOOP_ONLY_EXECUTED_ONCE", "__WARNING_LOOP_ONLY_EXECUTED_ONCE"] helpviewer_keywords: ["C6296"] -ms.assetid: 226573e0-db18-4c44-8fc6-0bc09d1028bc --- -# C6296 +# Warning C6296 -> warning C6296: Ill-defined for-loop: Loop body only executed once +> Ill-defined for-loop. Loop body only executed once. -This warning indicates that a for-loop might not function as intended. When the index is unsigned and a loop counts down from zero, its body is run only once. +## Remarks + +This warning indicates that a for-loop might unintentionally execute only once. A loop with an unsigned index counting down from zero or a mistaken use of `==` might cause this warning. + +Code analysis name: `LOOP_ONLY_EXECUTED_ONCE` ## Example -The following code generates this warning: +The following example generates C6296. Each for-loop shown executes exactly once. ```cpp -void f( ) +int main() { - unsigned int i; + for (unsigned int i = 0; i < 10; i--) {} // C6296 + // Use the following line to resolve the warning: + // for (unsigned int i = 0; i < 10; i++) {} - for (i = 0; i < 100; i--) - { - // code ... - } -} -``` + for (int i = 0; i == 0; i++) {} // C6296 -To correct this warning, use the following code: - -```cpp -void f( ) -{ - unsigned int i; + for (int i = 0; i < 1; i++) {} // OK - for (i = 0; i < 100; i++) - { - // code ... - } + for (int i = 1; i > 0; i--) {} // OK } ``` diff --git a/docs/code-quality/c6297.md b/docs/code-quality/c6297.md index 8d8f72935a..2bbd49a68b 100644 --- a/docs/code-quality/c6297.md +++ b/docs/code-quality/c6297.md @@ -1,8 +1,8 @@ --- -title: C6297 +title: Warning C6297 description: "Describes causes of MSVC Code analysis warning C6297, and how to fix the issue." ms.date: 07/15/2020 -f1_keywords: ["C6297"] +f1_keywords: ["C6297", "RESULTOFSHIFTCASTTOLARGERSIZE", "__WARNING_RESULTOFSHIFTCASTTOLARGERSIZE"] helpviewer_keywords: ["C6297"] ms.assetid: 17b585f0-75e5-4fc0-935a-143ec67659f4 --- @@ -18,6 +18,8 @@ In this case, a 32-bit value was shifted left, and the result of that shift was If you don't want to lose bits, cast the value to shift to a 64-bit quantity before it's shifted. If you want to lose bits, perform the appropriate cast to `unsigned long` or a `short` type. Or, mask the result of the shift. Either approach eliminates this warning and makes the intent of the code clearer. +Code analysis name: `RESULTOFSHIFTCASTTOLARGERSIZE` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6298.md b/docs/code-quality/c6298.md index dfe553ad92..7887a8ee7c 100644 --- a/docs/code-quality/c6298.md +++ b/docs/code-quality/c6298.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6298" -title: C6298 +description: "Learn more about: Warning C6298" +title: Warning C6298 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6298"] +f1_keywords: ["C6298", "CONST_STRING_TO_WRITABLE_STRING", "__WARNING_CONST_STRING_TO_WRITABLE_STRING"] helpviewer_keywords: ["C6298"] ms.assetid: 986dc8e7-8596-4223-a66f-8616357d4399 --- -# C6298 +# Warning C6298 -> warning C6298: using a read-only string \ as a writable string argument: this will attempt to write into static read-only memory and cause random crashes +> Using a read-only string '*pointer*' as a writable string argument: this will attempt to write into static read-only memory and cause random crashes + +## Remarks This warning indicates the use of a constant string as an argument to a function that might modify the contents of that string. Because the compiler allocates constant strings in a static read-only memory, any attempts to modify it cause access violations and random crashes. -This can be avoided by storing the constant string into a local array and then using the array as the argument to the function. +This warning can be avoided by storing the constant string into a local array and then using the array as the argument to the function. + +Code analysis name: `CONST_STRING_TO_WRITABLE_STRING` ## Example diff --git a/docs/code-quality/c6299.md b/docs/code-quality/c6299.md index 3d06705708..43c347fece 100644 --- a/docs/code-quality/c6299.md +++ b/docs/code-quality/c6299.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6299" -title: C6299 +description: "Learn more about: Warning C6299" +title: Warning C6299 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6299"] +f1_keywords: ["C6299", "BITFIELD_TO_BOOL_COMPARISON", "__WARNING_BITFIELD_TO_BOOL_COMPARISON"] helpviewer_keywords: ["C6299"] ms.assetid: 5129ac34-0d4f-4056-aea2-b0df2127dead --- -# C6299 +# Warning C6299 -> warning C6299: explicitly comparing a bit field to a Boolean type will yield unexpected results +> Explicitly comparing a bit field to a Boolean type will yield unexpected results + +## Remarks This warning indicates an incorrect assumption that Booleans and bit fields are equivalent. Assigning 1 to bit fields will place 1 in its single bit; however, any comparison of this bit field to 1 includes an implicit cast of the bit field to a signed int. This cast will convert the stored 1 to a -1 and the comparison can yield unexpected results. +Code analysis name: `BITFIELD_TO_BOOL_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6302.md b/docs/code-quality/c6302.md index ba0540bb29..e7e9a30709 100644 --- a/docs/code-quality/c6302.md +++ b/docs/code-quality/c6302.md @@ -1,42 +1,44 @@ --- -description: "Learn more about: C6302" -title: C6302 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6302"] +description: "Learn more about: Warning C6302" +title: Warning C6302 +ms.date: 03/07/2023 +f1_keywords: ["C6302", "CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6302"] -ms.assetid: b0b33103-6a0a-4c5b-bdb4-1b55ce877e74 --- -# C6302 +# Warning C6302 -> warning C6302: format string mismatch: character string passed as parameter \ when wide character string is required in call to \ +> Format string mismatch. -This warning indicates that the format string specifies a wide character string is expected. However, a character string is being passed. This will likely cause the output to be malformed or for the program to crash at runtime. +## Remarks + +This warning indicates that a format string specifies a wide character string, but is being passed a narrow character string instead. One cause of the warning is because the meaning of `%s` and `%S` flip when used with `printf` or `wprintf`. This defect can lead to crashes, in addition to potentially incorrect output. + +Code analysis name: `CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -```cpp -#include +The following code generates this warning. `buff` is a narrow character string, but `wprintf_s` is the wide string variant of `printf_s` and so expects `%s` to be wide: +```cpp void f() { - char buff[5] = "hi"; - - // Oops, because this is wprintf, the %s format specifier will interpret the argument as a wide string. - wprintf_s(L"%s", buff); + char buff[5] = "hi"; + wprintf_s(L"%s", buff); } ``` -The following sample code uses `%hs` to specify a single-byte character string with `wprintf_s` function: +The following sample code remediates this issue by using `%hs` to specify a single-byte character string. Alternatively it could have switched to `%S`, which is a narrow string when used with `wprintf` like functions. See [Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md#type-field-characters) for more options. ```cpp -#include - void f() { - char buff[5] = "hi"; - - // Use %hs format specifier so wprintf_s will interpret the argument correctly as a character string - wprintf_s(L"%hs", buff); + char buff[5] = "hi"; + wprintf_s(L"%hs", buff); } ``` + +## See also + +[Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C6303](./C6303.md) diff --git a/docs/code-quality/c6303.md b/docs/code-quality/c6303.md index 9e013b0c66..bb481fe624 100644 --- a/docs/code-quality/c6303.md +++ b/docs/code-quality/c6303.md @@ -1,55 +1,48 @@ --- -description: "Learn more about: C6303" -title: C6303 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6303"] +description: "Learn more about: Warning C6303" +title: Warning C6303 +ms.date: 03/07/2023 +f1_keywords: ["C6303", "WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6303"] -ms.assetid: b29aa352-9382-49d4-aeb8-03f34b0639a0 --- -# C6303 +# Warning C6303 -> warning C6303: format string mismatch: wide character string passed as parameter \ when character string is required in call to \ +> Format string mismatch. -This warning indicates that the format string specifies that a character string is required. However, a wide character string is being passed. This defect is likely to cause a crash or corruption of some form. +## Remarks + +This warning indicates that a format string specifies a narrow character string, but is being passed a wide character string instead. One cause of the warning is because the meaning of `%s` and `%S` flip when used with `printf` or `wprintf`. This defect can lead to crashes, in addition to potentially incorrect output. + +Code analysis name: `WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -The following sample code generates this warning: +The following sample code generates this warning. `buff` is a wide character string, but the `printf_s` call expects a short string as denoted by `%s`: ```cpp #include void f() { - wchar_t buff[5] = L"hi"; - - printf("%s", buff); + wchar_t buff[5] = L"hi"; + printf_s("%s", buff); } ``` -To correct this warning, use `%ls` as shown in the following sample code: +The following sample code remediates this issue by using `%ls` to specify a wide character string. Alternatively it could have switched to `%S`, which is a wide string when used with `printf` like functions. See [Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md#type-field-characters) for more options. ```cpp #include void f() { - wchar_t buff[5] = L"hi"; - - printf("%ls", buff); + wchar_t buff[5] = L"hi"; + printf_s("%ls", buff); } ``` -The following sample code uses safe string manipulation function `printf_s` to correct this warning: - -```cpp -#include - -void f() -{ - wchar_t buff[5] = L"hi"; +## See also - printf_s("%ls",buff); -} -``` +[Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C6302](./C6302.md) diff --git a/docs/code-quality/c6305.md b/docs/code-quality/c6305.md index 78c7c63ded..72f3f0ec9d 100644 --- a/docs/code-quality/c6305.md +++ b/docs/code-quality/c6305.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6305" -title: C6305 +description: "Learn more about: Warning C6305" +title: Warning C6305 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6305"] +f1_keywords: ["C6305", "SIZEOF_COUNTOF_MISMATCH", "__WARNING_SIZEOF_COUNTOF_MISMATCH"] helpviewer_keywords: ["C6305"] ms.assetid: 4b3bdf86-b593-425e-89cb-9282878b21bd --- -# C6305 +# Warning C6305 -> warning C6305: potential mismatch between sizeof and countof quantities +> Potential mismatch between sizeof and countof quantities -This warning indicates that a variable holding a **`sizeof`** result is being added to or subtracted from a pointer or `countof` expression. This will cause unexpected scaling in pointer arithmetic. +## Remarks + +This warning indicates that a variable holding a **`sizeof`** result is being added to or subtracted from a pointer or `countof` expression. This operation will cause unexpected scaling in pointer arithmetic. + +Code analysis name: `SIZEOF_COUNTOF_MISMATCH` ## Example diff --git a/docs/code-quality/c6306.md b/docs/code-quality/c6306.md index d8be24ee32..7235deeb6e 100644 --- a/docs/code-quality/c6306.md +++ b/docs/code-quality/c6306.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6306" -title: C6306 +description: "Learn more about: Warning C6306" +title: Warning C6306 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6306"] +f1_keywords: ["C6306", "INCORRECT_VARARG_FUNCTIONCALL", "__WARNING_INCORRECT_VARARG_FUNCTIONCALL"] helpviewer_keywords: ["C6306"] ms.assetid: 7502710c-7e0e-4412-aecc-b6821cb8c182 --- -# C6306 +# Warning C6306 -> warning C6306: incorrect call to \: consider using \ which accepts a va_list as an argument +> Incorrect call to '*function*': consider using '*function*' which accepts a va_list as an argument -This warning indicates an incorrect function call. The `printf` family includes several functions that take a variable list of arguments; however, these functions cannot be called with a `va_list` argument. There is a corresponding `vprintf` family of functions that can be used for such calls. Calling the wrong print function will cause incorrect output. +## Remarks + +This warning indicates an incorrect function call. The `printf` family includes several functions that take a variable list of arguments; however, these functions can't be called with a `va_list` argument. There's a corresponding `vprintf` family of functions that can be used for such calls. Calling the wrong print function will cause incorrect output. + +Code analysis name: `INCORRECT_VARARG_FUNCTIONCALL` ## Example diff --git a/docs/code-quality/c6308.md b/docs/code-quality/c6308.md index c06cd5c712..07cba3b71f 100644 --- a/docs/code-quality/c6308.md +++ b/docs/code-quality/c6308.md @@ -1,21 +1,24 @@ --- -title: C6308 +title: Warning C6308 description: "Understand the causes of Microsoft C/C++ code analysis warning C6308, and learn how to fix them." -ms.date: 10/23/2020 -ms.topic: reference -f1_keywords: ["C6308"] +ms.date: 09/28/2022 +f1_keywords: ["C6308", "REALLOCLEAK", "__WARNING_REALLOCLEAK"] helpviewer_keywords: ["C6308"] ms.assetid: 1162cd96-9037-4576-9858-0c8361a12559 --- -# C6308 +# Warning C6308 -> warning C6308: 'realloc' may return null pointer: assigning a null pointer to \, which is passed as an argument to 'realloc', will cause the original memory block to be leaked +> 'realloc' may return null pointer: assigning a null pointer to '*parameter-name*', which is passed as an argument to 'realloc', will cause the original memory block to be leaked -This warning indicates a memory leak that is the result of the incorrect use of a reallocation function. Heap reallocation functions do not free the passed buffer if reallocation is unsuccessful. To correct the defect, assign the result of the reallocation function to a temporary, and then replace the original pointer after successful reallocation. +## Remarks + +Heap reallocation functions don't free the passed buffer if reallocation is unsuccessful, potentially resulting in a memory leak if not handled properly. To correct the issue, assign the result of the reallocation function to a temporary variable, and then replace the original pointer after successful reallocation. + +Code analysis name: `REALLOCLEAK` ## Example -The following sample code generates this warning: +The following sample code generates warning C6308. This issue stems from the assignment of the return value from `realloc` to `x`. If `realloc` fails and returns a null pointer, then the original memory pointed to by `x` won't be freed: ```cpp #include @@ -23,18 +26,17 @@ The following sample code generates this warning: void f( ) { - char *x; - x = (char *) malloc(10); - if (x != NULL) - { - x = (char *) realloc(x, 512); - // code... - free(x); - } + char *x = (char *) malloc(10); + if (x != NULL) + { + x = (char *) realloc(x, 512); + // code... + free(x); + } } ``` -To correct this warning, use the following code: +To resolve the issue, you can create a temporary variable to store the return value of `realloc`. This change allows you to free the previously allocated memory safely if `realloc` fails: ```cpp #include @@ -42,27 +44,24 @@ To correct this warning, use the following code: void f() { - char *x, *tmp; - - x = (char *) malloc(10); - - if (x != NULL) - { - tmp = (char *) realloc(x,512); - if (tmp != NULL) + char *x = (char *) malloc(10); + if (x != NULL) { - x = tmp; + char *tmp = (char *) realloc(x,512); + if (tmp != NULL) + { + x = tmp; + } + // code... + free(x); } - // code... - free(x); - } } ``` -This warning might generate noise if there is a live alias to the buffer-to-be-reallocated at the time of the assignment of the result of the reallocation function. +This warning might generate noise if there's a live alias to the buffer-to-be-reallocated at the time of the assignment of the result of the reallocation function. -To avoid these kinds of problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of issues altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -[C6014](../code-quality/c6014.md) +[Warning C6014](../code-quality/c6014.md) diff --git a/docs/code-quality/c6310.md b/docs/code-quality/c6310.md index 6d35ade07a..88dd7cb380 100644 --- a/docs/code-quality/c6310.md +++ b/docs/code-quality/c6310.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: C6310" -title: C6310 +description: "Learn more about: Warning C6310" +title: Warning C6310 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6310"] +f1_keywords: ["C6310", "ILLEGALEXCEPTEXPRCONST", "__WARNING_ILLEGALEXCEPTEXPRCONST"] helpviewer_keywords: ["C6310"] ms.assetid: e759eb63-883f-4c3e-bf2f-b924ff511405 --- -# C6310 +# Warning C6310 -> warning C6310: illegal constant in exception filter can cause unexpected behavior +> Illegal constant in exception filter can cause unexpected behavior + +## Remarks This message indicates that an illegal constant was detected in the filter expression of a structured exception handler. The constants defined for use in the filter expression of a structured exception handler are: @@ -21,7 +22,9 @@ This message indicates that an illegal constant was detected in the filter expre These values are defined in the run-time header file excpt.h. -Using a constant that is not in the preceding list can cause unexpected behavior. +Using a constant that isn't in the preceding list can cause unexpected behavior. + +Code analysis name: `ILLEGALEXCEPTEXPRCONST` ## Example diff --git a/docs/code-quality/c6312.md b/docs/code-quality/c6312.md index 7289e2e1d0..eada1991cc 100644 --- a/docs/code-quality/c6312.md +++ b/docs/code-quality/c6312.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: C6312" -title: C6312 +description: "Learn more about: Warning C6312" +title: Warning C6312 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6312"] +f1_keywords: ["C6312", "EXCEPTIONCONTINUEEXECUTION", "__WARNING_EXCEPTIONCONTINUEEXECUTION"] helpviewer_keywords: ["C6312"] ms.assetid: 1fc8b9a1-e6ba-4799-84c3-31f289576cca --- -# C6312 +# Warning C6312 -> warning C6312: Possible infinite loop: use of the constant EXCEPTION_CONTINUE_EXECUTION in the exception-filter expression of a try-except +> Possible infinite loop: use of the constant EXCEPTION_CONTINUE_EXECUTION in the exception-filter expression of a try-except -This warning indicates the use of the constant `EXCEPTION_CONTINUE_EXECUTION` (or another constant that evaluates to -1) in the filter expression of a structured exception handler. Use of the constant value `EXCEPTION_CONTINUE_EXECUTION` could lead to an infinite loop. For example, if an exception was raised by hardware, the instruction that caused the exception will be restarted. If the address that caused the exception is still bad, another exception will occur and be handled in the same way. This causes an infinite loop. +## Remarks -An explicit call to `RaiseException` will not directly cause an infinite loop, but it will continue execution of the code in the protected block. This can be unexpected, and could lead to an infinite loop if `RaiseException` was used to avoid dereferencing an invalid pointer. +This warning indicates the use of the constant `EXCEPTION_CONTINUE_EXECUTION` (or another constant that evaluates to -1) in the filter expression of a structured exception handler. Use of the constant value `EXCEPTION_CONTINUE_EXECUTION` could lead to an infinite loop. For example, if an exception was raised by hardware, the instruction that caused the exception will be restarted. If the address that caused the exception is still bad, another exception will occur and be handled in the same way. The result is an infinite loop. + +An explicit call to `RaiseException` won't directly cause an infinite loop, but it will continue execution of the code in the protected block. This behavior can be unexpected, and could lead to an infinite loop if `RaiseException` was used to avoid dereferencing an invalid pointer. Typically, `EXCEPTION_CONTINUE_EXECUTION` should be returned only by a function called in the filter expression, which has a chance to fix either the pointer that caused the exception or the underlying memory. +Code analysis name: `EXCEPTIONCONTINUEEXECUTION` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6313.md b/docs/code-quality/c6313.md index ba210cddbe..b8b7bc1296 100644 --- a/docs/code-quality/c6313.md +++ b/docs/code-quality/c6313.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6313" -title: C6313 +description: "Learn more about: Warning C6313" +title: Warning C6313 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6313"] +f1_keywords: ["C6313", "BITANDVSZEROVALUEDFLAG", "__WARNING_BITANDVSZEROVALUEDFLAG"] helpviewer_keywords: ["C6313"] ms.assetid: 2fb95c62-d81e-4525-9ec7-7723844c806c --- -# C6313 +# Warning C6313 -> warning C6313: Incorrect operator: Zero-valued flag cannot be tested with bitwise-and. Use an equality test to check for zero-valued flags +> Incorrect operator: Zero-valued flag cannot be tested with bitwise-and. Use an equality test to check for zero-valued flags + +## Remarks This warning indicates that a constant value of zero was provided as an argument to the bitwise-and (`&`) operator in a test context. The resulting expression is constant and evaluates to false; the result is different than intended. -This is typically caused by using bitwise-and to test for a flag that has the value zero. To test zero-valued flags, a test for equality must be performed, for example, using `==` or `!=`. +This warning is typically caused by using bitwise-and to test for a flag that has the value zero. To test zero-valued flags, a test for equality must be performed, for example, using `==` or `!=`. + +Code analysis name: `BITANDVSZEROVALUEDFLAG` ## Example diff --git a/docs/code-quality/c6314.md b/docs/code-quality/c6314.md index b63dc08613..a0f47a7fee 100644 --- a/docs/code-quality/c6314.md +++ b/docs/code-quality/c6314.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6314" -title: C6314 +description: "Learn more about: Warning C6314" +title: Warning C6314 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6314"] +f1_keywords: ["C6314", "BITORVSQUESTION", "__WARNING_BITORVSQUESTION"] helpviewer_keywords: ["C6314"] ms.assetid: 2145ca62-967c-4223-b582-f1481b74f181 --- -# C6314 +# Warning C6314 -> warning C6314: Incorrect order of operations: bitwise-or has higher precedence than the conditional-expression operator. Add parentheses to clarify intent +> Incorrect order of operations: bitwise-or has higher precedence than the conditional-expression operator. Add parentheses to clarify intent + +## Remarks This message indicates that an expression that contains a bitwise-or operator (`|`) was detected in the tested expression of a conditional operation (`?:`). The conditional operator has lower precedence than bitwise operators. If the tested expression should contain the bitwise-or operator, then parentheses should be added around the conditional-expression. +Code analysis name: `BITORVSQUESTION` + ## Example The following code generates this warning: @@ -41,5 +44,5 @@ int f(int SignalValue) ## See also -- [Bitwise Inclusive OR Operator: |](../cpp/bitwise-inclusive-or-operator-pipe.md) +- [Bitwise Inclusive OR Operator: \|](../cpp/bitwise-inclusive-or-operator-pipe.md) - [Conditional Operator: ? :](../cpp/conditional-operator-q.md) diff --git a/docs/code-quality/c6315.md b/docs/code-quality/c6315.md index 2ca23c75ad..e367214b1d 100644 --- a/docs/code-quality/c6315.md +++ b/docs/code-quality/c6315.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6315" -title: C6315 +description: "Learn more about: Warning C6315" +title: Warning C6315 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6315"] +f1_keywords: ["C6315", "BITORVSBITAND", "__WARNING_BITORVSBITAND"] helpviewer_keywords: ["C6315"] ms.assetid: 4bc932d5-04fd-440d-b3af-e32a8bbc0618 --- -# C6315 +# Warning C6315 -> warning C6315: Incorrect order of operations: bitwise-and has higher precedence than bitwise-or. Add parentheses to clarify intent +> Incorrect order of operations: bitwise-and has higher precedence than bitwise-or. Add parentheses to clarify intent + +## Remarks This warning indicates that an expression in a test context contains both bitwise-and (`&`) and bitwise-or (`|`) operations, but causes a constant because the bitwise-or operation happens last. Parentheses should be added to clarify intent. +Code analysis name: `BITORVSBITAND` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6316.md b/docs/code-quality/c6316.md index cd520cd7fe..b5c3383508 100644 --- a/docs/code-quality/c6316.md +++ b/docs/code-quality/c6316.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6316" -title: C6316 +description: "Learn more about: Warning C6316" +title: Warning C6316 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6316"] +f1_keywords: ["C6316", "INAPPROPRIATEUSEOFBITOR", "__WARNING_INAPPROPRIATEUSEOFBITOR"] helpviewer_keywords: ["C6316"] ms.assetid: ddd6a928-76b1-4d1b-9a9d-af1efcf02e3a --- -# C6316 +# Warning C6316 -> warning C6316: Incorrect operator: tested expression is constant and non-zero. Use bitwise-and to determine whether bits are set +> Incorrect operator: tested expression is constant and non-zero. Use bitwise-and to determine whether bits are set + +## Remarks This warning indicates the use of bitwise-or (`|`) when bitwise-and (`&`) should have been used. Bitwise-or adds bits to the resulting expression, whereas bitwise-and selects only those bits in common between its two operators. Tests for flags must be performed with bitwise-and or a test of equality. +Code analysis name: `INAPPROPRIATEUSEOFBITOR` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6317.md b/docs/code-quality/c6317.md index 45c7e3bd1e..62319ef781 100644 --- a/docs/code-quality/c6317.md +++ b/docs/code-quality/c6317.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6317" -title: C6317 +description: "Learn more about: Warning C6317" +title: Warning C6317 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6317"] +f1_keywords: ["C6317", "NOTNOTCOMPLEMENT", "__WARNING_NOTNOTCOMPLEMENT"] helpviewer_keywords: ["C6317"] ms.assetid: dc771bb8-f596-4514-af0f-4b39658af365 --- -# C6317 +# Warning C6317 -> warning C6317: incorrect operator: logical-not (!) is not interchangeable with ones-complement (~) +> Incorrect operator: logical-not (!) is not interchangeable with ones-complement (~) -This warning indicates that a logical-not (`!`) is being applied to a constant that is likely to be a bit-flag. The result of logical-not is Boolean; it is incorrect to apply the bitwise-and (`&`) operator to a Boolean value. Use the ones-complement (`~`) operator to flip flags. +## Remarks + +This warning indicates that a logical-not (`!`) is being applied to a constant that is likely to be a bit-flag. The result of logical-not is Boolean; it's incorrect to apply the bitwise-and (`&`) operator to a Boolean value. Use the ones-complement (`~`) operator to flip flags. + +Code analysis name: `NOTNOTCOMPLEMENT` ## Example diff --git a/docs/code-quality/c6318.md b/docs/code-quality/c6318.md index 04be16a9dd..07cb2c8ccf 100644 --- a/docs/code-quality/c6318.md +++ b/docs/code-quality/c6318.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: C6318" -title: C6318 +description: "Learn more about: Warning C6318" +title: Warning C6318 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6318"] +f1_keywords: ["C6318", "EXCEPTIONCONTINUESEARCH", "__WARNING_EXCEPTIONCONTINUESEARCH"] helpviewer_keywords: ["C6318"] ms.assetid: 3284a83e-bb8e-461c-adcc-cfc66ceea05e --- -# C6318 +# Warning C6318 -> warning C6318: Ill-defined __try/\__except: use of the constant EXCEPTION_CONTINUE_SEARCH or another constant that evaluates to zero in the exception-filter expression. The code in the exception handler block is not executed +> Ill-defined `__try`/`__except`: use of the constant EXCEPTION_CONTINUE_SEARCH or another constant that evaluates to zero in the exception-filter expression. The code in the exception handler block is not executed -This warning indicates that if an exception occurs in the protected block of this structured exception handler, the exception will not be handled because the constant `EXCECPTION_CONTINUE_SEARCH` is used in the exception filter expression. +## Remarks -This code is equivalent to the protected block without the exception handler block because the handler block is not executed. +This warning indicates that if an exception occurs in the protected block of this structured exception handler, the exception won't be handled because the constant `EXCECPTION_CONTINUE_SEARCH` is used in the exception filter expression. + +This code is equivalent to the protected block without the exception handler block because the handler block isn't executed. + +Code analysis name: `EXCEPTIONCONTINUESEARCH` ## Example diff --git a/docs/code-quality/c6319.md b/docs/code-quality/c6319.md index 9721879b60..4d6642ab6f 100644 --- a/docs/code-quality/c6319.md +++ b/docs/code-quality/c6319.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6319" -title: C6319 +description: "Learn more about: Warning C6319" +title: Warning C6319 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6319"] +f1_keywords: ["C6319", "IGNOREDBYCOMMA", "__WARNING_IGNOREDBYCOMMA"] helpviewer_keywords: ["C6319"] ms.assetid: 3ccfc1d4-820d-48f0-8ff0-8fcfc87c45d6 --- -# C6319 +# Warning C6319 -> warning C6319: use of the comma-operator in a tested expression causes the left argument to be ignored when it has no side-effects +> Use of the comma-operator in a tested expression causes the left argument to be ignored when it has no side-effects -This warning indicates an ignored sub-expression in test context because of the comma-operator (,). The comma operator has left-to-right associativity. The result of the comma-operator is the last expression evaluated. If the left expression to comma-operator has no side effects, the compiler might omit code generation for the expression. +## Remarks + +This warning indicates an ignored sub-expression in test context because of the comma-operator (**`,`**). The comma operator has left-to-right associativity. The result of the comma-operator is the last expression evaluated. If the left expression to comma-operator has no side effects, the compiler might omit code generation for the expression. + +Code analysis name: `IGNOREDBYCOMMA` ## Example diff --git a/docs/code-quality/c6320.md b/docs/code-quality/c6320.md index c5d91299bb..9229dc3c39 100644 --- a/docs/code-quality/c6320.md +++ b/docs/code-quality/c6320.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6320" -title: C6320 +description: "Learn more about: Warning C6320" +title: Warning C6320 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6320"] +f1_keywords: ["C6320", "EXCEPTIONEXECUTEHANDLER", "__WARNING_EXCEPTIONEXECUTEHANDLER"] helpviewer_keywords: ["C6320"] ms.assetid: fb9e568e-b3d4-4ce2-a276-a64ad74d7b1e --- -# C6320 +# Warning C6320 -> warning C6320: exception-filter expression is the constant EXCEPTION_EXECUTE_HANDLER. This may mask exceptions that were not intended to be handled +> Exception-filter expression is the constant EXCEPTION_EXECUTE_HANDLER. This may mask exceptions that were not intended to be handled -This warning indicates the side effect of using EXCEPTION_EXECUTE_HANDLER constant in __except block. In this case, the statement in the \__except block will always execute to handle the exception, including exceptions you did not want to handle in a particular function. It is recommended that you check the exception before handling it. +## Remarks + +This warning indicates the side effect of using `EXCEPTION_EXECUTE_HANDLER` constant in an `__except` block. In this case, the statement in the `__except` block will always execute to handle the exception, including exceptions you didn't want to handle in a particular function. It's recommended that you check the exception before handling it. + +Code analysis name: `EXCEPTIONEXECUTEHANDLER` ## Example -The following code generates this warning because the __except block will try to handle exceptions of all types: +The following code generates this warning because the `__except` block will try to handle exceptions of all types: ```cpp #include diff --git a/docs/code-quality/c6322.md b/docs/code-quality/c6322.md index a5587f9474..cd3a8ac432 100644 --- a/docs/code-quality/c6322.md +++ b/docs/code-quality/c6322.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6322" -title: C6322 +description: "Learn more about: Warning C6322" +title: Warning C6322 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6322"] +f1_keywords: ["C6322", "EXCEPT_BLOCK_EMPTY", "__WARNING_EXCEPT_BLOCK_EMPTY"] helpviewer_keywords: ["C6322"] ms.assetid: fb23d2b1-b2a0-465c-8bf5-ec039c6c7757 --- -# C6322 +# Warning C6322 -> warning C6322: empty _except block +> Empty `__except` block -This message indicates that there is no code in the _except block. As a result, exceptions might go unhandled. +## Remarks + +This message indicates that there's no code in the `__except` block. As a result, exceptions might go unhandled. + +Code analysis name: `EXCEPT_BLOCK_EMPTY` ## Example @@ -26,7 +29,7 @@ void fd(char *pch) { __try { - // exception rasied if pch is null + // exception raised if pch is null *pch= 0 ; } __except(GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION) @@ -46,7 +49,7 @@ void f(char *pch) { __try { - // exception rasied if pch is null + // exception raised if pch is null *pch= 0 ; } __except(GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION ? @@ -60,4 +63,4 @@ void f(char *pch) ## See also -[try-except Statement](../cpp/try-except-statement.md) +[`try-except` Statement](../cpp/try-except-statement.md) diff --git a/docs/code-quality/c6323.md b/docs/code-quality/c6323.md index 40ebde2dc6..ad59ba354e 100644 --- a/docs/code-quality/c6323.md +++ b/docs/code-quality/c6323.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6323" -title: C6323 +description: "Learn more about: Warning C6323" +title: Warning C6323 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6323"] +f1_keywords: ["C6323", "ARITH_OP_ON_BOOL", "__WARNING_ARITH_OP_ON_BOOL"] helpviewer_keywords: ["C6323"] ms.assetid: e9ab47d7-21e1-4204-8dad-ed7ec6127647 --- -# C6323 +# Warning C6323 -> warning C6323 - use of arithmetic operator on Boolean type(s) +> Use of arithmetic operator on Boolean type(s) -This warning occurs if arithmetic operators are used on Boolean data types. Use of incorrect operator might yield incorrect results. It also indicates that the programmer's intent is not reflected in the code. +## Remarks + +This warning occurs if arithmetic operators are used on Boolean data types. Use of incorrect operator might yield incorrect results. It also indicates that the programmer's intent isn't reflected in the code. + +Code analysis name: `ARITH_OP_ON_BOOL` ## Example diff --git a/docs/code-quality/c6324.md b/docs/code-quality/c6324.md index adb3164dde..063ee638a8 100644 --- a/docs/code-quality/c6324.md +++ b/docs/code-quality/c6324.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6324" -title: C6324 +description: "Learn more about: Warning C6324" +title: Warning C6324 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6324"] +f1_keywords: ["C6324", "STRCPY_INSTEAD_OF_STRCMP", "__WARNING_STRCPY_INSTEAD_OF_STRCMP"] helpviewer_keywords: ["C6324"] ms.assetid: 08675af3-8957-4640-9bd6-01de71ea1042 --- -# C6324 +# Warning C6324 -> warning C6324: potential incorrect use of \: Did you intend to use \? +> Potential incorrect use of '*function1*': Did you intend to use '*function2*'? -This warning indicates that a string copy function was used where a string comparison function should have been used. Incorrect use of function can cause an unexpected logic error. +## Remarks + +This warning indicates that a string copy function was used where a string comparison function should have been used. Incorrect use of the function can cause an unexpected logic error. + +Code analysis name: `STRCPY_INSTEAD_OF_STRCMP` ## Example diff --git a/docs/code-quality/c6326.md b/docs/code-quality/c6326.md index d365061ac4..ed317497b1 100644 --- a/docs/code-quality/c6326.md +++ b/docs/code-quality/c6326.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6326" -title: C6326 +description: "Learn more about: Warning C6326" +title: Warning C6326 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6326"] +f1_keywords: ["C6326", "CONST_CONST_COMP", "__WARNING_CONST_CONST_COMP"] helpviewer_keywords: ["C6326"] ms.assetid: 0b606d29-e3c2-48b5-b520-b71b670c19a1 --- -# C6326 +# Warning C6326 -> warning C6326: potential comparison of a constant with another constant +> Potential comparison of a constant with another constant + +## Remarks This warning indicates a potential comparison of a constant with another constant, which is redundant code. You must check to make sure that your intent is properly captured in the code. In some cases, you can simplify the test condition to achieve the same result. +Code analysis name: `CONST_CONST_COMP` + ## Example The following code generates this warning because two constants are compared: diff --git a/docs/code-quality/c6328.md b/docs/code-quality/c6328.md index 790cb0fb91..87bb1426d8 100644 --- a/docs/code-quality/c6328.md +++ b/docs/code-quality/c6328.md @@ -1,46 +1,66 @@ --- -description: "Learn more about: C6328" -title: C6328 -ms.date: 10/16/2019 -ms.topic: reference -f1_keywords: ["C6328"] +description: "Learn more about: Warning C6328" +title: Warning C6328 +ms.date: 02/14/2024 +f1_keywords: ["C6328", "FORMAT_SIZE_MISMATCH", "__WARNING_FORMAT_SIZE_MISMATCH"] helpviewer_keywords: ["C6328"] ms.assetid: e25b00fa-d344-4dc9-b322-b4f1ae06f315 --- -# C6328 +# Warning C6328 -> warning C6328: Size mismatch: \ passed as parameter \ when \ is required in call to \ +> Size mismatch: '*type*' passed as _Param_(*number*) when '*type*' is required in call to '*function-name*' -Passing an argument of type **`char`** to C runtime, character-based routines named `is()`, for example, `isspace()`, can have unpredictable results. For example, an SBCS or MBCS single-byte character of type **`char`** with a value greater than `0x7F` is a negative value. If a **`char`** is passed, the compiler might convert the value to a signed **`int`** or a signed **`long`**. This value could be sign-extended by the compiler, with unexpected results. For example, `isspace` accepts an argument of type **`int`**; however, the valid range of values for its input argument is: +## Remarks -`0 <= c <= 255`, plus the special value `EOF`. +This warning indicates that type required by the format specifier and the type of the expression passed in don't match. +Using the wrong format specifier is undefined behavior. To fix the warning, make sure that the format specifiers match the types of the expressions passed in. + +Code analysis name: `FORMAT_SIZE_MISMATCH` ## Example -By default, **`char`** is a signed type in the Microsoft C++ compiler, so the range of values of a variable of type char is `-128 <= c <= 127`. Therefore, if you did the following, `c` would be sign-extended to a signed **`int`** with a value of -37, which is outside the valid range for [isspace](../standard-library/locale-functions.md#isspace): +```cpp +#include + +void f(long long a) +{ + printf("%d\n", a); // C6328 emitted. +} +``` + +There are multiple ways to fix the undefined behavior. We can change the format specifier: ```cpp -#include +#include -void f( ) +void f(long long a) { - char c = -37; - int retVal = isspace( c ); - // code ... + printf("%lld\n", a); // No C6328 emitted. } ``` -To correct this problem, you can use `static_cast`, as shown in the following code: +We can change the type of the expression: ```cpp -#include +#include -void f( ) +void f(int a) { - char c = -37; - int retVal = isspace( static_cast (c) ); - // code ... + printf("%d\n", a); // No C6328 emitted. } ``` -Warning C6328 exists specifically to catch this bug. For characters in the 7-bit ASCII range, the cast is unnecessary. Characters outside that range can have unpredictable results, for example, program fault and termination. +As a last resort when overflow can't happen, we can introduce a cast: + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhd\n", static_cast(a)); // No C6328 emitted. +} +``` + +## See also + +[C6340](c6340.md) diff --git a/docs/code-quality/c6329.md b/docs/code-quality/c6329.md index 209d363c68..b34263a856 100644 --- a/docs/code-quality/c6329.md +++ b/docs/code-quality/c6329.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6329" -title: C6329 +description: "Learn more about: Warning C6329" +title: Warning C6329 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6329"] +f1_keywords: ["C6329", "POTENTIAL_INCORRECT_RETVAL_CHECK", "__WARNING_POTENTIAL_INCORRECT_RETVAL_CHECK"] helpviewer_keywords: ["C6329"] ms.assetid: 5765bd4d-5fa1-4e51-82d6-c1837b4743db --- -# C6329 +# Warning C6329 -> warning C6329: Return value for a call to \ should not be checked against \ +> Return value for a call to '*function*' should not be checked against '*number*' + +## Remarks The program is comparing a number against the return value from a call to `CreateFile`. If `CreateFile` succeeds, it returns an open handle to the object. If it fails, it returns `INVALID_HANDLE_VALUE`. +Code analysis name: `POTENTIAL_INCORRECT_RETVAL_CHECK` + ## Examples This code could cause the warning: diff --git a/docs/code-quality/c6330.md b/docs/code-quality/c6330.md index 3737106126..d94d00c081 100644 --- a/docs/code-quality/c6330.md +++ b/docs/code-quality/c6330.md @@ -1,12 +1,13 @@ --- -description: "Learn more about: C6330" -title: C6330 +description: "Learn more about: Warning C6330" +title: Warning C6330 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6330"] +f1_keywords: ["C6330", "POTENTIAL_ARGUMENT_TYPE_MISMATCH", "__WARNING_POTENTIAL_ARGUMENT_TYPE_MISMATCH"] helpviewer_keywords: ["C6330"] ms.assetid: 48594e1c-0a4b-4848-8598-ae6d7e08b4e9 --- -# C6330 +# Warning C6330 -> warning C6330: Incorrect type passed as parameter in call to function +> '*type1*' passed as Parameter('*number*') when '*type2*' is required in call to '*function*' + +Code analysis name: `POTENTIAL_ARGUMENT_TYPE_MISMATCH` diff --git a/docs/code-quality/c6331.md b/docs/code-quality/c6331.md index 85f486d027..b0e322a1d4 100644 --- a/docs/code-quality/c6331.md +++ b/docs/code-quality/c6331.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6331" -title: C6331 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6331"] +title: Warning C6331 +description: "Learn more about: Warning C6331" +ms.date: 10/03/2022 +f1_keywords: ["C6331", "VirtualFreeInvalidParam1", "__WARNING_VIRTUALFREEINVALIDPARAM1"] helpviewer_keywords: ["C6331"] -ms.assetid: cb1ecc2c-29a5-4c57-acf2-0954a4c047b1 --- -# C6331 +# Warning C6331 -> warning C6331: Invalid parameter: passing MEM_RELEASE and MEM_DECOMMIT in conjunction to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing MEM_RELEASE and MEM_DECOMMIT in conjunction to *`function`* is not allowed. This results in the failure of this call -This message indicates that an invalid parameter being passed to VirtualFree or VirtualFreeEx. VirtualFree and VirtualFreeEx both reject the flags (MEM_RELEASE | MEM_DECOMMIT) in combination. Therefore, the values MEM_DECOMMIT and MEM_RELEASE may not be used together in the same call. +This message indicates that an invalid parameter is passed to `VirtualFree` or `VirtualFreeEx`. `VirtualFree` and `VirtualFreeEx` both reject the flags (`MEM_RELEASE | MEM_DECOMMIT`) in combination. Therefore, the values `MEM_DECOMMIT` and `MEM_RELEASE` may not be used together in the same call. -It is not required for decommit and release to occur as independent steps. Releasing committed memory will decommit the pages as well. Also, ensure the return value of this function is not ignored. +## Remarks + +It's not required for decommit and release to occur as independent steps. Releasing committed memory will decommit the pages as well. Also, ensure the return value of this function isn't ignored. + +Code analysis name: `VirtualFreeInvalidParam1` ## Example -The following sample code generates this warning: +The following sample code generates warning C6331: ```cpp #include @@ -56,7 +58,7 @@ VOID fd( VOID ) } ``` -To correct this warning, do not pass MEM_DECOMMIT value to VirtualFree call as shown in the following code: +To correct this warning, don't pass `MEM_DECOMMIT` to the `VirtualFree` call, as shown in the following code: ```cpp #include @@ -93,9 +95,9 @@ VOID f( VOID ) } ``` -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [VirtualAlloc Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method) -- [VirtualFree Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) +[`VirtualAlloc` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method)\ +[`VirtualFree` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) diff --git a/docs/code-quality/c6332.md b/docs/code-quality/c6332.md index ae7bed2bc9..acf5ef2d95 100644 --- a/docs/code-quality/c6332.md +++ b/docs/code-quality/c6332.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C6332" -title: C6332 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6332"] +description: "Learn more about: Warning C6332" +title: Warning C6332 +ms.date: 10/03/2022 +f1_keywords: ["C6332", "VirtualFreeInvalidParam2", "__WARNING_VIRTUALFREEINVALIDPARAM2"] helpviewer_keywords: ["C6332"] ms.assetid: 93d74b3f-4070-4b48-807e-52b1dfee1330 --- -# C6332 +# Warning C6332 -> warning C6332: Invalid parameter: passing zero as the dwFreeType parameter to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing zero as the dwFreeType parameter to '*function*' is not allowed. This results in the failure of this call -This warning indicates that an invalid parameter is being passed to VirtualFree or VirtualFreeEx. VirtualFree and VirtualFreeEx both reject a dwFreeType parameter of zero. The dwFreeType parameter can be either MEM_DECOMMIT or MEM_RELEASE. However, the values MEM_DECOMMIT and MEM_RELEASE may not be used together in the same call. Also, make sure that the return value of the VirtualFree function is not ignored. +This warning indicates that an invalid parameter is being passed to `VirtualFree` or `VirtualFreeEx`. + +## Remarks + +`VirtualFree` and `VirtualFreeEx` both reject a `dwFreeType` parameter of zero. The `dwFreeType` parameter can be either `MEM_DECOMMIT` or `MEM_RELEASE`. However, the values `MEM_DECOMMIT` and `MEM_RELEASE` may not be used together in the same call. Also, make sure that the return value of the `VirtualFree` function isn't ignored. + +Code analysis name: `VirtualFreeInvalidParam2` ## Example -The following code generates this warning because an invalid parameter is passed to the VirtualFree function: +The following code generates warning C6332 because an invalid parameter is passed to the `VirtualFree` function: ```cpp #include @@ -53,7 +58,7 @@ VOID f( VOID ) } ``` -To correct this warning, modify the call to the VirtualFree function as shown in the following code: +To correct this warning, modify the call to the `VirtualFree` function, as shown in the following code: ```cpp #include @@ -91,9 +96,9 @@ VOID f( VOID ) } ``` -The use of VirtualAlloc and VirtualFree have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `VirtualAlloc` and `VirtualFree` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [VirtualAlloc Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method) -- [VirtualFree Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) +[`VirtualAlloc` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method)\ +[`VirtualFree` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) diff --git a/docs/code-quality/c6333.md b/docs/code-quality/c6333.md index f54993c55d..3f917962ed 100644 --- a/docs/code-quality/c6333.md +++ b/docs/code-quality/c6333.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6333" -title: C6333 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6333"] +description: "Learn more about: Warning C6333" +title: Warning C6333 +ms.date: 08/25/2022 +f1_keywords: ["C6333", "VIRTUALFREEINVALIDPARAM3", "__WARNING_VIRTUALFREEINVALIDPARAM3"] helpviewer_keywords: ["C6333"] ms.assetid: 4b8fa4b2-a3a0-4d00-bec7-76686b66fcf9 --- -# C6333 +# Warning C6333 -> warning C6333: Invalid parameter: passing MEM_RELEASE and a non-zero dwSize parameter to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing MEM_RELEASE and a non-zero dwSize parameter to '*function_name*' is not allowed. This results in the failure of this call -This warning indicates an invalid parameter is being passed to VirtualFree or VirtualFreeEx. Both of these functions reject a dwFreeType of MEM_RELEASE with a non-zero value of dwSize. When passing MEM_RELEASE, the dwSize parameter must be zero. Also, make sure that the return value of this function is not ignored. +## Remarks + +Both `VirtualFree` and `VirtualFreeEx` reject a `dwFreeType` of `MEM_RELEASE` with a non-zero value of `dwSize`. When `MEM_RELEASE` is passed, the `dwSize` parameter must be zero. + +Code analysis name: `VIRTUALFREEINVALIDPARAM3` ## Example -The following sample code generates this warning: +The following code sample generates this warning: ```cpp #include @@ -24,36 +27,36 @@ The following sample code generates this warning: DWORD dwPages = 0; // count of pages DWORD dwPageSize; // page size -VOID f( VOID ) +VOID f(VOID) { - LPVOID lpvBase; // base address of the test memory - BOOL bSuccess; - SYSTEM_INFO sSysInfo; // system information - - GetSystemInfo( &sSysInfo ); - dwPageSize = sSysInfo.dwPageSize; - - // Reserve pages in the process's virtual address space - lpvBase = VirtualAlloc( - NULL, // system selects address - PAGELIMIT*dwPageSize,// size of allocation - MEM_RESERVE, - PAGE_NOACCESS ); - if (lpvBase) - { - // code to access memory - } - else - { - return; - } - - bSuccess = VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_RELEASE); - //code... + LPVOID lpvBase; // base address of the test memory + BOOL bSuccess; + SYSTEM_INFO sSysInfo; // system information + + GetSystemInfo(&sSysInfo); + dwPageSize = sSysInfo.dwPageSize; + + // Reserve pages in the process's virtual address space + lpvBase = VirtualAlloc( + NULL, // system selects address + PAGELIMIT*dwPageSize,// size of allocation + MEM_RESERVE, + PAGE_NOACCESS); + if (lpvBase) + { + // code to access memory + } + else + { + return; + } + + bSuccess = VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_RELEASE); + //code... } ``` -To correct this warning, use the following sample code: +To correct this warning, ensure that the value of `dwSize` is 0 in the call to `VirtualFree`: ```cpp #include @@ -62,37 +65,37 @@ To correct this warning, use the following sample code: DWORD dwPages = 0; // count of pages DWORD dwPageSize; // page size -VOID f( VOID ) +VOID f(VOID) { - LPVOID lpvBase; // base address of the test memory - BOOL bSuccess; - SYSTEM_INFO sSysInfo; // system information - - GetSystemInfo( &sSysInfo ); - dwPageSize = sSysInfo.dwPageSize; - - // Reserve pages in the process's virtual address space - lpvBase = VirtualAlloc( - NULL, // system selects address - PAGELIMIT*dwPageSize,// size of allocation - MEM_RESERVE, - PAGE_NOACCESS ); - if (lpvBase) - { - // code to access memory - } - else - { - return; - } - bSuccess = VirtualFree(lpvBase, 0, MEM_RELEASE ); - - // VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); - // code... + LPVOID lpvBase; // base address of the test memory + BOOL bSuccess; + SYSTEM_INFO sSysInfo; // system information + + GetSystemInfo(&sSysInfo); + dwPageSize = sSysInfo.dwPageSize; + + // Reserve pages in the process's virtual address space + lpvBase = VirtualAlloc( + NULL, // system selects address + PAGELIMIT*dwPageSize, // size of allocation + MEM_RESERVE, + PAGE_NOACCESS); + if (lpvBase) + { + // code to access memory + } + else + { + return; + } + bSuccess = VirtualFree(lpvBase, 0, MEM_RELEASE); + + // VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); + // code... } ``` -You can also use VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); call to decommit pages, and later release them using MEM_RELEASE flag. +You can also use `VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT);` call to decommit pages, and later release them using `MEM_RELEASE` flag. ## See also diff --git a/docs/code-quality/c6334.md b/docs/code-quality/c6334.md index 90b45505f5..5499f3ab13 100644 --- a/docs/code-quality/c6334.md +++ b/docs/code-quality/c6334.md @@ -1,54 +1,44 @@ --- -description: "Learn more about: C6334" -title: C6334 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6334"] +description: "Learn more about: Warning C6334" +title: Warning C6334 +ms.date: 08/25/2022 +f1_keywords: ["C6334", "SIZEOFEXPR", "__WARNING_SIZEOFEXPR"] helpviewer_keywords: ["C6334"] ms.assetid: 83c8abfb-b11e-4573-8c6f-95b205d32137 --- -# C6334 +# Warning C6334 -> warning C6334: sizeof operator applied to an expression with an operator may yield unexpected results +> `sizeof` operator applied to an expression with an operator may yield unexpected results -This warning indicates a misuse of the **`sizeof`** operator. The **`sizeof`** operator, when applied to an expression, yields the size of the type of the resulting expression. +## Remarks -For example, in the following code: +The `sizeof` operator, when applied to an expression, yields the size of the type of the resulting expression. -```cpp -char a[10]; -size_t x; - -x = sizeof (a - 1); -``` - - `x` will be assigned the value 4, not 9, because the resulting expression is no longer a pointer to the array `a`, but simply a pointer. +Code analysis name: `SIZEOFEXPR` ## Example -The following code generates this warning: +The following code generates this warning. Since `a - 4` is an expression, `sizeof` will return the size of the resulting pointer, not the size of the structure found at that pointer: ```cpp void f( ) { - size_t x; - char a[10]; - - x= sizeof (a - 4); - // code... + size_t x; + char a[100]; + x = sizeof(a - 4); + assert(x == 96); //assert fails since x == sizeof(char*) } ``` -To correct this warning, use the following code: +To correct this warning, ensure that you're working with the return value of `sizeof`, not the argument to it: ```cpp void f( ) { - size_t x; - char a[10]; - - x= sizeof (a) - 4; - // code... + size_t x; + char a[100]; + x = sizeof(a) - 4; + assert(x == 96); //assert succeeds } ``` diff --git a/docs/code-quality/c6335.md b/docs/code-quality/c6335.md index 41e51ad74e..a5f62fe5fe 100644 --- a/docs/code-quality/c6335.md +++ b/docs/code-quality/c6335.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6335" -title: C6335 +title: Warning C6335 +description: "Learn more about: Warning C6335" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6335"] +f1_keywords: ["C6335", "LEAKING_PROCESS_HANDLE", "__WARNING_LEAKING_PROCESS_HANDLE"] helpviewer_keywords: ["C6335"] -ms.assetid: f81c0859-3d82-4182-8bf1-6c3b76c7486f --- -# C6335 +# Warning C6335 -> warning C6335: leaking process information handle \ +> Leaking process information handle '*handlename*' + +## Remarks This warning indicates that the process information handles returned by the CreateProcess family of functions need to be closed using CloseHandle. Failure to do so will cause handle leaks. +Code analysis name: `LEAKING_PROCESS_HANDLE` + ## Example The following code generates this warning: @@ -51,7 +53,7 @@ void f( ) } ``` -To correct this warning, call `CloseHandle (pi.``hThread)` to close thread handle as shown in the following code: +To correct this warning, call `CloseHandle( pi.hThread )` to close thread handle as shown in the following code: ```cpp #include diff --git a/docs/code-quality/c6336.md b/docs/code-quality/c6336.md index 0bd0047fa1..a2264c13e8 100644 --- a/docs/code-quality/c6336.md +++ b/docs/code-quality/c6336.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6336" -title: C6336 +description: "Learn more about: Warning C6336" +title: Warning C6336 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6336"] +f1_keywords: ["C6336", "QUESTIONPRECEDENCE", "__WARNING_QUESTIONPRECEDENCE"] helpviewer_keywords: ["C6336"] ms.assetid: cf402433-9940-4466-ac15-f94288f51f74 --- -# C6336 +# Warning C6336 -> warning C6336: arithmetic operator has precedence over question operator, use parentheses to clarify intent +> Arithmetic operator has precedence over question operator, use parentheses to clarify intent -This warning indicates a possible operator precedence problem. The '+','-','*' and '/' operators have precedence over the '?' operator. If the precedence in the expression is not correct, use parentheses to change the operator precedence. +## Remarks + +This warning indicates a possible operator precedence problem. The '`+`','`-`','`*`' and '`/`' operators have precedence over the '`?`' operator. If the precedence in the expression isn't correct, use parentheses to change the operator precedence. + +Code analysis name: `QUESTIONPRECEDENCE` ## Example diff --git a/docs/code-quality/c6340.md b/docs/code-quality/c6340.md index e1d6c988ff..baf564d026 100644 --- a/docs/code-quality/c6340.md +++ b/docs/code-quality/c6340.md @@ -1,12 +1,67 @@ --- -description: "Learn more about: C6340" -title: C6340 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6340"] +description: "Learn more about: Warning C6340" +title: Warning C6340 +ms.date: 02/14/2024 +f1_keywords: ["C6340", "FORMAT_SIGN_MISMATCH"] helpviewer_keywords: ["C6340"] ms.assetid: c4fe474f-5a27-4148-ba35-1ef021371e13 --- -# C6340 +# Warning C6340 + +> Mismatch on sign: '*type*' passed as _Param_(*number*) when some (signed|unsigned) type is required in call to '*function-name*' + +## Remarks + +This warning indicates that sign of the type required by the format specifier and sign of the type of the expression passed in don't match. +Using the wrong format specifier is undefined behavior. To fix the warning, make sure that the format specifiers match the types of the expressions passed in. + +Code analysis name: `FORMAT_SIGN_MISMATCH` + +## Example + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhd\n", a); // C6340 emitted. +} +``` +There are multiple ways to fix the undefined behavior. We can change the format specifier: + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhu\n", a); // No C6340 emitted. +} +``` + +We can change the type of the expression: + +```cpp +#include + +void f(signed char a) +{ + printf("%hhd\n", a); // No C6340 emitted. +} +``` + +As a last resort when overflow can't happen, we can introduce a cast: + +```cpp +#include + +void f(long long a) +{ + printf("%d\n", static_cast(a)); // No C6328 emitted. +} +``` + +## See also + +[C6328](c6328.md) + -> warning C6340: Mismatch on sign: Incorrect type passed as parameter in call to function diff --git a/docs/code-quality/c6381.md b/docs/code-quality/c6381.md index 41058a91dd..1a753fdbde 100644 --- a/docs/code-quality/c6381.md +++ b/docs/code-quality/c6381.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: C6381" -title: C6381 +description: "Learn more about: Warning C6381" +title: Warning C6381 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6381"] +f1_keywords: ["C6381", "SHUTDOWN_API", "__WARNING_SHUTDOWN_API"] helpviewer_keywords: ["C6381"] ms.assetid: c01a3040-26d4-47ac-b72d-7e1292ca435f --- -# C6381 +# Warning C6381 -> warning C6381: Shutdown API \ requires a valid dwReason or lpMessage +> Shutdown API '*function*' requires a valid dwReason or lpMessage -This warning is issued if InitiateSystemShutdownEx is called: +## Remarks -- Without passing a valid shutdown reason (dwReason). If dwReason parameter is zero, the default is an undefined shutdown. By default, it is also an unplanned shutdown. You should use one of the System Shutdown Reason Codes for this parameter. +This warning is issued if `InitiateSystemShutdownEx` is called: -- Without passing a shutdown message (lpMessage). +- Without passing a valid shutdown reason (`dwReason`). If `dwReason` parameter is zero, the default is an undefined shutdown. By default, it's also an unplanned shutdown. You should use one of the System Shutdown Reason Codes for this parameter. + +- Without passing a shutdown message (`lpMessage`). We recommend that you use appropriate parameters when calling this API to help system administrators determine the cause of the shutdown. +Code analysis name: `SHUTDOWN_API` + ## Example The following code generates this warning because dwReason is zero and lpMessage is null: diff --git a/docs/code-quality/c6383.md b/docs/code-quality/c6383.md index 14bd47580f..72d0ef8b4f 100644 --- a/docs/code-quality/c6383.md +++ b/docs/code-quality/c6383.md @@ -1,56 +1,43 @@ --- -description: "Learn more about: C6383" -title: C6383 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6383"] +title: Warning C6383 +description: "Learn more about: Warning C6383" +ms.date: 09/07/2022 +f1_keywords: ["C6383", "ELEMENTS_TO_BYTES", "__WARNING_ELEMENTS_TO_BYTES"] helpviewer_keywords: ["C6383"] -ms.assetid: f5ff7938-0fbe-4b71-b98f-098fe887799d --- -# C6383 +# Warning C6383 -> warning C6383: buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter \ in call to \ +> Buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter *`parameter_name`* in call to *`function_name`* -This warning indicates that a non-constant byte count is being passed when an element count is required. Typically, this occurs when a variable is multiplied by the **`sizeof`** a type, but code analysis suggests that an element count is required. +This warning indicates that a non-constant byte count is being passed when an element count is instead required. -## Example +## Remarks -The following code generates this warning: +Typically, this warning occurs when a variable is multiplied by the `sizeof` a type. This issue will likely result in more bytes being copied to the buffer than it can hold. -```cpp -#include +Code analysis name: `ELEMENTS_TO_BYTES` -void f( wchar_t* t, wchar_t* s, int n ) -{ - // code ... - wcsncpy (t, s, n*sizeof(wchar_t)); // warning C6383 - // code ... -} -``` +## Example -To correct this warning, do not multiply the variable with the **`sizeof`** a type as shown in the following code: +The following code generates this warning. `wcsncpy` will allow `n * sizeof(wchar_t)` characters to be copied, but the buffer can only hold `n` characters. It should be noted that `wcsncpy` is an unsafe function, and shouldn't be used per [C28719](/windows-hardware/drivers/devtest/28719-banned-api-usage-use-updated-function-replacement). The unsafe variant is used here only for the purposes of demonstrating this warning: ```cpp -void f( wchar_t* t, wchar_t* s, int n ) +void f(wchar_t* t, wchar_t* s, int n) { - // code ... - wcsncpy (t, s, n); - // code ... + wcsncpy (t, s, n*sizeof(wchar_t)); } ``` -The following code corrects this warning by using the safe string manipulation function: +The following code corrects this warning by sending element count instead of the byte count: ```cpp -void f(wchar_t* t, wchar_t* s, size_t n) +void f( wchar_t* t, wchar_t* s, int n ) { - // code ... - wcsncpy_s( t, sizeof(s), s, n ); - // code ... + wcsncpy (t, s, n); } ``` ## See also -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -- [sizeof Operator](../cpp/sizeof-operator.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`sizeof` Operator](../cpp/sizeof-operator.md) diff --git a/docs/code-quality/c6384.md b/docs/code-quality/c6384.md index c91bee577a..75067282fa 100644 --- a/docs/code-quality/c6384.md +++ b/docs/code-quality/c6384.md @@ -1,23 +1,26 @@ --- -description: "Learn more about: C6384" -title: C6384 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6384"] +description: "Learn more about: Warning C6384" +title: Warning C6384 +ms.date: 10/03/2022 +f1_keywords: ["C6384", "DIVIDING_SIZEOF_POINTER", "__WARNING_DIVIDING_SIZEOF_POINTER"] helpviewer_keywords: ["C6384"] ms.assetid: 9c605b61-1485-49a8-847b-41170193dbf4 --- -# C6384 +# Warning C6384 -> warning C6384: dividing sizeof a pointer by another value +> Dividing sizeof a pointer by another value -This warning indicates that a size calculation might be incorrect. To calculate the number of elements in an array, one sometimes divides the size of the array by the size of the first element; however, when the array is actually a pointer, the result is typically different than intended. +This warning indicates that a size calculation might be incorrect. To calculate the number of elements in an array, you sometimes divide the size of the array by the size of the first element. However, when the array is actually a pointer, the result is typically different than intended. -If the pointer is a function parameter and the size of the buffer was not passed, it is not possible to calculate the maximum buffer available. When the pointer is allocated locally, the size used in the allocation should be used. +## Remarks + +If the pointer is a function parameter and the size of the buffer wasn't passed, it isn't possible to calculate the maximum buffer available. When the pointer is allocated locally, the size used in the allocation should be used. + +Code analysis name: `DIVIDING_SIZEOF_POINTER` ## Example -The following code generates this warning: +The following code generates warning C6384: ```cpp #include @@ -55,7 +58,7 @@ void f( ) } ``` -To correct this warning using the safe string function _tcsncpy_s, use the following code: +To correct this warning using the safe string function `_tcsncpy_s`, use the following code: ```cpp void f( ) @@ -69,9 +72,9 @@ void f( ) } ``` -Note that the use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [_mbsnbcpy_s, _mbsnbcpy_s_l](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md) -- [sizeof Operator](../cpp/sizeof-operator.md) +[`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md)\ +[`sizeof` Operator](../cpp/sizeof-operator.md) diff --git a/docs/code-quality/c6385.md b/docs/code-quality/c6385.md index 786ed5289d..ef43fb923b 100644 --- a/docs/code-quality/c6385.md +++ b/docs/code-quality/c6385.md @@ -1,18 +1,21 @@ --- -title: C6385 +title: Warning C6385 description: "Describes C++ Code Analysis warning C6385 and how to resolve it." ms.date: 03/16/2020 -ms.topic: reference -f1_keywords: ["C6385"] +f1_keywords: ["C6385", "READ_OVERRUN", "__WARNING_READ_OVERRUN"] helpviewer_keywords: ["C6385"] ms.assetid: 3e4961e7-0f09-42a8-8cc2-151109dfdbda --- -# C6385 +# Warning C6385 -> warning C6385: invalid data: accessing *buffer-name*, the readable size is *size1* bytes, but *size2* bytes may be read: Lines: *x*, *y* +> Invalid data: accessing *buffer-name*, the readable size is *size1* bytes, but *size2* bytes may be read: Lines: *x*, *y* + +## Remarks The readable extent of the buffer might be smaller than the index used to read from it. Attempts to read data outside the valid range leads to buffer overrun. +Code analysis name: `READ_OVERRUN` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6386.md b/docs/code-quality/c6386.md index 5121e5b1c4..7aa56f9f9f 100644 --- a/docs/code-quality/c6386.md +++ b/docs/code-quality/c6386.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6386" -title: C6386 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6386"] +description: "Learn more about: Warning C6386" +title: Warning C6386 +ms.date: 4/30/2025 +f1_keywords: ["C6386", "WRITE_OVERRUN", "__WARNING_WRITE_OVERRUN"] helpviewer_keywords: ["C6386"] -ms.assetid: 84e69fe8-8f03-4bb3-b194-e5551882e214 --- -# C6386 +# Warning C6386 -> warning C6386: buffer overrun: accessing \, the writable size is \ bytes, but \ bytes may be written: Lines: x, y +> Buffer overrun: accessing '*buffer name*', the writable size is '*size1*' bytes, but '*size2*' bytes may be written: Lines: x, y -This warning indicates that the writable extent of the specified buffer might be smaller than the index used to write to it. This can cause buffer overrun. +## Remarks + +This warning indicates that the writable extent of the specified buffer might be smaller than the index used to write to it. This defect can cause buffer overrun. + +Code analysis name: `WRITE_OVERRUN` ## Example @@ -20,15 +22,14 @@ The following code generates both this warning and [C6201](../code-quality/c6201 ```cpp #define MAX 25 -void f ( ) +void f() { - char ar[MAX]; - // code ... - ar[MAX] = '\0'; + char a[MAX]; + a[MAX] = '\0'; // this writes one element past the end of the buffer } ``` -To correct both warnings, use the following code: +To correct the warning, use the following code which accounts for the fact that array indexes are zero-based. Thus `MAX - 1` is the last element in the buffer: ```cpp #define MAX 25 @@ -36,8 +37,7 @@ To correct both warnings, use the following code: void f ( ) { char a[MAX]; - // code ... - a[MAX - 1] = '\0'; + a[MAX-1] = '\0'; } ``` diff --git a/docs/code-quality/c6387.md b/docs/code-quality/c6387.md index 5721b46c5e..a925d0b397 100644 --- a/docs/code-quality/c6387.md +++ b/docs/code-quality/c6387.md @@ -1,31 +1,32 @@ --- -description: "Learn more about: C6387" -title: C6387 +title: Warning C6387 +description: "Learn more about: Warning C6387" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6387"] +f1_keywords: ["C6387", "INVALID_PARAM_VALUE_1", "__WARNING_INVALID_PARAM_VALUE_1"] helpviewer_keywords: ["C6387"] -ms.assetid: 3ea2fc4d-ffc3-4c3c-bfae-d42aa56235d8 --- -# C6387 +# Warning C6387 -> warning C6387: \ may be \: this does not adhere to the specification for the function \: Lines: x, y +> '*argument*' may be '*value*': this does not adhere to the specification for the function '*function name*': Lines: x, y + +## Remarks This warning is raised if an annotated function parameter is being passed an unexpected value. For example, passing a potentially null value to a parameter that is marked with `_In_` annotation generates this warning. +Code analysis name: `INVALID_PARAM_VALUE_1` + ## Example The following code generates this warning because a null parameter is passed to `f(char *)`: ```cpp - #include _Post_ _Null_ char * g(); void f(_In_ char *pch); -void main() +int main() { char *pCh = g(); f(pCh); // Warning C6387 @@ -35,14 +36,13 @@ void main() To correct this warning, use the following code: ```cpp - #include _Post_ _Notnull_ char * g(); void f(_In_ char *pch); -void main() +int main() { char *pCh = g(); f(pCh); diff --git a/docs/code-quality/c6388.md b/docs/code-quality/c6388.md index 2a188f19a5..540db622f9 100644 --- a/docs/code-quality/c6388.md +++ b/docs/code-quality/c6388.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: C6388" -title: C6388 +description: "Learn more about: Warning C6388" +title: Warning C6388 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6388"] +f1_keywords: ["C6388", "INVALID_PARAM_VALUE_2", "__WARNING_INVALID_PARAM_VALUE_2"] helpviewer_keywords: ["C6388"] ms.assetid: 667fe9cf-cc53-49f9-b6c0-6ee87c397568 --- -# C6388 +# Warning C6388 -> warning C6388: \ may not be \: this does not adhere to the specification for the function \: Lines: x, y +> '*argument*' may not be '*value*': this does not adhere to the specification for the function '*function-name*': Lines: x, y -This warning indicates that an unexpected value is being used in the specified context. This is typically reported for values passed as arguments to a function that does not expect it. +## Remarks + +This warning indicates that an unexpected value is being used in the specified context. This warning is typically reported for values passed as arguments to a function that doesn't expect it. + +Code analysis name: `INVALID_PARAM_VALUE_2` ## Example -The following C++ code generates this warning because DoSomething expects a null value but a potentially non-null value might be passed: +The following code generates warning C6388 because `DoSomething` expects a null value but a potentially non-null value might be passed: ```cpp - +// C6388_warning.cpp #include #include #include @@ -37,7 +40,7 @@ void f() To correct this warning, use the following sample code: ```cpp - +// C6388_no_warning.cpp #include #include #include @@ -58,4 +61,4 @@ void f() } ``` -Note that the use of malloc and free have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6389.md b/docs/code-quality/c6389.md index 7240a06e78..5838f22f32 100644 --- a/docs/code-quality/c6389.md +++ b/docs/code-quality/c6389.md @@ -1,12 +1,15 @@ --- -title: C6389 +title: Warning C6389 description: "Describes the Microsoft C/C++ code analysis warning C6389, its causes, and how to address it." ms.date: 06/09/2021 -f1_keywords: ["C6389"] +f1_keywords: ["C6389", "MARK_INTERNAL_OR_MISSING_COMMON_DECL"] helpviewer_keywords: ["C6389"] --- +# Warning C6389 -# C6389: MARK_INTERNAL_OR_MISSING_COMMON_DECL +> Move '*declaration*' to anonymous namespace or put a forward declaration in a common header included in this file. + +## Remarks This check is intended to help reduce the visibility of certain symbols and to modularize the code. In multi-file C++ projects, each declaration should be either local to a C++ file (part of the anonymous namespace) or declared in a common header file that's included by multiple C++ files. @@ -14,14 +17,14 @@ When this check flags a declaration, either it should be moved to an anonymous n The rule is an experimental rule that must be explicitly enabled in a rule set file to work. For more information about rule sets, see [Use rule sets to group code analysis rules](/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules). +Code analysis name: `MARK_INTERNAL_OR_MISSING_COMMON_DECL` + ## Example ```cpp // A.h struct X; -``` -```cpp // A.cpp #include "A.h" @@ -39,9 +42,7 @@ One way to resolve these issues is to move `struct Y` into an anonymous namespac // A.h struct X; void f(); -``` -```cpp // A.cpp #include "A.h" diff --git a/docs/code-quality/c6390.md b/docs/code-quality/c6390.md new file mode 100644 index 0000000000..f5895dc43f --- /dev/null +++ b/docs/code-quality/c6390.md @@ -0,0 +1,31 @@ +--- +title: Warning C6390 +description: "Describes the Microsoft C/C++ code analysis warning C6390, its causes, and how to address it." +ms.date: 06/17/2022 +f1_keywords: ["C6390", "NO_NULLCHECK_FOR_THIS"] +helpviewer_keywords: ["C6390"] +--- +# Warning C6390 + +> According to the C++ standard, the value of 'this' is never null; some compilers will optimize this check out + +## Remarks + +While MSVC doesn't do such optimizations, some compilers optimize null checks for `this` out. Code that relies on null-valued `this` can trigger unexpected behavior when compiled with other compilers. This warning helps detect these portability problems. + +Code analysis name: `NO_NULLCHECK_FOR_THIS` + +## Example + +```cpp +struct X +{ + void m() + { + if(!this) // Warning: According to the C++ standard, the value of 'this' is never null; some compilers will optimize this check out + return; + } +}; +``` + +To solve this problem, rewrite the code to never call non-static member functions on null pointers. diff --git a/docs/code-quality/c6392.md b/docs/code-quality/c6392.md new file mode 100644 index 0000000000..b8dc3b2ff4 --- /dev/null +++ b/docs/code-quality/c6392.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about: Warning C6392" +title: Warning C6392 +ms.date: 03/06/2024 +f1_keywords: ["C6392", "STREAM_OUTPUT_VOID_PTR", "__STREAM_OUTPUT_VOID_PTR"] +helpviewer_keywords: ["C6392"] +--- +# Warning C6392 + +> This expression writes the value of the pointer to the stream. If this is intentional, add an explicit cast to 'void *' + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +C++ supports wide character streams such as `std::wostringstream`, and nonwide character streams such as `std::ostringstream`. Trying to print a wide string to a nonwide stream calls the `void*` overload of `operator<<`. This overload prints the address of the wide string instead of the value. + +Code analysis name: `STREAM_OUTPUT_VOID_PTR` + +## Example + +The following code snippet prints the value of the pointer to the standard output instead of the string `"Pear"`: + +```cpp +#include + +int main() { + std::cout << L"Pear\n"; // Warning: C6392 +} +``` + +There are multiple ways to fix this error. If printing the pointer value is unintended, use a nonwide string: + +```cpp +#include + +int main() { + std::cout << "Pear\n"; // No warning. +} +``` + +Alternatively, use a wide stream: + +```cpp +#include + +int main() { + std::wcout << L"Pear\n"; // No warning. +} +``` + +If the behavior is intentional, make the intention explicit and silence the warning by using an explicit cast: + +```cpp +#include + +int main() { + std::cout << static_cast(L"Pear\n"); // No warning. +} +``` diff --git a/docs/code-quality/c6393.md b/docs/code-quality/c6393.md new file mode 100644 index 0000000000..a905c012a2 --- /dev/null +++ b/docs/code-quality/c6393.md @@ -0,0 +1,61 @@ +--- +title: Warning C6393 +description: "Learn more about: Warning C6393" +ms.date: 11/29/2023 +f1_keywords: ["C6393", "LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP", "__WARNING_LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP"] +helpviewer_keywords: ["C6393"] +--- +# Warning C6393 + +> A lookup table of size 365 isn't sufficient to handle leap years + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +In the Gregorian calendar, every year exactly divisible by four is a leap year--except for years that are exactly divisible by 100. The centurial years are also leap years if they're exactly divisible by 400. + +A leap year bug occurs when software doesn't account for this leap year logic, or uses flawed logic. The can affect reliability, availability, or even the security of the affected system. + +Lookup tables of size 365 are often used to quickly find the month a given day corresponds to. However, it isn't correct because a leap year has 366 days. + +Code analysis name: `LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP` + +## Example + +The following code creates a lookup table for the day of the year, assuming 365 days per year. However, this doesn't work if the year is a leap year: + +```cpp +#include + +void foo(int year) +{ + const std::vector items(365); // C6393 + // Initialize items and use it... +} +``` + +To fix the problem, adjust the size of the lookup table as the table is created according to the result of appropriate leap year check: + +```cpp +#include + +void foo(int year) +{ + bool isLeapYear = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0); + const std::vector items(isLeapYear ? 366 : 365); + // Initialize items and use it... +} +``` + +## Heuristics + +This rule is enforced by checking if a constant lookup table is sized for 365 elements. Violation of this rule causes a high confidence warning to be reported. + +## See also + +[C6394](c6394.md)\ +[C26861](c26861.md)\ +[C26862](c26862.md)\ +[C26863](c26863.md)\ +[C26864](c26864.md) diff --git a/docs/code-quality/c6394.md b/docs/code-quality/c6394.md new file mode 100644 index 0000000000..d4a4fe6668 --- /dev/null +++ b/docs/code-quality/c6394.md @@ -0,0 +1,63 @@ +--- +title: Warning C6394 +description: "Learn more about: Warning C6394" +ms.date: 11/29/2023 +f1_keywords: ["C6394", "LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP_MUTABLE", "__WARNING_LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP_MUTABLE"] +helpviewer_keywords: ["C6394"] +--- +# Warning C6394 + +> A lookup table of size 365 isn't sufficient to handle leap years + +This rule was added in Visual Studio 2022 17.8. + +## Remarks + +In the Gregorian calendar, every year exactly divisible by four is a leap year--except for years that are exactly divisible by 100. The centurial years are also leap years if they're exactly divisible by 400. + +A leap year bug occurs when software doesn't account for this leap year logic, or uses flawed logic. The can affect reliability, availability, or even the security of the affected system. + +Lookup tables of size 365 are often used to quickly find the month a given day corresponds to, and so on. However, it isn't correct because a leap year has 366 days. + +Code analysis name: `LEAP_YEAR_INVALID_DATE_KEYED_LOOKUP_MUTABLE` + +## Example + +The following code creates a lookup table for the day of the year, but assumes there are 365 days per year. However, this produces the wrong result, or can cause an out-of-bounds access of the lookup table, if the year is a leap year: + +```cpp +#include + +void foo(int year) +{ + std::vector items(365); // C6394 + // Initialize items and use it... + // Another item may be added to the vector if year is a leap year, but this + // rule doesn't check if that is the case. +} +``` + +To fix this problem, adjust the size of the lookup table as the table is created according to the result of a leap year check: + +```cpp +#include + +void foo(int year) +{ + bool isLeapYear = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0); + const std::vector items(isLeapYear ? 366 : 365); + // Initialize items and use it... +} +``` + +## Heuristics + +This rule is enforced by checking if a lookup table has an initial size of 365 elements, but can be expanded to 366. However, it doesn't check if the table's size is adjusted through proper leap year check or not, and so is a low confidence warning. + +## See also + +[C6393](c6393.md)\ +[C26861](c26861.md)\ +[C26862](c26862.md)\ +[C26863](c26863.md)\ +[C26864](c26864.md) diff --git a/docs/code-quality/c6395.md b/docs/code-quality/c6395.md new file mode 100644 index 0000000000..fba3e04720 --- /dev/null +++ b/docs/code-quality/c6395.md @@ -0,0 +1,35 @@ +--- +title: Warning C6395 +description: "Describes the Microsoft C/C++ code analysis warning C6395, its causes, and how to address it." +ms.date: 10/12/2023 +f1_keywords: ["C6395", "EVAL_ORDER_CHANGE"] +helpviewer_keywords: ["C6395"] +--- +# Warning C6395 + +> %variable% has unsequenced reads and/or writes before C++17; changing the language standard might change the behavior of the code. + +## Remarks + +C++17 made the evaluation order of certain expressions stricter. MSVC complied, which changed the evaluation order for some expressions. Thus, changing the language version might change the observable behavior of the program. This check diagnoses some of the cases where the meaning of the code changes due to switching language versions. + +Code analysis name: `EVAL_ORDER_CHANGE` + +## Example + +```cpp +void foo(int* a, int i) +{ + a[++i] = i; // Warning: 'i' has unsequenced reads and/or writes before C++17; changing the language standard might change the behavior of the code +} +``` + +To solve this problem, separate the side effects from the rest of the expression to make the evaluation order well defined: + +```cpp +void foo(int* a, int i) +{ + ++i; + a[i] = i; // No warning. +} +``` diff --git a/docs/code-quality/c6396.md b/docs/code-quality/c6396.md new file mode 100644 index 0000000000..6bd3b0952b --- /dev/null +++ b/docs/code-quality/c6396.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: Warning C6396: sizeof('integerConstant') always returns the size of the underlying integer type" +title: Warning C6396 +ms.date: 02/05/2024 +f1_keywords: ["C6396", "SIZEOF_CONSTANT"] +helpviewer_keywords: ["C6396"] +--- +# Warning C6396 + +> sizeof('integerConstant') always returns the size of the underlying integer type + +## Remarks + +This warning indicates where an integral constant is used as a `sizeof` argument. Such expression always returns the size of the type of the constant. It's better to write `sizeof(type)` instead. This warning catches common typos in buffer offset calculations. + +This check ignores character literals because `buffer_size += sizeof(UNICODE_NULL)` is a common idiom. + +## Example + +```cpp +void f() +{ + int a = sizeof(5); // C6396 reported here +} +``` + +To fix this issue, replace the integral constant with its type: + +```cpp +void f() +{ + int a = sizeof(int); // no C6396 reported here +} +``` \ No newline at end of file diff --git a/docs/code-quality/c6397.md b/docs/code-quality/c6397.md new file mode 100644 index 0000000000..4247b43161 --- /dev/null +++ b/docs/code-quality/c6397.md @@ -0,0 +1,38 @@ +--- +description: "Learn more about: Warning C6397: The address-of operator cannot return null pointer in well-defined code" +title: Warning C6397 +ms.date: 02/05/2024 +f1_keywords: ["C6397", "DUBIOUS_NULL_CHECK"] +helpviewer_keywords: ["C6397"] +--- +# Warning C6397 + +> The address-of operator cannot return `null` pointer in well-defined code + +## Remarks + +The address-of operator returns the address of its operand. This value should never be compared to `nullptr`: +* The address-of a field can only be `nullptr` if the base pointer was `nullptr` and the field is at the zero offset (`&p->field == nullptr` implies `p == nullptr`). In this case, the expression should be simplified. +* In any other cases, the value of the unary `&` operator can't be `nullptr` unless there's undefined behavior in the code (`&v == nullptr` always evaluates to false). + +## Example + +```cpp +bool isNull(int *a) +{ + return &a == nullptr; // C6397 reported here. +} +``` + +To fix this issue, double check if the use of unary `&` was intentional: + +```cpp +bool isNull(int *a) +{ + return a == nullptr; // no C6397 reported here. +} +``` + +## See also + +[C6398](c6398.md) \ No newline at end of file diff --git a/docs/code-quality/c6398.md b/docs/code-quality/c6398.md new file mode 100644 index 0000000000..5ee996202d --- /dev/null +++ b/docs/code-quality/c6398.md @@ -0,0 +1,42 @@ +--- +description: "Learn more about: Warning C6398: The address-of a field cannot be null in well-defined code" +title: Warning C6398 +ms.date: 02/05/2024 +f1_keywords: ["C6398", "DUBIOUS_NULL_CHECK_FIELD"] +helpviewer_keywords: ["C6398"] +--- +# Warning C6398 + +> The address-of a field cannot be `null` in well-defined code + +## Remarks + +The address-of operator returns the address of its operand. This value should never be compared to `nullptr`: +* The address-of a field can only be `nullptr` if the base pointer was `nullptr` and the field is at the zero offset (`&p->field == nullptr` implies `p == nullptr`). In this case, the expression should be simplified. +* In any other cases, the value of the unary `&` operator can't be `nullptr` unless there's undefined behavior in the code (`&v == nullptr` always evaluates to false). + +## Example + +```cpp +struct A { int* x; }; + +bool hasNullField(A *a) +{ + return &a->x == nullptr; // C6398 reported here. +} +``` + +To fix this issue, double check if the use of unary `&` was intentional: + +```cpp +struct A { int* x; }; + +bool hasNullField(A *a) +{ + return a->x == nullptr; // no C6398 reported here. +} +``` + +## See also + +[C6397](c6397.md) \ No newline at end of file diff --git a/docs/code-quality/c6400.md b/docs/code-quality/c6400.md index 4a3729c987..2d2d4ac559 100644 --- a/docs/code-quality/c6400.md +++ b/docs/code-quality/c6400.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: C6400" -title: C6400 +description: "Learn more about: Warning C6400" +title: Warning C6400 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6400"] +f1_keywords: ["C6400", "LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON", "__WARNING_LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON"] helpviewer_keywords: ["C6400"] ms.assetid: 35808969-1d43-41e8-bcda-33635637fb26 --- -# C6400 +# Warning C6400 -> warning C6400: Using \ to perform a case-insensitive compare to constant string \. Yields unexpected results in non-English locales +> Using '*function name*' to perform a case-insensitive compare to constant string '*string name*'. Yields unexpected results in non-English locales -This warning indicates that a case-insensitive comparison to a constant string is being performed in a locale-dependent way, when, apparently, a locale-independent comparison was intended. +## Remarks -The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" will not match ".GIF"; in Vietnamese, "LogIn" will not match "LOGIN". +This warning indicates that a case-insensitive comparison to a constant string is being done in a locale-dependent way. It appears that a locale-independent comparison was intended. + +The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" won't match ".GIF"; in Vietnamese, "LookUp" won't match "LOOKUP". String comparisons should typically be performed with the `CompareString` function. To perform a locale-independent comparison on Windows XP, the first parameter should be the constant `LOCALE_INVARIANT`. +Code analysis name: `LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6401.md b/docs/code-quality/c6401.md index 521a57d2c1..954dbdddef 100644 --- a/docs/code-quality/c6401.md +++ b/docs/code-quality/c6401.md @@ -1,19 +1,20 @@ --- -description: "Learn more about: C6401" -title: C6401 +description: "Learn more about: Warning C6401" +title: Warning C6401 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6401"] +f1_keywords: ["C6401", "DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON", "__WARNING_DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON"] helpviewer_keywords: ["C6401"] ms.assetid: d57b1c94-57a3-4d4b-a7de-8b9ffbac3ebe --- -# C6401 +# Warning C6401 -> warning C6401: Using \ in a default locale to perform a case-insensitive compare to constant string \< string name>. Yields unexpected results in non-English locales +> Using '*function name*' in a default locale to perform a case-insensitive compare to constant string '*string name*'. Yields unexpected results in non-English locales -This warning indicates that a case-insensitive comparison to a constant string is being performed when specifying the default locale; usually, a locale-independent comparison was intended. +## Remarks -The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" will not match ".GIF"; in Vietnamese, "LogIn" will not match "LOGIN". +This warning indicates that a case-insensitive comparison to a constant string is being done when specifying the default locale. Usually, a locale-independent comparison was intended. + +The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" won't match ".GIF"; in Vietnamese, "LookUp" won't match "LOOKUP". The `CompareString` function takes a locale as an argument; however, passing in a default locale, for example, the constant `LOCALE_USER_DEFAULT`, will cause different behaviors in different locales, depending on the user's default. Usually, case-insensitive comparisons against a constant string should be performed in a locale-independent comparison. @@ -28,6 +29,8 @@ CompareString(LOCALE_INVARIANT, -1) == CSTR_EQUAL ``` +Code analysis name: `DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6411.md b/docs/code-quality/c6411.md index e22a8d4df3..a4a99565a8 100644 --- a/docs/code-quality/c6411.md +++ b/docs/code-quality/c6411.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: C6411" -title: C6411 +title: Warning C6411 +description: "Learn more about: Warning C6411" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6411"] -ms.assetid: 6bbc1734-eec4-4ad6-9908-4ed2a5f025db +f1_keywords: ["C6411", "POTENTIAL_READ_OVERRUN"] +helpviewer_keywords: ["C6411"] --- -# C6411 +# Warning C6411 -> warning C6411: Potentially reading invalid data from the buffer. +> Potentially reading invalid data from '*buffer*'. -This warning indicates that the value of the index that is used to read from the buffer can exceed the readable size of the buffer. Because the code analysis tool reports this warning when it cannot reduce a complex expression that represents the buffer size, or the index used to access the buffer, this warning might be reported in error. +## Remarks + +This warning indicates that the value of the index that is used to read from the buffer can exceed the readable size of the buffer. The code analysis tool may report this warning in error. The error may occur when it can't reduce a complex expression that represents the buffer size, or the index used to access the buffer. + +Code analysis name: `POTENTIAL_READ_OVERRUN` ## Example diff --git a/docs/code-quality/c6412.md b/docs/code-quality/c6412.md index 0d8da85815..230011ec6e 100644 --- a/docs/code-quality/c6412.md +++ b/docs/code-quality/c6412.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6412" -title: C6412 +title: Warning C6412 +description: "Learn more about: Warning C6412" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6412"] -ms.assetid: 6498f045-1bdc-4428-9d95-d9498de207bb +f1_keywords: ["C6412", "POTENTIAL_WRITE_OVERRUN"] +helpviewer_keywords: ["C6412"] --- -# C6412 +# Warning C6412 -> warning C6412: Potential buffer overrun while writing to buffer. The writable size is *write_size* bytes, but *write_index* bytes may be written. +> Potential buffer overrun while writing to buffer. The writable size is *write_size* bytes, but *write_index* bytes may be written. -This warning indicates that the value of the index that is used to write to the buffer can exceed the writeable size of the buffer. +## Remarks -Because the code analysis tool reports this warning when it cannot reduce a complex expression that represents the buffer size, or the index used to access the buffer, this warning might be reported in error. +This warning indicates that the value of the index that's used to write to the buffer can exceed the writeable size of the buffer. + +The code analysis tool may report this warning in error. It reports this warning when it can't reduce a complex expression that represents the buffer size, or the index used to access the buffer. + +Code analysis name: `POTENTIAL_WRITE_OVERRUN` ## Example diff --git a/docs/code-quality/c6500.md b/docs/code-quality/c6500.md index 14bd402e7d..db2024951b 100644 --- a/docs/code-quality/c6500.md +++ b/docs/code-quality/c6500.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: C6500" -title: C6500 +description: "Learn more about: Warning C6500" +title: Warning C6500 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6500"] +f1_keywords: ["C6500", "INVALID_ATTRIBUTE_PROPERTY", "__WARNING_INVALID_ATTRIBUTE_PROPERTY"] helpviewer_keywords: ["C6500"] ms.assetid: bfc61ec1-8ac5-4465-a23c-91418fbc4552 --- -# C6500 +# Warning C6500 -> warning C6500: invalid annotation: value for \ property is invalid +> Invalid annotation: value for '*name*' property is invalid > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that a property value used in the annotation is not valid. For example, it can occur if an incorrect level of dereference is used in the Deref property, or if you use a constant value that is larger than size_t for properties like ElementSize. +## Remarks + +This warning indicates that a property value used in the annotation isn't valid. For example, it can occur if an incorrect level of dereference is used in the `Deref` property, or if you use a constant value that is larger than `size_t` for properties like `ElementSize`. + +Code analysis name: `INVALID_ATTRIBUTE_PROPERTY` ## Example -The following code generates this warning because an incorrect level of dereference is used in the Pre condition: +The following code generates this warning because an incorrect level of dereference is used in the `Pre` condition: ```cpp // C diff --git a/docs/code-quality/c6501.md b/docs/code-quality/c6501.md index 8e663f71e4..437e4e78f4 100644 --- a/docs/code-quality/c6501.md +++ b/docs/code-quality/c6501.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6501" -title: C6501 +description: "Learn more about: Warning C6501" +title: Warning C6501 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6501"] +f1_keywords: ["C6501", "CONFLICTING_ATTRIBUTE_PROPERTY_VALUES", "__WARNING_CONFLICTING_ATTRIBUTE_PROPERTY_VALUES"] helpviewer_keywords: ["C6501"] ms.assetid: f9e8b847-2516-4bbb-bb1c-c87cfbacf254 --- -# C6501 +# Warning C6501 -> warning C6501: annotation conflict: \ property conflicts with previously specified property +> Annotation conflict: '*name*' property conflicts with previously specified property > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates the presence of conflicting properties in the annotation. This typically occurs when multiple properties that serve similar purpose are used to annotate a parameter or return value. To correct the warning, you must choose the property that best addresses your need. +## Remarks + +This warning indicates the presence of conflicting properties in the annotation. The warning typically occurs when multiple properties that serve similar purpose are used to annotate a parameter or return value. To correct the warning, you must choose the property that best addresses your need. + +Code analysis name: `CONFLICTING_ATTRIBUTE_PROPERTY_VALUES` ## Example diff --git a/docs/code-quality/c6503.md b/docs/code-quality/c6503.md index 1d1f71cb4d..919cad1a16 100644 --- a/docs/code-quality/c6503.md +++ b/docs/code-quality/c6503.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6503" -title: C6503 +description: "Learn more about: Warning C6503" +title: Warning C6503 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6503"] +f1_keywords: ["C6503", "REFERENCES_CANT_BE_NULL", "__WARNING_REFERENCES_CANT_BE_NULL"] helpviewer_keywords: ["C6503"] ms.assetid: a6212938-bef9-4830-becb-6baa70b53e97 --- -# C6503 +# Warning C6503 -> warning C6503: Invalid annotation: references and arrays may not be marked Null=Yes or Null=Maybe +> Invalid annotation: references and arrays may not be marked `Null=Yes` or `Null=Maybe` > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that Null property is incorrectly used on a reference or array type. A reference or array type holds the address of an object and must point to a valid object. Because reference and array types cannot be null, you must correct the error by either removing the Null property or by setting the Null property value to No. +## Remarks + +This warning indicates that `Null` property is incorrectly used on a reference or array type. A reference or array type holds the address of an object and must point to a valid object. Because reference and array types can't be null, you must correct the error by either removing the `Null` property or by setting the `Null` property value to `No`. + +Code analysis name: `REFERENCES_CANT_BE_NULL` ## Example diff --git a/docs/code-quality/c6504.md b/docs/code-quality/c6504.md index 319eb776d8..e77e99df28 100644 --- a/docs/code-quality/c6504.md +++ b/docs/code-quality/c6504.md @@ -1,60 +1,59 @@ --- -description: "Learn more about: C6504" -title: C6504 -ms.date: 12/19/2019 -ms.topic: reference -f1_keywords: ["C6504"] +description: "Learn more about: Warning C6504" +title: Warning C6504 +ms.date: 10/03/2022 +f1_keywords: ["C6504", "NULL_ON_NON_POINTER", "__WARNING_NULL_ON_NON_POINTER"] helpviewer_keywords: ["C6504"] ms.assetid: 6baeed46-e73d-4974-af16-7487c55b3473 --- -# C6504 +# Warning C6504 -> warning C6504: invalid annotation: property may only be used on values of pointer, pointer-to-member, or array type +> Invalid annotation: property may only be used on values of pointer, pointer-to-member, or array type -This warning indicates the use of a pointer-specific SAL annotation on a non-pointer data type. For more information about what data types are supported by properties, see [Annotation Properties](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +This warning indicates the use of a pointer-specific SAL annotation on a non-pointer data type. + +## Remarks + +For more information about what data types are supported by properties, see [Annotation Properties](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +Code analysis name: `NULL_ON_NON_POINTER` ## Example -```cpp -#include +The following code generates warning C6504. This issue stems from the use of the pointer-specific `_Maybenull_` and `_Notnull_` on reference `pt`. +```cpp class Point { -public: - // members + public: + // members }; -// Oops, according to this annotation, pt may be null which does not make sense for a reference types void f(_Pre_ _Maybenull_ Point& pt) { // code ... } -// Oops, according to this annotation, pt cannot be null which does not make sense for a reference types void g(_Pre_ _Notnull_ Point& pt) { // code ... } ``` -To correct this warning remove the annotation if it does not make sense. You could also change to an annotation to be applicable to the type used, or change to type to match the annotation. +To correct this warning, remove the annotation if it doesn't make sense. You could also change to an annotation that's applicable to the type used, or change the type to match the annotation. The following code remediates this warning by changing the first instance of `pt` to a pointer and by removing the second annotation to match the reference type. ```cpp -#include - class Point { -public: - // members + public: + // members }; -// Changed to pointer type because it may be null void f(_Pre_ _Maybenull_ Point* pt) { // code ... } -// Removed annotation because it did not apply to reference types. void g(Point& pt) { // code ... diff --git a/docs/code-quality/c6505.md b/docs/code-quality/c6505.md index 08843cd99a..3edfe826bb 100644 --- a/docs/code-quality/c6505.md +++ b/docs/code-quality/c6505.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6505" -title: C6505 +description: "Learn more about: Warning C6505" +title: Warning C6505 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6505"] +f1_keywords: ["C6505", "MUSTCHECK_ON_VOID", "__WARNING_MUSTCHECK_ON_VOID"] helpviewer_keywords: ["C6505"] ms.assetid: 1883ce60-48d7-41c8-add8-814e4b8b908b --- -# C6505 +# Warning C6505 -> warning C6505: invalid annotation: MustCheck property may not be used on values of void type +> Invalid annotation: MustCheck property may not be used on values of void type -This warning indicated that MustCheck property was used on a void data type. You cannot use MustCheck property on void type. Either remove the MustCheck property or use another data type. +## Remarks + +This warning indicated that MustCheck property was used on a void data type. You can't use `MustCheck` property on `void` type. Either remove the `MustCheck` property or use another data type. + +Code analysis name: `MUSTCHECK_ON_VOID` ## Example diff --git a/docs/code-quality/c6506.md b/docs/code-quality/c6506.md index e80d7abe48..377aef7813 100644 --- a/docs/code-quality/c6506.md +++ b/docs/code-quality/c6506.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6506" -title: C6506 +title: Warning C6506 +description: "Learn more about: Warning C6506" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6506"] +f1_keywords: ["C6506", "BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY", "__WARNING_BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY"] helpviewer_keywords: ["C6506"] -ms.assetid: 20b87ee8-13ea-4d71-95a1-2b2d144d196a --- -# C6506 +# Warning C6506 -> warning C6506: invalid annotation: \ property may only be used on values of pointer or array types +> Invalid annotation: '*name*' property may only be used on values of pointer or array types + +## Remarks This warning indicates that a property is used on a type other than pointer or array types. The Access, Tainted, and Valid properties can be used on all data types. Other properties, such as ValidBytesConst, ValidElementsConst, ElementSize, and NullTerminted support pointer, pointer to members, or array types. For a complete list of properties and the supported data types, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY` + ## Example The following code generates this warning: ```cpp -#include +#include void f(_Out_ char c) { c = 'd'; @@ -28,7 +30,7 @@ void f(_Out_ char c) To correct this warning, use a pointer or an array type, as shown in the following sample code: ```cpp -#include +#include void f(_Out_ char *c) { *c = 'd'; diff --git a/docs/code-quality/c6508.md b/docs/code-quality/c6508.md index 2d5020e858..3915b736ae 100644 --- a/docs/code-quality/c6508.md +++ b/docs/code-quality/c6508.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6508" -title: C6508 +description: "Learn more about: Warning C6508" +title: Warning C6508 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6508"] +f1_keywords: ["C6508", "WRITE_ACCESS_ON_CONST", "__WARNING_WRITE_ACCESS_ON_CONST"] helpviewer_keywords: ["C6508"] ms.assetid: ac5b23c8-ab9e-481b-bc97-8404f0b63100 --- -# C6508 +# Warning C6508 -> warning C6508: invalid annotation: write access is not allowed on const values +> Invalid annotation: write access is not allowed on const values > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + This warning indicates that the Access property specified on a const parameter implies that it can be written to. For constant values, Access=Read is the only valid setting. +Code analysis name: `WRITE_ACCESS_ON_CONST` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6509.md b/docs/code-quality/c6509.md index e40431abd5..5266f53e76 100644 --- a/docs/code-quality/c6509.md +++ b/docs/code-quality/c6509.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6509" -title: C6509 +description: "Learn more about: Warning C6509" +title: Warning C6509 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6509"] +f1_keywords: ["C6509", "RETURN_USED_ON_PRECONDITION", "__WARNING_RETURN_USED_ON_PRECONDITION"] helpviewer_keywords: ["C6509"] ms.assetid: 6311bfd9-8372-48da-b01b-1c8775c38449 --- -# C6509 +# Warning C6509 -> warning C6509: invalid annotation: 'return' cannot be referenced from a precondition +> Invalid annotation: 'return' cannot be referenced from a precondition -This warning indicates that the **`return`** keyword cannot be used in a precondition. The **`return`** keyword is used to terminate the execution of a function and return control to the calling function. +## Remarks + +This warning indicates that the **`return`** keyword can't be used in a precondition. The **`return`** keyword is used to terminate the execution of a function and return control to the calling function. + +Code analysis name: `RETURN_USED_ON_PRECONDITION` ## Example diff --git a/docs/code-quality/c6510.md b/docs/code-quality/c6510.md index 7095859ba0..e6d2366a4c 100644 --- a/docs/code-quality/c6510.md +++ b/docs/code-quality/c6510.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C6510" -title: C6510 +description: "Learn more about: Warning C6510" +title: Warning C6510 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6510"] +f1_keywords: ["C6510", "NULLTERMINATED_ON_NON_POINTER", "__WARNING_NULLTERMINATED_ON_NON_POINTER"] helpviewer_keywords: ["C6510"] ms.assetid: b7fc5eb4-3311-442c-ac79-401e88ef2129 --- -# C6510 +# Warning C6510 -> warning C6510: Invalid annotation: 'NullTerminated' property may only be used on buffers whose elements are of integral or pointer type: Function '\' \. +> Invalid annotation: 'NullTerminated' property may only be used on buffers whose elements are of integral or pointer type: Function ''*function*'' '*parameter*'. -This warning indicates an incorrect use of the **NullTerminated** property (those ending in '`_z`'). You can only use this type of property on pointer or array types. +## Remarks + +This warning indicates an incorrect use of the **NullTerminated** property (the ones ending in '`_z`'). You can only use this type of property on pointer or array types. + +Code analysis name: `NULLTERMINATED_ON_NON_POINTER` ## Example diff --git a/docs/code-quality/c6511.md b/docs/code-quality/c6511.md index f8baeaf483..262a03838f 100644 --- a/docs/code-quality/c6511.md +++ b/docs/code-quality/c6511.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6511" -title: C6511 +description: "Learn more about: Warning C6511" +title: Warning C6511 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6511"] +f1_keywords: ["C6511", "MUSTCHECK_MAYBE", "__WARNING_MUSTCHECK_MAYBE"] helpviewer_keywords: ["C6511"] ms.assetid: 1a0ac213-c205-4fb1-9bc3-3dc7885329fa --- -# C6511 +# Warning C6511 -> warning C6511: invalid annotation: MustCheck property must be Yes or No +> Invalid annotation: MustCheck property must be Yes or No > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates an invalid value for MustCheck property was specified. The only valid values for this property are: Yes and No. +## Remarks + +This warning indicates an invalid value for `MustCheck` property was specified. The only valid values for this property are: Yes and No. + +Code analysis name: `MUSTCHECK_MAYBE` ## Example diff --git a/docs/code-quality/c6513.md b/docs/code-quality/c6513.md index 45c5d0bb6f..be19005461 100644 --- a/docs/code-quality/c6513.md +++ b/docs/code-quality/c6513.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6513" -title: C6513 +description: "Learn more about: Warning C6513" +title: Warning C6513 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6513"] +f1_keywords: ["C6513", "ELEMENT_SIZE_WITHOUT_BUFFER_SIZE", "__WARNING_ELEMENT_SIZE_WITHOUT_BUFFER_SIZE"] helpviewer_keywords: ["C6513"] ms.assetid: b27780ac-b237-4b26-a796-68a920da73a3 --- -# C6513 +# Warning C6513 -> warning C6513: invalid annotation: ElementSizeConst requires additional size properties +> Invalid annotation: ElementSizeConst requires additional size properties > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that ElementSizeConst requires other properties that are missing from the annotation. Specifying ElementSizeConst alone does not provide any benefit to the analysis process. In addition to specifying ElementSize, other properties such as ValidElementsConst or WritableElementsConst must also be specified. +## Remarks + +This warning indicates that `ElementSizeConst` requires other properties that are missing from the annotation. Specifying `ElementSizeConst` alone doesn't provide any benefit to the analysis process. In addition to specifying `ElementSize`, other properties such as `ValidElementsConst` or `WritableElementsConst` must also be specified. + +Code analysis name: `ELEMENT_SIZE_WITHOUT_BUFFER_SIZE` ## Example diff --git a/docs/code-quality/c6514.md b/docs/code-quality/c6514.md index e0b4cd9482..cad312ecf2 100644 --- a/docs/code-quality/c6514.md +++ b/docs/code-quality/c6514.md @@ -1,23 +1,24 @@ --- -description: "Learn more about: C6514" -title: C6514 +description: "Learn more about: Warning C6514" +title: Warning C6514 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6514"] +f1_keywords: ["C6514", "BUFFER_SIZE_EXCEEDS_ARRAY_SIZE", "__WARNING_BUFFER_SIZE_EXCEEDS_ARRAY_SIZE"] helpviewer_keywords: ["C6514"] ms.assetid: 4930a9f9-c721-437f-8754-cf39b30ea2db --- -# C6514 +# Warning C6514 -> warning C6514: invalid annotation: value of the \ property exceeds the size of the array +> Invalid annotation: value of the '*name*' property exceeds the size of the array ## Remarks This warning indicates that a property value exceeds the size of the array specified in the parameter being annotated. This warning occurs when the value specified for the annotation property is greater than the actual length of the array being passed. +Code analysis name: `BUFFER_SIZE_EXCEEDS_ARRAY_SIZE` + ## Example -The following code generates this warning because the size of the array is 6 whereas the ValidElementsConst property value is 8: +The following code generates this warning because the size of the array is 6 but the `ValidElementsConst` property value is 8: ```cpp // C diff --git a/docs/code-quality/c6515.md b/docs/code-quality/c6515.md index 85da3d19fd..1f329099e6 100644 --- a/docs/code-quality/c6515.md +++ b/docs/code-quality/c6515.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6515" -title: C6515 +description: "Learn more about: Warning C6515" +title: Warning C6515 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6515"] +f1_keywords: ["C6515", "BUFFER_SIZE_ON_NON_POINTER", "__WARNING_BUFFER_SIZE_ON_NON_POINTER"] helpviewer_keywords: ["C6515"] ms.assetid: e0f21858-0fea-427b-965a-a7eff62e1371 --- -# C6515 +# Warning C6515 -> warning C6515 - invalid annotation: \ property may only be used on values of pointer type +> Invalid annotation: '*name*' property may only be used on values of pointer type + +## Remarks This warning indicates that a property for use on pointers was applied to a non-pointer type. For a list of annotation properties, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `BUFFER_SIZE_ON_NON_POINTER` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6516.md b/docs/code-quality/c6516.md index b345070573..7bb9fb5682 100644 --- a/docs/code-quality/c6516.md +++ b/docs/code-quality/c6516.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: C6516" -title: C6516 +description: "Learn more about: Warning C6516" +title: Warning C6516 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6516"] +f1_keywords: ["C6516", "NO_PROPERTIES_ON_ATTRIBUTE", "__WARNING_NO_PROPERTIES_ON_ATTRIBUTE"] helpviewer_keywords: ["C6516"] ms.assetid: 461078c8-18d4-49ca-80a2-a15736f429a0 --- -# C6516 +# Warning C6516 -> warning C6516: invalid annotation: no properties specified for \ attribute +> Invalid annotation: no properties specified for '*name*' attribute > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that either no property was specified in the attribute or the property that was specified is invalid; therefore, the attribute cannot be considered complete. +## Remarks + +This warning indicates that either no property was specified in the attribute or the property that was specified is invalid; therefore, the attribute can't be considered complete. + +Code analysis name: `NO_PROPERTIES_ON_ATTRIBUTE` ## Example -The following code generates this warning because Deref=1 only specifies the level of indirection, but this information alone does not help the analysis tool: +The following code generates this warning because Deref=1 only specifies the level of indirection, but this information alone doesn't help the analysis tool: ```cpp // C diff --git a/docs/code-quality/c6517.md b/docs/code-quality/c6517.md index affb381143..b7ce49aa83 100644 --- a/docs/code-quality/c6517.md +++ b/docs/code-quality/c6517.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: C6517" -title: C6517 +description: "Learn more about: Warning C6517" +title: Warning C6517 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6517"] +f1_keywords: ["C6517", "VALID_SIZE_ON_NON_READABLE_BUFFER", "__WARNING_VALID_SIZE_ON_NON_READABLE_BUFFER"] helpviewer_keywords: ["C6517"] ms.assetid: 96822155-8b2a-4699-980f-744afff84ca8 --- -# C6517 +# Warning C6517 -> warning C6517: Invalid annotation: 'SAL_readableTo' property may not be specified on buffers that are not readable: '\_Param\_(1)'. +> Invalid annotation: 'SAL_readableTo' property may not be specified on buffers that are not readable: '*Parameter*'. > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that `SAL_readableTo` property does not have the required read access. You cannot use this property to annotate a parameter without providing read access. +## Remarks + +This warning indicates that `SAL_readableTo` property doesn't have the required read access. You can't use this property to annotate a parameter without providing read access. + +Code analysis name: `VALID_SIZE_ON_NON_READABLE_BUFFER` ## Example -The following code generates this warning because read access is not granted on the buffer: +The following code generates this warning because read access isn't granted on the buffer: ```cpp #include diff --git a/docs/code-quality/c6518.md b/docs/code-quality/c6518.md index dfab23db1c..179ef86f93 100644 --- a/docs/code-quality/c6518.md +++ b/docs/code-quality/c6518.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6518" -title: C6518 +description: "Learn more about: Warning C6518" +title: Warning C6518 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6518"] +f1_keywords: ["C6518", "WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER", "__WARNING_WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER"] helpviewer_keywords: ["C6518"] ms.assetid: c391a75b-9f16-43a5-a7cd-c5a233002850 --- -# C6518 +# Warning C6518 -> warning C6518: Invalid annotation: 'SAL_writableTo' property may not be specified as a precondition on buffers that are not writable: '\_Param\_(1)' +> Invalid annotation: 'SAL_writableTo' property may not be specified as a precondition on buffers that are not writable: '*Parameter*'. -This warning indicates that a conflict exists between a `SAL_writableTo` property value and a writable property. This ordinarily indicates that a writable property does not have write access to the parameter being annotated. +## Remarks + +This warning indicates that a conflict exists between a `SAL_writableTo` property value and a writable property. The warning ordinarily indicates that a writable property doesn't have write access to the parameter being annotated. + +Code analysis name: `WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER` ## Example -The following code generates this warning because the `_Out_` annotation compiles to include a `SAL_writableTo` property, which does not allow write access: +The following code generates this warning because the `_Out_` annotation compiles to include a `SAL_writableTo` property, which doesn't allow write access: ```cpp #include diff --git a/docs/code-quality/c6522.md b/docs/code-quality/c6522.md index 0ef96ca6a4..3f7b9cbb6d 100644 --- a/docs/code-quality/c6522.md +++ b/docs/code-quality/c6522.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: C6522" -title: C6522 +description: "Learn more about: Warning C6522" +title: Warning C6522 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6522"] +f1_keywords: ["C6522", "INVALID_SIZE_STRING_TYPE", "__WARNING_INVALID_SIZE_STRING_TYPE"] helpviewer_keywords: ["C6522"] ms.assetid: ac482f63-b27f-4807-968a-1c449033d2dd --- -# C6522 +# Warning C6522 -> warning C6522: invalid size specification: expression must be of integral type +> Invalid size specification: expression must be of integral type: annotation '*annotation*' on function '*function*' '*parameter*' > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + This warning indicates that an integral type was expected, but an incorrect data type was used. You can use annotation properties that accept the size of a parameter in terms of another parameter, but you must use correct data type. For a list of annotation properties, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `INVALID_SIZE_STRING_TYPE` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6525.md b/docs/code-quality/c6525.md index 81d20ab9ce..360aa708d9 100644 --- a/docs/code-quality/c6525.md +++ b/docs/code-quality/c6525.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6525" -title: C6525 +description: "Learn more about: Warning C6525" +title: Warning C6525 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6525"] +f1_keywords: ["C6525", "INVALID_SIZE_STRING_UNREACHABLE_LOCATION", "__WARNING_INVALID_SIZE_STRING_UNREACHABLE_LOCATION"] helpviewer_keywords: ["C6525"] ms.assetid: a7af4dc7-d5a4-455f-a414-0c389ffd9aa9 --- -# C6525 +# Warning C6525 -> warning C6525: invalid size specification: property value may not be valid +> Invalid size specification: property value may not be valid > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that the property value used to specify the size is not valid. This occurs if the size parameter is annotated using Valid=No. +## Remarks + +This warning indicates that the property value used to specify the size isn't valid. The warning occurs if the size parameter is annotated using `Valid=No`. + +Code analysis name: `INVALID_SIZE_STRING_UNREACHABLE_LOCATION` ## Example diff --git a/docs/code-quality/c6527.md b/docs/code-quality/c6527.md index 5246109cda..4c6c08810c 100644 --- a/docs/code-quality/c6527.md +++ b/docs/code-quality/c6527.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C6527" -title: C6527 +description: "Learn more about: Warning C6527" +title: Warning C6527 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6527"] helpviewer_keywords: ["C6527"] ms.assetid: 5ebb6279-0f75-4566-a5f3-a47834de9625 --- -# C6527 +# Warning C6527 -> warning C6527: Invalid annotation: NeedsRelease property may not be used on values of void type +> Invalid annotation: NeedsRelease property may not be used on values of void type diff --git a/docs/code-quality/c6530.md b/docs/code-quality/c6530.md index d203ff4e71..4bf05cf3e3 100644 --- a/docs/code-quality/c6530.md +++ b/docs/code-quality/c6530.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: C6530" -title: C6530 +description: "Learn more about: Warning C6530" +title: Warning C6530 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6530"] +f1_keywords: ["C6530", "UNRECOGNIZED_FORMAT_STRING_STYLE", "__WARNING_UNRECOGNIZED_FORMAT_STRING_STYLE"] helpviewer_keywords: ["C6530"] ms.assetid: 60e9dc58-e0f1-4a34-8c75-efebaa6cadd2 --- -# C6530 +# Warning C6530 -> warning C6530: unrecognized format string style \ +> Unrecognized format string style '*name*' > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that the FormatString property is using a value other than scanf or printf. To correct this warning, review your code and use a valid value for the Style property. +## Remarks + +This warning indicates that the `FormatString` property is using a value other than `scanf` or `printf`. To correct this warning, review your code and use a valid value for the `Style` property. + +Code analysis name: `UNRECOGNIZED_FORMAT_STRING_STYLE` ## Example diff --git a/docs/code-quality/c6540.md b/docs/code-quality/c6540.md index 97520807fa..77790ec3ea 100644 --- a/docs/code-quality/c6540.md +++ b/docs/code-quality/c6540.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C6540" -title: C6540 +description: "Learn more about: Warning C6540" +title: Warning C6540 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6540"] helpviewer_keywords: ["C6540"] ms.assetid: b047084c-9187-443e-8bcd-8f42064003f7 --- -# C6540 +# Warning C6540 -> warning C6540: The use of attribute annotations on this function will invalidate all of its existing **`__declspec`** annotations +> The use of attribute annotations on this function will invalidate all of its existing **`__declspec`** annotations diff --git a/docs/code-quality/c6551.md b/docs/code-quality/c6551.md index 944bafdfa3..d6b47b6f15 100644 --- a/docs/code-quality/c6551.md +++ b/docs/code-quality/c6551.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C6551" -title: C6551 +description: "Learn more about: Warning C6551" +title: Warning C6551 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6551"] helpviewer_keywords: ["C6551"] ms.assetid: cfd02698-7ba7-4564-841d-208999b1561d --- -# C6551 +# Warning C6551 -> warning C6551: Invalid size specification: expression not parsable +> Invalid size specification: expression not parsable > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). diff --git a/docs/code-quality/c6552.md b/docs/code-quality/c6552.md index 57c0fdd9d6..9ccb714199 100644 --- a/docs/code-quality/c6552.md +++ b/docs/code-quality/c6552.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C6552" -title: C6552 +description: "Learn more about: Warning C6552" +title: Warning C6552 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6552"] helpviewer_keywords: ["C6552"] ms.assetid: 6c6f17d8-4ddd-4fad-b81f-e32285e7afa8 --- -# C6552 +# Warning C6552 -> warning C6552: Invalid `Deref=` or `Notref=`: expression not parsable +> Invalid `Deref=` or `Notref=`: expression not parsable > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). diff --git a/docs/code-quality/c6701.md b/docs/code-quality/c6701.md index 47dc9ab7b6..386d29a099 100644 --- a/docs/code-quality/c6701.md +++ b/docs/code-quality/c6701.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: C6701" -title: C6701 +title: Warning C6701 +description: "Learn more about: Warning C6701" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6701"] -helpviewer_keywords: ["C67901"] -ms.assetid: c48484e2-542c-4f7b-93ea-98c6367cb3d9 +helpviewer_keywords: ["C6701"] --- -# C6701 +# Warning C6701 -> warning C6701: The value is not a valid Yes/No/Maybe value: \ +> The value is not a valid Yes/No/Maybe value: '*string*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6702.md b/docs/code-quality/c6702.md index 5fab2c898c..6fb0c5520d 100644 --- a/docs/code-quality/c6702.md +++ b/docs/code-quality/c6702.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C6702" -title: C6702 +description: "Learn more about: Warning C6702" +title: Warning C6702 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6702"] helpviewer_keywords: ["C6702"] ms.assetid: 6d373843-4ab4-4a94-bb83-5fec9214c625 --- -# C6702 +# Warning C6702 -> warning C6702: The value is not a string value: \ +> The value is not a string value: '*string*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6703.md b/docs/code-quality/c6703.md index d6d89be47f..f8b5ad7669 100644 --- a/docs/code-quality/c6703.md +++ b/docs/code-quality/c6703.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C6703" -title: C6703 +description: "Learn more about: Warning C6703" +title: Warning C6703 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6703"] helpviewer_keywords: ["C6703"] ms.assetid: 8ec4f403-e63e-4930-8266-569c9cd263b4 --- -# C6703 +# Warning C6703 -> warning C6703: The value is not a number: \ +> The value is not a number: '*string*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6704.md b/docs/code-quality/c6704.md index 2edd6f25ef..c15266ab7f 100644 --- a/docs/code-quality/c6704.md +++ b/docs/code-quality/c6704.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C6704" -title: C6704 +description: "Learn more about: Warning C6704" +title: Warning C6704 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6704"] helpviewer_keywords: ["C6704"] ms.assetid: fc25543d-746e-415e-b0a8-d5134461af41 --- -# C6704 +# Warning C6704 -> warning C6704: Unexpected Annotation Expression Error: \ [\] +> Unexpected Annotation Expression Error: '*annotation*' ['*why*'] -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6705.md b/docs/code-quality/c6705.md index 0049e5d34b..6d6c84dcc5 100644 --- a/docs/code-quality/c6705.md +++ b/docs/code-quality/c6705.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C6705" -title: C6705 +description: "Learn more about: Warning C6705" +title: Warning C6705 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6705"] helpviewer_keywords: ["C6705"] ms.assetid: 5d81e7ac-0c51-4cca-aaa8-df1aa599f175 --- -# C6705 +# Warning C6705 -> warning C6705: Annotation error expected arguments for annotation \ found . +> Annotation error expected arguments for annotation '*parameter*' found . -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6706.md b/docs/code-quality/c6706.md index fdd87f0131..317a1bb989 100644 --- a/docs/code-quality/c6706.md +++ b/docs/code-quality/c6706.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C6706" -title: C6706 +description: "Learn more about: Warning C6706" +title: Warning C6706 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6706"] helpviewer_keywords: ["C6706"] ms.assetid: 20f3fd01-4993-4f7f-bd3f-57706356cf1d --- -# C6706 +# Warning C6706 -> warning C6706: Unexpected Annotation Error for annotation \: \ +> Unexpected Annotation Error for annotation '*annotation*': '*why*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6707.md b/docs/code-quality/c6707.md index f60931a941..8a12d79df9 100644 --- a/docs/code-quality/c6707.md +++ b/docs/code-quality/c6707.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C6707" -title: C6707 +description: "Learn more about: Warning C6707" +title: Warning C6707 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6707"] helpviewer_keywords: ["C6707"] ms.assetid: a6610464-9bc5-4f24-b0a5-7fa29581874d --- -# C6707 +# Warning C6707 -> warning C6707: Unexpected Model Error: \ +> Unexpected Model Error: '*why*' diff --git a/docs/code-quality/c6993.md b/docs/code-quality/c6993.md index 07c46c2a9a..54f78c56c9 100644 --- a/docs/code-quality/c6993.md +++ b/docs/code-quality/c6993.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: C6993" -title: C6993 -ms.date: 11/04/2016 -ms.topic: reference +title: Warning C6993 +description: "Learn more about: Warning C6993" +ms.date: 2/25/2025 f1_keywords: ["C6993"] -ms.assetid: 7ea93bc6-b934-4b6b-b71a-a56e765fb4cd +helpviewer_keywords: ["C6993"] --- -# C6993 +# Warning C6993 -> warning C6993: Code analysis ignores OpenMP constructs; analyzing single-threaded code +> Code analysis ignores OpenMP constructs; analyzing single-threaded code -This warning indicates that the Code Analyzer has encountered Open MP pragmas that it cannot analyze. +This warning indicates that the static analysis tools don't support Open MP pragmas. The static analysis tools could generate incorrect results because they assume the code is single-threaded, not multi-threaded. + +Your code doesn't necessarily need to be 'fixed' to resolve this diagnostic because this warning indicates what the toolset supports and not an issue with your code. \ No newline at end of file diff --git a/docs/code-quality/c6995.md b/docs/code-quality/c6995.md index 321ce2ed49..4ca022014e 100644 --- a/docs/code-quality/c6995.md +++ b/docs/code-quality/c6995.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C6995" -title: C6995 +title: Warning C6995 +description: "Learn more about: Warning C6995" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6995"] -ms.assetid: 1e82e3ad-99fe-4a35-87d5-359c74b9658e +helpviewer_keywords: ["C6995"] --- -# C6995 +# Warning C6995 -> warning C6995: Failed to save XML Log file +> Failed to save XML Log file -This warning indicates that the Code Analysis tool cannot create the defect log, which is the output of the code analysis. +This warning indicates that the Code Analysis tool can't create the defect log, which is the output of the code analysis. -This error might indicate a disk error or indicate that you do not have permission to create a file in the specified directory. +This error might indicate a disk error or indicate that you don't have permission to create a file in the specified directory. diff --git a/docs/code-quality/c6997.md b/docs/code-quality/c6997.md index 01a768b5e2..8cbfc9bd5e 100644 --- a/docs/code-quality/c6997.md +++ b/docs/code-quality/c6997.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: C6997" -title: C6997 +title: Warning C6997 +description: "Learn more about: Warning C6997" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6997"] -ms.assetid: 48fd86a3-d57b-4ecb-979a-5d3a4186482e +f1_keywords: ["C6997", "IGNORED_ANNOTATIONS"] +helpviewer_keywords: ["C6997"] --- -# C6997 +# Warning C6997 -> warning C6997: Annotations at this location are meaningless and will be ignored. +> Annotations at this location are meaningless and will be ignored. -Annotations cannot be applied to `extern "C" {...}`. Apply the annotations to a specific object. +## Remarks + +Annotations can't be applied to `extern "C" {...}`. Apply the annotations to a specific object. + +Code analysis name: `IGNORED_ANNOTATIONS` ## See also diff --git a/docs/code-quality/clang-tidy.md b/docs/code-quality/clang-tidy.md index 7c3ec8d831..7427e96a45 100644 --- a/docs/code-quality/clang-tidy.md +++ b/docs/code-quality/clang-tidy.md @@ -1,15 +1,15 @@ --- title: Using Clang-Tidy in Visual Studio description: "How to use Clang-Tidy in Visual Studio for Microsoft C++ code analysis." -ms.date: 02/19/2020 +ms.date: 03/1/2022 ms.topic: "conceptual" -f1_keywords: ["vs.codeanalysis.clangtidy"] +f1_keywords: ["vs.codeanalysis.clangtidy","vs.codeanalysis.propertypages.ClangTidyToolPath"] --- # Using Clang-Tidy in Visual Studio ::: moniker range="<=msvc-150" -Support for Clang-Tidy requires Visual Studio 2019 version 16.4 or later. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +Support for Clang-Tidy requires Visual Studio 2019 version 16.4 or later. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's at the top of the table of contents on this page. ::: moniker-end @@ -31,25 +31,72 @@ For more information, see [How to: Set Code Analysis Properties for C/C++ Projec ## CMake -In CMake projects, you can configure Clang-Tidy checks within *`CMakeSettings.json`*. Once opened, select "Edit JSON" in the top right-hand corner of the CMake Project Settings Editor. The following keys are recognized: +In CMake projects, you can configure Clang-Tidy checks within *`CMakeSettings.json`* or *`CMakePresets.json`*. + +Clang-Tidy recognizes the following keys: - `enableMicrosoftCodeAnalysis`: Enables Microsoft Code Analysis - `enableClangTidyCodeAnalysis`: Enables Clang-Tidy analysis -- `clangTidyChecks`: Clang-Tidy configuration, specified as a comma-separated list, that is, checks to be enabled or disabled - -If neither of the "enable" options are specified, Visual Studio will select the analysis tool matching the Platform Toolset used. - +- `clangTidyChecks`: Clang-Tidy configuration. A comma-separated list of checks to enable or disable. A leading `-` disables the check. For example, `cert-oop58-cpp, -cppcoreguidelines-no-malloc, google-runtime-int` enables `cert-oop58-cpp` and `google-runtime-int`, but disables `cppcoreguidelines-no-malloc`. For a list of Clang-Tidy checks, see the [Clang-Tidy documentation](https://clang.llvm.org/extra/clang-tidy/checks/list.html). + +If neither of the "enable" options are specified, Visual Studio selects the analysis tool matching the Platform Toolset used. + +### CMake settings + +To edit your Clang-Tidy settings, open your CMake settings, and select **Edit JSON** in the CMake Project Settings Editor. You can use the keys above to fill out your Clang-Tidy specifications in the CMake Settings JSON file. + +An example CMake settings implementation looks like this: + +```json +{ + "configurations": [ + { + "name": "x64-debug", + "generator": "Ninja", + .... + "clangTidyChecks": "llvm-include-order, -modernize-use-override", + "enableMicrosoftCodeAnalysis": true, + "enableClangTidyCodeAnalysis": true + } + ] +} +``` + +### CMake presets + +The same keys can be used in your CMake presets via the `vendor` object. + +An example CMake preset implementation looks like this: + +```json +"configurePreset": [ +{ "name": "base", + .... + "vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "clangTidyChecks": "llvm-include-order, -modernize-use-override", + "enableMicrosoftCodeAnalysis": true, + "enableClangTidyCodeAnalysis": true + } + } +} +] +``` ## Warning display -Clang-Tidy runs result in warnings displayed in the Error List, and as in-editor squiggles underneath relevant sections of code. Use the "Category" column in the Error List to sort and organize Clang-Tidy warnings. You can configure in-editor warnings by toggling the "Disable Code Analysis Squiggles" setting under **Tools** > **Options**. +Clang-Tidy runs result in warnings displayed in the Error List, and as in-editor squiggles underneath relevant sections of code. To sort and organize Clang-Tidy warnings, use the **Category** column in the **Error List** window. You can configure in-editor warnings by toggling the **Disable Code Analysis Squiggles** setting under **Tools** > **Options**. ## Clang-Tidy configuration -You can configure the checks that clang-tidy runs inside Visual Studio via the **Clang-Tidy Checks** option. This input is provided to the **`--checks`** argument of the tool. Any further configuration can be included in custom *`.clang-tidy`* files. For more information, see the [Clang-Tidy documentation on LLVM.org](https://clang.llvm.org/extra/clang-tidy/). +By default, Clang-Tidy does not set any checks when enabled. To see the list of checks in the command-line version, run `clang-tidy -list-checks` in a developer command prompt. You can configure the checks that Clang-Tidy runs inside Visual Studio. In the project Property Pages dialog, open the **Configuration Properties** > **Code Analysis** > **Clang-Tidy** page. Enter checks to run in the **Clang-Tidy Checks** property. A good default set is `clang-analyzer-*`. This property value is provided to the **`--checks`** argument of the tool. Any further configuration can be included in custom *`.clang-tidy`* files. For more information, see the [Clang-Tidy documentation on LLVM.org](https://clang.llvm.org/extra/clang-tidy/). + +## Clang-Tidy Tool Directory + +If you'd like to have custom rules built into your clang-tidy executable and run it in Microsoft Visual Studio, you can change the path to the executable that Visual Studio runs. In the project Property Pages dialog, open the **Configuration Properties** > **Code Analysis** > **Clang-Tidy** page. Manually type in the path or **Browse** and select the path under the **Clang-Tidy Tool Directory** property. The new executable is used once the change is saved, and the app is recompiled. ## See also -- [Clang/LLVM Support for MSBuild Projects](https://devblogs.microsoft.com/cppblog/clang-llvm-support-for-msbuild-projects/) -- [Clang/LLVM Support for CMake Projects](https://devblogs.microsoft.com/cppblog/visual-studio-cmake-support-clang-llvm-cmake-3-14-vcpkg-and-performance-improvements/) +[Clang/LLVM support for MSBuild projects](https://devblogs.microsoft.com/cppblog/clang-llvm-support-for-msbuild-projects/)\ +[Clang/LLVM support for CMake projects](https://devblogs.microsoft.com/cppblog/visual-studio-cmake-support-clang-llvm-cmake-3-14-vcpkg-and-performance-improvements/) ::: moniker-end diff --git a/docs/code-quality/code-analysis-for-cpp-corecheck.md b/docs/code-quality/code-analysis-for-cpp-corecheck.md index dc5f05ad2d..ecae8ba0d0 100644 --- a/docs/code-quality/code-analysis-for-cpp-corecheck.md +++ b/docs/code-quality/code-analysis-for-cpp-corecheck.md @@ -16,7 +16,7 @@ This section lists C++ Core Guidelines Checker warnings. For information about C ## OWNER_POINTER Group -[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ +[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). [C26403 RESET_OR_DELETE_OWNER](C26403.md)\ @@ -51,7 +51,7 @@ Do not assign the result of an allocation or a function call with an owner\ r [C26401 DONT_DELETE_NON_OWNER](c26401.md)\ Do not delete a raw pointer that is not an owner\. See [C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-raw). -[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ +[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). [C26408 NO_MALLOC_FREE](C26408.md)\ diff --git a/docs/code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md b/docs/code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md index 2fae13547e..cf2bac2dc3 100644 --- a/docs/code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md +++ b/docs/code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md @@ -10,9 +10,9 @@ helpviewer_keywords: --- # How to specify additional code information by using `_Analysis_assume_` -You can provide hints to the code analysis tool for C/C++ code that will help the analysis process and reduce warnings. To provide additional information, use the following function macro: +You can provide hints to the code analysis tool for C/C++ code that help the analysis process and reduce warnings. To provide additional information, use the following function macro: -`_Analysis_assume( expr )` +`_Analysis_assume_( expr )` *`expr`* - any expression that is assumed to evaluate to true. @@ -27,25 +27,44 @@ The following code uses `_Analysis_assume_` to correct the code analysis warning ```cpp #include -#include +#include -using namespace vc_attributes; +// Requires pc to be null. +void f(_Pre_null_ char* pc); -//requires pc to be null -void f([Pre(Null=Yes)] char* pc); - -// calls free and sets ch to null +// Calls free and sets ch to null. void FreeAndNull(char** ch); void test() { - char pc = (char)malloc(5); + char* pc = (char*)malloc(5); FreeAndNull(&pc); _Analysis_assume_(pc == NULL); f(pc); } ``` +`_Analysis_assume_` should be used as a last resort. We should first try to make the contracts of the functions more precise. In this case we could improve the contract of `FreeAndNull` instead of using `_Analysis_assume_`: + +```cpp +#include +#include + +// Requires pc to be null. +void f(_Pre_null_ char* pc); + +// Calls free and sets ch to null. +_At_(*ch, _Post_null_) +void FreeAndNull(char** ch); + +void test() +{ + char* pc = (char*)malloc(5); + FreeAndNull(&pc); + f(pc); +} +``` + ## See also - [__assume](../intrinsics/assume.md) diff --git a/docs/code-quality/index.yml b/docs/code-quality/index.yml index 7ae4caa668..337b3f5afa 100644 --- a/docs/code-quality/index.yml +++ b/docs/code-quality/index.yml @@ -8,6 +8,7 @@ metadata: description: Learn how Visual Studio can help you analyze C and C++ code quality. ms.topic: landing-page ms.date: 05/26/2020 + ms.author: twhitney ms.custom: intro-landing-hub # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new diff --git a/docs/code-quality/quick-start-code-analysis-for-c-cpp.md b/docs/code-quality/quick-start-code-analysis-for-c-cpp.md index d5924b87e7..499af5c14a 100644 --- a/docs/code-quality/quick-start-code-analysis-for-c-cpp.md +++ b/docs/code-quality/quick-start-code-analysis-for-c-cpp.md @@ -19,7 +19,7 @@ You can improve the quality of your application by running code analysis regular 1. To run code analysis every time the project is built using the selected configuration, select the **Enable Code Analysis on Build** check box. You can also run code analysis manually by opening the **Analyze** menu and then choosing **Run Code Analysis on** *ProjectName* or **Run Code Analysis on File**. -1. Choose the [rule set](using-rule-sets-to-specify-the-cpp-rules-to-run.md) that you want to use or create a [custom rule set](using-rule-sets-to-specify-the-cpp-rules-to-run.md#to-create-a-rule-set-in-a-text-editor). If using LLVM/clang-cl, see [Using Clang-Tidy in Visual Studio](../code-quality/clang-tidy.md) to configure Clang-Tidy analysis options. +1. Choose the [rule set](using-rule-sets-to-specify-the-cpp-rules-to-run.md) that you want to use or create a [custom rule set](using-rule-sets-to-specify-the-cpp-rules-to-run.md#to-create-a-rule-set-in-a-text-editor). If using LLVM/clang-cl, see [Using Clang-Tidy in Visual Studio](clang-tidy.md) to configure Clang-Tidy analysis options. ### Standard C/C++ rule sets @@ -42,7 +42,7 @@ Visual Studio includes these standard sets of rules for native code: | **C++ Core Check Raw Pointer Rules** | These rules enforce resource-management checks related to [raw pointers from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | | **C++ Core Check Rules** | These rules enforce a subset of the checks from the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c-core-guidelines). Use this ruleset to include all of the C++ Core Check rules except the Enum and Experimental rulesets. | | **C++ Core Check Shared Pointer Rules** | These rules enforce resource-management checks related to [types with shared pointer semantics from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | -| **C++ Core Check STL Rules** | These rules enforce checks related to the [C++ Standard Template Library (STL) from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-stdlib). | +| **C++ Core Check STL Rules** | These rules enforce checks related to the [C++ Standard Library from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-stdlib). | | **C++ Core Check Style Rules** | These rules enforce checks related to use of [expressions and statements from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es-expressions-and-statements). | | **C++ Core Check Type Rules** | These rules enforce the [Type profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile). | | **C++ Core Check Unique Pointer Rules** | These rules enforce resource-management checks related to types with [unique pointer semantics from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | @@ -57,10 +57,10 @@ Visual Studio includes these standard sets of rules for managed code: |--|--| | **Microsoft Basic Correctness Rules** | These rules focus on logic errors and common mistakes made in the usage of framework APIs. Include this rule set to expand on the list of warnings reported by the minimum recommended rules. | | **Microsoft Basic Design Guideline Rules** | These rules focus on enforcing best practices to make your code easy to understand and use. Include this rule set if your project includes library code or if you want to enforce best practices for easily maintainable code. | -| **Microsoft Extended Correctness Rules** | These rules expand on the basic correctness rules to maximize the reported logic and framework usage errors. Extra emphasis is placed on specific scenarios such as COM interop and mobile applications. Consider including this rule set if one of these scenarios applies to your project or to find additional problems in your project. | +| **Microsoft Extended Correctness Rules** | These rules expand on the basic correctness rules to maximize the reported logic and framework usage errors. Extra emphasis is placed on specific scenarios such as COM interop and mobile applications. Consider including this rule set if one of these scenarios applies to your project or to find more problems in your project. | | **Microsoft Extended Design Guideline Rules** | These rules expand on the basic design guideline rules to maximize the reported usability and maintainability issues. Extra emphasis is placed on naming guidelines. Consider including this rule set if your project includes library code or if you want to enforce the highest standards for writing maintainable code. | | **Microsoft Globalization Rules** | These rules focus on problems that prevent data in your application from displaying correctly when used in different languages, locales, and cultures. Include this rule set if your application is localized and/or globalized. | -| **Microsoft Managed Minimum Rules** | These rules focus on the most critical problems in your code for which Code Analysis is the most accurate. These rules are small in number and they are intended only to run in limited Visual Studio editions. Use MinimumRecommendedRules.ruleset with other Visual Studio editions. | +| **Microsoft Managed Minimum Rules** | These rules focus on the most critical problems in your code for which Code Analysis is the most accurate. These rules are small in number and they're intended only to run in limited Visual Studio editions. Use MinimumRecommendedRules.ruleset with other Visual Studio editions. | | **Microsoft Managed Recommended Rules** | These rules focus on the most critical problems in your code. These problems include potential security holes, application crashes, and other important logic and design errors. We recommend you include this rule set in any custom rule set you create for your projects. | | **Microsoft Mixed (C++ /CLR) Minimum Rules** | These rules focus on the most critical problems in your C++ projects that support the Common Language Runtime. These problems include potential security holes, application crashes, and other important logic and design errors. We recommend you include this rule set in any custom rule set you create for your C++ projects that support the Common Language Runtime. | | **Microsoft Mixed (C++ /CLR) Recommended Rules** | These rules focus on the most common and critical problems in your C++ projects that support the Common Language Runtime. These problems include potential security holes, application crashes, and other important logic and design errors. This ruleset is designed for use in the Visual Studio Professional edition and higher. | @@ -100,7 +100,7 @@ The Error List window lists the code analysis warnings found. The results are di For detailed information about the warning, including possible solutions to the issue, choose the warning ID in the Code column to display its corresponding online help article. -Double-click a warning to move the cursor to the line of code that caused the warning in the Visual Studio code editor. Or, press Enter on the selected warning. +Double-click a warning to move the cursor to the line of code that caused the warning in the code editor. Or, press Enter on the selected warning. After you understand the problem, you can resolve it in your code. Then, rerun code analysis to make sure that the warning no longer appears in the Error List. @@ -128,4 +128,4 @@ You can search long lists of warning messages and you can filter warnings in mul ## See also -- [Code analysis for C/C++](../code-quality/code-analysis-for-c-cpp-overview.md) +- [Code analysis for C/C++](code-analysis-for-c-cpp-overview.md) diff --git a/docs/code-quality/toc.yml b/docs/code-quality/toc.yml index d487a2fd3d..61bafc57ca 100644 --- a/docs/code-quality/toc.yml +++ b/docs/code-quality/toc.yml @@ -6,6 +6,8 @@ items: href: ../code-quality/code-analysis-for-c-cpp-overview.md - name: Quickstart href: ../code-quality/quick-start-code-analysis-for-c-cpp.md +- name: Build reliable and secure programs + href: ../code-quality/build-reliable-secure-programs.md - name: Analyze C/C++ code for defects href: ../code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md - name: Sample project @@ -39,787 +41,865 @@ items: href: ../code-quality/intrinsic-functions.md - name: Best practices and examples (SAL) href: ../code-quality/best-practices-and-examples-sal.md -- name: Specify additional code information by using _Analysis_assume_ +- name: Specify more code information by using _Analysis_assume_ href: ../code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md - name: C++ Core Guidelines checker warnings items: - name: Overview displayName: "C++ core guidelines checker warnings" href: ../code-quality/code-analysis-for-cpp-corecheck.md - - name: C26400 + - name: Warning C26400 href: ../code-quality/c26400.md - - name: C26401 + - name: Warning C26401 href: ../code-quality/c26401.md - - name: C26402 + - name: Warning C26402 href: ../code-quality/c26402.md - - name: C26403 + - name: Warning C26403 href: ../code-quality/c26403.md - - name: C26404 + - name: Warning C26404 href: ../code-quality/c26404.md - - name: C26405 + - name: Warning C26405 href: ../code-quality/c26405.md - - name: C26406 + - name: Warning C26406 href: ../code-quality/c26406.md - - name: C26407 + - name: Warning C26407 href: ../code-quality/c26407.md - - name: C26408 + - name: Warning C26408 href: ../code-quality/c26408.md - - name: C26409 + - name: Warning C26409 href: ../code-quality/c26409.md - - name: C26410 + - name: Warning C26410 href: ../code-quality/c26410.md - - name: C26411 + - name: Warning C26411 href: ../code-quality/c26411.md - - name: C26414 + - name: Warning C26414 href: ../code-quality/c26414.md - - name: C26415 + - name: Warning C26415 href: ../code-quality/c26415.md - - name: C26416 + - name: Warning C26416 href: ../code-quality/c26416.md - - name: C26417 + - name: Warning C26417 href: ../code-quality/c26417.md - - name: C26418 + - name: Warning C26418 href: ../code-quality/c26418.md - - name: C26426 + - name: Warning C26426 href: ../code-quality/c26426.md - - name: C26427 + - name: Warning C26427 href: ../code-quality/c26427.md - - name: C26429 + - name: Warning C26429 href: ../code-quality/c26429.md - - name: C26430 + - name: Warning C26430 href: ../code-quality/c26430.md - - name: C26431 + - name: Warning C26431 href: ../code-quality/c26431.md - - name: C26432 + - name: Warning C26432 href: ../code-quality/c26432.md - - name: C26433 + - name: Warning C26433 href: ../code-quality/c26433.md - - name: C26434 + - name: Warning C26434 href: ../code-quality/c26434.md - - name: C26435 + - name: Warning C26435 href: ../code-quality/c26435.md - - name: C26436 + - name: Warning C26436 href: ../code-quality/c26436.md - - name: C26437 + - name: Warning C26437 href: ../code-quality/c26437.md - - name: C26438 + - name: Warning C26438 href: ../code-quality/c26438.md - - name: C26439 + - name: Warning C26439 href: ../code-quality/c26439.md - - name: C26440 + - name: Warning C26440 href: ../code-quality/c26440.md - - name: C26441 + - name: Warning C26441 href: ../code-quality/c26441.md - - name: C26443 + - name: Warning C26443 href: ../code-quality/c26443.md - - name: C26444 + - name: Warning C26444 href: ../code-quality/c26444.md - - name: C26445 + - name: Warning C26445 href: ../code-quality/c26445.md - - name: C26446 + - name: Warning C26446 href: ../code-quality/c26446.md - - name: C26447 + - name: Warning C26447 href: ../code-quality/c26447.md - - name: C26448 + - name: Warning C26448 href: ../code-quality/c26448.md - - name: C26449 + - name: Warning C26449 href: ../code-quality/c26449.md - - name: C26450 + - name: Warning C26450 href: ../code-quality/c26450.md - - name: C26451 + - name: Warning C26451 href: ../code-quality/c26451.md - - name: C26452 + - name: Warning C26452 href: ../code-quality/c26452.md - - name: C26453 + - name: Warning C26453 href: ../code-quality/c26453.md - - name: C26454 + - name: Warning C26454 href: ../code-quality/c26454.md - - name: C26455 + - name: Warning C26455 href: ../code-quality/c26455.md - - name: C26456 + - name: Warning C26456 href: ../code-quality/c26456.md - - name: C26457 + - name: Warning C26457 href: ../code-quality/c26457.md - - name: C26460 + - name: Warning C26459 + href: ../code-quality/c26459.md + - name: Warning C26460 href: ../code-quality/c26460.md - - name: C26461 + - name: Warning C26461 href: ../code-quality/c26461.md - - name: C26462 + - name: Warning C26462 href: ../code-quality/c26462.md - - name: C26463 + - name: Warning C26463 href: ../code-quality/c26463.md - - name: C26464 + - name: Warning C26464 href: ../code-quality/c26464.md - - name: C26465 + - name: Warning C26465 href: ../code-quality/c26465.md - - name: C26466 + - name: Warning C26466 href: ../code-quality/c26466.md - - name: C26471 + - name: Warning C26471 href: ../code-quality/c26471.md - - name: C26472 + - name: Warning C26472 href: ../code-quality/c26472.md - - name: C26473 + - name: Warning C26473 href: ../code-quality/c26473.md - - name: C26474 + - name: Warning C26474 href: ../code-quality/c26474.md - - name: C26475 + - name: Warning C26475 href: ../code-quality/c26475.md - - name: C26476 + - name: Warning C26476 href: ../code-quality/c26476.md - - name: C26477 + - name: Warning C26477 href: ../code-quality/c26477.md - - name: C26478 + - name: Warning C26478 href: ../code-quality/c26478.md - - name: C26481 + - name: Warning C26479 + href: ../code-quality/c26479.md + - name: Warning C26481 href: ../code-quality/c26481.md - - name: C26482 + - name: Warning C26482 href: ../code-quality/c26482.md - - name: C26483 + - name: Warning C26483 href: ../code-quality/c26483.md - - name: C26485 + - name: Warning C26485 href: ../code-quality/c26485.md - - name: C26486 + - name: Warning C26486 href: ../code-quality/c26486.md - - name: C26487 + - name: Warning C26487 href: ../code-quality/c26487.md - - name: C26488 + - name: Warning C26488 href: ../code-quality/c26488.md - - name: C26489 + - name: Warning C26489 href: ../code-quality/c26489.md - - name: C26490 + - name: Warning C26490 href: ../code-quality/c26490.md - - name: C26491 + - name: Warning C26491 href: ../code-quality/c26491.md - - name: C26492 + - name: Warning C26492 href: ../code-quality/c26492.md - - name: C26493 + - name: Warning C26493 href: ../code-quality/c26493.md - - name: C26494 + - name: Warning C26494 href: ../code-quality/c26494.md - - name: C26495 + - name: Warning C26495 href: ../code-quality/c26495.md - - name: C26496 + - name: Warning C26496 href: ../code-quality/c26496.md - - name: C26497 + - name: Warning C26497 href: ../code-quality/c26497.md - - name: C26498 + - name: Warning C26498 href: ../code-quality/c26498.md - - name: C26812 + - name: Warning C26812 href: ../code-quality/c26812.md - - name: C26814 + - name: Warning C26814 href: ../code-quality/c26814.md - - name: C26815 + - name: Warning C26815 href: ../code-quality/c26815.md - - name: C26816 + - name: Warning C26816 href: ../code-quality/c26816.md - - name: C26817 + - name: Warning C26817 href: ../code-quality/c26817.md - - name: C26818 + - name: Warning C26818 href: ../code-quality/c26818.md - - name: C26819 + - name: Warning C26819 href: ../code-quality/c26819.md - - name: C26820 + - name: Warning C26820 href: ../code-quality/c26820.md - name: C/C++ code analysis warnings items: - name: Overview displayName: "Code analysis warnings" href: ../code-quality/code-analysis-for-c-cpp-warnings.md - - name: C1250 + - name: Fatal error C1250 href: ../code-quality/c1250.md - - name: C1251 + - name: Fatal error C1251 href: ../code-quality/c1251.md - - name: C1252 + - name: Fatal error C1252 href: ../code-quality/c1252.md - - name: C1253 + - name: Fatal error C1253 href: ../code-quality/c1253.md - - name: C1254 + - name: Fatal error C1254 href: ../code-quality/c1254.md - - name: C1255 + - name: Fatal error C1255 href: ../code-quality/c1255.md - - name: C1256 + - name: Fatal error C1256 href: ../code-quality/c1256.md - - name: C1257 + - name: Fatal error C1257 href: ../code-quality/c1257.md - - name: C6001 + - name: Fatal error C1258 + href: ../code-quality/c1258.md + - name: Fatal error C1259 + href: ../code-quality/c1259.md + - name: Fatal error C1260 + href: ../code-quality/c1260.md + - name: Warning C6001 href: ../code-quality/c6001.md - - name: C6011 + - name: Warning C6011 href: ../code-quality/c6011.md - - name: C6014 + - name: Warning C6014 href: ../code-quality/c6014.md - - name: C6029 + - name: Warning C6029 href: ../code-quality/c6029.md - - name: C6031 + - name: Warning C6030 + href: ../code-quality/c6030.md + - name: Warning C6031 href: ../code-quality/c6031.md - - name: C6053 + - name: Warning C6053 href: ../code-quality/c6053.md - - name: C6054 + - name: Warning C6054 href: ../code-quality/c6054.md - - name: C6059 + - name: Warning C6059 href: ../code-quality/c6059.md - - name: C6063 + - name: Warning C6063 href: ../code-quality/c6063.md - - name: C6064 + - name: Warning C6064 href: ../code-quality/c6064.md - - name: C6066 + - name: Warning C6065 + href: ../code-quality/c6065.md + - name: Warning C6066 href: ../code-quality/c6066.md - - name: C6067 + - name: Warning C6067 href: ../code-quality/c6067.md - - name: C6101 + - name: Warning C6101 href: ../code-quality/c6101.md - - name: C6102 + - name: Warning C6102 href: ../code-quality/c6102.md - - name: C6103 + - name: Warning C6103 href: ../code-quality/c6103.md - - name: C6200 + - name: Warning C6200 href: ../code-quality/c6200.md - - name: C6201 + - name: Warning C6201 href: ../code-quality/c6201.md - - name: C6211 + - name: Warning C6211 href: ../code-quality/c6211.md - - name: C6214 + - name: Warning C6214 href: ../code-quality/c6214.md - - name: C6215 + - name: Warning C6215 href: ../code-quality/c6215.md - - name: C6216 + - name: Warning C6216 href: ../code-quality/c6216.md - - name: C6217 + - name: Warning C6217 href: ../code-quality/c6217.md - - name: C6219 + - name: Warning C6219 href: ../code-quality/c6219.md - - name: C6220 + - name: Warning C6220 href: ../code-quality/c6220.md - - name: C6221 + - name: Warning C6221 href: ../code-quality/c6221.md - - name: C6225 + - name: Warning C6225 href: ../code-quality/c6225.md - - name: C6226 + - name: Warning C6226 href: ../code-quality/c6226.md - - name: C6230 + - name: Warning C6230 href: ../code-quality/c6230.md - - name: C6235 + - name: Warning C6235 href: ../code-quality/c6235.md - - name: C6236 + - name: Warning C6236 href: ../code-quality/c6236.md - - name: C6237 + - name: Warning C6237 href: ../code-quality/c6237.md - - name: C6239 + - name: Warning C6239 href: ../code-quality/c6239.md - - name: C6240 + - name: Warning C6240 href: ../code-quality/c6240.md - - name: C6242 + - name: Warning C6242 href: ../code-quality/c6242.md - - name: C6244 + - name: Warning C6244 href: ../code-quality/c6244.md - - name: C6246 + - name: Warning C6246 href: ../code-quality/c6246.md - - name: C6248 + - name: Warning C6248 href: ../code-quality/c6248.md - - name: C6250 + - name: Warning C6250 href: ../code-quality/c6250.md - - name: C6255 + - name: Warning C6255 href: ../code-quality/c6255.md - - name: C6258 + - name: Warning C6258 href: ../code-quality/c6258.md - - name: C6259 + - name: Warning C6259 href: ../code-quality/c6259.md - - name: C6260 + - name: Warning C6260 href: ../code-quality/c6260.md - - name: C6262 + - name: Warning C6262 href: ../code-quality/c6262.md - - name: C6263 + - name: Warning C6263 href: ../code-quality/c6263.md - - name: C6268 + - name: Warning C6268 href: ../code-quality/c6268.md - - name: C6269 + - name: Warning C6269 href: ../code-quality/c6269.md - - name: C6270 + - name: Warning C6270 href: ../code-quality/c6270.md - - name: C6271 + - name: Warning C6271 href: ../code-quality/c6271.md - - name: C6272 + - name: Warning C6272 href: ../code-quality/c6272.md - - name: C6273 + - name: Warning C6273 href: ../code-quality/c6273.md - - name: C6274 + - name: Warning C6274 href: ../code-quality/c6274.md - - name: C6276 + - name: Warning C6276 href: ../code-quality/c6276.md - - name: C6277 + - name: Warning C6277 href: ../code-quality/c6277.md - - name: C6278 + - name: Warning C6278 href: ../code-quality/c6278.md - - name: C6279 + - name: Warning C6279 href: ../code-quality/c6279.md - - name: C6280 + - name: Warning C6280 href: ../code-quality/c6280.md - - name: C6281 + - name: Warning C6281 href: ../code-quality/c6281.md - - name: C6282 + - name: Warning C6282 href: ../code-quality/c6282.md - - name: C6283 + - name: Warning C6283 href: ../code-quality/c6283.md - - name: C6284 + - name: Warning C6284 href: ../code-quality/c6284.md - - name: C6285 + - name: Warning C6285 href: ../code-quality/c6285.md - - name: C6286 + - name: Warning C6286 href: ../code-quality/c6286.md - - name: C6287 + - name: Warning C6287 href: ../code-quality/c6287.md - - name: C6288 + - name: Warning C6288 href: ../code-quality/c6288.md - - name: C6289 + - name: Warning C6289 href: ../code-quality/c6289.md - - name: C6290 + - name: Warning C6290 href: ../code-quality/c6290.md - - name: C6291 + - name: Warning C6291 href: ../code-quality/c6291.md - - name: C6292 + - name: Warning C6292 href: ../code-quality/c6292.md - - name: C6293 + - name: Warning C6293 href: ../code-quality/c6293.md - - name: C6294 + - name: Warning C6294 href: ../code-quality/c6294.md - - name: C6295 + - name: Warning C6295 href: ../code-quality/c6295.md - - name: C6296 + - name: Warning C6296 href: ../code-quality/c6296.md - - name: C6297 + - name: Warning C6297 href: ../code-quality/c6297.md - - name: C6298 + - name: Warning C6298 href: ../code-quality/c6298.md - - name: C6299 + - name: Warning C6299 href: ../code-quality/c6299.md - - name: C6302 + - name: Warning C6302 href: ../code-quality/c6302.md - - name: C6303 + - name: Warning C6303 href: ../code-quality/c6303.md - - name: C6305 + - name: Warning C6305 href: ../code-quality/c6305.md - - name: C6306 + - name: Warning C6306 href: ../code-quality/c6306.md - - name: C6308 + - name: Warning C6308 href: ../code-quality/c6308.md - - name: C6310 + - name: Warning C6310 href: ../code-quality/c6310.md - - name: C6312 + - name: Warning C6312 href: ../code-quality/c6312.md - - name: C6313 + - name: Warning C6313 href: ../code-quality/c6313.md - - name: C6314 + - name: Warning C6314 href: ../code-quality/c6314.md - - name: C6315 + - name: Warning C6315 href: ../code-quality/c6315.md - - name: C6316 + - name: Warning C6316 href: ../code-quality/c6316.md - - name: C6317 + - name: Warning C6317 href: ../code-quality/c6317.md - - name: C6318 + - name: Warning C6318 href: ../code-quality/c6318.md - - name: C6319 + - name: Warning C6319 href: ../code-quality/c6319.md - - name: C6320 + - name: Warning C6320 href: ../code-quality/c6320.md - - name: C6322 + - name: Warning C6322 href: ../code-quality/c6322.md - - name: C6323 + - name: Warning C6323 href: ../code-quality/c6323.md - - name: C6324 + - name: Warning C6324 href: ../code-quality/c6324.md - - name: C6326 + - name: Warning C6326 href: ../code-quality/c6326.md - - name: C6328 + - name: Warning C6328 href: ../code-quality/c6328.md - - name: C6329 + - name: Warning C6329 href: ../code-quality/c6329.md - - name: C6330 + - name: Warning C6330 href: ../code-quality/c6330.md - - name: C6331 + - name: Warning C6331 href: ../code-quality/c6331.md - - name: C6332 + - name: Warning C6332 href: ../code-quality/c6332.md - - name: C6333 + - name: Warning C6333 href: ../code-quality/c6333.md - - name: C6334 + - name: Warning C6334 href: ../code-quality/c6334.md - - name: C6335 + - name: Warning C6335 href: ../code-quality/c6335.md - - name: C6336 + - name: Warning C6336 href: ../code-quality/c6336.md - - name: C6340 + - name: Warning C6340 href: ../code-quality/c6340.md - - name: C6381 + - name: Warning C6381 href: ../code-quality/c6381.md - - name: C6383 + - name: Warning C6383 href: ../code-quality/c6383.md - - name: C6384 + - name: Warning C6384 href: ../code-quality/c6384.md - - name: C6385 + - name: Warning C6385 href: ../code-quality/c6385.md - - name: C6386 + - name: Warning C6386 href: ../code-quality/c6386.md - - name: C6387 + - name: Warning C6387 href: ../code-quality/c6387.md - - name: C6388 + - name: Warning C6388 href: ../code-quality/c6388.md - - name: C6389 + - name: Warning C6389 href: ../code-quality/c6389.md - - name: C6400 + - name: Warning C6390 + href: ../code-quality/c6390.md + - name: Warning C6392 + href: ../code-quality/c6392.md + - name: Warning C6393 + href: ../code-quality/c6393.md + - name: Warning C6394 + href: ../code-quality/c6394.md + - name: Warning C6395 + href: ../code-quality/c6395.md + - name: Warning C6396 + href: ../code-quality/c6396.md + - name: Warning C6397 + href: ../code-quality/c6397.md + - name: Warning C6398 + href: ../code-quality/c6398.md + - name: Warning C6400 href: ../code-quality/c6400.md - - name: C6401 + - name: Warning C6401 href: ../code-quality/c6401.md - - name: C6411 + - name: Warning C6411 href: ../code-quality/c6411.md - - name: C6412 + - name: Warning C6412 href: ../code-quality/c6412.md - - name: C6500 + - name: Warning C6500 href: ../code-quality/c6500.md - - name: C6501 + - name: Warning C6501 href: ../code-quality/c6501.md - - name: C6503 + - name: Warning C6503 href: ../code-quality/c6503.md - - name: C6504 + - name: Warning C6504 href: ../code-quality/c6504.md - - name: C6505 + - name: Warning C6505 href: ../code-quality/c6505.md - - name: C6506 + - name: Warning C6506 href: ../code-quality/c6506.md - - name: C6508 + - name: Warning C6508 href: ../code-quality/c6508.md - - name: C6509 + - name: Warning C6509 href: ../code-quality/c6509.md - - name: C6510 + - name: Warning C6510 href: ../code-quality/c6510.md - - name: C6511 + - name: Warning C6511 href: ../code-quality/c6511.md - - name: C6513 + - name: Warning C6513 href: ../code-quality/c6513.md - - name: C6514 + - name: Warning C6514 href: ../code-quality/c6514.md - - name: C6515 + - name: Warning C6515 href: ../code-quality/c6515.md - - name: C6516 + - name: Warning C6516 href: ../code-quality/c6516.md - - name: C6517 + - name: Warning C6517 href: ../code-quality/c6517.md - - name: C6518 + - name: Warning C6518 href: ../code-quality/c6518.md - - name: C6522 + - name: Warning C6522 href: ../code-quality/c6522.md - - name: C6525 + - name: Warning C6525 href: ../code-quality/c6525.md - - name: C6527 + - name: Warning C6527 href: ../code-quality/c6527.md - - name: C6530 + - name: Warning C6530 href: ../code-quality/c6530.md - - name: C6540 + - name: Warning C6540 href: ../code-quality/c6540.md - - name: C6551 + - name: Warning C6551 href: ../code-quality/c6551.md - - name: C6552 + - name: Warning C6552 href: ../code-quality/c6552.md - - name: C6701 + - name: Warning C6701 href: ../code-quality/c6701.md - - name: C6702 + - name: Warning C6702 href: ../code-quality/c6702.md - - name: C6703 + - name: Warning C6703 href: ../code-quality/c6703.md - - name: C6704 + - name: Warning C6704 href: ../code-quality/c6704.md - - name: C6705 + - name: Warning C6705 href: ../code-quality/c6705.md - - name: C6706 + - name: Warning C6706 href: ../code-quality/c6706.md - - name: C6707 + - name: Warning C6707 href: ../code-quality/c6707.md - - name: C6993 + - name: Warning C6993 href: ../code-quality/c6993.md - - name: C6995 + - name: Warning C6995 href: ../code-quality/c6995.md - - name: C6997 + - name: Warning C6997 href: ../code-quality/c6997.md - - name: C26100 + - name: Warning C26100 href: ../code-quality/c26100.md - - name: C26101 + - name: Warning C26101 href: ../code-quality/c26101.md - - name: C26105 + - name: Warning C26105 href: ../code-quality/c26105.md - - name: C26110 + - name: Warning C26110 href: ../code-quality/c26110.md - - name: C26111 + - name: Warning C26111 href: ../code-quality/c26111.md - - name: C26112 + - name: Warning C26112 href: ../code-quality/c26112.md - - name: C26115 + - name: Warning C26115 href: ../code-quality/c26115.md - - name: C26116 + - name: Warning C26116 href: ../code-quality/c26116.md - - name: C26117 + - name: Warning C26117 href: ../code-quality/c26117.md - - name: C26130 + - name: Warning C26130 href: ../code-quality/c26130.md - - name: C26135 + - name: Warning C26132 + href: c26132.md + - name: Warning C26133 + href: c26133.md + - name: Warning C26135 href: ../code-quality/c26135.md - - name: C26138 + - name: Warning C26138 href: ../code-quality/c26138.md - - name: C26140 + - name: Warning C26140 href: ../code-quality/c26140.md - - name: C26160 + - name: Warning C26160 href: ../code-quality/c26160.md - - name: C26165 + - name: Warning C26165 href: ../code-quality/c26165.md - - name: C26166 + - name: Warning C26166 href: ../code-quality/c26166.md - - name: C26167 + - name: Warning C26167 href: ../code-quality/c26167.md - - name: C26800 + - name: Warning C26800 href: ../code-quality/c26800.md - - name: C26810 + - name: Warning C26810 href: ../code-quality/c26810.md - - name: C26811 + - name: Warning C26811 href: ../code-quality/c26811.md - - name: C26826 + - name: Warning C26813 + href: ../code-quality/c26813.md + - name: Warning C26822 + href: ../code-quality/c26822.md + - name: Warning C26823 + href: ../code-quality/c26823.md + - name: Warning C26824 + href: ../code-quality/c26824.md + - name: Warning C26825 + href: ../code-quality/c26825.md + - name: Warning C26826 href: ../code-quality/c26826.md - - name: C28020 + - name: Warning C26827 + href: ../code-quality/c26827.md + - name: Warning C26828 + href: ../code-quality/c26828.md + - name: Warning C26829 + href: ../code-quality/c26829.md + - name: Warning C26830 + href: ../code-quality/c26830.md + - name: Warning C26831 + href: ../code-quality/c26831.md + - name: Warning C26838 + href: ../code-quality/c26838.md + - name: Warning C26839 + href: ../code-quality/c26839.md + - name: Warning C26832 + href: ../code-quality/c26832.md + - name: Warning C26833 + href: ../code-quality/c26833.md + - name: Warning C26835 + href: ../code-quality/c26835.md + - name: Warning C26837 + href: ../code-quality/c26837.md + - name: Warning C26859 + href: ../code-quality/c26859.md + - name: Warning C26860 + href: ../code-quality/c26860.md + - name: Warning C26861 + href: ../code-quality/c26861.md + - name: Warning C26862 + href: ../code-quality/c26862.md + - name: Warning C26863 + href: ../code-quality/c26863.md + - name: Warning C26864 + href: ../code-quality/c26864.md + - name: Warning C28020 href: ../code-quality/c28020.md - - name: C28021 + - name: Warning C28021 href: ../code-quality/c28021.md - - name: C28022 + - name: Warning C28022 href: ../code-quality/c28022.md - - name: C28023 + - name: Warning C28023 href: ../code-quality/c28023.md - - name: C28024 + - name: Warning C28024 href: ../code-quality/c28024.md - - name: C28039 + - name: Warning C28039 href: ../code-quality/c28039.md - - name: C28103 + - name: Warning C28103 href: ../code-quality/c28103.md - - name: C28104 + - name: Warning C28104 href: ../code-quality/c28104.md - - name: C28105 + - name: Warning C28105 href: ../code-quality/c28105.md - - name: C28106 + - name: Warning C28106 href: ../code-quality/c28106.md - - name: C28107 + - name: Warning C28107 href: ../code-quality/c28107.md - - name: C28108 + - name: Warning C28108 href: ../code-quality/c28108.md - - name: C28109 + - name: Warning C28109 href: ../code-quality/c28109.md - - name: C28112 + - name: Warning C28112 href: ../code-quality/c28112.md - - name: C28113 + - name: Warning C28113 href: ../code-quality/c28113.md - - name: C28125 + - name: Warning C28125 href: ../code-quality/c28125.md - - name: C28137 + - name: Warning C28137 href: ../code-quality/c28137.md - - name: C28138 + - name: Warning C28138 href: ../code-quality/c28138.md - - name: C28159 + - name: Warning C28159 href: ../code-quality/c28159.md - - name: C28160 + - name: Warning C28160 href: ../code-quality/c28160.md - - name: C28163 + - name: Warning C28163 href: ../code-quality/c28163.md - - name: C28164 + - name: Warning C28164 href: ../code-quality/c28164.md - - name: C28182 + - name: Warning C28182 href: ../code-quality/c28182.md - - name: C28183 + - name: Warning C28183 href: ../code-quality/c28183.md - - name: C28193 + - name: Warning C28193 href: ../code-quality/c28193.md - - name: C28194 + - name: Warning C28194 href: ../code-quality/c28194.md - - name: C28195 + - name: Warning C28195 href: ../code-quality/c28195.md - - name: C28196 + - name: Warning C28196 href: ../code-quality/c28196.md - - name: C28197 + - name: Warning C28197 href: ../code-quality/c28197.md - - name: C28198 + - name: Warning C28198 href: ../code-quality/c28198.md - - name: C28199 + - name: Warning C28199 href: ../code-quality/c28199.md - - name: C28202 + - name: Warning C28202 href: ../code-quality/c28202.md - - name: C28203 + - name: Warning C28203 href: ../code-quality/c28203.md - - name: C28204 + - name: Warning C28204 href: ../code-quality/c28204.md - - name: C28205 + - name: Warning C28205 href: ../code-quality/c28205.md - - name: C28206 + - name: Warning C28206 href: ../code-quality/c28206.md - - name: C28207 + - name: Warning C28207 href: ../code-quality/c28207.md - - name: C28208 + - name: Warning C28208 href: ../code-quality/c28208.md - - name: C28209 + - name: Warning C28209 href: ../code-quality/c28209.md - - name: C28210 + - name: Warning C28210 href: ../code-quality/c28210.md - - name: C28211 + - name: Warning C28211 href: ../code-quality/c28211.md - - name: C28212 + - name: Warning C28212 href: ../code-quality/c28212.md - - name: C28213 + - name: Warning C28213 href: ../code-quality/c28213.md - - name: C28214 + - name: Warning C28214 href: ../code-quality/c28214.md - - name: C28215 + - name: Warning C28215 href: ../code-quality/c28215.md - - name: C28216 + - name: Warning C28216 href: ../code-quality/c28216.md - - name: C28217 + - name: Warning C28217 href: ../code-quality/c28217.md - - name: C28218 + - name: Warning C28218 href: ../code-quality/c28218.md - - name: C28219 + - name: Warning C28219 href: ../code-quality/c28219.md - - name: C28220 + - name: Warning C28220 href: ../code-quality/c28220.md - - name: C28221 + - name: Warning C28221 href: ../code-quality/c28221.md - - name: C28222 + - name: Warning C28222 href: ../code-quality/c28222.md - - name: C28223 + - name: Warning C28223 href: ../code-quality/c28223.md - - name: C28224 + - name: Warning C28224 href: ../code-quality/c28224.md - - name: C28225 + - name: Warning C28225 href: ../code-quality/c28225.md - - name: C28226 + - name: Warning C28226 href: ../code-quality/c28226.md - - name: C28227 + - name: Warning C28227 href: ../code-quality/c28227.md - - name: C28228 + - name: Warning C28228 href: ../code-quality/c28228.md - - name: C28229 + - name: Warning C28229 href: ../code-quality/c28229.md - - name: C28230 + - name: Warning C28230 href: ../code-quality/c28230.md - - name: C28231 + - name: Warning C28231 href: ../code-quality/c28231.md - - name: C28232 + - name: Warning C28232 href: ../code-quality/c28232.md - - name: C28233 + - name: Warning C28233 href: ../code-quality/c28233.md - - name: C28234 + - name: Warning C28234 href: ../code-quality/c28234.md - - name: C28235 + - name: Warning C28235 href: ../code-quality/c28235.md - - name: C28236 + - name: Warning C28236 href: ../code-quality/c28236.md - - name: C28237 + - name: Warning C28237 href: ../code-quality/c28237.md - - name: C28238 + - name: Warning C28238 href: ../code-quality/c28238.md - - name: C28239 + - name: Warning C28239 href: ../code-quality/c28239.md - - name: C28240 + - name: Warning C28240 href: ../code-quality/c28240.md - - name: C28241 + - name: Warning C28241 href: ../code-quality/c28241.md - - name: C28243 + - name: Warning C28243 href: ../code-quality/c28243.md - - name: C28244 + - name: Warning C28244 href: ../code-quality/c28244.md - - name: C28245 + - name: Warning C28245 href: ../code-quality/c28245.md - - name: C28246 + - name: Warning C28246 href: ../code-quality/c28246.md - - name: C28250 + - name: Warning C28250 href: ../code-quality/c28250.md - - name: C28251 + - name: Warning C28251 href: ../code-quality/c28251.md - - name: C28252 + - name: Warning C28252 href: ../code-quality/c28252.md - - name: C28253 + - name: Warning C28253 href: ../code-quality/c28253.md - - name: C28254 + - name: Warning C28254 href: ../code-quality/c28254.md - - name: C28262 + - name: Warning C28262 href: ../code-quality/c28262.md - - name: C28263 + - name: Warning C28263 href: ../code-quality/c28263.md - - name: C28267 + - name: Warning C28267 href: ../code-quality/c28267.md - - name: C28272 + - name: Warning C28272 href: ../code-quality/c28272.md - - name: C28273 + - name: Warning C28273 href: ../code-quality/c28273.md - - name: C28275 + - name: Warning C28275 href: ../code-quality/c28275.md - - name: C28278 + - name: Warning C28278 href: ../code-quality/c28278.md - - name: C28279 + - name: Warning C28279 href: ../code-quality/c28279.md - - name: C28280 + - name: Warning C28280 href: ../code-quality/c28280.md - - name: C28282 + - name: Warning C28282 href: ../code-quality/c28282.md - - name: C28283 + - name: Warning C28283 href: ../code-quality/c28283.md - - name: C28284 + - name: Warning C28284 href: ../code-quality/c28284.md - - name: C28285 + - name: Warning C28285 href: ../code-quality/c28285.md - - name: C28286 + - name: Warning C28286 href: ../code-quality/c28286.md - - name: C28287 + - name: Warning C28287 href: ../code-quality/c28287.md - - name: C28288 + - name: Warning C28288 href: ../code-quality/c28288.md - - name: C28289 + - name: Warning C28289 href: ../code-quality/c28289.md - - name: C28290 + - name: Warning C28290 href: ../code-quality/c28290.md - - name: C28291 + - name: Warning C28291 href: ../code-quality/c28291.md - - name: C28300 + - name: Warning C28300 href: ../code-quality/c28300.md - - name: C28301 + - name: Warning C28301 href: ../code-quality/c28301.md - - name: C28302 + - name: Warning C28302 href: ../code-quality/c28302.md - - name: C28303 + - name: Warning C28303 href: ../code-quality/c28303.md - - name: C28304 + - name: Warning C28304 href: ../code-quality/c28304.md - - name: C28305 + - name: Warning C28305 href: ../code-quality/c28305.md - - name: C28306 + - name: Warning C28306 href: ../code-quality/c28306.md - - name: C28307 + - name: Warning C28307 href: ../code-quality/c28307.md - - name: C28308 + - name: Warning C28308 href: ../code-quality/c28308.md - - name: C28309 + - name: Warning C28309 href: ../code-quality/c28309.md - - name: C28310 + - name: Warning C28310 href: ../code-quality/c28310.md - - name: C28311 + - name: Warning C28311 href: ../code-quality/c28311.md - - name: C28312 + - name: Warning C28312 href: ../code-quality/c28312.md - - name: C28350 + - name: Warning C28350 href: ../code-quality/c28350.md - - name: C28351 + - name: Warning C28351 href: ../code-quality/c28351.md - - name: C33001 + - name: Warning C33001 href: ../code-quality/c33001.md - - name: C33004 + - name: Warning C33004 href: ../code-quality/c33004.md - - name: C33005 + - name: Warning C33005 href: ../code-quality/c33005.md - - name: C33010 + - name: Warning C33010 href: ../code-quality/c33010.md - - name: C33011 + - name: Warning C33011 href: ../code-quality/c33011.md - - name: C33020 + - name: Warning C33020 href: ../code-quality/c33020.md - - name: C33022 + - name: Warning C33022 href: ../code-quality/c33022.md diff --git a/docs/code-quality/understanding-sal.md b/docs/code-quality/understanding-sal.md index 198aed7335..7e3c30bfd4 100644 --- a/docs/code-quality/understanding-sal.md +++ b/docs/code-quality/understanding-sal.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Understanding SAL" title: Understanding SAL +description: "Learn more about: Understanding SAL" ms.date: 11/04/2016 ms.topic: "conceptual" -ms.assetid: a94d6907-55f2-4874-9571-51d52d6edcfd --- # Understanding SAL @@ -20,7 +19,6 @@ Simply stated, SAL is an inexpensive way to let the compiler check your code for SAL can help you make your code design more understandable, both for humans and for code analysis tools. Consider this example that shows the C runtime function `memcpy`: ```cpp - void * memcpy( void *dest, const void *src, @@ -42,7 +40,6 @@ The documentation contains a couple of bits of information that suggest that you However, the compiler can't read the documentation or informal comments. It doesn't know that there is a relationship between the two buffers and `count`, and it also can't effectively guess about a relationship. SAL could provide more clarity about the properties and implementation of the function, as shown here: ```cpp - void * memcpy( _Out_writes_bytes_all_(count) void *dest, _In_reads_bytes_(count) const void *src, @@ -53,7 +50,6 @@ void * memcpy( Notice that these annotations resemble the information in the documentation, but they are more concise and they follow a semantic pattern. When you read this code, you can quickly understand the properties of this function and how to avoid buffer overrun security issues. Even better, the semantic patterns that SAL provides can improve the efficiency and effectiveness of automated code analysis tools in the early discovery of potential bugs. Imagine that someone writes this buggy implementation of `wmemcpy`: ```cpp - wchar_t * wmemcpy( _Out_writes_all_(count) wchar_t *dest, _In_reads_(count) const wchar_t *src, @@ -97,9 +93,9 @@ These annotations help identify possible uninitialized values and invalid null p This section shows code examples for the basic SAL annotations. -### Using the Visual Studio Code Analysis Tool to Find Defects +### Using the Visual Studio code analysis tool to find defects -In the examples, the Visual Studio Code Analysis tool is used together with SAL annotations to find code defects. Here's how to do that. +In the examples, the Visual Studio code analysis tool is used together with SAL annotations to find code defects. Here's how to do that. #### To use Visual Studio code analysis tools and SAL @@ -148,14 +144,13 @@ void BadInCaller() } ``` -If you use Visual Studio Code Analysis on this example, it validates that the callers pass a non-Null pointer to an initialized buffer for `pInt`. In this case, `pInt` pointer cannot be NULL. +If you use Visual Studio code analysis on this example, it validates that the callers pass a non-Null pointer to an initialized buffer for `pInt`. In this case, `pInt` pointer cannot be NULL. ### Example: The \_In\_opt\_ Annotation `_In_opt_` is the same as `_In_`, except that the input parameter is allowed to be NULL and, therefore, the function should check for this. ```cpp - void GoodInOptCallee(_In_opt_ int *pInt) { if(pInt != NULL) { @@ -176,7 +171,7 @@ void InOptCaller() } ``` -Visual Studio Code Analysis validates that the function checks for NULL before it accesses the buffer. +Visual Studio code analysis validates that the function checks for NULL before it accesses the buffer. ### Example: The \_Out\_ Annotation @@ -202,7 +197,7 @@ void OutCaller() } ``` -Visual Studio Code Analysis Tool validates that the caller passes a non-NULL pointer to a buffer for `pInt` and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that the caller passes a non-NULL pointer to a buffer for `pInt` and that the buffer is initialized by the function before it returns. ### Example: The \_Out\_opt\_ Annotation @@ -229,7 +224,7 @@ void OutOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before `pInt` is dereferenced, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before `pInt` is dereferenced, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. ### Example: The \_Inout\_ Annotation @@ -260,7 +255,7 @@ void BadInOutCaller() } ``` -Visual Studio Code Analysis validates that callers pass a non-NULL pointer to an initialized buffer for `pInt`, and that, before return, `pInt` is still non-NULL and the buffer is initialized. +Visual Studio code analysis validates that callers pass a non-NULL pointer to an initialized buffer for `pInt`, and that, before return, `pInt` is still non-NULL and the buffer is initialized. ### Example: The \_Inout\_opt\_ Annotation @@ -289,7 +284,7 @@ void InOutOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before it accesses the buffer, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before it accesses the buffer, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. ### Example: The \_Outptr\_ Annotation @@ -319,7 +314,7 @@ void OutPtrCaller() } ``` -Visual Studio Code Analysis validates that the caller passes a non-NULL pointer for `*pInt`, and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that the caller passes a non-NULL pointer for `*pInt`, and that the buffer is initialized by the function before it returns. ### Example: The \_Outptr\_opt\_ Annotation @@ -351,7 +346,7 @@ void OutPtrOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before `*pInt` is dereferenced, and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before `*pInt` is dereferenced, and that the buffer is initialized by the function before it returns. ### Example: The \_Success\_ Annotation in Combination with \_Out\_ @@ -370,7 +365,7 @@ bool GetValue(_Out_ int *pInt, bool flag) } ``` -The `_Out_` annotation causes Visual Studio Code Analysis to validate that the caller passes a non-NULL pointer to a buffer for `pInt`, and that the buffer is initialized by the function before it returns. +The `_Out_` annotation causes Visual Studio code analysis to validate that the caller passes a non-NULL pointer to a buffer for `pInt`, and that the buffer is initialized by the function before it returns. ## SAL Best Practice @@ -388,7 +383,7 @@ Here are some guidelines: - Annotate value-range annotations so that Code Analysis can ensure buffer and pointer safety. -- Annotate locking rules and locking side effects. For more information, see [Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md). +- Annotate locking rules and locking side effects. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md). - Annotate driver properties and other domain-specific properties. @@ -396,10 +391,10 @@ Or you can annotate all parameters to make your intent clear throughout and to m ## See also -- [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [Annotating Function Parameters and Return Values](../code-quality/annotating-function-parameters-and-return-values.md) -- [Annotating Function Behavior](../code-quality/annotating-function-behavior.md) -- [Annotating Structs and Classes](../code-quality/annotating-structs-and-classes.md) -- [Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md) -- [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md) -- [Best Practices and Examples](../code-quality/best-practices-and-examples-sal.md) +- [Using SAL Annotations to Reduce C/C++ Code Defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) +- [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md) +- [Annotating Function Behavior](annotating-function-behavior.md) +- [Annotating Structs and Classes](annotating-structs-and-classes.md) +- [Annotating Locking Behavior](annotating-locking-behavior.md) +- [Specifying When and Where an Annotation Applies](specifying-when-and-where-an-annotation-applies.md) +- [Best Practices and Examples](best-practices-and-examples-sal.md) diff --git a/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md b/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md index 6591618fe1..545b52d184 100644 --- a/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md +++ b/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md @@ -229,7 +229,6 @@ The following ruleset schema describes the XML schema of a ruleset file. The rul - ``` Schema element details: diff --git a/docs/code-quality/using-the-cpp-core-guidelines-checkers.md b/docs/code-quality/using-the-cpp-core-guidelines-checkers.md index 1718eccb48..8ffa7df200 100644 --- a/docs/code-quality/using-the-cpp-core-guidelines-checkers.md +++ b/docs/code-quality/using-the-cpp-core-guidelines-checkers.md @@ -1,7 +1,7 @@ --- title: Using the C++ Core Guidelines checkers description: "How to set up and use the Microsoft C++ Code Analysis rules for C++ Core Guidelines." -ms.date: 12/16/2020 +ms.date: 06/21/2023 ms.topic: "conceptual" dev_langs: - CPP @@ -30,7 +30,7 @@ A subset of C++ Core Check rules is included in the Microsoft Native Recommended ![Property page for Code Analysis General settings.](media/cppcorecheck_codeanalysis_general.png) -To enable additional Core Check rules, open the dropdown list and choose which rule sets you want to include: +To enable more Core Check rules, open the dropdown list and choose which rule sets you want to include: ![Dropdown for additional C++ Core Check rule sets.](media/cppcorecheck_codeanalysis_extensions.png) @@ -49,7 +49,7 @@ A subset of C++ Core Check rules is included in the Microsoft Native Recommended You can also choose to run all the supported C++ Core Check rules, or select your own subset to run: -### To enable additional Core Check rules +### To enable more Core Check rules 1. Open the **Property Pages** dialog for your project. @@ -74,7 +74,7 @@ int main() int arr[10]; // warning C26494 int* p = arr; // warning C26485 - [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1 + [[gsl::suppress("bounds.1", justification : "This attribute suppresses Bounds rules #1")]] { int* q = p + 1; // warning C26481 (suppressed) p = q++; // warning C26481 (suppressed) @@ -104,11 +104,11 @@ c:\users\username\documents\visual studio 2015\projects\corecheckexample\coreche ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ========== ``` -The C++ Core Guidelines are there to help you write better and safer code. However, you may find an instance where a rule or a profile shouldn't be applied. It's easy to suppress it directly in the code. You can use the `[[gsl::suppress]]` attribute to keep C++ Core Check from detecting and reporting any violation of a rule in the following code block. You can mark individual statements to suppress specific rules. You can even suppress the entire bounds profile by writing `[[gsl::suppress(bounds)]]` without including a specific rule number. +The C++ Core Guidelines are there to help you write better and safer code. However, you might find an instance where a rule or a profile shouldn't be applied. It's easy to suppress it directly in the code. You can use the `[[gsl::suppress]]` attribute to keep C++ Core Check from detecting and reporting any violation of a rule in the following code block. You can mark individual statements to suppress specific rules. You can even suppress the entire bounds profile by writing `[[gsl::suppress("bounds")]]` without including a specific rule number. ## Supported rule sets -As new rules are added to the C++ Core Guidelines Checker, the number of warnings that are produced for pre-existing code may increase. You can use predefined rule sets to filter which kinds of rules to enable. You'll find reference articles for most rules under +As new rules are added to the C++ Core Guidelines Checker, the number of warnings that are produced for pre-existing code might increase. You can use predefined rule sets to filter which kinds of rules to enable. You'll find reference articles for most rules under [Visual Studio C++ Core Check Reference](code-analysis-for-cpp-corecheck.md). - **Arithmetic Rules**: Rules to detect arithmetic [overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow), [signed-unsigned operations](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-unsigned), and [bit manipulation](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nonnegative).15.6 @@ -197,19 +197,19 @@ The Microsoft C++ compiler has limited support for the `[[gsl::suppress]]` attri ```cpp // Suppress only warnings from the 'r.11' rule in expression. -[[gsl::suppress(r.11)]] new int; +[[gsl::suppress("r.11")]] new int; // Suppress all warnings from the 'r' rule group (resource management) in block. -[[gsl::suppress(r)]] +[[gsl::suppress("r")]] { new int; } // Suppress only one specific warning number. -// For declarations, you may need to use the surrounding block. +// For declarations, you might need to use the surrounding block. // Macros are not expanded inside of attributes. // Use plain numbers instead of macros from the warnings.h. -[[gsl::suppress(26400)]] +[[gsl::suppress("26400")]] { int *p = new int; } @@ -231,9 +231,9 @@ You can use the command-line option to temporarily disable all code analysis for Sometimes it's useful to do focused code analysis and still use the Visual Studio IDE. Try the following sample scenario for large projects. It can save build time and make it easier to filter results: -1. In the command shell, set the `esp.extension` and `esp.annotationbuildlevel` environment variables. +1. In the command shell, set the `esp.extension` environment variable. -1. To inherit these variables, open Visual Studio from the command shell. +1. To inherit this variable, open Visual Studio from the command shell. 1. Load your project and open its properties. @@ -243,7 +243,7 @@ Sometimes it's useful to do focused code analysis and still use the Visual Studi 1. Choose **Configuration Properties** > **C/C++** > **Command Line** > **Additional Options** and add *`/analyze:plugin EspXEngine.dll`* -1. Disable the use of precompiled header (**Configuration Properties** > **C/C++** > **Precompiled Headers**). It's necessary because the extensions engine may attempt to read its internal information from the precompiled header (PCH). If the PCH was compiled with default project options, it won't be compatible. +1. Disable the use of precompiled header (**Configuration Properties** > **C/C++** > **Precompiled Headers**). It's necessary because the extensions engine might attempt to read its internal information from the precompiled header (PCH). If the PCH was compiled with default project options, it won't be compatible. 1. Rebuild the project. The common PREFast checks should run on all files. Because the C++ Core Guidelines Checker isn't enabled by default, it should only run on the file that's configured to use it. @@ -269,10 +269,6 @@ You can run the C++ Core Checker only on specified files. Use the same approach ```xml - - true - Ignore - true CppCoreCheck.dll @@ -294,7 +290,7 @@ Code Analysis requires a few environment variables and compiler command-line opt - **Environment variables** - `set esp.extensions=cppcorecheck.dll` This tells the engine to load the C++ Core Guidelines module. - - `set esp.annotationbuildlevel=ignore` This disables the logic that processes SAL annotations. Annotations don't affect code analysis in the C++ Core Guidelines Checker, yet their processing takes time (sometimes a long time). This setting is optional, but highly recommended. + - Since Visual Studio 2019 we no longer recommend setting the `esp.annotationbuildlevel` environment variable because setting it can result in false positives. If seeing unexpected results, remove this variable from your environment. - `set caexcludepath=%include%` We highly recommend that you disable warnings that fire on standard headers. You can add more paths here, for example the path to the common headers in your project. - **Command-line options** @@ -303,13 +299,13 @@ Code Analysis requires a few environment variables and compiler command-line opt ## Use the Guideline Support Library -The Guideline Support Library (GSL) is designed to help you follow the Core Guidelines. The GSL includes definitions that let you replace error-prone constructs with safer alternatives. For example, you can replace a `T*, length` pair of parameters with the `span` type. The GSL project is available on GitHub at [https://github.com/Microsoft/GSL](https://github.com/Microsoft/GSL). The library is open-source, so you can view the sources, make comments, or contribute. You can also use the [vcpkg](https://vcpkg.io/) package manager to download and install the library locally. +The Guideline Support Library (GSL) is designed to help you follow the Core Guidelines. The GSL includes definitions that let you replace error-prone constructs with safer alternatives. For example, you can replace a `T*, length` pair of parameters with the `span` type. The GSL project is available on GitHub at [https://github.com/Microsoft/GSL](https://github.com/Microsoft/GSL). The library is open-source, so you can view the sources, make comments, or contribute. You can also use the [vcpkg](/vcpkg/) package manager to download and install the library locally. ::: moniker range="msvc-140" ## Use the C++ Core Check guidelines in Visual Studio 2015 projects -If you use Visual Studio 2015, the C++ Core Check code analysis rule sets aren't installed by default. Additional steps are needed before you can enable the C++ Core Check code analysis tools in Visual Studio 2015. Microsoft provides support for Visual Studio 2015 projects by using a NuGet package. The package is named Microsoft.CppCoreCheck, and it's available at [http://www.nuget.org/packages/Microsoft.CppCoreCheck](https://www.nuget.org/packages/Microsoft.CppCoreCheck). This package requires you have at least Visual Studio 2015 with Update 1 installed. +If you use Visual Studio 2015, the C++ Core Check code analysis rule sets aren't installed by default. Other steps are needed before you can enable the C++ Core Check code analysis tools in Visual Studio 2015. Microsoft provides support for Visual Studio 2015 projects by using a NuGet package. The package is named Microsoft.CppCoreCheck, and it's available at [http://www.nuget.org/packages/Microsoft.CppCoreCheck](https://www.nuget.org/packages/Microsoft.CppCoreCheck). This package requires you have at least Visual Studio 2015 with Update 1 installed. The package also installs another package as a dependency, the header-only Guideline Support Library (GSL). The GSL is also available on GitHub at [https://github.com/Microsoft/GSL](https://github.com/Microsoft/GSL). @@ -321,11 +317,11 @@ Because of the way the code analysis rules get loaded within Visual Studio 2015, 1. In the **NuGet Package Manager** window, search for Microsoft.CppCoreCheck. - ![Nuget Package Manager window showing the CppCoreCheck package.](../code-quality/media/cppcorecheck_nuget_window.png) + ![Nuget Package Manager window showing the CppCoreCheck package.](media/cppcorecheck_nuget_window.png) 1. Select the Microsoft.CppCoreCheck package and then choose the **Install** button to add the rules to your project. - The NuGet package adds an additional MSBuild *`.targets`* file to your project that is invoked when you enable code analysis on your project. The *`.targets`* file adds the C++ Core Check rules as an additional extension to the Visual Studio code analysis tool. When the package is installed, you can use the Property Pages dialog to enable or disable the released and experimental rules. + The NuGet package adds an MSBuild *`.targets`* file to your project that is invoked when you enable code analysis on your project. The *`.targets`* file adds the C++ Core Check rules as another extension to the Visual Studio code analysis tool. When the package is installed, you can use the Property Pages dialog to enable or disable the released and experimental rules. ::: moniker-end diff --git a/docs/code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md b/docs/code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md index 7ef995023e..0332306aa5 100644 --- a/docs/code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md +++ b/docs/code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md @@ -90,7 +90,7 @@ In this walkthrough, you'll: C6230: Implicit cast between semantically different types: using HRESULT in a Boolean context. - The code editor displays the line that caused the warning inside the function `bool ProcessDomain()`. This warning indicates that a `HRESULT` is being used in an 'if' statement where a Boolean result is expected. It's typically a mistake, because when the `S_OK` HRESULT is returned from a function it indicates success, but when converted into a boolean value it evaluates to **`false`**. + The code editor displays the line that caused the warning inside the function `bool ProcessDomain()`. This warning indicates that an `HRESULT` is being used in an 'if' statement where a Boolean result is expected. It's typically a mistake, because when the `S_OK` HRESULT is returned from a function it indicates success, but when converted into a boolean value it evaluates to **`false`**. 1. Correct this warning by using the `SUCCEEDED` macro, which converts to **`true`** when a `HRESULT` return value indicates success. Your code should resemble the following code: diff --git a/docs/cpp/additive-operators-plus-and.md b/docs/cpp/additive-operators-plus-and.md index 57281c0514..7c86e0a3ea 100644 --- a/docs/cpp/additive-operators-plus-and.md +++ b/docs/cpp/additive-operators-plus-and.md @@ -6,7 +6,7 @@ f1_keywords: ["+", "-"] helpviewer_keywords: ["operators [C++], addition", "subtraction operator [C++], additive operators", "+ operator [C++], additive operators", "additive operators [C++]", "arithmetic operators [C++], additive operators", "- operator [C++], additive operators in C++"] ms.assetid: d4afafe7-e201-4c69-a649-37f17756e784 --- -# Additive Operators: + and - +# Additive Operators: `+` and `-` ## Syntax @@ -102,6 +102,6 @@ One of the operands can be of integral type, as long as it is the second operand ## See also -[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C Additive Operators](../c-language/c-additive-operators.md) diff --git a/docs/cpp/aliases-and-typedefs-cpp.md b/docs/cpp/aliases-and-typedefs-cpp.md index f92bcdb3f2..a3b812eee2 100644 --- a/docs/cpp/aliases-and-typedefs-cpp.md +++ b/docs/cpp/aliases-and-typedefs-cpp.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Aliases and typedefs (C++)" title: "Aliases and typedefs (C++)" -ms.date: "11/04/2016" +ms.date: 06/30/2022 f1_keywords: ["typedef_cpp"] ms.assetid: af1c24d2-4bfd-408a-acfc-482e264232f5 --- # Aliases and typedefs (C++) -You can use an *alias declaration* to declare a name to use as a synonym for a previously declared type. (This mechanism is also referred to informally as a *type alias*). You can also use this mechanism to create an *alias template*, which can be particularly useful for custom allocators. +You can use an *alias declaration* to declare a name to use as a synonym for a previously declared type. (This mechanism is also referred to informally as a *type alias*). You can also use this mechanism to create an *alias template*, which can be useful for custom allocators. ## Syntax @@ -21,9 +21,9 @@ using identifier = type; The name of the alias. *type*
-The type identifier you are creating an alias for. +The type identifier you're creating an alias for. -An alias does not introduce a new type and cannot change the meaning of an existing type name. +An alias doesn't introduce a new type and can't change the meaning of an existing type name. The simplest form of an alias is equivalent to the **`typedef`** mechanism from C++03: @@ -35,7 +35,7 @@ using counter = long; // typedef long counter; ``` -Both of these enable the creation of variables of type "counter". Something more useful would be a type alias like this one for `std::ios_base::fmtflags`: +Both of these forms enable the creation of variables of type `counter`. Something more useful would be a type alias like this one for `std::ios_base::fmtflags`: ```cpp // C++11 @@ -75,7 +75,7 @@ ptr ptr_int; ## Example -The following example demonstrates how to use an alias template with a custom allocator—in this case, an integer vector type. You can substitute any type for **`int`** to create a convenient alias to hide the complex parameter lists in your main functional code. By using the custom allocator throughout your code you can improve readability and reduce the risk of introducing bugs caused by typos. +The following example demonstrates how to use an alias template with a custom allocator—in this case, an integer vector type. You can substitute any type for **`int`** to create a convenient alias to hide the complex parameter lists in your main functional code. By using the custom allocator throughout your code, you can improve readability and reduce the risk of introducing bugs caused by typos. ```cpp #include @@ -137,11 +137,11 @@ int main () A **`typedef`** declaration introduces a name that, within its scope, becomes a synonym for the type given by the *type-declaration* portion of the declaration. -You can use typedef declarations to construct shorter or more meaningful names for types already defined by the language or for types that you have declared. Typedef names allow you to encapsulate implementation details that may change. +You can use typedef declarations to construct shorter or more meaningful names for types already defined by the language or for types that you've declared. Typedef names allow you to encapsulate implementation details that may change. -In contrast to the **`class`**, **`struct`**, **`union`**, and **`enum`** declarations, **`typedef`** declarations do not introduce new types — they introduce new names for existing types. +In contrast to the **`class`**, **`struct`**, **`union`**, and **`enum`** declarations, **`typedef`** declarations don't introduce new types; they introduce new names for existing types. -Names declared using **`typedef`** occupy the same namespace as other identifiers (except statement labels). Therefore, they cannot use the same identifier as a previously declared name, except in a class-type declaration. Consider the following example: +Names declared using **`typedef`** occupy the same namespace as other identifiers (except statement labels). Therefore, they can't use the same identifier as a previously declared name, except in a class-type declaration. Consider the following example: ```cpp // typedef_names1.cpp @@ -163,6 +163,8 @@ int main() // typedef UL back in scope ``` +Another instance of name hiding: + ```cpp // typedef_specifier1.cpp typedef char FlagType; @@ -177,7 +179,7 @@ void myproc( int ) } ``` -When declaring a local-scope identifier by the same name as a typedef, or when declaring a member of a structure or union in the same scope or in an inner scope, the type specifier must be specified. For example: +When you declare a local-scope identifier by the same name as a **`typedef`**, or when you declare a member of a structure or union in the same scope or in an inner scope, the type specifier must be specified. For example: ```cpp typedef char FlagType; @@ -190,19 +192,19 @@ To reuse the `FlagType` name for an identifier, a structure member, or a union m const int FlagType; // Type specifier required ``` -It is not sufficient to say +It isn't sufficient to say ```cpp const FlagType; // Incomplete specification ``` -because the `FlagType` is taken to be part of the type, not an identifier that is being redeclared. This declaration is taken to be an illegal declaration like +because the `FlagType` is taken to be part of the type, not an identifier that's being redeclared. This declaration is taken to be an illegal declaration, similar to: ```cpp int; // Illegal declaration ``` -You can declare any type with typedef, including pointer, function, and array types. You can declare a typedef name for a pointer to a structure or union type before you define the structure or union type, as long as the definition has the same visibility as the declaration. +You can declare any type with **`typedef`**, including pointer, function, and array types. You can declare a typedef name for a pointer to a structure or union type before you define the structure or union type, as long as the definition has the same visibility as the declaration. ### Examples @@ -265,32 +267,42 @@ int main() 10 0.990000 ``` -### Re-declaration of typedefs +### Redeclaration of typedefs The **`typedef`** declaration can be used to redeclare the same name to refer to the same type. For example: +Source file `file1.h`: + ```cpp -// FILE1.H +// file1.h typedef char CHAR; +``` + +Source file `file2.h`: -// FILE2.H +```cpp +// file2.h typedef char CHAR; +``` -// PROG.CPP +Source file `prog.cpp`: + +```cpp +// prog.cpp #include "file1.h" #include "file2.h" // OK ``` -The program *PROG.CPP* includes two header files, both of which contain **`typedef`** declarations for the name `CHAR`. As long as both declarations refer to the same type, such redeclaration is acceptable. +The file *`prog.cpp`* includes two header files, both of which contain **`typedef`** declarations for the name `CHAR`. As long as both declarations refer to the same type, such redeclaration is acceptable. -A **`typedef`** cannot redefine a name that was previously declared as a different type. Therefore, if *FILE2.H* contains +A **`typedef`** can't redefine a name that was previously declared as a different type. Consider this alternative `file2.h`: ```cpp -// FILE2.H +// file2.h typedef int CHAR; // Error ``` -the compiler issues an error because of the attempt to redeclare the name `CHAR` to refer to a different type. This extends to constructs such as: +The compiler issues an error in *`prog.cpp`* because of the attempt to redeclare the name `CHAR` to refer to a different type. This policy extends to constructs such as: ```cpp typedef char CHAR; @@ -305,7 +317,7 @@ typedef union REGS // OK: name REGS redeclared ### typedefs in C++ vs. C -Use of the **`typedef`** specifier with class types is supported largely because of the ANSI C practice of declaring unnamed structures in **`typedef`** declarations. For example, many C programmers use the following: +Use of the **`typedef`** specifier with class types is supported largely because of the ANSI C practice of declaring unnamed structures in **`typedef`** declarations. For example, many C programmers use the following idiom: ```cpp // typedef_with_class_types1.cpp @@ -343,8 +355,8 @@ typedef struct { The preceding example declares a class named `POINT` using the unnamed class **`typedef`** syntax. `POINT` is treated as a class name; however, the following restrictions apply to names introduced this way: -- The name (the synonym) cannot appear after a **`class`**, **`struct`**, or **`union`** prefix. +- The name (the synonym) can't appear after a **`class`**, **`struct`**, or **`union`** prefix. -- The name cannot be used as constructor or destructor names within a class declaration. +- The name can't be used as a constructor or destructor name within a class declaration. -In summary, this syntax does not provide any mechanism for inheritance, construction, or destruction. +In summary, this syntax doesn't provide any mechanism for inheritance, construction, or destruction. diff --git a/docs/cpp/align-cpp.md b/docs/cpp/align-cpp.md index b54bddaf18..480640779f 100644 --- a/docs/cpp/align-cpp.md +++ b/docs/cpp/align-cpp.md @@ -4,11 +4,10 @@ title: "align (C++)" ms.date: "12/17/2018" f1_keywords: ["align_cpp"] helpviewer_keywords: ["align __declspec keyword", "__declspec keyword [C++], align"] -ms.assetid: 9cb63f58-658b-4425-ac47-af8eabfc5878 --- -# align (C++) +# `align` (C++) -In Visual Studio 2015 and later, use the C++11 standard **`alignas`** specifier to control alignment. For more information, see [Alignment](../cpp/alignment-cpp-declarations.md). +In Visual Studio 2015 and later, use [**`alignas`** specifier](../cpp/alignas-specifier.md) (C++11) to control alignment. For more information, see [Alignment](../cpp/alignment-cpp-declarations.md). **Microsoft Specific** @@ -20,7 +19,7 @@ Use `__declspec(align(#))` to precisely control the alignment of user-defined da ## Remarks -Writing applications that use the latest processor instructions introduces some new constraints and issues. Many new instructions require data that's aligned to 16-byte boundaries. Additionally, by aligning frequently used data to the processor's cache line size, you improve cache performance. For example, if you define a structure whose size is less than 32 bytes, you may want 32 byte alignment to make sure that objects of that structure type are efficiently cached. +Writing applications that use the latest processor instructions introduces some new constraints and issues. Many new instructions require data be aligned to 16-byte boundaries. Aligning frequently used data to the processor's cache line size improves cache performance. For example, if you define a structure whose size is less than 32 bytes, you might want 32-byte alignment to make sure that objects of that structure type are efficiently cached. \# is the alignment value. Valid entries are integer powers of two from 1 to 8192 (bytes), such as 2, 4, 8, 16, 32, or 64. `declarator` is the data that you're declaring as aligned. @@ -28,9 +27,9 @@ For information about how to return a value of type `size_t` that is the alignme You can use `__declspec(align(#))` when you define a **`struct`**, **`union`**, or **`class`**, or when you declare a variable. -The compiler doesn't guarantee or attempt to preserve the alignment attribute of data during a copy or data transform operation. For example, [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) can copy a struct declared with `__declspec(align(#))` to any location. Ordinary allocators (for example, [`malloc`](../c-runtime-library/reference/malloc.md), C++ [`operator new`](new-operator-cpp.md), and the Win32 allocators) typically return memory that isn't sufficiently aligned for `__declspec(align(#))` structures or arrays of structures. To guarantee that the destination of a copy or data transformation operation is correctly aligned, use [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md). Or, write your own allocator. +The compiler doesn't guarantee, or attempt to preserve, the alignment attribute of data during a copy or data transform operation. For example, [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) can copy a struct declared with `__declspec(align(#))` to any location. Ordinary allocators (for example, [`malloc`](../c-runtime-library/reference/malloc.md), C++ [`operator new`](new-operator-cpp.md), and the Win32 allocators) typically return memory that isn't aligned for `__declspec(align(#))` structures or arrays of structures. To guarantee that the destination of a copy or data transformation operation is correctly aligned, use [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md). Or, write your own allocator. -You can't specify alignment for function parameters. When you pass data that has an alignment attribute by value on the stack, its alignment is controlled by the calling convention. If data alignment is important in the called function, copy the parameter into correctly aligned memory before use. +You can't specify alignment for function parameters. When you pass data that has an alignment attribute by value on the stack, the calling convention controls its alignment. If data alignment is important in the called function, copy the parameter into correctly aligned memory before use. Without `__declspec(align(#))`, the compiler generally aligns data on natural boundaries based on the target processor and the size of the data, up to 4-byte boundaries on 32-bit processors, and 8-byte boundaries on 64-bit processors. Data in classes or structures is aligned in the class or structure at the minimum of its natural alignment and the current packing setting (from `#pragma pack` or the `/Zp` compiler option). @@ -42,7 +41,7 @@ __declspec(align(32)) struct Str1{ }; ``` -This type now has a 32-byte alignment attribute. It means that all static and automatic instances start on a 32-byte boundary. Additional structure types declared with this type as a member preserve this type's alignment attribute, that is, any structure with `Str1` as an element has an alignment attribute of at least 32. +This type now has a 32-byte alignment attribute. It means that all static and automatic instances start on a 32-byte boundary. Other structure types declared with this type as a member preserve this type's alignment attribute. That is, any structure with `Str1` as an element has an alignment attribute of at least 32. Here, `sizeof(struct Str1)` is equal to 32. It implies that if an array of `Str1` objects is created, and the base of the array is 32-byte aligned, each member of the array is also 32-byte aligned. To create an array whose base is correctly aligned in dynamic memory, use [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md). Or, write your own allocator. @@ -63,16 +62,12 @@ The compiler uses these rules for structure alignment: For more information, see: - [`align` Examples](#vclrfalignexamples) - - [Defining New Types with `__declspec(align(#))`](#vclrf_declspecaligntypedef) - - [Aligning Data in Thread Local Storage](#vclrfthreadlocalstorageallocation) - - [How `align` Works with Data Packing](#vclrfhowalignworkswithdatapacking) +- [x64 structure alignment examples](../build/x64-software-conventions.md#x64-structure-alignment-examples) -- [Examples of Structure Alignment](../build/x64-software-conventions.md#examples-of-structure-alignment) (x64 specific) - -## align Examples +## `align` Examples The following examples show how `__declspec(align(#))` affects the size and alignment of data structures. The examples assume the following definitions: @@ -150,7 +145,7 @@ struct S7 { `S6` and `S7` have identical alignment, allocation, and size characteristics. -In this example, the alignment of the starting addresses of a, b, c, and d are 4, 1, 4, and 1, respectively. +In this example, the alignment of the starting addresses of `a`, `b`, `c`, and `d` are 4, 1, 4, and 1, respectively. ```cpp void fn() { @@ -161,7 +156,7 @@ void fn() { } ``` -The alignment when memory is allocated on the heap depends on which allocation function is called. For example, if you use `malloc`, the result depends on the operand size. If *arg* >= 8, the memory returned is 8 byte aligned. If *arg* < 8, the alignment of the memory returned is the first power of 2 less than *arg*. For example, if you use `malloc(7)`, the alignment is 4 bytes. +The alignment when memory is allocated on the heap depends on which allocation function is called. For example, if you use `malloc`, the result depends on the operand size. If *arg* >= 8, the memory returned is 8-byte aligned. If *arg* < 8, the alignment of the memory returned is the first power of 2 less than *arg*. For example, if you use `malloc(7)`, the alignment is 4 bytes. ## Defining new types with `__declspec(align(#))` diff --git a/docs/cpp/alignas-specifier.md b/docs/cpp/alignas-specifier.md new file mode 100644 index 0000000000..4b5672fe86 --- /dev/null +++ b/docs/cpp/alignas-specifier.md @@ -0,0 +1,111 @@ +--- +description: "Learn more about: alignas specifier" +title: "alignas (C++)" +ms.date: 11/01/2023 +f1_keywords: ["alignas"] +helpviewer_keywords: ["alignas [C++]", "__alignof keyword [C++]", "alignof [C++]", "types [C++], alignment requirements"] +--- +# `alignas` (C++) + +The **`alignas`** specifier changes the alignment of a type or object in memory. + +## Syntax + +```cpp +alignas(expression) +alignas(type-id) +alignas(pack...) +``` + +## Remarks + +You can use **`alignas`** specifier on a **`struct`**, **`class`**, **`union`**, or variable declaration. + +For `alignas(expression)`, the expression must be an integral constant expression that is 0 or a power of 2 (1, 2, 4, 8, 16, ...). All other expressions are ill-formed. + +Use **`alignas`** instead of [`__declspec(align(#))`](align-cpp.md) for code portability. + +A common use of `alignas` is to control the alignment of a user-defined type, as shown in the following example: + +```cpp +struct alignas(8) S1 +{ + int x; +}; + +static_assert(alignof(S1) == 8, "alignof(S1) should be 8"); +``` + +When multiple **`alignas`** are applied to the same declaration, the one with the largest value is used. An **`alignas`** value of `0` is ignored. + +The following example shows how to use `alignas` with a user-defined type: + +```cpp +class alignas(4) alignas(16) C1 {}; + +// `alignas(0)` ignored +union alignas(0) U1 +{ + int i; + float f; +}; + +union U2 +{ + int i; + float f; +}; + +static_assert(alignof(C1) == 16, "alignof(C1) should be 16"); +static_assert(alignof(U1) == alignof(U2), "alignof(U1) should be equivalent to alignof(U2)"); +``` + +You can supply a type as the alignment value. The type's default alignment is used as the alignment value, as shown in the following example: + +```cpp +struct alignas(double) S2 +{ + int x; +}; + +static_assert(alignof(S2) == alignof(double), "alignof(S2) should be equivalent to alignof(double)"); +``` + +A template parameter pack (`alignas (pack...)`) can be used for the alignment value. The largest alignment value of all the elements in the pack is used. + +```cpp +template +class alignas(Ts...) C2 +{ + char c; +}; + +static_assert(alignof(C2<>) == 1, "alignof(C2<>) should be 1"); +static_assert(alignof(C2) == 4, "alignof(C2) should be 4"); +static_assert(alignof(C2) == 8, "alignof(C2) should be 8"); +``` + +If multiple **`alignas`** are applied, the resulting alignment is the largest of all the **`alignas`** values, and can't be less than the natural alignment of the type it's applied to. + +The declaration and definition of user-defined types must have the same alignment value. + +```cpp +// Declaration of `C3` +class alignas(16) C3; + +// Definition of `C3` with differing alignment value +class alignas(32) C3 {}; // Error: C2023 'C3': Alignment (32) different from prior declaration (16) + +int main() +{ + alignas(2) int x; // ill-formed because the natural alignment of int is 4 +} +``` + +## See also + +[`#pragma pack`](../preprocessor/pack.md)\ +[Alignment](../cpp/alignment-cpp-declarations.md)\ +[`alignof`](alignof-operator.md)\ +[Compiler error C2023](../error-messages/compiler-errors-1/compiler-error-c2023.md)\ +[Compiler warning C4359](../error-messages/compiler-warnings/compiler-warning-level-3-c4359.md) diff --git a/docs/cpp/alignment-cpp-declarations.md b/docs/cpp/alignment-cpp-declarations.md index 0219a84e4d..092f603341 100644 --- a/docs/cpp/alignment-cpp-declarations.md +++ b/docs/cpp/alignment-cpp-declarations.md @@ -1,16 +1,15 @@ --- title: "Alignment" description: "How data alignment is specified in modern C++." -ms.date: "12/11/2019" -ms.assetid: a986d510-ccb8-41f8-b905-433df9183485 +ms.date: 10/31/2023 --- # Alignment One of the low-level features of C++ is the ability to specify the precise alignment of objects in memory to take maximum advantage of a specific hardware architecture. By default, the compiler aligns class and struct members on their size value: **`bool`** and **`char`** on 1-byte boundaries, **`short`** on 2-byte boundaries, **`int`**, **`long`**, and **`float`** on 4-byte boundaries, and **`long long`**, **`double`**, and **`long double`** on 8-byte boundaries. -In most scenarios, you never have to be concerned with alignment because the default alignment is already optimal. In some cases, however, you can achieve significant performance improvements, or memory savings, by specifying a custom alignment for your data structures. Before Visual Studio 2015 you could use the Microsoft-specific keywords **`__alignof`** and **`__declspec(align)`** to specify an alignment greater than the default. Starting in Visual Studio 2015 you should use the C++11 standard keywords **`alignof`** and **`alignas`** for maximum code portability. The new keywords behave in the same way under the hood as the Microsoft-specific extensions. The documentation for those extensions also applies to the new keywords. For more information, see [`alignof` Operator](../cpp/alignof-operator.md) and [align](../cpp/align-cpp.md). The C++ standard doesn't specify packing behavior for alignment on boundaries smaller than the compiler default for the target platform, so you still need to use the Microsoft [`#pragma pack`](../preprocessor/pack.md) in that case. +In most scenarios, you never have to be concerned with alignment because the default alignment is already optimal. In some cases, however, you can achieve significant performance improvements, or memory savings, by specifying a custom alignment for your data structures. Before Visual Studio 2015 you could use the Microsoft-specific keywords **`__alignof`** and **`__declspec(align)`** to specify an alignment greater than the default. Starting in Visual Studio 2015 you should use the C++11 standard keywords **`alignof`** and **`alignas`** for maximum code portability. The new keywords behave in the same way under the hood as the Microsoft-specific extensions. The documentation for those extensions also applies to the new keywords. For more information, see [`alignof` Operator](../cpp/alignof-operator.md), [`alignas` Specifier](../cpp/alignas-specifier.md) and [align](../cpp/align-cpp.md). The C++ standard doesn't specify packing behavior for alignment on boundaries smaller than the compiler default for the target platform, so you still need to use the Microsoft [`#pragma pack`](../preprocessor/pack.md) in that case. -Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with non-trivial constructors or destructors. +Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with nontrivial constructors or destructors. ## Alignment and memory addresses @@ -58,8 +57,7 @@ Both declarations return `sizeof(struct x_)` as 12 bytes. The second declaration includes two padding elements: 1. `char _pad0[3]` to align the `int b` member on a 4-byte boundary. - -1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a four-byte boundary. +1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a 4-byte boundary. The padding aligns the elements of `bar[3]` in a way that allows natural access. @@ -92,11 +90,11 @@ adr offset element ## `alignof` and `alignas` -The **`alignas`** type specifier is a portable, C++ standard way to specify custom alignment of variables and user defined types. The **`alignof`** operator is likewise a standard, portable way to obtain the alignment of a specified type or variable. +The **`alignas`** specifier is a portable, C++ standard way to specify custom alignment of variables and user defined types. The **`alignof`** operator is likewise a standard, portable way to obtain the alignment of a specified type or variable. ## Example -You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler will choose the strictest one, (the one with the largest value). +You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler chooses the one with the largest value. ```cpp // alignas_alignof.cpp diff --git a/docs/cpp/alignof-operator.md b/docs/cpp/alignof-operator.md index 3dab06ff18..85de366870 100644 --- a/docs/cpp/alignof-operator.md +++ b/docs/cpp/alignof-operator.md @@ -4,9 +4,8 @@ title: "alignof Operator" ms.date: "12/17/2018" f1_keywords: ["__alignof_cpp", "alignof_cpp", "__alignof", "_alignof"] helpviewer_keywords: ["alignas [C++]", "alignment of structures", "__alignof keyword [C++]", "alignof [C++]", "types [C++], alignment requirements"] -ms.assetid: acb1eed7-6398-40bd-b0c5-684ceb64afbc --- -# alignof Operator +# `alignof` operator The **`alignof`** operator returns the alignment in bytes of the specified type as a value of type **`size_t`**. @@ -56,15 +55,11 @@ S* p = (S*)aligned_malloc(n * sizeof(S), alignof(S)); For more information on modifying alignment, see: -- [pack](../preprocessor/pack.md) - -- [align](../cpp/align-cpp.md) - -- [__unaligned](../cpp/unaligned.md) - -- [/Zp (Struct Member Alignment)](../build/reference/zp-struct-member-alignment.md) - -- [Examples of Structure Alignment](../build/x64-software-conventions.md#examples-of-structure-alignment) (x64 specific) +- [`pack`](../preprocessor/pack.md) +- [`align`](../cpp/align-cpp.md) +- [`__unaligned`](../cpp/unaligned.md) +- [`/Zp` (Struct member alignment)](../build/reference/zp-struct-member-alignment.md) +- [x64 structure alignment examples](../build/x64-software-conventions.md#x64-structure-alignment-examples) For more information on differences in alignment in code for x86 and x64, see: @@ -78,5 +73,5 @@ For compatibility with previous versions, **`_alignof`** is a synonym for **`__a ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/arrays-cpp.md b/docs/cpp/arrays-cpp.md index 941b90493e..48563141ee 100644 --- a/docs/cpp/arrays-cpp.md +++ b/docs/cpp/arrays-cpp.md @@ -3,11 +3,10 @@ title: "Arrays (C++)" description: "Learn how to declare and use the native array type in the standard C++ programming language." ms.date: 11/08/2020 helpviewer_keywords: ["declaring arrays [C++], about declaring arrays", "multidimensional arrays [C++]", "arrays [C++]"] -ms.assetid: 3f5986aa-485c-4ba4-9502-67e2ef924238 --- # Arrays (C++) -An array is a sequence of objects of the same type that occupy a contiguous area of memory. Traditional C-style arrays are the source of many bugs, but are still common, especially in older code bases. In modern C++, we strongly recommend using [std::vector](../standard-library/vector-class.md) or [std::array](../standard-library/array-class-stl.md) instead of C-style arrays described in this section. Both of these standard library types store their elements as a contiguous block of memory. However, they provide much greater type safety, and support iterators that are guaranteed to point to a valid location within the sequence. For more information, see [Containers](../standard-library/stl-containers.md). +An array is a sequence of objects of the same type that occupy a contiguous area of memory. Traditional C-style arrays are the source of many bugs, but are still common, especially in older code bases. In modern C++, we strongly recommend using [`std::vector`](../standard-library/vector-class.md) or [`std::array`](../standard-library/array-class-stl.md) instead of C-style arrays described in this section. Both of these standard library types store their elements as a contiguous block of memory. However, they provide greater type safety, and support iterators that are guaranteed to point to a valid location within the sequence. For more information, see [Containers](../standard-library/stl-containers.md). ## Stack declarations @@ -52,7 +51,6 @@ You may require an array that's too large to allocate on the stack, or whose siz The following example shows how to define an array on the heap at run time. It shows how to access the array elements using the subscript operator and by using pointer arithmetic: ```cpp - void do_something(size_t size) { // Declare an array of doubles to be allocated on the heap @@ -104,7 +102,6 @@ int main() { do_something(108); } - ``` ## Initializing arrays @@ -123,7 +120,7 @@ You can initialize an array in a loop, one element at a time, or in a single sta ## Passing arrays to functions -When an array is passed to a function, it's passed as a pointer to the first element, whether it's a stack-based or heap-based array. The pointer contains no additional size or type information. This behavior is called *pointer decay*. When you pass an array to a function, you must always specify the number of elements in a separate parameter. This behavior also implies that the array elements aren't copied when the array gets passed to a function. To prevent the function from modifying the elements, specify the parameter as a pointer to **`const`** elements. +When an array is passed to a function, it's passed as a pointer to the first element, whether it's a stack-based or heap-based array. The pointer contains no other size or type information. This behavior is called *pointer decay*. When you pass an array to a function, you must always specify the number of elements in a separate parameter. This behavior also implies that the array elements aren't copied when the array gets passed to a function. To prevent the function from modifying the elements, specify the parameter as a pointer to **`const`** elements. The following example shows a function that accepts an array and a length. The pointer points to the original array, not a copy. Because the parameter isn't **`const`**, the function can modify the array elements. @@ -164,8 +161,9 @@ int i2[5][7]; It specifies an array of type **`int`**, conceptually arranged in a two-dimensional matrix of five rows and seven columns, as shown in the following figure: -![Conceptual layout of a multi dimensional array.](../cpp/media/vc38rc1.gif)
-Conceptual layout of a multi-dimensional array +:::image type="complex" source="../cpp/media/vc38rc1.gif" alt-text="Conceptual layout of a multidimensional array."::: +The image is a grid 7 cells wide and 5 cells high. Each cell contains the index of the cell. The first cell index is labeled 0,0. The next cell in that row is 0,1 and so on to the last cell in that row which is 0,6. The next row starts with the index 1,0. The cell after that has an index of 1,1. The last cell in that row is 1,6. This pattern repeats until the last row, which starts with the index 4,0. The last cell in the last row has an index of 4,6. +:::image-end::: You can declare multidimensioned arrays that have an initializer list (as described in [Initializers](../cpp/initializers.md)). In these declarations, the constant expression that specifies the bounds for the first dimension can be omitted. For example: @@ -359,4 +357,4 @@ szError1 = psz; ## See also -[std::array](../standard-library/array-class-stl.md) +[`std::array`](../standard-library/array-class-stl.md) diff --git a/docs/cpp/assignment-operators.md b/docs/cpp/assignment-operators.md index 5e59a236b0..d03022b7bd 100644 --- a/docs/cpp/assignment-operators.md +++ b/docs/cpp/assignment-operators.md @@ -1,7 +1,7 @@ --- title: "Assignment operators" description: "The C++ standard language assignment operators syntax and use." -ms.date: 07/24/2020 +ms.date: 02/23/2024 f1_keywords: ["=", "*=", "/=", "%=", "+=", "-=", "<<=", ">>=", "&=", "^=", "|="] helpviewer_keywords: ["operators [C++], assignment", "assignment operators [C++], C++", "&= operator", "^= operator", "+= operator", ">>= operator", "|= operator", "operator>>=", "*= operator", "%= operator", "^= operator", "operator >>=", "= operator", "-= operator", "/= operator", "<<= operator"] ms.assetid: b028cf35-2ff1-4f14-9027-fd53ebec8aa0 @@ -10,9 +10,9 @@ ms.assetid: b028cf35-2ff1-4f14-9027-fd53ebec8aa0 ## Syntax -*expression* *assignment-operator* *expression* +*`expression`* *`assignment-operator`* *`expression`* -*assignment-operator*: one of
+*`assignment-operator`*: one of\  **`=`** **`*=`** **`/=`** **`%=`** **`+=`** **`-=`** **`<<=`** **`>>=`** **`&=`** **`^=`** **`|=`** ## Remarks @@ -83,7 +83,7 @@ The simple assignment operator (**`=`**) causes the value of the second operand Objects of **`const`** and **`volatile`** types can be assigned to l-values of types that are only **`volatile`**, or that aren't **`const`** or **`volatile`**. -Assignment to objects of class type (**`struct`**, **`union`**, and **`class`** types) is performed by a function named `operator=`. The default behavior of this operator function is to perform a bitwise copy; however, this behavior can be modified using overloaded operators. For more information, see [Operator overloading](../cpp/operator-overloading.md). Class types can also have *copy assignment* and *move assignment* operators. For more information, see [Copy constructors and copy assignment operators](copy-constructors-and-copy-assignment-operators-cpp.md) and [Move constructors and move assignment operators](move-constructors-and-move-assignment-operators-cpp.md). +Assignment to objects of class type (**`struct`**, **`union`**, and **`class`** types) is performed by a function named `operator=`. The default behavior of this operator function is to perform a member-wise copy assignment of the object's non-static data members and direct base classes; however, this behavior can be modified using overloaded operators. For more information, see [Operator overloading](../cpp/operator-overloading.md). Class types can also have *copy assignment* and *move assignment* operators. For more information, see [Copy constructors and copy assignment operators](copy-constructors-and-copy-assignment-operators-cpp.md) and [Move constructors and move assignment operators](move-constructors-and-move-assignment-operators-cpp.md). An object of any unambiguously derived class from a given base class can be assigned to an object of the base class. The reverse isn't true because there's an implicit conversion from derived class to base class, but not from base class to derived class. For example: @@ -154,18 +154,20 @@ The compound assignment operators are shown in the [Assignment operators table]( - a pointer, if *op* is **`+`** or **`-`** -The *e1* *op*= *e2* form behaves as *e1* **`=`** *e1* *op* *e2*, but *e1* is evaluated only once. +- a type for which there exists a matching `operator *op*=` overload for the type of *e1* + +The built-in *e1* *op*= *e2* form behaves as *e1* **`=`** *e1* *op* *e2*, but *e1* is evaluated only once. Compound assignment to an enumerated type generates an error message. If the left operand is of a pointer type, the right operand must be of a pointer type, or it must be a constant expression that evaluates to 0. When the left operand is of an integral type, the right operand must not be of a pointer type. -## Result of assignment operators +## Result of built-in assignment operators -The assignment operators return the value of the object specified by the left operand after the assignment. The resultant type is the type of the left operand. The result of an assignment expression is always an l-value. These operators have right-to-left associativity. The left operand must be a modifiable l-value. +The built-in assignment operators return the value of the object specified by the left operand after the assignment (and the arithmetic/logical operation in the case of compound assignment operators). The resultant type is the type of the left operand. The result of an assignment expression is always an l-value. These operators have right-to-left associativity. The left operand must be a modifiable l-value. In ANSI C, the result of an assignment expression isn't an l-value. That means the legal C++ expression `(a += b) += c` isn't allowed in C. ## See also -[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)
-[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)\ +[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C assignment operators](../c-language/c-assignment-operators.md) diff --git a/docs/cpp/attributes.md b/docs/cpp/attributes.md index 82f2d0bcc5..b34a559f80 100644 --- a/docs/cpp/attributes.md +++ b/docs/cpp/attributes.md @@ -1,13 +1,16 @@ --- description: "Learn more about: Attributes in C++" title: "Attributes in C++" -ms.date: 04/18/2021 +f1_keywords: ["deprecated", "no_return", "carries_dependency", "fallthrough", "nodiscard", "maybe_unused", "likely", "unlikely", "gsl::suppress", "msvc::intrinsic", "msvc::no_tls_guard"] +helpviewer_keywords: ["deprecated", "no_return", "carries_dependency", "fallthrough", "nodiscard", "maybe_unused", "likely", "unlikely", "gsl::suppress", "msvc::intrinsic", "msvc::no_tls_guard"] +ms.date: 4/13/2023 --- + # Attributes in C++ The C++ Standard defines a common set of attributes. It also allows compiler vendors to define their own attributes within a vendor-specific namespace. However, compilers are only required to recognize the attributes defined in the standard. -In some cases, standard attributes overlap with compiler-specific `__declspec` parameters. In Microsoft C++, you can use the `[[deprecated]]` attribute instead of using `__declspec(deprecated)`. The `[[deprecated]]` attribute is recognized by any conforming compiler. For all other `__declspec` parameters such as `dllimport` and `dllexport`, so far there's no attribute equivalent, so you must continue to use `__declspec` syntax. Attributes don't affect the type system, and they don’t change the meaning of a program. Compilers ignore attribute values they don't recognize. +In some cases, standard attributes overlap with compiler-specific `__declspec` parameters. In Microsoft C++, you can use the `[[deprecated]]` attribute instead of using `__declspec(deprecated)`. The `[[deprecated]]` attribute is recognized by any conforming compiler. For all other `__declspec` parameters such as `dllimport` and `dllexport`, so far there's no attribute equivalent, so you must continue to use `__declspec` syntax. Attributes don't affect the type system, and they don't change the meaning of a program. Compilers ignore attribute values they don't recognize. **Visual Studio 2017 version 15.3 and later** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later): In the scope of an attribute list, you can specify the namespace for all names with a single **`using`** introducer: @@ -18,7 +21,7 @@ void g() { } ``` -## C++ Standard Attributes +## C++ standard attributes In C++11, attributes provide a standardized way to annotate C++ constructs (including but not limited to classes, functions, variables, and blocks) with additional information. Attributes may or may not be vendor-specific. A compiler can use this information to generate informational messages, or to apply special logic when compiling the attributed code. The compiler ignores any attributes that it doesn't recognize, which means you can't define your own custom attributes using this syntax. Attributes are enclosed by double square brackets: @@ -27,54 +30,143 @@ In C++11, attributes provide a standardized way to annotate C++ constructs (incl void Foo(int); ``` -Attributes represent a standardized alternative to vendor-specific extensions such as `#pragma` directives, `__declspec()` (Visual C++), or `__attribute__` (GNU). However, you'll still need to use the vendor-specific constructs for most purposes. The standard currently specifies the following attributes that a conforming compiler should recognize: +Attributes represent a standardized alternative to vendor-specific extensions such as `#pragma` directives, `__declspec()` (Visual C++), or `__attribute__` (GNU). However, you'll still need to use the vendor-specific constructs for most purposes. The standard currently specifies the following attributes that a conforming compiler should recognize. + +### `[[carries_dependency]]` + +The `[[carries_dependency]]` attribute specifies that the function propagates data dependency ordering for thread synchronization. The attribute can be applied to one or more parameters, to specify that the passed-in argument carries a dependency into the function body. The attribute can be applied to the function itself, to specify that the return value carries a dependency out of the function. The compiler can use this information to generate more efficient code. + +### `[[deprecated]]` + +**Visual Studio 2015 and later:** The `[[deprecated]]` attribute specifies that a function isn't intended for use. Or, that it might not exist in future versions of a library interface. The `[[deprecated]]` attribute can be applied to declaration of a class, a typedef-name, a variable, a nonstatic data member, a function, a namespace, an enumeration, an enumerator, or a template specialization. The compiler can use this attribute to generate an informational message when client code attempts to call the function. When the Microsoft C++ compiler detects the use of a `[[deprecated]]` item, it raises compiler warning [C4996](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). + +### `[[fallthrough]]` + +**Visual Studio 2017 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[fallthrough]]` attribute can be used in the context of [`switch`](switch-statement-cpp.md) statements as a hint to the compiler (or anyone reading the code) that the fallthrough behavior is intended. The Microsoft C++ compiler currently doesn't warn on fallthrough behavior, so this attribute has no effect on compiler behavior. -- `[[noreturn]]` Specifies that a function never returns; in other words it always throws an exception. The compiler can adjust its compilation rules for `[[noreturn]]` entities. +### `[[likely]]` -- `[[carries_dependency]]` Specifies that the function propagates data dependency ordering for thread synchronization. The attribute can be applied to one or more parameters, to specify that the passed-in argument carries a dependency into the function body. The attribute can be applied to the function itself, to specify that the return value carries a dependency out of the function. The compiler can use this information to generate more efficient code. +**Visual Studio 2019 version 16.6 and later:** (Available with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[likely]]` attribute specifies a hint to the compiler that the code path for the attributed label or statement is more likely to execute than alternatives. In the Microsoft compiler, the `[[likely]]` attribute marks blocks as "hot code", which increments an internal optimization score. The score is incremented more when optimizing for speed, and not as much when optimizing for size. The net score affects the likelihood of inlining, loop unrolling, and vectorizing optimizations. The effect of `[[likely]]` and `[[unlikely]]` is similar to [Profile-guided optimization](../build/profile-guided-optimizations.md), but limited in scope to the current translation unit. The block reordering optimization isn't implemented yet for this attribute. -- `[[deprecated]]` **Visual Studio 2015 and later:** Specifies that a function isn't intended for use. Or, that it might not exist in future versions of a library interface. The compiler can use this attribute to generate an informational message when client code attempts to call the function. `[[deprecated]]` can be applied to declaration of a class, a typedef-name, a variable, a non-static data member, a function, a namespace, an enumeration, an enumerator, or a template specialization. +### `[[maybe_unused]]` -- `[[fallthrough]]` **Visual Studio 2017 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[fallthrough]]` attribute can be used in the context of [`switch`](switch-statement-cpp.md) statements as a hint to the compiler (or anyone reading the code) that the fallthrough behavior is intended. The Microsoft C++ compiler currently doesn't warn on fallthrough behavior, so this attribute has no effect compiler behavior. +**Visual Studio 2017 version 15.3 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[maybe_unused]]` attribute specifies that a variable, function, class, typedef, nonstatic data member, enum, or template specialization may be intentionally unused. The compiler doesn't warn when an entity marked `[[maybe_unused]]` isn't used. An entity that's declared without the attribute can later be redeclared with the attribute and vice-versa. An entity is considered *marked* after its first declaration that's marked `[[maybe_unused]]` gets analyzed, and for the rest of the current translation unit. -- `[[nodiscard]]` **Visual Studio 2017 version 15.3 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) Specifies that a function's return value isn't intended to be discarded. Raises warning [C4834](../error-messages/compiler-warnings/c4834.md), as shown in this example: +### `[[nodiscard]]` + +**Visual Studio 2017 version 15.3 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) Specifies that a function's return value isn't intended to be discarded. Raises warning [C4834](../error-messages/compiler-warnings/c4834.md), as shown in this example: + +```cpp +[[nodiscard]] +int foo(int i) { return i * i; } + +int main() +{ + foo(42); //warning C4834: discarding return value of function with 'nodiscard' attribute + return 0; +} +``` - ```cpp - [[nodiscard]] - int foo(int i) { return i * i; } +### `[[noreturn]]` - int main() +The `[[noreturn]]` attribute specifies that a function never returns; in other words, it always throws an exception or exits. The compiler can adjust its compilation rules for `[[noreturn]]` entities. + +### `[[unlikely]]` + +**Visual Studio 2019 version 16.6 and later:** (Available with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[unlikely]]` attribute specifies a hint to the compiler that the code path for the attributed label or statement is less likely to execute than alternatives. In the Microsoft compiler, the `[[unlikely]]` attribute marks blocks as "cold code", which decrements an internal optimization score. The score is decremented more when optimizing for size, and not as much when optimizing for speed. The net score affects the likelihood of inlining, loop unrolling, and vectorizing optimizations. The block reordering optimization isn't implemented yet for this attribute. + +## Microsoft-specific attributes + +### `[[gsl::suppress( [, justification: ])]]` + +`` is a string that specifies the name of the rule to suppress. The optional `justification` field allows you to explain why a warning is being disabled or suppressed. This value will appear in the SARIF output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal. The `[[gsl::suppress]]` attribute is available in Visual Studio 2022 version 17.14 and later versions. + +The Microsoft-specific `[[gsl::suppress]]` attribute is used to suppress warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider this code snippet: + +```cpp +int main() +{ + int arr[10]; // GSL warning C26494 will be fired + int* p = arr; // GSL warning C26485 will be fired + [[gsl::suppress("bounds.1", justification: "This attribute suppresses Bounds rule #1")]] { - foo(42); //warning C4834: discarding return value of function with 'nodiscard' attribute - return 0; + int* q = p + 1; // GSL warning C26481 suppressed + p = q--; // GSL warning C26481 suppressed } - ``` +} +``` -- `[[maybe_unused]]` **Visual Studio 2017 version 15.3 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) Specifies that a variable, function, class, typedef, non-static data member, enum, or template specialization may intentionally not be used. The compiler doesn't warn when an entity marked `[[maybe_unused]]` isn't used. An entity that's declared without the attribute can later be redeclared with the attribute and vice-versa. An entity is considered *marked* after its first declaration that's marked `[[maybe_unused]]` gets analyzed, and for the rest of the current translation unit. +The example raises these warnings: -## Microsoft-specific attributes +- [C26494](../code-quality/c26494.md) (Type Rule 5: Always initialize an object.) -- `[[gsl::suppress(rules)]]` This Microsoft-specific attribute is used for suppressing warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider this code snippet: +- [C26485](../code-quality/c26485.md) (Bounds Rule 3: No array to pointer decay.) - ```cpp - int main() +- [C26481](../code-quality/c26481.md) (Bounds Rule 1: Don't use pointer arithmetic. Use span instead.) + +The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing `[[gsl::suppress("bounds")]]` without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they aren't wanted. + +### `[[msvc::flatten]]` + +The Microsoft-specific attribute `[[msvc::flatten]]` is very similar to `[[msvc::forceinline_calls]]`, and can be used in the same places and in the same way. The difference is that `[[msvc::flatten]]` will `[[msvc::forceinline_calls]]` all calls in the scope it's applied to recursively, until no calls are left. This may have consequences for the resulting code size growth of the function or the throughput of the compiler, which you must manage manually. + +### `[[msvc::forceinline]]` + +When placed before a function declaration, the Microsoft-specific attribute `[[msvc::forceinline]]` has the same meaning as `__forceinline`. + +### `[[msvc::forceinline_calls]]` + +The Microsoft-specific attribute `[[msvc::forceinline_calls]]` can be placed on or before a statement or a block. It causes the inline heuristic to attempt to `[[msvc::forceinline]]` all calls in that statement or block: + +```cpp +void f() { + [[msvc::forceinline_calls]] { - int arr[10]; // GSL warning C26494 will be fired - int* p = arr; // GSL warning C26485 will be fired - [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1 - { - int* q = p + 1; // GSL warning C26481 suppressed - p = q--; // GSL warning C26481 suppressed - } + foo(); + bar(); } - ``` + ... + [[msvc::forceinline_calls]] + bar(); + + foo(); +} +``` + +The first call to `foo`, and both calls to `bar`, are treated as if they were declared `__forceinline`. The second call to `foo` isn't treated as `__forceinline`. + +### `[[msvc::intrinsic]]` + +The `[[msvc::intrinsic]]` attribute has three constraints on the function it's applied to: + +- The function can't be recursive; its body must only have a return statement with a `static_cast` from the parameter type to the return type. +- The function can only accept a single parameter. +- The **`/permissive-`** compiler option is required. (The **`/std:c++20`** and later options imply **`/permissive-`** by default.) + +The Microsoft-specific `[[msvc::intrinsic]]` attribute tells the compiler to inline a metafunction that acts as a named cast from the parameter type to the return type. When the attribute is present on a function definition, the compiler replaces all calls to that function with a simple cast. The `[[msvc::intrinsic]]` attribute is available in Visual Studio 2022 version 17.5 preview 2 and later versions. This attribute applies only to the specific function that follows it. + +#### Example + +In this sample code, the `[[msvc::intrinsic]]` attribute applied to the `my_move` function makes the compiler replace calls to the function with the inlined static cast in its body: + +```cpp +template +[[msvc::intrinsic]] T&& my_move(T&& t) { return static_cast(t); } + +void f() { + int i = 0; + i = my_move(i); +} +``` + +### `[[msvc::noinline]]` - The example raises these warnings: +When placed before a function declaration, the Microsoft-specific attribute `[[msvc::noinline]]` has the same meaning as `__declspec(noinline)`. - - 26494 (Type Rule 5: Always initialize an object.) +### `[[msvc::noinline_calls]]` - - 26485 (Bounds Rule 3: No array to pointer decay.) +The Microsoft-specific attribute `[[msvc::noinline_calls]]` has the same usage as `[[msvc::forceinline_calls]]`. It can be placed before any statement or block. Rather than force-inlining all calls in that block, it has the effect of turning off inlining for the scope it's applied to. - - 26481 (Bounds Rule 1: Don't use pointer arithmetic. Use span instead.) +### `[[msvc::no_tls_guard]]` - The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing `[[gsl::suppress(bounds)]]` without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they aren't wanted. +The Microsoft-specific `[[msvc::no_tls_guard]]` attribute disables checks for initialization on first access to thread-local variables in DLLs. The checks are enabled by default in code built using Visual Studio 2019 version 16.5 and later versions. This attribute applies only to the specific variable that follows it. To disable checks globally, use the [`/Zc:tlsGuards-`](../build/reference/zc-tlsguards.md) compiler option. diff --git a/docs/cpp/auto-cpp.md b/docs/cpp/auto-cpp.md index eefb9773b7..ef1288e32f 100644 --- a/docs/cpp/auto-cpp.md +++ b/docs/cpp/auto-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: `auto` (C++)" title: "auto (C++)" -ms.date: "12/10/2019" +ms.date: 09/27/2022 f1_keywords: ["auto_CPP", "auto"] helpviewer_keywords: ["auto keyword [C++]"] ms.assetid: e9d495d7-601c-4547-b897-998389a311f4 @@ -25,9 +25,9 @@ The **`auto`** keyword directs the compiler to use the initialization expression We recommend that you use the **`auto`** keyword for most situations—unless you really want a conversion—because it provides these benefits: -- **Robustness:** If the expression’s type is changed—this includes when a function return type is changed—it just works. +- **Robustness:** If the expression's type is changed—including when a function return type is changed—it just works. -- **Performance:** You’re guaranteed that there will be no conversion. +- **Performance:** You're guaranteed that there's no conversion. - **Usability:** You don't have to worry about type name spelling difficulties and typos. @@ -35,9 +35,9 @@ We recommend that you use the **`auto`** keyword for most situations—unless yo Conversion cases in which you might not want to use **`auto`**: -- When you want a specific type and nothing else will do. +- You want a specific type and nothing else will do. -- Expression template helper types—for example, `(valarray+valarray)`. +- In expression template helper types—for example, `(valarray+valarray)`. To use the **`auto`** keyword, use it instead of a type to declare a variable, and specify an initialization expression. In addition, you can modify the **`auto`** keyword by using specifiers and declarators such as **`const`**, **`volatile`**, pointer (**`*`**), reference (**`&`**), and rvalue reference (**`&&`**). The compiler evaluates the initialization expression and then uses that information to deduce the type of the variable. @@ -45,14 +45,14 @@ The **`auto`** initialization expression can take several forms: - Universal initialization syntax, such as `auto a { 42 };`. - Assignment syntax, such as `auto b = 0;`. -- Universal assignment syntax, which combines the two previous forms, such as `auto c = { 3.14156 };`. +- Universal assignment syntax, which combines the two previous forms, such as `auto c = { 3.14159 };`. - Direct initialization, or constructor-style syntax, such as `auto d( 1.41421f );`. For more information, see [Initializers](../cpp/initializers.md) and the code examples later in this document. When **`auto`** is used to declare the loop parameter in a range-based **`for`** statement, it uses a different initialization syntax, for example `for (auto& i : iterable) do_action(i);`. For more information, see [Range-based `for` Statement (C++)](../cpp/range-based-for-statement-cpp.md). -The **`auto`** keyword is a placeholder for a type, but it is not itself a type. Therefore, the **`auto`** keyword cannot be used in casts or operators such as [`sizeof`](../cpp/sizeof-operator.md) and (for C++/CLI) [`typeid`](../extensions/typeid-cpp-component-extensions.md). +The **`auto`** keyword is a placeholder for a type, but it isn't itself a type. Therefore, the **`auto`** keyword can't be used in casts or operators such as [`sizeof`](../cpp/sizeof-operator.md) and (for C++/CLI) [`typeid`](../extensions/typeid-cpp-component-extensions.md). ## Usefulness @@ -62,11 +62,11 @@ You can also use **`auto`** to declare and initialize a variable to a lambda exp ## Trailing Return Types -You can use **`auto`**, together with the **`decltype`** type specifier, to help write template libraries. Use **`auto`** and **`decltype`** to declare a template function whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a template function that wraps a call to another function, and then returns whatever is the return type of that other function. For more information, see [`decltype`](../cpp/decltype-cpp.md). +You can use **`auto`**, together with the **`decltype`** type specifier, to help write template libraries. Use **`auto`** and **`decltype`** to declare a function template whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a function template that wraps a call to another function, and then returns whatever is the return type of that other function. For more information, see [`decltype`](../cpp/decltype-cpp.md). ## References and cv-qualifiers -Note that using **`auto`** drops references, **`const`** qualifiers, and **`volatile`** qualifiers. Consider the following example: +Using **`auto`** drops references, **`const`** qualifiers, and **`volatile`** qualifiers. Consider the following example: ```cpp // cl.exe /analyze /EHsc /W4 @@ -88,7 +88,7 @@ int main( ) } ``` -In the previous example, myAuto is an **`int`**, not an **`int`** reference, so the output is `11 11`, not `11 12` as would be the case if the reference qualifier had not been dropped by **`auto`**. +In the previous example, myAuto is an **`int`**, not an **`int`** reference, so the output is `11 11`, not `11 12` as would be the case if the reference qualifier hadn't been dropped by **`auto`**. ## Type deduction with braced initializers (C++14) @@ -119,21 +119,21 @@ int main() } ``` -## Restrictions and Error Messages +## Restrictions and error messages The following table lists the restrictions on the use of the **`auto`** keyword, and the corresponding diagnostic error message that the compiler emits. -|Error number|Description| -|------------------|-----------------| -|[C3530](../error-messages/compiler-errors-2/compiler-error-c3530.md)|The **`auto`** keyword cannot be combined with any other type-specifier.| -|[C3531](../error-messages/compiler-errors-2/compiler-error-c3531.md)|A symbol that is declared with the **`auto`** keyword must have an initializer.| -|[C3532](../error-messages/compiler-errors-2/compiler-error-c3532.md)|You incorrectly used the **`auto`** keyword to declare a type. For example, you declared a method return type or an array.| -|[C3533](../error-messages/compiler-errors-2/compiler-error-c3533.md), [C3539](../error-messages/compiler-errors-2/compiler-error-c3539.md)|A parameter or template argument cannot be declared with the **`auto`** keyword.| -|[C3535](../error-messages/compiler-errors-2/compiler-error-c3535.md)|A method or template parameter cannot be declared with the **`auto`** keyword.| -|[C3536](../error-messages/compiler-errors-2/compiler-error-c3536.md)|A symbol cannot be used before it is initialized. In practice, this means that a variable cannot be used to initialize itself.| -|[C3537](../error-messages/compiler-errors-2/compiler-error-c3537.md)|You cannot cast to a type that is declared with the **`auto`** keyword.| -|[C3538](../error-messages/compiler-errors-2/compiler-error-c3538.md)|All the symbols in a declarator list that is declared with the **`auto`** keyword must resolve to the same type. For more information, see [Declarations and Definitions](declarations-and-definitions-cpp.md).| -|[C3540](../error-messages/compiler-errors-2/compiler-error-c3540.md), [C3541](../error-messages/compiler-errors-2/compiler-error-c3541.md)|The [sizeof](../cpp/sizeof-operator.md) and [typeid](../extensions/typeid-cpp-component-extensions.md) operators cannot be applied to a symbol that is declared with the **`auto`** keyword.| +| Error number | Description | +|--|--| +| [C3530](../error-messages/compiler-errors-2/compiler-error-c3530.md) | The **`auto`** keyword can't be combined with any other type-specifier. | +| [C3531](../error-messages/compiler-errors-2/compiler-error-c3531.md) | A symbol that is declared with the **`auto`** keyword must have an initializer. | +| [C3532](../error-messages/compiler-errors-2/compiler-error-c3532.md) | You incorrectly used the **`auto`** keyword to declare a type. For example, you declared a method return type or an array. | +| [C3533](../error-messages/compiler-errors-2/compiler-error-c3533.md), [C3539](../error-messages/compiler-errors-2/compiler-error-c3539.md) | A parameter or template argument can't be declared with the **`auto`** keyword. | +| [C3535](../error-messages/compiler-errors-2/compiler-error-c3535.md) | A method or template parameter can't be declared with the **`auto`** keyword. | +| [C3536](../error-messages/compiler-errors-2/compiler-error-c3536.md) | A symbol can't be used before it's initialized. In practice, it means that a variable can't be used to initialize itself. | +| [C3537](../error-messages/compiler-errors-2/compiler-error-c3537.md) | You can't cast to a type that is declared with the **`auto`** keyword. | +| [C3538](../error-messages/compiler-errors-2/compiler-error-c3538.md) | All the symbols in a declarator list that is declared with the **`auto`** keyword must resolve to the same type. For more information, see [Declarations and Definitions](declarations-and-definitions-cpp.md). | +| [C3540](../error-messages/compiler-errors-2/compiler-error-c3540.md), [C3541](../error-messages/compiler-errors-2/compiler-error-c3541.md) | The [sizeof](../cpp/sizeof-operator.md) and [typeid](../extensions/typeid-cpp-component-extensions.md) operators can't be applied to a symbol that is declared with the **`auto`** keyword. | ## Examples @@ -221,12 +221,12 @@ int main() ## See also -[Keywords](../cpp/keywords-cpp.md)
-[`/Zc:auto` (Deduce Variable Type)](../build/reference/zc-auto-deduce-variable-type.md)
-[`sizeof` Operator](../cpp/sizeof-operator.md)
-[`typeid`](../extensions/typeid-cpp-component-extensions.md)
-[`operator new`](new-operator-cpp.md)
-[Declarations and Definitions](declarations-and-definitions-cpp.md)
-[Examples of Lambda Expressions](../cpp/examples-of-lambda-expressions.md)
-[Initializers](../cpp/initializers.md)
+[Keywords](../cpp/keywords-cpp.md)\ +[`/Zc:auto` (Deduce variable type)](../build/reference/zc-auto-deduce-variable-type.md)\ +[`sizeof` operator](../cpp/sizeof-operator.md)\ +[`typeid`](../extensions/typeid-cpp-component-extensions.md)\ +[`operator new`](new-operator-cpp.md)\ +[Declarations and definitions](declarations-and-definitions-cpp.md)\ +[Examples of lambda expressions](../cpp/examples-of-lambda-expressions.md)\ +[Initializers](../cpp/initializers.md)\ [`decltype`](../cpp/decltype-cpp.md) diff --git a/docs/cpp/based-grammar.md b/docs/cpp/based-grammar.md index 292565d417..8797b6baa9 100644 --- a/docs/cpp/based-grammar.md +++ b/docs/cpp/based-grammar.md @@ -5,7 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["based addressing"] ms.assetid: a68ff750-c7fa-4c0c-8d5f-2df76e4686c5 --- -# __based Grammar +# `__based` Grammar **Microsoft Specific** @@ -15,20 +15,20 @@ The only form of based addressing acceptable in 32-bit and 64-bit compilations i ## Grammar -*based-range-modifier*: -**__based(** *base-expression* **)** +*`based-range-modifier`*:\ + **`__based(`** *`base-expression`* **`)`** -*base-expression*: -*based-variablebased-abstract-declaratorsegment-namesegment-cast* +*`base-expression`*:\ + *`based-variable`* *`based-abstract-declarator`* *`segment-name`* *`segment-cast`* -*based-variable*: -*identifier* +*`based-variable`*:\ + *`identifier`* -*based-abstract-declarator*: -*abstract-declarator* +*`based-abstract-declarator`*:\ + *`abstract-declarator`* -*base-type*: -*type-name* +*`base-type`*:\ + *`type-name`* **END Microsoft Specific** diff --git a/docs/cpp/binary-operators.md b/docs/cpp/binary-operators.md index c0e9f3a8ce..9c31087e1f 100644 --- a/docs/cpp/binary-operators.md +++ b/docs/cpp/binary-operators.md @@ -42,9 +42,9 @@ The following table shows a list of operators that can be overloaded. |**>>=**|Right shift/assignment| |**^**|Exclusive OR| |**^=**|Exclusive OR/assignment| -|**|**|Bitwise inclusive OR| -|**|=**|Bitwise inclusive OR/assignment| -|**||**|Logical OR| +|**\|**|Bitwise inclusive OR| +|**\|=**|Bitwise inclusive OR/assignment| +|**\|\|**|Logical OR| To declare a binary operator function as a nonstatic member, you must declare it in the form: diff --git a/docs/cpp/bitwise-exclusive-or-operator-hat.md b/docs/cpp/bitwise-exclusive-or-operator-hat.md index 62b113a085..b6755b4b06 100644 --- a/docs/cpp/bitwise-exclusive-or-operator-hat.md +++ b/docs/cpp/bitwise-exclusive-or-operator-hat.md @@ -6,7 +6,7 @@ f1_keywords: ["xor_cpp", "^"] helpviewer_keywords: ["operators [C++], bitwise", "exclusive OR operator", "XOR operator", "bitwise operators [C++], OR operator", "^ operator", "OR operator [C++], bitwise exclusive", "operators [C++], logical"] ms.assetid: f9185d85-65d5-4f64-a6d6-679758d52217 --- -# Bitwise exclusive OR operator: ^ +# Bitwise exclusive OR operator: `^` ## Syntax diff --git a/docs/cpp/bitwise-inclusive-or-operator-pipe.md b/docs/cpp/bitwise-inclusive-or-operator-pipe.md index d232bb18b9..5e759dc2e9 100644 --- a/docs/cpp/bitwise-inclusive-or-operator-pipe.md +++ b/docs/cpp/bitwise-inclusive-or-operator-pipe.md @@ -1,12 +1,12 @@ --- -title: "Bitwise inclusive OR operator: |" +title: "Bitwise inclusive OR operator: |" description: "The C++ standard language bitwise inclusive OR operator syntax and use." ms.date: 07/23/2020 f1_keywords: ["|", "bitor_cpp"] helpviewer_keywords: ["OR operator [C++], bitwise inclusive", "bitwise operators [C++], OR operator", "inclusive OR operator", "| operator"] ms.assetid: 4c8a6a68-d828-447d-875a-aedb4ce3aa9a --- -# Bitwise inclusive OR operator: | +# Bitwise inclusive OR operator: `|` ## Syntax @@ -18,7 +18,7 @@ The bitwise inclusive OR operator (**`|`**) compares each bit of its first opera Both operands to the operator must have integral types. The usual arithmetic conversions covered in [Standard Conversions](standard-conversions.md) are applied to the operands. -## Operator keyword for | +## Operator keyword for `|` C++ specifies **`bitor`** as an alternative spelling for **`|`**. In C, the alternative spelling is provided as a macro in the \ header. In C++, the alternative spelling is a keyword; use of \ or the C++ equivalent \ is deprecated. In Microsoft C++, the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is required to enable the alternative spelling. @@ -41,5 +41,5 @@ int main() { ## See also -[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C bitwise operators](../c-language/c-bitwise-operators.md) diff --git a/docs/cpp/break-statement-cpp.md b/docs/cpp/break-statement-cpp.md index 821fbad22a..1439e29ff9 100644 --- a/docs/cpp/break-statement-cpp.md +++ b/docs/cpp/break-statement-cpp.md @@ -4,21 +4,20 @@ title: "break Statement (C++)" ms.date: "11/04/2016" f1_keywords: ["break_cpp"] helpviewer_keywords: ["break keyword [C++]"] -ms.assetid: 63739928-8985-4b05-93ce-016322e6da3d --- -# break Statement (C++) +# `break` statement (C++) The **`break`** statement ends execution of the nearest enclosing loop or conditional statement in which it appears. Control passes to the statement that follows the end of the statement, if any. ## Syntax -``` +```cpp break; ``` ## Remarks -The **`break`** statement is used with the conditional [switch](../cpp/switch-statement-cpp.md) statement and with the [do](../cpp/do-while-statement-cpp.md), [for](../cpp/for-statement-cpp.md), and [while](../cpp/while-statement-cpp.md) loop statements. +The **`break`** statement is used with the conditional [`switch`](../cpp/switch-statement-cpp.md) statement and with the [`do`](../cpp/do-while-statement-cpp.md), [`for`](../cpp/for-statement-cpp.md), and [`while`](../cpp/while-statement-cpp.md) loop statements. In a **`switch`** statement, the **`break`** statement causes the program to execute the next statement outside the **`switch`** statement. Without a **`break`** statement, every statement from the matched **`case`** label to the end of the **`switch`** statement, including the **`default`** clause, is executed. @@ -58,7 +57,9 @@ int nums []{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; ``` ```Output -In each case: +1 +2 +3 1 2 3 @@ -93,8 +94,14 @@ int main() { ``` ```Output -In each case: -0123 +0 +1 +2 +3 +0 +1 +2 +3 ``` The following code shows how to use **`break`** in a switch statement. You must use **`break`** in every case if you want to handle each case separately; if you do not use **`break`**, the code execution falls through to the next case. diff --git a/docs/cpp/bstr-t-assign.md b/docs/cpp/bstr-t-assign.md index 565b248630..801be55d0a 100644 --- a/docs/cpp/bstr-t-assign.md +++ b/docs/cpp/bstr-t-assign.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: _bstr_t::Assign" title: "_bstr_t::Assign" +description: "Learn more about: _bstr_t::Assign" ms.date: 02/02/2021 f1_keywords: ["_bstr_t::Assign"] helpviewer_keywords: ["Assign method [C++]"] --- -# _`bstr_t::Assign` +# `_bstr_t::Assign` **Microsoft Specific** diff --git a/docs/cpp/c-cpp-language-and-standard-libraries.md b/docs/cpp/c-cpp-language-and-standard-libraries.md index a6f866c446..59218ff5e3 100644 --- a/docs/cpp/c-cpp-language-and-standard-libraries.md +++ b/docs/cpp/c-cpp-language-and-standard-libraries.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: C/C++ language and standard libraries reference" title: "C/C++ language and standard libraries reference" -ms.date: "08/13/2019" -ms.assetid: c26a6682-961a-43ef-ad33-2adc612f69ac +description: "Learn more about: C/C++ language and standard libraries reference" +ms.date: 09/11/2024 ms.topic: "overview" ms.custom: intro-overview --- @@ -17,7 +16,7 @@ You'll also find documentation for the C runtime library, the C++ standard libra [C language](../c-language/c-language-reference.md)\ Reference content for the Microsoft implementation of the C language. -[C++ language](../cpp/cpp-language-reference.md)\ +[C++ language](cpp-language-reference.md)\ Reference content for the Microsoft implementation of the C++ language. [C/C++ preprocessor](../preprocessor/c-cpp-preprocessor-reference.md)\ @@ -61,10 +60,13 @@ Classes that simplify the writing of programs that use data parallelism or task [OpenMP](../parallel/openmp/openmp-in-visual-cpp.md)\ Reference for the Microsoft implementation of the OpenMP API. +[Proxy library](https://github.com/microsoft/proxy)\ +A header-only C++20 library for using polymorphism in C++ without inheritance. For API reference information, see [Proxy 3 Specifications](https://microsoft.github.io/proxy/docs/specifications.html) + [SafeInt library](../safeint/safeint-library.md)\ A portable library that can be used with MSVC, GCC, or Clang to help prevent integer overflows. -[Data Access Libraries](../data/data-access-in-cpp.md) +[Data Access Libraries](../data/data-access-in-cpp.md)\ Libraries to support data access using ATL or MFC, and legacy services such as OLE DB and ODBC. ## Related articles diff --git a/docs/cpp/cast-operator-parens.md b/docs/cpp/cast-operator-parens.md index 29ed7a8bd9..a790aebacc 100644 --- a/docs/cpp/cast-operator-parens.md +++ b/docs/cpp/cast-operator-parens.md @@ -1,28 +1,30 @@ --- -description: "Learn more about: Cast Operator: ()" -title: "Cast Operator: ()" -ms.date: "11/04/2016" +description: "Learn more about: Cast operator: ()" +title: "Cast operator: ()" +ms.date: 06/30/2022 helpviewer_keywords: ["cast operators [C++]", "() cast operator"] ms.assetid: 4c99eb92-1b19-4a5d-9840-5d8c29b8453e --- -# Cast Operator: () +# Cast operator: `()` A type cast provides a method for explicit conversion of the type of an object in a specific situation. ## Syntax -``` -unary-expression ( type-name ) cast-expression -``` +*`cast-expression`*:\ + *`unary-expression`*\ + **`(`** *`type-name`* **`)`** *`cast-expression`* ## Remarks Any unary expression is considered a cast expression. -The compiler treats *cast-expression* as type *type-name* after a type cast has been made. Casts can be used to convert objects of any scalar type to or from any other scalar type. Explicit type casts are constrained by the same rules that determine the effects of implicit conversions. Additional restraints on casts may result from the actual sizes or representation of specific types. +The compiler treats *`cast-expression`* as type *`type-name`* after a type cast has been made. Casts can be used to convert objects of any scalar type to or from any other scalar type. Explicit type casts are constrained by the same rules that determine the effects of implicit conversions. Other restraints on casts may result from the actual sizes or representation of specific types. ## Examples +A standard cast conversion between built-in types: + ```cpp // expre_CastOperator.cpp // compile with: /EHsc @@ -41,6 +43,8 @@ int main() } ``` +A cast operator defined in a user-defined type: + ```cpp // expre_CastOperator2.cpp // The following sample shows how to define and use a cast operator. @@ -111,8 +115,8 @@ Raw Bytes after cast: Exciting ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
-[Explicit Type Conversion Operator: ()](../cpp/explicit-type-conversion-operator-parens.md)
-[Casting Operators](../cpp/casting-operators.md)
-[Cast Operators](../c-language/cast-operators.md) +[Expressions with unary operators](../cpp/expressions-with-unary-operators.md)\ +[C++ built-in operators, precedence and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ +[Explicit type conversion operator: `()`](../cpp/explicit-type-conversion-operator-parens.md)\ +[Casting operators (C++)](../cpp/casting-operators.md)\ +[Cast operators (C)](../c-language/cast-operators.md) diff --git a/docs/cpp/casting.md b/docs/cpp/casting.md index 20c8157beb..1a74c49398 100644 --- a/docs/cpp/casting.md +++ b/docs/cpp/casting.md @@ -1,36 +1,80 @@ --- -description: "Learn more about: Casting" title: "Casting" -ms.date: "11/19/2018" +description: "Learn more about: Casting in C++" +ms.date: 6/11/2024 helpviewer_keywords: ["casting [C++]", "coercion [C++]", "virtual functions [C++], in derived classes [C++]", "static cast operator", "dynamic cast operator", "polymorphic classes [C++]", "classes [C++], polymorphism"] -ms.assetid: 3dbeb06e-2f4b-4693-832d-624bc8ec95de +ai-usage: ai-assisted --- # Casting -The C++ language provides that if a class is derived from a base class containing virtual functions, a pointer to that base class type can be used to call the implementations of the virtual functions residing in the derived class object. A class containing virtual functions is sometimes called a "polymorphic class." +In C++, if a class is derived from a base class containing one or more virtual functions, a pointer to that base class type can be used to call virtual functions in the derived class object. A class containing virtual functions is sometimes called a "polymorphic class." -Since a derived class completely contains the definitions of all the base classes from which it is derived, it is safe to cast a pointer up the class hierarchy to any of these base classes. Given a pointer to a base class, it might be safe to cast the pointer down the hierarchy. It is safe if the object being pointed to is actually of a type derived from the base class. In this case, the actual object is said to be the "complete object." The pointer to the base class is said to point to a "subobject" of the complete object. For example, consider the class hierarchy shown in the following figure. - -![Diagram of a class hierarchy where C derives from B, which derives from A.](../cpp/media/vc38zz1.gif "Class hierarchy")
+![Diagram of a class hierarchy where C derives from B, which derives from A.](media/vc38zz1.gif "Class hierarchy")\ Class hierarchy -An object of type `C` could be visualized as shown in the following figure. +An object of type `C` can be visualized as follows: -![Diagram of Class C with subobjects B and A.](../cpp/media/vc38zz2.gif "Class C with subobjects B and A")
-Class C with sub-objects B and A +![Diagram of Class C with subobjects B and A.](media/vc38zz2.gif "Class C with subobjects B and A")\ +Class C with subobjects B and A -Given an instance of class `C`, there is a `B` subobject and an `A` subobject. The instance of `C`, including the `A` and `B` subobjects, is the "complete object." +Given an instance of class `C`, there's a `B` subobject and an `A` subobject. The instance of `C`, including the `A` and `B` subobjects, is the "complete object." -Using run-time type information, it is possible to check whether a pointer actually points to a complete object and can be safely cast to point to another object in its hierarchy. The [dynamic_cast](../cpp/dynamic-cast-operator.md) operator can be used to make these types of casts. It also performs the run-time check necessary to make the operation safe. +Because a derived class completely contains the definitions of all the base classes from which it's derived, it's safe to cast a pointer to any of its base classes (also called an upcast). Given a pointer to a base class, it may be safe to cast the pointer to an instance of a derived class (also called a downcast). -For conversion of nonpolymorphic types, you can use the [static_cast](../cpp/static-cast-operator.md) operator (this topic explains the difference between static and dynamic casting conversions, and when it is appropriate to use each). +Using run-time type information, it's possible to check whether a pointer actually points to a complete object and can be safely cast to point to another object in its hierarchy. The [dynamic_cast](dynamic-cast-operator.md) operator performs a run-time check to ensure that the operation is safe. It's better to design your class hierarchy so that you can use virtual functions to avoid the need for downcasting. However, if you must downcast, use `dynamic_cast` to ensure that the operation is safe. -This section covers the following topics: +For conversion of nonpolymorphic types, you can use the [static_cast](static-cast-operator.md) operator (this topic explains the difference between static and dynamic casting conversions, and when it's appropriate to use each). + +The following example demonstrates the use of `dynamic_cast` and `static_cast`: + +```cpp +#include + +class Base { +public: + virtual void print() { std::cout << "Base\n"; } +}; + +class Derived1 : public Base { +public: + void print() override { std::cout << "Derived1\n"; } +}; + +class Derived2 : public Base { +public: + void print() override { std::cout << "Derived2\n"; } +}; -- [Casting operators](../cpp/casting-operators.md) +class MostDerived : public Derived1, public Derived2 { +public: + void print() override { std::cout << "MostDerived\n"; } +}; + +int main() { + MostDerived md; + Base* b1 = static_cast(&md); // Upcast to Derived1 is safe + Base* b2 = static_cast(&md); // Upcast to Derived2 is safe + + // Downcast to MostDerived is ambiguous and unsafe + // MostDerived* md1 = static_cast(b1); // This won't compile + // MostDerived* md2 = static_cast(b2); // This won't compile + + // Correct way to downcast in this situation + MostDerived* md1 = dynamic_cast(b1); // This is safe + MostDerived* md2 = dynamic_cast(b2); // This is safe + + md1->print(); // Prints "MostDerived" + md2->print(); // Prints "MostDerived" + + return 0; +} +``` + +This section covers the following topics: -- [Run-time type information](../cpp/run-time-type-information.md) +- [Casting operators](casting-operators.md) +- [Run-time type information](run-time-type-information.md) ## See also -[Expressions](../cpp/expressions-cpp.md) +[Expressions](expressions-cpp.md) diff --git a/docs/cpp/char-wchar-t-char16-t-char32-t.md b/docs/cpp/char-wchar-t-char16-t-char32-t.md index 3b18753f07..5df11da266 100644 --- a/docs/cpp/char-wchar-t-char16-t-char32-t.md +++ b/docs/cpp/char-wchar-t-char16-t-char32-t.md @@ -2,11 +2,10 @@ description: "Learn more about: char, wchar_t, char8_t, char16_t, char32_t" title: "char, wchar_t, char8_t, char16_t, char32_t" ms.date: 04/23/2021 -ms.assetid: 6b33e9f5-455b-4e49-8f12-a150cbfe2e5b --- # char, wchar_t, char8_t, char16_t, char32_t -The types **`char`**, **`wchar_t`**, **`char8_t`**, **`char16_t`**, and **`char32_t`** are built-in types that represent alphanumeric characters, non-alphanumeric glyphs, and non-printing characters. +The types **`char`**, **`wchar_t`**, **`char8_t`**, **`char16_t`**, and **`char32_t`** are built-in types that represent alphanumeric characters, nonalphanumeric glyphs, and nonprinting characters. ## Syntax @@ -19,7 +18,7 @@ char32_t ch4{ U'a' }; ## Remarks -The **`char`** type was the original character type in C and C++. The **`char`** type can be used to store characters from the ASCII character set or any of the ISO-8859 character sets, and individual bytes of multi-byte characters such as Shift-JIS or the UTF-8 encoding of the Unicode character set. In the Microsoft compiler, **`char`** is an 8-bit type. It's a distinct type from both **`signed char`** and **`unsigned char`**. By default, variables of type **`char`** get promoted to **`int`** as if from type **`signed char`** unless the [`/J`](../build/reference/j-default-char-type-is-unsigned.md) compiler option is used. Under **`/J`**, they're treated as type **`unsigned char`** and get promoted to **`int`** without sign extension. +The **`char`** type was the original character type in C and C++. The **`char`** type stores characters from the ASCII character set or any of the ISO-8859 character sets, and individual bytes of multi-byte characters such as Shift-JIS or the UTF-8 encoding of the Unicode character set. In the Microsoft compiler, **`char`** is an 8-bit type. It's a distinct type from both **`signed char`** and **`unsigned char`**. By default, variables of type **`char`** get promoted to **`int`** as if from type **`signed char`** unless the [`/J`](../build/reference/j-default-char-type-is-unsigned.md) compiler option is used. Under **`/J`**, they're treated as type **`unsigned char`** and get promoted to **`int`** without sign extension. The type **`unsigned char`** is often used to represent a *byte*, which isn't a built-in type in C++. @@ -27,4 +26,6 @@ The **`wchar_t`** type is an implementation-defined wide character type. In the The **`char8_t`**, **`char16_t`**, and **`char32_t`** types represent 8-bit, 16-bit, and 32-bit wide characters, respectively. (**`char8_t`** is new in C++20 and requires the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or **`/std:c++latest`** compiler option.) Unicode encoded as UTF-8 can be stored in the **`char8_t`** type. Strings of **`char8_t`** and **`char`** type are referred to as *narrow* strings, even when used to encode Unicode or multi-byte characters. Unicode encoded as UTF-16 can be stored in the **`char16_t`** type, and Unicode encoded as UTF-32 can be stored in the **`char32_t`** type. Strings of these types and **`wchar_t`** are all referred to as *wide* strings, though the term often refers specifically to strings of **`wchar_t`** type. -In the C++ standard library, the `basic_string` type is specialized for both narrow and wide strings. Use `std::string` when the characters are of type **`char`**, `std::u8string` when the characters are of type **`char8_t`**, `std::u16string` when the characters are of type **`char16_t`**, `std::u32string` when the characters are of type **`char32_t`**, and `std::wstring` when the characters are of type **`wchar_t`**. Other types that represent text, including `std::stringstream` and `std::cout` have specializations for narrow and wide strings. +In the C++ standard library, the [`basic_string`](/cpp/standard-library/basic-string-class) type is specialized for both narrow and wide strings. Use `std::string` when the characters are of type **`char`**, `std::u8string` when the characters are of type **`char8_t`**, `std::u16string` when the characters are of type **`char16_t`**, `std::u32string` when the characters are of type **`char32_t`**, and `std::wstring` when the characters are of type **`wchar_t`**. + +Other types that represent text, including [`std::stringstream`](/cpp/standard-library/sstream-typedefs/#stringstream) and [`std::cout`](/cpp/standard-library/iostream#cout) have specializations for narrow and wide strings. diff --git a/docs/cpp/class-member-overview.md b/docs/cpp/class-member-overview.md index b2c25218e8..3d97b74bea 100644 --- a/docs/cpp/class-member-overview.md +++ b/docs/cpp/class-member-overview.md @@ -1,27 +1,27 @@ --- -description: "Learn more about: Class Member Overview" -title: "Class Member Overview" -ms.date: "11/04/2016" +description: "Learn more about: Class member overview" +title: "Class member overview" +ms.date: 07/01/2022 helpviewer_keywords: ["members [C++], types of class members", "members [C++]", "class members [C++], types of", "class members"] ms.assetid: 8802cfa9-705d-4f37-acde-245d6838010c --- -# Class Member Overview +# Class member overview -A class or struct consists of its members. The work that a class does is performed by its member functions. The state that it maintains is stored in its data members. Initialization of members is done by constructors, and cleanup work such as freeing of memory and releasing of resources is done by destructors. In C++11 and later, data members can (and usually should) be initialized at the point of declaration. +A `class` or `struct` consists of its members. The work that a class does is performed by its member functions. The state that it maintains is stored in its data members. Initialization of members is done by constructors, and cleanup work such as freeing of memory and releasing of resources is done by destructors. In C++11 and later, data members can (and usually should) be initialized at the point of declaration. ## Kinds of class members The full list of member categories is as follows: -- [Special Member Functions](special-member-functions.md). +- [Special member functions](special-member-functions.md). -- [Overview of Member Functions](overview-of-member-functions.md). +- [Overview of member functions](overview-of-member-functions.md). -- [Data members](static-members-cpp.md) including built-in types and other user defined types. +- [Mutable](mutable-data-members-cpp.md) and [static](static-members-cpp.md) data members, including built-in types and other user defined types. - Operators -- [Nested Class Declarations](nested-class-declarations.md) and.) +- [Nested class declarations](nested-class-declarations.md) and.) - [Unions](unions.md) @@ -47,7 +47,7 @@ class TestRun { // Start member list. - //The class interface accessible to all callers. + // The class interface accessible to all callers. public: // Use compiler-generated default constructor: TestRun() = default; @@ -83,31 +83,31 @@ int TestRun::_instances{ 0 }; ## Member accessibility -The members of a class are declared in the member list. The member list of a class may be divided into any number of **`private`**, **`protected`** and **`public`** sections using keywords known as access specifiers. A colon **:** must follow the access specifier. These sections need not be contiguous, that is, any of these keywords may appear several times in the member list. The keyword designates the access of all members up until the next access specifier or the closing brace. For more information, see [Member Access Control (C++)](../cpp/member-access-control-cpp.md). +The members of a class are declared in the member list. The member list of a class may be divided into any number of **`private`**, **`protected`** and **`public`** sections using keywords known as access specifiers. A colon **`:`** must follow the access specifier. These sections don't have to be contiguous; that is, any of these keywords may appear several times in the member list. The keyword designates the access of all members up until the next access specifier or the closing brace. For more information, see [Member access control (C++)](../cpp/member-access-control-cpp.md). ## Static members -A data member may be declared as static, which means all objects of the class have access to the same copy of it. A member function may be declared as static, in which case it can only access static data members of the class (and has no *this* pointer). For more information, see [Static Data Members](../cpp/static-members-cpp.md). +A data member may be declared as static, which means all objects of the class have access to the same copy of it. A member function may be declared as static, in which case it can only access static data members of the class (and has no **`this`** pointer). For more information, see [Static Data Members](../cpp/static-members-cpp.md). ## Special member functions -Special member functions are functions that are automatically provided by the compiler if you do not specify them in your source code. +Special member functions are functions that the compiler provides automatically if you don't specify them in your source code. -1. Default constructor +- Default constructor -1. Copy constructor +- Copy constructor -1. **(C++11)** Move constructor +- **(C++11)** Move constructor -1. Copy assignment operator +- Copy assignment operator -1. **(C++11)** Move assignment operator +- **(C++11)** Move assignment operator -1. Destructor +- Destructor -For more information, see [Special Member Functions](../cpp/special-member-functions.md). +For more information, see [Special member functions](../cpp/special-member-functions.md). -## Memberwise initialization +## Member-wise initialization In C++11 and later, non-static member declarators can contain initializers. @@ -131,9 +131,9 @@ int main() } ``` -If a member is assigned a value in a constructor, that value overwrites the value with which the member was initialized at the point of declaration. +If a member is assigned a value in a constructor, that value overwrites the value assigned at declaration. -There is only one shared copy of static data members for all objects of a given class type. Static data members must be defined and can be initialized at file scope. (For more information about static data members, see [Static Data Members](../cpp/static-members-cpp.md).) The following example shows how to perform these initializations: +There's only one shared copy of static data members for all objects of a given class type. Static data members must be defined and can be initialized at file scope. For more information about static data members, see [Static data members](../cpp/static-members-cpp.md). The following example shows how to initialize static data members: ```cpp // class_members2.cpp diff --git a/docs/cpp/class-templates.md b/docs/cpp/class-templates.md index d70081f21c..42bb8d2539 100644 --- a/docs/cpp/class-templates.md +++ b/docs/cpp/class-templates.md @@ -1,17 +1,17 @@ --- description: "Learn more about: Class Templates" title: "Class Templates" -ms.date: "11/04/2016" +ms.date: 06/30/2022 helpviewer_keywords: ["classes [C++], operating on type", "class templates", "templates, class templates"] ms.assetid: 633a53c8-24ee-4c23-8c88-e7c3cb0b7ac3 --- # Class Templates -This topic describes rules that are specific to C++ class templates. +This article describes rules that are specific to C++ class templates. ## Member functions of class templates -Member functions can be defined inside or outside of a class template. They are defined like function templates if defined outside the class template. +Member functions can be defined inside or outside of a class template. They're defined like function templates if defined outside the class template. ```cpp // member_function_templates1.cpp @@ -43,9 +43,9 @@ int main() } ``` -Note that just as with any template class member function, the definition of the class's constructor member function includes the template argument list twice. +As with any template class member function, the definition of the class's constructor member function includes the template argument list twice. -Member functions can themselves be function templates, specifying additional parameters, as in the following example. +Member functions can themselves be function templates and specify extra parameters, as in the following example. ```cpp // member_templates.cpp @@ -69,7 +69,7 @@ int main() ## Nested class templates -Templates can be defined within classes or class templates, in which case they are referred to as member templates. Member templates that are classes are referred to as nested class templates. Member templates that are functions are discussed in [Member Function Templates](../cpp/member-function-templates.md). +Templates can be defined within classes or class templates, in which case they're referred to as member templates. Member templates that are classes are referred to as nested class templates. Member templates that are functions are discussed in [Member Function Templates](../cpp/member-function-templates.md). Nested class templates are declared as class templates inside the scope of the outer class. They can be defined inside or outside of the enclosing class. @@ -83,7 +83,6 @@ using namespace std; class X { - template struct Y { @@ -109,6 +108,8 @@ int main() } ``` +The following code uses nested template type parameters to create nested class templates: + ```cpp // nested_class_template2.cpp // compile with: /EHsc @@ -174,16 +175,17 @@ int main() delete xc; } -//Output: +/* Output: X::Y::Y() X::Y::Y() 10 99 X::Y::~Y() X::Y::~Y() +*/ ``` -Local classes are not allowed to have member templates. +Local classes aren't allowed to have member templates. ## Template friends @@ -259,15 +261,16 @@ int main() { alpha3->print(); delete alpha3; } -//Output: +/* Output: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z +*/ ``` The next example involves a friend that has a template specialization. A function template specialization is automatically a friend if the original function template is a friend. -It is also possible to declare only the specialized version of the template as the friend, as the comment before the friend declaration in the following code indicates. If you do this, you must put the definition of the friend template specialization outside of the template class. +It's also possible to declare only the specialized version of the template as the friend, as the comment before the friend declaration in the following code indicates. If you declare a specialization as a friend, you must put the definition of the friend template specialization outside of the template class. ```cpp // template_friend2.cpp @@ -346,12 +349,13 @@ int main() Array a(10); f(a); } -//Output: +/* Output: 10 generic 10 int +*/ ``` -The next example shows a friend class template declared within a class template. The class template is then used as the template argument for the friend class. Friend class templates must be defined outside of the class template in which they are declared. Any specializations or partial specializations of the friend template are also friends of the original class template. +The next example shows a friend class template declared within a class template. The class template is then used as the template argument for the friend class. Friend class templates must be defined outside of the class template in which they're declared. Any specializations or partial specializations of the friend template are also friends of the original class template. ```cpp // template_friend3.cpp @@ -396,11 +400,12 @@ int main() x3->print(); x4->print(); } -//Output: +/* Output: 65 97 A a +*/ ``` ## Reuse of Template Parameters diff --git a/docs/cpp/clrcall.md b/docs/cpp/clrcall.md index 63c3326e48..c368132c78 100644 --- a/docs/cpp/clrcall.md +++ b/docs/cpp/clrcall.md @@ -20,7 +20,7 @@ When `/clr` (not `/clr:pure` or `/clr:safe`) is used and **__clrcall** is not us [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) implies that all functions and function pointers are **__clrcall** and the compiler will not permit a function inside the compiland to be marked anything other than **__clrcall**. When **/clr:pure** is used, **__clrcall** can only be specified on function pointers and external declarations. -You can directly call **__clrcall** functions from existing C++ code that was compiled by using **/clr** as long as that function has an MSIL implementation. **__clrcall** functions cannot be called directly from functions that have inline asm and call CPU-specific intrinisics, for example, even if those functions are compiled with `/clr`. +You can directly call **__clrcall** functions from existing C++ code that was compiled by using **/clr** as long as that function has an MSIL implementation. **__clrcall** functions cannot be called directly from functions that have inline asm and call CPU-specific intrinsics, for example, even if those functions are compiled with `/clr`. **__clrcall** function pointers are only meant to be used in the application domain in which they were created. Instead of passing **__clrcall** function pointers across application domains, use . For more information, see [Application Domains and Visual C++](../dotnet/application-domains-and-visual-cpp.md). @@ -38,7 +38,7 @@ int __clrcall Func1() { } // Func1 hasn't been used at this point (code has not been generated), -// so runtime returns the adddress of a stub to the function +// so runtime returns the address of a stub to the function int (__clrcall *pf)() = &Func1; // code calls the function, code generated at difference address diff --git a/docs/cpp/code-seg-declspec.md b/docs/cpp/code-seg-declspec.md index b4c26c8a03..888c24bbaf 100644 --- a/docs/cpp/code-seg-declspec.md +++ b/docs/cpp/code-seg-declspec.md @@ -1,50 +1,48 @@ --- description: "Learn more about: code_seg (__declspec)" title: "code_seg (__declspec)" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["code_seg_cpp"] helpviewer_keywords: ["code_seg __declspec keyword"] ms.assetid: ad3c1105-15d3-4e08-b7b9-e4bd9d7b6aa0 --- -# code_seg (__declspec) +# `__declspec(code_seg)` **Microsoft Specific** -The **code_seg** declaration attribute names an executable text segment in the .obj file in which the object code for the function or class member functions will be stored. +The **`code_seg`** declaration attribute names an executable text segment in the *`.obj`* file in which the object code for the function or class member functions is stored. ## Syntax -``` -__declspec(code_seg("segname")) declarator -``` +> **`__declspec(code_seg("`***`segname`***`"))`** *`declarator`* ## Remarks The `__declspec(code_seg(...))` attribute enables the placement of code into separate named segments that can be paged or locked in memory individually. You can use this attribute to control the placement of instantiated templates and compiler-generated code. -A *segment* is a named block of data in an .obj file that is loaded into memory as a unit. A *text segment* is a segment that contains executable code. The term *section* is often used interchangeably with segment. +A *segment* is a named block of data in an *`.obj`* file that is loaded into memory as a unit. A *text segment* is a segment that contains executable code. The term *section* is often used interchangeably with segment. -Object code that's generated when `declarator` is defined is put in the text segment specified by `segname`, which is a narrow-string literal. The name `segname` does not have to be specified in a [section](../preprocessor/section.md) pragma before it can be used in a declaration. By default, when no `code_seg` is specified, object code is put in a segment named .text. A **code_seg** attribute overrides any existing [#pragma code_seg](../preprocessor/code-seg.md) directive. A **code_seg** attribute applied to a member function overrides any **code_seg** attribute applied to the enclosing class. +Object code that's generated when `declarator` is defined is put in the text segment specified by `segname`, which is a narrow-string literal. The name `segname` doesn't have to be specified in a [section](../preprocessor/section.md) pragma before it can be used in a declaration. By default, when no `code_seg` is specified, object code is put in a segment named `.text`. A **`code_seg`** attribute overrides any existing [#pragma code_seg](../preprocessor/code-seg.md) directive. A **`code_seg`** attribute applied to a member function overrides any **`code_seg`** attribute applied to the enclosing class. -If an entity has a **code_seg** attribute, all declarations and definitions of the same entity must have identical **code_seg** attributes. If a base-class has a **code_seg** attribute, derived classes must have the same attribute. +If an entity has a **`code_seg`** attribute, all declarations and definitions of the same entity must have identical **`code_seg`** attributes. If a base-class has a **`code_seg`** attribute, derived classes must have the same attribute. -When a **code_seg** attribute is applied to a namespace-scope function or a member function, the object code for that function is put in the specified text segment. When this attribute is applied to a class, all member functions of the class and nested classes—this includes compiler-generated special member functions—are put in the specified segment. Locally defined classes—for example, classes defined in a member function body—do not inherit the **code_seg** attribute of the enclosing scope. +When a **`code_seg`** attribute is applied to a namespace-scope function or a member function, the object code for that function is put in the specified text segment. When this attribute is applied to a class, all member functions of the class and nested classes—including compiler-generated special member functions—are put in the specified segment. Locally defined classes—for example, classes defined in a member function body—don't inherit the **`code_seg`** attribute of the enclosing scope. -When a **code_seg** attribute is applied to a template class or template function, all implicit specializations of the template are put in the specified segment. Explicit or partial specializations do not inherit the **code_seg** attribute from the primary template. You may specify the same or a different **code_seg** attribute on the specialization. A **code_seg** attribute can’t be applied to an explicit template instantiation. +When a **`code_seg`** attribute is applied to a class template or function template, all implicit specializations of the template are put in the specified segment. Explicit or partial specializations don't inherit the **`code_seg`** attribute from the primary template. You may specify the same or a different **`code_seg`** attribute on the specialization. A **`code_seg`** attribute can't be applied to an explicit template instantiation. -By default, compiler-generated code such as a special member function is put in the .text segment. The `#pragma code_seg` directive does not override this default. Use the **code_seg** attribute on the class, class template, or function template to control where compiler-generated code is put. +By default, compiler-generated code such as a special member function is put in the `.text` segment. The `#pragma code_seg` directive doesn't override this default. Use the **`code_seg`** attribute on the class, class template, or function template to control where compiler-generated code is put. -Lambdas inherit **code_seg** attributes from their enclosing scope. To specify a segment for a lambda, apply a **code_seg** attribute after the parameter-declaration clause and before any mutable or exception specification, any trailing return-type specification, and the lambda body. For more information, see [Lambda Expression Syntax](../cpp/lambda-expression-syntax.md). This example defines a lambda in a segment named PagedMem: +Lambdas inherit **`code_seg`** attributes from their enclosing scope. To specify a segment for a lambda, apply a **`code_seg`** attribute after the parameter-declaration clause and before any mutable or exception specification, any trailing return-type specification, and the lambda body. For more information, see [Lambda Expression Syntax](../cpp/lambda-expression-syntax.md). This example defines a lambda in a segment named PagedMem: ```cpp auto Sqr = [](int t) __declspec(code_seg("PagedMem")) -> int { return t*t; }; ``` -Be careful when you put specific member functions—especially virtual member functions—in different segments. If you define a virtual function in a derived class that resides in a paged segment when the base class method resides in a non-paged segment, other base class methods or user code may assume that invoking the virtual method will not trigger a page fault. +Be careful when you put specific member functions—especially virtual member functions—in different segments. Say you define a virtual function in a derived class that resides in a paged segment when the base class method resides in a non-paged segment. Other base class methods or user code may assume that invoking the virtual method won't trigger a page fault. ## Example -This example shows how a **code_seg** attribute controls segment placement when implicit and explicit template specialization is used: +This example shows how a **`code_seg`** attribute controls segment placement when implicit and explicit template specialization is used: ```cpp // code_seg.cpp @@ -100,5 +98,5 @@ int main() ## See also -[__declspec](../cpp/declspec.md)
+[`__declspec`](../cpp/declspec.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp index e8577af7f1..dd50495388 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp @@ -1,6 +1,5 @@ void CComPtrDemo() { - HRESULT hr = CoInitialize(NULL); // Declare the smart pointer. diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_3.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_3.cpp index 820b1d6cd6..3bcf58d97e 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_3.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_3.cpp @@ -1,6 +1,5 @@ void COMAutomationSmartPointerDemo() { - CComPtr pWord; CComQIPtr pqi = pWord; CComDispatchDriver pDriver = pqi; diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp index af736b0495..753367555e 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp @@ -1,4 +1,3 @@ - // Use make_shared function when possible. auto sp1 = make_shared(L"The Beatles", L"Im Happy Just to Dance With You"); diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_5.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_5.cpp new file mode 100644 index 0000000000..f11f275dee --- /dev/null +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_5.cpp @@ -0,0 +1,29 @@ +void use_shared_ptr_by_value(shared_ptr sp); + +void use_shared_ptr_by_reference(shared_ptr& sp); +void use_shared_ptr_by_const_reference(const shared_ptr& sp); + +void use_raw_pointer(int* p); +void use_reference(int& r); + +void test() { + auto sp = make_shared(5); + + // Pass the shared_ptr by value. + // This invokes the copy constructor, increments the reference count, and makes the callee an owner. + use_shared_ptr_by_value(sp); + + // Pass the shared_ptr by reference or const reference. + // In this case, the reference count isn't incremented. + use_shared_ptr_by_reference(sp); + use_shared_ptr_by_const_reference(sp); + + // Pass the underlying pointer or a reference to the underlying object. + use_raw_pointer(sp.get()); + use_reference(*sp); + + // Pass the shared_ptr by value. + // This invokes the move constructor, which doesn't increment the reference count + // but in fact transfers ownership to the callee. + use_shared_ptr_by_value(move(sp)); +} diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp index 551c3f2f5b..2c02d593fb 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp @@ -1,4 +1,3 @@ - // Initialize two separate raw pointers. // Note that they contain the same values. auto song1 = new Song(L"Village People", L"YMCA"); diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp index e7ad81c8d5..29baefa191 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp @@ -1,4 +1,3 @@ - class MyClass { private: diff --git a/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_1.cpp b/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_1.cpp index 94a7422554..1ae88eee62 100644 --- a/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_1.cpp +++ b/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_1.cpp @@ -9,7 +9,6 @@ void UseRawPointer() delete pSong; } - void UseSmartPointer() { // Declare a smart pointer on stack and pass it the raw pointer. diff --git a/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp b/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp index 10ac9aab95..2c7e2716ed 100644 --- a/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp +++ b/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp @@ -1,4 +1,3 @@ - class LargeObject { public: diff --git a/docs/cpp/com-error-class.md b/docs/cpp/com-error-class.md index 579cbec9cc..90c26e6dd2 100644 --- a/docs/cpp/com-error-class.md +++ b/docs/cpp/com-error-class.md @@ -1,59 +1,59 @@ --- description: "Learn more about: _com_error Class" title: "_com_error Class" -ms.date: "11/04/2016" +ms.date: 11/17/2022 f1_keywords: ["_com_error"] helpviewer_keywords: ["_com_error class"] ms.assetid: 70dafa69-b1fb-4a5c-9249-e857e0793d42 --- -# _com_error Class +# `_com_error` class **Microsoft Specific** -A **_com_error** object represents an exception condition detected by the error-handling wrapper functions in the header files generated from the type library or by one of the COM support classes. The **_com_error** class encapsulates the HRESULT error code and any associated `IErrorInfo Interface` object. +A `_com_error` object represents an exception condition detected by the error-handling wrapper functions in the header files generated from the type library or by one of the COM support classes. The `_com_error` class encapsulates the `HRESULT` error code and any associated `IErrorInfo Interface` object. ### Construction | Name | Description | -|-|-| -|[_com_error](../cpp/com-error-com-error.md)|Constructs a **_com_error** object.| +|---|---| +| [`_com_error`](../cpp/com-error-com-error.md) | Constructs a `_com_error` object. | ### Operators | Name | Description | -|-|-| -|[operator =](../cpp/com-error-operator-equal.md)|Assigns an existing **_com_error** object to another.| +|---|---| +| [`operator =`](../cpp/com-error-operator-equal.md) | Assigns an existing `_com_error` object to another. | -### Extractor Functions +### Extractor functions | Name | Description | -|-|-| -|[Error](../cpp/com-error-error.md)|Retrieves the HRESULT passed to the constructor.| -|[ErrorInfo](../cpp/com-error-errorinfo.md)|Retrieves the `IErrorInfo` object passed to the constructor.| -|[WCode](../cpp/com-error-wcode.md)|Retrieves the 16-bit error code mapped into the encapsulated HRESULT.| +|---|---| +| [`Error`](../cpp/com-error-error.md) | Retrieves the `HRESULT` passed to the constructor. | +| [`ErrorInfo`](../cpp/com-error-errorinfo.md) | Retrieves the `IErrorInfo` object passed to the constructor. | +| [`WCode`](../cpp/com-error-wcode.md) | Retrieves the 16-bit error code mapped into the encapsulated `HRESULT`. | -### IErrorInfo Functions +### `IErrorInfo` functions | Name | Description | -|-|-| -|[Description](../cpp/com-error-description.md)|Calls `IErrorInfo::GetDescription` function.| -|[HelpContext](../cpp/com-error-helpcontext.md)|Calls `IErrorInfo::GetHelpContext` function.| -|[HelpFile](../cpp/com-error-helpfile.md)|Calls `IErrorInfo::GetHelpFile` function| -|[Source](../cpp/com-error-source.md)|Calls `IErrorInfo::GetSource` function.| -|[GUID](../cpp/com-error-guid.md)|Calls `IErrorInfo::GetGUID` function.| +|---|---| +| [`Description`](../cpp/com-error-description.md) | Calls `IErrorInfo::GetDescription` function. | +| [`HelpContext`](../cpp/com-error-helpcontext.md) | Calls `IErrorInfo::GetHelpContext` function. | +| [`HelpFile`](../cpp/com-error-helpfile.md) | Calls `IErrorInfo::GetHelpFile` function | +| [`Source`](../cpp/com-error-source.md) | Calls `IErrorInfo::GetSource` function. | +| [`GUID`](../cpp/com-error-guid.md) | Calls `IErrorInfo::GetGUID` function. | -### Format Message Extractor +### Format message extractor | Name | Description | -|-|-| -|[ErrorMessage](../cpp/com-error-errormessage.md)|Retrieves the string message for HRESULT stored in the **_com_error** object.| +|---|---| +| [`ErrorMessage`](../cpp/com-error-errormessage.md) | Retrieves the string message for `HRESULT` stored in the `_com_error` object. | -### ExepInfo.wCode to HRESULT Mappers +### `ExepInfo.wCode` to `HRESULT` mappers | Name | Description | -|-|-| -|[HRESULTToWCode](../cpp/com-error-hresulttowcode.md)|Maps 32-bit HRESULT to 16-bit `wCode`.| -|[WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)|Maps 16-bit `wCode` to 32-bit HRESULT.| +|---|---| +| [`HRESULTToWCode`](../cpp/com-error-hresulttowcode.md) | Maps 32-bit `HRESULT` to 16-bit `wCode`. | +| [`WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md) | Maps 16-bit `wCode` to 32-bit `HRESULT`. | **END Microsoft Specific** @@ -61,9 +61,9 @@ A **_com_error** object represents an exception condition detected by the error- **Header:** \ -`Lib:` comsuppw.lib or comsuppwd.lib (see [/Zc:wchar_t (wchar_t Is Native Type)](../build/reference/zc-wchar-t-wchar-t-is-native-type.md) for more information) +**Library:** *`comsuppw.lib`* or *`comsuppwd.lib`* (for more information, see [`/Zc:wchar_t` (wchar_t is native type)](../build/reference/zc-wchar-t-wchar-t-is-native-type.md)) ## See also -[Compiler COM Support Classes](../cpp/compiler-com-support-classes.md)
-[IErrorInfo Interface](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) +[Compiler COM support classes](../cpp/compiler-com-support-classes.md)\ +[`IErrorInfo` interface](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) diff --git a/docs/cpp/com-error-com-error.md b/docs/cpp/com-error-com-error.md index bb48c81b33..62702d9e5f 100644 --- a/docs/cpp/com-error-com-error.md +++ b/docs/cpp/com-error-com-error.md @@ -1,58 +1,58 @@ --- description: "Learn more about: _com_error::_com_error" title: "_com_error::_com_error" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::_com_error"] -helpviewer_keywords: ["_com_error method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error", "_com_error::_com_error"] +helpviewer_keywords: ["_com_error constructor [C++]"] ms.assetid: 0a69e46c-caab-49ef-b091-eee401253ce6 --- -# _com_error::_com_error +# `_com_error::_com_error` **Microsoft Specific** -Constructs a **_com_error** object. +Constructs a `_com_error` object. ## Syntax -``` +```cpp _com_error( HRESULT hr, IErrorInfo* perrinfo = NULL, - bool fAddRef=false) throw( ); + bool fAddRef = false) throw(); -_com_error( const _com_error& that ) throw( ); +_com_error( const _com_error& that ) throw(); ``` -#### Parameters +### Parameters -*hr*
-HRESULT information. +*`hr`*\ +`HRESULT` information. -*perrinfo*
+*`perrinfo`*\ `IErrorInfo` object. -*fAddRef*
-The default causes the constructor to call AddRef on a non-null `IErrorInfo` interface. This provides for correct reference counting in the common case where ownership of the interface is passed into the **_com_error** object, such as: +*`fAddRef`*\ +The default causes the constructor to not call AddRef on a non-null `IErrorInfo` interface. This behavior provides for correct reference counting in the common case where ownership of the interface is passed into the `_com_error` object, such as: ```cpp throw _com_error(hr, perrinfo); ``` -If you do not want your code to transfer ownership to the **_com_error** object, and the `AddRef` is required to offset the `Release` in the **_com_error** destructor, construct the object as follows: +If you don't want your code to transfer ownership to the `_com_error` object, and the `AddRef` is required to offset the `Release` in the `_com_error` destructor, construct the object as follows: ```cpp _com_error err(hr, perrinfo, true); ``` -*that*
-An existing **_com_error** object. +*`that`*\ +An existing `_com_error` object. ## Remarks -The first constructor creates a new object given an HRESULT and optional `IErrorInfo` object. The second creates a copy of an existing **_com_error** object. +The first constructor creates a new object given an `HRESULT` and optional `IErrorInfo` object. The second creates a copy of an existing `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-description.md b/docs/cpp/com-error-description.md index c351a52017..b60eb466ea 100644 --- a/docs/cpp/com-error-description.md +++ b/docs/cpp/com-error-description.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::Description" title: "_com_error::Description" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Description"] -helpviewer_keywords: ["Description method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Description", "_com_error::Description"] +helpviewer_keywords: ["_com_error Description method [C++]"] ms.assetid: 88191e24-4ee8-44a6-8c4c-3758e22e0548 --- -# _com_error::Description +# `_com_error::Description` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetDescription` function. ## Syntax -``` -_bstr_t Description( ) const; +```cpp +_bstr_t Description() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetDescription` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting `BSTR` is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Calls the `IErrorInfo::GetDescription` function and retrieves `IErrorInfo` recor ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-error.md b/docs/cpp/com-error-error.md index e784068c59..5301a4b1fb 100644 --- a/docs/cpp/com-error-error.md +++ b/docs/cpp/com-error-error.md @@ -1,33 +1,33 @@ --- description: "Learn more about: _com_error::Error" title: "_com_error::Error" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Error", "Error"] -helpviewer_keywords: ["Error method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Error", "_com_error::Error"] +helpviewer_keywords: ["_com_error Error method [C++]"] ms.assetid: b53a15fd-198e-4276-afcd-13439c4807f7 --- -# _com_error::Error +# `_com_error::Error` **Microsoft Specific** -Retrieves the HRESULT passed to the constructor. +Retrieves the `HRESULT` passed to the constructor. ## Syntax -``` -HRESULT Error( ) const throw( ); +```cpp +HRESULT Error() const throw(); ``` -## Return Value +## Return value -Raw HRESULT item passed into the constructor. +Raw `HRESULT` item passed into the constructor. ## Remarks -Retrieves the encapsulated HRESULT item in a `_com_error` object. +Retrieves the encapsulated `HRESULT` item in a `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-errorinfo.md b/docs/cpp/com-error-errorinfo.md index e352994c3a..b622817cb7 100644 --- a/docs/cpp/com-error-errorinfo.md +++ b/docs/cpp/com-error-errorinfo.md @@ -1,9 +1,9 @@ --- description: "Learn more about: _com_error::ErrorInfo" title: "_com_error::ErrorInfo" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::ErrorInfo"] -helpviewer_keywords: ["ErrorInfo method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::ErrorInfo", "_com_error::ErrorInfo"] +helpviewer_keywords: ["_com_error ErrorInfo method [C++]"] ms.assetid: 071b446c-4395-4fb8-bd3d-300a8b25f5cd --- # _com_error::ErrorInfo @@ -14,20 +14,20 @@ Retrieves the `IErrorInfo` object passed to the constructor. ## Syntax -``` +```cpp IErrorInfo * ErrorInfo( ) const throw( ); ``` -## Return Value +## Return value Raw `IErrorInfo` item passed into the constructor. ## Remarks -Retrieves the encapsulated `IErrorInfo` item in a `_com_error` object, or NULL if no `IErrorInfo` item is recorded. The caller must call `Release` on the returned object when finished using it. +Retrieves the encapsulated `IErrorInfo` item in a `_com_error` object, or `NULL` if no `IErrorInfo` item is recorded. The caller must call `Release` on the returned object when finished using it. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-errormessage.md b/docs/cpp/com-error-errormessage.md index 28e397f695..9b30f24e0a 100644 --- a/docs/cpp/com-error-errormessage.md +++ b/docs/cpp/com-error-errormessage.md @@ -1,33 +1,33 @@ --- description: "Learn more about: _com_error::ErrorMessage" title: "_com_error::ErrorMessage" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::ErrorMessage"] -helpviewer_keywords: ["ErrorMessage method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::ErrorMessage", "_com_error::ErrorMessage"] +helpviewer_keywords: ["_com_error ErrorMessage method [C++]"] ms.assetid: e47335b6-01af-4975-a841-121597479eb7 --- -# _com_error::ErrorMessage +# `_com_error::ErrorMessage` **Microsoft Specific** -Retrieves the string message for HRESULT stored in the `_com_error` object. +Retrieves the string message for `HRESULT` stored in the `_com_error` object. ## Syntax -``` -const TCHAR * ErrorMessage( ) const throw( ); +```cpp +const TCHAR * ErrorMessage() const throw(); ``` -## Return Value +## Return value -Returns the string message for the HRESULT recorded within the `_com_error` object. If the HRESULT is a mapped 16-bit [wCode](../cpp/com-error-wcode.md), then a generic message "`IDispatch error #`" is returned. If no message is found, then a generic message "`Unknown error #`" is returned. The returned string is either a Unicode or multibyte string, depending on the state of the _UNICODE macro. +Returns the string message for the `HRESULT` recorded within the `_com_error` object. If the `HRESULT` is a mapped 16-bit [`wCode`](../cpp/com-error-wcode.md), then a generic message "`IDispatch error #`" is returned. If no message is found, then a generic message "`Unknown error #`" is returned. The returned string is either a Unicode or multibyte string, depending on the state of the `_UNICODE` macro. ## Remarks -Retrieves the appropriate system message text for HRESULT recorded within the `_com_error` object. The system message text is obtained by calling the Win32 [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage) function. The string returned is allocated by the `FormatMessage` API, and it is released when the `_com_error` object is destroyed. +Retrieves the appropriate system message text for `HRESULT` recorded within the `_com_error` object. The system message text is obtained by calling the Win32 [`FormatMessage`](/windows/win32/api/winbase/nf-winbase-formatmessage) function. The string returned is allocated by the `FormatMessage` API, and it's released when the `_com_error` object is destroyed. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-guid.md b/docs/cpp/com-error-guid.md index 1b46f6c3c3..b035585333 100644 --- a/docs/cpp/com-error-guid.md +++ b/docs/cpp/com-error-guid.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::GUID" title: "_com_error::GUID" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::GUID"] -helpviewer_keywords: ["GUID method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::GUID", "_com_error::GUID"] +helpviewer_keywords: ["_com_error GUID method [C++]"] ms.assetid: e84c2c23-d02e-48f8-b776-9bd6937296d2 --- -# _com_error::GUID +# `_com_error::GUID` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetGUID` function. ## Syntax -``` -GUID GUID( ) const throw( ); +```cpp +GUID GUID() const throw(); ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetGUID` for the `IErrorInfo` object recorded within the `_com_error` object. If no `IErrorInfo` object is recorded, it returns `GUID_NULL`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetGUID` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-helpcontext.md b/docs/cpp/com-error-helpcontext.md index 28494a998b..28917755d8 100644 --- a/docs/cpp/com-error-helpcontext.md +++ b/docs/cpp/com-error-helpcontext.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::HelpContext" title: "_com_error::HelpContext" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HelpContext"] -helpviewer_keywords: ["HelpContext method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HelpContext", "_com_error::HelpContext"] +helpviewer_keywords: ["_com_error HelpContext method [C++]"] ms.assetid: 160d6443-9b68-4cf5-a540-50da951a5b2b --- -# _com_error::HelpContext +# `_com_error::HelpContext` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetHelpContext` function. ## Syntax -``` -DWORD HelpContext( ) const throw( ); +```cpp +DWORD HelpContext() const throw(); ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetHelpContext` for the `IErrorInfo` object recorded within the `_com_error` object. If no `IErrorInfo` object is recorded, it returns a zero. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetHelpContext` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-helpfile.md b/docs/cpp/com-error-helpfile.md index 6415cba6d3..917a3f7550 100644 --- a/docs/cpp/com-error-helpfile.md +++ b/docs/cpp/com-error-helpfile.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::HelpFile" title: "_com_error::HelpFile" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HelpFile"] -helpviewer_keywords: ["HelpFile method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HelpFile", "_com_error::HelpFile"] +helpviewer_keywords: ["_com_error HelpFile method [C++]"] ms.assetid: d2d3a0a1-6b62-4d52-a818-3cfae545a4af --- -# _com_error::HelpFile +# `_com_error::HelpFile` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetHelpFile` function. ## Syntax -``` +```cpp _bstr_t HelpFile() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetHelpFile` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting BSTR is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetHelpFile` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-hresulttowcode.md b/docs/cpp/com-error-hresulttowcode.md index 1cdfcce66c..166b4249d2 100644 --- a/docs/cpp/com-error-hresulttowcode.md +++ b/docs/cpp/com-error-hresulttowcode.md @@ -1,42 +1,42 @@ --- description: "Learn more about: _com_error::HRESULTToWCode" title: "_com_error::HRESULTToWCode" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HRESULTToWCode"] -helpviewer_keywords: ["HRESULTToWCode method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HRESULTToWCode", "_com_error::HRESULTToWCode"] +helpviewer_keywords: ["_com_error HRESULTToWCode method [C++]"] ms.assetid: ff3789f5-1047-41a0-b7e3-86dd8f638dba --- -# _com_error::HRESULTToWCode +# `_com_error::HRESULTToWCode` **Microsoft Specific** -Maps 32-bit HRESULT to 16-bit `wCode`. +Maps 32-bit `HRESULT` to 16-bit `wCode`. ## Syntax -``` +```cpp static WORD HRESULTToWCode( HRESULT hr -) throw( ); +) throw(); ``` -#### Parameters +### Parameters -*hr*
-The 32-bit HRESULT to be mapped to 16-bit `wCode`. +*`hr`*\ +The 32-bit `HRESULT` to be mapped to 16-bit `wCode`. -## Return Value +## Return value -16-bit `wCode` mapped from the 32-bit HRESULT. +16-bit `wCode` mapped from the 32-bit `HRESULT`. ## Remarks -See [_com_error::WCode](../cpp/com-error-wcode.md) for more information. +For more information, see [`_com_error::WCode`](../cpp/com-error-wcode.md). **END Microsoft Specific** ## See also -[_com_error::WCode](../cpp/com-error-wcode.md)
-[_com_error::WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::WCode`](../cpp/com-error-wcode.md)\ +[`_com_error::WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-member-functions.md b/docs/cpp/com-error-member-functions.md index 5f62a95fcb..6e84505cbf 100644 --- a/docs/cpp/com-error-member-functions.md +++ b/docs/cpp/com-error-member-functions.md @@ -1,14 +1,14 @@ --- description: "Learn more about: _com_error Member Functions" title: "_com_error Member Functions" -ms.date: "11/04/2016" +ms.date: 11/17/2022 helpviewer_keywords: ["_com_error class [C++], member functions"] ms.assetid: 39a73cdb-c12c-4d3b-a314-e3f6580f4d2d --- -# _com_error Member Functions +# `_com_error` member functions -For information about the **_com_error** member functions, see [_com_error Class](../cpp/com-error-class.md). +For information about the `_com_error` member functions, see [`_com_error` class](../cpp/com-error-class.md). ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-operator-equal.md b/docs/cpp/com-error-operator-equal.md index 8d4a2a2e4b..35748208fc 100644 --- a/docs/cpp/com-error-operator-equal.md +++ b/docs/cpp/com-error-operator-equal.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: _com_error::operator =" -title: "_com_error::operator =" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::operator="] -helpviewer_keywords: ["_com_error [C++]"] +description: "Learn more about: _com_error::operator=" +title: "_com_error::operator=" +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::operator=", "_com_error::operator="] +helpviewer_keywords: ["_com_error operator= [C++]"] ms.assetid: b9cc4094-d055-450c-b45a-0a95317488f8 --- -# _com_error::operator = +# `_com_error::operator=` **Microsoft Specific** @@ -14,19 +14,19 @@ Assigns an existing `_com_error` object to another. ## Syntax -``` -_com_error& operator = ( +```cpp +_com_error& operator=( const _com_error& that -) throw ( ); +) throw (); ``` -#### Parameters +### Parameters -*that*
+*`that`*\ A `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-operators.md b/docs/cpp/com-error-operators.md index cfe6340686..c4f8411660 100644 --- a/docs/cpp/com-error-operators.md +++ b/docs/cpp/com-error-operators.md @@ -1,14 +1,14 @@ --- description: "Learn more about: _com_error Operators" title: "_com_error Operators" -ms.date: "11/04/2016" +ms.date: 11/17/2022 helpviewer_keywords: ["_com_error class [C++], operators"] ms.assetid: 0c4a1532-59b7-41ea-8aeb-1c486898db4d --- -# _com_error Operators +# `_com_error` operators -For information about the **_com_error** operators, see [_com_error Class](../cpp/com-error-class.md). +For information about the `_com_error` operators, see [`_com_error` class](../cpp/com-error-class.md). ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-source.md b/docs/cpp/com-error-source.md index b2f53f049d..f14b30defb 100644 --- a/docs/cpp/com-error-source.md +++ b/docs/cpp/com-error-source.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::Source" title: "_com_error::Source" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Source"] -helpviewer_keywords: ["Source method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Source", "_com_error::Source"] +helpviewer_keywords: ["_com_error Source method [C++]"] ms.assetid: 55353741-fabc-4b0c-9787-b5a69bb189f2 --- -# _com_error::Source +# `_com_error::Source` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetSource` function. ## Syntax -``` +```cpp _bstr_t Source() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetSource` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting `BSTR` is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetSource` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-wcode.md b/docs/cpp/com-error-wcode.md index 964866741b..e3170bdbc7 100644 --- a/docs/cpp/com-error-wcode.md +++ b/docs/cpp/com-error-wcode.md @@ -1,35 +1,35 @@ --- description: "Learn more about: _com_error::WCode" title: "_com_error::WCode" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::WCode"] -helpviewer_keywords: ["WCode method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::WCode", "_com_error::WCode"] +helpviewer_keywords: ["_com_error WCode method [C++]"] ms.assetid: f3b21852-f8ea-4e43-bff1-11c2d35454c4 --- -# _com_error::WCode +# `_com_error::WCode` **Microsoft Specific** -Retrieves the 16-bit error code mapped into the encapsulated HRESULT. +Retrieves the 16-bit error code mapped into the encapsulated `HRESULT`. ## Syntax -``` -WORD WCode ( ) const throw( ); +```cpp +WORD WCode ( ) const throw(); ``` -## Return Value +## Return value -If the HRESULT is within the range 0x80040200 to 0x8004FFFF, the `WCode` method returns the HRESULT minus 0x80040200; otherwise, it returns zero. +If the `HRESULT` is within the range 0x80040200 to 0x8004FFFF, the `WCode` method returns the `HRESULT` minus 0x80040200; otherwise, it returns zero. ## Remarks -The `WCode` method is used to undo a mapping that happens in the COM support code. The wrapper for a `dispinterface` property or method calls a support routine that packages the arguments and calls `IDispatch::Invoke`. Upon return, if a failure HRESULT of `DISP_E_EXCEPTION` is returned, the error information is retrieved from the `EXCEPINFO` structure passed to `IDispatch::Invoke`. The error code can either be a 16-bit value stored in the `wCode` member of the `EXCEPINFO` structure or a full 32-bit value in the `scode` member of the `EXCEPINFO` structure. If a 16-bit `wCode` is returned, it must first be mapped to a 32-bit failure HRESULT. +The `WCode` method is used to undo a mapping that happens in the COM support code. The wrapper for a `dispinterface` property or method calls a support routine that packages the arguments and calls `IDispatch::Invoke`. Upon return, if a failure `HRESULT` of `DISP_E_EXCEPTION` is returned, the error information is retrieved from the `EXCEPINFO` structure passed to `IDispatch::Invoke`. The error code can either be a 16-bit value stored in the `wCode` member of the `EXCEPINFO` structure or a full 32-bit value in the `scode` member of the `EXCEPINFO` structure. If a 16-bit `wCode` is returned, it must first be mapped to a 32-bit failure `HRESULT`. **END Microsoft Specific** ## See also -[_com_error::HRESULTToWCode](../cpp/com-error-hresulttowcode.md)
-[_com_error::WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::HRESULTToWCode`](../cpp/com-error-hresulttowcode.md)\ +[`_com_error::WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-wcodetohresult.md b/docs/cpp/com-error-wcodetohresult.md index 13141e0df2..0e3bb9a678 100644 --- a/docs/cpp/com-error-wcodetohresult.md +++ b/docs/cpp/com-error-wcodetohresult.md @@ -1,42 +1,42 @@ --- description: "Learn more about: _com_error::WCodeToHRESULT" title: "_com_error::WCodeToHRESULT" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::WCodeToHRESULT"] -helpviewer_keywords: ["WCodeToHRESULT method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::WCodeToHRESULT", "_com_error::WCodeToHRESULT"] +helpviewer_keywords: ["_com_error WCodeToHRESULT method [C++]"] ms.assetid: 0ec43a4b-ca91-42d5-b270-3fde9c8412ea --- -# _com_error::WCodeToHRESULT +# `_com_error::WCodeToHRESULT` **Microsoft Specific** -Maps 16-bit *wCode* to 32-bit HRESULT. +Maps 16-bit *`wCode`* to 32-bit `HRESULT`. ## Syntax -``` +```cpp static HRESULT WCodeToHRESULT( WORD wCode -) throw( ); +) throw(); ``` -#### Parameters +### Parameters -*wCode*
-The 16-bit *wCode* to be mapped to 32-bit HRESULT. +*`wCode`*\ +The 16-bit *`wCode`* to be mapped to 32-bit `HRESULT`. -## Return Value +## Return value -32-bit HRESULT mapped from the 16-bit *wCode*. +32-bit `HRESULT` mapped from the 16-bit *`wCode`*. ## Remarks -See the [WCode](../cpp/com-error-wcode.md) member function. +See the [`WCode`](../cpp/com-error-wcode.md) member function. **END Microsoft Specific** ## See also -[_com_error::WCode](../cpp/com-error-wcode.md)
-[_com_error::HRESULTToWCode](../cpp/com-error-hresulttowcode.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::WCode`](../cpp/com-error-wcode.md)\ +[`_com_error::HRESULTToWCode`](../cpp/com-error-hresulttowcode.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-ptr-t-extractors.md b/docs/cpp/com-ptr-t-extractors.md index 416c396712..305a593e87 100644 --- a/docs/cpp/com-ptr-t-extractors.md +++ b/docs/cpp/com-ptr-t-extractors.md @@ -4,7 +4,6 @@ description: "Describes the extraction operators for the _com_ptr_t class." ms.date: 07/07/2020 f1_keywords: ["_com_ptr_t::operatorInterface&", "_com_ptr_t::operatorbool", "_com_ptr_t::operator->", "_com_ptr_t::operator*"] helpviewer_keywords: ["operator Interface& [C++]", "* operator [C++], with specific objects", "operator& [C++]", "operator* [C++]", "-> operator [C++], with specific objects", "& operator [C++], with specific objects", "operator Interface* [C++]", "operator * [C++]", "operator->", "operator bool", "extractors, _com_ptr_t class", "extractors [C++]"] -ms.assetid: 194b9e0e-123c-49ff-a187-0a7fcd68145a --- # `_com_ptr_t` Extractors @@ -14,7 +13,7 @@ Extract the encapsulated COM interface pointer. ## Syntax -```c++ +```cpp operator Interface*( ) const throw( ); operator Interface&( ) const; Interface& operator*( ) const; diff --git a/docs/cpp/comma-operator.md b/docs/cpp/comma-operator.md index 60bad789d8..a43a7c1193 100644 --- a/docs/cpp/comma-operator.md +++ b/docs/cpp/comma-operator.md @@ -6,7 +6,7 @@ f1_keywords: ["%2C"] helpviewer_keywords: ["comma operator"] ms.assetid: 38e0238e-19da-42ba-ae62-277bfdab6090 --- -# Comma Operator: , +# Comma Operator: `,` Allows grouping two statements where one is expected. @@ -55,6 +55,6 @@ int main () { ## See also -[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Sequential-Evaluation Operator](../c-language/sequential-evaluation-operator.md) diff --git a/docs/cpp/compiler-limits.md b/docs/cpp/compiler-limits.md index 9059716f9c..4fcdd08cfc 100644 --- a/docs/cpp/compiler-limits.md +++ b/docs/cpp/compiler-limits.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: Compiler Limits" title: "Compiler Limits" -ms.date: "05/06/2019" +description: "Learn more about: Compiler Limits" +ms.date: "06/05/2023" helpviewer_keywords: ["cl.exe compiler, limits for language constructs"] -ms.assetid: f1fa59c6-55b4-414b-80c5-3df72952160d --- # Compiler Limits -The C++ standard recommends limits for various language constructs. The following is a list of cases where the Microsoft C++ compiler does not implement the recommended limits. The first number is the limit that is established in the ISO C++ 11 standard (INCITS/ISO/IEC 14882-2011[2012], Annex B) and the second number is the limit implemented by the Microsoft C++ compiler: +The C++ standard recommends limits for various language constructs. The following is a list of cases where the Microsoft C++ compiler does not implement the recommended limits. The first number is the limit that is established in the ISO C++11 standard (INCITS/ISO/IEC 14882-2011[2012], Annex B) and the second number is the limit implemented by the Microsoft C++ compiler: - Nesting levels of compound statements, iteration control structures, and selection control structures - C++ standard: 256, Microsoft C++ compiler: depends on the combination of statements that are nested, but generally between 100 and 110. -- Parameters in one macro definition - C++ standard: 256, Microsoft C++ compiler: 127. +- Parameters in one macro definition - C++ standard: 256, Microsoft C++ compiler using `/Zc:preprocessor-`:127 or using `/Zc:preprocessor`:32767. -- Arguments in one macro invocation - C++ standard: 256, Microsoft C++ compiler 127. +- Arguments in one macro invocation - C++ standard: 256, Microsoft C++ compiler using `/Zc:preprocessor-`:127 or using `/Zc:preprocessor`:32767. - Characters in a character string literal or wide string literal (after concatenation) - C++ standard: 65536, Microsoft C++ compiler: 65535 single-byte characters, including the NULL terminator, and 32767 double-byte characters, including the NULL terminator. @@ -23,7 +22,7 @@ The C++ standard recommends limits for various language constructs. The followin - Scope qualifications of one identifier - C++ standard: 256, Microsoft C++ compiler: 127. -- Nested **`extern`** specifications - C++ standard: 1024, Microsoft C++ compiler: 9 (not counting the implicit **`extern`** specification in global scope, or 10, if you count the implicit **`extern`** specification in global scope.. +- Nested **`extern`** specifications - C++ standard: 1024, Microsoft C++ compiler: 9 (not counting the implicit **`extern`** specification in global scope, or 10, if you count the implicit **`extern`** specification in global scope. - Template arguments in a template declaration - C++ standard: 1024, Microsoft C++ compiler: 2046. diff --git a/docs/cpp/conditional-operator-q.md b/docs/cpp/conditional-operator-q.md index 511680d32d..4560531ba4 100644 --- a/docs/cpp/conditional-operator-q.md +++ b/docs/cpp/conditional-operator-q.md @@ -63,5 +63,5 @@ int main() { ## See also -[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Conditional-Expression Operator](../c-language/conditional-expression-operator.md) diff --git a/docs/cpp/const-and-volatile-pointers.md b/docs/cpp/const-and-volatile-pointers.md index cca4371b50..b786fcb6b4 100644 --- a/docs/cpp/const-and-volatile-pointers.md +++ b/docs/cpp/const-and-volatile-pointers.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: const and volatile pointers" title: "const and volatile pointers" +description: "Learn more about: const and volatile pointers" ms.date: "11/19/2019" helpviewer_keywords: ["volatile keyword [C++], and pointers", "pointers, and const", "pointers, and volatile", "const keyword [C++], volatile pointers"] -ms.assetid: 0c92dc6c-400e-4342-b345-63ddfe649d7e --- # const and volatile pointers @@ -117,5 +116,5 @@ int main() { ## See also -[Pointers](pointers-cpp.md) +[Pointers](pointers-cpp.md)\ [Raw pointers](raw-pointers.md) diff --git a/docs/cpp/const-cpp.md b/docs/cpp/const-cpp.md index 6870f4e166..fc2837dbf0 100644 --- a/docs/cpp/const-cpp.md +++ b/docs/cpp/const-cpp.md @@ -1,23 +1,50 @@ --- description: "Learn more about: const (C++)" title: "const (C++)" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["const_cpp"] helpviewer_keywords: ["const keyword [C++]"] ms.assetid: b21c0271-1ad0-40a0-b21c-5e812bba0318 --- -# const (C++) +# `const` (C++) -When modifying a data declaration, the **`const`** keyword specifies that the object or variable is not modifiable. +When it modifies a data declaration, the **`const`** keyword specifies that the object or variable isn't modifiable. ## Syntax -``` -const declaration ; -member-function const ; -``` - -## const values +> *`declarator`*:\ +>  *`ptr-declarator`*\ +>  *`noptr-declarator`* *`parameters-and-qualifiers`* *`trailing-return-type`*\ +> *`ptr-declarator`*:\ +>  *`noptr-declarator`*\ +>  *`ptr-operator`* *`ptr-declarator`*\ +> *`noptr-declarator`*:\ +>  *`declarator-id`* *`attribute-specifier-seq`*opt\ +>  *`noptr-declarator`* *`parameters-and-qualifiers`*\ +>  *`noptr-declarator`* **`[`** *`constant-expression`*opt **`]`** *`attribute-specifier-seq`*opt\ +>  **`(`** *`ptr-declarator`* **`)`**\ +> *`parameters-and-qualifiers`*:\ +>  **`(`** *`parameter-declaration-clause`* **`)`** *`cv-qualifier-seq`*opt\ +>  *`ref-qualifier`*opt *`noexcept-specifier`*opt *`attribute-specifier-seq`*opt\ +> *`trailing-return-type`*:\ +>  **`->`** *`type-id`*\ +> *`ptr-operator`*:\ +>  **`*`** *`attribute-specifier-seq`*opt *`cv-qualifier-seq`*opt\ +>  **`&`** *`attribute-specifier-seq`*opt\ +>  **`&&`** *`attribute-specifier-seq`*opt\ +>  *`nested-name-specifier`* **`*`** *`attribute-specifier-seq`*opt *`cv-qualifier-seq`*opt\ +> *`cv-qualifier-seq`*:\ +>  *`cv-qualifier`* *`cv-qualifier-seq`*opt\ +> *`cv-qualifier`*:\ +>  **`const`**\ +>  **`volatile`**\ +> *`ref-qualifier`*:\ +>  **`&`**\ +>  **`&&`**\ +> *`declarator-id`*:\ +>  **`...`**opt *`id-expression`* + +## `const` values The **`const`** keyword specifies that a variable's value is constant and tells the compiler to prevent the programmer from modifying it. @@ -30,7 +57,7 @@ int main() { } ``` -In C++, you can use the **`const`** keyword instead of the [#define](../preprocessor/hash-define-directive-c-cpp.md) preprocessor directive to define constant values. Values defined with **`const`** are subject to type checking, and can be used in place of constant expressions. In C++, you can specify the size of an array with a **`const`** variable as follows: +In C++, you can use the **`const`** keyword instead of the [`#define`](../preprocessor/hash-define-directive-c-cpp.md) preprocessor directive to define constant values. Values defined with **`const`** are subject to type checking, and can be used in place of constant expressions. In C++, you can specify the size of an array with a **`const`** variable as follows: ```cpp // constant_values2.cpp @@ -46,9 +73,10 @@ The **`const`** keyword can also be used in pointer declarations. ```cpp // constant_values3.cpp int main() { - char *mybuf = 0, *yourbuf; + char this_char{'a'}, that_char{'b'}; + char *mybuf = &this_char, *yourbuf = &that_char; char *const aptr = mybuf; - *aptr = 'a'; // OK + *aptr = 'c'; // OK aptr = yourbuf; // C3892 } ``` @@ -72,20 +100,20 @@ int main() { You can use pointers to constant data as function parameters to prevent the function from modifying a parameter passed through a pointer. -For objects that are declared as **`const`**, you can only call constant member functions. This ensures that the constant object is never modified. +For objects that are declared as **`const`**, you can only call constant member functions. The compiler ensures that the constant object is never modified. ```cpp birthday.getMonth(); // Okay birthday.setMonth( 4 ); // Error ``` -You can call either constant or nonconstant member functions for a nonconstant object. You can also overload a member function using the **`const`** keyword; this allows a different version of the function to be called for constant and nonconstant objects. +You can call either constant or non-constant member functions for a non-constant object. You can also overload a member function using the **`const`** keyword; this feature allows a different version of the function to be called for constant and non-constant objects. -You cannot declare constructors or destructors with the **`const`** keyword. +You can't declare constructors or destructors with the **`const`** keyword. -## const member functions +## `const` member functions -Declaring a member function with the **`const`** keyword specifies that the function is a "read-only" function that does not modify the object for which it is called. A constant member function cannot modify any non-static data members or call any member functions that aren't constant.To declare a constant member function, place the **`const`** keyword after the closing parenthesis of the argument list. The **`const`** keyword is required in both the declaration and the definition. +Declaring a member function with the **`const`** keyword specifies that the function is a "read-only" function that doesn't modify the object for which it's called. A constant member function can't modify any non-static data members or call any member functions that aren't constant. To declare a constant member function, place the **`const`** keyword after the closing parenthesis of the argument list. The **`const`** keyword is required in both the declaration and the definition. ```cpp // constant_member_function.cpp @@ -117,27 +145,32 @@ int main() } ``` -## C and C++ const differences +## C and C++ `const` differences -When you declare a variable as **`const`** in a C source code file, you do so as: +When you define a **`const`** variable in a C source code file, you do so as: -```cpp +```C const int i = 2; ``` You can then use this variable in another module as follows: -```cpp +```C extern const int i; ``` -But to get the same behavior in C++, you must declare your **`const`** variable as: +But to get the same behavior in C++, you must define your **`const`** variable as: ```cpp extern const int i = 2; ``` +Similar to C, you can then use this variable in another module as follows: + +```cpp +extern const int i; +``` -If you wish to declare an **`extern`** variable in a C++ source code file for use in a C source code file, use: +If you wish to define an **`extern`** variable in a C++ source code file for use in a C source code file, use: ```cpp extern "C" const int x=10; @@ -147,17 +180,17 @@ to prevent name mangling by the C++ compiler. ## Remarks -When following a member function's parameter list, the **`const`** keyword specifies that the function does not modify the object for which it is invoked. +When following a member function's parameter list, the **`const`** keyword specifies that the function doesn't modify the object for which it's invoked. -For more information on **`const`**, see the following topics: +For more information on **`const`**, see the following articles: -- [const and volatile Pointers](../cpp/const-and-volatile-pointers.md) +- [`const` and `volatile` pointers](../cpp/const-and-volatile-pointers.md) -- [Type Qualifiers (C Language Reference)](../c-language/type-qualifiers.md) +- [Type qualifiers (C language reference)](../c-language/type-qualifiers.md) -- [volatile](../cpp/volatile-cpp.md) +- [`volatile`](../cpp/volatile-cpp.md) -- [#define](../preprocessor/hash-define-directive-c-cpp.md) +- [`#define`](../preprocessor/hash-define-directive-c-cpp.md) ## See also diff --git a/docs/cpp/constexpr-cpp.md b/docs/cpp/constexpr-cpp.md index 4620d2775f..0096561562 100644 --- a/docs/cpp/constexpr-cpp.md +++ b/docs/cpp/constexpr-cpp.md @@ -61,7 +61,7 @@ The following rules apply to constexpr functions: - A **`constexpr`** function can be recursive. -- It can't be [virtual](../cpp/virtual-cpp.md). A constructor can't be defined as **`constexpr`** when the enclosing class has any virtual base classes. +- Before C++20, a **`constexpr`** function can't be [virtual](../cpp/virtual-cpp.md), and a constructor can't be defined as **`constexpr`** when the enclosing class has any virtual base classes. In C++20 and later, a **`constexpr`** function can be virtual. Visual Studio 2019 version 16.10 and later versions support **`constexpr`** virtual functions when you specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. - The body can be defined as `= default` or `= delete`. diff --git a/docs/cpp/constructors-cpp.md b/docs/cpp/constructors-cpp.md index e6ba74d04e..63259ed5a1 100644 --- a/docs/cpp/constructors-cpp.md +++ b/docs/cpp/constructors-cpp.md @@ -1,15 +1,15 @@ --- description: "Learn more about: Constructors (C++)" title: "Constructors (C++)" -ms.date: "12/27/2019" +ms.date: 02/07/2022 helpviewer_keywords: ["constructors [C++]", "objects [C++], creating", "instance constructors"] ms.assetid: 3e9f7211-313a-4a92-9584-337452e061a9 --- # Constructors (C++) -To customize how class members are initialized, or to invoke functions when an object of your class is created, define a *constructor*. A constructor has the same name as the class and no return value. You can define as many overloaded constructors as needed to customize initialization in various ways. Typically, constructors have public accessibility so that code outside the class definition or inheritance hierarchy can create objects of the class. But you can also declare a constructor as **`protected`** or **`private`**. +To customize how a class initializes its members, or to invoke functions when an object of your class is created, define a *constructor*. A constructor has the same name as the class and no return value. You can define as many overloaded constructors as needed to customize initialization in various ways. Typically, constructors have public accessibility so that code outside the class definition or inheritance hierarchy can create objects of the class. But you can also declare a constructor as **`protected`** or **`private`**. -Constructors can optionally take a member init list. This is a more efficient way to initialize class members than assigning values in the constructor body. The following example shows a class `Box` with three overloaded constructors. The last two use member init lists: +Constructors can optionally take a member initializer list. It's a more efficient way to initialize class members than assigning values in the constructor body. The following example shows a class `Box` with three overloaded constructors. The last two use member init lists: ```cpp class Box { @@ -54,15 +54,15 @@ int main() } ``` -- Constructors may be declared as **`inline`**, [explicit](#explicit_constructors), **`friend`** or [constexpr](#constexpr_constructors). +- Constructors may be declared as **`inline`**, [`explicit`](#explicit_constructors), [`friend`](friend-cpp.md), or [`constexpr`](#constexpr_constructors). - A constructor can initialize an object that has been declared as **`const`**, **`volatile`** or **`const volatile`**. The object becomes **`const`** after the constructor completes. -- To define a constructor in an implementation file, give it a qualified name as with any other member function: `Box::Box(){...}`. +- To define a constructor in an implementation file, give it a qualified name like any other member function: `Box::Box(){...}`. ## Member initializer lists -A constructor can optionally have a member initializer list, which initializes class members prior to execution of the constructor body. (Note that a member initializer list is not the same thing as an *initializer list* of type [std::initializer_list\](../standard-library/initializer-list-class.md).) +A constructor can optionally have a *member initializer list*, which initializes class members before the constructor body runs. (A member initializer list isn't the same thing as an *initializer list* of type [`std::initializer_list`](../standard-library/initializer-list-class.md).) -Using a member initializer list is preferred over assigning values in the body of the constructor because it directly initializes the member. In the following example shows the member initializer list consists of all the **identifier(argument)** expressions after the colon: +Prefer member initializer lists over assigning values in the body of the constructor. A member initializer list directly initializes the members. The following example shows the member initializer list, which consists of all the `identifier(argument)` expressions after the colon: ```cpp Box(int width, int length, int height) @@ -70,11 +70,11 @@ Using a member initializer list is preferred over assigning values in the body o {} ``` -The identifier must refer to a class member; it is initialized with the value of the argument. The argument can be one of the constructor parameters, a function call or a [std::initializer_list\](../standard-library/initializer-list-class.md). +The identifier must refer to a class member; it's initialized with the value of the argument. The argument can be one of the constructor parameters, a function call or a [`std::initializer_list`](../standard-library/initializer-list-class.md). **`const`** members and members of reference type must be initialized in the member initializer list. -Calls to parameterized base class constructors should be made in the initializer list to ensure the base class is fully initialized prior to execution of the derived constructor. +To ensure base classes are fully initialized before the derived constructor runs, call any parameterized base class constructors in the initializer list. ## Default constructors @@ -112,7 +112,7 @@ int main() { } ``` -If you rely on an implicit default constructor, be sure to initialize members in the class definition, as shown in the previous example. Without those initializers, the members would be uninitialized and the Volume() call would produce a garbage value. In general, it is good practice to initialize members in this way even when not relying on an implicit default constructor. +If you rely on an implicit default constructor, be sure to initialize members in the class definition, as shown in the previous example. Without those initializers, the members would be uninitialized and the Volume() call would produce a garbage value. In general, it's good practice to initialize members in this way even when not relying on an implicit default constructor. You can prevent the compiler from generating an implicit default constructor by defining it as [deleted](#explicitly_defaulted_and_deleted_constructors): @@ -121,7 +121,7 @@ You can prevent the compiler from generating an implicit default constructor by Box() = delete; ``` -A compiler-generated default constructor will be defined as deleted if any class members are not default-constructible. For example, all members of class type, and their class-type members, must have a default constructor and destructors that are accessible. All data members of reference type, as well as **`const`** members must have a default member initializer. +A compiler-generated default constructor will be defined as deleted if any class members aren't default-constructible. For example, all members of class type, and their class-type members, must have a default constructor and destructors that are accessible. All data members of reference type and all **`const`** members must have a default member initializer. When you call a compiler-generated default constructor and try to use parentheses, a warning is issued: @@ -132,9 +132,9 @@ myclass mc(); // warning C4930: prototyped function not called (was a variab } ``` -This is an example of the Most Vexing Parse problem. Because the example expression can be interpreted either as the declaration of a function or as the invocation of a default constructor, and because C++ parsers favor declarations over other things, the expression is treated as a function declaration. For more information, see [Most Vexing Parse](https://en.wikipedia.org/wiki/Most_vexing_parse). +This statement is an example of the "Most Vexing Parse" problem. You could interpret `myclass md();` either as a function declaration or as the invocation of a default constructor. Because C++ parsers favor declarations over other things, the expression is treated as a function declaration. For more information, see [Most Vexing Parse](https://en.wikipedia.org/wiki/Most_vexing_parse). -If any non-default constructors are declared, the compiler does not provide a default constructor: +If any non-default constructors are declared, the compiler doesn't provide a default constructor: ```cpp class Box { @@ -156,7 +156,7 @@ int main(){ } ``` -If a class has no default constructor, an array of objects of that class cannot be constructed by using square-bracket syntax alone. For example, given the previous code block, an array of Boxes cannot be declared like this: +If a class has no default constructor, an array of objects of that class can't be constructed by using square-bracket syntax alone. For example, given the previous code block, an array of Boxes can't be declared like this: ```cpp Box boxes[3]; // C2512: no appropriate default constructor available @@ -172,7 +172,7 @@ For more information, see [Initializers](initializers.md). ## Copy constructors -A *copy constructor* initializes an object by copying the member values from an object of the same type. If your class members are all simple types such as scalar values, the compiler-generated copy constructor is sufficient and you do not need to define your own. If your class requires more complex initialization, then you need to implement a custom copy constructor. For example, if a class member is a pointer then you need to define a copy constructor to allocate new memory and copy the values from the other's pointed-to object. The compiler-generated copy constructor simply copies the pointer, so that the new pointer still points to the other's memory location. +A *copy constructor* initializes an object by copying the member values from an object of the same type. If your class members are all simple types such as scalar values, the compiler-generated copy constructor is sufficient and you don't need to define your own. If your class requires more complex initialization, then you need to implement a custom copy constructor. For example, if a class member is a pointer then you need to define a copy constructor to allocate new memory and copy the values from the other's pointed-to object. The compiler-generated copy constructor simply copies the pointer, so that the new pointer still points to the other's memory location. A copy constructor may have one of these signatures: @@ -198,13 +198,13 @@ Attempting to copy the object produces error *C2280: attempting to reference a d ## Move constructors -A *move constructor* is a special member function that moves ownership of an existing object's data to a new variable without copying the original data. It takes an rvalue reference as its first parameter, and any additional parameters must have default values. Move constructors can significantly increase your program's efficiency when passing around large objects. +A *move constructor* is a special member function that moves ownership of an existing object's data to a new variable without copying the original data. It takes an rvalue reference as its first parameter, and any later parameters must have default values. Move constructors can significantly increase your program's efficiency when passing around large objects. ```cpp Box(Box&& other); ``` -The compiler chooses a move constructor in certain situations where the object is being initialized by another object of the same type that is about to be destroyed and no longer needs its resources. The following example shows one case when a move constructor is selected by overload resolution. In the constructor that calls `get_Box()`, the returned value is an *xvalue* (eXpiring value). It is not assigned to any variable and is therefore about to go out of scope. To provide motivation for this example, let's give Box a large vector of strings that represent its contents. Rather than copying the vector and its strings, the move constructor "steals" it from the expiring value "box" so that the vector now belongs to the new object. The call to `std::move` is all that's needed because both `vector` and `string` classes implement their own move constructors. +The compiler chooses a move constructor when the object is initialized by another object of the same type, if the other object is about to be destroyed and no longer needs its resources. The following example shows one case when a move constructor is selected by overload resolution. In the constructor that calls `get_Box()`, the returned value is an *xvalue* (eXpiring value). It's not assigned to any variable and is therefore about to go out of scope. To provide motivation for this example, let's give Box a large vector of strings that represent its contents. Rather than copying the vector and its strings, the move constructor "steals" it from the expiring value "box" so that the vector now belongs to the new object. The call to `std::move` is all that's needed because both `vector` and `string` classes implement their own move constructors. ```cpp #include @@ -271,9 +271,9 @@ int main() } ``` -If a class does not define a move constructor, the compiler generates an implicit one if there is no user-declared copy constructor, copy assignment operator, move assignment operator, or destructor. If no explicit or implicit move constructor is defined, operations that would otherwise use a move constructor use the copy constructor instead. If a class declares a move constructor or move assignment operator, the implicitly declared copy constructor is defined as deleted. +If a class doesn't define a move constructor, the compiler generates an implicit one if there's no user-declared copy constructor, copy assignment operator, move assignment operator, or destructor. If no explicit or implicit move constructor is defined, operations that would otherwise use a move constructor use the copy constructor instead. If a class declares a move constructor or move assignment operator, the implicitly declared copy constructor is defined as deleted. -An implicitly declared move constructor is defined as deleted if any members that are class types lack a destructor or the compiler cannot determine which constructor to use for the move operation. +An implicitly declared move constructor is defined as deleted if any members that are class types lack a destructor or if the compiler can't determine which constructor to use for the move operation. For more information about how to write a non-trivial move constructor, see [Move Constructors and Move Assignment Operators (C++)](../cpp/move-constructors-and-move-assignment-operators-cpp.md). @@ -282,7 +282,7 @@ For more information about how to write a non-trivial move constructor, see [Mov You can explicitly *default* copy constructors, default constructors, move constructors, copy assignment operators, move assignment operators, and destructors. You can explicitly *delete* all of the special member functions. ```cpp -class Box +class Box2 { public: Box2() = delete; @@ -300,17 +300,17 @@ For more information, see [Explicitly Defaulted and Deleted Functions](../cpp/ex A constructor may be declared as [constexpr](constexpr-cpp.md) if -- it is either declared as defaulted or else it satisfies all the conditions for [constexpr functions](constexpr-cpp.md#constexpr_functions) in general; +- it's either declared as defaulted or else it satisfies all the conditions for [constexpr functions](constexpr-cpp.md#constexpr_functions) in general; - the class has no virtual base classes; - each of the parameters is a [literal type](trivial-standard-layout-and-pod-types.md#literal_types); -- the body is not a function try-block; -- all non-static data members and base class sub-objects are initialized; +- the body isn't a function try-block; +- all non-static data members and base class subobjects are initialized; - if the class is (a) a union having variant members, or (b) has anonymous unions, only one of the union members is initialized; -- every non-static data member of class type, and all base-class sub-objects have a constexpr constructor +- every non-static data member of class type, and all base-class subobjects have a constexpr constructor ## Initializer list constructors -If a constructor takes a [std::initializer_list\](../standard-library/initializer-list-class.md) as its parameter, and any other parameters have default arguments, that constructor will be selected in overload resolution when the class is instantiated through direct initialization. You can use the initializer_list to initialize any member that can accept it. For example, assume the Box class (shown previously) has a `std::vector` member `m_contents`. You can provide a constructor like this: +If a constructor takes a [`std::initializer_list`](../standard-library/initializer-list-class.md) as its parameter, and any other parameters have default arguments, that constructor is selected in overload resolution when the class is instantiated through direct initialization. You can use the initializer_list to initialize any member that can accept it. For example, assume the Box class (shown previously) has a `std::vector` member `m_contents`. You can provide a constructor like this: ```cpp Box(initializer_list list, int w = 0, int h = 0, int l = 0) @@ -333,7 +333,7 @@ If a class has a constructor with a single parameter, or if all parameters excep Box(int size): m_width(size), m_length(size), m_height(size){} ``` -It is possible to initialize a Box like this: +It's possible to initialize a Box like this: ```cpp Box b = 42; @@ -375,7 +375,7 @@ A constructor performs its work in this order: 1. It executes any code in its function body. -The following example shows the order in which base class and member constructors are called in the constructor for a derived class. First, the base constructor is called, then the base-class members are initialized in the order in which they appear in the class declaration, and then the derived constructor is called. +The following example shows the order in which base class and member constructors are called in the constructor for a derived class. First, the base constructor is called. Then, the base-class members are initialized in the order in which they appear in the class declaration. Finally, the derived constructor is called. ```cpp #include @@ -429,7 +429,7 @@ DerivedContainer ctor A derived class constructor always calls a base class constructor, so that it can rely on completely constructed base classes before any extra work is done. The base class constructors are called in order of derivation—for example, if `ClassA` is derived from `ClassB`, which is derived from `ClassC`, the `ClassC` constructor is called first, then the `ClassB` constructor, then the `ClassA` constructor. -If a base class does not have a default constructor, you must supply the base class constructor parameters in the derived class constructor: +If a base class doesn't have a default constructor, you must supply the base class constructor parameters in the derived class constructor: ```cpp class Box { @@ -468,7 +468,7 @@ If a constructor throws an exception, the order of destruction is the reverse of 1. Base class and member objects are destroyed, in the reverse order of declaration. -1. If the constructor is non-delegating, all fully-constructed base class objects and members are destroyed. However, because the object itself is not fully constructed, the destructor is not run. +1. If the constructor is non-delegating, all fully constructed base class objects and members are destroyed. However, because the object itself isn't fully constructed, the destructor isn't run. ## Derived constructors and extended aggregate initialization @@ -492,7 +492,7 @@ Derived d2 {}; // OK in C++14: Calls Derived::Derived() // which can call Base ctor. ``` -In C++17, `Derived` is now considered an aggregate type. It means that the initialization of `Base` via the private default constructor happens directly, as part of the extended aggregate initialization rule. Previously, the `Base` private constructor was called via the `Derived` constructor, and it succeeded because of the friend declaration. +In C++17, `Derived` is now considered an aggregate type. It means that the initialization of `Base` via the private default constructor happens directly, as part of the extended aggregate initialization rule. Previously, the `Base` private constructor was called via the `Derived` constructor, and it succeeded because of the `friend` declaration. The following example shows C++17 behavior in Visual Studio 2017 and later in **`/std:c++17`** mode: @@ -512,13 +512,13 @@ struct Derived : Base { Derived d1; // OK. No aggregate init involved. -Derived d2 {}; // error C2248: 'Base::Base': cannot access +Derived d2 {}; // error C2248: 'Base::Base': can't access // private member declared in class 'Base' ``` ### Constructors for classes that have multiple inheritance -If a class is derived from multiple base classes, the base class constructors are invoked in the order in which they are listed in the declaration of the derived class: +If a class is derived from multiple base classes, the base class constructors are invoked in the order in which they're listed in the declaration of the derived class: ```cpp #include @@ -560,7 +560,7 @@ DerivedClass ctor ## Delegating constructors -A *delegating constructor* calls a different constructor in the same class to do some of the work of initialization. This is useful when you have multiple constructors that all have to perform similar work. You can write the main logic in one constructor and invoke it from others. In the following trivial example, Box(int) delegates its work to Box(int,int,int): +A *delegating constructor* calls a different constructor in the same class to do some of the work of initialization. This feature is useful when you have multiple constructors that all have to perform similar work. You can write the main logic in one constructor and invoke it from others. In the following trivial example, Box(int) delegates its work to Box(int,int,int): ```cpp class Box { @@ -635,7 +635,7 @@ Derived d4 calls: Base()*/ ::: moniker range=">=msvc-150" -**Visual Studio 2017 and later**: The **`using`** statement in **`/std:c++17`** mode and later brings into scope all constructors from the base class except those that have an identical signature to constructors in the derived class. In general, it is best to use inheriting constructors when the derived class declares no new data members or constructors. +**Visual Studio 2017 and later**: The **`using`** statement in **`/std:c++17`** mode and later brings into scope all constructors from the base class except ones that have an identical signature to constructors in the derived class. In general, it's best to use inheriting constructors when the derived class declares no new data members or constructors. ::: moniker-end @@ -649,7 +649,7 @@ class Derived : T { }; ``` -A deriving class cannot inherit from multiple base classes if those base classes have constructors that have an identical signature. +A deriving class can't inherit from multiple base classes if those base classes have constructors that have an identical signature. ## Constructors and composite classes diff --git a/docs/cpp/copy-constructors-and-copy-assignment-operators-cpp.md b/docs/cpp/copy-constructors-and-copy-assignment-operators-cpp.md index fbc3b27ae1..e732959c79 100644 --- a/docs/cpp/copy-constructors-and-copy-assignment-operators-cpp.md +++ b/docs/cpp/copy-constructors-and-copy-assignment-operators-cpp.md @@ -1,18 +1,18 @@ --- -description: "Learn more about: Copy Constructors and Copy Assignment Operators (C++)" -title: "Copy Constructors and Copy Assignment Operators (C++)" -ms.date: "11/04/2016" +description: "Learn more about: Copy constructors and copy assignment operators (C++)" +title: "Copy constructors and copy assignment operators (C++)" +ms.date: 02/11/2022 helpviewer_keywords: ["= operator [C++], copying objects", "assignment statements [C++], copying objects", "assignment operators [C++], for copying objects", "objects [C++], copying", "initializing objects, by copying objects", "copying objects", "assigning values to copy objects"] ms.assetid: a94fe1f9-0289-4fb9-8633-77c654002c0d --- -# Copy Constructors and Copy Assignment Operators (C++) +# Copy constructors and copy assignment operators (C++) > [!NOTE] > Starting in C++11, two kinds of assignment are supported in the language: *copy assignment* and *move assignment*. In this article "assignment" means copy assignment unless explicitly stated otherwise. For information about move assignment, see [Move Constructors and Move Assignment Operators (C++)](move-constructors-and-move-assignment-operators-cpp.md). > > Both the assignment operation and the initialization operation cause objects to be copied. -- **Assignment**: When one object's value is assigned to another object, the first object is copied to the second object. Therefore, +- **Assignment**: When one object's value is assigned to another object, the first object is copied to the second object. So, this code copies the value of `b` into `a`: ```cpp Point a, b; @@ -20,9 +20,7 @@ ms.assetid: a94fe1f9-0289-4fb9-8633-77c654002c0d a = b; ``` - causes the value of `b` to be copied to `a`. - -- **Initialization**: Initialization occurs when a new object is declared, when arguments are passed to functions by value, or when values are returned from functions by value. +- **Initialization**: Initialization occurs when you declare a new object, when you pass function arguments by value, or when you return by value from a function. You can define the semantics of "copy" for objects of class type. For example, consider this code: @@ -33,22 +31,23 @@ b.Open( "FILE2.DAT" ); b = a; ``` -The preceding code could mean "copy the contents of FILE1.DAT to FILE2.DAT" or it could mean "ignore FILE2.DAT and make `b` a second handle to FILE1.DAT." You must attach appropriate copying semantics to each class, as follows. +The preceding code could mean "copy the contents of FILE1.DAT to FILE2.DAT" or it could mean "ignore FILE2.DAT and make `b` a second handle to FILE1.DAT." You must attach appropriate copying semantics to each class, as follows: -- By using the assignment operator **operator=** together with a reference to the class type as the return type and the parameter that is passed by **`const`** reference—for example `ClassName& operator=(const ClassName& x);`. +- Use an assignment operator **`operator=`** that returns a reference to the class type and takes one parameter that's passed by **`const`** reference—for example `ClassName& operator=(const ClassName& x);`. -- By using the copy constructor. +- Use the copy constructor. -If you do not declare a copy constructor, the compiler generates a member-wise copy constructor for you. If you do not declare a copy assignment operator, the compiler generates a member-wise copy assignment operator for you. Declaring a copy constructor does not suppress the compiler-generated copy assignment operator, nor vice versa. If you implement either one, we recommend that you also implement the other one so that the meaning of the code is clear. +If you don't declare a copy constructor, the compiler generates a member-wise copy constructor for you. Similarly, if you don't declare a copy assignment operator, the compiler generates a member-wise copy assignment operator for you. Declaring a copy constructor doesn't suppress the compiler-generated copy assignment operator, and vice-versa. If you implement either one, we recommend that you implement the other one, too. When you implement both, the meaning of the code is clear. -The copy constructor takes an argument of type class-name&, where *class-name* is the name of the class for which the constructor is defined. For example: +The copy constructor takes an argument of type `ClassName&`, where *`ClassName`* is the name of the class. For example: ```cpp // spec1_copying_class_objects.cpp class Window { public: - Window( const Window& ); // Declare copy constructor. + Window( const Window& ); // Declare copy constructor. + Window& operator=(const Window& x); // Declare copy assignment. // ... }; @@ -58,19 +57,19 @@ int main() ``` > [!NOTE] -> Make the type of the copy constructor's argument **`const`** class-name& whenever possible. This prevents the copy constructor from accidentally changing the object from which it is copying. It also enables copying from **`const`** objects. +> Make the type of the copy constructor's argument `const ClassName&` whenever possible. This prevents the copy constructor from accidentally changing the copied object. It also lets you copy from **`const`** objects. ## Compiler generated copy constructors Compiler-generated copy constructors, like user-defined copy constructors, have a single argument of type "reference to *class-name*." An exception is when all base classes and member classes have copy constructors declared as taking a single argument of type **`const`** class-name&. In such a case, the compiler-generated copy constructor's argument is also **`const`**. -When the argument type to the copy constructor is not **`const`**, initialization by copying a **`const`** object generates an error. The reverse is not true: If the argument is **`const`**, you can initialize by copying an object that is not **`const`**. +When the argument type to the copy constructor isn't **`const`**, initialization by copying a **`const`** object generates an error. The reverse isn't true: If the argument is **`const`**, you can initialize by copying an object that's not **`const`**. -Compiler-generated assignment operators follow the same pattern with regard to **const.** They take a single argument of type class-name& unless the assignment operators in all base and member classes take arguments of type **`const`** class-name&. In this case, the class's generated assignment operator takes a **`const`** argument. +Compiler-generated assignment operators follow the same pattern for **`const`**. They take a single argument of type `ClassName&` unless the assignment operators in all base and member classes take arguments of type `const ClassName&`. In this case, the generated assignment operator for the class takes a **`const`** argument. > [!NOTE] -> When virtual base classes are initialized by copy constructors, compiler-generated or user-defined, they are initialized only once: at the point when they are constructed. +> When virtual base classes are initialized by copy constructors, whether compiler-generated or user-defined, they're initialized only once: at the point when they are constructed. -The implications are similar to those of the copy constructor. When the argument type is not **`const`**, assignment from a **`const`** object generates an error. The reverse is not true: If a **`const`** value is assigned to a value that is not **`const`**, the assignment succeeds. +The implications are similar to the copy constructor. When the argument type isn't **`const`**, assignment from a **`const`** object generates an error. The reverse isn't true: If a **`const`** value is assigned to a value that's not **`const`**, the assignment succeeds. For more information about overloaded assignment operators, see [Assignment](../cpp/assignment.md). diff --git a/docs/cpp/cpp-bit-fields.md b/docs/cpp/cpp-bit-fields.md index c175d82314..9f71ee362e 100644 --- a/docs/cpp/cpp-bit-fields.md +++ b/docs/cpp/cpp-bit-fields.md @@ -3,7 +3,6 @@ description: "Learn more about: C++ Bit Fields" title: "C++ Bit Fields" ms.date: "11/19/2018" helpviewer_keywords: ["bitfields [C++]", "fields [C++], bit", "bit fields"] -ms.assetid: 6f4b62e3-cc1d-4e5d-bf34-05904104f71a --- # C++ Bit Fields @@ -15,7 +14,7 @@ Classes and structures can contain members that occupy less storage than an inte ## Remarks -The (optional) *declarator* is the name by which the member is accessed in the program. It must be an integral type (including enumerated types). The *constant-expression* specifies the number of bits the member occupies in the structure. Anonymous bit fields — that is, bit-field members with no identifier — can be used for padding. +The (optional) *declarator* is the name by which the member is accessed in the program. It must be an integral type (including enumerated types). The *constant-expression* specifies the number of bits the member occupies in the structure. Anonymous bit fields—that is, bit-field members with no identifier—can be used for padding. > [!NOTE] > An unnamed bit field of width 0 forces alignment of the next bit field to the next **type** boundary, where **type** is the type of the member. @@ -33,20 +32,21 @@ struct Date { }; ``` -The conceptual memory layout of an object of type `Date` is shown in the following figure. +The conceptual memory layout of an object of type `Date` is shown in the following figure: -![Memory layout of a date object, showing the nWeekDay, nMonthDay, nMonth, and nYear bit fields.](../cpp/media/vc38uq1.png "Memory layout of a date object")
-Memory Layout of Date Object +:::image type="complex" source="../cpp/media/vc38uq1.png" alt-text="Diagram of the memory layout of a date object, showing where the n WeekDay, n MonthDay, n Month, and n Year bit fields are located."::: +32 bits of memory are displayed in a row. Starting with the least significant bit, 3 bits are for nWeekDay. The next 6 bits are for nMonthDay. The next 5 bits are for nMonth. The next 2 bits are unused. The next 8 bits are for nYear. The remaining 8 bits are unused. +:::image-end::: -Note that `nYear` is 8 bits long and would overflow the word boundary of the declared type, **`unsigned short`**. Therefore, it is begun at the beginning of a new **`unsigned short`**. It is not necessary that all bit fields fit in one object of the underlying type; new units of storage are allocated, according to the number of bits requested in the declaration. +`nYear` is 8 bits long, which would overflow the word boundary of the declared type, **`unsigned short`**. Therefore, it starts at the beginning of a new **`unsigned short`**. It isn't necessary that all bit fields fit in one object of the underlying type; new units of storage are allocated, according to the number of bits requested in the declaration. **Microsoft Specific** -The ordering of data declared as bit fields is from low to high bit, as shown in the figure above. +The ordering of data declared as bit fields is from low to high bit, as shown in the previous figure. **END Microsoft Specific** -If the declaration of a structure includes an unnamed field of length 0, as shown in the following example, +If the declaration of a structure includes an unnamed field of length 0, as shown in the following example: ```cpp // bit_fields2.cpp @@ -60,14 +60,15 @@ struct Date { }; ``` -then the memory layout is as shown in the following figure: +Then the memory layout is as shown in the following figure: -![Layout of a Date object with a zero length bit field, which forces alignment padding.](../cpp/media/vc38uq2.png)
-Layout of Date Object with Zero-Length Bit Field +:::image type="complex" source="../cpp/media/vc38uq2.png" alt-text="Diagram of the layout of a Date object, with a zero length bit field, which forces alignment padding."::: +64 bits of memory are displayed in a row. Starting with the least significant bit, 5 bits are for n Month. The next 8 bits are for n Year. The next 19 bits are unused. The next 3 bits are for n WeekDay. The next 6 bits are for n MonthDay. The remaining bits are unused. +:::image-end::: The underlying type of a bit field must be an integral type, as described in [Built-in types](../cpp/fundamental-types-cpp.md). -If the initializer for a reference of type `const T&` is an lvalue that refers to a bit field of type `T`, the reference is not bound to the bit field directly. Instead, the reference is bound to a temporary initialized to hold the value of the bit field. +If the initializer for a reference of type `const T&` is an lvalue that refers to a bit field of type `T`, the reference isn't bound to the bit field directly. Instead, the reference is bound to a temporary initialized to hold the value of the bit field. ## Restrictions on bit fields diff --git a/docs/cpp/cpp-language-reference.md b/docs/cpp/cpp-language-reference.md index f5316639df..7165a7aa29 100644 --- a/docs/cpp/cpp-language-reference.md +++ b/docs/cpp/cpp-language-reference.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: C++ Language Reference" title: "C++ Language Reference" +description: "Learn more about: C++ Language Reference" ms.custom: "index-page" -ms.date: "12/10/2019" +ms.date: 12/10/2019 helpviewer_keywords: ["C++, language reference"] -ms.assetid: 4be9cacb-c862-4391-894a-3a118c9c93ce --- # C++ Language Reference @@ -14,96 +13,95 @@ For an overview of Modern C++ programming practices, see [Welcome Back to C++](w See the following tables to quickly find a keyword or operator: -- [C++ Keywords](../cpp/keywords-cpp.md) - -- [C++ Operators](../cpp/cpp-built-in-operators-precedence-and-associativity.md) +- [C++ Keywords](keywords-cpp.md) +- [C++ Operators](cpp-built-in-operators-precedence-and-associativity.md) ## In This Section -[Lexical Conventions](../cpp/lexical-conventions.md)
+[Lexical Conventions](lexical-conventions.md)\ Fundamental lexical elements of a C++ program: tokens, comments, operators, keywords, punctuators, literals. Also, file translation, operator precedence/associativity. -[Basic Concepts](../cpp/basic-concepts-cpp.md)
+[Basic Concepts](basic-concepts-cpp.md)\ Scope, linkage, program startup and termination, storage classes, and types. -[Built-in types](fundamental-types-cpp.md) +[Built-in types](fundamental-types-cpp.md)\ The fundamental types that are built into the C++ compiler and their value ranges. -[Standard Conversions](../cpp/standard-conversions.md)
+[Standard Conversions](standard-conversions.md)\ Type conversions between built-in types. Also, arithmetic conversions and conversions among pointer, reference, and pointer-to-member types. -[Declarations and definitions](declarations-and-definitions-cpp.md) +[Declarations and definitions](declarations-and-definitions-cpp.md)\ Declaring and defining variables, types and functions. -[Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Operators, Precedence and Associativity](cpp-built-in-operators-precedence-and-associativity.md)\ The operators in C++. -[Expressions](../cpp/expressions-cpp.md)
+[Expressions](expressions-cpp.md)\ Types of expressions, semantics of expressions, reference topics on operators, casting and casting operators, run-time type information. -[Lambda Expressions](../cpp/lambda-expressions-in-cpp.md)
+[Lambda Expressions](lambda-expressions-in-cpp.md)\ A programming technique that implicitly defines a function object class and constructs a function object of that class type. -[Statements](../cpp/statements-cpp.md)
+[Statements](statements-cpp.md)\ Expression, null, compound, selection, iteration, jump, and declaration statements. -[Classes and structs](../cpp/classes-and-structs-cpp.md)
+[Classes and structs](classes-and-structs-cpp.md)\ Introduction to classes, structures, and unions. Also, member functions, special member functions, data members, bit fields, **`this`** pointer, nested classes. -[Unions](unions.md)
+[Unions](unions.md)\ User-defined types in which all members share the same memory location. -[Derived Classes](../cpp/inheritance-cpp.md)
+[Derived Classes](inheritance-cpp.md)\ Single and multiple inheritance, **`virtual`** functions, multiple base classes, **abstract** classes, scope rules. Also, the **`__super`** and **`__interface`** keywords. -[Member-Access Control](../cpp/member-access-control-cpp.md)
+[Member-Access Control](member-access-control-cpp.md)\ Controlling access to class members: **`public`**, **`private`**, and **`protected`** keywords. Friend functions and classes. -[Overloading](operator-overloading.md)
+[Overloading](operator-overloading.md)\ Overloaded operators, rules for operator overloading. -[Exception Handling](../cpp/exception-handling-in-visual-cpp.md)
+[Exception Handling](exception-handling-in-visual-cpp.md)\ C++ exception handling, structured exception handling (SEH), keywords used in writing exception handling statements. -[Assertion and User-Supplied Messages](../cpp/assertion-and-user-supplied-messages-cpp.md)
+[Assertion and User-Supplied Messages](assertion-and-user-supplied-messages-cpp.md)\ `#error` directive, the **`static_assert`** keyword, the `assert` macro. -[Templates](../cpp/templates-cpp.md)
+[Templates](templates-cpp.md)\ Template specifications, function templates, class templates, **`typename`** keyword, templates vs. macros, templates and smart pointers. -[Event Handling](../cpp/event-handling.md)
+[Event Handling](event-handling.md)\ Declaring events and event handlers. -[Microsoft-Specific Modifiers](../cpp/microsoft-specific-modifiers.md)
+[Microsoft-Specific Modifiers](microsoft-specific-modifiers.md)\ Modifiers specific to Microsoft C++. Memory addressing, calling conventions, **`naked`** functions, extended storage-class attributes (**`__declspec`**), **`__w64`**. -[Inline Assembler](../assembler/inline/inline-assembler.md)
+[Inline Assembler](../assembler/inline/inline-assembler.md)\ Using assembly language and C++ in **`__asm`** blocks. -[Compiler COM Support](../cpp/compiler-com-support.md)
+[Compiler COM Support](compiler-com-support.md)\ A reference to Microsoft-specific classes and global functions used to support COM types. -[Microsoft Extensions](../cpp/microsoft-extensions.md)
+[Microsoft Extensions](microsoft-extensions.md)\ Microsoft extensions to C++. -[Nonstandard Behavior](../cpp/nonstandard-behavior.md)
+[Nonstandard Behavior](nonstandard-behavior.md)\ Information about nonstandard behavior of the Microsoft C++ compiler. -[Welcome Back to C++](welcome-back-to-cpp-modern-cpp.md)
+[Welcome Back to C++](welcome-back-to-cpp-modern-cpp.md)\ An overview of modern C++ programming practices for writing safe, correct and efficient programs. ## Related Sections -[Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md)
+[Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md)\ Reference material on using the Microsoft C++ compiler to target .NET. -[C/C++ Building Reference](../build/reference/c-cpp-building-reference.md)
+[C/C++ Building Reference](../build/reference/c-cpp-building-reference.md)\ Compiler options, linker options, and other build tools. -[C/C++ Preprocessor Reference](../preprocessor/c-cpp-preprocessor-reference.md)
+[C/C++ Preprocessor Reference](../preprocessor/c-cpp-preprocessor-reference.md)\ Reference material on pragmas, preprocessor directives, predefined macros, and the preprocessor. -[Visual C++ Libraries](../standard-library/cpp-standard-library-reference.md)
+[Visual C++ Libraries](../standard-library/cpp-standard-library-reference.md)\ A list of links to the reference start pages for the various Microsoft C++ libraries. ## See also diff --git a/docs/cpp/cpp-type-system-modern-cpp.md b/docs/cpp/cpp-type-system-modern-cpp.md index b9b3d4b8f0..ad5f425f45 100644 --- a/docs/cpp/cpp-type-system-modern-cpp.md +++ b/docs/cpp/cpp-type-system-modern-cpp.md @@ -1,29 +1,33 @@ --- description: "Learn more about: C++ type system" title: "C++ type system" -ms.date: "11/19/2019" +ms.date: 11/04/2022 ms.topic: "conceptual" ms.assetid: 553c0ed6-77c4-43e9-87b1-c903eec53e80 --- # C++ type system -The concept of *type* is very important in C++. Every variable, function argument, and function return value must have a type in order to be compiled. Also, every expression (including literal values) is implicitly given a type by the compiler before it is evaluated. Some examples of types include **`int`** to store integer values, **`double`** to store floating-point values (also known as *scalar* data types), or the Standard Library class [std::basic_string](../standard-library/basic-string-class.md) to store text. You can create your own type by defining a **`class`** or **`struct`**. The type specifies the amount of memory that will be allocated for the variable (or expression result), the kinds of values that may be stored in that variable, how those values (as bit patterns) are interpreted, and the operations that can be performed on it. This article contains an informal overview of the major features of the C++ type system. +The concept of *type* is important in C++. Every variable, function argument, and function return value must have a type in order to be compiled. Also, all expressions (including literal values) are implicitly given a type by the compiler before they're evaluated. Some examples of types include built-in types such as **`int`** to store integer values, **`double`** to store floating-point values, or Standard Library types such as class [`std::basic_string`](../standard-library/basic-string-class.md) to store text. You can create your own type by defining a **`class`** or **`struct`**. The type specifies the amount of memory that's allocated for the variable (or expression result). The type also specifies the kinds of values that may be stored, how the compiler interprets the bit patterns in those values, and the operations you can perform on them. This article contains an informal overview of the major features of the C++ type system. ## Terminology -**Variable**: The symbolic name of a quantity of data so that the name can be used to access the data it refers to throughout the scope of the code where it is defined. In C++, *variable* is generally used to refer to instances of scalar data types, whereas instances of other types are usually called *objects*. +**Scalar type**: A type that holds a single value of a defined range. Scalars include arithmetic types (integral or floating-point values), enumeration type members, pointer types, pointer-to-member types, and `std::nullptr_t`. Fundamental types are typically scalar types. -**Object**: For simplicity and consistency, this article uses the term *object* to refer to any instance of a class or structure, and when it is used in the general sense includes all types, even scalar variables. +**Compound type**: A type that isn't a scalar type. Compound types include array types, function types, class (or struct) types, union types, enumerations, references, and pointers to non-static class members. -**POD type** (plain old data): This informal category of data types in C++ refers to types that are scalar (see the Fundamental types section) or are *POD classes*. A POD class has no static data members that aren’t also PODs, and has no user-defined constructors, user-defined destructors, or user-defined assignment operators. Also, a POD class has no virtual functions, no base class, and no private or protected non-static data members. POD types are often used for external data interchange, for example with a module written in the C language (which has POD types only). +**Variable**: The symbolic name of a quantity of data. The name can be used to access the data it refers to throughout the scope of the code where it's defined. In C++, *variable* is often used to refer to instances of scalar data types, whereas instances of other types are typically called *objects*. + +**Object**: For simplicity and consistency, this article uses the term *object* to refer to any instance of a class or structure. When it's used in the general sense, it includes all types, even scalar variables. + +**POD type** (plain old data): This informal category of data types in C++ refers to types that are scalar (see the Fundamental types section) or are *POD classes*. A POD class has no static data members that aren't also PODs, and has no user-defined constructors, user-defined destructors, or user-defined assignment operators. Also, a POD class has no virtual functions, no base class, and no private or protected non-static data members. POD types are often used for external data interchange, for example with a module written in the C language (which has POD types only). ## Specifying variable and function types -C++ is a *strongly typed* language and it is also *statically-typed*; every object has a type and that type never changes (not to be confused with static data objects). When you declare a variable in your code, you must either specify its type explicitly, or use the **`auto`** keyword to instruct the compiler to deduce the type from the initializer. When you declare a function in your code, you must specify the type of each argument and its return value, or **`void`** if no value is returned by the function. The exception is when you are using function templates, which allow for arguments of arbitrary types. +C++ is both a *strongly typed* language and a *statically typed* language; every object has a type and that type never changes. When you declare a variable in your code, you must either specify its type explicitly, or use the **`auto`** keyword to instruct the compiler to deduce the type from the initializer. When you declare a function in your code, you must specify the type of its return value and of each argument. Use the return value type **`void`** if no value is returned by the function. The exception is when you're using function templates, which allow for arguments of arbitrary types. -After you first declare a variable, you cannot change its type at some later point. However, you can copy the variable’s value or a function’s return value into another variable of a different type. Such operations are called *type conversions*, which are sometimes necessary but are also potential sources of data loss or incorrectness. +After you first declare a variable, you can't change its type at some later point. However, you can copy the variable's value or a function's return value into another variable of a different type. Such operations are called *type conversions*, which are sometimes necessary but are also potential sources of data loss or incorrectness. -When you declare a variable of POD type, we strongly recommend you initialize it, which means to give it an initial value. Until you initialize a variable, it has a "garbage" value that consists of whatever bits happened to be in that memory location previously. This is an important aspect of C++ to remember, especially if you are coming from another language that handles initialization for you. When declaring a variable of non-POD class type, the constructor handles initialization. +When you declare a variable of POD type, we strongly recommend you *initialize* it, which means to give it an initial value. Until you initialize a variable, it has a "garbage" value that consists of whatever bits happened to be in that memory location previously. It's an important aspect of C++ to remember, especially if you're coming from another language that handles initialization for you. When you declare a variable of non-POD class type, the constructor handles initialization. The following example shows some simple variable declarations with some descriptions for each. The example also shows how the compiler uses type information to allow or disallow certain subsequent operations on the variable. @@ -37,8 +41,8 @@ auto address; // error. Compiler cannot deduce a type // without an intializing value. age = 12; // error. Variable declaration must // specify a type or use auto! -result = "Kenny G."; // error. Can’t assign text to an int. -string result = "zero"; // error. Can’t redefine a variable with +result = "Kenny G."; // error. Can't assign text to an int. +string result = "zero"; // error. Can't redefine a variable with // new type. int maxValue; // Not recommended! maxValue contains // garbage bits until it is initialized. @@ -46,9 +50,9 @@ int maxValue; // Not recommended! maxValue contains ## Fundamental (built-in) types -Unlike some languages, C++ has no universal base type from which all other types are derived. The language includes many *fundamental types*, also known as *built-in types*. This includes numeric types such as **`int`**, **`double`**, **`long`**, **`bool`**, plus the **`char`** and **`wchar_t`** types for ASCII and UNICODE characters, respectively. Most integral fundamental types (except **`bool`**, **`double`**, **`wchar_t`**, and related types) all have **`unsigned`** versions, which modify the range of values that the variable can store. For example, an **`int`**, which stores a 32-bit signed integer, can represent a value from -2,147,483,648 to 2,147,483,647. An **`unsigned int`**, which is also stored as 32-bits, can store a value from 0 to 4,294,967,295. The total number of possible values in each case is the same; only the range is different. +Unlike some languages, C++ has no universal base type from which all other types are derived. The language includes many *fundamental types*, also known as *built-in types*. These types include numeric types such as **`int`**, **`double`**, **`long`**, **`bool`**, plus the **`char`** and **`wchar_t`** types for ASCII and UNICODE characters, respectively. Most integral fundamental types (except **`bool`**, **`double`**, **`wchar_t`**, and related types) all have **`unsigned`** versions, which modify the range of values that the variable can store. For example, an **`int`**, which stores a 32-bit signed integer, can represent a value from -2,147,483,648 to 2,147,483,647. An **`unsigned int`**, which is also stored as 32 bits, can store a value from 0 to 4,294,967,295. The total number of possible values in each case is the same; only the range is different. -The fundamental types are recognized by the compiler, which has built-in rules that govern what operations you can perform on them, and how they can be converted to other fundamental types. For a complete list of built-in types and their size and numeric limits, see [Built-in types](../cpp/fundamental-types-cpp.md). +The compiler recognizes these built-in types, and it has built-in rules that govern what operations you can perform on them, and how they can be converted to other fundamental types. For a complete list of built-in types and their size and numeric limits, see [Built-in types](../cpp/fundamental-types-cpp.md). The following illustration shows the relative sizes of the built-in types in the Microsoft C++ implementation: @@ -62,34 +66,33 @@ The following table lists the most frequently used fundamental types, and their | **`double`** | 8 bytes | The default choice for floating point values. | | **`bool`** | 1 byte | Represents values that can be either true or false. | | **`char`** | 1 byte | Use for ASCII characters in older C-style strings or std::string objects that will never have to be converted to UNICODE. | -| **`wchar_t`** | 2 bytes | Represents "wide" character values that may be encoded in UNICODE format (UTF-16 on Windows, other operating systems may differ). This is the character type that is used in strings of type `std::wstring`. | +| **`wchar_t`** | 2 bytes | Represents "wide" character values that may be encoded in UNICODE format (UTF-16 on Windows, other operating systems may differ). **`wchar_t`** is the character type that's used in strings of type `std::wstring`. | | **`unsigned char`** | 1 byte | C++ has no built-in byte type. Use **`unsigned char`** to represent a byte value. | | **`unsigned int`** | 4 bytes | Default choice for bit flags. | -| **`long long`** | 8 bytes | Represents very large integer values. | +| **`long long`** | 8 bytes | Represents a much larger range of integer values. | Other C++ implementations may use different sizes for certain numeric types. For more information on the sizes and size relationships that the C++ standard requires, see [Built-in types](fundamental-types-cpp.md). -## The void type +## The `void` type -The **`void`** type is a special type; you cannot declare a variable of type **`void`**, but you can declare a variable of type `void *` (pointer to **`void`**), which is sometimes necessary when allocating raw (un-typed) memory. However, pointers to **`void`** are not type-safe and generally their use is strongly discouraged in modern C++. In a function declaration, a **`void`** return value means that the function does not return a value; this is a common and acceptable use of **`void`**. While the C language required functions that have zero parameters to declare **`void`** in the parameter list, for example, `fou(void)`, this practice is discouraged in modern C++ and should be declared `fou()`. For more information, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +The **`void`** type is a special type; you can't declare a variable of type **`void`**, but you can declare a variable of type `void *` (pointer to **`void`**), which is sometimes necessary when allocating raw (untyped) memory. However, pointers to **`void`** aren't type-safe and their use is discouraged in modern C++. In a function declaration, a **`void`** return value means that the function doesn't return a value; using it as a return type is a common and acceptable use of **`void`**. While the C language required functions that have zero parameters to declare **`void`** in the parameter list, for example, `fn(void)`, this practice is discouraged in modern C++; a parameterless function should be declared `fn()`. For more information, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). -## const type qualifier +## `const` type qualifier -Any built-in or user-defined type may be qualified by the const keyword. Additionally, member functions may be **`const`**-qualified and even **`const`**-overloaded. The value of a **`const`** type cannot be modified after it is initialized. +Any built-in or user-defined type may be qualified by the **`const`** keyword. Additionally, member functions may be **`const`**-qualified and even **`const`**-overloaded. The value of a **`const`** type can't be modified after it's initialized. ```cpp - const double PI = 3.1415; -PI = .75 //Error. Cannot modify const variable. +PI = .75; //Error. Cannot modify const variable. ``` -The **`const`** qualifier is used extensively in function and variable declarations and "const correctness" is an important concept in C++; essentially it means to use **`const`** to guarantee, at compile time, that values are not modified unintentionally. For more information, see [`const`](../cpp/const-cpp.md). +The **`const`** qualifier is used extensively in function and variable declarations and "const correctness" is an important concept in C++; essentially it means to use **`const`** to guarantee, at compile time, that values aren't modified unintentionally. For more information, see [`const`](../cpp/const-cpp.md). -A **`const`** type is distinct from its non-const version; for example, **`const int`** is a distinct type from **`int`**. You can use the C++ **`const_cast`** operator on those rare occasions when you must remove *const-ness* from a variable. For more information, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +A **`const`** type is distinct from its non-**`const`** version; for example, **`const int`** is a distinct type from **`int`**. You can use the C++ **`const_cast`** operator on those rare occasions when you must remove *const-ness* from a variable. For more information, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). ## String types -Strictly speaking, the C++ language has no built-in string type; **`char`** and **`wchar_t`** store single characters - you must declare an array of these types to approximate a string, adding a terminating null value (for example, ASCII `'\0'`) to the array element one past the last valid character (also called a *C-style string*). C-style strings required much more code to be written or the use of external string utility library functions. But in modern C++, we have the Standard Library types `std::string` (for 8-bit **`char`**-type character strings) or `std::wstring` (for 16-bit **`wchar_t`**-type character strings). These C++ Standard Library containers can be thought of as native string types because they are part of the standard libraries that are included in any conformant C++ build environment. Simply use the `#include ` directive to make these types available in your program. (If you are using MFC or ATL, the `CString` class is also available, but is not part of the C++ standard.) The use of null-terminated character arrays (the C-style strings previously mentioned) is strongly discouraged in modern C++. +Strictly speaking, the C++ language has no built-in string type; **`char`** and **`wchar_t`** store single characters - you must declare an array of these types to approximate a string, adding a terminating null value (for example, ASCII `'\0'`) to the array element one past the last valid character (also called a *C-style string*). C-style strings required much more code to be written or the use of external string utility library functions. But in modern C++, we have the Standard Library types `std::string` (for 8-bit **`char`**-type character strings) or `std::wstring` (for 16-bit **`wchar_t`**-type character strings). These C++ Standard Library containers can be thought of as native string types because they're part of the standard libraries that are included in any conformant C++ build environment. Use the `#include ` directive to make these types available in your program. (If you're using MFC or ATL, the `CString` class is also available, but isn't part of the C++ standard.) The use of null-terminated character arrays (the C-style strings previously mentioned) is discouraged in modern C++. ## User-defined types @@ -97,13 +100,15 @@ When you define a **`class`**, **`struct`**, **`union`**, or **`enum`**, that co - The compiler has no built-in knowledge of a user-defined type. It learns of the type when it first encounters the definition during the compilation process. -- You specify what operations can be performed on your type, and how it can be converted to other types, by defining (through overloading) the appropriate operators, either as class members or non-member functions. For more information, see [Function Overloading](function-overloading.md) +- You specify what operations can be performed on your type, and how it can be converted to other types, by defining (through overloading) the appropriate operators, either as class members or non-member functions. For more information, see [Function overloading](function-overloading.md) ## Pointer types -Dating back to the earliest versions of the C language, C++ continues to let you declare a variable of a pointer type by using the special declarator **`*`** (asterisk). A pointer type stores the address of the location in memory where the actual data value is stored. In modern C++, these are referred to as *raw pointers*, and are accessed in your code through special operators **`*`** (asterisk) or **`->`** (dash with greater-than). This is called *dereferencing*, and which one that you use depends on whether you are dereferencing a pointer to a scalar or a pointer to a member in an object. Working with pointer types has long been one of the most challenging and confusing aspects of C and C++ program development. This section outlines some facts and practices to help use raw pointers if you want to, but in modern C++ it’s no longer required (or recommended) to use raw pointers for object ownership at all, due to the evolution of the [smart pointer](../cpp/smart-pointers-modern-cpp.md) (discussed more at the end of this section). It is still useful and safe to use raw pointers for observing objects, but if you must use them for object ownership, you should do so with caution and very careful consideration of how the objects owned by them are created and destroyed. +As in the earliest versions of the C language, C++ continues to let you declare a variable of a pointer type by using the special declarator **`*`** (asterisk). A pointer type stores the address of the location in memory where the actual data value is stored. In modern C++, these pointer types are referred to as *raw pointers*, and they're accessed in your code through special operators: **`*`** (asterisk) or **`->`** (dash with greater-than, often called *arrow*). This memory access operation is called *dereferencing*. Which operator you use depends on whether you're dereferencing a pointer to a scalar, or a pointer to a member in an object. + +Working with pointer types has long been one of the most challenging and confusing aspects of C and C++ program development. This section outlines some facts and practices to help use raw pointers if you want to. However, in modern C++, it's no longer required (or recommended) to use raw pointers for object ownership at all, due to the evolution of the [smart pointer](../cpp/smart-pointers-modern-cpp.md) (discussed more at the end of this section). It's still useful and safe to use raw pointers for observing objects. However, if you must use them for object ownership, you should do so with caution and with careful consideration of how the objects owned by them are created and destroyed. -The first thing that you should know is declaring a raw pointer variable will allocate only the memory that is required to store an address of the memory location that the pointer will be referring to when it is dereferenced. Allocation of the memory for the data value itself (also called *backing store*) is not yet allocated. In other words, by declaring a raw pointer variable, you are creating a memory address variable, not an actual data variable. Dereferencing a pointer variable before making sure that it contains a valid address to a backing store will cause undefined behavior (usually a fatal error) in your program. The following example demonstrates this kind of error: +The first thing that you should know is that a raw pointer variable declaration only allocates enough memory to store an address: the memory location that the pointer refers to when it's dereferenced. The pointer declaration doesn't allocate the memory needed to store the data value. (That memory is also called the *backing store*.) In other words, by declaring a raw pointer variable, you're creating a memory address variable, not an actual data variable. If you dereference a pointer variable before you've made sure that it contains a valid address for a backing store, it causes undefined behavior (usually a fatal error) in your program. The following example demonstrates this kind of error: ```cpp int* pNumber; // Declare a pointer-to-int variable. @@ -129,9 +134,9 @@ The example dereferences a pointer type without having any memory allocated to s // "pNumber". ``` -The corrected code example uses local stack memory to create the backing store that `pNumber` points to. We use a fundamental type for simplicity. In practice, the backing store for pointers are most often user-defined types that are dynamically-allocated in an area of memory called the *heap* (or *free store*) by using a **`new`** keyword expression (in C-style programming, the older `malloc()` C runtime library function was used). Once allocated, these variables are usually referred to as objects, especially if they are based on a class definition. Memory that is allocated with **`new`** must be deleted by a corresponding **`delete`** statement (or, if you used the `malloc()` function to allocate it, the C runtime function `free()`). +The corrected code example uses local stack memory to create the backing store that `pNumber` points to. We use a fundamental type for simplicity. In practice, the backing stores for pointers are most often user-defined types that are dynamically allocated in an area of memory called the *heap* (or *free store*) by using a **`new`** keyword expression (in C-style programming, the older `malloc()` C runtime library function was used). Once allocated, these variables are normally referred to as *objects*, especially if they're based on a class definition. Memory that is allocated with **`new`** must be deleted by a corresponding **`delete`** statement (or, if you used the `malloc()` function to allocate it, the C runtime function `free()`). -However, it is easy to forget to delete a dynamically-allocated object- especially in complex code, which causes a resource bug called a *memory leak*. For this reason, the use of raw pointers is strongly discouraged in modern C++. It is almost always better to wrap a raw pointer in a [smart pointer](../cpp/smart-pointers-modern-cpp.md), which will automatically release the memory when its destructor is invoked (when the code goes out of scope for the smart pointer); by using smart pointers you virtually eliminate a whole class of bugs in your C++ programs. In the following example, assume `MyClass` is a user-defined type that has a public method `DoSomeWork();` +However, it's easy to forget to delete a dynamically allocated object- especially in complex code, which causes a resource bug called a *memory leak*. For this reason, the use of raw pointers is discouraged in modern C++. It's almost always better to wrap a raw pointer in a [smart pointer](../cpp/smart-pointers-modern-cpp.md), which automatically releases the memory when its destructor is invoked. (That is, when the code goes out of scope for the smart pointer.) By using smart pointers, you virtually eliminate a whole class of bugs in your C++ programs. In the following example, assume `MyClass` is a user-defined type that has a public method `DoSomeWork();` ```cpp void someFunction() { @@ -142,28 +147,28 @@ void someFunction() { // for the unique_ptr, freeing the resource. ``` -For more information about smart pointers, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md). +For more information about smart pointers, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md). -For more information about pointer conversions, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +For more information about pointer conversions, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). For more information about pointers in general, see [Pointers](../cpp/pointers-cpp.md). ## Windows data types -In classic Win32 programming for C and C++, most functions use Windows-specific typedefs and `#define` macros (defined in `windef.h`) to specify the types of parameters and return values. These Windows data types are mostly just special names (aliases) given to C/C++ built-in types. For a complete list of these typedefs and preprocessor definitions, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). Some of these typedefs, such as `HRESULT` and `LCID`, are useful and descriptive. Others, such as `INT`, have no special meaning and are just aliases for fundamental C++ types. Other Windows data types have names that are retained from the days of C programming and 16-bit processors, and have no purpose or meaning on modern hardware or operating systems. There are also special data types associated with the Windows Runtime Library, listed as [Windows Runtime base data types](/windows/win32/WinRT/base-data-types). In modern C++, the general guideline is to prefer the C++ fundamental types unless the Windows type communicates some additional meaning about how the value is to be interpreted. +In classic Win32 programming for C and C++, most functions use Windows-specific typedefs and `#define` macros (defined in `windef.h`) to specify the types of parameters and return values. These Windows data types are mostly special names (aliases) given to C/C++ built-in types. For a complete list of these typedefs and preprocessor definitions, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). Some of these typedefs, such as `HRESULT` and `LCID`, are useful and descriptive. Others, such as `INT`, have no special meaning and are just aliases for fundamental C++ types. Other Windows data types have names that are retained from the days of C programming and 16-bit processors, and have no purpose or meaning on modern hardware or operating systems. There are also special data types associated with the Windows Runtime Library, listed as [Windows Runtime base data types](/windows/win32/WinRT/base-data-types). In modern C++, the general guideline is to prefer the C++ fundamental types unless the Windows type communicates some extra meaning about how the value is to be interpreted. ## More information -For more information about the C++ type system, see the following topics. +For more information about the C++ type system, see the following articles. -[Value Types](../cpp/value-types-modern-cpp.md)\ +[Value types](../cpp/value-types-modern-cpp.md)\ Describes *value types* along with issues relating to their use. -[Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md)\ +[Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md)\ Describes common type conversion issues and shows how to avoid them. ## See also -[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)
-[C++ Language Reference](../cpp/cpp-language-reference.md)
+[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)\ +[C++ language reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/data-type-ranges.md b/docs/cpp/data-type-ranges.md index 3e2e319429..eb51133925 100644 --- a/docs/cpp/data-type-ranges.md +++ b/docs/cpp/data-type-ranges.md @@ -3,31 +3,25 @@ description: "Learn more about: Data Type Ranges" title: "Data Type Ranges" ms.date: "05/28/2020" helpviewer_keywords: ["float keyword [C++]", "char keyword [C++]", "unsigned long", "__wchar_t keyword [C++]", "unsigned short int [C++]", "enum keyword [C++]", "unsigned char keyword [C++]", "integer data type [C++], data type ranges", "int data type", "data types [C++], ranges", "unsigned int [C++]", "short data type", "short int data", "signed types [C++], data type ranges", "long long keyword [C++]", "long double keyword [C++]", "double data type [C++], data type ranges", "signed short int [C++]", "unsigned short", "sized integer types", "signed int [C++]", "signed long int [C++]", "signed char keyword [C++]", "wchar_t keyword [C++]", "long keyword [C++]", "ranges [C++]", "unsigned types [C++], data type ranges", "floating-point numbers [C++]", "data type ranges", "ranges [C++], data types", "long int keyword [C++]", "unsigned long int [C++]"] -ms.assetid: 3691ceca-05fb-4b82-b1ae-5c4618cda91a --- # Data Type Ranges The Microsoft C++ 32-bit and 64-bit compilers recognize the types in the table later in this article. -- **`int`** (**`unsigned int`**) +```cpp +- int (unsigned int) +- __int8 (unsigned __int8) +- __int16 (unsigned __int16) +- __int32 (unsigned __int32) +- __int64 (unsigned __int64) +- short (unsigned short) +- long (unsigned long) +- long long (unsigned long long) +``` -- **`__int8`** (**`unsigned __int8`**) +If its name begins with two underscores (`__`), the data type is nonstandard. -- **`__int16`** (**`unsigned __int16`**) - -- **`__int32`** (**`unsigned __int32`**) - -- **`__int64`** (**`unsigned __int64`**) - -- **`short`** (**`unsigned short`**) - -- **`long`** (**`unsigned long`**) - -- **`long long`** (**`unsigned long long`**) - -If its name begins with two underscores (`__`), a data type is non-standard. - -The ranges that are specified in the following table are inclusive-inclusive. +The ranges specified in the following table are inclusive-inclusive. |Type Name|Bytes|Other Names|Range of Values| |---------------|-----------|-----------------|---------------------| @@ -52,16 +46,16 @@ The ranges that are specified in the following table are inclusive-inclusive. |**`long long`**|8|none (but equivalent to **`__int64`**)|-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807| |**`unsigned long long`**|8|none (but equivalent to **`unsigned __int64`**)|0 to 18,446,744,073,709,551,615| |**`enum`**|varies|none| | -|**`float`**|4|none|3.4E +/- 38 (7 digits)| -|**`double`**|8|none|1.7E +/- 308 (15 digits)| +|**`float`**|4|none|3.4E +/- 38 (seven digits)| +|**`double`**|8|none|1.7E +/- 308 (fifteen digits)| |**`long double`**|same as **`double`**|none|Same as **`double`**| |**`wchar_t`**|2|**`__wchar_t`**|0 to 65,535| -Depending on how it's used, a variable of **`__wchar_t`** designates either a wide-character type or multibyte-character type. Use the `L` prefix before a character or string constant to designate the wide-character-type constant. +A variable of **`__wchar_t`** designates either a wide-character type or multibyte-character type. Use the `L` prefix before a character or string constant to designate the wide-character-type constant. **`signed`** and **`unsigned`** are modifiers that you can use with any integral type except **`bool`**. Note that **`char`**, **`signed char`**, and **`unsigned char`** are three distinct types for the purposes of mechanisms like overloading and templates. -The **`int`** and **`unsigned int`** types have a size of four bytes. However, portable code should not depend on the size of **`int`** because the language standard allows this to be implementation-specific. +The **`int`** and **`unsigned int`** types have a size of 4 bytes. However, portable code shouldn't depend on the size of **`int`** because the language standard allows this to be implementation-specific. C/C++ in Visual Studio also supports sized integer types. For more information, see [`__int8, __int16, __int32, __int64`](../cpp/int8-int16-int32-int64.md) and [Integer Limits](../cpp/integer-limits.md). @@ -71,5 +65,5 @@ The range of enumerated types varies depending on the language context and speci ## See also -[Keywords](../cpp/keywords-cpp.md)
+[Keywords](../cpp/keywords-cpp.md)\ [Built-in types](../cpp/fundamental-types-cpp.md) diff --git a/docs/cpp/declarations-and-definitions-cpp.md b/docs/cpp/declarations-and-definitions-cpp.md index 0e94f331c5..eb34f752b9 100644 --- a/docs/cpp/declarations-and-definitions-cpp.md +++ b/docs/cpp/declarations-and-definitions-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Declarations and definitions (C++)" title: "Declarations and definitions (C++)" -ms.date: 07/23/2021 +ms.date: 02/22/2022 --- # Declarations and definitions (C++) @@ -18,8 +18,8 @@ int main() { const double pi = 3.14; //OK int i = f(2); //OK. f is forward-declared - std::string str; // OK std::string is declared in header C obj; // error! C not yet declared. + std::string str; // OK std::string is declared in header j = 0; // error! No type specified. auto k = 0; // OK. type inferred as int by compiler. } @@ -36,7 +36,7 @@ namespace N { On line 5, the `main` function is declared. On line 7, a **`const`** variable named `pi` is declared and *initialized*. On line 8, an integer `i` is declared and initialized with the value produced by the function `f`. The name `f` is visible to the compiler because of the *forward declaration* on line 3. -In line 9, a variable named `obj` of type `C` is declared. However, this declaration raises an error because `C` isn't declared until later in the program, and isn't forward-declared. To fix the error, you can either move the entire *definition* of `C` before `main` or else add a forward-declaration for it. This behavior is different from other languages such as C#, in which functions and classes can be used before their point of declaration in a source file. +In line 9, a variable named `obj` of type `C` is declared. However, this declaration raises an error because `C` isn't declared until later in the program, and isn't forward-declared. To fix the error, you can either move the entire *definition* of `C` before `main` or else add a forward-declaration for it. This behavior is different from other languages such as C#. In those languages, functions and classes can be used before their point of declaration in a source file. In line 10, a variable named `str` of type `std::string` is declared. The name `std::string` is visible because it's introduced in the `string` [header file](header-files-cpp.md), which is merged into the source file in line 1. `std` is the namespace in which the `string` class is declared. @@ -82,25 +82,25 @@ In older versions of C++, the [`typedef`](aliases-and-typedefs-cpp.md) keyword i ## Static class members -Because static class data members are discrete variables that are shared by all objects of the class, they must be defined and initialized outside the class definition. (For more information, see [Classes](../cpp/classes-and-structs-cpp.md).) +Static class data members are discrete variables that are shared by all objects of the class. Because they're shared, they must be defined and initialized outside the class definition. For more information, see [Classes](../cpp/classes-and-structs-cpp.md). ## extern declarations -A C++ program might contain more than one [compilation unit](header-files-cpp.md). To declare an entity that is defined in a separate compilation unit, use the [`extern`](extern-cpp.md) keyword. The information in the declaration is sufficient for the compiler, but if the definition of the entity can't be found in the linking step, then the linker will raise an error. +A C++ program might contain more than one [compilation unit](header-files-cpp.md). To declare an entity that's defined in a separate compilation unit, use the [`extern`](extern-cpp.md) keyword. The information in the declaration is sufficient for the compiler. However, if the definition of the entity can't be found in the linking step, then the linker will raise an error. ## In this section -[Storage classes](storage-classes-cpp.md)
-[`const`](const-cpp.md)
-[`constexpr`](constexpr-cpp.md)
-[`extern`](extern-cpp.md)
-[Initializers](initializers.md)
-[Aliases and typedefs](aliases-and-typedefs-cpp.md)
-[`using` declaration](using-declaration.md)
-[`volatile`](volatile-cpp.md)
-[`decltype`](decltype-cpp.md)
-[Attributes in C++](attributes.md)
+[Storage classes](storage-classes-cpp.md)\ +[`const`](const-cpp.md)\ +[`constexpr`](constexpr-cpp.md)\ +[`extern`](extern-cpp.md)\ +[Initializers](initializers.md)\ +[Aliases and typedefs](aliases-and-typedefs-cpp.md)\ +[`using` declaration](using-declaration.md)\ +[`volatile`](volatile-cpp.md)\ +[`decltype`](decltype-cpp.md)\ +[Attributes in C++](attributes.md) ## See also -[Basic Concepts](../cpp/basic-concepts-cpp.md)
+[Basic Concepts](../cpp/basic-concepts-cpp.md) diff --git a/docs/cpp/declspec.md b/docs/cpp/declspec.md index 54d4b52ba8..443a140a7c 100644 --- a/docs/cpp/declspec.md +++ b/docs/cpp/declspec.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: `__declspec`" title: "__declspec" -ms.date: "03/21/2019" +description: "Learn more about: `__declspec`" +ms.date: 1/14/2025 f1_keywords: ["__declspec_cpp", "__declspec", "_declspec"] helpviewer_keywords: ["__declspec keyword [C++]"] --- @@ -9,7 +9,7 @@ helpviewer_keywords: ["__declspec keyword [C++]"] **Microsoft Specific** -The extended attribute syntax for specifying storage-class information uses the **`__declspec`** keyword, which specifies that an instance of a given type is to be stored with a Microsoft-specific storage-class attribute listed below. Examples of other storage-class modifiers include the **`static`** and **`extern`** keywords. However, these keywords are part of the ANSI specification of the C and C++ languages, and as such are not covered by extended attribute syntax. The extended attribute syntax simplifies and standardizes Microsoft-specific extensions to the C and C++ languages. +The extended attribute syntax for specifying storage-class information uses the `__declspec` keyword, which specifies that an instance of a given type is to be stored with a Microsoft-specific storage-class attribute listed below. Examples of other storage-class modifiers include the `static` and `extern` keywords. However, these keywords are part of the ANSI specification of the C and C++ languages, and as such aren't covered by extended attribute syntax. The extended attribute syntax simplifies and standardizes Microsoft-specific extensions to the C and C++ languages. ## Grammar @@ -29,6 +29,8 @@ The extended attribute syntax for specifying storage-class information uses the  **`deprecated`**\  **`dllimport`**\  **`dllexport`**\ + **`empty_bases`**\ + **`hybrid_patchable`**\  **`jitintrinsic`**\  **`naked`**\  **`noalias`**\ @@ -38,7 +40,7 @@ The extended attribute syntax for specifying storage-class information uses the  **`novtable`**\  **`no_sanitize_address`**\  **`process`**\ - **`property(`** { **`get=`**_get-func-name_ | **`,put=`**_put-func-name_ } **`)`**\ + **`property(`** { **`get=`**_get-func-name_ \| **`,put=`**_put-func-name_ } **`)`**\  **`restrict`**\  **`safebuffers`**\  **`selectany`**\ @@ -48,11 +50,11 @@ The extended attribute syntax for specifying storage-class information uses the White space separates the declaration modifier sequence. Examples appear in later sections. -Extended attribute grammar supports these Microsoft-specific storage-class attributes: [`align`](../cpp/align-cpp.md), [`allocate`](../cpp/allocate.md), [`allocator`](../cpp/allocator.md), [`appdomain`](../cpp/appdomain.md), [`code_seg`](../cpp/code-seg-declspec.md), [`deprecated`](../cpp/deprecated-cpp.md), [`dllexport`](../cpp/dllexport-dllimport.md), [`dllimport`](../cpp/dllexport-dllimport.md), [`jitintrinsic`](../cpp/jitintrinsic.md), [`naked`](../cpp/naked-cpp.md), [`noalias`](../cpp/noalias.md), [`noinline`](../cpp/noinline.md), [`noreturn`](../cpp/noreturn.md), [`nothrow`](../cpp/nothrow-cpp.md), [`novtable`](../cpp/novtable.md), [`no_sanitize_address`](../cpp/no-sanitize-address.md),[`process`](../cpp/process.md), [`restrict`](../cpp/restrict.md), [`safebuffers`](../cpp/safebuffers.md), [`selectany`](../cpp/selectany.md), [`spectre`](../cpp/spectre.md), and [`thread`](../cpp/thread.md). It also supports these COM-object attributes: [`property`](../cpp/property-cpp.md) and [`uuid`](../cpp/uuid-cpp.md). +Extended attribute grammar supports these Microsoft-specific storage-class attributes: [`align`](align-cpp.md), [`allocate`](allocate.md), [`allocator`](allocator.md), [`appdomain`](appdomain.md), [`code_seg`](code-seg-declspec.md), [`deprecated`](deprecated-cpp.md), [`dllexport`](dllexport-dllimport.md), [`dllimport`](dllexport-dllimport.md), [`empty_bases`](empty-bases.md), [`jitintrinsic`](jitintrinsic.md), [`naked`](naked-cpp.md), [`noalias`](noalias.md), [`noinline`](noinline.md), [`noreturn`](noreturn.md), [`nothrow`](nothrow-cpp.md), [`novtable`](novtable.md), [`no_sanitize_address`](no-sanitize-address.md), [`process`](process.md), [`restrict`](restrict.md), [`safebuffers`](safebuffers.md), [`selectany`](selectany.md), [`spectre`](spectre.md), and [`thread`](thread.md). It also supports these COM-object attributes: [`property`](property-cpp.md) and [`uuid`](uuid-cpp.md). -The **`code_seg`**, **`dllexport`**, **`dllimport`**, **`naked`**, **`noalias`**, **`nothrow`**, **`no_sanitize_address`**, **`property`**, **`restrict`**, **`selectany`**, **`thread`**, and **`uuid`** storage-class attributes are properties only of the declaration of the object or function to which they are applied. The **`thread`** attribute affects data and objects only. The **`naked`** and **`spectre`** attributes affect functions only. The **`dllimport`** and **`dllexport`** attributes affect functions, data, and objects. The **`property`**, **`selectany`**, and **`uuid`** attributes affect COM objects. +The **`code_seg`**, **`dllexport`**, **`dllimport`**, **`empty_bases`**, **`naked`**, **`noalias`**, **`nothrow`**, **`no_sanitize_address`**, **`property`**, **`restrict`**, **`selectany`**, **`thread`**, and **`uuid`** storage-class attributes are properties only of the declaration of the object or function to which they're applied. The **`thread`** attribute affects data and objects only. The **`naked`** and **`spectre`** attributes affect functions only. The **`dllimport`** and **`dllexport`** attributes affect functions, data, and objects. The **`property`**, **`selectany`**, and **`uuid`** attributes affect COM objects. -For compatibility with previous versions, **`_declspec`** is a synonym for **`__declspec`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +For compatibility with previous versions, **`_declspec`** is a synonym for **`__declspec`** unless compiler option [`/Za` (Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. The **`__declspec`** keywords should be placed at the beginning of a simple declaration. The compiler ignores, without warning, any **`__declspec`** keywords placed after * or & and in front of the variable identifier in a declaration. @@ -72,9 +74,9 @@ In this case, the attribute applies to `X`. The general guideline for using the **`__declspec`** attribute for simple declarations is as follows: -*decl-specifier-seq* *init-declarator-list*; +*`decl-specifier-seq`* *`init-declarator-list`* `;` -The *decl-specifier-seq* should contain, among other things, a base type (e.g. **`int`**, **`float`**, a **`typedef`**, or a class name), a storage class (e.g. **`static`**, **`extern`**), or the **`__declspec`** extension. The *init-declarator-list* should contain, among other things, the pointer part of declarations. For example: +The *`decl-specifier-seq`* should contain, among other things, a base type (for example, **`int`**, **`float`**, a **`typedef`**, or a class name), a storage class (for example, **`static`**, **`extern`**), or the **`__declspec`** extension. The *`init-declarator-list`* should contain, among other things, the pointer part of declarations. For example: ```cpp __declspec(selectany) int * pi1 = 0; //Recommended, selectany & int both part of decl-specifier @@ -93,5 +95,5 @@ __declspec( thread ) int tls_i = 1; ## See also -[Keywords](../cpp/keywords-cpp.md)\ -[C Extended Storage-Class Attributes](../c-language/c-extended-storage-class-attributes.md) +[Keywords](keywords-cpp.md)\ +[C extended storage-class attributes](../c-language/c-extended-storage-class-attributes.md) diff --git a/docs/cpp/decltype-cpp.md b/docs/cpp/decltype-cpp.md index 7596557a30..2b387820ce 100644 --- a/docs/cpp/decltype-cpp.md +++ b/docs/cpp/decltype-cpp.md @@ -1,76 +1,75 @@ --- -description: "Learn more about: decltype (C++)" -title: "decltype (C++)" -ms.date: "11/04/2016" +description: "Learn more about: decltype (C++)" +title: "decltype (C++)" +ms.date: 09/14/2023 f1_keywords: ["decltype_cpp"] helpviewer_keywords: ["operators [C++], decltype", "decltype operator", "operators [C++], type of an expression", "operators [C++], deduce expression type"] -ms.assetid: 6dcf8888-8196-4f13-af50-51e3797255d4 --- -# decltype (C++) +# `decltype` (C++) -The **`decltype`** type specifier yields the type of a specified expression. The **`decltype`** type specifier, together with the [`auto` keyword](../cpp/auto-cpp.md), is useful primarily to developers who write template libraries. Use **`auto`** and **`decltype`** to declare a template function whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a template function that wraps a call to another function, and then returns the return type of the wrapped function. +The **`decltype`** type specifier yields the type of a specified expression. The **`decltype`** type specifier, together with the [`auto` keyword](../cpp/auto-cpp.md), is useful primarily to developers who write template libraries. Use **`auto`** and **`decltype`** to declare a function template whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a function template that wraps a call to another function, and then returns the return type of the wrapped function. ## Syntax -> **`decltype(`** *expression* **`)`** +> **`decltype(`** *`expression`* **`)`** ### Parameters -*expression*\ +*`expression`*\ An expression. For more information, see [Expressions](../cpp/expressions-cpp.md). -## Return Value +## Return value -The type of the *expression* parameter. +The type of the *`expression`* parameter. ## Remarks The **`decltype`** type specifier is supported in Visual Studio 2010 or later versions, and can be used with native or managed code. `decltype(auto)` (C++14) is supported in Visual Studio 2015 and later. -The compiler uses the following rules to determine the type of the *expression* parameter. +The compiler uses the following rules to determine the type of the *`expression`* parameter. -- If the *expression* parameter is an identifier or a [class member access](../cpp/member-access-operators-dot-and.md), `decltype(expression)` is the type of the entity named by *expression*. If there is no such entity or the *expression* parameter names a set of overloaded functions, the compiler yields an error message. +- If the *`expression`* parameter is an identifier or a [class member access](../cpp/member-access-operators-dot-and.md), `decltype(expression)` is the type of the entity named by *`expression`*. If there's no such entity or the *`expression`* parameter names a set of overloaded functions, the compiler yields an error message. -- If the *expression* parameter is a call to a function or an overloaded operator function, `decltype(expression)` is the return type of the function. Parentheses around an overloaded operator are ignored. +- If the *`expression`* parameter is a call to a function or an overloaded operator function, `decltype(expression)` is the return type of the function. Parentheses around an overloaded operator are ignored. -- If the *expression* parameter is an [rvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is the type of *expression*. If the *expression* parameter is an [lvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is an [lvalue reference](../cpp/lvalue-reference-declarator-amp.md) to the type of *expression*. +- If the *`expression`* parameter is an [rvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is the type of *`expression`*. If the *`expression`* parameter is an [lvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is an [lvalue reference](../cpp/lvalue-reference-declarator-amp.md) to the type of *`expression`*. -The following code example demonstrates some uses of the **`decltype`** type specifier. First, assume that you have coded the following statements. +The following code example demonstrates some uses of the **`decltype`** type specifier. First, assume that you've coded the following statements. ```cpp int var; const int&& fx(); -struct A { double x; } +struct A { double x; }; const A* a = new A(); ``` Next, examine the types that are returned by the four **`decltype`** statements in the following table. -|Statement|Type|Notes| -|---------------|----------|-----------| -|`decltype(fx());`|`const int&&`|An [rvalue reference](../cpp/rvalue-reference-declarator-amp-amp.md) to a **`const int`**.| -|`decltype(var);`|**`int`**|The type of variable `var`.| -|`decltype(a->x);`|**`double`**|The type of the member access.| -|`decltype((a->x));`|`const double&`|The inner parentheses cause the statement to be evaluated as an expression instead of a member access. And because `a` is declared as a **`const`** pointer, the type is a reference to **`const double`**.| +| Statement | Type | Notes | +|--|--|--| +| `decltype(fx());` | `const int&&` | An [rvalue reference](../cpp/rvalue-reference-declarator-amp-amp.md) to a **`const int`**. | +| `decltype(var);` | **`int`** | The type of variable `var`. | +| `decltype(a->x);` | **`double`** | The type of the member access. | +| `decltype((a->x));` | `const double&` | The inner parentheses cause the statement to be evaluated as an expression instead of a member access. And because `a` is declared as a **`const`** pointer, the type is a reference to **`const double`**. | -## Decltype and Auto +## `decltype` and `auto` -In C++14, you can use `decltype(auto)` with no trailing return type to declare a template function whose return type depends on the types of its template arguments. +In C++14, you can use `decltype(auto)` with no trailing return type to declare a function template whose return type depends on the types of its template arguments. -In C++11, you can use the **`decltype`** type specifier on a trailing return type, together with the **`auto`** keyword, to declare a template function whose return type depends on the types of its template arguments. For example, consider the following code example in which the return type of the template function depends on the types of the template arguments. In the code example, the *UNKNOWN* placeholder indicates that the return type cannot be specified. +In C++11, you can use the **`decltype`** type specifier on a trailing return type, together with the **`auto`** keyword, to declare a function template whose return type depends on the types of its template arguments. For example, consider the following code example in which the return type of the function template depends on the types of the template arguments. In the code example, the *`UNKNOWN`* placeholder indicates that the return type can't be specified. ```cpp template UNKNOWN func(T&& t, U&& u){ return t + u; }; ``` -The introduction of the **`decltype`** type specifier enables a developer to obtain the type of the expression that the template function returns. Use the *alternative function declaration syntax* that is shown later, the **`auto`** keyword, and the **`decltype`** type specifier to declare a *late-specified* return type. The late-specified return type is determined when the declaration is compiled, instead of when it is coded. +The introduction of the **`decltype`** type specifier enables a developer to obtain the type of the expression that the function template returns. Use the *alternative function declaration syntax* that is shown later, the **`auto`** keyword, and the **`decltype`** type specifier to declare a *late-specified* return type. The late-specified return type is determined when the declaration is compiled, instead of when it's coded. -The following prototype illustrates the syntax of an alternative function declaration. Note that the **`const`** and **`volatile`** qualifiers, and the **`throw`** [exception specification](../cpp/exception-specifications-throw-cpp.md) are optional. The *function_body* placeholder represents a compound statement that specifies what the function does. As a best coding practice, the *expression* placeholder in the **`decltype`** statement should match the expression specified by the **`return`** statement, if any, in the *function_body*. +The following prototype illustrates the syntax of an alternative function declaration. The **`const`** and **`volatile`** qualifiers, and the **`throw`** [exception specification](../cpp/exception-specifications-throw-cpp.md) are optional. The *`function_body`* placeholder represents a compound statement that specifies what the function does. As a best coding practice, the *`expression`* placeholder in the **`decltype`** statement should match the expression specified by the **`return`** statement, if any, in the *`function_body`*. -**`auto`** *function_name* **`(`** *parameters*opt **`)`** **`const`**opt **`volatile`**opt **`->`** **`decltype(`** *expression* **`)`** **`noexcept`**opt **`{`** *function_body* **`};`** +**`auto`** *`function_name`* **`(`** *`parameters`*opt **`)`** **`const`**opt **`volatile`**opt **`->`** **`decltype(`** *`expression`* **`)`** **`noexcept`**opt **`{`** *`function_body`* **`};`** -In the following code example, the late-specified return type of the `myFunc` template function is determined by the types of the `t` and `u` template arguments. As a best coding practice, the code example also uses rvalue references and the `forward` function template, which support *perfect forwarding*. For more information, see [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +In the following code example, the late-specified return type of the `myFunc` function template is determined by the types of the `t` and `u` template arguments. As a best coding practice, the code example also uses rvalue references and the `forward` function template, which support *perfect forwarding*. For more information, see [Rvalue reference declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). ```cpp //C++11 @@ -84,15 +83,15 @@ decltype(auto) myFunc(T&& t, U&& u) { return forward(t) + forward(u); }; ``` -## Decltype and Forwarding Functions (C++11) +## `decltype` and forwarding functions (C++11) Forwarding functions wrap calls to other functions. Consider a function template that forwards its arguments, or the results of an expression that involves those arguments, to another function. Furthermore, the forwarding function returns the result of calling the other function. In this scenario, the return type of the forwarding function should be the same as the return type of the wrapped function. -In this scenario, you cannot write an appropriate type expression without the **`decltype`** type specifier. The **`decltype`** type specifier enables generic forwarding functions because it does not lose required information about whether a function returns a reference type. For a code example of a forwarding function, see the previous `myFunc` template function example. +In this scenario, you can't write an appropriate type expression without the **`decltype`** type specifier. The **`decltype`** type specifier enables generic forwarding functions because it doesn't lose required information about whether a function returns a reference type. For a code example of a forwarding function, see the previous `myFunc` function template example. ## Examples -The following code example declares the late-specified return type of template function `Plus()`. The `Plus` function processes its two operands with the **`operator+`** overload. Consequently, the interpretation of the plus operator (**`+`**) and the return type of the `Plus` function depends on the types of the function arguments. +The following code example declares the late-specified return type of function template `Plus()`. The `Plus` function processes its two operands with the **`operator+`** overload. So, the interpretation of the plus operator (**`+`**) and the return type of the `Plus` function depends on the types of the function arguments. ```cpp // decltype_1.cpp @@ -164,7 +163,7 @@ Hello, world! x3.Dump() = 42 ``` -**Visual Studio 2017 and later:** The compiler parses **`decltype`** arguments when the templates are declared rather than instantiated. Consequently, if a non-dependent specialization is found in the **`decltype`** argument, it will not be deferred to instantiation-time and will be processed immediately and any resulting errors will be diagnosed at that time. +**Visual Studio 2017 and later:** The compiler parses **`decltype`** arguments when the templates are declared rather than instantiated. So, if a non-dependent specialization is found in the **`decltype`** argument, it won't be deferred to instantiation-time; it's processed immediately and any resulting errors are diagnosed at that time. The following example shows such a compiler error that is raised at the point of declaration: diff --git a/docs/cpp/delegating-constructors.md b/docs/cpp/delegating-constructors.md index bca843faa6..0760096e48 100644 --- a/docs/cpp/delegating-constructors.md +++ b/docs/cpp/delegating-constructors.md @@ -57,7 +57,7 @@ int main() { As you step through the previous example, notice that the constructor `class_c(int, int, int)` first calls the constructor `class_c(int, int)`, which in turn calls `class_c(int)`. Each of the constructors performs only the work that is not performed by the other constructors. -The first constructor that's called initializes the object so that all of its members are initialized at that point. You can’t do member initialization in a constructor that delegates to another constructor, as shown here: +The first constructor that's called initializes the object so that all of its members are initialized at that point. You can't do member initialization in a constructor that delegates to another constructor, as shown here: ```cpp class class_a { @@ -66,7 +66,7 @@ public: // member initialization here, no delegate class_a(string str) : m_string{ str } {} - //can’t do member initialization here + //can't do member initialization here // error C3511: a call to a delegating constructor shall be the only member-initializer class_a(string str, double dbl) : class_a(str) , m_double{ dbl } {} diff --git a/docs/cpp/destructors-cpp.md b/docs/cpp/destructors-cpp.md index feeb87d6a5..f1a95449ac 100644 --- a/docs/cpp/destructors-cpp.md +++ b/docs/cpp/destructors-cpp.md @@ -1,56 +1,59 @@ --- description: "Learn more about: Destructors (C++)" title: "Destructors (C++)" -ms.date: "07/20/2019" +ms.date: "11/29/2023" helpviewer_keywords: ["objects [C++], destroying", "destructors, C++"] -ms.assetid: afa859b0-f3bc-4c4d-b250-c68b335b6004 --- # Destructors (C++) -A destructor is a member function that is invoked automatically when the object goes out of scope or is explicitly destroyed by a call to **`delete`**. A destructor has the same name as the class, preceded by a tilde (`~`). For example, the destructor for class `String` is declared: `~String()`. +A destructor is a member function that is invoked automatically when the object goes out of scope or is explicitly destroyed by a call to **`delete`** or **`delete[]`**. A destructor has the same name as the class and is preceded by a tilde (`~`). For example, the destructor for class `String` is declared: `~String()`. -If you do not define a destructor, the compiler will provide a default one; for many classes this is sufficient. You only need to define a custom destructor when the class stores handles to system resources that need to be released, or pointers that own the memory they point to. +If you don't define a destructor, the compiler provides a default one, and for some classes this is sufficient. You need to define a custom destructor when the class maintains resources that must be explicitly released, such as handles to system resources or pointers to memory that should be released when an instance of the class is destroyed. Consider the following declaration of a `String` class: ```cpp // spec1_destructors.cpp -#include - -class String { -public: - String( char *ch ); // Declare constructor - ~String(); // and destructor. -private: - char *_text; - size_t sizeOfText; +#include // strlen() + +class String +{ + public: + String(const char* ch); // Declare the constructor + ~String(); // Declare the destructor + private: + char* _text{nullptr}; }; -// Define the constructor. -String::String( char *ch ) { - sizeOfText = strlen( ch ) + 1; +// Define the constructor +String::String(const char* ch) +{ + size_t sizeOfText = strlen(ch) + 1; // +1 to account for trailing NULL - // Dynamically allocate the correct amount of memory. - _text = new char[ sizeOfText ]; + // Dynamically allocate the correct amount of memory. + _text = new char[sizeOfText]; - // If the allocation succeeds, copy the initialization string. - if( _text ) - strcpy_s( _text, sizeOfText, ch ); + // If the allocation succeeds, copy the initialization string. + if (_text) + { + strcpy_s(_text, sizeOfText, ch); + } } // Define the destructor. -String::~String() { - // Deallocate the memory that was previously reserved - // for this string. - delete[] _text; +String::~String() +{ + // Deallocate the memory that was previously reserved for the string. + delete[] _text; } -int main() { - String str("The piper in the glen..."); +int main() +{ + String str("We love C++"); } ``` -In the preceding example, the destructor `String::~String` uses the **`delete`** operator to deallocate the space dynamically allocated for text storage. +In the preceding example, the destructor `String::~String` uses the **`delete[]`** operator to deallocate the space dynamically allocated for text storage. ## Declaring destructors @@ -58,35 +61,29 @@ Destructors are functions with the same name as the class but preceded by a tild Several rules govern the declaration of destructors. Destructors: -- Do not accept arguments. - -- Do not return a value (or **`void`**). - -- Cannot be declared as **`const`**, **`volatile`**, or **`static`**. However, they can be invoked for the destruction of objects declared as **`const`**, **`volatile`**, or **`static`**. - -- Can be declared as **`virtual`**. Using virtual destructors, you can destroy objects without knowing their type — the correct destructor for the object is invoked using the virtual function mechanism. Note that destructors can also be declared as pure virtual functions for abstract classes. +- Don't accept arguments. +- Don't return a value (or **`void`**). +- Can't be declared as **`const`**, **`volatile`**, or **`static`**. However, they can be invoked for the destruction of objects declared as **`const`**, **`volatile`**, or **`static`**. +- Can be declared as **`virtual`**. Using virtual destructors, you can destroy objects without knowing their type—the correct destructor for the object is invoked using the virtual function mechanism. Destructors can also be declared as pure virtual functions for abstract classes. ## Using destructors Destructors are called when one of the following events occurs: - A local (automatic) object with block scope goes out of scope. - -- An object allocated using the **`new`** operator is explicitly deallocated using **`delete`**. - +- Use **`delete`** to deallocate an object allocated using **`new`**. Using **`delete[]`** results in undefined behaviour. +- Use **`delete[]`** to deallocate an object allocated using **`new[]`**. Using **`delete`** results in undefined behaviour. - The lifetime of a temporary object ends. - - A program ends and global or static objects exist. - - The destructor is explicitly called using the destructor function's fully qualified name. Destructors can freely call class member functions and access class member data. There are two restrictions on the use of destructors: -- You cannot take its address. +- You can't take its address. -- Derived classes do not inherit the destructor of their base class. +- Derived classes don't inherit the destructor of their base class. ## Order of destruction @@ -94,7 +91,7 @@ When an object goes out of scope or is deleted, the sequence of events in its co 1. The class's destructor is called, and the body of the destructor function is executed. -1. Destructors for nonstatic member objects are called in the reverse order in which they appear in the class declaration. The optional member initialization list used in construction of these members does not affect the order of construction or destruction. +1. Destructors for nonstatic member objects are called in the reverse order in which they appear in the class declaration. The optional member initialization list used in construction of these members doesn't affect the order of construction or destruction. 1. Destructors for non-virtual base classes are called in the reverse order of declaration. @@ -124,8 +121,10 @@ int main() { B3 * b2 = new B3; delete b2; } +``` -Output: A3 dtor +```output +A3 dtor A2 dtor A1 dtor @@ -140,56 +139,44 @@ B1 dtor Destructors for virtual base classes are called in the reverse order of their appearance in a directed acyclic graph (depth-first, left-to-right, postorder traversal). the following figure depicts an inheritance graph. -![Inheritance graph that shows virtual base classes.](../cpp/media/vc392j1.gif "Inheritance graph that shows virtual base classes")
-Inheritance graph that shows virtual base classes +:::image type="complex" source="../cpp/media/vc392j1.gif" alt-text="Inheritance graph that shows virtual base classes."::: +Five classes, labeled A through E, are arranged in an inheritance graph. Class E is the base class of B, C, and D. Classes C and D are the base class of A and B. +:::image-end::: -The following lists the class heads for the classes shown in the figure. +The following lists the class definitions for the classes shown in the figure: ```cpp -class A -class B -class C : virtual public A, virtual public B -class D : virtual public A, virtual public B -class E : public C, public D, virtual public B +class A {}; +class B {}; +class C : virtual public A, virtual public B {}; +class D : virtual public A, virtual public B {}; +class E : public C, public D, virtual public B {}; ``` To determine the order of destruction of the virtual base classes of an object of type `E`, the compiler builds a list by applying the following algorithm: 1. Traverse the graph left, starting at the deepest point in the graph (in this case, `E`). - 1. Perform leftward traversals until all nodes have been visited. Note the name of the current node. - 1. Revisit the previous node (down and to the right) to find out whether the node being remembered is a virtual base class. - -1. If the remembered node is a virtual base class, scan the list to see whether it has already been entered. If it is not a virtual base class, ignore it. - -1. If the remembered node is not yet in the list, add it to the bottom of the list. - +1. If the remembered node is a virtual base class, scan the list to see whether it has already been entered. If it isn't a virtual base class, ignore it. +1. If the remembered node isn't yet in the list, add it to the bottom of the list. 1. Traverse the graph up and along the next path to the right. - 1. Go to step 2. - 1. When the last upward path is exhausted, note the name of the current node. - 1. Go to step 3. - 1. Continue this process until the bottom node is again the current node. Therefore, for class `E`, the order of destruction is: 1. The non-virtual base class `E`. - 1. The non-virtual base class `D`. - 1. The non-virtual base class `C`. - 1. The virtual base class `B`. - 1. The virtual base class `A`. -This process produces an ordered list of unique entries. No class name appears twice. Once the list is constructed, it is walked in reverse order, and the destructor for each of the classes in the list from the last to the first is called. +This process produces an ordered list of unique entries. No class name appears twice. Once the list is constructed, it's walked in reverse order, and the destructor for each of the classes in the list from the last to the first is called. -The order of construction or destruction is primarily important when constructors or destructors in one class rely on the other component being created first or persisting longer — for example, if the destructor for `A` (in the figure shown above) relied on `B` still being present when its code executed, or vice versa. +The order of construction or destruction is primarily important when constructors or destructors in one class rely on the other component being created first or persisting longer—for example, if the destructor for `A` (in the figure shown previously) relied on `B` still being present when its code executed, or vice versa. Such interdependencies between classes in an inheritance graph are inherently dangerous because classes derived later can alter which is the leftmost path, thereby changing the order of construction and destruction. @@ -206,7 +193,7 @@ In the preceding example, the destructor for `Base2` is called before the destru ## Explicit destructor calls -Calling a destructor explicitly is seldom necessary. However, it can be useful to perform cleanup of objects placed at absolute addresses. These objects are commonly allocated using a user-defined **`new`** operator that takes a placement argument. The **`delete`** operator cannot deallocate this memory because it is not allocated from the free store (for more information, see [The new and delete Operators](../cpp/new-and-delete-operators.md)). A call to the destructor, however, can perform appropriate cleanup. To explicitly call the destructor for an object, `s`, of class `String`, use one of the following statements: +Calling a destructor explicitly is seldom necessary. However, it can be useful to perform cleanup of objects placed at absolute addresses. These objects are commonly allocated using a user-defined **`new`** operator that takes a placement argument. The **`delete`** operator can't deallocate this memory because it isn't allocated from the free store (for more information, see [The new and delete Operators](../cpp/new-and-delete-operators.md)). A call to the destructor, however, can perform appropriate cleanup. To explicitly call the destructor for an object, `s`, of class `String`, use one of the following statements: ```cpp s.String::~String(); // non-virtual call @@ -222,7 +209,7 @@ The notation for explicit calls to destructors, shown in the preceding, can be u A class needs a destructor if it acquires a resource, and to manage the resource safely it probably has to implement a copy constructor and a copy assignment. -If these special functions are not defined by the user, they are implicitly defined by the compiler. The implicitly generated constructors and assignment operators perform shallow, memberwise copy, which is almost certainly wrong if an object is managing a resource. +If these special functions aren't defined by the user, they're implicitly defined by the compiler. The implicitly generated constructors and assignment operators perform shallow, memberwise copy, which is almost certainly wrong if an object is managing a resource. In the next example, the implicitly generated copy constructor will make the pointers `str1.text` and `str2.text` refer to the same memory, and when we return from `copy_strings()`, that memory will be deleted twice, which is undefined behavior: @@ -239,5 +226,5 @@ Explicitly defining a destructor, copy constructor, or copy assignment operator ## See also -[Copy Constructors and Copy Assignment Operators](../cpp/copy-constructors-and-copy-assignment-operators-cpp.md)
+[Copy Constructors and Copy Assignment Operators](../cpp/copy-constructors-and-copy-assignment-operators-cpp.md)\ [Move Constructors and Move Assignment Operators](../cpp/move-constructors-and-move-assignment-operators-cpp.md) diff --git a/docs/cpp/dllexport-dllimport.md b/docs/cpp/dllexport-dllimport.md index 5146083a11..e19dca7628 100644 --- a/docs/cpp/dllexport-dllimport.md +++ b/docs/cpp/dllexport-dllimport.md @@ -1,12 +1,12 @@ --- description: "Learn more about: dllexport, dllimport" title: "dllexport, dllimport" -ms.date: "11/04/2016" +ms.date: 05/24/2022 f1_keywords: ["dllimport_cpp", "dllexport_cpp"] helpviewer_keywords: ["dllexport __declspec keyword", "__declspec keyword [C++], dllexport", "dllimport __declspec keyword", "__declspec keyword [C++], dllimport"] ms.assetid: ff95b645-ef55-4e72-b848-df44657b3208 --- -# dllexport, dllimport +# `dllexport`, `dllimport` **Microsoft Specific** @@ -14,20 +14,18 @@ The **`dllexport`** and **`dllimport`** storage-class attributes are Microsoft-s ## Syntax -``` - __declspec( dllimport ) declarator - __declspec( dllexport ) declarator -``` +> **`__declspec( dllimport )`** *`declarator`*\ +> **`__declspec( dllexport )`** *`declarator`* ## Remarks -These attributes explicitly define the DLL's interface to its client, which can be the executable file or another DLL. Declaring functions as **`dllexport`** eliminates the need for a module-definition (.def) file, at least with respect to the specification of exported functions. The **`dllexport`** attribute replaces the **__export** keyword. +These attributes explicitly define the DLL's interface to its client, which can be the executable file or another DLL. Declaring functions as **`dllexport`** eliminates the need for a module-definition (`.def`) file, at least with respect to the specification of exported functions. The **`dllexport`** attribute replaces the **`__export`** keyword. -If a class is marked declspec(dllexport), any specializations of class templates in the class hierarchy are implicitly marked as declspec(dllexport). This means that class templates are explicitly instantiated and the class's members must be defined. +If a class is marked `__declspec(dllexport)`, any specializations of class templates in the class hierarchy are implicitly marked as `__declspec(dllexport)`. It means that class templates are explicitly instantiated and the class's members must be defined. -**`dllexport`** of a function exposes the function with its decorated name. For C++ functions, this includes name mangling. For C functions or functions that are declared as `extern "C"`, this includes platform-specific decoration that's based on the calling convention. For information on name decoration in C/C++ code, see [Decorated Names](../build/reference/decorated-names.md). No name decoration is applied to exported C functions or C++ `extern "C"` functions using the **`__cdecl`** calling convention. +**`dllexport`** of a function exposes the function with its decorated name, sometimes known as "name mangling". For C++ functions, the decorated name includes extra characters that encode type and parameter information. C functions or functions that are declared as `extern "C"` follow C name decoration rules. For more information on name decoration in C/C++ code, see [Decorated names](../build/reference/decorated-names.md). -To export an undecorated name, you can link by using a Module Definition (.def) file that defines the undecorated name in an EXPORTS section. For more information, see [EXPORTS](../build/reference/exports.md). Another way to export an undecorated name is to use a `#pragma comment(linker, "/export:alias=decorated_name")` directive in the source code. +To export an undecorated name, you can link by using a Module Definition (`.def`) file that defines the undecorated name in an `EXPORTS` section. For more information, see [`EXPORTS`](../build/reference/exports.md). Another way to export an undecorated name is to use a `#pragma comment(linker, "/export:alias=decorated_name")` directive in the source code. When you declare **`dllexport`** or **`dllimport`**, you must use [extended attribute syntax](../cpp/declspec.md) and the **`__declspec`** keyword. @@ -53,17 +51,17 @@ DllExport int n; For more information, see: -- [Definitions and Declarations](../cpp/definitions-and-declarations-cpp.md) +- [Definitions and declarations](../cpp/definitions-and-declarations-cpp.md) -- [Defining Inline C++ Functions with dllexport and dllimport](../cpp/defining-inline-cpp-functions-with-dllexport-and-dllimport.md) +- [Defining inline C++ functions with `dllexport` and `dllimport`](../cpp/defining-inline-cpp-functions-with-dllexport-and-dllimport.md) -- [General Rules and Limitations](../cpp/general-rules-and-limitations.md) +- [General rules and limitations](../cpp/general-rules-and-limitations.md) -- [Using dllimport and dllexport in C++ Classes](../cpp/using-dllimport-and-dllexport-in-cpp-classes.md) +- [Using `dllimport` and `dllexport` in C++ classes](../cpp/using-dllimport-and-dllexport-in-cpp-classes.md) **END Microsoft Specific** ## See also -[__declspec](../cpp/declspec.md)
+[`__declspec`](../cpp/declspec.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/dynamic-cast-operator.md b/docs/cpp/dynamic-cast-operator.md index 6093be23a7..cf31a13818 100644 --- a/docs/cpp/dynamic-cast-operator.md +++ b/docs/cpp/dynamic-cast-operator.md @@ -4,7 +4,6 @@ description: "Overview of the C++ language dynamic_cast operator." ms.date: "02/03/2020" f1_keywords: ["dynamic_cast_cpp"] helpviewer_keywords: ["dynamic_cast keyword [C++]"] -ms.assetid: f380ada8-6a18-4547-93c9-63407f19856b --- # dynamic_cast Operator @@ -20,15 +19,15 @@ dynamic_cast < type-id > ( expression ) The `type-id` must be a pointer or a reference to a previously defined class type or a "pointer to void". The type of `expression` must be a pointer if `type-id` is a pointer, or an l-value if `type-id` is a reference. -See [static_cast](../cpp/static-cast-operator.md) for an explanation of the difference between static and dynamic casting conversions, and when it is appropriate to use each. +See [static_cast](../cpp/static-cast-operator.md) for an explanation of the difference between static and dynamic casting conversions, and when it's appropriate to use each. There are two breaking changes in the behavior of **`dynamic_cast`** in managed code: - **`dynamic_cast`** to a pointer to the underlying type of a boxed enum will fail at runtime, returning 0 instead of the converted pointer. -- **`dynamic_cast`** will no longer throw an exception when `type-id` is an interior pointer to a value type, with the cast failing at runtime. The cast will now return the 0 pointer value instead of throwing. +- **`dynamic_cast`** will no longer throw an exception when `type-id` is an interior pointer to a value type; instead, the cast fails at runtime. The cast returns the 0 pointer value instead of throwing. -If `type-id` is a pointer to an unambiguous accessible direct or indirect base class of `expression`, a pointer to the unique subobject of type `type-id` is the result. For example: +If `type-id` is a pointer to an unambiguous accessible direct or indirect base class of `expression`, then a pointer to the unique subobject of type `type-id` is the result. For example: ```cpp // dynamic_cast_1.cpp @@ -45,7 +44,7 @@ void f(D* pd) { } ``` -This type of conversion is called an "upcast" because it moves a pointer up a class hierarchy, from a derived class to a class it is derived from. An upcast is an implicit conversion. +This type of conversion is called an "upcast" because it moves a pointer up a class hierarchy, from a derived class to a class it's derived from. An upcast is an implicit conversion. If `type-id` is void*, a run-time check is made to determine the actual type of `expression`. The result is a pointer to the complete object pointed to by `expression`. For example: @@ -66,7 +65,7 @@ void f() { } ``` -If `type-id` is not void*, a run-time check is made to see if the object pointed to by `expression` can be converted to the type pointed to by `type-id`. +If `type-id` isn't `void*`, a run-time check is made to see if the object pointed to by `expression` can be converted to the type pointed to by `type-id`. If the type of `expression` is a base class of the type of `type-id`, a run-time check is made to see if `expression` actually points to a complete object of the type of `type-id`. If this is true, the result is a pointer to a complete object of the type of `type-id`. For example: @@ -114,8 +113,9 @@ int main() { } ``` -![Class hierarchy that shows multiple inheritance.](../cpp/media/vc39011.gif "Class hierarchy that shows multiple inheritance")
-Class hierarchy that shows multiple inheritance +:::image type="complex" source="../cpp/media/vc39011.gif" alt-text="Diagram that shows multiple inheritance."::: +The diagram shows a class hierarchy with A as a base class of B which is a base class of D. A is also a base class for C, which is a base class for D. Class D inherits from both B and C. +:::image-end::: A pointer to an object of type `D` can be safely cast to `B` or `C`. However, if `D` is cast to point to an `A` object, which instance of `A` would result? This would result in an ambiguous casting error. To get around this problem, you can perform two unambiguous casts. For example: @@ -137,14 +137,18 @@ void f() { Further ambiguities can be introduced when you use virtual base classes. Consider the class hierarchy shown in the following figure. -![Class hierarchy that shows virtual base classes.](../cpp/media/vc39012.gif "Class hierarchy that shows virtual base classes")
+:::image type="complex" source="../cpp/media/vc39012.gif" alt-text="Diagram of a class hierarchy that shows virtual base classes."::: +The diagram shows the classes A, B, C, D, and E arranged as follows: Class A is a base class of B. Classes C and E each derive from B. Class E also inherits from D, which inherits from class B, which inherits from class A. +:::image-end::: Class hierarchy that shows virtual base classes -In this hierarchy, `A` is a virtual base class. Given an instance of class `E` and a pointer to the `A` subobject, a **`dynamic_cast`** to a pointer to `B` will fail due to ambiguity. You must first cast back to the complete `E` object, then work your way back up the hierarchy, in an unambiguous manner, to reach the correct `B` object. +In this hierarchy, `A` is a virtual base class. Given an instance of class `E` and a pointer to the `A` subobject, a **`dynamic_cast`** to a pointer to `B` fails due to ambiguity. You must first cast back to the complete `E` object, then work your way back up the hierarchy, in an unambiguous manner, to reach the correct `B` object. Consider the class hierarchy shown in the following figure. -![Class hierarchy that shows duplicate base classes.](../cpp/media/vc39013.gif "Class hierarchy that shows duplicate base classes")
+:::image type="complex" source="../cpp/media/vc39013.gif" alt-text="Diagram of a class hierarchy that shows duplicate base classes."::: +The diagram shows the classes A, B, C, D, and E arranged as follows: Class B derives from Class A. Class C derives from class A. class D derives from class B. Class E derives from class C, which derives from class A. In this case, the duplicate base class is class A, which is directly or indirectly inherited by all the other classes. Class A is inherited directly by classes B and C, and indirectly by class D via class B, and indirectly by class E via class C, and indirectly in class D via class B. +:::image-end::: Class hierarchy that shows duplicate base classes Given an object of type `E` and a pointer to the `D` subobject, to navigate from the `D` subobject to the left-most `A` subobject, three conversions can be made. You can perform a **`dynamic_cast`** conversion from the `D` pointer to an `E` pointer, then a conversion (either **`dynamic_cast`** or an implicit conversion) from `E` to `B`, and finally an implicit conversion from `B` to `A`. For example: @@ -165,9 +169,9 @@ void f(D* pd) { } ``` -The **`dynamic_cast`** operator can also be used to perform a "cross cast." Using the same class hierarchy, it is possible to cast a pointer, for example, from the `B` subobject to the `D` subobject, as long as the complete object is of type `E`. +The **`dynamic_cast`** operator can also be used to perform a "cross cast." Using the same class hierarchy, it's possible to cast a pointer, for example, from the `B` subobject to the `D` subobject, as long as the complete object is of type `E`. -Considering cross casts, it is actually possible to do the conversion from a pointer to `D` to a pointer to the left-most `A` subobject in just two steps. You can perform a cross cast from `D` to `B`, then an implicit conversion from `B` to `A`. For example: +Considering cross casts, it's possible to do the conversion from a pointer to `D` to a pointer to the left-most `A` subobject in just two steps. You can perform a cross cast from `D` to `B`, then an implicit conversion from `B` to `A`. For example: ```cpp // dynamic_cast_6.cpp @@ -186,7 +190,7 @@ void f(D* pd) { A null pointer value is converted to the null pointer value of the destination type by **`dynamic_cast`**. -When you use `dynamic_cast < type-id > ( expression )`, if `expression` cannot be safely converted to type `type-id`, the run-time check causes the cast to fail. For example: +When you use `dynamic_cast < type-id > ( expression )`, if `expression` can't be safely converted to type `type-id`, the run-time check causes the cast to fail. For example: ```cpp // dynamic_cast_7.cpp @@ -201,7 +205,7 @@ void f() { } ``` -The value of a failed cast to pointer type is the null pointer. A failed cast to reference type throws a [bad_cast Exception](../cpp/bad-cast-exception.md). If `expression` does not point to or reference a valid object, a `__non_rtti_object` exception is thrown. +The value of a failed cast to pointer type is the null pointer. A failed cast to reference type throws a [bad_cast Exception](../cpp/bad-cast-exception.md). If `expression` doesn't point to or reference a valid object, a `__non_rtti_object` exception is thrown. See [typeid](../cpp/typeid-operator.md) for an explanation of the `__non_rtti_object` exception. @@ -209,7 +213,7 @@ See [typeid](../cpp/typeid-operator.md) for an explanation of the `__non_rtti_ob The following sample creates the base class (struct A) pointer, to an object (struct C). This, plus the fact there are virtual functions, enables runtime polymorphism. -The sample also calls a non-virtual function in the hierarchy. +The sample also calls a nonvirtual function in the hierarchy. ```cpp // dynamic_cast_8.cpp @@ -270,7 +274,7 @@ int main() { C ConStack; Globaltest(ConStack); - // will fail because B knows nothing about C + // fails because B knows nothing about C B BonStack; Globaltest(BonStack); } diff --git a/docs/cpp/ellipses-and-variadic-templates.md b/docs/cpp/ellipses-and-variadic-templates.md index a2d3467566..a7e40b2769 100644 --- a/docs/cpp/ellipses-and-variadic-templates.md +++ b/docs/cpp/ellipses-and-variadic-templates.md @@ -1,40 +1,40 @@ --- -description: "Learn more about: Ellipsis and Variadic Templates" -title: "Ellipsis and Variadic Templates" -ms.date: "11/04/2016" +description: "Learn more about: Ellipsis and variadic templates" +title: "Ellipsis and variadic templates" +ms.date: 09/27/2022 ms.assetid: f20967d9-c967-4fd2-b902-2bb1d5ed87e3 --- -# Ellipsis and Variadic Templates +# Ellipsis and variadic templates This article shows how to use the ellipsis (`...`) with C++ variadic templates. The ellipsis has had many uses in C and C++. These include variable argument lists for functions. The `printf()` function from the C Runtime Library is one of the most well-known examples. -A *variadic template* is a class or function template that supports an arbitrary number of arguments. This mechanism is especially useful to C++ library developers because you can apply it to both class templates and function templates, and thereby provide a wide range of type-safe and non-trivial functionality and flexibility. +A *variadic template* is a class or function template that supports an arbitrary number of arguments. This mechanism is especially useful to C++ library developers: You can apply it to both class templates and function templates, and thereby provide a wide range of type-safe and non-trivial functionality and flexibility. ## Syntax An ellipsis is used in two ways by variadic templates. To the left of the parameter name, it signifies a *parameter pack*, and to the right of the parameter name, it expands the parameter packs into separate names. -Here's a basic example of *variadic template class* definition syntax: +Here's a basic example of *variadic class template* definition syntax: ```cpp template class classname; ``` -For both parameter packs and expansions, you can add whitespace around the ellipsis, based on your preference, as shown in these examples: +For both parameter packs and expansions, you can add whitespace around the ellipsis, based on your preference, as shown in this example: ```cpp template class classname; ``` -Or this: +Or this example: ```cpp template class classname; ``` -Notice that this article uses the convention that's shown in the first example (the ellipsis is attached to **`typename`**). +This article uses the convention that's shown in the first example (the ellipsis is attached to **`typename`**). -In the preceding examples, *Arguments* is a parameter pack. The class `classname` can accept a variable number of arguments, as in these examples: +In the preceding examples, *`Arguments`* is a parameter pack. The class `classname` can accept a variable number of arguments, as in these examples: ```cpp template class vtclass; @@ -45,21 +45,21 @@ vtclass vtinstance3; vtclass, std::string> vtinstance4; ``` -By using a variadic template class definition, you can also require at least one parameter: +By using a variadic class template definition, you can also require at least one parameter: ```cpp template class classname; ``` -Here's a basic example of *variadic template function* syntax: +Here's a basic example of *variadic function template* syntax: ```cpp template returntype functionname(Arguments... args); ``` -The *Arguments* parameter pack is then expanded for use, as shown in the next section, **Understanding variadic templates**. +The *`Arguments`* parameter pack is then expanded for use, as shown in the next section. -Other forms of variadic template function syntax are possible—including, but not limited to, these examples: +Other forms of variadic function template syntax are possible—including, but not limited to, these examples: ```cpp template returntype functionname(Arguments&... args); @@ -95,7 +95,7 @@ void tfunc(const Arguments&... args) ## More about ellipsis placement -Previously, this article described ellipsis placement that defines parameter packs and expansions as "to the left of the parameter name, it signifies a parameter pack, and to the right of the parameter name, it expands the parameter packs into separate names". This is technically true but can be confusing in translation to code. Consider: +Previously, this article described ellipsis placement that defines parameter packs and expansions in this form: "to the left of the parameter name, it signifies a parameter pack, and to the right of the parameter name, it expands the parameter packs into separate names". While technically true, it can be confusing in translation to code. Consider: - In a template-parameter-list (`template `), `typename...` introduces a template parameter pack. @@ -113,7 +113,7 @@ Previously, this article described ellipsis placement that defines parameter pac ## Example -A good way to illustrate the variadic template function mechanism is to use it in a re-write of some of the functionality of `printf`: +A good way to illustrate the variadic function template mechanism is to use it in a rewrite of some of the functionality of `printf`: ```cpp #include @@ -156,4 +156,4 @@ first, 2, third, 3.14159 ``` > [!NOTE] -> Most implementations that incorporate variadic template functions use recursion of some form, but it's slightly different from traditional recursion. Traditional recursion involves a function calling itself by using the same signature. (It may be overloaded or templated, but the same signature is chosen each time.) Variadic recursion involves calling a variadic function template by using differing (almost always decreasing) numbers of arguments, and thereby stamping out a different signature every time. A "base case" is still required, but the nature of the recursion is different. +> Most implementations that incorporate variadic function templates use recursion of some form, but it's slightly different from traditional recursion. Traditional recursion involves a function calling itself by using the same signature. (It may be overloaded or templated, but the same signature is chosen each time.) Variadic recursion involves calling a variadic function template by using differing (almost always decreasing) numbers of arguments, and thereby stamping out a different signature every time. A "base case" is still required, but the nature of the recursion is different. diff --git a/docs/cpp/empty-bases.md b/docs/cpp/empty-bases.md new file mode 100644 index 0000000000..6c77223b4a --- /dev/null +++ b/docs/cpp/empty-bases.md @@ -0,0 +1,220 @@ +--- +description: "Learn more about: empty_bases" +title: "empty_bases" +ms.date: 03/01/2022 +f1_keywords: ["empty_bases_cpp", "empty_bases"] +helpviewer_keywords: ["__declspec keyword (C++), empty_bases", "empty_bases __declspec keyword"] +--- +# `empty_bases` + +**Microsoft Specific** + +The C++ Standard requires that a most-derived object must have a non-zero size and must occupy one or more bytes of storage. Because the requirement only extends to most-derived objects, base class subobjects aren't subject to this constraint. The Empty Base Class Optimization (EBCO) takes advantage of this liberty. It results in reduced memory consumption, which can improve performance. The Microsoft Visual C++ compiler has historically had limited support for EBCO. In Visual Studio 2015 Update 3 and later versions, we've added a new `__declspec(empty_bases)` attribute for class types that takes full advantage of this optimization. + +> [!IMPORTANT] +> Use of `__declspec(empty_bases)` can cause an ABI-breaking change in structure and class layout where it's applied. Make sure that all client code uses the same definitions for structures and classes as your code when you make use of this storage class attribute. + +## Syntax + +> **`__declspec( empty_bases )`** + +## Remarks + +In Visual Studio, absent any `__declspec(align())` or `alignas()` specifications, an empty class is 1 byte in size: + +```cpp +struct Empty1 {}; +static_assert(sizeof(Empty1) == 1, "Empty1 should be 1 byte"); +``` + +A class with a single non-static data member of type `char` is also 1 byte in size: + +```cpp +struct Struct1 +{ + char c; +}; +static_assert(sizeof(Struct1) == 1, "Struct1 should be 1 byte"); +``` + +Combining these classes in a class hierarchy also results in a class that's 1 byte in size: + +```cpp +struct Derived1 : Empty1 +{ + char c; +}; +static_assert(sizeof(Derived1) == 1, "Derived1 should be 1 byte"); +``` + +This result is the Empty Base Class Optimization at work, as without it `Derived1` would be 2 bytes in size: 1 byte for `Empty1` and 1 byte for `Derived1::c`. The class layout is also optimal when there's a chain of empty classes: + +```cpp +struct Empty2 : Empty1 {}; +struct Derived2 : Empty2 +{ + char c; +}; +static_assert(sizeof(Derived2) == 1, "Derived2 should be 1 byte"); +``` + +However, the default class layout in Visual Studio doesn't take advantage of EBCO in multiple inheritance scenarios: + +```cpp +struct Empty3 {}; +struct Derived3 : Empty2, Empty3 +{ + char c; +}; +static_assert(sizeof(Derived3) == 1, "Derived3 should be 1 byte"); // Error +``` + +Although `Derived3` could be 1 byte in size, the default class layout results in it being 2 bytes in size. The class layout algorithm is adding 1 byte of padding between any two consecutive empty base classes, effectively resulting in `Empty2` consuming an extra byte within `Derived3`: + +```` +class Derived3 size(2): + +--- +0 | +--- (base class Empty2) +0 | | +--- (base class Empty1) + | | +--- + | +--- +1 | +--- (base class Empty3) + | +--- +1 | c + +--- +```` + +The effects of this suboptimal layout are compounded when the alignment requirements of a later base class or member subobject force extra padding: + +```cpp +struct Derived4 : Empty2, Empty3 +{ + int i; +}; +static_assert(sizeof(Derived4) == 4, "Derived4 should be 4 bytes"); // Error +``` + +The natural alignment for an object of type `int` is 4 bytes, so 3 bytes of extra padding must be added after `Empty3` to correctly align `Derived4::i`: + +```` +class Derived4 size(8): + +--- +0 | +--- (base class Empty2) +0 | | +--- (base class Empty1) + | | +--- + | +--- +1 | +--- (base class Empty3) + | +--- + | (size=3) +4 | i + +--- +```` + +Another issue with the default class layout is that an empty base class may be laid out at an offset past the end of the class: + +```cpp +struct Struct2 : Struct1, Empty1 +{ +}; +static_assert(sizeof(Struct2) == 1, "Struct2 should be 1 byte"); +``` + +```` +class Struct2 size(1): + +--- +0 | +--- (base class Struct1) +0 | | c + | +--- +1 | +--- (base class Empty1) + | +--- + +--- +```` + +Although `Struct2` is the optimal size, `Empty1` is laid out at offset 1 within `Struct2` but the size of `Struct2` isn't increased to account for it. As a result, for an array `A` of `Struct2` objects, the address of the `Empty1` subobject of `A[0]` will be the same as the address of `A[1]`, which shouldn't be the case. This issue wouldn't occur if `Empty1` were laid out at offset 0 within `Struct2`, thereby overlapping the `Struct1` subobject. + +The default layout algorithm hasn't been modified to address these limitations and fully take advantage of EBCO. Such a change would break binary compatibility. If the default layout for a class changed as a result of EBCO, every object file and library that contains the class definition would need to be recompiled so they all agree on the class layout. This requirement would also extend to libraries obtained from external sources. The developers of such libraries would have to provide independent versions compiled both with and without the EBCO layout to support customers who use different versions of the compiler. Although we can't change the default layout, we can provide a means to change the layout on a per-class basis with the addition of the `__declspec(empty_bases)` class attribute. A class defined with this attribute can make full use of EBCO. + +```cpp +struct __declspec(empty_bases) Derived3 : Empty2, Empty3 +{ + char c; +}; +static_assert(sizeof(Derived3) == 1, "Derived3 should be 1 byte"); // No Error +``` + +```` +class Derived3 size(1): + +--- +0 | +--- (base class Empty2) +0 | | +--- (base class Empty1) + | | +--- + | +--- +0 | +--- (base class Empty3) + | +--- +0 | c + +--- +```` + +All of the subobjects of `Derived3` are laid out at offset 0, and its size is the optimal 1 byte. One important point to remember is that `__declspec(empty_bases)` only affects the layout of the class to which it's applied. It isn't applied recursively to base classes: + +```cpp +struct __declspec(empty_bases) Derived5 : Derived4 +{ +}; +static_assert(sizeof(Derived5) == 4, "Derived5 should be 4 bytes"); // Error +``` + +```` +class Derived5 size(8): + +--- +0 | +--- (base class Derived4) +0 | | +--- (base class Empty2) +0 | | | +--- (base class Empty1) + | | | +--- + | | +--- +1 | | +--- (base class Empty3) + | | +--- + | | (size=3) +4 | | i + | +--- + +--- +```` + +Although `__declspec(empty_bases)` is applied to `Derived5`, it isn't eligible for EBCO because it doesn't have any direct empty base classes, so it has no effect. However, if instead it's applied to the `Derived4` base class, which is eligible for EBCO, both `Derived4` and `Derived5` will have optimal layout: + +```cpp +struct __declspec(empty_bases) Derived4 : Empty2, Empty3 +{ + int i; +}; +static_assert(sizeof(Derived4) == 4, "Derived4 should be 4 bytes"); // No Error + +struct Derived5 : Derived4 +{ +}; +static_assert(sizeof(Derived5) == 4, "Derived5 should be 4 bytes"); // No Error +``` + +```` +class Derived5 size(4): + +--- +0 | +--- (base class Derived4) +0 | | +--- (base class Empty2) +0 | | | +--- (base class Empty1) + | | | +--- + | | +--- +0 | | +--- (base class Empty3) + | | +--- +0 | | i + | +--- + +--- +```` + +Because of the requirement that all object files and libraries agree on the class layout, `__declspec(empty_bases)` can only be applied to classes that you control. It can't be applied to classes in the standard library, or to classes included in libraries that aren't also recompiled with the EBCO layout. + +**END Microsoft Specific** + +## See also + +[`__declspec`](../cpp/declspec.md)\ +[Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/enumerations-cpp.md b/docs/cpp/enumerations-cpp.md index 917ec7f6c9..bce6d27a4e 100644 --- a/docs/cpp/enumerations-cpp.md +++ b/docs/cpp/enumerations-cpp.md @@ -1,55 +1,87 @@ --- description: "Learn more about: Enumerations (C++)" title: "Enumerations (C++)" -ms.date: "06/01/2018" +ms.date: 06/30/2022 f1_keywords: ["enum_cpp"] helpviewer_keywords: ["declarations, enumerations", "enumerators, declaring", "enum keyword [C++]", "named constants, enumeration declarations", "declaring enumerations"] ms.assetid: 081829db-5dca-411e-a53c-bffef315bcb3 --- # Enumerations (C++) -An enumeration is a user-defined type that consists of a set of named integral constants that are known as enumerators. +An enumeration is a user-defined type that consists of a set of named integral constants that are known as *enumerators*. > [!NOTE] -> This article covers the ISO Standard C++ Language **`enum`** type and the scoped (or strongly-typed) **enum class** type which is introduced in C++11. For information about the **public enum class** or **private enum class** types in C++/CLI and C++/CX, see [enum class](../extensions/enum-class-cpp-component-extensions.md). +> This article covers the ISO Standard C++ Language **`enum`** type and the scoped (or strongly-typed) **`enum class`** type which is introduced in C++11. For information about the **`public enum class`** or **`private enum class`** types in C++/CLI and C++/CX, see [`enum class` (C++/CLI and C++/CX)](../extensions/enum-class-cpp-component-extensions.md). ## Syntax -``` +*`enum-name`*:\ + *`identifier`* + +*`enum-specifier`*:\ + *`enum-head`* **`{`** *`enumerator-list`*opt **`}`**\ + *`enum-head`* **`{`** *`enumerator-list`* **`,`** **`}`** + +*`enum-head`*:\ + *`enum-key`* *`attribute-specifier-seq`*opt *`enum-head-name`*opt *`enum-base`*opt + +*`enum-head-name`*:\ + *`nested-name-specifier`*opt *`identifier`* + +*`opaque-enum-declaration`*:\ + *`enum-key`* *`attribute-specifier-seq`*opt *`enum-head-name`* *`enum-base`*opt **`;`** + +*`enum-key`*:\ + **`enum`**\ + **`enum class`**\ + **`enum struct`** + +*`enum-base`*:\ + **`:`** *`type-specifier-seq`* + +*`enumerator-list`*:\ + *`enumerator-definition`*\ + *`enumerator-list`* **`,`** *`enumerator-definition`* + +*`enumerator-definition`*:\ + *`enumerator`*\ + *`enumerator`* **`=`** *`constant-expression`* + +*`enumerator`*:\ + *`identifier`* *`attribute-specifier-seq`*opt + +## Usage + +```cpp // unscoped enum: -enum [identifier] [: type] -{enum-list}; +// enum [identifier] [: type] {enum-list}; // scoped enum: -enum [class|struct] -[identifier] [: type] -{enum-list}; -``` +// enum [class|struct] [identifier] [: type] {enum-list}; -```cpp // Forward declaration of enumerations (C++11): -enum A : int; // non-scoped enum must have type specified -enum class B; // scoped enum defaults to int but ... +enum A : int; // non-scoped enum must have type specified +enum class B; // scoped enum defaults to int but ... enum class C : short; // ... may have any integral underlying type ``` -## Parameters +### Parameters -*identifier*
+*`identifier`*\ The type name given to the enumeration. -*type*
+*`type`*\ The underlying type of the enumerators; all enumerators have the same underlying type. May be any integral type. -*enum-list*
-Comma-separated list of the enumerators in the enumeration. Every enumerator or variable name in the scope must be unique. However, the values can be duplicated. In a unscoped enum, the scope is the surrounding scope; in a scoped enum, the scope is the *enum-list* itself. In a scoped enum, the list may be empty which in effect defines a new integral type. +*`enum-list`*\ +Comma-separated list of the enumerators in the enumeration. Every enumerator or variable name in the scope must be unique. However, the values can be duplicated. In an unscoped enum, the scope is the surrounding scope; in a scoped enum, the scope is the *`enum-list`* itself. In a scoped enum, the list may be empty, which in effect defines a new integral type. -*class*
-By using this keyword in the declaration, you specify the enum is scoped, and an *identifier* must be provided. You can also use the **`struct`** keyword in place of **`class`**, as they are semantically equivalent in this context. +*`class`*\ +By using this keyword in the declaration, you specify the enum is scoped, and an *`identifier`* must be provided. You can also use the **`struct`** keyword in place of **`class`**, as they're semantically equivalent in this context. ## Enumerator scope -An enumeration provides context to describe a range of values which are represented as named constants and are also called enumerators. In the original C and C++ enum types, the unqualified enumerators are visible throughout the scope in which the enum is declared. In scoped enums, the enumerator name must be qualified by the enum type name. The following example demonstrates this basic difference between the two kinds of enums: +An enumeration provides context to describe a range of values that are represented as named constants. These named constants are also called *enumerators*. In the original C and C++ `enum` types, the unqualified enumerators are visible throughout the scope in which the `enum` is declared. In scoped enums, the enumerator name must be qualified by the `enum` type name. The following example demonstrates this basic difference between the two kinds of enums: ```cpp namespace CardGame_Scoped @@ -82,19 +114,19 @@ Every name in an enumeration is assigned an integral value that corresponds to i enum Suit { Diamonds = 1, Hearts, Clubs, Spades }; ``` -The enumerator `Diamonds` is assigned the value `1`. Subsequent enumerators, if they are not given an explicit value, receive the value of the previous enumerator plus one. In the previous example, `Hearts` would have the value 2, `Clubs` would have 3, and so on. +The enumerator `Diamonds` is assigned the value `1`. Subsequent enumerators, if they aren't given an explicit value, receive the value of the previous enumerator plus one. In the previous example, `Hearts` would have the value 2, `Clubs` would have 3, and so on. -Every enumerator is treated as a constant and must have a unique name within the scope where the **`enum`** is defined (for unscoped enums) or within the **`enum`** itself (for scoped enums). The values given to the names do not have to be unique. For example, if the declaration of a unscoped enum `Suit` is this: +Every enumerator is treated as a constant and must have a unique name within the scope where the **`enum`** is defined (for unscoped enums) or within the **`enum`** itself (for scoped enums). The values given to the names don't have to be unique. For example, consider this declaration of an unscoped enum `Suit`: ```cpp enum Suit { Diamonds = 5, Hearts, Clubs = 4, Spades }; ``` -Then the values of `Diamonds`, `Hearts`, `Clubs`, and `Spades` are 5, 6, 4, and 5, respectively. Notice that 5 is used more than once; this is allowed even though it may not be intended. These rules are the same for scoped enums. +The values of `Diamonds`, `Hearts`, `Clubs`, and `Spades` are 5, 6, 4, and 5, respectively. Notice that 5 is used more than once; it's allowed even though it may not be intended. These rules are the same for scoped enums. ## Casting rules -Unscoped enum constants can be implicitly converted to **`int`**, but an **`int`** is never implicitly convertible to an enum value. The following example shows what happens if you try to assign `hand` a value that is not a `Suit`: +Unscoped enum constants can be implicitly converted to **`int`**, but an **`int`** is never implicitly convertible to an enum value. The following example shows what happens if you try to assign `hand` a value that isn't a `Suit`: ```cpp int account_num = 135692; @@ -102,13 +134,13 @@ Suit hand; hand = account_num; // error C2440: '=' : cannot convert from 'int' to 'Suit' ``` -A cast is required to convert an **`int`** to a scoped or unscoped enumerator. However, you can promote a unscoped enumerator to an integer value without a cast. +A cast is required to convert an **`int`** to a scoped or unscoped enumerator. However, you can promote an unscoped enumerator to an integer value without a cast. ```cpp -int account_num = Hearts; //OK if Hearts is in a unscoped enum +int account_num = Hearts; //OK if Hearts is in an unscoped enum ``` -Using implicit conversions in this way can lead to unintended side-effects. To help eliminate programming errors associated with unscoped enums, scoped enum values are strongly typed. Scoped enumerators must be qualified by the enum type name (identifier) and cannot be implicitly converted, as shown in the following example: +Using implicit conversions in this way can lead to unintended side-effects. To help eliminate programming errors associated with unscoped enums, scoped enum values are strongly typed. Scoped enumerators must be qualified by the enum type name (identifier) and can't be implicitly converted, as shown in the following example: ```cpp namespace ScopedEnumConversions @@ -130,7 +162,7 @@ namespace ScopedEnumConversions } ``` -Notice that the line `hand = account_num;` still causes the error that occurs with unscoped enums, as shown earlier. It is allowed with an explicit cast. However, with scoped enums, the attempted conversion in the next statement, `account_num = Suit::Hearts;`, is no longer allowed without an explicit cast. +Notice that the line `hand = account_num;` still causes the error that occurs with unscoped enums, as shown earlier. It's allowed with an explicit cast. However, with scoped enums, the attempted conversion in the next statement, `account_num = Suit::Hearts;`, is no longer allowed without an explicit cast. ## Enums with no enumerators @@ -172,5 +204,5 @@ int main() ## See also -[C Enumeration Declarations](../c-language/c-enumeration-declarations.md)
+[C Enumeration declarations](../c-language/c-enumeration-declarations.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/equality-operators-equal-equal-and-exclpt-equal.md b/docs/cpp/equality-operators-equal-equal-and-exclpt-equal.md index 9701cac39f..c0853757bb 100644 --- a/docs/cpp/equality-operators-equal-equal-and-exclpt-equal.md +++ b/docs/cpp/equality-operators-equal-equal-and-exclpt-equal.md @@ -1,12 +1,11 @@ --- title: "Equality operators: == and !=" description: "The C++ standard language equal-to and not-equal-to operator syntax and use." -ms.date: 07/23/2020 -f1_keywords: ["!=", "==", "not_eq_cpp"] -helpviewer_keywords: ["!= operator", "equality operator", "not equal to comparison operator", "equality operator [C++], syntax", "== operator", "not_eq operator", "equal to operator"] -ms.assetid: ba4e9659-2392-4fb4-be5a-910a2a6df45a +ms.date: 08/09/2024 +f1_keywords: ["!=", "=="] +helpviewer_keywords: ["!= operator", "equality operator", "not equal to operator", "equality operator [C++], syntax", "== operator", "equal to operator"] --- -# Equality operators: == and != +# Equality operators: `==` and `!=` ## Syntax @@ -15,38 +14,41 @@ ms.assetid: ba4e9659-2392-4fb4-be5a-910a2a6df45a ## Remarks -The binary equality operators compare their operands for strict equality or inequality. +The equal-to operator (**`==`**) returns **`true`** if both operands have the same value; otherwise **`false`**.\ +The not-equal-to operator (**`!=`**) returns **`true`** if the operands don't have the same value; otherwise **`false`**. -The equality operators, equal to (**`==`**) and not equal to (**`!=`**), have lower precedence than the relational operators, but they behave similarly. The result type for these operators is **`bool`**. - -The equal-to operator (**`==`**) returns **`true`** if both operands have the same value; otherwise, it returns **`false`**. The not-equal-to operator (**`!=`**) returns **`true`** if the operands don't have the same value; otherwise, it returns **`false`**. - -## Operator keyword for != - -C++ specifies **`not_eq`** as an alternative spelling for **`!=`**. (There's no alternative spelling for **`==`**.) In C, the alternative spelling is provided as a macro in the \ header. In C++, the alternative spelling is a keyword; use of \ or the C++ equivalent \ is deprecated. In Microsoft C++, the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is required to enable the alternative spelling. +In C and C++, **`not_eq`** can be used as alternative to **`!=`**. For more information, see [`not-eq`](../c-runtime-library/reference/not-eq.md). ## Example ```cpp -// expre_Equality_Operators.cpp -// compile with: /EHsc #include -using namespace std; - -int main() { - cout << boolalpha - << "The true expression 3 != 2 yields: " - << (3 != 2) << endl - << "The false expression 20 == 10 yields: " - << (20 == 10) << endl; +int main() +{ + int x = 1, y = 1, z = 2; + + if (x == y) + { + std::cout << "Equal\n"; + } + + if (x != z) + { + std::cout << "Not equal\n"; + } } ``` -Equality operators can compare pointers to members of the same type. In such a comparison, pointer-to-member conversions are performed. Pointers to members can also be compared to a constant expression that evaluates to 0. +```output +Equal +Not equal +``` ## See also -[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)
-[C++ built-in operators, precedence; and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[`not-eq`](../c-runtime-library/reference/not-eq.md)\ +[Operator overloading](../cpp/operator-overloading.md)\ +[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)\ +[C++ built-in operators, precedence; and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C relational and equality operators](../c-language/c-relational-and-equality-operators.md) diff --git a/docs/cpp/errors-and-exception-handling-modern-cpp.md b/docs/cpp/errors-and-exception-handling-modern-cpp.md index d9feec1266..486a271ba8 100644 --- a/docs/cpp/errors-and-exception-handling-modern-cpp.md +++ b/docs/cpp/errors-and-exception-handling-modern-cpp.md @@ -1,9 +1,8 @@ --- title: "Modern C++ best practices for exceptions and error handling" description: "How Modern C++ supports exceptional programming styles over error codes." -ms.date: 08/24/2020 +ms.date: 03/22/2024 ms.topic: "conceptual" -ms.assetid: a6c111d0-24f9-4bbb-997d-3db4569761b7 --- # Modern C++ best practices for exceptions and error handling @@ -11,19 +10,20 @@ In modern C++, in most scenarios, the preferred way to report and handle both lo ## Use exceptions for exceptional code -Program errors are often divided into two categories: Logic errors that are caused by programming mistakes, for example, an "index out of range" error. And, runtime errors that are beyond the control of programmer, for example, a "network service unavailable" error. In C-style programming and in COM, error reporting is managed either by returning a value that represents an error code or a status code for a particular function, or by setting a global variable that the caller may optionally retrieve after every function call to see whether errors were reported. For example, COM programming uses the HRESULT return value to communicate errors to the caller. And the Win32 API has the `GetLastError` function to retrieve the last error that was reported by the call stack. In both of these cases, it's up to the caller to recognize the code and respond to it appropriately. If the caller doesn't explicitly handle the error code, the program might crash without warning. Or, it might continue to execute using bad data and produce incorrect results. +Program errors are often divided into two categories: +- Logic errors caused by programming mistakes. For example, an "index out of range" error. +- Runtime errors that are beyond the control of programmer. For example, a "network service unavailable" error. + +In C-style programming and in COM, error reporting is managed either by returning a value that represents an error code or a status code for a particular function, or by setting a global variable that the caller may optionally retrieve after every function call to see whether errors were reported. For example, COM programming uses the `HRESULT` return value to communicate errors to the caller. And the Win32 API has the `GetLastError` function to retrieve the last error reported by the call stack. In both of these cases, it's up to the caller to recognize the code and respond to it appropriately. If the caller doesn't explicitly handle the error code, the program might crash without warning. Or, it might continue to execute using bad data and produce incorrect results. Exceptions are preferred in modern C++ for the following reasons: - An exception forces calling code to recognize an error condition and handle it. Unhandled exceptions stop program execution. - - An exception jumps to the point in the call stack that can handle the error. Intermediate functions can let the exception propagate. They don't have to coordinate with other layers. - - The exception stack-unwinding mechanism destroys all objects in scope after an exception is thrown, according to well-defined rules. - - An exception enables a clean separation between the code that detects the error and the code that handles the error. -The following simplified example shows the necessary syntax for throwing and catching exceptions in C++. +The following simplified example shows the necessary syntax for throwing and catching exceptions in C++: ```cpp #include @@ -35,7 +35,9 @@ using namespace std; void MyFunc(int c) { if (c > numeric_limits< char> ::max()) + { throw invalid_argument("MyFunc argument too large."); + } //... } @@ -56,33 +58,27 @@ int main() } ``` -Exceptions in C++ resemble ones in languages such as C# and Java. In the **`try`** block, if an exception is *thrown* it will be *caught* by the first associated **`catch`** block whose type matches that of the exception. In other words, execution jumps from the **`throw`** statement to the **`catch`** statement. If no usable catch block is found, `std::terminate` is invoked and the program exits. In C++, any type may be thrown; however, we recommend that you throw a type that derives directly or indirectly from `std::exception`. In the previous example, the exception type, [`invalid_argument`](../standard-library/invalid-argument-class.md), is defined in the standard library in the [``](../standard-library/stdexcept.md) header file. C++ doesn't provide or require a **`finally`** block to make sure all resources are released if an exception is thrown. The resource acquisition is initialization (RAII) idiom, which uses smart pointers, provides the required functionality for resource cleanup. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). For information about the C++ stack-unwinding mechanism, see [Exceptions and stack unwinding](exceptions-and-stack-unwinding-in-cpp.md). +Exceptions in C++ resemble ones in languages such as C# and Java. In the **`try`** block, if an exception is *thrown* it is *caught* by the first associated **`catch`** block whose type matches that of the exception. In other words, execution jumps from the **`throw`** statement to the **`catch`** statement. If no usable catch block is found, `std::terminate` is invoked and the program exits. In C++, any type may be thrown; however, we recommend that you throw a type that derives directly or indirectly from `std::exception`. In the previous example, the exception type, [`invalid_argument`](../standard-library/invalid-argument-class.md), is defined in the standard library in the [``](../standard-library/stdexcept.md) header file. C++ doesn't provide or require a **`finally`** block to make sure all resources are released if an exception is thrown. The resource acquisition is initialization (RAII) idiom, which uses smart pointers, provides the required functionality for resource cleanup. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). For information about the C++ stack-unwinding mechanism, see [Exceptions and stack unwinding](exceptions-and-stack-unwinding-in-cpp.md). ## Basic guidelines Robust error handling is challenging in any programming language. Although exceptions provide several features that support good error handling, they can't do all the work for you. To realize the benefits of the exception mechanism, keep exceptions in mind as you design your code. -- Use asserts to check for errors that should never occur. Use exceptions to check for errors that might occur, for example, errors in input validation on parameters of public functions. For more information, see the [Exceptions versus assertions](#exceptions_versus_assertions) section. - +- Use asserts to check for conditions that should always be true or always be false. Use exceptions to check for errors that might occur, for example, errors in input validation on parameters of public functions. For more information, see the [Exceptions versus assertions](#exceptions_versus_assertions) section. - Use exceptions when the code that handles the error is separated from the code that detects the error by one or more intervening function calls. Consider whether to use error codes instead in performance-critical loops, when code that handles the error is tightly coupled to the code that detects it. - -- For every function that might throw or propagate an exception, provide one of the three exception guarantees: the strong guarantee, the basic guarantee, or the nothrow (noexcept) guarantee. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). - -- Throw exceptions by value, catch them by reference. Don’t catch what you can't handle. - +- For every function that might throw or propagate an exception, provide one of the three exception guarantees: the strong guarantee, the basic guarantee, or the nothrow (`noexcept`) guarantee. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). +- Throw exceptions by value, catch them by reference. Don't catch what you can't handle. - Don't use exception specifications, which are deprecated in C++11. For more information, see the [Exception specifications and `noexcept`](#exception_specifications_and_noexcept) section. - - Use standard library exception types when they apply. Derive custom exception types from the [`exception` Class](../standard-library/exception-class.md) hierarchy. - - Don't allow exceptions to escape from destructors or memory-deallocation functions. ## Exceptions and performance -The exception mechanism has a minimal performance cost if no exception is thrown. If an exception is thrown, the cost of the stack traversal and unwinding is roughly comparable to the cost of a function call. Additional data structures are required to track the call stack after a **`try`** block is entered, and additional instructions are required to unwind the stack if an exception is thrown. However, in most scenarios, the cost in performance and memory footprint isn't significant. The adverse effect of exceptions on performance is likely to be significant only on memory-constrained systems. Or, in performance-critical loops, where an error is likely to occur regularly and there's tight coupling between the code to handle it and the code that reports it. In any case, it's impossible to know the actual cost of exceptions without profiling and measuring. Even in those rare cases when the cost is significant, you can weigh it against the increased correctness, easier maintainability, and other advantages that are provided by a well-designed exception policy. +The exception mechanism has a minimal performance cost if no exception is thrown. If an exception is thrown, the cost of the stack traversal and unwinding is roughly comparable to the cost of a function call. Other data structures are required to track the call stack after a **`try`** block is entered, and more instructions are required to unwind the stack if an exception is thrown. However, in most scenarios, the cost in performance and memory footprint isn't significant. The adverse effect of exceptions on performance is likely to be significant only on memory-constrained systems. Or, in performance-critical loops, where an error is likely to occur regularly and there's tight coupling between the code to handle it and the code that reports it. In any case, it's impossible to know the actual cost of exceptions without profiling and measuring. Even in those rare cases when the cost is significant, you can weigh it against the increased correctness, easier maintainability, and other advantages that are provided by a well-designed exception policy. ## Exceptions versus assertions -Exceptions and asserts are two distinct mechanisms for detecting run-time errors in a program. Use `assert` statements to test for conditions during development that should never be true if all your code is correct. There's no point in handling such an error by using an exception, because the error indicates that something in the code has to be fixed. It doesn't represent a condition that the program has to recover from at run time. An `assert` stops execution at the statement so that you can inspect the program state in the debugger. An exception continues execution from the first appropriate catch handler. Use exceptions to check error conditions that might occur at run time even if your code is correct, for example, "file not found" or "out of memory." Exceptions can handle these conditions, even if the recovery just outputs a message to a log and ends the program. Always check arguments to public functions by using exceptions. Even if your function is error-free, you might not have complete control over arguments that a user might pass to it. +Exceptions and asserts are two distinct mechanisms for detecting run-time errors in a program. Use `assert` statements to test for conditions during development that should always be true or always be false if all your code is correct. There's no point in handling such an error by using an exception, because the error indicates that something in the code has to be fixed. It doesn't represent a condition that the program has to recover from at run time. An `assert` stops execution at the statement so that you can inspect the program state in the debugger. An exception continues execution from the first appropriate catch handler. Use exceptions to check error conditions that might occur at run time even if your code is correct, for example, "file not found" or "out of memory." Exceptions can handle these conditions, even if the recovery just outputs a message to a log and ends the program. Always check arguments to public functions by using exceptions. Even if your function is error-free, you might not have complete control over arguments that a user might pass to it. ## C++ exceptions versus Windows SEH exceptions @@ -96,6 +92,6 @@ Exception specifications were introduced in C++ as a way to specify the exceptio ## See also -[How to: Interface between exceptional and non-exceptional code](../cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md)
-[C++ language reference](../cpp/cpp-language-reference.md)
+[How to: Interface between exceptional and non-exceptional code](../cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md)\ +[C++ language reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/examples-of-lambda-expressions.md b/docs/cpp/examples-of-lambda-expressions.md index 7cb154f621..b61948f50c 100644 --- a/docs/cpp/examples-of-lambda-expressions.md +++ b/docs/cpp/examples-of-lambda-expressions.md @@ -3,7 +3,6 @@ description: "Learn more about: Examples of Lambda Expressions" title: "Examples of Lambda Expressions" ms.date: "05/07/2019" helpviewer_keywords: ["lambda expressions [C++], examples"] -ms.assetid: 52506b15-0771-4190-a966-2f302049ca86 --- # Examples of Lambda Expressions @@ -23,7 +22,6 @@ Because a lambda expression is typed, you can assign it to an **`auto`** variabl int main() { - using namespace std; // Assign the lambda expression that adds two numbers to an auto variable. @@ -53,7 +51,7 @@ Although lambda expressions are most often declared in the body of a function, y ### Example 2 -The Microsoft C++ compiler binds a lambda expression to its captured variables when the expression is declared instead of when the expression is called. The following example shows a lambda expression that captures the local variable `i` by value and the local variable `j` by reference. Because the lambda expression captures `i` by value, the reassignment of `i` later in the program does not affect the result of the expression. However, because the lambda expression captures `j` by reference, the reassignment of `j` does affect the result of the expression. +The Microsoft C++ compiler binds a lambda expression to its captured variables when the expression is declared instead of when the expression is called. The following example shows a lambda expression that captures the local variable `i` by value and the local variable `j` by reference. Because the lambda expression captures `i` by value, the reassignment of `i` later in the program doesn't affect the result of the expression. However, because the lambda expression captures `j` by reference, the reassignment of `j` does affect the result of the expression. ```cpp // declaring_lambda_expressions2.cpp @@ -320,7 +318,7 @@ int main() values.push_back(4); // Create a Scale object that scales elements by 3 and apply - // it to the vector object. Does not modify the vector. + // it to the vector object. doesn't modify the vector. Scale s(3); s.ApplyScale(values); } @@ -425,7 +423,7 @@ int main() // Create another vector that contains index values. vector indices(3); indices[0] = 0; - indices[1] = -1; // This is not a valid subscript. It will trigger an exception. + indices[-1] = 1; // This is not a valid subscript. It will trigger an exception. indices[2] = 2; // Use the values from the vector of index values to @@ -461,7 +459,7 @@ For more information about exception handling, see [Exception Handling](../cpp/e ### Example -The capture clause of a lambda expression cannot contain a variable that has a managed type. However, you can pass an argument that has a managed type to the parameter list of a lambda expression. The following example contains a lambda expression that captures the local unmanaged variable `ch` by value and takes a object as its parameter. +The capture clause of a lambda expression can't contain a variable that has a managed type. However, you can pass an argument that has a managed type to the parameter list of a lambda expression. The following example contains a lambda expression that captures the local unmanaged variable `ch` by value and takes a object as its parameter. ```cpp // managed_lambda_expression.cpp diff --git a/docs/cpp/exception-specifications-throw-cpp.md b/docs/cpp/exception-specifications-throw-cpp.md index d63159cfaf..268e410d73 100644 --- a/docs/cpp/exception-specifications-throw-cpp.md +++ b/docs/cpp/exception-specifications-throw-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Exception specifications (throw, noexcept) (C++)" title: "Exception specifications (throw, noexcept) (C++)" +description: "Learn more about: Exception specifications (throw, noexcept) (C++)" ms.date: "01/18/2018" helpviewer_keywords: ["exceptions [C++], exception specifications", "throwing exceptions [C++], throw keyword", "C++ exception handling [C++], throwing exceptions", "throw keyword [C++]", "noexcept keyword [C++]"] -ms.assetid: 4d3276df-6f31-4c7f-8cab-b9d2d003a629 --- # Exception specifications (throw, noexcept) (C++) @@ -25,7 +24,7 @@ The following table summarizes the Microsoft C++ implementation of exception spe |Exception specification|Meaning| |-----------------------------|-------------| -|**`noexcept`**
`noexcept(true)`
`throw()`|The function does not throw an exception. In **`/std:c++14`** mode (which is the default), **`noexcept`** and `noexcept(true)` are equivalent. When an exception is thrown from a function that is declared **`noexcept`** or `noexcept(true)`, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked. When an exception is thrown from a function declared as `throw()` in **`/std:c++14`** mode, the result is undefined behavior. No specific function is invoked. This is a divergence from the C++14 standard, which required the compiler to invoke [`std::unexpected`](../standard-library/exception-functions.md#unexpected).
**Visual Studio 2017 version 15.5 and later**: In **`/std:c++17`** mode , **`noexcept`**, `noexcept(true)`, and `throw()` are all equivalent. In **`/std:c++17`** mode, `throw()` is an alias for `noexcept(true)`. In **`/std:c++17`** mode and later, when an exception is thrown from a function declared with any of these specifications, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked as required by the C++17 standard.| +|**`noexcept`**
`noexcept(true)`
`throw()`|The function does not throw an exception. In **`/std:c++14`** mode (which is the default), **`noexcept`** and `noexcept(true)` are equivalent. When an exception is thrown from a function that is declared **`noexcept`** or `noexcept(true)`, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked. When an exception is thrown from a function declared as `throw()` in **`/std:c++14`** mode, the result is undefined behavior. No specific function is invoked. This is a divergence from the C++14 standard, which required the compiler to invoke [`std::unexpected`](../standard-library/exception-functions.md#unexpected).
**Visual Studio 2017 version 15.5 and later**: In **`/std:c++17`** mode, **`noexcept`**, `noexcept(true)`, and `throw()` are all equivalent. In **`/std:c++17`** mode, `throw()` is an alias for `noexcept(true)`. In **`/std:c++17`** mode and later, when an exception is thrown from a function declared with any of these specifications, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked as required by the C++17 standard.| |`noexcept(false)`
`throw(...)`
No specification|The function can throw an exception of any type.| |`throw(type)`| (**C++14 and earlier**) The function can throw an exception of type `type`. The compiler accepts the syntax, but interprets it as `noexcept(false)`. In **`/std:c++17`** mode and later, the compiler issues warning C5040.| diff --git a/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md b/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md index 3cb9e891b9..3219d0d5d8 100644 --- a/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md +++ b/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md @@ -20,7 +20,7 @@ In the C++ exception mechanism, control moves from the throw statement to the fi ## Stack unwinding example -The following example demonstrates how the stack is unwound when an exception is thrown. Execution on the thread jumps from the throw statement in `C` to the catch statement in `main`, and unwinds each function along the way. Notice the order in which the `Dummy` objects are created and then destroyed as they go out of scope. Also notice that no function completes except `main`, which contains the catch statement. Function `A` never returns from its call to `B()`, and `B` never returns from its call to `C()`. If you uncomment the definition of the `Dummy` pointer and the corresponding delete statement, and then run the program, notice that the pointer is never deleted. This shows what can happen when functions do not provide an exception guarantee. For more information, see How to: Design for Exceptions. If you comment out the catch statement, you can observe what happens when a program terminates because of an unhandled exception. +The following example demonstrates how the stack is unwound when an exception is thrown. Execution on the thread jumps from the throw statement in `C` to the catch statement in `main`, and unwinds each function along the way. Notice the order in which the `Dummy` objects are created and then destroyed as they go out of scope. Also notice that no function completes except `main`, which contains the catch statement. Function `A` never returns from its call to `B()`, and `B` never returns from its call to `C()`. If you uncomment the definition of the `Dummy` pointer and the corresponding delete statement, and then run the program, notice that the pointer is never deleted. This shows what can happen when functions do not provide an exception guarantee. For more information, see [How to: Design for Exceptions](how-to-design-for-exception-safety.md). If you comment out the catch statement, you can observe what happens when a program terminates because of an unhandled exception. ```cpp #include diff --git a/docs/cpp/explicit-instantiation.md b/docs/cpp/explicit-instantiation.md index 578575d787..02a1e53d68 100644 --- a/docs/cpp/explicit-instantiation.md +++ b/docs/cpp/explicit-instantiation.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: Explicit Instantiation" -title: "Explicit Instantiation" -ms.date: "11/04/2016" +description: "Learn more about: Explicit instantiation" +title: "Explicit instantiation" +ms.date: 09/27/2022 helpviewer_keywords: ["templates, instantiation", "explicit instantiation", "instantiation, explicit"] ms.assetid: 8b0d4e32-45a6-49d5-8041-1ebdd674410e --- -# Explicit Instantiation +# Explicit instantiation -You can use explicit instantiation to create an instantiation of a templated class or function without actually using it in your code. Because this is useful when you are creating library (.lib) files that use templates for distribution, uninstantiated template definitions are not put into object (.obj) files. +You can use explicit instantiation to create an instantiation of a templated class or function without actually using it in your code. Because it's useful when you're creating library (*`.lib`*) files that use templates for distribution, uninstantiated template definitions aren't put into object (*`.obj`*) files. + +## Examples This code explicitly instantiates `MyStack` for **`int`** variables and six items: @@ -23,7 +25,7 @@ The next line explicitly instantiates only the constructor member function: template MyStack::MyStack( void ); ``` -You can explicitly instantiate function templates by using a specific type argument to re-declare them, as shown in the example in [Function Template Instantiation](../cpp/function-template-instantiation.md). +You can explicitly instantiate function templates by using a specific type argument to redeclare them, as shown in the example in [Function template instantiation](../cpp/function-template-instantiation.md). You can use the **`extern`** keyword to prevent the automatic instantiation of members. For example: @@ -37,11 +39,11 @@ Similarly, you can mark specific members as being external and not instantiated: extern template MyStack::MyStack( void ); ``` -You can use the **`extern`** keyword to keep the compiler from generating the same instantiation code in more than one object module. You must instantiate the template function by using the specified explicit template parameters in at least one linked module if the function is called, or you will get a linker error when the program is built. +You can use the **`extern`** keyword to keep the compiler from generating the same instantiation code in more than one object module. You must instantiate the function template by using the specified explicit template parameters in at least one linked module if the function is called. Otherwise, you'll get a linker error when the program is built. > [!NOTE] > The **`extern`** keyword in the specialization only applies to member functions defined outside of the body of the class. Functions defined inside the class declaration are considered inline functions and are always instantiated. ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/explicit-type-conversion-operator-parens.md b/docs/cpp/explicit-type-conversion-operator-parens.md index 184ba177cc..e0a684cebb 100644 --- a/docs/cpp/explicit-type-conversion-operator-parens.md +++ b/docs/cpp/explicit-type-conversion-operator-parens.md @@ -5,7 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["explicit data type conversion operator", "conversions [C++], explicit", "operators [C++], explicit type conversion", "data type conversion [C++], explicit", "type conversion [C++], explicit conversions"] ms.assetid: 54272006-5ffb-45ed-8283-27152ab97529 --- -# Explicit Type Conversion Operator: () +# Explicit Type Conversion Operator: `()` C++ allows explicit type conversion using syntax similar to the function-call syntax. @@ -117,5 +117,5 @@ Type definition within casts is illegal. ## See also -[Postfix Expressions](../cpp/postfix-expressions.md)
+[Postfix Expressions](../cpp/postfix-expressions.md)\ [C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md) diff --git a/docs/cpp/explicitly-defaulted-and-deleted-functions.md b/docs/cpp/explicitly-defaulted-and-deleted-functions.md index 25f53cb673..13daddcfc3 100644 --- a/docs/cpp/explicitly-defaulted-and-deleted-functions.md +++ b/docs/cpp/explicitly-defaulted-and-deleted-functions.md @@ -2,15 +2,14 @@ description: "Learn more about: Explicitly Defaulted and Deleted Functions" title: "Explicitly Defaulted and Deleted Functions" ms.date: "11/04/2016" -ms.assetid: 5a588478-fda2-4b3f-a279-db3967f5e07e --- # Explicitly Defaulted and Deleted Functions -In C++11, defaulted and deleted functions give you explicit control over whether the special member functions are automatically generated. Deleted functions also give you simple language to prevent problematic type promotions from occurring in arguments to functions of all types—special member functions, as well as normal member functions and non-member functions—which would otherwise cause an unwanted function call. +In C++11, defaulted and deleted functions give you explicit control over whether the special member functions are automatically generated. Deleted functions also give you simple language to prevent problematic type promotions from occurring in arguments to functions of all types—special member functions, and normal member functions and nonmember functions—which would otherwise cause an unwanted function call. ## Benefits of explicitly defaulted and deleted functions -In C++, the compiler automatically generates the default constructor, copy constructor, copy-assignment operator, and destructor for a type if it does not declare its own. These functions are known as the *special member functions*, and they are what make simple user-defined types in C++ behave like structures do in C. That is, you can create, copy, and destroy them without any additional coding effort. C++11 brings move semantics to the language and adds the move constructor and move-assignment operator to the list of special member functions that the compiler can automatically generate. +In C++, the compiler automatically generates the default constructor, copy constructor, copy-assignment operator, and destructor for a type if it doesn't declare its own. These functions are known as the *special member functions*, and they're what make simple user-defined types in C++ behave like structures do in C. That is, you can create, copy, and destroy them without extra coding effort. C++11 brings move semantics to the language and adds the move constructor and move-assignment operator to the list of special member functions that the compiler can automatically generate. This is convenient for simple types, but complex types often define one or more of the special member functions themselves, and this can prevent other special member functions from being automatically generated. In practice: @@ -36,11 +35,11 @@ This is convenient for simple types, but complex types often define one or more > - If a copy constructor or destructor is explicitly declared, then automatic generation of the copy-assignment operator is deprecated. > - If a copy-assignment operator or destructor is explicitly declared, then automatic generation of the copy constructor is deprecated. > -> In both cases, Visual Studio continues to automatically generate the necessary functions implicitly, and does not emit a warning. +> In both cases, Visual Studio continues to automatically generate the necessary functions implicitly, and doesn't emit a warning by default. Since Visual Studio 2022 version 17.7, [C5267](../error-messages/compiler-warnings/c5267.md) can be enabled to emit a warning. -The consequences of these rules can also leak into object hierarchies. For example, if for any reason a base class fails to have a default constructor that's callable from a deriving class—that is, a **`public`** or **`protected`** constructor that takes no parameters—then a class that derives from it cannot automatically generate its own default constructor. +The consequences of these rules can also leak into object hierarchies. For example, if for any reason a base class fails to have a default constructor that's callable from a deriving class—that is, a **`public`** or **`protected`** constructor that takes no parameters—then a class that derives from it can't automatically generate its own default constructor. -These rules can complicate the implementation of what should be straight-forward, user-defined types and common C++ idioms—for example, making a user-defined type non-copyable by declaring the copy constructor and copy-assignment operator privately and not defining them. +These rules can complicate the implementation of what should be straight-forward, user-defined types and common C++ idioms—for example, making a user-defined type noncopyable by declaring the copy constructor and copy-assignment operator privately and not defining them. ```cpp struct noncopyable @@ -53,17 +52,17 @@ private: }; ``` -Before C++11, this code snippet was the idiomatic form of non-copyable types. However, it has several problems: +Before C++11, this code snippet was the idiomatic form of noncopyable types. However, it has several problems: - The copy constructor has to be declared privately to hide it, but because it's declared at all, automatic generation of the default constructor is prevented. You have to explicitly define the default constructor if you want one, even if it does nothing. -- Even if the explicitly-defined default constructor does nothing, it's considered non-trivial by the compiler. It's less efficient than an automatically generated default constructor and prevents `noncopyable` from being a true POD type. +- Even if the explicitly defined default constructor does nothing, the compiler considers it to be nontrivial. It's less efficient than an automatically generated default constructor and prevents `noncopyable` from being a true POD type. -- Even though the copy constructor and copy-assignment operator are hidden from outside code, the member functions and friends of `noncopyable` can still see and call them. If they are declared but not defined, calling them causes a linker error. +- Even though the copy constructor and copy-assignment operator are hidden from outside code, the member functions and friends of `noncopyable` can still see and call them. If they're declared but not defined, calling them causes a linker error. -- Although this is a commonly accepted idiom, the intent is not clear unless you understand all of the rules for automatic generation of the special member functions. +- Although this is a commonly accepted idiom, the intent isn't clear unless you understand all of the rules for automatic generation of the special member functions. -In C++11, the non-copyable idiom can be implemented in a way that is more straightforward. +In C++11, the noncopyable idiom can be implemented in a way that is more straightforward. ```cpp struct noncopyable @@ -78,17 +77,17 @@ Notice how the problems with the pre-C++11 idiom are resolved: - Generation of the default constructor is still prevented by declaring the copy constructor, but you can bring it back by explicitly defaulting it. -- Explicitly defaulted special member functions are still considered trivial, so there is no performance penalty, and `noncopyable` is not prevented from being a true POD type. +- Explicitly defaulted special member functions are still considered trivial, so there's no performance penalty, and `noncopyable` isn't prevented from being a true POD type. -- The copy constructor and copy-assignment operator are public but deleted. It is a compile-time error to define or call a deleted function. +- The copy constructor and copy-assignment operator are public but deleted. It's a compile-time error to define or call a deleted function. - The intent is clear to anyone who understands `=default` and `=delete`. You don't have to understand the rules for automatic generation of special member functions. -Similar idioms exist for making user-defined types that are non-movable, that can only be dynamically allocated, or that cannot be dynamically allocated. Each of these idioms have pre-C++11 implementations that suffer similar problems, and that are similarly resolved in C++11 by implementing them in terms of defaulted and deleted special member functions. +Similar idioms exist for making user-defined types that are nonmovable, that can only be dynamically allocated, or that can't be dynamically allocated. Each of these idioms have pre-C++11 implementations that suffer similar problems, and that are similarly resolved in C++11 by implementing them in terms of defaulted and deleted special member functions. ## Explicitly defaulted functions -You can default any of the special member functions—to explicitly state that the special member function uses the default implementation, to define the special member function with a non-public access qualifier, or to reinstate a special member function whose automatic generation was prevented by other circumstances. +You can default any of the special member functions—to explicitly state that the special member function uses the default implementation, to define the special member function with a nonpublic access qualifier, or to reinstate a special member function whose automatic generation was prevented by other circumstances. You default a special member function by declaring it as in this example: @@ -109,7 +108,7 @@ Because of the performance benefits of trivial special member functions, we reco ## Deleted functions -You can delete special member functions as well as normal member functions and non-member functions to prevent them from being defined or called. Deleting of special member functions provides a cleaner way of preventing the compiler from generating special member functions that you don't want. The function must be deleted as it is declared; it cannot be deleted afterwards in the way that a function can be declared and then later defaulted. +You can delete special member functions and normal member functions and nonmember functions to prevent them from being defined or called. Deleting of special member functions provides a cleaner way of preventing the compiler from generating special member functions that you don't want. The function must be deleted as it's declared; it can't be deleted afterwards in the way that a function can be declared and then later defaulted. ```cpp struct widget @@ -119,7 +118,7 @@ struct widget }; ``` -Deleting of normal member function or non-member functions prevents problematic type promotions from causing an unintended function to be called. This works because deleted functions still participate in overload resolution and provide a better match than the function that could be called after the types are promoted. The function call resolves to the more-specific—but deleted—function and causes a compiler error. +Deleting of normal member function or nonmember functions prevents problematic type promotions from causing an unintended function to be called. This works because deleted functions still participate in overload resolution and provide a better match than the function that could be called after the types are promoted. The function call resolves to the more-specific—but deleted—function and causes a compiler error. ```cpp // deleted overload prevents call through type promotion of float to double from succeeding. @@ -127,7 +126,7 @@ void call_with_true_double_only(float) =delete; void call_with_true_double_only(double param) { return; } ``` -Notice in the preceding sample that calling `call_with_true_double_only` by using a **`float`** argument would cause a compiler error, but calling `call_with_true_double_only` by using an **`int`** argument would not; in the **`int`** case, the argument will be promoted from **`int`** to **`double`** and successfully call the **`double`** version of the function, even though that might not be what's intended. To ensure that any call to this function by using a non-double argument causes a compiler error, you can declare a template version of the function that's deleted. +Notice in the preceding sample that calling `call_with_true_double_only` by using a **`float`** argument would cause a compiler error, but calling `call_with_true_double_only` by using an **`int`** argument wouldn't; in the **`int`** case, the argument will be promoted from **`int`** to **`double`** and successfully call the **`double`** version of the function, even though that might not be what you intend. To ensure that any call to this function by using a non-double argument causes a compiler error, you can declare a template version of the deleted function. ```cpp template < typename T > diff --git a/docs/cpp/expressions-with-binary-operators.md b/docs/cpp/expressions-with-binary-operators.md index 8c55d441d8..e43b896549 100644 --- a/docs/cpp/expressions-with-binary-operators.md +++ b/docs/cpp/expressions-with-binary-operators.md @@ -49,13 +49,13 @@ Binary operators act on two operands in an expression. The binary operators are: - [Bitwise exclusive OR (^)](../cpp/bitwise-exclusive-or-operator-hat.md) - - [Bitwise inclusive OR (|)](../cpp/bitwise-inclusive-or-operator-pipe.md) + - [Bitwise inclusive OR (\|)](../cpp/bitwise-inclusive-or-operator-pipe.md) - Logical operators - [Logical AND (&&)](../cpp/logical-and-operator-amp-amp.md) - - [Logical OR (||)](../cpp/logical-or-operator-pipe-pipe.md) + - [Logical OR (\|\|)](../cpp/logical-or-operator-pipe-pipe.md) - [Assignment operators](../cpp/assignment-operators.md) @@ -79,7 +79,7 @@ Binary operators act on two operands in an expression. The binary operators are: - Bitwise exclusive OR assignment (^=) - - Bitwise inclusive OR assignment (|=) + - Bitwise inclusive OR assignment (\|=) - [Comma Operator](../cpp/comma-operator.md) (,) diff --git a/docs/cpp/fastcall.md b/docs/cpp/fastcall.md index bae76403db..772adbead2 100644 --- a/docs/cpp/fastcall.md +++ b/docs/cpp/fastcall.md @@ -1,10 +1,9 @@ --- description: "Learn more about: __fastcall" title: "__fastcall" -ms.date: "12/17/2018" +ms.date: 09/14/2023 f1_keywords: ["__fastcall_cpp", "__fastcall", "_fastcall"] helpviewer_keywords: ["__fastcall keyword [C++]"] -ms.assetid: bb5b9c8a-dfad-450c-9119-0ac2bc59544f --- # __fastcall @@ -14,10 +13,12 @@ The **`__fastcall`** calling convention specifies that arguments to functions ar |Element|Implementation| |-------------|--------------------| -|Argument-passing order|The first two DWORD or smaller arguments that are found in the argument list from left to right are passed in ECX and EDX registers; all other arguments are passed on the stack from right to left.| +|Argument-passing order|The first two `DWORD` or smaller arguments that are found in the argument list from left to right are passed in ECX and EDX registers; all other arguments are passed on the stack from right to left.| |Stack-maintenance responsibility|Called function pops the arguments from the stack.| |Name-decoration convention|At sign (\@) is prefixed to names; an at sign followed by the number of bytes (in decimal) in the parameter list is suffixed to names.| |Case-translation convention|No case translation performed.| +|Classes, structs, and unions|Treated as "multibyte" types (regardless of size) and passed on the stack. | +|Enums and enum classes | Passed by register if their underlying type is passed by register. For example, if the underlying type is `int` or `unsigned int` of size 8, 16, or 32 bits. | > [!NOTE] > Future compiler versions may use different registers to store parameters. @@ -26,7 +27,7 @@ Using the [/Gr](../build/reference/gd-gr-gv-gz-calling-convention.md) compiler o The **`__fastcall`** keyword is accepted and ignored by the compilers that target ARM and x64 architectures; on an x64 chip, by convention, the first four arguments are passed in registers when possible, and additional arguments are passed on the stack. For more information, see [x64 Calling Convention](../build/x64-calling-convention.md). On an ARM chip, up to four integer arguments and eight floating-point arguments may be passed in registers, and additional arguments are passed on the stack. -For non-static class functions, if the function is defined out-of-line, the calling convention modifier does not have to be specified on the out-of-line definition. That is, for class non-static member methods, the calling convention specified during declaration is assumed at the point of definition. Given this class definition: +For nonstatic class functions, if the function is defined out-of-line, the calling convention modifier doesn't have to be specified on the out-of-line definition. That is, for class non-static member methods, the calling convention specified during declaration is assumed at the point of definition. Given this class definition: ```cpp struct CMyClass { @@ -46,7 +47,7 @@ is equivalent to this: void __fastcall CMyClass::mymethod() { return; } ``` -For compatibility with previous versions, **_fastcall** is a synonym for **`__fastcall`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +For compatibility with previous versions, **`_fastcall`** is a synonym for **`__fastcall`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. ## Example diff --git a/docs/cpp/for-statement-cpp.md b/docs/cpp/for-statement-cpp.md index c2f73186fe..b331d9227e 100644 --- a/docs/cpp/for-statement-cpp.md +++ b/docs/cpp/for-statement-cpp.md @@ -1,14 +1,14 @@ --- title: "for statement (C++)" description: "Reference to the Standard C++ for statement in Microsoft Visual Studio C++." -f1_keywords: ["for_cpp"] -ms.date: 07/31/2020 +f1_keywords: ["for_CPP"] +ms.date: 04/15/2022 helpviewer_keywords: ["for keyword [C++]"] ms.assetid: 6c7d01b3-c4c1-4c6a-aa58-e2d198f33d4a --- # `for` statement (C++) -Executes a statement repeatedly until the condition becomes false. For information on the range-based **`for`** statement, see [Range-based `for` statement (C++)](../cpp/range-based-for-statement-cpp.md). +Executes a statement repeatedly until the condition becomes false. For information on the range-based **`for`** statement, see [Range-based `for` statement (C++)](../cpp/range-based-for-statement-cpp.md). For information on the C++/CLI **`for each`** statement, see [`for each`, `in`](../dotnet/for-each-in.md). ## Syntax @@ -68,10 +68,11 @@ int main(){ cout << "i + j = " << (i + j) << '\n'; } } - // Output: +/* Output: i + j = 15 i + j = 17 i + j = 19 +*/ ``` *`loop-expression`* can be incremented or decremented, or modified in other ways. @@ -88,7 +89,8 @@ for (int i = 10; i > 0; i--) { for (int i = 10; i < 20; i = i+2) { cout << i << ' '; } - // Output: 10 12 14 16 18 +} +// Output: 10 12 14 16 18 ``` A **`for`** loop terminates when a [`break`](../cpp/break-statement-cpp.md), [return](../cpp/return-statement-cpp.md), or [`goto`](../cpp/goto-statement-cpp.md) (to a labeled statement outside the **`for`** loop) within *`statement`* is executed. A [`continue`](../cpp/continue-statement-cpp.md) statement in a **`for`** loop terminates only the current iteration. @@ -121,9 +123,9 @@ for (int i = 0 ; i < 5 ; i++) { // i is now out of scope under /Za or /Zc:forScope ``` -By default, under [/Ze](../build/reference/za-ze-disable-language-extensions.md), a variable declared in a **`for`** loop remains in scope until the **`for`** loop's enclosing scope ends. +By default, under [`/Ze`](../build/reference/za-ze-disable-language-extensions.md), a variable declared in a **`for`** loop remains in scope until the **`for`** loop's enclosing scope ends. -[/Zc:forScope](../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) enables standard behavior of variables declared in for loops without needing to specify `/Za`. +[`/Zc:forScope`](../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) enables standard behavior of variables declared in for loops without needing to specify `/Za`. It's also possible to use the scoping differences of the **`for`** loop to redeclare variables under `/Ze` as follows: @@ -141,8 +143,8 @@ This behavior more closely mimics the standard behavior of a variable declared i ## See also -[Iteration statements](../cpp/iteration-statements-cpp.md)
-[Keywords](../cpp/keywords-cpp.md)
-[while statement (C++)](../cpp/while-statement-cpp.md)
-[do-while statement (C++)](../cpp/do-while-statement-cpp.md)
-[Range-based for statement (C++)](../cpp/range-based-for-statement-cpp.md) +[Iteration statements](../cpp/iteration-statements-cpp.md)\ +[Keywords](../cpp/keywords-cpp.md)\ +[`while` statement (C++)](../cpp/while-statement-cpp.md)\ +[`do-while` statement (C++)](../cpp/do-while-statement-cpp.md)\ +[Range-based `for` statement (C++)](../cpp/range-based-for-statement-cpp.md) diff --git a/docs/cpp/friend-cpp.md b/docs/cpp/friend-cpp.md index cb4bd3196a..4e4aa5f1d0 100644 --- a/docs/cpp/friend-cpp.md +++ b/docs/cpp/friend-cpp.md @@ -1,29 +1,30 @@ --- description: "Learn more about: friend (C++)" title: "friend (C++)" -ms.date: "07/15/2019" +ms.date: 06/30/2022 f1_keywords: ["friend_cpp"] helpviewer_keywords: ["member access, from friend functions", "friend classes [C++]", "friend keyword [C++]"] -ms.assetid: 8fe9ee55-d56f-40cd-9075-d9fb1375aff4 --- -# friend (C++) +# `friend` (C++) -In some circumstances, it is more convenient to grant member-level access to functions that are not members of a class or to all members in a separate class. Only the class implementer can declare who its friends are. A function or class cannot declare itself as a friend of any class. In a class definition, use the **`friend`** keyword and the name of a non-member function or other class to grant it access to the private and protected members of your class. In a template definition, a type parameter can be declared as a friend. +In some circumstances, it's useful for a class to grant member-level access to functions that aren't members of the class, or to all members in a separate class. These free functions and classes are known as *friends*, marked by the **`friend`** keyword. Only the class implementer can declare who its friends are. A function or class can't declare itself as a friend of any class. In a class definition, use the **`friend`** keyword and the name of a nonmember function or other class to grant it access to the private and protected members of your class. In a template definition, a type parameter can be declared as a **`friend`**. ## Syntax -``` -class friend F -friend F; -``` +*`friend-declaration`*:\ + **`friend`** *`function-declaration`*\ + **`friend`** *`function-definition`*\ + **`friend`** *`elaborated-type-specifier`* **`;`**;\ + **`friend`** *`simple-type-specifier`* **`;`**\ + **`friend`** *`typename-specifier`* **`;`** -## Friend declarations +## `friend` declarations -If you declare a friend function that was not previously declared, that function is exported to the enclosing nonclass scope. +If you declare a **`friend`** function that wasn't previously declared, that function is exported to the enclosing nonclass scope. -Functions declared in a friend declaration are treated as if they had been declared using the **`extern`** keyword. For more information, see [extern](extern-cpp.md). +Functions declared in a **`friend`** declaration are treated as if they had been declared using the **`extern`** keyword. For more information, see [`extern`](extern-cpp.md). -Although functions with global scope can be declared as friends prior to their prototypes, member functions cannot be declared as friends before the appearance of their complete class declaration. The following code shows why this fails: +Although functions with global scope can be declared as **`friend`** functions prior to their prototypes, member functions can't be declared as **`friend`** functions before the appearance of their complete class declaration. The following code shows how such a declaration fails: ```cpp class ForwardDeclared; // Class name is known. @@ -33,18 +34,18 @@ class HasFriends }; ``` -The preceding example enters the class name `ForwardDeclared` into scope, but the complete declaration — specifically, the portion that declares the function `IsAFriend` — is not known. Therefore, the **`friend`** declaration in class `HasFriends` generates an error. +The preceding example enters the class name `ForwardDeclared` into scope, but the complete declaration (specifically, the portion that declares the function `IsAFriend`) isn't known. the **`friend`** declaration in class `HasFriends` generates an error. -Starting in C++11, there are two forms of friend declarations for a class: +In C++11, there are two forms of friend declarations for a class: ```cpp friend class F; friend F; ``` -The first form introduces a new class F if no existing class by that name was found in the innermost namespace. **C++11**: The second form does not introduce a new class; it can be used when the class has already been declared, and it must be used when declaring a template type parameter or a typedef as a friend. +The first form introduces a new class F if no existing class by that name was found in the innermost namespace. **C++11**: The second form doesn't introduce a new class; it can be used when the class has already been declared, and it must be used when declaring a template type parameter or a `typedef` as a `friend`. -Use `friend class F` when the referenced type has not yet been declared: +Use `friend class F` when the referenced type hasn't been declared yet: ```cpp namespace NS @@ -56,6 +57,8 @@ namespace NS } ``` +An error occurs if you use `friend` with a class type that hasn't been declared: + ```cpp namespace NS { @@ -110,7 +113,7 @@ To declare two classes that are friends of one another, the entire second class ## friend functions -A **`friend`** function is a function that is not a member of a class but has access to the class's private and protected members. Friend functions are not considered class members; they are normal external functions that are given special access privileges. Friends are not in the class's scope, and they are not called using the member-selection operators (**.** and -**>**) unless they are members of another class. A **`friend`** function is declared by the class that is granting access. The **`friend`** declaration can be placed anywhere in the class declaration. It is not affected by the access control keywords. +A **`friend`** function is a function that isn't a member of a class but has access to the class's private and protected members. Friend functions aren't considered class members; they're normal external functions that are given special access privileges. Friends aren't in the class's scope, and they aren't called using the member-selection operators (**.** and -**>**) unless they're members of another class. A **`friend`** function is declared by the class that is granting access. The **`friend`** declaration can be placed anywhere in the class declaration. It isn't affected by the access control keywords. The following example shows a `Point` class and a friend function, `ChangePrivate`. The **`friend`** function has access to the private data member of the `Point` object it receives as a parameter. @@ -174,15 +177,15 @@ int A::Func1( B& b ) { return b._b; } // OK int A::Func2( B& b ) { return b._b; } // C2248 ``` -In the preceding example, only the function `A::Func1( B& )` is granted friend access to class `B`. Therefore, access to the private member `_b` is correct in `Func1` of class `A` but not in `Func2`. +In the preceding example, only the function `A::Func1( B& )` is granted `friend` access to class `B`. Therefore, access to the private member `_b` is correct in `Func1` of class `A` but not in `Func2`. -A **`friend`** class is a class all of whose member functions are friend functions of a class, that is, whose member functions have access to the other class's private and protected members. Suppose the **`friend`** declaration in class `B` had been: +A **`friend`** class is a class all of whose member functions are `friend` functions of a class, that is, whose member functions have access to the other class's private and protected members. Suppose the **`friend`** declaration in class `B` had been: ```cpp friend class A; ``` -In that case, all member functions in class `A` would have been granted friend access to class `B`. The following code is an example of a friend class: +In that case, all member functions in class `A` would have been granted `friend` access to class `B`. The following code is an example of a `friend` class: ```cpp // classes_as_friends2.cpp @@ -213,20 +216,21 @@ int main() { } ``` -Friendship is not mutual unless explicitly specified as such. In the above example, member functions of `YourClass` cannot access the private members of `YourOtherClass`. +Friendship isn't mutual unless explicitly specified as such. In the above example, member functions of `YourClass` can't access the private members of `YourOtherClass`. -A managed type (in C++/CLI) cannot have any friend functions, friend classes, or friend interfaces. +A managed type (in C++/CLI) can't have any `friend` functions, `friend` classes, or `friend` interfaces. -Friendship is not inherited, meaning that classes derived from `YourOtherClass` cannot access `YourClass`'s private members. Friendship is not transitive, so classes that are friends of `YourOtherClass` cannot access `YourClass`'s private members. +Friendship isn't inherited, meaning that classes derived from `YourOtherClass` can't access `YourClass`'s private members. Friendship isn't transitive, so classes that are friends of `YourOtherClass` can't access `YourClass`'s private members. The following figure shows four class declarations: `Base`, `Derived`, `aFriend`, and `anotherFriend`. Only class `aFriend` has direct access to the private members of `Base` (and to any members `Base` might have inherited). -![Diagram showing the derivation implications of a friend relationship.](../cpp/media/vc38v41.gif "Implications of friend relationship")
-Implications of friend relationship +:::image type="complex" source="../cpp/media/vc38v41.gif" alt-text="A diagram that shows the derivation implications of a friend relationship."::: +The diagram shows that class anotherFriend doesn't have a friend relationship with class base which friends class aFriend. Class aFriend is friended by class Base, but it doesn't have a friend relationship with class Derived even though class Derived inherits from Base. This demonstrates that inheritance doesn't imply that the derived class has the same friends as the base class. +:::image-end::: -## Inline friend definitions +## Inline `friend` definitions -Friend functions can be defined (given a function body) inside class declarations. These functions are inline functions, and like member inline functions they behave as though they were defined immediately after all class members have been seen but before the class scope is closed (the end of the class declaration). Friend functions that are defined inside class declarations are in the scope of the enclosing class. +Friend functions can be defined (given a function body) inside class declarations. These functions are inline functions. Like member inline functions, they behave as though they were defined immediately after all class members have been seen, but before the class scope is closed (at the end of the class declaration). Friend functions that are defined inside class declarations are in the scope of the enclosing class. ## See also diff --git a/docs/cpp/function-call-operator-parens.md b/docs/cpp/function-call-operator-parens.md index b065fdd6b0..3766abb0f4 100644 --- a/docs/cpp/function-call-operator-parens.md +++ b/docs/cpp/function-call-operator-parens.md @@ -6,7 +6,7 @@ helpviewer_keywords: ["( ) function call operator", "function calls, C++ functio ms.assetid: 50c92e59-a4bf-415a-a6ab-d66c679ee80a no-loc: [ opt ] --- -# Function Call Operator: () +# Function Call Operator: `()` A function call is a kind of *`postfix-expression`*, formed by an expression that evaluates to a function or callable object followed by the function-call operator, **`()`**. An object can declare an `operator ()` function, which provides function call semantics for the object. @@ -17,7 +17,7 @@ A function call is a kind of *`postfix-expression`*, formed by an expression tha ## Remarks -The arguments to the function-call operator come from an *`argument-expression-list`*, a comma-separated list of expressions. The values of these expressions are passed to the function as arguments. The *argument-expression-list* can be empty. Before C++ 17, the order of evaluation of the function expression and the argument expressions is unspecified and may occur in any order. In C++17 and later, the function expression is evaluated before any argument expressions or default arguments. The argument expressions are evaluated in an indeterminate sequence. +The arguments to the function-call operator come from an *`argument-expression-list`*, a comma-separated list of expressions. The values of these expressions are passed to the function as arguments. The *argument-expression-list* can be empty. Before C++17, the order of evaluation of the function expression and the argument expressions is unspecified and may occur in any order. In C++17 and later, the function expression is evaluated before any argument expressions or default arguments. The argument expressions are evaluated in an indeterminate sequence. The *`postfix-expression`* evaluates to the function to call. It can take any of several forms: @@ -172,6 +172,6 @@ Functions can be called recursively. For more information about function declara ## See also -[Postfix expressions](../cpp/postfix-expressions.md)
-[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Postfix expressions](../cpp/postfix-expressions.md)\ +[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Function call](../c-language/function-call-c.md) diff --git a/docs/cpp/function-overloading.md b/docs/cpp/function-overloading.md index aa4ea32934..8f8c24a61a 100644 --- a/docs/cpp/function-overloading.md +++ b/docs/cpp/function-overloading.md @@ -1,34 +1,33 @@ --- -description: "Learn more about: Function Overloading" title: "Function Overloading" -ms.date: "03/27/2019" +description: "Learn more about: Function Overloading" +ms.date: 02/01/2023 helpviewer_keywords: ["function overloading [C++], about function overloading", "function overloading", "declaring functions [C++], overloading"] -ms.assetid: 3c9884cb-1d5e-42e8-9a49-6f46141f929e --- # Function Overloading -C++ allows specification of more than one function of the same name in the same scope. These functions are called *overloaded* functions. Overloaded functions enable you to supply different semantics for a function, depending on the types and number of arguments. +C++ lets you specify more than one function of the same name in the same scope. These functions are called *overloaded* functions, or *overloads*. Overloaded functions enable you to supply different semantics for a function, depending on the types and number of its arguments. -For example, a `print` function that takes a `std::string` argument might perform very different tasks than one that takes an argument of type **`double`**. Overloading saves you from having to use names such as `print_string` or `print_double`. At compile time, the compiler chooses which overload to use based on the type of arguments passed in by the caller. If you call `print(42.0)`, then the `void print(double d)` function will be invoked. If you call `print("hello world")`, then the `void print(std::string)` overload will be invoked. +For example, consider a `print` function that takes a `std::string` argument. This function might perform very different tasks than a function that takes an argument of type `double`. Overloading keeps you from having to use names such as `print_string` or `print_double`. At compile time, the compiler chooses which overload to use based on the types and number of arguments passed in by the caller. If you call `print(42.0)`, then the `void print(double d)` function is invoked. If you call `print("hello world")`, then the `void print(std::string)` overload is invoked. -You can overload both member functions and non-member functions. The following table shows what parts of a function declaration C++ uses to differentiate between groups of functions with the same name in the same scope. +You can overload both member functions and free functions. The following table shows which parts of a function declaration C++ uses to differentiate between groups of functions with the same name in the same scope. ### Overloading Considerations -|Function Declaration Element|Used for Overloading?| -|----------------------------------|---------------------------| -|Function return type|No| -|Number of arguments|Yes| -|Type of arguments|Yes| -|Presence or absence of ellipsis|Yes| -|Use of **`typedef`** names|No| -|Unspecified array bounds|No| -|**`const`** or **`volatile`**|Yes, when applied to entire function| -|[Ref-qualifiers](#ref-qualifiers)|Yes| +| Function declaration element | Used for overloading? | +|--|--| +| Function return type | No | +| Number of arguments | Yes | +| Type of arguments | Yes | +| Presence or absence of ellipsis | Yes | +| Use of **`typedef`** names | No | +| Unspecified array bounds | No | +| **`const`** or **`volatile`** | Yes, when applied to entire function | +| Reference qualifiers (**`&`** and **`&&`**) | Yes | ## Example -The following example illustrates how overloading can be used. +The following example illustrates how you can use function overloads: ```cpp // function_overloading.cpp @@ -103,15 +102,15 @@ int print(double dvalue, int prec) } ``` -The preceding code shows overloading of the `print` function in file scope. +The preceding code shows overloads of the `print` function in file scope. The default argument isn't considered part of the function type. Therefore, it's not used in selecting overloaded functions. Two functions that differ only in their default arguments are considered multiple definitions rather than overloaded functions. Default arguments can't be supplied for overloaded operators. -## Argument Matching +## Argument matching -Overloaded functions are selected for the best match of function declarations in the current scope to the arguments supplied in the function call. If a suitable function is found, that function is called. "Suitable" in this context means either: +The compiler selects which overloaded function to invoke based on the best match among the function declarations in the current scope to the arguments supplied in the function call. If a suitable function is found, that function is called. "Suitable" in this context means either: - An exact match was found. @@ -121,13 +120,13 @@ Overloaded functions are selected for the best match of function declarations in - A standard conversion to the desired argument type exists. -- A user-defined conversion (either conversion operator or constructor) to the desired argument type exists. +- A user-defined conversion (either a conversion operator or a constructor) to the desired argument type exists. - Arguments represented by an ellipsis were found. The compiler creates a set of candidate functions for each argument. Candidate functions are functions in which the actual argument in that position can be converted to the type of the formal argument. -A set of "best matching functions" is built for each argument, and the selected function is the intersection of all the sets. If the intersection contains more than one function, the overloading is ambiguous and generates an error. The function that is eventually selected is always a better match than every other function in the group for at least one argument. If there's no clear winner, the function call generates an error. +A set of "best matching functions" is built for each argument, and the selected function is the intersection of all the sets. If the intersection contains more than one function, the overloading is ambiguous and generates an error. The function that's eventually selected is always a better match than every other function in the group for at least one argument. If there's no clear winner, the function call generates a compiler error. Consider the following declarations (the functions are marked `Variant 1`, `Variant 2`, and `Variant 3`, for identification in the following discussion): @@ -147,12 +146,12 @@ F1 = Add( F2, 23 ); The preceding statement builds two sets: -|Set 1: Candidate Functions That Have First Argument of Type Fraction|Set 2: Candidate Functions Whose Second Argument Can Be Converted to Type **`int`**| -|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------| -|Variant 1|Variant 1 (**`int`** can be converted to **`long`** using a standard conversion)| -|Variant 3|| +| Set 1: Candidate functions that have first argument of type `Fraction` | Set 2: Candidate functions whose second argument can be converted to type **`int`** | +|--|--| +| Variant 1 | Variant 1 (**`int`** can be converted to **`long`** using a standard conversion) | +| Variant 3 | | -Functions in Set 2 are functions for which there are implicit conversions from actual parameter type to formal parameter type, and among such functions there's a function for which the "cost" of converting the actual parameter type to its formal parameter type is the smallest. +Functions in Set 2 are functions that have implicit conversions from the actual parameter type to the formal parameter type. One of those functions has the smallest "cost" to convert the actual parameter type to its corresponding formal parameter type. The intersection of these two sets is Variant 1. An example of an ambiguous function call is: @@ -170,16 +169,16 @@ Because the intersection of these two sets is empty, the compiler generates an e For argument matching, a function with *n* default arguments is treated as *n*+1 separate functions, each with a different number of arguments. -The ellipsis (...) acts as a wildcard; it matches any actual argument. It can lead to many ambiguous sets, if you don't design your overloaded function sets with extreme care. +The ellipsis (`...`) acts as a wildcard; it matches any actual argument. It can lead to many ambiguous sets, if you don't design your overloaded function sets with extreme care. > [!NOTE] -> Ambiguity of overloaded functions can't be determined until a function call is encountered. At that point, the sets are built for each argument in the function call, and you can determine whether an unambiguous overload exists. This means that ambiguities can remain in your code until they are evoked by a particular function call. +> Ambiguity of overloaded functions can't be determined until a function call is encountered. At that point, the sets are built for each argument in the function call, and you can determine whether an unambiguous overload exists. This means that ambiguities can remain in your code until they're evoked by a particular function call. ## Argument Type Differences -Overloaded functions differentiate between argument types that take different initializers. Therefore, an argument of a given type and a reference to that type are considered the same for the purposes of overloading. They are considered the same because they take the same initializers. For example, `max( double, double )` is considered the same as `max( double &, double & )`. Declaring two such functions causes an error. +Overloaded functions differentiate between argument types that take different initializers. Therefore, an argument of a given type and a reference to that type are considered the same for the purposes of overloading. They're considered the same because they take the same initializers. For example, `max( double, double )` is considered the same as `max( double &, double & )`. Declaring two such functions causes an error. -For the same reason, function arguments of a type modified by **`const`** or **`volatile`** are not treated differently than the base type for the purposes of overloading. +For the same reason, function arguments of a type modified by **`const`** or **`volatile`** aren't treated differently than the base type for the purposes of overloading. However, the function overloading mechanism can distinguish between references that are qualified by **`const`** and **`volatile`** and references to the base type. It makes code such as the following possible: @@ -225,44 +224,44 @@ Pointers to **`const`** and **`volatile`** objects are also considered different When the compiler tries to match actual arguments against the arguments in function declarations, it can supply standard or user-defined conversions to obtain the correct type if no exact match can be found. The application of conversions is subject to these rules: -- Sequences of conversions that contain more than one user-defined conversion are not considered. +- Sequences of conversions that contain more than one user-defined conversion aren't considered. -- Sequences of conversions that can be shortened by removing intermediate conversions are not considered. +- Sequences of conversions that can be shortened by removing intermediate conversions aren't considered. -The resultant sequence of conversions, if any, is called the best matching sequence. There are several ways to convert an object of type **`int`** to type **`unsigned long`** using standard conversions (described in [Standard Conversions](../cpp/standard-conversions.md)): +The resultant sequence of conversions, if any, is called the *best matching sequence*. There are several ways to convert an object of type **`int`** to type **`unsigned long`** using standard conversions (described in [Standard conversions](../cpp/standard-conversions.md)): - Convert from **`int`** to **`long`** and then from **`long`** to **`unsigned long`**. - Convert from **`int`** to **`unsigned long`**. -The first sequence, although it achieves the desired goal, isn't the best matching sequence — a shorter sequence exists. +Although the first sequence achieves the desired goal, it isn't the best matching sequence, because a shorter sequence exists. -The following table shows a group of conversions, called trivial conversions, that have a limited effect on determining which sequence is the best matching. The instances in which trivial conversions affect choice of sequence are discussed in the list following the table. +The following table shows a group of conversions called *trivial conversions*. Trivial conversions have a limited effect on which sequence the compiler chooses as the best match. The effect of trivial conversions is described after the table. -### Trivial Conversions +### Trivial conversions -|Convert from Type|Convert to Type| -|-----------------------|---------------------| -|*type-name*|*type-name* **&**| -|*type-name* **&**|*type-name*| -|*type-name* **[ ]**|*type-name* __\*__| -|*type-name* **(** *argument-list* **)**|**(** __\*__ *type-name* **) (** *argument-list* **)**| -|*type-name*|**`const`** *type-name*| -|*type-name*|**`volatile`** *type-name*| -|*type-name* __\*__|**`const`** *type-name* __\*__| -|*type-name* __\*__|**`volatile`** *type-name* __\*__| +| Argument type | Converted type | +|--|--| +| `type-name` | `type-name&` | +| `type-name&` | `type-name` | +| `type-name[]` | `type-name*` | +| `type-name(argument-list)` | `(*type-name)(argument-list)` | +| `type-name` | `const type-name` | +| `type-name` | `volatile type-name` | +| `type-name*` | `const type-name*` | +| `type-name*` | `volatile type-name*` | The sequence in which conversions are attempted is as follows: 1. Exact match. An exact match between the types with which the function is called and the types declared in the function prototype is always the best match. Sequences of trivial conversions are classified as exact matches. However, sequences that don't make any of these conversions are considered better than sequences that convert: - - From pointer, to pointer to **`const`** (`type` \* to **`const`** `type` \*). + - From pointer, to pointer to **`const`** (`type-name*` to `const type-name*`). - - From pointer, to pointer to **`volatile`** (`type` \* to **`volatile`** `type` \*). + - From pointer, to pointer to **`volatile`** (`type-name*` to `volatile type-name*`). - - From reference, to reference to **`const`** (`type` **&** to **`const`** `type` **&**). + - From reference, to reference to **`const`** (`type-name&` to `const type-name&`). - - From reference, to reference to **`volatile`** (`type` **&** to **`volatile`** `type` **&**). + - From reference, to reference to **`volatile`** (`type-name&` to `volatile type&`). 1. Match using promotions. Any sequence not classified as an exact match that contains only integral promotions, conversions from **`float`** to **`double`**, and trivial conversions is classified as a match using promotions. Although not as good a match as any exact match, a match using promotions is better than a match using standard conversions. @@ -270,10 +269,10 @@ The sequence in which conversions are attempted is as follows: - Conversion from a pointer to a derived class, to a pointer to a direct or indirect base class is preferable to converting to `void *` or `const void *`. - - Conversion from a pointer to a derived class, to a pointer to a base class produces a better match the closer the base class is to a direct base class. Suppose the class hierarchy is as shown in the following figure. + - Conversion from a pointer to a derived class, to a pointer to a base class produces a better match the closer the base class is to a direct base class. Suppose the class hierarchy is as shown in the following figure: -![Graph of preferred conversions.](../cpp/media/vc391t1.gif "Graph of preferred conversions")
-Graph showing preferred conversions +:::image type="content" source="../cpp/media/vc391t1.gif" alt-text="Example class hierarchy showing that class A inherits from B which inherits from C which inherits from D.":::\ +Graph showing preferred conversions. Conversion from type `D*` to type `C*` is preferable to conversion from type `D*` to type `B*`. Similarly, conversion from type `D*` to type `B*` is preferable to conversion from type `D*` to type `A*`. @@ -283,16 +282,16 @@ This same rule applies to pointer-to-member conversions. Conversion from type `T The preceding rule applies only along a given path of derivation. Consider the graph shown in the following figure. -![Diagram of multiple inheritance that shows preferred conversions.](../cpp/media/vc391t2.gif)
-Multiple-inheritance graph that shows preferred conversions +:::image type="content" source="../cpp/media/vc391t2.gif" alt-text="Diagram of multiple inheritance that shows preferred conversions. Class C is the base class of class B and D. Class A inherits from class B":::\ +Multiple-inheritance graph that shows preferred conversions. Conversion from type `C*` to type `B*` is preferable to conversion from type `C*` to type `A*`. The reason is that they are on the same path, and `B*` is closer. However, conversion from type `C*` to type `D*` isn't preferable to conversion to type `A*`; there's no preference because the conversions follow different paths. -1. Match with user-defined conversions. This sequence can't be classified as an exact match, a match using promotions, or a match using standard conversions. The sequence must contain only user-defined conversions, standard conversions, or trivial conversions to be classified as a match with user-defined conversions. A match with user-defined conversions is considered a better match than a match with an ellipsis but not as good a match as a match with standard conversions. +1. Match with user-defined conversions. This sequence can't be classified as an exact match, a match using promotions, or a match using standard conversions. To be classified as a match with user-defined conversions, the sequence must only contain user-defined conversions, standard conversions, or trivial conversions. A match with user-defined conversions is considered a better match than a match with an ellipsis (`...`) but not as good a match as a match with standard conversions. 1. Match with an ellipsis. Any sequence that matches an ellipsis in the declaration is classified as a match with an ellipsis. It's considered the weakest match. -User-defined conversions are applied if no built-in promotion or conversion exists. These conversions are selected on the basis of the type of the argument being matched. Consider the following code: +User-defined conversions are applied if no built-in promotion or conversion exists. These conversions are selected based on the type of the argument being matched. Consider the following code: ```cpp // argument_matching1.cpp @@ -308,7 +307,7 @@ public: void Print( int i ) { -}; +} UDC udc; @@ -318,7 +317,7 @@ int main() } ``` -The available user-defined conversions for class `UDC` are from type **`int`** and type **`long`**. Therefore, the compiler considers conversions for the type of the object being matched: `UDC`. A conversion to **`int`** exists, and it is selected. +The available user-defined conversions for class `UDC` are from type **`int`** and type **`long`**. Therefore, the compiler considers conversions for the type of the object being matched: `UDC`. A conversion to **`int`** exists, and it's selected. During the process of matching arguments, standard conversions can be applied to both the argument and the result of a user-defined conversion. Therefore, the following code works: @@ -329,7 +328,7 @@ UDC udc; LogToFile( udc ); ``` -In the preceding example, the user-defined conversion, **operator long**, is invoked to convert `udc` to type **`long`**. If no user-defined conversion to type **`long`** had been defined, the conversion would have proceeded as follows: Type `UDC` would have been converted to type **`int`** using the user-defined conversion. Then the standard conversion from type **`int`** to type **`long`** would have been applied to match the argument in the declaration. +In this example, the compiler invokes a user-defined conversion, `operator long`, to convert `udc` to type **`long`**. If no user-defined conversion to type **`long`** was defined, the compiler would first convert type `UDC` to type **`int`** using the user-defined `operator int` conversion. Then it would apply the standard conversion from type **`int`** to type **`long`** to match the argument in the declaration. If any user-defined conversions are required to match an argument, the standard conversions aren't used when evaluating the best match. Even if more than one candidate function requires a user-defined conversion, the functions are considered equal. For example: @@ -366,15 +365,15 @@ Both versions of `Func` require a user-defined conversion to convert type **`int Even though the second one requires both a standard conversion and the user-defined conversion, the two conversions are still considered equal. > [!NOTE] -> User-defined conversions are considered conversion by construction or conversion by initialization (conversion function). Both methods are considered equal when considering the best match. +> User-defined conversions are considered conversion by construction or conversion by initialization. The compiler considers both methods equal when it determines the best match. -## Argument matching and the this pointer +## Argument matching and the `this` pointer -Class member functions are treated differently, depending on whether they are declared as **`static`**. Because nonstatic functions have an implicit argument that supplies the **`this`** pointer, nonstatic functions are considered to have one more argument than static functions; otherwise, they are declared identically. +Class member functions are treated differently, depending on whether they're declared as **`static`**. **`static`** functions don't have an implicit argument that supplies the **`this`** pointer, so they're considered to have one less argument than regular member functions. Otherwise, they're declared identically. -These nonstatic member functions require that the implied **`this`** pointer match the object type through which the function is being called, or, for overloaded operators, they require that the first argument match the object on which the operator is being applied. (For more information about overloaded operators, see [Overloaded Operators](../cpp/operator-overloading.md).) +Member functions that aren't **`static`** require the implied **`this`** pointer to match the object type the function is being called through. Or, for overloaded operators, they require the first argument to match the object the operator is applied to. For more information about overloaded operators, see [Overloaded operators](../cpp/operator-overloading.md). -Unlike other arguments in overloaded functions, no temporary objects are introduced and no conversions are attempted when trying to match the **`this`** pointer argument. +Unlike other arguments in overloaded functions, the compiler introduces no temporary objects and attempts no conversions when trying to match the **`this`** pointer argument. When the `->` member-selection operator is used to access a member function of class `class_name`, the **`this`** pointer argument has a type of `class_name * const`. If the members are declared as **`const`** or **`volatile`**, the types are `const class_name * const` and `volatile class_name * const`, respectively. @@ -390,9 +389,9 @@ obj.name The left operand of the `->*` and `.*` (pointer to member) operators are treated the same way as the `.` and `->` (member-selection) operators with respect to argument matching. -## Ref-qualifiers on member functions +## Reference-qualifiers on member functions -Ref qualifiers make it possible to overload a member function on the basis of whether the object pointed to by **`this`** is an rvalue or an lvalue. This feature can be used to avoid unnecessary copy operations in scenarios where you choose not to provide pointer access to the data. For example, assume class `C` initializes some data in its constructor, and returns a copy of that data in member function `get_data()`. If an object of type `C` is an rvalue that is about to be destroyed, then the compiler will choose the `get_data() &&` overload, which moves the data rather than copy it. +Reference qualifiers make it possible to overload a member function based on whether the object pointed to by **`this`** is an rvalue or an lvalue. Use this feature to avoid unnecessary copy operations in scenarios where you choose not to provide pointer access to the data. For example, assume class `C` initializes some data in its constructor, and returns a copy of that data in member function `get_data()`. If an object of type `C` is an rvalue that's about to be destroyed, then the compiler chooses the `get_data() &&` overload, which moves instead of copies the data. ```cpp #include @@ -402,7 +401,6 @@ using namespace std; class C { - public: C() {/*expensive initialization*/} vector get_data() & @@ -435,17 +433,17 @@ Several restrictions govern an acceptable set of overloaded functions: - Any two functions in a set of overloaded functions must have different argument lists. -- Overloading functions with argument lists of the same types, based on return type alone, is an error. +- Overloading functions that have argument lists of the same types, based on return type alone, is an error. **Microsoft Specific** -You can overload **operator new** solely on the basis of return type — specifically, on the basis of the memory-model modifier specified. + You can overload **`operator new`** based on the return type, specifically, based on the memory-model modifier specified. -**END Microsoft Specific** + **END Microsoft Specific** -- Member functions can't be overloaded solely on the basis of one being static and the other nonstatic. +- Member functions can't be overloaded solely because one is **`static`** and the other isn't **`static`**. -- **`typedef`** declarations do not define new types; they introduce synonyms for existing types. They don't affect the overloading mechanism. Consider the following code: +- **`typedef`** declarations don't define new types; they introduce synonyms for existing types. They don't affect the overloading mechanism. Consider the following code: ```cpp typedef char * PSTR; @@ -458,14 +456,14 @@ You can overload **operator new** solely on the basis of return type — specifi - Enumerated types are distinct types and can be used to distinguish between overloaded functions. -- The types "array of " and "pointer to" are considered identical for the purposes of distinguishing between overloaded functions, but only for singly dimensioned arrays. That's why these overloaded functions conflict and generate an error message: +- The types "array of" and "pointer to" are considered identical for the purposes of distinguishing between overloaded functions, but only for one-dimensional arrays. These overloaded functions conflict and generate an error message: ```cpp void Print( char *szToPrint ); void Print( char szToPrint[] ); ``` - For multiply dimensioned arrays, the second and all succeeding dimensions are considered part of the type. Therefore, they are used in distinguishing between overloaded functions: + For higher dimension arrays, the second and later dimensions are considered part of the type. They're used in distinguishing between overloaded functions: ```cpp void Print( char szToPrint[] ); @@ -475,13 +473,13 @@ You can overload **operator new** solely on the basis of return type — specifi ## Overloading, overriding, and hiding -Any two function declarations of the same name in the same scope can refer to the same function, or to two discrete functions that are overloaded. If the argument lists of the declarations contain arguments of equivalent types (as described in the previous section), the function declarations refer to the same function. Otherwise, they refer to two different functions that are selected using overloading. +Any two function declarations of the same name in the same scope can refer to the same function, or to two discrete overloaded functions. If the argument lists of the declarations contain arguments of equivalent types (as described in the previous section), the function declarations refer to the same function. Otherwise, they refer to two different functions that are selected using overloading. -Class scope is strictly observed; therefore, a function declared in a base class isn't in the same scope as a function declared in a derived class. If a function in a derived class is declared with the same name as a virtual function in the base class, the derived-class function *overrides* the base-class function. For more information, see [Virtual Functions](../cpp/virtual-functions.md). +Class scope is strictly observed. A function declared in a base class isn't in the same scope as a function declared in a derived class. If a function in a derived class is declared with the same name as a `virtual` function in the base class, the derived-class function *overrides* the base-class function. For more information, see [Virtual Functions](../cpp/virtual-functions.md). -If the base class function isn't declared as 'virtual', then the derived class function is said to *hide* it. Both overriding and hiding are distinct from overloading. +If the base class function isn't declared as `virtual`, then the derived class function is said to *hide* it. Both overriding and hiding are distinct from overloading. -Block scope is strictly observed; therefore, a function declared in file scope isn't in the same scope as a function declared locally. If a locally declared function has the same name as a function declared in file scope, the locally declared function hides the file-scoped function instead of causing overloading. For example: +Block scope is strictly observed. A function declared in file scope isn't in the same scope as a function declared locally. If a locally declared function has the same name as a function declared in file scope, the locally declared function hides the file-scoped function instead of causing overloading. For example: ```cpp // declaration_matching1.cpp @@ -496,22 +494,22 @@ void func( int i ) void func( char *sz ) { - cout << "Called locally declared func : " << sz << endl; + cout << "Called locally declared func : " << sz << endl; } int main() { - // Declare func local to main. - extern void func( char *sz ); + // Declare func local to main. + extern void func( char *sz ); - func( 3 ); // C2664 Error. func( int ) is hidden. - func( "s" ); + func( 3 ); // C2664 Error. func( int ) is hidden. + func( "s" ); } ``` The preceding code shows two definitions from the function `func`. The definition that takes an argument of type `char *` is local to `main` because of the **`extern`** statement. Therefore, the definition that takes an argument of type **`int`** is hidden, and the first call to `func` is in error. -For overloaded member functions, different versions of the function can be given different access privileges. They are still considered to be in the scope of the enclosing class and thus are overloaded functions. Consider the following code, in which the member function `Deposit` is overloaded; one version is public, the other, private. +For overloaded member functions, different versions of the function can be given different access privileges. They're still considered to be in the scope of the enclosing class and thus are overloaded functions. Consider the following code, in which the member function `Deposit` is overloaded; one version is public, the other, private. The intent of this sample is to provide an `Account` class in which a correct password is required to perform deposits. It's done by using overloading. diff --git a/docs/cpp/functions-cpp.md b/docs/cpp/functions-cpp.md index a1b57135b7..58670206a1 100644 --- a/docs/cpp/functions-cpp.md +++ b/docs/cpp/functions-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Functions (C++)" title: "Functions (C++)" -ms.date: "11/19/2018" +description: "Learn more about: Functions (C++)" +ms.date: 11/19/2018 helpviewer_keywords: ["defaults, arguments", "function definitions", "function definitions, about function definitions", "default arguments", "declarators, functions"] -ms.assetid: 33ba01d5-75b5-48d2-8eab-5483ac7d2274 --- # Functions (C++) @@ -27,15 +26,15 @@ int main() } ``` -There is no practical limit to function length, but good design aims for functions that perform a single well-defined task. Complex algorithms should be broken up into easy-to-understand simpler functions whenever possible. +There's no practical limit to function length, but good design aims for functions that perform a single well-defined task. Complex algorithms should be broken up into easy-to-understand simpler functions whenever possible. -Functions that are defined at class scope are called member functions. In C++, unlike other languages, a function can also be defined at namespace scope (including the implicit global namespace). Such functions are called *free functions* or *non-member functions*; they are used extensively in the Standard Library. +Functions that are defined at class scope are called member functions. In C++, unlike other languages, a function can also be defined at namespace scope (including the implicit global namespace). Such functions are called *free functions* or *non-member functions*; they're used extensively in the Standard Library. Functions may be *overloaded*, which means different versions of a function may share the same name if they differ by the number and/or type of formal parameters. For more information, see [Function Overloading](../cpp/function-overloading.md). ## Parts of a function declaration -A minimal function *declaration* consists of the return type, function name, and parameter list (which may be empty), along with optional keywords that provide additional instructions to the compiler. The following example is a function declaration: +A minimal function *declaration* consists of the return type, function name, and parameter list (which may be empty), along with optional keywords that provide more instructions to the compiler. The following example is a function declaration: ```cpp int sum(int a, int b); @@ -56,7 +55,7 @@ The required parts of a function declaration are: 1. The return type, which specifies the type of the value that the function returns, or **`void`** if no value is returned. In C++11, **`auto`** is a valid return type that instructs the compiler to infer the type from the return statement. In C++14, `decltype(auto)` is also allowed. For more information, see Type Deduction in Return Types below. -1. The function name, which must begin with a letter or underscore and cannot contain spaces. In general, leading underscores in the Standard Library function names indicate private member functions, or non-member functions that are not intended for use by your code. +1. The function name, which must begin with a letter or underscore and can't contain spaces. In general, leading underscores in the Standard Library function names indicate private member functions, or non-member functions that aren't intended for use by your code. 1. The parameter list, a brace delimited, comma-separated set of zero or more parameters that specify the type and optionally a local name by which the values may be accessed inside the function body. @@ -78,7 +77,6 @@ Optional parts of a function declaration are: ```cpp //Declare printf with C linkage. extern "C" int printf( const char *fmt, ... ); - ``` For more information, see [Translation units and linkage](../cpp/program-and-linkage-cpp.md). @@ -94,7 +92,7 @@ Optional parts of a function declaration are: For more information, see [Inline Functions](../cpp/inline-functions-cpp.md). -1. A **`noexcept`** expression, which specifies whether or not the function can throw an exception. In the following example, the function does not throw an exception if the `is_pod` expression evaluates to **`true`**. +1. A **`noexcept`** expression, which specifies whether or not the function can throw an exception. In the following example, the function doesn't throw an exception if the `is_pod` expression evaluates to **`true`**. ```cpp #include @@ -107,17 +105,12 @@ Optional parts of a function declaration are: 1. (Member functions only) The cv-qualifiers, which specify whether the function is **`const`** or **`volatile`**. -1. (Member functions only) **`virtual`**, **`override`**, or **`final`**. **`virtual`** specifies that a function can be overridden in a derived class. **`override`** means that a function in a derived class is overriding a virtual function. **`final`** means a function cannot be overridden in any further derived class. For more information, see [Virtual Functions](../cpp/virtual-functions.md). +1. (Member functions only) **`virtual`**, **`override`**, or **`final`**. **`virtual`** specifies that a function can be overridden in a derived class. **`override`** means that a function in a derived class is overriding a virtual function. **`final`** means a function can't be overridden in any further derived class. For more information, see [Virtual Functions](../cpp/virtual-functions.md). -1. (member functions only) **`static`** applied to a member function means that the function is not associated with any object instances of the class. +1. (member functions only) **`static`** applied to a member function means that the function isn't associated with any object instances of the class. 1. (Non-static member functions only) The ref-qualifier, which specifies to the compiler which overload of a function to choose when the implicit object parameter (`*this`) is an rvalue reference vs. an lvalue reference. For more information, see [Function Overloading](function-overloading.md#ref-qualifiers). -The following figure shows the parts of a function definition. The shaded area is the function body. - -![Diagram of the parts of a function definition.](../cpp/media/vc38ru1.gif "Parts of a function definition")
-Parts of a function definition - ## Function definitions A *function definition* consists of the declaration and the function body, enclosed in curly braces, which contains variable declarations, statements and expressions. The following example shows a complete function definition: @@ -149,7 +142,7 @@ Variables declared inside the body are called local variables or locals. They go ## const and constexpr functions -You can declare a member function as **`const`** to specify that the function is not allowed to change the values of any data members in the class. By declaring a member function as **`const`**, you help the compiler to enforce *const-correctness*. If someone mistakenly tries to modify the object by using a function declared as **`const`**, a compiler error is raised. For more information, see [const](const-cpp.md). +You can declare a member function as **`const`** to specify that the function isn't allowed to change the values of any data members in the class. By declaring a member function as **`const`**, you help the compiler to enforce *const-correctness*. If someone mistakenly tries to modify the object by using a function declared as **`const`**, a compiler error is raised. For more information, see [const](const-cpp.md). Declare a function as **`constexpr`** when the value it produces can possibly be determined at compile time. A constexpr function generally executes faster than a regular function. For more information, see [`constexpr`](constexpr-cpp.md). @@ -172,9 +165,9 @@ For more information, see [Function Templates](../cpp/function-templates.md) ## Function parameters and arguments -A function has a comma-separated parameter list of zero or more types, each of which has a name by which it can be accessed inside the function body. A function template may specify additional type or value parameters. The caller passes arguments, which are concrete values whose types are compatible with the parameter list. +A function has a comma-separated parameter list of zero or more types, each of which has a name by which it can be accessed inside the function body. A function template may specify more type or value parameters. The caller passes arguments, which are concrete values whose types are compatible with the parameter list. -By default, arguments are passed to the function by value, which means the function receives a copy of the object being passed. For large objects, making a copy can be expensive and is not always necessary. To cause arguments to be passed by reference (specifically lvalue reference), add a reference quantifier to the parameter: +By default, arguments are passed to the function by value, which means the function receives a copy of the object being passed. For large objects, making a copy can be expensive and isn't always necessary. To cause arguments to be passed by reference (specifically lvalue reference), add a reference quantifier to the parameter: ```cpp void DoSomething(std::string& input){...} @@ -186,7 +179,7 @@ When a function modifies an argument that is passed by reference, it modifies th void DoSomething(const std::string& input){...} ``` -**C++ 11:** To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference: +**C++11:** To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference: ```cpp void DoSomething(const std::string&& input){...} @@ -195,12 +188,11 @@ void DoSomething(const std::string&& input){...} A function declared with the single keyword **`void`** in the parameter declaration list takes no arguments, as long as the keyword **`void`** is the first and only member of the argument declaration list. Arguments of type **`void`** elsewhere in the list produce errors. For example: ```cpp - // OK same as GetTickCount() long GetTickCount( void ); ``` -Note that, while it is illegal to specify a **`void`** argument except as outlined here, types derived from type **`void`** (such as pointers to **`void`** and arrays of **`void`**) can appear anywhere the argument declaration list. +While it's illegal to specify a **`void`** argument except as outlined here, types derived from type **`void`** (such as pointers to **`void`** and arrays of **`void`**) can appear anywhere the argument declaration list. ### Default Arguments @@ -233,7 +225,7 @@ A function may not return another function, or a built-in array; however it can ### Trailing return types -An "ordinary" return type is located on the left side of the function signature. A *trailing return type* is located on the right most side of the signature and is preceded by the **`->`** operator. Trailing return types are especially useful in function templates when the type of the return value depends on template parameters. +An "ordinary" return type is located on the left side of the function signature. A *trailing return type* is located on the rightmost side of the signature and is preceded by the **`->`** operator. Trailing return types are especially useful in function templates when the type of the return value depends on template parameters. ```cpp template @@ -243,13 +235,13 @@ auto Add(const Lhs& lhs, const Rhs& rhs) -> decltype(lhs + rhs) } ``` -When **`auto`** is used in conjunction with a trailing return type, it just serves as a placeholder for whatever the decltype expression produces, and does not itself perform type deduction. +When **`auto`** is used in conjunction with a trailing return type, it just serves as a placeholder for whatever the decltype expression produces, and doesn't itself perform type deduction. ## Function local variables -A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the *named return value optimization* to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed. +A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they're declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the *named return value optimization* to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed. -In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object was not constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object. +In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object wasn't constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object. ## Type deduction in return types (C++14) @@ -265,7 +257,7 @@ auto Add2(const Lhs& lhs, const Rhs& rhs) } ``` -Note that **`auto`** does not preserve the const-ness of the type it deduces. For forwarding functions whose return value needs to preserve the const-ness or ref-ness of its arguments, you can use the **`decltype(auto)`** keyword, which uses the **`decltype`** type inference rules and preserves all the type information. **`decltype(auto)`** may be used as an ordinary return value on the left side, or as a trailing return value. +Note that **`auto`** doesn't preserve the const-ness of the type it deduces. For forwarding functions whose return value needs to preserve the const-ness or ref-ness of its arguments, you can use the **`decltype(auto)`** keyword, which uses the **`decltype`** type inference rules and preserves all the type information. **`decltype(auto)`** may be used as an ordinary return value on the left side, or as a trailing return value. The following example (based on code from [N3493](https://wg21.link/n3493)), shows **`decltype(auto)`** being used to enable perfect forwarding of function arguments in a return type that isn't known until the template is instantiated. @@ -352,7 +344,7 @@ There are various ways to return more than one value from a function: } ``` -1. **Visual Studio 2017 version 15.3 and later** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): Use structured bindings. The advantage of structured bindings is that the variables that store the return values are initialized at the same time they are declared, which in some cases can be significantly more efficient. In the statement `auto[x, y, z] = f();` the brackets introduce and initialize names that are in scope for the entire function block. +1. **Visual Studio 2017 version 15.3 and later** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): Use structured bindings. The advantage of structured bindings is that the variables that store the return values are initialized at the same time they're declared, which in some cases can be significantly more efficient. In the statement `auto[x, y, z] = f();` the brackets introduce and initialize names that are in scope for the entire function block. ```cpp #include @@ -398,26 +390,26 @@ There are various ways to return more than one value from a function: C++ supports function pointers in the same manner as the C language. However a more type-safe alternative is usually to use a function object. -It is recommended that **`typedef`** be used to declare an alias for the function pointer type if declaring a function that returns a function pointer type. For example +It's recommended that you use **`typedef`** to declare an alias for the function pointer type if declaring a function that returns a function pointer type. For example ```cpp typedef int (*fp)(int); fp myFunction(char* s); // function returning function pointer ``` -If this is not done, the proper syntax for the function declaration may be deduced from the declarator syntax for the function pointer by replacing the identifier (`fp` in the above example) with the functions name and argument list, as follows: +If this isn't done, the proper syntax for the function declaration may be deduced from the declarator syntax for the function pointer by replacing the identifier (`fp` in the above example) with the functions name and argument list, as follows: ```cpp int (*myFunction(char* s))(int); ``` -The preceding declaration is equivalent to the declaration using **`typedef`** above. +The preceding declaration is equivalent to the declaration using **`typedef`** earlier. ## See also -[Function Overloading](../cpp/function-overloading.md)
-[Functions with Variable Argument Lists](../cpp/functions-with-variable-argument-lists-cpp.md)
-[Explicitly Defaulted and Deleted Functions](../cpp/explicitly-defaulted-and-deleted-functions.md)
-[Argument-Dependent Name (Koenig) Lookup on Functions](../cpp/argument-dependent-name-koenig-lookup-on-functions.md)
-[Default Arguments](../cpp/default-arguments.md)
+[Function Overloading](../cpp/function-overloading.md)\ +[Functions with Variable Argument Lists](../cpp/functions-with-variable-argument-lists-cpp.md)\ +[Explicitly Defaulted and Deleted Functions](../cpp/explicitly-defaulted-and-deleted-functions.md)\ +[Argument-Dependent Name (Koenig) Lookup on Functions](../cpp/argument-dependent-name-koenig-lookup-on-functions.md)\ +[Default Arguments](../cpp/default-arguments.md)\ [Inline Functions](../cpp/inline-functions-cpp.md) diff --git a/docs/cpp/functions-with-variable-argument-lists-cpp.md b/docs/cpp/functions-with-variable-argument-lists-cpp.md index 1fb884942d..9ded375dbc 100644 --- a/docs/cpp/functions-with-variable-argument-lists-cpp.md +++ b/docs/cpp/functions-with-variable-argument-lists-cpp.md @@ -1,66 +1,68 @@ --- description: "Learn more about: Functions with Variable Argument Lists (C++)" title: "Functions with Variable Argument Lists (C++)" -ms.date: "11/04/2016" +ms.date: 05/01/2025 helpviewer_keywords: ["arguments [C++], variable number of", "variable argument lists", "declarators, functions", "argument lists [C++], variable number of", "declaring functions [C++], variables", "function calls, variable number of arguments"] -ms.assetid: 27c2f83a-21dd-44c6-913c-2834cb944703 --- # Functions with Variable Argument Lists (C++) -Function declarations in which the last member of is the ellipsis (...) can take a variable number of arguments. In these cases, C++ provides type checking only for the explicitly declared arguments. You can use variable argument lists when you need to make a function so general that even the number and types of arguments can vary. The family of functions is an example of functions that use variable argument lists.`printf`*argument-declaration-list* +Function declarations that have ellipsis (...) as the last argument take a variable number of arguments. C++ provides type checking only for the explicitly declared arguments. You can use variable argument lists when the number and types of arguments to the function can vary. The `printf` family of functions is an example of functions that have variable argument lists. ## Functions with variable arguments -To access arguments after those declared, use the macros contained in the standard include file \ as described below. +To access arguments after those declared, use the macros contained in the standard include file `` as explained in this article. **Microsoft Specific** -Microsoft C++ allows the ellipsis to be specified as an argument if the ellipsis is the last argument and the ellipsis is preceded by a comma. Therefore, the declaration `int Func( int i, ... );` is legal, but `int Func( int i ... );` is not. +Microsoft C++ allows the ellipsis to be specified as an argument if the ellipsis is the last argument and a comma comes before the ellipsis. Therefore, the declaration `int Func( int i, ... );` is legal, but `int Func( int i ... );` isn't. **END Microsoft Specific** -Declaration of a function that takes a variable number of arguments requires at least one placeholder argument, even if it is not used. If this placeholder argument is not supplied, there is no way to access the remaining arguments. +Declaration of a function that takes a variable number of arguments requires at least one placeholder argument, even if it isn't used. If this placeholder argument isn't supplied, there's no way to access the remaining arguments. -When arguments of type **`char`** are passed as variable arguments, they are converted to type **`int`**. Similarly, when arguments of type **`float`** are passed as variable arguments, they are converted to type **`double`**. Arguments of other types are subject to the usual integral and floating-point promotions. See [Standard Conversions](standard-conversions.md) for more information. +When arguments of type **`char`** are passed as variable arguments, they're converted to type **`int`**. Similarly, when arguments of type **`float`** are passed as variable arguments, they're converted to type **`double`**. Arguments of other types are subject to the usual integral and floating-point promotions. For more information, see [Standard Conversions](standard-conversions.md). -Functions that require variable lists are declared by using the ellipsis (...) in the argument list. Use the types and macros that are described in the \ include file to access arguments that are passed by a variable list. For more information about these macros, see [va_arg, va_copy, va_end, va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). in the documentation for the C Run-Time Library. +Functions that require variable lists are declared by using the ellipsis (...) in the argument list. Use the types and macros that are described in the `` include file to access arguments that are passed by a variable list. For more information about these macros, see [va_arg, va_copy, va_end, va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). -The following example shows how the macros work together with the type (declared in \): +The following example shows how to use the macros to process a variable argument list: ```cpp // variable_argument_lists.cpp + #include #include // Declaration, but not definition, of ShowVar. void ShowVar( char *szTypes, ... ); + int main() { ShowVar( "fcsi", 32.4f, 'a', "Test string", 4 ); } -// ShowVar takes a format string of the form -// "ifcs", where each character specifies the -// type of the argument in that position. +// ShowVar takes a format string of the form +// "ifcs", where each character specifies the +// type of the argument in that position. // -// i = int -// f = float -// c = char -// s = string (char *) +// i = int +// f = float +// c = char +// s = string (char *) // -// Following the format specification is a variable -// list of arguments. Each argument corresponds to -// a format character in the format string to which +// Following the format specification is a variable +// list of arguments. Each argument corresponds to +// a format character in the format string to which // the szTypes parameter points void ShowVar( char *szTypes, ... ) { va_list vl; int i; - // szTypes is the last argument specified; you must access - // all others using the variable-argument macros. + // szTypes is the last argument specified; you must access + // all others using the variable-argument macros. va_start( vl, szTypes ); // Step through the list. for( i = 0; szTypes[i] != '\0'; ++i ) { + union Printable_t { int i; float f; @@ -68,45 +70,44 @@ void ShowVar( char *szTypes, ... ) { char *s; } Printable; - switch( szTypes[i] ) { // Type to expect. + switch( szTypes[i] ) { // Type to expect case 'i': Printable.i = va_arg( vl, int ); printf_s( "%i\n", Printable.i ); - break; + break; case 'f': Printable.f = va_arg( vl, double ); printf_s( "%f\n", Printable.f ); - break; + break; case 'c': Printable.c = va_arg( vl, char ); printf_s( "%c\n", Printable.c ); - break; + break; case 's': Printable.s = va_arg( vl, char * ); printf_s( "%s\n", Printable.s ); - break; + break; default: - break; + break; } } va_end( vl ); } -//Output: -// 32.400002 -// a -// Test string +``` + +```Output +32.400002 +a +Test string ``` The previous example illustrates these important concepts: 1. You must establish a list marker as a variable of type `va_list` before any variable arguments are accessed. In the previous example, the marker is called `vl`. - 1. The individual arguments are accessed by using the `va_arg` macro. You must tell the `va_arg` macro the type of argument to retrieve so that it can transfer the correct number of bytes from the stack. If you specify an incorrect type of a size different from that supplied by the calling program to `va_arg`, the results are unpredictable. - 1. You should explicitly cast the result obtained by using the `va_arg` macro to the type that you want. - -You must call the macro to terminate variable-argument processing.`va_end` +1. You must call the `va_end` macro to terminate variable-argument processing. \ No newline at end of file diff --git a/docs/cpp/how-to-create-and-use-shared-ptr-instances.md b/docs/cpp/how-to-create-and-use-shared-ptr-instances.md index dd38446740..28e2e78d4a 100644 --- a/docs/cpp/how-to-create-and-use-shared-ptr-instances.md +++ b/docs/cpp/how-to-create-and-use-shared-ptr-instances.md @@ -2,17 +2,18 @@ description: "Learn more about: How to: Create and Use shared_ptr instances" title: "How to: Create and use shared_ptr instances" ms.custom: "how-to" -ms.date: "11/19/2019" +ms.date: "12/4/2024" ms.topic: "conceptual" -ms.assetid: 7d6ebb73-fa0d-4b0b-a528-bf05de96518e --- # How to: Create and Use shared_ptr instances -The `shared_ptr` type is a smart pointer in the C++ standard library that is designed for scenarios in which more than one owner might have to manage the lifetime of the object in memory. After you initialize a `shared_ptr` you can copy it, pass it by value in function arguments, and assign it to other `shared_ptr` instances. All the instances point to the same object, and share access to one "control block" that increments and decrements the reference count whenever a new `shared_ptr` is added, goes out of scope, or is reset. When the reference count reaches zero, the control block deletes the memory resource and itself. +The `shared_ptr` type is a smart pointer in the C++ standard library that is designed for scenarios in which more than one owner needs to manage the lifetime of an object. After you initialize a `shared_ptr` you can copy it, pass it by value in function arguments, and assign it to other `shared_ptr` instances. All the instances point to the same object, and share access to one "control block" that increments and decrements the reference count whenever a new `shared_ptr` is added, goes out of scope, or is reset. When the reference count reaches zero, the control block deletes the memory resource and itself. The following illustration shows several `shared_ptr` instances that point to one memory location. -![Shared pointer diagram.](media/shared_ptr.png "Shared pointer diagram") +:::image type="complex" source="media/shared_ptr.png" alt-text="Diagram showing two shared_ptr instances pointing to one memory location."::: +The first diagram shows a shared pointer, P1, that points to a MyClass instance as well as a control block with ref count = 1. The second diagram shows the addition of another shared pointer, P2, which also points to the MyClass instance and to the shared control block, which now has a ref count of 2. +:::image-end::: ## Example setup @@ -67,13 +68,13 @@ int main() ## Example 1 -Whenever possible, use the [make_shared](../standard-library/memory-functions.md#make_shared) function to create a `shared_ptr` when the memory resource is created for the first time. `make_shared` is exception-safe. It uses the same call to allocate the memory for the control block and the resource, which reduces the construction overhead. If you don't use `make_shared`, then you have to use an explicit **`new`** expression to create the object before you pass it to the `shared_ptr` constructor. The following example shows various ways to declare and initialize a `shared_ptr` together with a new object. +Whenever possible, use the [`make_shared`](../standard-library/memory-functions.md#make_shared) function to create a `shared_ptr` when the memory resource is created for the first time. `make_shared` is exception-safe. It uses the same call to allocate the memory for the control block and the resource, which reduces the construction overhead. If you don't use `make_shared`, then you have to use an explicit **`new`** expression to create the object before you pass it to the `shared_ptr` constructor. The following example shows various ways to declare and initialize a `shared_ptr` together with a new object. [!code-cpp[stl_smart_pointers#1](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp)] ## Example 2 -The following example shows how to declare and initialize `shared_ptr` instances that take on shared ownership of an object that has already been allocated by another `shared_ptr`. Assume that `sp2` is an initialized `shared_ptr`. +The following example shows how to declare and initialize `shared_ptr` instances that take on shared ownership of an object that was allocated by another `shared_ptr`. Assume that `sp2` is an initialized `shared_ptr`. [!code-cpp[stl_smart_pointers#2](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_2.cpp)] @@ -81,13 +82,13 @@ The following example shows how to declare and initialize `shared_ptr` instances `shared_ptr` is also helpful in C++ Standard Library containers when you're using algorithms that copy elements. You can wrap elements in a `shared_ptr`, and then copy it into other containers with the understanding that the underlying memory is valid as long as you need it, and no longer. The following example shows how to use the `remove_copy_if` algorithm on `shared_ptr` instances in a vector. -[!code-cpp[stl_smart_pointers#4](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_3.cpp)] +[!code-cpp[stl_smart_pointers#3](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_3.cpp)] ## Example 4 -You can use `dynamic_pointer_cast`, `static_pointer_cast`, and `const_pointer_cast` to cast a `shared_ptr`. These functions resemble the **`dynamic_cast`**, **`static_cast`**, and **`const_cast`** operators. The following example shows how to test the derived type of each element in a vector of `shared_ptr` of base classes, and then copy the elements and display information about them. +You can use `dynamic_pointer_cast`, `static_pointer_cast`, and `const_pointer_cast` to cast a `shared_ptr`. These functions resemble the **`dynamic_cast`**, **`static_cast`**, and **`const_cast`** operators. The following example shows how to test the derived type of each element in a vector of `shared_ptr` of base classes, and then copies the elements and display information about them. -[!code-cpp[stl_smart_pointers#5](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_4.cpp)] +[!code-cpp[stl_smart_pointers#4](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_4.cpp)] ## Example 5 @@ -97,19 +98,21 @@ You can pass a `shared_ptr` to another function in the following ways: - Pass the `shared_ptr` by reference or const reference. In this case, the reference count isn't incremented, and the callee can access the pointer as long as the caller doesn't go out of scope. Or, the callee can decide to create a `shared_ptr` based on the reference, and become a shared owner. Use this option when the caller has no knowledge of the callee, or when you must pass a `shared_ptr` and want to avoid the copy operation for performance reasons. -- Pass the underlying pointer or a reference to the underlying object. This enables the callee to use the object, but doesn't enable it to share ownership or extend the lifetime. If the callee creates a `shared_ptr` from the raw pointer, the new `shared_ptr` is independent from the original, and doesn't control the underlying resource. Use this option when the contract between the caller and callee clearly specifies that the caller retains ownership of the `shared_ptr` lifetime. +- Pass the underlying pointer or a reference to the underlying object. This enables the callee to use the object, but it doesn't share ownership of the object with the caller's `shared_ptr`. Beware the case of the callee creating a `shared_ptr` from the passed raw pointer because the callee's `shared_ptr` has an independent reference count from the caller's `shared_ptr`. When the `shared_ptr` in the callee goes out of scope, it will delete the object, leaving the pointer in the caller's 'shared_ptr' pointing at released memory. When the caller's `shared_ptr` then goes out of scope, a double-free results. Only use this option when the contract between the caller and callee clearly specifies that the caller retains ownership of the `shared_ptr` lifetime. - When you're deciding how to pass a `shared_ptr`, determine whether the callee has to share ownership of the underlying resource. An "owner" is an object or function that can keep the underlying resource alive for as long as it needs it. If the caller has to guarantee that the callee can extend the life of the pointer beyond its (the function's) lifetime, use the first option. If you don't care whether the callee extends the lifetime, then pass by reference and let the callee copy it or not. -- If you have to give a helper function access to the underlying pointer, and you know that the helper function will just use the pointer and return before the calling function returns, then that function doesn't have to share ownership of the underlying pointer. It just has to access the pointer within the lifetime of the caller's `shared_ptr`. In this case, it's safe to pass the `shared_ptr` by reference, or pass the raw pointer or a reference to the underlying object. Passing this way provides a small performance benefit, and may also help you express your programming intent. +- If you have to give a helper function access to the underlying pointer, and you know that the helper function uses the pointer and return before the calling function returns, then that function doesn't have to share ownership of the underlying pointer. It just has to access the pointer within the lifetime of the caller's `shared_ptr`. In this case, it's safe to pass the `shared_ptr` by reference, or pass the raw pointer or a reference to the underlying object. Passing this way provides a small performance benefit, and may also help you express your programming intent. - Sometimes, for example in a `std::vector>`, you may have to pass each `shared_ptr` to a lambda expression body or named function object. If the lambda or function doesn't store the pointer, then pass the `shared_ptr` by reference to avoid invoking the copy constructor for each element. +[!code-cpp[stl_smart_pointers#5](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_5.cpp)] + ## Example 6 The following example shows how `shared_ptr` overloads various comparison operators to enable pointer comparisons on the memory that is owned by the `shared_ptr` instances. -[!code-cpp[stl_smart_pointers#3](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)] +[!code-cpp[stl_smart_pointers#6](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)] ## See also diff --git a/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md b/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md index 75071fa932..75d4de4934 100644 --- a/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md +++ b/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md @@ -2,23 +2,22 @@ description: "Learn more about: How to: Interface between exceptional and non-exceptional code" title: "How to: Interface between exceptional and non-exceptional code" ms.custom: "how-to" -ms.date: "11/19/2019" +ms.date: 03/02/2022 ms.topic: "conceptual" -ms.assetid: fd5bb4af-5665-46a1-a321-614b48d4061e --- # How to: Interface between exceptional and non-exceptional code -This article describes how to implement consistent exception-handling in a C++ module, and also how to translate those exceptions to and from error codes at the exception boundaries. +This article describes how to implement consistent exception-handling in C++ code, and how to translate exceptions to and from error codes at exception boundaries. -Sometimes a C++ module has to interface with code that doesn't use exceptions (non-exceptional code). Such an interface is known as an *exception boundary*. For example, you may want to call the Win32 function `CreateFile` in your C++ program. `CreateFile` doesn't throw exceptions; instead it sets error codes that can be retrieved by the `GetLastError` function. If your C++ program is non-trivial, then in it you probably prefer to have a consistent exception-based error-handling policy. And you probably don't want to abandon exceptions just because you interface with non-exceptional code, and neither do you want to mix exception-based and non-exception-based error policies in your C++ module. +Sometimes C++ code has to interface with code that doesn't use exceptions (non-exceptional code). Such an interface is known as an *exception boundary*. For example, you may want to call the Win32 function `CreateFile` in your C++ program. `CreateFile` doesn't throw exceptions. Instead, it sets error codes that can be retrieved by the `GetLastError` function. If your C++ program is non-trivial, then you probably prefer to have a consistent exception-based error-handling policy. And, you probably don't want to abandon exceptions just because you interface with non-exceptional code. You also don't want to mix exception-based and non-exception-based error policies in your C++ code. -## Calling non-exceptional functions from C++ +## Call non-exceptional functions from C++ -When you call a non-exceptional function from C++, the idea is to wrap that function in a C++ function that detects any errors and then possibly throws an exception. When you design such a wrapper function, first decide which type of exception guarantee to provide: no-throw, strong, or basic. Second, design the function so that all resources, for example, file handles, are correctly released if an exception is thrown. Typically, this means that you use smart pointers or similar resource managers to own the resources. For more information about design considerations, see [How to: Design for Exception Safety](how-to-design-for-exception-safety.md). +When you call a non-exceptional function from C++, the idea is to wrap that function in a C++ function that detects any errors and then possibly throws an exception. When you design such a wrapper function, first decide which type of exception guarantee to provide: noexcept, strong, or basic. Second, design the function so that all resources, for example, file handles, are correctly released if an exception is thrown. Typically, it means that you use smart pointers or similar resource managers to own the resources. For more information about design considerations, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). ### Example -The following example shows C++ functions that use the Win32 `CreateFile` and `ReadFile` functions internally to open and read two files. The `File` class is a resource acquisition is initialization (RAII) wrapper for the file handles. Its constructor detects a "file not found" condition and throws an exception to propagate the error up the call stack of the C++ module (in this example, the `main()` function). If an exception is thrown after a `File` object is fully constructed, the destructor automatically calls `CloseHandle` to release the file handle. (If you prefer, you can use the Active Template Library (ATL) `CHandle` class for this same purpose, or a `unique_ptr` together with a custom deleter.) The functions that call Win32 and CRT APIs detect errors and then throw C++ exceptions using the locally-defined `ThrowLastErrorIf` function, which in turn uses the `Win32Exception` class, derived from the `runtime_error` class. All functions in this example provide a strong exception guarantee; if an exception is thrown at any point in these functions, no resources are leaked and no program state is modified. +The following example shows C++ functions that use the Win32 `CreateFile` and `ReadFile` functions internally to open and read two files. The `File` class is a resource acquisition is initialization (RAII) wrapper for the file handles. Its constructor detects a "file not found" condition and throws an exception to propagate the error up the call stack of the C++ executable (in this example, the `main()` function). If an exception is thrown after a `File` object is fully constructed, the destructor automatically calls `CloseHandle` to release the file handle. (If you prefer, you can use the Active Template Library (ATL) `CHandle` class for this same purpose, or a `unique_ptr` together with a custom deletion function.) The functions that call Win32 and CRT APIs detect errors and then throw C++ exceptions using the locally defined `ThrowLastErrorIf` function, which in turn uses the `Win32Exception` class, derived from the `runtime_error` class. All functions in this example provide a strong exception guarantee: If an exception is thrown at any point in these functions, no resources are leaked and no program state is modified. ```cpp // compile with: /EHsc @@ -153,11 +152,13 @@ int main ( int argc, char* argv[] ) } ``` -## Calling exceptional code from non-exceptional code +## Call exceptional code from non-exceptional code -C++ functions that are declared as "extern C" can be called by C programs. C++ COM servers can be consumed by code written in any of a number of different languages. When you implement public exception-aware functions in C++ to be called by non-exceptional code, the C++ function must not allow any exceptions to propagate back to the caller. Therefore, the C++ function must specifically catch every exception that it knows how to handle and, if appropriate, convert the exception to an error code that the caller understands. If not all potential exceptions are known, the C++ function should have a `catch(...)` block as the last handler. In such a case, it's best to report a fatal error to the caller, because your program might be in an unknown state. +C++ functions that are declared as `extern "C"` can be called by C programs. C++ COM servers can be consumed by code written in any number of different languages. When you implement public exception-aware functions in C++ to be called by non-exceptional code, the C++ function must not allow any exceptions to propagate back to the caller. Such callers have no way to catch or handle C++ exceptions. The program may terminate, leak resources, or cause undefined behavior. -The following example shows a function that assumes that any exception that might be thrown is either a Win32Exception or an exception type derived from `std::exception`. The function catches any exception of these types and propagates the error information as a Win32 error code to the caller. +We recommend your `extern "C"` C++ function specifically catch every exception that it knows how to handle and, if appropriate, convert the exception to an error code that the caller understands. If not all potential exceptions are known, the C++ function should have a `catch(...)` block as the last handler. In such a case, it's best to report a fatal error to the caller, because your program might be in an unknown and unrecoverable state. + +The following example shows a function that assumes that any exception that might be thrown is either a `Win32Exception` or an exception type derived from `std::exception`. The function catches any exception of these types and propagates the error information as a Win32 error code to the caller. ```cpp BOOL DiffFiles2(const string& file1, const string& file2) @@ -186,7 +187,7 @@ BOOL DiffFiles2(const string& file1, const string& file2) } ``` -When you convert from exceptions to error codes, one potential issue is that error codes often don't contain the richness of information that an exception can store. To address this, you can provide a **`catch`** block for each specific exception type that might be thrown, and perform logging to record the details of the exception before it is converted to an error code. This approach can create a lot of code repetition if multiple functions all use the same set of **`catch`** blocks. A good way to avoid code repetition is by refactoring those blocks into one private utility function that implements the **`try`** and **`catch`** blocks and accepts a function object that is invoked in the **`try`** block. In each public function, pass the code to the utility function as a lambda expression. +When you convert from exceptions to error codes, there's a potential issue: Error codes often don't contain the richness of information that an exception can store. To address this issue, you can provide a **`catch`** block for each specific exception type that might be thrown, and perform logging to record the details of the exception before it's converted to an error code. This approach can create repetitive code if multiple functions all use the same set of **`catch`** blocks. A good way to avoid code repetition is by refactoring those blocks into one private utility function that implements the **`try`** and **`catch`** blocks and accepts a function object that is invoked in the **`try`** block. In each public function, pass the code to the utility function as a lambda expression. ```cpp template @@ -208,7 +209,7 @@ bool Win32ExceptionBoundary(Func&& f) } ``` -The following example shows how to write the lambda expression that defines the functor. When a functor is defined "inline" by using a lambda expression, it is often easier to read than it would be if it were written as a named function object. +The following example shows how to write the lambda expression that defines the functor. A lambda expression is often easier to read inline than code that calls a named function object. ```cpp bool DiffFiles3(const string& file1, const string& file2) @@ -227,9 +228,21 @@ bool DiffFiles3(const string& file1, const string& file2) } ``` -For more information about lambda expressions, see [Lambda Expressions](lambda-expressions-in-cpp.md). +For more information about lambda expressions, see [Lambda expressions](lambda-expressions-in-cpp.md). + +## Call exceptional code through non-exceptional code from exceptional code + +It's possible, but not recommended, to throw exceptions across exception-unaware code. For example, your C++ program may call a library that uses callback functions you provide. In some circumstances, you can throw exceptions from the callback functions across the non-exceptional code that your original caller can handle. However, the circumstances when exceptions can work successfully are strict. You must compile the library code in a way that preserves stack unwinding semantics. The exception-unaware code can't do anything that might trap the C++ exception. Also, the library code between the caller and the callback can't allocate local resources. For example, the code that isn't exception-aware can't have locals that point to allocated heap memory. These resources are leaked when the stack is unwound. + +These requirements must be met to throw exceptions across non-exception-aware code: + +- You can build the entire code path across the non-exception-aware code using **`/EHs`**, +- There aren't any locally allocated resources that can leak when the stack is unwound, +- The code doesn't have any `__except` structured exception handlers that catch all exceptions. + +Because throwing exceptions across non-exceptional code is error-prone and may cause difficult debugging challenges, we don't recommend it. ## See also -[Modern C++ best practices for exceptions and error handling](errors-and-exception-handling-modern-cpp.md)
-[How to: Design for Exception Safety](how-to-design-for-exception-safety.md)
+[Modern C++ best practices for exceptions and error handling](errors-and-exception-handling-modern-cpp.md)\ +[How to: Design for exception safety](how-to-design-for-exception-safety.md) diff --git a/docs/cpp/hybrid-patchable.md b/docs/cpp/hybrid-patchable.md new file mode 100644 index 0000000000..49dc470455 --- /dev/null +++ b/docs/cpp/hybrid-patchable.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about: hybrid_patchable (C++)" +title: "hybrid_patchable (C++)" +ms.date: 1/15/2025 +f1_keywords: ["hybrid_patchable"] +helpviewer_keywords: ["__declspec keyword [C++], hybrid_patchable", "hybrid_patchable __declspec keyword"] +--- +# `hybrid_patchable` (C++) + +**Microsoft Specific** + +Use `__declspec(hybrid_patchable)` to mark a function as a hybrid patchable function. This attribute generates a fast-forward sequence. Fast-forward sequences are small x64 functions which contain no real logic, and tail-call the real Arm64EC function. Because fast-forward sequences are primarily used for hooking, if they are unaltered, execution is transferred directly to the Arm64EC function. + +## Syntax + +> `__declspec(hybrid_patchable)` + +## Remarks + +`__declspec(hybrid_patchable)` is an ARM64EC-only feature. + +**Example:** + +```cpp +__declspec(hybrid_patchable) int Example() +{ + return 1; +} +``` + +Generates the following fast-forward sequence: + +``` +EXP+#Example: + 00000001400CE000: 48 8B C4 mov rax,rsp + 00000001400CE003: 48 89 58 20 mov qword ptr [rax+20h],rbx + 00000001400CE007: 55 push rbp + 00000001400CE008: 5D pop rbp + 00000001400CE009: E9 BA 7A F3 FF jmp #Example + 00000001400CE00E: CC int 3 + 00000001400CE00F: CC int 3 +``` + +**END Microsoft Specific** + +## See also + +[`__declspec`](../cpp/declspec.md)\ +[Fast-Forward sequences](/windows/arm/arm64ec-abi#fast-forward-sequences) \ No newline at end of file diff --git a/docs/cpp/identifiers-cpp.md b/docs/cpp/identifiers-cpp.md index bcdcc5ff98..ab4d4e811f 100644 --- a/docs/cpp/identifiers-cpp.md +++ b/docs/cpp/identifiers-cpp.md @@ -77,7 +77,7 @@ int main() { } ``` -The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications/standards/Ecma-335.htm). +The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://ecma-international.org/publications-and-standards/standards/ecma-335/). **END Microsoft Specific** diff --git a/docs/cpp/if-else-statement-cpp.md b/docs/cpp/if-else-statement-cpp.md index a4328a4ece..21563cb749 100644 --- a/docs/cpp/if-else-statement-cpp.md +++ b/docs/cpp/if-else-statement-cpp.md @@ -1,20 +1,19 @@ --- title: "if-else statement (C++)" description: "Use if-else, if-else with initializer, and if-constexpr statements to control conditional branching." -ms.date: 10/02/2020 +ms.date: 10/16/2023 f1_keywords: ["else_cpp", "if_cpp"] helpviewer_keywords: ["if keyword [C++]", "else keyword [C++]"] -ms.assetid: f8c45cde-6bce-42ae-81db-426b3dbd4caa --- # if-else statement (C++) -An if-else statement controls conditional branching. Statements in the *`if-branch`* are executed only if the *`condition`* evaluates to a non-zero value (or **`true`**). If the value of *`condition`* is nonzero, the following statement gets executed, and the statement following the optional **`else`** gets skipped. Otherwise, the following statement gets skipped, and if there's an **`else`** then the statement following the **`else`** gets executed. +An if-else statement controls conditional branching. Statements in the *`if-branch`* are executed only if the *`condition`* evaluates to a nonzero value (or **`true`**). If the value of *`condition`* is nonzero, the following statement gets executed, and the statement following the optional **`else`** gets skipped. Otherwise, the following statement gets skipped, and if there's an **`else`** then the statement following the **`else`** gets executed. -*`condition`* expressions that evaluate to non-zero are: +*`condition`* expressions that evaluate to nonzero are: - **`true`** - a non-null pointer, -- any non-zero arithmetic value, or +- any nonzero arithmetic value, or - a class type that defines an unambiguous conversion to an arithmetic, boolean, or pointer type. (For information about conversions, see [Standard Conversions](../cpp/standard-conversions.md).) ## Syntax @@ -69,52 +68,54 @@ This sample code shows several **`if`** statements in use, both with and without using namespace std; -class C -{ - public: - void do_something(){} -}; -void init(C){} -bool is_true() { return true; } -int x = 10; - int main() { - if (is_true()) + int x = 10; + + if (x < 11) { - cout << "b is true!\n"; // executed + cout << "x < 11 is true!\n"; // executed } else { - cout << "b is false!\n"; + cout << "x < 11 is false!\n"; // not executed } // no else statement - if (x == 10) + bool flag = false; + if (flag == true) { - x = 0; + x = 100; // not executed } - C* c; - init(c); - if (c) + int *p = new int(25); + if (p) { - c->do_something(); + cout << *p << "\n"; // outputs 25 } else { - cout << "c is null!\n"; + cout << "p is null!\n"; // executed if memory allocation fails } } ``` +Output: + +```output +x < 11 is true! +25 +``` + ## if statement with an initializer -Starting in C++17, an **`if`** statement may also contain an *`init-statement`* expression that declares and initializes a named variable. Use this form of the if-statement when the variable is only needed within the scope of the if-statement. **Microsoft-specific**: This form is available starting in Visual Studio 2017 version 15.3, and requires at least the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) compiler option. +Starting in C++17, an **`if`** statement might also contain an *`init-statement`* expression that declares and initializes a named variable. Use this form of the if-statement when the variable is only needed within the scope of the if-statement. **Microsoft-specific**: This form is available starting in Visual Studio 2017 version 15.3, and requires at least the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) compiler option. ### Example ```cpp +// Compile with /std:c++17 + #include #include #include @@ -123,28 +124,26 @@ Starting in C++17, an **`if`** statement may also contain an *`init-statement`* using namespace std; -map m; +map m{ {1, "one"}, {2, "two"}, {10,"ten"} }; mutex mx; -bool shared_flag; // guarded by mx -void unsafe_operation() {} +bool shared_flag = true; // guarded by mx +int getValue() { return 42; } int main() { - if (auto it = m.find(10); it != m.end()) { - cout << it->second; - return 0; + cout << it->second << "\n"; } - if (char buf[10]; fgets(buf, 10, stdin)) + if (int x = getValue(); x == 42) { - m[0] += buf; + cout << "x is 42\n"; } if (lock_guard lock(mx); shared_flag) { - unsafe_operation(); + cout << "setting shared_flag to false\n"; shared_flag = false; } @@ -156,31 +155,62 @@ int main() } ``` -## if constexpr statements +Output: + +```Output +ten +x is 42 +setting shared_flag to false +Error! Token must not be a keyword +``` + +## if constexpr statements Starting in C++17, you can use an **`if constexpr`** statement in function templates to make compile-time branching decisions without having to resort to multiple function overloads. **Microsoft-specific**: This form is available starting in Visual Studio 2017 version 15.3, and requires at least the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) compiler option. ### Example -This example shows how you can write a single function that handles parameter unpacking. No zero-parameter overload is needed: +This example shows how you can conditionally compile a template based on the type sent to it: ```cpp -template -void f(T&& t, Rest&&... r) -{ - // handle t - do_something(t); +// Compile with /std:c++17 +#include - // handle r conditionally - if constexpr (sizeof...(r)) +template +auto Show(T t) +{ + //if (std::is_pointer_v) // Show(a) results in compiler error for return *t. Show(b) results in compiler error for return t. + if constexpr (std::is_pointer_v) // This statement goes away for Show(a) { - f(r...); + return *t; } else { - g(r...); + return t; } } + +int main() +{ + int a = 42; + int* pB = &a; + + std::cout << Show(a) << "\n"; // prints "42" + std::cout << Show(pB) << "\n"; // prints "42" +} +``` + +The **`if constexpr`** statement is evaluated at compile time, and the compiler only generates code for the **`if`** branch that matches the type of the argument sent to the function template. If you comment out the **`if constexpr`** statement and uncomment the **`if`** statement, the compiler generates code for both branches. That means you get an error: +- If you call `ShowValue(a);` you get an error on `return *t` because `t` isn't a pointer, even though the **`if`** statement is false and the code is never executed. +- If you call `ShowValue(pB);` you get an error on `return t` because `t` is a pointer, even though the **`if`** statement is true and the code is never executed. + +Using `if constexpr` solves this problem because only the statement that matches the type of the argument sent to the function template is compiled. + +Output: + +```output +42 +42 ``` ## See also diff --git a/docs/cpp/import-export-module.md b/docs/cpp/import-export-module.md index dea4a86503..ae7d37a4fe 100644 --- a/docs/cpp/import-export-module.md +++ b/docs/cpp/import-export-module.md @@ -1,13 +1,13 @@ --- title: "module, import, export" -ms.date: "12/12/2019" +ms.date: 02/13/2025 f1_keywords: ["module_cpp", "import_cpp", "export_cpp"] helpviewer_keywords: ["modules [C++]", "modules [C++], import", "modules [C++], export"] description: Use import and export declarations to access and to publish types and functions defined in the specified module. --- # `module`, `import`, `export` -The **`module`**, **`import`**, and **`export`** declarations are available in C++20 and require the [/experimental:module](../build/reference/experimental-module.md) compiler switch along with [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**). For more information, see [Overview of modules in C++](modules-cpp.md). +The **`module`**, **`import`**, and **`export`** declarations are available in C++20 and require the compiler switch [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later. For more information, see [Overview of modules in C++](modules-cpp.md). ## `module` @@ -19,7 +19,7 @@ module ModuleA; ## `export` -Use an **`export module`** declaration for the module's primary interface file, which must have extension *`.ixx`*: +Use an **`export module`** declaration for the module's primary interface file, which has an extension *`.ixx`* by default. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. ```cpp export module ModuleA; @@ -32,7 +32,7 @@ In an interface file, use the **`export`** modifier on names that are intended t export module ModuleA; -namespace Bar +namespace ModuleA_NS { export int f(); export double d(); @@ -40,33 +40,30 @@ namespace Bar } ``` -Non-exported names are not visible to code that imports the module: +Nonexported names aren't visible to code that imports the module: ```cpp -//MyProgram.cpp - import ModuleA; int main() { - Bar::f(); // OK - Bar::d(); // OK - Bar::internal_f(); // Ill-formed: error C2065: 'internal_f': undeclared identifier + ModuleA_NS::f(); // OK + ModuleA_NS::d(); // OK + ModuleA_NS::internal_f(); // Ill-formed: error C2065: 'internal_f': undeclared identifier } ``` The **`export`** keyword may not appear in a module implementation file. When **`export`** is applied to a namespace name, all names in the namespace are exported. -## import +## `import` -Use an **import** declaration to make a module's names visible in your program. The import declaration must appear after the module declaration and after any #include directives, but before any declarations in the file. +Use an **`import`** declaration to make a module's names visible in your program. The `import` declaration must appear after the `module` declaration and after any `#include` directives, but before any declarations in the file. ```cpp module ModuleA; #include "custom-lib.h" -import std.core; -import std.regex; -import ModuleB; +import std; +import myModule; // begin declarations here: template @@ -76,10 +73,9 @@ class Baz ## Remarks -Both **import** and **module** are treated as keywords only when they appear at the start of a logical line: +Both **`import`** and **`module`** are treated as keywords only when they appear at the start of a logical line: ```cpp - // OK: module ; module module-name @@ -100,7 +96,7 @@ int i; module ; **Microsoft Specific** -In Microsoft C++, the tokens **import** and **module** are always identifiers and never keywords when they are used as arguments to a macro. +In Microsoft C++, the tokens **`import`** and **`module`** are always identifiers and never keywords when they're used as arguments to a macro. ### Example @@ -115,4 +111,5 @@ import // Always an identifier, never a keyword ## See Also -[Overview of modules in C++](modules-cpp.md) +[Overview of modules in C++](modules-cpp.md)\ +[Import the C++ standard library using modules](tutorial-import-stl-named-module.md) \ No newline at end of file diff --git a/docs/cpp/index.yml b/docs/cpp/index.yml index 61c7cf7a41..4ba7817947 100644 --- a/docs/cpp/index.yml +++ b/docs/cpp/index.yml @@ -1,12 +1,13 @@ ### YamlMime:Landing -title: C++ language documentation +title: C++ documentation summary: Learn to use C++ and the C++ standard library. metadata: title: C++ docs - get started, tutorials, reference. description: C++ programming reference for users of Microsoft C++ and Visual Studio. ms.topic: landing-page - ms.date: 05/08/2020 + ms.date: 03/22/2022 + ms.author: twhitney ms.custom: intro-landing-hub # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -33,6 +34,10 @@ landingContent: url: ../build/vscpp-step-1-create.md - text: Create a console calculator in C++ url: ../get-started/tutorial-console-cpp.md + - linkListType: video + links: + - text: "Learn C++ - A general purpose language and library" + url: /shows/cplusplus-language-library - linkListType: learn links: - text: Welcome back to C++ - Modern C++ @@ -72,7 +77,7 @@ landingContent: url: ../build/reference/compiling-a-c-cpp-program.md - text: Linker reference url: ../build/reference/linking.md - - text: Additional build tools + - text: More build tools url: ../build/reference/c-cpp-build-tools.md - text: Errors and warnings url: ../error-messages/compiler-errors-1/c-cpp-build-errors.md diff --git a/docs/cpp/indirection-operator-star.md b/docs/cpp/indirection-operator-star.md index 9cde55e2a5..440b30ef03 100644 --- a/docs/cpp/indirection-operator-star.md +++ b/docs/cpp/indirection-operator-star.md @@ -5,7 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["* operator", "indirection operator", "operators [C++], indirection", "indirection operator [C++], syntax"] ms.assetid: c50309e1-6c02-4184-9fcb-2e13c1f4ac03 --- -# Indirection Operator: * +# Indirection Operator: `*` ## Syntax @@ -15,7 +15,7 @@ ms.assetid: c50309e1-6c02-4184-9fcb-2e13c1f4ac03 ## Remarks -The unary indirection operator (\*) dereferences a pointer; that is, it converts a pointer value to an l-value. The operand of the indirection operator must be a pointer to a type. The result of the indirection expression is the type from which the pointer type is derived. The use of the \* operator in this context is different from its meaning as a binary operator, which is multiplication. +The unary indirection operator (**`*`**) dereferences a pointer; that is, it converts a pointer value to an l-value. The operand of the indirection operator must be a pointer to a type. The result of the indirection expression is the type from which the pointer type is derived. The use of the **`*`** operator in this context is different from its meaning as a binary operator, which is multiplication. If the operand points to a function, the result is a function designator. If it points to a storage location, the result is an l-value designating the storage location. @@ -53,7 +53,7 @@ If the pointer value is invalid, the result is undefined. The following list inc ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
-[Address-of Operator: &](../cpp/address-of-operator-amp.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ +[Address-of Operator: &](../cpp/address-of-operator-amp.md)\ [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) diff --git a/docs/cpp/inheritance-cpp.md b/docs/cpp/inheritance-cpp.md index c024fafdcf..14660d3866 100644 --- a/docs/cpp/inheritance-cpp.md +++ b/docs/cpp/inheritance-cpp.md @@ -1,50 +1,54 @@ --- -description: "Learn more about: Inheritance (C++)" -title: "Inheritance (C++)" +title: "Inheritance (C++)" +description: "Learn more about: Inheritance (C++)" ms.date: "11/04/2016" helpviewer_keywords: ["derived classes [C++]", "derived classes [C++], about derived classes", "classes [C++], derived"] -ms.assetid: 3534ca19-d9ed-4a40-be1b-b921ad0e6956 --- -# Inheritance (C++) +# Inheritance (C++) This section explains how to use derived classes to produce extensible programs. ## Overview -New classes can be derived from existing classes using a mechanism called "inheritance" (see the information beginning in [Single Inheritance](../cpp/single-inheritance.md)). Classes that are used for derivation are called "base classes" of a particular derived class. A derived class is declared using the following syntax: +New classes can be derived from existing classes using a mechanism called "inheritance" (see the information beginning in [Single Inheritance](single-inheritance.md)). Classes that are used for derivation are called "base classes" of a particular derived class. A derived class is declared using the following syntax: ```cpp -class Derived : [virtual] [access-specifier] Base +class DerivedSingleBase : [virtual] [access-specifier] Base { - // member list + // member list }; -class Derived : [virtual] [access-specifier] Base1, - [virtual] [access-specifier] Base2, . . . + +class DerivedMultipleBases : [virtual] [access-specifier] Base1, + [virtual] [access-specifier] Base2, ... { - // member list + // member list }; ``` -After the tag (name) for the class, a colon appears followed by a list of base specifications. The base classes so named must have been declared previously. The base specifications may contain an access specifier, which is one of the keywords **`public`**, **`protected`** or **`private`**. These access specifiers appear before the base class name and apply only to that base class. These specifiers control the derived class's permission to use to members of the base class. See [Member-Access Control](../cpp/member-access-control-cpp.md) for information on access to base class members. If the access specifier is omitted, the access to that base is considered **`private`**. The base specifications may contain the keyword **`virtual`** to indicate virtual inheritance. This keyword may appear before or after the access specifier, if any. If virtual inheritance is used, the base class is referred to as a virtual base class. +After the tag (name) for the class, a colon appears followed by a list of base specifications. The base classes so named must have been declared previously. The base specifications may contain an access specifier, which is one of the keywords [**`public`**](public-cpp.md), [**`protected`**](protected-cpp.md) or [**`private`**](private-cpp.md). These access specifiers appear before the base class name and apply only to that base class. These specifiers control the derived class's permission to use members of the base class. See [Member-Access Control](member-access-control-cpp.md) for information on access to base class members. If the access specifier is omitted, the access to that base is considered **`private`**. The base specifications may contain the keyword [**`virtual`**](virtual-cpp.md) to indicate virtual inheritance. This keyword may appear before or after the access specifier, if any. If virtual inheritance is used, the base class is referred to as a virtual base class. -Multiple base classes can be specified, separated by commas. If a single base class is specified, the inheritance model is [Single inheritance](../cpp/single-inheritance.md). If more than one base class is specified, the inheritance model is called [Multiple inheritance](../cpp/multiple-base-classes.md). +Multiple base classes can be specified, separated by commas. If a single base class is specified, the inheritance model is [Single inheritance](single-inheritance.md). If more than one base class is specified, the inheritance model is called [Multiple inheritance](multiple-base-classes.md). The following topics are included: -- [Single inheritance](../cpp/single-inheritance.md) +- [Single inheritance](single-inheritance.md) + +- [Multiple base classes](multiple-base-classes.md) + +- [Virtual functions](virtual-functions.md) -- [Multiple base classes](../cpp/multiple-base-classes.md) +- [Explicit overrides](explicit-overrides-cpp.md) -- [Virtual functions](../cpp/virtual-functions.md) +- [Abstract classes](abstract-classes-cpp.md) -- [Explicit overrides](../cpp/explicit-overrides-cpp.md) +- [Summary of scope rules](summary-of-scope-rules.md) -- [Abstract classes](../cpp/abstract-classes-cpp.md) +**Microsoft Specific** -- [Summary of scope rules](../cpp/summary-of-scope-rules.md) +The [`__super`](super.md) and [`__interface`](interface.md) keywords are documented in this section. -The [__super](../cpp/super.md) and [__interface](../cpp/interface.md) keywords are documented in this section. +**END Microsoft Specific** ## See also -[C++ Language Reference](../cpp/cpp-language-reference.md) +[C++ Language Reference](cpp-language-reference.md) diff --git a/docs/cpp/initializers.md b/docs/cpp/initializers.md index de37785bbf..48c7f624d1 100644 --- a/docs/cpp/initializers.md +++ b/docs/cpp/initializers.md @@ -3,7 +3,6 @@ title: "Initializers" ms.date: "07/29/2019" description: "How to initialize classes, structs, arrays and fundamental types in C++." helpviewer_keywords: ["arrays [C++], array-element initializers", "aggregate initializers [C++]"] -ms.assetid: ce301ed8-aa1c-47b2-bb39-9f0541b4af85 --- # Initializers @@ -65,7 +64,7 @@ Initializers may take these forms: ## Kinds of initialization -There are several kinds of initialization, which may occur at different points in program execution. Different kinds of initialization are not mutually exclusive—for example, list initialization can trigger value initialization and in other circumstances, it can trigger aggregate initialization. +There are several kinds of initialization, which may occur at different points in program execution. Different kinds of initialization aren't mutually exclusive—for example, list initialization can trigger value initialization and in other circumstances, it can trigger aggregate initialization. ### Zero initialization @@ -115,9 +114,9 @@ MyClass mc1; MyClass* mc3 = new MyClass; ``` -If the class, struct, or union does not have a default constructor, the compiler emits an error. +If the class, struct, or union doesn't have a default constructor, the compiler emits an error. -Scalar variables are default initialized when they are defined with no initialization expression. They have indeterminate values. +Scalar variables are default initialized when they're defined with no initialization expression. They have indeterminate values. ```cpp int i1; @@ -125,17 +124,17 @@ float f; char c; ``` -Arrays are default initialized when they are defined with no initialization expression. When an array is default-initialized, its members are default initialized and have indeterminate values, as in the following example: +Arrays are default initialized when they're defined with no initialization expression. When an array is default-initialized, its members are default initialized and have indeterminate values, as in the following example: ```cpp int int_arr[3]; ``` -If the array members do not have a default constructor, the compiler emits an error. +If the array members don't have a default constructor, the compiler emits an error. #### Default initialization of constant variables -Constant variables must be declared together with an initializer. If they are scalar types they cause a compiler error, and if they are class types that have a default constructor they cause a warning: +Constant variables must be declared together with an initializer. If they're scalar types they cause a compiler error, and if they're class types that have a default constructor they cause a warning: ```cpp class MyClass{}; @@ -181,7 +180,7 @@ Value initialization does the following: - for classes with at least one public constructor, the default constructor is called -- for non-union classes with no declared constructors, the object is zero-initialized and the default constructor is called +- for nonunion classes with no declared constructors, the object is zero-initialized and the default constructor is called - for arrays, every element is value-initialized @@ -250,10 +249,10 @@ int main() { } ``` -Copy initialization cannot invoke explicit constructors. +Copy initialization can't invoke explicit constructors. ```cpp -vector v = 10; // the constructor is explicit; compiler error C2440: cannot convert from 'int' to 'std::vector>' +vector v = 10; // the constructor is explicit; compiler error C2440: can't convert from 'int' to 'std::vector>' regex r = "a.*b"; // the constructor is explicit; same error shared_ptr sp = new int(1729); // the constructor is explicit; same error ``` @@ -423,7 +422,7 @@ myArr3: 8 9 10 0 0 #### Initializing unions and structs -If a union does not have a constructor, you can initialize it with a single value (or with another instance of a union). The value is used to initialize the first non-static field. This is different from struct initialization, in which the first value in the initializer is used to initialize the first field, the second to initialize the second field, and so on. Compare the initialization of unions and structs in the following example: +If a union doesn't have a constructor, you can initialize it with a single value (or with another instance of a union). The value is used to initialize the first non-static field. This is different from struct initialization, in which the first value in the initializer is used to initialize the first field, the second to initialize the second field, and so on. Compare the initialization of unions and structs in the following example: ```cpp struct MyStruct { @@ -489,7 +488,7 @@ int main() } ``` -The only way to initialize a reference with a temporary object is to initialize a constant temporary object. Once initialized, a reference-type variable always points to the same object; it cannot be modified to point to another object. +The only way to initialize a reference with a temporary object is to initialize a constant temporary object. Once initialized, a reference-type variable always points to the same object; it can't be modified to point to another object. Although the syntax can be the same, initialization of reference-type variables and assignment to reference-type variables are semantically different. In the preceding example, the assignments that change `iVar` and `lVar` look similar to the initializations, but have different effects. The initialization specifies the object to which the reference-type variable points; the assignment assigns to the referred-to object through the reference. @@ -521,15 +520,17 @@ Reference-type variables can be declared without initializers only in the follow extern int& iVal; ``` -When initializing a reference-type variable, the compiler uses the decision graph shown in the following figure to select between creating a reference to an object or creating a temporary object to which the reference points. +When initializing a reference-type variable, the compiler uses the decision graph shown in the following figure to select between creating a reference to an object or creating a temporary object to which the reference points: -![Decision graph for initialization of reference types.](../cpp/media/vc38s71.gif "Decision graph for initialization of reference types")
+:::image type="complex" source="../cpp/media/vc38s71.gif" alt-text="Decision graph for initialization of reference types."::: +The decision graph begins with: is the initializer an lvalue of the same type or a type derived from the type of reference? If yes, the reference refers to the object specified in the initializer. If no, the next decision is whether the reference-type variable is a const T reference being initialized and can the initializer be implicitly converted to a T? If yes, the temporary is created and the reference variable becomes a name for that temporary. If no, it's an error. +:::image-end::: Decision graph for initialization of reference types -References to **`volatile`** types (declared as **`volatile`** *typename*& *identifier*) can be initialized with **`volatile`** objects of the same type or with objects that have not been declared as **`volatile`**. They cannot, however, be initialized with **`const`** objects of that type. Similarly, references to **`const`** types (declared as **`const`** *typename*& *identifier*) can be initialized with **`const`** objects of the same type (or anything that has a conversion to that type or with objects that have not been declared as **`const`**). They cannot, however, be initialized with **`volatile`** objects of that type. +References to **`volatile`** types (declared as **`volatile`** *typename*& *identifier*) can be initialized with **`volatile`** objects of the same type or with objects that haven't been declared as **`volatile`**. They can't, however, be initialized with **`const`** objects of that type. Similarly, references to **`const`** types (declared as **`const`** *typename*& *identifier*) can be initialized with **`const`** objects of the same type (or anything that has a conversion to that type or with objects that haven't been declared as **`const`**). They can't, however, be initialized with **`volatile`** objects of that type. -References that are not qualified with either the **`const`** or **`volatile`** keyword can be initialized only with objects declared as neither **`const`** nor **`volatile`**. +References that aren't qualified with either the **`const`** or **`volatile`** keyword can be initialized only with objects declared as neither **`const`** nor **`volatile`**. ### Initialization of external variables -Declarations of automatic, static, and external variables can contain initializers. However, declarations of external variables can contain initializers only if the variables are not declared as **`extern`**. +Declarations of automatic, static, and external variables can contain initializers. However, declarations of external variables can contain initializers only if the variables aren't declared as **`extern`**. diff --git a/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md b/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md index f47974713a..88ddfde83f 100644 --- a/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md +++ b/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md @@ -42,8 +42,9 @@ int main() // Member initialization (in order of declaration): TempData td{ 45978, time(&time_to_set), 28.9, 37.0, 16.7 }; - // Default initialization = {0,0,0,0,0} - TempData td_default{}; + // When there's no constructor, an empty brace initializer does + // value initialization = {0,0,0,0,0} + TempData td_emptyInit{}; // Uninitialized = if used, emits warning C4700 uninitialized local variable TempData td_noInit; @@ -55,7 +56,7 @@ int main() } ``` -When a `class` or `struct` has no constructor, you provide the list elements in the order that the members are declared in the `class`. If the `class` has a constructor, provide the elements in the order of the parameters. If a type has a default constructor, either implicitly or explicitly declared, you can use default brace initialization (with empty braces). For example, the following `class` may be initialized by using both default and non-default brace initialization: +When a `class` or `struct` has no constructor, you provide the list elements in the order that the members are declared in the `class`. If the `class` has a constructor, provide the elements in the order of the parameters. If a type has a default constructor, either implicitly or explicitly declared, you can use brace initialization with empty braces to invoke it. For example, the following `class` may be initialized by using both empty and non-empty brace initialization: ```cpp #include @@ -106,7 +107,7 @@ int main() } ``` -If the default constructor is explicitly declared but marked as deleted, default brace initialization can't be used: +If the default constructor is explicitly declared but marked as deleted, empty brace initialization can't be used: ```cpp class class_f { diff --git a/docs/cpp/inline-functions-cpp.md b/docs/cpp/inline-functions-cpp.md index 91152ef657..edfd41def2 100644 --- a/docs/cpp/inline-functions-cpp.md +++ b/docs/cpp/inline-functions-cpp.md @@ -1,84 +1,91 @@ --- title: "Inline Functions (C++)" description: "The C++ inline keyword can be used to suggest inline functions to the compiler." -ms.date: "10/09/2018" +ms.date: 12/07/2023 f1_keywords: ["__forceinline_cpp", "__inline_cpp", "inline_cpp", "__inline", "_inline", "__forceinline", "_forceinline"] helpviewer_keywords: ["inline functions [C++], class members"] -ms.assetid: 355f120c-2847-4608-ac04-8dda18ffe10c --- -# Inline Functions (C++) +# Inline functions (C++) -A function defined in the body of a class declaration is an inline function. +The **`inline`** keyword suggests that the compiler substitute the code within the function definition in place of each call to that function. + +In theory, using inline functions can make your program faster because they eliminate the overhead associated with function calls. Calling a function requires pushing the return address on the stack, pushing arguments onto the stack, jumping to the function body, and then executing a return instruction when the function finishes. This process is eliminated by inlining the function. The compiler also has different opportunities to optimize functions expanded inline versus those that aren't. A tradeoff of inline functions is that the overall size of your program can increase. + +Inline code substitution is done at the compiler's discretion. For example, the compiler won't inline a function if its address is taken or if the compiler decides it's too large. + +A function defined in the body of a class declaration is implicitly an inline function. ## Example -In the following class declaration, the `Account` constructor is an inline function. The member functions `GetBalance`, `Deposit`, and `Withdraw` aren't specified as **`inline`** but can be implemented as inline functions. +In the following class declaration, the `Account` constructor is an inline function because it is defined in the body of the class declaration. The member functions `GetBalance`, `Deposit`, and `Withdraw` are specified `inline` in their definitions. The `inline` keyword is optional in the function declarations in the class declaration. ```cpp -// Inline_Member_Functions.cpp +// account.h class Account { public: - Account(double initial_balance) { balance = initial_balance; } - double GetBalance(); - double Deposit( double Amount ); - double Withdraw( double Amount ); + Account(double initial_balance) + { + balance = initial_balance; + } + + double GetBalance() const; + double Deposit(double amount); + double Withdraw(double amount); + private: double balance; }; -inline double Account::GetBalance() +inline double Account::GetBalance() const { return balance; } -inline double Account::Deposit( double Amount ) +inline double Account::Deposit(double amount) { - return ( balance += Amount ); + balance += amount; + return balance; } -inline double Account::Withdraw( double Amount ) -{ - return ( balance -= Amount ); -} -int main() +inline double Account::Withdraw(double amount) { + balance -= amount; + return balance; } ``` > [!NOTE] > In the class declaration, the functions were declared without the **`inline`** keyword. The **`inline`** keyword can be specified in the class declaration; the result is the same. -A given inline member function must be declared the same way in every compilation unit. This constraint causes inline functions to behave as if they were instantiated functions. Additionally, there must be exactly one definition of an inline function. +A given inline member function must be declared the same way in every compilation unit. There must be exactly one definition of an inline function. -A class member function defaults to external linkage unless a definition for that function contains the **`inline`** specifier. The preceding example shows that you don't have to declare these functions explicitly with the **`inline`** specifier. Using **`inline`** in the function definition causes it to be an inline function. However, it's not allowed to redeclare a function as **`inline`** after a call to that function. +A class member function defaults to external linkage unless a definition for that function contains the **`inline`** specifier. The preceding example shows that you don't have to declare these functions explicitly with the **`inline`** specifier. Using **`inline`** in the function definition suggests to the compiler that it be treated as an inline function. However, you can't redeclare a function as **`inline`** after a call to that function. ## `inline`, `__inline`, and `__forceinline` -The **`inline`** and **`__inline`** specifiers instruct the compiler to insert a copy of the function body into each place the function is called. +The **`inline`** and **`__inline`** specifiers suggest to the compiler that it insert a copy of the function body into each place the function is called. -The insertion, called *inline expansion* or *inlining*, occurs only if the compiler's cost-benefit analysis shows it's worthwhile. Inline expansion minimizes the function-call overhead at the potential cost of larger code size. +The insertion, called *inline expansion* or *inlining*, occurs only if the compiler's own cost-benefit analysis shows it's worthwhile. Inline expansion minimizes the function-call overhead at the potential cost of larger code size. The **`__forceinline`** keyword overrides the cost-benefit analysis and relies on the judgment of the programmer instead. Exercise caution when using **`__forceinline`**. Indiscriminate use of **`__forceinline`** can result in larger code with only marginal performance gains or, in some cases, even performance losses (because of the increased paging of a larger executable, for example). -Using inline functions can make your program faster because they eliminate the overhead associated with function calls. Functions expanded inline are subject to code optimizations not available to normal functions. +The compiler treats the inline expansion options and keywords as suggestions. There's no guarantee that functions will be inlined. You can't force the compiler to inline a particular function, even with the **`__forceinline`** keyword. When you compile with **`/clr`**, the compiler won't inline a function if there are security attributes applied to the function. -The compiler treats the inline expansion options and keywords as suggestions. There's no guarantee that functions will be inlined. You can't force the compiler to inline a particular function, even with the **`__forceinline`** keyword. When compiling with **`/clr`**, the compiler won't inline a function if there are security attributes applied to the function. +For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`** and **`__forceinline`**, respectively, unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. -The **`inline`** keyword is available only in C++. The **`__inline`** and **`__forceinline`** keywords are available in both C and C++. For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`**, and **`__forceinline`** unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. - -The **`inline`** keyword tells the compiler that inline expansion is preferred. However, the compiler can create a separate instance of the function (instantiate) and create standard calling linkages instead of inserting the code inline. Two cases where this behavior can happen are: +The **`inline`** keyword tells the compiler that inline expansion is preferred. However, the compiler can ignore it. Two cases where this behavior can happen are: - Recursive functions. - - Functions that are referred to through a pointer elsewhere in the translation unit. -These reasons may interfere with inlining, *as may others*, at the discretion of the compiler; you shouldn't depend on the **`inline`** specifier to cause a function to be inlined. +These reasons may interfere with inlining, *as may others*, as determined by the compiler. Don't depend on the **`inline`** specifier to cause a function to be inlined. -As with normal functions, there's no defined order for argument evaluation in an inline function. In fact, it could be different from the argument evaluation order when passed using the normal function-call protocol. +Rather than expand an inline function defined in a header file, the compiler may create it as a callable function in more than one translation unit. The compiler marks the generated function for the linker to prevent one-definition-rule (ODR) violations. -The [`/Ob`](../build/reference/ob-inline-function-expansion.md) compiler optimization option helps to determine whether inline function expansion actually occurs. +As with normal functions, there's no defined order for argument evaluation in an inline function. In fact, it could be different from the argument evaluation order when passed using the normal function-call protocol. +Use the [`/Ob`](../build/reference/ob-inline-function-expansion.md) compiler optimization option to influence whether inline function expansion actually occurs.\ [`/LTCG`](../build/reference/ltcg-link-time-code-generation.md) does cross-module inlining whether it's requested in source code or not. ### Example 1 @@ -86,10 +93,9 @@ The [`/Ob`](../build/reference/ob-inline-function-expansion.md) compiler optimiz ```cpp // inline_keyword1.cpp // compile with: /c -inline int max( int a , int b ) { - if( a > b ) - return a; - return b; +inline int max(int a, int b) +{ + return a < b ? b : a; } ``` @@ -101,13 +107,14 @@ A class's member functions can be declared inline, either by using the **`inline // inline_keyword2.cpp // compile with: /EHsc /c #include -using namespace std; -class MyClass { +class MyClass +{ public: - void print() { cout << i << ' '; } // Implicitly inline + void print() { std::cout << i; } // Implicitly inline + private: - int i; + int i; }; ``` @@ -115,28 +122,20 @@ private: The **`__inline`** keyword is equivalent to **`inline`**. -Even with **`__forceinline`**, the compiler can't inline code in all circumstances. The compiler can't inline a function if: +Even with **`__forceinline`**, the compiler can't inline a function if: - The function or its caller is compiled with **`/Ob0`** (the default option for debug builds). - - The function and the caller use different types of exception handling (C++ exception handling in one, structured exception handling in the other). - - The function has a variable argument list. - - The function uses inline assembly, unless compiled with **`/Ox`**, **`/O1`**, or **`/O2`**. - - The function is recursive and doesn't have **`#pragma inline_recursion(on)`** set. With the pragma, recursive functions are inlined to a default depth of 16 calls. To reduce the inlining depth, use [`inline_depth`](../preprocessor/inline-depth.md) pragma. - - The function is virtual and is called virtually. Direct calls to virtual functions can be inlined. - - The program takes the address of the function and the call is made via the pointer to the function. Direct calls to functions that have had their address taken can be inlined. - - The function is also marked with the [`naked`](../cpp/naked-cpp.md) [`__declspec`](../cpp/declspec.md) modifier. If the compiler can't inline a function declared with **`__forceinline`**, it generates a level 1 warning, except when: - The function is compiled by using /Od or /Ob0. No inlining is expected in these cases. - - The function is defined externally, in an included library or another translation unit, or is a virtual call target or indirect call target. The compiler can't identify non-inlined code that it can't find in the current translation unit. Recursive functions can be replaced with inline code to a depth specified by the [`inline_depth`](../preprocessor/inline-depth.md) pragma, up to a maximum of 16 calls. After that depth, recursive function calls are treated as calls to an instance of the function. The depth to which recursive functions are examined by the inline heuristic can't exceed 16. The [`inline_recursion`](../preprocessor/inline-recursion.md) pragma controls the inline expansion of a function currently under expansion. See the [Inline-Function Expansion](../build/reference/ob-inline-function-expansion.md) (/Ob) compiler option for related information. @@ -146,24 +145,25 @@ Recursive functions can be replaced with inline code to a depth specified by the For more information on using the **`inline`** specifier, see: - [Inline Class Member Functions](../cpp/inline-functions-cpp.md) - - [Defining Inline C++ Functions with dllexport and dllimport](../cpp/defining-inline-cpp-functions-with-dllexport-and-dllimport.md) ## When to use inline functions -Inline functions are best used for small functions such as accessing private data members. The main purpose of these one- or two-line "accessor" functions is to return state information about objects. Short functions are sensitive to the overhead of function calls. Longer functions spend proportionately less time in the calling and returning sequence and benefit less from inlining. +Inline functions are best used for small functions, such as those that provide access to data members. Short functions are sensitive to the overhead of function calls. Longer functions spend proportionately less time in the calling and returning sequence and benefit less from inlining. A `Point` class can be defined as follows: ```cpp // when_to_use_inline_functions.cpp +// compile with: /c class Point { public: - // Define "accessor" functions as - // reference types. + // Define "accessor" functions + // as reference types. unsigned& x(); unsigned& y(); + private: unsigned _x; unsigned _y; @@ -173,86 +173,103 @@ inline unsigned& Point::x() { return _x; } + inline unsigned& Point::y() { return _y; } -int main() -{ -} ``` Assuming coordinate manipulation is a relatively common operation in a client of such a class, specifying the two accessor functions (`x` and `y` in the preceding example) as **`inline`** typically saves the overhead on: - Function calls (including parameter passing and placing the object's address on the stack) - - Preservation of caller's stack frame - - New stack frame setup - - Return-value communication - - Restoring the old stack frame - - Return ## Inline functions vs. macros -Inline functions are similar to macros, because the function code is expanded at the point of the call at compile time. However, inline functions are parsed by the compiler, and macros are expanded by the preprocessor. As a result, there are several important differences: +A macro has some things in common with an `inline` function. But there are important differences. Consider the following example: -- Inline functions follow all the protocols of type safety enforced on normal functions. - -- Inline functions are specified using the same syntax as any other function except that they include the **`inline`** keyword in the function declaration. - -- Expressions passed as arguments to inline functions are evaluated once. In some cases, expressions passed as arguments to macros can be evaluated more than once. +```cpp +#include -The following example shows a macro that converts lowercase letters to uppercase: +#define mult1(a, b) a * b +#define mult2(a, b) (a) * (b) +#define mult3(a, b) ((a) * (b)) -```cpp -// inline_functions_macro.c -#include -#include +inline int multiply(int a, int b) +{ + return a * b; +} -#define toupper(a) ((a) >= 'a' && ((a) <= 'z') ? ((a)-('a'-'A')):(a)) +int main() +{ + std::cout << (48 / mult1(2 + 2, 3 + 3)) << std::endl; // outputs 33 + std::cout << (48 / mult2(2 + 2, 3 + 3)) << std::endl; // outputs 72 + std::cout << (48 / mult3(2 + 2, 3 + 3)) << std::endl; // outputs 2 + std::cout << (48 / multiply(2 + 2, 3 + 3)) << std::endl; // outputs 2 -int main() { - char ch; - printf_s("Enter a character: "); - ch = toupper( getc(stdin) ); - printf_s( "%c", ch ); + std::cout << mult3(2, 2.2) << std::endl; // no warning + std::cout << multiply(2, 2.2); // Warning C4244 'argument': conversion from 'double' to 'int', possible loss of data } -// Sample Input: xyz -// Sample Output: Z ``` -The intent of the expression `toupper(getc(stdin))` is that a character should be read from the console device (`stdin`) and, if necessary, converted to uppercase. +```Output +33 +72 +2 +2 +4.4 +4 +``` -Because of the implementation of the macro, `getc` is executed once to determine whether the character is greater than or equal to "a," and once to determine whether it's less than or equal to "z." If it is in that range, `getc` is executed again to convert the character to uppercase. It means the program waits for two or three characters when, ideally, it should wait for only one. +Here are some of the differences between the macro and the inline function: -Inline functions remedy the problem previously described: +- Macros are always expanded inline. However, an inline function is only inlined when the compiler determines it is the optimal thing to do. +- The macro may result in unexpected behavior, which can lead to subtle bugs. For example, the expression `mult1(2 + 2, 3 + 3)` expands to `2 + 2 * 3 + 3` which evaluates to 11, but the expected result is 24. A seemingly valid fix is to add parentheses around both arguments of the function macro, resulting in `#define mult2(a, b) (a) * (b)`, which will solve the issue at hand but can still cause surprising behavior when part of a larger expression. That was demonstrated in the preceding example, and the problem could be addressed by defining the macro as such `#define mult3(a, b) ((a) * (b))`. +- An inline function is subject to semantic processing by the compiler, whereas the preprocessor expands macros without that same benefit. Macros aren't type-safe, whereas functions are. +- Expressions passed as arguments to inline functions are evaluated once. In some cases, expressions passed as arguments to macros can be evaluated more than once. For example, consider the following: ```cpp -// inline_functions_inline.cpp -#include -#include +#include + +#define sqr(a) ((a) * (a)) + +int increment(int& number) +{ + return number++; +} -inline char toupper( char a ) { - return ((a >= 'a' && a <= 'z') ? a-('a'-'A') : a ); +inline int square(int a) +{ + return a * a; } -int main() { - printf_s("Enter a character: "); - char ch = toupper( getc(stdin) ); - printf_s( "%c", ch ); +int main() +{ + int c = 5; + std::cout << sqr(increment(c)) << std::endl; // outputs 30 + std::cout << c << std::endl; // outputs 7 + + c = 5; + std::cout << square(increment(c)) << std::endl; // outputs 25 + std::cout << c; // outputs 6 } ``` ```Output -Sample Input: a -Sample Output: A +30 +7 +25 +6 ``` +In this example, the function `increment` is called twice as the expression `sqr(increment(c))` expands to `((increment(c)) * (increment(c)))`. This caused the second invocation of `increment` to return 6, hence the expression evaluates to 30. Any expression that contains side effects may affect the result when used in a macro, examine the fully expanded macro to check if the behavior is intended. Instead, if the inline function `square` was used, the function `increment` would only be called once and the correct result of 25 will be obtained. + ## See also -[`noinline`](../cpp/noinline.md)
+[`noinline`](../cpp/noinline.md)\ [`auto_inline`](../preprocessor/auto-inline.md) diff --git a/docs/cpp/keywords-cpp.md b/docs/cpp/keywords-cpp.md index f6d042ba48..0bb5fff6c0 100644 --- a/docs/cpp/keywords-cpp.md +++ b/docs/cpp/keywords-cpp.md @@ -4,7 +4,6 @@ description: "Lists the C++ standard language keywords, Microsoft-specific keywo ms.custom: "index-page" ms.date: 07/25/2020 helpviewer_keywords: ["keywords [C++]"] -ms.assetid: d7ca94a8-f785-41ce-9f73-d3c4fd508489 --- # Keywords (C++) @@ -14,7 +13,7 @@ Keywords are predefined reserved identifiers that have special meanings. They ca :::row::: :::column::: - [`alignas`](align-cpp.md)\ + [`alignas`](alignas-specifier.md)\ [`alignof`](alignof-operator.md)\ [`and`](logical-and-operator-amp-amp.md) b\ [`and_eq`](assignment-operators.md) b\ @@ -79,7 +78,7 @@ Keywords are predefined reserved identifiers that have special meanings. They ca [`private`](private-cpp.md)\ [`protected`](protected-cpp.md)\ [`public`](public-cpp.md)\ - [`register`](storage-classes-cpp.md#register) + [`register`](storage-classes-cpp.md#register)\ [`reinterpret_cast`](reinterpret-cast-operator.md)\ **`requires`** c\ [`return`](return-statement-cpp.md)\ @@ -287,5 +286,5 @@ These identifiers are extended attributes for the **`__declspec`** modifier. The ## See also -[Lexical conventions](lexical-conventions.md)
+[Lexical conventions](lexical-conventions.md)\ [C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md) diff --git a/docs/cpp/lambda-expressions-in-cpp.md b/docs/cpp/lambda-expressions-in-cpp.md index 3d2bfbae23..74d9b2a76a 100644 --- a/docs/cpp/lambda-expressions-in-cpp.md +++ b/docs/cpp/lambda-expressions-in-cpp.md @@ -1,9 +1,8 @@ --- description: "Learn more about: Lambda Expressions in C++" title: "Lambda expressions in C++" -ms.date: 07/13/2021 +ms.date: 01/30/2023 helpviewer_keywords: ["lambda expressions [C++]", "lambda expressions [C++], overview", "lambda expressions [C++], vs. function objects"] -ms.assetid: 713c7638-92be-4ade-ab22-fa33417073bf --- # Lambda expressions in C++ @@ -17,7 +16,7 @@ In C++11 and later, a lambda expression—often called a *lambda*—is a conveni ## Parts of a lambda expression -The ISO C++ Standard shows a simple lambda that is passed as the third argument to the `std::sort()` function: +Here is a simple lambda that is passed as the third argument to the `std::sort()` function: ```cpp #include @@ -33,9 +32,11 @@ void abssort(float* x, unsigned n) { } ``` -This illustration shows the parts of a lambda: +This illustration shows the parts of lambda syntax: -![An illustration of the structural elements of a lambda expression.](../cpp/media/lambdaexpsyntax.png "Structural elements of a lambda expression") +:::image type="complex" source="../cpp/media/lambdaexpsyntax.png" alt-text="Diagram that identifies the various parts of a lambda expression."::: +The lambda expression example is [=]() mutable throw() -> int { return x+y; } The [=] is the capture clause; also known as the lambda-introducer in the C++ specification. The parenthesis are for the parameter list. The mutable keyword is optional. throw() is the optional exception specification. -> int is the optional trailing return type. The lambda body consists of the statement inside the curly braces, or return x+y; These are explained in more detail following the image. +:::image-end::: 1. *capture clause* (Also known as the *lambda-introducer* in the C++ specification.) @@ -61,9 +62,7 @@ You can use a capture-default mode to indicate how to capture any outside variab [&total, factor] [factor, &total] [&, factor] -[factor, &] [=, &total] -[&total, =] ``` Only variables that are mentioned in the lambda body are captured when a capture-default is used. @@ -106,9 +105,9 @@ When you use the capture clause, we recommend that you keep these points in mind - Reference captures introduce a lifetime dependency, but value captures have no lifetime dependencies. It's especially important when the lambda runs asynchronously. If you capture a local by reference in an async lambda, that local could easily be gone by the time the lambda runs. Your code could cause an access violation at run time. -### Generalized capture (C++ 14) +### Generalized capture (C++14) -In C++14, you can introduce and initialize new variables in the capture clause, without the need to have those variables exist in the lambda function’s enclosing scope. The initialization can be expressed as any arbitrary expression; the type of the new variable is deduced from the type produced by the expression. This feature lets you capture move-only variables (such as `std::unique_ptr`) from the surrounding scope and use them in a lambda. +In C++14, you can introduce and initialize new variables in the capture clause, without the need to have those variables exist in the lambda function's enclosing scope. The initialization can be expressed as any arbitrary expression; the type of the new variable is deduced from the type produced by the expression. This feature lets you capture move-only variables (such as `std::unique_ptr`) from the surrounding scope and use them in a lambda. ```cpp pNums = make_unique>(nums); diff --git a/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md b/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md index 9fb7c08ec2..ca0ac901ca 100644 --- a/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md +++ b/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: Left shift and right shift operators ('<<' and '>>')" -title: "Left shift and right shift operators ('<<' and '>>')" +description: "Learn more about: Left shift and right shift operators: << and >>" +title: "Left shift and right shift operators: << and >>" ms.date: 12/09/2021 f1_keywords: ["<<", ">>"] helpviewer_keywords: ["<< operator [C++], with specific objects", "left shift operators [C++]", "right shift operators [C++]", "bitwise-shift operators [C++]", ">> operator", "shift operators [C++]", "operators [C++], shift"] -ms.assetid: 25fa0cbb-5fdd-4657-8745-b35f7d8f1606 --- -# Left shift and right shift operators (`<<` and `>>`) +# Left shift and right shift operators: `<<` and `>>` The bitwise shift operators are the right-shift operator (**`>>`**), which moves the bits of an integer or enumeration type expression to the right, and the left-shift operator (**`<<`**), which moves the bits to the left. 1 ## Syntax *`shift-expression`*:\ -&emsp *`additive-expression`*\ -&emsp *`shift-expression`* **`<<`** *`additive-expression`*\ -&emsp *`shift-expression`* **`>>`** *`additive-expression`* + *`additive-expression`*\ + *`shift-expression`* **`<<`** *`additive-expression`*\ + *`shift-expression`* **`>>`** *`additive-expression`* ## Remarks @@ -218,5 +217,5 @@ The value of `E1 >> E2` is `E1` right-shifted `E2` bit positions. If `E1` has an ## See also -[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)
+[Expressions with binary operators](../cpp/expressions-with-binary-operators.md)\ [C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md) diff --git a/docs/cpp/logical-negation-operator-exclpt.md b/docs/cpp/logical-negation-operator-exclpt.md index 812624506e..359a0ebbf4 100644 --- a/docs/cpp/logical-negation-operator-exclpt.md +++ b/docs/cpp/logical-negation-operator-exclpt.md @@ -6,7 +6,7 @@ f1_keywords: ["!"] helpviewer_keywords: ["! operator", "NOT operator", "logical negation"] ms.assetid: 650add9f-a7bc-426c-b01d-5fc6a81c8b62 --- -# Logical negation operator: ! +# Logical negation operator: `!` ## Syntax @@ -39,6 +39,6 @@ int main() { ## See also -[Expressions with unary operators](../cpp/expressions-with-unary-operators.md)
-[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
-[Unary arithmetic operators](../c-language/unary-arithmetic-operators.md)
+[Expressions with unary operators](../cpp/expressions-with-unary-operators.md)\ +[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ +[Unary arithmetic operators](../c-language/unary-arithmetic-operators.md) diff --git a/docs/cpp/logical-or-operator-pipe-pipe.md b/docs/cpp/logical-or-operator-pipe-pipe.md index 4973a31400..b5a178d585 100644 --- a/docs/cpp/logical-or-operator-pipe-pipe.md +++ b/docs/cpp/logical-or-operator-pipe-pipe.md @@ -1,12 +1,12 @@ --- -title: "Logical OR operator: ||" +title: "Logical OR operator: ||" description: "The C++ standard language logical OR operator syntax and use." ms.date: 07/23/2020 f1_keywords: ["||", "or_cpp"] helpviewer_keywords: ["OR operator [C++], logical", "|| operator", "OR operator", "logical OR operator"] ms.assetid: 31837c99-2655-4bf3-8ded-f13b7a9dc533 --- -# Logical OR operator: || +# Logical OR operator: `||` ## Syntax @@ -28,7 +28,7 @@ printf( "%d" , (x == w || x == y || x == z) ); In the above example, if `x` is equal to either `w`, `y`, or `z`, the second argument to the `printf` function evaluates to **`true`**, which is then promoted to an integer, and the value 1 is printed. Otherwise, it evaluates to **`false`** and the value 0 is printed. As soon as one of the conditions evaluates to **`true`**, evaluation stops. -## Operator keyword for || +## Operator keyword for `||` C++ specifies **`or`** as an alternative spelling for **`||`**. In C, the alternative spelling is provided as a macro in the \ header. In C++, the alternative spelling is a keyword; use of \ or the C++ equivalent \ is deprecated. In Microsoft C++, the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is required to enable the alternative spelling. @@ -54,5 +54,5 @@ int main() { ## See also -[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)\ [C logical operators](../c-language/c-logical-operators.md) diff --git a/docs/cpp/lvalues-and-rvalues-visual-cpp.md b/docs/cpp/lvalues-and-rvalues-visual-cpp.md index c4dbc9e284..0fb47aa4e2 100644 --- a/docs/cpp/lvalues-and-rvalues-visual-cpp.md +++ b/docs/cpp/lvalues-and-rvalues-visual-cpp.md @@ -3,7 +3,6 @@ description: "Learn more about: Lvalues and Rvalues (C++)" title: "Value Categories: Lvalues and Rvalues (C++)" ms.date: "05/07/2019" helpviewer_keywords: ["R-values [C++]", "L-values [C++]"] -ms.assetid: a8843344-cccc-40be-b701-b71f7b5cdcaf --- # Lvalues and Rvalues (C++) @@ -14,16 +13,19 @@ The C++17 standard defines expression value categories as follows: - A *glvalue* is an expression whose evaluation determines the identity of an object, bit-field, or function. - A *prvalue* is an expression whose evaluation initializes an object or a bit-field, or computes the value of the operand of an operator, as specified by the context in which it appears. - An *xvalue* is a glvalue that denotes an object or bit-field whose resources can be reused (usually because it is near the end of its lifetime). Example: Certain kinds of expressions involving rvalue references (8.3.2) yield xvalues, such as a call to a function whose return type is an rvalue reference or a cast to an rvalue reference type. -- An *lvalue* is a glvalue that is not an xvalue. +- An *lvalue* is a glvalue that isn't an xvalue. - An *rvalue* is a prvalue or an xvalue. The following diagram illustrates the relationships between the categories: -![C++ expression value categories.](media/value_categories.png "C++ expression value categories") +:::image type="complex" source="media/value_categories.png" alt-text="Diagram of C++ expression value categories."::: +The diagram begins with a box labeled expression, which has two children: glvalue and rvalue. glvalue has two children: lvalue and xvalue. rvalue has two children: prvalue and xvalue; xvalue is also a child of glvalue. +:::image-end::: + An lvalue has an address that your program can access. Examples of lvalue expressions include variable names, including **`const`** variables, array elements, function calls that return an lvalue reference, bit-fields, unions, and class members. -A prvalue expression has no address that is accessible by your program. Examples of prvalue expressions include literals, function calls that return a non-reference type, and temporary objects that are created during expression evaluation but accessible only by the compiler. +A prvalue expression has no address that is accessible by your program. Examples of prvalue expressions include literals, function calls that return a nonreference type, and temporary objects that are created during expression evaluation but accessible only by the compiler. An xvalue expression has an address that no longer accessible by your program but can be used to initialize an rvalue reference, which provides access to the expression. Examples include function calls that return an rvalue reference, and the array subscript, member and pointer to member expressions where the array or object is an rvalue reference. diff --git a/docs/cpp/m64.md b/docs/cpp/m64.md index 74c415036c..66800090f6 100644 --- a/docs/cpp/m64.md +++ b/docs/cpp/m64.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: __m64" title: "__m64" +description: "Learn more about: __m64" ms.date: "11/04/2016" f1_keywords: ["__m64_cpp"] helpviewer_keywords: ["__m64 keyword [C++]"] -ms.assetid: df0410e8-67c9-4954-88c8-fe2653575252 --- -# __m64 +# `__m64` **Microsoft Specific** @@ -15,9 +14,10 @@ The **`__m64`** data type is for use with the MMX and 3DNow! intrinsics, and is ```cpp // data_types__m64.cpp #include + int main() { - __m64 x; + __m64 x; } ``` @@ -25,14 +25,14 @@ int main() You should not access the **`__m64`** fields directly. You can, however, see these types in the debugger. A variable of type **`__m64`** maps to the MM[0-7] registers. -Variables of type **_m64** are automatically aligned on 8-byte boundaries. +Variables of type **`__m64`** are automatically aligned on 8-byte boundaries. -The **`__m64`** data type is not supported on x64 processors. Applications that use __m64 as part of MMX intrinsics must be rewritten to use equivalent SSE and SSE2 intrinsics. +The **`__m64`** data type is not supported on x64 processors. Applications that use **`__m64`** as part of MMX intrinsics must be rewritten to use equivalent SSE and SSE2 intrinsics. **END Microsoft Specific** ## See also -[Keywords](../cpp/keywords-cpp.md)
-[Built-in types](../cpp/fundamental-types-cpp.md)
-[Data Type Ranges](../cpp/data-type-ranges.md) +[Keywords](keywords-cpp.md)\ +[Built-in types](fundamental-types-cpp.md)\ +[Data Type Ranges](data-type-ranges.md) diff --git a/docs/cpp/main-function-command-line-args.md b/docs/cpp/main-function-command-line-args.md index 78025e9c9c..ac291e1374 100644 --- a/docs/cpp/main-function-command-line-args.md +++ b/docs/cpp/main-function-command-line-args.md @@ -40,7 +40,7 @@ An array of null-terminated strings representing command-line arguments entered For information on how to suppress command-line processing, see [Customize C++ command-line processing](#customize). > [!NOTE] -> By convention, `argv[0]` is the filename of the program. However, on Windows it's possible to spawn a process by using [`CreateProcess`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew). If you use both the first and second arguments (*`lpApplicationName`* and *`lpCommandLine`*), `argv[0]` may not be the executable name. You can use [`GetModuleFileName`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name, and its fully-qualified path. +> By convention, `argv[0]` is the filename of the program. However, on Windows it's possible to spawn a process by using [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). If you use both the first and second arguments (*`lpApplicationName`* and *`lpCommandLine`*), `argv[0]` may not be the executable name. You can use [`GetModuleFileName`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name, and its fully-qualified path. ## Microsoft-specific extensions @@ -169,7 +169,7 @@ Command-line arguments are handled by an internal routine in the runtime startup For more information on runtime startup linker options, see [Link options](../c-runtime-library/link-options.md). -## Customize C++ command-line processing +## Customize C++ command-line processing If your program doesn't take command-line arguments, you can suppress the command-line processing routine to save a small amount of space. To suppress its use, include the *`noarg.obj`* file (for both `main` and `wmain`) in your **`/link`** compiler options or your **`LINK`** command line. diff --git a/docs/cpp/media/vc38ru1.gif b/docs/cpp/media/vc38ru1.gif deleted file mode 100644 index 75a4b731c7..0000000000 Binary files a/docs/cpp/media/vc38ru1.gif and /dev/null differ diff --git a/docs/cpp/member-access-control-cpp.md b/docs/cpp/member-access-control-cpp.md index 2f7a74fd60..27f8ab7b17 100644 --- a/docs/cpp/member-access-control-cpp.md +++ b/docs/cpp/member-access-control-cpp.md @@ -228,9 +228,11 @@ In the preceding example, calling the virtual function `GetState` using a pointe ## Access control with multiple inheritance -In multiple-inheritance lattices involving virtual base classes, a given name can be reached through more than one path. Because different access control can be applied along these different paths, the compiler chooses the path that gives the most access. See the following figure. +In multiple-inheritance lattices involving virtual base classes, a given name can be reached through more than one path. Because different access control can be applied along these different paths, the compiler chooses the path that gives the most access. See the following figure: -![Diagram showing access along the paths of an inheritance graph.](../cpp/media/vc38v91.gif "Access along paths of an inheritance graph")
+:::image type="complex" source="../cpp/media/vc38v91.gif" alt-text="Diagram showing access along the paths of an inheritance graph."::: +The diagram shows the following inheritance hierarchy: class VBase is the base class. Class LeftPath inherits from VBase using virtual private VBase. class RightPath also inherits from VBase but using virtual public VBase. Finally, class Derived inherits from both class LeftPath and class RightPath using public LeftPath, public RightPath. +:::image-end::: Access along paths of an inheritance graph In the figure, a name declared in class `VBase` is always reached through class `RightPath`. The right path is more accessible because `RightPath` declares `VBase` as a **`public`** base class, while `LeftPath` declares `VBase` as **`private`**. diff --git a/docs/cpp/member-function-templates.md b/docs/cpp/member-function-templates.md index 7ae5206125..6ce35e319d 100644 --- a/docs/cpp/member-function-templates.md +++ b/docs/cpp/member-function-templates.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: Member Function Templates" -title: "Member Function Templates" -ms.date: "11/04/2016" +description: "Learn more about: Member function templates" +title: "Member function templates" +ms.date: 09/27/2022 helpviewer_keywords: ["function templates, member functions"] ms.assetid: 83d51835-6a27-40ed-997c-7d90dc9182d8 --- -# Member Function Templates +# Member function templates -The term member template refers to both member function templates and nested class templates. Member function templates are template functions that are members of a class or class template. +The term member template refers to both member function templates and nested class templates. Member function templates are function templates that are members of a class or class template. -Member functions can be function templates in several contexts. All functions of class templates are generic but are not referred to as member templates or member function templates. If these member functions take their own template arguments, they are considered to be member function templates. +Member functions can be function templates in several contexts. All functions of class templates are generic but aren't referred to as member templates or member function templates. If these member functions take their own template arguments, they're considered to be member function templates. ## Example: Declare member function templates -Member function templates of nontemplate or template classes are declared as function templates with their template parameters. +Member function templates of non-template classes or class templates are declared as function templates with their template parameters. ```cpp // member_function_templates.cpp @@ -30,9 +30,9 @@ int main() } ``` -## Example: Member function template of template class +## Example: Member function template of a class template -The following example shows a member function template of a template class. +The following example shows a member function template of a class template. ```cpp // member_function_templates2.cpp @@ -75,9 +75,9 @@ int main() ## Example: Templated user-defined conversion -Local classes are not allowed to have member templates. +Local classes aren't allowed to have member templates. -Member template functions cannot be virtual functions and cannot override virtual functions from a base class when they are declared with the same name as a base class virtual function. +Member function templates can't be virtual functions. And, they can't override virtual functions from a base class when they're declared with the same name as a base class virtual function. The following example shows a templated user-defined conversion: @@ -101,4 +101,4 @@ int main() ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/microsoft-extensions.md b/docs/cpp/microsoft-extensions.md index daa58f6df4..55d937622a 100644 --- a/docs/cpp/microsoft-extensions.md +++ b/docs/cpp/microsoft-extensions.md @@ -7,28 +7,28 @@ ms.assetid: 68654516-24ef-4f33-aae2-175f86cc1979 --- # Microsoft Extensions -*`asm-statement`*:
-    **`__asm`** *`assembly-instruction`* **`;`**opt
-    **`__asm {`** *`assembly-instruction-list`* **`} ;`**opt +*`asm-statement`*:\ + **`__asm`** *`assembly-instruction`* **`;`**opt\ + **`__asm {`** *`assembly-instruction-list`* **`} ;`**opt -*`assembly-instruction-list`*:
-    *`assembly-instruction`* **`;`**opt
-    *`assembly-instruction`* **`;`** *`assembly-instruction-list`* **`;`**opt +*`assembly-instruction-list`*:\ + *`assembly-instruction`* **`;`**opt \ + *`assembly-instruction`* **`;`** *`assembly-instruction-list`* **`;`**opt -*`ms-modifier-list`*:
-    *`ms-modifier`* *`ms-modifier-list`*opt +*`ms-modifier-list`*:\ + *`ms-modifier`* *`ms-modifier-list`*opt -*`ms-modifier`*:
-    **`__cdecl`**
-    **`__fastcall`**
-    **`__stdcall`**
-    **`__syscall`** (reserved for future implementations)
-    **`__oldcall`** (reserved for future implementations)
-    **`__unaligned`** (reserved for future implementations)
-    *`based-modifier`* +*`ms-modifier`*:\ + **`__cdecl`**\ + **`__fastcall`**\ + **`__stdcall`**\ + **`__syscall`** (reserved for future implementations)\ + **`__oldcall`** (reserved for future implementations)\ + **`__unaligned`** (reserved for future implementations)\ + *`based-modifier`* -*`based-modifier`*:
-    **`__based (`** *`based-type`* **`)`** +*`based-modifier`*:\ + **`__based (`** *`based-type`* **`)`** -*`based-type`*:
-    *`name`* +*`based-type`*:\ + *`name`* diff --git a/docs/cpp/microsoft-specific-modifiers.md b/docs/cpp/microsoft-specific-modifiers.md index 3d8fc86562..fda7e96615 100644 --- a/docs/cpp/microsoft-specific-modifiers.md +++ b/docs/cpp/microsoft-specific-modifiers.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: Microsoft-specific modifiers" title: "Microsoft-specific modifiers" +description: "Learn more about: Microsoft-specific modifiers" ms.date: "08/16/2018" -ms.assetid: 22c7178c-f854-47fa-9de6-07d23fda58e1 --- # Microsoft-specific modifiers @@ -29,7 +28,7 @@ Many of the Microsoft-specific keywords can be used to modify declarators to for |[__restrict](extension-restrict.md)|Similar to __declspec([restrict](restrict.md)), but for use on variables.|No| |[__stdcall](stdcall.md)|The name that follows specifies a function that observes the standard calling convention.|Yes| |[__w64](w64.md)|Marks a data type as being larger on a 64-bit compiler.|No| -|[__unaligned](unaligned.md)|Specifies that a pointer to a type or other data is not aligned..|No| +|[__unaligned](unaligned.md)|Specifies that a pointer to a type or other data is not aligned.|No| |[__vectorcall](vectorcall.md)|The name that follows declares a function that uses registers, including SSE registers, when available, instead of the stack for argument passing.|Yes| ## See also diff --git a/docs/cpp/modules-cpp.md b/docs/cpp/modules-cpp.md index 22c69ea399..309913a75b 100644 --- a/docs/cpp/modules-cpp.md +++ b/docs/cpp/modules-cpp.md @@ -1,130 +1,154 @@ --- title: "Overview of modules in C++" -ms.date: "12/13/2019" -helpviewer_keywords: ["modules [C++]", "modules [C++], overview"] description: Modules in C++20 provide a modern alternative to header files. +ms.date: 04/17/2025 +helpviewer_keywords: ["modules [C++]", "modules [C++], overview"] --- # Overview of modules in C++ -C++20 introduces *modules*, a modern solution for componentization of C++ libraries and programs. A module is a set of source code files that are compiled independently of the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. Modules eliminate or greatly reduce many of the problems associated with the use of header files, and also potentially reduce compilation times. Macros, preprocessor directives, and non-exported names declared in a module are not visible and therefore have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit do not participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions and templates. That file can be processed much faster than a header file, and can be reused by the compiler every place where the module is imported in a project. - -Modules can be used side by side with header files. A C++ source file can import modules and also #include header files. In some cases, a header file can be imported as a module rather than textually #included by the preprocessor. We recommend that new projects use modules rather than header files as much as possible. For larger existing projects under active development, we suggest that you experiment with converting legacy headers to modules to see whether you get a meaningful reduction in compilation times. - -## Enable modules in the Microsoft C++ compiler +C++20 introduces *modules*. A *module* is a set of source code files that are compiled independently of the source files (or more precisely, the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. -As of Visual Studio 2019 version 16.2, modules are not fully implemented in the Microsoft C++ compiler. You can use the modules feature to create single-partition modules and to import the Standard Library modules provided by Microsoft. To enable support for modules, compile with [/`experimental:module`](../build/reference/experimental-module.md) and [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**). In a Visual Studio project, right-click the project node in **Solution Explorer** and choose **Properties**. Set the **Configuration** drop-down to **All Configurations**, then choose **Configuration Properties** > **C/C++** > **Language** > **Enable C++ Modules (experimental)**. +Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times, sometimes significantly. Macros, preprocessor directives, and nonexported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. The compiler can process that file much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project. -A module and the code that consumes it must be compiled with the same compiler options. +You can use modules side by side with header files. A C++ source file can `import` modules and also `#include` header files. In some cases, you can import a header file as a module, which is faster than using `#include` to process it with the preprocessor. We recommend that you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base your adoption on whether you get a meaningful reduction in compilation times. -## Consume the C++ Standard Library as modules +To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). -Although not specified by the C++20 standard, Microsoft enables its implementation of the C++ Standard Library to be imported as modules. By importing the C++ Standard Library as modules rather than #including it through header files, you can potentially speed up compilation times depending on the size of your project. The library is componentized into the following modules: +Starting with Visual Studio 2022 version 17.5, importing the Standard Library as a module is both standardized and fully implemented in the Microsoft C++ compiler. To learn how to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md). -- std.regex provides the content of header \ -- std.filesystem provides the content of header \ -- std.memory provides the content of header \ -- std.threading provides the contents of headers \, \, \, \, \, and \ -- std.core provides everything else in the C++ Standard Library - -To consume these modules, just add an import declaration to the top of the source code file. For example: - -```cpp -import std.core; -import std.regex; -``` +## Single-partition modules -To consume the Microsoft Standard Library module, compile your program with [/EHsc](../build/reference/eh-exception-handling-model.md) and [/MD](../build/reference/md-mt-ld-use-run-time-library.md) options. +A single-partition module is a module that consists of a single source file. The module interface and implementation are in the same file. -## Basic example +The following single-partition module example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is the default extension for module interface files in Visual Studio. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. In this example, the interface file contains both the function definition and the declaration. You can also place the definitions in one or more separate module implementation files, as shown in a later example, but this is an example of a single-partition module. -The following example shows a simple module definition in a source file called **Foo.ixx**. The **.ixx** extension is required for module interface files in Visual Studio. In this example, the interface file contains the function definition as well as the declaration. However, the definitions can be also placed in one or more separate files (as shown in a later example). The **export module Foo** statement indicates that this file is the primary interface for a module called `Foo`. The **`export`** modifier on `f()` indicates that this function will be visible when `Foo` is imported by another program or module. Note that the module references a namespace `Bar`. +The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier before `int f()` indicates that this function is visible when another program or module imports `Example`: ```cpp -export module Foo; +// Example.ixx +export module Example; #define ANSWER 42 -namespace Bar +namespace Example_NS { - int f_internal() { - return ANSWER; - } + int f_internal() + { + return ANSWER; + } - export int f() { - return f_internal(); + export int f() + { + return f_internal(); } } ``` -The file **MyProgram.cpp** uses the **import** declaration to access the name that is exported by `Foo`. Note that the name `Bar` is visible here, but not all of its members. Also note that the macro `ANSWER` is not visible. +The file *`MyProgram.cpp`* uses **`import`** to access the name exported by `Example`. The namespace name `Example_NS` is visible here, but not all of its members because they aren't exported. Also, the macro `ANSWER` isn't visible because macros aren't exported. ```cpp - -import Foo; -import std.core; +// MyProgram.cpp +import std; +import Example; using namespace std; int main() { - cout << "The result of f() is " << Bar::f() << endl; // 42 - // int i = Bar::f_internal(); // C2039 + cout << "The result of f() is " << Example_NS::f() << endl; // 42 + // int i = Example_NS::f_internal(); // C2039 // int j = ANSWER; //C2065 } - ``` -The import declaration can appear only at global scope. +The `import` declaration can appear only at global scope. A module and the code that consumes it must be compiled with the same compiler options. + +## Module grammar + +> *`module-name`*:\ +>  *`module-name-qualifier-seq`*opt *`identifier`* +> +> *`module-name-qualifier-seq`*:\ +>  *`identifier`* **`.`**\ +>  *`module-name-qualifier-seq`* *`identifier`* **`.`** +> +> *`module-partition`*:\ +>  **`:`** *`module-name`* +> +> *`module-declaration`*:\ +>  **`export`**opt **`module`** *`module-name`* *`module-partition`*opt *`attribute-specifier-seq`*opt **`;`** +> +> *`module-import-declaration`*:\ +>  **`export`**opt **`import`** *`module-name`* *`attribute-specifier-seq`*opt **`;`**\ +>  **`export`**opt **`import`** *`module-partition`* *`attribute-specifier-seq`*opt **`;`**\ +>  **`export`**opt **`import`** *`header-name`* *`attribute-specifier-seq`*opt **`;`** +> ## Implementing modules -You can create a module with a single interface file (.ixx) that exports names and includes implementations of all functions and types. You can also put the implementations in one or more separate implementation files, similar to how .h and .cpp files are used. The **`export`** keyword is used in the interface file only. An implementation file can **import** another module, but cannot **`export`** any names. Implementation files may be named with any extension. An interface file and the set of implementation files that back it are treated as a special kind of translation unit called a *module unit*. A name that is declared in any implementation file is automatically visible in all other files within the same module unit. +A *module interface* exports the module name and all the namespaces, types, functions, and so on, that make up the public interface of the module.\ +A *module implementation* defines the things exported by the module.\ +In its simplest form, a module can be a single file that combines the module interface and implementation. You can also put the implementation in one or more separate module implementation files, similar to how *`.h`* and *`.cpp`* files do it. + +For larger modules, you can split parts of the module into submodules called *partitions*. Each partition consists of a module interface file that exports the module partition name. A partition may also have one or more partition implementation files. The module as a whole has one *primary module interface*, which is the public interface of the module. It can export the partition interfaces, if desired. -For larger modules, you can split the module into multiple module units called *partitions*. Each partition consists of an interface file backed by one or more implementation files. (As of Visual Studio 2019 version 16.2, partitions are not yet fully implemented.) +A module consists of one or more *module units*. A module unit is a translation unit (a source file) that contains a module declaration. There are several types of module units: + +- A *module interface unit* exports a module name or module partition name. A module interface unit has `export module` in its module declaration. +- A *module implementation unit* doesn't export a module name or module partition name. As the name implies, it implements a module. +- A *primary module interface unit* exports the module name. There must be one and only one primary module interface unit in a module. +- A *module partition interface unit* exports a module partition name. +- A *module partition implementation unit* has a module partition name in its module declaration, but no `export` keyword. + +The **`export`** keyword is only used in interface files. An implementation file can **`import`** another module, but it can't **`export`** any names. Implementation files can have any extension. ## Modules, namespaces, and argument-dependent lookup -The rules for namespaces in modules are the same as in any other code. If a declaration within a namespace is exported, the enclosing namespace (excluding non-exported members) is also implicitly exported. If a namespace is explicitly exported, all declarations within that namespace definition are exported. +The rules for namespaces in modules are the same as any other code. If a declaration within a namespace is exported, the enclosing namespace (excluding members that aren't explicitly exported in that namespace) is also implicitly exported. If a namespace is explicitly exported, all declarations within that namespace definition are exported. -When performing argument-dependent lookup for overload resolutions in the importing translation unit, the compiler considers functions which are declared in the same translation unit (including module interfaces) as where the type of the function's arguments are defined. +When the compiler does argument-dependent lookup for overload resolution in the importing translation unit, it considers functions declared in the same translation unit (including module interfaces) as where the type of the function's arguments is defined. ### Module partitions -> [!NOTE] -> This section is provided for completeness. Partitions are not yet implemented in the Microsoft C++ compiler. +A module partition is similar to a module, except: -A module can be componentized into *partitions*, each consisting of an interface file and zero or more implementation files. A module partition is similar to a module, except that it shares ownership of all declarations in the entire module. All names that are exported by partition interface files are imported and re-exported by the primary interface file. A partition's name must begin with the module name followed by a colon. Declarations in any of the partitions are visible within the entire module. No special precautions are needed to avoid one-definition-rule (ODR) errors. You can declare a name (function, class, etc.) in one partition and define it in another. A partition implementation file begins like this: +- It shares ownership of all declarations in the entire module. +- All names exported by partition interface files are imported and exported by the primary interface file. +- A partition's name must begin with the module name followed by a colon (`:`). +- Declarations in any of the partitions are visible within the entire module. +- No special precautions are needed to avoid one-definition-rule (ODR) errors. You can declare a name (function, class, and so on) in one partition and define it in another. + +A partition implementation file begins like this, and is an internal partition from a C++ standards perspective: ```cpp -module Foo:part1 +module Example:part1; ``` -and the partition interface file begins like this: +A partition interface file begins like this: ```cpp -export module Foo:part1 +export module Example:part1; ``` -To access declarations in another partition, a partition must import it, but it can only use the partition name, not the module name: +To access declarations in another partition, a partition must import it. But it can only use the partition name, not the module name: ```cpp -module Foo:part2; +module Example:part2; import :part1; ``` -The primary interface unit must import and re-export all the module's interface partition files like this: +The primary interface unit must import and re-export all of the module's interface partition files, like this: ```cpp -export import :part1 -export import :part2 -... +export import :part1; +export import :part2; ``` -The primary interface unit can import partition implementation files, but cannot export them because those files are not allowed to export any names. This enables a module to keep implementation details internal to the module. +The primary interface unit can import partition implementation files, but can't export them. Those files aren't allowed to export any names. This restriction enables a module to keep implementation details internal to the module. ## Modules and header files -You can include header files in a module source file by putting the `#include` directive before the module declaration. These files are considered to be in the *global module fragment*. A module can only see the names in the *global module fragment* that are in headers it explicitly includes. The global module fragment only contains symbols that are actually used. +You can include header files in a module source file by putting an `#include` directive before the module declaration. These files are considered to be in the *global module fragment*. A module can only see the names in the global module fragment that are in the headers that it explicitly includes. The global module fragment only contains symbols that are used. ```cpp // MyModuleA.cpp @@ -132,7 +156,7 @@ You can include header files in a module source file by putting the `#include` d #include "customlib.h" #include "anotherlib.h" -import std.core; +import std; import MyModuleB; //... rest of file @@ -142,24 +166,25 @@ You can use a traditional header file to control which modules are imported: ```cpp // MyProgram.h -import std.core; -#ifdef DEBUG_LOGGING -import std.filesystem; +#ifdef C_RUNTIME_GLOBALS +import std.compat; +#else +import std; #endif ``` ### Imported header files -> [!NOTE] -> This section is informational only. Legacy imports are not yet implemented in the Microsoft C++ compiler. - -Some headers are sufficiently self-contained that they are allowed to be brought in using the **import** keyword. The main difference between an imported header and an imported module is that any preprocessor definitions in the header are visible in the importing program immediately after the import statement. (Preprocessor definitions in any files included by that header are *not* visible.) +Some headers are sufficiently self-contained that they can be brought in using the **`import`** keyword. The main difference between an imported header and an imported module is that any preprocessor definitions in the header are visible in the importing program immediately after the `import` statement. ```cpp -import -import "myheader.h" +import ; +import "myheader.h"; ``` ## See also -[module, import, export](import-export-module.md) +[Import the C++ standard library using modules](tutorial-import-stl-named-module.md)\ +[`module`, `import`, `export`](import-export-module.md)\ +[Named modules tutorial](tutorial-named-modules-cpp.md)\ +[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md) diff --git a/docs/cpp/multiple-base-classes.md b/docs/cpp/multiple-base-classes.md index aa470f564d..d792657cd2 100644 --- a/docs/cpp/multiple-base-classes.md +++ b/docs/cpp/multiple-base-classes.md @@ -3,7 +3,6 @@ description: "Learn more about: Multiple Base Classes" title: "Multiple Base Classes" ms.date: "11/19/2018" helpviewer_keywords: ["base classes [C++], multiple", "derived classes [C++], multiple bases", "multiple inheritance, class declaration", "multiple base classes [C++]"] -ms.assetid: a30c69fe-401c-4a87-96a0-e0da70c7c740 --- # Multiple Base Classes @@ -20,16 +19,16 @@ class CollectionOfBook : public Book, public Collection { }; ``` -The order in which base classes are specified is not significant except in certain cases where constructors and destructors are invoked. In these cases, the order in which base classes are specified affects the following: +The order in which base classes are specified isn't significant except in certain cases where constructors and destructors are invoked. In these cases, the order in which base classes are specified affects the following: -- The order in which initialization by constructor takes place. If your code relies on the `Book` portion of `CollectionOfBook` to be initialized before the `Collection` part, the order of specification is significant. Initialization takes place in the order the classes are specified in the *base-list*. +- The order in which constructors are called. If your code relies on the `Book` portion of `CollectionOfBook` to be initialized before the `Collection` part, the order of specification is significant. Initialization takes place in the order the classes are specified in the *base-list*. - The order in which destructors are invoked to clean up. Again, if a particular "part" of the class must be present when the other part is being destroyed, the order is significant. Destructors are called in the reverse order of the classes specified in the *base-list*. > [!NOTE] > The order of specification of base classes can affect the memory layout of the class. Do not make any programming decisions based on the order of base members in memory. -When specifying the *base-list*, you cannot specify the same class name more than once. However, it is possible for a class to be an indirect base to a derived class more than once. +When specifying the *base-list*, you can't specify the same class name more than once. However, it's possible for a class to be an indirect base to a derived class more than once. ## Virtual base classes @@ -41,17 +40,21 @@ When a base class is specified as a virtual base, it can act as an indirect base When declaring a virtual base class, the **`virtual`** keyword appears in the base lists of the derived classes. -Consider the class hierarchy in the following figure, which illustrates a simulated lunch line. +Consider the class hierarchy in the following figure, which illustrates a simulated lunch line: -![Graph of simulated lunch line.](../cpp/media/vc38xp1.gif "Graph of simulated lunch line")
-Simulated lunch-line graph +:::image type="complex" source="../cpp/media/vc38xp1.gif" alt-text="Diagram of a simulated lunch line." border="false"::: +The base class is Queue. Cashier Queue and Lunch Queue both inherit from Queue. Finally, Lunch Cashier Queue inherits from both Cashier Queue and Lunch Queue. +:::image-end::: +*Simulated lunch-line graph* -In the figure, `Queue` is the base class for both `CashierQueue` and `LunchQueue`. However, when both classes are combined to form `LunchCashierQueue`, the following problem arises: the new class contains two subobjects of type `Queue`, one from `CashierQueue` and the other from `LunchQueue`. The following figure shows the conceptual memory layout (the actual memory layout might be optimized). +In the figure, `Queue` is the base class for both `CashierQueue` and `LunchQueue`. However, when both classes are combined to form `LunchCashierQueue`, the following problem arises: the new class contains two subobjects of type `Queue`, one from `CashierQueue` and the other from `LunchQueue`. The following figure shows the conceptual memory layout (the actual memory layout might be optimized): -![Simulated lunch line object.](../cpp/media/vc38xp2.gif)
-Simulated lunch-line object +:::image type="complex" source="../cpp/media/vc38xp2.gif" alt-text="Diagram of a simulated lunch line object." border="false"::: +The figure shows a Lunch Cashier Queue object with two subobjects in it: Cashier Queue and Lunch Queue. Both Cashier Queue and Lunch Queue contain a Queue subobject." +:::image-end::: +*Simulated lunch-line object* -Note that there are two `Queue` subobjects in the `LunchCashierQueue` object. The following code declares `Queue` to be a virtual base class: +There are two `Queue` subobjects in the `LunchCashierQueue` object. The following code declares `Queue` to be a virtual base class: ```cpp // deriv_VirtualBaseClasses.cpp @@ -64,23 +67,29 @@ class LunchCashierQueue : public LunchQueue, public CashierQueue {}; The **`virtual`** keyword ensures that only one copy of the subobject `Queue` is included (see the following figure). -![Diagram showing a simulated lunch line object, with virtual base classes.](../cpp/media/vc38xp3.gif)
-Simulated lunch-line object with virtual base classes +:::image type="complex" source="../cpp/media/vc38xp3.gif" alt-text="Diagram of a simulated lunch line object, with virtual base classes depicted." border="false"::: +The diagram shows a Lunch Cashier Queue object, which contains a Cashier Queue subobject and a Lunch Queue subobject. Both Cashier Queue and Lunch Queue share the same Queue subobject. +:::image-end::: +*Simulated lunch-line object with virtual base classes* -A class can have both a virtual component and a nonvirtual component of a given type. This happens in the conditions illustrated in the following figure. +A class can have both a virtual component and a nonvirtual component of a given type. This happens in the conditions illustrated in the following figure: -![Diagram showing virtual and non virtual components of a class.](../cpp/media/vc38xp4.gif)
-Virtual and non-virtual components of the same class +:::image type="complex" source="../cpp/media/vc38xp4.gif" alt-text="Diagram of virtual and non virtual components of a class." border="false"::: +The diagram shows a queue base class. A Cashier Queue class and Lunch Queue class inherit virtually from Queue. A third class, Takeout Queue, inherits non virtually from queue. Lunch Cashier Queue inherits from both Cashier Queue and Lunch Queue. Lunch Takeout Cashier Queue inherits from both Lunch Cashier Queue and Takeout Queue. +:::image-end::: +*Virtual and nonvirtual components of the same class* In the figure, `CashierQueue` and `LunchQueue` use `Queue` as a virtual base class. However, `TakeoutQueue` specifies `Queue` as a base class, not a virtual base class. Therefore, `LunchTakeoutCashierQueue` has two subobjects of type `Queue`: one from the inheritance path that includes `LunchCashierQueue` and one from the path that includes `TakeoutQueue`. This is illustrated in the following figure. -![Diagram showing virtual and non virtual inheritance in object layout.](../cpp/media/vc38xp5.gif)
-Object layout with virtual and non-virtual inheritance +:::image type="complex" source="../cpp/media/vc38xp5.gif" alt-text="Diagram of the object layout for virtual and non virtual inheritance." border="false"::: +A Lunch Takeout Cashier Queue object is shown that contains two subobjects: a Takeout Queue (which contains a Queue subobject) and a Lunch Cashier Queue. The Lunch Cashier Queue subobject contains a Cashier Queue subobject and a Lunch Queue subobject, both of which share a Queue sub object. +:::image-end::: +*Object layout with virtual and nonvirtual inheritance* > [!NOTE] > Virtual inheritance provides significant size benefits when compared with nonvirtual inheritance. However, it can introduce extra processing overhead. -If a derived class overrides a virtual function that it inherits from a virtual base class, and if a constructor or a destructor for the derived base class calls that function using a pointer to the virtual base class, the compiler may introduce additional hidden "vtordisp" fields into the classes with virtual bases. The `/vd0` compiler option suppresses the addition of the hidden vtordisp constructor/destructor displacement member. The `/vd1` compiler option, the default, enables them where they are necessary. Turn off vtordisps only if you are sure that all class constructors and destructors call virtual functions virtually. +If a derived class overrides a virtual function that it inherits from a virtual base class, and if a constructor or a destructor for the derived base class calls that function using a pointer to the virtual base class, the compiler may introduce other hidden "vtordisp" fields into the classes with virtual bases. The `/vd0` compiler option suppresses the addition of the hidden vtordisp constructor/destructor displacement member. The `/vd1` compiler option, the default, enables them where they're necessary. Turn off vtordisps only if you're sure that all class constructors and destructors call virtual functions virtually. The `/vd` compiler option affects an entire compilation module. Use the `vtordisp` pragma to suppress and then reenable `vtordisp` fields on a class-by-class basis: @@ -92,7 +101,7 @@ class GetReal : virtual public { ... }; ## Name ambiguities -Multiple inheritance introduces the possibility for names to be inherited along more than one path. The class-member names along these paths are not necessarily unique. These name conflicts are called "ambiguities." +Multiple inheritance introduces the possibility for names to be inherited along more than one path. The class-member names along these paths aren't necessarily unique. These name conflicts are called "ambiguities." Any expression that refers to a class member must make an unambiguous reference. The following example shows how ambiguities develop: @@ -108,7 +117,7 @@ public: class B { public: - unsigned a(); // Note that class A also has a member "a" + unsigned a(); // class A also has a member "a" int b(); // and a member "b". char c; }; @@ -117,7 +126,7 @@ public: class C : public A, public B {}; ``` -Given the preceding class declarations, code such as the following is ambiguous because it is unclear whether `b` refers to the `b` in `A` or in `B`: +Given the preceding class declarations, code such as the following is ambiguous because it's unclear whether `b` refers to the `b` in `A` or in `B`: ```cpp C *pc = new C; @@ -125,13 +134,13 @@ C *pc = new C; pc->b(); ``` -Consider the preceding example. Because the name `a` is a member of both class `A` and class `B`, the compiler cannot discern which `a` designates the function to be called. Access to a member is ambiguous if it can refer to more than one function, object, type, or enumerator. +Consider the preceding example. Because the name `a` is a member of both class `A` and class `B`, the compiler can't discern which `a` designates the function to be called. Access to a member is ambiguous if it can refer to more than one function, object, type, or enumerator. The compiler detects ambiguities by performing tests in this order: 1. If access to the name is ambiguous (as just described), an error message is generated. -1. If overloaded functions are unambiguous, they are resolved. +1. If overloaded functions are unambiguous, they're resolved. 1. If access to the name violates member-access permission, an error message is generated. (For more information, see [Member-Access Control](../cpp/member-access-control-cpp.md).) @@ -148,9 +157,9 @@ pc->B::a(); ### Dominance -It is possible for more than one name (function, object, or enumerator) to be reached through an inheritance graph. Such cases are considered ambiguous with nonvirtual base classes. They are also ambiguous with virtual base classes, unless one of the names "dominates" the others. +it's possible for more than one name (function, object, or enumerator) to be reached through an inheritance graph. Such cases are considered ambiguous with nonvirtual base classes. They're also ambiguous with virtual base classes, unless one of the names "dominates" the others. -A name dominates another name if it is defined in both classes and one class is derived from the other. The dominant name is the name in the derived class; this name is used when an ambiguity would otherwise have arisen, as shown in the following example: +A name dominates another name if it's defined in both classes and one class is derived from the other. The dominant name is the name in the derived class; this name is used when an ambiguity would otherwise have arisen, as shown in the following example: ```cpp // deriv_Dominance.cpp @@ -179,14 +188,16 @@ Explicit and implicit conversions from pointers or references to class types can - The declaration of an object of type `D`. -- The effect of applying the address-of operator (**&**) to that object. Note that the address-of operator always supplies the base address of the object. +- The effect of applying the address-of operator (**&**) to that object. The address-of operator always supplies the base address of the object. -- The effect of explicitly converting the pointer obtained using the address-of operator to the base-class type `A`. Note that coercing the address of the object to type `A*` does not always provide the compiler with enough information as to which subobject of type `A` to select; in this case, two subobjects exist. +- The effect of explicitly converting the pointer obtained using the address-of operator to the base-class type `A`. Coercing the address of the object to type `A*` doesn't always provide the compiler with enough information as to which subobject of type `A` to select; in this case, two subobjects exist. -![Diagram showing ambiguous conversion of pointers to base classes.](../cpp/media/vc38xt1.gif "Ambiguous conversion of pointers to base classes")
-Ambiguous conversion of pointers to base classes +:::image type="complex" source="../cpp/media/vc38xt1.gif" alt-text="Diagram showing how the conversion of pointers to base classes can be ambiguous." border="false"::: +The diagram first shows an inheritance hierarchy: A is the base class. B and C inherit from A. D inherits from B and C. Then, the memory layout is shown for object D. There are three subobjects in D: B (which includes a subobject A) and C (which includes a subobject A). The code & d points to the A in subobject B. The code ( * A ) & d points to both subobject B and subobject C. +:::image-end::: +*Ambiguous conversion of pointers to base classes* -The conversion to type `A*` (pointer to `A`) is ambiguous because there is no way to discern which subobject of type `A` is the correct one. Note that you can avoid the ambiguity by explicitly specifying which subobject you mean to use, as follows: +The conversion to type `A*` (pointer to `A`) is ambiguous because there's no way to discern which subobject of type `A` is the correct one. You can avoid the ambiguity by explicitly specifying which subobject you mean to use, as follows: ```cpp (A *)(B *)&d // Use B subobject. @@ -195,14 +206,16 @@ The conversion to type `A*` (pointer to `A`) is ambiguous because there is no wa ### Ambiguities and virtual base classes -If virtual base classes are used, functions, objects, types, and enumerators can be reached through multiple-inheritance paths. Because there is only one instance of the base class, there is no ambiguity when accessing these names. +If virtual base classes are used, functions, objects, types, and enumerators can be reached through multiple-inheritance paths. Because there's only one instance of the base class, there's no ambiguity when accessing these names. The following figure shows how objects are composed using virtual and nonvirtual inheritance. -![Diagram showing virtual derivation and nonvirtual derivation.](../cpp/media/vc38xr1.gif)
-Virtual and non-virtual derivation +:::image type="complex" source="../cpp/media/vc38xr1.gif" alt-text="Diagram showing virtual derivation and nonvirtual derivation." border="false"::: +The diagram first shows an inheritance hierarchy: A is the base class. B and C virtually inherit from A. D virtually inherits from B and C. Then, the layout of D is shown. D contains subobjects B and C, which share subobject A. Then the layout is shown as though the same hierarchy had been derived using nonvirtual inheritance. In that case, D contains the subobjects B and C. Both B and C contain their own copy of subobject A. +:::image-end::: +*Virtual and nonvirtual derivation* -In the figure, accessing any member of class `A` through nonvirtual base classes causes an ambiguity; the compiler has no information that explains whether to use the subobject associated with `B` or the subobject associated with `C`. However, when `A` is specified as a virtual base class, there is no question which subobject is being accessed. +In the figure, accessing any member of class `A` through nonvirtual base classes causes an ambiguity; the compiler has no information that explains whether to use the subobject associated with `B` or the subobject associated with `C`. However, when `A` is specified as a virtual base class, there's no question which subobject is being accessed. ## See also diff --git a/docs/cpp/multiplicative-operators-and-the-modulus-operator.md b/docs/cpp/multiplicative-operators-and-the-modulus-operator.md index 588bec202e..3dd6968ca1 100644 --- a/docs/cpp/multiplicative-operators-and-the-modulus-operator.md +++ b/docs/cpp/multiplicative-operators-and-the-modulus-operator.md @@ -20,11 +20,11 @@ expression % expression The multiplicative operators are: -- Multiplication (\*) +- Multiplication (**`*`**) -- Division (**/**) +- Division (**`/`**) -- Modulus (remainder from division) (**%**) +- Modulus (remainder from division) (**`%`**) These binary operators have left-to-right associativity. @@ -78,6 +78,6 @@ int main() { ## See also -[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C Multiplicative Operators](../c-language/c-multiplicative-operators.md) diff --git a/docs/cpp/mutable-data-members-cpp.md b/docs/cpp/mutable-data-members-cpp.md index 0c35e0be6d..6f07401347 100644 --- a/docs/cpp/mutable-data-members-cpp.md +++ b/docs/cpp/mutable-data-members-cpp.md @@ -1,14 +1,13 @@ --- description: "Learn more about: Mutable Data Members (C++)" title: "Mutable Data Members (C++)" -ms.date: "11/04/2016" +ms.date: "03/14/2024" f1_keywords: ["mutable_cpp"] helpviewer_keywords: ["mutable keyword [C++]"] -ms.assetid: ebe89746-3d36-43a8-8d69-f426af23f551 --- # Mutable Data Members (C++) -This keyword can only be applied to non-static and non-const data members of a class. If a data member is declared **`mutable`**, then it is legal to assign a value to this data member from a **`const`** member function. +This keyword can only be applied to non-static, non-const, and non-reference data members of a class. If a data member is declared **`mutable`**, then it is legal to assign a value to this data member from a **`const`** member function. ## Syntax @@ -25,19 +24,15 @@ For example, the following code will compile without error because `m_accessCoun class X { public: - bool GetFlag() const - { - m_accessCount++; - return m_flag; - } + bool GetFlag() const + { + m_accessCount++; + return m_flag; + } private: - bool m_flag; - mutable int m_accessCount; + bool m_flag; + mutable int m_accessCount; }; - -int main() -{ -} ``` ## See also diff --git a/docs/cpp/name-resolution-for-locally-declared-names.md b/docs/cpp/name-resolution-for-locally-declared-names.md index 8d16150289..be2d0b31bc 100644 --- a/docs/cpp/name-resolution-for-locally-declared-names.md +++ b/docs/cpp/name-resolution-for-locally-declared-names.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Name Resolution for Locally Declared Names" title: "Name Resolution for Locally Declared Names" -ms.date: "11/04/2016" +ms.date: 09/27/2022 ms.assetid: 743b88f3-de11-48f4-ae83-931449ea3886 --- # Name Resolution for Locally Declared Names @@ -10,7 +10,7 @@ The template's name itself can be referred to with or without the template argum ## Example: Specialization versus partial specialization -The following code shows that the class template's name A is interpreted differently in the scope of a specialization or partial specialization. +The following code shows that the class template's name `A` is interpreted differently in the scope of a specialization or partial specialization. ```cpp // template_name_resolution3.cpp @@ -32,7 +32,7 @@ template<> class A { ## Example: Name conflict between template parameter and object -In the case of a name conflict between a template parameter and another object, the template parameter can or cannot be hidden. The following rules will help determine precedence. +When there's a name conflict between a template parameter and another object, the template parameter can or can't be hidden. The following rules will help determine precedence. The template parameter is in scope from the point where it first appears until the end of the class or function template. If the name appears again in the template argument list or in the list of base classes, it refers to the same type. In standard C++, no other name that is identical to the template parameter can be declared in the same scope. A Microsoft extension allows the template parameter to be redefined in the scope of the template. The following example shows using the template parameter in the base specification of a class template. @@ -52,7 +52,7 @@ int main() { ## Example: Define member function outside class template -When defining a template's member functions outside the class template, a different template parameter name can be used. If the template member function definition uses a different name for the template parameter than the declaration does, and the name used in the definition conflicts with another member of the declaration, the member in the template declaration takes precedence. +When member functions are defined outside the class template, a different template parameter name can be used. If the class template member function's definition uses a different name for the template parameter than the declaration does, and the name used in the definition conflicts with another member of the declaration, the member in the template declaration takes precedence. ```cpp // template_name_resolution5.cpp @@ -87,7 +87,7 @@ Z::Z() ## Example: Define template or member function outside namespace -When defining a template function or member function outside the namespace in which the template was declared, the template argument takes precedence over the names of other members of the namespace. +When defining a function template or a member function outside the namespace in which the template was declared, the template argument takes precedence over the names of other members of the namespace. ```cpp // template_name_resolution6.cpp @@ -121,7 +121,7 @@ C::g ## Example: Base class or member name hides template argument -In definitions that are outside of the template class declaration, if a template class has a base class that does not depend on a template argument and if the base class or one of its members has the same name as a template argument, then the base class or member name hides the template argument. +In definitions that are outside of the template class declaration, if a template class has a base class that doesn't depend on a template argument and if the base class or one of its members has the same name as a template argument, then the base class or member name hides the template argument. ```cpp // template_name_resolution7.cpp @@ -159,4 +159,4 @@ Base ## See also -[Name Resolution](../cpp/templates-and-name-resolution.md) +[Name resolution](../cpp/templates-and-name-resolution.md) diff --git a/docs/cpp/namespaces-cpp.md b/docs/cpp/namespaces-cpp.md index 91eeb7b508..8051071fee 100644 --- a/docs/cpp/namespaces-cpp.md +++ b/docs/cpp/namespaces-cpp.md @@ -10,7 +10,7 @@ ms.assetid: d1a5a9ab-1cad-47e6-a82d-385bb77f4188 A namespace is a declarative region that provides a scope to the identifiers (the names of types, functions, variables, etc) inside it. Namespaces are used to organize code into logical groups and to prevent name collisions that can occur especially when your code base includes multiple libraries. All identifiers at namespace scope are visible to one another without qualification. Identifiers outside the namespace can access the members by using the fully qualified name for each identifier, for example `std::vector vec;`, or else by a [using Declaration](../cpp/using-declaration.md) for a single identifier (`using std::string`), or a [using Directive](../cpp/namespaces-cpp.md#using_directives) for all the identifiers in the namespace (`using namespace std;`). Code in header files should always use the fully qualified namespace name. -The following example shows a namespace declaration and three ways that code outside the namespace can accesses their members. +The following example shows a namespace declaration and three ways that code outside the namespace can access its members. ```cpp namespace ContosoData @@ -64,7 +64,7 @@ The **`using`** directive allows all the names in a **`namespace`** to be used w Typically, you declare a namespace in a header file. If your function implementations are in a separate file, then qualify the function names, as in this example. ```cpp -//contosoData.h +// contosoData.h #pragma once namespace ContosoDataServer { @@ -139,12 +139,12 @@ namespace ContosoDataServer Ordinary nested namespaces can be used to encapsulate internal implementation details that are not part of the public interface of the parent namespace. -## Inline namespaces (C++ 11) +## Inline namespaces (C++11) In contrast to an ordinary nested namespace, members of an inline namespace are treated as members of the parent namespace. This characteristic enables argument dependent lookup on overloaded functions to work on functions that have overloads in a parent and a nested inline namespace. It also enables you to declare a specialization in a parent namespace for a template that is declared in the inline namespace. The following example shows how external code binds to the inline namespace by default: ```cpp -//Header.h +// Header.h #include namespace Test @@ -160,6 +160,7 @@ namespace Test } } +// main.cpp #include "header.h" #include #include @@ -228,7 +229,7 @@ namespace Contoso T Multiply(T a, T b); std::vector Log(double); T Accumulate(std::vector nums); - }; + }; } } ``` diff --git a/docs/cpp/new-and-delete-operators.md b/docs/cpp/new-and-delete-operators.md index e8e31c908e..7561571216 100644 --- a/docs/cpp/new-and-delete-operators.md +++ b/docs/cpp/new-and-delete-operators.md @@ -1,14 +1,12 @@ --- title: "new and delete operators" description: "The C++ language new and delete operators allow control over allocation." -ms.date: 07/07/2020 +ms.date: 05/21/2022 helpviewer_keywords: ["new keyword [C++]", "delete keyword [C++]"] --- # `new` and `delete` operators -C++ supports dynamic allocation and deallocation of objects using the [`new`](new-operator-cpp.md) and [`delete`](delete-operator-cpp.md) operators. These operators allocate memory for objects from a pool called the free store. The **`new`** operator calls the special function [`operator new`](new-operator-cpp.md), and the **`delete`** operator calls the special function [`operator delete`](delete-operator-cpp.md). - -The **`new`** function in the C++ Standard Library supports the behavior specified in the C++ standard, which is to throw a `std::bad_alloc` exception if the memory allocation fails. If you still want the non-throwing version of **`new`**, link your program with *`nothrownew.obj`*. However, when you link with *`nothrownew.obj`*, the default **`operator new`** in the C++ Standard Library no longer functions. +C++ supports dynamic allocation and deallocation of objects using the [`new`](new-operator-cpp.md) and [`delete`](delete-operator-cpp.md) operators. These operators allocate memory for objects from a pool called the *free store* (also known as the *heap*). The **`new`** operator calls the special function [`operator new`](new-operator-cpp.md), and the **`delete`** operator calls the special function [`operator delete`](delete-operator-cpp.md). For a list of the library files in the C Runtime Library and the C++ Standard Library, see [CRT Library Features](../c-runtime-library/crt-library-features.md). @@ -20,9 +18,9 @@ The compiler translates a statement such as this one into a call to the function char *pch = new char[BUFFER_SIZE]; ``` -If the request is for zero bytes of storage, **`operator new`** returns a pointer to a distinct object. That is, repeated calls to **`operator new`** return different pointers. If there's insufficient memory for the allocation request, **`operator new`** throws a `std::bad_alloc` exception. Or, it returns **`nullptr`** if you've linked in non-throwing **`operator new`** support. +If the request is for zero bytes of storage, **`operator new`** returns a pointer to a distinct object. That is, repeated calls to **`operator new`** return different pointers. -You can write a routine that attempts to free memory and retry the allocation. For more information, see [`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md). For details on the recovery scheme, see the [Handling insufficient memory](#handling-insufficient-memory) section. +If there's insufficient memory for the allocation request, **`operator new`** throws a `std::bad_alloc` exception. Or, it returns **`nullptr`** if you've used the *placement* form `new(std::nothrow)`, or if you've linked in non-throwing **`operator new`** support. For more information, see [Allocation failure behavior](#allocation-failure-behavior). The two scopes for **`operator new`** functions are described in the following table. @@ -33,7 +31,7 @@ The two scopes for **`operator new`** functions are described in the following t | **`::operator new`** | Global | | *class-name* **`::operator new`** | Class | -The first argument to **`operator new`** must be of type `size_t`, defined in \, and the return type is always **`void*`**. +The first argument of **`operator new`** must be of type `size_t`, and the return type is always **`void*`**. The global **`operator new`** function is called when the **`new`** operator is used to allocate objects of built-in types, objects of class type that don't contain user-defined **`operator new`** functions, and arrays of any type. When the **`new`** operator is used to allocate objects of a class type where an **`operator new`** is defined, that class's **`operator new`** is called. @@ -94,24 +92,67 @@ int main() } ``` +### Allocation failure behavior + +The **`new`** function in the C++ Standard Library supports the behavior specified in the C++ standard since C++98. When there's insufficient memory for an allocation request, **`operator new`** throws a [`std::bad_alloc`](../standard-library/bad-alloc-class.md) exception. + +Older C++ code returned a null pointer for a failed allocation. If you have code that expects the non-throwing version of **`new`**, link your program with *`nothrownew.obj`*. The *`nothrownew.obj`* file replaces global **`operator new`** with a version that returns **`nullptr`** if an allocation fails. **`operator new`** no longer throws `std::bad_alloc`. For more information about *`nothrownew.obj`* and other linker option files, see [Link options](../c-runtime-library/link-options.md). + +You can't mix code that checks for exceptions from global **`operator new`** with code that checks for null pointers in the same application. However, you can still create class-local **`operator new`** that behaves differently. This possibility means the compiler must act defensively by default and include checks for null pointer returns in **`new`** calls. For more information on a way to optimize these compiler checks, see [`/Zc:throwingnew`](../build/reference/zc-throwingnew-assume-operator-new-throws.md). + ### Handling insufficient memory -Testing for failed memory allocation can be done as shown here: +The way you test for a failed allocation from a **`new`** expression depends on whether you use the standard exception mechanism, or you use a **`nullptr`** return. Standard C++ expects an allocator to throw either `std::bad_alloc` or a class derived from `std::bad_alloc`. You can handle such an exception as shown in this sample: + +```cpp +#include +#include +using namespace std; +#define BIG_NUMBER 10000000000LL +int main() { + try { + int *pI = new int[BIG_NUMBER]; + } + catch (bad_alloc& ex) { + cout << "Caught bad_alloc: " << ex.what() << endl; + return -1; + } +} +``` + +When you use the `nothrow` form of **`new`**, you can test for an allocation failure as shown in this sample: + +```cpp +#include +#include +using namespace std; +#define BIG_NUMBER 10000000000LL +int main() { + int *pI = new(nothrow) int[BIG_NUMBER]; + if ( pI == nullptr ) { + cout << "Insufficient memory" << endl; + return -1; + } +} +``` + +You can test for a failed memory allocation when you've used *`nothrownew.obj`* file to replace global **`operator new`** as shown here: ```cpp #include +#include using namespace std; -#define BIG_NUMBER 100000000 +#define BIG_NUMBER 10000000000LL int main() { int *pI = new int[BIG_NUMBER]; - if( pI == 0x0 ) { + if ( !pI ) { cout << "Insufficient memory" << endl; return -1; } } ``` -There's another way to handle failed memory allocation requests. Write a custom recovery routine to handle such a failure, then register your function by calling the [`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md) run-time function. +You can provide a handler for failed memory allocation requests. It's possible to write a custom recovery routine to handle such a failure. It could, for example, release some reserved memory, then allow the allocation to run again. For more information, see [`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md). ## The `delete` operator diff --git a/docs/cpp/noexcept-cpp.md b/docs/cpp/noexcept-cpp.md index 9302f2cc28..ceca8431bb 100644 --- a/docs/cpp/noexcept-cpp.md +++ b/docs/cpp/noexcept-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: noexcept (C++)" title: "noexcept (C++)" -ms.date: 11/30/2021 +ms.date: 09/27/2022 f1_keywords: ["noexcept_cpp"] ms.assetid: df24edb9-c6a6-4e37-9914-fd5c0c3716a8 --- @@ -31,7 +31,7 @@ Mark a function as **`noexcept`** only if all the functions that it calls, eithe ## Example -A template function that copies its argument might be declared **`noexcept`** on the condition that the object being copied is a plain old data type (POD). Such a function could be declared like this: +A function template that copies its argument might be declared **`noexcept`** on the condition that the object being copied is a plain old data type (POD). Such a function could be declared like this: ```cpp #include diff --git a/docs/cpp/nonstandard-behavior.md b/docs/cpp/nonstandard-behavior.md index d7d9e061de..2871910d0d 100644 --- a/docs/cpp/nonstandard-behavior.md +++ b/docs/cpp/nonstandard-behavior.md @@ -7,13 +7,13 @@ ms.assetid: a57dea27-dc79-4f64-8a83-017e84841773 --- # Nonstandard Behavior -The following sections list some of the places where the Microsoft implementation of C++ doesn't conform to the C++ standard. The section numbers given below refer to the section numbers in the C++ 11 standard (ISO/IEC 14882:2011(E)). +The following sections list some of the places where the Microsoft implementation of C++ doesn't conform to the C++ standard. The section numbers given below refer to the section numbers in the C++11 standard (ISO/IEC 14882:2011(E)). The list of compiler limits that differ from those defined in the C++ standard is given in [Compiler Limits](../cpp/compiler-limits.md). ## Covariant Return Types -Virtual base classes are not supported as covariant return types when the virtual function has a variable number of arguments. This doesn't conform to section 10.3, paragraph 7 of the C++ 11 ISO specification. The following sample doesn't compile; it generates compiler error [C2688](../error-messages/compiler-errors-2/compiler-error-c2688.md): +Virtual base classes are not supported as covariant return types when the virtual function has a variable number of arguments. This doesn't conform to section 10.3, paragraph 7 of the C++11 ISO specification. The following sample doesn't compile; it generates compiler error [C2688](../error-messages/compiler-errors-2/compiler-error-c2688.md): ```cpp // CovariantReturn.cpp @@ -30,7 +30,7 @@ class B : virtual A ## Binding Nondependent Names in Templates -The Microsoft C++ compiler doesn't currently support binding nondependent names when initially parsing a template. This doesn't conform to section 14.6.3 of the C++ 11 ISO specification. This can cause overloads declared after the template (but before the template is instantiated) to be seen. +The Microsoft C++ compiler doesn't currently support binding nondependent names when initially parsing a template. This doesn't conform to section 14.6.3 of the C++11 ISO specification. This can cause overloads declared after the template (but before the template is instantiated) to be seen. ```cpp #include @@ -56,7 +56,7 @@ int main() { ## Function Exception Specifiers -Function exception specifiers other than `throw()` are parsed but not used. This doesn't conform to section 15.4 of the ISO C++ 11 specification. For example: +Function exception specifiers other than `throw()` are parsed but not used. This doesn't conform to section 15.4 of the ISO C++11 specification. For example: ```cpp void f() throw(int); // parsed but not used @@ -67,7 +67,7 @@ For more information on exception specifications, see [Exception Specifications] ## char_traits::eof() -The C++ standard states that [char_traits::eof](../standard-library/char-traits-struct.md#eof) must not correspond to a valid `char_type` value. The Microsoft C++ compiler enforces this constraint for type **`char`**, but not for type **`wchar_t`**. This doesn't conform to the requirement in Table 62 in section 12.1.1 of the C++ 11 ISO specification. The example below demonstrates this behavior. +The C++ standard states that [char_traits::eof](../standard-library/char-traits-struct.md#eof) must not correspond to a valid `char_type` value. The Microsoft C++ compiler enforces this constraint for type **`char`**, but not for type **`wchar_t`**. This doesn't conform to the requirement in Table 62 in section 12.1.1 of the C++11 ISO specification. The example below demonstrates this behavior. ```cpp #include diff --git a/docs/cpp/noreturn.md b/docs/cpp/noreturn.md index 52f2b3db72..e06cecf56e 100644 --- a/docs/cpp/noreturn.md +++ b/docs/cpp/noreturn.md @@ -10,28 +10,43 @@ ms.assetid: 9c6517e5-22d7-4051-9974-3d2200ae4d1d **Microsoft Specific** -This **`__declspec`** attribute tells the compiler that a function does not return. As a consequence, the compiler knows that the code following a call to a **`__declspec(noreturn)`** function is unreachable. +The **`__declspec`** attribute tells the compiler that a function does not return. The compiler then knows that the code following a call to a **`__declspec(noreturn)`** function is unreachable. -If the compiler finds a function with a control path that does not return a value, it generates a warning (C4715) or error message (C2202). If the control path cannot be reached due to a function that never returns, you can use **`__declspec(noreturn)`** to prevent this warning or error. +If the compiler finds a function with a control path that does not return a value, it generates a warning (C4715) or error message (C2202). If the control path cannot be reached due to a function that never returns, use **`__declspec(noreturn)`** to prevent this warning or error. > [!NOTE] > Adding **`__declspec(noreturn)`** to a function that is expected to return can result in undefined behavior. ## Example -In the following sample,the **`else`** clause does not contain a return statement. Declaring `fatal` as **`__declspec(noreturn)`** avoids an error or warning message. +In the following example, when the argument for `isZeroOrPositive` is negative, `fatal` is called. There isn't a return statement in that control path, which results in warning C4715 that not all control paths return a value. Declaring `fatal` as **`__declspec(noreturn)`** mitigates that warning, which is desirable because there is no point in it since `fatal()` terminates the program. ```cpp // noreturn2.cpp -__declspec(noreturn) extern void fatal () {} - -int main() { - if(1) - return 1; - else if(0) - return 0; - else - fatal(); +#include + +__declspec(noreturn) void fatal() +{ + std::terminate(); +} + +int isZeroOrPositive(int val) +{ + if (val == 0) + { + return 0; + } + else if (val > 0) + { + return 1; + } + // this function terminates if val is negative + fatal(); +} + +int main() +{ + isZeroOrPositive(123); } ``` @@ -39,5 +54,5 @@ int main() { ## See also -[__declspec](../cpp/declspec.md)
+[__declspec](../cpp/declspec.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md b/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md index 3609a42adb..f57d1fb136 100644 --- a/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md +++ b/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md @@ -63,7 +63,7 @@ auto val_4 = 0x8000000000000000ULL << 16; // unsigned long long **Digit separators**: You can use the single-quote character (apostrophe) to separate place values in larger numbers to make them easier for humans to read. Separators have no effect on compilation. ```cpp -long long i = 24'847'458'121 +long long i = 24'847'458'121; ``` ## Floating point literals diff --git a/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md b/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md index 8940ffbd91..b13d412b96 100644 --- a/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md +++ b/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md @@ -1,13 +1,13 @@ --- title: "Object lifetime and resource management (RAII)" description: "Follow the principle of RAII in modern C++ to avoid resource leaks." -ms.date: "11/19/2019" +ms.date: 06/02/2022 ms.topic: "conceptual" ms.assetid: 8aa0e1a1-e04d-46b1-acca-1d548490700f --- # Object lifetime and resource management (RAII) -Unlike managed languages, C++ doesn't have automatic *garbage collection*. That's an internal process that releases heap memory and other resources as a program runs. A C++ program is responsible for returning all acquired resources to the operating system. Failure to release an unused resource is called a *leak*. Leaked resources are unavailable to other programs until the process exits. Memory leaks in particular are a common cause of bugs in C-style programming. +Unlike managed languages, C++ doesn't have automatic *garbage collection*, an internal process that releases heap memory and other resources as a program runs. A C++ program is responsible for returning all acquired resources to the operating system. Failure to release an unused resource is called a *leak*. Leaked resources are unavailable to other programs until the process exits. Memory leaks in particular are a common cause of bugs in C-style programming. Modern C++ avoids using heap memory as much as possible by declaring objects on the stack. When a resource is too large for the stack, then it should be *owned* by an object. As the object gets initialized, it acquires the resource it owns. The object is then responsible for releasing the resource in its destructor. The owning object itself is declared on the stack. The principle that *objects own resources* is also known as "resource acquisition is initialization," or RAII. @@ -48,12 +48,11 @@ public: }; void functionUsingWidget() { - widget w(1000000); // lifetime automatically tied to enclosing scope + widget w(1000000); // lifetime automatically tied to enclosing scope // constructs w, including the w.data member w.do_something(); } // automatic destruction and deallocation for w and w.data - ``` Since C++11, there's a better way to write the previous example: by using a smart pointer from the standard library. The smart pointer handles the allocation and deletion of the memory it owns. Using a smart pointer eliminates the need for an explicit destructor in the `widget` class. @@ -63,20 +62,19 @@ Since C++11, there's a better way to write the previous example: by using a smar class widget { private: - std::unique_ptr data; + std::unique_ptr data; public: - widget(const int size) { data = std::make_unique(size); } + widget(const int size) { data = std::make_unique(size); } void do_something() {} }; void functionUsingWidget() { - widget w(1000000); // lifetime automatically tied to enclosing scope - // constructs w, including the w.data gadget member + widget w(1000000); // lifetime automatically tied to enclosing scope + // constructs w, including the w.data gadget member // ... w.do_something(); // ... } // automatic destruction and deallocation for w and w.data - ``` By using smart pointers for memory allocation, you may eliminate the potential for memory leaks. This model works for other resources, such as file handles or sockets. You can manage your own resources in a similar way in your classes. For more information, see [Smart pointers](smart-pointers-modern-cpp.md). @@ -85,6 +83,6 @@ The design of C++ ensures objects are destroyed when they go out of scope. That ## See also -[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)
-[C++ Language Reference](../cpp/cpp-language-reference.md)
+[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)\ +[C++ language reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/one-s-complement-operator-tilde.md b/docs/cpp/one-s-complement-operator-tilde.md index 1f996f18f7..bcdc6623a1 100644 --- a/docs/cpp/one-s-complement-operator-tilde.md +++ b/docs/cpp/one-s-complement-operator-tilde.md @@ -6,7 +6,7 @@ f1_keywords: ["~", "compl_cpp"] helpviewer_keywords: ["tilde (~) one's complement operator", "one's complement operator", "bitwise-complement operator", "compl operator", "~ operator [C++], syntax"] ms.assetid: 4bf81967-34f7-4b4b-aade-fd03d5da0174 --- -# One's complement operator: ~ +# One's complement operator: `~` ## Syntax @@ -45,6 +45,6 @@ Integral promotion is performed on integral operands. The type the operand is pr ## See also -[Expressions with unary operators](expressions-with-unary-operators.md)
-[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with unary operators](expressions-with-unary-operators.md)\ +[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)\ [Unary arithmetic operators](../c-language/unary-arithmetic-operators.md) diff --git a/docs/cpp/operator-overloading.md b/docs/cpp/operator-overloading.md index ace83194aa..58964423c5 100644 --- a/docs/cpp/operator-overloading.md +++ b/docs/cpp/operator-overloading.md @@ -63,9 +63,9 @@ The name of an overloaded operator is **`operator`** *x*, where *x* is the opera |**[ ]**|Array subscript|—| |**^**|Exclusive OR|Binary| |**^=**|Exclusive OR assignment|Binary| -|**|**|Bitwise inclusive OR|Binary| -|**|=**|Bitwise inclusive OR assignment|Binary| -|**||**|Logical OR|Binary| +|**\|**|Bitwise inclusive OR|Binary| +|**\|=**|Bitwise inclusive OR assignment|Binary| +|**\|\|**|Logical OR|Binary| |**~**|One's complement|Unary| |**`delete`**|Delete|—| |**`new`**|New|—| diff --git a/docs/cpp/overload-resolution-of-function-template-calls.md b/docs/cpp/overload-resolution-of-function-template-calls.md index d515ad8419..f8e8fc3031 100644 --- a/docs/cpp/overload-resolution-of-function-template-calls.md +++ b/docs/cpp/overload-resolution-of-function-template-calls.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: Overload Resolution of Function Template Calls" -title: "Overload Resolution of Function Template Calls" -ms.date: "11/04/2016" +title: "Overload resolution of function template calls" +description: "Learn more about: Overload resolution of function template calls" +ms.date: 09/27/2022 helpviewer_keywords: ["function templates overload resolution"] -ms.assetid: a2918748-2cbb-4fc6-a176-e256f120bee4 --- -# Overload Resolution of Function Template Calls +# Overload resolution of function template calls -A function template can overload nontemplate functions of the same name. In this scenario, function calls are resolved by first using template argument deduction to instantiate the function template with a unique specialization. If template argument deduction fails, the other function overloads are considered to resolve the call. These other overloads, also known as the candidate set, include nontemplate functions and other instantiated function templates. If template argument deduction succeeds, then the generated function is compared with the other functions to determine the best match, following the rules for overload resolution. For more information, see [Function Overloading](function-overloading.md). +A function template can overload non-template functions of the same name. In this scenario, the compiler first attempts to resolve a function call by using template argument deduction to instantiate the function template with a unique specialization. If template argument deduction fails, then the compiler considers both instantiated function template overloads and non-template function overloads to resolve the call. These other overloads are known as the *candidate set*. If template argument deduction succeeds, then the generated function is compared with the other functions in the candidate set to determine the best match, following the rules for overload resolution. For more information, see [Function overloading](function-overloading.md). -## Example: Choose a nontemplate function +## Example: Choose a non-template function -If a nontemplate function is an equally good match to a template function, the nontemplate function is chosen (unless the template arguments were explicitly specified), as in the call `f(1, 1)` in the following example. +If a non-template function is an equally good match to a function template, the non-template function is chosen (unless the template arguments were explicitly specified), as in the call `f(1, 1)` in the following example. ```cpp // template_name_resolution9.cpp @@ -26,12 +25,12 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { - f(1, 1); // Equally good match; choose the nontemplate function. - f('a', 1); // Chooses the template function. + f(1, 1); // Equally good match; choose the non-template function. + f('a', 1); // Chooses the function template. f(2, 2); // Template arguments explicitly specified. } ``` @@ -42,9 +41,9 @@ void f(T1, T2) void f(T1, T2) ``` -## Example: Exact match template function preferred +## Example: Exact match function template preferred -The next example illustrates that the exactly matching template function is preferred if the nontemplate function requires a conversion. +The next example illustrates that the exactly matching function template is preferred if the non-template function requires a conversion. ```cpp // template_name_resolution10.cpp @@ -58,13 +57,13 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { long l = 0; int i = 0; - // Call the template function f(long, int) because f(int, int) + // Call the function template f(long, int) because f(int, int) // would require a conversion from long to int. f(l, i); } @@ -76,5 +75,5 @@ void f(T1, T2) ## See also -[Name Resolution](../cpp/templates-and-name-resolution.md)
-[typename](../cpp/typename.md) +[Name resolution](templates-and-name-resolution.md)\ +[`typename`](typename.md) diff --git a/docs/cpp/overloading-unary-operators.md b/docs/cpp/overloading-unary-operators.md index d99c49b8cc..6d9b26f6b0 100644 --- a/docs/cpp/overloading-unary-operators.md +++ b/docs/cpp/overloading-unary-operators.md @@ -1,51 +1,57 @@ --- -description: "Learn more about: Overloading Unary Operators" -title: "Overloading Unary Operators" -ms.date: "11/04/2016" +description: "Learn more about: Overloading unary operators" +title: "Overloading unary operators" +ms.date: 07/08/2022 helpviewer_keywords: ["unary operators [C++], plus", "increment operators [C++], overloaded", "unary operators [C++], minus", "operators [C++], unary", "redefinable unary operators [C++]", "unary operators [C++]", "pointer dereference operator overloading", "plus operator"] ms.assetid: 7683ef08-42a4-4283-928f-d3dd4f3ab4c0 --- -# Overloading Unary Operators +# Overloading unary operators -The unary operators that can be overloaded are the following: +Unary operators produce a result from a single operand. You can define overloads of a standard set of unary operators to work on user-defined types. -1. `!` ([logical NOT](../cpp/logical-negation-operator-exclpt.md)) +## Overloadable unary operators -1. `&` ([address-of](../cpp/address-of-operator-amp.md)) +You can overload the following unary operators on user-defined types: -1. `~` ([one's complement](../cpp/one-s-complement-operator-tilde.md)) +- **`!`** ([logical NOT](../cpp/logical-negation-operator-exclpt.md)) -1. `*` ([pointer dereference](../cpp/indirection-operator-star.md)) +- **`&`** ([address-of](../cpp/address-of-operator-amp.md)) -1. `+` ([unary plus](../cpp/additive-operators-plus-and.md)) +- **`~`** ([complement](../cpp/one-s-complement-operator-tilde.md)) -1. `-` ([unary negation](../cpp/additive-operators-plus-and.md)) +- **`*`** ([pointer dereference](../cpp/indirection-operator-star.md)) -1. `++` ([increment](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) +- **`+`** ([unary plus](../cpp/unary-plus-and-negation-operators-plus-and.md)) -1. `--` ([decrement](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) +- **`-`** ([unary negation](../cpp/unary-plus-and-negation-operators-plus-and.md)) -1. conversion operators +- **`++`** ([prefix increment](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) or ([postfix increment](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md)) -The postfix increment and decrement operators (`++` and `--`) are treated separately in [Increment and Decrement](../cpp/increment-and-decrement-operator-overloading-cpp.md). +- **`--`** ([prefix decrement](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) or ([postfix decrement](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md)) -Conversion operators are also discussed in a separate topic; see [User-Defined Type Conversions](../cpp/user-defined-type-conversions-cpp.md). +- [Conversion operators](../cpp/user-defined-type-conversions-cpp.md) -The following rules are true of all other unary operators. To declare a unary operator function as a nonstatic member, you must declare it in the form: +## Unary operator overload declarations -> *ret-type* **`operator`** *op* **()** +You can declare overloaded unary operators either as non-static member functions or as nonmember functions. Overloaded unary member functions take no argument because they implicitly operate on **`this`**. Nonmember functions are declared with one argument. When both forms are declared, the compiler follows the rules for overload resolution to determine which function to use, if any. -where *ret-type* is the return type and *op* is one of the operators listed in the preceding table. +The following rules apply to all prefix unary operators. To declare a unary operator function as a non-static member function, use this declaration form: -To declare a unary operator function as a global function, you must declare it in the form: +> *`return-type`* **`operator`** *`op`* **`();`** -> *ret-type* **`operator`** *op* **(** *arg* **)** +In this form, *`return-type`* is the return type and *`op`* is one of the operators listed in the preceding table. -where *ret-type* and *op* are as described for member operator functions and the *arg* is an argument of class type on which to operate. +To declare a unary operator function as a nonmember function, use this declaration form: + +> *`return-type`* **`operator`** *`op`* **`(`** *`class-type`* **`);`** + +In this form, *`return-type`* is the return type, *`op`* is one of the operators listed in the preceding table, and *`class-type`* is the class type of the argument on which to operate. + +The postfix forms of **`++`** and **`--`** take an extra **`int`** argument to distinguish them from the prefix forms. For more information about the prefix and postfix forms of **`++`** and **`--`**, see [Increment and decrement operator overloading](../cpp/increment-and-decrement-operator-overloading-cpp.md). > [!NOTE] -> There is no restriction on the return types of the unary operators. For example, it makes sense for logical NOT (`!`) to return an integral value, but this is not enforced. +> There's no restriction on the return types of the unary operators. For example, it makes sense for logical NOT (**`!`**) to return a **`bool`** value, but this behavior isn't enforced. ## See also -[Operator Overloading](../cpp/operator-overloading.md) +[Operator overloading](../cpp/operator-overloading.md) diff --git a/docs/cpp/partial-ordering-of-function-templates-cpp.md b/docs/cpp/partial-ordering-of-function-templates-cpp.md index 22b8d8f8f0..5e5607e843 100644 --- a/docs/cpp/partial-ordering-of-function-templates-cpp.md +++ b/docs/cpp/partial-ordering-of-function-templates-cpp.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: Partial Ordering of Function Templates (C++)" -title: "Partial Ordering of Function Templates (C++)" -ms.date: "07/30/2019" +description: "Learn more about: Partial ordering of function templates (C++)" +title: "Partial ordering of function templates (C++)" +ms.date: 09/27/2022 helpviewer_keywords: ["partial ordering of function templates"] ms.assetid: 0c17347d-0e80-47ad-b5ac-046462d9dc73 --- -# Partial Ordering of Function Templates (C++) +# Partial ordering of function templates (C++) Multiple function templates that match the argument list of a function call can be available. C++ defines a partial ordering of function templates to specify which function should be called. The ordering is partial because there can be some templates that are considered equally specialized. -The compiler chooses the most specialized template function available from the possible matches. For example, if a function template takes a type `T` and another function template that takes `T*` is available, the `T*` version is said to be more specialized. It's preferred over the generic `T` version whenever the argument is a pointer type, even though both would be allowable matches. +The compiler chooses the most specialized function template available from the possible matches. For example, if a function template takes a type `T` and another function template that takes `T*` is available, the `T*` version is said to be more specialized. It's preferred over the generic `T` version whenever the argument is a pointer type, even though both would be allowable matches. Use the following process to determine if one function template candidate is more specialized: -1. Consider two function templates, T1 and T2. +1. Consider two function templates, `T1` and `T2`. -1. Replace the parameters in T1 with a hypothetical unique type X. +1. Replace the parameters in `T1` with a hypothetical unique type `X`. -1. With the parameter list in T1, see if T2 is a valid template for that parameter list. Ignore any implicit conversions. +1. With the parameter list in `T1`, see if `T2` is a valid template for that parameter list. Ignore any implicit conversions. -1. Repeat the same process with T1 and T2 reversed. +1. Repeat the same process with `T1` and `T2` reversed. 1. If one template is a valid template argument list for the other template, but the converse isn't true, then that template is considered to be less specialized than the other template. If by using the previous step, both templates form valid arguments for each other, then they're considered to be equally specialized, and an ambiguous call results when you attempt to use them. @@ -27,11 +27,11 @@ Use the following process to determine if one function template candidate is mor 1. A template specialization for a specific type is more specialized than one taking a generic type argument. - 1. A template taking only `T*` is more specialized than one taking only `T`, because a hypothetical type `X*` is a valid argument for a `T` template argument, but `X` is not a valid argument for a `T*` template argument. + 1. A template taking only `T*` is more specialized than one taking only `T`, because a hypothetical type `X*` is a valid argument for a `T` template argument, but `X` isn't a valid argument for a `T*` template argument. - 1. `const T` is more specialized than `T`, because `const X` is a valid argument for a `T` template argument, but `X` is not a valid argument for a `const T` template argument. + 1. `const T` is more specialized than `T`, because `const X` is a valid argument for a `T` template argument, but `X` isn't a valid argument for a `const T` template argument. - 1. `const T*` is more specialized than `T*`, because `const X*` is a valid argument for a `T*` template argument, but `X*` is not a valid argument for a `const T*` template argument. + 1. `const T*` is more specialized than `T*`, because `const X*` is a valid argument for a `T*` template argument, but `X*` isn't a valid argument for a `const T*` template argument. ## Example @@ -77,4 +77,4 @@ Even more specialized function for const T* ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md b/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md index e594603a52..beb76735fa 100644 --- a/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md +++ b/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md @@ -6,7 +6,7 @@ f1_keywords: ["--", "++"] helpviewer_keywords: ["increment operators [C++], syntax", "member-selection operators [C++]", "-- operator [C++], postfix decrement operators", "postfix operators [C++]", "++ operator [C++], postfix increment operators", "decrement operators [C++], syntax", "operators [C++], postfix", "decrement operators [C++]"] ms.assetid: 0204d5c8-51b0-4108-b8a1-074c5754d89c --- -# Postfix Increment and Decrement Operators: ++ and -- +# Postfix Increment and Decrement Operators: `++` and `--` ## Syntax @@ -23,7 +23,7 @@ C++ provides prefix and postfix increment and decrement operators; this section i++; ``` -The effect of applying the postfix increment operator (**++**) is that the operand's value is increased by one unit of the appropriate type. Similarly, the effect of applying the postfix decrement operator (**--**) is that the operand's value is decreased by one unit of the appropriate type. +The effect of applying the postfix increment operator (**`++`**) is that the operand's value is increased by one unit of the appropriate type. Similarly, the effect of applying the postfix decrement operator (**`--`**) is that the operand's value is decreased by one unit of the appropriate type. It is important to note that a postfix increment or decrement expression evaluates to the value of the expression *prior to* application of the respective operator. The increment or decrement operation occurs *after* the operand is evaluated. This issue arises only when the postfix increment or decrement operation occurs in the context of a larger expression. @@ -60,6 +60,6 @@ for( myCompass = North; myCompass != West; myCompass++ ) // Error ## See also -[Postfix Expressions](../cpp/postfix-expressions.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Postfix Expressions](../cpp/postfix-expressions.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C Postfix Increment and Decrement Operators](../c-language/c-postfix-increment-and-decrement-operators.md) diff --git a/docs/cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md b/docs/cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md index 08b245ea21..238ae3dfb0 100644 --- a/docs/cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md +++ b/docs/cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md @@ -6,7 +6,7 @@ f1_keywords: ["--", "++"] helpviewer_keywords: ["increment operators [C++], syntax", "++ operator [C++], prefix increment operators", "operators [C++], decrement", "-- operator [C++], prefix decrement operators [C++]", "operators [C++], increment", "decrement operators [C++], syntax", "decrement operators [C++]"] ms.assetid: 45ea7fc7-f279-4be9-a216-1d9a0ef9eb7b --- -# Prefix Increment and Decrement Operators: ++ and -- +# Prefix Increment and Decrement Operators: `++` and `--` ## Syntax @@ -17,9 +17,9 @@ ms.assetid: 45ea7fc7-f279-4be9-a216-1d9a0ef9eb7b ## Remarks -The prefix increment operator (**++**) adds one to its operand; this incremented value is the result of the expression. The operand must be an l-value not of type **`const`**. The result is an l-value of the same type as the operand. +The prefix increment operator (**`++`**) adds one to its operand; this incremented value is the result of the expression. The operand must be an l-value not of type **`const`**. The result is an l-value of the same type as the operand. -The prefix decrement operator (**--**) is analogous to the prefix increment operator, except that the operand is decremented by one and the result is this decremented value. +The prefix decrement operator (**`--`**) is analogous to the prefix increment operator, except that the operand is decremented by one and the result is this decremented value. **Visual Studio 2017 version 15.3 and later** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): The operand of an increment or decrement operator may not be of type **`bool`**. @@ -66,6 +66,6 @@ If `i` is greater than or equal to `j` or less than `j` by 1, it will be increme ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Prefix Increment and Decrement Operators](../c-language/prefix-increment-and-decrement-operators.md) diff --git a/docs/cpp/primary-expressions.md b/docs/cpp/primary-expressions.md index 11f926e8a0..8722190e3e 100644 --- a/docs/cpp/primary-expressions.md +++ b/docs/cpp/primary-expressions.md @@ -1,9 +1,8 @@ --- title: "Primary expressions" description: "Primary expressions in the C++ programming language." -ms.date: 10/02/2020 +ms.date: 12/11/2023 helpviewer_keywords: ["primary expressions", "expressions [C++], name", "expressions [C++], literal", "expressions [C++], primary", "expressions [C++], qualified names"] -ms.assetid: 8ef9a814-6058-4b93-9b6e-e8eb8350b1ca --- # Primary Expressions @@ -15,27 +14,13 @@ Primary expressions are the building blocks of more complex expressions. They ma  *`name`*\  **`::`** *`name`* **`(`** *`expression`* **`)`** -A *`literal`* is a constant primary expression. Its type depends on the form of its specification. For complete information about specifying literals, see [Literals](../cpp/numeric-boolean-and-pointer-literals-cpp.md) . +A *`literal`* is a constant primary expression. Its type depends on the form of its specification. For more information about specifying literals, see [Literals](../cpp/numeric-boolean-and-pointer-literals-cpp.md) . -The **`this`** keyword is a pointer to a class object. It's available within nonstatic member functions. It points to the instance of the class for which the function was invoked. The **`this`** keyword can't be used outside the body of a class-member function. +The **`this`** keyword is a pointer to an instance of the class. It's available within nonstatic member functions and points to the instance of the class the function was invoked from. The **`this`** keyword can't be used outside the body of a class-member function. -The type of the **`this`** pointer is `type * const` (where `type` is the class name) within functions that don't specifically modify the **`this`** pointer. The following example shows member function declarations and the types of **`this`**: +For more information about the type of the **`this`** pointer, see [`this` pointer](this-pointer.md). -```cpp -// expre_Primary_Expressions.cpp -// compile with: /LD -class Example -{ -public: - void Func(); // * const this - void Func() const; // const * const this - void Func() volatile; // volatile * const this -}; -``` - -For more information about modifying the type of the **`this`** pointer, see [`this` pointer](this-pointer.md). - -The scope-resolution operator (**`::`**) followed by a name is a primary expression. Such names must be names at global scope, not member names. The type of the expression is determined by the declaration of the name. It's an l-value (that is, it can appear on the left-hand side of an assignment expression) if the declaring name is an l-value. The scope-resolution operator allows a global name to be referred to, even if that name is hidden in the current scope. See [Scope](../cpp/scope-visual-cpp.md) for an example of how to use the scope-resolution operator. +The scope-resolution operator (**`::`**) followed by a name is a primary expression. Such names must be names at global scope, not member names. The declaration of the name determines the type of the expression. It's an l-value (that is, it can appear on the left-hand side of an assignment expression) if the declaring name is an l-value. The scope-resolution operator allows a global name to be referred to, even if that name is hidden in the current scope. See [Scope](../cpp/scope-visual-cpp.md) for an example of how to use the scope-resolution operator. An expression enclosed in parentheses is a primary expression. Its type and value are identical to the type and value of the unparenthesized expression. It's an l-value if the unparenthesized expression is an l-value. diff --git a/docs/cpp/program-and-linkage-cpp.md b/docs/cpp/program-and-linkage-cpp.md index 7f9e6cc9a5..720e33de0f 100644 --- a/docs/cpp/program-and-linkage-cpp.md +++ b/docs/cpp/program-and-linkage-cpp.md @@ -11,7 +11,7 @@ In a C++ program, a *symbol*, for example a variable or function name, can be de The following example shows some declarations: ```cpp -int i; +extern int i; int f(int x); class C; ``` @@ -27,13 +27,13 @@ public: }; ``` -A program consists of one or more *translation units*. A translation unit consists of an implementation file and all the headers that it includes directly or indirectly. Implementation files typically have a file extension of *`.cpp`* or *`.cxx`*. Header files typically have an extension of *`.h`* or *`.hpp`*. Each translation unit is compiled independently by the compiler. After the compilation is complete, the linker merges the compiled translation units into a single *program*. Violations of the ODR rule typically show up as linker errors. Linker errors occur when the same name has two different definitions in different translation units. +A program consists of one or more *translation units*. A translation unit consists of an implementation file and all the headers that it includes directly or indirectly. Implementation files typically have a file extension of *`.cpp`* or *`.cxx`*. Header files typically have an extension of *`.h`* or *`.hpp`*. Each translation unit is compiled independently by the compiler. After the compilation is complete, the linker merges the compiled translation units into a single *program*. Violations of the ODR rule typically show up as linker errors. Linker errors occur when the same name is defined in more than one translation unit. -In general, the best way to make a variable visible across multiple files is to put it in a header file. Then add an #include directive in every *`.cpp`* file that requires the declaration. By adding *include guards* around the header contents, you ensure that the names it declares are only defined once. +In general, the best way to make a variable visible across multiple files is to declare it in a header file. Then add an `#include` directive in every *`.cpp`* file that requires the declaration. By adding *include guards* around the header contents, you ensure that the names a header declares are only declared once for each translation unit. Define the name in only one implementation file. In C++20, [modules](modules-cpp.md) are introduced as an improved alternative to header files. -In some cases, it may be necessary to declare a global variable or class in a *`.cpp`* file. In those cases, you need a way to tell the compiler and linker what kind of *linkage* the name has. The type of linkage specifies whether the name of the object applies just to the one file, or to all files. The concept of linkage applies only to global names. The concept of linkage doesn't apply to names that are declared within a scope. A scope is specified by a set of enclosing braces such as in function or class definitions. +In some cases, it may be necessary to declare a global variable or class in a *`.cpp`* file. In those cases, you need a way to tell the compiler and linker what kind of *linkage* the name has. The type of linkage specifies whether the name of the object is visible only in one file, or in all files. The concept of linkage applies only to global names. The concept of linkage doesn't apply to names that are declared within a scope. A scope is specified by a set of enclosing braces such as in function or class definitions. ## External vs. internal linkage diff --git a/docs/cpp/program-termination.md b/docs/cpp/program-termination.md index b582c5c91f..1ce131eed8 100644 --- a/docs/cpp/program-termination.md +++ b/docs/cpp/program-termination.md @@ -1,7 +1,7 @@ --- title: "C++ program termination" description: "Learn about the standard ways to exit a C++-language program." -ms.date: 12/07/2020 +ms.date: 07/07/2022 helpviewer_keywords: ["terminating execution", "quitting applications", "exiting applications", "programs [C++], terminating"] --- # C++ program termination @@ -16,11 +16,11 @@ In C++, you can exit a program in these ways: The [`exit`](../c-runtime-library/reference/exit-exit-exit.md) function, declared in \, terminates a C++ program. The value supplied as an argument to `exit` is returned to the operating system as the program's return code or exit code. By convention, a return code of zero means that the program completed successfully. You can use the constants `EXIT_FAILURE` and `EXIT_SUCCESS`, also defined in \, to indicate success or failure of your program. -Issuing a **`return`** statement from the `main` function is equivalent to calling the `exit` function with the return value as its argument. - ## `abort` function -The [`abort`](../c-runtime-library/reference/abort.md) function, also declared in the standard include file \, terminates a C++ program. The difference between `exit` and `abort` is that `exit` allows the C++ run-time termination processing to take place (global object destructors get called), but `abort` terminates the program immediately. The `abort` function bypasses the normal destruction process for initialized global static objects. It also bypasses any special processing that was specified using the [`atexit`](../c-runtime-library/reference/atexit.md) function. +The [`abort`](../c-runtime-library/reference/abort.md) function, also declared in the standard include file \, terminates a C++ program. The difference between `exit` and `abort` is that `exit` allows the C++ runtime termination processing to take place (global object destructors get called). `abort` terminates the program immediately. The `abort` function bypasses the normal destruction process for initialized global static objects. It also bypasses any special processing that was specified using the [`atexit`](../c-runtime-library/reference/atexit.md) function. + +**Microsoft-specific**: For Windows compatibility reasons, the Microsoft implementation of `abort` may allow DLL termination code to run in certain circumstances. For more information, see [`abort`](../c-runtime-library/reference/abort.md). ## `atexit` function @@ -28,23 +28,32 @@ Use the [`atexit`](../c-runtime-library/reference/atexit.md) function to specify ## `return` statement in `main` -Issuing a [`return`](return-statement-cpp.md) statement from `main` is functionally equivalent to calling the `exit` function. Consider the following example: +The **`return`** statement allows you to specify a return value from `main`. A [`return`](return-statement-cpp.md) statement in `main` first acts like any other `return` statement. Any automatic variables are destroyed. Then, `main` invokes `exit` with the return value as a parameter. Consider the following example: ```cpp // return_statement.cpp #include +struct S +{ + int value; +}; int main() { + S s{ 3 }; + exit( 3 ); + // or return 3; } ``` -The `exit` and **`return`** statements in the preceding example are functionally identical. Normally, C++ requires that functions that have return types other than **`void`** return a value. The `main` function is an exception; it can end without a **`return`** statement. In that case, it returns an implementation-specific value to the invoking process. The **`return`** statement allows you to specify a return value from `main`. +The `exit` and **`return`** statements in the preceding example have similar behavior. Both terminate the program and return a value of 3 to the operating system. The difference is that `exit` doesn't destroy the automatic variable `s`, while the `return` statement does. + +Normally, C++ requires that functions that have return types other than **`void`** return a value. The `main` function is an exception; it can end without a **`return`** statement. In that case, it returns an implementation-specific value to the invoking process. (By default, MSVC returns 0.) -## Destruction of static objects +## Destruction of thread and static objects -When you call `exit` or execute a **`return`** statement from `main`, static objects are destroyed in the reverse order of their initialization (after the call to `atexit` if one exists). The following example shows how such initialization and cleanup works. +When you call `exit` directly (or when it's called after a **`return`** statement from `main`), thread objects associated with the current thread are destroyed. Next, static objects are destroyed in the reverse order of their initialization (after calls to functions specified to `atexit`, if any). The following example shows how such initialization and cleanup works. ### Example @@ -86,7 +95,7 @@ int main() { } ``` -Another way to write this code is to declare the `ShowData` objects with block scope, allowing them to be destroyed when they go out of scope: +Another way to write this code is to declare the `ShowData` objects with block scope, which implicitly destroys them when they go out of scope: ```cpp int main() { diff --git a/docs/cpp/protected-cpp.md b/docs/cpp/protected-cpp.md index 8d4ec89e28..515f71fb84 100644 --- a/docs/cpp/protected-cpp.md +++ b/docs/cpp/protected-cpp.md @@ -30,7 +30,7 @@ The **`protected`** keyword specifies access to class members in the *member-lis When preceding the name of a base class, the **`protected`** keyword specifies that the public and protected members of the base class are protected members of its derived classes. -Protected members are not as private as **`private`** members, which are accessible only to members of the class in which they are declared, but they are not as public as **`public`** members, which are accessible in any function. +Protected members are not as private as **`private`** members, which are accessible only to members of the class in which they are declared but they are not as public as **`public`** members, which are accessible in any function. Protected members that are also declared as **`static`** are accessible to any friend or member function of a derived class. Protected members that are not declared as **`static`** are accessible to friends and member functions in a derived class only through a pointer to, reference to, or object of the derived class. @@ -75,7 +75,7 @@ int main() { y.Display(); // x.Protfunc(); error, Protfunc() is protected y.useProtfunc(); // OK, uses public access function - // in derived class + // in the derived class } ``` diff --git a/docs/cpp/raw-pointers.md b/docs/cpp/raw-pointers.md index dcc2e9464d..c12c7051c6 100644 --- a/docs/cpp/raw-pointers.md +++ b/docs/cpp/raw-pointers.md @@ -1,13 +1,13 @@ --- title: "Raw pointers (C++)" description: "How to use raw pointers in C++" -ms.date: "04/21/2020" +ms.date: 02/03/2022 helpviewer_keywords: ["pointers [C++]"] no-loc: [void, nullptr, const, char, new, delete] --- # Raw pointers (C++) -A *pointer* is a type of variable. It stores the address of an object in memory, and is used to access that object. A *raw pointer* is a pointer whose lifetime is not controlled by an encapsulating object, such as a [smart pointer](smart-pointers-modern-cpp.md). A raw pointer can be assigned the address of another non-pointer variable, or it can be assigned a value of [nullptr](nullptr.md). A pointer that hasn't been assigned a value contains random data. +A *pointer* is a type of variable. It stores the address of an object in memory, and is used to access that object. A *raw pointer* is a pointer whose lifetime isn't controlled by an encapsulating object, such as a [smart pointer](smart-pointers-modern-cpp.md). A raw pointer can be assigned the address of another non-pointer variable, or it can be assigned a value of [`nullptr`](nullptr.md). A pointer that hasn't been assigned a value contains random data. A pointer can also be *dereferenced* to retrieve the value of the object that it points at. The *member access operator* provides access to an object's members. @@ -19,7 +19,7 @@ A pointer can also be *dereferenced* to retrieve the value of the object that it int j = *p; // dereference p to retrieve the value at its address ``` -A pointer can point to a typed object or to **`void`**. When a program allocates an object on the [heap](https://wikipedia.org/wiki/Heap) in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers*. An owning pointer (or a copy of it) must be used to explicitly free the heap-allocated object when it's no longer needed. Failure to free the memory results in a *memory leak*, and renders that memory location unavailable to any other program on the machine. Memory allocated using **`new`** must be freed by using **`delete`** (or **delete\[]**). For more information, see [new and delete operators](new-and-delete-operators.md). +A pointer can point to a typed object or to **`void`**. When a program allocates an object on the [heap](https://wikipedia.org/wiki/Heap) in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers*. An owning pointer (or a copy of it) must be used to explicitly free the heap-allocated object when it's no longer needed. Failure to free the memory results in a *memory leak*, and renders that memory location unavailable to any other program on the machine. Memory allocated using **`new`** must be freed by using **`delete`** (or **`delete[]`**). For more information, see [`new` and `delete` operators](new-and-delete-operators.md). ```cpp MyClass* mc = new MyClass(); // allocate object on the heap @@ -27,7 +27,7 @@ A pointer can point to a typed object or to **`void`**. When a program allocates delete mc; // delete object (please don't forget!) ``` -A pointer (if it isn't declared as **`const`**) can be incremented or decremented to point at another location in memory. This operation is called *pointer arithmetic*. It's used in C-style programming to iterate over elements in arrays or other data structures. A **`const`** pointer can't be made to point to a different memory location, and in that sense is similar to a [reference](references-cpp.md). For more information, see [const and volatile pointers](const-and-volatile-pointers.md). +A pointer (if it isn't declared as **`const`**) can be incremented or decremented to point at another location in memory. This operation is called *pointer arithmetic*. It's used in C-style programming to iterate over elements in arrays or other data structures. A **`const`** pointer can't be made to point to a different memory location, and in that sense is similar to a [reference](references-cpp.md). For more information, see [`const` and `volatile` pointers](const-and-volatile-pointers.md). ```cpp // declare a C-style string. Compiler adds terminating '\0'. @@ -41,9 +41,9 @@ A pointer (if it isn't declared as **`const`**) can be incremented or decremente // pconst2 = &c2; // Error! pconst2 is const. ``` -On 64-bit operating systems, a pointer has a size of 64 bits. A system's pointer size determines how much addressable memory it can have. All copies of a pointer point to the same memory location. Pointers (along with references) are used extensively in C++ to pass larger objects to and from functions. That's because it's often more efficient to copy an object's address than to copy the entire object. When defining a function, specify pointer parameters as **`const`** unless you intend the function to modify the object. In general, **`const`** references are the preferred way to pass objects to functions unless the value of the object can possibly be **`nullptr`**. +On 64-bit operating systems, a pointer has a size of 64 bits. A system's pointer size determines how much addressable memory it can have. All copies of a pointer point to the same memory location. Pointers (along with references) are used extensively in C++ to pass larger objects to and from functions. It's often more efficient to copy an object's address than to copy the entire object. When defining a function, specify pointer parameters as **`const`** unless you intend the function to modify the object. In general, **`const`** references are the preferred way to pass objects to functions unless the value of the object can possibly be **`nullptr`**. -[Pointers to functions](#pointers_to_functions) enable functions to be passed to other functions and are used for "callbacks" in C-style programming. Modern C++ uses [lambda expressions](lambda-expressions-in-cpp.md) for this purpose. +[Pointers to functions](#pointers_to_functions) enable functions to be passed to other functions. They're used for "callbacks" in C-style programming. Modern C++ uses [lambda expressions](lambda-expressions-in-cpp.md) for this purpose. ## Initialization and member access @@ -81,7 +81,6 @@ void func_B(MyClass mc) mc.print(); // "Erika, 21" } - int main() { // Use the * operator to declare a pointer type @@ -129,10 +128,10 @@ int main() Pointers and arrays are closely related. When an array is passed by-value to a function, it's passed as a pointer to the first element. The following example demonstrates the following important properties of pointers and arrays: -- the **`sizeof`** operator returns the total size in bytes of an array -- to determine the number of elements, divide total bytes by the size of one element -- when an array is passed to a function, it *decays* to a pointer type -- the **`sizeof`** operator when applied to a pointer returns the pointer size, 4 bytes on x86 or 8 bytes on x64 +- The **`sizeof`** operator returns the total size in bytes of an array +- To determine the number of elements, divide total bytes by the size of one element +- When an array is passed to a function, it *decays* to a pointer type +- When the **`sizeof`** operator is applied to a pointer, it returns the pointer size, for example, 4 bytes on x86 or 8 bytes on x64 ```cpp #include @@ -150,7 +149,6 @@ void func(int arr[], int length) int main() { - int i[5]{ 1,2,3,4,5 }; // sizeof(i) = total bytes int j = sizeof(i) / sizeof(i[0]); @@ -158,7 +156,7 @@ int main() } ``` -Certain arithmetic operations can be used on non-const pointers to make them point to another memory location. Pointers are incremented and decremented using the **++**, **+=**, **-=** and **--** operators. This technique can be used in arrays and is especially useful in buffers of untyped data. A **void\*** gets incremented by the size of a **`char`** (1 byte). A typed pointer gets incremented by size of the type it points to. +Certain arithmetic operations can be used on non-`const` pointers to make them point to another memory location. Pointers are incremented and decremented using the **`++`**, **`+=`**, **`-=`** and **`--`** operators. This technique can be used in arrays and is especially useful in buffers of untyped data. A `void*` gets incremented by the size of a **`char`** (1 byte). A typed pointer gets incremented by size of the type it points to. The following example demonstrates how pointer arithmetic can be used to access individual pixels in a bitmap on Windows. Note the use of **`new`** and **`delete`**, and the dereference operator. @@ -170,7 +168,6 @@ using namespace std; int main() { - BITMAPINFOHEADER header; header.biHeight = 100; // Multiple of 4 for simplicity. header.biWidth = 100; @@ -225,14 +222,13 @@ int main() } ``` -## void* pointers +## `void*` pointers -A pointer to **`void`** simply points to a raw memory location. Sometimes it's necessary to use **void\*** pointers, for example when passing between C++ code and C functions. +A pointer to **`void`** simply points to a raw memory location. Sometimes it's necessary to use `void*` pointers, for example when passing between C++ code and C functions. -When a typed pointer is cast to a void pointer, the contents of the memory location are unchanged. However, the type information is lost, so that you can't do increment or decrement operations. A memory location can be cast, for example, from `MyClass*` to **`void*`** and back again to `MyClass*`. Such operations are inherently error-prone and require great care to avoid errors. Modern C++ discourages the use of void pointers in almost all circumstances. +When a typed pointer is cast to a `void` pointer, the contents of the memory location are unchanged. However, the type information is lost, so that you can't do increment or decrement operations. A memory location can be cast, for example, from `MyClass*` to `void*` and back again to `MyClass*`. Such operations are inherently error-prone and require great care to avoid errors. Modern C++ discourages the use of `void` pointers in almost all circumstances. ```cpp - //func.c void func(void* data, int length) { @@ -268,6 +264,7 @@ int main() void* p = static_cast(mc); MyClass* mc2 = static_cast(p); std::cout << mc2->name << std::endl; // "Marian" + delete(mc); // use operator new to allocate untyped memory block void* pvoid = operator new(1000); @@ -279,7 +276,7 @@ int main() func(pvoid, 1000); char ch = static_cast(pvoid)[0]; std::cout << ch << std::endl; // 'A' - operator delete(p); + operator delete(pvoid); } ``` @@ -337,7 +334,7 @@ int main() ## See also -[Smart pointers](smart-pointers-modern-cpp.md) -[Indirection Operator: *](indirection-operator-star.md)
-[Address-of Operator: &](address-of-operator-amp.md)
+[Smart pointers](smart-pointers-modern-cpp.md)\ +[Indirection Operator: *](indirection-operator-star.md)\ +[Address-of Operator: &](address-of-operator-amp.md)\ [Welcome back to C++](welcome-back-to-cpp-modern-cpp.md) diff --git a/docs/cpp/reference-type-function-returns.md b/docs/cpp/reference-type-function-returns.md index cdf3ea30b0..077a021837 100644 --- a/docs/cpp/reference-type-function-returns.md +++ b/docs/cpp/reference-type-function-returns.md @@ -91,7 +91,7 @@ Declarations of reference types must contain initializers except in the followin If you declare an object at local scope, that object will be destroyed when the function returns. If the function returns a reference to that object, that reference will probably cause an access violation at runtime if the caller attempts to use the null reference. ```cpp -// C4172 means Don’t do this!!! +// C4172 means Don't do this!!! Foo& GetFoo() { Foo f; diff --git a/docs/cpp/references-cpp.md b/docs/cpp/references-cpp.md index fc609d9e3b..456e543da0 100644 --- a/docs/cpp/references-cpp.md +++ b/docs/cpp/references-cpp.md @@ -3,38 +3,33 @@ description: "Learn more about: References (C++)" title: "References (C++)" ms.date: "11/04/2016" helpviewer_keywords: ["objects [C++], referencing", "references [C++]", "references, to pointers", "declarations, references", "references, declaring", "referencing objects, declarator syntax"] -ms.assetid: 68156f7f-97a0-4b66-b26d-b25ade5e3bd8 --- # References (C++) -A reference, like a pointer, stores the address of an object that is located elsewhere in memory. Unlike a pointer, a reference after it is initialized cannot be made to refer to a different object or set to null. There are two kinds of references: lvalue references which refer to a named variable and rvalue references which refer to a [temporary object](../cpp/temporary-objects.md). The & operator signifies an lvalue reference and the && operator signifies either an rvalue reference, or a universal reference (either rvalue or lvalue) depending on the context. +A reference, like a pointer, stores the address of an object that is located elsewhere in memory. Unlike a pointer, a reference after it's initialized can't be made to refer to a different object or set to null. There are two kinds of references: *lvalue* references, which refer to a named variable and *rvalue* references, which refer to a [temporary object](../cpp/temporary-objects.md). The `&` operator signifies an lvalue reference and the `&&` operator signifies either an rvalue reference, or a universal reference (either rvalue or lvalue) depending on the context. References may be declared using the following syntax: -> \[*storage-class-specifiers*] \[*cv-qualifiers*] *type-specifiers* \[*ms-modifier*] *declarator* \[**=** *expression*]**;** +> \[*storage-class-specifiers*] \[*cv-qualifiers*] *type-specifiers* \[*ms-modifier*] *declarator* \[**`=`** *expression*]**`;`** Any valid declarator specifying a reference may be used. Unless the reference is a reference to function or array type, the following simplified syntax applies: -> \[*storage-class-specifiers*] \[*cv-qualifiers*] *type-specifiers* \[**&** or **&&**] \[*cv-qualifiers*] *identifier* \[**=** *expression*]**;** +> \[*storage-class-specifiers*] \[*cv-qualifiers*] *type-specifiers* \[**`&`** or **`&&`**] \[*cv-qualifiers*] *identifier* \[**`=`** *expression*]**`;`** References are declared using the following sequence: 1. The declaration specifiers: - An optional storage class specifier. - - Optional **`const`** and/or **`volatile`** qualifiers. - - The type specifier: the name of a type. 1. The declarator: - An optional Microsoft-specific modifier. For more information, see [Microsoft-Specific Modifiers](../cpp/microsoft-specific-modifiers.md). - - The **&** operator or **&&** operator. - + - The **`&`** operator or **`&&`** operator. - Optional **`const`** and/or **`volatile`** qualifers. - - The identifier. 1. An optional initializer. @@ -48,7 +43,7 @@ int &i; int &i, &j; ``` -References, pointers and objects may be declared together: +References, pointers, and objects may be declared together: ```cpp int &ref, *ptr, k; @@ -69,7 +64,7 @@ struct S { int main() { S s; // Declare the object. - S& SRef = s; // Declare the reference. + S& SRef = s; // Declare and initialize the reference. s.i = 3; printf_s("%d\n", s.i); diff --git a/docs/cpp/relational-operators-equal-and-equal.md b/docs/cpp/relational-operators-equal-and-equal.md index 06221f5001..72b747923c 100644 --- a/docs/cpp/relational-operators-equal-and-equal.md +++ b/docs/cpp/relational-operators-equal-and-equal.md @@ -21,13 +21,13 @@ expression >= expression The binary relational operators determine the following relationships: -- Less than (**\<**) +- Less than (**`<`**) -- Greater than (**>**) +- Greater than (**`>`**) -- Less than or equal to (**\<=**) +- Less than or equal to (**`<=`**) -- Greater than or equal to (**>=**) +- Greater than or equal to (**`>=`**) The relational operators have left-to-right associativity. Both operands of relational operators must be of arithmetic or pointer type. They yield values of type **`bool`**. The value returned is **`false`** (0) if the relationship in the expression is false; otherwise, the value returned is **`true`** (1). @@ -48,7 +48,7 @@ int main() { } ``` -The expressions in the preceding example must be enclosed in parentheses because the stream insertion operator (**<<**) has higher precedence than the relational operators. Therefore, the first expression without the parentheses would be evaluated as: +The expressions in the preceding example must be enclosed in parentheses because the stream insertion operator (**`<<`**) has higher precedence than the relational operators. Therefore, the first expression without the parentheses would be evaluated as: ```cpp (cout << "The true expression 3 > 2 yields: " << 3) < (2 << "\n"); @@ -78,6 +78,6 @@ If two pointers point to elements of the same array or to the element one beyond ## See also -[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Expressions with Binary Operators](../cpp/expressions-with-binary-operators.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [C Relational and Equality Operators](../c-language/c-relational-and-equality-operators.md) diff --git a/docs/cpp/rvalue-reference-declarator-amp-amp.md b/docs/cpp/rvalue-reference-declarator-amp-amp.md index aa24139baf..c9dd311f11 100644 --- a/docs/cpp/rvalue-reference-declarator-amp-amp.md +++ b/docs/cpp/rvalue-reference-declarator-amp-amp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Rvalue reference declarator: &&" title: "Rvalue reference declarator: &&" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["&&"] helpviewer_keywords: ["&& rvalue reference declarator"] ms.assetid: eab0ce3a-c5a3-4992-aa70-6a8ab1f7491d @@ -21,7 +21,7 @@ Rvalue references enable you to distinguish an lvalue from an rvalue. Lvalue ref The following sections describe how rvalue references support the implementation of *move semantics* and *perfect forwarding*. -## Move Semantics +## Move semantics Rvalue references support the implementation of *move semantics*, which can significantly increase the performance of your applications. Move semantics enables you to write code that transfers resources (such as dynamically allocated memory) from one object to another. Move semantics works because it enables transfer of resources from temporary objects: ones that can't be referenced elsewhere in the program. @@ -43,17 +43,17 @@ int main() } ``` -Before Visual Studio 2010, each call to **`operator+`** allocates and returns a new temporary `string` object (an rvalue). **`operator+`** can't append one string to the other because it doesn't know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program and so must not be modified. By using rvalue references, **`operator+`** can be modified to take rvalues, which can't be referenced elsewhere in the program. With this change, **`operator+`** can now append one string to another. The change significantly reduces the number of dynamic memory allocations that the `string` class must make. For more information about the `string` class, see [basic_string Class](../standard-library/basic-string-class.md). +Before Visual Studio 2010, each call to **`operator+`** allocates and returns a new temporary `string` object (an rvalue). **`operator+`** can't append one string to the other because it doesn't know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program, and so must not be modified. You can modify **`operator+`** to take rvalues by using rvalue references, which can't be referenced elsewhere in the program. With this change, **`operator+`** can now append one string to another. The change significantly reduces the number of dynamic memory allocations that the `string` class must make. For more information about the `string` class, see [`basic_string` Class](../standard-library/basic-string-class.md). Move semantics also helps when the compiler can't use Return Value Optimization (RVO) or Named Return Value Optimization (NRVO). In these cases, the compiler calls the move constructor if the type defines it. -To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate memory for its elements and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it first creates a new element. Then it calls the copy constructor to copy the data from the previous element to the new element. Finally, it destroys the previous element. Move semantics enables you to move objects directly without having to make expensive memory allocation and copy operations. +To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate enough memory for its elements, and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it first creates a new element. Then it calls the copy constructor to copy the data from the previous element to the new element. Finally, it destroys the previous element. Move semantics enables you to move objects directly without having to make expensive memory allocation and copy operations. To take advantage of move semantics in the `vector` example, you can write a move constructor to move data from one object to another. For more information about the introduction of move semantics into the C++ Standard Library in Visual Studio 2010, see [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -## Perfect Forwarding +## Perfect forwarding Perfect forwarding reduces the need for overloaded functions and helps avoid the forwarding problem. The *forwarding problem* can occur when you write a generic function that takes references as its parameters. If it passes (or *forwards*) these parameters to another function, for example, if it takes a parameter of type `const T&`, then the called function can't modify the value of that parameter. If the generic function takes a parameter of type `T&`, then the function can't be called by using an rvalue (such as a temporary object or integer literal). @@ -100,7 +100,7 @@ int a = 4, b = 5; W* pw = factory(a, b); ``` -However, the following example doesn't contain a valid call to the `factory` function. That's because `factory` takes lvalue references that are modifiable as its parameters, but it's called by using rvalues: +However, the following example doesn't contain a valid call to the `factory` function. It's because `factory` takes lvalue references that are modifiable as its parameters, but it's called by using rvalues: ```cpp Z* pz = factory(2, 2); @@ -116,7 +116,7 @@ T* factory(A1&& a1, A2&& a2) } ``` -This example uses rvalue references as the parameters to the `factory` function. The purpose of the [std::forward](../standard-library/utility-functions.md#forward) function is to forward the parameters of the factory function to the constructor of the template class. +This example uses rvalue references as the parameters to the `factory` function. The purpose of the [`std::forward`](../standard-library/utility-functions.md#forward) function is to forward the parameters of the factory function to the constructor of the template class. The following example shows the `main` function that uses the revised `factory` function to create instances of the `W`, `X`, `Y`, and `Z` classes. The revised `factory` function forwards its parameters (either lvalues or rvalues) to the appropriate class constructor. @@ -136,7 +136,7 @@ int main() } ``` -## Properties of Rvalue References +## Properties of rvalue references **You can overload a function to take an lvalue reference and an rvalue reference.** @@ -183,7 +183,7 @@ In this example, the first call to `f` passes a local variable (an lvalue) as it **The compiler treats a named rvalue reference as an lvalue and an unnamed rvalue reference as an rvalue.** -Functions that take an rvalue reference as a parameter treat the parameter as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue. That's because a named object can be referenced by several parts of a program. It's dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first transfer succeeds. +Functions that take an rvalue reference as a parameter treat the parameter as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue. It's because a named object can be referenced by several parts of a program. It's dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first transfer succeeds. The following example shows the function `g`, which is overloaded to take an lvalue reference and an rvalue reference. The function `f` takes an rvalue reference as its parameter (a named rvalue reference) and returns an rvalue reference (an unnamed rvalue reference). In the call to `g` from `f`, overload resolution selects the version of `g` that takes an lvalue reference because the body of `f` treats its parameter as an lvalue. In the call to `g` from `main`, overload resolution selects the version of `g` that takes an rvalue reference because `f` returns an rvalue reference. @@ -275,7 +275,7 @@ In g(MemoryBlock&&). A function template that passes (or *forwards*) its parameters to another function is a common pattern. It's important to understand how template type deduction works for function templates that take rvalue references. -If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, assume you pass an rvalue reference to an object of type `X` to a template function that takes type `T&&` as its parameter. Template argument deduction deduces `T` to be `X`, so the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. +If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, assume you pass an rvalue reference to an object of type `X` to a function template that takes type `T&&` as its parameter. Template argument deduction deduces `T` to be `X`, so the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. The following example declares one structure template and then specializes it for various reference types. The `print_type_and_value` function takes an rvalue reference as its parameter and forwards it to the appropriate specialized version of the `S::print` method. The `main` function demonstrates the various ways to call the `S::print` method. @@ -390,7 +390,7 @@ The following table summarizes the reference collapsing rules for template argum | `T&& &` | `T&` | | `T&& &&` | `T&&` | -Template argument deduction is an important element of implementing perfect forwarding. The [Perfect Forwarding](#perfect-forwarding) section describes perfect forwarding in more detail. +Template argument deduction is an important element of implementing perfect forwarding. The [Perfect forwarding](#perfect-forwarding) section describes perfect forwarding in more detail. ## Summary diff --git a/docs/cpp/scope-resolution-operator.md b/docs/cpp/scope-resolution-operator.md index 5ed0813b26..02a1ee72fa 100644 --- a/docs/cpp/scope-resolution-operator.md +++ b/docs/cpp/scope-resolution-operator.md @@ -81,7 +81,7 @@ int main() { } ``` -You can use the scope resolution operator to identify a member of a **`namespace`**, or to identify a namespace that nominates the member’s namespace in a **`using`** directive. In the example below, you can use `NamespaceC` to qualify `ClassB`, even though `ClassB` was declared in namespace `NamespaceB`, because `NamespaceB` was nominated in `NamespaceC` by a **`using`** directive. +You can use the scope resolution operator to identify a member of a **`namespace`**, or to identify a namespace that nominates the member's namespace in a **`using`** directive. In the example below, you can use `NamespaceC` to qualify `ClassB`, even though `ClassB` was declared in namespace `NamespaceB`, because `NamespaceB` was nominated in `NamespaceC` by a **`using`** directive. ```cpp namespace NamespaceB { @@ -168,5 +168,5 @@ int main() { ## See also -[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Namespaces](../cpp/namespaces-cpp.md) diff --git a/docs/cpp/semantics-of-expressions.md b/docs/cpp/semantics-of-expressions.md index 778bec6d03..9c541b6a28 100644 --- a/docs/cpp/semantics-of-expressions.md +++ b/docs/cpp/semantics-of-expressions.md @@ -85,9 +85,9 @@ An expression can modify an object's value only once between consecutive "sequen The C++ language definition does not currently specify sequence points. Microsoft C++ uses the same sequence points as ANSI C for any expression involving C operators and not involving overloaded operators. When operators are overloaded, the semantics change from operator sequencing to function-call sequencing. Microsoft C++ uses the following sequence points: -- Left operand of the logical AND operator (&&). The left operand of the logical AND operator is completely evaluated and all side effects completed before continuing. There is no guarantee that the right operand of the logical AND operator will be evaluated. +- Left operand of the logical AND operator (`&&`). The left operand of the logical AND operator is completely evaluated and all side effects completed before continuing. There's no guarantee that the right operand of the logical AND operator will be evaluated. -- Left operand of the logical OR operator (||). The left operand of the logical OR operator is completely evaluated and all side effects completed before continuing. There is no guarantee that the right operand of the logical OR operator will be evaluated. +- Left operand of the logical OR operator (`||`). The left operand of the logical OR operator is completely evaluated and all side effects completed before continuing. There's no guarantee that the right operand of the logical OR operator will be evaluated. - Left operand of the comma operator. The left operand of the comma operator is completely evaluated and all side effects completed before continuing. Both operands of the comma operator are always evaluated. diff --git a/docs/cpp/sizeof-operator.md b/docs/cpp/sizeof-operator.md index d7eb3a7029..ae040a3a9b 100644 --- a/docs/cpp/sizeof-operator.md +++ b/docs/cpp/sizeof-operator.md @@ -6,7 +6,7 @@ f1_keywords: ["sizeof_cpp"] helpviewer_keywords: ["sizeof operator"] ms.assetid: 8bc3b6fb-54a1-4eb7-ada0-05f8c5efc532 --- -# sizeof Operator +# `sizeof` Operator Yields the size of its operand with respect to the size of type **`char`**. @@ -17,7 +17,7 @@ Yields the size of its operand with respect to the size of type **`char`**. ``` sizeof unary-expression -sizeof ( type-name ) +sizeof ( type-name ) ``` ## Remarks @@ -98,5 +98,5 @@ sizeof array / sizeof array[0] ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/source-code-organization-cpp-templates.md b/docs/cpp/source-code-organization-cpp-templates.md index 378a88bd7e..993385a2a8 100644 --- a/docs/cpp/source-code-organization-cpp-templates.md +++ b/docs/cpp/source-code-organization-cpp-templates.md @@ -1,20 +1,20 @@ --- description: "Learn more about: Source code organization (C++ Templates)" title: "Source code organization (C++ Templates)" -ms.date: "04/22/2019" +ms.date: 06/30/2022 ms.assetid: 50569c5d-0219-4966-9bcf-a8689074ad1d --- # Source code organization (C++ Templates) -When defining a class template, you must organize the source code in such a way that the member definitions are visible to the compiler when it needs them. You have the choice of using the *inclusion model* or the *explicit instantiation* model. In the inclusion model, you include the member definitions in every file that uses a template. This approach is simplest and provides maximum flexibility in terms of what concrete types can be used with your template. Its disadvantage is that it can increase compilation times. The impact can be significant if a project and/or the included files themselves are large. With the explicit instantiation approach, the template itself instantiates concrete classes or class members for specific types. This approach can speed up compilation times, but it limits usage to only those classes that the template implementer has enabled ahead of time. In general, we recommend that you use the inclusion model unless the compilation times become a problem. +When defining a class template, you must organize the source code in such a way that the member definitions are visible to the compiler when it needs them. You have the choice of using the *inclusion model* or the *explicit instantiation* model. In the inclusion model, you include the member definitions in every file that uses a template. This approach is simplest and provides maximum flexibility in terms of what concrete types can be used with your template. Its disadvantage is that it can increase compilation times. The times can be significant if a project or the included files themselves are large. With the explicit instantiation approach, the template itself instantiates concrete classes or class members for specific types. This approach can speed up compilation times, but it limits usage to only those classes that the template implementer has enabled ahead of time. In general, we recommend that you use the inclusion model unless the compilation times become a problem. ## Background -Templates are not like ordinary classes in the sense that the compiler does not generate object code for a template or any of its members. There is nothing to generate until the template is instantiated with concrete types. When the compiler encounters a template instantiation such as `MyClass mc;` and no class with that signature exists yet, it generates a new class. It also attempts to generate code for any member functions that are used. If those definitions are in a file that is not #included, directly or indirectly, in the .cpp file that is being compiled, the compiler can't see them. From the compiler's point of view, this isn't necessarily an error because the functions may be defined in another translation unit, in which case the linker will find them. If the linker does not find that code, it raises an *unresolved external* error. +Templates aren't like ordinary classes in the sense that the compiler doesn't generate object code for a template or any of its members. There's nothing to generate until the template is instantiated with concrete types. When the compiler encounters a template instantiation such as `MyClass mc;` and no class with that signature exists yet, it generates a new class. It also attempts to generate code for any member functions that are used. If those definitions are in a file that isn't #included, directly or indirectly, in the .cpp file that is being compiled, the compiler can't see them. From the compiler's point of view, it's not necessarily an error. The functions may be defined in another translation unit where the linker will find them. If the linker doesn't find that code, it raises an *unresolved external* error. ## The inclusion model -The simplest and most common way to make template definitions visible throughout a translation unit, is to put the definitions in the header file itself. Any .cpp file that uses the template simply has to #include the header. This is the approach used in the Standard Library. +The simplest and most common way to make template definitions visible throughout a translation unit, is to put the definitions in the header file itself. Any *`.cpp`* file that uses the template simply has to `#include` the header. This approach is used in the Standard Library. ```cpp #ifndef MYARRAY @@ -44,17 +44,15 @@ public: #endif ``` -With this approach, the compiler has access to the complete template definition and can instantiate templates on-demand for any type. It is simple and relatively easy to maintain. However, the inclusion model does have a cost in terms of compilation times. This cost can be significant in large programs, especially if the template header itself #includes other headers. Every *`.cpp`* file that #includes the header will get its own copy of the function templates and all the definitions. The linker will generally be able to sort things out so that you do not end up with multiple definitions for a function, but it takes time to do this work. In smaller programs that extra compilation time is probably not significant. +With this approach, the compiler has access to the complete template definition and can instantiate templates on-demand for any type. It's simple and relatively easy to maintain. However, the inclusion model does have a cost in terms of compilation times. This cost can be significant in large programs, especially if the template header itself #includes other headers. Every *`.cpp`* file that #includes the header will get its own copy of the function templates and all the definitions. The linker will generally be able to sort things out so that you don't end up with multiple definitions for a function, but it takes time to do this work. In smaller programs that extra compilation time is probably not significant. ## The explicit instantiation model -If the inclusion model is not viable for your project, and you know definitively the set of types that will be used to instantiate a template, then you can separate out the template code into an *`.h`* and *`.cpp`* file, and in the *`.cpp`* file explicitly instantiate the templates. This will cause object code to be generated that the compiler will see when it encounters user instantiations. +If the inclusion model isn't viable for your project, and you know definitively the set of types that will be used to instantiate a template, then you can separate out the template code into an *`.h`* and *`.cpp`* file, and in the *`.cpp`* file explicitly instantiate the templates. This approach generates object code that the compiler will see when it encounters user instantiations. -You create an explicit instantiation by using the keyword template followed by the signature of the entity you want to instantiate. This can be a type or a member. If you explicitly instantiate a type, all members are instantiated. +You create an explicit instantiation by using the keyword **`template`** followed by the signature of the entity you want to instantiate. This entity can be a type or a member. If you explicitly instantiate a type, all members are instantiated. -```cpp -template MyArray; -``` +The header file `MyArray.h` declares template class `MyArray`: ```cpp //MyArray.h @@ -71,7 +69,11 @@ public: T& operator[](int i); }; #endif +``` +The source file `MyArray.cpp` explicitly instantiates `template MyArray` and `template MyArray`: + +```cpp //MyArray.cpp #include #include "MyArray.h" @@ -91,10 +93,11 @@ void MyArray::Print() cout << endl; } -template MyArray;template MyArray; +template MyArray; +template MyArray; ``` -In the previous example, the explicit instantiations are at the bottom of the .cpp file. A `MyArray` may be used only for **`double`** or `String` types. +In the previous example, the explicit instantiations are at the bottom of the *`.cpp`* file. A `MyArray` may be used only for **`double`** or `String` types. > [!NOTE] > In C++11 the **`export`** keyword was deprecated in the context of template definitions. In practical terms this has little impact because most compilers never supported it. diff --git a/docs/cpp/standard-conversions.md b/docs/cpp/standard-conversions.md index 2c6163b980..083ac66a0f 100644 --- a/docs/cpp/standard-conversions.md +++ b/docs/cpp/standard-conversions.md @@ -3,7 +3,6 @@ description: "Learn more about: Standard conversions" title: "Standard conversions" ms.date: "10/02/2019" helpviewer_keywords: ["standard conversions, categories of", "L-values [C++]", "conversions, standard"] -ms.assetid: ce7ac8d3-5c99-4674-8229-0672de05528d --- # Standard conversions @@ -117,7 +116,7 @@ In the preceding example, `u` is an **`unsigned short`** integral object that mu ## Floating point conversions -An object of a floating type can be safely converted to a more precise floating type — that is, the conversion causes no loss of significance. For example, conversions from **`float`** to **`double`** or from **`double`** to **`long double`** are safe, and the value is unchanged. +An object of a floating type can be safely converted to a more precise floating type—that is, the conversion causes no loss of significance. For example, conversions from **`float`** to **`double`** or from **`double`** to **`long double`** are safe, and the value is unchanged. An object of a floating type can also be converted to a less precise type, if it's in a range representable by that type. (See [Floating Limits](../cpp/floating-limits.md) for the ranges of floating types.) If the original value isn't representable precisely, it can be converted to either the next higher or the next lower representable value. The result is undefined if no such value exists. Consider the following example: @@ -125,7 +124,7 @@ An object of a floating type can also be converted to a less precise type, if it cout << (float)1E300 << endl; ``` -The maximum value representable by type **`float`** is 3.402823466E38 — a much smaller number than 1E300. Therefore, the number is converted to infinity, and the result is "inf". +The maximum value representable by type **`float`** is 3.402823466E38 which is a much smaller number than 1E300. Therefore, the number is converted to infinity, and the result is "inf". ## Conversions between integral and floating point types @@ -179,14 +178,16 @@ There are two cases in which a pointer to a class can be converted to a pointer The first case is when the specified base class is accessible and the conversion is unambiguous. For more information about ambiguous base-class references, see [Multiple base classes](../cpp/multiple-base-classes.md). -Whether a base class is accessible depends on the kind of inheritance used in derivation. Consider the inheritance illustrated in the following figure. +Whether a base class is accessible depends on the kind of inheritance used in derivation. Consider the inheritance illustrated in the following figure: -![Inheritance graph showing base class accessibility.](../cpp/media/vc38xa1.gif)
-Inheritance Graph for Illustration of Base-Class Accessibility +:::image type="complex" source="../cpp/media/vc38xa1.gif" alt-text="Diagram showing an inheritance graph and base class accessibility."::: +The diagram shows base class A. Class B inherits from A via private protected public. Class C inherits from B via public B. +:::image-end::: +*Inheritance graph illustrating base-class accessibility* The following table shows the base-class accessibility for the situation illustrated in the figure. -|Type of Function|Derivation|Conversion from

B* to A\* Legal?| +|Type of Function|Derivation|Conversion from

`B*` to `A*` legal?| |----------------------|----------------|-------------------------------------------| |External (not class-scoped) function|Private|No| ||Protected|No| @@ -241,7 +242,7 @@ A pointer to a function can be converted to type `void *`, if type `void *` is l Pointers to type **`void`** can be converted to pointers to any other type, but only with an explicit type cast (unlike in C). A pointer to any type can be converted implicitly to a pointer to type **`void`**. A pointer to an incomplete object of a type can be converted to a pointer to **`void`** (implicitly) and back (explicitly). The result of such a conversion is equal to the value of the original pointer. An object is considered incomplete if it's declared, but there's insufficient information available to determine its size or base class. -A pointer to any object that is not **`const`** or **`volatile`** can be implicitly converted to a pointer of type `void *`. +A pointer to any object that isn't **`const`** or **`volatile`** can be implicitly converted to a pointer of type `void *`. ### const and volatile pointers @@ -291,7 +292,7 @@ A pointer to a member of a base class can be converted to a pointer to a member - The inverse conversion, from pointer to derived class to base-class pointer, is accessible. -- The derived class does not inherit virtually from the base class. +- The derived class doesn't inherit virtually from the base class. When the left operand is a pointer to member, the right operand must be of pointer-to-member type or be a constant expression that evaluates to 0. This assignment is valid only in the following cases: diff --git a/docs/cpp/static-assert.md b/docs/cpp/static-assert.md index 727c96727c..9ca5dc04b5 100644 --- a/docs/cpp/static-assert.md +++ b/docs/cpp/static-assert.md @@ -24,7 +24,7 @@ static_assert( constant-expression ); // C++17 (Visual Studio 2017 and later) An integral constant expression that can be converted to a Boolean. If the evaluated expression is zero (false), the *string-literal* parameter is displayed and the compilation fails with an error. If the expression is nonzero (true), the **`static_assert`** declaration has no effect. *string-literal*\ -An message that is displayed if the *constant-expression* parameter is zero. The message is a string of characters in the [base character set](../c-language/ascii-character-set.md) of the compiler; that is, not [multibyte or wide characters](../c-language/multibyte-and-wide-characters.md). +A message that is displayed if the *constant-expression* parameter is zero. The message is a string of characters in the [base character set](../c-language/ascii-character-set.md) of the compiler; that is, not [multibyte or wide characters](../c-language/multibyte-and-wide-characters.md). ## Remarks diff --git a/docs/cpp/stdcall.md b/docs/cpp/stdcall.md index a6e9a50351..61ad524d75 100644 --- a/docs/cpp/stdcall.md +++ b/docs/cpp/stdcall.md @@ -13,6 +13,8 @@ The **`__stdcall`** calling convention is used to call Win32 API functions. The ## Syntax > *return-type* **`__stdcall`** *function-name*[**`(`** *argument-list* **`)`**] +> +> **`auto`** **`__stdcall`** *function-name*[**`(`** *argument-list* **`)`**] [ **`->`** *return-type* ] ## Remarks diff --git a/docs/cpp/storage-classes-cpp.md b/docs/cpp/storage-classes-cpp.md index 1ca1029099..9bdfb6dedd 100644 --- a/docs/cpp/storage-classes-cpp.md +++ b/docs/cpp/storage-classes-cpp.md @@ -1,18 +1,18 @@ --- title: "Storage classes (C++)" description: "In C++, the static, extern and thread_local keywords specify the lifetime, linkage, and memory location of a variable or function." -ms.date: 10/19/2021 +ms.date: 02/14/2022 f1_keywords: ["thread_local_cpp", "static_cpp", "register_cpp"] helpviewer_keywords: ["storage classes [C++], basic concepts"] ms.assetid: f10e1c56-6249-4eb6-b08f-09ab1eef1992 --- # Storage classes -A *storage class* in the context of C++ variable declarations is a type specifier that governs the lifetime, linkage, and memory location of objects. A given object can have only one storage class. Variables defined within a block have automatic storage unless otherwise specified using the **`extern`**, **`static`**, or **`thread_local`** specifiers. Automatic objects and variables have no linkage; they are not visible to code outside the block. Memory is allocated for them automatically when execution enters the block and de-allocated when the block is exited. +A *storage class* in the context of C++ variable declarations is a type specifier that governs the lifetime, linkage, and memory location of objects. A given object can have only one storage class. Variables defined within a block have automatic storage unless otherwise specified using the **`extern`**, **`static`**, or **`thread_local`** specifiers. Automatic objects and variables have no linkage; they aren't visible to code outside the block. Memory is allocated for them automatically when execution enters the block, and it's de-allocated when the block is exited. ## Notes -- The [`mutable`](../cpp/mutable-data-members-cpp.md) keyword may be considered a storage class specifier. However, it is only available in the member list of a class definition. +- The [`mutable`](../cpp/mutable-data-members-cpp.md) keyword may be considered a storage class specifier. However, it's only available in the member list of a class definition. - **Visual Studio 2010 and later:** The **`auto`** keyword is no longer a C++ storage-class specifier, and the **`register`** keyword is deprecated. **Visual Studio 2017 version 15.7 and later:** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): The **`register`** keyword is removed from the C++ language. Its use causes a diagnostic message: @@ -26,17 +26,17 @@ A *storage class* in the context of C++ variable declarations is a type specifie The **`static`** keyword can be used to declare variables and functions at global scope, namespace scope, and class scope. Static variables can also be declared at local scope. -Static duration means that the object or variable is allocated when the program starts and is deallocated when the program ends. External linkage means that the name of the variable is visible from outside the file in which the variable is declared. Conversely, internal linkage means that the name is not visible outside the file in which the variable is declared. By default, an object or variable that is defined in the global namespace has static duration and external linkage. The **`static`** keyword can be used in the following situations. +Static duration means that the object or variable is allocated when the program starts and is deallocated when the program ends. External linkage means that the name of the variable is visible from outside the file where the variable is declared. Conversely, internal linkage means that the name isn't visible outside the file where the variable is declared. By default, an object or variable that is defined in the global namespace has static duration and external linkage. The **`static`** keyword can be used in the following situations. 1. When you declare a variable or function at file scope (global and/or namespace scope), the **`static`** keyword specifies that the variable or function has internal linkage. When you declare a variable, the variable has static duration and the compiler initializes it to 0 unless you specify another value. 1. When you declare a variable in a function, the **`static`** keyword specifies that the variable retains its state between calls to that function. -1. When you declare a data member in a class declaration, the **`static`** keyword specifies that one copy of the member is shared by all instances of the class. A static data member must be defined at file scope. An integral data member that you declare as **`const static`** can have an initializer. +1. When you declare a data member in a class declaration, the **`static`** keyword specifies that one copy of the member is shared by all instances of the class. A `static` data member must be defined at file scope. An integral data member that you declare as **`const static`** can have an initializer. -1. When you declare a member function in a class declaration, the **`static`** keyword specifies that the function is shared by all instances of the class. A static member function cannot access an instance member because the function does not have an implicit **`this`** pointer. To access an instance member, declare the function with a parameter that is an instance pointer or reference. +1. When you declare a member function in a class declaration, the **`static`** keyword specifies that the function is shared by all instances of the class. A `static` member function can't access an instance member because the function doesn't have an implicit **`this`** pointer. To access an instance member, declare the function with a parameter that's an instance pointer or reference. -1. You cannot declare the members of a union as static. However, a globally declared anonymous union must be explicitly declared **`static`**. +1. You can't declare the members of a `union` as **`static`**. However, a globally declared anonymous `union` must be explicitly declared **`static`**. This example shows how a variable declared **`static`** in a function retains its state between calls to that function. @@ -113,7 +113,7 @@ int main() { 3 ``` -This example shows a local variable declared **`static`** in a member function. The **`static`** variable is available to the whole program; all instances of the type share the same copy of the **`static`** variable. +The following example shows a local variable declared **`static`** in a member function. The **`static`** variable is available to the whole program; all instances of the type share the same copy of the **`static`** variable. ```cpp // static3.cpp @@ -153,7 +153,7 @@ Objects and variables declared as **`extern`** declare an object that is defined ## `thread_local` (C++11) -A variable declared with the **`thread_local`** specifier is accessible only on the thread on which it is created. The variable is created when the thread is created, and destroyed when the thread is destroyed. Each thread has its own copy of the variable. On Windows, **`thread_local`** is functionally equivalent to the Microsoft-specific [`__declspec( thread )`](../cpp/thread.md) attribute. +A variable declared with the **`thread_local`** specifier is accessible only on the thread on which it's created. The variable is created when the thread is created, and it's destroyed when the thread is destroyed. Each thread has its own copy of the variable. On Windows, **`thread_local`** is functionally equivalent to the Microsoft-specific [`__declspec( thread )`](../cpp/thread.md) attribute. ```cpp thread_local float f = 42.0; // Global namespace. Not implicitly static. @@ -178,13 +178,15 @@ Things to note about the **`thread_local`** specifier: - The **`thread_local`** specifier may be combined with **`static`** or **`extern`**. -- You can apply **`thread_local`** only to data declarations and definitions; **`thread_local`** cannot be used on function declarations or definitions. +- You can apply **`thread_local`** only to data declarations and definitions; **`thread_local`** can't be used on function declarations or definitions. -- You can specify **`thread_local`** only on data items with static storage duration. This includes global data objects (both **`static`** and **`extern`**), local static objects, and static data members of classes. Any local variable declared **`thread_local`** is implicitly static if no other storage class is provided; in other words, at block scope **`thread_local`** is equivalent to **`thread_local static`**. +- You can specify **`thread_local`** only on data items with static storage duration, which includes global data objects (both **`static`** and **`extern`**), local static objects, and static data members of classes. Any local variable declared **`thread_local`** is implicitly static if no other storage class is provided; in other words, at block scope **`thread_local`** is equivalent to **`thread_local static`**. - You must specify **`thread_local`** for both the declaration and the definition of a thread local object, whether the declaration and definition occur in the same file or separate files. -On Windows, **`thread_local`** is functionally equivalent to [`__declspec(thread)`](../cpp/thread.md) except that *`*__declspec(thread)`** can be applied to a type definition and is valid in C code. Whenever possible, use **`thread_local`** because it is part of the C++ standard and is therefore more portable. +- We don't recommend you use **`thread_local`** variables with `std::launch::async`. For more information, see [`` functions](../standard-library/future-functions.md). + +On Windows, **`thread_local`** is functionally equivalent to [`__declspec(thread)`](../cpp/thread.md) except that *`*__declspec(thread)`** can be applied to a type definition and is valid in C code. Whenever possible, use **`thread_local`** because it's part of the C++ standard and is therefore more portable. ## register @@ -267,15 +269,15 @@ Destroying: Auto I1 Destroying: Static I3 ``` -This example demonstrates how and when the objects `I1`, `I2`, and `I3` are initialized and when they are destroyed. +This example demonstrates how and when the objects `I1`, `I2`, and `I3` are initialized and when they're destroyed. There are several points to note about the program: -- First, `I1` and `I2` are automatically destroyed when the flow of control exits the block in which they are defined. +- First, `I1` and `I2` are automatically destroyed when the flow of control exits the block in which they're defined. -- Second, in C++, it is not necessary to declare objects or variables at the beginning of a block. Furthermore, these objects are initialized only when the flow of control reaches their definitions. (`I2` and `I3` are examples of such definitions.) The output shows exactly when they are initialized. +- Second, in C++, it isn't necessary to declare objects or variables at the beginning of a block. Furthermore, these objects are initialized only when the flow of control reaches their definitions. (`I2` and `I3` are examples of such definitions.) The output shows exactly when they're initialized. -- Finally, static local variables such as `I3` retain their values for the duration of the program, but are destroyed as the program terminates. +- Finally, static local variables such as `I3` retain their values while the program runs, but are destroyed as the program terminates. ## See also diff --git a/docs/cpp/string-and-character-literals-cpp.md b/docs/cpp/string-and-character-literals-cpp.md index 561a75d272..643fd31dae 100644 --- a/docs/cpp/string-and-character-literals-cpp.md +++ b/docs/cpp/string-and-character-literals-cpp.md @@ -211,7 +211,7 @@ char u5 = '\U00000041'; // \U UCN 'A' Universal character names can't encode values in the surrogate code point range D800-DFFF. For Unicode surrogate pairs, specify the universal character name by using `\UNNNNNNNN`, where NNNNNNNN is the eight-digit code point for the character. The compiler generates a surrogate pair if necessary. -In C++03, the language only allowed a subset of characters to be represented by their universal character names, and allowed some universal character names that didn’t actually represent any valid Unicode characters. This mistake was fixed in the C++11 standard. In C++11, both character and string literals and identifiers can use universal character names. For more information on universal character names, see [Character Sets](../cpp/character-sets.md). For more information about Unicode, see [Unicode](/windows/win32/intl/unicode). For more information about surrogate pairs, see [Surrogate Pairs and Supplementary Characters](/windows/win32/Intl/surrogates-and-supplementary-characters). +In C++03, the language only allowed a subset of characters to be represented by their universal character names, and allowed some universal character names that didn't actually represent any valid Unicode characters. This mistake was fixed in the C++11 standard. In C++11, both character and string literals and identifiers can use universal character names. For more information on universal character names, see [Character Sets](../cpp/character-sets.md). For more information about Unicode, see [Unicode](/windows/win32/intl/unicode). For more information about surrogate pairs, see [Surrogate Pairs and Supplementary Characters](/windows/win32/Intl/surrogates-and-supplementary-characters). ## String literals @@ -331,7 +331,10 @@ const size_t byteSize = (wcslen(str) + 1) * sizeof(wchar_t); Notice that `strlen()` and `wcslen()` don't include the size of the terminating null character, whose size is equal to the element size of the string type: one byte on a `char*` or `char8_t*` string, two bytes on `wchar_t*` or `char16_t*` strings, and four bytes on `char32_t*` strings. -The maximum length of a string literal is 65,535 bytes. This limit applies to both narrow string literals and wide string literals. +Maximum length of a string literal after concatenation: + +* Visual Studio prior to 2022 version 17.0: the maximum length of a string literal after concatenation is 65,535 bytes. This applies to both narrow and wide string literals. +* From Visual Studio 2022 version 17.0 onwards: the maximum length of a string literal after concatenation is only limited by available memory. However, the size limit before concatenation is still 16,384 bytes ### Modifying string literals @@ -391,7 +394,7 @@ The actual result is a hexadecimal 5F, which is the ASCII code for an underscore "\x05" "five" // Use string splicing. ``` -`std::string` literals (and the related `std::u8string`, `std::u16string`, and `ste::u32string`) can be concatenated with the **`+`** operator that's defined for [`basic_string`](../standard-library/basic-string-class.md) types. They can also be concatenated in the same way as adjacent string literals. In both cases, the string encoding and the suffix must match: +`std::string` literals (and the related `std::u8string`, `std::u16string`, and `std::u32string`) can be concatenated with the **`+`** operator that's defined for [`basic_string`](../standard-library/basic-string-class.md) types. They can also be concatenated in the same way as adjacent string literals. In both cases, the string encoding and the suffix must match: ```cpp auto x1 = "hello" " " " world"; // OK diff --git a/docs/cpp/structured-exception-handling-c-cpp.md b/docs/cpp/structured-exception-handling-c-cpp.md index 832b1ef11d..ab3f3c5817 100644 --- a/docs/cpp/structured-exception-handling-c-cpp.md +++ b/docs/cpp/structured-exception-handling-c-cpp.md @@ -1,20 +1,20 @@ --- title: "Structured Exception Handling (C/C++)" description: "An overview of structured exception handling in Microsoft C/C++." -ms.date: 08/24/2020 +ms.date: 09/27/2022 helpviewer_keywords: ["termination handlers [C++], handling exceptions in C++", "structured exception handling [C++]", "try-catch keyword [C++], exception handlers", "C++ exception handling, termination handlers", "try-catch keyword [C++], termination handlers", "C++ exception handling, exception handlers"] ms.assetid: dd3b647d-c269-43a8-aab9-ad1458712976 --- # Structured Exception Handling (C/C++) -Structured exception handling (SEH) is a Microsoft extension to C to handle certain exceptional code situations, such as hardware faults, gracefully. Although Windows and Microsoft C++ support SEH, we recommend that you use ISO-standard C++ exception handling. It makes your code more portable and flexible. However, to maintain existing code or for particular kinds of programs, you still might have to use SEH. +Structured exception handling (SEH) is a Microsoft extension to C and C++ to handle certain exceptional code situations, such as hardware faults, gracefully. Although Windows and Microsoft C++ support SEH, we recommend that you use ISO-standard C++ exception handling in C++ code. It makes your code more portable and flexible. However, to maintain existing code or for particular kinds of programs, you still might have to use SEH. **Microsoft-specific:** ## Grammar > *`try-except-statement`* :
->  **`__try`** *`compound-statement`* **`__except`** **`(`** *`expression`* **`)`** *`compound-statement`* +>  **`__try`** *`compound-statement`* **`__except`** **`(`** *`filter-expression`* **`)`** *`compound-statement`* > > *`try-finally-statement`* :
>  **`__try`** *`compound-statement`* **`__finally`** *`compound-statement`* @@ -23,23 +23,23 @@ Structured exception handling (SEH) is a Microsoft extension to C to handle cert With SEH, you can ensure that resources, such as memory blocks and files, get released correctly if execution unexpectedly terminates. You can also handle specific problems—for example, insufficient memory—by using concise structured code that doesn't rely on **`goto`** statements or elaborate testing of return codes. -The `try-except` and `try-finally` statements referred to in this article are Microsoft extensions to the C language. They support SEH by enabling applications to gain control of a program after events that would otherwise terminate execution. Although SEH works with C++ source files, it's not specifically designed for C++. If you use SEH in a C++ program that you compile by using the [`/EHa` or `/EHsc`](../build/reference/eh-exception-handling-model.md) option, destructors for local objects are called but other execution behavior might not be what you expect. For an illustration, see the example later in this article. In most cases, instead of SEH we recommend that you use ISO-standard [C++ exception handling](../cpp/try-throw-and-catch-statements-cpp.md), which the Microsoft C++ compiler also supports. By using C++ exception handling, you can ensure that your code is more portable, and you can handle exceptions of any type. +The [`try-except`](./try-except-statement.md) and [`try-finally`](./try-finally-statement.md) statements referred to in this article are Microsoft extensions to the C and C++ languages. They support SEH by enabling applications to gain control of a program after events that would otherwise terminate execution. Although SEH works with C++ source files, it's not specifically designed for C++. If you use SEH in a C++ program that you compile by using the [`/EHa` or `/EHsc`](../build/reference/eh-exception-handling-model.md) option, destructors for local objects are called, but other execution behavior might not be what you expect. For an illustration, see the example later in this article. In most cases, instead of SEH we recommend that you use ISO-standard [C++ exception handling](../cpp/try-throw-and-catch-statements-cpp.md). By using C++ exception handling, you can ensure that your code is more portable, and you can handle exceptions of any type. If you have C code that uses SEH, you can mix it with C++ code that uses C++ exception handling. For information, see [Handle structured exceptions in C++](../cpp/exception-handling-differences.md). There are two SEH mechanisms: -- [Exception handlers](../cpp/writing-an-exception-handler.md), or **`__except`** blocks, which can respond to or dismiss the exception. +- [Exception handlers](../cpp/writing-an-exception-handler.md), or **`__except`** blocks, which can respond to or dismiss the exception based on the *`filter-expression`* value. For more information, see [`try-except` statement](./try-except-statement.md). -- [Termination handlers](../cpp/writing-a-termination-handler.md), or **`__finally`** blocks, which are always called, whether an exception causes termination or not. +- [Termination handlers](../cpp/writing-a-termination-handler.md), or **`__finally`** blocks, which are always called, whether an exception causes termination or not. For more information, see [`try-finally` statement](./try-finally-statement.md). These two kinds of handlers are distinct, but are closely related through a process known as *unwinding the stack*. When a structured exception occurs, Windows looks for the most recently installed exception handler that's currently active. The handler can do one of three things: -- Fail to recognize the exception and pass control to other handlers. +- Fail to recognize the exception and pass control to other handlers (`EXCEPTION_CONTINUE_SEARCH`). -- Recognize the exception but dismiss it. +- Recognize the exception but dismiss it (`EXCEPTION_CONTINUE_EXECUTION`). -- Recognize the exception and handle it. +- Recognize the exception and handle it (`EXCEPTION_EXECUTE_HANDLER`). The exception handler that recognizes the exception may not be in the function that was running when the exception occurred. It may be in a function much higher on the stack. The currently running function and all other functions on the stack frame are terminated. During this process, the stack is *unwound*. That is, local non-static variables of terminated functions get cleared from the stack. @@ -67,17 +67,17 @@ class TestClass public: ~TestClass() { - printf("Destroying TestClass!\r\n"); + printf("Destroying TestClass!\n"); } }; __declspec(noinline) void TestCPPEX() { #ifdef CPPEX - printf("Throwing C++ exception\r\n"); + printf("Throwing C++ exception\n"); throw std::exception(""); #else - printf("Triggering SEH exception\r\n"); + printf("Triggering SEH exception\n"); volatile int *pInt = 0x00000000; *pInt = 20; #endif @@ -97,7 +97,7 @@ int main() } __except(EXCEPTION_EXECUTE_HANDLER) { - printf("Executing SEH __except block\r\n"); + printf("Executing SEH __except block\n"); } return 0; diff --git a/docs/cpp/subscript-operator.md b/docs/cpp/subscript-operator.md index 86d55361d0..ae2835f635 100644 --- a/docs/cpp/subscript-operator.md +++ b/docs/cpp/subscript-operator.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Subscript Operator []" -title: "Subscript Operator []" +description: "Learn more about: Subscript Operator: []" +title: "Subscript Operator: []" ms.date: "11/04/2016" f1_keywords: ["[]"] helpviewer_keywords: ["operators [C++], subscript", "postfix operators [C++]", "[] operator", "subscript operator [C++], syntax"] -ms.assetid: 69c31494-52da-4dd0-8bbe-6ccbfd50f197 --- -# Subscript Operator [] +# Subscript Operator: `[]` ## Syntax @@ -16,7 +15,7 @@ postfix-expression [ expression ] ## Remarks -A postfix expression (which can also be a primary expression) followed by the subscript operator, **[ ]**, specifies array indexing. +A postfix expression (which can also be a primary expression) followed by the subscript operator, **`[ ]`**, specifies array indexing. For information about managed arrays in C++/CLI, see [Arrays](../extensions/arrays-cpp-component-extensions.md). @@ -44,7 +43,7 @@ A subscript expression can also have multiple subscripts, as follows: *expression1* **[** *expression2* **] [** *expression3* **]** ... -Subscript expressions associate from left to right. The leftmost subscript expression, *expression1* **[** *expression2* **]**, is evaluated first. The address that results from adding *expression1* and *expression2* forms a pointer expression; then *expression3* is added to this pointer expression to form a new pointer expression, and so on until the last subscript expression has been added. The indirection operator (\*) is applied after the last subscripted expression is evaluated, unless the final pointer value addresses an array type. +Subscript expressions associate from left to right. The leftmost subscript expression, *expression1* **[** *expression2* **]**, is evaluated first. The address that results from adding *expression1* and *expression2* forms a pointer expression; then *expression3* is added to this pointer expression to form a new pointer expression, and so on until the last subscript expression has been added. The [indirection operator (**`*`**)](../cpp/indirection-operator-star.md) is applied after the last subscripted expression is evaluated, unless the final pointer value addresses an array type. Expressions with multiple subscripts refer to elements of multidimensional arrays. A multidimensional array is an array whose elements are arrays. For example, the first element of a three-dimensional array is an array with two dimensions. The following example declares and initializes a simple two-dimensional array of characters: @@ -98,8 +97,8 @@ The subscript operator is commutative. Therefore, the expressions *array*[*index ## See also -[Postfix Expressions](../cpp/postfix-expressions.md)
-[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
-[Arrays](../cpp/arrays-cpp.md)
-[One-Dimensional Arrays](../c-language/one-dimensional-arrays.md)
-[Multidimensional Arrays](../c-language/multidimensional-arrays-c.md)
+[Postfix Expressions](../cpp/postfix-expressions.md)\ +[C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ +[Arrays](../cpp/arrays-cpp.md)\ +[One-Dimensional Arrays](../c-language/one-dimensional-arrays.md)\ +[Multidimensional Arrays](../c-language/multidimensional-arrays-c.md) diff --git a/docs/cpp/switch-statement-cpp.md b/docs/cpp/switch-statement-cpp.md index 54bcda7443..21afd60347 100644 --- a/docs/cpp/switch-statement-cpp.md +++ b/docs/cpp/switch-statement-cpp.md @@ -14,19 +14,19 @@ Allows selection among multiple sections of code, depending on the value of an i ## Syntax > *`selection-statement`*:\ ->      **`switch`** **`(`** *`init-statement`*optC++17 *`condition`* **`)`** *`statement`* +>   **`switch`** **`(`** *`init-statement`*optC++17 *`condition`* **`)`** *`statement`* > *`init-statement`*:\ ->      *`expression-statement`*\ ->      *`simple-declaration`* +>   *`expression-statement`*\ +>   *`simple-declaration`* > *`condition`*:\ ->      *`expression`*\ ->      *`attribute-specifier-seq`*opt *`decl-specifier-seq`* *`declarator`* *`brace-or-equal-initializer`* +>   *`expression`*\ +>   *`attribute-specifier-seq`*opt *`decl-specifier-seq`* *`declarator`* *`brace-or-equal-initializer`* > *`labeled-statement`*:\ ->      **`case`** *`constant-expression`* **`:`** *`statement`*\ ->      **`default`** **`:`** *`statement`* +>   **`case`** *`constant-expression`* **`:`** *`statement`*\ +>   **`default`** **`:`** *`statement`* ## Remarks diff --git a/docs/cpp/templates-and-name-resolution.md b/docs/cpp/templates-and-name-resolution.md index d54b1e2dd7..f6737fa2ec 100644 --- a/docs/cpp/templates-and-name-resolution.md +++ b/docs/cpp/templates-and-name-resolution.md @@ -64,7 +64,7 @@ A type is dependent if it depends on the template arguments. Specifically, a typ ## Type Dependence and Value Dependence -Names and expressions dependent on a template parameter are categorized as type dependent or value dependent, depending on whether the template parameter is a type parameter or a value parameter. Also, any identifiers declared in a template with a type dependent on the template argument are considered value dependent, as is a integral or enumeration type initialized with a value-dependent expression. +Names and expressions dependent on a template parameter are categorized as type dependent or value dependent, depending on whether the template parameter is a type parameter or a value parameter. Also, any identifiers declared in a template with a type dependent on the template argument are considered value dependent, as is an integral or enumeration type initialized with a value-dependent expression. Type-dependent and value-dependent expressions are expressions that involve variables that are type dependent or value dependent. These expressions can have semantics that differ, depending on the parameters used for the template. diff --git a/docs/cpp/templates-cpp.md b/docs/cpp/templates-cpp.md index b7b65afd82..93e8ddb094 100644 --- a/docs/cpp/templates-cpp.md +++ b/docs/cpp/templates-cpp.md @@ -207,7 +207,7 @@ int main() ## Template specialization -In some cases, it isn’t possible or desirable for a template to define exactly the same code for any type. For example, you might wish to define a code path to be executed only if the type argument is a pointer, or a std::wstring, or a type derived from a particular base class. In such cases you can define a *specialization* of the template for that particular type. When a user instantiates the template with that type, the compiler uses the specialization to generate the class, and for all other types, the compiler chooses the more general template. Specializations in which all parameters are specialized are *complete specializations*. If only some of the parameters are specialized, it is called a *partial specialization*. +In some cases, it isn't possible or desirable for a template to define exactly the same code for any type. For example, you might wish to define a code path to be executed only if the type argument is a pointer, or a std::wstring, or a type derived from a particular base class. In such cases you can define a *specialization* of the template for that particular type. When a user instantiates the template with that type, the compiler uses the specialization to generate the class, and for all other types, the compiler chooses the more general template. Specializations in which all parameters are specialized are *complete specializations*. If only some of the parameters are specialized, it is called a *partial specialization*. ```cpp template diff --git a/docs/cpp/temporary-objects.md b/docs/cpp/temporary-objects.md index 1beb350980..175bdaaa8c 100644 --- a/docs/cpp/temporary-objects.md +++ b/docs/cpp/temporary-objects.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Temporary Objects" -title: "Temporary Objects" -ms.date: "11/04/2016" +description: "Learn more about: Temporary objects" +title: "Temporary objects" +ms.date: 03/21/2022 helpviewer_keywords: ["temporary objects", "objects [C++], temporary"] -ms.assetid: 4c8cec02-391e-4225-9bc6-06d150201412 --- -# Temporary Objects +# Temporary objects -In some cases, it is necessary for the compiler to create temporary objects. These temporary objects can be created for the following reasons: +A temporary object is an unnamed object created by the compiler to store a temporary value. -- To initialize a **`const`** reference with an initializer of a type different from that of the underlying type of the reference being initialized. +## Remarks -- To store the return value of a function that returns a user-defined type. These temporaries are created only if your program does not copy the return value to an object. For example: +In some cases, it's necessary for the compiler to create temporary objects. These temporary objects can be created for the following reasons: + +- To initialize a **`const`** reference with an initializer of a type different from the underlying type of the reference being initialized. + +- To store the return value of a function that returns a user-defined type (UDT). These temporaries are created only if your program doesn't copy the return value to an object. For example: ```cpp UDT Func1(); // Declare a function that returns a user-defined @@ -24,17 +27,22 @@ In some cases, it is necessary for the compiler to create temporary objects. The // value. ``` - Because the return value is not copied to another object, a temporary object is created. A more common case where temporaries are created is during the evaluation of an expression where overloaded operator functions must be called. These overloaded operator functions return a user-defined type that often is not copied to another object. + Because the return value isn't copied to another object, a temporary object is created. A more common case where temporaries are created is during the evaluation of an expression where overloaded operator functions must be called. These overloaded operator functions return a user-defined type that often isn't copied to another object. - Consider the expression `ComplexResult = Complex1 + Complex2 + Complex3`. The expression `Complex1 + Complex2` is evaluated, and the result is stored in a temporary object. Next, the expression *temporary* `+ Complex3` is evaluated, and the result is copied to `ComplexResult` (assuming the assignment operator is not overloaded). + Consider the expression `ComplexResult = Complex1 + Complex2 + Complex3`. The expression `Complex1 + Complex2` is evaluated, and the result is stored in a temporary object. Next, the expression *temporary* `+ Complex3` is evaluated, and the result is copied to `ComplexResult` (assuming the assignment operator isn't overloaded). - To store the result of a cast to a user-defined type. When an object of a given type is explicitly converted to a user-defined type, that new object is constructed as a temporary object. -Temporary objects have a lifetime that is defined by their point of creation and the point at which they are destroyed. Any expression that creates more than one temporary object eventually destroys them in the reverse order in which they were created. The points at which destruction occurs are shown in the following table. +Temporary objects have a lifetime, defined by their point of creation and the point at which they're destroyed. Any expression that creates more than one temporary object eventually destroys them in reverse order of creation. + +When destruction of a temporary occurs depends on how it's used: + +- Temporaries used for initializing **`const`** references:\ + If an initializer isn't an l-value of the same type as the reference being initialized, a temporary of the underlying object type is created. It's initialized by the initialization expression. This temporary object is destroyed immediately after the reference object to which it's bound is destroyed. As this destruction can happen well after the expression that created the temporary, it's sometimes referred to as *lifetime extension*. + +- Temporaries created as an effect of expression evaluation:\ + All temporaries that don't fit in the first category, and that are created as an effect of expression evaluation, are destroyed at the end of the expression statement (that is, at the semicolon), or at the end of the controlling expressions for **`for`**, **`if`**, **`while`**, **`do`**, and **`switch`** statements. -### Destruction Points for Temporary Objects +## See also -|Reason Temporary Created|Destruction Point| -|------------------------------|-----------------------| -|Result of expression evaluation|All temporaries created as a result of expression evaluation are destroyed at the end of the expression statement (that is, at the semicolon), or at the end of the controlling expressions for **`for`**, **`if`**, **`while`**, **`do`**, and **`switch`** statements.| -|Initializing **`const`** references|If an initializer is not an l-value of the same type as the reference being initialized, a temporary of the underlying object type is created and initialized with the initialization expression. This temporary object is destroyed immediately after the reference object to which it is bound is destroyed.| +Herb Sutter's blog on [References, simply](https://herbsutter.com/2020/02/23/references-simply/) diff --git a/docs/cpp/this-pointer.md b/docs/cpp/this-pointer.md index 235b5aae2c..1b560dd372 100644 --- a/docs/cpp/this-pointer.md +++ b/docs/cpp/this-pointer.md @@ -1,13 +1,12 @@ --- -title: "this pointer" +title: "The this pointer" description: "The this pointer is a compiler-generated pointer to the current object in nonstatic member functions." -ms.date: "01/22/2020" +ms.date: 12/11/2023 f1_keywords: ["this_cpp"] helpviewer_keywords: ["nonstatic member functions [C++]", "pointers, to class instance", "this pointer"] -ms.assetid: 92e3256a-4ad9-4d46-8be1-d77fad90791f no-loc: [this, class, struct, union, sizeof, const, volatile] --- -# this pointer +# The `this` pointer The **`this`** pointer is a pointer accessible only within the nonstatic member functions of a **`class`**, **`struct`**, or **`union`** type. It points to the object for which the member function is called. Static member functions don't have a **`this`** pointer. @@ -20,7 +19,7 @@ this->member-identifier ## Remarks -An object's **`this`** pointer isn't part of the object itself. It's not reflected in the result of a **`sizeof`** statement on the object. When a nonstatic member function is called for an object, the compiler passes the object's address to the function as a hidden argument. For example, the following function call: +An object's **`this`** pointer isn't part of the object itself. It's not part of the result of a **`sizeof`** statement on the object. When a nonstatic member function is called for an object, the compiler passes the object's address to the function as a hidden argument. For example, the following function call: ```cpp myDate.setMonth( 3 ); @@ -59,7 +58,7 @@ if (&Object != this) { > [!NOTE] > Because the **`this`** pointer is nonmodifiable, assignments to the **`this`** pointer are not allowed. Earlier implementations of C++ allowed assignment to **`this`**. -Occasionally, the **`this`** pointer is used directly — for example, to manipulate self-referential data structures, where the address of the current object is required. +Occasionally, the **`this`** pointer is used directly—for example, to manipulate self-referential data structures, where the address of the current object is required. ## Example @@ -131,45 +130,26 @@ my buffer your buffer ``` -## Type of the this pointer +## Type of the `this` pointer -The **`this`** pointer's type can be modified in the function declaration by the **`const`** and **`volatile`** keywords. To declare a function that has either of these attributes, add the keyword(s) after the function argument list. +The **`this`** pointer's type changes depending on whether the function declaration includes the **`const`** and/or **`volatile`** keywords. The following syntax describes the type of **`this`** in a member function: -Consider an example: +[*`cv-qualifier-list`*] *`class-type`* **`* const this`** -```cpp -// type_of_this_pointer1.cpp -class Point -{ - unsigned X() const; -}; -int main() -{ -} -``` - -The preceding code declares a member function, `X`, in which the **`this`** pointer is treated as a **`const`** pointer to a **`const`** object. Combinations of *cv-mod-list* options can be used, but they always modify the object pointed to by the **`this`** pointer, not the pointer itself. The following declaration declares function `X`, where the **`this`** pointer is a **`const`** pointer to a **`const`** object: - -```cpp -// type_of_this_pointer2.cpp -class Point -{ - unsigned X() const; -}; -int main() -{ -} -``` - -The type of **`this`** in a member function is described by the following syntax. The *cv-qualifier-list* is determined from the member function's declarator. It can be **`const`** or **`volatile`** (or both). *class-type* is the name of the class: +The member function's declarator determines *`cv-qualifier-list`*. It can be **`const`** or **`volatile`** (or both). *`class-type`* is the name of the class. -[*cv-qualifier-list*] *class-type* **\* const this** +The **`this`** pointer can't be reassigned. The **`const`** or **`volatile`** qualifiers used in the member function declaration apply to the class instance the **`this`** pointer points at, in the scope of that function, as shown in the following table: -In other words, the **`this`** pointer is always a const pointer. It can't be reassigned. The **`const`** or **`volatile`** qualifiers used in the member function declaration apply to the class instance the **`this`** pointer points at, in the scope of that function. +| Member function declaration | type of `this` pointer for a class named `myClass` | +|---|---| +| `void Func()` | `myClass *` | +| `void Func() const` | `const myClass *` | +| `void Func() volatile` | `volatile myClass *` | +| `void Func() const volatile` | `const volatile myClass *` | -The following table explains more about how these modifiers work. +The following table explains more about `const` and `volatile`. -### Semantics of this modifiers +### Semantics of `this` modifiers |Modifier|Meaning| |--------------|-------------| @@ -180,7 +160,7 @@ It's an error to pass a **`const`** object to a member function that isn't **`co Similarly, it's also an error to pass a **`volatile`** object to a member function that isn't **`volatile`**. -Member functions declared as **`const`** can't change member data — in such functions, the **`this`** pointer is a pointer to a **`const`** object. +Member functions declared as **`const`** can't change member data. In `const` functions, the **`this`** pointer is a pointer to a **`const`** object. > [!NOTE] > Constructors and destructors can't be declared as **`const`** or **`volatile`**. They can, however, be invoked on **`const`** or **`volatile`** objects. diff --git a/docs/cpp/toc.yml b/docs/cpp/toc.yml index 58ff5f6729..35e1c6921a 100644 --- a/docs/cpp/toc.yml +++ b/docs/cpp/toc.yml @@ -102,6 +102,8 @@ items: href: ../cpp/declarations-and-definitions-cpp.md - name: Storage classes href: ../cpp/storage-classes-cpp.md + - name: alignas + href: ../cpp/alignas-specifier.md - name: auto href: ../cpp/auto-cpp.md - name: const @@ -158,7 +160,7 @@ items: href: ../cpp/function-call-operator-parens.md - name: "Indirection operator: *" href: ../cpp/indirection-operator-star.md - - name: Left shift and right shift operators (>> and <<) + - name: "Left shift and right shift operators: << and >>" href: ../cpp/left-shift-and-right-shift-operators-input-and-output.md - name: "Logical AND operator: &&" href: ../cpp/logical-and-operator-amp-amp.md @@ -186,7 +188,7 @@ items: href: ../cpp/scope-resolution-operator.md - name: sizeof operator href: ../cpp/sizeof-operator.md - - name: "Subscript operator:" + - name: "Subscript operator: []" href: ../cpp/subscript-operator.md - name: typeid operator href: ../cpp/typeid-operator.md @@ -554,6 +556,8 @@ items: href: ../cpp/modules-cpp.md - name: module, import, export href: ../cpp/import-export-module.md + - name: "Tutorial: Import the standard library as a module" + href: ../cpp/tutorial-import-stl-named-module.md - name: Named modules tutorial in C++ href: ../cpp/tutorial-named-modules-cpp.md - name: Templates @@ -690,6 +694,10 @@ items: href: ../cpp/general-rules-and-limitations.md - name: Using dllimport and dllexport in C++ classes href: ../cpp/using-dllimport-and-dllexport-in-cpp-classes.md + - name: empty_bases + href: ../cpp/empty-bases.md + - name: hybrid_patchable + href: ../cpp/hybrid-patchable.md - name: jitintrinsic href: ../cpp/jitintrinsic.md - name: naked diff --git a/docs/cpp/transporting-exceptions-between-threads.md b/docs/cpp/transporting-exceptions-between-threads.md index 6f6b018ced..bddcb01e69 100644 --- a/docs/cpp/transporting-exceptions-between-threads.md +++ b/docs/cpp/transporting-exceptions-between-threads.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Transporting exceptions between threads" title: "Transporting exceptions between threads" -ms.date: "05/07/2019" +description: "Learn more about: Transporting exceptions between threads" +ms.date: 05/02/2023 helpviewer_keywords: ["std::current_exception", "transporting exceptions between threads", "std::copy_exception", "exception_ptr", "std::exception_ptr", "std::rethrow_exception", "current_exception", "transport exceptions between threads", "copy_exception", "rethrow_exception", "move exceptions between threads"] -ms.assetid: 5c95d57b-acf5-491f-8122-57c5df0edd98 --- # Transporting exceptions between threads @@ -24,23 +23,23 @@ namespace std ### Parameters -*unspecified*\ +*`unspecified`*\ An unspecified internal class that is used to implement the `exception_ptr` type. -*p*\ +*`p`*\ An `exception_ptr` object that references an exception. -*E*\ +*`E`*\ A class that represents an exception. -*e*\ +*`e`*\ An instance of the parameter `E` class. ## Return value -The `current_exception` function returns an `exception_ptr` object that references the exception that is currently in progress. If no exception is in progress, the function returns an `exception_ptr` object that is not associated with any exception. +The `current_exception` function returns an `exception_ptr` object that references the exception that is currently in progress. If no exception is in progress, the function returns an `exception_ptr` object that isn't associated with any exception. -The `make_exception_ptr` function returns an `exception_ptr` object that references the exception specified by the *e* parameter. +The `make_exception_ptr` function returns an `exception_ptr` object that references the exception specified by the *`e`* parameter. ## Remarks @@ -52,7 +51,7 @@ However, if a secondary thread throws an exception, you want the primary thread ### Solution -To handle the previous scenario, the C++ Standard supports transporting an exception between threads. If a secondary thread throws an exception, that exception becomes the *current exception*. By analogy to the real world, the current exception is said to be *in flight*. The current exception is in flight from the time it is thrown until the exception handler that catches it returns. +To handle the previous scenario, the C++ Standard supports transporting an exception between threads. If a secondary thread throws an exception, that exception becomes the *current exception*. By analogy to the real world, the current exception is said to be *in flight*. The current exception is in flight from the time it's thrown until the exception handler that catches it returns. The secondary thread can catch the current exception in a **`catch`** block, and then call the `current_exception` function to store the exception in an `exception_ptr` object. The `exception_ptr` object must be available to the secondary thread and to the primary thread. For example, the `exception_ptr` object can be a global variable whose access is controlled by a mutex. The term *transport an exception* means an exception in one thread can be converted to a form that can be accessed by another thread. @@ -60,24 +59,24 @@ Next, the primary thread calls the `rethrow_exception` function, which extracts Finally, the primary thread can catch the current exception in a **`catch`** block and then process it or throw it to a higher level exception handler. Or, the primary thread can ignore the exception and allow the process to end. -Most applications do not have to transport exceptions between threads. However, this feature is useful in a parallel computing system because the system can divide work among secondary threads, processors, or cores. In a parallel computing environment, a single, dedicated thread can handle all the exceptions from the secondary threads and can present a consistent exception-handling model to any application. +Most applications don't have to transport exceptions between threads. However, this feature is useful in a parallel computing system because the system can divide work among secondary threads, processors, or cores. In a parallel computing environment, a single, dedicated thread can handle all the exceptions from the secondary threads and can present a consistent exception-handling model to any application. For more information about the C++ Standards committee proposal, search the Internet for document number N2179, titled "Language Support for Transporting Exceptions between Threads". ### Exception-handling models and compiler options -Your application's exception-handling model determines whether it can catch and transport an exception. Visual C++ supports three models that can handle C++ exceptions, structured exception handling (SEH) exceptions, and common language runtime (CLR) exceptions. Use the [/EH](../build/reference/eh-exception-handling-model.md) and [/clr](../build/reference/clr-common-language-runtime-compilation.md) compiler options to specify your application's exception-handling model. +Your application's exception-handling model determines whether it can catch and transport an exception. Visual C++ supports three models for handling C++ exceptions: [ISO-standard C++ exception handling](/cpp/cpp/errors-and-exception-handling-modern-cpp), [structured exception handling (SEH)](/windows/win32/debug/structured-exception-handling), and [common language runtime (CLR) exceptions](/cpp/extensions/exception-handling-cpp-component-extensions). Use the [`/EH`](../build/reference/eh-exception-handling-model.md) and [`/clr`](../build/reference/clr-common-language-runtime-compilation.md) compiler options to specify your application's exception-handling model. -Only the following combination of compiler options and programming statements can transport an exception. Other combinations either cannot catch exceptions, or can catch but cannot transport exceptions. +Only the following combination of compiler options and programming statements can transport an exception. Other combinations either can't catch exceptions, or can catch but can't transport exceptions. -- The **/EHa** compiler option and the **`catch`** statement can transport SEH and C++ exceptions. +- The **`/EHa`** compiler option and the **`catch`** statement can transport SEH and C++ exceptions. -- The **/EHa**, **/EHs**, and **/EHsc** compiler options and the **`catch`** statement can transport C++ exceptions. +- The **`/EHa`**, **`/EHs`**, and **`/EHsc`** compiler options and the **`catch`** statement can transport C++ exceptions. -- The **/CLR** compiler option and the **`catch`** statement can transport C++ exceptions. The **/CLR** compiler option implies specification of the **/EHa** option. Note that the compiler does not support transporting managed exceptions. This is because managed exceptions, which are derived from the [System.Exception class](../standard-library/exception-class.md), are already objects that you can move between threads by using the facilities of the common languange runtime. +- The **`/clr`** compiler option and the **`catch`** statement can transport C++ exceptions. The **`/clr`** compiler option implies specification of the **`/EHa`** option. The compiler doesn't support transporting managed exceptions. This is because managed exceptions, which are derived from the [System.Exception class](../standard-library/exception-class.md), are already objects that you can move between threads by using the facilities of the common language runtime. > [!IMPORTANT] - > We recommend that you specify the **/EHsc** compiler option and catch only C++ exceptions. You expose yourself to a security threat if you use the **/EHa** or **/CLR** compiler option and a **`catch`** statement with an ellipsis *exception-declaration* (`catch(...)`). You probably intend to use the **`catch`** statement to capture a few specific exceptions. However, the `catch(...)` statement captures all C++ and SEH exceptions, including unexpected ones that should be fatal. If you ignore or mishandle an unexpected exception, malicious code can use that opportunity to undermine the security of your program. + > We recommend that you specify the **`/EHsc`** compiler option and catch only C++ exceptions. You expose yourself to a security threat if you use the **`/EHa`** or **`/clr`** compiler option and a **`catch`** statement with an ellipsis *exception-declaration* (`catch(...)`). You probably intend to use the **`catch`** statement to capture a few specific exceptions. However, the `catch(...)` statement captures all C++ and SEH exceptions, including unexpected ones that should be fatal. If you ignore or mishandle an unexpected exception, malicious code can use that opportunity to undermine the security of your program. ## Usage @@ -85,17 +84,17 @@ The following sections describe how to transport exceptions by using the `except ## exception_ptr type -Use an `exception_ptr` object to reference the current exception or an instance of a user-specified exception. In the Microsoft implementation, an exception is represented by an [EXCEPTION_RECORD](/windows/win32/api/winnt/ns-winnt-exception_record) structure. Each `exception_ptr` object includes an exception reference field that points to a copy of the `EXCEPTION_RECORD` structure that represents the exception. +Use an `exception_ptr` object to reference the current exception or an instance of a user-specified exception. In the Microsoft implementation, an exception is represented by an [`EXCEPTION_RECORD`](/windows/win32/api/winnt/ns-winnt-exception_record) structure. Each `exception_ptr` object includes an exception reference field that points to a copy of the `EXCEPTION_RECORD` structure that represents the exception. -When you declare an `exception_ptr` variable, the variable is not associated with any exception. That is, its exception reference field is NULL. Such an `exception_ptr` object is called a *null exception_ptr*. +When you declare an `exception_ptr` variable, the variable isn't associated with any exception. That is, its exception reference field is NULL. Such an `exception_ptr` object is called a *null exception_ptr*. -Use the `current_exception` or `make_exception_ptr` function to assign an exception to an `exception_ptr` object. When you assign an exception to an `exception_ptr` variable, the variable's exception reference field points to a copy of the exception. If there is insufficient memory to copy the exception, the exception reference field points to a copy of a [std::bad_alloc](../standard-library/bad-alloc-class.md) exception. If the `current_exception` or `make_exception_ptr` function cannot copy the exception for any other reason, the function calls the [terminate](../c-runtime-library/reference/terminate-crt.md) function to exit the current process. +Use the `current_exception` or `make_exception_ptr` function to assign an exception to an `exception_ptr` object. When you assign an exception to an `exception_ptr` variable, the variable's exception reference field points to a copy of the exception. If there is insufficient memory to copy the exception, the exception reference field points to a copy of a [std::bad_alloc](../standard-library/bad-alloc-class.md) exception. If the `current_exception` or `make_exception_ptr` function can't copy the exception for any other reason, the function calls the [terminate](../c-runtime-library/reference/terminate-crt.md) function to exit the current process. -Despite its name, an `exception_ptr` object is not itself a pointer. It does not obey pointer semantics and cannot be used with the pointer member access (`->`) or indirection (`*`) operators. The `exception_ptr` object has no public data members or member functions. +Despite its name, an `exception_ptr` object isn't itself a pointer. It doesn't obey pointer semantics and can't be used with the pointer member access (`->`) or indirection (`*`) operators. The `exception_ptr` object has no public data members or member functions. ### Comparisons -You can use the equal (`==`) and not-equal (`!=`) operators to compare two `exception_ptr` objects. The operators do not compare the binary value (bit pattern) of the `EXCEPTION_RECORD` structures that represent the exceptions. Instead, the operators compare the addresses in the exception reference field of the `exception_ptr` objects. Consequently, a null `exception_ptr` and the NULL value compare as equal. +You can use the equal (`==`) and not-equal (`!=`) operators to compare two `exception_ptr` objects. The operators don't compare the binary value (bit pattern) of the `EXCEPTION_RECORD` structures that represent the exceptions. Instead, the operators compare the addresses in the exception reference field of the `exception_ptr` objects. So, a null `exception_ptr` and the NULL value compare as equal. ## current_exception function @@ -105,21 +104,21 @@ Call the `current_exception` function in a **`catch`** block. If an exception is The `current_exception` function captures the exception that is in flight regardless of whether the **`catch`** statement specifies an [exception-declaration](../cpp/try-throw-and-catch-statements-cpp.md) statement. -The destructor for the current exception is called at the end of the **`catch`** block if you do not rethrow the exception. However, even if you call the `current_exception` function in the destructor, the function returns an `exception_ptr` object that references the current exception. +The destructor for the current exception is called at the end of the **`catch`** block if you don't rethrow the exception. However, even if you call the `current_exception` function in the destructor, the function returns an `exception_ptr` object that references the current exception. -Successive calls to the `current_exception` function return `exception_ptr` objects that refer to different copies of the current exception. Consequently, the objects compare as unequal because they refer to different copies, even though the copies have the same binary value. +Successive calls to the `current_exception` function return `exception_ptr` objects that refer to different copies of the current exception. So, the objects compare as unequal because they refer to different copies, even though the copies have the same binary value. ### SEH exceptions -If you use the **/EHa** compiler option, you can catch an SEH exception in a C++ **`catch`** block. The `current_exception` function returns an `exception_ptr` object that references the SEH exception. And the `rethrow_exception` function throws the SEH exception if you call it with thetransported `exception_ptr` object as its argument. +If you use the **`/EHa`** compiler option, you can catch an SEH exception in a C++ **`catch`** block. The `current_exception` function returns an `exception_ptr` object that references the SEH exception. And the `rethrow_exception` function throws the SEH exception if you call it with the transported `exception_ptr` object as its argument. The `current_exception` function returns a null `exception_ptr` if you call it in an SEH **`__finally`** termination handler, an **`__except`** exception handler, or the **`__except`** filter expression. -A transported exception does not support nested exceptions. A nested exception occurs if another exception is thrown while an exception is being handled. If you catch a nested exception, the `EXCEPTION_RECORD.ExceptionRecord` data member points to a chain of `EXCEPTION_RECORD` structures that describe the associated exceptions. The `current_exception` function does not support nested exceptions because it returns an `exception_ptr` object whose `ExceptionRecord` data member is zeroed out. +A transported exception doesn't support nested exceptions. A nested exception occurs if another exception is thrown while an exception is being handled. If you catch a nested exception, the `EXCEPTION_RECORD.ExceptionRecord` data member points to a chain of `EXCEPTION_RECORD` structures that describe the associated exceptions. The `current_exception` function doesn't support nested exceptions because it returns an `exception_ptr` object whose `ExceptionRecord` data member is zeroed out. If you catch an SEH exception, you must manage the memory referenced by any pointer in the `EXCEPTION_RECORD.ExceptionInformation` data member array. You must guarantee that the memory is valid during the lifetime of the corresponding `exception_ptr` object, and that the memory is freed when the `exception_ptr` object is deleted. -You can use structured exception (SE) translator functions together with the transport exceptions feature. If an SEH exception is translated to a C++ exception, the `current_exception` function returns an `exception_ptr` that references the translated exception instead of the original SEH exception. The `rethrow_exception` function subsequently throws the translated exception, not the original exception. For more information about SE translator functions, see [_set_se_translator](../c-runtime-library/reference/set-se-translator.md). +You can use structured exception (SE) translator functions together with the transport exceptions feature. If an SEH exception is translated to a C++ exception, the `current_exception` function returns an `exception_ptr` that references the translated exception instead of the original SEH exception. The `rethrow_exception` function throws the translated exception, not the original exception. For more information about SE translator functions, see [_set_se_translator](../c-runtime-library/reference/set-se-translator.md). ## rethrow_exception function @@ -133,7 +132,7 @@ The `make_exception_ptr` function takes an instance of a class as its argument a Calling the `make_exception_ptr` function is equivalent to throwing a C++ exception, catching it in a **`catch`** block, and then calling the `current_exception` function to return an `exception_ptr` object that references the exception. The Microsoft implementation of the `make_exception_ptr` function is more efficient than throwing and then catching an exception. -An application typically does not require the `make_exception_ptr` function, and we discourage its use. +An application typically doesn't require the `make_exception_ptr` function, and we discourage its use. ## Example @@ -241,10 +240,10 @@ exception_ptr 1: Caught a myException exception. ## Requirements -**Header:** \ +**Header:** `` ## See also -[Exception Handling](../cpp/exception-handling-in-visual-cpp.md)
-[/EH (Exception Handling Model)](../build/reference/eh-exception-handling-model.md)
-[/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) +[Exception Handling](../cpp/exception-handling-in-visual-cpp.md)\ +[`/EH` (Exception Handling Model)](../build/reference/eh-exception-handling-model.md)\ +[`/clr` (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) diff --git a/docs/cpp/try-finally-statement.md b/docs/cpp/try-finally-statement.md index da5bcbcc20..538555ed27 100644 --- a/docs/cpp/try-finally-statement.md +++ b/docs/cpp/try-finally-statement.md @@ -4,7 +4,6 @@ description: "The Microsoft C++ reference to the __try and __finally structured ms.date: 08/25/2020 f1_keywords: ["__try", "_try", "__leave_cpp", "__leave", "__finally_cpp", "__try_cpp", "__finally", "_finally"] helpviewer_keywords: ["__try keyword [C++]", "__finally keyword [C++]", "__leave keyword [C++]", "try-catch keyword [C++], try-finally keyword", "try-finally keyword [C++]", "__finally keyword [C++], try-finally statement syntax", "__leave keyword [C++], try-finally statement", "structured exception handling [C++], try-finally"] -ms.assetid: 826e0347-ddfe-4f6e-a7bc-0398e0edc7c2 --- # `try-finally` statement @@ -47,12 +46,14 @@ Control reaches a **`__try`** statement by simple sequential execution (fall thr A **`__finally`** statement doesn't block searching for an appropriate exception handler. -If an exception occurs in the **`__try`** block, the operating system must find a handler for the exception or the program will fail. If a handler is found, any and all **`__finally`** blocks are executed and execution resumes in the handler. +If an exception occurs in the **`__try`** block, the operating system must find a handler for the exception, or the program will fail. If a handler is found, any and all **`__finally`** blocks are executed and execution resumes in the handler. For example, suppose a series of function calls links function A to function D, as shown in the following figure. Each function has one termination handler. If an exception is raised in function D and handled in A, the termination handlers are called in this order as the system unwinds the stack: D, C, B. -![Diagram of the order of termination handler execution.](../cpp/media/vc38cx1.gif)
-Order of Termination-Handler Execution +:::image type="complex" source="../cpp/media/vc38cx1.gif" alt-text="Diagram of the order of termination handler execution."::: +The diagram starts with function A, which calls function B, which calls function C, which calls function D. Function D raises an exception. The termination handlers are then called in this order: D's termination handler, then C's, then B's, and then A handles the exception. +:::image-end::: +*Order of termination-handler execution* > [!NOTE] > The behavior of try-finally is different from some other languages that support the use of **`finally`**, such as C#. A single **`__try`** may have either, but not both, of **`__finally`** and **`__except`**. If both are to be used together, an outer try-except statement must enclose the inner try-finally statement. The rules specifying when each block executes are also different. diff --git a/docs/cpp/try-throw-and-catch-statements-cpp.md b/docs/cpp/try-throw-and-catch-statements-cpp.md index d18bac1627..602b308056 100644 --- a/docs/cpp/try-throw-and-catch-statements-cpp.md +++ b/docs/cpp/try-throw-and-catch-statements-cpp.md @@ -1,10 +1,9 @@ --- description: "Learn more about: try, throw, and catch Statements (C++)" title: "try, throw, and catch Statements (C++)" -ms.date: "11/04/2016" +ms.date: 02/01/2023 f1_keywords: ["catch_cpp", "try_cpp", "throw_cpp"] helpviewer_keywords: ["catch keyword [C++]", "keywords [C++], exception handling", "C++ exception handling, statement syntax", "try-catch keyword [C++], about try-catch exception handling", "throw keyword [C++]", "try-catch keyword [C++]", "try-catch keyword [C++], exception handling", "throwing exceptions [C++], throw keyword", "try-catch keyword [C++], throw keyword [C++]s", "throwing exceptions [C++], implementing C++ exception handling", "throwing exceptions [C++]", "throw keyword [C++], throw() vs. throw(...)"] -ms.assetid: 15e6a87b-b8a5-4032-a7ef-946c644ba12a --- # try, throw, and catch Statements (C++) @@ -12,7 +11,7 @@ To implement exception handling in C++, you use **`try`**, **`throw`**, and **`c First, use a **`try`** block to enclose one or more statements that might throw an exception. -A **`throw`** expression signals that an exceptional condition—often, an error—has occurred in a **`try`** block. You can use an object of any type as the operand of a **`throw`** expression. Typically, this object is used to communicate information about the error. In most cases, we recommend that you use the [std::exception](../standard-library/exception-class.md) class or one of the derived classes that are defined in the standard library. If one of those is not appropriate, we recommend that you derive your own exception class from `std::exception`. +A **`throw`** expression signals that an exceptional condition—often, an error—has occurred in a **`try`** block. You can use an object of any type as the operand of a **`throw`** expression. Typically, this object is used to communicate information about the error. In most cases, we recommend that you use the [`std::exception`](../standard-library/exception-class.md) class or one of the derived classes that are defined in the standard library. If one of those isn't appropriate, we recommend that you derive your own exception class from `std::exception`. To handle exceptions that may be thrown, implement one or more **`catch`** blocks immediately following a **`try`** block. Each **`catch`** block specifies the type of exception it can handle. @@ -54,9 +53,9 @@ MyData GetNetworkResource() ## Remarks -The code after the **`try`** clause is the guarded section of code. The **`throw`** expression *throws*—that is, raises—an exception. The code block after the **`catch`** clause is the exception handler. This is the handler that *catches* the exception that's thrown if the types in the **`throw`** and **`catch`** expressions are compatible. For a list of rules that govern type-matching in **`catch`** blocks, see [How Catch Blocks are Evaluated](../cpp/how-catch-blocks-are-evaluated-cpp.md). If the **`catch`** statement specifies an ellipsis (...) instead of a type, the **`catch`** block handles every type of exception. When you compile with the [/EHa](../build/reference/eh-exception-handling-model.md) option, these can include C structured exceptions and system-generated or application-generated asynchronous exceptions such as memory protection, divide-by-zero, and floating-point violations. Because **`catch`** blocks are processed in program order to find a matching type, an ellipsis handler must be the last handler for the associated **`try`** block. Use `catch(...)` with caution; do not allow a program to continue unless the catch block knows how to handle the specific exception that is caught. Typically, a `catch(...)` block is used to log errors and perform special cleanup before program execution is stopped. +The code after the **`try`** clause is the guarded section of code. The **`throw`** expression *throws*—that is, raises—an exception. The code block after the **`catch`** clause is the exception handler. This is the handler that *catches* the exception that's thrown if the types in the **`throw`** and **`catch`** expressions are compatible. For a list of rules that govern type-matching in **`catch`** blocks, see [How Catch Blocks are Evaluated](../cpp/how-catch-blocks-are-evaluated-cpp.md). If the **`catch`** statement specifies an ellipsis (...) instead of a type, the **`catch`** block handles every type of exception. When you compile with the [`/EHa`](../build/reference/eh-exception-handling-model.md) option, these can include C structured exceptions and system-generated or application-generated asynchronous exceptions such as memory protection, divide-by-zero, and floating-point violations. Because **`catch`** blocks are processed in program order to find a matching type, an ellipsis handler must be the last handler for the associated **`try`** block. Use `catch(...)` with caution; don't allow a program to continue unless the catch block knows how to handle the specific exception that is caught. Typically, a `catch(...)` block is used to log errors and perform special cleanup before program execution is stopped. -A **`throw`** expression that has no operand re-throws the exception currently being handled. We recommend this form when re-throwing the exception, because this preserves the original exception’s polymorphic type information. Such an expression should only be used in a **`catch`** handler or in a function that's called from a **`catch`** handler. The re-thrown exception object is the original exception object, not a copy. +A **`throw`** expression that has no operand rethrows the exception currently being handled. We recommend this form when rethrowing the exception, because this preserves the original exception's polymorphic type information. Such an expression should only be used in a **`catch`** handler or in a function that's called from a **`catch`** handler. The rethrown exception object is the original exception object, not a copy. ```cpp try { @@ -76,4 +75,4 @@ catch(...) { [Modern C++ best practices for exceptions and error handling](../cpp/errors-and-exception-handling-modern-cpp.md)
[Keywords](../cpp/keywords-cpp.md)
[Unhandled C++ Exceptions](../cpp/unhandled-cpp-exceptions.md)
-[__uncaught_exception](../c-runtime-library/reference/uncaught-exception.md) +[`__uncaught_exception`](../c-runtime-library/reference/uncaught-exception.md) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md new file mode 100644 index 0000000000..b2c961353f --- /dev/null +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -0,0 +1,236 @@ +--- +title: "Tutorial: Import the standard library (STL) using modules from the command line (C++)" +ms.date: 01/29/2024 +ms.topic: "tutorial" +author: "tylermsft" +ms.author: "twhitney" +helpviewer_keywords: ["modules [C++]", "modules [C++]", "named modules [C++], import standard library (STL) using named modules"] +description: Learn how to import the C++ standard library (STL) using modules from the command line +--- + +# Tutorial: Import the C++ standard library using modules from the command line + +Learn how to import the C++ standard library using C++ library modules. This results in faster compilation and is more robust than using header files or header units or precompiled headers (PCH). + +In this tutorial, learn about: + +- How to import the standard library as a module from the command line. +- The performance and usability benefits of modules. +- The two standard library modules `std` and `std.compat` and the difference between them. + +## Prerequisites + +This tutorial requires Visual Studio 2022 17.5 or later. + +## Introduction to standard library modules + +Header file semantics can change depending on macro definitions, the order in which you include them, and they slow compilation. Modules solve these problems. + +It's now possible to import the standard library as a module instead of as a tangle of header files. This is much faster and more robust than including header files or header units or precompiled headers (PCH). + +The C++23 standard library introduces two named modules: `std` and `std.compat`: + +- `std` exports the declarations and names defined in the C++ standard library namespace `std`, such as `std::vector`. It also exports the contents of C wrapper headers such as `` and ``, which provide functions like `std::printf()`. C functions defined in the global namespace, such as `::printf()`, aren't exported. This improves the situation where including a C wrapper header like `` *also* includes C header files like `stdio.h`, which bring in the C global namespace versions. This isn't a problem if you import `std`. +- `std.compat` exports everything in `std` and adds the C runtime global namespaces such as `::printf`, `::fopen`, `::size_t`, `::strlen`, and so on. The `std.compat` module makes it easier to work with codebases that refer to many C runtime functions/types in the global namespace. + +The compiler imports the entire standard library when you use `import std;` or `import std.compat;` and does it faster than bringing in a single header file. It's faster to bring in the entire standard library with `import std;` (or `import std.compat`) than to `#include `, for example. + +Because named modules don't expose macros, macros like `assert`, `errno`, `offsetof`, `va_arg`, and others aren't available when you import `std` or `std.compat`. See [Standard library named module considerations](#standard-library-named-module-considerations) for workarounds. + +## About C++ modules + +Header files are how declarations and definitions have been shared between source files in C++. Before standard library modules, you'd include the part of the standard library you needed with a directive like `#include `. Header files are fragile and difficult to compose because their semantics may change depending on the order you include them, or whether certain macros are defined. They also slow compilation because they're reprocessed by every source file that includes them. + +C++20 introduces a modern alternative called *modules*. In C++23, we were able to capitalize on module support to introduce named modules to represent the standard library. + +Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules aren't fragile and are easier to compose because their semantics don't change due to macro definitions or the order in which you import them. The compiler can process modules much faster than it can process `#include` files, and uses less memory at compile time as well. Named modules don't expose macro definitions or private implementation details. + +This article demonstrates the new and best way to consume the standard library. For more information about alternative ways to consume the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). + +## Import the standard library with `std` + +The following examples demonstrate how to consume the standard library as a module using the command line compiler. For information about how to do this in the Visual Studio IDE, see [Build ISO C++23 Standard Library Modules](..\build\reference\c-cpp-prop-page.md#build-iso-c23-standard-library-modules). + +The statement `import std;` or `import std.compat;` imports the standard library into your application. But first, you must compile the standard library named modules into binary form. The following steps demonstrate how. + +### Example: How to build and import `std` + +1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. +1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation. +1. Compile the `std` named module with the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" + ``` + + If you get errors, ensure that you're using the correct version of the command prompt. + + Compile the `std` named module using the same compiler settings that you intend to use with the code that imports the built module. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. + + Using the previous compiler command, the compiler outputs two files: + - `std.ifc` is the compiled binary representation of the named module interface that the compiler consults to process the `import std;` statement. This is a compile-time only artifact. It doesn't ship with your application. + - `std.obj` contains the implementation of the named module. Add `std.obj` to the command line when you compile the sample app to statically link the functionality you use from the standard library into your application. + + The key command-line switches in this example are: + + | Switch | Meaning | + |---|---| + | [`/std:c++:latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | + | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | + | [`/W4`](../build/reference//compiler-option-warning-level.md) | Using /W4 is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | + | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | + + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo:"somethingelse"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file name is `std.obj` by default because we're compiling the module file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. + +1. Import the `std` library you built by first creating a file named `importExample.cpp` with the following content: + + ```cpp + // requires /std:c++latest + + import std; + + int main() + { + std::cout << "Import the STL library for best performance\n"; + std::vector v{5, 5, 5}; + for (const auto& e : v) + { + std::cout << e; + } + } + ``` + + In the preceding code, `import std;` replaces `#include ` and `#include `. The statement `import std;` makes all of the standard library available with one statement. Importing the entire standard library is often much faster than processing a single standard library header file such as `#include `. + +1. Compile the example by using the following command in the same directory as the previous step: + + ```cmd + cl /c /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp + link importExample.obj std.obj + ``` + + It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it's located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + + In this example, compiling the source code and linking the module's implementation into the application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. + + If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Put it before any `.cpp` files that consume the `std` module. + + By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the executable file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: + + ```cmd + cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp + ``` + + Given the previous command line, the compiler produces an executable named `importExample.exe`. When you run it, it produces the following output: + + ```output + Import the STL library for best performance + 555 + ``` + +## Import the standard library and global C functions with `std.compat` + +The C++ standard library includes the ISO C standard library. The `std.compat` module provides all of the functionality of the `std` module like `std::vector`, `std::cout`, `std::printf`, `std::scanf`, and so on. But it also provides the global namespace versions of these functions such as `::printf`, `::scanf`, `::fopen`, `::size_t`, and so on. + +The `std.compat` named module is a compatibility layer provided to ease migrating existing code that refers to C runtime functions in the global namespace. If you want to avoid adding names to the global namespace, use `import std;`. If you need to ease migrating a codebase that uses many unqualified (global namespace) C runtime functions, use `import std.compat;`. This provides the global namespace C runtime names so that you don't have to qualify all the global names with `std::`. If you don't have any existing code that uses the global namespace C runtime functions, then you don't need to use `import std.compat;`. If you only call a few C runtime functions in your code, it may be better to use `import std;` and qualify the few global namespace C runtime names that need it with `std::`. For example, `std::printf()`. If you see an error like `error C3861: 'printf': identifier not found` when you try to compile your code, consider using `import std.compat;` to import the global namespace C runtime functions. + +### Example: How to build and import `std.compat` + +Before you can use `import std.compat;` you must compile the module interface file found in source code form in `std.compat.ixx`. Visual Studio ships the source code for the module so that you can compile the module using the compiler settings that match your project. The steps are similar to for building the `std` named module. The `std` named module is built first because `std.compat` depends on it: + +1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt. +1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors. +1. Compile the `std` and `std.compat` named modules with the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" + ``` + + You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that will import them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option. + + If you get errors, ensure that you're using the correct version of the command prompt. + + The compiler outputs four files from the previous two steps: + - `std.ifc` is the compiled binary named module interface that the compiler consults to process the `import std;` statement. The compiler also consults `std.ifc` to process `import std.compat;` because `std.compat` builds on `std`. This is a compile-time only artifact. It doesn't ship with your application. + - `std.obj` contains the implementation of the standard library. + - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application. + - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. + + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo:"somethingelse"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. + +1. Import the `std.compat` library by first creating a file named `stdCompatExample.cpp` with the following content: + + ```cpp + import std.compat; + + int main() + { + printf("Import std.compat to get global names like printf()\n"); + + std::vector v{5, 5, 5}; + for (const auto& e : v) + { + printf("%i", e); + } + } + ``` + + In the preceding code, `import std.compat;` replaces `#include ` and `#include `. The statement `import std.compat;` makes the standard library and C runtime functions available with one statement. Importing this named module, which includes the C++ standard library and C runtime library global namespace functions, is faster than processing a single `#include` like `#include `. + +1. Compile the example by using the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj + ``` + + We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + + When you import `std.compat`, you must link against both `std.compat` and `std.obj` because `std.compat` uses code in `std.obj`. + + If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: + + ```cmd + cl /c /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj + ``` + + In this example, compiling the source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. + + The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: + + ```output + Import std.compat to get global names like printf() + 555 + ``` + +## Standard library named module considerations + +Versioning for named modules is the same as for headers. The `.ixx` named module files are installed alongside the headers, for example: `"%VCToolsInstallDir%\modules\std.ixx`, which resolves to `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.38.33130\modules\std.ixx` in the version of the tools used at the time of this writing. Select the version of the named module the same way you choose the version of the header file to use--by the directory you refer to them from. + +Don't mix and match importing header units and named modules. For example, don't `import ;` and `import std;` in the same file. + +Don't mix and match importing C++ standard library header files and the named modules `std` or `std.compat`. For example, don't `#include ` and `import std;` in the same file. However, you can include C headers and import named modules in the same file. For example, you can `import std;` and `#include ` in the same file. Just don't include the C++ standard library version ``. + +You don't have to defend against importing a module multiple times. That is, you don't need `#ifndef` style header guards in modules. The compiler knows when it has already imported a named module and ignores duplicate attempts to do so. + +If you need to use the `assert()` macro, then `#include `. + +If you need to use the `errno` macro, `#include `. Because named modules don't expose macros, this is the workaround if you need to check for errors from ``, for example. + +Macros such as `NAN`, `INFINITY`, and `INT_MIN` are defined by ``, which you can include. However, if you `import std;` you can use `numeric_limits::quiet_NaN()` and `numeric_limits::infinity()` instead of `NAN` and `INFINITY`, and `std::numeric_limits::min()` instead of `INT_MIN`. + +## Summary + +In this tutorial, you've imported the standard library using modules. Next, learn about creating and importing your own modules in [Named modules tutorial in C++](tutorial-named-modules-cpp.md). + +## See also + +[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md)\ +[Overview of modules in C++](modules-cpp.md)\ +[A Tour of C++ Modules in Visual Studio](https://devblogs.microsoft.com/cppblog/a-tour-of-cpp-modules-in-visual-studio)\ +[Moving a project to C++ named Modules](https://devblogs.microsoft.com/cppblog/moving-a-project-to-cpp-named-modules) diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index 883e2e320a..776ac6f114 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -1,15 +1,17 @@ --- title: "Named modules tutorial in C++" -ms.date: "12/10/2021" +ms.date: 02/13/2025 ms.topic: "tutorial" +author: "tylermsft" +ms.author: "twhitney" helpviewer_keywords: ["modules [C++]", "modules [C++], named modules tutorial"] description: Named modules in C++20 provide a modern alternative to header files. --- # Named modules tutorial (C++) - This tutorial introduces the basics of creating C++20 modules. Modules are a new way to componentize C++ programs, replacing the venerable header file. You'll learn how modules are an improvement on header files and build an app that shows how to create and consume a module. +This tutorial is about creating C++20 modules. Modules are a significant improvement on header files. -In this tutorial, you learn how to: +In this tutorial, learn how to: - Create and import a module - Create a primary module interface unit @@ -18,97 +20,98 @@ In this tutorial, you learn how to: ## Prerequisites -For this tutorial, you'll need Visual Studio 2022 17.1.0 or later. - -You might get IntelliSense errors while working on the code example in this tutorial. Work on the IntelliSense engine is catching up with the compiler. IntelliSense errors can be ignored and won't prevent the code example from building. To track progress on the IntelliSense work, see this [issue](https://developercommunity.visualstudio.com/t/When-importing-a-C20-module-or-header-/1550846). +This tutorial requires Visual Studio 2022 17.1.0 or later. ## What are C++ modules -Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and difficult to compose because they may compile differently depending on the order in which you include them, or what macros are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. +Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and may compile differently depending on the order you include them in or on the macros that are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. + +C++20 introduces *modules* as a modern approach to componentizing C++ programs. -C++20 introduces a modern approach to componentizing C++ programs: *modules*. +Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules don't leak macro definitions or private implementation details. -Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules don’t leak macro definitions or private implementation details. +Modules are easier to compose because their semantics don't change because of macro definitions or what else has been imported, the order of imports, and so on. They also make it easier to control what is visible to consumers. -Modules are easier to compose. They make it easier to control what is visible to consumers. And their semantics don't change because of macro definitions or what else has been imported, the order of imports, and so on. +Modules provide extra safety guarantees that header files don't. The compiler and linker work together to prevent possible name collision issues, and provide stronger one definition rule ([ODR](https://stroustrup.com/glossary.html#Gone-definition-rule)) guarantees. -Modules provide extra safety guarantees that header files don't because the compiler and linker work together to prevent possible name collision issues and provide stronger one definition rule ([ODR](https://stroustrup.com/glossary.html#Gone-definition-rule)) guarantees. +A strong ownership model avoids clashes between names at link time because the linker attaches exported names to the module that exports them. This model allows the Microsoft Visual C++ compiler to prevent undefined behavior caused by linking different modules that report similar names in the same program. For more information, see [Strong Ownership](https://devblogs.microsoft.com/cppblog/standard-c20-modules-support-with-msvc-in-visual-studio-2019-version-16-8/#strong-ownership). -A strong ownership model avoids clashes between names at link time because the linker attaches exported names to the module that exports them. This allows the Microsoft Visual C++ compiler to prevent undefined behavior stemming from linking different modules that report similar names in the same program. For more information, see [Strong Ownership](https://devblogs.microsoft.com/cppblog/standard-c20-modules-support-with-msvc-in-visual-studio-2019-version-16-8/#strong-ownership) +A module is made up of one or more source code files compiled into a binary file. The binary file describes all the exported types, functions, and templates in the module. When a source file imports a module, the compiler reads in the binary file that contains the contents of the module. Reading the binary file is much faster than processing a header file. Also, the binary file is reused by the compiler every time the module is imported, saving even more time. Because a module is built once rather than every time it's imported, build time can be reduced, sometimes dramatically. -A module is made up of one or more source code files compiled into a binary file that describes all the exported types, functions, and templates in the module. When a source file imports a module, the binary file is read in that contains the contents of the module. Reading the binary file is faster than processing a header file. The binary file is reused by the compiler every time the module is imported by a source file. Because a module is built once rather than every time it's imported, build time can be reduced--sometimes dramatically. +More importantly, modules don't have the fragility problems that header files do. Importing a module doesn't change the module's semantics, or the semantics of any other imported module. Macros, preprocessor directives, and non-exported names declared in a module aren't visible to the source file that imports it. You can import modules in any order and it won't change the meaning of the modules. -But more importantly, modules don't have the fragility problems that header files do. Importing a module doesn't change the module's semantics, or the semantics of any other imported module. Macros, preprocessor directives, and non-exported names declared in a module aren't visible to the source file that imports it. You can import modules in any order without changing the meaning of the module or any other imported module. +Modules can be used side by side with header files. This feature is convenient if you're migrating a code base to use modules because you can do it in stages. -Modules can be used side by side with header files. This may be convenient if you're migrating a code base to use modules in stages. In some cases, a header file can be imported as a header unit rather than as an `#include` file. Header units are the recommended alternative to [precompiled header files](../build/creating-precompiled-header-files.md) (PCH). They're easier to set up and use than [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio), but they provide similar performance benefits. For more information, see [Walkthrough: Build and import header units in Microsoft Visual C++](../build/walkthrough-header-units.md). +In some cases, a header file can be imported as a header unit rather than as an `#include` file. Header units are the recommended alternative to [precompiled header files](../build/creating-precompiled-header-files.md) (PCH). They're easier to set up and use than [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio) files, but they provide similar performance benefits. For more information, see [Walkthrough: Build and import header units in Microsoft Visual C++](../build/walkthrough-header-units.md). -Your code can consume modules in the same project, or any referenced projects, automatically using project-to-project references to static library projects. +Your code can consume modules in the same project, or any referenced projects, automatically by using project-to-project references to static library projects. ## Create the project -As we build a simple project, we'll look at various aspects of modules as we implement an API using a module instead of a header file. +The following project implements an API using a module instead of a header file. -To begin, in Visual Studio 2022, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. +In Visual Studio 2022 or later, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. -Give the new project the name `ModulesTutorial` and create the project. +Give the new project the name *`ModulesTutorial`* and create the project. -Because modules are a C++20 feature, the project needs the [`/std:c++20` or `/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Set the **C++ Language Standard** property by right-clicking in the **Solution Explorer** on the project name `ModulesTutorial`, then choose `Properties`. In the project properties page that appears, ensure that `General` is selected on the left, and then change the **C++ Language Standard** dropdown to **ISO C++20 Standard (/std:c++20)**. Select **OK** to accept the change. +Because modules are a C++20 feature, use the [`/std:c++20` or `/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. In the **Solution Explorer**, right-click on the project name `ModulesTutorial`, then choose **Properties**. In the project Property Pages dialog, change **Configuration** to **All Configurations** and **Platform** to **All Platforms**. Select **Configuration Properties** > **General** in the tree view pane on the left. Select the **C++ Language Standard** property. Use the dropdown to change the property value to **ISO C++20 Standard (/std:c++20)**. Select **OK** to accept the change. ![A screenshot of the ModulesTutorial property page with the left pane open to Configuration Properties > General, and the C++ Language Standard dropdown open with ISO C++20 Standard (/std:c++20) selected](media/language-switch.png) ## Create the primary module interface unit -A module consists of one or more files. One of which must be what is called the primary module interface unit. It defines what the module exports. That is, what importers of the module will see. There can only be one of these. +A module consists of one or more files. One of these files must be what is called the *primary module interface unit*. It defines what the module exports; that is, what importers of the module see. There can only be one primary module interface unit per module. -In the **Solution Explorer**, add a primary module interface unit with a right-click on **Source Files**, then select **Add** > **Module...**. +To add a primary module interface unit, in **Solution Explorer**, right-click **Source Files** then select **Add** > **Module**. -![Add item dialog in solution explorer with Add > Module... highlighted to illustrate where to click to add a module](media/add-module.png) +![Add item dialog in solution explorer with Add > Module... highlighted to illustrate where to click to add a module.](media/add-module.png) -In the **Add New Item** dialog that appears, give the new module the name `BasicPlane.Figures.ixx` and select **Add**. +In the **Add New Item** dialog that appears, give the new module the name *`BasicPlane.Figures.ixx`* and choose **Add**. The default contents of the created module file has two lines: ```cpp export module BasicPlane; + export void MyFunc(); ``` -The first line declares this file to be a module interface unit. Specifically, it's the `export module` keywords that identify this file as a module interface unit. There's a subtle point here. For every named module, there must be exactly one module interface unit with no module partition specified. That module unit is called the primary module interface unit. Module partition files start the same way, but they aren't the primary module interface because they define a partition interface unit. +The `export module` keywords in the first line declare that this file is a module interface unit. There's a subtle point here: for every named module, there must be exactly one module interface unit with no module partition specified. That module unit is called the *primary module interface unit*. -The primary module interface unit is where you declare the functions, types, templates, and potentially other modules (and module partitions, discussed later in this tutorial) that will be exposed to the source files that import the module. A module can consist of multiple files, but this one, the primary module interface, identifies what will be exposed. +The primary module interface unit is where you declare the functions, types, templates, other modules, and module partitions to expose when source files import the module. A module can consist of multiple files, but only the primary module interface file identifies what to expose. -Replace the contents of this file with: +Replace the contents of *`BasicPlane.Figures.ixx`* file with: ```cpp -export module BasicPlane.Figures; // the export module keywords mark this as a primary module interface unit +export module BasicPlane.Figures; // the export module keywords mark this file as a primary module interface unit ``` -This line identifies this file as the primary module interface and gives this module a name: `BasicPlane.Figures`. The period in the module name has no special meaning to the compiler. A period can be used to convey how your module is organized. If you have multiple module files that work together, you can use periods to indicate a separation of concerns. In this tutorial, we'll use periods to indicate different functional areas of the API. +This line identifies this file as the primary module interface and gives the module a name: `BasicPlane.Figures`. The period in the module name has no special meaning to the compiler. A period can be used to convey how your module is organized. If you have multiple module files that work together, you can use periods to indicate a separation of concerns. In this tutorial, periods indicate different functional areas of the API. -This is also where the "named" in "named module" comes from. The files that are part of this module use this name to identify themselves as being part of the named module. In other words, a named module is the collection of module units with the same module name. +This name is also where the "named" in "named module" comes from. The files that are part of this module use this name to identify themselves as part of the named module. A named module is the collection of module units with the same module name. -We should talk about the API we'll implement for a moment before going further because it impacts the choices we make next. The API itself is simple. It represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes, such as `Rectangle`. +We should talk about the API we'll implement for a moment before going further. It impacts the choices we make next. The API represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes such as `Rectangle`. -To illustrate some features of modules, we'll factor this API into pieces. One piece will be the `Point` part of the API. The other part will be `Rectangle`. Imagine that this API will grow into something more complex and that the division is useful for separating concerns or easing code maintenance. +To illustrate some features of modules, we factor this API into parts. One part is the `Point` API. The other part is `Rectangle`. Imagine that this API could grow into something more complex. The division is useful for separating concerns or easing code maintenance. -So far, we've created the primary module interface that will expose this API. Let's now build the `Point` API. We want it to be part of this module. Let's say that for reasons of logical organization, and potential build efficiency (which is covered in [Best practices](#module-best-practices)), that we want this part of the API to be easily understood on its own. To do that, we'll create a *module partition* file. +So far, we've created the primary module interface that will expose this API. Let's now build the `Point` API. We want it to be part of this module. For reasons of logical organization, and potential build efficiency, we want to make the code for this part of the API a *module partition* file. -A module partition file is a piece, or component, of a module. What makes it unique is that it can be treated as an individual piece of the module, but only within the module. Module partitions can't be consumed outside of a module. They're useful for dividing the module implementation into more manageable pieces. +Module partitions are useful for dividing the module implementation into manageable parts. A module partition file is part of a module. What makes it unique is that it can be treated as an individual parts of the module--but only within the module. Module partitions can't be consumed outside of a module. -Importing a partition into its primary module makes all the declarations part of that partition interface visible to the primary module, regardless of whether they're exported. Partitions can be imported into any partition interface, primary module interface, or module unit that belongs to the named module. +When you import a partition into the primary module, all its declarations become visible to the primary module regardless of whether they're exported. Partitions can be imported into any partition interface, primary module interface, or module unit that belongs to the named module. ## Create a module partition file -### `Point` module partition +### `Point` module partition example -To create a module partition file, in the **Solution Explorer**, right-click **Source Files**, then select **Add** > **Module...**. Name the file `BasicPlane.Figures-Point.ixx` and select **Add**. +To create a module partition file, in the **Solution Explorer** right-click **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Point.ixx`* and choose **Add**. -Because this is a module partition file, we've added a hyphen and the name of the partition to the module name. This aids the compiler in the command-line case because the compiler uses name lookup rules based on the module name to find the compiled `.ifc` file for the partition. This way you don't have to provide explicit `/reference` command-line arguments to find the partitions that belong to the module. It's also helpful for organizing the files that belong to a module by name so that you can easily see which files belong to which modules. +Because it's a module partition file, we add a hyphen and the name of the partition to the module name. This convention aids the compiler in the command-line case because the compiler uses name lookup rules based on the module name to find the compiled *`.ifc`* file for the partition. This way you don't have to provide explicit `/reference` command-line arguments to find the partitions that belong to the module. It's also helpful for organizing the files that belong to a module by name because you can easily see which files belong to which modules. -Replace the contents of the file with: +Replace the contents of *`BasicPlane.Figures-Point.ixx`* with: ```cpp -export module BasicPlane.Figures:Point; // defines a module partition, Point, that is part of the module BasicPlane.Figures +export module BasicPlane.Figures:Point; // defines a module partition, Point, that's part of the module BasicPlane.Figures export struct Point { @@ -116,17 +119,17 @@ export struct Point }; ``` -The file starts with `export module`. Recall that this is how the primary module interface started out. What makes this different is the colon (`:`) following the module name, followed by the partition name. This naming convention identifies this as a module *partition*. Because it defines the module interface for a partition, it isn't considered the primary module interface. +The file starts with `export module`. These keywords are also how the primary module interface begins. What makes this file different is the colon (`:`) following the module name, followed by the partition name. This naming convention identifies the file as a *module partition*. Because it defines the module interface for a partition, it isn't considered the primary module interface. -The name `BasicPlane.Figures:Point` identifies this partition as part of the module `BasicPlane.Figures` (remember that the period in the name has no special meaning to the compiler). The colon indicates that this is a *module partition* named `Point`. This module partition named `Point` belongs to the module `BasicPlane.Figures`. We can import this partition into other files that are part of this named module. +The name `BasicPlane.Figures:Point` identifies this partition as part of the module `BasicPlane.Figures` (remember, the period in the name has no special meaning to the compiler). The colon indicates that this file contains a module partition named `Point` that belongs to the module `BasicPlane.Figures`. We can import this partition into other files that are part of this named module. -In this file, `struct Point` is made visible to consumers via the `export` keyword. +In this file, the `export` keyword makes `struct Point` visible to consumers. -### `Rectangle` module partition +### `Rectangle` module partition example -The next partition we'll define is `Rectangle`. Create another module file using the same steps as before. That is, in **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module...**. Name the file `BasicPlane.Figures-Rectangle.ixx` and select **Add**. +The next partition we define is `Rectangle`. Create another module file using the same steps as before: In **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Rectangle.ixx`* and select **Add**. -Replace the contents of the file with: +Replace the contents of *`BasicPlane.Figures-Rectangle.ixx`* with: ```cpp export module BasicPlane.Figures:Rectangle; // defines the module partition Rectangle @@ -145,27 +148,27 @@ export int height(const Rectangle& r); export int width(const Rectangle& r); ``` -The file begins with `export module BasicPlane.Figures:Rectangle;` This declares a module partition that is part of the module `BasicPlane.Figures`. The `:Rectangle` added to the module name defines it as a partition of the module `BasicPlane.Figures`. It can be imported individually into any of the module files that are part of this named module. +The file begins with `export module BasicPlane.Figures:Rectangle;` which declares a module partition that's part of the module `BasicPlane.Figures`. The `:Rectangle` added to the module name defines it as a partition of the module `BasicPlane.Figures`. It can be imported individually into any of the module files that are part of this named module. -Next, `import :Point;` (note the colon), shows how to import a module partition. It makes all the exported types, functions, and templates in the module partition visible to the module. You don't have to specify the module name because the compiler knows that this file belongs to the `BasicPlane.Figures` module. It knows this because of the `export module BasicPlane.Figures:Rectangle;` at the top of the file. +Next, `import :Point;` shows how to import a module partition. The `import` statement makes all the exported types, functions, and templates in the module partition visible to the module. You don't have to specify the module name. The compiler knows that this file belongs to the `BasicPlane.Figures` module because of the `export module BasicPlane.Figures:Rectangle;` at the top of the file. -Then we export the definition of `Rectangle` and the declarations of some functions that return various properties of the rectangle. The `export` keyword indicates whether to make what it precedes visible to consumers of the module. It's used to make the functions `area`, `height`, and `width` visible outside of the module. +Next, the code exports the definition of `struct Rectangle` and declarations for some functions that return various properties of the rectangle. The `export` keyword indicates whether to make what it precedes visible to consumers of the module. It's used to make the functions `area`, `height`, and `width` visible outside of the module. -All definitions and declarations in a module partition are visible to the importing module unit, whether they have the `export` keyword or not. The `export` keyword governs whether the definition, declaration, or typedef will be visible outside of the module when you export the partition in the primary module interface. +All definitions and declarations in a module partition are visible to the importing module unit whether they have the `export` keyword or not. The `export` keyword governs whether the definition, declaration, or typedef is visible outside of the module when you export the partition in the primary module interface. -This brings up the general question of how names are made visible to consumers of a module. Those ways are: +Names are made visible to consumers of a module in several ways: - Put the keyword `export` in front of each type, function, and so on, that you want to export. -- If you put `export` in front of a namespace, for example `export namespace N { ... }`, everything defined directly within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. That's because that namespace declaration isn't prefaced by `export`, even though there's another namespace with the same name that is. -- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. The type, function, and so on, will be visible to other files that are part of the module, but not to importers of the module. -- Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file, and visible only within the file. -- To make an imported module or module partition visible, use the `export import` keyword combination. This is shown in the next section. +- If you put `export` in front of a namespace, for example `export namespace N { ... }`, everything defined within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. It's not available because that namespace declaration isn't prefaced by `export`, even though there's another namespace with the same name that is. +- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It's visible to other files that are part of the module, but not to importers of the module. +- Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file. This section is visible only within the file. +- To make an imported module or module partition visible, use `export import`. An example is shown in the next section. ## Compose the module partitions Now that we have the two parts of the API defined, let's bring them together so that files that import this module can access them as a whole. -All module partitions must be exposed as part of the module definition that they belong to. This is done in the primary module interface. Open the `BasicPlane.Figures.ixx` file, which defines the primary module interface. Replace its contents with: +All module partitions must be exposed as part of the module definition that they belong to. Partitions are exposed in the primary module interface. Open the *`BasicPlane.Figures.ixx`* file, which defines the primary module interface. Replace its contents with: ```cpp export module BasicPlane.Figures; // keywords export module marks this as a primary module interface unit @@ -174,47 +177,47 @@ export import :Point; // bring in the Point partition, and export it to consumer export import :Rectangle; // bring in the Rectangle partition, and export it to consumers of this module ``` -What's new here are the two lines that begin `export import`. When combined like this, these two keywords instruct the compiler to import the specified module (in this case, a module partition, which is expressed by the colon (`:`) in the module name), and make it visible to consumers of this module. +The two lines that begin with `export import` are new here. When combined like this, these two keywords instruct the compiler to import the specified module and make it visible to consumers of this module. In this case, the colon (`:`) in the module name indicates that we're importing a module partition. -Notice that the imported names don't include the full module name. For example, the `:Point` partition was declared as `export module BasicPlane.Figures:Point;`. Yet here we're importing `:Point`. Because we're in the primary module interface file for the module `BasicPlane.Figures`, the module name is implied and only the partition name is specified. +The imported names don't include the full module name. For example, the `:Point` partition was declared as `export module BasicPlane.Figures:Point`. Yet here we're importing `:Point`. Because we're in the primary module interface file for the module `BasicPlane.Figures`, the module name is implied, and only the partition name is specified. -So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We'll do that in a module implementation file, which we'll create next. +So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We do that next by creating a module implementation file. ## Create a module unit implementation file -Module unit implementation files don't end with an `.ixx` extension. They're normal `.cpp` files. Add a module unit implementation file by creating a source file with a right-click in the **Solution Explorer** on **Source Files**, select **Add** > **New item...** and then select **C++ File (.cpp)**. Give the new file the name `BasicPlane.Figures-Rectangle.cpp`, then select **Add**. +Module unit implementation files don't end with an *`.ixx`* extension--they're normal *`.cpp`* files. Add a module unit implementation file by creating a source file with a right-click in the **Solution Explorer** on **Source Files**, select **Add** > **New item** and then select **C++ File (.cpp)**. Give the new file the name *`BasicPlane.Figures-Rectangle.cpp`*, then choose **Add**. -The naming convention for the module partition's implementation file follows the naming convention for partition. But it has a `.cpp` extension because it's an implementation file. +The naming convention for the module partition's implementation file follows the naming convention for a partition. But it has a *`.cpp`* extension because it's an implementation file. Replace the contents of the `BasicPlane.Figures-Rectangle.cpp` file with: ```cpp module; -// global module fragment area. #includes go here +// global module fragment area. Put #include directives here -module BasicPlane.Figures; +module BasicPlane.Figures:Rectangle; int area(const Rectangle& r) { return width(r) * height(r); } int height(const Rectangle& r) { return r.ul.y - r.lr.y; } int width(const Rectangle& r) { return r.lr.x - r.ul.x; } ``` -This file begins with `module;` which introduces a special area of the module called the *global module fragment*. It precedes the code for the named module and is where you can use preprocessor directives such as `#include`. This area is important because code in the global module fragment isn't owned by or exported by the module interface. +This file begins with `module;` which introduces a special area of the module called the *global module fragment*. It precedes the code for the named module and is where you can use preprocessor directives such as `#include`. Code in the global module fragment isn't owned or exported by the module interface. -When you `#include` a header file, you generally don't want it to be treated as an exported part of the module. You're typically including the header file as an implementation detail that shouldn't be made part of the interface of the module. There may be advanced cases where want to do that, but generally you don't. No separate metadata (`.ifc` files) are generated for `#include` directives in the global module fragment. Global module fragments provide a good place to include header files such as `windows.h`, or on Linux, `unistd.h`. +When you include a header file, you generally don't want it to be treated as an exported part of the module. You typically include the header file as an implementation detail that shouldn't be part of the module interface. There may be advanced cases where want to do that, but generally you don't. No separate metadata (*`.ifc`* files) are generated for `#include` directives in the global module fragment. Global module fragments provide a good place to include header files such as *`windows.h`*, or on Linux, *`unistd.h`*. -The module implementation file we're building doesn't include any libraries because it doesn't need them as part of its implementation. But if it did, this is where they would go. +The module implementation file we're building doesn't include any libraries because it doesn't need them as part of its implementation. But if it did, this area is where the `#include` directives would go. -The line `module BasicPlane.Figures;` identifies this file as part of the named module `BasicPlane.Figures`. This causes the compiler to automatically bring in the types and functions exposed by the primary module interface into this file. A module implementation unit doesn't have the `export` keyword before the `module` keyword in its module-declaration. +The line `module BasicPlane.Figures:Rectangle;` indicates that this file is part of the named module `BasicPlane.Figures`. The compiler automatically brings the types and functions exposed by the primary module interface into this file. A module implementation unit doesn't have the `export` keyword before the `module` keyword in its module declaration. -Next are the definition of the functions `area()`, `height()`, and `width()`. They were declared in the `Rectangle` partition in `BasicPlane.Figures-Rectangle.ixx`. Because the primary module interface for this module imported the `Point` and `Rectangle` module partitions, those types are visible here in the module unit implementation file. An interesting feature of module implementation units is that the compiler automatically makes everything in the corresponding module primary interface visible to the file. No `imports ` is needed. +Next are the definition of the functions `area()`, `height()`, and `width()`. They were declared in the `Rectangle` partition in *`BasicPlane.Figures-Rectangle.ixx`*. Because the primary module interface for this module imported the `Point` and `Rectangle` module partitions, those types are visible here in the module unit implementation file. An interesting feature of module implementation units: The compiler automatically makes everything in the corresponding module primary interface visible to the file. No `imports ` is needed. Anything you declare within an implementation unit is only visible to the module that it belongs to. ## Import the module -Now we'll make use of the module we've defined. Open the `ModulesTutorial.cpp` file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: +Now we make use of the module we've defined. Open the *`ModulesTutorial.cpp`* file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: ```cpp #include @@ -232,7 +235,7 @@ int main() } ``` -The first line, `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It can come before or after `#include` directives. +The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It comes after any `#include` directives. The app then uses the types and functions from the module to output the area and width of the defined rectangle: @@ -247,9 +250,9 @@ Let's now look in more detail at the various module files. ### Primary module interface -A module consists of one or more files. One of them defines the interface that importers will see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, it's the exported module interface unit that doesn't specify a module partition. +A module consists of one or more files. One of them defines the interface that importers see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, the exported module interface unit doesn't specify a module partition. -It has an `.ixx` extension by default. However, you can treat a source file with any extension as a module interface file. To do this, set the **Compile As** property in the **Advanced** tab for any source file's properties page to **Compile As Module (/interface)**. +It has an *`.ixx`* extension by default. However, you can treat a source file with any extension as a module interface file. To do so, set the **Compile As** property in the **Advanced** tab for the source file's properties page to **Compile As Module (/interface)**: ![Screenshot of a hypothetical source file's Configuration properties under Configuration properties > C/C++ > Advanced > Compile As, with Compile as C++ Module Code (/interface) highlighted](media\file-property-compile-as.png) @@ -260,13 +263,13 @@ module; // optional. Defines the beginning of the global module fragment // #include directives go here but only apply to this file and // aren't shared with other module implementation files. -// Macro definitions aren't visible outside this file, or to importers. +// Macro definitions aren't visible outside this file or to importers. // import statements aren't allowed here. They go in the module preamble, below. export module [module-name]; // Required. Marks the beginning of the module preamble // import statements go here. They're available to all files that belong to the named module -// Put #includes in in the global module fragment, above +// Put #includes in the global module fragment, above // After any import statements, the module purview begins here // Put exported functions, types, and templates here @@ -279,11 +282,11 @@ module :private; // optional. The start of the private module partition. This file must begin with either `module;` to indicate the beginning of the global module fragment, or `export module [module-name];` to indicate the start of the *module purview*. -The module purview is where functions, types, templates, and so on, go that you want the module to expose. +The module purview is where functions, types, templates, and so on, go that you want to expose from the module. -It's also where you can expose other modules or module partitions via the `export import` keywords, as shown in the `BasicPlane.Figures.ixx` file. +It's also where you can expose other modules or module partitions via the `export import` keywords, as shown in the *`BasicPlane.Figures.ixx`* file. -The primary interface file must export all the interface partitions defined for the module, either directly or indirectly, or the program is ill-formed. +The primary interface file must export all the interface partitions defined for the module directly or indirectly, or the program is ill-formed. The private module partition is where you can put things that you want to be only visible in this file. @@ -293,26 +296,29 @@ For a more in-depth look at module syntax, see [Modules](modules-cpp.md). ### Module implementation units -Module implementation units belong to a named module. The named module they belong to is established by the `module [module-name]` statement in the file. Module implementation units provide implementation details for the module that for code hygiene, or other reasons, you don't want to put in the primary module interface or in a module partition file. +Module implementation units belong to a named module. The named module they belong to is indicated by the `module [module-name]` statement in the file. Module implementation units provide implementation details that, for code hygiene or other reasons, you don't want to put in the primary module interface or in a module partition file. -Module implementation units are useful for breaking up a large module to factor dependencies to get faster build times. This is covered briefly in the [Best practices](#module-best-practices) section. +Module implementation units are useful for breaking up a large module into smaller parts, which can result in faster build times. This technique is covered briefly in the [Best practices](#module-best-practices) section. -Module implementation unit files have a `.cpp` extension. The basic outline of a module implementation unit file is: +Module implementation unit files have a *`.cpp`* extension. The basic outline of a module implementation unit file is: ```cpp -// optional #include or import statements. These only apply to this file +// optional #include statements. These only apply to this file +// optional import statements. These only apply to this file // imports in the associated module's interface are automatically available to this file -module [module-name] // required. Identifies which named module this implementation unit belongs to +module [module-name]; // required. Identifies which named module this implementation unit belongs to // implementation ``` ### Module partition files -Module partitions provide a way to componentize a module into different pieces, or partitions. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. +Module partitions provide a way to componentize a module into different parts, or *partitions*. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. + +A partition has an interface file, and zero or more implementation files. A module partition shares ownership of all the declarations in the entire module. -A partition has an interface file and zero or more implementation files. A module partition shares ownership of all the declarations in the entire module. All names exported by partition interface files must be imported and re-exported (`export import`) by the primary interface file. A partition's name must begin with the module name, followed by a colon, and then the name of the partition. +All names exported by partition interface files must be imported and re-exported (`export import`) by the primary interface file. A partition's name must begin with the module name, followed by a colon, and then the name of the partition. The basic outline of a partition interface file looks like this: @@ -348,14 +354,14 @@ A module and the code that imports it must be compiled with the same compiler op ### Module naming - You can use periods ('.') in your module names but they have no special meaning to the compiler. Use them to convey meaning to the users of your module. For example, start with the library or project top namespace. Finish with a name that describes the module's functionality. `BasicPlane.Figures` is meant to convey an API for geometric planes, and specifically figures that can be represented on a plane. -- The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named `BasicPlane.Figures.ixx`. -- The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, `BasicPlane.Figures-Rectangle.ixx` +- The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named *`BasicPlane.Figures.ixx`*. +- The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, *`BasicPlane.Figures-Rectangle.ixx`* -If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler will look for them automatically based on the name of the module. The name of the compiled partition file (ending with an `.ifc` extension) is generated implicitly from the module name. Consider the module name `BasicPlane.Figures:Rectangle`. The compiler will anticipate that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to ease using module partitions by automatically finding the interface unit files for partitions. +If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler looks for them automatically based on the name of the module. The name of the compiled partition file is generated from the module name and ends in *`.ifc`*. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler anticipates that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. -Or, you can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. +You can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. -### Module factoring +### Factor modules Use module implementation files and partitions to factor your module for easier code maintenance and potentially faster compilation times. @@ -365,13 +371,13 @@ Module partitions make it easier to logically factor a large module. They can be ## Summary -In this tutorial, you've been introduced t the basics of C++20 modules. You've created a primary module interface, defined a module partition, and built a module implementation file to factor and present an API to the files that will import it. The following resources provide more information about C++ 20 modules. +In this tutorial, you were introduced to the basics of C++20 modules by creating a primary module interface, defined a module partition, and built a module implementation file. ## See also [Overview of modules in C++](modules-cpp.md)\ -[module, import, export keywords](import-export-module.md)\ +[`module`, `import`, `export` keywords](import-export-module.md)\ [A Tour of C++ Modules in Visual Studio](https://devblogs.microsoft.com/cppblog/a-tour-of-cpp-modules-in-visual-studio)\ [Practical C++20 Modules and the future of tooling around C++ Modules](https://www.youtube.com/watch?v=ow2zV0Udd9M)\ [Moving a project to C++ named Modules](https://devblogs.microsoft.com/cppblog/moving-a-project-to-cpp-named-modules)\ -[Walkthrough: Build and import header units in Microsoft Visual C++](..\build\walkthrough-header-units.md) \ No newline at end of file +[Walkthrough: Build and import header units in Microsoft Visual C++](..\build\walkthrough-header-units.md) diff --git a/docs/cpp/type-conversions-and-type-safety-modern-cpp.md b/docs/cpp/type-conversions-and-type-safety-modern-cpp.md index 0d6fb436b4..dfa856f93b 100644 --- a/docs/cpp/type-conversions-and-type-safety-modern-cpp.md +++ b/docs/cpp/type-conversions-and-type-safety-modern-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Type conversions and type safety" title: "Type conversions and type safety" +description: "Learn more about: Type conversions and type safety" ms.date: "11/19/2019" ms.topic: "conceptual" -ms.assetid: 629b361a-2ce1-4700-8b5d-ab4f57b245d5 --- # Type conversions and type safety @@ -105,7 +104,7 @@ The C-style cast operator is identical to the call operator () and is therefore int i = d; // warning C4244 possible loss of data int j = static_cast(d); // No warning. string s = static_cast(d); // Error C2440:cannot convert from - // double to std:string + // double to std::string // No error but not necessarily safe. Base* b = new Base(); @@ -173,7 +172,7 @@ The C-style cast operator is identical to the call operator () and is therefore ## See also -[C++ type system](../cpp/cpp-type-system-modern-cpp.md)
-[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)
-[C++ Language Reference](../cpp/cpp-language-reference.md)
+[C++ type system](../cpp/cpp-type-system-modern-cpp.md)\ +[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)\ +[C++ Language Reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/type-info-class.md b/docs/cpp/type-info-class.md index 51a91196c1..6584320826 100644 --- a/docs/cpp/type-info-class.md +++ b/docs/cpp/type-info-class.md @@ -1,10 +1,9 @@ --- description: "Learn more about: type_info Class" title: "type_info Class" -ms.date: "11/04/2016" +ms.date: "07/11/2023" f1_keywords: ["type_info"] helpviewer_keywords: ["class type_info", "type_info class"] -ms.assetid: 894ddda2-7de4-4da3-9404-d2c74e356c16 --- # type_info Class @@ -38,7 +37,7 @@ There is no link between the collating order of types and inheritance relationsh The `type_info::name` member function returns a `const char*` to a null-terminated string representing the human-readable name of the type. The memory pointed to is cached and should never be directly deallocated. -The `type_info::raw_name` member function returns a `const char*` to a null-terminated string representing the decorated name of the object type. The name is actually stored in its decorated form to save space. Consequently, this function is faster than `type_info::name` because it doesn't need to undecorate the name. The string returned by the `type_info::raw_name` function is useful in comparison operations but is not readable. If you need a human-readable string, use the `type_info::name` function instead. +The `type_info::raw_name` member function is Microsoft specific. It returns a `const char*` to a null-terminated string representing the decorated name of the object type. The name is stored in its decorated form to save space. Consequently, this function is faster than `type_info::name` because it doesn't need to undecorate the name. The string returned by the `type_info::raw_name` function is useful in comparison operations but is not readable. If you need a human-readable string, use `type_info::name` instead. Type information is generated for polymorphic classes only if the [/GR (Enable Run-Time Type Information)](../build/reference/gr-enable-run-time-type-information.md) compiler option is specified. diff --git a/docs/cpp/typeid-operator.md b/docs/cpp/typeid-operator.md index 06ffeb8a99..ebe06ae194 100644 --- a/docs/cpp/typeid-operator.md +++ b/docs/cpp/typeid-operator.md @@ -5,7 +5,7 @@ ms.date: "10/04/2019" helpviewer_keywords: ["typeid operator"] ms.assetid: 8871cee6-d6b9-4301-a5cb-bf3dc9798d61 --- -# typeid Operator +# `typeid` Operator ## Syntax @@ -26,9 +26,9 @@ The **`typeid`** operator does a run-time check when applied to an l-value of a - A reference to a class -- A pointer, dereferenced with `*` +- A pointer, dereferenced with **`*`** -- A subscripted pointer (`[ ]`). (It's not safe to use a subscript with a pointer to a polymorphic type.) +- A subscripted pointer (**`[ ]`**). (It's not safe to use a subscript with a pointer to a polymorphic type.) If the *expression* points to a base class type, yet the object is actually of a type derived from that base class, a `type_info` reference for the derived class is the result. The *expression* must point to a polymorphic type (a class with virtual functions). Otherwise, the result is the `type_info` for the static class referred to in the *expression*. Further, the pointer must be dereferenced so that the object used is the one it points to. Without dereferencing the pointer, the result will be the `type_info` for the pointer, not what it points to. For example: diff --git a/docs/cpp/typename.md b/docs/cpp/typename.md index 602d1d0de4..60273a3ddb 100644 --- a/docs/cpp/typename.md +++ b/docs/cpp/typename.md @@ -1,26 +1,24 @@ --- description: "Learn more about: typename" title: "typename" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["typename_cpp"] helpviewer_keywords: ["typename template specifier"] ms.assetid: 52e1d901-220d-4f0d-ab43-dae7e05fb491 --- -# typename +# `typename` -In template definitions, provides a hint to the compiler that an unknown identifier is a type. In template parameter lists, is used to specify a type parameter. +In template definitions, **`typename`** provides a hint to the compiler that an unknown identifier is a type. In template parameter lists, it's used to specify a type parameter. ## Syntax -``` -typename identifier; -``` +> **`typename`** *`identifier`***`;`** ## Remarks -This keyword must be used if a name in a template definition is a qualified name that is dependent on a template argument; it is optional if the qualified name is not dependent. For more information, see [Templates and Name Resolution](../cpp/templates-and-name-resolution.md). +The **`typename`** keyword must be used if a name in a template definition is a qualified name that is dependent on a template argument; it's optional if the qualified name isn't dependent. For more information, see [Templates and Name Resolution](../cpp/templates-and-name-resolution.md). -**`typename`** can be used by any type anywhere in a template declaration or definition. It is not allowed in the base class list, unless as a template argument to a template base class. +**`typename`** can be used by any type anywhere in a template declaration or definition. It isn't allowed in the base class list, unless as a template argument to a template base class. ```cpp template @@ -54,5 +52,5 @@ int main() ## See also -[Templates](../cpp/templates-cpp.md)
+[Templates](../cpp/templates-cpp.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/unaligned.md b/docs/cpp/unaligned.md index dca6404c9e..ab25505fd0 100644 --- a/docs/cpp/unaligned.md +++ b/docs/cpp/unaligned.md @@ -4,31 +4,26 @@ title: "__unaligned" ms.date: "12/17/2018" f1_keywords: ["__unaligned_cpp", "__unaligned", "_unaligned"] helpviewer_keywords: ["__unaligned keyword [C++]"] -ms.assetid: 0cd83aad-1840-47e3-ad33-59bfcbe6375b --- -# __unaligned +# `__unaligned` -**Microsoft-specific**. When you declare a pointer with the **`__unaligned`** modifier, the compiler assumes that the pointer addresses data that is not aligned. Consequently, platform-appropriate code is generated to handle unaligned reads and writes through the pointer. +**Microsoft-specific**. When you declare a pointer with the **`__unaligned`** modifier, the compiler assumes that the pointer addresses data that isn't aligned. So, platform-appropriate code is generated to handle unaligned reads and writes through the pointer. ## Remarks -This modifier describes the alignment of the data addressed by the pointer; the pointer itself is assumed to be aligned. +This modifier describes the alignment of the data addressed by the pointer. It is assumed that the pointer itself is aligned. -The necessity for the **`__unaligned`** keyword varies by platform and environment. Failure to mark data appropriately can result in issues ranging from performance penalties to hardware faults. The **`__unaligned`** modifier is not valid for the x86 platform. +The necessity for the **`__unaligned`** keyword varies by platform and environment. Failure to mark data appropriately can result in issues ranging from performance penalties to hardware faults. The **`__unaligned`** modifier isn't valid for the x86 platform. For compatibility with previous versions, **`_unaligned`** is a synonym for **`__unaligned`** unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. For more information about alignment, see: - [`align`](../cpp/align-cpp.md) - - [`alignof` Operator](../cpp/alignof-operator.md) - - [`pack`](../preprocessor/pack.md) - - [`/Zp` (Struct Member Alignment)](../build/reference/zp-struct-member-alignment.md) - -- [Examples of Structure Alignment](../build/x64-software-conventions.md#examples-of-structure-alignment) +- [x64 structure alignment examples](../build/x64-software-conventions.md#x64-structure-alignment-examples) ## See also diff --git a/docs/cpp/unary-plus-and-negation-operators-plus-and.md b/docs/cpp/unary-plus-and-negation-operators-plus-and.md index 7aec830b64..be1f340234 100644 --- a/docs/cpp/unary-plus-and-negation-operators-plus-and.md +++ b/docs/cpp/unary-plus-and-negation-operators-plus-and.md @@ -6,7 +6,7 @@ f1_keywords: ["+", "-"] helpviewer_keywords: ["unary operators [C++], plus", "- operator", "negation operator", "+ operator [C++], unary operators", "+ operator"] ms.assetid: 2c58c4f4-0d92-4ae3-9d0c-1a6157875cc1 --- -# Unary Plus and Negation Operators: + and - +# Unary Plus and Negation Operators: `+` and `-` ## Syntax @@ -15,15 +15,15 @@ ms.assetid: 2c58c4f4-0d92-4ae3-9d0c-1a6157875cc1 - cast-expression ``` -## + operator +## `+` operator -The result of the unary plus operator (**+**) is the value of its operand. The operand to the unary plus operator must be of an arithmetic type. +The result of the unary plus operator (**`+`**) is the value of its operand. The operand to the unary plus operator must be of an arithmetic type. Integral promotion is performed on integral operands. The resultant type is the type to which the operand is promoted. Thus, the expression `+ch`, where `ch` is of type **`char`**, results in type **`int`**; the value is unmodified. See [Standard Conversions](standard-conversions.md) for more information about how the promotion is done. -## - operator +## `-` operator -The unary negation operator (**-**) produces the negative of its operand. The operand to the unary negation operator must be an arithmetic type. +The unary negation operator (**`-`**) produces the negative of its operand. The operand to the unary negation operator must be an arithmetic type. Integral promotion is performed on integral operands, and the resultant type is the type to which the operand is promoted. See [Standard Conversions](standard-conversions.md) for more information about how the promotion is performed. @@ -35,5 +35,5 @@ Unary negation of unsigned quantities is performed by subtracting the value of t ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ [C++ Built-in Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md) diff --git a/docs/cpp/unhook.md b/docs/cpp/unhook.md index c281450faf..146b6502e0 100644 --- a/docs/cpp/unhook.md +++ b/docs/cpp/unhook.md @@ -64,7 +64,7 @@ A pointer to the event handler method to be unhooked from an event. The handler - Managed events: *`ReceiverClass`* is the event receiver class and *`HandlerMethod`* is the handler. -*`receiver`*(optional) +*`receiver`* (optional) A pointer to an instance of the event receiver class. If you don't specify a receiver, the default is the receiver class or structure in which **`__unhook`** is called. ## Usage diff --git a/docs/cpp/unions.md b/docs/cpp/unions.md index 1ea4ddf6dc..5ee20502c5 100644 --- a/docs/cpp/unions.md +++ b/docs/cpp/unions.md @@ -4,7 +4,6 @@ description: "A description of the Standard C++ union class-type and keyword, it ms.date: "08/18/2020" f1_keywords: ["union_cpp"] helpviewer_keywords: ["class type [C++], union as", "union keyword [C++]"] -ms.assetid: 25c4e219-fcbb-4b7b-9b64-83f3252a92ca no-loc: ["union", "struct", "enum", "class", "static"] --- # `union` @@ -14,7 +13,7 @@ no-loc: ["union", "struct", "enum", "class", "static"] A **`union`** is a user-defined type in which all members share the same memory location. This definition means that at any given time, a union can contain no more than one object from its list of members. It also means that no matter how many members a union has, it always uses only enough memory to store the largest member. -A union can be useful for conserving memory when you have lots of objects and limited memory. However, a union requires extra care to use correctly. You're responsible for ensuring that you always access the same member you assigned. If any member types have a non-trivial constructor, then you must write additional code to explicitly construct and destroy that member. Before you use a union, consider whether the problem you're trying to solve could be better expressed by using a base class and derived class types. +A union can be useful for conserving memory when you have lots of objects and limited memory. However, a union requires extra care to use correctly. You're responsible for ensuring that you always access the same member you assigned. If any member types have a nontrivial constructor, then you must write code to explicitly construct and destroy that member. Before you use a union, consider whether the problem you're trying to solve could be better expressed by using a base class and derived class types. ## Syntax @@ -22,10 +21,10 @@ A union can be useful for conserving memory when you have lots of objects and li ### Parameters -*`tag`*
+*`tag`*\ The type name given to the union. -*`member-list`*
+*`member-list`*\ Members that the union can contain. ## Declare a union @@ -144,7 +143,7 @@ It's easy to misuse the `Input` struct in the example. It's up to the user to us ## Unrestricted union (C++11) -In C++03 and earlier, a union can contain non-static data members that have a class type, as long as the type has no user provided constructors, destructors, or assignment operators. In C++11, these restrictions are removed. If you include such a member in your union, the compiler automatically marks any special member functions that aren't user provided as **`deleted`**. If the union is an anonymous union inside a class or struct, then any special member functions of the class or struct that aren't user provided are marked as **`deleted`**. The following example shows how to handle this case. One of the members of the union has a member that requires this special treatment: +In C++03 and earlier, a union can contain nonstatic data members that have a class type, as long as the type has no user provided constructors, destructors, or assignment operators. In C++11, these restrictions are removed. If you include such a member in your union, the compiler automatically marks any special member functions that aren't user provided as **`deleted`**. If the union is an anonymous union inside a class or struct, then any special member functions of the class or struct that aren't user provided are marked as **`deleted`**. The following example shows how to handle this case. One of the members of the union has a member that requires this special treatment: ```cpp // for MyVariant @@ -504,7 +503,7 @@ int main() } ``` -A union can't store a reference. A union also doesn’t support inheritance. That means you can't use a union as a base class, or inherit from another class, or have virtual functions. +A union can't store a reference. A union also doesn't support inheritance. That means you can't use a union as a base class, or inherit from another class, or have virtual functions. ## Initialize a union @@ -534,10 +533,11 @@ int main() */ ``` -The `NumericType` union is arranged in memory (conceptually) as shown in the following figure. +The `NumericType` union is arranged in memory (conceptually) as shown in the following figure: -![Diagram that shows the overlapping storage of data in a numeric type union.](../cpp/media/vc38ul1.png "Storage of data in a NumericType union")
-Storage of data in a `NumericType` union +:::image type="complex" source="../cpp/media/vc38ul1.png" alt-text="Diagram that shows the overlapping storage of data in the NumericType union."::: +The diagram shows 8 bytes of data. The double type dValue occupies the entire 8 bytes. The type long lValue occupies the first 4 bytes. The short type iValue occupies the first byte. +:::image-end::: ## Anonymous union @@ -547,17 +547,15 @@ An anonymous union is one declared without a *`class-name`* or *`declarator-list Names declared in an anonymous union are used directly, like nonmember variables. It implies that the names declared in an anonymous union must be unique in the surrounding scope. -An anonymous union is subject to these additional restrictions: +An anonymous union is subject to these restrictions: - If declared in file or namespace scope, it must also be declared as **`static`**. - - It can have only **`public`** members; having **`private`** and **`protected`** members in an anonymous union generates errors. - - It can't have member functions. ## See also -[Classes and Structs](../cpp/classes-and-structs-cpp.md)
-[Keywords](../cpp/keywords-cpp.md)
-[`class`](../cpp/class-cpp.md)
+[Classes and Structs](../cpp/classes-and-structs-cpp.md)\ +[Keywords](../cpp/keywords-cpp.md)\ +[`class`](../cpp/class-cpp.md)\ [`struct`](../cpp/struct-cpp.md) diff --git a/docs/cpp/user-defined-literals-cpp.md b/docs/cpp/user-defined-literals-cpp.md index 8261db33e3..3dcac38eb8 100644 --- a/docs/cpp/user-defined-literals-cpp.md +++ b/docs/cpp/user-defined-literals-cpp.md @@ -6,7 +6,7 @@ ms.assetid: ff4a5bec-f795-4705-a2c0-53788fd57609 --- # User-defined literals -There are six major categories of literals in C++: integer, character, floating-point, string, boolean, and pointer. Starting in C++ 11, you can define your own literals based on these categories, to provide syntactic shortcuts for common idioms and increase type safety. For example, let's say you have a `Distance` class. You could define a literal for kilometers and another one for miles, and encourage the user to be explicit about the units of measure by writing: `auto d = 42.0_km` or `auto d = 42.0_mi`. There's no performance advantage or disadvantage to user-defined literals; they're primarily for convenience or for compile-time type deduction. The Standard Library has user-defined literals for `std::string`, for `std::complex`, and for units in time and duration operations in the \ header: +There are six major categories of literals in C++: integer, character, floating-point, string, boolean, and pointer. Starting in C++11, you can define your own literals based on these categories, to provide syntactic shortcuts for common idioms and increase type safety. For example, let's say you have a `Distance` class. You could define a literal for kilometers and another one for miles, and encourage the user to be explicit about the units of measure by writing: `auto d = 42.0_km` or `auto d = 42.0_mi`. There's no performance advantage or disadvantage to user-defined literals; they're primarily for convenience or for compile-time type deduction. The Standard Library has user-defined literals for `std::string`, for `std::complex`, and for units in time and duration operations in the \ header: ```cpp Distance d = 36.0_mi + 42.0_km; // Custom UDL (see below) diff --git a/docs/cpp/uuidof-operator.md b/docs/cpp/uuidof-operator.md index 11e02a7c90..e6628b991e 100644 --- a/docs/cpp/uuidof-operator.md +++ b/docs/cpp/uuidof-operator.md @@ -70,5 +70,5 @@ StringFromCLSID(__LIBID_, &lpolestr); ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/value-types-modern-cpp.md b/docs/cpp/value-types-modern-cpp.md index 53c23e787a..a3bed668f6 100644 --- a/docs/cpp/value-types-modern-cpp.md +++ b/docs/cpp/value-types-modern-cpp.md @@ -1,13 +1,13 @@ --- description: "Learn more about: C++ classes as value types" title: "C++ classes as value types" -ms.date: "11/19/2019" +ms.date: 06/09/2022 ms.topic: "conceptual" ms.assetid: f63bb62c-60da-40d5-ac14-4366608fe260 --- # C++ classes as value types -C++ classes are, by default, value types. They can be specified as reference types, which enable polymorphic behavior to support object-oriented programming. Value types are sometimes viewed from the perspective of memory and layout control, whereas reference types are about base classes and virtual functions for polymorphic purposes. By default, value types are copyable, which means there is always a copy constructor and a copy assignment operator. For reference types, you make the class non-copyable (disable the copy constructor and copy assignment operator) and use a virtual destructor, which supports their intended polymorphism. Value types are also about the contents, which, when they are copied, always give you two independent values that can be modified separately. Reference types are about identity - what kind of object is it? For this reason, "reference types" are also referred to as "polymorphic types". +C++ classes are, by default, value types. They can be specified as reference types, which enable polymorphic behavior to support object-oriented programming. Value types are sometimes viewed from the perspective of memory and layout control, whereas reference types are about base classes and virtual functions for polymorphic purposes. By default, value types are copyable, which means there's always a copy constructor and a copy assignment operator. For reference types, you make the class non-copyable (disable the copy constructor and copy assignment operator) and use a virtual destructor, which supports their intended polymorphism. Value types are also about the contents, which, when they're copied, always give you two independent values that can be modified separately. Reference types are about identity - what kind of object is it? For this reason, "reference types" are also referred to as "polymorphic types". If you really want a reference-like type (base class, virtual functions), you need to explicitly disable copying, as shown in the `MyRefType` class in the following code. @@ -40,11 +40,11 @@ test.cpp(15) : error C2248: 'MyRefType::operator =' : cannot access private memb ## Value types and move efficiency -Copy allocation overhead is avoided due to new copy optimizations. For example, when you insert a string in the middle of a vector of strings, there will be no copy re-allocation overhead, only a move- even if it results in a grow of the vector itself. This also applies to other operations, for instance performing an add operation on two very large objects. How do you enable these value operation optimizations? In some C++ compilers, the compiler will enable this for you implicitly, much like copy constructors can be automatically generated by the compiler. However, in C++, your class will need to "opt-in" to move assignment and constructors by declaring it in your class definition. This is accomplished by using the double ampersand (&&) rvalue reference in the appropriate member function declarations and defining move constructor and move assignment methods. You also need to insert the correct code to "steal the guts" out of the source object. +Copy allocation overhead is avoided due to new copy optimizations. For example, when you insert a string in the middle of a vector of strings, there's no copy reallocation overhead, only a move, even if it results in growth of the vector itself. These optimizations also apply to other operations: for instance, performing an add operation on two huge objects. How do you enable these value operation optimizations? The compiler enables them for you implicitly, much like copy constructors can be automatically generated by the compiler. However, your class has to "opt-in" to move assignments and move constructors by declaring them in your class definition. Move uses the double ampersand (&&) rvalue reference in the appropriate member function declarations and defining move constructor and move assignment methods. You also need to insert the correct code to "steal the guts" out of the source object. -How do you decide if you need move enabled? If you already know you need copy construction enabled, you probably want move enabled if it can be cheaper than a deep copy. However, if you know you need move support, it doesn't necessarily mean you want copy enabled. This latter case would be called a "move-only type". An example already in the standard library is `unique_ptr`. As a side note, the old `auto_ptr` is deprecated, and was replaced by `unique_ptr` precisely due to the lack of move semantics support in the previous version of C++. +How do you decide if you need to enable move operations? If you already know you need to enable copy construction, you probably want to enable move construction, too, especially if it's cheaper than a deep copy. However, if you know you need move support, it doesn't necessarily mean you want to enable copy operations. This latter case would be called a "move-only type". An example already in the standard library is `unique_ptr`. As a side note, the old `auto_ptr` is deprecated, and was replaced by `unique_ptr` precisely due to the lack of move semantics support in the previous version of C++. -By using move semantics you can return-by-value or insert-in-middle. Move is an optimization of copy. There is need for heap allocation as a workaround. Consider the following pseudocode: +By using move semantics, you can return-by-value or insert-in-middle. Move is an optimization of copy. There's no need for heap allocation as a workaround. Consider the following pseudocode: ```cpp #include @@ -99,7 +99,7 @@ public: If you enable copy construction/assignment, also enable move construction/assignment if it can be cheaper than a deep copy. -Some *non-value* types are move-only, such as when you can’t clone a resource, only transfer ownership. Example: `unique_ptr`. +Some *non-value* types are move-only, such as when you can't clone a resource, only transfer ownership. Example: `unique_ptr`. ## See also diff --git a/docs/cpp/variant-t-variant-t.md b/docs/cpp/variant-t-variant-t.md index 48f311b9eb..cc8b163338 100644 --- a/docs/cpp/variant-t-variant-t.md +++ b/docs/cpp/variant-t-variant-t.md @@ -171,7 +171,7 @@ A `BYTE` value to be copied into the new `_variant_t` object. A **`char`** value to be copied into the new `_variant_t` object. *`usSrc`*\ -A **`unsigned short`** value to be copied into the new `_variant_t` object. +An **`unsigned short`** value to be copied into the new `_variant_t` object. *`ulSrc`*\ A **`unsigned long`** value to be copied into the new `_variant_t` object. diff --git a/docs/cpp/vectorcall.md b/docs/cpp/vectorcall.md index eec395dc2f..97bca68b08 100644 --- a/docs/cpp/vectorcall.md +++ b/docs/cpp/vectorcall.md @@ -21,7 +21,7 @@ Using the [`/Gv`](../build/reference/gd-gr-gv-gz-calling-convention.md) compiler You can pass three kinds of arguments by register in **`__vectorcall`** functions: *integer type* values, *vector type* values, and *homogeneous vector aggregate* (HVA) values. -An integer type satisfies two requirements: it fits in the native register size of the processor—for example, 4 bytes on an x86 machine or 8 bytes on an x64 machine—and it’s convertible to an integer of register length and back again without changing its bit representation. For example, any type that can be promoted to **`int`** on x86 (**`long long`** on x64)—for example, a **`char`** or **`short`**—or that can be cast to **`int`** (**`long long`** on x64) and back to its original type without change is an integer type. Integer types include pointer, reference, and **`struct`** or **`union`** types of 4 bytes (8 bytes on x64) or less. On x64 platforms, larger **`struct`** and **`union`** types are passed by reference to memory allocated by the caller; on x86 platforms, they are passed by value on the stack. +An integer type satisfies two requirements: it fits in the native register size of the processor—for example, 4 bytes on an x86 machine or 8 bytes on an x64 machine—and it's convertible to an integer of register length and back again without changing its bit representation. For example, any type that can be promoted to **`int`** on x86 (**`long long`** on x64)—for example, a **`char`** or **`short`**—or that can be cast to **`int`** (**`long long`** on x64) and back to its original type without change is an integer type. Integer types include pointer, reference, and **`struct`** or **`union`** types of 4 bytes (8 bytes on x64) or less. On x64 platforms, larger **`struct`** and **`union`** types are passed by reference to memory allocated by the caller; on x86 platforms, they are passed by value on the stack. A vector type is either a floating-point type—for example, a **`float`** or **`double`**—or an SIMD vector type—for example, **`__m128`** or **`__m256`**. @@ -35,11 +35,11 @@ typedef struct { } hva3; // 3 element HVA type on __m256 ``` -Declare your functions explicitly with the **`__vectorcall`** keyword in header files to allow separately compiled code to link without errors. Functions must be prototyped to use **`__vectorcall`**, and can’t use a `vararg` variable length argument list. +Declare your functions explicitly with the **`__vectorcall`** keyword in header files to allow separately compiled code to link without errors. Functions must be prototyped to use **`__vectorcall`**, and can't use a `vararg` variable length argument list. A member function may be declared by using the **`__vectorcall`** specifier. The hidden **`this`** pointer is passed by register as the first integer type argument. -On ARM machines, **`__vectorcall`** is accepted and ignored by the compiler. +On ARM machines, **`__vectorcall`** is accepted and ignored by the compiler. On ARM64EC, **`__vectorcall`** is unsupported and rejected by the compiler. For non-static class member functions, if the function is defined out-of-line, the calling convention modifier does not have to be specified on the out-of-line definition. That is, for class non-static members, the calling convention specified during declaration is assumed at the point of definition. Given this class definition: @@ -73,7 +73,7 @@ For compatibility with previous versions, **`_vectorcall`** is a synonym for **` The **`__vectorcall`** calling convention on x64 extends the standard x64 calling convention to take advantage of additional registers. Both integer type arguments and vector type arguments are mapped to registers based on position in the argument list. HVA arguments are allocated to unused vector registers. -When any of the first four arguments in order from left to right are integer type arguments, they are passed in the register that corresponds to that position—RCX, RDX, R8, or R9. A hidden **`this`** pointer is treated as the first integer type argument. When an HVA argument in one of the first four arguments can’t be passed in the available registers, a reference to caller-allocated memory is passed in the corresponding integer type register instead. Integer type arguments after the fourth parameter position are passed on the stack. +When any of the first four arguments in order from left to right are integer type arguments, they are passed in the register that corresponds to that position—RCX, RDX, R8, or R9. A hidden **`this`** pointer is treated as the first integer type argument. When an HVA argument in one of the first four arguments can't be passed in the available registers, a reference to caller-allocated memory is passed in the corresponding integer type register instead. Integer type arguments after the fourth parameter position are passed on the stack. When any of the first six arguments in order from left to right are vector type arguments, they are passed by value in SSE vector registers 0 to 5 according to argument position. Floating-point and **`__m128`** types are passed in XMM registers, and **`__m256`** types are passed in YMM registers. This differs from the standard x64 calling convention, because the vector types are passed by value instead of by reference, and additional registers are used. The shadow stack space allocated for vector type arguments is fixed at 8 bytes, and the [`/homeparams`](../build/reference/homeparams-copy-register-parameters-to-stack.md) option does not apply. Vector type arguments in the seventh and later parameter positions are passed on the stack by reference to memory allocated by the caller. diff --git a/docs/cpp/virtual-functions.md b/docs/cpp/virtual-functions.md index f9ed3ff0ea..665db8ecdf 100644 --- a/docs/cpp/virtual-functions.md +++ b/docs/cpp/virtual-functions.md @@ -4,6 +4,7 @@ title: "Virtual Functions" ms.date: "09/10/2019" helpviewer_keywords: ["functions [C++], virtual functions", "derived classes [C++], virtual functions", "virtual functions"] ms.assetid: b3e1ed88-2a90-4af8-960a-16f47deb3452 +adobe-target: true --- # Virtual Functions diff --git a/docs/cpp/void-cpp.md b/docs/cpp/void-cpp.md index 9d991fdb27..09444a7cc0 100644 --- a/docs/cpp/void-cpp.md +++ b/docs/cpp/void-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: void (C++)" title: "void (C++)" -ms.date: 10/15/2021 +ms.date: 12/13/2022 f1_keywords: ["void_cpp"] helpviewer_keywords: ["void keyword [C++]", "functions [C++], void", "pointers, void"] ms.assetid: d203edba-38e6-4056-8b89-011437351057 @@ -16,16 +16,26 @@ In C++, a **`void`** pointer can point to a free function (a function that's not You can't declare a variable of type **`void`**. +As a matter of style, the C++ Core Guidelines recommend you don't use **`void`** to specify an empty formal parameter list. For more information, see [C++ Core Guidelines NL.25: Don't use `void` as an argument type](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#nl25-dont-use-void-as-an-argument-type). + ## Example ```cpp // void.cpp + +void return_nothing() +{ + // A void function can have a return with no argument, + // or no return statement. +} + void vobject; // C2182 void *pv; // okay int *pint; int i; -int main() { +int main() +{ pv = &i; - // Cast optional in C required in C++ + // Cast is optional in C, required in C++ pint = (int *)pv; } ``` diff --git a/docs/cpp/welcome-back-to-cpp-modern-cpp.md b/docs/cpp/welcome-back-to-cpp-modern-cpp.md index c7b8cf57df..dd8346fd6d 100644 --- a/docs/cpp/welcome-back-to-cpp-modern-cpp.md +++ b/docs/cpp/welcome-back-to-cpp-modern-cpp.md @@ -1,9 +1,8 @@ --- title: "Welcome back to C++ - Modern C++" description: "Describes the new programming idioms in Modern C++ and their rationale." -ms.date: 09/07/2021 +ms.date: 06/02/2022 ms.topic: "conceptual" -ms.assetid: 1cb1b849-ed9c-4721-a972-fd8f3dab42e2 --- # Welcome back to C++ - Modern C++ @@ -24,20 +23,19 @@ To support easy adoption of RAII principles, the C++ Standard Library provides t class widget { private: - std::unique_ptr data; + std::unique_ptr data; public: - widget(const int size) { data = std::make_unique(size); } + widget(const int size) { data = std::make_unique(size); } void do_something() {} }; void functionUsingWidget() { - widget w(1000000); // lifetime automatically tied to enclosing scope - // constructs w, including the w.data gadget member + widget w(1000000); // lifetime automatically tied to enclosing scope + // constructs w, including the w.data gadget member // ... w.do_something(); // ... } // automatic destruction and deallocation for w and w.data - ``` Whenever possible, use a smart pointer to manage heap memory. If you must use the **`new`** and **`delete`** operators explicitly, follow the principle of RAII. For more information, see [Object lifetime and resource management (RAII)](object-lifetime-and-resource-management-modern-cpp.md). @@ -65,26 +63,20 @@ apple_color["Granny Smith"] = "Green"; When performance optimization is needed, consider using: -- The [`array`](../standard-library/array-class-stl.md) type when embedding is important, for example, as a class member. - - Unordered associative containers such as [`unordered_map`](../standard-library/unordered-map-class.md). These have lower per-element overhead and constant-time lookup, but they can be harder to use correctly and efficiently. - - Sorted `vector`. For more information, see [Algorithms](../standard-library/algorithms.md). -Don’t use C-style arrays. For older APIs that need direct access to the data, use accessor methods such as `f(vec.data(), vec.size());` instead. For more information about containers, see [C++ Standard Library Containers](../standard-library/stl-containers.md). +Don't use C-style arrays. For older APIs that need direct access to the data, use accessor methods such as `f(vec.data(), vec.size());` instead. For more information about containers, see [C++ Standard Library Containers](../standard-library/stl-containers.md). ## Standard Library algorithms -Before you assume that you need to write a custom algorithm for your program, first review the C++ Standard Library [algorithms](../standard-library/algorithm.md). The Standard Library contains an ever-growing assortment of algorithms for many common operations such as searching, sorting, filtering, and randomizing. The math library is extensive. Starting in C++17, parallel versions of many algorithms are provided. +Before you assume that you need to write a custom algorithm for your program, first review the C++ Standard Library [algorithms](../standard-library/algorithm.md). The Standard Library contains an ever-growing assortment of algorithms for many common operations such as searching, sorting, filtering, and randomizing. The math library is extensive. In C++17 and later, parallel versions of many algorithms are provided. Here are some important examples: - `for_each`, the default traversal algorithm (along with range-based `for` loops). - - `transform`, for not-in-place modification of container elements - - `find_if`, the default search algorithm. - - `sort`, `lower_bound`, and the other default sorting and searching algorithms. To write a comparator, use strict **`<`** and use *named lambdas* when you can. @@ -95,7 +87,7 @@ auto comp = [](const widget& w1, const widget& w2) sort( v.begin(), v.end(), comp ); -auto i = lower_bound( v.begin(), v.end(), comp ); +auto i = lower_bound( v.begin(), v.end(), widget{0}, comp ); ``` ## `auto` instead of explicit type names @@ -142,7 +134,7 @@ Macros in C and C++ are tokens that are processed by the preprocessor before com constexpr int size = 10; // modern C++ ``` -### Uniform initialization +## Uniform initialization In modern C++, you can use brace initialization for any type. This form of initialization is especially convenient when initializing arrays, vectors, or other containers. In the following example, `v2` is initialized with three instances of `S`. `v3` is initialized with three instances of `S` that are themselves initialized using braces. The compiler infers the type of each element based on the declared type of `v3`. @@ -185,7 +177,7 @@ Modern C++ provides *move semantics*, which make it possible to eliminate unnece ## Lambda expressions -In C-style programming, a function can be passed to another function by using a *function pointer*. Function pointers are inconvenient to maintain and understand. The function they refer to may be defined elsewhere in the source code, far away from the point at which it's invoked. Also, they're not type-safe. Modern C++ provides *function objects*, classes that override the [`operator()`](function-call-operator-parens.md) operator, which enables them to be called like a function. The most convenient way to create function objects is with inline [lambda expressions](../cpp/lambda-expressions-in-cpp.md). The following example shows how to use a lambda expression to pass a function object, that the `for_each` function will invoke on each element in the vector: +In C-style programming, a function can be passed to another function by using a *function pointer*. Function pointers are inconvenient to maintain and understand. The function they refer to may be defined elsewhere in the source code, far away from the point at which it's invoked. Also, they're not type-safe. Modern C++ provides *function objects*, classes that override the [`operator()`](function-call-operator-parens.md) operator, which enables them to be called like a function. The most convenient way to create function objects is with inline [lambda expressions](../cpp/lambda-expressions-in-cpp.md). The following example shows how to use a lambda expression to pass a function object, that the `find_if` function will invoke on each element in the vector: ```cpp std::vector v {1,2,3,4,5}; diff --git a/docs/cpp/writing-an-exception-filter.md b/docs/cpp/writing-an-exception-filter.md index cf3e4b3781..dfa69fb7df 100644 --- a/docs/cpp/writing-an-exception-filter.md +++ b/docs/cpp/writing-an-exception-filter.md @@ -16,25 +16,29 @@ For example, the following code uses a function call in the *filter* expression: ```cpp // exceptions_Writing_an_Exception_Filter.cpp #include +int Eval_Exception(int); int main() { - int Eval_Exception( int ); - - __try {} - - __except ( Eval_Exception( GetExceptionCode( ))) { - ; - } - + __try { + ; + } + __except (Eval_Exception(GetExceptionCode())) { + ; + } +} +void HandleOverflow() { + // Gracefully recover } -void ResetVars( int ) {} -int Eval_Exception ( int n_except ) { - if ( n_except != STATUS_INTEGER_OVERFLOW && - n_except != STATUS_FLOAT_OVERFLOW ) // Pass on most exceptions - return EXCEPTION_CONTINUE_SEARCH; - - // Execute some code to clean up problem - ResetVars( 0 ); // initializes data to 0 - return EXCEPTION_CONTINUE_EXECUTION; +int Eval_Exception(int n_except) { + if ( + n_except != STATUS_INTEGER_OVERFLOW && + n_except != STATUS_FLOAT_OVERFLOW + ) { + // Pass on most exceptions + return EXCEPTION_CONTINUE_SEARCH; + } + // Execute some code to clean up problem + HandleOverflow(); + return EXCEPTION_CONTINUE_EXECUTION; } ``` @@ -42,7 +46,7 @@ It's a good idea to use a function call in the *filter* expression whenever *fil Note the use of [`GetExceptionCode`](/windows/win32/Debug/getexceptioncode) to determine the exception. This function must be called inside the filter expression of the **`__except`** statement. `Eval_Exception` can't call `GetExceptionCode`, but it must have the exception code passed to it. -This handler passes control to another handler unless the exception is an integer or floating-point overflow. If it is, the handler calls a function (`ResetVars` is only an example, not an API function) to reset some global variables. The **`__except`** statement block, which in this example is empty, can never be executed because `Eval_Exception` never returns `EXCEPTION_EXECUTE_HANDLER` (1). +This handler passes control to another handler unless the exception is an integer or floating-point overflow. If it is, the handler calls a function (`HandleOverflow` is only an example, not an API function) to appropriately try to recover from the exception. The **`__except`** statement block, which in this example is empty, can never be executed because `Eval_Exception` never returns `EXCEPTION_EXECUTE_HANDLER` (1). Using a function call is a good general-purpose technique for dealing with complex filter expressions. Two other C language features that are useful are: @@ -53,13 +57,13 @@ Using a function call is a good general-purpose technique for dealing with compl The conditional operator is frequently useful here. It can be used to check for a specific return code and then return one of two different values. For example, the filter in the following code recognizes the exception only if the exception is `STATUS_INTEGER_OVERFLOW`: ```cpp -__except( GetExceptionCode() == STATUS_INTEGER_OVERFLOW ? 1 : 0 ) { +__except (GetExceptionCode() == STATUS_INTEGER_OVERFLOW ? 1 : 0) ``` The purpose of the conditional operator in this case is mainly to provide clarity, because the following code produces the same results: ```cpp -__except( GetExceptionCode() == STATUS_INTEGER_OVERFLOW ) { +__except (GetExceptionCode() == STATUS_INTEGER_OVERFLOW) ``` The conditional operator is more useful in situations where you might want the filter to evaluate to -1, `EXCEPTION_CONTINUE_EXECUTION`. @@ -67,7 +71,7 @@ The conditional operator is more useful in situations where you might want the f The comma operator lets you execute multiple expressions in sequence. It then returns the value of the last expression. For example, the following code stores the exception code in a variable and then tests it: ```cpp -__except( nCode = GetExceptionCode(), nCode == STATUS_INTEGER_OVERFLOW ) +__except (nCode = GetExceptionCode(), nCode == STATUS_INTEGER_OVERFLOW) ``` ## See also diff --git a/docs/cppcx/back-inserter-function.md b/docs/cppcx/back-inserter-function.md index 7e0f7a15e4..0860f65804 100644 --- a/docs/cppcx/back-inserter-function.md +++ b/docs/cppcx/back-inserter-function.md @@ -13,7 +13,6 @@ Returns an iterator that is used to insert elements at the end of the specified ## Syntax ``` - template Platform::BackInsertIterator back_inserter(IVector^ v); diff --git a/docs/cppcx/begin-function.md b/docs/cppcx/begin-function.md index f240fa91dd..dd0749fbe1 100644 --- a/docs/cppcx/begin-function.md +++ b/docs/cppcx/begin-function.md @@ -1,63 +1,58 @@ --- description: "Learn more about: begin Function" title: "begin Function" -ms.date: "01/22/2017" +ms.date: 09/27/2022 f1_keywords: ["collection/Windows::Foundation::Collections::begin"] helpviewer_keywords: ["begin Function"] ms.assetid: 5a44fb33-e247-49fd-b7a1-4a5b42e9e1e4 --- -# begin Function +# `begin` Function Returns an iterator that points to the beginning of a collection that is accessed by the specified interface parameter. ## Syntax -``` - +```cpp template ::Platform::Collections::VectorIterator - begin( - IVector^ v ); + begin(IVector^ v); template ::Platform::Collections::VectorViewIterator - begin( - IVectorView^ v - ); + begin(IVectorView^ v); template ::Platform::Collections::InputIterator - begin( - IIterable^ i ); + begin(IIterable^ i); ``` #### Parameters -*T*
+*`T`*\ A template type parameter. -*v*
-A collection of Vector\ or VectorView\ objects that are accessed by an IVector\ or IVectorView\ interface. +*`v`*\ +A collection of `Vector` or `VectorView` objects that are accessed by an `IVector` or `IVectorView` interface. -*i*
-A collection of arbitrary Windows Runtime objects that are accessed by an IIterable\ interface. +*`i`*\ +A collection of arbitrary Windows Runtime objects that are accessed by an `IIterable` interface. -### Return Value +### Return value An iterator that points to the beginning of the collection. ### Remarks -The first two template functions return iterators, and the third template function returns an input iterator. +The first two function templates return iterators, and the third function template returns an input iterator. -The VectorIterator object that is returned by begin is a proxy iterator that stores elements of type VectorProxy\. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +The `VectorIterator` object that is returned by `begin` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). ### Requirements **Header:** collection.h -**Namespace:** Windows::Foundation::Collections +**Namespace:** `Windows::Foundation::Collections` ## See also -[Windows::Foundation::Collections Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) +[`Windows::Foundation::Collections` namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) diff --git a/docs/cppcx/casting-c-cx.md b/docs/cppcx/casting-c-cx.md index 0815789fc4..621c4ab35d 100644 --- a/docs/cppcx/casting-c-cx.md +++ b/docs/cppcx/casting-c-cx.md @@ -43,14 +43,14 @@ Use safe_cast if the code does not declare the relationship but you are sure tha // ... A^ obj = ref new Class1(); - // You know that obj’s backing type implements A and B, but - // the compiler can’t tell this by comparing A and B. The run-time type check succeeds. + // You know that obj's backing type implements A and B, but + // the compiler can't tell this by comparing A and B. The run-time type check succeeds. B^ obj2 = safe_cast(obj); ``` ## dynamic_cast -Use **`dynamic_cast`** when you cast an object (more specifically, a hat **^**) to a more derived type, you expect either that the target object might sometimes be **`nullptr`** or that the cast might fail, and you want to handle that condition as a regular code path instead of an exception. For example, in the **Blank App (Universal Windows)** project template, the `OnLaunched` method in app.xaml.cpp uses **`dynamic_cast`** to test whether the app window has content. It's not an error if it doesn’t have content; it is an expected condition. `Windows::Current::Content` is a `Windows::UI::XAML::UIElement` and the conversion is to a `Windows::UI.XAML::Controls::Frame`, which is a more derived type in the inheritance hierarchy. +Use **`dynamic_cast`** when you cast an object (more specifically, a hat **^**) to a more derived type, you expect either that the target object might sometimes be **`nullptr`** or that the cast might fail, and you want to handle that condition as a regular code path instead of an exception. For example, in the **Blank App (Universal Windows)** project template, the `OnLaunched` method in app.xaml.cpp uses **`dynamic_cast`** to test whether the app window has content. It's not an error if it doesn't have content; it is an expected condition. `Windows::Current::Content` is a `Windows::UI::XAML::UIElement` and the conversion is to a `Windows::UI.XAML::Controls::Frame`, which is a more derived type in the inheritance hierarchy. ```cpp void App::OnLaunched(Windows::ApplicationModel::Activation::LaunchActivatedEventArgs^ args) @@ -77,7 +77,7 @@ You can also apply a **`dynamic_cast`** to a tracking reference, but in this cas ## reinterpret_cast -We recommend that you not use [reinterpret_cast](../cpp/reinterpret-cast-operator.md) because neither a compile-time check nor a run-time check is performed. In the worst case, a **`reinterpret_cast`** makes it possible for programming errors to go undetected at development time and cause subtle or catastrophic errors in your program’s behavior. Therefore, we recommend that you use **`reinterpret_cast`** only in those rare cases when you must cast between unrelated types and you know that the cast will succeed. An example of a rare use is to convert a Windows Runtime type to its underlying ABI type—this means that you are taking control of the reference counting for the object. To do this, we recommend that you use the [ComPtr Class](../cpp/com-ptr-t-class.md) smart pointer. Otherwise, you must specifically call Release on the interface. The following example shows how a ref class can be cast to an `IInspectable*`. +We recommend that you not use [reinterpret_cast](../cpp/reinterpret-cast-operator.md) because neither a compile-time check nor a run-time check is performed. In the worst case, a **`reinterpret_cast`** makes it possible for programming errors to go undetected at development time and cause subtle or catastrophic errors in your program's behavior. Therefore, we recommend that you use **`reinterpret_cast`** only in those rare cases when you must cast between unrelated types and you know that the cast will succeed. An example of a rare use is to convert a Windows Runtime type to its underlying ABI type—this means that you are taking control of the reference counting for the object. To do this, we recommend that you use the [ComPtr Class](../cpp/com-ptr-t-class.md) smart pointer. Otherwise, you must specifically call Release on the interface. The following example shows how a ref class can be cast to an `IInspectable*`. ```cpp #include @@ -97,7 +97,7 @@ If you use **`reinterpret_cast`** to convert from one Windows Runtime interface - Conversions between a Windows Runtime interface type and its equivalent ABI type are always safe—that is, `IBuffer^` to `ABI::IBuffer*`. -- A Windows Runtime runtime class should always be converted to `IInspectable*` or its default interface, if that is known. +- A Windows Runtime class should always be converted to `IInspectable*` or its default interface, if that is known. - After you convert to ABI types, you own the lifetime of the type and must follow the COM rules. We recommend that you use `WRL::ComPtr` to simplify lifetime management of ABI pointers. diff --git a/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h b/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h index 52efa84e74..9e8425b3b8 100644 --- a/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h +++ b/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h @@ -21,7 +21,7 @@ namespace PartialClassExample /* // This is commented out because it causes - // a compile error in Delcaration #6 due to mc already being defined. + // a compile error in Declaration #6 due to mc already being defined. // the error is understood. The example is most effective showing // the various declaration rules all in one example like this. // diff --git a/docs/cppcx/collections-c-cx.md b/docs/cppcx/collections-c-cx.md index e5de70a968..3d3caad993 100644 --- a/docs/cppcx/collections-c-cx.md +++ b/docs/cppcx/collections-c-cx.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: Collections (C++/CX)" title: "Collections (C++/CX)" +description: "Learn more about: Collections (C++/CX)" ms.date: "11/19/2018" -ms.assetid: 914da30b-aac5-4cd7-9da3-a5ac08cdd72c --- # Collections (C++/CX) @@ -14,9 +13,9 @@ The Windows Runtime defines the interfaces for collections and related types, an - The [Platform::Collections::Vector class](../cppcx/platform-collections-vector-class.md) resembles the [std::vector class](../standard-library/vector-class.md). -- The [Platform::Collections::Map Class](../cppcx/platform-collections-map-class.md) class resembles the [std::map class](../standard-library/map-class.md). +- The [Platform::Collections::Map class](../cppcx/platform-collections-map-class.md) resembles the [std::map class](../standard-library/map-class.md). -- [Platform::Collections::VectorView Class](../cppcx/platform-collections-vectorview-class.md) and[Platform::Collections::MapView Class](../cppcx/platform-collections-mapview-class.md) are read-only versions of `Vector` and `Map`. +- [Platform::Collections::VectorView class](../cppcx/platform-collections-vectorview-class.md) and [Platform::Collections::MapView class](../cppcx/platform-collections-mapview-class.md) are read-only versions of `Vector` and `Map`. - Iterators are defined in the [Platform::Collections Namespace](../cppcx/platform-collections-namespace.md). These iterators satisfy the requirements for STL iterators and enable the use of [std::find](../standard-library/algorithm-functions.md#find), [std::count_if](../standard-library/algorithm-functions.md#count_if), and other STL algorithms on any [Windows::Foundation::Collections](/uwp/api/windows.foundation.collections) interface type or [Platform::Collections](../cppcx/platform-collections-namespace.md) concrete type. For example, this means that you can iterate a collection in a Windows Runtime component that's created in C# and apply an STL algorithm to it. @@ -44,7 +43,7 @@ If you have existing code that uses `std::vector` and you want to reuse it in a [!code-cpp[cx_collections#02](../cppcx/codesnippet/CPP/collections/class1.cpp#02)] -If you have a vector of strings that you must pass across the ABI at some future point, you must decide whether to create the strings initially as `std::wstring` types or as `Platform::String^` types. If you have to do a lot of processing on the strings, then use `wstring`. Otherwise, create the strings as `Platform::String^` types and avoid the cost of converting them later. You must also decide whether to put these strings into a `std:vector` or `Platform::Collections::Vector` internally. As a general practice, use `std::vector` and then create a `Platform::Vector` from it only when you pass the container across the ABI. +If you have a vector of strings that you must pass across the ABI at some future point, you must decide whether to create the strings initially as `std::wstring` types or as `Platform::String^` types. If you have to do a lot of processing on the strings, then use `wstring`. Otherwise, create the strings as `Platform::String^` types and avoid the cost of converting them later. You must also decide whether to put these strings into a `std::vector` or `Platform::Collections::Vector` internally. As a general practice, use `std::vector` and then create a `Platform::Vector` from it only when you pass the container across the ABI. ## Value types in Vector @@ -95,27 +94,27 @@ Collections fall into four categories: modifiable versions and read-only version Elements of a modifiable collection can be changed, but elements of a read-only collection, which is known as a *view*, can only be read. Elements of a [Platform::Collections::Vector](../cppcx/platform-collections-vector-class.md) or[Platform::Collections::VectorView](../cppcx/platform-collections-vectorview-class.md) collection can be accessed by using an iterator or the collection's [Vector::GetAt](../cppcx/platform-collections-vector-class.md#getat) and an index. Elements of an associative collection can be accessed by using the collection's [Map::Lookup](../cppcx/platform-collections-map-class.md#lookup) and a key. -[Platform::Collections::Map Class](../cppcx/platform-collections-map-class.md)
+[Platform::Collections::Map class](../cppcx/platform-collections-map-class.md)\ A modifiable, associative collection. Map elements are key-value pairs. Looking up a key to retrieve its associated value, and iterating through all key-value pairs, are both supported. `Map` and `MapView` are templated on `>`; therefore, you can customize the comparator. Additionally, `Vector` and `VectorView` are templated on `>` so that you can customize the behavior of `IndexOf()`. This is important mostly for `Vector` and `VectorView` of value structs. For example, to create a Vector\, you must provide a custom comparator because DateTime does not overload the == operator. -[Platform::Collections::MapView Class](../cppcx/platform-collections-mapview-class.md)
+[Platform::Collections::MapView class](../cppcx/platform-collections-mapview-class.md)\ A read-only version of a `Map`. -[Platform::Collections::Vector Class](../cppcx/platform-collections-vector-class.md)
-A modifiable sequence collection. `Vector` supports constant-time random access and amortized-constant-time [Append](../cppcx/platform-collections-vector-class.md#append) operations.. +[Platform::Collections::Vector class](../cppcx/platform-collections-vector-class.md)\ +A modifiable sequence collection. `Vector` supports constant-time random access and amortized-constant-time [Append](../cppcx/platform-collections-vector-class.md#append) operations. -[Platform::Collections::VectorView Class](../cppcx/platform-collections-vectorview-class.md)
+[Platform::Collections::VectorView class](../cppcx/platform-collections-vectorview-class.md)\ A read-only version of a `Vector`. -[Platform::Collections::InputIterator Class](../cppcx/platform-collections-inputiterator-class.md)
+[Platform::Collections::InputIterator class](../cppcx/platform-collections-inputiterator-class.md)\ An STL iterator that satisfies the requirements of an STL input iterator. -[Platform::Collections::VectorIterator Class](../cppcx/platform-collections-vectoriterator-class.md)
+[Platform::Collections::VectorIterator class](../cppcx/platform-collections-vectoriterator-class.md)\ An STL iterator that satisfies the requirements of an STL mutable random-access iterator. -[Platform::Collections::VectorViewIterator Class](../cppcx/platform-collections-vectorviewiterator-class.md)
+[Platform::Collections::VectorViewIterator class](../cppcx/platform-collections-vectorviewiterator-class.md)\ An STL iterator that satisfies the requirements of an STL **`const`** random-access iterator. ### begin() and end() functions @@ -140,6 +139,6 @@ The [Windows::Foundation::Collections::VectorChangedEventHandler](/uwp/api/windo ## See also -[Type System](../cppcx/type-system-c-cx.md)
-[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)
+[Type System](../cppcx/type-system-c-cx.md)\ +[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)\ [Namespaces Reference](../cppcx/namespaces-reference-c-cx.md) diff --git a/docs/cppcx/compiler-and-linker-options-c-cx.md b/docs/cppcx/compiler-and-linker-options-c-cx.md index f8597586f6..ff2700a08a 100644 --- a/docs/cppcx/compiler-and-linker-options-c-cx.md +++ b/docs/cppcx/compiler-and-linker-options-c-cx.md @@ -26,7 +26,7 @@ The %LIBPATH% environment variable specifies the default path to search for .win |Option|Description| |------------|-----------------| |/APPCONTAINER[:NO]|Marks the executable as runnable in the appcontainer (only).| -|/WINMD[:{NO|ONLY}]|Emits a .winmd file and an associated binary file. This option must be passed to the linker for a .winmd to be emitted.

**NO**—Doesn't emit a .winmd file, but does emit a binary file.

**ONLY**—Emits a .winmd file, but doesn't emit a binary file.| +|/WINMD[:{NO\|ONLY}]|Emits a .winmd file and an associated binary file. This option must be passed to the linker for a .winmd to be emitted.

**NO**—Doesn't emit a .winmd file, but does emit a binary file.

**ONLY**—Emits a .winmd file, but doesn't emit a binary file.| |/WINMDFILE:*filename*|The name of the .winmd file to emit, instead of the default .winmd file name. If multiple file names are specified on the command line, the last name is used.| |/WINMDDELAYSIGN[:NO]|Partially signs the .winmd file and places the public key in the binary.

**NO**—(Default) Doesn't sign the .winmd file.

/WINMDDELAYSIGN has no effect unless /WINMDKEYFILE or /WINMDKEYCONTAINER is also specified.| |/WINMDKEYCONTAINER:*name*|Specifies a key container to sign an assembly. The *name* parameter corresponds to the key container that's used to sign the metadata file.| diff --git a/docs/cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md b/docs/cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md index 602af8f276..9291df90cc 100644 --- a/docs/cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md +++ b/docs/cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md @@ -1,8 +1,7 @@ --- title: "CRT functions not supported in Universal Windows Platform apps" description: "Reference guide to CRT functions not supported in Universal Windows Platform apps." -ms.date: "04/16/2020" -ms.assetid: cbfc957d-6c60-48f4-97e3-1ed8526743b4 +ms.date: 04/16/2020 --- # CRT functions not supported in Universal Windows Platform apps @@ -47,4 +46,4 @@ Both the previously mentioned APIs and the following APIs are unavailable in Win |`_chdir` `_wchdir` `_getcwd` `_getdcwd` `_wgetcwd` `_wgetdcwd`|The concept of a working directory doesn't apply to Windows 8.x Store apps.|Use full paths instead.| |`_isleadbyte_l` `_ismbbalnum`, `_ismbbalnum_l`, `_ismbbalpha`, `_ismbbalpha` `_ismbbalpha_l` `_ismbbgraph` `_ismbbgraph_l` `_ismbbkalnum` `_ismbbkalnum_l` `_ismbbkana` `_ismbbkana_l` `_ismbbkprint` `_ismbbkprint_l` `_ismbbkpunct` `_ismbbkpunct_l` `_ismbblead` `_ismbblead_l` `_ismbbprint` `_ismbbprint_l` `_ismbbpunct` `_ismbbpunct_l` `_ismbbtrail` `_ismbbtrail_l` `_ismbslead` `_ismbslead_l` `_ismbstrail` `_ismbstrail_l` `_mbsdup` `isleadbyte`|Multi-byte strings are not supported in Windows 8.x Store apps.|Use Unicode strings instead.| |`_tzset`|Environment variables are not available to Windows 8.x Store apps.|No workaround.| -|`_get_heap_handle`, `_heapmin`|The corresponding Win32 APIs are not supported in Windows 8.x Store apps. And, apps can no longer create private heaps.|No workaround. However, ``_get_heap_handle`` is available in the DEBUG CRT, for debugging purposes only.| +|`_get_heap_handle`, `_heapmin`|The corresponding Win32 APIs are not supported in Windows 8.x Store apps. And, apps can no longer create private heaps.|No workaround. However, `_get_heap_handle` is available in the DEBUG CRT, for debugging purposes only.| diff --git a/docs/cppcx/delegates-c-cx.md b/docs/cppcx/delegates-c-cx.md index 1da0f2675b..3ea53942eb 100644 --- a/docs/cppcx/delegates-c-cx.md +++ b/docs/cppcx/delegates-c-cx.md @@ -12,13 +12,13 @@ The **`delegate`** keyword is used to declare a reference type that is the Windo public delegate void PrimeFoundHandler(int result); ``` -Delegates are most commonly used in conjunction with events. An event has a delegate type, in much the same way that a class can have an interface type. The delegate represents a contract that event handlers much fulfill. Here’s an event class member whose type is the previously-defined delegate: +Delegates are most commonly used in conjunction with events. An event has a delegate type, in much the same way that a class can have an interface type. The delegate represents a contract that event handlers much fulfill. Here's an event class member whose type is the previously-defined delegate: ```cpp event PrimeFoundHandler^ primeFoundEvent; ``` -When declaring delegates that will be exposed to clients across the Windows Runtime application binary interface, use [Windows::Foundation::TypedEventHandler\](/uwp/api/windows.foundation.typedeventhandler-2). This delegate has predefined proxy and stub binaries that enable it to be consumed by Javascript clients. +When declaring delegates that will be exposed to clients across the Windows Runtime application binary interface, use [Windows::Foundation::TypedEventHandler\](/uwp/api/windows.foundation.typedeventhandler-2). This delegate has predefined proxy and stub binaries that enable it to be consumed by JavaScript clients. ## Consuming delegates @@ -81,7 +81,7 @@ It then calls the member function and passes the delegate. Assume that `ci` is a In the next example, a client app passes a custom delegate to a public method in a Windows Runtime component that executes the delegate against each item in a `Vector`: [!code-cpp[Cx_delegates#118](../cppcx/codesnippet/CPP/clientapp/mainpage.xaml.cpp#118)] - +  [!code-cpp[Cx_delegates#119](../cppcx/codesnippet/CPP/delegatesevents/class1.cpp#119)] ### Construction @@ -105,7 +105,7 @@ The following example shows how to construct a delegate from each of these objec ### Generic delegates -Generic delegates in C++/CX have restrictions similar to declarations of generic classes. They cannot be declared as public. You can declare a private or internal generic delegate and consume it from C++, but .NET or JavaScript clients can’t consume it because it is not emitted into the .winmd metadata. This example declares a generic delegate that can only be consumed by C++: +Generic delegates in C++/CX have restrictions similar to declarations of generic classes. They cannot be declared as public. You can declare a private or internal generic delegate and consume it from C++, but .NET or JavaScript clients can't consume it because it is not emitted into the .winmd metadata. This example declares a generic delegate that can only be consumed by C++: [!code-cpp[Cx_delegates#116](../cppcx/codesnippet/CPP/delegatesevents/class1.h#116)] @@ -123,7 +123,7 @@ If the code that executes the delegate is running on a different thread—for ex If you want your created delegate to be called back on the same thread that it was created on—for example, if you pass it to a component that runs in an MTA apartment—and you want it to be invoked on the same thread as the creator, then use the delegate constructor overload that takes a second `CallbackContext` parameter. Only use this overload on delegates that have a registered proxy/stub; not all of the delegates that are defined in Windows.winmd are registered. -If you are familiar with event handlers in .NET, you know that the recommended practice is to make a local copy of an event before you fire it. This avoids race conditions in which an event handler might be removed just before the event is invoked. It isn’t necessary to do this in C++/CX because when event handlers are added or removed a new handler list is created. Because a C++ object increments the reference count on the handler list before invoking an event, it is guaranteed that all handlers will be valid. However, this also means that if you remove an event handler on the consuming thread, that handler might still get invoked if the publishing object is still operating on its copy of the list, which is now out-of-date. The publishing object will not get the updated list until the next time it fires the event. +If you are familiar with event handlers in .NET, you know that the recommended practice is to make a local copy of an event before you fire it. This avoids race conditions in which an event handler might be removed just before the event is invoked. It isn't necessary to do this in C++/CX because when event handlers are added or removed a new handler list is created. Because a C++ object increments the reference count on the handler list before invoking an event, it is guaranteed that all handlers will be valid. However, this also means that if you remove an event handler on the consuming thread, that handler might still get invoked if the publishing object is still operating on its copy of the list, which is now out-of-date. The publishing object will not get the updated list until the next time it fires the event. ## See also diff --git a/docs/cppcx/deprecating-types-and-members-c-cx.md b/docs/cppcx/deprecating-types-and-members-c-cx.md index 85471b58e5..8c17a5e3a8 100644 --- a/docs/cppcx/deprecating-types-and-members-c-cx.md +++ b/docs/cppcx/deprecating-types-and-members-c-cx.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Deprecating types and members (C++/CX)" title: "Deprecating types and members (C++/CX)" +description: "Learn more about: Deprecating types and members (C++/CX)" ms.date: 01/07/2022 no-loc: [ "class", "delegate", "enum", "field", "interface", "method", "property", "struct" ] --- @@ -13,7 +13,7 @@ C++/CX supports deprecation of Windows Runtime types and members for producers a ## Example -The following example shows how to deprecate your own public APIs—for example, in a Windows Runtime component. The second parameter, of type [`Windows:Foundation::Metadata::DeprecationType`](/uwp/api/windows.foundation.metadata.deprecationtype) specifies whether the API is being deprecated or removed. Currently only the `DeprecationType::Deprecated` value is supported. The third parameter in the attribute specifies the [`Windows::Foundation::Metadata::Platform`](/uwp/api/windows.foundation.metadata.platformattribute) to which the attribute applies. +The following example shows how to deprecate your own public APIs—for example, in a Windows Runtime component. The second parameter, of type [`Windows::Foundation::Metadata::DeprecationType`](/uwp/api/windows.foundation.metadata.deprecationtype) specifies whether the API is being deprecated or removed. Currently only the `DeprecationType::Deprecated` value is supported. The third parameter in the attribute specifies the [`Windows::Foundation::Metadata::Platform`](/uwp/api/windows.foundation.metadata.platformattribute) to which the attribute applies. ```cpp namespace wfm = Windows::Foundation::Metadata; diff --git a/docs/cppcx/dlls-c-cx.md b/docs/cppcx/dlls-c-cx.md index e3ed96ed35..a9d97df533 100644 --- a/docs/cppcx/dlls-c-cx.md +++ b/docs/cppcx/dlls-c-cx.md @@ -22,7 +22,7 @@ For more information, see [Creating Windows Runtime Components in C++](/windows/ ## Standard DLLs -You can create a standard DLL for C++ code that doesn’t consume or produce public Windows Runtime types and consume it from a UWP app. Use the Dynamic-Link Library (DLL) project type when you just want to migrate an existing DLL to compile in this version of Visual Studio but not convert the code to a Windows Runtime Component project. When you use the following steps, the DLL will be deployed alongside your app executable in the .appx package. +You can create a standard DLL for C++ code that doesn't consume or produce public Windows Runtime types and consume it from a UWP app. Use the Dynamic-Link Library (DLL) project type when you just want to migrate an existing DLL to compile in this version of Visual Studio but not convert the code to a Windows Runtime Component project. When you use the following steps, the DLL will be deployed alongside your app executable in the .appx package. ### To create a standard DLL in Visual Studio diff --git a/docs/cppcx/end-function.md b/docs/cppcx/end-function.md index 6c75d827eb..dc3a983fb3 100644 --- a/docs/cppcx/end-function.md +++ b/docs/cppcx/end-function.md @@ -1,63 +1,57 @@ --- description: "Learn more about: end Function" title: "end Function" -ms.date: "01/22/2017" +ms.date: 09/27/2022 f1_keywords: ["collection/Windows::Foundation::Collections::end"] helpviewer_keywords: ["end Function"] ms.assetid: fb837bff-fc76-4bae-9096-facf0e03041c --- -# end Function +# `end` function Returns an iterator that points beyond the end of a collection that is accessed by the specified interface parameter. ## Syntax -``` - +```cpp template ::Platform::Collections::VectorIterator - end( - IVector^ v ); + end(IVector^ v); template ::Platform::Collections::VectorViewIterator - end( - IVectorView^ v - ); + end(IVectorView^ v); template ::Platform::Collections::InputIterator - end( - IIterable^ i - ); + end(IIterable^ i); ``` -#### Parameters +### Parameters -*T*
+*`T`*\ A template type parameter. -*v*
-A collection of Vector\ or VectorView\ objects that are accessed by an IVector\, or IVectorView\ interface. +*`v`*\ +A collection of `Vector` or `VectorView` objects that are accessed by an `IVector`, or `IVectorView` interface. -*i*
-A collection of arbitraty Windows Runtime objects that are accessed by an IIterable\ interface. +*`i`*\ +A collection of arbitrary Windows Runtime objects that are accessed by an `IIterable` interface. -### Return Value +## Return Value An iterator that points beyond the end of the collection. -### Remarks +## Remarks -The first two template functions return iterators, and the third template function returns an input iterator. +The first two function templates return iterators, and the third function template returns an input iterator. -The [Platform::Collections::VectorViewIterator](../cppcx/platform-collections-vectorviewiterator-class.md) object that is returned by `end` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +The [`Platform::Collections::VectorViewIterator`](../cppcx/platform-collections-vectorviewiterator-class.md) object that is returned by `end` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). -### Requirements +## Requirements **Header:** collection.h -**Namespace:** Windows::Foundation::Collections +**Namespace:** `Windows::Foundation::Collections` ## See also -[Windows::Foundation::Collections Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) +[`Windows::Foundation::Collections` Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) diff --git a/docs/cppcx/enums-c-cx.md b/docs/cppcx/enums-c-cx.md index 964fbe106e..f0d9e1ff1c 100644 --- a/docs/cppcx/enums-c-cx.md +++ b/docs/cppcx/enums-c-cx.md @@ -12,7 +12,7 @@ C++/CX supports the `public enum class` keyword, which is analogous to a standar A `public enum class` that doesn't have an access specifier, such as **`public`**, is treated as a standard C++ [scoped enum](../cpp/enumerations-cpp.md). -A `public enum class` or `public enum struct` declaration can have an underlying type of any integral type although the Windows Runtime itself requires that the type be int32, or uint32 for a flags enum. The following syntax describes the parts of an `public enum class` or `public enum struct`. +A `public enum class` or `public enum struct` declaration can have an underlying type of any integral type although the Windows Runtime itself requires that the type be int32, or uint32 for a flags enum. The following syntax describes the parts of a `public enum class` or `public enum struct`. This example shows how to define a public enum class: diff --git a/docs/cppcx/events-c-cx.md b/docs/cppcx/events-c-cx.md index 404e0b5d80..d0a5ef857c 100644 --- a/docs/cppcx/events-c-cx.md +++ b/docs/cppcx/events-c-cx.md @@ -10,7 +10,7 @@ A Windows Runtime type can declare (that is, publish) events, and client code in ## Consuming events in Windows components -Many components in the Windows Runtime expose events. For example, a LightSensor object fires a ReadingChanged event when the sensor reports a new luminescence value. When you use a LightSensor object in your program, you can define a method that will be called when the ReadingChanged event is fired. The method can do whatever you want it to do; the only requirement is that its signature must match the signature of the delegate that is invoked. For more information about how to create an delegate event handler and subscribe to an event, see [Delegates](../cppcx/delegates-c-cx.md). +Many components in the Windows Runtime expose events. For example, a LightSensor object fires a ReadingChanged event when the sensor reports a new luminescence value. When you use a LightSensor object in your program, you can define a method that will be called when the ReadingChanged event is fired. The method can do whatever you want it to do; the only requirement is that its signature must match the signature of the delegate that is invoked. For more information about how to create a delegate event handler and subscribe to an event, see [Delegates](../cppcx/delegates-c-cx.md). ## Creating custom events diff --git a/docs/cppcx/fundamental-types-c-cx.md b/docs/cppcx/fundamental-types-c-cx.md index 4f1bd6c1d8..47155e3cdb 100644 --- a/docs/cppcx/fundamental-types-c-cx.md +++ b/docs/cppcx/fundamental-types-c-cx.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Fundamental types (C++/CX)" title: "Fundamental types (C++/CX)" +description: "Learn more about: Fundamental types (C++/CX)" ms.date: "01/22/2017" -ms.assetid: c9f82907-25f2-440b-91d6-afb8dbd46ea6 --- # Fundamental types (C++/CX) -In addition to the standard C++ built-in types, C++/CX supports the type system that's defined by the Windows Runtime architecture by providing typedefs for the Windows Runtime fundamental types that map to standard C++ types.. C++/CX implements Boolean, character, and numeric fundamental types. These typedefs are defined in the `default` namespace, which never needs to be specified explicitly. In addition, C++/CX provides wrappers and concrete implementations for certain Windows Runtime types and interfaces. +In addition to the standard C++ built-in types, C++/CX supports the type system that's defined by the Windows Runtime architecture by providing typedefs for the Windows Runtime fundamental types that map to standard C++ types. C++/CX implements Boolean, character, and numeric fundamental types. These typedefs are defined in the `default` namespace, which never needs to be specified explicitly. In addition, C++/CX provides wrappers and concrete implementations for certain Windows Runtime types and interfaces. ## Boolean and Character Types diff --git a/docs/cppcx/interfaces-c-cx.md b/docs/cppcx/interfaces-c-cx.md index bef57c95d8..eff0d69066 100644 --- a/docs/cppcx/interfaces-c-cx.md +++ b/docs/cppcx/interfaces-c-cx.md @@ -86,7 +86,7 @@ Here's how Windows Runtime types can be used to author a generic interface: - In the interface, any reference to the current interface—in a method parameter, return value, or property—is assumed to refer to the current instantiation. For example, *IMyIntf* means *IMyIntf\*. -- When the type of a method parameter is a type parameter, the declaration of that parameter or variable uses the type parameter’s name without any pointer, native reference, or handle declarators. In other words, you never write "T^". +- When the type of a method parameter is a type parameter, the declaration of that parameter or variable uses the type parameter's name without any pointer, native reference, or handle declarators. In other words, you never write "T^". - Templated ref classes must be private. They can implement generic interfaces, and can pass template parameter *T* to generic argument *T*. Each instantiation of a templated ref class is itself a ref class. diff --git a/docs/cppcx/operator-type-hat.md b/docs/cppcx/operator-type-hat.md index 04b0546b10..658cfdad71 100644 --- a/docs/cppcx/operator-type-hat.md +++ b/docs/cppcx/operator-type-hat.md @@ -20,7 +20,7 @@ Returns a `Platform::Type` when given a [Windows::UI::Xaml::Interop::TypeName](/ ### Remarks -`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can’t be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: +`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can't be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: ``` rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); @@ -31,7 +31,6 @@ rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); The next example shows how to convert between `TypeName` and `Type`. ``` - // Convert from Type to TypeName TypeName tn = TypeName(MainPage::typeid); diff --git a/docs/cppcx/operator-windows-ui-xaml-interop-typename.md b/docs/cppcx/operator-windows-ui-xaml-interop-typename.md index ea83d67b0d..750e6301a9 100644 --- a/docs/cppcx/operator-windows-ui-xaml-interop-typename.md +++ b/docs/cppcx/operator-windows-ui-xaml-interop-typename.md @@ -20,7 +20,7 @@ Returns a [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.intero ### Remarks -`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can’t be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: +`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can't be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: ```cpp rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); diff --git a/docs/cppcx/partial-classes-c-cx.md b/docs/cppcx/partial-classes-c-cx.md index b17036025e..d6e18b397e 100644 --- a/docs/cppcx/partial-classes-c-cx.md +++ b/docs/cppcx/partial-classes-c-cx.md @@ -69,7 +69,7 @@ At the point of the full definition of the class X, the behavior is the same as The following two code examples have identical meaning and effect. The first example uses a partial class and the second example doesn't. [!code-cpp[cx_partial#05](../cppcx/codesnippet/CPP/partialclassexample/class1.h#05)] - +  [!code-cpp[cx_partial#06](../cppcx/codesnippet/CPP/partialclassexample/class1.h#06)] ## Templates @@ -87,7 +87,7 @@ The **`partial`** keyword is supported only in combination with the **`ref class The following example defines the `Address` class across two code files. The designer modifies `Address.details.h` and you modify `Address.h`. Only the class definition in the first file uses the **`partial`** keyword. [!code-cpp[cx_partial#07](../cppcx/codesnippet/CPP/partialclassexample/address.details.h#07)] - +  [!code-cpp[cx_partial#09](../cppcx/codesnippet/CPP/partialclassexample/address.h#09)] ## See also diff --git a/docs/cppcx/platform-accessdeniedexception-class.md b/docs/cppcx/platform-accessdeniedexception-class.md index bf6cbaed0b..cc50d74596 100644 --- a/docs/cppcx/platform-accessdeniedexception-class.md +++ b/docs/cppcx/platform-accessdeniedexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::AccessDeniedException Class" title: "Platform::AccessDeniedException Class" +description: "Learn more about: Platform::AccessDeniedException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::AccessDeniedException", "VCCORLIB/Platform::AccessDeniedException::AccessDeniedException"] helpviewer_keywords: ["Platform::AccessDeniedException"] -ms.assetid: 6ae2155b-7b16-4587-8d2d-da05eab4c7e9 --- # Platform::AccessDeniedException Class @@ -14,7 +13,7 @@ Thrown when access to a resource or feature is denied. ## Syntax ```cpp -public ref class AccessDeniedException : COMException, IException, IPrintable, IEquatable +public ref class AccessDeniedException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-agile-class.md b/docs/cppcx/platform-agile-class.md index 59f73faa71..26713d7fe9 100644 --- a/docs/cppcx/platform-agile-class.md +++ b/docs/cppcx/platform-agile-class.md @@ -146,7 +146,7 @@ The address of a handle to an object of type `T`. ### Remarks -This operation releases the current representation of a object of type `T`, if any; reinitializes the Agile object's data members; acquires the current threading context; and then returns the address of a handle-to-object variable that can represent a non-agile object. To cause an Agile class instance to represent an object, use the assignment operator ([Agile::operator=](#operator-assign)) to assign the object to the Agile class instance. +This operation releases the current representation of an object of type `T`, if any; reinitializes the Agile object's data members; acquires the current threading context; and then returns the address of a handle-to-object variable that can represent a non-agile object. To cause an Agile class instance to represent an object, use the assignment operator ([Agile::operator=](#operator-assign)) to assign the object to the Agile class instance. ## Agile::GetAddressOfForInOut Method diff --git a/docs/cppcx/platform-changedstateexception-class.md b/docs/cppcx/platform-changedstateexception-class.md index b123e94431..6fc1201500 100644 --- a/docs/cppcx/platform-changedstateexception-class.md +++ b/docs/cppcx/platform-changedstateexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::ChangedStateException Class" title: "Platform::ChangedStateException Class" +description: "Learn more about: Platform::ChangedStateException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::ChangedStateException", "VCCORLIB/Platform::ChangedStateException::ChangedStateException"] helpviewer_keywords: ["Platform::ChangedStateException"] -ms.assetid: f894beac-9e80-4fac-ac25-89f1dbc0a6a4 --- # Platform::ChangedStateException Class @@ -14,7 +13,7 @@ Thrown when the internal state of an object has changed, thereby invalidating th ## Syntax ```cpp -public ref class ChangedStateException : COMException, IException, IPrintable, IEquatable +public ref class ChangedStateException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-classnotregisteredexception-class.md b/docs/cppcx/platform-classnotregisteredexception-class.md index 9fa2b99397..0108e2bff6 100644 --- a/docs/cppcx/platform-classnotregisteredexception-class.md +++ b/docs/cppcx/platform-classnotregisteredexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::ClassNotRegisteredException Class" title: "Platform::ClassNotRegisteredException Class" +description: "Learn more about: Platform::ClassNotRegisteredException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::ClassNotRegisteredException::ClassNotRegisteredException", "VCCORLIB/Platform::ClassNotRegisteredException"] helpviewer_keywords: ["Platform::ClassNotRegisteredException"] -ms.assetid: 8f8871d8-51b9-46e8-902e-ae023c9f1de9 --- # Platform::ClassNotRegisteredException Class @@ -14,7 +13,7 @@ Thrown when a COM class has not been registered. ## Syntax ```cpp -public ref class ClassNotRegisteredException : COMException, IException, IPrintable, IEquatable +public ref class ClassNotRegisteredException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-collections-inputiterator-class.md b/docs/cppcx/platform-collections-inputiterator-class.md index dac7e5cdab..f2d5367a68 100644 --- a/docs/cppcx/platform-collections-inputiterator-class.md +++ b/docs/cppcx/platform-collections-inputiterator-class.md @@ -30,7 +30,7 @@ The typename of the InputIterator template class. |Name|Description| |----------|-----------------| |`difference_type`|A pointer difference (ptrdiff_t).| -|`iterator_category`|The category of a input iterator (::std::input_iterator_tag).| +|`iterator_category`|The category of an input iterator (::std::input_iterator_tag).| |`pointer`|A pointer to a `const X`| |`reference`|A reference to a `const X`| |`value_type`|The `X` typename.| diff --git a/docs/cppcx/platform-collections-map-class.md b/docs/cppcx/platform-collections-map-class.md index 21b981e5f6..473101cef0 100644 --- a/docs/cppcx/platform-collections-map-class.md +++ b/docs/cppcx/platform-collections-map-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Collections::Map Class" title: "Platform::Collections::Map Class" -ms.date: "10/01/2019" +description: "Learn more about: Platform::Collections::Map Class" +ms.date: 10/01/2019 ms.topic: "reference" f1_keywords: ["COLLECTION/Platform::Collections::Map::Map", "COLLECTION/Platform::Collections::Map::Clear", "COLLECTION/Platform::Collections::Map::First", "COLLECTION/Platform::Collections::Map::GetView", "COLLECTION/Platform::Collections::Map::HasKey", "COLLECTION/Platform::Collections::Map::Insert", "COLLECTION/Platform::Collections::Map::Lookup", "COLLECTION/Platform::Collections::Map::Remove", "COLLECTION/Platform::Collections::Map::Size"] helpviewer_keywords: ["Map Class (C++/Cx)"] -ms.assetid: 2b8cf968-1167-4898-a149-1195b32c1785 --- # Platform::Collections::Map Class @@ -206,7 +205,7 @@ Initializes a new instance of the Map class. ```cpp explicit Map(const C& comp = C()); explicit Map(const StdMap& m); -explicit Map(StdMap&& m ; +explicit Map(StdMap&& m); template Map( InItfirst, diff --git a/docs/cppcx/platform-collections-mapview-class.md b/docs/cppcx/platform-collections-mapview-class.md index 67ca96405d..2f166b244e 100644 --- a/docs/cppcx/platform-collections-mapview-class.md +++ b/docs/cppcx/platform-collections-mapview-class.md @@ -90,7 +90,6 @@ Determines whether the current MapView contains the specified key. ### Syntax ``` - bool HasKey(K key); ``` diff --git a/docs/cppcx/platform-collections-namespace.md b/docs/cppcx/platform-collections-namespace.md index f079c117af..1cffd68521 100644 --- a/docs/cppcx/platform-collections-namespace.md +++ b/docs/cppcx/platform-collections-namespace.md @@ -9,7 +9,7 @@ ms.assetid: b5042864-5f22-40b7-b7a5-c0691f65cc47 --- # Platform::Collections Namespace -The Platform::Collections namespace contains the `Map`, `MapView`, `Vector`, and `VectorView` classes. These classes are concrete implementations of the corresponding interfaces that are defined in the [Windows::Foundation::Collections](/uwp/api/windows.foundation.collections) namespace. The concrete collection types are not portable across the ABI (for example when a Javascript or C# program calls into a C++ component), but they are implicitly convertible to their corresponding interface types. For example, if you implement a public method that populates and returns a collection, then use [Platform::Collections::Vector](../cppcx/platform-collections-vector-class.md) to implement the collection internally and use [Windows::Foundation::Collections::IVector](/uwp/api/windows.foundation.collections.ivector-1) as the return type. For more information, see [Collections](../cppcx/collections-c-cx.md) and [Creating Windows Runtime Components in C++](/windows/uwp/winrt-components/creating-windows-runtime-components-in-cpp). +The Platform::Collections namespace contains the `Map`, `MapView`, `Vector`, and `VectorView` classes. These classes are concrete implementations of the corresponding interfaces that are defined in the [Windows::Foundation::Collections](/uwp/api/windows.foundation.collections) namespace. The concrete collection types are not portable across the ABI (for example when a JavaScript or C# program calls into a C++ component), but they are implicitly convertible to their corresponding interface types. For example, if you implement a public method that populates and returns a collection, then use [Platform::Collections::Vector](../cppcx/platform-collections-vector-class.md) to implement the collection internally and use [Windows::Foundation::Collections::IVector](/uwp/api/windows.foundation.collections.ivector-1) as the return type. For more information, see [Collections](../cppcx/collections-c-cx.md) and [Creating Windows Runtime Components in C++](/windows/uwp/winrt-components/creating-windows-runtime-components-in-cpp). You can construct a Platform::Collections::Vector from a [std::vector](../standard-library/vector-class.md) and a [Platform::Collections::Map](../cppcx/platform-collections-map-class.md) from a [std::map](../standard-library/map-class.md). diff --git a/docs/cppcx/platform-collections-unorderedmap-class.md b/docs/cppcx/platform-collections-unorderedmap-class.md index d79f646dd1..a2a55e7132 100644 --- a/docs/cppcx/platform-collections-unorderedmap-class.md +++ b/docs/cppcx/platform-collections-unorderedmap-class.md @@ -46,7 +46,7 @@ Allowed types are: - public enum class -**UnorderedMap** is basically a wrapper for [std::unordered_map](../standard-library/unordered-map-class.md) that supports storage of Windows Runtime types. It is the a concrete implementation of the [Windows::Foundation::Collections::IMap](/uwp/api/windows.foundation.collections.imap-2) and [IObservableMap](/uwp/api/windows.foundation.collections.iobservablemap-2) types that are passed across public Windows Runtime interfaces. If you try to use a `Platform::Collections::UnorderedMap` type in a public return value or parameter, compiler error C3986 is raised. You can fix the error by changing the type of the parameter or return value to [Windows::Foundation::Collections::IMap](/uwp/api/windows.foundation.collections.imap-2). +**UnorderedMap** is basically a wrapper for [std::unordered_map](../standard-library/unordered-map-class.md) that supports storage of Windows Runtime types. It is the concrete implementation of the [Windows::Foundation::Collections::IMap](/uwp/api/windows.foundation.collections.imap-2) and [IObservableMap](/uwp/api/windows.foundation.collections.iobservablemap-2) types that are passed across public Windows Runtime interfaces. If you try to use a `Platform::Collections::UnorderedMap` type in a public return value or parameter, compiler error C3986 is raised. You can fix the error by changing the type of the parameter or return value to [Windows::Foundation::Collections::IMap](/uwp/api/windows.foundation.collections.imap-2). For more information, see [Collections](../cppcx/collections-c-cx.md). @@ -119,7 +119,7 @@ A convenient way to hold the iterator returned by First() is to assign the retur ## UnorderedMap::GetView Method -Returns a read-only view of the current UnorderedMap; that is, an [Platform::Collections::UnorderedMapView Class](../cppcx/platform-collections-unorderedmapview-class.md) that implements the [Windows::Foundation::Collections::IMapView::IMapView](/uwp/api/windows.foundation.collections.imapview-2) interface. +Returns a read-only view of the current UnorderedMap; that is, a [Platform::Collections::UnorderedMapView Class](../cppcx/platform-collections-unorderedmapview-class.md) that implements the [Windows::Foundation::Collections::IMapView::IMapView](/uwp/api/windows.foundation.collections.imapview-2) interface. ### Syntax diff --git a/docs/cppcx/platform-collections-vectoriterator-class.md b/docs/cppcx/platform-collections-vectoriterator-class.md index f6a5f65660..f7d2ee8c9f 100644 --- a/docs/cppcx/platform-collections-vectoriterator-class.md +++ b/docs/cppcx/platform-collections-vectoriterator-class.md @@ -1,29 +1,28 @@ --- +title: "Platform::Collections::VectorIterator class" description: "Learn more about: Platform::Collections::VectorIterator Class" -title: "Platform::Collections::VectorIterator Class" ms.date: "03/27/2019" ms.topic: "reference" f1_keywords: ["COLLECTION/Platform::Collections::VectorIterator::VectorIterator"] helpviewer_keywords: ["VectorIterator Class"] -ms.assetid: d531cb42-27e0-48a6-bf5e-c265891a18ff --- -# Platform::Collections::VectorIterator Class +# `Platform::Collections::VectorIterator` class -Provides a Standard Template Library iterator for objects derived from the Windows Runtime IVector interface. +Provides a Standard Template Library iterator for objects derived from the Windows Runtime `IVector` interface. -VectorIterator is a proxy iterator that stores elements of type VectorProxy\. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +`VectorIterator` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). ## Syntax -``` +```cpp template class VectorIterator; ``` #### Parameters -*T*
-The typename of the VectorIterator template class. +*`T`*\ +The typename of the `VectorIterator` template class. ### Members @@ -31,37 +30,37 @@ The typename of the VectorIterator template class. |Name|Description| |----------|-----------------| -|`difference_type`|A pointer difference (ptrdiff_t).| -|`iterator_category`|The category of a random access iterator (::std::random_access_iterator_tag).| -|`pointer`|A pointer to an internal type, Platform::Collections::Details::VectorProxy\, that is required for the implementation of VectorIterator.| -|`reference`|A reference to an internal type, Platform::Collections::Details::VectorProxy\,, that is required for the implementation of VectorIterator.| +|`difference_type`|A pointer difference (`ptrdiff_t`).| +|`iterator_category`|The category of a random access iterator (`::std::random_access_iterator_tag`).| +|`pointer`|A pointer to an internal type, `Platform::Collections::Details::VectorProxy`, that is required for the implementation of `VectorIterator`.| +|`reference`|A reference to an internal type, `Platform::Collections::Details::VectorProxy`, that is required for the implementation of `VectorIterator`.| |`value_type`|The `T` typename.| -### Public Constructors +### Public constructors |Name|Description| |----------|-----------------| -|[VectorIterator::VectorIterator](#ctor)|Initializes a new instance of the VectorIterator class.| +|[`VectorIterator::VectorIterator`](#ctor)|Initializes a new instance of the `VectorIterator` class.| -### Public Operators +### Public operators |Name|Description| |----------|-----------------| -|[VectorIterator::operator- Operator](#operator-minus)|Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators.| -|[VectorIterator::operator-- Operator](#operator-decrement)|Decrements the current VectorIterator.| -|[VectorIterator::operator!= Operator](#operator-inequality)|Indicates whether the current VectorIterator is not equal to a specified VectorIterator.| -|[VectorIterator::operator* Operator](#operator-dereference)|Retrieves a reference to the element specified by the current VectorIterator.| -|[VectorIterator::operator\[\]](#operator-at)|Retrieves a reference to the element that is a specified displacement from the current VectorIterator.| -|[VectorIterator::operator+ Operator](#operator-plus)|Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator.| -|[VectorIterator::operator++ Operator](#operator-increment)|Increments the current VectorIterator.| -|[VectorIterator::operator+= Operator](#operator-plus-assign)|Increments the current VectorIterator by the specified displacement.| -|[VectorIterator::operator< Operator](#operator-less-than)|Indicates whether the current VectorIterator is less than a specified VectorIterator.| -|[VectorIterator::operator\<= Operator](#operator-less-than-or-equals)|Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator.| -|[VectorIterator::operator-= Operator](#operator-minus-equals)|Decrements the current VectorIterator by the specified displacement.| -|[VectorIterator::operator== Operator](#operator-equality)|Indicates whether the current VectorIterator is equal to a specified VectorIterator.| -|[VectorIterator::operator> Operator](#operator-greater-than)|Indicates whether the current VectorIterator is greater than a specified VectorIterator.| -|[VectorIterator::operator-> Operator](#operator-arrow)|Retrieves the address of the element referenced by the current VectorIterator.| -|[VectorIterator::operator>= Operator](#operator-greater-than-or-equals)|Indicates whether the current VectorIterator is greater than or equal to a specified VectorIterator.| +|[`VectorIterator::operator-` Operator](#operator-minus)|Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators.| +|[`VectorIterator::operator--` Operator](#operator-decrement)|Decrements the current VectorIterator.| +|[`VectorIterator::operator!=` Operator](#operator-inequality)|Indicates whether the current VectorIterator is not equal to a specified VectorIterator.| +|[`VectorIterator::operator*` Operator](#operator-dereference)|Retrieves a reference to the element specified by the current VectorIterator.| +|[`VectorIterator::operator[]`](#operator-at)|Retrieves a reference to the element that is a specified displacement from the current VectorIterator.| +|[`VectorIterator::operator+` Operator](#operator-plus)|Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator.| +|[`VectorIterator::operator++` Operator](#operator-increment)|Increments the current VectorIterator.| +|[`VectorIterator::operator+=` Operator](#operator-plus-assign)|Increments the current VectorIterator by the specified displacement.| +|[`VectorIterator::operator<` Operator](#operator-less-than)|Indicates whether the current VectorIterator is less than a specified VectorIterator.| +|[`VectorIterator::operator<=` Operator](#operator-less-than-or-equals)|Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator.| +|[`VectorIterator::operator-=` Operator](#operator-minus-equals)|Decrements the current VectorIterator by the specified displacement.| +|[`VectorIterator::operator==` Operator](#operator-equality)|Indicates whether the current VectorIterator is equal to a specified VectorIterator.| +|[`VectorIterator::operator>` Operator](#operator-greater-than)|Indicates whether the current VectorIterator is greater than a specified VectorIterator.| +|[`VectorIterator::operator->` Operator](#operator-arrow)|Retrieves the address of the element referenced by the current VectorIterator.| +|[`VectorIterator::operator>=` Operator](#operator-greater-than-or-equals)|Indicates whether the current VectorIterator is greater than or equal to a specified VectorIterator.| ## Inheritance Hierarchy @@ -69,84 +68,83 @@ The typename of the VectorIterator template class. ### Requirements -**Header:** collection.h +**Header:** `collection.h` -**Namespace:** Platform::Collections +**Namespace:** `Platform::Collections` -## `VectorIterator::operator->` Operator +## `VectorIterator::operator->` operator Retrieves the address of the element referenced by the current VectorIterator. ### Syntax -``` +```cpp Detail::ArrowProxy operator->() const; ``` ### Return Value -The value of the element that is referenced by the current VectorIterator. +The value of the element that is referenced by the current `VectorIterator`. The type of the return value is an unspecified internal type that is required for the implementation of this operator. -## VectorIterator::operator-- Operator +## `VectorIterator::operator--` operator Decrements the current VectorIterator. ### Syntax -``` - +```cpp VectorIterator& operator--(); VectorIterator operator--(int); ``` ### Return Value -The first syntax decrements and then returns the current VectorIterator. The second syntax returns a copy of the current VectorIterator and then decrements the current VectorIterator. +The first syntax decrements and then returns the current `VectorIterator`. The second syntax returns a copy of the current `VectorIterator` and then decrements the current `VectorIterator`. ### Remarks -The first VectorIterator syntax pre-decrements the current VectorIterator. +The first VectorIterator syntax pre-decrements the current `VectorIterator`. The second syntax post-decrements the current VectorIterator. The **`int`** type in the second syntax indicates a post-decrement operation, not an actual integer operand. -## VectorIterator::operator\* Operator +## `VectorIterator::operator*` operator -Retrieves the address of the element specified by the current VectorIterator. +Retrieves the address of the element specified by the current `VectorIterator`. ### Syntax -``` +```cpp reference operator*() const; ``` ### Return Value -The element specified by the current VectorIterator. +The element specified by the current `VectorIterator`. -## VectorIterator::operator== Operator +## `VectorIterator::operator==` operator -Indicates whether the current VectorIterator is equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is equal to a specified `VectorIterator`. ### Syntax -``` +```cpp bool operator==(const VectorIterator& other) const; ``` ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value **`true`** if the current VectorIterator is equal to *other*; otherwise, **`false`**. -## `VectorIterator::operator>` Operator +## `VectorIterator::operator>` operator -Indicates whether the current VectorIterator is greater than a specified VectorIterator. +Indicates whether the current `VectorIterator` is greater than a specified `VectorIterator`. ### Syntax @@ -156,16 +154,16 @@ bool operator>(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is greater than *other*; otherwise, **`false`**. +**`true`** if the current VectorIterator is greater than *`other`*; otherwise, **`false`**. -## `VectorIterator::operator>=` Operator +## `VectorIterator::operator>=` operator -Indicates whether the current VectorIterator is greater than or equal to the specified VectorIterator. +Indicates whether the current VectorIterator is greater than or equal to the specified `VectorIterator`. ### Syntax @@ -175,56 +173,56 @@ bool operator>=(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is greater than or equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is greater than or equal to *`other`*; otherwise, **`false`**. -## VectorIterator::operator++ Operator +## `VectorIterator::operator++` operator -Increments the current VectorIterator. +Increments the current `VectorIterator`. ### Syntax -``` +```cpp VectorIterator& operator++(); VectorIterator operator++(int); ``` ### Return Value -The first syntax increments and then returns the current VectorIterator. The second syntax returns a copy of the current VectorIterator and then increments the current VectorIterator. +The first syntax increments and then returns the current `VectorIterator`. The second syntax returns a copy of the current `VectorIterator` and then increments the current `VectorIterator`. ### Remarks -The first VectorIterator syntax pre-increments the current VectorIterator. +The first `VectorIterator` syntax pre-increments the current `VectorIterator`. -The second syntax post-increments the current VectorIterator. The **`int`** type in the second syntax indicates a post-increment operation, not an actual integer operand. +The second syntax post-increments the current `VectorIterator`. The **`int`** type in the second syntax indicates a post-increment operation, not an actual integer operand. -## VectorIterator::operator!= Operator +## `VectorIterator::operator!=` operator -Indicates whether the current VectorIterator is not equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is not equal to a specified `VectorIterator`. ### Syntax -``` +```cpp bool operator!=(const VectorIterator& other) const; ``` ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is not equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is not equal to *other*; otherwise, **`false`**. -## `VectorIterator::operator<` Operator +## `VectorIterator::operator<` operator -Indicates whether the current VectorIterator is less than a specified VectorIterator. +Indicates whether the current `VectorIterator` is less than a specified `VectorIterator`. ### Syntax @@ -234,16 +232,16 @@ bool operator<(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is less than *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is less than *`other`*; otherwise, **`false`**. -## `VectorIterator::operator<=` Operator +## `VectorIterator::operator<=` operator -Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is less than or equal to a specified `VectorIterator`. ### Syntax @@ -253,21 +251,20 @@ bool operator<=(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is less than or equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is less than or equal to *`other`*; otherwise, **`false`**. -## VectorIterator::operator- Operator +## `VectorIterator::operator-` operator Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators. ### Syntax -``` - +```cpp VectorIterator operator-(difference_type n) const; difference_type operator-(const VectorIterator& other) const; @@ -275,43 +272,42 @@ difference_type operator-(const VectorIterator& other) const; ### Parameters -*n*
+*`n`*\ A number of elements. -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -The first operator syntax returns a VectorIterator object that is `n` elements less than the current VectorIterator. The second operator syntax returns the number of elements between the current and the `other` VectorIterator. +The first operator syntax returns a `VectorIterator` object that is `n` elements less than the current `VectorIterator`. The second operator syntax returns the number of elements between the current and the `other` `VectorIterator`. -## VectorIterator::operator+= Operator +## `VectorIterator::operator+=` operator -Increments the current VectorIterator by the specified displacement. +Increments the current `VectorIterator` by the specified displacement. ### Syntax -``` +```cpp VectorIterator& operator+=(difference_type n); ``` ### Parameters -*n*
+*`n`*\ A integer displacement. ### Return Value -The updated VectorIterator. +The updated `VectorIterator`. -## VectorIterator::operator+ Operator +## `VectorIterator::operator+` operator -Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator. +Returns a `VectorIterator` that references the element at the specified displacement from the specified `VectorIterator`. ### Syntax -``` - +```cpp VectorIterator operator+(difference_type n); template @@ -322,70 +318,70 @@ inline VectorIterator operator+( ### Parameters -*T*
-In the second syntax, the typename of the VectorIterator. +*`T`*\ +In the second syntax, the typename of the `VectorIterator`. -*n*
+*`n`*\ An integer displacement. -*i*
-In the second syntax, a VectorIterator. +*`i`*\ +In the second syntax, a `VectorIterator`. ### Return Value -In the first syntax, a VectorIterator that references the element at the specified displacement from the current VectorIterator. +In the first syntax, a `VectorIterator` that references the element at the specified displacement from the current `VectorIterator`. -In the second syntax, a VectorIterator that references the element at the specified displacement from the beginning of parameter `i`. +In the second syntax, a `VectorIterator` that references the element at the specified displacement from the beginning of parameter `i`. ### Remarks The first syntax example -## VectorIterator::operator-= Operator +## `VectorIterator::operator-=` operator -Decrements the current VectorIterator by the specified displacement. +Decrements the current `VectorIterator` by the specified displacement. ### Syntax -``` +```cpp VectorIterator& operator-=(difference_type n); ``` ### Parameters -*n*
+*`n`*\ An integer displacement. ### Return Value -The updated VectorIterator. +The updated `VectorIterator`. -## VectorIterator::operator\[\] +## `VectorIterator::operator[]` operator -Retrieves a reference to the element that is a specified displacement from the current VectorIterator. +Retrieves a reference to the element that is a specified displacement from the current `VectorIterator`. ### Syntax -``` +```cpp reference operator[](difference_type n) const; ``` ### Parameters -*n*
+*`n`*\ An integer displacement. ### Return Value -The element that is displaced by `n` elements from the current VectorIterator. +The element that is displaced by `n` elements from the current `VectorIterator`. -## VectorIterator::VectorIterator Constructor +## `VectorIterator::VectorIterator` constructor -Initializes a new instance of the VectorIterator class. +Initializes a new instance of the `VectorIterator` class. ### Syntax -``` +```cpp VectorIterator(); explicit VectorIterator( @@ -394,12 +390,12 @@ explicit VectorIterator( ### Parameters -*v*
-An IVector\ object. +*`v`*\ +An `IVector` object. ### Remarks -The first syntax example is the default constructor. The second syntax example is an explicit constructor that is used to construct a VectorIterator from an IVector\ object. +The first syntax example is the default constructor. The second syntax example is an explicit constructor that is used to construct a `VectorIterator` from an `IVector` object. ## See also diff --git a/docs/cppcx/platform-collections-vectorview-class.md b/docs/cppcx/platform-collections-vectorview-class.md index 9bbc63a322..5fe72ec39f 100644 --- a/docs/cppcx/platform-collections-vectorview-class.md +++ b/docs/cppcx/platform-collections-vectorview-class.md @@ -65,7 +65,6 @@ Returns an iterator that specifies the first element in the VectorView. ### Syntax ``` - virtual Windows::Foundation::Collections::IIterator^ First(); ``` @@ -85,7 +84,6 @@ Retrieves the element of the current VectorView that is indicated by the specifi ### Syntax ``` - T GetAt( UInt32 index ); @@ -107,7 +105,6 @@ Retrieves a sequence of items from the current VectorView, starting at the speci ### Syntax ``` - virtual unsigned int GetMany( unsigned int startIndex, ::Platform::WriteOnlyArray^ dest @@ -133,7 +130,6 @@ Searches for the specified item in the current VectorView, and if found, returns ### Syntax ``` - virtual bool IndexOf( T value, unsigned int* index @@ -161,7 +157,6 @@ Returns the number of elements in the current VectorView object. ### Syntax ``` - virtual property unsigned int Size; ``` diff --git a/docs/cppcx/platform-collections-vectorviewiterator-class.md b/docs/cppcx/platform-collections-vectorviewiterator-class.md index 9e58635be0..9abe562999 100644 --- a/docs/cppcx/platform-collections-vectorviewiterator-class.md +++ b/docs/cppcx/platform-collections-vectorviewiterator-class.md @@ -150,7 +150,6 @@ Indicates whether the current VectorViewIterator is greater than a specified Vec ### Syntax ``` - bool operator>(const VectorViewIterator& other) const; ``` @@ -170,7 +169,6 @@ Indicates whether the current `VectorViewIterator` is greater than or equal to t ### Syntax ``` - bool operator>=(const VectorViewIterator& other) const; ``` @@ -190,7 +188,6 @@ Increments the current VectorViewIterator. ### Syntax ``` - VectorViewIterator& operator++(); VectorViewIterator operator++(int); ``` @@ -250,7 +247,6 @@ Indicates whether the current `VectorIterator` is less than or equal to a specif ### Syntax ``` - bool operator<=(const VectorViewIterator& other) const; ``` @@ -270,7 +266,6 @@ Subtracts either a specified number of elements from the current iterator yieldi ### Syntax ``` - VectorViewIterator operator-(difference_type n) const; difference_type operator-(const VectorViewIterator& other) const; @@ -314,7 +309,6 @@ Returns a VectorViewIterator that references the element at the specified displa ### Syntax ``` - VectorViewIterator operator+(difference_type n) const; template @@ -385,7 +379,6 @@ Initializes a new instance of the VectorViewIterator class. ### Syntax ``` - VectorViewIterator(); explicit VectorViewIterator( diff --git a/docs/cppcx/platform-comexception-class.md b/docs/cppcx/platform-comexception-class.md index 5c8363381c..e76f69daed 100644 --- a/docs/cppcx/platform-comexception-class.md +++ b/docs/cppcx/platform-comexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::COMException Class" title: "Platform::COMException Class" +description: "Learn more about: Platform::COMException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::COMException", "VCCORLIB/Platform::COMException::HResult", "VCCORLIB/Platform::COMException::Message"] helpviewer_keywords: ["Platform::COMException Class"] -ms.assetid: 44fda4e5-574f-4d12-ab5f-4ff3f277448d --- # Platform::COMException Class @@ -14,7 +13,7 @@ Represents COM errors that occur during application execution. COMException is t ## Syntax ```cpp -public ref class COMException : Exception, IException, IPrintable, IEquatable +public ref class COMException : Exception, IException, IPrintable, IEquatable ``` ### Members @@ -79,12 +78,12 @@ Intializes a new instance of the COMException class. ### Syntax ```cpp -COMException( int hresult ) +COMException(int hresult); ``` ### Parameters -*hresult*
+*hresult*\ The error HRESULT that is represented by the exception. ## COMException::HResult Property @@ -95,7 +94,7 @@ The HRESULT that corresponds to the exception. ```cpp public: - property int HResult { int get();} + property int HResult { int get(); } ``` ## Property Value @@ -113,7 +112,8 @@ Message that describes the exception. ### Syntax ```cpp -public:property String^ Message { String^ get();} +public: + property String^ Message { String^ get(); } ``` ### Property Value diff --git a/docs/cppcx/platform-details-heapallocationtrackinglevel-enumeration.md b/docs/cppcx/platform-details-heapallocationtrackinglevel-enumeration.md index 095d32d623..8e3e645bf9 100644 --- a/docs/cppcx/platform-details-heapallocationtrackinglevel-enumeration.md +++ b/docs/cppcx/platform-details-heapallocationtrackinglevel-enumeration.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Details::HeapAllocationTrackingLevel Enumeration" title: "Platform::Details::HeapAllocationTrackingLevel Enumeration" -ms.date: "12/30/2016" +description: "Learn more about: Platform::Details::HeapAllocationTrackingLevel Enumeration" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Details::HeapAllocationTrackingLevel"] helpviewer_keywords: ["Platform::Details::HeapAllocationTrackingLevel Enumeration"] -ms.assetid: dc341bc0-b47b-4eb2-9445-fbaf788e7b1a --- # Platform::Details::HeapAllocationTrackingLevel Enumeration @@ -14,7 +13,7 @@ This enumeration is intended for internal use only, and is not intended to be us ## Syntax ```cpp -enumm class HeapAllocationTrackingLevel; +enum class HeapAllocationTrackingLevel; ``` ### Remarks diff --git a/docs/cppcx/platform-disconnectedexception-class.md b/docs/cppcx/platform-disconnectedexception-class.md index 332d47be88..5721f44c9a 100644 --- a/docs/cppcx/platform-disconnectedexception-class.md +++ b/docs/cppcx/platform-disconnectedexception-class.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Platform::DisconnectedException Class" title: "Platform::DisconnectedException Class" +description: "Learn more about: Platform::DisconnectedException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::DisconnectedException", "VCCORLIB/Platform::DisconnectedException::DisconnectedException"] helpviewer_keywords: ["Platform::DisconnectedException"] -ms.assetid: c25e0d64-5bff-4c21-88e5-c4ec2776fa7f --- # Platform::DisconnectedException Class -Thrown when a COM proxy object attempts to reference a COM server that no longer exists +Thrown when a COM proxy object attempts to reference a COM server that no longer exists. ## Syntax -``` -public ref class DisconnectedException : COMException, IException, IPrintable, IEquatable +```cpp +public ref class DisconnectedException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-exception-class.md b/docs/cppcx/platform-exception-class.md index 69631f3d54..4eb7e70d3d 100644 --- a/docs/cppcx/platform-exception-class.md +++ b/docs/cppcx/platform-exception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Exception Class" title: "Platform::Exception Class" +description: "Learn more about: Platform::Exception Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Exception::Exception", "VCCORLIB/Platform::Exception::CreateException", "VCCORLIB/Platform::Exception::HResult", "VCCORLIB/Platform::Exception::Message"] helpviewer_keywords: ["Platform::Exception Class"] -ms.assetid: ca1d5a67-3a5a-48fe-8099-f9c38a2d2dce --- # Platform::Exception Class @@ -14,7 +13,7 @@ Represents errors that occur during application execution. Custom exception clas ## Syntax ```cpp -public ref class Exception : Object, IException, IPrintable, IEquatable +public ref class Exception : Object, IException, IPrintable, IEquatable ``` ### Members @@ -31,7 +30,7 @@ The `Exception` class also has the following kinds of members. ### Methods -The `Exception` class inherits the `Equals()`, `Finalize()`,`GetHashCode()`,`GetType()`,`MemberwiseClose()`, and `ToString()` methods from the [Platform::Object Class](../cppcx/platform-object-class.md). The `Exception` class also has the following method. +The `Exception` class inherits the `Equals()`, `Finalize()`, `GetHashCode()`, `GetType()`, `MemberwiseClose()`, and `ToString()` methods from the [Platform::Object Class](../cppcx/platform-object-class.md). The `Exception` class also has the following method. |Member|Description| |------------|-----------------| @@ -69,10 +68,10 @@ Exception^ CreateException(int32 hr, Platform::String^ message); ### Parameters -*hr*
+*hr*\ An HRESULT value that you typically get from a call to a COM method. If the value is 0, which is equal to S_OK, this method throws [Platform::InvalidArgumentException](../cppcx/platform-invalidargumentexception-class.md) because COM methods that succeed should not throw exceptions. -*message*
+*message*\ A string that describes the error. ### Return Value @@ -98,10 +97,10 @@ Exception(int32 hresult, ::Platform::String^ message); ### Parameters -*hresult*
+*hresult*\ The error HRESULT that is represented by the exception. -*message*
+*message*\ A user-specified message, such as prescriptive text, that is associated with the exception. In general you should prefer the second overload in order to provide a descriptive message that is as specific as possible about how and why the error has occurred. ## Exception::HResult Property @@ -130,7 +129,8 @@ Message that describes the error. ### Syntax ```cpp -public:property String^ Message; +public: + property String^ Message; ``` ### Property Value diff --git a/docs/cppcx/platform-failureexception-class.md b/docs/cppcx/platform-failureexception-class.md index 02f7ca1cfb..24268a74b3 100644 --- a/docs/cppcx/platform-failureexception-class.md +++ b/docs/cppcx/platform-failureexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::FailureException Class" title: "Platform::FailureException Class" +description: "Learn more about: Platform::FailureException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::FailureException::FailureException", "VCCORLIB/Platform::FailureException"] helpviewer_keywords: ["Platform::FailureException"] -ms.assetid: 1729cd07-bfc2-448e-9db5-185d5cbf5b81 --- # Platform::FailureException Class @@ -14,7 +13,7 @@ Thrown when the operation has failed. It is the equivalent of the E_FAIL HRESULT ## Syntax ```cpp -public ref class FailureException : COMException, IException, IPrintable, IEquatable +public ref class FailureException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-guid-value-class.md b/docs/cppcx/platform-guid-value-class.md index 952645712c..825700de85 100644 --- a/docs/cppcx/platform-guid-value-class.md +++ b/docs/cppcx/platform-guid-value-class.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Platform::Guid value class" title: "Platform::Guid value class" +description: "Learn more about: Platform::Guid value class" ms.date: "01/15/2019" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Guid"] helpviewer_keywords: ["Platform::Guid Struct"] -ms.assetid: 25c0bfb2-7f93-44d8-bdf4-ef4fbac3424a --- # Platform::Guid value class -Represents a [GUID](/windows/win32/api/guiddef/ns-guiddef-guid type in the Windows Runtime type system. +Represents a [GUID](/windows/win32/api/guiddef/ns-guiddef-guid) type in the Windows Runtime type system. ## Syntax @@ -74,43 +73,43 @@ Guid( ### Parameters -*a*
+*a*\ The first 4 bytes of the `GUID`. -*b*
+*b*\ The next 2 bytes of the `GUID`. -*c*
+*c*\ The next 2 bytes of the `GUID`. -*d*
+*d*\ The next byte of the `GUID`. -*e*
+*e*\ The next byte of the `GUID`. -*f*
+*f*\ The next byte of the `GUID`. -*g*
+*g*\ The next byte of the `GUID`. -*h*
+*h*\ The next byte of the `GUID`. -*i*
+*i*\ The next byte of the `GUID`. -*j*
+*j*\ The next byte of the `GUID`. -*k*
+*k*\ The next byte of the `GUID`. -*m*
+*m*\ A `GUID` in the form a [GUID structure](/windows/win32/api/guiddef/ns-guiddef-guid). -*n*
+*n*\ The remaining 8 bytes of the `GUID`. ## Guid::operator== Operator @@ -125,10 +124,10 @@ static bool Platform::Guid::operator==(Platform::Guid guid1, Platform::Guid guid ### Parameters -*guid1*
+*guid1*\ The first `Platform::Guid` to compare. -*guid2*
+*guid2*\ The second `Platform::Guid` to compare. ### Return Value @@ -152,10 +151,10 @@ static bool Platform::Guid::operator!=(Platform::Guid guid1, Platform::Guid guid ### Parameters -*guid1*
+*guid1*\ The first `Platform::Guid` to compare. -*guid2*
+*guid2*\ The second `Platform::Guid` to compare. ### Return Value @@ -174,10 +173,10 @@ static bool Platform::Guid::operator<(Platform::Guid guid1, Platform::Guid guid2 ### Parameters -*guid1*
+*guid1*\ The first `Platform::Guid` to compare. -*guid2*
+*guid2*\ The second `Platform::Guid` to compare. ### Return Value diff --git a/docs/cppcx/platform-intptr-value-class.md b/docs/cppcx/platform-intptr-value-class.md index ffadf9627d..b08b50209b 100644 --- a/docs/cppcx/platform-intptr-value-class.md +++ b/docs/cppcx/platform-intptr-value-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::IntPtr value class" title: "Platform::IntPtr value class" +description: "Learn more about: Platform::IntPtr value class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/PlatformIntPtr::IntPtr", "VCCORLIB/PlatformIntPtr::op_explicit Operator", "VCCORLIB/PlatformIntPtr::ToInt32"] helpviewer_keywords: ["Platform::IntPtr Struct"] -ms.assetid: 6c0326e8-edfd-4e53-a963-240b845dcde8 --- # Platform::IntPtr value class @@ -37,7 +36,7 @@ IntPtr has the following members: **Metadata:** platform.winmd -## IntPtr::IntPtr Constructor +## IntPtr::IntPtr Constructor Initializes a new instance of an IntPtr with the specified value. @@ -52,7 +51,7 @@ IntPtr( __int64 handle-or-pointer ); IntPtr( void* value ); IntPtr( int 32-b *value*
A 64-bit handle or pointer, or a pointer to a 64-bit value, or a 32-bit value that can be converted to a 64-bit value. -## IntPtr::op_explicit Operator +## IntPtr::op_explicit Operator Converts the specified parameter to an IntPtr or a pointer to an IntPtr value. @@ -68,7 +67,7 @@ static IntPtr::operator IntPtr( void* value1); static IntPtr::operator IntPtr( A pointer to a handle or IntPtr. *value2*
-An 32-bit integer that can be converted to an IntPtr. +A 32-bit integer that can be converted to an IntPtr. *value3*
An IntPtr. @@ -77,7 +76,7 @@ An IntPtr. The first and second operators return an IntPtr. The third operator returns a pointer to the value represented by the current IntPtr. -## IntPtr::ToInt32 Method +## IntPtr::ToInt32 Method Converts the current IntPtr value to a 32-bit integer. diff --git a/docs/cppcx/platform-invalidargumentexception-class.md b/docs/cppcx/platform-invalidargumentexception-class.md index 120bdd9d5c..040d608c66 100644 --- a/docs/cppcx/platform-invalidargumentexception-class.md +++ b/docs/cppcx/platform-invalidargumentexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::InvalidArgumentException Class" title: "Platform::InvalidArgumentException Class" +description: "Learn more about: Platform::InvalidArgumentException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::InvalidArgumentException", "VCCORLIB/Platform::InvalidArgumentException::InvalidArgumentException"] helpviewer_keywords: ["Platform::InvalidArgumentException"] -ms.assetid: 1a8d860b-3bcb-41a9-9346-6610616a0b46 --- # Platform::InvalidArgumentException Class @@ -14,7 +13,7 @@ Thrown when one of the arguments provided to a method is not valid. ## Syntax ```cpp -public ref class InvalidArgumentException : COMException, IException, IPrintable, IEquatable +public ref class InvalidArgumentException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-invalidcastexception-class.md b/docs/cppcx/platform-invalidcastexception-class.md index 4f9b3c4ba7..9e664b598b 100644 --- a/docs/cppcx/platform-invalidcastexception-class.md +++ b/docs/cppcx/platform-invalidcastexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::InvalidCastException Class" title: "Platform::InvalidCastException Class" +description: "Learn more about: Platform::InvalidCastException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::InvalidCastException::InvalidCastException", "VCCORLIB/Platform::InvalidCastException"] helpviewer_keywords: ["Platform::InvalidCastException"] -ms.assetid: 0215131d-1251-4913-9561-824410e045b6 --- # Platform::InvalidCastException Class @@ -14,7 +13,7 @@ Thrown when a cast or explicit conversion is invalid. ## Syntax ```cpp -public ref class InvalidCastException : COMException, IException, IPrintable, IEquatable +public ref class InvalidCastException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-metadata-runtimeclassname.md b/docs/cppcx/platform-metadata-runtimeclassname.md index d40541dd80..e7e5d3a056 100644 --- a/docs/cppcx/platform-metadata-runtimeclassname.md +++ b/docs/cppcx/platform-metadata-runtimeclassname.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Platform::Metadata::RuntimeClassName" title: "Platform::Metadata::RuntimeClassName" +description: "Learn more about: Platform::Metadata::RuntimeClassName" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Metadata::RuntimeClassName"] helpviewer_keywords: ["RuntimeClassName", "Platform::Metadata::RuntimeClassName"] -ms.assetid: fdef8f85-ab94-4edd-ba50-ee0da9358ff6 --- # Platform::Metadata::RuntimeClassName -When applied to a class definition, ensures that a private class returns a valid name from the GetRuntimeClassName function.. +When applied to a class definition, ensures that a private class returns a valid name from the GetRuntimeClassName function. ## Syntax diff --git a/docs/cppcx/platform-notimplementedexception-class.md b/docs/cppcx/platform-notimplementedexception-class.md index 55e18d0b57..94f1c289d8 100644 --- a/docs/cppcx/platform-notimplementedexception-class.md +++ b/docs/cppcx/platform-notimplementedexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::NotImplementedException Class" title: "Platform::NotImplementedException Class" +description: "Learn more about: Platform::NotImplementedException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::NotImplementedException", "VCCORLIB/Platform::NotImplementedException::NotImplementedException"] helpviewer_keywords: ["Platform::NotImplementedException"] -ms.assetid: 6da26cc2-dde8-4aea-aa85-67aac55cf97b --- # Platform::NotImplementedException Class @@ -14,7 +13,7 @@ Thrown when an interface member is not been implemented in a derived type. ## Syntax ```cpp -public ref class NotImplementedException : COMException, IException, IPrintable, IEquatable +public ref class NotImplementedException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-nullreferenceexception-class.md b/docs/cppcx/platform-nullreferenceexception-class.md index c5924402c2..4fd3153854 100644 --- a/docs/cppcx/platform-nullreferenceexception-class.md +++ b/docs/cppcx/platform-nullreferenceexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::NullReferenceException Class" title: "Platform::NullReferenceException Class" +description: "Learn more about: Platform::NullReferenceException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::NullReferenceException", "VCCORLIB/Platform::NullReferenceException::NullReferenceException"] helpviewer_keywords: ["Platform::NullReferenceException"] -ms.assetid: be202577-d898-4716-83cd-e3556fe8a241 --- # Platform::NullReferenceException Class @@ -14,7 +13,7 @@ Thrown when there is an attempt to dereference a null object reference. ## Syntax ```cpp -public ref class NullReferenceException : COMException, IException, IPrintable, IEquatable +public ref class NullReferenceException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-object-class.md b/docs/cppcx/platform-object-class.md index 3c0b40457d..3964399163 100644 --- a/docs/cppcx/platform-object-class.md +++ b/docs/cppcx/platform-object-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Object Class" title: "Platform::Object Class" +description: "Learn more about: Platform::Object Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Object::Object", "VCCORLIB/Platform::Object::Equals", "VCCORLIB/Platform::Object::GetHashCode", "VCCORLIB/Platform::Object::ReferenceEquals", "VCCORLIB/Platform::ToString", "VCCORLIB/Platform::GetType"] helpviewer_keywords: ["Object class"] -ms.assetid: 709e84a8-0bff-471b-bc14-63e424080b5a --- # Platform::Object Class @@ -104,7 +103,7 @@ A [Platform::Type](../cppcx/platform-type-class.md) object that describes the ru The static [Type::GetTypeCode](../cppcx/platform-type-class.md#gettypecode) can be used to get a [Platform::TypeCode Enumeration](../cppcx/platform-typecode-enumeration.md) value that represents the current type. This is mostly useful for built-in types. The type code for any ref class besides [Platform::String](../cppcx/platform-string-class.md) is Object (1). -The [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.interop.typename) class is used in the Windows APIs as a language-independent way of passing type information between Windows components and apps. The T[Platform::Type Class](../cppcx/platform-type-class.md) has operators for converting between `Type` and `TypeName`. +The [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.interop.typename) class is used in the Windows APIs as a language-independent way of passing type information between Windows components and apps. The [Platform::Type Class](../cppcx/platform-type-class.md) has operators for converting between `Type` and `TypeName`. Use the [typeid](../extensions/typeid-cpp-component-extensions.md) operator to return a `Platform::Type` object for a class name, for example when navigating between XAML pages: @@ -166,13 +165,13 @@ public: Tree(){} virtual Platform::String^ ToString() override { - return "I’m a Tree"; + return "I'm a Tree"; }; }; ``` ## See also -[Platform Namespace](platform-namespace-c-cx.md)
-[Platform::Type Class](platform-type-class.md)
+[Platform Namespace](platform-namespace-c-cx.md)\ +[Platform::Type Class](platform-type-class.md)\ [Type System](type-system-c-cx.md) diff --git a/docs/cppcx/platform-objectdisposedexception-class.md b/docs/cppcx/platform-objectdisposedexception-class.md index 36f7004267..0d9a905551 100644 --- a/docs/cppcx/platform-objectdisposedexception-class.md +++ b/docs/cppcx/platform-objectdisposedexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::ObjectDisposedException Class" title: "Platform::ObjectDisposedException Class" +description: "Learn more about: Platform::ObjectDisposedException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::ObjectDisposedException", "VCCORLIB/Platform::ObjectDisposedException::ObjectDisposedException"] helpviewer_keywords: ["Platform::ObjectDisposedException"] -ms.assetid: 68506fe4-d09c-4407-999f-1e3edb261d41 --- # Platform::ObjectDisposedException Class @@ -14,7 +13,7 @@ Thrown when an operation is performed on a disposed object. ## Syntax ```cpp -public ref class ObjectDisposedException : COMException, IException, IPrintable, IEquatable +public ref class ObjectDisposedException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-operationcanceledexception-class.md b/docs/cppcx/platform-operationcanceledexception-class.md index 0ada6f4496..99ce0bc558 100644 --- a/docs/cppcx/platform-operationcanceledexception-class.md +++ b/docs/cppcx/platform-operationcanceledexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::OperationCanceledException Class" title: "Platform::OperationCanceledException Class" +description: "Learn more about: Platform::OperationCanceledException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::OperationCanceledException::OperationCanceledException", "VCCORLIB/Platform::OperationCanceledException"] helpviewer_keywords: ["Platform::OperationCanceledException"] -ms.assetid: 5351bc20-5408-423a-8169-f09acc8a3fbb --- # Platform::OperationCanceledException Class @@ -14,7 +13,7 @@ Thrown when an operation is aborted. ## Syntax ```cpp -public ref class OperationCanceledException : COMException, IException, IPrintable, IEquatable +public ref class OperationCanceledException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-outofboundsexception-class.md b/docs/cppcx/platform-outofboundsexception-class.md index d8a878c891..2bca3dbbac 100644 --- a/docs/cppcx/platform-outofboundsexception-class.md +++ b/docs/cppcx/platform-outofboundsexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::OutOfBoundsException Class" title: "Platform::OutOfBoundsException Class" +description: "Learn more about: Platform::OutOfBoundsException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::OutOfBoundsException", "VCCORLIB/Platform::OutOfBoundsException::OutOfBoundsException"] helpviewer_keywords: ["Platform::OutOfBoundsException"] -ms.assetid: 96f8bf75-1207-4049-964b-7771822cadf3 --- # Platform::OutOfBoundsException Class @@ -14,7 +13,7 @@ Thrown when an operation attempts to access data outside the valid range. ## Syntax ```cpp -public ref class OutOfBoundsException : COMException, IException, IPrintable, IEquatable +public ref class OutOfBoundsException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-outofmemoryexception-class.md b/docs/cppcx/platform-outofmemoryexception-class.md index bf36a9f791..486396cf6a 100644 --- a/docs/cppcx/platform-outofmemoryexception-class.md +++ b/docs/cppcx/platform-outofmemoryexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::OutOfMemoryException Class" title: "Platform::OutOfMemoryException Class" +description: "Learn more about: Platform::OutOfMemoryException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::OutOfMemoryException", "VCCORLIB/Platform::OutOfMemoryException::OutOfMemoryException"] helpviewer_keywords: ["Platform::OutOfMemoryException"] -ms.assetid: 49c19f6b-f66c-4448-b861-91dcbf32de2c --- # Platform::OutOfMemoryException Class @@ -14,7 +13,7 @@ Thrown when there's insufficient memory to complete the operation. ## Syntax ```cpp -public ref class OutOfMemoryException : COMException, IException, IPrintable, IEquatable +public ref class OutOfMemoryException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/platform-string-class.md b/docs/cppcx/platform-string-class.md index 340750259b..aeaff32abf 100644 --- a/docs/cppcx/platform-string-class.md +++ b/docs/cppcx/platform-string-class.md @@ -22,7 +22,7 @@ public ref class String sealed : Object, ## Iterators -Two iterator functions, which are not members of the String class, can be used with the `std::for_each` template function to enumerate the characters in a String object. +Two iterator functions, which are not members of the String class, can be used with the `std::for_each` function template to enumerate the characters in a String object. |Member|Description| |------------|-----------------| diff --git a/docs/cppcx/platform-type-class.md b/docs/cppcx/platform-type-class.md index df4a4ca7ce..b63ccf0366 100644 --- a/docs/cppcx/platform-type-class.md +++ b/docs/cppcx/platform-type-class.md @@ -100,7 +100,7 @@ The equivalent of the GetTypeCode() member method is the **`typeid`** property. ## Type::ToString Method -Retrieves a the name of the type. +Retrieves the name of the type. ### Syntax diff --git a/docs/cppcx/platform-writeonlyarray-class.md b/docs/cppcx/platform-writeonlyarray-class.md index 744ff8e94d..797264d80b 100644 --- a/docs/cppcx/platform-writeonlyarray-class.md +++ b/docs/cppcx/platform-writeonlyarray-class.md @@ -30,7 +30,7 @@ These methods have internal accessibility—that is, they are only accessible wi |[WriteOnlyArray::begin](#begin)|An iterator that points to the first element of the array.| |[WriteOnlyArray::Data](#data)|A pointer to the data buffer.| |[WriteOnlyArray::end](#end)|An iterator that points to one past the last element in the array.| -|[WriteOnlyArray::FastPass](#fastpass)|Indicates whether the array can use the FastPass mechanism, which is an optimization transparently performed by the system. Don’t use this in your code| +|[WriteOnlyArray::FastPass](#fastpass)|Indicates whether the array can use the FastPass mechanism, which is an optimization transparently performed by the system. Don't use this in your code| |[WriteOnlyArray::Length](#length)|Returns the number of elements in the array.| |[WriteOnlyArray::set](#set)|Sets the specified element to the specified value.| diff --git a/docs/cppcx/platform-wrongthreadexception-class.md b/docs/cppcx/platform-wrongthreadexception-class.md index 79320770d5..33c5039914 100644 --- a/docs/cppcx/platform-wrongthreadexception-class.md +++ b/docs/cppcx/platform-wrongthreadexception-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::WrongThreadException Class" title: "Platform::WrongThreadException Class" +description: "Learn more about: Platform::WrongThreadException Class" ms.date: "12/30/2016" ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::WrongThreadException", "VCCORLIB/Platform::WrongThreadException::WrongThreadException"] helpviewer_keywords: ["Platform::WrongThreadException"] -ms.assetid: c193f97e-0392-4535-a4c4-0711e4e4a836 --- # Platform::WrongThreadException Class @@ -14,7 +13,7 @@ Thrown when a thread calls by way of an interface pointer for a proxy object tha ## Syntax ```cpp -public ref class WrongThreadException : COMException, IException, IPrintable, IEquatable +public ref class WrongThreadException : COMException, IException, IPrintable, IEquatable ``` ### Remarks diff --git a/docs/cppcx/quick-reference-c-cx.md b/docs/cppcx/quick-reference-c-cx.md index 1f6b75ac08..b62ceb8531 100644 --- a/docs/cppcx/quick-reference-c-cx.md +++ b/docs/cppcx/quick-reference-c-cx.md @@ -1,46 +1,46 @@ --- description: "Learn more about: Quick Reference (C++/CX)" title: "Quick Reference (C++/CX)" -ms.date: "12/30/2016" +ms.date: 05/31/2022 ms.assetid: ba457195-26e5-43aa-b99d-24a871e550f4 --- # Quick Reference (C++/CX) -The Windows Runtime supports Universal Windows Platform (UWP) apps that execute only in a trustworthy operating system environment, use authorized functions, data types, and devices, and are distributed through the Microsoft Store. The C++/CX simplify the writing of apps for the Windows Runtime. This article is a quick reference; for more complete documentation, see [Type System](../cppcx/type-system-c-cx.md). +The Windows Runtime supports Universal Windows Platform (UWP) apps. These apps execute only in a trustworthy operating system environment, use authorized functions, data types, and devices, and are distributed through the Microsoft Store. The C++/CX simplify the writing of apps for the Windows Runtime. This article is a quick reference; for more complete documentation, see [Type system](../cppcx/type-system-c-cx.md). -When you build on the command line, use the **/ZW** compiler option to build a UWP app or Windows Runtime component. To access Windows Runtime declarations, which are defined in the Windows Runtime metadata (.winmd) files, specify the `#using` directive or the **/FU** compiler option. When you create a project for a UWP app, Visual Studio by default sets these options and adds references to all Windows Runtime libraries. +When you build on the command line, use the **`/ZW`** compiler option to build a UWP app or Windows Runtime component. To access Windows Runtime declarations, which are defined in the Windows Runtime metadata (.winmd) files, specify the `#using` directive or the **`/FU`** compiler option. When you create a project for a UWP app, Visual Studio by default sets these options and adds references to all Windows Runtime libraries. ## Quick reference -|Concept|Standard C++|C++/CX|Remarks| -|-------------|--------------------|------------------------------------------------------------------|-------------| -|Fundamental types|C++ fundamental types.|C++/CX fundamental types that implement fundamental types that are defined in the Windows Runtime.|The `default` namespace contains C++/CX built-in, fundamental types. The compiler implicitly maps C++/CX fundamental types to standard C++ types.

The `Platform` family of namespaces contains types that implement fundamental Windows Runtime types.| -||**`bool`**|**`bool`**|An 8-bit Boolean value.| -||**`wchar_t`**, **`char16_t`**|`char16`|A 16-bit nonnumeric value that represents a Unicode (UTF-16) code point.| -||**`short`**

**`unsigned short`**|`int16`

`uint16`|A 16-bit signed integer.

A 16-bit unsigned integer.| -||**`int`**

**`unsigned int`**|**`int`**

`uint32`|A 32-bit signed integer.

A 32-bit unsigned integer.| -||**`long long`** -or- **`__int64`**

**`unsigned long long`**|`int64`

`uint64`|A 64-bit signed integer.

A 64-bit unsigned integer.| -||**`float`**, **`double`**|`float32, float64`|A 32-bit or 64-bit IEEE 754 floating-point number.| -||**`enum`**|**`enum class`**

-or-

**`enum struct`**|A 32-bit enumeration.| -||(Does not apply)|`Platform::Guid`|A 128-bit nonnumeric value (a GUID) in the `Platform` namespace.| -||`std::time_get`|`Windows::Foundation::DateTime`|A date-time structure.| -||(Does not apply)|`Windows::Foundation::TimeSpan`|A timespan structure.| -||(Does not apply)|`Platform::Object^`|The reference-counted base object in the C++ view of the Windows Runtime type system.| -||`std::wstring`

`L"..."`|`Platform::String^`|`Platform::String^` is a reference-counted, immutable, sequence of Unicode characters that represent text.| -|Pointer|Pointer to object (`*`):

`std::shared_ptr`|Handle-to-object (`^`, pronounced "hat"):

*T^ identifier*|All Windows Runtime classes are declared by using the handle-to-object modifier. Members of the object are accessed by using the arrow (`->`) class-member-access operator.

The hat modifier means "pointer to a Windows Runtime object that is automatically reference counted." More precisely, handle-to-object declares that the compiler should insert code to automatically manage the object's reference count, and delete the object if the reference count goes to zero.| -|Reference|Reference to an object (`&`):

*T* `&` *identifier*|Tracking reference (`%`):

*T* `%` *identifier*|Only Windows Runtime types can be declared by using the tracking reference modifier. Members of the object are accessed by using the dot (`.`) class-member-access operator.

The tracking reference means "a reference to a Windows Runtime object that is automatically reference counted." More precisely, a tracking reference declares that the compiler should insert code to automatically manage the object's reference count, and delete the object if the reference count goes to zero.| -|Dynamic type declaration|`new`|`ref new`|Allocates a Windows Runtime object and then returns a handle to that object.| -|Object lifetime management|`delete` *identifier*

`delete[]` *identifier*|(Invokes the destructor.)|Lifetime is determined by reference counting. A call to delete invokes the destructor but itself does not free memory.| -|Array declaration|*T identifier* `[]`

`std::array` *identifier*|`Array<` *T* `^>^` *identifier* `(` *size* `)`

-or-

`WriteOnlyArray<` *T* `^>` *identifier* `(` *size* `)`|Declares a one-dimensional modifiable or write-only array of type T^. The array itself is also a reference-counted object that must be declared by using the handle-to-object modifier.

(Array declarations use a template header class that is in the `Platform` namespace.)| -|Class declaration|**`class`** *identifier* `{}`

**`struct`** *identifier* `{}`|**`ref class`** *identifier* `{}`

**`ref struct`** *identifier* `{}`|Declares a runtime class that has default private accessibility.

Declares a runtime class that has default public accessibility.| -|Structure declaration|**`struct`** *identifier* `{}`

(that is, a Plain Old Data structure (POD))|**`value class`** *identifier* `{}`

**`value struct`** *identifier* `{}`|Declares a POD struct that has default private accessibility.

A value class can be represented in Windows metadata, but a standard C++ class cannot be.

Declares a POD struct that has default public accessibility.

A value struct can be represented in Windows metadata, but a standard C++ struct cannot be.| -|Interface declaration|abstract class that contains only pure virtual functions.|**`interface class`** *identifier* `{}`

**`interface struct`** *identifier* `{}`|Declares an interface that has default private accessibility.

Declares an interface that has default public accessibility.| -|Delegate|`std::function`|`public delegate` *return-type* *delegate-type-identifier* `(` *[ parameters ]* `);`|Declares an object that can be invoked like a function call.| -|Event|(Does not apply)|**`event`** *delegate-type-identifier* *event-identifier* `;`

*delegate-type-identifier* *delegate-identifier* = `ref new`*delegate-type-identifier*`( this`*[, parameters]*`);`

*event-identifier* `+=` *delegate-identifier* `;`

-or-

`EventRegistrationToken` *token-identifier* = *obj*`.`*event-identifier*`+=`*delegate-identifier*`;`

-or-

**`auto`** *token-identifier* = *obj*. *event-identifier*`::add(`*delegate-identifier*`);`

*obj* `.` *event-identifier* `-=` *token-identifier* `;`

-or-

*obj* `.` *event-identifier* `::remove(` *token-identifier* `);`|Declares an event object, which stores a collection of event handlers (delegates) that are called when an event occurs.

Creates an event handler.

Adds an event handler.

Adding an event handler returns an event token (*token-identifier*). If you intend to explicitly remove the event handler, you must save the event token for later use.

Removes an event handler.

To remove an event handler, you must specify the event token that you saved when the event handler was added.| -|Property|(Does not apply)|**`property`** *T* *identifier*;

**`property`** *T* *identifier* `[` *index* `];`

**`property`** *T* `default[` *index* `];`|Declares that a class or object member function is accessed by using the same syntax that's used to access a data member or indexed array element.

Declares a property on a class or object member function.

Declares an indexed property on an object member function.

Declares an indexed property on a class member function.| -|Parameterized types|templates|`generic interface class` *identifier* `{}`

`generic delegate` *[return-type]* *delegate-identifier* `() {}`|Declares a parameterized interface class.

Declares a parameterized delegate.| -|Nullable value types|`boost::optional`|[Platform::IBox \](../cppcx/platform-ibox-interface.md)|Enables variables of scalar types and value structs to have a value of **`nullptr`**.| +| Concept | Standard C++ | C++/CX | Remarks | +|--|--|--|--| +| Fundamental types | C++ fundamental types. | C++/CX fundamental types that implement fundamental types that are defined in the Windows Runtime. | The `default` namespace contains C++/CX built-in, fundamental types. The compiler implicitly maps C++/CX fundamental types to standard C++ types.

The `Platform` family of namespaces contains types that implement fundamental Windows Runtime types. | +| | **`bool`** | **`bool`** | An 8-bit Boolean value. | +| | **`wchar_t`**, **`char16_t`** | `char16` | A 16-bit nonnumeric value that represents a Unicode (UTF-16) code point. | +| | **`short`**

**`unsigned short`** | `int16`

`uint16` | A 16-bit signed integer.

A 16-bit unsigned integer. | +| | **`int`**

**`unsigned int`** | `int`

`uint32` | A 32-bit signed integer.

A 32-bit unsigned integer. | +| | **`long long`** -or- **`__int64`**

**`unsigned long long`** | `int64`

`uint64` | A 64-bit signed integer.

A 64-bit unsigned integer. | +| | **`float`**, **`double`** | `float32`, `float64` | A 32-bit or 64-bit IEEE 754 floating-point number. | +| | **`enum`** | **`enum class`**

-or-

**`enum struct`** | A 32-bit enumeration. | +| | (Doesn't apply) | `Platform::Guid` | A 128-bit nonnumeric value (a GUID) in the `Platform` namespace. | +| | `std::time_get` | `Windows::Foundation::DateTime` | A date-time structure. | +| | (Doesn't apply) | `Windows::Foundation::TimeSpan` | A timespan structure. | +| | (Doesn't apply) | `Platform::Object^` | The reference-counted base object in the C++ view of the Windows Runtime type system. | +| | `std::wstring`

`L"..."` | `Platform::String^` | `Platform::String^` is a reference-counted, immutable, sequence of Unicode characters that represent text. | +| Pointer | Pointer to object (`*`):

`std::shared_ptr` | Handle-to-object (`^`, pronounced "hat"):

`T^ identifier` | All Windows Runtime classes are declared by using the handle-to-object modifier. Members of the object are accessed by using the arrow (`->`) class-member-access operator.

The hat modifier means "pointer to a Windows Runtime object that is automatically reference counted." More precisely, handle-to-object declares that the compiler should insert code to manage the object's reference count automatically, and delete the object if the reference count goes to zero | +| Reference | Reference to an object (`&`):

`T& identifier` | Tracking reference (`%`):

`T% identifier` | Only Windows Runtime types can be declared by using the tracking reference modifier. Members of the object are accessed by using the dot (`.`) class-member-access operator.

The tracking reference means "a reference to a Windows Runtime object that is automatically reference counted." More precisely, a tracking reference declares that the compiler should insert code to manage the object's reference count automatically. The code deletes the object if the reference count goes to zero. | +| Dynamic type declaration | `new` | `ref new` | Allocates a Windows Runtime object and then returns a handle to that object. | +| Object lifetime management | `delete identifier`

`delete[] identifier` | (Invokes the destructor.) | Lifetime is determined by reference counting. A call to `delete` invokes the destructor but itself doesn't free memory. | +| Array declaration | `T identifier[]`

`std::array identifier` | `Array^ identifier( size )`

-or-

`WriteOnlyArray identifier( size )` | Declares a one-dimensional modifiable or write-only array of type `T^`. The array itself is also a reference-counted object that must be declared by using the handle-to-object modifier.

(Array declarations use a template header class that is in the `Platform` namespace.) | +| Class declaration | `class identifier {}`

`struct identifier {}` | `ref class identifier {}`

`ref struct identifier {}` | Declares a runtime class that has default `private` accessibility.

Declares a runtime class that has default `public` accessibility. | +| Structure declaration | `struct identifier {}`

(that is, a Plain Old Data structure (POD)) | `value class identifier {}`

`value struct identifier {}` | Declares a POD struct that has default `private` accessibility.

A `value class` can be represented in Windows metadata, but a standard C++ `class` can't be.

Declares a POD struct that has default `public` accessibility.

A `value struct` can be represented in Windows metadata, but a standard C++ `struct` can't be. | +| Interface declaration | abstract class that contains only pure virtual functions. | `interface class identifier {}`

`interface struct identifier {}` | Declares an interface that has default `private` accessibility.

Declares an interface that has default `public` accessibility. | +| Delegate | `std::function` | `public delegate return-type delegate-type-identifier (` *[ parameters ]* `);` | Declares an object that can be invoked like a function call. | +| Event | (Doesn't apply) | `event delegate-type-identifier event-identifier;`

`delegate-type-identifier delegate-identifier = ref new delegate-type-identifier( this` *[, parameters]* `);`

`event-identifier += *delegate-identifier;`

-or-

`EventRegistrationToken token-identifier = object.event-identifier += delegate-identifier;`

-or-

`auto token-identifier = object.event-identifier::add( delegate-identifier );`

`object.event-identifier -= token-identifier;`

-or-

`object.event-identifier::remove( token-identifier );` | Declares an `event` object, which stores a collection of event handlers (delegates) that are called when an event occurs.

Creates an event handler.

Adds an event handler.

Adding an event handler returns an event token (*`token-identifier`*). If you intend to explicitly remove the event handler, you must save the event token for later use.

Removes an event handler.

To remove an event handler, you must specify the event token that you saved when the event handler was added. | +| Property | (Doesn't apply) | `property T identifier;`

`property T identifier[ index ];`

`property T default[ index ];` | Declares that a class or object member function is accessed by using the same syntax that's used to access a data member or indexed array element.

Declares a property on a class or object member function.

Declares an indexed property on an object member function.

Declares an indexed property on a class member function. | +| Parameterized types | templates | `generic interface class identifier {}`

`generic delegate` *[`return-type`]* `delegate-identifier() {}` | Declares a parameterized interface class.

Declares a parameterized delegate. | +| Nullable value types | `std::optional` | [`Platform::IBox `](../cppcx/platform-ibox-interface.md) | Enables variables of scalar types and `value` structs to have a value of **`nullptr`**. | ## See also -[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md) +[C++/CX language reference](../cppcx/visual-c-language-reference-c-cx.md) diff --git a/docs/cppcx/static-libraries-c-cx.md b/docs/cppcx/static-libraries-c-cx.md index a67e7db8fe..8f887064f4 100644 --- a/docs/cppcx/static-libraries-c-cx.md +++ b/docs/cppcx/static-libraries-c-cx.md @@ -38,13 +38,13 @@ Instructions for creating a new project vary depending on which version of Visua When you compile a new static library, if you make a call to a Win32 API that's excluded for UWP apps, the compiler will raise error C3861, "Identifier not found." To look for an alternative method that's supported for the Windows Runtime, see [Alternatives to Windows APIs in UWP apps](/uwp/win32-and-com/alternatives-to-windows-apis-uwp). -If you add a C++ static library project to a UWP app solution, you might have to update the library project’s property settings so that the UWP support property is set to **Yes**. Without this setting, the code builds and links, but an error occurs when you attempt to verify the app for the Microsoft Store. The static lib should be compiled with the same compiler settings as the project that consumes it. +If you add a C++ static library project to a UWP app solution, you might have to update the library project's property settings so that the UWP support property is set to **Yes**. Without this setting, the code builds and links, but an error occurs when you attempt to verify the app for the Microsoft Store. The static lib should be compiled with the same compiler settings as the project that consumes it. If you consume a static library that creates public `ref` classes, public interface classes, or public value classes, the linker raises this warning: > **warning LNK4264:** archiving object file compiled with /ZW into a static library; note that when authoring Windows Runtime types it is not recommended to link with a static library that contains Windows Runtime metadata. -You can safely ignore the warning only if the static library is not producing Windows Runtime components that are consumed outside the library itself. If the library doesn’t consume a component that it defines, then the linker can optimize away the implementation even though the public metadata contains the type information. This means that public components in a static library will compile but will not activate at run time. For this reason, any Windows Runtime component that's intended for consumption by other components or apps must be implemented in a dynamic-link library (DLL). +You can safely ignore the warning only if the static library is not producing Windows Runtime components that are consumed outside the library itself. If the library doesn't consume a component that it defines, then the linker can optimize away the implementation even though the public metadata contains the type information. This means that public components in a static library will compile but will not activate at run time. For this reason, any Windows Runtime component that's intended for consumption by other components or apps must be implemented in a dynamic-link library (DLL). ## See also diff --git a/docs/cppcx/threading-and-marshaling-c-cx.md b/docs/cppcx/threading-and-marshaling-c-cx.md index da89d293b3..3ddf3dd499 100644 --- a/docs/cppcx/threading-and-marshaling-c-cx.md +++ b/docs/cppcx/threading-and-marshaling-c-cx.md @@ -18,7 +18,7 @@ A Windows Runtime class can support concurrent thread access in various ways, as - `MarshallingBehavior` attribute can have one of the values—Agile, None, or Standard as defined by the `MarshallingType` enumeration. -The `ThreadingModel` attribute specifies where the class is loaded when activated: only in a user-interface thread (STA) context, only in a background thread (MTA) context, or in the context of the thread that creates the object (Both). The `MarshallingBehavior` attribute values refer to how the object behaves in the various threading contexts; in most cases, you don’t have to understand these values in detail. Of the classes that are provided by the Windows API, about 90 percent have `ThreadingModel`=Both and `MarshallingType`=Agile. This means that they can handle low-level threading details transparently and efficiently. When you use `ref new` to create an "agile" class, you can call methods on it from your main app thread or from one or more worker threads. In other words, you can use an agile class—no matter whether it's provided by Windows or by a third party—from anywhere in your code. You don’t have to be concerned with the class’s threading model or marshaling behavior. +The `ThreadingModel` attribute specifies where the class is loaded when activated: only in a user-interface thread (STA) context, only in a background thread (MTA) context, or in the context of the thread that creates the object (Both). The `MarshallingBehavior` attribute values refer to how the object behaves in the various threading contexts; in most cases, you don't have to understand these values in detail. Of the classes that are provided by the Windows API, about 90 percent have `ThreadingModel`=Both and `MarshallingType`=Agile. This means that they can handle low-level threading details transparently and efficiently. When you use `ref new` to create an "agile" class, you can call methods on it from your main app thread or from one or more worker threads. In other words, you can use an agile class—no matter whether it's provided by Windows or by a third party—from anywhere in your code. You don't have to be concerned with the class's threading model or marshaling behavior. ## Consuming Windows Runtime components @@ -31,7 +31,6 @@ For various reasons, some classes can't be agile. If you are accessing instances Of the non-agile classes, the easiest to deal with are those that have `ThreadingModel`=Both and `MarshallingType`=Standard. You can make these classes agile just by using the `Agile` helper class. The following example shows a declaration of a non-agile object of type `Windows::Security::Credentials::UI::CredentialPickerOptions^`, and the compiler warning that's issued as a result. ``` - ref class MyOptions { public: @@ -63,7 +62,6 @@ If neither of those conditions apply, then you can mark the containing class as The following example shows how to use `Agile` so that you can safely ignore the warning. ``` - #include ref class MyOptions { diff --git a/docs/cppcx/value-classes-and-structs-c-cx.md b/docs/cppcx/value-classes-and-structs-c-cx.md index 9dbebf73e1..55d9691754 100644 --- a/docs/cppcx/value-classes-and-structs-c-cx.md +++ b/docs/cppcx/value-classes-and-structs-c-cx.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Value classes and structs (C++/CX)" title: "Value classes and structs (C++/CX)" +description: "Learn more about: Value classes and structs (C++/CX)" ms.date: "12/30/2016" helpviewer_keywords: ["value struct", "value class"] -ms.assetid: 262a0992-9721-4c02-8297-efc07d90e5a4 --- # Value classes and structs (C++/CX) @@ -12,7 +11,6 @@ A *value struct* or *value class* is a Windows Runtime-compatible POD ("plain ol The following examples show how to declare and initialize value structs. ``` - // in mainpage.xaml.h: value struct TestStruct { @@ -49,7 +47,7 @@ A value struct or value class can contain as fields only fundamental numeric typ A value class or value struct that contains a `Platform::String^` or `IBox^` type as a member is not `memcpy`-able. -Because all members of a **`value class`** or **`value struct`** are public and are emitted into metadata, standard C++ types are not allowed as members. This is different from ref classes, which may contain **`private`** or **`internal`** standard C++ types.. +Because all members of a **`value class`** or **`value struct`** are public and are emitted into metadata, standard C++ types are not allowed as members. This is different from ref classes, which may contain **`private`** or **`internal`** standard C++ types. The following code fragment declares the `Coordinates` and `City` types as value structs. Notice that one of the `City` data members is a `GeoCoordinates` type. A **`value struct`** can contain other value structs as members. @@ -125,7 +123,6 @@ bool MainPage::IsCurrentlyEnrolled(Student s) A value struct itself may be made nullable in the same way, as shown here: ``` - public value struct MyStruct { public: @@ -142,7 +139,7 @@ public: ## See also -[Type System (C++/CX)](../cppcx/type-system-c-cx.md)
-[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)
-[Namespaces Reference](../cppcx/namespaces-reference-c-cx.md)
+[Type System (C++/CX)](../cppcx/type-system-c-cx.md)\ +[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)\ +[Namespaces Reference](../cppcx/namespaces-reference-c-cx.md)\ [Ref classes and structs (C++/CX)](../cppcx/ref-classes-and-structs-c-cx.md) diff --git a/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md b/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md index 6ec20f173f..77f627b36d 100644 --- a/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md +++ b/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md @@ -6,12 +6,11 @@ ms.assetid: 1acb6402-05f0-4951-af94-0e9dab41c53e --- # Weak references and breaking cycles (C++/CX) -In any type system that's based on reference-counting, references to types can form *cycles*—that is, one object refers to a second object, the second object refers to a third object, and so on until some final object refers back to the first object. In a cycle, objects can't be deleted correctly when one object's reference count becomes zero. To help you solve this problem, C++/CX provides the [Platform::WeakReference Class](../cppcx/platform-weakreference-class.md) class. A `WeakReference` object supports the [Resolve](../cppcx/platform-weakreference-class.md#resolve) method, which returns null if the object no longer exists, or throws an [Platform::InvalidCastException](../cppcx/platform-invalidcastexception-class.md) if the object is alive but is not of type `T`. +In any type system that's based on reference-counting, references to types can form *cycles*—that is, one object refers to a second object, the second object refers to a third object, and so on until some final object refers back to the first object. In a cycle, objects can't be deleted correctly when one object's reference count becomes zero. To help you solve this problem, C++/CX provides the [Platform::WeakReference Class](../cppcx/platform-weakreference-class.md). A `WeakReference` object supports the [Resolve](../cppcx/platform-weakreference-class.md#resolve) method, which returns null if the object no longer exists, or throws an [Platform::InvalidCastException](../cppcx/platform-invalidcastexception-class.md) if the object is alive but is not of type `T`. One scenario in which `WeakReference` must be used is when the **`this`** pointer is captured in a lambda expression that's used to define an event handler. We recommend that you use named methods when you define event handlers, but if you want to use a lambda for your event handler—or if you have to break a reference counting cycle in some other situation—use `WeakReference`. Here's an example: ``` - using namespace Platform::Details; using namespace Windows::UI::Xaml; using namespace Windows::UI::Xaml::Input; diff --git a/docs/cppcx/windows-foundation-collections-namespace-c-cx.md b/docs/cppcx/windows-foundation-collections-namespace-c-cx.md index e9f9056966..4bfd12a620 100644 --- a/docs/cppcx/windows-foundation-collections-namespace-c-cx.md +++ b/docs/cppcx/windows-foundation-collections-namespace-c-cx.md @@ -13,7 +13,6 @@ C++/CX supplements the Windows::Foundation::Collections namespace with functions ## Syntax ``` - namespace Windows { namespace Foundation { namespace Collections; diff --git a/docs/cppcx/wrl/activationfactory-class.md b/docs/cppcx/wrl/activationfactory-class.md index 26f79c006e..dc849fce65 100644 --- a/docs/cppcx/wrl/activationfactory-class.md +++ b/docs/cppcx/wrl/activationfactory-class.md @@ -139,7 +139,7 @@ STDMETHOD( ### Parameters *iidCount*
-When this operation completes, the number of interace IDs in the *iids* array. +When this operation completes, the number of interface IDs in the *iids* array. *iids*
When this operation completes, an array of implemented interface IDs. diff --git a/docs/cppcx/wrl/agileeventsource-class.md b/docs/cppcx/wrl/agileeventsource-class.md index 5a3d541588..3922e3f696 100644 --- a/docs/cppcx/wrl/agileeventsource-class.md +++ b/docs/cppcx/wrl/agileeventsource-class.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["AgileEventSource class"] --- # AgileEventSource Class -Represents an event that is raised by a agile component, which is a component that can be accessed from any thread. Inherits from [EventSource](eventsource-class.md) and overrides the `Add` member function with an additional type parameter for specifying options for how to invoke the agile event. +Represents an event that is raised by an agile component, which is a component that can be accessed from any thread. Inherits from [EventSource](eventsource-class.md) and overrides the `Add` member function with an additional type parameter for specifying options for how to invoke the agile event. ## Syntax diff --git a/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md b/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md index 9ed068e9a3..84a982a6a9 100644 --- a/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md +++ b/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md @@ -9,7 +9,7 @@ ms.assetid: 5de49f7d-e5e3-43e9-bbca-666caf226cef --- # CancelTransitionPolicy Enumeration -Indicates how an asynchronous operation’s attempt to transition to a terminal state of completed or error should behave with respect to a client-requested canceled state. +Indicates how an asynchronous operation's attempt to transition to a terminal state of completed or error should behave with respect to a client-requested canceled state. ## Syntax diff --git a/docs/cppcx/wrl/chaininterfaces-structure.md b/docs/cppcx/wrl/chaininterfaces-structure.md index 8f4c5b7bed..d27322ff97 100644 --- a/docs/cppcx/wrl/chaininterfaces-structure.md +++ b/docs/cppcx/wrl/chaininterfaces-structure.md @@ -90,7 +90,7 @@ A derived type. The base type of a derived type. *hasImplements*
-A Boolean value that if **`true`**, means you can't use a [MixIn](mixin-structure.md) structure with a class that does not derive from the [Implements](implements-structure.md) stucture. +A Boolean value that if **`true`**, means you can't use a [MixIn](mixin-structure.md) structure with a class that does not derive from the [Implements](implements-structure.md) structure. ## Members diff --git a/docs/cppcx/wrl/comptr-class.md b/docs/cppcx/wrl/comptr-class.md index 7bf5048666..4a7dd96ff2 100644 --- a/docs/cppcx/wrl/comptr-class.md +++ b/docs/cppcx/wrl/comptr-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: ComPtr Class" title: "ComPtr Class" -ms.date: "06/02/2020" +ms.date: 05/09/2022 ms.topic: "reference" f1_keywords: ["client/Microsoft::WRL::ComPtr", "client/Microsoft::WRL::ComPtr::As", "client/Microsoft::WRL::ComPtr::AsIID", "client/Microsoft::WRL::ComPtr::AsWeak", "client/Microsoft::WRL::ComPtr::Attach", "client/Microsoft::WRL::ComPtr::ComPtr", "client/Microsoft::WRL::ComPtr::CopyTo", "client/Microsoft::WRL::ComPtr::Detach", "client/Microsoft::WRL::ComPtr::Get", "client/Microsoft::WRL::ComPtr::GetAddressOf", "client/Microsoft::WRL::ComPtr::InternalAddRef", "client/Microsoft::WRL::ComPtr::InternalRelease", "client/Microsoft::WRL::ComPtr::operator&", "client/Microsoft::WRL::ComPtr::operator->", "client/Microsoft::WRL::ComPtr::operator=", "client/Microsoft::WRL::ComPtr::operator==", "client/Microsoft::WRL::ComPtr::operator!=", "client/Microsoft::WRL::ComPtr::operator Microsoft::WRL::Details::BoolType", "client/Microsoft::WRL::ComPtr::ptr_", "client/Microsoft::WRL::ComPtr::ReleaseAndGetAddressOf", "client/Microsoft::WRL::ComPtr::Reset", "client/Microsoft::WRL::ComPtr::Swap", "client/Microsoft::WRL::ComPtr::~ComPtr"] helpviewer_keywords: ["Microsoft::WRL::ComPtr class", "Microsoft::WRL::ComPtr::As method", "Microsoft::WRL::ComPtr::AsIID method", "Microsoft::WRL::ComPtr::AsWeak method", "Microsoft::WRL::ComPtr::Attach method", "Microsoft::WRL::ComPtr::ComPtr, constructor", "Microsoft::WRL::ComPtr::CopyTo method", "Microsoft::WRL::ComPtr::Detach method", "Microsoft::WRL::ComPtr::Get method", "Microsoft::WRL::ComPtr::GetAddressOf method", "Microsoft::WRL::ComPtr::InternalAddRef method", "Microsoft::WRL::ComPtr::InternalRelease method", "Microsoft::WRL::ComPtr::operator& operator", "Microsoft::WRL::ComPtr::operator-> operator", "Microsoft::WRL::ComPtr::operator= operator", "Microsoft::WRL::ComPtr::operator== operator", "Microsoft::WRL::ComPtr::operator!= operator", "Microsoft::WRL::ComPtr::operator Microsoft::WRL::Details::BoolType operator", "Microsoft::WRL::ComPtr::ptr_ data member", "Microsoft::WRL::ComPtr::ReleaseAndGetAddressOf method", "Microsoft::WRL::ComPtr::Reset method", "Microsoft::WRL::ComPtr::Swap method", "Microsoft::WRL::ComPtr::~ComPtr, destructor"] @@ -17,16 +17,16 @@ Creates a *smart pointer* type that represents the interface specified by the te template class ComPtr; -template +template friend class ComPtr; ``` ### Parameters -*T*
+*`T`*\ The interface that the `ComPtr` represents. -*U*
+*`U`*\ A class to which the current `ComPtr` is a friend. (The template that uses this parameter is protected.) ## Remarks @@ -39,56 +39,56 @@ For more information about smart pointers, see the "COM Smart Pointers" subsecti ### Public Typedefs -Name | Description ---------------- | --------------------------------------------------------------- -`InterfaceType` | A synonym for the type specified by the *T* template parameter. +| Name | Description | +|--|--| +| `InterfaceType` | A synonym for the type specified by the *`T`* template parameter. | ### Public Constructors -Name | Description --------------------------------- | -------------------------------------------------------------------------------------------------------------------- -[ComPtr::ComPtr](#comptr) | Initializes a new instance of the `ComPtr` class. Overloads provide default, copy, move, and conversion constructors. -[ComPtr::~ComPtr](#tilde-comptr) | Deinitializes an instance of `ComPtr`. +| Name | Description | +|--|--| +| [`ComPtr::ComPtr`](#comptr) | Initializes a new instance of the `ComPtr` class. Overloads provide default, copy, move, and conversion constructors. | +| [`ComPtr::~ComPtr`](#tilde-comptr) | Deinitializes an instance of `ComPtr`. | ### Public Methods -Name | Description ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -[ComPtr::As](#as) | Returns a `ComPtr` object that represents the interface identified by the specified template parameter. -[ComPtr::AsIID](#asiid) | Returns a `ComPtr` object that represents the interface identified by the specified interface ID. -[ComPtr::AsWeak](#asweak) | Retrieves a weak reference to the current object. -[ComPtr::Attach](#attach) | Associates this `ComPtr` with the interface type specified by the current template type parameter. -[ComPtr::CopyTo](#copyto) | Copies the current or specified interface associated with this `ComPtr` to the specified output pointer. -[ComPtr::Detach](#detach) | Disassociates this `ComPtr` from the interface that it represents. -[ComPtr::Get](#get) | Retrieves a pointer to the interface that is associated with this `ComPtr`. -[ComPtr::GetAddressOf](#getaddressof) | Retrieves the address of the [ptr_](#ptr) data member, which contains a pointer to the interface represented by this `ComPtr`. -[ComPtr::ReleaseAndGetAddressOf](#releaseandgetaddressof) | Releases the interface associated with this `ComPtr` and then retrieves the address of the [ptr_](#ptr) data member, which contains a pointer to the interface that was released. -[ComPtr::Reset](#reset) | Releases the interface associated with this `ComPtr` and returns the new reference count. -[ComPtr::Swap](#swap) | Exchanges the interface managed by the current `ComPtr` with the interface managed by the specified `ComPtr`. +| Name | Description | +|--|--| +| [`ComPtr::As`](#as) | Returns a `ComPtr` object that represents the interface identified by the specified template parameter. | +| [`ComPtr::AsIID`](#asiid) | Returns a `ComPtr` object that represents the interface identified by the specified interface ID. | +| [`ComPtr::AsWeak`](#asweak) | Retrieves a weak reference to the current object. | +| [`ComPtr::Attach`](#attach) | Associates this `ComPtr` with the interface type specified by the current template type parameter. | +| [`ComPtr::CopyTo`](#copyto) | Copies the current or specified interface associated with this `ComPtr` to the specified output pointer. | +| [`ComPtr::Detach`](#detach) | Disassociates this `ComPtr` from the interface that it represents. | +| [`ComPtr::Get`](#get) | Retrieves a pointer to the interface that is associated with this `ComPtr`. | +| [`ComPtr::GetAddressOf`](#getaddressof) | Retrieves the address of the [`ptr_`](#ptr) data member, which contains a pointer to the interface represented by this `ComPtr`. | +| [`ComPtr::ReleaseAndGetAddressOf`](#releaseandgetaddressof) | Releases the interface associated with this `ComPtr` and then retrieves the address of the [`ptr_`](#ptr) data member, which contains a pointer to the interface that was released. | +| [`ComPtr::Reset`](#reset) | Releases the interface associated with this `ComPtr` and returns the new reference count. | +| [`ComPtr::Swap`](#swap) | Exchanges the interface managed by the current `ComPtr` with the interface managed by the specified `ComPtr`. | ### Protected Methods -Name | Description -------------------------------------------- | -------------------------------------------------------------------------------- -[ComPtr::InternalAddRef](#internaladdref) | Increments the reference count of the interface associated with this `ComPtr`. -[ComPtr::InternalRelease](#internalrelease) | Performs a COM Release operation on the interface associated with this `ComPtr`. +| Name | Description | +|--|--| +| [`ComPtr::InternalAddRef`](#internaladdref) | Increments the reference count of the interface associated with this `ComPtr`. | +| [`ComPtr::InternalRelease`](#internalrelease) | Performs a COM Release operation on the interface associated with this `ComPtr`. | ### Public Operators -Name | Description ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ -[ComPtr::operator&](#operator-ampersand) | Retrieves the address of the current `ComPtr`. -[ComPtr::operator->](#operator-arrow) | Retrieves a pointer to the type specified by the current template parameter. -[ComPtr::operator=](#operator-assign) | Assigns a value to the current `ComPtr`. -[ComPtr::operator==](#operator-equality) | Indicates whether two `ComPtr` objects are equal. -[ComPtr::operator!=](#operator-inequality) | Indicates whether two `ComPtr` objects aren't equal. -[ComPtr::operator Microsoft::WRL::Details::BoolType](#operator-microsoft-wrl-details-booltype) | Indicates whether a `ComPtr` is managing the object lifetime of an interface. +| Name | Description | +|--|--| +| [`ComPtr::operator&`](#operator-ampersand) | Retrieves the address of the current `ComPtr`. | +| [`ComPtr::operator->`](#operator-arrow) | Retrieves a pointer to the type specified by the current template parameter. | +| [`ComPtr::operator=`](#operator-assign) | Assigns a value to the current `ComPtr`. | +| [`ComPtr::operator==`](#operator-equality) | Indicates whether two `ComPtr` objects are equal. | +| [`ComPtr::operator!=`](#operator-inequality) | Indicates whether two `ComPtr` objects aren't equal. | +| [`ComPtr::operator Microsoft::WRL::Details::BoolType`](#operator-microsoft-wrl-details-booltype) | Indicates whether a `ComPtr` is managing the object lifetime of an interface. | ### Protected Data Members -Name | Description --------------------- | ------------------------------------------------------------------------------------------ -[ComPtr::ptr_](#ptr) | Contains a pointer to the interface that is associated with, and managed by this `ComPtr`. +| Name | Description | +|--|--| +| [`ComPtr::ptr_`](#ptr) | Contains a pointer to the interface that is associated with, and managed by this `ComPtr`. | ## Inheritance Hierarchy @@ -96,11 +96,11 @@ Name | Description ## Requirements -**Header:** client.h +**Header:** *`client.h`* -**Namespace:** Microsoft::WRL +**Namespace:** `Microsoft::WRL` -## ComPtr::~ComPtr +## `ComPtr::~ComPtr` Deinitializes an instance of `ComPtr`. @@ -108,7 +108,7 @@ Deinitializes an instance of `ComPtr`. WRL_NOTHROW ~ComPtr(); ``` -## ComPtr::As +## `ComPtr::As` Returns a `ComPtr` object that represents the interface identified by the specified template parameter. @@ -126,21 +126,21 @@ HRESULT As( ### Parameters -*U*
-The interface to be represented by parameter *p*. +*`U`*\ +The interface to be represented by parameter *`p`*. -*p*
-A `ComPtr` object that represents the interface specified by parameter *U*. Parameter *p* must not refer to the current `ComPtr` object. +*`p`*\ +A `ComPtr` object that represents the interface specified by parameter *`U`*. Parameter *`p`* must not refer to the current `ComPtr` object. ### Remarks -The first template is the form that you should use in your code. The second template is an internal, helper specialization. It supports C++ language features such as the [auto](../../cpp/auto-cpp.md) type deduction keyword. +The first template is the form that you should use in your code. The second template is an internal, helper specialization. It supports C++ language features such as the [`auto`](../../cpp/auto-cpp.md) type deduction keyword. ### Return Value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## ComPtr::AsIID +## `ComPtr::AsIID` Returns a `ComPtr` object that represents the interface identified by the specified interface ID. @@ -153,17 +153,17 @@ WRL_NOTHROW HRESULT AsIID( ### Parameters -*riid*
+*`riid`*\ An interface ID. -*p*
-If the object has an interface whose ID equals *riid*, a doubly indirect pointer to the interface specified by the *riid* parameter. Otherwise, a pointer to `IUnknown`. +*`p`*\ +If the object has an interface whose ID equals *`riid`*, a doubly indirect pointer to the interface specified by the *`riid`* parameter. Otherwise, a pointer to `IUnknown`. ### Return Value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## ComPtr::AsWeak +## `ComPtr::AsWeak` Retrieves a weak reference to the current object. @@ -175,14 +175,14 @@ HRESULT AsWeak( ### Parameters -*pWeakRef*
+*`pWeakRef`*\ When this operation completes, a pointer to a weak reference object. ### Return Value S_OK if successful; otherwise, an HRESULT that indicates the error. -## ComPtr::Attach +## `ComPtr::Attach` Associates this `ComPtr` with the interface type specified by the current template type parameter. @@ -194,10 +194,10 @@ void Attach( ### Parameters -*other*
+*`other`*\ An interface type. -## ComPtr::ComPtr +## `ComPtr::ComPtr` Initializes a new instance of the `ComPtr` class. Overloads provide default, copy, move, and conversion constructors. @@ -235,25 +235,25 @@ WRL_NOTHROW ComPtr( ### Parameters -*U*
-The type of the *other* parameter. +*`U`*\ +The type of the *`other`* parameter. -*other*
-An object of type *U*. +*`other`*\ +An object of type *`U`*. ### Return Value ### Remarks -The first constructor is the default constructor, which implicitly creates an empty object. The second constructor specifies [__nullptr](../../extensions/nullptr-cpp-component-extensions.md), which explicitly creates an empty object. +The first constructor is the default constructor, which implicitly creates an empty object. The second constructor specifies [`__nullptr`](../../extensions/nullptr-cpp-component-extensions.md), which explicitly creates an empty object. -The third constructor creates an object from the object specified by a pointer. The ComPtr now owns the pointed-to memory and maintains a reference count to it. +The third constructor creates an object from the object specified by a pointer. The `ComPtr` now owns the pointed-to memory and maintains a reference count to it. The fourth and fifth constructors are copy constructors. The fifth constructor copies an object if it's convertible to the current type. The sixth and seventh constructors are move constructors. The seventh constructor moves an object if it's convertible to the current type. -## ComPtr::CopyTo +## `ComPtr::CopyTo` Copies the current or specified interface associated with this `ComPtr` to the specified pointer. @@ -275,28 +275,28 @@ HRESULT CopyTo( ### Parameters -*U*
+*`U`*\ A type name. -*ptr*
+*`ptr`*\ When this operation completes, a pointer to the requested interface. -*riid*
+*`riid`*\ An interface ID. ### Return Value -S_OK if successful; otherwise, an HRESULT that indicates why the implicit `QueryInterface` operation failed. +`S_OK` if successful; otherwise, an `HRESULT` that indicates why the implicit `QueryInterface` operation failed. ### Remarks -The first function returns a copy of a pointer to the interface associated with this `ComPtr`. This function always returns S_OK. +The first function returns a copy of a pointer to the interface associated with this `ComPtr`. This function always returns `S_OK`. -The second function performs a `QueryInterface` operation on the interface associated with this `ComPtr` for the interface specified by the *riid* parameter. +The second function performs a `QueryInterface` operation on the interface associated with this `ComPtr` for the interface specified by the *`riid`* parameter. -The third function performs a `QueryInterface` operation on the interface associated with this `ComPtr` for the underlying interface of the *U* parameter. +The third function performs a `QueryInterface` operation on the interface associated with this `ComPtr` for the underlying interface of the *`U`* parameter. -## ComPtr::Detach +## `ComPtr::Detach` Disassociates this `ComPtr` object from the interface that it represents. @@ -308,7 +308,7 @@ T* Detach(); A pointer to the interface that was represented by this `ComPtr` object. -## ComPtr::Get +## `ComPtr::Get` Retrieves a pointer to the interface that is associated with this `ComPtr`. @@ -320,9 +320,9 @@ T* Get() const; Pointer to the interface that is associated with this `ComPtr`. -## ComPtr::GetAddressOf +## `ComPtr::GetAddressOf` -Retrieves the address of the [ptr_](#ptr) data member, which contains a pointer to the interface represented by this `ComPtr`. +Retrieves the address of the [`ptr_`](#ptr) data member, which contains a pointer to the interface represented by this `ComPtr`. ```cpp T* const* GetAddressOf() const; @@ -333,7 +333,7 @@ T** GetAddressOf(); The address of a variable. -## ComPtr::InternalAddRef +## `ComPtr::InternalAddRef` Increments the reference count of the interface associated with this `ComPtr`. @@ -345,7 +345,7 @@ void InternalAddRef() const; This method is protected. -## ComPtr::InternalRelease +## `ComPtr::InternalRelease` Performs a COM Release operation on the interface associated with this `ComPtr`. @@ -357,7 +357,7 @@ unsigned long InternalRelease(); This method is protected. -## ComPtr::operator& +## `ComPtr::operator&` Releases the interface associated with this `ComPtr` object and then retrieves the address of the `ComPtr` object. @@ -373,7 +373,7 @@ A weak reference to the current `ComPtr`. ### Remarks -This method differs from [ComPtr::GetAddressOf](#getaddressof) in that this method releases a reference to the interface pointer. Use `ComPtr::GetAddressOf` when you require the address of the interface pointer but don't want to release that interface. +This method differs from [`ComPtr::GetAddressOf`](#getaddressof) in that this method releases a reference to the interface pointer. Use `ComPtr::GetAddressOf` when you require the address of the interface pointer but don't want to release that interface. ## `ComPtr::operator->` @@ -391,7 +391,7 @@ Pointer to the type specified by the current template type name. This helper function removes unnecessary overhead caused by using the STDMETHOD macro. This function makes `IUnknown` types **`private`** instead of **`virtual`**. -## ComPtr::operator= +## `ComPtr::operator=` Assigns a value to the current `ComPtr`. @@ -424,10 +424,10 @@ WRL_NOTHROW ComPtr& operator=( ### Parameters -*U*
+*`U`*\ A class. -*other*
+*`other`*\ A pointer, reference, or rvalue reference to a type or another `ComPtr`. ### Return Value @@ -448,9 +448,9 @@ The fifth version is a copy operator; a reference to a `ComPtr` is assigned to t The sixth version is a copy operator that uses move semantics; an rvalue reference to a `ComPtr` if any type is static cast and then assigned to the current `ComPtr`. -The seventh version is a copy operator that uses move semantics; an rvalue reference to a `ComPtr` of type *U* is static cast then and assigned to the current `ComPtr`. +The seventh version is a copy operator that uses move semantics; an rvalue reference to a `ComPtr` of type *`U`* is static cast then and assigned to the current `ComPtr`. -## ComPtr::operator== +## `ComPtr::operator==` Indicates whether two `ComPtr` objects are equal. @@ -473,19 +473,19 @@ bool operator==( ### Parameters -*a*
+*`a`*\ A reference to a `ComPtr` object. -*b*
+*`b`*\ A reference to another `ComPtr` object. ### Return Value -The first operator yields **`true`** if object *a* is equal to object *b*; otherwise, **`false`**. +The first operator yields **`true`** if object *`a`* is equal to object *`b`*; otherwise, **`false`**. -The second and third operators yield **`true`** if object *a* is equal to **`nullptr`**; otherwise, **`false`**. +The second and third operators yield **`true`** if object *`a`* is equal to **`nullptr`**; otherwise, **`false`**. -## ComPtr::operator!= +## `ComPtr::operator!=` Indicates whether two `ComPtr` objects aren't equal. @@ -508,19 +508,19 @@ bool operator!=( ### Parameters -*a*
+*`a`*\ A reference to a `ComPtr` object. -*b*
+*`b`*\ A reference to another `ComPtr` object. ### Return Value -The first operator yields **`true`** if object *a* is not equal to object *b*; otherwise, **`false`**. +The first operator yields **`true`** if object *`a`* isn't equal to object *`b`*; otherwise, **`false`**. -The second and third operators yield **`true`** if object *a* is not equal to **`nullptr`**; otherwise, **`false`**. +The second and third operators yield **`true`** if object *`a`* isn't equal to **`nullptr`**; otherwise, **`false`**. -## ComPtr::operator Microsoft::WRL::Details::BoolType +## `ComPtr::operator Microsoft::WRL::Details::BoolType` Indicates whether a `ComPtr` is managing the object lifetime of an interface. @@ -530,9 +530,9 @@ WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const; ### Return Value -If an interface is associated with this `ComPtr`, the address of the [BoolStruct::Member](boolstruct-structure.md#member) data member; otherwise, **`nullptr`**. +If an interface is associated with this `ComPtr`, the address of the [`BoolStruct::Member`](boolstruct-structure.md#member) data member; otherwise, **`nullptr`**. -## ComPtr::ptr_ +## `ComPtr::ptr_` Contains a pointer to the interface that is associated with, and managed by this `ComPtr`. @@ -544,9 +544,9 @@ InterfaceType *ptr_; `ptr_` is an internal, protected data member. -## ComPtr::ReleaseAndGetAddressOf +## `ComPtr::ReleaseAndGetAddressOf` -Releases the interface associated with this `ComPtr` and then retrieves the address of the [ptr_](#ptr) data member, which contains a pointer to the interface that was released. +Releases the interface associated with this `ComPtr` and then retrieves the address of the [`ptr_`](#ptr) data member, which contains a pointer to the interface that was released. ```cpp T** ReleaseAndGetAddressOf(); @@ -554,9 +554,9 @@ T** ReleaseAndGetAddressOf(); ### Return Value -The address of the [ptr_](#ptr) data member of this `ComPtr`. +The address of the [`ptr_`](#ptr) data member of this `ComPtr`. -## ComPtr::Reset +## `ComPtr::Reset` Releases the interface associated with this `ComPtr` and returns the new reference count. @@ -568,7 +568,7 @@ unsigned long Reset(); The number of references remaining to the underlying interface, if any. -## ComPtr::Swap +## `ComPtr::Swap` Exchanges the interface managed by the current `ComPtr` with the interface managed by the specified `ComPtr`. @@ -584,5 +584,5 @@ void Swap( ### Parameters -*r*
+*`r`*\ A `ComPtr`. diff --git a/docs/cppcx/wrl/criticalsection-class.md b/docs/cppcx/wrl/criticalsection-class.md index de0c012ca7..c061d36772 100644 --- a/docs/cppcx/wrl/criticalsection-class.md +++ b/docs/cppcx/wrl/criticalsection-class.md @@ -75,7 +75,7 @@ The spin count for the critical section object. The default value is 0. ### Remarks -For more information about critical sections and spincounts, see the `InitializeCriticalSectionAndSpinCount` function in the `Synchronization` section of the Windows API documenation. +For more information about critical sections and spincounts, see the `InitializeCriticalSectionAndSpinCount` function in the `Synchronization` section of the Windows API documentation. ## CriticalSection::cs_ diff --git a/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md b/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md index 90737d312d..113ac97dc3 100644 --- a/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md +++ b/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md @@ -47,7 +47,7 @@ The following steps use the `Windows::Foundation::IUriRuntimeClass` interface to [!code-cpp[wrl-consume-component#6](../codesnippet/CPP/how-to-activate-and-use-a-windows-runtime-component-using-wrl_4.cpp)] - In the Windows Runtime, you don’t allocate memory for a string that the Windows Runtime will use. Instead, the Windows Runtime creates a copy of your string in a buffer that it maintains and uses for operations, and then returns a handle to the buffer that it created. + In the Windows Runtime, you don't allocate memory for a string that the Windows Runtime will use. Instead, the Windows Runtime creates a copy of your string in a buffer that it maintains and uses for operations, and then returns a handle to the buffer that it created. 5. Use the `IUriRuntimeClassFactory::CreateUri` factory method to create a `ABI::Windows::Foundation::IUriRuntimeClass` object. diff --git a/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md b/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md index 9c2412c043..5e6a4535bf 100644 --- a/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md +++ b/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md @@ -46,7 +46,7 @@ The following steps start an asynchronous timer and wait for the timer to expire [!code-cpp[wrl-consume-async#5](../codesnippet/CPP/how-to-complete-asynchronous-operations-using-wrl_4.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Create an `IThreadPoolTimer` object that expires after two seconds. Use the `Callback` function to create the event handler (an `ABI::Windows::System::Threading::ITimerElapsedHandler` object). @@ -94,7 +94,7 @@ The following steps start a worker thread and define the action that's performed [!code-cpp[wrl-consume-asyncOp#5](../codesnippet/CPP/how-to-complete-asynchronous-operations-using-wrl_11.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Call the `IThreadPoolStatics::RunAsync` method to create a worker thread. Use the `Callback` function to define the action. diff --git a/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md b/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md index 8436766015..4b01f17a9a 100644 --- a/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md +++ b/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md @@ -68,7 +68,7 @@ This document shows how to use the Windows Runtime C++ Template Library to creat @="1.0" ``` -2. Run RegScript.reg or add it to your project’s **Post-Build Event**. For more information, see [Pre-build Event/Post-build Event Command Line Dialog Box](/visualstudio/ide/reference/pre-build-event-post-build-event-command-line-dialog-box). +2. Run RegScript.reg or add it to your project's **Post-Build Event**. For more information, see [Pre-build Event/Post-build Event Command Line Dialog Box](/visualstudio/ide/reference/pre-build-event-post-build-event-command-line-dialog-box). 3. Add a **Win32 Console Application** project to the solution. Name the project, for example, `Calculator`. diff --git a/docs/cppcx/wrl/how-to-handle-events-using-wrl.md b/docs/cppcx/wrl/how-to-handle-events-using-wrl.md index 2458674807..40245ab498 100644 --- a/docs/cppcx/wrl/how-to-handle-events-using-wrl.md +++ b/docs/cppcx/wrl/how-to-handle-events-using-wrl.md @@ -39,7 +39,7 @@ The following steps start an `ABI::Windows::System::Threading::IDeviceWatcher` o [!code-cpp[wrl-consume-event#4](../codesnippet/CPP/how-to-handle-events-using-wrl_4.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Create an activation factory for the `IDeviceWatcher` interface. diff --git a/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md b/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md index f450c89319..207ee699fd 100644 --- a/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md +++ b/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md @@ -16,7 +16,7 @@ To learn how to use Windows Runtime C++ Template Library to create a classic COM This document shows two examples. The first example uses the `Make` function to instantiate a component. The second example uses the `MakeAndInitialize` function to instantiate a component that can fail during construction. (Because COM typically uses HRESULT values, instead of exceptions, to indicate errors, a COM type typically does not throw from its constructor. `MakeAndInitialize` enables a component to validate its construction arguments through the `RuntimeClassInitialize` method.) Both examples define a basic logger interface and implement that interface by defining a class that writes messages to the console. > [!IMPORTANT] -> You can’t use the `new` operator to instantiate Windows Runtime C++ Template Library components. Therefore, we recommend that you always use `Make` or `MakeAndInitialize` to instantiate a component directly. +> You can't use the `new` operator to instantiate Windows Runtime C++ Template Library components. Therefore, we recommend that you always use `Make` or `MakeAndInitialize` to instantiate a component directly. ### To create and instantiate a basic logger component diff --git a/docs/cppcx/wrl/hstring-class.md b/docs/cppcx/wrl/hstring-class.md index 310b828349..c29a4a6cff 100644 --- a/docs/cppcx/wrl/hstring-class.md +++ b/docs/cppcx/wrl/hstring-class.md @@ -42,7 +42,7 @@ Name | Description [HString::GetRawBuffer](#getrawbuffer) | Retrieves a pointer to the underlying string data. [HString::IsValid](#isvalid) | Indicates whether the current `HString` object is valid. [HString::MakeReference](#makereference) | Creates an `HStringReference` object from a specified string parameter. -[HString::Release](#release) | Deletes the underlying string value and intializes the current `HString` object to an empty value. +[HString::Release](#release) | Deletes the underlying string value and initializes the current `HString` object to an empty value. [HString::Set](#set) | Sets the value of the current `HString` object to the specified wide-character string or `HString` parameter. ### Public Operators diff --git a/docs/cppcx/wrl/module-class.md b/docs/cppcx/wrl/module-class.md index 75bbf6bc9c..3cefc4e6d7 100644 --- a/docs/cppcx/wrl/module-class.md +++ b/docs/cppcx/wrl/module-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Module Class" title: "Module Class" -ms.date: "10/18/2018" +description: "Learn more about: Module Class" +ms.date: 10/18/2018 ms.topic: "reference" f1_keywords: ["module/Microsoft::WRL::Module", "module/Microsoft::WRL::Module::Create", "module/Microsoft::WRL::Module::DecrementObjectCount", "module/Microsoft::WRL::Module::GetActivationFactory", "module/Microsoft::WRL::Module::GetClassObject", "module/Microsoft::WRL::Module::GetModule", "module/Microsoft::WRL::Module::GetObjectCount", "module/Microsoft::WRL::Module::IncrementObjectCount", "module/Microsoft::WRL::Module::Module", "module/Microsoft::WRL::Module::objectCount_Data", "module/Microsoft::WRL::Module::RegisterCOMObject", "module/Microsoft::WRL::Module::RegisterObjects", "module/Microsoft::WRL::Module::RegisterWinRTObject", "module/Microsoft::WRL::Module::releaseNotifier_", "module/Microsoft::WRL::Module::Terminate", "module/Microsoft::WRL::Module::~Module", "module/Microsoft::WRL::Module::UnregisterCOMObject", "module/Microsoft::WRL::Module::UnregisterObjects", "module/Microsoft::WRL::Module::UnregisterWinRTObject"] helpviewer_keywords: ["Microsoft::WRL::Module class", "Microsoft::WRL::Module::Create method", "Microsoft::WRL::Module::DecrementObjectCount method", "Microsoft::WRL::Module::GetActivationFactory method", "Microsoft::WRL::Module::GetClassObject method", "Microsoft::WRL::Module::GetModule method", "Microsoft::WRL::Module::GetObjectCount method", "Microsoft::WRL::Module::IncrementObjectCount method", "Microsoft::WRL::Module::Module, constructor", "Microsoft::WRL::Module::objectCount_ data member", "Microsoft::WRL::Module::RegisterCOMObject method", "Microsoft::WRL::Module::RegisterObjects method", "Microsoft::WRL::Module::RegisterWinRTObject method", "Microsoft::WRL::Module::releaseNotifier_ data member", "Microsoft::WRL::Module::Terminate method", "Microsoft::WRL::Module::~Module, destructor", "Microsoft::WRL::Module::UnregisterCOMObject method", "Microsoft::WRL::Module::UnregisterObjects method", "Microsoft::WRL::Module::UnregisterWinRTObject method"] -ms.assetid: dd67e3b8-c2e1-4f53-8c0f-565a140ba649 --- # Module Class @@ -189,7 +188,7 @@ S_OK if successful; otherwise, the HRESULT returned by GetActivationFactory. ## Module::GetClassObject -Retreives a cache of class factories. +Retrieves a cache of class factories. ```cpp HRESULT GetClassObject( @@ -309,7 +308,7 @@ The number of CLSIDs to register. ### Return Value -S_OK if successfu; otherwise, an HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed. +S_OK if successful; otherwise, an HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed. ### Remarks @@ -396,7 +395,7 @@ Unregisters one or more COM objects, which prevents other applications from conn virtual HRESULT UnregisterCOMObject( const wchar_t* serverName, DWORD* cookies, - unsigned int count + unsigned int count); ``` ### Parameters diff --git a/docs/cppcx/wrl/runtimeclass-class.md b/docs/cppcx/wrl/runtimeclass-class.md index 5011d0fbae..6e026c28c9 100644 --- a/docs/cppcx/wrl/runtimeclass-class.md +++ b/docs/cppcx/wrl/runtimeclass-class.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: RuntimeClass Class" -title: "RuntimeClass Class" -ms.date: "09/11/2018" +description: "Learn more about: RuntimeClass class" +title: "RuntimeClass class" +ms.date: 09/28/2022 ms.topic: "reference" f1_keywords: ["implements/Microsoft::WRL::RuntimeClass", "implements/Microsoft::WRL::RuntimeClass::AddRef", "implements/Microsoft::WRL::RuntimeClass::DecrementReference", "implements/Microsoft::WRL::RuntimeClass::GetIids", "implements/Microsoft::WRL::RuntimeClass::GetRuntimeClassName", "implements/Microsoft::WRL::RuntimeClass::GetTrustLevel", "implements/Microsoft::WRL::RuntimeClass::GetWeakReference", "implements/Microsoft::WRL::RuntimeClass::InternalAddRef", "implements/Microsoft::WRL::RuntimeClass::QueryInterface", "implements/Microsoft::WRL::RuntimeClass::Release", "implements/Microsoft::WRL::RuntimeClass::RuntimeClass", "implements/Microsoft::WRL::RuntimeClass::~RuntimeClass"] helpviewer_keywords: ["Microsoft::WRL::RuntimeClass class", "Microsoft::WRL::RuntimeClass::AddRef method", "Microsoft::WRL::RuntimeClass::DecrementReference method", "Microsoft::WRL::RuntimeClass::GetIids method", "Microsoft::WRL::RuntimeClass::GetRuntimeClassName method", "Microsoft::WRL::RuntimeClass::GetTrustLevel method", "Microsoft::WRL::RuntimeClass::GetWeakReference method", "Microsoft::WRL::RuntimeClass::InternalAddRef method", "Microsoft::WRL::RuntimeClass::QueryInterface method", "Microsoft::WRL::RuntimeClass::Release method", "Microsoft::WRL::RuntimeClass::RuntimeClass, constructor", "Microsoft::WRL::RuntimeClass::~RuntimeClass, destructor"] ms.assetid: d52f9d1a-98e5-41f2-a143-8fb629dd0727 --- -# RuntimeClass Class +# `RuntimeClass` class Represents a WinRT or COM class that inherits the specified interfaces and provides the specified Windows Runtime, classic COM, and weak reference support. @@ -22,49 +22,49 @@ template class RuntimeClass; ### Parameters -*classFlags*
-Optional parameter. A combination of one or more [RuntimeClassType](runtimeclasstype-enumeration.md) enumeration values. The `__WRL_CONFIGURATION_LEGACY__` macro can be defined to change the default value of classFlags for all runtime classes in the project. If defined, RuntimeClass instances are non-agile by default. When not defined, RuntimeClass instances are agile by default. To avoid ambiguity always specify the `Microsoft::WRL::FtmBase` in `TInterfaces` or `RuntimeClassType::InhibitFtmBase`. Note, if InhibitFtmBase and FtmBase are both used the object will be agile. +*`classFlags`*\ +Optional parameter. A combination of one or more [`RuntimeClassType`](runtimeclasstype-enumeration.md) enumeration values. The `__WRL_CONFIGURATION_LEGACY__` macro can be defined to change the default value of *`classFlags`* for all runtime classes in the project. If defined, `RuntimeClass` instances are non-agile by default. When not defined, `RuntimeClass` instances are agile by default. To avoid ambiguity, always specify the `Microsoft::WRL::FtmBase` in `TInterfaces` or `RuntimeClassType::InhibitFtmBase`. If `InhibitFtmBase` and `FtmBase` are both used, the object will be agile. -*TInterfaces*
-The list of interfaces the object implements beyond `IUnknown`, `IInspectable` or other interfaces controlled by [RuntimeClassType](runtimeclasstype-enumeration.md). It also may list other classes to be derived from, notably `Microsoft::WRL::FtmBase` to make the object agile and cause it to implement `IMarshal`. +*`TInterfaces`*\ +The list of interfaces the object implements beyond `IUnknown`, `IInspectable` or other interfaces controlled by [`RuntimeClassType`](runtimeclasstype-enumeration.md). It also may list other classes to be derived from, notably `Microsoft::WRL::FtmBase` to make the object agile and cause it to implement `IMarshal`. ## Members -`RuntimeClassInitialize`
-A function which initializes the object if the `MakeAndInitialize` template function is used to construct the object. It returns S_OK if the object was successfully initialized, or a COM error code if initialization failed. The COM error code is propagated as the return value of `MakeAndInitialize`. Note that the `RuntimeClassInitialize` method is not called if the `Make` template function is used to construct the object. +`RuntimeClassInitialize`\ +A function that initializes the object if the `MakeAndInitialize` function template is used to construct the object. It returns `S_OK` if the object was successfully initialized, or a COM error code if initialization failed. The COM error code is propagated as the return value of `MakeAndInitialize`. The `RuntimeClassInitialize` method isn't called if the `Make` function template is used to construct the object. ### Public Constructors -| Name | Description | -| -------------------------------------------------- | --------------------------------------------------------------- | -| [RuntimeClass::RuntimeClass](#runtimeclass) | Initializes the current instance of the `RuntimeClass` class. | -| [RuntimeClass::~RuntimeClass](#tilde-runtimeclass) | Deinitializes the current instance of the `RuntimeClass` class. | +| Name | Description | +|--|--| +| [`RuntimeClass::RuntimeClass`](#runtimeclass) | Initializes the current instance of the `RuntimeClass` class. | +| [`RuntimeClass::~RuntimeClass`](#tilde-runtimeclass) | Deinitializes the current instance of the `RuntimeClass` class. | ### Public Methods -| Name | Description | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| [RuntimeClass::AddRef](#addref) | Increments the reference count for the current `RuntimeClass` object. | -| [RuntimeClass::DecrementReference](#decrementreference) | Decrements the reference count for the current `RuntimeClass` object. | -| [RuntimeClass::GetIids](#getiids) | Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. | -| [RuntimeClass::GetRuntimeClassName](#getruntimeclassname) | Gets the runtime class name of the current `RuntimeClass` object. | -| [RuntimeClass::GetTrustLevel](#gettrustlevel) | Gets the trust level of the current `RuntimeClass` object. | -| [RuntimeClass::GetWeakReference](#getweakreference) | Gets a pointer to the weak reference object for the current `RuntimeClass` object. | -| [RuntimeClass::InternalAddRef](#internaladdref) | Increments the reference count to the current `RuntimeClass` object. | -| [RuntimeClass::QueryInterface](#queryinterface) | Retrieves a pointer to the specified interface ID. | -| [RuntimeClass::Release](#release) | Performs a COM Release operation on the current `RuntimeClass` object. | +| Name | Description | +|--|--| +| [`RuntimeClass::AddRef`](#addref) | Increments the reference count for the current `RuntimeClass` object. | +| [`RuntimeClass::DecrementReference`](#decrementreference) | Decrements the reference count for the current `RuntimeClass` object. | +| [`RuntimeClass::GetIids`](#getiids) | Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. | +| [`RuntimeClass::GetRuntimeClassName`](#getruntimeclassname) | Gets the runtime class name of the current `RuntimeClass` object. | +| [`RuntimeClass::GetTrustLevel`](#gettrustlevel) | Gets the trust level of the current `RuntimeClass` object. | +| [`RuntimeClass::GetWeakReference`](#getweakreference) | Gets a pointer to the weak reference object for the current `RuntimeClass` object. | +| [`RuntimeClass::InternalAddRef`](#internaladdref) | Increments the reference count to the current `RuntimeClass` object. | +| [`RuntimeClass::QueryInterface`](#queryinterface) | Retrieves a pointer to the specified interface ID. | +| [`RuntimeClass::Release`](#release) | Performs a COM Release operation on the current `RuntimeClass` object. | ## Inheritance Hierarchy -This is an implementation detail. +The hierarchy is an implementation detail. ## Requirements **Header:** implements.h -**Namespace:** Microsoft::WRL +**Namespace:** `Microsoft::WRL` -## RuntimeClass::~RuntimeClass +## `RuntimeClass::~RuntimeClass` Deinitializes the current instance of the `RuntimeClass` class. @@ -72,7 +72,7 @@ Deinitializes the current instance of the `RuntimeClass` class. virtual ~RuntimeClass(); ``` -## RuntimeClass::AddRef +## `RuntimeClass::AddRef` Increments the reference count for the current `RuntimeClass` object. @@ -83,11 +83,11 @@ STDMETHOD_( )(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::DecrementReference +## `RuntimeClass::DecrementReference` Decrements the reference count for the current `RuntimeClass` object. @@ -95,11 +95,11 @@ Decrements the reference count for the current `RuntimeClass` object. ULONG DecrementReference(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::GetIids +## `RuntimeClass::GetIids` Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. @@ -113,17 +113,17 @@ STDMETHOD( ### Parameters -*iidCount*
-When this operation completes, the total number of elements in array *iids*. +*`iidCount`*\ +When this operation completes, the total number of elements in array *`iids`*. -*iids*
+*`iids`*\ When this operation completes, a pointer to an array of interface IDs. -### Return Value +### Return value -S_OK if successful; otherwise, E_OUTOFMEMORY. +`S_OK` if successful; otherwise, `E_OUTOFMEMORY`. -## RuntimeClass::GetRuntimeClassName +## `RuntimeClass::GetRuntimeClassName` Gets the runtime class name of the current `RuntimeClass` object. @@ -135,18 +135,18 @@ STDMETHOD( GetRuntimeClassName )( ### Parameters -*runtimeName*
+*`runtimeName`*\ When this operation completes, the runtime class name. -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. ### Remarks An assert error is emitted if `__WRL_STRICT__` or `__WRL_FORCE_INSPECTABLE_CLASS_MACRO__` isn't defined. -## RuntimeClass::GetTrustLevel +## `RuntimeClass::GetTrustLevel` Gets the trust level of the current `RuntimeClass` object. @@ -158,18 +158,18 @@ STDMETHOD(GetTrustLevel)( ### Parameters -*trustLvl*
+*`trustLvl`*\ When this operation completes, the trust level of the current `RuntimeClass` object. -### Return Value +### Return value -Always S_OK. +Always `S_OK`. ### Remarks An assert error is emitted if `__WRL_STRICT__` or `__WRL_FORCE_INSPECTABLE_CLASS_MACRO__` isn't defined. -## RuntimeClass::GetWeakReference +## `RuntimeClass::GetWeakReference` Gets a pointer to the weak reference object for the current `RuntimeClass` object. @@ -181,14 +181,14 @@ STDMETHOD( ### Parameters -*weakReference*
+*`weakReference`*\ When this operation completes, a pointer to a weak reference object. -### Return Value +### Return value -Always S_OK. +Always `S_OK`. -## RuntimeClass::InternalAddRef +## `RuntimeClass::InternalAddRef` Increments the reference count to the current `RuntimeClass` object. @@ -196,11 +196,11 @@ Increments the reference count to the current `RuntimeClass` object. ULONG InternalAddRef(); ``` -### Return Value +### Return value The resulting reference count. -## RuntimeClass::QueryInterface +## `RuntimeClass::QueryInterface` Retrieves a pointer to the specified interface ID. @@ -214,17 +214,17 @@ STDMETHOD( ### Parameters -*riid*
+*`riid`*\ An interface ID. -*ppvObject*
-When this opereation completes, a pointer to the interface specified by the *riid* parameter. +*`ppvObject`*\ +When this operation completes, a pointer to the interface specified by the *`riid`* parameter. -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::Release +## `RuntimeClass::Release` Performs a COM Release operation on the current `RuntimeClass` object. @@ -235,15 +235,15 @@ STDMETHOD_( )(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. ### Remarks If the reference count becomes zero, the `RuntimeClass` object is deleted. -## RuntimeClass::RuntimeClass +## `RuntimeClass::RuntimeClass` Initializes the current instance of the `RuntimeClass` class. diff --git a/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md b/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md index 9986b362fe..5ec81ffc80 100644 --- a/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md +++ b/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Creating a UWP app using WRL and Media Foundation" title: "Walkthrough: Creating a UWP app using WRL and Media Foundation" +description: "Learn more about: Creating a UWP app using WRL and Media Foundation" ms.date: 04/15/2021 ms.topic: "reference" --- @@ -37,7 +37,7 @@ You can usually use C++/CX to create Windows Runtime components. However, someti - The `namespace` and `runtimeclass` attributes, and the `NTDDI_WIN8` [version](/windows/win32/Midl/version) attribute value are important parts of the MIDL definition for a Media Foundation component that uses WRL. -- [`Microsoft::WRL::RuntimeClass`](runtimeclass-class.md) is the base class for the custom Media Foundation component. The [`Microsoft::WRL::RuntimeClassType::WinRtClassicComMix]`(runtimeclasstype-enumeration.md) enum value, which is provided as a template argument, marks the class for use both as a Windows Runtime class and as a classic COM runtime class. +- [`Microsoft::WRL::RuntimeClass`](runtimeclass-class.md) is the base class for the custom Media Foundation component. The [`Microsoft::WRL::RuntimeClassType::WinRtClassicComMix`](runtimeclasstype-enumeration.md) enum value, which is provided as a template argument, marks the class for use both as a Windows Runtime class and as a classic COM runtime class. - The [`InspectableClass`](inspectableclass-macro.md) macro implements basic COM functionality such as reference counting and the `QueryInterface` method, and sets the runtime class name and trust level. @@ -86,7 +86,7 @@ You can usually use C++/CX to create Windows Runtime components. However, someti [!code-cpp[wrl-media-capture#6](../codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_6.cpp)] -1. In the project’s **Property Pages** dialog box, set the following **Linker** properties. +1. In the project's **Property Pages** dialog box, set the following **Linker** properties. 1. Under **Input**, for the **Module Definition File**, specify `GrayScaleTransform.def`. diff --git a/docs/cppcx/wrl/weakref-class.md b/docs/cppcx/wrl/weakref-class.md index 86e2c5d46a..227bdd1cf2 100644 --- a/docs/cppcx/wrl/weakref-class.md +++ b/docs/cppcx/wrl/weakref-class.md @@ -60,7 +60,7 @@ HRESULT hr = wr.As(&strongRef); // Check the input pointer instead. if(wr == nullptr) { - wprintf(L"Couldn’t get strong ref!"); + wprintf(L"Couldn't get strong ref!"); } ``` diff --git a/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md b/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md index 9630e0cffc..931a152030 100644 --- a/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md +++ b/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md @@ -24,7 +24,7 @@ The Windows Runtime C++ Template Library and C++/CX provide different benefits. - Windows Runtime C++ Template Library adds little abstraction over the Windows Runtime Application Binary Interface (ABI), giving you the ability to control the underlying code to better create or consume Windows Runtime APIs. -- C++/CX represents COM HRESULT values as exceptions. If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions. +- C++/CX represents COM HRESULT values as exceptions. If you've inherited a code base that uses COM, or one that doesn't use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions. > [!NOTE] > The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. In addition, the Windows Runtime C++ Template Library uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. For more info about smart pointers and RAII, see [Smart Pointers](../../cpp/smart-pointers-modern-cpp.md) and [Objects Own Resources (RAII)](../../cpp/object-lifetime-and-resource-management-modern-cpp.md). diff --git a/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md b/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md index 991d9a0c23..bb6cc8a0cd 100644 --- a/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md +++ b/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md @@ -1,16 +1,19 @@ --- description: "Learn more about: Build an OpenGL ES application on Android and iOS" title: "Build an OpenGL ES application on Android and iOS" -ms.date: "10/09/2019" -ms.assetid: 76a67886-df57-4a81-accb-2e3c2eaf607b +ms.date: "06/09/2023" --- + # Build an OpenGL ES application on Android and iOS You can create Visual Studio solutions and projects for iOS apps and Android apps that share common code. This article guides you through a combined solution template. It creates both an iOS app, and an Android Native Activity app. The apps have C++ code in common that uses OpenGL ES to display the same animated rotating cube on each platform. OpenGL ES (OpenGL for Embedded Systems or GLES) is a 2D and 3D graphics API. It's supported on many mobile devices. ## Requirements -Meet all the system requirements to create an OpenGL ES app for iOS and Android. If you haven't already, install the Mobile Development with C++ workload in the Visual Studio Installer. To get the OpenGL ES templates, and to build for iOS, include the optional C++ iOS development tools. To build for Android, install the C++ Android development tools and the required third-party tools: Android NDK, Apache Ant, and Google Android Emulator. +> [!IMPORTANT] +> OpenGL support is no longer available. It was last available in Visual Studio 17.3. + +Here are the system requirements to create an OpenGL ES app for iOS and Android. If you haven't already, install the Mobile Development with C++ workload in the Visual Studio Installer. To get the OpenGL ES templates, and to build for iOS, include the optional C++ iOS development tools. To build for Android, install the C++ Android development tools and the required third-party tools: Android NDK, Apache Ant, and Google Android Emulator. For better emulator performance on Intel platforms, one option is to install the Intel Hardware Accelerated Execution Manager (HAXM). For detailed instructions, see [Install cross-platform mobile development with C++](../cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md). @@ -18,7 +21,7 @@ To build and test the iOS app, you'll need a Mac computer. Set it up according t ## Create a new OpenGLES Application project -In this tutorial, you first create a new OpenGL ES Application project. and then build and run the default app in an Android emulator. Next you build the app for iOS and run the app on an iOS device. +In this tutorial, you first create a new OpenGL ES Application project and then build and run it in an Android emulator. Next you build the app for iOS and run the app on an iOS device. ::: moniker range="msvc-150" @@ -50,7 +53,7 @@ In this tutorial, you first create a new OpenGL ES Application project. and then ::: moniker-end -The new OpenGL ES Application solution includes three library projects and two application projects. The Libraries folder includes a shared code project. And, two platform-specific projects that reference the shared code: +The new OpenGL ES Application solution includes three library projects and two application projects. The Libraries folder includes a shared code project, and two platform-specific projects that reference the shared code: - `MyOpenGLESApp.Android.NativeActivity` contains the references and glue code that implements your app as a Native Activity on Android. The entry points from the glue code are implemented in *main.cpp*, which includes the common shared code in `MyOpenGLESApp.Shared`. Precompiled headers are in *pch.h*. This Native Activity app project is compiled into a shared library (*.so*) file, which is picked up by the `MyOpenGLESApp.Android.Packaging` project. diff --git a/docs/cross-platform/cross-platform-mobile-development-examples.md b/docs/cross-platform/cross-platform-mobile-development-examples.md index c6a20033c9..7eb5ea368a 100644 --- a/docs/cross-platform/cross-platform-mobile-development-examples.md +++ b/docs/cross-platform/cross-platform-mobile-development-examples.md @@ -1,41 +1,28 @@ --- description: "Learn more about: Cross-platform mobile development examples" title: "Cross-platform mobile development examples" -ms.date: "10/17/2019" -ms.assetid: bc384c12-fccc-45d7-9fb9-b90d536aa663 +ms.date: 03/04/2024 --- # Cross-platform mobile development examples -Several of the templates installed by the **Mobile development with C++** workload generate complete examples that you can use to learn from. Additionally, the Windows Dev Center has several example applications that you can download and try out in Visual Studio. +Several of the templates installed by the **Mobile development with C++** workload generate complete examples that you can use to learn from. Additionally, here are some example applications that you can download and try out in Visual Studio. -- [hello-jni Android Application Sample](https://code.msdn.microsoft.com/hello-jni-Android-790ab73d) +- [hello-jni Android Application Sample](https://github.com/android/ndk-samples/tree/master/hello-jni) This sample is a port of the Android NDK hello-jni application. The sample demonstrates an end-to-end Java Native Interface "Hello World" app. It loads a string from a native method implemented in a shared library, and then displays it in the app. -- [hello-gl2 Android Application Sample](https://code.msdn.microsoft.com/hello-gl2-Android-3b61896c) +- [TwoLibs Android Library Sample](https://github.com/microsoftarchive/msdn-code-gallery-community-s-z/tree/master/TwoLibs%20Android%20Library%20Sample) - This sample is a port of the Android NDK hello-gl2 application. The sample demonstrates an end-to-end Java Native Interface Android OpenGL app. It renders a triangle using the OpenGL ES 2.0 shader APIs. + This sample is a port of the Android NDK TwoLibs sample. It uses both a dynamically loaded shared library and a static C++ Android native library that implements a method called from a Java Native Interface app. This sample is a good starting point for developers to understand how to use static/dynamic shared libraries to build an end-to-end JNI Android application with Visual Studio. -- [Bitmap Plasma Android Application Sample](https://code.msdn.microsoft.com/Bitmap-Plasma-Android-77ae296a) - - This sample is a port of the Android NDK Bitmap Plasma application. The sample demonstrates an end-to-end Java Native Interface Android OpenGL ES 2.0 application. It demonstrates direct manipulation of Android bitmap pixel buffers to generate a plasma effect. - -- [TwoLibs Android Library Sample](https://code.msdn.microsoft.com/TwoLibs-Android-Library-6396e5c4) - - This sample is a port of the Android NDK TwoLibs sample. It uses both a dynamically loaded shared library, and a static C++ Android native library, that implements a method called from a Java Native Interface app. This sample is a good starting point for developers to understand how to use static/dynamic shared libraries to build an end-to-end JNI Android application with Visual Studio. - -- [Tea Pot Android Application Sample](https://code.msdn.microsoft.com/Tea-Pot-Android-Application-e7c05d73) - - This sample is a port of the Android NDK TeaPot application. The sample demonstrates an end-to-end Java Native Interface Android OpenGL ES 2.0 application. - -- [MoreTeaPots Android Application Sample](https://code.msdn.microsoft.com/MoreTeaPots-Android-a9bd8549) - - This sample is a port of the Android NDK MoreTeaPots application. The sample demonstrates an end-to-end Java Native Interface Android OpenGL application. - -- [test-libstdcpp Android Library Sample](https://code.msdn.microsoft.com/test-libstdcpp-Android-00b548f5) +- [test-libstdcpp Android Library Sample](https://github.com/microsoftarchive/msdn-code-gallery-community-s-z/tree/master/test-libstdcpp%20Android%20Library%20Sample) This sample is a port of the Android NDK test-libstdc++ sample, specifically for use with Visual Studio. This sample is a good starting point for developers to understand how to use the Standard Library. To open one of the examples in Visual Studio, download the zip file and open the **Properties** page of the downloaded file in Explorer. Choose the **Unblock** button then choose **OK**. Extract the contents of the zip file to a convenient location, then open the C++ folder in the extracted sample and open the solution file. To build the sample, press **F7**, or on the menu bar, choose **Build**, **Build Solution**. + +## See also + +[Android NDK samples](https://github.com/android/ndk-samples/tree/master/) diff --git a/docs/cross-platform/index.yml b/docs/cross-platform/index.yml index 60d95e09af..0fb5f94c59 100644 --- a/docs/cross-platform/index.yml +++ b/docs/cross-platform/index.yml @@ -6,8 +6,8 @@ metadata: title: Mobile development with C++ documentation description: Create native C++ apps for iOS, Android, and Windows devices with Visual Studio. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 05/26/2020 ms.custom: intro-landing-hub @@ -29,8 +29,6 @@ landingContent: url: visual-cpp-for-cross-platform-mobile-development.md - linkListType: tutorial links: - - text: Build an OpenGL ES application on Android and iOS - url: build-an-opengl-es-application-on-android-and-ios.md - text: Create an Android Native Activity App url: create-an-android-native-activity-app.md - linkListType: learn diff --git a/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md b/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md index 34ad0a4084..84bc01c589 100644 --- a/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md +++ b/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md @@ -1,22 +1,22 @@ --- description: "Learn more about: Install and configure tools to build using iOS" title: "Install and configure tools to build using iOS" -ms.date: "10/17/2019" +ms.date: 12/18/2022 ms.assetid: d0c311c9-9eb9-42c5-ba07-25604362cd28 ms.custom: intro-installation --- # Install and configure tools to build using iOS -You can use Visual Studio with the cross-platform **Mobile development with C++** tools to edit, debug, and deploy iOS code to the iOS Simulator or to an iOS device. But, because of licensing restrictions, the code must be built and run remotely on a Mac. To build and run iOS apps using Visual Studio, you need to set up and configure the remote agent, [vcremote](https://www.npmjs.com/package/vcremote), on your Mac. The remote agent handles build requests from Visual Studio and runs the app on an iOS device connected to the Mac, or in the iOS Simulator on the Mac. +You can use Visual Studio with the cross-platform **Mobile development with C++** tools to edit, debug, and deploy iOS code to the iOS Simulator or to an iOS device. But, because of licensing restrictions, the code must be built and run remotely on a Mac. To build and run iOS apps using Visual Studio, you need to set up and configure the remote agent, [vcremote](https://www.npmjs.com/package/vcremote), on your Mac. The vcremote remote agent handles build requests from Visual Studio and runs the app on an iOS device connected to the Mac, or in the iOS Simulator on the Mac. > [!NOTE] > For information on using cloud-hosted Mac services instead of a Mac, see [Configure Visual Studio to connect to your cloud hosted Mac](/visualstudio/cross-platform/tools-for-cordova/tips-workarounds/host-a-mac-in-the-cloud?view=toolsforcordova-2017&preserve-view=true#configure-visual-studio-to-connect-to-your-cloud-hosted-mac). The instructions are for building using Visual Studio Tools for Apache Cordova. To use the instructions to build using C++, substitute `vcremote` for `remotebuild`. -Once you have installed the tools to build using iOS, refer to this article for ways to quickly configure and update the remote agent for iOS development in Visual Studio and on your Mac. +Once you've installed the tools to build using iOS, refer to this article again. It describes ways to quickly configure and update vcremote for iOS development in Visual Studio and on your Mac. ## Prerequisites -To install and use the remote agent to develop code for iOS, you must first have these prerequisites: +To install and use the vcremote remote agent to develop code for iOS, you must first have these prerequisites: - A Mac computer running macOS Mojave version 10.14 or later @@ -26,7 +26,7 @@ To install and use the remote agent to develop code for iOS, you must first have You can get a free account that allows sideloading apps to an iOS device for testing only but not for distribution. -- [Xcode](https://developer.apple.com/xcode/downloads/) version 10.2.1 or later +- [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12/) version 10.2.1 or later Xcode can be downloaded from the App Store. @@ -42,25 +42,25 @@ To install and use the remote agent to develop code for iOS, you must first have For detailed information on signing requirements, see [What is app signing](https://help.apple.com/xcode/mac/current/#/dev3a05256b8). -- If you are using an iOS device for development, a provisioning Profile configured in Xcode for your device +- If you're using an iOS device for development, a provisioning Profile configured in Xcode for your device - Xcode provides automatic signing where it creates signing certificates for you as needed. For detailed information about Xcode automatic signing see [automatic signing](https://help.apple.com/xcode/mac/current/#/dev80cc24546). + Xcode provides automatic signing, where it creates signing certificates for you as needed. For detailed information about Xcode automatic signing, see [automatic signing](https://help.apple.com/xcode/mac/current/#/dev80cc24546). If you want to do manual signing, you need to create a provisioning Profile for your app. For detailed information on creating provisioning Profiles, see [Create a development provisioning profile](https://help.apple.com/developer-account/#/devf2eb157f8). -- [Node.js](https://nodejs.org/) version 12.14.1 and npm version 6.13.4 +- [Node.js](https://nodejs.org/dist/v18.12.1/node-v18.12.1.pkg) version 18.12.1 and npm version 8.19.2 - Install version 12.14.1 of Node.js on your Mac. If you install the Node.js package, it should come with npm version 6.13.4. Other versions of Node.js and npm may not support some modules used in the remote agent `vcremote`, which can cause `vcremote` installation to fail. We recommend you install Node.js by using a package manager such as [Node Version Manager](https://nodejs.org/en/download/package-manager/#nvm). Avoid using the command `sudo` to install Node.js, as some modules can fail to install when using `sudo`. + Install version 18.12.1 of Node.js on your Mac. If you install the Node.js package, it should come with npm version 8.19.2. Other versions of Node.js and npm may not support some modules used in vcremote, which can cause vcremote installation to fail. We recommend you install Node.js by using a package manager such as [Node Version Manager](https://nodejs.org/en/download/package-manager/#nvm). Avoid using the command `sudo` to install Node.js, as some modules can fail to install when using sudo. -## Install the remote agent for iOS +## Install vcremote for iOS -When you install the Mobile development with C++ workload, Visual Studio can communicate with [vcremote](https://www.npmjs.com/package/vcremote), a remote agent running on your Mac to transfer files, build and run your iOS app, and send debugging commands. +When you install the Mobile development with C++ workload, Visual Studio can communicate with the [vcremote](https://www.npmjs.com/package/vcremote) remote agent running on your Mac to transfer files, build and run your iOS app, and send debugging commands. -Before you install the remote agent, make sure you have satisfied the [Prerequisites](#prerequisites) and completed the installation steps in [Install cross-platform mobile development with C++](../cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md#install-the-tools). +Before you install vcremote, make sure you've satisfied the [Prerequisites](#prerequisites) and completed the installation steps in [Install cross-platform mobile development with C++](../cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md#install-the-tools). -### To download and install the remote agent +### To download and install vcremote -- From the Terminal app on your Mac, verify that the Node.js version currently in use is the required version 12.14.1. To verify the version, run the command: +- From the Terminal app on your Mac, verify that the Node.js version currently in use is the required version 18.12.1. To verify the version, run the command: `node -v` @@ -75,35 +75,44 @@ Before you install the remote agent, make sure you have satisfied the [Prerequis During the installation, `vcremote` is installed and developer mode is activated on your Mac. [Homebrew](https://brew.sh/) and two npm packages, `vcremote-lib` and `vcremote-utils`, are also installed. When installation completes, it's safe to ignore any warnings about skipped optional dependencies. > [!NOTE] - > To install Homebrew, you must have sudo (administrator) access. If you need to install `vcremote` without sudo, you can install Homebrew manually in a usr/local location and add its bin folder to your path. For more information, see the [Homebrew documentation](https://github.com/Homebrew/homebrew/wiki/Installation). To manually enable developer mode, enter this command in the Terminal app: `DevToolsSecurity -enable` + > To install Homebrew, you must have sudo (administrator) access. If you need to install vcremote without sudo, you can install Homebrew manually in a `usr/local` location and add its `bin` folder to your path. For more information, see the [Homebrew documentation](https://github.com/Homebrew/homebrew/wiki/Installation). To manually enable developer mode, enter this command in the Terminal app: `DevToolsSecurity -enable` -If you update to a new version of Visual Studio, you must update to the current version of the remote agent as well. To update the remote agent, repeat the steps to download and install the remote agent. +If you update to a new version of Visual Studio, you must update to the current version of vcremote as well. To update vcremote, repeat the steps to download and install the remote agent. -## Start the remote agent +## Start vcremote -The remote agent must be running for Visual Studio to build and run your iOS code. Visual Studio must be paired with the remote agent before it can communicate. By default, the remote agent runs in secured connection mode, which requires a PIN to pair with Visual Studio. +The vcremote remote agent must be running for Visual Studio to build and run your iOS code. Visual Studio must be paired with vcremote before it can communicate. By default, vcremote runs in *secured connection mode*, which requires the transferring of client and server certificates between the Visual Studio and Mac machines. -### To start the remote agent + > [!NOTE] + > Version 1.0.19 or later of vcremote requires at least Visual Studio 2022 version 17.5.0 Preview 1 or later. If you're using Visual Studio 2022 version 17.4 or an earlier version, install vcremote version 1.0.17. + +### To start vcremote - From the Terminal app on your Mac, enter: `vcremote` - This command starts the remote agent with a default build directory of `~/vcremote`. For additional configuration options, see [Configure the remote agent on the Mac](#ConfigureMac). + This command starts the remote agent with a default build directory of *`~/vcremote`*. For more configuration options, see [Configure vcremote on the Mac](#ConfigureMac). + +The first time you start vcremote, and every time you create a new server certificate, you're provided with the required information to configure the connection in Visual Studio. The information includes the host name and the port. If you intend to configure the remote agent in Visual Studio using the host name, ping the Mac from Windows using the host name to verify that it's reachable. Otherwise, you may need to use the IP address instead. + +You can use the remote agent in unsecured mode. In unsecured mode, the remote agent can be paired to Visual Studio using a simple HTTP connection that doesn't encrypt data. Use unsecured mode at your own risk. We recommend you use a secure mode to connect: + +**Visual Studio 2022 version 17.5 and later with vcremote 1.0.19 and later:** -The first time you start the agent, and every time you create a new client certificate, you are provided with the required information to configure the agent in Visual Studio, including the host name, the port, and the PIN. +In vcremote 1.0.19 and later, vcremote reports the path to a *`server-cert.pem`* certificate file, which must be uploaded to Visual Studio. -![Use vcremote to generate a secure PIN.](../cross-platform/media/cppmdd-vcremote-generateclientcert.png "Use vcremote to generate a secure PIN") +**Visual Studio 2022 version 17.4 and earlier versions with vcremote 1.0.17 and earlier:** -If you intend to configure the remote agent in Visual Studio using the host name, ping the Mac from Windows using the host name to verify that it is reachable. Otherwise, you may need to use the IP address instead. +Version 1.0.17 and older versions of vcremote generate a PIN for secure communication with versions of Visual Studio through Visual Studio 2022 version 17.4. -The generated PIN is for one time use, and is only valid for a limited time. If you do not pair Visual Studio with the remote agent before the time expires, you will need to generate a new PIN. For more information, see [Generate a new security PIN](#GeneratePIN). +:::image type="content" source="media/cppmdd-vcremote-generateclientcert.png" alt-text="Screenshot of the Mac Terminal window that shows the host name, port, and PIN reported when VC remote is started."::: -You can use the remote agent in unsecured mode. In unsecured mode, the remote agent can be paired to Visual Studio without a PIN. +The generated PIN is for one time use, and is only valid for a limited time. If you don't pair Visual Studio with the remote agent before the time expires, you'll need to generate a new PIN. For more information, see [Generate a new security PIN](#GeneratePIN). #### To disable secured connection mode -- To disable secured connection mode in `vcremote`, enter this command in the Terminal app on your Mac: +- To disable secured connection mode in vcremote, enter this command in the Terminal app on your Mac: `vcremote --secure false` @@ -113,27 +122,61 @@ You can use the remote agent in unsecured mode. In unsecured mode, the remote ag `vcremote --secure true` -Once you have started the remote agent, you can use it from Visual Studio until you stop it. +Once you've started the remote agent, you can use it from Visual Studio until you stop it. #### To stop the remote agent -- In the Terminal window `vcremote` is running in, enter **Control**+**C**. +- In the Terminal window vcremote is running in, enter **Control**+**C**. + +## Configure vcremote in Visual Studio + +To connect to the vcremote remote agent from Visual Studio, you must specify the remote configuration in the Visual Studio options. Visual Studio uses the same information to connect to the remote agent on your Mac each time you use it. You don't need to pair Visual Studio with the remote agent again unless you generate a new security certificate on your Mac, or its hostname or IP address changes. + +### To configure vcremote from Visual Studio 2022 version 17.5 and later + +1. If the agent isn't already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running vcremote for Visual Studio to successfully pair, connect, and build your project. + +1. On your Mac, get the host name or IP address of your Mac. + + You can get the IP address by using the **ifconfig** command in a Terminal window. Use the `inet` address listed under the active network interface. + +1. On the Visual Studio menu bar, choose **Tools** > **Options**. + +1. In the **Options** dialog box, expand **Cross Platform** > **C++** > **iOS**. + +1. In the **Host Name** and **Port** fields, enter the values specified by the remote agent when you started it. The host name can be the DNS name or IP address of your Mac. The default port is 3030. + + > [!NOTE] + > If you can't ping the Mac using the host name, you may need to use the IP address. + +1. If you use the remote agent in the default secured connection mode, check the **Secure** checkbox, and transfer the *`server-cert.pem`* file from the Mac to Visual Studio for uploading. Next, choose the **Generate** button to generate a new *`client-cert.pem`* file, which should appear on the desktop. Then, transfer the client certificate to the Mac under *`/vcremote/certs/Authorized-Clients`*. (You may transfer multiple client certificate files to this directory, so multiple authorized Visual Studio machines can send requests to this Mac.) -## Configure the remote agent in Visual Studio + > [!NOTE] + > If you're using a USB drive to transfer certificates, delete the certificates from the USB drive after the transfer is complete. + +1. Choose **Pair** to enable the pairing. + + :::image type="content" source="media/cppmdd-options-ios-new.png" alt-text="Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, and the Remote Root values are set."::: + + The pairing persists until you change the host name, port, or generate a new server or client certificate. If you change the host name or port in the **Options** dialog box, you can choose the **Revert** button to undo the change and revert to the previous pairing. -To connect to the remote agent from Visual Studio, you must specify the remote configuration in the Visual Studio options. + If the pairing doesn't succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). Follow the steps to [Generate a new server certificate](#GenerateServerCert) and [Generate a new client certificate](#GenerateClientCert). If you're using the host name of your Mac, try using the IP address in the **Host Name** field instead. -### To configure the remote agent from Visual Studio +1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*`~`*) directory on the Mac. By default, the remote agent uses *`/Users//vcremote`* as the remote root. -1. If the agent is not already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running `vcremote` for Visual Studio to successfully pair, connect, and build your project. +1. Choose **OK** to save the remote pairing connection settings. + +### To configure vcremote from versions before Visual Studio 2022 version 17.5 + +1. If the agent isn't already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running vcremote for Visual Studio to successfully pair, connect, and build your project. 1. On your Mac, get the host name or IP address of your Mac. - You can get the IP address by using the **ifconfig** command in a Terminal window. Use the inet address listed under the active network interface. + You can get the IP address by using the **ifconfig** command in a Terminal window. Use the `inet` address listed under the active network interface. -1. On the Visual Studio menu bar, choose **Tools**, **Options**. +1. On the Visual Studio menu bar, choose **Tools** > **Options**. -1. In the **Options** dialog box, expand **Cross Platform**, **C++**, **iOS**. +1. In the **Options** dialog box, expand **Cross Platform** > **C++** > **iOS**. 1. In the **Host Name** and **Port** fields, enter the values specified by the remote agent when you started it. The host name can be the DNS name or IP address of your Mac. The default port is 3030. @@ -144,21 +187,21 @@ To connect to the remote agent from Visual Studio, you must specify the remote c 1. Choose **Pair** to enable the pairing. - ![Configure vcremote connection for iOS builds.](../cross-platform/media/cppmdd-options-ios.png "Configure vcremote connection for iOS builds") + :::image type="content" source="media/cppmdd-options-ios-old.png" alt-text="Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, the pin, and the Remote Root values are set."::: The pairing persists until you change the host name or port. If you change the host name or port in the **Options** dialog box, to undo the change, choose the **Revert** button to revert to the previous pairing. - If the pairing does not succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). If too much time has passed since the remote agent PIN was generated, follow the steps in [Generate a new security PIN](#GeneratePIN) on the Mac and then try again. If you are using the host name of your Mac, try using the IP address in the **Host Name** field instead. + If the pairing doesn't succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). If too much time has passed since the remote agent PIN was generated, follow the steps in [Generate a new security PIN](#GeneratePIN). Then try again. If you're using the host name of your Mac, try using the IP address in the **Host Name** field instead. -1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*~*) directory on the Mac. By default, the remote agent uses `/Users//vcremote` as the remote root. +1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*`~`*) directory on the Mac. By default, the remote agent uses `/Users//vcremote` as the remote root. 1. Choose **OK** to save the remote pairing connection settings. -Visual Studio uses the same information to connect to the remote agent on your Mac each time you use it. You do not need to pair Visual Studio with the remote agent again unless you generate a new security certificate on your Mac, or its hostname or IP address changes. - ## Generate a new security PIN -When you start the remote agent the first time, the generated PIN is valid for a limited amount of time—by default, 10 minutes. If you don't pair Visual Studio to the remote agent before the time expires, you will need to generate a new PIN. +**Applies to: Visual Studio 2022 version 17.4 and earlier versions, using vcremote version 1.0.17 and earlier.** + +When you start the remote agent the first time, the generated PIN is valid for a limited amount of time—by default, 10 minutes. If you don't pair Visual Studio to the remote agent before the time expires, you'll need to generate a new PIN. ### To generate a new PIN @@ -170,7 +213,15 @@ When you start the remote agent the first time, the generated PIN is valid for a The remote agent generates a new temporary PIN. To pair Visual Studio by using the new PIN, repeat the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). -## Generate a new server certificate +## Generate a new client certificate + +**Applies to: Visual Studio 2022 version 17.5 and later versions, using vcremote version 1.0.19 and later.** + +When you pair on Visual Studio, you'll generate a new *`client-cert.pem`* file. Transfer the certificate file to the Mac build machine under *`/vcremote/certs/Authorized-Clients`*. This certificate allows the Mac to authorize requests that come from your Visual Studio machine. + +## Generate a new server certificate + +**Applies to: Visual Studio 2022 version 17.5 and later versions, using vcremote version 1.0.19 and later.** For security purposes, the server certificates that pair Visual Studio with the remote agent are tied to the IP address or host name of your Mac. If these values change, you must generate a new server certificate, and then reconfigure Visual Studio with the new values. @@ -184,15 +235,9 @@ For security purposes, the server certificates that pair Visual Studio with the 1. When prompted for confirmation, enter `Y`. -1. Enter this command in the Terminal app: - - `vcremote generateClientCert` - - This command generates a new temporary PIN. - -1. To pair Visual Studio by using the new PIN, repeat the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). +1. To pair Visual Studio with the Mac, transfer the newly generated *`server-cert.pem`* file from the Mac and upload it to Visual Studio, repeating the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). -## Configure the remote agent on the Mac +## Configure vcremote on the Mac You can configure the remote agent using various command-line options. For example, you can specify the port to listen for build requests and specify the maximum number of builds to maintain on the file system. By default, the limit is 10 builds. The remote agent will remove builds that exceed the maximum on shutdown. @@ -206,31 +251,31 @@ You can configure the remote agent using various command-line options. For examp `vcremote --secure false` - When you use this option, clear the **Secure** checkbox and leave the **Pin** field blank when configuring the agent in Visual Studio. + When you use this option, clear the **Secure** checkbox. - To specify a location for remote agent files, enter: `vcremote --serverDir directory_path` - where *directory_path* is the location on your Mac to place log files, builds, and server certificates. By default, this location is `/Users//vcremote`. Builds are organized by build number in this location. + Replace `directory_path` with the location on your Mac to place log files, builds, and server certificates. By default, this location is *`/Users//vcremote`*. Builds are organized by build number in this location. -- To use a background process to capture `stdout` and `stderr` to a file named server.log, enter: +- To use a background process to capture `stdout` and `stderr` to a file named *`server.log`*, enter: `vcremote > server.log 2>&1 &` - The server.log file can assist in troubleshooting build issues. + The *`server.log`* file can help troubleshooting build issues. - To run the agent by using a configuration file instead of command-line parameters, enter: `vcremote --config config_file_path` - where *config_file_path* is the path to a configuration file in JSON format. The startup options and their values must not include dashes. + Replace `config_file_path` with the path to a configuration file in JSON format. The startup options and their values must not include dashes. ## Troubleshoot the remote agent ### Debugging on an iOS device -If debugging on an iOS device does not work, there could be issues with the tool [ideviceinstaller](https://github.com/libimobiledevice/ideviceinstaller), which is used to communicate with an iOS device. This tool is typically installed from Homebrew during the installation of `vcremote`. Follow the steps below as a workaround. +If debugging on an iOS device doesn't work, there could be issues with the [`ideviceinstaller`](https://github.com/libimobiledevice/ideviceinstaller) tool, which is used to communicate with an iOS device. This tool is typically installed from Homebrew during the installation of `vcremote`. Follow the next steps as a workaround: Open the Terminal app and update `ideviceinstaller` and its dependencies by running the following commands in order: @@ -264,7 +309,7 @@ Verify that `ideviceinstaller` can communicate with the device by trying to list `ideviceinstaller -l` -If `ideviceinstaller` errors that it cannot access the folder `/var/db/lockdown`, change the privilege on the folder with: +If `ideviceinstaller` reports an error that it can't access the folder `/var/db/lockdown`, change the privilege on the folder using this command: `sudo chmod 777 /var/db/lockdown` diff --git a/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md b/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md index 5d610defde..200c128cb3 100644 --- a/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md +++ b/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md @@ -2,12 +2,11 @@ description: "Learn more about: Install cross-platform mobile development with C++" title: "Install cross-platform mobile development with C++" ms.date: "10/17/2019" -ms.assetid: aaea6b8d-55eb-4427-8185-c050f855c257 ms.custom: intro-installation --- # Install cross-platform mobile development with C++ -You can use C++ in Visual Studio to build Windows Desktop apps, Universal Windows Platform (UWP) apps, and Linux apps. And now, you can build C++ apps for Android and iOS. The **Mobile development with C++** workload is an installable set of components in Visual Studio. It includes cross-platform iOS, Android, and UWP Visual Studio templates. The workload installs the cross-platform tools and SDKs you need to get started quickly. You won't have to locate, download, and configure them yourself. You can use these tools in Visual Studio to easily create, edit, debug, and test your cross-platform projects. +You can use C++ in Visual Studio to build Windows Desktop apps, Universal Windows Platform (UWP) apps, and Linux apps. And now, you can build C++ apps for Android and iOS. The **Mobile development with C++** workload is an installable set of components in Visual Studio. It includes cross-platform iOS, Android, and UWP Visual Studio templates. The workload installs the cross-platform tools and SDKs you need to get started quickly. You don't have to locate, download, and configure them yourself. You can use these tools in Visual Studio to easily create, edit, debug, and test your cross-platform projects. This article describes how to install the tools and third-party software required to develop cross-platform apps in C++ using Visual Studio. For an overview, see [Visual C++ cross-platform mobile](https://visualstudio.microsoft.com/vs/features/cplusplus-mdd/) @@ -30,9 +29,9 @@ This article describes how to install the tools and third-party software require ::: moniker-end -To build apps for specific device platforms, there are some additional requirements: +To build apps for specific device platforms, there are some other requirements: -- The x86 Android emulators that come with the Android SDK work best on computers that can use hardware acceleration, such as the Intel Hardware Accelerated Execution Manager (HAXM). For more information, see [Hardware acceleration for emulator performance (Hyper-V & HAXM)](/xamarin/android/get-started/installation/android-emulator/hardware-acceleration?tabs=vswin&pivots=windows). +- The x86 Android emulators that come with the Android SDK work best on computers that can use hardware acceleration. For more information, see [How to enable hardware acceleration with Android emulators (Hyper-V & AEHD)](/dotnet/maui/android/emulator/hardware-acceleration). - Building code for iOS requires an Apple ID, an iOS Developer Program account, and a Mac computer that can run [Xcode](https://developer.apple.com/xcode/) version 10.2 or later on OS X Mavericks (version 10.9) or later versions. For a link to installation steps, see [Install tools for iOS](#install-tools-for-ios). @@ -62,13 +61,13 @@ The Visual Studio Installer includes a **Mobile development with C++** workload. 1. Run the **Visual Studio Installer** from the **Start** menu. -1. If you've already installed Visual Studio, choose the **Modify** button for the installed version of Visual Studio you'd like to modify. Otherwise, choose **Install** to install Visual Studio. +1. If you've installed Visual Studio, choose the **Modify** button for the installed version of Visual Studio you'd like to modify. Otherwise, choose **Install** to install Visual Studio. 1. With the **Workloads** tab selected, scroll down and select the **Mobile development with C++** workload in the Visual Studio Installer. When this workload is selected, other required components for C++ development are also selected. You can also choose other workloads and individual components to install at the same time. To build cross-platform code that also targets UWP, select the **Universal Windows Platform development** workload. -1. In the **Installation details** pane, expand **Mobile development with C++**. In the **Optional** section, you can choose additional versions of the NDK, the Google Android Emulator, the Intel Hardware Accelerated Execution Manager, and the IncrediBuild build acceleration tool. +1. In the **Installation details** pane, expand **Mobile development with C++**. In the **Optional** section, you can choose other versions of the NDK, the Google Android Emulator, the Intel Hardware Accelerated Execution Manager, and the IncrediBuild build acceleration tool. -1. By default, one or more Android SDK setup components are included by the workload. Additional versions of the Android SDK are available. To add one to your installation, choose the **Individual components** tab, then scroll down to the **SDKs, libraries, and frameworks** section to make your selection. +1. By default, one or more Android SDK setup components are included by the workload. More versions of the Android SDK are available. To add one to your installation, choose the **Individual components** tab, then scroll down to the **SDKs, libraries, and frameworks** section to make your selection. 1. Choose the **Modify** or **Install** button to install the **Mobile development with C++** workload and your other selected workloads and optional components. @@ -87,11 +86,11 @@ You can use Visual Studio to edit, debug, and deploy iOS code to the iOS Simulat You don't have to install all the third-party dependencies when you install the **Mobile development with C++** workload (or in Visual Studio 2015, the Visual C++ Mobile Development option). Install them later by using the steps in [Install the tools](#install-the-tools). The Visual Studio Installer is updated regularly to install the latest third-party components. Use it to install updated SDKs and NDKs. You can also install or update them independently of Visual Studio. -You can run the SDK Manager app in the Android SDK directory again to update the SDK. And, to install optional tools and additional API levels. Updates may fail to install unless you use **Run as administrator** to run the SDK Manager app. If you have problems building an Android app, check the SDK Manager for updates to your installed SDKs. +You can run the SDK Manager app in the Android SDK directory again to update the SDK. And, to install optional tools and other API levels. Updates may fail to install unless you use **Run as administrator** to run the SDK Manager app. If you have problems building an Android app, check the SDK Manager for updates to your installed SDKs. -To use some of the Android SDK emulators, you may need to set up hardware acceleration. For more information, see [Hardware acceleration for emulator performance (Hyper-V & HAXM)](/xamarin/android/get-started/installation/android-emulator/hardware-acceleration?tabs=vswin). +To use some of the Android SDK emulators, you may need to set up hardware acceleration. For more information, see [How to enable hardware acceleration with Android emulators (Hyper-V & AEHD)](/dotnet/maui/android/emulator/hardware-acceleration). -In most cases, Visual Studio can detect the configurations for the third-party software you've installed. It maintains the installation paths in internal environment variables. You can override the default paths of these cross-platform development tools in the Visual Studio IDE. +In most cases, Visual Studio can detect the configurations for installed third-party software. It maintains the installation paths in internal environment variables. You can override the default paths of these cross-platform development tools in the Visual Studio IDE. ### To set the paths for third-party tools diff --git a/docs/cross-platform/media/cppmdd-options-ios-new.png b/docs/cross-platform/media/cppmdd-options-ios-new.png new file mode 100644 index 0000000000..4a79c5d200 Binary files /dev/null and b/docs/cross-platform/media/cppmdd-options-ios-new.png differ diff --git a/docs/cross-platform/media/cppmdd-options-ios.png b/docs/cross-platform/media/cppmdd-options-ios-old.png similarity index 100% rename from docs/cross-platform/media/cppmdd-options-ios.png rename to docs/cross-platform/media/cppmdd-options-ios-old.png diff --git a/docs/data/changes-you-might-make-to-the-default-code-mfc-data-access.md b/docs/data/changes-you-might-make-to-the-default-code-mfc-data-access.md index e2555def69..d524c7ae40 100644 --- a/docs/data/changes-you-might-make-to-the-default-code-mfc-data-access.md +++ b/docs/data/changes-you-might-make-to-the-default-code-mfc-data-access.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Changes You Might Make to the Default Code (MFC Data Access)" title: "Changes You Might Make to the Default Code (MFC Data Access)" +description: "Learn more about: Changes You Might Make to the Default Code (MFC Data Access)" ms.date: "11/04/2016" helpviewer_keywords: ["record views [C++], customizing default code"] -ms.assetid: 9992ed37-a6bf-45a5-a572-5c14e42b6628 --- # Changes You Might Make to the Default Code (MFC Data Access) @@ -13,7 +12,7 @@ The [MFC Application Wizard](../mfc/reference/database-support-mfc-application-w - Parameterize the recordset. Specify the actual run-time parameter value after the filter. For more information, see [Recordset: Parameterizing a Recordset (ODBC)](../data/odbc/recordset-parameterizing-a-recordset-odbc.md) -- Pass a customized SQL string to the [Open](../mfc/reference/crecordset-class.md#open) member function. For a discussion of what you can accomplish with this technique , see [SQL: Customizing Your Recordset's SQL Statement (ODBC)](../data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md). +- Pass a customized SQL string to the [Open](../mfc/reference/crecordset-class.md#open) member function. For a discussion of what you can accomplish with this technique, see [SQL: Customizing Your Recordset's SQL Statement (ODBC)](../data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md). ## See also diff --git a/docs/data/data-access-in-cpp.md b/docs/data/data-access-in-cpp.md index 9ac4a72755..30bf416352 100644 --- a/docs/data/data-access-in-cpp.md +++ b/docs/data/data-access-in-cpp.md @@ -31,7 +31,7 @@ Connect to Azure SQL Database from C or C++ applications. [Azure Storage](/azure/storage/common/storage-introduction) is a cloud storage solution for modern applications that rely on durability, availability, and scalability to meet the needs of their customers. Connect to Azure Storage from C++ by using the Azure Storage Client Library for C++. [ODBC Driver for SQL Server](/sql/connect/odbc/microsoft-odbc-driver-for-sql-server)
-The latest ODBC driver provides robust data access to Microsoft SQL Server and Microsoft Azure SQL Database for C/C++ based applications. Provides support for features including always encrypted, Azure Active Directory, and AlwaysOn Availability Groups. Also available for MacOS and Linux. +The latest ODBC driver provides robust data access to Microsoft SQL Server and Microsoft Azure SQL Database for C/C++ based applications. Provides support for features including always encrypted, Azure Active Directory, and AlwaysOn Availability Groups. Also available for macOS and Linux. [OLE DB Driver for SQL Server](/sql/connect/oledb/oledb-driver-for-sql-server)
The latest OLE DB driver is a stand-alone data access application programming interface (API) that supports Microsoft SQL Server and Microsoft Azure SQL Database. diff --git a/docs/data/installing-database-support-mfc-atl.md b/docs/data/installing-database-support-mfc-atl.md index d4a6c7cfbd..047eee85fe 100644 --- a/docs/data/installing-database-support-mfc-atl.md +++ b/docs/data/installing-database-support-mfc-atl.md @@ -8,7 +8,7 @@ ms.custom: intro-installation --- # Installing Database Support (MFC/ATL) -Visual C++ does not include any database products. To +Visual C++ does not include any database products. ## See also diff --git a/docs/data/odbc/odbc-and-mfc.md b/docs/data/odbc/odbc-and-mfc.md index 5f25751635..8a647cef02 100644 --- a/docs/data/odbc/odbc-and-mfc.md +++ b/docs/data/odbc/odbc-and-mfc.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: ODBC and MFC" title: "ODBC and MFC" +description: "Learn more about: ODBC and MFC" ms.date: "11/04/2016" helpviewer_keywords: ["ODBC [C++], MFC", "connections [C++], databases", "connections [C++], data source", "databases [C++], connecting to", "data sources [C++], connecting to", "MFC [C++], ODBC and", "database connections [C++], MFC ODBC classes"] -ms.assetid: 98f02fd7-1235-437b-89a9-edfd0fc797f7 --- # ODBC and MFC > [!NOTE] -> To use the MFC database classes, you must have the appropriate ODBC driver for your data source. The lastest Microsoft ODBC driver for SQL Server is [Microsoft ODBC Driver 13 for SQL Server](https://www.microsoft.com/download/details.aspx?id=50420). Most database vendors provide an ODBC driver for Windows. +> To use the MFC database classes, you must have the appropriate ODBC driver for your data source. The lastest Microsoft ODBC driver for SQL Server is [Microsoft ODBC Driver 18 for SQL Server](/sql/connect/odbc/download-odbc-driver-for-sql-server). Most database vendors provide an ODBC driver for Windows. This topic introduces the main concepts of the Microsoft Foundation Classes (MFC) library's ODBC-based database classes and provides an overview of how the classes work together. For more information about ODBC and MFC, see the following topics: diff --git a/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md b/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md index b458eab1d2..c8f798aa6f 100644 --- a/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md +++ b/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: SQL: Customizing Your Recordset’s SQL Statement (ODBC)" -title: "SQL: Customizing Your Recordset’s SQL Statement (ODBC)" +description: "Learn more about: SQL: Customizing Your Recordset's SQL Statement (ODBC)" +title: "SQL: Customizing Your Recordset's SQL Statement (ODBC)" ms.date: "11/04/2016" helpviewer_keywords: ["recordsets, SQL statements", "ODBC recordsets, SQL statements", "SQL statements, customizing", "SQL statements, recordset", "customizing SQL statements", "overriding, SQL statements", "SQL, opening recordsets"] ms.assetid: 72293a08-cef2-4be2-aa1c-30565fcfbaf9 --- -# SQL: Customizing Your Recordset’s SQL Statement (ODBC) +# SQL: Customizing Your Recordset's SQL Statement (ODBC) This topic explains: diff --git a/docs/data/oledb/cdataconnection-class.md b/docs/data/oledb/cdataconnection-class.md index 6185ad4691..d388cafa61 100644 --- a/docs/data/oledb/cdataconnection-class.md +++ b/docs/data/oledb/cdataconnection-class.md @@ -179,7 +179,7 @@ This operator returns a reference to the contained `CDataSource` object, allowin If you have a function (such as `func` below) that takes a `CDataSource` reference, you can use `CDataSource&` to pass a `CDataConnection` object instead. [!code-cpp[NVC_OLEDB_Consumer#3](../../data/oledb/codesnippet/cpp/cdataconnection-operator-cdatasource-amp_1.cpp)] - +  [!code-cpp[NVC_OLEDB_Consumer#4](../../data/oledb/codesnippet/cpp/cdataconnection-operator-cdatasource-amp_2.cpp)] ## `CDataConnection::operator CDataSource*` @@ -217,7 +217,7 @@ This operator returns a reference to the contained `CSession` object, allowing y If you have a function (such as `func` below) that takes a `CSession` reference, you can use `CSession&` to pass a `CDataConnection` object instead. [!code-cpp[NVC_OLEDB_Consumer#5](../../data/oledb/codesnippet/cpp/cdataconnection-operator-csession-amp_1.cpp)] - +  [!code-cpp[NVC_OLEDB_Consumer#6](../../data/oledb/codesnippet/cpp/cdataconnection-operator-csession-amp_2.cpp)] ## `CDataConnection::operator CSession*` diff --git a/docs/data/oledb/cdbpropset-class.md b/docs/data/oledb/cdbpropset-class.md index 9086c09dde..858162faf3 100644 --- a/docs/data/oledb/cdbpropset-class.md +++ b/docs/data/oledb/cdbpropset-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CDBPropSet Class" title: "CDBPropSet Class" +description: "Learn more about: CDBPropSet Class" ms.date: "11/04/2016" f1_keywords: ["CDBPropSet", "ATL.CDBPropSet", "ATL::CDBPropSet", "CDBPropSet::AddProperty", "CDBPropSet.AddProperty", "AddProperty", "ATL::CDBPropSet::AddProperty", "ATL.CDBPropSet.AddProperty", "CDBPropSet.CDBPropSet", "CDBPropSet::CDBPropSet", "ATL::CDBPropSet::CDBPropSet", "ATL.CDBPropSet.CDBPropSet", "CDBPropSet.operator=", "ATL::CDBPropSet::operator=", "ATL.CDBPropSet.operator=", "CDBPropSet::operator=", "ATL.CDBPropSet.SetGUID", "CDBPropSet.SetGUID", "ATL::CDBPropSet::SetGUID", "CDBPropSet::SetGUID"] helpviewer_keywords: ["CDBPropSet class", "AddProperty method", "CDBPropSet class, constructor", "operator =, property sets", "= operator, with OLE DB templates", "operator=, property sets", "SetGUID method", "AddProperty method"] -ms.assetid: 54190149-c277-4679-b81a-ef484d4d1c00 --- # CDBPropSet Class @@ -144,8 +143,8 @@ CDBPropSet& operator =(CDBPropSet& propset) throw(); ## See also -[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)
-[OLE DB Consumer Templates Reference](../../data/oledb/ole-db-consumer-templates-reference.md)
-[CDBPropIDSet Class](../../data/oledb/cdbpropidset-class.md)
-[DBPROPSET Structure](/previous-versions/windows/desktop/ms714367(v=vs.85)) +[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)\ +[OLE DB Consumer Templates Reference](../../data/oledb/ole-db-consumer-templates-reference.md)\ +[CDBPropIDSet Class](../../data/oledb/cdbpropidset-class.md)\ +[DBPROPSET Structure](/previous-versions/windows/desktop/ms714367(v=vs.85))\ [DBPROP Structure](/previous-versions/windows/desktop/ms717970(v=vs.85)) diff --git a/docs/data/oledb/consumer-wizard-generated-classes.md b/docs/data/oledb/consumer-wizard-generated-classes.md index c56375b66c..07eb3edd88 100644 --- a/docs/data/oledb/consumer-wizard-generated-classes.md +++ b/docs/data/oledb/consumer-wizard-generated-classes.md @@ -19,7 +19,7 @@ When you use the **ATL OLE DB Consumer Wizard** to generate a consumer, you have - If you select a templated consumer, the wizard generates a command class and a user record class. The command class will have the name that you enter in the **Class** box in the wizard (for example, `CProducts`), and the user record class will have a name of the form "*ClassName*Accessor" (for example, `CProductsAccessor`). Both classes are placed in the consumer's header file. -- If you select an attributed consumer, the user record class will have a name of the form "_*ClassName*Accessor" and will be injected. That is, you'll be able to view only the command class in the text editor; you can only view the user record class as injected code. For information about viewing injected code, see [Debugging Injected Code](/visualstudio/debugger/how-to-debug-injected-code). +- If you select an attributed consumer, the user record class will have a name of the form "_*ClassName*Accessor" and will be injected. That is, you'll be able to view only the command class in the text editor; you can only view the user record class as injected code. For information about viewing injected code, see [Debugging Injected Code](../../windows/attributes/cpp-attributes-com-net.md#debug-injected-code). The following examples use a command class created on the `Products` table of the `Northwind` database to demonstrate the wizard-generated consumer code for the command class and user record class. @@ -178,7 +178,7 @@ class CProducts : public CCommand> Most of the injected code is the same as or similar to the templated version. The main differences are in the injected methods, which are described in [Consumer Wizard-Generated Methods](../../data/oledb/consumer-wizard-generated-methods.md). -For information about viewing injected code, see [Debugging Injected Code](/visualstudio/debugger/how-to-debug-injected-code). +For information about viewing injected code, see [Debugging Injected Code](../../windows/attributes/cpp-attributes-com-net.md#debug-injected-code). ::: moniker-end diff --git a/docs/data/oledb/consumer-wizard-generated-methods.md b/docs/data/oledb/consumer-wizard-generated-methods.md index 28a3305590..1bda308545 100644 --- a/docs/data/oledb/consumer-wizard-generated-methods.md +++ b/docs/data/oledb/consumer-wizard-generated-methods.md @@ -15,7 +15,7 @@ The ATL OLE DB Consumer wizard is not available in Visual Studio 2019 and later. ::: moniker range="<=msvc-150" -The **ATL OLE DB Consumer Wizard** and the **MFC Application Wizard** generate certain functions of which you should be aware. Some methods are implemented differently in attributed projects, so there are a few caveats; each case is covered below. For information about viewing injected code, see [Debugging Injected Code](/visualstudio/debugger/how-to-debug-injected-code). +The **ATL OLE DB Consumer Wizard** and the **MFC Application Wizard** generate certain functions of which you should be aware. Some methods are implemented differently in attributed projects, so there are a few caveats; each case is covered below. For information about viewing injected code, see [Debugging Injected Code](../../windows/attributes/cpp-attributes-com-net.md#debug-injected-code). - `OpenAll` opens the data source, rowsets, and turns on bookmarks if they're available. diff --git a/docs/data/oledb/crowset-class.md b/docs/data/oledb/crowset-class.md index d64fd3ebc5..d42f6d0f81 100644 --- a/docs/data/oledb/crowset-class.md +++ b/docs/data/oledb/crowset-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CRowset Class" title: "CRowset Class" +description: "Learn more about: CRowset Class" ms.date: "11/04/2016" f1_keywords: ["ATL.CRowset", "CRowset", "ATL::CRowset", "ATL::CRowset", "ATL.CRowset", "CRowset.AddRefRows", "CRowset.AddRefRows", "ATL.CRowset.AddRefRows", "AddRefRows", "CRowset::AddRefRows", "CRowset::AddRefRows", "ATL::CRowset::AddRefRows", "ATL.CRowset.AddRefRows", "ATL::CRowset::AddRefRows", "CRowset::Close", "ATL.CRowset.Close", "CRowset::Close", "CRowset.Close", "ATL.CRowset.Close", "ATL::CRowset::Close", "ATL::CRowset::Close", "CRowset.Close", "CRowset.Compare", "CRowset::Compare", "ATL.CRowset.Compare", "ATL::CRowset::Compare", "CRowset.Compare", "ATL::CRowset::Compare", "ATL.CRowset.Compare", "CRowset::Compare", "CRowset::CRowset", "CRowset.CRowset", "ATL::CRowset::CRowset", "ATL::CRowset::CRowset", "ATL.CRowset.CRowset", "CRowset.CRowset", "CRowset::CRowset", "ATL.CRowset.CRowset", "ATL::CRowset::Delete", "CRowset.Delete", "CRowset::Delete", "ATL.CRowset.Delete", "ATL::CRowset::Delete", "CRowset.Delete", "CRowset::Delete", "ATL.CRowset.Delete", "ATL.CRowset.FindNextRow", "CRowset.FindNextRow", "ATL::CRowset::FindNextRow", "CRowset::FindNextRow", "CRowset::FindNextRow", "CRowset.FindNextRow", "ATL.CRowset.FindNextRow", "ATL::CRowset::FindNextRow", "FindNextRow", "ATL::CRowset::GetApproximatePosition", "ATL::CRowset::GetApproximatePosition", "CRowset.GetApproximatePosition", "CRowset::GetApproximatePosition", "GetApproximatePosition", "ATL.CRowset.GetApproximatePosition", "CRowset::GetApproximatePosition", "CRowset::GetData", "ATL::CRowset::GetData", "ATL::CRowset::GetData", "ATL.CRowset.GetData", "CRowset.GetData", "CRowset::GetData", "CRowset.GetData", "ATL.CRowset.GetData", "CRowset::GetDataHere", "CRowset.GetDataHere", "CRowset.GetDataHere", "GetDataHere", "CRowset::GetDataHere", "ATL::CRowset::GetDataHere", "ATL::CRowset::GetDataHere", "ATL.CRowset.GetDataHere", "ATL.CRowset.GetDataHere", "ATL.CRowset.GetOriginalData", "CRowset::GetOriginalData", "ATL::CRowset::GetOriginalData", "ATL.CRowset.GetOriginalData", "CRowset::GetOriginalData", "ATL::CRowset::GetOriginalData", "CRowset.GetOriginalData", "CRowset.GetRowStatus", "ATL.CRowset.GetRowStatus", "ATL::CRowset::GetRowStatus", "CRowset::GetRowStatus", "ATL::CRowset::GetRowStatus", "CRowset::GetRowStatus", "ATL.CRowset.GetRowStatus", "CRowset.GetRowStatus", "ATL.CRowset.Insert", "CRowset.Insert", "CRowset.Insert", "CRowset::Insert", "ATL::CRowset::Insert", "ATL.CRowset.Insert", "CRowset::Insert", "ATL::CRowset::Insert", "CRowset::IsSameRow", "CRowset.IsSameRow", "ATL::CRowset::IsSameRow", "ATL.CRowset.IsSameRow", "CRowset::IsSameRow", "ATL.CRowset.IsSameRow", "CRowset.IsSameRow", "ATL::CRowset::IsSameRow", "CRowset::MoveFirst", "ATL::CRowset::MoveFirst", "CRowset.MoveFirst", "CRowset::MoveFirst", "CRowset.MoveFirst", "ATL.CRowset.MoveFirst", "ATL.CRowset.MoveFirst", "ATL::CRowset::MoveFirst", "ATL::CRowset::MoveLast", "CRowset::MoveLast", "ATL.CRowset.MoveLast", "ATL::CRowset::MoveLast", "CRowset.MoveLast", "CRowset::MoveLast", "ATL.CRowset.MoveLast", "CRowset.MoveLast", "ATL.CRowset.MoveNext", "ATL.CRowset.MoveNext", "ATL::CRowset::MoveNext", "CRowset.MoveNext", "CRowset.MoveNext", "CRowset::MoveNext", "CRowset::MoveNext", "ATL::CRowset::MoveNext", "CRowset.MovePrev", "CRowset.MovePrev", "CRowset::MovePrev", "ATL.CRowset.MovePrev", "ATL::CRowset::MovePrev", "ATL::CRowset::MovePrev", "ATL.CRowset.MovePrev", "CRowset::MovePrev", "ATL::CRowset::MoveToBookmark", "ATL::CRowset::MoveToBookmark", "ATL.CRowset.MoveToBookmark", "ATL.CRowset.MoveToBookmark", "CRowset::MoveToBookmark", "CRowset.MoveToBookmark", "CRowset::MoveToBookmark", "CRowset::MoveToRatio", "CRowset::MoveToRatio", "CRowset.MoveToRatio", "ATL.CRowset.MoveToRatio", "ATL::CRowset::MoveToRatio", "CRowset.MoveToRatio", "ATL.CRowset.MoveToRatio", "ATL::CRowset::MoveToRatio", "CRowset::ReleaseRows", "ATL::CRowset::ReleaseRows", "CRowset.ReleaseRows", "CRowset.ReleaseRows", "ATL.CRowset.ReleaseRows", "ATL.CRowset.ReleaseRows", "CRowset::ReleaseRows", "ATL::CRowset::ReleaseRows", "ATL.CRowset.SetData", "ATL::CRowset::SetData", "CRowset.SetData", "CRowset::SetData", "ATL.CRowset.SetData", "CRowset.SetData", "CRowset::SetData", "ATL::CRowset::SetData", "CRowset.Undo", "ATL::CRowset::Undo", "CRowset::Undo", "ATL.CRowset.Undo", "ATL.CRowset.Undo", "CRowset.Undo", "ATL::CRowset::Undo", "CRowset::Undo", "Undo", "CRowset.Update", "ATL.CRowset.Update", "ATL.CRowset.Update", "ATL::CRowset::Update", "CRowset::Update", "CRowset::Update", "CRowset.Update", "ATL::CRowset::Update", "CRowset::UpdateAll", "ATL.CRowset.UpdateAll", "CRowset.UpdateAll", "ATL.CRowset.UpdateAll", "UpdateAll", "CRowset.UpdateAl", "ATL::CRowset::UpdateAll", "CRowset::UpdateAll", "ATL::CRowset::UpdateAll"] helpviewer_keywords: ["CRowset class", "AddRefRows method", "Close method", "Compare method", "CRowset class, constructor", "Delete method", "FindNextRow method", "GetApproximatePosition method", "GetData method [OLE DB]", "GetDataHere method", "GetOriginalData method", "GetRowStatus method", "Insert method", "IsSameRow method", "MoveFirst method", "MoveLast method", "MoveNext method", "MovePrev method", "MoveToBookmark method", "MoveToRatio method", "ReleaseRows method", "SetData method", "Undo method", "Update method", "UpdateAll method"] -ms.assetid: b0228a90-b8dd-47cc-b397-8d4c15c1e7f4 --- # CRowset Class @@ -19,7 +18,7 @@ class CRowset ### Parameters -*TAccessor*
+*TAccessor*\ An accessor class. The default is `CAccessorBase`. ## Requirements @@ -36,14 +35,14 @@ An accessor class. The default is `CAccessorBase`. |[Close](#close)|Releases rows and the current `IRowset` interface.| |[Compare](#compare)|Compares two bookmarks using [IRowsetLocate::Compare](/previous-versions/windows/desktop/ms709539(v=vs.85)).| |[CRowset](#crowset)|Creates a new `CRowset` object and (optionally) associates it with an `IRowset` interface supplied as a parameter.| -|[Delete](#delete)|Deletes rows from the rowset using [IRowsetChange:DeleteRows](/previous-versions/windows/desktop/ms724362(v=vs.85)).| +|[Delete](#delete)|Deletes rows from the rowset using [IRowsetChange::DeleteRows](/previous-versions/windows/desktop/ms724362(v=vs.85)).| |[FindNextRow](#findnextrow)|Finds the next matching row after the specified bookmark.| |[GetApproximatePosition](#getapproximateposition)|Returns the approximate position of a row corresponding to a bookmark.| |[GetData](#getdata)|Retrieves data from the rowset's copy of the row.| |[GetDataHere](#getdatahere)|Retrieves data from the specified buffer.| |[GetOriginalData](#getoriginaldata)|Retrieves the data most recently fetched from or transmitted to the data source, ignoring pending changes.| |[GetRowStatus](#getrowstatus)|Returns the status of all rows.| -|[Insert](#insert)|Creates and inserts a new row using [IRowsetChange:InsertRow](/previous-versions/windows/desktop/ms716921(v=vs.85)).| +|[Insert](#insert)|Creates and inserts a new row using [IRowsetChange::InsertRow](/previous-versions/windows/desktop/ms716921(v=vs.85)).| |[IsSameRow](#issamerow)|Compares the specified row with the current row.| |[MoveFirst](#movefirst)|Repositions the next-fetch location to the initial position.| |[MoveLast](#movelast)|Moves to the last record.| @@ -52,7 +51,7 @@ An accessor class. The default is `CAccessorBase`. |[MoveToBookmark](#movetobookmark)|Fetches the row marked by a bookmark or the row at a specified offset from that bookmark.| |[MoveToRatio](#movetoratio)|Fetches rows starting from a fractional position in the rowset.| |[ReleaseRows](#releaserows)|Calls [IRowset::ReleaseRows](/previous-versions/windows/desktop/ms719771(v=vs.85)) to release the current row handle.| -|[SetData](#setdata)|Sets data values in one or more columns of a row using [IRowsetChange:SetData](/previous-versions/windows/desktop/ms721232(v=vs.85)).| +|[SetData](#setdata)|Sets data values in one or more columns of a row using [IRowsetChange::SetData](/previous-versions/windows/desktop/ms721232(v=vs.85)).| |[Undo](#undo)|Undoes any changes made to a row since the last fetch or [Update](#update).| |[Update](#update)|Transmits any pending changes made to the current row since the last fetch or update.| |[UpdateAll](#updateall)|Transmits any pending changes made to all rows since the last fetch or update.| @@ -109,13 +108,13 @@ HRESULT Compare(const CBookmarkBase& bookmark1, #### Parameters -*Bookmark1*
+*Bookmark1*\ [in] The first bookmark to compare. -*Bookmark2*
+*Bookmark2*\ [in] The second bookmark to compare. -*pComparison*
+*pComparison*\ [out] A pointer to the result of the comparison. ### Return Value @@ -142,7 +141,7 @@ CRowset(IRowset* pRowset); #### Parameters -*pRowset*
+*pRowset*\ [in] A pointer to an `IRowset` interface to be associated with this class. ## CRowset::Delete @@ -178,28 +177,28 @@ HRESULT FindNextRow(DBCOMPAREOP op, #### Parameters -*op*
+*op*\ [in] The operation to use in comparing row values. For values, see [IRowsetFind::FindNextRow](/previous-versions/windows/desktop/ms723091(v=vs.85)). -*pData*
+*pData*\ [in] A pointer to the value to be matched. -*wType*
+*wType*\ [in] Indicates the data type of the value part of the buffer. For information about type indicators, see [Data Types](/previous-versions/windows/desktop/ms723969(v=vs.85)) in the *OLE DB Programmer's Reference* in the Windows SDK. -*nLength*
+*nLength*\ [in] The length, in bytes, of the consumer data structure allocated for the data value. For details, see the description of `cbMaxLen` in [DBBINDING Structures](/previous-versions/windows/desktop/ms716845(v=vs.85)) in the *OLE DB Programmer's Reference.* -*bPrecision*
+*bPrecision*\ [in] The maximum precision used when getting data. Used only if *wType* is DBTYPE_NUMERIC. For more information, see [Conversions involving DBTYPE_NUMERIC or DBTYPE_DECIMAL](/previous-versions/windows/desktop/ms719714(v=vs.85)) in the *OLE DB Programmer's Reference*. -*bScale*
+*bScale*\ [in] The scale used when getting data. Used only if *wType* is DBTYPE_NUMERIC or DBTYPE_DECIMAL. For more information, see [Conversions involving DBTYPE_NUMERIC or DBTYPE_DECIMAL](/previous-versions/windows/desktop/ms719714(v=vs.85)) in the *OLE DB Programmer's Reference*. -*bSkipCurrent*
+*bSkipCurrent*\ [in] The number of rows from the bookmark at which to start a search. -*pBookmark*
+*pBookmark*\ [in] The bookmark for position at which to start a search. ### Return Value @@ -226,13 +225,13 @@ HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark, #### Parameters -*pBookmark*
+*pBookmark*\ [in] A pointer to a bookmark that identifies the row whose position is to be found. NULL if only the row count is required. -*pPosition*
+*pPosition*\ [out] A pointer to the location where `GetApproximatePosition` returns the position of the row. NULL if the position is not required. -*pcRows*
+*pcRows*\ [out] A pointer to the location where `GetApproximatePosition` returns the total number of rows. NULL if the row count is not required. ### Return Value @@ -259,7 +258,7 @@ HRESULT GetData(int nAccessor) throw(); #### Parameters -*nAccessor*
+*nAccessor*\ [in] The (zero-offset) index number of the accessor to use for accessing the data. ### Return Value @@ -283,10 +282,10 @@ HRESULT GetDataHere(int nAccessor, #### Parameters -*nAccessor*
+*nAccessor*\ [in] The index number of the accessor to use for accessing the data. -*pBuffer*
+*pBuffer*\ [out] A buffer into which to place the data for the current record. ### Return Value @@ -329,7 +328,7 @@ HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw(); #### Parameters -*pStatus*
+*pStatus*\ [out] A pointer to a location where `GetRowStatus` returns the status value. See DBPENDINGSTATUS in the OLE DB Programmer's Reference. ### Return Value @@ -353,10 +352,10 @@ HRESULT Insert(int nAccessor = 0, #### Parameters -*nAccessor*
+*nAccessor*\ [in] The number of the accessor to use for inserting the data. -*bGetHRow*
+*bGetHRow*\ [in] Indicates whether the handle for the inserted row is retrieved. ### Return Value @@ -389,7 +388,7 @@ HRESULT IsSameRow(HROW hRow) const throw(); #### Parameters -*hRow*
+*hRow*\ [in] A handle to the row to compare to the current row. ### Return Value @@ -449,10 +448,10 @@ HRESULT MoveNext(LONG lSkip, #### Parameters -*lSkip*
+*lSkip*\ [in] The number of rows to skip before fetching. -*bForward*
+*bForward*\ [in] Pass **`true`** to move forward to the next record, **`false`** to move backward. ### Return Value @@ -502,10 +501,10 @@ HRESULT MoveToBookmark(const CBookmarkBase& bookmark, #### Parameters -*bookmark*
+*bookmark*\ [in] A bookmark marking the location from which you want to fetch data. -*lSkip*
+*lSkip*\ [in] The number count of rows from the bookmark to the target row. If *lSkip* is zero, the first row fetched is the bookmarked row. If *lSkip* is 1, the first row fetched is the row after the bookmarked row. If *lSkip* is -1, the first row fetched is the row before the bookmarked row. ### Return Value @@ -531,13 +530,13 @@ HRESULT MoveToRatio(DBCOUNTITEM nNumerator, #### Parameters -*nNumerator*
+*nNumerator*\ [in] The numerator used to determine the fractional positional from which to fetch data. -*nDenominator*
+*nDenominator*\ [in] The denominator used to determine the fractional positional from which to fetch data. -*bForward*
+*bForward*\ [in] Indicates whether to move forward or backward. The default is forward. ### Return Value @@ -582,7 +581,7 @@ HRESULT SetData(int nAccessor) const throw(); #### Parameters -*nAccessor*
+*nAccessor*\ [in] The number of the accessor to use for accessing the data. ### Return Value @@ -611,13 +610,13 @@ HRESULT Undo(DBCOUNTITEM* pcRows = NULL, #### Parameters -*pcRows*
+*pcRows*\ [out] A pointer to the location where `Undo` returns the number of rows it attempted to undo if required. -*phRow*
+*phRow*\ [out] A pointer to the location where `Undo` returns an array of handles to all rows it attempted to undo if required. -*pStatus*
+*pStatus*\ [out] A pointer to the location where `Undo` returns the row status value. No status is returned if *pStatus* is null. ### Return Value @@ -642,13 +641,13 @@ HRESULT Update(DBCOUNTITEM* pcRows = NULL, #### Parameters -*pcRows*
+*pcRows*\ [out] A pointer to the location where `Update` returns the number of rows it attempted to update, if required. -*phRow*
+*phRow*\ [out] A pointer to the location where `Update` returns the handle of the row it attempted to update. No handle is returned if *phRow* is null. -*pStatus*
+*pStatus*\ [out] A pointer to the location where `Update` returns the row status value. No status is returned if *pStatus* is null. ### Return Value @@ -675,13 +674,13 @@ HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL, #### Parameters -*pcRows*
+*pcRows*\ [out] A pointer to the location where `UpdateAll` returns the number of rows it attempted to update, if required. -*pphRow*
+*pphRow*\ [out] A pointer to memory in which `UpdateAll` returns the handle of the row it attempted to update. No handle is returned if *pphRow* is null. -*ppStatus*
+*ppStatus*\ [out] A pointer to the location where `Update` returns the row status value. No status is returned if *ppStatus* is null. ### Remarks @@ -698,8 +697,8 @@ A standard HRESULT. ## See also -[DBViewer Sample](../../overview/visual-cpp-samples.md)
-[MultiRead Sample](../../overview/visual-cpp-samples.md)
-[MultiRead Attributes Sample](../../overview/visual-cpp-samples.md)
-[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)
+[DBViewer Sample](../../overview/visual-cpp-samples.md)\ +[MultiRead Sample](../../overview/visual-cpp-samples.md)\ +[MultiRead Attributes Sample](../../overview/visual-cpp-samples.md)\ +[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)\ [OLE DB Consumer Templates Reference](../../data/oledb/ole-db-consumer-templates-reference.md) diff --git a/docs/data/oledb/irowsetlocateimpl-class.md b/docs/data/oledb/irowsetlocateimpl-class.md index 082de1f7b9..16872cbd1a 100644 --- a/docs/data/oledb/irowsetlocateimpl-class.md +++ b/docs/data/oledb/irowsetlocateimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IRowsetLocateImpl Class" title: "IRowsetLocateImpl Class" +description: "Learn more about: IRowsetLocateImpl Class" ms.date: "11/04/2016" f1_keywords: ["IRowsetLocateImpl", "ATL.IRowsetLocateImpl.Compare", "IRowsetLocateImpl::Compare", "IRowsetLocateImpl.Compare", "ATL::IRowsetLocateImpl::Compare", "GetRowsAt", "IRowsetLocateImpl.GetRowsAt", "ATL::IRowsetLocateImpl::GetRowsAt", "IRowsetLocateImpl::GetRowsAt", "ATL.IRowsetLocateImpl.GetRowsAt", "IRowsetLocateImpl::GetRowsByBookmark", "IRowsetLocateImpl.GetRowsByBookmark", "GetRowsByBookmark", "IRowsetLocateImpl::Hash", "IRowsetLocateImpl.Hash", "m_rgBookmarks", "IRowsetLocateImpl::m_rgBookmarks", "ATL.IRowsetLocateImpl.m_rgBookmarks", "ATL::IRowsetLocateImpl::m_rgBookmarks", "IRowsetLocateImpl.m_rgBookmarks"] helpviewer_keywords: ["providers, bookmarks", "IRowsetLocateImpl class", "bookmarks, OLE DB", "Compare method", "GetRowsAt method", "GetRowsByBookmark method", "Hash method", "m_rgbookmarks"] -ms.assetid: a8aa3149-7ce8-4976-a680-2da193fd3234 --- # IRowsetLocateImpl Class @@ -202,8 +201,8 @@ CAtlArray m_rgBookmarks; ## See also -[OLE DB Provider Templates](../../data/oledb/ole-db-provider-templates-cpp.md)
-[OLE DB Provider Template Architecture](../../data/oledb/ole-db-provider-template-architecture.md)
-[IRowsetLocate:IRowset](/previous-versions/windows/desktop/ms721190(v=vs.85)) -[Provider Support for Bookmarks](../../data/oledb/provider-support-for-bookmarks.md)
+[OLE DB Provider Templates](../../data/oledb/ole-db-provider-templates-cpp.md)\ +[OLE DB Provider Template Architecture](../../data/oledb/ole-db-provider-template-architecture.md)\ +[IRowsetLocate:IRowset](/previous-versions/windows/desktop/ms721190(v=vs.85))\ +[Provider Support for Bookmarks](../../data/oledb/provider-support-for-bookmarks.md)\ [Bookmarks](/previous-versions/windows/desktop/ms709728(v=vs.85)) diff --git a/docs/data/oledb/irowsetnotifyimpl-class.md b/docs/data/oledb/irowsetnotifyimpl-class.md index 314202ddd9..8737941bcd 100644 --- a/docs/data/oledb/irowsetnotifyimpl-class.md +++ b/docs/data/oledb/irowsetnotifyimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IRowsetNotifyImpl Class" title: "IRowsetNotifyImpl Class" +description: "Learn more about: IRowsetNotifyImpl Class" ms.date: "11/04/2016" f1_keywords: ["ATL.IRowsetNotifyImpl", "ATL::IRowsetNotifyImpl", "IRowsetNotifyImpl", "IRowsetNotifyImpl.OnFieldChange", "IRowsetNotifyImpl::OnFieldChange", "OnFieldChange", "IRowsetNotifyImpl::OnRowChange", "IRowsetNotifyImpl.OnRowChange", "OnRowChange", "OnRowsetChange", "IRowsetNotifyImpl::OnRowsetChange", "IRowsetNotifyImpl.OnRowsetChange"] helpviewer_keywords: ["IRowsetNotifyImpl class", "OnFieldChange method", "OnRowChange method", "OnRowsetChange method"] -ms.assetid: fbfd0cb2-38ff-4b42-899a-8de902f834b8 --- # IRowsetNotifyImpl Class @@ -121,6 +120,6 @@ This method wraps the [IRowsetNotify::OnRowsetChange](/previous-versions/windows ## See also -[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)
-[IRowsetNotify](/previous-versions/windows/desktop/ms712959(v=vs.85)) +[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)\ +[IRowsetNotify](/previous-versions/windows/desktop/ms712959(v=vs.85))\ [IRowsetNotifyCP Class](../../data/oledb/irowsetnotifycp-class.md) diff --git a/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md b/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md index 574d95b2ac..f478250666 100644 --- a/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md +++ b/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md @@ -1,12 +1,9 @@ --- -description: "Learn more about: Schema Rowset Classes and Typedef Classes" title: "Schema Rowset Classes and Typedef Classes" -ms.date: "11/04/2016" +description: "Learn more about: Schema Rowset Classes and Typedef Classes" +ms.date: 11/04/2016 f1_keywords: ["CAssertionInfo", "CAssertions", "CCatalogInfo", "CCatalogs", "CCharacterSetInfo", "CCharacterSets", "CCheckConstraintInfo", "CCheckConstraints", "CCollationInfo", "CCollations", "CColumnDomainUsage", "CColumnDomainUsageInfo", "CColumnPrivilegeInfo", "CColumnPrivileges", "CColumns", "CColumnsInfo", "CConstraintColumnUsage", "CConstraintColumnUsageInfo", "CConstraintTableUsage", "CConstraintTableUsageInfo", "CForeignKeys", "CForeignKeysInfo", "CHARACTER_MAXIMUM_LENGTH", "CHARACTER_OCTET_LENGTH", "CHARACTER_SET_CATALOG", "CHARACTER_SET_NAME", "CHARACTER_SET_SCHEMA", "CHECK_CLAUSE", "CHECK_CONSTRAINTS", "CHECK_OPTION", "CIndexes", "CIndexInfo", "CKeyColumnInfo", "CKeyColumns", "CLUSTERED", "COLLATION", "COLLATION_CATALOG", "COLLATION_NAME", "COLLATION_SCHEMA", "COLLATIONS", "COLUMN_DEFAULT", "COLUMN_DOMAIN_USAGE", "COLUMN_FLAGS", "COLUMN_GUID", "COLUMN_HASDEFAULT", "COLUMN_PRIVILEGES", "COLUMN_PROPID", "COLUMN_SIZE", "CONSTRAINT_CATALOG", "CONSTRAINT_COLUMN_USAGE", "CONSTRAINT_NAME", "CONSTRAINT_SCHEMA", "CONSTRAINT_TABLE_USAGE", "CONSTRAINT_TYPE", "CPrimaryKeyInfo", "CPrimaryKeys", "CProcedureColumnInfo", "CProcedureColumns", "CProcedureInfo", "CProcedureParameters", "CProcedureParamInfo", "CProcedures", "CProviderInfo", "CProviderTypes", "CReferentialConstraintInfo", "CReferentialConstraints", "CSchemata", "CSchemataInfo", "CSQLLanguageInfo", "CSQLLanguages", "CStatisticInfo", "CStatistics", "CTableConstraintInfo", "CTableConstraints", "CTableInfo", "CTablePrivilegeInfo", "CTablePrivileges", "CTables", "CTranslationInfo", "CTranslations", "CUsagePrivilegeInfo", "CUsagePrivileges", "CViewColumnInfo", "CViewColumnUsage", "CViewInfo", "CViews", "CViewTableInfo", "CViewTableUsage", "DATA_TYPE", "DATETIME_PRECISION", "DEFAULT_CHARACTER_SET_CATALOG", "DEFAULT_CHARACTER_SET_NAME", "DEFAULT_CHARACTER_SET_SCHEMA", "DEFAULT_COLLATE_CATALOG", "DEFAULT_COLLATE_NAME", "DEFAULT_COLLATE_SCHEMA", "DELETE_RULE", "DOMAIN_CATALOG", "DOMAIN_NAME", "DOMAIN_SCHEMA", "FILL_FACTOR", "FILTER_CONDITION", "FIXED_PREC_SCALE", "FK_COLUMN_GUID", "FK_COLUMN_NAME", "FK_COLUMN_PROPID", "FK_TABLE_CATALOG", "FK_TABLE_NAME", "FK_TABLE_SCHEMA", "FORM_OF_USE", "GRANTEE", "GRANTOR", "INDEX_CATALOG", "INDEX_NAME", "INDEX_SCHEMA", "INITIAL_SIZE", "INITIALLY_DEFERRED", "IS_DEFERRABLE", "IS_GRANTABLE", "IS_LONG", "IS_NULLABLE", "IS_UPDATABLE", "LITERAL_SUFFIX", "LOCAL_TYPE_NAME", "m_bAutoUniqueValue", "m_bAutoUpdate", "m_bBestMatch", "m_bCaseSensitive", "m_bCheckOption", "m_bClustered", "m_bColumnHasDefault", "m_bFixedPrecScale", "m_bHasDefault", "m_bInitiallyDeferred", "m_bIsDeferrable", "m_bIsGrantable", "m_bIsLong", "m_bIsNullable", "m_bIsUpdatable", "m_bPrimaryKey", "m_bSortBookmarks", "m_bUnique", "m_bUnsignedAttribute", "m_guidColumn", "m_guidFKColumn", "m_guidPKColumn", "m_guidTable", "m_guidType", "m_nCardinality", "m_nCollation", "m_nColumnFlags", "m_nColumnPropID", "m_nColumnSize", "m_nDataType", "m_nDateTimePrecision", "m_nFillFactor", "m_nFKColumnPropID", "m_nInitialSize", "m_nMaxLength", "m_nMaxScale", "m_nNullCollation", "m_nNulls", "m_nNumCharacters", "m_nNumericPrecision", "m_nNumericScale", "m_nOctetLength", "m_nOrdinal", "m_nOrdinalPosition", "m_nPages", "m_nPKColumnPropID", "m_nPrecision", "m_nRowsetNumber", "m_nScale", "m_nSearchable", "m_szBindingStyle", "m_szCatalog", "m_szCharCatalog", "m_szCharName", "m_szCharSchema", "m_szCharSetCatalog", "m_szCharSetName", "m_szCharSetSchema", "m_szCheckClause", "m_szCollateCatalog", "m_szCollateName", "m_szCollateSchema", "m_szCollationCatalog", "m_szCollationName", "m_szCollationSchema", "m_szColumnDefault", "m_szColumnName", "m_szConformance", "m_szConstraintCatalog", "m_szConstraintName", "m_szConstraintSchema", "m_szCreateParams", "m_szDefault", "m_szDefinition", "m_szDeleteRule", "m_szDomainCatalog", "m_szDomainName", "m_szDomainSchema", "m_szFilterCondition", "m_szFKColumnName", "m_szFKTableCatalog", "m_szFKTableName", "m_szFKTableSchema", "m_szFormOfUse", "m_szGrantee", "m_szGrantor", "m_szImplementation", "m_szIndexCatalog", "m_szIndexName", "m_szIndexSchema", "m_szIntegrity", "m_szLiter alSuffix", "m_szLiteralPrefix", "m_szLocalTypeName", "m_szMatchOption", "m_szObjectCatalog", "m_szObjectName", "m_szObjectSchema", "m_szObjectType", "m_szOwner", "m_szPadAttribute", "m_szParameterName", "m_szPKColumnName", "m_szPKTableCatalog", "m_szPKTableName", "m_szPKTableSchema", "m_szPrivilegeType", "m_szProgrammingLanguage", "m_szSchema", "m_szSource", "m_szSourceCatalog", "m_szSourceName", "m_szSourceSchema", "m_szTableCatalog", "m_szTableName", "m_szTableSchema", "m_szTargetCatalog", "m_szTargetName", "m_szTargetSchema", "m_szType", "m_szTypeLib", "m_szTypeName", "m_szUniqueCatalog", "m_szUniqueName", "m_szUniqueSchema", "m_szUpdateRule", "m_szVersion", "m_szYear", "MATCH_OPTION", "MAXIMUM_SCALE", "MINIMUM_SCALE", "NULL_COLLATION", "NULLS", "NUMBER_OF_CHARACTERS", "NUMERIC_PRECISION", "NUMERIC_SCALE", "OBJECT_CATALOG", "OBJECT_NAME", "OBJECT_SCHEMA", "OBJECT_TYPE", "ORDINAL", "ORDINAL_POSITION", "TABLE_CATALOG", "TABLE_GUID", "TABLE_NAME", "TABLE_SCHEMA"] - - helpviewer_keywords: ["schema rowsets", "CAssertionInfo parameter class", "CAssertions typedef class", "CCatalogInfo parameter class", "CCatalogs typedef class", "CCharacterSetInfo parameter class", "CCharacterSets typedef class", "CCheckConstraintInfo parameter class", "CCheckConstraints typedef class", "CCollationInfo parameter class", "CCollations typedef class", "CColumnDomainUsage typedef class", "CColumnDomainUsageInfo parameter class", "CColumnPrivilegeInfo parameter class", "CColumnPrivileges typedef class", "CColumns typedef class", "CColumnsInfo parameter class", "CConstraintColumnUsage typedef class", "CConstraintColumnUsageInfo parameter class", "CConstraintTableUsage typedef class", "CConstraintTableUsageInfo parameter class", "CForeignKeys typedef class", "CForeignKeysInfo parameter class", "CHARACTER_MAXIMUM_LENGTH", "CHARACTER_OCTET_LENGTH", "CHARACTER_SET_CATALOG", "CHARACTER_SET_NAME", "CHARACTER_SET_SCHEMA", "CHECK_CLAUSE", "CHECK_CONSTRAINTS", "CHECK_OPTION", "CIndexes typedef class", "CIndexInfo parameter class", "CKeyColumnInfo parameter class", "CKeyColumns typedef class", "CLUSTERED", "COLLATION_CATALOG", "COLLATION_NAME", "COLLATION_SCHEMA", "COLLATIONS recordset", "COLUMN_DEFAULT", "COLUMN_DOMAIN_USAGE", "COLUMN_FLAGS", "COLUMN_GUID", "COLUMN_HASDEFAULT", "COLUMN_NAME", "COLUMN_PRIVILEGES", "COLUMN_PROPID", "CONSTRAINT_CATALOG", "CONSTRAINT_COLUMN_USAGE", "CONSTRAINT_NAME", "CONSTRAINT_SCHEMA", "CONSTRAINT_TABLE_USAGE", "CONSTRAINT_TYPE", "CPrimaryKeyInfo parameter class", "CPrimaryKeys typedef class", "CProcedureColumnInfo parameter class", "CProcedureColumns typedef class", "CProcedureInfo parameter class", "CProcedureParameters typedef class", "CProcedureParamInfo parameter class", "CProcedures typedef class", "CProviderInfo parameter class", "CProviderTypes typedef class", "CReferentialConstraintInfo parameter class", "CReferentialConstraints typedef class", "CSchemata typedef class", "CSchemataInfo parameter class", "CSQLLanguageInfo parameter class", "CSQLLanguages typedef class", "CStatisticInfo parameter class", "CStatistics typedef class", "CTableConstraintInfo parameter class", "CTableConstraints typedef class", "CTableInfo parameter class", "CTablePrivilegeInfo parameter class", "CTablePrivileges typedef class", "CTables typedef class", "CTranslationInfo parameter class", "CTranslations typedef class", "CUsagePrivilegeInfo parameter class", "CUsagePrivileges typedef class", "CViewColumnInfo parameter class", "CViewColumnUsage typedef class", "CViewInfo parameter class", "CViews typedef class", "CViewTableInfo parameter class", "CViewTableUsage typedef class", "DATA_TYPE", "DATETIME_PRECISION", "DEFAULT_CHARACTER_SET_CATALOG", "DEFAULT_CHARACTER_SET_NAME", "DEFAULT_CHARACTER_SET_SCHEMA", "DEFAULT_COLLATE_CATALOG", "DEFAULT_COLLATE_NAME", "DEFAULT_COLLATE_SCHEMA", "DELETE_RULE", "DESCRIPTION class data member", "DOMAIN_CATALOG", "DOMAIN_NAME", "DOMAIN_SCHEMA", "FILL_FACTOR", "FILTER_CONDITION", "FIXED_PREC_SCALE", "FK_COLUMN_GUID", "FK_COLUMN_NAME", "FK_COLUMN_PROPID", "FK_TABLE_CATALOG", "FK_TABLE_NAME", "FK_TABLE_SCHEMA", "FORM_OF_USE OLE DB column", "GRANTEE", "GRANTOR", "INDEX_CATALOG", "INDEX_NAME", "INDEX_SCHEMA", "INITIAL_SIZE", "INITIALLY_DEFERRED", "IS_DEFERRABLE", "IS_GRANTABLE", "IS_LONG", "IS_NULLABLE", "IS_UPDATABLE", "LITERAL_SUFFIX", "LOCAL_TYPE_NAME", "m_bAutoUniqueValue", "m_bAutoUpdate", "m_bBestMatch", "m_bCaseSensitive", "m_bCheckOption", "m_bClustered", "m_bColumnHasDefault", "m_bFixedPrecScale", "m_bHasDefault", "m_bInitiallyDeferred", "m_bIsDeferrable", "m_bIsGrantable", "m_bIsLong", "m_bIsNullable", "m_bIsUpdatable", "m_bPrimaryKey", "m_bSortBookmarks", "m_bUnique", "m_bUnsignedAttribute", "m_guidColumn", "m_guidFKColumn", "m_guidTable", "m_guidType", "m_nCardinality", "m_nCollation", "m_nColumnFlags", "m_nColumnPropID", "m_nColumnSize", "m_nDataType", "m_nDateTimePrecision", "m_nFillFactor", "m_nFKColumnPropID", "m_nInitialSize", "m_nMaxLength", "m_nMinScale", "m_nNullCollation", "m_nNulls", "m_nNumCharacters", "m_nNumericPrecision", "m_nNumericScale", "m_nOctetLength", "m_nOrdinal", "m_nOrdinalPosition", "m_nPages", "m_nPKColumnPropID", "m_nPrecision", "m_nRowsetNumber", "m_nScale", "m_nSearchable", "m_nType", "m_szBindingStyle", "m_szCatalog", "m_szCharCatalog", "m_szCharName", "m_szCharSchema", "m_szCharSetCatalog", "m_szCharSetName", "m_szCharSetSchema", "m_szCheckClause", "m_szCollateCatalog", "m_szCollateName", "m_szCollateSchema", "m_szCollationCatalog", "m_szCollationName", "m_szCollationSchema", "m_szColumnDefault", "m_szColumnName", "m_szConformance", "m_szConstraintCatalog", "m_szConstraintName", "m_szConstraintSchema", "m_szCreateParams", "m_szDefault", "m_szDefinition", "m_szDeleteRule", "m_szDescription", "m_szDomainCatalog", "m_szDomainName", "m_szDomainSchema", "m_szFilterCondition", "m_szFKColumnName", "m_szFKTableCatalog", "m_szFKTableName", "m_szFKTableSchema", "m_szFormOfUse", "m_szGrantee", "m_szGrantor", "m_szImplementation", "m_szIndexCatalog", "m_szIndexName", "m_szIndexSchema", "m_szIntegrity", "m_szLiteralPrefix", "m_szLocalTypeName", "m_szMatchOption", "m_szName", "m_szObjectCatalog", "m_szObjectName", "m_szObjectSchema", "m_szObjectType", "m_szOwner", "m_szPadAttribute", "m_szParameterName", "m_szPKColumnName", "m_szPKTableCatalog", "m_szPKTableName", "m_szPKTableSchema", "m_szPrivilegeType", "m_szPrivilegeType", "m_szProgrammingLanguage", "m_szSchema", "m_szSource", "m_szSourceCatalog", "m_szSourceName", "m_szSourceSchema", "m_szTableCatalog", "m_szTableName", "m_szTableSchema", "m_szTargetCatalog", "m_szTargetName", "m_szTargetSchema", "m_szType", "m_szTypeLib", "m_szTypeName", "m_szUniqueCatalog", "m_szUniqueName", "m_szUniqueSchema", "m_szUpdateRule", "m_szUpdateRule", "m_szVersion", "m_szYear", "MATCH_OPTION", "MAXIMUM_SCALE", "MINIMUM_SCALE", "NULL_COLLATION", "NULLS", "NUMBER_OF_CHARACTERS", "NUMERIC_PRECISION", "NUMERIC_SCALE", "OBJECT_CATALOG", "OBJECT_NAME", "OBJECT_SCHEMA", "OBJECT_TYPE", "ORDINAL data member", "ORDINAL_POSITION", "TABLE_CATALOG", "TABLE_GUID", "TABLE_NAME", "TABLE_SCHEMA"] -ms.assetid: 4bd881b3-26ca-4bdb-9226-d67560864f29 --- # Schema Rowset Classes and Typedef Classes diff --git a/docs/data/oledb/user-record.md b/docs/data/oledb/user-record.md index 67f68e80fb..760bda8535 100644 --- a/docs/data/oledb/user-record.md +++ b/docs/data/oledb/user-record.md @@ -1,10 +1,12 @@ --- description: "Learn more about: User Record" title: "User Record" -ms.date: "05/09/2019" +ms.date: 06/21/2022 helpviewer_keywords: ["records, user", "OLE DB providers, user record", "user records", "user records, described", "rowsets, user record"] ms.assetid: 9c0d2864-2738-4f62-a750-1016d9c3523f +ms.custom: devdivchpfy22 --- + # User Record > [!NOTE] @@ -53,7 +55,7 @@ The PROVIDER_COLUMN_MAP macros aid in creating a `GetColumnInfo` function: - END_PROVIDER_COLUMN_MAP closes the array and the function. It also places the array element count into the *pcCols* parameter. -When a user record is created at run time, `GetColumnInfo` uses the *pThis* parameter to receive a pointer to a rowset or command instance. Commands and rowsets must support the `IColumnsInfo` interface, so column information can be taken from this pointer. +When a user record is created at run time, `GetColumnInfo` uses the *`pThis`* parameter to receive a pointer to a rowset or command instance. Commands and rowsets must support the `IColumnsInfo` interface, so column information can be taken from this pointer. `CommandClass` and `RowsetClass` are the command and rowset that use the user record. diff --git a/docs/data/toc.yml b/docs/data/toc.yml index aea9e6bb11..af9d03c0fa 100644 --- a/docs/data/toc.yml +++ b/docs/data/toc.yml @@ -575,7 +575,7 @@ items: items: - name: SQL in ODBC href: ../data/odbc/sql.md - - name: "SQL: Customizing Your recordset’s SQL statement (ODBC)" + - name: "SQL: Customizing Your recordset's SQL statement (ODBC)" href: ../data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md - name: "SQL: SQL and C++ data types (ODBC)" href: ../data/odbc/sql-sql-and-cpp-data-types-odbc.md diff --git a/docs/docfx.json b/docs/docfx.json index 44665b56a1..389b95cc45 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -38,28 +38,35 @@ "externalReference": [], "globalMetadata": { "breadcrumb_path": "~/_breadcrumb/toc.yml", - "extendBreadcrumb": "true", +  "uhfHeaderId": "MSDocsHeader-CPP", "ROBOTS": "INDEX,FOLLOW", - "manager": "markl", + "manager": "coxford", "ms.date": "11/16/2016", "ms.topic": "conceptual", "audience": "developer", - "ms.prod": "visual-cpp", - "ms.tgt_pltfrm": "", + "ms.service": "visual-cpp", + "ms.tgt_pltfrm": "Windows", "ms.workload": [ "cplusplus" ], "dev_langs": [ - "C++" + "cpp" ], "searchScope": [ "C++" ], - "feedback_system": "GitHub", + "feedback_system": "Standard", "feedback_github_repo": "MicrosoftDocs/cpp-docs", - "feedback_product_url": "https://aka.ms/feedback/report?space=62" + "feedback_product_url": "https://developercommunity.visualstudio.com/cpp/", + "feedback_help_link_url": "https://learn.microsoft.com/en-us/answers/tags/314/cpp", + "feedback_help_link_type": "get-help-at-qna" }, "fileMetadata": { + "feedback_help_link_url": { + "dotnet/*.md": "https://learn.microsoft.com/en-us/answers/tags/308/dotnetcli", + "ide/*.md": "https://learn.microsoft.com/en-us/answers/tags/176/vs", + "windows/*.md": "https://learn.microsoft.com/en-us/answers/tags/184/windows-app-sdk" + }, "ms.tgt_pltfrm": { "linux/**.md": "Linux" }, @@ -98,11 +105,11 @@ "c-language/**.md": "language-reference", "c-runtime-library/**.md": "reference", "c-runtime-library/reference/**.md": "reference", - "code-quality/**.md": "reference", + "code-quality/**.md": "error-reference", "cpp/**.md": "language-reference", "cppcx/**.md": "language-reference", "data/oledb/**.md": "reference", - "error-messages/**.md": "reference", + "error-messages/**.md": "error-reference", "extensions/**.md": "reference", "intrinsics/**.md": "reference", "mfc/reference/**.md": "reference", @@ -116,115 +123,116 @@ "standard-library/**.md": "reference", "windows/attributes/**.md": "reference" }, - "ms.technology": { - "assembler/**.md": "cpp-masm", - "attributes/**.md": "cpp-cli", - "atl/**.md": "cpp-atl", - "atl-mfc-shared/**.md": "cpp-mfc", - "build/**.md": "cpp-tools", - "build-insights/**.md": "cpp-tools", - "c-language/**.md": "cpp-c-language", - "c-runtime-library/**.md": "cpp-ucrt", - "cloud/**.md": "cpp-azure", - "code-quality/**.md": "cpp-tools", - "cpp/**.md": "cpp-language", - "cppcx/**.md": "cpp-cx", - "cross-platform/**.md": "cpp-tools", - "data/**.md": "cpp-data", - "dotnet/**.md": "cpp-cli", - "error-messages/**.md": "cpp-diagnostics", - "extensions/**.md": "cpp-cli", - "get-started/**.md": "cpp-language", - "ide/**.md": "cpp-ide", - "intrinsics/**.md": "cpp-tools", - "linux/**.md": "cpp-linux", - "mfc/**.md": "cpp-mfc", - "overview/**.md": "cpp-tools", - "parallel/amp/**.md": "cpp-amp", - "parallel/concrt/**.md": "cpp-concrt", - "parallel/**.md": "cpp-parallel", - "porting/**.md": "cpp-language", - "preprocessor/**.md": "cpp-language", - "safeint/**.md": "cpp-standard-libraries", - "sanitizers/**.md": "cpp-tools", - "security/**.md": "cpp-windows", - "standard-library/**.md": "cpp-standard-libraries", - "text/**.md": "cpp-windows", - "windows/**.md": "cpp-windows" + "ms.subservice": { + "assembler/**.md": "masm", + "attributes/**.md": "cli-lang", + "atl/**.md": "atl-library", + "atl-mfc-shared/**.md": "mfc-library", + "build/**.md": "tools", + "build-insights/**.md": "tools", + "c-language/**.md": "c-language", + "c-runtime-library/**.md": "ucrt", + "cloud/**.md": "azure-development", + "code-quality/**.md": "tools", + "cpp/**.md": "cpp-lang", + "cppcx/**.md": "cpp-cx-lang", + "cross-platform/**.md": "tools", + "data/**.md": "data-access", + "dotnet/**.md": "cli-lang", + "embedded/**.md": "tools", + "error-messages/**.md": "errors-warnings", + "extensions/**.md": "cli-lang", + "get-started/**.md": "cpp-lang", + "ide/**.md": "ide", + "intrinsics/**.md": "tools", + "linux/**.md": "linux-development", + "mfc/**.md": "mfc-library", + "overview/**.md": "tools", + "parallel/amp/**.md": "parallel-programming", + "parallel/concrt/**.md": "parallel-programming", + "parallel/**.md": "parallel-programming", + "porting/**.md": "cpp-lang", + "preprocessor/**.md": "cpp-lang", + "safeint/**.md": "standard-libraries", + "sanitizers/**.md": "tools", + "security/**.md": "windows-development", + "standard-library/**.md": "standard-libraries", + "text/**.md": "windows-development", + "windows/**.md": "windows-development" }, "author": { - "index.md": "corob-msft", + "index.md": "tylermsft", "assembler/**.md": "tylermsft", - "attributes/**.md": "corob-msft", + "attributes/**.md": "tylermsft", "atl/**.md": "tylermsft", "atl-mfc-shared/**.md": "tylermsft", - "build/**.md": "corob-msft", - "build-insights/**.md": "kevcadieux", - "c-language/**.md": "corob-msft", + "build/**.md": "tylermsft", + "build-insights/**.md": "tylermsft", + "c-language/**.md": "tylermsft", "c-runtime-library/**.md": "tylermsft", - "cloud/**.md": "corob-msft", - "code-quality/**.md": "corob-msft", - "cpp/**.md": "corob-msft", - "cppcx/**.md": "corob-msft", - "cross-platform/**.md": "corob-msft", - "data/**.md": "corob-msft", + "cloud/**.md": "tylermsft", + "code-quality/**.md": "tylermsft", + "cpp/**.md": "tylermsft", + "cppcx/**.md": "tylermsft", + "cross-platform/**.md": "tylermsft", + "data/**.md": "tylermsft", "dotnet/**.md": "tylermsft", - "error-messages/**.md": "corob-msft", - "extensions/**.md": "corob-msft", - "get-started/**.md": "corob-msft", - "ide/**.md": "corob-msft", - "intrinsics/**.md": "corob-msft", + "error-messages/**.md": "tylermsft", + "extensions/**.md": "tylermsft", + "get-started/**.md": "tylermsft", + "ide/**.md": "tylermsft", + "intrinsics/**.md": "tylermsft", "linux/**.md": "tylermsft", "mfc/**.md": "tylermsft", - "overview/**.md": "corob-msft", + "overview/**.md": "tylermsft", "parallel/amp/**.md": "tylermsft", "parallel/concrt/**.md": "tylermsft", "parallel/**.md": "tylermsft", - "porting/**.md": "corob-msft", - "preprocessor/**.md": "corob-msft", + "porting/**.md": "tylermsft", + "preprocessor/**.md": "tylermsft", "safeint/**.md": "tylermsft", - "sanitizers/**.md": "corob-msft", - "security/**.md": "corob-msft", + "sanitizers/**.md": "tylermsft", + "security/**.md": "tylermsft", "standard-library/**.md": "tylermsft", "text/**.md": "tylermsft", - "windows/**.md": "corob-msft" + "windows/**.md": "tylermsft" }, "ms.author": { - "index.md": "corob", + "index.md": "twhitney", "assembler/**.md": "twhitney", "atl/**.md": "twhitney", "atl-mfc-shared/**.md": "twhitney", - "attributes/**.md": "corob", - "build/**.md": "corob", - "build-insights/**.md": "kevca", - "c-language/**.md": "corob", + "attributes/**.md": "twhitney", + "build/**.md": "twhitney", + "build-insights/**.md": "twhitney", + "c-language/**.md": "twhitney", "c-runtime-library/**.md": "twhitney", - "cloud/**.md": "corob", - "code-quality/**.md": "corob", - "cpp/**.md": "corob", - "cppcx/**.md": "corob", - "cross-platform/**.md": "corob", - "data/**.md": "corob", + "cloud/**.md": "twhitney", + "code-quality/**.md": "twhitney", + "cpp/**.md": "twhitney", + "cppcx/**.md": "twhitney", + "cross-platform/**.md": "twhitney", + "data/**.md": "twhitney", "dotnet/**.md": "twhitney", - "error-messages/**.md": "corob", - "extensions/**.md": "corob", - "get-started/**.md": "corob", - "ide/**.md": "corob", - "intrinsics/**.md": "corob", + "error-messages/**.md": "twhitney", + "extensions/**.md": "twhitney", + "get-started/**.md": "twhitney", + "ide/**.md": "twhitney", + "intrinsics/**.md": "twhitney", "linux/**.md": "twhitney", "mfc/**.md": "twhitney", - "overview/**.md": "corob", + "overview/**.md": "twhitney", "parallel/amp/**.md": "twhitney", "parallel/concrt/**.md": "twhitney", "parallel/**.md": "twhitney", - "porting/**.md": "corob", - "preprocessor/**.md": "corob", + "porting/**.md": "twhitney", + "preprocessor/**.md": "twhitney", "safeint/**.md": "twhitney", - "sanitizers/**.md": "corob", - "security/**.md": "corob", + "sanitizers/**.md": "twhitney", + "security/**.md": "twhitney", "standard-library/**.md": "twhitney", "text/**.md": "twhitney", - "windows/**.md": "corob" + "windows/**.md": "twhitney" } }, "template": [], diff --git a/docs/dotnet/adapter-stl-clr.md b/docs/dotnet/adapter-stl-clr.md index 957a358feb..7bd08c581e 100644 --- a/docs/dotnet/adapter-stl-clr.md +++ b/docs/dotnet/adapter-stl-clr.md @@ -7,9 +7,9 @@ f1_keywords: ["", "cliext::collection_adapter", "cliext::collect helpviewer_keywords: [" header [STL/CLR]", "adapter [STL/CLR]", " header [STL/CLR]", "collection_adapter class [STL/CLR]", "base member [STL/CLR]", "begin member [STL/CLR]", "collection_adapter member [STL/CLR]", "difference_type member [STL/CLR]", "end member [STL/CLR]", "iterator member [STL/CLR]", "key_type member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "value_type member [STL/CLR]", "make_collection function [STL/CLR]", "range_adapter class [STL/CLR]", "operator= member [STL/CLR]", "range_adapter member [STL/CLR]"] ms.assetid: 71ce7e51-42b6-4f70-9595-303791a97677 --- -# adapter (STL/CLR) +# `` (STL/CLR) -The STL/CLR header `` specifies two template classes (`collection_adapter` and `range_adapter`), and the template function `make_collection`. +The STL/CLR header `` specifies two class templates (`collection_adapter` and `range_adapter`), and the function template `make_collection`. ## Syntax @@ -21,22 +21,22 @@ The STL/CLR header `` specifies two template classes (`collectio **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Class|Description| -|-----------|-----------------| -|[collection_adapter (STL/CLR)](#collection_adapter)|Wraps the Base Class Library (BCL) collection as a range.| -|[range_adapter (STL/CLR)](#range_adapter)|Wraps the range as a BCL collection.| +| Class | Description | +|---|---| +| [`collection_adapter`](#collection_adapter) | Wraps the Base Class Library (BCL) collection as a range. | +| [`range_adapter`](#range_adapter) | Wraps the range as a BCL collection. | -|Function|Description| -|--------------|-----------------| -|[make_collection (STL/CLR)](#make_collection)|Creates a range adapter using an iterator pair.| +| Function | Description | +|---|---| +| [`make_collection`](#make_collection) | Creates a range adapter using an iterator pair. | ## Members -## collection_adapter (STL/CLR) +## `collection_adapter` Wraps a .NET collection for use as an STL/CLR container. A `collection_adapter` is a template class that describes a simple STL/CLR container object. It wraps a Base Class Library (BCL) interface, and returns an iterator pair that you use to manipulate the controlled sequence. @@ -75,52 +75,52 @@ template +*`Coll`*\ The type of the wrapped collection. ### Specializations -|Specialization|Description| -|--------------------|-----------------| -|IEnumerable|Sequences through elements.| -|ICollection|Maintains a group of elements.| -|IList|Maintains an ordered group of elements.| -|IDictionary|Maintain a set of {key, value} pairs.| -|IEnumerable\|Sequences through typed elements.| -|ICollection\|Maintains a group of typed elements.| -|IList\|Maintains an ordered group of typed elements.| -|IDictionary\|Maintains a set of typed {key, value} pairs.| +| Specialization | Description | +|---|---| +| `IEnumerable` | Sequences through elements. | +| `ICollection` | Maintains a group of elements. | +| `IList` | Maintains an ordered group of elements. | +| `IDictionary` | Maintain a set of {key, value} pairs. | +| `IEnumerable` | Sequences through typed elements. | +| `ICollection` | Maintains a group of typed elements. | +| `IList` | Maintains an ordered group of typed elements. | +| `IDictionary` | Maintains a set of typed {key, value} pairs. | ### Members -|Type Definition|Description| -|---------------------|-----------------| -|[collection_adapter::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[collection_adapter::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[collection_adapter::key_type (STL/CLR)](#key_type)|The type of a dictionary key.| -|[collection_adapter::mapped_type (STL/CLR)](#mapped_type)|The type of a dictionary value.| -|[collection_adapter::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[collection_adapter::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[collection_adapter::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[collection_adapter::base (STL/CLR)](#base)|Designates the wrapped BCL interface.| -|[collection_adapter::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[collection_adapter::collection_adapter (STL/CLR)](#collection_adapter_collection_adapter)|Constructs an adapter object.| -|[collection_adapter::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[collection_adapter::size (STL/CLR)](#size)|Counts the number of elements.| -|[collection_adapter::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| - -|Operator|Description| -|--------------|-----------------| -|[collection_adapter::operator= (STL/CLR)](#op_eq)|Replaces the stored BCL handle.| +| Type definition | Description | +|---|---| +| [`collection_adapter::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`collection_adapter::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`collection_adapter::key_type`](#key_type) | The type of a dictionary key. | +| [`collection_adapter::mapped_type`](#mapped_type) | The type of a dictionary value. | +| [`collection_adapter::reference`](#reference) | The type of a reference to an element. | +| [`collection_adapter::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`collection_adapter::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`collection_adapter::base`](#base) | Designates the wrapped BCL interface. | +| [`collection_adapter::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`collection_adapter::collection_adapter`](#collection_adapter_collection_adapter) | Constructs an adapter object. | +| [`collection_adapter::end`](#end) | Designates the end of the controlled sequence. | +| [`collection_adapter::size`](#size) | Counts the number of elements. | +| [`collection_adapter::swap`](#swap) | Swaps the contents of two containers. | + +| Operator | Description | +|---|---| +| [`collection_adapter::operator=`](#op_eq) | Replaces the stored BCL handle. | ### Remarks You use this template class to manipulate a BCL container as a STL/CLR container. The `collection_adapter` stores a handle to a BCL interface, which in turn controls a sequence of elements. A `collection_adapter` object `X` returns a pair of input iterators `X.begin()` and `X.end()` that you use to visit the elements, in order. Some of the specializations also let you write `X.size()` to determine the length of the controlled sequence. -## collection_adapter::base (STL/CLR) +## `collection_adapter::base` Designates the wrapped BCL interface. @@ -164,7 +164,7 @@ x x x x x x base() same = True ``` -## collection_adapter::begin (STL/CLR) +## `collection_adapter::begin` Designates the beginning of the controlled sequence. @@ -215,7 +215,7 @@ a b c *++begin() = b ``` -## collection_adapter::collection_adapter (STL/CLR) +## `collection_adapter::collection_adapter` Constructs an adapter object. @@ -230,10 +230,10 @@ collection_adapter(Coll^ collection); #### Parameters -*collection*
+*`collection`*\ BCL handle to wrap. -*right*
+*`right`*\ Object to copy. ### Remarks @@ -248,13 +248,13 @@ The constructor: `collection_adapter(collection_adapter% right);` -initializes the stored handle with `right.`[collection_adapter::base (STL/CLR)](#base)`()`. +initializes the stored handle with `right.base()`. The constructor: `collection_adapter(collection_adapter^ right);` -initializes the stored handle with `right->`[collection_adapter::base (STL/CLR)](#base)`()`. +initializes the stored handle with `right->base()`. The constructor: @@ -309,7 +309,7 @@ x x x x x x x x x x x x ``` -## collection_adapter::difference_type (STL/CLR) +## `collection_adapter::difference_type` The types of a signed distance between two elements. @@ -361,7 +361,7 @@ a b c end()-begin() = 3 ``` -## collection_adapter::end (STL/CLR) +## `collection_adapter::end` Designates the end of the controlled sequence. @@ -406,7 +406,7 @@ int main() a b c ``` -## collection_adapter::iterator (STL/CLR) +## `collection_adapter::iterator` The type of an iterator for the controlled sequence. @@ -451,7 +451,7 @@ int main() a b c ``` -## collection_adapter::key_type (STL/CLR) +## `collection_adapter::key_type` The type of a dictionary key. @@ -463,7 +463,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter `Key`, in a specialization for `IDictionary` or `IDictionary`; otherwise it is not defined. +The type is a synonym for the template parameter `Key`, in a specialization for `IDictionary` or `IDictionary`; otherwise it isn't defined. ### Example @@ -501,7 +501,7 @@ int main() [a 1] [b 2] [c 3] ``` -## collection_adapter::mapped_type (STL/CLR) +## `collection_adapter::mapped_type` The type of a dictionary value. @@ -513,7 +513,7 @@ typedef Value mapped_type; ### Remarks -The type is a synonym for the template parameter `Value`, in a specialization for `IDictionary` or `IDictionary`; otherwise it is not defined. +The type is a synonym for the template parameter `Value`, in a specialization for `IDictionary` or `IDictionary`; otherwise it isn't defined. ### Example @@ -551,7 +551,7 @@ int main() [a 1] [b 2] [c 3] ``` -## collection_adapter::operator= (STL/CLR) +## `collection_adapter::operator=` Replaces the stored BCL handle. @@ -563,12 +563,12 @@ collection_adapter% operator=(collection_adapter% right); #### Parameters -*right*
+*`right`*\ Adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored BCL handle with a copy of the stored BCL handle in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored BCL handle with a copy of the stored BCL handle in *`right`*. ### Example @@ -608,7 +608,7 @@ a b c a b c ``` -## collection_adapter::reference (STL/CLR) +## `collection_adapter::reference` The type of a reference to an element. @@ -656,7 +656,7 @@ int main() a b c ``` -## collection_adapter::size (STL/CLR) +## `collection_adapter::size` Counts the number of elements. @@ -668,7 +668,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. It is not defined in a specialization for `IEnumerable` or `IEnumerable`. +The member function returns the length of the controlled sequence. It isn't defined in a specialization for `IEnumerable` or `IEnumerable`. ### Example @@ -699,9 +699,9 @@ x x x x x x size() = 6 ``` -## collection_adapter::size_type (STL/CLR) +## `collection_adapter::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -744,7 +744,7 @@ x x x x x x size() = 6 ``` -## collection_adapter::swap (STL/CLR) +## `collection_adapter::swap` Swaps the contents of two containers. @@ -756,12 +756,12 @@ void swap(collection_adapter% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the stored BCL handles between **`*this`** and *right*. +The member function swaps the stored BCL handles between **`*this`** and *`right`*. ### Example @@ -813,7 +813,7 @@ x x x x x a b c ``` -## collection_adapter::value_type (STL/CLR) +## `collection_adapter::value_type` The type of an element. @@ -825,7 +825,7 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*, if present in the specialization; otherwise it is a synonym for `System::Object^`. +The type is a synonym for the template parameter *`Value`*, if present in the specialization; otherwise it's a synonym for `System::Object^`. ### Example @@ -875,18 +875,18 @@ template #### Parameters -*Iter*
+*`Iter`*\ The type of the wrapped iterators. -*first*
+*`first`*\ First iterator to wrap. -*last*
+*`last`*\ Second iterator to wrap. ### Remarks -The template function returns `gcnew range_adapter(first, last)`. You use it to construct a `range_adapter` object from a pair of iterators. +The function template returns `gcnew range_adapter(first, last)`. You use it to construct a `range_adapter` object from a pair of iterators. ### Example @@ -942,7 +942,7 @@ SyncRoot not nullptr = True ## range_adapter (STL/CLR) -A template class that wraps a pair of iterators that are used to implement several Base Class Library (BCL) interfaces. You use the range_adapter to manipulate an STL/CLR range as if it were a BCL collection. +A template class that wraps a pair of iterators that are used to implement several Base Class Library (BCL) interfaces. You use the range_adapter to manipulate an STL/CLR range as if it was a BCL collection. ### Syntax @@ -959,33 +959,33 @@ template #### Parameters -*Iter*
+*`Iter`*\ The type associated with the wrapped iterators. ### Members -|Member Function|Description| -|---------------------|-----------------| -|[range_adapter::range_adapter (STL/CLR)](#range_adapter_range_adapter)|Constructs an adapter object.| +| Member function | Description | +|---|---| +| [`range_adapter::range_adapter`](#range_adapter_range_adapter) | Constructs an adapter object. | -|Operator|Description| -|--------------|-----------------| -|[range_adapter::operator= (STL/CLR)](#range_adapter_op_eq)|Replaces the stored iterator pair.| +| Operator | Description | +|---|---| +| [`range_adapter::operator=`](#range_adapter_op_eq) | Replaces the stored iterator pair. | ### Interfaces -|Interface|Description| -|---------------|-----------------| -||Iterates through elements in the collection.| -||Maintains a group of elements.| -||Iterates through typed elements in the collection..| -||Maintains a group of typed elements.| +| Interface | Description | +|---|---| +| | Iterates through elements in the collection. | +| | Maintains a group of elements. | +| | Iterates through typed elements in the collection. | +| | Maintains a group of typed elements. | ### Remarks The range_adapter stores a pair of iterators, which in turn delimit a sequence of elements. The object implements four BCL interfaces that let you iterate through the elements, in order. You use this template class to manipulate STL/CLR ranges much like BCL containers. -## range_adapter::operator= (STL/CLR) +## `range_adapter::operator=` Replaces the stored iterator pair. @@ -997,12 +997,12 @@ range_adapter% operator=(range_adapter% right); #### Parameters -*right*
+*`right`*\ Adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored iterator pair with a copy of the stored iterator pair in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored iterator pair with a copy of the stored iterator pair in *`right`*. ### Example @@ -1042,7 +1042,7 @@ a b c a b c ``` -## range_adapter::range_adapter (STL/CLR) +## `range_adapter::range_adapter` Constructs an adapter object. @@ -1057,13 +1057,13 @@ range_adapter(Iter first, Iter last); #### Parameters -*first*
+*`first`*\ First iterator to wrap. -*last*
+*`last`*\ Second iterator to wrap. -*right*
+*`right`*\ Object to copy. ### Remarks @@ -1078,7 +1078,7 @@ The constructor: `range_adapter(range_adapter% right);` -initializes the stored iterator pair by copying the pair stored in *right*. +initializes the stored iterator pair by copying the pair stored in *`right`*. The constructor: @@ -1090,7 +1090,7 @@ The constructor: `range_adapter(Iter^ first, last);` -initializes the stored iterator pair with *first* and *last*. +initializes the stored iterator pair with *`first`* and *`last`*. ### Example diff --git a/docs/dotnet/algorithm-stl-clr.md b/docs/dotnet/algorithm-stl-clr.md index d719dd4ab4..7b08823a39 100644 --- a/docs/dotnet/algorithm-stl-clr.md +++ b/docs/dotnet/algorithm-stl-clr.md @@ -9,7 +9,7 @@ ms.assetid: ee2718dc-a98d-40b8-8341-593fe7d2ac15 --- # algorithm (STL/CLR) -Defines STL/CLR container template functions that perform algorithms. +Defines STL/CLR container function templates that perform algorithms. ## Syntax diff --git a/docs/dotnet/auto-gcroot-class.md b/docs/dotnet/auto-gcroot-class.md index 00b3976e16..073b6c06ab 100644 --- a/docs/dotnet/auto-gcroot-class.md +++ b/docs/dotnet/auto-gcroot-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: auto_gcroot Class" title: "auto_gcroot Class" +description: "Learn more about: auto_gcroot Class" ms.date: "01/16/2019" ms.topic: "reference" f1_keywords: ["msclr::auto_gcroot::auto_gcroot", "msclr::auto_gcroot::attach", "msclr::auto_gcroot::get", "msclr::auto_gcroot::release", "msclr::auto_gcroot::reset", "msclr::auto_gcroot::swap", "msclr::auto_gcroot::operator=", "msclr::auto_gcroot::operator->", "msclr::auto_gcroot::operator!", "msclr::auto_gcroot::operator auto_gcroot"] helpviewer_keywords: ["msclr::auto_gcroot"] -ms.assetid: b5790912-265d-463e-a486-47302e91042a --- # auto_gcroot Class @@ -20,7 +19,7 @@ class auto_gcroot; ### Parameters -*_element_type*
+*_element_type*\ The managed type to be embedded. ## Members @@ -30,8 +29,7 @@ The managed type to be embedded. |Name|Description| |---------|-----------| |[auto_gcroot::auto_gcroot](#auto-gcroot)|The `auto_gcroot` constructor.| -|[auto_gcroot::~auto_gcroot](#tilde-auto-gcroot)|The `auto_gcroot` destructor. -| +|[auto_gcroot::~auto_gcroot](#tilde-auto-gcroot)|The `auto_gcroot` destructor.| ### Public methods @@ -78,10 +76,10 @@ auto_gcroot( ### Parameters -*_ptr*
+*_ptr*\ The object to own. -*_right*
+*_right*\ An existing `auto_gcroot`. ### Remarks @@ -241,7 +239,7 @@ auto_gcroot<_element_type> & attach( ### Parameters -*_right*
+*_right*\ The object to attach, or an `auto_gcroot` containing the object to attach. ### Return value @@ -452,7 +450,7 @@ void reset( ### Parameters -*_new_ptr*
+*_new_ptr*\ (Optional) The new object. ### Example @@ -517,7 +515,7 @@ void swap( ### Parameters -*_right*
+*_right*\ The `auto_gcroot` with which to swap objects. ### Example @@ -615,7 +613,7 @@ auto_gcroot<_element_type> & operator=( ### Parameters -*_right*
+*_right*\ The object or `auto_gcroot` to be assigned to the current `auto_gcroot`. ### Return value diff --git a/docs/dotnet/cpp-stack-semantics-for-reference-types.md b/docs/dotnet/cpp-stack-semantics-for-reference-types.md index 83f5b0cccb..279b7584eb 100644 --- a/docs/dotnet/cpp-stack-semantics-for-reference-types.md +++ b/docs/dotnet/cpp-stack-semantics-for-reference-types.md @@ -29,7 +29,7 @@ A compiler-generated assignment operator will follow the usual standard C++ rule - Any non-static data member whose type is a value type will be shallow copied. -- Any non-static data member whose type is an instance of a reference type will invoke a call to the reference type’s copy constructor. +- Any non-static data member whose type is an instance of a reference type will invoke a call to the reference type's copy constructor. The compiler also provides a `%` unary operator to convert an instance of a reference type created using stack semantics to its underlying handle type. diff --git a/docs/dotnet/data-access-using-adonet-cpp-cli.md b/docs/dotnet/data-access-using-adonet-cpp-cli.md index 73c3d4e6c8..69724de4d5 100644 --- a/docs/dotnet/data-access-using-adonet-cpp-cli.md +++ b/docs/dotnet/data-access-using-adonet-cpp-cli.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Data Access Using ADO.NET (C++/CLI)" title: "Data Access Using ADO.NET (C++/CLI)" +description: "Learn more about: Data Access Using ADO.NET (C++/CLI)" ms.date: "11/04/2016" helpviewer_keywords: ["ADO.NET [C++]", ".NET Framework [C++], data access", "databases [C++], accessing in C++", "data access [C++], ADO.NET", "data [C++], ADO.NET", "native strings [C++]", "ADO.NET [C++], marshaling ANSI strings", "strings [C++], ADO.NET", "BSTRs, strings", "ADO.NET [C++], marshaling BSTR strings", "strings [C++], marshaling BSTR strings", "ADO.NET [C++], marshaling Unicode strings", "Unicode [C++], strings", "strings [C++], Unicode", "VARIANT, marshaling", "ADO.NET [C++], marshaling VARIANT types", "VARIANT", "SAFEARRAY, marshaling", "ADO.NET [C++], marshaling SAFEARRAY types"] -ms.assetid: b0cd987d-1ea7-4f76-ba01-cbd52503d06d --- # Data Access Using ADO.NET (C++/CLI) @@ -152,7 +151,7 @@ The rest of the code in this example is native C++ code, as is indicated by the > [!NOTE] > The memory allocated by must be deallocated by calling either or `SysFreeString`. -``` cpp +```cpp // adonet_marshal_string_bstr.cpp // compile with: /clr /FU System.dll /FU System.Data.dll /FU System.Xml.dll #include diff --git a/docs/dotnet/deque-stl-clr.md b/docs/dotnet/deque-stl-clr.md index b7e7be166a..9961dd1c21 100644 --- a/docs/dotnet/deque-stl-clr.md +++ b/docs/dotnet/deque-stl-clr.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: deque (STL/CLR)" title: "deque (STL/CLR)" +description: "Learn more about: deque (STL/CLR)" ms.date: "11/04/2016" ms.topic: "reference" f1_keywords: ["cliext::deque", "cliext::deque::assign", "cliext::deque::at", "cliext::deque::back", "cliext::deque::back_item", "cliext::deque::begin", "cliext::deque::clear", "cliext::deque::const_iterator", "cliext::deque::const_reference", "cliext::deque::const_reverse_iterator", "cliext::deque::deque", "cliext::deque::difference_type", "cliext::deque::empty", "cliext::deque::end", "cliext::deque::erase", "cliext::deque::front", "cliext::deque::front_item", "cliext::deque::generic_container", "cliext::deque::generic_iterator", "cliext::deque::generic_reverse_iterator", "cliext::deque::generic_value", "cliext::deque::insert", "cliext::deque::iterator", "cliext::deque::operator!=", "cliext::deque::operator[]", "cliext::deque::pop_back", "cliext::deque::pop_front", "cliext::deque::push_back", "cliext::deque::push_front", "cliext::deque::rbegin", "cliext::deque::reference", "cliext::deque::rend", "cliext::deque::resize", "cliext::deque::reverse_iterator", "cliext::deque::size", "cliext::deque::size_type", "cliext::deque::swap", "cliext::deque::to_array", "cliext::deque::value_type", "cliext::deque::operator<", "cliext::deque::operator<=", "cliext::deque::operator=", "cliext::deque::operator==", "cliext::deque::operator>", "cliext::deque::operator>="] helpviewer_keywords: ["deque class [STL/CLR]", " header [STL/CLR]", " header [STL/CLR]", "assign member [STL/CLR]", "assign member [STL/CLR]", "at member [STL/CLR]", "back member [STL/CLR]", "back_item member [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "deque member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "erase member [STL/CLR]", "front member [STL/CLR]", "front_item member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "operator!= member [STL/CLR]", "operator member [] [STL/CLR]", "pop_back member [STL/CLR]", "pop_front member [STL/CLR]", "push_back member [STL/CLR]", "push_front member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "resize member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "value_type member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]"] -ms.assetid: dd669da3-3c0e-45e9-8596-f6b483720941 --- # deque (STL/CLR) @@ -561,7 +560,7 @@ a b c ## deque::const_reverse_iterator (STL/CLR) -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax diff --git a/docs/dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md b/docs/dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md index 2109d30ace..5306b90a11 100644 --- a/docs/dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md +++ b/docs/dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md @@ -1,11 +1,15 @@ --- title: ".NET programming with C++/CLI" description: "Learn how to use C++/CLI to create .NET apps and components in Visual Studio." -ms.date: 10/28/2021 +ms.date: 05/02/2025 helpviewer_keywords: ["programming [C++], .NET programming", ".NET Framework [C++]", ".NET applications [C++]", "Visual C++, .NET programming"] --- # .NET programming with C++/CLI +C++/CLI supplanted Managed C++. C++/CLI is a language specification created by Microsoft that extends C++ to support .NET. It's only supported on Windows. It's not for writing [WinUI](/windows/apps/winui) or Universal Windows Platform [UWP](/windows/uwp/get-started/universal-application-platform-guide) Windows Runtime (WinRT) apps. It's for writing .NET applications and components that run on .NET. C++/CLI is a bridge between native C++ code and managed code. It allows you to use existing C++ libraries in .NET applications and to write new .NET applications in C++. + +Microsoft provides C++/WinRT for writing WinUI and WinRT apps. It's an entirely standard modern C++17 language projection for Windows Runtime (WinRT) APIs. For more information about using C++ with the Windows Runtime (WinRT), see [C++/WinRT](/windows/uwp/cpp-and-winrt-apis/). + ::: moniker range="msvc-140" By default, CLR projects created with Visual Studio 2015 target .NET Framework 4.5.2. You can target .NET Framework 4.6 when you create a new project. In the **New Project** dialog, change the target framework in the dropdown at the top middle of the dialog. To change the target framework for an existing project, close the project, edit the project file (*`.vcxproj`*), and change the value of the Target Framework Version to 4.6. The changes take effect the next time you open the project. @@ -41,40 +45,23 @@ C++/CLI itself isn't installed by default when you install a Visual Studio C++ w ## In this section -[C++/CLI tasks](../dotnet/cpp-cli-tasks.md) - -[Native and .NET interoperability](../dotnet/native-and-dotnet-interoperability.md) - -[Pure and verifiable code (C++/CLI)](../dotnet/pure-and-verifiable-code-cpp-cli.md) - -[Regular expressions (C++/CLI)](../dotnet/regular-expressions-cpp-cli.md) - -[File handling and I/O (C++/CLI)](../dotnet/file-handling-and-i-o-cpp-cli.md) - -[Graphics operations (C++/CLI)](../dotnet/graphics-operations-cpp-cli.md) - -[Windows operations (C++/CLI)](../dotnet/windows-operations-cpp-cli.md) - -[Data access using ADO.NET (C++/CLI)](../dotnet/data-access-using-adonet-cpp-cli.md) - -[Interoperability with other .NET languages (C++/CLI)](../dotnet/interoperability-with-other-dotnet-languages-cpp-cli.md) - -[Serialization (C++/CLI)](../dotnet/serialization-cpp-cli.md) - -[Managed types (C++/CLI)](../dotnet/managed-types-cpp-cli.md) - -[Reflection (C++/CLI)](../dotnet/reflection-cpp-cli.md) - -[Strong Name assemblies (assembly signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) - -[Debug class (C++/CLI)](../dotnet/debug-class-cpp-cli.md) - -[STL/CLR library reference](../dotnet/stl-clr-library-reference.md) - -[C++ support library](../dotnet/cpp-support-library.md) - -[Exceptions in C++/CLI](../dotnet/exceptions-in-cpp-cli.md) - +[C++/CLI tasks](../dotnet/cpp-cli-tasks.md)\ +[Native and .NET interoperability](../dotnet/native-and-dotnet-interoperability.md)\ +[Pure and verifiable code (C++/CLI)](../dotnet/pure-and-verifiable-code-cpp-cli.md)\ +[Regular expressions (C++/CLI)](../dotnet/regular-expressions-cpp-cli.md)\ +[File handling and I/O (C++/CLI)](../dotnet/file-handling-and-i-o-cpp-cli.md)\ +[Graphics operations (C++/CLI)](../dotnet/graphics-operations-cpp-cli.md)\ +[Windows operations (C++/CLI)](../dotnet/windows-operations-cpp-cli.md)\ +[Data access using ADO.NET (C++/CLI)](../dotnet/data-access-using-adonet-cpp-cli.md)\ +[Interoperability with other .NET languages (C++/CLI)](../dotnet/interoperability-with-other-dotnet-languages-cpp-cli.md)\ +[Serialization (C++/CLI)](../dotnet/serialization-cpp-cli.md)\ +[Managed types (C++/CLI)](../dotnet/managed-types-cpp-cli.md)\ +[Reflection (C++/CLI)](../dotnet/reflection-cpp-cli.md)\ +[Strong Name assemblies (assembly signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md)\ +[Debug class (C++/CLI)](../dotnet/debug-class-cpp-cli.md)\ +[STL/CLR library reference](../dotnet/stl-clr-library-reference.md)\ +[C++ support library](../dotnet/cpp-support-library.md)\ +[Exceptions in C++/CLI](../dotnet/exceptions-in-cpp-cli.md)\ [Boxing (C++/CLI)](../dotnet/boxing-cpp-cli.md) ## See also diff --git a/docs/dotnet/for-each-in.md b/docs/dotnet/for-each-in.md index 9d7743eed0..51f9e9fe17 100644 --- a/docs/dotnet/for-each-in.md +++ b/docs/dotnet/for-each-in.md @@ -1,43 +1,42 @@ --- title: "for each, in" -description: "C++/CLI for each, in statement description and examples." -ms.date: 09/25/2020 +description: "C++/CLI for each, in, statement descriptions and examples." +ms.date: 06/29/2023 ms.topic: "reference" -f1_keywords: ["cliext::foreach", "for", "each", "in"] +f1_keywords: ["cliext::foreach", "each_CPP", "in_CPP", "for each_CPP", "for each", "in"] helpviewer_keywords: ["for each keyword [C++]"] -ms.assetid: 0c3a364b-2747-43f3-bb8d-b7d3b7023f79 --- -# for each, in +# `for each`, `in` -Iterates through an array or collection. This non-standard keyword is available in both C++/CLI and native C++ projects. However, its use isn't recommended. Consider using a standard [Range-based for Statement (C++)](../cpp/range-based-for-statement-cpp.md) instead. +Iterates through an array or collection. This nonstandard keyword is available in both C++/CLI and native C++ projects. However, using a standard [Range-based for Statement (C++)](../cpp/range-based-for-statement-cpp.md) is preferred, instead. -## All Runtimes +## All runtimes ### Syntax -> **for each (** *type* *identifier* **in** *expression* **) {**\ ->     *statements*\ -> **}** +> **`for each (`** *`type`* *`identifier`* **`in`** *`expression`* **`) {`**\ +>  *`statements`*\ +> **`}`** ### Parameters -*type*
+*`type`*\ The type of `identifier`. -*identifier*
+*`identifier`*\ The iteration variable that represents the collection element. When `identifier` is a [Tracking Reference Operator](../extensions/tracking-reference-operator-cpp-component-extensions.md), you can modify the element. -*expression*
+*`expression`*\ An array expression or collection. The collection element must be such that the compiler can convert it to the `identifier` type. -*statements*
+*`statements`*\ One or more statements to be executed. ### Remarks The `for each` statement is used to iterate through a collection. You can modify elements in a collection, but you can't add or delete elements. -The *statements* are executed for each element in the array or collection. After the iteration has been completed for all the elements in the collection, control is transferred to the statement that follows the `for each` block. +The *`statements`* are executed for each element in the array or collection. After the iteration has been completed for all the elements in the collection, control is transferred to the statement that follows the `for each` block. `for each` and `in` are [context-sensitive keywords](../extensions/context-sensitive-keywords-cpp-component-extensions.md). @@ -45,7 +44,7 @@ The *statements* are executed for each element in the array or collection. After ### Requirements -Compiler option: **/ZW** +Compiler option: **`/ZW`** ### Example @@ -57,29 +56,34 @@ This example shows how to use `for each` to iterate through a string. #include using namespace Platform; -ref struct MyClass { +ref struct MyClass +{ property String^ MyStringProperty; }; -int main() { +int main() +{ String^ MyString = ref new String("abcd"); for each ( char c in MyString ) + { wprintf("%c", c); + } - wprintf("/n"); + wprintf("\n"); MyClass^ x = ref new MyClass(); x->MyStringProperty = "Testing"; for each( char c in x->MyStringProperty ) + { wprintf("%c", c); + } } ``` ```Output abcd - Testing ``` @@ -89,14 +93,14 @@ Testing The CLR syntax is the same as the **All Runtimes** syntax, except as follows. -*expression*
-A managed array expression or collection. The collection element must be such that the compiler can convert it from to the *identifier* type. +*`expression`*\ +A managed array expression or collection. The collection element must be such that the compiler can convert it from to the *`identifier`* type. -*expression* evaluates to a type that implements , , or a type that defines a `GetEnumerator` method that either returns a type that implements or declares all of the methods that are defined in `IEnumerator`. +*`expression`* evaluates to a type that implements , , or a type that defines a `GetEnumerator` method that either returns a type that implements or declares all of the methods that are defined in `IEnumerator`. ### Requirements -Compiler option: **/clr** +Compiler option: **`/clr`** ### Example @@ -107,29 +111,34 @@ This example shows how to use `for each` to iterate through a string. // compile with: /clr using namespace System; -ref struct MyClass { +ref struct MyClass +{ property String ^ MyStringProperty; }; -int main() { +int main() +{ String ^ MyString = gcnew String("abcd"); for each ( Char c in MyString ) + { Console::Write(c); + } Console::WriteLine(); - MyClass ^ x = gcnew MyClass(); + MyClass ^x = gcnew MyClass(); x->MyStringProperty = "Testing"; for each( Char c in x->MyStringProperty ) + { Console::Write(c); + } } ``` ```Output abcd - Testing ``` diff --git a/docs/dotnet/functional-stl-clr.md b/docs/dotnet/functional-stl-clr.md index 194249db4d..a47621cd29 100644 --- a/docs/dotnet/functional-stl-clr.md +++ b/docs/dotnet/functional-stl-clr.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: functional (STL/CLR)" title: "functional (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: functional (STL/CLR)" +ms.date: 09/28/2022 ms.topic: "reference" f1_keywords: ["", "cliext::binary_delegate", "cliext::binary_delegate_noreturn", "cliext::binary_negate", "cliext::bind1st", "cliext::bind2nd", "cliext::binder1st", "cliext::binder2nd", "cliext::divides", "cliext::equal_to", "cliext::greater", "cliext::greater_equal", "cliext::less", "cliext::less_equal", "cliext::logical_and", "cliext::logical_not", "cliext::logical_or", "cliext::minus", "cliext::modulus", "cliext::multiplies", "cliext::negate", "cliext::not_equal_to", "cliext::not1", "cliext::not2", "cliext::plus", "cliext::unary_delegate", "cliext::unary_delegate_noreturn", "cliext::unary_negate"] helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "functional functions [STL/CLR]", "binary_delegate function [STL/CLR]", "binary_delegate_noreturn function [STL/CLR]", "binary_negate function [STL/CLR]", "bind1st function [STL/CLR]", "bind2nd function [STL/CLR]", "binder1st function [STL/CLR]", "binder2nd function [STL/CLR]", "divides function [STL/CLR]", "equal_to function [STL/CLR]", "greater function [STL/CLR]", "greater_equal function [STL/CLR]", "less function [STL/CLR]", "less_equal function [STL/CLR]", "logical_and function [STL/CLR]", "logical_not function [STL/CLR]", "logical_or function [STL/CLR]", "minus function [STL/CLR]", "modulus function [STL/CLR]", "multiplies function [STL/CLR]", "negate function [STL/CLR]", "not_equal_to function [STL/CLR]", "not1 function [STL/CLR]", "not2 function [STL/CLR]", "plus function [STL/CLR]", "unary_delegate function [STL/CLR]", "unary_delegate_noreturn function [STL/CLR]", "unary_negate function [STL/CLR]"] -ms.assetid: 88738b8c-5d37-4375-970e-a4442bf5efde --- -# functional (STL/CLR) +# `functional` (STL/CLR) -Include the STL/CLR header `` to define the a number of template classes and related template delegates and functions. +Include the STL/CLR header `` to define functional class templates and related template delegates and functions. ## Syntax @@ -21,51 +20,51 @@ Include the STL/CLR header `` to define the a number of templ **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Delegate|Description| -|--------------|-----------------| -|[binary_delegate (STL/CLR)](#binary_delegate)|Two-argument delegate.| -|[binary_delegate_noreturn (STL/CLR)](#binary_delegate_noreturn)|Two-argument delegate returning **`void`**.| -|[unary_delegate (STL/CLR)](#unary_delegate)|One-argument delegate.| -|[unary_delegate_noreturn (STL/CLR)](#unary_delegate_noreturn)|One-argument delegate returning **`void`**.| - -|Class|Description| -|-----------|-----------------| -|[binary_negate (STL/CLR)](#binary_negate)|Functor to negate a two-argument functor.| -|[binder1st (STL/CLR)](#binder1st)|Functor to bind first argument to a two-argument functor.| -|[binder2nd (STL/CLR)](#binder2nd)|Functor to bind second argument to a two-argument functor.| -|[divides (STL/CLR)](#divides)|Divide functor.| -|[equal_to (STL/CLR)](#equal_to)|Equal comparison functor.| -|[greater (STL/CLR)](#greater)|Greater comparison functor.| -|[greater_equal (STL/CLR)](#greater_equal)|Greater or equal comparison functor.| -|[less (STL/CLR)](#less)|Less comparison functor.| -|[less_equal (STL/CLR)](#less_equal)|Less or equal comparison functor.| -|[logical_and (STL/CLR)](#logical_and)|Logical AND functor.| -|[logical_not (STL/CLR)](#logical_not)|Logical NOT functor.| -|[logical_or (STL/CLR)](#logical_or)|Logical OR functor.| -|[minus (STL/CLR)](#minus)|Subtract functor.| -|[modulus (STL/CLR)](#modulus)|Modulus functor.| -|[multiplies (STL/CLR)](#multiplies)|Multiply functor.| -|[negate (STL/CLR)](#negate)|Functor to return its argument negated.| -|[not_equal_to (STL/CLR)](#not_equal_to)|Not equal comparison functor.| -|[plus (STL/CLR)](#plus)|Add functor.| -|[unary_negate (STL/CLR)](#unary_negate)|Functor to negate a one-argument functor.| - -|Function|Description| -|--------------|-----------------| -|[bind1st (STL/CLR)](#bind1st)|Generates a binder1st for an argument and functor.| -|[bind2nd (STL/CLR)](#bind2nd)|Generates a binder2nd for an argument and functor.| -|[not1 (STL/CLR)](#not1)|Generates a unary_negate for a functor.| -|[not2 (STL/CLR)](#not2)|Generates a binary_negate for a functor.| +| Delegate | Description | +|--|--| +| [`binary_delegate` (STL/CLR)](#binary_delegate) | Two-argument delegate. | +| [`binary_delegate_noreturn` (STL/CLR)](#binary_delegate_noreturn) | Two-argument delegate returning **`void`**. | +| [`unary_delegate` (STL/CLR)](#unary_delegate) | One-argument delegate. | +| [`unary_delegate_noreturn` (STL/CLR)](#unary_delegate_noreturn) | One-argument delegate returning **`void`**. | + +| Class | Description | +|--|--| +| [`binary_negate` (STL/CLR)](#binary_negate) | Functor to negate a two-argument functor. | +| [`binder1st` (STL/CLR)](#binder1st) | Functor to bind first argument to a two-argument functor. | +| [`binder2nd` (STL/CLR)](#binder2nd) | Functor to bind second argument to a two-argument functor. | +| [`divides` (STL/CLR)](#divides) | Divide functor. | +| [`equal_to` (STL/CLR)](#equal_to) | Equal comparison functor. | +| [`greater` (STL/CLR)](#greater) | Greater comparison functor. | +| [`greater_equal` (STL/CLR)](#greater_equal) | Greater or equal comparison functor. | +| [`less` (STL/CLR)](#less) | Less comparison functor. | +| [`less_equal` (STL/CLR)](#less_equal) | Less or equal comparison functor. | +| [`logical_and` (STL/CLR)](#logical_and) | Logical AND functor. | +| [`logical_not` (STL/CLR)](#logical_not) | Logical NOT functor. | +| [`logical_or` (STL/CLR)](#logical_or) | Logical OR functor. | +| [`minus` (STL/CLR)](#minus) | Subtract functor. | +| [`modulus` (STL/CLR)](#modulus) | Modulus functor. | +| [`multiplies` (STL/CLR)](#multiplies) | Multiply functor. | +| [`negate` (STL/CLR)](#negate) | Functor to return its argument negated. | +| [`not_equal_to` (STL/CLR)](#not_equal_to) | Not equal comparison functor. | +| [`plus` (STL/CLR)](#plus) | Add functor. | +| [`unary_negate` (STL/CLR)](#unary_negate) | Functor to negate a one-argument functor. | + +| Function | Description | +|--|--| +| [`bind1st` (STL/CLR)](#bind1st) | Generates a binder1st for an argument and functor. | +| [`bind2nd` (STL/CLR)](#bind2nd) | Generates a binder2nd for an argument and functor. | +| [`not1` (STL/CLR)](#not1) | Generates a unary_negate for a functor. | +| [`not2` (STL/CLR)](#not2) | Generates a binary_negate for a functor. | ## Members -## binary_delegate (STL/CLR) +## `binary_delegate` (STL/CLR) -The genereic class describes a two-argument delegate. You use it specify a delegate in terms of its argument and return types. +The generic class describes a two-argument delegate. You use it specify a delegate in terms of its argument and return types. ### Syntax @@ -78,20 +77,20 @@ generic +*`Arg1`*\ The type of the first argument. -*Arg2*
+*`Arg2`*\ The type of the second argument. -*Result*
+*`Result`*\ The return type. ### Remarks -The genereic delegate describes a two-argument function. +The generic delegate describes a two-argument function. -Note that for: +In these function templates: `binary_delegate Fun1;` @@ -103,7 +102,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate int Fun2(int, int);` -they are not the same type. +they aren't the same type. ### Example @@ -139,9 +138,9 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## binary_delegate_noreturn (STL/CLR) +## `binary_delegate_noreturn` (STL/CLR) -The genereic class describes a two-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument. +The generic class describes a two-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument. ### Syntax @@ -153,17 +152,17 @@ generic +*`Arg1`*\ The type of the first argument. -*Arg2*
+*`Arg2`*\ The type of the second argument. ### Remarks -The genereic delegate describes a two-argument function that returns **`void`**. +The generic delegate describes a two-argument function that returns **`void`**. -Note that for: +In these function templates: `binary_delegate_noreturn Fun1;` @@ -175,7 +174,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate void Fun2(int, int);` -they are not the same type. +they aren't the same type. ### Example @@ -209,7 +208,7 @@ compare(a, b) = True compare(b, a) = False ``` -## binary_negate (STL/CLR) +## `binary_negate` (STL/CLR) The template class describes a functor that, when called, returns the logical NOT of its stored two-argument functor. You use it specify a function object in terms of its stored functor. @@ -239,27 +238,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binary_negate|Constructs the functor.| +|`binary_negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -323,7 +322,7 @@ int main() 1 0 ``` -## bind1st (STL/CLR) +## `bind1st` (STL/CLR) Generates a `binder1st` for an argument and functor. @@ -338,23 +337,23 @@ template +*`Arg`*\ The type of the argument. -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. -*left*
+*`left`*\ The first argument to wrap. ### Remarks -The template function returns [binder1st (STL/CLR)](#binder1st)`(functor, left)`. You use it as a convenient way to wrap a two-argument functor and its first argument in a one-argument functor that calls it with a second argument. +The function template returns [`binder1st(functor, left)`](#binder1st). You use it as a convenient way to wrap a two-argument functor and its first argument in a one-argument functor that calls it with a second argument. ### Example @@ -404,7 +403,7 @@ int main() -1 0 ``` -## bind2nd (STL/CLR) +## `bind2nd` (STL/CLR) Generates a `binder2nd` for an argument and functor. @@ -419,23 +418,23 @@ template +*`Arg`*\ The type of the argument. -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. -*right*
+*`right`*\ The second argument to wrap. ### Remarks -The template function returns [binder2nd (STL/CLR)](#binder2nd)`(functor, right)`. You use it as a convenient way to wrap a two-argument functor and its second argument in a one-argument functor that calls it with a first argument. +The function template returns [`binder2nd(functor, right)`](#binder2nd). You use it as a convenient way to wrap a two-argument functor and its second argument in a one-argument functor that calls it with a first argument. ### Example @@ -485,7 +484,7 @@ int main() 0 -1 ``` -## binder1st (STL/CLR) +## `binder1st` (STL/CLR) The template class describes a one-argument functor that, when called, returns its stored two-argument functor called with its stored first argument and the supplied second argument. You use it specify a function object in terms of its stored functor. @@ -499,7 +498,7 @@ public: typedef Fun stored_function_type; typedef typename Fun::first_argument_type first_argument_type; typedef typename Fun::second_argument_type second_argument_type; - typedef typename Fun:result_type result_type; + typedef typename Fun::result_type result_type; typedef Microsoft::VisualC::StlClr::UnaryDelegate< second_argument_type, result_type> delegate_type; @@ -514,27 +513,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binder1st|Constructs the functor.| +|`binder1st`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -590,7 +589,7 @@ int main() -1 0 ``` -## binder2nd (STL/CLR) +## `binder2nd` (STL/CLR) The template class describes a one-argument functor that, when called, returns its stored two-argument functor called with the supplied first argument and its stored second argument. You use it specify a function object in terms of its stored functor. @@ -604,7 +603,7 @@ public: typedef Fun stored_function_type; typedef typename Fun::first_argument_type first_argument_type; typedef typename Fun::second_argument_type second_argument_type; - typedef typename Fun:result_type result_type; + typedef typename Fun::result_type result_type; typedef Microsoft::VisualC::StlClr::UnaryDelegate< first_argument_type, result_type> delegate_type; @@ -619,27 +618,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binder2nd|Constructs the functor.| +|`binder2nd`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -695,7 +694,7 @@ int main() 0 -1 ``` -## divides (STL/CLR) +## `divides` (STL/CLR) The template class describes a functor that, when called, returns the first argument divided by the second. You use it specify a function object in terms of its argument type. @@ -724,26 +723,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|divides|Constructs the functor.| +|`divides`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -796,7 +795,7 @@ int main() 2 3 ``` -## equal_to (STL/CLR) +## `equal_to` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is equal to the second. You use it specify a function object in terms of its argument type. @@ -825,26 +824,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|equal_to|Constructs the functor.| +|`equal_to`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -897,7 +896,7 @@ int main() 1 0 ``` -## greater (STL/CLR) +## `greater` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is greater than the second. You use it specify a function object in terms of its argument type. @@ -926,26 +925,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|greater|Constructs the functor.| +|`greater`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -998,7 +997,7 @@ int main() 1 0 ``` -## greater_equal (STL/CLR) +## `greater_equal` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is greater than or equal to the second. You use it specify a function object in terms of its argument type. @@ -1027,26 +1026,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|greater_equal|Constructs the functor.| +|`greater_equal`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1099,7 +1098,7 @@ int main() 1 0 ``` -## less (STL/CLR) +## `less` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is less than the second. You use it specify a function object in terms of its argument type. @@ -1128,26 +1127,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|less|Constructs the functor.| +|`less`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1200,7 +1199,7 @@ int main() 0 1 ``` -## less_equal (STL/CLR) +## `less_equal` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is less than or equal to the second. You use it specify a function object in terms of its argument type. @@ -1229,26 +1228,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|less_equal|Constructs the functor.| +|`less_equal`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1301,7 +1300,7 @@ int main() 0 1 ``` -## logical_and (STL/CLR) +## `logical_and` (STL/CLR) The template class describes a functor that, when called, returns true only if both the first argument and the second test as true. You use it specify a function object in terms of its argument type. @@ -1330,26 +1329,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|logical_and|Constructs the functor.| +|`logical_and`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1402,7 +1401,7 @@ int main() 1 0 ``` -## logical_not (STL/CLR) +## `logical_not` (STL/CLR) The template class describes a functor that, when called, returns true only if either its argument tests as false. You use it specify a function object in terms of its argument type. @@ -1429,25 +1428,25 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|logical_not|Constructs the functor.| +|`logical_not`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1492,7 +1491,7 @@ int main() 0 1 ``` -## logical_or (STL/CLR) +## `logical_or` (STL/CLR) The template class describes a functor that, when called, returns true only if either the first argument or the second tests as true. You use it specify a function object in terms of its argument type. @@ -1521,26 +1520,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|logical_or|Constructs the functor.| +|`logical_or`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1593,7 +1592,7 @@ int main() 1 0 ``` -## minus (STL/CLR) +## `minus` (STL/CLR) The template class describes a functor that, when called, returns the first argument minus the second. You use it specify a function object in terms of its argument type. @@ -1622,26 +1621,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|minus|Constructs the functor.| +|`minus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1694,7 +1693,7 @@ int main() 2 2 ``` -## modulus (STL/CLR) +## `modulus` (STL/CLR) The template class describes a functor that, when called, returns the first argument modulo the second. You use it specify a function object in terms of its argument type. @@ -1723,26 +1722,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|modulus|Constructs the functor.| +|`modulus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1795,7 +1794,7 @@ int main() 1 0 ``` -## multiplies (STL/CLR) +## `multiplies` (STL/CLR) The template class describes a functor that, when called, returns the first argument times the second. You use it specify a function object in terms of its argument type. @@ -1824,26 +1823,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|multiplies|Constructs the functor.| +|`multiplies`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1896,7 +1895,7 @@ int main() 8 3 ``` -## negate (STL/CLR) +## `negate` (STL/CLR) The template class describes a functor that, when called, returns its argument negated. You use it specify a function object in terms of its argument type. @@ -1923,25 +1922,25 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|negate|Constructs the functor.| +|`negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1986,9 +1985,9 @@ int main() -4 3 ``` -## not_equal_to (STL/CLR) +## `not_equal_to` (STL/CLR) -The template class describes a functor that, when called, returns true only if the first argument is not equal to the second. You use it specify a function object in terms of its argument type. +The template class describes a functor that, when called, returns true only if the first argument isn't equal to the second. You use it specify a function object in terms of its argument type. ### Syntax @@ -2015,30 +2014,30 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|not_equal_to|Constructs the functor.| +|`not_equal_to`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks -The template class describes a two-argument functor. It defines the member operator `operator()` so that, when the object is called as a function, it returns true only if the first argument is not equal to the second. +The template class describes a two-argument functor. It defines the member operator `operator()` so that, when the object is called as a function, it returns true only if the first argument isn't equal to the second. You can also pass the object as a function argument whose type is `delegate_type^` and it will be converted appropriately. @@ -2087,7 +2086,7 @@ int main() 0 1 ``` -## not1 (STL/CLR) +## `not1` (STL/CLR) Generates a `unary_negate` for a functor. @@ -2100,17 +2099,17 @@ template #### Template Parameters -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. ### Remarks -The template function returns [unary_negate (STL/CLR)](#unary_negate)`(functor)`. You use it as a convenient way to wrap a one-argument functor in a functor that delivers its logical NOT. +The function template returns [`unary_negate(functor)`](#unary_negate). You use it as a convenient way to wrap a one-argument functor in a functor that delivers its logical NOT. ### Example @@ -2159,7 +2158,7 @@ int main() 1 0 ``` -## not2 (STL/CLR) +## `not2` (STL/CLR) Generates a `binary_negate` for a functor. @@ -2172,17 +2171,17 @@ template #### Template Parameters -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. ### Remarks -The template function returns [binary_negate (STL/CLR)](#negate)`(functor)`. You use it as a convenient way to wrap a two-argument functor in a functor that delivers its logical NOT. +The function template returns [`binary_negate(functor)`](#negate). You use it as a convenient way to wrap a two-argument functor in a functor that delivers its logical NOT. ### Example @@ -2240,7 +2239,7 @@ int main() 1 0 ``` -## plus (STL/CLR) +## `plus` (STL/CLR) The template class describes a functor that, when called, returns the first argument plus the second. You use it specify a function object in terms of its argument type. @@ -2269,26 +2268,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|plus|Constructs the functor.| +|`plus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -2341,9 +2340,9 @@ int main() 6 4 ``` -## unary_delegate (STL/CLR) +## `unary_delegate` (STL/CLR) -The genereic class describes a one-argument delegate. You use it specify a delegate in terms of its argument and return types. +The generic class describes a one-argument delegate. You use it specify a delegate in terms of its argument and return types. ### Syntax @@ -2355,21 +2354,21 @@ generic +*`Arg`*\ The type of the argument. -*Result*
+*`Result`*\ The return type. ### Remarks -The genereic delegate describes a one-argument function. +The generic delegate describes a one-argument function. -Note that for: +In these function templates: -`unary_delegare Fun1;` +`unary_delegate Fun1;` -`unary_delegare Fun2;` +`unary_delegate Fun2;` the types `Fun1` and `Fun2` are synonyms, while for: @@ -2377,7 +2376,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate int Fun2(int);` -they are not the same type. +they aren't the same type. ### Example @@ -2407,9 +2406,9 @@ hash(L'a') = 5 hash(L'b') = 22 ``` -## unary_delegate_noreturn (STL/CLR) +## `unary_delegate_noreturn` (STL/CLR) -The genereic class describes a one-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument type. +The generic class describes a one-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument type. ### Syntax @@ -2420,18 +2419,18 @@ generic #### Parameters -*Arg*
+*`Arg`*\ The type of the argument. ### Remarks -The genereic delegate describes a one-argument function that returns **`void`**. +The generic delegate describes a one-argument function that returns **`void`**. -Note that for: +In these function templates: -`unary_delegare_noreturn Fun1;` +`unary_delegate_noreturn Fun1;` -`unary_delegare_noreturn Fun2;` +`unary_delegate_noreturn Fun2;` the types `Fun1` and `Fun2` are synonyms, while for: @@ -2439,7 +2438,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate void Fun2(int);` -they are not the same type. +they aren't the same type. ### Example @@ -2470,7 +2469,7 @@ hash(a) = 5 hash(b) = 22 ``` -## unary_negate (STL/CLR) +## `unary_negate` (STL/CLR) The template class describes a functor that, when called, returns the logical NOT of its stored one-argument functor. You use it specify a function object in terms of its stored functor. @@ -2498,25 +2497,25 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|unary_negate|Constructs the functor.| +|`unary_negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`delegate_type^`|Casts the functor to a delegate.| ### Remarks diff --git a/docs/dotnet/hash-map-stl-clr.md b/docs/dotnet/hash-map-stl-clr.md index c824be59ad..b7d55f2553 100644 --- a/docs/dotnet/hash-map-stl-clr.md +++ b/docs/dotnet/hash-map-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::hash_map", "cliext::hash_map::begin", "cliext::hash_map:: helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "hash_map class [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_map member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: c3cfc69b-04c6-42ae-a30e-0eda953fe883 --- -# hash_map (STL/CLR) +# `hash_map` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_map` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as `Key` unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as `Key` unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as `Mapped` unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as `Mapped` unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -41,123 +41,123 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_map::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_map::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_map::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_map::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_map::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_map::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_map::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_map::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_map::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_map::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_map::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_map::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_map::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[hash_map::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_map::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_map::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_map::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_map::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_map::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_map::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_map::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_map::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_map::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_map::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_map::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_map::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_map::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_map::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_map::hash_map (STL/CLR)](#hash_map)|Constructs a container object.| -|[hash_map::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_map::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_map::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_map::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_map::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_map::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_map::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_map::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_map::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_map::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_map::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_map::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_map::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_map::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_map::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[hash_map::operator(STL/CLR)](#op)|Maps a key to its associated mapped value.| +| Type definition | Description | +|---|---| +| [`hash_map::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_map::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_map::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_map::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_map::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_map::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_map::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_map::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_map::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_map::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_map::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_map::key_type`](#key_type) | The type of an ordering key. | +| [`hash_map::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`hash_map::reference`](#reference) | The type of a reference to an element. | +| [`hash_map::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_map::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_map::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_map::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_map::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_map::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_map::clear`](#clear) | Removes all elements. | +| [`hash_map::count`](#count) | Counts elements matching a specified key. | +| [`hash_map::empty`](#empty) | Tests whether no elements are present. | +| [`hash_map::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_map::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_map::erase`](#erase) | Removes elements at specified positions. | +| [`hash_map::find`](#find) | Finds an element that matches a specified key. | +| [`hash_map::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_map::hash_map`](#hash_map) | Constructs a container object. | +| [`hash_map::insert`](#insert) | Adds elements. | +| [`hash_map::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_map::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_map::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_map::make_value`](#make_value) | Constructs a value object. | +| [`hash_map::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_map::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_map::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_map::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_map::size`](#size) | Counts the number of elements. | +| [`hash_map::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_map::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_map::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_map::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_map::operator=`](#op_as) | Replaces the controlled sequence. | +| [`hash_map::operator[]`](#op) | Maps a key to its associated mapped value. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -||Maintain group of {key, value} pairs.| -|IHash|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| | Maintain group of {key, value} pairs. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp()`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multimap (STL/CLR)](../dotnet/hash-multimap-stl-clr.md), an object of template class `hash_map` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_multimap`](../dotnet/hash-multimap-stl-clr.md), an object of template class `hash_map` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_map supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_map::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_map iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_map` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_map` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_map element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_map` element directly given its numerical position; that requires a random-access iterator. -A hash_map iterator stores a handle to its associated hash_map node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_map iterator remains valid so long as its associated hash_map node is associated with some hash_map. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_map` iterator stores a handle to its associated `hash_map` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_map` iterator remains valid so long as its associated `hash_map` node is associated with some `hash_map`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it's not equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles doesn't* destroy its elements. ## Members -## hash_map::begin (STL/CLR) +## `hash_map::begin` Designates the beginning of the controlled sequence. @@ -208,7 +208,7 @@ int main() *++begin() = [b 2] ``` -## hash_map::bucket_count (STL/CLR) +## `hash_map::bucket_count` Counts the number of buckets. @@ -220,7 +220,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -282,7 +282,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::clear (STL/CLR) +## `hash_map::clear` Removes all elements. @@ -294,7 +294,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_map::erase (STL/CLR)](#erase)`(` [hash_map::begin (STL/CLR)](#begin)`(),` [hash_map::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -340,7 +340,7 @@ size() = 0 size() = 0 ``` -## hash_map::const_iterator (STL/CLR) +## `hash_map::const_iterator` The type of a constant iterator for the controlled sequence. @@ -382,7 +382,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::const_reference (STL/CLR) +## `hash_map::const_reference` The type of a constant reference to an element. @@ -427,9 +427,9 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::const_reverse_iterator (STL/CLR) +## `hash_map::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -469,7 +469,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_map::count (STL/CLR) +## `hash_map::count` Finds the number of elements matching a specified key. @@ -481,12 +481,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -522,7 +522,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_map::difference_type (STL/CLR) +## `hash_map::difference_type` The types of a signed distance between two elements. @@ -577,7 +577,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_map::empty (STL/CLR) +## `hash_map::empty` Tests whether no elements are present. @@ -589,7 +589,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_map::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_map is empty. +The member function returns `true` for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_map` is empty. ### Example @@ -629,7 +629,7 @@ size() = 0 empty() = True ``` -## hash_map::end (STL/CLR) +## `hash_map::end` Designates the end of the controlled sequence. @@ -641,7 +641,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -682,7 +682,7 @@ int main() *--end() = [c 3] ``` -## hash_map::equal_range (STL/CLR) +## `hash_map::equal_range` Finds range that matches a specified key. @@ -694,7 +694,7 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks @@ -743,7 +743,7 @@ equal_range(L'x') empty = True [b 2] ``` -## hash_map::erase (STL/CLR) +## `hash_map::erase` Removes elements at specified positions. @@ -757,25 +757,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_map::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -836,7 +836,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## hash_map::find (STL/CLR) +## `hash_map::find` Finds an element that matches a specified key. @@ -848,12 +848,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_map::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -895,7 +895,7 @@ find b = [b 2] find C = False ``` -## hash_map::generic_container (STL/CLR) +## `hash_map::generic_container` The type of the generic interface for the container. @@ -959,7 +959,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## hash_map::generic_iterator (STL/CLR) +## `hash_map::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -1016,7 +1016,7 @@ int main() [a 1] ``` -## hash_map::generic_reverse_iterator (STL/CLR) +## `hash_map::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1072,7 +1072,7 @@ int main() [c 3] ``` -## hash_map::generic_value (STL/CLR) +## `hash_map::generic_value` The type of an element for use with the generic interface for the container. @@ -1126,7 +1126,7 @@ int main() [a 1] ``` -## hash_map::hash_delegate (STL/CLR) +## `hash_map::hash_delegate` Finds an element that matches a specified key. @@ -1164,7 +1164,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_map::hash_map (STL/CLR) +## `hash_map::hash_map` Constructs a container object. @@ -1193,19 +1193,19 @@ hash_map(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1220,25 +1220,25 @@ The constructor: `explicit hash_map(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_map(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_map(hash_map% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_map object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_map` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_map(hash_map^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_map object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_map` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1250,31 +1250,31 @@ The constructor: `template hash_map(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_map(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1407,7 +1407,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## hash_map::hasher (STL/CLR) +## `hash_map::hasher` The hashing delegate for a key. @@ -1446,7 +1446,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_map::insert (STL/CLR) +## `hash_map::insert` Adds elements. @@ -1462,19 +1462,19 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks @@ -1483,13 +1483,13 @@ Each of the member functions inserts a sequence specified by the remaining opera The first member function endeavors to insert an element with value `val`, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1566,7 +1566,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [c 3] [x 24] [y 25] ``` -## hash_map::iterator (STL/CLR) +## `hash_map::iterator` The type of an iterator for the controlled sequence. @@ -1608,7 +1608,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::key_comp (STL/CLR) +## `hash_map::key_comp` Copies the ordering delegate for two keys. @@ -1667,7 +1667,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_map::key_compare (STL/CLR) +## `hash_map::key_compare` The ordering delegate for two keys. @@ -1727,7 +1727,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_map::key_type (STL/CLR) +## `hash_map::key_type` The type of an ordering key. @@ -1739,7 +1739,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1772,7 +1772,7 @@ int main() a b c ``` -## hash_map::load_factor (STL/CLR) +## `hash_map::load_factor` Counts the average elements per bucket. @@ -1784,7 +1784,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_map::size (STL/CLR)](#size)`() /` [hash_map::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1846,7 +1846,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::lower_bound (STL/CLR) +## `hash_map::lower_bound` Finds beginning of range that matches a specified key. @@ -1858,12 +1858,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1905,7 +1905,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## hash_map::make_value (STL/CLR) +## `hash_map::make_value` Constructs a value object. @@ -1917,15 +1917,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1954,7 +1954,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::mapped_type (STL/CLR) +## `hash_map::mapped_type` The type of a mapped value associated with each key. @@ -1999,7 +1999,7 @@ int main() 1 2 3 ``` -## hash_map::max_load_factor (STL/CLR) +## `hash_map::max_load_factor` Gets or sets the maximum elements per bucket. @@ -2012,14 +2012,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -2081,7 +2081,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::operator= (STL/CLR) +## `hash_map::operator=` Replaces the controlled sequence. @@ -2093,12 +2093,12 @@ hash_map% operator=(hash_map% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2136,7 +2136,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::operator(STL/CLR) +## `hash_map::operator[]` Maps a key to its associated mapped value. @@ -2148,12 +2148,12 @@ mapped_type operator[](key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member functions endeavors to find an element with equivalent ordering to *key*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. +The member functions endeavors to find an element with equivalent ordering to *`key`*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. ### Example @@ -2203,7 +2203,7 @@ c1[b] = 2 [a 1] [A 10] [b 2] [c 13] ``` -## hash_map::rbegin (STL/CLR) +## `hash_map::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2254,7 +2254,7 @@ int main() *++rbegin() = [b 2] ``` -## hash_map::reference (STL/CLR) +## `hash_map::reference` The type of a reference to an element. @@ -2299,7 +2299,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::rehash (STL/CLR) +## `hash_map::rehash` Rebuilds the hash table. @@ -2311,7 +2311,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_map::load_factor (STL/CLR)](#load_factor)`() <=` [hash_map::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2373,7 +2373,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::rend (STL/CLR) +## `hash_map::rend` Designates the end of the reversed controlled sequence. @@ -2426,7 +2426,7 @@ int main() *--rend() = [a 1] ``` -## hash_map::reverse_iterator (STL/CLR) +## `hash_map::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2468,7 +2468,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_map::size (STL/CLR) +## `hash_map::size` Counts the number of elements. @@ -2480,7 +2480,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_map::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_map::empty`](#empty). ### Example @@ -2520,9 +2520,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_map::size_type (STL/CLR) +## `hash_map::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2568,7 +2568,7 @@ int main() end()-begin() = 3 ``` -## hash_map::swap (STL/CLR) +## `hash_map::swap` Swaps the contents of two containers. @@ -2580,12 +2580,12 @@ void swap(hash_map% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2636,7 +2636,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::to_array (STL/CLR) +## `hash_map::to_array` Copies the controlled sequence to a new array. @@ -2686,7 +2686,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::upper_bound (STL/CLR) +## `hash_map::upper_bound` Finds end of range that matches a specified key. @@ -2698,12 +2698,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2745,7 +2745,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## hash_map::value_comp (STL/CLR) +## `hash_map::value_comp` Copies the ordering delegate for two element values. @@ -2792,7 +2792,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_map::value_compare (STL/CLR) +## `hash_map::value_compare` The ordering delegate for two element values. @@ -2840,7 +2840,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_map::value_type (STL/CLR) +## `hash_map::value_type` The type of an element. diff --git a/docs/dotnet/hash-multimap-stl-clr.md b/docs/dotnet/hash-multimap-stl-clr.md index 54cb5964bc..59ec4336e5 100644 --- a/docs/dotnet/hash-multimap-stl-clr.md +++ b/docs/dotnet/hash-multimap-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::hash_multimap", "cliext::hash_multimap::begin", "cliext:: helpviewer_keywords: ["hash_multimap class [STL/CLR]", " header [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_multimap member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: cd78687b-8a05-48e0-9d22-8b8194ae3b0b --- -# hash_multimap (STL/CLR) +# `hash_multimap` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_multimap` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -40,121 +40,121 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_multimap::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_multimap::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_multimap::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_multimap::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_multimap::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_multimap::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_multimap::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_multimap::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_multimap::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_multimap::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_multimap::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_multimap::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_multimap::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[hash_multimap::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_multimap::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_multimap::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_multimap::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_multimap::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_multimap::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_multimap::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_multimap::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_multimap::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_multimap::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_multimap::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_multimap::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_multimap::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_multimap::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_multimap::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_multimap::hash_multimap (STL/CLR)](#hash_multimap)|Constructs a container object.| -|[hash_multimap::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_multimap::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_multimap::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_multimap::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_multimap::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_multimap::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_multimap::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_multimap::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_multimap::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_multimap::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_multimap::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_multimap::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_multimap::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_multimap::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_multimap::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_multimap::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_multimap::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_multimap::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_multimap::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_multimap::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_multimap::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_multimap::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_multimap::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_multimap::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_multimap::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_multimap::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_multimap::key_type`](#key_type) | The type of an ordering key. | +| [`hash_multimap::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`hash_multimap::reference`](#reference) | The type of a reference to an element. | +| [`hash_multimap::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_multimap::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_multimap::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_multimap::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_multimap::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_multimap::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_multimap::clear`](#clear) | Removes all elements. | +| [`hash_multimap::count`](#count) | Counts elements matching a specified key. | +| [`hash_multimap::empty`](#empty) | Tests whether no elements are present. | +| [`hash_multimap::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_multimap::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_multimap::erase`](#erase) | Removes elements at specified positions. | +| [`hash_multimap::find`](#find) | Finds an element that matches a specified key. | +| [`hash_multimap::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_multimap::hash_multimap`](#hash_multimap) | Constructs a container object. | +| [`hash_multimap::insert`](#insert) | Adds elements. | +| [`hash_multimap::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_multimap::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_multimap::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_multimap::make_value`](#make_value) | Constructs a value object. | +| [`hash_multimap::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_multimap::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_multimap::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_multimap::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_multimap::size`](#size) | Counts the number of elements. | +| [`hash_multimap::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_multimap::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_multimap::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_multimap::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_multimap::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_map (STL/CLR)](../dotnet/hash-map-stl-clr.md), an object of template class `hash_multimap` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_map` (STL/CLR)](../dotnet/hash-map-stl-clr.md), an object of template class `hash_multimap` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_multimap supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_multimap::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_multimap iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_multimap` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_multimap` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_multimap element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_multimap` element directly given its numerical position. That requires a random-access iterator. -A hash_multimap iterator stores a handle to its associated hash_multimap node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_multimap iterator remains valid so long as its associated hash_multimap node is associated with some hash_multimap. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_multimap` iterator stores a handle to its associated `hash_multimap` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_multimap` iterator remains valid so long as its associated `hash_multimap` node is associated with some `hash_multimap`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_multimap::begin (STL/CLR) +## hash_multimap::begin Designates the beginning of the controlled sequence. @@ -205,7 +205,7 @@ int main() *++begin() = [b 2] ``` -## hash_multimap::bucket_count (STL/CLR) +## hash_multimap::bucket_count Counts the number of buckets. @@ -217,7 +217,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -279,7 +279,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::clear (STL/CLR) +## hash_multimap::clear Removes all elements. @@ -291,7 +291,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_multimap::erase (STL/CLR)](#erase)`(` [hash_multimap::begin (STL/CLR)](#begin)`(),` [hash_multimap::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -337,7 +337,7 @@ size() = 0 size() = 0 ``` -## hash_multimap::const_iterator (STL/CLR) +## hash_multimap::const_iterator The type of a constant iterator for the controlled sequence. @@ -379,7 +379,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::const_reference (STL/CLR) +## hash_multimap::const_reference The type of a constant reference to an element. @@ -424,9 +424,9 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::const_reverse_iterator (STL/CLR) +## hash_multimap::const_reverse_iterator -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -466,7 +466,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_multimap::count (STL/CLR) +## hash_multimap::count Finds the number of elements matching a specified key. @@ -478,12 +478,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -519,7 +519,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_multimap::difference_type (STL/CLR) +## hash_multimap::difference_type The types of a signed distance between two elements. @@ -574,7 +574,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_multimap::empty (STL/CLR) +## hash_multimap::empty Tests whether no elements are present. @@ -586,7 +586,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_multimap::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_multimap is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_multimap` is empty. ### Example @@ -626,7 +626,7 @@ size() = 0 empty() = True ``` -## hash_multimap::end (STL/CLR) +## hash_multimap::end Designates the end of the controlled sequence. @@ -638,7 +638,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -679,7 +679,7 @@ int main() *--end() = [c 3] ``` -## hash_multimap::equal_range (STL/CLR) +## hash_multimap::equal_range Finds range that matches a specified key. @@ -691,12 +691,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_multimap::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_multimap::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -740,7 +740,7 @@ equal_range(L'x') empty = True [b 2] ``` -## hash_multimap::erase (STL/CLR) +## hash_multimap::erase Removes elements at specified positions. @@ -754,25 +754,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_multimap::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the half-open range `[first, last)`, and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -833,7 +833,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## hash_multimap::find (STL/CLR) +## `hash_multimap::find` Finds an element that matches a specified key. @@ -845,12 +845,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_multimap::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`hash_multimap::end`](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -892,7 +892,7 @@ find b = [b 2] find C = False ``` -## hash_multimap::generic_container (STL/CLR) +## `hash_multimap::generic_container` The type of the generic interface for the container. @@ -956,7 +956,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## hash_multimap::generic_iterator (STL/CLR) +## `hash_multimap::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -1013,7 +1013,7 @@ int main() [a 1] ``` -## hash_multimap::generic_reverse_iterator (STL/CLR) +## `hash_multimap::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1069,7 +1069,7 @@ int main() [c 3] ``` -## hash_multimap::generic_value (STL/CLR) +## `hash_multimap::generic_value` The type of an element for use with the generic interface for the container. @@ -1123,7 +1123,7 @@ int main() [a 1] ``` -## hash_multimap::hash_delegate (STL/CLR) +## `hash_multimap::hash_delegate` Finds an element that matches a specified key. @@ -1161,7 +1161,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multimap::hash_multimap (STL/CLR) +## `hash_multimap::hash_multimap` Constructs a container object. @@ -1190,19 +1190,19 @@ hash_multimap(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1217,61 +1217,61 @@ The constructor: `explicit hash_multimap(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_multimap(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_multimap(hash_multimap% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multimap object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multimap` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_multimap(hash_multimap^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multimap object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multimap` object *`right`*, with the default ordering predicate and hash function. The constructor: `template hash_multimap(InIter first, InIter last);` -initializes the controlled sequence with the sequence [`first`, `last`), with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the default ordering predicate and hash function. The constructor: `template hash_multimap(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_multimap(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1404,7 +1404,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## hash_multimap::hasher (STL/CLR) +## `hash_multimap::hasher` The hashing delegate for a key. @@ -1443,7 +1443,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multimap::insert (STL/CLR) +## `hash_multimap::insert` Adds elements. @@ -1459,34 +1459,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. -The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. +The third member function inserts the sequence `[first, last)`. You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1561,7 +1561,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [b 2] [c 3] [x 24] [y 25] ``` -## hash_multimap::iterator (STL/CLR) +## `hash_multimap::iterator` The type of an iterator for the controlled sequence. @@ -1603,7 +1603,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::key_comp (STL/CLR) +## `hash_multimap::key_comp` Copies the ordering delegate for two keys. @@ -1662,7 +1662,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multimap::key_compare (STL/CLR) +## `hash_multimap::key_compare` The ordering delegate for two keys. @@ -1722,7 +1722,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multimap::key_type (STL/CLR) +## `hash_multimap::key_type` The type of an ordering key. @@ -1734,7 +1734,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1767,7 +1767,7 @@ int main() a b c ``` -## hash_multimap::load_factor (STL/CLR) +## `hash_multimap::load_factor` Counts the average elements per bucket. @@ -1779,7 +1779,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_multimap::size (STL/CLR)](#size)`() /` [hash_multimap::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1841,7 +1841,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::lower_bound (STL/CLR) +## `hash_multimap::lower_bound` Finds beginning of range that matches a specified key. @@ -1853,12 +1853,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`hash_multimap::end`](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1900,7 +1900,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## hash_multimap::make_value (STL/CLR) +## `hash_multimap::make_value` Constructs a value object. @@ -1912,15 +1912,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1949,7 +1949,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::mapped_type (STL/CLR) +## `hash_multimap::mapped_type` The type of a mapped value associated with each key. @@ -1961,7 +1961,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1994,7 +1994,7 @@ int main() 1 2 3 ``` -## hash_multimap::max_load_factor (STL/CLR) +## `hash_multimap::max_load_factor` Gets or sets the maximum elements per bucket. @@ -2007,14 +2007,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -2076,7 +2076,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::operator= (STL/CLR) +## `hash_multimap::operator=` Replaces the controlled sequence. @@ -2088,12 +2088,12 @@ hash_multimap% operator=(hash_multimap% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2131,7 +2131,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::rbegin (STL/CLR) +## `hash_multimap::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2182,7 +2182,7 @@ int main() *++rbegin() = [b 2] ``` -## hash_multimap::reference (STL/CLR) +## `hash_multimap::reference` The type of a reference to an element. @@ -2227,7 +2227,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::rehash (STL/CLR) +## `hash_multimap::rehash` Rebuilds the hash table. @@ -2239,7 +2239,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_multimap::load_factor (STL/CLR)](#load_factor)`() <=` [hash_multimap::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2301,7 +2301,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::rend (STL/CLR) +## `hash_multimap::rend` Designates the end of the reversed controlled sequence. @@ -2354,7 +2354,7 @@ int main() *--rend() = [a 1] ``` -## hash_multimap::reverse_iterator (STL/CLR) +## `hash_multimap::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2396,7 +2396,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_multimap::size (STL/CLR) +## `hash_multimap::size` Counts the number of elements. @@ -2408,7 +2408,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_multimap::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_multimap::empty`](#empty)`()`. ### Example @@ -2448,9 +2448,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_multimap::size_type (STL/CLR) +## `hash_multimap::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2496,7 +2496,7 @@ int main() end()-begin() = 3 ``` -## hash_multimap::swap (STL/CLR) +## `hash_multimap::swap` Swaps the contents of two containers. @@ -2508,12 +2508,12 @@ void swap(hash_multimap% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2564,7 +2564,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::to_array (STL/CLR) +## `hash_multimap::to_array` Copies the controlled sequence to a new array. @@ -2614,7 +2614,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::upper_bound (STL/CLR) +## `hash_multimap::upper_bound` Finds end of range that matches a specified key. @@ -2626,12 +2626,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`hash_multimap::end`](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2673,7 +2673,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## hash_multimap::value_comp (STL/CLR) +## `hash_multimap::value_comp` Copies the ordering delegate for two element values. @@ -2720,7 +2720,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_multimap::value_compare (STL/CLR) +## `hash_multimap::value_compare` The ordering delegate for two element values. @@ -2768,7 +2768,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_multimap::value_type (STL/CLR) +## `hash_multimap::value_type` The type of an element. diff --git a/docs/dotnet/hash-multiset-stl-clr.md b/docs/dotnet/hash-multiset-stl-clr.md index c14ded18c1..0c6b7b53d5 100644 --- a/docs/dotnet/hash-multiset-stl-clr.md +++ b/docs/dotnet/hash-multiset-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::hash_multiset", "cliext::hash_multiset::begin", "cliext:: helpviewer_keywords: [" header [STL/CLR]", "hash_multiset class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_multiset member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 8462bd21-6829-4dd3-ac81-c42d6fdf92f0 --- -# hash_multiset (STL/CLR) +# `hash_multiset` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_multiset` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. The value of each element is used as a key, for ordering the sequence. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,117 +31,117 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_multiset::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_multiset::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_multiset::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_multiset::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_multiset::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_multiset::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_multiset::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_multiset::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_multiset::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_multiset::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_multiset::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_multiset::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_multiset::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_multiset::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_multiset::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_multiset::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_multiset::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_multiset::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_multiset::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_multiset::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_multiset::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_multiset::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_multiset::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_multiset::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_multiset::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_multiset::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_multiset::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_multiset::hash_multiset (STL/CLR)](#hash_multiset)|Constructs a container object.| -|[hash_multiset::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_multiset::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_multiset::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_multiset::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_multiset::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_multiset::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_multiset::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_multiset::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_multiset::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_multiset::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_multiset::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_multiset::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_multiset::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_multiset::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_multiset::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_multiset::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_multiset::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_multiset::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_multiset::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_multiset::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_multiset::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_multiset::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_multiset::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_multiset::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_multiset::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_multiset::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_multiset::key_type`](#key_type) | The type of an ordering key. | +| [`hash_multiset::reference`](#reference) | The type of a reference to an element. | +| [`hash_multiset::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_multiset::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_multiset::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_multiset::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_multiset::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_multiset::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_multiset::clear`](#clear) | Removes all elements. | +| [`hash_multiset::count`](#count) | Counts elements matching a specified key. | +| [`hash_multiset::empty`](#empty) | Tests whether no elements are present. | +| [`hash_multiset::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_multiset::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_multiset::erase`](#erase) | Removes elements at specified positions. | +| [`hash_multiset::find`](#find) | Finds an element that matches a specified key. | +| [`hash_multiset::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_multiset::hash_multiset`](#hash_multiset) | Constructs a container object. | +| [`hash_multiset::insert`](#insert) | Adds elements. | +| [`hash_multiset::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_multiset::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_multiset::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_multiset::make_value`](#make_value) | Constructs a value object. | +| [`hash_multiset::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_multiset::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_multiset::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_multiset::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_multiset::size`](#size) | Counts the number of elements. | +| [`hash_multiset::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_multiset::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_multiset::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_multiset::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_multiset::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_set (STL/CLR)](../dotnet/hash-set-stl-clr.md), an object of template class `hash_multiset` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_set` (STL/CLR)](../dotnet/hash-set-stl-clr.md), an object of template class `hash_multiset` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_multiset supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_multiset::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_multiset iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_multiset` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`hash_multiset::end`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_multiset` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_multiset element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_multiset` element directly given its numerical position. That requires a random-access iterator. -A hash_multiset iterator stores a handle to its associated hash_multiset node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_multiset iterator remains valid so long as its associated hash_multiset node is associated with some hash_multiset. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_multiset` iterator stores a handle to its associated `hash_multiset` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_multiset` iterator remains valid so long as its associated `hash_multiset` node is associated with some `hash_multiset`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_multiset::begin (STL/CLR) +## `hash_multiset::begin` Designates the beginning of the controlled sequence. @@ -189,7 +189,7 @@ a b c *++begin() = b ``` -## hash_multiset::bucket_count (STL/CLR) +## `hash_multiset::bucket_count` Counts the number of buckets. @@ -201,7 +201,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -263,7 +263,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::clear (STL/CLR) +## `hash_multiset::clear` Removes all elements. @@ -275,7 +275,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_multiset::erase (STL/CLR)](#erase)`(` [hash_multiset::begin (STL/CLR)](#begin)`(),` [hash_multiset::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -321,7 +321,7 @@ a b size() = 0 ``` -## hash_multiset::const_iterator (STL/CLR) +## `hash_multiset::const_iterator` The type of a constant iterator for the controlled sequence. @@ -363,7 +363,7 @@ int main() a b c ``` -## hash_multiset::const_reference (STL/CLR) +## `hash_multiset::const_reference` The type of a constant reference to an element. @@ -408,9 +408,9 @@ int main() a b c ``` -## hash_multiset::const_reverse_iterator (STL/CLR) +## `hash_multiset::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -450,7 +450,7 @@ int main() c b a ``` -## hash_multiset::count (STL/CLR) +## `hash_multiset::count` Finds the number of elements matching a specified key. @@ -462,12 +462,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -503,7 +503,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_multiset::difference_type (STL/CLR) +## `hash_multiset::difference_type` The types of a signed distance between two elements. @@ -558,7 +558,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_multiset::empty (STL/CLR) +## `hash_multiset::empty` Tests whether no elements are present. @@ -570,7 +570,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_multiset::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_multiset is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_multiset` is empty. ### Example @@ -610,7 +610,7 @@ size() = 0 empty() = True ``` -## hash_multiset::end (STL/CLR) +## `hash_multiset::end` Designates the end of the controlled sequence. @@ -622,7 +622,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -659,7 +659,7 @@ a b c *--end() = c ``` -## hash_multiset::equal_range (STL/CLR) +## `hash_multiset::equal_range` Finds range that matches a specified key. @@ -671,12 +671,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_multiset::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_multiset::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -719,7 +719,7 @@ equal_range(L'x') empty = True b ``` -## hash_multiset::erase (STL/CLR) +## `hash_multiset::erase` Removes elements at specified positions. @@ -733,25 +733,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_multiset::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -803,7 +803,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## hash_multiset::find (STL/CLR) +## `hash_multiset::find` Finds an element that matches a specified key. @@ -815,12 +815,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_multiset::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -859,7 +859,7 @@ find b = b find C = False ``` -## hash_multiset::generic_container (STL/CLR) +## `hash_multiset::generic_container` The type of the generic interface for the container. @@ -923,7 +923,7 @@ a b c d a b c d e ``` -## hash_multiset::generic_iterator (STL/CLR) +## `hash_multiset::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -979,7 +979,7 @@ a b c a ``` -## hash_multiset::generic_reverse_iterator (STL/CLR) +## `hash_multiset::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1035,7 +1035,7 @@ a b c c ``` -## hash_multiset::generic_value (STL/CLR) +## `hash_multiset::generic_value` The type of an element for use with the generic interface for the container. @@ -1089,7 +1089,7 @@ a b c a ``` -## hash_multiset::hash_delegate (STL/CLR) +## `hash_multiset::hash_delegate` Finds an element that matches a specified key. @@ -1127,7 +1127,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multiset::hash_multiset (STL/CLR) +## `hash_multiset::hash_multiset` Constructs a container object. @@ -1156,19 +1156,19 @@ hash_multiset(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1183,25 +1183,25 @@ The constructor: `explicit hash_multiset(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_multiset(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_multiset(hash_multiset% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multiset object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multiset` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_multiset(hash_multiset^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multiset object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multiset` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1213,31 +1213,31 @@ The constructor: `template hash_multiset(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_multiset(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1367,7 +1367,7 @@ a b c a b c ``` -## hash_multiset::hasher (STL/CLR) +## `hash_multiset::hasher` The hashing delegate for a key. @@ -1406,7 +1406,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multiset::insert (STL/CLR) +## `hash_multiset::insert` Adds elements. @@ -1422,34 +1422,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1519,7 +1519,7 @@ a b b c x a b b c x y ``` -## hash_multiset::iterator (STL/CLR) +## `hash_multiset::iterator` The type of an iterator for the controlled sequence. @@ -1561,7 +1561,7 @@ int main() a b c ``` -## hash_multiset::key_comp (STL/CLR) +## `hash_multiset::key_comp` Copies the ordering delegate for two keys. @@ -1620,7 +1620,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multiset::key_compare (STL/CLR) +## `hash_multiset::key_compare` The ordering delegate for two keys. @@ -1680,7 +1680,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multiset::key_type (STL/CLR) +## `hash_multiset::key_type` The type of an ordering key. @@ -1692,7 +1692,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1725,7 +1725,7 @@ int main() a b c ``` -## hash_multiset::load_factor (STL/CLR) +## `hash_multiset::load_factor` Counts the average elements per bucket. @@ -1737,7 +1737,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_multiset::size (STL/CLR)](#size)`() /` [hash_multiset::bucket_count (STL/CLR)](#count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / count()`. You use it to determine the average bucket size. ### Example @@ -1799,7 +1799,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::lower_bound (STL/CLR) +## `hash_multiset::lower_bound` Finds beginning of range that matches a specified key. @@ -1811,12 +1811,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1856,7 +1856,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## hash_multiset::make_value (STL/CLR) +## `hash_multiset::make_value` Constructs a value object. @@ -1868,12 +1868,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1902,7 +1902,7 @@ int main() a b c ``` -## hash_multiset::max_load_factor (STL/CLR) +## `hash_multiset::max_load_factor` Gets or sets the maximum elements per bucket. @@ -1915,14 +1915,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -1984,7 +1984,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::operator= (STL/CLR) +## `hash_multiset::operator=` Replaces the controlled sequence. @@ -1996,12 +1996,12 @@ hash_multiset% operator=(hash_multiset% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2039,7 +2039,7 @@ a b c a b c ``` -## hash_multiset::rbegin (STL/CLR) +## `hash_multiset::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2087,7 +2087,7 @@ a b c *++rbegin() = b ``` -## hash_multiset::reference (STL/CLR) +## `hash_multiset::reference` The type of a reference to an element. @@ -2132,7 +2132,7 @@ int main() a b c ``` -## hash_multiset::rehash (STL/CLR) +## `hash_multiset::rehash` Rebuilds the hash table. @@ -2144,7 +2144,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_multiset::load_factor (STL/CLR)](#load_factor)`() <=` [hash_multiset::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2206,7 +2206,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::rend (STL/CLR) +## `hash_multiset::rend` Designates the end of the reversed controlled sequence. @@ -2255,7 +2255,7 @@ a b c *--rend() = a ``` -## hash_multiset::reverse_iterator (STL/CLR) +## `hash_multiset::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2297,7 +2297,7 @@ int main() c b a ``` -## hash_multiset::size (STL/CLR) +## `hash_multiset::size` Counts the number of elements. @@ -2309,7 +2309,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_multiset::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_multiset::empty`](#empty). ### Example @@ -2351,9 +2351,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_multiset::size_type (STL/CLR) +## `hash_multiset::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2399,7 +2399,7 @@ a b c end()-begin() = 3 ``` -## hash_multiset::swap (STL/CLR) +## `hash_multiset::swap` Swaps the contents of two containers. @@ -2411,12 +2411,12 @@ void swap(hash_multiset% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2467,7 +2467,7 @@ d e f a b c ``` -## hash_multiset::to_array (STL/CLR) +## `hash_multiset::to_array` Copies the controlled sequence to a new array. @@ -2517,7 +2517,7 @@ a b c d a b c ``` -## hash_multiset::upper_bound (STL/CLR) +## `hash_multiset::upper_bound` Finds end of range that matches a specified key. @@ -2529,12 +2529,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2574,7 +2574,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## hash_multiset::value_comp (STL/CLR) +## `hash_multiset::value_comp` Copies the ordering delegate for two element values. @@ -2618,7 +2618,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_multiset::value_compare (STL/CLR) +## `hash_multiset::value_compare` The ordering delegate for two element values. @@ -2663,7 +2663,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_multiset::value_type (STL/CLR) +## `hash_multiset::value_type` The type of an element. diff --git a/docs/dotnet/hash-set-stl-clr.md b/docs/dotnet/hash-set-stl-clr.md index fd3ce0dca7..6a4a7d6bc7 100644 --- a/docs/dotnet/hash-set-stl-clr.md +++ b/docs/dotnet/hash-set-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::hash_set", "cliext::hash_set::begin", "cliext::hash_set:: helpviewer_keywords: [" header [STL/CLR]", "hash_set class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_set member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: d110e356-ba3e-4e52-9e2d-d997bf975c96 --- -# hash_set (STL/CLR) +# `hash_set` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_set` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. The value of each element is used as a key, for ordering the sequence. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,117 +31,117 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_set::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_set::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_set::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_set::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_set::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_set::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_set::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_set::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_set::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_set::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_set::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_set::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_set::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_set::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_set::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_set::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_set::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_set::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_set::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_set::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_set::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_set::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_set::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_set::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_set::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_set::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_set::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_set::hash_set (STL/CLR)](#hash_set)|Constructs a container object.| -|[hash_set::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_set::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_set::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_set::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_set::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_set::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_set::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_set::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_set::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_set::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_set::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_set::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_set::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_set::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_set::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_set::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_set::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_set::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_set::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_set::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_set::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_set::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_set::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_set::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_set::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_set::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_set::key_type`](#key_type) | The type of an ordering key. | +| [`hash_set::reference`](#reference) | The type of a reference to an element. | +| [`hash_set::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_set::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_set::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_set::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_set::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_set::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_set::clear`](#clear) | Removes all elements. | +| [`hash_set::count`](#count) | Counts elements matching a specified key. | +| [`hash_set::empty`](#empty) | Tests whether no elements are present. | +| [`hash_set::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_set::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_set::erase`](#erase) | Removes elements at specified positions. | +| [`hash_set::find`](#find) | Finds an element that matches a specified key. | +| [`hash_set::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_set::hash_set`](#hash_set) | Constructs a container object. | +| [`hash_set::insert`](#insert) | Adds elements. | +| [`hash_set::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_set::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_set::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_set::make_value`](#make_value) | Constructs a value object. | +| [`hash_set::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_set::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_set::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_set::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_set::size`](#size) | Counts the number of elements. | +| [`hash_set::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_set::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_set::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_set::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_set::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multiset (STL/CLR)](../dotnet/hash-multiset-stl-clr.md), an object of template class `hash_set` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multiset (STL/CLR)](../dotnet/hash-multiset-stl-clr.md), an object of template class `hash_set` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](#max_load_factor) and [hash_set::rehash (STL/CLR)](#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](#max_load_factor) and [`hash_set::rehash`](#rehash). -A hash_set supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_set::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_set iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_set` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_set` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_set element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_set` element directly given its numerical position. That requires a random-access iterator. -A hash_set iterator stores a handle to its associated hash_set node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_set iterator remains valid so long as its associated hash_set node is associated with some hash_set. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_set` iterator stores a handle to its associated `hash_set` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_set` iterator remains valid so long as its associated `hash_set` node is associated with some hash_set. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_set::begin (STL/CLR) +## `hash_set::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ int main() } ``` -## hash_set::bucket_count (STL/CLR) +## `hash_set::bucket_count` Counts the number of buckets. @@ -195,7 +195,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -257,7 +257,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::clear (STL/CLR) +## `hash_set::clear` Removes all elements. @@ -269,7 +269,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_set::erase (STL/CLR)](#erase)`(` [hash_set::begin (STL/CLR)](#begin)`(),` [hash_set::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -315,7 +315,7 @@ a b size() = 0 ``` -## hash_set::const_iterator (STL/CLR) +## `hash_set::const_iterator` The type of a constant iterator for the controlled sequence. @@ -357,7 +357,7 @@ int main() a b c ``` -## hash_set::const_reference (STL/CLR) +## `hash_set::const_reference` The type of a constant reference to an element. @@ -402,9 +402,9 @@ int main() a b c ``` -## hash_set::const_reverse_iterator (STL/CLR) +## `hash_set::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -444,7 +444,7 @@ int main() c b a ``` -## hash_set::count (STL/CLR) +## `hash_set::count` Finds the number of elements matching a specified key. @@ -456,12 +456,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -497,7 +497,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_set::difference_type (STL/CLR) +## `hash_set::difference_type` The types of a signed distance between two elements. @@ -552,7 +552,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_set::empty (STL/CLR) +## `hash_set::empty` Tests whether no elements are present. @@ -564,7 +564,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_set::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_set is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_set` is empty. ### Example @@ -604,7 +604,7 @@ size() = 0 empty() = True ``` -## hash_set::end (STL/CLR) +## `hash_set::end` Designates the end of the controlled sequence. @@ -616,7 +616,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -653,7 +653,7 @@ a b c *--end() = c ``` -## hash_set::equal_range (STL/CLR) +## `hash_set::equal_range` Finds range that matches a specified key. @@ -665,12 +665,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_set::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_set::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -713,7 +713,7 @@ equal_range(L'x') empty = True b ``` -## hash_set::erase (STL/CLR) +## `hash_set::erase` Removes elements at specified positions. @@ -727,25 +727,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_set::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -797,7 +797,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## hash_set::find (STL/CLR) +## `hash_set::find` Finds an element that matches a specified key. @@ -809,12 +809,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_set::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -853,7 +853,7 @@ find b = b find C = False ``` -## hash_set::generic_container (STL/CLR) +## `hash_set::generic_container` The type of the generic interface for the container. @@ -917,7 +917,7 @@ a b c d a b c d e ``` -## hash_set::generic_iterator (STL/CLR) +## `hash_set::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -973,7 +973,7 @@ a b c a ``` -## hash_set::generic_reverse_iterator (STL/CLR) +## `hash_set::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1029,7 +1029,7 @@ a b c c ``` -## hash_set::generic_value (STL/CLR) +## `hash_set::generic_value` The type of an element for use with the generic interface for the container. @@ -1083,7 +1083,7 @@ a b c a ``` -## hash_set::hash_delegate (STL/CLR) +## `hash_set::hash_delegate` Finds an element that matches a specified key. @@ -1121,7 +1121,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_set::hash_set (STL/CLR) +## `hash_set::hash_set` Constructs a container object. @@ -1150,19 +1150,19 @@ hash_set(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1177,25 +1177,25 @@ The constructor: `explicit hash_set(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_set(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_set(hash_set% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_set object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_set` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_set(hash_set^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_set object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_set` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1207,31 +1207,31 @@ The constructor: `template hash_set(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_set(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1361,7 +1361,7 @@ a b c a b c ``` -## hash_set::hasher (STL/CLR) +## `hash_set::hasher` The hashing delegate for a key. @@ -1400,7 +1400,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_set::insert (STL/CLR) +## `hash_set::insert` Adds elements. @@ -1416,34 +1416,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1516,7 +1516,7 @@ a b c x a b c x y ``` -## hash_set::iterator (STL/CLR) +## `hash_set::iterator` The type of an iterator for the controlled sequence. @@ -1558,7 +1558,7 @@ int main() a b c ``` -## hash_set::key_comp (STL/CLR) +## `hash_set::key_comp` Copies the ordering delegate for two keys. @@ -1617,7 +1617,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_set::key_compare (STL/CLR) +## `hash_set::key_compare` The ordering delegate for two keys. @@ -1677,7 +1677,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_set::key_type (STL/CLR) +## `hash_set::key_type` The type of an ordering key. @@ -1689,7 +1689,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1722,7 +1722,7 @@ int main() a b c ``` -## hash_set::load_factor (STL/CLR) +## `hash_set::load_factor` Counts the average elements per bucket. @@ -1734,7 +1734,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_set::size (STL/CLR)](#size)`() /` [hash_set::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1796,7 +1796,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::lower_bound (STL/CLR) +## `hash_set::lower_bound` Finds beginning of range that matches a specified key. @@ -1808,12 +1808,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1853,7 +1853,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## hash_set::make_value (STL/CLR) +## `hash_set::make_value` Constructs a value object. @@ -1865,12 +1865,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1899,7 +1899,7 @@ int main() a b c ``` -## hash_set::max_load_factor (STL/CLR) +## `hash_set::max_load_factor` Gets or sets the maximum elements per bucket. @@ -1912,14 +1912,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -1966,7 +1966,7 @@ int main() } ``` -## hash_set::operator= (STL/CLR) +## `hash_set::operator=` Replaces the controlled sequence. @@ -1978,12 +1978,12 @@ hash_set% operator=(hash_set% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2021,7 +2021,7 @@ a b c a b c ``` -## hash_set::rbegin (STL/CLR) +## `hash_set::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2069,7 +2069,7 @@ a b c *++rbegin() = b ``` -## hash_set::reference (STL/CLR) +## `hash_set::reference` The type of a reference to an element. @@ -2114,7 +2114,7 @@ int main() a b c ``` -## hash_set::rehash (STL/CLR) +## `hash_set::rehash` Rebuilds the hash table. @@ -2126,7 +2126,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_set::load_factor (STL/CLR)](#load_factor)`() <=` [hash_set::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2188,7 +2188,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::rend (STL/CLR) +## `hash_set::rend` Designates the end of the reversed controlled sequence. @@ -2237,7 +2237,7 @@ a b c *--rend() = a ``` -## hash_set::reverse_iterator (STL/CLR) +## `hash_set::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2279,7 +2279,7 @@ int main() c b a ``` -## hash_set::size (STL/CLR) +## `hash_set::size` Counts the number of elements. @@ -2291,7 +2291,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_set::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -2333,9 +2333,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_set::size_type (STL/CLR) +## `hash_set::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2381,7 +2381,7 @@ a b c end()-begin() = 3 ``` -## hash_set::swap (STL/CLR) +## `hash_set::swap` Swaps the contents of two containers. @@ -2393,12 +2393,12 @@ void swap(hash_set% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2449,7 +2449,7 @@ d e f a b c ``` -## hash_set::to_array (STL/CLR) +## `hash_set::to_array` Copies the controlled sequence to a new array. @@ -2499,7 +2499,7 @@ a b c d a b c ``` -## hash_set::upper_bound (STL/CLR) +## `hash_set::upper_bound` Finds end of range that matches a specified key. @@ -2511,12 +2511,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2556,7 +2556,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## hash_set::value_comp (STL/CLR) +## `hash_set::value_comp` Copies the ordering delegate for two element values. @@ -2600,7 +2600,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_set::value_compare (STL/CLR) +## `hash_set::value_compare` The ordering delegate for two element values. @@ -2645,7 +2645,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_set::value_type (STL/CLR) +## `hash_set::value_type` The type of an element. diff --git a/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md b/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md index 14d59ab612..de752c26f9 100644 --- a/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md +++ b/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Hosting a Windows Form User Control as an MFC Dialog Box" title: "Hosting a Windows Form User Control as an MFC Dialog Box" -ms.date: "11/04/2016" +description: "Learn more about: Hosting a Windows Form User Control as an MFC Dialog Box" +ms.date: 11/04/2016 helpviewer_keywords: ["MFC [C++], Windows Forms support", "Windows Forms [C++], hosting as MFC Dialog", "hosting Windows Forms control [C++]"] -ms.assetid: 0434a9d7-8b14-48e6-ad69-9ba9a684677a --- # Hosting a Windows Form User Control as an MFC Dialog Box -MFC provides the template class [CWinFormsDialog](../mfc/reference/cwinformsdialog-class.md) so that you can host a Windows Forms user control () in a modal or modeless MFC dialog box. `CWinFormsDialog` is derived from the MFC class [CDialog](../mfc/reference/cdialog-class.md), so the dialog box can be launched as modal or modeless. +MFC provides the template class [`CWinFormsDialog`](../mfc/reference/cwinformsdialog-class.md) so that you can host a Windows Forms user control () in a modal or modeless MFC dialog box. `CWinFormsDialog` is derived from the MFC class [`CDialog`](../mfc/reference/cdialog-class.md), so the dialog box can be launched as modal or modeless. -The process that `CWinFormsDialog` uses to host the user control is the similar to that described in [Hosting a Windows Form User Control in an MFC Dialog Box](../dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md). However, `CWinFormsDialog` manages the initialization and hosting of the user control so that it does not have to be programmed manually. +The process that `CWinFormsDialog` uses to host the user control is similar to that described in [Hosting a Windows Form User Control in an MFC Dialog Box](hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md). However, `CWinFormsDialog` manages the initialization and hosting of the user control so that it does not have to be programmed manually. ### To create the MFC host application @@ -17,7 +16,7 @@ The process that `CWinFormsDialog` uses to host the user control is the similar On the **File** menu, select **New**, and then click **Project**. In the **Visual C++** folder, select **MFC Application**. - In the **Name** box, enter `MFC03` and change the Solution setting to **Add to Solution**.Click **OK**. + In the **Name** box, enter `MFC03` and change the Solution setting to **Add to Solution**. Click **OK**. In the **MFC Application Wizard**, accept all the defaults, and then click **Finish**. This creates an MFC application with a Multiple Document Interface. @@ -29,21 +28,21 @@ The process that `CWinFormsDialog` uses to host the user control is the similar 1. Add a reference to the .NET control. - In **Solution Explorer**, right-click the **MFC03** project node and choose **Add**, **References**. In the **Property Page**, click **Add New Reference**, select WindowsControlLibrary1 (under the **Projects** tab), and click **OK**. This adds a reference in the form of a [/FU](../build/reference/fu-name-forced-hash-using-file.md) compiler option so that the program will compile; it also copies WindowsControlLibrary1.dll into the `MFC03` project directory so that the program will run. + In **Solution Explorer**, right-click the **MFC03** project node and choose **Add**, **References**. In the **Property Page**, click **Add New Reference**, select WindowsControlLibrary1 (under the **Projects** tab), and click **OK**. This adds a reference in the form of a [`/FU`](../build/reference/fu-name-forced-hash-using-file.md) compiler option so that the program will compile; it also copies `WindowsControlLibrary1.dll` into the `MFC03` project directory so that the program will run. 1. Add `#include ` to *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier), at the end of the existing `#include` statements. 1. Add a new class that subclasses `CDialog`. - Right click on project name and add an MFC class (called CHostForWinForm) that subclasses `CDialog`. Since you do not need the dialog box resource, you can delete the resource ID (select **Resource View**, expand the **Dialog** folder and delete `IDD_HOSTFORWINFORM` resource. Then, remove any references to the ID in code.). + Right click on project name and add an MFC class (called `CHostForWinForm`) that subclasses `CDialog`. Since you do not need the dialog box resource, you can delete the resource ID (select **Resource View**, expand the **Dialog** folder and delete `IDD_HOSTFORWINFORM` resource. Then, remove any references to the ID in code.). -1. Replace `CDialog` in CHostForWinForm.h and CHostForWinForm.cpp files with `CWinFormsDialog`. +1. Replace `CDialog` in `CHostForWinForm.h` and `CHostForWinForm.cpp` files with `CWinFormsDialog`. -1. Call DoModal on the CHostForWinForm class. +1. Call `DoModal` on the `CHostForWinForm` class. - In MFC03.cpp, add `#include "HostForWinForm.h"`. + In `MFC03.cpp`, add `#include "HostForWinForm.h"`. - Before the return statement in the definition of CMFC03App::InitInstance, add: + Before the return statement in the definition of `CMFC03App::InitInstance`, add: ```cpp CHostForWinForm m_HostForWinForm; @@ -58,15 +57,15 @@ The process that `CWinFormsDialog` uses to host the user control is the similar Next you will add code to monitor the state of a control on the Windows Forms from the MFC application. -1. Add a handler for OnInitDialog. +1. Add a handler for `OnInitDialog`. - Display the **Properties** window (F4). In **Class View**, select CHostForWinForm. In the **Properties** window, select overrides and in the row for OnInitDialog, click in the left hand column and select \< Add >. This adds the following line to CHostForWinForm.h: + Display the **Properties** window (F4). In **Class View**, select `CHostForWinForm`. In the **Properties** window, select overrides and in the row for `OnInitDialog`, click in the left hand column and select \< Add >. This adds the following line to `CHostForWinForm.h`: ```cpp virtual BOOL OnInitDialog(); ``` -1. Define OnInitDialog (in CHostForWinForm.cpp) as follows: +1. Define `OnInitDialog` (in `CHostForWinForm.cpp`) as follows: ```cpp BOOL CHostForWinForm::OnInitDialog() { @@ -76,7 +75,7 @@ The process that `CWinFormsDialog` uses to host the user control is the similar } ``` -1. Next add the OnButton1 handler. Add the following lines to the public section of the CHostForWinForm class in CHostForWinForm.h: +1. Next add the `OnButton1` handler. Add the following lines to the public section of the `CHostForWinForm` class in `CHostForWinForm.h`: ```cpp virtual void OnButton1( System::Object^ sender, System::EventArgs^ e ); @@ -86,7 +85,7 @@ The process that `CWinFormsDialog` uses to host the user control is the similar END_DELEGATE_MAP() ``` - In CHostForWinForm.cpp, add this definition: + In `CHostForWinForm.cpp`, add this definition: ```cpp void CHostForWinForm::OnButton1( System::Object^ sender, System::EventArgs^ e ) @@ -99,13 +98,13 @@ The process that `CWinFormsDialog` uses to host the user control is the similar Next you will add code to display from the MFC code the value in the text box on the Windows Form. -1. In the public section of the CHostForWinForm class in CHostForWinForm.h, add the following declaration: +1. In the public section of the `CHostForWinForm` class in `CHostForWinForm.h`, add the following declaration: ```cpp CString m_sEditBoxOnWinForm; ``` -1. In the definition of DoDataExchange in CHostForWinForm.cpp, add the following three lines to the end of the function: +1. In the definition of `DoDataExchange` in `CHostForWinForm.cpp`, add the following four lines to the end of the function: ```cpp if (pDX->m_bSaveAndValidate) @@ -114,7 +113,7 @@ The process that `CWinFormsDialog` uses to host the user control is the similar GetControl()->textBox1->Text = gcnew System::String(m_sEditBoxOnWinForm); ``` -1. In the definition of OnButton1 in CHostForWinForm.cpp, add the following three lines to the end of the function: +1. In the definition of `OnButton1` in `CHostForWinForm.cpp`, add the following three lines to the end of the function: ```cpp this->UpdateData(TRUE); @@ -126,5 +125,5 @@ The process that `CWinFormsDialog` uses to host the user control is the similar ## See also - -[Using a Windows Form User Control in MFC](../dotnet/using-a-windows-form-user-control-in-mfc.md) +\ +[Using a Windows Form User Control in MFC](using-a-windows-form-user-control-in-mfc.md) diff --git a/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md b/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md index 178581d23a..b7b889caf1 100644 --- a/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md +++ b/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md @@ -22,7 +22,10 @@ MFC hosts a Windows Forms control as a special kind of ActiveX control and commu ## Reference -[CWinFormsControl Class](../mfc/reference/cwinformscontrol-class.md) | [CDialog Class](../mfc/reference/cdialog-class.md) | [CWnd Class](../mfc/reference/cwnd-class.md) | +[`CWinFormsControl` Class](../mfc/reference/cwinformscontrol-class.md)\ +[`CDialog` Class](../mfc/reference/cdialog-class.md)\ +[`CWnd` Class](../mfc/reference/cwnd-class.md)\ + ## See also diff --git a/docs/dotnet/how-to-access-characters-in-a-system-string.md b/docs/dotnet/how-to-access-characters-in-a-system-string.md index 1dab0f2a63..c16e9e8720 100644 --- a/docs/dotnet/how-to-access-characters-in-a-system-string.md +++ b/docs/dotnet/how-to-access-characters-in-a-system-string.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Access Characters in a System::String" title: "How to: Access Characters in a System::String" +description: "Learn more about: How to: Access Characters in a System::String" +ms.date: 11/04/2016 ms.custom: "get-started-article" -ms.date: "11/04/2016" helpviewer_keywords: ["characters [C++], accessing in System::String", "examples [C++], strings", "strings [C++], accessing characters"] -ms.assetid: cfc89756-aef3-4988-907e-fb236dcb7087 --- # How to: Access Characters in a System::String @@ -21,7 +20,7 @@ If you pass `ppchar` to a native function, then it must be a pinning pointer; th ```cpp // PtrToStringChars.cpp // compile with: /clr -#include +#include using namespace System; int main() { @@ -54,7 +53,7 @@ size_t getlen(System::String ^ s) { // make sure it doesn't move during the unmanaged call pin_ptr pinchars = PtrToStringChars(s); return wcsnlen(pinchars, maxsize); -}; +} int main() { System::Console::WriteLine(getlen("testing")); diff --git a/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md b/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md index f0987db970..88f4ef71bb 100644 --- a/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md +++ b/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md @@ -13,7 +13,7 @@ This topic shows how to convert STL/CLR containers to their equivalent .NET coll 1. Use one of the following methods: - - To convert part of a container, call the [make_collection](./adapter-stl-clr.md#make_collection) function, and pass the begin iterator and end iterator of the STL/CLR container to be copied into the .NET collection. This template function takes an STL/CLR iterator as a template argument. The first example demonstrates this method. + - To convert part of a container, call the [make_collection](./adapter-stl-clr.md#make_collection) function, and pass the begin iterator and end iterator of the STL/CLR container to be copied into the .NET collection. This function template takes an STL/CLR iterator as a template argument. The first example demonstrates this method. - To convert an entire container, cast the container to an appropriate .NET collection interface or interface collection. The second example demonstrates this method. diff --git a/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md b/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md index a84ac096d4..4bdccb60b0 100644 --- a/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md +++ b/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md @@ -15,7 +15,7 @@ You can use the **CLR Console Application** template in the **New Project** dia You can use the **CLR Console App** template in the **New Project** dialog to create a console app project that already has essential project references and files. -C++/CLI support isn't installed by default when you install a Visual Studio C++ workload. If you don't see a CLR heading under Visual C++ in the **New Project** dialog, you may need to install C++/CLI support. For more information, see [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md). +C++/CLI support isn't installed by default when you install a Visual Studio C++ workload. If you don't see a CLR heading under Visual C++ in the **New Project** dialog, you may need to install C++/CLI support. For more information, see [Install C++/CLI support in Visual Studio 2022](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). ::: moniker-end ::: moniker range=">=msvc-160" diff --git a/docs/dotnet/how-to-create-clr-empty-projects.md b/docs/dotnet/how-to-create-clr-empty-projects.md index 1a34671db3..ff213eeef3 100644 --- a/docs/dotnet/how-to-create-clr-empty-projects.md +++ b/docs/dotnet/how-to-create-clr-empty-projects.md @@ -18,7 +18,8 @@ To create a CLR empty project, use the **CLR Empty Project** template, which is The **New Project** dialog box appears. -1. Under **Installed Templates**, click the **Visual C++** node; then click the **CLR** node. Choose the **CLR Empty Project** icon. +1. Under **Installed Templates**, click the **Visual C++** node; then click the **CLR** node. Choose the **CLR Empty Project** icon. If you don't see the CLR empty project templates in the Create a new project dialog, you may need to install C++/CLI support. For more information, see [Install C++/CLI support in Visual Studio 2022](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). + 1. In the **Name** box, enter a unique name for your application. diff --git a/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md b/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md index a9e25c2df5..3eeb84d31e 100644 --- a/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md +++ b/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: How to: Declare Override Specifiers in Native Compilations (C++/CLI)" title: "How to: Declare Override Specifiers (C++/CLI)" +description: "Learn more about: How to: Declare Override Specifiers in Native Compilations (C++/CLI)" ms.date: "11/04/2016" helpviewer_keywords: ["override specifiers in native compilation, overriding"] -ms.assetid: d0551836-9ac7-41eb-a6e9-a4b3ef60767d --- # How to: Declare Override Specifiers in Native Compilations (C++/CLI) -[sealed](../extensions/sealed-cpp-component-extensions.md), [abstract](../extensions/abstract-cpp-component-extensions.md), and [override](../extensions/override-cpp-component-extensions.md) are available in compilations that do not use **/ZW** or [/clr](../build/reference/clr-common-language-runtime-compilation.md). +[`sealed`](../extensions/sealed-cpp-component-extensions.md), [`abstract`](../extensions/abstract-cpp-component-extensions.md), and [`override`](../extensions/override-cpp-component-extensions.md) are available in compilations that do not use **/ZW** or [`/clr`](../build/reference/clr-common-language-runtime-compilation.md). > [!NOTE] -> The ISO C++11 Standard language has the [override](../cpp/override-specifier.md) identifier and the [final](../cpp/final-specifier.md) identifier, and both are supported in Visual Studio Use `final` instead of **`sealed`** in code that is meant to be compiled as native-only. +> The ISO C++11 Standard language [`override`](../cpp/override-specifier.md) and [`final`](../cpp/final-specifier.md) specifiers are supported in Visual Studio. Use `final` instead of **`sealed`** in code that is meant to be compiled as native-only. ## Example: sealed is valid @@ -67,7 +66,7 @@ public: ### Description -This example shows that **`abstract`** is valid in native compilations. +This example shows that `abstract` is valid in native compilations. ### Code diff --git a/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md b/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md index f2aeaa4c5b..a0b88ce253 100644 --- a/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md +++ b/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md @@ -3,7 +3,6 @@ title: "How to: Define and consume classes and structs (C++/CLI)" description: "How to create and use user-defined class and struct types in C++/CLI code." ms.date: 09/25/2020 helpviewer_keywords: ["structs [C++]", "classes [C++], instantiating"] -ms.assetid: 1c03cb0d-1459-4b5e-af65-97d6b3094fd7 --- # How to: Define and consume classes and structs (C++/CLI) @@ -467,7 +466,7 @@ in static constructor ## Semantics of the `this` pointer -When you're using C++\CLI to define types, the **`this`** pointer in a reference type is of type *handle*. The **`this`** pointer in a value type is of type *interior pointer*. +When you're using C++/CLI to define types, the **`this`** pointer in a reference type is of type *handle*. The **`this`** pointer in a value type is of type *interior pointer*. These different semantics of the **`this`** pointer can cause unexpected behavior when a default indexer is called. The next example shows the correct way to access a default indexer in both a ref type and a value type. @@ -636,7 +635,7 @@ The following sample demonstrates when a copy constructor isn't generated. ```cpp // compile with: /clr -#include +#include struct S { int i; @@ -802,13 +801,13 @@ If your type has a finalizer, the compiler generates a `Finalize(void)` method t If a type has either a finalizer or a destructor, the compiler generates a `Dispose(bool)` method, according to the design pattern. (For information, see [Dispose Pattern](/dotnet/standard/design-guidelines/dispose-pattern)). You can't explicitly author or call `Dispose(bool)` in Visual C++. -If a type has a base class that conforms to the design pattern, the destructors for all base classes are called when the destructor for the derived class is called. (If your type is written in Visual C++, the compiler ensures that your types implement this pattern.) In other words, the destructor of a reference class chains to its bases and members as specified by the C++ standard. First, the class’s destructor is run. Then, the destructors for its members get run in the reverse of the order in which they were constructed. Finally, the destructors for its base classes get run in the reverse of the order in which they were constructed. +If a type has a base class that conforms to the design pattern, the destructors for all base classes are called when the destructor for the derived class is called. (If your type is written in Visual C++, the compiler ensures that your types implement this pattern.) In other words, the destructor of a reference class chains to its bases and members as specified by the C++ standard. First, the class's destructor is run. Then, the destructors for its members get run in the reverse of the order in which they were constructed. Finally, the destructors for its base classes get run in the reverse of the order in which they were constructed. Destructors and finalizers aren't allowed inside value types or interfaces. A finalizer can only be defined or declared in a reference type. Like a constructor and destructor, a finalizer has no return type. -After an object's finalizer runs, finalizers in any base classes are also called, beginning with the least derived type. Finalizers for data members aren't automatically chained to by a class’s finalizer. +After an object's finalizer runs, finalizers in any base classes are also called, beginning with the least derived type. Finalizers for data members aren't automatically chained to by a class's finalizer. If a finalizer deletes a native pointer in a managed type, you must ensure that references to or through the native pointer aren't prematurely collected. Call the destructor on the managed type instead of using . diff --git a/docs/dotnet/how-to-define-and-consume-enums-in-cpp-cli.md b/docs/dotnet/how-to-define-and-consume-enums-in-cpp-cli.md index 33d95fd07e..63b3121f25 100644 --- a/docs/dotnet/how-to-define-and-consume-enums-in-cpp-cli.md +++ b/docs/dotnet/how-to-define-and-consume-enums-in-cpp-cli.md @@ -1,15 +1,15 @@ --- description: "Learn more about: How to: Define and consume enums in C++/CLI" title: "How to: Define and consume enums in C++/CLI" -ms.date: "11/04/2016" +ms.date: 06/30/2022 helpviewer_keywords: ["enum class, specifying underlying types"] ms.assetid: df8f2b91-b9d2-4fab-9be4-b1d58b8bc570 --- # How to: Define and consume enums in C++/CLI -This topic discusses enums in C++/CLI. +Enumeration types in C++/CLI have some differences with enumeration types in standard C++. This article explains how to use C++/CLI enumeration types and how to interoperate with standard enumeration types. -## Specifying the underlying type of an enum +## Specifying the underlying type of an `enum` By default, the underlying type of an enumeration is **`int`**. However, you can specify the type to be signed or unsigned forms of **`int`**, **`short`**, **`long`**, **`__int32`**, or **`__int64`**. You can also use **`char`**. @@ -43,7 +43,7 @@ sun ## How to convert between managed and standard enumerations -There is no standard conversion between an enum and an integral type; a cast is required. +There's no standard conversion between an enum and an integral type; a cast is required. ```cpp // mcppv2_enum_4.cpp @@ -73,20 +73,20 @@ a and day2 are the same The following operators are valid on enums in C++/CLI: -|Operator| -|--------------| -|== != \< > \<= >=| -|+ -| -|| ^ & ~| -|++ --| -|sizeof| +| Operator | +|--| +| `==` `!=` `<` `>` `<=` `>=` | +| `+` `-` | +| `|` `^` `&` `~` | +| `++` `--` | +| `sizeof` | -Operators | ^ & ~ ++ -- are defined only for enumerations with integral underlying types, not including bool. Both operands must be of the enumeration type. +Operators `|`, `^`, `&`, `~`, `++`, and `--` are defined only for enumerations with integral underlying types, not including `bool`. Both operands must be of the enumeration type. The compiler does no static or dynamic checking of the result of an enum operation; an operation may result in a value not in the range of the enum's valid enumerators. > [!NOTE] -> C++11 introduces enum class types in unmanaged code which are significantly different than managed enum classes in C++/CLI. In particular, the C++11 enum class type does not support the same operators as the managed enum class type in C++/CLI, and C++/CLI source code must provide an accessibility specifier in managed enum class declarations in order to distinguish them from unmanaged (C++11) enum class declarations. For more information about enum classes in C++/CLI, C++/CX, and C++11, see [enum class](../extensions/enum-class-cpp-component-extensions.md). +> C++11 introduces `enum class` types in unmanaged code, which are significantly different than managed `enum class` types in C++/CLI. In particular, the C++11 `enum class` type does not support the same operators as the managed `enum class` type in C++/CLI, and C++/CLI source code must provide an accessibility specifier in managed `enum class` declarations in order to distinguish them from unmanaged (C++11) `enum class` declarations. For more information about `enum class` use in C++/CLI, C++/CX, and C++11, see [`enum class`](../extensions/enum-class-cpp-component-extensions.md). ```cpp // mcppv2_enum_5.cpp @@ -104,6 +104,8 @@ int main() { } ``` +Use scope qualifiers to distinguish between `enum` and `enum class` values: + ```cpp // mcppv2_enum_6.cpp // compile with: /clr @@ -131,4 +133,4 @@ True ## See also -[enum class](../extensions/enum-class-cpp-component-extensions.md) +[`enum class`](../extensions/enum-class-cpp-component-extensions.md) diff --git a/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md b/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md index 3a2235ad91..eec4a6002e 100644 --- a/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md +++ b/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: How to: Define and Use Delegates (C++/CLI)" title: "How to: Define and Use Delegates (C++/CLI)" -ms.date: "11/04/2016" +description: "Learn more about: How to: Define and Use Delegates (C++/CLI)" +ms.date: 11/04/2016 helpviewer_keywords: ["delegates"] -ms.assetid: 1cdf3420-89c1-47c0-b796-aa984020e0f8 --- # How to: Define and Use Delegates (C++/CLI) @@ -442,7 +441,7 @@ int main() { Del^ d = gcnew Del(r1, &R::f); d += gcnew Del(&R::f); d(r2); -}; +} ``` **Output** diff --git a/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md b/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md index a86ffde885..476d54cfb5 100644 --- a/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md +++ b/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md @@ -8,9 +8,9 @@ ms.assetid: 5a854822-6172-4b22-b236-320165412568 --- # How to: Determine if an Image is Native or CLR -One way to determine whether an image was built for the common language runtime is to use **dumpbin**[/CLRHEADER](../build/reference/clrheader.md). +One way to determine whether an image was built for the common language runtime is to use the **`dumpbin /CLRHEADER`** command. For more information, see [`/CLRHEADER`](../build/reference/clrheader.md). -You can also programmatically check whether an image was built for the common language runtime. For more information, see [How to: Detect /clr Compilation](../dotnet/how-to-detect-clr-compilation.md). +You can also programmatically check whether an image was built for the common language runtime. For more information, see [How to: Detect /clr compilation](../dotnet/how-to-detect-clr-compilation.md). ## Example diff --git a/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md b/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md index 7d77830650..098179c4ef 100644 --- a/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md +++ b/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Do DDX/DDV Data Binding with Windows Forms" title: "How to: Do DDX-DDV Data Binding with Windows Forms" +description: "Learn more about: How to: Do DDX/DDV Data Binding with Windows Forms" ms.custom: "get-started-article" ms.date: "11/04/2016" helpviewer_keywords: ["MFC [C++], hosting a Windows Forms Control", "Windows Forms [C++], MFC support"] -ms.assetid: b2957370-cf1f-4779-94ac-228cd393686c --- # How to: Do DDX/DDV Data Binding with Windows Forms @@ -53,7 +52,7 @@ void CMFC01Dlg::DoDataExchange(CDataExchange* pDX) ## Example: Add handler method -Now we will add the handler method for a click on the OK button. Click the **Resource View** tab. In Resource View, double-click on `IDD_MFC01_DIALOG`. The dialog resource appears in Resource Editor. Then double click the OK button.. +Now we will add the handler method for a click on the OK button. Click the **Resource View** tab. In Resource View, double-click on `IDD_MFC01_DIALOG`. The dialog resource appears in Resource Editor. Then double click the OK button. Define the handler as follows. @@ -77,6 +76,6 @@ You can now build and run the application. Notice that any text in the text box ## See also -[CWinFormsControl Class](../mfc/reference/cwinformscontrol-class.md)
-[DDX_ManagedControl](../mfc/reference/standard-dialog-data-exchange-routines.md#ddx_managedcontrol)
+[CWinFormsControl Class](../mfc/reference/cwinformscontrol-class.md)\ +[DDX_ManagedControl](../mfc/reference/standard-dialog-data-exchange-routines.md#ddx_managedcontrol)\ [CWnd::DoDataExchange](../mfc/reference/cwnd-class.md#dodataexchange) diff --git a/docs/dotnet/how-to-marshal-arrays-using-pinvoke.md b/docs/dotnet/how-to-marshal-arrays-using-pinvoke.md index fff6040778..846c077d53 100644 --- a/docs/dotnet/how-to-marshal-arrays-using-pinvoke.md +++ b/docs/dotnet/how-to-marshal-arrays-using-pinvoke.md @@ -1,24 +1,22 @@ --- -description: "Learn more about: How to: Marshal Arrays Using PInvoke" -title: "How to: Marshal Arrays Using PInvoke" +description: "Learn more about: How to: Marshal arrays using P/Invoke" +title: "How to: Marshal arrays using P/Invoke" ms.custom: "get-started-article" -ms.date: "11/04/2016" +ms.date: 06/30/2022 helpviewer_keywords: ["marshaling [C++], arrays", "platform invoke [C++], arrays", "interop [C++], arrays", "data marshaling [C++], arrays"] ms.assetid: a1237797-a2da-4df4-984a-6333ed3af406 --- -# How to: Marshal Arrays Using PInvoke +# How to: Marshal arrays using P/Invoke -This topic explains how native functions that accept C-style strings can be called using the CLR string type using .NET Framework Platform Invoke support. Visual C++ programmers are encouraged to use the C++ Interop features instead (when possible) because P/Invoke provides little compile-time error reporting, is not type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL and the source code is not available, P/Invoke is the only option (otherwise, see [Using C++ Interop (Implicit PInvoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md)). +You can call native functions that accept C-style strings by using the CLR string type when using .NET Framework Platform Invoke (P/Invoke) support. We encourage you to use the C++ Interop features instead of P/Invoke when possible. P/Invoke provides little compile-time error reporting, isn't type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL and the source code isn't available, P/Invoke is the only option. Otherwise, see [Using C++ Interop (Implicit P/Invoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md)). ## Example -Because native and managed arrays are laid out differently in memory, passing them successfully across the managed/unmanaged boundary requires conversion, or marshaling. This topic demonstrates how an array of simple (blitable) items can be passed to native functions from managed code. +Because native and managed arrays are laid out differently in memory, passing them successfully across the managed/unmanaged boundary requires conversion, or *marshaling*. This article demonstrates how an array of simple (blitable) items can be passed to native functions from managed code. -As is true of managed/unmanaged data marshaling in general, the attribute is used to create a managed entry point for each native function that will be used. In the case of functions that take arrays as arguments, the attribute must be used as well to specify to the compiler how the data will be marshaled. In the following example, the enumeration is used to indicate that the managed array will be marshaled as a C-style array. +As is true of managed/unmanaged data marshaling in general, the attribute is used to create a managed entry point for each native function that's used. In functions that take arrays as arguments, the attribute must be used to specify how to marshal the data. In the following example, the enumeration is used to indicate that the managed array is marshaled as a C-style array. -The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function that accepts an array of integers. The second module is a managed command-line application that imports this function, but defines it in terms of a managed array, and uses the attribute to specify that the array should be converted to a native array when called. - -The managed module is compiled with /clr. +The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function that accepts an array of integers. The second module is a managed command-line application that imports this function, but defines it in terms of a managed array. It uses the attribute to specify that the array should be converted to a native array when called. ```cpp // TraditionalDll4.cpp @@ -43,6 +41,8 @@ void TakesAnArray(int len, int a[]) { } ``` +The managed module is compiled by using **`/clr`**. + ```cpp // MarshalBlitArray.cpp // compile with: /clr @@ -68,8 +68,8 @@ int main() { } ``` -Note that no portion of the DLL is exposed to the managed code through the traditional #include directive. In fact, because the DLL is accessed at run time only, problems with functions imported with will not be detected at compile time. +No portion of the DLL is exposed to the managed code through the traditional `#include` directive. In fact, because the DLL is accessed at runtime only, problems in functions imported by using can't be detected at compile time. ## See also -[Using Explicit PInvoke in C++ (DllImport Attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) +[Using explicit P/Invoke in C++ (`DllImport` attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) diff --git a/docs/dotnet/how-to-marshal-embedded-pointers-using-pinvoke.md b/docs/dotnet/how-to-marshal-embedded-pointers-using-pinvoke.md index b99c197df4..90d5955f5b 100644 --- a/docs/dotnet/how-to-marshal-embedded-pointers-using-pinvoke.md +++ b/docs/dotnet/how-to-marshal-embedded-pointers-using-pinvoke.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: How to: Marshal Embedded Pointers Using PInvoke" -title: "How to: Marshal Embedded Pointers Using PInvoke" +description: "Learn more about: How to: Marshal embedded pointers using P/Invoke" +title: "How to: Marshal embedded pointers using P/Invoke" ms.custom: "get-started-article" -ms.date: "11/04/2016" +ms.date: 06/29/2022 helpviewer_keywords: ["embedded pointers [C++]", "interop [C++], embedded pointers", "platform invoke [C++], embedded pointers", "marshaling [C++], embedded pointers", "data marshaling [C++], embedded pointers"] ms.assetid: f12c1b9a-4f82-45f8-83c8-3fc9321dbb98 --- -# How to: Marshal Embedded Pointers Using PInvoke +# How to: Marshal embedded pointers using P/Invoke -Functions that are implemented in unmanaged DLLs can be called from managed code using Platform Invoke (P/Invoke) functionality. If the source code for the DLL is not available, P/Invoke is the only option for interoperating. However, unlike other .NET languages, Visual C++ provides an alternative to P/Invoke. For more information, see [Using C++ Interop (Implicit PInvoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md) and [How to: Marshal Embedded Pointers Using C++ Interop](../dotnet/how-to-marshal-embedded-pointers-using-cpp-interop.md). +Functions that are implemented in unmanaged DLLs can be called from managed code using Platform Invoke (P/Invoke) functionality. If the source code for the DLL isn't available, P/Invoke is the only option for interoperating. However, unlike other .NET languages, Visual C++ provides an alternative to P/Invoke. For more information, see [Using C++ Interop (Implicit P/Invoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md) and [How to: Marshal embedded pointers using C++ Interop](../dotnet/how-to-marshal-embedded-pointers-using-cpp-interop.md). ## Example Passing structures to native code requires that a managed structure that is equivalent in terms of data layout to the native structure is created. However, structures that contain pointers require special handling. For each embedded pointer in the native structure, the managed version of the structure should contain an instance of the type. Also, memory for these instances must be explicitly allocated, initialized, and released using the , , and methods. -The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function that accepts a structure called ListString that contains a pointer, and a function called TakesListStruct. The managed module is a command-line application that imports the TakesListStruct function and defines a structure called MListStruct that is equivalent to the native ListStruct except that the double* is represented with an instance. Before calling TakesListStruct, the main function allocates and initializes the memory that this field references. +The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function that accepts a structure called `ListString` that contains a pointer, and a function called `TakesListStruct`. ```cpp // TraditionalDll6.cpp @@ -46,6 +46,8 @@ void TakesListStruct(ListStruct list) { } ``` +The managed module is a command-line application that imports the `TakesListStruct` function and defines a structure called `MListStruct` that is equivalent to the native `ListStruct` except that the `double*` is represented with an instance. Before it calls `TakesListStruct`, the `main` function allocates and initializes the memory that this field references. + ```cpp // EmbeddedPointerMarshalling.cpp // compile with: /clr @@ -88,8 +90,8 @@ int main() { } ``` -Note that no portion of the DLL is exposed to the managed code using the traditional #include directive. In fact, the DLL is accessed at run time only, so problems with functions imported with will not be detected at compile time. +No portion of the DLL is exposed to the managed code using the traditional `#include` directive. In fact, the DLL is accessed at runtime only, so problems in functions imported by using can't be detected at compile time. ## See also -[Using Explicit PInvoke in C++ (DllImport Attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) +[Using explicit P/Invoke in C++ (`DllImport` attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) diff --git a/docs/dotnet/how-to-marshal-function-pointers-using-pinvoke.md b/docs/dotnet/how-to-marshal-function-pointers-using-pinvoke.md index d633c3c7b4..90e00d5bb5 100644 --- a/docs/dotnet/how-to-marshal-function-pointers-using-pinvoke.md +++ b/docs/dotnet/how-to-marshal-function-pointers-using-pinvoke.md @@ -1,28 +1,24 @@ --- -description: "Learn more about: How to: Marshal Function Pointers Using PInvoke" -title: "How to: Marshal Function Pointers Using PInvoke" +description: "Learn more about: How to: Marshal function pointers using P/Invoke" +title: "How to: Marshal function pointers using P/Invoke" ms.custom: "get-started-article" -ms.date: "11/04/2016" +ms.date: 06/29/2022 helpviewer_keywords: ["data marshaling [C++], callbacks and delegates", "interop [C++], callbacks and delegates", "platform invoke [C++], callbacks and delegates", "marshaling [C++], callbacks and delegates"] ms.assetid: dcf396fd-a91d-49c0-ab0b-1ea160668a89 --- -# How to: Marshal Function Pointers Using PInvoke +# How to: Marshal function pointers using P/Invoke -This topic explains how managed delegates can be used in place of function pointers when interoperating with unmanaged functions using .NET Framework P/Invoke features. However, Visual C++ programmers are encouraged to use the C++ Interop features instead (when possible) because P/Invoke provides little compile-time error reporting, is not type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL and the source code is not available, P/Invoke is the only option. Otherwise, see the following topics: +Managed delegates can be used in place of function pointers when interoperating with unmanaged functions by using .NET Framework P/Invoke features. However, we encourage you to use the C++ Interop features instead, when possible. P/Invoke provides little compile-time error reporting, isn't type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL and the source code isn't available, P/Invoke is the only option. Otherwise, see these articles: -- [Using C++ Interop (Implicit PInvoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md) +- [Using C++ Interop (Implicit P/Invoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md) -- [How to: Marshal Callbacks and Delegates By Using C++ Interop](../dotnet/how-to-marshal-callbacks-and-delegates-by-using-cpp-interop.md) +- [How to: Marshal callbacks and delegates by using C++ Interop](../dotnet/how-to-marshal-callbacks-and-delegates-by-using-cpp-interop.md) -Unmanaged APIs that take functions pointers as arguments can be called from managed code with a managed delegate in place of the native function pointer. The compiler automatically marshals the delegate to unmanaged functions as a function pointer and inserts the necessary managed/unmanaged transition code. +Unmanaged APIs that take functions pointers as arguments can be called from managed code by using a managed delegate in place of the native function pointer. The compiler automatically marshals the delegate to unmanaged functions as a function pointer. It inserts the necessary managed/unmanaged transition code. ## Example -The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function called TakesCallback that accepts a function pointer. This address is used to execute the function. - -The managed module defines a delegate that is marshaled to the native code as a function pointer and uses the attribute to expose the native TakesCallback function to the managed code. In the main function, an instance of the delegate is created and passed to the TakesCallback function. The program output demonstrates that this function gets executed by the native TakesCallback function. - -The managed function suppresses garbage collection for the managed delegate to prevent .NET Framework garbage collection from relocating the delegate while the native function executes. +The following code consists of an unmanaged and a managed module. The unmanaged module is a DLL that defines a function called `TakesCallback` that accepts a function pointer. This address is used to execute the function. ```cpp // TraditionalDll5.cpp @@ -48,6 +44,10 @@ int TakesCallback(CALLBACK fp, int n) { } ``` +The managed module defines a delegate that's marshaled to the native code as a function pointer. It uses the attribute to expose the native `TakesCallback` function to the managed code. In the `main` function, an instance of the delegate is created and passed to the `TakesCallback` function. The program output demonstrates that this function gets executed by the native `TakesCallback` function. + +The managed function suppresses garbage collection for the managed delegate to prevent .NET Framework garbage collection from relocating the delegate while the native function executes. + ```cpp // MarshalDelegate.cpp // compile with: /clr @@ -76,8 +76,8 @@ int main() { } ``` -Note that no portion of the DLL is exposed to the managed code using the traditional #include directive. In fact, the DLL is accessed at run time only, so problems with functions imported with will not be detected at compile time. +No portion of the DLL is exposed to the managed code using the traditional `#include` directive. In fact, the DLL is accessed at runtime only, so problems with functions imported by using can't be detected at compile time. ## See also -[Using Explicit PInvoke in C++ (DllImport Attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) +[Using explicit P/Invoke in C++ (`DllImport` attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) diff --git a/docs/dotnet/how-to-marshal-strings-using-pinvoke.md b/docs/dotnet/how-to-marshal-strings-using-pinvoke.md index 2f12cdf02d..85a00e53bd 100644 --- a/docs/dotnet/how-to-marshal-strings-using-pinvoke.md +++ b/docs/dotnet/how-to-marshal-strings-using-pinvoke.md @@ -1,26 +1,26 @@ --- -description: "Learn more about: How to: Marshal Strings Using PInvoke" -title: "How to: Marshal Strings Using PInvoke" +description: "Learn more about: How to: Marshal strings using P/Invoke" +title: "How to: Marshal strings using P/Invoke" ms.custom: "get-started-article" -ms.date: "09/09/2016" +ms.date: 06/29/2022 helpviewer_keywords: ["interop [C++], strings", "marshaling [C++], strings", "data marshaling [C++], strings", "platform invoke [C++], strings"] ms.assetid: bcc75733-7337-4d9b-b1e9-b95a98256088 --- -# How to: Marshal Strings Using PInvoke +# How to: Marshal strings using P/Invoke -This topic explains how native functions that accept C-style strings can be called using the CLR string type System::String using .NET Framework Platform Invoke support. Visual C++ programmers are encouraged to use the C++ Interop features instead (when possible) because P/Invoke provides little compile-time error reporting, is not type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL, and the source code is not available, then P/Invoke is the only option, but otherwise see [Using C++ Interop (Implicit PInvoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md). +Native functions that accept C-style strings can be called using the CLR string type `System::String` by using .NET Framework Platform Invoke (P/Invoke) support. We encourage you to use the C++ Interop features instead of P/Invoke when possible. because P/Invoke provides little compile-time error reporting, isn't type-safe, and can be tedious to implement. If the unmanaged API is packaged as a DLL, and the source code isn't available, then P/Invoke is the only option. Otherwise, see [Using C++ Interop (Implicit P/Invoke)](../dotnet/using-cpp-interop-implicit-pinvoke.md). Managed and unmanaged strings are laid out differently in memory, so passing strings from managed to unmanaged functions requires the attribute to instruct the compiler to insert the required conversion mechanisms for marshaling the string data correctly and safely. -As with functions that use only intrinsic data types, is used to declare managed entry points into the native functions, but--for passing strings--instead of defining these entry points as taking C-style strings, a handle to the type can be used instead. This prompts the compiler to insert code that performs the required conversion. For each function argument in an unmanaged function that takes a string, the attribute should be used to indicate that the String object should be marshaled to the native function as a C-style string. +As with functions that use only intrinsic data types, is used to declare managed entry points into the native functions. Functions that pass strings can use a handle to the type instead of defining these entry points as taking C-style strings. Using this type prompts the compiler to insert code that performs the required conversion. For each function argument in an unmanaged function that takes a string, use the attribute to indicate that the `String` object should be marshaled to the native function as a C-style string. -The marshaler wraps the call to the unmanaged function in a hidden wrapper routine that pins and copies the managed string into a locally allocated string in the unmanaged context, which then is passed to the unmanaged function. When the unmanaged function returns, the wrapper either deletes the resource, or if it was on the stack, it is reclaimed when the wrapper goes out of scope. The unmanaged function is not responsible for this memory. The unmanaged code only creates and deletes memory in the heap set up by its own CRT, so there is never an issue with the marshaller using a different CRT version. +The marshaler wraps the call to the unmanaged function in a hidden wrapper routine. The wrapper routine pins and copies the managed string into a locally allocated string in the unmanaged context. The local copy is then passed to the unmanaged function. When the unmanaged function returns, the wrapper deletes the resource. Or, if it was on the stack, it's reclaimed when the wrapper goes out of scope. The unmanaged function isn't responsible for this memory. The unmanaged code only creates and deletes memory in the heap set up by its own CRT, so there's never an issue with the marshaller using a different CRT version. If your unmanaged function returns a string, either as a return value or an out parameter, the marshaler copies it into a new managed string, and then releases the memory. For more information, see [Default Marshaling Behavior](/dotnet/framework/interop/default-marshaling-behavior) and [Marshaling Data with Platform Invoke](/dotnet/framework/interop/marshaling-data-with-platform-invoke). ## Example -The following code consists of a unmanaged and a managed module. The unmanaged module is a DLL that defines a function called TakesAString that accepts a C-style ANSI string in the form of a char*. The managed module is a command-line application that imports the TakesAString function, but defines it as taking a managed System.String instead of a char\*. The attribute is used to indicate how the managed string should be marshaled when TakesAString is called. +The following code consists of an unmanaged module and a managed module. The unmanaged module is a DLL that defines a function called `TakesAString`. `TakesAString` accepts a C-style narrow string in the form of a `char*`. ```cpp // TraditionalDll2.cpp @@ -47,6 +47,8 @@ void TakesAString(char* p) { } ``` +The managed module is a command-line application that imports the `TakesAString` function, but defines it as taking a managed `System.String` instead of a `char*`. The attribute is used to indicate how the managed string should be marshaled when `TakesAString` is called. + ```cpp // MarshalString.cpp // compile with: /clr @@ -62,16 +64,16 @@ value struct TraditionalDLL int main() { String^ s = gcnew String("sample string"); - Console::WriteLine("[managed] passing managed string to unmanaged function..."); + Console::WriteLine("[managed] passing managed string to unmanaged function..."); TraditionalDLL::TakesAString(s); Console::WriteLine("[managed] {0}", s); } ``` -This technique causes a copy of the string to be constructed on the unmanaged heap, so changes made to the string by the native function will not be reflected in the managed copy of the string. +This technique constructs a copy of the string on the unmanaged heap, so changes made to the string by the native function won't be reflected in the managed copy of the string. -Note that no portion of the DLL is exposed to the managed code via the traditional #include directive. In fact, the DLL is accessed at runtime only, so problems with functions imported with `DllImport` will not be detected at compile time. +No portion of the DLL is exposed to the managed code by the traditional `#include` directive. In fact, the DLL is accessed at runtime only, so problems in functions imported by using `DllImport` aren't detected at compile time. ## See also -[Using Explicit PInvoke in C++ (DllImport Attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) +[Using explicit P/Invoke in C++ (`DllImport` attribute)](../dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md) diff --git a/docs/dotnet/how-to-migrate-to-clr.md b/docs/dotnet/how-to-migrate-to-clr.md index eea61e82fc..b3e6d4c633 100644 --- a/docs/dotnet/how-to-migrate-to-clr.md +++ b/docs/dotnet/how-to-migrate-to-clr.md @@ -1,22 +1,22 @@ --- description: "Learn more about: How to: Migrate to /clr" -title: "How to: Migrate to -clr" +title: "How to: Migrate to /clr" ms.custom: "get-started-article" ms.date: "09/18/2018" helpviewer_keywords: ["upgrading Visual C++ applications, /clr compiler option", "compiling native code [C++]", "interoperability [C++], /clr compiler option", "interop [C++], /clr compiler option", "migration [C++], /clr compiler option", "/clr compiler option [C++], porting to"] ms.assetid: c9290b8b-436a-4510-8b56-eae51f4a9afc --- -# How to: Migrate to /clr +# How to: Migrate to `/clr` -This topic discusses issues that arise when compiling native code with **/clr** (see [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) for more information). **/clr** allows native C++ code to invoke and be invoked from .NET assemblies in addition to other native C++ code. See [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md) and [Native and .NET Interoperability](../dotnet/native-and-dotnet-interoperability.md) for more information on the advantages of compiling with **/clr**. +This article discusses issues that arise when compiling native code with **`/clr`**. (For more information, see [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md).) **`/clr`** allows native C++ code to invoke and be invoked from .NET assemblies in addition to other native C++ code. For more information on the advantages of compiling with **`/clr`**, see [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md) and [Native and .NET Interoperability](../dotnet/native-and-dotnet-interoperability.md). -## Known Issues Compiling Library Projects with /clr +## Known issues compiling library projects with `/clr` -Visual Studio contains some known issues when compiling library projects with **/clr**: +Visual Studio contains some known issues when compiling library projects with **`/clr`**: -- Your code may query types at runtime with [CRuntimeClass::FromName](../mfc/reference/cruntimeclass-structure.md#fromname). However, if a type is in an MSIL .dll (compiled with **/clr**), the call to `FromName` may fail if it occurs before the static constructors run in the managed .dll (you will not see this problem if the FromName call happens after code has executed in the managed .dll). To work around this problem, you can force the construction of the managed static constructor by defining a function in the managed .dll, exporting it, and invoking it from the native MFC application. For example: +- Your code may query types at runtime with [`CRuntimeClass::FromName`](../mfc/reference/cruntimeclass-structure.md#fromname). However, if a type is in an MSIL DLL (compiled with **`/clr`**), the call to `FromName` may fail if it occurs before the static constructors run in the managed DLL. (You won't see this problem if the `FromName` call happens after code has executed in the managed DLL.) To work around this problem, you can force the construction of the managed static constructor: define a function in the managed DLL, export it, and invoke it from the native MFC application. For example: - ``` + ```cpp // MFC extension DLL Header file: __declspec( dllexport ) void EnsureManagedInitialization () { // managed code that won't be optimized away @@ -26,36 +26,34 @@ Visual Studio contains some known issues when compiling library projects with ** ## Compile with Visual C++ -Before using **/clr** on any module in your project, first compile and link your native project with Visual Studio 2010. - -The following steps, followed in order, provide the easiest path to a **/clr** compilation. It is important to compile and run your project after each of these steps. +Before you use **`/clr`** on any module in your project, first compile and link your native project with Visual Studio. -### Versions Prior to Visual Studio 2003 +The following steps, followed in order, provide the easiest path to a **`/clr`** compilation. It's important to compile and run your project after each of these steps. -If you are upgrading to Visual Studio 2010 from a version prior to Visual Studio 2003, you may see compiler errors related to the enhanced C++ standard conformance in Visual Studio 2003 +### Upgrading from earlier versions of Visual Studio -### Upgrading from Visual Studio 2003 +If you're upgrading Visual Studio from an earlier version, you may see compiler errors related to the enhanced Standard C++ conformance in Visual Studio. -Projects previous built with Visual Studio 2003 should also first be compiled without **/clr** as Visual Studio now has increased ANSI/ISO conformance and some breaking changes. The change that is likely to require the most attention is [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). Code that uses the CRT is very likely to produce deprecation warnings. These warnings can be suppressed, but migrating to the new [Security-Enhanced Versions of CRT Functions](../c-runtime-library/security-enhanced-versions-of-crt-functions.md) is preferred, as they provide better security and may reveal security issues in your code. +Projects built with earlier versions of Visual Studio should also first be compiled without **`/clr`**. Visual Studio now has increased Standard C++ conformance and some breaking changes. The changes that are likely to require the most attention are [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). Code that uses the CRT is likely to produce deprecation warnings. These warnings can be suppressed, but migrating to the new [Security-enhanced versions of CRT functions](../c-runtime-library/security-enhanced-versions-of-crt-functions.md) is preferred, as they provide better security and may reveal security issues in your code. ### Upgrading from Managed Extensions for C++ -Starting in Visual Studio 2005, code written with Managed Extensions for C++ won't compile under **/clr**. +In Visual Studio 2005 and later versions, code written with Managed Extensions for C++ won't compile under **`/clr`**. -## Convert C Code to C++ +## Convert C code to C++ -Although Visual Studio will compile C files, it is necessary to convert them to C++ for a **/clr** compilation. The actual filename doesn't have to be changed; you can use **/Tp** (see [/Tc, /Tp, /TC, /TP (Specify Source File Type)](../build/reference/tc-tp-tc-tp-specify-source-file-type.md).) Note that although C++ source code files are required for **/clr**, it is not necessary to re-factor your code to use object-oriented paradigms. +Although Visual Studio will compile C files, it's necessary to convert them to C++ for a **`/clr`** compilation. The actual filename doesn't have to be changed; you can use **`/Tp`** (see [`/Tc`, `/Tp`, `/TC`, `/TP` (Specify source file type)](../build/reference/tc-tp-tc-tp-specify-source-file-type.md).) Although C++ source code files are required for **`/clr`**, it isn't necessary to refactor your code to use object-oriented paradigms. -C code is very likely to require changes when compiled as a C++ file. The C++ type-safety rules are strict, so type conversions must be made explicit with casts. For example, malloc returns a void pointer, but can be assigned to a pointer to any type in C with a cast: +C code is likely to require changes when compiled as a C++ file. The C++ type-safety rules are strict, so type conversions must be made explicit with casts. For example, malloc returns a void pointer, but can be assigned to a pointer to any type in C with a cast: -``` +```cpp int* a = malloc(sizeof(int)); // C code int* b = (int*)malloc(sizeof(int)); // C++ equivalent ``` -Function pointers are also strictly type-safe in C++, so the following C code requires modification. In C++ it's best to create a **`typedef`** that defines the function pointer type, and then use that type to cast function pointers: +Function pointers are also strictly type-safe in C++, so the following C code requires modification. In C++, it's best to create a **`typedef`** that defines the function pointer type, and then use that type to cast function pointers: -``` +```cpp NewFunc1 = GetProcAddress( hLib, "Func1" ); // C code typedef int(*MYPROC)(int); // C++ equivalent NewFunc2 = (MYPROC)GetProcAddress( hLib, "Func2" ); @@ -63,87 +61,87 @@ NewFunc2 = (MYPROC)GetProcAddress( hLib, "Func2" ); C++ also requires that functions either be prototyped or fully defined before they can be referenced or invoked. -Identifiers used in C code that happen to be keywords in C++ (such as **`virtual`**, **`new`**, **`delete`**, **`bool`**, **`true`**, **`false`**, etc.) must be renamed. This can generally be done with simple search-and-replace operations. +Identifiers used in C code that happen to be keywords in C++ (such as **`virtual`**, **`new`**, **`delete`**, **`bool`**, **`true`**, **`false`**, etc.) must be renamed. This change can generally be done with simple search-and-replace operations. -``` +```cpp COMObj1->lpVtbl->Method(COMObj, args); // C code COMObj2->Method(args); // C++ equivalent ``` -## Reconfigure Project Settings +## Reconfigure project settings -After your project compiles and runs in Visual Studio 2010 you should create new project configurations for **/clr** rather than modifying the default configurations. **/clr** is incompatible with some compiler options and creating separate configurations lets you build your project as native or managed. When **/clr** is selected in the property pages dialog box, project settings not compatible with **/clr** are disabled (and disabled options are not automatically restored if **/clr** is subsequently unselected). +After your project compiles and runs in Visual Studio, you should create new project configurations for **`/clr`** rather than modifying the default configurations. **`/clr`** is incompatible with some compiler options. Creating separate configurations lets you build your project as native or managed. When **`/clr`** is selected in the property pages dialog box, project settings not compatible with **`/clr`** are disabled. (Disabled options aren't automatically restored if **`/clr`** is later unselected.) -### Create New Project Configurations +### Create new project configurations -You can use **Copy Settings From** option in the **New Project Configuration Dialog Box** (**Build** > **Configuration Manager** > **Active Solution Configuration** > **New**) to create a project configuration based on your existing project settings. Do this once for the Debug configuration and once for Release configuration. Subsequent changes can then be applied to the **/clr** -specific configurations only, leaving the original project configurations intact. +You can use **Copy Settings From** option in the **New Project Configuration Dialog Box** (**Build** > **Configuration Manager** > **Active Solution Configuration** > **New**) to create a project configuration based on your existing project settings. Create a copy of your configuration once for the Debug configuration, and once for Release configuration. Subsequent changes can then be applied to the **`/clr`**-specific configurations only, leaving the original project configurations intact. Projects that use custom build rules may require extra attention. -This step has different implications for projects that use makefiles. In this case a separate build-target can be configured, or version specific to **/clr** compilation can be created from a copy of the original. +This step has different implications for projects that use makefiles. In this case, a separate build-target can be configured, or a version specific to **`/clr`** compilation can be created from a copy of the original. -### Change Project Settings +### Change project settings -**/clr** can be selected in the development environment by following the instructions in [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md). As mentioned previously, this step will automatically disable conflicting project settings. +**`/clr`** can be selected in the development environment by following the instructions in [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md). As mentioned previously, this step will automatically disable conflicting project settings. > [!NOTE] -> When upgrading a managed library or web service project from Visual Studio 2003, the **/Zl** compiler option will added to the **Command Line** property page. This will cause LNK2001. Remove **/Zl** from the **Command Line** property page to resolve. See [/Zl (Omit Default Library Name)](../build/reference/zl-omit-default-library-name.md) and [Set compiler and build properties](../build/working-with-project-properties.md) for more information. Or, add msvcrt.lib and msvcmrt.lib to the linker's **Additional Dependencies** property. +> When upgrading a managed library or web service project from Visual Studio 2003, the **`/Zl`** compiler option is added to the **Command Line** property page. This causes LNK2001 errors. Remove **`/Zl`** from the **Command Line** property page to resolve the errors. For more information, see [`/Zl` (Omit default library name)](../build/reference/zl-omit-default-library-name.md) and [Set compiler and build properties](../build/working-with-project-properties.md). -For projects built with makefiles, incompatible compiler options must be disabled manually once **/clr** is added. See /[/clr Restrictions](../build/reference/clr-restrictions.md) for information on compiler options that are not compatible with **/clr**. +For projects built with makefiles, incompatible compiler options must be disabled manually once **`/clr`** is added. For information on compiler options that aren't compatible with **`/clr`**, see [`/clr` restrictions](../build/reference/clr-restrictions.md). -### Precompiled Headers +### Precompiled headers -Precompiled headers are supported under **/clr**. However, if you only compile some of your CPP files with **/clr** (compiling the rest as native) some changes will be required because precompiled headers generated with **/clr** are not compatible with those generated without **/clr**. This incompatibility is due to the fact that **/clr** generates and requires metadata. Modules compiled **/clr** can therefore not use precompiled headers that don't include metadata, and non **/clr** modules can't use precompiled header files that do contain meta data. +Precompiled headers are supported under **`/clr`**. However, if you only compile some of your CPP files with **`/clr`** (compiling the rest as native), some changes are required. Precompiled headers generated with **`/clr`** aren't compatible with precompiled headers generated without **`/clr`**, because **`/clr`** generates and requires metadata. Modules compiled with **`/clr`** can't use precompiled headers that don't include metadata, and non-**`/clr`** modules can't use precompiled header files that do contain metadata. -The easiest way to compile a project where some modules are compiled **/clr** is to disable precompiled headers entirely. (In the project Property Pages dialog, open the C/C++ node, and select Precompiled Headers. Then change the Create/Use Precompiled Headers property to "Not Using Precompiled Headers".) +The easiest way to compile a project where some modules are compiled with **`/clr`** is to disable precompiled headers entirely. (In the project Property Pages dialog, open the **C/C++** node, and select **Precompiled Headers**. Then change the **Create/Use Precompiled Headers** property to "Not Using Precompiled Headers".) -However, particularly for large projects, precompiled headers provide much better compilation speed, so disabling this feature is not desirable. In this case it's best to configure the **/clr** and non **/clr** files to use separate precompiled headers. This can be done in one step by multi-selecting the modules to be compiled **/clr** using **Solution Explorer**, right-clicking on the group, and selecting Properties. Then change both the Create/Use PCH Through File and Precompiled Header File properties to use a different header file name and PCH file respectively. +However, particularly for large projects, precompiled headers provide much better compilation speed, so disabling this feature isn't desirable. In this case, it's best to configure the **`/clr`** and non-**`/clr`** files to use separate precompiled headers. You can configure them in one step: Multi-select the modules to compile with **`/clr`** by using **Solution Explorer**. Right-click on the group, and select **Properties**. Then, change both the **Create/Use PCH Through File** and **Precompiled Header File** properties to use a different header file name and PCH file, respectively. -## Fixing Errors +## Fix errors -Compiling with **/clr** may result in compiler, linker or runtime errors. This section discusses the most common problems. +Compiling your code with **`/clr`** may result in compiler, linker or runtime errors. This section discusses the most common problems. -### Metadata Merge +### Metadata merge -Differing versions of data types can cause the linker to fail because the metadata generated for the two types doesn't match. (This is usually caused when members of a type are conditionally defined, but the conditions are not the same for all CPP files that use the type.) In this case the linker fails, reporting only the symbol name and the name of the second OBJ file where the type was defined. It is often useful to rotate the order that OBJ files are sent to the linker to discover the location of the other version of the data type. +Differing versions of data types can cause the linker to fail because the metadata generated for the two types doesn't match. (Errors occur when you conditionally define members of a type, but the conditions aren't the same for all CPP files that use the type.) In this case, the linker fails, reporting only the symbol name and the name of the second OBJ file where the type was defined. You may find it's useful to rotate the order that OBJ files are sent to the linker, to discover the location of the other version of the data type. -### Loader Lock Deadlock +### Loader lock deadlock The "loader lock deadlock" can occur, but is deterministic and is detected and reported at runtime. See [Initialization of Mixed Assemblies](../dotnet/initialization-of-mixed-assemblies.md) for detailed background, guidance, and solutions. -### Data Exports +### Data exports -Exporting DLL data is error-prone, and not recommended. This is because the data section of a DLL is not guaranteed to be initialized until some managed portion of the DLL has been executed. Reference metadata with [#using Directive](../preprocessor/hash-using-directive-cpp.md). +Exporting DLL data is error-prone, and not recommended in **`/clr`** code. It's because initialization of the data section of a DLL isn't guaranteed until some managed portion of the DLL is executed. Reference metadata with [`#using` directives](../preprocessor/hash-using-directive-cpp.md). -### Type Visibility +### Type visibility -Native types are private by default. This can result in a native type not being visible outside the DLL. Resolve this error by adding **`public`** to these types. +Native types are **`private`** by default. A **`private`** native type isn't visible outside the DLL. Resolve this error by adding **`public`** to these types. -### Floating Point and Alignment Issues +### Floating point and alignment issues -`__controlfp` is not supported on the common language runtime (see [_control87, _controlfp, \__control87_2](../c-runtime-library/reference/control87-controlfp-control87-2.md) for more information). The CLR will also not respect [align](../cpp/align-cpp.md). +`__controlfp` isn't supported in the common language runtime. (For more information, see [`_control87`, `_controlfp`, `__control87_2`](../c-runtime-library/reference/control87-controlfp-control87-2.md).) The CLR also doesn't respect [`align`](../cpp/align-cpp.md). -### COM Initialization +### COM initialization -The Common Language Runtime initializes COM automatically when a module is initialized (when COM is initialized automatically it’s done so as MTA). As a result, explicitly initializing COM yields return codes indicating that COM is already initialized. Attempting to explicitly initialize COM with one threading model when the CLR has already initialized COM to another threading model can cause your application to fail. +The Common Language Runtime initializes COM automatically when a module is initialized (when COM is initialized automatically it's done so as MTA). As a result, explicitly initializing COM yields return codes indicating that COM is already initialized. Attempting to explicitly initialize COM with one threading model when the CLR has already initialized COM to another threading model can cause your application to fail. -The common language runtime starts COM as MTA by default; use [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](../build/reference/clrthreadattribute-set-clr-thread-attribute.md) to modify this. +The common language runtime starts COM as MTA by default; use [`/CLRTHREADATTRIBUTE` (Set CLR thread attribute)](../build/reference/clrthreadattribute-set-clr-thread-attribute.md) to modify the COM model. -### Performance Issues +### Performance issues -You may see decreased performance when native C++ methods generated to MSIL are called indirectly (virtual function calls or using function pointers). To learn more about this, see [Double Thunking](../dotnet/double-thunking-cpp.md). +You may see decreased performance when native C++ methods generated to MSIL are called indirectly (through virtual function calls or by using function pointers). To learn more, see [Double Thunking](../dotnet/double-thunking-cpp.md). -When moving from native to MSIL, you will notice an increase in the size of your working set. This is because the common language runtime provides many features to ensure that programs run correctly. If your **/clr** application is not running correctly, you may want to enable C4793 (off by default), see [Compiler Warning (level 1 and 3) C4793](../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md) for more information. +When you move from native to MSIL, you'll notice an increase in the size of your working set. This increase happens because the common language runtime provides many features to ensure that programs run correctly. If your **`/clr`** application isn't running correctly, you may want to enable off-by-default [Compiler Warning (level 1 and 3) C4793](../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md). -### Program Crashes on Shutdown +### Program crashes on shutdown -In some cases, the CLR can shutdown before your managed code is finished running. Using `std::set_terminate` and `SIGTERM` can cause this. See [signal Constants](../c-runtime-library/signal-constants.md) and [set_terminate](../c-runtime-library/abnormal-termination.md) for more information. +In some cases, the CLR can shut down before your managed code is finished running. Use of `std::set_terminate` and `SIGTERM` can cause the shutdown. For more information, see [`signal` constants](../c-runtime-library/signal-constants.md) and [`set_terminate`](../c-runtime-library/abnormal-termination.md). -## Using New Visual C++ Features +## Using new Visual C++ features -After your application compiles, links, and runs, you can begin using .NET features in any module compiled with **/clr**. For more information, see [Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md). +After your application compiles, links, and runs, you can begin using .NET features in any module compiled with **`/clr`**. For more information, see [Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md). -For information on .NET programming in Visual C++ see: +For more information on .NET programming in Visual C++, see: - [.NET Programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md) diff --git a/docs/dotnet/how-to-use-arrays-in-cpp-cli.md b/docs/dotnet/how-to-use-arrays-in-cpp-cli.md index 14f17299db..6bdeba25b0 100644 --- a/docs/dotnet/how-to-use-arrays-in-cpp-cli.md +++ b/docs/dotnet/how-to-use-arrays-in-cpp-cli.md @@ -221,7 +221,7 @@ public: }; int main() { - // Aggregate initialize a multidimension managed array. + // Aggregate initialize a multidimensional managed array. array^ gc1 = gcnew array{ {"one", "two"}, {"three", "four"} }; array^ gc2 = { {"one", "two"}, {"three", "four"} }; diff --git a/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md b/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md index 3a9ba0614c..a63bc2182f 100644 --- a/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md +++ b/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md @@ -286,9 +286,9 @@ Boxed new copy V: 1 Original V: 4, Reference to handle of originally boxed V: 1 ``` -## Template functions that take native, value, or reference parameters +## Function templates that take native, value, or reference parameters -By using a tracking reference in the signature of a template function, you ensure that the function can be called by a parameter whose type is native, CLR value, or CLR reference. +By using a tracking reference in the signature of a function template, you ensure that the function can be called by a parameter whose type is native, CLR value, or CLR reference. ```cpp // tracking_reference_template.cpp @@ -297,7 +297,7 @@ using namespace System; class Temp { public: - // template functions + // function templates template static int f1(T% tt) { // works for object in any location Console::WriteLine("T %"); diff --git a/docs/dotnet/list-stl-clr.md b/docs/dotnet/list-stl-clr.md index 7069b4797c..fff82c19fd 100644 --- a/docs/dotnet/list-stl-clr.md +++ b/docs/dotnet/list-stl-clr.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: list (STL/CLR)" title: "list (STL/CLR)" +description: "Learn more about: list (STL/CLR)" ms.date: "11/04/2016" ms.topic: "reference" f1_keywords: ["cliext::list", "cliext::list::assign", "cliext::list::back", "cliext::list::back_item", "cliext::list::begin", "cliext::list::clear", "cliext::list::const_iterator", "cliext::list::const_reference", "cliext::list::const_reverse_iterator", "cliext::list::difference_type", "cliext::list::empty", "cliext::list::end", "cliext::list::erase", "cliext::list::front", "cliext::list::front_item", "cliext::list::generic_container", "cliext::list::generic_iterator", "cliext::list::generic_reverse_iterator", "cliext::list::generic_value", "cliext::list::insert", "cliext::list::iterator", "cliext::list::list", "cliext::list::merge", "cliext::list::operator=", "cliext::list::pop_back", "cliext::list::pop_front", "cliext::list::push_back", "cliext::list::push_front", "cliext::list::rbegin", "cliext::list::reference", "cliext::list::remove", "cliext::list::remove_if", "cliext::list::rend", "cliext::list::resize", "cliext::list::reverse", "cliext::list::reverse_iterator", "cliext::list::size", "cliext::list::size_type", "cliext::list::sort", "cliext::list::splice", "cliext::list::swap", "cliext::list::to_array", "cliext::list::unique", "cliext::list::value_type", "cliext::operator!=(list)", "cliext::operator<(list)", "cliext::operator<=(list)", "cliext::operator==(list)", "cliext::operator>(list)", "cliext::operator>=(list)"] helpviewer_keywords: [" header [STL/CLR]", "list class [STL/CLR]", " header [STL/CLR]", "assign member [STL/CLR]", "assign member [STL/CLR]", "back member [STL/CLR]", "back_item member [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "erase member [STL/CLR]", "front member [STL/CLR]", "front_item member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "list member [STL/CLR]", "merge member [STL/CLR]", "operator= member [STL/CLR]", "pop_back member [STL/CLR]", "pop_front member [STL/CLR]", "push_back member [STL/CLR]", "push_front member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "remove member [STL/CLR]", "remove_if member [STL/CLR]", "rend member [STL/CLR]", "resize member [STL/CLR]", "reverse member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "sort member [STL/CLR]", "splice member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "unique member [STL/CLR]", "value_type member [STL/CLR]", "operator!=(list) member [STL/CLR]", "operator<(list) member [STL/CLR]", "operator<=(list) member [STL/CLR]", "operator==(list) member [STL/CLR]", "operator>(list) member [STL/CLR]", "operator>=(list) member [STL/CLR]"] -ms.assetid: a70c45c8-a257-4f6b-8434-b27ff6685bac --- # list (STL/CLR) @@ -510,7 +509,7 @@ a b c ## list::const_reverse_iterator (STL/CLR) -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax diff --git a/docs/dotnet/managed-types-cpp-cli.md b/docs/dotnet/managed-types-cpp-cli.md index 6b6b86a35f..44899b6372 100644 --- a/docs/dotnet/managed-types-cpp-cli.md +++ b/docs/dotnet/managed-types-cpp-cli.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Managed Types (C++/CLI)" title: "Managed Types (C++/CLI)" -ms.date: "11/04/2016" +ms.date: 06/29/2022 helpviewer_keywords: ["data types [C++], managed", "managed data types [C++]", ".NET Framework [C++], managed types", "data types [C++], .NET feature access", "main function, in managed applications", "managed code, main() function", ".NET Framework [C++], C++ equivalents", "__nogc type declarations", "__value keyword, issues when nesting", "equality, testing for", "versioning, diagnosing conflicts", "versioning", "exceptions, diagnosing odd behavior", "compatibility, between assemblies"] ms.assetid: 679b8ed3-d966-4a0c-b627-2a3f3ec96b74 --- @@ -11,7 +11,7 @@ Visual C++ allows access to .NET features through managed types, which provide s ## Managed Types and the main Function -When writing an application using **`/clr`**, the arguments of the **main()** function cannot be of a managed type. +When you write an application using **`/clr`**, the arguments of the **`main()`** function can't be of a managed type. An example of a proper signature is: @@ -25,21 +25,21 @@ int main(int, char*[], char*[]) {} The following table shows the keywords for built-in Visual C++ types, which are aliases of predefined types in the **System** namespace. -|Visual C++ type|.NET Framework type| -|-----------------------|-------------------------| -|**`void`**|| -|**`bool`**|| -|**`signed char`** || -|**`unsigned char`**|| -|**`wchar_t`**|| -|**`short`** and **`signed short`**|| -|**`unsigned short`**|| -|**`int`**, **`signed int`**, **`long`**, and **`signed long`**|| -|**`unsigned int`** and **`unsigned long`**|| -|**`__int64`** and **`signed __int64`**|| -|**`unsigned __int64`**|| -|**`float`**|| -|**`double`** and **`long double`**|| +| Visual C++ type | .NET Framework type | +|--|--| +| **`void`** | | +| **`bool`** | | +| **`signed char`** | | +| **`unsigned char`** | | +| **`wchar_t`** | | +| **`short`** and **`signed short`** | | +| **`unsigned short`** | | +| **`int`**, **`signed int`**, **`long`**, and **`signed long`** | | +| **`unsigned int`** and **`unsigned long`** | | +| **`__int64`** and **`signed __int64`** | | +| **`unsigned __int64`** | | +| **`float`** | | +| **`double`** and **`long double`** | | For more information about the compiler option to default to **`signed char`** or **`unsigned char`**, see [`/J` (Default **`char`** type is **`unsigned`**)](../build/reference/j-default-char-type-is-unsigned.md). @@ -104,9 +104,9 @@ S.i = 11 ### Comments -However, if you add another member to `struct S` in nested_value_types.cpp, (for example, `double d;`) and recompile the component without recompiling the client, the result is an unhandled exception (of type ). +However, if you add another member to `struct S` in `nested_value_types.cpp` (for example, `double d;`) and recompile the component without also recompiling the client, the result is an unhandled exception (of type ). -## How to: Test for Equality +## How to test for equality In the following sample, a test for equality that uses Managed Extensions for C++ is based on what the handles refer to. @@ -124,38 +124,37 @@ bool Test1() { } ``` -The IL for this program shows that the return value is implemented by using a call to op_Equality. +The IL for this program shows that the return value is implemented by using a call to `op_Equality`. ```MSIL -IL_0012: call bool [mscorlib]System.String::op_Equality(string, - string) +IL_0012: call bool [mscorlib]System.String::op_Equality(string, string) ``` -## How to: Diagnose and Fix Assembly Compatibility Problems +## How to diagnose and fix assembly compatibility problems -This topic explains what can happen when the version of an assembly referenced at compile time doesn't match the version of the assembly referenced at runtime, and how to avoid the problem. +When the version of an assembly referenced at compile time doesn't match the version of the assembly referenced at runtime, various problems may occur. When an assembly is compiled, other assemblies may be referenced with the `#using` syntax. During the compilation, these assemblies are accessed by the compiler. Information from these assemblies is used to make optimization decisions. -However, if the referenced assembly is changed and recompiled, and you do not recompile the referencing assembly that is dependent on it, the assemblies might not still be compatible. Optimization decisions that were valid at first might not be correct with respect to the new assembly version. Various runtime errors might occur due to these incompatibilities. There is no specific exception that will be produced in such cases. The way the failure is reported at runtime depends on the nature of the code change that caused the problem. +However, if the referenced assembly is changed and recompiled, also recompile the referencing assembly that's dependent on it. Otherwise, the assemblies might become incompatible. Optimization decisions that were valid at first might not be correct for the new assembly version. Various runtime errors might occur because of these incompatibilities. There's no specific exception produced in such cases. The way the failure is reported at runtime depends on the nature of the code change that caused the problem. -These errors should not be a problem in your final production code as long as the entire application is rebuilt for the released version of your product. Assemblies that are released to the public should be marked with an official version number, which will ensure that these problems are avoided. For more information, see [Assembly Versioning](/dotnet/framework/app-domains/assembly-versioning). +These errors shouldn't be a problem in your final production code as long as the entire application is rebuilt for the released version of your product. Assemblies that are released to the public should be marked with an official version number, which will ensure that these problems are avoided. For more information, see [Assembly Versioning](/dotnet/framework/app-domains/assembly-versioning). -### Diagnosing and fixing an incompatibility error +### To diagnose and fix an incompatibility error -1. If you encounter runtime exceptions or other error conditions that occur in code that references another assembly, and have no other identified cause, you may be dealing with an out of date assembly. +You may encounter runtime exceptions or other error conditions in code that references another assembly. If you can't identify another cause, the problem may be an out of date assembly. 1. First, isolate and reproduce the exception or other error condition. A problem that occurs due to an outdated exception should be reproducible. 1. Check the timestamp of any assemblies referenced in your application. -1. If the timestamps of any referenced assemblies are later than the timestamp of your application's last compilation, then your application is out of date. If this occurs, recompile your application with the most recent assembly, and make any code changes required. +1. If the timestamps of any referenced assemblies are later than the timestamp of your application's last compilation, then your application is out of date. If it's out of date, recompile your application with the most recent assemblies, and edit your code if necessary. -1. Rerun the application, perform the steps that reproduce the problem, and verify that the exception does not occur. +1. Rerun the application, perform the steps that reproduce the problem, and verify that the exception doesn't occur. ### Example -The following program illustrates the problem by reducing the accessibility of a method, and trying to access that method in another assembly without recompiling. Try compiling `changeaccess.cpp` first. This is the referenced assembly which will change. Then compile `referencing.cpp`. The compilation succeeds. Now, reduce the accessibility of the called method. Recompile `changeaccess.cpp` with the flag `/DCHANGE_ACCESS`. This makes the method protected, rather than private, so it can longer be called legally. Without recompiling `referencing.exe`, rerun the application. An exception will result. +The following program illustrates the problem: it first reduces the accessibility of a method, and then tries to access that method in another assembly without recompiling. Compile `changeaccess.cpp` first. It's the referenced assembly that will change. Then compile `referencing.cpp`. It should successfully compile. Next, reduce the accessibility of the called method. Recompile `changeaccess.cpp` with the compiler option `/DCHANGE_ACCESS`. It makes the `access_me` method `protected`, rather than `public`, so it can't be called from outside `Test` or its derivatives. Without recompiling `referencing.exe`, rerun the application. A occurs. ```cpp // changeaccess.cpp @@ -178,6 +177,8 @@ public: }; ``` +Here's the source for the referencing assembly: + ```cpp // referencing.cpp // compile with: /clr:safe @@ -208,7 +209,7 @@ int main() { ## See also -[.NET Programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md)
-[Interoperability with Other .NET Languages (C++/CLI)](../dotnet/interoperability-with-other-dotnet-languages-cpp-cli.md)
-[Managed Types (C++/CLI)](../dotnet/managed-types-cpp-cli.md)
-[#using Directive](../preprocessor/hash-using-directive-cpp.md) +[.NET programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md)\ +[Interoperability with other .NET languages (C++/CLI)](../dotnet/interoperability-with-other-dotnet-languages-cpp-cli.md)\ +[Managed types (C++/CLI)](../dotnet/managed-types-cpp-cli.md)\ +[`#using` directive](../preprocessor/hash-using-directive-cpp.md) diff --git a/docs/dotnet/map-stl-clr.md b/docs/dotnet/map-stl-clr.md index ca5931c244..8ed6171113 100644 --- a/docs/dotnet/map-stl-clr.md +++ b/docs/dotnet/map-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::map", "cliext::map::begin", "cliext::map::clear", "cliext helpviewer_keywords: [" header [STL/CLR]", "map class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "map member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= (map) member [STL/CLR]", "operator< (map) member [STL/CLR]", "operator<= (map) member [STL/CLR]", "operator== (map) member [STL/CLR]", "operator> (map) member [STL/CLR]", "operator>= (map) member [STL/CLR]"] ms.assetid: 8b0a7764-b5e4-4175-a802-82b72eb8662a --- -# map (STL/CLR) +# `map` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `map` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -41,93 +41,93 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[map::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[map::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[map::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[map::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[map::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[map::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[map::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[map::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[map::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[map::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[map::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[map::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[map::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[map::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[map::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[map::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[map::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[map::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[map::clear (STL/CLR)](#clear)|Removes all elements.| -|[map::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[map::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[map::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[map::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[map::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[map::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[map::insert (STL/CLR)](#insert)|Adds elements.| -|[map::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[map::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[map::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[map::map (STL/CLR)](#map)|Constructs a container object.| -|[map::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[map::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[map::size (STL/CLR)](#size)|Counts the number of elements.| -|[map::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[map::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[map::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[map::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[map::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[map::operator(STL/CLR)](#op)|Maps a key to its associated mapped value.| -|[operator!= (map) (STL/CLR)](#op_neq)|Determines if a `map` object is not equal to another `map` object.| -|[operator< (map) (STL/CLR)](#op_lt)|Determines if a `map` object is less than another `map` object.| -|[operator<= (map) (STL/CLR)](#op_lteq)|Determines if a `map` object is less than or equal to another `map` object.| -|[operator== (map) (STL/CLR)](#op_eq)|Determines if a `map` object is equal to another `map` object.| -|[operator> (map) (STL/CLR)](#op_gt)|Determines if a `map` object is greater than another `map` object.| -|[operator>= (map) (STL/CLR)](#op_gteq)|Determines if a `map` object is greater than or equal to another `map` object.| +| Type definition | Description | +|---|---| +| [`map::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`map::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`map::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`map::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`map::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`map::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`map::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`map::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`map::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`map::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`map::key_type`](#key_type) | The type of an ordering key. | +| [`map::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`map::reference`](#reference) | The type of a reference to an element. | +| [`map::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`map::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`map::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`map::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`map::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`map::clear`](#clear) | Removes all elements. | +| [`map::count`](#count) | Counts elements matching a specified key. | +| [`map::empty`](#empty) | Tests whether no elements are present. | +| [`map::end`](#end) | Designates the end of the controlled sequence. | +| [`map::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`map::erase`](#erase) | Removes elements at specified positions. | +| [`map::find`](#find) | Finds an element that matches a specified key. | +| [`map::insert`](#insert) | Adds elements. | +| [`map::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`map::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`map::make_value`](#make_value) | Constructs a value object. | +| [`map::map`](#map) | Constructs a container object. | +| [`map::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`map::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`map::size`](#size) | Counts the number of elements. | +| [`map::swap`](#swap) | Swaps the contents of two containers. | +| [`map::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`map::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`map::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`map::operator=`](#op_as) | Replaces the controlled sequence. | +| [`map::operator[]`](#op) | Maps a key to its associated mapped value. | +| [`operator!=` (map)](#op_neq) | Determines if a `map` object isn't equal to another `map` object. | +| [`operator<` (map)](#op_lt) | Determines if a `map` object is less than another `map` object. | +| [`operator<=` (map)](#op_lteq) | Determines if a `map` object is less than or equal to another `map` object. | +| [`operator==` (map)](#op_eq) | Determines if a `map` object is equal to another `map` object. | +| [`operator>` (map)](#op_gt) | Determines if a `map` object is greater than another `map` object. | +| [`operator>=` (map)](#op_gteq) | Determines if a `map` object is greater than or equal to another `map` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -||Maintain group of {key, value} pairs.| -|ITree|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| | Maintain group of {key, value} pairs. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [map::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the map; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [map::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`map::key_compare`](#key_compare). You can specify the stored delegate object when you construct the map; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`map::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [map::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`map::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -137,21 +137,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map](../dotnet/map-stl-clr.md), an object of template class `map` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map](../dotnet/map-stl-clr.md), an object of template class `map` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A map supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [map::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a map iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `map` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `map` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a map element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `map` element directly given its numerical position. That requires a random-access iterator. -A map iterator stores a handle to its associated map node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A map iterator remains valid so long as its associated map node is associated with some map. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `map` iterator stores a handle to its associated `map` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `map` iterator remains valid so long as its associated `map` node is associated with some map. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## map::begin (STL/CLR) +## `map::begin` Designates the beginning of the controlled sequence. @@ -202,7 +202,7 @@ int main() *++begin() = [b 2] ``` -## map::clear (STL/CLR) +## `map::clear` Removes all elements. @@ -214,7 +214,7 @@ void clear(); ### Remarks -The member function effectively calls [map::erase (STL/CLR)](#erase)`(` [map::begin (STL/CLR)](#begin)`(),` [map::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -260,7 +260,7 @@ size() = 0 size() = 0 ``` -## map::const_iterator (STL/CLR) +## `map::const_iterator` The type of a constant iterator for the controlled sequence. @@ -302,7 +302,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::const_reference (STL/CLR) +## `map::const_reference` The type of a constant reference to an element. @@ -347,9 +347,9 @@ int main() [a 1] [b 2] [c 3] ``` -## map::const_reverse_iterator (STL/CLR) +## `map::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -389,7 +389,7 @@ int main() [c 3] [b 2] [a 1] ``` -## map::count (STL/CLR) +## `map::count` Finds the number of elements matching a specified key. @@ -401,12 +401,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -442,7 +442,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## map::difference_type (STL/CLR) +## `map::difference_type` The types of a signed distance between two elements. @@ -497,7 +497,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## map::empty (STL/CLR) +## `map::empty` Tests whether no elements are present. @@ -509,7 +509,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [map::size (STL/CLR)](#size)`() == 0`. You use it to test whether the map is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `map` is empty. ### Example @@ -549,7 +549,7 @@ size() = 0 empty() = True ``` -## map::end (STL/CLR) +## `map::end` Designates the end of the controlled sequence. @@ -561,7 +561,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -596,7 +596,7 @@ int main() } ``` -## map::equal_range (STL/CLR) +## `map::equal_range` Finds range that matches a specified key. @@ -608,12 +608,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [map::lower_bound (STL/CLR)](#lower_bound)`(key),` [map::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -657,7 +657,7 @@ equal_range(L'x') empty = True [b 2] ``` -## map::erase (STL/CLR) +## `map::erase` Removes elements at specified positions. @@ -671,25 +671,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [map::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -750,7 +750,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## map::find (STL/CLR) +## `map::find` Finds an element that matches a specified key. @@ -762,12 +762,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [map::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -809,7 +809,7 @@ find b = [b 2] find C = False ``` -## map::generic_container (STL/CLR) +## `map::generic_container` The type of the generic interface for the container. @@ -873,7 +873,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## map::generic_iterator (STL/CLR) +## `map::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -930,7 +930,7 @@ int main() [a 1] ``` -## map::generic_reverse_iterator (STL/CLR) +## `map::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -986,7 +986,7 @@ int main() [c 3] ``` -## map::generic_value (STL/CLR) +## `map::generic_value` The type of an element for use with the generic interface for the container. @@ -1040,7 +1040,7 @@ int main() [a 1] ``` -## map::insert (STL/CLR) +## `map::insert` Adds elements. @@ -1056,34 +1056,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1160,7 +1160,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [c 3] [x 24] [y 25] ``` -## map::iterator (STL/CLR) +## `map::iterator` The type of an iterator for the controlled sequence. @@ -1202,7 +1202,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::key_comp (STL/CLR) +## `map::key_comp` Copies the ordering delegate for two keys. @@ -1261,7 +1261,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## map::key_compare (STL/CLR) +## `map::key_compare` The ordering delegate for two keys. @@ -1321,7 +1321,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## map::key_type (STL/CLR) +## `map::key_type` The type of an ordering key. @@ -1333,7 +1333,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1366,7 +1366,7 @@ int main() a b c ``` -## map::lower_bound (STL/CLR) +## `map::lower_bound` Finds beginning of range that matches a specified key. @@ -1378,12 +1378,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1425,7 +1425,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## map::make_value (STL/CLR) +## `map::make_value` Constructs a value object. @@ -1437,15 +1437,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1474,7 +1474,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::map (STL/CLR) +## `map::map` Constructs a container object. @@ -1497,16 +1497,16 @@ map(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1521,19 +1521,19 @@ The constructor: `explicit map(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `map(map% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the map object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `map` object *`right`*, with the default ordering predicate. The constructor: `map(map^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the map object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `map` object *`right`*, with the default ordering predicate. The constructor: @@ -1545,19 +1545,19 @@ The constructor: `template map(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `map(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1647,7 +1647,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## map::mapped_type (STL/CLR) +## `map::mapped_type` The type of a mapped value associated with each key. @@ -1659,7 +1659,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1692,7 +1692,7 @@ int main() 1 2 3 ``` -## map::operator= (STL/CLR) +## `map::operator=` Replaces the controlled sequence. @@ -1704,12 +1704,12 @@ map% operator=(map% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1747,7 +1747,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::operator(STL/CLR) +## `map::operator[]` Maps a key to its associated mapped value. @@ -1759,12 +1759,12 @@ mapped_type operator[](key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member functions endeavors to find an element with equivalent ordering to *key*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. +The member functions endeavors to find an element with equivalent ordering to *`key`*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. ### Example @@ -1814,7 +1814,7 @@ c1[b] = 2 [A 10] [a 1] [b 2] [c 13] ``` -## map::rbegin (STL/CLR) +## `map::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1865,7 +1865,7 @@ int main() *++rbegin() = [b 2] ``` -## map::reference (STL/CLR) +## `map::reference` The type of a reference to an element. @@ -1910,7 +1910,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::rend (STL/CLR) +## `map::rend` Designates the end of the reversed controlled sequence. @@ -1963,7 +1963,7 @@ int main() *--rend() = [a 1] ``` -## map::reverse_iterator (STL/CLR) +## `map::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2005,7 +2005,7 @@ int main() [c 3] [b 2] [a 1] ``` -## map::size (STL/CLR) +## `map::size` Counts the number of elements. @@ -2017,7 +2017,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [map::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -2057,9 +2057,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## map::size_type (STL/CLR) +## `map::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2105,7 +2105,7 @@ int main() end()-begin() = 3 ``` -## map::swap (STL/CLR) +## `map::swap` Swaps the contents of two containers. @@ -2117,12 +2117,12 @@ void swap(map% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2173,7 +2173,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::to_array (STL/CLR) +## `map::to_array` Copies the controlled sequence to a new array. @@ -2223,7 +2223,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::upper_bound (STL/CLR) +## `map::upper_bound` Finds end of range that matches a specified key. @@ -2235,12 +2235,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2282,7 +2282,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## map::value_comp (STL/CLR) +## `map::value_comp` Copies the ordering delegate for two element values. @@ -2329,7 +2329,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## map::value_compare (STL/CLR) +## `map::value_compare` The ordering delegate for two element values. @@ -2377,7 +2377,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## map::value_type (STL/CLR) +## `map::value_type` The type of an element. @@ -2436,15 +2436,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two maps are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two maps are compared element by element. ### Example @@ -2492,7 +2492,7 @@ int main() [a b c] != [a b d] is True ``` -## `operator<` (map) (STL/CLR) +## `operator<` (map) List less than comparison. @@ -2507,15 +2507,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two maps are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. Use this operator to test whether *`left`* is ordered before *`right`* when the two maps are compared element by element. ### Example @@ -2563,7 +2563,7 @@ int main() [a b c] < [a b d] is True ``` -## `operator<=` (map) (STL/CLR) +## `operator<=` (map) List less than or equal comparison. @@ -2578,15 +2578,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two maps are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two maps are compared element by element. ### Example @@ -2634,7 +2634,7 @@ int main() [a b d] <= [a b c] is False ``` -## operator== (map) (STL/CLR) +## `operator==` (map) List equal comparison. @@ -2649,15 +2649,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two maps are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two maps are compared element by element. ### Example @@ -2705,7 +2705,7 @@ int main() [a b c] == [a b d] is False ``` -## `operator>` (map) (STL/CLR) +## `operator>` (map) List greater than comparison. @@ -2720,15 +2720,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two maps are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two maps are compared element by element. ### Example @@ -2776,7 +2776,7 @@ int main() [a b d] > [a b c] is True ``` -## `operator>=` (map) (STL/CLR) +## `operator>=` (map) List greater than or equal comparison. @@ -2791,15 +2791,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left` `<` `right)`. You use it to test whether *left* is not ordered before *right* when the two maps are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two maps are compared element by element. ### Example diff --git a/docs/dotnet/multimap-stl-clr.md b/docs/dotnet/multimap-stl-clr.md index c339792122..5579077cd3 100644 --- a/docs/dotnet/multimap-stl-clr.md +++ b/docs/dotnet/multimap-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::multimap", "cliext::multimap::begin", "cliext::multimap:: helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "multimap class [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "multimap member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]"] ms.assetid: 3dfe329d-a078-462a-b050-7999ce6110ad --- -# multimap (STL/CLR) +# `multimap` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `multimap` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -40,91 +40,91 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[multimap::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[multimap::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[multimap::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[multimap::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[multimap::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[multimap::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[multimap::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[multimap::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[multimap::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[multimap::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[multimap::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[multimap::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[multimap::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[multimap::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[multimap::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[multimap::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[multimap::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[multimap::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[multimap::clear (STL/CLR)](#clear)|Removes all elements.| -|[multimap::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[multimap::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[multimap::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[multimap::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[multimap::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[multimap::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[multimap::insert (STL/CLR)](#insert)|Adds elements.| -|[multimap::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[multimap::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[multimap::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[multimap::multimap (STL/CLR)](#multimap)|Constructs a container object.| -|[multimap::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[multimap::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[multimap::size (STL/CLR)](#size)|Counts the number of elements.| -|[multimap::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[multimap::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[multimap::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[multimap::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[multimap::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (multimap) (STL/CLR)](#op_neq)|Determines if a `multimap` object is not equal to another `multimap` object.| -|[operator< (multimap) (STL/CLR)](#op_lt)|Determines if a `multimap` object is less than another `multimap` object.| -|[operator<= (multimap) (STL/CLR)](#op_lteq)|Determines if a `multimap` object is less than or equal to another `multimap` object.| -|[operator== (multimap) (STL/CLR)](#op_eq)|Determines if a `multimap` object is equal to another `multimap` object.| -|[operator> (multimap) (STL/CLR)](#op_gt)|Determines if a `multimap` object is greater than another `multimap` object.| -|[operator>= (multimap) (STL/CLR)](#op_gteq)|Determines if a `multimap` object is greater than or equal to another `multimap` object.| +| Type definition | Description | +|---|---| +| [`multimap::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`multimap::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`multimap::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`multimap::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`multimap::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`multimap::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`multimap::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`multimap::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`multimap::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`multimap::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`multimap::key_type`](#key_type) | The type of an ordering key. | +| [`multimap::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`multimap::reference`](#reference) | The type of a reference to an element. | +| [`multimap::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`multimap::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`multimap::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`multimap::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`multimap::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`multimap::clear`](#clear) | Removes all elements. | +| [`multimap::count`](#count) | Counts elements matching a specified key. | +| [`multimap::empty`](#empty) | Tests whether no elements are present. | +| [`multimap::end`](#end) | Designates the end of the controlled sequence. | +| [`multimap::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`multimap::erase`](#erase) | Removes elements at specified positions. | +| [`multimap::find`](#find) | Finds an element that matches a specified key. | +| [`multimap::insert`](#insert) | Adds elements. | +| [`multimap::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`multimap::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`multimap::make_value`](#make_value) | Constructs a value object. | +| [`multimap::multimap`](#multimap) | Constructs a container object. | +| [`multimap::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`multimap::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`multimap::size`](#size) | Counts the number of elements. | +| [`multimap::swap`](#swap) | Swaps the contents of two containers. | +| [`multimap::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`multimap::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`multimap::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`multimap::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (multimap)](#op_neq) | Determines if a `multimap` object isn't equal to another `multimap` object. | +| [`operator<` (multimap)](#op_lt) | Determines if a `multimap` object is less than another `multimap` object. | +| [`operator<=` (multimap)](#op_lteq) | Determines if a `multimap` object is less than or equal to another `multimap` object. | +| [`operator==` (multimap)](#op_eq) | Determines if a `multimap` object is equal to another `multimap` object. | +| [`operator>` (multimap)](#op_gt) | Determines if a `multimap` object is greater than another `multimap` object. | +| [`operator>=` (multimap)](#op_gteq) | Determines if a `multimap` object is greater than or equal to another `multimap` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [multimap::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the multimap; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [multimap::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`multimap::key_compare`](#key_compare). You can specify the stored delegate object when you construct the multimap; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`multimap::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [multimap::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`multimap::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -134,21 +134,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map (STL/CLR)](../dotnet/map-stl-clr.md), an object of template class `multimap` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map (STL/CLR)](../dotnet/map-stl-clr.md), an object of template class `multimap` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A multimap supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [multimap::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a multimap iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `multimap` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `multimap` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a multimap element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `multimap` element directly given its numerical position. That requires a random-access iterator. -A multimap iterator stores a handle to its associated multimap node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A multimap iterator remains valid so long as its associated multimap node is associated with some multimap. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `multimap` iterator stores a handle to its associated `multimap` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `multimap` iterator remains valid so long as its associated `multimap` node is associated with some multimap. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## multimap::begin (STL/CLR) +## `multimap::begin` Designates the beginning of the controlled sequence. @@ -199,7 +199,7 @@ int main() *++begin() = [b 2] ``` -## multimap::clear (STL/CLR) +## `multimap::clear` Removes all elements. @@ -211,7 +211,7 @@ void clear(); ### Remarks -The member function effectively calls [multimap::erase (STL/CLR)](#erase)`(` [multimap::begin (STL/CLR)](#begin)`(),` [multimap::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -257,7 +257,7 @@ size() = 0 size() = 0 ``` -## multimap::const_iterator (STL/CLR) +## `multimap::const_iterator` The type of a constant iterator for the controlled sequence. @@ -299,7 +299,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::const_reference (STL/CLR) +## `multimap::const_reference` The type of a constant reference to an element. @@ -344,7 +344,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::const_reverse_iterator (STL/CLR) +## `multimap::const_reverse_iterator` The type of a constant reverse iterator for the controlled sequence. @@ -386,7 +386,7 @@ int main() [c 3] [b 2] [a 1] ``` -## multimap::count (STL/CLR) +## `multimap::count` Finds the number of elements matching a specified key. @@ -398,12 +398,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -439,7 +439,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## multimap::difference_type (STL/CLR) +## `multimap::difference_type` The types of a signed distance between two elements. @@ -494,7 +494,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## multimap::empty (STL/CLR) +## `multimap::empty` Tests whether no elements are present. @@ -506,7 +506,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [multimap::size (STL/CLR)](#size)`() == 0`. You use it to test whether the multimap is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `multimap` is empty. ### Example @@ -546,7 +546,7 @@ size() = 0 empty() = True ``` -## multimap::end (STL/CLR) +## `multimap::end` Designates the end of the controlled sequence. @@ -558,7 +558,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -599,24 +599,24 @@ int main() *--end() = [c 3] ``` -## multimap::equal_range (STL/CLR) +## `multimap::equal_range` Finds range that matches a specified key. ### Syntax ```cpp -pair_iter_iter equal_range(key_type _Keyval); +pair_iter_iter equal_range(key_type key); ``` #### Parameters -*_Keyval*
+*`key`*
Key value to search for. ### Remarks -The method returns a pair of iterators `-` [multimap::lower_bound (STL/CLR)](#lower_bound)`(_Keyval),` [multimap::upper_bound (STL/CLR)](#upper_bound)`(_Keyval)`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The method returns a pair of iterators, `pair_iter_iter(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -660,7 +660,7 @@ equal_range(L'x') empty = True [b 2] ``` -## multimap::erase (STL/CLR) +## `multimap::erase` Removes elements at specified positions. @@ -674,25 +674,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [multimap::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -753,7 +753,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## multimap::find (STL/CLR) +## `multimap::find` Finds an element that matches a specified key. @@ -765,12 +765,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [multimap::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns[`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -812,7 +812,7 @@ find b = [b 2] find C = False ``` -## multimap::generic_container (STL/CLR) +## `multimap::generic_container` The type of the generic interface for the container. @@ -876,7 +876,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## multimap::generic_iterator (STL/CLR) +## `multimap::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -933,7 +933,7 @@ int main() [a 1] ``` -## multimap::generic_reverse_iterator (STL/CLR) +## `multimap::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -989,7 +989,7 @@ int main() [c 3] ``` -## multimap::generic_value (STL/CLR) +## `multimap::generic_value` The type of an element for use with the generic interface for the container. @@ -1043,7 +1043,7 @@ int main() [a 1] ``` -## multimap::insert (STL/CLR) +## `multimap::insert` Adds elements. @@ -1059,34 +1059,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1161,7 +1161,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [b 2] [c 3] [x 24] [y 25] ``` -## multimap::iterator (STL/CLR) +## `multimap::iterator` The type of an iterator for the controlled sequence. @@ -1203,7 +1203,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::key_comp (STL/CLR) +## `multimap::key_comp` Copies the ordering delegate for two keys. @@ -1262,7 +1262,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multimap::key_compare (STL/CLR) +## `multimap::key_compare` The ordering delegate for two keys. @@ -1322,7 +1322,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multimap::key_type (STL/CLR) +## `multimap::key_type` The type of an ordering key. @@ -1334,7 +1334,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1367,7 +1367,7 @@ int main() a b c ``` -## multimap::lower_bound (STL/CLR) +## `multimap::lower_bound` Finds beginning of range that matches a specified key. @@ -1379,12 +1379,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1426,7 +1426,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## multimap::make_value (STL/CLR) +## `multimap::make_value` Constructs a value object. @@ -1438,15 +1438,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1475,7 +1475,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::mapped_type (STL/CLR) +## `multimap::mapped_type` The type of a mapped value associated with each key. @@ -1487,7 +1487,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1520,7 +1520,7 @@ int main() 1 2 3 ``` -## multimap::multimap (STL/CLR) +## `multimap::multimap` Constructs a container object. @@ -1543,16 +1543,16 @@ multimap(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1567,19 +1567,19 @@ The constructor: `explicit multimap(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `multimap(multimap% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multimap object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multimap` object *`right`*, with the default ordering predicate. The constructor: `multimap(multimap^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multimap object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multimap` object *`right`*, with the default ordering predicate. The constructor: @@ -1591,19 +1591,19 @@ The constructor: `template multimap(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `multimap(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1693,7 +1693,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## multimap::operator= (STL/CLR) +## `multimap::operator=` Replaces the controlled sequence. @@ -1705,12 +1705,12 @@ multimap% operator=(multimap% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1748,7 +1748,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::rbegin (STL/CLR) +## `multimap::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1799,7 +1799,7 @@ int main() *++rbegin() = [b 2] ``` -## multimap::reference (STL/CLR) +## `multimap::reference` The type of a reference to an element. @@ -1844,7 +1844,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::rend (STL/CLR) +## `multimap::rend` Designates the end of the reversed controlled sequence. @@ -1897,7 +1897,7 @@ int main() *--rend() = [a 1] ``` -## multimap::reverse_iterator (STL/CLR) +## `multimap::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1939,7 +1939,7 @@ int main() [c 3] [b 2] [a 1] ``` -## multimap::size (STL/CLR) +## `multimap::size` Counts the number of elements. @@ -1951,7 +1951,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [multimap::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1991,9 +1991,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## multimap::size_type (STL/CLR) +## `multimap::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2039,7 +2039,7 @@ int main() end()-begin() = 3 ``` -## multimap::swap (STL/CLR) +## `multimap::swap` Swaps the contents of two containers. @@ -2051,12 +2051,12 @@ void swap(multimap% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2107,7 +2107,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::to_array (STL/CLR) +## `multimap::to_array` Copies the controlled sequence to a new array. @@ -2157,7 +2157,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::upper_bound (STL/CLR) +## `multimap::upper_bound` Finds end of range that matches a specified key. @@ -2169,12 +2169,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2216,7 +2216,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## multimap::value_comp (STL/CLR) +## `multimap::value_comp` Copies the ordering delegate for two element values. @@ -2263,7 +2263,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## multimap::value_compare (STL/CLR) +## `multimap::value_compare` The ordering delegate for two element values. @@ -2311,7 +2311,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## multimap::value_type (STL/CLR) +## `multimap::value_type` The type of an element. @@ -2355,7 +2355,7 @@ int main() [a 1] [b 2] [c 3] ``` -## operator!= (multimap) (STL/CLR) +## `operator!=` (multimap) List not equal comparison. @@ -2370,15 +2370,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two multimaps are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two multimaps are compared element by element. ### Example @@ -2426,7 +2426,7 @@ int main() [a b c] != [a b d] is True ``` -## `operator<` (multimap) (STL/CLR) +## `operator<` (multimap) List less than comparison. @@ -2441,15 +2441,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two multimaps are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two multimaps are compared element by element. ### Example @@ -2497,7 +2497,7 @@ int main() [a b c] < [a b d] is True ``` -## `operator<=` (multimap) (STL/CLR) +## `operator<=` (multimap) List less than or equal comparison. @@ -2512,15 +2512,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two multimaps are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two multimaps are compared element by element. ### Example @@ -2568,7 +2568,7 @@ int main() [a b d] <= [a b c] is False ``` -## operator== (multimap) (STL/CLR) +## `operator==` (multimap) List equal comparison. @@ -2583,15 +2583,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two multimaps are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two multimaps are compared element by element. ### Example @@ -2639,7 +2639,7 @@ int main() [a b c] == [a b d] is False ``` -## `operator>` (multimap) (STL/CLR) +## `operator>` (multimap) List greater than comparison. @@ -2654,15 +2654,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two multimaps are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two multimaps are compared element by element. ### Example @@ -2710,7 +2710,7 @@ int main() [a b d] > [a b c] is True ``` -## `operator>=` (multimap) (STL/CLR) +## `operator>=` (multimap) List greater than or equal comparison. @@ -2725,15 +2725,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left` `<` `right)`. You use it to test whether *left* is not ordered before *right* when the two multimaps are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two multimaps are compared element by element. ### Example diff --git a/docs/dotnet/multiset-stl-clr.md b/docs/dotnet/multiset-stl-clr.md index 33b1ab9d4a..bea1d2aad3 100644 --- a/docs/dotnet/multiset-stl-clr.md +++ b/docs/dotnet/multiset-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::multiset", "cliext::multiset::begin", "cliext::multiset:: helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "multiset class [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "map member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]"] ms.assetid: 7c46e2b4-cd88-49b7-a9e6-63ad5ae7feb5 --- -# multiset (STL/CLR) +# `multiset` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `multiset` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,87 +31,87 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[multiset::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[multiset::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[multiset::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[multiset::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[multiset::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[multiset::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[multiset::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[multiset::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[multiset::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[multiset::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[multiset::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[multiset::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[multiset::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[multiset::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[multiset::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[multiset::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[multiset::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[multiset::clear (STL/CLR)](#clear)|Removes all elements.| -|[multiset::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[multiset::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[multiset::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[multiset::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[multiset::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[multiset::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[multiset::insert (STL/CLR)](#insert)|Adds elements.| -|[multiset::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[multiset::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[multiset::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[multiset::multiset (STL/CLR)](#multiset)|Constructs a container object.| -|[multiset::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[multiset::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[multiset::size (STL/CLR)](#size)|Counts the number of elements.| -|[multiset::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[multiset::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[multiset::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[multiset::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[multiset::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (multiset) (STL/CLR)](#op_neq)|Determines if a `multiset` object is not equal to another `multiset` object.| -|[operator< (multiset) (STL/CLR)](#op_lt)|Determines if a `multiset` object is less than another `multiset` object.| -|[operator<= (multiset) (STL/CLR)](#op_lteq)|Determines if a `multiset` object is less than or equal to another `multiset` object.| -|[operator== (multiset) (STL/CLR)](#op_eq)|Determines if a `multiset` object is equal to another `multiset` object.| -|[operator> (multiset) (STL/CLR)](#op_gt)|Determines if a `multiset` object is greater than another `multiset` object.| -|[operator>= (multiset) (STL/CLR)](#op_gteq)|Determines if a `multiset` object is greater than or equal to another `multiset` object.| +| Type definition | Description | +|---|---| +| [`multiset::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`multiset::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`multiset::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`multiset::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`multiset::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`multiset::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`multiset::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`multiset::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`multiset::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`multiset::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`multiset::key_type`](#key_type) | The type of an ordering key. | +| [`multiset::reference`](#reference) | The type of a reference to an element. | +| [`multiset::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`multiset::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`multiset::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`multiset::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`multiset::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`multiset::clear`](#clear) | Removes all elements. | +| [`multiset::count`](#count) | Counts elements matching a specified key. | +| [`multiset::empty`](#empty) | Tests whether no elements are present. | +| [`multiset::end`](#end) | Designates the end of the controlled sequence. | +| [`multiset::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`multiset::erase`](#erase) | Removes elements at specified positions. | +| [`multiset::find`](#find) | Finds an element that matches a specified key. | +| [`multiset::insert`](#insert) | Adds elements. | +| [`multiset::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`multiset::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`multiset::make_value`](#make_value) | Constructs a value object. | +| [`multiset::multiset`](#multiset) | Constructs a container object. | +| [`multiset::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`multiset::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`multiset::size`](#size) | Counts the number of elements. | +| [`multiset::swap`](#swap) | Swaps the contents of two containers. | +| [`multiset::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`multiset::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`multiset::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`multiset::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (multiset)](#op_neq) | Determines if a `multiset` object isn't equal to another `multiset` object. | +| [`operator<` (multiset)](#op_lt) | Determines if a `multiset` object is less than another `multiset` object. | +| [`operator<=` (multiset)](#op_lteq) | Determines if a `multiset` object is less than or equal to another `multiset` object. | +| [`operator==` (multiset)](#op_eq) | Determines if a `multiset` object is equal to another `multiset` object. | +| [`operator>` (multiset)](#op_gt) | Determines if a `multiset` object is greater than another `multiset` object. | +| [`operator>=` (multiset)](#op_gteq) | Determines if a `multiset` object is greater than or equal to another `multiset` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [multiset::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the multiset; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [multiset::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`multiset::key_compare`](#key_compare). You can specify the stored delegate object when you construct the multiset; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`multiset::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [multiset::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`multiset::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -121,21 +121,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set (STL/CLR)](../dotnet/set-stl-clr.md), an object of template class `multiset` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set (STL/CLR)](../dotnet/set-stl-clr.md), an object of template class `multiset` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element serves as both a ey and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A multiset supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [multiset::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a multiset iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `multiset` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `multiset` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a multiset element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `multiset` element directly given its numerical position. That requires a random-access iterator. -A multiset iterator stores a handle to its associated multiset node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A multiset iterator remains valid so long as its associated multiset node is associated with some multiset. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `multiset` iterator stores a handle to its associated `multiset` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `multiset` iterator remains valid so long as its associated `multiset` node is associated with some multiset. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## multiset::begin (STL/CLR) +## `multiset::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ a b c *++begin() = b ``` -## multiset::clear (STL/CLR) +## `multiset::clear` Removes all elements. @@ -195,7 +195,7 @@ void clear(); ### Remarks -The member function effectively calls [multiset::erase (STL/CLR)](#erase)`(` [multiset::begin (STL/CLR)](#begin)`(),` [multiset::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -241,7 +241,7 @@ a b size() = 0 ``` -## multiset::const_iterator (STL/CLR) +## `multiset::const_iterator` The type of a constant iterator for the controlled sequence. @@ -283,7 +283,7 @@ int main() a b c ``` -## multiset::const_reference (STL/CLR) +## `multiset::const_reference` The type of a constant reference to an element. @@ -328,9 +328,9 @@ int main() a b c ``` -## multiset::const_reverse_iterator (STL/CLR) +## `multiset::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -370,7 +370,7 @@ int main() c b a ``` -## multiset::count (STL/CLR) +## `multiset::count` Finds the number of elements matching a specified key. @@ -382,12 +382,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -423,7 +423,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## multiset::difference_type (STL/CLR) +## `multiset::difference_type` The types of a signed distance between two elements. @@ -478,7 +478,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## multiset::empty (STL/CLR) +## `multiset::empty` Tests whether no elements are present. @@ -490,7 +490,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [multiset::size (STL/CLR)](#size)`() == 0`. You use it to test whether the multiset is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `multiset` is empty. ### Example @@ -530,7 +530,7 @@ size() = 0 empty() = True ``` -## multiset::end (STL/CLR) +## `multiset::end` Designates the end of the controlled sequence. @@ -542,7 +542,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -579,7 +579,7 @@ a b c *--end() = c ``` -## multiset::equal_range (STL/CLR) +## `multiset::equal_range` Finds range that matches a specified key. @@ -591,12 +591,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [multiset::lower_bound (STL/CLR)](#lower_bound)`(key),` [multiset::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -639,7 +639,7 @@ equal_range(L'x') empty = True b ``` -## multiset::erase (STL/CLR) +## `multiset::erase` Removes elements at specified positions. @@ -653,25 +653,25 @@ size_type erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [multiset::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range `[first, last)`, and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -723,7 +723,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## multiset::find (STL/CLR) +## `multiset::find` Finds an element that matches a specified key. @@ -735,12 +735,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [multiset::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -779,7 +779,7 @@ find b = b find C = False ``` -## multiset::generic_container (STL/CLR) +## `multiset::generic_container` The type of the generic interface for the container. @@ -843,7 +843,7 @@ a b c d a b c d e ``` -## multiset::generic_iterator (STL/CLR) +## `multiset::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -899,7 +899,7 @@ a b c a ``` -## multiset::generic_reverse_iterator (STL/CLR) +## `multiset::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -955,7 +955,7 @@ a b c c ``` -## multiset::generic_value (STL/CLR) +## `multiset::generic_value` The type of an element for use with the generic interface for the container. @@ -1009,7 +1009,7 @@ a b c a ``` -## multiset::insert (STL/CLR) +## `multiset::insert` Adds elements. @@ -1025,34 +1025,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1122,7 +1122,7 @@ a b b c x a b b c x y ``` -## multiset::iterator (STL/CLR) +## `multiset::iterator` The type of an iterator for the controlled sequence. @@ -1164,7 +1164,7 @@ int main() a b c ``` -## multiset::key_comp (STL/CLR) +## `multiset::key_comp` Copies the ordering delegate for two keys. @@ -1223,7 +1223,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multiset::key_compare (STL/CLR) +## `multiset::key_compare` The ordering delegate for two keys. @@ -1283,7 +1283,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multiset::key_type (STL/CLR) +## `multiset::key_type` The type of an ordering key. @@ -1295,7 +1295,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1328,7 +1328,7 @@ int main() a b c ``` -## multiset::lower_bound (STL/CLR) +## `multiset::lower_bound` Finds beginning of range that matches a specified key. @@ -1340,12 +1340,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1385,7 +1385,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## multiset::make_value (STL/CLR) +## `multiset::make_value` Constructs a value object. @@ -1397,12 +1397,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1431,7 +1431,7 @@ int main() a b c ``` -## multiset::multiset (STL/CLR) +## `multiset::multiset` Constructs a container object. @@ -1454,16 +1454,16 @@ multiset(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1478,19 +1478,19 @@ The constructor: `explicit multiset(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `multiset(multiset% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multiset object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multiset` object *`right`*, with the default ordering predicate. The constructor: `multiset(multiset^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multiset object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multiset` object *`right`*, with the default ordering predicate. The constructor: @@ -1502,19 +1502,19 @@ The constructor: `template multiset(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `multiset(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1602,7 +1602,7 @@ c b a a b c ``` -## multiset::operator= (STL/CLR) +## `multiset::operator=` Replaces the controlled sequence. @@ -1614,12 +1614,12 @@ multiset% operator=(multiset% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1657,7 +1657,7 @@ a b c a b c ``` -## multiset::rbegin (STL/CLR) +## `multiset::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1705,7 +1705,7 @@ a b c *++rbegin() = b ``` -## multiset::reference (STL/CLR) +## `multiset::reference` The type of a reference to an element. @@ -1750,7 +1750,7 @@ int main() a b c ``` -## multiset::rend (STL/CLR) +## `multiset::rend` Designates the end of the reversed controlled sequence. @@ -1799,7 +1799,7 @@ a b c *--rend() = a ``` -## multiset::reverse_iterator (STL/CLR) +## `multiset::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1841,7 +1841,7 @@ int main() c b a ``` -## multiset::size (STL/CLR) +## `multiset::size` Counts the number of elements. @@ -1853,7 +1853,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [multiset::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1895,9 +1895,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## multiset::size_type (STL/CLR) +## `multiset::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1943,7 +1943,7 @@ a b c end()-begin() = 3 ``` -## multiset::swap (STL/CLR) +## `multiset::swap` Swaps the contents of two containers. @@ -1955,12 +1955,12 @@ void swap(multiset% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2011,7 +2011,7 @@ d e f a b c ``` -## multiset::to_array (STL/CLR) +## `multiset::to_array` Copies the controlled sequence to a new array. @@ -2061,7 +2061,7 @@ a b c d a b c ``` -## multiset::upper_bound (STL/CLR) +## `multiset::upper_bound` Finds end of range that matches a specified key. @@ -2073,12 +2073,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2118,7 +2118,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## multiset::value_comp (STL/CLR) +## `multiset::value_comp` Copies the ordering delegate for two element values. @@ -2162,7 +2162,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## multiset::value_compare (STL/CLR) +## `multiset::value_compare` The ordering delegate for two element values. @@ -2207,7 +2207,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## multiset::value_type (STL/CLR) +## `multiset::value_type` The type of an element. @@ -2252,7 +2252,7 @@ int main() a b c ``` -## operator!= (multiset) (STL/CLR) +## `operator!=` (multiset) List not equal comparison. @@ -2266,15 +2266,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two multisets are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two multisets are compared element by element. ### Example @@ -2336,15 +2336,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two multisets are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two multisets are compared element by element. ### Example @@ -2392,7 +2392,7 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (multiset) (STL/CLR) +## `operator<=` (multiset) List less than or equal comparison. @@ -2406,15 +2406,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two multisets are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two multisets are compared element by element. ### Example @@ -2462,7 +2462,7 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (multiset) (STL/CLR) +## `operator==` (multiset) List equal comparison. @@ -2476,15 +2476,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two multisets are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two multisets are compared element by element. ### Example @@ -2532,7 +2532,7 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (multiset) (STL/CLR) +## `operator>` (multiset) List greater than comparison. @@ -2546,15 +2546,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two multisets are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two multisets are compared element by element. ### Example @@ -2602,7 +2602,7 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (multiset) (STL/CLR) +## `operator>=` (multiset) List greater than or equal comparison. @@ -2616,15 +2616,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two multisets are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two multisets are compared element by element. ### Example diff --git a/docs/dotnet/numeric-stl-clr.md b/docs/dotnet/numeric-stl-clr.md index 2be870dabc..2aae6eaa34 100644 --- a/docs/dotnet/numeric-stl-clr.md +++ b/docs/dotnet/numeric-stl-clr.md @@ -9,7 +9,7 @@ ms.assetid: 1dc4d9a3-e734-459c-9678-5d9be0ef4c79 --- # numeric (STL/CLR) -Defines container template functions that perform algorithms provided for numerical processing. +Defines container function templates that perform algorithms provided for numerical processing. ## Syntax diff --git a/docs/dotnet/queue-stl-clr.md b/docs/dotnet/queue-stl-clr.md index 841400c6e7..d3bc7430b5 100644 --- a/docs/dotnet/queue-stl-clr.md +++ b/docs/dotnet/queue-stl-clr.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: queue (STL/CLR)" title: "queue (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: queue (STL/CLR)" +ms.date: "4/20/2023" ms.topic: "reference" f1_keywords: ["cliext::queue", "cliext::queue::assign", "cliext::queue::back", "cliext::queue::back_item", "cliext::queue::const_reference", "cliext::queue::container_type", "cliext::queue::difference_type", "cliext::queue::empty", "cliext::queue::front", "cliext::queue::front_item", "cliext::queue::generic_container", "cliext::queue::generic_value", "cliext::queue::get_container", "cliext::queue::operator=", "cliext::queue::pop", "cliext::queue::push", "cliext::queue::queue", "cliext::queue::reference", "cliext::queue::size", "cliext::queue::size_type", "cliext::queue::to_array", "cliext::queue::value_type"] helpviewer_keywords: [" header [STL/CLR]", "queue class [STL/CLR]", " header [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]", "assign member [STL/CLR]", "back member [STL/CLR]", "back_item member [STL/CLR]", "const_reference member [STL/CLR]", "container_type member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "front member [STL/CLR]", "front_item member [STL/CLR]", "generic_container member [STL/CLR]", "generic_value member [STL/CLR]", "get_container member [STL/CLR]", "operator= member [STL/CLR]", "pop member [STL/CLR]", "push member [STL/CLR]", "queue member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "to_array member [STL/CLR]", "value_type member [STL/CLR]"] -ms.assetid: 9ea7dec3-ea98-48ff-87d0-a5afc924aaf2 --- -# queue (STL/CLR) +# `queue` (STL/CLR) -The template class describes an object that controls a varying-length sequence of elements that has first-in first-out access. You use the container adapter `queue` to manage an underlying container as a queue. +The template class describes an object that controls a varying length sequence of elements that has first-in first-out access. Use the container adapter `queue` to manage an underlying container as a queue. -In the description below, `GValue` is the same as *Value* unless the latter is a ref type, in which case it is `Value^`. Similarly, `GContainer` is the same as *Container* unless the latter is a ref type, in which case it is `Container^`. +In the following description, `GValue` is the same as *`Value`* unless the latter is a ref type, in which case it's `Value^`. Similarly, `GContainer` is the same as *`Container`* unless the latter is a ref type, in which case it's `Container^`. ## Syntax @@ -27,73 +26,76 @@ template +*`Value`*\ The type of an element in the controlled sequence. -*Container*
+*`Container`*\ The type of the underlying container. ## Requirements -**Header:** \ +**Header:** `` + +**Namespace:** `cliext` -**Namespace:** cliext +> [!IMPORTANT] +> To compile the examples in this topic, ensure that you have installed C++/CLI support as described in [Install C++/CLI support in Visual Studio 2022](dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). For the project type, create a *CLR Console app (.NET Framework)*. ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[queue::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[queue::container_type (STL/CLR)](#container_type)|The type of the underlying container.| -|[queue::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[queue::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container adapter.| -|[queue::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container adapter.| -|[queue::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[queue::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[queue::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[queue::assign (STL/CLR)](#assign)|Replaces all elements.| -|[queue::back (STL/CLR)](#back)|Accesses the last element.| -|[queue::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[queue::front (STL/CLR)](#front)|Accesses the first element.| -|[queue::get_container (STL/CLR)](#get_container)|Accesses the underlying container.| -|[queue::pop (STL/CLR)](#pop)|Removes the first element.| -|[queue::push (STL/CLR)](#push)|Adds a new last element.| -|[queue::queue (STL/CLR)](#queue)|Constructs a container object.| -|[queue::size (STL/CLR)](#size)|Counts the number of elements.| -|[queue::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| - -|Property|Description| -|--------------|-----------------| -|[queue::back_item (STL/CLR)](#back_item)|Accesses the last element.| -|[queue::front_item (STL/CLR)](#front_item)|Accesses the first element.| - -|Operator|Description| -|--------------|-----------------| -|[queue::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (queue) (STL/CLR)](#op_neq)|Determines if a `queue` object is not equal to another `queue` object.| -|[operator< (queue) (STL/CLR)](#op_lt)|Determines if a `queue` object is less than another `queue` object.| -|[operator<= (queue) (STL/CLR)](#op_lteq)|Determines if a `queue` object is less than or equal to another `queue` object.| -|[operator== (queue) (STL/CLR)](#op_eq)|Determines if a `queue` object is equal to another `queue` object.| -|[operator> (queue) (STL/CLR)](#op_gt)|Determines if a `queue` object is greater than another `queue` object.| -|[operator>= (queue) (STL/CLR)](#op_gteq)|Determines if a `queue` object is greater than or equal to another `queue` object.| +| Type definition | Description | +|---|---| +| [`queue::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`queue::container_type`](#container_type) | The type of the underlying container. | +| [`queue::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`queue::generic_container`](#generic_container) | The type of the generic interface for the container adapter. | +| [`queue::generic_value`](#generic_value) | The type of an element for the generic interface for the container adapter. | +| [`queue::reference`](#reference) | The type of a reference to an element. | +| [`queue::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`queue::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`queue::assign`](#assign) | Replaces all elements. | +| [`queue::back`](#back) | Accesses the last element. | +| [`queue::empty`](#empty) | Tests whether no elements are present. | +| [`queue::front`](#front) | Accesses the first element. | +| [`queue::get_container`](#get_container) | Accesses the underlying container. | +| [`queue::pop`](#pop) | Removes the first element. | +| [`queue::push`](#push) | Adds a new last element. | +| [`queue::queue`](#queue) | Constructs a container object. | +| [`queue::size`](#size) | Counts the number of elements. | +| [`queue::to_array`](#to_array) | Copies the controlled sequence to a new array. | + +| Property | Description | +|---|---| +| [`queue::back_item`](#back_item) | Accesses the last element. | +| [`queue::front_item`](#front_item) | Accesses the first element. | + +| Operator | Description | +|---|---| +| [`queue::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (queue)](#op_neq) | Determines if a `queue` object isn't equal to another `queue` object. | +| [`operator<` (queue)](#op_lt) | Determines if a `queue` object is less than another `queue` object. | +| [`operator<=` (queue)](#op_lteq) | Determines if a `queue` object is less than or equal to another `queue` object. | +| [`operator==` (queue)](#op_eq) | Determines if a `queue` object is equal to another `queue` object. | +| [`operator>` (queue)](#op_gt) | Determines if a `queue` object is greater than another `queue` object. | +| [`operator>=` (queue)](#op_gteq) | Determines if a `queue` object is greater than or equal to another `queue` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -|IQueue\|Maintain generic container adapter.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| `IQueue` | Maintain generic container adapter. | ## Remarks -The object allocates and frees storage for the sequence it controls through an underlying container, of type `Container`, that stores `Value` elements and grows on demand. The object restricts access to just pushing the first element and popping the last element, implementing a first-in first-out queue (also known as a FIFO queue, or simply a queue). +The object allocates and frees storage for the sequence it controls through an underlying container of type *`Container`* that stores *`Value`* elements and grows on demand. The object restricts access to just pushing the first element and popping the last element, implementing a first-in first-out queue (also known as a FIFO queue, or simply a queue). ## Members -## queue::assign (STL/CLR) +## `queue::assign` Replaces all elements. @@ -105,7 +107,7 @@ void assign(queue% right); #### Parameters -*right*
+*`right`*\ Container adapter to insert. ### Remarks @@ -117,29 +119,30 @@ The member function assigns `right.get_container()` to the underlying container. ```cpp // cliext_queue_assign.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign a repetition of values + // assign a repetition of values Myqueue c2; c2.assign(c1); for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -147,7 +150,7 @@ a b c a b c ``` -## queue::back (STL/CLR) +## `queue::back` Accesses the last element. @@ -159,38 +162,39 @@ reference back(); ### Remarks -The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know it exists. +The member function returns a reference to the last element of the controlled sequence, which must be nonempty. You use it to access the last element, when you know one exists. ### Example ```cpp // cliext_queue_back.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("back() = {0}", c1.back()); -// alter last item and reinspect + // alter last item and reinspect c1.back() = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -199,7 +203,7 @@ back() = c a b x ``` -## queue::back_item (STL/CLR) +## `queue::back_item` Accesses the last element. @@ -211,38 +215,39 @@ property value_type back_item; ### Remarks -The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know it exists. +The property accesses the last element of the controlled sequence, which must be nonempty. You use it to read or write the last element, when you know one exists. ### Example ```cpp // cliext_queue_back_item.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("back_item = {0}", c1.back_item); -// alter last item and reinspect + // alter last item and reinspect c1.back_item = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -251,7 +256,7 @@ back_item = c a b x ``` -## queue::const_reference (STL/CLR) +## `queue::const_reference` The type of a constant reference to an element. @@ -270,17 +275,18 @@ The type describes a constant reference to an element. ```cpp // cliext_queue_const_reference.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for (; !c1.empty(); c1.pop()) { // get a const reference to an element Myqueue::const_reference cref = c1.front(); @@ -288,14 +294,14 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::container_type (STL/CLR) +## `queue::container_type` The type of the underlying container. @@ -314,30 +320,31 @@ The type is a synonym for the template parameter `Container`. ```cpp // cliext_queue_container_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" using container_type + // display contents "a b c" using container_type Myqueue::container_type wc1 = c1.get_container(); for each (wchar_t elem in wc1) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::difference_type (STL/CLR) +## `queue::difference_type` The types of a signed distance between two elements. @@ -356,29 +363,30 @@ The type describes a possibly negative element count. ```cpp // cliext_queue_difference_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// compute negative difference + // compute negative difference Myqueue::difference_type diff = c1.size(); c1.push(L'd'); c1.push(L'e'); diff -= c1.size(); System::Console::WriteLine("pushing 2 = {0}", diff); -// compute positive difference + // compute positive difference diff = c1.size(); c1.pop(); c1.pop(); @@ -386,7 +394,7 @@ int main() diff -= c1.size(); System::Console::WriteLine("popping 3 = {0}", diff); return (0); - } +} ``` ```Output @@ -395,7 +403,7 @@ pushing 2 = -2 popping 3 = 3 ``` -## queue::empty (STL/CLR) +## `queue::empty` Tests whether no elements are present. @@ -407,38 +415,39 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [queue::size (STL/CLR)](#size)`() == 0`. You use it to test whether the queue is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `queue` is empty. ### Example ```cpp // cliext_queue_empty.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); System::Console::WriteLine("size() = {0}", c1.size()); System::Console::WriteLine("empty() = {0}", c1.empty()); -// clear the container and reinspect + // clear the container and reinspect c1.pop(); c1.pop(); c1.pop(); System::Console::WriteLine("size() = {0}", c1.size()); System::Console::WriteLine("empty() = {0}", c1.empty()); return (0); - } +} ``` ```Output @@ -449,7 +458,7 @@ size() = 0 empty() = True ``` -## queue::front (STL/CLR) +## `queue::front` Accesses the first element. @@ -461,38 +470,39 @@ reference front(); ### Remarks -The member function returns a reference to the first element of the controlled sequence, which must be non-empty. You use it to access the first element, when you know it exists. +The member function returns a reference to the first element of the controlled sequence, which must be nonempty. You use it to access the first element, when you know one exists. ### Example ```cpp // cliext_queue_front.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect first item + // inspect first item System::Console::WriteLine("front() = {0}", c1.front()); -// alter first item and reinspect + // alter first item and reinspect c1.front() = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -501,7 +511,7 @@ front() = a x b c ``` -## queue::front_item (STL/CLR) +## `queue::front_item` Accesses the first element. @@ -513,38 +523,39 @@ property value_type front_item; ### Remarks -The property accesses the first element of the controlled sequence, which must be non-empty. You use it to read or write the first element, when you know it exists. +The property accesses the first element of the controlled sequence, which must be nonempty. You use it to read or write the first element, when you know one exists. ### Example ```cpp // cliext_queue_front_item.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("front_item = {0}", c1.front_item); -// alter last item and reinspect + // alter last item and reinspect c1.front_item = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -553,7 +564,7 @@ front_item = a x b c ``` -## queue::generic_container (STL/CLR) +## `queue::generic_container` The type of the generic interface for the container adapter. @@ -573,40 +584,41 @@ The type describes the generic interface for this template container adapter cla ```cpp // cliext_queue_generic_container.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct a generic container + // construct a generic container Myqueue::generic_container^ gc1 = %c1; for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify generic and display original + // modify generic and display original gc1->push(L'd'); for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify original and display generic + // modify original and display generic c1.push(L'e'); for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -616,7 +628,7 @@ a b c d a b c d e ``` -## queue::generic_value (STL/CLR) +## `queue::generic_value` The type of an element for use with the generic interface for the container. @@ -635,28 +647,29 @@ The type describes an object of type `GValue` that describes the stored element ```cpp // cliext_queue_generic_value.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// get interface to container + // get interface to container Myqueue::generic_container^ gc1 = %c1; for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// display in order using generic_value + // display in order using generic_value for (; !gc1->empty(); gc1->pop()) { Myqueue::generic_value elem = gc1->front(); @@ -665,7 +678,7 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -674,7 +687,7 @@ a b c a b c ``` -## queue::get_container (STL/CLR) +## `queue::get_container` Accesses the underlying container. @@ -693,29 +706,30 @@ The member function returns the underlying container. You use it to bypass the r ```cpp // cliext_queue_get_container.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::operator= (STL/CLR) +## `queue::operator=` Replaces the controlled sequence. @@ -727,41 +741,42 @@ queue % operator=(queue % right); #### Parameters -*right*
+*`right`*\ Container adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example ```cpp // cliext_queue_operator_as.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2 = c1; for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -769,9 +784,9 @@ a b c a b c ``` -## queue::pop (STL/CLR) +## `queue::pop` -Removes the last element. +Removes the first element. ### Syntax @@ -781,35 +796,36 @@ void pop(); ### Remarks -The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the queue by one element at the back. +Removes the first element of the controlled sequence, which must be nonempty. ### Example ```cpp // cliext_queue_pop.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// pop an element and redisplay + // pop an element and redisplay c1.pop(); for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -817,7 +833,7 @@ a b c b c ``` -## queue::push (STL/CLR) +## `queue::push` Adds a new last element. @@ -836,29 +852,30 @@ The member function adds an element with value `val` at the end of the queue. Yo ```cpp // cliext_queue_push.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::queue (STL/CLR) +## `queue::queue` Constructs a container adapter object. @@ -873,10 +890,10 @@ explicit queue(container_type% wrapped); #### Parameters -*right*
+*`right`*\ Object to copy. -*wrapped*
+*`wrapped`*\ Wrapped container to use. ### Remarks @@ -891,25 +908,26 @@ The constructor: `queue(queue% right);` -creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the queue object *right*. +creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `queue` object *`right`*. The constructor: `queue(queue^ right);` -creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the queue object `*right`. +creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `queue` object `*right`. The constructor: `explicit queue(container_type wrapped);` -uses the existing container *wrapped* as the wrapped container. You use it to construct a queue from an existing container. +uses the existing container *`wrapped`* as the wrapped container. You use it to construct a `queue` from an existing container. ### Example ```cpp // cliext_queue_construct.cpp // compile with: /clr +#include "pch.h" #include #include @@ -917,31 +935,31 @@ typedef cliext::queue Myqueue; typedef cliext::list Mylist; typedef cliext::queue Myqueue_list; int main() - { -// construct an empty container +{ + // construct an empty container Myqueue c1; System::Console::WriteLine("size() = {0}", c1.size()); -// construct from an underlying container + // construct from an underlying container Mylist v2(5, L'x'); Myqueue_list c2(v2); for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct by copying another container + // construct by copying another container Myqueue_list c3(c2); for each (wchar_t elem in c3.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct by copying another container through handle + // construct by copying another container through handle Myqueue_list c4(%c2); for each (wchar_t elem in c4.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -951,7 +969,7 @@ x x x x x x x x x x ``` -## queue::reference (STL/CLR) +## `queue::reference` The type of a reference to an element. @@ -970,29 +988,30 @@ The type describes a reference to an element. ```cpp // cliext_queue_reference.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify back of queue and redisplay + // modify back of queue and redisplay Myqueue::reference ref = c1.back(); ref = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -1000,7 +1019,7 @@ a b c a b x ``` -## queue::size (STL/CLR) +## `queue::size` Counts the number of elements. @@ -1012,39 +1031,40 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [queue::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example ```cpp // cliext_queue_size.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); System::Console::WriteLine("size() = {0} starting with 3", c1.size()); -// pop an item and reinspect + // pop an item and reinspect c1.pop(); System::Console::WriteLine("size() = {0} after popping", c1.size()); -// add two elements and reinspect + // add two elements and reinspect c1.push(L'a'); c1.push(L'b'); System::Console::WriteLine("size() = {0} after adding 2", c1.size()); return (0); - } +} ``` ```Output @@ -1054,9 +1074,9 @@ size() = 2 after popping size() = 4 after adding 2 ``` -## queue::size_type (STL/CLR) +## `queue::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1073,29 +1093,30 @@ The type describes a non-negative element count. ```cpp // cliext_queue_size_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// compute positive difference + // compute positive difference Myqueue::size_type diff = c1.size(); c1.pop(); c1.pop(); diff -= c1.size(); System::Console::WriteLine("size difference = {0}", diff); return (0); - } +} ``` ```Output @@ -1103,7 +1124,7 @@ a b c size difference = 2 ``` -## queue::to_array (STL/CLR) +## `queue::to_array` Copies the controlled sequence to a new array. @@ -1122,17 +1143,18 @@ The member function returns an array containing the controlled sequence. You use ```cpp // cliext_queue_to_array.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// copy the container and modify it + // copy the container and modify it cli::array^ a1 = c1.to_array(); c1.push(L'd'); @@ -1140,12 +1162,12 @@ int main() System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// display the earlier array copy + // display the earlier array copy for each (wchar_t elem in a1) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -1153,7 +1175,7 @@ a b c d a b c ``` -## queue::value_type (STL/CLR) +## `queue::value_type` The type of an element. @@ -1165,24 +1187,25 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*. +The type is a synonym for the template parameter *`Value`*. ### Example ```cpp // cliext_queue_value_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display reversed contents " a b c" using value_type + // display reversed contents "a b c" using value_type for (; !c1.empty(); c1.pop()) { // store element in value_type object Myqueue::value_type val = c1.front(); @@ -1191,16 +1214,16 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## operator!= (queue) (STL/CLR) +## `operator!=` (queue) -Queue not equal comparison. +`Queue` not equal comparison. ### Syntax @@ -1213,43 +1236,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two queues are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_ne.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1259,7 +1283,7 @@ int main() System::Console::WriteLine("[a b c] != [a b d] is {0}", c1 != c2); return (0); - } +} ``` ```Output @@ -1269,9 +1293,9 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (queue) (STL/CLR) +## `operator<` (queue) -Queue less than comparison. +`Queue` less than comparison. ### Syntax @@ -1284,43 +1308,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->`[queue::size (STL/CLR)](#size)`() <` `right->size()` You use it to test whether *left* is ordered before *right* when the two queues are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_lt.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1330,7 +1355,7 @@ int main() System::Console::WriteLine("[a b c] < [a b d] is {0}", c1 < c2); return (0); - } +} ``` ```Output @@ -1340,9 +1365,9 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (queue) (STL/CLR) +## `operator<=` (queue) -Queue less than or equal comparison. +`Queue` less than or equal comparison. ### Syntax @@ -1355,43 +1380,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two queues are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_le.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1401,7 +1427,7 @@ int main() System::Console::WriteLine("[a b d] <= [a b c] is {0}", c2 <= c1); return (0); - } +} ``` ```Output @@ -1411,9 +1437,9 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (queue) (STL/CLR) +## `operator==` (queue) -Queue equal comparison. +`Queue` equal comparison. ### Syntax @@ -1426,43 +1452,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two queues are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_eq.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1472,7 +1499,7 @@ int main() System::Console::WriteLine("[a b c] == [a b d] is {0}", c1 == c2); return (0); - } +} ``` ```Output @@ -1482,9 +1509,9 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (queue) (STL/CLR) +## `operator>` (queue) -Queue greater than comparison. +`Queue` greater than comparison. ### Syntax @@ -1497,43 +1524,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two queues are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_gt.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1543,7 +1571,7 @@ int main() System::Console::WriteLine("[a b d] > [a b c] is {0}", c2 > c1); return (0); - } +} ``` ```Output @@ -1553,9 +1581,9 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (queue) (STL/CLR) +## `operator>=` (queue) -Queue greater than or equal comparison. +`Queue` greater than or equal comparison. ### Syntax @@ -1568,43 +1596,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two queues are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_ge.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1614,7 +1643,7 @@ int main() System::Console::WriteLine("[a b c] >= [a b d] is {0}", c1 >= c2); return (0); - } +} ``` ```Output diff --git a/docs/dotnet/reflection-cpp-cli.md b/docs/dotnet/reflection-cpp-cli.md index 9b31b0a149..5cf26a76a1 100644 --- a/docs/dotnet/reflection-cpp-cli.md +++ b/docs/dotnet/reflection-cpp-cli.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Reflection (C++/CLI)" title: "Reflection (C++/CLI)" -ms.date: "11/04/2016" -helpviewer_keywords: ["typeid keyword [C++]", "reflection [C++}, about reflection", "metadata, reflection", "GetType method", ".NET Framework [C++], reflection", "data types [C++], reflection", "reflection [C++}", "plug-ins [C++]", "reflection [C++}, plug-ins", "assemblies [C++], enumerating data types in", "public types [C++]", "reflection [C++], external assemblies", "assemblies [C++]", "data types [C++], enumerating", "public members [C++]"] -ms.assetid: 46b6ff4a-e441-4022-8892-78e69422f230 +description: "Learn more about: Reflection (C++/CLI)" +ms.date: 11/04/2016 +helpviewer_keywords: ["typeid keyword [C++]", "reflection [C++], about reflection", "metadata, reflection", "GetType method", ".NET Framework [C++], reflection", "data types [C++], reflection", "reflection [C++]", "plug-ins [C++]", "reflection [C++], plug-ins", "assemblies [C++], enumerating data types in", "public types [C++]", "reflection [C++], external assemblies", "assemblies [C++]", "data types [C++], enumerating", "public members [C++]"] --- # Reflection (C++/CLI) diff --git a/docs/dotnet/set-stl-clr.md b/docs/dotnet/set-stl-clr.md index d028cbb1fc..be54240cf6 100644 --- a/docs/dotnet/set-stl-clr.md +++ b/docs/dotnet/set-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::set", "cliext::set::begin", "cliext::set::clear", "cliext helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "set class [STL/CLR]", "operator!= (set) member [STL/CLR]", "operator< (set) member [STL/CLR]", "operator<= (set) member [STL/CLR]", "operator== (set) member [STL/CLR]", "operator> (set) member [STL/CLR]", "operator>= (set) member [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "set member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 27d3628c-741a-43a7-bef1-5085536f679e --- -# set (STL/CLR) +# `set` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `set` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,87 +31,87 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[set::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[set::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[set::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[set::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[set::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[set::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[set::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[set::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[set::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[set::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[set::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[set::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[set::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[set::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[set::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[set::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[set::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[set::clear (STL/CLR)](#clear)|Removes all elements.| -|[set::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[set::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[set::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[set::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[set::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[set::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[set::insert (STL/CLR)](#insert)|Adds elements.| -|[set::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[set::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[set::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[set::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[set::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[set::set (STL/CLR)](#set)|Constructs a container object.| -|[set::size (STL/CLR)](#size)|Counts the number of elements.| -|[set::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[set::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[set::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[set::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[set::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (set) (STL/CLR)](#op_neq)|Determines if a `set` object is not equal to another `set` object.| -|[operator< (set) (STL/CLR)](#op_lt)|Determines if a `set` object is less than another `set` object.| -|[operator<= (set) (STL/CLR)](#op_lteq)|Determines if a `set` object is less than or equal to another `set` object.| -|[operator== (set) (STL/CLR)](#op_eq)|Determines if a `set` object is equal to another `set` object.| -|[operator> (set) (STL/CLR)](#op_gt)|Determines if a `set` object is greater than another `set` object.| -|[operator>= (set) (STL/CLR)](#op_gteq)|Determines if a `set` object is greater than or equal to another `set` object.| +| Type definition | Description | +|---|---| +| [`set::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`set::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`set::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`set::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`set::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`set::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`set::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`set::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`set::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`set::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`set::key_type`](#key_type) | The type of an ordering key. | +| [`set::reference`](#reference) | The type of a reference to an element. | +| [`set::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`set::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`set::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`set::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`set::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`set::clear`](#clear) | Removes all elements. | +| [`set::count`](#count) | Counts elements matching a specified key. | +| [`set::empty`](#empty) | Tests whether no elements are present. | +| [`set::end`](#end) | Designates the end of the controlled sequence. | +| [`set::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`set::erase`](#erase) | Removes elements at specified positions. | +| [`set::find`](#find) | Finds an element that matches a specified key. | +| [`set::insert`](#insert) | Adds elements. | +| [`set::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`set::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`set::make_value`](#make_value) | Constructs a value object. | +| [`set::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`set::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`set::set`](#set) | Constructs a container object. | +| [`set::size`](#size) | Counts the number of elements. | +| [`set::swap`](#swap) | Swaps the contents of two containers. | +| [`set::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`set::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`set::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`set::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (set)](#op_neq) | Determines if a `set` object isn't equal to another `set` object. | +| [`operator<` (set)](#op_lt) | Determines if a `set` object is less than another `set` object. | +| [`operator<=` (set)](#op_lteq) | Determines if a `set` object is less than or equal to another `set` object. | +| [`operator==` (set)](#op_eq) | Determines if a `set` object is equal to another `set` object. | +| [`operator>` (set)](#op_gt) | Determines if a `set` object is greater than another `set` object. | +| [`operator>=` (set)](#op_gteq) | Determines if a `set` object is greater than or equal to another `set` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [set::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the set; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [set::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`set::key_compare`](#key_compare). You can specify the stored delegate object when you construct the set; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`set::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [set::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`set::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -121,21 +121,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set](../dotnet/set-stl-clr.md), an object of template class `set` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set](../dotnet/set-stl-clr.md), an object of template class `set` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element serves as both a ey and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A set supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [set::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a set iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `set` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `set` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a set element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `set` element directly given its numerical position. That requires a random-access iterator. -A set iterator stores a handle to its associated set node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A set iterator remains valid so long as its associated set node is associated with some set. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `set` iterator stores a handle to its associated `set` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `set` iterator remains valid so long as its associated `set` node is associated with some set. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## set::begin (STL/CLR) +## `set::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ a b c *++begin() = b ``` -## set::clear (STL/CLR) +## `set::clear` Removes all elements. @@ -195,7 +195,7 @@ void clear(); ### Remarks -The member function effectively calls [set::erase (STL/CLR)](#erase)`(` [set::begin (STL/CLR)](#begin)`(),` [set::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -241,7 +241,7 @@ a b size() = 0 ``` -## set::const_iterator (STL/CLR) +## `set::const_iterator` The type of a constant iterator for the controlled sequence. @@ -283,7 +283,7 @@ int main() a b c ``` -## set::const_reference (STL/CLR) +## `set::const_reference` The type of a constant reference to an element. @@ -328,9 +328,9 @@ int main() a b c ``` -## set::const_reverse_iterator (STL/CLR) +## `set::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -370,7 +370,7 @@ int main() c b a ``` -## set::count (STL/CLR) +## `set::count` Finds the number of elements matching a specified key. @@ -382,12 +382,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -423,7 +423,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## set::difference_type (STL/CLR) +## `set::difference_type` The types of a signed distance between two elements. @@ -478,7 +478,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## set::empty (STL/CLR) +## `set::empty` Tests whether no elements are present. @@ -490,7 +490,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [set::size (STL/CLR)](#size)`() == 0`. You use it to test whether the set is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `set` is empty. ### Example @@ -530,7 +530,7 @@ size() = 0 empty() = True ``` -## set::end (STL/CLR) +## `set::end` Designates the end of the controlled sequence. @@ -542,7 +542,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -579,7 +579,7 @@ a b c *--end() = c ``` -## set::equal_range (STL/CLR) +## `set::equal_range` Finds range that matches a specified key. @@ -591,12 +591,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [set::lower_bound (STL/CLR)](#lower_bound)`(key),` [set::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -639,7 +639,7 @@ equal_range(L'x') empty = True b ``` -## set::erase (STL/CLR) +## `set::erase` Removes elements at specified positions. @@ -653,25 +653,25 @@ size_type erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [set::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -723,7 +723,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## set::find (STL/CLR) +## `set::find` Finds an element that matches a specified key. @@ -735,12 +735,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [set::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -779,7 +779,7 @@ find b = b find C = False ``` -## set::generic_container (STL/CLR) +## `set::generic_container` The type of the generic interface for the container. @@ -843,7 +843,7 @@ a b c d a b c d e ``` -## set::generic_iterator (STL/CLR) +## `set::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -899,7 +899,7 @@ a b c a ``` -## set::generic_reverse_iterator (STL/CLR) +## `set::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -955,7 +955,7 @@ a b c c ``` -## set::generic_value (STL/CLR) +## `set::generic_value` The type of an element for use with the generic interface for the container. @@ -1009,7 +1009,7 @@ a b c a ``` -## set::insert (STL/CLR) +## `set::insert` Adds elements. @@ -1025,34 +1025,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1125,7 +1125,7 @@ a b c x a b c x y ``` -## set::iterator (STL/CLR) +## `set::iterator` The type of an iterator for the controlled sequence. @@ -1167,7 +1167,7 @@ int main() a b c ``` -## set::key_comp (STL/CLR) +## `set::key_comp` Copies the ordering delegate for two keys. @@ -1226,7 +1226,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## set::key_compare (STL/CLR) +## `set::key_compare` The ordering delegate for two keys. @@ -1286,7 +1286,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## set::key_type (STL/CLR) +## `set::key_type` The type of an ordering key. @@ -1298,7 +1298,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1331,7 +1331,7 @@ int main() a b c ``` -## set::lower_bound (STL/CLR) +## `set::lower_bound` Finds beginning of range that matches a specified key. @@ -1343,12 +1343,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1388,7 +1388,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## set::make_value (STL/CLR) +## `set::make_value` Constructs a value object. @@ -1400,12 +1400,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1434,7 +1434,7 @@ int main() a b c ``` -## set::operator= (STL/CLR) +## `set::operator=` Replaces the controlled sequence. @@ -1446,12 +1446,12 @@ set% operator=(set% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1489,7 +1489,7 @@ a b c a b c ``` -## set::rbegin (STL/CLR) +## `set::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1537,7 +1537,7 @@ a b c *++rbegin() = b ``` -## set::reference (STL/CLR) +## `set::reference` The type of a reference to an element. @@ -1582,7 +1582,7 @@ int main() a b c ``` -## set::rend (STL/CLR) +## `set::rend` Designates the end of the reversed controlled sequence. @@ -1631,7 +1631,7 @@ a b c *--rend() = a ``` -## set::reverse_iterator (STL/CLR) +## `set::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1673,7 +1673,7 @@ int main() c b a ``` -## set::set (STL/CLR) +## `set::set` Constructs a container object. @@ -1696,16 +1696,16 @@ set(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1720,19 +1720,19 @@ The constructor: `explicit set(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `set(set% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the set object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `set` object *`right`*, with the default ordering predicate. The constructor: `set(set^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the set object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `set` object *`right`*, with the default ordering predicate. The constructor: @@ -1744,19 +1744,19 @@ The constructor: `template set(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `set(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1844,7 +1844,7 @@ c b a a b c ``` -## set::size (STL/CLR) +## `set::size` Counts the number of elements. @@ -1856,7 +1856,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [set::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1898,9 +1898,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## set::size_type (STL/CLR) +## `set::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1946,7 +1946,7 @@ a b c end()-begin() = 3 ``` -## set::swap (STL/CLR) +## `set::swap` Swaps the contents of two containers. @@ -1958,12 +1958,12 @@ void swap(set% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2014,7 +2014,7 @@ d e f a b c ``` -## set::to_array (STL/CLR) +## `set::to_array` Copies the controlled sequence to a new array. @@ -2064,7 +2064,7 @@ a b c d a b c ``` -## set::upper_bound (STL/CLR) +## `set::upper_bound` Finds end of range that matches a specified key. @@ -2076,12 +2076,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2121,7 +2121,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## set::value_comp (STL/CLR) +## `set::value_comp` Copies the ordering delegate for two element values. @@ -2165,7 +2165,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## set::value_compare (STL/CLR) +## `set::value_compare` The ordering delegate for two element values. @@ -2210,7 +2210,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## set::value_type (STL/CLR) +## `set::value_type` The type of an element. @@ -2255,7 +2255,7 @@ int main() a b c ``` -## operator!= (set) (STL/CLR) +## `operator!=` (set) List not equal comparison. @@ -2269,15 +2269,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two sets are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two sets are compared element by element. ### Example @@ -2325,7 +2325,7 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (set) (STL/CLR) +## `operator<` (set) List less than comparison. @@ -2339,15 +2339,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two sets are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two sets are compared element by element. ### Example @@ -2395,7 +2395,7 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (set) (STL/CLR) +## `operator<=` (set) List less than or equal comparison. @@ -2409,15 +2409,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two sets are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two sets are compared element by element. ### Example @@ -2465,7 +2465,7 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (set) (STL/CLR) +## `operator==` (set) List equal comparison. @@ -2479,15 +2479,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two sets are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two sets are compared element by element. ### Example @@ -2535,7 +2535,7 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (set) (STL/CLR) +## `operator>` (set) List greater than comparison. @@ -2549,15 +2549,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two sets are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two sets are compared element by element. ### Example @@ -2605,7 +2605,7 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (set) (STL/CLR) +## `operator>=` (set) List greater than or equal comparison. @@ -2619,15 +2619,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two sets are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two sets are compared element by element. ### Example diff --git a/docs/dotnet/stack-stl-clr.md b/docs/dotnet/stack-stl-clr.md index 75ea0945df..c5fae0dceb 100644 --- a/docs/dotnet/stack-stl-clr.md +++ b/docs/dotnet/stack-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::stack", "cliext::stack::assign", "cliext::stack::const_re helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "stack class [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]", "assign member [STL/CLR]", "const_reference member [STL/CLR]", "container_type member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "generic_container member [STL/CLR]", "generic_value member [STL/CLR]", "get_container member [STL/CLR]", "operator= member [STL/CLR]", "pop member [STL/CLR]", "push member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "stack member [STL/CLR]", "to_array member [STL/CLR]", "top member [STL/CLR]", "top_item member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 6ee96b9f-8a33-4cf7-b7e0-6535c24bdefb --- -# stack (STL/CLR) +# `stack` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has last-in first-out access. You use the container adapter `stack` to manage an underlying container as a push-down stack. -In the description below, `GValue` is the same as *Value* unless the latter is a ref type, in which case it is `Value^`. Similarly, `GContainer` is the same as *Container* unless the latter is a ref type, in which case it is `Container^`. +In the description below, `GValue` is the same as *`Value`* unless the latter is a ref type, in which case it's `Value^`. Similarly, `GContainer` is the same as *`Container`* unless the latter is a ref type, in which case it's `Container^`. ## Syntax @@ -27,71 +27,71 @@ template +*`Value`*\ The type of an element in the controlled sequence. -*Container*
+*`Container`*\ The type of the underlying container. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[stack::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[stack::container_type (STL/CLR)](#container_type)|The type of the underlying container.| -|[stack::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[stack::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container adapter.| -|[stack::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container adapter.| -|[stack::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[stack::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[stack::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[stack::assign (STL/CLR)](#assign)|Replaces all elements.| -|[stack::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[stack::get_container (STL/CLR)](#get_container)|Accesses the underlying container.| -|[stack::pop (STL/CLR)](#pop)|Removes the last element.| -|[stack::push (STL/CLR)](#push)|Adds a new last element.| -|[stack::size (STL/CLR)](#size)|Counts the number of elements.| -|[stack::stack (STL/CLR)](#stack)|Constructs a container object.| -|[stack::top (STL/CLR)](#top)|Accesses the last element.| -|[stack::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| - -|Property|Description| -|--------------|-----------------| -|[stack::top_item (STL/CLR)](#top_item)|Accesses the last element.| - -|Operator|Description| -|--------------|-----------------| -|[stack::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (stack) (STL/CLR)](#op_neq)|Determines if a `stack` object is not equal to another `stack` object.| -|[operator< (stack) (STL/CLR)](#op_lt)|Determines if a `stack` object is less than another `stack` object.| -|[operator<= (stack) (STL/CLR)](#op_lteq)|Determines if a `stack` object is less than or equal to another `stack` object.| -|[operator== (stack) (STL/CLR)](#op_eq)|Determines if a `stack` object is equal to another `stack` object.| -|[operator> (stack) (STL/CLR)](#op_gt)|Determines if a `stack` object is greater than another `stack` object.| -|[operator>= (stack) (STL/CLR)](#op_gteq)|Determines if a `stack` object is greater than or equal to another `stack` object.| +| Type definition | Description | +|---|---| +| [`stack::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`stack::container_type`](#container_type) | The type of the underlying container. | +| [`stack::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`stack::generic_container`](#generic_container) | The type of the generic interface for the container adapter. | +| [`stack::generic_value`](#generic_value) | The type of an element for the generic interface for the container adapter. | +| [`stack::reference`](#reference) | The type of a reference to an element. | +| [`stack::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`stack::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`stack::assign`](#assign) | Replaces all elements. | +| [`stack::empty`](#empty) | Tests whether no elements are present. | +| [`stack::get_container`](#get_container) | Accesses the underlying container. | +| [`stack::pop`](#pop) | Removes the last element. | +| [`stack::push`](#push) | Adds a new last element. | +| [`stack::size`](#size) | Counts the number of elements. | +| [`stack::stack`](#stack) | Constructs a container object. | +| [`stack::top`](#top) | Accesses the last element. | +| [`stack::to_array`](#to_array) | Copies the controlled sequence to a new array. | + +| Property | Description | +|---|---| +| [`stack::top_item`](#top_item) | Accesses the last element. | + +| Operator | Description | +|---|---| +| [`stack::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (stack)](#op_neq) | Determines if a `stack` object isn't equal to another `stack` object. | +| [`operator<` (stack)](#op_lt) | Determines if a `stack` object is less than another `stack` object. | +| [`operator<=` (stack)](#op_lteq) | Determines if a `stack` object is less than or equal to another `stack` object. | +| [`operator==` (stack)](#op_eq) | Determines if a `stack` object is equal to another `stack` object. | +| [`operator>` (stack)](#op_gt) | Determines if a `stack` object is greater than another `stack` object. | +| [`operator>=` (stack)](#op_gteq) | Determines if a `stack` object is greater than or equal to another `stack` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -|IStack\|Maintain generic container adapter.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| `IStack` | Maintain generic container adapter. | ## Remarks -The object allocates and frees storage for the sequence it controls through an underlying container, of type *Container*, that stores *Value* elements and grows on demand. The object restricts access to pushing and popping just the last element, implementing a last-in first-out queue (also known as a LIFO queue, or stack). +The object allocates and frees storage for the sequence it controls through an underlying container of type *`Container`* that stores *`Value`* elements and grows on demand. The object restricts access to pushing and popping just the last element, implementing a last-in first-out queue (also known as a LIFO queue, or stack). ## Members -## stack::assign (STL/CLR) +## `stack::assign` Replaces all elements. @@ -103,7 +103,7 @@ void assign(stack% right); #### Parameters -*right*
+*`right`*\ Container adapter to insert. ### Remarks @@ -145,7 +145,7 @@ a b c a b c ``` -## stack::const_reference (STL/CLR) +## `stack::const_reference` The type of a constant reference to an element. @@ -189,7 +189,7 @@ int main() c b a ``` -## stack::container_type (STL/CLR) +## `stack::container_type` The type of the underlying container. @@ -201,7 +201,7 @@ typedef Container value_type; ### Remarks -The type is a synonym for the template parameter *Container*. +The type is a synonym for the template parameter *`Container`*. ### Example @@ -231,7 +231,7 @@ int main() a b c ``` -## stack::difference_type (STL/CLR) +## `stack::difference_type` The types of a signed distance between two elements. @@ -289,7 +289,7 @@ pushing 2 = -2 popping 3 = 3 ``` -## stack::empty (STL/CLR) +## `stack::empty` Tests whether no elements are present. @@ -301,7 +301,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [stack::size (STL/CLR)](#size)`() == 0`. You use it to test whether the stack is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `stack` is empty. ### Example @@ -343,7 +343,7 @@ size() = 0 empty() = True ``` -## stack::generic_container (STL/CLR) +## `stack::generic_container` The type of the generic interface for the container adapter. @@ -406,7 +406,7 @@ a b c d a b c d e ``` -## stack::generic_value (STL/CLR) +## `stack::generic_value` The type of an element for use with the generic interface for the container. @@ -464,7 +464,7 @@ a b c c b a ``` -## stack::get_container (STL/CLR) +## `stack::get_container` Accesses the underlying container. @@ -506,24 +506,24 @@ int main() a b c ``` -## stack::operator= (STL/CLR) +## `stack::operator=` Replaces the controlled sequence. ### Syntax ```cpp -stack % operator=(stack % right); +stack% operator=(stack% right); ``` #### Parameters -*right*
+*`right`*\ Container adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -560,7 +560,7 @@ a b c a b c ``` -## stack::pop (STL/CLR) +## `stack::pop` Removes the last element. @@ -572,7 +572,7 @@ void pop(); ### Remarks -The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the stack by one element at the back. +The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the `stack` by one element at the back. ### Example @@ -608,7 +608,7 @@ a b c a b ``` -## stack::push (STL/CLR) +## `stack::push` Adds a new last element. @@ -649,7 +649,7 @@ int main() a b c ``` -## stack::reference (STL/CLR) +## `stack::reference` The type of a reference to an element. @@ -698,7 +698,7 @@ a b c a b x ``` -## stack::size (STL/CLR) +## `stack::size` Counts the number of elements. @@ -710,7 +710,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [stack::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`stack::empty`](#empty). ### Example @@ -752,9 +752,9 @@ size() = 2 after popping size() = 4 after adding 2 ``` -## stack::size_type (STL/CLR) +## `stack::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -801,7 +801,7 @@ a b c size difference = 2 ``` -## stack::stack (STL/CLR) +## `stack::stack` Constructs a container adapter object. @@ -816,10 +816,10 @@ explicit stack(container_type% wrapped); #### Parameters -*right*
+*`right`*\ Object to copy. -*wrapped*
+*`wrapped`*\ Wrapped container to use. ### Remarks @@ -834,19 +834,19 @@ The constructor: `stack(stack% right);` -creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the stack object *right*. +creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `stack` object *`right`*. The constructor: `stack(stack^ right);` -creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the stack object `*right`. +creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `stack` object `*right`. The constructor: `explicit stack(container_type% wrapped);` -uses the existing container *wrapped* as the wrapped container. You use it to construct a stack from an existing container. +uses the existing container *`wrapped`* as the wrapped container. You use it to construct a `stack` from an existing container. ### Example @@ -894,7 +894,7 @@ x x x x x x x x x x ``` -## stack::to_array (STL/CLR) +## `stack::to_array` Copies the controlled sequence to a new array. @@ -944,7 +944,7 @@ a b c d a b c ``` -## stack::top (STL/CLR) +## `stack::top` Accesses the last element. @@ -956,7 +956,7 @@ reference top(); ### Remarks -The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know it exists. +The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know one exists. ### Example @@ -996,7 +996,7 @@ top() = c a b x ``` -## stack::top_item (STL/CLR) +## `stack::top_item` Accesses the last element. @@ -1008,7 +1008,7 @@ property value_type top_item; ### Remarks -The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know it exists. +The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know one exists. ### Example @@ -1048,7 +1048,7 @@ top_item = c a b x ``` -## stack::value_type (STL/CLR) +## `stack::value_type` The type of an element. @@ -1060,7 +1060,7 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*. +The type is a synonym for the template parameter *`Value`*. ### Example @@ -1093,9 +1093,9 @@ int main() c b a ``` -## operator!= (stack) (STL/CLR) +## `operator!=` (stack) -Stack not equal comparison. +`Stack` not equal comparison. ### Syntax @@ -1108,15 +1108,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two stacks are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two stacks are compared element by element. ### Example @@ -1164,9 +1164,9 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (stack) (STL/CLR) +## `operator<` (stack) -Stack less than comparison. +`Stack` less than comparison. ### Syntax @@ -1179,15 +1179,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->`[stack::size (STL/CLR)](#size)`() <` `right->size()` You use it to test whether *left* is ordered before *right* when the two stacks are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two stacks are compared element by element. ### Example @@ -1235,9 +1235,9 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (stack) (STL/CLR) +## `operator<=` (stack) -Stack less than or equal comparison. +`Stack` less than or equal comparison. ### Syntax @@ -1250,15 +1250,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two stacks are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two stacks are compared element by element. ### Example @@ -1306,9 +1306,9 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (stack) (STL/CLR) +## `operator==` (stack) -Stack equal comparison. +`Stack` equal comparison. ### Syntax @@ -1321,15 +1321,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two stacks are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two stacks are compared element by element. ### Example @@ -1377,9 +1377,9 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (stack) (STL/CLR) +## `operator>` (stack) -Stack greater than comparison. +`Stack` greater than comparison. ### Syntax @@ -1392,15 +1392,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two stacks are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two stacks are compared element by element. ### Example @@ -1448,9 +1448,9 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (stack) (STL/CLR) +## `operator>=` (stack) -Stack greater than or equal comparison. +`Stack` greater than or equal comparison. ### Syntax @@ -1463,15 +1463,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two stacks are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two stacks are compared element by element. ### Example diff --git a/docs/dotnet/user-defined-operators-cpp-cli.md b/docs/dotnet/user-defined-operators-cpp-cli.md index ec068e65ec..984a75eb85 100644 --- a/docs/dotnet/user-defined-operators-cpp-cli.md +++ b/docs/dotnet/user-defined-operators-cpp-cli.md @@ -53,8 +53,8 @@ You can define the following operators: |^|Binary| |false|Unary| |true|Unary| -|||Binary| -||||Binary| +| `|` | Binary | +| `||` | Binary | |~|Unary| ## Example: User-defined operators diff --git a/docs/dotnet/utility-stl-clr.md b/docs/dotnet/utility-stl-clr.md index 40ae39d5ee..d014d1fc08 100644 --- a/docs/dotnet/utility-stl-clr.md +++ b/docs/dotnet/utility-stl-clr.md @@ -7,42 +7,42 @@ f1_keywords: ["", "cliext::pair", "cliext::pair::pair", "cliext: helpviewer_keywords: [" header [STL/CLR]", "utility header [STL/CLR]", " header [STL/CLR]", "first member [STL/CLR]", "first_type member [STL/CLR]", "second member [STL/CLR]", "second_type member [STL/CLR]", "swap member [STL/CLR]", "make_pair function [STL/CLR]", "pair class [STL/CLR]", "pair member [STL/CLR]", "operator== member [STL/CLR]", "operator= member [STL/CLR]", "operator>= member [STL/CLR]", "operator> member [STL/CLR]", "operator!= member [STL/CLR]", "operator<= member [STL/CLR]", "operator< member [STL/CLR]"] ms.assetid: fb48cb75-d5ef-47ce-b526-bf60dc86c552 --- -# utility (STL/CLR) +# `` (STL/CLR) -Include the STL/CLR header `` to define the template class `pair` and several supporting template functions. +Include the STL/CLR header `` to define the class template `pair` and several supporting function templates. ## Syntax ```cpp -#include +#include ``` ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Class|Description| -|-----------|-----------------| -|[pair (STL/CLR)](#pair)|Wrap a pair of elements.| +| Class | Description | +|---|---| +| [`pair`](#pair) | Wrap a pair of elements. | -|Operator|Description| -|--------------|-----------------| -|[operator== (pair) (STL/CLR)](#op_eq)|Pair equal comparison.| -|[operator!= (pair) (STL/CLR)](#op_neq)|Pair not equal comparison.| -|[operator< (pair) (STL/CLR)](#op_lt)|Pair less than comparison.| -|[operator\<= (pair) (STL/CLR)](#op_lteq)|Pair less than or equal comparison.| -|[operator> (pair) (STL/CLR)](#op_gt)|Pair greater than comparison.| -|[operator>= (pair) (STL/CLR)](#op_gteq)|Pair greater than or equal comparison.| +| Operator | Description | +|---|---| +| [`operator==` (pair)](#op_eq) | `pair` equal comparison. | +| [`operator!=` (pair)](#op_neq) | `pair` not equal comparison. | +| [`operator<` (pair)](#op_lt) | `pair` less than comparison. | +| [`operator<=` (pair)](#op_lteq) | `pair` less than or equal comparison. | +| [`operator>` (pair)](#op_gt) | `pair` greater than comparison. | +| [`operator>=` (pair)](#op_gteq) | `pair` greater than or equal comparison. | -|Function|Description| -|--------------|-----------------| -|[make_pair (STL/CLR)](#make_pair)|Make a pair from a pair of values.| +| Function | Description | +|---|---| +| [`make_pair`](#make_pair) | Make a `pair` from a pair of values. | -## pair (STL/CLR) +## `pair` The template class describes an object that wraps a pair of values. @@ -56,38 +56,38 @@ template +*`Value1`*\ The type of first wrapped value. -*Value2*
+*`Value2`*\ The type of second wrapped value. ## Members -|Type Definition|Description| -|---------------------|-----------------| -|[pair::first_type (STL/CLR)](#first_type)|The type of the first wrapped value.| -|[pair::second_type (STL/CLR)](#second_type)|The type of the second wrapped value.| +| Type definition | Description | +|---|---| +| [`pair::first_type`](#first_type) | The type of the first wrapped value. | +| [`pair::second_type`](#second_type) | The type of the second wrapped value. | -|Member Object|Description| -|-------------------|-----------------| -|[pair::first (STL/CLR)](#first)|The first stored value.| -|[pair::second (STL/CLR)](#second)|The second stored value.| +| Member object | Description | +|---|---| +| [`pair::first`](#first) | The first stored value. | +| [`pair::second`](#second) | The second stored value. | -|Member Function|Description| -|---------------------|-----------------| -|[pair::pair (STL/CLR)](#pair_pair)|Constructs a pair object.| -|[pair::swap (STL/CLR)](#swap)|Swaps the contents of two pairs.| +| Member function | Description | +|---|---| +| [`pair::pair`](#pair_pair) | Constructs a `pair` object. | +| [`pair::swap`](#swap) | Swaps the contents of two `pair` objects. | -|Operator|Description| -|--------------|-----------------| -|[pair::operator= (STL/CLR)](#op_as)|Replaces the stored pair of values.| +| Operator | Description | +|---|---| +| [`pair::operator=`](#op_as) | Replaces the stored pair of values. | ## Remarks The object stores a pair of values. You use this template class to combine two values into a single object. Also, the object `cliext::pair` (described here) stores only managed types; to store a pair of unmanaged types use `std::pair`, declared in ``. -## pair::first (STL/CLR) +## `pair::first` The first wrapped value. @@ -124,7 +124,7 @@ int main() [x, 3] ``` -## pair::first_type (STL/CLR) +## `pair::first_type` The type of the first wrapped value. @@ -136,7 +136,7 @@ typedef Value1 first_type; ### Remarks -The type is a synonym for the template parameter *Value1*. +The type is a synonym for the template parameter *`Value1`*. ### Example @@ -161,7 +161,7 @@ int main() [x, 3] ``` -## pair::operator= (STL/CLR) +## `pair::operator=` Replaces the stored pair of values. @@ -173,12 +173,12 @@ pair% operator=(pair% right); #### Parameters -*right*
-Pair to copy. +*`right`*\ +`pair` to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored pair of values with a copy of the stored pair of values in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored pair of values with a copy of the stored pair of values in *`right`*. ### Example @@ -205,9 +205,9 @@ int main() [x, 3] ``` -## pair::pair (STL/CLR) +## `pair::pair` -Constructs a pair object. +Constructs a `pair` object. ### Syntax @@ -220,13 +220,13 @@ pair(Value1 val1, Value2 val2); #### Parameters -*right*
-Pair to store. +*`right`*\ +`pair` to store. -*val1*
+*`val1`*\ First value to store. -*val2*
+*`val2`*\ Second value to store. ### Remarks @@ -241,17 +241,17 @@ The constructor: `pair(pair% right);` -initializes the stored pair with `right.`[pair::first (STL/CLR)](#first) and `right.`[pair::second (STL/CLR)](#second). +initializes the stored pair with `right.first` and `right.second`. `pair(pair^ right);` -initializes the stored pair with `right->`[pair::first (STL/CLR)](#first) and `right>`[pair::second (STL/CLR)](#second). +initializes the stored pair with `right->first` and `right->second`. The constructor: `pair(Value1 val1, Value2 val2);` -initializes the stored pair with *val1* and *val2*. +initializes the stored pair with *`val1`* and *`val2`*. ### Example @@ -290,7 +290,7 @@ int main() [x, 3] ``` -## pair::second (STL/CLR) +## `pair::second` The second wrapped value. @@ -327,7 +327,7 @@ int main() [x, 3] ``` -## pair::second_type (STL/CLR) +## `pair::second_type` The type of the second wrapped value. @@ -339,7 +339,7 @@ typedef Value2 second_type; ### Remarks -The type is a synonym for the template parameter *Value2*. +The type is a synonym for the template parameter *`Value2`*. ### Example @@ -364,9 +364,9 @@ int main() [x, 3] ``` -## pair::swap (STL/CLR) +## `pair::swap` -Swaps the contents of two pairs. +Swaps the contents of two `pair` objects. ### Syntax @@ -376,12 +376,12 @@ void swap(pair% right); #### Parameters -*right*
-Pair to swap contents with. +*`right`*\ +`pair` to swap contents with. ### Remarks -The member function swaps the stored pair of values between **`*this`** and *right*. +The member function swaps the stored pair of values between **`*this`** and *`right`*. ### Example @@ -433,7 +433,7 @@ x x x x x a b c ``` -## make_pair (STL/CLR) +## `make_pair` Make a `pair` from a pair of values. @@ -447,21 +447,21 @@ template +*`Value1`*\ The type of the first wrapped value. -*Value2*
+*`Value2`*\ The type of the second wrapped value. -*first*
+*`first`*\ First value to wrap. -*second*
+*`second`*\ Second value to wrap. ### Remarks -The template function returns `pair(first, second)`. You use it to construct a `pair` object from a pair of values. +The function template returns `pair(first, second)`. You use it to construct a `pair` object from a pair of values. ### Example @@ -486,9 +486,9 @@ int main() [y, 4] ``` -## operator!= (pair) (STL/CLR) +## `operator!=` (pair) -Pair not equal comparison. +`pair` not equal comparison. ### Syntax @@ -501,15 +501,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two pairs are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two `pair` objects are compared element by element. ### Example @@ -540,9 +540,9 @@ int main() [x 3] != [x 4] is True ``` -## `operator<` (pair) (STL/CLR) +## `operator<` -Pair less than comparison. +`pair` less than comparison. ### Syntax @@ -555,15 +555,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `left.first <` `right.first || !(right.first <` `left.first &&` `left.second <` `right.second`. You use it to test whether *left* is ordered the before *right* when the two pairs are compared element by element. +The operator function returns `left.first < right.first || !(right.first < left.first && left.second < right.second`. You use it to test whether *`left`* is ordered the before *`right`* when the two `pair` objects are compared element by element. ### Example @@ -594,9 +594,9 @@ int main() [x 3] < [x 4] is True ``` -## `operator<=` (pair) (STL/CLR) +## `operator<=` -Pair less than or equal comparison. +`pair` less than or equal comparison. ### Syntax @@ -609,15 +609,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two pairs are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two `pair` objects are compared element by element. ### Example @@ -648,9 +648,9 @@ int main() [x 4] <= [x 3] is False ``` -## operator== (pair) (STL/CLR) +## `operator==` -Pair equal comparison. +`pair` equal comparison. ### Syntax @@ -663,15 +663,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `left.first ==` `right.first &&` `left.second ==` `right.second`. You use it to test whether *left* is ordered the same as *right* when the two pairs are compared element by element. +The operator function returns `left.first == right.first && left.second == right.second`. You use it to test whether *`left`* is ordered the same as *`right`* when the two `pair` objects are compared element by element. ### Example @@ -702,9 +702,9 @@ int main() [x 3] == [x 4] is False ``` -## `operator>` (pair) (STL/CLR) +## `pair::operator>` -Pair greater than comparison. +`pair` greater than comparison. ### Syntax @@ -717,15 +717,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two pairs are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two `pair` objects are compared element by element. ### Example @@ -756,9 +756,9 @@ int main() [x 4] > [x 3] is True ``` -## `operator>=` (pair) (STL/CLR) +## `operator>=` -Pair greater than or equal comparison. +`pair` greater than or equal comparison. ### Syntax @@ -771,15 +771,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two pairs are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two `pair` objects are compared element by element. ### Example diff --git a/docs/dotnet/vector-stl-clr.md b/docs/dotnet/vector-stl-clr.md index d325c77397..c6c3fd953c 100644 --- a/docs/dotnet/vector-stl-clr.md +++ b/docs/dotnet/vector-stl-clr.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: vector (STL/CLR)" title: "vector (STL/CLR)" +description: "Learn more about: vector (STL/CLR)" ms.date: "11/04/2016" ms.topic: "reference" f1_keywords: ["cliext::vector", "cliext::vector::assign", "cliext::vector::at", "cliext::vector::back", "cliext::vector::back_item", "cliext::vector::begin", "cliext::vector::capacity", "cliext::vector::clear", "cliext::vector::const_iterator", "cliext::vector::const_reference", "cliext::vector::const_reverse_iterator", "cliext::vector::difference_type", "cliext::vector::empty", "cliext::vector::end", "cliext::vector::erase", "cliext::vector::front", "cliext::vector::front_item", "cliext::vector::generic_container", "cliext::vector::generic_iterator", "cliext::vector::generic_reverse_iterator", "cliext::vector::generic_value", "cliext::vector::insert", "cliext::vector::iterator", "cliext::vector::operator=", "cliext::vector::operator", "cliext::vector::pop_back", "cliext::vector::push_back", "cliext::vector::rbegin", "cliext::vector::reference", "cliext::vector::rend", "cliext::vector::reserve", "cliext::vector::resize", "cliext::vector::reverse_iterator", "cliext::vector::size", "cliext::vector::size_type", "cliext::vector::swap", "cliext::vector::to_array", "cliext::vector::value_type", "cliext::vector::vector"] helpviewer_keywords: ["vector class [STL/CLR]", " header [STL/CLR]", " header [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> (vector) member [STL/CLR]", "operator>= member [STL/CLR]", "assign member [STL/CLR]", "at member [STL/CLR]", "back member [STL/CLR]", "back_item member [STL/CLR]", "begin member [STL/CLR]", "capacity member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "erase member [STL/CLR]", "front member [STL/CLR]", "front_item member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "pop_back member [STL/CLR]", "push_back member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reserve member [STL/CLR]", "resize member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "value_type member [STL/CLR]", "vector member [STL/CLR]"] -ms.assetid: f90060d5-097a-4e9d-9a26-a634b5b9c6c2 --- # vector (STL/CLR) @@ -608,7 +607,7 @@ a b c ## vector::const_reverse_iterator (STL/CLR) -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax diff --git a/docs/dotnet/walkthrough-compiling-a-cpp-program-that-targets-the-clr-in-visual-studio.md b/docs/dotnet/walkthrough-compiling-a-cpp-program-that-targets-the-clr-in-visual-studio.md index a07c0032fc..89be33ea73 100644 --- a/docs/dotnet/walkthrough-compiling-a-cpp-program-that-targets-the-clr-in-visual-studio.md +++ b/docs/dotnet/walkthrough-compiling-a-cpp-program-that-targets-the-clr-in-visual-studio.md @@ -26,7 +26,7 @@ The following steps vary depending on which version of Visual Studio you are usi 1. In **Solution Explorer**, right-click on the top to open the **Create a New Project** dialog box. -1. At the top of the dialog, type **CLR** in the search box and then choose **CLR Empty Project** from the results list. +1. At the top of the dialog, type **CLR** in the search box and then choose **CLR Empty Project (.NET Framework)** from the results list. 1. Choose the **Create** button to create the project. diff --git a/docs/embedded/download-and-install-the-embedded-tooling.md b/docs/embedded/download-and-install-the-embedded-tooling.md new file mode 100644 index 0000000000..a445146308 --- /dev/null +++ b/docs/embedded/download-and-install-the-embedded-tooling.md @@ -0,0 +1,59 @@ +--- +title: "Install the Embedded tooling in Visual Studio and Visual Studio Code" +description: "How to download and install the Embedded tooling in Visual Studio and Visual Studio Code." +ms.date: "07/12/2022" +ms.custom: intro-installation +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- + +# Download and install the Embedded tooling + +# [Visual Studio](#tab/visual-studio) + +In Visual Studio 2022 and later versions, you can use the Visual Studio IDE on Windows to edit and debug embedded projects. Use tools such as the [Peripheral View](./peripheral-view.md), [RTOS View](./rtos-view.md), and the [Serial Monitor](./serial-monitor.md) to help interact with and debug your embedded projects. + +To use the embedded development tools in Visual Studio, you must install the required **Linux and embedded development with C++** workload. + +## To install the Linux and embedded development with C++ workload + +1. Enter "Visual Studio Installer" in the Windows search box: + + ![Screenshot showing the Windows search box.](../linux/media/visual-studio-installer-search.png) + +1. Open the Visual Studio Installer. In Visual Studio Installer, choose **Modify** next to your installation of Visual Studio, and then select the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux and embedded development with C++** workload. + + ![Screenshot showing the Visual C++ for Linux Development workload item in Visual Studio Installer.](media/linux-and-embedded-workload.png) + +1. Choose **Modify** to continue with the installation. + +When installation completes, you're ready to use Visual Studio for embedded development. + +# [Visual Studio Code](#tab/visual-studio-code) + +## Install the Embedded extensions in Visual Studio Code + +Microsoft provides an extension to Visual Studio Code that lets you use embedded tools such as a [Peripheral View](./peripheral-view.md), [RTOS View](./rtos-view.md), and a [Serial Monitor](./serial-monitor.md). Now you can use Microsoft tools to help debug your Linux-based embedded applications. + +## To install the embedded extensions for Visual Studio Code + +1. Enter "Visual Studio Code" in the Windows search box: + + ![Search-Visual-Studio-Code](media/windows-search-vscode.png) + +1. Open Visual Studio Code. In Visual Studio Code, open the **Extensions Pane**. + + ![Visual Studio Code Extensions Pane](media/extensions-pane.png) + +1. Search for and install the [Embedded Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-embedded-tools) extension. + + ![Embedded Tools extension](media/embedded-tools-extension.png) + +1. Search for and install the [Serial Monitor](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-serial-monitor) extension. + + ![Serial Monitor extension](media/serial-monitor-extension.png) + +When installation completes, you're ready to use Visual Studio Code for embedded development. + +--- diff --git a/docs/embedded/index.yml b/docs/embedded/index.yml new file mode 100644 index 0000000000..61a779727b --- /dev/null +++ b/docs/embedded/index.yml @@ -0,0 +1,59 @@ +### YamlMime:Landing +title: Embedded development with C++ | Create and debug embedded applications # < 60 chars +summary: Use Embedded tooling in Visual Studio 2022 and later to create and debug applications for Embedded. # < 160 chars + +metadata: + title: Embedded development with C++ + description: Learn how to use Embedded tooling in Visual Studio and Visual Studio Code to create and debug applications for Linux. + ms.topic: landing-page + author: gcampbell-msft + ms.author: gcampbell + ms.date: 07/12/2022 + ms.custom: intro-landing-hub + monikerRange: '>=msvc-170' + +# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new + +landingContent: +# Cards and links should be based on top customer tasks or top subjects +# Start card title with a verb + + # Card + - title: Build and debug embedded projects in Visual Studio and Visual Studio Code + linkLists: + - linkListType: get-started + links: + - text: Download the Embedded workload in Visual Studio and Visual Studio Code + url: download-and-install-the-embedded-tooling.md + - linkListType: how-to-guide + links: + - text: Getting started guides + url: https://github.com/azure-rtos/getting-started + - linkListType: tutorial + links: + - text: Embedded Software Development in Visual Studio + url: https://devblogs.microsoft.com/cppblog/visual-studio-embedded-development/ + - text: Embedded Software Development in Visual Studio Code + url: https://devblogs.microsoft.com/cppblog/vscode-embedded-development/ + - linkListType: whats-new + links: + - text: Zephyr support in Visual Studio and Visual Studio Code + url: https://devblogs.microsoft.com/cppblog/serial-and-zephyr-support/ + + - title: Embedded Tooling in Visual Studio and Visual Studio Code + linkLists: + - linkListType: reference + links: + - text: Peripheral View + url: ./peripheral-view.md + - text: RTOS View + url: ./rtos-view.md + - text: Serial Monitor + url: ./serial-monitor.md + + - title: More embedded tools + linkLists: + - linkListType: whats-new + links: + - text: Bootstrap your development environment + url: https://devblogs.microsoft.com/cppblog/vcpkg-artifacts/ diff --git a/docs/embedded/media/embedded-tools-extension.png b/docs/embedded/media/embedded-tools-extension.png new file mode 100644 index 0000000000..bc02e3316c Binary files /dev/null and b/docs/embedded/media/embedded-tools-extension.png differ diff --git a/docs/embedded/media/extensions-pane.png b/docs/embedded/media/extensions-pane.png new file mode 100644 index 0000000000..dce8de909a Binary files /dev/null and b/docs/embedded/media/extensions-pane.png differ diff --git a/docs/embedded/media/linux-and-embedded-workload.png b/docs/embedded/media/linux-and-embedded-workload.png new file mode 100644 index 0000000000..72773c34ea Binary files /dev/null and b/docs/embedded/media/linux-and-embedded-workload.png differ diff --git a/docs/embedded/media/peripheral-view-vscode.png b/docs/embedded/media/peripheral-view-vscode.png new file mode 100644 index 0000000000..0ce79cd438 Binary files /dev/null and b/docs/embedded/media/peripheral-view-vscode.png differ diff --git a/docs/embedded/media/peripheral-view.png b/docs/embedded/media/peripheral-view.png new file mode 100644 index 0000000000..49d5127bf9 Binary files /dev/null and b/docs/embedded/media/peripheral-view.png differ diff --git a/docs/embedded/media/rtos-threads-vscode.png b/docs/embedded/media/rtos-threads-vscode.png new file mode 100644 index 0000000000..cb111aae0c Binary files /dev/null and b/docs/embedded/media/rtos-threads-vscode.png differ diff --git a/docs/embedded/media/rtos-threads.png b/docs/embedded/media/rtos-threads.png new file mode 100644 index 0000000000..b9adaf0e80 Binary files /dev/null and b/docs/embedded/media/rtos-threads.png differ diff --git a/docs/embedded/media/serial-monitor-extension.png b/docs/embedded/media/serial-monitor-extension.png new file mode 100644 index 0000000000..966d40ed81 Binary files /dev/null and b/docs/embedded/media/serial-monitor-extension.png differ diff --git a/docs/embedded/media/serial-monitor-vscode-tcp.png b/docs/embedded/media/serial-monitor-vscode-tcp.png new file mode 100644 index 0000000000..c1c6ae0e21 Binary files /dev/null and b/docs/embedded/media/serial-monitor-vscode-tcp.png differ diff --git a/docs/embedded/media/serial-monitor-vscode.png b/docs/embedded/media/serial-monitor-vscode.png new file mode 100644 index 0000000000..29a6c931e1 Binary files /dev/null and b/docs/embedded/media/serial-monitor-vscode.png differ diff --git a/docs/embedded/media/serial-monitor.png b/docs/embedded/media/serial-monitor.png new file mode 100644 index 0000000000..e247eef5e7 Binary files /dev/null and b/docs/embedded/media/serial-monitor.png differ diff --git a/docs/embedded/media/windows-search-vscode.png b/docs/embedded/media/windows-search-vscode.png new file mode 100644 index 0000000000..7374e0953c Binary files /dev/null and b/docs/embedded/media/windows-search-vscode.png differ diff --git a/docs/embedded/peripheral-view.md b/docs/embedded/peripheral-view.md new file mode 100644 index 0000000000..900dbec762 --- /dev/null +++ b/docs/embedded/peripheral-view.md @@ -0,0 +1,33 @@ +--- +title: "Peripheral View" +ms.date: "07/12/2022" +description: "Peripheral View that allows users to view and manipulate peripherals." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# Peripheral View + +## Overview + +The Peripheral View allows embedded developers to view and manipulate registers and peripherals defined in SVD (System View Description) files while debugging. + +# [Visual Studio](#tab/visual-studio) + +![Screenshot of the Peripheral View in VS.](media/peripheral-view.png) + +# [Visual Studio Code](#tab/visual-studio-code) + +![Screenshot of the Peripheral View in Visual Studio Code.](media/peripheral-view-vscode.png) + +--- + +## Capabilities + +| Capability | Description | Instructions | Keyboard shortcuts | +|--|--|--|--| +| Navigate peripherals | Navigate the peripheral tree view by collapsing and expanding components in the tree view. | Scroll to view all of the peripherals. Select the caret on each item to expand or collapse the view. | Use the **Up** or **Down** arrow keys to scroll. Use the **Left** and **Right** arrow keys to expand or collapse the view. | +| Edit peripheral values | Modify writeable peripheral values. | Select the peripheral value to edit. Use the **Enter** key to submit that value. | Use the **F2** key to edit, **Esc** to cancel editing, and **Enter** to submit edits. | +| Access memory | View the memory locations of peripherals. | Select the linked memory addresses to view. | Use **Tab** to select the link, and **Enter** to navigate to the link. | +| Pin peripherals | Pin important peripherals to the top of the view. | Select the pin icon to pin or unpin peripherals. | Use **Tab** to select the pin icon, and **Enter** to pin or unpin it. | +| Search for peripherals | Search for peripherals that you have specific interest in | Type text into the search bar. | See **Instructions** column. | diff --git a/docs/embedded/rtos-view.md b/docs/embedded/rtos-view.md new file mode 100644 index 0000000000..e5e9b7da9b --- /dev/null +++ b/docs/embedded/rtos-view.md @@ -0,0 +1,81 @@ +--- +title: "RTOS Object Views" +ms.date: "07/12/2022" +description: "RTOS View that allows users to view RTOS data of their application." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# RTOS (Real time operating system) Object View + +## Overview + +The RTOS Object View allows users to view various components of an RTOS while debugging their application. + +# [Visual Studio](#tab/visual-studio) + +![RTOS View in VS](media/rtos-threads.png) + +# [Visual Studio Code](#tab/visual-studio-code) + +![RTOS View in VS Code](media/rtos-threads-vscode.png) + +--- + +## Supported RTOSes and their supported object types + +- Azure RTOS (ThreadX) + - Block pools + - Byte pools + - Event flags + - Mutexes + - Queues + - Semaphores + - Threads + - Timers +- FreeRTOS + - Queues + - Threads +- Zephyr + - Mailboxes + - Memory slabs + - Message queues + - Mutexes + - Pipes + - Queues + - Semaphores + - Stacks + - Threads + - Timers + +## Usage + +Use the RTOS Object View to: + +- Access memory locations of various objects. +- Access thread variables or various objects in the Watch view. + +Use the arrow keys to select objects within the view. Use the **Enter** key to navigate to the linked content. + +## Configuring an embedded application for the RTOS view + +The RTOS Object View will attempt to automatically display information, but setting certain build flags can allow the RTOS Object View to display additional details. The build flags are specific to the RTOS being used. The exact mechanism used to set these flags varies depending on the build system used by the project. Consult your RTOS and build system documentation for more details. + +### Azure RTOS (ThreadX) + +All features should work by default. + +### FreeRTOS + +- Thread base priority is only available if `configUSE_MUTEXES` is enabled. +- Thread run count is only available if `configGENERATE_RUN_TIME_STATS` is enabled. +- The end address of a thread's stack space is only available if `portSTACK_GROWTH` or `configRECORD_STACK_HIGH_ADDRESS` are enabled. +- The thread list will be retrieved faster if `configMAX_PRIORITIES` is set to the lowest possible value that still satisfies the application's requirements. + +### Zephyr + +- All thread information is only available if `CONFIG_DEBUG_THREAD_INFO` is enabled. +- Thread stack usage is only available if `CONFIG_INIT_STACKS` and `CONFIG_THREAD_STACK_INFO` are enabled. +- For all object types other than threads, information is only available if `CONFIG_TRACING` and `CONFIG_TRACING_OBJECT_TRACKING` are enabled. +- The maximum usage of a memory slab is only available if `CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION` is enabled. +- The list of threads waiting on an object is only available if `CONFIG_WAITQ_SCALABLE` is disabled. diff --git a/docs/embedded/serial-monitor.md b/docs/embedded/serial-monitor.md new file mode 100644 index 0000000000..6ec62acf7e --- /dev/null +++ b/docs/embedded/serial-monitor.md @@ -0,0 +1,89 @@ +--- +title: "Serial Monitor" +ms.date: "07/12/2022" +description: "Serial Monitor allows users to configure, monitor, and communicate with serial ports." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# Serial Monitor + +## Overview + +The Serial Monitor allows users to configure, monitor, and communicate with serial ports. + +# [Visual Studio](#tab/visual-studio) + +:::image type="complex" source="./media/serial-monitor.png" alt-text="Screenshot of the Visual Studio Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (serial), Port (virtual COM port COM3), baud rate (115200), line ending (None), and a Stop monitoring button. The bottom section shows the messages, consisting of four lines of the text Hello, World! +:::image-end::: + +## Capabilities + +- **Monitor a serial port**: Choose the **Start Monitoring** or **Stop Monitoring** button to control whether to monitor data coming from the port. +- **Send data to a serial port**: Enter text into the text field at the bottom of the view. Use the **Enter** key or choose the **Send Message** arrow button to send the data. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). +- **Configure Serial Monitor and port connection settings**: See the following table to learn about the settings that the Serial Monitor provides. + +## Configurable settings + +| Settings | Description | Usage | Available options | +|--|--|--|--| +| **Port** | Ports that are actively connected to a device | Use the **Port** dropdown | Serial port compatible devices connected to the machine | +| **Baud Rate** | Frequency at which the monitor attempts to communicate with the connected device | Use the **Baud Rate** dropdown | 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230000, 250000 | +| **Line Ending** | The line ending to use in messages sent to the connected device | Use the **Line Ending** dropdown | None, LF, CR, CRLF | +| **Timestamp** | Adds timestamps to the output of data received from the connected port | Use the **timestamp** toggle button | On/Off | +| **Autoscroll** | Whether to auto-scroll new content that comes from the connected port | Use the **autoscroll** toggle button | On/Off | +| **Automatic Reconnection** | Allows for automatic reconnection and monitoring of disconnected selected ports | Use the **automatic reconnection** toggle button in **Serial** mode | On/Off | +| **Message Encoding** | Can select type of encoding for messages sent to serial port | Use the **message encoding** dropdown in **Serial** mode | Text (utf8), Hex, Binary | +| **Data bits** | Can select how many data bits are used for the serial port connection | Use the **Data bits** dropdown in the **additional settings** | 5, 6, 7, 8 | +| **Stop bits** | Can select how many stop bits are used for the serial port connection | Use the **Stop bits** dropdown in the **additional settings** | 1, 1.5, 2 | +| **Parity** | Can select what parity is used for the serial port connection | Use the **Parity** dropdown in the **additional settings** | None, Odd, Even, Mark, Space | +| **File Logging** | Allows the ability to log output to a file | Use the **file logging** toggle button, as well as the **Choose Log File Directory** button to choose the desired directory in the **additional settings** | On/Off | + +# [Visual Studio Code](#tab/visual-studio-code) + +:::image type="complex" source="./media/serial-monitor-vscode.png" alt-text="Screenshot of the VS Code Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (serial), Port (virtual COM port COM3), baud rate (115200), line ending (None), and a Stop monitoring button. The bottom section where messages are displayed is empty. +:::image-end::: + +:::image type="complex" source="./media/serial-monitor-vscode-tcp.png" alt-text="Screenshot of the VS Code TCP Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (TCP), Host (::1), Port (1234), and a Start monitoring button. The bottom section shows the messages, starting with "Opening the TCP connection on ::1:1234. Then Connected to ::1:1234. Then five lines of the text Hello, World!. Then Closed the TCP connection ::1:1234. +:::image-end::: + +## Capabilities + +- **Toggle the serial monitor mode**: Choose **Serial** or **TCP** from the **Monitor Mode** dropdown. +- **Monitor a serial/tcp port**: Choose the **Start Monitoring** or **Stop Monitoring** button to control whether to monitor data coming from the port. +- **Monitor multiple serial/tcp ports at a time**: Press the **Open an additional Monitor** button to open another monitor. +- **Send data to a serial/tcp port**: Enter text into the text field at the bottom of the view. Use the **Enter** key or choose the **Send Message** arrow button to send the data. When sending hex or binary data, bytes are automatically separated by spaces. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). +- **Configure Serial Monitor and connection settings**: See the following table to learn about the settings that the Serial Monitor provides. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). + +## Configurable settings + +| Settings | Description | Usage | Available options | +|--|--|--|--| +| **Port** | Ports that are actively connected to a device | Use the **Port** dropdown in **Serial** mode | Serial port compatible devices connected to the machine | +| **Baud Rate** | Frequency at which the monitor attempts to communicate with the connected device | Use the **Baud Rate** dropdown in **Serial** mode | 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230000, 250000 | +| **Host** | Name of your host address | Use the **Host** text box to enter your host name in **TCP** mode | Any string that matches a valid host | +| **Port** | The port number of your address | Use the **Port** text box in **TCP** mode | Any valid TCP port | +| **Line Ending** | The line ending to use in messages sent to the connected device | Use the **Line Ending** dropdown in **Serial** mode | None, LF, CR, CRLF | +| **DTR** | Allows the DTR COM output line to be manually set | Use the **DTR** checkbox | True/False | +| **RTS** | Allows the RTS COM output line to be manually set | Use the **RTS** checkbox | True/False | +| **Timestamp** | Adds timestamps to the output of data received from the connected port | Use the **timestamp** toggle button | On/Off | +| **Autoscroll** | Whether to auto-scroll new content that comes from the connected port | Use the **autoscroll** toggle button | On/Off | +| **Automatic Reconnection** | Allows for automatic reconnection and monitoring of disconnected selected ports | Use the **automatic reconnection** toggle button | On/Off| +| **Message Echoing** | Allows the ability to echo/not echo messages you send | Use the **message echoing** toggle button | On/Off | +| **Message Encoding** | Can select type of encoding for messages sent to serial port | Use the **message encoding** dropdown | Text (utf8), Hex, Binary | +| **Data bits** | Can select how many data bits are used for the serial port connection | Use the **Data bits** dropdown in the **additional settings** | 5, 6, 7, 8 | +| **Stop bits** | Can select how many stop bits are used for the serial port connection | Use the **Stop bits** dropdown in the **additional settings** | 1, 1.5, 2 | +| **Parity** | Can select what parity is used for the serial port connection | Use the **Parity** dropdown in the **additional settings** | None, Odd, Even, Mark, Space | +| **File Logging** | Allows the ability to log output to a file | Use the **file logging** toggle button, as well as the **Choose Log File Directory** button to choose the desired directory in the **additional settings** | On/Off | +| **Serial Wire Output (SWO)** | Can enable Serial Wire Output (SWO) decoding | Use the **Serial Wire Output** toggle in the **additional settings** in **TCP** mode | On/Off | + +--- diff --git a/docs/embedded/toc.yml b/docs/embedded/toc.yml new file mode 100644 index 0000000000..01279ba35c --- /dev/null +++ b/docs/embedded/toc.yml @@ -0,0 +1,25 @@ +items: +- name: Embedded development with Visual Studio and Visual Studio Code + href: ./index.yml +- name: Download and install the Embedded Tools + href: download-and-install-the-embedded-tooling.md +- name: Getting started guides + href: https://github.com/azure-rtos/getting-started +- name: Build and debug embedded projects + items: + - name: Embedded Software Development in Visual Studio + href: https://devblogs.microsoft.com/cppblog/visual-studio-embedded-development/ + - name: Embedded Software Development in Visual Studio Code + href: https://devblogs.microsoft.com/cppblog/vscode-embedded-development/ + - name: Zephyr support + href: https://devblogs.microsoft.com/cppblog/serial-and-zephyr-support/ +- name: Embedded Tooling + items: + - name: Peripheral View + href: ./peripheral-view.md + - name: RTOS View + href: ./rtos-view.md + - name: Serial Monitor + href: ./serial-monitor.md + - name: vcpkg artifacts + href: https://devblogs.microsoft.com/cppblog/vcpkg-artifacts/ diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2006.md b/docs/error-messages/compiler-errors-1/compiler-error-c2006.md index a1a2874400..531f672d9b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2006.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2006.md @@ -1,28 +1,22 @@ --- -description: "Learn more about: Compiler Error C2006" title: "Compiler Error C2006" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2006" +ms.date: "01/28/2025" f1_keywords: ["C2006"] helpviewer_keywords: ["C2006"] -ms.assetid: caaed6f7-ceb9-4742-8820-d66657c0b04d --- # Compiler Error C2006 -'directive' expected a filename, found 'token' +'directive': expected "FILENAME" or \ -Directives such as [#include](../../preprocessor/hash-include-directive-c-cpp.md) or [#import](../../preprocessor/hash-import-directive-cpp.md) require a filename. To resolve the error, make sure *token* is a valid filename. Also, put the filename in double quotes or angle brackets. +Directives such as [#include](../../preprocessor/hash-include-directive-c-cpp.md) or [#import](../../preprocessor/hash-import-directive-cpp.md) require a filename. To resolve the error, ensure the filename is valid and enclosed in either double quotes or angle brackets. The following sample generates C2006: ```cpp // C2006.cpp -#include stdio.h // C2006 -``` - -Possible resolution: - -```cpp -// C2006b.cpp // compile with: /c -#include +#include iostream // C2006 +#include 'iostream' // C2006 +#include // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2016.md b/docs/error-messages/compiler-errors-1/compiler-error-c2016.md new file mode 100644 index 0000000000..8e6379635a --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2016.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Compiler Error C2016" +title: "Compiler Error C2016" +ms.date: 08/18/2022 +f1_keywords: ["C2016"] +helpviewer_keywords: ["C2016"] +--- +# Compiler Error C2016 + +> C requires that a struct or union has at least one member + +The compiler found a **`struct`** or **`union`** defined with no members, which isn't allowed in C. For more information, see [Structures](../../c-language/structure-declarations.md) and [Unions](../../c-language/union-declarations.md). + +To resolve this error, create at least one member in your **`struct`** or **`union`**. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2018.md b/docs/error-messages/compiler-errors-1/compiler-error-c2018.md index 5b4dda0985..f81256fbfb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2018.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2018.md @@ -11,3 +11,21 @@ ms.assetid: 86b54573-dca0-4446-be1a-e3ac489c073b unknown character 'hexnumber' The source file contains an unexpected ASCII character, which is identified by its hex number. To resolve the error, remove the character. + +The following sample generates C2018: + +```cpp +// C2018.cpp +int main() { + @ // C2018 +} +``` + +Possible resolution: + +```cpp +// C2018b.cpp +int main() { + +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2023.md b/docs/error-messages/compiler-errors-1/compiler-error-c2023.md new file mode 100644 index 0000000000..ab9dba93d8 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2023.md @@ -0,0 +1,33 @@ +--- +description: "Learn more about: Compiler Error C2023" +title: "Compiler Error C2023" +ms.date: 08/18/2022 +f1_keywords: ["C2023"] +helpviewer_keywords: ["C2023"] +--- +# Compiler Error C2023 + +> '*identifier*': Alignment (*value-1*) different from prior declaration (*value-2*) + +The compiler found an alignment specifier for a class type that's different from a previous declaration, or an **`enum`** alignment specifier that's different from the natural alignment of the base type. + +To resolve this error, make sure all declarations and definitions of the type use the same alignment value. + +The following sample generates C2023: + +```cpp +// C2023.cpp +class alignas(2) C; + +class alignas(4) C {}; // C2023 +``` + +Possible resolution: + +```cpp +// C2023b.cpp +// compile with: /c +class alignas(2) C; + +class alignas(2) C {}; +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2024.md b/docs/error-messages/compiler-errors-1/compiler-error-c2024.md new file mode 100644 index 0000000000..fe0b5e057f --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2024.md @@ -0,0 +1,33 @@ +--- +description: "Learn more about: Compiler Error C2024" +title: "Compiler Error C2024" +ms.date: 08/18/2022 +f1_keywords: ["C2024"] +helpviewer_keywords: ["C2024"] +--- +# Compiler Error C2024 + +> 'alignas' attribute applies to variables, data members and tag types only + +The compiler found an **`alignas`** specifier applied to a function or other type that can't be aligned. + +To resolve this error, remove the **`alignas`** specifier. + +The following sample generates C2024: + +```cpp +// C2024.cpp +namespace alignas(2) ns { // C2024 + void func(alignas(8) int x) {} // C2024 +} +``` + +Possible resolution: + +```cpp +// C2024b.cpp +// compile with: /c +namespace ns { + void func(int x) {} +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2025.md b/docs/error-messages/compiler-errors-1/compiler-error-c2025.md new file mode 100644 index 0000000000..92c0e186ea --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2025.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Compiler Error C2025" +title: "Compiler Error C2025" +ms.date: 08/18/2022 +f1_keywords: ["C2025"] +helpviewer_keywords: ["C2025"] +--- +# Compiler Error C2025 + +> invalid or corrupted binary module interface file: '*filename*' + +The compiler could not read the specified IFC file. + +To resolve this error, rebuild the module interface file. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2031.md b/docs/error-messages/compiler-errors-1/compiler-error-c2031.md new file mode 100644 index 0000000000..737fec9789 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2031.md @@ -0,0 +1,15 @@ +--- +description: "Learn more about: Compiler Error C2031" +title: "Compiler Error C2031" +ms.date: 08/18/2022 +f1_keywords: ["C2031"] +helpviewer_keywords: ["C2031"] +--- +# Compiler Error C2031 + +> a virtual destructor with '*accessibility*' accessibility is not allowed for this type\ +> a virtual destructor must have 'public' accessibility + +A virtual Windows Runtime class has an access specifier or **`sealed`** specifier that's not allowed for a virtual destructor. For more information, see [Ref classes and structs](../../cppcx/ref-classes-and-structs-c-cx.md). + +To fix this error, change the accessibility of the destructor. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2035.md b/docs/error-messages/compiler-errors-1/compiler-error-c2035.md new file mode 100644 index 0000000000..3b2f4c6fa8 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2035.md @@ -0,0 +1,15 @@ +--- +description: "Learn more about: Compiler Error C2035" +title: "Compiler Error C2035" +ms.date: 08/18/2022 +f1_keywords: ["C2035"] +helpviewer_keywords: ["C2035"] +--- +# Compiler Error C2035 + +> a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type\ +> a non-virtual destructor must have 'protected private' or 'private' accessibility + +A non-virtual Windows Runtime class has an access specifier or **`sealed`** specifier that's not allowed for a non-virtual destructor. For more information, see [Ref classes and structs](../../cppcx/ref-classes-and-structs-c-cx.md). + +To fix this error, change the accessibility of the destructor. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2037.md b/docs/error-messages/compiler-errors-1/compiler-error-c2037.md new file mode 100644 index 0000000000..ad11cf2dc6 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2037.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Compiler Error C2037" +title: "Compiler Error C2037" +ms.date: 08/18/2022 +f1_keywords: ["C2037"] +helpviewer_keywords: ["C2037"] +--- +# Compiler Error C2037 + +> left of '*operator*' specifies undefined struct/union '*type*' + +The operand to the left of the member-selection *operator* is not a fully defined class, structure, or union. + +This error can be caused by a left operand that is an undefined variable. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2038.md b/docs/error-messages/compiler-errors-1/compiler-error-c2038.md new file mode 100644 index 0000000000..8e7ffa2aa0 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2038.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Compiler Error C2038" +title: "Compiler Error C2038" +ms.date: 08/18/2022 +f1_keywords: ["C2038"] +helpviewer_keywords: ["C2038"] +--- +# Compiler Error C2038 + +> the std namespace cannot be inline + +The C++ standard does not allow the `std` namespace to be declared `inline`. + +To resolve this issue, remove the `inline` specifier. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2039.md b/docs/error-messages/compiler-errors-1/compiler-error-c2039.md index f84cbdefa6..0264758359 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2039.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2039.md @@ -1,20 +1,19 @@ --- description: "Learn more about: Compiler Error C2039" title: "Compiler Error C2039" -ms.date: "11/04/2016" +ms.date: "8/1/2023" f1_keywords: ["C2039"] helpviewer_keywords: ["C2039"] -ms.assetid: f9dfd521-9b36-4454-a69c-d63f45b606bb --- # Compiler Error C2039 -'identifier1' : is not a member of 'identifier2' +`'identifier1' : is not a member of 'identifier2'` The code incorrectly calls or refers to a member of a structure, class, or union. ## Examples -The following sample generates C2039. +The following sample generates C2039: ```cpp // C2039.cpp @@ -28,7 +27,7 @@ int main() { } ``` -The following sample generates C2039. +The following sample generates C2039: ```cpp // C2039_b.cpp @@ -41,7 +40,7 @@ int main() { } ``` -The following sample generates C2039. +The following sample generates C2039: ```cpp // C2039_c.cpp @@ -57,9 +56,9 @@ int S::get_Count() { return 0; } // C2039 int S::Count::get() { return 0; } // OK ``` -C2039 can also occur if you attempt to access a default indexer incorrectly. The following sample defines a component authored in C#. +C2039 can also occur if you attempt to access a default indexer incorrectly. To demonstrate, this code defines a C# component that is used by the C++/CLI code that follows: -``` +```c# // C2039_d.cs // compile with: /target:library // a C# program @@ -72,7 +71,7 @@ public class B { }; ``` -The following sample generates C2039. +The following sample generates C2039 when it uses the previously defined C# component's default indexer incorrectly from C++/CLI: ```cpp // C2039_e.cpp @@ -89,7 +88,7 @@ int main() { } ``` -C2039 can also occur if you use generics. The following sample generates C2039. +C2039 can also occur if you use generics. The following sample generates C2039: ```cpp // C2039_f.cpp @@ -114,7 +113,7 @@ int main() { C2039 can occur when you try to release managed or unmanaged resources. For more information, see [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). -The following sample generates C2039. +The following sample generates C2039: ```cpp // C2039_g.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2049.md b/docs/error-messages/compiler-errors-1/compiler-error-c2049.md new file mode 100644 index 0000000000..cc707acda1 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2049.md @@ -0,0 +1,32 @@ +--- +description: "Learn more about: Compiler Error C2049" +title: "Compiler Error C2049" +ms.date: 08/18/2022 +f1_keywords: ["C2049"] +helpviewer_keywords: ["C2049"] +--- +# Compiler Error C2049 + +> '*namespace-name*': non-inline namespace cannot be reopened as inline + +The **`inline`** keyword may be used on a namespace definition extension only if it was also used on the original namespace definition. + +To resolve this issue, make the use of the **`inline`** specifier consistent across all parts of the namespace. + +The following sample generates C2049: + +```cpp +// C2049.cpp +namespace ns {} + +inline namespace ns {} // C2049 +``` + +Possible resolution: + +```cpp +// C2049b.cpp +namespace ns {} + +namespace ns {} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2055.md b/docs/error-messages/compiler-errors-1/compiler-error-c2055.md index fe73b75244..1654921d89 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2055.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2055.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: Compiler Error C2055" -title: "Compiler Error C2055" -ms.date: "11/04/2016" +description: "Learn more about: Microsoft Visual C++ compiler error C2055" +title: "Compiler error C2055" +ms.date: 06/10/2024 f1_keywords: ["C2055"] helpviewer_keywords: ["C2055"] -ms.assetid: 6cec79cc-6bec-443f-9897-fbf5452718c7 --- -# Compiler Error C2055 +# Compiler error C2055 -expected formal parameter list, not a type list +> expected formal parameter list, not a type list -A function definition contains a parameter type list instead of a formal parameter list. ANSI C requires formal parameters to be named unless they are void or an ellipsis (`...`). +A function definition contains a parameter type list instead of a formal parameter list. ANSI C requires formal parameters to be named unless they're `void` or an ellipsis (`...`). -The following sample generates C2055: +An example of a named formal parameter is the `int i` in `void func(int i)`.\ +A parameter type list is a list of types, for example, `int, char`. + +The following code generates error `C2055`: ```c // C2055.c // compile with: /c void func(int, char) {} // C2055 -void func (int i, char c) {} // OK +void func (int i, char c) {} // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2058.md b/docs/error-messages/compiler-errors-1/compiler-error-c2058.md index d8aa9725a7..4910bb4b71 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2058.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2058.md @@ -11,3 +11,16 @@ ms.assetid: 81e08e6b-15f7-41b4-980a-53763e19990c constant expression is not integral The context requires an integer constant expression. + +The following sample generates C2058: + +```cpp +// C2058.cpp +struct alignas(1.5) S {}; // C2058 + +int main() { + int arr[1.5]; // C2058 +} +``` + +To resolve the issue, use an integer constant expression. For example, `int arr[2];` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2061.md b/docs/error-messages/compiler-errors-1/compiler-error-c2061.md index 2a79f1cd5a..2af16ddaee 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2061.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2061.md @@ -14,30 +14,54 @@ The compiler found an identifier where it wasn't expected. Make sure that `ident An initializer may be enclosed by parentheses. To avoid this problem, enclose the declarator in parentheses or make it a **`typedef`**. -This error could also be caused when the compiler detects an expression as a class template argument; use [typename](../../cpp/typename.md) to tell the compiler it is a type. +This error could also be caused when the compiler detects an expression as a class template argument; use [typename](../../cpp/typename.md) to tell the compiler it is a type, as shown in the following example: The following sample generates C2061: ```cpp // C2061.cpp -// compile with: /c -template < A a > // C2061 -// try the following line instead -// template < typename b > -class c{}; +// compile with: /std:c++17 + +template // C2061 +class C1 {}; + +template // ok +class C2 {}; + +template +class C3 +{ + // Both are valid since C++20 + using Type1 = T::Type; // C2061 + using Type2 = typename T::Type; // OK +}; + +int main() +{ + int x; + unsigned a1 = alignof(x); // C2061 + unsigned a2 = alignof(int); // OK + unsigned a3 = alignof(decltype(x)); // OK +} ``` +To resolve the error with `template class C1{};`, use `template class C1 {};`\ +To resolve the issue with `using Type1 = T::Type;`, use `using Type1 = typename T::Type;`\ +To resolve the issue with `alignof(x)`, replace the argument with the type of `x`. In this case, `int` or `decltype(x);` + C2061 can occur if you pass an instance name to [typeid](../../extensions/typeid-cpp-component-extensions.md): ```cpp // C2061b.cpp // compile with: /clr -ref struct G { +ref struct G +{ int i; }; -int main() { - G ^ pG = gcnew G; +int main() +{ + G ^pG = gcnew G; System::Type ^ pType = typeid; // C2061 System::Type ^ pType2 = typeid; // OK } diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2065.md b/docs/error-messages/compiler-errors-1/compiler-error-c2065.md index 310b7aa78f..e18d500450 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2065.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2065.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Compiler Error C2065" title: "Compiler Error C2065" -ms.date: "08/19/2019" +ms.date: 06/29/2022 f1_keywords: ["C2065"] helpviewer_keywords: ["C2065"] ms.assetid: 78093376-acb7-45f5-9323-5ed7e0aab1dc @@ -10,7 +10,7 @@ ms.assetid: 78093376-acb7-45f5-9323-5ed7e0aab1dc > '*identifier*' : undeclared identifier -The compiler can't find the declaration for an identifier. There are many possible causes for this error. The most common causes of C2065 are that the identifier hasn't been declared, the identifier is misspelled, the header where the identifier is declared is not included in the file, or the identifier is missing a scope qualifier, for example, `cout` instead of `std::cout`. For more information on declarations in C++, see [Declarations and Definitions (C++)](../../cpp/declarations-and-definitions-cpp.md). +The compiler can't find the declaration for an identifier. There are many possible causes for this error. The most common causes of C2065 are that the identifier hasn't been declared, the identifier is misspelled, the header where the identifier is declared isn't included in the file, or the identifier is missing a scope qualifier, for example, `cout` instead of `std::cout`. For more information on declarations in C++, see [Declarations and Definitions (C++)](../../cpp/declarations-and-definitions-cpp.md). Here are some common issues and solutions in greater detail. @@ -22,7 +22,7 @@ If the identifier is a member of a class or struct, or declared in a namespace, If the identifier is the tag for a user-defined type, for example, a **`class`** or **`struct`**, the type of the tag must be declared before it can be used. For example, the declaration `struct SomeStruct { /*...*/ };` must exist before you can declare a variable `SomeStruct myStruct;` in your code. -If the identifier is a type alias, the type must be declared by using a **`using`** declaration or **`typedef`** before it can be used. For example, you must declare `using my_flags = std::ios_base::fmtflags;` before you can use `my_flags` as a type alias for `std::ios_base::fmtflags`. +If the identifier is a type alias, the type must be declared by a **`using`** declaration or **`typedef`** before it can be used. For example, you must declare `using my_flags = std::ios_base::fmtflags;` before you can use `my_flags` as a type alias for `std::ios_base::fmtflags`. ## Example: misspelled identifier @@ -44,7 +44,7 @@ int main() { ## Example: use an unscoped identifier -This error can occur if your identifier is not properly scoped. If you see C2065 when you use `cout`, this is the cause. When C++ Standard Library functions and operators are not fully qualified by namespace, or you have not brought the `std` namespace into the current scope by using a **`using`** directive, the compiler can't find them. To fix this issue, you must either fully qualify the identifier names, or specify the namespace with the **`using`** directive. +This error can occur if your identifier isn't properly scoped. If you see C2065 when you use `cout`, a scope issue is the cause. When C++ Standard Library functions and operators aren't fully qualified by namespace, or you haven't brought the `std` namespace into the current scope by using a **`using`** directive, the compiler can't find them. To fix this issue, you must either fully qualify the identifier names, or specify the namespace with the **`using`** directive. This example fails to compile because `cout` and `endl` are defined in the `std` namespace: @@ -66,21 +66,25 @@ Identifiers that are declared inside of **`class`**, **`struct`**, or **`enum cl ## Example: precompiled header isn't first -This error can occur if you put any preprocessor directives, such as #include, #define, or #pragma, before the #include of a precompiled header file. If your source file uses a precompiled header file (that is, if it's compiled by using the **/Yu** compiler option) then all preprocessor directives before the precompiled header file are ignored. +This error can occur if you put any preprocessor directives, such as `#include`, `#define`, or `#pragma`, before the `#include` of a precompiled header file. If your source file uses a precompiled header file (that is, if it's compiled by using the **`/Yu`** compiler option) then all preprocessor directives before the precompiled header file are ignored. -This example fails to compile because `cout` and `endl` are defined in the \ header, which is ignored because it is included before the precompiled header file. To build this example, create all three files, then compile stdafx.cpp, then compile C2065_pch.cpp. +This example fails to compile because `cout` and `endl` are defined in the `` header, which is ignored because it's included before the precompiled header file. To build this example, create all three files, then compile `pch.h` (some versions of Visual Studio use `stdafx.cpp`), then compile `C2065_pch.cpp`. ```cpp // pch.h (stdafx.h in Visual Studio 2017 and earlier) #include ``` +The `pch.h` or `stdafx.h` source file: + ```cpp // pch.cpp (stdafx.cpp in Visual Studio 2017 and earlier) // Compile by using: cl /EHsc /W4 /c /Ycstdafx.h stdafx.cpp #include "pch.h" ``` +Source file `C2065_pch.cpp`: + ```cpp // C2065_pch.cpp // compile with: cl /EHsc /W4 /Yustdafx.h C2065_pch.cpp @@ -94,11 +98,11 @@ int main() { } ``` -To fix this issue, add the #include of \ into the precompiled header file, or move it after the precompiled header file is included in your source file. +To fix this issue, add the #include of `` into the precompiled header file, or move it after the precompiled header file is included in your source file. ## Example: missing header file -You have not included the header file that declares the identifier. Make sure the file that contains the declaration for the identifier is included in every source file that uses it. +The error can occur if you haven't included the header file that declares the identifier. Make sure the file that contains the declaration for the identifier is included in every source file that uses it. ```cpp // C2065_header.cpp @@ -127,11 +131,11 @@ int main() { } ``` -You may see this error in Windows Desktop app source files if you define `VC_EXTRALEAN`, `WIN32_LEAN_AND_MEAN`, or `WIN32_EXTRA_LEAN`. These preprocessor macros exclude some header files from windows.h and afxv\_w32.h to speed compiles. Look in windows.h and afxv_w32.h for an up-to-date description of what's excluded. +You may see this error in Windows Desktop app source files if you define `VC_EXTRALEAN`, `WIN32_LEAN_AND_MEAN`, or `WIN32_EXTRA_LEAN`. These preprocessor macros exclude some header files from `windows.h` and `afxv_w32.h` to speed compiles. Look in `windows.h` and `afxv_w32.h` for an up-to-date description of what's excluded. ## Example: missing closing quote -This error can occur if you are missing a closing quote after a string constant. This is an easy way to confuse the compiler. Note that the missing closing quote may be several lines before the reported error location. +This error can occur if you're missing a closing quote after a string constant. It's an easy way to confuse the compiler. The missing closing quote may be several lines before the reported error location. ```cpp // C2065_quote.cpp @@ -148,7 +152,7 @@ int main() { ## Example: use iterator outside for loop scope -This error can occur if you declare an iterator variable in a **`for`** loop, and then you try to use that iterator variable outside the scope of the **`for`** loop. The compiler enables the [/Zc:forScope](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) compiler option by default. See [Debug Iterator Support](../../standard-library/debug-iterator-support.md) for more information. +This error can occur if you declare an iterator variable in a **`for`** loop, and then you try to use that iterator variable outside the scope of the **`for`** loop. The compiler enables the [`/Zc:forScope`](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) compiler option by default. For more information, see [Debug iterator support](../../standard-library/debug-iterator-support.md). ```cpp // C2065_iter.cpp @@ -174,9 +178,9 @@ int main() { ## Example: preprocessor removed declaration -This error can occur if you refer to a function or variable that is in conditionally compiled code that is not compiled for your current configuration. This can also occur if you call a function in a header file that is currently not supported in your build environment. If certain variables or functions are only available when a particular preprocessor macro is defined, make sure the code that calls those functions can only be compiled when the same preprocessor macro is defined. This issue is easy to spot in the IDE, because the declaration for the function is greyed out if the required preprocessor macros are not defined for the current build configuration. +This error can occur if you refer to a function or variable that is in conditionally compiled code that isn't compiled for your current configuration. The error can also occur if you call a function in a header file that currently isn't supported in your build environment. If certain variables or functions are only available when a particular preprocessor macro is defined, make sure the code that calls those functions can only be compiled when the same preprocessor macro is defined. This issue is easy to spot in the IDE: The declaration for the function is greyed out if the required preprocessor macros aren't defined for the current build configuration. -This is an example of code that works when you build in Debug, but not Retail: +Here's an example of code that works when you build in Debug, but not Release: ```cpp // C2065_defined.cpp @@ -198,7 +202,7 @@ int main() { ## Example: C++/CLI type deduction failure -This error can occur when calling a generic function, if the intended type argument cannot be deduced from the parameters used. For more information, see [Generic Functions (C++/CLI)](../../extensions/generic-functions-cpp-cli.md). +This error can occur when calling a generic function, if the intended type argument can't be deduced from the parameters used. For more information, see [Generic Functions (C++/CLI)](../../extensions/generic-functions-cpp-cli.md). ```cpp // C2065_b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2068.md b/docs/error-messages/compiler-errors-1/compiler-error-c2068.md new file mode 100644 index 0000000000..71ed5cd042 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2068.md @@ -0,0 +1,22 @@ +--- +description: "Learn more about: Compiler Error C2068" +title: "Compiler Error C2068" +ms.date: 08/18/2022 +f1_keywords: ["C2068"] +helpviewer_keywords: ["C2068"] +--- +# Compiler Error C2068 + +> illegal use of overloaded function. Missing argument list? + +The compiler detected the invalid use of an overloaded function with no arguments. + +For example: + +```cpp +void f(int x) {} +void f(char x) {} +void g() noexcept( noexcept(f) ); +``` + +To resolve this issue, include the argument types required to resolve the function overload. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2073.md b/docs/error-messages/compiler-errors-1/compiler-error-c2073.md index 866910f600..c790ea0ffb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2073.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2073.md @@ -1,18 +1,24 @@ --- description: "Learn more about: Compiler Error C2073" title: "Compiler Error C2073" -ms.date: "11/04/2016" +ms.date: 06/29/2022 f1_keywords: ["C2073"] helpviewer_keywords: ["C2073"] ms.assetid: 57908234-be7a-4ce9-b0a7-8b1ad621865e --- # Compiler Error C2073 -'identifier' : elements of partially initialized array must have a default constructor +> 'identifier' : elements of partially initialized array must have a default constructor + +## Remarks Too few initializers were specified for an array of user-defined types or constants. If an explicit initializer and its corresponding constructor are not specified for an array member, a default constructor must be supplied. -The following sample generates C2073: +This compiler error is obsolete in Visual Studio 2022. + +## Example + +The following sample generates C2073. Source file `C2073.cpp`: ```cpp // C2073.cpp @@ -23,6 +29,8 @@ public: A a[3] = { A(1), A(2) }; // C2073, no default constructor ``` +A fix is shown here in source file `C2073b.cpp`: + ```cpp // C2073b.cpp // compile with: /c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2076.md b/docs/error-messages/compiler-errors-1/compiler-error-c2076.md new file mode 100644 index 0000000000..bd3b76f5c7 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2076.md @@ -0,0 +1,20 @@ +--- +description: "Learn more about: Compiler Error C2076" +title: "Compiler Error C2076" +ms.date: 08/18/2022 +f1_keywords: ["C2076"] +helpviewer_keywords: ["C2076"] +--- +# Compiler Error C2076 + +> a brace-enclosed initializer list cannot be used in a new-expression whose type contains 'auto/decltype(auto)' + +If an **`auto`** type-specifier appears in the specifier sequence of a new type-identifier or the type-identifier of a **`new`** expression, the expression must contain an initializer of the form `( assignment-expression )`. The compiler deduces the type-identifier from the `assignment-expression` in the initializer. For example, + +```cpp +new auto(42); // new allocates int +auto c = new auto('a'); // c is of type char*, new allocates char +new (auto*)(static_cast(nullptr)); // allocates type short* +``` + +To resolve this issue, use parentheses to enclose the initialization value of the **`new`** expression. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2080.md b/docs/error-messages/compiler-errors-1/compiler-error-c2080.md new file mode 100644 index 0000000000..26fa529539 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2080.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: Compiler Error C2080" +title: "Compiler Error C2080" +ms.date: 08/18/2022 +f1_keywords: ["C2080"] +helpviewer_keywords: ["C2080"] +--- +# Compiler Error C2080 + +> '*identifier*': the type for '*type*' can only be deduced from a single initializer expression + +## Remarks + +The compiler can only deduce the type for `auto` or `decltype(auto)` if the declaration uses direct list-initialization and the initializer-list has a single element. + +## Example + +The following sample shows some declarations that cause C2080: + +```cpp +auto x1(1, 2); // C2080 +auto x2({4}); // C2080 +decltype(auto) x3(1, 2); // C2080 +decltype(auto) x4({4}); // C2080 +``` + +To resolve the issue, use a single value initializer: + +```cpp +auto x1 = 1; // Valid +auto x2(1); // Valid +decltype(auto) x3 = 1; // Valid +decltype(auto) x4(1); // Valid +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2082.md b/docs/error-messages/compiler-errors-1/compiler-error-c2082.md index 25b3e93eed..e5a420137b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2082.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2082.md @@ -16,8 +16,11 @@ The following sample generates C2082: ```cpp // C2082.cpp -void func(int i) { - int i; // C2082 - int ii; // OK +void func(int num1) { + int num1; // C2082 + int num2; // OK + + auto lambda1 = [](int num1){ int num1; }; // C2082 + auto lambda2 = [](int num1){ int num2; }; // OK } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2095.md b/docs/error-messages/compiler-errors-1/compiler-error-c2095.md index 8224cfb3a8..0c20af59dd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2095.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2095.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Compiler Error C2095" title: "Compiler Error C2095" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2095" +ms.date: 11/04/2016 f1_keywords: ["C2095"] helpviewer_keywords: ["C2095"] -ms.assetid: 44f8ada1-974f-4e81-a408-33ac6695aa53 --- # Compiler Error C2095 'function' : actual parameter has type 'void' : parameter 'number' -The parameter passed to the function is type **`void`**, which is not allowed. Use a pointer to void ( `void *`) instead. +The parameter passed to the function is type **`void`**, which is not allowed. Use a pointer to void (`void *`) instead. The `number` indicates which parameter is **`void`**. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2096.md b/docs/error-messages/compiler-errors-1/compiler-error-c2096.md new file mode 100644 index 0000000000..429150aba6 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2096.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Compiler Error C2096" +title: "Compiler Error C2096" +ms.date: 08/23/2022 +f1_keywords: ["C2096"] +helpviewer_keywords: ["C2096"] +--- +# Compiler Error C2096 + +> '*identifier*': A data member cannot be initialized with a parenthesized initializer + +The compiler expected a braced initializer or an equal expression initializer. To resolve the issue, replace the parenthesized initializer with a braced initializer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2098.md b/docs/error-messages/compiler-errors-1/compiler-error-c2098.md new file mode 100644 index 0000000000..b8c19fd652 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2098.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Compiler Error C2098" +title: "Compiler Error C2098" +ms.date: 08/23/2022 +f1_keywords: ["C2098"] +helpviewer_keywords: ["C2098"] +--- +# Compiler Error C2098 + +> unexpected token after data member '*identifier*' + +The compiler expected a semicolon, a braced initializer or an equal expression initializer. To resolve the issue, insert a semicolon or an initializer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2100.md b/docs/error-messages/compiler-errors-1/compiler-error-c2100.md index 8c69129528..c2ec852188 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2100.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2100.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C2100" title: "Compiler Error C2100" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2100" +ms.date: 11/04/2016 f1_keywords: ["C2100"] helpviewer_keywords: ["C2100"] -ms.assetid: 9ed5ea11-9d55-4ddf-8b1a-162c74f3c390 --- # Compiler Error C2100 illegal indirection -Indirection operator ( `*` ) is applied to a nonpointer value. +Indirection operator (`*`) is applied to a nonpointer value. The following sample generates C2100: diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2101.md b/docs/error-messages/compiler-errors-1/compiler-error-c2101.md index 70d8b692fb..a01fe6598c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2101.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2101.md @@ -1,24 +1,22 @@ --- description: "Learn more about: Compiler Error C2101" title: "Compiler Error C2101" -ms.date: "11/04/2016" +ms.date: "03/04/2024" f1_keywords: ["C2101"] helpviewer_keywords: ["C2101"] -ms.assetid: 42f0136f-8cc1-4f2b-be1c-721ec9278e66 --- # Compiler Error C2101 '&' on constant -The address-of operator ( `&` ) must have an l-value as operand. +The [address-of operator (**`&`**)](../../cpp/address-of-operator-amp.md) must have an l-value as operand. The following sample generates C2101: ```cpp // C2101.cpp -int main() { - char test; - test = &'a'; // C2101 - test = 'a'; // OK +int main() +{ + int* ptr = &123; // C2101 } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2102.md b/docs/error-messages/compiler-errors-1/compiler-error-c2102.md index 2c71c692be..292bbccacc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2102.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2102.md @@ -1,13 +1,27 @@ --- description: "Learn more about: Compiler Error C2102" title: "Compiler Error C2102" -ms.date: "11/04/2016" +ms.date: "03/03/2024" f1_keywords: ["C2102"] helpviewer_keywords: ["C2102"] -ms.assetid: d15b5fa3-fa46-4cd4-a3d2-3661646ecb7a --- # Compiler Error C2102 '&' requires l-value -The address-of operator ( `&` ) must have an l-value as operand. +The [address-of operator (**`&`**)](../../cpp/address-of-operator-amp.md) must have an l-value as operand. Address of temporary values cannot be taken. + +The following sample generates C2102: + +```cpp +// C2102.cpp +int func() +{ + return 1; +} + +int main() +{ + int* ptr = &func(); // C2102 +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2103.md b/docs/error-messages/compiler-errors-1/compiler-error-c2103.md index 0c2a9d28ed..3809ebf983 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2103.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2103.md @@ -1,13 +1,26 @@ --- description: "Learn more about: Compiler Error C2103" title: "Compiler Error C2103" -ms.date: "11/04/2016" +ms.date: "03/04/2024" f1_keywords: ["C2103"] helpviewer_keywords: ["C2103"] -ms.assetid: dfe95972-35e9-469a-b8a8-52c849d4e4e4 --- # Compiler Error C2103 '&' on register variable You cannot take the address of a register. + +The following sample generates C2103: + +```c +// C2103.c +int main(void) +{ + register int x = 1; + int* ptr = &x; // C2103 +} +``` + +> [!NOTE] +> This error applies to C code. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2107.md b/docs/error-messages/compiler-errors-1/compiler-error-c2107.md index 6e6c3991ba..1644f15337 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2107.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2107.md @@ -14,7 +14,7 @@ A subscript is applied to an expression that does not evaluate to a pointer. ## Example -C2107 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the this pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). +C2107 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). The following sample generates C2107. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2108.md b/docs/error-messages/compiler-errors-1/compiler-error-c2108.md index 38d7dfea98..4560690ae7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2108.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2108.md @@ -1,20 +1,22 @@ --- description: "Learn more about: Compiler Error C2108" title: "Compiler Error C2108" -ms.date: "11/04/2016" +ms.date: 06/03/2022 f1_keywords: ["C2108"] helpviewer_keywords: ["C2108"] ms.assetid: c84f0b47-5e2c-47d2-8edb-427a40e17c36 --- # Compiler Error C2108 -subscript is not of integral type +> subscript is not of integral type -The array subscript is a noninteger expression. +## Remarks + +The array subscript is a non-integer expression. ## Example -C2108 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the this pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). +C2108 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). The following sample generates C2108. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2110.md b/docs/error-messages/compiler-errors-1/compiler-error-c2110.md index 6136d130b1..42bfa8a939 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2110.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2110.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C2110" title: "Compiler Error C2110" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2110" +ms.date: 11/04/2016 f1_keywords: ["C2110"] helpviewer_keywords: ["C2110"] -ms.assetid: 48fd76ed-90d6-4a60-9c7b-f6ce9355b4ca --- # Compiler Error C2110 '+' : cannot add two pointers -An attempt was made to add two pointer values using the plus ( `+` ) operator. +An attempt was made to add two pointer values using the plus (`+`) operator. The following sample generates C2110: diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2111.md b/docs/error-messages/compiler-errors-1/compiler-error-c2111.md index 10ba943b72..d0d6444cac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2111.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2111.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C2111" title: "Compiler Error C2111" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2111" +ms.date: 11/04/2016 f1_keywords: ["C2111"] helpviewer_keywords: ["C2111"] -ms.assetid: 38fd42ec-1480-4a44-aaca-ae4593ed5f50 --- # Compiler Error C2111 '+' : pointer addition requires integral operand -An attempt was made to add a nonintegral value to a pointer using the plus ( `+` ) operator. +An attempt was made to add a nonintegral value to a pointer using the plus (`+`) operator. The following sample generates C2111: diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2128.md b/docs/error-messages/compiler-errors-1/compiler-error-c2128.md index 3d964e79d8..242935dcf8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2128.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2128.md @@ -2,9 +2,8 @@ description: "Learn more about: Compiler Error C2128" title: "Compiler Error C2128" ms.date: "11/04/2016" -f1_keywords: ["c2128"] +f1_keywords: ["C2128"] helpviewer_keywords: ["C2128"] -ms.assetid: 08cbf734-75b3-49f2-9026-9b319947612d --- # Compiler Error C2128 diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2129.md b/docs/error-messages/compiler-errors-1/compiler-error-c2129.md index a6945a3fc5..bc65e65142 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2129.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2129.md @@ -13,3 +13,27 @@ static function 'function' declared but not defined A forward reference is made to a **`static`** function that is never defined. A **`static`** function must be defined within file scope. If the function is defined in another file, it must be declared **`extern`**. + +The following sample generates C2129: + +```cpp +// C2129.cpp +static void foo(); // C2129 + +int main() { + foo(); +} +``` + +Possible resolution: + +```cpp +// C2129b.cpp +static void foo(); + +int main() { + foo(); +} + +static void foo() {} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2134.md b/docs/error-messages/compiler-errors-1/compiler-error-c2134.md index a46a383784..0436d94a76 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2134.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2134.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Compiler Error C2134" title: "Compiler Error C2134" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2134" +ms.date: 11/04/2016 f1_keywords: ["C2134"] -ms.assetid: d45cb3e8-0be4-4bd6-8be9-5f8d2384363f +helpviewer_keywords: ["C2134"] --- # Compiler Error C2134 @@ -18,7 +18,7 @@ The following sample generates C2134: // compile with: /c int A() { return 42; -}; +} constexpr int B() { return A(); // Error C2134: 'A': call does not result in a constant expression. @@ -31,7 +31,7 @@ Possible resolution: // C2134b.cpp constexpr int A() { // add constexpr to A, since it meets the requirements of constexpr. return 42; -}; +} constexpr int B() { return A(); // No error diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2153.md b/docs/error-messages/compiler-errors-1/compiler-error-c2153.md index 893455edab..2090da157a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2153.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2153.md @@ -1,23 +1,26 @@ --- -description: "Learn more about: Compiler Error C2153" title: "Compiler Error C2153" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2153" +ms.date: "01/31/2025" f1_keywords: ["C2153"] helpviewer_keywords: ["C2153"] -ms.assetid: cfc50cb7-9a0f-4b5b-879a-d419c99f7be1 --- # Compiler Error C2153 -hex constants must have at least one hex digit +integer literals must have at least one digit -Hexadecimal constants 0x, 0X, and \x are not valid. At least one hex digit must follow x or X. +Hexadecimal and binary literals must contain at least one digit after the leading sequence (`0x`, `0X`, `0b`, or `0B`), otherwise the trailing character may be incorrectly interpreted as a suffix or literal operator. See [Integer literals](../../cpp/numeric-boolean-and-pointer-literals-cpp.md#integer-literals) for more information. The following sample generates C2153: ```cpp // C2153.cpp -int main() { - int a= 0x; // C2153 - int b= 0xA; // OK +int main() +{ + int a = 0x; // C2153 + int b = 0x0; // OK + + int c = 0b; // C2153 + int d = 0b0; // OK } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2162.md b/docs/error-messages/compiler-errors-1/compiler-error-c2162.md index 9255eacdab..2cd9768016 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2162.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2162.md @@ -1,26 +1,23 @@ --- -description: "Learn more about: Compiler Error C2162" title: "Compiler Error C2162" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2162" +ms.date: "03/30/2025" f1_keywords: ["C2162"] helpviewer_keywords: ["C2162"] -ms.assetid: 34923628-d35e-48ab-9072-b95e3b5f6b45 --- # Compiler Error C2162 -expected macro formal parameter +> expected macro formal parameter -The token following a stringizing operator (#) is not a formal parameter name. +The token following a [stringizing operator (#)](../../preprocessor/stringizing-operator-hash.md) or a [charizing operator (#@)](../../preprocessor/charizing-operator-hash-at.md) is not a formal parameter. ## Example -The following sample generates C2162: +The following example generates C2162: ```cpp // C2162.cpp // compile with: /c -#include - -#define print(a) printf_s(b) // OK -#define print(a) printf_s(#b) // C2162 +#define make_string1(s) # // C2162 +#define make_string2(s) #s // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2200.md b/docs/error-messages/compiler-errors-1/compiler-error-c2200.md index bc39dfceb8..c01937be6c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2200.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2200.md @@ -1,13 +1,21 @@ --- -description: "Learn more about: Compiler Error C2200" title: "Compiler Error C2200" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2200" +ms.date: "02/15/2025" f1_keywords: ["C2200"] helpviewer_keywords: ["C2200"] -ms.assetid: a04139a6-ce18-404b-9bfd-2369fc0af3cb --- # Compiler Error C2200 -'function' : function has already been defined +'function': function has already been defined + +An [`alloc_text`](../../preprocessor/alloc-text.md) pragma uses a function name already defined. Ensure the `alloc_text` pragma appears after the function declaration but before its definition. + +The following sample generates C2200: -An `alloc_text` pragma uses a function name already defined. +```cpp +// C2200.cpp +// compile with: /c +extern "C" void func() {} +#pragma alloc_text("section", func) // C2200 +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2217.md b/docs/error-messages/compiler-errors-1/compiler-error-c2217.md index bbe71cce5a..009e512bf1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2217.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2217.md @@ -12,15 +12,9 @@ ms.assetid: 1ce1e3f5-4171-4376-804d-967f7e612935 The first function attribute requires the second attribute. -### To fix by checking the following possible causes - -1. Interrupt (`__interrupt`) function declared as `near`. Interrupt functions must be `far`. - -1. Interrupt function declared with **`__stdcall`**, or **`__fastcall`**. Interrupt functions must use C calling conventions. - ## Example -C2217 can also occur if you attempt to bind a delegate to a CLR function that takes a variable number of arguments. If the function also has e param array overload, use that instead. The following sample generates C2217. +C2217 can occur if you attempt to bind a delegate to a CLR function that takes a variable number of arguments. If the function also has a param array overload, use that instead. The following sample generates C2217. ```cpp // C2217.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2248.md b/docs/error-messages/compiler-errors-1/compiler-error-c2248.md index 22b7966dbd..81f0232666 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2248.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2248.md @@ -1,20 +1,22 @@ --- description: "Learn more about: Compiler Error C2248" title: "Compiler Error C2248" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["C2248"] helpviewer_keywords: ["C2248"] ms.assetid: 7a3ba0e8-d3b9-4bb9-95db-81ef17e31d23 --- # Compiler Error C2248 -'*member*' : cannot access '*access_level*' member declared in class '*class*' +> '*member*': can't access '*access_level*' member declared in class '*class*' -Members of a derived class cannot access **`private`** members of a base class. You cannot access **`private`** or **`protected`** members of class instances. +## Remarks + +Members of a derived class can't access **`private`** members of a base class. You can't access **`private`** or **`protected`** members of class instances. ## Example -The following sample generates C2248 when private or protected members of a class are accessed from outside the class. To fix this issue, do not access these members directly outside the class. Use public member data and member functions to interact with the class. +The following sample generates C2248 when `private` or `protected` members of a class are accessed from outside the class. To fix this issue, don't access these members directly outside the class. Use `public` member data and member functions to interact with the class. ```cpp // C2248_access.cpp @@ -44,7 +46,7 @@ int main() { } ``` -Another conformance issue that exposes C2248 is the use of template friends and specialization. To fix this issue, declare friend template functions by using either an empty template parameter list <> or specific template parameters. +Another conformance issue that exposes C2248 is the use of template friends and specialization. To fix this issue, declare friend function templates by using either an empty template parameter list `<>` or specific template parameters. ```cpp // C2248_template.cpp @@ -72,7 +74,7 @@ int main() { } ``` -Another conformance issue that exposes C2248 is when you attempt to declare a friend of a class and when the class is not visible to the friend declaration in the scope of the class. To fix this issue, grant friendship to the enclosing class. +Here's another conformance issue that exposes C2248: You attempt to declare a friend of a class, but the class isn't visible to the friend declaration in the scope of the class. To fix this issue, grant friendship to the enclosing class. ```cpp // C2248_enclose.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2283.md b/docs/error-messages/compiler-errors-1/compiler-error-c2283.md index 2c01122914..52b1375800 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2283.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2283.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2283" title: "Compiler Error C2283" +description: "Learn more about: Compiler Error C2283" ms.date: "11/04/2016" f1_keywords: ["C2283"] helpviewer_keywords: ["C2283"] -ms.assetid: 8a5b3175-b480-4598-a1f7-0b50504c5caa --- # Compiler Error C2283 -'identifier' : pure specifier or abstract override specifier not allowed on unnamed struct +> '*identifier*': pure specifier or abstract override specifier not allowed on unnamed struct A member function of an unnamed class or structure is declared with a pure specifier, which is not permitted. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2299.md b/docs/error-messages/compiler-errors-1/compiler-error-c2299.md index a3ad1a5dfd..16cf37d4d9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2299.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2299.md @@ -8,11 +8,15 @@ ms.assetid: d001c2bc-f6fd-47aa-8e42-0eb824d6441d --- # Compiler Error C2299 -'function' : behavior change: an explicit specialization can not be a copy constructor or copy assignment operator +> '*function*': behavior change: an explicit specialization can not be a copy constructor or copy assignment operator -This error can also be generated as a result of compiler conformance work that was done for Visual Studio 2005: previous versions of Visual C++ allowed explicit specializations for a copy constructor or a copy assignment operator. +## Remarks -To resolve C2299, do not make the copy constructor or assignment operator a template function, but rather a non-template function that takes a class type. Any code that calls the copy constructor or assignment operator by explicitly specifying the template arguments needs to remove the template arguments. +This error can also be generated as a result of compiler conformance work that was done for Visual Studio 2005. Previous versions of Visual C++ allowed explicit specializations for a copy constructor or a copy assignment operator. + +To resolve C2299, don't make the copy constructor or assignment operator a function template. Make them non-template functions that take a class type. Any code that calls the copy constructor or assignment operator by explicitly specifying the template arguments needs to remove the template arguments. + +## Example The following sample generates C2299: diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2323.md b/docs/error-messages/compiler-errors-1/compiler-error-c2323.md new file mode 100644 index 0000000000..d17cf401d9 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2323.md @@ -0,0 +1,31 @@ +--- +title: "Compiler Error C2323" +description: "Learn more about: Compiler Error C2323" +ms.date: "03/20/2024" +f1_keywords: ["C2323"] +helpviewer_keywords: ["C2323"] +--- +# Compiler Error C2323 + +'identifier': non-member operator `new` or `delete` functions may not be declared `static` or in a namespace other than the global namespace. + +The `new` and `delete` overload operators must be non-static, defined in the global namespace or as class members. + +The following generates C2323: + +```cpp +// C2323.cpp +// compile with: /c +static void* operator new(size_t); // C2323 since static +static void operator delete(void*); // C2323 since static + +namespace NS +{ + void* operator new(size_t); // C2323 since not defined in the global namespace + void operator delete(void*); // C2323 since not defined in the global namespace +} +``` + +## See also + +[`new` and `delete` operators](../../cpp/new-and-delete-operators.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2338.md b/docs/error-messages/compiler-errors-1/compiler-error-c2338.md index 0906fb0bbf..1ab34e8a9b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2338.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2338.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Compiler Error C2338" title: "Compiler Error C2338" -ms.date: "11/04/2016" +ms.date: 02/22/2022 f1_keywords: ["C2338"] helpviewer_keywords: ["C2338"] ms.assetid: 49bba575-1de4-4963-86c6-ce3226a2ba51 @@ -10,9 +10,9 @@ ms.assetid: 49bba575-1de4-4963-86c6-ce3226a2ba51 > *Error message* -This error can be caused by a **`static_assert`** error during compilation. The message is supplied by the **`static_assert`** parameters. +Error C2338 can be caused by a **`static_assert`** error during compilation. The message is supplied by the **`static_assert`** parameters. -This error message can also be generated by external providers to the compiler. In most cases, these errors are reported by an attribute provider DLL, such as ATLPROV. Some common forms of this message include: +Error C2338 can also be generated by external providers to the compiler. In most cases, these errors are reported by an attribute provider DLL, such as ATLPROV. Some common forms of this message include: - '*attribute*' Atl Attribute Provider : error ATL*number* *message* @@ -23,3 +23,27 @@ This error message can also be generated by external providers to the compiler. These errors are often unrecoverable, and may be followed by a fatal compiler error. To fix these issues, correct the attribute usage. For example, in some cases, attribute parameters must be declared before they can be used. If an ATL error number is provided, check the documentation for that error for more specific information. + +In Standard C++11 and later, **`constexpr`** functions are no longer considered **`noexcept`** by default when used in a constant expression. This behavior change comes from the resolution of Core Working Group (CWG) [CWG 1351](https://wg21.link/cwg1351) and is enabled in [`/permissive-`](../../build/reference/permissive-standards-conformance.md) mode. The following example compiles in Visual Studio 2019 version 16.1 and earlier, but produces C2338 in Visual Studio 2019 version 16.2: + +```cpp +// c2338.cpp +// Compile using: cl /EHsc /W4 /permissive- c2338.cpp +constexpr int f() { return 0; } + +int main() { + static_assert(noexcept(f()), "f should be noexcept"); // C2338 in 16.2 +} +``` + +To fix the error, add the **`noexcept`** expression to the function declaration: + +```cpp +// c2338_fixed.cpp +// Compile using: cl /EHsc /W4 /permissive- c2338_fixed.cpp +constexpr int f() noexcept { return 0; } + +int main() { + static_assert(noexcept(f()), "f should be noexcept"); +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2345.md b/docs/error-messages/compiler-errors-1/compiler-error-c2345.md index 50933b2e64..4044e32b0e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2345.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2345.md @@ -12,11 +12,11 @@ align(value) : illegal alignment value You passed a value to the [align](../../cpp/align-cpp.md) keyword that is outside the allowable range. -The following code generates C2345 +The following sample generates C2345: ```cpp // C2345.cpp // compile with: /c -__declspec(align(0)) int a; // C2345 -__declspec(align(1)) int a; // OK +__declspec(align(8)) int a; // OK +__declspec(align(16384)) int b; // C2345 ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2385.md b/docs/error-messages/compiler-errors-1/compiler-error-c2385.md index 36b74b5946..073c282ce9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2385.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2385.md @@ -1,66 +1,63 @@ --- description: "Learn more about: Compiler Error C2385" title: "Compiler Error C2385" -ms.date: "11/04/2016" +ms.date: "1/19/2024" f1_keywords: ["C2385"] helpviewer_keywords: ["C2385"] -ms.assetid: 6d3dd1f2-e56d-49d7-865c-6a9acdb17417 --- # Compiler Error C2385 -ambiguous access of 'member' +> ambiguous access of 'member' -The member can derive from more than one object (it is inherited from more than one object). To resolve this error, +A member is inherited from more than one base type, making unqualified access to that member ambiguous. To resolve this error: -- Make the member unambiguous by providing a cast. - -- Rename the ambiguous members in the base classes. +- Explicitly qualify access to the member. +- Cast the object to the base class containing the member before accessing the member. +- Rename the ambiguous member in the base class. +- Bring the member into scope. ## Example -The following sample generates C2385. +The following sample generates C2385: ```cpp // C2385.cpp -// C2385 expected -#include - struct A { - void x(int i) - { - printf_s("\nIn A::x"); - } + void func1(int i) {} + void func2() {} }; struct B { - void x(char c) - { - printf_s("\nIn B::x"); - } + void func1(char c) {} + void func2() {} }; -// Delete the following line to resolve. -struct C : A, B {} - -// Uncomment the following 4 lines to resolve. -// struct C : A, B -// { -// using B::x; -// using A::x; -// }; +struct C : A, B +{ + // Uncomment the following lines to resolve the first 2 errors + // The error below for the call to c.func2() will remain + // using A::func1; + // using B::func1; +}; int main() { - C aC; - aC.x(100); - aC.x('c'); -} + C c; -struct C : A, B -{ - using B::x; - using A::x; -}; + c.func1(123); // C2385 + c.func1('a'); // C2385 + c.func2(); // C2385 + + c.A::func2(); // OK because explicitly qualified + c.B::func2(); // OK because explicitly qualified + static_cast(c).func2(); // OK because of the cast + static_cast(c).func2(); // OK because of the cast +} ``` + +You can resolve the ambiguous calls to `func1` by bringing both overloads into scope. However, this doesn't work for `func2` because `A::func2` and `B::func2` don't take arguments, so calling them can't be differentiated by their parameters. You can resolve the issue by: +- Introduce the one you want to use into scope +- Explicitly qualify the call with the base type +- Cast the object before calling the function. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2394.md b/docs/error-messages/compiler-errors-1/compiler-error-c2394.md index 14b86fb044..7e5ede5979 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2394.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2394.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2394" title: "Compiler Error C2394" +description: "Learn more about: Compiler Error C2394" ms.date: "11/04/2016" f1_keywords: ["C2394"] helpviewer_keywords: ["C2394"] -ms.assetid: 653fa9a0-29b3-48aa-bc01-82f98f717a2b --- # Compiler Error C2394 -'your_type::operator'op'" : CLR or WinRToperator not valid. At least one parameter must be of the following types: 'T^', 'T^%', 'T^&', where T = 'your_type' +'*type*::operator *operator*': CLR/WinRT operator not valid. At least one parameter must be of the following types: 'T^', 'T^%', 'T^&', where T = 'type' An operator in a Windows Runtime or managed type did not have at least one parameter whose type is the same as the type of the operator return value. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2397.md b/docs/error-messages/compiler-errors-1/compiler-error-c2397.md index c73c5fe9b3..56f0115468 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2397.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2397.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Compiler Error C2397" title: "Compiler Error C2397" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2397" +ms.date: 11/04/2016 f1_keywords: ["C2397"] -ms.assetid: b418cf5a-d50d-4a6c-98a7-994ae35046d1 +helpviewer_keywords: ["C2397"] --- # Compiler Error C2397 @@ -15,26 +15,22 @@ The C language allows implicit narrowing conversions in assignments and initiali A narrowing conversion can be okay when you know the possible range of converted values can fit in the target. In this case, you know more than the compiler does. If you make a narrowing conversion intentionally, make your intentions explicit by using a static cast. Otherwise, this error message almost always indicates you have a bug in your code. You can fix it by making sure the objects you initialize have types that are large enough to handle the inputs. -The following sample generates C2397 and shows one way to fix it: - -``` -// C2397.cpp -- C++ narrowing conversion diagnostics -// Compile by using: cl /EHsc C2397.cpp -#include +The following sample generates C2397: -struct S1 { - int m1; - double m2, m3; +```cpp +// C2397.cpp +// compile with: /c +struct S { + int m1; + double m2, m3; }; -void function_C2397(double d1) { - char c1 { 127 }; // OK - char c2 { 513 }; // error C2397 - - std::vector vS1; - vS1.push_back({ d1, 2, 3 }); // error C2397 - - // Possible fix if you know d1 always fits in an int - vS1.push_back({ static_cast(d1), 2, 3 }); +void func(double d1) { + char c1 { 127 }; // OK + char c2 { 513 }; // C2397 + + S arr[2]{}; + arr[0] = { d1, 2.0, 3.0 }; // C2397 + arr[1] = { static_cast(d1), 2.0, 3.0 }; // OK } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2433.md b/docs/error-messages/compiler-errors-1/compiler-error-c2433.md index 614e07b1be..75ec082785 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2433.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2433.md @@ -1,26 +1,24 @@ --- -description: "Learn more about: Compiler Error C2433" title: "Compiler Error C2433" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2433" +ms.date: 05/25/2025 f1_keywords: ["C2433"] helpviewer_keywords: ["C2433"] -ms.assetid: 7079fedd-6059-4125-82ef-ebe275f1f9d1 --- # Compiler Error C2433 -'identifier' : 'modifier' not permitted on data declarations +> '*identifier*': '*modifier*' not permitted on data declarations The **`friend`**, **`virtual`**, and **`inline`** modifiers cannot be used for data declarations. ## Example -The following sample generates C2433. +The following example generates C2433: ```cpp // C2433.cpp -class C{}; - -int main() { - inline C c; // C2433 +int main() +{ + virtual int i; // C2433 } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2440.md b/docs/error-messages/compiler-errors-1/compiler-error-c2440.md index 218b5f7a3d..d12b621c4a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2440.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2440.md @@ -1,18 +1,17 @@ --- -description: "Learn about type conversion errors that cause Compiler Error C2440." title: "Compiler Error C2440" +description: "Learn about type conversion errors that cause Compiler Error C2440." ms.date: 08/27/2021 f1_keywords: ["C2440"] helpviewer_keywords: ["C2440"] no-loc: ["struct", "const"] -ms.assetid: 36e6676c-f04f-4715-8ba1-f096c4bf3b44 --- # Compiler Error C2440 > '*initializing*' : cannot convert from '*type1*' to '*type2*'\ > '*conversion*' : cannot convert from '*type1*' to '*type2*' -The compiler can't implicitly convert from `*type1*` to `*type2*`, or can't use the specified cast or conversion operator. +The compiler can't implicitly convert from *`type1`* to *`type2`*, or can't use the specified cast or conversion operator. ## Remarks diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2450.md b/docs/error-messages/compiler-errors-1/compiler-error-c2450.md index 6a4d09afad..ac6c260ef8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2450.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2450.md @@ -4,7 +4,6 @@ title: "Compiler Error C2450" ms.date: "11/04/2016" f1_keywords: ["C2450"] helpviewer_keywords: ["C2450"] -ms.assetid: 929f1c06-8774-468b-be2a-f428757875a2 --- # Compiler Error C2450 @@ -16,23 +15,26 @@ The following sample generates C2450: ```cpp // C2450.cpp -class X { +class X +{ public: int i; } x; -class Y { +class Y +{ public: int i; operator int() { return i; } // conversion operator } y; -int main() { - int j = 1; - switch ( x ) { // C2450, x is not type int - // try the following line instead - // switch ( y ) { - default: ; +int main() +{ + switch ( x ) + { // C2450, x is not type int + // try the following line instead + // switch ( y ) { + default: ; } } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2466.md b/docs/error-messages/compiler-errors-1/compiler-error-c2466.md index ae382ccd5f..34e0cca594 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2466.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2466.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2466" title: "Compiler Error C2466" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2466" +ms.date: "03/19/2025" f1_keywords: ["C2466"] helpviewer_keywords: ["C2466"] -ms.assetid: 75b251d1-7d0b-4a86-afca-26adedf74486 --- # Compiler Error C2466 -cannot allocate an array of constant size 0 +> cannot allocate an array of constant size 0 An array is allocated or declared with size zero. The constant expression for the array size must be an integer greater than zero. An array declaration with a zero subscript is legal only for a class, structure, or union member and only with Microsoft extensions ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)). @@ -17,7 +16,6 @@ The following sample generates C2466: ```cpp // C2466.cpp // compile with: /c -int i[0]; // C2466 -int j[1]; // OK -char *p; +int arr1[0]; // C2466 +int arr2[1]; // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2470.md b/docs/error-messages/compiler-errors-1/compiler-error-c2470.md index 1070a0128b..d0bc5eda5a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2470.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2470.md @@ -1,26 +1,34 @@ --- -description: "Learn more about: Compiler Error C2470" title: "Compiler Error C2470" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2470" +ms.date: "03/29/2025" f1_keywords: ["C2470"] helpviewer_keywords: ["C2470"] -ms.assetid: e17d2cb8-b84c-447c-976a-625f0c96f3fe --- # Compiler Error C2470 -'function' : looks like a function definition, but there is no parameter list; skipping apparent body +> '*function*': looks like a function definition, but there is no parameter list; skipping apparent body A function definition is missing its argument list. -The following sample generates C2470: +## Example + +The following example generates C2470: ```cpp // C2470.cpp -int MyFunc {}; // C2470 -void MyFunc2() {}; //OK +// compile with: /c +template +class C +{ + int func(); +}; -int main(){ - MyFunc(); - MyFunc2(); +template +int C::func // C2470 +// Use the following line to resolve the error: +// int C::func() +{ + return 0; } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2487.md b/docs/error-messages/compiler-errors-1/compiler-error-c2487.md index 2f3cb10645..29a8a9beeb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2487.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2487.md @@ -1,13 +1,29 @@ --- description: "Learn more about: Compiler Error C2487" title: "Compiler Error C2487" -ms.date: "11/04/2016" +ms.date: "03/04/2024" f1_keywords: ["C2487"] helpviewer_keywords: ["C2487"] -ms.assetid: 95d734fb-64ac-488d-b799-64f084eecb09 --- # Compiler Error C2487 'identifier' : member of dll interface class may not be declared with dll interface You can declare a whole class, or certain members of a non-DLL interface class, with DLL interface. You cannot declare a class with DLL interface and then declare a member of that class with DLL interface. + +The following sample generates C2487: + +```cpp +// C2487.cpp +// compile with: /c +class __declspec(dllexport) C +{ + __declspec(dllexport) void func() {} // C2487 +}; +``` + +To resolve this error, remove the DLL interface on the class or the members. + +## See also + +[Using `dllimport` and `dllexport` in C++ classes](../../cpp/using-dllimport-and-dllexport-in-cpp-classes.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2000-c3999.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2000-c3999.md index e43aa5e56b..41ec42f58d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2000-c3999.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2000-c3999.md @@ -1,15 +1,15 @@ --- -description: "Learn about compiler errors C2000 - C3999 and C7000 - C7999." -title: "Compiler errors C2000 - C3999, C7000 - C7999" +description: "Learn about compiler errors C2001 - C3999 and C7000 - C7999." +title: "Compiler errors C2001 - C3999, C7000 - C7999" ms.date: 04/18/2021 --- -# Compiler errors C2000 - C3999, C7000 - C7999 +# Compiler errors C2001 - C3999, C7000 - C7999 The articles in this section of the documentation explain a subset of the error messages that are generated by the Microsoft C/C++ compiler. ## In this section -[Compiler errors C2000 through C2099](../compiler-errors-1/compiler-errors-c2001-through-c2099.md) \ +[Compiler errors C2001 through C2099](../compiler-errors-1/compiler-errors-c2001-through-c2099.md) \ [Compiler errors C2100 through C2199](../compiler-errors-1/compiler-errors-c2100-through-c2199.md) \ [Compiler errors C2200 through C2299](../compiler-errors-1/compiler-errors-c2200-through-c2299.md) \ [Compiler errors C2300 through C2399](../compiler-errors-1/compiler-errors-c2300-through-c2399.md) \ diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md index 9da4fe0ae9..d12d6a6217 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Compiler errors C2000 through C2099" -title: "Compiler errors C2000 through C2099" -ms.date: "04/21/2019" -f1_keywords: ["C2000", "C2016", "C2023", "C2024", "C2025", "C2029", "C2031", "C2035", "C2037", "C2038", "C2049", "C2068", "C2076", "C2080", "C2096", "C2098"] -helpviewer_keywords: ["C2000", "C2016", "C2023", "C2024", "C2025", "C2029", "C2031", "C2035", "C2037", "C2038", "C2049", "C2068", "C2076", "C2080", "C2096", "C2098"] -ms.assetid: d99a19eb-eeeb-4181-9b33-9cbe4459767b +description: "Learn more about: Compiler errors C2001 through C2099" +title: "Compiler errors C2001 through C2099" +ms.date: 08/24/2022 +f1_keywords: ["C2029"] +helpviewer_keywords: ["C2029"] --- -# Compiler errors C2000 through C2099 +# Compiler errors C2001 through C2099 The articles in this section of the documentation explain a subset of the error messages that are generated by the compiler. @@ -14,110 +13,109 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|Compiler error C2000|UNKNOWN ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Compiler error C2001](compiler-error-c2001.md)|newline in constant| -|[Compiler error C2002](compiler-error-c2002.md)|invalid wide-character constant| -|[Compiler error C2003](compiler-error-c2003.md)|expected 'defined id'| -|[Compiler error C2004](compiler-error-c2004.md)|expected 'defined(id)'| -|[Compiler error C2005](compiler-error-c2005.md)|#line expected a line number, found '*token*'| -|[Compiler error C2006](compiler-error-c2006.md)|'*directive*': expected a filename, found '*token*'| -|[Compiler error C2007](compiler-error-c2007.md)|#define syntax| -|[Compiler error C2008](compiler-error-c2008.md)|'*character*': unexpected in macro definition| -|[Compiler error C2009](compiler-error-c2009.md)|reuse of macro formal '*identifier*'| -|[Compiler error C2010](compiler-error-c2010.md)|'*character*': unexpected in macro formal parameter list| -|[Compiler error C2011](compiler-error-c2011.md)|'*identifier*': '*type*' type redefinition| -|[Compiler error C2012](compiler-error-c2012.md)|missing name following '<'| -|[Compiler error C2013](compiler-error-c2013.md)|missing '>'| -|[Compiler error C2014](compiler-error-c2014.md)|preprocessor command must start as first nonwhite space| -|[Compiler error C2015](compiler-error-c2015.md)|too many characters in constant| -|Compiler error C2016|C requires that a struct or union has at least one member| -|[Compiler error C2017](compiler-error-c2017.md)|illegal escape sequence| -|[Compiler error C2018](compiler-error-c2018.md)|unknown character '0x*value*'| -|[Compiler error C2019](compiler-error-c2019.md)|expected preprocessor directive, found '*character*'| -|[Compiler error C2020](compiler-error-c2020.md)|'*member*': '*class*' member redefinition| -|[Compiler error C2021](compiler-error-c2021.md)|expected exponent value, not '*character*'| -|[Compiler error C2022](compiler-error-c2022.md)|'*number*': too big for character| -|Compiler error C2023|'*identifier*': Alignment (*number1*) different from prior declaration (*number2*)| -|Compiler error C2024|'alignas' attribute applies to variables, data members and tag types only| -|Compiler error C2025|invalid or corrupted binary module interface file: '*filename*'| -|[Compiler error C2026](compiler-error-c2026.md)|string too big, trailing characters truncated| -|[Compiler error C2027](compiler-error-c2027.md)|use of undefined type '*type*'| -|[Compiler error C2028](compiler-error-c2028.md)|struct/union member must be inside a struct/union| -|Compiler error C2029|left of '*token*' specifies undefined class/struct/interface '*identifier*'| -|[Compiler error C2030](compiler-error-c2030.md)|a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed'| -|Compiler error C2031|a virtual destructor with '*accessibility*' accessibility is not allowed for this type| -|[Compiler error C2032](compiler-error-c2032.md)|'*identifier*': function cannot be member of struct/union '*type*'| -|[Compiler error C2033](compiler-error-c2033.md)|'*identifier*': bit field cannot have indirection| -|[Compiler error C2034](compiler-error-c2034.md)|'*identifier*': type of bit field too small for number of bits| -|Compiler error C2035|a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type| -|[Compiler error C2036](compiler-error-c2036.md)|'*identifier*': unknown size| -|Compiler error C2037|left of '*identifier*' specifies undefined struct/union '*type*'| -|Compiler error C2038|the std namespace cannot be inline| -|[Compiler error C2039](compiler-error-c2039.md)|'*identifier1*': is not a member of '*identifier2*'| -|[Compiler error C2040](compiler-error-c2040.md)|'*operator*': '*identifier1*' differs in levels of indirection from '*identifier2*'| -|[Compiler error C2041](compiler-error-c2041.md)|illegal digit '*character*' for base '*number*'| -|[Compiler error C2042](compiler-error-c2042.md)|signed/unsigned keywords mutually exclusive| -|[Compiler error C2043](compiler-error-c2043.md)|illegal break| -|[Compiler error C2044](compiler-error-c2044.md)|illegal continue| -|[Compiler error C2045](compiler-error-c2045.md)|'*identifier*': label redefined| -|[Compiler error C2046](compiler-error-c2046.md)|illegal case| -|[Compiler error C2047](compiler-error-c2047.md)|illegal default| -|[Compiler error C2048](compiler-error-c2048.md)|more than one default| -|Compiler error C2049|'*identifier*': non-inline namespace cannot be reopened as inline| -|[Compiler error C2050](compiler-error-c2050.md)|switch expression not integral| -|[Compiler error C2051](compiler-error-c2051.md)|case expression not constant| -|[Compiler error C2052](compiler-error-c2052.md)|'*type*': illegal type for case expression| -|[Compiler error C2053](compiler-error-c2053.md)|'*identifier*': wide string mismatch| -|[Compiler error C2054](compiler-error-c2054.md)|expected '(' to follow '*identifier*'| -|[Compiler error C2055](compiler-error-c2055.md)|expected formal parameter list, not a type list| -|[Compiler error C2056](compiler-error-c2056.md)|illegal expression| -|[Compiler error C2057](compiler-error-c2057.md)|expected constant expression| -|[Compiler error C2058](compiler-error-c2058.md)|constant expression is not integral| -|[Compiler error C2059](compiler-error-c2059.md)|syntax error: '*token*'| -|[Compiler error C2060](compiler-error-c2060.md)|syntax error: end of file found| -|[Compiler error C2061](compiler-error-c2061.md)|syntax error: identifier '*identifier*'| -|[Compiler error C2062](compiler-error-c2062.md)|type '*type*' unexpected| -|[Compiler error C2063](compiler-error-c2063.md)|'*identifier*': not a function| -|[Compiler error C2064](compiler-error-c2064.md)|term does not evaluate to a function taking *number* arguments| -|[Compiler error C2065](compiler-error-c2065.md)|'*identifier*': undeclared identifier| -|[Compiler error C2066](compiler-error-c2066.md)|cast to function type is illegal| -|[Compiler error C2067](compiler-error-c2067.md)|cast to array type is illegal| -|Compiler error C2068|illegal use of overloaded function. Missing argument list?| -|[Compiler error C2069](compiler-error-c2069.md)|cast of 'void' term to non-'void'| -|[Compiler error C2070](compiler-error-c2070.md)|'*type*': illegal sizeof operand| -|[Compiler error C2071](compiler-error-c2071.md)|'*identifier*': illegal storage class| -|[Compiler error C2072](compiler-error-c2072.md)|'*identifier*': initialization of a function| -|[Compiler error C2073](compiler-error-c2073.md)|'*identifier*': elements of partially initialized array must have a default constructor| -|[Compiler error C2074](compiler-error-c2074.md)|'*identifier*': '*type*' initialization requires a brace-enclosed initializer list| -|[Compiler error C2075](compiler-error-c2075.md)|'*identifier*': array initialization requires a brace-enclosed initializer list| -|Compiler error C2076|a brace-enclosed initializer list cannot be used in a new-expression whose type contains '*type*'| -|[Compiler error C2077](compiler-error-c2077.md)|non-scalar field initializer '*identifier*'| -|[Compiler error C2078](compiler-error-c2078.md)|too many initializers| -|[Compiler error C2079](compiler-error-c2079.md)|'*identifier*' uses undefined struct/class/union '*type*'| -|Compiler error C2080|'*identifier*': the type for '*type*' can only be deduced from a single initializer expression| -|[Compiler error C2081](compiler-error-c2081.md)|'*identifier*': name in formal parameter list illegal| -|[Compiler error C2082](compiler-error-c2082.md)|redefinition of formal parameter '*identifier*'| -|[Compiler error C2083](compiler-error-c2083.md)|struct/union comparison illegal| -|[Compiler error C2084](compiler-error-c2084.md)|function '*identifier*' already has a body| -|[Compiler error C2085](compiler-error-c2085.md)|'*identifier*': not in formal parameter list| -|[Compiler error C2086](compiler-error-c2086.md)|'*identifier*': redefinition| -|[Compiler error C2087](compiler-error-c2087.md)|'*identifier*': missing subscript| -|[Compiler error C2088](compiler-error-c2088.md)|'*operator*': illegal for struct/class/union| -|[Compiler error C2089](compiler-error-c2089.md)|'*identifier*': '*type*' too large| -|[Compiler error C2090](compiler-error-c2090.md)|function returns array| -|[Compiler error C2091](compiler-error-c2091.md)|function returns function| -|[Compiler error C2092](compiler-error-c2092.md)|'*identifier*' array element type cannot be function| -|[Compiler error C2093](compiler-error-c2093.md)|'*identifier1*': cannot be initialized using address of automatic variable '*identifier2*'| -|[Compiler error C2094](compiler-error-c2094.md)|label '*identifier*' was undefined| -|[Compiler error C2095](compiler-error-c2095.md)|'*function*': actual parameter has type 'void': parameter *number*| -|Compiler error C2096|'*identifier*': A data member cannot be initialized with a parenthesized initializer| -|[Compiler error C2097](compiler-error-c2097.md)|illegal initialization| -|Compiler error C2098|unexpected token after data member '*identifier*'| -|[Compiler error C2099](compiler-error-c2099.md)|initializer is not a constant| +| Error | Message | +|--|--| +| [Compiler error C2001](compiler-error-c2001.md) | newline in constant | +| [Compiler error C2002](compiler-error-c2002.md) | invalid wide-character constant | +| [Compiler error C2003](compiler-error-c2003.md) | expected 'defined id' | +| [Compiler error C2004](compiler-error-c2004.md) | expected 'defined(id)' | +| [Compiler error C2005](compiler-error-c2005.md) | #line expected a line number, found '*token*' | +| [Compiler error C2006](compiler-error-c2006.md) | '*directive*': expected `"FILENAME"` or `` | +| [Compiler error C2007](compiler-error-c2007.md) | #define syntax | +| [Compiler error C2008](compiler-error-c2008.md) | '*character*': unexpected in macro definition | +| [Compiler error C2009](compiler-error-c2009.md) | cannot reuse macro parameter name '*identifier*' | +| [Compiler error C2010](compiler-error-c2010.md) | '*character*': unexpected in macro formal parameter list | +| [Compiler error C2011](compiler-error-c2011.md) | '*identifier*': '*type*' type redefinition | +| [Compiler error C2012](compiler-error-c2012.md) | missing name following '<' | +| [Compiler error C2013](compiler-error-c2013.md) | expected a '*token*' | +| [Compiler error C2014](compiler-error-c2014.md) | preprocessor command must start as first nonwhite space | +| [Compiler error C2015](compiler-error-c2015.md) | too many characters in constant | +| [Compiler error C2016](compiler-error-c2016.md) | C requires that a struct or union has at least one member | +| [Compiler error C2017](compiler-error-c2017.md) | illegal escape sequence | +| [Compiler error C2018](compiler-error-c2018.md) | unknown character '0x*value*' | +| [Compiler error C2019](compiler-error-c2019.md) | expected preprocessor directive, found '*character*' | +| [Compiler error C2020](compiler-error-c2020.md) | '*member*': '*class*' member redefinition | +| [Compiler error C2021](compiler-error-c2021.md) | expected exponent value, not '*character*' | +| [Compiler error C2022](compiler-error-c2022.md) | '*number*': too big for character | +| [Compiler error C2023](compiler-error-c2023.md) | '*identifier*': Alignment (*value-1*) different from prior declaration (*value-2*) | +| [Compiler error C2024](compiler-error-c2024.md) | 'alignas' attribute applies to variables, data members and tag types only | +| [Compiler error C2025](compiler-error-c2025.md) | invalid or corrupted binary module interface file: '*filename*' | +| [Compiler error C2026](compiler-error-c2026.md) | string too big, trailing characters truncated | +| [Compiler error C2027](compiler-error-c2027.md) | use of undefined type '*type*' | +| [Compiler error C2028](compiler-error-c2028.md) | struct/union member must be inside a struct/union | +| Compiler error C2029 | **(Obsolete)** left of '*token*' specifies undefined class/struct/interface '*identifier*' | +| [Compiler error C2030](compiler-error-c2030.md) | a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed' | +| [Compiler error C2031](compiler-error-c2031.md) | a virtual destructor with '*accessibility*' accessibility is not allowed for this type | +| [Compiler error C2032](compiler-error-c2032.md) | '*identifier*': function cannot be member of struct/union '*type*' | +| [Compiler error C2033](compiler-error-c2033.md) | '*identifier*': bit field cannot have indirection | +| [Compiler error C2034](compiler-error-c2034.md) | '*identifier*': type of bit field too small for number of bits | +| [Compiler error C2035](compiler-error-c2035.md) | a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type | +| [Compiler error C2036](compiler-error-c2036.md) | '*identifier*': unknown size | +| [Compiler error C2037](compiler-error-c2037.md) | left of '*operator*' specifies undefined struct/union '*type*' | +| [Compiler error C2038](compiler-error-c2038.md) | the std namespace cannot be inline | +| [Compiler error C2039](compiler-error-c2039.md) | '*identifier1*': is not a member of '*identifier2*' | +| [Compiler error C2040](compiler-error-c2040.md) | '*operator*': '*identifier1*' differs in levels of indirection from '*identifier2*' | +| [Compiler error C2041](compiler-error-c2041.md) | illegal digit '*character*' for base '*number*' | +| [Compiler error C2042](compiler-error-c2042.md) | signed/unsigned keywords mutually exclusive | +| [Compiler error C2043](compiler-error-c2043.md) | illegal break | +| [Compiler error C2044](compiler-error-c2044.md) | illegal continue | +| [Compiler error C2045](compiler-error-c2045.md) | '*identifier*': label redefined | +| [Compiler error C2046](compiler-error-c2046.md) | illegal case | +| [Compiler error C2047](compiler-error-c2047.md) | illegal default | +| [Compiler error C2048](compiler-error-c2048.md) | more than one default | +| [Compiler error C2049](compiler-error-c2049.md) | '*namespace-name*': non-inline namespace cannot be reopened as inline | +| [Compiler error C2050](compiler-error-c2050.md) | switch expression not integral | +| [Compiler error C2051](compiler-error-c2051.md) | case expression not constant | +| [Compiler error C2052](compiler-error-c2052.md) | '*type*': illegal type for case expression | +| [Compiler error C2053](compiler-error-c2053.md) | '*identifier*': wide string mismatch | +| [Compiler error C2054](compiler-error-c2054.md) | expected '(' to follow '*identifier*' | +| [Compiler error C2055](compiler-error-c2055.md) | expected formal parameter list, not a type list | +| [Compiler error C2056](compiler-error-c2056.md) | illegal expression | +| [Compiler error C2057](compiler-error-c2057.md) | expected constant expression | +| [Compiler error C2058](compiler-error-c2058.md) | constant expression is not integral | +| [Compiler error C2059](compiler-error-c2059.md) | syntax error: '*token*' | +| [Compiler error C2060](compiler-error-c2060.md) | syntax error: end of file found | +| [Compiler error C2061](compiler-error-c2061.md) | syntax error: identifier '*identifier*' | +| [Compiler error C2062](compiler-error-c2062.md) | type '*type*' unexpected | +| [Compiler error C2063](compiler-error-c2063.md) | '*identifier*': not a function | +| [Compiler error C2064](compiler-error-c2064.md) | term does not evaluate to a function taking *number* arguments | +| [Compiler error C2065](compiler-error-c2065.md) | '*identifier*': undeclared identifier | +| [Compiler error C2066](compiler-error-c2066.md) | cast to function type is illegal | +| [Compiler error C2067](compiler-error-c2067.md) | cast to array type is illegal | +| [Compiler error C2068](compiler-error-c2068.md) | illegal use of overloaded function. Missing argument list? | +| [Compiler error C2069](compiler-error-c2069.md) | cast of 'void' term to non-'void' | +| [Compiler error C2070](compiler-error-c2070.md) | '*type*': illegal sizeof operand | +| [Compiler error C2071](compiler-error-c2071.md) | '*identifier*': illegal storage class | +| [Compiler error C2072](compiler-error-c2072.md) | '*identifier*': initialization of a function | +| [Compiler error C2073](compiler-error-c2073.md) | **(Obsolete)** '*identifier*': elements of partially initialized array must have a default constructor | +| [Compiler error C2074](compiler-error-c2074.md) | '*identifier*': '*type*' initialization requires a brace-enclosed initializer list | +| [Compiler error C2075](compiler-error-c2075.md) | '*identifier*': initialization requires a brace-enclosed initializer list | +| [Compiler error C2076](compiler-error-c2076.md) | a brace-enclosed initializer list cannot be used in a new-expression whose type contains '*type*' | +| [Compiler error C2077](compiler-error-c2077.md) | non-scalar field initializer '*identifier*' | +| [Compiler error C2078](compiler-error-c2078.md) | too many initializers | +| [Compiler error C2079](compiler-error-c2079.md) | '*identifier*' uses undefined struct/class/union '*type*' | +| [Compiler error C2080](compiler-error-c2080.md) | '*identifier*': the type for '*type*' can only be deduced from a single initializer expression | +| [Compiler error C2081](compiler-error-c2081.md) | '*identifier*': name in formal parameter list illegal | +| [Compiler error C2082](compiler-error-c2082.md) | redefinition of formal parameter '*identifier*' | +| [Compiler error C2083](compiler-error-c2083.md) | struct/union comparison illegal | +| [Compiler error C2084](compiler-error-c2084.md) | function '*identifier*' already has a body | +| [Compiler error C2085](compiler-error-c2085.md) | '*identifier*': not in formal parameter list | +| [Compiler error C2086](compiler-error-c2086.md) | '*identifier*': redefinition | +| [Compiler error C2087](compiler-error-c2087.md) | '*identifier*': missing subscript | +| [Compiler error C2088](compiler-error-c2088.md) | built-in operator '*operator*' cannot be applied to an operand of type '*class type*' | +| [Compiler error C2089](compiler-error-c2089.md) | '*identifier*': '*type*' too large | +| [Compiler error C2090](compiler-error-c2090.md) | function returns array | +| [Compiler error C2091](compiler-error-c2091.md) | function returns function | +| [Compiler error C2092](compiler-error-c2092.md) | '*identifier*' array element type cannot be function or abstract class type | +| [Compiler error C2093](compiler-error-c2093.md) | '*identifier1*': cannot be initialized using address of automatic variable '*identifier2*' | +| [Compiler error C2094](compiler-error-c2094.md) | label '*identifier*' was undefined | +| [Compiler error C2095](compiler-error-c2095.md) | '*function*': actual parameter has type 'void': parameter *number* | +| [Compiler error C2096](compiler-error-c2096.md) | '*identifier*': A data member cannot be initialized with a parenthesized initializer | +| [Compiler error C2097](compiler-error-c2097.md) | illegal initialization | +| [Compiler error C2098](compiler-error-c2098.md) | unexpected token after data member '*identifier*' | +| [Compiler error C2099](compiler-error-c2099.md) | initializer is not a constant | ## See also [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[Compiler errors C2001 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md index 2a62b7560f..ef2e8e4b3f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C2100 through C2199" title: "Compiler errors C2100 through C2199" +description: "Learn more about: Compiler errors C2100 through C2199" ms.date: "04/21/2019" f1_keywords: ["C2119", "C2123", "C2125", "C2126", "C2127", "C2136", "C2176", "C2187", "C2189"] -helpviewer_keywords: ["C2119", "C2123", "C2125", "C2126", "C2127", "C2131", "C2136", "C2176", "C2187", "C2189"] -ms.assetid: 1ccab076-0954-4386-b959-d3112a6793ae +helpviewer_keywords: ["C2119", "C2123", "C2125", "C2126", "C2127", "C2136", "C2176", "C2187", "C2189"] --- # Compiler errors C2100 through C2199 @@ -16,7 +15,7 @@ The articles in this section of the documentation explain a subset of the error |Error|Message| |-----------|-------------| -|[Compiler error C2100](compiler-error-c2100.md)|illegal indirection| +|[Compiler error C2100](compiler-error-c2100.md)|you cannot dereference an operand of type '*type*'| |[Compiler error C2101](compiler-error-c2101.md)|'&' on constant| |[Compiler error C2102](compiler-error-c2102.md)|'&' requires l-value| |[Compiler error C2103](compiler-error-c2103.md)|'&' on register variable| @@ -32,11 +31,11 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2113](compiler-error-c2113.md)|'-': pointer can only be subtracted from another pointer| |[Compiler error C2114](compiler-error-c2114.md)|'*operator*': pointer on left; needs integral value on right| |[Compiler error C2115](compiler-error-c2115.md)|'*operator*': incompatible types| -|[Compiler error C2116](compiler-error-c2116.md)|function parameter lists differed| +|[Compiler error C2116](compiler-error-c2116.md)|'*name*': function parameter lists do not match between declarations| |[Compiler error C2117](compiler-error-c2117.md)|'*identifier*': array bounds overflow| |[Compiler error C2118](compiler-error-c2118.md)|negative subscript| |Compiler error C2119|'*identifier*': the type for '*type*' cannot be deduced from an empty initializer| -|[Compiler error C2120](compiler-error-c2120.md)|'void' illegal with all types| +|[Compiler error C2120](compiler-error-c2120.md)|'`void`' cannot be combined with any other type specifier| |[Compiler error C2121](compiler-error-c2121.md)|'#': invalid character: possibly the result of a macro expansion| |[Compiler error C2122](compiler-error-c2122.md)|'*identifier*': prototype parameter in name list illegal| |Compiler error C2123|'*identifier*': alias templates cannot be explicitly or partially specialized| @@ -51,7 +50,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2132](compiler-error-c2132.md)|syntax error: unexpected identifier| |[Compiler error C2133](compiler-error-c2133.md)|'*identifier*': unknown size| |[Compiler error C2134](compiler-error-c2134.md)|'*function*': call does not result in a constant expression| -|[Compiler error C2135](compiler-error-c2135.md)|'*operator*': illegal bit field operation| +|[Compiler error C2135](compiler-error-c2135.md)|'*identifier*': you cannot apply '*operator*' to a bit-field| |Compiler error C2136|authoring API contract not allowed| |[Compiler error C2137](compiler-error-c2137.md)|empty character constant| |[Compiler error C2138](compiler-error-c2138.md)|illegal to define an enumeration without any members| @@ -87,7 +86,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2168](compiler-error-c2168.md)|'*function*': too few actual parameters for intrinsic function| |[Compiler error C2169](compiler-error-c2169.md)|'*function*': intrinsic function, cannot be defined| |[Compiler error C2170](compiler-error-c2170.md)|'*identifier*': not declared as a function, cannot be intrinsic| -|[Compiler error C2171](compiler-error-c2171.md)|'*operator*': illegal on operands of type '*type*'| +|[Compiler error C2171](compiler-error-c2171.md)|operator '*operator*' cannot be applied to an operand of type '*type*'| |[Compiler error C2172](compiler-error-c2172.md)|'*function*': actual parameter is not a pointer: parameter *number*| |[Compiler error C2173](compiler-error-c2173.md)|'*function*': actual parameter is not a pointer: parameter *number*, parameter list *number*| |[Compiler error C2174](compiler-error-c2174.md)|'*function*': actual parameter has type 'void': parameter *number*, parameter list *number*| @@ -119,5 +118,5 @@ The articles in this section of the documentation explain a subset of the error ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[C/C++ Compiler and build tools errors and warnings](c-cpp-build-errors.md)\ +[Compiler errors C2001 - C3999, C7000 - C7999](compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2200-through-c2299.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2200-through-c2299.md index fbb78db362..061b94f169 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2200-through-c2299.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2200-through-c2299.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C2200 through C2299" title: "Compiler errors C2200 through C2299" +description: "Learn more about: Compiler errors C2200 through C2299" ms.date: "04/21/2019" -f1_keywords: ["C2202", "C2209", "C2210", "C2211", "C2214", "C2215", "C2221", "C2225", "C2230", "C2235", "C2237", "C2239", "C2240", "C2257", "C2260", "C2263", "C2265", "C2269", "C2278", "C2281", "C2282", "C2288", "C2291", "C2294"] -helpviewer_keywords: ["C2202", "C2209", "C2210", "C2211", "C2214", "C2215", "C2221", "C2225", "C2230", "C2235", "C2237", "C2239", "C2240", "C2257", "C2260", "C2263", "C2265", "C2269", "C2278", "C2281", "C2282", "C2288", "C2291", "C2294"] -ms.assetid: 9b36d11b-9510-4390-96f1-0c9235124d14 +f1_keywords: ["C2202", "C2209", "C2210", "C2211", "C2214", "C2215", "C2221", "C2225", "C2230", "C2235", "C2237", "C2239", "C2240", "C2257", "C2260", "C2263", "C2265", "C2269", "C2278", "C2281", "C2282", "C2284", "C2288", "C2291", "C2294"] +helpviewer_keywords: ["C2202", "C2209", "C2210", "C2211", "C2214", "C2215", "C2221", "C2225", "C2230", "C2235", "C2237", "C2239", "C2240", "C2257", "C2260", "C2263", "C2265", "C2269", "C2278", "C2281", "C2282", "C2284", "C2288", "C2291", "C2294"] --- # Compiler errors C2200 through C2299 @@ -36,7 +35,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2217](compiler-error-c2217.md)|'*attribute1*' requires '*attribute2*'| |[Compiler error C2218](compiler-error-c2218.md)|'*calltype*' cannot be used with '/arch:IA32'| |[Compiler error C2219](compiler-error-c2219.md)|syntax error: type qualifier must be after '*'| -|[Compiler error C2220](compiler-error-c2220.md)|warning treated as error - no '*filetype*' file generated| +|[Compiler error C2220](compiler-error-c2220.md)|the following warning is treated as an error| |Compiler error C2221|Obsolete.| |[Compiler error C2222](compiler-error-c2222.md)|unexpected type '*type*': a base-class or member was expected| |[Compiler error C2223](compiler-error-c2223.md)|left of '->*identifier*' must point to struct/union| @@ -51,7 +50,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2232](compiler-error-c2232.md)|'->*identifier*': left operand has 'class/struct/union' type, use '.'| |[Compiler error C2233](compiler-error-c2233.md)|'*identifier*': arrays of objects containing zero-size arrays are illegal| |[Compiler error C2234](compiler-error-c2234.md)|*identifier*': arrays of references are illegal| -|Compiler error C2235|Obsolete.| +|Compiler error C2235|mismatching target architecture for compiled module interface for '*architecture 1*' from '*architecture 2*'| |[Compiler error C2236](compiler-error-c2236.md)|unexpected token '*token*'. Did you forget a ';'?| |Compiler error C2237|multiple module declaration| |[Compiler error C2238](compiler-error-c2238.md)|unexpected token(s) preceding '*token*'| @@ -79,7 +78,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C2260|'*specifier*': invalid InternalsVisibleToAttribute friend assembly specifier| |[Compiler error C2261](compiler-error-c2261.md)|'*string*': assembly reference is invalid and cannot be resolved| |[Compiler error C2262](compiler-error-c2262.md)|'*specifier*': InternalsVisibleTo declarations cannot have a version, culture, or processor architecture specified| -|Compiler error C2263|Obsolete.| +|Compiler error C2263|'*module name*': a translation unit cannot be imported into itself| |[Compiler error C2264](compiler-error-c2264.md)|'*function*': error in function definition or declaration; function not called| |Compiler error C2265|Obsolete.| |[Compiler error C2266](compiler-error-c2266.md)|'*identifier*': reference to a non-constant bounded array is illegal| @@ -91,20 +90,20 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2272](compiler-error-c2272.md)|'*function*': modifiers not allowed on static member functions| |[Compiler error C2273](compiler-error-c2273.md)|'*type*': illegal as right side of '->' operator| |[Compiler error C2274](compiler-error-c2274.md)|'*type*': illegal as right side of '.' operator| -|[Compiler error C2275](compiler-error-c2275.md)|'*type*': illegal use of this type as an expression| +|[Compiler error C2275](compiler-error-c2275.md)|'*type*': expected an expression instead of a type| |[Compiler error C2276](compiler-error-c2276.md)|'*operator*': illegal operation on bound member function expression| |[Compiler error C2277](compiler-error-c2277.md)|'*function*': cannot take address of this member function| -|Compiler error C2278|Obsolete.| +|Compiler error C2278|'*token*': unexpected token. Format is '`__has_cpp_attribute( identifier )`'| |[Compiler error C2279](compiler-error-c2279.md)|exception specification cannot appear in a typedef declaration| |[Compiler error C2280](compiler-error-c2280.md)|'*class*::*function*': attempting to reference a deleted function| |Compiler error C2281|'*class*::*function*': a function can only be deleted on the first declaration| |Compiler error C2282|'*function1*' cannot override '*function2*'| -|[Compiler error C2283](compiler-error-c2283.md)|'*identifer*': pure specifier or abstract override specifier not allowed on unnamed class/struct| +|[Compiler error C2283](compiler-error-c2283.md)|'*identifier*': pure specifier or abstract override specifier not allowed on unnamed struct| |Compiler error C2284|'*function*': illegal argument to intrinsic function, parameter *number*| |[Compiler error C2285](compiler-error-c2285.md)|pointers to members representation has already been determined - pragma ignored| |[Compiler error C2286](compiler-error-c2286.md)|pointers to members of '*identifier*' representation is already set to *inheritance* - declaration ignored| |[Compiler error C2287](compiler-error-c2287.md)|'*identifier*': inheritance representation: '*inheritiance*' is less general than the required '*inheritance*'| -|Compiler error C2288|Obsolete.| +|Compiler error C2288|preprocessing number '*number*' is not a valid integer or floating literal| |[Compiler error C2289](compiler-error-c2289.md)|same type qualifier used more than once| |[Compiler error C2290](compiler-error-c2290.md)|C++ 'asm' syntax ignored. Use __asm.| |Compiler error C2291|An anonymous namespace cannot be exported.| @@ -120,4 +119,4 @@ The articles in this section of the documentation explain a subset of the error ## See also [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[Compiler errors C2001 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2300-through-c2399.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2300-through-c2399.md index a78a533c3b..3abd7f9ea4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2300-through-c2399.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2300-through-c2399.md @@ -2,9 +2,8 @@ description: "Learn more about: Compiler errors C2300 Through C2399" title: "Compiler errors C2300 Through C2399" ms.date: "04/21/2019" -f1_keywords: ["C2303", "C2304", "C2305", "C2306", "C2314", "C2321", "C2323", "C2328", "C2329", "C2330", "C2331", "C2335", "C2336", "C2339", "C2340", "C2342", "C2343", "C2347", "C2354", "C2358", "C2359", "C2363", "C2366", "C2367", "C2398", "C2399"] -helpviewer_keywords: ["C2303", "C2304", "C2305", "C2306", "C2314", "C2321", "C2323", "C2328", "C2329", "C2330", "C2331", "C2335", "C2336", "C2339", "C2340", "C2342", "C2343", "C2347", "C2354", "C2358", "C2359", "C2363", "C2366", "C2367", "C2398", "C2399"] -ms.assetid: 07ca45b5-b2f0-4049-837b-40a7a3caed88 +f1_keywords: ["C2303", "C2304", "C2305", "C2306", "C2314", "C2321", "C2328", "C2329", "C2330", "C2331", "C2335", "C2336", "C2339", "C2340", "C2342", "C2343", "C2347", "C2354", "C2358", "C2359", "C2363", "C2366", "C2367", "C2398", "C2399"] +helpviewer_keywords: ["C2303", "C2304", "C2305", "C2306", "C2314", "C2321", "C2328", "C2329", "C2330", "C2331", "C2335", "C2336", "C2339", "C2340", "C2342", "C2343", "C2347", "C2354", "C2358", "C2359", "C2363", "C2366", "C2367", "C2398", "C2399"] --- # Compiler errors C2300 Through C2399 @@ -39,7 +38,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2320](compiler-error-c2320.md)|expected ':' to follow access specifier '*specifier*'| |Compiler error C2321|'*identifier*' is a keyword, and cannot be used in this context| |[Compiler error C2322](compiler-error-c2322.md)|'*identifier*': address of dllimport '*identifier*' is not static| -|Compiler error C2323|'*identifier*': non-member operator new or delete functions may not be declared static or in a namespace other than the global namespace| +|[Compiler error C2323](compiler-error-c2323.md)|'*identifier*': non-member operator new or delete functions may not be declared static or in a namespace other than the global namespace| |[Compiler error C2324](compiler-error-c2324.md)|'*identifier*': unexpected to the right of '::~'| |[Compiler error C2325](compiler-error-c2325.md)|'*type1*': unexpected type to the right of '->~': expected '*type2*'| |[Compiler error C2326](compiler-error-c2326.md)|'*declarator*': function cannot access '*identifier*'| @@ -54,7 +53,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C2335|'*identifier*': a type cannot be introduced in a function parameter list| |Compiler error C2336|'*type*': illegal type| |[Compiler error C2337](compiler-error-c2337.md)|'*attribute*': attribute not found| -|[Compiler error C2338](compiler-error-c2338.md)|*(error message from external provider)*| +|[Compiler error C2338](compiler-error-c2338.md)|static_assert failed: '*(error message from external provider)*'| |Compiler error C2339|'*identifier*': illegal type in embedded-IDL| |Compiler error C2340|'*identifier*': 'static' can only be used within a class definition| |[Compiler error C2341](compiler-error-c2341.md)|'*section*': segment must be defined using #pragma data_seg, code_seg or section prior to use| @@ -68,7 +67,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2349](compiler-error-c2349.md)|'*function*' cannot be compiled as managed: '*explanation*'; use #pragma unmanaged| |[Compiler error C2350](compiler-error-c2350.md)|'*identifier*' is not a static member| |[Compiler error C2351](compiler-error-c2351.md)|obsolete C++ constructor initialization syntax| -|[Compiler error C2352](compiler-error-c2352.md)|'*identifier*': illegal call of non-static member function| +|[Compiler error C2352](compiler-error-c2352.md)|'*identifier*': a call of a non-static member function requires an object| |[Compiler error C2353](compiler-error-c2353.md)|exception specification is not allowed| |Compiler error C2354|Obsolete.| |[Compiler error C2355](compiler-error-c2355.md)|'this': can only be referenced inside non-static member functions or non-static data member initializers| @@ -97,7 +96,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2378](compiler-error-c2378.md)|'*identifier*': redefinition; symbol cannot be overloaded with a typedef| |[Compiler error C2379](compiler-error-c2379.md)|formal parameter *number* has different type when promoted| |[Compiler error C2380](compiler-error-c2380.md)|type(s) preceding '*identifier*' (constructor with return type, or illegal redefinition of current class-name?)| -|[Compiler error C2381](compiler-error-c2381.md)|'*identifier*': redefinition; '__declspec(noreturn)' or '[[noreturn]]' differs| +|[Compiler error C2381](compiler-error-c2381.md)|'*identifier*': redefinition; '`noreturn`' differs| |[Compiler error C2382](compiler-error-c2382.md)|'*identifier*': redefinition; different exception specifications| |[Compiler error C2383](compiler-error-c2383.md)|'*identifier*': default-arguments are not allowed on this symbol| |[Compiler error C2384](compiler-error-c2384.md)|'*member*': cannot apply thread_local or __declspec(thread) to a member of a managed/WinRT class| @@ -120,4 +119,4 @@ The articles in this section of the documentation explain a subset of the error ## See also [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[Compiler errors C2001 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2400-through-c2499.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2400-through-c2499.md index a22a80372d..d7e931c1e4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2400-through-c2499.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2400-through-c2499.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C2400 Through C2499" title: "Compiler errors C2400 Through C2499" +description: "Learn more about: Compiler errors C2400 Through C2499" ms.date: "04/21/2019" f1_keywords: ["C2416", "C2442", "C2453", "C2454", "C2455", "C2456", "C2468", "C2475", "C2478", "C2481", "C2497"] helpviewer_keywords: ["C2416", "C2442", "C2453", "C2454", "C2455", "C2456", "C2468", "C2475", "C2478", "C2481", "C2497"] -ms.assetid: f1f05572-af0b-497b-bde4-4c81ec01af3b --- # Compiler errors C2400 Through C2499 @@ -51,7 +50,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2432](compiler-error-c2432.md)|illegal reference to 16-bit data in '*context*'| |[Compiler error C2433](compiler-error-c2433.md)|'*identifier*': '*modifier*' not permitted on data declarations| |[Compiler error C2434](compiler-error-c2434.md)|'*symbol*': a symbol declared with `__declspec(process)` cannot be dynamically initialized in `/clr:pure` mode| -|[Compiler error C2435](compiler-error-c2435.md)|'var': dynamic initialization requires managed CRT, cannot compile with `/clr:safe`| +|[Compiler error C2435](compiler-error-c2435.md)|'*var*': dynamic initialization requires managed CRT, cannot compile with `/clr:safe`| |[Compiler error C2436](compiler-error-c2436.md)|'*identifier*': member function or nested class in constructor initializer list| |[Compiler error C2437](compiler-error-c2437.md)|'*identifier*': has already been initialized| |[Compiler error C2438](compiler-error-c2438.md)|'*identifier*': cannot initialize static class data via constructor| @@ -61,11 +60,12 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C2442|'*identifier*': nested-namespace-definition cannot be inline or have attributes| |[Compiler error C2443](compiler-error-c2443.md)|operand size conflict| |[Compiler error C2444](compiler-error-c2444.md)|'*identifier*': used ANSI prototype, found 'type', expected '{' or ';'| +|Compiler error C2445|result type of conditional expression is ambiguous: types '*type 1*' and '*type 2*' can be converted to multiple common types| |[Compiler error C2446](compiler-error-c2446.md)|'*operator*': no conversion from '*type_1*' to '*type_2*'| |[Compiler error C2447](compiler-error-c2447.md)|'{': missing function header (old-style formal list?)| |[Compiler error C2448](compiler-error-c2448.md)|'*identifier*': function-style initializer appears to be a function definition| |[Compiler error C2449](compiler-error-c2449.md)|found '{' at file scope (missing function header?)| -|[Compiler error C2450](compiler-error-c2450.md)|switch expression of type '*type*' is illegal| +|[Compiler error C2450](compiler-error-c2450.md)|a `switch` expression of type '*type*' is illegal| |[Compiler error C2451](compiler-error-c2451.md)|conditional expression of type '*type*' is illegal| |[Compiler error C2452](compiler-error-c2452.md)|'*type*': invalid source type for `safe_cast`| |Compiler error C2453|'*type*': invalid target type for safe_cast| @@ -116,4 +116,4 @@ The articles in this section of the documentation explain a subset of the error ## See also [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[Compiler errors C2001 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md b/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md index f24db7c8a5..8ba3fceb81 100644 --- a/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md +++ b/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Compiler fatal errors C999 through C1999" -title: "Compiler fatal errors C999 through C1999" -ms.date: "04/21/2019" -f1_keywords: ["C1034", "C1036", "C1041", "C1048", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1193", "C1195", "C1300", "C1301", "C1302", "C1306", "C1384", "C1451", "C1505", "C1901"] -helpviewer_keywords: ["C1034", "C1036", "C1041", "C1048", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1193", "C1195", "C1300", "C1301", "C1302", "C1306", "C1384", "C1451", "C1505", "C1901"] -ms.assetid: 6c8df109-7594-48ed-987a-97d9fe2b04af +title: "Compiler fatal errors C1001 through C1907" +description: "Learn more about: Compiler fatal errors C1001 through C1907" +ms.date: 01/24/2025 +f1_keywords: ["C1006", "C1024", "C1027", "C1030", "C1032", "C1034", "C1036", "C1039", "C1040", "C1041", "C1042", "C1043", "C1044", "C1048", "C1056", "C1058", "C1059", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1118", "C1119", "C1127", "C1193", "C1194", "C1195", "C1198", "C1199", "C1203", "C1204", "C1212", "C1213", "C1214", "C1300", "C1301", "C1302", "C1303", "C1304", "C1306", "C1354", "C1355", "C1356", "C1357", "C1358", "C1384", "C1385", "C1451", "C1505", "C1507", "C1511", "C1604", "C1605", "C1859", "C1901", "C1906", "C1907"] +helpviewer_keywords: ["C1006", "C1024", "C1027", "C1030", "C1032", "C1034", "C1036", "C1039", "C1040", "C1041", "C1042", "C1043", "C1044", "C1048", "C1056", "C1058", "C1059", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1118", "C1119", "C1127", "C1193", "C1194", "C1195", "C1198", "C1199", "C1203", "C1204", "C1212", "C1213", "C1214", "C1300", "C1301", "C1302", "C1303", "C1304", "C1306", "C1354", "C1355", "C1356", "C1357", "C1358", "C1384", "C1385", "C1451", "C1505", "C1507", "C1511", "C1604", "C1605", "C1859", "C1901", "C1906", "C1907"] --- -# Compiler fatal errors C999 through C1999 +# Compiler fatal errors C1001 through C1907 The articles in this section of the documentation explain a subset of the error messages that are generated by the Microsoft C/C++ compiler. @@ -14,153 +13,201 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Fatal error C999](../../error-messages/compiler-errors-1/fatal-error-c999.md)|UNKNOWN MESSAGE Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Fatal error C1001](../../error-messages/compiler-errors-1/fatal-error-c1001.md)|An internal error has occurred in the compiler.
(compiler file '*file*', line *number*)
To work around this problem, try simplifying or changing the program near the locations listed above. Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Fatal error C1002](../../error-messages/compiler-errors-1/fatal-error-c1002.md)|compiler is out of heap space in pass 2| -|[Fatal error C1003](../../error-messages/compiler-errors-1/fatal-error-c1003.md)|error count exceeds *number*; stopping compilation| -|[Fatal error C1004](../../error-messages/compiler-errors-1/fatal-error-c1004.md)|unexpected end-of-file found| -|[Fatal error C1005](../../error-messages/compiler-errors-1/fatal-error-c1005.md)|string too big for buffer| -|[Fatal error C1007](../../error-messages/compiler-errors-1/fatal-error-c1007.md)|unrecognized flag '*string*' in '*option*'| -|[Fatal error C1008](../../error-messages/compiler-errors-1/fatal-error-c1008.md)|no input file specified| -|[Fatal error C1009](../../error-messages/compiler-errors-1/fatal-error-c1009.md)|compiler limit: macros nested too deeply| -|[Fatal error C1010](../../error-messages/compiler-errors-1/fatal-error-c1010.md)|unexpected end of file while looking for precompiled header. Did you forget to add '#include \<*file*>' to your source?| -|[Fatal error C1012](fatal-error-c1012.md)|unmatched parenthesis: missing '*character*"| -|[Fatal error C1013](fatal-error-c1013.md)|compiler limit: too many open parentheses| -|[Fatal error C1014](fatal-error-c1014.md)|too many include files: depth = *number*| -|[Fatal error C1016](fatal-error-c1016.md)|#ifdef/#ifndef expected an identifier| -|[Fatal error C1017](../../error-messages/compiler-errors-1/fatal-error-c1017.md)|invalid integer constant expression| -|[Fatal error C1018](fatal-error-c1018.md)|unexpected #elif| -|[Fatal error C1019](fatal-error-c1019.md)|unexpected #else| -|[Fatal error C1020](fatal-error-c1020.md)|unexpected #endif| -|[Fatal error C1021](fatal-error-c1021.md)|invalid preprocessor command '*string*'| -|[Fatal error C1022](fatal-error-c1022.md)|expected #endif| -|[Fatal error C1023](fatal-error-c1023.md)|'*file*': unexpected error with pch, try rebuilding the pch| -|[Fatal error C1026](../../error-messages/compiler-errors-1/fatal-error-c1026.md)|parser stack overflow, program too complex| -|[Fatal error C1033](../../error-messages/compiler-errors-1/fatal-error-c1033.md)|cannot open program database '*file*'| -|Fatal error C1034|*file*: no include path set| -|[Fatal error C1035](fatal-error-c1035.md)|expression too complex; simplify expression| -|Fatal error C1036|cannot overwrite earlier program database format, delete '*file*' and recompile| -|[Fatal error C1037](fatal-error-c1037.md)|cannot open object file '*file*'| -|[Fatal error C1038](fatal-error-c1038.md)|compiler limit: '*function*': control flow state too complex; simplify function| -|Fatal error C1041|cannot open program database '*file*'; if multiple CL.EXE write to the same .PDB file, please use /FS| -|[Fatal error C1045](fatal-error-c1045.md)|compiler limit: linkage specifications nested too deeply| -|[Fatal error C1046](../../error-messages/compiler-errors-1/fatal-error-c1046.md)|compiler limit: *structure* nested too deeply| -|[Fatal error C1047](fatal-error-c1047.md)|The object or library file '*file*' was created with an older compiler than other objects; rebuild old objects and libraries| -|Fatal error C1048|unknown option '*string*' in '*option*'| -|[Fatal error C1049](fatal-error-c1049.md)|invalid numerical argument '*value*'| -|[Fatal error C1051](../../error-messages/compiler-errors-1/fatal-error-c1051.md)|program database file, '*file*', has an obsolete format, delete it and recompile| -|[Fatal error C1052](fatal-error-c1052.md)|program database file, '*filename*', was generated by the linker with /DEBUG:fastlink; compiler cannot update such PDB files; please delete it or use /Fd to specify a different PDB filename| -|[Fatal error C1053](fatal-error-c1053.md)|'*function*': function too large| -|[Fatal error C1054](../../error-messages/compiler-errors-1/fatal-error-c1054.md)|compiler limit: initializers nested too deeply| -|[Fatal error C1055](../../error-messages/compiler-errors-1/fatal-error-c1055.md)|compiler limit: out of keys| -|[Fatal error C1057](../../error-messages/compiler-errors-1/fatal-error-c1057.md)|unexpected end of file in macro expansion| -|[Fatal error C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md)|compiler is out of heap space| -|[Fatal error C1061](../../error-messages/compiler-errors-1/fatal-error-c1061.md)|compiler limit: blocks nested too deeply| -|Fatal error C1063|compiler limit: compiler stack overflow| -|[Fatal error C1064](../../error-messages/compiler-errors-1/fatal-error-c1064.md)|compiler limit: token overflowed internal buffer| -|[Fatal error C1065](../../error-messages/compiler-errors-1/fatal-error-c1065.md)|compiler limit: out of tags| -|[Fatal error C1067](../../error-messages/compiler-errors-1/fatal-error-c1067.md)|compiler limit: 64K limit on size of a type record has been exceeded| -|[Fatal error C1068](fatal-error-c1068.md)|cannot open file '*file*'| -|Fatal error C1069|cannot read compiler command line| -|[Fatal error C1070](fatal-error-c1070.md)|mismatched #if/#endif pair in file '*file*'| -|[Fatal error C1071](../../error-messages/compiler-errors-1/fatal-error-c1071.md)|unexpected end of file found in comment| -|[Fatal error C1073](../../error-messages/compiler-errors-1/fatal-error-c1073.md)|Internal error involving incremental compilation(compiler file '*file*', line *number*)| -|[Fatal error C1074](fatal-error-c1074.md)|'IDB' is illegal extension for PDB file: *file*| -|[Fatal error C1075](../../error-messages/compiler-errors-1/fatal-error-c1075.md)|the left *token* was unmatched at the end of the file| -|[Fatal error C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md)|compiler limit: internal heap limit reached; use /Zm to specify a higher limit| -|[Fatal error C1077](fatal-error-c1077.md)|compiler limit: cannot have more than *number* command line options| -|[Fatal error C1079](../../error-messages/compiler-errors-1/fatal-error-c1079.md)|compiler limit: PCH file size limit exceeded| -|[Fatal error C1080](../../error-messages/compiler-errors-1/fatal-error-c1080.md)|compiler limit: command line option exceeded limit of *number* characters| -|[Fatal error C1081](../../error-messages/compiler-errors-1/fatal-error-c1081.md)|'*file*': file name too long| -|[Fatal error C1082](fatal-error-c1082.md)|cannot close *type* file: '*file*': *message*| -|[Fatal error C1083](../../error-messages/compiler-errors-1/fatal-error-c1083.md)|cannot open *type* file: '*file*': *message*| -|[Fatal error C1084](../../error-messages/compiler-errors-1/fatal-error-c1084.md)|cannot read *type* file: '*file*': *message*| -|[Fatal error C1085](../../error-messages/compiler-errors-1/fatal-error-c1085.md)|cannot write *type* file: '*file*': *message*| -|[Fatal error C1086](fatal-error-c1086.md)|cannot seek *type* file: '*file*': *message*| -|[Fatal error C1087](fatal-error-c1087.md)|cannot tell *type* file: '*file*': *message*| -|[Fatal error C1088](fatal-error-c1088.md)|cannot flush *type* file: '*file*': *message*| -|[Fatal error C1089](fatal-error-c1089.md)|cannot truncate *type* file: '*file*': *message*| -|[Fatal error C1090](fatal-error-c1090.md)|PDB API call failed, error code '*code*': '*message*'| -|[Fatal error C1091](fatal-error-c1091.md)|compiler limit: string exceeds *number* bytes in length| -|[Fatal error C1092](../../error-messages/compiler-errors-1/fatal-error-c1092.md)|Edit and Continue does not support changes to data types; build required| -|[Fatal error C1093](../../error-messages/compiler-errors-1/fatal-error-c1093.md)|API call '*function*' failed '*HRESULT*' : '*description*'| -|[Fatal error C1094](../../error-messages/compiler-errors-1/fatal-error-c1094.md)|'-Zm*number*': command line option is inconsistent with value used to build precompiled header ('-Zm*number*')| -|[Fatal error C1098](fatal-error-c1098.md)|Version mismatch with Edit and Continue engine| -|[Fatal error C1099](fatal-error-c1099.md)|Edit and Continue engine terminating compile| -|[Fatal error C1100](fatal-error-c1100.md)|unable to initialize OLE: *error*| -|Fatal error C1101|cannot create handler for attribute '*identifier*'| -|Fatal error C1102|unable to initialize: *error*| -|[Fatal error C1103](fatal-error-c1103.md)|fatal error importing progid: '*message*'| -|[Fatal error C1104](fatal-error-c1104.md)|fatal error importing libid: '*message*'| -|Fatal error C1105|*message*: *error*| -|[Fatal error C1107](../../error-messages/compiler-errors-1/fatal-error-c1107.md)|could not find assembly '*assembly*': please specify the assembly search path using /AI or by setting the LIBPATH environment variable| -|[Fatal error C1108](fatal-error-c1108.md)|unable to find DLL: '*file*'| -|[Fatal error C1109](fatal-error-c1109.md)|unable to find '*symbol*' in DLL '*file*'| -|Fatal error C1110|too many nested template/generic definitions| -|Fatal error C1111|too many template/generic parameters| -|Fatal error C1112|compiler limit: '*number*' too many macro arguments, only *number* allowed| -|[Fatal error C1113](../../error-messages/compiler-errors-1/fatal-error-c1113.md)|#using failed on '*file*'| -|Fatal error C1114|'*file*': WinRT does not support #using of a managed assembly| -|[Fatal error C1120](../../error-messages/compiler-errors-1/fatal-error-c1120.md)|call to GetProcAddress failed for '*function*'| -|[Fatal error C1121](../../error-messages/compiler-errors-1/fatal-error-c1121.md)|call to CryptoAPI failed| -|[Fatal error C1126](../../error-messages/compiler-errors-1/fatal-error-c1126.md)|automatic allocation exceeds *size*| -|[Fatal error C1128](../../error-messages/compiler-errors-1/fatal-error-c1128.md)|number of sections exceeded object file format limit: compile with /bigobj| -|[Fatal error C1189](../../error-messages/compiler-errors-1/fatal-error-c1189.md)|#error: *message*| -|[Fatal error C1190](fatal-error-c1190.md)|managed targeted code requires a '/clr' option| -|[Fatal error C1191](../../error-messages/compiler-errors-1/fatal-error-c1191.md)|'*file*' can only be imported at global scope| -|[Fatal error C1192](../../error-messages/compiler-errors-1/fatal-error-c1192.md)|#using failed on '*file*'| -|Fatal error C1193|an error expected in *file*(*line*) not reached| -|Fatal error C1195|use of /Yu and /Yc on the same command line is incompatible with the /clr option| -|[Fatal error C1196](fatal-error-c1196.md)|'*identifier*' : identifier found in type library '*typelib*' is not a valid C++ identifier| -|[Fatal error C1197](../../error-messages/compiler-errors-1/fatal-error-c1197.md)|cannot reference '*file*' as the program has already referenced '*file*'| -|[Fatal error C1201](fatal-error-c1201.md)|unable to continue after syntax error in class template definition| -|[Fatal error C1202](fatal-error-c1202.md)|recursive type or function dependency context too complex| -|[Fatal error C1205](fatal-error-c1205.md)|Generics are not supported by the version of the runtime installed| -|[Fatal error C1206](fatal-error-c1206.md)|Per-appdomain data is not supported by the version of the runtime installed| -|[Fatal error C1207](fatal-error-c1207.md)|Managed templates not supported by the version of the runtime installed| -|[Fatal error C1208](fatal-error-c1208.md)|Allocating reference classes on the stack is not supported by the version of the runtime installed| -|[Fatal error C1209](fatal-error-c1209.md)|Friend assemblies not supported by the version of the runtime installed| -|[Fatal error C1210](fatal-error-c1210.md)|/clr:pure and /clr:safe are not supported by the version of the runtime installed| -|[Fatal error C1211](fatal-error-c1211.md)|The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed| -|Fatal error C1300|error accessing program database *file* (*message*)| -|Fatal error C1301|error accessing program database *file*, invalid format, please delete and rebuild| -|Fatal error C1302|no profile data for module '*module*' in profile database '*file*'| -|[Fatal error C1305](../../error-messages/compiler-errors-1/fatal-error-c1305.md)|profile database '*file*' is for a different architecture| -|Fatal error C1306|last change to profile data base '*file*' was not optimization analysis; optimization decisions may be out of date| -|[Fatal error C1307](../../error-messages/compiler-errors-1/fatal-error-c1307.md)|program has been edited since profile data was collected| -|[Fatal error C1308](../../error-messages/compiler-errors-1/fatal-error-c1308.md)|*file*: linking assemblies is not supported| -|[Fatal error C1309](../../error-messages/compiler-errors-1/fatal-error-c1309.md)|Mismatched versions of C2.DLL and pgodb*ver*.DLL| -|[Fatal error C1310](fatal-error-c1310.md)|profile guided optimizations are not available with OpenMP| -|[Fatal error C1311](../../error-messages/compiler-errors-1/fatal-error-c1311.md)|COFF format cannot statically initialize '*symbol*' with *number* byte(s) of an address| -|[Fatal error C1312](fatal-error-c1312.md)|Too many conditional branches in function. Simplify or refactor source code.| -|[Fatal error C1313](../../error-messages/compiler-errors-1/fatal-error-c1313.md)|compiler limit: *type* blocks may not be nested deeper than *number* levels| -|[Fatal error C1350](../../error-messages/compiler-errors-1/fatal-error-c1350.md)|error loading dll '*file*': dll not found| -|[Fatal error C1351](../../error-messages/compiler-errors-1/fatal-error-c1351.md)|error loading dll '*file*': incompatible version| -|[Fatal error C1352](fatal-error-c1352.md)|Invalid or corrupt MSIL in function '*function*' from module '*module*'| -|[Fatal error C1353](fatal-error-c1353.md)|metadata operation failed: runtime not installed or version mismatch| -|[Fatal error C1382](../../error-messages/compiler-errors-1/fatal-error-c1382.md)|the PCH file '*file*' has been rebuilt since '*obj*' was generated. Please rebuild this object| -|[Fatal error C1383](fatal-error-c1383.md)|compiler option /GL is incompatible with the installed version of common language runtime| -|Fatal error C1384|Incorrect setting for PGO_PATH_TRANSLATION when linking '*file*'| -|Fatal error C1451|Failed to generate debug information when compiling the call graph for the concurrency::parallel_for_each at: '*callsite*'| -|Fatal error C1505|unrecoverable parser look-ahead error| -|[Fatal error C1506](../../error-messages/compiler-errors-1/fatal-error-c1506.md)|unrecoverable block scoping error| -|[Fatal error C1508](fatal-error-c1508.md)|compiler limit: '*function*': more than 65535 argument bytes| -|[Fatal error C1509](../../error-messages/compiler-errors-1/fatal-error-c1509.md)|compiler limit: too many exception handler states in function '*function*'; simplify function| -|[Fatal error C1510](../../error-messages/compiler-errors-1/fatal-error-c1510.md)|Cannot open language resource clui.dll| -|[Fatal error C1601](../../error-messages/compiler-errors-1/fatal-error-c1601.md)|unsupported inline assembly opcode| -|[Fatal error C1602](../../error-messages/compiler-errors-1/fatal-error-c1602.md)|unsupported intrinsic| -|[Fatal error C1603](../../error-messages/compiler-errors-1/fatal-error-c1603.md)|inline assembly branch target out of range by *number* bytes| -|[Fatal error C1852](fatal-error-c1852.md)|'*file*' is not a valid precompiled header file| -|[Fatal error C1853](../../error-messages/compiler-errors-1/fatal-error-c1853.md)|'*file*' precompiled header file is from a previous version of the compiler, or the precompiled header is C++ and you are using it from C (or vice versa)| -|[Fatal error C1854](../../error-messages/compiler-errors-1/fatal-error-c1854.md)|cannot overwrite information formed during creation of the precompiled header in object file: '*file*'| -|[Fatal error C1900](../../error-messages/compiler-errors-1/fatal-error-c1900.md)|Il mismatch between '*tool*' version '*number*' and '*tool*' version '*number*'| -|Fatal error C1901|Internal memory management error| -|[Fatal error C1902](../../error-messages/compiler-errors-1/fatal-error-c1902.md)|Program database manager mismatch; please check your installation| -|[Fatal error C1903](fatal-error-c1903.md)|unable to recover from previous error(s); stopping compilation| -|[Fatal error C1904](fatal-error-c1904.md)|bad provider interaction: '*file*'| -|[Fatal error C1905](../../error-messages/compiler-errors-1/fatal-error-c1905.md)|Front end and back end not compatible (must target same processor).| +| Error | Message | +|--|--| +| [Fatal error C1001](fatal-error-c1001.md) | An internal error has occurred in the compiler.
(compiler file '*file*', line *number*)
To work around this problem, try simplifying or changing the program near the locations listed above. Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information | +| [Fatal error C1002](fatal-error-c1002.md) | compiler is out of heap space in pass 2 | +| [Fatal error C1003](fatal-error-c1003.md) | error count exceeds *number*; stopping compilation | +| [Fatal error C1004](fatal-error-c1004.md) | unexpected end-of-file found | +| [Fatal error C1005](fatal-error-c1005.md) | string too big for buffer | +| Fatal error C1006 | write error on compiler intermediate file | +| [Fatal error C1007](fatal-error-c1007.md) | unrecognized flag '*string*' in '*option*' | +| [Fatal error C1008](fatal-error-c1008.md) | no input file specified | +| [Fatal error C1009](fatal-error-c1009.md) | compiler limit: macros nested too deeply | +| [Fatal error C1010](fatal-error-c1010.md) | unexpected end of file while looking for precompiled header. Did you forget to add '`#include <`*file*`>`' to your source? | +| [Fatal error C1011](fatal-error-c1011.md) | cannot locate standard module interface. Did you install the library part of the C++ modules feature in VS setup? | +| [Fatal error C1012](fatal-error-c1012.md) | unmatched parenthesis: missing '*character*' | +| [Fatal error C1013](fatal-error-c1013.md) | compiler limit: too many open parentheses | +| [Fatal error C1014](fatal-error-c1014.md) | too many include files: depth = *number* | +| [Fatal error C1015](fatal-error-c1015.md) | header-names '*header-name*' and '*header-name*' identify the same header and cannot be used as both `/headerUnit:quoted` and `/headerUnit:angle` arguments; please provide this header-name only once | +| [Fatal error C1016](fatal-error-c1016.md) | `#ifdef`/`#ifndef` expected an identifier | +| [Fatal error C1017](fatal-error-c1017.md) | invalid integer constant expression | +| [Fatal error C1018](fatal-error-c1018.md) | unexpected `#elif` | +| [Fatal error C1019](fatal-error-c1019.md) | unexpected `#else` | +| [Fatal error C1020](fatal-error-c1020.md) | unexpected `#endif` | +| [Fatal error C1021](fatal-error-c1021.md) | invalid preprocessor command '*string*' | +| [Fatal error C1022](fatal-error-c1022.md) | expected `#endif` | +| [Fatal error C1023](fatal-error-c1023.md) | '*file*': unexpected error with pch, try rebuilding the pch | +| Fatal error C1024 | **(Obsolete)** too many symbols | +| [Fatal error C1025](fatal-error-c1025-c1115.md) | too many nested lambdas | +| [Fatal error C1026](fatal-error-c1026.md) | parser stack overflow, program too complex | +| Fatal error C1027 | **(Obsolete)** Inconsistent values for /Ym between creation and use of precompiled header | +| Fatal error C1028 | missing IFC for analysis. Please rebuild *module* '*ifc filename*' with `/analyze`. | +| Fatal error C1030 | WMMX types not allowed in the function signature by the calling convention | +| Fatal error C1032 | `__eabi` requires VFP code generation (`/QRfpe-`) | +| [Fatal error C1033](fatal-error-c1033.md) | cannot open program database '*file*' | +| Fatal error C1034 | *file*: no include path set | +| [Fatal error C1035](fatal-error-c1035.md) | expression too complex; simplify expression | +| Fatal error C1036 | cannot overwrite earlier program database format, delete '*file*' and recompile | +| [Fatal error C1037](fatal-error-c1037.md) | cannot open object file '*file*' | +| [Fatal error C1038](fatal-error-c1038.md) | **(Obsolete)** compiler limit: '*function*': control flow state too complex; simplify function | +| Fatal error C1039 | more arguments of intrinsic type than allowed by the calling convention | +| Fatal error C1040 | intrinsic function or type not allowed in Thumb mode | +| Fatal error C1041 | cannot open program database '*file*'; if multiple CL.EXE write to the same `.PDB` file, please use `/FS` | +| Fatal error C1042 | cannot open compiler intermediate file - no such file or directory | +| Fatal error C1043 | cannot open compiler intermediate file | +| Fatal error C1044 | out of disk space for compiler intermediate file | +| [Fatal error C1045](fatal-error-c1045.md) | compiler limit: linkage specifications nested too deeply | +| [Fatal error C1046](fatal-error-c1046.md) | compiler limit: *structure* nested too deeply | +| [Fatal error C1047](fatal-error-c1047.md) | The object or library file '*file*' was created with an older compiler than other objects; rebuild old objects and libraries | +| Fatal error C1048 | unknown option '*string*' in '*option*' | +| [Fatal error C1049](fatal-error-c1049.md) | invalid numerical argument '*value*' | +| [Fatal error C1051](fatal-error-c1051.md) | program database file, '*file*', has an obsolete format, delete it and recompile | +| [Fatal error C1052](fatal-error-c1052.md) | program database file, '*filename*', was generated by the linker with `/DEBUG:fastlink`; compiler cannot update such PDB files; please delete it or use `/Fd` to specify a different PDB filename | +| [Fatal error C1053](fatal-error-c1053.md) | '*function*': function too large | +| [Fatal error C1054](fatal-error-c1054.md) | compiler limit: initializers nested too deeply | +| [Fatal error C1055](fatal-error-c1055.md) | compiler limit: out of keys | +| Fatal error C1056 | cannot update the time date stamp field in '*object-file*'; error code *error-code* | +| [Fatal error C1057](fatal-error-c1057.md) | unexpected end of file in macro expansion | +| Fatal error C1058 | compiler limit: too many attributes on symbol '*symbol-name*' | +| Fatal error C1059 | **(Obsolete)** compiler is out of near heap space | +| [Fatal error C1060](fatal-error-c1060.md) | compiler is out of heap space | +| [Fatal error C1061](fatal-error-c1061.md) | compiler limit: blocks nested too deeply | +| Fatal error C1063 | compiler limit: compiler stack overflow | +| [Fatal error C1064](fatal-error-c1064.md) | compiler limit: token overflowed internal buffer | +| [Fatal error C1065](fatal-error-c1065.md) | compiler limit: out of tags | +| [Fatal error C1067](fatal-error-c1067.md) | compiler limit: 64K limit on size of a type record has been exceeded | +| [Fatal error C1068](fatal-error-c1068.md) | cannot open file '*file*' | +| Fatal error C1069 | cannot read compiler command line | +| [Fatal error C1070](fatal-error-c1070.md) | mismatched `#if`/`#endif` pair in file '*file*' | +| [Fatal error C1071](fatal-error-c1071.md) | unexpected end of file found in comment | +| [Fatal error C1073](fatal-error-c1073.md) | **(Obsolete)** Internal error involving incremental compilation(compiler file '*file*', line *number*) | +| [Fatal error C1074](fatal-error-c1074.md) | 'IDB' is illegal extension for PDB file: *file* | +| [Fatal error C1075](fatal-error-c1075.md) | the left *token* was unmatched at the end of the file | +| [Fatal error C1076](fatal-error-c1076.md) | compiler limit: internal heap limit reached; use `/Zm` to specify a higher limit | +| [Fatal error C1077](fatal-error-c1077.md) | compiler limit: cannot have more than *number* command line options | +| [Fatal error C1079](fatal-error-c1079.md) | **(Obsolete)** compiler limit: PCH file size limit exceeded | +| [Fatal error C1080](fatal-error-c1080.md) | compiler limit: command line option exceeded limit of *number* characters | +| [Fatal error C1081](fatal-error-c1081.md) | '*file*': file name too long | +| [Fatal error C1082](fatal-error-c1082.md) | cannot close *type* file: '*file*': *message* | +| [Fatal error C1083](fatal-error-c1083.md) | cannot open *type* file: '*file*': *message* | +| [Fatal error C1084](fatal-error-c1084.md) | cannot read *type* file: '*file*': *message* | +| [Fatal error C1085](fatal-error-c1085.md) | cannot write *type* file: '*file*': *message* | +| [Fatal error C1086](fatal-error-c1086.md) | cannot seek *type* file: '*file*': *message* | +| [Fatal error C1087](fatal-error-c1087.md) | cannot tell *type* file: '*file*': *message* | +| [Fatal error C1088](fatal-error-c1088.md) | cannot flush *type* file: '*file*': *message* | +| [Fatal error C1089](fatal-error-c1089.md) | cannot truncate *type* file: '*file*': *message* | +| [Fatal error C1090](fatal-error-c1090.md) | PDB API call failed, error code '*code*': '*message*' | +| [Fatal error C1091](fatal-error-c1091.md) | compiler limit: string exceeds *number* bytes in length | +| [Fatal error C1092](fatal-error-c1092.md) | Edit and Continue does not support changes to data types; build required | +| [Fatal error C1093](fatal-error-c1093.md) | API call '*function*' failed '*HRESULT*': '*description*' | +| [Fatal error C1094](fatal-error-c1094.md) | '`-Zm`*number*': command line option is inconsistent with value used to build precompiled header ('`-Zm`*number*') | +| Fatal error C1095 | Failed to locate a free memory range. Use `/Yb` to specify a base address. | +| [Fatal error C1098](fatal-error-c1098.md) | Version mismatch with Edit and Continue engine | +| [Fatal error C1099](fatal-error-c1099.md) | Edit and Continue engine terminating compile | +| [Fatal error C1100](fatal-error-c1100.md) | unable to initialize OLE: *error* | +| Fatal error C1101 | cannot create handler for attribute '*identifier*' | +| Fatal error C1102 | unable to initialize: *error* | +| [Fatal error C1103](fatal-error-c1103.md) | fatal error importing progid: '*message*' | +| [Fatal error C1104](fatal-error-c1104.md) | fatal error importing libid: '*message*' | +| Fatal error C1105 | *message*: *HRESULT error* | +| Fatal error C1106 | compiler limit: only *number* function parameters are allowed | +| [Fatal error C1107](fatal-error-c1107.md) | could not find assembly '*assembly*': please specify the assembly search path using `/AI` or by setting the `LIBPATH` environment variable | +| [Fatal error C1108](fatal-error-c1108.md) | unable to find DLL: '*file*' | +| [Fatal error C1109](fatal-error-c1109.md) | unable to find '*symbol*' in DLL '*file*' | +| Fatal error C1110 | too many nested template/generic definitions | +| Fatal error C1111 | too many template/generic parameters | +| Fatal error C1112 | compiler limit: '*number*' too many macro arguments, only '*number*' allowed | +| [Fatal error C1113](fatal-error-c1113.md) | `#using` failed on '*file*' | +| Fatal error C1114 | '*file*': WinRT does not support `#using` of a managed assembly | +| [Fatal error C1115](fatal-error-c1025-c1115.md) | too many nested lambdas | +| [Fatal error C1116](fatal-error-c1116.md) | unrecoverable error importing module/headerunit '*name*'. Specialization of '*primary-template*' with arguments '*argument-list*' | +| [Fatal error C1117](fatal-error-c1117.md) | unrecoverable error importing module/headerunit '*name*': symbol '*symbol-name*' has already been defined | +| Fatal error C1118 | cannot expand the environment variable *variable-name* in *file-type* filename in object file '*object-file*' | +| Fatal error C1119 | unrecoverable error importing symbol '*symbol-name*' from module '*module-name*' | +| [Fatal error C1120](fatal-error-c1120.md) | call to `GetProcAddress` failed for '*function*' | +| [Fatal error C1121](fatal-error-c1121.md) | call to CryptoAPI failed | +| [Fatal error C1126](fatal-error-c1126.md) | automatic allocation exceeds *size* | +| Fatal error C1127 | *Operation* requires *option* | +| [Fatal error C1128](fatal-error-c1128.md) | number of sections exceeded object file format limit: compile with `/bigobj` | +| [Fatal error C1189](fatal-error-c1189.md) | `#error`: *message* | +| [Fatal error C1190](fatal-error-c1190.md) | `System::Object` not found, missing `/clr` option or missing import of standard assemblies? | +| [Fatal error C1191](fatal-error-c1191.md) | '*file*' can only be imported at global scope | +| [Fatal error C1192](fatal-error-c1192.md) | `#using` failed on '*file*' | +| Fatal error C1193 | an error expected in *file*(*line*) not reached | +| Fatal error C1194 | **(Obsolete)** checkpoint '*name*' expected in *file*(*line*) not reached | +| Fatal error C1195 | use of `/Yu` and `/Yc` on the same command line is incompatible with the `/clr` option | +| [Fatal error C1196](fatal-error-c1196.md) | '*identifier*' : identifier found in type library '*typelib*' is not a valid C++ identifier | +| [Fatal error C1197](fatal-error-c1197.md) | cannot reference '*file*' as the program has already referenced '*file*' | +| Fatal error C1198 | *feature* will be supported in a future release | +| Fatal error C1199 | missing reference to IFC file to resolve an import-declaration; please ensure the proper value for a '`/reference`' or '`/headerUnit`' option is provided | +| [Fatal error C1201](fatal-error-c1201.md) | unable to continue after syntax error in class template definition | +| [Fatal error C1202](fatal-error-c1202.md) | recursive type or function dependency context too complex | +| Fatal error C1203 | invalid symbol name or value specification in `#pragma extern_absolute` | +| Fatal error C1204 | symbol '*symbol-name*' specified in `#pragma extern_absolute` has different values: *value-1* and *value-2* | +| [Fatal error C1205](fatal-error-c1205.md) | **(Obsolete)** Generics are not supported by the version of the runtime installed | +| [Fatal error C1206](fatal-error-c1206.md) | **(Obsolete)** Per-appdomain data is not supported by the version of the runtime installed | +| [Fatal error C1207](fatal-error-c1207.md) | **(Obsolete)** Managed templates not supported by the version of the runtime installed | +| [Fatal error C1208](fatal-error-c1208.md) | **(Obsolete)** Allocating reference classes on the stack is not supported by the version of the runtime installed | +| [Fatal error C1209](fatal-error-c1209.md) | **(Obsolete)** Friend assemblies not supported by the version of the runtime installed | +| [Fatal error C1210](fatal-error-c1210.md) | **(Obsolete)** /clr:pure and /clr:safe are not supported by the version of the runtime installed | +| [Fatal error C1211](fatal-error-c1211.md) | **(Obsolete)** The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed | +| Fatal error C1212 | Input file was modified by another process while building: '*filename*' | +| Fatal error C1213 | Header units are unsupported without `/Zc:preprocessor` | +| Fatal error C1214 | Modules conflict with non-standard behavior requested via '*option*' | +| Fatal error C1215 | Cannot open file '*filename*' corresponding to warning set '`-W`*warning set*' | +| Fatal error C1300 | error accessing program database *file* (*message*) | +| Fatal error C1301 | error accessing program database *file*, invalid format, please delete and rebuild | +| Fatal error C1302 | no profile data for module '*module*' in profile database '*file*' | +| Fatal error C1303 | profile data corrupt in profile database '*filename*' | +| Fatal error C1304 | profile data version mismatch in profile database '*filename*' | +| [Fatal error C1305](fatal-error-c1305.md) | profile database '*file*' is for a different architecture | +| Fatal error C1306 | last change to profile data base '*file*' was not optimization analysis; optimization decisions may be out of date | +| [Fatal error C1307](fatal-error-c1307.md) | program has been edited since profile data was collected | +| [Fatal error C1308](fatal-error-c1308.md) | *file*: linking assemblies is not supported | +| [Fatal error C1309](fatal-error-c1309.md) | Mismatched versions of C2.DLL and pgodb*version*.DLL | +| [Fatal error C1310](fatal-error-c1310.md) | profile guided optimizations are not available with OpenMP | +| [Fatal error C1311](fatal-error-c1311.md) | COFF format cannot statically initialize '*symbol*' with *number* byte(s) of an address | +| [Fatal error C1312](fatal-error-c1312.md) | Too many conditional branches in function. Simplify or refactor source code. | +| [Fatal error C1313](fatal-error-c1313.md) | compiler limit: *type* blocks may not be nested deeper than *number* levels | +| [Fatal error C1350](fatal-error-c1350.md) | error loading dll '*file*': dll not found | +| [Fatal error C1351](fatal-error-c1351.md) | error loading dll '*file*': incompatible version | +| [Fatal error C1352](fatal-error-c1352.md) | Invalid or corrupt MSIL in function '*function*' from module '*module*' | +| [Fatal error C1353](fatal-error-c1353.md) | metadata operation failed: runtime not installed or version mismatch | +| Fatal error C1354 | error accessing previous object file *filename* (*reason*) | +| Fatal error C1355 | unable to find entrypoint '*function-name*' in *PDB helper* | +| Fatal error C1356 | unable to find *PDB helper* | +| Fatal error C1357 | C2.DLL unsupported flag combination *`hybrid:x86arm64, CLR`* | +| Fatal error C1358 | module (key=0x*value*) information unavailable | +| [Fatal error C1382](fatal-error-c1382.md) | the PCH file '*file*' has been rebuilt since '*obj*' was generated. Please rebuild this object | +| [Fatal error C1383](fatal-error-c1383.md) | compiler option `/GL` is incompatible with the installed version of common language runtime | +| Fatal error C1384 | Incorrect setting for PGO_PATH_TRANSLATION when linking '*file*' | +| Fatal error C1385 | profile guided optimizations not available for Thumb; compile '*filename*' as ARM or Thumb-2. | +| Fatal error C1451 | Failed to generate debug information when compiling the call graph for the `concurrency::parallel_for_each` at: '*callsite*' | +| Fatal error C1505 | unrecoverable parser look-ahead error | +| [Fatal error C1506](fatal-error-c1506.md) | unrecoverable block scoping error | +| Fatal error C1507 | previous user errors and subsequent error recovery halt further compilation | +| [Fatal error C1508](fatal-error-c1508.md) | compiler limit: '*function*': more than 65535 argument bytes | +| [Fatal error C1509](fatal-error-c1509.md) | compiler limit: too many exception handler states in function '*function*'; simplify function | +| [Fatal error C1510](fatal-error-c1510.md) | Cannot open language resource clui.dll | +| Fatal error C1511 | *Message* (used by capture_repro option) | +| [Fatal error C1601](fatal-error-c1601.md) | unsupported inline assembly opcode | +| [Fatal error C1602](fatal-error-c1602.md) | unsupported intrinsic | +| [Fatal error C1603](fatal-error-c1603.md) | inline assembly branch target out of range by *number* bytes | +| Fatal error C1604 | fatal lambda parsing error: see the lambda definition beginning on line *number* | +| Fatal error C1605 | compiler limit: object file size cannot exceed 4 GB | +| [Fatal error C1852](fatal-error-c1852.md) | '*file*' is not a valid precompiled header file | +| [Fatal error C1853](fatal-error-c1853.md) | '*file*' precompiled header file is from a previous version of the compiler, or the precompiled header is C++ and you are using it from C (or vice versa) | +| [Fatal error C1854](fatal-error-c1854.md) | cannot overwrite information formed during creation of the precompiled header in object file: '*file*' | +| Fatal error C1859 | **(Obsolete)** '*Message*' unexpected precompiled header error, simply rerunning the compiler might fix this problem | +| [Fatal error C1900](fatal-error-c1900.md) | IL mismatch between '*tool*' version '*number*' and '*tool*' version '*number*' | +| Fatal error C1901 | **(Obsolete)** Internal memory management error | +| [Fatal error C1902](fatal-error-c1902.md) | Program database manager mismatch; please check your installation | +| [Fatal error C1903](fatal-error-c1903.md) | unable to recover from previous error(s); stopping compilation | +| [Fatal error C1904](fatal-error-c1904.md) | bad provider interaction: '*file*' | +| [Fatal error C1905](fatal-error-c1905.md) | Front end and back end not compatible (must target same processor). | +| Fatal error C1906 | assembly reference '*name*' not resolved for type '*type-name*'; missing option '-FU *filename*.dll'? | +| Fatal error C1907 | unable to recover from previous error(s); stopping compilation | ## See also diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1011.md b/docs/error-messages/compiler-errors-1/fatal-error-c1011.md new file mode 100644 index 0000000000..b7517a9e35 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1011.md @@ -0,0 +1,24 @@ +--- +description: "Learn more about: Fatal Error C1011" +title: "Fatal Error C1011" +ms.date: 08/17/2022 +f1_keywords: ["C1011"] +helpviewer_keywords: ["C1011"] +--- +# Fatal Error C1011 + +> cannot locate standard module interface. Did you install the library part of the C++ modules feature in VS setup? + +## Remarks + +Use of standard modules requires the **C++ Modules for *version* build tools** component. You can add the component to your Visual Studio installation by using the Visual Studio Installer. + +## To install the C++ Modules build tools + +1. Open the Visual Studio Installer. In Visual Studio Installer, choose **Modify** next to your installation of Visual Studio, and then select the **Individual components** tab. + +1. In the **Individual components** list, scroll down to **Compilers, build tools, and runtimes** and select the **C++ Modules for *version* build tools** component. + +1. Choose **Modify** to continue with the installation. + +When installation completes, you're ready to use C++ Modules in Visual Studio. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1012.md b/docs/error-messages/compiler-errors-1/fatal-error-c1012.md index 3de04be3d2..21849c9d15 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1012.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1012.md @@ -1,13 +1,21 @@ --- -description: "Learn more about: Fatal Error C1012" title: "Fatal Error C1012" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1012" +ms.date: "02/20/2025" f1_keywords: ["C1012"] helpviewer_keywords: ["C1012"] -ms.assetid: 92cc83a7-b5b8-4da8-a128-9b7ccb510496 --- # Fatal Error C1012 -unmatched parenthesis : missing character +unmatched parenthesis: missing 'character' The parentheses in a preprocessor directive do not match. + +The following sample generates C1012: + +```cpp +// C1012.cpp +// compile with: /c +#if (0 // C1012 +#endif +``` diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1015.md b/docs/error-messages/compiler-errors-1/fatal-error-c1015.md new file mode 100644 index 0000000000..71edb00f18 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1015.md @@ -0,0 +1,12 @@ +--- +title: "Fatal Error C1015" +description: "Learn more about: Fatal Error C1015" +ms.date: 08/17/2022 +f1_keywords: ["C1015"] +helpviewer_keywords: ["C1015"] +--- +# Fatal Error C1015 + +> header-names '*header-name*' and '*header-name*' identify the same header and cannot be used as both `/headerUnit:quote` and `/headerUnit:angle` arguments; please provide this header-name only once + +Don't include a header unit using both double-quotes and angle brackets. Use only one form, consistent with the **`/headerUnit:quote`** or **`/headerUnit:angle`** compiler option. For more information, see [`/headerUnit` (Use header unit IFC)](../../build/reference/headerunit.md). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1020.md b/docs/error-messages/compiler-errors-1/fatal-error-c1020.md index 3e377cf473..1fb7fcdb59 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1020.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1020.md @@ -1,17 +1,23 @@ --- description: "Learn more about: Fatal Error C1020" title: "Fatal Error C1020" -ms.date: "11/04/2016" +ms.date: 07/11/2022 f1_keywords: ["C1020"] helpviewer_keywords: ["C1020"] ms.assetid: 42f429e2-5e3b-4086-a10d-b99e032e51c5 --- # Fatal Error C1020 -unexpected #endif +> unexpected #endif + +## Remarks The `#endif` directive has no matching `#if`, `#ifdef`, or `#ifndef` directive. Be sure each `#endif` has a matching directive. +This error can occur if you have conditional preprocessor directives before you include a precompiled header file. The compiler ignores everything in the file before the precompiled header, including any `#if`, `#ifdef`, or `#ifndef` directives. For more information, see [`/Yu` (Use precompiled header)](../../build/reference/yu-use-precompiled-header-file.md). + +## Examples + The following sample generates C1020: ```cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md b/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md new file mode 100644 index 0000000000..caf838ff18 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal Error C1025, C1115" +title: "Fatal Error C1025, C1115" +ms.date: 08/17/2022 +f1_keywords: ["C1025", "C1115"] +helpviewer_keywords: ["C1025", "C1115"] +--- +# Fatal Error C1025, C1115 + +> too many nested lambdas + +The compiler detected more than an internal limit for nested lambdas in the same scope. The limit is 65,535 in recent versions of Visual Studio. To resolve this issue, reduce the number of nested lambdas in the current scope. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1038.md b/docs/error-messages/compiler-errors-1/fatal-error-c1038.md index 8a2bd8bd22..fd563949b8 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1038.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1038.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Fatal Error C1038" title: "Fatal Error C1038" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1038"] helpviewer_keywords: ["C1038"] ms.assetid: 560dccb8-5b45-46f0-9412-caa4a6172aef --- # Fatal Error C1038 -compiler limit : function : control flow state too complex; simplify function +> compiler limit : function : control flow state too complex; simplify function The function has more control-flow states than the compiler can handle. Simplify control flow or split the function into smaller functions. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1049.md b/docs/error-messages/compiler-errors-1/fatal-error-c1049.md index 3a658b4c49..658e780882 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1049.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1049.md @@ -11,7 +11,7 @@ helpviewer_keywords: ["C1049"] The CL.EXE command-line parser found *value* where it was expecting a numerical argument. -A C1049 error may occur when the compiler can’t find a numerical argument for one of these compiler options: +A C1049 error may occur when the compiler can't find a numerical argument for one of these compiler options: [/constexpr:depth](../../build/reference/constexpr-control-constexpr-evaluation.md)\ [/constexpr:backtrace](../../build/reference/constexpr-control-constexpr-evaluation.md)\ diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1073.md b/docs/error-messages/compiler-errors-1/fatal-error-c1073.md index 74e63dc932..5bdfc8ee77 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1073.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1073.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Fatal Error C1073" title: "Fatal Error C1073" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1073"] helpviewer_keywords: ["C1073"] ms.assetid: a946fcf1-674e-4a7a-a28c-b1effacbabe1 --- # Fatal Error C1073 -Internal error involving incremental compilation (compiler file 'filename', line number) +> Internal error involving incremental compilation (compiler file '*filename*', line *number*) Recompile the file without using incremental compilation. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1079.md b/docs/error-messages/compiler-errors-1/fatal-error-c1079.md index e381ae6398..d66d45a595 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1079.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1079.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Fatal Error C1079" title: "Fatal Error C1079" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1079"] helpviewer_keywords: ["C1079"] ms.assetid: cf06a65a-f9a5-4bd8-8128-201a6cbe2113 --- # Fatal Error C1079 -compiler limit : PCH file size limit exceeded +> compiler limit : PCH file size limit exceeded The PCH file exceeds the 4 GB size limit. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1083.md b/docs/error-messages/compiler-errors-1/fatal-error-c1083.md index c5f68fc295..740cef0703 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1083.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1083.md @@ -4,21 +4,20 @@ title: "Fatal Error C1083" ms.date: "09/01/2017" f1_keywords: ["C1083"] helpviewer_keywords: ["C1083"] -ms.assetid: 97e52df3-e79c-4f85-8f1e-bbd1057d55e7 --- # Fatal Error C1083 > Cannot open *filetype* file: '*file*': *message* -The compiler generates a C1083 error when it can’t find a file it requires. There are many possible causes for this error. An incorrect include search path or missing or misnamed header files are the most common causes, but other file types and issues can also cause C1083. Here are some of the common reasons why the compiler generates this error. +The compiler generates a C1083 error when it can't find a file. There are many possible causes for this error. An incorrect include search path or missing or misnamed header files are the most common causes, but other file types and issues can also cause C1083. Here are some of the common reasons why the compiler generates this error. ## The specified file name is wrong -The name of a file may be mistyped. For example, +The name of a file might be mistyped. For example, `#include ` -might not find the file you intend. Most C++ Standard Library header files do not have a .h file name extension. The \ header would not be found by this `#include` directive. To fix this issue, verify that the correct file name is entered, as in this example: +might not find the file you intend. Most C++ Standard Library header files don't have a `.h` file name extension. This `#include` directive won't find the `` header. To fix this issue, verify that the correct file name is entered, as follows: `#include ` @@ -26,9 +25,9 @@ Certain C Runtime Library headers are located in a subdirectory of the standard `#include ` -## The file is not included in the include search path +## The file isn't included in the include search path -The compiler cannot find the file by using the search rules that are indicated by an `#include` or `#import` directive. For example, when a header file name is enclosed by quotation marks, +The compiler can't find the file by using the search rules for the `#include` or `#import` directive. For example, when a header file name is enclosed by quotation marks, `#include "myincludefile.h"` @@ -48,64 +47,64 @@ but this example works: `#include "headers\myheader.h"` -Relative paths can also be used with directories on the include search path. If you add a directory to the **INCLUDE** environment variable or to your **Include Directories** path in Visual Studio, do not also add part of the path to the include directives. For example, if your header is located at *`\path\example\headers\myheader.h`*, and you add *`\path\example\headers\`* to your **Include Directories** path in Visual Studio, but your `#include` directive refers to the file as +Relative paths can also be used with directories on the include search path. If you add a directory to the **INCLUDE** environment variable or to your **Include Directories** path in Visual Studio, don't add part of the path to the include directives. For example, if your header is located at *`\path\example\headers\myheader.h`*, and you add *`\path\example\headers\`* to your **Include Directories** path in Visual Studio, but your `#include` directive refers to the file as `#include ` -then the file is not found. Use the correct path relative to the directory specified in the include search path. In this example, you could change the include search path to *`\path\example\`*, or remove the *`headers\`* path segment from the `#include` directive. +then the file isn't found. Use the correct path relative to the directory specified in the include search path. In this example, you could change the include search path to *`\path\example\`*, or remove the *`headers\`* path segment from the `#include` directive. ## Third-party library issues and vcpkg -If you see this error when you are trying to configure a third-party library as part of your build, consider using [vcpkg](https://vcpkg.io/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. +If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](/vcpkg/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. ## The file is in your project, but not the include search path -Even when header files are listed in **Solution Explorer** as part of a project, the files are only found by the compiler when they are referred to by an `#include` or `#import` directive in a source file, and are located in an include search path. Different kinds of builds might use different search paths. The **`/X`** compiler option can be used to exclude directories from the include search path. This enables different builds to use different include files that have the same name, but are kept in different directories. This is an alternative to conditional compilation by using preprocessor commands. For more information about the **`/X`** compiler option, see [`/X` (Ignore Standard Include Paths)](../../build/reference/x-ignore-standard-include-paths.md). +Even when header files are listed in **Solution Explorer** as part of a project, the files are only found by the compiler when they're referred to by an `#include` or `#import` directive in a source file, and are located in an include search path. Different kinds of builds might use different search paths. The **`/X`** compiler option can be used to exclude directories from the include search path. This enables different builds to use different include files that have the same name, but are kept in different directories. This is an alternative to conditional compilation by using preprocessor commands. For more information about the **`/X`** compiler option, see [`/X` (Ignore Standard Include Paths)](../../build/reference/x-ignore-standard-include-paths.md). -To fix this issue, correct the path that the compiler uses to search for the included or imported file. A new project uses default include search paths. You may have to modify the include search path to add a directory for your project. If you are compiling on the command line, add the path to the **INCLUDE** environment variable or the **`/I`** compiler option to specify the path to the file. +To fix this issue, correct the path that the compiler uses to search for the included or imported file. A new project uses default include search paths. You might have to modify the include search path to add a directory for your project. If you're compiling on the command line, add the path to the **INCLUDE** environment variable or the **`/I`** compiler option to specify the path to the file. -To set the include directory path in Visual Studio, open the project’s **Property Pages** dialog box. Select **VC++ Directories** under **Configuration Properties** in the left pane, and then edit the **Include Directories** property. For more information about the per-user and per-project directories searched by the compiler in Visual Studio, see [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). For more information about the **`/I`** compiler option, see [`/I` (Additional Include Directories)](../../build/reference/i-additional-include-directories.md). +To set the include directory path in Visual Studio, open the project's **Property Pages** dialog box. Select **VC++ Directories** under **Configuration Properties** in the left pane, and then edit the **Include Directories** property. For more information about the per-user and per-project directories searched by the compiler in Visual Studio, see [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). For more information about the **`/I`** compiler option, see [`/I` (Additional Include Directories)](../../build/reference/i-additional-include-directories.md). -## The command line INCLUDE or LIB environment is not set +## The command line INCLUDE or LIB environment isn't set -When the compiler is invoked on the command line, environment variables are often used to specify search paths. If the search path described by the **INCLUDE** or **LIB** environment variable is not set correctly, a C1083 error can be generated. We strongly recommend using a developer command prompt shortcut to set the basic environment for command line builds. For more information, see [Build C/C++ on the Command Line](../../build/building-on-the-command-line.md). For more information about how to use environment variables, see [How to: Use Environment Variables in a Build](/visualstudio/msbuild/how-to-use-environment-variables-in-a-build). +When the compiler is invoked on the command line, environment variables are often used to specify search paths. If the search path described by the **INCLUDE** or **LIB** environment variable isn't set correctly, a C1083 error can be generated. We strongly recommend using a developer command prompt shortcut to set the basic environment for command line builds. For more information, see [Build C/C++ on the Command Line](../../build/building-on-the-command-line.md). For more information about how to use environment variables, see [How to: Use Environment Variables in a Build](/visualstudio/msbuild/how-to-use-environment-variables-in-a-build). -## The file may be locked or in use +## The file might be locked or in use -If you are using another program to edit or access the file, it may have the file locked. Try closing the file in the other program. Sometimes the other program can be Visual Studio itself, if you are using parallel compilation options. If turning off the parallel build option makes the error go away, then this is the problem. Other parallel build systems can also have this issue. Be careful to set file and project dependencies so build order is correct. In some cases, consider creating an intermediate project to force build dependency order for a common file that may be built by multiple projects. Sometimes antivirus programs temporarily lock recently changed files for scanning. If possible, consider excluding your project build directories from the antivirus scanner. +If you're using another program to edit or access the file, it might have the file locked. Try closing the file in the other program. Sometimes the other program can be Visual Studio itself, if you're using parallel compilation options. If turning off the parallel build option makes the error go away, then this is the problem. Other parallel build systems can also have this issue. Be careful to set file and project dependencies so build order is correct. In some cases, consider creating an intermediate project to force build dependency order for a common file that might be built by multiple projects. Sometimes antivirus programs temporarily lock recently changed files for scanning. If possible, consider excluding your project build directories from the antivirus scanner. ## The wrong version of a file name is included -A C1083 error can also indicate that the wrong version of a file is included. For example, a build could include the wrong version of a file that has an `#include` directive for a header file that is not intended for that build. For example, certain files may only apply to x86 builds, or to Debug builds. When the header file is not found, the compiler generates a C1083 error. The fix for this problem is to use the correct file, not to add the header file or directory to the build. +A C1083 error can also indicate that the wrong version of a file is included. For example, a build could include the wrong version of a file that has an `#include` directive for a header file that isn't intended for that build. For example, certain files might only apply to x86 builds, or to Debug builds. When the header file isn't found, the compiler generates a C1083 error. The fix for this problem is to use the correct file, not to add the header file or directory to the build. -## The precompiled headers are not yet precompiled +## The precompiled headers aren't yet precompiled When a project is configured to use precompiled headers, the relevant *`.pch`* files have to be created so that files that use the header contents can be compiled. For example, the *`pch.cpp`* file (*`stdafx.cpp`* in Visual Studio 2017 and earlier) is automatically created in the project directory for new projects. Compile that file first to create the precompiled header files. In the typical build process design, this is done automatically. For more information, see [Creating Precompiled Header Files](../../build/creating-precompiled-header-files.md). -## Additional causes +## Other causes -- You have installed an SDK or third-party library, but you have not opened a new developer command prompt window after the SDK or library is installed. If the SDK or library adds files to the **INCLUDE** path, you may need to open a new developer command prompt window to pick up these environment variable changes. +- You've installed an SDK or third-party library, but haven't opened a new developer command prompt. If the SDK or library adds files to the **INCLUDE** path, you might need to open a new developer command prompt window to pick up these environment variable changes. -- The file uses managed code, but the compiler option **`/clr`** is not specified. For more information, see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). +- The file uses managed code, but the compiler option **`/clr`** isn't specified. For more information, see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). - The file is compiled by using a different **`/analyze`** compiler option setting than is used to precompile the headers. When the headers for a project are precompiled, all should use the same **`/analyze`** settings. For more information, see [`/analyze` (Code Analysis)](../../build/reference/analyze-code-analysis.md). -- The file or directory was created by the Windows Subsystem for Linux, per-directory case sensitivity is enabled, and the specified case of a path or file does not match the case of the path or file on disk. +- The file or directory was created by the Windows Subsystem for Linux, per-directory case sensitivity is enabled, and the specified case of a path or file doesn't match the case of the path or file on disk. - The file, the directory, or the disk is read-only. -- Visual Studio or the command line tools do not have sufficient permissions to read the file or the directory. This can happen, for example, when the project files have different ownership than the process running Visual Studio or the command line tools. Sometimes this issue can be fixed by running Visual Studio or the developer command prompt as Administrator. +- Visual Studio or the command line tools don't have sufficient permissions to read the file or the directory. This can happen, for example, when the project files have different ownership than the process running Visual Studio or the command line tools. Sometimes this issue can be fixed by running Visual Studio or the developer command prompt as Administrator. -- There are not enough file handles. Close some applications and then recompile. This condition is unusual under typical circumstances. However, it can occur when large projects are built on a computer that has limited physical memory. +- There aren't enough file handles. Close some applications and then recompile. This condition is unusual under typical circumstances. However, it can occur when large projects are built on a computer that has limited physical memory. ## Example -The following example generates a C1083 error when the header file `"test.h"` does not exist in the source directory or on the include search path. +The following example generates a C1083 error when the header file `"test.h"` doesn't exist in the source directory or on the include search path. ```cpp // C1083.cpp // compile with: /c -#include "test.h" // C1083 test.h does not exist +#include "test.h" // C1083 test.h doesn't exist #include "stdio.h" // OK ``` diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1094.md b/docs/error-messages/compiler-errors-1/fatal-error-c1094.md index 62706f27af..bc80c63eeb 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1094.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1094.md @@ -1,16 +1,20 @@ --- description: "Learn more about: Fatal Error C1094" title: "Fatal Error C1094" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1094"] helpviewer_keywords: ["C1094"] ms.assetid: 9e1193b2-cb95-44f9-bf6f-019e0d41dd97 --- # Fatal Error C1094 -'-Zmval1' : command line option is inconsistent with value used to build precompiled header ('-Zmval2') +> '-Zm*value-1*' : command line option is inconsistent with value used to build precompiled header ('-Zm*value-2*') -The value that is passed to [/Yc](../../build/reference/yc-create-precompiled-header-file.md) must be the same value that is passed to [/Yu](../../build/reference/yu-use-precompiled-header-file.md) (**/Zm** values must be the same in all compilations that use or create the same precompiled header file). +## Remarks + +The value that is passed to [`/Yc`](../../build/reference/yc-create-precompiled-header-file.md) must be the same value that is passed to [`/Yu`](../../build/reference/yu-use-precompiled-header-file.md) (**`/Zm`** values must be the same in all compilations that use or create the same precompiled header file). + +## Example The following sample generates C1094: diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1116.md b/docs/error-messages/compiler-errors-1/fatal-error-c1116.md new file mode 100644 index 0000000000..7a5fba81b0 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1116.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal Error C1116" +title: "Fatal Error C1116" +ms.date: 08/17/2022 +f1_keywords: ["C1116"] +helpviewer_keywords: ["C1116"] +--- +# Fatal Error C1116 + +> unrecoverable error importing module/headerunit '*name*'. Specialization of '*primary-template*' with arguments '*argument-list*' + +Error C1116 can happen when the creation of the specialization requires the compiler to parse a token-stream and it encounters an identifier without a matching symbol. To resolve the issue, verify that all template specification arguments are defined and spelled correctly. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1117.md b/docs/error-messages/compiler-errors-1/fatal-error-c1117.md new file mode 100644 index 0000000000..af3886d74f --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1117.md @@ -0,0 +1,12 @@ +--- +description: "Learn more about: Fatal Error C1117" +title: "Fatal Error C1117" +ms.date: 08/17/2022 +f1_keywords: ["C1117"] +helpviewer_keywords: ["C1117"] +--- +# Fatal Error C1117 + +> unrecoverable error importing module/headerunit '*name*': symbol '*symbol-name*' has already been defined + +The compiler found a redefinition of an existing type. To resolve the issue, verify that the symbol has only one definition across modules and translation units. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1128.md b/docs/error-messages/compiler-errors-1/fatal-error-c1128.md index fd928239b9..083737e4b4 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1128.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1128.md @@ -22,4 +22,4 @@ If possible, compile without debugging information. You may also need to have specific instantiations of templates in separate source code files, rather than having the compiler emit them. -When porting code, C1128 will likely appear first when using the x64 compiler, and much later with the x86 compiler. x64 will have at least 4 sections associated with each function compiled **/Gy** or inlined from templates or class-inline: code, pdata, and debug info, and possibly xdata. X86 won’t have the pdata. +When porting code, C1128 will likely appear first when using the x64 compiler, and much later with the x86 compiler. x64 will have at least 4 sections associated with each function compiled **/Gy** or inlined from templates or class-inline: code, pdata, and debug info, and possibly xdata. X86 won't have the pdata. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1192.md b/docs/error-messages/compiler-errors-1/fatal-error-c1192.md index 7f4529470d..93ece1e127 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1192.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1192.md @@ -2,9 +2,8 @@ description: "Learn more about: Fatal Error C1192" title: "Fatal Error C1192" ms.date: "11/04/2016" -f1_keywords: ["c1192"] +f1_keywords: ["C1192"] helpviewer_keywords: ["C1192"] -ms.assetid: 54cff717-a3eb-471d-9bd4-1c2e673dbbef --- # Fatal Error C1192 diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1205.md b/docs/error-messages/compiler-errors-1/fatal-error-c1205.md index 8dad0bb4a0..37af5602e9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1205.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1205.md @@ -1,15 +1,17 @@ --- description: "Learn more about: Fatal Error C1205" title: "Fatal Error C1205" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1205"] helpviewer_keywords: ["C1205"] ms.assetid: f855c145-8cf7-4dd1-bb19-257ee38b8382 --- # Fatal Error C1205 -Generics are not supported by the version of the runtime installed +> Generics are not supported by the version of the runtime installed -The version of the common language runtime that the compiler is using is not a version of the runtime supported by the current compiler. For example, the generics feature requires a runtime that is matched to the compiler. +The version of the common language runtime that the compiler is using isn't a version of the runtime supported by the current compiler. For example, the generics feature requires a runtime that is matched to the compiler. Your path specification may need to be modified. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1206.md b/docs/error-messages/compiler-errors-1/fatal-error-c1206.md index bfb0125715..0859695a79 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1206.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1206.md @@ -1,17 +1,19 @@ --- description: "Learn more about: Fatal Error C1206" title: "Fatal Error C1206" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1206"] helpviewer_keywords: ["C1206"] ms.assetid: 2211428f-ad86-4f7b-82eb-f1ba89b0510e --- # Fatal Error C1206 -Per-appdomain data is not supported by the version of the runtime installed +> Per-appdomain data is not supported by the version of the runtime installed Some features, such as per application domain data, are only supported by the common language runtime that supports the feature. -C1206 indicates that the latest version of the runtime is not installed on your computer. Install the common language runtime version that is intended for use with your compiler. +C1206 indicates that the latest version of the runtime isn't installed on your computer. Install the common language runtime version that is intended for use with your compiler. -See [appdomain](../../cpp/appdomain.md) for more information. +For more information, see [`appdomain`](../../cpp/appdomain.md) + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1207.md b/docs/error-messages/compiler-errors-1/fatal-error-c1207.md index 77a59a8b13..5302f9c823 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1207.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1207.md @@ -1,17 +1,19 @@ --- description: "Learn more about: Fatal Error C1207" title: "Fatal Error C1207" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1207"] helpviewer_keywords: ["C1207"] ms.assetid: cd31b410-9523-47db-883c-e69a9351ffa2 --- # Fatal Error C1207 -Managed templates not supported by the version of the runtime installed +> Managed templates not supported by the version of the runtime installed C1207 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1207 install the common language runtime version that is intended for use with your compiler. +To resolve C1207, install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1208.md b/docs/error-messages/compiler-errors-1/fatal-error-c1208.md index 0609c245d9..304879dfc5 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1208.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1208.md @@ -1,17 +1,19 @@ --- description: "Learn more about: Fatal Error C1208" title: "Fatal Error C1208" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1208"] helpviewer_keywords: ["C1208"] ms.assetid: 4eefd8f0-5c2e-4a11-9e63-293e1139db65 --- # Fatal Error C1208 -Allocating reference classes on the stack is not supported by the version of the runtime installed +> Allocating reference classes on the stack is not supported by the version of the runtime installed C1208 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. Install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1209.md b/docs/error-messages/compiler-errors-1/fatal-error-c1209.md index 0d417de1bc..1029773c30 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1209.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1209.md @@ -1,19 +1,21 @@ --- description: "Learn more about: Fatal Error C1209" title: "Fatal Error C1209" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1209"] helpviewer_keywords: ["C1209"] ms.assetid: aa9ee10f-abe3-4683-9792-adca4cbbabb5 --- # Fatal Error C1209 -Friend assemblies not supported by the version of the runtime installed +> Friend assemblies not supported by the version of the runtime installed C1208 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1209, install the common language runtime that shipped with the compiler you are using. +To resolve C1209, install the common language runtime that shipped with the compiler you're using. For more information, see [Friend Assemblies (C++)](../../dotnet/friend-assemblies-cpp.md). + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1210.md b/docs/error-messages/compiler-errors-1/fatal-error-c1210.md index 4167d5d456..09aac9e2bd 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1210.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1210.md @@ -1,19 +1,21 @@ --- description: "Learn more about: Fatal Error C1210" title: "Fatal Error C1210" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1210"] helpviewer_keywords: ["C1210"] ms.assetid: e2208309-c284-425c-a7e8-48e96e66f35b --- # Fatal Error C1210 -> /clr:pure and /clr:safe are not supported by the version of the runtime installed +> `/clr:pure` and `/clr:safe` are not supported by the version of the runtime installed -The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +The **`/clr:pure`** and **`/clr:safe`** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. C1210 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1210 install the common language runtime version that is intended for use with your compiler. +To resolve C1210, install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1211.md b/docs/error-messages/compiler-errors-1/fatal-error-c1211.md index 8fed88ea02..174c78ea00 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1211.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1211.md @@ -1,19 +1,21 @@ --- description: "Learn more about: Fatal Error C1211" title: "Fatal Error C1211" -ms.date: "11/04/2016" +ms.date: 08/17/2022 f1_keywords: ["C1211"] helpviewer_keywords: ["C1211"] ms.assetid: df0ca70d-ec6e-4400-926a-b877e2599978 --- # Fatal Error C1211 -The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed +> The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed C1211 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1211 install the common language runtime that shipped with the compiler you are using. +To resolve C1211, install the common language runtime that shipped with the compiler you're using. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c999.md b/docs/error-messages/compiler-errors-1/fatal-error-c999.md deleted file mode 100644 index 1a519a2067..0000000000 --- a/docs/error-messages/compiler-errors-1/fatal-error-c999.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: "Learn more about: Fatal Error C999" -title: "Fatal Error C999" -ms.date: "11/04/2016" -f1_keywords: ["C999"] -helpviewer_keywords: ["C999"] -ms.assetid: a3a49a96-a352-4ff2-aa84-84eb6a9a81f1 ---- -# Fatal Error C999 - -UNKNOWN MESSAGE Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information - -This error usually means that you have mixed files from different versions of the compiler, or your compiler installation is corrupted. Use the **Programs and Features** applet in the Control Panel to repair or reinstall the product. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2504.md b/docs/error-messages/compiler-errors-2/compiler-error-c2504.md index d20e2ff8b2..454446e651 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2504.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2504.md @@ -10,7 +10,7 @@ ms.assetid: c9e002a6-a4ee-4ba7-970e-edf4adb83692 'class' : base class undefined -The base class is declared but never defined. Possible causes: +The base class is declared but never defined. Possible causes: 1. Missing include file. @@ -23,11 +23,7 @@ The following sample generates C2504: // compile with: /c class A; class B : public A {}; // C2504 -``` - -// OK -``` -class C{}; -class D : public C {}; +class C {}; +class D : public C {}; // OK ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2510.md b/docs/error-messages/compiler-errors-2/compiler-error-c2510.md index 3d234c77f0..6f3e7b8c2a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2510.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2510.md @@ -11,3 +11,18 @@ ms.assetid: bf6d28db-f2f4-48f8-8f4e-7d662ed278fe 'identifier' : left of '::' must be a class/struct/union A class, structure, or union name must appear on the left side of the scope-resolution operator (`::`) operator. + +The following sample generates C2510: + +```cpp +// C2510.cpp +struct S { + static const int x = 1; +}; + +int main() { + S s; + int num1 = s::x; // C2510 + int num2 = S::x; // OK +} +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2526.md b/docs/error-messages/compiler-errors-2/compiler-error-c2526.md index 07b4d610a3..bd212154e2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2526.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2526.md @@ -1,13 +1,26 @@ --- description: "Learn more about: Compiler Error C2526" title: "Compiler Error C2526" -ms.date: "11/04/2016" +ms.date: "03/08/2024" f1_keywords: ["C2526"] helpviewer_keywords: ["C2526"] -ms.assetid: 0f8c554c-f990-457e-bcae-b6f273481825 --- # Compiler Error C2526 'identifier1' : C linkage function cannot return C++ class 'identifier2' A function defined with C linkage cannot return a user-defined type. + +The following sample generates C2526: + +```cpp +// C2526.cpp +// compile with: /c +template +class A {}; + +extern "C" A func() // C2526 +{ + return A(); +} +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2534.md b/docs/error-messages/compiler-errors-2/compiler-error-c2534.md index b363a21ccd..71081526b9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2534.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2534.md @@ -10,17 +10,27 @@ ms.assetid: 481f9f54-5b51-4aa0-8eea-218f10807705 'identifier' : constructor cannot return a value -A constructor cannot return a value or have a return type (not even a **`void`** return type). - -This error may be fixed by removing the **`return`** statement from the constructor definition. +A constructor cannot contain a **`return`** statement with an expression (even if the expression has type **`void`**). This differs from regular void-returning function where a return expression of type **`void`** is allowed. However, using the **`return`** statement without an expression is allowed for early returns in the constructor. The following sample generates C2534: ```cpp // C2534.cpp +// compile with: /c +void void_func() {} + class A { public: int i; - A() { return i; } // C2534 + A() { + return i; // C2534 + return 123; // C2534 + return (void)0; // C2534 + return void_func(); // C2534 + + return; // OK + } }; ``` + +The preceding errors may be fixed by removing the entire **`return`** statement or omitting the return expression if an early return is desired. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2537.md b/docs/error-messages/compiler-errors-2/compiler-error-c2537.md index 23c52c10d0..10f8c00625 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2537.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2537.md @@ -1,26 +1,22 @@ --- description: "Learn more about: Compiler Error C2537" title: "Compiler Error C2537" -ms.date: "11/04/2016" +ms.date: "03/08/2024" f1_keywords: ["C2537"] helpviewer_keywords: ["C2537"] -ms.assetid: aee81d8e-300e-4a8b-b6c4-b3828398b34e --- # Compiler Error C2537 'specifier' : illegal linkage specification -Possible causes: - -1. The linkage specifier is not supported. Only the "C" linkage specifier is supported. - -1. "C" linkage is specified for more than one function in a set of overloaded functions. This is not allowed. +The linkage specifier is not supported. Only the "C" and "C++" linkage specifiers are supported. The following sample generates C2537: ```cpp // C2537.cpp // compile with: /c -extern "c" void func(); // C2537 +extern "c" void func1(); // C2537 extern "C" void func2(); // OK +extern "C++" void func3(); // OK ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2548.md b/docs/error-messages/compiler-errors-2/compiler-error-c2548.md index 607c8fad3e..6b59cfc2b6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2548.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2548.md @@ -1,27 +1,39 @@ --- description: "Learn more about: Compiler Error C2548" -title: "Compiler Error C2548" -ms.date: "11/04/2016" +title: "Compiler error C2548" +ms.date: "03/01/2024" f1_keywords: ["C2548"] helpviewer_keywords: ["C2548"] -ms.assetid: 01e9c835-9bf3-4020-9295-5ee448c519f3 --- -# Compiler Error C2548 +# Compiler error C2548 'class::member' : missing default parameter for parameter parameter -The default parameter list is missing a parameter. If you supply a default parameter anywhere in a parameter list, you must define default parameters for all subsequent parameters. +The default parameter list is missing a parameter. If you supply a default parameter anywhere in a parameter list, you must define default parameters for all subsequent parameters in the current declaration or any previous declarations within the same scope. ## Example -The following sample generates C2548: +The following sample generates C2548 for: + +- `func1` because it's missing the default argument `b`. +- `func3` because it's missing the default argument `c`. + +The following sample doesn't generate C2548 for: + +- `func2` because all the required default arguments are supplied. +- The second `func4` declaration because the default argument `c` is supplied in the preceding declaration and is in the same scope. +- The third `func4` declaration because both default arguments `b` and `c` are provided previously. ```cpp // C2548.cpp // compile with: /c -void func( int = 1, int, int = 3); // C2548 +void func1(int a = 1, int b, int c = 3); // C2548 + +void func2(int a = 1, int b = 2, int c = 3); // OK + +void func3(int a, int b = 2, int c); // C2548 -// OK -void func2( int, int, int = 3); -void func3( int, int = 2, int = 3); +void func4(int a, int b, int c = 3); // OK +void func4(int a, int b = 2, int c); // OK +void func4(int a = 1, int b, int c); // OK ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2574.md b/docs/error-messages/compiler-errors-2/compiler-error-c2574.md index 0581e78c1f..cc557824ff 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2574.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2574.md @@ -1,25 +1,30 @@ --- -description: "Learn more about: Compiler Error C2574" title: "Compiler Error C2574" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2574" +ms.date: 06/04/2025 f1_keywords: ["C2574"] helpviewer_keywords: ["C2574"] -ms.assetid: 3e1c5c18-ee8b-4dbb-bfc0-d3b8991af71b --- # Compiler Error C2574 -'destructor' : cannot be declared static +> '*function*': cannot be declared static + +## Remarks -Neither destructors nor constructors can be declared **`static`**. +Neither [constructors](../../cpp/constructors-cpp.md) nor [destructors](../../cpp/destructors-cpp.md) can be declared **`static`**. -The following sample generates C2574: +## Example + +The following example generates C2574: ```cpp // C2574.cpp // compile with: /c -class A { - virtual static ~A(); // C2574 - // try the following line instead - // virtual ~A(); +struct S +{ + static S() {} // C2574 + + // Try the following line instead: + // S() {} }; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2583.md b/docs/error-messages/compiler-errors-2/compiler-error-c2583.md index be529b59a7..e6a0d84075 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2583.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2583.md @@ -1,28 +1,30 @@ --- -description: "Learn more about: Compiler Error C2583" title: "Compiler Error C2583" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2583" +ms.date: 06/06/2025 f1_keywords: ["C2583"] helpviewer_keywords: ["C2583"] -ms.assetid: b1c952dc-872c-47e4-9fc8-4dd72bcee6f9 --- # Compiler Error C2583 -'identifier' : 'const/volatile' 'this' pointer is illegal for constructors/destructors +> '*identifier*': '*const/volatile*' 'this' pointer is illegal for constructors/destructors + +## Remarks + +A [constructor](../../cpp/constructors-cpp.md) or [destructor](../../cpp/destructors-cpp.md) can't be declared **`const`** or **`volatile`**. -A constructor or destructor is declared **`const`** or **`volatile`**. This is not allowed. +## Example -The following sample generates C2583: +The following example generates C2583: ```cpp // C2583.cpp // compile with: /c -class A { -public: - int i; - A() const; // C2583 +struct S +{ + S() const {} // C2583 - // try the following line instead - // A(); + // Try the following line instead: + // S() {} }; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2601.md b/docs/error-messages/compiler-errors-2/compiler-error-c2601.md index 451d97d15c..0a5225628f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2601.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2601.md @@ -1,28 +1,51 @@ --- -description: "Learn more about: Compiler Error C2601" title: "Compiler Error C2601" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2601" +ms.date: 06/04/2025 f1_keywords: ["C2601"] helpviewer_keywords: ["C2601"] -ms.assetid: 88275582-5f37-45d7-807d-05f06ba00965 --- # Compiler Error C2601 -'function' : local function definitions are illegal +> '*function*': local function definitions are illegal + +## Remarks Code tries to define a function within a function. -Or, there may be an extra brace in your source code before the location of the C2601 error. +Or, there may be an extra/missing brace before the location of the C2601 error. -The following sample generates C2601: +## Examples + +### Define function within a function + +[Lambda Expressions](../../cpp/lambda-expressions-in-cpp.md) may be used to emulate the behavior of local functions: ```cpp -// C2601.cpp -int main() { - int i = 0; +// C2601a.cpp +int main() +{ + int increment(int value) // C2601 + { + return value + 1; + } + + // Try the following line instead: + // auto increment = [](int value) { return value + 1; }; - void funcname(int j) { // C2601 - j++; - } + int two = increment(1); } ``` + +### Missing closing brace + +If a preceding function is missing a closing brace, the subsequent function is taken to be a local function: + +```cpp +// C2601b.cpp +void func() +{ +// missing '}' brace here + +int main() {} // C2601 +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2640.md b/docs/error-messages/compiler-errors-2/compiler-error-c2640.md index c1467898ef..5014adb77d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2640.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2640.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: Compiler Error C2640" title: "Compiler Error C2640" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2640" +ms.date: "03/17/2025" f1_keywords: ["C2640"] helpviewer_keywords: ["C2640"] -ms.assetid: e4d137ab-ed1d-457c-9eec-b70d97f1b0b4 --- # Compiler Error C2640 -'identifier' : __based modifier illegal on reference +> 'abstract declarator': __based modifier illegal on reference -The **`__based`** modifier can be used on pointers only. +The [**`__based`**](../../cpp/based-pointers-cpp.md) modifier can be used on pointers only. The following sample generates C2640: ```cpp // C2640.cpp -void f(int i) { - void *vp; - int _based(vp) &vr = I; // C2640 +int* ptr; + +int main() +{ + int __based(ptr)& based_ref; // C2640 + int __based(ptr)* based_ptr; // OK } ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2647.md b/docs/error-messages/compiler-errors-2/compiler-error-c2647.md index 20f2b56c02..736eee85d9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2647.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2647.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C2647" title: "Compiler Error C2647" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2647" +ms.date: 11/04/2016 f1_keywords: ["C2647"] helpviewer_keywords: ["C2647"] -ms.assetid: 1034589e-bc3e-41a6-831f-2a1a4b8a2500 --- # Compiler Error C2647 'operator': cannot dereference a 'type1' on a 'type2' -The left operand of a pointer-to-member operator ( `->*` or `.*` ) cannot be implicitly converted to a type related to the right operator. +The left operand of a pointer-to-member operator (`->*` or `.*`) cannot be implicitly converted to a type related to the right operator. The following sample generates C2647: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2653.md b/docs/error-messages/compiler-errors-2/compiler-error-c2653.md index b1cbd55778..dba63492f1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2653.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2653.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2653" title: "Compiler Error C2653" -ms.date: "11/30/2017" +description: "Learn more about: Compiler Error C2653" +ms.date: 11/30/2017 f1_keywords: ["C2653"] helpviewer_keywords: ["C2653"] -ms.assetid: 3f49e731-affd-43a0-a8d0-181db7650bc3 --- # Compiler Error C2653 @@ -14,7 +13,7 @@ The language syntax requires a class, structure, union, or namespace name here. This error can occur when you use a name that has not been declared as a class, structure, union, or namespace in front of a scope operator. To fix this issue, declare the name or include the header that declares the name before it is used. -C2653 is also possible if you try to define a *compound namespace*, a namespace that contains one or more scope-nested namespace names. Compound namespace definitions are not allowed in C++ prior to C++17. Compound namespaces are supported starting in Visual Studio 2015 Update 3 when you specify the [`/std:c++latest`](../../build/reference/std-specify-language-standard-version.md) compiler option. Starting in Visual Studio 2017 version 15.5, the compiler supports compound namespace definitions when the `[/std:c++17`](../../build/reference/std-specify-language-standard-version.md) or later option is specified. +C2653 is also possible if you try to define a *compound namespace*, a namespace that contains one or more scope-nested namespace names. Compound namespace definitions are not allowed in C++ prior to C++17. Compound namespaces are supported starting in Visual Studio 2015 Update 3 when you specify the [`/std:c++latest`](../../build/reference/std-specify-language-standard-version.md) compiler option. Starting in Visual Studio 2017 version 15.5, the compiler supports compound namespace definitions when the [`/std:c++17`](../../build/reference/std-specify-language-standard-version.md) or later option is specified. ## Examples diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2659.md b/docs/error-messages/compiler-errors-2/compiler-error-c2659.md index 8971dceda1..ab818a1f07 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2659.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2659.md @@ -30,7 +30,7 @@ int main() To resolve this issue, change the declaration of the identifier so that it is not parsed as a function declaration. -Error C2659 can also occur when the function has a type that can’t be used in the expression on the left side of the specified operator. This example generates C2659 when the code assigns a function pointer to a function: +Error C2659 can also occur when the function has a type that can't be used in the expression on the left side of the specified operator. This example generates C2659 when the code assigns a function pointer to a function: ```cpp // C2659b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2676.md b/docs/error-messages/compiler-errors-2/compiler-error-c2676.md index ef6a6bae96..c2368b92a6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2676.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2676.md @@ -1,14 +1,16 @@ --- description: "Learn more about: Compiler Error C2676" title: "Compiler Error C2676" -ms.date: "11/04/2016" +ms.date: 06/03/2022 f1_keywords: ["C2676"] helpviewer_keywords: ["C2676"] ms.assetid: 838a5e34-c92f-4f65-a597-e150bf8cf737 --- # Compiler Error C2676 -binary 'operator' : 'type' does not define this operator or a conversion to a type acceptable to the predefined operator +> binary '*operator*' : 'type*' does not define this operator or a conversion to a type acceptable to the predefined operator + +## Remarks To use the operator, you must overload it for the specified type or define a conversion to a type for which the operator is defined. @@ -46,7 +48,7 @@ int main() { C2676 can also occur if you attempt to do pointer arithmetic on the **`this`** pointer of a reference type. -The **`this`** pointer is of type handle in a reference type. For more information, see [Semantics of the this pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). +The **`this`** pointer is of type handle in a reference type. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). The following sample generates C2676. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2701.md b/docs/error-messages/compiler-errors-2/compiler-error-c2701.md index ba58effeea..7db2a0789f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2701.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2701.md @@ -1,16 +1,16 @@ --- description: "Learn more about: Compiler Error C2701" title: "Compiler Error C2701" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["C2701"] helpviewer_keywords: ["C2701"] ms.assetid: 31cf2ab7-ced9-4f75-aa51-e169e20407fb --- # Compiler Error C2701 -'function' : a function template cannot be a friend of a local class +> 'function': a function template cannot be a `friend` of a local class -A local class cannot have a template function as a friend function. +A local class can't have a function template as a `friend` function. The following sample generates C2701: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2751.md b/docs/error-messages/compiler-errors-2/compiler-error-c2751.md index c2d5e50061..6a466cdf6a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2751.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2751.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler Error C2751" title: "Compiler Error C2751" -ms.date: "11/04/2016" +ms.date: "03/11/2024" f1_keywords: ["C2751"] helpviewer_keywords: ["C2751"] -ms.assetid: 44a3abdf-8a87-4a09-b34b-532c220c310a --- # Compiler Error C2751 @@ -16,11 +15,11 @@ The following sample generates C2751: ```cpp // C2751.cpp -namespace std { - template - class list {}; +// compile with: /c +namespace NS +{ + class C {}; } -#define list std::list -void f(int &list){} // C2751 +void func(int NS::C) {} // C2751 ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2768.md b/docs/error-messages/compiler-errors-2/compiler-error-c2768.md index 36d6ca0157..c8ae01c2c0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2768.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2768.md @@ -8,12 +8,16 @@ ms.assetid: a7f6047a-6a80-4737-ad5c-c12868639fb5 --- # Compiler Error C2768 -'function' : illegal use of explicit template arguments +> 'function': illegal use of explicit template arguments -The compiler was unable to determine if a function definition was supposed to be an explicit specialization of a function template or if the function definition was supposed to be for a new function. +## Remarks + +The compiler was unable to determine if a function definition was an explicit specialization of a function template or if it was a new function. This error was introduced in Visual Studio .NET 2003, as part of the compiler conformance enhancements. +## Example + The following sample generates C2768: ```cpp @@ -27,6 +31,6 @@ void f(int) {} // C2768 template<> void f(int) {} -// global nontemplate function overload +// global non-template function overload void f(int) {} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2834.md b/docs/error-messages/compiler-errors-2/compiler-error-c2834.md index b1116f2a31..716e1c7e5a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2834.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2834.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Compiler Error C2834" title: "Compiler Error C2834" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2834"] helpviewer_keywords: ["C2834"] ms.assetid: 28f9f6eb-ab2a-4e64-aaaa-9d14f955de41 --- # Compiler Error C2834 -'operator operator' must be globally qualified +> 'operator *operator-name*' must be globally qualified The `new` and `delete` operators are tied to the class where they reside. Scope resolution cannot be used to select a version of `new` or `delete` from a different class. To implement multiple forms of the `new` or `delete` operator, create a version of the operator with extra formal parameters. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2835.md b/docs/error-messages/compiler-errors-2/compiler-error-c2835.md index 4dbcb7c9d5..ae076c90af 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2835.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2835.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2835" title: "Compiler Error C2835" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2835" +ms.date: 11/04/2016 f1_keywords: ["C2835"] helpviewer_keywords: ["C2835"] -ms.assetid: 41c70630-983f-4da2-8342-513cf48b0519 --- # Compiler Error C2835 @@ -22,12 +21,12 @@ public: A() { v_char = 'A'; - }; + } operator char(char a) { // C2835 // try the following line instead // operator char() { return v_char + 1; - }; + } }; int main() { diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2858.md b/docs/error-messages/compiler-errors-2/compiler-error-c2858.md index fb178633af..5c73c903ae 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2858.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2858.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Compiler Error C2858" title: "Compiler Error C2858" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2858"] helpviewer_keywords: ["C2858"] ms.assetid: 1fb1d770-307e-476e-9984-a1d8f8ce2820 --- # Compiler Error C2858 -command-line option '/Yc (/Fdfilename)' inconsistent with precompiled header, which used '/Fdfilename' +> command-line option '/Yc (/Fd*filename1*)' inconsistent with precompiled header, which used '/Fd*filename2*' -The program database specified by the Use Precompiled Header ([/Yu](../../build/reference/yu-use-precompiled-header-file.md)) option is not the one specified by the previous Create Precompiled Header ([/Yc](../../build/reference/yc-create-precompiled-header-file.md)) option. +The program database specified by the Use Precompiled Header ([`/Yu`](../../build/reference/yu-use-precompiled-header-file.md)) option is not the one specified by the previous Create Precompiled Header ([`/Yc`](../../build/reference/yc-create-precompiled-header-file.md)) option. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2860.md b/docs/error-messages/compiler-errors-2/compiler-error-c2860.md index 9bd2b0bc53..5d0d595820 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2860.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2860.md @@ -1,22 +1,22 @@ --- description: "Learn more about: Compiler Error C2860" title: "Compiler Error C2860" -ms.date: "11/04/2016" +ms.date: "03/16/2024" f1_keywords: ["C2860"] helpviewer_keywords: ["C2860"] -ms.assetid: ccc83553-90ed-4e94-b5e9-38b58ae38e31 --- # Compiler Error C2860 -'void' cannot be an argument type, except for '(void)' +'void' cannot be used as a function parameter except for '(void)' -Type **`void`** cannot be used as an argument type with other arguments. +A function parameter cannot be of type **`void`**. The following sample generates C2860: ```cpp // C2860.cpp // compile with: /c -void profunc1(void, int i); // C2860 -void func10(void); // OK +void func1(void x); // C2860 +void func2(void, int y); // C2860 +void func3(void); // OK ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2875.md b/docs/error-messages/compiler-errors-2/compiler-error-c2875.md index 299b83fdd7..ed6b53506d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2875.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2875.md @@ -8,10 +8,12 @@ ms.assetid: d589fc0c-08b2-4a79-bc0e-dca5eb80bdd5 --- # Compiler Error C2875 -using-declaration causes a multiple declaration of 'class::identifier' +> using-declaration causes a multiple declaration of 'class::identifier' The declaration causes the same item to be defined twice. +This error is obsolete in Visual Studio 2022 and later versions. + The following sample generates C2875: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2888.md b/docs/error-messages/compiler-errors-2/compiler-error-c2888.md index cfc30eecb9..eed0d34ea2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2888.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2888.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2888" title: "Compiler Error C2888" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2888" +ms.date: 11/04/2016 f1_keywords: ["C2888"] helpviewer_keywords: ["C2888"] -ms.assetid: 244f593e-ff25-4dad-b31f-84dafa3bc84a --- # Compiler Error C2888 @@ -23,7 +22,7 @@ namespace M { void f2(); } - void N::f1() {} // OK: namspace M encloses N + void N::f1() {} // OK: namespace M encloses N } namespace O { diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2893.md b/docs/error-messages/compiler-errors-2/compiler-error-c2893.md index 7e1fab4903..01cb21c042 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2893.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2893.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2893" title: "Compiler Error C2893" +description: "Learn more about: Compiler Error C2893" ms.date: "11/04/2016" f1_keywords: ["C2893"] helpviewer_keywords: ["C2893"] -ms.assetid: ec0cbe43-005d-45da-8742-aaeb9b81d28e --- # Compiler Error C2893 @@ -21,7 +20,7 @@ C2893 occurs because `f`'s template parameter `T` is deduced to be `std::map +#include using namespace std; class MyClass {}; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2896.md b/docs/error-messages/compiler-errors-2/compiler-error-c2896.md index 24b7149f88..32db06f54f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2896.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2896.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2896" title: "Compiler Error C2896" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2896"] helpviewer_keywords: ["C2896"] ms.assetid: b600407b-cb05-42e3-9069-2aa6960f0eaa --- # Compiler Error C2896 -'function1' : cannot use function template 'function2' as argument +> '*function1*' : cannot use function template '*function2*' as argument -A function template cannot be an argument to another function template. +A function template can't be an argument to another function template. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2896: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2902.md b/docs/error-messages/compiler-errors-2/compiler-error-c2902.md index 3f554c72ef..1769f12a7d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2902.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2902.md @@ -1,17 +1,19 @@ --- description: "Learn more about: Compiler Error C2902" title: "Compiler Error C2902" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2902"] helpviewer_keywords: ["C2902"] ms.assetid: 89d78d0e-78e5-4c2c-a0f9-a60110e9395e --- # Compiler Error C2902 -'token' : unexpected token following 'template', identifier expected +> '*token*' : unexpected token following '*template*', identifier expected The token following the keyword **`template`** was not an identifier. +This error is obsolete in Visual Studio 2022 and later versions. + The following sample generates C2902: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2917.md b/docs/error-messages/compiler-errors-2/compiler-error-c2917.md index 64c029aefd..f7b627b426 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2917.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2917.md @@ -1,16 +1,20 @@ --- description: "Learn more about: Compiler Error C2917" title: "Compiler Error C2917" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2917"] helpviewer_keywords: ["C2917"] ms.assetid: ec9da9ee-0f37-47b3-87dd-19ef5a14dc4c --- # Compiler Error C2917 -'name' : invalid template-parameter +> '*name*' : invalid template-parameter -A template parameter list contains an identifier that was not a template parameter. +## Remarks + +A template parameter list contains an identifier that wasn't a template parameter. + +This error is obsolete in Visual Studio 2022 and later versions. ## Example diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2927.md b/docs/error-messages/compiler-errors-2/compiler-error-c2927.md index 2421022f3a..26c2fc59b5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2927.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2927.md @@ -10,4 +10,4 @@ ms.assetid: 3f75beec-ff5c-44e1-9085-990ecd55198d 'function' : a function template must be called with at least one argument -You cannot call a template function without arguments. The type of the template arguments determines what version of the function to generate. +You cannot call a function template without arguments. The type of the template arguments determines what version of the function to generate. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2931.md b/docs/error-messages/compiler-errors-2/compiler-error-c2931.md index ac9eb359f4..569af1e587 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2931.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2931.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2931" title: "Compiler Error C2931" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2931"] helpviewer_keywords: ["C2931"] ms.assetid: 33430407-b149-4ba3-baf8-b0dae1ea3a5d --- # Compiler Error C2931 -'class' : type-class-id redefined as a member function of 'identifier' +'*class*' : type-class-id redefined as a member function of '*identifier*' -You cannot use a generic or template class as a member function of another class. +You can't use a generic or template class as a member function of another class. + +This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2932.md b/docs/error-messages/compiler-errors-2/compiler-error-c2932.md index 3b82428f14..3ec4a323b0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2932.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2932.md @@ -8,9 +8,11 @@ ms.assetid: c28e88d9-e654-4367-bfb4-13c780bca9bd --- # Compiler Error C2932 -'class' : type-class-id redefined as a data member of 'identifier' +> '*class*' : type-class-id redefined as a data member of '*identifier*' -You cannot use a generic or template class as a data member. +You can't use a generic or template class as a data member. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2932: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2933.md b/docs/error-messages/compiler-errors-2/compiler-error-c2933.md index b88ca9e143..c908e2a05c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2933.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2933.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2933" title: "Compiler Error C2933" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2933"] helpviewer_keywords: ["C2933"] ms.assetid: 394891e3-6b52-4b61-83d2-a1c5125d9bd5 --- # Compiler Error C2933 -'class' : type-class-id redefined as a typedef member of 'identifier' +> '*class*' : type-class-id redefined as a typedef member of '*identifier*' -You cannot use a generic or template class as a **`typedef`** member. +You can't use a generic or template class as a **`typedef`** member. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2933: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2934.md b/docs/error-messages/compiler-errors-2/compiler-error-c2934.md index f69f239ab6..f95f66da05 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2934.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2934.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Compiler Error C2934" title: "Compiler Error C2934" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2934"] helpviewer_keywords: ["C2934"] ms.assetid: b7f7e7aa-2d4c-4e17-8564-2c005ab81fd5 --- # Compiler Error C2934 -'class' : type-class-id redefined as a nested 'item' of 'identifier' +'*class*' : type-class-id redefined as a nested 'item' of '*identifier*' -You cannot use a generic or template class as a nested item. +You can't use a generic or template class as a nested item. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2935.md b/docs/error-messages/compiler-errors-2/compiler-error-c2935.md index 0190d4ebf4..277c0cafd5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2935.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2935.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2935" title: "Compiler Error C2935" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2935"] helpviewer_keywords: ["C2935"] ms.assetid: e11ef90d-0756-4e43-8a09-4974c6aa72a3 --- # Compiler Error C2935 -'class' : type-class-id redefined as a global function +> '*class*' : type-class-id redefined as a global function -You cannot use a generic or template class as a global function. +You can't use a generic or template class as a global function. + +This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2936.md b/docs/error-messages/compiler-errors-2/compiler-error-c2936.md index 6ab1bdda19..0b7ee74a59 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2936.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2936.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2936" title: "Compiler Error C2936" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2936"] helpviewer_keywords: ["C2936"] ms.assetid: 5d1ba0fc-0c78-4a37-a83b-1ef8527763be --- # Compiler Error C2936 -'class' : type-class-id redefined as a global data variable +> '*class*' : type-class-id redefined as a global data variable -You cannot use a generic or template class as a global data variable. +You can't use a generic or template class as a global data variable. + +This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2937.md b/docs/error-messages/compiler-errors-2/compiler-error-c2937.md index 331412e975..7c14567bc2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2937.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2937.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2937" title: "Compiler Error C2937" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2937"] helpviewer_keywords: ["C2937"] ms.assetid: 95671ca3-79f7-4b56-a5f2-a92296da1629 --- # Compiler Error C2937 -'class' : type-class-id redefined as a global typedef +> '*class*' : type-class-id redefined as a global typedef -You cannot use a generic or template class as a global **`typedef`**. +You can't use a generic or template class as a global **`typedef`**. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2937: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2939.md b/docs/error-messages/compiler-errors-2/compiler-error-c2939.md index 3e55634518..602ed451dc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2939.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2939.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2939" title: "Compiler Error C2939" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2939"] helpviewer_keywords: ["C2939"] ms.assetid: 455b050b-f2dc-4b5b-bd6a-e1f81d3d1644 --- # Compiler Error C2939 -'class' : type-class-id redefined as a local data variable +> '*class*' : type-class-id redefined as a local data variable -You cannot use a generic or template class as a local data variable. +You can't use a generic or template class as a local data variable. + +This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2940.md b/docs/error-messages/compiler-errors-2/compiler-error-c2940.md index 7d7c809c40..dec4f0abd4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2940.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2940.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2940" title: "Compiler Error C2940" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2940"] helpviewer_keywords: ["C2940"] ms.assetid: af6bf2bf-8de6-4cfd-bbf0-4c6b32a30edf --- # Compiler Error C2940 -'class' : type-class-id redefined as a local typedef +> '*class*' : type-class-id redefined as a local typedef -You cannot use a generic or template class as a local **`typedef`**. +You can't use a generic or template class as a local **`typedef`**. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2940: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2941.md b/docs/error-messages/compiler-errors-2/compiler-error-c2941.md index 964a413e31..53c28a6c84 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2941.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2941.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Compiler Error C2941" title: "Compiler Error C2941" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2941"] helpviewer_keywords: ["C2941"] ms.assetid: 1bba94eb-5bf6-468d-8f84-96a6391a7048 --- # Compiler Error C2941 -'class' : type-class-id redefined as a local 'item' +> '*class*' : type-class-id redefined as a local 'item' -You cannot use a generic or template class as an item. +You can't use a generic or template class as an item. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2942.md b/docs/error-messages/compiler-errors-2/compiler-error-c2942.md index 0f389b5c89..8342663126 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2942.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2942.md @@ -1,21 +1,22 @@ --- description: "Learn more about: Compiler Error C2942" title: "Compiler Error C2942" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2942"] helpviewer_keywords: ["C2942"] ms.assetid: 13abf744-8fa1-450d-886d-e5717c04956e --- # Compiler Error C2942 -'class' : type-class-id redefined as a formal argument of a function +> '*class*' : type-class-id redefined as a formal argument of a function -You cannot use a generic or template class as a formal argument. You cannot pass an argument directly to the constructor of a generic or template class. +You can't use a generic or template class as a formal argument. You cannot pass an argument directly to the constructor of a generic or template class. -The following sample generates C2942: +This error is obsolete in Visual Studio 2022 and later versions. -``` +The following sample generates C2942: +```cpp // C2942.cpp // compile with: /c template diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2943.md b/docs/error-messages/compiler-errors-2/compiler-error-c2943.md index 58aa4c44cf..99b4d8f7ab 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2943.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2943.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2943" title: "Compiler Error C2943" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2943"] helpviewer_keywords: ["C2943"] ms.assetid: ede6565e-d892-44c0-8eee-c69545f3be2e --- # Compiler Error C2943 -'class' : type-class-id redefined as a type argument of a template +> '*class*' : type-class-id redefined as a type argument of a template -You cannot use a generic or template class, instead of a symbol, as a generic or template type argument. +You can't use a generic or template class, instead of a symbol, as a generic or template type argument. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2943: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2944.md b/docs/error-messages/compiler-errors-2/compiler-error-c2944.md index 5705f61b8a..6886658694 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2944.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2944.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Compiler Error C2944" title: "Compiler Error C2944" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C2944"] helpviewer_keywords: ["C2944"] ms.assetid: f209e668-e72f-442a-a438-8c4ff43a404a --- # Compiler Error C2944 -'class' : type-class-id redefined as a value argument of a template +> '*class*' : type-class-id redefined as a value argument of a template -You cannot use a generic or template class, instead of a symbol, as a template value argument. +You can't use a generic or template class, instead of a symbol, as a template value argument. + +This error is obsolete in Visual Studio 2022 and later versions. The following sample generates C2944: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2956.md b/docs/error-messages/compiler-errors-2/compiler-error-c2956.md new file mode 100644 index 0000000000..d5fc918703 --- /dev/null +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2956.md @@ -0,0 +1,62 @@ +--- +description: "Learn more about: Compiler Error C2956" +title: "Compiler Error C2956" +ms.date: 04/05/2022 +f1_keywords: ["C2956"] +helpviewer_keywords: ["C2956"] +--- +# Compiler Error C2956 + +> usual deallocation function '*function*' would be chosen as placement deallocation function + +The deallocation function found for the placement new expression matches one of the usual deallocation functions. Either an implicit compiler-generated deallocation or an explicit `delete` (or `delete[]`) would use the wrong deallocation function. + +## Remarks + +Error C2956 indicates you used a *placement new expression* (a `new` expression that takes parameters) in a way that can cause a memory leak or runtime crash. It usually means the resulting value can't be deleted in a typical way. That is, either an explicit `delete` (or `delete[]`) expression in your code, or the implicit deallocation when a constructor throws an exception, could invoke the wrong `operator delete` or supply it with the wrong parameters. + +The C++ standard specifies *usual deallocation functions* as overloads of `operator delete` or `operator delete[]` that take extra parameters of type `std::size_t` (C++14 or later), `std::align_val_t` (C++17 or later), and `std::destroying_delete_t` (C++20 or later). When you use a placement new expression, the compiler looks for a matching `operator delete` function that takes the same parameters (after the first one). If one is found and its signature matches a usual deallocation function, the compiler reports error C2956. + +The way to resolve the issue depends in part on your intent. For example, in C++11, you could define an `operator new` overload that takes an extra `size_t` parameter in your class to pass a value to the allocator. In C++14, the same code now causes an error: + +```cpp +#include +struct T { + void* operator new(std::size_t, std::size_t); // Placement allocation function + void operator delete(void*, std::size_t); // now considered a usual deallocation function +}; + +T* p = new (0) T; // error: usual deallocation function would be chosen as placement deallocation function +``` + +If your intent is to specify over-aligned memory for an object, you can instead specify the alignment directly on the type by using `alignas`. For more information about `alignas`, see [Alignment](../../cpp/alignment-cpp-declarations.md). + +If your intent is to specify over-aligned memory for a heap-allocated native type or an array, wrap it in a `struct` or `class` that has the `alignas` specifier. Then normal `new` and `delete` expressions can allocate and deallocate instances that have your intended alignment. + +## Example + +In this example, the *`new-expression`* uses placement syntax with an argument of type `std::align_val_t`. However, since type `T` doesn't specify an alignment requirement, a *`delete-expression`* on a `T*` won't invoke a matching over-aligned deallocation function. Instead, the compiler would invoke the usual deallocation function `void operator delete(void* ptr) noexcept`, which doesn't handle an over-aligned allocation. Rather than cause a crash or a memory leak, the compiler reports an error for this use of placement `new`: + +```cpp +#include +struct T {}; + +int main() +{ + T* p = new (std::align_val_t{64}) T; // C2956 + delete p; // ordinary, not over-aligned delete +} +``` + +To resolve this issue, apply an `alignas` specifier to `T`: + +```cpp +#include +struct alignas(64) T {}; + +int main() +{ + T* p = new T; // invokes ::operator new(std::size_t, std::align_val_t) + delete p; // now invokes ::operator delete(void*, std::align_val_t) +} +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2978.md b/docs/error-messages/compiler-errors-2/compiler-error-c2978.md index 4426147e9a..cf6adef493 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2978.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2978.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C2978" title: "Compiler Error C2978" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2978" +ms.date: 11/04/2016 f1_keywords: ["C2978"] helpviewer_keywords: ["C2978"] -ms.assetid: 5e7bee82-e266-4ccd-ad2e-ee89606ec5bf --- # Compiler Error C2978 syntax error : expected 'keyword1' or 'keyword2'; found type 'keyword3'; non-type parameters are not supported in generics -A generic class was declared incorrectly. See [Generics](../../extensions/generics-cpp-component-extensions.md)for more information. +A generic class was declared incorrectly. See [Generics](../../extensions/generics-cpp-component-extensions.md) for more information. ## Example diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2992.md b/docs/error-messages/compiler-errors-2/compiler-error-c2992.md index 228162b189..2220dec821 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2992.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2992.md @@ -20,30 +20,34 @@ The following sample generates C2992: // C2992.cpp // compile with: /c template -struct TC1 { +struct Outer { template - struct TC2; + struct Inner; }; -template struct TC1::TC2 {}; // C2992 +template // C2992 +struct Outer::Inner {}; -// OK template -template -struct TC1::TC2 {}; -// C2992 can also occur when using generics: -// C2992c.cpp -// compile with: /clr /c +template // OK +struct Outer::Inner {}; +``` + +C2992 can also occur when using generics: + +```cpp +// C2992b.cpp +// compile with: /c /clr generic -ref struct GC1 { +ref struct Outer { generic - ref struct GC2; + ref struct Inner; }; -generic ref struct GC1::GC2 {}; // C2992 +generic // C2992 +ref struct Outer::Inner {}; -// OK generic -generic -ref struct GC1::GC2 {}; +generic // OK +ref struct Outer::Inner {}; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2993.md b/docs/error-messages/compiler-errors-2/compiler-error-c2993.md index 27ca013f1e..3588a205e1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2993.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2993.md @@ -1,43 +1,51 @@ --- description: "Learn more about: Compiler Error C2993" title: "Compiler Error C2993" -ms.date: "11/04/2016" +ms.date: "10/03/2023" f1_keywords: ["C2993"] helpviewer_keywords: ["C2993"] -ms.assetid: 4ffd2b78-654b-46aa-95a6-b62101cf91c8 --- # Compiler Error C2993 'identifier' : illegal type for non-type template parameter 'parameter' -You cannot declare a template with a structure or union argument. Use pointers to pass structures and unions as template parameters. +- Prior to C++20, you cannot declare a template with a structure, class, or union argument. Pointers can be used in place of these types as template parameters. +- Since C++20, structure, class, or unions *can* be used as non-type template parameters. A non-type template parameter can't be a rvalue reference type or a parameter pack of rvalue types. The following sample generates C2993: ```cpp -// C2993.cpp -// compile with: /c -// C2993 expected -struct MyStruct { - int a;char b; -}; - -template // C2993 - -// try the following line instead -// template -class CMyClass {}; +// compile with: /c and /std:c++17 +template // C2993 +struct S1 {}; + +template // C2993 +struct S2 {}; +``` + +Before MSVC 19.26, the following code emitted C2993. It now emits C7582: + +```cpp +// compile with: /c /std:c++17 +struct MyStruct {}; + +template // Was C2993 prior to MSVC 19.26. Now emits C7582. +class MyClass1 {}; + +template // OK +class MyClass2 {}; ``` -This error will also be generated as a result of compiler conformance work that was done in Visual Studio .NET 2003: floating point non-type template parameters no longer allowed. The C++ standard does not allow floating point non-type template parameters. +With C++17 and earlier, you can't have floating point non-type template parameters. Since C++20, floating point non-type template parameters are allowed. Use a function argument to pass the floating point non-type template parameter to function templates. -If it is a function template, use a function argument to pass in the floating point non-type template parameter (this code will be valid in the Visual Studio .NET 2003 and Visual Studio .NET versions of Visual C++). If it is a class template, there is no easy workaround. +Before MSVC 19.26, the following code emitted C2993. It now emits C7582: ```cpp // C2993b.cpp -// compile with: /c -template void func(T) {} // C2993 +// compile with: /c /std:c++17 +template // Was C2993 prior to MSVC 19.26. Now emits C7592 +void func1(T t) {} -// OK -template void func2(T, float) {} +template // OK +void func2(T t, float F) {} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3047.md b/docs/error-messages/compiler-errors-2/compiler-error-c3047.md index 688a37e915..33412373c1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3047.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3047.md @@ -1,17 +1,19 @@ --- description: "Learn more about: Compiler Error C3047" title: "Compiler Error C3047" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C3047"] helpviewer_keywords: ["C3047"] ms.assetid: 91c14566-5958-433d-8549-0e8bc3196f76 --- # Compiler Error C3047 -Structured block in an OpenMP 'sections' region must be preceded by '#pragma omp section' +> Structured block in an OpenMP 'sections' region must be preceded by '#pragma omp section' Any code in a code block introduced by a [sections](../../parallel/openmp/reference/openmp-directives.md#sections-openmp) directive must be in a code block introduced by a `section` directive. +This error is obsolete in Visual Studio 2022 and later versions. + The following sample generates C3047: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3054.md b/docs/error-messages/compiler-errors-2/compiler-error-c3054.md index cd3cf421a1..4961c563e5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3054.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3054.md @@ -1,17 +1,21 @@ --- description: "Learn more about: Compiler Error C3054" title: "Compiler Error C3054" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C3054"] helpviewer_keywords: ["C3054"] ms.assetid: 6f4b7ac5-0d12-474b-b611-76ff26ee41ac --- # Compiler Error C3054 -'#pragma omp parallel' is currently not supported in a generic class or function +> '#pragma omp parallel' is currently not supported in a generic class or function + +## Remarks For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md) and [OpenMP](../../parallel/openmp/openmp-in-visual-cpp.md). +This error is obsolete in Visual Studio 2022 and later versions. + ## Example The following sample generates C3054. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3185.md b/docs/error-messages/compiler-errors-2/compiler-error-c3185.md index cad61481f3..315365082c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3185.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3185.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3185" title: "Compiler Error C3185" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3185" +ms.date: 11/04/2016 f1_keywords: ["C3185"] helpviewer_keywords: ["C3185"] -ms.assetid: 5bf96279-043c-4981-9d02-b4550071b192 --- # Compiler Error C3185 @@ -25,5 +24,5 @@ int main() { Base ^pb = pd; const type_info & t1 = typeid(pb); // C3185 System::Type ^ MyType = Base::typeid; // OK -}; +} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3189.md b/docs/error-messages/compiler-errors-2/compiler-error-c3189.md index 8a40773ddb..6197c274ae 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3189.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3189.md @@ -8,10 +8,12 @@ ms.assetid: b254de79-931e-4a59-a9f4-1c690d90ca5e --- # Compiler Error C3189 -'typeid\': this syntax is no longer supported, use ::typeid instead +> 'typeid\': this syntax is no longer supported, use ::typeid instead An obsolete form of [typeid](../../extensions/typeid-cpp-component-extensions.md) was used, use the new form. +This error is obsolete in Visual Studio 2022 and later versions. + The following sample generates C3189: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3206.md b/docs/error-messages/compiler-errors-2/compiler-error-c3206.md index 0a8b124440..0832f2a6eb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3206.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3206.md @@ -10,7 +10,7 @@ ms.assetid: d62995b5-e349-4418-bbe8-8a5e776ca7b0 'function' : invalid type argument for 'param', missing type argument list on class type 'typename' -A template function is defined as taking a template type argument. However, a template template argument was passed. +A function template is defined as taking a template type argument. However, a template template argument was passed. The following sample generates C3206: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3207.md b/docs/error-messages/compiler-errors-2/compiler-error-c3207.md index 4fc51223a1..bef3bea2a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3207.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3207.md @@ -10,7 +10,7 @@ ms.assetid: 4a28b976-142a-4cff-aa2f-480b892c50ca 'function' : invalid template argument for 'arg', class template expected -A template function is defined as taking a template template argument. However, a template type argument was passed. +A function template is defined as taking a template template argument. However, a template type argument was passed. The following sample generates C3207: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3251.md b/docs/error-messages/compiler-errors-2/compiler-error-c3251.md index 96f1b29072..8756c4429d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3251.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3251.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Compiler Error C3251" title: "Compiler Error C3251" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C3251"] helpviewer_keywords: ["C3251"] ms.assetid: 541c163e-5ee9-457c-a1e5-da860788b10d --- # Compiler Error C3251 -cannot invoke base class method on a value type instance +> cannot invoke base class method on a value type instance The following error occurs because `GetClass` is a member of `Microsoft.Runtime.Object`, not of `Microsoft.Runtime.Integer4`. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3275.md b/docs/error-messages/compiler-errors-2/compiler-error-c3275.md index 86df5b4566..ec6d61c49e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3275.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3275.md @@ -1,15 +1,15 @@ --- description: "Learn more about: Compiler Error C3275" title: "Compiler Error C3275" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C3275"] helpviewer_keywords: ["C3275"] ms.assetid: 5752680f-7d3e-4c42-ba9c-845e09d32e7a --- # Compiler Error C3275 -'enum member' : cannot use this symbol without qualifier +> 'enum member' : cannot use this symbol without qualifier When using managed code and when two or more enumerations contain an identifier with the same name, you must explicitly qualify references to the identifier. -C3275 is only reachable using the obsolete compiler option **/clr:oldSyntax**. +C3275 is only reachable using the obsolete compiler option **`/clr:oldSyntax`**. It's not generated in Visual Studio 2022 or later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3485.md b/docs/error-messages/compiler-errors-2/compiler-error-c3485.md index ac8553ee8a..f1a6261029 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3485.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3485.md @@ -1,16 +1,20 @@ --- description: "Learn more about: Compiler Error C3485" title: "Compiler Error C3485" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["C3485"] helpviewer_keywords: ["C3485"] ms.assetid: d67536f9-67a1-4ad9-9a94-d8bbbca3d0dc --- # Compiler Error C3485 -a lambda definition cannot have any cv-qualifiers +> a lambda definition cannot have any cv-qualifiers -You cannot use a **`const`** or **`volatile`** qualifier as part of the definition of a lambda expression. +## Remarks + +You can't use a **`const`** or **`volatile`** qualifier as part of the definition of a lambda expression. + +This error is obsolete in Visual Studio 2022. ### To correct this error @@ -29,6 +33,8 @@ int main() } ``` +To fix it, remove the **`const`** qualifier. + ## See also -[Lambda Expressions](../../cpp/lambda-expressions-in-cpp.md) +[Lambda expressions](../../cpp/lambda-expressions-in-cpp.md) diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3536.md b/docs/error-messages/compiler-errors-2/compiler-error-c3536.md index 1701d26b5a..0e13e6df59 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3536.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3536.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3536" title: "Compiler Error C3536" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3536" +ms.date: 11/04/2016 f1_keywords: ["C3536"] helpviewer_keywords: ["C3536"] -ms.assetid: 8d866075-866b-49eb-9979-ee27b308f7e3 --- # Compiler Error C3536 @@ -31,7 +30,7 @@ int main() auto* d = &d; //C3536 auto& e = e; //C3536 return 0; -}; +} ``` ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3550.md b/docs/error-messages/compiler-errors-2/compiler-error-c3550.md index abecd370ee..01e5f18565 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3550.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3550.md @@ -10,7 +10,23 @@ ms.assetid: 9f2d5ffc-e429-41a1-89e3-7acc4fd47e14 only plain 'decltype(auto)' is allowed in this context -If `decltype(auto)` is used as a placeholder for the return type of a function, it must be used by itself. It cannot be used as part of a pointer declaration (`decltype(auto*)`), a reference declaration (`decltype(auto&)`), or any other such qualification. +If [`decltype(auto)`](../../cpp/decltype-cpp.md#decltype-and-auto) is used as a placeholder for the return type of a function, it must be used by itself. It cannot be used as part of a pointer declaration (`decltype(auto)*`), a reference declaration (`decltype(auto)&`), or any other such qualification. + +## Example + +The following sample generates C3550: + +```cpp +// C3550.cpp +// compile with: /c +decltype(auto)* func1(); // C3550 +decltype(auto)& func2(); // C3550 +decltype(auto)&& func3(); // C3550 + +auto* func4(); // OK +``` + +To resolve the error remove all illegal qualification on `decltype(auto)`. For instance, `decltype(auto)* func1()` can be turned into `auto* func1()`. ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3551.md b/docs/error-messages/compiler-errors-2/compiler-error-c3551.md index 1220d333bf..0423abf69e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3551.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3551.md @@ -1,21 +1,25 @@ --- description: "Learn more about: Compiler Error C3551" title: "Compiler Error C3551" -ms.date: "11/04/2016" +ms.date: "10/07/2023" f1_keywords: ["C3551"] helpviewer_keywords: ["C3551"] ms.assetid: c8ee23da-6568-40db-93a6-3ddb7ac47712 --- # Compiler Error C3551 -"expected a late specified return type" +if a trailing return type is used then the leading return type shall be the single type-specifier 'auto' (not 'type') -If you use the **`auto`** keyword as a placeholder for the return type of a function, you must provide a late-specified return type. In the following example, the late-specified return type of function `myFunction` is a pointer to an array of four elements of type **`int`**. +The leading return type in [trailing return type](../../cpp/functions-cpp.md#trailing-return-types) syntax must contain only `auto`. -``` -auto myFunction()->int(*)[4]; -``` +```cpp +// C3551.cpp +// compile with: /c +const auto func1() -> const int; // C3551 +auto* func2() -> int*; // C3551 +auto& func3() -> int&; // C3551 +auto&& func4() -> int&&; // C3551 +decltype(auto) func5() -> int; // C3551 -## See also - -[auto](../../cpp/auto-cpp.md) +auto func6() -> int; // OK +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3630.md b/docs/error-messages/compiler-errors-2/compiler-error-c3630.md index 9364e595cb..d5fd687898 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3630.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3630.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Compiler Error C3630" title: "Compiler Error C3630" -ms.date: "11/04/2016" +ms.date: 05/25/2022 f1_keywords: ["C3630"] helpviewer_keywords: ["C3630"] ms.assetid: 865626a9-98cc-465d-acde-44d4574c019a --- # Compiler Error C3630 -error when processing the token 'token' +> error when processing the token '*token*' -A token in source code could not be processed. +A token in source code couldn't be processed. This error is obsolete in Visual Studio 2022. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3672.md b/docs/error-messages/compiler-errors-2/compiler-error-c3672.md index 3624f2563d..d217e41c36 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3672.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3672.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3672" title: "Compiler Error C3672" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3672" +ms.date: 11/04/2016 f1_keywords: ["C3672"] helpviewer_keywords: ["C3672"] -ms.assetid: da971041-1766-467a-aecf-1d8655c6cb7a --- # Compiler Error C3672 @@ -22,7 +21,7 @@ template void f(T* pT) { &pT->T::~T; // C3672 pT->T::~T(); // OK -}; +} int main() { int i; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3859.md b/docs/error-messages/compiler-errors-2/compiler-error-c3859.md index 87c08ccdc3..f46601d681 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3859.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3859.md @@ -1,15 +1,34 @@ --- description: "Learn more about: Compiler Error C3859" title: "Compiler Error C3859" -ms.date: "03/08/2019" +ms.date: 02/22/2022 f1_keywords: ["C3859"] helpviewer_keywords: ["C3859"] -ms.assetid: 40e93b25-4393-4467-90de-035434a665c7 --- # Compiler Error C3859 -> virtual memory range for PCH exceeded; please recompile with a command line option of '-Zm*value*' or greater +> Failed to create virtual memory for PCH -The virtual memory allocated for your precompiled header is too small for the amount of data the compiler is trying to put in it. Starting in Visual Studio 2015, the **/Zm** recommendation is only significant when using the `#pragma hdrstop` directive. In other cases, it's a spurious error that indicates Windows virtual memory pressure issues. +The message has one of the following notes: +>The system returned code *error code*: *OS error message*\ +>PCH: Address is not a multiple of the system's allocation granularity\ +>PCH: The chunk has not been previously reserved\ +>PCH: Commit size too large\ +>PCH: Unable to commit memory across file map\ +>PCH: Exhausted chunk list before committing all bytes\ +>PCH: Unexpected end of chunk list while trying to free\ +>PCH: Shouldn't be hitting a file map in the decommit case\ +>PCH: Invalid chunk\ +>PCH: Map size too large\ +>PCH: Unable to map file: memory already committed\ +>PCH: File map already in place\ +>PCH: Unable to get the requested block of memory\ +>Consider using /Fp to allow the compiler to reserve the memory early -If your precompiled header uses a `#pragma hdrstop` directive, use the **/Zm** compiler flag to specify a larger value for the precompiled header file. Otherwise, consider reducing the number of parallel compilation processes in your build. For more information, see [/Zm (Specify Precompiled Header Memory Allocation Limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md). +There isn't enough virtual memory allocated for your [precompiled header (PCH)](../../build/creating-precompiled-header-files.md). If your precompiled header uses an explicit `#pragma hdrstop` directive, use the **`/Zm`** compiler flag to specify a larger value for the precompiled header file. Otherwise, consider reducing the number of parallel compilation processes in your build. For more information, see [`/Zm` (Specify precompiled header memory allocation limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md). + +This diagnostic shows up mostly in two scenarios: + +The first scenario is that the system is overloaded with multiple `/Yu` compile requests at the same time. Setting the maximum starting virtual memory size typically resolves this issue. + +The second scenario is when the the Windows loader injects a DLL into the process at startup. That injected DLL can allocate memory that conflicts with where the PCH must reside. For example, `msbuild.exe` injects `FileTracker.dll` into every `CL.exe` process at startup. In this scenario, using the [`/Fp` (Name .pch file)](../../build/reference/fp-name-dot-pch-file.md) flag ensures that the memory for the PCH is allocated as early as possible in the `CL.exe` process, before any injected DLLs try to occupy the address space. These failures can be intermittent because Windows Address Space Layout Randomization (ASLR) allocates memory at different addresses across different process invocations. Without `/Fp`, memory for the PCH can't be allocated until the compiler finds the header file `#include` specified in the `/Yu` command line option or the `#pragma hdrstop`. By this time, it's much more likely that the memory required by the PCH is already reserved. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3861.md b/docs/error-messages/compiler-errors-2/compiler-error-c3861.md index 465d8e150e..738a3e76f4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3861.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3861.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: Compiler Error C3861" title: "Compiler Error C3861" -ms.date: "03/23/2018" +description: "Learn more about: Compiler Error C3861" +ms.date: 06/29/2022 f1_keywords: ["C3861"] helpviewer_keywords: ["C3861"] -ms.assetid: 0a1eee30-b3db-41b1-b1e5-35949c3924d7 --- # Compiler Error C3861 > '*identifier*': identifier not found -The compiler was not able to resolve a reference to an identifier, even using argument-dependent lookup. +The compiler was unable to resolve a reference to an identifier, even using argument-dependent lookup. ## Remarks -To fix this error, compare use of *identifier* to the identifier declaration for case and spelling. Verify that [scope resolution operators](../../cpp/scope-resolution-operator.md) and namespace [using directives](../../cpp/namespaces-cpp.md#using_directives) are used correctly. If the identifier is declared in a header file, verify that the header is included before the identifier is referenced. If the identifier is meant to be externally visible, make sure that it is declared in any source file that uses it. Also check that the identifier declaration or definition is not excluded by [conditional compilation directives](../../preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md). +To fix this error, compare use of *identifier* to the identifier declaration for case and spelling. Verify that [scope resolution operators](../../cpp/scope-resolution-operator.md) and namespace [`using` directives](../../cpp/namespaces-cpp.md#using_directives) are used correctly. If the identifier is declared in a header file, verify that the header is included before the identifier is referenced. If the identifier is meant to be externally visible, make sure that it's declared in any source file that uses it. Also check that the identifier declaration or definition isn't excluded by [conditional compilation directives](../../preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md). -Changes to remove obsolete functions from the C Runtime Library in Visual Studio 2015 can cause C3861. To resolve this error, remove references to these functions or replace them with their secure alternatives, if any. For more information, see [Obsolete Functions](../../c-runtime-library/obsolete-functions.md). +Changes to remove obsolete functions from the C Runtime Library in Visual Studio 2015 can cause C3861. To resolve this error, remove references to these functions or replace them with their secure alternatives, if any. For more information, see [Obsolete functions](../../c-runtime-library/obsolete-functions.md). -If error C3861 appears after project migration from older versions of the compiler, you may have issues related to supported Windows versions. Visual C++ no longer supports targeting Windows 95, Windows 98, Windows ME, Windows NT or Windows 2000. If your **WINVER** or **_WIN32_WINNT** macros are assigned to one of these versions of Windows, you must modify the macros. For more information, see [Modifying WINVER and _WIN32_WINNT](../../porting/modifying-winver-and-win32-winnt.md). +If error C3861 appears after project migration from older versions of the compiler, you may have issues related to supported Windows versions. Visual C++ no longer supports targeting Windows 95, Windows 98, Windows ME, Windows NT or Windows 2000. If your **`WINVER`** or **`_WIN32_WINNT`** macros are assigned to one of these versions of Windows, you must modify the macros. For more information, see [Modifying `WINVER` and `_WIN32_WINNT`](../../porting/modifying-winver-and-win32-winnt.md). ## Examples ### Undefined identifier -The following sample generates C3861 because the identifier is not defined. +The following sample generates C3861 because the identifier isn't defined. ```cpp // C3861.cpp @@ -37,7 +36,9 @@ int main() { ### Identifier not in scope -The following sample generates C3861 because an identifier is only visible in the file scope of its definition, unless it is declared in other source files that use it. +The following sample generates C3861, because an identifier is only visible in the file scope of its definition, unless it's declared in other source files that use it. + +Source file `C3861_a1.cpp`: ```cpp // C3861_a1.cpp @@ -50,6 +51,8 @@ int main() { } ``` +Source file `C3861_a2.cpp`: + ```cpp // C3861_a2.cpp int f() { // declared and defined here @@ -94,7 +97,7 @@ int main() { ### ADL and friend functions -The following sample generates C3767 because the compiler cannot use argument dependent lookup for `FriendFunc`: +The following sample generates C3861 because the compiler can't use argument dependent lookup for `FriendFunc`: ```cpp namespace N { diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3867.md b/docs/error-messages/compiler-errors-2/compiler-error-c3867.md index 8a22a876fe..db31e6aef7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3867.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3867.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3867" title: "Compiler Error C3867" +description: "Learn more about: Compiler Error C3867" ms.date: "11/04/2016" f1_keywords: ["C3867"] helpviewer_keywords: ["C3867"] -ms.assetid: bc5de03f-e01a-4407-88c3-2c63f0016a1e --- # Compiler Error C3867 @@ -42,7 +41,7 @@ The following sample generates C3867 and shows how to fix it. ```cpp // C3867_2.cpp -#include +#include struct S { char *func() { diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3872.md b/docs/error-messages/compiler-errors-2/compiler-error-c3872.md index 134462ee8f..65ac7afb1f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3872.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3872.md @@ -12,7 +12,7 @@ ms.assetid: 519e95be-5641-40cc-894c-da4819506604 The C++ compiler follows the C++11 standard on characters allowed in an identifier. Only certain ranges of characters and universal character names are allowed in an identifier. Additional restrictions apply to the initial character of an identifier. For more information and a list of allowed characters and universal character name ranges, see [Identifiers](../../cpp/identifiers-cpp.md). -The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications/standards/Ecma-335.htm). +The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://ecma-international.org/publications-and-standards/standards/ecma-335/). The following sample generates C3872: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3873.md b/docs/error-messages/compiler-errors-2/compiler-error-c3873.md index 4ecff3c14d..90f0de0b05 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3873.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3873.md @@ -12,7 +12,7 @@ ms.assetid: e68fd3be-2391-492b-ac3f-d2428901b2e9 The C++ compiler follows the C++11 standard on characters allowed in an identifier. Only certain ranges of characters and universal character names are allowed in an identifier. Additional restrictions apply to the initial character of an identifier. For more information and a list of allowed characters and universal character name ranges, see [Identifiers](../../cpp/identifiers-cpp.md). -The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications/standards/Ecma-335.htm). +The range of characters allowed in an identifier is less restrictive when compiling C++/CLI code. Identifiers in code compiled by using /clr should follow [Standard ECMA-335: Common Language Infrastructure (CLI)](https://ecma-international.org/publications-and-standards/standards/ecma-335/). The following sample generates C3873: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3883.md b/docs/error-messages/compiler-errors-2/compiler-error-c3883.md index 5ffa8913d6..6ed6a89c19 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3883.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3883.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C3883" title: "Compiler Error C3883" +description: "Learn more about: Compiler Error C3883" ms.date: "11/04/2016" f1_keywords: ["C3883"] helpviewer_keywords: ["C3883"] -ms.assetid: cdd1c1f4-f268-4469-9c62-d52303114b0c --- # Compiler Error C3883 -'var' : an initonly static data member must be initialized +> '*member*': an initonly static data member must be initialized A variable marked with [initonly](../../dotnet/initonly-cpp-cli.md) was not initialized correctly. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7510.md b/docs/error-messages/compiler-errors-2/compiler-error-c7510.md index c528336d5b..4d310b7a6f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c7510.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7510.md @@ -58,7 +58,7 @@ struct X : Base }; ``` -In Visual Studio 2019 under **`/std:c++20`** or later, template function bodies that have **`if constexpr`** statements have extra parsing-related checks enabled. For example, in Visual Studio 2017 the following code produces C7510 only if the **`/permissive-`** option is set. In Visual Studio 2019 the same code raises errors even when the **`/permissive`** option is set: +In Visual Studio 2019 under **`/std:c++20`** or later, function template bodies that have **`if constexpr`** statements have extra parsing-related checks enabled. For example, in Visual Studio 2017 the following code produces C7510 only if the **`/permissive-`** option is set. In Visual Studio 2019 the same code raises errors even when the **`/permissive`** option is set: ```cpp // C7510.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7553.md b/docs/error-messages/compiler-errors-2/compiler-error-c7553.md new file mode 100644 index 0000000000..63cd4464c5 --- /dev/null +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7553.md @@ -0,0 +1,75 @@ +--- +title: "Compiler Error C7553" +description: Compiler Error C7553 description and solution. +ms.date: 02/22/2022 +f1_keywords: ["C7553"] +helpviewer_keywords: ["C7553"] +--- +# Compiler Error C7553 + +> inline assembler is not supported in a lambda + +## Remarks + +In versions of Visual Studio before Visual Studio 2017 version 15.9, the use of inline-assembler within a lambda could lead to the corruption of `ebp` (the return address register) at runtime. A malicious attacker could possibly take advantage of this scenario. The inline assembler is only supported on x86, and interaction between the inline assembler and the rest of the compiler is poor. Given these facts and the nature of the issue, the safest solution to this problem was to disallow inline assembler within a lambda expression. + +The only use of inline assembler within a lambda expression that we have found 'in the wild' was to capture the return address. In this scenario, you can capture the return address on all platforms simply by using a compiler intrinsic `_ReturnAddress()`. + +Compiler Error C7553 occurs in Visual Studio starting in Visual Studio 2017 version 15.9. + +## Example + +The following code produces C7553 in Visual Studio 2017 15.9 and later versions: + +```cpp +#include + +int f() +{ + int y = 1724; + int x = 0xdeadbeef; + + auto lambda = [&] + { + __asm { // C7553: inline assembler is not supported in a lambda + + mov eax, x + mov y, eax + } + }; + + lambda(); + return y; +} +``` + +To avoid the error, move the assembly code into a named function as shown in the following example: + +```cpp +#include + +void g(int& x, int& y) +{ + __asm { + mov eax, x + mov y, eax + } +} + +int f() +{ + int y = 1724; + int x = 0xdeadbeef; + auto lambda = [&] + { + g(x, y); + }; + lambda(); + return y; +} + +int main() +{ + std::printf("%d\n", f()); +} +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7688.md b/docs/error-messages/compiler-errors-2/compiler-error-c7688.md new file mode 100644 index 0000000000..8716a20d4f --- /dev/null +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7688.md @@ -0,0 +1,44 @@ +--- +title: "Compiler error C7688" +description: Compiler error C7688 description and solution. +ms.date: 03/01/2023 +f1_keywords: ["C7688"] +helpviewer_keywords: ["C7688"] +--- +# Compiler error C7688 + +> '`pragma omp atomic`': expected an expression of scalar type + +## Remarks + +OpenMP restricts expressions in `#pragma omp atomic` constructs to scalar type. + +Compiler error C7688 is new in Visual Studio 2022 version 17.4. In previous compiler versions, the compiler would emit error [C3048](compiler-error-c3048.md). + +## Example + +The sample code shows diagnostics generated for non-scalar types in `#pragma omp atomic` constructs. + +```cpp +// C7688.cpp +// compile using /c /openmp:llvm +struct S { char c; }; +S operator+(S, int); + +void test() +{ + S s1, s2; + #pragma omp atomic capture + { s1 = s2; s2 = s1 + 1; } +} +/* +When built, the compiler emits: + +.\C7688.cpp(10,10): error C7688: '#pragma omp atomic': expected an expression of scalar type + { s1 = s2; s2 = s1 + 1; } + ^ +.\C7688.cpp(10,10): note: type is 'S' +*/ +``` + +To resolve this issue, use scalar types in `#pragma omp atomic` constructs. diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599.md b/docs/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599.md index dc47e09a5b..62ed444ca7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C2500 Through C2599" title: "Compiler errors C2500 Through C2599" -ms.date: "04/21/2019" +description: "Learn more about: Compiler errors C2500 Through C2599" +ms.date: 04/21/2019 f1_keywords: ["C2501", "C2508", "C2515", "C2519", "C2520", "C2522", "C2525", "C2527", "C2536", "C2538", "C2539", "C2546", "C2547", "C2559", "C2560", "C2564", "C2565", "C2576", "C2578", "C2580", "C2590", "C2591", "C2595", "C2596"] helpviewer_keywords: ["C2501", "C2508", "C2515", "C2519", "C2520", "C2522", "C2525", "C2527", "C2536", "C2538", "C2539", "C2546", "C2547", "C2559", "C2560", "C2564", "C2565", "C2576", "C2578", "C2580", "C2590", "C2591", "C2595", "C2596"] -ms.assetid: a869aaed-e9f6-49e3-b273-00ea7f45bed7 --- # Compiler errors C2500 Through C2599 @@ -34,7 +33,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C2515|'*identifier*': 'vtguard' can only be applied to class declarations or definitions| |[Compiler error C2516](compiler-error-C2516.md)|'*class*': is not a legal base class| |[Compiler error C2517](compiler-error-C2517.md)|'*identifier*': right of '::' is undefined| -|[Compiler error C2518](compiler-error-C2518.md)|keyword '*keyword*' illegal in base class list; ignored| +|[Compiler error C2518](compiler-error-C2518.md)|keyword '*keyword*' is invalid in a base class list; expected a `class` name| |Compiler error C2519|'*identifier*': WinRT attributes may only contain public fields| |Compiler error C2520|'*class*': no non-explicit constructor available for implicit conversion| |[Compiler error C2521](compiler-error-C2521.md)|a destructor/finalizer does not take any arguments| @@ -64,12 +63,13 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2545](compiler-error-C2545.md)|'*operator*': unable to find overloaded operator| |Compiler error C2546|'*identifier*': when a type is defined in both a PIA and a no-PIA the PIA must be referenced first| |Compiler error C2547|'*identifier*': All parameters of a published method must be explicitly named on the declaration| -|[Compiler error C2548](compiler-error-C2548.md)|'*function*': missing default parameter for parameter *parameter*| +|[Compiler error C2548](compiler-error-C2548.md)|'*function*': missing default argument for parameter *parameter*| |[Compiler error C2549](compiler-error-C2549.md)|user-defined conversion cannot specify a return type| |[Compiler error C2550](compiler-error-C2550.md)|'*identifier*': constructor initializer lists are only allowed on constructor definitions| |[Compiler error C2551](compiler-error-C2551.md)|'void *' type needs explicit cast| |[Compiler error C2552](compiler-error-C2552.md)|'*identifier*': non-aggregates cannot be initialized with an initializer list| |[Compiler error C2553](compiler-error-C2553.md)|'*type* *derived_class*::*function*': overriding virtual function return type differs from '*type* *base_class*::*function*'| +|Compiler error C2554|'*variable*': 'constinit' only allowed on a variable declaration with static or thread storage duration| |[Compiler error C2555](compiler-error-C2555.md)|'*derived_class*::*function*': overriding virtual function return type differs and is not covariant from '*base_class*::*function*'| |[Compiler error C2556](compiler-error-C2556.md)|'*type1* *class*::*function*': overloaded function differs only by return type from '*type2* *class*::*function*'| |[Compiler error C2557](compiler-error-C2557.md)|'*identifier*': private and protected members cannot be initialized without a constructor| @@ -89,7 +89,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2571](compiler-error-C2571.md)|'*identifier*': virtual function cannot be in union '*union*'| |[Compiler error C2572](compiler-error-C2572.md)|'*function*': redefinition of default argument: parameter *number*| |[Compiler error C2573](compiler-error-C2573.md)|'*class*': cannot delete pointers to objects of this type; the class has no non-placement overload for 'operator delete'. Use ::delete, or add 'operator delete(void*)' to the class| -|[Compiler error C2574](compiler-error-C2574.md)|'*destructor*': cannot be declared static| +|[Compiler error C2574](compiler-error-C2574.md)|'*function*': cannot be declared static| |[Compiler error C2575](compiler-error-C2575.md)|'*identifier*': only member functions and bases can be virtual| |Compiler error C2576|'*identifier*': cannot introduce a new virtual method as 'public'. Consider making the method non-virtual, or change the accessibility to 'internal' or 'protected private'| |[Compiler error C2577](compiler-error-C2577.md)|'*identifier*': a destructor/finalizer cannot have a return type| @@ -98,7 +98,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C2580|'*identifier*': multiple versions of a defaulted special member functions are not allowed| |[Compiler error C2581](compiler-error-C2581.md)|'*type*': static 'operator =' function is illegal| |[Compiler error C2582](compiler-error-C2582.md)|'operator *operator*' function is unavailable in '*type*'| -|[Compiler error C2583](compiler-error-C2583.md)|'*identifier*': 'const/volatile' 'this' pointer is illegal for constructors/destructors| +|[Compiler error C2583](compiler-error-C2583.md)|'*identifier*': '*const/volatile*' 'this' pointer is illegal for constructors/destructors| |[Compiler error C2584](compiler-error-C2584.md)|'*class*': direct base '*base_class2*' is inaccessible; already a base of '*base_class1*'| |[Compiler error C2585](compiler-error-C2585.md)|explicit conversion to '*type*' is ambiguous| |[Compiler error C2586](compiler-error-C2586.md)|incorrect user-defined conversion syntax: illegal indirections| diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c2600-through-c2699.md b/docs/error-messages/compiler-errors-2/compiler-errors-c2600-through-c2699.md index 4c6182230c..e8cbf106a7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c2600-through-c2699.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c2600-through-c2699.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C2600 Through C2699" title: "Compiler errors C2600 Through C2699" +description: "Learn more about: Compiler errors C2600 Through C2699" ms.date: "04/21/2019" f1_keywords: ["C2604", "C2606", "C2607", "C2608", "C2609", "C2610", "C2615", "C2618", "C2620", "C2621", "C2622", "C2623", "C2625", "C2629", "C2631", "C2639", "C2641", "C2642", "C2643", "C2644", "C2684", "C2685", "C2686", "C2697"] helpviewer_keywords: ["C2604", "C2606", "C2607", "C2608", "C2609", "C2610", "C2615", "C2618", "C2620", "C2621", "C2622", "C2623", "C2625", "C2629", "C2631", "C2639", "C2641", "C2642", "C2643", "C2644", "C2684", "C2685", "C2686", "C2697"] -ms.assetid: 73c6319f-cbea-4a2f-913b-90dc1af61f64 --- # Compiler errors C2600 Through C2699 @@ -24,17 +23,17 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2605](compiler-error-c2605.md)|'*identifier*': this method is reserved within a managed/WinRT class| |Compiler error C2606|'*class1*': cannot re-implement '*member*', as it is inherited from runtime base '*class2*'| |Compiler error C2607|static assertion failed| -|Compiler error C2608|Obsolete.| -|Compiler error C2609|Obsolete.| +|Compiler error C2608|invalid token '*token*' in macro parameter list| +|Compiler error C2609|missing ')' in macro parameter list| |Compiler error C2610|'*class*::*member*': is not a special member function which can be defaulted| |[Compiler error C2611](compiler-error-c2611.md)|'*token*': illegal following '~' (expected identifier)| |[Compiler error C2612](compiler-error-c2612.md)|trailing '*character*' illegal in base/member initializer list| |[Compiler error C2613](compiler-error-c2613.md)|trailing '*character*' illegal in base class list| |[Compiler error C2614](compiler-error-c2614.md)|'*class*': illegal member initialization: '*identifier*' is not a base or member| -|Compiler error C2615|Obsolete.| +|Compiler error C2615|'`offsetof`' cannot be applied to non-class type '*type*'| |[Compiler error C2616](compiler-error-c2616.md)|'*conversion*': cannot implicitly convert a non-lvalue '*type1*' to a '*type2*' that is not const| |[Compiler error C2617](compiler-error-c2617.md)|'*function*': inconsistent return statement| -|Compiler error C2618|Obsolete.| +|Compiler error C2618|illegal member designator in `offsetof`| |[Compiler error C2619](compiler-error-c2619.md)|'*identifier*': a static data member is not allowed in an anonymous struct/union| |Compiler error C2620|Obsolete.| |Compiler error C2621|Obsolete.| @@ -55,12 +54,12 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2636](compiler-error-c2636.md)|'*identifier*': pointer to reference member is illegal| |[Compiler error C2637](compiler-error-c2637.md)|'*identifier*': cannot modify pointers to data members| |[Compiler error C2638](compiler-error-c2638.md)|'*identifier*': __based modifier illegal on pointer to member| -|Compiler error C2639|Obsolete.| -|[Compiler error C2640](compiler-error-c2640.md)|'*identifier*': __based modifier illegal on reference| -|Compiler error C2641|Obsolete.| -|Compiler error C2642|Obsolete.| -|Compiler error C2643|Obsolete.| -|Compiler error C2644|Obsolete.| +|Compiler error C2639|trailing return type '*type*' of deduction guide should be a specialization of '*class template*'| +|[Compiler error C2640](compiler-error-c2640.md)|'abstract declarator': __based modifier illegal on reference| +|Compiler error C2641|cannot deduce template arguments for '*template name*'| +|Compiler error C2642|two deduction guide declarations for the same class template cannot have equivalent parameter list and template head| +|Compiler error C2643|deduction guide should be declared in the same scope as the corresponding class template '*template name*'| +|Compiler error C2644|deduction guide should have the same access as the corresponding class template '*template name*'| |[Compiler error C2645](compiler-error-c2645.md)|no qualified name for pointer to member (found ':: *')| |[Compiler error C2646](compiler-error-c2646.md)|an anonymous struct/union at global or namespace scope must be declared static| |[Compiler error C2647](compiler-error-c2647.md)|'*operator*': cannot dereference a '*type1*' on a '*type2*'| @@ -79,11 +78,11 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2660](compiler-error-c2660.md)|'*function*': function does not take *number* arguments| |[Compiler error C2661](compiler-error-c2661.md)|'*function*': no overloaded function takes *number* arguments| |[Compiler error C2662](compiler-error-c2662.md)|'*function*': cannot convert 'this' pointer from '*type1*' to '*type2*'| -|[Compiler error C2663](compiler-error-c2663.md)|'*function*': *number* overloads have no legal conversion for 'this' pointer| +|[Compiler error C2663](compiler-error-c2663.md)|'*function*': no overloaded function has valid conversion for '`this`' pointer| |[Compiler error C2664](compiler-error-c2664.md)|'*function*': cannot convert argument *number* from '*type1*' to '*type2*'| -|[Compiler error C2665](compiler-error-c2665.md)|'*function*': none of the *number* overloads could convert all the argument types| -|[Compiler error C2666](compiler-error-c2666.md)|'*function*': *number* overloads have similar conversions| -|[Compiler error C2667](compiler-error-c2667.md)|'*function*': none of *number* overloads have a best conversion| +|[Compiler error C2665](compiler-error-c2665.md)|'*function*': no overloaded function could convert all the argument types| +|[Compiler error C2666](compiler-error-c2666.md)|'*function*': overloaded functions have similar conversions| +|[Compiler error C2667](compiler-error-c2667.md)|'*function*': no overloaded function has a best conversion| |[Compiler error C2668](compiler-error-c2668.md)|'*function*': ambiguous call to overloaded function| |[Compiler error C2669](compiler-error-c2669.md)|member function not allowed in anonymous union| |[Compiler error C2670](compiler-error-c2670.md)|'*function*': the function template cannot convert parameter *number* from type '*type*'| diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c2700-through-c2799.md b/docs/error-messages/compiler-errors-2/compiler-errors-c2700-through-c2799.md index 9d44ce11f4..1a597951d4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c2700-through-c2799.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c2700-through-c2799.md @@ -4,7 +4,6 @@ title: "Compiler errors C2700 Through C2799" ms.date: "04/21/2019" f1_keywords: ["C2716", "C2717", "C2727", "C2729", "C2737", "C2740", "C2741", "C2742", "C2744", "C2746", "C2747", "C2759", "C2763", "C2769", "C2772", "C2789", "C2796", "C2799"] helpviewer_keywords: ["C2716", "C2717", "C2727", "C2729", "C2737", "C2740", "C2741", "C2742", "C2744", "C2746", "C2747", "C2759", "C2763", "C2769", "C2772", "C2789", "C2796", "C2799"] -ms.assetid: 6ee257bb-94bc-42b9-af2c-3c73926afba4 --- # Compiler errors C2700 Through C2799 @@ -49,7 +48,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2730](compiler-error-c2730.md)|'*class*': cannot be a base class of itself| |[Compiler error C2731](compiler-error-c2731.md)|'*function*': function cannot be overloaded| |[Compiler error C2732](compiler-error-c2732.md)|linkage specification contradicts earlier specification for '*function*'| -|[Compiler error C2733](compiler-error-c2733.md)|'*function*': second C linkage of overloaded function not allowed| +|[Compiler error C2733](compiler-error-c2733.md)|'*function*': you cannot overload a function with '`extern "C"`' linkage| |[Compiler error C2734](compiler-error-c2734.md)|'*identifier*': 'const' object must be initialized if not 'extern'| |[Compiler error C2735](compiler-error-c2735.md)|'*keyword*' keyword is not permitted in formal parameter type specifier| |[Compiler error C2736](compiler-error-c2736.md)|'*keyword*' keyword is not permitted in cast| @@ -81,7 +80,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2762](compiler-error-c2762.md)|'*template*': invalid expression as a template argument for '*parameter*'| |Compiler error C2763|'*template*': invalid use of a string literal as a template argument for '*parameter*'| |[Compiler error C2764](compiler-error-c2764.md)|'*parameter*': template parameter not used or deducible in partial specialization '*specialization*'| -|[Compiler error C2765](compiler-error-c2765.md)|'*function*': an explicit specialization of a function template cannot have any default arguments| +|[Compiler error C2765](compiler-error-c2765.md)|'*function*': an explicit specialization or instantiation of a function template cannot have any default arguments| |[Compiler error C2766](compiler-error-c2766.md)|explicit specialization; '*specialization*' has already been defined| |[Compiler error C2767](compiler-error-c2767.md)|managed/WinRT array dimension mismatch: expected *number* argument(s) - *number* provided| |[Compiler error C2768](compiler-error-c2768.md)|'*function*': illegal use of explicit template arguments| @@ -113,7 +112,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2794](compiler-error-c2794.md)|'*identifier*': is not a member of any direct or indirect base class of '*class*'| |[Compiler error C2795](compiler-error-c2795.md)|'super::*identifier*' is not a member function| |Compiler error C2796|'ref new' may only be used to create an instance of a WinRT type| -|[Compiler error C2797](compiler-error-c2797.md)|(Obsolete) '*identifier*': list initialization inside member initializer list or non-static data member initializer is not implemented| +|[Compiler error C2797](compiler-error-c2797.md)|'*identifier*': list initialization inside member initializer list or non-static data member initializer is not implemented| |[Compiler error C2798](compiler-error-c2798.md)|'super::*identifier*' is ambiguous| |Compiler error C2799|'*identifier*': an object of const-qualified class type without a user-provided default constructor must be initialized| diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c2800-through-c2899.md b/docs/error-messages/compiler-errors-2/compiler-errors-c2800-through-c2899.md index f6d3547107..6ad3bb045b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c2800-through-c2899.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c2800-through-c2899.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C2800 Through C2899" title: "Compiler errors C2800 Through C2899" -ms.date: "04/21/2019" +ms.date: 06/01/2022 f1_keywords: ["C2816", "C2820", "C2822", "C2826", "C2832", "C2836", "C2837", "C2840", "C2841", "C2848", "C2851", "C2852", "C2853", "C2866", "C2880", "C2887", "C2889", "C2895", "C2899"] helpviewer_keywords: ["C2816", "C2820", "C2822", "C2826", "C2832", "C2836", "C2837", "C2840", "C2841", "C2848", "C2851", "C2852", "C2853", "C2866", "C2880", "C2887", "C2889", "C2895", "C2899"] -ms.assetid: e5de1e92-746a-4315-a331-c5d9efb76dbb --- # Compiler errors C2800 Through C2899 @@ -14,108 +13,108 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Compiler error C2800](compiler-error-c2800.md)|'operator *operator*' cannot be overloaded| -|[Compiler error C2801](compiler-error-c2801.md)|'*member*' must be a non-static member| -|[Compiler error C2802](compiler-error-c2802.md)|static member 'operator *operator*' has no formal parameters| -|[Compiler error C2803](compiler-error-c2803.md)|'operator *operator*' must have at least one formal parameter of class type| -|[Compiler error C2804](compiler-error-c2804.md)|binary 'operator *operator*' has too many parameters| -|[Compiler error C2805](compiler-error-c2805.md)|binary 'operator *operator*' has too few parameters| -|[Compiler error C2806](compiler-error-c2806.md)|'operator *operator*' has too many formal parameters| -|[Compiler error C2807](compiler-error-c2807.md)|the second formal parameter to postfix 'operator *operator*' must be 'int'| -|[Compiler error C2808](compiler-error-c2808.md)|unary 'operator *operator*' has too many formal parameters| -|[Compiler error C2809](compiler-error-c2809.md)|'operator *operator*' has no formal parameters| -|[Compiler error C2810](compiler-error-c2810.md)|'*interface*': an interface can only inherit from another interface| -|[Compiler error C2811](compiler-error-c2811.md)|'*type1*': cannot inherit from '*type2*', a ref class can only inherit from a ref class or interface class| -|[Compiler error C2812](compiler-error-c2812.md)|#import is not supported with /clr:pure and /clr:safe| -|[Compiler error C2813](compiler-error-c2813.md)|#import is not supported with /MP| -|[Compiler error C2814](compiler-error-c2814.md)|'*member*': a native type cannot be nested within a managed/WinRT type '*class*'| -|[Compiler error C2815](compiler-error-c2815.md)|'operator delete': first formal parameter must be 'void \*', but '*type*' was used| -|Compiler error C2816|Obsolete.| -|[Compiler error C2817](compiler-error-c2817.md)|return type for 'operator delete' must be 'void'| -|[Compiler error C2818](compiler-error-c2818.md)|application of overloaded 'operator ->' is recursive through type '*class*'| -|[Compiler error C2819](compiler-error-c2819.md)|type '*class*' does not have an overloaded member 'operator ->'| -|Compiler error C2820|Obsolete.| -|[Compiler error C2821](compiler-error-c2821.md)|first formal parameter to 'operator new' must be 'size_t'| -|Compiler error C2822|local unwind is not supported on this platform| -|[Compiler error C2823](compiler-error-c2823.md)|a typedef template/generic is illegal| -|[Compiler error C2824](compiler-error-c2824.md)|return type for 'operator new' must be 'void \*'| -|[Compiler error C2825](compiler-error-c2825.md)|'*identifier*': must be a class or namespace when followed by '::'| -|Compiler error C2826|Obsolete.| -|[Compiler error C2827](compiler-error-c2827.md)|'operator *operator*' cannot be globally overridden with unary form| -|[Compiler error C2828](compiler-error-c2828.md)|'operator *operator*' cannot be globally overridden with binary form| -|[Compiler error C2829](compiler-error-c2829.md)|'operator *operator*' cannot have a variable parameter list| -|[Compiler error C2830](compiler-error-c2830.md)|only placement parameters to 'operator new' can have default values| -|[Compiler error C2831](compiler-error-c2831.md)|'operator *operator*' cannot have default parameters| -|Compiler error C2832|'*identifier*': a reference type cannot be value-initialized| -|[Compiler error C2833](compiler-error-c2833.md)|'operator *token*' is not a recognized operator or type| -|[Compiler error C2834](compiler-error-c2834.md)|'operator *operator*' must be globally qualified| -|[Compiler error C2835](compiler-error-c2835.md)|user-defined conversion '*type*' takes no formal parameters| -|Compiler error C2836|'*identifier*': only one non-static data member of a union may have a default member initializer| -|Compiler error C2837|'*function*': cannot use OpenMP directives and #pragma loop(hint_parallel) in same function| -|[Compiler error C2838](compiler-error-c2838.md)|'*identifier*': illegal qualified name in member declaration| -|[Compiler error C2839](compiler-error-c2839.md)|invalid return type '*type*' for overloaded 'operator ->'| -|Compiler error C2840|instruction word argument not constant| -|Compiler error C2841|register argument not constant| -|[Compiler error C2842](compiler-error-c2842.md)|'*class*': a managed/WinRT type may not define its own 'operator new' or 'operator delete'| -|[Compiler error C2843](compiler-error-c2843.md)|'*member*': cannot take the address of a non-static data member or method of a managed/WinRT type| -|[Compiler error C2844](compiler-error-c2844.md)|'*identifier*': cannot be a member of interface '*interface*'| -|[Compiler error C2845](compiler-error-c2845.md)|'*type*': pointer arithmetic not allowed on this type| -|[Compiler error C2846](compiler-error-c2846.md)|'*interface*': an interface cannot have a constructor| -|[Compiler error C2847](compiler-error-c2847.md)|cannot apply sizeof to managed/WinRT type '*class*'| -|Compiler error C2848|'*class*': a managed/WinRT type cannot be a member of a union| -|[Compiler error C2849](compiler-error-c2849.md)|'*interface*': an interface cannot have a destructor| -|[Compiler error C2850](compiler-error-c2850.md)|'*construct*': only allowed at file scope; may not be in a nested construct| -|Compiler error C2851|'*enum*': A public WinRT enum can only use 'int' or 'unsigned int' as a base type| -|Compiler error C2852|'*identifier*': only data members can be initialized within a class| -|Compiler error C2853|'*identifier*': a non-static data member cannot have a type that contains 'auto'| -|[Compiler error C2854](compiler-error-c2854.md)|syntax error in #pragma hdrstop| -|[Compiler error C2855](compiler-error-c2855.md)|command-line option '*option*' inconsistent with precompiled header| -|[Compiler error C2856](compiler-error-c2856.md)|#pragma hdrstop cannot be inside an #if block| -|[Compiler error C2857](compiler-error-c2857.md)|'#include' statement specified with the /Yc*filename* command-line option was not found in the source file| -|[Compiler error C2858](compiler-error-c2858.md)|command-line option '/Yc (/Fd*filename*)' inconsistent with precompiled header, which used '/Fd*filename*'| -|[Compiler error C2859](compiler-error-c2859.md)|*filename* is not the *filetype* file that was used when this precompiled header was created, recreate the precompiled header.| -|[Compiler error C2860](compiler-error-c2860.md)|'void' cannot be an argument type, except for '(void)'| -|[Compiler error C2861](compiler-error-c2861.md)|'*declaration*': an interface member function cannot be defined| -|[Compiler error C2862](compiler-error-c2862.md)|'*interface*': an interface can only have public members| -|[Compiler error C2863](compiler-error-c2863.md)|'*interface*': an interface cannot have friends| -|[Compiler error C2864](compiler-error-c2864.md)|'*identifier*': a static data member/template variable with an in-class initializer must have non-volatile const integral type| -|[Compiler error C2865](compiler-error-c2865.md)|'*operator*': illegal comparison for object pointer/handle| -|Compiler error C2866|Obsolete.| -|[Compiler error C2867](compiler-error-c2867.md)|'*identifier*': is not a namespace| -|[Compiler error C2868](compiler-error-c2868.md)|'*identifier*': illegal syntax for using-declaration; expected qualified-name| -|[Compiler error C2869](compiler-error-c2869.md)|'*identifier*': has already been defined to be a namespace| -|[Compiler error C2870](compiler-error-c2870.md)|'*identifier*': a namespace definition must appear either at file scope or immediately within another namespace definition| -|[Compiler error C2871](compiler-error-c2871.md)|'*identifier*': a namespace with this name does not exist| -|[Compiler error C2872](compiler-error-c2872.md)|'*identifier*': ambiguous symbol| -|[Compiler error C2873](compiler-error-c2873.md)|'*symbol*': symbol cannot be used in a using-declaration| -|[Compiler error C2874](compiler-error-c2874.md)|using-declaration causes a multiple declaration of '*identifier*'| -|[Compiler error C2875](compiler-error-c2875.md)|using-declaration causes a multiple declaration of '*class*::*identifier*'| -|[Compiler error C2876](compiler-error-c2876.md)|'*class*::*member*': not all overloads are accessible| -|[Compiler error C2877](compiler-error-c2877.md)|'*member*' is not accessible from '*class*'| -|[Compiler error C2878](compiler-error-c2878.md)|'*identifier*': a namespace or class of this name does not exist| -|[Compiler error C2879](compiler-error-c2879.md)|'*identifier*': only an existing namespace can be given an alternative name by a namespace alias definition| -|Compiler error C2880|__swi or __hvc requires a valid constant as first argument (SWI number)| -|[Compiler error C2881](compiler-error-c2881.md)|'*identifier*': is already used as an alias for '*class*'| -|[Compiler error C2882](compiler-error-c2882.md)|'*identifier*': illegal use of namespace identifier in expression| -|[Compiler error C2883](compiler-error-c2883.md)|'*function*': function declaration conflicts with '*identifier*' introduced by using-declaration| -|[Compiler error C2884](compiler-error-c2884.md)|'*identifier*': introduced by using-declaration conflicts with local function '*function*'| -|[Compiler error C2885](compiler-error-c2885.md)|'*class*::*identifier*': not a valid using-declaration at non-class scope| -|[Compiler error C2886](compiler-error-c2886.md)|'*class*::*identifier*': symbol cannot be used in a member using-declaration| -|Compiler error C2887|__swi or __hvc cannot have more than five arguments (SWI number, r0 - r3)| -|[Compiler error C2888](compiler-error-c2888.md)|'*identifier*': symbol cannot be defined within namespace '*namespace*'| -|Compiler error C2889|'*class*': a managed/WinRT class type cannot be a virtual base class| -|[Compiler error C2890](compiler-error-c2890.md)|'*class*': a ref class can only have one non-interface base class| -|[Compiler error C2891](compiler-error-c2891.md)|'*parameter*': cannot take the address of a template parameter| -|[Compiler error C2892](compiler-error-c2892.md)|local class shall not have member templates| -|[Compiler error C2893](compiler-error-c2893.md)|Failed to specialize function template '*template*'| -|[Compiler error C2894](compiler-error-c2894.md)|templates cannot be declared to have 'C' linkage| -|Compiler error C2895|'*declaration*': cannot explicitly instantiate a function template that has been declared with dllimport| -|[Compiler error C2896](compiler-error-c2896.md)|'*function1*': cannot use function template/generic '*function2*' as a function argument| -|[Compiler error C2897](compiler-error-c2897.md)|a destructor/finalizer cannot be a function template| -|[Compiler error C2898](compiler-error-c2898.md)|'*declaration*': member function templates cannot be virtual| -|Compiler error C2899|Obsolete.| +| Error | Message | +|--|--| +| [Compiler error C2800](compiler-error-c2800.md) | 'operator *operator*' cannot be overloaded | +| [Compiler error C2801](compiler-error-c2801.md) | '*member*' must be a non-static member | +| [Compiler error C2802](compiler-error-c2802.md) | static member 'operator *operator*' has no formal parameters | +| [Compiler error C2803](compiler-error-c2803.md) | 'operator *operator*' must have at least one formal parameter of class type | +| [Compiler error C2804](compiler-error-c2804.md) | binary 'operator *operator*' has too many parameters | +| [Compiler error C2805](compiler-error-c2805.md) | binary 'operator *operator*' has too few parameters | +| [Compiler error C2806](compiler-error-c2806.md) | 'operator *operator*' has too many formal parameters | +| [Compiler error C2807](compiler-error-c2807.md) | the second formal parameter to postfix 'operator *operator*' must be 'int' | +| [Compiler error C2808](compiler-error-c2808.md) | unary 'operator *operator*' has too many formal parameters | +| [Compiler error C2809](compiler-error-c2809.md) | 'operator *operator*' has no formal parameters | +| [Compiler error C2810](compiler-error-c2810.md) | '*interface*': an interface can only inherit from another interface | +| [Compiler error C2811](compiler-error-c2811.md) | '*type1*': cannot inherit from '*type2*', a ref class can only inherit from a ref class or interface class | +| [Compiler error C2812](compiler-error-c2812.md) | #import is not supported with /clr:pure and /clr:safe | +| [Compiler error C2813](compiler-error-c2813.md) | #import is not supported with /MP | +| [Compiler error C2814](compiler-error-c2814.md) | '*member*': a native type cannot be nested within a managed/WinRT type '*class*' | +| [Compiler error C2815](compiler-error-c2815.md) | 'operator delete': first formal parameter must be 'void \*', but '*type*' was used | +| Compiler error C2816 | invocation of function-like macro '*identifier*' is missing terminating ')' | +| [Compiler error C2817](compiler-error-c2817.md) | return type for 'operator delete' must be 'void' | +| [Compiler error C2818](compiler-error-c2818.md) | application of overloaded 'operator ->' is recursive through type '*class*' | +| [Compiler error C2819](compiler-error-c2819.md) | type '*class*' does not have an overloaded member 'operator ->' | +| Compiler error C2820 | Obsolete. | +| [Compiler error C2821](compiler-error-c2821.md) | first formal parameter to 'operator new' must be 'size_t' | +| Compiler error C2822 | local unwind is not supported on this platform | +| [Compiler error C2823](compiler-error-c2823.md) | a typedef template/generic is illegal | +| [Compiler error C2824](compiler-error-c2824.md) | return type for 'operator new' must be 'void \*' | +| [Compiler error C2825](compiler-error-c2825.md) | '*identifier*': must be a class or namespace when followed by '::' | +| Compiler error C2826 | Obsolete. | +| [Compiler error C2827](compiler-error-c2827.md) | 'operator *operator*' cannot be globally overridden with unary form | +| [Compiler error C2828](compiler-error-c2828.md) | 'operator *operator*' cannot be globally overridden with binary form | +| [Compiler error C2829](compiler-error-c2829.md) | 'operator *operator*' cannot have a variable parameter list | +| [Compiler error C2830](compiler-error-c2830.md) | only placement parameters to 'operator new' can have default values | +| [Compiler error C2831](compiler-error-c2831.md) | 'operator *operator*' cannot have default parameters | +| Compiler error C2832 | '*identifier*': a reference type cannot be value-initialized | +| [Compiler error C2833](compiler-error-c2833.md) | 'operator *token*' is not a recognized operator or type | +| [Compiler error C2834](compiler-error-c2834.md) | 'operator *operator*' must be globally qualified (Obsolete in Visual Studio 2022.) | +| [Compiler error C2835](compiler-error-c2835.md) | user-defined conversion '*type*' takes no formal parameters | +| Compiler error C2836 | '*identifier*': only one non-static data member of a union may have a default member initializer | +| Compiler error C2837 | '*function*': cannot use OpenMP directives and #pragma loop(hint_parallel) in same function | +| [Compiler error C2838](compiler-error-c2838.md) | '*identifier*': illegal qualified name in member declaration | +| [Compiler error C2839](compiler-error-c2839.md) | invalid return type '*type*' for overloaded 'operator ->' | +| Compiler error C2840 | instruction word argument not constant | +| Compiler error C2841 | register argument not constant | +| [Compiler error C2842](compiler-error-c2842.md) | '*class*': a managed/WinRT type may not define its own 'operator new' or 'operator delete' | +| [Compiler error C2843](compiler-error-c2843.md) | '*member*': cannot take the address of a non-static data member or method of a managed/WinRT type | +| [Compiler error C2844](compiler-error-c2844.md) | '*identifier*': cannot be a member of interface '*interface*' | +| [Compiler error C2845](compiler-error-c2845.md) | '*type*': pointer arithmetic not allowed on this type | +| [Compiler error C2846](compiler-error-c2846.md) | '*interface*': an interface cannot have a constructor | +| [Compiler error C2847](compiler-error-c2847.md) | cannot apply sizeof to managed/WinRT type '*class*' | +| Compiler error C2848 | '*class*': a managed/WinRT type cannot be a member of a union | +| [Compiler error C2849](compiler-error-c2849.md) | '*interface*': an interface cannot have a destructor | +| [Compiler error C2850](compiler-error-c2850.md) | '*construct*': only allowed at file scope; may not be in a nested construct | +| Compiler error C2851 | '*enum*': A public WinRT enum can only use 'int' or 'unsigned int' as a base type | +| Compiler error C2852 | '*identifier*': only data members can be initialized within a class | +| Compiler error C2853 | '*identifier*': a non-static data member cannot have a type that contains 'auto' | +| [Compiler error C2854](compiler-error-c2854.md) | syntax error in #pragma hdrstop | +| [Compiler error C2855](compiler-error-c2855.md) | command-line option '*option*' inconsistent with precompiled header | +| [Compiler error C2856](compiler-error-c2856.md) | #pragma hdrstop cannot be inside an #if block | +| [Compiler error C2857](compiler-error-c2857.md) | '#include' statement specified with the /Yc*filename* command-line option was not found in the source file | +| [Compiler error C2858](compiler-error-c2858.md) | command-line option '/Yc (/Fd*filename*)' inconsistent with precompiled header, which used '/Fd*filename*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2859](compiler-error-c2859.md) | *filename* is not the *filetype* file that was used when this precompiled header was created, recreate the precompiled header. | +| [Compiler error C2860](compiler-error-c2860.md) | 'void' cannot be used as a function parameter except for '(void)' | +| [Compiler error C2861](compiler-error-c2861.md) | '*declaration*': an interface member function cannot be defined | +| [Compiler error C2862](compiler-error-c2862.md) | '*interface*': an interface can only have public members | +| [Compiler error C2863](compiler-error-c2863.md) | '*interface*': an interface cannot have friends | +| [Compiler error C2864](compiler-error-c2864.md) | '*identifier*': a static data member/template variable with an in-class initializer must have non-volatile const integral type | +| [Compiler error C2865](compiler-error-c2865.md) | '*operator*': illegal comparison for object pointer/handle | +| Compiler error C2866 | Obsolete. | +| [Compiler error C2867](compiler-error-c2867.md) | '*identifier*': is not a namespace | +| [Compiler error C2868](compiler-error-c2868.md) | '*identifier*': illegal syntax for using-declaration; expected qualified-name | +| [Compiler error C2869](compiler-error-c2869.md) | '*identifier*': has already been defined to be a namespace | +| [Compiler error C2870](compiler-error-c2870.md) | '*identifier*': a namespace definition must appear either at file scope or immediately within another namespace definition | +| [Compiler error C2871](compiler-error-c2871.md) | '*identifier*': a namespace with this name does not exist | +| [Compiler error C2872](compiler-error-c2872.md) | '*identifier*': ambiguous symbol | +| [Compiler error C2873](compiler-error-c2873.md) | '*symbol*': symbol cannot be used in a using-declaration | +| [Compiler error C2874](compiler-error-c2874.md) | using-declaration causes a multiple declaration of '*identifier*' | +| [Compiler error C2875](compiler-error-c2875.md) | using-declaration causes a multiple declaration of '*class*::*identifier*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2876](compiler-error-c2876.md) | '*class*::*member*': not all overloads are accessible | +| [Compiler error C2877](compiler-error-c2877.md) | '*member*' is not accessible from '*class*' | +| [Compiler error C2878](compiler-error-c2878.md) | '*identifier*': a namespace or class of this name does not exist | +| [Compiler error C2879](compiler-error-c2879.md) | '*identifier*': only an existing namespace can be given an alternative name by a namespace alias definition | +| Compiler error C2880 | __swi or __hvc requires a valid constant as first argument (SWI number) | +| [Compiler error C2881](compiler-error-c2881.md) | '*identifier*': is already used as an alias for '*class*' | +| [Compiler error C2882](compiler-error-c2882.md) | '*identifier*': illegal use of namespace identifier in expression | +| [Compiler error C2883](compiler-error-c2883.md) | '*function*': function declaration conflicts with '*identifier*' introduced by using-declaration | +| [Compiler error C2884](compiler-error-c2884.md) | '*identifier*': introduced by using-declaration conflicts with local function '*function*' | +| [Compiler error C2885](compiler-error-c2885.md) | '*class*::*identifier*': not a valid using-declaration at non-class scope | +| [Compiler error C2886](compiler-error-c2886.md) | '*class*::*identifier*': symbol cannot be used in a member using-declaration | +| Compiler error C2887 | __swi or __hvc cannot have more than five arguments (SWI number, r0 - r3) | +| [Compiler error C2888](compiler-error-c2888.md) | '*identifier*': symbol cannot be defined within namespace '*namespace*' | +| Compiler error C2889 | '*class*': a managed/WinRT class type cannot be a virtual base class | +| [Compiler error C2890](compiler-error-c2890.md) | '*class*': a ref class can only have one non-interface base class | +| [Compiler error C2891](compiler-error-c2891.md) | '*parameter*': cannot take the address of a template parameter | +| [Compiler error C2892](compiler-error-c2892.md) | a template cannot be a member of a local class | +| [Compiler error C2893](compiler-error-c2893.md) | Failed to specialize function template '*template*' | +| [Compiler error C2894](compiler-error-c2894.md) | templates cannot be declared to have 'C' linkage | +| Compiler error C2895 | '*declaration*': cannot explicitly instantiate a function template that has been declared with dllimport | +| [Compiler error C2896](compiler-error-c2896.md) | '*function1*': cannot use function template/generic '*function2*' as a function argument (Obsolete in Visual Studio 2022.) | +| [Compiler error C2897](compiler-error-c2897.md) | a destructor/finalizer cannot be a function template | +| [Compiler error C2898](compiler-error-c2898.md) | '*declaration*': member function templates cannot be virtual | +| Compiler error C2899 | Obsolete. | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c2900-through-c3499.md b/docs/error-messages/compiler-errors-2/compiler-errors-c2900-through-c3499.md index 1ed61d9d78..2b2fb65959 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c2900-through-c3499.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c2900-through-c3499.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C2900 Through C2999" title: "Compiler errors C2900 Through C2999" -ms.date: "04/21/2019" -f1_keywords: ["C2900", "C2901", "C2905", "C2907", "C2915", "C2916", "C2922", "C2924", "C2925", "C2926", "C2938", "C2949", "C2950", "C2954", "C2956", "C2960", "C2961", "C2963", "C2964", "C2965", "C2966", "C2967", "C2968", "C2972", "C2980", "C2981", "C2982", "C2983", "C2984", "C2985", "C2986", "C2987", "C2997", "C2999"] -helpviewer_keywords: ["C2900", "C2901", "C2905", "C2907", "C2915", "C2916", "C2922", "C2924", "C2925", "C2926", "C2938", "C2949", "C2950", "C2954", "C2956", "C2960", "C2961", "C2963", "C2964", "C2965", "C2966", "C2967", "C2968", "C2972", "C2980", "C2981", "C2982", "C2983", "C2984", "C2985", "C2986", "C2987", "C2997", "C2999"] -ms.assetid: e3440738-e11b-4878-9ae3-6bc6c53ba461 +ms.date: 06/01/2022 +f1_keywords: ["C2900", "C2901", "C2905", "C2907", "C2915", "C2916", "C2922", "C2924", "C2925", "C2926", "C2938", "C2949", "C2950", "C2954", "C2960", "C2961", "C2963", "C2964", "C2965", "C2966", "C2967", "C2968", "C2972", "C2980", "C2981", "C2982", "C2983", "C2984", "C2985", "C2986", "C2987", "C2997"] +helpviewer_keywords: ["C2900", "C2901", "C2905", "C2907", "C2915", "C2916", "C2922", "C2924", "C2925", "C2926", "C2938", "C2949", "C2950", "C2954", "C2960", "C2961", "C2963", "C2964", "C2965", "C2966", "C2967", "C2968", "C2972", "C2980", "C2981", "C2982", "C2983", "C2984", "C2985", "C2986", "C2987", "C2997"] --- # Compiler errors C2900 Through C2999 @@ -14,108 +13,107 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|Compiler error C2900|'*declarator*': member function templates in WinRT classes must be 'private', 'internal' or 'protected private'| -|Compiler error C2901|'*identifier*': A generic interface or delegate cannot be public| -|[Compiler error C2902](compiler-error-c2902.md)|'*token*': unexpected token following 'template/generic', identifier expected| -|[Compiler error C2903](compiler-error-c2903.md)|'*identifier*': symbol is neither a class template/generic nor a function template/generic| -|[Compiler error C2904](compiler-error-c2904.md)|'*identifier*': name already used for a template in the current scope| -|Compiler error C2905|Obsolete.| -|[Compiler error C2906](compiler-error-c2906.md)|'*template*': explicit specialization requires 'template <>'| -|Compiler error C2907|register argument '*number*' does not specify a valid register number| -|[Compiler error C2908](compiler-error-c2908.md)|explicit specialization; '*template*' has already been instantiated| -|[Compiler error C2909](compiler-error-c2909.md)|'*identifier*': explicit instantiation of function template requires return type| -|[Compiler error C2910](compiler-error-c2910.md)|'*function*': cannot be explicitly specialized| -|[Compiler error C2911](compiler-error-c2911.md)|'*member*': cannot be declared or defined in the current scope| -|[Compiler error C2912](compiler-error-c2912.md)|explicit specialization '*declaration*' is not a specialization of a function template| -|[Compiler error C2913](compiler-error-c2913.md)|explicit specialization; '*declaration*' is not a specialization of a class template| -|[Compiler error C2914](compiler-error-c2914.md)|'*identifier*': cannot deduce template/generic argument as function argument is ambiguous| -|Compiler error C2915|'*identifier*': '*type*' cannot be directly used on the published surface of a WinRT type. Use 'Platform::Object^' instead to pass this type| -|Compiler error C2916|'*identifier*': [FlagsAttribute] must (only) be specified on a public enum with an 'unsigned int' underlying type| -|[Compiler error C2917](compiler-error-c2917.md)|'*identifier*': invalid template-parameter| -|[Compiler error C2918](compiler-error-c2918.md)|'*identifier*': Indexed properties cannot be used on the published surface of a WinRT type| -|[Compiler error C2919](compiler-error-c2919.md)|'*type*': Operators cannot be used on the published surface of a WinRT type| -|[Compiler error C2920](compiler-error-c2920.md)|redefinition: '*type*': class template/generic has already been declared as '*declaration*'| -|[Compiler error C2921](compiler-error-c2921.md)|redefinition: '*type*': class template/generic is being redeclared as '*declaration*'| -|Compiler error C2922|'*interface*': A WinRT interface cannot contain static members| -|[Compiler error C2923](compiler-error-c2923.md)|'*type*': '*identifier*' is not a valid template/generic type argument for parameter '*parameter*'| -|Compiler error C2924|__declspec(interrupt) routine argument not in R2| -|Compiler error C2925|__declspec(interrupt) routine cannot use floating-point| -|Compiler error C2926|'*identifier*': a default member initializer is not allowed for a member of an anonymous struct within a union| -|[Compiler error C2927](compiler-error-c2927.md)|'*identifier*': a function template must be called with at least one argument| -|[Compiler error C2928](compiler-error-c2928.md)|explicit instantiation; '*identifier*' is not a function or static data member of template-class '*class*'| -|[Compiler error C2929](compiler-error-c2929.md)|'*declarator*': explicit instantiation; cannot explicitly force and suppress instantiation of template-class member| -|[Compiler error C2930](compiler-error-c2930.md)|'*class*': template-id/generic-id redefined as an enumerator of 'enum *identifier*'| -|[Compiler error C2931](compiler-error-c2931.md)|'*class1*': template-id/generic-id redefined as a member function of '*class2*'| -|[Compiler error C2932](compiler-error-c2932.md)|'*type*': template-id/generic-id redefined as a data member of '*identifier*'| -|[Compiler error C2933](compiler-error-c2933.md)|'*type*': template-id/generic-id redefined as a typedef member of '*identifier*'| -|[Compiler error C2934](compiler-error-c2934.md)|'*type*': template-id/generic-id redefined as a nested '*item*' of '*identifier*'| -|[Compiler error C2935](compiler-error-c2935.md)|'*type*': template-id/generic-id redefined as a global function| -|[Compiler error C2936](compiler-error-c2936.md)|'*type*': template-id/generic-id redefined as a global data variable| -|[Compiler error C2937](compiler-error-c2937.md)|'*type*': template-id/generic-id redefined as a global typedef| -|Compiler error C2938|'*identifier*' : Failed to specialize alias template| -|[Compiler error C2939](compiler-error-c2939.md)|'*type*': template-id/generic-id redefined as a local data variable| -|[Compiler error C2940](compiler-error-c2940.md)|'*type*': template-id/generic-id redefined as a local typedef| -|[Compiler error C2941](compiler-error-c2941.md)|'*type*': template-id/generic-id redefined as a local '*item*'| -|[Compiler error C2942](compiler-error-c2942.md)|'*type*': template-id/generic-id redefined as a formal argument of a function| -|[Compiler error C2943](compiler-error-c2943.md)|'*type*': template-id/generic-id redefined as a type argument of a template| -|[Compiler error C2944](compiler-error-c2944.md)|'*type*': template-id/generic-id redefined as a value argument of a template| -|[Compiler error C2945](compiler-error-c2945.md)|explicit instantiation does not refer to a template-class specialization| -|[Compiler error C2946](compiler-error-c2946.md)|explicit instantiation; '*type*' is not a template-class specialization| -|[Compiler error C2947](compiler-error-c2947.md)|expecting '>' to terminate template arguments, found '*token*'| -|[Compiler error C2948](compiler-error-c2948.md)|explicit instantiation; storage class specifier '*specifier*' not permitted on specialization| -|Compiler error C2949|thread_local is not supported with /kernel| -|Compiler error C2950|Obsolete.| -|[Compiler error C2951](compiler-error-c2951.md)|template/generic declarations are only permitted at global, namespace, or class scope| -|[Compiler error C2952](compiler-error-c2952.md)|'*declaration*': template/generic declaration missing template/generic parameter list| -|[Compiler error C2953](compiler-error-c2953.md)|'*type*': class template has already been defined| -|Compiler error C2954|instruction word argument not in range| -|[Compiler error C2955](compiler-error-c2955.md)|'*type*': use of class template/generic requires template/generic argument list| -|Compiler error C2956|sized deallocation function 'operator delete(void*, size_t)' would be chosen as placement deallocation function.| -|[Compiler error C2957](compiler-error-c2957.md)|'*token*': invalid left delimiter: expected '<'| -|[Compiler error C2958](compiler-error-c2958.md)|the left *delimiter* found at '*file*(*line_number*)' was not matched correctly| -|[Compiler error C2959](compiler-error-c2959.md)|a generic class or function may not be a member of a template| -|Compiler error C2960|Obsolete.| -|Compiler error C2961|'*function*': inconsistent explicit instantiations, a previous explicit instantiation did not specify '*argument*'| -|[Compiler error C2962](compiler-error-c2962.md)|syntax error: '*token*': expected template-class member function definition to end with '}'| -|Compiler error C2963|Obsolete.| -|Compiler error C2964|Obsolete.| -|Compiler error C2965|__declspec(*specifier*) is not supported with /kernel| -|Compiler error C2966|'*identifier1*': must have the same __declspec(code_seg(...)) as its base class '*identifier2*'| -|Compiler error C2967|'*identifier*': an overriding virtual function must have the same __declspec(code_seg(...)) as an overridden virtual function| -|Compiler error C2968|'*identifier*': recursive alias declaration| -|[Compiler error C2969](compiler-error-c2969.md)|syntax error: '*token*': expected member function definition to end with '}'| -|[Compiler error C2970](compiler-error-c2970.md)|'*type*': template parameter '*parameter*': '*argument*': an expression involving objects with internal linkage cannot be used as a non-type argument| -|[Compiler error C2971](compiler-error-c2971.md)|'*type*': template parameter '*parameter*': '*argument*': a variable with non-static storage duration cannot be used as a non-type argument| -|Compiler error C2972|'*type*': template parameter '*parameter*': the type of non-type argument is invalid| -|[Compiler error C2973](compiler-error-c2973.md)|'*template*': invalid template argument '*number*'| -|[Compiler error C2974](compiler-error-c2974.md)|'*type*': invalid template/generic argument for '*parameter*', type expected| -|[Compiler error C2975](compiler-error-c2975.md)|'*type*': invalid template argument for '*parameter*', expected compile-time constant expression| -|[Compiler error C2976](compiler-error-c2976.md)|'*type*': too few template/generic arguments| -|[Compiler error C2977](compiler-error-c2977.md)|'*type*': too many template/generic arguments| -|[Compiler error C2978](compiler-error-c2978.md)|syntax error: expected '*keyword1*' or '*keyword2*'; found type '*type*'; non-type parameters are not supported in generics| -|[Compiler error C2979](compiler-error-c2979.md)|explicit specializations are not supported in generics| -|Compiler error C2980|C++ exception handling is not supported with /kernel| -|Compiler error C2981|the dynamic form of '*keyword*' is not supported with /kernel| -|Compiler error C2982|'*declaration*': different __declspec(code_seg(...)) used: was '*identifier1*' now '*identifier2*'| -|Compiler error C2983|'*declaration*': all declarations must have an identical __declspec(code_seg(...))| -|Compiler error C2984|Obsolete.| -|Compiler error C2985|'*argument*': the argument to __declspec(code_seg(...)) must be a text section| -|Compiler error C2986|'*identifier*': __declspec(code_seg(...)) can only be applied to a class or a function| -|Compiler error C2987|a declaration cannot have both __declspec(code_seg('*identifier*')) and __declspec(code_seg('*value*'))| -|[Compiler error C2988](compiler-error-c2988.md)|unrecognizable template declaration/definition| -|[Compiler error C2989](compiler-error-c2989.md)|'*class*': class template/generic has already been declared as a non-class template/generic| -|[Compiler error C2990](compiler-error-c2990.md)|'*class*': non-class template/generic has already been declared as a class template/generic| -|[Compiler error C2991](compiler-error-c2991.md)|redefinition of template/generic parameter '*parameter*'| -|[Compiler error C2992](compiler-error-c2992.md)|'*class*': invalid or missing template/generic parameter list| -|[Compiler error C2993](compiler-error-c2993.md)|'*type*': illegal type for non-type template parameter '*identifier*'| -|[Compiler error C2994](compiler-error-c2994.md)|unnamed class in template parameter list| -|[Compiler error C2995](compiler-error-c2995.md)|'*declaration*': function template has already been defined| -|[Compiler error C2996](compiler-error-c2996.md)|'*function*': recursive function template definition| -|Compiler error C2997|'*function*': array bound cannot be deduced from a default member initializer| -|[Compiler error C2998](compiler-error-c2998.md)|'*declarator*': cannot be a template definition| -|Compiler error C2999|UNKNOWN ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| +| Error | Message | +|--|--| +| Compiler error C2900 | '*declarator*': member function templates in WinRT classes must be 'private', 'internal' or 'protected private' | +| Compiler error C2901 | '*identifier*': A generic interface or delegate cannot be public | +| [Compiler error C2902](compiler-error-c2902.md) | '*token*': unexpected token following 'template/generic', identifier expected (Obsolete in Visual Studio 2022.) | +| [Compiler error C2903](compiler-error-c2903.md) | '*identifier*': symbol is neither a class template/generic nor a function template/generic | +| [Compiler error C2904](compiler-error-c2904.md) | '*identifier*': name already used for a template in the current scope | +| Compiler error C2905 | Obsolete. | +| [Compiler error C2906](compiler-error-c2906.md) | '*template*': explicit specialization requires 'template <>' | +| Compiler error C2907 | register argument '*number*' does not specify a valid register number | +| [Compiler error C2908](compiler-error-c2908.md) | explicit specialization; '*template*' has already been instantiated | +| [Compiler error C2909](compiler-error-c2909.md) | '*identifier*': explicit instantiation of function template requires return type | +| [Compiler error C2910](compiler-error-c2910.md) | '*function*': cannot be explicitly specialized | +| [Compiler error C2911](compiler-error-c2911.md) | '*member*': cannot be declared or defined in the current scope | +| [Compiler error C2912](compiler-error-c2912.md) | explicit specialization '*declaration*' is not a specialization of a function template | +| [Compiler error C2913](compiler-error-c2913.md) | explicit specialization; '*declaration*' is not a specialization of a class template | +| [Compiler error C2914](compiler-error-c2914.md) | '*identifier*': cannot deduce template/generic argument as function argument is ambiguous | +| Compiler error C2915 | '*identifier*': '*type*' cannot be directly used on the published surface of a WinRT type. Use 'Platform::Object^' instead to pass this type | +| Compiler error C2916 | '*identifier*': [FlagsAttribute] must (only) be specified on a public enum with an 'unsigned int' underlying type | +| [Compiler error C2917](compiler-error-c2917.md) | '*identifier*': invalid template-parameter (Obsolete in Visual Studio 2022.) | +| [Compiler error C2918](compiler-error-c2918.md) | '*identifier*': Indexed properties cannot be used on the published surface of a WinRT type | +| [Compiler error C2919](compiler-error-c2919.md) | '*type*': Operators cannot be used on the published surface of a WinRT type | +| [Compiler error C2920](compiler-error-c2920.md) | redefinition: '*type*': class template/generic has already been declared as '*declaration*' | +| [Compiler error C2921](compiler-error-c2921.md) | redefinition: '*type*': class template/generic is being redeclared as '*declaration*' | +| Compiler error C2922 | '*interface*': A WinRT interface cannot contain static members | +| [Compiler error C2923](compiler-error-c2923.md) | '*type*': '*identifier*' is not a valid template/generic type argument for parameter '*parameter*' | +| Compiler error C2924 | __declspec(interrupt) routine argument not in R2 | +| Compiler error C2925 | __declspec(interrupt) routine cannot use floating-point | +| Compiler error C2926 | '*identifier*': a default member initializer is not allowed for a member of an anonymous struct within a union | +| [Compiler error C2927](compiler-error-c2927.md) | '*identifier*': a function template must be called with at least one argument | +| [Compiler error C2928](compiler-error-c2928.md) | explicit instantiation; '*identifier*' is not a function or static data member of template-class '*class*' | +| [Compiler error C2929](compiler-error-c2929.md) | '*declarator*': explicit instantiation; cannot explicitly force and suppress instantiation of template-class member | +| [Compiler error C2930](compiler-error-c2930.md) | '*class*': template-id/generic-id redefined as an enumerator of 'enum *identifier*' | +| [Compiler error C2931](compiler-error-c2931.md) | '*class1*': template-id/generic-id redefined as a member function of '*class2*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2932](compiler-error-c2932.md) | '*type*': template-id/generic-id redefined as a data member of '*identifier*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2933](compiler-error-c2933.md) | '*type*': template-id/generic-id redefined as a typedef member of '*identifier*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2934](compiler-error-c2934.md) | '*type*': template-id/generic-id redefined as a nested '*item*' of '*identifier*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2935](compiler-error-c2935.md) | '*type*': template-id/generic-id redefined as a global function (Obsolete in Visual Studio 2022.) | +| [Compiler error C2936](compiler-error-c2936.md) | '*type*': template-id/generic-id redefined as a global data variable (Obsolete in Visual Studio 2022.) | +| [Compiler error C2937](compiler-error-c2937.md) | '*type*': template-id/generic-id redefined as a global typedef (Obsolete in Visual Studio 2022.) | +| Compiler error C2938 | '*identifier*' : Failed to specialize alias template | +| [Compiler error C2939](compiler-error-c2939.md) | '*type*': template-id/generic-id redefined as a local data variable (Obsolete in Visual Studio 2022.) | +| [Compiler error C2940](compiler-error-c2940.md) | '*type*': template-id/generic-id redefined as a local typedef (Obsolete in Visual Studio 2022.) | +| [Compiler error C2941](compiler-error-c2941.md) | '*type*': template-id/generic-id redefined as a local '*item*' (Obsolete in Visual Studio 2022.) | +| [Compiler error C2942](compiler-error-c2942.md) | '*type*': template-id/generic-id redefined as a formal argument of a function (Obsolete in Visual Studio 2022.) | +| [Compiler error C2943](compiler-error-c2943.md) | '*type*': template-id/generic-id redefined as a type argument of a template (Obsolete in Visual Studio 2022.) | +| [Compiler error C2944](compiler-error-c2944.md) | '*type*': template-id/generic-id redefined as a value argument of a template (Obsolete in Visual Studio 2022.) | +| [Compiler error C2945](compiler-error-c2945.md) | explicit instantiation does not refer to a template-class specialization | +| [Compiler error C2946](compiler-error-c2946.md) | explicit instantiation; '*type*' is not a template-class specialization | +| [Compiler error C2947](compiler-error-c2947.md) | expecting '>' to terminate template arguments, found '*token*' | +| [Compiler error C2948](compiler-error-c2948.md) | explicit instantiation; storage class specifier '*specifier*' not permitted on specialization | +| Compiler error C2949 | thread_local is not supported with /kernel | +| Compiler error C2950 | Obsolete. | +| [Compiler error C2951](compiler-error-c2951.md) | template/generic declarations are only permitted at global, namespace, or class scope | +| [Compiler error C2952](compiler-error-c2952.md) | '*declaration*': template/generic declaration missing template/generic parameter list | +| [Compiler error C2953](compiler-error-c2953.md) | '*type*': class template has already been defined | +| Compiler error C2954 | instruction word argument not in range | +| [Compiler error C2955](compiler-error-c2955.md) | '*type*': use of class template/generic requires template/generic argument list | +| [Compiler error C2956](compiler-error-c2956.md) | usual deallocation function '*function*' would be chosen as placement deallocation function | +| [Compiler error C2957](compiler-error-c2957.md) | '*token*': invalid left delimiter: expected '<' | +| [Compiler error C2958](compiler-error-c2958.md) | the left *delimiter* found at '*file*(*line_number*)' was not matched correctly | +| [Compiler error C2959](compiler-error-c2959.md) | a generic class or function may not be a member of a template | +| Compiler error C2960 | Obsolete. | +| Compiler error C2961 | '*function*': inconsistent explicit instantiations, a previous explicit instantiation did not specify '*argument*' | +| [Compiler error C2962](compiler-error-c2962.md) | syntax error: '*token*': expected template-class member function definition to end with '}' | +| Compiler error C2963 | Obsolete. | +| Compiler error C2964 | Obsolete. | +| Compiler error C2965 | __declspec(*specifier*) is not supported with /kernel | +| Compiler error C2966 | '*identifier1*': must have the same __declspec(code_seg(...)) as its base class '*identifier2*' (Obsolete in Visual Studio 2022.) | +| Compiler error C2967 | '*identifier*': an overriding virtual function must have the same __declspec(code_seg(...)) as an overridden virtual function (Obsolete in Visual Studio 2022.) | +| Compiler error C2968 | '*identifier*': recursive alias declaration | +| [Compiler error C2969](compiler-error-c2969.md) | syntax error: '*token*': expected member function definition to end with '}' | +| [Compiler error C2970](compiler-error-c2970.md) | '*type*': template parameter '*parameter*': '*argument*': an expression involving objects with internal linkage cannot be used as a non-type argument | +| [Compiler error C2971](compiler-error-c2971.md) | '*type*': template parameter '*parameter*': '*argument*': a variable with non-static storage duration cannot be used as a non-type argument | +| Compiler error C2972 | '*type*': template parameter '*parameter*': the type of non-type argument is invalid | +| [Compiler error C2973](compiler-error-c2973.md) | '*template*': invalid template argument '*number*' | +| [Compiler error C2974](compiler-error-c2974.md) | '*type*': invalid template/generic argument for '*parameter*', type expected | +| [Compiler error C2975](compiler-error-c2975.md) | '*type*': invalid template argument for '*parameter*', expected compile-time constant expression | +| [Compiler error C2976](compiler-error-c2976.md) | '*type*': too few template/generic arguments | +| [Compiler error C2977](compiler-error-c2977.md) | '*type*': too many template/generic arguments | +| [Compiler error C2978](compiler-error-c2978.md) | syntax error: expected '*keyword1*' or '*keyword2*'; found type '*type*'; non-type parameters are not supported in generics | +| [Compiler error C2979](compiler-error-c2979.md) | explicit specializations are not supported in generics | +| Compiler error C2980 | C++ exception handling is not supported with /kernel | +| Compiler error C2981 | the dynamic form of '*keyword*' is not supported with /kernel | +| Compiler error C2982 | '*declaration*': different __declspec(code_seg(...)) used: was '*identifier1*' now '*identifier2*' | +| Compiler error C2983 | '*name*': a definition must have the same `__declspec(code_seg(...))` as the prior declaration | +| Compiler error C2984 | Obsolete. | +| Compiler error C2985 | '*argument*': the argument to __declspec(code_seg(...)) must be a text section | +| Compiler error C2986 | '`__declspec(code_seg(...))`' can only be applied to a class or a function | +| Compiler error C2987 | a declaration cannot have both __declspec(code_seg('*identifier*')) and __declspec(code_seg('*value*')) | +| [Compiler error C2988](compiler-error-c2988.md) | unrecognizable template declaration/definition | +| [Compiler error C2989](compiler-error-c2989.md) | '*class*': class template/generic has already been declared as a non-class template/generic | +| [Compiler error C2990](compiler-error-c2990.md) | '*class*': non-class template/generic has already been declared as a class template/generic | +| [Compiler error C2991](compiler-error-c2991.md) | redefinition of template/generic parameter '*parameter*' | +| [Compiler error C2992](compiler-error-c2992.md) | '*class*': invalid or missing template/generic parameter list | +| [Compiler error C2993](compiler-error-c2993.md) | '*type*': illegal type for non-type template parameter '*identifier*' | +| [Compiler error C2994](compiler-error-c2994.md) | unnamed class in template parameter list | +| [Compiler error C2995](compiler-error-c2995.md) | '*declaration*': function template has already been defined | +| [Compiler error C2996](compiler-error-c2996.md) | '*function*': recursive function template definition | +| Compiler error C2997 | '*function*': array bound cannot be deduced from a default member initializer | +| [Compiler error C2998](compiler-error-c2998.md) | '*declarator*': cannot be a template definition | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md index 92bd2b8db7..bcdc2b953e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C3000 Through C3099" title: "Compiler errors C3000 Through C3099" -ms.date: "04/21/2019" -f1_keywords: ["C3051", "C3061", "C3064", "C3067", "C3074", "C3078", "C3079", "C3081", "C3082", "C3086", "C3088", "C3089", "C3090", "C3091", "C3092", "C3093", "C3098"] -helpviewer_keywords: ["C3051", "C3061", "C3064", "C3067", "C3074", "C3078", "C3079", "C3081", "C3082", "C3086", "C3088", "C3089", "C3090", "C3091", "C3092", "C3093", "C3098"] -ms.assetid: 01b7b9cb-b351-4b5a-8cb0-1fcddb08d2ab +ms.date: 06/01/2022 +f1_keywords: ["C3000", "C3051", "C3061", "C3064", "C3067", "C3074", "C3078", "C3079", "C3081", "C3082", "C3086", "C3088", "C3089", "C3090", "C3091", "C3092", "C3093", "C3098"] +helpviewer_keywords: ["C3000", "C3051", "C3061", "C3064", "C3067", "C3074", "C3078", "C3079", "C3081", "C3082", "C3086", "C3088", "C3089", "C3090", "C3091", "C3092", "C3093", "C3098"] --- # Compiler errors C3000 Through C3099 @@ -14,108 +13,108 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|Compiler error C3000|Obsolete.| -|[Compiler error C3001](compiler-error-c3001.md)|'*message*': expected an OpenMP directive name| -|[Compiler error C3002](compiler-error-c3002.md)|'*name1* *name2*': multiple OpenMP directive names| -|[Compiler error C3003](compiler-error-c3003.md)|'*directive*': OpenMP directive name not allowed after directive clauses| -|[Compiler error C3004](compiler-error-c3004.md)|'*clause*': clause not valid on OpenMP '*directive*' directive| -|[Compiler error C3005](compiler-error-c3005.md)|'*message*': unexpected token encountered on OpenMP '*directive*' directive| -|[Compiler error C3006](compiler-error-c3006.md)|'*clause*': clause on OpenMP '*directive*' directive is missing an expected argument| -|[Compiler error C3007](compiler-error-c3007.md)|'*clause*': clause on OpenMP '*directive*' directive does not take an argument| -|[Compiler error C3008](compiler-error-c3008.md)|'*argument*': argument is missing closing ')' on OpenMP '*directive*' directive| -|[Compiler error C3009](compiler-error-c3009.md)|'*label*': jump into OpenMP structured block not allowed| -|[Compiler error C3010](compiler-error-c3010.md)|'*label*': jump out of OpenMP structured block not allowed| -|[Compiler error C3011](compiler-error-c3011.md)|inline assembly not allowed directly within a parallel region| -|[Compiler error C3012](compiler-error-c3012.md)|'*function*': intrinsic function not allowed directly within a parallel region| -|[Compiler error C3013](compiler-error-c3013.md)|'*clause*': clause may only appear once on OpenMP '*directive*' directive| -|[Compiler error C3014](compiler-error-c3014.md)|expected a for loop following OpenMP '*directive*' directive| -|[Compiler error C3015](compiler-error-c3015.md)|initialization in OpenMP 'for' statement has improper form| -|[Compiler error C3016](compiler-error-c3016.md)|'*identifier*': index variable in OpenMP 'for' statement must have signed integral type| -|[Compiler error C3017](compiler-error-c3017.md)|termination test in OpenMP 'for' statement has improper form| -|[Compiler error C3018](compiler-error-c3018.md)|'*identifier*': OpenMP 'for' test or increment must use index variable '*variable*'| -|[Compiler error C3019](compiler-error-c3019.md)|increment in OpenMP 'for' statement has improper form| -|[Compiler error C3020](compiler-error-c3020.md)|'*variable*': index variable of OpenMP 'for' loop cannot be modified in loop body| -|[Compiler error C3021](compiler-error-c3021.md)|'*argument*': argument is empty on OpenMP '*directive*' directive| -|[Compiler error C3022](compiler-error-c3022.md)|'*directive*': invalid schedule kind of '*directive*' on OpenMP '*directive*' directive| -|[Compiler error C3023](compiler-error-c3023.md)|'*argument*': unexpected token encountered in argument to OpenMP '*directive*' clause| -|[Compiler error C3024](compiler-error-c3024.md)|'schedule(runtime)': chunk_size expression is not allowed| -|[Compiler error C3025](compiler-error-c3025.md)|'*clause*': integral expression expected| -|[Compiler error C3026](compiler-error-c3026.md)|'*clause*': constant expression must be positive| -|[Compiler error C3027](compiler-error-c3027.md)|'*clause*': arithmetic or pointer expression expected| -|[Compiler error C3028](compiler-error-c3028.md)|'*member*': only a variable or static data member can be used in a data-sharing clause| -|[Compiler error C3029](compiler-error-c3029.md)|'*symbol*': can only appear once in data-sharing clauses in an OpenMP directive| -|[Compiler error C3030](compiler-error-c3030.md)|'*identifier*': variable in '*directive*' clause/directive cannot have reference type| -|[Compiler error C3031](compiler-error-c3031.md)|'*identifier*': variable in 'reduction' clause must have scalar arithmetic type| -|[Compiler error C3032](compiler-error-c3032.md)|'*identifier*': variable in '*clause*' clause cannot have incomplete type '*type*'| -|[Compiler error C3033](compiler-error-c3033.md)|'*identifier*': variable in '*clause*' clause cannot have const-qualified type| -|[Compiler error C3034](compiler-error-c3034.md)|OpenMP '*directive*' directive cannot be directly nested within '*directive*' directive| -|[Compiler error C3035](compiler-error-c3035.md)|OpenMP 'ordered' directive must bind directly to a 'for' or 'parallel for' directive with the 'ordered' clause| -|[Compiler error C3036](compiler-error-c3036.md)|'*clause*': invalid operator token in OpenMP 'reduction' clause| -|[Compiler error C3037](compiler-error-c3037.md)|'*identifier*': variable in '*clause*' clause must be shared in enclosing context| -|[Compiler error C3038](compiler-error-c3038.md)|'*identifier*': variable in 'private' clause cannot be a reduction variable in enclosing context| -|[Compiler error C3039](compiler-error-c3039.md)|'*identifier*': index variable in OpenMP 'for' statement cannot be a reduction variable| -|[Compiler error C3040](compiler-error-c3040.md)|'*identifier*': type of variable in 'reduction' clause is incompatible with reduction operator '*operator*'| -|[Compiler error C3041](compiler-error-c3041.md)|'*identifier*': variable in 'copyprivate' clause must be private in enclosing context| -|[Compiler error C3042](compiler-error-c3042.md)|'copyprivate' and 'nowait' clauses cannot appear together on OpenMP '*directive*' directive| -|[Compiler error C3043](compiler-error-c3043.md)|OpenMP 'critical' directive cannot be nested in 'critical' directive with same name| -|[Compiler error C3044](compiler-error-c3044.md)|'section': only allowed directly nested under an OpenMP 'sections' directive| -|[Compiler error C3045](compiler-error-c3045.md)|Expected a compound statement following OpenMP 'sections' directive. Missing '{'| -|[Compiler error C3046](compiler-error-c3046.md)|Missing structured block in an OpenMP '#pragma omp sections' region| -|[Compiler error C3047](compiler-error-c3047.md)|Structured block in an OpenMP 'sections' region must be preceded by '#pragma omp section'| -|[Compiler error C3048](compiler-error-c3048.md)|Expression following '#pragma omp atomic' has improper form| -|[Compiler error C3049](compiler-error-c3049.md)|'*argument*': invalid argument in OpenMP 'default' clause| -|[Compiler error C3050](compiler-error-c3050.md)|'*class*': a ref class cannot inherit from '*identifier*'| -|Compiler error C3051|Obsolete.| -|[Compiler error C3052](compiler-error-c3052.md)|'*identifier*': variable doesn't appear in a data-sharing clause under a default(none) clause| -|[Compiler error C3053](compiler-error-c3053.md)|'*identifier*': 'threadprivate' is only valid for global or static data items| -|[Compiler error C3054](compiler-error-c3054.md)|'#pragma omp parallel' is currently not supported in a generic class or function| -|[Compiler error C3055](compiler-error-c3055.md)|'*identifier*': symbol cannot be referenced before it is used in 'threadprivate' directive| -|[Compiler error C3056](compiler-error-c3056.md)|'*identifier*': symbol is not in the same scope with 'threadprivate' directive| -|[Compiler error C3057](compiler-error-c3057.md)|'*identifier*': dynamic initialization of 'threadprivate' symbols is not currently supported| -|[Compiler error C3058](compiler-error-c3058.md)|'*identifier*': symbol not declared as 'threadprivate' before it is used in the 'copyin' clause| -|[Compiler error C3059](compiler-error-c3059.md)|'*identifier*': 'threadprivate' symbol cannot be used in the '*clause*' clause| -|[Compiler error C3060](compiler-error-c3060.md)|'*identifier*': a friend function may not be defined inside a class using a qualified name (it may only be declared)| -|Compiler error C3061|operator '*operator*': not allowed on enumeration '*type*' with underlying type '*type*'| -|[Compiler error C3062](compiler-error-c3062.md)|'*identifier*': enumerator requires value since the underlying type is '*type*'| -|[Compiler error C3063](compiler-error-c3063.md)|operator '*operator*': all operands must have the same enumeration type| -|Compiler error C3064|'*identifier*': must be a simple type or resolve to one| -|[Compiler error C3065](compiler-error-c3065.md)|property declaration at non-class scope is not allowed| -|[Compiler error C3066](compiler-error-c3066.md)|there are multiple ways that an object of this type can be called with these arguments| -|Compiler error C3067|an initializer list cannot be used with the built-in operator[]| -|[Compiler error C3068](compiler-error-c3068.md)|'*identifier*': a 'naked' function cannot contain objects that would require unwinding if a C++ exception occurred| -|[Compiler error C3069](compiler-error-c3069.md)|operator '*operator*': not allowed for enumeration type| -|[Compiler error C3070](compiler-error-c3070.md)|'*identifier*': property does not have a 'set' method| -|[Compiler error C3071](compiler-error-c3071.md)|operator '*operator*' can only be applied to an instance of a ref class or a value-type| -|[Compiler error C3072](compiler-error-c3072.md)|operator '*operator*' cannot be applied to an instance of a ref class use the unary '%' operator to convert an instance of a ref class to a handle type| -|[Compiler error C3073](compiler-error-c3073.md)|'*identifier*': ref class does not have a user-defined copy constructor| -|Compiler error C3074|an array cannot be initialized with a parenthesized initializer| -|[Compiler error C3075](compiler-error-c3075.md)|'*identifier*': you cannot embed an instance of a reference type, '*type*', in a value-type| -|[Compiler error C3076](compiler-error-c3076.md)|'*identifier*': you cannot embed an instance of a reference type, '*type*', in a native type| -|[Compiler error C3077](compiler-error-c3077.md)|'*identifier*': a finalizer can only be a member of a reference type| -|Compiler error C3078|array size must be specified in new expressions| -|Compiler error C3079|an initializer list cannot be used as the right operand of this assignment operator| -|[Compiler error C3080](compiler-error-c3080.md)|'*finalizer*': a finalizer cannot have a storage-class-specifier| -|Compiler error C3081|Obsolete.| -|Compiler error C3082|Obsolete.| -|[Compiler error C3083](compiler-error-c3083.md)|'*identifier*': the symbol to the left of a '::' must be a type| -|[Compiler error C3084](compiler-error-c3084.md)|'*identifier*': a destructor/finalizer cannot be '*keyword*'| -|[Compiler error C3085](compiler-error-c3085.md)|'*identifier*': a constructor cannot be '*keyword*'| -|Compiler error C3086|cannot find 'std::initializer_list': you need to #include \| -|[Compiler error C3087](compiler-error-c3087.md)|'*identifier*': call of '*declaration*' already initializes this member| -|Compiler error C3088|'*class*': attribute constructor must have named formal arguments| -|Compiler error C3089|'*identifier*': parameter name does not match any data member's name| -|Compiler error C3090|'*class*': attribute class cannot be a template| -|Compiler error C3091|'*class*': attribute class cannot have base classes| -|Compiler error C3092|'*class*': attribute class member cannot be a bit field, 'static' or 'const'| -|Compiler error C3093|'*type*': type not allowed for attribute class member '*member*'| -|[Compiler error C3094](compiler-error-c3094.md)|'*attribute*': anonymous usage not allowed| -|[Compiler error C3095](compiler-error-c3095.md)|'*attribute*': attribute cannot be repeated| -|[Compiler error C3096](compiler-error-c3096.md)|'*attribute*': attribute is allowed on data members of attribute classes only| -|[Compiler error C3097](compiler-error-c3097.md)|'*attribute*': attribute must be scoped with 'assembly:' or 'module:'| -|Compiler error C3098|'*identifier*': attribute has no user-defined constructors| -|[Compiler error C3099](compiler-error-c3099.md)|'*keyword*': use [System::AttributeUsageAttribute]/[Windows::Foundation::Metadata::AttributeUsageAttribute] for managed/WinRT attributes| +| Error | Message | +|--|--| +| Compiler error C3000 | '*symbol*': use of class template requires template argument list. Argument deduction is not allowed in non-static data member. | +| [Compiler error C3001](compiler-error-c3001.md) | '*message*': expected an OpenMP directive name | +| [Compiler error C3002](compiler-error-c3002.md) | '*name1* *name2*': multiple OpenMP directive names | +| [Compiler error C3003](compiler-error-c3003.md) | '*directive*': OpenMP directive name not allowed after directive clauses | +| [Compiler error C3004](compiler-error-c3004.md) | '*clause*': clause not valid on OpenMP '*directive*' directive | +| [Compiler error C3005](compiler-error-c3005.md) | '*message*': unexpected token encountered on OpenMP '*directive*' directive | +| [Compiler error C3006](compiler-error-c3006.md) | '*clause*': clause on OpenMP '*directive*' directive is missing an expected argument | +| [Compiler error C3007](compiler-error-c3007.md) | '*clause*': clause on OpenMP '*directive*' directive does not take an argument | +| [Compiler error C3008](compiler-error-c3008.md) | '*argument*': argument is missing closing ')' on OpenMP '*directive*' directive | +| [Compiler error C3009](compiler-error-c3009.md) | '*label*': jump into OpenMP structured block not allowed | +| [Compiler error C3010](compiler-error-c3010.md) | '*label*': jump out of OpenMP structured block not allowed | +| [Compiler error C3011](compiler-error-c3011.md) | inline assembly not allowed directly within a parallel region | +| [Compiler error C3012](compiler-error-c3012.md) | '*function*': intrinsic function not allowed directly within a parallel region | +| [Compiler error C3013](compiler-error-c3013.md) | '*clause*': clause may only appear once on OpenMP '*directive*' directive | +| [Compiler error C3014](compiler-error-c3014.md) | expected a for loop following OpenMP '*directive*' directive | +| [Compiler error C3015](compiler-error-c3015.md) | initialization in OpenMP 'for' statement has improper form | +| [Compiler error C3016](compiler-error-c3016.md) | '*identifier*': index variable in OpenMP 'for' statement must have signed integral type | +| [Compiler error C3017](compiler-error-c3017.md) | termination test in OpenMP 'for' statement has improper form | +| [Compiler error C3018](compiler-error-c3018.md) | '*identifier*': OpenMP 'for' test or increment must use index variable '*variable*' | +| [Compiler error C3019](compiler-error-c3019.md) | increment in OpenMP 'for' statement has improper form | +| [Compiler error C3020](compiler-error-c3020.md) | '*variable*': index variable of OpenMP 'for' loop cannot be modified in loop body | +| [Compiler error C3021](compiler-error-c3021.md) | '*argument*': argument is empty on OpenMP '*directive*' directive | +| [Compiler error C3022](compiler-error-c3022.md) | '*directive*': invalid schedule kind of '*directive*' on OpenMP '*directive*' directive | +| [Compiler error C3023](compiler-error-c3023.md) | '*argument*': unexpected token encountered in argument to OpenMP '*directive*' clause | +| [Compiler error C3024](compiler-error-c3024.md) | 'schedule(runtime)': chunk_size expression is not allowed | +| [Compiler error C3025](compiler-error-c3025.md) | '*clause*': integral expression expected | +| [Compiler error C3026](compiler-error-c3026.md) | '*clause*': constant expression must be positive | +| [Compiler error C3027](compiler-error-c3027.md) | '*clause*': arithmetic or pointer expression expected | +| [Compiler error C3028](compiler-error-c3028.md) | '*member*': only a variable or static data member can be used in a data-sharing clause | +| [Compiler error C3029](compiler-error-c3029.md) | '*symbol*': can only appear once in data-sharing clauses in an OpenMP directive | +| [Compiler error C3030](compiler-error-c3030.md) | '*identifier*': variable in '*directive*' clause/directive cannot have reference type | +| [Compiler error C3031](compiler-error-c3031.md) | '*identifier*': variable in 'reduction' clause must have scalar arithmetic type | +| [Compiler error C3032](compiler-error-c3032.md) | '*identifier*': variable in '*clause*' clause cannot have incomplete type '*type*' | +| [Compiler error C3033](compiler-error-c3033.md) | '*identifier*': variable in '*clause*' clause cannot have const-qualified type | +| [Compiler error C3034](compiler-error-c3034.md) | OpenMP '*directive*' directive cannot be directly nested within '*directive*' directive | +| [Compiler error C3035](compiler-error-c3035.md) | OpenMP 'ordered' directive must bind directly to a 'for' or 'parallel for' directive with the 'ordered' clause | +| [Compiler error C3036](compiler-error-c3036.md) | '*clause*': invalid operator token in OpenMP 'reduction' clause | +| [Compiler error C3037](compiler-error-c3037.md) | '*identifier*': variable in '*clause*' clause must be shared in enclosing context | +| [Compiler error C3038](compiler-error-c3038.md) | '*identifier*': variable in 'private' clause cannot be a reduction variable in enclosing context | +| [Compiler error C3039](compiler-error-c3039.md) | '*identifier*': index variable in OpenMP 'for' statement cannot be a reduction variable | +| [Compiler error C3040](compiler-error-c3040.md) | '*identifier*': type of variable in 'reduction' clause is incompatible with reduction operator '*operator*' | +| [Compiler error C3041](compiler-error-c3041.md) | '*identifier*': variable in 'copyprivate' clause must be private in enclosing context | +| [Compiler error C3042](compiler-error-c3042.md) | 'copyprivate' and 'nowait' clauses cannot appear together on OpenMP '*directive*' directive | +| [Compiler error C3043](compiler-error-c3043.md) | OpenMP 'critical' directive cannot be nested in 'critical' directive with same name | +| [Compiler error C3044](compiler-error-c3044.md) | 'section': only allowed directly nested under an OpenMP 'sections' directive | +| [Compiler error C3045](compiler-error-c3045.md) | Expected a compound statement following OpenMP 'sections' directive. Missing '{' | +| [Compiler error C3046](compiler-error-c3046.md) | Missing structured block in an OpenMP '#pragma omp sections' region | +| [Compiler error C3047](compiler-error-c3047.md) | Structured block in an OpenMP 'sections' region must be preceded by '#pragma omp section' (Obsolete in Visual Studio 2022.) | +| [Compiler error C3048](compiler-error-c3048.md) | '`#pragma omp atomic`*statement*': expression or block-statement following pragma does not conform to the OpenMP specification | +| [Compiler error C3049](compiler-error-c3049.md) | '*argument*': invalid argument in OpenMP 'default' clause | +| [Compiler error C3050](compiler-error-c3050.md) | '*class*': a ref class cannot inherit from '*identifier*' | +| Compiler error C3051 | Obsolete. | +| [Compiler error C3052](compiler-error-c3052.md) | '*identifier*': variable reference occurs under a `default(none)` clause and must have explicitly specified data sharing attributes | +| [Compiler error C3053](compiler-error-c3053.md) | '*identifier*': 'threadprivate' is only valid for global or static data items | +| [Compiler error C3054](compiler-error-c3054.md) | '#pragma omp parallel' is currently not supported in a generic class or function (Obsolete in Visual Studio 2022.) | +| [Compiler error C3055](compiler-error-c3055.md) | '*identifier*': symbol cannot be referenced before it is used in 'threadprivate' directive | +| [Compiler error C3056](compiler-error-c3056.md) | '*identifier*': symbol is not in the same scope with 'threadprivate' directive | +| [Compiler error C3057](compiler-error-c3057.md) | '*identifier*': dynamic initialization of 'threadprivate' symbols is not currently supported | +| [Compiler error C3058](compiler-error-c3058.md) | '*identifier*': symbol not declared as 'threadprivate' before it is used in the 'copyin' clause | +| [Compiler error C3059](compiler-error-c3059.md) | '*identifier*': 'threadprivate' symbol cannot be used in the '*clause*' clause | +| [Compiler error C3060](compiler-error-c3060.md) | '*identifier*': a friend function may not be defined inside a class using a qualified name (it may only be declared) | +| Compiler error C3061 | operator '*operator*': not allowed on enumeration '*type*' with underlying type '*type*' | +| [Compiler error C3062](compiler-error-c3062.md) | '*identifier*': enumerator requires value since the underlying type is '*type*' | +| [Compiler error C3063](compiler-error-c3063.md) | operator '*operator*': all operands must have the same enumeration type | +| Compiler error C3064 | '*identifier*': must be a simple type or resolve to one | +| [Compiler error C3065](compiler-error-c3065.md) | '`__declspec(`*specifier*`)`' at non-class scope is not allowed | +| [Compiler error C3066](compiler-error-c3066.md) | call to an object of this type is ambiguous | +| Compiler error C3067 | an initializer list cannot be used with the built-in operator[] | +| [Compiler error C3068](compiler-error-c3068.md) | '*identifier*': a 'naked' function cannot contain objects that would require unwinding if a C++ exception occurred | +| [Compiler error C3069](compiler-error-c3069.md) | operator '*operator*': not allowed for enumeration type | +| [Compiler error C3070](compiler-error-c3070.md) | '*identifier*': property does not have a 'set' method | +| [Compiler error C3071](compiler-error-c3071.md) | operator '*operator*' can only be applied to an instance of a ref class or a value-type | +| [Compiler error C3072](compiler-error-c3072.md) | operator '*operator*' cannot be applied to an instance of a ref class use the unary '%' operator to convert an instance of a ref class to a handle type | +| [Compiler error C3073](compiler-error-c3073.md) | '*identifier*': ref class does not have a user-defined copy constructor | +| Compiler error C3074 | an array cannot be initialized with a parenthesized initializer | +| [Compiler error C3075](compiler-error-c3075.md) | '*identifier*': you cannot embed an instance of a reference type, '*type*', in a value-type | +| [Compiler error C3076](compiler-error-c3076.md) | '*identifier*': you cannot embed an instance of a reference type, '*type*', in a native type | +| [Compiler error C3077](compiler-error-c3077.md) | '*identifier*': a finalizer can only be a member of a reference type | +| Compiler error C3078 | array size must be specified in new expressions without an initializer | +| Compiler error C3079 | an initializer list cannot be used as the right operand of this assignment operator | +| [Compiler error C3080](compiler-error-c3080.md) | '*finalizer*': a finalizer cannot have a storage-class-specifier | +| Compiler error C3081 | Obsolete. | +| Compiler error C3082 | Obsolete. | +| [Compiler error C3083](compiler-error-c3083.md) | '*identifier*': the symbol to the left of a '::' must be a type | +| [Compiler error C3084](compiler-error-c3084.md) | '*identifier*': a destructor/finalizer cannot be '*keyword*' | +| [Compiler error C3085](compiler-error-c3085.md) | '*identifier*': a constructor cannot be '*keyword*' | +| Compiler error C3086 | cannot find 'std::initializer_list': you need to #include \ | +| [Compiler error C3087](compiler-error-c3087.md) | '*identifier*': call of '*declaration*' already initializes this member | +| Compiler error C3088 | '*class*': attribute constructor must have named formal arguments | +| Compiler error C3089 | '*identifier*': parameter name does not match any data member's name | +| Compiler error C3090 | '*class*': attribute class cannot be a template | +| Compiler error C3091 | '*class*': attribute class cannot have base classes | +| Compiler error C3092 | '*class*': attribute class member cannot be a bit field, 'static' or 'const' | +| Compiler error C3093 | '*type*': type not allowed for attribute class member '*member*' | +| [Compiler error C3094](compiler-error-c3094.md) | '*attribute*': anonymous usage not allowed | +| [Compiler error C3095](compiler-error-c3095.md) | '*attribute*': attribute cannot be repeated | +| [Compiler error C3096](compiler-error-c3096.md) | '*attribute*': attribute is allowed on data members of attribute classes only | +| [Compiler error C3097](compiler-error-c3097.md) | '*attribute*': attribute must be scoped with 'assembly:' or 'module:' | +| Compiler error C3098 | '*identifier*': attribute has no user-defined constructors | +| [Compiler error C3099](compiler-error-c3099.md) | '*keyword*': use [System::AttributeUsageAttribute]/[Windows::Foundation::Metadata::AttributeUsageAttribute] for managed/WinRT attributes | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md index 31ff19bc1e..338e4eceb9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C3100 Through C3199" title: "Compiler errors C3100 Through C3199" -ms.date: "04/21/2019" -f1_keywords: ["C3102", "C3105", "C3107", "C3108", "C3109", "C3111", "C3112", "C3119", "C3122", "C3123", "C3124", "C3125", "C3127", "C3128", "C3129", "C3143", "C3144", "C3146", "C3147", "C3148", "C3151", "C3158", "C3164", "C3165", "C3169", "C3177", "C3178", "C3184", "C3188", "C3191", "C3193"] -helpviewer_keywords: ["C3102", "C3105", "C3107", "C3108", "C3109", "C3111", "C3112", "C3119", "C3122", "C3123", "C3124", "C3125", "C3127", "C3128", "C3129", "C3143", "C3144", "C3146", "C3147", "C3148", "C3151", "C3158", "C3164", "C3165", "C3169", "C3177", "C3178", "C3184", "C3188", "C3191", "C3193"] -ms.assetid: 7bc40c2f-6a8d-488a-b665-f39375afee77 +ms.date: 06/01/2022 +f1_keywords: ["C3102", "C3105", "C3107", "C3108", "C3109", "C3111", "C3112", "C3119", "C3122", "C3123", "C3124", "C3125", "C3127", "C3128", "C3129", "C3143", "C3144", "C3146", "C3147", "C3148", "C3151", "C3158", "C3164", "C3165", "C3169", "C3177", "C3178", "C3184", "C3186", "C3188", "C3191", "C3193"] +helpviewer_keywords: ["C3102", "C3105", "C3107", "C3108", "C3109", "C3111", "C3112", "C3119", "C3122", "C3123", "C3124", "C3125", "C3127", "C3128", "C3129", "C3143", "C3144", "C3146", "C3147", "C3148", "C3151", "C3158", "C3164", "C3165", "C3169", "C3177", "C3178", "C3184", "C3186", "C3188", "C3191", "C3193"] --- # Compiler errors C3100 Through C3199 @@ -14,108 +13,108 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Compiler error C3100](compiler-error-c3100.md)|'*identifier*': unknown attribute qualifier| -|[Compiler error C3101](compiler-error-c3101.md)|illegal expression for named attribute argument '*identifier*'| -|Compiler error C3102|Obsolete.| -|[Compiler error C3103](compiler-error-c3103.md)|'*identifier*': repeated named argument| -|[Compiler error C3104](compiler-error-c3104.md)|illegal attribute argument| -|Compiler error C3105|'*symbol*': cannot be used as an attribute| -|[Compiler error C3106](compiler-error-c3106.md)|'*attribute*': unnamed arguments must precede named arguments| -|Compiler error C3107|'*attribute*': member functions of native attributes cannot be defined| -|Compiler error C3108|cannot deduce a type as an initializer list is not an expression| -|Compiler error C3109|'*identifier*': interface methods must use either the '__stdcall' or '__cdecl' calling convention| -|[Compiler error C3110](compiler-error-c3110.md)|'*function*': you cannot overload a COM interface method| -|Compiler error C3111|An initializer list cannot be used as the default argument for a template parameter| -|Compiler error C3112|'*interface*': an interface can only be declared at global or namespace scope| -|[Compiler error C3113](compiler-error-c3113.md)|an 'interface/enum' cannot be a template/generic| -|[Compiler error C3114](compiler-error-c3114.md)|'*identifier*': not a valid named attribute argument| -|[Compiler error C3115](compiler-error-c3115.md)|'*attribute*': this attribute is not allowed on '*construct*'| -|[Compiler error C3116](compiler-error-c3116.md)|'*specifier*': invalid storage class for interface method| -|[Compiler error C3117](compiler-error-c3117.md)|'*interface*': an interface can only have one base class| -|[Compiler error C3118](compiler-error-c3118.md)|'*interface*': interfaces do not support virtual inheritance| -|Compiler error C3119|alignas(void) is not allowed| -|[Compiler error C3120](compiler-error-c3120.md)|'*identifier*': interface methods cannot take a variable argument list| -|[Compiler error C3121](compiler-error-c3121.md)|cannot change GUID for class '*class*'| -|Compiler error C3122|'*interface*': a WinRT generic interface cannot have GUID| -|Compiler error C3123|WinRT generic interface cannot have constraints| -|Compiler error C3124|'signed char' is not a valid WinRT data type. Use 'unsigned char', 'wchar_t' or 'signed short' instead.| -|Compiler error C3125|'*type*': type cannot directly or indirectly derive from 'Platform::Exception'| -|[Compiler error C3126](compiler-error-c3126.md)|cannot define a union '*union*' inside of managed/WinRT type '*type*'| -|Compiler error C3127|'*type*': '*trait*' trait can only be used on a WinRT ref class| -|Compiler error C3128|'*type*' does not have a vtable that was introduced by '*type*'| -|Compiler error C3129|'*type*': __default_vptr_for_base can only be used on locally defined polymorphic types and bases| -|[Compiler error C3130](compiler-error-c3130.md)|Internal Compiler error: failed to write injected code block to PDB| -|[Compiler error C3131](compiler-error-c3131.md)|project must have a 'module' attribute with a 'name' property| -|[Compiler error C3132](compiler-error-c3132.md)|'*parameter*': parameter arrays can only be applied to a formal argument of type 'single-dimensional managed/WinRT array'| -|[Compiler error C3133](compiler-error-c3133.md)|Attributes cannot be applied to C++ varargs| -|[Compiler error C3134](compiler-error-c3134.md)|'*value*': value of attribute argument '*argument*' does not have valid type '*type*'| -|[Compiler error C3135](compiler-error-c3135.md)|'*identifier*': a property cannot have a 'const' or 'volatile' type| -|[Compiler error C3136](compiler-error-c3136.md)|'*interface*': a COM interface can only inherit from another COM interface, '*interface*' is not a COM interface| -|[Compiler error C3137](compiler-error-c3137.md)|'*identifier*': a property cannot be initialized| -|[Compiler error C3138](compiler-error-c3138.md)|'*identifier*': a '*attribute*' interface must inherit from IDispatch, or from an interface that inherits from IDispatch| -|[Compiler error C3139](compiler-error-c3139.md)|'*type*': cannot export a UDT without members| -|[Compiler error C3140](compiler-error-c3140.md)|cannot have multiple 'module' attributes in the same compilation unit| -|[Compiler error C3141](compiler-error-c3141.md)|'*interface*': interfaces only support public inheritance| -|[Compiler error C3142](compiler-error-c3142.md)|'*property*': you cannot take the address of a property| -|Compiler error C3143|'*argument*': attribute argument cannot have multiple values| -|Compiler error C3144|'*attribute*': attribute requires explicit arguments, '*argument*' is unnamed| -|[Compiler error C3145](compiler-error-c3145.md)|'*identifier*': global or static variable may not have managed/WinRT type '*type*'| -|Compiler error C3146|Obsolete.| -|Compiler error C3147|Obsolete.| -|Compiler error C3148|Obsolete.| -|[Compiler error C3149](compiler-error-c3149.md)|'*type*': cannot use this type here without a top-level '*token*'| -|[Compiler error C3150](compiler-error-c3150.md)|'*construct*': '*attribute*' can only be applied to a class, struct, interface, array or pointer| -|Compiler error C3151|Obsolete.| -|[Compiler error C3152](compiler-error-c3152.md)|'*function*': '*keyword*' can only be applied to a class, struct, or virtual member function| -|[Compiler error C3153](compiler-error-c3153.md)|'*interface*': you cannot create an instance of an interface| -|[Compiler error C3154](compiler-error-c3154.md)|Expected ',' before ellipsis. Non-comma separated ellipsis not supported on parameter array functions.| -|[Compiler error C3155](compiler-error-c3155.md)|attributes are not allowed in a property indexer| -|[Compiler error C3156](compiler-error-c3156.md)|'*class*': you cannot have a local definition of a managed/WinRT type| -|[Compiler error C3157](compiler-error-c3157.md)|ParamArray attribute can only be applied to the last parameter| -|Compiler error C3158|'*function*': '*keyword*' can only be applied to a virtual member function| -|[Compiler error C3159](compiler-error-c3159.md)|'*identifier*': array of pointers to value type cannot be declared| -|[Compiler error C3160](compiler-error-c3160.md)|'*type*': a data member of a managed/WinRT class cannot have this type| -|[Compiler error C3161](compiler-error-c3161.md)|'*interface*': nesting class, struct, or interface in an interface is illegal; nesting interface in a class or struct is illegal| -|[Compiler error C3162](compiler-error-c3162.md)|'*type*': a reference type which has a destructor cannot be used as the type of static data member '*member*'| -|[Compiler error C3163](compiler-error-c3163.md)|'*class*': attributes inconsistent with previous declaration| -|Compiler error C3164|Obsolete.| -|Compiler error C3165|'*value*': cannot convert to an integral or floating point value| -|[Compiler error C3166](compiler-error-c3166.md)|Obsolete. '*type*': a data member of a managed/WinRT class cannot have type '*pointer_type* to interior *managed_pointer_type*'| -|[Compiler error C3167](compiler-error-c3167.md)|Unable to initialize .NET Framework: make sure it is installed| -|[Compiler error C3168](compiler-error-c3168.md)|'*type*': illegal underlying type for enum| -|Compiler error C3169|'*type*': cannot deduce type for 'auto' from '*type*'| -|[Compiler error C3170](compiler-error-c3170.md)|cannot have different module identifiers in a project| -|[Compiler error C3171](compiler-error-c3171.md)|'*module*': cannot specify different module attributes in a project| -|[Compiler error C3172](compiler-error-c3172.md)|'*identifier*': cannot specify different idl_module attributes in a project| -|[Compiler error C3173](compiler-error-c3173.md)|version mismatch in idl merge| -|[Compiler error C3174](compiler-error-c3174.md)|module attribute was not specified| -|[Compiler error C3175](compiler-error-c3175.md)|'*function*': cannot call a method of a managed type from unmanaged function '*function*'| -|[Compiler error C3176](compiler-error-c3176.md)|'*type*': cannot declare local value type| -|Compiler error C3177|you cannot have a conversion function to a type that contains '*type*'| -|Compiler error C3178|'*type*': cannot use ParamArray in a function with default arguments| -|[Compiler error C3179](compiler-error-c3179.md)|an unnamed managed/WinRT type is not allowed| -|[Compiler error C3180](compiler-error-c3180.md)|'*type*': name exceeds meta-data limit of '*number*' characters| -|[Compiler error C3181](compiler-error-c3181.md)|'*type*': invalid operand for *operator*| -|[Compiler error C3182](compiler-error-c3182.md)|'*type*': a member using-declaration or access declaration is illegal within a managed/WinRT type| -|[Compiler error C3183](compiler-error-c3183.md)|cannot define unnamed class, struct or union inside of managed/WinRT type '*class*'| -|Compiler error C3184|Obsolete.| -|[Compiler error C3185](compiler-error-c3185.md)|'typeid': used on managed/WinRT type '*type*', use '*operator*' instead| -|Compiler error C3186|Obsolete.| -|[Compiler error C3187](compiler-error-c3187.md)|'*identifier*': is only available within the body of a function| -|Compiler error C3188|Obsolete.| -|[Compiler error C3189](compiler-error-c3189.md)|'typeid<*declarator*>': this syntax is no longer supported, use::typeid instead| -|[Compiler error C3190](compiler-error-c3190.md)|'*declarator*' with the provided template arguments is not the explicit instantiation of any member function of '*type*'| -|Compiler error C3191|Obsolete.| -|[Compiler error C3192](compiler-error-c3192.md)|syntax error: '^' is not a prefix operator (did you mean '*'?)| -|Compiler error C3193|'*construct*': requires '/clr' or '/ZW' command line option| -|[Compiler error C3194](compiler-error-c3194.md)|'*type*': a value-type cannot have an assignment operator| -|[Compiler error C3195](compiler-error-c3195.md)|'*keyword*': is reserved and cannot be used as a member of a ref class or value type. CLR/WinRT operators must be defined using the 'operator' keyword| -|[Compiler error C3196](compiler-error-c3196.md)|'*identifier*': used more than once| -|[Compiler error C3197](compiler-error-c3197.md)|'*keyword*': can only be used in definitions| -|[Compiler error C3198](compiler-error-c3198.md)|invalid use of floating-point pragmas: fenv_access pragma operates only in precise mode| -|[Compiler error C3199](compiler-error-c3199.md)|invalid use of floating-point pragmas: exceptions are not supported in non-precise mode| +| Error | Message | +|--|--| +| [Compiler error C3100](compiler-error-c3100.md) | '*identifier*': unknown attribute qualifier | +| [Compiler error C3101](compiler-error-c3101.md) | illegal expression for named attribute argument '*identifier*' | +| Compiler error C3102 | Obsolete. | +| [Compiler error C3103](compiler-error-c3103.md) | '*identifier*': repeated named argument | +| [Compiler error C3104](compiler-error-c3104.md) | illegal attribute argument | +| Compiler error C3105 | '*symbol*': cannot be used as an attribute | +| [Compiler error C3106](compiler-error-c3106.md) | '*attribute*': unnamed arguments must precede named arguments | +| Compiler error C3107 | '*attribute*': member functions of native attributes cannot be defined | +| Compiler error C3108 | cannot deduce a type as an initializer list is not an expression | +| Compiler error C3109 | '*identifier*': interface methods must use either the '__stdcall' or '__cdecl' calling convention | +| [Compiler error C3110](compiler-error-c3110.md) | '*function*': you cannot overload a COM interface method | +| Compiler error C3111 | An initializer list cannot be used as the default argument for a template parameter | +| Compiler error C3112 | '*interface*': an interface can only be declared at global or namespace scope | +| [Compiler error C3113](compiler-error-c3113.md) | an 'interface/enum' cannot be a template/generic | +| [Compiler error C3114](compiler-error-c3114.md) | '*identifier*': not a valid named attribute argument | +| [Compiler error C3115](compiler-error-c3115.md) | '*attribute*': this attribute is not allowed on '*construct*' | +| [Compiler error C3116](compiler-error-c3116.md) | '*specifier*': invalid storage class for interface method | +| [Compiler error C3117](compiler-error-c3117.md) | '*interface*': an interface can only have one base class | +| [Compiler error C3118](compiler-error-c3118.md) | '*interface*': interfaces do not support virtual inheritance | +| Compiler error C3119 | alignas(void) is not allowed | +| [Compiler error C3120](compiler-error-c3120.md) | '*identifier*': interface methods cannot take a variable argument list | +| [Compiler error C3121](compiler-error-c3121.md) | cannot change GUID for class '*class*' | +| Compiler error C3122 | '*interface*': a WinRT generic interface cannot have GUID | +| Compiler error C3123 | WinRT generic interface cannot have constraints | +| Compiler error C3124 | 'signed char' is not a valid WinRT data type. Use 'unsigned char', 'wchar_t' or 'signed short' instead. | +| Compiler error C3125 | '*type*': type cannot directly or indirectly derive from 'Platform::Exception' | +| [Compiler error C3126](compiler-error-c3126.md) | cannot define a union '*union*' inside of managed/WinRT type '*type*' | +| Compiler error C3127 | '*type*': '*trait*' trait can only be used on a WinRT ref class | +| Compiler error C3128 | '*type*' does not have a vtable that was introduced by '*type*' | +| Compiler error C3129 | '*type*': __default_vptr_for_base can only be used on locally defined polymorphic types and bases | +| [Compiler error C3130](compiler-error-c3130.md) | Internal Compiler error: failed to write injected code block to PDB | +| [Compiler error C3131](compiler-error-c3131.md) | project must have a 'module' attribute with a 'name' property | +| [Compiler error C3132](compiler-error-c3132.md) | '*parameter*': parameter arrays can only be applied to a formal argument of type 'single-dimensional managed/WinRT array' | +| [Compiler error C3133](compiler-error-c3133.md) | Attributes cannot be applied to C++ varargs | +| [Compiler error C3134](compiler-error-c3134.md) | '*value*': value of attribute argument '*argument*' does not have valid type '*type*' | +| [Compiler error C3135](compiler-error-c3135.md) | '*identifier*': a property cannot have a 'const' or 'volatile' type | +| [Compiler error C3136](compiler-error-c3136.md) | '*interface*': a COM interface can only inherit from another COM interface, '*interface*' is not a COM interface | +| [Compiler error C3137](compiler-error-c3137.md) | '*identifier*': a property cannot be initialized | +| [Compiler error C3138](compiler-error-c3138.md) | '*identifier*': a '*attribute*' interface must inherit from IDispatch, or from an interface that inherits from IDispatch | +| [Compiler error C3139](compiler-error-c3139.md) | '*type*': cannot export a UDT without members | +| [Compiler error C3140](compiler-error-c3140.md) | cannot have multiple 'module' attributes in the same compilation unit | +| [Compiler error C3141](compiler-error-c3141.md) | '*interface*': interfaces only support public inheritance | +| [Compiler error C3142](compiler-error-c3142.md) | '*property*': you cannot take the address of a property | +| Compiler error C3143 | '*argument*': attribute argument cannot have multiple values | +| Compiler error C3144 | '*attribute*': attribute requires explicit arguments, '*argument*' is unnamed | +| [Compiler error C3145](compiler-error-c3145.md) | '*identifier*': global or static variable may not have managed/WinRT type '*type*' | +| Compiler error C3146 | Obsolete. | +| Compiler error C3147 | Obsolete. | +| Compiler error C3148 | Obsolete. | +| [Compiler error C3149](compiler-error-c3149.md) | '*type*': cannot use this type here without a top-level '*token*' | +| [Compiler error C3150](compiler-error-c3150.md) | '*construct*': '*attribute*' can only be applied to a class, struct, interface, array or pointer | +| Compiler error C3151 | Obsolete. | +| [Compiler error C3152](compiler-error-c3152.md) | '*function*': '*keyword*' can only be applied to a class, struct, or virtual member function | +| [Compiler error C3153](compiler-error-c3153.md) | '*interface*': you cannot create an instance of an interface | +| [Compiler error C3154](compiler-error-c3154.md) | Expected ',' before ellipsis. Non-comma separated ellipsis not supported on parameter array functions. | +| [Compiler error C3155](compiler-error-c3155.md) | attributes are not allowed in a property indexer | +| [Compiler error C3156](compiler-error-c3156.md) | '*class*': you cannot have a local definition of a managed/WinRT type | +| [Compiler error C3157](compiler-error-c3157.md) | ParamArray attribute can only be applied to the last parameter | +| Compiler error C3158 | '*function*': '*keyword*' can only be applied to a virtual member function | +| [Compiler error C3159](compiler-error-c3159.md) | '*identifier*': array of pointers to value type cannot be declared | +| [Compiler error C3160](compiler-error-c3160.md) | '*type*': a data member of a managed/WinRT class cannot have this type | +| [Compiler error C3161](compiler-error-c3161.md) | '*interface*': nesting class, struct, or interface in an interface is illegal; nesting interface in a class or struct is illegal | +| [Compiler error C3162](compiler-error-c3162.md) | '*type*': a reference type which has a destructor cannot be used as the type of static data member '*member*' | +| [Compiler error C3163](compiler-error-c3163.md) | '*class*': attributes inconsistent with previous declaration | +| Compiler error C3164 | Obsolete. | +| Compiler error C3165 | '*value*': cannot convert to an integral or floating point value | +| [Compiler error C3166](compiler-error-c3166.md) | '*type*': a data member of a managed/WinRT class cannot have type '*pointer_type* to interior *managed_pointer_type*' | +| [Compiler error C3167](compiler-error-c3167.md) | Unable to initialize .NET Framework: make sure it is installed | +| [Compiler error C3168](compiler-error-c3168.md) | '*type*': illegal underlying type for enum | +| Compiler error C3169 | '*type*': cannot deduce type for 'auto' from '*type*' | +| [Compiler error C3170](compiler-error-c3170.md) | cannot have different module identifiers in a project | +| [Compiler error C3171](compiler-error-c3171.md) | '*module*': cannot specify different module attributes in a project | +| [Compiler error C3172](compiler-error-c3172.md) | '*identifier*': cannot specify different idl_module attributes in a project | +| [Compiler error C3173](compiler-error-c3173.md) | version mismatch in idl merge | +| [Compiler error C3174](compiler-error-c3174.md) | module attribute was not specified | +| [Compiler error C3175](compiler-error-c3175.md) | '*function*': cannot call a method of a managed type from unmanaged function '*function*' | +| [Compiler error C3176](compiler-error-c3176.md) | '*type*': cannot declare local value type | +| Compiler error C3177 | you cannot have a conversion function to a type that contains '*type*' (Obsolete in Visual Studio 2022.) | +| Compiler error C3178 | '*type*': cannot use ParamArray in a function with default arguments (Obsolete in Visual Studio 2022.) | +| [Compiler error C3179](compiler-error-c3179.md) | an unnamed managed/WinRT type is not allowed | +| [Compiler error C3180](compiler-error-c3180.md) | '*type*': name exceeds meta-data limit of '*number*' characters | +| [Compiler error C3181](compiler-error-c3181.md) | '*type*': invalid operand for *operator* | +| [Compiler error C3182](compiler-error-c3182.md) | '*type*': a member using-declaration or access declaration is illegal within a managed/WinRT type | +| [Compiler error C3183](compiler-error-c3183.md) | cannot define unnamed class, struct or union inside of managed/WinRT type '*class*' | +| Compiler error C3184 | Obsolete. | +| [Compiler error C3185](compiler-error-c3185.md) | 'typeid': used on managed/WinRT type '*type*', use '*operator*' instead | +| Compiler error C3186 | Obsolete. | +| [Compiler error C3187](compiler-error-c3187.md) | '*identifier*': is only available within the body of a function | +| Compiler error C3188 | Obsolete. | +| [Compiler error C3189](compiler-error-c3189.md) | 'typeid<*declarator*>': this syntax is no longer supported, use::typeid instead (Obsolete in Visual Studio 2022.) | +| [Compiler error C3190](compiler-error-c3190.md) | '*declarator*' with the provided template arguments is not the explicit instantiation of any member function of '*type*' | +| Compiler error C3191 | Obsolete. | +| [Compiler error C3192](compiler-error-c3192.md) | syntax error: '^' is not a prefix operator (did you mean '*'?) | +| Compiler error C3193 | '*construct*': requires '/clr' or '/ZW' command line option | +| [Compiler error C3194](compiler-error-c3194.md) | '*type*': a value-type cannot have an assignment operator | +| [Compiler error C3195](compiler-error-c3195.md) | '*keyword*': is reserved and cannot be used as a member of a ref class or value type. CLR/WinRT operators must be defined using the 'operator' keyword | +| [Compiler error C3196](compiler-error-c3196.md) | '*identifier*': used more than once | +| [Compiler error C3197](compiler-error-c3197.md) | '*keyword*': can only be used in definitions | +| [Compiler error C3198](compiler-error-c3198.md) | invalid use of floating-point pragmas: fenv_access pragma operates only in precise mode | +| [Compiler error C3199](compiler-error-c3199.md) | invalid use of floating-point pragmas: exceptions are not supported in non-precise mode | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3200-through-c3299.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3200-through-c3299.md index 6a18ea33b1..87483c7cfe 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3200-through-c3299.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3200-through-c3299.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C3200 Through C3299" title: "Compiler errors C3200 Through C3299" -ms.date: "04/21/2019" +ms.date: 06/01/2022 f1_keywords: ["C3220", "C3221", "C3245", "C3249", "C3250", "C3256", "C3257", "C3258", "C3259", "C3260", "C3261", "C3263", "C3267", "C3281", "C3294"] helpviewer_keywords: ["C3220", "C3221", "C3245", "C3249", "C3250", "C3256", "C3257", "C3258", "C3259", "C3260", "C3261", "C3263", "C3267", "C3281", "C3294"] -ms.assetid: 6b3104f6-63bc-4823-b6f3-b8a16be4b87f --- # Compiler errors C3200 Through C3299 @@ -14,108 +13,108 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Compiler error C3200](compiler-error-c3200.md)|'*type*': invalid template argument for template parameter '*parameter*', expected a class template| -|[Compiler error C3201](compiler-error-c3201.md)|the template parameter list for class template '*template*' does not match the template parameter list for template parameter '*parameter*'| -|[Compiler error C3202](compiler-error-c3202.md)|'*identifier*': invalid default argument, expected a class template| -|[Compiler error C3203](compiler-error-c3203.md)|'*identifier*': unspecialized class template/generic can't be used as a template/generic argument for template/generic parameter '*parameter*', expected a real type| -|[Compiler error C3204](compiler-error-c3204.md)|'*function*' cannot be called from within a `catch` block| -|[Compiler error C3205](compiler-error-c3205.md)|argument list for template template parameter '*identifier*' is missing| -|[Compiler error C3206](compiler-error-c3206.md)|'*function*': invalid template/generic argument for '*template*', missing template/generic argument list on class template/generic '*type*'| -|[Compiler error C3207](compiler-error-c3207.md)|'*function*': invalid template argument for '*parameter*', class template expected| -|[Compiler error C3208](compiler-error-c3208.md)|'*function*': template parameter list for class template '*template*' does not match template parameter list for template template parameter '*parameter*'| -|[Compiler error C3209](compiler-error-c3209.md)|'*type*': generic class must be a managed/WinRT class| -|[Compiler error C3210](compiler-error-c3210.md)|'*identifier*': access declaration can only be applied to a base class member| -|[Compiler error C3211](compiler-error-c3211.md)|'*function*': explicit specialization is using partial specialization syntax, use `template <>` instead| -|[Compiler error C3212](compiler-error-c3212.md)|'*function*': an explicit specialization of a template member must be a member of an explicit specialization| -|[Compiler error C3213](compiler-error-c3213.md)|base class '*class*' is less accessible than '*derived_class*'| -|[Compiler error C3214](compiler-error-c3214.md)|'*argument*': invalid type argument for generic parameter '*parameter*' of generic '*type*', does not meet constraint '*constraint*'| -|[Compiler error C3215](compiler-error-c3215.md)|'*constraint1*': generic type parameter already constrained by '*constraint2*'| -|[Compiler error C3216](compiler-error-c3216.md)|constraint must be a generic parameter, not '*type*'| -|[Compiler error C3217](compiler-error-c3217.md)|'*parameter*': generic parameter cannot be constrained in this declaration| -|[Compiler error C3218](compiler-error-c3218.md)|'*type*': type not allowed as a constraint| -|[Compiler error C3219](compiler-error-c3219.md)|'*parameter*': generic parameter cannot be constrained by multiple non-interfaces: '*type*'| -|Compiler error C3220|'*interface*': interface cannot have `progid`| -|Compiler error C3221|'*member*': multiple 'default' and 'case' attributes not allowed on a member| -|[Compiler error C3222](compiler-error-c3222.md)|'*function*': cannot declare default arguments for member functions of a managed/WinRT type or generic functions| -|[Compiler error C3223](compiler-error-c3223.md)|'*property*': you cannot apply '`typeid`' to a property| -|[Compiler error C3224](compiler-error-c3224.md)|'*type*': no overloaded generic class takes '*number*' generic type arguments| -|[Compiler error C3225](compiler-error-c3225.md)|generic type argument for '*argument*' cannot be '*type*', it must be a value type or a handle to a reference type| -|[Compiler error C3226](compiler-error-c3226.md)|A template declaration is not allowed inside a generic declaration| -|[Compiler error C3227](compiler-error-c3227.md)|'*type*': cannot use '*operator*' to allocate a generic type| -|[Compiler error C3228](compiler-error-c3228.md)|'*function*': generic type argument for '*argument*' cannot be '*type*', it must be a value type or handle type| -|[Compiler error C3229](compiler-error-c3229.md)|'*type*': indirections on a generic type parameter are not allowed| -|[Compiler error C3230](compiler-error-c3230.md)|'*function*': template type argument for '*argument*' cannot contain a generic type parameter: '*type*'| -|[Compiler error C3231](compiler-error-c3231.md)|'*type*': template type argument cannot use a generic type parameter| -|[Compiler error C3232](compiler-error-c3232.md)|'*parameter*': a generic type parameter cannot be used in a qualified name| -|[Compiler error C3233](compiler-error-c3233.md)|'*type*': generic type parameter already constrained| -|[Compiler error C3234](compiler-error-c3234.md)|a generic class may not derive from a generic type parameter| -|[Compiler error C3235](compiler-error-c3235.md)|'*specialization*': explicit or partial specialization of a generic class is not allowed| -|[Compiler error C3236](compiler-error-c3236.md)|explicit instantiation of a generic is not allowed| -|[Compiler error C3237](compiler-error-c3237.md)|'*class*': a generic class cannot be a custom attribute| -|[Compiler error C3238](compiler-error-c3238.md)|'*type*': a type with this name has already been forwarded to assembly '*assembly*'| -|[Compiler error C3239](compiler-error-c3239.md)|'*type*': pointer to interior/pin pointer is disallowed by the common language runtime| -|[Compiler error C3240](compiler-error-c3240.md)|'*identifier*': must be a non-overloaded abstract member function of '*type*'| -|[Compiler error C3241](compiler-error-c3241.md)|'*member*': this method was not introduced by '*interface*'| -|[Compiler error C3242](compiler-error-c3242.md)|'*function*': you can only explicitly override virtual functions| -|[Compiler error C3243](compiler-error-c3243.md)|none of the overload functions were introduced by '*interface*'| -|[Compiler error C3244](compiler-error-c3244.md)|'*member*': this method was introduced by '*interface1*' not by '*interface2*'| -|Compiler error C3245|'*function*': use of a variable template requires template argument list| -|[Compiler error C3246](compiler-error-c3246.md)|'*class*': cannot inherit from '*base_class*' as it has been declared as '*inheritance*'| -|[Compiler error C3247](compiler-error-c3247.md)|'*coclass*': a coclass cannot inherit from another coclass '*base_class*'| -|[Compiler error C3248](compiler-error-c3248.md)|Obsolete. '*function*': function declared as 'sealed' cannot be overridden by '*function*'| -|Compiler error C3249|illegal statement or sub-expression for '`constexpr`' function| -|Compiler error C3250|'*declaration*': declaration is not allowed in '`constexpr`' function body| -|[Compiler error C3251](compiler-error-c3251.md)|cannot invoke base class method on a value type instance| -|[Compiler error C3252](compiler-error-c3252.md)|'*function*': cannot reduce accessibility of a virtual method in a managed/WinRT type| -|[Compiler error C3253](compiler-error-c3253.md)|'*function*': error with explicit override| -|[Compiler error C3254](compiler-error-c3254.md)|'*function*': class contains explicit override '*function*' but does not derive from an interface that contains the function declaration| -|[Compiler error C3255](compiler-error-c3255.md)|'*type*': cannot dynamically allocate this value type object on native heap| -|Compiler error C3256|'*function*': variable use does not produce a constant expression| -|Compiler error C3257|Obsolete.| -|Compiler error C3258|Obsolete.| -|Compiler error C3259|'`constexpr`' functions can only have one `return` statement| -|Compiler error C3260|'*token*': skipping unexpected token(s) before lambda body| -|Compiler error C3261|a function returning a managed/WinRT array must have array brackets at the end of the declaration: '*identifier*(...) \[]'| -|[Compiler error C3262](compiler-error-c3262.md)|invalid array indexing: *number* dimension(s) specified for *number*-dimensional '*type*'| -|Compiler error C3263|Obsolete.| -|[Compiler error C3264](compiler-error-c3264.md)|'*identifier*': a class-constructor cannot have a return type| -|[Compiler error C3265](compiler-error-c3265.md)|cannot declare a managed '*managed_construct*' in an unmanaged '*unmanaged_construct*'| -|[Compiler error C3266](compiler-error-c3266.md)|'*function*': a class-constructor must have a '`void`' parameter list| -|Compiler error C3267|Obsolete.| -|[Compiler error C3268](compiler-error-c3268.md)|'*function*': a generic function or a member-function of a generic class cannot have a variable parameter list| -|[Compiler error C3269](compiler-error-c3269.md)|'*function*': a member-function of a managed/WinRT type cannot be declared with '`...`'| -|[Compiler error C3270](compiler-error-c3270.md)|'*field*': the `FieldOffset` attribute can only be used in the context of `StructLayout(LayoutKind::Explicit)`| -|[Compiler error C3271](compiler-error-c3271.md)|'*field*': invalid value '*number*' for the `FieldOffset` attribute| -|[Compiler error C3272](compiler-error-c3272.md)|'*symbol*': symbol requires `FieldOffset`, as it is a member of struct/class *type_name* defined with `StructLayout(LayoutKind::Explicit)`| -|[Compiler error C3273](compiler-error-c3273.md)|'*keyword*': not allowed on C++ `try` block| -|[Compiler error C3274](compiler-error-c3274.md)|`finally`/`__finally` without matching `try`| -|[Compiler error C3275](compiler-error-c3275.md)|'*identifier*': cannot use this symbol without qualifier| -|[Compiler error C3276](compiler-error-c3276.md)|'*keyword*': jump out of `finally`/`__finally` block has undefined behavior during termination handling| -|[Compiler error C3277](compiler-error-c3277.md)|cannot define an unmanaged enum '*enumeration*' inside managed '*type*'| -|[Compiler error C3278](compiler-error-c3278.md)|direct call of interface or pure method '*function*' will fail at runtime| -|[Compiler error C3279](compiler-error-c3279.md)|partial and explicit specializations as well as explicit instantiations of class templates declared in the `cli` namespace are disallowed| -|[Compiler error C3280](compiler-error-c3280.md)|'*function*': a member-function of a managed type cannot be compiled as an unmanaged function| -|Compiler error C3281|'*function*': global operator cannot have managed/WinRT type '*type*' in signature| -|[Compiler error C3282](compiler-error-c3282.md)|generic parameter lists can only appear on managed/WinRT classes, structs, or functions| -|[Compiler error C3283](compiler-error-c3283.md)|'*interface*': an interface cannot have an instance constructor| -|[Compiler error C3284](compiler-error-c3284.md)|the constraints for generic parameter '*parameter*' of function '*declarator*' must match the constraints for generic parameter '*parameter*' of function '*declarator*'| -|[Compiler error C3285](compiler-error-c3285.md)|for each statement cannot operate on variables of type '*type*'| -|[Compiler error C3286](compiler-error-c3286.md)|'*specifier*': an iteration variable cannot have any storage-class specifiers| -|[Compiler error C3287](compiler-error-c3287.md)|the type '*type*' (return type of `GetEnumerator`) must have a suitable public `MoveNext` member function and public `Current` property| -|[Compiler error C3288](compiler-error-c3288.md)|'*type*': illegal dereference of a handle type| -|[Compiler error C3289](compiler-error-c3289.md)|'*identifier*': a trivial property cannot be indexed| -|[Compiler error C3290](compiler-error-c3290.md)|'*type*': a trivial property cannot have reference type| -|[Compiler error C3291](compiler-error-c3291.md)|'default': cannot be the name of a trivial property| -|[Compiler error C3292](compiler-error-c3292.md)|the cli namespace cannot be reopened| -|[Compiler error C3293](compiler-error-c3293.md)|'*identifier*': use '`default`' to access the default property (indexer) for class '*class*'| -|Compiler error C3294|Obsolete.| -|[Compiler error C3295](compiler-error-c3295.md)|'#pragma *specifier*' can only be used at global or namespace scope| -|[Compiler error C3296](compiler-error-c3296.md)|'*identifier*': a property with this name already exists| -|[Compiler error C3297](compiler-error-c3297.md)|' *constraint2*': cannot use ' *constraint1*' as a constraint because ' *constraint1*' has the value constraint| -|[Compiler error C3298](compiler-error-c3298.md)|' *constraint1*': cannot use ' *constraint2*' as a constraint because ' *constraint2*' has the ref constraint and ' *constraint1*' has the value constraint| -|[Compiler error C3299](compiler-error-c3299.md)|' *function*': cannot specify constraints, they are inherited from the base method| +| Error | Message | +|--|--| +| [Compiler error C3200](compiler-error-c3200.md) | '*type*': invalid template argument for template parameter '*parameter*', expected a class template | +| [Compiler error C3201](compiler-error-c3201.md) | the template parameter list for class template '*template*' does not match the template parameter list for template parameter '*parameter*' | +| [Compiler error C3202](compiler-error-c3202.md) | '*identifier*': invalid default argument, expected a class template | +| [Compiler error C3203](compiler-error-c3203.md) | '*identifier*': unspecialized class template/generic can't be used as a template/generic argument for template/generic parameter '*parameter*', expected a real type | +| [Compiler error C3204](compiler-error-c3204.md) | '*function*' cannot be called from within a `catch` block | +| [Compiler error C3205](compiler-error-c3205.md) | argument list for template template parameter '*identifier*' is missing | +| [Compiler error C3206](compiler-error-c3206.md) | '*function*': invalid template/generic argument for '*template*', missing template/generic argument list on class template/generic '*type*' | +| [Compiler error C3207](compiler-error-c3207.md) | '*function*': invalid template argument for '*parameter*', class template expected | +| [Compiler error C3208](compiler-error-c3208.md) | '*function*': template parameter list for class template '*template*' does not match template parameter list for template template parameter '*parameter*' | +| [Compiler error C3209](compiler-error-c3209.md) | '*type*': generic class must be a managed/WinRT class | +| [Compiler error C3210](compiler-error-c3210.md) | '*identifier*': access declaration can only be applied to a base class member | +| [Compiler error C3211](compiler-error-c3211.md) | '*function*': explicit specialization is using partial specialization syntax, use `template <>` instead | +| [Compiler error C3212](compiler-error-c3212.md) | '*function*': an explicit specialization of a template member must be a member of an explicit specialization | +| [Compiler error C3213](compiler-error-c3213.md) | base class '*class*' is less accessible than '*derived_class*' | +| [Compiler error C3214](compiler-error-c3214.md) | '*argument*': invalid type argument for generic parameter '*parameter*' of generic '*type*', does not meet constraint '*constraint*' | +| [Compiler error C3215](compiler-error-c3215.md) | '*constraint1*': generic type parameter already constrained by '*constraint2*' | +| [Compiler error C3216](compiler-error-c3216.md) | constraint must be a generic parameter, not '*type*' | +| [Compiler error C3217](compiler-error-c3217.md) | '*parameter*': generic parameter cannot be constrained in this declaration | +| [Compiler error C3218](compiler-error-c3218.md) | '*type*': type not allowed as a constraint | +| [Compiler error C3219](compiler-error-c3219.md) | '*parameter*': generic parameter cannot be constrained by multiple non-interfaces: '*type*' | +| Compiler error C3220 | '*interface*': interface cannot have `progid` | +| Compiler error C3221 | '*member*': multiple 'default' and 'case' attributes not allowed on a member | +| [Compiler error C3222](compiler-error-c3222.md) | '*function*': cannot declare default arguments for member functions of a managed/WinRT type or generic functions | +| [Compiler error C3223](compiler-error-c3223.md) | '*property*': you cannot apply '`typeid`' to a property | +| [Compiler error C3224](compiler-error-c3224.md) | '*type*': no overloaded generic class takes '*number*' generic type arguments | +| [Compiler error C3225](compiler-error-c3225.md) | generic type argument for '*argument*' cannot be '*type*', it must be a value type or a handle to a reference type | +| [Compiler error C3226](compiler-error-c3226.md) | A template declaration is not allowed inside a generic declaration | +| [Compiler error C3227](compiler-error-c3227.md) | '*type*': cannot use '*operator*' to allocate a generic type | +| [Compiler error C3228](compiler-error-c3228.md) | '*function*': generic type argument for '*argument*' cannot be '*type*', it must be a value type or handle type | +| [Compiler error C3229](compiler-error-c3229.md) | '*type*': indirections on a generic type parameter are not allowed | +| [Compiler error C3230](compiler-error-c3230.md) | '*function*': template type argument for '*argument*' cannot contain a generic type parameter: '*type*' | +| [Compiler error C3231](compiler-error-c3231.md) | '*type*': template type argument cannot use a generic type parameter | +| [Compiler error C3232](compiler-error-c3232.md) | '*parameter*': a generic type parameter cannot be used in a qualified name | +| [Compiler error C3233](compiler-error-c3233.md) | '*type*': generic type parameter already constrained | +| [Compiler error C3234](compiler-error-c3234.md) | a generic class may not derive from a generic type parameter | +| [Compiler error C3235](compiler-error-c3235.md) | '*specialization*': explicit or partial specialization of a generic class is not allowed | +| [Compiler error C3236](compiler-error-c3236.md) | explicit instantiation of a generic is not allowed | +| [Compiler error C3237](compiler-error-c3237.md) | '*class*': a generic class cannot be a custom attribute | +| [Compiler error C3238](compiler-error-c3238.md) | '*type*': a type with this name has already been forwarded to assembly '*assembly*' | +| [Compiler error C3239](compiler-error-c3239.md) | '*type*': pointer to interior/pin pointer is disallowed by the common language runtime | +| [Compiler error C3240](compiler-error-c3240.md) | '*identifier*': must be a non-overloaded abstract member function of '*type*' | +| [Compiler error C3241](compiler-error-c3241.md) | '*member*': this method was not introduced by '*interface*' | +| [Compiler error C3242](compiler-error-c3242.md) | '*function*': you can only explicitly override virtual functions | +| [Compiler error C3243](compiler-error-c3243.md) | none of the overload functions were introduced by '*interface*' | +| [Compiler error C3244](compiler-error-c3244.md) | '*member*': this method was introduced by '*interface1*' not by '*interface2*' | +| Compiler error C3245 | '*function*': use of a variable template requires template argument list | +| [Compiler error C3246](compiler-error-c3246.md) | '*class*': cannot inherit from '*base_class*' as it has been declared as '*inheritance*' | +| [Compiler error C3247](compiler-error-c3247.md) | '*coclass*': a coclass cannot inherit from another coclass '*base_class*' | +| [Compiler error C3248](compiler-error-c3248.md) | '*function*': function declared as '`sealed`' cannot be overridden by '*function*' | +| Compiler error C3249 | illegal statement or sub-expression for '`constexpr`' function (Obsolete in Visual Studio 2022.) | +| Compiler error C3250 | '*declaration*': declaration is not allowed in '`constexpr`' function body (Obsolete in Visual Studio 2022.) | +| [Compiler error C3251](compiler-error-c3251.md) | cannot invoke base class method on a value type instance (Obsolete in Visual Studio 2022.) | +| [Compiler error C3252](compiler-error-c3252.md) | '*function*': cannot reduce accessibility of a virtual method in a managed/WinRT type | +| [Compiler error C3253](compiler-error-c3253.md) | '*function*': error with explicit override | +| [Compiler error C3254](compiler-error-c3254.md) | '*function*': class contains explicit override '*function*' but does not derive from an interface that contains the function declaration | +| [Compiler error C3255](compiler-error-c3255.md) | '*type*': cannot dynamically allocate this value type object on native heap | +| Compiler error C3256 | '*function*': variable use does not produce a constant expression (Obsolete in Visual Studio 2022.) | +| Compiler error C3257 | Obsolete. | +| Compiler error C3258 | Obsolete. | +| Compiler error C3259 | '`constexpr`' functions can only have one `return` statement (Obsolete in Visual Studio 2022.) | +| Compiler error C3260 | '*token*': skipping unexpected token(s) before lambda body | +| Compiler error C3261 | a function returning a managed/WinRT array must have array brackets at the end of the declaration: '*identifier*(...) []' | +| [Compiler error C3262](compiler-error-c3262.md) | invalid array indexing: *number* dimension(s) specified for *number*-dimensional '*type*' | +| Compiler error C3263 | Obsolete. | +| [Compiler error C3264](compiler-error-c3264.md) | '*identifier*': a class-constructor cannot have a return type | +| [Compiler error C3265](compiler-error-c3265.md) | cannot declare a managed '*managed_construct*' in an unmanaged '*unmanaged_construct*' | +| [Compiler error C3266](compiler-error-c3266.md) | '*function*': a class-constructor must have a '`void`' parameter list | +| Compiler error C3267 | Obsolete. | +| [Compiler error C3268](compiler-error-c3268.md) | '*function*': a generic function or a member-function of a generic class cannot have a variable parameter list | +| [Compiler error C3269](compiler-error-c3269.md) | '*function*': a member-function of a managed/WinRT type cannot be declared with '`...`' | +| [Compiler error C3270](compiler-error-c3270.md) | '*field*': the `FieldOffset` attribute can only be used in the context of `StructLayout(LayoutKind::Explicit)` | +| [Compiler error C3271](compiler-error-c3271.md) | '*field*': invalid value '*number*' for the `FieldOffset` attribute | +| [Compiler error C3272](compiler-error-c3272.md) | '*symbol*': symbol requires `FieldOffset`, as it is a member of struct/class *type_name* defined with `StructLayout(LayoutKind::Explicit)` | +| [Compiler error C3273](compiler-error-c3273.md) | '*keyword*': not allowed on C++ `try` block | +| [Compiler error C3274](compiler-error-c3274.md) | `finally` / `__finally` without matching `try` | +| [Compiler error C3275](compiler-error-c3275.md) | '*identifier*': cannot use this symbol without qualifier (Obsolete in Visual Studio 2022.) | +| [Compiler error C3276](compiler-error-c3276.md) | '*keyword*': jump out of `finally`/`__finally` block has undefined behavior during termination handling | +| [Compiler error C3277](compiler-error-c3277.md) | cannot define an unmanaged enum '*enumeration*' inside managed '*type*' | +| [Compiler error C3278](compiler-error-c3278.md) | direct call of interface or pure method '*function*' will fail at runtime | +| [Compiler error C3279](compiler-error-c3279.md) | partial and explicit specializations as well as explicit instantiations of class templates declared in the `cli` namespace are disallowed | +| [Compiler error C3280](compiler-error-c3280.md) | '*function*': a member-function of a managed type cannot be compiled as an unmanaged function | +| Compiler error C3281 | '*function*': global operator cannot have managed/WinRT type '*type*' in signature | +| [Compiler error C3282](compiler-error-c3282.md) | generic parameter lists can only appear on managed/WinRT classes, structs, or functions | +| [Compiler error C3283](compiler-error-c3283.md) | '*interface*': an interface cannot have an instance constructor | +| [Compiler error C3284](compiler-error-c3284.md) | the constraints for generic parameter '*parameter*' of function '*declarator*' must match the constraints for generic parameter '*parameter*' of function '*declarator*' | +| [Compiler error C3285](compiler-error-c3285.md) | for each statement cannot operate on variables of type '*type*' | +| [Compiler error C3286](compiler-error-c3286.md) | A for-range-declaration cannot have a storage class other than '`constexpr`' | +| [Compiler error C3287](compiler-error-c3287.md) | the type '*type*' (return type of `GetEnumerator`) must have a suitable public `MoveNext` member function and public `Current` property | +| [Compiler error C3288](compiler-error-c3288.md) | '*type*': illegal dereference of a handle type | +| [Compiler error C3289](compiler-error-c3289.md) | '*identifier*': a trivial property cannot be indexed | +| [Compiler error C3290](compiler-error-c3290.md) | '*type*': a trivial property cannot have reference type | +| [Compiler error C3291](compiler-error-c3291.md) | 'default': cannot be the name of a trivial property | +| [Compiler error C3292](compiler-error-c3292.md) | the cli namespace cannot be reopened | +| [Compiler error C3293](compiler-error-c3293.md) | '*identifier*': use '`default`' to access the default property (indexer) for class '*class*' | +| Compiler error C3294 | Obsolete. | +| [Compiler error C3295](compiler-error-c3295.md) | '#pragma *specifier*' can only be used at global or namespace scope | +| [Compiler error C3296](compiler-error-c3296.md) | '*identifier*': a property with this name already exists | +| [Compiler error C3297](compiler-error-c3297.md) | ' *constraint2*': cannot use ' *constraint1*' as a constraint because ' *constraint1*' has the value constraint | +| [Compiler error C3298](compiler-error-c3298.md) | ' *constraint1*': cannot use ' *constraint2*' as a constraint because ' *constraint2*' has the ref constraint and ' *constraint1*' has the value constraint | +| [Compiler error C3299](compiler-error-c3299.md) | ' *function*': cannot specify constraints, they are inherited from the base method | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3300-through-c3399.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3300-through-c3399.md index 8c847b6e21..691f9c0e36 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3300-through-c3399.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3300-through-c3399.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C3300 Through C3399" -title: "Compiler errors C3300 Through C3399" -ms.date: "04/21/2019" +title: "Compiler errors C3300 through C3399" +ms.date: 06/01/2022 f1_keywords: ["C3300", "C3301", "C3302", "C3304", "C3305", "C3306", "C3307", "C3308", "C3310", "C3311", "C3312", "C3313", "C3314", "C3315", "C3316", "C3317", "C3318", "C3319", "C3321", "C3323", "C3324", "C3325", "C3326", "C3327", "C3328", "C3329", "C3330", "C3331", "C3332", "C3335", "C3336", "C3337", "C3338", "C3339", "C3341", "C3343", "C3344", "C3346", "C3348", "C3349", "C3355", "C3357", "C3359", "C3361", "C3362", "C3376", "C3377", "C3378"] helpviewer_keywords: ["C3300", "C3301", "C3302", "C3304", "C3305", "C3306", "C3307", "C3308", "C3310", "C3311", "C3312", "C3313", "C3314", "C3315", "C3316", "C3317", "C3318", "C3319", "C3321", "C3323", "C3324", "C3325", "C3326", "C3327", "C3328", "C3329", "C3330", "C3331", "C3332", "C3335", "C3336", "C3337", "C3338", "C3339", "C3341", "C3343", "C3344", "C3346", "C3348", "C3349", "C3355", "C3357", "C3359", "C3361", "C3362", "C3376", "C3377", "C3378"] -ms.assetid: 190b7d29-ffe6-4261-921d-140da1935d00 --- # Compiler errors C3300 Through C3399 @@ -14,108 +13,110 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|Compiler error C3300|'*symbol*': improper format for IDL '*value*'| -|Compiler error C3301|'*coclass*': coclass cannot be a '*symbol*' interface| -|Compiler error C3302|'*identifier*': identifier has more than *number* characters| -|[Compiler error C3303](compiler-error-c3303.md)|'*attribute*': attribute can only be used on '*type*'| -|Compiler error C3304|Obsolete.| -|Compiler error C3305|Obsolete.| -|Compiler error C3306|'*template*': unnamed class template/generic is not allowed| -|Compiler error C3307|'*module*': unable to create IDL module| -|Compiler error C3308|' *function*': direct call through imported class is not supported| -|[Compiler error C3309](compiler-error-c3309.md)|'*macro*/*keyword*': module name cannot be a macro or a keyword| -|Compiler error C3310|'*identifier*': module name conflict| -|Compiler error C3311|module attribute must be defined at global scope| -|Compiler error C3312|no callable '*identifier*' function found for type '*type*'| -|Compiler error C3313|'*identifier*': variable cannot have the type '*type*'| -|Compiler error C3314|'*symbol*': not a supported IDL module type| -|Compiler error C3315|' *function*': must be a member function| -|Compiler error C3316|'*type*': an array of unknown size cannot be used in a range-based for statement| -|Compiler error C3317|'*identifier*': an overload function cannot be used as the expression in a range-based for statement| -|Compiler error C3318|'*type*': an array cannot have an element type that contains 'auto'| -|Compiler error C3319|Obsolete.| -|[Compiler error C3320](compiler-error-c3320.md)|'*type*': type cannot have the same name as the module 'name' property| -|Compiler error C3321|an initializer list is unexpected in this context| -|[Compiler error C3322](compiler-error-c3322.md)|'*property*': is not a valid property for attribute '*attribute*'| -|Compiler error C3323|'alignas' and '__declspec(align)' are not allowed on function declarations| -|Compiler error C3324|'*property*': property occurs more than once in attribute '*attribute*'| -|Compiler error C3325|'*attribute*': attribute has too many arguments| -|Compiler error C3326|'*value*': is not a valid value for property '*property*' of attribute '*attribute*'| -|Compiler error C3327|'*property*': must specify value for property of attribute '*attribute*'| -|Compiler error C3328|'*attribute*': attribute does not have enough arguments| -|Compiler error C3329|syntax error: expected '*token1*' not '*token2*'| -|Compiler error C3330|' *function*': a function cannot return an array '*type*'| -|Compiler error C3331|'*identifier*': attributes on parameters are only allowed on COM interfaces and coclasses| -|Compiler error C3332|'*property*': grammar inconsistent, property '*property*' is both required and has a default| -|[Compiler error C3333](compiler-error-c3333.md)|'*library*': cannot #import corrupt type library| -|[Compiler error C3334](compiler-error-c3334.md)|cannot #import corrupt type library| -|Compiler error C3335|'*identifier*': There can be at most one default interface for a coclass '*class*'| -|Compiler error C3336|This operation must be performed at class scope| -|Compiler error C3337|'*identifier*': defaultvtable must be an event source for a coclass '*class*'| -|Compiler error C3338|'*identifier*': There can be at most one default interface that is also an event source for a coclass '*class*'| -|Compiler error C3339|template template parameter requires either 'class' or 'typename' after the parameter list| -|[Compiler error C3340](compiler-error-c3340.md)|'*identifier*': interface cannot be both 'restricted' and 'default' in coclass '*class*'| -|Compiler error C3341|'*interface*': a defaultvtable interface must be either 'dual' or 'custom'| -|[Compiler error C3342](compiler-error-c3342.md)|'*identifier*': ambiguous attribute| -|Compiler error C3343|'*class*::*name*': attribute identifier has too many characters| -|Compiler error C3344|you cannot define an explicit specialization nor a partial specialization of '*symbol*'| -|[Compiler error C3345](compiler-error-c3345.md)|'*name*': invalid identifier for module name| -|Compiler error C3346|exported declaration at non-namespace scope| -|[Compiler error C3347](compiler-error-c3347.md)|'*argument*': required argument is not specified in attribute *attribute-name*| -|Compiler error C3348|exported templates are not part of the current C++ standards| -|Compiler error C3349|'*class*::*member*': multicast attribute has already been implemented by provider *provider*| -|[Compiler error C3350](compiler-error-c3350.md)|' *function*': a delegate constructor expects *number* argument(s)| -|[Compiler error C3351](compiler-error-c3351.md)|' *function*': if you pass a NULL object instance to a delegate constructor you must also pass the address of a static member function| -|[Compiler error C3352](compiler-error-c3352.md)|'*function*': the specified function does not match the delegate type '*type*'| -|[Compiler error C3353](compiler-error-c3353.md)|'*identifier*': a delegate can only be created from a global function or a member function of a managed/WinRT type| -|[Compiler error C3354](compiler-error-c3354.md)|'*identifier*': the function used to create a delegate cannot have return type '*type*'| -|Compiler error C3355|'*class*::*member*': multicast attribute listens to provider '*provider1*', but is implemented by provider '*provider2*'| -|[Compiler error C3356](compiler-error-c3356.md)|'*identifier*': cannot call a multicast attribute with a fully qualified name| -|Compiler error C3357|'*attribute*': attribute is ambiguous, must use fully qualified name| -|[Compiler error C3358](compiler-error-c3358.md)|'*symbol*': symbol not found| -|Compiler error C3359|'*specialization*': cannot specialize template| -|[Compiler error C3360](compiler-error-c3360.md)|'*string*': cannot create *name*| -|Compiler error C3361|there is no context in which to *action*| -|Compiler error C3362|'*class*::*member*': multicast attribute has not been implemented| -|[Compiler error C3363](compiler-error-c3363.md)|'*identifier*': 'typeid' can only be applied to a type| -|[Compiler error C3364](compiler-error-c3364.md)|' *function*': invalid argument for delegate constructor; delegate target needs to be a pointer to a member function| -|[Compiler error C3365](compiler-error-c3365.md)|operator '*operator*': differing operands of type '*type*' and '*type*'| -|[Compiler error C3366](compiler-error-c3366.md)|'*member*': static data members of managed/WinRT types must be defined within the class definition| -|[Compiler error C3367](compiler-error-c3367.md)|' *function*': cannot use static function to create an unbound delegate| -|[Compiler error C3368](compiler-error-c3368.md)|'*declarator*': invalid calling convention for IDL| -|[Compiler error C3369](compiler-error-c3369.md)|'*module*': idl_module already defined| -|[Compiler error C3370](compiler-error-c3370.md)|'*module*': idl_module not yet defined| -|[Compiler error C3371](compiler-error-c3371.md)|'idl_module': only the 'name' property is allowed here| -|[Compiler error C3372](compiler-error-c3372.md)|must specify at least 1 interface for attribute '*attribute*' on a coclass| -|[Compiler error C3373](compiler-error-c3373.md)|attribute '*attribute*' takes no arguments except on a coclass| -|[Compiler error C3374](compiler-error-c3374.md)|can't take address of ' *function*' unless creating delegate instance| -|[Compiler error C3375](compiler-error-c3375.md)|'*function*': ambiguous delegate function| -|Compiler error C3376|'*template*': only static data member templates are allowed| -|Compiler error C3377|'decltype(auto)' is not allowed in a new-expression| -|Compiler error C3378|a declaration can be exported only from a module interface unit| -|[Compiler error C3379](compiler-error-c3379.md)|'*class*': a nested class cannot have an assembly access specifier as part of its declaration| -|[Compiler error C3380](compiler-error-c3380.md)|'*specifier*': invalid assembly access specifier - only 'public' or 'private' are allowed| -|[Compiler error C3381](compiler-error-c3381.md)|'*specifier*': assembly access specifiers are only available in code compiled with a /clr option| -|[Compiler error C3382](compiler-error-c3382.md)|'sizeof' is not supported with /clr:safe| -|[Compiler error C3383](compiler-error-c3383.md)|'operator new' is not supported with /clr:safe| -|[Compiler error C3384](compiler-error-c3384.md)|'*type*': the value constraint and the ref constraint are mutually exclusive| -|[Compiler error C3385](compiler-error-c3385.md)|' *function*': a function that has a DllImport custom attribute cannot return an instance of a class| -|[Compiler error C3386](compiler-error-c3386.md)|'*type*': __declspec(dllexport)/__declspec(dllimport) cannot be applied to a managed/WinRT type| -|[Compiler error C3387](compiler-error-c3387.md)|'*member*': __declspec(dllexport)/__declspec(dllimport) cannot be applied to a member of a managed/WinRT type| -|[Compiler error C3388](compiler-error-c3388.md)|'*token*': not allowed as a constraint, assuming '*value*' to continue parsing| -|[Compiler error C3389](compiler-error-c3389.md)|__declspec(*specifier*) cannot be used with /clr:pure or /clr:safe| -|[Compiler error C3390](compiler-error-c3390.md)|'*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must be a reference type| -|[Compiler error C3391](compiler-error-c3391.md)|'*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must be a non-nullable value type| -|[Compiler error C3392](compiler-error-c3392.md)|'*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must have a public parameterless constructor| -|[Compiler error C3393](compiler-error-c3393.md)|syntax error in constraint clause: '*identifier*' is not a type| -|[Compiler error C3394](compiler-error-c3394.md)|syntax error in constraint clause: found '*symbol*' expected a type| -|[Compiler error C3395](compiler-error-c3395.md)|' *function*': __declspec(dllexport) cannot be applied to a function with the __clrcall calling convention| -|[Compiler error C3396](compiler-error-c3396.md)|'*class*.*member*': custom attribute not found in '*namespace*'| -|[Compiler error C3397](compiler-error-c3397.md)|Aggregate initialization is not allowed in default arguments| -|[Compiler error C3398](compiler-error-c3398.md)|'*operator*': cannot convert from '*type*' to '*type*'. Source expression must be a function symbol| -|[Compiler error C3399](compiler-error-c3399.md)|'*type*': cannot provide arguments when creating an instance of a generic parameter| +| Error | Message | +|--|--| +| Compiler error C3300 | '*symbol*': improper format for IDL '*value*' | +| Compiler error C3301 | '*coclass*': `coclass` cannot be a '*symbol*' interface | +| Compiler error C3302 | '*identifier*': identifier has more than *number* characters | +| [Compiler error C3303](compiler-error-c3303.md) | '*attribute*': attribute can only be used on '*type*' | +| Compiler error C3304 | Obsolete. | +| Compiler error C3305 | Obsolete. | +| Compiler error C3306 | '*template*': unnamed class template/generic is not allowed | +| Compiler error C3307 | '*module*': unable to create IDL module | +| Compiler error C3308 | '*function*': direct call through imported class is not supported | +| [Compiler error C3309](compiler-error-c3309.md) | '*macro*/*keyword*': module name cannot be a macro or a keyword | +| Compiler error C3310 | '*identifier*': module name conflict | +| Compiler error C3311 | module attribute must be defined at global scope | +| Compiler error C3312 | no callable '*identifier*' function found for type '*type*' | +| Compiler error C3313 | '*identifier*': variable cannot have the type '*type*' | +| Compiler error C3314 | '*symbol*': not a supported IDL module type | +| Compiler error C3315 | '*function*': must be a member function | +| Compiler error C3316 | '*type*': an array of unknown size cannot be used in a range-based for statement | +| Compiler error C3317 | '*identifier*': an overload function cannot be used as the expression in a range-based for statement | +| Compiler error C33181 | '*type*': an array cannot have an element type that contains '`auto`'| +| Compiler error C3319 | Obsolete. | +| [Compiler error C3320](compiler-error-c3320.md) | '*type*': type cannot have the same name as the module 'name' property | +| Compiler error C3321 | an initializer list is unexpected in this context | +| [Compiler error C3322](compiler-error-c3322.md) | '*property*': is not a valid property for attribute '*attribute*' | +| Compiler error C3323 | 'alignas' and '__declspec(align)' are not allowed on function declarations | +| Compiler error C3324 | '*property*': property occurs more than once in attribute '*attribute*' | +| Compiler error C3325 | '*attribute*': attribute has too many arguments | +| Compiler error C3326 | '*value*': is not a valid value for property '*property*' of attribute '*attribute*' | +| Compiler error C3327 | '*property*': must specify value for property of attribute '*attribute*' | +| Compiler error C3328 | '*attribute*': attribute does not have enough arguments | +| Compiler error C3329 | syntax error: expected '*token1*' not '*token2*' | +| Compiler error C3330 | ' *function*': a function cannot return an array '*type*' | +| Compiler error C3331 | '*identifier*': attributes on parameters are only allowed on COM interfaces and coclasses | +| Compiler error C3332 | '*property*': grammar inconsistent, property '*property*' is both required and has a default | +| [Compiler error C3333](compiler-error-c3333.md) | '*library*': cannot #import corrupt type library | +| [Compiler error C3334](compiler-error-c3334.md) | cannot #import corrupt type library | +| Compiler error C3335 | '*identifier*': There can be at most one default interface for a coclass '*class*' | +| Compiler error C3336 | This operation must be performed at class scope | +| Compiler error C3337 | '*identifier*': defaultvtable must be an event source for a coclass '*class*' | +| Compiler error C3338 | '*identifier*': There can be at most one default interface that is also an event source for a coclass '*class*' | +| Compiler error C3339 | template template parameter requires either '`class`' or '`typename`' after the parameter list | +| [Compiler error C3340](compiler-error-c3340.md) | '*identifier*': interface cannot be both 'restricted' and 'default' in coclass '*class*' | +| Compiler error C3341 | '*interface*': a defaultvtable interface must be either 'dual' or 'custom' | +| [Compiler error C3342](compiler-error-c3342.md) | '*identifier*': ambiguous attribute | +| Compiler error C3343 | '*class*::*name*': attribute identifier has too many characters | +| Compiler error C3344 | you cannot define an explicit specialization nor a partial specialization of '*symbol*' | +| [Compiler error C3345](compiler-error-c3345.md) | '*name*': invalid identifier for module name | +| Compiler error C3346 | exported declaration at non-namespace scope | +| [Compiler error C3347](compiler-error-c3347.md) | '*argument*': required argument is not specified in attribute *attribute-name* | +| Compiler error C3348 | exported templates are not part of the current C++ standards | +| Compiler error C3349 | '*class*::*member*': multicast attribute has already been implemented by provider *provider-name* | +| [Compiler error C3350](compiler-error-c3350.md) | '*function*': a delegate constructor expects *number* argument(s) | +| [Compiler error C3351](compiler-error-c3351.md) | '*function*': if you pass a NULL object instance to a delegate constructor you must also pass the address of a static member function | +| [Compiler error C3352](compiler-error-c3352.md) | '*function*': the specified function does not match the delegate type '*type*' | +| [Compiler error C3353](compiler-error-c3353.md) | '*identifier*': a delegate can only be created from a global function or a member function of a managed/WinRT type | +| [Compiler error C3354](compiler-error-c3354.md) | '*identifier*': the function used to create a delegate cannot have return type '*type*' | +| Compiler error C3355 | '*class*::*member*': multicast attribute listens to provider '*provider1*', but is implemented by provider '*provider2*' | +| [Compiler error C3356](compiler-error-c3356.md) | '*identifier*': cannot call a multicast attribute with a fully qualified name | +| Compiler error C3357 | '*attribute*': attribute is ambiguous, must use fully qualified name | +| [Compiler error C3358](compiler-error-c3358.md) | '*symbol*': symbol not found | +| Compiler error C3359 | '*specialization*': cannot specialize template | +| [Compiler error C3360](compiler-error-c3360.md) | '*string*': cannot create *name* | +| Compiler error C3361 | there is no context in which to *action* | +| Compiler error C3362 | '*class*::*member*': multicast attribute has not been implemented | +| [Compiler error C3363](compiler-error-c3363.md) | '*identifier*': 'typeid' can only be applied to a type | +| [Compiler error C3364](compiler-error-c3364.md) | ' *function*': invalid argument for delegate constructor; delegate target needs to be a pointer to a member function | +| [Compiler error C3365](compiler-error-c3365.md) | operator '*operator*': differing operands of type '*type*' and '*type*' | +| [Compiler error C3366](compiler-error-c3366.md) | '*member*': static data members of managed/WinRT types must be defined within the class definition | +| [Compiler error C3367](compiler-error-c3367.md) | ' *function*': cannot use static function to create an unbound delegate | +| [Compiler error C3368](compiler-error-c3368.md) | '*declarator*': invalid calling convention for IDL | +| [Compiler error C3369](compiler-error-c3369.md) | '*module*': idl_module already defined | +| [Compiler error C3370](compiler-error-c3370.md) | '*module*': idl_module not yet defined | +| [Compiler error C3371](compiler-error-c3371.md) | 'idl_module': only the 'name' property is allowed here | +| [Compiler error C3372](compiler-error-c3372.md) | must specify at least 1 interface for attribute '*attribute*' on a coclass | +| [Compiler error C3373](compiler-error-c3373.md) | attribute '*attribute*' takes no arguments except on a coclass | +| [Compiler error C3374](compiler-error-c3374.md) | can't take address of ' *function*' unless creating delegate instance | +| [Compiler error C3375](compiler-error-c3375.md) | '*function*': ambiguous delegate function | +| Compiler error C3376 | '*template*': only static data member templates are allowed | +| Compiler error C3377 | 'decltype(auto)' is not allowed in a new-expression (Obsolete in Visual Studio 2022.) | +| Compiler error C3378 | a declaration can be exported only from a module interface unit | +| [Compiler error C3379](compiler-error-c3379.md) | '*class*': a nested class cannot have an assembly access specifier as part of its declaration | +| [Compiler error C3380](compiler-error-c3380.md) | '*specifier*': invalid assembly access specifier - only 'public' or 'private' are allowed | +| [Compiler error C3381](compiler-error-c3381.md) | '*specifier*': assembly access specifiers are only available in code compiled with a /clr option | +| [Compiler error C3382](compiler-error-c3382.md) | 'sizeof' is not supported with /clr:safe | +| [Compiler error C3383](compiler-error-c3383.md) | 'operator new' is not supported with /clr:safe | +| [Compiler error C3384](compiler-error-c3384.md) | '*type*': the value constraint and the ref constraint are mutually exclusive | +| [Compiler error C3385](compiler-error-c3385.md) | ' *function*': a function that has a DllImport custom attribute cannot return an instance of a class | +| [Compiler error C3386](compiler-error-c3386.md) | '*type*': __declspec(dllexport)/__declspec(dllimport) cannot be applied to a managed/WinRT type | +| [Compiler error C3387](compiler-error-c3387.md) | '*member*': __declspec(dllexport)/__declspec(dllimport) cannot be applied to a member of a managed/WinRT type | +| [Compiler error C3388](compiler-error-c3388.md) | '*token*': not allowed as a constraint, assuming '*value*' to continue parsing | +| [Compiler error C3389](compiler-error-c3389.md) | __declspec(*specifier*) cannot be used with /clr:pure or /clr:safe | +| [Compiler error C3390](compiler-error-c3390.md) | '*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must be a reference type | +| [Compiler error C3391](compiler-error-c3391.md) | '*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must be a non-nullable value type | +| [Compiler error C3392](compiler-error-c3392.md) | '*type*': invalid type argument for generic parameter '*parameter*' of generic '*generic_type*', must have a public parameterless constructor | +| [Compiler error C3393](compiler-error-c3393.md) | syntax error in constraint clause: '*identifier*' is not a type | +| [Compiler error C3394](compiler-error-c3394.md) | syntax error in constraint clause: found '*symbol*' expected a type | +| [Compiler error C3395](compiler-error-c3395.md) | ' *function*': __declspec(dllexport) cannot be applied to a function with the __clrcall calling convention | +| [Compiler error C3396](compiler-error-c3396.md) | '*class*.*member*': custom attribute not found in '*namespace*' | +| [Compiler error C3397](compiler-error-c3397.md) | Aggregate initialization is not allowed in default arguments | +| [Compiler error C3398](compiler-error-c3398.md) | '*operator*': cannot convert from '*type*' to '*type*'. Source expression must be a function symbol | +| [Compiler error C3399](compiler-error-c3399.md) | '*type*': cannot provide arguments when creating an instance of a generic parameter | + +1-No longer emitted in Visual Studio 2022 version 17.11 ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3400-through-c3499.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3400-through-c3499.md index 45e9a8a138..688a5b80ca 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3400-through-c3499.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3400-through-c3499.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler errors C3400 Through C3499" title: "Compiler errors C3400 Through C3499" -ms.date: "04/21/2019" -f1_keywords: ["C3401", "C3402", "C3403", "C3404", "C3405", "C3406", "C3407", "C3410", "C3411", "C3416", "C3419", "C3422", "C3424", "C3425", "C3426", "C3427", "C3428", "C3429", "C3430", "C3431", "C3432", "C3433", "C3434", "C3435", "C3436", "C3437", "C3438", "C3439", "C3440", "C3441", "C3442", "C3443", "C3444", "C3471", "C3472", "C3473", "C3474", "C3475", "C3476", "C3477", "C3478", "C3479", "C3486", "C3494", "C3497"] -helpviewer_keywords: ["C3401", "C3402", "C3403", "C3404", "C3405", "C3406", "C3407", "C3410", "C3411", "C3416", "C3419", "C3422", "C3424", "C3425", "C3426", "C3427", "C3428", "C3429", "C3430", "C3431", "C3432", "C3433", "C3434", "C3435", "C3436", "C3437", "C3438", "C3439", "C3440", "C3441", "C3442", "C3443", "C3444", "C3471", "C3472", "C3473", "C3474", "C3475", "C3476", "C3477", "C3478", "C3479", "C3486", "C3494", "C3497"] -ms.assetid: a5651dfb-c402-4e01-b3ae-28f371e51d6a +ms.date: 06/01/2022 +f1_keywords: ["C3401", "C3402", "C3403", "C3404", "C3405", "C3406", "C3407", "C3410", "C3411", "C3416", "C3419", "C3422", "C3423", "C3424", "C3425", "C3426", "C3427", "C3428", "C3429", "C3430", "C3431", "C3432", "C3433", "C3434", "C3435", "C3436", "C3437", "C3438", "C3439", "C3440", "C3441", "C3442", "C3443", "C3444", "C3447", "C3448", "C3449", "C3471", "C3472", "C3473", "C3474", "C3475", "C3476", "C3477", "C3478", "C3479", "C3486", "C3494", "C3497"] +helpviewer_keywords: ["C3401", "C3402", "C3403", "C3404", "C3405", "C3406", "C3407", "C3410", "C3411", "C3416", "C3419", "C3422", "C3423", "C3424", "C3425", "C3426", "C3427", "C3428", "C3429", "C3430", "C3431", "C3432", "C3433", "C3434", "C3435", "C3436", "C3437", "C3438", "C3439", "C3440", "C3441", "C3442", "C3443", "C3444", "C3447", "C3448", "C3449", "C3471", "C3472", "C3473", "C3474", "C3475", "C3476", "C3477", "C3478", "C3479", "C3486", "C3494", "C3497"] --- # Compiler errors C3400 Through C3499 @@ -14,108 +13,108 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Compiler error C3400](compiler-error-c3400.md)|circular constraint dependency involving '*constraint1*' and '*constraint2*'| -|Compiler error C3401|'*specifier*': invalid assembly access specifier - only 'private' is allowed on class templates| -|Compiler error C3402|'*function*': cannot resolve overload except in the current scope| -|Compiler error C3403|thread_local cannot be used with /clr:pure or /clr:safe| -|Compiler error C3404|'*construct*': unexpected syntax error| -|Compiler error C3405|'*function*': cannot resolve overload without complete descriptor| -|Compiler error C3406|'*keyword*': cannot be used in an elaborated type specifier| -|Compiler error C3407|'*type*' cannot be used in this context| -|[Compiler error C3408](compiler-error-c3408.md)|'*attribute*': attribute is not allowed on template definitions| -|[Compiler error C3409](compiler-error-c3409.md)|empty attribute block is not allowed| -|Compiler error C3410|'*identifier*': the type of the explicit instantiation '*type*' does not match the type of the variable template '*type*'| -|Compiler error C3411|'*type*' is not valid as the size of an array as it is not an integer type| -|[Compiler error C3412](compiler-error-c3412.md)|'*specialization*': cannot specialize template in current scope| -|[Compiler error C3413](compiler-error-c3413.md)|'*template*': invalid explicit instantiation| -|[Compiler error C3414](compiler-error-c3414.md)|'*function*': imported member function can't be defined| -|[Compiler error C3415](compiler-error-c3415.md)|multiple '*section*' sections found with different attributes ('0x*value*')| -|Compiler error C3416|Obsolete.| -|[Compiler error C3417](compiler-error-c3417.md)|'*declarator*': value types cannot contain user-defined special member functions| -|[Compiler error C3418](compiler-error-c3418.md)|access specifier '*specifier*' is not supported| -|Compiler error C3419|Obsolete.| -|[Compiler error C3420](compiler-error-c3420.md)|'*function*': a finalizer cannot be virtual| -|[Compiler error C3421](compiler-error-c3421.md)|'*function*': you cannot call the finalizer for this class as it is either inaccessible or it does not exist| -|Compiler error C3422|'*declaration*': mismatched types '*type*' and '*type*'| -|Compiler error C3423|Obsolete.| -|Compiler error C3424|'*type*': a function-style cast to an array type is not allowed| -|Compiler error C3425|cannot throw pointer to object of incomplete type '*type*'| -|Compiler error C3426|cannot throw object of incomplete type '*type*'| -|Compiler error C3427|'*context*': '*keyword*' cannot be used with layout_version(*number*)| -|Compiler error C3428|'*context*': '*keyword*' can only be applied to class declarations or definitions| -|Compiler error C3429|'*context*': '*keyword*' cannot be applied to a union| -|Compiler error C3430|a scoped enumeration must have a name| -|Compiler error C3431|'*identifier*': *type1* cannot be redeclared as *type2*| -|Compiler error C3432|'*identifier*': a forward declaration of an unscoped enumeration must have an underlying type| -|Compiler error C3433|'*identifier*': all declarations of an enumeration must have the same underlying type, was '*type1*' now '*type2*'| -|Compiler error C3434|'*context*': enumerator value '*number*' cannot be represented as '*type*', value is '*number*'| -|Compiler error C3435|character set '*name*' is not supported| -|Compiler error C3436|#pragma setlocale is not supported when /source-charset, /execution-charset, or /utf-8 has been specified| -|Compiler error C3437|#pragma execution_character_set is not supported when /source-charset, /execution-charset, or /utf-8 has been specified| -|Compiler error C3438|'*context*': '*value*' cannot be applied to a managed/WinRT class| -|Compiler error C3439|layout_version(*number*): invalid version number| -|Compiler error C3440|'*declaration*': layout_version(*number*) incompatible with a prior declaration| -|Compiler error C3441|'*declaration*': '*keyword*' cannot be applied after the class has been defined| -|Compiler error C3442|Initializing multiple members of union: '*member1*' and '*member2*'| -|Compiler error C3443|The default member initializer for '*class*' is recursive| -|Compiler error C3444|Empty aggregate class '*class*' must be initialized with '{}'| -|[Compiler error C3445](compiler-error-c3445.md)|copy-list-initialization of '*type*' cannot use an explicit constructor| -|[Compiler error C3446](compiler-error-c3446.md)|'*class*': a default member initializer is not allowed for a member of a value class| -|Compiler error C3447|Obsolete.| -|Compiler error C3448|Obsolete.| -|Compiler error C3449|Obsolete.| -|[Compiler error C3450](compiler-error-c3450.md)|'*type*': not an attribute; cannot specify [System::AttributeUsageAttribute]/[Windows::Foundation::Metadata::AttributeUsageAttribute]| -|[Compiler error C3451](compiler-error-c3451.md)|'*attribute*': cannot apply unmanaged attribute to '*type*'| -|[Compiler error C3452](compiler-error-c3452.md)|list argument member not constant| -|[Compiler error C3453](compiler-error-c3453.md)|'*attribute*': attribute not applied because qualifier '*qualifier*' did not match| -|[Compiler error C3454](compiler-error-c3454.md)|[attribute] not allowed on class declaration| -|[Compiler error C3455](compiler-error-c3455.md)|'*attribute*': none of the attribute constructors matched the arguments| -|[Compiler error C3456](compiler-error-c3456.md)|[source\_annotation_attribute] not allowed on managed/WinRT class declaration| -|[Compiler error C3457](compiler-error-c3457.md)|'*attribute*': attribute does not support unnamed arguments| -|[Compiler error C3458](compiler-error-c3458.md)|'[*attribute*]': attribute '[*attribute*]' already specified for '*identifier*'| -|[Compiler error C3459](compiler-error-c3459.md)|'[*attribute*]': attribute allowed only on class indexer (default indexed property)| -|[Compiler error C3460](compiler-error-c3460.md)|'*type*': only a user-defined type can be forwarded| -|[Compiler error C3461](compiler-error-c3461.md)|'*type*': only a managed/WinRT type can be forwarded| -|[Compiler error C3462](compiler-error-c3462.md)|'*type*': only an imported type can be forwarded| -|[Compiler error C3463](compiler-error-c3463.md)|'*type*': type not allowed in attribute 'implements'| -|[Compiler error C3464](compiler-error-c3464.md)|'*type*' a nested type cannot be forwarded| -|[Compiler error C3465](compiler-error-c3465.md)|to use type '*type*' you must reference the assembly '*assembly*'| -|[Compiler error C3466](compiler-error-c3466.md)|'*type*': a specialization of a generic class cannot be forwarded| -|[Compiler error C3467](compiler-error-c3467.md)|'*type*': this type has already been forwarded| -|[Compiler error C3468](compiler-error-c3468.md)|'*type*': you can only forward a type to an assembly: '*identifier*' is not an assembly| -|[Compiler error C3469](compiler-error-c3469.md)|'*type*': a generic class cannot be forwarded| -|[Compiler error C3470](compiler-error-c3470.md)|'*class*': a class cannot have both an indexer (default indexed property) and an operator[]| -|Compiler error C3471|new module name *name* (set on command line) conflicts with previous name *name*| -|Compiler error C3472|new output file name *filename* (set on command line) conflicts with previous file name *filename*| -|Compiler error C3473|no output pathname or module name specified.| -|Compiler error C3474|could not open output file '*filename*'| -|Compiler error C3475|syntax error in input file '*filename*'| -|Compiler error C3476|could not open file '*filename*' for input| -|Compiler error C3477|a lambda cannot appear in an unevaluated context| -|Compiler error C3478|'*identifier*': an array cannot be captured by copy| -|Compiler error C3479|SAL annotations on lambdas are not supported| -|[Compiler error C3480](compiler-error-c3480.md)|'*variable*': a lambda capture variable must be from an enclosing function scope| -|[Compiler error C3481](compiler-error-c3481.md)|'*identifier*': lambda capture variable not found| -|[Compiler error C3482](compiler-error-c3482.md)|'this' can only be used as a lambda capture within a non-static member function| -|[Compiler error C3483](compiler-error-c3483.md)|'*identifier*' is already part of the lambda capture list| -|[Compiler error C3484](compiler-error-c3484.md)|syntax error: expected '->' before the return type| -|[Compiler error C3485](compiler-error-c3485.md)|a lambda definition cannot have any cv-qualifiers| -|Compiler error C3486|Obsolete.| -|[Compiler error C3487](compiler-error-c3487.md)|'*type*': all return expressions must deduce to the same type: previously it was '*type*'| -|[Compiler error C3488](compiler-error-c3488.md)|'&*identifier*' is not allowed when the default capture mode is by-reference| -|[Compiler error C3489](compiler-error-c3489.md)|'&*identifier*' is required when the default capture mode is by copy| -|[Compiler error C3490](compiler-error-c3490.md)|'*identifier*' cannot be modified because it is being accessed through a const object| -|[Compiler error C3491](compiler-error-c3491.md)|'*identifier*': a by copy capture cannot be modified in a non-mutable lambda| -|[Compiler error C3492](compiler-error-c3492.md)|'*identifier*': you cannot capture a member of an anonymous union| -|[Compiler error C3493](compiler-error-c3493.md)|'*identifier*' cannot be implicitly captured because no default capture mode has been specified| -|Compiler error C3494|'this' cannot be explicitly captured because an enclosing capture mode does not allow it| -|[Compiler error C3495](compiler-error-c3495.md)|'*identifier*': identifier in capture must be a variable with automatic storage duration declared in the reaching scope of the lambda| -|[Compiler error C3496](compiler-error-c3496.md)|'this' is always captured by value: '&' ignored| -|Compiler error C3497|you cannot construct an instance of a lambda| -|[Compiler error C3498](compiler-error-c3498.md)|'*identifier*': you cannot capture a variable that has a managed/WinRT type| -|[Compiler error C3499](compiler-error-c3499.md)|a lambda that has been specified to have a void return type cannot return a value| +| Error | Message | +|--|--| +| [Compiler error C3400](compiler-error-c3400.md) | circular constraint dependency involving '*constraint1*' and '*constraint2*' | +| Compiler error C3401 | '*specifier*': invalid assembly access specifier - only 'private' is allowed on class templates | +| Compiler error C3402 | '*function*': cannot resolve overload except in the current scope | +| Compiler error C3403 | thread_local cannot be used with /clr:pure or /clr:safe | +| Compiler error C3404 | '*construct*': unexpected syntax error | +| Compiler error C3405 | '*function*': cannot resolve overload without complete descriptor | +| Compiler error C3406 | '*keyword*': cannot be used in an elaborated type specifier | +| Compiler error C3407 | '*type*' cannot be used in this context | +| [Compiler error C3408](compiler-error-c3408.md) | '*attribute*': attribute is not allowed on template definitions | +| [Compiler error C3409](compiler-error-c3409.md) | empty attribute block is not allowed | +| Compiler error C3410 | '*identifier*': the type of the explicit instantiation '*type*' does not match the type of the variable template '*type*' | +| Compiler error C3411 | '*type*' is not valid as the size of an array as it is not an integer type | +| [Compiler error C3412](compiler-error-c3412.md) | '*specialization*': cannot specialize template in current scope | +| [Compiler error C3413](compiler-error-c3413.md) | '*template*': invalid explicit instantiation | +| [Compiler error C3414](compiler-error-c3414.md) | '*function*': imported member function can't be defined | +| [Compiler error C3415](compiler-error-c3415.md) | multiple '*section*' sections found with different attributes ('0x*value*') | +| Compiler error C3416 | Obsolete. | +| [Compiler error C3417](compiler-error-c3417.md) | '*declarator*': value types cannot contain user-defined special member functions | +| [Compiler error C3418](compiler-error-c3418.md) | access specifier '*specifier*' is not supported | +| Compiler error C3419 | Obsolete. | +| [Compiler error C3420](compiler-error-c3420.md) | '*function*': a finalizer cannot be virtual | +| [Compiler error C3421](compiler-error-c3421.md) | '*function*': you cannot call the finalizer for this class as it is either inaccessible or it does not exist | +| Compiler error C3422 | '*declaration*': mismatched types '*type*' and '*type*' | +| Compiler error C3423 | Obsolete. | +| Compiler error C3424 | '*type*': a function-style cast to an array type is not allowed | +| Compiler error C3425 | cannot throw pointer to object of incomplete type '*type*' | +| Compiler error C3426 | cannot throw object of incomplete type '*type*' | +| Compiler error C3427 | '*context*': '*keyword*' cannot be used with layout_version(*number*) | +| Compiler error C3428 | '`__declspec(`*keyword*`)`' can only be applied to class declarations or definitions | +| Compiler error C3429 | '*context*': '*keyword*' cannot be applied to a union | +| Compiler error C3430 | a scoped enumeration must have a name | +| Compiler error C3431 | '*identifier*': *type1* cannot be redeclared as *type2* | +| Compiler error C3432 | '*identifier*': a forward declaration of an unscoped enumeration must have an underlying type | +| Compiler error C3433 | '*identifier*': all declarations of an enumeration must have the same underlying type, was '*type1*' now '*type2*' | +| Compiler error C3434 | '*context*': enumerator value '*number*' cannot be represented as '*type*', value is '*number*' | +| Compiler error C3435 | character set '*name*' is not supported. | +| Compiler error C3436 | #pragma setlocale is not supported when /source-charset, /execution-charset, or /utf-8 has been specified | +| Compiler error C3437 | #pragma execution_character_set is not supported when /source-charset, /execution-charset, or /utf-8 has been specified | +| Compiler error C3438 | '*context*': '*value*' cannot be applied to a managed/WinRT class | +| Compiler error C3439 | layout_version(*number*): invalid version number | +| Compiler error C3440 | '*declaration*': layout_version(*number*) incompatible with a prior declaration | +| Compiler error C3441 | '*declaration*': '*keyword*' cannot be applied after the class has been defined | +| Compiler error C3442 | Initializing multiple members of union: '*member1*' and '*member2*' | +| Compiler error C3443 | The default member initializer for '*class*' is recursive | +| Compiler error C3444 | Empty aggregate class '*class*' must be initialized with '{}' | +| [Compiler error C3445](compiler-error-c3445.md) | copy-list-initialization of '*type*' cannot use an explicit constructor | +| [Compiler error C3446](compiler-error-c3446.md) | '*class*': a default member initializer is not allowed for a member of a value class | +| Compiler error C3447 | *operand* to the conditional operator `?:` is of type 'void', but the *other-operand* is neither a throw-expression nor of type 'void' | +| Compiler error C3448 | the number of identifiers must match the number of array elements or members in a structured binding declaration | +| Compiler error C3449 | the number of identifiers must match the value of `std::tuple_size::value` in a structured binding of tuple-like type | +| [Compiler error C3450](compiler-error-c3450.md) | '*type*': not an attribute; cannot specify [`System::AttributeUsageAttribute`]/[Windows::Foundation::Metadata::AttributeUsageAttribute] | +| [Compiler error C3451](compiler-error-c3451.md) | '*attribute*': cannot apply unmanaged attribute to '*type*' | +| [Compiler error C3452](compiler-error-c3452.md) | list argument member not constant | +| [Compiler error C3453](compiler-error-c3453.md) | '*attribute*': attribute not applied because qualifier '*qualifier*' did not match | +| [Compiler error C3454](compiler-error-c3454.md) | [attribute] not allowed on class declaration | +| [Compiler error C3455](compiler-error-c3455.md) | '*attribute*': none of the attribute constructors matched the arguments | +| [Compiler error C3456](compiler-error-c3456.md) | [source-annotation-attribute] not allowed on managed/WinRT class declaration | +| [Compiler error C3457](compiler-error-c3457.md) | '*attribute*': attribute does not support unnamed arguments | +| [Compiler error C3458](compiler-error-c3458.md) | '[*attribute*]': attribute '[*attribute*]' already specified for '*identifier*' | +| [Compiler error C3459](compiler-error-c3459.md) | '[*attribute*]': attribute allowed only on class indexer (default indexed property) | +| [Compiler error C3460](compiler-error-c3460.md) | '*type*': only a user-defined type can be forwarded | +| [Compiler error C3461](compiler-error-c3461.md) | '*type*': only a managed/WinRT type can be forwarded | +| [Compiler error C3462](compiler-error-c3462.md) | '*type*': only an imported type can be forwarded | +| [Compiler error C3463](compiler-error-c3463.md) | '*type*': type not allowed in attribute 'implements' | +| [Compiler error C3464](compiler-error-c3464.md) | '*type*' a nested type cannot be forwarded | +| [Compiler error C3465](compiler-error-c3465.md) | to use type '*type*' you must reference the assembly '*assembly*' | +| [Compiler error C3466](compiler-error-c3466.md) | '*type*': a specialization of a generic class cannot be forwarded | +| [Compiler error C3467](compiler-error-c3467.md) | '*type*': this type has already been forwarded | +| [Compiler error C3468](compiler-error-c3468.md) | '*type*': you can only forward a type to an assembly: '*identifier*' is not an assembly | +| [Compiler error C3469](compiler-error-c3469.md) | '*type*': a generic class cannot be forwarded | +| [Compiler error C3470](compiler-error-c3470.md) | '*class*': a class cannot have both an indexer (default indexed property) and an operator[] | +| Compiler error C3471 | new module name *module-name* (set on command line) conflicts with previous name *module-name* | +| Compiler error C3472 | new output file name *filename* (set on command line) conflicts with previous file name *filename* | +| Compiler error C3473 | no output pathname or module name specified. | +| Compiler error C3474 | could not open output file '*filename*' | +| Compiler error C3475 | syntax error in input file '*filename*' | +| Compiler error C3476 | could not open file '*filename*' for input | +| Compiler error C3477 | a lambda can only appear in an unevaluated context with '*C++ version*' or later | +| Compiler error C3478 | '*identifier*': an array of unknown bounds cannot be captured by copy | +| Compiler error C3479 | SAL annotations on lambdas are not supported | +| [Compiler error C3480](compiler-error-c3480.md) | '*variable*': a lambda capture variable must be from an enclosing function scope | +| [Compiler error C3481](compiler-error-c3481.md) | '*identifier*': lambda capture variable not found | +| [Compiler error C3482](compiler-error-c3482.md) | 'this' can only be used as a lambda capture within a non-static member function | +| [Compiler error C3483](compiler-error-c3483.md) | '*identifier*' is already part of the lambda capture list | +| [Compiler error C3484](compiler-error-c3484.md) | syntax error: expected '->' before the return type | +| [Compiler error C3485](compiler-error-c3485.md) | a lambda definition cannot have any cv-qualifiers (Obsolete in Visual Studio 2022.) | +| Compiler error C3486 | a parameter for a lambda cannot have a default argument (Obsolete in Visual Studio 2022.) | +| [Compiler error C3487](compiler-error-c3487.md) | '*type*': all return expressions must deduce to the same type: previously it was '*type*' | +| [Compiler error C3488](compiler-error-c3488.md) | '`&`*identifier*' cannot be explicitly captured when the default capture mode is by reference (`&`) | +| [Compiler error C3489](compiler-error-c3489.md) | '`&`*identifier*' is required when the default capture mode is by copy (`=`) | +| [Compiler error C3490](compiler-error-c3490.md) | '*identifier*' cannot be modified because it is being accessed through a const object | +| [Compiler error C3491](compiler-error-c3491.md) | '*identifier*': a by copy capture cannot be modified in a non-mutable lambda | +| [Compiler error C3492](compiler-error-c3492.md) | '*identifier*': you cannot capture a member of an anonymous union | +| [Compiler error C3493](compiler-error-c3493.md) | '*identifier*' cannot be implicitly captured because no default capture mode has been specified | +| Compiler error C3494 | 'this' cannot be explicitly captured because an enclosing capture mode does not allow it | +| [Compiler error C3495](compiler-error-c3495.md) | '*identifier*': a simple capture must be a variable with automatic storage duration declared in the reaching scope of the lambda | +| [Compiler error C3496](compiler-error-c3496.md) | '`this`' is always captured by copy: '`&`' ignored | +| Compiler error C3497 | cannot construct an instance of this lambda | +| [Compiler error C3498](compiler-error-c3498.md) | '*identifier*': you cannot capture a variable that has a managed/WinRT type | +| [Compiler error C3499](compiler-error-c3499.md) | a lambda that has been specified to have a void return type cannot return a value | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3500-through-c3999.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3500-through-c3999.md index 8ea69da300..e1469d0230 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3500-through-c3999.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3500-through-c3999.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: Compiler errors C3500 through C3999" title: "Compiler errors C3500 through C3999" -ms.date: "04/21/2019" -f1_keywords: ["C3502", "C3503", "C3504", "C3511", "C3512", "C3513", "C3514", "C3515", "C3516", "C3517", "C3518", "C3520", "C3521", "C3522", "C3523", "C3524", "C3525", "C3526", "C3527", "C3528", "C3529", "C3534", "C3542", "C3543", "C3544", "C3545", "C3546", "C3547", "C3548", "C3549", "C3557", "C3558", "C3559", "C3560", "C3561", "C3562", "C3563", "C3564", "C3565", "C3566", "C3567", "C3568", "C3569", "C3570", "C3571", "C3572", "C3573", "C3574", "C3575", "C3576", "C3577", "C3578", "C3579", "C3580", "C3581", "C3582", "C3583", "C3584", "C3585", "C3586", "C3587", "C3588", "C3589", "C3590", "C3591", "C3592", "C3593", "C3594", "C3595", "C3596", "C3597", "C3598", "C3599", "C3600", "C3601", "C3602", "C3604", "C3605", "C3613", "C3614", "C3616", "C3620", "C3621", "C3635", "C3636", "C3649", "C3658", "C3659", "C3660", "C3663", "C3664", "C3667", "C3674", "C3676", "C3677", "C3678", "C3679", "C3680", "C3681", "C3682", "C3683", "C3684", "C3685", "C3686", "C3687", "C3688", "C3689", "C3690", "C3691", "C3696", "C3716", "C3720", "C3725", "C3726", "C3729", "C3730", "C3735", "C3742", "C3746", "C3750", "C3751", "C3756", "C3757", "C3758", "C3759", "C3760", "C3770", "C3773", "C3774", "C3775", "C3776", "C3777", "C3778", "C3780", "C3781", "C3782", "C3783", "C3784", "C3785", "C3786", "C3787", "C3801", "C3802", "C3806", "C3811", "C3814", "C3819", "C3822", "C3823", "C3826", "C3827", "C3829", "C3837", "C3840", "C3841", "C3843", "C3844", "C3845", "C3863", "C3870", "C3871", "C3875", "C3879", "C3881", "C3882", "C3884", "C3885", "C3897", "C3905", "C3906", "C3916", "C3921", "C3924", "C3925", "C3926", "C3927", "C3928", "C3930", "C3931", "C3932", "C3933", "C3934", "C3935", "C3936", "C3937", "C3938", "C3939", "C3940", "C3941", "C3945", "C3946", "C3947", "C3948", "C3949", "C3950", "C3951", "C3952", "C3953", "C3954", "C3955", "C3956", "C3957", "C3958", "C3959", "C3960", "C3961", "C3962", "C3963", "C3964", "C3965", "C3966", "C3967", "C3968", "C3969", "C3970", "C3971", "C3972", "C3975", "C3976", "C3977", "C3978", "C3979", "C3980", "C3981", "C3982", "C3983", "C3984", "C3985", "C3986", "C3987", "C3988", "C3989", "C3990", "C3991", "C3992", "C3993", "C3994", "C3995", "C3996", "C3997", "C3998", "C3999"] -ms.assetid: bd6f23ad-b300-4e07-8e35-9661cab1585f +description: "Learn more about: Compiler errors C3500 through C3999" +ms.date: 05/25/2022 +f1_keywords: ["C3502", "C3503", "C3504", "C3511", "C3512", "C3513", "C3514", "C3515", "C3516", "C3517", "C3518", "C3520", "C3521", "C3522", "C3523", "C3524", "C3525", "C3526", "C3527", "C3528", "C3529", "C3534", "C3542", "C3543", "C3544", "C3545", "C3546", "C3547", "C3548", "C3549", "C3557", "C3558", "C3559", "C3560", "C3561", "C3562", "C3563", "C3564", "C3565", "C3566", "C3567", "C3568", "C3569", "C3570", "C3571", "C3572", "C3573", "C3574", "C3575", "C3576", "C3577", "C3578", "C3579", "C3580", "C3581", "C3582", "C3583", "C3584", "C3585", "C3586", "C3587", "C3588", "C3589", "C3590", "C3591", "C3592", "C3593", "C3594", "C3595", "C3596", "C3597", "C3598", "C3599", "C3600", "C3601", "C3602", "C3604", "C3605", "C3606", "C3613", "C3614", "C3616", "C3617", "C3620", "C3621", "C3629", "C3635", "C3636", "C3639", "C3643", "C3647", "C3649", "C3658", "C3659", "C3660", "C3663", "C3664", "C3667", "C3674", "C3676", "C3677", "C3678", "C3679", "C3680", "C3681", "C3682", "C3683", "C3684", "C3685", "C3686", "C3687", "C3688", "C3689", "C3690", "C3691", "C3692", "C3693", "C3694", "C3695", "C3696", "C3700", "C3716", "C3720", "C3725", "C3726", "C3729", "C3730", "C3735", "C3742", "C3746", "C3750", "C3751", "C3756", "C3757", "C3758", "C3759", "C3760", "C3770", "C3773", "C3774", "C3775", "C3776", "C3777", "C3778", "C3780", "C3781", "C3782", "C3783", "C3784", "C3785", "C3786", "C3787", "C3788", "C3789", "C3790", "C3791", "C3792", "C3793", "C3794", "C3795", "C3796", "C3801", "C3802", "C3806", "C3810", "C3811", "C3814", "C3819", "C3822", "C3823", "C3826", "C3827", "C3829", "C3835", "C3837", "C3840", "C3841", "C3843", "C3844", "C3845", "C3847", "C3863", "C3864", "C3870", "C3871", "C3875", "C3876", "C3877", "C3878", "C3879", "C3881", "C3882", "C3884", "C3885", "C3897", "C3905", "C3906", "C3907", "C3916", "C3921", "C3924", "C3925", "C3926", "C3927", "C3928", "C3930", "C3931", "C3932", "C3933", "C3934", "C3935", "C3936", "C3937", "C3938", "C3939", "C3940", "C3941", "C3945", "C3946", "C3947", "C3948", "C3949", "C3950", "C3951", "C3952", "C3953", "C3954", "C3955", "C3956", "C3957", "C3958", "C3959", "C3960", "C3961", "C3962", "C3963", "C3964", "C3965", "C3966", "C3967", "C3968", "C3969", "C3970", "C3971", "C3972", "C3973", "C3974", "C3975", "C3976", "C3977", "C3978", "C3979", "C3980", "C3981", "C3982", "C3983", "C3984", "C3985", "C3986", "C3987", "C3988", "C3989", "C3990", "C3991", "C3992", "C3993", "C3994", "C3995", "C3996", "C3997", "C3998"] +helpviewer_keywords: ["C3502", "C3503", "C3504", "C3511", "C3512", "C3513", "C3514", "C3515", "C3516", "C3517", "C3518", "C3520", "C3521", "C3522", "C3523", "C3524", "C3525", "C3526", "C3527", "C3528", "C3529", "C3534", "C3542", "C3543", "C3544", "C3545", "C3546", "C3547", "C3548", "C3549", "C3557", "C3558", "C3559", "C3560", "C3561", "C3562", "C3563", "C3564", "C3565", "C3566", "C3567", "C3568", "C3569", "C3570", "C3571", "C3572", "C3573", "C3574", "C3575", "C3576", "C3577", "C3578", "C3579", "C3580", "C3581", "C3582", "C3583", "C3584", "C3585", "C3586", "C3587", "C3588", "C3589", "C3590", "C3591", "C3592", "C3593", "C3594", "C3595", "C3596", "C3597", "C3598", "C3599", "C3600", "C3601", "C3602", "C3604", "C3605", "C3606", "C3613", "C3614", "C3616", "C3617", "C3620", "C3621", "C3629", "C3635", "C3636", "C3639", "C3643", "C3647", "C3649", "C3658", "C3659", "C3660", "C3663", "C3664", "C3667", "C3674", "C3676", "C3677", "C3678", "C3679", "C3680", "C3681", "C3682", "C3683", "C3684", "C3685", "C3686", "C3687", "C3688", "C3689", "C3690", "C3691", "C3692", "C3693", "C3694", "C3695", "C3696", "C3700", "C3716", "C3720", "C3725", "C3726", "C3729", "C3730", "C3735", "C3742", "C3746", "C3750", "C3751", "C3756", "C3757", "C3758", "C3759", "C3760", "C3770", "C3773", "C3774", "C3775", "C3776", "C3777", "C3778", "C3780", "C3781", "C3782", "C3783", "C3784", "C3785", "C3786", "C3787", "C3788", "C3789", "C3790", "C3791", "C3792", "C3793", "C3794", "C3795", "C3796", "C3801", "C3802", "C3806", "C3810", "C3811", "C3814", "C3819", "C3822", "C3823", "C3826", "C3827", "C3829", "C3835", "C3837", "C3840", "C3841", "C3843", "C3844", "C3845", "C3847", "C3863", "C3864", "C3870", "C3871", "C3875", "C3876", "C3877", "C3878", "C3879", "C3881", "C3882", "C3884", "C3885", "C3897", "C3905", "C3906", "C3907", "C3916", "C3921", "C3924", "C3925", "C3926", "C3927", "C3928", "C3930", "C3931", "C3932", "C3933", "C3934", "C3935", "C3936", "C3937", "C3938", "C3939", "C3940", "C3941", "C3945", "C3946", "C3947", "C3948", "C3949", "C3950", "C3951", "C3952", "C3953", "C3954", "C3955", "C3956", "C3957", "C3958", "C3959", "C3960", "C3961", "C3962", "C3963", "C3964", "C3965", "C3966", "C3967", "C3968", "C3969", "C3970", "C3971", "C3972", "C3973", "C3974", "C3975", "C3976", "C3977", "C3978", "C3979", "C3980", "C3981", "C3982", "C3983", "C3984", "C3985", "C3986", "C3987", "C3988", "C3989", "C3990", "C3991", "C3992", "C3993", "C3994", "C3995", "C3996", "C3997", "C3998"] --- # Compiler errors C3500 through C3999 -The articles in this section of the documentation explain a subset of the error messages that are generated by the compiler. +The articles in this section explain a subset of the error messages generated by the compiler. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -25,7 +25,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3507](compiler-error-c3507.md)|a ProgID can have no more than 39 characters '*progid*'; nor contain any punctuation apart from '.'; nor start with a digit| |[Compiler error C3508](compiler-error-c3508.md)|'*type*': is not a valid Automation type| |[Compiler error C3509](compiler-error-c3509.md)|'*type*': invalid Automation return type; when a parameter is marked 'retval', the return type must be 'void', 'HRESULT' or 'SCODE'| -|[Compiler error C3510](compiler-error-c3510.md)|cannot locate dependent type library *library*| +|[Compiler error C3510](compiler-error-c3510.md)|cannot locate dependent type library *library_name*| |Compiler error C3511|'*identifier*': a call to a delegating constructor shall be the only member-initializer| |Compiler error C3512|the delimiting character sequence for a raw string literal shall have no more than 16 characters| |Compiler error C3513|'*string*': unsupported raw string literal delimiter character| @@ -105,7 +105,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3587|dynamic_cast is unsupported in amp restricted code| |Compiler error C3588|casting from '*type1*' to '*type2*' is unsupported in amp restricted code| |Compiler error C3589|'*string*': unsupported usage of string literals in amp restricted code| -|Compiler error C3590|'*token*': by-reference capture or 'this' capture is unsupported if the lambda is amp restricted| +|Compiler error C3590|capture of '*value*' is unsupported if the lambda is amp restricted| |Compiler error C3591|typeid operator is unsupported in amp restricted code| |Compiler error C3592|Inline native assembly ('__asm') is unsupported in amp restricted code| |Compiler error C3593|'goto' is unsupported in amp restricted code| @@ -121,9 +121,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3603](compiler-error-c3603.md)|'*symbol*': type '*type*' not yet supported| |Compiler error C3604|'*identifier*': can only create a managed object on the gc heap| |Compiler error C3605|The total number of samplers (*number* captured and *number* predefined) exceed *number* when compiling the call graph for the concurrency::parallel_for_each at: '*function*'| -|Compiler error C3606|Obsolete.| -|Compiler error C3607|Obsolete.| -|Compiler error C3608|Obsolete.| +| Compiler error C3606 | intrinsic function '*function*' cannot be mapped to HLSL | |[Compiler error C3609](compiler-error-c3609.md)|'*identifier*': a 'sealed/final' function must be virtual| |[Compiler error C3610](compiler-error-c3610.md)|'*identifier*': value type must be 'boxed' before method '*method*' can be called| |[Compiler error C3611](compiler-error-c3611.md)|'*identifier*': a sealed function cannot have a pure-specifier| @@ -132,7 +130,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3614|Differing values for pack size within the same class; previous was '*value*', new value is '*value*'| |[Compiler error C3615](compiler-error-c3615.md)|constexpr function '*function*' cannot result in a constant expression| |Compiler error C3616|Obsolete.| -|Compiler error C3617|Obsolete.| +| Compiler error C3617 | initializers of structured bindings must be of array or non-union class type; type '*type_name*' is not permitted | |[Compiler error C3618](compiler-error-c3618.md)|'*declaration*': a method marked DllImport cannot be defined| |[Compiler error C3619](compiler-error-c3619.md)|a template cannot be declared within a managed/WinRT type| |Compiler error C3620|'*type*': setting the alignment is not allowed on WinRT types| @@ -145,7 +143,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3627](compiler-error-c3627.md)|Only a value type can be boxed| |[Compiler error C3628](compiler-error-c3628.md)|'*class*': managed/WinRT classes only support public inheritance| |Compiler error C3629|'*token*': a capture default can only appear at the beginning of a lambda capture list| -|[Compiler error C3630](compiler-error-c3630.md)|error when processing the token '*token*'| +|[Compiler error C3630](compiler-error-c3630.md)|error when processing the token '*token*' (Obsolete in Visual Studio 2022.)| |[Compiler error C3631](compiler-error-c3631.md)|'*event*': cannot overload managed/WinRT events| |[Compiler error C3632](compiler-error-c3632.md)|'*event*': illegal style of event for *construct*| |[Compiler error C3633](compiler-error-c3633.md)|cannot define '*identifier*' as a member of managed '*class*'| @@ -154,11 +152,11 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3636|'*identifier*': cannot be applied to this type| |[Compiler error C3637](compiler-error-c3637.md)|'*function*': a friend function definition cannot be a specialization of a function template/generic| |[Compiler error C3638](compiler-error-c3638.md)|'*operator*': the standard boxing and unboxing conversion operators cannot be redefined| -|Compiler error C3639|Obsolete.| +| Compiler error C3639 | a lambda that is part of a default argument can only have an init-capture | |[Compiler error C3640](compiler-error-c3640.md)|'*member*': a referenced or virtual member function of a local class must be defined| -|[Compiler error C3641](compiler-error-c3641.md)|'*function*': invalid calling convention '*convention*' for function compiled with /clr:pure or /clr:safe| +|[Compiler error C3641](compiler-error-c3641.md)|'*function*': invalid calling convention '*convention*' for function compiled with `/clr:pure` or `/clr:safe`| |[Compiler error C3642](compiler-error-c3642.md)|'*function*': cannot call a function with __clrcall calling convention from native code| -|Compiler error C3643|Obsolete.| +| Compiler error C3643 | '%$S': cannot decompose type with non-static data-members in both '%$S' and '%$S' | |[Compiler error C3644](compiler-error-c3644.md)|'*function*': cannot compile the function to generate managed code| |[Compiler error C3645](compiler-error-c3645.md)|'*function*': __clrcall cannot be used on functions compiled to native code| |[Compiler error C3646](compiler-error-c3646.md)|'*identifier*': unknown override specifier| @@ -207,15 +205,15 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3689|'operator *identifier*': literal operator/literal operator template must be in a global or namespace scope| |Compiler error C3690|expected a string literal, but found a user-defined string literal instead| |Compiler error C3691|invalid literal prefix '*prefix*'| -|Compiler error C3692|Obsolete.| -|Compiler error C3693|Obsolete.| -|Compiler error C3694|Obsolete.| -|Compiler error C3695|Obsolete.| +| Compiler error C3692 | non-scalar type '*type_name*' cannot be used in a pseudo-destructor expression | +| Compiler error C3693 | '*identifier*': bit-fields cannot be captured by reference | +| Compiler error C3694 | a structured binding declaration can contain no specifiers other than 'static', 'thread_local', 'auto', and cv-qualifiers | +| Compiler error C3695 | '%$S': cannot decompose a type containing an anonymous union or struct | |Compiler error C3696|'*keyword*': cannot use this qualifier on '%'| |[Compiler error C3697](compiler-error-c3697.md)|'*keyword*': cannot use this qualifier on '^'| |[Compiler error C3698](compiler-error-c3698.md)|'*type*': cannot use this type as argument of '*operator*'| |[Compiler error C3699](compiler-error-c3699.md)|'*operator*': cannot use this indirection on type '*type*'| -|Compiler error C3700|Obsolete.| +| Compiler error C3700 | filename is missing terminating '%c' | |[Compiler error C3701](compiler-error-c3701.md)|'*function*': event source has no events| |[Compiler error C3702](compiler-error-c3702.md)|ATL is required for COM events| |[Compiler error C3703](compiler-error-c3703.md)|'*event_handler*': an event handler method must have the same storage class as the source '*event*'| @@ -231,26 +229,26 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3713](compiler-error-c3713.md)|'*event_handler*': an event handler method must have the same function parameters as the source '*event*'| |[Compiler error C3714](compiler-error-c3714.md)|'*event_handler*': an event handler method must have the same calling convention as the source '*event*'| |[Compiler error C3715](compiler-error-c3715.md)|'*pointer*': must be a pointer to '*type*'| -|Compiler error C3716|Obsolete.| +| Compiler error C3716 | '%$L': building precompiled header with module constructs is not allowed | |[Compiler error C3717](compiler-error-c3717.md)|'*member*': a method that fires events cannot be defined| |[Compiler error C3718](compiler-error-c3718.md)|can only call '__*keyword*' in the context of a member function of the receiving class| |[Compiler error C3719](compiler-error-c3719.md)|'*member*': an interface based event source can only be used for COM events| -|Compiler error C3720|'*type*': can only implement IDispatch on a dual or dispinterface| +|Compiler error C3720|'*type*': can only implement `IDispatch` on a dual or dispinterface| |[Compiler error C3721](compiler-error-c3721.md)|'*signature*': incompatible signature for event| |[Compiler error C3722](compiler-error-c3722.md)|a generic event is not allowed| |[Compiler error C3723](compiler-error-c3723.md)|'*function*': could not resolve event| |[Compiler error C3724](compiler-error-c3724.md)|must #include \ to use multi-threading with events| |Compiler error C3725|Obsolete.| -|Compiler error C3726|Obsolete.| +| Compiler error C3726 | Could not apply SecureHotPatch transformations to '%s'. *explanation* | |[Compiler error C3727](compiler-error-c3727.md)|'*event*': a managed event must be a member function or a data member that is a pointer to a delegate| |[Compiler error C3728](compiler-error-c3728.md)|'*event*': event does not have a raise method| -|Compiler error C3729|Obsolete.| +| Compiler error C3729 | attribute specifier cannot contain both using namespace prefix and scoped attribute | |Compiler error C3730|Obsolete.| |[Compiler error C3731](compiler-error-c3731.md)|incompatible event '*event*' and handler '*event_handler*'; event source and event handler must have the same event type| -|[Compiler error C3732](compiler-error-c3732.md)|'*interface*': a custom interface that fires COM events cannot inherit from IDispatch| +|[Compiler error C3732](compiler-error-c3732.md)|'*interface*': a custom interface that fires COM events cannot inherit from `IDispatch`| |[Compiler error C3733](compiler-error-c3733.md)|'*event*': improper syntax for specifying a COM event; did you forget '__interface'?| |[Compiler error C3734](compiler-error-c3734.md)|'*class*': a managed/WinRT class cannot be a coclass| -|Compiler error C3735|Obsolete.| +| Compiler error C3735 | template or generic redefined | |[Compiler error C3736](compiler-error-c3736.md)|'*member*': must be a method or, in the case of managed events, optionally a data member| |[Compiler error C3737](compiler-error-c3737.md)|'*identifier*': a delegate may not have an explicit calling convention| |[Compiler error C3738](compiler-error-c3738.md)|'*convention*': the calling convention of the explicit instantiation must match that of the template being instantiated| @@ -265,33 +263,33 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3747](compiler-error-c3747.md)|missing default template/generic parameter: parameter *number*| |[Compiler error C3748](compiler-error-c3748.md)|'*interface*': unmanaged interfaces may not fire events| |[Compiler error C3749](compiler-error-c3749.md)|'*attribute*': a custom attribute may not be used inside a function| -|Compiler error C3750|'*token*': unexpected token in attribute list| +|Compiler error C3750|'*token*': unexpected token in attribute specifier| |Compiler error C3751|'*identifier*': unexpected identifier in attribute list| |[Compiler error C3752](compiler-error-c3752.md)|'*attribute*': cannot classify attribute; '*keyword*' should not be used in this context| |[Compiler error C3753](compiler-error-c3753.md)|a generic property is not allowed| |[Compiler error C3754](compiler-error-c3754.md)|delegate constructor: member function '*member*' cannot be called on an instance of type '*type*'| |[Compiler error C3755](compiler-error-c3755.md)|'*identifier*': a delegate may not be defined| |Compiler error C3756|Obsolete.| -|Compiler error C3757|'*type*': type not allowed for 'constexpr' function| +| Compiler error C3757 | '*type*': type not allowed for 'constexpr' function (Obsolete in Visual Studio 2022.) | |Compiler error C3758|'*member*': virtual function cannot be declared 'constexpr'| -|Compiler error C3759|'*member*': member function of non-literal type cannot be declared 'constexpr'| -|Compiler error C3760|please use __property keyword to declare property in managed/WinRT '*class*'| -|[Compiler error C3761](compiler-error-c3761.md)|'*function*': 'retval' can only appear on the last argument of a function| +| Compiler error C3759 | '*member*': member function of non-literal type cannot be declared 'constexpr' (Obsolete in Visual Studio 2022.) | +|Compiler error C3760|please use `__property` keyword to declare property in managed/WinRT '*class*'| +|[Compiler error C3761](compiler-error-c3761.md)|'*function*': '`retval`' can only appear on the last argument of a function| |[Compiler error C3762](compiler-error-c3762.md)|unable to process attribute '*attribute*'| -|[Compiler error C3763](compiler-error-c3763.md)|'*type*': 'retval' and 'out' can only appear on a data-pointer type| +|[Compiler error C3763](compiler-error-c3763.md)|'*type*': '`retval`' and '`out`' can only appear on a data-pointer type| |[Compiler error C3764](compiler-error-c3764.md)|'*member*': cannot override base class method '*member*'| |[Compiler error C3765](compiler-error-c3765.md)|'*event*': cannot define an event in a class/struct '*type*' marked as an event_receiver| |[Compiler error C3766](compiler-error-c3766.md)|'*type*' must provide an implementation for the interface method '*function*'| |[Compiler error C3767](compiler-error-c3767.md)|'*function*': candidate function(s) not accessible| -|[Compiler error C3768](compiler-error-c3768.md)|cannot take the address of a virtual vararg function in pure managed code| +|[Compiler error C3768](compiler-error-c3768.md)|cannot take the address of a virtual `vararg` function in pure managed code| |[Compiler error C3769](compiler-error-c3769.md)|'*identifier*': a nested class cannot have the same name as the immediately enclosing class| |Compiler error C3770|'*type*': is not a valid base class| |[Compiler error C3771](compiler-error-c3771.md)|'*identifier*': friend declaration cannot be found in the nearest namespace scope| |[Compiler error C3772](compiler-error-c3772.md)|'*identifier*': invalid friend template declaration| -|Compiler error C3773|please use /await compiler switch to enable coroutines| -|Compiler error C3774|cannot find '*scope*::*identifier*': Please include *header* header| +|Compiler error C3773|Use of '*feature*' in this context is a non-conforming extension in `C++`*version*| +|Compiler error C3774|cannot find '*scope*::*identifier*': Please include *header_name* header| |Compiler error C3775|return type of '*function*' should not be '*type*'| -|Compiler error C3776|cannot return an expresssion of type void in a coroutine with non-void eventual return type| +|Compiler error C3776|cannot return an expression of type void in a coroutine with non-void eventual return type| |Compiler error C3777|'*function*': a coroutine cannot take a variable argument list| |Compiler error C3778|alloca: cannot be used in a coroutine| |[Compiler error C3779](compiler-error-c3779.md)|'*function*': a function that returns '*auto*' cannot be used before it is defined| @@ -299,19 +297,19 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3781|'*keyword*': cannot be a used in a coroutine of type '*type*'. Either *keyword* or *keyword* must be present in associated promise_type| |Compiler error C3782|*type*: a coroutine's promise cannot contain both *keyword* and *keyword*| |Compiler error C3783|'*identifier*': cannot be a coroutine| -|Compiler error C3784|*keyword* expression cannot appear in this context| +|Compiler error C3784|*keyword* cannot appear in this context| |Compiler error C3785|the first template argument to 'std::integer_sequence' must be an integer type| |Compiler error C3786|the second template argument to 'std::make_integer_sequence' must be an integer constant greater than or equal to zero| |Compiler error C3787|cannot deduce the return type of this coroutine| -|Compiler error C3788|Obsolete.| -|Compiler error C3789|Obsolete.| -|Compiler error C3790|Obsolete.| -|Compiler error C3791|Obsolete.| -|Compiler error C3792|Obsolete.| -|Compiler error C3793|Obsolete.| -|Compiler error C3794|Obsolete.| -|Compiler error C3795|Obsolete.| -|Compiler error C3796|Obsolete.| +| Compiler error C3788 | this function cannot be a coroutine: '*type_name*' is not a class | +| Compiler error C3789 | this function cannot be a coroutine: '%$T' does not declare the member '%$I()' | +| Compiler error C3790 | capturing '*this' requires '%1$M' | +| Compiler error C3791 | 'this' cannot be explicitly captured when the default capture mode is by copy (=) | +| Compiler error C3792 | unrecognized hash algorithm '%$I' | +| Compiler error C3793 | hash value for algorithm '%$I' must be exactly %u characters long | +| Compiler error C3794 | file '%$S' specified in #pragma file_hash is also part of the current compilation unit | +| Compiler error C3795 | multiple conflicting hash values for file '%$S' | +| Compiler error C3796 | 'operator %$I': is neither a string literal operator template nor a numeric literal operator template | |[Compiler error C3797](compiler-error-c3797.md)|'*keyword*': event declaration cannot have override specifier (should be placed on event add/remove/raise methods instead)| |[Compiler error C3798](compiler-error-c3798.md)|'*keyword*': property declaration cannot have override specifier (should be placed on property get/set methods instead)| |[Compiler error C3799](compiler-error-c3799.md)|indexed property cannot have an empty parameter list| @@ -325,7 +323,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3807](compiler-error-c3807.md)|'*type*': a class with the ComImport attribute cannot derive from '*type*', only interface implementation is allowed| |[Compiler error C3808](compiler-error-c3808.md)|'*type*': a class with the ComImport attribute cannot define member '*member*', only abstract or dllimport functions are allowed| |[Compiler error C3809](compiler-error-c3809.md)|'*type*': a managed/WinRT type cannot have any friend functions/classes/interfaces| -|Compiler error C3810|Obsolete.| +| Compiler error C3810 | '%1$S': cannot decompose type with ambiguous base class '*type_name*' | |Compiler error C3811|Obsolete.| |[Compiler error C3812](compiler-error-c3812.md)|'__property' must be the first token in a property declaration| |[Compiler error C3813](compiler-error-c3813.md)|a property declaration can only appear within the definition of a managed/WinRT type| @@ -344,7 +342,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3826|Obsolete.| |Compiler error C3827|standard attribute 'deprecated' may have either no arguments or one string literal describing the reason| |[Compiler error C3828](compiler-error-c3828.md)|placement arguments cannot be specified for a '*keyword*' expression for type '*type*'| -|Compiler error C3829|standard attribute 'noreturn' may only be applied to functions| +|Compiler error C3829|attribute `[[`*attribute name*`]]` may only be applied to a function declaration| |[Compiler error C3830](compiler-error-c3830.md)|'*type1*': cannot inherit from '*type2*', value types can only inherit from interface classes| |[Compiler error C3831](compiler-error-c3831.md)|'*identifier*': '*type*' cannot have a pinned data member or a member function returning a pinning pointer| |[Compiler error C3832](compiler-error-c3832.md)|'*typelib*': type library looks as if it was built for 32-bit pointers; please change the 'ptrsize' qualifier| @@ -362,7 +360,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3844|'*identifier*': cannot import symbol from '*source*': as '*identifier*' already exists in the current scope| |Compiler error C3845|Obsolete.| |[Compiler error C3846](compiler-error-c3846.md)|'*identifier*': cannot import symbol from '*source*': as '*identifier*' has already been imported from another assembly '*assembly*'| -|Compiler error C3847|Obsolete.| +| Compiler error C3847 | a noexcept-specifier on an explicit instantiation must match that of the template being instantiated | |[Compiler error C3848](compiler-error-c3848.md)|expression having type '*type*' would lose some const-volatile qualifiers in order to call '*identifier*'| |[Compiler error C3849](compiler-error-c3849.md)|function-style call on an expression of type '*type*' would lose const and/or volatile qualifiers for all *number* available operator overloads| |[Compiler error C3850](compiler-error-c3850.md)|'*token*': a universal-character-name specifies an invalid character| @@ -374,12 +372,12 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3856](compiler-error-c3856.md)|'*class*': class is not a class template/generic| |[Compiler error C3857](compiler-error-c3857.md)|'*template*': multiple template/generic parameter lists are not allowed| |[Compiler error C3858](compiler-error-c3858.md)|'*identifier*': cannot be redeclared in current scope| -|[Compiler error C3859](compiler-error-c3859.md)|virtual memory range for PCH exceeded; please recompile with a command line option of '-Zm*number*' or greater| +|[Compiler error C3859](compiler-error-c3859.md)|Failed to create virtual memory for PCH| |[Compiler error C3860](compiler-error-c3860.md)|template/generic argument list following class template/generic name must list parameters in the order used in template/generic parameter list| |[Compiler error C3861](compiler-error-c3861.md)|'*identifier*': identifier not found| -|[Compiler error C3862](compiler-error-c3862.md)|'*function*': cannot compile an unmanaged function with /clr:pure or /clr:safe| +|[Compiler error C3862](compiler-error-c3862.md)|'*function*': cannot compile an unmanaged function with `/clr:pure` or `/clr:safe`| |Compiler error C3863|array type '*type*' is not assignable| -|Compiler error C3864|Obsolete.| +|Compiler error C3864|'*context*': requires clause is incompatible with the declaration| |[Compiler error C3865](compiler-error-c3865.md)|'*keyword*': can only be used on native member functions| |[Compiler error C3866](compiler-error-c3866.md)|destructor/finalizer call missing argument list| |[Compiler error C3867](compiler-error-c3867.md)|'*function*': non-standard syntax; use '&' to create a pointer to member| @@ -391,20 +389,20 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3873](compiler-error-c3873.md)|'0x*value*': this character is not allowed as a first character of an identifier| |[Compiler error C3874](compiler-error-c3874.md)|return type of '*identifier*' should be '*type1*' instead of '*type2*'| |Compiler error C3875|call of non-static member function missing argument list| -|Compiler error C3876|Obsolete.| -|Compiler error C3877|Obsolete.| -|Compiler error C3878|Obsolete.| +| Compiler error C3876 | hexadecimal floating literal requires an exponent | +| Compiler error C3877 | invalid type argument to the TypeForwardedTo attribute | +| Compiler error C3878 | syntax error: unexpected token '*name*' following '*context*' | |Compiler error C3879|'*member*': cannot be an initonly data member| |[Compiler error C3880](compiler-error-c3880.md)|'*member*': cannot be a literal data member| |Compiler error C3881|can only inherit constructor from direct base| |Compiler error C3882|'*class*': constructor has already been inherited from '*class*'| -|Compiler error C3883|'*member*': an initonly static data member must be initialized| +|[Compiler error C3883](compiler-error-c3883.md)|'*member*': an initonly static data member must be initialized| |Compiler error C3884|'*type*': An array of unknown size cannot be value-initialized| |Compiler error C3885|'*type*': An array of unknown size cannot be initialized with an empty initializer list| |[Compiler error C3886](compiler-error-c3886.md)|'*member*': a literal data member must be initialized| |[Compiler error C3887](compiler-error-c3887.md)|'*member*': the initializer for a literal data member must be a constant expression| |[Compiler error C3888](compiler-error-c3888.md)|'*member*': the const expression associated with this literal data member is not supported by C++/CLI| -|Compiler error C3889|Obsolete.| +|Compiler error C3889|call to object of class type '*type*': no matching call operator found| |[Compiler error C3890](compiler-error-c3890.md)|'*member*': you cannot take the address of a literal data member| |[Compiler error C3891](compiler-error-c3891.md)|'*member*': a literal data member cannot be used as a l-value| |[Compiler error C3892](compiler-error-c3892.md)|'*variable*': you cannot assign to a variable that is const| @@ -422,7 +420,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3904](compiler-error-c3904.md)|'*property*': must specify *number* parameter(s)| |Compiler error C3905|unaligned accesses are not supported for intrinsic type '*type*'| |Compiler error C3906|intrinsic type '*type*' is not a supported return or argument type for vararg or unprototyped functions| -|Compiler error C3907|Obsolete.| +| Compiler error C3907 | cannot jump to a label that is in a different 'if constexpr' statement or substatement | |[Compiler error C3908](compiler-error-c3908.md)|access level less restrictive than that of '*identifier*'| |[Compiler error C3909](compiler-error-c3909.md)|a managed/WinRT event declaration must occur in a managed/WinRT type| |[Compiler error C3910](compiler-error-c3910.md)|'*event*': must define member '*member*'| @@ -431,20 +429,20 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C3913](compiler-error-c3913.md)|a default property must be indexed| |[Compiler error C3914](compiler-error-c3914.md)|a default property cannot be static| |[Compiler error C3915](compiler-error-c3915.md)|'*identifier*' has no default indexed property (class indexer)| -|Compiler error C3916|Obsolete.| +| Compiler error C3916 | function parameter with index %d and requested alignment of %d won't be aligned | |[Compiler error C3917](compiler-error-c3917.md)|'*token*': obsolete *construct* declaration style (did you mean to use '[' ']' instead?)| |[Compiler error C3918](compiler-error-c3918.md)|usage requires '*identifier*' to be a data member| |[Compiler error C3919](compiler-error-c3919.md)|'*function*': function must have type '*return_type* (*type*)'| |[Compiler error C3920](compiler-error-c3920.md)|'*operator*': cannot define a postfix increment/decrement CLR/WinRT operator Calling the postfix CLR/WinRT operator will call the corresponding prefix CLR/WinRT operator (op_Increment/op_Decrement), but with postfix semantics| |Compiler error C3921|Obsolete.| -|Compiler error C3922|Obsolete.| +|Compiler error C3922|'*name*': argument must be a constant expression| |[Compiler error C3923](compiler-error-c3923.md)|'*member*': local class, struct or union definitions are not allowed in a member function of a managed/WinRT class| |Compiler error C3924|error in argument #*number* of delegate constructor call '*constructor*':| -|Compiler error C3925|expected a loop (for, while, or do) following '*directive*' directive| +|Compiler error C3925|expected a loop (`for`, `while`, or `do`) following '*directive_name*' directive| |Compiler error C3926|invalid constant in 'parallel' directive| |Compiler error C3927|'->': trailing return type is not allowed after a non-function declarator| |Compiler error C3928|'->': trailing return type is not allowed after a parenthesized declarator| -|Compiler error C3929|Obsolete.| +|Compiler error C3929|'`collapse(`*count*`)`' specified but found only *value* loops following '`#pragma omp for`'| |Compiler error C3930|'*function*': no overloaded function has restriction specifiers that are compatible with the ambient context '*context*'| |Compiler error C3931|'*type*': cannot call a function that has restriction specifiers that are incompatible with the ambient context| |Compiler error C3932|Obsolete.| @@ -457,9 +455,9 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3939|'*identifier*': pointer to member functions, function pointers, references to functions with 'amp' restriction specifier are not allowed| |Compiler error C3940|'*identifier*': identifier not found - possible mismatch between compiler and library versions. Please ensure vccorlib.h/.lib, vccorlib120.dll and c1xx.dll match| |Compiler error C3941|'*condition*': requires '/clr' command line option| -|Compiler error C3942|Obsolete.| -|Compiler error C3943|Obsolete.| -|Compiler error C3944|Obsolete.| +|Compiler error C3942|'`#pragma omp atomic capture`': expression on right of '`=`' must be an lvalue-expression of scalar type| +|Compiler error C3943|'`#pragma omp atomic`': operator '*operator*' is overloaded; only built-in operators are allowed| +|Compiler error C3944|'`#pragma omp atomic`': lvalue expression required as left operand of '*operator*'| |Compiler error C3945|'*type*': unable to throw or catch a winrt object which doesn't derive from Platform::Exception| |Compiler error C3946|'*type*': typeid cannot be applied to this type| |Compiler error C3947|'*typeid*': typeid cannot be applied to a pack expansion| @@ -468,7 +466,7 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3950|Obsolete.| |Compiler error C3951|Cannot use pointer-to-member in projected WinRT type '*type*'. Use a delegate instead.| |Compiler error C3952|'*type*': WinRT does not support 'in/out' arrays. Use 'const Array\^' for 'in' and 'WriteOnlyArray\' or 'Array\^*' for 'out' on public APIs| -|Compiler error C3953|Cannot use managed class '*type*' in WinRT module.| +| Compiler error C3953 | Cannot use managed class '*type*' in WinRT module. (Obsolete in Visual Studio 2022.) | |Compiler error C3954|'*type*': An array returned from a published method on a WinRT type must use the form 'Array\^'| |Compiler error C3955|'*type*': A public constructor cannot contain an 'out' parameter or 'WriteOnlyArray\'| |Compiler error C3956|'*type*': Type is marked as Exclusive To '*type*' and cannot be used as a base of '*derived_type*'| @@ -488,8 +486,8 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3970|'*identifier*': '*keyword*' can only be applied to 'ref class' or 'ref struct' at global scope or namespace scope| |Compiler error C3971|'*type*': partial definition cannot appear after full definition| |Compiler error C3972|'*type*': 'partial' can only be applied to class declarations or definitions| -|Compiler error C3973|Obsolete.| -|Compiler error C3974|Obsolete.| +| Compiler error C3973 | Unimplemented feature: %$M | +| Compiler error C3974 | '%$S': index variable in OpenMP 'for' statement must have integral type | |Compiler error C3975|'class/struct *identifier*' was previously declared or defined with a different modifier| |Compiler error C3976|'*identifier1*' must be declared as 'public' in order to use '*identifier2*'| |Compiler error C3977|Usage requires a reference to an assembly that defines '*identifier*'| @@ -512,10 +510,10 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3994|'*type*': a value type cannot implement interfaces or have virtual functions| |Compiler error C3995|'*type*': a value type cannot have any event members '*identifier*'| |Compiler error C3996|Obsolete.| +| Compiler error C3997 | Warbird: *message* | |Compiler error C3998|'c++*version*': unsupported C++ version; defaulting to 'c++*version*'| -|Compiler error C3999|UNKNOWN ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ [Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md b/docs/error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md index d06ad0a7d9..0ed99e5e5f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Compiler errors C7500 through C7999" title: "Compiler errors C7500 through C7999" -ms.date: 04/18/2021 -f1_keywords: ["C7500", "C7501", "C7502", "C7503", "C7504", "C7505", "C7506", "C7507", "C7508", "C7509", "C7511", "C7512", "C7513", "C7514", "C7515", "C7516", "C7517", "C7518", "C7519", "C7520", "C7521", "C7522", "C7523", "C7524", "C7525", "C7526", "C7527", "C7528", "C7529", "C7530", "C7531", "C7532", "C7533", "C7534", "C7535", "C7537", "C7538", "C7539", "C7540", "C7541", "C7542", "C7543", "C7544", "C7545", "C7546", "C7547", "C7548", "C7549", "C7550", "C7551", "C7552", "C7553", "C7554", "C7555", "C7556", "C7557", "C7558", "C7559", "C7560", "C7561", "C7562", "C7563", "C7564", "C7565", "C7566", "C7567", "C7568", "C7569", "C7570", "C7571", "C7572", "C7573", "C7574", "C7575", "C7576", "C7577", "C7578", "C7579", "C7580", "C7581", "C7582", "C7583", "C7584", "C7585", "C7586", "C7587", "C7588", "C7589", "C7590", "C7591", "C7592", "C7593", "C7594", "C7595", "C7596", "C7597", "C7599", "C7600", "C7601", "C7602", "C7603", "C7604", "C7605", "C7606", "C7607", "C7608", "C7609", "C7610", "C7611", "C7612", "C7613", "C7614", "C7615", "C7616", "C7617", "C7618", "C7619", "C7620", "C7621", "C7622", "C7623", "C7624", "C7625", "C7627", "C7628", "C7629", "C7630", "C7631", "C7632", "C7633", "C7634", "C7635", "C7636", "C7637", "C7638", "C7639", "C7640", "C7641", "C7642", "C7643", "C7644", "C7645", "C7646", "C7647", "C7648", "C7649", "C7650", "C7651", "C7652", "C7653", "C7654", "C7655", "C7656", "C7657", "C7658", "C7659", "C7660", "C7661", "C7662", "C7700", "C7701", "C7702", "C7703", "C7704"] -helpviewer_keywords: ["C7500", "C7501", "C7502", "C7503", "C7504", "C7505", "C7506", "C7507", "C7508", "C7509", "C7511", "C7512", "C7513", "C7514", "C7515", "C7516", "C7517", "C7518", "C7519", "C7520", "C7521", "C7522", "C7523", "C7524", "C7525", "C7526", "C7527", "C7528", "C7529", "C7530", "C7531", "C7532", "C7533", "C7534", "C7535", "C7537", "C7538", "C7539", "C7540", "C7541", "C7542", "C7543", "C7544", "C7545", "C7546", "C7547", "C7548", "C7549", "C7550", "C7551", "C7552", "C7553", "C7554", "C7555", "C7556", "C7557", "C7558", "C7559", "C7560", "C7561", "C7562", "C7563", "C7564", "C7565", "C7566", "C7567", "C7568", "C7569", "C7570", "C7571", "C7572", "C7573", "C7574", "C7575", "C7576", "C7577", "C7578", "C7579", "C7580", "C7581", "C7582", "C7583", "C7584", "C7585", "C7586", "C7587", "C7588", "C7589", "C7590", "C7591", "C7592", "C7593", "C7594", "C7595", "C7596", "C7597", "C7599", "C7600", "C7601", "C7602", "C7603", "C7604", "C7605", "C7606", "C7607", "C7608", "C7609", "C7610", "C7611", "C7612", "C7613", "C7614", "C7615", "C7616", "C7617", "C7618", "C7619", "C7620", "C7621", "C7622", "C7623", "C7624", "C7625", "C7627", "C7628", "C7629", "C7630", "C7631", "C7632", "C7633", "C7634", "C7635", "C7636", "C7637", "C7638", "C7639", "C7640", "C7641", "C7642", "C7643", "C7644", "C7645", "C7646", "C7647", "C7648", "C7649", "C7650", "C7651", "C7652", "C7653", "C7654", "C7655", "C7656", "C7657", "C7658", "C7659", "C7660", "C7661", "C7662", "C7700", "C7701", "C7702", "C7703", "C7704"] +ms.date: 10/13/2023 +f1_keywords: ["C7500", "C7501", "C7502", "C7503", "C7504", "C7505", "C7506", "C7507", "C7508", "C7509", "C7511", "C7512", "C7513", "C7514", "C7515", "C7516", "C7517", "C7518", "C7519", "C7520", "C7521", "C7522", "C7523", "C7524", "C7525", "C7526", "C7527", "C7528", "C7529", "C7530", "C7531", "C7532", "C7533", "C7534", "C7535", "C7537", "C7538", "C7539", "C7540", "C7541", "C7542", "C7543", "C7544", "C7545", "C7546", "C7547", "C7548", "C7549", "C7550", "C7551", "C7552", "C7554", "C7555", "C7556", "C7557", "C7558", "C7559", "C7560", "C7561", "C7562", "C7563", "C7564", "C7565", "C7566", "C7567", "C7568", "C7569", "C7570", "C7571", "C7572", "C7573", "C7574", "C7575", "C7576", "C7577", "C7578", "C7579", "C7580", "C7581", "C7582", "C7583", "C7584", "C7585", "C7586", "C7587", "C7588", "C7589", "C7590", "C7591", "C7592", "C7593", "C7594", "C7595", "C7596", "C7597", "C7599", "C7600", "C7601", "C7602", "C7603", "C7604", "C7605", "C7606", "C7607", "C7608", "C7609", "C7610", "C7611", "C7612", "C7613", "C7614", "C7615", "C7616", "C7617", "C7618", "C7619", "C7620", "C7621", "C7622", "C7623", "C7624", "C7625", "C7627", "C7628", "C7629", "C7630", "C7631", "C7632", "C7633", "C7634", "C7635", "C7636", "C7637", "C7638", "C7639", "C7640", "C7641", "C7642", "C7643", "C7644", "C7645", "C7646", "C7647", "C7648", "C7649", "C7650", "C7651", "C7652", "C7653", "C7654", "C7655", "C7656", "C7657", "C7658", "C7659", "C7660", "C7661", "C7662", "C7686", "C7700", "C7701", "C7702", "C7703", "C7704"] +helpviewer_keywords: ["C7500", "C7501", "C7502", "C7503", "C7504", "C7505", "C7506", "C7507", "C7508", "C7509", "C7511", "C7512", "C7513", "C7514", "C7515", "C7516", "C7517", "C7518", "C7519", "C7520", "C7521", "C7522", "C7523", "C7524", "C7525", "C7526", "C7527", "C7528", "C7529", "C7530", "C7531", "C7532", "C7533", "C7534", "C7535", "C7537", "C7538", "C7539", "C7540", "C7541", "C7542", "C7543", "C7544", "C7545", "C7546", "C7547", "C7548", "C7549", "C7550", "C7551", "C7552", "C7554", "C7555", "C7556", "C7557", "C7558", "C7559", "C7560", "C7561", "C7562", "C7563", "C7564", "C7565", "C7566", "C7567", "C7568", "C7569", "C7570", "C7571", "C7572", "C7573", "C7574", "C7575", "C7576", "C7577", "C7578", "C7579", "C7580", "C7581", "C7582", "C7583", "C7584", "C7585", "C7586", "C7587", "C7588", "C7589", "C7590", "C7591", "C7592", "C7593", "C7594", "C7595", "C7596", "C7597", "C7599", "C7600", "C7601", "C7602", "C7603", "C7604", "C7605", "C7606", "C7607", "C7608", "C7609", "C7610", "C7611", "C7612", "C7613", "C7614", "C7615", "C7616", "C7617", "C7618", "C7619", "C7620", "C7621", "C7622", "C7623", "C7624", "C7625", "C7627", "C7628", "C7629", "C7630", "C7631", "C7632", "C7633", "C7634", "C7635", "C7636", "C7637", "C7638", "C7639", "C7640", "C7641", "C7642", "C7643", "C7644", "C7645", "C7646", "C7647", "C7648", "C7649", "C7650", "C7651", "C7652", "C7653", "C7654", "C7655", "C7656", "C7657", "C7658", "C7659", "C7660", "C7661", "C7662", "C7686", "C7700", "C7701", "C7702", "C7703", "C7704"] --- # Compiler errors C7500 through C7999 -The articles in this section of the documentation explain a subset of the error messages that are generated by the compiler. +The articles in this section of the documentation explain a subset of the error messages generated by the compiler. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -42,7 +42,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7524 | 'inline' specifier cannot appear on a block-scope declaration or non-static data member | | Compiler error C7525 | inline variables require at least '%1$M' | | Compiler error C7526 | '%$I': inline variable is undefined | -| Compiler error C7527 | '%$I': template parameter name cannot be redeclared | +| Compiler error C7527 | '*identifier*': a template parameter name cannot be reused within its scope | | Compiler error C7528 | '%1$S': A default constructor or its exception specification cannot be used within a data member initializer of the same class | | Compiler error C7529 | multiple using-declarators require at least '%1$M' | | Compiler error C7530 | applying a pack-expansion to a using-declaration requires at least '%1$M' | @@ -58,7 +58,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7540 | '%1$I': member cannot have the same name as the enclosing class | | Compiler error C7541 | '%1$I': C++17 inline static data members are not compatible with managed types | | Compiler error C7542 | '%1$S': expected a type | -| Compiler error C7543 | likelihood attributes can only be applied to statements and labels | +| Compiler error C7543 | attribute `[[`*attribute*`]]` can only be applied to statements and labels | | Compiler error C7544 | standard attributes '%1$s' and '%2$s' are mutually exclusive | | Compiler error C7545 | attribute '%sno_unique_address' can only be applied to a non-static data member that is not a bitfield | | Compiler error C7546 | binary operator '<=>': unsupported operand types '%$T' and '%$T' | @@ -68,7 +68,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7550 | '%1$S': the qualified name in this context names a constructor, not a type | | Compiler error C7551 | '%1$pS': template parameter '%2$S': '%3$pS': purely intrinsic functions have no address for use as a non-type template argument | | Compiler error C7552 | '%1$S': purely intrinsic functions have no address | -| Compiler error C7553 | inline assembler is not supported in a lambda | +| [Compiler error C7553](compiler-error-c7553.md) | inline assembler is not supported in a lambda | | Compiler error C7554 | %1$pS is not an integral constant expression | | Compiler error C7555 | use of designated initializers requires at least '%1$M' | | Compiler error C7556 | cannot mix designated-initializers with non-designated-initializers | @@ -113,6 +113,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7595 | '%1$S': call to immediate function is not a constant expression | | Compiler error C7596 | '%1$S': cannot take address of immediate function outside of an immediate invocation | | Compiler error C7597 | '%1$D': 'consteval': overriding function must match overridden function | +| Compiler error C7598 | the constraint expression cannot use the concept name '*identifier*'| | Compiler error C7599 | '%1$S': a trailing requires clause is only allowed on a templated function | | Compiler error C7600 | '%1$S': the concept designated by a type constraint shall be a type concept | | Compiler error C7601 | the associated constraints are not satisfied | @@ -123,7 +124,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7606 | '%1$S': concept cannot be explicitly instantiated, explicitly specialized or partially specialized | | Compiler error C7607 | atomic constraint should be a constant expression of type 'bool', not '%1$T' | | Compiler error C7608 | atomic constraint should be a constant expression | -| Compiler error C7609 | '%1$S': type constraint expects a concept name | +| Compiler error C7609 | '*identifier*': expected a concept name for type constraint | | Compiler error C7610 | operator '%$L': not allowed between enumeration types and floating-point types | | Compiler error C7611 | operator '%$L': not allowed for array types | | Compiler error C7612 | could not find header unit for '%s' | @@ -163,8 +164,8 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7646 | destroying operator delete functions cannot be array delete operators 'operator delete[]' | | Compiler error C7647 | destroying operator delete functions must be usual deallocation functions | | Compiler error C7648 | a conversion function cannot have a trailing return type | -| Compiler error C7649 | attribute 'xfg::rename' may only be applied to structs, classes and virtual methods | -| Compiler error C7650 | attribute 'xfg::rename' must be passed a string argument | +| Compiler error C7649 | attribute '`[[xfg::rename]]`' may only be applied to structs, classes and virtual methods | +| Compiler error C7650 | attribute '`[[xfg::rename]]`' must be passed a string argument | | Compiler error C7651 | %1$I cannot be used with /await. Use '%2$M' or later for standard coroutine support | | Compiler error C7652 | if a member function has a trailing requires clause then another member function with the same signature, ignoring any trailing requires clause, cannot be virtual | | Compiler error C7653 | '%1$S': failed to select a destructor for the class | @@ -173,15 +174,79 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C7656 | private module fragment cannot be redeclared | | Compiler error C7657 | private module fragment cannot be declared before a module declaration | | Compiler error C7658 | '%1$S': the initializer must be the address of a variable | -| Compiler error C7659 | attribute 'xfg::rename' may not be applied to nested class hierarchies | +| Compiler error C7659 | attribute '`[[xfg::rename]]`' may not be applied to nested class hierarchies | | Compiler error C7660 | '%s': requires '%s' command line option(s) | | Compiler error C7661 | header-name '%s' has an ambiguous resolution to header '%s' | | Compiler error C7662 | '%$S': a coroutine cannot be constexpr or consteval | +| Compiler error C7665 | '*operator*': you cannot assign to '`this`' as it is not an lvalue | +| Compiler error C7666 | you cannot apply '*operator*' to '`this`' as it is not an lvalue | +| Compiler error C7667 | no global `operator delete` function found | +| Compiler error C7668 | a function with an explicit object parameter must be a member function | +| Compiler error C7669 | a function with an explicit object parameter cannot be declared '`static`' | +| Compiler error C7670 | only the first parameter may be an explicit object parameter | +| Compiler error C7671 | a member function with an explicit object parameter may only have one such parameter | +| Compiler error C7672 | a member function with an explicit object parameter may not have trailing implicit object parameter specifiers | +| Compiler error C7673 | explicit object member functions requires at least '*C++ language version*' | +| Compiler error C7674 | member function '*function 1*' with explicit object parameter of type '*type 1*' cannot overload member function '*function 2*' with implicit object parameter of type '*type 2*' | +| Compiler error C7675 | cannot overload static member function with member function declaring the same non-object parameter types | +| Compiler error C7676 | member functions with an explicit object parameter cannot be defaulted | +| Compiler error C7677 | constructors cannot contain an explicit object parameter | +| Compiler error C7678 | member functions with an explicit object parameter cannot be virtual | +| Compiler error C7679 | an explicit object parameter cannot be a parameter pack | +| Compiler error C7680 | only function parameters may be explicit object parameters | +| Compiler error C7682 | '*declaration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration | +| Compiler error C7683 | you cannot create a reference to '`void`' | +| Compiler error C7684 | module name '*name*' has an ambiguous resolution to IFC | +| Compiler error C7685 | there is no type named '*identifier*' in '*type*' | +| Compiler error C7686 | attribute `[[msvc::constexpr]]` cannot be applied to a '`constexpr`' or '`consteval`' function | +| Compiler error C7687 | attribute `[[`*attribute*`]]` may only be applied to statements and functions | +| [Compiler error C7688](compiler-error-c7688.md) | '`#pragma omp atomic`': expected an expression of scalar type | +| Compiler error C7689 | attribute `[[msvc::intrinsic]]` cannot be applied to explicit specializations | +| Compiler error C7690 | attribute `[[msvc::intrinsic]]` cannot be applied to a recursive function | +| Compiler error C7691 | '`__super`' is not supported as '`/allowSuper-`' was specified | +| Compiler error C7692 | '*name*': rewritten candidate function was excluded from overload resolution because a corresponding `operator!=` declared in the same scope | +| Compiler error C7693 | constraints are not supported for managed types and constructs | +| Compiler error C7694 | managed type '*type*' used in a constraint definition or evaluation or in an entity that uses constraints | +| Compiler error C7695 | coroutine promise type '*type*' cannot be abstract | +| Compiler error C7696 | TOML parse error: *error name*; see '*TOML filename*' | +| Compiler error C7697 | '*header unit*' is not a recognized header-name lookup | +| Compiler error C7698 | '`__declspec(`*name*`(...))`' requires a single string argument | +| Compiler error C7699 | file mapping must be unique. Both '*name 1*' and '*name 2*' map to '*filename*' | | Compiler error C7700 | type '%$T' in _Generic association compatible with previous association type '%$T' | | Compiler error C7701 | default _Generic association previously specified | | Compiler error C7702 | no compatible type for '%$T' in _Generic association list | | Compiler error C7703 | inline nested namespaces requires at least '%1$M' | | Compiler error C7704 | '_Alignas' specifier can be used on variables and structure fields only | +| Compiler error C7705 | '`_Atomic`' type '*typename*' cannot be an array or function | +| Compiler error C7706 | '`_Atomic`' type '*typename*' cannot be atomic or CVR qualified | +| Compiler error C7707 | call to '*function*': argument type '*type*' must be a pointer to an atomic type | +| Compiler error C7708 | '*variable*': '`thread_local`' is only valid on variables at file or block scope | +| Compiler error C7709 | '*variable*': '`thread_local`' variables at block scope must be marked `static` | +| Compiler error C7710 | '*variable*': bit-fields cannot be atomic | +| Compiler error C7711 | '`_Atomic`' cannot be applied to incomplete type '*type*' | +| Compiler error C7712 | address argument to atomic operation must be a pointer to an atomic integer, '*type*' is not valid | +| Compiler error C7713 | a statement-expression may only appear inside a function body | +| Compiler error C7714 | the syntax for a 'statement-expression' is '`__extension__ ({ S1; ... ; Sn; })`' | +| Compiler error C7720 | bound for nested loop to be collapsed does not conform to the OpenMP specification | +| Compiler error C7730 | '`#`*directive*' directive requires '*language version*' or later | +| Compiler error C7731 | '*name*' is not allowed on a constructor declaration | +| Compiler error C7732 | expected an expression before '`]`' | +| Compiler error C7733 | the built-in subscript operator expects a single expression | +| Compiler error C7734 | '`size_t`' literal is out of range of possible '`size_t`' values | +| Compiler error C7735 | a lambda cannot be both '`static`' and '`mutable`' | +| Compiler error C7736 | a static lambda must have an empty capture-clause | +| Compiler error C7737 | a lambda with an explicit object parameter shall be neither '`mutable`' nor '`static`' | +| Compiler error C7738 | '`if consteval`' requires a compound statement | +| Compiler error C7739 | cannot jump from this `goto` statement to its label | +| Compiler error C7740 | cannot jump to case label | +| Compiler error C7741 | ABI inconsistency: '*function*' was originally assumed to use '`C`' return semantics but now it requires '`C++`' return semantics | +| Compiler error C7800 | duplicate explicit instantiation definition of '*name*' | +| Compiler error C7801 | '*function*': if one declaration of '*identifier*' has the '`[[msvc::disptach]]`' attribute then all functions must have the attribute | +| Compiler error C7802 | '*identifier*': a capability must resolve to an enumerator | +| Compiler error C7803 | '*identifier*': a capability must be associated with a non-overloaded, non-virtual function | +| Compiler error C7804 | '*identifier*': cannot find a matching default dispatch function | +| Compiler error C7806 | support for the '`msvc::dispatch`' attribute requires '`/experimental:loadTimeSelection`' | +| Compiler error C7807 | expecting a narrow string literal | ## See also diff --git a/docs/error-messages/compiler-warnings/c4371.md b/docs/error-messages/compiler-warnings/c4371.md index 0e51dcf410..aed32ad81b 100644 --- a/docs/error-messages/compiler-warnings/c4371.md +++ b/docs/error-messages/compiler-warnings/c4371.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4371" -title: "Compiler Warning (level 3) C4371" +description: "Learn more about: Compiler Warning (level 3, off) C4371" +title: "Compiler Warning (level 3, off) C4371" ms.date: "01/31/2018" f1_keywords: ["C4371"] helpviewer_keywords: ["C4371"] @@ -9,6 +9,6 @@ helpviewer_keywords: ["C4371"] > '*classname*': layout of class may have changed from a previous version of the compiler due to better packing of member '*member*' -If your code relies on a particular memory layout for a class, warning C4371 tells you that the layout created by the current compiler may be different from the layout generated by previous versions of the compiler. This may be significant for serialization operations or operating system interfaces that rely on a particular memory layout. In most other cases, this warning is safe to ignore. +Warning C4371 tells you that the layout created by the current compiler may be different from the layout generated by previous versions of the compiler. This difference may be significant for serialization operations or operating system interfaces that rely on a particular memory layout. In most other cases, this warning is safe to ignore. Warning C4371 is off by default. For more information, see [Compiler Warnings That Are Off By Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). diff --git a/docs/error-messages/compiler-warnings/c4388.md b/docs/error-messages/compiler-warnings/c4388.md index 1f8cc6b7f9..ee8b36db8d 100644 --- a/docs/error-messages/compiler-warnings/c4388.md +++ b/docs/error-messages/compiler-warnings/c4388.md @@ -1,11 +1,11 @@ --- -title: "Compiler Warning (level 4) C4388" -description: "Microsoft C/C++ compiler warning C4388, its causes and resolution." +title: "Compiler Warning (level 4, off) C4388" +description: "Learn more about: Compiler Warning (level 4, off) C4388" ms.date: 10/16/2020 f1_keywords: ["C4388"] helpviewer_keywords: ["C4388"] --- -# Compiler Warning (level 4) C4388 +# Compiler Warning (level 4, off) C4388 > '*token*' : signed/unsigned mismatch diff --git a/docs/error-messages/compiler-warnings/c4770.md b/docs/error-messages/compiler-warnings/c4770.md new file mode 100644 index 0000000000..3acd9eddc4 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c4770.md @@ -0,0 +1,53 @@ +--- +description: "Learn more about: Compiler Warning (level 4) C4770" +title: "Compiler Warning (level 4) C4770" +ms.date: 11/02/2022 +f1_keywords: ["C4770"] +helpviewer_keywords: ["C4770"] +--- +# Compiler Warning (level 4) C4770 + +> partially validated enum '*symbol*' used as index + +The compiler warns if an enum value is cast or aliased to an integer type, but the result isn't checked for non-negative or excessive values. + +## Remarks + +This warning is new in Visual Studio 2013. It's not enabled by default. To enable it as a level 1 warning, use `/w14770`. For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). + +## Example + +The following code produces warning C4770: + +```cpp +// c4770.cpp +// compile by using: cl /GL /w14770 c4770.cpp + +enum E { a 0, b, c, E_MAX }; + +int main(int argc, char *argv[]) +{ + const E e1 = E(argc); // value unknown at compile time + + if ((int)(e1) >= E_MAX) + return 0; + + const int n = e1 + e1; // C4770 partially validated enum used as index + + return argv[n][n]; +} +``` + +To fix the warning, you could cast the value in the check to `unsigned int`, which implicitly forces a non-negative value: + +```cpp + if ((unsigned int)(e1) >= E_MAX) + return 0; +``` + +Or, explicitly check for a non-negative value: + +```cpp + if ((int)(e1) >= E_MAX || (int)(e1) < 0) + return 0; +``` diff --git a/docs/error-messages/compiler-warnings/c4834.md b/docs/error-messages/compiler-warnings/c4834.md index 99cb8784ad..7012f5c3c6 100644 --- a/docs/error-messages/compiler-warnings/c4834.md +++ b/docs/error-messages/compiler-warnings/c4834.md @@ -1,7 +1,7 @@ --- description: "Learn about the cause and fixes for Compiler warning (level 1) C4834." title: "Compiler warning (Level 1) C4834" -ms.date: 07/26/2021 +ms.date: 01/18/2024 f1_keywords: ["C4834"] helpviewer_keywords: ["C4834"] --- @@ -11,9 +11,10 @@ helpviewer_keywords: ["C4834"] ## Remarks -Starting in the C++17 Standard, the `[[nodiscard]]` attribute specifies that a function's return value isn't intended to be discarded. If a caller discards the return value, the compiler generates warning C4834. +Starting in the C++17 Standard, the `[[nodiscard]]` attribute specifies that a function's return value isn't intended to be discarded. If a caller discards the return value, the compiler generates warning C4834. Although this attribute was introduced in C++17, the compiler respects this attribute and generates warnings related to it when using `/std:c++14` and later. -To resolve this warning, consider why your code doesn't use the return value. Your use of the function may not match its intent. You can circumvent the warning by using a cast to **`void`**. +To resolve this warning, consider why your code doesn't use the return value. Your use of the function may not match its intent. You can circumvent the warning by assigning the value to **`std::ignore`** or by casting it to **`void`** if discarding the value is intentional. +Assignment to **`std::ignore`** is preferred over casting to **`void`** in C++11 and higher, as it makes your intent clearer and will not trigger [Warning C26457](../../code-quality/c26457.md) if enabled in your code analysis settings. This warning was introduced in Visual Studio 2017 version 15.3 as a level 3 warning. It was changed to a level 1 warning in Visual Studio 2017 version 15.7. Code that compiled without warnings in versions of the compiler before Visual Studio 2017 version 15.3 can now generate C4834. For information on how to disable warnings introduced in a particular compiler version or later, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). @@ -29,7 +30,7 @@ To turn off the warning for an entire project in the Visual Studio IDE: ## Example -This sample generates C4834, and shows a way to fix it: +This sample generates C4834, and shows four ways to fix it: ```cpp // C4834.cpp @@ -42,8 +43,19 @@ int square_of(int i) { return i * i; } int main() { square_of(42); // warning C4834: discarding return value of function with 'nodiscard' attribute - // to fix, make use of the return value, as shown here: - // std::cout << "square_of(42) = " << square_of(42) << "\n"; + // If ignoring the [[nodiscard] attribute is unintentional, make use of the return value as intended: + // For example: + std::cout << "square_of(42) = " << square_of(42) << "\n"; // Ok + // Or: + int result = square_of(43); // Ok + std::cout << "square_of(43) = " << result << "\n"; + + // If ignoring the [[nodiscard]] attribute value is intentional, you have two options: + // Preferrably, assign the return value to std::ignore: + std::ignore = square_of(42); // Ok, C++11 and higher + // Alternatively, you can cast the return value to void. + // The intent may be less clear to other developers. + (void) square_of(42); // May produce warning C26457 return 0; } ``` diff --git a/docs/error-messages/compiler-warnings/c5054.md b/docs/error-messages/compiler-warnings/c5054.md new file mode 100644 index 0000000000..ba2e219746 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5054.md @@ -0,0 +1,42 @@ +--- +title: "Compiler Warning C5054" +description: Compiler warning C5054 description and solution. +ms.date: 02/22/2022 +f1_keywords: ["C5054"] +helpviewer_keywords: ["C5054"] +--- +# Compiler warning (level 4) C5054 + +> operator '*operator-name*': deprecated between enumerations of different types + +## Remarks + +C++20 has deprecated the usual arithmetic conversions on operands, where one operand is of enumeration type and the other is of a different enumeration type. For more information, see C++ Standard proposal [P1120R0](https://wg21.link/p1120r0). + +In Visual Studio 2019 version 16.2 and later, an implicit conversion between enumeration types produces a level 4 warning when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**. + +## Example + +In Visual Studio 2019 version 16.2 and later, the following code produces a level 4 warning when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**: + +```cpp +// C5054.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5054.cpp +enum E1 { a }; +enum E2 { b }; +int main() { + int i = a | b; // warning C5054: operator '|': deprecated between enumerations of different types +} +``` + +To avoid the warning, use [`static_cast`](../../cpp/static-cast-operator.md) to convert the second operand: + +```cpp +// C5054_fixed.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5054_fixed.cpp +enum E1 { a }; +enum E2 { b }; +int main() { + int i = a | static_cast(b); +} +``` diff --git a/docs/error-messages/compiler-warnings/c5055.md b/docs/error-messages/compiler-warnings/c5055.md new file mode 100644 index 0000000000..4cca582e6c --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5055.md @@ -0,0 +1,40 @@ +--- +title: "Compiler Warning C5055" +description: Compiler warning C5055 description and solution. +ms.date: 02/22/2022 +f1_keywords: ["C5055"] +helpviewer_keywords: ["C5055"] +--- +# Compiler warning (level 1) C5055 + +> operator '*operator-name*': deprecated between enumerations and floating-point types + +## Remarks + +C++20 has deprecated the usual arithmetic conversions on operands, where one operand is of enumeration type and the other is of floating-point type. For more information, see C++ Standard proposal [P1120R0](https://wg21.link/p1120r0). + +In Visual Studio 2019 version 16.2 and later, an implicit conversion between enumeration types and floating-point types produces a level 1 warning when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**. + +## Example + +In Visual Studio 2019 version 16.2 and later, a binary operation between an enumeration and a floating-point type produces a level 1 warning when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**: + +```cpp +// C5055.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5055.cpp +enum E1 { a }; +int main() { + double i = a * 1.1; // Warning C5055: operator '*': deprecated between enumerations and floating-point types +} +``` + +To avoid the warning, use [`static_cast`](../../cpp/static-cast-operator.md) to convert the second operand: + +```cpp +// C5055_fixed.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5055_fixed.cpp +enum E1 { a }; +int main() { + double i = static_cast(a) * 1.1; +} +``` diff --git a/docs/error-messages/compiler-warnings/c5056.md b/docs/error-messages/compiler-warnings/c5056.md new file mode 100644 index 0000000000..cb757f7ad9 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5056.md @@ -0,0 +1,48 @@ +--- +title: "Compiler Warning C5056" +description: Compiler warning C5056 description and solution. +ms.date: 02/22/2022 +f1_keywords: ["C5056"] +helpviewer_keywords: ["C5056"] +--- +# Compiler warning (level 1) C5056 + +> operator '*operator-name*': deprecated for array types + +## Remarks + +Equality and relational comparisons between two operands of array type are deprecated in C++20. For more information, see C++ Standard proposal [P1120R0](https://wg21.link/p1120r0). + +In Visual Studio 2019 version 16.2 and later, a comparison operation between two arrays (despite rank and extent similarities) now produces a level 1 C5056 warning when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**. + +## Example + +In Visual Studio 2019 version 16.2 and later, the following code produces warning C5056 when the **`/std:c++latest`** compiler option is enabled. In Visual Studio 2019 version 16.11 and later, it also produces a warning under **`/std:c++20`**: + +```cpp +// C5056.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5056.cpp +int main() { + int a[] = { 1, 2, 3 }; + int b[] = { 1, 2, 3 }; + if (a == b) { return 1; } // warning C5056: operator '==': deprecated for array types +} +``` + +To avoid the warning, you can compare the addresses of the first elements: + +```cpp +// C5056_fixed.cpp +// Compile using: cl /EHsc /W4 /std:c++latest C5056_fixed.cpp +int main() { + int a[] = { 1, 2, 3 }; + int b[] = { 1, 2, 3 }; + if (&a[0] == &b[0]) { return 1; } +} +``` + +To determine whether the contents of two arrays are equal, use the [`std::equal`](../../standard-library/algorithm-functions.md#equal) function: + +```cpp +std::equal(std::begin(a), std::end(a), std::begin(b), std::end(b)); +``` diff --git a/docs/error-messages/compiler-warnings/c5240.md b/docs/error-messages/compiler-warnings/c5240.md new file mode 100644 index 0000000000..8389182d68 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5240.md @@ -0,0 +1,44 @@ +--- +title: "Compiler Warning C5240" +description: Compiler warning C5240 description and solution. +ms.date: 02/22/2022 +f1_keywords: ["C5240"] +helpviewer_keywords: ["C5240"] +--- +# Compiler Warning (level 4, off) C5240 + +> '*attribute-string*': attribute is ignored in this syntactic position + +## Remarks + +Warning C5240 occurs when a `[[nodiscard]]` or `[[maybe_unused]]` attribute is found in the wrong syntactic position. For example, the `[[nodiscard]]` attribute in this syntactic position applies to the *`decl-specifier-seq`*, not to the function `f`: + +```cpp +static [[nodiscard]] int f() { return 1; } +``` + +Before Visual Studio 2019 version 16.10, the compiler would silently ignore uses of a `[[nodiscard]]` or `[[maybe_unused]]` attribute in a syntactic position that didn't apply to the function or object being declared. In Visual Studio 2019 version 16.10 and later, the compiler emits off-by-default level 4 warning C5240 instead. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). + +## Example + +The following example shows how warning 5240 can occur: + +```cpp +// c5240.cpp +// Compile using: cl /EHsc /W4 /std:c++17 /permissive- /c c5240.cpp +#pragma warning( default: 5240 ) +static [[nodiscard]] int f() { return 1; } // C5240 +``` + +To fix this issue, move the attribute to the correct syntactic position: + +```cpp +// c5240_fixed.cpp +// Compile using: cl /EHsc /W4 /std:c++17 /permissive- /c c5240_fixed.cpp +#pragma warning( default: 5240 ) +[[nodiscard]] static int f() { return 1; } // OK +``` + +## See also + +[Attributes in C++](../../cpp/attributes.md) diff --git a/docs/error-messages/compiler-warnings/c5243.md b/docs/error-messages/compiler-warnings/c5243.md index a2fabbb18e..0679327d67 100644 --- a/docs/error-messages/compiler-warnings/c5243.md +++ b/docs/error-messages/compiler-warnings/c5243.md @@ -1,5 +1,5 @@ --- -title: "Compiler Warning C5243" +title: Compiler warning C5243 description: Compiler warning C5243 description and solution. ms.date: 08/09/2021 f1_keywords: ["C5243"] @@ -11,7 +11,7 @@ helpviewer_keywords: ["C5243"] ## Remarks -The Microsoft C++ ABI in Visual Studio 2019 and earlier versions uses more than one kind of pointer-to-member type. These types have different sizes that depend on the inheritance model used by the class. The C++ standard allows you to declare a pointer-to-member of an incomplete class type. If you declare a variable of pointer-to-member type for an incomplete class, the compiler must use the most general representation. It can lead to a *one definition rule*, or ODR violation, since the compiler may use a smaller, more specific representation for this pointer-to-member type in other translation units where the complete class type is available. +The Microsoft C++ ABI uses more than one kind of pointer-to-member type. These types have different sizes that depend on the inheritance model used by the class. The C++ standard allows you to declare a pointer-to-member of an incomplete class type. If you declare a variable of pointer-to-member type for an incomplete class, the compiler must use the most general representation. It can lead to a *one definition rule*, or ODR violation, since the compiler may use a smaller, more specific representation for this pointer-to-member type in other translation units where the complete class type is available. To resolve this error, you can specify the complete class type before you declare the pointer-to-member variable. Or, use a Microsoft-specific [inheritance keyword](../../cpp/inheritance-keywords.md) to specify the correct inheritance model on the incomplete forward class declaration. diff --git a/docs/error-messages/compiler-warnings/c5262.md b/docs/error-messages/compiler-warnings/c5262.md new file mode 100644 index 0000000000..d51098ead1 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5262.md @@ -0,0 +1,60 @@ +--- +title: "Compiler warning (level 1, error, off) C5262" +description: Compiler warning C5262 description and solution. +ms.date: 03/01/2023 +f1_keywords: ["C5262"] +helpviewer_keywords: ["C5262"] +--- +# Compiler warning (level 1, error, off) C5262 + +> implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases + +## Remarks + +Control flow that implicitly falls between cases of switch statements is a historical source of bugs for both C and C++. While we had the `__fallthrough` SAL macro, it wasn't useful for the build-compiler diagnostics. Since customers have legacy code that "falls through" on purpose, it isn't viable to give an actionable warning without some way of indicating an intentional fall through. In C++17, the `[[fallthrough]]` attribute was added to indicate such an instance. The compiler can take this attribute into account and suppress the new warning. + +Compiler warning C5262 is new in Visual Studio 2022 version 17.4, and is both off by default and treated as an error by default when enabled. To continue to support legacy code without build breaks, C5262 must be explicitly enabled. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). + +## Example + +The sample code shows diagnostics for `switch` cases that fall through without `break` or `return` statements or the `[[fallthrough]]` attribute. + +```cpp +// C5262.cpp +// compile using /std:c++17 /we5262 + +int main(int argc, char** argv) +{ + switch (argc) + { + case 0: ++argv; + case 1: + case 2: argv++; + default: + argv = 0; + } +} + +/* +When built, the compiler produces this output: + +.\C5262.cpp(9,9): error C5262: implicit fall-through occurs here; are you missing a break statement? Use [[fallthrough]] when a break statement is intentionally omitted between cases + case 1: + ^ +.\C5262.cpp(8,17): note: statement that may fall through is here + case 0: ++argv; + ^ +.\C5262.cpp(11,9): error C5262: implicit fall-through occurs here; are you missing a break statement? Use [[fallthrough]] when a break statement is intentionally omitted between cases + default: + ^ +.\C5262.cpp(10,17): note: statement that may fall through is here + case 2: argv++; +*/ +``` + +To resolve this issue when the control flow between cases is intentional, use the `[[fallthrough]]` attribute. + +## See also + +[`switch` statement (C++)](../../cpp/switch-statement-cpp.md)\ +[`[[fallthrough]]` attribute](../../cpp/attributes.md#fallthrough) diff --git a/docs/error-messages/compiler-warnings/c5267.md b/docs/error-messages/compiler-warnings/c5267.md new file mode 100644 index 0000000000..23b1a7a5db --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5267.md @@ -0,0 +1,56 @@ +--- +title: "Compiler warning C5267" +description: Learn about compiler warning C5267 +ms.date: 11/08/2023 +f1_keywords: ["C5267"] +helpviewer_keywords: ["C5267"] +--- +# Compiler warning (level 4) C5267 + +> definition of implicit copy constructor/assignment operator for '*type*' is deprecated because it has a user-provided assignment operator/copy constructor + +## Remarks + +The C++ Standard deprecated (but didn't remove) the implicit generation of copy and assignment operators under some conditions. The MSVC compiler still generates the copy and assignment operators under those conditions, but may change its behavior in the future if the standard removes the deprecated behavior. The purpose of this warning is to help future proof your code if the committee decides to remove this functionality. + +The relevant sections in the C++ standard are: +- [class.copy.ctor paragraph 6](https://eel.is/c++draft/class.copy.ctor#6), which says: "If the class definition does not explicitly declare a copy constructor, a nonexplicit one is declared implicitly. If the class definition declares a move constructor or move assignment operator, the implicitly declared copy constructor is defined as deleted; otherwise, it is defaulted. The latter case is deprecated if the class has a user-declared copy assignment operator or a user-declared destructor." +- [Annex D D.8](https://eel.is/c++draft/depr.impldec#1), which says: "The implicit definition of a copy constructor as defaulted is deprecated if the class has a user-declared copy assignment operator or a user-declared destructor. The implicit definition of a copy assignment operator as defaulted is deprecated if the class has a user-declared copy constructor or a user-declared destructor. It's possible that future versions of C++ will specify that these implicit definitions are deleted." + +## Example + +The following code shows warning C5267 when an implicitly generated special function is called but isn't explicitly defined. Both `/W4` and `/w45267` are required to produce this warning. + +```cpp +// C5267.cpp +// compile using: /W4 /w45267 +struct CopyCtorOnly +{ + CopyCtorOnly() = default; + CopyCtorOnly(const CopyCtorOnly&) {} // C5267 +}; + +struct CopyAssignOpOnly +{ + CopyAssignOpOnly() = default; + CopyAssignOpOnly& operator=(const CopyAssignOpOnly&) // C5267 + { + return *this; + } +}; + +int main() +{ + CopyCtorOnly a1, a2; + a1 = a2; // Calls deprecated copy assignment operator + + CopyAssignOpOnly b1; + CopyAssignOpOnly b2 = b1; // Calls deprecated copy constructor +} +``` + +To resolve this issue, explicitly define the missing copy constructor or copy assignment operator. + +## See also + +[Explicitly Defaulted and Deleted Functions](../../cpp/explicitly-defaulted-and-deleted-functions.md) diff --git a/docs/error-messages/compiler-warnings/c5301-c5302.md b/docs/error-messages/compiler-warnings/c5301-c5302.md new file mode 100644 index 0000000000..0283c7f2f6 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c5301-c5302.md @@ -0,0 +1,48 @@ +--- +title: "Compiler warnings (level 1) C5301 and C5302" +description: Compiler warnings C5301 and C5302 description and solution. +ms.date: 03/01/2023 +f1_keywords: ["C5301", "C5302"] +helpviewer_keywords: ["C5301", "C5302"] +--- +# Compiler warnings (level 1) C5301 and C5302 + +> '`#pragma omp for`': '*loop-index*' increases while loop condition uses '*comparison*'; non-terminating loop? + +> '`#pragma omp for`': '*loop-index*' decreases while loop condition uses '*comparison*'; non-terminating loop? + +## Remarks + +Along with improved support for OpenMP 3.1, we've added two diagnostics, C5301 and C5302, to improve the developer experience. These diagnostics check that the loop conditions for `omp parallel for` are correct, based on whether the loop index variable is increasing or decreasing. These checks work for both integral and pointer indices. + +These compiler warnings are new in Visual Studio 2022 version 17.4. + +## Example + +The sample code shows a diagnostic for a `for` loop that decrements the index, but it uses a `<=` comparison that tests whether the index is less than a value higher than the starting value. + +```C +// C5302.c +// compile using /openmp + +#include + +int main() +{ + int a[100], i; + int k = 1; + #pragma omp parallel for + for (i = 0; i <= 100; i--) + a[i] = i*i; +} + +/* +Compiler warning message: + +.\C5302.c(11,19): warning C5302: '#pragma omp for': 'i' decreases while loop condition uses '<='; non-terminating loop? + for (i = 0; i <= 100; i--) + ^ +*/ +``` + +To resolve this issue, change the test condition or the direction of the index change to one that terminates without causing overflow, underflow, or other undefined behavior. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4335.md b/docs/error-messages/compiler-warnings/compiler-warning-c4335.md index 3ec3cdd5d3..e57e115b0b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4335.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4335.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning C4335" -title: "Compiler Warning C4335" +description: "Learn more about: Compiler Warning (level 1) C4335" +title: "Compiler Warning(level 1) C4335" ms.date: "11/04/2016" f1_keywords: ["C4335"] helpviewer_keywords: ["C4335"] -ms.assetid: e66467ad-a10b-4438-8c7c-e8e8d11d39bb --- -# Compiler Warning C4335 +# Compiler Warning (level 1) C4335 -Mac file format detected: please convert the source file to either DOS or UNIX format +> Mac file format detected: please convert the source file to either DOS or UNIX format -The line termination character of the first line of a source file is Macintosh style ('\r') as opposed to UNIX ('\n') or DOS ('\r\n'). +The line termination character of the first line of a source file is the old Macintosh style ('\r') as opposed to UNIX ('\n') or DOS ('\r\n'). -This warning is always issued as an error. See [warning](../../preprocessor/warning.md) pragma for information about how to disable this warning. Also, this warning is only issued once per compiland. Therefore, if there are multiple `#include` directives that specify files in Macintosh format, C4335 will only be issued once. +This warning is only issued once per translation unit. Therefore, if there are multiple `#include` directives that specify files in Macintosh format, C4335 is emitted once. One way to generate files in Macintosh format is by using the **Advanced Save Options** (on the **File** menu) in Visual Studio. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4355.md b/docs/error-messages/compiler-warnings/compiler-warning-c4355.md index 24633d26bd..f32d4d86f9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4355.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4355.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Compiler Warning C4355" -title: "Compiler Warning C4355" +description: "Learn more about: Compiler Warning (level 1 and level 4, off) C4355" +title: "Compiler Warning (level 1 and level 4, off) C4355" ms.date: "11/04/2016" f1_keywords: ["C4355"] helpviewer_keywords: ["C4355"] -ms.assetid: b819ecab-8a07-42d7-8fa4-1180d51626c0 --- -# Compiler Warning C4355 +# Compiler Warning (level 1 and level 4, off) C4355 -'this' : used in base member initializer list +> '`this`': used in base member initializer list -The **`this`** pointer is valid only within nonstatic member functions. It cannot be used in the initializer list for a base class. +The `this` pointer is valid only within nonstatic member functions. It can't be used in the initializer list for a base class. -The base-class constructors and class member constructors are called before **`this`** constructor. In effect, you've passed a pointer to an unconstructed object to another constructor. If those other constructors access any members or call member functions on this, the result will be undefined. You should not use the **`this`** pointer until all construction has completed. +The base-class constructors and class member constructors are called before `this` constructor. This pattern is the same as passing a pointer to an unconstructed object to another constructor. If those other constructors access any members or call member functions on `this`, the result is undefined. You shouldn't use the `this` pointer until all construction is complete. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4355: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4368.md b/docs/error-messages/compiler-warnings/compiler-warning-c4368.md index 7808f627b5..0d5f930532 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4368.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4368.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning C4368" -title: "Compiler Warning C4368" +description: "Learn more about: Compiler Warning (level 1, Error) C4368" +title: "Compiler Warning (level 1, Error) C4368" ms.date: "11/04/2016" f1_keywords: ["C4368"] helpviewer_keywords: ["C4368"] -ms.assetid: cb85bcee-fd3d-4aa5-b626-2324f07a4f1b --- -# Compiler Warning C4368 +# Compiler Warning (level 1, Error) C4368 -cannot define 'member' as a member of managed 'type': mixed types are not supported +> cannot define 'member' as a member of managed 'type': mixed types are not supported -You cannot embed a native data member in a CLR type. +You can't embed a native data member in a managed type. -You can, however, declare a pointer to a native type and control its lifetime in the constructor and destructor and finalizer of your managed class. For more information see [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). +You can, however, declare a pointer to a native type and control its lifetime in the constructor and destructor and finalizer of your managed class. For more information, see [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable C4368. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4394.md b/docs/error-messages/compiler-warnings/compiler-warning-c4394.md index 95e4d0660a..d49d391ea0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4394.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4394.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Compiler Warning C4394" -title: "Compiler Warning C4394" +description: "Learn more about: Compiler Warning (level 1, Error) C4394" +title: "Compiler Warning (level 1, Error) C4394" ms.date: "11/04/2016" f1_keywords: ["C4394"] helpviewer_keywords: ["C4394"] -ms.assetid: 5de94de0-17e3-4e7c-92f4-5c3c1b825120 --- -# Compiler Warning C4394 +# Compiler Warning (level 1, Error) C4394 -'function' : per-appdomain symbol should not be marked with __declspec(dllexport) +> 'function' : per-appdomain symbol should not be marked with __declspec(dllexport) -A function marked with the [appdomain](../../cpp/appdomain.md) **`__declspec`** modifier is compiled to MSIL (not to native), and export tables ([export](../../windows/attributes/export.md) **`__declspec`** modifier) are not supported for managed functions. +A function marked with the [appdomain](../../cpp/appdomain.md) **`__declspec`** modifier is compiled to MSIL (not native), and export tables ([export](../../windows/attributes/export.md) **`__declspec`** modifier) aren't supported for managed functions. You can declare a managed function to have public accessibility. For more information, see [Type visibility](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Type_visibility) and [Member visibility](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Member_visibility). -C4394 is always issued as an error. You can turn off this warning with the `#pragma warning` or **/wd**; see [warning](../../preprocessor/warning.md) or [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](../../build/reference/compiler-option-warning-level.md) for more information. +C4394 is always issued as an error. You can turn off this warning or change its level with `#pragma warning` or **/wd**. For more information, see [warning](../../preprocessor/warning.md) or [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](../../build/reference/compiler-option-warning-level.md). ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4430.md b/docs/error-messages/compiler-warnings/compiler-warning-c4430.md index 15c04e3b0f..6814fb10c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4430.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4430.md @@ -1,36 +1,33 @@ --- -description: "Learn more about: Compiler Warning C4430" -title: "Compiler Warning C4430" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1, error) C4430" +title: "Compiler warning (level 1, error) C4430" +ms.date: 04/22/2025 f1_keywords: ["C4430"] helpviewer_keywords: ["C4430"] -ms.assetid: 12efbfff-aa58-4a86-a7d6-2c6a12d01dd3 --- -# Compiler Warning C4430 +# Compiler Warning (level 1, Error) C4430 -missing type specifier - int assumed. Note: C++ does not support default-int +> missing type specifier - int assumed. Note: C++ does not support default-int -This error can be generated as a result of compiler conformance work that was done for Visual Studio 2005: all declarations must explicitly specify the type; int is no longer assumed. +This warning is issued when a type specifier is missing in a declaration. The compiler used to assume the type was `int` in this case. But due to compiler conformance work done for Visual Studio 2005, all declarations must explicitly specify the type. -C4430 is always issued as an error. You can turn off this warning with the `#pragma warning` or **/wd**; see [warning](../../preprocessor/warning.md) or [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](../../build/reference/compiler-option-warning-level.md) for more information. +C4430 is always issued as an error. You can turn off this warning with the `#pragma warning` or `/wd`. For more information, see [`warning`](../../preprocessor/warning.md) or [`/w`, `/W0`, `/W1`, `/W2`, `/W3`, `/W4`, `/w1`, `/w2`, `/w3`, `/w4`, `/Wall`, `/wd`, `/we`, `/wo`, `/Wv`, `/WX` (Warning Level)](../../build/reference/compiler-option-warning-level.md). ## Example -The following sample generates C4430. +The following sample generates C4430: ```cpp -// C4430.cpp // compile with: /c struct CMyClass { CUndeclared m_myClass; // C4430 - int m_myClass; // OK }; typedef struct { - POINT(); // C4430 - // try the following line instead - // int POINT(); + someFunction(); // C4430 unsigned x; unsigned y; } POINT; ``` + +To fix this code, you'd need to define the type `CUndeclared` and the function `someFunction` prior to their use. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4439.md b/docs/error-messages/compiler-warnings/compiler-warning-c4439.md index f8d402b838..9608a6c02c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4439.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4439.md @@ -1,22 +1,21 @@ --- -description: "Learn more about: Compiler Warning C4439" -title: "Compiler Warning C4439" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1, error) C4439" +title: "Compiler warning (level 1, error) C4439" +ms.date: "1/22/2025" f1_keywords: ["C4439"] helpviewer_keywords: ["C4439"] -ms.assetid: 9449958f-f407-4824-829b-9e092f2af97d --- -# Compiler Warning C4439 +# Compiler warning C4439 -'function' : function definition with a managed type in the signature must have a __clrcall calling convention +> '*function name*': function definition with a managed type in the signature must have a `__clrcall` calling convention The compiler implicitly replaced a calling convention with [`__clrcall`](../../cpp/clrcall.md). To resolve this warning, remove the **`__cdecl`** or **`__stdcall`** calling convention. -C4439 is always issued as an error. You can turn off this warning with the `#pragma warning` or **`/wd`**; see [warning](../../preprocessor/warning.md) or [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](../../build/reference/compiler-option-warning-level.md) for more information. +C4439 is always issued as an error. You can turn off this warning with the `#pragma warning` or **`/wd`**. For more information, see [`warning`](../../preprocessor/warning.md) or [`/w`, `/W0`, `/W1`, `/W2`, `/W3`, `/W4`, `/w1`, `/w2`, `/w3`, `/w4`, `/Wall`, `/wd`, `/we`, `/wo`, `/Wv`, `/WX` (Warning Level)](../../build/reference/compiler-option-warning-level.md). ## Example -The following sample generates C4439. +The following sample generates C4439: ```cpp // C4439.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4746.md b/docs/error-messages/compiler-warnings/compiler-warning-c4746.md index 50e340f6be..04491bb8f1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4746.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4746.md @@ -8,9 +8,9 @@ ms.assetid: 5e79ab46-6031-499a-a986-716c866b6c0e --- # Compiler Warning C4746 -volatile access of '\' is subject to /volatile:[iso|ms] setting; consider using __iso_volatile_load/store intrinsic functions. +volatile access of '\' is subject to /volatile:[iso\|ms] setting; consider using __iso_volatile_load/store intrinsic functions. -C4746 is emitted whenever a volatile variable is accessed directly. It is intended to help developers identify code locations that are affected by the specific volatile model currently specified (which can be controlled with the [/volatile](../../build/reference/volatile-volatile-keyword-interpretation.md) compiler option). In particular, it can be useful in locating compiler-generated hardware memory barriers when /volatile:ms is used. +C4746 is emitted whenever a volatile variable is accessed directly. It's intended to help developers identify code locations that are affected by the specific volatile model currently specified (which can be controlled with the [`/volatile`](../../build/reference/volatile-volatile-keyword-interpretation.md) compiler option). In particular, it can be useful in locating compiler-generated hardware memory barriers when `/volatile:ms` is used. The __iso_volatile_load/store intrinsics can be used to explicitly access volatile memory without being affected by the volatile model. Using these intrinsics will not trigger C4746. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c5072.md b/docs/error-messages/compiler-warnings/compiler-warning-c5072.md new file mode 100644 index 0000000000..b3216cb81b --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warning-c5072.md @@ -0,0 +1,26 @@ +--- +description: "Learn more about: Compiler Warning (level 1) C5072" +title: "Compiler Warning (level 1) C5072" +ms.date: 02/09/2024 +f1_keywords: ["C5072"] +helpviewer_keywords: ["C5072"] +--- +# Compiler Warning (level 1) C5072 + +> ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting + +This warning occurs when you compile with [Address Sanitizer](/cpp/sanitizers/asan) (ASAN) turned on, but you don't also instruct the compiler to emit debug info. ASAN uses debug info to provide better diagnostics. + +## Example + +The following command line generates warning `C5072`: + +```cpp + cl /fsanitize=address /EHsc test.cpp +``` + +To fix it, have the compiler generate debug information by using a switch like [`/Zi`](/cpp/build/reference/z7-zi-zi-debug-information-format#zi) or [`/Z7`](/cpp/build/reference/z7-zi-zi-debug-information-format#z7), like this: `cl /fsanitize=address /EHsc /Zi test.cpp` + +## See also + +[Address Sanitizer (ASAN)](/cpp/sanitizers/asan) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md index 81b4c94e93..db6a5e55dc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Compiler Warning (level 1 and level 4) C4700" title: "Compiler Warning (level 1 and level 4) C4700" -ms.date: "02/21/2018" +ms.date: 08/30/2022 f1_keywords: ["C4700"] helpviewer_keywords: ["C4700"] ms.assetid: 2da0deb4-77dd-4b05-98d3-b78d74ac4ca7 @@ -10,13 +10,17 @@ ms.assetid: 2da0deb4-77dd-4b05-98d3-b78d74ac4ca7 > uninitialized local variable '*name*' used -The local variable *name* has been *used*, that is, read from, before it has been assigned a value. In C and C++, local variables are not initialized by default. Uninitialized variables can contain any value, and their use leads to undefined behavior. Warning C4700 almost always indicates a bug that can cause unpredictable results or crashes in your program. +## Remarks -To fix this issue, you can initialize local variables when they are declared, or assign a value to them before they are used. A function can be used to initialize a variable that's passed as a reference parameter, or when its address is passed as a pointer parameter. +The local variable *name* has been *used*, that is, read from, before it has been assigned a value. In C and C++, local variables aren't initialized by default. Uninitialized variables can contain any value, and their use leads to undefined behavior. Warning C4700 almost always indicates a bug that can cause unpredictable results or crashes in your program. + +To fix this issue, you can initialize local variables when they're declared, or assign a value to them before they're used. A function can be used to initialize a variable that's passed as a reference parameter, or when its address is passed as a pointer parameter. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example -This sample generates C4700 when variables t, u, and v are used before they are initialized, and shows the kind of garbage value that can result. Variables x, y, and z do not cause the warning, because they are initialized before use: +This sample generates C4700 when variables `t`, `u`, and `v` are used before they're initialized, and shows the kind of garbage value that can result. Variables `x`, `y`, and `z` don't cause the warning, because they're initialized before use: ```cpp // c4700.cpp @@ -46,7 +50,7 @@ int main() } ``` -When this code is run, t, u, and v are uninitialized, and the output for s is unpredictable: +When this code is run, `t`, `u`, and `v` are uninitialized, and the output for `s` is unpredictable: ```Output Value in s: 37816963 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4002.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4002.md index eb79eb1e82..18d513c787 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4002.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4002.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4002" -title: "Compiler Warning (level 1) C4002" +description: "Learn more about: Compiler Warning (level 1, Error) C4002" +title: "Compiler Warning (level 1, Error) C4002" ms.date: "11/04/2016" f1_keywords: ["C4002"] helpviewer_keywords: ["C4002"] -ms.assetid: 6bda1dfe-e2e4-4771-9794-5a404c466dd5 --- -# Compiler Warning (level 1) C4002 +# Compiler Warning (level 1, Error) C4002 -too many actual parameters for macro 'identifier' +> too many arguments for function-like macro invocation '*identifier*' The number of actual parameters in the macro exceeds the number of formal parameters in the macro definition. The preprocessor collects the extra parameters but ignores them during macro expansion. -C4002 can occur when incorrectly using [Variadic Macros](../../preprocessor/variadic-macros.md). +C4002 can occur when incorrectly using [variadic macros](../../preprocessor/variadic-macros.md). The following sample generates C4002: @@ -32,7 +31,7 @@ int main() { This error can also be generated as a result of compiler conformance work that was done for Visual Studio .NET 2003: extra commas in macro no longer accepted. -The compiler will no longer accept extra commas in a macro. For code to be valid in both the Visual Studio .NET 2003 and Visual Studio .NET versions of Visual C++, remove the extra commas. +The compiler no longer accepts extra commas in a macro. For code to be valid in both the Visual Studio .NET 2003 and Visual Studio .NET versions of Visual C++, remove the extra commas. ```cpp // C4002b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4003.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4003.md index da9d1a36c9..360f59e894 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4003.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4003.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4003" -title: "Compiler Warning (level 1) C4003" +description: "Learn more about: Compiler Warning (level 1, Error) C4003" +title: "Compiler Warning (level 1, Error) C4003" ms.date: "11/04/2016" f1_keywords: ["C4003"] helpviewer_keywords: ["C4003"] -ms.assetid: 0ed1c285-4428-4c90-8131-86897e31f115 --- -# Compiler Warning (level 1) C4003 +# Compiler Warning (level 1, Error) C4003 -not enough actual parameters for macro 'identifier' +> not enough arguments for function-like macro invocation '*identifier*' The number of formal parameters in the macro definition exceeds the number of actual parameters in the macro. Macro expansion substitutes empty text for the missing parameters. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4052.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4052.md index 889c7e063b..aaf4746a46 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4052.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4052.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4052" -title: "Compiler Warning (level 1) C4052" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4052" +title: "Compiler Warning (level 1 and level 4) C4052" ms.date: "11/04/2016" f1_keywords: ["C4052"] helpviewer_keywords: ["C4052"] -ms.assetid: f9955421-16ab-46e5-8f9d-bf1639a519ef --- -# Compiler Warning (level 1) C4052 +# Compiler Warning (level 1 and level 4) C4052 -function declarations different; one contains variable arguments +> function declarations different; one contains variable arguments -One declaration of the function does not contain variable arguments. It is ignored. +One declaration of the function doesn't contain variable arguments. The empty declaration is ignored. The following sample generates C4052: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4091.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4091.md index 89745ffea5..bd1e02649e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4091.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4091.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4091" -title: "Compiler Warning (level 1) C4091" +description: "Learn more about: Compiler Warning (level 1 and level 2) C4091" +title: "Compiler Warning (level 1 and level 2) C4091" ms.date: "11/04/2016" f1_keywords: ["C4091"] helpviewer_keywords: ["C4091"] -ms.assetid: 3a404967-ab42-49b0-b324-fd7ba1859d78 --- -# Compiler Warning (level 1) C4091 +# Compiler Warning (level 1 and level 2) C4091 -'keyword' : ignored on left of 'type' when no variable is declared +> '*keyword*': ignored on left of '*type*' when no variable is declared -The compiler detected a situation where the user probably intended a variable to be declared, but the compiler was not able to declare the variable. +The compiler detected a situation where the user probably intended a variable to be declared, but the compiler wasn't able to declare the variable. ## Examples @@ -29,7 +28,7 @@ __declspec(dllimport) class X2 {} varX; class __declspec(dllimport) X3 {}; ``` -If an identifier is a typedef, it cannot also be a variable name. The following sample generates C4091. +If an identifier is a typedef, it can't also be a variable name. The following sample generates C4091. ```cpp // C4091_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4141.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4141.md index abe11df5f5..e166131289 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4141.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4141.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4141" -title: "Compiler Warning (level 1) C4141" +description: "Learn more about: Compiler Warning (level 1, Error) C4141" +title: "Compiler Warning (level 1, Error) C4141" ms.date: "11/04/2016" f1_keywords: ["C4141"] helpviewer_keywords: ["C4141"] -ms.assetid: 6ce8c058-7f4c-41cf-93e7-90a466744656 --- -# Compiler Warning (level 1) C4141 +# Compiler Warning (level 1, Error) C4141 -'modifier' : used more than once +> '*modifier*': used more than once ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md index 35fb106354..0c5e3fe14c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md @@ -10,4 +10,4 @@ ms.assetid: 6513c6b9-6772-4849-b96c-5bb093d54de6 > assuming #pragma pointers_to_members(full_generality, inheritance) -A **#pragma pointers_to_members(** *single* | *multiple* | *virtual* **)** was issued without an accompanying **#pragma pointers_to_members(full_generality)**. +A `#pragma pointers_to_members( single | multiple | virtual )` was issued without an accompanying `#pragma pointers_to_members(full_generality)`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4165.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4165.md index 22390f5cf9..aa851b63b8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4165.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4165.md @@ -1,26 +1,27 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4165" -title: "Compiler Warning (level 1) C4165" +description: "Learn more about: Compiler Warning (level 3, off) C4165" +title: "Compiler Warning (level 3, off) C4165" ms.date: "11/04/2016" f1_keywords: ["C4165"] helpviewer_keywords: ["C4165"] -ms.assetid: f5bed515-2290-4f88-8dab-b45d95fe26ef --- -# Compiler Warning (level 1) C4165 +# Compiler Warning (level 3, off) C4165 -'HRESULT' is being converted to 'bool'; are you sure this is what you want? +'`HRESULT`' is being converted to '`bool`'; are you sure this is what you want? -When using an HRESULT in an [if](../../cpp/if-else-statement-cpp.md) statement, the HRESULT will be converted to a [bool](../../cpp/bool-cpp.md) unless you explicitly test for the variable as an HRESULT. This warning is off by default. +When an `HRESULT` is used in an [`if`](../../cpp/if-else-statement-cpp.md) statement, the `HRESULT` is converted to a [`bool`](../../cpp/bool-cpp.md) unless you explicitly test for the variable as an `HRESULT`. + +Warning C4165 is off by default. For more information, see [Compiler Warnings That Are Off By Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example -The following sample generates C4165 +The following sample generates C4165: ```cpp // C4165.cpp -// compile with: /W1 +// compile with: /W3 #include -#pragma warning(1:4165) +#pragma warning(3:4165) extern HRESULT hr; int main() { diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4178.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4178.md index 216d7cb61a..c3cf047325 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4178.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4178.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler Warning (level 1) C4178" title: "Compiler Warning (level 1) C4178" -ms.date: "11/04/2016" +ms.date: "03/06/2024" f1_keywords: ["C4178"] helpviewer_keywords: ["C4178"] -ms.assetid: 2c2c8f97-a5c4-47cd-8dd2-beea172613f3 --- # Compiler Warning (level 1) C4178 @@ -16,16 +15,16 @@ A case constant in a **`switch`** expression does not fit in the type to which i ```cpp // C4178.cpp -// compile with: /W1 +// compile with: /W1 /permissive int main() { - int i; // maximum size of unsigned long int is 4294967295 - switch( i ) + unsigned int u = 1; + switch (u) { - case 4294967295: // OK - break; - case 4294967296: // C4178 - break; + case 4294967295: // OK, maximum value for type unsigned int + break; + case 4294967296: // C4178, exceeded maximum value + break; } } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4218.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4218.md index a93576090b..510c44d4b9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4218.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4218.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4218" -title: "Compiler Warning (level 1) C4218" +description: "Learn more about: Compiler Warning (level 4) C4218" +title: "Compiler Warning (level 4) C4218" ms.date: "11/04/2016" f1_keywords: ["C4218"] helpviewer_keywords: ["C4218"] -ms.assetid: d6c3cd90-4518-49e9-ae86-4ba9e2761d98 --- -# Compiler Warning (level 1) C4218 +# Compiler Warning (level 4) C4218 -nonstandard extension used : must specify at least a storage class or a type +> nonstandard extension used: must specify at least a storage class or a type -With the default Microsoft extensions (/Ze), you can declare a variable without specifying a type or storage class. The default type is **`int`**. +With the default Microsoft extensions (`/Ze`), you can declare a variable without specifying a type or storage class. The default type is **`int`**. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4229.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4229.md index e4be2c9181..d79edef4c8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4229.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4229.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4229" -title: "Compiler Warning (level 1) C4229" +description: "Learn more about: Compiler Warning (level 1, Error) C4229" +title: "Compiler Warning (level 1, Error) C4229" ms.date: "11/04/2016" f1_keywords: ["C4229"] helpviewer_keywords: ["C4229"] -ms.assetid: aadfc83b-1e5f-4229-bd0a-9c10a5d13182 --- -# Compiler Warning (level 1) C4229 +# Compiler Warning (level 1, Error) C4229 -anachronism used : modifiers on data are ignored +> anachronism used: modifiers on data are ignored Using a Microsoft modifier such as **`__cdecl`** on a data declaration is an outdated practice. @@ -17,5 +16,5 @@ Using a Microsoft modifier such as **`__cdecl`** on a data declaration is an out ```cpp // C4229.cpp // compile with: /W1 /LD -int __cdecl counter; // C4229 cdecl ignored +int __cdecl counter; // C4229 ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4251.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4251.md index 24505a8bf0..1056b7868c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4251.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4251.md @@ -1,40 +1,73 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4251" -title: "Compiler Warning (level 1) C4251" -ms.date: "04/21/2020" +title: "Compiler Warning (level 2) C4251" +description: "Learn more about: Compiler Warning (level 2) C4251" +ms.date: 12/01/2023 f1_keywords: ["C4251"] helpviewer_keywords: ["C4251"] -ms.assetid: a9992038-f0c2-4fc4-a9be-4509442cbc1e --- -# Compiler Warning (level 1) C4251 +# Compiler Warning (level 2) C4251 -> '*type*' : class '*type1*' needs to have dll-interface to be used by clients of class '*type2*' +> '*type*': '*type1*' needs to have dll-interface to be used by clients of '*type2*' ## Remarks -To minimize the possibility of data corruption when exporting a class declared as [__declspec(dllexport)](../../cpp/dllexport-dllimport.md), ensure that: +This warning happens if a class is marked with `__declspec(dllexport)` or `__declspec(dllimport)` and a nonstatic data member that is a member of the class or a member of one of its base classes, has a type that is a class type that isn't marked with `__declspec(dllexport)` or `__declspec(dllimport)`. See [Example](#example). -- All your static data is accessed through functions that are exported from the DLL. +To minimize the possibility of data corruption when exporting a class declared as [`__declspec(dllexport)`](../../cpp/dllexport-dllimport.md), ensure that: +- All your static data is accessed through functions that are exported from the DLL. - No inlined methods of your class can modify static data. - - No inlined methods of your class use CRT functions or other library functions that use static data. For more information, see [Potential errors passing CRT objects across DLL boundaries](../../c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md). - - No methods of your class (whether inlined or not) can use types where the instantiation in the EXE and DLL have static data differences. -You can avoid issues when exporting a class from a DLL: Define your class to have virtual functions, and functions to instantiate and delete objects of the type. You can then just call virtual functions on the type. +You can avoid issues when exporting a class from a DLL by: -C4251 can be ignored if your class is derived from a type in the C++ Standard Library, you're compiling a debug release (**/MTd**), and where the compiler error message refers to `_Container_base`. +- Defining your class to have virtual functions. +- Defining a virtual destructor. +- Defining functions to instantiate and delete instances of the type. -## Example +You can ignore C4251 if your class is derived from a type in the C++ Standard Library, you're compiling a debug release (**`/MTd`**), and the compiler error message refers to `_Container_base`. + +Think carefully about adding `__declspec(dllexport)` or `__declspec(dllimport)` to a class because it's almost always not the right choice and it can make maintenance more difficult because it makes changing implementation details harder. -This sample exports a specialized class `VecWrapper` derived from `std::vector`. +## Example ```cpp // C4251.cpp -// compile with: /EHsc /MTd /W2 /c +// Compile with /std:c++20 /EHsc /W2 /c C4251.cpp +#include + +class __declspec(dllexport) X +{ +public: + X(); + ~X(); + + void do_something(); + +private: + void do_something_else(); + std::vector data; // warning c4251 +}; +``` + +To fix this warning, don't mark the class with `__declspec(dllexport)` or `__declspec(dllimport)`. Instead, only mark the methods that are used directly by a client. For example: + +```cpp +// C4251_fixed.cpp +// Compile with /std:c++20 /EHsc /W2 /c C4251-fixed.cpp #include -using namespace std; -class Node; -class __declspec(dllexport) VecWrapper : vector {}; // C4251 + +class X +{ +public: + __declspec(dllexport) X(); + __declspec(dllexport) ~X(); + + __declspec(dllexport) void do_something(); + +private: + void do_something_else(); + std::vector data; +}; ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4264.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4264.md index 23996076bb..4fe4000068 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4264.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4264.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4264" -title: "Compiler Warning (level 1) C4264" +description: "Learn more about: Compiler Warning (level 4, off) C4264" +title: "Compiler Warning (level 4, off) C4264" ms.date: "11/04/2016" f1_keywords: ["C4264"] helpviewer_keywords: ["C4264"] -ms.assetid: 315a13c1-ca54-4a90-9d2b-dd996463af5d --- -# Compiler Warning (level 1) C4264 +# Compiler Warning (level 4, off) C4264 -'virtual_function' : no override available for virtual member function from base 'class'; function is hidden +> 'virtual_function' : no override available for virtual member function from base 'class'; function is hidden C4264 is always generated after [C4263](../../error-messages/compiler-warnings/compiler-warning-level-4-c4263.md). -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4269.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4269.md index 3a8fdd16f4..faa8737853 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4269.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4269.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4269" title: "Compiler Warning (level 1) C4269" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4269" +ms.date: 11/04/2016 f1_keywords: ["C4269"] helpviewer_keywords: ["C4269"] -ms.assetid: 96c97bbc-068a-4b65-8cd8-4ed5dca04c15 --- # Compiler Warning (level 1) C4269 @@ -24,7 +23,7 @@ public: void g() { const X x1; // C4269 -}; +} ``` Since this instance of the class is generated on the stack, the initial value of `m_data` can be anything. Also, since it is a **`const`** instance, the value of `m_data` can never be changed. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md index 6cefa5432a..4bd91a8079 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md @@ -1,20 +1,20 @@ --- description: "Learn more about: Compiler Warning (level 1) C4273" title: "Compiler Warning (level 1) C4273" -ms.date: "11/04/2016" +ms.date: 05/23/2022 f1_keywords: ["C4273"] helpviewer_keywords: ["C4273"] ms.assetid: cc18611d-9454-40a4-ad73-69823d5888fb --- # Compiler Warning (level 1) C4273 -'function' : inconsistent DLL linkage +> '*function*' : inconsistent DLL linkage -Two definitions in a file differ in their use of [dllimport](../../cpp/dllexport-dllimport.md). +Two definitions in a file differ in their use of [`dllimport`](../../cpp/dllexport-dllimport.md). ## Examples -The following sample generates C4273. +The following sample generates C4273, and shows how to fix it. ```cpp // C4273.cpp @@ -23,7 +23,7 @@ char __declspec(dllimport) c; char c; // C4273, delete this line or the line above to resolve ``` -The following sample generates C4273. +The following sample generates C4273. To fix it, delete the redeclaration of `printf_s`. ```cpp // C4273_b.cpp @@ -31,3 +31,8 @@ The following sample generates C4273. #include extern "C" int printf_s(const char *, ...); // C4273 ``` + +## See also + +[`dllexport`, `dllimport`](../../cpp/dllexport-dllimport.md)\ +[Export C functions for use in C or C++ language executables](../../build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4305.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4305.md index d7faa04094..ba2979d7c6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4305.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4305.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4305" -title: "Compiler Warning (level 1) C4305" +description: "Learn more about: Compiler Warning (level 1 and level 2 and level 4) C4305" +title: "Compiler Warning (level 1 and level 2 and level 4) C4305" ms.date: "01/17/2018" f1_keywords: ["C4305"] helpviewer_keywords: ["C4305"] --- # Compiler Warning (level 1) C4305 -> '*context*' : truncation from '*type1*' to '*type2*' +> '*conversion*': truncation from '*type1*' to '*type2*' ## Remarks diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4329.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4329.md index 22106ed141..2922e2c625 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4329.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4329.md @@ -4,13 +4,12 @@ title: "Compiler Warning (level 1) C4329" ms.date: "11/04/2016" f1_keywords: ["C4329"] helpviewer_keywords: ["C4329"] -ms.assetid: 4316f51a-2c56-4b3f-831e-65d24b83b65c --- # Compiler Warning (level 1) C4329 -__declspec(align()) is ignored on enum +> alignment specifier is ignored on enum -Use of the [align](../../cpp/align-cpp.md) keyword of the [__declspec](../../cpp/declspec.md) modifier is not allowed on an **`enum`**. The following sample generates C4329: +Use of the alignment specifiers on `enum` isn't allowed. This pattern includes the use of the [`align`](../../cpp/align-cpp.md) [`__declspec`](../../cpp/declspec.md) modifier. The following sample generates C4329: ```cpp // C4329.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4384.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4384.md index a4c538bc31..ee4ea78178 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4384.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4384.md @@ -4,13 +4,17 @@ title: "Compiler Warning (level 1) C4384" ms.date: "11/04/2016" f1_keywords: ["C4384"] helpviewer_keywords: ["C4384"] -ms.assetid: fafa8eb2-cbfc-4edb-8b0f-511ff5d37ac0 --- # Compiler Warning (level 1) C4384 -\#pragma 'make_public' should only be used at global scope +> `#pragma` '*pragma_name*' should only be used at global scope -The [make_public](../../preprocessor/make-public.md) pragma was applied incorrectly. +A `pragma` directive that must be applied at a global scope, was found in a different scope. + +The warning applies to the following `pragma` directives: +* [`detect_mismatch`](../../preprocessor/detect-mismatch.md) +* `extern_absolute` +* [`make_public`](../../preprocessor/make-public.md) ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4392.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4392.md index 3e6c6317c5..79d7ebd020 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4392.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4392.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4392" -title: "Compiler Warning (level 1) C4392" +description: "Learn more about: Compiler Warning (level 1, Error) C4392" +title: "Compiler Warning (level 1, Error) C4392" ms.date: "11/04/2016" f1_keywords: ["C4392"] helpviewer_keywords: ["C4392"] -ms.assetid: 817806ad-06a6-4b9e-8355-e25687c782dc --- -# Compiler Warning (level 1) C4392 +# Compiler Warning (level 1, Error) C4392 -'signature' : incorrect number of arguments for intrinsic function, expected 'number' arguments +> 'signature' : incorrect number of arguments for intrinsic function, expected 'number' arguments -A function declaration for a compiler intrinsic had the wrong number of arguments. The resulting image may not run correctly. +A function declaration for a compiler intrinsic had the wrong number of arguments. The resulting image may not run correctly. To fix this warning, either correct the declaration or delete the declaration and `#include` the appropriate header file. -To fix this warning, either correct the declaration or delete the declaration and simply #include the appropriate header file. +This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable or change the warning level. The following sample generates C4392: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4399.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4399.md index a99bfcba5c..39947ec818 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4399.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4399.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4399" -title: "Compiler Warning (level 1) C4399" +description: "Learn more about: Compiler Warning (level 1, Error) C4399" +title: "Compiler Warning (level 1, Error) C4399" ms.date: "11/04/2016" f1_keywords: ["C4399"] helpviewer_keywords: ["C4399"] ms.assetid: f58d9ba7-71a0-4c3b-b26f-f946dda8af30 --- -# Compiler Warning (level 1) C4399 +# Compiler Warning (level 1, Error) C4399 > '*symbol*' : per-process symbol should not be marked with __declspec(dllimport) when compiled with /clr:pure @@ -14,7 +14,9 @@ ms.assetid: f58d9ba7-71a0-4c3b-b26f-f946dda8af30 The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. -Data from a native image or an image with native and CLR constructs can not be imported into a pure image. To resolve this warning, compile with **/clr** (not **/clr:pure**) or delete `__declspec(dllimport)`. +Data from a native image or an image with native and common language runtime (CLR) constructs can't be imported into a pure image. To resolve this warning, compile with **/clr** (not **/clr:pure**) or delete `__declspec(dllimport)`. + +This warning can be issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable or change the warning level. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md index c8376a2dad..c206a7b8cd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md @@ -15,7 +15,7 @@ An incorrect cast between pointer-to-member types was detected. C4407 can be generated because of compiler conformance work that was done in Visual Studio 2005. Pointer-to-member now requires a qualified name and the address-of operator (&). -C4407 can occur if you cast between a multiple inheritance pointer-to-member to a single inheritance pointer-to-member. Sometimes this can work, but sometimes it can’t because the single inheritance pointer-to-member representation doesn’t hold sufficient information. Compiling with the **`/vmm`** might help. For more information, see [`/vmm`, `/vms`, `/vmv` (General purpose representation)](../../build/reference/vmm-vms-vmv-general-purpose-representation.md). You can also try rearranging your base classes; the compiler is detecting a loss of information in the conversion because a base class is at a non-zero offset from the derived. +C4407 can occur if you cast between a multiple inheritance pointer-to-member to a single inheritance pointer-to-member. Sometimes this can work, but sometimes it can't because the single inheritance pointer-to-member representation doesn't hold sufficient information. Compiling with the **`/vmm`** might help. For more information, see [`/vmm`, `/vms`, `/vmv` (General purpose representation)](../../build/reference/vmm-vms-vmv-general-purpose-representation.md). You can also try rearranging your base classes; the compiler is detecting a loss of information in the conversion because a base class is at a non-zero offset from the derived. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4436.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4436.md index 2e6e126ead..9b3e694ede 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4436.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4436.md @@ -1,35 +1,31 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4436" -title: "Compiler Warning (level 1) C4436" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4436" +title: "Compiler warning (level 1 and level 4) C4436" +ms.date: "1/22/2025" f1_keywords: ["C4436"] helpviewer_keywords: ["C4436"] -ms.assetid: 2b54a1fc-c9c6-4cc9-90be-faa44fc715d5 --- -# Compiler Warning (level 1) C4436 +# Compiler warning (level 1) C4436 -dynamic_cast from virtual base 'class1' to 'class2' in constructor or destructor could fail with partially-constructed object Compile with /vd2 or define 'class2' with #pragma vtordisp(2) in effect +> `dynamic_cast` from virtual base '*base_class*' to '*derived_class*' in constructor or destructor could fail with partially-constructed object -The compiler has encountered a **`dynamic_cast`** operation with the following characteristics. +A `dynamic_cast` operation is used when: - The cast is from a base class pointer to a derived class pointer. - - The derived class virtually inherits the base class. +- The derived class doesn't have a `vtordisp` field for the virtual base. +- The cast is found in a constructor or destructor of the derived class, or a class that inherits from the derived class. -- The derived class does not have a `vtordisp` field for the virtual base. - -- The cast is found in a constructor or destructor of the derived class, or some class which further inherits from the derived class. - -The warning indicates the **`dynamic_cast`** might not perform correctly, if it is operating on a partially-constructed object. That happens if the derived constructor/destructor is operating on a sub-object of some further derived object. If the derived class named in the warning is never further derived, the warning can be ignored. +This warning indicates that the `dynamic_cast` might not perform correctly if it is applied to a partially constructed object. Which happens if the derived constructor/destructor is operating on a subobject of some further derived object. If the derived class named in the warning isn't further derived, you can ignore the warning. ## Example -The following sample generates C4436 and demonstrates the code generation issue that arises from the missing `vtordisp` field. +The following sample generates C4436 and demonstrates the code generation issue due to the missing `vtordisp` field: ```cpp // C4436.cpp // To see the warning and runtime assert, compile with: /W1 -// To eliminate the warning and assert, compile with: /W1 /vd2 +// To eliminate the warning and assert, compile with: /W1 /vd2 // or compile with: /W1 /DFIX #include @@ -48,7 +44,7 @@ struct B : virtual A { A* a = static_cast(this); B* b = dynamic_cast(a); // C4436 - assert(this == b); // assert unless compiled with /vd2 + assert(this == b); // asserts unless compiled with /vd2 } }; #if defined(FIX) @@ -68,6 +64,6 @@ int main() ## See also -[dynamic_cast Operator](../../cpp/dynamic-cast-operator.md)
-[vtordisp](../../preprocessor/vtordisp.md)
-[Compiler Warning (level 4) C4437](../../error-messages/compiler-warnings/compiler-warning-level-4-c4437.md) +[`dynamic_cast` Operator](../../cpp/dynamic-cast-operator.md)\ +[`vtordisp`](../../preprocessor/vtordisp.md)\ +[Compiler Warning (level 1 and level 4, off) C4437](compiler-warning-level-4-c4437.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md index 2303da79ab..000e2059c5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md @@ -1,30 +1,36 @@ --- description: "Learn more about: Compiler Warning (level 1) C4532" title: "Compiler Warning (level 1) C4532" -ms.date: "11/04/2016" +ms.date: 08/30/2022 f1_keywords: ["C4532"] helpviewer_keywords: ["C4532"] ms.assetid: 4e2a286a-d233-4106-9f65-29be1a94ca02 --- # Compiler Warning (level 1) C4532 -'continue' : jump out of __finally/finally block has undefined behavior during termination handling +> 'continue' : jump out of __finally/finally block has undefined behavior during termination handling + +## Remarks The compiler encountered one of the following keywords: -- [continue](../../cpp/continue-statement-cpp.md) +- [`continue`](../../cpp/continue-statement-cpp.md) -- [break](../../cpp/break-statement-cpp.md) +- [`break`](../../cpp/break-statement-cpp.md) -- [goto](../../cpp/goto-statement-cpp.md) +- [`goto`](../../cpp/goto-statement-cpp.md) -causing a jump out of a [__finally](../../cpp/try-finally-statement.md) or [finally](../../dotnet/finally.md) block during abnormal termination. +causing a jump out of a [`__finally`](../../cpp/try-finally-statement.md) or [`finally`](../../dotnet/finally.md) block during abnormal termination. If an exception occurs, and while the stack is being unwound during execution of the termination handlers (the **`__finally`** or finally blocks), and your code jumps out of a **`__finally`** block before the **`__finally`** block ends, the behavior is undefined. Control may not return to the unwinding code, so the exception may not be handled properly. If you must jump out of a **`__finally`** block, check for abnormal termination first. -The following sample generates C4532; simply comment out the jump statements to resolve the warnings. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + +## Example + +The following sample generates C4532; delete or comment out the jump statements to resolve the warnings. ```cpp // C4532.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md index af1f372eaf..11ebe5d594 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md @@ -1,16 +1,24 @@ --- description: "Learn more about: Compiler Warning (level 1) C4533" title: "Compiler Warning (level 1) C4533" -ms.date: "11/04/2016" +ms.date: 08/30/2022 f1_keywords: ["C4533"] helpviewer_keywords: ["C4533"] ms.assetid: 359fecda-d540-46e5-b214-dbabe9ef50d2 --- # Compiler Warning (level 1) C4533 -initialization of 'variable' is skipped by 'instruction' +> initialization of '*variable*' is skipped by '*instruction*' -An instruction in your program changed the flow of control, such that, an instruction that initialized a variable was not executed. The following sample generates C4533: +## Remarks + +An instruction in your program changed the flow of control, so an instruction that initialized a variable wasn't executed. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + +## Example + +The following sample generates C4533. To resolve the issue, move the initialization before the jump instruction or after the target of the jump. ```cpp // C4533.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md index 371adf13d2..1d14bf8eb5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4556" title: "Compiler Warning (level 1) C4556" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4556" +ms.date: "03/28/2025" f1_keywords: ["C4556"] helpviewer_keywords: ["C4556"] -ms.assetid: e4c0e296-b747-4db1-9608-30b8b74feac2 --- # Compiler Warning (level 1) C4556 -> value of intrinsic immediate argument '*value*' is out of range '*lowerbound* - *upperbound*' +> value of intrinsic immediate argument '*value*' is out of range '*lower_bound* - *upper_bound*' ## Remarks @@ -16,21 +15,18 @@ An intrinsic matches a hardware instruction. The hardware instruction has a fixe ## Example -The following sample generates C4556: +The following example generates C4556: ```cpp // C4556.cpp // compile with: /W1 -// processor: x86 IPF +// processor: x86 #include -void test() -{ - __m64 m; - _m_pextrw(m, 5); // C4556 -} - int main() { + __m64 m = _mm_setzero_si64(); + _m_pextrw(m, 5); // C4556 + _mm_empty(); } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md index fcd30dbafb..7587043b9d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md @@ -1,31 +1,33 @@ --- description: "Learn more about: Compiler Warning (Level 1) C4743" title: "Compiler Warning (Level 1) C4743" -ms.date: "05/13/2019" +ms.date: 06/16/2022 f1_keywords: ["C4743"] helpviewer_keywords: ["C4743"] ms.assetid: 2ee76ea3-77f3-4c2f-9a57-0751823c89fd --- # Compiler Warning (Level 1) C4743 -'*type*' has different size in '*file1*' and '*file2*': *number* and *number* bytes +> '*type*' has different size in '*file1*' and '*file2*': *size_1* and *size_2* bytes An external variable referenced or defined in two files has different types in those files, and the compiler determined that the size of the variable in *file1* differs from the size of the variable in *file2*. ## Remarks -There is an important case when this warning can be emitted for C++. If you declare the same types with the same name in two different files, if those declarations contain virtual functions, and if the declarations are not the same, then the compiler can emit warning C4744 for the virtual function tables. The warning occurs because there are two different-sized virtual function tables for the same type, and linker must choose one of them to incorporate into the executable. It is possible that it can result in your program calling the wrong virtual function. +There's an important case when this warning can be emitted for C++. If you declare class types with the same name in two different files, if those declarations contain virtual functions, and if the declarations aren't the same, then the compiler can emit warning C4744 for the virtual function tables. The warning occurs because there are two different-sized virtual function tables for the same type, and the linker must choose one of them to incorporate into the executable. It's possible that it can result in your program calling the wrong virtual function. To resolve this warning, either use the same type definition or use different names for the types or variables. ## Example -The following sample generates C4743. To compile it, place both files in the same folder, then run +The following sample generates C4743. To compile it, place both files in the same folder, then run this command in a developer command prompt: ```cmd cl /EHsc /W1 /GL /O2 C4743a.cpp C4743b.cpp ``` +Source file *`C4743a.cpp`*: + ```cpp // C4743a.cpp class C { @@ -41,6 +43,8 @@ void C::f3(void) {} C q; ``` +Source file *`C4743b.cpp`*: + ```cpp // C4743b.cpp class C { @@ -58,3 +62,5 @@ C x; int main() {} ``` + +To resolve this issue, rename one of the `C` classes. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md index e4cb1f2a3f..3c788f2d51 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md @@ -15,7 +15,7 @@ An external variable referenced or defined in two files has different types in t C4744 is emitted only when files are compiled with /GL. For more information, see [/GL (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md). > [!NOTE] -> C4744 usually occurs in C (not C++) files, because in C++ a variable name is decorated with type information. When the sample (below) is compiles as C++, you’ll get linker error LNK2019. +> C4744 usually occurs in C (not C++) files, because in C++ a variable name is decorated with type information. When the sample (below) is compiles as C++, you'll get linker error LNK2019. ## Examples diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md index dd4276de10..4d871d446c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md @@ -14,7 +14,7 @@ The compiler limits the maximum length allowed for a function name. When the com The resulting funclet name can be too long, and the compiler will truncate it and generate C4788. -To resolve this warning, shorten the original function name. If the function is a C++ template function or method, use a typedef for part of the name. For example: +To resolve this warning, shorten the original function name. If the function is a C++ function template or method, use a typedef for part of the name. For example: ```cpp C1>::C2::f diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md index 2d5fa6daeb..696cc4eacd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4789" title: "Compiler Warning (Level 1) C4789" -ms.date: "03/25/2019" +description: "Learn more about: Compiler Warning (Level 1) C4789" +ms.date: 08/30/2022 f1_keywords: ["C4789"] helpviewer_keywords: ["C4789"] -ms.assetid: 5800c301-5afb-4af0-85c1-ceb54d775234 --- # Compiler Warning (Level 1) C4789 @@ -18,11 +17,9 @@ ms.assetid: 5800c301-5afb-4af0-85c1-ceb54d775234 The warning occurs if the copy uses the intrinsic form of one of these CRT functions: -- [strcpy](../../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md) - -- [memset](../../c-runtime-library/reference/memset-wmemset.md) - -- [memcpy](../../c-runtime-library/reference/memcpy-wmemcpy.md), [wmemcpy](../../c-runtime-library/reference/memcpy-wmemcpy.md) +- [`strcpy`](../../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md) +- [`memset`](../../c-runtime-library/reference/memset-wmemset.md) +- [`memcpy`](../../c-runtime-library/reference/memcpy-wmemcpy.md), [`wmemcpy`](../../c-runtime-library/reference/memcpy-wmemcpy.md) The warning also appears when you cast a parameter to a larger data type, and then make a copy assignment from an lvalue reference. @@ -31,15 +28,17 @@ Visual C++ might generate this warning for a code path that never executes. You ```cpp #pragma warning( push ) #pragma warning( disable : 4789 ) -// unused code that generates compiler warning C4789` +// unused code that generates compiler warning C4789 #pragma warning( pop ) ``` -This idiom keeps Visual C++ from generating the warning for that specific block of code. The `#pragma warning(push)` preserves the existing state before `#pragma warning(disable: 4789)` changes it. The `#pragma warning(pop)` restores the pushed state, and removes the effects of the `#pragma warning(disable:4789)`. For more information about the C++ preprocessor directive `#pragma`, see [warning](../../preprocessor/warning.md) and [Pragma Directives and the __Pragma Keyword](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). +This idiom keeps Visual C++ from generating the warning for that specific block of code. The `#pragma warning(push)` preserves the existing state before `#pragma warning(disable: 4789)` changes it. The `#pragma warning(pop)` restores the pushed state, and removes the effects of the `#pragma warning(disable:4789)`. For more information about the C++ preprocessor directive `#pragma`, see [`warning`](../../preprocessor/warning.md) and [Pragma Directives and the `__Pragma` Keyword](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Examples -The following sample generates C4789. +The following sample generates C4789: ```cpp // C4789.cpp @@ -61,7 +60,7 @@ int main() } ``` -The following sample also generates C4789. +The following sample also generates C4789: ```cpp // C4789b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4799.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4799.md index ec6ba0260e..a5c280ad86 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4799.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4799.md @@ -1,17 +1,35 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4799" title: "Compiler Warning (level 1) C4799" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4799" +ms.date: "03/28/2025" f1_keywords: ["C4799"] helpviewer_keywords: ["C4799"] -ms.assetid: 8ecbd06f-c778-4371-a2fb-c690b6743ec8 --- # Compiler Warning (level 1) C4799 -> No EMMS at end of function '*function*' +> function '*function*' has no EMMS instruction -The function has at least one MMX instruction, but does not have an `EMMS` instruction. When a multimedia instruction is used, an `EMMS` instruction or `_mm_empty` intrinsic should also be used to clear the multimedia tag word at the end of the MMX code. +The function has at least one MMX instruction, but does not have an `EMMS` instruction. When a multimedia instruction is used, an `EMMS` instruction or [`_mm_empty`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_empty) intrinsic should also be used to clear the multimedia tag word at the end of the MMX code. -You may get C4799 when using ivec.h, indicating that the code does not use properly execute the EMMS instruction before returning. This is a false warning for these headers. You may turn these off by defining _SILENCE_IVEC_C4799 in ivec.h. However, be aware that this will also keep the compiler from giving correct warnings of this type. +You may get C4799 when using `ivec.h`, indicating that the code does not properly execute the `EMMS` instruction before returning. This is a false warning for these headers. You may turn these off by defining `_SILENCE_IVEC_C4799` in `ivec.h`. However, be aware that this will also keep the compiler from giving correct warnings of this type. For related information, see [Intel's MMX Instruction Set](../../assembler/inline/intel-s-mmx-instruction-set.md). + +## Example + +The following example generates C4799: + +```cpp +// C4799.cpp +// compile with: /W1 +// processor: x86 +#include + +int main() +{ + __m64 m = _mm_setzero_si64(); + + // Uncomment the following line to resolve the warning: + // _mm_empty(); +} // C4799 +``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md index 4985337cbb..51968a971d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md @@ -10,9 +10,15 @@ ms.assetid: 0f231a30-2eb0-4722-aaa0-e2d19d3e7eea 'member' : local class member function does not have a body -A local class member function was declared but not defined in class. To use a local class member function, you must define it in the class. You cannot declare it in class and define it out of class. +## Remarks -Any out-of-class definition for a local class member function will be an error. +A local class member function was declared but not defined in the class. To use a local class member function, you must define it in the class. You can't declare it in class and define it out of class. + +Any out-of-class definition for a local class member function is an error. + +In Visual Studio 2019 and later, C4822 is an [off-by-default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) warning. + +## Example The following sample generates C4822: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4999.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4999.md deleted file mode 100644 index d1add86f49..0000000000 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4999.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: "Learn more about: Compiler Warning (level 1) C4999" -title: "Compiler Warning (level 1) C4999" -ms.date: "11/04/2016" -f1_keywords: ["C4999"] -helpviewer_keywords: ["C4999"] -ms.assetid: 79db8bcb-6404-4451-a374-8cd184d7c4b5 ---- -# Compiler Warning (level 1) C4999 - -UNKNOWN WARNING From the Help menu choose the Technical Support command or open the Technical Support help file for more information - -Note the circumstances of the error, try to isolate the problem and create a reproducible test case, then contact [Microsoft Product Support Services](/visualstudio/ide/talk-to-us). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4007.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4007.md index 7b38ae77bb..336918d5ce 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4007.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4007.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4007" -title: "Compiler Warning (level 2) C4007" +description: "Learn more about: Compiler Warning (level 3) C4007" +title: "Compiler Warning (level 3) C4007" ms.date: "11/04/2016" f1_keywords: ["C4007"] helpviewer_keywords: ["C4007"] -ms.assetid: 56a70c07-59a5-4fd7-80ed-63592c65cbb7 --- -# Compiler Warning (level 2) C4007 +# Compiler Warning (level 3) C4007 -'function' : must be 'attribute' +> '*function*': must be '*attribute*' -A required attribute for a function is not explicitly stated. For example, the function **main** must have the **`__cdecl`** attribute. The compiler forces the attribute. +A required attribute for a function isn't explicitly stated. For example, the function `main` must have the `__cdecl` attribute. The compiler forces the attribute. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4099.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4099.md index 40fd5f1901..813ec5943a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4099.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4099.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4099" title: "Compiler Warning (level 2) C4099" +description: "Learn more about: Compiler Warning (level 2) C4099" ms.date: "11/04/2016" f1_keywords: ["C4099"] helpviewer_keywords: ["C4099"] -ms.assetid: 00bb803d-cae7-4ab8-8969-b46f54139ac8 --- # Compiler Warning (level 2) C4099 -'identifier' : type name first seen using 'objecttype1' now seen using 'objecttype2' +> '*identifier*': type name first seen using '*object_type1*' now seen using '*object_type2*' An object declared as a structure is defined as a class, or an object declared as a class is defined as a structure. The compiler uses the type given in the definition. @@ -20,5 +19,5 @@ The following sample generates C4099. // C4099.cpp // compile with: /W2 /c struct A; -class A {}; // C4099, use different identifer or use same object type +class A {}; // C4099, use different identifier or use same object type ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md index 146880f253..5cf2284477 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Compiler warning (level 2) C4146" title: "Compiler warning (level 2) C4146" -ms.date: 11/18/2021 +ms.date: 04/22/2025 f1_keywords: ["C4146"] helpviewer_keywords: ["C4146"] --- @@ -9,21 +9,22 @@ helpviewer_keywords: ["C4146"] > unary minus operator applied to unsigned type, result still unsigned -Unsigned types can hold only non-negative values, so unary minus (negation) usually doesn't make sense when applied to an unsigned type. Both the operand and the result are non-negative. +Unsigned types only hold non-negative values. So unary minus (negation) usually doesn't make sense when applied to an unsigned type. Both the operand and the result are non-negative. ## Remarks -When you express a negative integer literal, the **`-`** in front of the value is parsed as a [unary negation](../../cpp/unary-plus-and-negation-operators-plus-and.md) operator. The compiler applies the operator after it parses the numeric value. If the numeric value fits in the range of an unsigned integer type, but not the corresponding signed integer type, the compiler interprets the value as unsigned. An unsigned value is unchanged by the unary negation operator. +When you express a negative integer literal, the **`-`** in front of the value is parsed as a [unary negation](../../cpp/unary-plus-and-negation-operators-plus-and.md) operator. The compiler applies the operator after it parses the numeric value. If the numeric value fits in the range of an unsigned integer type, but not the corresponding signed integer type, the compiler interprets the value as unsigned. -This warning often occurs when you try to express the minimum **`int`** value, -2147483648, or the minimum **`long long`** value, -9223372036854775808. These values can't be written as -2147483648 or -9223372036854775808ll, respectively. That's because the compiler processes the expression in two stages: first, it parses the numeric value, then it applies the negation operator. For example, when the compiler parses -2147483648, it follows these steps: +This warning often occurs when you try to express the minimum **`int`** value, -2147483648, or the minimum **`long long`** value, -9223372036854775808. These values can't be written as -2147483648 or -9223372036854775808ll. The reason is because the compiler processes the expression in two stages: first, it parses the numeric value, then it applies the negation operator. For example, when the compiler parses -2147483648, it follows these steps: 1. The number 2147483648 is evaluated. Because it's greater than the maximum **`int`** value of 2147483647, but still fits in an **`unsigned int`**, the type of 2147483648 is **`unsigned int`**. - 1. Unary minus is applied to the unsigned value, with an unsigned result, which also happens to be 2147483648. The unsigned type of the result can cause unexpected behavior. If the result is used in a comparison, then an unsigned comparison might be used, for example, when the other operand is an **`int`**. -You can avoid C4146 by using `INT_MIN` or `LLONG_MIN` from *``* or the C++ equivalent, *``*. These values have signed types. +You can avoid **C4146** by using `INT_MIN` or `LLONG_MIN` from *``* or the C++ equivalent, *``*. These values have signed types. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4150.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4150.md index 1d141e54d1..3fcab81522 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4150.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4150.md @@ -1,30 +1,83 @@ --- +title: Compiler warning (level 2) C4150 description: "Learn more about: Compiler Warning (level 2) C4150" -title: "Compiler Warning (level 2) C4150" -ms.date: "11/04/2016" +ms.date: 11/04/2016 f1_keywords: ["C4150"] helpviewer_keywords: ["C4150"] -ms.assetid: ff1760ec-0d9f-4d45-b797-94261624becf --- # Compiler Warning (level 2) C4150 -deletion of pointer to incomplete type 'type'; no destructor called +> deletion of pointer to incomplete type 'type'; no destructor called -The **`delete`** operator is called to delete a type that was declared but not defined, so the compiler cannot find a destructor. +The `delete` operator is called to delete a type that was declared but not defined. The compiler can't find the destructor to call because the definition isn't in the same translation unit as the `delete`. -The following sample generates C4150: +## Example + +The following sample generates C4150 by declaring but not defining `class IncClass`: ```cpp -// C4150.cpp // compile with: /W2 -class IncClass; +class IncClass; + +void NoDestruct( IncClass* pIncClass ) +{ + delete pIncClass; // C4150 +} +``` + +To fix the issue, put the definition of `IncClass` in the same file as the `delete`. If the class is declared in a header file, it can be added to the file using `#include`. If the class isn't declared in a header file, the `NoDestruct` function definition may need to be moved into the same file as the `IncClass` definition. + +```cpp +// compile with: /W2 +#include "IncClass.h" void NoDestruct( IncClass* pIncClass ) { delete pIncClass; -} // C4150, define class to resolve +} +``` + +C4150 will be emitted when the class is defined after the destructor call in the same file. In the following example `IncClass` is declared before being used, but defined after the `delete`: + +```cpp +// C4150.cpp +// compile with: /W2 +class IncClass; -int main() +void NoDestruct( IncClass* pIncClass ) +{ + delete pIncClass; // C4150 +} + +class IncClass +{ +public: + IncClass() = default; + ~IncClass() = default; +}; +``` +In this scenario, the use of `delete` needs to be after the class definition. +```cpp +// C4150.cpp +// compile with: /W2 +class IncClass; + +void NoDestruct( IncClass* pIncClass ); + +class IncClass { +public: + IncClass() = default; + ~IncClass() = default; +}; + +void NoDestruct( IncClass* pIncClass ) +{ + delete pIncClass; } ``` + +## See also + +* [Projects and build systems](../../build/projects-and-build-systems-cpp.md) +* [Source files and source programs](../../c-language/source-files-and-source-programs.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4307.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4307.md index 0bfaf97272..c2561f469e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4307.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4307.md @@ -8,7 +8,7 @@ ms.assetid: 7cca11e9-be61-49e4-8b15-88b84f0cbf07 --- # Compiler Warning (level 2) C4307 -'operator' : integral constant overflow +'operator' : signed integral constant overflow The operator is used in an expression that results in an integer constant overflowing the space allocated for it. You may need to use a larger type for the constant. A **`signed int`** holds a smaller value than an **`unsigned int`** because the **`signed int`** uses one bit to represent the sign. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md index 65171067b5..0f1b82759f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md @@ -1,17 +1,21 @@ --- description: "Learn more about: Compiler Warning (level 2) C4308" title: "Compiler Warning (level 2) C4308" -ms.date: "11/04/2016" +ms.date: 08/30/2022 f1_keywords: ["C4308"] helpviewer_keywords: ["C4308"] ms.assetid: d4e5c53c-71b2-4bbc-8a7c-3a2a3180d9d9 --- # Compiler Warning (level 2) C4308 -negative integral constant converted to unsigned type +> negative integral constant converted to unsigned type + +## Remarks An expression converts a negative integer constant to an unsigned type. The result of the expression is probably meaningless. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + ## Example ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4412.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4412.md index 2c6d5bb4fa..3ef99e9709 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4412.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4412.md @@ -1,35 +1,33 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4412" -title: "Compiler Warning (level 2) C4412" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2, off) C4412" +title: "Compiler warning (level 2, off) C4412" +ms.date: "1/22/2025" f1_keywords: ["C4412"] helpviewer_keywords: ["C4412"] -ms.assetid: f28dc531-1a98-497b-a366-0a13e1bc81c7 --- -# Compiler Warning (level 2) C4412 +# Compiler warning (level 2, off) C4412 -> '*function*' : function signature contains type '*type*'; C++ objects are unsafe to pass between pure code and mixed or native. +> '*function*': function signature contains type '*type*'; C++ objects are unsafe to pass between pure code and mixed or native. ## Remarks -The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. If you have code that needs to be pure, we recommend that you port it to C#. +The `/clr:pure` compiler option is deprecated in Visual Studio 2015, and unsupported starting in Visual Studio 2017. If you have code that needs to be CLR pure, we recommend that you port it to C#. -The compiler detected a potentially unsafe situation that could result in a runtime error: a call is being made from a **/clr:pure** compiland to a function that was imported via dllimport and the function signature contains an unsafe type. A type is unsafe if it contains a member function or has a data member that is an unsafe type or an indirection to an unsafe type. +The compiler detected a potentially unsafe situation that could result in a runtime error: a call is being made from code compiled with `/clr:pure` to a function imported via `dllimport`, and the function signature contains an unsafe type. A type is unsafe if it contains a member function or has a data member that is an unsafe type or an indirection to an unsafe type. -This is unsafe because of the difference in the default calling conventions between pure and native code (or mixed native and managed). When importing (via `dllimport`) a function into a **/clr:pure** compiland, ensure that the declarations of each type in the signature are identical to those in the compiland that exports the function (being especially careful about differences in implicit calling conventions). +This pattern is unsafe because of the difference in the default calling conventions between pure and native code (or mixed native and managed). When importing a function via `dllimport` into code compiled with `/clr:pure`, ensure that the declarations of each type in the signature are identical to the signature in the compiland that exports the function (being especially careful about differences in implicit calling conventions). -A virtual member function is especially prone to give unexpected results. However, even a non-virtual function should be tested to ensure that you get the correct results. If you are sure that you are getting the correct results, you can ignore this warning. +A virtual member function is especially prone to give unexpected results. However, even a nonvirtual function should be tested to ensure that you get the correct results. This warning can be ignored once you ensure the result is correct. -C4412 is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) and [dllexport, dllimport](../../cpp/dllexport-dllimport.md) for more information. +C4412 is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) and [`dllexport`, `dllimport`](../../cpp/dllexport-dllimport.md). To resolve this warning, remove all functions from the type. -## Examples +## Example -The following sample generates C4412. +The following sample generates C4412: ```cpp -// C4412.cpp // compile with: /c /W2 /clr:pure #pragma warning (default : 4412) @@ -52,7 +50,7 @@ int main() { } ``` -The following sample is a header file that declares two types. The `Unsafe` type is unsafe because it has a member function. +The following sample is a header file that declares two types. The `Unsafe` type is unsafe because it has a member function: ```cpp // C4412.h @@ -70,7 +68,7 @@ struct Safe { }; ``` -This sample exports functions with the types defined in the header file. +This sample exports functions with the types defined in the header file: ```cpp // C4412_2.cpp @@ -85,9 +83,9 @@ __declspec(dllexport) Unsafe * __cdecl func() { return new Unsafe; } __declspec(dllexport) Safe * __cdecl func2() { return new Safe; } ``` -The default calling convention in a **/clr:pure** compilation is different from a native compilation. When C4412.h is included, `Test` defaults to `__clrcall`. If you compile and run this program (do not use **/c**), the program will throw an exception. +The default calling convention in a `/clr:pure` compilation is different from a native compilation. When `C4412.h` is included, `Test` defaults to `__clrcall`. -The following sample generates C4412. +The following sample generates C4412 and throws an exception at runtime: ```cpp // C4412_3.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4066.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4066.md index 509d435b2f..11ddd3399f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4066.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4066.md @@ -1,13 +1,29 @@ --- description: "Learn more about: Compiler Warning (level 3) C4066" title: "Compiler Warning (level 3) C4066" -ms.date: "11/04/2016" +ms.date: "03/06/2024" f1_keywords: ["C4066"] helpviewer_keywords: ["C4066"] -ms.assetid: f2ae6465-a140-459a-87fd-c8f25fafedd4 --- # Compiler Warning (level 3) C4066 characters beyond first in wide-character constant ignored The compiler processes only the first character of a wide-character constant. + +```cpp +// C4066.cpp +// compile with: /W3 +#include + +int main() +{ + wchar_t wc = L'AB'; // C4066 + + std::wcout << wc; +} +``` + +```output +A +``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4101.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4101.md index 8044b98d73..3199f6c3e5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4101.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4101.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4101" -title: "Compiler Warning (level 3) C4101" +description: "Learn more about: Compiler Warning (level 3 and level 4) C4101" +title: "Compiler Warning (level 3 and level 4) C4101" ms.date: "11/04/2016" f1_keywords: ["C4101"] helpviewer_keywords: ["C4101"] -ms.assetid: d98563cd-9dce-4aae-8f12-bd552a4ea677 --- -# Compiler Warning (level 3) C4101 +# Compiler Warning (level 3 and level 4) C4101 -'identifier' : unreferenced local variable +> '*identifier*': unreferenced local variable -The local variable is never used. This warning will occur in the obvious situation: +The local variable is never used. This warning occurs in the obvious situation: ```cpp // C4101a.cpp @@ -20,7 +19,7 @@ int i; // C4101 } ``` -However, this warning will also occur when calling a **`static`** member function through an instance of the class: +However, this warning also occurs when calling a **`static`** member function through an instance of the class: ```cpp // C4101b.cpp @@ -39,7 +38,7 @@ int main() { } ``` -In this situation, the compiler uses information about `si` to access the **`static`** function, but the instance of the class is not needed to call the **`static`** function; hence the warning. To resolve this warning, you could: +In this situation, the compiler uses information about `si` to access the **`static`** function, but the instance of the class isn't needed to call the **`static`** function; hence the warning. To resolve this warning, you could: - Add a constructor, in which the compiler would use the instance of `si` in the call to `func`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4133.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4133.md index 77a80d1326..48a818c0f0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4133.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4133.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4133" -title: "Compiler Warning (level 3) C4133" +description: "Learn more about: Compiler Warning (level 1 and level 3) C4133" +title: "Compiler Warning (level 1 and level 3) C4133" ms.date: "11/04/2016" f1_keywords: ["C4133"] helpviewer_keywords: ["C4133"] -ms.assetid: bdef87b0-21b3-41ac-9b23-1fa86101a9ac --- -# Compiler Warning (level 3) C4133 +# Compiler Warning (level 1 and level 3) C4133 -'type' : incompatible types - from 'type1' to 'type2' +> '*expression*': incompatible types - from '*type1*' to '*type2*' -This warning can be caused by trying to subtract two pointers of different types. +This warning is emitted when incompatible types are used in an expression. For example, doing arithmetic operations such as subtraction with different pointer types. To avoid this warning, provide an appropriate type cast. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4191.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4191.md index a0bdee8047..46b90ba9e2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4191.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4191.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4191" -title: "Compiler Warning (level 3) C4191" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3, off) C4191" +description: "Learn more about: Compiler Warning (level 3, off) C4191" +ms.date: 11/04/2016 f1_keywords: ["C4191"] helpviewer_keywords: ["C4191"] -ms.assetid: 576d3bc6-95b7-448a-af31-5d798452df09 --- -# Compiler Warning (level 3) C4191 +# Compiler Warning (level 3, off) C4191 -'operator/operation' : unsafe conversion from 'type of expression' to 'type required' +> '*operation*': unsafe conversion from '*type_of_expression*' to '*type_required*'
Making a function call using the resulting pointer may cause your program to fail Several operations involving function pointers are considered unsafe: @@ -18,15 +17,15 @@ Several operations involving function pointers are considered unsafe: - Argument or return types with different sizes, type categories, or classifications. -- Differing argument list lengths (on **`__cdecl`**, only on cast from longer list to shorter list, even if shorter is varargs). +- Different argument list lengths (on **`__cdecl`**, only on cast from longer list to shorter list, even if shorter is varargs). -- Pointer to data (other than **`void`**\*) aliased against a pointer to function. +- Pointer to data (other than **`void*`**) aliased against a pointer to function. - Any other type difference that would yield an error or warning on a **`reinterpret_cast`**. Calling this function through the result pointer might cause your program to crash. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4191: @@ -47,5 +46,5 @@ int main() { fnptr1 fp3 = (fnptr1) &f2; // C4191 fnptr2 fp4 = (fnptr2) &f1; // C4191 -}; +} ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4243.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4243.md index ea6813c8f3..8fab32eef4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4243.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4243.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4243" title: "Compiler Warning (level 3) C4243" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4243" +ms.date: 11/04/2016 f1_keywords: ["C4243"] helpviewer_keywords: ["C4243"] -ms.assetid: ca72f9ad-ce0b-43a9-a68c-106e1f8b90ef --- # Compiler Warning (level 3) C4243 @@ -21,7 +20,7 @@ The following sample generates C4243: struct B { int f() { return 0; - }; + } }; struct D : private B {}; diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4265.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4265.md index fdee3d43de..fa20cef811 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4265.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4265.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4265" -title: "Compiler Warning (level 3) C4265" +description: "Learn more about: Compiler Warning (level 3, off) C4265" +title: "Compiler Warning (level 3, off) C4265" ms.date: "11/04/2016" f1_keywords: ["C4265"] helpviewer_keywords: ["C4265"] -ms.assetid: 20547159-6f30-4cc4-83aa-927884c8bb4c --- -# Compiler Warning (level 3) C4265 +# Compiler Warning (level 3, off) C4265 -'class' : class has virtual functions, but destructor is not virtual +> '*classname*': class has virtual functions, but its non-trivial destructor is not virtual; instances of this class may not be destructed correctly When a class has virtual functions but a nonvirtual destructor, objects of the type might not be destroyed properly when the class is destroyed through a base class pointer. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4265: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4278.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4278.md index bed4655598..464d6497f3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4278.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4278.md @@ -1,15 +1,12 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4278" -title: "Compiler Warning (level 3) C4278" +description: "Learn more about: Compiler Warning (level 3 and level 4) C4278" +title: "Compiler Warning (level 3 and level 4) C4278" ms.date: "08/27/2018" f1_keywords: ["C4278"] helpviewer_keywords: ["C4278"] -ms.assetid: 4b6053fb-df62-4c04-b6c8-c011759557b8 --- -# Compiler Warning (level 3) C4278 +# Compiler Warning (level 3 and level 4) C4278 > '*identifier*': identifier in type library '*tlb*' is already a macro; use the 'rename' qualifier -When using [#import](../../preprocessor/hash-import-directive-cpp.md), an identifier in the typelib you are importing is attempting to declare an identifier *identifier*. However, this is already a valid symbol. - -Use the `#import` **rename** attribute to assign an alias to the symbol in the type library. +The [`#import`](../../preprocessor/hash-import-directive-cpp.md) is attempting to import an identifier into the translation unit. However, there's already a symbol with that name. Use the `#import` **rename** attribute to assign an alias to the symbol in the type library. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4287.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4287.md index 4834efa3a1..989066bb6b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4287.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4287.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4287" -title: "Compiler Warning (level 3) C4287" +description: "Learn more about: Compiler Warning (level 3, off) C4287" +title: "Compiler Warning (level 3, off) C4287" ms.date: "11/04/2016" f1_keywords: ["C4287"] helpviewer_keywords: ["C4287"] -ms.assetid: 1bf3bff8-6402-4d06-95ba-431678a790a7 --- -# Compiler Warning (level 3) C4287 +# Compiler Warning (level 3, off) C4287 -'operator' : unsigned/negative constant mismatch +> 'operator' : unsigned/negative constant mismatch An unsigned variable was used in an operation with a negative number. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4306.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4306.md index 21157e1bbc..0e334e644e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4306.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4306.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4306" -title: "Compiler Warning (level 3) C4306" +description: "Learn more about: Compiler Warning (level 4) C4306" +title: "Compiler Warning (level 4) C4306" ms.date: "08/27/2018" f1_keywords: ["C4306"] helpviewer_keywords: ["C4306"] -ms.assetid: 5b2192d7-402d-4b6d-8619-08105e7dcac7 --- -# Compiler Warning (level 3) C4306 +# Compiler Warning (level 4) C4306 -> '*identifier*' : conversion from '*type1*' to '*type2*' of greater size +> '*conversion*': conversion from '*type1*' to '*type2*' of greater size -The identifier is type cast to a larger pointer. The unfilled high bits of the new type will be zero-filled. +The identifier is type cast to a larger pointer. The unfilled high bits of the new type are zero-filled. This warning may indicate an unwanted conversion. The resulting pointer may not be valid. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4310.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4310.md index 0daee29ed4..97a146b576 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4310.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4310.md @@ -1,21 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4310" -title: "Compiler Warning (level 3) C4310" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4310" +title: "Compiler Warning (level 4) C4310" +ms.date: 10/17/2023 f1_keywords: ["C4310"] helpviewer_keywords: ["C4310"] -ms.assetid: cba3eca1-f1ed-499c-9243-337446bdbdd8 --- -# Compiler Warning (level 3) C4310 +# Compiler Warning (level 4) C4310 -cast truncates constant value +> cast truncates constant value A constant value is cast to a smaller type. The compiler performs the cast, which truncates data. The following sample generates C4310: ```cpp // C4310.cpp // compile with: /W4 -int main() { +int main() +{ long int a; a = (char) 128; // C4310, use value 0-127 to resolve } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4334.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4334.md index 2f372281b8..7b3c4b482c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4334.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4334.md @@ -8,9 +8,9 @@ ms.assetid: d845857f-bc95-4faf-a079-626a0cf935ba --- # Compiler Warning (level 3) C4334 -'operator' : result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?) +'operator': result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?) -The result of 32-bit shift was implicitly converted to 64-bits, and the compiler suspects that a 64-bit shift was intended. To resolve this warning, either use 64-bit shift, or explicitly cast the shift result to 64-bit. +The result of 32-bit shift was converted to 64-bit, and the compiler suspects that a 64-bit shift was intended. Resolve this warning by using a 64-bit shift. If a 32-bit shift is intentional, then cast the shift result to 32-bit to make it clear to the compiler. ## Example @@ -20,7 +20,9 @@ The following sample generates C4334. // C4334.cpp // compile with: /W3 /c void SetBit(unsigned __int64 *p, int i) { - *p |= (1 << i); // C4334 - *p |= (1i64 << i); // OK + *p |= (1 << i); // C4334, 32-bit shift cast to 64-bit + *p |= (1i64 << i); // OK, 64-bit shift + *p |= static_cast(1 << i); // OK, 32-bit shift saved to 64-bit result + *p |= static_cast<__int64>(1) << i; // OK, 64-bit shift } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4359.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4359.md index f4f62e9759..1323cb6fe5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4359.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4359.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4359" -title: "Compiler Warning (level 3) C4359" +description: "Learn more about: Compiler Warning (level 1 and level 3) C4359" +title: "Compiler Warning (level 1 and level 3) C4359" ms.date: "11/04/2016" f1_keywords: ["C4359"] helpviewer_keywords: ["C4359"] -ms.assetid: d8fe993c-ef82-45a0-a43d-c29f9d1bacdb --- -# Compiler Warning (level 3) C4359 +# Compiler Warning (level 1 and level 3) C4359 -'type': actual alignment (8) is greater than the value specified in __declspec(align()) +> 'type': actual alignment (8) is greater than the value specified in __declspec(align()) -The alignment specified for a type is less than the alignment of the type of one of its data members. For more information, see [align](../../cpp/align-cpp.md). +The alignment specified for a type is less than the alignment of the type of one of its data members. For more information, see [align](../../cpp/align-cpp.md). ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4373.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4373.md index ee956ccc2e..4bcae67303 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4373.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4373.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4373" -title: "Compiler Warning (level 3) C4373" +description: "Learn more about: Compiler Warning (level 4) C4373" +title: "Compiler Warning (level 4) C4373" ms.date: "11/04/2016" f1_keywords: ["C4373"] helpviewer_keywords: ["C4373"] -ms.assetid: 670c0ba3-b7d6-4aed-b207-1cb84da3bcde --- -# Compiler Warning (level 3) C4373 +# Compiler Warning (level 4) C4373 > '*function*': virtual function overrides '*base_function*', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers ## Remarks -Your application contains a method in a derived class that overrides a virtual method in a base class, and the parameters in the overriding method differ by only a [const](../../cpp/const-cpp.md) or [volatile](../../cpp/volatile-cpp.md) qualifier from the parameters of the virtual method. This means the compiler must bind a function reference to the method in either the base or derived class. +Your application contains a method in a derived class that overrides a virtual method in a base class. The parameters in the overriding method differ by a [`const`](../../cpp/const-cpp.md) or [`volatile`](../../cpp/volatile-cpp.md) qualifier from the parameters of the virtual method. -Versions of the compiler prior to Visual Studio 2008 bind the function to the method in the base class, then issue a warning message. Later versions of the compiler ignore the **`const`** or **`volatile`** qualifier, bind the function to the method in the derived class, then issue warning **C4373**. The later behavior conforms to the C++ standard. +Before Visual Studio 2008, the compiler would bind the function to the method in the base class. Later versions of the compiler ignore the **`const`** or **`volatile`** qualifier, bind the function to the method in the derived class, then issue warning **C4373**. The latter behavior conforms to the C++ standard. ## Example -The following code example generates warning C4373. To resolve this issue, you can either make the override use the same CV-qualifiers as the base member function, or if you did not intend to create an override, you can give the function in the derived class a different name. +The following code example generates warning C4373. To resolve this issue, make the override use the same CV-qualifiers as the base member function. If you didn't intend to create an override, rename the function in the derived class. ```cpp // c4373.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4534.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4534.md index 82420cf1d0..9e5841e73a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4534.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4534.md @@ -2,9 +2,8 @@ description: "Learn more about: Compiler Warning (level 3) C4534" title: "Compiler Warning (level 3) C4534" ms.date: "11/04/2016" -f1_keywords: ["c4534"] +f1_keywords: ["C4534"] helpviewer_keywords: ["C4534"] -ms.assetid: ec2adf3b-d7a1-4005-bb0c-5d219df78dc8 --- # Compiler Warning (level 3) C4534 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md index 40a319396a..a753799357 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md @@ -1,20 +1,24 @@ --- description: "Learn more about: Compiler Warning (level 3) C4995" title: "Compiler Warning (level 3) C4995" -ms.date: "11/04/2016" +ms.date: 08/30/2022 f1_keywords: ["C4995"] helpviewer_keywords: ["C4995"] ms.assetid: c6b61755-4730-4947-ad4d-d1c2bc82585a --- # Compiler Warning (level 3) C4995 -'function': name was marked as #pragma deprecated +> '*function*': name was marked as `#pragma deprecated` -The compiler encountered a function that was marked with pragma [deprecated](../../preprocessor/deprecated-c-cpp.md). The function may no longer be supported in a future release. You can turn this warning off with the [warning](../../preprocessor/warning.md) pragma (example below). +## Remarks + +The compiler encountered a function that was marked with [`#pragma deprecated`](../../preprocessor/deprecated-c-cpp.md). The function may no longer be supported in a future release. You can turn off this warning by using [`#pragma warning`](../../preprocessor/warning.md). + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example -The following sample generates C4995: +The following sample generates C4995. Uncomment the `#pragma warning` line to disable the warning. ```cpp // C4995.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md index 4385832759..db12f3841f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md @@ -1,7 +1,7 @@ --- title: "Compiler Warning (level 3) C4996" description: "Explains why Compiler warning C4996 happens, and describes what to do about it." -ms.date: 07/09/2020 +ms.date: 08/30/2022 f1_keywords: ["C4996"] helpviewer_keywords: ["C4996"] ms.assetid: 926c7cc2-921d-43ed-ae75-634f560dd317 @@ -15,7 +15,9 @@ Your code uses a function, class member, variable, or typedef that's marked *dep ## Remarks -Many functions, member functions, template functions, and global variables in Visual Studio libraries are *deprecated*. Some, such as POSIX and Microsoft-specific functions, are deprecated because they now have a different preferred name. Some C runtime library functions are deprecated because they're insecure and have a more secure variant. Others are deprecated because they're obsolete. The deprecation messages usually include a suggested replacement for the deprecated function or global variable. +Many functions, member functions, function templates, and global variables in Visual Studio libraries are *deprecated*. Some, such as POSIX and Microsoft-specific functions, are deprecated because they now have a different preferred name. Some C runtime library functions are deprecated because they're insecure and have a more secure variant. Others are deprecated because they're obsolete. The deprecation messages usually include a suggested replacement for the deprecated function or global variable. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Turn off the warning @@ -87,7 +89,7 @@ For more information about these deprecated functions and globals, see [Security **`'std::`** *`function_name`* **`::_Unchecked_iterators::_Deprecate' Call to std::`** *`function_name`* **`with parameters that may be unsafe - this call relies on the caller to check that the passed values are correct. To disable this warning, use -D_SCL_SECURE_NO_WARNINGS. See documentation on how to use Visual C++ 'Checked Iterators'`** -In Visual Studio 2015, this warning appears in debug builds because certain C++ Standard Library template functions don't check parameters for correctness. Often it's because not enough information is available to the function to check container bounds. Or, because iterators may be used incorrectly with the function. This warning helps you identify these functions, because they may be a source of serious security holes in your program. For more information, see [Checked iterators](../../standard-library/checked-iterators.md). +In Visual Studio 2015, this warning appears in debug builds because certain C++ Standard Library function templates don't check parameters for correctness. Often it's because not enough information is available to the function to check container bounds. Or, because iterators may be used incorrectly with the function. This warning helps you identify these functions, because they may be a source of serious security holes in your program. For more information, see [Checked iterators](../../standard-library/checked-iterators.md). For example, this warning appears in Debug mode if you pass an element pointer to `std::copy`, instead of a plain array. To fix this issue, use an appropriately declared array, so the library can check the array extents and do bounds checking. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4001.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4001.md index cea9a5aa4a..73499a4579 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4001.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4001.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4001" -title: "Compiler Warning (level 4) C4001" +description: "Learn more about: Compiler Warning (level 4, no longer emitted) C4001" +title: "Compiler Warning (level 4, no longer emitted) C4001" ms.date: "11/04/2016" f1_keywords: ["C4001"] helpviewer_keywords: ["C4001"] -ms.assetid: 414a47fe-d597-425e-9374-6a569231dc0a --- -# Compiler Warning (level 4) C4001 +# Compiler Warning (level 4, no longer emitted) C4001 -nonstandard extension 'single line comment' was used +> nonstandard extension 'single line comment' was used > [!NOTE] > This warning is removed in Visual Studio 2017 version 15.5 because single-line comments are standard in C99. Single-line comments are standard in C++ and standard in C starting with C99. -Under strict ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)), C files that contain single-line comments, generate C4001 due to the usage of a nonstandard extension. Since single-line comments are standard in C++, C files containing single-line comments do not produce C4001 when compiling with Microsoft extensions (/Ze). +Under strict ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)), C files that contain single-line comments, generate C4001 due to the usage of a nonstandard extension. Since single-line comments are standard in C++, C files containing single-line comments don't produce C4001 when compiling with Microsoft extensions (/Ze). ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4019.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4019.md index 0a68e08ae7..60b67551c2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4019.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4019.md @@ -10,10 +10,13 @@ ms.assetid: 4ecfe85d-673f-4334-8154-36fe7f0b3444 empty statement at global scope -A semicolon at global scope is not preceded by a statement. +A semicolon at global scope isn't preceded by a statement. This warning may be fixed if you remove the extra semicolon. +> [!Important] +> This warning only applies to C programs. + ## Example ```c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4061.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4061.md index fb09ff4c50..a3649649a1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4061.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4061.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4061" -title: "Compiler Warning (level 4) C4061" +description: "Learn more about: Compiler Warning (level 4, off) C4061" +title: "Compiler Warning (level 4, off) C4061" ms.date: "04/05/2019" f1_keywords: ["C4061"] helpviewer_keywords: ["C4061"] -ms.assetid: a99cf88e-7941-4519-8b1b-f6889d914b2f --- -# Compiler Warning (level 4) C4061 +# Compiler Warning (level 4, off) C4061 -> enumerator '*identifier*' in switch of enum '*enumeration*' is not explicitly handled by a case label +> enumerator '*identifier*' in switch of `enum` '*enumeration*' is not explicitly handled by a `case` label -The specified enumerator *identifier* has no associated handler in a **`switch`** statement that has a **`default`** case. The missing case might be an oversight, or it may not be an issue. It may depend on whether the enumerator is handled by the default case or not. For a related warning on unused enumerators in **`switch`** statements that have no **`default`** case, see [C4062](compiler-warning-level-4-c4062.md). +The specified enumerator *identifier* has no associated handler in a `switch` statement that has a `default` case. The missing case might be an oversight, or it may not be an issue. Whether the missing `case` is an issue in practice depends on if the default case handles the enumerator. For a related warning on unused enumerators in `switch` statements that have no `default` case, see [C4062](compiler-warning-level-4-c4062.md). This warning is off by default. For more information about how to enable warnings that are off by default, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). @@ -34,10 +33,6 @@ void func ( E e ) break; } // C4061 c' not handled } - -int main() -{ -} ``` ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4062.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4062.md index 7a88ec1ecc..e6430b05b8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4062.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4062.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4062" -title: "Compiler Warning (level 4) C4062" +description: "Learn more about: Compiler Warning (level 4, off) C4062" +title: "Compiler Warning (level 4, off) C4062" ms.date: "04/05/2019" f1_keywords: ["C4062"] helpviewer_keywords: ["C4062"] -ms.assetid: 36d1c6ae-c917-4b08-bf30-2eb49ee94169 --- -# Compiler Warning (level 4) C4062 +# Compiler Warning (level 4, off) C4062 -> enumerator '*identifier*' in switch of enum '*enumeration*' is not handled +> enumerator '*identifier*' in switch of `enum` '*enumeration*' is not handled -The enumerator *identifier* has no associated `case` handler in a **`switch`** statement, and there's no **`default`** label that can catch it. The missing case may be an oversight, and is a potential error in your code. For a related warning on unused enumerators in **`switch`** statements that have a **`default`** case, see [C4061](compiler-warning-level-4-c4061.md). +The enumerator *identifier* doesn't have a `case` handler associated with it in a **`switch`** statement, and there's no **`default`** label that can catch it. The missing case may be an oversight, and is a potential error in your code. For a related warning on unused enumerators in **`switch`** statements that have a **`default`** case, see [C4061](compiler-warning-level-4-c4061.md). This warning is off by default. For more information about how to enable warnings that are off by default, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). @@ -31,9 +30,6 @@ void func ( E e ) { break; // no default label } // C4062, enumerator 'c' not handled } - -int main() { -} ``` ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4100.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4100.md index 189fa4462c..b4b8cfae66 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4100.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4100.md @@ -1,27 +1,25 @@ --- description: "Learn more about: Compiler Warning (level 4) C4100" title: "Compiler Warning (level 4) C4100" -ms.date: "11/04/2016" +ms.date: 04/22/2025 f1_keywords: ["C4100"] helpviewer_keywords: ["C4100"] -ms.assetid: 478ed97d-e502-49e4-9afb-ac2a6c61194b --- # Compiler Warning (level 4) C4100 -'identifier' : unreferenced formal parameter +> 'identifier' : unreferenced formal parameter The formal parameter is not referenced in the body of the function. The unreferenced parameter is ignored. -C4100 can also be issued when code calls a destructor on a otherwise unreferenced parameter of primitive type. This is a limitation of the Microsoft C++ compiler. +C4100 can also be issued when code calls a destructor on an otherwise unreferenced parameter of primitive type. The following sample generates C4100: ```cpp // C4100.cpp // compile with: /W4 -void func(int i) { // C4100, delete the unreferenced parameter to - //resolve the warning - // i; // or, add a reference like this +void func(int i) { // C4100, delete the unreferenced parameter to resolve the warning + // i; // Or uncomment this line to add a reference } int main() diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4189.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4189.md index 7c3e2d6bf6..6376aebe9d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4189.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4189.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4189" -title: "Compiler Warning (level 4) C4189" +description: "Learn more about: Compiler Warning (level 3 and level 4) C4189" +title: "Compiler Warning (level 3 and level 4) C4189" ms.date: 05/03/2021 f1_keywords: ["C4189"] helpviewer_keywords: ["C4189"] --- -# Compiler Warning (level 4) C4189 +# Compiler Warning (level 3 and level 4) C4189 > '*identifier*' : local variable is initialized but not referenced @@ -19,16 +19,16 @@ The following sample generates C4189: // C4189.cpp // compile with: /W4 int main() { - int a = 1; // C4189, remove declaration to resolve + int a = 1; // C4189 } ``` -Starting in Visual Studio 2017 version 15.5, warning C4189 is emitted in more cases, as shown in the following code: +In Visual Studio 2017 version 15.5 and later, warning C4189 is emitted in more cases, as shown in the following code: ```cpp void f() { - char s[2] = {0}; // C4189. Either use the variable or remove it. + char s[2] = {0}; // C4189 } ``` -To fix the error, remove the unused variable. +To fix the error, remove the unused variable or add the `[[maybe_unused]]` attribute. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4205.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4205.md index 82848a4a96..2deee61561 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4205.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4205.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4205" title: "Compiler Warning (level 4) C4205" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4205" +ms.date: 11/04/2016 f1_keywords: ["C4205"] helpviewer_keywords: ["C4205"] -ms.assetid: 39b5108c-7230-41b4-b2fe-2293eb6aae28 --- # Compiler Warning (level 4) C4205 @@ -20,7 +19,7 @@ With Microsoft extensions (/Ze), **`static`** functions can be declared inside a void func1() { static int func2(); // C4205 -}; +} int main() { diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4233.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4233.md index 92cb29c0fe..7987d2e583 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4233.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4233.md @@ -1,19 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4233" -title: "Compiler Warning (level 4) C4233" +description: "Learn more about: Compiler Warning (level 1, Error) C4233" +title: "Compiler Warning (level 1, Error) C4233" ms.date: "10/25/2017" f1_keywords: ["C4233"] helpviewer_keywords: ["C4233"] -ms.assetid: 9aa51fc6-8ef3-43b5-bafb-c9333cf60de3 --- -# Compiler Warning (level 4) C4233 +# Compiler Warning (level 1, Error) C4233 -> nonstandard extension used : '*keyword*' keyword only supported in C++, not C +> nonstandard extension used: '*keyword*' keyword only supported in C++, not C The compiler compiled your source code as C rather than C++, and you used a keyword that is only valid in C++. The compiler compiles your source file as C if the extension of the source file is .c or you use [/Tc](../../build/reference/tc-tp-tc-tp-specify-source-file-type.md). -This warning is automatically promoted to an error. If you wish to modify this behavior, use [#pragma warning](../../preprocessor/warning.md). For example, to make C4233 into a level 4 warning issue, add this line to your source code file: - -```cpp -#pragma warning(4:4233) -``` +This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4235.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4235.md index 4c75a0cdca..b555d0df57 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4235.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4235.md @@ -1,21 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4235" -title: "Compiler Warning (level 4) C4235" +description: "Learn more about: Compiler Warning (level 1, Error) C4235" +title: "Compiler Warning (level 1, Error) C4235" ms.date: "11/04/2016" f1_keywords: ["C4235"] helpviewer_keywords: ["C4235"] -ms.assetid: d4214799-d62c-4674-b4e2-9e201c303303 --- -# Compiler Warning (level 4) C4235 +# Compiler Warning (level 1, Error) C4235 -nonstandard extension used : 'keyword' keyword not supported on this architecture +> nonstandard extension used: '*keyword*' keyword not supported on this architecture -The compiler does not support the keyword you used. +The compiler doesn't support the keyword you used on the architecture your build is targeting. -This warning is automatically promoted to an error. If you wish to modify this behavior, use [#pragma warning](../../preprocessor/warning.md). For example, to make C4235 into a level 2 warning, use the following line of code - -```cpp -#pragma warning(2:4235) -``` - -in your source code file. +This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4242.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4242.md index 2196063782..f0d4ccb106 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4242.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4242.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4242" -title: "Compiler Warning (level 4) C4242" +description: "Learn more about: Compiler Warning (level 3, off) C4242" +title: "Compiler Warning (level 3, off) C4242" ms.date: "11/04/2016" f1_keywords: ["C4242"] helpviewer_keywords: ["C4242"] -ms.assetid: 8df742e1-fbf1-42f3-8e93-c0e1c222dc7e --- -# Compiler Warning (level 4) C4242 +# Compiler Warning (level 3, off) C4242 -'identifier' : conversion from 'type1' to 'type2', possible loss of data +> '*identifier*': conversion from '*type1*' to '*type2*', possible loss of data The types are different. Type conversion may result in loss of data. The compiler makes the type conversion. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). -For additional information on C4242, see [Common Compiler Errors](/windows/win32/WinProg64/common-compiler-errors). +For more information on C4242, see [Common Compiler Errors](/windows/win32/WinProg64/common-compiler-errors). The following sample generates C4242: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4254.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4254.md index a5a4987a12..dbcbdcc801 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4254.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4254.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4254" -title: "Compiler Warning (level 4) C4254" -ms.date: "11/04/2016" -f1_keywords: ["c4254"] +title: "Compiler Warning (level 4, off) C4254" +description: "Learn more about: Compiler Warning (level 4, off) C4254" +ms.date: 11/04/2016 +f1_keywords: ["C4254"] helpviewer_keywords: ["C4254"] -ms.assetid: c7dcef24-d535-4c98-bb41-fc3d2b88fd11 --- # Compiler Warning (level 4) C4254 -'operator' : conversion from 'type1' to 'type2', possible loss of data +> '*operator*': conversion from '*type1*':'*field_bits*' to '*type2*':'*field_bits*', possible loss of data A larger bit field was assigned to a smaller bit field. There could be a loss of data. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4254: @@ -32,5 +31,5 @@ int main() { x->a = 4; x->a = x->b; // OK x->b = x->a; // C4254 -}; +} ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4255.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4255.md index ff98dea558..4358f2e093 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4255.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4255.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4255" -title: "Compiler Warning (level 4) C4255" +description: "Learn more about: Compiler Warning (level 4, off) C4255" +title: "Compiler Warning (level 4, off) C4255" ms.date: "11/04/2016" f1_keywords: ["C4255"] helpviewer_keywords: ["C4255"] -ms.assetid: 2087b635-4b4c-4182-8a01-c26770d2bb88 --- -# Compiler Warning (level 4) C4255 +# Compiler Warning (level 4, off) C4255 -'function' : no function prototype given: converting '()' to '(void)' +> 'function' : no function prototype given: converting '()' to '(void)' -The compiler did not find an explicit list of arguments to a function. This warning is for the C compiler only. +The compiler didn't find an explicit list of arguments to a function. This warning is for the C compiler only. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4255: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4263.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4263.md index 7fa9923092..7ea2676192 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4263.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4263.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4263" -title: "Compiler Warning (level 4) C4263" +description: "Learn more about: Compiler Warning (level 4, off) C4263" +title: "Compiler Warning (level 4, off) C4263" ms.date: "11/04/2016" f1_keywords: ["C4263"] helpviewer_keywords: ["C4263"] -ms.assetid: daabb05d-ab56-460f-ab6c-c74d222ef649 --- -# Compiler Warning (level 4) C4263 +# Compiler Warning (level 4, off) C4263 -'function' : member function does not override any base class virtual member function +> 'function' : member function does not override any base class virtual member function -A class function definition has the same name as a virtual function in a base class but not the same number or type of arguments. This effectively hides the virtual function in the base class. +A class function definition has the same name as a virtual function in a base class but not the same number or type of arguments. This pattern effectively hides the virtual function in the base class. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4263: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4266.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4266.md index fccff4b84f..88e8e554df 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4266.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4266.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4266" -title: "Compiler Warning (level 4) C4266" +description: "Learn more about: Compiler Warning (level 4, off) C4266" +title: "Compiler Warning (level 4, off) C4266" ms.date: "11/04/2016" f1_keywords: ["C4266"] helpviewer_keywords: ["C4266"] -ms.assetid: 90ec5f5b-3451-4c16-bb1b-c30a626bdaa0 --- -# Compiler Warning (level 4) C4266 +# Compiler Warning (level 4, off) C4266 -'function' : no override available for virtual member function from base 'type'; function is hidden +> 'function' : no override available for virtual member function from base 'type'; function is hidden -A derived class did not override all overloads of a virtual function. +A derived class didn't override all overloads of a virtual function. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4266: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4289.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4289.md index 3f29ff0cfa..e12bb325ac 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4289.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4289.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4289" -title: "Compiler Warning (level 4) C4289" +description: "Learn more about: Compiler Warning (level 4, off) C4289" +title: "Compiler Warning (level 4, off) C4289" ms.date: "11/04/2016" f1_keywords: ["C4289"] helpviewer_keywords: ["C4289"] -ms.assetid: 0dbd2863-4cde-4e16-894b-104a2d5fa724 --- -# Compiler Warning (level 4) C4289 +# Compiler Warning (level 4, off) C4289 -nonstandard extension used : 'var' : loop control variable declared in the for-loop is used outside the for-loop scope +> nonstandard extension used : 'var' : loop control variable declared in the `for`-loop is used outside the `for`-loop scope -When compiling with [/Ze](../../build/reference/za-ze-disable-language-extensions.md) and **/Zc:forScope-**, a variable declared in a [for](../../cpp/for-statement-cpp.md) loop was used after the **`for`**-loop scope. +When [/Ze](../../build/reference/za-ze-disable-language-extensions.md) and **/Zc:forScope-** are used in a build, a variable declared in a [`for`](../../cpp/for-statement-cpp.md) loop was used after the **`for`**-loop scope. See [/Zc:forScope](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) for information about how to specify standard behavior in **`for`** loops with **/Ze**. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4289: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4296.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4296.md index eb4f2ed99e..39cb0b6e93 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4296.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4296.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4296" -title: "Compiler Warning (level 4) C4296" +description: "Learn more about: Compiler Warning (level 4, off) C4296" +title: "Compiler Warning (level 4, off) C4296" ms.date: "11/04/2016" f1_keywords: ["C4296"] helpviewer_keywords: ["C4296"] -ms.assetid: 9d99aafe-f6bd-4ee0-b8d0-98ce5712274d --- -# Compiler Warning (level 4) C4296 +# Compiler Warning (level 4, off) C4296 -'operator' : expression is always false +> 'operator' : expression is always false An unsigned variable was used in a comparison operation with zero. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4296: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4324.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4324.md index f50703025a..f2f4076e29 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4324.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4324.md @@ -4,13 +4,12 @@ title: "Compiler Warning (level 4) C4324" ms.date: "11/04/2016" f1_keywords: ["C4324"] helpviewer_keywords: ["C4324"] -ms.assetid: 420fa929-d9c0-40b4-8808-2d8ad3ca8090 --- # Compiler Warning (level 4) C4324 -'struct_name' : structure was padded due to __declspec(align()) +> '*structname*': structure was padded due to alignment specifier -Padding was added at the end of a structure because you specified a [__declspec(align)](../../cpp/align-cpp.md) value. +Padding was added at the end of a structure because you specified an alignment specifier, such as [__declspec(align)](../../cpp/align-cpp.md). For example, the following code generates C4324: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4339.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4339.md index 4b868b05e1..77a9a5a3e5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4339.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4339.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4339" -title: "Compiler Warning (level 4) C4339" +description: "Learn more about: Compiler Warning (level 4, off) C4339" +title: "Compiler Warning (level 4, off) C4339" ms.date: "11/04/2016" f1_keywords: ["C4339"] helpviewer_keywords: ["C4339"] -ms.assetid: 5b83353d-7777-4afb-8476-3c368349028c --- -# Compiler Warning (level 4) C4339 +# Compiler Warning (level 4, off) C4339 -'type' : use of undefined type detected in WinRT or CLR meta-data - use of this type may lead to a runtime exception +> 'type' : use of undefined type detected in WinRT or CLR meta-data - use of this type may lead to a runtime exception -A type was not defined in code that was compiled for Windows Runtime or the common language runtime. Define the type to avoid a possible runtime exception. +A type wasn't defined in code that was compiled for Windows Runtime or the common language runtime. Define the type to avoid a possible runtime exception. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). The following sample generates C4339 and shows how to fix it: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4365.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4365.md index 931b249b13..d26dec6ad7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4365.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4365.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4365" -title: "Compiler Warning (level 4) C4365" +description: "Learn more about: Compiler Warning (level 4, off) C4365" +title: "Compiler Warning (level 4, off) C4365" ms.date: "11/04/2016" f1_keywords: ["C4365"] helpviewer_keywords: ["C4365"] -ms.assetid: af4b4191-bdfd-4dbb-8229-3ba4405df257 --- -# Compiler Warning (level 4) C4365 +# Compiler Warning (level 4, off) C4365 -'action' : conversion from 'type_1' to 'type_2', signed/unsigned mismatch +> 'action' : conversion from 'type_1' to 'type_2', signed/unsigned mismatch -For example, you tried to convert an unsigned value to a signed value. +For example, you tried to convert an unsigned value to a signed value. This pattern can cause unexpected results when the source value at runtime in not in the range of the destination type. Such as a negative value being converted into a signed value. -C4365 is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). +C4365 is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4389.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4389.md index 77af090278..ce2dce28c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4389.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4389.md @@ -1,8 +1,8 @@ --- title: "Compiler Warning (level 4) C4389" -description: "Microsoft C/C++ compiler warning C4389, its causes and resolution." +description: "Learn more about: Compiler Warning (level 4) C4389" ms.date: 10/16/2020 -f1_keywords: ["c4389"] +f1_keywords: ["C4389"] helpviewer_keywords: ["C4389"] --- # Compiler Warning (level 4) C4389 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4400.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4400.md index 071fc9c192..a97330018c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4400.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4400.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4400" -title: "Compiler Warning (level 4) C4400" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4, error) C4400" +title: "Compiler warning (level 4, error) C4400" +ms.date: "1/22/2025" f1_keywords: ["C4400"] helpviewer_keywords: ["C4400"] -ms.assetid: f135fe98-4f92-4e07-9d71-2621b36ee755 --- -# Compiler Warning (level 4) C4400 +# Compiler warning (level 4, error) C4400 -'type' : const/volatile qualifiers on this type are not supported +> '*type*': `const`/`volatile` qualifiers on this type are not supported -The [const](../../cpp/const-cpp.md)and [volatile](../../cpp/volatile-cpp.md)qualifiers will not work with variables of common language runtime types. +The [`const`](../../cpp/const-cpp.md) and [`volatile`](../../cpp/volatile-cpp.md) qualifiers don't work with common language runtime typed variables. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4435.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4435.md index c60d859b88..8b30d0111b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4435.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4435.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4435" -title: "Compiler Warning (level 4) C4435" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4, off) C4435" +title: "Compiler Warning (level 4, off) C4435" +ms.date: "1/22/2025" f1_keywords: ["C4435"] helpviewer_keywords: ["C4435"] -ms.assetid: a04524af-2b71-4ff9-9729-d9d1d1904ed7 --- -# Compiler Warning (level 4) C4435 +# Compiler warning (level 4, off) C4435 -'class1' : Object layout under /vd2 will change due to virtual base 'class2' +> '*derived_class*': Object layout under `/vd2` will change due to virtual base '*base_class*' -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). -Under the default compile option of /vd1, the derived class does not have a `vtordisp` field for the indicated virtual base. If /vd2 or `#pragma vtordisp(2)` is in effect, a `vtordisp` field will be present, changing the object layout. This can lead to binary compatibility problems if interacting modules are compiled with different `vtordisp` settings. +Under the default compile option of `/vd1`, the derived class doesn't have a `vtordisp` field for the indicated virtual base. If `/vd2` or `#pragma vtordisp(2)` is in effect, a `vtordisp` field is present, changing the object layout. This difference can lead to binary compatibility problems if interacting modules are compiled with different `vtordisp` settings. ## Example @@ -34,5 +33,5 @@ class B : public virtual A // C4435 ## See also -[vtordisp](../../preprocessor/vtordisp.md)
-[/vd (Disable Construction Displacements)](../../build/reference/vd-disable-construction-displacements.md) +[`vtordisp`](../../preprocessor/vtordisp.md)\ +[`/vd` (Disable Construction Displacements)](../../build/reference/vd-disable-construction-displacements.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4437.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4437.md index a2207a1ad8..6a5a36565b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4437.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4437.md @@ -1,32 +1,28 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4437" -title: "Compiler Warning (level 4) C4437" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1 and level 4, off) C4437" +title: "Compiler warning (level 1 and level 4, off) C4437" +ms.date: "1/22/2025" f1_keywords: ["C4437"] helpviewer_keywords: ["C4437"] -ms.assetid: dc07e350-20eb-474c-a7ad-f841ae7ec339 --- -# Compiler Warning (level 4) C4437 +# Compiler warning (level 1 and level 4, off) C4437 -dynamic_cast from virtual base 'class1' to 'class2' could fail in some contexts Compile with /vd2 or define 'class2' with #pragma vtordisp(2) in effect +> `dynamic_cast` from virtual base '*base_class*' to '*derived_class*' could fail in some contexts -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). -The compiler has encountered a **`dynamic_cast`** operation with the following characteristics. +A `dynamic_cast` operation is used when: - The cast is from a base class pointer to a derived class pointer. - - The derived class virtually inherits the base class. +- The derived class doesn't have a `vtordisp` field for the virtual base. +- The cast is found in a constructor or destructor of the derived class, or a class that inherits from the derived class. Otherwise, compiler warning [C4436](compiler-warning-level-1-c4436.md) is emitted issued of C4435. -- The derived class does not have a `vtordisp` field for the virtual base. - -- The cast is not found in a constructor or destructor of the derived class, or some class which further inherits from the derived class (otherwise, compiler warning C4436 will be issued). - -The warning indicates that the **`dynamic_cast`** might not perform correctly if it is operating on a partially-constructed object. This situation occurs when the enclosing function is called from a constructor or destructor of a class that inherits the derived class that is named in the warning. If the derived class that is named in the warning is never further derived, or the enclosing function is not called during object construction or destruction, the warning can be ignored. +This warning indicates that the `dynamic_cast` might not perform correctly when applied to a partially constructed object. This situation occurs when the enclosing function is called from a constructor or destructor of a class that inherits from *derived_class*. You can ignore the error if *derived_class* is never further derived, or the enclosing function isn't called during object construction or destruction. ## Example -The following sample generates C4437 and demonstrates the code generation issue that arises from the missing `vtordisp` field. +The following sample generates C4437 and demonstrates the code generation issue that arises from the missing `vtordisp` field: ```cpp // C4437.cpp @@ -76,6 +72,6 @@ int main() ## See also -[dynamic_cast Operator](../../cpp/dynamic-cast-operator.md)
-[vtordisp](../../preprocessor/vtordisp.md)
-[Compiler Warning (level 1) C4436](../../error-messages/compiler-warnings/compiler-warning-level-1-c4436.md) +[`dynamic_cast` Operator](../../cpp/dynamic-cast-operator.md)\ +[`vtordisp`](../../preprocessor/vtordisp.md)\ +[Compiler Warning (level 1) C4436](compiler-warning-level-1-c4436.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md index de023ee907..ca3587adea 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md @@ -1,30 +1,44 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4464" +description: "Learn more about: Compiler Warning (level 4, off) C4464" title: "Compiler Warning (level 4) C4464" -ms.date: "03/13/2018" +ms.date: 09/14/2022 f1_keywords: ["C4464"] helpviewer_keywords: ["C4464"] --- -# Compiler Warning (level 4) C4464 +# Compiler Warning (level 4, off) C4464 -> **relative include path contains '..'** +> relative include path contains '..' -A `#include` directive has a path that includes a '..' parent directory specifier. +A `#include` directive has a path that includes a parent directory specifier (a `..` path segment). ## Remarks -Starting in Visual Studio 2015 Update 1, the compiler can detect an include directive that contains a '..' path segment and issue a warning, if enabled. Code written in this way is usually intended to include headers that exist outside of the project by incorrectly using project-relative paths. This creates a risk that the program could be compiled by including a different source file than the programmer intends, or that these relative paths would not be portable to other build environments. Although there is no specific warning for it, we also recommend that you do not use a parent directory path segment to specify your project include directories. +In Visual Studio 2015 Update 1 and later versions, if enabled, the compiler can detect and issue a warning for a `#include` directive that contains a parent directory path segment (`..`). Code is sometimes written that uses parent directory relative paths to include headers from external libraries. When these parent directory-relative header paths are specified in source files, it creates a risk: The program could be compiled by including a different header file than the programmer intends. These relative paths may not be portable to other developers' build environments. -This warning is new in Visual Studio 2015 Update 1, and is off by default. Use [/Wall](../../build/reference/compiler-option-warning-level.md) to enable all warnings that are off by default, or __/w__*n*__4464__ to enable C4464 as a level *n* warning. For more information, see [Compiler Warnings That Are Off By Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). +Instead, we recommend you specify the paths to such headers in the build environment, such as in the `INCLUDE` environment variable or in parameters to the [`/I` (Additional include directories)](../../build/reference/i-additional-include-directories.md) compiler option. In the Visual Studio IDE, you can set the paths in your project's **Configuration Properties** > **C/C++** > **General** property page, in the **Additional Include Directories** property. Although there's no specific warning for it, we also don't recommend use of parent directory path segments when you specify your project's include directories. + +Warning C4464 is new in Visual Studio 2015 Update 1, and is off by default. Use [`/Wall`](../../build/reference/compiler-option-warning-level.md) to enable all warnings that are off by default. Use **`/wN4464`** to enable C4464 as a level `N` warning (where `N` is 1-4). For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). For information on how to disable warnings introduced in or after a specific compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). ## Example -Source code files that use '..' path segments can trigger this warning when the **/Wall** option is specified: +Source code files that use `..` path segments in `#include` directives can trigger this warning when C4464 is enabled or when the **`/Wall`** option is specified. + +In this example, the project source is in *`C:\project\source`* and an external library's header files are in *`C:\other_lib\headers`*: ```cpp -#include "..\headers\C4426.h" // emits warning C4464 +// C:\project\source\C4464.cpp +// Compile by using: cl /w14464 C4464.cpp +#include "..\..\other_lib\headers\other.h" // C4464 +#include "..\..\other_lib\headers\extras\nested.h" // C4464 +// . . . +``` -// To fix this issue, specify only the header file name, and add -// the absolute path to 'headers\' to your project's include directories -#include "C4426.h" +To fix this issue, add the path *`C:\other_lib\headers`* to your project's include directories. Then, change the source to include the header files as external headers: + +```cpp +// C:\project\source\C4464b.cpp +// Compile by using: cl /w14464 /I"C:\other_lib\headers" C4464b.cpp +#include // OK +#include // OK +// . . . ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md index 4365461a87..958561ae41 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md @@ -39,6 +39,8 @@ enum Example; // C4471 In C++11, you can add an explicit type to an unscoped enumeration and to its forward declaration. We recommend this solution only if complex header inclusion logic prevents use of the definition instead of a forward declaration. This solution can lead to a maintenance issue: if you change the underlying type used for the enumeration definition, you must also change all of the forward declarations to match, or you may have silent errors in your code. You can put the forward declaration into a header file to minimize this issue. +Source file `C4471c.cpp`: + ```cpp // C4471c.cpp // Client code for enumeration defined in C4471d.cpp @@ -49,6 +51,8 @@ enum Example; // C4471, int assumed // ... ``` +Source file `C4471d.cpp`: + ```cpp // C4471d.cpp // Definition for enumeration used in C4471c.cpp @@ -61,6 +65,8 @@ If you specify an explicit type for an enumeration, we recommend you also enable You can change your code to use a scoped enum, a feature that is new in C++11. Both the definition and any client code that uses the enumeration type must be changed to use a scoped enum. We recommend you use a scoped enum if you have issues with namespace pollution, as the names of defined enumeration items are limited to the scope of the enum. Another feature of a scoped enum is that its members can't be implicitly converted to another integral or enumeration type, which can be a source of subtle bugs. +Source file `C4471e.cpp`: + ```cpp // C4471e.cpp // Client code for scoped enumeration defined in C4471f.cpp @@ -71,6 +77,8 @@ enum Example; // C4471 // ... ``` +Source file `C4471f.cpp`: + ```cpp // C4471f.cpp // Definition for scoped enumeration used in C4471e.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md index d5831092ad..012e051384 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md @@ -1,18 +1,18 @@ --- description: "Learn more about: Compiler Warning (level 4) C4623" title: "Compiler Warning (level 4) C4623" -ms.date: "11/04/2016" +ms.date: 10/27/2022 f1_keywords: ["C4623"] helpviewer_keywords: ["C4623"] ms.assetid: e630d8d0-f6ea-469c-a74f-07b027587225 --- # Compiler Warning (level 4) C4623 -'`derived class`' : default constructor was implicitly defined as deleted because a base class default constructor is inaccessible or deleted +> '`derived class`' : default constructor was implicitly defined as deleted -A constructor was not accessible in a base class and was not generated for the derived class. Any attempt to create an object of this type on the stack will cause a compiler error. +Because the default constructor is deleted or inaccessible in a base class, the compiler can't generate a default constructor for the derived class. Attempts to create an object of this type by using the default constructor (for example, in an array) cause a compiler error. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example @@ -35,6 +35,6 @@ class D : public B {}; // C4623 - to fix, make B's constructor public class E : public C {}; // OK - class C constructor is public int main() { - // D d; will cause an error + // D d; // Error C2280 } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md index edc4555635..af2e4d53e9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md @@ -1,16 +1,20 @@ --- description: "Learn more about: Compiler Warning (level 4) C4703" title: "Compiler Warning (level 4) C4703" -ms.date: "11/04/2016" +ms.date: 08/30/2022 f1_keywords: ["C4703"] helpviewer_keywords: ["C4703"] ms.assetid: 5dad454e-69e3-4931-9168-050a861c05f8 --- # Compiler Warning (level 4) C4703 -Potentially uninitialized local pointer variable 'name' used +> Potentially uninitialized local pointer variable 'name' used -The local pointer variable *name* might have been used without being assigned a value. This could lead to unpredictable results. +## Remarks + +The local pointer variable *name* might have been used without being assigned a value. This access could lead to unpredictable results. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example @@ -65,5 +69,5 @@ int main() ## See also -[Compiler Warning (level 4) C4701](../../error-messages/compiler-warnings/compiler-warning-level-4-c4701.md)
-[Warnings, /sdl, and improving uninitialized variable detection](https://www.microsoft.com/security/blog/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/) +[Compiler Warning (level 4) C4701](../../error-messages/compiler-warnings/compiler-warning-level-4-c4701.md)\ +[Warnings, `/sdl`, and improving uninitialized variable detection](https://www.microsoft.com/security/blog/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md index 6fa2feebb0..d31d01fd41 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md @@ -1,70 +1,65 @@ --- description: "Learn more about: Compiler Warning (level 4) C4706" title: "Compiler Warning (level 4) C4706" -ms.date: "11/04/2016" +ms.date: "3/5/2025" f1_keywords: ["C4706"] helpviewer_keywords: ["C4706"] -ms.assetid: 89cd3f4f-812c-4a4b-9426-65a5a6d1b99c --- # Compiler Warning (level 4) C4706 -assignment within conditional expression +> assignment used as a condition -The test value in a conditional expression was the result of an assignment. +The test value in a conditional expression is the result of an assignment. An assignment has a value (the value on the left side of the assignment) that can be used legally in another expression, including a test expression. The following sample generates C4706: ```cpp -// C4706a.cpp // compile with: /W4 int main() { int a = 0, b = 0; - if ( a = b ) // C4706 + if (a = b) // C4706 { } } ``` -The warning will occur even if you double the parentheses around the test condition: +Suppress the warning with `((`*expression*`))`. For example: ```cpp -// C4706b.cpp // compile with: /W4 int main() { int a = 0, b = 0; - if ( ( a = b ) ) // C4706 + if ((a = b)) // No warning { } } ``` -If your intention is to test a relation and not to make an assignment, use the `==` operator. For example, the following line tests whether a and b are equal: +If your intention is to test a relation, not to make an assignment, use the `==` operator. For example, the following tests whether a and b are equal: ```cpp -// C4706c.cpp // compile with: /W4 int main() { int a = 0, b = 0; - if ( a == b ) + if (a == b) { } } ``` -If you intend to make your test value the result of an assignment, test to ensure that the assignment is non-zero or not null. For example, the following code will not generate this warning: +If you intend to make your test value the result of an assignment, test to ensure that the assignment is non-zero or non-null. For example, the following code doesn't generate this warning: ```cpp -// C4706d.cpp // compile with: /W4 int main() { int a = 0, b = 0; - if ( ( a = b ) != 0 ) + if ((a = b) != 0) { } } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md index c6b5ccc34d..d1767d4750 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md @@ -38,7 +38,7 @@ int main() a.x = 15; throw a; } - catch (ALIGNEDA b) // can’t align b to > 16 bytes + catch (ALIGNEDA b) // can't align b to > 16 bytes { printf_s("%d\n", b.x); } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c5266.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c5266.md new file mode 100644 index 0000000000..f4e794516d --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c5266.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: Compiler Warning (level 4) C5266" +title: "Compiler Warning (level 4) C5266" +ms.date: 01/18/2024 +f1_keywords: ["C5266"] +helpviewer_keywords: ["C5266"] +--- +# Compiler Warning (level 4) C5266 + +> 'const' qualifier on return type has no effect + +The C++ Standard specifies that a top-level const (or volatile) qualification on a function return type is ignored. + +This warning is off by default.\ +This warning was introduced in Visual Studio 17.6 + +## Example + +The following sample generates C5266: + +```cpp +// compile with: /W4 /c + +#pragma warning(default : 5266) // enable warning C5266 because it's off by default (or compile with /w45266) + +const int f() // warning C5266: 'const' qualifier on return type has no effect +{ + return 13; +} +``` + +## See also + +[Enable warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) \ No newline at end of file diff --git a/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4112.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4112.md index e8ca7c73d0..6dc4a888be 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4112.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4112.md @@ -1,25 +1,24 @@ --- -description: "Learn more about: Compiler Warning (levels 1 and 4) C4112" -title: "Compiler Warning (levels 1 and 4) C4112" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4112" +title: "Compiler Warning (level 1 and level 4) C4112" ms.date: "11/04/2016" f1_keywords: ["C4112"] helpviewer_keywords: ["C4112"] -ms.assetid: aff64897-bb79-4a67-9b6f-902c6d44f3dc --- -# Compiler Warning (levels 1 and 4) C4112 +# Compiler Warning (level 1 and level 4) C4112 -\#line requires an integer between 1 and number +> `#line` requires an integer between 1 and '*line_count*' The [#line](../../preprocessor/hash-line-directive-c-cpp.md) directive specifies an integer parameter that is outside the allowable range. -If the specified parameter is less than 1, the line counter is reset to 1. If the specified parameter is greater than *number*, which is the compiler-defined limit, the line counter is unchanged. This is a level 1 warning under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) and a level 4 warning with Microsoft extensions ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)). +If the specified parameter is less than 1, the line counter is reset to 1. If the specified parameter is greater than *number*, which is the compiler-defined limit, the line counter is unchanged. This diagnostic is a level 1 warning under ANSI C compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) and a level 4 warning with Microsoft extensions ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)). The following sample generates C4112: ```cpp // C4112.cpp // compile with: /W4 -#line 0 // C4112, value must be between 1 and number +#line 0 // C4112 int main() { } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4223.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4223.md index 1cd6fb3afc..bc05a609f2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4223.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4223.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: Compiler Warning (levels 1 and 4) C4223" -title: "Compiler Warning (levels 1 and 4) C4223" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4223" +title: "Compiler Warning (level 1 and level 4) C4223" ms.date: "11/04/2016" f1_keywords: ["C4223"] helpviewer_keywords: ["C4223"] ms.assetid: 6fc44336-0250-4432-928b-fc5dbe7b7c1c --- -# Compiler Warning (levels 1 and 4) C4223 +# Compiler Warning (level 1 and level 4) C4223 -nonstandard extension used : non-lvalue array converted to pointer +> nonstandard extension used: non-lvalue array converted to pointer -In standard C, you cannot convert a non-lvalue array to a pointer. With the default Microsoft extensions ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)), you can. +In standard C, you can't convert a nonlvalue array to a pointer. With the default Microsoft extensions ([`/Ze`](../../build/reference/za-ze-disable-language-extensions.md)), you can. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-4-c4200.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-4-c4200.md index 8a6bd71ddf..309f2b0317 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-4-c4200.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-4-c4200.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: Compiler Warning (levels 2 and 4) C4200" -title: "Compiler Warning (levels 2 and 4) C4200" +description: "Learn more about: Compiler Warning (level 2 and level 4) C4200" +title: "Compiler Warning (level 2 and level 4) C4200" ms.date: "11/04/2016" f1_keywords: ["C4200"] helpviewer_keywords: ["C4200"] -ms.assetid: e44d6073-937f-42b7-acc1-65e802b475c6 --- -# Compiler Warning (levels 2 and 4) C4200 +# Compiler Warning (level 2 and level 4) C4200 -nonstandard extension used : zero-sized array in struct/union +> nonstandard extension used: zero-sized array in struct/union -Indicates that a structure or union contains an array that has zero size. - -Declaration of a zero-sized array is a Microsoft extension. This causes a Level-2 warning when a C++ file is compiled and a Level-4 warning when a C file is compiled. C++ compilation also gives this warning: "Cannot generate copy-ctor or copy-assignment operator when UDT contains a zero-sized array." This example generates warning C4200: +C++ only: +> This member will be ignored by a defaulted constructor or copy/move assignment operator + +This warning indicates that a structure or union contains an array that has zero size. Declaration of a zero-sized array is a nonstandard compiler extension. This causes a Level-2 warning when a C++ file is compiled and a Level-4 warning when a C file is compiled. This example generates warning C4200: ```cpp // C4200.cpp // compile by using: cl /W4 c4200.cpp struct A { + int len; int a[0]; // C4200 }; -int main() { -} ``` -This non-standard extension is often used to interface code with external data structures that have a variable length. If this scenario applies to your code, you can disable the warning: +This nonstandard extension is often used to interface code with external data structures that have a variable length. If this scenario applies to your code, you can disable the warning: ## Example @@ -33,8 +32,7 @@ This non-standard extension is often used to interface code with external data s // compile by using: cl /W4 c4200a.cpp #pragma warning(disable : 4200) struct A { + int len; int a[0]; }; -int main() { -} ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-levels-3-and-4-c4244.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-3-and-4-c4244.md index 6e064a47f8..75b41ea7dd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-3-and-4-c4244.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-3-and-4-c4244.md @@ -1,51 +1,56 @@ --- description: "Learn more about: Compiler Warning (levels 3 and 4) C4244" title: "Compiler Warning (levels 3 and 4) C4244" -ms.date: "11/04/2016" -ms.assetid: f116bb09-c479-4b4e-a647-fe629a1383f6 +ms.date: "11/6/2023" --- # Compiler Warning (levels 3 and 4) C4244 'conversion' conversion from 'type1' to 'type2', possible loss of data -An integer type is converted to a smaller integer type. This is a level-4 warning if *type1* is **`int`** and *type2* is smaller than **`int`**. Otherwise, it is a level 3 (assigned a value of type [__int64](../../cpp/int8-int16-int32-int64.md) to a variable of type **`unsigned int`**). A possible loss of data may have occurred. +An integer type is converted to a smaller integer type. +- This is a level-4 warning if *type1* is a signed or unsigned **`int`** and *type2* is a smaller, such as a signed or unsigned **`short`**. +- It's a level 3 warning if a value of type [`__int64`](../../cpp/int8-int16-int32-int64.md) or **`unsigned __int64`** is assigned to a signed or unsigned **`int`**. A possible loss of data may have occurred due to a narrowing conversion, which might lead to unexpected results. -If you get C4244, you should either change your program to use compatible types, or add some logic to your code, to ensure that the range of possible values will always be compatible with the types you are using. +To fix this warning, either change your program to use compatible types, or add logic that ensures that the range of possible values is compatible with the types you're using. If the conversion is intended, use an explicit cast to silence the warning. -C4244 can also fire at level 2; see [Compiler Warning (level 2) C4244](../../error-messages/compiler-warnings/compiler-warning-level-2-c4244.md) for more information. - -The conversion may have a problem due to implicit conversions. +C4244 can also appear when the warning level is 2. For more information, see [Compiler Warning (level 2) C4244](../../error-messages/compiler-warnings/compiler-warning-level-2-c4244.md). The following sample generates C4244: ```cpp // C4244_level4.cpp // compile with: /W4 -int aa; -unsigned short bb; +void test(unsigned short num) {} + int main() { - int b = 0, c = 0; - short a = b + c; // C4244 + int int1 = 1; + unsigned int uint1 = 2; - bb += c; // C4244 - bb = bb + c; // C4244 - bb += (unsigned short)aa; // C4244 - bb = bb + (unsigned short)aa; // OK + short short1 = int1; // C4244 + short short2 = (short)int1; // warning silenced - explicit cast + + short short3 = uint1; // C4244 + unsigned short ushort = uint1; // C4244 + test(uint1); // C4244 } ``` -For more information, see [Usual Arithmetic Conversions](../../c-language/usual-arithmetic-conversions.md). +For more information, see [Usual Arithmetic Conversions](../../c-language/usual-arithmetic-conversions.md).\ +For more information about setting the warning level in Visual Studio, see [To set the compiler options in the Visual Studio development environment](../../build/reference/compiler-option-warning-level.md#to-set-the-compiler-options-in-the-visual-studio-development-environment) ```cpp // C4244_level3.cpp // compile with: /W3 int main() { - __int64 i = 8; - unsigned int ii = i; // C4244 + __int64 i64 = 1; + unsigned __int64 u64 = 2; + + int int1 = i64; // C4244 + int int3 = u64; // C4244 } ``` -Warning C4244 can occur when building code for 64-bit targets that does not generate the warning when building for 32-bit targets. For example, a difference between pointers is a 32-bit quantity on 32-bit platforms, but a 64-bit quantity on 64-bit platforms. +Warning C4244 can occur when building code for 64-bit targets that doesn't generate the warning when building for 32-bit targets. For example, pointer arithmetic results in a 32-bit quantity on 32-bit platforms, but a 64-bit quantity on 64-bit platforms. The following sample generates C4244 when compiled for 64-bit targets: diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md b/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md index 772903fbd2..f68e772b83 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md @@ -1,7 +1,7 @@ --- title: "Compiler Warnings by compiler version" description: "Table of Microsoft C/C++ compiler warnings by compiler version." -ms.date: 12/01/2021 +ms.date: 01/18/2024 helpviewer_keywords: ["warnings, by compiler version", "cl.exe compiler, setting warning options"] --- # Compiler Warnings by compiler version @@ -12,38 +12,50 @@ These versions of the compiler introduced new warnings: | Product | Compiler version number | |--|--| -| Visual Studio 2002 | 13.00.9466 | -| Visual Studio 2003 | 13.10.3077 | -| Visual Studio 2005 | 14.00.50727.762 | -| Visual Studio 2008 | 15.00.21022.08 | -| Visual Studio 2010 | 16.00.40219.01 | -| Visual Studio 2012 | 17.00.51106.1 | -| Visual Studio 2013 | 18.00.21005.1 | -| Visual Studio 2015 RTM | 19.00.23026.0 | -| Visual Studio 2015 Update 1 | 19.00.23506.0 | -| Visual Studio 2015 Update 2 | 19.00.23918.0 | -| Visual Studio 2015 Update 3 | 19.00.24215.1 | -| Visual Studio 2017 RTM | 19.10.25017.0 | -| Visual Studio 2017 version 15.3 | 19.11.25506.0 | -| Visual Studio 2017 version 15.5 | 19.12.25830.0 | -| Visual Studio 2017 version 15.6 | 19.13.26128.0 | -| Visual Studio 2017 version 15.7 | 19.14.26428.0 | -| Visual Studio 2017 version 15.8 | 19.15.26726.0 | -| Visual Studio 2017 version 15.9 | 19.16.26926.0 | -| Visual Studio 2019 RTM | 19.20.27004.0 | -| Visual Studio 2019 version 16.1 | 19.21.27702.0 | -| Visual Studio 2019 version 16.2 | 19.22.27905.0 | -| Visual Studio 2019 version 16.3 | 19.23.28105.0 | -| Visual Studio 2019 version 16.4 | 19.24.28314.0 | -| Visual Studio 2019 version 16.5 | 19.25.28610.0 | -| Visual Studio 2019 version 16.6 | 19.26.28805.0 | -| Visual Studio 2019 version 16.7 | 19.27.29112.0 | -| Visual Studio 2019 version 16.8 | 19.28.29333.0 | -| Visual Studio 2019 version 16.9 | 19.28.29700.0 | -| Visual Studio 2019 version 16.10 | 19.29.30000.0 | -| Visual Studio 2019 version 16.11 | 19.29.30100.0 | -| Visual Studio 2022 version 17.0 RTW | 19.30 | +| Visual Studio 2022 version 17.13 | 19.43 | +| Visual Studio 2022 version 17.12 | 19.42 | +| Visual Studio 2022 version 17.11 | 19.41 | +| Visual Studio 2022 version 17.10 | 19.40 | +| Visual Studio 2022 version 17.9 | 19.39 | +| Visual Studio 2022 version 17.8 | 19.38 | +| Visual Studio 2022 version 17.7 | 19.37 | +| Visual Studio 2022 version 17.6 | 19.36 | +| Visual Studio 2022 version 17.5 | 19.35 | +| Visual Studio 2022 version 17.4 | 19.34 | +| Visual Studio 2022 version 17.3 | 19.33 | +| Visual Studio 2022 version 17.2 | 19.32 | | Visual Studio 2022 version 17.1 | 19.31 | +| Visual Studio 2022 version 17.0 RTW | 19.30 | +| Visual Studio 2019 version 16.11 | 19.29.30100.0 | +| Visual Studio 2019 version 16.10 | 19.29.30000.0 | +| Visual Studio 2019 version 16.9 | 19.28.29700.0 | +| Visual Studio 2019 version 16.8 | 19.28.29333.0 | +| Visual Studio 2019 version 16.7 | 19.27.29112.0 | +| Visual Studio 2019 version 16.6 | 19.26.28805.0 | +| Visual Studio 2019 version 16.5 | 19.25.28610.0 | +| Visual Studio 2019 version 16.4 | 19.24.28314.0 | +| Visual Studio 2019 version 16.3 | 19.23.28105.0 | +| Visual Studio 2019 version 16.2 | 19.22.27905.0 | +| Visual Studio 2019 version 16.1 | 19.21.27702.0 | +| Visual Studio 2019 RTM | 19.20.27004.0 | +| Visual Studio 2017 version 15.9 | 19.16.26926.0 | +| Visual Studio 2017 version 15.8 | 19.15.26726.0 | +| Visual Studio 2017 version 15.7 | 19.14.26428.0 | +| Visual Studio 2017 version 15.6 | 19.13.26128.0 | +| Visual Studio 2017 version 15.5 | 19.12.25830.0 | +| Visual Studio 2017 version 15.3 | 19.11.25506.0 | +| Visual Studio 2017 RTM | 19.10.25017.0 | +| Visual Studio 2015 Update 3 | 19.00.24215.1 | +| Visual Studio 2015 Update 2 | 19.00.23918.0 | +| Visual Studio 2015 Update 1 | 19.00.23506.0 | +| Visual Studio 2015 RTM | 19.00.23026.0 | +| Visual Studio 2013 | 18.00.21005.1 | +| Visual Studio 2012 | 17.00.51106.1 | +| Visual Studio 2010 | 16.00.40219.01 | +| Visual Studio 2008 | 15.00.21022.08 | +| Visual Studio 2005 | 14.00.50727.762 | +| Visual Studio 2003 | 13.10.3077 | +| Visual Studio 2002 | 13.00.9466 | You can specify only the major number, the major and minor numbers, or the major, minor, and build numbers to the **`/Wv`** option. The compiler reports all warnings that match versions that begin with the specified number. It suppresses all warnings for versions greater than the specified number. For example, **`/Wv:17`** reports warnings introduced in or before any version of Visual Studio 2012, and suppresses warnings introduced by any compiler from Visual Studio 2013 (version 18) or later. To suppress warnings introduced in Visual Studio 2015 update 2 and later, you can use **`/Wv:19.00.23506`**. Use **`/Wv:19.11`** to report the warnings introduced in any version of Visual Studio before Visual Studio 2017 version 15.5, but suppress warnings introduced in Visual Studio 2017 version 15.5 and later. @@ -51,9 +63,135 @@ The following sections list the warnings introduced by each version of Visual C+ ::: moniker range=">= msvc-170" +## Warnings introduced in Visual Studio 2022 version 17.13 (compiler version 19.43) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.42`**. + +| Warning | Message | +|--|--| +|C5277| type trait optimization for '*class name*' is disabled +|C5308| Modifying reserved macro name '*macro name*' may cause undefined behavior +|C5309| literal suffix '*name*' requires at least '*language version*' + +## Warnings introduced in Visual Studio 2022 version 17.12 (compiler version 19.42) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.41`**. + +| Warning | Message | +|--|--| +|C5086| Arch setting *arch* and vector length *number* are not allowed. Using the default vector length - *number*. +|C5276| `/experimental:ifcDebugRecords` currently requires `/Z7` to be enabled. Please recompile with `/Z7` enabled. +|C5306| parameter array behavior change: overload '*identifier 1*' resolved to '*identifier 2*'; previously, it would have resolved to '*identifier 3*'. Use `/clr:ECMAParamArray` to revert to old behavior +|C5307| '*function*': argument (*argument number*) converted from '*type 1*' to '*type 2*'. Missing '`L`' encoding-prefix for character literal? + + +## Warnings introduced in Visual Studio 2022 version 17.11 (compiler version 19.41) + +There were no new warnings introduced in 17.11 + +## Warnings introduced in Visual Studio 2022 version 17.10 (compiler version 19.40) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.39`**. + +| Warning | Message | +|--|--| +|C4859 | '*value*' is not a valid argument for '`/presetWarn`': it must be a decimal value > 0. Command-line flag ignored| +|C4860 | '*object name*': compiler zero initialized '*number*' bytes of storage| +|C4861 | compiler zero initialized '*number*' bytes of storage| +|C5273 | behavior change: `_Alignas` on anonymous type no longer ignored (promoted members will align)| +|C5274 | behavior change: `_Alignas` no longer applies to the type '*type*' (only applies to declared data objects)| +|C5275 | facade assembly '*name*' being imported under '`/clr`'; missing option '`/clr:netcore`'?| +|C5304 | a declaration designated by the using-declaration '*name1*' exported from this module has internal linkage and using such a name outside the module is ill-formed; consider declaring '*name2*' '`inline`' to use it outside of this module| +|C5305 | '*name*': an explicit instantiation declaration that follows an explicit instantiation definition is ignored| + +## Warnings introduced in Visual Studio 2022 version 17.9 (compiler version 19.39) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.38`**. + +| Warning | Message | +|--|--| +|C4975 | modopt '[*modifier*]' was ignored for formal parameter '*parameter*'| +|C5272 | throwing an object of non-copyable type '*type*' is non-standard. If a copy is needed at runtime it will be made as if by `memcpy`.| + +## Warnings introduced in Visual Studio 2022 version 17.8 (compiler version 19.38) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.37`**. + +| Warning | Message | +|--|--| +|C5109|`__VA_OPT__` use in macro requires '`/Zc:preprocessor`'| +|C5110|`__VA_OPT__` is an extension prior to C++20 or C23| +|C5271 | previously imported assembly '*assembly1*' has the same name as assembly '*assembly2*' being imported. Is this intentional?| +|C5303 | function marked with `[[msvc::intrinsic]]` did not result in a no-op cast| + +## Warnings introduced in Visual Studio 2022 version 17.7 (compiler version 19.37) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.36`**. + +| Warning | Message | +|--|--| +|C4907|multiple calling conventions cannot be specified; last given will be used| +|[C5267](c5267.md) | definition of implicit copy constructor/assignment operator for '*type*' is deprecated because it has a user-provided assignment operator/copy constructor| +|C5268 | Failed to allocate memory at fixed address 0x*address*. Use `/Yb` to specify a specific address base if bit-identical .pch files are required.| +|C5269 | Failed to allocate PCH memory at fixed address 0x*address*. Use `/Ym` to specify a specific address base if bit-identical .pch files are required.| +|C5270 | '*value*' is not allowed for option '*switch name*'; allowed values are: *value list*| + +## Warnings introduced in Visual Studio 2022 version 17.6 (compiler version 19.36) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.35`**. + +| Warning | Message | +|--|--| +|[C5266](compiler-warning-level-4-c5266.md) | 'const' qualifier on return type has no effect| + +## Warnings introduced in Visual Studio 2022 version 17.5 (compiler version 19.35) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.34`**. + +| Warning | Message | +|--|--| +|C5082|second argument to 'va_start' is not the last named parameter| +|C5265 | cannot open search path '*path*'| + +## Warnings introduced in Visual Studio 2022 version 17.4 (compiler version 19.34) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.33`**. + +| Warning | Message | +|--|--| +| C5260 | the constant variable '*variable-name*' has internal linkage in an included header file context, but external linkage in imported header unit context; consider declaring it '`inline`' as well if it will be shared across translation units, or '`static`' to express intent to use it local to this translation unit | +| C5261 | no integer type can represent all enumerator values in enumeration '*enum-name*' | +| [C5262](c5262.md) | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases | +| C5263 | calling '`std::move`' on a temporary object prevents copy elision | +| C5264 | '*variable-name*': '`const`' variable is not used | + +## Warnings introduced in Visual Studio 2022 version 17.3 (compiler version 19.33) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.32`**. + +| Warning | Message | +|--|--| +| C5259 | '*specialized-type*': explicit specialization requires 'template <>' | + +## Warnings introduced in Visual Studio 2022 version 17.2 (compiler version 19.32) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.31`**. + +| Warning | Message | +|--|--| +| C4983 | '/analyze:sarif:hashname' ignored because the argument to '/analyze:log' is a single file rather than a directory | +| C5081 | Secure hotpatch is not supported with /GENPROFILE, /FASTGENPROFILE or /LTCG:PGI, disabling secure hotpatch. | +| C5255 | unterminated bidirectional character encountered: 'U+XXXX' | +| C5256 | '*enumeration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration | +| C5257 | '*enumeration*': enumeration was previously declared without a fixed underlying type | +| C5258 | explicit capture of '*symbol*' is not required for this use | +| C5300 | '#pragma omp atomic': left operand of '*operator*' must match left hand side of assignment-expression | +|[C5301](c5301-c5302.md) | '#pragma omp for': '*loop-index*' increases while loop condition uses '*comparison*'; non-terminating loop?| +|[C5302](c5301-c5302.md) | '#pragma omp for': '*loop-index*' decreases while loop condition uses '*comparison*'; non-terminating loop?| + ## Warnings introduced in Visual Studio 2022 version 17.1 (compiler version 19.31) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.30`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.30`**. | Warning | Message | |--|--| @@ -63,7 +201,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2022 version 17.0 (compiler version 19.30) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.29`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.29`**. | Warning | Message | |--|--| @@ -80,16 +218,16 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.11 (compiler version 19.29.30100.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.29.30099`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.29.30099`**. | Warning | Message | |--|--| -| C5247 | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | -| C5248 | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified | +| [C5247](c5247.md) | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | +| [C5248](c5248.md) | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified | ## Warnings introduced in Visual Studio 2019 version 16.10 (compiler version 19.29.30000.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.28`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.28`**. | Warning | Message | |--|--| @@ -100,14 +238,14 @@ These warnings and all warnings in later versions are suppressed by using the co | C5237 | cannot resolve header unit entry '*string*' to a header file in '*filename*'; ignoring entry | | C5238 | file system error: cannot open '*filename*' for reading; ignoring | | C5239 | '*Symbol*': potentially-throwing function called from a function declared `__declspec(nothrow)`. Undefined behavior may occur if an exception is thrown. | -| C5240 | '*attribute-string*': attribute is ignored in this syntactic position | +| [C5240](c5240.md) | '*attribute-string*': attribute is ignored in this syntactic position | | C5241 | '`/exportHeader`' usage to lookup header-name is deprecated; prefer '`/headerName:arg-1 arg-2=filename`' | | C5242 | syntax error in pragma '*pragma-name*' | -| C5243 | '*Type-name*': using incomplete class '*symbol*' can cause potential one definition rule violation due to ABI limitation | +| [C5243](c5243.md) | '*Type-name*': using incomplete class '*symbol*' can cause potential one definition rule violation due to ABI limitation | ## Warnings introduced in Visual Studio 2019 version 16.9 (compiler version 19.28.29700.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.28.29699`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.28.29699`**. | Warning | Message | |--|--| @@ -115,11 +253,11 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.8 (compiler version 19.28.29333.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.27`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.27`**. | Warning | Message | |--|--| -| C5072 | `ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting` | +| [C5072](compiler-warning-c5072.md) | `ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting` | | C5211 | `'keyword-1' has been deprecated; prefer using 'keyword-2' instead` | | C5222 | `'attribute-name': all unscoped attribute names are reserved for future standardization` | | C5223 | `all attribute names in the attribute namespace 'msvc' are reserved for the implementation` | @@ -134,7 +272,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.7 (compiler version 19.27.29112.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.26`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.26`**. | Warning | Message | |--|--| @@ -154,16 +292,16 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.6 (compiler version 19.26.28805.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.25`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.25`**. | Warning | Message | |--|--| | C5207 | `the simple requirement asserts the validity of expression 'e->id'. Did you mean '{ e } -> id'? You can suppress the warning using '{ e->id }'` | -| C5208 | `unnamed class used in typedef name cannot declare members other than non-static data members, member enumerations, or member classes` | +| [C5208](c5208.md) | `unnamed class used in typedef name cannot declare members other than non-static data members, member enumerations, or member classes` | ## Warnings introduced in Visual Studio 2019 version 16.5 (compiler version 19.25.28610.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.24`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.24`**. |Warning|Message| |-|-| @@ -177,7 +315,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.4 (compiler version 19.24.28314.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.23`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.23`**. | Warning | Message | |--|--| @@ -188,7 +326,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.3 (compiler version 19.23.28105.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.22`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.22`**. | Warning | Message | |--|--| @@ -197,14 +335,14 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.2 (compiler version 19.22.27905.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.21`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.21`**. | Warning | Message | |--|--| | C4855 | `implicit capture of 'this' via '[=]' is deprecated in 'version'` | -| C5054 | `operator 'operator-name': deprecated between enumerations of different types` | -| C5055 | `operator 'operator-name': deprecated between enumerations and floating-point types` | -| C5056 | `operator 'operator-name': deprecated for array types` | +| [C5054](c5054.md) | `operator 'operator-name': deprecated between enumerations of different types` | +| [C5055](c5055.md) | `operator 'operator-name': deprecated between enumerations and floating-point types` | +| [C5056](c5056.md) | `operator 'operator-name': deprecated for array types` | | C5057 | `header unit reference to 'name' already exists. Ignoring header unit 'header-name'` | | C5058 | `file system error: cannot find header file 'file-name' for header unit 'unit-name'` | | C5059 | `runtime checks and address sanitizer is not currently supported - disabling runtime checks` | @@ -212,7 +350,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.1 (compiler version 19.21.27702.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.20`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.20`**. | Warning | Message | |--|--| @@ -221,7 +359,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 RTW (compiler version 19.20.27004.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.15`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.15`**. | Warning | Message | |--|--| @@ -234,7 +372,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.8 (compiler version 19.15.26726.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.14`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.14`**. | Warning | Message | |--|--| @@ -244,32 +382,32 @@ These warnings and all warnings in later versions are suppressed by using the co | C4846 | `'value' is not a valid argument for '/d1initall': command-line flag ignored` | | C4847 | `'__declspec(no_init_all)' can only be applied to a function, a class type, or a local variable: ignored` | | C4866 | `compiler may not enforce left-to-right evaluation order for call to 'function'` | -| C5046 | `'function': Symbol involving type with internal linkage not defined` | +| [C5046](c5046.md) | `'function': Symbol involving type with internal linkage not defined` | | C5047 | `use of nonstandard __if_exists with modules is not supported` | | C5048 | `Use of macro 'macroname' may result in non-deterministic output` | | C5049 | `'string': Embedding a full path may result in machine-dependent output` | -| C5050 | `Possible incompatible environment while importing module 'module_name': issue` | +| [C5050](c5050.md) | `Possible incompatible environment while importing module 'module_name': issue` | | C5100 | `__VA_ARGS__ is reserved for use in variadic macros` | | C5101 | `use of preprocessor directive in function-like macro argument list is undefined behavior` | | C5102 | `ignoring invalid command-line macro definition 'value'` | | C5103 | `pasting 'token1' and 'token2' does not result in a valid preprocessing token` | | C5104 | `found 'string1#string2' in macro replacement list, did you mean 'string1""#string2'?` | -| C5105 | `macro expansion producing 'defined' has undefined behavior` | +| [C5105](c5105.md) | `macro expansion producing 'defined' has undefined behavior` | | C5106 | `macro redefined with different parameter names` | | C5107 | `missing terminating 'char' character` | ## Warnings introduced in Visual Studio 2017 version 15.7 (compiler version 19.14.26428.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.13`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.13`**. | Warning | Message | |--|--| | C4642 | `'issue': could not import the constraints for generic parameter 'parameter'` | -| C5045 | `Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified` | +| [C5045](c5045.md) | `Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified` | ## Warnings introduced in Visual Studio 2017 version 15.6 (compiler version 19.13.26128.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.12`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.12`**. | Warning | Message | |--|--| @@ -277,11 +415,11 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.5 (compiler version 19.12.25830.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.11`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.11`**. | Warning | Message | |--|--| -| C4843 | `'type1': An exception handler of reference to array or function type is unreachable, use 'type2' instead` | +| [C4843](c4843.md) | `'type1': An exception handler of reference to array or function type is unreachable, use 'type2' instead` | | C4844 | `'export module module_name;' is now the preferred syntax for declaring a module interface` | | C5039 | `'function': pointer or reference to potentially throwing function passed to extern C function under -EHc. Undefined behavior may occur if this function throws an exception.` | | C5040 | `dynamic exception specifications are valid only in C++14 and earlier; treating as noexcept(false)` | @@ -291,64 +429,64 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.3 (compiler version 19.11.25506.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.10`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.10`**. | Warning | Message | |--|--| -| C4597 | `undefined behavior: description` | +| [C4597](c4597.md) | `undefined behavior: description` | | C4604 | `'type': passing argument by value across native and managed boundary requires valid copy constructor. Otherwise the runtime behavior is undefined` | | C4749 | `conditionally supported: description` | -| C4768 | `__declspec attributes before linkage specification are ignored` | -| C4834 | `discarding return value of function with 'nodiscard' attribute` | -| C4841 | `non-standard extension used: extension` | +| [C4768](c4768.md) | `__declspec attributes before linkage specification are ignored` | +| [C4834](c4834.md) | `discarding return value of function with 'nodiscard' attribute` | +| [C4841](c4841.md) | `non-standard extension used: extension` | | C4842 | `the result of 'offsetof' applied to a type using multiple inheritance is not guaranteed to be consistent between compiler releases` | | C4869 | `'nodiscard' may only be applied to classes, enumerations, and functions with non-void return type` | -| C4984 | `'if constexpr' is a C++17 language extension` | -| C5033 | `'*storage-class*' is no longer a supported storage class` | +| [C4984](compiler-warning-c4984.md) | `'if constexpr' is a C++17 language extension` | +| [C5033](c5033.md) | `'*storage-class*' is no longer a supported storage class` | | C5034 | `use of intrinsic 'intrinsic' causes function function to be compiled as guest code` | | C5035 | `use of feature 'feature' causes function function to be compiled as guest code` | | C5036 | `varargs function pointer conversion when compiling with /hybrid:x86arm64 'type1' to 'type2'` | -| C5037 | `'*member-function*': an out-of-line definition of a member of a class template cannot have default arguments` | -| C5038 | `data member 'member1' will be initialized after data member 'member2'` | +| [C5037](c5037.md) | `'*member-function*': an out-of-line definition of a member of a class template cannot have default arguments` | +| [C5038](c5038.md) | `data member 'member1' will be initialized after data member 'member2'` | ## Warnings introduced in Visual Studio 2017 RTM (compiler version 19.10.25017.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00`**. | Warning | Message | |--|--| | C4468 | `'fallthrough': attribute must be followed by a case label or a default label` | -| C4698 | `'feature' is for evaluation purposes only and is subject to change or removal in future updates.` | -| C4839 | `non-standard use of class 'class' as an argument to a variadic function` | -| C4840 | `non-portable use of class 'class' as an argument to a variadic function` | +| [C4698](c4698.md) | `'feature' is for evaluation purposes only and is subject to change or removal in future updates.` | +| [C4839](compiler-warning-level-3-c4839.md) | `non-standard use of class 'class' as an argument to a variadic function` | +| [C4840](compiler-warning-level-4-c4840.md) | `non-portable use of class 'class' as an argument to a variadic function` | ::: moniker-end ## Warnings introduced in Visual Studio 2015 Update 3 (compiler version 19.00.24215.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23918`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23918`**. | Warning | Message | |--|--| | C4467 | `usage of ATL attributes is deprecated` | -| C4596 | `'name': illegal qualified name in member declaration` | +| [C4596](c4596.md) | `'name': illegal qualified name in member declaration` | | C4598 | `'#include

': header number number in the source does not match source at that position` | | C4599 | `'argument': source argument number number does not match source` | ## Warnings introduced in Visual Studio 2015 Update 2 (compiler version 19.00.23918.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23506`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23506`**. | Warning | Message | |--|--| | C4466 | `Could not perform coroutine heap elision` | | C4595 | `'class': non-member operator new or delete functions may not be declared inline` | | C4828 | `The file contains a character starting at offset 0xvalue that is illegal in the current source character set (codepage number).` | -| C4868 | `compiler may not enforce left-to-right evaluation order in braced initializer list` | +| [C4868](compiler-warning-c4868.md) | `compiler may not enforce left-to-right evaluation order in braced initializer list` | ## Warnings introduced in Visual Studio 2015 Update 1 (compiler version 19.00.23506.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23026`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23026`**. | Warning | Message | |--|--| @@ -359,24 +497,24 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2015 RTM (compiler version 19.00.23026.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:18`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:18`**. | Warning | Message | |--|--| | C4427 | `'error': overflow in constant division, undefined behavior` | | C4438 | `'type': cannot be called safely in /await:clrcompat mode. If 'type' calls into the CLR it may result in CLR head corruption` | | C4455 | `'operator name': literal suffix identifiers that do not start with an underscore are reserved` | -| C4456 | `declaration of 'name' hides previous local declaration` | -| C4457 | `declaration of 'name' hides function parameter` | -| C4458 | `declaration of 'name' hides class member` | -| C4459 | `declaration of 'name' hides global declaration` | -| C4462 | `'type' : cannot determine the GUID of the type. Program may fail at runtime.` | -| C4463 | `overflow; assigning value to bit-field that can only hold values from value to value` | -| C4473 | `'function' : not enough arguments passed for format string` | +| [C4456](compiler-warning-level-4-c4456.md) | `declaration of 'name' hides previous local declaration` | +| [C4457](compiler-warning-level-4-c4457.md) | `declaration of 'name' hides function parameter` | +| [C4458](compiler-warning-level-4-c4458.md) | `declaration of 'name' hides class member` | +| [C4459](compiler-warning-level-4-c4459.md) | `declaration of 'name' hides global declaration` | +| [C4462](compiler-warning-level-1-c4462.md) | `'type' : cannot determine the GUID of the type. Program may fail at runtime.` | +| [C4463](compiler-warning-level-4-c4463.md) | `overflow; assigning value to bit-field that can only hold values from value to value` | +| [C4473](c4473.md) | `'function' : not enough arguments passed for format string` | | C4474 | `'function' : too many arguments passed for format string` | | C4475 | `'function' : length modifier 'modifier' cannot be used with type field character 'character' in format specifier` | | C4476 | `'function' : unknown type field character 'character' in format specifier` | -| C4477 | `'function' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | +| [C4477](c4477.md) | `'function' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | | C4478 | `'function' : positional and non-positional placeholders cannot be mixed in the same format string` | | C4494 | `'type' : Ignoring __declspec(allocator) because the function return type is not a pointer or reference` | | C4495 | `nonstandard extension '__super' used: replace with explicit base class name` | @@ -385,7 +523,7 @@ These warnings and all warnings in later versions are suppressed by using the co | C4498 | `nonstandard extension used: 'extension'` | | C4499 | `'specialization': an explicit specialization cannot have a storage class (ignored)` | | C4576 | `a parenthesized type followed by an initializer list is a non-standard explicit type conversion syntax` | -| C4577 | `'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc` | +| [C4577](compiler-warning-level-1-c4577.md) | `'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc` | | C4578 | `'abs': conversion from 'type' to 'type', possible loss of data (Did you mean to call 'name' or to #include ?)` | | C4582 | `'type': constructor is not implicitly called` | | C4583 | `'type': destructor is not implicitly called` | @@ -405,7 +543,7 @@ These warnings and all warnings in later versions are suppressed by using the co | C4776 | `'%character' is not allowed in the format string of function 'function'` | | C4777 | `'description' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | | C4778 | `'description' : unterminated format string 'string'` | -| C4838 | `conversion from 'type' to 'type' requires a narrowing conversion` | +| [C4838](compiler-warning-level-1-c4838.md) | `conversion from 'type' to 'type' requires a narrowing conversion` | | C5022 | `'type': multiple move constructors specified` | | C5023 | `'type': multiple move assignment operators specified` | | C5024 | `'declaration': move constructor was implicitly defined as deleted` | @@ -418,24 +556,24 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2013 (compiler version 18.00.21005.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:17`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:17`**. | Warning | Message | |--|--| | C4301 | `'type': overriding virtual function only differs from 'declaration' by const/volatile qualifier` | -| C4316 | `'type': object allocated on the heap may not be aligned number` | +| [C4316](compiler-warning-level-3-c4316.md) | `'type': object allocated on the heap may not be aligned number` | | C4380 | `'type': A default constructor cannot be deprecated` | -| C4388 | `'token': signed/unsigned mismatch` | +| [C4388](c4388.md) | `'token': signed/unsigned mismatch` | | C4423 | `'std::bad_alloc': will be caught by class ('type') on line number` | | C4424 | `catch for 'type' preceded by 'type' on line number; unpredictable behavior may result if 'std::bad_alloc' is thrown` | | C4425 | `A SAL annotation cannot be applied to '...'` | -| C4464 | `relative include path contains '..'` | +| [C4464](compiler-warning-level-4-c4464.md) | `relative include path contains '..'` | | C4575 | `'__vectorcall' incompatible with the '/clr' option: converting to '__stdcall'` | | C4609 | `'type' derives from default interface 'type' on type 'type'. Use a different default interface for 'type', or break the base/derived relationship.` | -| C4754 | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed. Cast 'type' to 'type' (or similar type of number bytes).` | +| [C4754](compiler-warning-level-4-c4754.md) | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed. Cast 'type' to 'type' (or similar type of number bytes).` | | C4755 | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed in an inlined function. Cast 'type' to 'type' (or similar type of number bytes).` | | C4767 | `section name 'name' is longer than 8 characters and will be truncated by the linker` | -| C4770 | `partially validated enum 'name' used as index` | +| [C4770](c4770.md) | `partially validated enum 'name' used as index` | | C4827 | `A public 'ToString' method with 0 parameters should be marked as virtual and override` | | C4882 | `passing functors with non-const call operators to concurrency::parallel_for_each is deprecated` | | C4973 | `'type': marked as deprecated` | @@ -447,7 +585,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2012 (compiler version 17.00.51106.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:16`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:16`**. | Warning | Message | |--|--| @@ -457,9 +595,9 @@ These warnings and all warnings in later versions are suppressed by using the co | C4417 | `an explicit template instantiation cannot have __declspec(code_seg(...)): ignored` | | C4418 | `__declspec(code_seg(...)) ignored on an enum` | | C4419 | `'name' has no effect when applied to private ref class 'type'.` | -| C4435 | `'type': Object layout under /vd2 will change due to virtual base 'type'` | -| C4436 | `dynamic_cast from virtual base 'type' to 'type' in constructor or destructor could fail with partially-constructed object` | -| C4437 | `dynamic_cast from virtual base 'type' to 'type' could fail in some contexts` | +| [C4435](compiler-warning-level-4-c4435.md) | `'type': Object layout under /vd2 will change due to virtual base 'type'` | +| [C4436](compiler-warning-level-1-c4436.md) | `dynamic_cast from virtual base 'type' to 'type' in constructor or destructor could fail with partially-constructed object` | +| [C4437](compiler-warning-level-4-c4437.md) | `dynamic_cast from virtual base 'type' to 'type' could fail in some contexts` | | C4443 | `expected pragma parameter to be '0', '1', or '2'` | | C4446 | `'type': cannot map member 'name' into this type, due to conflict with the type name. The method was renamed to 'name'` | | C4447 | `'main' signature found without threading model. Consider using 'int main(Platform::Array^ args)'.` | @@ -470,17 +608,17 @@ These warnings and all warnings in later versions are suppressed by using the co | C4452 | `'type': public type cannot be at global scope. It must be in a namespace that is a child of the name of the output .winmd file.` | | C4453 | `'type': A '[WebHostHidden]' type should not be used on the published surface of a public type that is not '[WebHostHidden]'` | | C4454 | `'type' is overloaded by more than the number of input parameters without having [DefaultOverload] specified. Picking 'declaration' as the default overload` | -| C4471 | `'name': a forward declaration of an unscoped enumeration must have an underlying type (int assumed)` | +| [C4471](compiler-warning-level-4-c4471.md) | `'name': a forward declaration of an unscoped enumeration must have an underlying type (int assumed)` | | C4472 | `'name' is a native enum: add an access specifier (private/public) to declare a managed/WinRT enum` | | C4492 | `'type': matches base ref class method 'type', but is not marked 'override'` | | C4493 | `delete expression has no effect as the destructor of 'type' does not have 'public' accessibility` | | C4585 | `'type': A WinRT 'public ref class' must either be sealed or derive from an existing unsealed class` | | C4586 | `'type': A public type cannot be declared in a top-level namespace called 'Windows'` | | C4695 | `#pragma execution_character_set: 'argument' is not a supported argument: currently only 'UTF-8' is supported` | -| C4703 | `potentially uninitialized local pointer variable 'name' used` | +| [C4703](compiler-warning-level-4-c4703.md) | `potentially uninitialized local pointer variable 'name' used` | | C4728 | `/Yl- option ignored because PCH reference is required` | | C4745 | `volatile access of 'name' cannot be honored due to its size` | -| C4746 | `volatile access of 'name' is subject to /volatile: setting; consider using __iso_volatile_load/store intrinsic functions` | +| [C4746](compiler-warning-c4746.md) | `volatile access of 'name' is subject to /volatile: setting; consider using __iso_volatile_load/store intrinsic functions` | | C4872 | `floating point division by zero detected when compiling the call graph for the concurrency::parallel_for_each at: 'description'` | | C4880 | `casting from 'type' to 'type': casting away constness from a pointer or reference may result in undefined behavior in an amp restricted function` | | C4881 | `the constructor and/or the destructor will not be invoked for tile_static variable 'type'` | @@ -490,7 +628,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2010 (compiler version 16.00.40219.01) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:15`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:15`**. | Warning | Message | |--|--| @@ -501,350 +639,349 @@ These warnings and all warnings in later versions are suppressed by using the co | C4751 | `/arch AVX flag does not apply to Intel(R) Streaming SIMD Extensions that are within inline ASM` | | C4752 | `found Intel(R) Advanced Vector Extensions; consider using the appropriate /arch AVX flag` | | C4837 | `trigraph detected: '??character' replaced by 'character'` | -| C4986 | `'declaration': exception specification does not match previous declaration` | +| [C4986](compiler-warning-c4986.md) | `'declaration': exception specification does not match previous declaration` | | C4987 | `nonstandard extension used: 'throw (...)'` | ## Warnings introduced in Visual Studio 2008 (compiler version 15.00.21022.08) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:14`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:14`**. | Warning | Message | |--|--| -| C4396 | `'type': the inline specifier cannot be used when a friend declaration refers to a specialization of a function template` | +| [C4396](compiler-warning-level-2-c4396.md) | `'type': the inline specifier cannot be used when a friend declaration refers to a specialization of a function template` | | C4413 | `'declaration': reference member is initialized to a temporary that doesn't persist after the constructor exits` | | C4491 | `'description': has an illegal IDL version format` | -| C4603 | `'name': macro is not defined or definition is different after precompiled header use` | -| C4627 | `'description': skipped when looking for precompiled header use` | -| C4750 | `'description': function with _alloca() inlined into a loop` | -| C4910 | `'type': '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation` | -| C4985 | `'declaration': attributes not present on previous declaration.` | +| [C4603](compiler-warning-level-1-c4603.md) | `'name': macro is not defined or definition is different after precompiled header use` | +| [C4627](compiler-warning-level-1-c4627.md) | `'description': skipped when looking for precompiled header use` | +| [C4750](compiler-warning-level-1-c4750.md) | `'description': function with _alloca() inlined into a loop` | +| [C4910](compiler-warning-level-1-c4910.md) | `'type': '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation` | +| [C4985](compiler-warning-level-4-c4985.md) | `'declaration': attributes not present on previous declaration.` | ## Warnings introduced in Visual Studio 2005 (compiler version 14.00.50727.762) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:13`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:13`**. | Warning | Message | |--|--| -| C4000 | `UNKNOWN WARNING Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information` | -| C4272 | `'type': is marked __declspec(dllimport); must specify native calling convention when importing a function.` | -| C4333 | `'expression': right shift by too large amount, data loss` | -| C4334 | `'expression': result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)` | -| C4335 | `Mac file format detected: please convert the source file to either DOS or UNIX format` | -| C4342 | `behavior change: 'type' called, but a member operator was called in previous versions` | -| C4350 | `behavior change: 'declaration' called instead of 'declaration'` | -| C4357 | `param array argument found in formal argument list for delegate 'declaration' ignored when generating 'type'` | -| C4358 | `'expression': return type of combined delegates is not 'void'; returned value is undefined` | -| C4359 | `'type': Alignment specifier is less than actual alignment (number), and will be ignored.` | +| [C4272](compiler-warning-level-1-c4272.md) | `'type': is marked __declspec(dllimport); must specify native calling convention when importing a function.` | +| [C4333](compiler-warning-level-1-c4333.md) | `'expression': right shift by too large amount, data loss` | +| [C4334](compiler-warning-level-3-c4334.md) | `'expression': result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)` | +| [C4335](compiler-warning-c4335.md) | `Mac file format detected: please convert the source file to either DOS or UNIX format` | +| [C4342](compiler-warning-level-1-c4342.md) | `behavior change: 'type' called, but a member operator was called in previous versions` | +| [C4350](compiler-warning-level-1-c4350.md) | `behavior change: 'declaration' called instead of 'declaration'` | +| [C4357](compiler-warning-level-3-c4357.md) | `param array argument found in formal argument list for delegate 'declaration' ignored when generating 'type'` | +| [C4358](compiler-warning-level-1-c4358.md) | `'expression': return type of combined delegates is not 'void'; returned value is undefined` | +| [C4359](compiler-warning-level-3-c4359.md) | `'type': Alignment specifier is less than actual alignment (number), and will be ignored.` | | C4362 | `'type': alignment greater than 8 bytes is not supported by CLR` | -| C4364 | `#using for assembly 'name' previously seen at description(number) without as_friend attribute; as_friend not applied` | -| C4365 | `'expression': conversion from 'type' to 'type', signed/unsigned mismatch` | -| C4366 | `The result of the unary 'operator' operator may be unaligned` | +| [C4364](compiler-warning-level-1-c4364.md) | `#using for assembly 'name' previously seen at description(number) without as_friend attribute; as_friend not applied` | +| [C4365](compiler-warning-level-4-c4365.md) | `'expression': conversion from 'type' to 'type', signed/unsigned mismatch` | +| [C4366](compiler-warning-level-4-c4366.md) | `The result of the unary 'operator' operator may be unaligned` | | C4367 | `Conversion from 'type' to 'type' may cause datatype misalignment exception` | -| C4368 | `cannot define 'name' as a member of managed 'type': mixed types are not supported` | -| C4369 | `'type': enumerator value 'number' cannot be represented as 'type', value is 'number'` | -| C4374 | `'declaration': interface method will not be implemented by non-virtual method 'declaration'` | -| C4375 | `non-public method 'declaration' does not override 'declaration'` | -| C4376 | `access specifier 'specifier:' is no longer supported: please use 'specifier:' instead` | -| C4377 | `native types are private by default; -d1PrivateNativeTypes is deprecated` | -| C4378 | `Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle` | -| C4379 | `Version version of the common language runtime is not supported by this compiler. Using this version may cause unexpected results` | -| C4381 | `'declaration': interface method will not be implemented by non-public method 'declaration'` | -| C4382 | `throwing 'type': a type with __clrcall destructor or copy constructor can only be caught in /clr:pure module` | -| C4383 | `'type': the meaning of dereferencing a handle can change, when a user-defined 'operator' operator exists; write the operator as a static function to be explicit about the operand` | -| C4384 | `#pragma 'directive' should only be used at global scope` | -| C4393 | `'type': const has no effect on description data member; ignored` | -| C4394 | `'type': per-appdomain symbol should not be marked with __declspec(value)` | -| C4395 | `'type': member function will be invoked on a copy of the initonly data member 'type'` | -| C4397 | `DefaultCharSetAttribute is ignored` | -| C4398 | `'type': per-process global object might not work correctly with multiple appdomains; consider using __declspec(appdomain)` | -| C4399 | `'type': per-process symbol should not be marked with __declspec(value) when compiled with /clr:pure` | -| C4400 | `'type': const/volatile qualifiers on this type are not supported` | -| C4412 | `'declaration': function signature contains type 'type'; C++ objects are unsafe to pass between pure code and mixed or native.` | -| C4429 | `possible incomplete or improperly formed universal-character-name` | -| C4430 | `missing type specifier - int assumed. Note: C++ does not support default-int` | -| C4431 | `missing type specifier - int assumed. Note: C no longer supports default-int` | -| C4434 | `a static constructor must have private accessibility; changing to private access` | -| C4439 | `'type': function definition with a managed type in the signature must have a __clrcall calling convention` | -| C4441 | `calling convention of 'convention' ignored; 'convention' used instead` | -| C4445 | `'declaration': in a managed/WinRT type a virtual method cannot be private` | -| C4460 | `CLR/WinRT operator 'type', has parameter passed by reference. CLR/WinRT operator 'operator' has different semantics from C++ operator 'operator', did you intend to pass by value?` | -| C4461 | `'type': this class has a finalizer '!type' but no destructor '~type'` | -| C4470 | `floating-point control pragmas ignored under /clr` | +| [C4368](compiler-warning-c4368.md) | `cannot define 'name' as a member of managed 'type': mixed types are not supported` | +| [C4369](compiler-warning-level-1-c4369.md) | `'type': enumerator value 'number' cannot be represented as 'type', value is 'number'` | +| [C4374](compiler-warning-level-1-c4374.md) | `'declaration': interface method will not be implemented by non-virtual method 'declaration'` | +| [C4375](compiler-warning-level-1-c4375.md) | `non-public method 'declaration' does not override 'declaration'` | +| [C4376](compiler-warning-level-1-c4376.md) | `access specifier 'specifier:' is no longer supported: please use 'specifier:' instead` | +| [C4377](compiler-warning-level-1-c4377.md) | `native types are private by default; -d1PrivateNativeTypes is deprecated` | +| [C4378](compiler-warning-level-1-c4378.md) | `Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle` | +| [C4379](compiler-warning-level-1-c4379.md) | `Version version of the common language runtime is not supported by this compiler. Using this version may cause unexpected results` | +| [C4381](compiler-warning-level-1-c4381.md) | `'declaration': interface method will not be implemented by non-public method 'declaration'` | +| [C4382](compiler-warning-level-1-c4382.md) | `throwing 'type': a type with __clrcall destructor or copy constructor can only be caught in /clr:pure module` | +| [C4383](compiler-warning-level-1-c4383.md) | `'type': the meaning of dereferencing a handle can change, when a user-defined 'operator' operator exists; write the operator as a static function to be explicit about the operand` | +| [C4384](compiler-warning-level-1-c4384.md) | `#pragma 'directive' should only be used at global scope` | +| [C4393](compiler-warning-level-1-c4393.md) | `'type': const has no effect on description data member; ignored` | +| [C4394](compiler-warning-c4394.md) | `'type': per-appdomain symbol should not be marked with __declspec(value)` | +| [C4395](compiler-warning-level-1-c4395.md) | `'type': member function will be invoked on a copy of the initonly data member 'type'` | +| [C4397](compiler-warning-level-1-c4397.md) | `DefaultCharSetAttribute is ignored` | +| [C4398](compiler-warning-level-3-c4398.md) | `'type': per-process global object might not work correctly with multiple appdomains; consider using __declspec(appdomain)` | +| [C4399](compiler-warning-level-1-c4399.md) | `'type': per-process symbol should not be marked with __declspec(value) when compiled with /clr:pure` | +| [C4400](compiler-warning-level-4-c4400.md) | `'type': const/volatile qualifiers on this type are not supported` | +| [C4412](compiler-warning-level-2-c4412.md) | `'declaration': function signature contains type 'type'; C++ objects are unsafe to pass between pure code and mixed or native.` | +| [C4429](compiler-warning-level-4-c4429.md) | `possible incomplete or improperly formed universal-character-name` | +| [C4430](compiler-warning-c4430.md) | `missing type specifier - int assumed. Note: C++ does not support default-int` | +| [C4431](compiler-warning-level-4-c4431.md) | `missing type specifier - int assumed. Note: C no longer supports default-int` | +| [C4434](compiler-warning-level-4-c4434.md) | `a static constructor must have private accessibility; changing to private access` | +| [C4439](compiler-warning-c4439.md) | `'type': function definition with a managed type in the signature must have a __clrcall calling convention` | +| [C4441](compiler-warning-level-1-c4441.md) | `calling convention of 'convention' ignored; 'convention' used instead` | +| [C4445](compiler-warning-level-1-c4445.md) | `'declaration': in a managed/WinRT type a virtual method cannot be private` | +| [C4460](compiler-warning-level-4-c4460.md) | `CLR/WinRT operator 'type', has parameter passed by reference. CLR/WinRT operator 'operator' has different semantics from C++ operator 'operator', did you intend to pass by value?` | +| [C4461](compiler-warning-level-1-c4461.md) | `'type': this class has a finalizer '!type' but no destructor '~type'` | +| [C4470](compiler-warning-level-1-c4470.md) | `floating-point control pragmas ignored under /clr` | | C4480 | `nonstandard extension used: specifying underlying type for enum 'type'` | -| C4481 | `nonstandard extension used: override specifier 'specifier'` | +| [C4481](compiler-warning-level-4-c4481.md) | `nonstandard extension used: override specifier 'specifier'` | | C4482 | `nonstandard extension used: enum 'type' used in qualified name` | | C4483 | `syntax error: expected C++ keyword` | -| C4484 | `'type': matches base ref class method 'type', but is not marked 'virtual', 'new' or 'override'; 'new' (and not 'virtual') is assumed` | -| C4485 | `'type': matches base ref class method 'type', but is not marked 'new' or 'override'; 'new' (and 'virtual') is assumed` | -| C4486 | `'type': a private virtual method of a ref class or value class should be marked 'sealed'` | -| C4487 | `'type': matches inherited non-virtual method 'type' but is not explicitly marked 'new'` | -| C4488 | `'type': requires 'keyword' keyword to implement the interface method 'type'` | -| C4489 | `'keyword': not allowed on interface method 'name'; override specifiers are only allowed on ref class and value class methods` | -| C4490 | `'keyword': incorrect use of override specifier; 'type' does not match a base ref class method` | -| C4538 | `'type': const/volatile qualifiers on this type are not supported` | -| C4559 | `'type': redefinition; the function gains __declspec(value)` | -| C4565 | `'type': redefinition; the symbol was previously declared with __declspec(value)` | -| C4566 | `character represented by universal-character-name 'character' cannot be represented in the current code page (number)` | +| [C4484](compiler-warning-c4484.md) | `'type': matches base ref class method 'type', but is not marked 'virtual', 'new' or 'override'; 'new' (and not 'virtual') is assumed` | +| [C4485](compiler-warning-c4485.md) | `'type': matches base ref class method 'type', but is not marked 'new' or 'override'; 'new' (and 'virtual') is assumed` | +| [C4486](compiler-warning-level-1-c4486.md) | `'type': a private virtual method of a ref class or value class should be marked 'sealed'` | +| [C4487](compiler-warning-level-4-c4487.md) | `'type': matches inherited non-virtual method 'type' but is not explicitly marked 'new'` | +| [C4488](compiler-warning-level-1-c4488.md) | `'type': requires 'keyword' keyword to implement the interface method 'type'` | +| [C4489](compiler-warning-level-1-c4489.md) | `'keyword': not allowed on interface method 'name'; override specifiers are only allowed on ref class and value class methods` | +| [C4490](compiler-warning-level-1-c4490.md) | `'keyword': incorrect use of override specifier; 'type' does not match a base ref class method` | +| [C4538](compiler-warning-level-3-c4538.md) | `'type': const/volatile qualifiers on this type are not supported` | +| [C4559](compiler-warning-level-4-c4559.md) | `'type': redefinition; the function gains __declspec(value)` | +| [C4565](compiler-warning-level-4-c4565.md) | `'type': redefinition; the symbol was previously declared with __declspec(value)` | +| [C4566](compiler-warning-level-1-c4566.md) | `character represented by universal-character-name 'character' cannot be represented in the current code page (number)` | | C4568 | `'type': no members match the signature of the explicit override` | | C4569 | `'type': no members match the signature of the explicit override` | -| C4570 | `'type': is not explicitly declared as abstract but has abstract functions` | -| C4571 | `Informational: catch(...) semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught` | -| C4572 | `[ParamArray] attribute is deprecated under /clr, use '...' instead` | -| C4580 | `[attribute] is deprecated; instead specify specifiedAttribute as a base class` | -| C4581 | `deprecated behavior: '"name"' replaced with 'name' to process attribute` | -| C4606 | `#pragma warning: 'number' ignored; Code Analysis warnings are not associated with warning levels` | -| C4631 | `MSXML or XPath unavailable, XML document comments will not be processed. description` | -| C4632 | `XML document comment: description - access denied: description` | -| C4633 | `XML document comment description: error: description` | -| C4634 | `XML document comment description: cannot be applied: description` | -| C4635 | `XML document comment description: badly-formed XML: description` | -| C4636 | `XML document comment description: tag requires non-empty 'description' attribute.` | -| C4637 | `XML document comment description: tag discarded. description` | -| C4638 | `XML document comment description: reference to unknown symbol 'description'.` | -| C4639 | `MSXML error, XML document comments will not be processed. description` | -| C4641 | `XML document comment has an ambiguous cross reference:` | -| C4678 | `base class 'declaration' is less accessible than 'name'` | -| C4679 | `'description': could not import member` | -| C4687 | `'type': a sealed abstract class cannot implement an interface 'type'` | -| C4688 | `'name': constraint list contains assembly private type 'declaration'` | -| C4690 | `[ emitidl( pop ) ]: more pops than pushes` | -| C4691 | `'type': type referenced was expected in unreferenced module 'description', type defined in current translation unit used instead` | -| C4692 | `'name': signature of non-private member contains assembly private native type 'declaration'` | -| C4693 | `'type': a sealed abstract class cannot have any instance members 'name'` | -| C4694 | `'type': a sealed abstract class cannot have a base-class 'type'` | +| [C4570](compiler-warning-level-3-c4570.md) | `'type': is not explicitly declared as abstract but has abstract functions` | +| [C4571](compiler-warning-level-4-c4571.md) | `Informational: catch(...) semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught` | +| [C4572](compiler-warning-level-1-c4572.md) | `[ParamArray] attribute is deprecated under /clr, use '...' instead` | +| [C4580](compiler-warning-level-3-c4580.md) | `[attribute] is deprecated; instead specify specifiedAttribute as a base class` | +| [C4581](compiler-warning-level-1-c4581.md) | `deprecated behavior: '"name"' replaced with 'name' to process attribute` | +| [C4606](compiler-warning-level-1-c4606.md) | `#pragma warning: 'number' ignored; Code Analysis warnings are not associated with warning levels` | +| [C4631](compiler-warning-level-1-c4631.md) | `MSXML or XPath unavailable, XML document comments will not be processed. description` | +| [C4632](compiler-warning-level-1-c4632.md) | `XML document comment: description - access denied: description` | +| [C4633](compiler-warning-level-3-c4633.md) | `XML document comment description: error: description` | +| [C4634](compiler-warning-level-4-c4634.md) | `XML document comment description: cannot be applied: description` | +| [C4635](compiler-warning-level-3-c4635.md) | `XML document comment description: badly-formed XML: description` | +| [C4636](compiler-warning-level-3-c4636.md) | `XML document comment description: tag requires non-empty 'description' attribute.` | +| [C4637](compiler-warning-level-3-c4637.md) | `XML document comment description: tag discarded. description` | +| [C4638](compiler-warning-level-3-c4638.md) | `XML document comment description: reference to unknown symbol 'description'.` | +| [C4639](compiler-warning-level-4-c4639.md) | `MSXML error, XML document comments will not be processed. description` | +| [C4641](compiler-warning-level-3-c4641.md) | `XML document comment has an ambiguous cross reference:` | +| [C4678](compiler-warning-level-1-c4678.md) | `base class 'declaration' is less accessible than 'name'` | +| [C4679](compiler-warning-level-1-c4679.md) | `'description': could not import member` | +| [C4687](compiler-warning-c4687.md) | `'type': a sealed abstract class cannot implement an interface 'type'` | +| [C4688](compiler-warning-level-1-c4688.md) | `'name': constraint list contains assembly private type 'declaration'` | +| [C4690](compiler-warning-level-4-c4690.md) | `[ emitidl( pop ) ]: more pops than pushes` | +| [C4691](compiler-warning-level-1-c4691.md) | `'type': type referenced was expected in unreferenced module 'description', type defined in current translation unit used instead` | +| [C4692](compiler-warning-level-1-c4692.md) | `'name': signature of non-private member contains assembly private native type 'declaration'` | +| [C4693](compiler-warning-c4693.md) | `'type': a sealed abstract class cannot have any instance members 'name'` | +| [C4694](compiler-warning-c4694.md) | `'type': a sealed abstract class cannot have a base-class 'type'` | | C4720 | `in-line assembler reports: 'description'` | | C4721 | `'description': not available as an intrinsic` | -| C4722 | `'description': destructor never returns, potential memory leak` | +| [C4722](compiler-warning-level-1-c4722.md) | `'description': destructor never returns, potential memory leak` | | C4726 | `ARM arch4/4T supports only ' or ' with immediate value` | -| C4727 | `PCH named name with same timestamp found in name and name. Using first PCH.` | -| C4729 | `function too big for flow graph based warnings` | -| C4730 | `'description': mixing _m64 and floating point expressions may result in incorrect code` | -| C4731 | `'description': frame pointer register 'register' modified by inline assembly code` | +| [C4727](compiler-warning-level-1-c4727.md) | `PCH named name with same timestamp found in name and name. Using first PCH.` | +| [C4729](compiler-warning-level-1-c4729.md) | `function too big for flow graph based warnings` | +| [C4730](compiler-warning-level-1-c4730.md) | `'description': mixing _m64 and floating point expressions may result in incorrect code` | +| [C4731](compiler-warning-level-1-c4731.md) | `'description': frame pointer register 'register' modified by inline assembly code` | | C4732 | `intrinsic 'intrinsic' is not supported in this architecture` | -| C4733 | `Inline asm assigning to 'FS:0': handler not registered as safe handler` | +| [C4733](compiler-warning-level-1-c4733.md) | `Inline asm assigning to 'FS:0': handler not registered as safe handler` | | C4734 | `More than 64k line numbers in a COFF debug info section; stop emitting COFF debug line numbers for module 'module'` | -| C4738 | `storing 32-bit float result in memory, possible loss of performance` | -| C4739 | `reference to variable 'variable' exceeds its storage space` | -| C4740 | `flow in or out of inline asm code suppresses global optimization` | -| C4742 | `'variable' has different alignment in 'location' and 'location': number and number` | -| C4743 | `'name' has different size in 'location' and 'location': number and number bytes` | -| C4744 | `'name' has different type in 'location' and 'location': 'type' and 'type'` | -| C4747 | `Calling managed 'type': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint` | +| [C4738](compiler-warning-level-3-c4738.md) | `storing 32-bit float result in memory, possible loss of performance` | +| [C4739](compiler-warning-level-1-c4739.md) | `reference to variable 'variable' exceeds its storage space` | +| [C4740](compiler-warning-level-4-c4740.md) | `flow in or out of inline asm code suppresses global optimization` | +| [C4742](compiler-warning-level-1-c4742.md) | `'variable' has different alignment in 'location' and 'location': number and number` | +| [C4743](compiler-warning-level-1-c4743.md) | `'name' has different size in 'location' and 'location': number and number bytes` | +| [C4744](compiler-warning-level-1-c4744.md) | `'name' has different type in 'location' and 'location': 'type' and 'type'` | +| [C4747](compiler-warning-level-1-c4747.md) | `Calling managed 'type': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint` | | C4761 | `integral size mismatch in argument; conversion supplied` | -| C4764 | `Cannot align catch objects to greater than 16 bytes` | -| C4788 | `'identifier': identifier was truncated to 'number' characters` | -| C4789 | `buffer 'name' of size number bytes will be overrun; number bytes will be written starting at offset number` | +| [C4764](compiler-warning-level-4-c4764.md) | `Cannot align catch objects to greater than 16 bytes` | +| [C4788](compiler-warning-level-1-c4788.md) | `'identifier': identifier was truncated to 'number' characters` | +| [C4789](compiler-warning-level-1-c4789.md) | `buffer 'name' of size number bytes will be overrun; number bytes will be written starting at offset number` | | C4801 | `Return by reference is not verifiable: description` | -| C4819 | `The file contains a character that cannot be represented in the current code page (number). Save the file in Unicode format to prevent data loss` | +| [C4819](compiler-warning-level-1-c4819.md) | `The file contains a character that cannot be represented in the current code page (number). Save the file in Unicode format to prevent data loss` | | C4826 | `Conversion from 'type' to 'type' is sign-extended. This may cause unexpected runtime behavior.` | -| C4829 | `Possibly incorrect parameters to function main. Consider 'int main(Platform::Array^ argv)'` | -| C4835 | `'type': the initializer for exported data will not be run until managed code is first executed in the host assembly` | -| C4867 | `'type': non-standard syntax; use '&' to create a pointer to member` | -| C4936 | `this __declspec is supported only when compiled with /clr or /clr:pure` | -| C4937 | `'name' and 'name' are indistinguishable as arguments to 'option'` | -| C4938 | `'type': Floating point reduction variable may cause inconsistent results under /fp:strict or #pragma fenv_access` | -| C4939 | `#pragma vtordisp is deprecated and will be removed in a future release of Visual C++` | -| C4947 | `'type': marked as obsolete` | -| C4949 | `pragmas 'managed' and 'unmanaged' are meaningful only when compiled with '/clr[:option]'` | -| C4950 | `'type': marked as obsolete` | +| [C4829](compiler-warning-level-1-c4829.md) | `Possibly incorrect parameters to function main. Consider 'int main(Platform::Array^ argv)'` | +| [C4835](compiler-warning-level-1-c4835.md) | `'type': the initializer for exported data will not be run until managed code is first executed in the host assembly` | +| [C4867](compiler-warning-c4867.md) | `'type': non-standard syntax; use '&' to create a pointer to member` | +| [C4936](compiler-warning-c4936.md) | `this __declspec is supported only when compiled with /clr or /clr:pure` | +| [C4937](compiler-warning-level-4-c4937.md) | `'name' and 'name' are indistinguishable as arguments to 'option'` | +| [C4938](compiler-warning-level-4-c4938.md) | `'type': Floating point reduction variable may cause inconsistent results under /fp:strict or #pragma fenv_access` | +| [C4939](compiler-warning-level-1-c4939.md) | `#pragma vtordisp is deprecated and will be removed in a future release of Visual C++` | +| [C4947](compiler-warning-level-1-c4947.md) | `'type': marked as obsolete` | +| [C4949](compiler-warning-level-1-and-level-4-c4949.md) | `pragmas 'managed' and 'unmanaged' are meaningful only when compiled with '/clr[:option]'` | +| [C4950](compiler-warning-c4950.md) | `'type': marked as obsolete` | | C4955 | `'description': import ignored; already imported from 'source'` | -| C4956 | `'type': this type is not verifiable` | -| C4957 | `'expression': explicit cast from 'type' to 'type' is not verifiable` | -| C4958 | `'expression': pointer arithmetic is not verifiable` | -| C4959 | `cannot define unmanaged class 'type' in /clr:safe because accessing its members yields unverifiable code` | -| C4960 | `'description' is too big to be profiled` | -| C4961 | `No profile data was merged into 'location', profile-guided optimizations disabled` | -| C4962 | `'description': Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent` | +| [C4956](compiler-warning-c4956.md) | `'type': this type is not verifiable` | +| [C4957](compiler-warning-c4957.md) | `'expression': explicit cast from 'type' to 'type' is not verifiable` | +| [C4958](compiler-warning-c4958.md) | `'expression': pointer arithmetic is not verifiable` | +| [C4959](compiler-warning-c4959.md) | `cannot define unmanaged class 'type' in /clr:safe because accessing its members yields unverifiable code` | +| [C4960](compiler-warning-level-4-c4960.md) | `'description' is too big to be profiled` | +| [C4961](compiler-warning-c4961.md) | `No profile data was merged into 'location', profile-guided optimizations disabled` | +| [C4962](compiler-warning-c4962.md) | `'description': Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent` | | C4963 | `'description': no profile data found; different compiler options were used in instrumented build` | -| C4964 | `No optimization options were specified; profile info will not be collected` | -| C4965 | `implicit box of integer 0; use nullptr or explicit cast` | +| [C4964](compiler-warning-level-1-c4964.md) | `No optimization options were specified; profile info will not be collected` | +| [C4965](compiler-warning-level-1-c4965.md) | `implicit box of integer 0; use nullptr or explicit cast` | | C4970 | `delegate constructor: target object ignored since 'declaration' is static` | | C4971 | `Argument order: , for delegate constructor is deprecated, use , ` | -| C4972 | `Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable` | +| [C4972](compiler-warning-c4972.md) | `Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable` | ## Warnings introduced in Visual Studio 2003 (compiler version 13.10.3077) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:13.00.9466`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:13.00.9466`**. | Warning | Message | |--|--| -| C4343 | `#pragma optimize(description,off) overrides /Og option` | -| C4344 | `behavior change: use of explicit template arguments results in call to 'declaration'` | -| C4346 | `'type': dependent name is not a type` | -| C4348 | `'declaration': redefinition of default parameter: parameter number` | -| C4356 | `'type': static data member cannot be initialized via derived class` | -| C4408 | `anonymous struct did not declare any data members` | -| C4544 | `'declaration': default template argument ignored on this template declaration` | -| C4545 | `expression before comma evaluates to a function which is missing an argument list` | -| C4546 | `function call before comma missing argument list` | -| C4547 | `'expression': operator before comma has no effect; expected operator with side-effect` | -| C4548 | `expression before comma has no effect; expected expression with side-effect` | -| C4549 | `'expression': operator before comma has no effect; did you intend 'expression'?` | -| C4628 | `digraphs not supported with -Ze. Character sequence 'sequence' not interpreted as alternate token for 'token'` | -| C4629 | `digraph used, character sequence 'sequence' interpreted as token 'token' (insert a space between the two characters if this is not what you intended)` | +| [C4343](compiler-warning-level-4-c4343.md) | `#pragma optimize(description,off) overrides /Og option` | +| [C4344](compiler-warning-level-1-c4344.md) | `behavior change: use of explicit template arguments results in call to 'declaration'` | +| [C4346](compiler-warning-level-1-c4346.md) | `'type': dependent name is not a type` | +| [C4348](compiler-warning-level-1-c4348.md) | `'declaration': redefinition of default parameter: parameter number` | +| [C4356](compiler-warning-level-2-c4356.md) | `'type': static data member cannot be initialized via derived class` | +| [C4408](compiler-warning-level-4-c4408.md) | `anonymous struct did not declare any data members` | +| [C4544](compiler-warning-level-1-c4544.md) | `'declaration': default template argument ignored on this template declaration` | +| [C4545](compiler-warning-level-1-c4545.md) | `expression before comma evaluates to a function which is missing an argument list` | +| [C4546](compiler-warning-level-1-c4546.md) | `function call before comma missing argument list` | +| [C4547](compiler-warning-level-1-c4547.md) | `'expression': operator before comma has no effect; expected operator with side-effect` | +| [C4548](compiler-warning-level-1-c4548.md) | `expression before comma has no effect; expected expression with side-effect` | +| [C4549](compiler-warning-level-1-c4549.md) | `'expression': operator before comma has no effect; did you intend 'expression'?` | +| [C4628](compiler-warning-level-1-c4628.md) | `digraphs not supported with -Ze. Character sequence 'sequence' not interpreted as alternate token for 'token'` | +| [C4629](compiler-warning-level-4-c4629.md) | `digraph used, character sequence 'sequence' interpreted as token 'token' (insert a space between the two characters if this is not what you intended)` | | C4671 | `'description': the copy constructor is inaccessible` | | C4676 | `'description': the destructor is inaccessible` | -| C4677 | `'name': signature of non-private member contains assembly private type 'declaration'` | -| C4686 | `'type': possible change in behavior, change in UDT return calling convention` | -| C4812 | `obsolete declaration style: please use 'type::name' instead` | -| C4813 | `'type': a friend function of a local class must have been previously declared` | -| C4821 | `Unable to determine Unicode encoding type, please save the file with signature (BOM)` | -| C4822 | `'type': local class member function does not have a body` | -| C4823 | `'type': uses pinning pointers but unwind semantics are not enabled. Consider using /EHa` | -| C4913 | `user defined binary operator ',' exists but no overload could convert all operands, default built-in binary operator ',' used` | -| C4948 | `return type of 'declaration' does not match the last parameter type of the corresponding setter` | -| C4951 | `'description' has been edited since profile data was collected, function profile data not used` | -| C4952 | `'description': no profile data found in program database 'description'` | -| C4953 | `Inlinee 'description' has been edited since profile data was collected, profile data not used` | +| [C4677](compiler-warning-level-1-c4677.md) | `'name': signature of non-private member contains assembly private type 'declaration'` | +| [C4686](compiler-warning-level-3-c4686.md) | `'type': possible change in behavior, change in UDT return calling convention` | +| [C4812](compiler-warning-level-1-c4812.md) | `obsolete declaration style: please use 'type::name' instead` | +| [C4813](compiler-warning-level-1-c4813.md) | `'type': a friend function of a local class must have been previously declared` | +| [C4821](compiler-warning-level-1-c4821.md) | `Unable to determine Unicode encoding type, please save the file with signature (BOM)` | +| [C4822](compiler-warning-level-1-c4822.md) | `'type': local class member function does not have a body` | +| [C4823](compiler-warning-level-3-c4823.md) | `'type': uses pinning pointers but unwind semantics are not enabled. Consider using /EHa` | +| [C4913](compiler-warning-level-4-c4913.md) | `user defined binary operator ',' exists but no overload could convert all operands, default built-in binary operator ',' used` | +| [C4948](compiler-warning-level-2-c4948.md) | `return type of 'declaration' does not match the last parameter type of the corresponding setter` | +| [C4951](compiler-warning-level-1-c4951.md) | `'description' has been edited since profile data was collected, function profile data not used` | +| [C4952](compiler-warning-level-1-c4952.md) | `'description': no profile data found in program database 'description'` | +| [C4953](compiler-warning-level-1-c4953.md) | `Inlinee 'description' has been edited since profile data was collected, profile data not used` | | C4954 | `'description': not profiled (contains __int64 switch expression)` | ## Warnings introduced in Visual Studio 2002 (compiler version 13.00.9466) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:12`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:12`**. | Warning | Message | |--|--| -| C4096 | `'type': interface is not a COM interface; will not be emitted to IDL` | -| C4097 | `expected pragma parameter to be 'restore' or 'off'` | -| C4165 | `'HRESULT' is being converted to 'bool'; are you sure this is what you want?` | -| C4183 | `'name': missing return type; assumed to be a member function returning 'int'` | +| [C4096](compiler-warning-level-1-c4096.md) | `'type': interface is not a COM interface; will not be emitted to IDL` | +| [C4097](compiler-warning-level-1-c4097.md) | `expected pragma parameter to be 'restore' or 'off'` | +| [C4165](compiler-warning-level-1-c4165.md) | `'HRESULT' is being converted to 'bool'; are you sure this is what you want?` | +| [C4183](compiler-warning-level-1-c4183.md) | `'name': missing return type; assumed to be a member function returning 'int'` | | C4199 | `description` | -| C4255 | `'name': no function prototype given: converting '()' to '(void)'` | -| C4256 | `'declaration': constructor for class with virtual bases has '...'; calls may not be compatible with older versions of Visual C++` | -| C4258 | `'name': definition from the for loop is ignored; the definition from the enclosing scope is used` | -| C4263 | `'declaration': member function does not override any base class virtual member function` | -| C4264 | `'declaration': no override available for virtual member function from base 'class'; function is hidden` | -| C4265 | `'type': class has virtual functions, but destructor is not virtual instances of this class may not be destructed correctly` | -| C4266 | `'declaration': no override available for virtual member function from base 'class'; function is hidden` | -| C4267 | `'expression': conversion from 'size_t' to 'type', possible loss of data` | -| C4274 | `#ident ignored; see documentation for #pragma comment(exestr, 'string')` | +| [C4255](compiler-warning-level-4-c4255.md) | `'name': no function prototype given: converting '()' to '(void)'` | +| [C4256](compiler-warning-level-4-c4256.md) | `'declaration': constructor for class with virtual bases has '...'; calls may not be compatible with older versions of Visual C++` | +| [C4258](compiler-warning-level-1-c4258.md) | `'name': definition from the for loop is ignored; the definition from the enclosing scope is used` | +| [C4263](compiler-warning-level-4-c4263.md) | `'declaration': member function does not override any base class virtual member function` | +| [C4264](compiler-warning-level-1-c4264.md) | `'declaration': no override available for virtual member function from base 'class'; function is hidden` | +| [C4265](compiler-warning-level-3-c4265.md) | `'type': class has virtual functions, but destructor is not virtual instances of this class may not be destructed correctly` | +| [C4266](compiler-warning-level-4-c4266.md) | `'declaration': no override available for virtual member function from base 'class'; function is hidden` | +| [C4267](compiler-warning-level-3-c4267.md) | `'expression': conversion from 'size_t' to 'type', possible loss of data` | +| [C4274](compiler-warning-level-1-c4274.md) | `#ident ignored; see documentation for #pragma comment(exestr, 'string')` | | C4277 | `imported item 'type::name' exists as both data member and function member; data member ignored` | -| C4278 | `'name': identifier in type library 'description' is already a macro; use the 'rename' qualifier` | +| [C4278](compiler-warning-level-3-c4278.md) | `'name': identifier in type library 'description' is already a macro; use the 'rename' qualifier` | | C4279 | `'name': identifier in type library 'description' is a keyword; use the 'rename' qualifier` | -| C4287 | `'expression': unsigned/negative constant mismatch` | -| C4288 | `nonstandard extension used: 'name': loop control variable declared in the for-loop is used outside the for-loop scope; it conflicts with the declaration in the outer scope` | -| C4289 | `nonstandard extension used: 'name': loop control variable declared in the for-loop is used outside the for-loop scope` | -| C4293 | `'expression': shift count negative or too big, undefined behavior` | -| C4295 | `'type': array is too small to include a terminating null character` | -| C4296 | `'expression': expression is always value` | -| C4297 | `'type': function assumed not to throw an exception but does` | +| [C4287](compiler-warning-level-3-c4287.md) | `'expression': unsigned/negative constant mismatch` | +| [C4288](compiler-warning-level-1-c4288.md) | `nonstandard extension used: 'name': loop control variable declared in the for-loop is used outside the for-loop scope; it conflicts with the declaration in the outer scope` | +| [C4289](compiler-warning-level-4-c4289.md) | `nonstandard extension used: 'name': loop control variable declared in the for-loop is used outside the for-loop scope` | +| [C4293](compiler-warning-level-1-c4293.md) | `'expression': shift count negative or too big, undefined behavior` | +| [C4295](compiler-warning-level-4-c4295.md) | `'type': array is too small to include a terminating null character` | +| [C4296](compiler-warning-level-4-c4296.md) | `'expression': expression is always value` | +| [C4297](compiler-warning-level-1-c4297.md) | `'type': function assumed not to throw an exception but does` | | C4298 | `'name': identifier in type library 'description' is already a macro; renaming to '__name'` | | C4299 | `'name': identifier in type library 'description' is a keyword; renaming to '__name'` | -| C4302 | `'expression': truncation from 'type' to 'type'` | +| [C4302](compiler-warning-level-2-c4302.md) | `'expression': truncation from 'type' to 'type'` | | C4303 | `conversion from 'type' to 'type' is deprecated, use static_cast, __try_cast or dynamic_cast` | | C4314 | `expected pragma parameter to be '32' or '64'` | | C4315 | `'type': 'this' pointer for member 'type' may not be aligned number as expected by the constructor` | | C4318 | `passing constant zero as the length to memset` | -| C4319 | `'expression': zero extending 'type' to 'type' of greater size` | +| [C4319](compiler-warning-level-1-c4319.md) | `'expression': zero extending 'type' to 'type' of greater size` | | C4321 | `automatically generating an IID for interface 'type'` | | C4322 | `automatically generating a CLSID for class 'type'` | | C4323 | `re-using registered CLSID for class 'type'` | -| C4324 | `'type': structure was padded due to alignment specifier` | -| C4325 | `attributes for standard section 'description' ignored` | -| C4326 | `return type of 'name' should be 'type' instead of 'type'` | +| [C4324](compiler-warning-level-4-c4324.md) | `'type': structure was padded due to alignment specifier` | +| [C4325](compiler-warning-level-1-c4325.md) | `attributes for standard section 'description' ignored` | +| [C4326](compiler-warning-level-1-c4326.md) | `return type of 'name' should be 'type' instead of 'type'` | | C4327 | `'expression': indirection alignment of LHS (number) is greater than RHS (number)` | | C4328 | `'description': indirection alignment of formal parameter number (number) is greater than the actual argument alignment (number)` | -| C4329 | `alignment specifier is ignored on enum` | -| C4336 | `import cross-referenced type library 'library' before importing 'description'` | -| C4337 | `cross-referenced type library 'library' in 'description' is being automatically imported` | +| [C4329](compiler-warning-level-1-c4329.md) | `alignment specifier is ignored on enum` | +| [C4336](compiler-warning-level-4-c4336.md) | `import cross-referenced type library 'library' before importing 'description'` | +| [C4337](compiler-warning-level-4-c4337.md) | `cross-referenced type library 'library' in 'description' is being automatically imported` | | C4338 | `#pragma description: standard section 'section' is used` | -| C4339 | `'type': use of undefined type detected in CLR/WinRT meta-data - use of this type may lead to a runtime exception` | -| C4353 | `nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead` | +| [C4339](compiler-warning-level-4-c4339.md) | `'type': use of undefined type detected in CLR/WinRT meta-data - use of this type may lead to a runtime exception` | +| [C4353](compiler-warning-level-1-c4353.md) | `nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead` | | C4370 | `'declaration': layout of class has changed from a previous version of the compiler due to better packing` | -| C4371 | `'declaration': layout of class may have changed from a previous version of the compiler due to better packing of member 'member'` | -| C4373 | `'type': virtual function overrides 'declaration', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers` | +| [C4371](c4371.md) | `'declaration': layout of class may have changed from a previous version of the compiler due to better packing of member 'member'` | +| [C4373](compiler-warning-level-3-c4373.md) | `'type': virtual function overrides 'declaration', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers` | | C4387 | `'description': was considered` | -| C4389 | `'expression': signed/unsigned mismatch` | -| C4391 | `'declaration': incorrect return type for intrinsic function, expected 'type'` | -| C4392 | `'declaration': incorrect number of arguments for intrinsic function, expected 'number' arguments` | -| C4407 | `cast between different pointer to member representations, compiler may generate incorrect code` | -| C4420 | `'name': operator not available, using 'name' instead; run-time checking may be compromised` | -| C4440 | `calling convention redefinition from 'description' to 'description' ignored` | +| [C4389](compiler-warning-level-4-c4389.md) | `'expression': signed/unsigned mismatch` | +| [C4391](compiler-warning-level-1-c4391.md) | `'declaration': incorrect return type for intrinsic function, expected 'type'` | +| [C4392](compiler-warning-level-1-c4392.md) | `'declaration': incorrect number of arguments for intrinsic function, expected 'number' arguments` | +| [C4407](compiler-warning-level-1-c4407.md) | `cast between different pointer to member representations, compiler may generate incorrect code` | +| [C4420](compiler-warning-level-1-c4420.md) | `'name': operator not available, using 'name' instead; run-time checking may be compromised` | +| [C4440](compiler-warning-level-1-c4440.md) | `calling convention redefinition from 'description' to 'description' ignored` | | C4442 | `embedded null terminator in __annotation argument. Value will be truncated.` | | C4444 | `'name': top level '__unaligned' is not implemented in this context` | -| C4526 | `'type': static member function cannot override virtual function 'declaration' override ignored, virtual function will be hidden` | +| [C4526](compiler-warning-level-1-c4526.md) | `'type': static member function cannot override virtual function 'declaration' override ignored, virtual function will be hidden` | | C4531 | `C++ exception handling not available on Windows CE. Use Structured Exception Handling` | -| C4532 | `'description': jump out of finally block has undefined behavior during termination handling` | -| C4533 | `initialization of 'declaration' is skipped by 'goto declaration'` | -| C4534 | `'declaration' will not be a default constructor for class 'type' due to the default argument` | -| C4535 | `calling _set_se_translator() requires /EHa` | -| C4536 | `'description': type-name exceeds meta-data limit of 'number' characters` | -| C4537 | `'declaration': '.' applied to non-UDT type` | +| [C4532](compiler-warning-level-1-c4532.md) | `'description': jump out of finally block has undefined behavior during termination handling` | +| [C4533](compiler-warning-level-1-c4533.md) | `initialization of 'declaration' is skipped by 'goto declaration'` | +| [C4534](compiler-warning-level-3-c4534.md) | `'declaration' will not be a default constructor for class 'type' due to the default argument` | +| [C4535](compiler-warning-level-3-c4535.md) | `calling _set_se_translator() requires /EHa` | +| [C4536](compiler-warning-level-4-c4536.md) | `'description': type-name exceeds meta-data limit of 'number' characters` | +| [C4537](compiler-warning-level-1-c4537.md) | `'declaration': '.' applied to non-UDT type` | | C4542 | `Skipping generation of merged injected text file, cannot write type file: 'filename': error` | -| C4543 | `Injected text suppressed by attribute 'no_injected_text'` | -| C4555 | `expression has no effect; expected expression with side-effect` | -| C4557 | `'__assume' contains effect 'effect'` | -| C4558 | `value of operand 'number' is out of range 'number - number'` | -| C4561 | `'__fastcall' incompatible with the '/clr' option: converting to '__stdcall'` | +| [C4543](compiler-warning-level-3-c4543.md) | `Injected text suppressed by attribute 'no_injected_text'` | +| [C4555](compiler-warning-level-1-c4555.md) | `expression has no effect; expected expression with side-effect` | +| [C4557](compiler-warning-level-3-c4557.md) | `'__assume' contains effect 'effect'` | +| [C4558](compiler-warning-level-1-c4558.md) | `value of operand 'number' is out of range 'number - number'` | +| [C4561](compiler-warning-level-1-c4561.md) | `'__fastcall' incompatible with the '/clr' option: converting to '__stdcall'` | | C4562 | `fully prototyped functions are required with the '/clr' option: converting '()' to '(void)'` | -| C4564 | `method 'name' of class 'type' defines unsupported default parameter 'parameter'` | -| C4584 | `'type': base-class 'declaration' is already a base-class of 'declaration'` | -| C4608 | `Initializing multiple members of union: 'type' and 'type'` | -| C4619 | `#pragma warning: there is no warning number 'number'` | -| C4623 | `'type': default constructor was implicitly defined as deleted` | -| C4624 | `'type': destructor was implicitly defined as deleted` | -| C4625 | `'type': copy constructor was implicitly defined as deleted` | -| C4626 | `'type': assignment operator was implicitly defined as deleted` | -| C4645 | `function declared with 'noreturn' has a return statement` | -| C4646 | `function declared with 'noreturn' has non-void return type` | -| C4659 | `#pragma 'description': use of reserved segment 'name' has undefined behavior, use #pragma comment(linker, ...)` | -| C4667 | `'declaration': no function template defined that matches forced instantiation` | -| C4668 | `'name' is not defined as a preprocessor macro, replacing with '0' for 'value'` | -| C4669 | `'expression': unsafe conversion: 'type' is a managed/WinRT type object` | -| C4674 | `'name' should be declared 'static' and have exactly one parameter` | -| C4680 | `'type': coclass does not specify a default interface` | -| C4681 | `'type': coclass does not specify a default interface that is an event source` | -| C4682 | `'type': no directional parameter attribute specified, defaulting to [in]` | -| C4683 | `'declaration': event source has an 'out'-parameter; exercise caution when hooking multiple event handlers` | -| C4684 | `'description': WARNING!! attribute may cause invalid code generation: use with caution` | -| C4685 | `expecting '> >' found '>>' when parsing template parameters` | -| C4700 | `uninitialized local variable 'name' used` | -| C4701 | `potentially uninitialized local variable 'name' used` | -| C4702 | `unreachable code` | -| C4711 | `function 'name' selected for automatic inline expansion` | -| C4714 | `function 'declaration' marked as __forceinline not inlined` | -| C4715 | `'function': not all control paths return a value` | -| C4716 | `'function': must return a value` | -| C4717 | `'function': recursive on all control paths, function will cause runtime stack overflow` | -| C4718 | `'function': recursive call has no side effects, deleting` | +| [C4564](compiler-warning-level-4-c4564.md) | `method 'name' of class 'type' defines unsupported default parameter 'parameter'` | +| [C4584](compiler-warning-level-1-c4584.md) | `'type': base-class 'declaration' is already a base-class of 'declaration'` | +| [C4608](compiler-warning-level-3-c4608.md) | `Initializing multiple members of union: 'type' and 'type'` | +| [C4619](compiler-warning-level-3-c4619.md) | `#pragma warning: there is no warning number 'number'` | +| [C4623](compiler-warning-level-4-c4623.md) | `'type': default constructor was implicitly defined as deleted` | +| [C4624](compiler-warning-level-1-c4624.md) | `'type': destructor was implicitly defined as deleted` | +| [C4625](compiler-warning-level-4-c4625.md) | `'type': copy constructor was implicitly defined as deleted` | +| [C4626](compiler-warning-level-4-c4626.md) | `'type': assignment operator was implicitly defined as deleted` | +| [C4645](compiler-warning-level-3-c4645.md) | `function declared with 'noreturn' has a return statement` | +| [C4646](compiler-warning-level-3-c4646.md) | `function declared with 'noreturn' has non-void return type` | +| [C4659](compiler-warning-level-1-c4659.md) | `#pragma 'description': use of reserved segment 'name' has undefined behavior, use #pragma comment(linker, ...)` | +| [C4667](compiler-warning-level-1-c4667.md) | `'declaration': no function template defined that matches forced instantiation` | +| [C4668](compiler-warning-level-4-c4668.md) | `'name' is not defined as a preprocessor macro, replacing with '0' for 'value'` | +| [C4669](compiler-warning-level-1-c4669.md) | `'expression': unsafe conversion: 'type' is a managed/WinRT type object` | +| [C4674](compiler-warning-level-1-c4674.md) | `'name' should be declared 'static' and have exactly one parameter` | +| [C4680](compiler-warning-level-4-c4680.md) | `'type': coclass does not specify a default interface` | +| [C4681](compiler-warning-level-4-c4681.md) | `'type': coclass does not specify a default interface that is an event source` | +| [C4682](compiler-warning-level-4-c4682.md) | `'type': no directional parameter attribute specified, defaulting to [in]` | +| [C4683](compiler-warning-level-1-c4683.md) | `'declaration': event source has an 'out'-parameter; exercise caution when hooking multiple event handlers` | +| [C4684](compiler-warning-level-1-c4684.md) | `'description': WARNING!! attribute may cause invalid code generation: use with caution` | +| [C4685](compiler-warning-level-1-c4685.md) | `expecting '> >' found '>>' when parsing template parameters` | +| [C4700](compiler-warning-level-1-and-level-4-c4700.md) | `uninitialized local variable 'name' used` | +| [C4701](compiler-warning-level-4-c4701.md) | `potentially uninitialized local variable 'name' used` | +| [C4702](compiler-warning-level-4-c4702.md) | `unreachable code` | +| [C4711](compiler-warning-level-1-c4711.md) | `function 'name' selected for automatic inline expansion` | +| [C4714](compiler-warning-level-4-c4714.md) | `function 'declaration' marked as __forceinline not inlined` | +| [C4715](compiler-warning-level-1-c4715.md) | `'function': not all control paths return a value` | +| [C4716](compiler-warning-level-1-c4716.md) | `'function': must return a value` | +| [C4717](compiler-warning-level-1-c4717.md) | `'function': recursive on all control paths, function will cause runtime stack overflow` | +| [C4718](compiler-warning-level-4-c4718.md) | `'function': recursive call has no side effects, deleting` | | C4719 | `Double constant found when Qfast specified - use 'f' as a suffix to indicate single precision` | -| C4723 | `potential divide by 0` | -| C4724 | `potential mod by 0` | -| C4725 | `instruction may be inaccurate on some Pentiums` | +| [C4723](compiler-warning-level-3-c4723.md) | `potential divide by 0` | +| [C4724](compiler-warning-level-3-c4724.md) | `potential mod by 0` | +| [C4725](compiler-warning-level-4-c4725.md) | `instruction may be inaccurate on some Pentiums` | | C4757 | `subscript is a large unsigned value, did you intend a negative constant?` | -| C4772 | `#import referenced a type from a missing type library; 'description' used as a placeholder` | -| C4792 | `function 'function' declared using sysimport and referenced from native code; import library required to link` | -| C4794 | `segment of thread local storage variable 'name' changed from 'segment' to 'segment'` | +| [C4772](compiler-warning-level-1-c4772.md) | `#import referenced a type from a missing type library; 'description' used as a placeholder` | +| [C4792](compiler-warning-level-3-c4792.md) | `function 'function' declared using sysimport and referenced from native code; import library required to link` | +| [C4794](compiler-warning-level-1-c4794.md) | `segment of thread local storage variable 'name' changed from 'segment' to 'segment'` | | C4798 | `native code generated for p-code function 'name' with exception handler or unwind semantics` | -| C4799 | `function 'name' has no EMMS instruction` | -| C4803 | `'declaration': the raise method has a different storage class from that of the event, 'declaration'` | -| C4810 | `value of pragma pack(show) == number` | -| C4811 | `value of pragma conform(forScope, show) == value` | -| C4820 | `'type': 'number' bytes padding added after type 'type'` | -| C4905 | `wide string literal cast to 'type'` | -| C4906 | `string literal cast to 'type'` | -| C4912 | `'attribute': attribute has undefined behavior on a nested UDT` | +| [C4799](compiler-warning-level-1-c4799.md) | `function 'function' has no EMMS instruction` | +| [C4803](compiler-warning-level-1-c4803.md) | `'declaration': the raise method has a different storage class from that of the event, 'declaration'` | +| [C4810](compiler-warning-level-1-c4810.md) | `value of pragma pack(show) == number` | +| [C4811](compiler-warning-level-1-c4811.md) | `value of pragma conform(forScope, show) == value` | +| [C4820](compiler-warning-level-4-c4820.md) | `'type': 'number' bytes padding added after type 'type'` | +| [C4905](compiler-warning-level-1-c4905.md) | `wide string literal cast to 'type'` | +| [C4906](compiler-warning-level-1-c4906.md) | `string literal cast to 'type'` | +| [C4912](compiler-warning-level-1-c4912.md) | `'attribute': attribute has undefined behavior on a nested UDT` | | C4916 | `in order to have a dispid, 'type': must be introduced by an interface` | -| C4917 | `'type': a GUID can only be associated with a class, interface or namespace` | -| C4918 | `'character': invalid character in pragma optimization list` | -| C4920 | `enum name member name=number already seen in enum name as name=number` | +| [C4917](compiler-warning-level-1-c4917.md) | `'type': a GUID can only be associated with a class, interface or namespace` | +| [C4918](compiler-warning-level-4-c4918.md) | `'character': invalid character in pragma optimization list` | +| [C4920](compiler-warning-level-1-c4920.md) | `enum name member name=number already seen in enum name as name=number` | | C4921 | `'name': attribute value 'value' should not be multiply specified` | -| C4925 | `'declaration': dispinterface method cannot be called from script` | -| C4926 | `'declaration': symbol is already defined: attributes ignored` | -| C4927 | `illegal conversion; more than one user-defined conversion has been implicitly applied` | -| C4928 | `illegal copy-initialization; more than one user-defined conversion has been implicitly applied` | -| C4929 | `'description': typelibrary contains a union; ignoring the 'embedded_idl' qualifier` | -| C4930 | `'declaration': prototyped function not called (was a variable definition intended?)` | -| C4931 | `we are assuming the type library was built for number-bit pointers` | -| C4932 | `__identifier(description) and __identifier(description) are indistinguishable` | +| [C4925](compiler-warning-level-1-c4925.md) | `'declaration': dispinterface method cannot be called from script` | +| [C4926](compiler-warning-level-1-c4926.md) | `'declaration': symbol is already defined: attributes ignored` | +| [C4927](compiler-warning-level-1-c4927.md) | `illegal conversion; more than one user-defined conversion has been implicitly applied` | +| [C4928](compiler-warning-level-1-c4928.md) | `illegal copy-initialization; more than one user-defined conversion has been implicitly applied` | +| [C4929](compiler-warning-level-1-c4929.md) | `'description': typelibrary contains a union; ignoring the 'embedded_idl' qualifier` | +| [C4930](compiler-warning-level-1-c4930.md) | `'declaration': prototyped function not called (was a variable definition intended?)` | +| [C4931](compiler-warning-level-4-c4931.md) | `we are assuming the type library was built for number-bit pointers` | +| [C4932](compiler-warning-level-4-c4932.md) | `__identifier(description) and __identifier(description) are indistinguishable` | | C4934 | `'__delegate(multicast)' is deprecated, use '__delegate' instead` | -| C4935 | `assembly access specifier modified from 'description'` | -| C4944 | `'name': cannot import symbol from 'source': as 'declaration' already exists in the current scope` | -| C4945 | `'name': cannot import symbol from 'source': as 'declaration' has already been imported from another assembly 'source'` | -| C4946 | `reinterpret_cast used between related classes: 'declaration' and 'declaration'` | -| C4995 | `'name': name was marked as #pragma deprecated` | -| C4996 | `'deprecated declaration': deprecation message (or "was declared deprecated")` | -| C4997 | `'type': coclass does not implement a COM interface or pseudo-interface` | +| [C4935](compiler-warning-level-1-c4935.md) | `assembly access specifier modified from 'description'` | +| [C4944](compiler-warning-level-1-c4944.md) | `'name': cannot import symbol from 'source': as 'declaration' already exists in the current scope` | +| [C4945](compiler-warning-level-1-c4945.md) | `'name': cannot import symbol from 'source': as 'declaration' has already been imported from another assembly 'source'` | +| [C4946](compiler-warning-level-1-c4946.md) | `reinterpret_cast used between related classes: 'declaration' and 'declaration'` | +| [C4995](compiler-warning-level-3-c4995.md) | `'name': name was marked as #pragma deprecated` | +| [C4996](compiler-warning-level-3-c4996.md) | `'deprecated declaration': deprecation message (or "was declared deprecated")` | +| [C4997](compiler-warning-level-1-c4997.md) | `'type': coclass does not implement a COM interface or pseudo-interface` | | C4998 | `EXPECTATION FAILED: description(number)` | ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4000-c5999.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4000-c5999.md index 36315ad4e8..08f6b5cf34 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4000-c5999.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4000-c5999.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: Compiler warnings C4000 - C5999" -title: "Compiler warnings C4000 - C5999" -ms.date: "04/22/2019" +title: "Microsoft C/C++ compiler (MSVC) warnings C4000 through C5399" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings." +ms.date: "04/19/2024" --- -# Compiler warnings C4000 - C5999 +# Microsoft C/C++ compiler warnings C4000 through C5399 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the Microsoft C/C++ compiler. +This article links to descriptions of Microsoft C/C++ compiler warnings C4000-C5399. ## In this section -[Compiler warnings C4000 through C4199](../compiler-warnings/compiler-warnings-c4000-through-c4199.md) \ -[Compiler warnings C4200 through C4399](../compiler-warnings/compiler-warnings-c4200-through-c4399.md) \ -[Compiler warnings C4400 through C4599](../compiler-warnings/compiler-warnings-c4400-through-c4599.md) \ -[Compiler warnings C4600 through C4799](../compiler-warnings/compiler-warnings-c4600-through-c4799.md) \ -[Compiler warnings C4800 through C5999](../compiler-warnings/compiler-warnings-c4800-through-c4999.md) +[Compiler warnings C4000 through C4199](../compiler-warnings/compiler-warnings-c4000-through-c4199.md)\ +[Compiler warnings C4200 through C4399](../compiler-warnings/compiler-warnings-c4200-through-c4399.md)\ +[Compiler warnings C4400 through C4599](../compiler-warnings/compiler-warnings-c4400-through-c4599.md)\ +[Compiler warnings C4600 through C4799](../compiler-warnings/compiler-warnings-c4600-through-c4799.md)\ +[Compiler warnings C4800 through C4999](../compiler-warnings/compiler-warnings-c4800-through-c4999.md)\ +[Compiler warnings C5000 through C5199](../compiler-warnings/compiler-warnings-c5000-through-c5199.md)\ +[Compiler warnings C5200 through C5399](../compiler-warnings/compiler-warnings-c5200-through-c5399.md) ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199.md index 90331c8309..675357263c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199.md @@ -1,169 +1,168 @@ --- -description: "Learn more about: Compiler warnings C4000 Through C4199" -title: "Compiler warnings C4000 Through C4199" +title: "Microsoft C/C++ compiler (MSVC) warnings C4000 through C4199" +description: "Table of Microsoft C/C++ compiler (MSVC) warning messages C4000 through C4199" ms.date: "04/21/2019" -f1_keywords: ["C4000", "C4035", "C4060", "C4063", "C4064", "C4065", "C4069", "C4123", "C4137", "C4181", "C4188", "C4193", "C4194", "C4195", "C4196", "C4199"] -ms.assetid: 426f495a-43af-4906-ad2b-6e5822c09965 +f1_keywords: ["C4023", "C4035", "C4051", "C4060", "C4063", "C4064", "C4065", "C4069", "C4123", "C4137", "C4181", "C4188", "C4193", "C4194", "C4195", "C4196", "C4199"] +helpviewer_keywords: ["C4023", "C4035", "C4051", "C4060", "C4063", "C4064", "C4065", "C4069", "C4123", "C4137", "C4181", "C4188", "C4193", "C4194", "C4195", "C4196", "C4199"] --- -# Compiler warnings C4000 Through C4199 +# Microsoft C/C++ compiler warnings C4000 through C4199 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4000 through C4199. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Warning messages |Warning|Message| |-------------|-------------| -|Compiler warning C4000|UNKNOWN WARNING

Please choose the Technical Support command on the Visual C++

Help menu, or open the Technical Support help file for more information| -|[Compiler warning (level 4) C4001](../../error-messages/compiler-warnings/compiler-warning-level-4-c4001.md)|nonstandard extension 'single line comment' was used| -|[Compiler warning (level 1) C4002](compiler-warning-level-1-c4002.md)|too many actual parameters for macro 'identifier'| -|[Compiler warning (level 1) C4003](../../error-messages/compiler-warnings/compiler-warning-level-1-c4003.md)|not enough actual parameters for macro 'identifier'| -|[Compiler warning (level 1) C4005](../../error-messages/compiler-warnings/compiler-warning-level-1-c4005.md)|'identifier': macro redefinition| -|[Compiler warning (level 1) C4006](compiler-warning-level-1-c4006.md)|#undef expected an identifier| -|[Compiler warning (level 2) C4007](../../error-messages/compiler-warnings/compiler-warning-level-2-c4007.md)|'function': must be 'attribute'| -|[Compiler warning (level 3) C4008](compiler-warning-levels-2-and-3-c4008.md)|'function': 'attribute' attribute ignored| -|[Compiler warning (level 1) C4010](../../error-messages/compiler-warnings/compiler-warning-level-1-c4010.md)|single-line comment contains line-continuation character| -|[Compiler warning (level 3) C4013](../../error-messages/compiler-warnings/compiler-warning-level-3-c4013.md)|'function' undefined; assuming extern returning int| -|[Compiler warning (level 1) C4015](../../error-messages/compiler-warnings/compiler-warning-level-1-c4015.md)|'identifer': type of bit field must be integral| -|[Compiler warning (level 3) C4018](../../error-messages/compiler-warnings/compiler-warning-level-3-c4018.md)|'expression': signed/unsigned mismatch| +|[Compiler warning (level 4, no longer emitted) C4001](compiler-warning-level-4-c4001.md)|nonstandard extension 'single line comment' was used| +|[Compiler warning (level 1, error) C4002](compiler-warning-level-1-c4002.md)|too many arguments for function-like macro invocation '*identifier*'| +|[Compiler warning (level 1, error) C4003](compiler-warning-level-1-c4003.md)|not enough arguments for function-like macro invocation '*identifier*'| +|[Compiler warning (level 1) C4005](compiler-warning-level-1-c4005.md)|'*identifier*': macro redefinition| +|[Compiler warning (level 1) C4006](compiler-warning-level-1-c4006.md)|`#undef` expected an identifier| +|[Compiler warning (level 3) C4007](compiler-warning-level-2-c4007.md)|'*function*': must be '*attribute*'| +|[Compiler warning (level 3) C4008](compiler-warning-levels-2-and-3-c4008.md)|'*function*': '*attribute*' attribute ignored| +|[Compiler warning (level 1) C4010](compiler-warning-level-1-c4010.md)|single-line comment contains line-continuation character| +|[Compiler warning (level 3) C4013](compiler-warning-level-3-c4013.md)|'*function*' undefined; assuming extern returning int| +|[Compiler warning (level 1) C4015](compiler-warning-level-1-c4015.md)|'*identifier*': type of bit field must be integral| +|[Compiler warning (level 3) C4018](compiler-warning-level-3-c4018.md)|'*expression*': signed/unsigned mismatch| |[Compiler warning (level 4) C4019](compiler-warning-level-4-c4019.md)|empty statement at global scope| -|[Compiler warning (level 1) C4020](../../error-messages/compiler-warnings/compiler-warning-level-1-c4020.md)|'function': too many actual parameters| -|[Compiler warning (level 1) C4022](../../error-messages/compiler-warnings/compiler-warning-level-1-c4022.md)|'function': pointer mismatch for actual parameter 'parameter number'| -|Compiler warning (level 1) C4023|'function': based pointer passed to unprototyped function: parameter 'parameter_number'| -|[Compiler warning (level 1) C4024](../../error-messages/compiler-warnings/compiler-warning-level-1-c4024.md)|'function': different types for formal and actual parameter 'parameter_number'| -|[Compiler warning (level 1) C4025](compiler-warning-level-1-c4025.md)|'function': based pointer passed to function with variable arguments: parameter 'parameter_number'| +|[Compiler warning (level 1) C4020](compiler-warning-level-1-c4020.md)|'function': too many actual parameters| +|[Compiler warning (level 1) C4022](compiler-warning-level-1-c4022.md)|'*function*': pointer mismatch for actual parameter *parameter_number*| +|Compiler warning (level 1) C4023|'*function*': based pointer passed to unprototyped function: parameter *parameter_number*| +|[Compiler warning (level 1) C4024](compiler-warning-level-1-c4024.md)|'*function*': different types for formal and actual parameter *parameter_number*| +|[Compiler warning (level 1) C4025](compiler-warning-level-1-c4025.md)|'*function*': based pointer passed to function with variable arguments: parameter *parameter_number*| |[Compiler warning (level 1) C4026](compiler-warning-level-1-c4026.md)|function declared with formal parameter list| |[Compiler warning (level 1) C4027](compiler-warning-level-1-c4027.md)|function declared without formal parameter list| -|[Compiler warning (level 1) C4028](../../error-messages/compiler-warnings/compiler-warning-level-1-c4028.md)|formal parameter 'parameter_number' different from declaration| -|[Compiler warning (level 1) C4029](../../error-messages/compiler-warnings/compiler-warning-level-1-c4029.md)|declared formal parameter list different from definition| +|[Compiler warning (level 1) C4028](compiler-warning-level-1-c4028.md)|formal parameter *parameter_number* different from declaration| +|[Compiler warning (level 1) C4029](compiler-warning-level-1-c4029.md)|declared formal parameter list different from definition| |[Compiler warning (level 1) C4030](compiler-warning-level-1-c4030.md)|first formal parameter list longer than the second list| -|[Compiler warning (level 1) C4031](../../error-messages/compiler-warnings/compiler-warning-level-1-c4031.md)|second formal parameter list longer than the first list| -|[Compiler warning (level 4) C4032](../../error-messages/compiler-warnings/compiler-warning-level-4-c4032.md)|formal parameter 'parameter_number' has different type when promoted| -|[Compiler warning (level 1) C4033](compiler-warning-level-1-c4033.md)|'function' must return a value| -|[Compiler warning (level 1) C4034](../../error-messages/compiler-warnings/compiler-warning-level-1-c4034.md)|sizeof returns 0| -|Compiler warning (level 3) C4035|'function': no return value| +|[Compiler warning (level 1) C4031](compiler-warning-level-1-c4031.md)|second formal parameter list longer than the first list| +|[Compiler warning (level 4) C4032](compiler-warning-level-4-c4032.md)|formal parameter *parameter_number* has different type when promoted| +|[Compiler warning (level 1) C4033](compiler-warning-level-1-c4033.md)|'*function*' must return a value| +|[Compiler warning (level 1) C4034](compiler-warning-level-1-c4034.md)|sizeof returns 0| +|Compiler warning (level 3) C4035|'*function*': no return value| |[Compiler warning (level 1) C4036](compiler-warning-level-1-c4036.md)|unnamed 'type' as actual parameter| -|[Compiler warning (level 1) C4038](compiler-warning-level-1-c4038.md)|'modifier': illegal class modifier| +|[Compiler warning (level 1) C4038](compiler-warning-level-1-c4038.md)|'*modifier*': illegal class modifier| |[Compiler warning (level 1) C4041](compiler-warning-level-1-c4041.md)|compiler limit: terminating browser output| -|[Compiler warning (level 1) C4042](../../error-messages/compiler-warnings/compiler-warning-level-1-c4042.md)|'identifier': has bad storage class| -|[Compiler warning (level 1) C4045](compiler-warning-level-1-c4045.md)|'array': array bounds overflow| -|[Compiler warning (level 1) C4047](../../error-messages/compiler-warnings/compiler-warning-level-1-c4047.md)|'operator': 'identifier1' differs in levels of indirection from 'identifier2'| -|[Compiler warning (level 1) C4048](../../error-messages/compiler-warnings/compiler-warning-level-1-c4048.md)|different array subscripts: 'identifier1' and 'identifier2'| -|[Compiler warning (level 1) C4049](../../error-messages/compiler-warnings/compiler-warning-level-1-c4049.md)|compiler limit: terminating line number emission| +|[Compiler warning (level 1) C4042](compiler-warning-level-1-c4042.md)|'*identifier*': has bad storage class| +|[Compiler warning (level 1) C4045](compiler-warning-level-1-c4045.md)|'*array*': array bounds overflow| +|[Compiler warning (level 1) C4047](compiler-warning-level-1-c4047.md)|'*operator*': '*identifier1*' differs in levels of indirection from '*identifier2*'| +|[Compiler warning (level 1) C4048](compiler-warning-level-1-c4048.md)|different array subscripts: '*identifier1*' and '*identifier2*'| +|[Compiler warning (level 1) C4049](compiler-warning-level-1-c4049.md)|compiler limit: terminating line number emission| |Compiler warning (level 1) C4051|type conversion; possible loss of data| -|[Compiler warning (level 4) C4052](compiler-warning-level-1-c4052.md)|function declarations different; one contains variable arguments| -|[Compiler warning (level 4) C4053](compiler-warning-level-4-c4053.md)|one void operand for '?:'| +|[Compiler warning (level 1 and level 4) C4052](compiler-warning-level-1-c4052.md)|function declarations different; one contains variable arguments| +|[Compiler warning (level 4) C4053](compiler-warning-level-4-c4053.md)|one void operand for '`?:`'| |[Compiler warning (level 1) C4055](compiler-warning-level-1-c4055.md)|'conversion' : from data pointer '*type1*' to function pointer '*type2*'| -|[Compiler warning (level 2) C4056](../../error-messages/compiler-warnings/compiler-warning-level-2-c4056.md)|overflow in floating-point constant arithmetic| -|[Compiler warning (level 4) C4057](compiler-warning-level-4-c4057.md)|'operator': 'identifier1' differs in indirection to slightly different base types from 'identifier2'| -|Compiler warning C4060|switch statement contains no 'case' or 'default' labels| -|[Compiler warning (level 4) C4061](../../error-messages/compiler-warnings/compiler-warning-level-4-c4061.md)|enumerator 'identifier' in switch of enum 'enumeration' is not explicitly handled by a case label| -|[Compiler warning (level 4) C4062](../../error-messages/compiler-warnings/compiler-warning-level-4-c4062.md)|enumerator 'identifier' in switch of enum 'enumeration' is not handled| -|Compiler warning C4063|case 'identifier' is not a valid value for switch of enum 'enumeration'| -|Compiler warning C4064|switch of incomplete enum 'enumeration'| -|Compiler warning C4065|switch statement contains 'default' but no 'case' labels| +|[Compiler warning (level 2) C4056](compiler-warning-level-2-c4056.md)|overflow in floating-point constant arithmetic| +|[Compiler warning (level 4) C4057](compiler-warning-level-4-c4057.md)|'*operator*': '*identifier1*' differs in indirection to slightly different base types from '*identifier2*'| +|Compiler warning (level 3, off) C4060|switch statement contains no 'case' or 'default' labels| +|[Compiler warning (level 4, off) C4061](compiler-warning-level-4-c4061.md)|enumerator '*identifier*' in switch of `enum` '*enumeration*' is not explicitly handled by a `case` label| +|[Compiler warning (level 4, off) C4062](compiler-warning-level-4-c4062.md)|enumerator '*identifier*' in switch of `enum` '*enumeration*' is not handled| +|Compiler warning (level 4) C4063|case '*identifier*' is not a valid value for switch of `enum` '*enumeration*'| +|Compiler warning (level 4) C4064|switch of incomplete `enum` '*enumeration*'| +|Compiler warning (level 3, off) C4065|switch statement contains '`default`' but no '`case`' labels| |[Compiler warning (level 3) C4066](compiler-warning-level-3-c4066.md)|characters beyond first in wide-character constant ignored| -|[Compiler warning (level 1) C4067](../../error-messages/compiler-warnings/compiler-warning-level-1-c4067.md)|unexpected tokens following preprocessor directive - expected a newline| -|[Compiler warning (level 1) C4068](compiler-warning-level-1-c4068.md)|unknown pragma| +|[Compiler warning (level 1) C4067](compiler-warning-level-1-c4067.md)|unexpected tokens following preprocessor directive - expected a newline| +|[Compiler warning (level 1) C4068](compiler-warning-level-1-c4068.md)|unknown pragma '*identifier*'| |Compiler warning C4069|long double is the same precision as double| -|[Compiler warning (level 3) C4073](../../error-messages/compiler-warnings/compiler-warning-level-3-c4073.md)|initializers put in library initialization area| -|[Compiler warning (level 1) C4074](../../error-messages/compiler-warnings/compiler-warning-level-1-c4074.md)|initializers put in compiler reserved initialization area| +|[Compiler warning (level 3) C4073](compiler-warning-level-3-c4073.md)|initializers put in library initialization area| +|[Compiler warning (level 1) C4074](compiler-warning-level-1-c4074.md)|initializers put in compiler reserved initialization area| |[Compiler warning (level 1) C4075](compiler-warning-level-1-c4075.md)|initializers put in unrecognized initialization area| -|[Compiler warning (level 1) C4076](compiler-warning-level-1-c4076.md)|'type_modifier': can not be used with type 'typename'| +|[Compiler warning (level 1) C4076](compiler-warning-level-1-c4076.md)|'*type_modifier*': cannot be used with type '*typename*'| |[Compiler warning (level 1) C4077](compiler-warning-level-1-c4077.md)|unknown check_stack option| -|[Compiler warning (level 1) C4079](../../error-messages/compiler-warnings/compiler-warning-level-1-c4079.md)|unexpected token 'token'| -|[Compiler warning (level 1) C4080](compiler-warning-level-1-c4080.md)|expected identifier for segment name; found 'symbol'| -|[Compiler warning (level 1) C4081](compiler-warning-level-1-c4081.md)|expected 'token1'; found 'token2'| -|[Compiler warning (level 1) C4083](../../error-messages/compiler-warnings/compiler-warning-level-1-c4083.md)|expected 'token'; found identifier 'identifier'| -|[Compiler warning (level 1) C4085](compiler-warning-level-1-c4085.md)|expected pragma parameter to be 'on' or 'off'| +|[Compiler warning (level 1) C4079](compiler-warning-level-1-c4079.md)|unexpected token '*token*'| +|[Compiler warning (level 1) C4080](compiler-warning-level-1-c4080.md)|expected identifier for segment name; found '*symbol*'| +|[Compiler warning (level 1) C4081](compiler-warning-level-1-c4081.md)|expected '*token1*'; found '*token2*'| +|[Compiler warning (level 1) C4083](compiler-warning-level-1-c4083.md)|expected '*token*'; found identifier '*identifier*'| +|[Compiler warning (level 1) C4085](compiler-warning-level-1-c4085.md)|expected pragma parameter to be '`on`' or '`off`'| |[Compiler warning (level 1) C4086](compiler-warning-level-1-c4086.md)|expected pragma parameter to be '1', '2', '4', '8', or '16'| -|[Compiler warning (level 1) C4087](compiler-warning-level-1-c4087.md)|'function': declared with 'void' parameter list| -|[Compiler warning (level 1) C4088](../../error-messages/compiler-warnings/compiler-warning-level-1-c4088.md)|'function': pointer mismatch in actual parameter 'parameter_number', formal parameter 'parameter_number'| -|[Compiler warning (level 1) C4089](../../error-messages/compiler-warnings/compiler-warning-level-1-c4089.md)|'function': different types in actual parameter 'parameter_number', formal parameter 'parameter_number'| -|[Compiler warning (level 1) C4090](../../error-messages/compiler-warnings/compiler-warning-level-1-c4090.md)|'operation': different 'modifier' qualifiers| -|[Compiler warning (level 1) C4091](../../error-messages/compiler-warnings/compiler-warning-level-1-c4091.md)|keyword': ignored on left of 'type' when no variable is declared| -|[Compiler warning (level 4) C4092](../../error-messages/compiler-warnings/compiler-warning-level-4-c4092.md)|sizeof returns 'unsigned long'| -|[Compiler warning (level 2) C4094](../../error-messages/compiler-warnings/compiler-warning-level-2-c4094.md)|untagged 'token' declared no symbols| -|[Compiler warning (level 1) C4096](../../error-messages/compiler-warnings/compiler-warning-level-1-c4096.md)|'identifier': interface is not a COM interface; will not be emitted to IDL| -|[Compiler warning (level 1) C4097](compiler-warning-level-1-c4097.md)|expected pragma parameter to be 'restore' or 'off'| -|[Compiler warning (level 1) C4098](../../error-messages/compiler-warnings/compiler-warning-level-1-c4098.md)|'function': 'void' function returning a value| -|[Compiler warning (level 2) C4099](../../error-messages/compiler-warnings/compiler-warning-level-2-c4099.md)|'identifier': type name first seen using 'object_type1' now seen using 'object_type2'| -|[Compiler warning (level 4) C4100](../../error-messages/compiler-warnings/compiler-warning-level-4-c4100.md)|'identifier': unreferenced formal parameter| -|[Compiler warning (level 3) C4101](../../error-messages/compiler-warnings/compiler-warning-level-3-c4101.md)|'identifier': unreferenced local variable| -|[Compiler warning (level 3) C4102](compiler-warning-level-3-c4102.md)|'label': unreferenced label| -|[Compiler warning (level 1) C4103](../../error-messages/compiler-warnings/compiler-warning-level-1-c4103.md)|'filename': alignment changed after including header, may be due to missing #pragma pack(pop)| -|[Compiler warning (level 1) C4109](compiler-warning-level-1-c4109.md)|unexpected identifier 'identifier'| -|[Compiler warning (level 1) C4112](compiler-warning-levels-1-and-4-c4112.md)|#line requires an integer between 1 and 'line_count'| -|[Compiler warning (level 1) C4113](../../error-messages/compiler-warnings/compiler-warning-level-1-c4113.md)|'identifier1' differs in parameter lists from 'identifier2'| -|[Compiler warning (level 1) C4114](../../error-messages/compiler-warnings/compiler-warning-level-1-c4114.md)|same type qualifier used more than once| -|[Compiler warning (level 1 and level 4) C4115](compiler-warning-levels-1-and-4-c4115.md)|'type': named type definition in parentheses| -|[Compiler warning (level 1) C4116](../../error-messages/compiler-warnings/compiler-warning-level-1-c4116.md)|unnamed type definition in parentheses| -|[Compiler warning (level 1) C4117](compiler-warning-level-1-c4117.md)|macro name 'name' is reserved, 'command' ignored| -|[Compiler warning (level 1) C4119](compiler-warning-level-1-c4119.md)|different bases 'base1' and 'base2' specified| +|[Compiler warning (level 1) C4087](compiler-warning-level-1-c4087.md)|'function': declared with '`void`' parameter list| +|[Compiler warning (level 1) C4088](compiler-warning-level-1-c4088.md)|'*function*': pointer mismatch in actual parameter *parameter_number*, formal parameter *parameter_number*| +|[Compiler warning (level 1) C4089](compiler-warning-level-1-c4089.md)|'*function*': different types in actual parameter *parameter_number*, formal parameter *parameter_number*| +|[Compiler warning (level 1) C4090](compiler-warning-level-1-c4090.md)|'*operation*': different '*modifier*' qualifiers| +|[Compiler warning (level 1 and level 2) C4091](compiler-warning-level-1-c4091.md)|'*keyword*': ignored on left of '*type*' when no variable is declared| +|[Compiler warning (level 4) C4092](compiler-warning-level-4-c4092.md)|sizeof returns 'unsigned long'| +|[Compiler warning (level 2) C4094](compiler-warning-level-2-c4094.md)|untagged '*token*' declared no symbols| +|[Compiler warning (level 1) C4096](compiler-warning-level-1-c4096.md)|'*identifier*': interface is not a COM interface; will not be emitted to IDL| +|[Compiler warning (level 1) C4097](compiler-warning-level-1-c4097.md)|expected pragma parameter to be '`restore`' or '`off`'| +|[Compiler warning (level 1) C4098](compiler-warning-level-1-c4098.md)|'*function*': '`void`' function returning a value| +|[Compiler warning (level 2) C4099](compiler-warning-level-2-c4099.md)|'*identifier*': type name first seen using '*object_type1*' now seen using '*object_type2*'| +|[Compiler warning (level 4) C4100](compiler-warning-level-4-c4100.md)|'*identifier*': unreferenced parameter| +|[Compiler warning (level 3 and level 4) C4101](compiler-warning-level-3-c4101.md)|'*identifier*': unreferenced local variable| +|[Compiler warning (level 3) C4102](compiler-warning-level-3-c4102.md)|'*label*': unreferenced label| +|[Compiler warning (level 1) C4103](compiler-warning-level-1-c4103.md)|alignment changed after including header, may be due to missing `#pragma pack(pop)`| +|[Compiler warning (level 1) C4109](compiler-warning-level-1-c4109.md)|unexpected identifier '*identifier*'| +|[Compiler warning (level 1 and level 4) C4112](compiler-warning-levels-1-and-4-c4112.md)|`#line` requires an integer between 1 and *line_count*| +|[Compiler warning (level 1) C4113](compiler-warning-level-1-c4113.md)|'*identifier1*' differs in parameter lists from '*identifier2*'| +|[Compiler warning (level 1) C4114](compiler-warning-level-1-c4114.md)|same type qualifier used more than once| +|[Compiler warning (level 1 and level 4) C4115](compiler-warning-levels-1-and-4-c4115.md)|'*type*': named type definition in parentheses| +|[Compiler warning (level 1) C4116](compiler-warning-level-1-c4116.md)|unnamed type definition in parentheses| +|[Compiler warning (level 1) C4117](compiler-warning-level-1-c4117.md)|macro name '*name*' is reserved, '*command*' ignored| +|[Compiler warning (level 1) C4119](compiler-warning-level-1-c4119.md)|different bases '*base1*' and '*base2*' specified| |[Compiler warning (level 1) C4120](compiler-warning-level-1-c4120.md)|based/unbased mismatch| -|[Compiler warning (level 4) C4121](../../error-messages/compiler-warnings/compiler-warning-level-4-c4121.md)|'symbol': alignment of a member was sensitive to packing| -|[Compiler warning (level 1) C4122](compiler-warning-level-1-c4122.md)|'function': alloc_text applicable only to functions with C linkage| +|[Compiler warning (level 4) C4121](compiler-warning-level-4-c4121.md)|'*symbol*': alignment of a member was sensitive to packing| +|[Compiler warning (level 1) C4122](compiler-warning-level-1-c4122.md)|'*function*': alloc_text applicable only to functions with C linkage| |Compiler warning (level 1) C4123|different base expressions specified| -|[Compiler warning (level 1) C4124](../../error-messages/compiler-warnings/compiler-warning-level-1-c4124.md)|__fastcall with stack checking is inefficient| +|[Compiler warning (level 1) C4124](compiler-warning-level-1-c4124.md)|__fastcall with stack checking is inefficient| |[Compiler warning (level 4) C4125](compiler-warning-level-4-c4125.md)|decimal digit terminates octal escape sequence| -|[Compiler warning (level 4) C4127](../../error-messages/compiler-warnings/compiler-warning-level-4-c4127.md)|conditional expression is constant| -|[Compiler warning (level 1) C4129](../../error-messages/compiler-warnings/compiler-warning-level-1-c4129.md)|'character': unrecognized character escape sequence| -|[Compiler warning (level 4) C4130](compiler-warning-level-4-c4130.md)|'operator': logical operation on address of string constant| -|[Compiler warning (level 4) C4131](compiler-warning-level-4-c4131.md)|'function': uses old-style declarator| -|[Compiler warning (level 4) C4132](compiler-warning-level-4-c4132.md)|'object': const object should be initialized| -|[Compiler warning (level 3) C4133](../../error-messages/compiler-warnings/compiler-warning-level-3-c4133.md)|'expression': incompatible types - from 'type1' to 'type2'| +|[Compiler warning (level 4) C4127](compiler-warning-level-4-c4127.md)|conditional expression is constant| +|[Compiler warning (level 1) C4129](compiler-warning-level-1-c4129.md)|'*character*': unrecognized character escape sequence| +|[Compiler warning (level 4) C4130](compiler-warning-level-4-c4130.md)|'*operator*': logical operation on address of string constant| +|[Compiler warning (level 4) C4131](compiler-warning-level-4-c4131.md)|'*function*': uses old-style declarator| +|[Compiler warning (level 4) C4132](compiler-warning-level-4-c4132.md)|'*object*': `const` object should be initialized| +|[Compiler warning (level 1 and level 3) C4133](compiler-warning-level-3-c4133.md)|'*expression*': incompatible types - from '*type1*' to '*type2*'| |Compiler warning C4137|'function': no return value from floating-point function| -|[Compiler warning (level 1) C4138](compiler-warning-level-1-c4138.md)|'*/' found outside of comment| -|[Compiler warning (level 1) C4141](compiler-warning-level-1-c4141.md)|'modifier': used more than once| -|[Compiler warning (level 1) C4142](../../error-messages/compiler-warnings/compiler-warning-level-1-c4142.md)|benign redefinition of type| -|[Compiler warning (level 1) C4143](compiler-warning-level-1-c4143.md)|pragma 'same_seg' not supported; use __based allocation| -|[Compiler warning (level 1) C4144](../../error-messages/compiler-warnings/compiler-warning-level-1-c4144.md)|'expression': relational expression as switch expression| -|[Compiler warning (level 1) C4145](compiler-warning-level-1-c4145.md)|'expression1': relational expression as switch expression; possible confusion with 'expression2'| -|[Compiler warning (level 2) C4146](../../error-messages/compiler-warnings/compiler-warning-level-2-c4146.md)|unary minus operator applied to unsigned type, result still unsigned| -|[Compiler warning (level 2) C4150](../../error-messages/compiler-warnings/compiler-warning-level-2-c4150.md)|deletion of pointer to incomplete type 'type'; no destructor called| +|[Compiler warning (level 1) C4138](compiler-warning-level-1-c4138.md)|'`*/`' found outside of comment| +|[Compiler warning (level 1, error) C4141](compiler-warning-level-1-c4141.md)|'*modifier*': used more than once| +|[Compiler warning (level 1) C4142](compiler-warning-level-1-c4142.md)|'*identifier*': benign redefinition of type| +|[Compiler warning (level 1) C4143](compiler-warning-level-1-c4143.md)|`pragma` 'same_seg' not supported; use `__based` allocation| +|[Compiler warning (level 1) C4144](compiler-warning-level-1-c4144.md)|'*expression*': relational expression as switch expression| +|[Compiler warning (level 1) C4145](compiler-warning-level-1-c4145.md)|'*expression1*': relational expression as switch expression; possible confusion with '*expression2*'| +|[Compiler warning (level 2) C4146](compiler-warning-level-2-c4146.md)|unary minus operator applied to unsigned type, result still unsigned| +|[Compiler warning (level 2) C4150](compiler-warning-level-2-c4150.md)|deletion of pointer to incomplete type '*type*'; no destructor called| |[Compiler warning (level 4) C4152](compiler-warning-level-4-c4152.md)|nonstandard extension, function/data pointer conversion in expression| |[Compiler warning (level 1) C4153](compiler-warning-level-1-c4153.md)|function/data pointer conversion in expression| -|[Compiler warning (level 1) C4154](../../error-messages/compiler-warnings/compiler-warning-level-1-c4154.md)|deletion of an array expression; conversion to pointer supplied| +|[Compiler warning (level 1) C4154](compiler-warning-level-1-c4154.md)|deletion of an array expression; conversion to pointer supplied| |[Compiler warning (level 1) C4155](compiler-warning-level-1-c4155.md)|deletion of an array expression without using the array form of 'delete'| -|[Compiler warning (level 2) C4156](../../error-messages/compiler-warnings/compiler-warning-level-2-c4156.md)|deletion of an array expression without using the array form of 'delete'; array form substituted| -|[Compiler warning (level 1) C4157](../../error-messages/compiler-warnings/compiler-warning-level-1-c4157.md)|pragma was ignored by C compiler| -|[Compiler warning (level 1) C4158](compiler-warning-level-1-c4158.md)|assuming #pragma pointers_to_members(full_generality, 'inheritance_type')| -|[Compiler warning (level 3) C4159](../../error-messages/compiler-warnings/compiler-warning-level-3-c4159.md)|#pragma 'pragma'(pop,...): has popped previously pushed identifier 'identifier'| -|[Compiler warning (level 1) C4160](compiler-warning-level-1-c4160.md)|#pragma 'pragma'(pop,...): did not find previously pushed identifier 'identifier'| -|[Compiler warning (level 3) C4161](compiler-warning-level-3-c4161.md)|#pragma 'pragma'(pop...): more pops than pushes| -|[Compiler warning (level 1) C4162](../../error-messages/compiler-warnings/compiler-warning-level-1-c4162.md)|'identifier': no function with C linkage found| -|[Compiler warning (level 1) C4163](compiler-warning-level-1-c4163.md)|'identifier': not available as an intrinsic function| -|[Compiler warning (level 1) C4164](compiler-warning-level-1-c4164.md)|'function': intrinsic function not declared| -|[Compiler warning (level 1) C4165](compiler-warning-level-1-c4165.md)|'HRESULT' is being converted to 'bool'; are you sure this is what you want?| +|[Compiler warning (level 2) C4156](compiler-warning-level-2-c4156.md)|deletion of an array expression without using the array form of 'delete'; array form substituted| +|[Compiler warning (level 1) C4157](compiler-warning-level-1-c4157.md)|pragma was ignored by C compiler| +|[Compiler warning (level 1) C4158](compiler-warning-level-1-c4158.md)|assuming `#pragma pointers_to_members(full_generality, `*inheritance_type*`)`| +|[Compiler warning (level 3) C4159](compiler-warning-level-3-c4159.md)|`#pragma `*pragma*`(pop,...)`: has popped previously pushed identifier '*identifier*'| +|[Compiler warning (level 1) C4160](compiler-warning-level-1-c4160.md)|`#pragma `*pragma*`(pop,...)`: did not find previously pushed identifier '*identifier*'| +|[Compiler warning (level 3) C4161](compiler-warning-level-3-c4161.md)|`#pragma `*pragma*`(pop...)`: more pops than pushes| +|[Compiler warning (level 1) C4162](compiler-warning-level-1-c4162.md)|'*identifier*': no function with C linkage found| +|[Compiler warning (level 1) C4163](compiler-warning-level-1-c4163.md)|'*identifier*': not available as an intrinsic function| +|[Compiler warning (level 1) C4164](compiler-warning-level-1-c4164.md)|'*function*': intrinsic function not declared| +|[Compiler warning (level 3, off) C4165](compiler-warning-level-1-c4165.md)|'`HRESULT`' is being converted to '`bool`'; are you sure this is what you want?| |[Compiler warning (level 1) C4166](compiler-warning-level-1-c4166.md)|illegal calling convention for constructor/destructor| -|[Compiler warning (level 1) C4167](compiler-warning-level-1-c4167.md)|'function': only available as an intrinsic function| -|[Compiler warning (level 1) C4168](compiler-warning-level-1-c4168.md)|compiler limit: out of debugger types, delete program database 'database' and rebuild| -|[Compiler warning (level 1) C4172](../../error-messages/compiler-warnings/compiler-warning-level-1-c4172.md)|returning address of local variable or temporary| -|[Compiler warning (level 1) C4174](compiler-warning-level-1-c4174.md)|'name': not available as a #pragma component| -|[Compiler warning (level 1) C4175](compiler-warning-level-1-c4175.md)|#pragma component(browser, on): browser info must initially be specified on the command line| -|[Compiler warning (level 1) C4176](compiler-warning-level-1-c4176.md)|'subcomponent': unknown subcomponent for #pragma component browser| -|[Compiler warning (level 1) C4177](compiler-warning-level-1-c4177.md)|#pragma 'pragma' should only be used at global scope or namespace scope| -|[Compiler warning (level 1) C4178](compiler-warning-level-1-c4178.md)|case constant 'constant' too big for the type of the switch expression| -|[Compiler warning (level 4) C4179](compiler-warning-level-1-c4179.md)|'//*': parsed as '/' and '/\*': confusion with standard '//' comments| +|[Compiler warning (level 1) C4167](compiler-warning-level-1-c4167.md)|'*function*': only available as an intrinsic function| +|[Compiler warning (level 1) C4168](compiler-warning-level-1-c4168.md)|compiler limit: out of debugger types, delete program database '*database*' and rebuild| +|[Compiler warning (level 1) C4172](compiler-warning-level-1-c4172.md)|returning address of local variable or temporary *optional_context*| +|[Compiler warning (level 1) C4174](compiler-warning-level-1-c4174.md)|'*name*': not available as a `#pragma component`| +|[Compiler warning (level 1) C4175](compiler-warning-level-1-c4175.md)|`#pragma component(browser, on)`: browser info must initially be specified on the command line| +|[Compiler warning (level 1) C4176](compiler-warning-level-1-c4176.md)|'*subcomponent*': unknown subcomponent for `#pragma component` browser| +|[Compiler warning (level 1) C4177](compiler-warning-level-1-c4177.md)|`#pragma `'*pragma*' should only be used at global scope or namespace scope| +|[Compiler warning (level 1) C4178](compiler-warning-level-1-c4178.md)|`case` constant '*constant*' too big for the type of the switch expression| +|[Compiler warning (level 4, no longer emitted) C4179](compiler-warning-level-1-c4179.md)|'`//*`': parsed as '`/`' and '`/\*`': confusion with standard '`//`' comments| |[Compiler warning (level 1) C4180](compiler-warning-level-1-c4180.md)|qualifier applied to function type has no meaning; ignored| |Compiler warning C4181|qualifier applied to reference type; ignored| -|[Compiler warning (level 1) C4182](compiler-warning-level-1-c4182.md)|#include nesting level is 'nest_count' deep; possible infinite recursion| -|[Compiler warning (level 1) C4183](../../error-messages/compiler-warnings/compiler-warning-level-1-c4183.md)|'identifier': missing return type; assumed to be a member function returning 'int'| -|[Compiler warning (level 1) C4185](compiler-warning-level-1-c4185.md)|ignoring unknown #import attribute 'attribute'| -|[Compiler warning (level 1) C4186](compiler-warning-level-1-c4186.md)|#import attribute 'attribute' requires 'argument_count' arguments; ignored| -|[Compiler warning (level 1) C4187](compiler-warning-level-1-c4187.md)|#import attributes 'attribute1' and 'attribute2' are incompatible; both ignored| +|[Compiler warning (level 1) C4182](compiler-warning-level-1-c4182.md)|`#include` nesting level is *nest_count* deep; possible infinite recursion| +|[Compiler warning (level 1) C4183](compiler-warning-level-1-c4183.md)|'*identifier*': missing return type; assumed to be a member function returning '`int`'| +|[Compiler warning (level 1) C4185](compiler-warning-level-1-c4185.md)|ignoring unknown `#`*import* attribute '*attribute*'| +|[Compiler warning (level 1) C4186](compiler-warning-level-1-c4186.md)|`#`*import* attribute '*attribute*' requires *argument_count* arguments; ignored| +|[Compiler warning (level 1) C4187](compiler-warning-level-1-c4187.md)|`#import` attributes '*attribute1*' and '*attribute2*' are incompatible; both ignored| |Compiler warning (level 1) C4188|constant expression is not integral| -|[Compiler warning (level 4) C4189](compiler-warning-level-4-c4189.md)|'identifier': local variable is initialized but not referenced| -|[Compiler warning (level 1) C4190](../../error-messages/compiler-warnings/compiler-warning-level-1-c4190.md)|'identifier1' has C-linkage specified, but returns UDT 'identifier2' which is incompatible with C| -|[Compiler warning (level 3) C4191](compiler-warning-level-3-c4191.md)|'operator/operation': unsafe conversion from 'type_of_expression' to 'type_required'\nCalling this function through the result pointer may cause your program to fail| -|[Compiler warning (level 3) C4192](../../error-messages/compiler-warnings/compiler-warning-level-3-c4192.md)|automatically excluding 'identifier' while importing type library 'library'| -|Compiler warning (level 3) C4193|#pragma warning(pop): no matching '#pragma warning(push)'| -|Compiler warning (level 1) C4194|#pragma start_map_region cannot be nested; ignored| -|Compiler warning (level 1) C4195|#pragma stop_map_region used without matching #pragma start_map_region; ignored| -|Compiler warning (level 1) C4196|expected '%$L' or '%$L'; found '%$L'| -|[Compiler warning (level 3) C4197](../../error-messages/compiler-warnings/compiler-warning-level-3-c4197.md)|'type': top-level volatile in cast is ignored| -|Compiler warning (level 1, level 2, level 3, and level 4) C4199|%s| +|[Compiler warning (level 3 and level 4) C4189](compiler-warning-level-4-c4189.md)|'*identifier*': local variable is initialized but not referenced| +|[Compiler warning (level 1) C4190](compiler-warning-level-1-c4190.md)|'*identifier1*' has C-linkage specified, but returns '*identifier2*' which is incompatible with C| +|[Compiler warning (level 3, off) C4191](compiler-warning-level-3-c4191.md)|'*operation*': unsafe conversion from '*type_of_expression*' to '*type_required*'
Making a function call using the resulting pointer may cause your program to fail| +|[Compiler warning (level 3) C4192](compiler-warning-level-3-c4192.md)|automatically excluding '*identifier*' while importing type library '*library*'| +|Compiler warning (level 3) C4193|`#pragma warning(pop)`: no matching '`#pragma warning(push)`'| +|Compiler warning (level 1) C4194|`#pragma start_map_region` cannot be nested; ignored| +|Compiler warning (level 1) C4195|`#pragma stop_map_region` used without matching `#pragma start_map_region`; ignored| +|Compiler warning (level 1) C4196|expected '*token1*' or '*token2*'; found '*token3*'| +|[Compiler warning (level 3) C4197](compiler-warning-level-3-c4197.md)|'*type*': top-level `volatile` in cast is ignored| +|Compiler warning (level 1, level 2, level 3, and level 4) C4199|*message*| ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4200-through-c4399.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4200-through-c4399.md index 843d241ee3..08698aef3a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4200-through-c4399.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4200-through-c4399.md @@ -1,12 +1,13 @@ --- -title: "Compiler warnings C4200 Through C4399" -description: "Table of Microsoft C/C++ compiler warnings C4200 through C4389." +title: "Microsoft C/C++ compiler (MSVC) warnings C4200 through C4399" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4200 through C4399." ms.date: 10/18/2020 f1_keywords: ["C4203", "C4277", "C4279", "C4298", "C4299", "C4301", "C4303", "C4314", "C4315", "C4317", "C4318", "C4321", "C4322", "C4323", "C4327", "C4328", "C4330", "C4338", "C4352", "C4362", "C4367", "C4370", "C4380", "C4387"] +helpviewer_keywords: ["C4203", "C4277", "C4279", "C4298", "C4299", "C4301", "C4303", "C4314", "C4315", "C4317", "C4318", "C4321", "C4322", "C4323", "C4327", "C4328", "C4330", "C4338", "C4352", "C4362", "C4367", "C4370", "C4380", "C4387"] --- -# Compiler warnings C4200 through C4399 +# Microsoft C/C++ compiler warnings C4200 through C4399 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4200 through C4399. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -14,166 +15,166 @@ The articles in this section of the documentation explain a subset of the warnin |Warning|Message| |-------------|-------------| -|[Compiler warning (levels 2 and 4) C4200](../../error-messages/compiler-warnings/compiler-warning-levels-2-and-4-c4200.md)|nonstandard extension used: zero-sized array in struct/union| -|[Compiler warning (level 4) C4201](../../error-messages/compiler-warnings/compiler-warning-level-4-c4201.md)|nonstandard extension used: nameless struct/union| -|[Compiler warning (level 4) C4202](../../error-messages/compiler-warnings/compiler-warning-level-4-c4202.md)|nonstandard extension used: '...': prototype parameter in name list illegal| +|[Compiler warning (level 2 and level 4) C4200](compiler-warning-levels-2-and-4-c4200.md)|nonstandard extension used: zero-sized array in struct/union| +|[Compiler warning (level 4) C4201](compiler-warning-level-4-c4201.md)|nonstandard extension used: nameless struct/union| +|[Compiler warning (level 4) C4202](compiler-warning-level-4-c4202.md)|nonstandard extension used: '`...`': prototype parameter in name list illegal| |Compiler warning C4203|nonstandard extension used: union with static member variable| -|[Compiler warning (level 4) C4204](../../error-messages/compiler-warnings/compiler-warning-level-4-c4204.md)|nonstandard extension used: non-constant aggregate initializer| -|[Compiler warning (level 4) C4205](../../error-messages/compiler-warnings/compiler-warning-level-4-c4205.md)|nonstandard extension used: static function declaration in function scope| -|[Compiler warning (level 4) C4206](../../error-messages/compiler-warnings/compiler-warning-level-4-c4206.md)|nonstandard extension used: translation unit is empty| -|[Compiler warning (level 4) C4207](../../error-messages/compiler-warnings/compiler-warning-level-4-c4207.md)|nonstandard extension used: extended initializer form| -|[Compiler warning (level 4) C4208](../../error-messages/compiler-warnings/compiler-warning-level-4-c4208.md)|nonstandard extension used: delete [exp] - exp evaluated but ignored| -|[Compiler warning (level 4) C4210](../../error-messages/compiler-warnings/compiler-warning-level-4-c4210.md)|nonstandard extension used: function given file scope| -|[Compiler warning (level 4) C4211](../../error-messages/compiler-warnings/compiler-warning-level-4-c4211.md)|nonstandard extension used: redefined extern to static| -|[Compiler warning (level 4) C4212](../../error-messages/compiler-warnings/compiler-warning-level-4-c4212.md)|nonstandard extension used: function declaration used ellipsis| -|[Compiler warning (level 4) C4213](../../error-messages/compiler-warnings/compiler-warning-level-4-c4213.md)|nonstandard extension used: cast on l-value| -|[Compiler warning (level 4) C4214](../../error-messages/compiler-warnings/compiler-warning-level-4-c4214.md)|nonstandard extension used: bit field types other than int| -|[Compiler warning (level 1) C4215](../../error-messages/compiler-warnings/compiler-warning-level-1-c4215.md)|nonstandard extension used: long float| -|[Compiler warning (level 1) C4216](../../error-messages/compiler-warnings/compiler-warning-level-1-c4216.md)|nonstandard extension used: float long| -|[Compiler warning (level 1) C4218](../../error-messages/compiler-warnings/compiler-warning-level-1-c4218.md)|nonstandard extension used: must specify at least a storage class or a type| -|[Compiler warning (level 4) C4220](../../error-messages/compiler-warnings/compiler-warning-level-4-c4220.md)|varargs matches remaining parameters| -|[Compiler warning (level 4) C4221](../../error-messages/compiler-warnings/compiler-warning-level-4-c4221.md)|nonstandard extension used: '*identifier*': cannot be initialized using address of automatic variable '*variable*'| -|[Compiler warning (levels 1 and 4) C4223](../../error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4223.md)|nonstandard extension used: non-lvalue array converted to pointer| -|[Compiler warning (level 1) C4224](../../error-messages/compiler-warnings/compiler-warning-level-1-c4224.md)|nonstandard extension used: formal parameter '*identifier*' was previously defined as a type| -|[Compiler warning (level 1, Error) C4226](../../error-messages/compiler-warnings/compiler-warning-level-1-c4226.md)|nonstandard extension used: '*keyword*' is an obsolete keyword| -|[Compiler warning (level 1) C4227](../../error-messages/compiler-warnings/compiler-warning-level-1-c4227.md)|anachronism used: qualifiers on reference are ignored| -|[Compiler warning (level 1) C4228](../../error-messages/compiler-warnings/compiler-warning-level-1-c4228.md)|nonstandard extension used: qualifiers after comma in declarator list are ignored| -|[Compiler warning (level 1) C4229](../../error-messages/compiler-warnings/compiler-warning-level-1-c4229.md)|anachronism used: modifiers on data are ignored| -|[Compiler warning (level 1) C4230](../../error-messages/compiler-warnings/compiler-warning-level-1-c4230.md)|anachronism used: modifiers/qualifiers interspersed; qualifier ignored| -|[Compiler warning (level 4) C4232](../../error-messages/compiler-warnings/compiler-warning-level-4-c4232.md)|nonstandard extension used: '*identifier*': address of dllimport '*dllimport*' is not static, identity not guaranteed| -|[Compiler warning (level 4, Error) C4233](../../error-messages/compiler-warnings/compiler-warning-level-4-c4233.md)|nonstandard extension used: '*keyword*' keyword only supported in C++, not C| -|[Compiler warning (level 4, Error) C4234](../../error-messages/compiler-warnings/compiler-warning-level-4-c4234.md)|nonstandard extension used: '*keyword*' keyword reserved for future use| -|[Compiler warning (level 4, Error) C4235](../../error-messages/compiler-warnings/compiler-warning-level-4-c4235.md)|nonstandard extension used: '*keyword*' keyword not supported on this architecture| -|[Compiler warning (level 1) C4237](../../error-messages/compiler-warnings/compiler-warning-level-1-c4237.md)|'*keyword*' keyword is not yet supported, but reserved for future use| -|[Compiler warning (level 4) C4238](../../error-messages/compiler-warnings/compiler-warning-level-4-c4238.md)|nonstandard extension used: class rvalue used as lvalue| -|[Compiler warning (level 4) C4239](../../error-messages/compiler-warnings/compiler-warning-level-4-c4239.md)|nonstandard extension used: '*token*': conversion from '*type1*' to '*type2*'| -|[Compiler warning (level 3) C4240](../../error-messages/compiler-warnings/compiler-warning-level-3-c4240.md)|nonstandard extension used: access to '*classname*' now defined to be '*access_specifier1*', previously it was defined to be '*access_specifier2*'| -|[Compiler warning (level 4) C4242](../../error-messages/compiler-warnings/compiler-warning-level-4-c4242.md)|'*identifier*': conversion from '*type1*' to '*type2*', possible loss of data| -|[Compiler warning (level 3) C4243](../../error-messages/compiler-warnings/compiler-warning-level-3-c4243.md)|'*conversion_type*' conversion from '*type1*' to '*type2*' exists, but is inaccessible| -|[Compiler warning (level 2) C4244](../../error-messages/compiler-warnings/compiler-warning-level-2-c4244.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', possible loss of data| -|[Compiler warning (levels 3 and 4) C4244](../../error-messages/compiler-warnings/compiler-warning-levels-3-and-4-c4244.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', possible loss of data| -|[Compiler warning (level 4) C4245](../../error-messages/compiler-warnings/compiler-warning-level-4-c4245.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', signed/unsigned mismatch| -|[Compiler warning (level 2) C4250](../../error-messages/compiler-warnings/compiler-warning-level-2-c4250.md)|'*classname*': inherits '*base_classname*::*member*' via dominance| -|[Compiler warning (level 1) C4251](../../error-messages/compiler-warnings/compiler-warning-level-1-c4251.md)|'*identifier*': '*object_type1*' '*identifier1*' needs to have dll-interface to be used by clients of '*object_type*' '*identfier2*'| -|[Compiler warning (level 4) C4254](../../error-messages/compiler-warnings/compiler-warning-level-4-c4254.md)|'*operator*': conversion from '*type1*:*field_bits*' to '*type2*:*field_bits*', possible loss of data| -|[Compiler warning (level 4) C4255](../../error-messages/compiler-warnings/compiler-warning-level-4-c4255.md)|'*function*': no function prototype given: converting '()' to '(void)'| -|[Compiler warning (level 4) C4256](../../error-messages/compiler-warnings/compiler-warning-level-4-c4256.md)|'*function*': constructor for class with virtual bases has '...'; calls may not be compatible with older versions of Visual C++| -|[Compiler warning (level 1) C4258](../../error-messages/compiler-warnings/compiler-warning-level-1-c4258.md)|'*variable*': definition from the for loop is ignored; the definition from the enclosing scope is used| -|[Compiler warning (level 4) C4263](../../error-messages/compiler-warnings/compiler-warning-level-4-c4263.md)|'*function*': member function does not override any base class virtual member function| -|[Compiler warning (level 1) C4264](../../error-messages/compiler-warnings/compiler-warning-level-1-c4264.md)|'*virtual_function*': no override available for virtual member function from base '*classname*'; function is hidden| -|[Compiler warning (level 3) C4265](../../error-messages/compiler-warnings/compiler-warning-level-3-c4265.md)|'*classname*': class has virtual functions, but destructor is not virtual\n instances of this class may not be destructed correctly| -|[Compiler warning (level 4) C4266](../../error-messages/compiler-warnings/compiler-warning-level-4-c4266.md)|'*virtual_function*': no override available for virtual member function from base '*classname*'; function is hidden| -|[Compiler warning (level 3) C4267](../../error-messages/compiler-warnings/compiler-warning-level-3-c4267.md)|'*variable*': conversion from 'size_t' to '*type*', possible loss of data| -|[Compiler warning (level 4) C4268](../../error-messages/compiler-warnings/compiler-warning-level-4-c4268.md)|'*identifier*': 'const' static/global data initialized with compiler generated default constructor fills the object with zeros| -|[Compiler warning (level 1) C4269](../../error-messages/compiler-warnings/compiler-warning-level-1-c4269.md)|'*identifier*': 'const' automatic data initialized with compiler generated default constructor produces unreliable results| -|[Compiler warning (level 1) C4272](../../error-messages/compiler-warnings/compiler-warning-level-1-c4272.md)|'*function*': is marked __declspec(dllimport); must specify native calling convention when importing a function.| -|[Compiler warning (level 1) C4273](../../error-messages/compiler-warnings/compiler-warning-level-1-c4273.md)|'*function*': inconsistent dll linkage| -|[Compiler warning (level 1) C4274](compiler-warning-level-1-c4274.md)|#ident ignored; see documentation for #pragma comment(exestr, 'string')| -|[Compiler warning (level 2) C4275](../../error-messages/compiler-warnings/compiler-warning-level-2-c4275.md)|non dll-interface '*classkey*' '*identifier1*' used as base for dll-interface '*classkey*' '*identifier2*'| -|[Compiler warning (level 1) C4276](../../error-messages/compiler-warnings/compiler-warning-level-1-c4276.md)|'*function*': no prototype provided; assumed no parameters| +|[Compiler warning (level 4) C4204](compiler-warning-level-4-c4204.md)|nonstandard extension used: non-constant aggregate initializer| +|[Compiler warning (level 4) C4205](compiler-warning-level-4-c4205.md)|nonstandard extension used: static function declaration in function scope| +|[Compiler warning (level 4) C4206](compiler-warning-level-4-c4206.md)|nonstandard extension used: translation unit is empty| +|[Compiler warning (level 4) C4207](compiler-warning-level-4-c4207.md)|nonstandard extension used: extended initializer form| +|[Compiler warning (level 4) C4208](compiler-warning-level-4-c4208.md)|nonstandard extension used: delete [exp] - exp evaluated but ignored| +|[Compiler warning (level 4) C4210](compiler-warning-level-4-c4210.md)|nonstandard extension used: function given file scope| +|[Compiler warning (level 4) C4211](compiler-warning-level-4-c4211.md)|nonstandard extension used: redefined extern to static| +|[Compiler warning (level 4) C4212](compiler-warning-level-4-c4212.md)|nonstandard extension used: function declaration used ellipsis| +|[Compiler warning (level 4) C4213](compiler-warning-level-4-c4213.md)|nonstandard extension used: cast on l-value| +|[Compiler warning (level 4) C4214](compiler-warning-level-4-c4214.md)|nonstandard extension used: bit field types other than int| +|[Compiler warning (level 1) C4215](compiler-warning-level-1-c4215.md)|nonstandard extension used: long float| +|[Compiler warning (level 1) C4216](compiler-warning-level-1-c4216.md)|nonstandard extension used: float long| +|[Compiler warning (level 4) C4218](compiler-warning-level-1-c4218.md)|nonstandard extension used: must specify at least a storage class or a type| +|[Compiler warning (level 4) C4220](compiler-warning-level-4-c4220.md)|varargs matches remaining parameters| +|[Compiler warning (level 4) C4221](compiler-warning-level-4-c4221.md)|nonstandard extension used: '*identifier*': cannot be initialized using address of automatic variable '*variable*'| +|[Compiler warning (level 1 and level 4) C4223](compiler-warning-levels-1-and-4-c4223.md)|nonstandard extension used: non-lvalue array converted to pointer| +|[Compiler warning (level 1) C4224](compiler-warning-level-1-c4224.md)|nonstandard extension used: formal parameter '*identifier*' was previously defined as a type| +|[Compiler warning (level 1, Error) C4226](compiler-warning-level-1-c4226.md)|nonstandard extension used: '*keyword*' is an obsolete keyword| +|[Compiler warning (level 1) C4227](compiler-warning-level-1-c4227.md)|anachronism used: qualifiers on reference are ignored| +|[Compiler warning (level 1) C4228](compiler-warning-level-1-c4228.md)|nonstandard extension used: qualifiers after comma in declarator list are ignored| +|[Compiler warning (level 1, Error) C4229](compiler-warning-level-1-c4229.md)|anachronism used: modifiers on data are ignored| +|[Compiler warning (level 1) C4230](compiler-warning-level-1-c4230.md)|anachronism used: modifiers/qualifiers interspersed; qualifier ignored| +|[Compiler warning (level 4) C4232](compiler-warning-level-4-c4232.md)|nonstandard extension used: '*identifier*': address of dllimport '*dllimport*' is not static, identity not guaranteed| +|[Compiler warning (level 1, Error) C4233](compiler-warning-level-4-c4233.md)|nonstandard extension used: '*keyword*' keyword only supported in C++, not C| +|[Compiler warning (level 4, Error) C4234](compiler-warning-level-4-c4234.md)|nonstandard extension used: '*keyword*' keyword reserved for future use| +|[Compiler warning (level 1, Error) C4235](compiler-warning-level-4-c4235.md)|nonstandard extension used: '*keyword*' keyword not supported on this architecture| +|[Compiler warning (level 1) C4237](compiler-warning-level-1-c4237.md)|'*keyword*' keyword is not yet supported, but reserved for future use| +|[Compiler warning (level 4) C4238](compiler-warning-level-4-c4238.md)|nonstandard extension used: class rvalue used as lvalue| +|[Compiler warning (level 4) C4239](compiler-warning-level-4-c4239.md)|nonstandard extension used: '*token*': conversion from '*type1*' to '*type2*'| +|[Compiler warning (level 3) C4240](compiler-warning-level-3-c4240.md)|nonstandard extension used: access to '*classname*' now defined to be '*access_specifier1*', previously it was defined to be '*access_specifier2*'| +|[Compiler warning (level 3, off) C4242](compiler-warning-level-4-c4242.md)|'*identifier*': conversion from '*type1*' to '*type2*', possible loss of data| +|[Compiler warning (level 3) C4243](compiler-warning-level-3-c4243.md)|*conversion_type* conversion from '*type1*' to '*type2*' exists, but is inaccessible| +|[Compiler warning (level 2) C4244](compiler-warning-level-2-c4244.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', possible loss of data| +|[Compiler warning (level 2 and level 3 and level 4) C4244](compiler-warning-levels-3-and-4-c4244.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', possible loss of data| +|[Compiler warning (level 4) C4245](compiler-warning-level-4-c4245.md)|'*conversion_type*': conversion from '*type1*' to '*type2*', signed/unsigned mismatch| +|[Compiler warning (level 2) C4250](compiler-warning-level-2-c4250.md)|'*classname*': inherits '*base_classname*::*member*' via dominance| +|[Compiler warning (level 2) C4251](compiler-warning-level-1-c4251.md)|'*type*': '*type1*' needs to have dll-interface to be used by clients of '*type2*'| +|[Compiler warning (level 4, off) C4254](compiler-warning-level-4-c4254.md)|'*operator*': conversion from '*type1*':'*field_bits*' to '*type2*':'*field_bits*', possible loss of data| +|[Compiler warning (level 4, off) C4255](compiler-warning-level-4-c4255.md)|'*function*': no function prototype given: converting '()' to '(void)'| +|[Compiler warning (level 4) C4256](compiler-warning-level-4-c4256.md)|'*function*': constructor for class with virtual bases has '`...`'; calls may not be compatible with older versions of Visual C++| +|[Compiler warning (level 1) C4258](compiler-warning-level-1-c4258.md)|'*variable*': definition from the for loop is ignored; the definition from the enclosing scope is used| +|[Compiler warning (level 4, off) C4263](compiler-warning-level-4-c4263.md)|'*function*': member function does not override any base class virtual member function| +|[Compiler warning (level 4, off) C4264](compiler-warning-level-1-c4264.md)|'*virtual_function*': no override available for virtual member function from base '*classname*'; function is hidden| +|[Compiler warning (level 3, off) C4265](compiler-warning-level-3-c4265.md)|'*classname*': class has virtual functions, but its non-trivial destructor is not virtual; instances of this class may not be destructed correctly| +|[Compiler warning (level 4, off) C4266](compiler-warning-level-4-c4266.md)|'*virtual_function*': no override available for virtual member function from base '*classname*'; function is hidden| +|[Compiler warning (level 3) C4267](compiler-warning-level-3-c4267.md)|'*variable*': conversion from 'size_t' to '*type*', possible loss of data| +|[Compiler warning (level 4) C4268](compiler-warning-level-4-c4268.md)|'*identifier*': 'const' static/global data initialized with compiler generated default constructor fills the object with zeros| +|[Compiler warning (level 1) C4269](compiler-warning-level-1-c4269.md)|'*identifier*': 'const' automatic data initialized with compiler generated default constructor produces unreliable results| +|[Compiler warning (level 1) C4272](compiler-warning-level-1-c4272.md)|'*function*': is marked __declspec(dllimport); must specify native calling convention when importing a function.| +|[Compiler warning (level 1) C4273](compiler-warning-level-1-c4273.md)|'*function*': inconsistent dll linkage| +|[Compiler warning (level 1) C4274](compiler-warning-level-1-c4274.md)|`#ident` ignored; see documentation for `#pragma comment(exestr, 'string')`| +|[Compiler warning (level 2) C4275](compiler-warning-level-2-c4275.md)|non dll-interface *classkey* '*identifier1*' used as base for dll-interface *classkey* '*identifier2*'| +|[Compiler warning (level 1) C4276](compiler-warning-level-1-c4276.md)|'*function*': no prototype provided; assumed no parameters| |Compiler warning (level 1) C4277|imported item '*classname*::*member*' exists as both data member and function member; data member ignored| -|[Compiler warning (level 3) C4278](../../error-messages/compiler-warnings/compiler-warning-level-3-c4278.md)|'*identifier*': identifier in type library '*library*' is already a macro; use the 'rename' qualifier| +|[Compiler warning (level 3 and level 4) C4278](compiler-warning-level-3-c4278.md)|'*identifier*': identifier in type library '*library*' is already a macro; use the 'rename' qualifier| |Compiler warning (level 3 and level 4) C4279|'*identifier*': identifier in type library '*library*' is a keyword; use the 'rename' qualifier| -|[Compiler warning (level 3) C4280](../../error-messages/compiler-warnings/compiler-warning-level-3-c4280.md)|'operator ->' was self recursive through type '*type*'| -|[Compiler warning (level 3) C4281](../../error-messages/compiler-warnings/compiler-warning-level-3-c4281.md)|'operator ->' recursion occurred through type '*type1*'| -|[Compiler warning (level 3) C4282](../../error-messages/compiler-warnings/compiler-warning-level-3-c4282.md)|then through type '*type2*'| -|[Compiler warning (level 3) C4283](../../error-messages/compiler-warnings/compiler-warning-level-3-c4283.md)|and through type '*typeN*'| -|[Compiler warning (level 2) C4285](../../error-messages/compiler-warnings/compiler-warning-level-2-c4285.md)|return type for '*identifier*::operator ->' is recursive if applied using infix notation| -|[Compiler warning (level 1) C4286](../../error-messages/compiler-warnings/compiler-warning-level-1-c4286.md)|'*derived_type*': is caught by base class ('*base_type*') on line '*line_number*'| -|[Compiler warning (level 3) C4287](../../error-messages/compiler-warnings/compiler-warning-level-3-c4287.md)|'*operator*': unsigned/negative constant mismatch| -|[Compiler warning (level 1) C4288](../../error-messages/compiler-warnings/compiler-warning-level-1-c4288.md)|nonstandard extension used: '*variable*': loop control variable declared in the for-loop is used outside the for-loop scope; it conflicts with the declaration in the outer scope| -|[Compiler warning (level 4) C4289](../../error-messages/compiler-warnings/compiler-warning-level-4-c4289.md)|nonstandard extension used: '*variable*': loop control variable declared in the for-loop is used outside the for-loop scope| -|[Compiler warning (level 3) C4290](../../error-messages/compiler-warnings/compiler-warning-level-3-c4290.md)|C++ exception specification ignored except to indicate a function is not __declspec(nothrow)| -|[Compiler warning (level 1) C4291](../../error-messages/compiler-warnings/compiler-warning-level-1-c4291.md)|'*declaration*': no matching operator delete found; memory will not be freed if initialization throws an exception| -|[Compiler warning (level 1) C4293](../../error-messages/compiler-warnings/compiler-warning-level-1-c4293.md)|'*shift_operator*': shift count negative or too big, undefined behavior| -|[Compiler warning (level 4) C4295](../../error-messages/compiler-warnings/compiler-warning-level-4-c4295.md)|'*array*': array is too small to include a terminating null character| -|[Compiler warning (level 4) C4296](../../error-messages/compiler-warnings/compiler-warning-level-4-c4296.md)|'*operator*': expression is always '*boolean_value*'| -|[Compiler warning (level 1) C4297](../../error-messages/compiler-warnings/compiler-warning-level-1-c4297.md)|'*function*': function assumed not to throw an exception but does| -|Compiler warning (level 4) C4298|'*identifier*': identifier in type library '*library*' is already a macro; renaming to '*__identifier*'| -|Compiler warning (level 4) C4299|'*identifier*': identifier in type library '*library*' is a keyword; renaming to '*__identifier*'| +|[Compiler warning (level 3) C4280](compiler-warning-level-3-c4280.md)|'`operator ->`' was self recursive through type '*type*'| +|[Compiler warning (level 3) C4281](compiler-warning-level-3-c4281.md)|'`operator ->`' recursion occurred through type '*type1*'| +|[Compiler warning (level 3) C4282](compiler-warning-level-3-c4282.md)|then through type '*type2*'| +|[Compiler warning (level 3) C4283](compiler-warning-level-3-c4283.md)|and through type '*typeN*'| +|[Compiler warning (level 2) C4285](compiler-warning-level-2-c4285.md)|return type for '*identifier*`::operator ->`' is recursive if applied using infix notation| +|[Compiler warning (level 1) C4286](compiler-warning-level-1-c4286.md)|'*derived_type*': is caught by base class ('*base_type*') on line *line_number*| +|[Compiler warning (level 3, off) C4287](compiler-warning-level-3-c4287.md)|'*operator*': unsigned/negative constant mismatch| +|[Compiler warning (level 1) C4288](compiler-warning-level-1-c4288.md)|nonstandard extension used: '*variable*': loop control variable declared in the for-loop is used outside the for-loop scope; it conflicts with the declaration in the outer scope| +|[Compiler warning (level 4, off) C4289](compiler-warning-level-4-c4289.md)|nonstandard extension used: '*variable*': loop control variable declared in the for-loop is used outside the for-loop scope| +|[Compiler warning (level 3) C4290](compiler-warning-level-3-c4290.md)|C++ exception specification ignored except to indicate a function is not `__declspec(nothrow)`| +|[Compiler warning (level 1) C4291](compiler-warning-level-1-c4291.md)|'*declaration*': no matching operator delete found; memory will not be freed if initialization throws an exception| +|[Compiler warning (level 1) C4293](compiler-warning-level-1-c4293.md)|'*shift_operator*': shift count negative or too big, undefined behavior| +|[Compiler warning (level 4) C4295](compiler-warning-level-4-c4295.md)|'*array*': array is too small to include a terminating null character| +|[Compiler warning (level 4, off) C4296](compiler-warning-level-4-c4296.md)|'*operator*': expression is always *boolean_value*| +|[Compiler warning (level 1) C4297](compiler-warning-level-1-c4297.md)|'*function*': function assumed not to throw an exception but does| +|Compiler warning (level 4) C4298|'*identifier*': identifier in type library '*library*' is already a macro; renaming to '__*identifier*'| +|Compiler warning (level 4) C4299|'*identifier*': identifier in type library '*library*' is a keyword; renaming to '__*identifier*'| |Compiler warning C4301|'*derived_class*::*function*': overriding virtual function only differs from '*base_class*::*function*' by const/volatile qualifier| -|[Compiler warning (level 2) C4302](../../error-messages/compiler-warnings/compiler-warning-level-2-c4302.md)|'*conversion*': truncation from '*type1*' to '*type2*'| -|Compiler warning C4303|C-style cast from '*type1*' to '*type2*' is deprecated, use static\_cast, \_\_try\_cast or dynamic\_cast| -|[Compiler warning (level 1) C4305](../../error-messages/compiler-warnings/compiler-warning-level-1-c4305.md)|'*conversion*': truncation from '*type1*' to '*type2*'| -|[Compiler warning (level 3) C4306](../../error-messages/compiler-warnings/compiler-warning-level-3-c4306.md)|'*conversion*': conversion from '*type1*' to '*type2*' of greater size| -|[Compiler warning (level 2) C4307](../../error-messages/compiler-warnings/compiler-warning-level-2-c4307.md)|'*operator*': integral constant overflow| -|[Compiler warning (level 2) C4308](../../error-messages/compiler-warnings/compiler-warning-level-2-c4308.md)|negative integral constant converted to unsigned type| -|[Compiler warning (level 2) C4309](../../error-messages/compiler-warnings/compiler-warning-level-2-c4309.md)|'*conversion*': truncation of constant value| -|[Compiler warning (level 3) C4310](../../error-messages/compiler-warnings/compiler-warning-level-3-c4310.md)|cast truncates constant value| -|[Compiler warning (level 1) C4311](../../error-messages/compiler-warnings/compiler-warning-level-1-c4311.md)|'*variable*': pointer truncation from '*type1*' to '*type2*'| -|[Compiler warning (level 1) C4312](../../error-messages/compiler-warnings/compiler-warning-level-1-c4312.md)|'*operation*': conversion from '*type1*' to '*type2*' of greater size| -|[Compiler warning (level 1) C4313](../../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md)|'*function*': '*format_specifier*' in format string conflicts with argument '*argument_number*' of type '*type*'| +|[Compiler warning (level 2) C4302](compiler-warning-level-2-c4302.md)|'*conversion*': truncation from '*type1*' to '*type2*'| +|Compiler warning (no longer emitted) C4303|C-style cast from '*type1*' to '*type2*' is deprecated, use `static_cast`, `__try_cast` or `dynamic_cast`| +|[Compiler warning (level 1 and level 2 and level 4) C4305](compiler-warning-level-1-c4305.md)|'*conversion*': truncation from '*type1*' to '*type2*'| +|[Compiler warning (level 4) C4306](compiler-warning-level-3-c4306.md)|'*conversion*': conversion from '*type1*' to '*type2*' of greater size| +|[Compiler warning (level 2) C4307](compiler-warning-level-2-c4307.md)|'*operator*': signed integral constant overflow| +|[Compiler warning (level 2) C4308](compiler-warning-level-2-c4308.md)|negative integral constant converted to unsigned type| +|[Compiler warning (level 2) C4309](compiler-warning-level-2-c4309.md)|'*conversion*': truncation of constant value| +|[Compiler warning (level 4) C4310](compiler-warning-level-3-c4310.md)|cast truncates constant value| +|[Compiler warning (level 1) C4311](compiler-warning-level-1-c4311.md)|'*variable*': pointer truncation from '*type1*' to '*type2*'| +|[Compiler warning (level 1) C4312](compiler-warning-level-1-c4312.md)|'*operation*': conversion from '*type1*' to '*type2*' of greater size| +|[Compiler warning (level 1) C4313](compiler-warning-level-1-c4313.md)|'*function*': '`%`*format_specifier*' in format string conflicts with argument *argument_number* of type '*type*'| |Compiler warning C4314|expected pragma parameter to be '32' or '64'| -|Compiler warning (level 4) C4315|'*classname*': 'this' pointer for member '*member*' may not be aligned '*alignment*' as expected by the constructor| -|[Compiler warning (level 3) C4316](compiler-warning-level-3-c4316.md)|'*identifier*': object allocated on the heap may not be aligned '*alignment*'| +|Compiler warning (level 4) C4315|'*classname*': 'this' pointer for member '*member*' may not be aligned *alignment* as expected by the constructor| +|[Compiler warning (level 3) C4316](compiler-warning-level-3-c4316.md)|'*identifier*': object allocated on the heap may not be aligned *alignment*| |Compiler warning (level 1) C4317|'*printf_family*' : not enough arguments passed for format string| |Compiler warning C4318|passing constant zero as the length to memset| -|[Compiler warning (level 1) C4319](../../error-messages/compiler-warnings/compiler-warning-level-1-c4319.md)|'*operator*': zero extending '*type1*' to '*type2*' of greater size| +|[Compiler warning (level 1) C4319](compiler-warning-level-1-c4319.md)|'*operator*': zero extending '*type1*' to '*type2*' of greater size| |Compiler warning (level 1) C4321|automatically generating an IID for interface '*interface*'| |Compiler warning (level 1) C4322|automatically generating a CLSID for class '*class*'| |Compiler warning (level 1) C4323|re-using registered CLSID for class '*class*'| -|[Compiler warning (level 4) C4324](../../error-messages/compiler-warnings/compiler-warning-level-4-c4324.md)|'*structname*': structure was padded due to __declspec(align())| -|[Compiler warning (level 1) C4325](../../error-messages/compiler-warnings/compiler-warning-level-1-c4325.md)|attributes for standard section '*section*' ignored| -|[Compiler warning (level 1) C4326](../../error-messages/compiler-warnings/compiler-warning-level-1-c4326.md)|return type of '*function*' should be '*type1*' instead of '*type2*'| +|[Compiler warning (level 4) C4324](compiler-warning-level-4-c4324.md)|'*structname*': structure was padded due to alignment specifier| +|[Compiler warning (level 1) C4325](compiler-warning-level-1-c4325.md)|attributes for standard section '*section*' ignored| +|[Compiler warning (level 1) C4326](compiler-warning-level-1-c4326.md)|return type of '*function*' should be '*type1*' instead of '*type2*'| |Compiler warning C4327|'*assignment*': indirection alignment of LHS ('*alignment1*') is greater than RHS ('*alignment2*')| |Compiler warning C4328|'*function*': indirection alignment of formal parameter *parameter_number* (*parameter_alignment*) is greater than the actual argument alignment (*argument_alignment*)| -|[Compiler warning (level 1) C4329](../../error-messages/compiler-warnings/compiler-warning-level-1-c4329.md)|__declspec(align()) is ignored on enum| +|[Compiler warning (level 1) C4329](compiler-warning-level-1-c4329.md)|alignment specifier is ignored on enum| |Compiler warning (level 1) C4330|attribute '*attribute*' for section '*section*' ignored| -|[Compiler warning (level 1) C4333](../../error-messages/compiler-warnings/compiler-warning-level-1-c4333.md)|'*shift_operator*': right shift by too large amount, data loss| -|[Compiler warning (level 3) C4334](../../error-messages/compiler-warnings/compiler-warning-level-3-c4334.md)|'*shift_operator*': result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)| -|[Compiler warning C4335](../../error-messages/compiler-warnings/compiler-warning-c4335.md)|Mac file format detected: please convert the source file to either DOS or UNIX format| -|[Compiler warning (level 4) C4336](../../error-messages/compiler-warnings/compiler-warning-level-4-c4336.md)|import cross-referenced type library '*library1*' before importing '*library2*'| -|[Compiler warning (level 4) C4337](../../error-messages/compiler-warnings/compiler-warning-level-4-c4337.md)|cross-referenced type library '*library1*' in '*library2*' is being automatically imported| +|[Compiler warning (level 1) C4333](compiler-warning-level-1-c4333.md)|'*shift_operator*': right shift by too large amount, data loss| +|[Compiler warning (level 3) C4334](compiler-warning-level-3-c4334.md)|'*shift_operator*': result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)| +|[Compiler warning (level 1) C4335](compiler-warning-c4335.md)|Mac file format detected: please convert the source file to either DOS or UNIX format| +|[Compiler warning (level 4) C4336](compiler-warning-level-4-c4336.md)|import cross-referenced type library '*library1*' before importing '*library2*'| +|[Compiler warning (level 4) C4337](compiler-warning-level-4-c4337.md)|cross-referenced type library '*library1*' in '*library2*' is being automatically imported| |Compiler warning (level 4) C4338|#pragma *directive*: standard section '*section*' is used| -|[Compiler warning (level 4) C4339](../../error-messages/compiler-warnings/compiler-warning-level-4-c4339.md)|'*type*': use of undefined type detected in 'WinRT|CLR' meta-data - use of this type may lead to a runtime exception| -|[Compiler warning (level 1) C4340](../../error-messages/compiler-warnings/compiler-warning-level-1-c4340.md)|'*value*': value wrapped from positive to negative value| -|[Compiler warning (level 1) C4342](../../error-messages/compiler-warnings/compiler-warning-level-1-c4342.md)|behavior change: '*function*' called, but a member operator was called in previous versions| -|[Compiler warning (level 4) C4343](compiler-warning-level-4-c4343.md)|#pragma optimize("g",off) overrides /Og option| -|[Compiler warning (level 1) C4344](../../error-messages/compiler-warnings/compiler-warning-level-1-c4344.md)|behavior change: use of explicit template arguments results in call to '*function*'| -|[Compiler warning (level 1) C4346](../../error-messages/compiler-warnings/compiler-warning-level-1-c4346.md)|'*name*': dependent name is not a type| -|[Compiler warning (level 1) C4348](../../error-messages/compiler-warnings/compiler-warning-level-1-c4348.md)|'*type*': redefinition of default parameter: parameter '*parameter_number*'| -|[Compiler warning (level 1) C4350](../../error-messages/compiler-warnings/compiler-warning-level-1-c4350.md)|behavior change: '*member1*' called instead of '*member2*'| +|[Compiler warning (level 4, off) C4339](compiler-warning-level-4-c4339.md)|'*type*': use of undefined type detected in *WinRT/CLR* meta-data - use of this type may lead to a runtime exception| +|[Compiler warning (level 1) C4340](compiler-warning-level-1-c4340.md)|'*value*': value wrapped from positive to negative value| +|[Compiler warning (level 1, off, no longer emitted) C4342](compiler-warning-level-1-c4342.md)|behavior change: '*function*' called, but a member operator was called in previous versions| +|[Compiler warning (level 4) C4343](compiler-warning-level-4-c4343.md)|`#pragma optimize("g",off)` overrides `/Og` option| +|[Compiler warning (level 1) C4344](compiler-warning-level-1-c4344.md)|behavior change: use of explicit template arguments results in call to '*function*'| +|[Compiler warning (level 1) C4346](compiler-warning-level-1-c4346.md)|'*name*': dependent name is not a type| +|[Compiler warning (level 1) C4348](compiler-warning-level-1-c4348.md)|'*type*': redefinition of default parameter: parameter *parameter_number*| +|[Compiler warning (level 1, off, no longer emitted) C4350](compiler-warning-level-1-c4350.md)|behavior change: '*member1*' called instead of '*member2*'| |Compiler warning (level 1) C4352|'*identifier*': intrinsic function already defined| -|[Compiler warning (level 1) C4353](../../error-messages/compiler-warnings/compiler-warning-level-1-c4353.md)|nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead| -|[Compiler warning C4355](../../error-messages/compiler-warnings/compiler-warning-c4355.md)Compiler warning (level 1 and level 4) C4355|'this': used in base member initializer list| -|[Compiler warning (level 2) C4356](../../error-messages/compiler-warnings/compiler-warning-level-2-c4356.md)|'*member*': static data member cannot be initialized via derived class| -|[Compiler warning (level 3) C4357](../../error-messages/compiler-warnings/compiler-warning-level-3-c4357.md)|param array argument found in formal argument list for delegate '*delegate*' ignored when generating '*function*'| -|[Compiler warning (level 1) C4358](../../error-messages/compiler-warnings/compiler-warning-level-1-c4358.md)|'*operator*': return type of combined delegates is not 'void'; returned value is undefined| -|[Compiler warning (level 3) C4359](../../error-messages/compiler-warnings/compiler-warning-level-3-c4359.md)|'*type*': Alignment specifier is less than actual alignment ('*alignment*'), and will be ignored.| +|[Compiler warning (level 1) C4353](compiler-warning-level-1-c4353.md)|nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead| +|[Compiler warning (level 1 and level 4, off) C4355](compiler-warning-c4355.md)|'this': used in base member initializer list| +|[Compiler warning (level 2) C4356](compiler-warning-level-2-c4356.md)|'*member*': static data member cannot be initialized via derived class| +|[Compiler warning (level 3) C4357](compiler-warning-level-3-c4357.md)|param array argument found in formal argument list for delegate '*delegate*' ignored when generating '*function*'| +|[Compiler warning (level 1) C4358](compiler-warning-level-1-c4358.md)|'*operator*': return type of combined delegates is not 'void'; returned value is undefined| +|[Compiler warning (level 1 and level 3) C4359](compiler-warning-level-3-c4359.md)|'*type*': Alignment specifier is less than actual alignment (*alignment*), and will be ignored.| |Compiler warning (level 2) C4362|'*type*': alignment greater than 8 bytes is not supported by CLR| -|[Compiler warning (level 1) C4364](../../error-messages/compiler-warnings/compiler-warning-level-1-c4364.md)|#using for assembly '*assembly*' previously seen at '*location*'('*line_number*') without as\_friend attribute; as\_friend not applied| -|[Compiler warning (level 4) C4365](../../error-messages/compiler-warnings/compiler-warning-level-4-c4365.md)|'*expression*': conversion from '*type1*' to '*type2*', signed/unsigned mismatch| -|[Compiler warning (level 4) C4366](../../error-messages/compiler-warnings/compiler-warning-level-4-c4366.md)|The result of the unary '*operator*' operator may be unaligned| +|[Compiler warning (level 1) C4364](compiler-warning-level-1-c4364.md)|`#using` for assembly '*assembly*' previously seen at *location*(*line_number*) without `as_friend` attribute; `as_friend` not applied| +|[Compiler warning (level 4, off) C4365](compiler-warning-level-4-c4365.md)|'*expression*': conversion from '*type1*' to '*type2*', signed/unsigned mismatch| +|[Compiler warning (level 4) C4366](compiler-warning-level-4-c4366.md)|The result of the unary '*operator*' operator may be unaligned| |Compiler warning (level 3) C4367|Conversion from '*type1*' to '*type2*' may cause datatype misalignment exception| -|[Compiler warning (Error) C4368](../../error-messages/compiler-warnings/compiler-warning-c4368.md)|cannot define '*member*' as a member of managed '*type*': mixed types are not supported| -|[Compiler warning (level 1) C4369](../../error-messages/compiler-warnings/compiler-warning-level-1-c4369.md)|'*enumerator*': enumerator value '*value*' cannot be represented as '*type*', value is '*new_value*'| -|Compiler warning C4370|'*classname*': layout of class has changed from a previous version of the compiler due to better packing| -|[Compiler warning (level 3) C4371](../../error-messages/compiler-warnings/c4371.md)|'*classname*': layout of class may have changed from a previous version of the compiler due to better packing of member '*member*'| -|[Compiler warning (level 3) C4373](compiler-warning-level-3-c4373.md)|'*derived_class*::*function*': virtual function overrides '*base_class*::*function*', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers| -|[Compiler warning (level 1) C4374](../../error-messages/compiler-warnings/compiler-warning-level-1-c4374.md)|'*function1*': interface method will not be implemented by non-virtual method '*function2*'| -|[Compiler warning (level 1) C4375](../../error-messages/compiler-warnings/compiler-warning-level-1-c4375.md)|non-public method '*method2*' does not override '*method2*'| -|[Compiler warning (level 1) C4376](../../error-messages/compiler-warnings/compiler-warning-level-1-c4376.md)|access specifier '*old_specifier*:' is no longer supported: please use '*new_specifier*:' instead| -|[Compiler warning (level 1) C4377](../../error-messages/compiler-warnings/compiler-warning-level-1-c4377.md)|native types are private by default; -d1PrivateNativeTypes is deprecated| -|[Compiler warning (level 1) C4378](../../error-messages/compiler-warnings/compiler-warning-level-1-c4378.md)|Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle| -|[Compiler warning (level 1) C4379](../../error-messages/compiler-warnings/compiler-warning-level-1-c4379.md)|Version '*version_number*' of the common language runtime is not supported by this compiler. Using this version may cause unexpected results| +|[Compiler warning (level 1, Error) C4368](compiler-warning-c4368.md)|cannot define '*member*' as a member of managed '*type*': mixed types are not supported| +|[Compiler warning (level 1) C4369](compiler-warning-level-1-c4369.md)|'*enumerator*': enumerator value '*value*' cannot be represented as '*type*', value is '*new_value*'| +|Compiler warning (level 4, no longer emitted) C4370|'*classname*': layout of class has changed from a previous version of the compiler due to better packing| +|[Compiler warning (level 3, off) C4371](c4371.md)|'*classname*': layout of class may have changed from a previous version of the compiler due to better packing of member '*member*'| +|[Compiler warning (level 4) C4373](compiler-warning-level-3-c4373.md)|'*function*': virtual function overrides '*base_class_function*', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers| +|[Compiler warning (level 1) C4374](compiler-warning-level-1-c4374.md)|'*function1*': interface method will not be implemented by non-virtual method '*function2*'| +|[Compiler warning (level 1) C4375](compiler-warning-level-1-c4375.md)|non-public method '*method2*' does not override '*method2*'| +|[Compiler warning (level 1) C4376](compiler-warning-level-1-c4376.md)|access specifier '*specifier1* *specifier2*:' is no longer supported: please use '*new_specifier*:' instead| +|[Compiler warning (level 1) C4377](compiler-warning-level-1-c4377.md)|native types are private by default; -d1PrivateNativeTypes is deprecated| +|[Compiler warning (level 1) C4378](compiler-warning-level-1-c4378.md)|Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle| +|[Compiler warning (level 1) C4379](compiler-warning-level-1-c4379.md)|Version '*version_number*' of the common language runtime is not supported by this compiler. Using this version may cause unexpected results| |Compiler warning (level 1, Error) C4380|'*class*': A default constructor cannot be deprecated| -|[Compiler warning (level 1) C4381](../../error-messages/compiler-warnings/compiler-warning-level-1-c4381.md)|'*function1*': interface method will not be implemented by non-public method '*function2*'| -|[Compiler warning (level 1) C4382](../../error-messages/compiler-warnings/compiler-warning-level-1-c4382.md)|throwing '*type*': a type with __clrcall destructor or copy constructor can only be caught in /clr:pure module| -|[Compiler warning (level 1) C4383](../../error-messages/compiler-warnings/compiler-warning-level-1-c4383.md)|'*instance_dereference_operator*': the meaning of dereferencing a handle can change, when a user-defined '*instance_dereference_operator*' operator exists; write the operator as a static function to be explicit about the operand| -|[Compiler warning (level 1) C4384](../../error-messages/compiler-warnings/compiler-warning-level-1-c4384.md)|#pragma 'make_public' should only be used at global scope| +|[Compiler warning (level 1) C4381](compiler-warning-level-1-c4381.md)|'*function1*': interface method will not be implemented by non-public method '*function2*'| +|[Compiler warning (level 1) C4382](compiler-warning-level-1-c4382.md)|throwing '*type*': a type with `__clrcall` destructor or copy constructor can only be caught in `/clr:pure` module| +|[Compiler warning (level 1) C4383](compiler-warning-level-1-c4383.md)|'*instance_dereference_operator*': the meaning of dereferencing a handle can change, when a user-defined '*instance_dereference_operator*' operator exists; write the operator as a static function to be explicit about the operand| +|[Compiler warning (level 1) C4384](compiler-warning-level-1-c4384.md)|`#pragma` '*pragma_name*' should only be used at global scope| |Compiler warning (level 3) C4387|'*alternative*': was considered| -|[Compiler warning (level 4) C4388](./c4388.md))|'*expression*': signed/unsigned mismatch| -|[Compiler warning (level 4) C4389](../../error-messages/compiler-warnings/compiler-warning-level-4-c4389.md)|'*operator*': signed/unsigned mismatch| -|[Compiler warning (level 3) C4390](../../error-messages/compiler-warnings/compiler-warning-level-3-c4390.md)|';': empty controlled statement found; is this the intent?| -|[Compiler warning (level 1) C4391](../../error-messages/compiler-warnings/compiler-warning-level-1-c4391.md)|'*function_signature*': incorrect return type for intrinsic function, expected '*type*'| -|[Compiler warning (level 1) C4392](../../error-messages/compiler-warnings/compiler-warning-level-1-c4392.md)|'*function_signature*': incorrect number of arguments for intrinsic function, expected '*argument_count*' arguments| -|[Compiler warning (level 1) C4393](../../error-messages/compiler-warnings/compiler-warning-level-1-c4393.md)|'*variable*': const has no effect on '*literal*' data member; ignored| -|[Compiler warning C4394](../../error-messages/compiler-warnings/compiler-warning-c4394.md)|'*function*': per-appdomain symbol should not be marked with __declspec('dllexport')| -|[Compiler warning (level 1) C4395](../../error-messages/compiler-warnings/compiler-warning-level-1-c4395.md)|'*function*': member function will be invoked on a copy of the initonly data member '*member*'| +|[Compiler warning (level 4, off) C4388](./c4388.md))|'*expression*': signed/unsigned mismatch| +|[Compiler warning (level 4) C4389](compiler-warning-level-4-c4389.md)|'*operator*': signed/unsigned mismatch| +|[Compiler warning (level 3) C4390](compiler-warning-level-3-c4390.md)|';': empty controlled statement found; is this the intent?| +|[Compiler warning (level 1) C4391](compiler-warning-level-1-c4391.md)|'*function_signature*': incorrect return type for intrinsic function, expected '*type*'| +|[Compiler warning (level 1, Error) C4392](compiler-warning-level-1-c4392.md)|'*function_signature*': incorrect number of arguments for intrinsic function, expected '*argument_count*' arguments| +|[Compiler warning (level 1) C4393](compiler-warning-level-1-c4393.md)|'*variable*': const has no effect on *literal* data member; ignored| +|[Compiler warning (level 1, Error) C4394](compiler-warning-c4394.md)|'*function*': per-appdomain symbol should not be marked with `__declspec(`*dllexport*`)`| +|[Compiler warning (level 1) C4395](compiler-warning-level-1-c4395.md)|'*function*': member function will be invoked on a copy of the initonly data member '*member*'| |[Compiler warning (level 2) C4396](compiler-warning-level-2-c4396.md)|'*function*': the inline specifier cannot be used when a friend declaration refers to a specialization of a function template| -|[Compiler warning (level 1) C4397](../../error-messages/compiler-warnings/compiler-warning-level-1-c4397.md)|DefaultCharSetAttribute is ignored| -|[Compiler warning (level 3) C4398](../../error-messages/compiler-warnings/compiler-warning-level-3-c4398.md)|'*variable*': per-process global object might not work correctly with multiple appdomains; consider using __declspec(appdomain)| -|[Compiler warning (level 1) C4399](../../error-messages/compiler-warnings/compiler-warning-level-1-c4399.md)|'*symbol*': per-process symbol should not be marked with __declspec('dllimport') when compiled with /clr:pure| +|[Compiler warning (level 1) C4397](compiler-warning-level-1-c4397.md)|`DefaultCharSetAttribute` is ignored| +|[Compiler warning (level 3) C4398](compiler-warning-level-3-c4398.md)|'*variable*': per-process global object might not work correctly with multiple appdomains; consider using `__declspec(appdomain)`| +|[Compiler warning (level 1, Error) C4399](compiler-warning-level-1-c4399.md)|'*symbol*': per-process symbol should not be marked with `__declspec(`*dllimport*`)` when compiled with `/clr:pure`| ## See also diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md index 475af489f0..03b421b60e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler warnings C4400 Through C4599" -title: "Compiler warnings C4400 Through C4599" -ms.date: "04/21/2019" -f1_keywords: ["C4413", "C4415", "C4416", "C4417", "C4418", "C4419", "C4421", "C4423", "C4424", "C4425", "C4426", "C4427", "C4438", "C4442", "C4443", "C4444", "C4446", "C4447", "C4448", "C4449", "C4450", "C4452", "C4453", "C4454", "C4455", "C4472", "C4474", "C4475", "C4476", "C4478", "C4480", "C4482", "C4483", "C4491", "C4492", "C4493", "C4494", "C4495", "C4496", "C4497", "C4498", "C4499", "C4509", "C4519", "C4531", "C4542", "C4562", "C4568", "C4569", "C4573", "C4574", "C4575", "C4582", "C4583", "C4585", "C4586", "C4587", "C4588", "C4591", "C4592", "C4593", "C4594", "C4595", "C4598", "C4599"] -helpviewer_keywords: ["C4413", "C4415", "C4416", "C4417", "C4418", "C4419", "C4421", "C4423", "C4424", "C4425", "C4426", "C4427", "C4438", "C4442", "C4443", "C4444", "C4446", "C4447", "C4448", "C4449", "C4450", "C4451", "C4452", "C4453", "C4454", "C4455", "C4456", "C4457", "C4459", "C4472", "C4474", "C4475", "C4476", "C4478", "C4480", "C4482", "C4483", "C4491", "C4492", "C4493", "C4494", "C4495", "C4496", "C4497", "C4498", "C4499", "C4509", "C4519", "C4531", "C4542", "C4562", "C4568", "C4569", "C4573", "C4574", "C4575", "C4582", "C4583", "C4585", "C4586", "C4587", "C4588", "C4591", "C4592", "C4593", "C4594", "C4595", "C4598", "C4599"] -ms.assetid: b07850a5-ae89-48ea-bf9a-f0e30939f9b9 +title: "Microsoft C/C++ compiler (MSVC) warnings C4400 through C4599" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4400 through C4599" +ms.date: "1/22/2025" +f1_keywords: ["C4413", "C4415", "C4416", "C4417", "C4418", "C4419", "C4421", "C4423", "C4424", "C4425", "C4426", "C4427", "C4438", "C4442", "C4443", "C4444", "C4446", "C4447", "C4448", "C4449", "C4450", "C4451", "C4452", "C4453", "C4454", "C4455", "C4466", "C4467", "C4468", "C4472", "C4474", "C4475", "C4476", "C4478", "C4480", "C4482", "C4483", "C4491", "C4492", "C4493", "C4494", "C4495", "C4496", "C4497", "C4498", "C4499", "C4509", "C4519", "C4531", "C4542", "C4562", "C4568", "C4569", "C4573", "C4574", "C4575", "C4576", "C4578", "C4582", "C4583", "C4585", "C4586", "C4587", "C4588", "C4589", "C4591", "C4592", "C4593", "C4594", "C4595", "C4598", "C4599"] +helpviewer_keywords: ["C4413", "C4415", "C4416", "C4417", "C4418", "C4419", "C4421", "C4423", "C4424", "C4425", "C4426", "C4427", "C4438", "C4442", "C4443", "C4444", "C4446", "C4447", "C4448", "C4449", "C4450", "C4451", "C4452", "C4453", "C4454", "C4455", "C4466", "C4467", "C4468", "C4472", "C4474", "C4475", "C4476", "C4478", "C4480", "C4482", "C4483", "C4491", "C4492", "C4493", "C4494", "C4495", "C4496", "C4497", "C4498", "C4499", "C4509", "C4519", "C4531", "C4542", "C4562", "C4568", "C4569", "C4573", "C4574", "C4575", "C4576", "C4578", "C4582", "C4583", "C4585", "C4586", "C4587", "C4588", "C4589", "C4591", "C4592", "C4593", "C4594", "C4595", "C4598", "C4599"] --- -# Compiler warnings C4400 Through C4599 +# Microsoft C/C++ compiler warnings C4400 through C4599 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4400-C4599. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -16,182 +15,186 @@ The articles in this section of the documentation explain a subset of the warnin |Warning|Message| |-------------|-------------| -|[Compiler warning (level 1) C4600](compiler-warning-level-1-c4600.md)|#pragma '*macro name*': expected a valid non-empty string| -|[Compiler warning (level 4) C4400](../../error-messages/compiler-warnings/compiler-warning-level-4-c4400.md)|'*type*': const/volatile qualifiers on this type are not supported| -|[Compiler warning (level 1) C4401](../../error-messages/compiler-warnings/compiler-warning-level-1-c4401.md)|'*bitfield*': member is bit field| -|[Compiler warning (level 1) C4402](../../error-messages/compiler-warnings/compiler-warning-level-1-c4402.md)|must use PTR operator| -|[Compiler warning (level 1) C4403](../../error-messages/compiler-warnings/compiler-warning-level-1-c4403.md)|illegal PTR operator| -|[Compiler warning (level 3) C4404](../../error-messages/compiler-warnings/compiler-warning-level-3-c4404.md)|period on directive ignored| -|[Compiler warning (level 1) C4405](../../error-messages/compiler-warnings/compiler-warning-level-1-c4405.md)|'*identifier*': identifier is reserved word| -|[Compiler warning (level 1) C4406](../../error-messages/compiler-warnings/compiler-warning-level-1-c4406.md)|operand on directive ignored| -|[Compiler warning (level 1) C4407](../../error-messages/compiler-warnings/compiler-warning-level-1-c4407.md)|cast between different pointer to member representations, compiler may generate incorrect code| -|[Compiler warning (level 4) C4408](../../error-messages/compiler-warnings/compiler-warning-level-4-c4408.md)|anonymous 'struct|union' did not declare any data members| -|[Compiler warning (level 1) C4409](../../error-messages/compiler-warnings/compiler-warning-level-1-c4409.md)|illegal instruction size| -|[Compiler warning (level 1) C4410](../../error-messages/compiler-warnings/compiler-warning-level-1-c4410.md)|illegal size for operand| -|[Compiler warning (level 1) C4411](../../error-messages/compiler-warnings/compiler-warning-level-1-c4411.md)|'*identifier*': symbol resolves to displacement register| -|[Compiler warning (level 2) C4412](../../error-messages/compiler-warnings/compiler-warning-level-2-c4412.md)|'*function*': function signature contains type '*type*'; C++ objects are unsafe to pass between pure code and mixed or native.| -|Compiler warning C4413|'classname::member': reference member is initialized to a temporary that doesn't persist after the constructor exits| -|[Compiler warning (level 3) C4414](../../error-messages/compiler-warnings/compiler-warning-level-3-c4414.md)|'*function*': short jump to function converted to near| -|Compiler warning (level 1) C4415|duplicate __declspec(code_seg('*name*'))| -|Compiler warning (level 1) C4416|__declspec(code_seg(...)) contains empty string: ignored| -|Compiler warning (level 1) C4417|an explicit template instantiation cannot have __declspec(code_seg(...)): ignored| -|Compiler warning (level 1) C4418|__declspec(code_seg(...)) ignored on an enum| -|Compiler warning (level 3) C4419|'*symbol*' has no effect when applied to private ref class '*class*'.| -|[Compiler warning (level 1) C4420](../../error-messages/compiler-warnings/compiler-warning-level-1-c4420.md)|'*checked_operator*': operator not available, using '*operator*' instead; run-time checking may be compromised| +|[Compiler warning (level 4, Error) C4400](compiler-warning-level-4-c4400.md)|'*type*': `const`/`volatile` qualifiers on this type are not supported| +|[Compiler warning (level 1) C4401](compiler-warning-level-1-c4401.md)|'*bitfield*': member is bit field| +|[Compiler warning (level 1) C4402](compiler-warning-level-1-c4402.md)|must use `PTR` operator| +|[Compiler warning (level 1) C4403](compiler-warning-level-1-c4403.md)|illegal `PTR` operator| +|[Compiler warning (level 3) C4404](compiler-warning-level-3-c4404.md)|period on directive ignored| +|[Compiler warning (level 1) C4405](compiler-warning-level-1-c4405.md)|'*identifier*': identifier is reserved word| +|[Compiler warning (level 1) C4406](compiler-warning-level-1-c4406.md)|operand on directive ignored| +|[Compiler warning (level 1) C4407](compiler-warning-level-1-c4407.md)|cast between different pointer to member representations, compiler may generate incorrect code| +|[Compiler warning (level 4) C4408](compiler-warning-level-4-c4408.md)|anonymous *struct/union* did not declare any data members| +|[Compiler warning (level 1) C4409](compiler-warning-level-1-c4409.md)|illegal instruction size| +|[Compiler warning (level 1) C4410](compiler-warning-level-1-c4410.md)|illegal size for operand| +|[Compiler warning (level 1) C4411](compiler-warning-level-1-c4411.md)|'*identifier*': symbol resolves to displacement register| +|[Compiler warning (level 2, off) C4412](compiler-warning-level-2-c4412.md)|'*function*': function signature contains type '*type*'; C++ objects are unsafe to pass between pure code and mixed or native.| +|Compiler warning (no longer emitted) C4413|'`classname::member`': reference member is initialized to a temporary that doesn't persist after the constructor exits| +|[Compiler warning (level 3) C4414](compiler-warning-level-3-c4414.md)|'*function*': short jump to function converted to near| +|Compiler warning (level 1) C4415|duplicate `__declspec(code_seg(`'*name*'`))`| +|Compiler warning (level 1) C4416|`__declspec(code_seg(...))` contains empty string: ignored| +|Compiler warning (level 1) C4417|an explicit template instantiation cannot have `__declspec(code_seg(...))`: ignored| +|Compiler warning (level 1) C4418|`__declspec(code_seg(...))` ignored on an `enum`| +|Compiler warning (level 3) C4419|'*symbol*' has no effect when applied to `private ref class` '*class*'.| +|[Compiler warning (level 1) C4420](compiler-warning-level-1-c4420.md)|'*checked_operator*': operator not available, using '*operator*' instead; run-time checking may be compromised| |Compiler warning (level 3) C4421|'*parameter*': a reference parameter on a resumable function is potentially unsafe| -|Compiler warning (level 3) C4423|'std::bad_alloc': will be caught by class ('*type*') on line *number*| -|Compiler warning (level 3) C4424|catch for '*type1*' preceded by '*type2*' on line *number*; unpredictable behavior may result if 'std::bad_alloc' is thrown| -|Compiler warning (level 1) C4425|A SAL annotation cannot be applied to '...'| -|Compiler warning (level 1) C4426|optimization flags changed after including header, may be due to #pragma optimize()| +|Compiler warning (level 3) C4423|'`std::bad_alloc`': will be caught by class ('*type*') on line *number*| +|Compiler warning (level 3) C4424|catch for '*type1*' preceded by '*type2*' on line *number*; unpredictable behavior may result if '`std::bad_alloc`' is thrown| +|Compiler warning (level 1) C4425|A SAL annotation cannot be applied to '`...`'| +|Compiler warning (level 1, off) C4426|optimization flags changed after including header, may be due to `#pragma optimize()`| |Compiler warning (level 1) C4427|'*operator*': overflow in constant division, undefined behavior| -|[Compiler warning (level 4) C4429](../../error-messages/compiler-warnings/compiler-warning-level-4-c4429.md)|possible incomplete or improperly formed universal-character-name| -|[Compiler warning (Error) C4430](../../error-messages/compiler-warnings/compiler-warning-c4430.md)|missing type specifier - int assumed. Note: C++ does not support default-int| -|[Compiler warning (level 4) C4431](../../error-messages/compiler-warnings/compiler-warning-level-4-c4431.md)|missing type specifier - int assumed. Note: C no longer supports default-int| -|[Compiler warning (level 4) C4434](../../error-messages/compiler-warnings/compiler-warning-level-4-c4434.md)|a static constructor must have private accessibility; changing to private access| -|[Compiler warning (level 4) C4435](../../error-messages/compiler-warnings/compiler-warning-level-4-c4435.md)|'*derived_class*': Object layout under /vd2 will change due to virtual base '*base_class*'| -|[Compiler warning (level 1) C4436](../../error-messages/compiler-warnings/compiler-warning-level-1-c4436.md)|dynamic\_cast from virtual base '*base_class*' to '*derived_class*' in constructor or destructor could fail with partially-constructed object| -|[Compiler warning (level 4) C4437](../../error-messages/compiler-warnings/compiler-warning-level-4-c4437.md)|dynamic\_cast from virtual base '*base_class*' to '*derived_class*' could fail in some contexts| -|Compiler warning C4438|'*function*': cannot be called safely in /await:clrcompat mode. If '*function*' calls into the CLR it may result in CLR head corruption| -|[Compiler warning (Error) C4439](../../error-messages/compiler-warnings/compiler-warning-c4439.md)|'*function*': function definition with a managed type in the signature must have a __clrcall calling convention| -|[Compiler warning (level 1) C4440](../../error-messages/compiler-warnings/compiler-warning-level-1-c4440.md)|calling convention redefinition from '*calling_convention1*' to '*calling_convenction2*' ignored| -|[Compiler warning (level 1) C4441](../../error-messages/compiler-warnings/compiler-warning-level-1-c4441.md)|calling convention of '*calling_convention1*' ignored; '*calling_convention2*' used instead| -|Compiler warning (level 1) C4442|embedded null terminator in __annotation argument. Value will be truncated.| -|Compiler warning (level 1) C4443|expected pragma parameter to be '0', '1', or '2'| -|Compiler warning (level 3) C4444|'*identifier*': top level '__unaligned' is not implemented in this context| -|[Compiler warning (level 1) C4445](../../error-messages/compiler-warnings/compiler-warning-level-1-c4445.md)|'*function*': in a 'WinRT|managed' type a virtual method cannot be private| +|[Compiler warning (level 4) C4429](compiler-warning-level-4-c4429.md)|possible incomplete or improperly formed universal-character-name| +|[Compiler warning (level 1, Error) C4430](compiler-warning-c4430.md)|missing type specifier - int assumed. Note: C++ does not support default-int| +|[Compiler warning (level 4) C4431](compiler-warning-level-4-c4431.md)|missing type specifier - int assumed. Note: C no longer supports default-int| +|[Compiler warning (level 4) C4434](compiler-warning-level-4-c4434.md)|a static constructor must have private accessibility; changing to private access| +|[Compiler warning (level 4, off) C4435](compiler-warning-level-4-c4435.md)|'*derived_class*': Object layout under `/vd2` will change due to virtual base '*base_class*'| +|[Compiler warning (level 1 and level 4) C4436](compiler-warning-level-1-c4436.md)|`dynamic_cast` from virtual base '*base_class*' to '*derived_class*' in constructor or destructor could fail with partially-constructed object| +|[Compiler warning (level 1 and level 4, off) C4437](compiler-warning-level-4-c4437.md)|`dynamic_cast` from virtual base '*base_class*' to '*derived_class*' could fail in some contexts| +|Compiler warning C4438|'*function*': cannot be called safely in `/await:clrcompat` mode. If '*function*' calls into the CLR it may result in CLR head corruption| +|[Compiler warning (level 1, Error) C4439](compiler-warning-c4439.md)|'*function*': function definition with a managed type in the signature must have a `__clrcall` calling convention| +|[Compiler warning (level 1) C4440](compiler-warning-level-1-c4440.md)|calling convention redefinition from '*calling_convention1*' to '*calling_convenction2*' ignored| +|[Compiler warning (level 1) C4441](compiler-warning-level-1-c4441.md)|calling convention of '*calling_convention1*' ignored; '*calling_convention2*' used instead| +|Compiler warning (level 1) C4442|embedded null terminator in `__annotation` argument. Value will be truncated.| +|Compiler warning (level 1) C4443|expected pragma parameter to be '`0`', '`1`', or '`2`'| +|Compiler warning (level 3, off) C4444|'*identifier*': top level '`__unaligned`' is not implemented in this context| +|[Compiler warning (level 1) C4445](compiler-warning-level-1-c4445.md)|'*function*': in a *WinRT/managed* type a virtual method cannot be private| |Compiler warning (level 1) C4446|'*type*': cannot map member '*name1*' into this type, due to conflict with the type name. The method was renamed to '*name2*'| -|Compiler warning (level 1) C4447|'main' signature found without threading model. Consider using 'int main(Platform::Array\^ args)'.| -|Compiler warning C4448|'*type*1' does not have a default interface specified in metadata. Picking: '*type2*', which may fail at runtime.| -|Compiler warning C4449|'*type*' an unsealed type should be marked as '[WebHostHidden]'| -|Compiler warning C4450|'*type1*' should be marked as '[WebHostHidden]' because it derives from '*type2*'| -|Compiler warning (level 4) C4451|'classname1::member': Usage of ref class 'classname2::member' inside this context can lead to invalid marshaling of object across contexts| -|Compiler warning (level 1) C4452|'*identifier*': public type cannot be at global scope. It must be in a namespace that is a child of the name of the output .winmd file.| -|Compiler warning (level 1) C4453|'*type*': A '[WebHostHidden]' type should not be used on the published surface of a public type that is not '[WebHostHidden]'| -|Compiler warning (level 1) C4454|'*function*' is overloaded by more than the number of input parameters without having [DefaultOverload] specified. Picking '*declaration*' as the default overload| +|Compiler warning (level 1) C4447|'`main`' signature found without threading model. Consider using '`int main(Platform::Array^ args)`'.| +|Compiler warning (level 1) C4448|'*type1*' does not have a default interface specified in metadata. Picking: '*type2*', which may fail at runtime.| +|Compiler warning C4449|'*type*' an unsealed type should be marked as '`[WebHostHidden]`'| +|Compiler warning C4450|'*type1*' should be marked as '`[WebHostHidden]`' because it derives from '*type2*'| +|Compiler warning (level 3 and level 4) C4451|'*classname1::member*': Usage of ref class '*classname2::member*' inside this context can lead to invalid marshaling of object across contexts| +|Compiler warning (level 1, Error) C4452|'*identifier*': public type cannot be at global scope. It must be in a namespace that is a child of the name of the output `.winmd` file.| +|Compiler warning (level 1) C4453|'*type*': A '`[WebHostHidden]`' type should not be used on the published surface of a public type that is not '`[WebHostHidden]`'| +|Compiler warning (level 1) C4454|'*function*' is overloaded by more than the number of input parameters without having `[DefaultOverload]` specified. Picking '*declaration*' as the default overload| |Compiler warning (level 1) C4455|'operator *operator*': literal suffix identifiers that do not start with an underscore are reserved| -|[Compiler warning (level 4) C4456](compiler-warning-level-4-c4456.md)|declaration of '*identifier*' hides previous local declaration| -|[Compiler warning (level 4) C4457](compiler-warning-level-4-c4457.md)|declaration of '*identifier*' hides function parameter| -|[Compiler warning (level 4) C4458](compiler-warning-level-4-c4458.md)|declaration of '*identifier*' hides class member| -|[Compiler warning (level 4) C4459](compiler-warning-level-4-c4459.md)|declaration of '*identifier*' hides global declaration| -|[Compiler warning (level 4) C4460](../../error-messages/compiler-warnings/compiler-warning-level-4-c4460.md)|'WinRT|managed' operator '*operator*', has parameter passed by reference. 'WinRT|managed' operator '*operator*' has different semantics from C++ operator '*cpp_operator*', did you intend to pass by value?| -|[Compiler warning (level 1) C4461](../../error-messages/compiler-warnings/compiler-warning-level-1-c4461.md)|'*classname*': this class has a finalizer '!*finalizer*' but no destructor '~*dtor*'| -|[Compiler warning (level 1, Error) C4462](../../error-messages/compiler-warnings/compiler-warning-level-1-c4462.md)|'*type*' : cannot determine the GUID of the type. Program may fail at runtime.| -|[Compiler warning (level 4) C4463](compiler-warning-level-4-c4463.md)|overflow; assigning '*value*' to bit-field that can only hold values from '*min_value*' to '*max_value*'| -|[Compiler warning (level 4) C4464](../../error-messages/compiler-warnings/compiler-warning-level-4-c4464.md)|relative include path contains '..'| -|[Compiler warning (level 1) C4470](../../error-messages/compiler-warnings/compiler-warning-level-1-c4470.md)|floating-point control pragmas ignored under /clr| -|[Compiler warning (level 4) C4471](compiler-warning-level-4-c4471.md)|'*enumeration*': a forward declaration of an unscoped enumeration must have an underlying type (int assumed)| -|Compiler warning (level 1) C4472|'*identifier*' is a native enum: add an access specifier (private/public) to declare a 'WinRT|managed' enum| +|[Compiler warning (level 1 and level 4) C4456](compiler-warning-level-4-c4456.md)|declaration of '*identifier*' hides previous local declaration| +|[Compiler warning (level 1 and level 4) C4457](compiler-warning-level-4-c4457.md)|declaration of '*identifier*' hides function parameter| +|[Compiler warning (level 1 and level 4) C4458](compiler-warning-level-4-c4458.md)|declaration of '*identifier*' hides class member| +|[Compiler warning (level 1 and level 4) C4459](compiler-warning-level-4-c4459.md)|declaration of '*identifier*' hides global declaration| +|[Compiler warning (level 4) C4460](compiler-warning-level-4-c4460.md)|*WinRT/managed* operator '*operator*', has parameter passed by reference. *WinRT/managed* operator '*operator*' has different semantics from C++ operator '*cpp_operator*', did you intend to pass by value?| +|[Compiler warning (level 1) C4461](compiler-warning-level-1-c4461.md)|'*classname*': this class has a finalizer '`!`*finalizer*' but no destructor '`~`*dtor*'| +|[Compiler warning (level 1, Error) C4462](compiler-warning-level-1-c4462.md)|'*type*' : cannot determine the GUID of the type. Program may fail at runtime.| +|[Compiler warning (level 4) C4463](compiler-warning-level-4-c4463.md)|overflow; assigning *value* to bit-field that can only hold values from *min_value* to *max_value*| +|[Compiler warning (level 4, off) C4464](compiler-warning-level-4-c4464.md)|relative include path contains '`..`'| +|Compiler warning C4466|Could not perform coroutine heap elision| +|Compiler warning (level 1) C4465|'*identifier*': use of dependent template requires `::template`| +|Compiler warning (level 1) C4467|Usage of ATL attributes is deprecated| +|Compiler warning (level 1) C4468|The `[[fallthrough]]` attribute must be followed by a `case` label or a `default` label| +|[Compiler warning (level 1) C4470](compiler-warning-level-1-c4470.md)|floating-point control pragmas ignored under `/clr`| +|[Compiler warning (level 4, off) C4471](compiler-warning-level-4-c4471.md)|'*enumeration*': a forward declaration of an unscoped enumeration must have an underlying type| +|Compiler warning (level 1) C4472|'*identifier*' is a native enum: add an access specifier (private/public) to declare a 'WinRT/managed' enum| |[Compiler warning (level 1) C4473](c4473.md)|'*function*' : not enough arguments passed for format string| |Compiler warning (level 3) C4474|'*function*' : too many arguments passed for format string| |Compiler warning (level 3) C4475|'*function*' : length modifier '*modifier*' cannot be used with type field character '*character*' in format specifier| |Compiler warning (level 3) C4476|'*function*' : unknown type field character '*character*' in format specifier| |[Compiler warning (level 1) C4477](c4477.md)|'*function*' : format string '*string*' requires an argument of type '*type*', but variadic argument *number* has type '*type*'| |Compiler warning (level 1) C4478|'*function*' : positional and non-positional placeholders cannot be mixed in the same format string| -|Compiler warning (Error) C4480|nonstandard extension used: specifying underlying type for enum '*enumeration*'| -|[Compiler warning (level 4) C4481](../../error-messages/compiler-warnings/compiler-warning-level-4-c4481.md)|nonstandard extension used: override specifier '*keyword*'| -|Compiler warning C4482|nonstandard extension used: enum '*enumeration*' used in qualified name| +|Compiler warning (Error) C4480|nonstandard extension used: specifying underlying type for `enum` '*enumeration*'| +|[Compiler warning (level 4, Error) C4481](compiler-warning-level-4-c4481.md)|nonstandard extension used: override specifier '*keyword*'| +|Compiler warning C4482|nonstandard extension used: `enum` '*enumeration*' used in qualified name| |Compiler warning (level 1, Error) C4483|syntax error: expected C++ keyword| -|[Compiler warning (Error) C4484](../../error-messages/compiler-warnings/compiler-warning-c4484.md)|'*override_function*': matches base ref class method '*base_class_function*', but is not marked 'virtual', 'new' or 'override'; 'new' (and not 'virtual') is assumed| -|[Compiler warning (Error) C4485](../../error-messages/compiler-warnings/compiler-warning-c4485.md)|'*override_function*': matches base ref class method '*base_class_function*', but is not marked 'new' or 'override'; 'new' (and 'virtual') is assumed| -|[Compiler warning (level 1) C4486](../../error-messages/compiler-warnings/compiler-warning-level-1-c4486.md)|'*function*': a private virtual method of a ref class or value class should be marked 'sealed'| -|[Compiler warning (level 4) C4487](../../error-messages/compiler-warnings/compiler-warning-level-4-c4487.md)|'*derived_class_function*': matches inherited non-virtual method '*base_class_function*' but is not explicitly marked 'new'| -|[Compiler warning (level 1) C4488](../../error-messages/compiler-warnings/compiler-warning-level-1-c4488.md)|'*function*': requires '*keyword*' keyword to implement the interface method '*interface_method*'| -|[Compiler warning (level 1) C4489](../../error-messages/compiler-warnings/compiler-warning-level-1-c4489.md)|'*specifier*': not allowed on interface method '*method*'; override specifiers are only allowed on ref class and value class methods| -|[Compiler warning (level 1) C4490](../../error-messages/compiler-warnings/compiler-warning-level-1-c4490.md)|'override': incorrect use of override specifier; '*function*' does not match a base ref class method| +|[Compiler warning (level 1, Error) C4484](compiler-warning-c4484.md)|'*override_function*': matches base `ref class` method '*base_class_function*', but is not marked '`virtual`', '`new`' or '`override`'; '`new`' (and not '`virtual`') is assumed| +|[Compiler warning (level 1, Error) C4485](compiler-warning-c4485.md)|'*override_function*': matches base `ref class` method '*base_class_function*', but is not marked '`new`' or '`override`'; '`new`' (and '`virtual`') is assumed| +|[Compiler warning (level 1) C4486](compiler-warning-level-1-c4486.md)|'*function*': a private virtual method of a `ref class` or value class should be marked '`sealed`'| +|[Compiler warning (level 4) C4487](compiler-warning-level-4-c4487.md)|'*derived_class_function*': matches inherited non-virtual method '*base_class_function*' but is not explicitly marked '`new`'| +|[Compiler warning (level 1) C4488](compiler-warning-level-1-c4488.md)|'*function*': requires '*keyword*' keyword to implement the interface method '*interface_method*'| +|[Compiler warning (level 1) C4489](compiler-warning-level-1-c4489.md)|'*specifier*': not allowed on interface method '*method*'; override specifiers are only allowed on ref class and value class methods| +|[Compiler warning (level 1) C4490](compiler-warning-level-1-c4490.md)|'*override*': incorrect use of override specifier; '*function*' does not match a base ref class method| |Compiler warning (level 1) C4491|'*name*': has an illegal IDL version format| -|Compiler warning (level 1, Error) C4492|'*function1*': matches base ref class method '*function2*', but is not marked 'override'| -|Compiler warning (level 3, Error) C4493|delete expression has no effect as the destructor of '*type*' does not have 'public' accessibility| -|Compiler warning (level 1) C4494|'*function*' : Ignoring __declspec(allocator) because the function return type is not a pointer or reference| -|Compiler warning C4495|nonstandard extension '__super' used: replace with explicit base class name| -|Compiler warning C4496|nonstandard extension 'for each' used: replace with ranged-for statement| -|Compiler warning C4497|nonstandard extension 'sealed' used: replace with 'final'| -|Compiler warning C4498|nonstandard extension used: '*extension*'| -|Compiler warning (level 4) C4499|'*function*' : an explicit specialization cannot have a storage class (ignored)"| -|[Compiler warning (level 1) C4502](../../error-messages/compiler-warnings/compiler-warning-level-1-c4502.md)|'*linkage specification*' requires use of keyword 'extern' and must precede all other specifiers| -|[Compiler warning (level 1) C4503](../../error-messages/compiler-warnings/compiler-warning-level-1-c4503.md)|'*identifier*': decorated name length exceeded, name was truncated| -|[Compiler warning (level 4) C4505](../../error-messages/compiler-warnings/compiler-warning-level-4-c4505.md)|'*function*': unreferenced local function has been removed| -|[Compiler warning (level 1) C4506](../../error-messages/compiler-warnings/compiler-warning-level-1-c4506.md)|no definition for inline function '*function*'| -|[Compiler warning (level 1) C4508](../../error-messages/compiler-warnings/compiler-warning-level-1-c4508.md)|'*function*': function should return a value; 'void' return type assumed| +|Compiler warning (level 1, Error) C4492|'*function1*': matches base `ref class` method '*function2*', but is not marked '`override`'| +|Compiler warning (level 3, Error) C4493|delete expression has no effect as the destructor of '*type*' does not have '`public`' accessibility| +|Compiler warning (level 1) C4494|'*function*' : Ignoring `__declspec(allocator)` because the function return type is not a pointer or reference| +|Compiler warning (level 4, off) C4495|nonstandard extension '`__super`' used: replace with explicit base class name| +|Compiler warning (level 4, Error, off) C4496|nonstandard extension '`for each`' used: replace with ranged-for statement| +|Compiler warning (level 4, off) C4497|nonstandard extension '`sealed`' used: replace with '`final`'| +|Compiler warning (level 4, off) C4498|nonstandard extension used: '*extension*'| +|Compiler warning (level 4) C4499|'*function*': an explicit specialization cannot have a storage class (ignored)| +|[Compiler warning (level 1) C4502](compiler-warning-level-1-c4502.md)|'linkage specification' requires use of keyword '`extern`' and must precede all other specifiers| +|[Compiler warning (level 1) C4503](compiler-warning-level-1-c4503.md)|'*identifier*': decorated name length exceeded, name was truncated| +|[Compiler warning (level 4) C4505](compiler-warning-level-4-c4505.md)|'*function*': unreferenced function with internal linkage has been removed| +|[Compiler warning (level 1) C4506](compiler-warning-level-1-c4506.md)|no definition for inline function '*function*'| +|[Compiler warning (level 1) C4508](compiler-warning-level-1-c4508.md)|'*function*': function should return a value; '`void`' return type assumed| |Compiler warning C4509|nonstandard extension used: '*function*' uses SEH and '*object*' has destructor| -|[Compiler warning (level 4) C4510](../../error-messages/compiler-warnings/compiler-warning-level-4-c4510.md)|'*class*': default constructor was implicitly defined as deleted| -|[Compiler warning (level 3) C4511](../../error-messages/compiler-warnings/compiler-warning-level-3-c4511.md)|'*class*': copy constructor was implicitly defined as deleted| -|[Compiler warning (level 4) C4512](../../error-messages/compiler-warnings/compiler-warning-level-4-c4512.md)|'*class*': assignment operator was implicitly defined as deleted| -|[Compiler warning (level 4) C4513](../../error-messages/compiler-warnings/compiler-warning-level-4-c4513.md)|'*class*': destructor was implicitly defined as deleted| -|[Compiler warning (level 4) C4514](../../error-messages/compiler-warnings/compiler-warning-level-4-c4514.md)|'*function*': unreferenced inline function has been removed| -|[Compiler warning (level 4) C4515](../../error-messages/compiler-warnings/compiler-warning-level-4-c4515.md)|'*namespace*': namespace uses itself| -|[Compiler warning (level 4) C4516](../../error-messages/compiler-warnings/compiler-warning-level-4-c4516.md)|'class::symbol': access-declarations are deprecated; member using-declarations provide a better alternative| -|[Compiler warning (level 4) C4517](../../error-messages/compiler-warnings/compiler-warning-level-4-c4517.md)|access-declarations are deprecated; member using-declarations provide a better alternative| -|[Compiler warning (level 1) C4518](../../error-messages/compiler-warnings/compiler-warning-level-1-c4518.md)|'*specifier*': storage-class or type specifier(s) unexpected here; ignored| -|Compiler warning (Error) C4519|default template arguments are only allowed on a class template| -|[Compiler warning (level 3) C4521](../../error-messages/compiler-warnings/compiler-warning-level-3-c4521.md)|'*class*': multiple copy constructors specified| -|[Compiler warning (level 3) C4522](../../error-messages/compiler-warnings/compiler-warning-level-3-c4522.md)|'*class*': multiple assignment operators specified| -|[Compiler warning (level 3) C4523](../../error-messages/compiler-warnings/compiler-warning-level-3-c4523.md)|'*class*': multiple destructors specified| -|[Compiler warning (level 1) C4526](../../error-messages/compiler-warnings/compiler-warning-level-1-c4526.md)|'*function*': static member function cannot override virtual function '*virtual function*' override ignored, virtual function will be hidden| -|[Compiler warning (level 1) C4530](../../error-messages/compiler-warnings/compiler-warning-level-1-c4530.md)|C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc| +|[Compiler warning (level 4) C4510](compiler-warning-level-4-c4510.md)|'*class*': default constructor was implicitly defined as deleted| +|[Compiler warning (level 4) C4511](compiler-warning-level-3-c4511.md)|'*class*': copy constructor was implicitly defined as deleted| +|[Compiler warning (level 4) C4512](compiler-warning-level-4-c4512.md)|'*class*': assignment operator was implicitly defined as deleted| +|[Compiler warning (level 4) C4513](compiler-warning-level-4-c4513.md)|'*class*': destructor was implicitly defined as deleted| +|[Compiler warning (level 4, off) C4514](compiler-warning-level-4-c4514.md)|'*function*': unreferenced inline function has been removed| +|[Compiler warning (level 4) C4515](compiler-warning-level-4-c4515.md)|'*namespace*': namespace uses itself| +|[Compiler warning (level 4) C4516](compiler-warning-level-4-c4516.md)|'*class*::*symbol*': access-declarations are deprecated; member using-declarations provide a better alternative| +|[Compiler warning (level 4) C4517](compiler-warning-level-4-c4517.md)|access-declarations are deprecated; member using-declarations provide a better alternative| +|[Compiler warning (level 1) C4518](compiler-warning-level-1-c4518.md)|'*specifier*': storage-class or type specifier(s) unexpected here; ignored| +|Compiler warning (level1, Error, no longer emitted) C4519|default template arguments are only allowed on a class template| +|[Compiler warning (level 3) C4521](compiler-warning-level-3-c4521.md)|'*class*': multiple copy constructors specified| +|[Compiler warning (level 3) C4522](compiler-warning-level-3-c4522.md)|'*class*': multiple assignment operators specified| +|[Compiler warning (level 3) C4523](compiler-warning-level-3-c4523.md)|'*class*': multiple destructors specified| +|[Compiler warning (level 1) C4526](compiler-warning-level-1-c4526.md)|'*function*': static member function cannot override virtual function '*virtual function*'
override ignored, virtual function will be hidden| +|[Compiler warning (level 1) C4530](compiler-warning-level-1-c4530.md)|C++ exception handler used, but unwind semantics are not enabled. Specify `/EHsc`| |Compiler warning (level 1) C4531|C++ exception handling not available on Windows CE. Use Structured Exception Handling| -|[Compiler warning (level 1) C4532](../../error-messages/compiler-warnings/compiler-warning-level-1-c4532.md)|'continue': jump out of '__finally/finally' block has undefined behavior during termination handling| -|[Compiler warning (level 1) C4533](../../error-messages/compiler-warnings/compiler-warning-level-1-c4533.md)|initialization of '*variable*' is skipped by '*goto label*'| -|[Compiler warning (level 3) C4534](../../error-messages/compiler-warnings/compiler-warning-level-3-c4534.md)|'*constructor*' will not be a default constructor for 'class/struct' '*identifier*' due to the default argument| -|[Compiler warning (level 3) C4535](../../error-messages/compiler-warnings/compiler-warning-level-3-c4535.md)|calling _set_se_translator() requires /EHa| -|[Compiler warning (level 4) C4536](../../error-messages/compiler-warnings/compiler-warning-level-4-c4536.md)|'*typename*': type-name exceeds meta-data limit of '*character_limit*' characters| -|[Compiler warning (level 1) C4537](../../error-messages/compiler-warnings/compiler-warning-level-1-c4537.md)|'*object*': '.' applied to non-UDT type| -|[Compiler warning (level 3) C4538](../../error-messages/compiler-warnings/compiler-warning-level-3-c4538.md)|'*type*': const/volatile qualifiers on this type are not supported| -|[Compiler warning (level 1) C4540](../../error-messages/compiler-warnings/compiler-warning-level-1-c4540.md)|dynamic_cast used to convert to inaccessible or ambiguous base; run-time test will fail ('*type1*' to '*type2*')| -|[Compiler warning (level 1) C4541](../../error-messages/compiler-warnings/compiler-warning-level-1-c4541.md)|'*identifier*' used on polymorphic type '*type*' with /GR-; unpredictable behavior may result| +|[Compiler warning (level 1) C4532](compiler-warning-level-1-c4532.md)|'*continue*': jump out of *__finally/finally* block has undefined behavior during termination handling| +|[Compiler warning (level 1) C4533](compiler-warning-level-1-c4533.md)|initialization of '*variable*' is skipped by '`goto` *label*'| +|[Compiler warning (level 3) C4534](compiler-warning-level-3-c4534.md)|'*constructor*' will not be a default constructor for *class/struct* '*identifier*' due to the default argument| +|[Compiler warning (level 3) C4535](compiler-warning-level-3-c4535.md)|calling `_set_se_translator()` requires `/EHa`| +|[Compiler warning (level 4, off) C4536](compiler-warning-level-4-c4536.md)|'*typename*': type-name exceeds meta-data limit of '*character_limit*' characters| +|[Compiler warning (level 1) C4537](compiler-warning-level-1-c4537.md)|'*object*': '`.`' applied to non-UDT type| +|[Compiler warning (level 3) C4538](compiler-warning-level-3-c4538.md)|'*type*': `const`/`volatile` qualifiers on this type are not supported| +|[Compiler warning (level 1) C4540](compiler-warning-level-1-c4540.md)|`dynamic_cast` used to convert to inaccessible or ambiguous base; run-time test will fail ('*type1*' to '*type2*')| +|[Compiler warning (level 1) C4541](compiler-warning-level-1-c4541.md)|'*identifier*' used on polymorphic type '*type*' with `/GR-`; unpredictable behavior may result| |Compiler warning (level 1) C4542|Skipping generation of merged injected text file, cannot write *filetype* file: '*issue*': *message*| -|[Compiler warning (level 3) C4543](../../error-messages/compiler-warnings/compiler-warning-level-3-c4543.md)|Injected text suppressed by attribute 'no\_injected_text'| -|[Compiler warning (level 1) C4544](../../error-messages/compiler-warnings/compiler-warning-level-1-c4544.md)|'*declaration*': default template argument ignored on this template declaration| -|[Compiler warning (level 1) C4545](../../error-messages/compiler-warnings/compiler-warning-level-1-c4545.md)|expression before comma evaluates to a function which is missing an argument list| -|[Compiler warning (level 1) C4546](../../error-messages/compiler-warnings/compiler-warning-level-1-c4546.md)|function call before comma missing argument list| -|[Compiler warning (level 1) C4547](../../error-messages/compiler-warnings/compiler-warning-level-1-c4547.md)|'*operator*': operator before comma has no effect; expected operator with side-effect| -|[Compiler warning (level 1) C4548](../../error-messages/compiler-warnings/compiler-warning-level-1-c4548.md)|expression before comma has no effect; expected expression with side-effect| -|[Compiler warning (level 1) C4549](../../error-messages/compiler-warnings/compiler-warning-level-1-c4549.md)|'*operator*': operator before comma has no effect; did you intend '*operator*'?| -|[Compiler warning (level 1) C4550](../../error-messages/compiler-warnings/compiler-warning-level-1-c4550.md)|expression evaluates to a function which is missing an argument list| -|[Compiler warning (level 1) C4551](../../error-messages/compiler-warnings/compiler-warning-level-1-c4551.md)|function call missing argument list| -|[Compiler warning (level 1) C4552](../../error-messages/compiler-warnings/compiler-warning-level-1-c4552.md)|'*operator*': operator has no effect; expected operator with side-effect| -|[Compiler warning (level 1) C4553](../../error-messages/compiler-warnings/compiler-warning-level-1-c4553.md)|'*operator*': operator has no effect; did you intend 'operator?| -|[Compiler warning (level 3) C4554](../../error-messages/compiler-warnings/compiler-warning-level-3-c4554.md) C4554|'*operator*': check operator precedence for possible error; use parentheses to clarify precedence| -|[Compiler warning (level 1) C4555](../../error-messages/compiler-warnings/compiler-warning-level-1-c4555.md)|expression has no effect; expected expression with side-effect| -|[Compiler warning (level 1) C4556](../../error-messages/compiler-warnings/compiler-warning-level-1-c4556.md)|value of intrinsic immediate argument '*value*' is out of range '*lower_bound* - *upper_bound*'| -|[Compiler warning (level 3) C4557](../../error-messages/compiler-warnings/compiler-warning-level-3-c4557.md)|'__assume' contains effect '*effect*'| -|[Compiler warning (level 1) C4558](../../error-messages/compiler-warnings/compiler-warning-level-1-c4558.md)|value of operand '*value*' is out of range '*lower_bound* - *upper_bound*'| -|[Compiler warning (level 4) C4559](../../error-messages/compiler-warnings/compiler-warning-level-4-c4559.md)|'*function*': redefinition; the function gains __declspec(modifier)| -|[Compiler warning (level 1) C4561](../../error-messages/compiler-warnings/compiler-warning-level-1-c4561.md)|'__fastcall' incompatible with the '/clr' option: converting to '__stdcall'| -|Compiler warning (level 4) C4562|fully prototyped functions are required with the '/clr' option: converting '()' to '(void)'| -|[Compiler warning (level 4) C4564](../../error-messages/compiler-warnings/compiler-warning-level-4-c4564.md)|method '*method*' of 'class' '*classname*' defines unsupported default parameter '*parameter*'| -|[Compiler warning (level 4) C4565](../../error-messages/compiler-warnings/compiler-warning-level-4-c4565.md)|'*function*': redefinition; the symbol was previously declared with __declspec(modifier)| -|[Compiler warning (level 1) C4566](../../error-messages/compiler-warnings/compiler-warning-level-1-c4566.md)|character represented by universal-character-name '*char*' cannot be represented in the current code page (*number*)| +|[Compiler warning (level 3) C4543](compiler-warning-level-3-c4543.md)|Injected text suppressed by attribute '`no_injected_text`'| +|[Compiler warning (level 1) C4544](compiler-warning-level-1-c4544.md)|the default template argument for '*declaration*' is ignored on this template declaration| +|[Compiler warning (level 1, off) C4545](compiler-warning-level-1-c4545.md)|expression before comma evaluates to a function which is missing an argument list| +|[Compiler warning (level 1, off) C4546](compiler-warning-level-1-c4546.md)|function call before comma missing argument list| +|[Compiler warning (level 1, off) C4547](compiler-warning-level-1-c4547.md)|'*operator*': operator before comma has no effect; expected operator with side-effect| +|[Compiler warning (level 1, off) C4548](compiler-warning-level-1-c4548.md)|expression before comma has no effect; expected expression with side-effect| +|[Compiler warning (level 1, off) C4549](compiler-warning-level-1-c4549.md)|'*operator*': operator before comma has no effect; did you intend '*operator*'?| +|[Compiler warning (level 1) C4550](compiler-warning-level-1-c4550.md)|expression evaluates to a function which is missing an argument list| +|[Compiler warning (level 1) C4551](compiler-warning-level-1-c4551.md)|function call missing argument list| +|[Compiler warning (level 1) C4552](compiler-warning-level-1-c4552.md)|'*operator*': result of expression not used| +|[Compiler warning (level 1) C4553](compiler-warning-level-1-c4553.md)|'*operator*': result of expression not used; did you intend '*operator*'?| +|[Compiler warning (level 3) C4554](compiler-warning-level-3-c4554.md) C4554|'*operator*': check operator precedence for possible error; use parentheses to clarify precedence| +|[Compiler warning (level 1, off) C4555](compiler-warning-level-1-c4555.md)|result of expression not used| +|[Compiler warning (level 1) C4556](compiler-warning-level-1-c4556.md)|value of intrinsic immediate argument '*value*' is out of range '*lower_bound* - *upper_bound*'| +|[Compiler warning (level 3, off) C4557](compiler-warning-level-3-c4557.md)|'`__assume`' contains effect '*effect*'| +|[Compiler warning (level 1) C4558](compiler-warning-level-1-c4558.md)|value of operand '*value*' is out of range '*lower_bound* - *upper_bound*'| +|[Compiler warning (level 4) C4559](compiler-warning-level-4-c4559.md)|'*function*': redefinition; the function gains `__declspec(`*modifier*`)`| +|[Compiler warning (level 1) C4561](compiler-warning-level-1-c4561.md)|'`__fastcall`' incompatible with the '`/clr`' option: converting to '`__stdcall`'| +|Compiler warning (level 4) C4562|fully prototyped functions are required with the '`/clr`' option: converting '`()`' to '`(void)`'| +|[Compiler warning (level 4) C4564](compiler-warning-level-4-c4564.md)|method '*method*' of *class* '*classname*' defines unsupported default parameter '*parameter*'| +|[Compiler warning (level 4) C4565](compiler-warning-level-4-c4565.md)|'*function*': redefinition; the symbol was previously declared with `__declspec(`*modifier*`)`| +|[Compiler warning (level 1) C4566](compiler-warning-level-1-c4566.md)|character represented by universal-character-name '*char*' cannot be represented in the current code page (*number*)| |Compiler warning (level 1) C4568|'*function*': no members match the signature of the explicit override| |Compiler warning (level 3) C4569|'*function*': no members match the signature of the explicit override| -|[Compiler warning (level 3) C4570](../../error-messages/compiler-warnings/compiler-warning-level-3-c4570.md)|'*type*': is not explicitly declared as abstract but has abstract functions| -|[Compiler warning (level 4) C4571](../../error-messages/compiler-warnings/compiler-warning-level-4-c4571.md)|Informational: catch(...) semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught| -|[Compiler warning (level 1) C4572](../../error-messages/compiler-warnings/compiler-warning-level-1-c4572.md)|[ParamArray] attribute is deprecated under /clr, use '...' instead| -|Compiler warning (level 1) C4573|the usage of '*lambda function*' requires the compiler to capture 'this' but the current default capture mode does not allow it| -|Compiler warning (level 4) C4574|'*Identifier*' is defined to be '0': did you mean to use '#if identifier'?| -|Compiler warning (level 1) C4575|'__vectorcall' incompatible with the '/clr' option: converting to '__stdcall'| +|[Compiler warning (level 3) C4570](compiler-warning-level-3-c4570.md)|'*type*': is not explicitly declared as abstract but has abstract functions| +|[Compiler warning (level 4) C4571](compiler-warning-level-4-c4571.md)|Informational: `catch(...)` semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught| +|[Compiler warning (level 1) C4572](compiler-warning-level-1-c4572.md)|`[ParamArray]` attribute is deprecated under `/clr`, use '`...`' instead| +|Compiler warning (level 1, Error) C4573|the usage of '*lambda function*' requires the compiler to capture '`this`' but the current default capture mode does not allow it| +|Compiler warning (level 4, off) C4574|'*Identifier*' is defined to be '`0`': did you mean to use '`#if` *identifier*'?| +|Compiler warning (level 1) C4575|'`__vectorcall`' incompatible with the '`/clr`' option: converting to '`__stdcall`'| |Compiler warning (level 1, Error) C4576|a parenthesized type followed by an initializer list is a non-standard explicit type conversion syntax| -|[Compiler warning (level 1, Off) C4577](../../error-messages/compiler-warnings/compiler-warning-level-1-c4577.md)|'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc| -|Compiler warning (level 1, Error) C4578|'abs': conversion from '*type1*' to '*type2*', possible loss of data (Did you mean to call '*function*' or to #include \?)| -|[Compiler warning (level 3) C4580](../../error-messages/compiler-warnings/compiler-warning-level-3-c4580.md)|[attribute] is deprecated; instead specify System::Attribute or Platform::Metadata as a base class| -|[Compiler warning (level 1) C4581](../../error-messages/compiler-warnings/compiler-warning-level-1-c4581.md)|deprecated behavior: '"*string*"' replaced with '*string*' to process attribute| -|Compiler warning (level 4) C4582|'*type*': constructor is not implicitly called| -|Compiler warning (level 4) C4583|'*type*': destructor is not implicitly called| -|[Compiler warning (level 1) C4584](../../error-messages/compiler-warnings/compiler-warning-level-1-c4584.md)|'*class1*': base-class '*class2*' is already a base-class of '*class3*'| -|Compiler warning (level 1, Error) C4585|'*class*': A WinRT 'public ref class' must either be sealed or derive from an existing unsealed class| -|Compiler warning (level 1, Error) C4586|'*type*': A public type cannot be declared in a top-level namespace called 'Windows'| -|Compiler warning (level 1) C4587|'*anonymous_structure*': behavior change: constructor is no longer implicitly called| -|Compiler warning (level 1) C4588|'*anonymous_structure*': behavior change: destructor is no longer implicitly called| -|Compiler warning (level 1) C4591|'constexpr' call-depth limit of *number* exceeded (/constexpr:depth\)| -|Compiler warning (level 3) C4592|'*function*': 'constexpr' call evaluation failed; function will be called at run-time| -|Compiler warning (level 1) C4593|'*function*': 'constexpr' call evaluation step limit of '*limit*' exceeded; use /constexpr:steps\ to increase the limit| -|Compiler warning (level 3) C4594|'*type*': destructor will not be implicitly called if an exception is thrown| -|Compiler warning (level 1) C4595|'*type*': behavior change: destructor will no longer be implicitly called if an exception is thrown| -|[Compiler warning (level 4) C4596](../../error-messages/compiler-warnings/c4596.md)|'*identifier*': illegal qualified name in member declaration| -|[Compiler warning (error) C4597](c4597.md)|undefined behavior: offsetof applied to a member of a virtual base| -|Compiler warning (level 1 and level 3) C4598|'#include "*header*"': header number *number* in the precompiled header does not match current compilation at that position| -|Compiler warning (level 3) C4599|'*flag* *path*': command line argument number *number* does not match precompiled header| +|[Compiler warning (level 1, Off) C4577](compiler-warning-level-1-c4577.md)|'`noexcept`' used with no exception handling mode specified; termination on exception is not guaranteed. Specify `/EHsc`| +|Compiler warning (level 1, Error) C4578|'`abs`': conversion from '*type1*' to '*type2*', possible loss of data (Did you mean to call '*function*' or to `#include `?)| +|[Compiler warning (level 3) C4580](compiler-warning-level-3-c4580.md)|`[attribute]` is deprecated; instead specify *namespace::*Attribute as a base class| +|[Compiler warning (level 1) C4581](compiler-warning-level-1-c4581.md)|deprecated behavior: '"*string*"' replaced with '*string*' to process attribute| +|Compiler warning (level 4, off) C4582|'*type*': constructor is not implicitly called| +|Compiler warning (level 4, off) C4583|'*type*': destructor is not implicitly called| +|[Compiler warning (level 1) C4584](compiler-warning-level-1-c4584.md)|'*class1*': base-class '*class2*' is already a base-class of '*class3*'| +|Compiler warning (level 1, Error) C4585|'*class*': A WinRT '`public ref class`' must either be sealed or derive from an existing unsealed class| +|Compiler warning (level 1, Error) C4586|'*type*': A public type cannot be declared in a top-level namespace called '`Windows`'| +|Compiler warning (level 1, off) C4587|'*anonymous_structure*': behavior change: constructor is no longer implicitly called| +|Compiler warning (level 1, off) C4588|'*anonymous_structure*': behavior change: destructor is no longer implicitly called| +|Compiler warning (level 4) C4589|Constructor of abstract class '*class1*' ignores initializer for virtual base class '*class2*'| +|Compiler warning (level 1, no longer emitted) C4591|'`constexpr`' call-depth limit of *number* exceeded (`/constexpr:depth`)| +|Compiler warning (level 1, Error) C4592|'*name*': symbol will be dynamically initialized (implementation limitation)| +|Compiler warning (level 1, no longer emitted) C4593|'*function*': '`constexpr`' call evaluation step limit of '*limit*' exceeded; use `/constexpr:steps` to increase the limit| +|Compiler warning (level 1) C4594|class '*name*' can never be instantiated - indirect virtual base class '*name*' is inaccessible| +|Compiler warning (level 3) C4595|'*name*': non-member operator new or delete functions may not be declared inline| +|[Compiler warning (level 4, Error, off) C4596](c4596.md)|'*identifier*': illegal qualified name in member declaration| +|[Compiler warning (error) C4597](c4597.md)|undefined behavior: *message*| +|Compiler warning (level 1 and level 3) C4598|'`#include "`*header*`"`': header number *number* in the precompiled header does not match current compilation at that position| +|Compiler warning (level 3, off) C4599|'*flag* *path*': command line argument number *number* does not match precompiled header| ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ [Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md index d08577ceb2..073da82641 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler warnings C4600 Through C4799" -title: "Compiler warnings C4600 Through C4799" +title: "Microsoft C/C++ compiler (MSVC) warnings C4600 through C4799" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4600 through C4799" ms.date: 05/03/2021 -f1_keywords: ["C4609", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4728", "C4732", "C4751", "C4752", "C4755", "C4757", "C4767", "C4770"] -helpviewer_keywords: ["C4609", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4728", "C4732", "C4751", "C4752", "C4755", "C4757", "C4767", "C4770"] -ms.assetid: 22bd4392-f3be-445c-9f23-6126aebac901 +f1_keywords: ["C4604", "C4605", "C4609", "C4631", "C4642", "C4643", "C4644", "C4647", "C4648", "C4649", "C4654", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4725", "C4726", "C4728", "C4729", "C4732", "C4734", "C4735", "C4736", "C4745", "C4749", "C4751", "C4752", "C4753", "C4755", "C4757", "C4761", "C4767", "C4771", "C4774", "C4775", "C4776", "C4777", "C4778", "C4792", "C4798"] +helpviewer_keywords: ["C4604", "C4605", "C4609", "C4631", "C4642", "C4643", "C4644", "C4647", "C4648", "C4649", "C4654", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4725", "C4726", "C4728", "C4729", "C4732", "C4734", "C4735", "C4736", "C4745", "C4749", "C4751", "C4752", "C4753", "C4755", "C4757", "C4761", "C4767", "C4771", "C4774", "C4775", "C4776", "C4777", "C4778", "C4792", "C4798"] --- -# Compiler warnings C4600 Through C4799 +# Microsoft C/C++ compiler warnings C4600 through C4799 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4600 through C4799. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -16,153 +15,164 @@ The articles in this section of the documentation explain a subset of the warnin |Warning|Message| |-------------|-------------| -|[Compiler warning (level 1) C4600](../../error-messages/compiler-warnings/compiler-warning-level-1-c4600.md)|#pragma 'macro name': expected a valid non-empty string| -|[Compiler warning (level 1) C4602](compiler-warning-level-1-c4602.md)|#pragma pop_macro: 'macro name' no previous #pragma push_macro for this identifier| +|[Compiler warning (level 1) C4600](compiler-warning-level-1-c4600.md)|`#pragma `'*macro name*': expected a valid non-empty string| +|[Compiler warning (level 1) C4602](compiler-warning-level-1-c4602.md)|`#pragma pop_macro: `'*macro name*' no previous `#pragma push_macro` for this identifier| |[Compiler warning (level 1) C4603](compiler-warning-level-1-c4603.md)|'*identifier*': macro is not defined or definition is different after precompiled header use| -|Compiler warning (level 1) C4604|'*type*': passing argument by value across native and managed boundary requires valid copy constructor. Otherwise the runtime behavior is undefined| -|Compiler warning (level 1) C4605|'/D*macro*' specified on current command line, but was not specified when precompiled header was built| -|[Compiler warning (level 1) C4606](../../error-messages/compiler-warnings/compiler-warning-level-1-c4606.md)|#pragma warning: 'warning number' ignored; Code Analysis warnings are not associated with warning levels| -|[Compiler warning (level 3) C4608](../../error-messages/compiler-warnings/compiler-warning-level-3-c4608.md)|'union_member' has already been initialized by another union member in the initializer list, 'union_member'| -|Compiler warning (level 3, Error) C4609|'*type1*' derives from default interface '*interface*' on type '*type2*'. Use a different default interface for '*type1*', or break the base/derived relationship.| -|[Compiler warning (level 4) C4610](../../error-messages/compiler-warnings/compiler-warning-level-4-c4610.md)|object 'class' can never be instantiated - user defined constructor required| -|[Compiler warning (level 4) C4611](../../error-messages/compiler-warnings/compiler-warning-level-4-c4611.md)|interaction between 'function' and C++ object destruction is non-portable| +|Compiler warning (level 1) C4604|'*type*': passing an argument of this type by value across the native/managed boundary requires the type to be move- or copy-constructible. Otherwise, the runtime behavior is undefined| +|Compiler warning (level 1, off) C4605|'`/D`*macro*' specified on current command line, but was not specified when precompiled header was built| +|[Compiler warning (level 1) C4606](compiler-warning-level-1-c4606.md)|`#pragma warning:` '*warning number*' ignored; Code Analysis warnings are not associated with warning levels| +|[Compiler warning (level 3, off) C4608](compiler-warning-level-3-c4608.md)|Initializing multiple members of union: '*member1*' and '*member2*'| +|Compiler warning (level 3, error) C4609|'*type1*' derives from default interface '*interface*' on type '*type2*'. Use a different default interface for '*type1*', or break the base/derived relationship.| +|[Compiler warning (level 4) C4610](compiler-warning-level-4-c4610.md)|*class* '*name*' can never be instantiated - user defined constructor required| +|[Compiler warning (level 4) C4611](compiler-warning-level-4-c4611.md)|interaction between '*function*' and C++ object destruction is non-portable| |[Compiler warning (level 1) C4612](compiler-warning-level-1-c4612.md)|error in include filename| |[Compiler warning (level 1) C4613](compiler-warning-level-1-c4613.md)|'*symbol*': class of segment cannot be changed| -|[Compiler warning (level 1) C4615](../../error-messages/compiler-warnings/compiler-warning-level-1-c4615.md)|#pragma warning: unknown user warning type| -|[Compiler warning (level 1) C4616](../../error-messages/compiler-warnings/compiler-warning-level-1-c4616.md)|#pragma warning: warning number 'number' not a valid compiler warning| -|[Compiler warning (level 1) C4618](../../error-messages/compiler-warnings/compiler-warning-level-1-c4618.md)|pragma parameters included an empty string; pragma ignored| -|[Compiler warning (level 3) C4619](../../error-messages/compiler-warnings/compiler-warning-level-3-c4619.md)|#pragma warning: there is no warning number 'number'| -|[Compiler warning (level 1) C4620](compiler-warning-level-1-c4620.md)|no postfix form of 'operator ++' found for type 'type', using prefix form| -|[Compiler warning (level 1) C4621](../../error-messages/compiler-warnings/compiler-warning-level-1-c4621.md)|no postfix form of 'operator --' found for type 'type', using prefix form| -|[Compiler warning (level 3) C4622](compiler-warning-level-3-c4622.md)|overwriting debug information formed during creation of the precompiled header in object file: 'file'| -|[Compiler warning (level 4) C4623](../../error-messages/compiler-warnings/compiler-warning-level-4-c4623.md)|'derived class': default constructor was implicitly defined as deleted because a base class default constructor is inaccessible or deleted| -|[Compiler warning (level 1) C4624](../../error-messages/compiler-warnings/compiler-warning-level-1-c4624.md)|'derived class': destructor was implicitly defined as deleted because a base class destructor is inaccessible or deleted| -|[Compiler warning (level 4) C4625](../../error-messages/compiler-warnings/compiler-warning-level-4-c4625.md)|'derived class': copy constructor was implicitly defined as deleted because a base class copy constructor is inaccessible or deleted| -|[Compiler warning (level 4) C4626](../../error-messages/compiler-warnings/compiler-warning-level-4-c4626.md)|'derived class': assignment operator was implicitly defined as deleted because a base class assignment operator is inaccessible or deleted| -|[Compiler warning (level 1) C4627](../../error-messages/compiler-warnings/compiler-warning-level-1-c4627.md)|'\': skipped when looking for precompiled header use| -|[Compiler warning (level 1) C4628](../../error-messages/compiler-warnings/compiler-warning-level-1-c4628.md)|digraphs not supported with -Ze. Character sequence 'digraph' not interpreted as alternate token for '%s'| -|[Compiler warning (level 4) C4629](compiler-warning-level-4-c4629.md)|digraph used, character sequence 'digraph' interpreted as token 'char' (insert a space between the two characters if this is not what you intended)| -|[Compiler warning (level 1) C4630](../../error-messages/compiler-warnings/compiler-warning-level-1-c4630.md)|'symbol': 'extern' storage-class specifier illegal on member definition| -|Compiler warning (level 2) C4631|MSXML or XPath unavailable, XML document comments will not be processed. reason| -|[Compiler warning (level 1) C4632](../../error-messages/compiler-warnings/compiler-warning-level-1-c4632.md)|XML document comment: file - access denied: reason| -|[Compiler warning (level 3) C4633](../../error-messages/compiler-warnings/compiler-warning-level-3-c4633.md)|XML document comment target: error: reason| -|[Compiler warning (level 4) C4634](compiler-warning-level-4-c4634.md)|XML document comment target: cannot be applied: reason| -|[Compiler warning (level 3) C4635](compiler-warning-level-3-c4635.md)|XML document comment target: badly-formed XML: reason| -|[Compiler warning (level 3) C4636](compiler-warning-level-3-c4636.md)|XML document comment applied to construct: tag requires non-empty 'attribute' attribute.| -|[Compiler warning (level 3 and level 4) C4637](compiler-warning-level-3-c4637.md)|XML document comment target: \ tag discarded. Reason| -|[Compiler warning (level 3) C4638](compiler-warning-level-3-c4638.md)|XML document comment target: reference to unknown symbol 'symbol'.| -|[Compiler warning (level 4) C4639](../../error-messages/compiler-warnings/compiler-warning-level-4-c4639.md)|MSXML error, XML document comments will not be processed. Reason| -|[Compiler warning (level 3) C4640](../../error-messages/compiler-warnings/compiler-warning-level-3-c4640.md)|'instance': construction of local static object is not thread-safe| -|[Compiler warning (level 3) C4641](../../error-messages/compiler-warnings/compiler-warning-level-3-c4641.md)|XML document comment has an ambiguous cross reference:| -|[Compiler warning (level 3) C4645](compiler-warning-level-3-c4645.md)|function declared with __declspec(noreturn) has a return statement| -|[Compiler warning (level 3) C4646](compiler-warning-level-3-c4646.md)|function declared with __declspec(noreturn) has non-void return type| -|Compiler warning (level 3) C4647|behavior change: __is_pod(*type*) has different value in previous versions| -|Compiler warning (level 3) C4648|standard attribute 'carries_dependency' is ignored| +|[Compiler warning (level 1) C4615](compiler-warning-level-1-c4615.md)|`#pragma warning`: unknown user warning type| +|[Compiler warning (level 1) C4616](compiler-warning-level-1-c4616.md)|`#pragma warning`: warning number '*number*' not a valid compiler warning| +|[Compiler warning (level 1) C4618](compiler-warning-level-1-c4618.md)|pragma parameters included an empty string; pragma ignored| +|[Compiler warning (level 3, off) C4619](compiler-warning-level-3-c4619.md)|`#pragma warning`: there is no warning number '*number*'| +|[Compiler warning (level 1) C4620](compiler-warning-level-1-c4620.md)|no postfix form of '`operator ++`' found for type '*type*', using prefix form| +|[Compiler warning (level 1) C4621](compiler-warning-level-1-c4621.md)|no postfix form of '`operator --`' found for type '*type*', using prefix form| +|[Compiler warning (level 3) C4622](compiler-warning-level-3-c4622.md)|overwriting debug information formed during creation of the precompiled header in object file: '*file*'| +|[Compiler warning (level 1 and level 4, off) C4623](compiler-warning-level-4-c4623.md)|'*derived class*': default constructor was implicitly defined as deleted| +|[Compiler warning (level 1 and level 4) C4624](compiler-warning-level-1-c4624.md)|'*derived class*': destructor was implicitly defined as deleted| +|[Compiler warning (level 1 and level 4, off) C4625](compiler-warning-level-4-c4625.md)|'*derived class*': copy constructor was implicitly defined as deleted| +|[Compiler warning (level 1 and level 4, off) C4626](compiler-warning-level-4-c4626.md)|'*derived class*': assignment operator was implicitly defined as deleted| +|[Compiler warning (level 1, no longer emitted) C4627](compiler-warning-level-1-c4627.md)|'`identifier`': skipped when looking for precompiled header use| +|[Compiler warning (level 1, off) C4628](compiler-warning-level-1-c4628.md)|digraphs not supported with `-Ze`. Character sequence '*digraph*' not interpreted as alternate token for '*token*'| +|[Compiler warning (level 4, no longer emitted) C4629](compiler-warning-level-4-c4629.md)|digraph used, character sequence '*digraph*' interpreted as token '*char*' (insert a space between the two characters if this is not what you intended)| +|[Compiler warning (level 1) C4630](compiler-warning-level-1-c4630.md)|'*symbol*': '*extern*' storage-class specifier illegal on member definition| +|Compiler warning (level 2) C4631|`MSXML` or `XPath` unavailable, XML document comments will not be processed. *reason*| +|[Compiler warning (level 1) C4632](compiler-warning-level-1-c4632.md)|XML document comment: *file* - access denied: *reason*| +|[Compiler warning (level 3 and level 4) C4633](compiler-warning-level-3-c4633.md)|XML document comment *target*: error: *reason*| +|[Compiler warning (level 4) C4634](compiler-warning-level-4-c4634.md)|XML document comment *target*: cannot be applied: *reason*| +|[Compiler warning (level 3 and level 4) C4635](compiler-warning-level-3-c4635.md)|XML document comment *target*: badly-formed XML: *reason*| +|[Compiler warning (level 3) C4636](compiler-warning-level-3-c4636.md)|XML document comment *target*: tag requires non-empty '*attribute*' attribute.| +|[Compiler warning (level 3 and level 4) C4637](compiler-warning-level-3-c4637.md)|XML document comment *target*: `` tag discarded. *Reason*| +|[Compiler warning (level 3) C4638](compiler-warning-level-3-c4638.md)|XML document comment *target*: reference to unknown symbol '*symbol*'.| +|[Compiler warning (level 2) C4639](compiler-warning-level-4-c4639.md)|`MSXML` error, XML document comments will not be processed. *Reason*| +|[Compiler warning (level 3, off) C4640](compiler-warning-level-3-c4640.md)|'*instance*': construction of local static object is not thread-safe| +|[Compiler warning (level 3) C4641](compiler-warning-level-3-c4641.md)|XML document comment has an ambiguous cross reference:| +|Compiler warning (level 1) C4642|'*class*': could not import the constraints for generic parameter '*name*'| +|Compiler warning (level 4, off) C4643|Forward declaring '*identifier*' in namespace std is not permitted by the C++ Standard.| +|Compiler warning (level 1) C4644|usage of the macro-based `offsetof` pattern in constant expressions is non-standard; use `offsetof` defined in the C++ standard library instead| +|[Compiler warning (level 3) C4645](compiler-warning-level-3-c4645.md)|function declared with '`noreturn`' has a return statement| +|[Compiler warning (level 3) C4646](compiler-warning-level-3-c4646.md)|function declared with '`noreturn`' has non-void return type| +|Compiler warning (level 3, off) C4647|behavior change: `__is_pod(`*type*`)` has different value in previous versions| +|Compiler warning (level 3) C4648|standard attribute `[[`*attribute*`]]` is ignored| |Compiler warning (level 3) C4649|attributes are ignored in this context| -|[Compiler warning (level 1) C4650](../../error-messages/compiler-warnings/compiler-warning-level-1-c4650.md)|debugging information not in precompiled header; only global symbols from the header will be available| -|[Compiler warning (level 1) C4651](../../error-messages/compiler-warnings/compiler-warning-level-1-c4651.md)|'definition' specified for precompiled header but not for current compile| -|[Compiler warning (level 1) C4652](../../error-messages/compiler-warnings/compiler-warning-level-1-c4652.md)|compiler option 'option' inconsistent with precompiled header; current command-line option will override that defined in the precompiled header| -|[Compiler warning (level 2) C4653](../../error-messages/compiler-warnings/compiler-warning-level-2-c4653.md)|compiler option 'option' inconsistent with precompiled header; current command-line option ignored| -|Compiler warning (level 4) C4654|Code placed before include of precompiled header line will be ignored. Add code to precompiled header.| -|[Compiler warning (level 1) C4655](compiler-warning-level-1-c4655.md)|'symbol': variable type is new since the latest build, or is defined differently elsewhere| -|[Compiler warning (level 1) C4656](../../error-messages/compiler-warnings/compiler-warning-level-1-c4656.md)|'symbol': data type is new or has changed since the latest build, or is defined differently elsewhere| +|[Compiler warning (level 1) C4650](compiler-warning-level-1-c4650.md)|debugging information not in precompiled header; only global symbols from the header will be available| +|[Compiler warning (level 1) C4651](compiler-warning-level-1-c4651.md)|'`/D`*definition*' specified for precompiled header but not for current compile| +|[Compiler warning (level 1) C4652](compiler-warning-level-1-c4652.md)|compiler option '*option*' inconsistent with precompiled header; current command-line option will override that defined in the precompiled header| +|[Compiler warning (level 1) C4653](compiler-warning-level-2-c4653.md)|compiler option '*option*' inconsistent with precompiled header; current command-line option ignored| +|Compiler warning (level 4, off) C4654|Code placed before include of precompiled header line will be ignored. Add code to precompiled header.| +|[Compiler warning (level 1) C4655](compiler-warning-level-1-c4655.md)|'*symbol*': variable type is new since the latest build, or is defined differently elsewhere| +|[Compiler warning (level 1) C4656](compiler-warning-level-1-c4656.md)|'*symbol*': data type is new or has changed since the latest build, or is defined differently elsewhere| |[Compiler warning (level 1) C4657](compiler-warning-level-1-c4657.md)|expression involves a data type that is new since the latest build| -|Compiler warning (level 1) C4658|'function': function prototype is new since the latest build, or is declared differently elsewhere| -|[Compiler warning (level 1) C4659](../../error-messages/compiler-warnings/compiler-warning-level-1-c4659.md)|#pragma 'pragma': use of reserved segment 'segment' has undefined behavior, use #pragma comment(linker, ...)| -|[Compiler warning (level 1) C4661](../../error-messages/compiler-warnings/compiler-warning-level-1-c4661.md)|'identifier': no suitable definition provided for explicit template instantiation request| -|[Compiler warning (level 1) C4662](compiler-warning-level-1-c4662.md)|explicit instantiation; template-class 'identifier1' has no definition from which to specialize 'identifier2'| -|[Compiler warning (level 1) C4667](../../error-messages/compiler-warnings/compiler-warning-level-1-c4667.md)|'function': no function template defined that matches forced instantiation| -|[Compiler warning (level 4) C4668](../../error-messages/compiler-warnings/compiler-warning-level-4-c4668.md)|'symbol' is not defined as a preprocessor macro, replacing with '0' for 'directive'| -|[Compiler warning (level 1) C4669](../../error-messages/compiler-warnings/compiler-warning-level-1-c4669.md)|'cast': unsafe conversion: 'class' is a managed type object| -|[Compiler warning (level 4) C4670](compiler-warning-level-4-c4670.md)|'identifier': this base class is inaccessible| -|Compiler warning (level 4) C4671|'identifier': the copy constructor is inaccessible| -|[Compiler warning (level 4) C4672](compiler-warning-level-4-c4672.md)|'identifier1': ambiguous. First seen as 'identifier2'| -|[Compiler warning (level 4) C4673](../../error-messages/compiler-warnings/compiler-warning-level-4-c4673.md)|throwing 'identifier' the following types will not be considered at the catch site| -|[Compiler warning (level 1) C4674](compiler-warning-level-1-c4674.md)|'method' should be declared 'static' and have exactly one parameter| -|Compiler warning (level 4) C4676|'%s': the destructor is inaccessible| -|[Compiler warning (level 1) C4677](../../error-messages/compiler-warnings/compiler-warning-level-1-c4677.md)|'function': signature of non-private member contains assembly private type 'private_type'| -|[Compiler warning (level 1) C4678](compiler-warning-level-1-c4678.md)|base class 'base_type' is less accessible than 'derived_type'| -|[Compiler warning (level 1) C4679](../../error-messages/compiler-warnings/compiler-warning-level-1-c4679.md)|'member': could not import member| -|[Compiler warning (level 4) C4680](../../error-messages/compiler-warnings/compiler-warning-level-4-c4680.md)|'class': coclass does not specify a default interface| -|[Compiler warning (level 4) C4681](compiler-warning-level-4-c4681.md)|'class': coclass does not specify a default interface that is an event source| -|[Compiler warning (level 4) C4682](compiler-warning-level-4-c4682.md)|'parameter': no directional parameter attribute specified, defaulting to [in]| -|[Compiler warning (level 1) C4683](../../error-messages/compiler-warnings/compiler-warning-level-1-c4683.md)|'function': event source has an 'out'-parameter; exercise caution when hooking multiple event handlers| -|[Compiler warning (level 1) C4684](../../error-messages/compiler-warnings/compiler-warning-level-1-c4684.md)|'attribute': WARNING!! attribute may cause invalid code generation: use with caution| -|[Compiler warning (level 1) C4685](compiler-warning-level-1-c4685.md)|expecting '> >' found '>>' when parsing template parameters| -|[Compiler warning (level 3) C4686](../../error-messages/compiler-warnings/compiler-warning-level-3-c4686.md)|'user-defined type': possible change in behavior, change in UDT return calling convention| -|[Compiler warning (Error) C4687](../../error-messages/compiler-warnings/compiler-warning-c4687.md)|'class': a sealed abstract class cannot implement an interface 'interface'| -|[Compiler warning (level 1) C4688](../../error-messages/compiler-warnings/compiler-warning-level-1-c4688.md)|'constraint': constraint list contains assembly private type 'type'| -|Compiler warning (level 1) C4689|'%c': unsupported character in #pragma detect_mismatch; #pragma ignored| -|[Compiler warning (level 4) C4690](../../error-messages/compiler-warnings/compiler-warning-level-4-c4690.md)|\[ emitidl( pop ) ]: more pops than pushes| -|[Compiler warning (level 1) C4691](../../error-messages/compiler-warnings/compiler-warning-level-1-c4691.md)|'type': type referenced was expected in unreferenced assembly 'file', type defined in current translation unit used instead| -|[Compiler warning (level 1) C4692](../../error-messages/compiler-warnings/compiler-warning-level-1-c4692.md)|'function': signature of non-private member contains assembly private native type 'native_type'| -|[Compiler warning (level 1, Error) C4693](../../error-messages/compiler-warnings/compiler-warning-c4693.md)|'class': a sealed abstract class cannot have any instance members 'instance member'| -|[Compiler warning (level 1, Error) C4694](../../error-messages/compiler-warnings/compiler-warning-c4694.md)|'class': a sealed abstract class cannot have a base-class 'base_class'| -|Compiler warning (level 1) C4695|#pragma execution_character_set: 'character set' is not a supported argument: currently only 'UTF-8' is supported| -|Compiler warning (level 1) C4696|/ZBvalue1 option out of range; assuming 'value2'| -| [Compiler warning (level 3) C4698](../../error-messages/compiler-warnings/c4698.md) | '*feature*' is for evaluation purposes only and is subject to change or removal in future updates. | -|[Compiler warning (level 1 and level 4) C4700](../../error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md)|uninitialized local variable 'name' used| -|[Compiler warning (level 4) C4701](../../error-messages/compiler-warnings/compiler-warning-level-4-c4701.md)|potentially uninitialized local variable 'name' used| -|[Compiler warning (level 4) C4702](../../error-messages/compiler-warnings/compiler-warning-level-4-c4702.md)|unreachable code| -|[Compiler warning (level 4) C4703](../../error-messages/compiler-warnings/compiler-warning-level-4-c4703.md)|potentially uninitialized local pointer variable '%s' used| -|[Compiler warning (level 4) C4706](../../error-messages/compiler-warnings/compiler-warning-level-4-c4706.md)|assignment within conditional expression| -|[Compiler warning (level 4) C4709](../../error-messages/compiler-warnings/compiler-warning-level-4-c4709.md)|comma operator within array index expression| -|[Compiler warning (level 4) C4710](../../error-messages/compiler-warnings/compiler-warning-level-4-c4710.md)|'function': function not inlined| -|[Compiler warning (level 1) C4711](../../error-messages/compiler-warnings/compiler-warning-level-1-c4711.md)|function 'function' selected for automatic inline expansion| -|[Compiler warning (level 4) C4714](../../error-messages/compiler-warnings/compiler-warning-level-4-c4714.md)|function 'function' marked as __forceinline not inlined| -|[Compiler warning (level 1) C4715](../../error-messages/compiler-warnings/compiler-warning-level-1-c4715.md)|'function': not all control paths return a value| -|[Compiler warning (level 1, Error) C4716](../../error-messages/compiler-warnings/compiler-warning-level-1-c4716.md)|'function': must return a value| -|[Compiler warning (level 1) C4717](../../error-messages/compiler-warnings/compiler-warning-level-1-c4717.md)|'function': recursive on all control paths, function will cause runtime stack overflow| +|Compiler warning (level 1) C4658|'*function*': function prototype is new since the latest build, or is declared differently elsewhere| +|[Compiler warning (level 1) C4659](compiler-warning-level-1-c4659.md)|`#pragma `'*pragma*': use of reserved segment '*segment*' has undefined behavior, use `#pragma comment(linker, ...)`| +|[Compiler warning (level 1) C4661](compiler-warning-level-1-c4661.md)|'*identifier*': no suitable definition provided for explicit template instantiation request| +|[Compiler warning (level 1) C4662](compiler-warning-level-1-c4662.md)|explicit instantiation; template-class '*identifier1*' has no definition from which to specialize '*identifier2*'| +|[Compiler warning (level 1) C4667](compiler-warning-level-1-c4667.md)|'*function*': cannot find a function template that matches the explicit instantiation| +|[Compiler warning (level 4, off) C4668](compiler-warning-level-4-c4668.md)|'*symbol*' is not defined as a preprocessor macro, replacing with '`0`' for '*directive*'| +|[Compiler warning (level 1) C4669](compiler-warning-level-1-c4669.md)|'*cast*': unsafe conversion: '*class*' is a *managed/WinRT* type object| +|[Compiler warning (level 4) C4670](compiler-warning-level-4-c4670.md)|'*identifier*': this base class is inaccessible| +|Compiler warning (level 4) C4671|'*identifier*': the copy constructor is inaccessible| +|[Compiler warning (level 4) C4672](compiler-warning-level-4-c4672.md)|'*identifier1*': ambiguous. First seen as '*identifier2*'| +|[Compiler warning (level 4) C4673](compiler-warning-level-4-c4673.md)|throwing '*identifier*' the following types will not be considered at the catch site| +|[Compiler warning (level 1) C4674](compiler-warning-level-1-c4674.md)|'*method*' should be declared '`static`' and have exactly one parameter| +|Compiler warning (level 4) C4676|'*class*': the destructor is inaccessible| +|[Compiler warning (level 1) C4677](compiler-warning-level-1-c4677.md)|'*function*': signature of non-private member contains assembly private type '*private_type*'| +|[Compiler warning (level 1) C4678](compiler-warning-level-1-c4678.md)|base class '*base_type*' is less accessible than '*derived_type*'| +|[Compiler warning (level 1 and level 4) C4679](compiler-warning-level-1-c4679.md)|'*member*': could not import item or its associated custom attribute| +|[Compiler warning (level 4) C4680](compiler-warning-level-4-c4680.md)|'*class*': `coclass` does not specify a default interface| +|[Compiler warning (level 4) C4681](compiler-warning-level-4-c4681.md)|'*class*': `coclass` does not specify a default interface that is an event source| +|[Compiler warning (level 4, off) C4682](compiler-warning-level-4-c4682.md)|'*parameter*': no directional parameter attribute specified, defaulting to `[in]`| +|[Compiler warning (level 1) C4683](compiler-warning-level-1-c4683.md)|'*function*': event source has an 'out'-parameter; exercise caution when hooking multiple event handlers| +|[Compiler warning (level 1) C4684](compiler-warning-level-1-c4684.md)|'*attribute*': WARNING!! attribute may cause invalid code generation: use with caution| +|[Compiler warning (level 1, no longer emitted) C4685](compiler-warning-level-1-c4685.md)|expecting '`> >`' found '`>>`' when parsing template parameters| +|[Compiler warning (level 3, off) C4686](compiler-warning-level-3-c4686.md)|'*user-defined type*': possible change in behavior, change in UDT return calling convention| +|[Compiler warning (level 1, error) C4687](compiler-warning-c4687.md)|'*class*': a sealed abstract class cannot implement an interface '*interface*'| +|[Compiler warning (level 1) C4688](compiler-warning-level-1-c4688.md)|'*constraint*': constraint list contains assembly private type '*type*'| +|Compiler warning (level 1) C4689|'*character*': unsupported character in `#pragma detect_mismatch`; `#pragma` ignored| +|[Compiler warning (level 4) C4690](compiler-warning-level-4-c4690.md)|`[ emitidl( pop ) ]`: more pops than pushes| +|[Compiler warning (level 1) C4691](compiler-warning-level-1-c4691.md)|'*type*': type referenced was expected in unreferenced *assembly* '*file*', type defined in current translation unit used instead| +|[Compiler warning (level 1, off) C4692](compiler-warning-level-1-c4692.md)|'*function*': signature of non-private member contains assembly private native type '*native_type*'| +|[Compiler warning (level 1, error) C4693](compiler-warning-c4693.md)|'*class*': a sealed abstract class cannot have any instance members '*instance member*'| +|[Compiler warning (level 1, error) C4694](compiler-warning-c4694.md)|'*class*': a sealed abstract class cannot have a base-class '*base_class*'| +|Compiler warning (level 1) C4695|`#pragma execution_character_set`: '*character set*' is not a supported argument: currently only '`UTF-8`' is supported| +|Compiler warning (level 1) C4696|`/ZBvalue1` option out of range; assuming 'value2'| +| [Compiler warning (level 3) C4698](c4698.md) | '*feature*' is for evaluation purposes only and is subject to change or removal in future updates. | +|[Compiler warning (level 1 and level 4) C4700](compiler-warning-level-1-and-level-4-c4700.md)|uninitialized local variable 'name' used| +|[Compiler warning (level 4) C4701](compiler-warning-level-4-c4701.md)|potentially uninitialized local variable 'name' used| +|[Compiler warning (level 4) C4702](compiler-warning-level-4-c4702.md)|unreachable code| +|[Compiler warning (level 4) C4703](compiler-warning-level-4-c4703.md)|potentially uninitialized local pointer variable '*identifier*' used| +|[Compiler warning (level 4) C4706](compiler-warning-level-4-c4706.md)|assignment used as a condition| +|[Compiler warning (level 4) C4709](compiler-warning-level-4-c4709.md)|comma operator within array index expression| +|[Compiler warning (level 4, off) C4710](compiler-warning-level-4-c4710.md)|'*function*': function not inlined| +|[Compiler warning (level 1) C4711](compiler-warning-level-1-c4711.md)|function 'function' selected for automatic inline expansion| +|[Compiler warning (level 4) C4714](compiler-warning-level-4-c4714.md)|function '*function*' marked as `__forceinline` not inlined| +|[Compiler warning (level 1) C4715](compiler-warning-level-1-c4715.md)|'function': not all control paths return a value| +|[Compiler warning (level 1, error) C4716](compiler-warning-level-1-c4716.md)|'function': must return a value| +|[Compiler warning (level 1) C4717](compiler-warning-level-1-c4717.md)|'function': recursive on all control paths, function will cause runtime stack overflow| |[Compiler warning (level 4) C4718](compiler-warning-level-4-c4718.md)|'function call': recursive call has no side effects, deleting| |Compiler warning (level 1) C4719|Double constant found when Qfast specified - use 'f' as a suffix to indicate single precision| |Compiler warning (level 2) C4720|in-line assembler reports: 'message'| |Compiler warning (level 1) C4721|'function': not available as an intrinsic| |[Compiler warning (level 1) C4722](compiler-warning-level-1-c4722.md)|'function': destructor never returns, potential memory leak| -|[Compiler warning (level 3) C4723](../../error-messages/compiler-warnings/compiler-warning-level-3-c4723.md)|potential divide by 0| +|[Compiler warning (level 3) C4723](compiler-warning-level-3-c4723.md)|potential divide by 0| |[Compiler warning (level 3) C4724](compiler-warning-level-3-c4724.md)|potential mod by 0| |Compiler warning (level 3) C4725|instruction may be inaccurate on some Pentiums| -|[Compiler warning (level 1) C4727](../../error-messages/compiler-warnings/compiler-warning-level-1-c4727.md)|PCH named pch_file with same timestamp found in obj_file_1 and obj_file_2. Using first PCH.| -|Compiler warning (level 1) C4728|/Yl- option ignored because PCH reference is required| +|Compiler warning C4726|ARM arch4/4T supports only '`` or ``' with immediate value| +|[Compiler warning (level 1) C4727](compiler-warning-level-1-c4727.md)|PCH named pch_file with same timestamp found in obj_file_1 and obj_file_2. Using first PCH.| +|Compiler warning (level 1) C4728|`/Yl-` option ignored because PCH reference is required| |Compiler warning (level 4) C4729|function too big for flow graph based warnings| -|[Compiler warning (Level 1) C4730](../../error-messages/compiler-warnings/compiler-warning-level-1-c4730.md)Compiler warning (level 1) C4730|'main': mixing _m64 and floating point expressions may result in incorrect code| -|[Compiler warning (Level 1) C4731](../../error-messages/compiler-warnings/compiler-warning-level-1-c4731.md)|'pointer': frame pointer register 'register' modified by inline assembly code| -|Compiler warning (level 1) C4732|intrinsic '%s' is not supported in this architecture| -|[Compiler warning (Level 1) C4733](../../error-messages/compiler-warnings/compiler-warning-level-1-c4733.md)|Inline asm assigning to 'FS:0': handler not registered as safe handler| -|[Compiler warning (Level 3) C4738](../../error-messages/compiler-warnings/compiler-warning-level-3-c4738.md)|storing 32-bit float result in memory, possible loss of performance| +|[Compiler warning (Level 1) C4730](compiler-warning-level-1-c4730.md)|'main': mixing `_m64` and floating point expressions may result in incorrect code| +|[Compiler warning (Level 1) C4731](compiler-warning-level-1-c4731.md)|'pointer': frame pointer register 'register' modified by inline assembly code| +|Compiler warning (level 1) C4732|intrinsic '*identifier*' is not supported in this architecture| +|[Compiler warning (Level 1) C4733](compiler-warning-level-1-c4733.md)|Inline asm assigning to '`FS:0`': handler not registered as safe handler| +|Compiler warning C4734|More than 64k line numbers in a COFF debug info section; stop emitting COFF debug line numbers for module 'module'| +|Compiler warning C4735|`align_function` attribute argument '*argument*' is not a power of two and is not positive. Ignoring attribute| +|Compiler warning C4736|`align_function` attribute ignored because `/Gy` was not specified| +|[Compiler warning (Level 3) C4738](compiler-warning-level-3-c4738.md)|storing 32-bit float result in memory, possible loss of performance| |[Compiler warning (level 1) C4739](compiler-warning-level-1-c4739.md)|reference to variable 'var' exceeds its storage space| -|[Compiler warning (Level 4) C4740](../../error-messages/compiler-warnings/compiler-warning-level-4-c4740.md)|flow in or out of inline asm code suppresses global optimization| -|[Compiler warning (Level 1) C4742](../../error-messages/compiler-warnings/compiler-warning-level-1-c4742.md)|'var' has different alignment in 'file1' and 'file2': number and number| -|[Compiler warning (Level 1) C4743](../../error-messages/compiler-warnings/compiler-warning-level-1-c4743.md)|'type' has different size in 'file1' and 'file2': number and number bytes| -|[Compiler warning (Level 1) C4744](../../error-messages/compiler-warnings/compiler-warning-level-1-c4744.md)|'var' has different type in 'file1' and 'file2': 'type1' and 'type2'| -|[Compiler warning C4746](../../error-messages/compiler-warnings/compiler-warning-c4746.md)|volatile access of '*expression*' is subject to /volatile:\ setting; consider using __iso_volatile_load/store intrinsic functions| -|[Compiler warning (level 1) C4747](../../error-messages/compiler-warnings/compiler-warning-level-1-c4747.md)|Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint| -|Compiler warning (level 4) C4749|conditionally supported: offsetof applied to non-standard-layout type '*type*'| -|[Compiler warning (level 1) C4750](compiler-warning-level-1-c4750.md)|'identifier': function with _alloca() inlined into a loop| -|Compiler warning (level 4) C4751|/arch:AVX does not apply to Intel(R) Streaming SIMD Extensions that are within inline ASM| -|Compiler warning (level 4) C4752|found Intel(R) Advanced Vector Extensions; consider using /arch:AVX| +|[Compiler warning (Level 4) C4740](compiler-warning-level-4-c4740.md)|flow in or out of inline asm code suppresses global optimization| +|[Compiler warning (Level 1) C4742](compiler-warning-level-1-c4742.md)|'var' has different alignment in 'file1' and 'file2': number and number| +|[Compiler warning (Level 1) C4743](compiler-warning-level-1-c4743.md)|'type' has different size in 'file1' and 'file2': number and number bytes| +|[Compiler warning (Level 1) C4744](compiler-warning-level-1-c4744.md)|'var' has different type in 'file1' and 'file2': 'type1' and 'type2'| +|Compiler warning C4745|volatile access of 'name' cannot be honored due to its size| +|[Compiler warning C4746](compiler-warning-c4746.md)|volatile access of '*expression*' is subject to `/volatile:` setting; consider using `__iso_volatile_load/store intrinsic functions`| +|[Compiler warning (level 1) C4747](compiler-warning-level-1-c4747.md)|Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint| +|Compiler warning (level 4, off) C4749|conditionally supported: *message*| +|[Compiler warning (level 1) C4750](compiler-warning-level-1-c4750.md)|'identifier': function with `_alloca()` inlined into a loop| +|Compiler warning (level 4) C4751|`/arch:AVX` does not apply to Intel(R) Streaming SIMD Extensions that are within inline ASM| +|Compiler warning (level 4) C4752|found Intel(R) Advanced Vector Extensions; consider using `/arch:AVX`| +|Compiler warning C4753|Cannot find bounds for pointer; MPX intrinsic function ignored| |[Compiler warning (level 4) C4754](compiler-warning-level-4-c4754.md)|Conversion rules for arithmetic operations in the comparison at %s(%d) mean that one branch cannot be executed. Cast '%s' to '%s' (or similar type of %d bytes).| |Compiler warning C4755|Conversion rules for arithmetic operations in the comparison at %s(%d) mean that one branch cannot be executed in an inlined function. Cast '%s' to '%s' (or similar type of %d bytes).| -|[Compiler warning (level 2) C4756](../../error-messages/compiler-warnings/compiler-warning-level-2-c4756.md)|overflow in constant arithmetic| +|[Compiler warning (level 2) C4756](compiler-warning-level-2-c4756.md)|overflow in constant arithmetic| |Compiler warning (level 4) C4757|subscript is a large unsigned value, did you intend a negative constant?| +|Compiler warning C4761|integral size mismatch in argument; conversion supplied| |[Compiler warning (level 4) C4764](compiler-warning-level-4-c4764.md)|Can not align catch objects to greater than 16 bytes| -|Compiler warning (level 4) C4767|section name '%s' is longer than 8 characters and will be truncated by the linker| -|[Compiler warning (level 3) C4768](c4768.md)|__declspec attributes before linkage specification are ignored| -|Compiler warning C4770|partially validated enum '*name*' used as index| +|Compiler warning (level 4, off) C4767|section name '%s' is longer than 8 characters and will be truncated by the linker| +|[Compiler warning (level 3, off) C4768](c4768.md)|`__declspec` attributes before linkage specification are ignored| +| [Compiler warning (level 4) C4770](./c4770.md) | partially validated enum '*name*' used as index | |Compiler warning C4771|Bounds must be created using a simple pointer; MPX intrinsic function ignored| -|[Compiler warning (level 1, Error) C4772](../../error-messages/compiler-warnings/compiler-warning-level-1-c4772.md)|#import referenced a type from a missing type library; 'missing_type' used as a placeholder| -|Compiler warning (level 4) C4774|'*string*' : format string expected in argument *number* is not a string literal| +|[Compiler warning (level 1, error) C4772](compiler-warning-level-1-c4772.md)|`#import` referenced a type from a missing type library; '*missing_type*' used as a placeholder| +|Compiler warning (level 4, off) C4774|'*string*' : format string expected in argument *number* is not a string literal| |Compiler warning (level 3) C4775|nonstandard extension used in format string '*string*' of function '*function*'| -|Compiler warning (level 1) C4776|'%*character*' is not allowed in the format string of function '*function*'| -|Compiler warning (level 4) C4777|'*function*' : format string '*string*' requires an argument of type '*type1*', but variadic argument *number* has type '*type2*'| +|Compiler warning (level 1) C4776|'`%`*character*' is not allowed in the format string of function '*function*'| +|Compiler warning (level 4, off) C4777|'*function*' : format string '*string*' requires an argument of type '*type1*', but variadic argument *number* has type '*type2*'| |Compiler warning (level 3) C4778|'*function*' : unterminated format string '*string*'| -|[Compiler warning (Level 1) C4788](../../error-messages/compiler-warnings/compiler-warning-level-1-c4788.md)|'identifier': identifier was truncated to 'number' characters| -|[Compiler warning (Level 1) C4789](../../error-messages/compiler-warnings/compiler-warning-level-1-c4789.md)|buffer 'identifier' of size N bytes will be overrun; M bytes will be written starting at offset L| -|Compiler warning (level 2) C4792|function '%s' declared using sysimport and referenced from native code; import library required to link| -|[Compiler warning (level 1 and 3) C4793](../../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md)|'function': function compiled as native: 'reason'| +|[Compiler warning (Level 1) C4788](compiler-warning-level-1-c4788.md)|'identifier': identifier was truncated to 'number' characters| +|[Compiler warning (Level 1) C4789](compiler-warning-level-1-c4789.md)|buffer 'identifier' of size N bytes will be overrun; M bytes will be written starting at offset L| +|Compiler warning (level 2) C4792|function '%s' declared using `sysimport` and referenced from native code; import library required to link| +|[Compiler warning (level 1 and level 3) C4793](compiler-warning-level-1-and-3-c4793.md)|'*function*': function compiled as native:
*reason*| |[Compiler warning (level 1) C4794](compiler-warning-level-1-c4794.md)|segment of thread local storage variable '%s' changed from '%s' to '%s'| -|[Compiler warning (level 1) C4799](../../error-messages/compiler-warnings/compiler-warning-level-1-c4799.md)|function 'function' has no EMMS instruction| +|Compiler warning C4798|native code generated for p-code function 'name' with exception handler or unwind semantics| +|[Compiler warning (level 1) C4799](compiler-warning-level-1-c4799.md)|function '*function*' has no EMMS instruction| ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ +[Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) \ No newline at end of file diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md index d0fc903a71..604fdbc580 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md @@ -1,13 +1,13 @@ --- -title: "Compiler warnings C4800 Through C5999" -description: "Table of Microsoft C/C++ compiler warnings C4800 through C5999." -ms.date: 12/01/2021 -f1_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254"] -helpviewer_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254"] +title: "Microsoft C/C++ compiler (MSVC) warnings C4800 through C4999" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4800 through C4999." +ms.date: 04/17/2024 +f1_keywords: ["C4801", "C4808", "C4809", "C4815", "C4826", "C4827", "C4828", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4849", "C4854", "C4855", "C4856", "C4857", "C4858", "C4859", "C4860", "C4861", "C4869", "C4872", "C4880", "C4881", "C4882", "C4883", "C4907", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4975", "C4976", "C4981", "C4983", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998"] +helpviewer_keywords: ["C4801", "C4808", "C4809", "C4815", "C4826", "C4827", "C4828", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4849", "C4854", "C4855", "C4856", "C4857", "C4858", "C4859", "C4860", "C4861", "C4869", "C4872", "C4880", "C4881", "C4882", "C4883", "C4907", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4975", "C4976", "C4981", "C4983", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998"] --- -# Compiler warnings C4800 through C5999 +# Microsoft C/C++ compiler warnings C4800 through C4999 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4800-C4999. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -16,6 +16,7 @@ The articles in this section of the documentation explain a subset of the warnin | Warning | Message | |--|--| | [Compiler warning (level 4, off) C4800](compiler-warning-level-3-c4800.md) | Implicit conversion from '*type*' to `bool`. Possible information loss | +| Compiler warning C4801 | Return by reference is not verifiable: *message* | | [Compiler warning (level 1) C4803](compiler-warning-level-1-c4803.md) | '*method*': the raise method has a different storage class from that of the event, '*event*' | | [Compiler warning (level 1) C4804](compiler-warning-level-1-c4804.md) | '*operation*': unsafe use of type '`bool`' in operation | | [Compiler warning (level 1) C4805](compiler-warning-level-1-c4805.md) | '*operation*': unsafe mix of type '*type1*' and type '*type2*' in operation | @@ -23,220 +24,127 @@ The articles in this section of the documentation explain a subset of the warnin | [Compiler warning (level 1) C4807](compiler-warning-level-1-c4807.md) | '*operation*': unsafe mix of type '*type1*' and signed bit field of type '*type2*' | | Compiler warning (level 1) C4808 | `case` '*value*' is not a valid value for `switch` condition of type '`bool`' | | Compiler warning (level 1) C4809 | `switch` statement has redundant '`default`' label; all possible '`case`' labels are given | -| [Compiler warning (level 1) C4810](compiler-warning-level-1-c4810.md) | value of `pragma pack(show)` == n | +| [Compiler warning (level 1) C4810](compiler-warning-level-1-c4810.md) | value of `pragma pack(show)` == *number* | | [Compiler warning (level 1) C4811](compiler-warning-level-1-c4811.md) | value of `pragma conform(forScope, show)` == *value* | | [Compiler warning (level 1) C4812](compiler-warning-level-1-c4812.md) | obsolete declaration style: please use '*new_syntax*' instead | | [Compiler warning (level 1) C4813](compiler-warning-level-1-c4813.md) | '*function*': a friend function of a local class must have been previously declared | +| Compiler warning (level 4) C4815 | '*object name*': zero-sized array in stack object will have no elements (unless the object is an aggregate that has been aggregate initialized) | | [Compiler warning (level 4) C4816](compiler-warning-level-4-c4816.md) | '*param*': parameter has a zero-sized array which will be truncated (unless the object is passed by reference) | -| [Compiler warning (level 1) C4817](compiler-warning-level-1-c4817.md) | '*member*': illegal use of '.' to access this member; compiler replaced with '->' | -| [Compiler warning (level 1) C4819](compiler-warning-level-1-c4819.md) | The file contains a character that cannot be represented in the current code page (number). Save the file in Unicode format to prevent data loss | -| [Compiler warning (level 4, off) C4820](compiler-warning-level-4-c4820.md) | '*bytes*' bytes padding added after construct '*member_name*' | +| [Compiler warning (level 1) C4817](compiler-warning-level-1-c4817.md) | '*member*': illegal use of '`.`' to access this member; compiler replaced with '`->`' | +| [Compiler warning (level 1) C4819](compiler-warning-level-1-c4819.md) | The file contains a character that cannot be represented in the current code page (*number*). Save the file in Unicode format to prevent data loss | +| [Compiler warning (level 4, off) C4820](compiler-warning-level-4-c4820.md) |'*type*': '*bytes*' bytes padding added after *class* '*member_name*'| | [Compiler warning (level 1) C4821](compiler-warning-level-1-c4821.md) | Unable to determine Unicode encoding type, please save the file with signature (BOM) | -| [Compiler warning (level 1, off) C4822](compiler-warning-level-1-c4822.md) | 'member function': local class member function does not have a body | +| [Compiler warning (level 4, off) C4822](compiler-warning-level-1-c4822.md) | '*member function*': local class member function does not have a body | | [Compiler warning (level 3) C4823](compiler-warning-level-3-c4823.md) | '*function*': uses pinning pointers but unwind semantics are not enabled. Consider using `/EHa` | | Compiler warning (level 2, off) C4826 | Conversion from '*type1*' to '*type2*' is sign-extended. This may cause unexpected runtime behavior. | | Compiler warning (level 3) C4827 | A public '`ToString`' method with 0 parameters should be marked as `virtual` and `override` | +| Compiler warning (level 1) C4828 | The file contains a character starting at offset `0x`*HexOffset* that is illegal in the current source character set (codepage *codepage*). | | [Compiler warning (level 1) C4829](compiler-warning-level-1-c4829.md) | Possibly incorrect parameters to function `main`. Consider '`int main(Platform::Array^ argv)`' | -| [Compiler warning (level 1) C4834](c4834.md) | discarding return value of function with 'nodiscard' attribute | +| [Compiler warning (level 1) C4834](c4834.md) |discarding return value of function with `[[nodiscard]]` attribute| | [Compiler warning (level 1) C4835](compiler-warning-level-1-c4835.md) | '*variable*': the initializer for exported data will not be run until managed code is first executed in the host assembly | | Compiler warning (level 4, off) C4837 | trigraph detected: '`??`*character*' replaced by '*character*' | | [Compiler warning (level 1) C4838](compiler-warning-level-1-c4838.md) | conversion from '*type_1*' to '*type_2*' requires a narrowing conversion | -| [Compiler warning (level 3) C4839](compiler-warning-level-3-c4839.md) | non-standard use of class '*type*' as an argument to a variadic function | +| [Compiler warning (level 3, error) C4839](compiler-warning-level-3-c4839.md) | non-standard use of class '*type*' as an argument to a variadic function | | [Compiler warning (level 4) C4840](compiler-warning-level-4-c4840.md) | non-portable use of class '*type*' as an argument to a variadic function | -| [Compiler warning (level 4, off) C4841](c4841.md) | non-standard extension used: compound member designator used in `offsetof` | +| [Compiler warning (level 4, off) C4841](c4841.md) | non-standard extension used: *message* | | Compiler warning (level 4, off) C4842 | the result of '`offsetof`' applied to a type using multiple inheritance is not guaranteed to be consistent between compiler releases | | [Compiler warning (level 4) C4843](c4843.md) | '*type1*': An exception handler of reference to array or function type is unreachable, use '*type2*' instead | | Compiler warning (level 1) C4844 | '`export module` *`module_name`*`;`' is now the preferred syntax for declaring a module interface | -| Compiler warning (level 4) C4845 | '`__declspec(no_init_all)`' is ignored if '`/d1initall[0|1|2|3]`' was not specified on the command line | +| Compiler warning (level 4) C4845 |'`__declspec(no_init_all)`' is ignored unless '`/d1initall[0|1|2|3]`' or '`/presetPadding`' is specified on the command line| | Compiler warning (level 4) C4846 | '*value*' is not a valid argument for '`/d1initall`': command-line flag ignored | -| Compiler warning (level 4) C4847 | '`__declspec(no_init_all)`' can only be applied to a function, a class type, or a local variable: ignored | -| Compiler warning (level 1) C4848 | support for standard attribute '`no_unique_address`' in C++17 and earlier is a vendor extension | +| Compiler warning (level 4) C4847 |'*identifier*': '`__declspec(no_init_all)`' can only be applied to a function, a class type, or a local variable: ignored | +| Compiler warning (level 1) C4848 | support for attribute `[[`*attribute*`]]` in C++17 and earlier is a vendor extension | +| Compiler warning (level 1) C4849 | OpenMP '*clause*' clause ignored in '*directive*' directive | | Compiler warning (Level 1, error) C4854 | binding dereferenced null pointer to reference has undefined behavior | -| Compiler warning (level 1, off) C4855 | implicit capture of '`this`' via '`[=]`' is deprecated in 'version' | -| Compiler warning (level 4) C4856 | '*value*' is not a valid argument for '`/d1initAll:FillPattern`' (value must be between 0 and 255). Command-line flag ignored | -| Compiler warning (level 1) C4857 | C++/CLI mode does not support C++ versions newer than C++17; setting language to `/std:c++17` | +| Compiler warning (level 1, off) C4855 | implicit capture of '`this`' via '`[=]`' is deprecated in '*version*' | +| Compiler warning (level 4) C4856 | '*value*' is not a valid argument for '`/d1initAll:FillPattern`' (value must be between `0` and `255`). Command-line flag ignored | +| Compiler warning (level 1) C4857 | C++/CLI mode does not support C++ versions newer than C++*ver*; setting language to `/std:c++`*ver* | +| Compiler warning (level 1) C4858 | discarding return value: *function name* | +| Compiler warning (level 4) C4859 | '*value*' is not a valid argument for '`/presetWarn`': it must be a decimal value > 0. Command-line flag ignored | +| Compiler warning (level 4) C4860 | '*object name*': compiler zero initialized '*number*' bytes of storage | +| Compiler warning (level 4) C4861 | compiler zero initialized '*number*' bytes of storage | | [Compiler warning (level 4) C4866](c4866.md) | compiler may not enforce left-to-right evaluation order for call to *operator_name* | -| [Compiler warning (level 1, error) C4867](compiler-warning-c4867.md) | '*function*': function call missing argument list; use '*call*' to create a pointer to member | -| [Compiler warning (level 4) C4868](compiler-warning-c4868.md) | '_file_(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| [Compiler warning (level 1, error) C4867](compiler-warning-c4867.md) |'*function name*': non-standard syntax; use '`&`' to create a pointer to member| +| [Compiler warning (level 4) C4868](compiler-warning-c4868.md) | '*file*(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| Compiler warning (level 3) C4869 | '`nodiscard`' may only be applied to classes, enumerations, and functions | | Compiler warning (level 2) C4872 | floating point division by zero detected when compiling the call graph for the `concurrency::parallel_for_each` at: '*location*' | -| Compiler warning (level 1) C4880 | casting from 'const *type_1*' to '*type_2*': casting away constness from a pointer or reference may result in undefined behavior in an amp restricted function | +| Compiler warning (level 1) C4880 | casting from '*const type_1*' to '*type_2*': casting away constness from a pointer or reference may result in undefined behavior in an `amp` restricted function | | Compiler warning (level 4) C4881 | the constructor and/or the destructor will not be invoked for `tile_static` variable '*variable-name*' | | Compiler warning (level 1) C4882 | passing functors with non-const call operators to `concurrency::parallel_for_each` is deprecated | +| Compiler warning C4883 | '*function name*': function size suppresses optimizations | | [Compiler warning C4900](compiler-warning-level-1-c4900.md) | Il mismatch between '*tool1*' version '*version1*' and '*tool2*' version '*version2*' | -| [Compiler warning (level 1, off) C4905](compiler-warning-level-1-c4905.md) | wide string literal cast to '`LPSTR`' | -| [Compiler warning (level 1, off) C4906](compiler-warning-level-1-c4906.md) | string literal cast to '`LPWSTR`' | -| [Compiler warning (level 1) C4910](compiler-warning-level-1-c4910.md) | '\: '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation | +| [Compiler warning (level 1, off) C4905](compiler-warning-level-1-c4905.md) | wide string literal cast to '*type*' | +| [Compiler warning (level 1, off) C4906](compiler-warning-level-1-c4906.md) | string literal cast to '*type*' | +| Compiler warning (error) C4907 | multiple calling conventions cannot be specified; last given will be used | +| [Compiler warning (level 1) C4910](compiler-warning-level-1-c4910.md) |'*identifier*': '`__declspec(dllexport)`' and '`extern`' are incompatible on an explicit instantiation| | [Compiler warning (level 1) C4912](compiler-warning-level-1-c4912.md) | '*attribute*': attribute has undefined behavior on a nested UDT | | [Compiler warning (level 4) C4913](compiler-warning-level-4-c4913.md) | user defined binary operator '`,`' exists but no overload could convert all operands, default built-in binary operator '`,`' used | | Compiler warning (level 1) C4916 | in order to have a `dispid`, '*description*': must be introduced by an interface | | [Compiler warning (level 1, off) C4917](compiler-warning-level-1-c4917.md) | '*declarator*': a GUID can only be associated with a class, interface or namespace | | [Compiler warning (level 4) C4918](compiler-warning-level-4-c4918.md) | '*character*': invalid character in pragma optimization list | -| [Compiler warning (level 1) C4920](compiler-warning-level-1-c4920.md) | enum *enum-name* member *member_1*=*value_1* already seen in enum *enum-name* as *member_2*=*value_2* | +| [Compiler warning (level 1) C4920](compiler-warning-level-1-c4920.md) | `enum` *enum-name* member *member_1*`=`*value_1* already seen in `enum` *enum-name* as *member_2*`=`*value_2* | | Compiler warning (level 3) C4921 | '*description*': attribute value '*attribute*' should not be multiply specified | -| [Compiler warning (level 1) C4925](compiler-warning-level-1-c4925.md) | '*method*': dispinterface method cannot be called from script | +| [Compiler warning (level 1) C4925](compiler-warning-level-1-c4925.md) | '*method*': `dispinterface` method cannot be called from script | | [Compiler warning (level 1) C4926](compiler-warning-level-1-c4926.md) | '*identifier*': symbol is already defined: attributes ignored | | [Compiler warning (level 1) C4927](compiler-warning-level-1-c4927.md) | illegal conversion; more than one user-defined conversion has been implicitly applied | | [Compiler warning (level 1, off) C4928](compiler-warning-level-1-c4928.md) | illegal copy-initialization; more than one user-defined conversion has been implicitly applied | -| [Compiler warning (level 1) C4929](compiler-warning-level-1-c4929.md) | '*file*': typelibrary contains a union; ignoring the 'embedded_idl' qualifier | +| [Compiler warning (level 1) C4929](compiler-warning-level-1-c4929.md) | '*file*': `typelibrary` contains a union; ignoring the '`embedded_idl`' qualifier | | [Compiler warning (level 1) C4930](compiler-warning-level-1-c4930.md) | '*prototype*': prototyped function not called (was a variable definition intended?) | | [Compiler warning (level 4, off) C4931](compiler-warning-level-4-c4931.md) | we are assuming the type library was built for *number*-bit pointers | | [Compiler warning (level 4) C4932](compiler-warning-level-4-c4932.md) | `__identifier(`*identifier*`)` and `__identifier(`*identifier*`)` are indistinguishable | | Compiler warning (level 1) C4934 | '`__delegate(multicast)`' is deprecated, use '`__delegate`' instead | | [Compiler warning (level 1) C4935](compiler-warning-level-1-c4935.md) | assembly access specifier modified from '*access*' | -| [Compiler warning (level 1, Error) C4936](compiler-warning-c4936.md) | this __declspec is supported only when compiled with `/clr` or `/clr:pure` | +| [Compiler warning (level 1, error) C4936](compiler-warning-c4936.md) | this `__declspec` is supported only when compiled with `/clr` or `/clr:pure` | | [Compiler warning (level 4) C4937](compiler-warning-level-4-c4937.md) | '*text1*' and '*text2*' are indistinguishable as arguments to '*directive*' | | [Compiler warning (level 4) C4938](compiler-warning-level-4-c4938.md) | '*var*': Floating point reduction variable may cause inconsistent results under `/fp:strict` or `#pragma fenv_access` | -| [Compiler warning C4939](compiler-warning-level-1-c4939.md) | #pragma vtordisp is deprecated and will be removed in a future release of Visual C++ | +| [Compiler warning (level 1) C4939](compiler-warning-level-1-c4939.md) | `#pragma vtordisp` is deprecated and will be removed in a future release of Visual C++ | | [Compiler warning (level 1) C4944](compiler-warning-level-1-c4944.md) | '*symbol*': cannot import symbol from '*assembly1*': as '*symbol*' already exists in the current scope | | [Compiler warning (level 1) C4945](compiler-warning-level-1-c4945.md) | '*symbol*': cannot import symbol from '*assembly1*': as '*symbol*' has already been imported from another assembly '*assembly2*' | | [Compiler warning (level 1, off) C4946](compiler-warning-level-1-c4946.md) | `reinterpret_cast` used between related classes: '*class1*' and '*class2*' | | [Compiler warning (level 1) C4947](compiler-warning-level-1-c4947.md) | '*type_or_member*': marked as obsolete | | [Compiler warning (level 2) C4948](compiler-warning-level-2-c4948.md) | return type of '*accessor*' does not match the last parameter type of the corresponding setter | -| [Compiler warning (level 1 and level 4) C4949](compiler-warning-level-1-and-level-4-c4949.md) | pragmas '`managed`' and '`unmanaged`' are meaningful only when compiled with '`/clr[:option]`' | -| [Compiler warning (level 1, Error) C4950](compiler-warning-c4950.md) | '*type_or_member*': marked as obsolete | +| [Compiler warning (level 1 and level 4) C4949](compiler-warning-level-1-and-level-4-c4949.md) | `pragma` '*pragma*' is meaningful only when compiled with '`/clr[:option]`'| +| [Compiler warning (level 1, error) C4950](compiler-warning-c4950.md) | '*type_or_member*': marked as obsolete | | [Compiler warning (level 1) C4951](compiler-warning-level-1-c4951.md) | '*function*' has been edited since profile data was collected, function profile data not used | | [Compiler warning (level 1) C4952](compiler-warning-level-1-c4952.md) | '*function*': no profile data found in program database '*pgd-file*' | | [Compiler warning (level 1) C4953](compiler-warning-level-1-c4953.md) | Inlinee '*function*' has been edited since profile data was collected, profile data not used | | Compiler warning C4954 | '*function*': not profiled (contains `__int64` switch expression) | | Compiler warning C4955 | '*import2*': import ignored; already imported from '*import1*' | -| [Compiler warning (level 1, Error) C4956](compiler-warning-c4956.md) | '*type*': this type is not verifiable | -| [Compiler warning (level 1, Error) C4957](compiler-warning-c4957.md) | '*cast*': explicit cast from '*cast_from*' to '*cast_to*' is not verifiable | -| [Compiler warning (level 1, Error) C4958](compiler-warning-c4958.md) | '*operation*': pointer arithmetic is not verifiable | -| [Compiler warning (level 1, Error) C4959](compiler-warning-c4959.md) | cannot define unmanaged type '*type*' in `/clr:safe` because accessing its members yields unverifiable code | +| [Compiler warning (level 1, error) C4956](compiler-warning-c4956.md) | '*type*': this type is not verifiable | +| [Compiler warning (level 1, error) C4957](compiler-warning-c4957.md) | '*cast*': explicit cast from '*cast_from*' to '*cast_to*' is not verifiable | +| [Compiler warning (level 1, error) C4958](compiler-warning-c4958.md) | '*operation*': pointer arithmetic is not verifiable | +| [Compiler warning (level 1, error) C4959](compiler-warning-c4959.md) | cannot define unmanaged *type* '*identifier*' in `/clr:safe` because accessing its members yields unverifiable code | | [Compiler warning (level 4) C4960](compiler-warning-level-4-c4960.md) | '*function*' is too big to be profiled | | [Compiler warning (level 1) C4961](compiler-warning-c4961.md) | No profile data was merged into '*pgd-file*', profile-guided optimizations disabled | | [Compiler warning (level 4, off) C4962](compiler-warning-c4962.md) | '*function*': Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent | | Compiler warning (level 1) C4963 | '*description*': no profile data found; different compiler options were used in instrumented build | | [Compiler warning (level 1) C4964](compiler-warning-level-1-c4964.md) | No optimization options were specified; profile info will not be collected | -| [Compiler warning (level 1) C4965](compiler-warning-level-1-c4965.md) | implicit box of integer 0; use nullptr or explicit cast | +| [Compiler warning (level 1) C4965](compiler-warning-level-1-c4965.md) | implicit box of integer `0`; use `nullptr` or explicit cast | | Compiler warning (level 1) C4966 | '*function*' has `__code_seg` annotation with unsupported segment name, annotation ignored | | Compiler warning C4970 | delegate constructor: target object ignored since '*type*' is static | -| Compiler warning (level 1) C4971 | Argument order: \, \ for delegate constructor is deprecated, use \, \ | -| [Compiler warning (level 1, Error) C4972](compiler-warning-c4972.md) | Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable | +| Compiler warning (level 1, no longer emitted) C4971 |Argument order: ``, `` for delegate constructor is deprecated, use ``, ``| +| [Compiler warning (level 1, error) C4972](compiler-warning-c4972.md) | Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable | | Compiler warning (level 1) C4973 | '*symbol*': marked as deprecated | | Compiler warning (level 1) C4974 | '*symbol*': marked as deprecated | -| Compiler warning (level 3) C4981 | Warbird: function '*function*' marked as __forceinline not inlined because it contains exception semantics | -| [Compiler warning C4984](compiler-warning-c4984.md) | '`if constexpr`' is a C++17 language extension | -| [Compiler warning (level 4) C4985](compiler-warning-level-4-c4985.md) | '*symbol_name*': attributes not present on previous declaration. | -| [Compiler warning (level 4, off) C4986](compiler-warning-c4986.md) | '*declaration*': exception specification does not match previous declaration | +| Compiler warning (level 1) C4975 | modopt '[*modifier*]' was ignored for formal parameter '*parameter*' | +| Compiler warning (level 1) C4976 | invalid value '*value*' for '`/W`'; assuming '`1`' | +| Compiler warning (level 3) C4981 | Warbird: function '*function*' marked as `__forceinline` not inlined because it contains exception semantics | +| Compiler warning (level 3) C4983 | '`/analyze:sarif:hashname`' ignored because the argument to '`/analyze:log`' is a single file rather than a directory | +| [Compiler warning (level 1) C4984](compiler-warning-c4984.md) | '`if constexpr`' is a C++17 language extension | +| [Compiler warning (level 3) C4985](compiler-warning-level-4-c4985.md) | '*symbol_name*': attributes not present on previous declaration. | +| [Compiler warning (level 2 and level 4, off) C4986](compiler-warning-c4986.md) | '*declaration*': exception specification does not match previous declaration | | Compiler warning (level 4, off) C4987 | nonstandard extension used: '`throw (...)`' | | Compiler warning (level 4, off) C4988 | '*variable*': variable declared outside class/function scope | | Compiler warning (level 4) C4989 | '*type*': type has conflicting definitions. | | Compiler warning (level 3) C4990 | Warbird: *message* | | Compiler warning (level 3) C4991 | Warbird: function '*function*' marked as `__forceinline` not inlined because protection level of inlinee is greater than the parent | | Compiler warning (level 3) C4992 | Warbird: function '*function-name*' marked as `__forceinline` not inlined because it contains inline assembly which cannot be protected | -| [Compiler warning (level 3) C4995](compiler-warning-level-3-c4995.md) | '*function*': name was marked as #pragma deprecated | -| [Compiler warning (level 3) C4996](compiler-warning-level-3-c4996.md) | '*deprecated-declaration*': *deprecation-message* (or "was declared deprecated") | -| [Compiler warning (level 1) C4997](compiler-warning-level-1-c4997.md) | '*class*': coclass does not implement a COM interface or pseudo-interface | +| [Compiler warning (level 3) C4995](compiler-warning-level-3-c4995.md) | '*function*': name was marked as `#pragma deprecated` | +| [Compiler warning (level 3) C4996](compiler-warning-level-3-c4996.md) | '*deprecated-declaration*': *deprecation-message* | +| [Compiler warning (level 1) C4997](compiler-warning-level-1-c4997.md) | '*class*': `coclass` does not implement a COM interface or pseudo-interface | | Compiler warning (level 1) C4998 | EXPECTATION FAILED: *expectation*(*value*) | -| [Compiler warning C4999](compiler-warning-level-1-c4999.md) | UNKNOWN WARNING Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information | -| Compiler warning C5022 | '*type*': multiple move constructors specified | -| Compiler warning C5023 | '*type*': multiple move assignment operators specified | -| Compiler warning (level 4, off) C5024 | '*type*': move constructor was implicitly defined as deleted | -| Compiler warning (level 4, off) C5025 | '*type*': move assignment operator was implicitly defined as deleted | -| Compiler warning (level 1 and level 4, off) C5026 | '*type*': move constructor was implicitly defined as deleted | -| Compiler warning (level 1 and level 4, off) C5027 | '*type*': move assignment operator was implicitly defined as deleted | -| Compiler warning (level 1) C5028 | '*name*': Alignment specified in prior declaration (*number*) not specified in definition | -| Compiler warning (level 4, off) C5029 | nonstandard extension used: alignment attributes in C++ apply to variables, data members and tag types only | -| Compiler warning (level 3) C5030 | attribute '*attribute-name*' is not recognized | -| Compiler warning (level 4, off) C5031 | `#pragma warning(pop)`: likely mismatch, popping warning state pushed in different file | -| Compiler warning (level 4, off) C5032 | detected `#pragma warning(push)` with no corresponding `#pragma warning(pop)` | -| [Compiler warning (level 1) C5033](c5033.md) | '*storage-class*' is no longer a supported storage class | -| Compiler warning (level 5, off) C5034 | use of intrinsic '*intrinsic*' causes function *function-name* to be compiled as guest code | -| Compiler warning (level 5, off) C5035 | use of feature '*feature*' causes function *function-name* to be compiled as guest code | -| Compiler warning (level 1) C5036 | varargs function pointer conversion when compiling with `/hybrid:x86arm64` '*type1*' to '*type2*' | -| [Compiler warning (error) C5037](c5037.md) | '*member-function*': an out-of-line definition of a member of a class template cannot have default arguments | -| [Compiler warning (level 4, off) C5038](c5038.md) | data member '*member1*' will be initialized after data member '*member2*' | -| Compiler warning (level 4, off) C5039 | '*function*': pointer or reference to potentially throwing function passed to `extern C` function under `-EHc`. Undefined behavior may occur if this function throws an exception. | -| Compiler warning (level 3) C5040 | dynamic exception specifications are valid only in C++14 and earlier; treating as noexcept(false) | -| Compiler warning (level 1, off) C5041 | '*definition*': out-of-line definition for constexpr static data member is not needed and is deprecated in C++17 | -| Compiler warning (level 3, off) C5042 | '*declaration*': function declarations at block scope cannot be specified 'inline' in standard C++; remove 'inline' specifier | -| Compiler warning (level 2) C5043 | '*specification*': exception specification does not match previous declaration | -| Compiler warning (level 4) C5044 | An argument to command-line option *option-name* points to a path '*path-name*' that does not exist | -| [Compiler warning (level 4) C5045](c5045.md) | Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified | -| [Compiler warning (level 2) C5046](c5046.md) | '*function*': Symbol involving type with internal linkage not defined | -| Compiler warning (level 1) C5047 | use of nonstandard `__if_exists` with modules is not supported | -| Compiler warning (level 1) C5048 | Use of macro '*macroname*' may result in non-deterministic output | -| Compiler warning (level 1) C5049 | '*string*': Embedding a full path may result in machine-dependent output | -| [Compiler warning (level 1) C5050](c5050.md) | Possible incompatible environment while importing module '*module_name*': *issue* | -| Compiler warning (level 1) C5051 | attribute 'attribute-name' requires at least 'standard-level'; ignored | -| Compiler warning (level 3, off) C5052 | Keyword 'keyword-name' was introduced in C++\ and requires use of the 'option-name' command-line option | -| Compiler warning (level 1) C5053 | support for '`explicit()`' in C++17 and earlier is a vendor extension | -| Compiler warning (level 4) C5054 | operator 'operator-name': deprecated between enumerations of different types | -| Compiler warning (level 1) C5055 | operator 'operator-name': deprecated between enumerations and floating-point types | -| Compiler warning (level 1) C5056 | operator 'operator-name': deprecated for array types | -| Compiler warning (level 1) C5057 | header unit reference to 'name' already exists. Ignoring header unit 'header-name' | -| Compiler warning (level 1) C5058 | file system error: cannot find header file 'file-name' for header unit 'unit-name' | -| Compiler warning C5059 | runtime checks and address sanitizer is not currently supported - disabling runtime checks | -| Compiler warning (level 4) C5060 | `/Qpar` and address sanitizer not currently supported - disabling auto-parallelization | -| Compiler warning (level 4) C5061 | the use of a comma operator as a subscript expression has been deprecated | -| Compiler warning (level 4) C5062 | enum direct list initialization between 'type-1' and 'type-2' is no longer supported | -| Compiler warning (level 1) C5063 | '`std::is_constant_evaluated`' always evaluates to true in manifestly constant-evaluated expressions | -| Compiler warning (level 1) C5100 | `__VA_ARGS__` is reserved for use in variadic macros | -| Compiler warning (level 1) C5101 | use of preprocessor directive in function-like macro argument list is undefined behavior | -| Compiler warning (level 1) C5102 | ignoring invalid command-line macro definition '*value*' | -| Compiler warning (level 1) C5103 | pasting '*token1*' and '*token2*' does not result in a valid preprocessing token | -| Compiler warning (level 1) C5104 | found '*string1*`#`*string2*' in macro replacement list, did you mean '*string1*`""#`*string2*'? | -| [Compiler warning (level 1) C5105](c5105.md) | macro expansion producing 'defined' has undefined behavior | -| Compiler warning (level 1) C5106 | macro redefined with different parameter names | -| Compiler warning (level 1) C5107 | missing terminating '*char*' character | -| Compiler warning (level 1) C5108 | `__VA_OPT__` is reserved for use in variadic macros | -| Compiler warning (level 1) C5200 | feature 'feature-name' requires compiler flag 'option-name' | -| Compiler warning (level 1) C5201 | a module declaration can appear only at the start of a translation unit unless a global module fragment is used | -| Compiler warning (level 1) C5202 | a global module fragment can only contain preprocessor directives | -| Compiler warning (level 1) C5203 | a parenthesized declarator name after 'explicit' will be considered an explicit-specifier in C++20 | -| Compiler warning (level 3, off) C5204 | 'type-name': class has virtual functions, but its trivial destructor is not virtual; instances of objects derived from this class may not be destructed correctly | -| Compiler warning (level 4) C5205 | delete of an abstract class 'type-name' that has a non-virtual destructor results in undefined behavior | -| Compiler warning (level 3) C5206 | deduced return types for coroutines is a non-standard extension | -| Compiler warning (level 1) C5207 | the simple requirement asserts the validity of expression '`e->id`'. Did you mean '`{ e } -> id`'? You can suppress the warning using '`{ e->id }`' | -| [Compiler warning (level 1) C5208](c5208.md) | unnamed class used in `typedef` name cannot declare members other than non-static data members, member enumerations, or member classes | -| Compiler warning (level 1) C5209 | the C++20 syntax for an init-capture has changed to '& ...opt identifier initializer' | -| Compiler warning (level 1) C5210 | '*name*' is not a valid header unit reference; ignoring | -| Compiler warning (level 1) C5212 | '*name*' is not a valid named reference; treating as reference to file | -| Compiler warning (level 1) C5213 | '*name*' named reference is treated as a named partition but the name is not specified; treating as reference to file | -| Compiler warning (level 4, off) C5214 | applying '*modifier*' to an operand with a volatile qualified type is deprecated in C++20 | -| Compiler warning (level 4, off) C5215 | '*name*' a function parameter with a volatile qualified type is deprecated in C++20 | -| Compiler warning (level 4, off) C5216 | '*name*' a volatile qualified return type is deprecated in C++20 | -| Compiler warning (level 4, off) C5217 | a structured binding declaration that includes volatile is deprecated in C++20 | -| Compiler warning (level 1) C5218 | destroying delete may not behave as intended when non-conforming switches '`/Zc:sizedDealloc-`' or '`/Zc:alignedNew-`' are used | -| Compiler warning (level 2, off) C5219 | implicit conversion from '*type-1*' to '*type-2*', possible loss of data | -| Compiler warning (level 4, off) C5220 | '*name*': a non-static data member with a volatile qualified type no longer implies that compiler generated copy/move constructors and copy/move assignment operators are not trivial | -| Compiler warning (level 1) C5221 | xfg::rename is deprecated. | -| Compiler warning (level 3) C5222 | '*attribute-name*': all unscoped attribute names are reserved for future standardization | -| Compiler warning (level 3) C5223 | all attribute names in the attribute namespace 'msvc' are reserved for the implementation | -| Compiler warning (level 3) C5224 | all attribute names in the attribute namespace '*namespace-name*' are reserved for future standardization | -| Compiler warning (level 1) C5225 | '*symbol*': exported inline function defined in a private module fragment is a non-standard extension | -| Compiler warning (level 1) C5226 | '*symbol*': exported template defined in private module fragment has no reachable instantiation | -| Compiler warning (level 4) C5227 | nonstandard extension, resolved '*symbol*' to '*value*' which is not visible with `/permissive-` on. | -| Compiler warning (level 4) C5228 | nonstandard extension, '*identifier*' resolved to a member of a dependent base. This lookup is not allowed under `/permissive-`. | -| Compiler warning (level 4) C5229 | nonstandard extension, the hidden friend function '*function-name*' was found by name lookup which isn't allowed under `/permissive-`. | -| Compiler warning C5230 | nonstandard extension, '*identifier*' was resolved to '*symbol-1*' under `/permissive`. Under `/permissive-` it would resolve to '*symbol-2*'. | -| Compiler warning (level 3) C5231 | the expression '`co_await promise.final_suspend()`' must be non-throwing | -| Compiler warning (level 1) C5232 | in C++20 this comparison calls '*name*' recursively | -| Compiler warning (level 4, off) C5233 | explicit lambda capture '*identifier*' is not used | -| Compiler warning (level 1) C5234 | file system error: '*filename*' is not a valid header-name; ignoring | -| Compiler warning (level 1) C5235 | JSON parse error: *message*; ignoring '*filename*' | -| Compiler warning (level 1) C5236 | JSON ill-formed: *message*; ignoring '*filename*' | -| Compiler warning (level 1) C5237 | cannot resolve header unit entry '*name*' to a header file in '*filename*'; ignoring entry | -| Compiler warning (level 1) C5238 | file system error: cannot open '*filename*' for reading; ignoring | -| Compiler warning (level 4) C5239 | '*symbol*': potentially-throwing function called from a function declared `__declspec(nothrow)`. Undefined behavior may occur if an exception is thrown. | -| Compiler warning (level 4) C5240 | '*name*': attribute is ignored in this syntactic position | -| Compiler warning (level 1) C5241 | '`/exportHeader`' usage to lookup header-name is deprecated; prefer '/headerName:name value=filename' | -| Compiler warning (level 1) C5242 | syntax error in pragma '*identifier*' | -| [Compiler warning (level 1, off) C5243](c5243.md) | '*type-name*': using incomplete class 'class-name' can cause potential one definition rule violation due to ABI limitation | -| Compiler warning (level 1) C5244 | '#include \<*filename*>' in the purview of module '*module-name-1*' appears erroneous. Consider moving that directive before the module declaration, or replace the textual inclusion with 'import \<*module-name-2*>;'. | -| Compiler warning (level 4, off) C5245 | '*function*': unreferenced function with internal linkage has been removed | -| Compiler warning (level 1, off) C5246 | '*member*': the initialization of a subobject should be wrapped in braces | -| [Compiler warning (level 1, off) C5247](c5247.md) | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | -| [Compiler warning (level 1, off) C5248](c5248.md) | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified. | -| Compiler warning (level 1, off) C5249 | '*bitfield*' of type '*enumeration_name*' has named enumerators with values that cannot be represented in the given bit field width of '*bitfield_width*'. 17.0 | -| Compiler warning (level 3, off) C5250 | '*function_name*': intrinsic function not declared. 17.0 | -| Compiler warning (level 4, off) C5251 | *segment-name* changed after including header 17.1 | -| Compiler warning (level 4) C5252 | Multiple different types resulted in the same XFG type-hash *hash-value*; the PDB will only record information for one of them 17.0 | -| Compiler warning (level 4) C5253 | a non-local lambda cannot have a capture default 17.1 | -| Compiler warning (level 4, off) C5254 | language feature 'terse static assert' requires compiler flag '/std:c++17' 17.1 | ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ [Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c5000-through-c5199.md b/docs/error-messages/compiler-warnings/compiler-warnings-c5000-through-c5199.md new file mode 100644 index 0000000000..38f4e44895 --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c5000-through-c5199.md @@ -0,0 +1,77 @@ +--- +title: "Microsoft C/C++ compiler (MSVC) warnings C5000 through C5199" +description: "Table of Microsoft C/C++ (MSVC) compiler warnings C5000 through C5199." +ms.date: 04/17/2024 +f1_keywords: ["C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5081", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5109", "C5110"] +helpviewer_keywords: ["C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5081", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5109", "C5110"] +--- +# Microsoft C/C++ compiler warnings C5000 through C5199 + +The articles in this section describe Microsoft C/C++ compiler warning messages C5000 through C5199. + +[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] + +## Warning messages + +| Warning | Message | +|--|--| +| Compiler warning C5022 | '*type*': multiple move constructors specified | +| Compiler warning C5023 | '*type*': multiple move assignment operators specified | +| Compiler warning (level 4, off) C5024 | '*type*': move constructor was implicitly defined as deleted | +| Compiler warning (level 4, off) C5025 | '*type*': move assignment operator was implicitly defined as deleted | +| Compiler warning (level 1 and level 4, off) C5026 | '*type*': move constructor was implicitly defined as deleted | +| Compiler warning (level 1 and level 4, off) C5027 | '*type*': move assignment operator was implicitly defined as deleted | +| Compiler warning (level 1) C5028 | '*name*': Alignment specified in prior declaration (*number*) not specified in definition | +| Compiler warning (level 4, off) C5029 | nonstandard extension used: alignment attributes in C++ apply to variables, data members and tag types only | +| Compiler warning (level 3) C5030 | attribute `[[`*attribute_name*`]]` is not recognized | +| Compiler warning (level 4, off) C5031 | `#pragma warning(pop)`: likely mismatch, popping warning state pushed in different file | +| Compiler warning (level 4, off) C5032 | detected `#pragma warning(push)` with no corresponding `#pragma warning(pop)` | +| [Compiler warning (level 1) C5033](c5033.md) | '*storage-class*' is no longer a supported storage class | +| Compiler warning (level 4, off) C5034 | use of intrinsic '*intrinsic*' causes function *function-name* to be compiled as guest code | +| Compiler warning (level 4, off) C5035 | use of feature '*feature*' causes function *function-name* to be compiled as guest code | +| Compiler warning (level 1) C5036 | `varargs` function pointer conversion when compiling with /hybrid:x86arm64 from type '*type1*' to type '*type2*' | +| [Compiler warning (level 3, error) C5037](c5037.md) | '*member-function*': an out-of-line definition of a member of a class template cannot have default arguments | +| [Compiler warning (level 4, off) C5038](c5038.md) | *data member* '*member1*' will be initialized after *data member* '*member2*' | +| Compiler warning (level 4, off) C5039 | '*function*': pointer or reference to potentially throwing function passed to '`extern "C"`' function under `-EHc`. Undefined behavior may occur if this function throws an exception. | +| Compiler warning (level 3) C5040 | dynamic exception specifications are valid only in C++14 and earlier; treating as noexcept(false) | +| Compiler warning (level 4, off) C5041 | '*definition*': out-of-line definition for `constexpr` static data member is not needed and is deprecated in C++17 | +| Compiler warning (level 3, off) C5042 | '*declaration*': function declarations at block scope cannot be specified '`inline`' in standard C++; remove '`inline`' specifier | +| Compiler warning (level 2) C5043 | '*specification*': exception specification does not match previous declaration | +| Compiler warning (level 4) C5044 | An argument to command-line option *option-name* points to a path '*path-name*' that does not exist | +| [Compiler warning (level 4) C5045](c5045.md) | Compiler will insert Spectre mitigation for memory load if `/Qspectre` switch specified | +| [Compiler warning (level 2) C5046](c5046.md) | '*function*': Symbol involving type with internal linkage not defined | +| Compiler warning (level 1, error) C5047 | use of nonstandard '*keyword*' with modules is not supported | +| Compiler warning (level 1) C5048 | Use of macro '*macroname*' may result in non-deterministic output | +| Compiler warning (level 1) C5049 | '*string*': Embedding a full path may result in machine-dependent output | +| [Compiler warning (level 1) C5050](c5050.md) | Possible incompatible environment while importing module '*module_name*': *issue* | +| Compiler warning (level 1) C5051 | attribute `[[`*attribute-name*`]]` requires at least '*standard_version*'; ignored | +| Compiler warning (level 3, off) C5052 | Keyword '*keyword-name*' was introduced in `C++`*version* and requires use of the '*switch*' command-line option | +| Compiler warning (level 1) C5053 | support for '`explicit()`' in C++17 and earlier is a vendor extension | +| [Compiler warning (level 4) C5054](c5054.md) | operator '*operator-name*': deprecated between enumerations of different types | +| [Compiler warning (level 1) C5055](c5055.md) | operator '*operator-name*': deprecated between enumerations and floating-point types | +| [Compiler warning (level 1) C5056](c5056.md) | operator '*operator-name*': deprecated for array types | +| Compiler warning (level 1) C5057 | header unit reference to '*name*' already exists. Ignoring header unit '*header-name*' | +| Compiler warning (level 1) C5058 | file system error: cannot find header file '*file-name*' for header unit '*unit-name*' | +| Compiler warning C5059 | runtime checks and address sanitizer is not currently supported - disabling runtime checks | +| Compiler warning (level 4) C5060 | `/Qpar` and address sanitizer not currently supported - disabling auto-parallelization | +| Compiler warning (level 4) C5061 | the use of a comma operator as a subscript expression has been deprecated | +| Compiler warning (level 4) C5062 | `enum` direct list initialization between '*type-1*' and '*type-2*' is no longer supported | +| Compiler warning (level 1) C5063 | '`std::is_constant_evaluated`' always evaluates to true in manifestly constant-evaluated expressions | +| [Compiler warning (level 1) C5072](compiler-warning-c5072.md) | ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting | +| Compiler warning (level 1) C5081 | Secure hotpatch is not supported with `/GENPROFILE`, `/FASTGENPROFILE` or `/LTCG:PGI`, disabling secure hotpatch. | +| Compiler warning (level 1) C5100 | `__VA_ARGS__` is reserved for use in variadic macros | +| Compiler warning (level 1) C5101 | use of preprocessor directive in function-like macro argument list is undefined behavior | +| Compiler warning (level 1) C5102 | ignoring invalid command-line macro definition '*value*' | +| Compiler warning (level 1) C5103 | pasting '*token1*' and '*token2*' does not result in a valid preprocessing token | +| Compiler warning (level 1) C5104 | found '*string1*`#`*string2*' in macro replacement list, did you mean '*string1*`""#`*string2*'? | +| [Compiler warning (level 1) C5105](c5105.md) | macro expansion producing 'defined' has undefined behavior | +| Compiler warning (level 1) C5106 | macro redefined with different parameter names | +| Compiler warning (level 1) C5107 | missing terminating '*char*' character | +| Compiler warning (level 1) C5108 | `__VA_OPT__` is reserved for use in variadic macros | +| Compiler warning (level 1) C5109 | `__VA_OPT__` use in macro requires '`/Zc:preprocessor`' | +| Compiler warning (level 4, off) C5110 | `__VA_OPT__` is an extension prior to C++20 or C23 | + +## See also + +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ +[Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warnings-c5200-through-c5399.md b/docs/error-messages/compiler-warnings/compiler-warnings-c5200-through-c5399.md new file mode 100644 index 0000000000..1b66790fb1 --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c5200-through-c5399.md @@ -0,0 +1,119 @@ +--- +title: "Microsoft C/C++ compiler (MSVC) compiler warnings C5200 through C5399" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C5200 through C5399." +ms.date: 04/19/2024 +f1_keywords: ["C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254", "C5255", "C5256", "C5257", "C5258", "C5259", "C5260", "C5261", "C5263", "C5264", "C5265", "C5268", "C5269", "C5270", "C5271", "C5272", "C5273", "C5274", "C5275", "C5300", "C5303", "C5304", "C5305"] +helpviewer_keywords: ["C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254", "C5255", "C5256", "C5257", "C5258", "C5259", "C5260", "C5261", "C5263", "C5264", "C5265", "C5268", "C5269", "C5270", "C5271", "C5272", "C5273", "C5274", "C5275", "C5300", "C5303", "C5304", "C5305"] +--- +# Microsoft C/C++ compiler warnings C5200 through C5399 + +The articles in this section describe Microsoft C/C++ compiler warning messages C5200 through C5399. + +[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] + +## Warning messages + +| Warning | Message | +|--|--| +| Compiler warning (level 1) C5200 | *feature* '*feature-name*' requires compiler flag '*option-name*' | +| Compiler warning (level 1) C5201 | a module declaration can appear only at the start of a translation unit unless a global module fragment is used | +| Compiler warning (level 1) C5202 | a global module fragment can only contain preprocessor directives | +| Compiler warning (level 1) C5203 | a parenthesized declarator name after '`explicit`' will be considered an explicit-specifier in C++20 | +| Compiler warning (level 3, off) C5204 | '*type-name*': class has virtual functions, but its trivial destructor is not virtual; instances of objects derived from this class may not be destructed correctly | +| Compiler warning (level 4) C5205 | delete of an abstract class '*type-name*' that has a non-virtual destructor results in undefined behavior | +| Compiler warning (level 3) C5206 | deduced return types for coroutines is a non-standard extension | +| Compiler warning (level 1) C5207 | the simple requirement asserts the validity of expression '`e->id`'. Did you mean '`{ e } -> id`'? You can suppress the warning using '`{ e->id }`' | +| [Compiler warning (level 1, error) C5208](c5208.md) | unnamed class used in `typedef` name cannot declare members other than non-static data members, member enumerations, or member classes | +| Compiler warning (level 1) C5209 | the C++20 syntax for an init-capture has changed to '`& ...opt identifier initializer`' | +| Compiler warning (level 1) C5210 | '*name*' is not a valid header unit reference; ignoring | +| Compiler warning (level 1) C5212 | '*name*' is not a valid named reference; treating as reference to file | +| Compiler warning (level 1) C5213 | '*name*' named reference is treated as a named partition but the *module* name is not specified; treating as reference to file | +| Compiler warning (level 4, off) C5214 | applying '*modifier*' to an operand with a volatile qualified type is deprecated in C++20 | +| Compiler warning (level 4, off) C5215 | '*name*' a function parameter with a volatile qualified type is deprecated in C++20 | +| Compiler warning (level 4, off) C5216 | '*name*' a volatile qualified return type is deprecated in C++20 | +| Compiler warning (level 4, off) C5217 | a structured binding declaration that includes volatile is deprecated in C++20 | +| Compiler warning (level 1) C5218 | destroying delete may not behave as intended when non-conforming switches '`/Zc:sizedDealloc-`' or '`/Zc:alignedNew-`' are used | +| Compiler warning (level 2, off) C5219 | implicit conversion from '*type-1*' to '*type-2*', possible loss of data | +| Compiler warning (level 4, off) C5220 | '*name*': a non-static data member with a volatile qualified type no longer implies
that compiler generated copy/move constructors and copy/move assignment operators are not trivial | +| Compiler warning (level 1) C5221 | `xfg::rename` is deprecated. | +| Compiler warning (level 3) C5222 | '*attribute-name*': all unscoped attribute names are reserved for future standardization | +| Compiler warning (level 3) C5223 | all attribute names in the attribute namespace '`msvc`' are reserved for the implementation | +| Compiler warning (level 3) C5224 | all attribute names in the attribute namespace '*namespace-name*' are reserved for future standardization | +| Compiler warning (level 1) C5225 | '*symbol*': exported inline function defined in a private module fragment is a non-standard extension | +| Compiler warning (level 1) C5226 | '*symbol*': exported template defined in private module fragment has no reachable instantiation | +| Compiler warning (level 4) C5227 | nonstandard extension, resolved '*symbol*' to '*value*' which is not visible with `/permissive-` on. | +| Compiler warning (level 4) C5228 | nonstandard extension, '*identifier*' resolved to a member of a dependent base. This lookup is not allowed under `/permissive-`. | +| Compiler warning (level 4) C5229 | nonstandard extension, the hidden friend function '*function-name*' was found by name lookup which isn't allowed under `/permissive-`. | +| Compiler warning C5230 | nonstandard extension, '*identifier*' was resolved to '*symbol-1*' under `/permissive`. Under `/permissive-` it would resolve to '*symbol-2*'. | +| Compiler warning (level 3, error) C5231 | the expression '`co_await promise.final_suspend()`' must be non-throwing | +| Compiler warning (level 1) C5232 | in C++20 this comparison calls '*name*' recursively | +| Compiler warning (level 4, off) C5233 | explicit lambda capture '*identifier*' is not used | +| Compiler warning (level 1) C5234 | file system error: '*filename*' is not a valid header-name; ignoring | +| Compiler warning (level 1) C5235 | JSON parse error: *message*; ignoring '*filename*' | +| Compiler warning (level 1) C5236 | JSON ill-formed: *message*; ignoring '*filename*' | +| Compiler warning (level 1) C5237 | cannot resolve header unit entry '*name*' to a header file in '*filename*'; ignoring entry | +| Compiler warning (level 1) C5238 | file system error: cannot open '*filename*' for reading; ignoring | +| Compiler warning (level 4) C5239 | '*symbol*': potentially-throwing function called from a function declared `__declspec(nothrow)`. Undefined behavior may occur if an exception is thrown. | +| [Compiler warning (level 4, off) C5240](c5240.md) | '*attribute-name*': attribute is ignored in this syntactic position | +| Compiler warning (level 1) C5241 | '`/exportHeader`' usage to lookup header-name is deprecated; prefer '`/headerName:`*name* *value*`=`*filename*' | +| Compiler warning (level 1) C5242 | syntax error in pragma '*identifier*' | +| [Compiler warning (level 1, off) C5243](c5243.md) | '*type-name*': using incomplete class '*class-name*' can cause potential one definition rule violation due to ABI limitation | +| Compiler warning (level 1) C5244 | '`#include <`*filename*`>`' in the purview of module '*module-name-1*' appears erroneous. Consider moving that directive before the module declaration, or replace the textual inclusion with '`import <`*module-name-2*`>;`'. | +| Compiler warning (level 4, off) C5245 | '*function*': unreferenced function with internal linkage has been removed | +| Compiler warning (level 1, off) C5246 | '*member*': the initialization of a subobject should be wrapped in braces | +| [Compiler warning (level 1, off) C5247](c5247.md) | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | +| [Compiler warning (level 1, off) C5248](c5248.md) | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified | +| Compiler warning (level 1, off) C5249 | '*bitfield*' of type '*enumeration_name*' has named enumerators with values that cannot be represented in the given bit field width of '*bitfield_width*'. | +| Compiler warning (level 3, off) C5250 | '*function_name*': intrinsic function not declared | +| Compiler warning (level 4, off) C5251 | the value of `#pragma` *pragma name* changed after `#include`; `#pragma `*pragma name*`(pop)` missing in this header? | +| Compiler warning (level 4) C5252 | Multiple different types resulted in the same XFG type-hash *hash-value*; the PDB will only record information for one of them | +| Compiler warning (level 4) C5253 | a non-local lambda cannot have a capture default | +| Compiler warning (level 4, off) C5254 | language feature 'terse static assert' requires compiler flag '*/std:c++17*' | +| Compiler warning (level 3) C5255 | unterminated bidirectional character encountered: '`U+`*XXXX*' | +| Compiler warning (level 1, off) C5256 | '*enumeration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration | +| Compiler warning (level 1 and level 4) C5257 | '*enumeration*': enumeration was previously declared without a fixed underlying type | +| Compiler warning (level 4, off) C5258 | explicit capture of '*symbol*' is not required for this use | +| Compiler warning (level 4, off) C5259 | '*specialized-type*': explicit specialization requires 'template <>' | +| Compiler warning (level 1) C5260 | the constant variable '*variable-name*' has internal linkage in an included header file context, but external linkage in imported header unit context; consider declaring it 'inline' as well if it will be shared across translation units, or 'static' to express intent to use it local to this translation unit | +| Compiler warning (level 2) C5261 | no integer type can represent all enumerator values in enumeration '*enum-name*' | +| [Compiler warning (level 1, off) C5262](c5262.md) | implicit fall-through occurs here; are you missing a break statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases | +| Compiler warning (level 4, off) C5263 | calling '`std::move`' on a temporary object prevents copy elision | +| Compiler warning (level 4, off) C5264 | '*variable-name*': 'const' variable is not used | +| Compiler warning (level 1) C5265 | cannot open search path '*path*' | +| [Compiler warning (level 4, off) C5266](compiler-warning-level-4-c5266.md) | '*const*' qualifier on return type has no effect | +| [Compiler warning (level 4, off) C5267](c5267.md) | definition of implicit *copy constructor/assignment operator* for '*type*' is deprecated because it has a user-provided *assignment operator/copy constructor* | +| Compiler warning (level 1) C5268 | Failed to allocate memory at fixed address 0x*address*. Use `/Yb` to specify a specific address base if bit-identical .pch files are required. | +| Compiler warning (level 1) C5269 | Failed to allocate PCH memory at fixed address 0x*address*. Use `/Ym` to specify a specific address base if bit-identical .pch files are required. | +| Compiler warning (level 3) C5270 | '*value*' is not allowed for option '*switch name*'; allowed values are: *value list* | +| Compiler warning (level 4) C5271 | previously imported assembly '*assembly1*' has the same name as assembly '*assembly2*' being imported. Is this intentional? | +| Compiler warning (level 1) C5272 | throwing an object of non-copyable type '*type*' is non-standard. If a copy is needed at runtime it will be made as if by `memcpy`. | +| Compiler warning (level 1) C5273 | behavior change: `_Alignas` on anonymous type no longer ignored (promoted members will align) | +| Compiler warning (level 1) C5274 | behavior change: `_Alignas` no longer applies to the type '*type*' (only applies to declared data objects) | +| Compiler warning (error) C5275 | assembly '*name*' being imported under '*/clr*' does not contain the required fundamental types | +| Compiler warning (level 1) C5276 | `/experimental:ifcDebugRecords` currently requires `/Z7` to be enabled. Please recompile with `/Z7` enabled.| +| Compiler warning (level 1) C5277 | type trait optimization for '*class name*' is disabled | +| Compiler warning (level 1) C5278 | adding a specialization for '*type*' has undefined behavior | +| Compiler warning (level 1) C5279 | a lambda declarator without a parameter list requires at least '*language version*' | +| Compiler warning (level 1) C5280 | a static operator '*operator name*' requires at least '*language version*'| +| Compiler warning (level 1) C5281 | a static lambda requires at least '*language version*' | +| Compiler warning (level 1) C5282 | '`if consteval`' requires at least '*language version*' | +| Compiler warning (level 1) C5283 | an attribute in this position requires at least '*language version*' | +| Compiler warning (level 4) C5284 | conversion from value '*value*' of type '*type 1*' to '*type 2*' requires a narrowing conversion | +| Compiler warning (level 1) C5285 | cannot declare a specialization for '*template name*': *template argument* | +| Compiler warning (level 1) C5286 | implicit conversion from `enum` type '*type 1*' to `enum` type '*type 2*'; use an explicit cast to silence this warning | +| Compiler warning (level 1) C5287 | operands are different `enum` types '*type 1*' and '*type 2*'; use an explicit cast to silence this warning | +| Compiler warning (error) C5300 | '`#pragma omp atomic` *clause*': expression mismatch for lvalue being updated | +| [Compiler warning (level 1) C5301](c5301-c5302.md) | '`#pragma omp for`': '*loop-index*' increases while loop condition uses '*comparison*'; non-terminating loop? | +| [Compiler warning (level 1) C5302](c5301-c5302.md) | '`#pragma omp for`': '*loop-index*' decreases while loop condition uses '*comparison*'; non-terminating loop? | +| Compiler warning (level 1) C5303 | function marked with `[[msvc::intrinsic]]` did not result in a no-op cast | +| Compiler warning (level 1) C5304 | a declaration designated by the using-declaration '*name1*' exported from this module has internal linkage and using such a name outside the module is ill-formed; consider declaring '*name2*' '`inline`' to use it outside of this module | +| Compiler warning (level 1) C5305 | '*name*': an explicit instantiation declaration that follows an explicit instantiation definition is ignored | +| Compiler warning (level 1) C5306 | parameter array behavior change: overload '*identifier 1*' resolved to '*identifier 2*'; previously, it would have resolved to '*identifier 3*'. Use `/clr:ECMAParamArray` to revert to old behavior | +| Compiler warning (level 3) C5307 | '*function*': argument (*argument number*) converted from '*type 1*' to '*type 2*'. Missing '`L`' encoding-prefix for character literal? | +| Compiler warning (level 1, error) C5308 | Modifying reserved macro name '*macro name*' may cause undefined behavior | +| Compiler warning (level 1, error) C5309 | literal suffix '*name*' requires at least '*language version*'| + +## See also + +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ +[Compiler warnings C4000 - C5999](compiler-warnings-c4000-c5999.md) diff --git a/docs/error-messages/includes/error-boilerplate.md b/docs/error-messages/includes/error-boilerplate.md index c94b2ac74f..d7eba2d5c8 100644 --- a/docs/error-messages/includes/error-boilerplate.md +++ b/docs/error-messages/includes/error-boilerplate.md @@ -1,11 +1,11 @@ > [!IMPORTANT] -> The Visual Studio compilers and build tools can report many kinds of errors and warnings. After an error or warning is found, the build tools may make assumptions about code intent and attempt to continue, so that more issues can be reported at the same time. If the tools make the wrong assumption, later errors or warnings may not apply to your project. When you correct issues in your project, always start with the first error or warning that's reported, and rebuild often. One fix may make many subsequent errors go away. +> The Visual Studio compilers and build tools can report many kinds of errors and warnings. After an error or warning is found, the build tools may make assumptions about code intent and attempt to continue, so that more issues can be reported at the same time. If the tools make the wrong assumption, later errors or warnings may not apply to your project. When you correct issues in your project, always start with the first error or warning that's reported, and rebuild often. One fix may resolve multiple subsequent errors. To get help on a particular diagnostic message in Visual Studio, select it in the **Output** window and press the **F1** key. Visual Studio opens the documentation page for that error, if one exists. You can also use the search tool at the top of the page to find articles about specific errors or warnings. Or, browse the list of errors and warnings by tool and type in the table of contents on this page. > [!NOTE] -> Not every Visual Studio error or warning is documented. In many cases, the diagnostic message provides all of the information that's available. If you landed on this page when you used **F1** and you think the error or warning message needs additional explanation, let us know. You can use the feedback buttons on this page to raise a documentation issue on [GitHub](https://github.com/MicrosoftDocs/cpp-docs/issues). If you think the error or warning is wrong, or you've found another problem with the toolset, report a product issue on the [Developer Community](https://aka.ms/feedback/report?space=62) site. You can also send feedback and enter bugs within the IDE. In Visual Studio, go to the menu bar and choose **Help > Send Feedback > Report a Problem**, or submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. +> Not every Visual Studio error or warning is documented. In many cases, the diagnostic message provides all of the information that's available. If you landed on this page and think the error or warning message needs additional explanation, let us know by using the feedback buttons on this page. If you think the error or warning is wrong, or you've found another problem with the toolset, report a product issue on the [Developer Community](https://aka.ms/feedback/report?space=62) site. You can also send feedback and enter bugs within the IDE. In Visual Studio, go to the menu bar and choose **Help > Send Feedback > Report a Problem**, or submit a suggestion by using **Help > Send Feedback > Suggest a Feature**. Some compiler error topics were created that are not emitted by the compiler and now redirect to this page instead. -You may find additional assistance for errors and warnings in [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) forums. Or, search for the error or warning number on the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) site. You can also search [Stack Overflow](https://stackoverflow.com/) to find solutions. +You may find additional assistance for errors and warnings in [Microsoft Q&A C++](/answers/tags/314/cpp) forums. Or, search for the error or warning number on the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) site. You can also search [Stack Overflow](https://stackoverflow.com/) to find solutions. For links to additional help and community resources, see [Visual C++ Help and Community](../../overview/visual-cpp-help-and-community.md). diff --git a/docs/error-messages/toc.yml b/docs/error-messages/toc.yml index 71ccf0402f..8109e4d313 100644 --- a/docs/error-messages/toc.yml +++ b/docs/error-messages/toc.yml @@ -86,251 +86,259 @@ items: - name: Compiler fatal errors expanded: false items: - - name: Compiler fatal errors C999 through C1999 + - name: Compiler fatal errors C1001 through C1907 href: compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md - - name: fatal error C999 - href: compiler-errors-1/fatal-error-c999.md - - name: fatal error C1001 + - name: Fatal error C1001 href: compiler-errors-1/fatal-error-c1001.md - - name: fatal error C1002 + - name: Fatal error C1002 href: compiler-errors-1/fatal-error-c1002.md - - name: fatal error C1003 + - name: Fatal error C1003 href: compiler-errors-1/fatal-error-c1003.md - - name: fatal error C1004 + - name: Fatal error C1004 href: compiler-errors-1/fatal-error-c1004.md - - name: fatal error C1005 + - name: Fatal error C1005 href: compiler-errors-1/fatal-error-c1005.md - - name: fatal error C1007 + - name: Fatal error C1007 href: compiler-errors-1/fatal-error-c1007.md - - name: fatal error C1008 + - name: Fatal error C1008 href: compiler-errors-1/fatal-error-c1008.md - - name: fatal error C1009 + - name: Fatal error C1009 href: compiler-errors-1/fatal-error-c1009.md - - name: fatal error C1010 + - name: Fatal error C1010 href: compiler-errors-1/fatal-error-c1010.md - - name: fatal error C1012 + - name: Fatal error C1011 + href: compiler-errors-1/fatal-error-c1011.md + - name: Fatal error C1012 href: compiler-errors-1/fatal-error-c1012.md - - name: fatal error C1013 + - name: Fatal error C1013 href: compiler-errors-1/fatal-error-c1013.md - - name: fatal error C1014 + - name: Fatal error C1014 href: compiler-errors-1/fatal-error-c1014.md - - name: fatal error C1016 + - name: Fatal error C1015 + href: compiler-errors-1/fatal-error-c1015.md + - name: Fatal error C1016 href: compiler-errors-1/fatal-error-c1016.md - - name: fatal error C1017 + - name: Fatal error C1017 href: compiler-errors-1/fatal-error-c1017.md - - name: fatal error C1018 + - name: Fatal error C1018 href: compiler-errors-1/fatal-error-c1018.md - - name: fatal error C1019 + - name: Fatal error C1019 href: compiler-errors-1/fatal-error-c1019.md - - name: fatal error C1020 + - name: Fatal error C1020 href: compiler-errors-1/fatal-error-c1020.md - - name: fatal error C1021 + - name: Fatal error C1021 href: compiler-errors-1/fatal-error-c1021.md - - name: fatal error C1022 + - name: Fatal error C1022 href: compiler-errors-1/fatal-error-c1022.md - - name: fatal error C1023 + - name: Fatal error C1023 href: compiler-errors-1/fatal-error-c1023.md - - name: fatal error C1026 + - name: Fatal error C1025, C1115 + href: compiler-errors-1/fatal-error-c1025-c1115.md + - name: Fatal error C1026 href: compiler-errors-1/fatal-error-c1026.md - - name: fatal error C1033 + - name: Fatal error C1033 href: compiler-errors-1/fatal-error-c1033.md - - name: fatal error C1035 + - name: Fatal error C1035 href: compiler-errors-1/fatal-error-c1035.md - - name: fatal error C1037 + - name: Fatal error C1037 href: compiler-errors-1/fatal-error-c1037.md - - name: fatal error C1038 + - name: Fatal error C1038 href: compiler-errors-1/fatal-error-c1038.md - - name: fatal error C1045 + - name: Fatal error C1045 href: compiler-errors-1/fatal-error-c1045.md - - name: fatal error C1046 + - name: Fatal error C1046 href: compiler-errors-1/fatal-error-c1046.md - - name: fatal error C1047 + - name: Fatal error C1047 href: compiler-errors-1/fatal-error-c1047.md - - name: fatal error C1049 + - name: Fatal error C1049 href: compiler-errors-1/fatal-error-c1049.md - - name: fatal error C1051 + - name: Fatal error C1051 href: compiler-errors-1/fatal-error-c1051.md - - name: fatal error C1052 + - name: Fatal error C1052 href: compiler-errors-1/fatal-error-c1052.md - - name: fatal error C1053 + - name: Fatal error C1053 href: compiler-errors-1/fatal-error-c1053.md - - name: fatal error C1054 + - name: Fatal error C1054 href: compiler-errors-1/fatal-error-c1054.md - - name: fatal error C1055 + - name: Fatal error C1055 href: compiler-errors-1/fatal-error-c1055.md - - name: fatal error C1057 + - name: Fatal error C1057 href: compiler-errors-1/fatal-error-c1057.md - - name: fatal error C1060 + - name: Fatal error C1060 href: compiler-errors-1/fatal-error-c1060.md - - name: fatal error C1061 + - name: Fatal error C1061 href: compiler-errors-1/fatal-error-c1061.md - - name: fatal error C1064 + - name: Fatal error C1064 href: compiler-errors-1/fatal-error-c1064.md - - name: fatal error C1065 + - name: Fatal error C1065 href: compiler-errors-1/fatal-error-c1065.md - - name: fatal error C1067 + - name: Fatal error C1067 href: compiler-errors-1/fatal-error-c1067.md - - name: fatal error C1068 + - name: Fatal error C1068 href: compiler-errors-1/fatal-error-c1068.md - - name: fatal error C1070 + - name: Fatal error C1070 href: compiler-errors-1/fatal-error-c1070.md - - name: fatal error C1071 + - name: Fatal error C1071 href: compiler-errors-1/fatal-error-c1071.md - - name: fatal error C1073 + - name: Fatal error C1073 href: compiler-errors-1/fatal-error-c1073.md - - name: fatal error C1074 + - name: Fatal error C1074 href: compiler-errors-1/fatal-error-c1074.md - - name: fatal error C1075 + - name: Fatal error C1075 href: compiler-errors-1/fatal-error-c1075.md - - name: fatal error C1076 + - name: Fatal error C1076 href: compiler-errors-1/fatal-error-c1076.md - - name: fatal error C1077 + - name: Fatal error C1077 href: compiler-errors-1/fatal-error-c1077.md - - name: fatal error C1079 + - name: Fatal error C1079 href: compiler-errors-1/fatal-error-c1079.md - - name: fatal error C1080 + - name: Fatal error C1080 href: compiler-errors-1/fatal-error-c1080.md - - name: fatal error C1081 + - name: Fatal error C1081 href: compiler-errors-1/fatal-error-c1081.md - - name: fatal error C1082 + - name: Fatal error C1082 href: compiler-errors-1/fatal-error-c1082.md - - name: fatal error C1083 + - name: Fatal error C1083 href: compiler-errors-1/fatal-error-c1083.md - - name: fatal error C1084 + - name: Fatal error C1084 href: compiler-errors-1/fatal-error-c1084.md - - name: fatal error C1085 + - name: Fatal error C1085 href: compiler-errors-1/fatal-error-c1085.md - - name: fatal error C1086 + - name: Fatal error C1086 href: compiler-errors-1/fatal-error-c1086.md - - name: fatal error C1087 + - name: Fatal error C1087 href: compiler-errors-1/fatal-error-c1087.md - - name: fatal error C1088 + - name: Fatal error C1088 href: compiler-errors-1/fatal-error-c1088.md - - name: fatal error C1089 + - name: Fatal error C1089 href: compiler-errors-1/fatal-error-c1089.md - - name: fatal error C1090 + - name: Fatal error C1090 href: compiler-errors-1/fatal-error-c1090.md - - name: fatal error C1091 + - name: Fatal error C1091 href: compiler-errors-1/fatal-error-c1091.md - - name: fatal error C1092 + - name: Fatal error C1092 href: compiler-errors-1/fatal-error-c1092.md - - name: fatal error C1093 + - name: Fatal error C1093 href: compiler-errors-1/fatal-error-c1093.md - - name: fatal error C1094 + - name: Fatal error C1094 href: compiler-errors-1/fatal-error-c1094.md - - name: fatal error C1098 + - name: Fatal error C1098 href: compiler-errors-1/fatal-error-c1098.md - - name: fatal error C1099 + - name: Fatal error C1099 href: compiler-errors-1/fatal-error-c1099.md - - name: fatal error C1100 + - name: Fatal error C1100 href: compiler-errors-1/fatal-error-c1100.md - - name: fatal error C1103 + - name: Fatal error C1103 href: compiler-errors-1/fatal-error-c1103.md - - name: fatal error C1104 + - name: Fatal error C1104 href: compiler-errors-1/fatal-error-c1104.md - - name: fatal error C1107 + - name: Fatal error C1107 href: compiler-errors-1/fatal-error-c1107.md - - name: fatal error C1108 + - name: Fatal error C1108 href: compiler-errors-1/fatal-error-c1108.md - - name: fatal error C1109 + - name: Fatal error C1109 href: compiler-errors-1/fatal-error-c1109.md - - name: fatal error C1113 + - name: Fatal error C1113 href: compiler-errors-1/fatal-error-c1113.md - - name: fatal error C1120 + - name: Fatal error C1116 + href: compiler-errors-1/fatal-error-c1116.md + - name: Fatal error C1117 + href: compiler-errors-1/fatal-error-c1117.md + - name: Fatal error C1120 href: compiler-errors-1/fatal-error-c1120.md - - name: fatal error C1121 + - name: Fatal error C1121 href: compiler-errors-1/fatal-error-c1121.md - - name: fatal error C1126 + - name: Fatal error C1126 href: compiler-errors-1/fatal-error-c1126.md - - name: fatal error C1128 + - name: Fatal error C1128 href: compiler-errors-1/fatal-error-c1128.md - - name: fatal error C1189 + - name: Fatal error C1189 href: compiler-errors-1/fatal-error-c1189.md - - name: fatal error C1190 + - name: Fatal error C1190 href: compiler-errors-1/fatal-error-c1190.md - - name: fatal error C1191 + - name: Fatal error C1191 href: compiler-errors-1/fatal-error-c1191.md - - name: fatal error C1192 + - name: Fatal error C1192 href: compiler-errors-1/fatal-error-c1192.md - - name: fatal error C1196 + - name: Fatal error C1196 href: compiler-errors-1/fatal-error-c1196.md - - name: fatal error C1197 + - name: Fatal error C1197 href: compiler-errors-1/fatal-error-c1197.md - - name: fatal error C1201 + - name: Fatal error C1201 href: compiler-errors-1/fatal-error-c1201.md - - name: fatal error C1202 + - name: Fatal error C1202 href: compiler-errors-1/fatal-error-c1202.md - - name: fatal error C1205 + - name: Fatal error C1205 href: compiler-errors-1/fatal-error-c1205.md - - name: fatal error C1206 + - name: Fatal error C1206 href: compiler-errors-1/fatal-error-c1206.md - - name: fatal error C1207 + - name: Fatal error C1207 href: compiler-errors-1/fatal-error-c1207.md - - name: fatal error C1208 + - name: Fatal error C1208 href: compiler-errors-1/fatal-error-c1208.md - - name: fatal error C1209 + - name: Fatal error C1209 href: compiler-errors-1/fatal-error-c1209.md - - name: fatal error C1210 + - name: Fatal error C1210 href: compiler-errors-1/fatal-error-c1210.md - - name: fatal error C1211 + - name: Fatal error C1211 href: compiler-errors-1/fatal-error-c1211.md - - name: fatal error C1305 + - name: Fatal error C1305 href: compiler-errors-1/fatal-error-c1305.md - - name: fatal error C1307 + - name: Fatal error C1307 href: compiler-errors-1/fatal-error-c1307.md - - name: fatal error C1308 + - name: Fatal error C1308 href: compiler-errors-1/fatal-error-c1308.md - - name: fatal error C1309 + - name: Fatal error C1309 href: compiler-errors-1/fatal-error-c1309.md - - name: fatal error C1310 + - name: Fatal error C1310 href: compiler-errors-1/fatal-error-c1310.md - - name: fatal error C1311 + - name: Fatal error C1311 href: compiler-errors-1/fatal-error-c1311.md - - name: fatal error C1312 + - name: Fatal error C1312 href: compiler-errors-1/fatal-error-c1312.md - - name: fatal error C1313 + - name: Fatal error C1313 href: compiler-errors-1/fatal-error-c1313.md - - name: fatal error C1350 + - name: Fatal error C1350 href: compiler-errors-1/fatal-error-c1350.md - - name: fatal error C1351 + - name: Fatal error C1351 href: compiler-errors-1/fatal-error-c1351.md - - name: fatal error C1352 + - name: Fatal error C1352 href: compiler-errors-1/fatal-error-c1352.md - - name: fatal error C1353 + - name: Fatal error C1353 href: compiler-errors-1/fatal-error-c1353.md - - name: fatal error C1382 + - name: Fatal error C1382 href: compiler-errors-1/fatal-error-c1382.md - - name: fatal error C1383 + - name: Fatal error C1383 href: compiler-errors-1/fatal-error-c1383.md - - name: fatal error C1506 + - name: Fatal error C1506 href: compiler-errors-1/fatal-error-c1506.md - - name: fatal error C1508 + - name: Fatal error C1508 href: compiler-errors-1/fatal-error-c1508.md - - name: fatal error C1509 + - name: Fatal error C1509 href: compiler-errors-1/fatal-error-c1509.md - - name: fatal error C1510 + - name: Fatal error C1510 href: compiler-errors-1/fatal-error-c1510.md - - name: fatal error C1601 + - name: Fatal error C1601 href: compiler-errors-1/fatal-error-c1601.md - - name: fatal error C1602 + - name: Fatal error C1602 href: compiler-errors-1/fatal-error-c1602.md - - name: fatal error C1603 + - name: Fatal error C1603 href: compiler-errors-1/fatal-error-c1603.md - - name: fatal error C1852 + - name: Fatal error C1852 href: compiler-errors-1/fatal-error-c1852.md - - name: fatal error C1853 + - name: Fatal error C1853 href: compiler-errors-1/fatal-error-c1853.md - - name: fatal error C1854 + - name: Fatal error C1854 href: compiler-errors-1/fatal-error-c1854.md - - name: fatal error C1900 + - name: Fatal error C1900 href: compiler-errors-1/fatal-error-c1900.md - - name: fatal error C1902 + - name: Fatal error C1902 href: compiler-errors-1/fatal-error-c1902.md - - name: fatal error C1903 + - name: Fatal error C1903 href: compiler-errors-1/fatal-error-c1903.md - - name: fatal error C1904 + - name: Fatal error C1904 href: compiler-errors-1/fatal-error-c1904.md - - name: fatal error C1905 + - name: Fatal error C1905 href: compiler-errors-1/fatal-error-c1905.md - name: Compiler errors expanded: false @@ -372,6 +380,8 @@ items: href: compiler-errors-1/compiler-error-c2014.md - name: Compiler error C2015 href: compiler-errors-1/compiler-error-c2015.md + - name: Compiler error C2016 + href: compiler-errors-1/compiler-error-c2016.md - name: Compiler error C2017 href: compiler-errors-1/compiler-error-c2017.md - name: Compiler error C2018 @@ -384,6 +394,12 @@ items: href: compiler-errors-1/compiler-error-c2021.md - name: Compiler error C2022 href: compiler-errors-1/compiler-error-c2022.md + - name: Compiler error C2023 + href: compiler-errors-1/compiler-error-c2023.md + - name: Compiler error C2024 + href: compiler-errors-1/compiler-error-c2024.md + - name: Compiler error C2025 + href: compiler-errors-1/compiler-error-c2025.md - name: Compiler error C2026 href: compiler-errors-1/compiler-error-c2026.md - name: Compiler error C2027 @@ -392,14 +408,22 @@ items: href: compiler-errors-1/compiler-error-c2028.md - name: Compiler error C2030 href: compiler-errors-1/compiler-error-c2030.md + - name: Compiler error C2031 + href: compiler-errors-1/compiler-error-c2031.md - name: Compiler error C2032 href: compiler-errors-1/compiler-error-c2032.md - name: Compiler error C2033 href: compiler-errors-1/compiler-error-c2033.md - name: Compiler error C2034 href: compiler-errors-1/compiler-error-c2034.md + - name: Compiler error C2035 + href: compiler-errors-1/compiler-error-c2035.md - name: Compiler error C2036 href: compiler-errors-1/compiler-error-c2036.md + - name: Compiler error C2037 + href: compiler-errors-1/compiler-error-c2037.md + - name: Compiler error C2038 + href: compiler-errors-1/compiler-error-c2038.md - name: Compiler error C2039 href: compiler-errors-1/compiler-error-c2039.md - name: Compiler error C2040 @@ -420,6 +444,8 @@ items: href: compiler-errors-1/compiler-error-c2047.md - name: Compiler error C2048 href: compiler-errors-1/compiler-error-c2048.md + - name: Compiler error C2049 + href: compiler-errors-1/compiler-error-c2049.md - name: Compiler error C2050 href: compiler-errors-1/compiler-error-c2050.md - name: Compiler error C2051 @@ -456,6 +482,8 @@ items: href: compiler-errors-1/compiler-error-c2066.md - name: Compiler error C2067 href: compiler-errors-1/compiler-error-c2067.md + - name: Compiler error C2068 + href: compiler-errors-1/compiler-error-c2068.md - name: Compiler error C2069 href: compiler-errors-1/compiler-error-c2069.md - name: Compiler error C2070 @@ -470,12 +498,16 @@ items: href: compiler-errors-1/compiler-error-c2074.md - name: Compiler error C2075 href: compiler-errors-1/compiler-error-c2075.md + - name: Compiler error C2076 + href: compiler-errors-1/compiler-error-c2076.md - name: Compiler error C2077 href: compiler-errors-1/compiler-error-c2077.md - name: Compiler error C2078 href: compiler-errors-1/compiler-error-c2078.md - name: Compiler error C2079 href: compiler-errors-1/compiler-error-c2079.md + - name: Compiler error C2080 + href: compiler-errors-1/compiler-error-c2080.md - name: Compiler error C2081 href: compiler-errors-1/compiler-error-c2081.md - name: Compiler error C2082 @@ -506,8 +538,12 @@ items: href: compiler-errors-1/compiler-error-c2094.md - name: Compiler error C2095 href: compiler-errors-1/compiler-error-c2095.md + - name: Compiler error C2096 + href: compiler-errors-1/compiler-error-c2096.md - name: Compiler error C2097 href: compiler-errors-1/compiler-error-c2097.md + - name: Compiler error C2098 + href: compiler-errors-1/compiler-error-c2098.md - name: Compiler error C2099 href: compiler-errors-1/compiler-error-c2099.md - name: Compiler errors C2100 through C2199 @@ -852,10 +888,10 @@ items: href: compiler-errors-1/compiler-error-c2298.md - name: Compiler error C2299 href: compiler-errors-1/compiler-error-c2299.md - - name: Compiler errors C2300 Through C2399 + - name: Compiler errors C2300 through C2399 expanded: false items: - - name: Compiler errors C2300 Through C2399 + - name: Compiler errors C2300 through C2399 href: compiler-errors-1/compiler-errors-c2300-through-c2399.md - name: Compiler error C2300 href: compiler-errors-1/compiler-error-c2300.md @@ -891,6 +927,8 @@ items: href: compiler-errors-1/compiler-error-c2320.md - name: Compiler error C2322 href: compiler-errors-1/compiler-error-c2322.md + - name: Compiler error C2323 + href: compiler-errors-1/compiler-error-c2323.md - name: Compiler error C2324 href: compiler-errors-1/compiler-error-c2324.md - name: Compiler error C2325 @@ -1005,10 +1043,10 @@ items: href: compiler-errors-1/compiler-error-c2396.md - name: Compiler error C2397 href: compiler-errors-1/compiler-error-c2397.md - - name: Compiler errors C2400 Through C2499 + - name: Compiler errors C2400 through C2499 expanded: false items: - - name: Compiler errors C2400 Through C2499 + - name: Compiler errors C2400 through C2499 href: compiler-errors-1/compiler-errors-c2400-through-c2499.md - name: Compiler error C2400 href: compiler-errors-1/compiler-error-c2400.md @@ -1180,10 +1218,10 @@ items: href: compiler-errors-1/compiler-error-c2498.md - name: Compiler error C2499 href: compiler-errors-1/compiler-error-c2499.md - - name: Compiler errors C2500 Through C2599 + - name: Compiler errors C2500 through C2599 expanded: false items: - - name: Compiler errors C2500 Through C2599 + - name: Compiler errors C2500 through C2599 href: compiler-errors-2/compiler-errors-c2500-through-c2599.md - name: Compiler error C2500 href: compiler-errors-2/compiler-error-c2500.md @@ -1335,10 +1373,10 @@ items: href: compiler-errors-2/compiler-error-c2598.md - name: Compiler error C2599 href: compiler-errors-2/compiler-error-c2599.md - - name: Compiler errors C2600 Through C2699 + - name: Compiler errors C2600 through C2699 expanded: false items: - - name: Compiler errors C2600 Through C2699 + - name: Compiler errors C2600 through C2699 href: compiler-errors-2/compiler-errors-c2600-through-c2699.md - name: Compiler error C2600 href: compiler-errors-2/compiler-error-c2600.md @@ -1490,10 +1528,10 @@ items: href: compiler-errors-2/compiler-error-c2696.md - name: Compiler error C2698 href: compiler-errors-2/compiler-error-c2698.md - - name: Compiler errors C2700 Through C2799 + - name: Compiler errors C2700 through C2799 expanded: false items: - - name: Compiler errors C2700 Through C2799 + - name: Compiler errors C2700 through C2799 href: compiler-errors-2/compiler-errors-c2700-through-c2799.md - name: Compiler error C2700 href: compiler-errors-2/compiler-error-c2700.md @@ -1659,10 +1697,10 @@ items: href: compiler-errors-2/compiler-error-c2797.md - name: Compiler error C2798 href: compiler-errors-2/compiler-error-c2798.md - - name: Compiler errors C2800 Through C2899 + - name: Compiler errors C2800 through C2899 expanded: false items: - - name: Compiler errors C2800 Through C2899 + - name: Compiler errors C2800 through C2899 href: compiler-errors-2/compiler-errors-c2800-through-c2899.md - name: Compiler error C2800 href: compiler-errors-2/compiler-error-c2800.md @@ -1826,10 +1864,10 @@ items: href: compiler-errors-2/compiler-error-c2897.md - name: Compiler error C2898 href: compiler-errors-2/compiler-error-c2898.md - - name: Compiler errors C2900 Through C2999 + - name: Compiler errors C2900 through C2999 expanded: false items: - - name: Compiler errors C2900 Through C2999 + - name: Compiler errors C2900 through C2999 href: compiler-errors-2/compiler-errors-c2900-through-c3499.md - name: Compiler error C2902 href: compiler-errors-2/compiler-error-c2902.md @@ -1915,6 +1953,8 @@ items: href: compiler-errors-2/compiler-error-c2953.md - name: Compiler error C2955 href: compiler-errors-2/compiler-error-c2955.md + - name: Compiler error C2956 + href: compiler-errors-2/compiler-error-c2956.md - name: Compiler error C2957 href: compiler-errors-2/compiler-error-c2957.md - name: Compiler error C2958 @@ -1963,10 +2003,10 @@ items: href: compiler-errors-2/compiler-error-c2996.md - name: Compiler error C2998 href: compiler-errors-2/compiler-error-c2998.md - - name: Compiler errors C3000 Through C3099 + - name: Compiler errors C3000 through C3099 expanded: false items: - - name: Compiler errors C3000 Through C3099 + - name: Compiler errors C3000 through C3099 href: compiler-errors-2/compiler-errors-c3000-through-c3099.md - name: Compiler error C3001 href: compiler-errors-2/compiler-error-c3001.md @@ -2132,10 +2172,10 @@ items: href: compiler-errors-2/compiler-error-c3097.md - name: Compiler error C3099 href: compiler-errors-2/compiler-error-c3099.md - - name: Compiler errors C3100 Through C3199 + - name: Compiler errors C3100 through C3199 expanded: false items: - - name: Compiler errors C3100 Through C3199 + - name: Compiler errors C3100 through C3199 href: compiler-errors-2/compiler-errors-c3100-through-c3199.md - name: Compiler error C3100 href: compiler-errors-2/compiler-error-c3100.md @@ -2273,10 +2313,10 @@ items: href: compiler-errors-2/compiler-error-c3198.md - name: Compiler error C3199 href: compiler-errors-2/compiler-error-c3199.md - - name: Compiler errors C3200 Through C3299 + - name: Compiler errors C3200 through C3299 expanded: false items: - - name: Compiler errors C3200 Through C3299 + - name: Compiler errors C3200 through C3299 href: compiler-errors-2/compiler-errors-c3200-through-c3299.md - name: Compiler error C3200 href: compiler-errors-2/compiler-error-c3200.md @@ -2448,10 +2488,10 @@ items: href: compiler-errors-2/compiler-error-c3298.md - name: Compiler error C3299 href: compiler-errors-2/compiler-error-c3299.md - - name: Compiler errors C3300 Through C3399 + - name: Compiler errors C3300 through C3399 expanded: false items: - - name: Compiler errors C3300 Through C3399 + - name: Compiler errors C3300 through C3399 href: compiler-errors-2/compiler-errors-c3300-through-c3399.md - name: Compiler error C3303 href: compiler-errors-2/compiler-error-c3303.md @@ -2557,10 +2597,10 @@ items: href: compiler-errors-2/compiler-error-c3398.md - name: Compiler error C3399 href: compiler-errors-2/compiler-error-c3399.md - - name: Compiler errors C3400 Through C3499 + - name: Compiler errors C3400 through C3499 expanded: false items: - - name: Compiler errors C3400 Through C3499 + - name: Compiler errors C3400 through C3499 href: compiler-errors-2/compiler-errors-c3400-through-c3499.md - name: Compiler error C3400 href: compiler-errors-2/compiler-error-c3400.md @@ -3123,29 +3163,33 @@ items: href: compiler-errors-2/compiler-error-c7510.md - name: Compiler error C7536 href: compiler-errors-2/compiler-error-c7536.md + - name: Compiler error C7553 + href: compiler-errors-2/compiler-error-c7553.md - name: Compiler error C7626 href: compiler-warnings/c5208.md -- name: Compiler warnings C4000 Through C5999 + - name: Compiler error C7688 + href: compiler-errors-2/compiler-error-c7688.md +- name: Compiler warnings C4000 through C5999 expanded: false items: - - name: Compiler warnings C4000 - C5999 + - name: Compiler warnings C4000 through C5999 href: compiler-warnings/compiler-warnings-c4000-c5999.md - - name: Compiler warnings C4000 Through C4199 + - name: Compiler warnings C4000 through C4199 expanded: false items: - - name: Compiler warnings C4000 Through C4199 + - name: Compiler warnings C4000 through C4199 href: compiler-warnings/compiler-warnings-c4000-through-c4199.md - - name: Compiler warning (level 4) C4001 + - name: Compiler warning (level 4, no longer emitted) C4001 href: compiler-warnings/compiler-warning-level-4-c4001.md - - name: Compiler warning (level 1) C4002 + - name: Compiler warning (level 1, Error) C4002 href: compiler-warnings/compiler-warning-level-1-c4002.md - - name: Compiler warning (level 1) C4003 + - name: Compiler warning (level 1, Error) C4003 href: compiler-warnings/compiler-warning-level-1-c4003.md - name: Compiler warning (level 1) C4005 href: compiler-warnings/compiler-warning-level-1-c4005.md - name: Compiler warning (level 1) C4006 href: compiler-warnings/compiler-warning-level-1-c4006.md - - name: Compiler warning (level 2) C4007 + - name: Compiler warning (level 3) C4007 href: compiler-warnings/compiler-warning-level-2-c4007.md - name: Compiler warning (levels 2 and 3) C4008 href: compiler-warnings/compiler-warning-levels-2-and-3-c4008.md @@ -3205,7 +3249,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4049.md - name: Compiler warning (level 2) C4051 href: compiler-warnings/compiler-warning-level-2-c4051.md - - name: Compiler warning (level 1) C4052 + - name: Compiler warning (level 1 and level 4) C4052 href: compiler-warnings/compiler-warning-level-1-c4052.md - name: Compiler warning (level 4) C4053 href: compiler-warnings/compiler-warning-level-4-c4053.md @@ -3215,9 +3259,9 @@ items: href: compiler-warnings/compiler-warning-level-2-c4056.md - name: Compiler warning (level 4) C4057 href: compiler-warnings/compiler-warning-level-4-c4057.md - - name: Compiler warning (level 4) C4061 + - name: Compiler warning (level 4, off) C4061 href: compiler-warnings/compiler-warning-level-4-c4061.md - - name: Compiler warning (level 4) C4062 + - name: Compiler warning (level 4, off) C4062 href: compiler-warnings/compiler-warning-level-4-c4062.md - name: Compiler warning (level 3) C4066 href: compiler-warnings/compiler-warning-level-3-c4066.md @@ -3255,7 +3299,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4089.md - name: Compiler warning (level 1) C4090 href: compiler-warnings/compiler-warning-level-1-c4090.md - - name: Compiler warning (level 1) C4091 + - name: Compiler warning (level 1 and level 2) C4091 href: compiler-warnings/compiler-warning-level-1-c4091.md - name: Compiler warning (level 4) C4092 href: compiler-warnings/compiler-warning-level-4-c4092.md @@ -3271,7 +3315,7 @@ items: href: compiler-warnings/compiler-warning-level-2-c4099.md - name: Compiler warning (level 4) C4100 href: compiler-warnings/compiler-warning-level-4-c4100.md - - name: Compiler warning (level 3) C4101 + - name: Compiler warning (level 3 and level 4) C4101 href: compiler-warnings/compiler-warning-level-3-c4101.md - name: Compiler warning (level 3) C4102 href: compiler-warnings/compiler-warning-level-3-c4102.md @@ -3279,7 +3323,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4103.md - name: Compiler warning (level 1) C4109 href: compiler-warnings/compiler-warning-level-1-c4109.md - - name: Compiler warning (levels 1 and 4) C4112 + - name: Compiler warning (level 1 and level 4) C4112 href: compiler-warnings/compiler-warning-levels-1-and-4-c4112.md - name: Compiler warning (level 1) C4113 href: compiler-warnings/compiler-warning-level-1-c4113.md @@ -3313,11 +3357,11 @@ items: href: compiler-warnings/compiler-warning-level-4-c4131.md - name: Compiler warning (level 4) C4132 href: compiler-warnings/compiler-warning-level-4-c4132.md - - name: Compiler warning (level 3) C4133 + - name: Compiler warning (level 1 and level 3) C4133 href: compiler-warnings/compiler-warning-level-3-c4133.md - name: Compiler warning (level 1) C4138 href: compiler-warnings/compiler-warning-level-1-c4138.md - - name: Compiler warning (level 1) C4141 + - name: Compiler warning (level 1, Error) C4141 href: compiler-warnings/compiler-warning-level-1-c4141.md - name: Compiler warning (level 1) C4142 href: compiler-warnings/compiler-warning-level-1-c4142.md @@ -3357,7 +3401,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4163.md - name: Compiler warning (level 1) C4164 href: compiler-warnings/compiler-warning-level-1-c4164.md - - name: Compiler warning (level 1) C4165 + - name: Compiler warning (level 3, off) C4165 href: compiler-warnings/compiler-warning-level-1-c4165.md - name: Compiler warning (level 1) C4166 href: compiler-warnings/compiler-warning-level-1-c4166.md @@ -3391,20 +3435,20 @@ items: href: compiler-warnings/compiler-warning-level-1-c4186.md - name: Compiler warning (level 1) C4187 href: compiler-warnings/compiler-warning-level-1-c4187.md - - name: Compiler warning (level 4) C4189 + - name: Compiler warning (level 3 and level 4) C4189 href: compiler-warnings/compiler-warning-level-4-c4189.md - name: Compiler warning (level 1) C4190 href: compiler-warnings/compiler-warning-level-1-c4190.md - - name: Compiler warning (level 3) C4191 + - name: Compiler warning (level 3, off) C4191 href: compiler-warnings/compiler-warning-level-3-c4191.md - name: Compiler warning (level 3) C4192 href: compiler-warnings/compiler-warning-level-3-c4192.md - name: Compiler warning (level 3) C4197 href: compiler-warnings/compiler-warning-level-3-c4197.md - - name: Compiler warnings C4200 Through C4399 + - name: Compiler warnings C4200 through C4399 expanded: false items: - - name: Compiler warnings C4200 Through C4399 + - name: Compiler warnings C4200 through C4399 href: compiler-warnings/compiler-warnings-c4200-through-c4399.md - name: Compiler warning (levels 2 and 4) C4200 href: compiler-warnings/compiler-warning-levels-2-and-4-c4200.md @@ -3488,19 +3532,19 @@ items: href: compiler-warnings/compiler-warning-level-1-c4251.md - name: Compiler warning (level 4) C4254 href: compiler-warnings/compiler-warning-level-4-c4254.md - - name: Compiler warning (level 4) C4255 + - name: Compiler warning (level 4, off) C4255 href: compiler-warnings/compiler-warning-level-4-c4255.md - name: Compiler warning (level 4) C4256 href: compiler-warnings/compiler-warning-level-4-c4256.md - name: Compiler warning (level 1) C4258 href: compiler-warnings/compiler-warning-level-1-c4258.md - - name: Compiler warning (level 4) C4263 + - name: Compiler warning (level 4, off) C4263 href: compiler-warnings/compiler-warning-level-4-c4263.md - - name: Compiler warning (level 1) C4264 + - name: Compiler warning (level 4, off) C4264 href: compiler-warnings/compiler-warning-level-1-c4264.md - - name: Compiler warning (level 3) C4265 + - name: Compiler warning (level 3, off) C4265 href: compiler-warnings/compiler-warning-level-3-c4265.md - - name: Compiler warning (level 4) C4266 + - name: Compiler warning (level 4, off) C4266 href: compiler-warnings/compiler-warning-level-4-c4266.md - name: Compiler warning (level 3) C4267 href: compiler-warnings/compiler-warning-level-3-c4267.md @@ -3518,7 +3562,7 @@ items: href: compiler-warnings/compiler-warning-level-2-c4275.md - name: Compiler warning (level 1) C4276 href: compiler-warnings/compiler-warning-level-1-c4276.md - - name: Compiler warning (level 3) C4278 + - name: Compiler warning (level 3 and level 4) C4278 href: compiler-warnings/compiler-warning-level-3-c4278.md - name: Compiler warning (level 3) C4280 href: compiler-warnings/compiler-warning-level-3-c4280.md @@ -3532,11 +3576,11 @@ items: href: compiler-warnings/compiler-warning-level-2-c4285.md - name: Compiler warning (level 1) C4286 href: compiler-warnings/compiler-warning-level-1-c4286.md - - name: Compiler warning (level 3) C4287 + - name: Compiler warning (level 3, off) C4287 href: compiler-warnings/compiler-warning-level-3-c4287.md - name: Compiler warning (level 1) C4288 href: compiler-warnings/compiler-warning-level-1-c4288.md - - name: Compiler warning (level 4) C4289 + - name: Compiler warning (level 4, off) C4289 href: compiler-warnings/compiler-warning-level-4-c4289.md - name: Compiler warning (level 3) C4290 href: compiler-warnings/compiler-warning-level-3-c4290.md @@ -3546,7 +3590,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4293.md - name: Compiler warning (level 4) C4295 href: compiler-warnings/compiler-warning-level-4-c4295.md - - name: Compiler warning (level 4) C4296 + - name: Compiler warning (level 4, off) C4296 href: compiler-warnings/compiler-warning-level-4-c4296.md - name: Compiler warning (level 1) C4297 href: compiler-warnings/compiler-warning-level-1-c4297.md @@ -3562,7 +3606,7 @@ items: href: compiler-warnings/compiler-warning-level-2-c4308.md - name: Compiler warning (level 2) C4309 href: compiler-warnings/compiler-warning-level-2-c4309.md - - name: Compiler warning (level 3) C4310 + - name: Compiler warning (level 4) C4310 href: compiler-warnings/compiler-warning-level-3-c4310.md - name: Compiler warning (level 1) C4311 href: compiler-warnings/compiler-warning-level-1-c4311.md @@ -3586,17 +3630,17 @@ items: href: compiler-warnings/compiler-warning-level-1-c4333.md - name: Compiler warning (level 3) C4334 href: compiler-warnings/compiler-warning-level-3-c4334.md - - name: Compiler warning C4335 + - name: Compiler warning (level 1) C4335 href: compiler-warnings/compiler-warning-c4335.md - name: Compiler warning (level 4) C4336 href: compiler-warnings/compiler-warning-level-4-c4336.md - name: Compiler warning (level 4) C4337 href: compiler-warnings/compiler-warning-level-4-c4337.md - - name: Compiler warning (level 4) C4339 + - name: Compiler warning (level 4, off) C4339 href: compiler-warnings/compiler-warning-level-4-c4339.md - name: Compiler warning (level 1) C4340 href: compiler-warnings/compiler-warning-level-1-c4340.md - - name: Compiler warning (level 1) C4342 + - name: Compiler warning (level 1, no longer emitted) C4342 href: compiler-warnings/compiler-warning-level-1-c4342.md - name: Compiler warning (level 4) C4343 href: compiler-warnings/compiler-warning-level-4-c4343.md @@ -3606,7 +3650,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4346.md - name: Compiler warning (level 1) C4348 href: compiler-warnings/compiler-warning-level-1-c4348.md - - name: Compiler warning (level 1) C4350 + - name: Compiler warning (level 1, no longer emitted) C4350 href: compiler-warnings/compiler-warning-level-1-c4350.md - name: Compiler warning (level 1) C4353 href: compiler-warnings/compiler-warning-level-1-c4353.md @@ -3618,21 +3662,21 @@ items: href: compiler-warnings/compiler-warning-level-3-c4357.md - name: Compiler warning (level 1) C4358 href: compiler-warnings/compiler-warning-level-1-c4358.md - - name: Compiler warning (level 3) C4359 + - name: Compiler warning (level 1 and level 3) C4359 href: compiler-warnings/compiler-warning-level-3-c4359.md - name: Compiler warning (level 1) C4364 href: compiler-warnings/compiler-warning-level-1-c4364.md - - name: Compiler warning (level 4) C4365 + - name: Compiler warning (level 4, off) C4365 href: compiler-warnings/compiler-warning-level-4-c4365.md - name: Compiler warning (level 4) C4366 href: compiler-warnings/compiler-warning-level-4-c4366.md - - name: Compiler warning C4368 + - name: Compiler warning (level 1, Error) C4368 href: compiler-warnings/compiler-warning-c4368.md - name: Compiler warning (level 1) C4369 href: compiler-warnings/compiler-warning-level-1-c4369.md - - name: Compiler warning (level 3) C4371 + - name: Compiler warning (level 3, off) C4371 href: compiler-warnings/c4371.md - - name: Compiler warning (level 3) C4373 + - name: Compiler warning (level 4) C4373 href: compiler-warnings/compiler-warning-level-3-c4373.md - name: Compiler warning (level 1) C4374 href: compiler-warnings/compiler-warning-level-1-c4374.md @@ -3654,7 +3698,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4383.md - name: Compiler warning (level 1) C4384 href: compiler-warnings/compiler-warning-level-1-c4384.md - - name: Compiler warning (level 4) C4388 + - name: Compiler warning (level 4, off) C4388 href: compiler-warnings/c4388.md - name: Compiler warning (level 4) C4389 href: compiler-warnings/compiler-warning-level-4-c4389.md @@ -3662,11 +3706,11 @@ items: href: compiler-warnings/compiler-warning-level-3-c4390.md - name: Compiler warning (level 1) C4391 href: compiler-warnings/compiler-warning-level-1-c4391.md - - name: Compiler warning (level 1) C4392 + - name: Compiler warning (level 1, Error) C4392 href: compiler-warnings/compiler-warning-level-1-c4392.md - name: Compiler warning (level 1) C4393 href: compiler-warnings/compiler-warning-level-1-c4393.md - - name: Compiler warning C4394 + - name: Compiler warning (level 1, Error) C4394 href: compiler-warnings/compiler-warning-c4394.md - name: Compiler warning (level 1) C4395 href: compiler-warnings/compiler-warning-level-1-c4395.md @@ -3676,14 +3720,14 @@ items: href: compiler-warnings/compiler-warning-level-1-c4397.md - name: Compiler warning (level 3) C4398 href: compiler-warnings/compiler-warning-level-3-c4398.md - - name: Compiler warning (level 1) C4399 + - name: Compiler warning (level 1, Error) C4399 href: compiler-warnings/compiler-warning-level-1-c4399.md - - name: Compiler warnings C4400 Through C4599 + - name: Compiler warnings C4400 through C4599 expanded: false items: - - name: Compiler warnings C4400 Through C4599 + - name: Compiler warnings C4400 through C4599 href: compiler-warnings/compiler-warnings-c4400-through-c4599.md - - name: Compiler warning (level 4) C4400 + - name: Compiler warning (level 4, Error) C4400 href: compiler-warnings/compiler-warning-level-4-c4400.md - name: Compiler warning (level 1) C4401 href: compiler-warnings/compiler-warning-level-1-c4401.md @@ -3707,7 +3751,7 @@ items: href: compiler-warnings/compiler-warning-level-1-c4410.md - name: Compiler warning (level 1) C4411 href: compiler-warnings/compiler-warning-level-1-c4411.md - - name: Compiler warning (level 2) C4412 + - name: Compiler warning (level 2, off) C4412 href: compiler-warnings/compiler-warning-level-2-c4412.md - name: Compiler warning (level 3) C4414 href: compiler-warnings/compiler-warning-level-3-c4414.md @@ -3715,19 +3759,19 @@ items: href: compiler-warnings/compiler-warning-level-1-c4420.md - name: Compiler warning (level 4) C4429 href: compiler-warnings/compiler-warning-level-4-c4429.md - - name: Compiler warning C4430 + - name: Compiler warning (level 1, Error) C4430 href: compiler-warnings/compiler-warning-c4430.md - name: Compiler warning (level 4) C4431 href: compiler-warnings/compiler-warning-level-4-c4431.md - name: Compiler warning (level 4) C4434 href: compiler-warnings/compiler-warning-level-4-c4434.md - - name: Compiler warning (level 4) C4435 + - name: Compiler warning (level 4, off) C4435 href: compiler-warnings/compiler-warning-level-4-c4435.md - - name: Compiler warning (level 1) C4436 + - name: Compiler warning (level 1 and level 4) C4436 href: compiler-warnings/compiler-warning-level-1-c4436.md - - name: Compiler warning (level 4) C4437 + - name: Compiler warning (level 1 and level 4, off) C4437 href: compiler-warnings/compiler-warning-level-4-c4437.md - - name: Compiler warning C4439 + - name: Compiler warning (level 1, Error) C4439 href: compiler-warnings/compiler-warning-c4439.md - name: Compiler warning (level 1) C4440 href: compiler-warnings/compiler-warning-level-1-c4440.md @@ -3735,13 +3779,13 @@ items: href: compiler-warnings/compiler-warning-level-1-c4441.md - name: Compiler warning (level 1) C4445 href: compiler-warnings/compiler-warning-level-1-c4445.md - - name: Compiler warning (level 4) C4456 + - name: Compiler warning (level 1 and level 4) C4456 href: compiler-warnings/compiler-warning-level-4-c4456.md - - name: Compiler warning (level 4) C4457 + - name: Compiler warning (level 1 and level 4) C4457 href: compiler-warnings/compiler-warning-level-4-c4457.md - - name: Compiler warning (level 4) C4458 + - name: Compiler warning (level 1 and level 4) C4458 href: compiler-warnings/compiler-warning-level-4-c4458.md - - name: Compiler warning (level 4) C4459 + - name: Compiler warning (level 1 and level 4) C4459 href: compiler-warnings/compiler-warning-level-4-c4459.md - name: Compiler warning (level 4) C4460 href: compiler-warnings/compiler-warning-level-4-c4460.md @@ -3751,21 +3795,21 @@ items: href: compiler-warnings/compiler-warning-level-1-c4462.md - name: Compiler warning (level 4) C4463 href: compiler-warnings/compiler-warning-level-4-c4463.md - - name: Compiler warning (level 4) C4464 + - name: Compiler warning (level 4, off) C4464 href: compiler-warnings/compiler-warning-level-4-c4464.md - name: Compiler warning (level 1) C4470 href: compiler-warnings/compiler-warning-level-1-c4470.md - - name: Compiler warning (level 4) C4471 + - name: Compiler warning (level 4, off) C4471 href: compiler-warnings/compiler-warning-level-4-c4471.md - name: Compiler warning (level 1) C4473 href: compiler-warnings/c4473.md - name: Compiler warning (level 1) C4477 href: compiler-warnings/c4477.md - - name: Compiler warning (level 4) C4481 + - name: Compiler warning (level 4, Error) C4481 href: compiler-warnings/compiler-warning-level-4-c4481.md - - name: Compiler warning C4484 + - name: Compiler warning (level 1, Error) C4484 href: compiler-warnings/compiler-warning-c4484.md - - name: Compiler warning C4485 + - name: Compiler warning (level 1, Error) C4485 href: compiler-warnings/compiler-warning-c4485.md - name: Compiler warning (level 1) C4486 href: compiler-warnings/compiler-warning-level-1-c4486.md @@ -3789,13 +3833,13 @@ items: href: compiler-warnings/compiler-warning-level-1-c4508.md - name: Compiler warning (level 4) C4510 href: compiler-warnings/compiler-warning-level-4-c4510.md - - name: Compiler warning (level 3) C4511 + - name: Compiler warning (level 4) C4511 href: compiler-warnings/compiler-warning-level-3-c4511.md - name: Compiler warning (level 4) C4512 href: compiler-warnings/compiler-warning-level-4-c4512.md - name: Compiler warning (level 4) C4513 href: compiler-warnings/compiler-warning-level-4-c4513.md - - name: Compiler warning (level 4) C4514 + - name: Compiler warning (level 4, off) C4514 href: compiler-warnings/compiler-warning-level-4-c4514.md - name: Compiler warning (level 4) C4515 href: compiler-warnings/compiler-warning-level-4-c4515.md @@ -3823,7 +3867,7 @@ items: href: compiler-warnings/compiler-warning-level-3-c4534.md - name: Compiler warning (level 3) C4535 href: compiler-warnings/compiler-warning-level-3-c4535.md - - name: Compiler warning (level 4) C4536 + - name: Compiler warning (level 4, off) C4536 href: compiler-warnings/compiler-warning-level-4-c4536.md - name: Compiler warning (level 1) C4537 href: compiler-warnings/compiler-warning-level-1-c4537.md @@ -3837,15 +3881,15 @@ items: href: compiler-warnings/compiler-warning-level-3-c4543.md - name: Compiler warning (level 1) C4544 href: compiler-warnings/compiler-warning-level-1-c4544.md - - name: Compiler warning (level 1) C4545 + - name: Compiler warning (level 1, off) C4545 href: compiler-warnings/compiler-warning-level-1-c4545.md - - name: Compiler warning (level 1) C4546 + - name: Compiler warning (level 1, off) C4546 href: compiler-warnings/compiler-warning-level-1-c4546.md - - name: Compiler warning (level 1) C4547 + - name: Compiler warning (level 1, off) C4547 href: compiler-warnings/compiler-warning-level-1-c4547.md - - name: Compiler warning (level 1) C4548 + - name: Compiler warning (level 1, off) C4548 href: compiler-warnings/compiler-warning-level-1-c4548.md - - name: Compiler warning (level 1) C4549 + - name: Compiler warning (level 1, off) C4549 href: compiler-warnings/compiler-warning-level-1-c4549.md - name: Compiler warning (level 1) C4550 href: compiler-warnings/compiler-warning-level-1-c4550.md @@ -3857,11 +3901,11 @@ items: href: compiler-warnings/compiler-warning-level-1-c4553.md - name: Compiler warning (level 3) C4554 href: compiler-warnings/compiler-warning-level-3-c4554.md - - name: Compiler warning (level 1) C4555 + - name: Compiler warning (level 1, off) C4555 href: compiler-warnings/compiler-warning-level-1-c4555.md - name: Compiler warning (level 1) C4556 href: compiler-warnings/compiler-warning-level-1-c4556.md - - name: Compiler warning (level 3) C4557 + - name: Compiler warning (level 3, off) C4557 href: compiler-warnings/compiler-warning-level-3-c4557.md - name: Compiler warning (level 1) C4558 href: compiler-warnings/compiler-warning-level-1-c4558.md @@ -3889,14 +3933,14 @@ items: href: compiler-warnings/compiler-warning-level-1-c4581.md - name: Compiler warning (level 1) C4584 href: compiler-warnings/compiler-warning-level-1-c4584.md - - name: Compiler warning (level 4) C4596 + - name: Compiler warning (level 4, Error, off) C4596 href: compiler-warnings/c4596.md - name: Compiler warning (level 4) C4597 href: compiler-warnings/c4597.md - - name: Compiler warnings C4600 Through C4799 + - name: Compiler warnings C4600 through C4799 expanded: false items: - - name: Compiler warnings C4600 Through C4799 + - name: Compiler warnings C4600 through C4799 href: compiler-warnings/compiler-warnings-c4600-through-c4799.md - name: Compiler warning (level 1) C4600 href: compiler-warnings/compiler-warning-level-1-c4600.md @@ -4112,6 +4156,8 @@ items: href: compiler-warnings/compiler-warning-level-4-c4764.md - name: Compiler warning (level 4) C4768 href: compiler-warnings/c4768.md + - name: Compiler warning (level 4) C4770 + href: compiler-warnings/c4770.md - name: Compiler warning (level 1) C4772 href: compiler-warnings/compiler-warning-level-1-c4772.md - name: Compiler warning (Level 1) C4788 @@ -4126,10 +4172,10 @@ items: href: compiler-warnings/compiler-warning-level-1-c4794.md - name: Compiler warning (level 1) C4799 href: compiler-warnings/compiler-warning-level-1-c4799.md - - name: Compiler warnings C4800 Through C5999 + - name: Compiler warnings C4800 through C4999 expanded: false items: - - name: Compiler warnings C4800 Through C5999 + - name: Compiler warnings C4800 through C4999 href: compiler-warnings/compiler-warnings-c4800-through-c4999.md - name: Compiler warning (level 3) C4800 href: compiler-warnings/compiler-warning-level-3-c4800.md @@ -4283,8 +4329,11 @@ items: href: compiler-warnings/compiler-warning-level-3-c4996.md - name: Compiler warning (level 1) C4997 href: compiler-warnings/compiler-warning-level-1-c4997.md - - name: Compiler warning (level 1) C4999 - href: compiler-warnings/compiler-warning-level-1-c4999.md + - name: Compiler warnings C5000 through C5199 + expanded: false + items: + - name: Compiler warnings C5000 through C5199 + href: compiler-warnings/compiler-warnings-c5000-through-c5199.md - name: Compiler warning (level 1) C5033 href: compiler-warnings/c5033.md - name: Compiler warning C5037 @@ -4297,16 +4346,39 @@ items: href: compiler-warnings/c5046.md - name: Compiler warning C5050 href: compiler-warnings/c5050.md + - name: Compiler warning (level 4) C5054 + href: compiler-warnings/c5054.md + - name: Compiler warning (level 1) C5055 + href: compiler-warnings/c5055.md + - name: Compiler warning (level 1) C5056 + href: compiler-warnings/c5056.md + - name: Compiler warning (level 1) C5072 + href: compiler-warnings/compiler-warning-c5072.md - name: Compiler warning (level 1) C5105 href: compiler-warnings/c5105.md + - name: Compiler warnings C5200 through C5399 + expanded: false + items: + - name: Compiler warnings C5200 through C5399 + href: compiler-warnings/compiler-warnings-c5200-through-c5399.md - name: Compiler warning (level 1) C5208 href: compiler-warnings/c5208.md + - name: Compiler warning (level 1) C5240 + href: compiler-warnings/c5240.md - name: Compiler warning (level 1) C5243 href: compiler-warnings/c5243.md - name: Compiler warning (level 1) C5247 href: compiler-warnings/c5247.md - name: Compiler warning (level 1) C5248 href: compiler-warnings/c5248.md + - name: Compiler warning (level 1, error, off) C5262 + href: compiler-warnings/c5262.md + - name: Compiler warning (level 4) C5266 + href: compiler-warnings/compiler-warning-level-4-c5266.md + - name: Compiler warning (level 4) C5267 + href: compiler-warnings/c5267.md + - name: Compiler warning (level 1) C5301 and C5302 + href: compiler-warnings/c5301-c5302.md - name: Compiler warnings by compiler version href: compiler-warnings/compiler-warnings-by-compiler-version.md - name: Compiler warnings that are off by default @@ -4547,6 +4619,8 @@ items: href: tool-errors/linker-tools-error-lnk1168.md - name: Linker tools error LNK1169 href: tool-errors/linker-tools-error-lnk1169.md + - name: Linker tools error LNK1170 + href: tool-errors/linker-tools-error-lnk1170.md - name: Linker tools error LNK1179 href: tool-errors/linker-tools-error-lnk1179.md - name: Linker tools error LNK1181 @@ -4765,10 +4839,14 @@ items: href: tool-errors/linker-tools-warning-lnk4254.md - name: Linker tools warning LNK4286 href: tool-errors/linker-tools-warning-lnk4286.md + - name: Linker tools warning LNK4306 + href: tool-errors/linker-tools-warning-lnk4306.md + - name: Linker tools warning LNK4307 + href: tool-errors/linker-tools-warning-lnk4307.md - name: Math errors expanded: false items: - - name: Math errors (Mxxxx) + - name: Math errors (M6101 through M6205) href: tool-errors/math-errors-m6101-through-m6205.md - name: Math error M6101 href: tool-errors/math-error-m6101.md diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6017.md b/docs/error-messages/tool-errors/c-runtime-error-r6017.md index 45d4f87130..b6c878e78a 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6017.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6017.md @@ -23,4 +23,4 @@ unexpected multithread lock error The process received an unexpected error while trying to access a C runtime multithread lock on a system resource. This error usually occurs if the process inadvertently alters the runtime heap data. However, it can also be caused by an internal error in the runtime library or operating-system code. -To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). +To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT debug heap details](../../c-runtime-library/crt-debug-heap-details.md). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6018.md b/docs/error-messages/tool-errors/c-runtime-error-r6018.md index fc35736331..9736151410 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6018.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6018.md @@ -25,4 +25,4 @@ The program encountered an unexpected error while performing a memory-management This error usually occurs if the program inadvertently alters the run-time heap data. However, it can also be caused by an internal error in the runtime or operating-system code. -To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). +To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT Debug Heap Details](../../c-runtime-library/crt-debug-heap-details.md). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6028.md b/docs/error-messages/tool-errors/c-runtime-error-r6028.md index 7213f00140..1f93ef783e 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6028.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6028.md @@ -25,4 +25,4 @@ unable to initialize heap This error occurs when the operating system failed to create the memory pool for the application. Specifically, the C Runtime (CRT) called the Win32 function `HeapCreate`, which returned NULL indicating failure. -If this error occurs during app startup, the system may be unable to satisfy heap requests because defective drivers are loaded. Check Windows Update or your hardware vendor’s web site for updated drivers. +If this error occurs during app startup, the system may be unable to satisfy heap requests because defective drivers are loaded. Check Windows Update or your hardware vendor's web site for updated drivers. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md index dd048dc35b..dd6c44187f 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md @@ -20,9 +20,9 @@ There are many other possible causes for this error. To narrow them down, first ## Can't open your app or its .pdb file -### Your app is running, or it's loaded in the debugger +### Your app is running, or is loaded in the debugger -When *filename* is your executable's name, or an associated .pdb file, see if your application is already running. Then check whether it's loaded in a debugger. To fix this issue, stop the program and unload it from the debugger before building it again. If the app is open in another program, such as a resource editor, close it. If your program is unresponsive, you may need to use Task Manager to end the process. You might also need to close and restart Visual Studio. +When *filename* is your executable's name, or an associated .pdb file, see if your application is already running. Then check whether it's loaded in a debugger. To fix this issue, stop the program and unload it from the debugger before building it again. If the app is open in another program, such as a resource editor, close it. If your program is unresponsive, you might need to use Task Manager to end the process. You might also need to close and restart Visual Studio. ### Your app is locked by an antivirus scan @@ -32,51 +32,51 @@ Antivirus programs often temporarily block access to newly created files, especi ### Windows libraries, such as kernel32.lib -If the file that can't be opened is one of the standard library files provided by Microsoft, such as *kernel32.lib*, you may have a project configuration error or an installation error. Verify the Windows SDK has been installed. If your project requires other Microsoft libraries, such as MFC, make sure the MFC components were also installed by the Visual Studio installer. You can run the installer again to add optional components at any time. For more information, see [Modify Visual Studio](/visualstudio/install/modify-visual-studio). Use the **Individual components** tab in the installer to choose specific libraries and SDKs. +If the file that can't be opened is one of the standard library files provided by Microsoft, such as *kernel32.lib*, you might have a project configuration error or an installation error. Verify the Windows SDK is installed. If your project requires other Microsoft libraries, such as MFC, make sure the MFC components were also installed by the Visual Studio installer. You can run the installer again to add optional components at any time. For more information, see [Modify Visual Studio](/visualstudio/install/modify-visual-studio). Use the **Individual components** tab in the installer to choose specific libraries and SDKs. ### Versioned vcruntime libraries -If the error message has a versioned Microsoft library such as *msvcr120.lib*, the platform toolset for that compiler version may not be installed. To fix this issue, you have two options: Upgrade the project to use the current platform toolset, or install the older toolset and build the project unchanged. For more information, see [Upgrading Projects from Earlier Versions of Visual C++](../../porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md) and [Use native multi-targeting in Visual Studio to build old projects](../../porting/use-native-multi-targeting.md). +If the error message has a versioned Microsoft library such as *msvcr120.lib*, the platform toolset for that compiler version might not be installed. To fix this issue, you have two options: Upgrade the project to use the current platform toolset, or install the older toolset and build the project unchanged. For more information, see [Upgrading Projects from Earlier Versions of Visual C++](../../porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md) and [Use native multi-targeting in Visual Studio to build old projects](../../porting/use-native-multi-targeting.md). ### Retail, Debug, or platform-specific libraries -The error may occur when you first build for a new target platform or configuration, such as Retail, or ARM64. In the IDE, verify the **Platform toolset** and **Windows SDK Version** specified in the [General property page](../../build/reference/general-property-page-project.md) are installed. Also verify the required libraries are available in the **Library Directories** specified in the [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). Check the properties for each configuration, such as Debug, Retail, x86, or ARM64. If one build works but another doesn't, compare the settings for both. Install any missing required tools and libraries. +The error might occur when you first build for a new target platform or configuration, such as Retail, or ARM64. In the IDE, verify the **Platform toolset** and **Windows SDK Version** specified in the [General property page](../../build/reference/general-property-page-project.md) are installed. Also verify the required libraries are available in the **Library Directories** specified in the [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). Check the properties for each configuration, such as Debug, Retail, x86, or ARM64. If one build works but another doesn't, compare the settings for both. Install any missing required tools and libraries. ### The vccorlib.lib library -There are no Spectre-mitigated libraries for Universal Windows (UWP) apps or components. If the error message includes *vccorlib.lib*, you may have enabled [/Qspectre](../../build/reference/qspectre.md) in a UWP project. Disable the **/Qspectre** compiler option to fix this issue. In Visual Studio, change the **Spectre Mitigation** property. It's found in the **C/C++** > **Code Generation** page of the project **Property Pages** dialog. +There are no Spectre-mitigated libraries for Universal Windows (UWP) apps or components. If the error message includes *vccorlib.lib*, you might have enabled [`/Qspectre`](../../build/reference/qspectre.md) in a UWP project. Disable the **`/Qspectre`** compiler option to fix this issue. In Visual Studio, change the **Spectre Mitigation** property. It's in the **C/C++** > **Code Generation** page of the project **Property Pages** dialog. ### Libraries in projects from online or other sources -If you build a project copied from another computer, the library installation locations may be different. For command-line builds, verify the LIB environment variable and library paths are set correctly for the build. In Visual Studio, you can see and edit the current library paths set in the Property pages for your project. In the **VC++ Directories** page, choose the drop-down control for the **Library Directories** property, then choose **Edit**. The **Evaluated value** section of the **Library Directories** dialog lists the current paths searched for library files. Update these paths to point to your local libraries. +If you build a project copied from another computer, the library installation locations might be different. For command-line builds, verify the LIB environment variable and library paths are set correctly for the build. In Visual Studio, you can see and edit the current library paths set in the Property pages for your project. In the **VC++ Directories** page, choose the drop-down control for the **Library Directories** property, then choose **Edit**. The **Evaluated value** section of the **Library Directories** dialog lists the current paths searched for library files. Update these paths to point to your local libraries. ### Updated Windows SDK libraries -This error can occur when the Visual Studio path to the Windows SDK is out of date. It may happen if you install a newer Windows SDK independently of the Visual Studio installer. To fix it in the IDE, update the paths specified in the [VC++ Directories property page](../../build/reference/vcpp-directories-property-page.md). Set the version in the path to match the new SDK. If you use the Developer Command Prompt, update the batch file that initializes the environment variables with the new SDK paths. This problem can be avoided by using the Visual Studio installer to install updated SDKs. +This error can occur when the Visual Studio path to the Windows SDK is out of date. It might happen if you install a newer Windows SDK independently of the Visual Studio installer. To fix it in the IDE, update the paths specified in the [VC++ Directories property page](../../build/reference/vcpp-directories-property-page.md). Set the version in the path to match the new SDK. If you use the Developer Command Prompt, update the batch file that initializes the environment variables with the new SDK paths. This problem can be avoided by using the Visual Studio installer to install updated SDKs. ## Can't open a third-party library file There are several common causes for this issue: -- The path to your library file may be incorrect, or not wrapped in double-quotes. Or, you may not have specified it to the linker. +- The path to your library file might be incorrect, or not wrapped in double-quotes. Or, you might not have specified it to the linker. -- You may have installed a 32-bit version of the library but you're building for 64 bits, or the other way around. +- You might have installed a 32-bit version of the library but you're building for 64 bits, or the other way around. -- The library may have dependencies on other libraries that aren't installed. +- The library might have dependencies on other libraries that aren't installed. To fix a path issue for command-line builds, verify the LIB environment variable is set. Make sure it includes paths for all the libraries you use, and for every configuration you build. In the IDE, the library paths get set by the **VC++ Directories** > **Library Directories** property. Make sure all the directories that contain the libraries you need are listed here, for every configuration you build. -You might need to supply a library directory that overrides a standard library directory. On the command line, use the [/LIBPATH](../../build/reference/libpath-additional-libpath.md) option. In the IDE, use the **Additional Library Directories** property in the **Configuration Properties > Linker > General** property page for your project. +You might need to supply a library directory that overrides a standard library directory. On the command line, use the [`/LIBPATH`](../../build/reference/libpath-additional-libpath.md) option. In the IDE, use the **Additional Library Directories** property in the **Configuration Properties > Linker > General** property page for your project. -Make sure you install every version of the library you need for the configurations you build. Consider using the [vcpkg](https://vcpkg.io/) package management utility to automate the installation and setup for many common libraries. When you can, it's best to build your own copies of third-party libraries. Then you're sure to have all the libraries' local dependencies, built for the same configurations as your project. +Make sure you install every version of the library you need for the configurations you build. Consider using the [vcpkg](/vcpkg/) package management utility to automate the installation and setup for many common libraries. When you can, it's best to build your own copies of third-party libraries. Then you're sure to have all the libraries' local dependencies, built for the same configurations as your project. ## Can't open a file built by your project -You may see this error if *filename* doesn't exist yet when the linker tries to access it. It can happen when one project depends on another in the solution, but the projects build in the wrong order. To fix this issue, make sure your project references are set in the project that uses the file. Then the missing file gets built before it's required. For more information, see [Adding references in Visual Studio C++ projects](../../build/adding-references-in-visual-cpp-projects.md) and [Managing references in a project](/visualstudio/ide/managing-references-in-a-project). +You might see this error if *filename* doesn't exist yet when the linker tries to access it. It can happen when one project depends on another in the solution, but the projects build in the wrong order. To fix this issue, make sure your project references are set in the project that uses the file. Then the missing file gets built before it's required. For more information, see [Adding references in Visual Studio C++ projects](../../build/adding-references-in-visual-cpp-projects.md) and [Managing references in a project](/visualstudio/ide/managing-references-in-a-project). ## Can't open file 'C:\\Program.obj' -If you see the filename *C:\\Program.obj* in the error message, wrap your library paths in double quotes. This error happens when an unwrapped path that begins with *C:\\Program Files* gets passed to the linker. Unwrapped paths may also cause similar errors. Typically, they show an unexpected .obj file in the root of your drive. +If you see the filename *C:\\Program.obj* in the error message, wrap your library paths in double quotes. This error happens when an unwrapped path that begins with *C:\\Program Files* gets passed to the linker. Unwrapped paths might also cause similar errors. Typically, they show an unexpected .obj file in the root of your drive. To fix this issue for command-line builds, check the [/LIBPATH](../../build/reference/libpath-additional-libpath.md) option parameters. Also check the paths specified in the LIB environment variable, and the paths specified on the command line. Make sure to use double-quotes around any paths that include spaces. @@ -96,7 +96,7 @@ This error can occur when the library filename or path specified to the linker i ### Parallel build synchronization -If you're using a parallel build option, Visual Studio may have locked the file on another thread. To fix this issue, verify the same code object or library isn't built in multiple projects. Use build dependencies or project references to pick up built binaries in your project. +If you're using a parallel build option, Visual Studio might have locked the file on another thread. To fix this issue, verify the same code object or library isn't built in multiple projects. Use build dependencies or project references to pick up built binaries in your project. ### Additional dependencies specified in the IDE @@ -104,15 +104,15 @@ When you specify individual libraries in the **Additional Dependencies** propert ### Paths that are too long -You may see this error when the path for *filename* expands to more than 260 characters. If needed, rearrange your directory structure or shorten your folder and file names to shorten the paths. +You might see this error when the path for *filename* expands to more than 260 characters. If needed, rearrange your directory structure or shorten your folder and file names to shorten the paths. ### Files that are too large -This error can occur because the file is too large. Libraries or object files more than a gigabyte in size may cause problems for the 32-bit linker. A possible fix for this issue is to use the 64-bit toolset. For more information on how to use the 64-bit toolset at the command line, see [How to: Enable a 64-Bit Visual C++ Toolset on the Command Line](../../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md). For information on how to use the 64-bit toolset in the IDE, see [Using MSBuild with the 64-bit Compiler and Tools](../../build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md#using-msbuild-to-build-your-project). Also see this Stack Overflow post: [How to make Visual Studio use the native amd64 toolchain](https://stackoverflow.com/questions/19820718/how-to-make-visual-studio-use-the-native-amd64-toolchain/23793055). +This error can occur because the file is too large. Libraries or object files more than a gigabyte in size might cause problems for the 32-bit linker. A possible fix for this issue is to use the 64-bit toolset. For more information on how to use the 64-bit toolset at the command line, see [How to: Enable a 64-Bit Visual C++ Toolset on the Command Line](../../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md). For information on how to use the 64-bit toolset in the IDE, see [Using MSBuild with the 64-bit Compiler and Tools](../../build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md#using-msbuild-to-build-your-project). Also see this Stack Overflow post: [How to make Visual Studio use the native amd64 toolchain](https://stackoverflow.com/questions/19820718/how-to-make-visual-studio-use-the-native-amd64-toolchain/23793055). ### Incorrect file permissions -This error can occur if you have insufficient file permissions to access *filename*. It may happen if you use an ordinary user account to access library files in protected system directories. Or, if you use files copied from other users that still have their original permissions set. To fix this issue, move the file to a writeable project directory. If the moved file has inaccessible permissions, run the takeown.exe command in an Administrator command window to take ownership of the file. +This error can occur if you have insufficient file permissions to access *filename*. It might happen if you use an ordinary user account to access library files in protected system directories. Or, if you use files copied from other users that still have their original permissions set. To fix this issue, move the file to a writeable project directory. If the moved file has inaccessible permissions, run the takeown.exe command in an Administrator command window to take ownership of the file. ### Insufficient disk space @@ -120,10 +120,10 @@ The error can occur when you don't have enough disk space. The linker uses tempo ### Problems in the TMP environment variable -If the *filename* is named LNK*nnn*, it's a filename generated by the linker for a temporary file. The directory specified in the TMP environment variable may not exist. Or, more than one directory may be specified for the TMP environment variable. Only one directory path should be specified for the TMP environment variable. +If the *filename* is named LNK*nnn*, it's a filename generated by the linker for a temporary file. The directory specified in the TMP environment variable might not exist. Or, more than one directory might be specified for the TMP environment variable. Only one directory path should be specified for the TMP environment variable. ## Help, my issue isn't listed here! -When none of the issues listed here apply, you can use the feedback tools in Visual Studio for help. In the IDE, go to the menu bar and choose **Help > Send Feedback > Report a Problem**. Or, submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. You can also use the [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) site for questions, and the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) website. Use these sites to search for answers to questions and ask for help. For more information, see [How to report a problem with the Visual C++ toolset or documentation](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). +When none of the issues listed here apply, you can use the feedback tools in Visual Studio for help. In the IDE, go to the menu bar and choose **Help > Send Feedback > Report a Problem**. Or, submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. You can also use the [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html) site for questions, and the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) website. Use these sites to search for answers to questions and ask for help. For more information, see [How to report a problem with the Visual C++ toolset or documentation](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). -If you've discovered a new way to fix this issue that we should add to this article, let us know. You can send us feedback by using the button below for **this page**. Use it to create a new issue in our [C++ documentation GitHub repo](https://github.com/MicrosoftDocs/cpp-docs/issues). Thanks! +If you've discovered a new way to fix this issue that we should add to this article, let us know. You can send us feedback by using the button below for **This page**. Use it to create a new issue in our [C++ documentation GitHub repo](https://github.com/MicrosoftDocs/cpp-docs/issues). Thanks! diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md index 6582032632..0e62d58797 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Linker Tools Error LNK1112" title: "Linker Tools Error LNK1112" -ms.date: "11/04/2016" +ms.date: 05/23/2022 f1_keywords: ["LNK1112"] helpviewer_keywords: ["LNK1112"] ms.assetid: 425793d8-37e6-4072-9b6e-c3d4e9c12562 @@ -12,16 +12,16 @@ ms.assetid: 425793d8-37e6-4072-9b6e-c3d4e9c12562 ## Remarks -The object files specified as input were compiled for different computer types. +The object files specified as input were compiled for a different target platform. -For example, if you try to link an object file compiled with **/clr** and an object file compiled with **/clr:pure** (machine type CEE), the linker will generate the error LNK1112. The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +For example, if you try to link an object file compiled with **`/clr`** and an object file compiled with **`/clr:pure`** (machine type CEE), the linker will generate the error LNK1112. The **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Similarly, if you create one module with the x64 compiler and another module with the x86 compiler, and try to link them, the linker will generate LNK1112. -A possible reason for this error is if you are developing a 64-bit application but have not installed one of the Visual C++ 64-bit compilers. In this case, 64-bit configurations will not be available. To fix this issue, run the installer for Visual Studio and install the missing C++ components. +A possible reason for this error is if you're developing a 64-bit application but haven't installed one of the Visual C++ 64-bit compilers. Or, you're targeting an ARM or ARM64 platform, but you don't have the ARM or ARM64 build tools installed. To fix this issue, run the Visual Studio Installer and install the missing C++ components. This error can also occur if you change the **Active solution configuration** in the **Configuration Manager** and then try to build the project before you delete the intermediate project files. To resolve this error, select **Rebuild Solution** from the **Build** menu. You can also select **Clean Solution** from the **Build** menu and then build the solution. ## See also -- [Linker Tools Errors and Warnings](../../error-messages/tool-errors/linker-tools-errors-and-warnings.md) +- [Linker tools errors and warnings](../../error-messages/tool-errors/linker-tools-errors-and-warnings.md) diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md index b383fbe74f..78fddef3f0 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md @@ -10,7 +10,7 @@ ms.assetid: 97ead151-fd99-46fe-9a1d-7e84dc0b8cc8 cannot open filename for writing -The linker can’t write to `filename`. The file may be in use and its file handle locked by another process, or you may not have write permission for the file, or for the directory or network share it is located in. This error is often caused by a transient condition—for example, a lock held by an anti-virus program, a file search indexing process, or a delay in releasing a lock held by the Visual Studio build system. +The linker can't write to `filename`. The file may be in use and its file handle locked by another process, or you may not have write permission for the file, or for the directory or network share it is located in. This error is often caused by a transient condition—for example, a lock held by an anti-virus program, a file search indexing process, or a delay in releasing a lock held by the Visual Studio build system. To fix this issue, verify that the `filename` file handle is not locked, and that you have write permission for the file. If it is an executable, verify that it is not already running. @@ -20,4 +20,4 @@ If the file is locked by an anti-virus program, you can fix this issue by exclud If the file is locked by a search indexing service, you can fix this issue by excluding your build output directories from automatic indexing. Consult the documentation for the indexing service for more information. To change the Windows search indexing service, use **Indexing Options** in the Windows **Control Panel**. For more information, see [Search indexing in Windows 10: FAQ](https://support.microsoft.com/help/4098843/windows-10-search-indexing-faq). -If your executable can’t be overwritten by the build process, it may be locked by File Explorer. If the **Application Experience** service has been disabled, File Explorer may hold on to an executable file handle lock for an extended time. To fix this issue, run **services.msc** and then open the **Properties** dialog box for the **Application Experience** service. Change the **Startup type** from **Disabled** to **Manual**. +If your executable can't be overwritten by the build process, it may be locked by File Explorer. If the **Application Experience** service has been disabled, File Explorer may hold on to an executable file handle lock for an extended time. To fix this issue, run **services.msc** and then open the **Properties** dialog box for the **Application Experience** service. Change the **Startup type** from **Disabled** to **Manual**. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md new file mode 100644 index 0000000000..7b4979f8e5 --- /dev/null +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md @@ -0,0 +1,15 @@ +--- +description: "Learn more about: Linker tools Error LNK1170" +title: "Linker tools Error LNK1170" +ms.date: 05/17/2022 +f1_keywords: ["LNK1170"] +helpviewer_keywords: ["LNK1170"] +ms.assetid: e079d518-f184-48cd-8b38-969bf137af54 +--- +# Linker tools Error LNK1170 + +> line in command file contains *maximum-length* or more characters + +The build failed because a line in a command response file was too long. A line in an automatically generated response file may be too long for many reasons. For example, this error may occur if the number of object file names is too high. Or, if the combined lengths of the paths included in object file names is too long. + +The appropriate fix for this issue depends on the cause. For example, if it's caused by long paths in object file names, you may try to shorten the directory names in the path. Or, move the project tree into a directory closer to the root of the drive. You may want to break up how response files are generated and consumed by your build system, for instance, by generating some code as static libraries. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md index ea6f44f66c..46248f9a0b 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md @@ -1,24 +1,28 @@ --- description: "Learn more about: Linker Tools Error LNK1237" title: "Linker Tools Error LNK1237" -ms.date: "11/04/2016" +ms.date: 06/29/2022 f1_keywords: ["LNK1237"] helpviewer_keywords: ["LNK1237"] ms.assetid: 8722ffa8-096a-4bb0-85f9-f3aa0e10872a --- # Linker Tools Error LNK1237 -during code generation, compiler introduced reference to symbol 'symbol' defined in module 'module' compiled with /GL +> during code generation, compiler introduced reference to symbol 'symbol' defined in module 'module' compiled with /GL -During code generation, the compiler should not introduce symbols that are later resolved to definitions compiled **/GL**. `symbol` is a symbol that was introduced and later resolved to a definition compiled with **/GL**. +## Remarks -For more information, see [/GL (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md). +During code generation, the compiler shouldn't introduce symbols that are later resolved to definitions compiled **`/GL`**. `symbol` is a symbol that was introduced and later resolved to a definition compiled by using **`/GL`**. -To resolve LNK1237, do not compile the symbol with **/GL** or use [/INCLUDE (Force Symbol References)](../../build/reference/include-force-symbol-references.md) to force a reference to the symbol. +For more information, see [`/GL` (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md). + +To resolve LNK1237, don't use **`/GL`** to compile the symbol, or use [`/INCLUDE` (Force Symbol References)](../../build/reference/include-force-symbol-references.md) to force a reference to the symbol. ## Example -The following sample generates LNK1237. To resolve this error, do not initialize the array in LNK1237_a.cpp and add **/include:__chkstk** to the link command. +The following sample generates LNK1237. To resolve this error, don't initialize the array in `LNK1237_a.cpp` and add **`/include:__chkstk`** to the link command. + +Source file `LNK1237_a.cpp`: ```cpp // LNK1237_a.cpp @@ -27,6 +31,8 @@ int main() { } ``` +Source file `LNK1237_b.cpp`: + ```cpp // LNK1237_b.cpp // compile with: /GS- /GL /c LNK1237_a.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md index b1813f0420..dcdb91e729 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md @@ -1,12 +1,21 @@ --- description: "Learn more about: Linker Tools Error LNK1248" title: "Linker Tools Error LNK1248" -ms.date: "12/28/2017" +ms.date: 08/31/2022 f1_keywords: ["LNK1248"] helpviewer_keywords: ["LNK1248"] --- # Linker Tools Error LNK1248 -> image size ('*size*') exceeds maximum allowable size (80000000) +> image size ('*output_size*') exceeds maximum allowable size (*maximum_size*) -The linker determined that the size of the output file will exceed the largest possible size for a 32-bit program image. You may want to make your program into multiple DLLs. +## Remarks + +The linker determined that the size of an output file will exceed the largest possible size for a 32-bit program image or object file (PE or COFF file). + +To resolve this issue if the file is an executable or DLL, you may want to refactor your program to move some functionality into a separate DLL. If the file is an object file, you may want to refactor your source file into multiple translation units. If the file is a *`.iobj`* file created by [`/LTCGOUT` (Name LTCG incremental object file)](../../build/reference/ltcgout.md) and you aren't using **`/LTCG:INCREMENTAL`**, then remove the **`/LTCGOUT`** option. If you're using **`/LTCG:INCREMENTAL`**, then consider refactoring your executable to reduce the size of the component that causes the error. + +## See also + +[`/GL` (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md)\ +[`/LTCG` (Link-time code generation)](../../build/reference/ltcg-link-time-code-generation.md) diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md index b551a294ef..0028bd2e48 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Linker Tools Error LNK1313" title: "Linker Tools Error LNK1313" -ms.date: "11/04/2016" +ms.date: 06/29/2022 f1_keywords: ["LNK1313"] helpviewer_keywords: ["LNK1313"] ms.assetid: 5df0b72e-bb3f-428c-8d84-6084238f9827 @@ -12,12 +12,14 @@ ms.assetid: 5df0b72e-bb3f-428c-8d84-6084238f9827 ## Remarks -The current version of Visual C++ does not support linking native or mixed managed/native .obj files with .obj files compiled with **/clr:pure**. +The current version of Visual C++ does not support linking native or mixed managed/native `.obj` files with `.obj` files compiled with **`/clr:pure`**. -The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +The **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. ## Examples +Source file `LNK1313.cpp`: + ```cpp // LNK1313.cpp // compile with: /c /clr:pure @@ -25,6 +27,8 @@ The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupp int main() {} ``` +Source file `LNK1313_b.cpp`: + ```cpp // LNK1313_b.cpp // compile with: /c /clr diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md index 1890ccfeff..a12ad9a170 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md @@ -1,7 +1,7 @@ --- title: "Linker Tools Error LNK2019" description: "All about the Microsoft Visual Studio Linker error LNK2019 and how to diagnose and correct it in C and C++ code." -ms.date: "01/15/2020" +ms.date: 09/07/2022 f1_keywords: ["LNK2019"] helpviewer_keywords: ["nochkclr.obj", "LNK2019", "_check_commonlanguageruntime_version"] no-loc: [main, WinMain, wmain, wWinMain, __cdecl, __stdcall, __fastcall, __vectorcall, extern, static, const, ARCH, AVX2, wchar_t, VERBOSE, EXPORTS, SYMBOLS, DUMPBIN, UNDNAME] @@ -10,19 +10,19 @@ no-loc: [main, WinMain, wmain, wWinMain, __cdecl, __stdcall, __fastcall, __vecto > unresolved external symbol '*symbol*' referenced in function '*function*' -The compiled code for *function* makes a reference or call to *symbol*, but the linker can't find the symbol definition in any of the libraries or object files to link. +The compiled code for *function* makes a reference or call to *symbol*, but the linker can't find the symbol definition in any of the libraries or object files. This error message is followed by fatal error [LNK1120](../../error-messages/tool-errors/linker-tools-error-lnk1120.md). To fix error LNK1120, you must fix all LNK2001 and LNK2019 errors first. ## Possible causes -There are many ways to get this error. All of them involve a reference to a function or variable that the linker couldn't *resolve*, or find a definition for. The compiler can identify when a symbol isn't *declared*, but it can't tell when the symbol isn't *defined*. That's because the definition may be in a different source file or library. If a symbol is referred to but never defined, the linker generates an unresolved external symbol error. +There are many ways to get this error. All of them involve a reference to a function or variable that the linker couldn't *resolve*, or find a definition for. The compiler can identify when a symbol isn't *declared*, but it can't tell when the symbol isn't *defined*. It's because the definition might be in a different source file or library. If a symbol is referred to but never defined, the linker generates an unresolved external symbol error. Here are some common problems that cause LNK2019: ### The source file that contains the definition of the symbol isn't compiled -In Visual Studio, make sure the source file that defines the symbol gets compiled as part of your project. Check the intermediate build output directory for a matching .obj file. If the source file isn't compiled, right-click on the file in Solution Explorer and choose **Properties** to check the properties of the file. The **Configuration Properties** > **General** page should show an **Item Type** of **C/C++ Compiler**. On the command line, make sure the source file that contains the definition is compiled. +In Visual Studio, make sure the source file that defines the symbol gets compiled as part of your project. Check the intermediate build output directory for a matching .obj file. If the source file isn't compiled, right-click on the file in Solution Explorer, and then choose **Properties** to check the properties of the file. The **Configuration Properties** > **General** page should show an **Item Type** of **C/C++ Compiler**. On the command line, make sure the source file that contains the definition is compiled. ### The object file or library that contains the definition of the symbol isn't linked @@ -34,7 +34,7 @@ Verify you use the correct spelling and capitalization in both the declaration a ### A function is used but the type or number of the parameters don't match the function definition -The function declaration must match the definition. Make sure the function call matches the declaration, and that the declaration matches the definition. Code that invokes template functions must also have matching template function declarations that include the same template parameters as the definition. For an example of a template declaration mismatch, see sample LNK2019e.cpp in the Examples section. +The function declaration must match the definition. Make sure the function call matches the declaration, and that the declaration matches the definition. Code that invokes function templates must also have matching function template declarations that include the same template parameters as the definition. For an example of a template declaration mismatch, see sample LNK2019e.cpp in the Examples section. ### A function or variable is declared but not defined @@ -42,11 +42,11 @@ LNK2019 can occur when a declaration exists in a header file, but no matching de ### The calling convention is different between the function declaration and the function definition -Calling conventions ([__cdecl](../../cpp/cdecl.md), [__stdcall](../../cpp/stdcall.md), [__fastcall](../../cpp/fastcall.md), or [__vectorcall](../../cpp/vectorcall.md)) are encoded as part of the decorated name. Make sure the calling convention is the same. +Some calling conventions ([`__cdecl`](../../cpp/cdecl.md), [`__stdcall`](../../cpp/stdcall.md), [`__fastcall`](../../cpp/fastcall.md), and [`__vectorcall`](../../cpp/vectorcall.md)) are encoded as part of the decorated name. Make sure the calling convention is the same. -### A symbol is defined in a C file, but declared without using extern "C" in a C++ file +### A symbol is defined in a C file, but declared without using `extern "C"` in a C++ file -Symbols defined in a file that is compiled as C have different decorated names than symbols declared in a C++ file unless you use an [extern "C"](../../cpp/extern-cpp.md) modifier. Make sure the declaration matches the compilation linkage for each symbol. Similarly, if you define a symbol in a C++ file that will be used by a C program, use `extern "C"` in the definition. +A file that's compiled as C creates decorated names for symbols that are different from the decorated names for the same symbols declared in a C++ file, unless you use an [`extern "C"`](../../cpp/extern-cpp.md) modifier. Make sure the declaration matches the compilation linkage for each symbol. Similarly, if you define a symbol in a C++ file that will be used by a C program, use `extern "C"` in the definition. ### A symbol is defined as static and then later referenced outside the file @@ -58,19 +58,19 @@ A static class member must have a unique definition, or it will violate the one- ### A build dependency is only defined as a project dependency in the solution -In earlier versions of Visual Studio, this level of dependency was sufficient. However, starting with Visual Studio 2010, Visual Studio requires a [project-to-project reference](/visualstudio/ide/managing-references-in-a-project). If your project doesn't have a project-to-project reference, you may receive this linker error. Add a project-to-project reference to fix it. +In earlier versions of Visual Studio, this level of dependency was sufficient. However, starting with Visual Studio 2010, Visual Studio requires a [project-to-project reference](/visualstudio/ide/managing-references-in-a-project). If your project doesn't have a project-to-project reference, you might receive this linker error. Add a project-to-project reference to fix it. ### An entry point isn't defined -The application code must define an appropriate entry point: `main` or `wmain` for console applications, and `WinMain` or `wWinMain` for Windows applications. For more information, see [main function and command-line arguments](../../cpp/main-function-command-line-args.md) or [WinMain function](/windows/win32/api/winbase/nf-winbase-winmain). To use a custom entry point, specify the [/ENTRY (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md) linker option. +The application code must define an appropriate entry point: `main` or `wmain` for console applications, and `WinMain` or `wWinMain` for Windows applications. For more information, see [`main` function and command-line arguments](../../cpp/main-function-command-line-args.md) or [`WinMain` function](/windows/win32/api/winbase/nf-winbase-winmain). To use a custom entry point, specify the [`/ENTRY` (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md) linker option. ### You build a console application by using settings for a Windows application -If the error message is similar to **unresolved external symbol WinMain referenced in function** *function_name*, link by using **/SUBSYSTEM:CONSOLE** instead of **/SUBSYSTEM:WINDOWS**. For more information about this setting, and for instructions on how to set this property in Visual Studio, see [/SUBSYSTEM (Specify Subsystem)](../../build/reference/subsystem-specify-subsystem.md). +If the error message is similar to **unresolved external symbol WinMain referenced in function** *function_name*, link by using **`/SUBSYSTEM:CONSOLE`** instead of **`/SUBSYSTEM:WINDOWS`**. For more information about this setting, and for instructions on how to set this property in Visual Studio, see [`/SUBSYSTEM` (Specify Subsystem)](../../build/reference/subsystem-specify-subsystem.md). ### You attempt to link 64-bit libraries to 32-bit code, or 32-bit libraries to 64-bit code -Libraries and object files linked to your code must be compiled for the same architecture as your code. Make sure the libraries your project references are compiled for the same architecture as your project. Make sure the [/LIBPATH](../../build/reference/libpath-additional-libpath.md) or **Additional Library Directories** property points to libraries built for the correct architecture. +Libraries and object files linked to your code must be compiled for the same architecture as your code. Make sure the libraries your project references are compiled for the same architecture as your project. Make sure the [`/LIBPATH`](../../build/reference/libpath-additional-libpath.md) or **Additional Library Directories** property points to libraries built for the correct architecture. ### You use different compiler options for function inlining in different source files @@ -82,29 +82,33 @@ Automatic (function scope) variables can only be used in the scope of that funct ### You call intrinsic functions or pass argument types to intrinsic functions that aren't supported on your target architecture -For example, if you use an AVX2 intrinsic, but don't specify the [/ARCH:AVX2](../../build/reference/arch-x86.md) compiler option, the compiler assumes that the intrinsic is an external function. Instead of generating an inline instruction, the compiler generates a call to an external symbol with the same name as the intrinsic. When the linker tries to find the definition of this missing function, it generates LNK2019. Make sure you only use intrinsics and types supported by your target architecture. +For example, if you use an AVX2 intrinsic, but don't specify the [`/ARCH:AVX2`](../../build/reference/arch-x86.md) compiler option, the compiler assumes that the intrinsic is an external function. Instead of generating an inline instruction, the compiler generates a call to an external symbol with the same name as the intrinsic. When the linker tries to find the definition of this missing function, it generates LNK2019. Make sure you only use intrinsics and types supported by your target architecture. -### You mix code that uses native wchar_t with code that doesn't +### You mix code that uses native `wchar_t` with code that doesn't -C++ language conformance work that was done in Visual Studio 2005 made **`wchar_t`** a native type by default. If not all files have been compiled by using the same **/Zc:wchar_t** settings, type references may not resolve to compatible types. Make sure **`wchar_t`** types in all library and object files are compatible. Either update from a **`wchar_t`** typedef, or use consistent **/Zc:wchar_t** settings when you compile. +C++ language conformance work that was done in Visual Studio 2005 made **`wchar_t`** a native type by default. If not all files have been compiled by using the same **`/Zc:wchar_t`** settings, type references might not resolve to compatible types. Make sure **`wchar_t`** types in all library and object files are compatible. Either update from a **`wchar_t`** typedef, or use consistent **/Zc:wchar_t** settings when you compile. + +### You get errors for *`printf`* and *`scanf`* functions when you link a legacy static library + +A static library that was built using a version of Visual Studio before Visual Studio 2015 might cause LNK2019 errors when linked with the UCRT. The UCRT header files ``, ``, and ``now define many *`printf`* and *`scanf`* variations as **`inline`** functions. The inlined functions are implemented by a smaller set of common functions. Individual exports for the inlined functions aren't available in the standard UCRT libraries, which only export the common functions. There are a couple of ways to resolve this issue. The method we recommend is to rebuild the legacy library with your current version of Visual Studio. Make sure the library code uses the standard headers for the definitions of the *`printf`* and *`scanf`* functions that caused the errors. Another option for a legacy library that you can't rebuild is to add `legacy_stdio_definitions.lib` to the list of libraries you link. This library file provides symbols for the *`printf`* and *`scanf`* functions that are inlined in the UCRT headers. For more information, see the **Libraries** section in [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md#libraries). ## Third-party library issues and vcpkg -If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](https://vcpkg.io/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports). It sets all the configuration properties and dependencies required for successful builds as part of your project. +If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](/vcpkg/). **vcpkg** is a C++ package manager that uses your existing Visual Studio tools to install and build the library. **vcpkg** supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports). It sets all the configuration properties and dependencies required for successful builds as part of your project. ## Diagnosis tools Sometimes it's difficult to tell why the linker can't find a particular symbol definition. Often the problem is that you haven't included the code that contains the definition in your build. Or, build options have created different decorated names for external symbols. There are several tools and options that can help you diagnose LNK2019 errors. -- The [/VERBOSE](../../build/reference/verbose-print-progress-messages.md) linker option can help you determine which files the linker references. This option can help you verify whether the file that contains the definition of the symbol is included in your build. +- The [`/VERBOSE`](../../build/reference/verbose-print-progress-messages.md) linker option can help you determine which files the linker references. This option can help you verify whether the file that contains the definition of the symbol is included in your build. -- The [/EXPORTS](../../build/reference/dash-exports.md) and [/SYMBOLS](../../build/reference/symbols.md) options of the **DUMPBIN** utility can help you discover which symbols are defined in your .dll and object or library files. Make sure the exported decorated names match the decorated names the linker searches for. +- The [`/EXPORTS`](../../build/reference/dash-exports.md) and [`/SYMBOLS`](../../build/reference/symbols.md) options of the **DUMPBIN** utility can help you discover which symbols are defined in your .dll and object or library files. Make sure the exported decorated names match the decorated names the linker searches for. - The **UNDNAME** utility can show you the equivalent undecorated external symbol for a decorated name. ## Examples -Here are several examples of code that causes a LNK2019 error, together with information about how to fix the error. +Here are several examples of code that causes LNK2019 errors, together with information about how to fix the errors. ### A symbol is declared but not defined @@ -120,7 +124,7 @@ int main() { } ``` -Here is another example where a variable and function are declared as **`extern`** but no definition is provided: +Here's another example where a variable and function are declared as **`extern`** but no definition is provided: ```cpp // LNK2019c.cpp @@ -135,7 +139,7 @@ void f() { int main() {} ``` -Unless `i` and `g` are defined in one of the files included in the build, the linker generates LNK2019. You can fix the errors by including the source code file that contains the definitions as part of the compilation. Alternatively, you can pass .obj files or .lib files that contain the definitions to the linker. +Unless `i` and `g` are defined in one of the files included in the build, the linker generates LNK2019. You can fix the errors by including the source code file that contains the definitions as part of the compilation. Alternatively, you can pass `.obj` files or `.lib` files that contain the definitions to the linker. ### A static data member is declared but not defined @@ -160,7 +164,7 @@ int main() { ### Declaration parameters don't match the definition -Code that invokes template functions must have matching template function declarations. Declarations must include the same template parameters as the definition. The following sample generates LNK2019 on a user-defined operator, and shows how to fix it. +Code that invokes function templates must have matching function template declarations. Declarations must include the same template parameters as the definition. The following sample generates LNK2019 on a user-defined operator, and shows how to fix it. ```cpp // LNK2019e.cpp @@ -213,8 +217,8 @@ int main() { } ``` -To fix this error, change **`unsigned short`** to **`wchar_t`** or `WCHAR`, or compile LNK2019g.cpp by using **/Zc:wchar_t-**. +To fix this error, change **`unsigned short`** to **`wchar_t`** or `WCHAR`, or compile LNK2019g.cpp by using **`/Zc:wchar_t-`**. -## Additional resources +## See also -For more information about possible causes and solutions for LNK2001, see the Stack Overflow question [What is an undefined reference/unresolved external symbol error and how do I fix it?](https://stackoverflow.com/q/12573816/2002113). +For more information about possible causes and solutions for LNK2019, LNK2001, and LNK1120 errors, see the Stack Overflow question: [`What is an undefined reference/unresolved external symbol error and how do I fix it?`](https://stackoverflow.com/q/12573816/2002113). diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md index 36de7722e0..e9711b9f71 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK2020" title: "Linker Tools Error LNK2020" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2020" +ms.date: 11/04/2016 f1_keywords: ["LNK2020"] helpviewer_keywords: ["LNK2020"] -ms.assetid: 4dd017d0-5e83-471b-ac8a-538ac1ed6870 --- # Linker Tools Error LNK2020 @@ -47,16 +46,16 @@ The following sample generates LNK2020. template ref struct Base { - virtual void f1() {}; + virtual void f1() {} }; template ref struct Base2 { - virtual void f1() {}; + virtual void f1() {} }; int main() { Base^ p; // LNK2020 Base2^ p2 = gcnew Base2(); // OK -}; +} ``` diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md index 02a0ccc9a8..ca0deb3ce2 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2033" title: "Linker Tools Error LNK2033" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2033" +ms.date: 11/04/2016 f1_keywords: ["LNK2033"] helpviewer_keywords: ["LNK2033"] -ms.assetid: d61db467-9328-4788-bf54-e2a20537f13f --- # Linker Tools Error LNK2033 unresolved typeref token (token) for 'type' -A type doesn’t have a definition in MSIL metadata. +A type doesn't have a definition in MSIL metadata. LNK2033 can occur when compiling with **/clr:safe** and where there is only a forward declaration for a type in an MSIL module, where the type is referenced in the MSIL module. @@ -32,5 +31,5 @@ ref class B {}; int main() { A ^ aa = nullptr; B ^ bb = nullptr; // OK -}; +} ``` diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md index 46faa30469..8162a57997 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md @@ -18,24 +18,24 @@ This error can occur when an object file in your project is out-of-date. Before Visual Studio defines the following symbols to prevent the linking of incompatible code, which can cause run-time errors or other unexpected behavior. - `_MSC_VER` - Indicates the major and minor version numbers of the Microsoft C++ compiler (MSVC) that's used to build an app or library. Code that's compiled by using one version of the MSVC is incompatible with code that's compiled by using a version that has different major and minor version numbers. For more information, see `_MSC_VER` in [Predefined Macros](../../preprocessor/predefined-macros.md). + Indicates the major and minor version numbers of the Microsoft C++ compiler (MSVC) used to build an app or library. Code that's compiled by using one version of the MSVC is incompatible with code that's compiled by using a version that has different major and minor version numbers. For more information, see `_MSC_VER` in [Predefined Macros](../../preprocessor/predefined-macros.md). - If you're linking to a library that's not compatible with the version of the MSVC that you're using, and you cannot acquire or build a compatible version of the library, you can use an earlier version of the compiler to build your project: change the **Platform Toolset** property of the project to the earlier toolset. For more information, see [How to: Modify the Target Framework and Platform Toolset](../../build/how-to-modify-the-target-framework-and-platform-toolset.md). + If you're linking to a library that's not compatible with the version of the MSVC that you're using, and you can't acquire or build a compatible version of the library, you can use an earlier version of the compiler to build your project: change the **Platform Toolset** property of the project to the earlier toolset. For more information, see [How to: Modify the Target Framework and Platform Toolset](../../build/how-to-modify-the-target-framework-and-platform-toolset.md). - `_ITERATOR_DEBUG_LEVEL` Indicates the level of security and debugging features that are enabled in the C++ Standard Library. These features can change the representation of certain C++ Standard Library objects and thereby make them incompatible with those that use different security and debugging features. For more information, see [_ITERATOR_DEBUG_LEVEL](../../standard-library/iterator-debug-level.md). - `RuntimeLibrary` - Indicates the version of the C++ Standard Library and C runtime that's used by an app or library. Code that uses one version of the C++ Standard Library or C runtime is incompatible with code that uses a different version. For more information, see [/MD, /MT, /LD (Use Run-Time Library)](../../build/reference/md-mt-ld-use-run-time-library.md). + Indicates the version of the C++ Standard Library and C runtime used by an app or library. Code that uses one version of the C++ Standard Library or C runtime is incompatible with code that uses a different version. For more information, see [/MD, /MT, /LD (Use Run-Time Library)](../../build/reference/md-mt-ld-use-run-time-library.md). - `_PPLTASKS_WITH_WINRT` - Indicates that code that uses the [Parallel Patterns Library (PPL)](../../parallel/concrt/parallel-patterns-library-ppl.md) is linked to objects compiled by using a different setting for the [/ZW](../../build/reference/zw-windows-runtime-compilation.md) compiler option. (**/ZW** supports C++/CX.) Code that uses or depends on the PPL must be compiled by using the same **/ZW** setting that's used in the rest of the app. + Indicates that code that uses the [Parallel Patterns Library (PPL)](../../parallel/concrt/parallel-patterns-library-ppl.md) is linked to objects compiled by using a different setting for the [/ZW](../../build/reference/zw-windows-runtime-compilation.md) compiler option. (**`/ZW`** supports C++/CX.) Code that uses or depends on the PPL must be compiled by using the same **`/ZW`** setting used in the rest of the app. -Ensure that the values of these symbols are consistent throughout the projects in your Visual Studio solution, and also that they are consistent with code and libraries that your app links to. +Ensure that the values of these symbols are consistent throughout the projects in your Visual Studio solution, and also that they're consistent with code and libraries that your app links to. ## Third-party library issues and vcpkg -If you see this error when you are trying to configure a third-party library as part of your build, consider using [vcpkg](https://vcpkg.io/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. +If you see this error when you are trying to configure a third-party library as part of your build, consider using [vcpkg](/vcpkg/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. ## See also diff --git a/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md b/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md index 80f8ac41dc..2e90c8b062 100644 --- a/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md +++ b/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker tools errors and warnings (LNKxxxx)" title: "Linker tools errors and warnings" -ms.date: "09/10/2019" -f1_keywords: ["LNK1100", "LNK1101", "LNK1102", "LNK1105", "LNK1108", "LNK1109", "LNK1111", "LNK1114", "LNK1115", "LNK1117", "LNK1118", "LNK1119", "LNK1121", "LNK1129", "LNK1130", "LNK1131", "LNK1132", "LNK1137", "LNK1144", "LNK1145", "LNK1146", "LNK1147", "LNK1148", "LNK1149", "LNK1154", "LNK1155", "LNK1156", "LNK1159", "LNK1160", "LNK1161", "LNK1162", "LNK1163", "LNK1165", "LNK1167", "LNK1170", "LNK1171", "LNK1172", "LNK1173", "LNK1174", "LNK1175", "LNK1178", "LNK1180", "LNK1182", "LNK1183", "LNK1184", "LNK1185", "LNK1186", "LNK1187", "LNK1190", "LNK1194", "LNK1195", "LNK1197", "LNK1198", "LNK1199", "LNK1207", "LNK1209", "LNK1210", "LNK1212", "LNK1213", "LNK1214", "LNK1216", "LNK1219", "LNK1220", "LNK1227", "LNK1229", "LNK1230", "LNK1232", "LNK1233", "LNK1234", "LNK1235", "LNK1236", "LNK1242", "LNK1243", "LNK1244", "LNK1246", "LNK1247", "LNK1249", "LNK1250", "LNK1252", "LNK1253", "LNK1255", "LNK1257", "LNK1258", "LNK1260", "LNK1261", "LNK1262", "LNK1263", "LNK1265", "LNK1266", "LNK1267", "LNK1268", "LNK1269", "LNK1270", "LNK1272", "LNK1274", "LNK1276", "LNK1279", "LNK1280", "LNK1281", "LNK1283", "LNK1285", "LNK1286", "LNK1289", "LNK1290", "LNK1291", "LNK1292", "LNK1293", "LNK1294", "LNK1295", "LNK1297", "LNK1298", "LNK1299", "LNK1300", "LNK1303", "LNK1304", "LNK1305", "LNK1307", "LNK1308", "LNK1310", "LNK1311", "LNK1315", "LNK1316", "LNK1317", "LNK1319", "LNK1320", "LNK1321", "LNK1322", "LNK1323", "LNK1324", "LNK1325", "LNK1327", "LNK1328", "LNK1329", "LNK1330", "LNK1331", "LNK1333", "LNK1334", "LNK1335", "LNK1336", "LNK1337", "LNK1338", "LNK1339", "LNK1340", "LNK1341", "LNK1342", "LNK1343", "LNK1344", "LNK1345", "LNK1346", "LNK1347", "LNK1348", "LNK1349", "LNK1350", "LNK1351", "LNK1353", "LNK1354", "LNK1355", "LNK1356", "LNK1360", "LNK1361", "LNK1362", "LNK1363", "LNK1364", "LNK1365", "LNK1366", "LNK1367", "LNK1368", "LNK1369", "LNK1370", "LNK1371", "LNK1372", "LNK1373", "LNK1375", "LNK1376", "LNK1377", "LNK1378", "LNK1379", "LNK1380", "LNK1381", "LNK1382", "LNK1383", "LNK1384", "LNK1385", "LNK2002", "LNK2003", "LNK2009", "LNK2014", "LNK2015", "LNK2016", "LNK2018", "LNK2021", "LNK2024", "LNK2029", "LNK2030", "LNK2032", "LNK2034", "LNK2035", "LNK2036", "LNK2037", "LNK2040", "LNK2041", "LNK2042", "LNK2043", "LNK2044", "LNK2045", "LNK4003", "LNK4012", "LNK4013", "LNK4017", "LNK4018", "LNK4019", "LNK4030", "LNK4031", "LNK4038", "LNK4040", "LNK4041", "LNK4042", "LNK4043", "LNK4046", "LNK4047", "LNK4048", "LNK4051", "LNK4052", "LNK4056", "LNK4060", "LNK4061", "LNK4062", "LNK4066", "LNK4067", "LNK4068", "LNK4069", "LNK4072", "LNK4077", "LNK4079", "LNK4081", "LNK4085", "LNK4087", "LNK4088", "LNK4093", "LNK4094", "LNK4097", "LNK4103", "LNK4108", "LNK4195", "LNK4196", "LNK4198", "LNK4202", "LNK4203", "LNK4207", "LNK4208", "LNK4209", "LNK4223", "LNK4225", "LNK4226", "LNK4228", "LNK4232", "LNK4233", "LNK4236", "LNK4238", "LNK4239", "LNK4240", "LNK4241", "LNK4242", "LNK4243", "LNK4244", "LNK4245", "LNK4246", "LNK4249", "LNK4250", "LNK4251", "LNK4252", "LNK4255", "LNK4256", "LNK4257", "LNK4258", "LNK4259", "LNK4260", "LNK4261", "LNK4262", "LNK4263", "LNK4264", "LNK4265", "LNK4266", "LNK4267", "LNK4268", "LNK4269", "LNK4270", "LNK4271", "LNK4272", "LNK4273", "LNK4274", "LNK4275", "LNK4276", "LNK4277", "LNK4278", "LNK4279", "LNK4280", "LNK4281", "LNK4282", "LNK4283", "LNK4284", "LNK4285", "LNK4287", "LNK4288", "LNK4289", "LNK4290"] +description: "Learn more about: Linker tools errors and warnings (LNKxxxx)" +ms.date: 01/30/2024 +f1_keywords: ["LNK1100", "LNK1101", "LNK1102", "LNK1105", "LNK1108", "LNK1109", "LNK1111", "LNK1114", "LNK1115", "LNK1117", "LNK1118", "LNK1119", "LNK1121", "LNK1129", "LNK1130", "LNK1131", "LNK1132", "LNK1137", "LNK1144", "LNK1145", "LNK1146", "LNK1147", "LNK1148", "LNK1149", "LNK1154", "LNK1155", "LNK1156", "LNK1159", "LNK1160", "LNK1161", "LNK1162", "LNK1163", "LNK1165", "LNK1167", "LNK1171", "LNK1172", "LNK1173", "LNK1174", "LNK1175", "LNK1178", "LNK1180", "LNK1182", "LNK1183", "LNK1184", "LNK1185", "LNK1186", "LNK1187", "LNK1190", "LNK1194", "LNK1195", "LNK1197", "LNK1198", "LNK1199", "LNK1207", "LNK1209", "LNK1210", "LNK1212", "LNK1213", "LNK1214", "LNK1216", "LNK1219", "LNK1220", "LNK1227", "LNK1229", "LNK1230", "LNK1232", "LNK1233", "LNK1234", "LNK1235", "LNK1236", "LNK1242", "LNK1243", "LNK1244", "LNK1246", "LNK1247", "LNK1249", "LNK1250", "LNK1252", "LNK1253", "LNK1255", "LNK1257", "LNK1258", "LNK1260", "LNK1261", "LNK1262", "LNK1263", "LNK1265", "LNK1266", "LNK1267", "LNK1268", "LNK1269", "LNK1270", "LNK1272", "LNK1274", "LNK1276", "LNK1279", "LNK1280", "LNK1281", "LNK1283", "LNK1285", "LNK1286", "LNK1289", "LNK1290", "LNK1291", "LNK1292", "LNK1293", "LNK1294", "LNK1295", "LNK1297", "LNK1298", "LNK1299", "LNK1300", "LNK1303", "LNK1304", "LNK1305", "LNK1307", "LNK1308", "LNK1310", "LNK1311", "LNK1315", "LNK1316", "LNK1317", "LNK1319", "LNK1320", "LNK1321", "LNK1322", "LNK1323", "LNK1324", "LNK1325", "LNK1327", "LNK1328", "LNK1329", "LNK1330", "LNK1331", "LNK1333", "LNK1334", "LNK1335", "LNK1336", "LNK1337", "LNK1338", "LNK1339", "LNK1340", "LNK1341", "LNK1342", "LNK1343", "LNK1344", "LNK1345", "LNK1346", "LNK1347", "LNK1348", "LNK1349", "LNK1350", "LNK1351", "LNK1353", "LNK1354", "LNK1355", "LNK1356", "LNK1360", "LNK1361", "LNK1362", "LNK1363", "LNK1364", "LNK1365", "LNK1366", "LNK1367", "LNK1368", "LNK1369", "LNK1370", "LNK1371", "LNK1372", "LNK1373", "LNK1375", "LNK1376", "LNK1377", "LNK1378", "LNK1379", "LNK1380", "LNK1381", "LNK1382", "LNK1383", "LNK1384", "LNK1385", "LNK2002", "LNK2003", "LNK2009", "LNK2014", "LNK2015", "LNK2016", "LNK2018", "LNK2021", "LNK2024", "LNK2029", "LNK2030", "LNK2032", "LNK2034", "LNK2035", "LNK2036", "LNK2037", "LNK2040", "LNK2041", "LNK2042", "LNK2043", "LNK2044", "LNK2045", "LNK4003", "LNK4012", "LNK4013", "LNK4017", "LNK4018", "LNK4019", "LNK4030", "LNK4031", "LNK4038", "LNK4040", "LNK4041", "LNK4042", "LNK4043", "LNK4046", "LNK4047", "LNK4048", "LNK4051", "LNK4052", "LNK4056", "LNK4060", "LNK4061", "LNK4062", "LNK4066", "LNK4067", "LNK4068", "LNK4069", "LNK4072", "LNK4077", "LNK4079", "LNK4081", "LNK4085", "LNK4087", "LNK4088", "LNK4093", "LNK4094", "LNK4097", "LNK4103", "LNK4108", "LNK4195", "LNK4196", "LNK4198", "LNK4202", "LNK4203", "LNK4207", "LNK4208", "LNK4209", "LNK4223", "LNK4225", "LNK4226", "LNK4228", "LNK4232", "LNK4233", "LNK4236", "LNK4238", "LNK4239", "LNK4240", "LNK4241", "LNK4242", "LNK4243", "LNK4244", "LNK4245", "LNK4246", "LNK4249", "LNK4250", "LNK4251", "LNK4252", "LNK4255", "LNK4256", "LNK4257", "LNK4258", "LNK4259", "LNK4260", "LNK4261", "LNK4262", "LNK4263", "LNK4264", "LNK4265", "LNK4266", "LNK4267", "LNK4268", "LNK4269", "LNK4270", "LNK4271", "LNK4272", "LNK4273", "LNK4274", "LNK4275", "LNK4276", "LNK4277", "LNK4278", "LNK4279", "LNK4280", "LNK4281", "LNK4282", "LNK4283", "LNK4284", "LNK4285", "LNK4287", "LNK4288", "LNK4289", "LNK4290", "LNK4306", "LNK4307"] helpviewer_keywords: ["errors [C++]", "linker [C++], errors and warnings", "errors [C++], linker"] -ms.assetid: d4b12c0f-4dae-48b2-9b9e-fedf94c94cb0 --- # Linker tools errors and warnings (LNKxxxx) @@ -34,6 +33,7 @@ The linker tools LINK, LIB, DUMPBIN, and EDITBIN share a common executable that [Linker Tools Error LNK1166](../../error-messages/tool-errors/linker-tools-error-lnk1166.md) \ [Linker Tools Error LNK1168](../../error-messages/tool-errors/linker-tools-error-lnk1168.md) \ [Linker Tools Error LNK1169](../../error-messages/tool-errors/linker-tools-error-lnk1169.md) \ +[Linker Tools Error LNK1170](../../error-messages/tool-errors/linker-tools-error-lnk1170.md) \ [Linker Tools Error LNK1179](../../error-messages/tool-errors/linker-tools-error-lnk1179.md) \ [Linker Tools Error LNK1181](../../error-messages/tool-errors/linker-tools-error-lnk1181.md) \ [Linker Tools Error LNK1188](../../error-messages/tool-errors/linker-tools-error-lnk1188.md) \ @@ -137,7 +137,9 @@ The linker tools LINK, LIB, DUMPBIN, and EDITBIN share a common executable that [Linker Tools Warning LNK4248](../../error-messages/tool-errors/linker-tools-warning-lnk4248.md) \ [Linker Tools Warning LNK4253](../../error-messages/tool-errors/linker-tools-warning-lnk4253.md) \ [Linker Tools Warning LNK4254](../../error-messages/tool-errors/linker-tools-warning-lnk4254.md) \ -[Linker Tools Warning LNK4286](../../error-messages/tool-errors/linker-tools-warning-lnk4286.md) +[Linker Tools Warning LNK4286](../../error-messages/tool-errors/linker-tools-warning-lnk4286.md) \ +[Linker Tools Warning LNK4306](../../error-messages/tool-errors/linker-tools-warning-lnk4306.md) \ +[Linker Tools Warning LNK4307](../../error-messages/tool-errors/linker-tools-warning-lnk4307.md) ## See also diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md index 5c414ede43..9449741131 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md @@ -29,7 +29,6 @@ int main() func(); return 0; } - ``` And then, diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md index 964370bae2..9fae0c56fd 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md @@ -1,22 +1,24 @@ --- description: "Learn more about: Linker Tools Warning LNK4221" title: "Linker Tools Warning LNK4221" -ms.date: "08/19/2019" +ms.date: 06/29/2022 f1_keywords: ["LNK4221"] helpviewer_keywords: ["LNK4221"] ms.assetid: 8e2eb2de-9532-4b85-908a-8c9ff5c4cccb --- # Linker Tools Warning LNK4221 -This object file does not define any previously undefined public symbols, so it will not be used by any link operation that consumes this library +> This object file does not define any previously undefined public symbols, so it will not be used by any link operation that consumes this library -Consider the following two code snippets. +Consider the following two code snippets, `a.cpp`: ```cpp // a.cpp #include ``` +And `b.cpp`: + ```cpp // b.cpp #include @@ -26,20 +28,20 @@ int function() } ``` -To compile the files and create two object files, run **cl /c a.cpp b.cpp** at a command prompt. If you link the object files by running **link /lib /out:test.lib a.obj b.obj**, you will receive the LNK4221 warning. If you link the objects by running **link /lib /out:test.lib b.obj a.obj**, you will not receive a warning. +To compile the files and create two object files, run **`cl /c a.cpp b.cpp`** at a command prompt. If you link the object files by running **`link /lib /out:test.lib a.obj b.obj`**, you'll receive the LNK4221 warning. If you link the objects by running **`link /lib /out:test.lib b.obj a.obj`**, you won't receive a warning. -No warning is issued in the second scenario because the linker operates in a last-in first-out (LIFO) manner. In the first scenario, b.obj is processed before a.obj, and a.obj has no new symbols to add. By instructing the linker to process a.obj first, you can avoid the warning. +No warning is issued in the second scenario because the linker operates in a last-in first-out (LIFO) manner. In the first scenario, `b.obj` is processed before `a.obj`, and `a.obj` has no new symbols to add. By instructing the linker to process `a.obj` first, you can avoid the warning. ::: moniker range=">=msvc-160" -A common cause of this error is when two source files specify the option [/Yc (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md) with the same header file name specified in the **Precompiled Header** field. A common cause of this problem deals with *pch.h* since, by default, *pch.cpp* includes *pch.h* and does not add any new symbols. If another source file includes *pch.h* with **/Yc** and the associated .obj file is processed before pch.obj, the linker will throw LNK4221. +A common cause of this error is when two source files specify the option [`/Yc` (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md) with the same header file name specified in the **Precompiled Header** field. A common cause of this problem deals with *`pch.h`* since, by default, *`pch.cpp`* includes *`pch.h`* and doesn't add any new symbols. If another source file includes *`pch.h`* with **`/Yc`** and the associated `.obj` file is processed before `pch.obj`, the linker will throw LNK4221. ::: moniker-end ::: moniker range="<=msvc-150" -A common cause of this error is when two source files specify the option [/Yc (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md) with the same header file name specified in the **Precompiled Header** field. A common cause of this problem deals with *stdafx.h* since, by default, *stdafx.cpp* includes *stdafx.h* and does not add any new symbols. If another source file includes *stdafx.h* with **/Yc** and the associated .obj file is processed before stdafx.obj, the linker will throw LNK4221. +A common cause of this error is when two source files specify the option [`/Yc` (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md) with the same header file name specified in the **Precompiled Header** field. A common cause of this problem deals with *`stdafx.h`* since, by default, *`stdafx.cpp`* includes *`stdafx.h`* and doesn't add any new symbols. If another source file includes *`stdafx.h`* with **`/Yc`** and the associated `.obj` file is processed before `stdafx.obj`, the linker will throw LNK4221. ::: moniker-end -One way to resolve this problem is to make sure that for each precompiled header, there is only one source file that includes it with **/Yc**. All other source files must use precompiled headers. For more information about how to change this setting, see [/Yu (Use Precompiled Header File)](../../build/reference/yu-use-precompiled-header-file.md). +One way to resolve this problem is to make sure that for each precompiled header, there's only one source file that includes it with **`/Yc`**. All other source files must use precompiled headers. For more information about how to change this setting, see [`/Yu` (Use Precompiled Header File)](../../build/reference/yu-use-precompiled-header-file.md). diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md index 51158a3942..17b02f0c4f 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md @@ -10,7 +10,7 @@ ms.assetid: e40523ff-e3cb-4ba6-ab79-23f0f339f6cf unresolved typeref token (token) for 'type'; image may not run -A type doesn’t have a definition in MSIL metadata. +A type doesn't have a definition in MSIL metadata. LNK4248 can occur when there is only a forward declaration for a type in an MSIL module (compiled with **/clr**), where the type is referenced in the MSIL module, and where the MSIL module is linked with a native module that has a definition for the type. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4306.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4306.md new file mode 100644 index 0000000000..585f507811 --- /dev/null +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4306.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Linker tools warning LNK4306" +title: "Linker tools warning LNK4306" +ms.date: 01/30/2024 +f1_keywords: ["LNK4306"] +helpviewer_keywords: ["LNK4306"] +--- +# Linker tools warning LNK4306 + +> The auxiliary delayload import address table is not properly aligned with the primary delayload import address table. This may have negative perf impact. + +This warning indicates a problem has occurred within the linker. + +Please report the issue and how you ran into it in the [C++ Developer Community channel](https://developercommunity.visualstudio.com/cpp). Add the tag `ARM64EC` to your issue to help us find the issue. \ No newline at end of file diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4307.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4307.md new file mode 100644 index 0000000000..97bf46196a --- /dev/null +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4307.md @@ -0,0 +1,14 @@ +--- +description: "Learn more about: Linker Tools warning LNK4307" +title: "Linker Tools warning LNK4307" +ms.date: 01/30/2024 +f1_keywords: ["LNK4307"] +helpviewer_keywords: ["LNK4307"] +--- +# Linker tools warning LNK4307 + +> The auxiliary delayload import address table copy is not properly aligned with the auxiliary delayload import address table. This may have negative perf impact. + +This warning indicates a problem has occurred within the linker. + +Please report the issue and how you ran into it in the [C++ Developer Community channel](https://developercommunity.visualstudio.com/cpp). Add the tag `ARM64EC` to your issue to help us find the issue. \ No newline at end of file diff --git a/docs/error-messages/tool-errors/math-errors-m6101-through-m6205.md b/docs/error-messages/tool-errors/math-errors-m6101-through-m6205.md index 5c934acfb5..497e291e5f 100644 --- a/docs/error-messages/tool-errors/math-errors-m6101-through-m6205.md +++ b/docs/error-messages/tool-errors/math-errors-m6101-through-m6205.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Math errors (Mxxxx)" -title: "Math errors" +title: "Learn about math errors M6101 through M6205" ms.date: "04/16/2019" -ms.assetid: bdf3dc2a-d993-4f53-b0f2-9604e4914127 --- -# Math errors (Mxxxx) +# Math errors (M6101 through M6205) This section is a reference to the errors generated by the runtime floating-point math library. Math runtime errors and warnings have the form M*xxxx*, where *xxxx* is a four-digit number. diff --git a/docs/error-messages/tool-errors/resource-compiler-errors-rc1000-through-rc4413.md b/docs/error-messages/tool-errors/resource-compiler-errors-rc1000-through-rc4413.md index 86313c3916..bc1f2f17fe 100644 --- a/docs/error-messages/tool-errors/resource-compiler-errors-rc1000-through-rc4413.md +++ b/docs/error-messages/tool-errors/resource-compiler-errors-rc1000-through-rc4413.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: Resource compiler errors and warnings (RCxxxx, RWxxxx)" title: "Resource compiler errors and warnings" +description: "Learn more about: Resource compiler errors and warnings (RCxxxx, RWxxxx)" ms.date: "04/17/2019" -ms.assetid: 0819f955-0561-491d-af3d-2453f4e2d035 --- # Resource compiler errors and warnings (RCxxxx, RWxxxx) @@ -94,5 +93,5 @@ This section is a reference to the errors generated by the resource compiler. Re ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) +[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md)\ [Resource compiler](/windows/win32/menurc/resource-compiler) diff --git a/docs/extensions/abstract-cpp-component-extensions.md b/docs/extensions/abstract-cpp-component-extensions.md index bb6484969d..54e681d6cf 100644 --- a/docs/extensions/abstract-cpp-component-extensions.md +++ b/docs/extensions/abstract-cpp-component-extensions.md @@ -25,7 +25,7 @@ The **abstract** keyword declares either: ### Remarks -The first example syntax declares a class to be abstract. The *class-declaration* component can be either a native C++ declaration (**`class`**** or **`struct`**), or a C++ extension declaration (**ref class** or **ref struct**) if the `/ZW` or `/clr` compiler option is specified. +The first example syntax declares a class to be abstract. The *class-declaration* component can be either a native C++ declaration (**`class`** or **`struct`**), or a C++ extension declaration (**ref class** or **ref struct**) if the `/ZW` or `/clr` compiler option is specified. The second example syntax declares a virtual member function to be abstract. Declaring a function abstract is the same as declaring it a pure virtual function. Declaring a member function abstract also causes the enclosing class to be declared abstract. diff --git a/docs/extensions/compiler-support-for-type-traits-cpp-component-extensions.md b/docs/extensions/compiler-support-for-type-traits-cpp-component-extensions.md index 98f1acc128..c88366385c 100644 --- a/docs/extensions/compiler-support-for-type-traits-cpp-component-extensions.md +++ b/docs/extensions/compiler-support-for-type-traits-cpp-component-extensions.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Compiler Support for Type Traits (C++/CLI and C++/CX)" title: "Compiler Support for Type Traits (C++/CLI and C++/CX)" +description: "Learn more about: Compiler Support for Type Traits (C++/CLI and C++/CX)" ms.date: "10/12/2018" ms.topic: "reference" f1_keywords: ["__is_simple_value_class", "__has_trivial_destructor", "__has_assign", "__is_union", "__is_class", "__is_abstract", "__has_trivial_assign", "__has_virtual_destructor", "__is_ref_array", "__is_base_of", "__has_copy", "__is_polymorphic", "__has_nothrow_constructor", "__is_ref_class", "__is_delegate", "__is_convertible_to", "__is_value_class", "__is_interface_class", "__has_nothrow_copy", "__is_sealed", "__has_trivial_constructor", "__has_trivial_copy", "__is_enum", "__has_nothrow_assign", "__has_finalizer", "__is_empty", "__is_pod", "__has_user_destructor"] helpviewer_keywords: ["__is_class keyword [C++]", "__is_pod keyword [C++]", "__is_delegate keyword [C++]", "__is_value_class keyword [C++]", "__has_copy keyword [C++]", "__has_nothrow_copy keyword [C++]", "__is_interface_class keyword [C++]", "__is_sealed keyword [C++]", "__is_convertible_to keyword [C++]", "__is_ref_class keyword [C++]", "__has_trivial_copy keyword [C++]", "__has_user_destructor keyword [C++]", "__is_abstract keyword [C++]", "__is_empty keyword [C++]", "__has_trivial_assign keyword [C++]", "__has_nothrow_constructor keyword [C++]", "__is_ref_array keyword [C++]", "__is_base_of keyword [C++]", "__has_nothrow_assign keyword [C++]", "__has_virtual_destructor keyword [C++]", "__has_finalizer keyword [C++]", "__is_union keyword [C++]", "__has_assign keyword [C++]", "__has_trivial_destructor keyword [C++]", "__is_polymorphic keyword [C++]", "__is_enum keyword [C++]", "__is_simple_value_class keyword [C++]", "__has_trivial_constructor keyword [C++]"] -ms.assetid: cd440630-0394-48c0-a16b-1580b6ef5844 --- # Compiler Support for Type Traits (C++/CLI and C++/CX) @@ -160,7 +159,7 @@ The following list contains the type traits that are supported by the compiler. Returns **`true`** if the type has a trivial, compiler-generated destructor. - ``` cpp + ```cpp // has_trivial_destructor.cpp #include struct S {}; @@ -419,7 +418,7 @@ The following list contains the type traits that are supported by the compiler. ref class R {}; value struct V {}; value struct V2 { - R ^ r; // not a simnple value type + R ^ r; // not a simple value type }; int main() { diff --git a/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md b/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md index e36d5db911..22cc991cba 100644 --- a/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md +++ b/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Constraints on generic type parameters (C++/CLI)" title: "Constraints on generic type parameters (C++/CLI)" -ms.date: "10/12/2018" +ms.date: 06/01/2022 ms.topic: "reference" f1_keywords: ["where"] helpviewer_keywords: ["where keyword [C++]", "constraints, C++"] @@ -11,25 +11,23 @@ ms.assetid: eb828cc9-684f-48a3-a898-b327700c0a63 In generic type or method declarations, you can qualify a type parameter with *constraints*. A constraint is a requirement that types used as type arguments must satisfy. For example, a constraint might be that the type argument must implement a certain interface or inherit from a specific class. -Constraints are optional; not specifying a constraint on a parameter is equivalent to constraining that parameter to . +Constraints are optional; not specifying a constraint on a parameter is equivalent to using a constraint. ## Syntax -```cpp -where type-parameter: constraint-list -``` +> **`where`** *`type-parameter`* **`:`** *`constraint-list`* ### Parameters *`type-parameter`*\ -One of the type parameters, to be constrained. +One of the type parameter identifiers to constrain. *`constraint-list`*\ -*`constraint-list`* is a comma-separated list of constraint specifications. The list can include interfaces to be implemented by the type parameter. +A comma-separated list of constraint specifications. The list can include interfaces to be implemented by the *`type-parameter`*. -The list can also include a class. For the type argument to satisfy a base class constraint, it must be the same class as the constraint or derive from the constraint. +The list can also include a class. To satisfy a base class constraint, the type argument must be the same class as the constraint or derive from the constraint. Specify **`ref class`** to indicate the type argument must be a reference type, including any `class`, `interface`, `delegate`, or `array` type. Specify **`value class`** to indicate the type argument must be a value type. Any value type except `Nullable` can be specified. -You can also specify **`gcnew()`** to indicate the type argument must have a public parameterless constructor; or **`ref class`** to indicate the type argument must be a reference type, including any class, interface, delegate, or array type; or **`value class`** to indicate the type argument must be a value type. Any value type except `Nullable` can be specified. +You can also specify `gcnew()` to indicate the type argument must have a public parameterless constructor. You can also specify a generic parameter as a constraint. The type argument supplied for the type you're constraining must be or derive from the type of the constraint. This parameter is called a *naked type constraint*. @@ -56,7 +54,7 @@ This constraint requires that a type argument used for `T` implements `IComparab Static methods in the type argument's class can't be called through the type parameter; they can be called only through the actual named type. -A constraint can't be a value type, including built-in types such as **`int`** or **`double`**. Since value types cannot have derived classes, only one class could ever satisfy the constraint. In that case, the generic can be rewritten with the type parameter replaced by the specific value type. +A constraint can't be a value type, including built-in types such as **`int`** or **`double`**. Since value types can't have derived classes, only one class could ever satisfy the constraint. In that case, the generic can be rewritten with the type parameter replaced by the specific value type. Constraints are required in some cases since the compiler won't allow the use of methods or other features of an unknown type unless the constraints imply that the unknown type supports the methods or interfaces. diff --git a/docs/extensions/generic-functions-cpp-cli.md b/docs/extensions/generic-functions-cpp-cli.md index 02b61934bb..76441f7d41 100644 --- a/docs/extensions/generic-functions-cpp-cli.md +++ b/docs/extensions/generic-functions-cpp-cli.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Generic functions (C++/CLI)" title: "Generic Functions (C++/CLI)" -ms.date: "10/12/2018" +ms.date: 05/31/2022 ms.topic: "reference" helpviewer_keywords: ["functions [C++], generic", "generic methods", "generics [C++], functions", "methods [C++], generic", "generic functions"] ms.assetid: 8e409364-58f9-4360-b486-e7d555e0c218 @@ -24,56 +24,84 @@ This feature isn't supported in the Windows Runtime. ### Requirements -Compiler option: `/ZW` +Not applicable. ## Common Language Runtime -A generic function is a function that's declared with type parameters. When called, actual types are used instead of the type parameters. +A generic function is a function that's declared with generic type parameters. When called, actual types are used instead of the type parameters. ### Syntax -```cpp -[attributes] [modifiers] -return-type identifier -[type-parameter-constraints-clauses] +*`generic-declaration`*:\ +  **`generic`** **`<`** *`generic-parameter-list`* **`>`** *`constraint-clause-list`*opt *`function-definition`* -([formal-parameters]) -{function-body} -``` +*`generic-parameter-list`*:\ +  *`generic-parameter`*\ +  *`generic-parameter-list`* **`,`** *`generic-parameter`* -### Parameters +*`generic-parameter`*:\ +  *`attributes`*opt **`class`** *`identifier`*\ +  *`attributes`*opt **`typename`** *`identifier`* -*`attributes`*\ -(Optional) Additional declarative information. For more information on attributes and attribute classes, see [attributes](../cppcx/attributes-c-cx.md). +*`constraint-clause-list`*:\ +  *`constraint-clause-list`*opt *`constraint-clause`* + +*`constraint-clause`*:\ +  **`where`** *`identifier`* **`:`** *`constraint-item-list`* + +*`constraint-item-list`*:\ +  *`constraint-item`*\ +  *`constraint-item-list`* **`,`** *`constraint-item`* + +*`constraint-item`*:\ +  *`type-id`*\ +  **`ref class`**\ +  **`ref struct`**\ +  **`value class`**\ +  **`value struct`**\ +  **`gcnew ( )`** -*`modifiers`*\ -(Optional) A modifier for the function, such as `static`. **`virtual`** isn't allowed since virtual methods may not be generic. +*`generic-id`*:\ +  *`generic-name`* **`<`** *`generic-argument-list`* **`>`** -*`return-type`*\ -The type returned by the method. If the return type is void, no return value is required. +*`generic-name`*:\ +  *`identifier`*\ +  *`operator-function-id`* -*`identifier`*\ -The function name. +*`generic-argument-list`*:\ +  *`generic-argument`*\ +  *`generic-argument-list`* **`,`** *`generic-argument`* + +*`generic-argument`*:\ +  *`type-id`* + +### Parameters + +*`generic-parameter-list`*\ +A comma-separated list of optionally attributed generic type parameter identifiers. + +*`attributes`*\ +(Optional) Extra declarative information. For more information on attributes and attribute classes, see [attributes](../cppcx/attributes-c-cx.md). -*`type-parameter-identifier-list`*\ -Comma-separated identifiers list. +*`constraint-clause-list`*\ +This optional list specifies restrictions on the types that may be used as type arguments. It takes the form specified in [Constraints on generic type parameters (C++/CLI)](constraints-on-generic-type-parameters-cpp-cli.md). -*`formal-parameters`*\ -(Optional) Parameter list. +*`function-definition`*\ +A definition of a method or standalone function. The function may not have a `virtual` modifier, which isn't allowed since virtual methods may not be generic. The body of the function may refer to the generic type parameter identifiers. The function may be an `operator` function. -*`type-parameter-constraints-clauses`*\ -This set specifies restrictions on the types that may be used as type arguments, and takes the form specified in [Constraints on Generic Type Parameters (C++/CLI)](constraints-on-generic-type-parameters-cpp-cli.md). +*`generic-id`*\ +When you invoke an instance of a generic function, you specify the types used to implement it in the *`generic-argument-list`*. This list corresponds to the *`generic-parameter-list`*, and must satisfy the constraints of the optional *`constraint-clause-list`*. -*`function-body`*\ -The body of the method, which may refer to the type parameter identifiers. +*`generic-name`*\ +A generic function may have an *`identifier`* as its name, or it may be an `operator` function. ### Remarks -Generic functions are functions declared with a generic type parameter. They may be methods in a `class` or `struct`, or standalone functions. A single generic declaration implicitly declares a family of functions that differ only in the substitution of a different actual type for the generic type parameter. +Generic functions are functions declared with one or more generic type parameters. They may be methods in a `class` or `struct`, or standalone functions. A single generic declaration implicitly declares a family of functions that differ only in the substitution of a different actual type for the generic type parameter. A `class` or `struct` constructor may not be declared with generic type parameters. -When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a template function call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. The compiler reports an error if the intended type argument cannot be deduced from the parameters used. +When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a function template call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. The compiler reports an error if the intended type argument can't be deduced from the parameters used. ### Requirements diff --git a/docs/extensions/generic-interfaces-visual-cpp.md b/docs/extensions/generic-interfaces-visual-cpp.md index 29f3456ca9..5fa795e2ef 100644 --- a/docs/extensions/generic-interfaces-visual-cpp.md +++ b/docs/extensions/generic-interfaces-visual-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Generic Interfaces (C++/CLI)" title: "Generic Interfaces (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: Generic Interfaces (C++/CLI)" +ms.date: 10/12/2018 ms.topic: "reference" -helpviewer_keywords: ["generic interfaces", "interfaces, generic [C++}"] -ms.assetid: f3da788a-ba83-4db7-9dcf-9b95a8fb9d1a +helpviewer_keywords: ["generic interfaces", "interfaces, generic [C++]"] --- # Generic Interfaces (C++/CLI) diff --git a/docs/extensions/how-to-declare-interior-pointers-with-the-const-keyword-cpp-cli.md b/docs/extensions/how-to-declare-interior-pointers-with-the-const-keyword-cpp-cli.md index cc911e9bcb..7a4bb01bf4 100644 --- a/docs/extensions/how-to-declare-interior-pointers-with-the-const-keyword-cpp-cli.md +++ b/docs/extensions/how-to-declare-interior-pointers-with-the-const-keyword-cpp-cli.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Declare Interior Pointers with the const Keyword (C++/CLI)" title: "How to: Declare Interior Pointers with the const Keyword (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: How to: Declare Interior Pointers with the const Keyword (C++/CLI)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["pointers, interior"] -ms.assetid: 64e08b0e-9396-4046-ab51-8f6588f32330 --- # How to: Declare Interior Pointers with the const Keyword (C++/CLI) @@ -66,10 +65,10 @@ int main() { // h_G->msg = "test"; error h_G is const interior_ptr int_ptr_G = &(h_G->msg); - G ^ const h_G2 = gcnew G; // interior pointers to this obejct cannot be dereferenced and changed + G ^ const h_G2 = gcnew G; // interior pointers to this object cannot be dereferenced and changed h_G2->msg = "test"; interior_ptr int_ptr_G2 = &(h_G->msg); -}; +} ``` ## See also diff --git a/docs/extensions/how-to-declare-value-types-with-the-interior-ptr-keyword-cpp-cli.md b/docs/extensions/how-to-declare-value-types-with-the-interior-ptr-keyword-cpp-cli.md index 33936cc19b..cb260147a5 100644 --- a/docs/extensions/how-to-declare-value-types-with-the-interior-ptr-keyword-cpp-cli.md +++ b/docs/extensions/how-to-declare-value-types-with-the-interior-ptr-keyword-cpp-cli.md @@ -58,7 +58,7 @@ int main() { 3 ``` -## Example: this pointer +## Example: `this` pointer ### Description diff --git a/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md b/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md index 583458caaa..f9eba24de2 100644 --- a/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md +++ b/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md @@ -1,24 +1,24 @@ --- -description: "Learn more about: How to: Improve Performance with Generics (C++/CLI)" -title: "How to: Improve Performance with Generics (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: How to: Improve performance with generics (C++/CLI)" +title: "How to: Improve performance with generics (C++/CLI)" +ms.date: 10/03/2022 ms.topic: "reference" helpviewer_keywords: ["performance, C++", "C++, performance", "C++, generics", "generics [C++], performance"] ms.assetid: f14a175b-301f-46cc-86e4-c82d35f9aa3e --- -# How to: Improve Performance with Generics (C++/CLI) +# How to: Improve performance with generics (C++/CLI) With generics, you can create reusable code based on a type parameter. The actual type of the type parameter is deferred until called by client code. For more information on generics, see [Generics](generics-cpp-component-extensions.md). -This article will discuss how generics can help increase the performance of an application that uses collections. +This article discusses how generics can help increase the performance of an application that uses collections. ## Example: Two main drawbacks of .NET Framework collections -The .NET Framework comes with many collection classes in the namespace. Most of these collections operate on objects of type . This allows collections to store any type, since all types in the .NET Framework, even value types, derive from . However, there are two drawbacks to this approach. +The .NET Framework comes with many collection classes in the namespace. Most of these collections operate on objects of type . Collections can store any type, since all types in the .NET Framework, even value types, derive from . However, there are two drawbacks to this approach. -First, if the collection is storing value types such as integers, the value must be boxed before being added to the collection and unboxed when the value is retrieved from the collection. These are expensive operations. +First, if the collection is storing value types such as integers, the value must be boxed before being added to the collection and unboxed when the value is retrieved from the collection. These operations are expensive. -Second, there is no way to control which types can be added to a collection. It is perfectly legal to add an integer and a string to the same collection, even though this is probably not what was intended. Therefore, in order for your code to be type safe, you have to check that the type retrieved from the collection really is what was expected. +Second, there's no way to control which types can be added to a collection. It's perfectly legal to add an integer and a string to the same collection, even though it's probably not what was intended. Therefore, in order for your code to be type safe, you have to check that the type retrieved from the collection really is what was expected. The following code example shows the two main drawbacks of the .NET Framework collections before generics. @@ -71,7 +71,7 @@ Popped an int: 7 ## Example: Benefit of using generic collection -The new namespace contains many of the same collections found in the namespace, but they have been modified to accept generic type parameters. This eliminates the two drawbacks of non-generic collections: the boxing and unboxing of value types and the inability to specify the types to be stored in the collections. Operations on the two collections are identical; they differ only in how they are instantiated. +The new namespace contains many of the same collections found in the namespace, but they've been modified to accept generic type parameters. This change eliminates the two drawbacks of non-generic collections: the boxing and unboxing of value types and the inability to specify the types to be stored in the collections. Operations on the two collections are identical; they differ only in how they're instantiated. Compare the example written above with this example that uses a generic collection. On large collections that are frequently accessed, the performance of this example will be significantly greater than the preceding example. @@ -89,8 +89,8 @@ int main() // This Stack can only contain integers. Stack ^s = gcnew Stack(); - // Push an integer to the Stack. - // A boxing operation is performed here. + // Push an integer to the Stack. + // No boxing operation is performed here. s->Push(7); s->Push(14); diff --git a/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md b/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md index 0065f44486..5caafaeebf 100644 --- a/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md +++ b/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" title: "How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["Functions with interior and native pointers, overloading"] -ms.assetid: d70df625-4aad-457c-84f5-70a0a290cc1f --- # How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI) @@ -49,7 +48,7 @@ int main() { G ^pG = gcnew G; // common language runtime heap f( &pS->i ); f( &pG->i ); -}; +} ``` ```Output diff --git a/docs/extensions/interface-class-cpp-component-extensions.md b/docs/extensions/interface-class-cpp-component-extensions.md index 90dfd56870..9688279ef0 100644 --- a/docs/extensions/interface-class-cpp-component-extensions.md +++ b/docs/extensions/interface-class-cpp-component-extensions.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: interface class (C++/CLI and C++/CX)" +description: "Learn more about: interface class (C++/CLI and C++/CX)" title: "interface class (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +ms.date: 04/15/2022 ms.topic: "reference" -f1_keywords: ["interface_CPP"] +f1_keywords: ["interface_CPP", "interface class", "interface class_CPP"] helpviewer_keywords: ["interface class keyword", "interface struct keyword"] ms.assetid: 3ccea701-f50b-4da7-ad6b-f0ee1203e2b9 --- -# interface class (C++/CLI and C++/CX) +# `interface class` (C++/CLI and C++/CX) -Declares an interface. For information on native interfaces, see [__interface](../cpp/interface.md). +Declares an interface. For information on native interfaces, see [`__interface`](../cpp/interface.md). -## All Runtimes +## All runtimes ### Syntax @@ -22,39 +22,39 @@ interface_access interface struct name : inherit_access base_interface {}; ### Parameters -*interface_access*
-The accessibility of an interface outside the assembly. Possible values are **`public`** and **`private`**. **`private`** is the default. Nested interfaces cannot have an *interface_access* specifier. +*`interface_access`*\ +The accessibility of an interface outside the assembly. Possible values are **`public`** and **`private`**. **`private`** is the default. Nested interfaces can't have an *`interface_access`* specifier. -*name*
+*`name`*\ The name of the interface. -*inherit_access*
-The accessibility of *base_interface*. The only permitted accessibility for a base interface is **`public`** (the default). +*`inherit_access`*\ +The accessibility of *`base_interface`*. The only permitted accessibility for a base interface is **`public`** (the default). -*base_interface*
-(Optional) A base interface for interface *name*. +*`base_interface`*\ +(Optional) A base interface for interface *`name`*. ### Remarks -**interface struct** is equivalent to **interface class**. +**`interface struct`** is equivalent to **`interface class`**. An interface can contain declarations for functions, events, and properties. All interface members have public accessibility. An interface can also contain static data members, functions, events, and properties, and these static members must be defined in the interface. -An interface defines how a class may be implemented. An interface is not a class and classes can only implement interfaces. When a class defines a function declared in an interface, the function is implemented, not overridden. Therefore, name lookup does not include interface members. +An interface defines how a class may be implemented. An interface isn't a class and classes can only implement interfaces. When a class defines a function declared in an interface, the function is implemented, not overridden. Therefore, name lookup doesn't include interface members. -A class or struct that derives from an interface must implement all members of the interface. When implementing interface *name* you must also implement the interfaces in the `base_interface` list. +A `class` or `struct` that derives from an interface must implement all members of the interface. When implementing interface *`name`*, you must also implement the interfaces in the *`base_interface`* list. For more information, see: -- [Interface Static Constructor](../dotnet/how-to-define-an-interface-static-constructor-cpp-cli.md) +- [Interface static constructor](../dotnet/how-to-define-an-interface-static-constructor-cpp-cli.md) -- [Generic Interfaces (C++/CLI)](generic-interfaces-visual-cpp.md) +- [Generic interfaces (C++/CLI)](generic-interfaces-visual-cpp.md) For information on other CLR types, see [Classes and Structs](classes-and-structs-cpp-component-extensions.md). -You can detect at compile time if a type is an interface with `__is_interface_class(type)`. For more information, see [Compiler Support for Type Traits](compiler-support-for-type-traits-cpp-component-extensions.md). +You can detect at compile time if a type is an interface with `__is_interface_class(type)`. For more information, see [Compiler support for type traits](compiler-support-for-type-traits-cpp-component-extensions.md). -In the development environment, you can get F1 help on these keywords by highlighting the keyword, (**`interface class`**, for example) and pressing F1. +In the development environment, you can get F1 help on these keywords by highlighting the keyword (for example, **`interface class`**) and pressing **F1**. ## Windows Runtime diff --git a/docs/extensions/overview-of-generics-in-visual-cpp.md b/docs/extensions/overview-of-generics-in-visual-cpp.md index 108be1e564..5e0760fcad 100644 --- a/docs/extensions/overview-of-generics-in-visual-cpp.md +++ b/docs/extensions/overview-of-generics-in-visual-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Overview of Generics in C++/CLI" title: "Overview of Generics in C++/CLI" +description: "Learn more about: Overview of Generics in C++/CLI" ms.date: "10/12/2018" ms.topic: "reference" helpviewer_keywords: ["generics [C++], about generics", "default initializers [C++]", "type parameters [C++]", "constructed types", "type arguments [C++]", "constructed types, open [C++]", "open constructed types [C++]", "constructed types, closed [C++]"] -ms.assetid: 21f10637-0fce-4916-b925-6c86a126d3aa --- # Overview of Generics in C++/CLI @@ -38,7 +37,7 @@ The *type argument* is the actual type used in place of the type parameter when ### Constructed Type -A type constructed from a generic type is referred to as a *constructed type*. A type not fully specified, such as `List` is an *open constructed type*; a type fully specified, such as `List,` is a *closed constructed type* or *specialized type*. Open constructed types may be used in the definition of other generic types or methods and may not be fully specified until the enclosing generic is itself specified. For example, the following is a use of an open constructed type as a base class for a generic: +A type constructed from a generic type is referred to as a *constructed type*. A type not fully specified, such as `List` is an *open constructed type*; a type fully specified, such as `List`, is a *closed constructed type* or *specialized type*. Open constructed types may be used in the definition of other generic types or methods and may not be fully specified until the enclosing generic is itself specified. For example, the following is a use of an open constructed type as a base class for a generic: ```cpp // generics_overview.cpp diff --git a/docs/extensions/pin-ptr-cpp-cli.md b/docs/extensions/pin-ptr-cpp-cli.md index c5c3f29afd..ea3baddba4 100644 --- a/docs/extensions/pin-ptr-cpp-cli.md +++ b/docs/extensions/pin-ptr-cpp-cli.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: pin_ptr (C++/CLI)" title: "pin_ptr (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: pin_ptr (C++/CLI)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["pin_ptr_cpp", "stdcli::language::pin_ptr", "pin_ptr"] helpviewer_keywords: ["pinning pointers", "pin_ptr keyword [C++]"] -ms.assetid: 6c2e6c73-4ec2-4dce-8e1f-ccf3a9f9d0aa --- # pin_ptr (C++/CLI) @@ -164,7 +163,7 @@ int main() { k = l; // ok Console::WriteLine(*k); -}; +} ``` ```Output diff --git a/docs/extensions/safe-cast-cpp-component-extensions.md b/docs/extensions/safe-cast-cpp-component-extensions.md index 1a192940e9..800fe8605f 100644 --- a/docs/extensions/safe-cast-cpp-component-extensions.md +++ b/docs/extensions/safe-cast-cpp-component-extensions.md @@ -103,7 +103,7 @@ An expression that evaluates to a handle to a reference or value type, a value t The expression `safe_cast<`*type-id*`>(`*expression*`)` converts the operand *expression* to an object of type *type-id*. -The compiler will accept a [static_cast](../cpp/static-cast-operator.md) in most places that it will accept a **safe_cast**. However, **safe_cast** is guaranteed to produce verifiable MSIL, where as a **`static_cast`** could produce unverifiable MSIL. See [Pure and Verifiable Code (C++/CLI)](../dotnet/pure-and-verifiable-code-cpp-cli.md) and [Peverify.exe (PEVerify Tool)](/dotnet/framework/tools/peverify-exe-peverify-tool) for more information on verifiable code. +The compiler will accept a [static_cast](../cpp/static-cast-operator.md) in most places that it will accept a **safe_cast**. However, **safe_cast** is guaranteed to produce verifiable MSIL, whereas a **`static_cast`** could produce unverifiable MSIL. See [Pure and Verifiable Code (C++/CLI)](../dotnet/pure-and-verifiable-code-cpp-cli.md) and [Peverify.exe (PEVerify Tool)](/dotnet/framework/tools/peverify-exe-peverify-tool) for more information on verifiable code. Like **`static_cast`**, **safe_cast** invokes user-defined conversions. diff --git a/docs/extensions/string-cpp-component-extensions.md b/docs/extensions/string-cpp-component-extensions.md index 57a1c3d638..6af1f65170 100644 --- a/docs/extensions/string-cpp-component-extensions.md +++ b/docs/extensions/string-cpp-component-extensions.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: String (C++/CLI and C++/CX)" title: "String (C++/CLI and C++/CX)" -ms.date: "10/08/2018" +description: "Learn more about: String (C++/CLI and C++/CX)" +ms.date: 10/08/2018 ms.topic: "reference" helpviewer_keywords: ["string support with /clr", "/clr compiler option [C++], string support"] -ms.assetid: c695f965-9be0-4e20-9661-373bfee6557e --- # String (C++/CLI and C++/CX) @@ -104,7 +103,7 @@ int main() { if (a != b) Console::WriteLine("a and b are not equal"); - // System:String^ and tracking reference + // System::String^ and tracking reference String^% rstr1 = a; Console::WriteLine(rstr1); @@ -211,11 +210,11 @@ The following sample shows that the compiler distinguishes between native string using namespace System; int func() { throw "simple string"; // const char * -}; +} int func2() { throw "string" + "string"; // returns System::String -}; +} template void func3(T t) { @@ -254,6 +253,6 @@ System.String ## See also -[Component Extensions for .NET and UWP](component-extensions-for-runtime-platforms.md)
-[String and Character Literals](../cpp/string-and-character-literals-cpp.md)
+[Component Extensions for .NET and UWP](component-extensions-for-runtime-platforms.md)\ +[String and Character Literals](../cpp/string-and-character-literals-cpp.md)\ [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) diff --git a/docs/get-started/includes/git-source-control.md b/docs/get-started/includes/git-source-control.md index 86a7efc76a..c1d17bec68 100644 --- a/docs/get-started/includes/git-source-control.md +++ b/docs/get-started/includes/git-source-control.md @@ -20,7 +20,7 @@ To associate your code with Git, you start by creating a new Git repository wher 1. In the **Create a Git repository** dialog box, sign in to GitHub. - :::image type="content" source="../media/vs-2022/git-create-repo.png" alt-text="Screenshot of the Create a Git Repository dialog window where you can sign in to GitHub."::: + :::image type="content" source="../media/vs-2022/git-create-repo.png" alt-text="Screenshot of the Create a Git Repository dialog window where you create a new GitHub repository."::: The repository name auto-populates based on your folder location. By default, your new repository is private, which means you're the only one who can access it. @@ -29,9 +29,9 @@ To associate your code with Git, you start by creating a new Git repository wher 1. Select **Create and Push**. - After you create your repository, you see status details in the status bar. + After you create your repository, status details appear in the status bar. - :::image type="content" source="../media/vs-2022/git-new-private-repo-status-details.png" alt-text="Screenshot of the repo status bar that's below the Solution Explorer pane in Visual Studio."::: + :::image type="content" source="../media/vs-2022/git-new-private-repo-status-details.png" alt-text="Screenshot of the repo status bar located below the Visual Studio Solution Explorer pane, showing the branch name and number of outstanding changes."::: The first icon with the arrows shows how many outgoing/incoming commits are in your current branch. You can use this icon to pull any incoming commits or push any outgoing commits. You can also choose to view these commits first. To do so, select the icon, and then select **View Outgoing/Incoming**. diff --git a/docs/get-started/index.yml b/docs/get-started/index.yml index fc9645a01a..d338b6c128 100644 --- a/docs/get-started/index.yml +++ b/docs/get-started/index.yml @@ -9,11 +9,10 @@ metadata: ms.custom: vs-acquisition ms.topic: landing-page ms.date: 12/06/2021 - author: corob-msft - ms.author: corob - manager: markl - ms.prod: visual-cpp - ms.technology: vs-acquisition + author: tylermsft + ms.author: twhitney + manager: coxford + ms.service: visual-cpp dev_langs: - C++ @@ -70,11 +69,11 @@ landingContent: - linkListType: tutorial links: - text: Open code from a repo - url: /visualstudio/get-started/tutorial-open-project-from-repo.md + url: /visualstudio/get-started/tutorial-open-project-from-repo - text: Write and edit code - url: /visualstudio/get-started/tutorial-editor.md + url: /visualstudio/get-started/tutorial-editor - text: Compile and build - url: /visualstudio/ide/compiling-and-building-in-visual-studio.md + url: /visualstudio/ide/compiling-and-building-in-visual-studio - text: Debug your C++ code url: /visualstudio/debugger/quickstart-debug-with-cplusplus - text: Test your C++ code diff --git a/docs/get-started/media/calc-divide-by-zero-fail.png b/docs/get-started/media/calc-divide-by-zero-fail.png new file mode 100644 index 0000000000..aabbef891a Binary files /dev/null and b/docs/get-started/media/calc-divide-by-zero-fail.png differ diff --git a/docs/get-started/media/calc-final-verification.png b/docs/get-started/media/calc-final-verification.png new file mode 100644 index 0000000000..7ed460ef3c Binary files /dev/null and b/docs/get-started/media/calc-final-verification.png differ diff --git a/docs/get-started/media/calc-vs2017-conditional-breakpoint.png b/docs/get-started/media/calc-vs2017-conditional-breakpoint.png new file mode 100644 index 0000000000..a68503955a Binary files /dev/null and b/docs/get-started/media/calc-vs2017-conditional-breakpoint.png differ diff --git a/docs/get-started/media/calc-vs2017-create-calculator-class.png b/docs/get-started/media/calc-vs2017-create-calculator-class.png new file mode 100644 index 0000000000..ff3accfbe2 Binary files /dev/null and b/docs/get-started/media/calc-vs2017-create-calculator-class.png differ diff --git a/docs/get-started/media/calc-vs2017-create-definition.png b/docs/get-started/media/calc-vs2017-create-definition.png new file mode 100644 index 0000000000..8782a1404e Binary files /dev/null and b/docs/get-started/media/calc-vs2017-create-definition.png differ diff --git a/docs/get-started/media/calc-vs2017-debug-breakpoint.png b/docs/get-started/media/calc-vs2017-debug-breakpoint.png new file mode 100644 index 0000000000..5a8c1e203d Binary files /dev/null and b/docs/get-started/media/calc-vs2017-debug-breakpoint.png differ diff --git a/docs/get-started/media/calc-vs2017-debug-inf.png b/docs/get-started/media/calc-vs2017-debug-inf.png new file mode 100644 index 0000000000..eee553c418 Binary files /dev/null and b/docs/get-started/media/calc-vs2017-debug-inf.png differ diff --git a/docs/get-started/media/calc-vs2017-hover-tooltip.png b/docs/get-started/media/calc-vs2017-hover-tooltip.png new file mode 100644 index 0000000000..3fc57e6626 Binary files /dev/null and b/docs/get-started/media/calc-vs2017-hover-tooltip.png differ diff --git a/docs/get-started/media/calc-vs2017-new-project-dialog.png b/docs/get-started/media/calc-vs2017-new-project-dialog.png new file mode 100644 index 0000000000..bb80014a16 Binary files /dev/null and b/docs/get-started/media/calc-vs2017-new-project-dialog.png differ diff --git a/docs/get-started/media/calc-vs2017-set-breakpoint.png b/docs/get-started/media/calc-vs2017-set-breakpoint.png new file mode 100644 index 0000000000..df4c6b693b Binary files /dev/null and b/docs/get-started/media/calc-vs2017-set-breakpoint.png differ diff --git a/docs/get-started/media/calc-vs2019-build-your-project.png b/docs/get-started/media/calc-vs2019-build-your-project.png index 2fc5b19b4e..733930b8a2 100644 Binary files a/docs/get-started/media/calc-vs2019-build-your-project.png and b/docs/get-started/media/calc-vs2019-build-your-project.png differ diff --git a/docs/get-started/media/calc-vs2019-choose-console-app.png b/docs/get-started/media/calc-vs2019-choose-console-app.png deleted file mode 100644 index 57501b418c..0000000000 Binary files a/docs/get-started/media/calc-vs2019-choose-console-app.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-conditional-breakpoint.png b/docs/get-started/media/calc-vs2019-conditional-breakpoint.png deleted file mode 100644 index 037e8d4875..0000000000 Binary files a/docs/get-started/media/calc-vs2019-conditional-breakpoint.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-create-calculator-class.png b/docs/get-started/media/calc-vs2019-create-calculator-class.png deleted file mode 100644 index 99b438d465..0000000000 Binary files a/docs/get-started/media/calc-vs2019-create-calculator-class.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-create-definition.png b/docs/get-started/media/calc-vs2019-create-definition.png deleted file mode 100644 index 8003656743..0000000000 Binary files a/docs/get-started/media/calc-vs2019-create-definition.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-debug-breakpoint.png b/docs/get-started/media/calc-vs2019-debug-breakpoint.png deleted file mode 100644 index 2e9988c00e..0000000000 Binary files a/docs/get-started/media/calc-vs2019-debug-breakpoint.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-divide-by-zero-fail.png b/docs/get-started/media/calc-vs2019-divide-by-zero-fail.png deleted file mode 100644 index 1ac14bd830..0000000000 Binary files a/docs/get-started/media/calc-vs2019-divide-by-zero-fail.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-final-verification.png b/docs/get-started/media/calc-vs2019-final-verification.png deleted file mode 100644 index eb7befa4aa..0000000000 Binary files a/docs/get-started/media/calc-vs2019-final-verification.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2019-five-plus-five.png b/docs/get-started/media/calc-vs2019-five-plus-five.png index f1bbd82c34..b6aac8a07e 100644 Binary files a/docs/get-started/media/calc-vs2019-five-plus-five.png and b/docs/get-started/media/calc-vs2019-five-plus-five.png differ diff --git a/docs/get-started/media/calc-vs2019-hover-tooltip.png b/docs/get-started/media/calc-vs2019-hover-tooltip.png index 7fdca8eeb3..9d56d7808b 100644 Binary files a/docs/get-started/media/calc-vs2019-hover-tooltip.png and b/docs/get-started/media/calc-vs2019-hover-tooltip.png differ diff --git a/docs/get-started/media/calc-vs2019-name-your-project.png b/docs/get-started/media/calc-vs2019-name-your-project.png index 2a1cd21703..16bfc349e1 100644 Binary files a/docs/get-started/media/calc-vs2019-name-your-project.png and b/docs/get-started/media/calc-vs2019-name-your-project.png differ diff --git a/docs/get-started/media/calc-vs2019-set-breakpoint.png b/docs/get-started/media/calc-vs2019-set-breakpoint.png deleted file mode 100644 index 1df9186a44..0000000000 Binary files a/docs/get-started/media/calc-vs2019-set-breakpoint.png and /dev/null differ diff --git a/docs/get-started/media/calc-vs2022-autos.png b/docs/get-started/media/calc-vs2022-autos.png new file mode 100644 index 0000000000..6dfdf8199e Binary files /dev/null and b/docs/get-started/media/calc-vs2022-autos.png differ diff --git a/docs/get-started/media/calc-vs2022-choose-console-app.png b/docs/get-started/media/calc-vs2022-choose-console-app.png new file mode 100644 index 0000000000..b4c5e574a5 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-choose-console-app.png differ diff --git a/docs/get-started/media/calc-vs2022-conditional-breakpoint.png b/docs/get-started/media/calc-vs2022-conditional-breakpoint.png new file mode 100644 index 0000000000..0d25a762f8 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-conditional-breakpoint.png differ diff --git a/docs/get-started/media/calc-vs2022-create-calculator-class.png b/docs/get-started/media/calc-vs2022-create-calculator-class.png new file mode 100644 index 0000000000..79eeff423a Binary files /dev/null and b/docs/get-started/media/calc-vs2022-create-calculator-class.png differ diff --git a/docs/get-started/media/calc-vs2022-create-definition.png b/docs/get-started/media/calc-vs2022-create-definition.png new file mode 100644 index 0000000000..6b034ba971 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-create-definition.png differ diff --git a/docs/get-started/media/calc-vs2022-ctor-definition.png b/docs/get-started/media/calc-vs2022-ctor-definition.png new file mode 100644 index 0000000000..c96f8008f1 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-ctor-definition.png differ diff --git a/docs/get-started/media/calc-vs2022-debug-breakpoint.png b/docs/get-started/media/calc-vs2022-debug-breakpoint.png new file mode 100644 index 0000000000..3266b4b4e2 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-debug-breakpoint.png differ diff --git a/docs/get-started/media/calc-vs2022-debug-inf.png b/docs/get-started/media/calc-vs2022-debug-inf.png new file mode 100644 index 0000000000..2e16e63a35 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-debug-inf.png differ diff --git a/docs/get-started/media/calc-vs2022-initial-dialog.png b/docs/get-started/media/calc-vs2022-initial-dialog.png index f37534789a..b807d690ba 100644 Binary files a/docs/get-started/media/calc-vs2022-initial-dialog.png and b/docs/get-started/media/calc-vs2022-initial-dialog.png differ diff --git a/docs/get-started/media/calc-vs2022-set-breakpoint.png b/docs/get-started/media/calc-vs2022-set-breakpoint.png new file mode 100644 index 0000000000..b90dd13458 Binary files /dev/null and b/docs/get-started/media/calc-vs2022-set-breakpoint.png differ diff --git a/docs/get-started/media/calculator-app.gif b/docs/get-started/media/calculator-app.gif deleted file mode 100644 index 3f0d8778ea..0000000000 Binary files a/docs/get-started/media/calculator-app.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-conditional-breakpoint.gif b/docs/get-started/media/calculator-conditional-breakpoint.gif deleted file mode 100644 index ec477879fb..0000000000 Binary files a/docs/get-started/media/calculator-conditional-breakpoint.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-create-class.gif b/docs/get-started/media/calculator-create-class.gif deleted file mode 100644 index 028f3a22ac..0000000000 Binary files a/docs/get-started/media/calculator-create-class.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-create-definition.gif b/docs/get-started/media/calculator-create-definition.gif deleted file mode 100644 index 5a3f002d42..0000000000 Binary files a/docs/get-started/media/calculator-create-definition.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-debug-conditional.gif b/docs/get-started/media/calculator-debug-conditional.gif deleted file mode 100644 index 50f1c18dc9..0000000000 Binary files a/docs/get-started/media/calculator-debug-conditional.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-divide-by-zero-fail.png b/docs/get-started/media/calculator-divide-by-zero-fail.png index 8b1e09fda5..da42b04840 100644 Binary files a/docs/get-started/media/calculator-divide-by-zero-fail.png and b/docs/get-started/media/calculator-divide-by-zero-fail.png differ diff --git a/docs/get-started/media/calculator-final-verification.gif b/docs/get-started/media/calculator-final-verification.gif deleted file mode 100644 index 49c8588feb..0000000000 Binary files a/docs/get-started/media/calculator-final-verification.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-first-launch.gif b/docs/get-started/media/calculator-first-launch.gif deleted file mode 100644 index 54ffdcd711..0000000000 Binary files a/docs/get-started/media/calculator-first-launch.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-first-launch.png b/docs/get-started/media/calculator-first-launch.png new file mode 100644 index 0000000000..43c8547c94 Binary files /dev/null and b/docs/get-started/media/calculator-first-launch.png differ diff --git a/docs/get-started/media/calculator-five-plus-five.png b/docs/get-started/media/calculator-five-plus-five.png index 4d8f0ffde7..885c023879 100644 Binary files a/docs/get-started/media/calculator-five-plus-five.png and b/docs/get-started/media/calculator-five-plus-five.png differ diff --git a/docs/get-started/media/calculator-hello-world-console.png b/docs/get-started/media/calculator-hello-world-console.png index 40b3e63569..5f804bb016 100644 Binary files a/docs/get-started/media/calculator-hello-world-console.png and b/docs/get-started/media/calculator-hello-world-console.png differ diff --git a/docs/get-started/media/calculator-hover-tooltip.gif b/docs/get-started/media/calculator-hover-tooltip.gif deleted file mode 100644 index 9e430ec801..0000000000 Binary files a/docs/get-started/media/calculator-hover-tooltip.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-initial-build-output.png b/docs/get-started/media/calculator-initial-build-output.png index b3c43caaa1..03890a1065 100644 Binary files a/docs/get-started/media/calculator-initial-build-output.png and b/docs/get-started/media/calculator-initial-build-output.png differ diff --git a/docs/get-started/media/calculator-new-project-dialog.gif b/docs/get-started/media/calculator-new-project-dialog.gif deleted file mode 100644 index 459dee0c1d..0000000000 Binary files a/docs/get-started/media/calculator-new-project-dialog.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-new-project-dialog.png b/docs/get-started/media/calculator-new-project-dialog.png deleted file mode 100644 index fb2686bdc9..0000000000 Binary files a/docs/get-started/media/calculator-new-project-dialog.png and /dev/null differ diff --git a/docs/get-started/media/calculator-set-breakpoint.gif b/docs/get-started/media/calculator-set-breakpoint.gif deleted file mode 100644 index d736a4217d..0000000000 Binary files a/docs/get-started/media/calculator-set-breakpoint.gif and /dev/null differ diff --git a/docs/get-started/media/calculator-undefined-zero.gif b/docs/get-started/media/calculator-undefined-zero.gif deleted file mode 100644 index bb7db5c40f..0000000000 Binary files a/docs/get-started/media/calculator-undefined-zero.gif and /dev/null differ diff --git a/docs/get-started/tutorial-console-cpp.md b/docs/get-started/tutorial-console-cpp.md index 0383f331c2..5a251dca67 100644 --- a/docs/get-started/tutorial-console-cpp.md +++ b/docs/get-started/tutorial-console-cpp.md @@ -2,43 +2,45 @@ title: "Create a console calculator in C++" description: "Create a Hello World console app and a calculator app in Visual C++" ms.custom: "acquisition, mvc" -ms.date: 08/31/2021 +ms.date: 10/08/2024 ms.topic: "tutorial" ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 --- # Create a console calculator in C++ ::: moniker range=">=msvc-160" -The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. That's what you'll create first in Visual Studio in this article, and then we'll move on to something more challenging: a calculator app. +The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. You start with that in this article, and then move on to something more challenging: a calculator app. ## Prerequisites -- Have Visual Studio with the **Desktop development with C++** workload installed and running on your computer. If it's not installed yet, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). +- Visual Studio with the **Desktop development with C++** workload installed and running on your computer. To install it, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). +- This tutorial demonstrates a feature called edit and continue which allows you to make changes to your code while the app is running. To enable edit and continue, from the main menu select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. ## Create your app project -Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize your projects. A project contains all the options, configurations, and rules used to build your apps. It also manages the relationship between all the project's files and any external files. To create your app, first, you'll create a new project and solution. +Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize one or more projects. A project contains all the options, configurations, and rules used to build an app. It also manages the relationship between all the project's files and any external files. To create your app, first, create a new project and solution. -1. If you've just started Visual Studio, you'll see the Visual Studio Start dialog box. Choose **Create a new project** to get started. +1. Start Visual Studio--the Visual Studio Start dialog box appears. Select **Create a new project** to get started. - ![Screenshot of the Visual Studio 2022 initial dialog.](./media/calc-vs2022-initial-dialog.png) + :::image type="complex" source="./media/calc-vs2022-initial-dialog.png" alt-text="Screenshot of dialog that appears when Visual Studio 2022 starts."::: + The dialog has options to clone a repository, open a project or solution, open a local folder, and create a new project." + :::image-end::: - Otherwise, on the menubar in Visual Studio, choose **File** > **New** > **Project**. The **Create a new project** window opens. +1. In the **Create a new project** dialog, set the language dropdown to **C++**, set the platform dropdown to **Windows**, select **Console App** from the list of project types, then select **Next**. -1. In the list of project templates, choose **Console App**, then choose **Next**. - - ![Screenshot of choosing the Console App template.](./media/calc-vs2019-choose-console-app.png "Choose the Console App template") + :::image type="complex" source="./media/calc-vs2022-choose-console-app.png" alt-text="Screenshot of the Visual Studio Create a new project dialog."::: + The language dropdown is set to C++, the platform dropdown is set to Windows, and project types like Empty Project, Console App, CMake Project, Windows Desktop Wizard, and so on, appear in the list of project types." + :::image-end::: > [!Important] - > Make sure you choose the C++ version of the **Console App** template. It has the **C++**, **Windows**, and **Console** tags, and the icon has "++" in the corner. + > Make sure you select the C++ version of the **Console App** template. It has the **C++**, **Windows**, and **Console** tags, and the icon has "++" in the corner. -1. In the **Configure your new project** dialog box, select the **Project name** edit box, name your new project *CalculatorTutorial*, then choose **Create**. +1. In the **Configure your new project** dialog box, select the **Project name** text box, name your new project *CalculatorTutorial*, then select **Create**. - ![Name your project in the Configure your new project dialog.](./media/calc-vs2019-name-your-project.png "Name your project in the Configure your new project dialog") + :::image type="content" source="./media/calc-vs2019-name-your-project.png" alt-text="Screenshot of the Visual Studio Configure your new project dialog. It has fields for project name, project location, and Solution name."::: - An empty C++ Windows console application gets created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: + An empty C++ Windows console application 'Hello World' app is created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -67,25 +69,29 @@ Visual Studio uses *projects* to organize the code for an app, and *solutions* t The template for a new Windows console application creates a simple C++ "Hello World" app. At this point, you can see how Visual Studio builds and runs the apps you create right from the IDE. -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, select **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. + + :::image type="content" source="./media/calc-vs2019-build-your-project.png" alt-text="Screenshot of the Visual Studio Output window. It's displaying a message that the build succeeded."::: + +1. To run the code, on the menu bar, select **Debug** > **Start without debugging** (Ctrl+F5). - ![Screenshot of Visual Studio 2019 with the Output window showing the result of the build process.](./media/calc-vs2019-build-your-project.png "Build the project") + :::image type="content" source="./media/calc-vs2019-hello-world-console.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the output of the application: Hello World!"::: -1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. + A console window opens and your app runs within it. - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the code ran successfully.](./media/calc-vs2019-hello-world-console.png "Start the project") + When you start a console app in Visual Studio, it runs your code, then prints "Press any key to close this window . . ." to give you a chance to see the output. - A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to close this window . . ." to give you a chance to see the output. Congratulations! You've created your first "Hello, world!" console app in Visual Studio! + Congratulations! You created your first "Hello, world!" console app in Visual Studio! 1. Press a key to dismiss the console window and return to Visual Studio. -You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we'll show you how to debug it if it doesn't. +You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we show you how to debug it if it doesn't. ## Edit the code -Now let's turn the code in this template into a calculator app. +Now let's modify the code in this template to be a calculator app. -1. In the *CalculatorTutorial.cpp* file, edit the code to match this example: +1. Replace the contents of the *`CalculatorTutorial.cpp`* file with the following code so that it matches this example: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -116,35 +122,41 @@ Now let's turn the code in this template into a calculator app. > Understanding the code: > - > - The `#include` statements allow you to reference code located in other files. Sometimes, you may see a filename surrounded by angle brackets (**\<\>**); other times, it's surrounded by quotes (**" "**). In general, angle brackets are used when referencing the C++ Standard Library, while quotes are used for other files. - > - The `using namespace std;` line tells the compiler to expect stuff from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with a `std::`, to denote its scope. For instance, without that line, each reference to `cout` would have to be written as `std::cout`. The **`using`** statement is added to make the code look more clean. - > - The `cout` keyword is used to print to standard output in C++. The **\<\<** operator tells the compiler to send whatever is to the right of it to the standard output. - > - The **endl** keyword is like the Enter key; it ends the line and moves the cursor to the next line. It is a better practice to put a `\n` inside the string (contained by "") to do the same thing, as `endl` always flushes the buffer and can hurt the performance of the program, but since this is a very small app, `endl` is used instead for better readability. + > - The `#include` statement brings in code in other files. Sometimes, you may see a filename surrounded by angle brackets like ``. The angle brackets instruct the compiler to look for the `iostream` header file first in the standard system directories, and if not found, to look in directories specific to the project. Other times, you may see a filename surrounded by quotes like `"someHeader.h"`. The quotes instruct the compiler to skip looking in the standard system directories and instead only look in directories specific to the project. + > - The `using namespace std;` tells the compiler to expect code from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with `std::` to denote its scope. For instance, without that line, each reference to `cout` would be written as `std::cout`. The **`using`** statement is added to make it more convenient to access code in another namespace. + > - The `cout` keyword is used to print to standard output in C++. The `<<` operator tells the compiler to send whatever is to the right of it to the standard output. + > - The `endl` keyword is like the Enter key; it ends the line and moves the cursor to the next line. It's a better practice to put a `\n` inside the string (contained by `""`) to do the same thing because `endl` always flushes the buffer which can hurt the performance of the program. But since this is a very small app, `endl` is used instead. > - All C++ statements must end with semicolons and all C++ applications must contain a `main()` function. This function is what the program runs at the start. All code must be accessible from `main()` in order to be used. -1. To save the file, enter **Ctrl+S**, or choose the **Save** icon near the top of the IDE, the floppy disk icon in the toolbar under the menu bar. +1. To save the file, press **Ctrl+S**, or select the floppy disk icon in the toolbar under the menu bar. -1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and choose **Start Without Debugging**. You should see a console window appear that displays the text specified in the code. +1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and select **Start Without Debugging**. You should see a console window appear that looks like this. 1. Close the console window when you're done. ## Add code to do some math -It's time to add some math logic. +A class is like a blueprint for an object that does something. In this case, we define a calculator class to contain the math logic. -### To add a Calculator class +### Add a Calculator class -1. Go to the **Project** menu and choose **Add Class**. In the **Class Name** edit box, enter *Calculator*. Choose **OK**. Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. +1. Go to the **Project** menu and select **Add Class**. In the **Class Name** edit box, enter *Calculator*. Select **OK**. - ![Screenshot of the Add Class dialog box with Calculator typed in the Class Name text box.](./media/calc-vs2019-create-calculator-class.png "Create the Calculator class") + :::image type="complex" source="./media/calc-vs2022-create-calculator-class.png" alt-text="Screenshot of the Visual Studio Add Class dialog box."::: + The class name field contains the text calculator. The .h file field contains Calculator.h. The .cpp file field contains Calculator.cpp. The base class field is empty. The options for inline, and Managed are unchecked. + :::image-end::: - A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. The **Add Class** wizard you used above created .h and .cpp files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, you can open it from the menu bar: choose **View** > **Solution Explorer**. + Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss saving any changes. - ![Screenshot of the Visual Studio 2019 Solution Explorer window displaying the Calculator Tutorial project.](./media/calc-vs2019-solution-explorer.png "Solution Explorer") + The **Add Class** wizard creates `.h` and `.cpp` files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, open it from the menu bar via **View** > **Solution Explorer**. - You should now have three tabs open in the editor: *CalculatorTutorial.cpp*, *Calculator.h*, and *Calculator.cpp*. If you accidentally close one of them, you can reopen it by double-clicking it in the **Solution Explorer** window. + :::image type="complex" source="./media/calc-vs2019-solution-explorer.png" alt-text="Screenshot of the Visual Studio Solution Explorer window."::: + The calculator tutorial project has a header files node containing Calculator.h. A Source Files node contains Calculator.cpp and CalculatorTutorial.cpp. Nodes for references, external dependencies, and resource files are visible but closed. + :::image-end::: -1. In **Calculator.h**, remove the `Calculator();` and `~Calculator();` lines that were generated, since you won't need them here. Next, add the following line of code so the file now looks like this: + You can open a file by double-clicking it in the **Solution Explorer** window. Double-click `Calculator.h` to open it. + +1. Replace the contents of **`Calculator.h`** with the following code so that the file now looks like this: ```cpp #pragma once @@ -157,26 +169,25 @@ It's time to add some math logic. > Understanding the code > - > - The line you added declares a new function called `Calculate`, which we'll use to run math operations for addition, subtraction, multiplication, and division. - > - C++ code is organized into *header* (.h) files and *source* (.cpp) files. Several other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where 'filename.h' is the name of the file that declares the variables or functions you want to use. - > - The two lines you deleted declared a *constructor* and *destructor* for the class. For a simple class like this one, the compiler creates them for you, and their uses are beyond the scope of this tutorial. + > - This code declares a new function called `Calculate`, which handles math operations for addition, subtraction, multiplication, and division. + > - C++ code is organized into *header* (`.h`) files and *source* (`.cpp`) files. Some other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where `filename.h` is the name of the file that declares the variables or functions you want to use. > - It's good practice to organize your code into different files based on what it does, so it's easy to find the code you need later. In our case, we define the `Calculator` class separately from the file containing the `main()` function, but we plan to reference the `Calculator` class in `main()`. -1. You'll see a green squiggle appear under `Calculate`. It's because we haven't defined the `Calculate` function in the .cpp file. Hover over the word, click the lightbulb (in this case, a screwdriver) that pops up, and choose **Create definition of 'Calculate' in Calculator.cpp**. +1. A green squiggle appears under `Calculate` because although the `Calculate` function is *declared*, it isn't *defined*. Hover over `Calculate`, click the down arrow on the screwdriver icon, and select **Create definition of 'Calculate' in `Calculator.cpp`**. - ![Screenshot of Visual Studio 2019 showing the Create definition of Calculate in Calculator C P P option highlighted.](./media/calc-vs2019-create-definition.png "Create definition of Calculate") + :::image type="content" source="./media/calc-vs2022-create-definition.png" alt-text="Screenshot of a screwdriver dropdown in the Visual Studio editor window. The option 'Create definition of Calculate in Calculator.cpp' is highlighted."::: - A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *Calculator.cpp*. + This code is added to *`Calculator.cpp`*: - ![Pop-up with definition of Calculate.](./media/calc-vs2019-pop-up-definition.png "Pop-up with definition of Calculate") + :::image type="complex" source="./media/calc-vs2022-ctor-definition.png" alt-text="Screenshot of the Visual Studio editor showing the definition of the 'Calculate' function."::: + The definition of the function is: double Calculator::Calculate( double x, char oper, double y) { return 0.0; } + :::image-end::: - Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up. + Currently, it just returns 0.0. Let's change that. -1. Switch to the *Calculator.cpp* file in the editor window. Remove the `Calculator()` and `~Calculator()` sections (as you did in the .h file) and add the following code to `Calculate()`: +1. Switch to the *`Calculator.cpp`* file in the editor window. Replace the contents of *`Calculator::Calculate(double x, char oper, double y)`* with: ```cpp - #include "Calculator.h" - double Calculator::Calculate(double x, char oper, double y) { switch(oper) @@ -197,16 +208,16 @@ It's time to add some math logic. > Understanding the code > - > - The function `Calculate` consumes a number, an operator, and a second number, then performs the requested operation on the numbers. - > - The switch statement checks which operator was provided, and only executes the case corresponding to that operation. The default: case is a fallback in case the user types an operator that isn't accepted, so the program doesn't break. In general, it's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. - > - The **`double`** keyword denotes a type of number that supports decimals. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return such a number due to the **`double`** at the very start of the code (this denotes the function's return type), which is why we return 0.0 even in the default case. - > - The .h file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The .cpp file has all the implementation details of the function. + > - The function `Calculate` takes a number, an operator, and a second number. Then it performs the requested operation on the two numbers. + > - The `switch` statement checks which operator was provided, and executes the case corresponding to that operation. The `default:` case is a fallback in case the user types an operator that isn't handled by any of the preceding `case` statements. It's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. + > - The **`double`** keyword denotes a type of number that supports decimals. This type of number is called a floating-point number, and `double` means a floating point number that has extra precision. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return a double-precision floating point number due to the **`double`** at the start of the code (this denotes the function's return type), which is why we return 0.0 in the default case. + > - The `.h` file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The `.cpp` file has all the implementation details of the function. -If you build and run the code again at this point, it will still exit after asking which operation to perform. Next, you'll modify the `main` function to do some calculations. +If you build and run the code again at this point, it immediately exits after asking which operation to perform. So, modify the `main` function to do multiple calculations. -### To call the Calculator class member functions +### Call the `Calculator` class member functions -1. Now let's update the `main` function in *CalculatorTutorial.cpp*: +1. Update the `main` function in *`CalculatorTutorial.cpp`* as follows: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -233,7 +244,7 @@ If you build and run the code again at this point, it will still exit after aski { cin >> x >> oper >> y; result = c.Calculate(x, oper, y); - cout << "Result is: " << result << endl; + cout << "Result " << "of " << x << oper << y << " is: " << result << endl; } return 0; @@ -242,75 +253,95 @@ If you build and run the code again at this point, it will still exit after aski > Understanding the code > - > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so a `#include` statement is needed. - > - Some initial variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It is always good practice to give them some initial values to avoid undefined behavior, which is what is done here. - > - The `Calculator c;` line declares an object named 'c' as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. - > - The `while (true)` statement is a loop. The code inside the loop continues to execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. - > - The `cin` keyword is used to accept input from the user. This input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order, assuming the user input matches the required specification. You can modify this line to accept different types of input, for instance, more than two numbers, though the `Calculate()` function would also need to be updated to handle this. - > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values. The function then returns a number that gets stored in `result`. - > - Finally, `result` is printed to the console, so the user sees the result of the calculation. + > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so an `#include` statement is needed to make that code visible to our `main()` function. + > - The variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It's always good practice to give them some initial values to avoid undefined behavior, which is what is done here. + > - The `Calculator c;` line declares an object named `c` as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. + > - The `while (true)` statement is a loop. The code inside the loop executes over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. + > - The `cin` keyword accepts input from the user. The input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order. + > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values and the requested operation. The function then returns a number that is stored in `result`. + > - Finally, `result` is printed to the console and the user sees the result of the calculation. ### Build and test the code again -Now it's time to test the program again to make sure everything works properly. +Now test the program again to make sure everything works properly. 1. Press **Ctrl+F5** to rebuild and start the app. +1. Enter `5+5`, and press **Enter**. Verify that the result is 10. -1. Enter `5 + 5`, and press **Enter**. Verify that the result is 10. - - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the correct result of 5 + 5.](./media/calc-vs2019-five-plus-five.png "The result of 5 + 5") + :::image type="complex" source="./media/calc-vs2019-five-plus-five.png" alt-text="Screenshot of a command window showing the results of running the program."::: + The app output the message: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5+5. The app output: Result of 5+5 is: 10 + :::image-end::: +1. Stop the program by closing the console window. ## Debug the app -Since the user is free to type anything into the console window, let's make sure the calculator handles some input as expected. Instead of running the program, let's debug it instead, so we can inspect what it's doing in detail, step-by-step. +Since the user is free to type anything into the console window, let's make sure the calculator handles unexpected input. Instead of running the program, let's debug it so we can inspect what it's doing step-by-step. -### To run the app in the debugger +### Run the app in the debugger -1. Set a breakpoint on the `result = c.Calculate(x, oper, y);` line, just after the user was asked for input. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window. A red dot appears. +1. In `CalcuatorTutorial.cpp`, set a breakpoint on the line: `result = c.Calculate(x, oper, y);`. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window so that a red dot appears. - ![Screenshot of Visual Studio 2019 showing the red dot that represents a breakpoint.](./media/calc-vs2019-set-breakpoint.png "Set a breakpoint") + :::image type="content" source="./media/calc-vs2022-set-breakpoint.png" alt-text="Screenshot of the Visual Studio editor. A red dot representing a breakpoint appears on the line: result = c.Calculate(x, oper, y)."::: - Now when we debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. + Now when we debug the program, execution pauses at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time we call `Calculate()`, let's make the breakpoint conditional. -1. Right-click the red dot that represents the breakpoint, and choose **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Choose the **Close** button when you're done. The condition is saved automatically. +1. Right-click the red dot that represents the breakpoint, and select **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Select the **Close** button to save the breakpoint condition. - ![Screenshot of Visual Studio 2019 showing the Breakpoint Settings section and a condition added to the Is true value.](./media/calc-vs2019-conditional-breakpoint.png "Set a conditional breakpoint") + :::image type="complex" source="./media/calc-vs2022-conditional-breakpoint.png" alt-text="Screenshot of a set breakpoint"::: + The breakpoint is on the line: result = c dot Calculate ( x, oper, y). 'Conditions...' The Condition option is checked. The Conditions dropdown is set to "Conditional Expression". The condition dropdown is set to "Is true". The condition is set to y == 0 && oper == '/'. + :::image-end::: - Now we pause execution at the breakpoint specifically if a division by 0 is attempted. + Now, execution pauses at the breakpoint when the app tries to divide by 0. -1. To debug the program, press **F5**, or choose the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers: `cin` is smart enough to parse the input appropriately. +1. To debug the program, press **F5**, or select the **Local Windows Debugger** debugger toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can put any number of spaces between the operator and numbers: `cin` is smart enough to parse the input appropriately. - ![Screenshot of Visual Studios 2019 showing that the program paused at the conditional breakpoint.](./media/calc-vs2019-debug-breakpoint.png "Pause at the conditional breakpoint") + :::image type="content" source="./media/calc-vs2022-debug-breakpoint.png" alt-text="Screenshot of Visual Studio editor. Program execution halted at the conditional breakpoint on the line: result = c.Calculate(x, oper, y);."::: ### Useful windows in the debugger -Whenever you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. To see all of the variables from that function, switch to the **Locals** window. You can actually modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we'll leave them alone. +When you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. If you don't see the **Autos** window, from the main menu select **Debug** > **Windows** > **Autos**. - ![Screenshot of the Locals window in Visual Studio 2019.](./media/calc-vs2019-debug-locals.png "The Locals window") + :::image type="complex" source="./media/calc-vs2022-autos.png" alt-text="Screenshot of the Visual Studio debugger Autos window."::: + The value of oper is 47 '/', result is 5, x is 10, and y is 0. + :::image-end::: -You can also just hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. +To see all of the variables from that function, switch to the **Locals** window. Because this is a small function, the Autos and Locals window show the same variables. But you can modify the values of these variables in the Locals window while debugging to see what effect they would have on the program. In this case, we leave them alone. Open the **Locals** window by selecting **Locals** at the bottom of the **Autos** window, or by selecting from the main menu **Debug** > **Windows** > **Locals**. - ![Screenshot of Visual Studio 2019 showing the tooltip that appears displaying the value of the variable.](./media/calc-vs2019-hover-tooltip.png "Hover to view current variable values") + :::image type="complex" source="./media/calc-vs2019-debug-locals.png" alt-text="Screenshot of the Locals window in Visual Studio, displaying the current values of local variables while debugging."::: + The value of oper is 47 '/', result is 0, x is 10, and y is 0. + :::image-end::: -### To continue debugging +You can also hover over variables in the code to see their current values at the point where execution is currently paused. Make sure the editor window is in focus by clicking on it first. -1. The yellow line on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. You'll find yourself in the body of the `Calculate` function. Be careful with **Step Into**; if you do it too much, you may waste a lot of time. It goes into any code you use on the line you are on, including standard library functions. + :::image type="content" source="./media/calc-vs2019-hover-tooltip.png" alt-text="Screenshot of a tooltip showing the value of the variable 'oper', which is 47 or '/'."::: -1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general you should use **Step Over** instead of **Step Into**, unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). +### Continue debugging + +1. The yellow arrow on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. Now you're executing code in the body of the `Calculate` function. Be careful with **Step Into** because it steps into any functions on the line you're on, including standard library functions. It's fine to step into the standard library, but you may be more interested in focusing on your code instead of library code. + +1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general, you should use **Step Over** instead of **Step Into** unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). 1. Continue using **F10** to **Step Over** each line until you get back to the `main()` function in the other file, and stop on the `cout` line. - It looks like the program is doing what is expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. You'll see its value is listed as "inf", which doesn't look right, so let's fix it. The `cout` line just outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: + The program is doing what's expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. Its value is `inf`, which doesn't look right. + + :::image type="complex" source="./media/calc-vs2022-debug-inf.png" alt-text="Screenshot of debugging the calculator."::: + The current statement in the debugger is cout << "Result is: " << result << endl; In the autos window, result is inf. + :::image-end::: - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the result of dividing by zero.](./media/calc-vs2019-divide-by-zero-fail.png "The result of divide by zero") + Let's fix it. The `cout` line outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: - This result happens because division by zero is undefined, so the program doesn't have a numerical answer to the requested operation. + :::image type="complex" source="./media/calc-divide-by-zero-fail.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the result of a division by zero operation."::: + The app outputs: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5-0. The app output: Result is: 5. The user entered 10/0. The app output: Result is: inf + :::image-end::: -### To fix the "divide by zero" error + This result is because division by zero is undefined, so the program doesn't have a numerical answer for the requested operation. -Let's handle division by zero more gracefully, so a user can understand the problem. +### Fix the "divide by zero" error -1. Make the following changes in *CalculatorTutorial.cpp*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**): +Let's handle division by zero more gracefully so that it's easier for the user to understand the problem. + +1. Make the following changes in *`CalculatorTutorial.cpp`*. You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**. Add an `if` statement following `cin >> x >> oper >> y;` to check for division by zero and output a message to the user if it happens. Otherwise, the result is printed. ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -334,46 +365,50 @@ Let's handle division by zero more gracefully, so a user can understand the prob Calculator c; while (true) { - cin >> x >> oper >> y; + cin >> x >> oper >> y; if (oper == '/' && y == 0) { - cout << "Division by 0 exception" << endl; + cout << "Math error: Attempted to divide by zero!" << endl; continue; } else { result = c.Calculate(x, oper, y); } - cout << "Result is: " << result << endl; + cout << "Result " << "of " << x << oper << y << " is: " << result << endl; } return 0; } ``` -1. Now press **F5** once. Program execution continues all the way until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. +1. Press **F5** once. Program execution continues until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the final result after changes.](./media/calc-vs2019-final-verification.png "The final result after changes") + :::image type="complex" source="./media/calc-final-verification.png" alt-text="Screenshot of a console window showing the final output after implementing changes to handle division by zero."::: + The console window displays two lines: 10 / 0 Result is: inf, followed by, 10 / 0 Math error: Attempted to divide by zero. + :::image-end::: > [!Note] - > When you edit code while in debugging mode, there is a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you'll need to step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > When you edit code while in debugging mode, there's a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger displays a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you need to step out of the function, then back into it again to get the updated code. If that doesn't work and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > + > Another reason edit and continue may fail is if you see a message that says "The Require source files to exactly match the original version setting under Debug->Options->General needs to be enabled..." To fix this, from the main menu select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. > Understanding the Run and Debug shortcuts > - > - **F5** (or **Debug** > **Start Debugging**) starts a debugging session if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If you have something like a "Hello World" program to run, use **Ctrl+F5** or set a breakpoint before you enter **F5** to keep the window open. - > - **Ctrl+F5** (or **Debug** > **Start Without Debugging**) runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. - > - **F10** (known as **Step Over**) lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. - > - **F11** (known as **Step Into**) works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. + > - **F5**, or **Debug** > **Start Debugging**, starts a debugging session, if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If your program outputs to the console, use **Ctrl+F5** or set a breakpoint before you press **F5** to keep the window open. + > - **Ctrl+F5**, or **Debug** > **Start Without Debugging**, runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. + > - **F10**, known as **Step Over**, lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. + > - **F11**, known as **Step Into**, works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. ### Close the app -- If it's still running, close the console window for the calculator app. +- If it's still running, close the console window to stop the calculator app. [!INCLUDE[includes/git-source-control.md](includes/git-source-control.md)] ## The finished app -Congratulations! You've completed the code for the calculator app, built and debugged it, and added it to a repo, all in Visual Studio. +Congratulations! You completed the code for the calculator app, built and debugged it, and added it to a repo, all in Visual Studio. ## Next steps @@ -383,31 +418,30 @@ Congratulations! You've completed the code for the calculator app, built and deb ::: moniker range=" **New** > **Project**. The **New Project** window opens. +Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize one or more projects. A project contains all the options, configurations, and rules used to build an app. It also manages the relationship between all the project's files and any external files. To create your app, first, create a new project and solution. -2. On the left sidebar, make sure **Visual C++** is selected. In the center, choose **Windows Console Application**. +1. On the menubar in Visual Studio, select **File** > **New** > **Project**. The **New Project** window opens. +2. On the left sidebar, ensure that **Visual C++** is selected. In the center, select **Console App**. +3. In the **Name** textbox at the bottom, name the new project *CalculatorTutorial*, then select **OK**. -3. In the **Name** edit box at the bottom, name the new project *CalculatorTutorial*, then choose **OK**. + :::image type="complex" source="./media/calc-vs2017-new-project-dialog.png" alt-text="Screenshot of the New Project dialog."::: + On the left, Other Languages > Visual C++ is selected. In the center, the Console App project type is selected. The Name text box contains CalculatorTutorial. + :::image-end::: - ![The New Project dialog.](./media/calculator-new-project-dialog.png "The New Project dialog") - - An empty C++ Windows console application gets created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: + An empty C++ Windows console application 'Hello World' app is created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include int main() @@ -431,31 +465,34 @@ Visual Studio uses *projects* to organize the code for an app, and *solutions* t The template for a new windows console application creates a simple C++ "Hello World" app. At this point, you can see how Visual Studio builds and runs the apps you create right from the IDE. -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, select **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. + + :::image type="content" source="./media/calculator-initial-build-output.png" alt-text="Screenshot of the Visual Studio Output window showing that the build was successful."::: + +1. To run the code, on the menu bar, select **Debug**, **Start without debugging** (Ctrl+F5). - ![Screenshot Visual Studio with the Output window showing the result of the build process.](./media/calculator-initial-build-output.png "Build the project") + :::image type="content" source="./media/calculator-hello-world-console.png" alt-text="Screenshot of the Visual Studio Debug Console showing the output: Hello World!"::: -1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. + A console window opens and your app runs within it. - ![Screenshot of the Microsoft Visual Studio Debug Console showing the code ran successfully.](./media/calculator-hello-world-console.png "Start the project") + When you start a console app in Visual Studio, it runs your code, then prints `Press any key to close this window . . .` to give you a chance to see the output. - A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to continue . . ." to give you a chance to see the output. Congratulations! You've created your first "Hello, world!" console app in Visual Studio! + Congratulations! You created your first "Hello, world!" console app in Visual Studio! 1. Press a key to dismiss the console window and return to Visual Studio. -You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we'll show you how to debug it if it doesn't. +You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we show you how to debug it if it doesn't. ## Edit the code -Now let's turn the code in this template into a calculator app. +Now let's turn the code in this template to be a calculator app. -1. In the *CalculatorTutorial.cpp* file, edit the code to match this example: +1. Replace the contents of the *`CalculatorTutorial.cpp`* file with the following code so that it matches this example: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include using namespace std; @@ -463,8 +500,7 @@ Now let's turn the code in this template into a calculator app. int main() { cout << "Calculator Console Application" << endl << endl; - cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" - << endl; + cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" << endl; return 0; } @@ -481,38 +517,47 @@ Now let's turn the code in this template into a calculator app. > Understanding the code: > - > - The `#include` statements allow you to reference code located in other files. Sometimes, you may see a filename surrounded by angle brackets (**\<\>**); other times, it's surrounded by quotes (**" "**). In general, angle brackets are used when referencing the C++ Standard Library, while quotes are used for other files. - > - The `#include "pch.h"` (or in Visual Studio 2017 and earlier, `#include "stdafx.h"`) line references something known as a precompiled header. These are often used by professional programmers to improve compilation times, but they are beyond the scope of this tutorial. - > - The `using namespace std;` line tells the compiler to expect stuff from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with a `std::`, to denote its scope. For instance, without that line, each reference to `cout` would have to be written as `std::cout`. The **`using`** statement is added to make the code look more clean. - > - The `cout` keyword is used to print to standard output in C++. The **\<\<** operator tells the compiler to send whatever is to the right of it to the standard output. - > - The **endl** keyword is like the Enter key; it ends the line and moves the cursor to the next line. It is a better practice to put a `\n` inside the string (contained by "") to do the same thing, as `endl` always flushes the buffer and can hurt the performance of the program, but since this is a very small app, `endl` is used instead for better readability. + > - The `#include` statement brings in code in other files. Sometimes, you may see a filename surrounded by angle brackets like ``. The angle brackets instruct the compiler to look for the `iostream` header file first in the standard system directories, and if not found, to look in directories specific to the project. Other times, you may see a filename surrounded by quotes like `"someHeader.h"`. The quotes instruct the compiler to skip looking in the standard system directories and instead only look in directories specific to the project. + > - The `using namespace std;` tells the compiler to expect code from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with `std::` to denote its scope. For instance, without that line, each reference to `cout` would be written as `std::cout`. The **`using`** statement is added to make it more convenient to access code in another namespace. + > - The `cout` keyword prints to standard output in C++. The `<<` operator tells the compiler to send whatever is to the right of it to the standard output. + > - The `endl` keyword is like the Enter key; it ends the line and moves the cursor to the next line. It's a better practice to put a `\n` inside the string (contained by `""`) to do the same thing because `endl` always flushes the buffer and can hurt the performance of the program. But since this is a very small app, `endl` is used instead. > - All C++ statements must end with semicolons and all C++ applications must contain a `main()` function. This function is what the program runs at the start. All code must be accessible from `main()` in order to be used. -1. To save the file, enter **Ctrl+S**, or choose the **Save** icon near the top of the IDE, the floppy disk icon in the toolbar under the menu bar. +1. To save the file, press **Ctrl+S**, or select the floppy disk icon in the toolbar under the menu bar. -1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and choose **Start Without Debugging**. If you get a pop-up that says **This project is out of date**, you may select **Do not show this dialog again**, and then choose **Yes** to build your application. You should see a console window appear that displays the text specified in the code. +1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and select **Start Without Debugging**. If you get a pop-up that says **This project is out of date**, you may select **Do not show this dialog again**, and then select **Yes** to build your application. You should see a console window appear that looks like this: - ![Build and start your application.](./media/calculator-first-launch.gif "Build and start your application") + :::image type="complex" source="./media/calculator-first-launch.png" alt-text="Screenshot of the calculator app running in a console window."::: + The console app shows the output which is: Calculator Console Application. Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The process exited with code 0 and there's a message that to automatically close the console when debugging stops, enable Tools > Options > Debugging > Automatically close the console when debugging stops. Lastly, there's a message to press any key to close this window. + :::image-end::: 1. Close the console window when you're done. ## Add code to do some math -It's time to add some math logic. +A class is like a blueprint for an object that does something. In this case, we define a calculator class to contain the math logic. + +### Add a Calculator class -### To add a Calculator class +1. Go to the **Project** menu and select **Add Class**. In the **Class Name** edit box, enter *Calculator*. Select **OK**. -1. Go to the **Project** menu and choose **Add Class**. In the **Class Name** edit box, enter *Calculator*. Choose **OK**. Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. + :::image type="complex" source="./media/calc-vs2017-create-calculator-class.png" alt-text="Screenshot of the Visual Studio Add Class dialog box."::: + The class name field contains the text calculator. The .h file field contains Calculator.h. The .cpp file field contains Calculator.cpp. The base class field is empty. The options for inline, and Managed are unchecked. + :::image-end::: - ![Short video showing the user opening the Add Class dialog box, typing Calculator in the Class Name field, and selecting O K.](./media/calculator-create-class.gif "Create the Calculator class") + A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. - A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. The **Add Class** wizard you used above created .h and .cpp files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, you can open it from the menu bar: choose **View** > **Solution Explorer**. + Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. - ![Screenshot of the Solution Explorer window displaying the Calculator Tutorial project.](./media/calculator-solution-explorer.png "Solution Explorer") + The **Add Class** wizard creates `.h` and `.cpp` files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the **Solution Explorer** isn't visible, open it from the menu bar: select **View** > **Solution Explorer**. - You should now have three tabs open in the editor: *CalculatorTutorial.cpp*, *Calculator.h*, and *Calculator.cpp*. If you accidentally close one of them, you can reopen it by double-clicking it in the **Solution Explorer** window. + :::image type="complex" source="./media/calculator-solution-explorer.png" alt-text="Screenshot of the Visual Studio Solution Explorer window."::: + The calculator tutorial project has a header files node containing Calculator.h, stdafx.h, and targetver.h. A Source Files node contains Calculator.cpp, CalculatorTutorial.cpp, and stdafx.cpp. Nodes for references, external dependencies, and resource files are visible but closed. + :::image-end::: -1. In **Calculator.h**, remove the `Calculator();` and `~Calculator();` lines that were generated, since you won't need them here. Next, add the following line of code so the file now looks like this: + You can open a file by double-clicking it in the **Solution Explorer** window. Double-click `Calculator.h` to open it. + +1. Replace the contents of **`Calculator.h`** with the following code so that the file now looks like this: ```cpp #pragma once @@ -525,21 +570,19 @@ It's time to add some math logic. > Understanding the code > - > - The line you added declares a new function called `Calculate`, which we'll use to run math operations for addition, subtraction, multiplication, and division. - > - C++ code is organized into *header* (.h) files and *source* (.cpp) files. Several other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where 'filename.h' is the name of the file that declares the variables or functions you want to use. - > - The two lines you deleted declared a *constructor* and *destructor* for the class. For a simple class like this one, the compiler creates them for you, and their uses are beyond the scope of this tutorial. + > - This code declares a new function called `Calculate`, which handles math operations for addition, subtraction, multiplication, and division. + > - C++ code is organized into *header* (`.h`) files and *source* (`.cpp`) files. Some other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where `filename.h` is the name of the file that declares the variables or functions you want to use. > - It's good practice to organize your code into different files based on what it does, so it's easy to find the code you need later. In our case, we define the `Calculator` class separately from the file containing the `main()` function, but we plan to reference the `Calculator` class in `main()`. -1. You'll see a green squiggle appear under `Calculate`. It's because we haven't defined the `Calculate` function in the .cpp file. Hover over the word, click the lightbulb that pops up, and choose **Create definition of 'Calculate' in Calculator.cpp**. A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *Calculator.cpp*. +1. A green squiggle appears under `Calculate` because although the `Calculate` function is *declared*, it isn't *defined*. Hover over `Calculate`, click the down arrow on the light bulb, and select **Create definition of 'Calculate' in `Calculator.cpp`**. A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *`Calculator.cpp`*. - ![Short video showing the user selecting the Create definition of Calculate in Calculator C P P option.](./media/calculator-create-definition.gif "Create definition of Calculate") + :::image type="content" source="./media/calc-vs2017-create-definition.png" alt-text="Video showing using the light bulb dropdown to select Create definition of Calculate in Calculator.cpp."::: - Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up. + Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up and choose **Yes** to save the changes. -1. Switch to the *Calculator.cpp* file in the editor window. Remove the `Calculator()` and `~Calculator()` sections (as you did in the .h file) and add the following code to `Calculate()`: +1. Switch to the *`Calculator.cpp`* file in the editor window. Replace the contents of the file with the following code: ```cpp - #include "pch.h" #include "Calculator.h" double Calculator::Calculate(double x, char oper, double y) @@ -562,22 +605,21 @@ It's time to add some math logic. > Understanding the code > - > - The function `Calculate` consumes a number, an operator, and a second number, then performs the requested operation on the numbers. - > - The switch statement checks which operator was provided, and only executes the case corresponding to that operation. The default: case is a fallback in case the user types an operator that isn't accepted, so the program doesn't break. In general, it's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. - > - The **`double`** keyword denotes a type of number that supports decimals. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return such a number due to the **`double`** at the very start of the code (this denotes the function's return type), which is why we return 0.0 even in the default case. - > - The .h file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The .cpp file has all the implementation details of the function. + > - The function `Calculate` takes a number, an operator, and a second number. Then it performs the requested operation on the two numbers. + > - The `switch` statement checks which operator was provided, and executes the case corresponding to that operation. The `default:` case is a fallback in case the user types an operator that isn't handled by any of the preceding `case` statements. It's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. + > - The **`double`** keyword denotes a type of number that supports decimals. This type of number is called a floating-point number, and `double` means a floating point number that has extra precision. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return a double-precision floating point number due to the **`double`** at the start of the code (this denotes the function's return type), which is why we return 0.0 in the default case. + > - The `.h` file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The `.cpp` file has all the implementation details of the function. -If you build and run the code again at this point, it will still exit after asking which operation to perform. Next, you'll modify the `main` function to do some calculations. +If you build and run the code again at this point, it still exits after asking which operation to perform. Next, modify the `main` function to do some calculations. -### To call the Calculator class member functions +### Call the Calculator class member functions -1. Now let's update the `main` function in *CalculatorTutorial.cpp*: +1. Update the `main` function in *`CalculatorTutorial.cpp`* as follows: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include #include "Calculator.h" @@ -591,8 +633,7 @@ If you build and run the code again at this point, it will still exit after aski char oper = '+'; cout << "Calculator Console Application" << endl << endl; - cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" - << endl; + cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" << endl; Calculator c; while (true) @@ -608,87 +649,100 @@ If you build and run the code again at this point, it will still exit after aski > Understanding the code > - > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so a `#include` statement is needed. - > - Some initial variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It is always good practice to give them some initial values to avoid undefined behavior, which is what is done here. - > - The `Calculator c;` line declares an object named 'c' as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. - > - The `while (true)` statement is a loop. The code inside the loop continues to execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. - > - The `cin` keyword is used to accept input from the user. This input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order, assuming the user input matches the required specification. You can modify this line to accept different types of input, for instance, more than two numbers, though the `Calculate()` function would also need to be updated to handle this. - > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values. The function then returns a number that gets stored in `result`. - > - Finally, `result` is printed to the console, so the user sees the result of the calculation. + > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so an `#include` statement is needed to make that code visible to our `main()` function. + > - The variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It's always good practice to give them some initial values to avoid undefined behavior, which is what is done here. + > - The `Calculator c;` line declares an object named `c` as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. + > - The `while (true)` statement is a loop. The code inside the loop execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. + > - The `cin` keyword accepts input from the user. The input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order. + > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values and the requested operation. The function then returns a number that is stored in `result`. + > - Finally, `result` is printed to the console and the user sees the result of the calculation. ### Build and test the code again -Now it's time to test the program again to make sure everything works properly. +Test the program again to make sure everything works properly. 1. Press **Ctrl+F5** to rebuild and start the app. +1. Enter `5+5`, and press **Enter**. Verify that the result is 10. -1. Enter `5 + 5`, and press **Enter**. Verify that the result is 10. - - ![Screenshot of the Microsoft Visual Studio Debug Console showing the correct result of 5 + 5.](./media/calculator-five-plus-five.png "The result of 5 + 5") + :::image type="content" source="./media/calculator-five-plus-five.png" alt-text="Screenshot of a command window running the Calculator app. It shows that the result of 5 + 5 is 10."::: +1. Stop the program by closing the console window. ## Debug the app -Since the user is free to type anything into the console window, let's make sure the calculator handles some input as expected. Instead of running the program, let's debug it instead, so we can inspect what it's doing in detail, step-by-step. +Since the user is free to type anything into the console window, let's make sure the calculator handles unexpected input. Instead of running the program, let's debug it instead, so we can inspect what it's doing step-by-step. -### To run the app in the debugger +### Run the app in the debugger -1. Set a breakpoint on the `result = c.Calculate(x, oper, y);` line, just after the user was asked for input. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window. A red dot appears. +1. In `CalcuatorTutorial.cpp`, set a breakpoint on the `result = c.Calculate(x, oper, y);` line. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window so that a red dot appears. - ![Short video of Visual Studios showing the user creating the red dot that represents a breakpoint.](./media/calculator-set-breakpoint.gif "Set a breakpoint") + :::image type="content" source="./media/calc-vs2017-set-breakpoint.png" alt-text="Screenshot of the user setting a breakpoint on line 23: result = c.Calculate(x, oper, y);."::: - Now when we debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. + Now when you debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. -1. Right-click the red dot that represents the breakpoint, and choose **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Choose the **Close** button when you're done. The condition is saved automatically. +1. Right-click the red dot that represents the breakpoint, and select **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Select the **Close** button when you're done to save the breakpoint condition. - ![Short video of Visual Studio 2019 showing the user opening the Breakpoint Settings section and setting a conditional breakpoint.](./media/calculator-conditional-breakpoint.gif "Set a conditional breakpoint") + :::image type="complex" source="./media/calc-vs2017-conditional-breakpoint.png" alt-text="Screenshot showing the conditional breakpoint window."::: + The breakpoint is on the line: result = c dot Calculate ( x, oper, y). 'Conditions...' The Condition option is checked. The Conditions dropdown is set to "Conditional Expression". The condition dropdown is set to "Is true". The condition is set to y == 0 && oper == '/'. + :::image-end::: - Now we pause execution at the breakpoint specifically if a division by 0 is attempted. + Execution will pause at the breakpoint if a division by 0 is attempted. -1. To debug the program, press **F5**, or choose the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers; `cin` is smart enough to parse the input appropriately. +1. To debug the program, press **F5**, or select the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers; `cin` is smart enough to parse the input appropriately. - ![Short video of Visual Studios showing that the program paused at the conditional breakpoint.](./media/calculator-debug-conditional.gif "Pause at the conditional breakpoint") + :::image type="complex" source="./media/calc-vs2017-debug-breakpoint.png" alt-text="Video showing the program execution paused at the conditional breakpoint."::: + The user enters 5 - 0. The app outputs: Result is 5. The user then enters 10/0 and because the condition for the conditional breakpoint is met, execution stops on the line: result = c.Calculate(x, oper, y); + :::image-end::: ### Useful windows in the debugger -Whenever you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. +When you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. If you don't see the **Autos** window, from the main menu select **Debug** > **Windows** > **Autos**. - ![The Autos window.](./media/calculator-autos.png "The Autos window") + :::image type="complex" source="./media/calculator-autos.png" alt-text="Screenshot of the Visual Studio debugger Autos window."::: + The value of oper is 47 '/', result is 5, x is 10, and y is 0. + :::image-end::: -To see all of the variables from that function, switch to the **Locals** window. You can actually modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we'll leave them alone. +To see all of the variables from that function, switch to the **Locals** window. Because this is a small function, the Autos and Locals window show the same variables. But you can modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we leave them alone. Open the **Locals** window by selecting **Locals** at the bottom of the **Autos** window, or by selecting from the main menu **Debug** > **Windows** > **Locals**. - ![Screenshot of the Locals window.](./media/calculator-locals.png "The Locals window") + :::image type="complex" source="./media/calculator-locals.png" alt-text="Screenshot of the Locals window in Visual Studio, displaying the current values of local variables while debugging."::: + The value of oper is 47 '/', result is 0, x is 10, and y is 0. + :::image-end::: -You can also just hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. +You can also hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. - ![Short video showing the tooltip that appears displaying the value of the variable.](./media/calculator-hover-tooltip.gif "Hover to view current variable values") + :::image type="content" source="./media/calc-vs2017-hover-tooltip.png" alt-text="Video demonstrating a tooltip that appears while hovering over the variable y. It displays y's current value, which is 0."::: -### To continue debugging +### Continue debugging -1. The yellow line on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. You'll find yourself in the body of the `Calculate` function. Be careful with **Step Into**; if you do it too much, you may waste a lot of time. It goes into any code you use on the line you are on, including standard library functions. +1. The yellow arrow on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function, which takes you into the body of the `Calculate` function. Be careful with **Step Into** because it steps into any functions on the line you're on, including standard library functions. It's fine to step into the standard library, but you may be more interested in focusing on your code instead of library code. 1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general you should use **Step Over** instead of **Step Into**, unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). 1. Continue using **F10** to **Step Over** each line until you get back to the `main()` function in the other file, and stop on the `cout` line. - ![Step out of Calculate and check result.](./media/calculator-undefined-zero.gif "Step out of Calculate and check result") + The program is doing what's expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. Its value is `inf`, which doesn't look right. + + :::image type="complex" source="./media/calc-vs2017-debug-inf.png" alt-text="Screenshot of debugging the calculator."::: + The current statement in the debugger is cout << "Result is: " << result << endl; In the autos window, result is inf. + :::image-end::: - It looks like the program is doing what is expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. You'll see its value is listed as "inf", which doesn't look right, so let's fix it. The `cout` line just outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: + Let's fix it. The `cout` line outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: - ![Screenshot of the Microsoft Visual Studio Debug Console showing the result of dividing by zero.](./media/calculator-divide-by-zero-fail.png "The result of divide by zero") + :::image type="complex" source="./media/calc-divide-by-zero-fail.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the result of a division by zero operation."::: + The app outputs: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5-0. The app output: Result is: 5. The user entered 10/0. The app output: Result is: inf + :::image-end::: - This result happens because division by zero is undefined, so the program doesn't have a numerical answer to the requested operation. + This result is because division by zero is undefined, so the program doesn't have a numerical answer for the requested operation. -### To fix the "divide by zero" error +### Fix the "divide by zero" error -Let's handle division by zero more gracefully, so a user can understand the problem. +Let's handle division by zero more gracefully so that it's easier for the user to understand the problem. -1. Make the following changes in *CalculatorTutorial.cpp*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**): +1. Make the following changes in *`CalculatorTutorial.cpp`*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**). The change is to add an `if` statement following `cin >> x >> oper >> y;` to check for division by zero and output a message to the user if it happens. Otherwise, the result is printed: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include #include "Calculator.h" @@ -707,7 +761,7 @@ Let's handle division by zero more gracefully, so a user can understand the prob Calculator c; while (true) { - cin >> x >> oper >> y; + cin >> x >> oper >> y; if (oper == '/' && y == 0) { cout << "Division by 0 exception" << endl; @@ -724,25 +778,29 @@ Let's handle division by zero more gracefully, so a user can understand the prob } ``` -1. Now press **F5** once. Program execution continues all the way until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. +1. Press **F5** once. Program execution continues until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. - ![Short video of the Microsoft Visual Studio Debug Console showing the final result after changes.](./media/calculator-final-verification.gif "The final result after changes") + :::image type="content" source="./media/calc-final-verification.png" alt-text="Video of the Debug Console showing the final result after code changes. 10 / 0 is entered and the program displays 'Division by 0 exception'."::: > [!Note] - > When you edit code while in debugging mode, there is a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you'll need to step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > When you edit code while in debugging mode, there's a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > + > Another reason edit and continue may fail is that you need to go to the main menu and select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. > Understanding the Run and Debug shortcuts > - > - **F5** (or **Debug** > **Start Debugging**) starts a debugging session if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If you have something like a "Hello World" program to run, use **Ctrl+F5** or set a breakpoint before you enter **F5** to keep the window open. - > - **Ctrl+F5** (or **Debug** > **Start Without Debugging**) runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. - > - **F10** (known as **Step Over**) lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. - > - **F11** (known as **Step Into**) works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. + > - **F5**, or **Debug** > **Start Debugging**, starts a debugging session, if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If your program outputs to the console, use **Ctrl+F5** or set a breakpoint before you press **F5** to keep the window open. + > - **Ctrl+F5**, or **Debug** > **Start Without Debugging**, runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. + > - **F10**, known as **Step Over**, lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. + > - **F11**, known as **Step Into**, works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. ### Close the app -- If it's still running, close the console window for the calculator app. +- If it's still running, close the console window to stop the calculator app. + +## The finished app -Congratulations! You've completed the code for the calculator app, and built and debugged it in Visual Studio. +Congratulations! You completed the code for the calculator app, and built and debugged it in Visual Studio. ## Next steps diff --git a/docs/ide/add-interface-definition-library-method-wizard.md b/docs/ide/add-interface-definition-library-method-wizard.md new file mode 100644 index 0000000000..6f4430b635 --- /dev/null +++ b/docs/ide/add-interface-definition-library-method-wizard.md @@ -0,0 +1,117 @@ +--- +title: "Add an IDL method" +description: "Learn more about: Use a Microsoft Visual Studio wizard to add a method to an interface definition language (IDL) interface in your project" +ms.date: "04/13/2022" +f1_keywords: ["vc.codewiz.method.overview", "vc.codewiz.method.idlattrib"] +helpviewer_keywords: ["add IDL method wizard [C++]", "IDL methods [C++], adding", "methods [C++], adding using wizards", "IDL attributes, add an IDL method wizard"] +ms.custom: devdivchpfy22 +--- + +# Add an IDL method + +The **Add IDL Method** wizard adds a method to an Interface Definition Library (IDL) interface, such as in an ATL project that contains an IDL file. This wizard isn't available in projects that support MFC. + +This wizard differs from the [**Add method**](adding-a-method-visual-cpp.md) wizard and the [**Add IDL MFC method**](../mfc/reference/add-idl-mfc-method-wizard.md) wizard in the following ways: + +- The **Add method** wizard adds a method to an interface in your project and can update the class associated with the interface. +- The **Add IDL MFC method** wizard is specific to MFC, ActiveX, or ATL projects that support MFC. + +## Add a method to your IDL interface + +1. On the **View** menu, select **Class View**. + +1. In the **Class View** pane, expand the project node to display the IDL interface (`.idl` file) to which you want to add the method. + +1. Right-click the name of the interface. + +1. On the shortcut menu, select **Add** > **Add Method**. + +1. In the **Add IDL Method** wizard, provide the information to create the method. + +1. Select **OK** to add the method. + +### User Interface element list + +The following section describes the wizard interface that you'll use to add a method: + +:::image type="content" source= "media/add-interface-definition-library-method-wizard.png" alt-text="Screenshot of adding a method using the wizard. Shows two parameters: [ in ] int i and [ in ] float f. Return type is HRESULT. Infer in out parameter values from type is selected."::: + +- **Method name** + + Provide a name for the method. + +- **Return type** + + The data type returned by the method. The standard way to return error codes from methods defined in an interface is with an `HRESULT`. + + The following table describes the different kinds of interfaces that you can add a method to, and the allowed return type. For dual and custom interfaces, the return type must be `HRESULT` and the wizard won't allow you to change it. + + |Interface kind|Return type| + |--------------------|-----------------| + |[Dual interface](/windows/win32/winauto/dual-interfaces--iaccessible-and-idispatch)|`HRESULT`. Unchangeable.| + |[Custom interface](/windows/win32/winauto/custom-user-interface-elements)|`HRESULT`. Unchangeable.| + |Local custom interface|Provide your own return type or select it from the drop-down list.| + |[Dispinterface](/windows/win32/midl/dispinterface)|Provide your own return type or select it from the drop-down list.| + +- **Parameters** + + Displays the method's parameters, modifiers, and types. + +- **+** + + Add a parameter. In **Parameters**, type the parameter type, name, and any modifiers. For example, `[in] int i`, and choose **OK**. + +- **x** + + Removes the selected parameter from the **Parameters** list. + +- **Infer in/out parameters values from types** + + Inserts the `[in]` or `[out]` attribute based on the parameter's type. + +- **Set the last parameter as the return value (retval)** + + The last parameter will be treated as the method's return value. + +- **Attributes** + + The following attributes are also described in the [MIDL Reference](/windows/win32/midl/midl-language-reference). + + - `id` + + Sets the numeric ID that identifies the method. For more information, see [`id`](/windows/win32/Midl/id). + + - `call_as` + + Specifies the name of the remote method to map to this local method. For more information, see [`call_as`](/windows/win32/Midl/call-as). + + - `helpcontext` + + Specifies a context ID that lets the user view information about this method in the Help file. For more information, see [`helpcontext`](/windows/win32/Midl/helpcontext). + + - `helpstring` + + Specifies the character string used to describe the element to which it applies. For more information, see [`helpstring`](/windows/win32/Midl/helpstring). + +- **Additional attributes** + + - `hidden` + + Indicates that the item exists but shouldn't be displayed in a user-oriented browser. For more information, see [`hidden`](/windows/win32/Midl/hidden). + + - `local` + + Specifies that an interface or function isn't remote. For more information, see [`local`](/windows/win32/Midl/local). + + - `restricted` + + Specifies that a library, or member of a module, interface, or dispinterface can't be called arbitrarily. For more information, see [`restricted`](/windows/win32/Midl/restricted). + + - `source` + + Indicates that a member of a [`coclass`](/windows/win32/Midl/coclass), property, or method is a source of events. For a member of a `coclass`, this attribute means that the member is called rather than implemented. For more information, see [`source`](/windows/win32/Midl/source). + +## See also + +[Add a method wizard](adding-a-method-visual-cpp.md)\ +[Add an IDL MFC method wizard](../mfc/reference/add-idl-mfc-method-wizard.md) diff --git a/docs/ide/add-interface-definition-library-property-wizard.md b/docs/ide/add-interface-definition-library-property-wizard.md new file mode 100644 index 0000000000..c12abece36 --- /dev/null +++ b/docs/ide/add-interface-definition-library-property-wizard.md @@ -0,0 +1,125 @@ +--- +description: "Learn more about: Use a Microsoft Visual Studio wizard to add an IDL property to an IDL interface in your project" +title: "Add an IDL property" +ms.date: 04/14/2022 +f1_keywords: ["vc.codewiz.prop.overview", "vc.codewiz.prop.idlattributes"] +helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "IDL attributes", "stock properties, about stock properties", "stock properties"] +ms.custom: devdivchpfy22 +--- +# Add an IDL property + +The **Add IDL Property** wizard adds a property to an interface defined in an Interface Definition Library (IDL), such as in an ATL project that contains an `.idl` file. This wizard isn't available in projects that support MFC. + +This wizard differs from the [Add Property](adding-a-property-visual-cpp.md) wizard and [Add IDL MFC Property](../mfc/reference/add-interface-definition-library-mfc-property-wizard.md) wizard in the following ways: +- The **Add Property** wizard adds a property to an interface in your project. +- The **Add IDL MFC Property** wizard is specific to MFC, ActiveX, or ATL projects that support MFC. + +**To add an IDL property** + +1. On the **View** menu, select **Class View**. + +1. In [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the name of the interface to which you want to add the property. + + > [!NOTE] + > You can also add properties to dispinterfaces, which, unless the project is attributed, are nested within the library node. + +1. Right-click the name of the interface. + +1. From the shortcut menu, select **Add** > **Add Property**. + +1. In the **Add IDL Property** wizard, provide the information to create the property. + +1. Select **OK** to add the property. + +The `Get` and `Put` methods of the property are displayed as two icons in **Class View** under the interface where it's defined. Double-click either icon to view the property declaration in the `.idl` file. + +For ATL interfaces, the `Get` and `Put` functions are added to the `.cpp` and `.h` files. + +## Add an IDL property wizard + +The following section describes the UI that you'll use to add an IDL property: + +:::image type="content" source="media/add-interface-definition-library-property-wizard.png" alt-text="Screenshot of Add IDL Property with two parameters: [ in ] int i and [ in ] char c. Return type is HRESULT. Property type is float."::: + +- **Property name** + + Sets the name of the property. + +- **Property type** + + The data type of the property. + +- **Return type** + + For ATL interfaces, sets the return type for the property. + For dual interfaces, `HRESULT` is always the return type, and select option is unavailable. + For custom interfaces, you can select a return type from the list. `HRESULT` is still recommended, as it provides a standard way to return errors. + +- **Get function** + + For ATL interfaces, creates the `Get` method for retrieving the property value. Select **Get**, **Put**, or both. + +- **Put function** + + For ATL interfaces, creates the `Put` method for setting the property value. Select **Get**, **Put**, or both. If you select **Put function**, you can choose from the following two ways to implement the method: + + |Option|Description| + |------------|-----------------| + |**`propput`**|The [`PropPut`](../windows/attributes/propput.md) function returns a copy of the object. **propput** is the default and the most common way to make the property writable.| + |**`propputref`**|The [`PropPutRef`](../windows/attributes/propputref.md) function returns a reference to the object, rather than returning the copy of the object itself. Consider using **`propputref`** option for objects, such as large structs or arrays, that may have initialization overhead.| + +- **Parameters** + + Displays the list of parameters added to the property. Each item in the list consists of the parameter name, parameter type, and attributes. + + `in` indicates that the parameter is passed from the calling procedure to the called procedure. + `out` indicates that the pointer parameter is returned from the called procedure to the calling procedure (from the server to the client). + +- **+** + + Add a parameter. In **Parameters**, type the parameter type and name. For example, `int x`, and select **OK**. + +- **x** + + Removes the selected parameter from **Parameters**. + +- **Pencil icon** + + Edit the selected parameter. + +- **Attributes** + +1. `helpcontext` + + Specifies a context ID that lets the user view information about this property in the Help file. For more information, see [`helpcontext`](/windows/win32/Midl/helpcontext). + +1. `helpstring` + + Specifies a character string that's used to describe the element to which it applies. By default, it's set to **`property`** *Property name*. For more information, see [`helpstring`](/windows/win32/Midl/helpstring). + +1. `id` + + Sets the numerical identifier that identifies the property. This option isn't available for properties of custom interfaces. For more information, see [`id`](/windows/win32/Midl/id). + +- **Additional attributes** + +Keywords in the Microsoft Interface Definition Language (MIDL) are described in detail in the [MIDL language reference](/windows/win32/midl/midl-language-reference). + + |Option|Description| + |------------|-----------------| + |`bindable`|Indicates that the property supports data binding. For more information, see [`bindable`](/windows/win32/Midl/bindable).| + |`defaultbind`|Indicates that this single, bindable property best represents the object. For more information, see [defaultbind](/windows/win32/Midl/defaultbind).| + |`defaultcollelem`|Indicates that the property is an accessor function for an element of the default collection. For more information, see [`defaultcollelem`](/windows/win32/Midl/defaultcollelem).| + |`displaybind`|Indicates that this property should be displayed to the user as bindable. For more information, see [`displaybind`](/windows/win32/Midl/displaybind).| + |`hidden`|Indicates that the property exists but shouldn't be displayed in a user-oriented browser. For more information, see [`hidden`](/windows/win32/Midl/hidden).| + |`immediatebind`|Indicates that the database will be notified immediately of all changes to this property of a data-bound object. For more information, see [`immediatebind`](/windows/win32/Midl/immediatebind).| + |`local`|Specifies to the MIDL compiler that the property isn't remote. For more information, see [`local`](/windows/win32/Midl/local).| + |`nonbrowsable`|Tags an interface or dispinterface member that shouldn't be displayed in a properties browser. For more information, see [`nonbrowsable`](/windows/win32/Midl/nonbrowsable).| + |`requestedit`|Indicates that the property supports the `OnRequestEdit` notification. For more information, see [`requestedit`](/windows/win32/Midl/requestedit).| + |`restricted`|Specifies that the property can't be called arbitrarily. For more information, see [`restricted`](/windows/win32/Midl/restricted).| + |`source`|Indicates that a member of the property is a source of events. For more information, see [`source`](/windows/win32/Midl/source).| + +## **See also** + +[Add Property](adding-a-property-visual-cpp.md)\ +[Add IDL MFC Property](../mfc/reference/add-interface-definition-library-mfc-property-wizard.md) diff --git a/docs/ide/adding-a-class-from-an-activex-control-visual-cpp.md b/docs/ide/adding-a-class-from-an-activex-control-visual-cpp.md index e1b843541f..5fb6833df0 100644 --- a/docs/ide/adding-a-class-from-an-activex-control-visual-cpp.md +++ b/docs/ide/adding-a-class-from-an-activex-control-visual-cpp.md @@ -1,95 +1,72 @@ --- description: "Learn more about: Add a class from an ActiveX control" title: "Add a class from an ActiveX control" -ms.date: "11/08/2018" +ms.date: 04/28/2023 f1_keywords: ["vc.codewiz.class.axcontrol"] helpviewer_keywords: ["ActiveX controls [C++], adding classes", "classes [C++], creating", "ActiveX Control Wizard", "add class from ActiveX control wizard [C++]"] -ms.assetid: 729fcb37-54b8-44d5-9b4e-50bb16e0eea4 +ms.custom: devdivchpfy22 --- # Add a class from an ActiveX control -Use this wizard to create an MFC class from an interface in an available ActiveX control. You can add an MFC class to an [MFC application](../mfc/reference/creating-an-mfc-application.md), an [MFC DLL](../mfc/reference/creating-an-mfc-dll-project.md), or an [MFC ActiveX control](../mfc/reference/creating-an-mfc-activex-control.md). +Use this wizard to create an MFC class from an interface in an available ActiveX control. For this wizard to be available, you must have Visual Studio 2019 or later, and be in one of the following project types: [MFC application](../mfc/reference/creating-an-mfc-application.md), [MFC DLL](../mfc/reference/creating-an-mfc-dll-project.md), or [MFC ActiveX control](../mfc/reference/creating-an-mfc-activex-control.md). -> [!WARNING] -> In Visual Studio 2017 version 15.9, Microsoft deprecated this code wizard, and we will remove it in a future version of Visual Studio. This wizard is rarely used. General support for ATL and MFC isn't impacted by the removal of this wizard. If you would like to share your feedback about this deprecation, complete [this survey](https://www.surveymonkey.com/r/QDWKKCN). Your feedback matters to us. - > [!NOTE] > You don't need to create your MFC project with Automation enabled to add a class from an ActiveX control. -An ActiveX control is a reusable software component based on the Component Object Model (COM) that supports a wide variety of OLE functionality. It can be customized to fit many software needs. You may use ActiveX controls in ordinary ActiveX control containers or on the Internet in World Wide Web pages. +An ActiveX control is a reusable software component based on the Component Object Model (COM) that supports a wide variety of OLE functionality. You may use ActiveX controls in ordinary ActiveX control containers. **To add an MFC class from an ActiveX control:** 1. In either **Solution Explorer** or [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the name of the project to which you want to add the ActiveX control class. -1. From the shortcut menu, choose **Add**, and then choose **Add Class**. +1. From the shortcut menu, select **Add**, and then select **New Item**. -1. In the [Add Class](./adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the **Templates** pane, choose **MFC Class from ActiveX Control**, and then choose **Open** to display the [add class from ActiveX control wizard](#add-class-from-activex-control-wizard). +1. In the **Add New Item** dialog box, in the **Templates** pane, choose **MFC Class from ActiveX Control**, and then choose **Add** to display the [add class from ActiveX control wizard](#add-class-from-activex-control-wizard). In the wizard, you can add more than one interface in an ActiveX control. You can also create classes from more than one ActiveX control in a single wizard session. -You can add classes from ActiveX controls registered in your system, or you can add classes from ActiveX controls located in type library files (.tlb, .olb, .dll, .ocx, or .exe) without first registering them in your system. For more information about registering ActiveX controls, see [Registering OLE controls](../mfc/reference/registering-ole-controls.md). +You can add classes from ActiveX controls registered in your system, or you can add classes from ActiveX controls located in type library files (`.tlb`, `.olb`, `.dll`, `.ocx`, or `.exe`) without first registering them in your system. For more information about registering ActiveX controls, see [Registering OLE controls](../mfc/reference/registering-ole-controls.md). The wizard creates an MFC class, derived from [CWnd](../mfc/reference/cwnd-class.md) or from [COleDispatchDriver](../mfc/reference/coledispatchdriver-class.md), for each interface you add from the selected ActiveX control. -## In this section - -- [Add class from ActiveX control wizard](#add-class-from-activex-control-wizard) - ## Add class from ActiveX control wizard Use this wizard to add an MFC class from an available ActiveX control. The wizard creates a class for each interface you add from the selected ActiveX control. -- **Add Class From** +:::image type="content" source="../ide/media/add-mfc-class-from-activex-control.png" alt-text="Add class from ActiveX control wizard"::: + +- **Implement interface from** Specifies the location of the type library from which the class is created. |Option|Description| |------------|-----------------| - |**Registry**|The type library is registered in the system. Registered type libraries are listed in **Available ActiveX controls**.| + |**Registry**|The type library is registered in the system. Registered type libraries are listed in **Available type libraries**.| |**File**|The type library isn't necessarily registered in the system but is stored in a file. Provide the file location in **Location**.| -- **Available ActiveX controls** +- **Available type libraries** - Specifies the ActiveX controls currently registered in the system. Select an ActiveX control from this list to display its interfaces in the **Interfaces** list. See [MFC ActiveX controls: Distributing ActiveX controls](../mfc/mfc-activex-controls-distributing-activex-controls.md) for more information about registering ActiveX controls. + Specifies the ActiveX controls currently registered in the system. Select an ActiveX control from this list to display its interfaces in the **Interfaces** list. For more information about registering ActiveX controls, see [MFC ActiveX controls: Distributing ActiveX controls](../mfc/mfc-activex-controls-distributing-activex-controls.md). - If you select **File** under **Add Class From**, this box is unavailable for change. + If you select **File** under **Implement interface from**, this box is unavailable for change. - **Location** - Specifies the location of the ActiveX control. If you select **File** under **Add Class From**, you can provide the location of the file that has the type library. To browse to the location of the file, select the ellipsis button. + Specifies the location of the ActiveX control. If you select **File** under **Implement interface from**, you can provide the location of the file that has the type library. To browse to the location of the file, select the ellipsis button. - If you select **Registry** under **Add Class From**, this box is unavailable for change. + If you select **Registry** under **Implement interface from**, this box is unavailable for change. -- **Interfaces** +- **Available Interfaces** - Specifies the interfaces in the ActiveX control. The wizard uses the interfaces from the current selection in **Available ActiveX controls**, or it uses the interfaces from the type library file specified in **Location**. + Specifies the interfaces in the ActiveX control. The wizard uses the interfaces from the current selection in **Available type libraries**, or it uses the interfaces from the type library file specified in **Location**. |Transfer button|Description| |---------------------|-----------------| - |**>**|Adds the interface currently selected in the **Interfaces** list. Unavailable if no interface is selected.| - |**>>**|Adds all the interfaces in the ActiveX control. The wizard uses the interfaces from the current selection in **Available ActiveX controls**, or it uses the interfaces from the type library file specified in **Location**.| - |**\<**|Removes the class currently selected in the **Generated classes** list. Unavailable if no class is currently selected in the **Generated classes** list.| - |**\<\<**|Removes all the classes in the **Generated classes** list. Unavailable if the **Generated classes** list is empty.| - -- **Generated classes** - - Specifies the class names to be generated from the interfaces added using the **>** or **>>** button. You can select this box to select a class, and then use the up or down keys to scroll through the list. When you select **Finish**, you may view each generated class name in the **Class** box and each generated file name in the **.h file** box. You can select only one class at a time in this box. - - You can remove a class by selecting it in this list and selecting **<**. You don't need to select a class in the **Generated classes** box to remove all classes. By selecting **<<**, you remove all classes in the **Generated classes** box. - -- **Class** - - Specifies the name of the class selected in the **Generated classes** box that the wizard adds when you select **Finish**. You can edit the name in the **Class** box. - -- **.h file** - - Sets the name of the header file for the new object's class. By default, this name is based on the name you provide in **Generated classes**. Select the ellipsis button to save the file name to the location of your choice, or to append the class declaration to an existing file. If you choose an existing file, the wizard won't save it to the selected location until you select **Finish** in the wizard. - - The wizard doesn't overwrite a file. If you select the name of an existing file and then select **Finish**, the wizard prompts you to indicate whether to append the class declaration to the file contents. Select **Yes** to append the file; select **No** to return to the wizard and specify another file name. - -- **.cpp file** + |**>**|Adds the interface currently selected in the **Available Interfaces** list. Unavailable if no interface is selected.| + |**>>**|Adds all the interfaces in the ActiveX control. The wizard uses the interfaces from the current selection in **Available type libraries**, or it uses the interfaces from the type library file specified in **Location**.| + |**\<**|Removes the class currently selected in the **Implement interfaces** list. Unavailable if no class is currently selected in the **Implement interfaces** list.| + |**\<\<**|Removes all the classes in the **Implement interfaces** list. Unavailable if the **Implement interfaces** list is empty.| - Sets the name of the implementation file for the new object's class. By default, this name is based on the name you provide in **Generated classes**. Select the ellipsis button to save the file name to the location of your choice. The file isn't saved to the selected location until you select **Finish** in the wizard. +- **Implement interfaces** - The wizard doesn't overwrite a file. If you select the name of an existing file and then select **Finish**, the wizard prompts you to indicate whether to append the class implementation to the file contents. Select **Yes** to append the file; select **No** to return to the wizard and specify another file name. + Specifies the class names to be generated from the interfaces added using the **>** or **>>** button. You can select this box to select a class, and then use the up or down arrow keys to scroll through the list. diff --git a/docs/ide/adding-a-class-visual-cpp.md b/docs/ide/adding-a-class-visual-cpp.md index 1d20d849cb..86fbb62e71 100644 --- a/docs/ide/adding-a-class-visual-cpp.md +++ b/docs/ide/adding-a-class-visual-cpp.md @@ -1,18 +1,20 @@ --- description: "Learn more about: Add a class" title: "Add a class" -ms.date: "05/14/2019" +ms.date: 02/14/2022 f1_keywords: ["vc.addclass"] helpviewer_keywords: ["ATL projects, adding classes", "classes [C++], creating", "classes [C++], adding", "Add Class dialog box"] ms.assetid: c34b5f70-4e72-4faa-ba21-e2b05361c4d9 --- # Add a class -To add a class in a Visual Studio C++ project, in **Solution Explorer**, right-click the project, choose **Add**, and then choose **Class**. This opens the [Add Class dialog box](#add-class-dialog-box). +To add a class in a Visual Studio C++ project, in **Solution Explorer**, right-click the project, choose **Add**, and then choose **Class**. This command opens the [Add Class dialog box](#add-class-dialog-box). When you add a class, you must specify a name that is different from classes that already exist in MFC or ATL. If you specify a name that already exists in either library, the IDE shows an error message. -If your project naming convention requires you to use an existing name, then you can just change the case of one or more letters in the name because C++ is case-sensitive. For example, although you cannot name a class `CDocument`, you can name it `cdocument`. +If your project naming convention requires you to use an existing name, then you can just change the case of one or more letters in the name because C++ is case-sensitive. For example, although you can't name a class `CDocument`, you can name it `cdocument`. + +::: moniker range="msvc-140" ## In this section @@ -23,22 +25,26 @@ If your project naming convention requires you to use an existing name, then you In the **Add Class** dialog box, when you expand the **Visual C++** node in the left pane several groupings of installed templates are displayed. The groups include **CLR**, **ATL**, **MFC**, and **C++**. When you select a group, a list of the available templates in that group is displayed in the middle pane. Each template contains the files and source code that are required for a class. -To generate a new class, select a template in the middle pane, type a name for the class in the **Name** box, and select **Add**. This opens the **Add Class Wizard** so that you can specify options for the class. +To generate a new class, select a template in the middle pane, type a name for the class in the **Name** box, and choose **Add**. This button opens the **Add Class Wizard** so that you can specify options for the class. - For more information about how to create MFC classes, see [MFC class](../mfc/reference/adding-an-mfc-class.md). - For more information about how to create ATL classes, see [ATL simple object](../atl/reference/adding-an-atl-simple-object.md). > [!NOTE] -> The template **Add ATL Support to MFC** does not create a class, but instead configures the project to use ATL. For more information, see [ATL support in an MFC project](../mfc/reference/adding-atl-support-to-your-mfc-project.md). +> The template **Add ATL Support to MFC** doesn't create a class, but instead configures the project to use ATL. For more information, see [ATL support in an MFC project](../mfc/reference/adding-atl-support-to-your-mfc-project.md). -To make a C++ class that does not use MFC, ATL, or CLR, use the **C++ Class** template in the **C++** group of installed templates. For more information, see [Add a generic C++ class](../ide/adding-a-generic-cpp-class.md). +To make a C++ class that doesn't use MFC, ATL, or CLR, use the **C++ Class** template in the **C++** group of installed templates. For more information, see [Add a generic C++ class](../ide/adding-a-generic-cpp-class.md). Two kinds of form-based C++ classes are available. The first one, [CFormView class](../mfc/reference/cformview-class.md), creates an MFC class. The second one creates a CLR Windows Forms class. -## Add Class dialog box +::: moniker-end + +## Add Class dialog box + +::: moniker range="msvc-140" -The **Add Class** dialog box contains templates that allow you to: +In Visual Studio 2015, the **Add Class** dialog box contains templates that allow you to: - Open a corresponding code wizard, if one is available. For more information, see [Add functionality with code wizards](../ide/adding-functionality-with-code-wizards-cpp.md). @@ -51,9 +57,25 @@ You can access the **Add Class** dialog box from the **Project** menu, **Solutio > [!NOTE] > When you attempt to add a class that is not suited to your current project, you will receive an error message. Select **OK** to return to the **Add Class** dialog box. +::: moniker-end + +::: moniker range=">=msvc-150" + +In Visual Studio 2017 and later versions, the **Add Class** dialog is the generic C++ Class dialog. For more information, see [Add a generic C++ class](adding-a-generic-cpp-class.md). + +## Class Wizard dialog box + +You can create a class from installed templates in the **Class Wizard** dialog. To use the Class Wizard, right-click on your project in **Solution Explorer** and choose **Class Wizard** from the shortcut menu. The **Add Class** button on the dialog has a drop-down control for choosing a template. + +![Screenshot of the C plus plus Class Wizard dialog box.](../ide/media/vs2017-class-wizard.png) + +You can also use Class Wizard to modify or examine an existing class. + +::: moniker-end + ### Add Class templates -There are four categories of **Add Class** templates: .NET, ATL, MFC, and Generic. When you select a template in the **Templates** pane, text describing your selection will appear under the **Categories** and **Templates** panes. +There are four categories of **Add Class** templates: .NET, ATL, MFC, and Generic. #### .NET diff --git a/docs/ide/adding-a-generic-cpp-class.md b/docs/ide/adding-a-generic-cpp-class.md index bc0383c874..9d7342c49c 100644 --- a/docs/ide/adding-a-generic-cpp-class.md +++ b/docs/ide/adding-a-generic-cpp-class.md @@ -10,7 +10,9 @@ ms.assetid: e95a5a14-dbed-4edc-8551-344fe48613cb You can add a generic C++ class by using **Class View**. A generic C++ class is a class that you define or that is derived from a class that you define. -**To add a generic C++ class to a project:** +::: moniker range="msvc-140" + +## To add a generic C++ class to a project: 1. In **Class View**, right-click the project to which you want to add the new class, choose **Add**, and then choose **Class**. @@ -20,6 +22,8 @@ You can add a generic C++ class by using **Class View**. A generic C++ class is 1. To close the wizard and view the new generic C++ class in the project, select **Finish**. +::: moniker-end + ## In this section - [Generic C++ class wizard](#generic-c-class-wizard) diff --git a/docs/ide/adding-a-method-visual-cpp.md b/docs/ide/adding-a-method-visual-cpp.md index 7e84bfdbe4..6fdc77ce36 100644 --- a/docs/ide/adding-a-method-visual-cpp.md +++ b/docs/ide/adding-a-method-visual-cpp.md @@ -1,157 +1,62 @@ --- -description: "Learn more about: Add a method" +description: "Learn more about: Add a method to an interface in a Microsoft Visual Studio C++ project" title: "Add a method" -ms.date: "11/09/2018" +ms.date: "03/31/2022" f1_keywords: ["vc.codewiz.method.overview", "vc.codewiz.method.idlattrib"] helpviewer_keywords: ["add method wizard [C++]", "methods [C++], adding", "methods [C++], adding using wizards", "IDL attributes, add method wizard"] -ms.assetid: 4ba4e45f-fa38-4d5e-af44-cbec0a7ab558 +ms.custom: devdivchpfy22 --- # Add a method -You can use the [add method wizard](#add-method-wizard) to add a method to an interface in your project. If the project contains a class associated with the interface, the wizard modifies the class, too. +Use the [add method wizard](#add-method-wizard) to add a method to an interface in your project. If the project contains a class associated with the interface, the wizard also adds the method to the class. -**To add a method to your object:** +**Add a method to your interface:** -1. In **Class View**, expand the project node to display the interface to which you want to add the method. +1. From the Visual Studio main menu, choose **View** > **Class view**. In the **Class View** pane, expand the project node to display the interface you want to add the method to. > [!NOTE] - > You can also add methods to dispinterfaces, which, unless the project is attributed, are located under the library node. + > You can also add methods to dispinterfaces. Unless the project is attributed, dispinterfaces are located under the library node. 1. Right-click the name of the interface. -1. On the shortcut menu, choose **Add**, and then choose **Add Method**. +1. On the shortcut menu, choose **Add** > **Add Method**. -1. In the Add Method Wizard, provide the information to create the method. +1. In the **Add Method** wizard dialog box, provide the information to create the method as described in the next section. -1. Specify any interface definition language settings for this method in the [IDL attributes](#idl-attributes-add-method-wizard) page of the wizard. - -1. Select **Finish** to add the method. - -## In this section - -- [Add method wizard](#add-method-wizard) -- [IDL attributes, add method wizard](#idl-attributes-add-method-wizard) +1. Select **OK** to add the method. ## Add method wizard -Use this wizard to add a method to an interface. Depending on the project type or interface type to which you're adding a method, the wizard displays different options. +Add a method to an interface by using the add method wizard: -### Names - -- **Return type** - - The data type returned by the method. `HRESULT` is recommended for all interface types, because it provides a standard way to return errors. - - |Interface type|Description| - |--------------------|-----------------| - |Dual interface|`HRESULT`. Unchangeable.| - |Custom interface|`HRESULT`. Unchangeable.| - |Local custom interface|Provide your own return type or select from the list.| - |Dispinterface|Provide your own return type or select from the list.| - |MFC ActiveX control dispinterface|If you implement a stock method, the return type is set to the appropriate value and is unchangeable. If you select a method from the **Method name** list and select **Custom** under **Select method type**, select a return type from the list.| +:::image type="content" source="../ide/media/add-method-wizard.png" alt-text="Screenshot of Add method wizard. Method name is aMethod, return type is H RESULT. Two parameters are defined: int x, bool clip"::: - **Method name** - Sets the name for the method. - - |Interface type|Description| - |--------------------|-----------------| - |ATL dual interface, custom interface, and local custom interface|Provide your own method name.| - |MFC dispinterface|Provide your own method name or select a suggested method name from the list. If you select a name from the list, the appropriate value appears in the **Return type** box, and it's unchangeable.| - |MFC ActiveX control dispinterface|Provide your own or select either of the stock methods [DoClick](../mfc/reference/colecontrol-class.md#doclick) and [Refresh](../mfc/reference/colecontrol-class.md#refresh). For more information, see [MFC ActiveX controls: Adding stock methods](../mfc/mfc-activex-controls-adding-stock-methods.md).| - -- **Method type** - - Available only for MFC ActiveX controls. If you provide a method name in the **Method name** box, rather than selecting a method from the list, this box is unavailable. - - If you select one of the methods in the **Method name** list, select either the stock implementation or a custom implementation. - - |Method type|Description| - |-----------------|-----------------| - |**Stock**|The default. Inserts the stock implementation of the method you select in the **Method name** list. **Return type** is unchangeable if you select **Stock**.| - |**Custom**|Inserts a stub implementation of the method selected in the **Method name** list. For custom method types, you can provide your own return type, or you can select one from the **Return type** list.| - -- **Internal name** - - Available for only custom methods added to an MFC dispinterface. Sets the name used in the dispatch map, the header (.h) file, and the implementation (.cpp) file. By default, this name is the same as **Method name**. You can change the method name if you're working with an MFC dispinterface or if you're adding a custom method to an MFC ActiveX control dispinterface. - - |Interface type|Description| - |--------------------|-----------------| - |ATL dual interface, custom interface, and local custom interface|Not available.| - |MFC dispinterface|Set to the method name by default. You can edit the internal name.| - |MFC ActiveX control dispinterface|You can set the internal name only for custom methods. Stock methods don't use an internal name.| - -- **Parameter attributes** - - Sets any additional attributes for the parameter specified in **Parameter name**. - - |Parameter attribute|Description|Allowed combinations| - |-------------------------|-----------------|--------------------------| - |**In**|Indicates that the parameter is passed from the calling procedure to the called procedure.|`in` only

`in` and `out`| - |**Out**|Indicates that the pointer parameter is returned from the called procedure to the calling procedure (from the server to the client).|`out` only

`in` and `out`

`out` and `retval`| - |**Retval**|Indicates that the parameter receives the return value of the member.|`retval` and `out`| + Provide the method name. -- **Parameter type** - - Sets the data type of the parameter. Select the type from the list. - -- **Parameter name** - - Sets the name of a parameter to pass through your method. After you type the name, select **Add** to add it to the list of parameters that will pass through your method. If you don't provide a parameter name, the wizard ignores any parameter attributes (ATL only) or **Parameter type** selections. - - Once you select **Add**, the parameter name appears in **Parameter list**. - - > [!NOTE] - > If you supply a parameter name and then select **Finish** before you select **Add**, the parameter isn't added to the method. You must find the method and insert the parameter manually. - -- **Add** - - Adds the parameter you specify in **Parameter name**, and its type and parameter attributes, to **Parameter list**. Select **Add** to add a parameter to the list. - -- **Remove** - - Removes the parameter you select in **Parameter list** from the list. - -- **Parameter list** - - Displays all parameters and their modifiers and types currently added for the method. As you add parameters, the wizard updates **Parameter list** to display each parameter, with its modifier and type. - -## IDL attributes, add method wizard - -Use this page of the Add Method Wizard to specify any interface definition language (IDL) settings for the method. - -- `id` - - Sets the numerical ID that identifies the method. For more information, see [id](/windows/win32/Midl/id) in the *MIDL Reference*. - - This box is unavailable for custom interfaces and isn't available for MFC dispinterfaces. - -- `call_as` +- **Return type** - Specifies the name of a remote method to which this local method can be mapped. For more information, see [call_as](/windows/win32/Midl/call-as) in the *MIDL Reference*. + Type the return type or select it from the drop-down list. - Not available for MFC dispinterfaces. +- **Parameters** -- `helpcontext` + Displays the method's parameters, modifiers, and types. The wizard updates the **Parameters** list as you add parameters. - Specifies a context ID that lets the user view information about this method in the Help file. For more information, see [helpcontext](/windows/win32/Midl/helpcontext) in the *MIDL Reference*. +- **+** - Not available for MFC dispinterfaces. + Add a parameter. In **Parameters**, type the parameter type, name, and any modifiers. For example, `int x`, and choose **OK**. -- `helpstring` +- **x** - Specifies a character string that's used to describe the element to which it applies. It's set by default to "method *Method name*." For more information, see [helpstring](/windows/win32/Midl/helpstring) in the *MIDL Reference*. + Remove the selected parameter from the **Parameters** list. - Not available for MFC dispinterfaces. +- **Pencil icon** -- **Additional attributes** + Edit the selected parameter. - Not available for MFC dispinterfaces. +## See also - |Attribute|Description| - |---------------|-----------------| - |`hidden`|Indicates that the method exists but shouldn't be displayed in a user-oriented browser. For more information, see [hidden](/windows/win32/Midl/hidden) in the *MIDL Reference*.| - |`source`|Indicates that a member of the method is a source of events. For more information, see [source](/windows/win32/Midl/source) in the *MIDL Reference*.| - |`local`|Specifies to the MIDL compiler that the method isn't remote. For more information, see [local](/windows/win32/Midl/local) in the *MIDL Reference*.| - |`restricted`|Specifies that the method can't be called arbitrarily. For more information, see [restricted](/windows/win32/Midl/restricted) in the *MIDL Reference*.| - |`vararg`|Specifies that the method takes a variable number of arguments. To accomplish this, the last argument must be a safe array of `VARIANT` type that contains the rest of the arguments. For more information, see [vararg](/windows/win32/Midl/vararg) in the *MIDL Reference*.| +[Add an IDL method wizard](add-interface-definition-library-method-wizard.md)\ +[Add an IDL MFC method wizard](../mfc/reference/add-idl-mfc-method-wizard.md)\ +[Adding functionality with code wizards](adding-functionality-with-code-wizards-cpp.md) \ No newline at end of file diff --git a/docs/ide/adding-a-property-visual-cpp.md b/docs/ide/adding-a-property-visual-cpp.md index b06a10306e..f710a05bef 100644 --- a/docs/ide/adding-a-property-visual-cpp.md +++ b/docs/ide/adding-a-property-visual-cpp.md @@ -1,182 +1,59 @@ --- -description: "Learn more about: Add a property" +description: "Learn more about: Add a property to an interface in a Microsoft Visual Studio C++ project" title: "Add a property" -ms.date: "11/09/2018" -f1_keywords: ["vc.codewiz.prop.overview", "vc.codewiz.prop.idlattributes"] -helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "IDL attributes, add property wizard", "stock properties, about stock properties", "stock properties"] -ms.assetid: 37bd4db7-efd3-4faa-87ad-64902ed16a36 +ms.date: 04/12/2022 +f1_keywords: ["vc.codewiz.prop.overview"] +helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "add property wizard", "stock properties, about stock properties", "stock properties"] +ms.custom: devdivchpfy22 --- + # Add a property -You can use the [add property wizard](#names-add-property-wizard) to add a method to an interface in your project. +Use the [Add Property wizard](#add-property-wizard) to add a property to an interface in your project. -**To add a property to your object:** +**To add a property to your interface:** -1. In [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the name of the interface to which you want to add the property. +1. From the Visual Studio main menu, select **View** > **Class view**. In the [Class View](/visualstudio/ide/viewing-the-structure-of-code) pane, expand the project node to display the interface you want to add the property to. > [!NOTE] > You can also add properties to dispinterfaces, which, unless the project is attributed, are nested within the library node. -1. From the shortcut menu, choose **Add**, and then choose **Add Property**. - -1. In the [add property wizard](#names-add-property-wizard), provide the information to create the property. - -1. Specify any interface definition language (IDL) settings for the property in the [IDL attributes](#idl-attributes-add-property-wizard) page of the wizard. - -1. Select **Finish** to add the property. - -The `Get` and `Put` methods of the property are displayed as two icons in Class View, under the interface where it's defined. You can double-click either icon to view the property declaration in the .idl file. - -- For ATL interfaces, the `Get` and `Put` functions are added to the .cpp file, and references to these functions are added to the .h file. +1. Right-click the name of interface. -- For MFC dispinterfaces, if you select **Member variable** as the implementation type, a method and a variable are added to the class that implements it. If you select **Get/Set methods** as the implementation type, two methods are added to the class that implements it. +1. From the shortcut menu, select **Add** > **Add Property**. -## In this section +1. In the [Add property wizard](#add-property-wizard), provide the information to create the property. -- [Names, add property wizard](#names-add-property-wizard) -- [IDL attributes, add property wizard](#idl-attributes-add-property-wizard) -- [Stock properties](#stock-properties) +1. Select **OK** to add the property. -## Names, add property wizard +## Add Property wizard -Use this wizard to add a property to an interface. +The following section describes the UI that you'll use to add a property: -- **Property type** - - Sets the type of property you're adding. For MFC dispinterfaces, provide your own type or select from the predefined list. If you provide a stock implementation of a property, **Property type** is set to the stock type and is unavailable for change. +:::image type="content" source="../ide/media/add-property-wizard.png" alt-text="Screenshot of Add property wizard with the method name field set to sample and the property type set to int a"::: - **Property name** - Sets the name of the property. For MFC dispinterfaces associated with ActiveX controls, you can supply your own name or you can select a stock property name from the predefined list. If you provide your own property name, the **Stock** implementation type is unavailable. See [stock properties](#stock-properties) for a description of the properties in the list. - - |Interface type|Description| - |--------------------|-----------------| - |ATL dual interface, custom interface, and local custom interface|Provide a property name.| - |MFC dispinterface, MFC ActiveX control dispinterface|Provide a property name or select a stock property from the list. If you select a property from the list, the appropriate value appears in the **Property type** box. You can change this type, depending on your selection under **Implementation type**.| - -- **Return type** - - ATL interfaces only. Sets the return type for the property. For dual interfaces, `HRESULT` is always the return type, and this box is unavailable. For custom interfaces, you can select a return type from the list. `HRESULT` is still recommended, because it provides a standard way to return errors. - -- **Variable name** + Sets the name of the property. - MFC dispinterfaces only. Available only if you specify **Member variable** under **Implementation type**. Sets the name of the member variable with which the property is associated. By default, the variable name is set to `m_`*PropertyName*. You can edit this name. - -- **Notification function** +- **Property type** - MFC dispinterfaces only. Available only if you specify **Member variable** under **Implementation type**. Sets the name of the notification function called if the property changes. By default, the name of the notification function is set to `On`*PropertyName*`Changed`. You can edit this name. + Sets the return type of the property. - **Get function** - For MFC dispinterfaces. Available only if you specify **Get/Set methods** under **Implementation type**. Sets the name of the function to get the property. By default, the name of the `Get` function is set to `Get`*PropertyName*. You can edit this name. If you delete the name, the function [GetNotSupported](../mfc/reference/colecontrol-class.md#getnotsupported) is inserted into the interface dispatch map. The `Get`*PropertyName* function specifies that the property as readable. - -- **Set function** - - MFC dispinterfaces only. Available only if you specify **Get/Set methods** under **Implementation type**. Sets the name of the function to set the property. By default, the name of the `Set` function is set to `Set`*PropertyName*. You can edit this name. If you delete the name, the function [SetNotSupported](../mfc/reference/colecontrol-class.md#setnotsupported) is inserted into the interface dispatch map. The `Set`*PropertyName* function specifies that the property is writable. - -- **Implementation type** - - MFC dispinterfaces only. Specifies how to implement the property you're adding. + Select to add a property getter. By default, the name of the `Get` function is `Get`*PropertyName*. You can edit this name. If you delete the name, the function [`GetNotSupported`](../mfc/reference/colecontrol-class.md#getnotsupported) is inserted into the interface dispatch map. The `Get`*PropertyName* function specifies the property as readable. - |Implementation type|Description| - |-------------------------|-----------------| - |**Stock**|Specifies a stock implementation for the property selected in **Property name**. The default. For more information, see [stock properties](#stock-properties).

If you specify **Stock**, then **Property type**, **Parameter type**, and **Parameter name** are dimmed.| - |**Member variable**|Specifies the property is added as a member variable. You can add custom properties or most stock properties as member variables. You can't specify **Member variable** for the `Caption`, `hWnd`, and `Text` properties.

Provides default names under **Variable name** and **Notification function**. You can edit this name.| - |**Get/Set methods**|Specifies the property is added as `Get`*PropertyName* and `Set`*PropertyName* functions, by default. These names appear under **Get function** and **Set function**.

You can change the default **Property type**, which passes a value for the Get function. You can specify parameters for the `Get` and `Set` functions.| - -- **Get function** - - For ATL interfaces. Sets the property as readable; that is, it creates the `Get` method for retrieving this property from the object. Select **Get**, **Put**, or both. + For ATL interfaces **Get function** makes the property readable; that is, it creates the `Get` method for retrieving this property from the object. Select **Get**, **Put**, or both. - **Put function** - ATL interfaces only. Sets the property writable; that is, it creates the `Put` method for setting, or "putting," this property of the object. Select **Get**, **Put**, or both. If you select this option, you can choose from the following two ways to implement the method: - - |Option|Description| - |------------|-----------------| - |**PropPut**|The [PropPut](../windows/attributes/propput.md) function returns a copy of the object. This is the default and the most common way to make the property writable.| - |**PropPutRef**|The [PropPutRef](../windows/attributes/propputref.md) function returns a reference to the object, rather than returning the copy of the object itself. Consider using this option for objects, such as large structs or arrays, that may have initialization overhead.| - -- **Parameter attributes** - - ATL interfaces only. Sets whether the parameter specified by **Parameter name** is `in`, `out`, both, or none. - - |Option|Description| - |------------|-----------------| - |`in`|Indicates that the parameter is passed from the calling procedure to the called procedure.| - |`out`|Indicates that the pointer parameter is returned from the called procedure to the calling procedure (from the server to the client).| - -- **Parameter type** - - Sets the data type of the parameter. Select the type from the list. - -- **Parameter name** - - Sets the name of a parameter you're adding for the property, if the property has parameters. Once you select **Add**, the parameter name appears in **Parameter list**. - -- **Parameter list** - - Displays the list of attributes to be added to the property. Each item in the list consists of the parameter name, parameter type, and attributes. Use **Add** and **Remove** to update the list. - -- **Add** - - Adds the parameter you specify in **Parameter name** and **Parameter type** to the **Parameter list**. Select **Add** to add a parameter to the list. - -- **Remove** - - Removes the parameter you select in **Parameter list**. - -- **Default property** - - MFC dispinterface only. Sets this property as the default for the interface. An interface can have only one default property; once you specify the default property, for any other properties you add to the interface, this box is unavailable. - -## IDL attributes, add property wizard - -Use this page of the Add Property Wizard to specify any interface definition language (IDL) settings for the property. - -- `id` - - Sets the numerical ID that identifies the property. This option isn't available for properties of custom interfaces. See [id](/windows/win32/Midl/id) in the *MIDL Reference*. - -- `helpcontext` - - Specifies a context ID that lets the user view information about this property in the Help file. See [helpcontext](/windows/win32/Midl/helpcontext) in the *MIDL Reference*. - -- `helpstring` - - Specifies a character string that's used to describe the element to which it applies. By default, it's set to **`property`** *Property name*. See [helpstring](/windows/win32/Midl/helpstring) in the *MIDL Reference*. - -### Other options - -Not all options are available to all property types. + Select to add a property setter. By default, the name of the `Set` function is `Set`*PropertyName*. You can edit this name. If you delete the name, the function [`SetNotSupported`](../mfc/reference/colecontrol-class.md#setnotsupported) is inserted into the interface dispatch map. The `Set`*PropertyName* function specifies that the property is writable. -|Option|Description| -|------------|-----------------| -|`bindable`|Indicates that the property supports data binding. See [bindable](/windows/win32/Midl/bindable) in the *MIDL Reference*. For the stock implementation of the property, this option is set by default and is unchangeable.| -|`defaultbind`|Indicates that this single, bindable property best represents the object. See [defaultbind](/windows/win32/Midl/defaultbind) in the *MIDL Reference*.| -|`displaybind`|Indicates that this property should be displayed to the user as bindable. See [displaybind](/windows/win32/Midl/displaybind) in the *MIDL Reference*.| -|`immediatebind`|Indicates that the database will be notified immediately of all changes to this property of a data-bound object. See [immediatebind](/windows/win32/Midl/immediatebind) in the *MIDL Reference*.| -|`defaultcollelem`|Indicates that the property is an accessor function for an element of the default collection. See [defaultcollelem](/windows/win32/Midl/defaultcollelem) in the *MIDL Reference*.| -|`nonbrowsable`|Tags an interface or dispinterface member that shouldn't be displayed in a properties browser. See [nonbrowsable](/windows/win32/Midl/nonbrowsable) in the *MIDL Reference*.| -|`requestedit`|Indicates that the property supports the `OnRequestEdit` notification. See [requestedit](/windows/win32/Midl/requestedit) in the *MIDL Reference*. For the stock implementation of the property, this option is set by default and is unchangeable.| -|`source`|Indicates that a member of the property is a source of events. See [source](/windows/win32/Midl/source) in the *MIDL Reference*.| -|`hidden`|Indicates that the property exists but shouldn't be displayed in a user-oriented browser. See [hidden](/windows/win32/Midl/hidden) in the *MIDL Reference*.| -|`restricted`|Specifies that the property can't be called arbitrarily. See [restricted](/windows/win32/Midl/restricted) in the *MIDL Reference*.| -|`local`|Specifies to the MIDL compiler that the property isn't remote. See [local](/windows/win32/Midl/local) in the *MIDL Reference*.| + For ATL interfaces **Put function** makes the property writable; that is, it creates the `Put` method for setting, or "putting," this property of the object. Select **Get**, **Put**, or both. -## Stock properties +## See Also -If you're adding a property to an MFC dispinterface using the [add property wizard](#idl-attributes-add-property-wizard), you can choose a stock property from the **Property name** list in the [Names](#names-add-property-wizard) page of the wizard. These properties are as follows: +[Add IDL Property](add-interface-definition-library-property-wizard.md) -|Property name|Description| -|-------------------|-----------------| -|`Appearance`|Returns or sets a value that determines the appearance of the control. The control's `Appearance` property can include or omit three-dimensional display effects. This property is an ambient read/write property.| -|`BackColor`|Returns or sets the control's ambient `BackColor` property to either a palette (RGB) color or a predefined system color. By default, its value corresponds to the foreground color of the control's container. This property is an ambient read/write property.| -|`BorderStyle`|Returns or sets the border style for a control. This property is a read/write property.| -|`Caption`|Returns or sets the control's `Caption` property. The caption is the title of the window. `Caption` has no **Member variable** implementation type.| -|`Enabled`|Returns or sets the control's `Enabled` property. An enabled control can respond to user-generated events.| -|`Font`|Returns or sets the control's ambient font. Null if the control has no font.| -|`ForeColor`|Returns or sets the control's ambient `ForeColor` property.| -|`hWnd`|Returns or sets the control's `hWnd` property. `hWnd` has no **Member variable** implementation type.| -|`ReadyState`|Returns or sets the control's `ReadyState` property. A control can be uninitialized, initialized, loading, interactive, or complete. For more information, see [READYSTATE](/previous-versions/aa768362\(v=vs.85\)) in the *Internet SDK*.| -|`Text`|Returns or sets the text contained in a control. `Text` has no **Member variable** implementation type.| +[Add IDL MFC Property](../mfc/reference/add-interface-definition-library-mfc-property-wizard.md) \ No newline at end of file diff --git a/docs/ide/adding-functionality-with-code-wizards-cpp.md b/docs/ide/adding-functionality-with-code-wizards-cpp.md index ac4767cb36..a5088db657 100644 --- a/docs/ide/adding-functionality-with-code-wizards-cpp.md +++ b/docs/ide/adding-functionality-with-code-wizards-cpp.md @@ -10,7 +10,7 @@ ms.assetid: 6afb7ef9-7056-423d-b244-91bb4236d1d7 Once you have created a project, you will want to change or add to that project's functionality. Such tasks include creating new classes, adding new member functions and variables, and adding Automation methods and properties. The code wizards are designed to let you do all these things. > [!NOTE] -> The following rarely-used code wizards are removed in Visual Studio 2019. General support for ATL and MFC is not impacted by the removal of these wizards. Sample code for these technologies is archived at Microsoft Docs and the VCSamples GitHub repository. +> The following rarely-used code wizards are removed in Visual Studio 2019. General support for ATL and MFC is not impacted by the removal of these wizards. Sample code for these technologies is archived in Microsoft Learn and the VCSamples GitHub repository. - ATL COM+ 1.0 Component Wizard - ATL Active Server Pages Component Wizard @@ -64,7 +64,7 @@ There are three locations where you can access C++ code wizards: |-----------------------------|-----------------| |Add New Item|The Add New Item code wizards add source files to your project. If necessary, additional directories are created to contain the files where the project build engine expects to find them. Code wizards available from the Add Item icon include:

- Add C++ source files (.cpp, .h, .idl, .rc, .srf, .def, .rgs).
- Add Web development files (.html, .asp, .css, .xml).
- Add utility and resource files (.bmp, .cur, .ico, .rct, .sql, .txt).

These code wizards generally do not ask you for any information but add a file to your development tree. You may rename the file in the property window.| |Solution Explorer|The code wizards available from Solution Explorer depend on where your cursor focus is when you right-click an item. If the **Add** option does not appear when you right-click an item, then move your cursor up one level in the development tree and try again. The code wizards will always place the additional code in the appropriate place in the development tree, no matter where your cursor is. Code wizards available from Solution Explorer include:

- Add Class (opens the **Add Class** dialog box containing the new code wizards).
- Add Resource (New, Import, or Custom).
- Add Web Reference.| - |Class View|The code wizards available from Class View depend on where your cursor focus is when you right click an item. If the **Add** option does not appear when you right click an item, then move your cursor up one level in the class tree and try again. The code wizards will always place the additional code in the appropriate place in the development tree, no matter where your cursor is. Code wizards available from Class View include:

- [Add Member Function](../ide/adding-a-member-function-visual-cpp.md).
- [Add Member Variable](../ide/adding-a-member-variable-visual-cpp.md).
- [Add Class](../ide/adding-a-class-visual-cpp.md).
- [Implement Interface](./implementing-an-interface-visual-cpp.md#implement-interface-wizard) (from a control class only)
- [Add Connection Point](./implementing-a-connection-point-visual-cpp.md#implement-connection-point-wizard) (ATL class only)
- [Add Method](./adding-a-method-visual-cpp.md#add-method-wizard) (from an interface only)
- [Add Property](./adding-a-property-visual-cpp.md#names-add-property-wizard) (from an interface only)
- [Add Event](./adding-an-event-visual-cpp.md#add-event-wizard) (from a control class only)

The Add Class selection opens the **Add Class** dialog box, which gives you access to all the new Add Class code wizards.| + |Class View|The code wizards available from Class View depend on where your cursor focus is when you right click an item. If the **Add** option does not appear when you right click an item, then move your cursor up one level in the class tree and try again. The code wizards will always place the additional code in the appropriate place in the development tree, no matter where your cursor is. Code wizards available from Class View include:

- [Add Member Function](../ide/adding-a-member-function-visual-cpp.md).
- [Add Member Variable](../ide/adding-a-member-variable-visual-cpp.md).
- [Add Class](../ide/adding-a-class-visual-cpp.md).
- [Implement Interface](./implementing-an-interface-visual-cpp.md#implement-interface-wizard) (from a control class only)
- [Add Connection Point](./implementing-a-connection-point-visual-cpp.md#implement-connection-point-wizard) (ATL class only)
- [Add Method](./adding-a-method-visual-cpp.md) (from an interface only)
- [Add Property](./adding-a-property-visual-cpp.md) (from an interface only)
- [Add Event](./adding-an-event-visual-cpp.md#add-event-wizard) (from a control class only)

The Add Class selection opens the **Add Class** dialog box, which gives you access to all the new Add Class code wizards.| ## See also diff --git a/docs/ide/cpp-linter-overview.md b/docs/ide/cpp-linter-overview.md index a6bda09ef7..07057453ac 100644 --- a/docs/ide/cpp-linter-overview.md +++ b/docs/ide/cpp-linter-overview.md @@ -16,7 +16,9 @@ monikerRange: ">=msvc-160" The IntelliSense code linter for C++ helps developers find and fix common C++ problems right inside Visual Studio. It's based on the same engine that provides C++ IntelliSense, so problems are flagged as soon as you type them. -![Animation showing the C plus plus linter in action.](../ide/media/linter-demo-animation.gif) +:::image type="complex" source="media/linter-demo-animation.gif" alt-text="Animation showing the C plus plus linter in action."::: +As the user types if (i = 3), a popup appears suggesting the correction i == 3, which is selected and updates the code to read if (i == 3) +:::image-end::: ## Find problems @@ -26,7 +28,7 @@ Starting in Visual Studio 2022, the C++ Linter is enabled by default. To use it, Most of the linter checks have suggestions for fixing the problem. Hover over the error squiggle and choose the light bulb that pops up to see the suggestions. A preview diff of the suggested change is shown, so you can confirm the change makes sense before you apply it. -## Configure the linter +## Configure the linter You can enable or disable the linter, or configure the severity level for each check, in the C++ Code Style options. @@ -38,7 +40,7 @@ When you change the check severity level, it changes how the problem is shown in ::: moniker range=">=msvc-170" -![Screenshot that shows the C plus plus linter configuration.](../ide/media/linter-settings.png) +![Screenshot of the linter configuration window with options such as warning on accidental assignment, uninitialized local variable, and more.](media/linter-settings.png) (The presentation in Visual Studio 2019 is slightly different, but the options are similar.) diff --git a/docs/ide/creating-a-com-interface-visual-cpp.md b/docs/ide/creating-a-com-interface-visual-cpp.md index c7b9eabcdc..65a379d516 100644 --- a/docs/ide/creating-a-com-interface-visual-cpp.md +++ b/docs/ide/creating-a-com-interface-visual-cpp.md @@ -73,7 +73,7 @@ The following three wizards help you customize existing interfaces. They're avai |Wizard|Project type| |------------|------------------| -|[Add property wizard](./adding-a-property-visual-cpp.md#names-add-property-wizard)|ATL or MFC projects supporting ATL. Right-click the interface to which you want to add the property.

Visual C++ detects the project type and modifies the options in the Add Property Wizard as necessary:

- For dispinterfaces in projects created by using the [MFC application wizard](../mfc/reference/mfc-application-wizard.md), invoking the Add Property Wizard provides options specific to MFC.
- For MFC ActiveX control interfaces, the Add Property Wizard provides a list of stock methods and properties that you can use as provided or customize for your control.
- For all other interfaces, the Add Property Wizards provide options useful in most situations.| -|[Add method wizard](./adding-a-method-visual-cpp.md#add-method-wizard)|ATL or MFC projects supporting ATL. Right-click the interface to which you want to add the method.

Visual C++ detects the project type and modifies the options in the Add Method Wizard as necessary:

- For dispinterfaces in projects created by using the [MFC application wizard](../mfc/reference/mfc-application-wizard.md), using the Add Method Wizard provides options specific to MFC.
- For MFC ActiveX control interfaces, the Add Method Wizard provides a list of stock methods and properties that you can use as provided or customize for your control.
- For all other interfaces, the **Add Method** wizards provide options useful in most situations.| +|[Add property wizard](./adding-a-property-visual-cpp.md)|ATL or MFC projects supporting ATL. Right-click the interface to which you want to add the property.

Visual C++ detects the project type and modifies the options in the Add Property Wizard as necessary:

- For dispinterfaces in projects created by using the [MFC application wizard](../mfc/reference/mfc-application-wizard.md), invoking the Add Property Wizard provides options specific to MFC.
- For MFC ActiveX control interfaces, the Add Property Wizard provides a list of stock methods and properties that you can use as provided or customize for your control.
- For all other interfaces, the Add Property Wizards provide options useful in most situations.| +|[Add method wizard](./adding-a-method-visual-cpp.md)|ATL or MFC projects supporting ATL. Right-click the interface to which you want to add the method.

Visual C++ detects the project type and modifies the options in the Add Method Wizard as necessary:

- For dispinterfaces in projects created by using the [MFC application wizard](../mfc/reference/mfc-application-wizard.md), using the Add Method Wizard provides options specific to MFC.
- For MFC ActiveX control interfaces, the Add Method Wizard provides a list of stock methods and properties that you can use as provided or customize for your control.
- For all other interfaces, the **Add Method** wizards provide options useful in most situations.| Additionally, you can implement new interfaces on your COM control. Just right-click the object's control class in Class View and choose [Implement Interface](./implementing-an-interface-visual-cpp.md#implement-interface-wizard). diff --git a/docs/ide/how-to-set-preferences.md b/docs/ide/how-to-set-preferences.md index fe492600dc..a4acc28862 100644 --- a/docs/ide/how-to-set-preferences.md +++ b/docs/ide/how-to-set-preferences.md @@ -16,7 +16,7 @@ You can make your C++ coding experience more convenient, productive, and pleasur - Specify C++ formatting rules, including several styles of ClangFormat. - Create custom keyboard shortcuts. -You can synchronize your preferences across multiple machines, and create and store multiple sets of preferences and share them with teammates. You can install extensions from the Visual Studio Marketplace, giving you additional options for customizing behavior. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). +You can synchronize your preferences across multiple machines, and create and store multiple sets of preferences and share them with teammates. You can install extensions from the Visual Studio Marketplace, giving you more options for customizing behavior. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). ## Arrange window layout @@ -24,7 +24,7 @@ Within the Visual Studio window, the space is divided into the main menu, the to The following screenshot shows the **Team Explorer** window being dragged from its default position to a new, docked position on the left side of the code editor. The blue shaded area shows where the window will be placed when the mouse button is released. -![Screenshot of Visual Studio Team Explorer window, with layout change highlighted.](media/window-layout-move-team-explorer.png) +![Screenshot of Visual Studio Team Explorer window, with the blue shaded area highlighted where the window will be placed when the mouse is released.](media/window-layout-move-team-explorer.png) In the document window, each open file is contained in a tabbed frame. You can float or lock these tabs, just like tool windows. For more information, see [Customize window layouts in Visual Studio](/visualstudio/ide/customizing-window-layouts-in-visual-studio). @@ -34,7 +34,7 @@ To hide all the tool windows and maximize the Code Editor window, press **Alt** You can specify many individual code formatting options, such as indentation and brace positions. To do so, go to **Tools** > **Options** > **Text Editor** > **C/C++** > **Formatting** (or type **Ctrl + Q** and search for "Formatting"). Alternatively, you can specify one of the [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) styles (or your own custom ClangFormat style). -![Screenshot of ClangFormat options.](media/clang-format-ide.png) +![Screenshot of the Options pane with Text Editor > C / C plus plus > Formatting > General selected. In the right pane the ClangFormat options appear.](media/clang-format-ide.png) For more information about all the formatting options, see [Options, Text Editor, C/C++, Formatting](/visualstudio/ide/reference/options-text-editor-c-cpp-formatting). @@ -42,25 +42,25 @@ For more information about all the formatting options, see [Options, Text Editor To set a light or dark background, type **Ctrl + Q** and search for "Color Theme". You can also find these by going to **Tools** > **Options** > **Environment**, and choosing **Color Theme**. -![Screenshot of color themes.](media/tools-options-color-theme.png) +![Screenshot of the Options pane. Environment > General is selected. On the right, the color theme dropdown shows options for Light, Dark, and more.](media/tools-options-color-theme.png) For example, here's the dark theme: -![Screenshot of Visual Studio with dark color theme.](media/tools-options-dark-theme.png) +![Screenshot of Visual Studio with the dark color theme.](media/tools-options-dark-theme.png) ## Customize code colorization In Visual Studio 2019, you can choose from three predefined *color schemes*. These specify how code elements are colorized in the editor. To choose a theme, go to **Tools** > **Options** > **Text Editor** > **C/C++** > **View**, and choose **Color Scheme**: -![Screenshot of C++ Color Scheme options, with Enhanced highlighted.](media/color-schemes.png) +![Screenshot of C++ Color Scheme dropdown options. Of the available options, Enhanced is highlighted.](media/color-schemes.png) -In the color scheme called **Visual Studio 2017**, most code elements are simply black. In the **Enhanced** color scheme, functions, local variables, macros, and other elements are colorized. In the **Enhanced (Globals vs. Members)** scheme, global functions and variables are colorized to contrast with class members. The default mode is **Enhanced**, and it looks like this: +In the color scheme called **Visual Studio 2017**, most code elements are black. In the **Enhanced** color scheme, functions, local variables, macros, and other elements are colorized. In the **Enhanced (Globals vs. Members)** scheme, global functions and variables are colorized to contrast with class members. The default mode is **Enhanced**, and it looks like this: -![Screenshot of enhanced color scheme.](media/color-scheme-enhanced.png) +![Screenshot of the enhanced color scheme which has a black background and colors for C++ keywords such as blue for int and green for comments.](media/color-scheme-enhanced.png) Regardless of which theme or color scheme is active, you can customize the font and colors for individual code elements. To do this, go to **Tools** > **Options** > **Environment** > **Fonts and Colors** (or type **Ctrl + Q** and search for "Fonts"). Scroll down the list of display items until you see the C++ options. -![Screenshot of C++ font and color options.](media/tools-options-cpp-colors.png) +![Screenshot of C++ font and color options that shows you can set colors for C++ code elements such as enums, functions, keywords, macros, and so on.](media/tools-options-cpp-colors.png) Colors that you set here override the values defined for the color schemes. If you want to go back to the default colors for the color scheme, set a color back to **Default**. @@ -70,11 +70,11 @@ The toolbars provide a convenient way to issue commands with a single click, rat Hover over the icons in the toolbar to see which command it represents: -![Screenshot of toolbar icons, with example of command information available on hover.](media/toolbar-mouse-hover.png) +![Screenshot of hovering over the bookmark icon. The tooltip says: "Toggle a bookmark on the current line", along with the keyboard shortcut Ctrl+K, Ctrl+K.](media/toolbar-mouse-hover.png) You can add or remove commands, or create a custom toolbar, by selecting the down-arrow. To move the toolbar to a new location, drag it by the dotted bar on the left. -![Screenshot of toolbar, with down-arrow and dotted bar highlighted.](media/toolbar-move-edit.png). +![Screenshot of a toolbar with the dotted bar on the left highlighted where you move the toolbar with the mouse. The down arrow is also highlighted.](media/toolbar-move-edit.png). For more information, see [How to: Customize menus and toolbars in Visual Studio](/visualstudio/ide/how-to-customize-menus-and-toolbars-in-visual-studio). @@ -82,7 +82,7 @@ For more information, see [How to: Customize menus and toolbars in Visual Studio You can specify whether line numbers show on the left of the editor windows. In **Options**, under **C/C++**, select **General**. In the **Settings** section, select or clear **Line numbers**, depending on your preference. -![Screenshot of General options, with Line numbers highlighted.](media/tools-options-line-numbers.png) +![Screenshot of General options (Text Editor > C / C plus plus > General). The Line numbers checkbox is highlighted.](media/tools-options-line-numbers.png) ## Create keyboard shortcuts diff --git a/docs/ide/include-cleanup-config.md b/docs/ide/include-cleanup-config.md new file mode 100644 index 0000000000..5d4e281390 --- /dev/null +++ b/docs/ide/include-cleanup-config.md @@ -0,0 +1,67 @@ +--- +title: "Configure C/C++ Include Cleanup in Visual Studio" +description: "Learn how to configure C/C++ Include Cleanup." +ms.date: 10/10/2023 +ms.topic: "how-to" +f1_keywords: ["config include cleanup"] +helpviewer_keywords: ["config include cleanup"] +--- +# Configure C/C++ Include Cleanup in Visual Studio + +Starting with 17.8 Preview 1, Visual Studio can clean up your `#include`s to improve the quality of your C and C++ code in the following ways: +- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file. +- Offers to remove unused header files--improving build times. + +This article describes how to configure Include Cleanup in Visual Studio. For more information about Include Cleanup, see [C/C++ Include Cleanup overview](include-cleanup-overview.md). + +## Turn on Include Cleanup + +The Include Cleanup feature is on by default. If it isn't active, you can turn it on via **Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup** and select **Enable #include cleanup**. + +Then use the dropdowns to configure how you want to be notified about opportunities to add indirect headers or remove unused headers: + +:::image type="complex" source="media/vs2022-include-cleanup-option.png" alt-text="The Tools options dialog opened at Text Editor > C/C++ > Code Cleanup."::: +The Enable # include cleanup checkbox is checked. The dropdowns for Remove unused includes suggestion level, and Add missing includes suggestion level, are shown. The contents of the dropdown are shown, which are: **Refactoring only**, **Suggestion**, **Warning**, and **Error**. The **Remove unused includes suggestion level** dropdown offers the same options but also adds dimmed. +:::image-end::: + +The meanings of the suggestion level options are: + +**Refactoring only**: Include Cleanup offers actions you can take through the quick action menu when you hover the mouse pointer over an `#include`, or place the cursor on the `#include` line and press Ctrl+period: + +:::image type="complex" source="media/include-cleanup-refactor-lightbulb.png" alt-text="A screenshot of the quick action to remove an unused header"::: +When hovering the cursor over # include iostream, a light bulb appears with the text that # include iostream isn't used in this file." +:::image-end::: + +**Suggestion, Warning, Error**: Include Cleanup offers actions it can take via suggestions, warnings, or errors in the Error List window. You determine which. In the following screenshot of the Error List, Include Cleanup is configured to show unused headers with a warning. Ensure that **Build + Intellisense** is selected in the dropdown filter so that you can see the Include Cleanup output: + +:::image type="complex" source="media/include-cleanup-error-list.png" alt-text="A screenshot of the Error List window."::: +The dropdown filter is set to Build + IntelliSense. A warning is visible: VCIC002 - #include < iostream > isn't used in this file." +:::image-end::: + +**Dimmed** + +Include Cleanup shows unused headers by dimming the line of the unused header file in the code editor. Hover your cursor over the dimmed `#include` to bring up the quick action menu and choose **Show potential fixes**, or click on the light bulb dropdown, to see actions related to the unused file. + +:::image type="complex" source="media/include-cleanup-dimmed-include.png" alt-text="A screenshot of a dimmed #include < iostream > line."::: +The line for #include < iostream > is dimmed because the line of code that uses iostream is commented out. That line of code is // std::cout << "charSize = " << charSize; The quick action menu is also visible for this line. It says the #include < iostream > isn't used in this file, and has a link to Show potential fixes. +:::image-end::: + +## Configure Include Cleanup with `.editorconfig` + +There are more options for configuring Include Cleanup such as excluding specified includes from cleanup suggestions, indicating that some header files are required so that the tool doesn't mark them as unused, and so on. These options are defined in an `.editorconfig` file, that you can add to your project to, among other things, enforce consistent coding styles for everyone that works in the codebase. For more information about adding an `.editorconfig` file to your project, see [Create portable, custom editor settings with EditorConfig](/visualstudio/ide/create-portable-custom-editor-options). + +The `.editorconfig` settings that you can use with Include Cleanup are: + +| Setting | Values | Example | +|--|--|--|--| +| `cpp_include_cleanup_add_missing_error_tag_type`

Sets the error level of add transitive include messages. | `none`
`suggestion`
`warning`
`error` | `cpp_include_cleanup_add_missing_error_tag_type = suggestion` | +| `cpp_include_cleanup_remove_unused_error_tag_type`

Sets the error level of remove unused include messages. | `none`
`suggestion`
`warning`
`error`
`dimmed` | `cpp_include_cleanup_remove_unused_error_tag_type = dimmed` | +| `cpp_include_cleanup_excluded_files`

Excludes the specified files from Include Cleanup messages. You won't get a suggestion related to the header at all, whether to add it or that it's unused. | *filename* | `cpp_include_cleanup_excluded_files = vcruntime.h, vcruntime_string.h` | +| `cpp_include_cleanup_required_files`

Specify that usage of *file1* requires *file2*. For example, specify that if you use `atlwin.h` that `altbase.h` must also be included. | *file1*:*file2* | `cpp_include_cleanup_required_files = atlwin.h:altbase.h, atlcom.h:altbase.h` | +| `cpp_include_cleanup_replacement_files`

Replaces *file1* with *file2* during Include Cleanup processing. For example, you may prefer using `cstdio` over `stdio.h`. If you have a file with both `#include ` and `#include ` and you consume content only from `stdio.h`, with this setting Include Cleanup will tell you to remove `stdio.h` because it replaced the usage of `cstdio` with `stdio.h` during processing. If you don't use the contents from either, Include Cleanup will tell you to remove both.| *file1*:*file2* | `cpp_include_cleanup_replacement_files = stdio.h:cstdio,stdint.h:cstdint` | +| `cpp_include_cleanup_alternate_files`

Don't generate a message for indirect include *file2* if *file1* is included. For example, if you `#include ` and are only using something from its indirectly included header `winerror.h`, Include Cleanup won't prompt to add `winerror.h`. Useful when you prefer to include a facade header file instead of the indirect includes it contains. | *file1*:*file2* | `cpp_include_cleanup_alternate_files = windows.h:winerror.h, windows.h:minwindef.h` | + +## See also + +[C/C++ Include Cleanup overview](include-cleanup-overview.md)\ +[Include Cleanup messages](include-cleanup-messages.md) diff --git a/docs/ide/include-cleanup-messages.md b/docs/ide/include-cleanup-messages.md new file mode 100644 index 0000000000..e3dfcb4af6 --- /dev/null +++ b/docs/ide/include-cleanup-messages.md @@ -0,0 +1,41 @@ +--- +title: "Include Cleanup messages" +description: "Learn what the messages generated by Include Cleanup mean." +ms.date: 10/10/2023 +ms.topic: "reference" +f1_keywords: ["VCIC001", "VCIC002"] +helpviewer_keywords: ["VCIC001", "VCIC002"] +--- +# Include Cleanup messages + +This article describes the messages generated by the Include Cleanup feature. For more information about Include Cleanup, see [C/C++ Include Cleanup overview](include-cleanup-overview.md). + +Starting with 17.8 Preview 1, Visual Studio can clean up your `#include`s to improve the quality of your C and C++ code in the following ways: + +- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file. +- Offers to remove unused header files--improving build times. + +You can choose whether messages from Include Cleanup appear in the form of suggestions, warnings, or errors in the Error List window. For more information, see [Config C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md). + +In the following screenshot of the Error List, Include Cleanup is configured to show unused headers with a warning: + +:::image type="complex" source="media/include-cleanup-error-list.png" alt-text="A screenshot of the Error List window."::: +The dropdown filter is set to Build + IntelliSense. A warning is visible: VCIC002 - #include < iostream > isn't used in this file." +:::image-end::: + +Include Cleanup generates the following messages: + +## `VCIC001`: Content from #include is used in this file and transitively included + +This message means that you're using content from a header file that is included indirectly. + +For example, you may be directly including a header file that also contains `#include `. If you use `string` in your code, but don't `#include ` in that file, it works as long as the other header file continues to indirectly include `` for you. This message identifies this situation in your code so that you can take action to directly include the transitively included header file. For more information, see [Direct vs indirect headers](include-cleanup-overview.md#direct-vs-indirect-headers). + +## `VCIC002`: #include is not used in this file + +This message means that the specified header file is not used in the current file. You can remove the associated `#include` directive to clean up your `#include`s and improve your build times. + +## See also + +[C/C++ Include Cleanup overview](include-cleanup-overview.md)\ +[Configure C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md) \ No newline at end of file diff --git a/docs/ide/include-cleanup-overview.md b/docs/ide/include-cleanup-overview.md new file mode 100644 index 0000000000..423b16a344 --- /dev/null +++ b/docs/ide/include-cleanup-overview.md @@ -0,0 +1,125 @@ +--- +title: "Clean up C/C++ #includes in Visual Studio" +description: "Learn about using C/C++ Include Cleanup in Visual Studio to remove unused headers, and transitively add indirect headers needed in your project." +ms.date: 10/5/2023 +ms.topic: "overview" +ms.custom: intro-overview +f1_keywords: ["include cleanup"] +helpviewer_keywords: ["include cleanup"] +--- +# Clean up C/C++ includes in Visual Studio + +Starting with Visual Studio 17.8 Preview 1, Visual Studio provides an `#include` cleanup feature that improves the quality of your code in the following ways: + +- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file. +- Offers to remove unused header files--improving build times and code cleanliness. + +Include Cleanup is on by default. To learn how to configure it, see [Config C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md). + +## Direct vs indirect headers + +First some terminology: + +- A direct header is a header that you explicitly `#include` in your code. +- An indirect header is a header that you don't explicitly `#include`. Instead, a header file that you do directly include, includes it. We also say that an indirect header is included `transitively`. + +Include Cleanup analyzes your code and determines which headers aren't used and which are indirectly included. Consider the following header file: + +```cpp +// myHeader.h + +#include +#include + +void myFunc() +{ + std::string s = "myFunc()\n"; + std::cout << s; +} +``` + +And the program that uses it: + +```cpp +// myProgram.cpp +#include "myHeader.h" + +int main() +{ + std::string s = "main()"; // string is indirectly included by myHeader.h + std::cout << s; // cout is indirectly included by myHeader.h + myFunc(); +} +``` + +`myHeader.h` is a direct header because `myProgram.cpp` explicitly includes it. `myHeader.h` includes `` and ``, so those are indirect headers. + +The issue is that `myProgram.cpp` uses `std::string` and `std::cout`, but doesn't directly include the headers that define them. This code happens to compile because `myHeader.h` includes those headers. This code is brittle because if `myHeader.h` ever stopped including either one, `myProgram.cpp` wouldn't compile anymore. + +Per the C++ guidelines, it's better to explicitly include headers for all of your dependencies so that your code isn't subject to brittleness caused by changes to header files. For more information, see [SF.10: Avoid dependencies on implicitly `#include`d names](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf10-avoid-dependencies-on-implicitly-included-names) in the C++ Core Guidelines. + +Include Cleanup analyzes your code to identify unused and indirectly included headers. It provides feedback based on the settings described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md). Feedback can be in the form of error list warnings, suggestions, etc. For more details on the feedback provided by Include Cleanup, refer [Include Cleanup messages](include-cleanup-messages.md). + +## Unused headers + +As your code evolves, you may no longer need some header files. This is hard to keep track of in a complex project. Over time, your builds may take longer because the compiler is processing unnecessary header files. Include Cleanup helps you find and remove unused headers. For example, what if `myFunc()` is commented out in `myProgram.cpp`: + +```cpp +// myProgram.cpp +#include "myHeader.h" + +int main() +{ + std::string s = "main()"; // string is indirectly included from myHeader.h + std::cout << s; // cout is indirectly included from myHeader.h + // myFunc(); // directly included from myHeader.h +} +``` + +In the following screenshot, `#include "myHeader.h"` is dimmed (a setting described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md)) because it isn't used since `myFunc()` is commented out. + +Hover your cursor over the dimmed `#include` to bring up the quick action menu. Click the light bulb (or choose the **Show potential fixes** link) to see actions related to the unused file: + +:::image type="content" source="media/vs2022-include-cleanup-refactor-options.png" alt-text="Three refactoring options are shown: Remove # include myHeader.h, remove all unused includes, and Add all transitively used and remove all unused # includes."::: + +## Add transitively used headers + +We could choose to remove the unused header file, but that breaks the code since `` and `` are indirectly included via `myheader.h`. + +Instead, we can choose **Add all transitively used and remove all unused #includes**. This removes the unused header `myHeader.h`, but also adds any headers being used that are indirectly included via `myHeader.h`. The result, in this case, is adding `#include ` and `#include ` to `myProgram.cpp`, and removing `#include "myHeader.h"`: + +```cpp +// myProgram.cpp +#include +#include + +int main() +{ + std::string s = "main()"; // string is directly included from + std::cout << s; // cout is directly included from + // MyFunc(); +} +``` + +The tool doesn't update the comments, but you can see that the code is now using `std::string` and `std::cout` directly. This code is no longer brittle because it doesn't depend on `myHeader.h` to include the other required headers. + +## Best practice + +Don't remove what appear to be unused header files without first adding indirectly included header files. That's because your code may rely on indirect includes in a header file that is otherwise unused. Add transitively used headers first. Then, when you remove unused headers, you don't get compilation errors due to missing header files that are included indirectly by a header file you've removed. + +One way to do this is to set the Include Cleanup setting for **Add missing includes suggestion level** to **Suggestion** (**Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup**). Also set **Remove unused includes suggestion level** to **Suggestion**. Then: + +1. In the error list, make sure the filter is set to **Build + IntelliSense**. +1. Look for instances of "Content from #include x is used in this file and transitively included." +1. Hover your cursor over a line with the suggestion. From the light bulb dropdown, select **Add all transitively used includes**. +1. Repeat these steps in your project until all suggestions regarding transitive includes are addressed. +1. Remove unused includes: in the error list, look for an instance of "#include x is not used in this file." +1. Hover your cursor over the unused header. From the light bulb dropdown, select **Remove all unused includes**. +1. Repeat these steps in your project until all Include Cleanup suggestions are addressed. + +In this brief overview, you've seen how Include Cleanup can help you remove unused headers, and add headers that were indirectly included. This helps you keep your code clean, potentially build faster, and reduces the brittleness of your code. + +## See also + +[Configure C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md)\ +[Include Cleanup messages](include-cleanup-messages.md) \ No newline at end of file diff --git a/docs/ide/include-diagnostics.md b/docs/ide/include-diagnostics.md new file mode 100644 index 0000000000..c28d372ff2 --- /dev/null +++ b/docs/ide/include-diagnostics.md @@ -0,0 +1,106 @@ +--- +title: "C++ Include Diagnostics" +description: "Learn how to use #include Diagnostics in Visual Studio to analyze how often something from an include file is used and how an #include impacts build time." +ms.date: 10/10/2023 +ms.topic: "how-to" +f1_keywords: ["include diagnostics"] +helpviewer_keywords: ["include diagnostics"] +--- +# C++ Include Diagnostics in Visual Studio + +Starting with Visual Studio 17.8, Visual Studio helps you analyze your C++ `#include` files: + +- Displays how often, and where, something from each header file is used. +- Displays the build time for each `#include` file--which helps you identify opportunities to optimize your build time. + +## Enable C++ Include Diagnostics and CodeLens + +The C++ Include Diagnostics feature is off by default. To turn it on, right-click in the code editor to bring up the context menu, and choose **Include Directives** > **Turn #include Diagnostics On**. + +:::image type="complex" source="media/vs2022-enable-include-diagnostics.png" alt-text="A screenshot of the context menu that appears when you right-click in the code editor area."::: +The context menu shows the include directives option highlighted, which reveals two options: Sort # include directives and turn # include diagnostics on. +:::image-end::: + +Information about your `#include` files is displayed via CodeLens, which is off by default. To turn on the relevant CodeLens settings, navigate to **Tools** > **Options** > **Text Editor** > **All Languages** > **CodeLens** and confirm both **Show C++ #include references** and **Show C++ compilation times** are enabled. + +:::image type="complex" source="media/vs2022-enable-code-lens-for-includes.png" alt-text="A screenshot of the options window."::: +The options window is set to Text Editor > All Languages > CodeLens. The Show C++ # include references and Show C++ compilation times options are highlighted. +:::image-end::: + +## View `#include` references + +To try out Include Diagnostics, create a new C++ console project. Replace the contents of the main `.cpp` file with the following code: + +```cpp +#include +#include + +// a function that takes a vector of integers and prints them out +void print(std::vector &vec) +{ + for (int i : vec) + { + std::cout << i << std::endl; + } + std::cout << std::endl; +} + +// a function that takes a vector of integers and adds 10 to each element of the vector and store the result in a new vector +std::vector add10(std::vector& vec) +{ + std::vector newVec; + for (int i : vec) + { + newVec.push_back(i + 10); + } + return newVec; +} + +int main() +{ + std::vector vec = { 7, 5, 16, 8 }; + + print(vec); + auto newVec = add10(vec); + print(newVec); +} +``` + +When C++ Include Diagnostics are turned on, the number of times code from a header file is referenced in the current code file is displayed above the header file. It looks like this for the previous code sample: + +```cpp +6 references +#include +5 references +#include +``` + +In the code editor, select **5 references** above `#include ` and a summary of locations where code from `` is used in this file is displayed: + +:::image type="complex" source="media/visual-studio-2022-codelens-include-references.png" alt-text="A screenshot of the C++ Include Diagnostics context window showing where code from the vector header file is used."::: +The C++ Include Diagnostics context window shows that there are five places in the code where code from the vector header file is used in the current code file. For example, it's used twice on the definition of the add10 function, as a return value and parameter. It's used on line 17 in the declaration of newVec, and so on. +:::image-end::: + +Select an item to go to its location in your code. + +## View `#include` build time + +To see the build time for each file you `#include`, first build using Build Insights. + +Turn on Build Insights from the main menu bar by selecting **Build** > **Run Build Insights on Solution** > **Build**. After the build completes, a window appears to list the build times for the various files that are compiled. Return to the source code window, and the build time for each `#include` file is displayed in CodeLens. It looks similar to this: + +```cpp +6 references | Build: 0.3560s +#include +5 references | Build 0.0360s +#include +``` + +If you have an `#include` directive that is used infrequently, but significantly impacts your compile time, this tool can help you identify it. + +In this article, you've seen how to turn on C++ Include Diagnostics and CodeLens, and how to use C++ Include Diagnostics to analyze how often something from an include file is used and how an `#include` impacts build time. + +## See also + +[C/C++ Include Cleanup overview](include-cleanup-overview.md)\ +[Include Cleanup messages](include-cleanup-messages.md) \ No newline at end of file diff --git a/docs/ide/live-share-cpp.md b/docs/ide/live-share-cpp.md index ef99caa6b0..4a5fecdd50 100644 --- a/docs/ide/live-share-cpp.md +++ b/docs/ide/live-share-cpp.md @@ -7,13 +7,13 @@ ms.date: "05/24/2019" In Visual Studio 2019 and Visual Studio Code, you can use **Live Share** to collaborate on C++ projects in real-time. With **Live Share** another person can edit and debug your code without having to install your project or any of its dependencies. You see each other's edits as they occur, and each edit is tagged with the name of the person who made it. -![Screenshot of C plus plus Live Share Editing.](../ide/media/live-share-edit-cpp.png) +![Screenshot of C plus plus Live Share Editing. A change to the code specifying a color is highlighted and annotated with the name of the person making it.](../ide/media/live-share-edit-cpp.png) ## Live Share host and guests -In a Live Share session there is a host and one or more guests. Both host and guests can use either Visual Studio or Visual Studio Code. A Visual Studio 2019 host on Windows can share with a Visual Studio Code guest on Linux. +In a Live Share session, there's a host and one or more guests. Both host and guests can use either Visual Studio or Visual Studio Code. A Visual Studio 2019 host on Windows can share with a Visual Studio Code guest on Linux. -The host provides the guests with everything they need to be productive. Guests are not required to have the source code, compiler, external dependencies, or even the same installed components. +The host provides the guests with everything they need to be productive. Guests aren't required to have the source code, compiler, external dependencies, or even the same installed components. The host and guests can use these IntelliSense features: @@ -27,7 +27,7 @@ The host and guests can use these IntelliSense features: - Reference Highlighting - Diagnostics/Errors/Squiggles -![Screenshot of C plus plus Live Share Debugging.](../ide/media/live-share-debug-cpp.png) +![A side-by-side screenshot of a C plus plus Live Share Debugging intended to show two people seeing the debugging experience on their own screen.](../ide/media/live-share-debug-cpp.png) ## Start and end a Live Share session diff --git a/docs/ide/lnt-arithmetic-overflow.md b/docs/ide/lnt-arithmetic-overflow.md index 0025e19be1..c1719c26aa 100644 --- a/docs/ide/lnt-arithmetic-overflow.md +++ b/docs/ide/lnt-arithmetic-overflow.md @@ -17,6 +17,8 @@ The `lnt-arithmetic-overflow` check is controlled by the **Arithmetic Overflow** ## Examples ```cpp +#include + void overflow(int a, int b) { int64_t mul = a * b; // Flagged: 32-bit operation may overflow. int64_t shift = a << 34; // Flagged: Shift would overflow. diff --git a/docs/ide/lnt-comparison-bitwise-precedence.md b/docs/ide/lnt-comparison-bitwise-precedence.md index 7c6c07d630..cae1725fa2 100644 --- a/docs/ide/lnt-comparison-bitwise-precedence.md +++ b/docs/ide/lnt-comparison-bitwise-precedence.md @@ -1,7 +1,7 @@ --- title: lnt-comparison-bitwise-precedence description: "Reference for Visual Studio C++ IntelliSense Linter check lnt-comparison-bitwise-precedence." -ms.date: 09/29/2021 +ms.date: 06/29/2022 f1_keywords: ["lnt-comparison-bitwise-precedence"] helpviewer_keywords: ["lnt-comparison-bitwise-precedence"] monikerRange: ">=msvc-160" @@ -19,16 +19,18 @@ The `lnt-comparison-bitwise-precedence` check is controlled by the **Comparison/ ```cpp bool is_flag_set(unsigned value, unsigned flag) { - return value & flag == flag; // Flagged: `flag == flag` is evaluated first. + return value & flag == flag; // Flagged: `flag == flag` is evaluated first. // Then `value & (int)true` is evaluated which // returns an incorrect result in most cases. } ``` +Use parentheses to force the correct order of operations: + ```cpp bool is_flag_set(unsigned value, unsigned flag) { - return (value & flag) == flag; // Correct + return (value & flag) == flag; // Correct } ``` diff --git a/docs/ide/lnt-logical-bitwise-mismatch.md b/docs/ide/lnt-logical-bitwise-mismatch.md index 9104b18bf1..c501a731b4 100644 --- a/docs/ide/lnt-logical-bitwise-mismatch.md +++ b/docs/ide/lnt-logical-bitwise-mismatch.md @@ -23,7 +23,6 @@ void example(bool a, bool b) { bool c = a & b; // Flagged: Bitwise AND operator used with Boolean variables. bool d = a || b; // OK: Logical OR operator used with Boolean variables. } - ``` Only use bitwise operators on integer values. diff --git a/docs/ide/lnt-make-member-function-const.md b/docs/ide/lnt-make-member-function-const.md new file mode 100644 index 0000000000..1e3439c952 --- /dev/null +++ b/docs/ide/lnt-make-member-function-const.md @@ -0,0 +1,78 @@ +--- +title: lnt-make-member-function-const +description: "Reference for Visual Studio C++ IntelliSense Linter check lnt-make-member-function-const." +ms.date: 09/28/2023 +f1_keywords: ["lnt-make-member-function-const"] +helpviewer_keywords: ["lnt-make-member-function-const"] +monikerRange: ">=msvc-170" +--- +# `lnt-make-member-function-const` + +When a member function doesn't modify the object's state, annotate it with the `const` keyword. This guidance comes from [Con.2: By default, make member functions `const`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#con2-by-default-make-member-functions-const) in the C++ Core Guidelines. + +## Example + +The linter flags the following code twice because `getValue()` and `getRadius()` don't modify the object's state: + +```cpp +class MyClass +{ +public: + + int getValue() { return value; } // Flagged: 'getValue' doesn't modify the object's state. + void setValue(int newValue) { value = newValue; } // OK: 'setValue' modifies the object's state. + +private: + + int value = 42; +}; + +double getRadius() +{ // Flagged: 'getRadius' doesn't modify the object's state. + return radius; +} +``` + +## How to fix the issue + +Mark member functions `const` when they don't modify the object's state. This lets readers of the code and the compiler know that the function is safe to call on a `const` object. + +In the following example, `const` has been added to `getValue()` and `getRadius()`: + +```cpp +class MyClass +{ +public: + + int getValue() const { return value; } // Added const + void setValue(int newValue) { value = newValue; } // OK: 'setValue' modifies the object's state. + +private: + + int value = 42; + +}; + +double getRadius() const // added const +{ // 'getRadius' doesn't modify the object's state. + return radius; +} +``` + +The editor can make this change for you. Place the cursor on the flagged symbol and choose **Show potential fixes** and then **Make member const**: + +:::image type="complex" source="media/lnt-make-member-function-const.png" alt-text="Screenshot of the editor suggesting to make member const." ::: +The cursor is on the line int getValue() and **Show potential fixes** appeared and was chosen. Now **Make member const** is visible and it shows the get value function with const added to it. You can now choose **Make member const** to make the change. +:::image-end::: + +Make this change for all flagged member functions. + +## Remarks + +Introduced in Visual Studio 2022 17.8, this check focuses on `const` usage for member functions in C++ code. The C++ Core Guidelines recommends marking member functions as `const` when they don't modify the object's state. + +The current implementation of this check allows you to add `const` to member functions after their declaration. It's a good practice to declare member functions as `const` from the beginning if they don't modify the object's state. + +## See also + +[IntelliSense code linter for C++ overview](cpp-linter-overview.md) diff --git a/docs/ide/lnt-naming-convention.md b/docs/ide/lnt-naming-convention.md new file mode 100644 index 0000000000..d0a503be4b --- /dev/null +++ b/docs/ide/lnt-naming-convention.md @@ -0,0 +1,59 @@ +--- +title: lnt-naming-convention +description: "Reference for Visual Studio C++ IntelliSense Linter check lnt-naming-convention." +ms.date: 09/28/2023 +f1_keywords: ["lnt-naming-convention"] +helpviewer_keywords: ["lnt-naming-convention"] +monikerRange: ">=msvc-170" +--- +# `lnt-naming-convention` + +Ensure that the naming convention for symbols aligns with your coding style, as specified in the project's `.editorconfig` file. + +To enable this feature, add an `.editorconfig` file in the same directory as your project file. The `.editorconfig` specifies the naming conventions for symbols in your project. As an example, the naming conventions for Unreal Engine projects are specified in an `.editorconfig` on [GitHub](https://raw.githubusercontent.com/microsoft/vc-ue-extensions/main/Source/.editorconfig). + +Once you have the `.editorconfig` file in your project, turn on the `lnt-naming-convention` check with the **Naming Convention** setting in the C/C++ Code Style options. For information about how to change this setting, see [Configure the linter](cpp-linter-overview.md#configure-the-linter). + +## Example + +Suppose that you have an `.editorconfig` file that contains: + +``` +cpp_naming_style.boolean_style.capitalization = pascal_case +cpp_naming_style.boolean_style.required_prefix = b +``` + +The linter flags the following code because it isn't prefixed with 'b' and because it isn't Pascal case, as specified in the `.editorconfig` file: + +```cpp +void example() +{ + bool myFlag = true; // flagged because it doesn't follow the naming convention specified in the .editorconfig +} +``` + +## How to fix the issue + +Change the naming to match the style specified in the `.editorconfig`: + +```cpp +void example() +{ + bool bMyFlag = true; // fixed to follow the code style specified in the .editorconfig +} +``` + +The editor can make the change for you. Place the cursor on the flagged symbol. Choose **Show potential fixes** and then **Apply naming convention**: + +:::image type="complex" source="media/lnt-apply-naming-convention.png" alt-text="Screenshot of the IDE suggesting applying naming convention."::: +The code editor shows bool myFlag = true. With the cursor on that line of code, **Show potential fixes** appeared and was chosen. Now **Apply naming convention** is visible and it shows bool my Flag = true in red and the suggested change, bool b My Flag, in green. You can now choose **Apply naming convention** to change the flagged code to bool b My Flag = true. +:::image-end::: + +## Remarks + +Introduced in Visual Studio 2022 17.7, the `lnt-naming-convention` linter check ensures that naming conventions align with those specified in the `.editorconfig` file. You can apply this check to any project that has an `.editorconfig` file. You can also customize your `.editorconfig` file to suit your project's coding style. + +## See also + +[Create portable, custom editor settings with EditorConfig](/visualstudio/ide/create-portable-custom-editor-options)\ +[IntelliSense code linter for C++ overview](cpp-linter-overview.md) \ No newline at end of file diff --git a/docs/ide/lnt-uninitialized-local.md b/docs/ide/lnt-uninitialized-local.md index 44466eb134..1be51a46df 100644 --- a/docs/ide/lnt-uninitialized-local.md +++ b/docs/ide/lnt-uninitialized-local.md @@ -10,7 +10,7 @@ monikerRange: ">=msvc-160" Local variables should be initialized when they're declared. -This guidance comes from the [C++ Core Guideline ES.20](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es20-always-initialize-an-object). +This guidance comes from [ES.20: Always initialize an object](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es20-always-initialize-an-object) in the C++ Core Guidelines. The `lnt-uninitialized-local` check is controlled by the **Uninitialized Local Variable** setting in the C/C++ Code Style options. For information on how to change this setting, see [Configure the linter](cpp-linter-overview.md#configure-the-linter). @@ -25,7 +25,7 @@ void example() { std::string s; // OK: The type is default initialized. int j; // OK: The local is immediately assigned after declaration. - j = 0; // This is allowed as as a slight relaxation of the C++ Core Guideline. + j = 0; // This is allowed as a slight relaxation of the C++ Core Guideline. } ``` @@ -55,5 +55,5 @@ Using "Almost Always Auto" for declarations requires initialization at declarati ## See also [IntelliSense code linter for C++ overview](cpp-linter-overview.md)\ -[C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es20-always-initialize-an-object)\ +[ES.20: Always initialize an object](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es20-always-initialize-an-object)\ [Almost Always Auto - Herb Sutter](https://herbsutter.com/2013/08/12/gotw-94-solution-aaa-style-almost-always-auto/) diff --git a/docs/ide/media/add-interface-definition-library-method-wizard.png b/docs/ide/media/add-interface-definition-library-method-wizard.png new file mode 100644 index 0000000000..a4f0a75033 Binary files /dev/null and b/docs/ide/media/add-interface-definition-library-method-wizard.png differ diff --git a/docs/ide/media/add-interface-definition-library-property-wizard.png b/docs/ide/media/add-interface-definition-library-property-wizard.png new file mode 100644 index 0000000000..14917ae0b5 Binary files /dev/null and b/docs/ide/media/add-interface-definition-library-property-wizard.png differ diff --git a/docs/ide/media/add-method-wizard.png b/docs/ide/media/add-method-wizard.png new file mode 100644 index 0000000000..94c92c3e28 Binary files /dev/null and b/docs/ide/media/add-method-wizard.png differ diff --git a/docs/ide/media/add-mfc-class-from-activex-control.png b/docs/ide/media/add-mfc-class-from-activex-control.png new file mode 100644 index 0000000000..1e0e77c2af Binary files /dev/null and b/docs/ide/media/add-mfc-class-from-activex-control.png differ diff --git a/docs/ide/media/add-property-wizard.png b/docs/ide/media/add-property-wizard.png new file mode 100644 index 0000000000..7c551672d1 Binary files /dev/null and b/docs/ide/media/add-property-wizard.png differ diff --git a/docs/ide/media/include-cleanup-dimmed-include.png b/docs/ide/media/include-cleanup-dimmed-include.png new file mode 100644 index 0000000000..c2f9f6381a Binary files /dev/null and b/docs/ide/media/include-cleanup-dimmed-include.png differ diff --git a/docs/ide/media/include-cleanup-error-list.png b/docs/ide/media/include-cleanup-error-list.png new file mode 100644 index 0000000000..0d6eeba3ad Binary files /dev/null and b/docs/ide/media/include-cleanup-error-list.png differ diff --git a/docs/ide/media/include-cleanup-refactor-lightbulb.png b/docs/ide/media/include-cleanup-refactor-lightbulb.png new file mode 100644 index 0000000000..9a5aff92ce Binary files /dev/null and b/docs/ide/media/include-cleanup-refactor-lightbulb.png differ diff --git a/docs/ide/media/linter-settings.png b/docs/ide/media/linter-settings.png index b5499ae2f8..775d8730a7 100644 Binary files a/docs/ide/media/linter-settings.png and b/docs/ide/media/linter-settings.png differ diff --git a/docs/ide/media/lnt-apply-naming-convention.png b/docs/ide/media/lnt-apply-naming-convention.png new file mode 100644 index 0000000000..607e6579cf Binary files /dev/null and b/docs/ide/media/lnt-apply-naming-convention.png differ diff --git a/docs/ide/media/lnt-make-member-function-const.png b/docs/ide/media/lnt-make-member-function-const.png new file mode 100644 index 0000000000..5a0f2426a2 Binary files /dev/null and b/docs/ide/media/lnt-make-member-function-const.png differ diff --git a/docs/ide/media/visual-studio-2022-codelens-include-references.png b/docs/ide/media/visual-studio-2022-codelens-include-references.png new file mode 100644 index 0000000000..f024ebba6e Binary files /dev/null and b/docs/ide/media/visual-studio-2022-codelens-include-references.png differ diff --git a/docs/ide/media/visual-studio-2022-hover-macro.png b/docs/ide/media/visual-studio-2022-hover-macro.png new file mode 100644 index 0000000000..ed1386ec93 Binary files /dev/null and b/docs/ide/media/visual-studio-2022-hover-macro.png differ diff --git a/docs/ide/media/visual-studio-2022-work-macro-expansion.png b/docs/ide/media/visual-studio-2022-work-macro-expansion.png new file mode 100644 index 0000000000..2f6a11030b Binary files /dev/null and b/docs/ide/media/visual-studio-2022-work-macro-expansion.png differ diff --git a/docs/ide/media/vs2022-enable-code-lens-for-includes.png b/docs/ide/media/vs2022-enable-code-lens-for-includes.png new file mode 100644 index 0000000000..34c864afe3 Binary files /dev/null and b/docs/ide/media/vs2022-enable-code-lens-for-includes.png differ diff --git a/docs/ide/media/vs2022-enable-include-diagnostics.png b/docs/ide/media/vs2022-enable-include-diagnostics.png new file mode 100644 index 0000000000..cb77d384a5 Binary files /dev/null and b/docs/ide/media/vs2022-enable-include-diagnostics.png differ diff --git a/docs/ide/media/vs2022-include-cleanup-option.png b/docs/ide/media/vs2022-include-cleanup-option.png new file mode 100644 index 0000000000..2cbdb0d3aa Binary files /dev/null and b/docs/ide/media/vs2022-include-cleanup-option.png differ diff --git a/docs/ide/media/vs2022-include-cleanup-refactor-options.png b/docs/ide/media/vs2022-include-cleanup-refactor-options.png new file mode 100644 index 0000000000..57dfd9200a Binary files /dev/null and b/docs/ide/media/vs2022-include-cleanup-refactor-options.png differ diff --git a/docs/ide/navigate-code-cpp.md b/docs/ide/navigate-code-cpp.md index 85284c9080..4838fd2057 100644 --- a/docs/ide/navigate-code-cpp.md +++ b/docs/ide/navigate-code-cpp.md @@ -11,7 +11,7 @@ Visual Studio provides a suite of tools that you can use to navigate around your Right-click an `#include` directive, and select **Go To Document**. Or, select **F12** with the cursor over that line to open the file. -![Screenshot of the C plus plus Go To Document menu option.](../ide/media/go-to-document.png) +![Screenshot of the C plus plus Go To Document menu option in the context of some include statements.](media/go-to-document.png) ## Toggle Header/Code File @@ -19,17 +19,17 @@ You can switch between a header file and its corresponding source file. Right-cl ## Go To Definition/Declaration -You can navigate to the definition of a code symbol by right-clicking it in the editor and selecting **Go To Definition**, or by selecting **F12**. You can navigate to a declaration similarly by right-clicking to open the context menu, or by selecting **Ctrl+F12**. +You can navigate to the definition of a code element with a right-click in the editor and selecting **Go To Definition**, or by selecting **F12**. You can navigate to a declaration similarly by right-clicking to open the context menu, or by selecting **Ctrl+F12**. -![Screenshot of C plus plus Go To Definition.](../ide/media/go-to-def.png) +![Screenshot of options that appear when you right-click a code element. Includes Go To Definition, Peek Definition, and Go To Declaration.](media/go-to-def.png) ## Go To -**Go To** refers to a set of navigation features that each provide a specific kind of result based on filters you specify. +**Go To** refers to a set of navigation features that each provide a specific result based on filters you specify. You can open **Go To** with **Ctrl+,**. This action creates a search box over the document you're editing. -![Screenshot of C plus plus Go To.](../ide/media/go-to-cpp.png) +![Screenshot of the search box that appears when you open Go To. There's a text box for your search terms, and filters for types, recent files, etc.](media/go-to-cpp.png) **Go To** includes these search filters: @@ -47,7 +47,7 @@ You can open **Go To** with **Ctrl+,**. This action creates a search box over th - Properties and events. - **Go To Symbol** (**Ctrl 1, S**): Search results include: - Results from Go To Types and Go To Members. - - All remaining C++ language constructs, which includes macros. + - All remaining C++ language constructs, which include macros. When you first invoke **Go To** with **Ctrl +**, **Go To All** is activated (no filters on search results). You then can select the filter you want by using the buttons near the search box. You can invoke a specific filter using its corresponding keyboard shortcut. Doing so opens the **Go To** search box with that filter preselected. All keyboard shortcuts are configurable. @@ -62,11 +62,11 @@ To apply a text filter, start your search query with the filter's corresponding The following example shows results from a *Go To Files* operation by using the "f" filter: -![Screenshot of the Go to Files menu.](../ide/media/vs2017-go-to-results.png "Go To Menu") +![Screenshot of Go to Files results. The user typed 'f str' and string_utils.cpp and string_utils.h appear because they contain `str` in the name.](media/vs2017-go-to-results.png "Go To Menu") To see the list of text filters, type a ? followed by a space. You also can access the **Go To** commands with the **Edit** menu. This is another way to remind yourself of the main **Go To** keyboard shortcuts. -![Screenshot of the Go To menu.](../ide/media/go-to-menu-cpp.png "Go To Menu") +![Screenshot of the Go To menu which has options like Go To Line (Ctrl + G), Go to File (Ctrl + 1, Ctrl + F), and more.](media/go-to-menu-cpp.png "Go To Menu") ## Find or Find in Files @@ -74,15 +74,15 @@ You can run a text search for anything in your solution with **Find** (**Ctrl+F* **Find** can be scoped to a selection, the current document, all open documents, the current project, or the entire solution. You can use regular expressions and plain text. It also highlights all matches automatically in the IDE. -![Screenshot of C plus plus Find.](../ide/media/find-cpp.png) +![Screenshot of the Find dialog. The user has searched `channel`. Yellow highlights in the file show all the places `Channel` is found.](media/find-cpp.png) **Find in Files** is a more powerful version of **Find** that displays results in the **Find Results** window. You can search external code dependencies, filter by file types, and more. -![Screenshot of the Find and Replace window showing the Find in Files page.](../ide/media/find-in-files-cpp.png "Find in Files") +![Screenshot of the Find and Replace dialog. The Find in Files page is selected. Options are shown for matching case, the whole word, and so on.](media/find-in-files-cpp.png "Find in Files") You can organize **Find in Files** results in two windows. You can append results from multiple searches together. Select a result to go to that location in the file. -![Screenshot showing a Find in File search result.](../ide/media/vs2017-find-in-files-results.png "Find in Files") +![Screenshot showing a Find in Files search result listing files containing text that matches the search string and an excerpt of each match.](media/vs2017-find-in-files-results.png "Find in Files") For more information, see [Find in Files](/visualstudio/ide/find-in-files) in the Visual Studio documentation. @@ -90,9 +90,9 @@ For more information, see [Find in Files](/visualstudio/ide/find-in-files) in th To find all usages of a symbol in your codebase, place the caret in or just after the symbol, right-click, and then select **Find All References**. You can filter, sort, or group results in many different ways. Results populate incrementally. They're classified as Reads or Writes to help you see what's in your solution as opposed to system headers or other libraries. -![Screenshot of C plus plus Find all references.](../ide/media/find-all-references-results-cpp.png) +![Screenshot of Find all references results which shows the line where the symbol was found, which file and project it is located in, and so on.](media/find-all-references-results-cpp.png) -You group results by the following categories: +You can group results by the following categories: - Project then Definition - Definition Only @@ -104,13 +104,13 @@ You group results by the following categories: To filter results, hover over a column and select the filtering icon that pops up. You can filter results from the first column to hide things like string and comment references that you might not want to see. -![Screenshot of C plus plus Find all references filters.](../ide/media/find-all-references-filters-cpp.png) +![Screenshot of filtering options. Includes Confirmed, Disconfirmed, In comment, and unprocessed. Each shows how many results apply to that category.](media/find-all-references-filters-cpp.png) - **Confirmed results**: Actual code references to the symbol being searched for. For example, searching for a member function called `Size` returns all references to `Size` that match the scope of the class that defines `Size`. - **Disconfirmed results**: This filter is off by default because it shows symbols whose name matches but aren't actual references to the symbol you're searching for. For example, if you have two classes that each define a member function called `Size`, and you run a search for `Size` on a reference from an object of `Class1`, any references to `Size` from `Class2` appear as disconfirmed. -- **Unprocessed results**: **Find All References** operations can take time to complete on larger codebases, so the Results list shows "unprocessed" results here. Unprocessed results match the name of the symbol being searched for but haven't yet been confirmed as actual code references. You can turn on this filter to get faster results. Just be aware that some results might not be actual references. +- **Unprocessed results**: **Find All References** operations can take time to complete on larger codebases, so the Results list shows "unprocessed" results here. Unprocessed results match the name of the symbol being searched for but haven't yet been confirmed as actual code references. You can turn on this filter to get faster results. Some results might not be actual references. #### Sort results @@ -120,10 +120,10 @@ You can sort results by any column by selecting that column. You can swap betwee You can navigate to the definition of a type in a file, or to type members, by using the **Navigation Bar** that's above the editor window. -![Screenshot of the C plus plus Navigation Bar.](../ide/media/navbar-cpp.png) +![Screenshot of the Navigation Bar above the editor window. It shows cryptlib > ChannelSwitch > ChannelMessageSeriesEnd().](media/navbar-cpp.png) ## See also -- [Read and understand C++ code](read-and-understand-code-cpp.md)
-- [Edit and refactor C++ code](read-and-understand-code-cpp.md)
+- [Read and understand C++ code](read-and-understand-code-cpp.md) +- [Edit and refactor C++ code](read-and-understand-code-cpp.md) - [Collaborate with Live Share for C++](live-share-cpp.md) diff --git a/docs/ide/read-and-understand-code-cpp.md b/docs/ide/read-and-understand-code-cpp.md index cdc0bd5c7e..e98759ba67 100644 --- a/docs/ide/read-and-understand-code-cpp.md +++ b/docs/ide/read-and-understand-code-cpp.md @@ -1,7 +1,7 @@ --- title: "Read and understand C++ code in Visual Studio" description: "Use the C++ code editor in Visual Studio to format, and understand your code." -ms.date: "05/28/2019" +ms.date: 05/28/2019 --- # Read and understand C++ code in Visual Studio @@ -11,19 +11,19 @@ The C++ code editor and Visual Studio IDE provide many coding aids. Some are uni Visual Studio colorizes syntax elements to differentiate between types of symbols such as language keywords, type names, variable names, function parameters, string literals, and so on. -![Screenshot showing code colorization in the editor.](../ide/media/code-outline-colorization.png "C++ colorization") +![Screenshot showing code colorization in the editor. Keywords are shown in different colors such as blue for if, while and green for comments](../ide/media/code-outline-colorization.png "C++ colorization") Unused code (such as code under an #if 0) is more faded in color. -![Screenshot showing inactive code in the editor.](../ide/media/inactive-code-cpp.png "C++ inactive code") +![Screenshot showing inactive code in the editor, which appears faded compared to active code.](../ide/media/inactive-code-cpp.png "C++ inactive code") -You can customize the colors by typing "Fonts" in **Quick Launch**, and then choosing **Fonts and Colors**. In the **Fonts and Colors** dialog scroll down to the C/C++ options and then choose a custom font and/or color. +You can customize the colors by typing "Fonts" in **Quick Launch**, and then choosing **Fonts and Colors**. In the **Fonts and Colors** dialog, scroll down to the C/C++ options and then choose a custom font and/or color. ## Outlining -Right-click anywhere in a source code file and choose **Outlining** to collapse or expand code blocks and/or custom regions to make it easier to browse only the code you are interested in. For more information, see [Outlining](/visualstudio/ide/outlining). +Right-click anywhere in a source code file and choose **Outlining** to collapse or expand code blocks and/or custom regions to make it easier to browse only the code you're interested in. For more information, see [Outlining](/visualstudio/ide/outlining). -![Screenshot of C plus plus Outlining.](../ide/media/vs2015_cpp_outlining.png) +![Screenshot of the outlining window shows the body of classes collapsed. Options for Collapse to Definitions, Toggle All Outlining, etc. are visible.](../ide/media/vs2015_cpp_outlining.png) When you place your cursor in front of a curly brace, '{' or '}', the editor highlights its matching counterpart. @@ -37,11 +37,11 @@ You can add line numbers to your project by going to **Tools** > **Options** > * You can zoom in or out in the editor by pressing the **Ctrl** key and scrolling with your mouse wheel. You can also zoom by using the zoom setting in the bottom left corner. -![Screenshot of the C plus plus Zoom Control.](../ide/media/zoom-control.png) +![Screenshot of the Zoom Control in the lower left of the screen. It's a dropdown with various zoom options like 133%.](../ide/media/zoom-control.png) Scrollbar **Map Mode** enables you to quickly scroll and browse through a code file without leaving your current location. You can click anywhere on the code map to go directly to that location. -![Screenshot of the Code Map in C plus plus.](../ide/media/vs2015-cpp-code-map.png) +![Screenshot of the Code Map which shows an outline of the entire file on the right and a window displaying the code from the selected part of the map.](../ide/media/vs2015-cpp-code-map.png) To turn on **Map Mode**, type "map" in the **Quick Launch** search box in the main toolbar and choose **Use scroll map mode**. For more information, see [How to: Track your code by customizing the scrollbar](/visualstudio/ide/how-to-track-your-code-by-customizing-the-scrollbar). @@ -53,13 +53,13 @@ Hover over any variable, function, or other symbol to get information about it, ::: moniker range=">=msvc-160" -![Screenshot showing the Quick Info tooltip in Visual Studio 2019.](../ide/media/quick-info-vs2019.png "Quick Info") +![Screenshot of the Quick Info tooltip displaying the definition of a function that the user is hovering over in the code window.](../ide/media/quick-info-vs2019.png "Quick Info") The **Quick Info** tooltip has a **Search Online** link. Go to **Tools** > **Options** > **Text Editor** > **C++** > **View** to specify the search provider. -If there is an error in your code, you can hover over it and **Quick Info** will display the error message. You can also find the error message in the Error List window. +If there's an error in your code, you can hover over it, and **Quick Info** will display the error message. You can also find the error message in the Error List window. -![Screenshot showing Quick Info on error.](../ide/media/quickinfo-on-error.png "Quick Info on error") +![Screenshot of the Quick Info tooltip showing the error associated with a code squiggle.](../ide/media/quickinfo-on-error.png "Quick Info on error") ::: moniker-end @@ -67,43 +67,43 @@ If there is an error in your code, you can hover over it and **Quick Info** will ![Screenshot showing the Quick Info tooltip in Visual Studio 2017.](../ide/media/quick-info.png "Quick Info") -If there is an error in your code, you can hover over it and **Quick Info** will display the error message. You can also find the error message in the **Error List** window. +If there's an error in your code, you can hover over it, and **Quick Info** will display the error message. You can also find the error message in the **Error List** window. -![Screenshot showing Quick Info on error.](../ide/media/quickinfo-on-error.png "Quick Info on error") +![Screenshot of the Quick Info tooltip showing the error associated with a code squiggle.](../ide/media/quickinfo-on-error.png "Quick Info on error") ::: moniker-end -When you call a function, **Parameter Info** shows the types of parameters and the order in which they are expected. +When you call a function, **Parameter Info** shows the types of parameters and the order in which they're expected. -![Screenshot of Parameter Info in C plus plus.](../ide/media/parameter-info.png) +![Screenshot of parameter info showing the parameters for the function resize on vector v. The parameter info is: const size_t _Newsize, const int & _Val.](../ide/media/parameter-info.png) ## Peek Definition Hover over a variable or function declaration, right-click, then choose **Peek Definition** to see an inline view of its definition without navigating away from your current location. For more information, see [Peek Definition (Alt+F12)](/visualstudio/ide/how-to-view-and-edit-code-by-using-peek-definition-alt-plus-f12). -![Screenshot of C plus plus Peek Definition.](../ide/media/vs2015_cpp_peek_definition.png) +![Screenshot of the drop-down that appears when you right-click a function. Peek Definition appears in the menu along with the shortcut Alt + F 12.](../ide/media/vs2015_cpp_peek_definition.png) ## F1 Help -Place the cursor on or just after any type, keyword or function and press **F1** to go directly to the relevant reference topic on docs.microsoft.com. **F1** also works on items in the error list, and in many dialog boxes. +Place the cursor on or just after any type, keyword or function and press **F1** to go directly to the relevant reference topic on Microsoft Learn. **F1** also works on items in the error list and in many dialog boxes. ## Class View **Class View** displays a searchable set of trees of all code symbols and their scope and parent/child hierarchies, organized on a per-project basis. You can configure what **Class View** displays from **Class View Settings** (click the gear box icon at the top of the window). -![Screenshot of Class View in C plus plus.](../ide/media/class-view.png) +![Screenshot of the Class View window displaying the classes in the project such as CipherFactory, FilterTester, and so on.](../ide/media/class-view.png) ## Generate graph of include files Right click on a code file in your project and choose **Generate graph of include files** to see a graph of which files are included by other files. -![Screenshot of C plus plus graph of include files.](../ide/media/vs2015_cpp_include_graph.png) +![Screenshot of a graph of include files. The graph shows that NAMESPACE DLL .CPP includes Namespace DLL .h, which includes V_10 .H, among other files.](../ide/media/vs2015_cpp_include_graph.png) ## View Call Hierarchy Right click on any function call and view a recursive list of all the functions that it calls, and all the functions that call it. Each function in the list can be expanded in the same way. For more information, see [Call Hierarchy](/visualstudio/ide/reference/call-hierarchy). -![Screenshot of C plus plus Call Hierarchy.](../ide/media/vs2015_cpp_call_hierarchy.png) +![Screenshot of the Call Hierarchy window which shows calls to and from Floating_to_wstring(). For example, to_wstring() calls Floating_to_wstring().](../ide/media/vs2015_cpp_call_hierarchy.png) ## See Also diff --git a/docs/ide/refactoring/change-signature.md b/docs/ide/refactoring/change-signature.md index c6ca40fa16..e8b15f9005 100644 --- a/docs/ide/refactoring/change-signature.md +++ b/docs/ide/refactoring/change-signature.md @@ -1,14 +1,14 @@ --- description: "Learn more about: Change Signature" title: "Change Signature" -ms.date: "11/16/2016" -ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 +ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.changesignaturedlg"] --- # Change Signature **What:** Lets you modify a function's parameters. -**When:** You want to re-order, add, remove, or modify a function's parameters that is currently being used in a variety of locations. +**When:** You want to reorder, add, remove, or modify a function's parameters that are used in various locations. **Why:** You could manually change these parameters yourself, and then find all calls to that function and change them one-by-one, but that could lead to errors. This refactoring tool will perform the task automatically. @@ -16,11 +16,11 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 1. Place the text or mouse cursor inside the name of the method to modify, or one of its usages: - ![Screenshot showing highlighted code.](images/changesignature_highlight.png) + ![Screenshot of code with the mouse cursor on the function ChangeUserInfo.](images/changesignature_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+O**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+O**. (Your keyboard shortcut may be different depending on which profile you've selected.) * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Change Signature** from the context menu. * **Mouse** * Select **Edit > Refactor > Reorder Parameters**. @@ -28,23 +28,23 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 1. In the **Change Signature** dialog that pops up, you can use the buttons on the right side to change the method signature: - ![Screenshot showing the Change Signature dialog.](images/changesignature_dialog.png) + ![Screenshot of the Change Signature dialog for the ChangeName() function. Parameters are listed by name, type, and associated value, if any.](images/changesignature_dialog.png) | Button | Description | ------ | --- | **Up/Down** | Move the selected parameter up and down the list | **Add** | Add a new parameter to the list | **Remove** | Remove the selected parameter from the list - | **Modify** | Modify the selected parameter by changing its type, name, and whether it is optional, and what its injected value would be + | **Modify** | Modify the selected parameter by changing its type, name, and whether it's optional, and what its injected value would be | **Revert** | Restore the selected parameter its original state | **Revert All** | Restore all parameters to their original state > [!TIP] > Use the **Skip preview reference changes if all references are confirmed** checkbox to make the changes immediately without the preview window popping up first. - When adding or modifying a parameter, you will see the **Add Parameter** or **Edit Parameter** window. + When adding or modifying a parameter, you'll see the **Add Parameter** or **Edit Parameter** window. - ![Screenshot showing the Add Modify parameter.](images/changesignature_addmodify.png) + ![Screenshot of the Add parameter window where you can edit or set a parameter's type, name, and whether its default or optional.](images/changesignature_addmodify.png) Here, you can do the following: @@ -52,16 +52,16 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 | ----- | --- | **Type** | The type of the parameter (int, double, float, etc.) | **Name** | The name of the parameter - | **Optional Parameter** | Makes the parameter optionally specified + | **Optional Parameter** | Make the parameter optionally specified | **Injected Value** | The value inserted into any calls to the function where the parameter isn't specified (only valid for **Add**) | **Default value** | The value used by the function if the caller doesn't specify one (only valid for **Optional Parameters**) -1. Use the **Search scope** drop down to select if the changes will apply to the project or the entire solution. +1. Use the **Search scope** drop-down to select if the changes will apply to the project or the entire solution. -1. When you are finished, press the **OK** button to make the changes. Ensure that the changes you are requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. +1. When you're finished, press the **OK** button to make the changes. Ensure that the changes you're requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. - ![Screenshot showing the Change Signature preview.](images/changesignature_preview.png) + ![Screenshot of a Change Signature preview. Everywhere the function is called is previewed so you can verify each change.](images/changesignature_preview.png) -1. When everything looks good, click the **Apply** button and the function will be changed in your source code. +1. When everything looks good, click the **Apply** button, and the function will be changed in your source code. - ![Screenshot showing the Change Signature result.](images/changesignature_result.png) + ![Screenshot of the resulting change. The parameters to ChangeUserInfo() are now: std::string lastName, std::string firstname, int age = -1).](images/changesignature_result.png) diff --git a/docs/ide/refactoring/convert-to-raw-string-literal.md b/docs/ide/refactoring/convert-to-raw-string-literal.md index ea55cc97fa..4657d34f5d 100644 --- a/docs/ide/refactoring/convert-to-raw-string-literal.md +++ b/docs/ide/refactoring/convert-to-raw-string-literal.md @@ -1,30 +1,29 @@ --- description: "Learn more about: Convert to Raw String Literal" title: "Convert to Raw String Literal" -ms.date: "11/16/2016" -ms.assetid: fffbfee4-66ee-42ba-aeb9-df07fb702c51 +ms.date: "09/19/2022" --- # Convert to Raw String Literal -**What:** Lets you turn any string into a C++ raw string literal. +**What:** Turn any string into a C++ raw string literal. -**When:** You have a string with escaped characters which shouldn't be processed as escaped characters. +**When:** You have a string with escaped characters, which shouldn't be processed as escaped characters. -**Why:** You could double-escape characters, but this often leads to confusing and unreadable strings. Using raw string literals makes strings much easier to read. +**Why:** You could double-escape characters, but this often leads to confusing and strings. Raw string literals make strings much easier to read. **How:** 1. Place text or mouse cursor over the escaped string to convert. - ![Screenshot showing highlighted code.](images/stringliteral_highlight.png) + ![Screenshot of the cursor in the middle of the word quoted on the line of code that reads: auto MyString = "A \"quoted\" string".](images/stringliteral_highlight.png) 1. Next, do one of the following: * **Keyboard** * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Convert to Raw String Literal** from the context menu. * **Mouse** * Right-click the code, select the **Quick Actions and Refactorings** menu and select **Convert to Raw String Literal** from the context menu. - * Click the ![Lightbulb.](images/bulb.png) icon which appears in the left margin and select **Convert to Raw String Literal** from the context menu. + * Click the ![Lightbulb.](images/bulb.png) icon that appears in the left margin and select **Convert to Raw String Literal** from the context menu. 1. The string will be immediately converted into a raw string literal. - ![Raw String Literal result.](images/stringliteral_result.png) + ![Screenshot showing that the line of code now reads: auto myString = R"(A "quoted" string.)" The interior quotes are no longer escaped.](images/stringliteral_result.png) diff --git a/docs/ide/refactoring/create-declaration-definition.md b/docs/ide/refactoring/create-declaration-definition.md index ce0b0e4043..0fe31ad574 100644 --- a/docs/ide/refactoring/create-declaration-definition.md +++ b/docs/ide/refactoring/create-declaration-definition.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Create Declaration / Definition" title: "Create Declaration / Definition" -ms.date: "10/19/2018" -ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba +ms.date: "09/19/2022" --- # Create Declaration / Definition @@ -10,13 +9,13 @@ ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba **When:** You have a function that needs a declaration, or vice-versa. -**Why:** You could manually create the declaration/definition, but this will create it automatically, creating the header/code file if required. +**Why:** You could manually create the declaration/definition, but this will create it automatically, creating the header/code file if necessary. **How:** 1. Place your text or mouse cursor over the function for which you want to create the declaration or definition. - ![Screenshot showing highlighted code.](images/createdefinition_highlight.png) + ![Screenshot showing the code: void MyFunction(int x). The cursor is on MyFunction.](images/createdefinition_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -24,6 +23,6 @@ ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba * **Mouse** * Right-click and select the **Quick Actions and Refactorings** menu and select **Create Declaration / Definition** from the context menu. -1. The function's declaration/definition will be created in the source or header file, which you will see in a popup preview window. If the source or header file does not exist, it will also be created and placed in the project. +1. The function's declaration/definition will be created in the source or header file, which you'll see in a popup preview window. If the source or header file doesn't exist, it will also be created and placed in the project. - ![Create Declaration / Definition result.](images/createdefinition_result.png) + ![Screenshot showing a popup window containing the header file Source.h with the created declaration: void MyFunction(int x);.](images/createdefinition_result.png) diff --git a/docs/ide/refactoring/extract-function.md b/docs/ide/refactoring/extract-function.md index 6dd777335f..91a9fc7d79 100644 --- a/docs/ide/refactoring/extract-function.md +++ b/docs/ide/refactoring/extract-function.md @@ -1,36 +1,36 @@ --- description: "Learn more about: Extract Function" title: "Extract Function" -ms.date: "11/16/2016" -ms.assetid: e31d1249-9705-4511-acbd-9f6fe73bdf2d +ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.extractfuncdlg"] --- # Extract Function -**What:** Lets you turn a fragment of code into its own function. +**What:** Turn a fragment of code into its own function. **When:** You have a fragment of existing code in some function that needs to be called from another function. -**Why:** You could copy/paste that code, but that would lead to duplication. A better solution is to refactor that fragment into its own function which can be called freely by any other function. +**Why:** You could copy/paste that code, but that would lead to duplication. A better solution is to refactor that fragment into its own function, which can be called by any other function. **How:** 1. Highlight the code to be extracted: - ![Screenshot showing highlighted code.](images/extractfunction_highlight.png) + ![Screenshot showing the following code that is highlighted prepartory to being extracted: double area = M_PI * readious * radious;.](images/extractfunction_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+M**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+M**. (Your keyboard shortcut may be different depending on which profile you've selected.) * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Extract Function (Experimental)** from the context menu. * **Mouse** * Select **Edit > Refactor > Extract Function (Experimental)**. * Right-click the code, select the **Quick Actions and Refactorings** menu and select **Extract Function (Experimental)** from the context menu. - * Click the ![Lightbulb.](images/bulb.png) icon which appears in the left margin and select **Extract Function (Experimental)** from the context menu. + * Click the ![Lightbulb.](images/bulb.png) icon that appears in the left margin and select **Extract Function (Experimental)** from the context menu. 1. In the **Extract Function/Method (Experimental)** window, enter the new function name, select where you want the code to be placed, and click the **OK** button. - ![Extract function dialog.](images/extractfunction_dialog.png) + ![Screenshot of the extract function dialog which takes the function name and whether to create it above or below the current function.](images/extractfunction_dialog.png) 1. The new function will be created where you specified, a function prototype in the corresponding header file, and the original code will be changed to call that function. - ![Extract function result.](images/extractfunction_result.png) + ![Screenshot of the created function that contains the extracted code. The definition is void CalculateArea(double radius).](images/extractfunction_result.png) diff --git a/docs/ide/refactoring/images/changesignature_dialog.png b/docs/ide/refactoring/images/changesignature_dialog.png index c90b13a54e..c4d48f3877 100644 Binary files a/docs/ide/refactoring/images/changesignature_dialog.png and b/docs/ide/refactoring/images/changesignature_dialog.png differ diff --git a/docs/ide/refactoring/images/extractfunction_dialog.png b/docs/ide/refactoring/images/extractfunction_dialog.png index 99a47848a5..72a8235aaa 100644 Binary files a/docs/ide/refactoring/images/extractfunction_dialog.png and b/docs/ide/refactoring/images/extractfunction_dialog.png differ diff --git a/docs/ide/refactoring/implement-pure-virtuals.md b/docs/ide/refactoring/implement-pure-virtuals.md index de4fdbfe6b..5ee582745a 100644 --- a/docs/ide/refactoring/implement-pure-virtuals.md +++ b/docs/ide/refactoring/implement-pure-virtuals.md @@ -1,12 +1,11 @@ --- description: "Learn more about: Implement Pure Virtuals" title: "Implement Pure Virtuals" -ms.date: "11/16/2016" -ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 +ms.date: "09/19/2022" --- # Implement Pure Virtuals -**What:** Lets you immediately generate the code required to implement all pure virtual methods in a class. +**What:** Generate the code required to implement all pure virtual methods in a class. **When:** You want to inherit from a class with pure virtual functions. @@ -16,7 +15,7 @@ ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 1. Place your text or mouse cursor over the class in which you want to implement the pure virtual functions of the base class. - ![Screenshot showing highlighted code.](images/virtuals_highlight.png) + ![Screenshot of a class that has two pure virtual functions named Method1 and Method2. An empty class named MyInheritedClass derives from it.](images/virtuals_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -26,4 +25,4 @@ ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 1. The pure virtual method signatures will be created automatically, ready to be implemented. - ![Implement Pure Virtuals result.](images/virtuals_result.png) + ![Screenshot of MyInheritedClass which now has 2 virtual method definitions that match the names and signatures of the declarations in the base class.](images/virtuals_result.png) diff --git a/docs/ide/refactoring/move-definition-location.md b/docs/ide/refactoring/move-definition-location.md index 2336e86efd..5ee8c82f8b 100644 --- a/docs/ide/refactoring/move-definition-location.md +++ b/docs/ide/refactoring/move-definition-location.md @@ -1,22 +1,21 @@ --- description: "Learn more about: Move Definition Location" title: "Move Definition Location" -ms.date: "11/16/2016" -ms.assetid: c6d507ac-c61e-4da2-95c8-d504b42e2520 +ms.date: "09/19/2022" --- # Move Definition Location -**What:** Lets you immediately move a function definition to the corresponding header file. +**What:** Move a function definition to the corresponding header file. **When:** You have a function that you want to move to a header file. -**Why:** You could manually move the function, but this feature will move it automatically, creating the header file if required. +**Why:** You could manually move the function, but this feature will move it automatically, and create the header file if necessary. **How:** 1. Place your text or mouse cursor over the function for which you want to move. - ![Screenshot showing highlighted code.](images/movedefinition_highlight.png) + ![Screenshot of a function, with the cursor on the function name.](images/movedefinition_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -24,6 +23,6 @@ ms.assetid: c6d507ac-c61e-4da2-95c8-d504b42e2520 * **Mouse** * Right-click and select the **Quick Actions and Refactorings** menu and select **Move Definition Location** from the context menu. -1. The function will be moved to the corresponding header file, which you will see in a popup preview window. If the header file does not exist, it will also be created and placed in the project. +1. The function will be moved to the corresponding header file, which you'll see in a popup preview window. If the header file doesn't exist, it will also be created and placed in the project. - ![Create Declaration / Definition result.](images/movedefinition_result.png) + ![Screenshot of a pop-up window containing a header file that the function was moved to.](images/movedefinition_result.png) diff --git a/docs/ide/refactoring/rename.md b/docs/ide/refactoring/rename.md index a01c365f10..69bf660156 100644 --- a/docs/ide/refactoring/rename.md +++ b/docs/ide/refactoring/rename.md @@ -1,39 +1,39 @@ --- description: "Learn more about: Rename" title: "Rename" -ms.date: "11/16/2016" -ms.assetid: 64b42a88-3bd9-4399-8b96-75bceffc353b +ms.date: "09/19/2022" +f1_keywords: ["vc.pkg.refactoring.renamedlg"] --- # Rename -**What:** Lets you rename identifiers for code symbols, such as fields, local variables, methods, namespaces, properties and types. +**What:** Rename identifiers for code symbols such as fields, local variables, methods, namespaces, properties and types. **When:** You want to safely rename something without having to find all instances, and copy/paste the new name. -**Why:** Copy and pasting the new name across an entire project would likely result in errors. This refactoring tool will accurately perform the renaming action. +**Why:** Copy and pasting the new name across an entire project could result in errors. This feature accurately performs the rename. **How:** 1. Highlight or place the text cursor inside the item to be renamed: - ![Screenshot showing highlighted code.](images/rename_highlight.png) + ![Screenshot showing the variable r highlighted. The line reads: double r = 1.23;.](images/rename_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+R**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+R**. (Your keyboard shortcut may be different depending on which profile you've selected.) * **Mouse** * Select **Edit > Refactor > Rename**. * Right-click the code and select **Rename**. 1. In the **Rename** window that pops up, enter the new name for the selected item and click the **Preview** button. Change the **Search scope** if you need to widen or narrow the scope of the renaming. - ![Rename dialog.](images/rename_dialog.png) + ![Screenshot of the Rename dialog. It asks for the new name of the symbol and allows you to specify the scope of the changes.](images/rename_dialog.png) > [!TIP] > You can skip the preview by checking the **Skip preview changes if references are all confirmed** option. -1. When the **Preview Changes - Rename** window appears, ensure that the changes you are requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. +1. When the **Preview Changes - Rename** window appears, ensure that the changes you're requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. - ![Rename preview.](images/rename_preview.png) + ![Screenshot of the rename preview dialog which shows the proposed changes and allows you to deselect those you don't want.](images/rename_preview.png) -1. When everything looks good, click the **Apply** button and the item will be renamed in your source code. +1. When everything looks good, click the **Apply** button, and the item will be renamed in your source code. diff --git a/docs/ide/toc.yml b/docs/ide/toc.yml index bdcaca200b..c208f599e6 100644 --- a/docs/ide/toc.yml +++ b/docs/ide/toc.yml @@ -4,10 +4,20 @@ items: items: - name: Read and understand C++ code href: ../ide/read-and-understand-code-cpp.md + - name: Visualize macro expansions + href: ../ide/visualize-macro-expansion.md - name: Edit and refactor C++ code href: ../ide/writing-and-refactoring-code-cpp.md - name: Navigate C++ code href: ../ide/navigate-code-cpp.md + - name: C/C++ Include Cleanup overview + href: ../ide/include-cleanup-overview.md + - name: Configure C/C++ Include Cleanup + href: ../ide/include-cleanup-config.md + - name: Include Cleanup messages + href: ../ide/include-cleanup-messages.md + - name: C++ Include Diagnostics + href: include-diagnostics.md - name: Set your C++ coding preferences href: ../ide/how-to-set-preferences.md - name: Collaborate using Live Share for C++ @@ -30,6 +40,10 @@ items: href: ../ide/lnt-integer-float-division.md - name: lnt-logical-bitwise-mismatch href: ../ide/lnt-logical-bitwise-mismatch.md + - name: lnt-make-member-function-const + href: ../ide/lnt-make-member-function-const.md + - name: lnt-naming-convention + href: ../ide/lnt-naming-convention.md - name: lnt-uninitialized-local href: ../ide/lnt-uninitialized-local.md - name: Change signature @@ -78,8 +92,12 @@ items: href: ../ide/adding-a-member-variable-visual-cpp.md - name: Add a method href: ../ide/adding-a-method-visual-cpp.md + - name: Add an IDL method + href: ../ide/add-interface-definition-library-method-wizard.md - name: Add a property href: ../ide/adding-a-property-visual-cpp.md + - name: Add an IDL property + href: ../ide/add-interface-definition-library-property-wizard.md - name: Add an event href: ../ide/adding-an-event-visual-cpp.md - name: Add an event handler diff --git a/docs/ide/visualize-macro-expansion.md b/docs/ide/visualize-macro-expansion.md new file mode 100644 index 0000000000..0a8071e0a9 --- /dev/null +++ b/docs/ide/visualize-macro-expansion.md @@ -0,0 +1,86 @@ +--- +title: "Visualize C/C++ macro expansion" +description: "Learn how to use Visual Studio to visualize C/C++ macro expansion." +ms.date: 03/07/2024 +ms.topic: "how-to" +f1_keywords: ["macro expansion", "macro visualization"] +helpviewer_keywords: ["macro expansion", "macro visualization"] +--- +# Visualize C/C++ macro expansion + +Long macros can be difficult to read. Visual Studio can now expand C and C++ macros. You can get a copy on the clipboard of what the expanded macro looks like, replace the macro inline with its expansion, and step-by-step expand a macro to see what it looks like at each stage of expansion. In this article, you experiment with all of these features. + +## Prerequisites + +- Visual Studio version 17.5 or later + +### Create the sample + +1. Start Visual Studio 2022, version 17.5 or later, and create a C++ Console app. +1. Replace the default code with: + + ```cpp + #include + + #define MASS 10.0 + #define ACCELERATION 20.0 + #define SPEED 5.0 + #define TIME 2.0 + #define DISTANCE() (SPEED * TIME) + #define FORCE()(MASS * ACCELERATION) + #define WORK()(FORCE() * DISTANCE()) + #define POWER()(WORK()/TIME) + + int main() + { + std::cout << "Distance: " << DISTANCE() << std::endl; + std::cout << "Force: " << FORCE() << std::endl; + std::cout << "Work: " << WORK() << std::endl; + std::cout << "Power: " << POWER() << std::endl; + } + ``` + +## Copy an expanded macro + +You can inspect a macro's expanded value, even when several preprocessor steps are involved, by using the following steps: + +1. Place the cursor on the `POWER` macro inside `main()` in the example. +1. As you hover over the macro, options appear to **Copy**, **Expand Inline**, **Visualize Expansion**, and **Search Online**: + + :::image type="complex" source="media/visual-studio-2022-hover-macro.png" alt-text="Screenshot of the macro window, showing the POWER macro expansion."::: + The macro window is open on POWER to show that it expands to (((10.0 * 20.0) * (5.0 * 2.0)) / 2.0). Options to copy, expand inline, visual expansion, and search online appear at the bottom of the window. + :::image-end::: + +1. Choose **Copy**. +1. Create a comment following the `POWER` line and choose paste (CTRL+V). The expansion of the macro, as a comment near your macro, looks like: `// (((10.0 * 20.0)* (5.0 * 2.0)) / 2.0).` The keyboard shortcut for this action is CTRL+M, CTRL+C. + +## Expand a macro inline + +Use the following steps to expand a macro inline, which replaces the macro with its expansion: + +1. Place the cursor on the `POWER` macro inside `main()` in the example. +1. As you hover over the macro, options appear to **Copy**, **Expand Inline**, **Visualize Expansion**, and **Search Online** +1. Choose **Expand Inline**. The `POWER()` macro is replaced with its expanded value: ```std::cout << "Power: " << (((10.0 * 20.0) * (5.0 * 2.0)) / 2.0) << std::endl;```. The keyboard shortcut for this action is CTRL+M, CTRL+I. + +## Visualize macro expansion + +You can expand a macro one step at a time. This is useful when there are nested macros and you want to see the expansion step-by-step. To visualize the macro expansion for the `WORK` macro, use the following steps: + +1. Place the cursor on the `WORK` macro inside `main()` in the example. +1. As you hover over the macro, options appear to **Copy**, **Expand Inline**, **Visualize Expansion**, and **Search Online**. +1. Choose **Visualize Expansion**. The keyboard shortcut for this action is CTRL+M followed by CTRL+V. +1. The macro expansion window appears. The first expansion of the `WORK` macro is visible: `(FORCE() * DISTANCE())`: + + :::image type="complex" source="media/visual-studio-2022-work-macro-expansion.png" alt-text="Screenshot of the macro expansion window, which allows you to step through the WORK macro expansion one step at a time."::: + The macro visualization window is open on FORCE to show that it initially expands to (FORCE()*DISTANCE()). There are single angle brackets in the window for moving forwards and backwards a single expansion at a time. The double angle brackets fully expand or fully undo the macro expansion. + :::image-end::: + +1. Click the right angle bracket to expand the `FORCE` macro. The window now shows the `FORCE` macro expansion: `(MASS * ACCELERATION) * DISTANCE()`. +1. Click the right angle bracket to expand another step. The window now shows the `FORCE` macro expansion: `((10.0 * ACCELERATION) * DISTANCE())`. + +Continue to expand the macro to see the full expansion of the `WORK` macro, which is: ```((10.0 * 20.0) * (5.0 * 2.0))```. +You can use the double angle brackets to fully expand the macro, or to reverse the expansion to the first level of expansion. + +## See also + +[View UE macros in Visual Studio](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-quickstart#view-ue-macros-in-visual-studio) \ No newline at end of file diff --git a/docs/ide/walkthrough-deploying-your-program-cpp.md b/docs/ide/walkthrough-deploying-your-program-cpp.md index 44cdf605b4..366b51534e 100644 --- a/docs/ide/walkthrough-deploying-your-program-cpp.md +++ b/docs/ide/walkthrough-deploying-your-program-cpp.md @@ -1,59 +1,70 @@ --- description: "Learn more about: Walkthrough: Deploying Your Program (C++)" title: "Walkthrough: Deploying Your Program (C++)" -ms.date: "05/14/2019" +ms.date: "01/30/2024" helpviewer_keywords: ["deploying applications [C++], walkthroughs", "setup projects [C++]", "program deployments [C++]", "projects [C++], setup", "projects [C++], deploying programs", "application deployment [C++], walkthroughs"] -ms.assetid: 79e6cc4e-dced-419d-aaf7-d62d1367603f --- # Walkthrough: Deploying Your Program (C++) -Now that you've created your application by completing the earlier related walkthroughs, the last step is to create an installer so that other users can install the program on their computers. For the installer, you'll add a new project to your existing solution. The output of this new project is a setup.exe file that will install your app on another computer. +Now that you've created your application by completing the earlier related walkthroughs, the last step is to create an installer so that other users can install the program on their computers. For the installer, you add a new project to your existing solution. The output of this new project is a `setup.exe` file that can install your app on another computer. The walkthrough shows how to use Windows Installer to deploy your application. You can also use ClickOnce to deploy an application. For more information, see [ClickOnce Deployment for Visual C++ Applications](../windows/clickonce-deployment-for-visual-cpp-applications.md). For more information about deployment in general, see [Deploying Applications, Services, and Components](/visualstudio/deployment/deploying-applications-services-and-components). ## Prerequisites - The walkthrough assumes that you understand the fundamentals of the C++ language. - - It also assumes that you've completed the earlier related walkthroughs that are listed in [Using the Visual Studio IDE for C++ Desktop Development](using-the-visual-studio-ide-for-cpp-desktop-development.md). - - The walkthrough can't be completed in Express editions of Visual Studio. +- The walkthrough can't be completed without the *Microsoft Visual Studio Installer Project* extension. Instructions for how to install it follow. -## Install the Visual Studio setup and deployment project template +## Install the Visual Studio setup and deployment projects template -The steps in this section vary depending on which version of Visual Studio you have installed. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +The steps in this section vary depending on which version of Visual Studio you have installed. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. The control near the top of the table of contents on this page. ::: moniker range=">=msvc-160" -### To install the setup and deployment project template for Visual Studio +If you haven't already done so, download the *Microsoft Visual Studio Installer Projects* extension. The extension is free for Visual Studio developers and adds the setup and deployment project templates to Visual Studio. -1. If you haven't already done so, download the Microsoft Visual Studio Installer Projects extension. The extension is free for Visual Studio developers and adds the functionality of the setup and deployment project templates to Visual Studio. When you're connected to the Internet, in Visual Studio, choose **Extensions** > **Manage Extensions**. Under the **Extensions and Updates** dialog, select the **Online** tab and type *Microsoft Visual Studio Installer Projects* in the search box. Hit **Enter**, select **Microsoft Visual Studio \ Installer Projects**, and click **Download**. Choose to run and install the extension, then restart Visual Studio. +1. When you're connected to the Internet, from the main menu in Visual Studio choose **Extensions** > **Manage Extensions**. The **Manage Extensions** dialog appears. +1. Select the **Online** tab and type *Microsoft Visual Studio Installer Projects* in the search box. Hit **Enter**, select **Microsoft Visual Studio Installer Projects**, and click **Download**. +1. Choose to run and install the extension, then restart Visual Studio. -1. On the Visual Studio menu bar, choose **File** > **Recent Projects and Solutions**, and then choose to reopen your project. +### Create the setup project -1. On the menu bar, choose **File** > **New** > **Project** to open the **Create a New Project** dialog box. In the search box, type "Setup" and from the results list choose **Setup Project**. +1. From the Visual Studio main menu, choose **File** > **Recent Projects and Solutions**, and then choose to reopen your project. -1. Enter a name for the setup project in the **Name** box. In the **Solution** drop-down list, select **Add to solution**. Choose the **OK** button to create the setup project. A **File Assistant (ProjectName)** tab opens in the editor window. +1. From the main menu, choose **File** > **New** > **Project** to open the **Create a New Project** dialog box. In the search box, type `Setup` and from the results choose **Setup Project** and then **Next**. -1. Right-click the **Application Folder** node and select **Add** > **Project Output** to open the **Add Project Output Group** dialog box. +1. Enter a name for the setup project in the **Name** box, such as `Setup`. -1. In the dialog box, select **Primary Output** and click **OK**. A new item named **Primary Output from Game (Active)** appears. +1. In the **Solution** drop-down list, select **Add to solution**. Choose **Create** to create the setup project. A **File System** tab opens in the editor window. -1. Select the item **Primary Output from Game (Active)**, right-click and choose **Create Shortcut to Primary Output from Game (Active)**. A new item named **Shortcut to Primary Output from Game (Active)** appears. +1. Right-click the **Application Folder** node in the left pane and select **Add** > **Project Output** to open the **Add Project Output Group** dialog box. + +1. In the dialog box, select **Primary Output** and click **OK**. (You won't see Primary Output if you forgot to change the **Solution** dropdown to **Add to solution** in the earlier step). A new item named **Primary Output from Game (Active)** appears. + +1. Select **Primary Output from Game (Active)**, right-click and choose **Create Shortcut to Primary Output from Game (Active)**. A new item named **Shortcut to Primary Output from Game (Active)** appears. 1. Rename the shortcut item to *Game*, then drag and drop the item into the **User's Programs Menu** node on the left side of the window. -1. In **Solution Explorer**, select the **Game Installer** project and choose **View** > **Properties Window** or hit **F4** to open the **Properties** window. +1. In **Solution Explorer**, select the setup project and choose **View** > **Properties Window** to open the **Properties** window for the setup project. -1. Specify additional details as you want them to appear in the installer. For example, use *Contoso* for **Manufacturer**, *Game Installer* for **Product Name**, and *https\://www.contoso.com* for **SupportUrl**. +1. Specify the other details in the property window the way you want them to appear in the installer. For example, use *Contoso* for **Manufacturer**, *Game Installer* for **Product Name**, and `https://www.contoso.com` for **SupportUrl**. -1. On the menu bar, choose **Build** > **Configuration Manager**. In the **Project** table, under the **Build** column, check the box for **Game Installer**. Click **Close**. +### Build the setup project -1. On the menu bar, choose **Build** > **Build Solution** to build the Game project and the Game Installer project. +1. From the main menu, choose **Build** > **Configuration Manager**. -1. In the solution folder, locate the setup.exe program that was built from the Game Installer project, and then run it to install the Game application on your computer. You can copy this file (and GameInstaller.msi) to install the application and its required library files on another computer. +1. In the **Project contexts** table, under the **Build** column, check the box for the setup project, **Setup**. Click **Close**. + +1. From the menu bar, choose **Build** > **Build Solution** to build the Game project and the installer project. + +### Run the setup project + +1. In the solution explorer, press the button to **Switch between solutions and available views** to switch to folder view. +1. Navigate to the setup folder and the **Debug** folder under that. You can run the `setup.exe` program there, which was built from the setup project, to install the Game application on your computer. You can copy this file (and Setup.msi) to install the application and its required library files on another computer. ::: moniker-end @@ -77,7 +88,9 @@ The steps in this section vary depending on which version of Visual Studio you h 1. In the left pane of the dialog box, expand the **Installed** > **Other Project Types** nodes, and then select **Visual Studio Installer**. In the center pane, select **Setup Project**. -1. Enter a name for the setup project in the **Name** box. For this example, enter *Game Installer*. In the **Solution** drop-down list, select **Add to solution**. Choose the **OK** button to create the setup project. A **File Assistant (Game Installer)** tab opens in the editor window. +1. Enter a name for the setup project in the **Name** box. For this example, enter *Game Installer*. + +1. In the **Solution** drop-down list, select **Add to solution**. Choose the **OK** button to create the setup project. A **File Assistant (Game Installer)** tab opens in the editor window. 1. Right-click the **Application Folder** node and select **Add** > **Project Output** to open the **Add Project Output Group** dialog box. @@ -89,9 +102,9 @@ The steps in this section vary depending on which version of Visual Studio you h 1. In **Solution Explorer**, select the **Game Installer** project and choose **View** > **Properties Window** or hit **F4** to open the **Properties** window. -1. Specify additional details as you want them to appear in the installer. For example, use *Contoso* for **Manufacturer**, *Game Installer* for **Product Name**, and *https\://www.contoso.com* for **SupportUrl**. +1. Specify the other details the way you want them to appear in the installer. For example, use *Contoso* for **Manufacturer**, *Game Installer* for **Product Name**, and *https\://www.contoso.com* for **SupportUrl**. -1. On the menu bar, choose **Build** > **Configuration Manager**. In the **Project** table, under the **Build** column, check the box for **Game Installer**. Click **Close**. +1. On the menu bar, choose **Build** > **Configuration Manager**. In the **Project** table, under the **Build** column, check the box for the **Setup** project. Click **Close**. 1. On the menu bar, choose **Build** > **Build Solution** to build the Game project and the Game Installer project. diff --git a/docs/ide/walkthrough-testing-a-project-cpp.md b/docs/ide/walkthrough-testing-a-project-cpp.md index bb086f53bb..189fe59131 100644 --- a/docs/ide/walkthrough-testing-a-project-cpp.md +++ b/docs/ide/walkthrough-testing-a-project-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Walkthrough: Testing a Project (C++)" title: "Walkthrough: Testing a Project (C++)" -ms.date: "04/25/2019" +ms.date: 03/15/2022 helpviewer_keywords: ["project testing [C++]", "testing projects", "projects [C++], testing"] ms.assetid: 88cdd377-c5c8-4201-889d-32f5653ebead --- @@ -19,7 +19,7 @@ In this walkthrough, you watch the value of a variable as the program runs and d ### To run a program in Debug mode -1. Open Games.cpp for editing. +1. Open Game.cpp for editing. 1. Select this line of code: @@ -31,7 +31,7 @@ In this walkthrough, you watch the value of a variable as the program runs and d 1. On the menu bar, choose **Debug** > **Start Debugging**, or choose the **F5** key. - When the program reaches the line that has the breakpoint, execution stops temporarily, because your program is in Break mode. A yellow arrow to the left of a line of code indicates that it's the next line to be executed. + Because your program is in Break mode, execution pauses when it reaches the breakpoint line. A yellow arrow to the left of a line of code indicates that it's the next line to be executed. 1. To examine the value of the `Cardgame::totalParticipants` variable, move the pointer over `Cardgame` and then move it over the expansion control at the left of the tooltip window. The variable name `totalParticipants` and its value of **12** are displayed. @@ -43,16 +43,16 @@ In this walkthrough, you watch the value of a variable as the program runs and d 1. Open the shortcut menu for the `return 0;` statement and then choose **Run to Cursor**. The yellow arrow to the left of the code points to the next statement to be executed. -1. The `Cardgame::totalParticipants` number should decrease when a `Cardgame` ends. At this point, `Cardgame::totalParticipants` should equal 0 because all `Cardgame` instances have been deleted, but the **Watch 1** window indicates that `Cardgame::totalparticipants` equals **18**. The difference indicates that there's a bug in the code, which you can detect and fix by completing the next walkthrough, [Walkthrough: Debugging a Project (C++)](../ide/walkthrough-debugging-a-project-cpp.md). +1. The `Cardgame::totalParticipants` number should decrease when a `Cardgame` ends. At this point, `Cardgame::totalParticipants` should equal 0 because all `Cardgame` instances have been deleted, but the **Watch 1** window indicates that `Cardgame::totalparticipants` equals **18**. The difference indicates that there's a bug in the code. You can detect and fix it by completing the next walkthrough, [Walkthrough: Debugging a Project (C++)](../ide/walkthrough-debugging-a-project-cpp.md). 1. To stop the program, on the menu bar, choose **Debug** > **Stop Debugging**, or choose the **Shift**+**F5** keyboard shortcut. ## Next Steps -**Previous:** [Walkthrough: Building a Project (C++)](../ide/walkthrough-building-a-project-cpp.md)
+**Previous:** [Walkthrough: Building a Project (C++)](../ide/walkthrough-building-a-project-cpp.md)\ **Next:** [Walkthrough: Debugging a Project (C++)](../ide/walkthrough-debugging-a-project-cpp.md) ## See also -[C++ Language Reference](../cpp/cpp-language-reference.md)
-[Projects and build systems](../build/projects-and-build-systems-cpp.md)
+[C++ Language Reference](../cpp/cpp-language-reference.md)\ +[Projects and build systems](../build/projects-and-build-systems-cpp.md) diff --git a/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md b/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md index 0bb96cb8a3..990ce0c8d2 100644 --- a/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md +++ b/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Walkthrough: Working with Projects and Solutions (C++)" title: "Walkthrough: Working with Projects and Solutions (C++)" -ms.date: 10/27/2021 +ms.date: 02/23/2023 helpviewer_keywords: ["solutions [C++]", "projects [C++], about projects", "projects [C++]", "solutions [C++], about solutions"] ms.assetid: 93a3f290-e294-46e3-876e-e3084d9ae833 --- @@ -19,7 +19,7 @@ It helps if you understand the fundamentals of the C++ language, and know what a ## Create a project -To create a project, first choose a project-type template. For each project type, Visual Studio sets compiler settings and—depending on the type—generates starter code that you can modify later. The following steps vary depending on which version of Visual Studio you are using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +To create a project, first choose a project-type template. For each project type, Visual Studio sets compiler settings and—depending on the type—generates starter code that you can modify later. The following steps vary depending on which version of Visual Studio you're using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. ::: moniker range=">=msvc-160" @@ -49,7 +49,7 @@ To create a project, first choose a project-type template. For each project type 1. In the left pane of the **New Project** dialog box, expand **Installed** and select **Visual C++**, if it isn't open already. -1. In the list of installed templates in the center pane, select **Windows Console Application**. +1. In the list of installed templates in the center pane, select **Console App**. 1. Enter a name for the project in the **Name** box. For this example, enter *Game*. @@ -79,7 +79,11 @@ To create a project, first choose a project-type template. For each project type When you create a project, Visual Studio puts the project in a solution. By default, the solution has the same name as the project. You can change the name in the **Solution name** box, but for this example, keep the default name. -1. Choose the **OK** button to create the project. +1. Choose the **OK** button to dismiss the **New Project** dialog and start the **Win32 Application Wizard**. + +1. In the wizard, choose the **Next** button. On the **Application Settings** page, under **Additional options**, clear the **Precompiled header** check box. + +1. Choose the **Finish** button to create the project. Visual Studio creates your new solution and project files, and opens the editor for the Game.cpp source code file it generated. @@ -99,7 +103,7 @@ This part of the walkthrough shows how to add a class to the project. When you a 1. In the **Add Class** dialog, enter *Cardgame* in the **Class Name** box. Don't modify the default file names and settings. Choose the **OK** button. - Visual Studio creates new files and adds them to your project. You can see them in the **Solution Explorer** window. The Cardgame.h and Cardgame.cpp files are opened in the editor. + Visual Studio creates new files and adds them to your project. You can see them in the **Solution Explorer** window. Visual Studio opens the Cardgame.h and Cardgame.cpp files in the editor. 1. Edit the Cardgame.h file, and make these changes: @@ -120,12 +124,12 @@ This part of the walkthrough shows how to add a class to the project. When you a `Cardgame(int players);` - - After the default destructor, add an inline declaration for a `static int` member function named *GetParticipants* that takes no parameters and returns the `totalParticipants` value. + - After the default destructor, add an inline declaration for a `static int` member function named `GetParticipants` that takes no parameters and returns the `totalParticipants` value. `static int GetParticipants() { return totalParticipants; }` - The Cardgame.h file should resemble the code below after you change it: + The Cardgame.h file should resemble this code after you change it: @@ -142,7 +146,7 @@ This part of the walkthrough shows how to add a class to the project. When you a }; ``` - The line `#pragma once` tells the compiler to include the header file only one time. For more information, see [once](../preprocessor/once.md). For information about other C++ keywords in the header file above, see [class](../cpp/class-cpp.md), [int](../cpp/fundamental-types-cpp.md), [static](../cpp/storage-classes-cpp.md), and [public](../cpp/public-cpp.md). + The line `#pragma once` tells the compiler to include the header file only one time. For more information, see [`once`](../preprocessor/once.md). For information about other C++ keywords in the header file, see [`class`](../cpp/class-cpp.md), [`int`](../cpp/fundamental-types-cpp.md), [`static`](../cpp/storage-classes-cpp.md), and [`public`](../cpp/public-cpp.md). 1. Choose the **Cardgame.cpp** tab at the top of the editing pane to open it for editing. @@ -151,7 +155,6 @@ This part of the walkthrough shows how to add a class to the project. When you a ```cpp - #include "pch.h" // remove this line in Visual Studio 2019 #include "Cardgame.h" #include @@ -164,7 +167,7 @@ This part of the walkthrough shows how to add a class to the project. When you a { totalParticipants += players; cout << players << " players have started a new game. There are now " - << totalParticipants << " players in total." << endl; + << totalParticipants << " players in total.\n"; } Cardgame::~Cardgame() @@ -189,7 +192,6 @@ Add some code to your app that tests the new functions. // Game.cpp : Defines the entry point for the console application. // - #include "pch.h" // remove this line in Visual Studio 2019 #include "Cardgame.h" #include diff --git a/docs/ide/writing-and-refactoring-code-cpp.md b/docs/ide/writing-and-refactoring-code-cpp.md index d68c9dec49..7c3edfb3da 100644 --- a/docs/ide/writing-and-refactoring-code-cpp.md +++ b/docs/ide/writing-and-refactoring-code-cpp.md @@ -1,8 +1,7 @@ --- title: "Edit and refactor C++ code in Visual Studio" description: "Use the C++ code editor in Visual Studio to format, navigate, understand and refactor your code." -ms.date: "05/31/2019" -ms.assetid: 56ffb9e9-514f-41f4-a3cf-fd9ce2daf3b6 +ms.date: "09/20/2022" ms.topic: "overview" ms.custom: intro-overview --- @@ -14,14 +13,14 @@ Visual Studio provides several tools to help you write, edit, and refactor your IntelliSense is a powerful code completion tool that suggests symbols and code snippets for you as you type. C++ IntelliSense in Visual Studio runs in real time, analyzing your codebase as you update it and providing recommendations. As you type more characters, the list of recommended results narrows down. -![Screenshot of the C plus plus member list drop down.](../ide/media/cpp-statement-completion.png) +![Screenshot of the C plus plus member list drop down showing the methods available for string such as append, assign, and so on.](../ide/media/cpp-statement-completion.png) -Some symbols are omitted automatically to help narrow down the results. For example, when accessing a class object's members from outside the class, you will not be able to see private members by default, or protected members (if you are not in the context of a child class). You can adjust the filtering by using the buttons at the bottom. +Some symbols are omitted automatically to help narrow down the results. For example, when accessing a class object's members from outside the class, you won't be able to see private members by default, or protected members (if you aren't in the context of a child class). You can adjust the filtering by using the buttons at the bottom. After you choose the symbol from the drop-down list, you can autocomplete it with **Tab**, **Enter**, or one of the other commit characters (by default: `{ } [ ] ( ) . , : ; + - * / % & | ^ ! = ? @ # \`). To add or remove characters from this list, search for "IntelliSense" in **Quick Launch** (Ctrl + Q) and choose the **Text Editor > C/C++ > Advanced** option. The **Member List Commit Characters** option enables you to customize the list with the changes you want. -The **Member List Filter Mode** option controls what kinds of IntelliSense autocomplete suggestions you see. By default, it is set to **Fuzzy**. In a fuzzy search, if you have a symbol called *MyAwesomeClass*, you can type "MAC" and find the class in your autocomplete suggestions. The fuzzy algorithm sets a minimum threshold that symbols must meet to show up in the list. **Smart** filtering displays all symbols containing substrings that match what you typed. **Prefix** filtering searches for strings that begin with what you typed. +The **Member List Filter Mode** option controls what kinds of IntelliSense autocomplete suggestions you see. By default, it's set to **Fuzzy**. In a fuzzy search, if you have a symbol called *MyAwesomeClass*, you can type "MAC" and find the class in your autocomplete suggestions. The fuzzy algorithm sets a minimum threshold that symbols must meet to show up in the list. **Smart** filtering displays all symbols containing substrings that match what you typed. **Prefix** filtering searches for strings that begin with what you typed. For more information about C++ IntelliSense, see [Visual C++ IntelliSense](/visualstudio/ide/visual-cpp-intellisense) and [Configure a C++ project for IntelliSense](/visualstudio/ide/visual-cpp-intellisense-configuration). @@ -29,9 +28,9 @@ For more information about C++ IntelliSense, see [Visual C++ IntelliSense](/visu IntelliCode is AI-assisted IntelliSense. It puts the most likely candidate at the top of your completion list. IntelliCode recommendations are based on thousands of open source projects on GitHub each with over 100 stars. When combined with the context of your code, the completion list is tailored to promote common practices. -When writing C++, IntelliCode will assist when using popular libraries such as the C++ Standard Library. The context of your code is used to provide the most useful recommendations first. In the following example, the `size` member function is commonly used with the `sort` function, so it is surfaced to the top of the results list. +When writing C++, IntelliCode will assist when using popular libraries such as the C++ Standard Library. The context of your code is used to provide the most useful recommendations first. In the following example, the `size` member function is commonly used with the `sort` function, so it's surfaced to the top of the results list. -![Screenshot of C plus plus IntelliCode.](../ide/media/intellicode-cpp.png) +![Screenshot of C plus plus IntelliCode dropdown which shows the members of the vector class sorted by which are most commonly used in your code.](../ide/media/intellicode-cpp.png) ::: moniker range=">=msvc-160" @@ -47,7 +46,7 @@ In Visual Studio 2017, IntelliCode is available as an extension in the Visual St ## Predictive IntelliSense (Experimental) -**Predictive IntelliSense** is an experimental feature that uses contextual awareness to limit the number of results displayed in the IntelliSense dropdown list. The algorithm applies type matching so that it shows only those results that match the expected type. In the simplest case, if you type `int x =` and invoke the IntelliSense dropdown, you will see only integers or functions returning integers. This feature is off by default because it is still in development. It works best with global symbols; member functions are not yet supported. You can turn it on by typing "Predictive" in **Quick Launch** or by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Experimental** > **Enable Predictive IntelliSense**. +**Predictive IntelliSense** is an experimental feature that uses contextual awareness to limit the number of results displayed in the IntelliSense dropdown list. The algorithm applies type matching so that it shows only those results that match the expected type. In the simplest case, if you type `int x =` and invoke the IntelliSense dropdown, you will see only integers or functions returning integers. This feature is off by default because it's still in development. It works best with global symbols; member functions aren't yet supported. You can turn it on by typing "Predictive" in **Quick Launch** or by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Experimental** > **Enable Predictive IntelliSense**. To override **Predictive IntelliSense** and show the longer list, press **Ctrl + J**. If **Predictive IntelliSense** is on, invoking **Ctrl + J** removes the Predictive filter. Pressing **Ctrl + J** again removes the accessibility filter from Member List results where relevant. The ([+]) button under the IntelliSense dropdown list does the same thing as **Ctrl + J**. Hover over the button to see tooltip information about what is being shown. @@ -62,39 +61,37 @@ The preceding screenshot shows several buttons under the dropdown list. These en - Enums - Namespaces -A button is displayed only if it is relevant to your current IntelliSense session. You typically do not see all the buttons at the same time. +A button is displayed only if it's relevant to your current IntelliSense session. You typically don't see all the buttons at the same time. ## Template IntelliSense -When the caret is inside a template definition, a **Template Bar** appears, which enables you to provide sample template arguments for IntelliSense. +The template bar is a UI element that appears when your cursor is on a template definition. It's useful because you can provide sample template arguments for intellisense that will appear when you edit the template body. For example, you could specify that a template argument is of type `std::vector`. Then, when you use that argument in the template body, you'll see the members of `std::vector`in intellisense. -![Screenshot of C plus plus Template IntelliSense Show Existing Instantiations.](../ide/media/template-intellisense-cpp-1.png) +![Screenshot of the template bar which has the Add All Existing Instantiations option highlighted.](../ide/media/template-intellisense-cpp-1.png) -Click the **\** icon to expand/collapse the **Template Bar**. Click the pencil icon or double-click the **Template Bar** to open the **Edit** window. +Click the **\** icon to expand/collapse the **Template Bar**. Click the pencil icon or double-click the **Template Bar** to open the **Edit** window where you specify argument types for the parameters. -![Screenshot of C plus plus Template IntelliSense.](../ide/media/template-intellisense-cpp-3.png) +![Screenshot of the editing experience inside the template bar where you enter a type for each template parameter.](../ide/media/template-intellisense-cpp-3.png) -Edits that you make in the window are applied directly to the source code, so that you can see the effects in real time. +The Template Bar can auto-populate parameter types based on instantiations of the template in your code. Click on **Add All Existing Instantiations** to see a list of all concrete arguments that have been used to instantiate the template throughout your code base. -The Template Bar can auto-populate candidates based on instantiations in your code. Click on **Add All Existing Instantiations** to see a list of all concrete arguments that have been used to instantiate the template throughout your code base. +![Screenshot of the Template IntelliSense Results listing the different types used to instantiate template parameter C such as C = AmbientLight, C = Candle, and others.](../ide/media/template-intellisense-cpp-2.png) -![Screenshot of C plus plus Template IntelliSense Results List.](../ide/media/template-intellisense-cpp-2.png) +A window at the bottom of the editor shows where each instantiation was found, and what its arguments were. You can select an instantiation to go to the location in your code where that instantiation was found. -A window at the bottom of the editor shows where each instantiation was found, and what its arguments were. +![Screenshot of the list of instantiations of the template in your code. The instantion, file, location, and arguments are listed.](../ide/media/template-intellisense-cpp-4.png) -![Screenshot of C plus plus Template IntelliSense Instantiation Map.](../ide/media/template-intellisense-cpp-4.png) - -**Template Bar** information is treated as user-specific. It is stored in the .vs folder and is not committed to source control. +**Template Bar** information is user-specific. It's stored in the `.vs` folder and isn't committed to source control. ## Error squiggles and quick fixes If the editor detects problems with your code, it will add colored squiggles under the problem. Red squiggles indicate code that won't compile. Green squiggles indicate other kinds of problems that might still be potentially serious. You can open the **Error List** window to get more information about the problems. -For some kinds of errors, as well as common coding patterns, the editor will offer a **Quick Fix** in the form of a light bulb that appears when you hover over the squiggle. Click the down arrow to see the suggestions. +For some kinds of errors, and common coding patterns, the editor will offer a **Quick Fix** in the form of a light bulb that appears when you hover over the squiggle. Click the down arrow to see the suggestions. In the following example, a `vector` was declared but no definition was found, so the editor offers to include the necessary header file: -![Screenshot showing error squiggles and the quick fix that the editor offers.](../ide/media/quick-fix-for-header-cpp.png "C++ Quick Fix") +![Screenshot of an error and the proposed quick fix to # include vector.](../ide/media/quick-fix-for-header-cpp.png "C++ Quick Fix") The editor also offers Quick Fixes for some refactoring opportunities. For example, if you declare a class in a header file, Visual Studio will offer to create a definition for it in a separate .cpp file. @@ -104,7 +101,7 @@ The editor also offers Quick Fixes for some refactoring opportunities. For examp Whenever you make a change to a file, a yellow bar appears on the left to indicate that unsaved changes were made. When you save the file, the bar turns green. The green and yellow bars are preserved as long as the document is open in the editor. They represent the changes that were made since you last opened the document. -![Screenshot of C plus plus change tracking.](../ide/media/change-tracking-cpp.png) +![Screenshot of C plus plus change tracking. A yellow bar down the left appears to indicate changes.](../ide/media/change-tracking-cpp.png) ## Move code @@ -112,19 +109,21 @@ You can move lines of code up and down by selecting them, holding down Alt, and ## Insert snippets -A snippet is a predefined piece of source code. Right-click on a single point or on selected text to either insert a snippet or surround the selected text with the snippet. The following illustration shows the three steps to surround a selected statement with a for loop. The yellow highlights in the final image are editable fields that you access with the tab key. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). +A snippet is a predefined piece of source code. Right-click on a single point or on selected text and select Snippet to either insert a snippet or surround the selected text with the snippet. The following illustration shows the three steps to surround a selected statement with a for loop. The yellow highlights in the final image are editable fields that you access with the tab key. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). -![Screenshot of C plus plus Insert Snippet Drop down control.](../ide/media/vs2015_cpp_surround_with.png) +:::image type="complex" source="../ide/media/vs2015_cpp_surround_with.png" alt-text="Screenshot of the Insert Snippet Drop down control."::: +A function is selected. In the dropdown that appears after a right-click on the function name, Surround With... is highlighted in yellow. In the Surround With: dropdown, the snippet for a `for` loop is selected. This results in putting a for loop around the function. The loop variable and limit are shown in yellow to indicate that they are editable fields. +:::image-end::: ## Add Class Add a new class from the **Project** menu, or from the context menu in **Solution Explorer**: -![Add New Class in C plus plus.](../ide/media/vs2017-add-class.png) +![Screenshot of the Add New Class dialog. It has fields for the class name, accessibility, files to put the declaration and implementation, and so on.](../ide/media/vs2017-add-class.png) You can also use Class Wizard to modify or examine an existing class. -![C plus plus Class Wizard.](../ide/media/vs2017-class-wizard.png) +![Screenshot of the Class Wizard which has options for adding methods, member variables, and much more.](../ide/media/vs2017-class-wizard.png) For more information, see [Adding Functionality with Code Wizards (C++)](../ide/adding-functionality-with-code-wizards-cpp.md). @@ -151,31 +150,31 @@ Visual Studio 2017 and later comes with built-in support for [ClangFormat](https - WebKit - Visual Studio -You can also provide your own .clang-format or _clang-format file to apply custom rules to all code files at the same level or below. +You can also provide your own `.clang-format` or `_clang-format` file to apply custom rules to all code files at the same level or below. The files are easily shareable via source control, so you can enforce coding conventions across your whole development team. -![Screenshot showing C plus plus Clang Format.](../ide/media/clang-format-cpp.png) +![Screenshot showing a .clang-format file which has many options such as the column limit, indent width, tab width, and so on.](../ide/media/clang-format-cpp.png) Visual Studio 2017 and later also supports [EditorConfig](https://editorconfig.org/), which works in a similar way. ClangFormat, however, has more style options than EditorConfig, including rules that are specific to C++. With **EditorConfig**, you create **.editorconfig** files and place them in different folders of your codebase to specify code styles for those folders and their subfolders. An **.editorconfig** file supersedes any other **.editorconfig** files in parent folders and overwrites any formatting settings configured via **Tools** > **Options**. You can set rules for tabs vs. spaces, indent size, and more. For more information, see [Create portable, custom editor settings with EditorConfig](/visualstudio/ide/create-portable-custom-editor-options). ## Other formatting options -The **Quick Launch** search box provides the fastest way to find a setting or tool. It is located on the main menu. Just start typing and the auto-completion list will filter the results. +The **Quick Launch** search box provides the fastest way to find a setting or tool. It's located on the main menu. Just start typing and the auto-completion list will filter the results. -![Screenshot showing Visual Studio Quick Launch.](../ide/media/vs2015_cpp_quick_launch.png "Quick Launch") +![Screenshot of the Quick Launch search box. It shows searching C plus plus advanced which results in options for the text editor.](../ide/media/vs2015_cpp_quick_launch.png "Quick Launch") To set formatting options such as indents, brace completion, and colorization, type "C++ Formatting" into the **Quick Launch** window. -![Screenshot showing C++ formatting options.](media/cpp-formatting-options.png) +![Screenshot showing C++ formatting options such as whether to automatically indent when you type a tab.](media/cpp-formatting-options.png) Other formatting options are found under **Edit** > **Advanced** in the main menu. -![Screenshot showing C++ advanced editing options.](media/edit-advanced-cpp.png) +![Screenshot showing advanced editing options such a viewing white space, word wrap, commenting a selection, increasing line indent, and more.](media/edit-advanced-cpp.png) Options for enabling and configuring C++-specific editing features are located under **Tools** > **Options** > **Text Editor** > **C/C++**. After choosing which option you want to set, you can get more help by pressing **F1** when the dialog is in focus. For general code formatting options, type `Editor C++` into **Quick Launch**. -![Screenshot showing Visual Studio Tools > Options dialog editor options.](../ide/media/tools-options.png "Editor options") +![Screenshot showing the Visual Studio menu item Tools selected, and the Options menu item highlighted.](../ide/media/tools-options.png "Editor options") Experimental features, which may or may not be included in a future version of Visual Studio, are found in the [Text Editor C++ Experimental](/visualstudio/ide/reference/options-text-editor-c-cpp-experimental) dialog. In Visual Studio 2017 and later you can enable **Predictive IntelliSense** in this dialog. diff --git a/docs/index.yml b/docs/index.yml index cb91f700a0..94be641a2b 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -1,15 +1,15 @@ ### YamlMime:Hub title: Microsoft C++, C, and Assembler documentation summary: Learn how to use C++, C, and assembly language to develop applications, services, and tools for your platforms and devices. -# brand: aspnet | azure | dotnet | dynamics | m365 | ms-graph | office | power-platform | sql | sql-server | vs | visual-studio | windows | xamarin +# brand: aspnet | azure | dotnet | dynamics | m365 | ms-graph | office | power-platform | sql | sql-server | vs | visual-studio | windows brand: visual-studio metadata: title: Microsoft C/C++ Documentation description: Learn how to use C++ to develop applications, services, and tools for your platforms and devices. - ms.prod: visual-cpp + ms.service: visual-cpp ms.topic: hub-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 06/04/2020 ms.custom: intro-landing-hub @@ -118,7 +118,7 @@ conceptualContent: - text: Use C++ on Linux url: https://code.visualstudio.com/docs/cpp/config-linux itemType: tutorial - - text: Use C++ on MacOS + - text: Use C++ on macOS url: https://code.visualstudio.com/docs/cpp/config-clang-mac itemType: tutorial @@ -127,19 +127,19 @@ tools: title: Languages and frameworks items: - title: C++ - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: cpp/index.yml - title: C - imageSrc: https://docs.microsoft.com/media/logos/logo_C.svg + imageSrc: /media/logos/logo_C.svg url: c-language/index.yml - title: Microsoft Assembler imageSrc: media/index/logo-asm.svg url: intrinsics/index.yml - title: C++/CX for Windows Runtime - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: cppcx/visual-c-language-reference-c-cx.md - title: C++/CLI for .NET - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md - title: Active Template Library (ATL) imageSrc: media/index/logo-atl.svg @@ -148,7 +148,7 @@ tools: imageSrc: media/index/logo-mfc.svg url: mfc/mfc-desktop-applications.md - title: C++/WinRT for Windows Runtime - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: /windows/uwp/cpp-and-winrt-apis/ # additionalContent section (optional) @@ -164,16 +164,20 @@ additionalContent: - text: Universal Windows Platform development url: cppcx/universal-windows-apps-cpp.md - text: Windows Desktop development - url: ./windows/desktop-applications-visual-cpp.md + url: windows/overview-of-windows-programming-in-cpp.md - text: Linux development url: linux/index.yml + - text: Embedded development + url: embedded/index.yml - text: Mobile development url: cross-platform/index.yml - text: Game development - url: /windows/uwp/gaming/e2e/ + url: /visualstudio/gamedev/ # Card - title: Features links: + - text: Build reliable and secure programs + url: code-quality/build-reliable-secure-programs.md - text: Edit and refactor code url: ide/writing-and-refactoring-code-cpp.md - text: Build code projects @@ -203,5 +207,7 @@ additionalContent: url: cloud/cloud-and-web-programming-in-visual-cpp.md - text: Universal Windows Platform libraries url: cppcx/namespaces-reference-c-cx.md + - text: vcpkg package manager + url: /vcpkg/ # footer (optional) - footer: "[Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) - [C++ Team Blog](https://devblogs.microsoft.com/cppblog/) - [Twitter](https://twitter.com/visualc) - [Developer Community](https://aka.ms/vsfeedback/browsecpp) - [Stack Overflow](https://stackoverflow.com/questions/tagged/visual-c++) - [How to report an issue](overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md) - [Suggest a feature](https://aka.ms/feedback/suggest?space=62) - Contribute to C++ docs: Read our [contributor guide](/contribute/)." + footer: "[Microsoft Learn Q&A](/answers/topics/c%2B%2B.html) - [C++ Team Blog](https://devblogs.microsoft.com/cppblog/) - [Twitter](https://twitter.com/visualc) - [Developer Community](https://aka.ms/vsfeedback/browsecpp) - [Stack Overflow](https://stackoverflow.com/questions/tagged/visual-c++) - [How to report an issue](overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md) - [Suggest a feature](https://aka.ms/feedback/suggest?space=62) - Contribute to C++ docs: Read our [contributor guide](/contribute/)." diff --git a/docs/intrinsics/addressofreturnaddress.md b/docs/intrinsics/addressofreturnaddress.md index 62708c065e..62ed8bddb9 100644 --- a/docs/intrinsics/addressofreturnaddress.md +++ b/docs/intrinsics/addressofreturnaddress.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _AddressOfReturnAddress" title: "_AddressOfReturnAddress" +description: "Learn more about: _AddressOfReturnAddress" ms.date: "09/02/2019" f1_keywords: ["_AddressOfReturnAddress_cpp", "_AddressOfReturnAddress"] helpviewer_keywords: ["_AddressOfReturnAddress intrinsic", "AddressOfReturnAddress intrinsic"] -ms.assetid: c7e10b8c-445e-4236-a602-e2d90200f70a --- # _AddressOfReturnAddress @@ -41,7 +40,7 @@ This routine is only available as an intrinsic. #include // This function will print three values: -// (1) The address retrieved from _AddressOfReturnAdress +// (1) The address retrieved from _AddressOfReturnAddress // (2) The return address stored at the location returned in (1) // (3) The return address retrieved the _ReturnAddress* intrinsic // Note that (2) and (3) should be the same address. diff --git a/docs/intrinsics/alphabetical-listing-of-intrinsic-functions.md b/docs/intrinsics/alphabetical-listing-of-intrinsic-functions.md index cf4ffa0393..f0fcca5fb3 100644 --- a/docs/intrinsics/alphabetical-listing-of-intrinsic-functions.md +++ b/docs/intrinsics/alphabetical-listing-of-intrinsic-functions.md @@ -7,7 +7,7 @@ ms.assetid: 178f88a2-7e8e-43ac-b55e-ef3298bef895 --- # Alphabetical listing of intrinsic functions -The following sections describe the Microsoft-specific intrinsic functions available on some or all architectures. Other supported intrinsics are documented by processor manufacturers, either in the header files or on their websites. For more information, and links to manufacturer documentation, see these articles: [ARM intrinsics](../intrinsics/arm-intrinsics.md), [ARM64 intrinsics](../intrinsics/arm64-intrinsics.md), [x86 intrinsics](../intrinsics/x86-intrinsics-list.md), and [x64 intrinsics](../intrinsics/x64-amd64-intrinsics-list.md). C Runtime Library (CRT) functions implemented as intrinsics aren't documented here. CRT intrinsic functions are documented in the [C Runtime Library Reference](../c-runtime-library/c-run-time-library-reference.md). +The following sections describe the Microsoft-specific intrinsic functions available on some or all architectures. Processor manufacturers document other supported intrinsics, either in the header files or on their websites. For more information, and links to manufacturer documentation, see these articles: [ARM intrinsics](../intrinsics/arm-intrinsics.md), [ARM64 intrinsics](../intrinsics/arm64-intrinsics.md), [x86 intrinsics](../intrinsics/x86-intrinsics-list.md), and [x64 intrinsics](../intrinsics/x64-amd64-intrinsics-list.md). C Runtime Library (CRT) functions implemented as intrinsics aren't documented here. CRT intrinsic functions are documented in the [C Runtime Library Reference](../c-runtime-library/c-run-time-library-reference.md). [`__addfsbyte`, `__addfsword`, `__addfsdword`](../intrinsics/addfsbyte-addfsword-addfsdword.md) @@ -29,6 +29,8 @@ The following sections describe the Microsoft-specific intrinsic functions avail [`_bittestandset`, `_bittestandset64`](../intrinsics/bittestandset-bittestandset64.md) +[`__check_isa_support`, `__check_arch_support`](../intrinsics/check-isa-arch-support.md) + [`__cpuid`, `__cpuidex`](../intrinsics/cpuid-cpuidex.md) [`_cvt_ftoi_fast`, `_cvt_ftoll_fast`, `_cvt_ftoui_fast`, `_cvt_ftoull_fast`, `_cvt_dtoi_fast`, `_cvt_dtoll_fast`, `_cvt_dtoui_fast`, `_cvt_dtoull_fast`](../intrinsics/fast-conversion-functions.md) diff --git a/docs/intrinsics/arm-intrinsics.md b/docs/intrinsics/arm-intrinsics.md index 3f8bbd62a7..f2a248f9a9 100644 --- a/docs/intrinsics/arm-intrinsics.md +++ b/docs/intrinsics/arm-intrinsics.md @@ -4,7 +4,6 @@ description: "Reference list of ARM intrinsics supported by the Microsoft C++ co ms.date: "09/02/2019" f1_keywords: ["arm_neon/vsetq_lane_p8", "armintr/_arm_uxtb", "arm_neon/vld4_lane_p8", "arm_neon/vrshrn_n_s64", "arm_neon/vsli_n_u32", "arm_neon/vsraq_n_u16", "arm_neon/vcgt_f32", "armintr/__iso_volatile_store32", "arm_neon/vceqq_f32", "armintr/_arm_smlal", "arm_neon/vmull_n_s32", "arm_neon/vmax_s8", "arm_neon/vmvn_u32", "arm_neon/vrshl_u32", "arm_neon/int32x2_t", "arm_neon/vdupq_n_p8", "arm_neon/vpmax_u16", "arm_neon/vtrnq_s32", "arm_neon/vset_lane_f32", "arm_neon/vrev64_s8", "arm_neon/vtrnq_p8", "arm_neon/vqshlq_u64", "arm_neon/vld1q_dup_s64", "arm_neon/vmovq_n_u64", "arm_neon/vqshrn_n_u16", "arm_neon/vhadd_s32", "arm_neon/vrhaddq_u32", "arm_neon/vst1q_p8", "arm_neon/vshrn_n_s16", "arm_neon/vget_high_f32", "arm_neon/vuzpq_s16", "arm_neon/vand_u16", "arm_neon/vmulq_s32", "arm_neon/vrsraq_n_s64", "arm_neon/vceqq_s8", "arm_neon/uint64x1x3_t", "arm_neon/veor_u32", "armintr/_arm_pkhtb", "arm_neon/vorrq_u16", "arm_neon/vpaddl_s8", "arm_neon/vmla_n_s16", "arm_neon/vqdmlal_lane_s32", "arm_neon/vshlq_n_u8", "arm_neon/vst2_lane_p8", "arm_neon/vld3q_u16", "arm_neon/vandq_u8", "arm_neon/vst1_u64", "arm_neon/vaddq_s64", "arm_neon/vuzpq_u32", "arm_neon/vld3_lane_p8", "arm_neon/vminq_s32", "arm_neon/vabd_u16", "arm_neon/vdup_n_u32", "arm_neon/vmul_p8", "arm_neon/vsra_n_u16", "arm_neon/vst3q_u16", "arm_neon/int32x2x3_t", "arm_neon/vld2_dup_u16", "arm_neon/vrhaddq_u8", "arm_neon/vhadd_u8", "arm_neon/vgetq_lane_s32", "arm_neon/vcleq_u16", "arm_neon/vabdq_s8", "arm_neon/vrev16q_u8", "arm_neon/vqshlu_n_s64", "arm_neon/vcvt_n_s32_f32", "arm_neon/vqrshrn_n_s64", "arm_neon/vst1q_p16", "arm_neon/vgetq_lane_s16", "arm_neon/vtstq_u32", "arm_neon/vmlsl_n_s16", "arm_neon/vcge_s8", "arm_neon/vshr_n_s16", "armintr/_arm_rbit", "arm_neon/vmls_u32", "arm_neon/vmls_lane_u32", "arm_neon/vcvtq_n_s32_f32", "arm_neon/vqshl_n_s8", "arm_neon/vst1q_s16", "armintr/__emit", "arm_neon/vshlq_s64", "arm_neon/vuzp_s8", "arm_neon/vld1q_lane_s64", "arm_neon/veorq_s32", "arm_neon/vaddq_u64", "arm_neon/vceq_s32", "arm_neon/vmovn_u16", "arm_neon/vabal_s8", "arm_neon/vabsq_f32", "armintr/_arm_smuad", "arm_neon/veor_u8", "arm_neon/int16x4_t", "arm_neon/vsraq_n_s16", "arm_neon/vshlq_s8", "arm_neon/vcreate_u32", "arm_neon/vzipq_s8", "arm_neon/vst3q_u8", "arm_neon/int64x1x4_t", "armintr/__iso_volatile_store16", "arm_neon/vst4_lane_p16", "arm_neon/vld1_dup_p16", "arm_neon/vhadd_s16", "arm_neon/vtbl2_s8", "arm_neon/veorq_u32", "arm_neon/vqdmlal_lane_s16", "arm_neon/vrsra_n_u8", "arm_neon/vbslq_u16", "arm_neon/vget_low_s64", "arm_neon/vceq_u16", "arm_neon/vdupq_lane_u32", "arm_neon/vabdl_u32", "arm_neon/vmlal_s32", "arm_neon/vst1_lane_u8", "arm_neon/vld4q_f16", "arm_neon/vqdmlsl_s32", "arm_neon/vqrdmulh_s32", "arm_neon/vqrshl_u8", "arm_neon/uint32x4x4_t", "arm_neon/vabaq_u16", "arm_neon/vcnt_p8", "arm_neon/vld3q_s16", "arm_neon/vshl_n_u32", "arm_neon/vrev64q_u16", "arm_neon/vextq_s64", "arm_neon/vhsubq_s8", "arm_neon/vld2_dup_u8", "arm_neon/vst3_s16", "arm_neon/vorn_u16", "arm_neon/vst4_f16", "arm_neon/vpadalq_u8", "armintr/__iso_volatile_load8", "arm_neon/vmovl_u16", "arm_neon/vld4q_u32", "arm_neon/vcgt_u32", "arm_neon/vmlaq_n_u32", "arm_neon/vrsra_n_u64", "arm_neon/vst4_s8", "arm_neon/vcvtq_n_f32_u32", "arm_neon/vst2q_u16", "arm_neon/vqshrn_n_s16", "arm_neon/vld4_s16", "arm_neon/uint16x8x4_t", "arm_neon/vrsqrte_u32", "arm_neon/vcltq_s8", "arm_neon/vst3_u16", "arm_neon/vst2_f32", "arm_neon/vld2_u64", "arm_neon/vst1_u16", "arm_neon/vmls_s16", "arm_neon/vqrshlq_s32", "arm_neon/vqdmull_s16", "arm_neon/vld2_lane_p16", "arm_neon/vpaddlq_u8", "arm_neon/vcvt_n_f32_u32", "arm_neon/vcgtq_u8", "arm_neon/vshl_s32", "arm_neon/vtbx3_p8", "arm_neon/vld3_dup_s32", "arm_neon/int16x4x3_t", "arm_neon/vcale_f32", "arm_neon/vqabsq_s32", "arm_neon/vmulq_u16", "arm_neon/vst1_s8", "arm_neon/vclt_u8", "armintr/_arm_sxtb16", "arm_neon/vshr_n_s8", "arm_neon/vst1_lane_f16", "arm_neon/vorn_s64", "armintr/_arm_usub8", "arm_neon/vst4_lane_f32", "arm_neon/vmls_lane_u16", "arm_neon/vpaddl_u32", "arm_neon/vdup_lane_u64", "arm_neon/vsri_n_p16", "arm_neon/vqrshlq_u64", "arm_neon/vclz_s16", "arm_neon/vsra_n_u32", "arm_neon/vabaq_s8", "arm_neon/vst2_lane_s8", "arm_neon/vcvt_n_u32_f32", "arm_neon/vst3_u32", "arm_neon/vcvtq_f32_u32", "arm_neon/vraddhn_s64", "armintr/_arm_uqsax", "arm_neon/vshl_u8", "armintr/_arm_uqadd16", "arm_neon/vrsra_n_u16", "arm_neon/vrshl_u64", "arm_neon/int32x4x3_t", "arm_neon/vmull_u8", "arm_neon/vcombine_u64", "arm_neon/vmull_u16", "arm_neon/vld1_dup_s8", "armintr/_CountLeadingSigns64", "arm_neon/vqshlq_n_s32", "arm_neon/vrecpe_f32", "arm_neon/vsri_n_u32", "arm_neon/vrsraq_n_s8", "arm_neon/vsetq_lane_s16", "arm_neon/vget_high_u32", "arm_neon/vmlal_u32", "arm_neon/vdupq_lane_s16", "arm_neon/vsubq_u64", "arm_neon/vext_p8", "arm_neon/vshl_u16", "arm_neon/vmls_n_u16", "arm_neon/vmull_s16", "arm_neon/vmovq_n_s64", "arm_neon/vaddq_f32", "arm_neon/vshl_n_s16", "arm_neon/vext_p16", "arm_neon/vextq_u32", "arm_neon/vld1_p8", "arm_neon/veor_s32", "arm_neon/int16x8x4_t", "arm_neon/vst1q_u16", "arm_neon/vzipq_p8", "arm_neon/int32x4x4_t", "arm_neon/vqdmulhq_lane_s32", "arm_neon/vst3_lane_u32", "arm_neon/vhsubq_s32", "armintr/__static_assert", "arm_neon/vst3q_lane_u16", "arm_neon/vpmin_u32", "arm_neon/vrev64q_p16", "arm_neon/vcleq_f32", "arm_neon/vhsub_u16", "arm_neon/vld2_lane_s32", "arm_neon/vmlsl_s32", "armintr/_arm_rev", "arm_neon/vcgeq_s16", "arm_neon/vmulq_s8", "arm_neon/vsri_n_s8", "arm_neon/vpadd_f32", "arm_neon/vld1q_lane_f16", "arm_neon/vmls_u16", "arm_neon/vld1_lane_f32", "arm_neon/vmlaq_lane_s16", "arm_neon/vqadd_u32", "arm_neon/vmul_n_s32", "arm_neon/vld1q_dup_p8", "arm_neon/vtrnq_s8", "arm_neon/vbslq_p8", "arm_neon/vget_lane_s8", "arm_neon/vext_u16", "arm_neon/vsubq_s16", "arm_neon/vld4_lane_s8", "arm_neon/uint32x2x2_t", "arm_neon/vdup_n_s8", "arm_neon/vld4_lane_u16", "arm_neon/vmovq_n_s16", "arm_neon/vst4q_s32", "arm_neon/vst2q_f16", "arm_neon/vbslq_s16", "arm_neon/vand_u64", "arm_neon/poly16_t", "arm_neon/vaba_u16", "arm_neon/vqshlq_s64", "armintr/_arm_uxth", "arm_neon/vst2_lane_s16", "arm_neon/vand_u8", "arm_neon/int8x16x3_t", "arm_neon/vrev64_u16", "arm_neon/vld2_lane_s16", "arm_neon/vabaq_s16", "arm_neon/vsli_n_u8", "arm_neon/vsraq_n_u64", "arm_neon/vmlsl_s16", "arm_neon/vmovn_u64", "arm_neon/vld4_f32", "arm_neon/vst2q_f32", "arm_neon/vtbx3_u8", "arm_neon/vcombine_s8", "arm_neon/vqdmulhq_s32", "arm_neon/vgetq_lane_p8", "armintr/_arm_smusd", "arm_neon/vpmax_u32", "arm_neon/vceq_f32", "arm_neon/vsri_n_p8", "arm_neon/vhsubq_u8", "arm_neon/vuzp_s16", "arm_neon/uint32x2x4_t", "arm_neon/vst4_lane_s32", "arm_neon/vsli_n_p8", "arm_neon/vld3_lane_f16", "arm_neon/vbic_u64", "arm_neon/vmlal_u16", "arm_neon/vmvn_s8", "arm_neon/vtstq_s8", "arm_neon/vmaxq_s32", "arm_neon/vqmovn_u64", "armintr/_arm_ssax", "arm_neon/vext_u32", "arm_neon/vld1_dup_u64", "arm_neon/vmlal_n_s16", "armintr/_arm_smulbb", "arm_neon/vqrdmulhq_lane_s16", "arm_neon/vdup_n_p8", "arm_neon/vaba_s8", "arm_neon/vrshrq_n_s32", "arm_neon/vmvnq_s32", "arm_neon/vpadal_s32", "arm_neon/vqshl_s16", "arm_neon/vtrn_p8", "arm_neon/vzip_s16", "arm_neon/vcge_f32", "armintr/_arm_sxtab16", "arm_neon/vst1q_lane_u64", "arm_neon/vqrshlq_u16", "arm_neon/int8x8_t", "arm_neon/vorr_u8", "arm_neon/vrev64_f32", "arm_neon/vpaddlq_s16", "arm_neon/vdupq_lane_u64", "arm_neon/vcltq_u16", "arm_neon/vst3_lane_f32", "arm_neon/vld2_dup_f32", "armintr/_arm_smmul", "arm_neon/vbsl_s16", "arm_neon/vld1_lane_u8", "arm_neon/vld2q_lane_u16", "arm_neon/vqshlu_n_s32", "armintr/_arm_smlalbt", "arm_neon/vmla_s8", "arm_neon/vsli_n_p16", "arm_neon/vmla_u8", "arm_neon/vqaddq_s16", "arm_neon/vld3_p16", "arm_neon/uint64x2x4_t", "arm_neon/vcnt_u8", "arm_neon/vcltq_u8", "arm_neon/vtbx1_p8", "arm_neon/vrev32q_u16", "arm_neon/vld1_lane_u16", "arm_neon/vqadd_s16", "arm_neon/vcnt_s8", "armintr/_MulUnsignedHigh", "arm_neon/vsliq_n_u8", "arm_neon/vpmin_s16", "armintr/__iso_volatile_load16", "arm_neon/vst2_lane_f32", "arm_neon/vqsubq_s32", "arm_neon/vqshl_s32", "arm_neon/vsraq_n_u32", "arm_neon/vcreate_s32", "arm_neon/vld3q_lane_u32", "arm_neon/vaddq_u16", "arm_neon/vand_s32", "arm_neon/vbicq_s32", "armintr/_arm_smulbt", "arm_neon/vrsra_n_s8", "arm_neon/vshrq_n_u32", "arm_neon/vld4_f16", "arm_neon/vcagtq_f32", "arm_neon/vaddw_u32", "armintr/_arm_uxtah", "arm_neon/vtstq_u8", "arm_neon/vld1_dup_u16", "arm_neon/int16x4x4_t", "arm_neon/vqshluq_n_s8", "arm_neon/vqdmulhq_n_s32", "arm_neon/vst1_s64", "arm_neon/vrsubhn_u16", "arm_neon/vld4_dup_p16", "arm_neon/vmlaq_s32", "arm_neon/vnegq_s32", "arm_neon/vst2q_u8", "arm_neon/vget_low_s32", "arm_neon/vorn_u32", "arm_neon/vld1q_s8", "arm_neon/vandq_s64", "arm_neon/vmvn_p8", "arm_neon/vabdl_s16", "arm_neon/vqshl_u32", "arm_neon/vld3_dup_u16", "arm_neon/vmov_n_f32", "arm_neon/vcvt_f32_u32", "arm_neon/vrhadd_s8", "arm_neon/vpadal_u32", "armintr/_arm_ubfx", "arm_neon/vcgt_s8", "arm_neon/vget_lane_f32", "arm_neon/vcge_s16", "arm_neon/vmov_n_s64", "arm_neon/vmulq_n_f32", "arm_neon/vpadalq_u32", "armintr/_arm_smlaldx", "arm_neon/vtst_u16", "arm_neon/vmls_n_s16", "arm_neon/vcombine_f32", "arm_neon/vld1q_p16", "armintr/_arm_ssat", "arm_neon/vextq_s8", "arm_neon/vmax_u32", "arm_neon/vqsubq_s64", "arm_neon/vcltq_s16", "arm_neon/vst2q_s8", "arm_neon/vpmax_u8", "arm_neon/vld4_dup_p8", "arm_neon/vrshr_n_u64", "arm_neon/vqrshrun_n_s16", "arm_neon/vget_low_u64", "arm_neon/vst2q_s32", "arm_neon/vst4_s32", "arm_neon/vrshrq_n_u8", "arm_neon/vdupq_n_u64", "arm_neon/vsriq_n_u8", "arm_neon/vdupq_lane_u8", "arm_neon/vsriq_n_s64", "arm_neon/vget_low_u8", "arm_neon/vst1_lane_p16", "arm_neon/vld1q_lane_u8", "arm_neon/vcgt_s32", "arm_neon/vst1_lane_u32", "arm_neon/vzipq_p16", "arm_neon/vmvn_u16", "arm_neon/vld1q_lane_u16", "armintr/_MoveToCoprocessor64", "arm_neon/vdup_n_u16", "arm_neon/vzipq_f32", "arm_neon/vshl_s16", "arm_neon/vmlaq_n_s16", "arm_neon/vget_lane_s64", "arm_neon/vld1q_lane_f32", "arm_neon/vnegq_s16", "armintr/_arm_usax", "arm_neon/vabd_s16", "arm_neon/vmovq_n_u32", "arm_neon/vshlq_n_u16", "armintr/_CountLeadingSigns", "arm_neon/vld3q_f16", "arm_neon/vceqq_u32", "arm_neon/int8x8x2_t", "arm_neon/vst2_s64", "arm_neon/vst4q_lane_s16", "arm_neon/vorn_s32", "arm_neon/vcle_f32", "arm_neon/vld1_p16", "arm_neon/vtrn_u32", "arm_neon/vbsl_s32", "arm_neon/float32x2_t", "arm_neon/vmvn_s32", "arm_neon/vqdmlsl_lane_s16", "arm_neon/vtbl3_s8", "arm_neon/vsra_n_u8", "arm_neon/vcvtq_u32_f32", "arm_neon/vst1_p8", "arm_neon/vrev64_p16", "armintr/__ldrexd", "arm_neon/vcgeq_u8", "arm_neon/vmlal_n_s32", "arm_neon/vst1q_lane_p8", "arm_neon/vpadalq_s32", "arm_neon/vtstq_p8", "arm_neon/vld4_lane_u8", "armintr/_arm_ssub16", "arm_neon/vpaddlq_u16", "armintr/_arm_udiv", "arm_neon/vld1_lane_p8", "arm_neon/vst1q_u32", "arm_neon/vld1_f32", "arm_neon/uint64x2x2_t", "arm_neon/vqsubq_u64", "arm_neon/vld4q_s32", "arm_neon/vceq_s16", "arm_neon/vst3_s64", "arm_neon/vext_s8", "armintr/_arm_smlsd", "arm_neon/vpadal_s16", "arm_neon/vbic_s32", "arm_neon/vld1_dup_u8", "arm_neon/vclt_f32", "arm_neon/vrev64_s16", "arm_neon/vrshlq_s64", "arm_neon/vdupq_n_s64", "arm_neon/vuzp_p16", "arm_neon/vld3_dup_p16", "arm_neon/vcreate_s8", "armintr/_arm_smlatt", "arm_neon/vtst_s32", "arm_neon/vshrq_n_s64", "arm_neon/vqshlq_n_s64", "arm_neon/vqshlu_n_s16", "arm_neon/vcleq_s16", "arm_neon/vmull_lane_s16", "arm_neon/int32x4_t", "arm_neon/vqadd_s8", "arm_neon/vld2q_f16", "arm_neon/vld2q_lane_p16", "arm_neon/vadd_u32", "arm_neon/vcntq_u8", "arm_neon/vst1_f32", "arm_neon/vmaxq_u32", "arm_neon/vsub_u64", "arm_neon/vsubl_s32", "arm_neon/poly16x4_t", "arm_neon/vgetq_lane_u16", "arm_neon/vdup_lane_s32", "arm_neon/vrhadd_s32", "arm_neon/veorq_u8", "arm_neon/vclzq_s8", "arm_neon/vsliq_n_s64", "arm_neon/vpadalq_s16", "arm_neon/vmla_n_f32", "arm_neon/vcgt_u16", "armintr/_arm_usada8", "arm_neon/vabd_u32", "arm_neon/vgetq_lane_s8", "arm_neon/vqshlq_n_u64", "arm_neon/vabaq_u32", "armintr/_arm_uhsax", "arm_neon/vmulq_f32", "arm_neon/vld3_dup_s16", "arm_neon/vst3_f16", "arm_neon/vrshrq_n_s64", "armintr/__rdpmccntr64", "arm_neon/vclsq_s32", "arm_neon/vmax_u16", "arm_neon/vmvnq_p8", "arm_neon/veor_u16", "arm_neon/vqshrn_n_u32", "arm_neon/vextq_u64", "arm_neon/vld1q_f32", "arm_neon/vget_low_u32", "arm_neon/vhaddq_s32", "arm_neon/vminq_u16", "arm_neon/vqrdmulhq_lane_s32", "arm_neon/vmla_s16", "arm_neon/vadd_s16", "arm_neon/vbsl_u16", "arm_neon/vhsub_s8", "arm_neon/vld4q_lane_p16", "arm_neon/vld1_s16", "arm_neon/vst2q_lane_p16", "arm_neon/vld2_dup_s8", "arm_neon/vst3q_s16", "arm_neon/vcgeq_u32", "arm_neon/vabdq_s16", "arm_neon/vrhadd_u16", "arm_neon/vqshlq_n_u32", "arm_neon/vst4q_lane_u32", "arm_neon/vrsraq_n_u64", "arm_neon/vmlsq_n_s32", "arm_neon/vld4_u8", "arm_neon/vld2_f16", "arm_neon/vqshlq_u8", "arm_neon/vorrq_u64", "arm_neon/vmin_u16", "arm_neon/vext_u8", "arm_neon/vpaddl_s32", "arm_neon/vshlq_u64", "arm_neon/vst2q_lane_f16", "armintr/_arm_sbfx", "arm_neon/vld3_dup_f16", "armintr/_arm_uhasx", "arm_neon/vst2_lane_u8", "armintr/_arm_smultb", "arm_neon/vdup_n_p16", "arm_neon/vtrnq_u32", "arm_neon/vrshlq_u8", "arm_neon/vld4_lane_p16", "arm_neon/vsraq_n_s32", "arm_neon/vclt_s16", "arm_neon/vzip_u8", "arm_neon/vld3_lane_s16", "arm_neon/vceqq_s32", "arm_neon/vld3_dup_f32", "arm_neon/vld4q_lane_s32", "arm_neon/poly8x16x4_t", "arm_neon/uint64x1x2_t", "arm_neon/vqdmlal_n_s16", "arm_neon/vld2_dup_f16", "arm_neon/vshrq_n_s32", "arm_neon/vcleq_s8", "arm_neon/vld3_s32", "arm_neon/vqrshlq_s64", "arm_neon/vbsl_f32", "arm_neon/vext_s64", "arm_neon/vabaq_s32", "arm_neon/vmulq_s16", "arm_neon/vld3_lane_u16", "arm_neon/vld3q_lane_u16", "armintr/_arm_smlaltt", "arm_neon/poly8x8x2_t", "arm_neon/vst3q_u32", "armintr/_arm_smlsdx", "arm_neon/vqrshl_s64", "arm_neon/vextq_p8", "armintr/_arm_uhsub16", "arm_neon/vld3q_p8", "armintr/_arm_smlawt", "armintr/_arm_smlawb", "arm_neon/vdupq_lane_s8", "arm_neon/vaddl_s16", "arm_neon/vcombine_p16", "arm_neon/vzipq_u32", "arm_neon/poly16x8_t", "arm_neon/vshlq_n_s32", "arm_neon/vrshl_s8", "arm_neon/vst2_u64", "arm_neon/vrev64q_s8", "arm_neon/vst2q_lane_s32", "arm_neon/vld2_dup_s16", "arm_neon/vclt_u16", "arm_neon/vuzp_p8", "arm_neon/vshrq_n_s16", "arm_neon/vst3_u64", "arm_neon/vpmin_u16", "arm_neon/vld3q_lane_s32", "arm_neon/vmlal_s16", "arm_neon/poly16x4x4_t", "arm_neon/vorr_u16", "arm_neon/vsliq_n_s16", "arm_neon/vaddl_u8", "arm_neon/vld4_dup_s32", "arm_neon/vld2_f32", "arm_neon/vclt_u32", "arm_neon/vmull_lane_u16", "arm_neon/vsubw_u32", "arm_neon/vld2_dup_s32", "arm_neon/vuzp_s32", "arm_neon/vcge_s32", "arm_neon/vdup_lane_p16", "arm_neon/vpmin_s8", "arm_neon/vpaddlq_u32", "arm_neon/vmlaq_n_s32", "arm_neon/vshrn_n_u64", "arm_neon/vrshr_n_u16", "arm_neon/vld1_s64", "arm_neon/vbsl_u64", "armintr/_arm_smlad", "arm_neon/vqsub_s16", "arm_neon/vld4_p8", "arm_neon/vqdmulh_lane_s32", "arm_neon/vld3_dup_s64", "arm_neon/vornq_s32", "arm_neon/vpadd_u8", "arm_neon/vld3_lane_p16", "arm_neon/uint64x1x4_t", "arm_neon/vld3_u16", "armintr/_arm_shsax", "arm_neon/vabdq_u16", "arm_neon/vcgtq_f32", "arm_neon/vsubq_s8", "arm_neon/vget_low_f16", "arm_neon/vld4_dup_u64", "arm_neon/vst3_lane_s8", "armintr/_arm_ssat16", "arm_neon/vmlaq_f32", "arm_neon/vsri_n_s32", "arm_neon/vmax_u8", "arm_neon/vqadd_u8", "armintr/_arm_uqsub8", "armintr/_arm_clz", "arm_neon/vcgtq_s32", "arm_neon/vraddhn_s32", "arm_neon/vzip_s8", "arm_neon/veorq_s16", "arm_neon/vsetq_lane_s32", "arm_neon/vmul_n_u16", "armintr/_ReadBankedReg", "arm_neon/vld1q_u8", "arm_neon/vld4_p16", "arm_neon/int64x2x2_t", "arm_neon/vmaxq_s8", "arm_neon/vpmax_s16", "arm_neon/vshlq_u16", "arm_neon/vtrnq_p16", "arm_neon/vabal_u16", "arm_neon/vld2_lane_u16", "arm_neon/vrev32_u8", "arm_neon/vrshl_s32", "arm_neon/vget_low_f32", "arm_neon/vld2_s8", "arm_neon/vclzq_s16", "arm_neon/vqdmulhq_n_s16", "arm_neon/vset_lane_u64", "arm_neon/vld2_dup_p16", "arm_neon/vpaddlq_s32", "arm_neon/vld2q_p8", "arm_neon/vst3_lane_u8", "arm_neon/vld4_dup_f32", "arm_neon/vld2_s64", "arm_neon/vmls_u8", "arm_neon/vtbx4_u8", "arm_neon/vsetq_lane_f32", "arm_neon/vcvt_s32_f32", "arm_neon/vst3q_s32", "arm_neon/vmlsq_s8", "arm_neon/vmlaq_n_u16", "armintr/__iso_volatile_load64", "arm_neon/vcgt_u8", "arm_neon/vld2_dup_p8", "arm_neon/vmov_n_u8", "armintr/_arm_sasx", "arm_neon/vmovq_n_p16", "arm_neon/vmlaq_u32", "arm_neon/vst3_f32", "arm_neon/int32x2x4_t", "arm_neon/vld1q_lane_u64", "arm_neon/vclz_u16", "arm_neon/uint8x8_t", "arm_neon/vsub_u32", "arm_neon/vorn_u8", "armintr/__wfe", "arm_neon/vget_high_s16", "arm_neon/vzip_p8", "arm_neon/vmlal_lane_s16", "arm_neon/vmulq_u8", "armintr/_isunordered", "arm_neon/vld1_dup_f32", "arm_neon/vld4_lane_s16", "arm_neon/vdupq_n_s16", "arm_neon/vst3q_p16", "arm_neon/vst1_lane_f32", "arm_neon/float32x4x3_t", "arm_neon/vand_s8", "arm_neon/float32x2x4_t", "arm_neon/vld3_p8", "arm_neon/vmlaq_lane_u16", "armintr/_arm_uqsub16", "arm_neon/vget_high_s32", "arm_neon/vshl_n_s32", "arm_neon/vornq_s8", "arm_neon/vmlsl_n_u32", "arm_neon/vqshlq_n_s8", "arm_neon/int32x2x2_t", "arm_neon/int16x4x2_t", "arm_neon/vceqq_u8", "arm_neon/vcreate_f16", "arm_neon/vorn_s16", "arm_neon/vqmovn_s32", "arm_neon/vextq_u8", "arm_neon/vld4_s32", "armintr/_WriteStatusReg", "arm_neon/uint8x16_t", "arm_neon/vshrn_n_s64", "arm_neon/vmul_n_u32", "arm_neon/vabdl_u8", "arm_neon/vtbx3_s8", "arm_neon/vaddhn_s16", "arm_neon/vld3q_s8", "arm_neon/vmlsl_n_u16", "arm_neon/vrev64q_s32", "arm_neon/int16x8_t", "arm_neon/vext_s32", "arm_neon/vdupq_n_f32", "arm_neon/vld1q_lane_s32", "arm_neon/vqrshlq_u32", "arm_neon/vtbl2_u8", "arm_neon/vgetq_lane_u8", "arm_neon/veorq_u64", "arm_neon/vcntq_s8", "arm_neon/vbslq_p16", "arm_neon/vqnegq_s32", "arm_neon/vaddw_s32", "arm_neon/vmov_n_p8", "arm_neon/vmull_p8", "arm_neon/vld1_lane_u32", "arm_neon/vcombine_s16", "arm_neon/vqshrn_n_s64", "arm_neon/vceqq_s16", "arm_neon/vld4q_p16", "armintr/_ReadStatusReg", "armintr/_arm_qdadd", "arm_neon/uint32x4x2_t", "arm_neon/vcleq_u8", "armintr/_arm_sxtah", "arm_neon/vrhaddq_s32", "arm_neon/vset_lane_s64", "arm_neon/vld4_s64", "armintr/_DAddSatInt", "arm_neon/vorr_s8", "arm_neon/vst2_u32", "arm_neon/vshll_n_u16", "arm_neon/vld2_dup_u32", "arm_neon/vst3q_lane_s32", "arm_neon/vst3q_p8", "armintr/_MoveFromCoprocessor", "arm_neon/uint32x4_t", "arm_neon/vuzpq_s8", "arm_neon/vrecps_f32", "arm_neon/vst1_lane_s8", "arm_neon/vtbx1_s8", "arm_neon/uint16x8x3_t", "arm_neon/vpaddl_s16", "arm_neon/vsubq_s64", "arm_neon/vrsraq_n_u8", "arm_neon/vqadd_s64", "arm_neon/vst4_lane_s16", "arm_neon/vqadd_u16", "arm_neon/vset_lane_u32", "arm_neon/vand_u32", "arm_neon/vrsqrtsq_f32", "arm_neon/vqaddq_u32", "arm_neon/vsra_n_s64", "armintr/_arm_umlal", "arm_neon/vcvt_f32_f16", "arm_neon/vget_lane_u32", "arm_neon/vbsl_s8", "arm_neon/vrshlq_u32", "arm_neon/vqdmull_lane_s16", "arm_neon/vabsq_s32", "arm_neon/vld3_s8", "arm_neon/vst3q_lane_s16", "arm_neon/vld2q_lane_s16", "arm_neon/vst1_lane_s64", "arm_neon/vmov_n_u16", "arm_neon/vst4_lane_u8", "arm_neon/vshll_n_u32", "arm_neon/vqabs_s8", "arm_neon/vmvnq_u8", "arm_neon/vpadalq_u16", "arm_neon/vbsl_p16", "arm_neon/vqrshrn_n_u16", "arm_neon/vld3q_u32", "arm_neon/vcgeq_f32", "armintr/__iso_volatile_load32", "arm_neon/vrecpe_u32", "arm_neon/vld2_dup_u64", "arm_neon/vld3q_f32", "armintr/_arm_shsub8", "arm_neon/vdup_lane_s64", "arm_neon/vqrshl_s8", "arm_neon/vsliq_n_u16", "arm_neon/vld1q_u16", "arm_neon/vorr_u32", "arm_neon/vqrshl_s32", "armintr/__dmb", "arm_neon/veorq_s8", "arm_neon/vld1_u16", "arm_neon/vmov_n_u32", "arm_neon/vhsub_s16", "arm_neon/vst4q_lane_u16", "arm_neon/vbsl_u8", "armintr/_arm_uxtab", "arm_neon/vld2q_lane_f32", "arm_neon/vst2_p8", "armintr/_arm_smmla", "arm_neon/vaddw_u16", "arm_neon/vmlal_s8", "arm_neon/vtst_u32", "arm_neon/vtbl4_u8", "arm_neon/vcvt_n_f32_s32", "arm_neon/vcageq_f32", "arm_neon/vget_low_s16", "arm_neon/vdupq_n_u8", "arm_neon/vorn_s8", "arm_neon/uint8x16x3_t", "arm_neon/vabdq_u32", "arm_neon/vrev64_p8", "arm_neon/vqsubq_s8", "armintr/_arm_smlabb", "arm_neon/vbicq_s64", "arm_neon/vmaxq_u16", "arm_neon/vdup_n_u8", "arm_neon/veor_s8", "arm_neon/int16x8x2_t", "arm_neon/vcvtq_s32_f32", "arm_neon/vtrn_u16", "arm_neon/vbslq_s32", "arm_neon/vld1q_dup_u32", "arm_neon/vmul_n_f32", "arm_neon/vqrshl_u32", "arm_neon/vqsubq_s16", "arm_neon/vst2_lane_f16", "armintr/_arm_smulwt", "arm_neon/vrshrn_n_u32", "arm_neon/vget_high_p16", "arm_neon/vqadd_u64", "arm_neon/vsli_n_s32", "arm_neon/vhadd_u32", "arm_neon/vmlsl_lane_u16", "arm_neon/vclzq_u32", "arm_neon/vqshrun_n_s64", "arm_neon/vrev64q_u32", "arm_neon/vqshrun_n_s16", "arm_neon/vrev32q_s8", "armintr/_arm_shasx", "arm_neon/vaddl_s8", "armintr/_arm_smull", "arm_neon/vabaq_u8", "armintr/_arm_revsh", "arm_neon/vsubq_f32", "arm_neon/poly16x4x2_t", "arm_neon/poly8x8x3_t", "arm_neon/vsubhn_s64", "arm_neon/vcle_u16", "arm_neon/poly8x16x3_t", "arm_neon/vqdmlsl_n_s16", "arm_neon/vqshl_u64", "arm_neon/vcge_u16", "armintr/_arm_uasx", "arm_neon/vmovl_s32", "arm_neon/vst1q_lane_u16", "arm_neon/vbic_u32", "arm_neon/vld2_s16", "armintr/_arm_qasx", "arm_neon/vorrq_u8", "arm_neon/vst2_s32", "armintr/_WriteBankedReg", "arm_neon/veorq_s64", "arm_neon/vld4_lane_f32", "arm_neon/vcreate_u8", "arm_neon/vset_lane_u8", "arm_neon/vandq_u16", "arm_neon/vrsubhn_s64", "arm_neon/vst1q_lane_p16", "arm_neon/uint8x8x2_t", "arm_neon/vmlsl_s8", "arm_neon/vmax_s32", "arm_neon/uint32x4x3_t", "arm_neon/vld4_dup_u16", "arm_neon/vabs_s32", "arm_neon/vld3_dup_u32", "arm_neon/vrshl_u16", "arm_neon/vcle_u8", "arm_neon/vqshl_n_u16", "arm_neon/vbic_s8", "arm_neon/float32x4x2_t", "arm_neon/vmls_f32", "arm_neon/vshll_n_u8", "arm_neon/vminq_s8", "arm_neon/vmlsq_lane_f32", "arm_neon/vst1q_f16", "arm_neon/vst1_lane_u64", "arm_neon/vrhadd_u8", "arm_neon/vclt_s32", "arm_neon/vst2_p16", "arm_neon/vrshrq_n_u16", "arm_neon/vneg_s32", "arm_neon/vmovl_s16", "arm_neon/vqshlq_s8", "arm_neon/vld1_s8", "arm_neon/vqdmulh_s32", "arm_neon/vcls_s8", "armintr/__trap", "arm_neon/vuzp_u32", "armintr/_CopyInt64FromDouble", "arm_neon/int8x16x2_t", "arm_neon/vmovn_s32", "arm_neon/vget_high_s8", "arm_neon/veor_s64", "armintr/_arm_uadd8", "arm_neon/vrev16_u8", "arm_neon/vbicq_u64", "arm_neon/vst4_lane_f16", "arm_neon/vst3_s32", "arm_neon/poly8x8_t", "arm_neon/vtstq_u16", "arm_neon/vld1_lane_s8", "arm_neon/float32x4x4_t", "arm_neon/vst2_s16", "arm_neon/vqrdmulhq_s32", "arm_neon/vqdmulhq_s16", "arm_neon/vrshrq_n_s8", "arm_neon/vcle_s32", "arm_neon/vtbl3_p8", "arm_neon/vbslq_u8", "arm_neon/vst4_u64", "armintr/_arm_umaal", "arm_neon/vshll_n_s8", "arm_neon/vcvt_u32_f32", "arm_neon/vld4q_p8", "arm_neon/vsetq_lane_u16", "arm_neon/vabd_u8", "arm_neon/vclz_u8", "arm_neon/vsubq_u32", "arm_neon/vld1q_lane_p16", "arm_neon/vcgtq_s16", "arm_neon/vmla_lane_s32", "arm_neon/vshlq_n_s64", "arm_neon/vbsl_u32", "arm_neon/vqshlq_s16", "armintr/_arm_qadd8", "arm_neon/vrshr_n_s32", "armintr/_CountOneBits64", "arm_neon/vceq_u32", "arm_neon/vbsl_p8", "arm_neon/uint16x8x2_t", "arm_neon/vsli_n_s16", "arm_neon/vmla_n_s32", "arm_neon/vld4_dup_u32", "arm_neon/vshrq_n_s8", "arm_neon/vqaddq_s8", "arm_neon/vshl_n_u64", "arm_neon/vtbl2_p8", "arm_neon/vcleq_u32", "arm_neon/vqsub_u32", "arm_neon/vmovl_u8", "arm_neon/vmlal_u8", "arm_neon/vmul_s8", "armintr/_MoveFromCoprocessor64", "arm_neon/vrsraq_n_s16", "arm_neon/vdupq_n_u32", "arm_neon/vmov_n_s16", "arm_neon/vst4_lane_p8", "arm_neon/vld1_s32", "arm_neon/vst4_p8", "arm_neon/vsriq_n_u32", "arm_neon/vqdmull_n_s16", "arm_neon/vshlq_u32", "arm_neon/vld3_u8", "armintr/_arm_usub16", "arm_neon/vmlsq_lane_s16", "arm_neon/vmovq_n_s8", "arm_neon/int32x4x2_t", "arm_neon/vld4q_u8", "arm_neon/poly16x8x2_t", "arm_neon/vld1q_u64", "arm_neon/vld3q_lane_s16", "arm_neon/int64x1x2_t", "arm_neon/vshlq_n_s8", "arm_neon/vrshl_s64", "arm_neon/vqshl_n_u8", "armintr/_arm_qadd", "armintr/_DSubSatInt", "armintr/_arm_usat16", "arm_neon/vmull_s8", "arm_neon/vsub_s8", "arm_neon/vmovq_n_u16", "arm_neon/vst4_u16", "arm_neon/vmlsl_lane_u32", "arm_neon/vsliq_n_p16", "arm_neon/vmovn_u32", "arm_neon/vbic_u16", "arm_neon/vtbx2_p8", "arm_neon/vrsubhn_s32", "armintr/_SubSatInt", "arm_neon/vst3_u8", "arm_neon/vdupq_n_s32", "arm_neon/vcntq_p8", "arm_neon/vst4_f32", "arm_neon/vbic_s64", "arm_neon/vld3_s64", "arm_neon/vrsra_n_s64", "arm_neon/vqabsq_s16", "arm_neon/vsriq_n_p8", "arm_neon/vst2_lane_p16", "arm_neon/vabsq_s16", "arm_neon/vcombine_u8", "arm_neon/vld2q_p16", "armintr/_CountOneBits", "armintr/__prefetch", "arm_neon/vld3_dup_u64", "arm_neon/vld2q_s16", "arm_neon/vget_low_p16", "arm_neon/vuzpq_u8", "arm_neon/vrev32q_s16", "armintr/_AddSatInt", "arm_neon/uint16x4x2_t", "arm_neon/vmov_n_s32", "arm_neon/vaddl_u16", "arm_neon/vqaddq_s64", "arm_neon/vmlaq_u16", "arm_neon/vsli_n_s8", "armintr/_arm_sxth", "arm_neon/vorr_s32", "arm_neon/vsra_n_u64", "arm_neon/vst2_f16", "arm_neon/vcombine_u16", "arm_neon/vabs_s16", "arm_neon/vsubhn_s32", "arm_neon/vst1q_lane_u32", "arm_neon/vst3_p8", "arm_neon/vqshrun_n_s32", "arm_neon/vcreate_s64", "arm_neon/vld4q_lane_s16", "arm_neon/vzipq_u16", "arm_neon/vmin_s32", "armintr/_CopyInt32FromFloat", "arm_neon/vcgtq_u32", "arm_neon/vabdl_s32", "arm_neon/vqshlq_n_u16", "arm_neon/int8x16x4_t", "arm_neon/vqrdmulh_n_s32", "arm_neon/vqaddq_u64", "arm_neon/vhaddq_s8", "arm_neon/vshll_n_s16", "arm_neon/vuzp_u8", "arm_neon/vaddl_u32", "arm_neon/vld4q_s16", "arm_neon/vqmovun_s16", "arm_neon/vld1q_lane_s8", "arm_neon/vld2_lane_u32", "arm_neon/vrshr_n_s8", "arm_neon/vmlaq_s16", "armintr/_CopyFloatFromInt32", "arm_neon/vmul_f32", "arm_neon/vmlaq_n_f32", "arm_neon/vst4_s16", "arm_neon/vld1_dup_s32", "arm_neon/vmul_u16", "arm_neon/vhaddq_s16", "arm_neon/vst1q_lane_f32", "arm_neon/vrhaddq_u16", "arm_neon/vbicq_u32", "arm_neon/vrev32_s8", "arm_neon/vmlaq_s8", "arm_neon/vmin_s16", "arm_neon/vst3_lane_p16", "arm_neon/vst2q_lane_f32", "arm_neon/vld4q_lane_f32", "arm_neon/vget_low_u16", "arm_neon/vqsub_s32", "arm_neon/vtbl1_s8", "arm_neon/vmovn_s64", "arm_neon/vpmax_s8", "arm_neon/int8x16_t", "arm_neon/vpmin_u8", "arm_neon/vdup_lane_p8", "arm_neon/vsetq_lane_u64", "arm_neon/vuzpq_u16", "arm_neon/vcgeq_u16", "arm_neon/uint8x16x2_t", "armintr/_arm_rev16", "armintr/_arm_sxtb", "arm_neon/vsliq_n_u64", "arm_neon/vmovq_n_u8", "arm_neon/vshlq_n_u32", "arm_neon/vcombine_s64", "armintr/_arm_qsax", "arm_neon/vmin_f32", "armintr/_arm_sadd16", "arm_neon/vmlsq_n_s16", "arm_neon/vorr_u64", "arm_neon/vqrshrun_n_s64", "arm_neon/vld2q_lane_s32", "arm_neon/vgetq_lane_p16", "arm_neon/vrev32_s16", "arm_neon/vqshl_u16", "arm_neon/vtrn_s8", "arm_neon/vst1q_lane_s64", "arm_neon/vtbl4_p8", "arm_neon/vst1_p16", "arm_neon/vmvn_u8", "arm_neon/vld2_lane_u8", "arm_neon/vld2q_u16", "arm_neon/vmovl_s8", "arm_neon/vbslq_u64", "arm_neon/vmls_s8", "arm_neon/vld3q_p16", "arm_neon/vtbl3_u8", "arm_neon/vabs_f32", "arm_neon/vsraq_n_s8", "arm_neon/vqadd_s32", "arm_neon/vmulq_n_s16", "arm_neon/vst3q_s8", "arm_neon/vaddhn_s64", "arm_neon/vmul_n_s16", "arm_neon/vtbl1_p8", "arm_neon/uint64x2x3_t", "arm_neon/vmlsq_s32", "arm_neon/vld2q_lane_u32", "arm_neon/vaddq_u8", "arm_neon/vcombine_f16", "arm_neon/vandq_s16", "arm_neon/vst4q_lane_p16", "arm_neon/vsri_n_u8", "arm_neon/vst3_lane_p8", "arm_neon/vst3_lane_s16", "arm_neon/vdup_n_s16", "arm_neon/vbicq_s8", "arm_neon/vdup_lane_u8", "arm_neon/vst4q_lane_s32", "arm_neon/vqrshl_u16", "arm_neon/vrsra_n_u32", "arm_neon/vdupq_lane_p8", "arm_neon/vld3_lane_u8", "arm_neon/vqrdmulh_n_s16", "arm_neon/vpmin_s32", "armintr/__cps", "arm_neon/vshl_u32", "armintr/_arm_uadd16", "arm_neon/vld3_s16", "arm_neon/vcvt_f32_s32", "arm_neon/vshlq_n_u64", "arm_neon/vrev64q_u8", "arm_neon/vextq_u16", "arm_neon/vsubl_s16", "arm_neon/vget_lane_p8", "arm_neon/vabal_s16", "arm_neon/vrecpeq_u32", "arm_neon/vminq_u8", "arm_neon/veor_s16", "arm_neon/vmull_n_u16", "arm_neon/vshl_n_u8", "arm_neon/vrev32q_u8", "arm_neon/vandq_s8", "arm_neon/vrshlq_s16", "arm_neon/vst4q_p16", "arm_neon/vandq_s32", "armintr/_MoveToCoprocessor2", "arm_neon/vqdmlsl_lane_s32", "arm_neon/vld1q_s64", "arm_neon/vmull_n_s16", "arm_neon/vneg_s16", "arm_neon/vqshluq_n_s64", "arm_neon/vst2_lane_s32", "arm_neon/vmvnq_u16", "arm_neon/vshll_n_s32", "arm_neon/vld3_dup_s8", "arm_neon/vtstq_s32", "arm_neon/vmlsl_u32", "arm_neon/vqdmulhq_lane_s16", "arm_neon/vaddl_s32", "armintr/_CountLeadingZeros", "arm_neon/vqrshrn_n_s16", "arm_neon/vmla_lane_u32", "arm_neon/vst1_u8", "arm_neon/vshl_u64", "arm_neon/vshr_n_u8", "arm_neon/vmull_lane_s32", "arm_neon/vmlal_lane_u32", "arm_neon/vsubl_s8", "arm_neon/float32x2x2_t", "armintr/_arm_bfc", "arm_neon/vaddq_s16", "arm_neon/vmlal_lane_s32", "arm_neon/vpadd_u16", "arm_neon/vst2q_lane_u16", "arm_neon/vld4_s8", "arm_neon/vst1q_s8", "arm_neon/vshrq_n_u64", "arm_neon/vsli_n_u16", "arm_neon/vqrdmulh_lane_s32", "arm_neon/vst4_lane_u16", "arm_neon/vabdq_f32", "arm_neon/vld2_lane_f16", "arm_neon/vqsub_u64", "arm_neon/vsub_f32", "arm_neon/vld1q_s16", "arm_neon/vmaxq_s16", "arm_neon/vcombine_u32", "arm_neon/vrsraq_n_u32", "armintr/_arm_smusdx", "arm_neon/vrev16_s8", "arm_neon/vqdmulh_n_s32", "arm_neon/vmul_s32", "arm_neon/vabdq_s32", "arm_neon/veor_u64", "arm_neon/vmlsl_n_s32", "arm_neon/vsub_s16", "arm_neon/vadd_u16", "arm_neon/vsriq_n_u16", "arm_neon/vmla_u32", "arm_neon/vuzpq_s32", "arm_neon/vst4q_s8", "arm_neon/vaddhn_u32", "arm_neon/vmlaq_lane_f32", "arm_neon/vld3_lane_s8", "arm_neon/vsliq_n_u32", "arm_neon/vqrshlq_s8", "arm_neon/vqdmlal_n_s32", "arm_neon/uint8x16x4_t", "arm_neon/vcgtq_u16", "arm_neon/vandq_u32", "arm_neon/vld4q_lane_u32", "arm_neon/vzip_p16", "arm_neon/vget_low_p8", "armintr/_arm_shadd8", "arm_neon/vmovn_s16", "arm_neon/vcge_u8", "arm_neon/vld2q_f32", "arm_neon/vaba_u32", "armintr/__iso_volatile_store8", "arm_neon/vst2q_p16", "arm_neon/vmul_s16", "arm_neon/vand_s16", "arm_neon/vtbx4_p8", "arm_neon/vceq_u8", "arm_neon/vrhaddq_s16", "arm_neon/vgetq_lane_f32", "arm_neon/vqshl_s8", "arm_neon/vbslq_f32", "arm_neon/vrsqrts_f32", "arm_neon/vld2q_s8", "arm_neon/vtbl1_u8", "arm_neon/vtst_u8", "arm_neon/vrev64q_f32", "arm_neon/vcle_s8", "arm_neon/vsetq_lane_p16", "arm_neon/vcreate_p16", "arm_neon/vabal_s32", "armintr/_arm_smlald", "arm_neon/vmla_f32", "arm_neon/vtbx2_s8", "arm_neon/int64x1x3_t", "arm_neon/vclz_s8", "arm_neon/vorr_s16", "arm_neon/vornq_s64", "arm_neon/vst1q_u64", "arm_neon/vdupq_n_s8", "armintr/_arm_sadd8", "arm_neon/vextq_s32", "armintr/_arm_smuadx", "armintr/_arm_qsub", "arm_neon/vadd_f32", "arm_neon/vrshrq_n_s16", "arm_neon/vqsub_s8", "arm_neon/vld3_f32", "arm_neon/vhadd_s8", "arm_neon/vmull_n_u32", "arm_neon/vdup_n_u64", "arm_neon/vsubw_s32", "armintr/_arm_sxtab", "armintr/_arm_uxtb16", "arm_neon/vmvn_s16", "arm_neon/vst1_lane_s16", "arm_neon/vqrdmulhq_n_s32", "arm_neon/vsriq_n_s32", "arm_neon/poly8x16x2_t", "arm_neon/vadd_u8", "arm_neon/vuzpq_p8", "arm_neon/vst2q_p8", "armintr/__wfi", "arm_neon/vget_high_u16", "arm_neon/vqrshl_u64", "arm_neon/vld1_dup_s64", "arm_neon/vqrshrn_n_s32", "arm_neon/vrshr_n_s64", "arm_neon/vst3_s8", "arm_neon/poly16x4x3_t", "arm_neon/vqrdmulh_lane_s16", "arm_neon/vmvnq_u32", "arm_neon/vqsubq_u32", "arm_neon/vmovq_n_p8", "arm_neon/vtrn_s16", "arm_neon/vld2q_u32", "arm_neon/vqsubq_u16", "arm_neon/vrsqrteq_u32", "arm_neon/vadd_u64", "armintr/_arm_usat", "arm_neon/vcvtq_n_u32_f32", "arm_neon/vaddq_s8", "arm_neon/vrsraq_n_u16", "arm_neon/vqabs_s16", "arm_neon/vsra_n_s8", "arm_neon/vsra_n_s16", "arm_neon/vqshlq_n_u8", "arm_neon/vpadal_s8", "arm_neon/vmlal_n_u16", "armintr/_CopyDoubleFromInt64", "arm_neon/vaddw_u8", "arm_neon/vmulq_n_s32", "arm_neon/vqaddq_s32", "arm_neon/vmla_lane_f32", "arm_neon/vmlaq_lane_s32", "arm_neon/vld1q_dup_u64", "arm_neon/uint16x8_t", "arm_neon/vld2_s32", "arm_neon/vcltq_f32", "arm_neon/vst4q_f32", "arm_neon/vsri_n_u16", "arm_neon/vshlq_s32", "arm_neon/vgetq_lane_u32", "arm_neon/vld1q_dup_f16", "arm_neon/vrev64q_s16", "arm_neon/vrshrq_n_u32", "arm_neon/vld2q_s32", "arm_neon/vcgtq_s8", "arm_neon/vsubhn_u64", "arm_neon/vmls_n_s32", "armintr/_arm_smmlar", "arm_neon/vld3_dup_u8", "arm_neon/vld3q_lane_p16", "arm_neon/vld2_dup_s64", "arm_neon/vqabs_s32", "arm_neon/vqaddq_u8", "arm_neon/vminq_u32", "arm_neon/vpaddl_u16", "arm_neon/vaba_s16", "arm_neon/vmul_u32", "arm_neon/vst1_lane_u16", "arm_neon/vcreate_f32", "arm_neon/vcvt_f16_f32", "arm_neon/vset_lane_s32", "arm_neon/vshl_s8", "arm_neon/vcgt_s16", "arm_neon/vtrn_f32", "arm_neon/vget_high_s64", "arm_neon/vld3_dup_p8", "arm_neon/vcreate_u64", "arm_neon/vext_u64", "arm_neon/vld1q_dup_s16", "arm_neon/vget_lane_s16", "arm_neon/vqdmlal_s16", "arm_neon/vld2_p16", "arm_neon/vld4_u16", "armintr/_arm_smlalbb", "arm_neon/vrev64_u8", "arm_neon/vbslq_s64", "arm_neon/vsubw_u16", "arm_neon/vrsubhn_u32", "arm_neon/vabdq_u8", "arm_neon/vmls_n_u32", "arm_neon/vshr_n_s32", "arm_neon/vmulq_n_u32", "arm_neon/vst3_p16", "arm_neon/vrev32_u16", "arm_neon/int8x8x3_t", "arm_neon/vst2q_lane_u32", "arm_neon/vextq_p16", "arm_neon/vtrnq_f32", "armintr/_arm_smultt", "arm_neon/vqneg_s8", "arm_neon/vmlsq_lane_s32", "arm_neon/vmov_n_p16", "arm_neon/vraddhn_u64", "arm_neon/vrhadd_u32", "arm_neon/vrev64_u32", "arm_neon/vrshrn_n_s32", "arm_neon/vld4q_f32", "arm_neon/vst2_s8", "arm_neon/vrsqrteq_f32", "arm_neon/uint16x4_t", "arm_neon/vget_low_s8", "arm_neon/vst2_lane_u32", "arm_neon/vhsub_s32", "arm_neon/vqdmull_lane_s32", "armintr/_arm_smulwb", "arm_neon/vmlsl_u8", "arm_neon/vdup_lane_s16", "arm_neon/vtbx4_s8", "arm_neon/vld4q_lane_u16", "arm_neon/vget_high_u8", "arm_neon/vclzq_s32", "arm_neon/vld1q_dup_f32", "arm_neon/vtrn_u8", "arm_neon/vqabsq_s8", "arm_neon/vdup_lane_f32", "arm_neon/vqrdmulh_s16", "arm_neon/vst4_u32", "arm_neon/vdup_lane_u32", "arm_neon/vst4_u8", "arm_neon/vmovq_n_s32", "arm_neon/vld2_lane_s8", "arm_neon/vld3_u32", "arm_neon/vsubl_u16", "arm_neon/vqshlu_n_s8", "arm_neon/float32x4_t", "arm_neon/vqshl_n_s32", "arm_neon/float32x2x3_t", "armintr/__hvc", "arm_neon/vst1q_lane_f16", "arm_neon/vmvnq_s16", "arm_neon/vst3q_lane_f32", "arm_neon/vld1q_dup_u8", "arm_neon/vmlsq_s16", "arm_neon/vget_lane_u8", "arm_neon/vld1_lane_s32", "arm_neon/vst4q_s16", "armintr/_arm_qsub8", "arm_neon/vorrq_s32", "arm_neon/vsriq_n_s8", "arm_neon/vqshrn_n_u64", "arm_neon/vdup_n_s32", "armintr/_arm_uhsub8", "arm_neon/vld3_lane_s32", "arm_neon/vbsl_s64", "arm_neon/vld1_dup_f16", "arm_neon/vsli_n_u64", "arm_neon/vraddhn_u32", "arm_neon/vsub_u16", "arm_neon/vcltq_u32", "arm_neon/vminq_f32", "arm_neon/vshl_n_s64", "arm_neon/vld4_u32", "arm_neon/vld1_u32", "arm_neon/vaddhn_u16", "arm_neon/vcvtq_n_f32_s32", "arm_neon/vorn_u64", "arm_neon/vsubhn_u16", "arm_neon/int64x1_t", "arm_neon/vst1q_lane_s8", "arm_neon/vld1q_dup_s32", "arm_neon/vrev32_p8", "arm_neon/vst3q_lane_p16", "arm_neon/vrecpeq_f32", "arm_neon/int8x8x4_t", "arm_neon/vshr_n_u32", "arm_neon/vdupq_lane_s64", "arm_neon/vpaddlq_s8", "arm_neon/vqshl_n_u32", "arm_neon/vmul_u8", "arm_neon/vtbx2_u8", "arm_neon/vshr_n_u64", "arm_neon/vqrshlq_s16", "arm_neon/vst3_lane_u16", "arm_neon/vqsub_u8", "arm_neon/vrsra_n_s16", "arm_neon/vaba_s32", "arm_neon/vsri_n_u64", "arm_neon/vst3q_lane_u32", "arm_neon/vmlsq_n_u32", "arm_neon/poly8x16_t", "arm_neon/vld2_u8", "armintr/_arm_smmulr", "arm_neon/vtst_s16", "armintr/_arm_smmls", "arm_neon/vqdmulh_s16", "arm_neon/vtrnq_u8", "arm_neon/vset_lane_p8", "arm_neon/vmlsl_u16", "arm_neon/vshrn_n_u16", "arm_neon/vld1_dup_p8", "arm_neon/vrev16q_s8", "arm_neon/vmov_n_s8", "arm_neon/vld1_u64", "arm_neon/vpmin_f32", "arm_neon/vmla_n_u16", "arm_neon/vst1_f16", "arm_neon/vqdmlsl_s16", "arm_neon/vmin_u32", "armintr/_arm_qsub16", "arm_neon/vcage_f32", "arm_neon/vornq_u32", "arm_neon/vpadd_s16", "arm_neon/vld1_u8", "arm_neon/vhsubq_s16", "arm_neon/vld1_dup_u32", "arm_neon/vld4_u64", "armintr/_MulHigh", "arm_neon/vmaxq_u8", "arm_neon/vget_lane_u16", "arm_neon/vld2q_u8", "arm_neon/vld1q_dup_p16", "arm_neon/vsraq_n_u8", "arm_neon/vqdmlsl_n_s32", "arm_neon/vst1_s16", "arm_neon/vst1q_s32", "arm_neon/vmaxq_f32", "arm_neon/vqdmulh_lane_s16", "armintr/__isb", "arm_neon/vuzpq_p16", "arm_neon/vmls_lane_s16", "arm_neon/vtbl4_s8", "arm_neon/vst1_lane_p8", "arm_neon/vsubw_s8", "arm_neon/vmin_u8", "arm_neon/vzip_u16", "arm_neon/vld4q_u16", "arm_neon/vshrn_n_s32", "arm_neon/vpadal_u16", "arm_neon/vorrq_s8", "arm_neon/vrshlq_u64", "arm_neon/vst3_lane_s32", "arm_neon/vqshluq_n_s32", "armintr/_arm_shsub16", "arm_neon/vst1_u32", "arm_neon/vrhadd_s16", "arm_neon/vzipq_s32", "arm_neon/vshrq_n_u16", "arm_neon/vcls_s32", "arm_neon/vceq_s8", "arm_neon/vld2q_lane_f16", "arm_neon/vst4q_u8", "arm_neon/vraddhn_u16", "arm_neon/vget_lane_u64", "armintr/_arm_smlsld", "arm_neon/vld3_u64", "arm_neon/vld1_lane_s16", "arm_neon/vabd_f32", "arm_neon/vdupq_n_u16", "armintr/__iso_volatile_store64", "arm_neon/vqsubq_u8", "arm_neon/poly16x8x3_t", "arm_neon/vcltq_s32", "arm_neon/vqnegq_s16", "arm_neon/vqsub_u16", "arm_neon/vaddq_s32", "arm_neon/vqshl_n_s64", "arm_neon/vabdl_s8", "arm_neon/vclsq_s16", "arm_neon/vpaddl_u8", "arm_neon/vmlsq_n_u16", "armintr/_arm_uqadd8", "arm_neon/vhsub_u32", "arm_neon/vset_lane_s16", "arm_neon/vsubl_u32", "arm_neon/vld3_lane_f32", "arm_neon/vcle_s16", "arm_neon/vmovl_u32", "arm_neon/vst3_lane_f16", "arm_neon/vcaltq_f32", "arm_neon/vsubq_s32", "arm_neon/vand_s64", "arm_neon/vst2_u8", "arm_neon/vcombine_p8", "arm_neon/vqdmlal_s32", "arm_neon/vsub_s32", "armintr/_arm_uxtab16", "arm_neon/vmlsq_n_f32", "armintr/_arm_qdsub", "arm_neon/vhaddq_u32", "arm_neon/vhsubq_u16", "arm_neon/vmlsq_lane_u16", "arm_neon/vst4_s64", "armintr/_CountLeadingOnes", "armintr/_arm_smlabt", "arm_neon/vcombine_s32", "arm_neon/vld4_lane_f16", "arm_neon/vadd_s64", "arm_neon/vorrq_u32", "armintr/__sev", "arm_neon/vdupq_lane_s32", "arm_neon/vrecpsq_f32", "arm_neon/vbicq_u16", "arm_neon/vld1_lane_p16", "arm_neon/vrshr_n_u32", "arm_neon/vcgeq_s32", "arm_neon/vld4_dup_s16", "arm_neon/vld1q_p8", "arm_neon/vrshlq_u16", "arm_neon/vmlaq_lane_u32", "arm_neon/vsub_s64", "arm_neon/vcreate_u16", "arm_neon/vget_lane_s32", "arm_neon/vuzp_f32", "arm_neon/vld2_lane_p8", "arm_neon/vuzp_u16", "arm_neon/vorrq_s16", "armintr/_arm_smlaltb", "arm_neon/vrshrn_n_s16", "arm_neon/vabd_s8", "arm_neon/vnegq_s8", "arm_neon/vst4q_u16", "arm_neon/vst1q_lane_s32", "arm_neon/vst1_lane_s32", "arm_neon/vmla_u16", "arm_neon/vmls_lane_s32", "arm_neon/vtst_s8", "arm_neon/vcgeq_s8", "arm_neon/poly8x8x4_t", "arm_neon/vqsub_s64", "armintr/_arm_uqasx", "arm_neon/vld1_lane_u64", "arm_neon/vminq_s16", "arm_neon/vmulq_u32", "arm_neon/vqrshlq_u8", "arm_neon/vdupq_n_p16", "arm_neon/vld4_dup_f16", "arm_neon/vcls_s16", "arm_neon/vmov_n_u64", "arm_neon/vmla_s32", "arm_neon/vrshl_s16", "arm_neon/vcalt_f32", "arm_neon/int64x2x3_t", "arm_neon/vsub_u8", "arm_neon/vzipq_u8", "arm_neon/vrshrn_n_u64", "arm_neon/vrshlq_s32", "arm_neon/vorr_s64", "arm_neon/vqrshl_s16", "arm_neon/vceqq_u16", "arm_neon/vmulq_n_u16", "arm_neon/vmlaq_u8", "arm_neon/vsri_n_s64", "arm_neon/vld3q_u8", "arm_neon/vld1_dup_s16", "arm_neon/vld1q_s32", "arm_neon/vsri_n_s16", "arm_neon/vshlq_u8", "arm_neon/vsli_n_s64", "arm_neon/vmull_lane_u32", "arm_neon/vshl_s64", "arm_neon/vcreate_s16", "arm_neon/uint8x8x4_t", "arm_neon/vqshrn_n_s32", "arm_neon/vqshlq_u32", "arm_neon/vmlal_n_u32", "arm_neon/vtrnq_s16", "arm_neon/vshr_n_s64", "arm_neon/vst2_u16", "arm_neon/vtrn_s32", "arm_neon/vsubhn_u32", "arm_neon/vbicq_s16", "arm_neon/vsetq_lane_s8", "arm_neon/vrsubhn_s16", "arm_neon/vhsub_u8", "arm_neon/vcleq_s32", "arm_neon/vld4_dup_s8", "arm_neon/vmull_u32", "arm_neon/vrshr_n_s16", "arm_neon/vst1q_lane_s16", "arm_neon/vmlsq_lane_u32", "arm_neon/vnegq_f32", "arm_neon/vmin_s8", "arm_neon/vrev16_p8", "arm_neon/vbic_u8", "arm_neon/vclzq_u16", "arm_neon/vcge_u32", "arm_neon/vget_high_u64", "arm_neon/vabsq_s8", "arm_neon/vhaddq_u16", "arm_neon/vsraq_n_s64", "arm_neon/vld2_u32", "arm_neon/vld2_lane_f32", "arm_neon/vqrshrn_n_u32", "arm_neon/vbslq_s8", "armintr/_CountLeadingZeros64", "arm_neon/vbicq_u8", "arm_neon/vdup_lane_s8", "arm_neon/vpadd_s32", "arm_neon/vld3q_lane_f16", "arm_neon/vaba_u8", "arm_neon/vqshlq_u16", "arm_neon/vst1q_u8", "arm_neon/vst4q_lane_f16", "arm_neon/vshl_n_u16", "armintr/_arm_smladx", "arm_neon/vmla_lane_s16", "arm_neon/vornq_u8", "arm_neon/vqneg_s32", "arm_neon/vadd_s8", "arm_neon/vcle_u32", "arm_neon/vclzq_u8", "arm_neon/vtbx1_u8", "armintr/_CountLeadingOnes64", "armintr/__dsb", "arm_neon/vaddq_u32", "arm_neon/vclsq_s8", "arm_neon/vdup_n_s64", "arm_neon/vmax_s16", "arm_neon/vst2q_u32", "arm_neon/vsetq_lane_s64", "arm_neon/vtst_p8", "arm_neon/vabs_s8", "arm_neon/vqshl_n_s16", "arm_neon/vqrshrn_n_u64", "arm_neon/vaddw_s8", "armintr/_arm_uhadd16", "arm_neon/vsriq_n_p16", "arm_neon/vld4_lane_u32", "arm_neon/vneg_f32", "armintr/_MoveToCoprocessor", "arm_neon/vmvnq_s8", "arm_neon/vld1q_lane_p8", "arm_neon/uint32x2x3_t", "arm_neon/vrshrn_n_u16", "arm_neon/vld3_f16", "arm_neon/vsriq_n_s16", "arm_neon/vshlq_n_s16", "arm_neon/vabal_u8", "arm_neon/vqshluq_n_s16", "arm_neon/vst2_lane_u16", "arm_neon/vbic_s16", "arm_neon/vqshl_n_u64", "arm_neon/vcagt_f32", "arm_neon/vpadalq_s8", "arm_neon/vclz_s32", "arm_neon/vld1_lane_s64", "arm_neon/vget_high_p8", "arm_neon/uint64x1_t", "arm_neon/vextq_s16", "arm_neon/vpadd_s8", "arm_neon/vrsubhn_u64", "arm_neon/vst3q_f16", "arm_neon/vdupq_lane_u16", "arm_neon/vrshrq_n_u64", "arm_neon/vmovq_n_f32", "arm_neon/vld1q_dup_u16", "arm_neon/vshr_n_u16", "arm_neon/uint32x2_t", "armintr/_arm_umull", "arm_neon/vtrnq_u16", "arm_neon/vsetq_lane_u32", "arm_neon/vneg_s8", "arm_neon/vsetq_lane_u8", "arm_neon/vst2q_lane_s16", "arm_neon/vqmovun_s32", "armintr/_arm_usad8", "armintr/_arm_pkhbt", "arm_neon/uint16x4x3_t", "arm_neon/vsra_n_s32", "arm_neon/vqmovun_s64", "arm_neon/vld1q_dup_s8", "arm_neon/vaddhn_s32", "arm_neon/vpmax_f32", "arm_neon/vpadd_u32", "arm_neon/vhsubq_u32", "arm_neon/vqrshrun_n_s32", "arm_neon/vadd_s32", "arm_neon/vclt_s8", "arm_neon/vorrq_s64", "arm_neon/vst4q_f16", "arm_neon/vst1_s32", "arm_neon/vceq_p8", "arm_neon/vsubw_s16", "arm_neon/vgetq_lane_u64", "arm_neon/vmla_n_u32", "arm_neon/vcvtq_f32_s32", "arm_neon/vld1q_u32", "arm_neon/vmax_f32", "armintr/_isunorderedf", "arm_neon/vrshl_u8", "arm_neon/vld4_dup_s64", "arm_neon/vqaddq_u16", "arm_neon/vld4q_lane_f16", "arm_neon/vceqq_p8", "arm_neon/vsubw_u8", "arm_neon/vqmovn_u16", "armintr/_arm_smlsldx", "arm_neon/vcreate_p8", "arm_neon/vqdmull_n_s32", "arm_neon/uint64x2_t", "arm_neon/vmls_s32", "arm_neon/vst3q_f32", "armintr/_arm_bfi", "armintr/_arm_qadd16", "arm_neon/vrshlq_s8", "arm_neon/vget_lane_p16", "arm_neon/vld2_p8", "arm_neon/vld3_lane_u32", "armintr/_MoveFromCoprocessor2", "arm_neon/vqshl_u8", "arm_neon/poly8_t", "arm_neon/vhadd_u16", "arm_neon/vmla_lane_u16", "arm_neon/vshrq_n_u8", "arm_neon/vuzpq_f32", "arm_neon/vmls_lane_f32", "arm_neon/vqneg_s16", "arm_neon/vtrn_p16", "arm_neon/vshrn_n_u32", "arm_neon/vaddhn_u64", "arm_neon/vabal_u32", "arm_neon/vld1q_lane_u32", "arm_neon/vrsraq_n_s32", "arm_neon/vandq_u64", "arm_neon/vqdmull_s32", "arm_neon/vext_s16", "arm_neon/vaddw_s16", "arm_neon/vrev64q_p8", "arm_neon/uint8x8x3_t", "arm_neon/vzip_f32", "armintr/_arm_ssub8", "arm_neon/uint16x4x4_t", "armintr/__swi", "armintr/_arm_smlatb", "arm_neon/vrhaddq_s8", "arm_neon/vpmax_s32", "arm_neon/vqshl_s64", "arm_neon/vrev16q_p8", "arm_neon/vqmovn_u32", "arm_neon/vld1q_f16", "arm_neon/vornq_u64", "arm_neon/vqshlq_n_s16", "arm_neon/vld1_f16", "armintr/_arm_smmlsr", "arm_neon/vshlq_s16", "arm_neon/vsubhn_s16", "arm_neon/vmulq_p8", "arm_neon/vdupq_lane_f32", "armintr/_arm_shadd16", "arm_neon/vornq_s16", "arm_neon/vst1q_lane_u8", "arm_neon/vcaleq_f32", "arm_neon/vst3q_lane_f16", "armintr/_arm_sdiv", "arm_neon/vld2_u16", "arm_neon/vdup_lane_u16", "arm_neon/vst4q_lane_f32", "arm_neon/vdup_n_f32", "arm_neon/vsubq_u8", "arm_neon/vset_lane_p16", "arm_neon/vrsqrte_f32", "arm_neon/vsubl_u8", "arm_neon/vld3q_lane_f32", "arm_neon/vqnegq_s8", "arm_neon/vqmovn_s16", "arm_neon/int16x8x3_t", "arm_neon/veorq_u16", "arm_neon/vqdmulh_n_s16", "arm_neon/vhaddq_u8", "arm_neon/vpadal_u8", "arm_neon/vst2q_s16", "arm_neon/poly16x8x4_t", "arm_neon/int64x2_t", "arm_neon/vmull_s32", "arm_neon/vld4_lane_s32", "arm_neon/vst4q_p8", "arm_neon/vmlal_lane_u16", "arm_neon/vclz_u32", "arm_neon/vsliq_n_s8", "arm_neon/vmls_n_f32", "arm_neon/vmlsl_lane_s16", "arm_neon/vst4q_u32", "arm_neon/vld1q_lane_s16", "arm_neon/vst1q_f32", "arm_neon/vrshr_n_u8", "arm_neon/vst1q_s64", "arm_neon/vbslq_u32", "arm_neon/vset_lane_s8", "arm_neon/vdupq_lane_p16", "arm_neon/vtstq_s16", "arm_neon/vshl_n_s8", "arm_neon/vqrdmulhq_n_s16", "arm_neon/vget_high_f16", "arm_neon/vst4_lane_u32", "arm_neon/vraddhn_s16", "arm_neon/vmlsl_lane_s32", "arm_neon/vld3q_s32", "arm_neon/vsriq_n_u64", "arm_neon/vld4_dup_u8", "arm_neon/vld4q_s8", "arm_neon/vqmovn_s64", "arm_neon/vrev32q_p8", "arm_neon/vsliq_n_p8", "arm_neon/vzipq_s16", "arm_neon/vgetq_lane_s64", "arm_neon/vst4_p16", "arm_neon/vsubq_u16", "arm_neon/vrev64_s32", "armintr/_arm_uhadd8", "arm_neon/vornq_u16", "arm_neon/vst4_lane_s8", "arm_neon/vabd_s32", "arm_neon/vqrdmulhq_s16", "arm_neon/vqshlq_s32", "arm_neon/int64x2x4_t", "arm_neon/vset_lane_u16", "arm_neon/vrsra_n_s32", "arm_neon/vabdl_u16", "arm_neon/vsliq_n_s32"] helpviewer_keywords: ["cl.exe compiler, ARM intrinsics", "intrinsics, ARM", "__cps ARM intrinsic", "__dmb ARM intrinsic", "__dsb ARM intrinsic", "__emit ARM intrinsic", "__hvc ARM intrinsic", "__isb ARM intrinsic", "__iso_volatile_load16 ARM intrinsic", "__iso_volatile_load32 ARM intrinsic", "__iso_volatile_load64 ARM intrinsic", "__iso_volatile_load8 ARM intrinsic", "__iso_volatile_store16 ARM intrinsic", "__iso_volatile_store32 ARM intrinsic", "__iso_volatile_store64 ARM intrinsic", "__iso_volatile_store8 ARM intrinsic", "__ldrexd ARM intrinsic", "__prefetch ARM intrinsic", "__rdpmccntr64 ARM intrinsic", "__sev ARM intrinsic", "__static_assert ARM intrinsic", "__swi ARM intrinsic", "__trap ARM intrinsic", "__wfe ARM intrinsic", "__wfi ARM intrinsic", "_AddSatInt ARM intrinsic", "_arm_bfc ARM intrinsic", "_arm_bfi ARM intrinsic", "_arm_clz ARM intrinsic", "_arm_pkhbt ARM intrinsic", "_arm_pkhtb ARM intrinsic", "_arm_qadd ARM intrinsic", "_arm_qadd16 ARM intrinsic", "_arm_qadd8 ARM intrinsic", "_arm_qasx ARM intrinsic", "_arm_qdadd ARM intrinsic", "_arm_qdsub ARM intrinsic", "_arm_qsax ARM intrinsic", "_arm_qsub ARM intrinsic", "_arm_qsub16 ARM intrinsic", "_arm_qsub8 ARM intrinsic", "_arm_rbit ARM intrinsic", "_arm_rev ARM intrinsic", "_arm_rev16 ARM intrinsic", "_arm_revsh ARM intrinsic", "_arm_sadd16 ARM intrinsic", "_arm_sadd8 ARM intrinsic", "_arm_sasx ARM intrinsic", "_arm_sbfx ARM intrinsic", "_arm_sdiv ARM intrinsic", "_arm_shadd16 ARM intrinsic", "_arm_shadd8 ARM intrinsic", "_arm_shasx ARM intrinsic", "_arm_shsax ARM intrinsic", "_arm_shsub16 ARM intrinsic", "_arm_shsub8 ARM intrinsic", "_arm_smlabb ARM intrinsic", "_arm_smlabt ARM intrinsic", "_arm_smlad ARM intrinsic", "_arm_smladx ARM intrinsic", "_arm_smlal ARM intrinsic", "_arm_smlalbb ARM intrinsic", "_arm_smlalbt ARM intrinsic", "_arm_smlald ARM intrinsic", "_arm_smlaldx ARM intrinsic", "_arm_smlaltb ARM intrinsic", "_arm_smlaltt ARM intrinsic", "_arm_smlatb ARM intrinsic", "_arm_smlatt ARM intrinsic", "_arm_smlawb ARM intrinsic", "_arm_smlawt ARM intrinsic", "_arm_smlsd ARM intrinsic", "_arm_smlsdx ARM intrinsic", "_arm_smlsld ARM intrinsic", "_arm_smlsldx ARM intrinsic", "_arm_smmla ARM intrinsic", "_arm_smmlar ARM intrinsic", "_arm_smmls ARM intrinsic", "_arm_smmlsr ARM intrinsic", "_arm_smmul ARM intrinsic", "_arm_smmulr ARM intrinsic", "_arm_smuad ARM intrinsic", "_arm_smuadx ARM intrinsic", "_arm_smulbb ARM intrinsic", "_arm_smulbt ARM intrinsic", "_arm_smull ARM intrinsic", "_arm_smultb ARM intrinsic", "_arm_smultt ARM intrinsic", "_arm_smulwb ARM intrinsic", "_arm_smulwt ARM intrinsic", "_arm_smusd ARM intrinsic", "_arm_smusdx ARM intrinsic", "_arm_ssat ARM intrinsic", "_arm_ssat16 ARM intrinsic", "_arm_ssax ARM intrinsic", "_arm_ssub16 ARM intrinsic", "_arm_ssub8 ARM intrinsic", "_arm_sxtab ARM intrinsic", "_arm_sxtab16 ARM intrinsic", "_arm_sxtah ARM intrinsic", "_arm_sxtb ARM intrinsic", "_arm_sxtb16 ARM intrinsic", "_arm_sxth ARM intrinsic", "_arm_uadd16 ARM intrinsic", "_arm_uadd8 ARM intrinsic", "_arm_uasx ARM intrinsic", "_arm_ubfx ARM intrinsic", "_arm_udiv ARM intrinsic", "_arm_uhadd16 ARM intrinsic", "_arm_uhadd8 ARM intrinsic", "_arm_uhasx ARM intrinsic", "_arm_uhsax ARM intrinsic", "_arm_uhsub16 ARM intrinsic", "_arm_uhsub8 ARM intrinsic", "_arm_umaal ARM intrinsic", "_arm_umlal ARM intrinsic", "_arm_umull ARM intrinsic", "_arm_uqadd16 ARM intrinsic", "_arm_uqadd8 ARM intrinsic", "_arm_uqasx ARM intrinsic", "_arm_uqsax ARM intrinsic", "_arm_uqsub16 ARM intrinsic", "_arm_uqsub8 ARM intrinsic", "_arm_usad8 ARM intrinsic", "_arm_usada8 ARM intrinsic", "_arm_usat ARM intrinsic", "_arm_usat16 ARM intrinsic", "_arm_usax ARM intrinsic", "_arm_usub16 ARM intrinsic", "_arm_usub8 ARM intrinsic", "_arm_uxtab ARM intrinsic", "_arm_uxtab16 ARM intrinsic", "_arm_uxtah ARM intrinsic", "_arm_uxtb ARM intrinsic", "_arm_uxtb16 ARM intrinsic", "_arm_uxth ARM intrinsic", "_CopyDoubleFromInt64 ARM intrinsic", "_CopyFloatFromInt32 ARM intrinsic", "_CopyInt32FromFloat ARM intrinsic", "_CopyInt64FromDouble ARM intrinsic", "_CountLeadingOnes ARM intrinsic", "_CountLeadingOnes64 ARM intrinsic", "_CountLeadingSigns ARM intrinsic", "_CountLeadingSigns64 ARM intrinsic", "_CountLeadingZeros ARM intrinsic", "_CountLeadingZeros64 ARM intrinsic", "_CountOneBits ARM intrinsic", "_CountOneBits64 ARM intrinsic", "_DAddSatInt ARM intrinsic", "_DSubSatInt ARM intrinsic", "_isunordered ARM intrinsic", "_isunorderedf ARM intrinsic", "_MoveFromCoprocessor ARM intrinsic", "_MoveFromCoprocessor2 ARM intrinsic", "_MoveFromCoprocessor64 ARM intrinsic", "_MoveToCoprocessor ARM intrinsic", "_MoveToCoprocessor2 ARM intrinsic", "_MoveToCoprocessor64 ARM intrinsic", "_MulHigh ARM intrinsic", "_MulUnsignedHigh ARM intrinsic", "_ReadBankedReg ARM intrinsic", "_ReadStatusReg ARM intrinsic", "_SubSatInt ARM intrinsic", "_WriteBankedReg ARM intrinsic", "_WriteStatusReg ARM intrinsic", "float32x2_t ARM intrinsic", "float32x2x2_t ARM intrinsic", "float32x2x3_t ARM intrinsic", "float32x2x4_t ARM intrinsic", "float32x4_t ARM intrinsic", "float32x4x2_t ARM intrinsic", "float32x4x3_t ARM intrinsic", "float32x4x4_t ARM intrinsic", "int16x4_t ARM intrinsic", "int16x4x2_t ARM intrinsic", "int16x4x3_t ARM intrinsic", "int16x4x4_t ARM intrinsic", "int16x8_t ARM intrinsic", "int16x8x2_t ARM intrinsic", "int16x8x3_t ARM intrinsic", "int16x8x4_t ARM intrinsic", "int32x2_t ARM intrinsic", "int32x2x2_t ARM intrinsic", "int32x2x3_t ARM intrinsic", "int32x2x4_t ARM intrinsic", "int32x4_t ARM intrinsic", "int32x4x2_t ARM intrinsic", "int32x4x3_t ARM intrinsic", "int32x4x4_t ARM intrinsic", "int64x1_t ARM intrinsic", "int64x1x2_t ARM intrinsic", "int64x1x3_t ARM intrinsic", "int64x1x4_t ARM intrinsic", "int64x2_t ARM intrinsic", "int64x2x2_t ARM intrinsic", "int64x2x3_t ARM intrinsic", "int64x2x4_t ARM intrinsic", "int8x16_t ARM intrinsic", "int8x16x2_t ARM intrinsic", "int8x16x3_t ARM intrinsic", "int8x16x4_t ARM intrinsic", "int8x8_t ARM intrinsic", "int8x8x2_t ARM intrinsic", "int8x8x3_t ARM intrinsic", "int8x8x4_t ARM intrinsic", "poly16_t ARM intrinsic", "poly16x4_t ARM intrinsic", "poly16x4x2_t ARM intrinsic", "poly16x4x3_t ARM intrinsic", "poly16x4x4_t ARM intrinsic", "poly16x8_t ARM intrinsic", "poly16x8x2_t ARM intrinsic", "poly16x8x3_t ARM intrinsic", "poly16x8x4_t ARM intrinsic", "poly8_t ARM intrinsic", "poly8x16_t ARM intrinsic", "poly8x16x2_t ARM intrinsic", "poly8x16x3_t ARM intrinsic", "poly8x16x4_t ARM intrinsic", "poly8x8_t ARM intrinsic", "poly8x8x2_t ARM intrinsic", "poly8x8x3_t ARM intrinsic", "poly8x8x4_t ARM intrinsic", "uint16x4_t ARM intrinsic", "uint16x4x2_t ARM intrinsic", "uint16x4x3_t ARM intrinsic", "uint16x4x4_t ARM intrinsic", "uint16x8_t ARM intrinsic", "uint16x8x2_t ARM intrinsic", "uint16x8x3_t ARM intrinsic", "uint16x8x4_t ARM intrinsic", "uint32x2_t ARM intrinsic", "uint32x2x2_t ARM intrinsic", "uint32x2x3_t ARM intrinsic", "uint32x2x4_t ARM intrinsic", "uint32x4_t ARM intrinsic", "uint32x4x2_t ARM intrinsic", "uint32x4x3_t ARM intrinsic", "uint32x4x4_t ARM intrinsic", "uint64x1_t ARM intrinsic", "uint64x1x2_t ARM intrinsic", "uint64x1x3_t ARM intrinsic", "uint64x1x4_t ARM intrinsic", "uint64x2_t ARM intrinsic", "uint64x2x2_t ARM intrinsic", "uint64x2x3_t ARM intrinsic", "uint64x2x4_t ARM intrinsic", "uint8x16_t ARM intrinsic", "uint8x16x2_t ARM intrinsic", "uint8x16x3_t ARM intrinsic", "uint8x16x4_t ARM intrinsic", "uint8x8_t ARM intrinsic", "uint8x8x2_t ARM intrinsic", "uint8x8x3_t ARM intrinsic", "uint8x8x4_t ARM intrinsic", "vaba_s16 ARM intrinsic", "vaba_s32 ARM intrinsic", "vaba_s8 ARM intrinsic", "vaba_u16 ARM intrinsic", "vaba_u32 ARM intrinsic", "vaba_u8 ARM intrinsic", "vabal_s16 ARM intrinsic", "vabal_s32 ARM intrinsic", "vabal_s8 ARM intrinsic", "vabal_u16 ARM intrinsic", "vabal_u32 ARM intrinsic", "vabal_u8 ARM intrinsic", "vabaq_s16 ARM intrinsic", "vabaq_s32 ARM intrinsic", "vabaq_s8 ARM intrinsic", "vabaq_u16 ARM intrinsic", "vabaq_u32 ARM intrinsic", "vabaq_u8 ARM intrinsic", "vabd_f32 ARM intrinsic", "vabd_s16 ARM intrinsic", "vabd_s32 ARM intrinsic", "vabd_s8 ARM intrinsic", "vabd_u16 ARM intrinsic", "vabd_u32 ARM intrinsic", "vabd_u8 ARM intrinsic", "vabdl_s16 ARM intrinsic", "vabdl_s32 ARM intrinsic", "vabdl_s8 ARM intrinsic", "vabdl_u16 ARM intrinsic", "vabdl_u32 ARM intrinsic", "vabdl_u8 ARM intrinsic", "vabdq_f32 ARM intrinsic", "vabdq_s16 ARM intrinsic", "vabdq_s32 ARM intrinsic", "vabdq_s8 ARM intrinsic", "vabdq_u16 ARM intrinsic", "vabdq_u32 ARM intrinsic", "vabdq_u8 ARM intrinsic", "vabs_f32 ARM intrinsic", "vabs_s16 ARM intrinsic", "vabs_s32 ARM intrinsic", "vabs_s8 ARM intrinsic", "vabsq_f32 ARM intrinsic", "vabsq_s16 ARM intrinsic", "vabsq_s32 ARM intrinsic", "vabsq_s8 ARM intrinsic", "vadd_f32 ARM intrinsic", "vadd_s16 ARM intrinsic", "vadd_s32 ARM intrinsic", "vadd_s64 ARM intrinsic", "vadd_s8 ARM intrinsic", "vadd_u16 ARM intrinsic", "vadd_u32 ARM intrinsic", "vadd_u64 ARM intrinsic", "vadd_u8 ARM intrinsic", "vaddhn_s16 ARM intrinsic", "vaddhn_s32 ARM intrinsic", "vaddhn_s64 ARM intrinsic", "vaddhn_u16 ARM intrinsic", "vaddhn_u32 ARM intrinsic", "vaddhn_u64 ARM intrinsic", "vaddl_s16 ARM intrinsic", "vaddl_s32 ARM intrinsic", "vaddl_s8 ARM intrinsic", "vaddl_u16 ARM intrinsic", "vaddl_u32 ARM intrinsic", "vaddl_u8 ARM intrinsic", "vaddq_f32 ARM intrinsic", "vaddq_s16 ARM intrinsic", "vaddq_s32 ARM intrinsic", "vaddq_s64 ARM intrinsic", "vaddq_s8 ARM intrinsic", "vaddq_u16 ARM intrinsic", "vaddq_u32 ARM intrinsic", "vaddq_u64 ARM intrinsic", "vaddq_u8 ARM intrinsic", "vaddw_s16 ARM intrinsic", "vaddw_s32 ARM intrinsic", "vaddw_s8 ARM intrinsic", "vaddw_u16 ARM intrinsic", "vaddw_u32 ARM intrinsic", "vaddw_u8 ARM intrinsic", "vand_s16 ARM intrinsic", "vand_s32 ARM intrinsic", "vand_s64 ARM intrinsic", "vand_s8 ARM intrinsic", "vand_u16 ARM intrinsic", "vand_u32 ARM intrinsic", "vand_u64 ARM intrinsic", "vand_u8 ARM intrinsic", "vandq_s16 ARM intrinsic", "vandq_s32 ARM intrinsic", "vandq_s64 ARM intrinsic", "vandq_s8 ARM intrinsic", "vandq_u16 ARM intrinsic", "vandq_u32 ARM intrinsic", "vandq_u64 ARM intrinsic", "vandq_u8 ARM intrinsic", "vbic_s16 ARM intrinsic", "vbic_s32 ARM intrinsic", "vbic_s64 ARM intrinsic", "vbic_s8 ARM intrinsic", "vbic_u16 ARM intrinsic", "vbic_u32 ARM intrinsic", "vbic_u64 ARM intrinsic", "vbic_u8 ARM intrinsic", "vbicq_s16 ARM intrinsic", "vbicq_s32 ARM intrinsic", "vbicq_s64 ARM intrinsic", "vbicq_s8 ARM intrinsic", "vbicq_u16 ARM intrinsic", "vbicq_u32 ARM intrinsic", "vbicq_u64 ARM intrinsic", "vbicq_u8 ARM intrinsic", "vbsl_f32 ARM intrinsic", "vbsl_p16 ARM intrinsic", "vbsl_p8 ARM intrinsic", "vbsl_s16 ARM intrinsic", "vbsl_s32 ARM intrinsic", "vbsl_s64 ARM intrinsic", "vbsl_s8 ARM intrinsic", "vbsl_u16 ARM intrinsic", "vbsl_u32 ARM intrinsic", "vbsl_u64 ARM intrinsic", "vbsl_u8 ARM intrinsic", "vbslq_f32 ARM intrinsic", "vbslq_p16 ARM intrinsic", "vbslq_p8 ARM intrinsic", "vbslq_s16 ARM intrinsic", "vbslq_s32 ARM intrinsic", "vbslq_s64 ARM intrinsic", "vbslq_s8 ARM intrinsic", "vbslq_u16 ARM intrinsic", "vbslq_u32 ARM intrinsic", "vbslq_u64 ARM intrinsic", "vbslq_u8 ARM intrinsic", "vcage_f32 ARM intrinsic", "vcageq_f32 ARM intrinsic", "vcagt_f32 ARM intrinsic", "vcagtq_f32 ARM intrinsic", "vcale_f32 ARM intrinsic", "vcaleq_f32 ARM intrinsic", "vcalt_f32 ARM intrinsic", "vcaltq_f32 ARM intrinsic", "vceq_f32 ARM intrinsic", "vceq_p8 ARM intrinsic", "vceq_s16 ARM intrinsic", "vceq_s32 ARM intrinsic", "vceq_s8 ARM intrinsic", "vceq_u16 ARM intrinsic", "vceq_u32 ARM intrinsic", "vceq_u8 ARM intrinsic", "vceqq_f32 ARM intrinsic", "vceqq_p8 ARM intrinsic", "vceqq_s16 ARM intrinsic", "vceqq_s32 ARM intrinsic", "vceqq_s8 ARM intrinsic", "vceqq_u16 ARM intrinsic", "vceqq_u32 ARM intrinsic", "vceqq_u8 ARM intrinsic", "vcge_f32 ARM intrinsic", "vcge_s16 ARM intrinsic", "vcge_s32 ARM intrinsic", "vcge_s8 ARM intrinsic", "vcge_u16 ARM intrinsic", "vcge_u32 ARM intrinsic", "vcge_u8 ARM intrinsic", "vcgeq_f32 ARM intrinsic", "vcgeq_s16 ARM intrinsic", "vcgeq_s32 ARM intrinsic", "vcgeq_s8 ARM intrinsic", "vcgeq_u16 ARM intrinsic", "vcgeq_u32 ARM intrinsic", "vcgeq_u8 ARM intrinsic", "vcgt_f32 ARM intrinsic", "vcgt_s16 ARM intrinsic", "vcgt_s32 ARM intrinsic", "vcgt_s8 ARM intrinsic", "vcgt_u16 ARM intrinsic", "vcgt_u32 ARM intrinsic", "vcgt_u8 ARM intrinsic", "vcgtq_f32 ARM intrinsic", "vcgtq_s16 ARM intrinsic", "vcgtq_s32 ARM intrinsic", "vcgtq_s8 ARM intrinsic", "vcgtq_u16 ARM intrinsic", "vcgtq_u32 ARM intrinsic", "vcgtq_u8 ARM intrinsic", "vcle_f32 ARM intrinsic", "vcle_s16 ARM intrinsic", "vcle_s32 ARM intrinsic", "vcle_s8 ARM intrinsic", "vcle_u16 ARM intrinsic", "vcle_u32 ARM intrinsic", "vcle_u8 ARM intrinsic", "vcleq_f32 ARM intrinsic", "vcleq_s16 ARM intrinsic", "vcleq_s32 ARM intrinsic", "vcleq_s8 ARM intrinsic", "vcleq_u16 ARM intrinsic", "vcleq_u32 ARM intrinsic", "vcleq_u8 ARM intrinsic", "vcls_s16 ARM intrinsic", "vcls_s32 ARM intrinsic", "vcls_s8 ARM intrinsic", "vclsq_s16 ARM intrinsic", "vclsq_s32 ARM intrinsic", "vclsq_s8 ARM intrinsic", "vclt_f32 ARM intrinsic", "vclt_s16 ARM intrinsic", "vclt_s32 ARM intrinsic", "vclt_s8 ARM intrinsic", "vclt_u16 ARM intrinsic", "vclt_u32 ARM intrinsic", "vclt_u8 ARM intrinsic", "vcltq_f32 ARM intrinsic", "vcltq_s16 ARM intrinsic", "vcltq_s32 ARM intrinsic", "vcltq_s8 ARM intrinsic", "vcltq_u16 ARM intrinsic", "vcltq_u32 ARM intrinsic", "vcltq_u8 ARM intrinsic", "vclz_s16 ARM intrinsic", "vclz_s32 ARM intrinsic", "vclz_s8 ARM intrinsic", "vclz_u16 ARM intrinsic", "vclz_u32 ARM intrinsic", "vclz_u8 ARM intrinsic", "vclzq_s16 ARM intrinsic", "vclzq_s32 ARM intrinsic", "vclzq_s8 ARM intrinsic", "vclzq_u16 ARM intrinsic", "vclzq_u32 ARM intrinsic", "vclzq_u8 ARM intrinsic", "vcnt_p8 ARM intrinsic", "vcnt_s8 ARM intrinsic", "vcnt_u8 ARM intrinsic", "vcntq_p8 ARM intrinsic", "vcntq_s8 ARM intrinsic", "vcntq_u8 ARM intrinsic", "vcombine_f16 ARM intrinsic", "vcombine_f32 ARM intrinsic", "vcombine_p16 ARM intrinsic", "vcombine_p8 ARM intrinsic", "vcombine_s16 ARM intrinsic", "vcombine_s32 ARM intrinsic", "vcombine_s64 ARM intrinsic", "vcombine_s8 ARM intrinsic", "vcombine_u16 ARM intrinsic", "vcombine_u32 ARM intrinsic", "vcombine_u64 ARM intrinsic", "vcombine_u8 ARM intrinsic", "vcreate_f16 ARM intrinsic", "vcreate_f32 ARM intrinsic", "vcreate_p16 ARM intrinsic", "vcreate_p8 ARM intrinsic", "vcreate_s16 ARM intrinsic", "vcreate_s32 ARM intrinsic", "vcreate_s64 ARM intrinsic", "vcreate_s8 ARM intrinsic", "vcreate_u16 ARM intrinsic", "vcreate_u32 ARM intrinsic", "vcreate_u64 ARM intrinsic", "vcreate_u8 ARM intrinsic", "vcvt_f16_f32 ARM intrinsic", "vcvt_f32_f16 ARM intrinsic", "vcvt_f32_s32 ARM intrinsic", "vcvt_f32_u32 ARM intrinsic", "vcvt_n_f32_s32 ARM intrinsic", "vcvt_n_f32_u32 ARM intrinsic", "vcvt_n_s32_f32 ARM intrinsic", "vcvt_n_u32_f32 ARM intrinsic", "vcvt_s32_f32 ARM intrinsic", "vcvt_u32_f32 ARM intrinsic", "vcvtq_f32_s32 ARM intrinsic", "vcvtq_f32_u32 ARM intrinsic", "vcvtq_n_f32_s32 ARM intrinsic", "vcvtq_n_f32_u32 ARM intrinsic", "vcvtq_n_s32_f32 ARM intrinsic", "vcvtq_n_u32_f32 ARM intrinsic", "vcvtq_s32_f32 ARM intrinsic", "vcvtq_u32_f32 ARM intrinsic", "vdup_lane_f32 ARM intrinsic", "vdup_lane_p16 ARM intrinsic", "vdup_lane_p8 ARM intrinsic", "vdup_lane_s16 ARM intrinsic", "vdup_lane_s32 ARM intrinsic", "vdup_lane_s64 ARM intrinsic", "vdup_lane_s8 ARM intrinsic", "vdup_lane_u16 ARM intrinsic", "vdup_lane_u32 ARM intrinsic", "vdup_lane_u64 ARM intrinsic", "vdup_lane_u8 ARM intrinsic", "vdup_n_f32 ARM intrinsic", "vdup_n_p16 ARM intrinsic", "vdup_n_p8 ARM intrinsic", "vdup_n_s16 ARM intrinsic", "vdup_n_s32 ARM intrinsic", "vdup_n_s64 ARM intrinsic", "vdup_n_s8 ARM intrinsic", "vdup_n_u16 ARM intrinsic", "vdup_n_u32 ARM intrinsic", "vdup_n_u64 ARM intrinsic", "vdup_n_u8 ARM intrinsic", "vdupq_lane_f32 ARM intrinsic", "vdupq_lane_p16 ARM intrinsic", "vdupq_lane_p8 ARM intrinsic", "vdupq_lane_s16 ARM intrinsic", "vdupq_lane_s32 ARM intrinsic", "vdupq_lane_s64 ARM intrinsic", "vdupq_lane_s8 ARM intrinsic", "vdupq_lane_u16 ARM intrinsic", "vdupq_lane_u32 ARM intrinsic", "vdupq_lane_u64 ARM intrinsic", "vdupq_lane_u8 ARM intrinsic", "vdupq_n_f32 ARM intrinsic", "vdupq_n_p16 ARM intrinsic", "vdupq_n_p8 ARM intrinsic", "vdupq_n_s16 ARM intrinsic", "vdupq_n_s32 ARM intrinsic", "vdupq_n_s64 ARM intrinsic", "vdupq_n_s8 ARM intrinsic", "vdupq_n_u16 ARM intrinsic", "vdupq_n_u32 ARM intrinsic", "vdupq_n_u64 ARM intrinsic", "vdupq_n_u8 ARM intrinsic", "veor_s16 ARM intrinsic", "veor_s32 ARM intrinsic", "veor_s64 ARM intrinsic", "veor_s8 ARM intrinsic", "veor_u16 ARM intrinsic", "veor_u32 ARM intrinsic", "veor_u64 ARM intrinsic", "veor_u8 ARM intrinsic", "veorq_s16 ARM intrinsic", "veorq_s32 ARM intrinsic", "veorq_s64 ARM intrinsic", "veorq_s8 ARM intrinsic", "veorq_u16 ARM intrinsic", "veorq_u32 ARM intrinsic", "veorq_u64 ARM intrinsic", "veorq_u8 ARM intrinsic", "vext_p16 ARM intrinsic", "vext_p8 ARM intrinsic", "vext_s16 ARM intrinsic", "vext_s32 ARM intrinsic", "vext_s64 ARM intrinsic", "vext_s8 ARM intrinsic", "vext_u16 ARM intrinsic", "vext_u32 ARM intrinsic", "vext_u64 ARM intrinsic", "vext_u8 ARM intrinsic", "vextq_p16 ARM intrinsic", "vextq_p8 ARM intrinsic", "vextq_s16 ARM intrinsic", "vextq_s32 ARM intrinsic", "vextq_s64 ARM intrinsic", "vextq_s8 ARM intrinsic", "vextq_u16 ARM intrinsic", "vextq_u32 ARM intrinsic", "vextq_u64 ARM intrinsic", "vextq_u8 ARM intrinsic", "vget_high_f16 ARM intrinsic", "vget_high_f32 ARM intrinsic", "vget_high_p16 ARM intrinsic", "vget_high_p8 ARM intrinsic", "vget_high_s16 ARM intrinsic", "vget_high_s32 ARM intrinsic", "vget_high_s64 ARM intrinsic", "vget_high_s8 ARM intrinsic", "vget_high_u16 ARM intrinsic", "vget_high_u32 ARM intrinsic", "vget_high_u64 ARM intrinsic", "vget_high_u8 ARM intrinsic", "vget_lane_f32 ARM intrinsic", "vget_lane_p16 ARM intrinsic", "vget_lane_p8 ARM intrinsic", "vget_lane_s16 ARM intrinsic", "vget_lane_s32 ARM intrinsic", "vget_lane_s64 ARM intrinsic", "vget_lane_s8 ARM intrinsic", "vget_lane_u16 ARM intrinsic", "vget_lane_u32 ARM intrinsic", "vget_lane_u64 ARM intrinsic", "vget_lane_u8 ARM intrinsic", "vget_low_f16 ARM intrinsic", "vget_low_f32 ARM intrinsic", "vget_low_p16 ARM intrinsic", "vget_low_p8 ARM intrinsic", "vget_low_s16 ARM intrinsic", "vget_low_s32 ARM intrinsic", "vget_low_s64 ARM intrinsic", "vget_low_s8 ARM intrinsic", "vget_low_u16 ARM intrinsic", "vget_low_u32 ARM intrinsic", "vget_low_u64 ARM intrinsic", "vget_low_u8 ARM intrinsic", "vgetq_lane_f32 ARM intrinsic", "vgetq_lane_p16 ARM intrinsic", "vgetq_lane_p8 ARM intrinsic", "vgetq_lane_s16 ARM intrinsic", "vgetq_lane_s32 ARM intrinsic", "vgetq_lane_s64 ARM intrinsic", "vgetq_lane_s8 ARM intrinsic", "vgetq_lane_u16 ARM intrinsic", "vgetq_lane_u32 ARM intrinsic", "vgetq_lane_u64 ARM intrinsic", "vgetq_lane_u8 ARM intrinsic", "vhadd_s16 ARM intrinsic", "vhadd_s32 ARM intrinsic", "vhadd_s8 ARM intrinsic", "vhadd_u16 ARM intrinsic", "vhadd_u32 ARM intrinsic", "vhadd_u8 ARM intrinsic", "vhaddq_s16 ARM intrinsic", "vhaddq_s32 ARM intrinsic", "vhaddq_s8 ARM intrinsic", "vhaddq_u16 ARM intrinsic", "vhaddq_u32 ARM intrinsic", "vhaddq_u8 ARM intrinsic", "vhsub_s16 ARM intrinsic", "vhsub_s32 ARM intrinsic", "vhsub_s8 ARM intrinsic", "vhsub_u16 ARM intrinsic", "vhsub_u32 ARM intrinsic", "vhsub_u8 ARM intrinsic", "vhsubq_s16 ARM intrinsic", "vhsubq_s32 ARM intrinsic", "vhsubq_s8 ARM intrinsic", "vhsubq_u16 ARM intrinsic", "vhsubq_u32 ARM intrinsic", "vhsubq_u8 ARM intrinsic", "vld1_dup_f16 ARM intrinsic", "vld1_dup_f32 ARM intrinsic", "vld1_dup_p16 ARM intrinsic", "vld1_dup_p8 ARM intrinsic", "vld1_dup_s16 ARM intrinsic", "vld1_dup_s32 ARM intrinsic", "vld1_dup_s64 ARM intrinsic", "vld1_dup_s8 ARM intrinsic", "vld1_dup_u16 ARM intrinsic", "vld1_dup_u32 ARM intrinsic", "vld1_dup_u64 ARM intrinsic", "vld1_dup_u8 ARM intrinsic", "vld1_f16 ARM intrinsic", "vld1_f32 ARM intrinsic", "vld1_lane_f32 ARM intrinsic", "vld1_lane_p16 ARM intrinsic", "vld1_lane_p8 ARM intrinsic", "vld1_lane_s16 ARM intrinsic", "vld1_lane_s32 ARM intrinsic", "vld1_lane_s64 ARM intrinsic", "vld1_lane_s8 ARM intrinsic", "vld1_lane_u16 ARM intrinsic", "vld1_lane_u32 ARM intrinsic", "vld1_lane_u64 ARM intrinsic", "vld1_lane_u8 ARM intrinsic", "vld1_p16 ARM intrinsic", "vld1_p8 ARM intrinsic", "vld1_s16 ARM intrinsic", "vld1_s32 ARM intrinsic", "vld1_s64 ARM intrinsic", "vld1_s8 ARM intrinsic", "vld1_u16 ARM intrinsic", "vld1_u32 ARM intrinsic", "vld1_u64 ARM intrinsic", "vld1_u8 ARM intrinsic", "vld1q_dup_f16 ARM intrinsic", "vld1q_dup_f32 ARM intrinsic", "vld1q_dup_p16 ARM intrinsic", "vld1q_dup_p8 ARM intrinsic", "vld1q_dup_s16 ARM intrinsic", "vld1q_dup_s32 ARM intrinsic", "vld1q_dup_s64 ARM intrinsic", "vld1q_dup_s8 ARM intrinsic", "vld1q_dup_u16 ARM intrinsic", "vld1q_dup_u32 ARM intrinsic", "vld1q_dup_u64 ARM intrinsic", "vld1q_dup_u8 ARM intrinsic", "vld1q_f16 ARM intrinsic", "vld1q_f32 ARM intrinsic", "vld1q_lane_f16 ARM intrinsic", "vld1q_lane_f32 ARM intrinsic", "vld1q_lane_p16 ARM intrinsic", "vld1q_lane_p8 ARM intrinsic", "vld1q_lane_s16 ARM intrinsic", "vld1q_lane_s32 ARM intrinsic", "vld1q_lane_s64 ARM intrinsic", "vld1q_lane_s8 ARM intrinsic", "vld1q_lane_u16 ARM intrinsic", "vld1q_lane_u32 ARM intrinsic", "vld1q_lane_u64 ARM intrinsic", "vld1q_lane_u8 ARM intrinsic", "vld1q_p16 ARM intrinsic", "vld1q_p8 ARM intrinsic", "vld1q_s16 ARM intrinsic", "vld1q_s32 ARM intrinsic", "vld1q_s64 ARM intrinsic", "vld1q_s8 ARM intrinsic", "vld1q_u16 ARM intrinsic", "vld1q_u32 ARM intrinsic", "vld1q_u64 ARM intrinsic", "vld1q_u8 ARM intrinsic", "vld2_dup_f16 ARM intrinsic", "vld2_dup_f32 ARM intrinsic", "vld2_dup_p16 ARM intrinsic", "vld2_dup_p8 ARM intrinsic", "vld2_dup_s16 ARM intrinsic", "vld2_dup_s32 ARM intrinsic", "vld2_dup_s64 ARM intrinsic", "vld2_dup_s8 ARM intrinsic", "vld2_dup_u16 ARM intrinsic", "vld2_dup_u32 ARM intrinsic", "vld2_dup_u64 ARM intrinsic", "vld2_dup_u8 ARM intrinsic", "vld2_f16 ARM intrinsic", "vld2_f32 ARM intrinsic", "vld2_lane_f16 ARM intrinsic", "vld2_lane_f32 ARM intrinsic", "vld2_lane_p16 ARM intrinsic", "vld2_lane_p8 ARM intrinsic", "vld2_lane_s16 ARM intrinsic", "vld2_lane_s32 ARM intrinsic", "vld2_lane_s8 ARM intrinsic", "vld2_lane_u16 ARM intrinsic", "vld2_lane_u32 ARM intrinsic", "vld2_lane_u8 ARM intrinsic", "vld2_p16 ARM intrinsic", "vld2_p8 ARM intrinsic", "vld2_s16 ARM intrinsic", "vld2_s32 ARM intrinsic", "vld2_s64 ARM intrinsic", "vld2_s8 ARM intrinsic", "vld2_u16 ARM intrinsic", "vld2_u32 ARM intrinsic", "vld2_u64 ARM intrinsic", "vld2_u8 ARM intrinsic", "vld2q_f16 ARM intrinsic", "vld2q_f32 ARM intrinsic", "vld2q_lane_f16 ARM intrinsic", "vld2q_lane_f32 ARM intrinsic", "vld2q_lane_p16 ARM intrinsic", "vld2q_lane_s16 ARM intrinsic", "vld2q_lane_s32 ARM intrinsic", "vld2q_lane_u16 ARM intrinsic", "vld2q_lane_u32 ARM intrinsic", "vld2q_p16 ARM intrinsic", "vld2q_p8 ARM intrinsic", "vld2q_s16 ARM intrinsic", "vld2q_s32 ARM intrinsic", "vld2q_s8 ARM intrinsic", "vld2q_u16 ARM intrinsic", "vld2q_u32 ARM intrinsic", "vld2q_u8 ARM intrinsic", "vld3_dup_f16 ARM intrinsic", "vld3_dup_f32 ARM intrinsic", "vld3_dup_p16 ARM intrinsic", "vld3_dup_p8 ARM intrinsic", "vld3_dup_s16 ARM intrinsic", "vld3_dup_s32 ARM intrinsic", "vld3_dup_s64 ARM intrinsic", "vld3_dup_s8 ARM intrinsic", "vld3_dup_u16 ARM intrinsic", "vld3_dup_u32 ARM intrinsic", "vld3_dup_u64 ARM intrinsic", "vld3_dup_u8 ARM intrinsic", "vld3_f16 ARM intrinsic", "vld3_f32 ARM intrinsic", "vld3_lane_f16 ARM intrinsic", "vld3_lane_f32 ARM intrinsic", "vld3_lane_p16 ARM intrinsic", "vld3_lane_p8 ARM intrinsic", "vld3_lane_s16 ARM intrinsic", "vld3_lane_s32 ARM intrinsic", "vld3_lane_s8 ARM intrinsic", "vld3_lane_u16 ARM intrinsic", "vld3_lane_u32 ARM intrinsic", "vld3_lane_u8 ARM intrinsic", "vld3_p16 ARM intrinsic", "vld3_p8 ARM intrinsic", "vld3_s16 ARM intrinsic", "vld3_s32 ARM intrinsic", "vld3_s64 ARM intrinsic", "vld3_s8 ARM intrinsic", "vld3_u16 ARM intrinsic", "vld3_u32 ARM intrinsic", "vld3_u64 ARM intrinsic", "vld3_u8 ARM intrinsic", "vld3q_f16 ARM intrinsic", "vld3q_f32 ARM intrinsic", "vld3q_lane_f16 ARM intrinsic", "vld3q_lane_f32 ARM intrinsic", "vld3q_lane_p16 ARM intrinsic", "vld3q_lane_s16 ARM intrinsic", "vld3q_lane_s32 ARM intrinsic", "vld3q_lane_u16 ARM intrinsic", "vld3q_lane_u32 ARM intrinsic", "vld3q_p16 ARM intrinsic", "vld3q_p8 ARM intrinsic", "vld3q_s16 ARM intrinsic", "vld3q_s32 ARM intrinsic", "vld3q_s8 ARM intrinsic", "vld3q_u16 ARM intrinsic", "vld3q_u32 ARM intrinsic", "vld3q_u8 ARM intrinsic", "vld4_dup_f16 ARM intrinsic", "vld4_dup_f32 ARM intrinsic", "vld4_dup_p16 ARM intrinsic", "vld4_dup_p8 ARM intrinsic", "vld4_dup_s16 ARM intrinsic", "vld4_dup_s32 ARM intrinsic", "vld4_dup_s64 ARM intrinsic", "vld4_dup_s8 ARM intrinsic", "vld4_dup_u16 ARM intrinsic", "vld4_dup_u32 ARM intrinsic", "vld4_dup_u64 ARM intrinsic", "vld4_dup_u8 ARM intrinsic", "vld4_f16 ARM intrinsic", "vld4_f32 ARM intrinsic", "vld4_lane_f16 ARM intrinsic", "vld4_lane_f32 ARM intrinsic", "vld4_lane_p16 ARM intrinsic", "vld4_lane_p8 ARM intrinsic", "vld4_lane_s16 ARM intrinsic", "vld4_lane_s32 ARM intrinsic", "vld4_lane_s8 ARM intrinsic", "vld4_lane_u16 ARM intrinsic", "vld4_lane_u32 ARM intrinsic", "vld4_lane_u8 ARM intrinsic", "vld4_p16 ARM intrinsic", "vld4_p8 ARM intrinsic", "vld4_s16 ARM intrinsic", "vld4_s32 ARM intrinsic", "vld4_s64 ARM intrinsic", "vld4_s8 ARM intrinsic", "vld4_u16 ARM intrinsic", "vld4_u32 ARM intrinsic", "vld4_u64 ARM intrinsic", "vld4_u8 ARM intrinsic", "vld4q_f16 ARM intrinsic", "vld4q_f32 ARM intrinsic", "vld4q_lane_f16 ARM intrinsic", "vld4q_lane_f32 ARM intrinsic", "vld4q_lane_p16 ARM intrinsic", "vld4q_lane_s16 ARM intrinsic", "vld4q_lane_s32 ARM intrinsic", "vld4q_lane_u16 ARM intrinsic", "vld4q_lane_u32 ARM intrinsic", "vld4q_p16 ARM intrinsic", "vld4q_p8 ARM intrinsic", "vld4q_s16 ARM intrinsic", "vld4q_s32 ARM intrinsic", "vld4q_s8 ARM intrinsic", "vld4q_u16 ARM intrinsic", "vld4q_u32 ARM intrinsic", "vld4q_u8 ARM intrinsic", "vmax_f32 ARM intrinsic", "vmax_s16 ARM intrinsic", "vmax_s32 ARM intrinsic", "vmax_s8 ARM intrinsic", "vmax_u16 ARM intrinsic", "vmax_u32 ARM intrinsic", "vmax_u8 ARM intrinsic", "vmaxq_f32 ARM intrinsic", "vmaxq_s16 ARM intrinsic", "vmaxq_s32 ARM intrinsic", "vmaxq_s8 ARM intrinsic", "vmaxq_u16 ARM intrinsic", "vmaxq_u32 ARM intrinsic", "vmaxq_u8 ARM intrinsic", "vmin_f32 ARM intrinsic", "vmin_s16 ARM intrinsic", "vmin_s32 ARM intrinsic", "vmin_s8 ARM intrinsic", "vmin_u16 ARM intrinsic", "vmin_u32 ARM intrinsic", "vmin_u8 ARM intrinsic", "vminq_f32 ARM intrinsic", "vminq_s16 ARM intrinsic", "vminq_s32 ARM intrinsic", "vminq_s8 ARM intrinsic", "vminq_u16 ARM intrinsic", "vminq_u32 ARM intrinsic", "vminq_u8 ARM intrinsic", "vmla_f32 ARM intrinsic", "vmla_lane_f32 ARM intrinsic", "vmla_lane_s16 ARM intrinsic", "vmla_lane_s32 ARM intrinsic", "vmla_lane_u16 ARM intrinsic", "vmla_lane_u32 ARM intrinsic", "vmla_n_f32 ARM intrinsic", "vmla_n_s16 ARM intrinsic", "vmla_n_s32 ARM intrinsic", "vmla_n_u16 ARM intrinsic", "vmla_n_u32 ARM intrinsic", "vmla_s16 ARM intrinsic", "vmla_s32 ARM intrinsic", "vmla_s8 ARM intrinsic", "vmla_u16 ARM intrinsic", "vmla_u32 ARM intrinsic", "vmla_u8 ARM intrinsic", "vmlal_lane_s16 ARM intrinsic", "vmlal_lane_s32 ARM intrinsic", "vmlal_lane_u16 ARM intrinsic", "vmlal_lane_u32 ARM intrinsic", "vmlal_n_s16 ARM intrinsic", "vmlal_n_s32 ARM intrinsic", "vmlal_n_u16 ARM intrinsic", "vmlal_n_u32 ARM intrinsic", "vmlal_s16 ARM intrinsic", "vmlal_s32 ARM intrinsic", "vmlal_s8 ARM intrinsic", "vmlal_u16 ARM intrinsic", "vmlal_u32 ARM intrinsic", "vmlal_u8 ARM intrinsic", "vmlaq_f32 ARM intrinsic", "vmlaq_lane_f32 ARM intrinsic", "vmlaq_lane_s16 ARM intrinsic", "vmlaq_lane_s32 ARM intrinsic", "vmlaq_lane_u16 ARM intrinsic", "vmlaq_lane_u32 ARM intrinsic", "vmlaq_n_f32 ARM intrinsic", "vmlaq_n_s16 ARM intrinsic", "vmlaq_n_s32 ARM intrinsic", "vmlaq_n_u16 ARM intrinsic", "vmlaq_n_u32 ARM intrinsic", "vmlaq_s16 ARM intrinsic", "vmlaq_s32 ARM intrinsic", "vmlaq_s8 ARM intrinsic", "vmlaq_u16 ARM intrinsic", "vmlaq_u32 ARM intrinsic", "vmlaq_u8 ARM intrinsic", "vmls_f32 ARM intrinsic", "vmls_lane_f32 ARM intrinsic", "vmls_lane_s16 ARM intrinsic", "vmls_lane_s32 ARM intrinsic", "vmls_lane_u16 ARM intrinsic", "vmls_lane_u32 ARM intrinsic", "vmls_n_f32 ARM intrinsic", "vmls_n_s16 ARM intrinsic", "vmls_n_s32 ARM intrinsic", "vmls_n_u16 ARM intrinsic", "vmls_n_u32 ARM intrinsic", "vmls_s16 ARM intrinsic", "vmls_s32 ARM intrinsic", "vmls_s8 ARM intrinsic", "vmls_u16 ARM intrinsic", "vmls_u32 ARM intrinsic", "vmls_u8 ARM intrinsic", "vmlsl_lane_s16 ARM intrinsic", "vmlsl_lane_s32 ARM intrinsic", "vmlsl_lane_u16 ARM intrinsic", "vmlsl_lane_u32 ARM intrinsic", "vmlsl_n_s16 ARM intrinsic", "vmlsl_n_s32 ARM intrinsic", "vmlsl_n_u16 ARM intrinsic", "vmlsl_n_u32 ARM intrinsic", "vmlsl_s16 ARM intrinsic", "vmlsl_s32 ARM intrinsic", "vmlsl_s8 ARM intrinsic", "vmlsl_u16 ARM intrinsic", "vmlsl_u32 ARM intrinsic", "vmlsl_u8 ARM intrinsic", "vmlsq_lane_f32 ARM intrinsic", "vmlsq_lane_s16 ARM intrinsic", "vmlsq_lane_s32 ARM intrinsic", "vmlsq_lane_u16 ARM intrinsic", "vmlsq_lane_u32 ARM intrinsic", "vmlsq_n_f32 ARM intrinsic", "vmlsq_n_s16 ARM intrinsic", "vmlsq_n_s32 ARM intrinsic", "vmlsq_n_u16 ARM intrinsic", "vmlsq_n_u32 ARM intrinsic", "vmlsq_s16 ARM intrinsic", "vmlsq_s32 ARM intrinsic", "vmlsq_s8 ARM intrinsic", "vmov_n_f32 ARM intrinsic", "vmov_n_p16 ARM intrinsic", "vmov_n_p8 ARM intrinsic", "vmov_n_s16 ARM intrinsic", "vmov_n_s32 ARM intrinsic", "vmov_n_s64 ARM intrinsic", "vmov_n_s8 ARM intrinsic", "vmov_n_u16 ARM intrinsic", "vmov_n_u32 ARM intrinsic", "vmov_n_u64 ARM intrinsic", "vmov_n_u8 ARM intrinsic", "vmovl_s16 ARM intrinsic", "vmovl_s32 ARM intrinsic", "vmovl_s8 ARM intrinsic", "vmovl_u16 ARM intrinsic", "vmovl_u32 ARM intrinsic", "vmovl_u8 ARM intrinsic", "vmovn_s16 ARM intrinsic", "vmovn_s32 ARM intrinsic", "vmovn_s64 ARM intrinsic", "vmovn_u16 ARM intrinsic", "vmovn_u32 ARM intrinsic", "vmovn_u64 ARM intrinsic", "vmovq_n_f32 ARM intrinsic", "vmovq_n_p16 ARM intrinsic", "vmovq_n_p8 ARM intrinsic", "vmovq_n_s16 ARM intrinsic", "vmovq_n_s32 ARM intrinsic", "vmovq_n_s64 ARM intrinsic", "vmovq_n_s8 ARM intrinsic", "vmovq_n_u16 ARM intrinsic", "vmovq_n_u32 ARM intrinsic", "vmovq_n_u64 ARM intrinsic", "vmovq_n_u8 ARM intrinsic", "vmul_f32 ARM intrinsic", "vmul_n_f32 ARM intrinsic", "vmul_n_s16 ARM intrinsic", "vmul_n_s32 ARM intrinsic", "vmul_n_u16 ARM intrinsic", "vmul_n_u32 ARM intrinsic", "vmul_p8 ARM intrinsic", "vmul_s16 ARM intrinsic", "vmul_s32 ARM intrinsic", "vmul_s8 ARM intrinsic", "vmul_u16 ARM intrinsic", "vmul_u32 ARM intrinsic", "vmul_u8 ARM intrinsic", "vmull_lane_s16 ARM intrinsic", "vmull_lane_s32 ARM intrinsic", "vmull_lane_u16 ARM intrinsic", "vmull_lane_u32 ARM intrinsic", "vmull_n_s16 ARM intrinsic", "vmull_n_s32 ARM intrinsic", "vmull_n_u16 ARM intrinsic", "vmull_n_u32 ARM intrinsic", "vmull_p8 ARM intrinsic", "vmull_s16 ARM intrinsic", "vmull_s32 ARM intrinsic", "vmull_s8 ARM intrinsic", "vmull_u16 ARM intrinsic", "vmull_u32 ARM intrinsic", "vmull_u8 ARM intrinsic", "vmulq_f32 ARM intrinsic", "vmulq_n_f32 ARM intrinsic", "vmulq_n_s16 ARM intrinsic", "vmulq_n_s32 ARM intrinsic", "vmulq_n_u16 ARM intrinsic", "vmulq_n_u32 ARM intrinsic", "vmulq_p8 ARM intrinsic", "vmulq_s16 ARM intrinsic", "vmulq_s32 ARM intrinsic", "vmulq_s8 ARM intrinsic", "vmulq_u16 ARM intrinsic", "vmulq_u32 ARM intrinsic", "vmulq_u8 ARM intrinsic", "vmvn_p8 ARM intrinsic", "vmvn_s16 ARM intrinsic", "vmvn_s32 ARM intrinsic", "vmvn_s8 ARM intrinsic", "vmvn_u16 ARM intrinsic", "vmvn_u32 ARM intrinsic", "vmvn_u8 ARM intrinsic", "vmvnq_p8 ARM intrinsic", "vmvnq_s16 ARM intrinsic", "vmvnq_s32 ARM intrinsic", "vmvnq_s8 ARM intrinsic", "vmvnq_u16 ARM intrinsic", "vmvnq_u32 ARM intrinsic", "vmvnq_u8 ARM intrinsic", "vneg_f32 ARM intrinsic", "vneg_s16 ARM intrinsic", "vneg_s32 ARM intrinsic", "vneg_s8 ARM intrinsic", "vnegq_f32 ARM intrinsic", "vnegq_s16 ARM intrinsic", "vnegq_s32 ARM intrinsic", "vnegq_s8 ARM intrinsic", "vorn_s16 ARM intrinsic", "vorn_s32 ARM intrinsic", "vorn_s64 ARM intrinsic", "vorn_s8 ARM intrinsic", "vorn_u16 ARM intrinsic", "vorn_u32 ARM intrinsic", "vorn_u64 ARM intrinsic", "vorn_u8 ARM intrinsic", "vornq_s16 ARM intrinsic", "vornq_s32 ARM intrinsic", "vornq_s64 ARM intrinsic", "vornq_s8 ARM intrinsic", "vornq_u16 ARM intrinsic", "vornq_u32 ARM intrinsic", "vornq_u64 ARM intrinsic", "vornq_u8 ARM intrinsic", "vorr_s16 ARM intrinsic", "vorr_s32 ARM intrinsic", "vorr_s64 ARM intrinsic", "vorr_s8 ARM intrinsic", "vorr_u16 ARM intrinsic", "vorr_u32 ARM intrinsic", "vorr_u64 ARM intrinsic", "vorr_u8 ARM intrinsic", "vorrq_s16 ARM intrinsic", "vorrq_s32 ARM intrinsic", "vorrq_s64 ARM intrinsic", "vorrq_s8 ARM intrinsic", "vorrq_u16 ARM intrinsic", "vorrq_u32 ARM intrinsic", "vorrq_u64 ARM intrinsic", "vorrq_u8 ARM intrinsic", "vpadal_s16 ARM intrinsic", "vpadal_s32 ARM intrinsic", "vpadal_s8 ARM intrinsic", "vpadal_u16 ARM intrinsic", "vpadal_u32 ARM intrinsic", "vpadal_u8 ARM intrinsic", "vpadalq_s16 ARM intrinsic", "vpadalq_s32 ARM intrinsic", "vpadalq_s8 ARM intrinsic", "vpadalq_u16 ARM intrinsic", "vpadalq_u32 ARM intrinsic", "vpadalq_u8 ARM intrinsic", "vpadd_f32 ARM intrinsic", "vpadd_s16 ARM intrinsic", "vpadd_s32 ARM intrinsic", "vpadd_s8 ARM intrinsic", "vpadd_u16 ARM intrinsic", "vpadd_u32 ARM intrinsic", "vpadd_u8 ARM intrinsic", "vpaddl_s16 ARM intrinsic", "vpaddl_s32 ARM intrinsic", "vpaddl_s8 ARM intrinsic", "vpaddl_u16 ARM intrinsic", "vpaddl_u32 ARM intrinsic", "vpaddl_u8 ARM intrinsic", "vpaddlq_s16 ARM intrinsic", "vpaddlq_s32 ARM intrinsic", "vpaddlq_s8 ARM intrinsic", "vpaddlq_u16 ARM intrinsic", "vpaddlq_u32 ARM intrinsic", "vpaddlq_u8 ARM intrinsic", "vpmax_f32 ARM intrinsic", "vpmax_s16 ARM intrinsic", "vpmax_s32 ARM intrinsic", "vpmax_s8 ARM intrinsic", "vpmax_u16 ARM intrinsic", "vpmax_u32 ARM intrinsic", "vpmax_u8 ARM intrinsic", "vpmin_f32 ARM intrinsic", "vpmin_s16 ARM intrinsic", "vpmin_s32 ARM intrinsic", "vpmin_s8 ARM intrinsic", "vpmin_u16 ARM intrinsic", "vpmin_u32 ARM intrinsic", "vpmin_u8 ARM intrinsic", "vqabs_s16 ARM intrinsic", "vqabs_s32 ARM intrinsic", "vqabs_s8 ARM intrinsic", "vqabsq_s16 ARM intrinsic", "vqabsq_s32 ARM intrinsic", "vqabsq_s8 ARM intrinsic", "vqadd_s16 ARM intrinsic", "vqadd_s32 ARM intrinsic", "vqadd_s64 ARM intrinsic", "vqadd_s8 ARM intrinsic", "vqadd_u16 ARM intrinsic", "vqadd_u32 ARM intrinsic", "vqadd_u64 ARM intrinsic", "vqadd_u8 ARM intrinsic", "vqaddq_s16 ARM intrinsic", "vqaddq_s32 ARM intrinsic", "vqaddq_s64 ARM intrinsic", "vqaddq_s8 ARM intrinsic", "vqaddq_u16 ARM intrinsic", "vqaddq_u32 ARM intrinsic", "vqaddq_u64 ARM intrinsic", "vqaddq_u8 ARM intrinsic", "vqdmlal_lane_s16 ARM intrinsic", "vqdmlal_lane_s32 ARM intrinsic", "vqdmlal_n_s16 ARM intrinsic", "vqdmlal_n_s32 ARM intrinsic", "vqdmlal_s16 ARM intrinsic", "vqdmlal_s32 ARM intrinsic", "vqdmlsl_lane_s16 ARM intrinsic", "vqdmlsl_lane_s32 ARM intrinsic", "vqdmlsl_n_s16 ARM intrinsic", "vqdmlsl_n_s32 ARM intrinsic", "vqdmlsl_s16 ARM intrinsic", "vqdmlsl_s32 ARM intrinsic", "vqdmulh_lane_s16 ARM intrinsic", "vqdmulh_lane_s32 ARM intrinsic", "vqdmulh_n_s16 ARM intrinsic", "vqdmulh_n_s32 ARM intrinsic", "vqdmulh_s16 ARM intrinsic", "vqdmulh_s32 ARM intrinsic", "vqdmulhq_lane_s16 ARM intrinsic", "vqdmulhq_lane_s32 ARM intrinsic", "vqdmulhq_n_s16 ARM intrinsic", "vqdmulhq_n_s32 ARM intrinsic", "vqdmulhq_s16 ARM intrinsic", "vqdmulhq_s32 ARM intrinsic", "vqdmull_lane_s16 ARM intrinsic", "vqdmull_lane_s32 ARM intrinsic", "vqdmull_n_s16 ARM intrinsic", "vqdmull_n_s32 ARM intrinsic", "vqdmull_s16 ARM intrinsic", "vqdmull_s32 ARM intrinsic", "vqmovn_s16 ARM intrinsic", "vqmovn_s32 ARM intrinsic", "vqmovn_s64 ARM intrinsic", "vqmovn_u16 ARM intrinsic", "vqmovn_u32 ARM intrinsic", "vqmovn_u64 ARM intrinsic", "vqmovun_s16 ARM intrinsic", "vqmovun_s32 ARM intrinsic", "vqmovun_s64 ARM intrinsic", "vqneg_s16 ARM intrinsic", "vqneg_s32 ARM intrinsic", "vqneg_s8 ARM intrinsic", "vqnegq_s16 ARM intrinsic", "vqnegq_s32 ARM intrinsic", "vqnegq_s8 ARM intrinsic", "vqrdmulh_lane_s16 ARM intrinsic", "vqrdmulh_lane_s32 ARM intrinsic", "vqrdmulh_n_s16 ARM intrinsic", "vqrdmulh_n_s32 ARM intrinsic", "vqrdmulh_s16 ARM intrinsic", "vqrdmulh_s32 ARM intrinsic", "vqrdmulhq_lane_s16 ARM intrinsic", "vqrdmulhq_lane_s32 ARM intrinsic", "vqrdmulhq_n_s16 ARM intrinsic", "vqrdmulhq_n_s32 ARM intrinsic", "vqrdmulhq_s16 ARM intrinsic", "vqrdmulhq_s32 ARM intrinsic", "vqrshl_s16 ARM intrinsic", "vqrshl_s32 ARM intrinsic", "vqrshl_s64 ARM intrinsic", "vqrshl_s8 ARM intrinsic", "vqrshl_u16 ARM intrinsic", "vqrshl_u32 ARM intrinsic", "vqrshl_u64 ARM intrinsic", "vqrshl_u8 ARM intrinsic", "vqrshlq_s16 ARM intrinsic", "vqrshlq_s32 ARM intrinsic", "vqrshlq_s64 ARM intrinsic", "vqrshlq_s8 ARM intrinsic", "vqrshlq_u16 ARM intrinsic", "vqrshlq_u32 ARM intrinsic", "vqrshlq_u64 ARM intrinsic", "vqrshlq_u8 ARM intrinsic", "vqrshrn_n_s16 ARM intrinsic", "vqrshrn_n_s32 ARM intrinsic", "vqrshrn_n_s64 ARM intrinsic", "vqrshrn_n_u16 ARM intrinsic", "vqrshrn_n_u32 ARM intrinsic", "vqrshrn_n_u64 ARM intrinsic", "vqrshrun_n_s16 ARM intrinsic", "vqrshrun_n_s32 ARM intrinsic", "vqrshrun_n_s64 ARM intrinsic", "vqshl_n_s16 ARM intrinsic", "vqshl_n_s32 ARM intrinsic", "vqshl_n_s64 ARM intrinsic", "vqshl_n_s8 ARM intrinsic", "vqshl_n_u16 ARM intrinsic", "vqshl_n_u32 ARM intrinsic", "vqshl_n_u64 ARM intrinsic", "vqshl_n_u8 ARM intrinsic", "vqshl_s16 ARM intrinsic", "vqshl_s32 ARM intrinsic", "vqshl_s64 ARM intrinsic", "vqshl_s8 ARM intrinsic", "vqshl_u16 ARM intrinsic", "vqshl_u32 ARM intrinsic", "vqshl_u64 ARM intrinsic", "vqshl_u8 ARM intrinsic", "vqshlq_n_s16 ARM intrinsic", "vqshlq_n_s32 ARM intrinsic", "vqshlq_n_s64 ARM intrinsic", "vqshlq_n_s8 ARM intrinsic", "vqshlq_n_u16 ARM intrinsic", "vqshlq_n_u32 ARM intrinsic", "vqshlq_n_u64 ARM intrinsic", "vqshlq_n_u8 ARM intrinsic", "vqshlq_s16 ARM intrinsic", "vqshlq_s32 ARM intrinsic", "vqshlq_s64 ARM intrinsic", "vqshlq_s8 ARM intrinsic", "vqshlq_u16 ARM intrinsic", "vqshlq_u32 ARM intrinsic", "vqshlq_u64 ARM intrinsic", "vqshlq_u8 ARM intrinsic", "vqshlu_n_s16 ARM intrinsic", "vqshlu_n_s32 ARM intrinsic", "vqshlu_n_s64 ARM intrinsic", "vqshlu_n_s8 ARM intrinsic", "vqshluq_n_s16 ARM intrinsic", "vqshluq_n_s32 ARM intrinsic", "vqshluq_n_s64 ARM intrinsic", "vqshluq_n_s8 ARM intrinsic", "vqshrn_n_s16 ARM intrinsic", "vqshrn_n_s32 ARM intrinsic", "vqshrn_n_s64 ARM intrinsic", "vqshrn_n_u16 ARM intrinsic", "vqshrn_n_u32 ARM intrinsic", "vqshrn_n_u64 ARM intrinsic", "vqshrun_n_s16 ARM intrinsic", "vqshrun_n_s32 ARM intrinsic", "vqshrun_n_s64 ARM intrinsic", "vqsub_s16 ARM intrinsic", "vqsub_s32 ARM intrinsic", "vqsub_s64 ARM intrinsic", "vqsub_s8 ARM intrinsic", "vqsub_u16 ARM intrinsic", "vqsub_u32 ARM intrinsic", "vqsub_u64 ARM intrinsic", "vqsub_u8 ARM intrinsic", "vqsubq_s16 ARM intrinsic", "vqsubq_s32 ARM intrinsic", "vqsubq_s64 ARM intrinsic", "vqsubq_s8 ARM intrinsic", "vqsubq_u16 ARM intrinsic", "vqsubq_u32 ARM intrinsic", "vqsubq_u64 ARM intrinsic", "vqsubq_u8 ARM intrinsic", "vraddhn_s16 ARM intrinsic", "vraddhn_s32 ARM intrinsic", "vraddhn_s64 ARM intrinsic", "vraddhn_u16 ARM intrinsic", "vraddhn_u32 ARM intrinsic", "vraddhn_u64 ARM intrinsic", "vrecpe_f32 ARM intrinsic", "vrecpe_u32 ARM intrinsic", "vrecpeq_f32 ARM intrinsic", "vrecpeq_u32 ARM intrinsic", "vrecps_f32 ARM intrinsic", "vrecpsq_f32 ARM intrinsic", "vrev16_p8 ARM intrinsic", "vrev16_s8 ARM intrinsic", "vrev16_u8 ARM intrinsic", "vrev16q_p8 ARM intrinsic", "vrev16q_s8 ARM intrinsic", "vrev16q_u8 ARM intrinsic", "vrev32_p8 ARM intrinsic", "vrev32_s16 ARM intrinsic", "vrev32_s8 ARM intrinsic", "vrev32_u16 ARM intrinsic", "vrev32_u8 ARM intrinsic", "vrev32q_p8 ARM intrinsic", "vrev32q_s16 ARM intrinsic", "vrev32q_s8 ARM intrinsic", "vrev32q_u16 ARM intrinsic", "vrev32q_u8 ARM intrinsic", "vrev64_f32 ARM intrinsic", "vrev64_p16 ARM intrinsic", "vrev64_p8 ARM intrinsic", "vrev64_s16 ARM intrinsic", "vrev64_s32 ARM intrinsic", "vrev64_s8 ARM intrinsic", "vrev64_u16 ARM intrinsic", "vrev64_u32 ARM intrinsic", "vrev64_u8 ARM intrinsic", "vrev64q_f32 ARM intrinsic", "vrev64q_p16 ARM intrinsic", "vrev64q_p8 ARM intrinsic", "vrev64q_s16 ARM intrinsic", "vrev64q_s32 ARM intrinsic", "vrev64q_s8 ARM intrinsic", "vrev64q_u16 ARM intrinsic", "vrev64q_u32 ARM intrinsic", "vrev64q_u8 ARM intrinsic", "vrhadd_s16 ARM intrinsic", "vrhadd_s32 ARM intrinsic", "vrhadd_s8 ARM intrinsic", "vrhadd_u16 ARM intrinsic", "vrhadd_u32 ARM intrinsic", "vrhadd_u8 ARM intrinsic", "vrhaddq_s16 ARM intrinsic", "vrhaddq_s32 ARM intrinsic", "vrhaddq_s8 ARM intrinsic", "vrhaddq_u16 ARM intrinsic", "vrhaddq_u32 ARM intrinsic", "vrhaddq_u8 ARM intrinsic", "vrshl_s16 ARM intrinsic", "vrshl_s32 ARM intrinsic", "vrshl_s64 ARM intrinsic", "vrshl_s8 ARM intrinsic", "vrshl_u16 ARM intrinsic", "vrshl_u32 ARM intrinsic", "vrshl_u64 ARM intrinsic", "vrshl_u8 ARM intrinsic", "vrshlq_s16 ARM intrinsic", "vrshlq_s32 ARM intrinsic", "vrshlq_s64 ARM intrinsic", "vrshlq_s8 ARM intrinsic", "vrshlq_u16 ARM intrinsic", "vrshlq_u32 ARM intrinsic", "vrshlq_u64 ARM intrinsic", "vrshlq_u8 ARM intrinsic", "vrshr_n_s16 ARM intrinsic", "vrshr_n_s32 ARM intrinsic", "vrshr_n_s64 ARM intrinsic", "vrshr_n_s8 ARM intrinsic", "vrshr_n_u16 ARM intrinsic", "vrshr_n_u32 ARM intrinsic", "vrshr_n_u64 ARM intrinsic", "vrshr_n_u8 ARM intrinsic", "vrshrn_n_s16 ARM intrinsic", "vrshrn_n_s32 ARM intrinsic", "vrshrn_n_s64 ARM intrinsic", "vrshrn_n_u16 ARM intrinsic", "vrshrn_n_u32 ARM intrinsic", "vrshrn_n_u64 ARM intrinsic", "vrshrq_n_s16 ARM intrinsic", "vrshrq_n_s32 ARM intrinsic", "vrshrq_n_s64 ARM intrinsic", "vrshrq_n_s8 ARM intrinsic", "vrshrq_n_u16 ARM intrinsic", "vrshrq_n_u32 ARM intrinsic", "vrshrq_n_u64 ARM intrinsic", "vrshrq_n_u8 ARM intrinsic", "vrsqrte_f32 ARM intrinsic", "vrsqrte_u32 ARM intrinsic", "vrsqrteq_f32 ARM intrinsic", "vrsqrteq_u32 ARM intrinsic", "vrsqrts_f32 ARM intrinsic", "vrsqrtsq_f32 ARM intrinsic", "vrsra_n_s16 ARM intrinsic", "vrsra_n_s32 ARM intrinsic", "vrsra_n_s64 ARM intrinsic", "vrsra_n_s8 ARM intrinsic", "vrsra_n_u16 ARM intrinsic", "vrsra_n_u32 ARM intrinsic", "vrsra_n_u64 ARM intrinsic", "vrsra_n_u8 ARM intrinsic", "vrsraq_n_s16 ARM intrinsic", "vrsraq_n_s32 ARM intrinsic", "vrsraq_n_s64 ARM intrinsic", "vrsraq_n_s8 ARM intrinsic", "vrsraq_n_u16 ARM intrinsic", "vrsraq_n_u32 ARM intrinsic", "vrsraq_n_u64 ARM intrinsic", "vrsraq_n_u8 ARM intrinsic", "vrsubhn_s16 ARM intrinsic", "vrsubhn_s32 ARM intrinsic", "vrsubhn_s64 ARM intrinsic", "vrsubhn_u16 ARM intrinsic", "vrsubhn_u32 ARM intrinsic", "vrsubhn_u64 ARM intrinsic", "vset_lane_f32 ARM intrinsic", "vset_lane_p16 ARM intrinsic", "vset_lane_p8 ARM intrinsic", "vset_lane_s16 ARM intrinsic", "vset_lane_s32 ARM intrinsic", "vset_lane_s64 ARM intrinsic", "vset_lane_s8 ARM intrinsic", "vset_lane_u16 ARM intrinsic", "vset_lane_u32 ARM intrinsic", "vset_lane_u64 ARM intrinsic", "vset_lane_u8 ARM intrinsic", "vsetq_lane_f32 ARM intrinsic", "vsetq_lane_p16 ARM intrinsic", "vsetq_lane_p8 ARM intrinsic", "vsetq_lane_s16 ARM intrinsic", "vsetq_lane_s32 ARM intrinsic", "vsetq_lane_s64 ARM intrinsic", "vsetq_lane_s8 ARM intrinsic", "vsetq_lane_u16 ARM intrinsic", "vsetq_lane_u32 ARM intrinsic", "vsetq_lane_u64 ARM intrinsic", "vsetq_lane_u8 ARM intrinsic", "vshl_n_s16 ARM intrinsic", "vshl_n_s32 ARM intrinsic", "vshl_n_s64 ARM intrinsic", "vshl_n_s8 ARM intrinsic", "vshl_n_u16 ARM intrinsic", "vshl_n_u32 ARM intrinsic", "vshl_n_u64 ARM intrinsic", "vshl_n_u8 ARM intrinsic", "vshl_s16 ARM intrinsic", "vshl_s32 ARM intrinsic", "vshl_s64 ARM intrinsic", "vshl_s8 ARM intrinsic", "vshl_u16 ARM intrinsic", "vshl_u32 ARM intrinsic", "vshl_u64 ARM intrinsic", "vshl_u8 ARM intrinsic", "vshll_n_s16 ARM intrinsic", "vshll_n_s32 ARM intrinsic", "vshll_n_s8 ARM intrinsic", "vshll_n_u16 ARM intrinsic", "vshll_n_u32 ARM intrinsic", "vshll_n_u8 ARM intrinsic", "vshlq_n_s16 ARM intrinsic", "vshlq_n_s32 ARM intrinsic", "vshlq_n_s64 ARM intrinsic", "vshlq_n_s8 ARM intrinsic", "vshlq_n_u16 ARM intrinsic", "vshlq_n_u32 ARM intrinsic", "vshlq_n_u64 ARM intrinsic", "vshlq_n_u8 ARM intrinsic", "vshlq_s16 ARM intrinsic", "vshlq_s32 ARM intrinsic", "vshlq_s64 ARM intrinsic", "vshlq_s8 ARM intrinsic", "vshlq_u16 ARM intrinsic", "vshlq_u32 ARM intrinsic", "vshlq_u64 ARM intrinsic", "vshlq_u8 ARM intrinsic", "vshr_n_s16 ARM intrinsic", "vshr_n_s32 ARM intrinsic", "vshr_n_s64 ARM intrinsic", "vshr_n_s8 ARM intrinsic", "vshr_n_u16 ARM intrinsic", "vshr_n_u32 ARM intrinsic", "vshr_n_u64 ARM intrinsic", "vshr_n_u8 ARM intrinsic", "vshrn_n_s16 ARM intrinsic", "vshrn_n_s32 ARM intrinsic", "vshrn_n_s64 ARM intrinsic", "vshrn_n_u16 ARM intrinsic", "vshrn_n_u32 ARM intrinsic", "vshrn_n_u64 ARM intrinsic", "vshrq_n_s16 ARM intrinsic", "vshrq_n_s32 ARM intrinsic", "vshrq_n_s64 ARM intrinsic", "vshrq_n_s8 ARM intrinsic", "vshrq_n_u16 ARM intrinsic", "vshrq_n_u32 ARM intrinsic", "vshrq_n_u64 ARM intrinsic", "vshrq_n_u8 ARM intrinsic", "vsli_n_p16 ARM intrinsic", "vsli_n_p8 ARM intrinsic", "vsli_n_s16 ARM intrinsic", "vsli_n_s32 ARM intrinsic", "vsli_n_s64 ARM intrinsic", "vsli_n_s8 ARM intrinsic", "vsli_n_u16 ARM intrinsic", "vsli_n_u32 ARM intrinsic", "vsli_n_u64 ARM intrinsic", "vsli_n_u8 ARM intrinsic", "vsliq_n_p16 ARM intrinsic", "vsliq_n_p8 ARM intrinsic", "vsliq_n_s16 ARM intrinsic", "vsliq_n_s32 ARM intrinsic", "vsliq_n_s64 ARM intrinsic", "vsliq_n_s8 ARM intrinsic", "vsliq_n_u16 ARM intrinsic", "vsliq_n_u32 ARM intrinsic", "vsliq_n_u64 ARM intrinsic", "vsliq_n_u8 ARM intrinsic", "vsra_n_s16 ARM intrinsic", "vsra_n_s32 ARM intrinsic", "vsra_n_s64 ARM intrinsic", "vsra_n_s8 ARM intrinsic", "vsra_n_u16 ARM intrinsic", "vsra_n_u32 ARM intrinsic", "vsra_n_u64 ARM intrinsic", "vsra_n_u8 ARM intrinsic", "vsraq_n_s16 ARM intrinsic", "vsraq_n_s32 ARM intrinsic", "vsraq_n_s64 ARM intrinsic", "vsraq_n_s8 ARM intrinsic", "vsraq_n_u16 ARM intrinsic", "vsraq_n_u32 ARM intrinsic", "vsraq_n_u64 ARM intrinsic", "vsraq_n_u8 ARM intrinsic", "vsri_n_p16 ARM intrinsic", "vsri_n_p8 ARM intrinsic", "vsri_n_s16 ARM intrinsic", "vsri_n_s32 ARM intrinsic", "vsri_n_s64 ARM intrinsic", "vsri_n_s8 ARM intrinsic", "vsri_n_u16 ARM intrinsic", "vsri_n_u32 ARM intrinsic", "vsri_n_u64 ARM intrinsic", "vsri_n_u8 ARM intrinsic", "vsriq_n_p16 ARM intrinsic", "vsriq_n_p8 ARM intrinsic", "vsriq_n_s16 ARM intrinsic", "vsriq_n_s32 ARM intrinsic", "vsriq_n_s64 ARM intrinsic", "vsriq_n_s8 ARM intrinsic", "vsriq_n_u16 ARM intrinsic", "vsriq_n_u32 ARM intrinsic", "vsriq_n_u64 ARM intrinsic", "vsriq_n_u8 ARM intrinsic", "vst1_f16 ARM intrinsic", "vst1_f32 ARM intrinsic", "vst1_lane_f16 ARM intrinsic", "vst1_lane_f32 ARM intrinsic", "vst1_lane_p16 ARM intrinsic", "vst1_lane_p8 ARM intrinsic", "vst1_lane_s16 ARM intrinsic", "vst1_lane_s32 ARM intrinsic", "vst1_lane_s64 ARM intrinsic", "vst1_lane_s8 ARM intrinsic", "vst1_lane_u16 ARM intrinsic", "vst1_lane_u32 ARM intrinsic", "vst1_lane_u64 ARM intrinsic", "vst1_lane_u8 ARM intrinsic", "vst1_p16 ARM intrinsic", "vst1_p8 ARM intrinsic", "vst1_s16 ARM intrinsic", "vst1_s32 ARM intrinsic", "vst1_s64 ARM intrinsic", "vst1_s8 ARM intrinsic", "vst1_u16 ARM intrinsic", "vst1_u32 ARM intrinsic", "vst1_u64 ARM intrinsic", "vst1_u8 ARM intrinsic", "vst1q_f16 ARM intrinsic", "vst1q_f32 ARM intrinsic", "vst1q_lane_f16 ARM intrinsic", "vst1q_lane_f32 ARM intrinsic", "vst1q_lane_p16 ARM intrinsic", "vst1q_lane_p8 ARM intrinsic", "vst1q_lane_s16 ARM intrinsic", "vst1q_lane_s32 ARM intrinsic", "vst1q_lane_s64 ARM intrinsic", "vst1q_lane_s8 ARM intrinsic", "vst1q_lane_u16 ARM intrinsic", "vst1q_lane_u32 ARM intrinsic", "vst1q_lane_u64 ARM intrinsic", "vst1q_lane_u8 ARM intrinsic", "vst1q_p16 ARM intrinsic", "vst1q_p8 ARM intrinsic", "vst1q_s16 ARM intrinsic", "vst1q_s32 ARM intrinsic", "vst1q_s64 ARM intrinsic", "vst1q_s8 ARM intrinsic", "vst1q_u16 ARM intrinsic", "vst1q_u32 ARM intrinsic", "vst1q_u64 ARM intrinsic", "vst1q_u8 ARM intrinsic", "vst2_f16 ARM intrinsic", "vst2_f32 ARM intrinsic", "vst2_lane_f16 ARM intrinsic", "vst2_lane_f32 ARM intrinsic", "vst2_lane_p16 ARM intrinsic", "vst2_lane_p8 ARM intrinsic", "vst2_lane_s16 ARM intrinsic", "vst2_lane_s32 ARM intrinsic", "vst2_lane_s8 ARM intrinsic", "vst2_lane_u16 ARM intrinsic", "vst2_lane_u32 ARM intrinsic", "vst2_lane_u8 ARM intrinsic", "vst2_p16 ARM intrinsic", "vst2_p8 ARM intrinsic", "vst2_s16 ARM intrinsic", "vst2_s32 ARM intrinsic", "vst2_s64 ARM intrinsic", "vst2_s8 ARM intrinsic", "vst2_u16 ARM intrinsic", "vst2_u32 ARM intrinsic", "vst2_u64 ARM intrinsic", "vst2_u8 ARM intrinsic", "vst2q_f16 ARM intrinsic", "vst2q_f32 ARM intrinsic", "vst2q_lane_f16 ARM intrinsic", "vst2q_lane_f32 ARM intrinsic", "vst2q_lane_p16 ARM intrinsic", "vst2q_lane_s16 ARM intrinsic", "vst2q_lane_s32 ARM intrinsic", "vst2q_lane_u16 ARM intrinsic", "vst2q_lane_u32 ARM intrinsic", "vst2q_p16 ARM intrinsic", "vst2q_p8 ARM intrinsic", "vst2q_s16 ARM intrinsic", "vst2q_s32 ARM intrinsic", "vst2q_s8 ARM intrinsic", "vst2q_u16 ARM intrinsic", "vst2q_u32 ARM intrinsic", "vst2q_u8 ARM intrinsic", "vst3_f16 ARM intrinsic", "vst3_f32 ARM intrinsic", "vst3_lane_f16 ARM intrinsic", "vst3_lane_f32 ARM intrinsic", "vst3_lane_p16 ARM intrinsic", "vst3_lane_p8 ARM intrinsic", "vst3_lane_s16 ARM intrinsic", "vst3_lane_s32 ARM intrinsic", "vst3_lane_s8 ARM intrinsic", "vst3_lane_u16 ARM intrinsic", "vst3_lane_u32 ARM intrinsic", "vst3_lane_u8 ARM intrinsic", "vst3_p16 ARM intrinsic", "vst3_p8 ARM intrinsic", "vst3_s16 ARM intrinsic", "vst3_s32 ARM intrinsic", "vst3_s64 ARM intrinsic", "vst3_s8 ARM intrinsic", "vst3_u16 ARM intrinsic", "vst3_u32 ARM intrinsic", "vst3_u64 ARM intrinsic", "vst3_u8 ARM intrinsic", "vst3q_f16 ARM intrinsic", "vst3q_f32 ARM intrinsic", "vst3q_lane_f16 ARM intrinsic", "vst3q_lane_f32 ARM intrinsic", "vst3q_lane_p16 ARM intrinsic", "vst3q_lane_s16 ARM intrinsic", "vst3q_lane_s32 ARM intrinsic", "vst3q_lane_u16 ARM intrinsic", "vst3q_lane_u32 ARM intrinsic", "vst3q_p16 ARM intrinsic", "vst3q_p8 ARM intrinsic", "vst3q_s16 ARM intrinsic", "vst3q_s32 ARM intrinsic", "vst3q_s8 ARM intrinsic", "vst3q_u16 ARM intrinsic", "vst3q_u32 ARM intrinsic", "vst3q_u8 ARM intrinsic", "vst4_f16 ARM intrinsic", "vst4_f32 ARM intrinsic", "vst4_lane_f16 ARM intrinsic", "vst4_lane_f32 ARM intrinsic", "vst4_lane_p16 ARM intrinsic", "vst4_lane_p8 ARM intrinsic", "vst4_lane_s16 ARM intrinsic", "vst4_lane_s32 ARM intrinsic", "vst4_lane_s8 ARM intrinsic", "vst4_lane_u16 ARM intrinsic", "vst4_lane_u32 ARM intrinsic", "vst4_lane_u8 ARM intrinsic", "vst4_p16 ARM intrinsic", "vst4_p8 ARM intrinsic", "vst4_s16 ARM intrinsic", "vst4_s32 ARM intrinsic", "vst4_s64 ARM intrinsic", "vst4_s8 ARM intrinsic", "vst4_u16 ARM intrinsic", "vst4_u32 ARM intrinsic", "vst4_u64 ARM intrinsic", "vst4_u8 ARM intrinsic", "vst4q_f16 ARM intrinsic", "vst4q_f32 ARM intrinsic", "vst4q_lane_f16 ARM intrinsic", "vst4q_lane_f32 ARM intrinsic", "vst4q_lane_p16 ARM intrinsic", "vst4q_lane_s16 ARM intrinsic", "vst4q_lane_s32 ARM intrinsic", "vst4q_lane_u16 ARM intrinsic", "vst4q_lane_u32 ARM intrinsic", "vst4q_p16 ARM intrinsic", "vst4q_p8 ARM intrinsic", "vst4q_s16 ARM intrinsic", "vst4q_s32 ARM intrinsic", "vst4q_s8 ARM intrinsic", "vst4q_u16 ARM intrinsic", "vst4q_u32 ARM intrinsic", "vst4q_u8 ARM intrinsic", "vsub_f32 ARM intrinsic", "vsub_s16 ARM intrinsic", "vsub_s32 ARM intrinsic", "vsub_s64 ARM intrinsic", "vsub_s8 ARM intrinsic", "vsub_u16 ARM intrinsic", "vsub_u32 ARM intrinsic", "vsub_u64 ARM intrinsic", "vsub_u8 ARM intrinsic", "vsubhn_s16 ARM intrinsic", "vsubhn_s32 ARM intrinsic", "vsubhn_s64 ARM intrinsic", "vsubhn_u16 ARM intrinsic", "vsubhn_u32 ARM intrinsic", "vsubhn_u64 ARM intrinsic", "vsubl_s16 ARM intrinsic", "vsubl_s32 ARM intrinsic", "vsubl_s8 ARM intrinsic", "vsubl_u16 ARM intrinsic", "vsubl_u32 ARM intrinsic", "vsubl_u8 ARM intrinsic", "vsubq_f32 ARM intrinsic", "vsubq_s16 ARM intrinsic", "vsubq_s32 ARM intrinsic", "vsubq_s64 ARM intrinsic", "vsubq_s8 ARM intrinsic", "vsubq_u16 ARM intrinsic", "vsubq_u32 ARM intrinsic", "vsubq_u64 ARM intrinsic", "vsubq_u8 ARM intrinsic", "vsubw_s16 ARM intrinsic", "vsubw_s32 ARM intrinsic", "vsubw_s8 ARM intrinsic", "vsubw_u16 ARM intrinsic", "vsubw_u32 ARM intrinsic", "vsubw_u8 ARM intrinsic", "vtbl1_p8 ARM intrinsic", "vtbl1_s8 ARM intrinsic", "vtbl1_u8 ARM intrinsic", "vtbl2_p8 ARM intrinsic", "vtbl2_s8 ARM intrinsic", "vtbl2_u8 ARM intrinsic", "vtbl3_p8 ARM intrinsic", "vtbl3_s8 ARM intrinsic", "vtbl3_u8 ARM intrinsic", "vtbl4_p8 ARM intrinsic", "vtbl4_s8 ARM intrinsic", "vtbl4_u8 ARM intrinsic", "vtbx1_p8 ARM intrinsic", "vtbx1_s8 ARM intrinsic", "vtbx1_u8 ARM intrinsic", "vtbx2_p8 ARM intrinsic", "vtbx2_s8 ARM intrinsic", "vtbx2_u8 ARM intrinsic", "vtbx3_p8 ARM intrinsic", "vtbx3_s8 ARM intrinsic", "vtbx3_u8 ARM intrinsic", "vtbx4_p8 ARM intrinsic", "vtbx4_s8 ARM intrinsic", "vtbx4_u8 ARM intrinsic", "vtrn_f32 ARM intrinsic", "vtrn_p16 ARM intrinsic", "vtrn_p8 ARM intrinsic", "vtrn_s16 ARM intrinsic", "vtrn_s32 ARM intrinsic", "vtrn_s8 ARM intrinsic", "vtrn_u16 ARM intrinsic", "vtrn_u32 ARM intrinsic", "vtrn_u8 ARM intrinsic", "vtrnq_f32 ARM intrinsic", "vtrnq_p16 ARM intrinsic", "vtrnq_p8 ARM intrinsic", "vtrnq_s16 ARM intrinsic", "vtrnq_s32 ARM intrinsic", "vtrnq_s8 ARM intrinsic", "vtrnq_u16 ARM intrinsic", "vtrnq_u32 ARM intrinsic", "vtrnq_u8 ARM intrinsic", "vtst_p8 ARM intrinsic", "vtst_s16 ARM intrinsic", "vtst_s32 ARM intrinsic", "vtst_s8 ARM intrinsic", "vtst_u16 ARM intrinsic", "vtst_u32 ARM intrinsic", "vtst_u8 ARM intrinsic", "vtstq_p8 ARM intrinsic", "vtstq_s16 ARM intrinsic", "vtstq_s32 ARM intrinsic", "vtstq_s8 ARM intrinsic", "vtstq_u16 ARM intrinsic", "vtstq_u32 ARM intrinsic", "vtstq_u8 ARM intrinsic", "vuzp_f32 ARM intrinsic", "vuzp_p16 ARM intrinsic", "vuzp_p8 ARM intrinsic", "vuzp_s16 ARM intrinsic", "vuzp_s32 ARM intrinsic", "vuzp_s8 ARM intrinsic", "vuzp_u16 ARM intrinsic", "vuzp_u32 ARM intrinsic", "vuzp_u8 ARM intrinsic", "vuzpq_f32 ARM intrinsic", "vuzpq_p16 ARM intrinsic", "vuzpq_p8 ARM intrinsic", "vuzpq_s16 ARM intrinsic", "vuzpq_s32 ARM intrinsic", "vuzpq_s8 ARM intrinsic", "vuzpq_u16 ARM intrinsic", "vuzpq_u32 ARM intrinsic", "vuzpq_u8 ARM intrinsic", "vzip_f32 ARM intrinsic", "vzip_p16 ARM intrinsic", "vzip_p8 ARM intrinsic", "vzip_s16 ARM intrinsic", "vzip_s8 ARM intrinsic", "vzip_u16 ARM intrinsic", "vzip_u8 ARM intrinsic", "vzipq_f32 ARM intrinsic", "vzipq_p16 ARM intrinsic", "vzipq_p8 ARM intrinsic", "vzipq_s16 ARM intrinsic", "vzipq_s32 ARM intrinsic", "vzipq_s8 ARM intrinsic", "vzipq_u16 ARM intrinsic", "vzipq_u32 ARM intrinsic", "vzipq_u8 ARM intrinsic"] -ms.assetid: d3d7dadd-7bd5-4508-8bff-371a66913e20 --- # ARM intrinsics @@ -166,6 +165,8 @@ The primary difference between MSVC and the ARM compiler is that the MSVC adds ` |_CountLeadingSigns64||unsigned int _CountLeadingSigns64(\__int64)| |_CountLeadingZeros||unsigned int _CountLeadingZeros(unsigned long)| |_CountLeadingZeros64||unsigned int _CountLeadingZeros64(unsigned \__int64)| +|_CountTrailingZeros||unsigned _CountTrailingZeros(unsigned long)| +|_CountTrailingZeros64||unsigned _CountTrailingZeros64(unsigned \__int64)| |_CountOneBits||unsigned int _CountOneBits(unsigned long)| |_CountOneBits64||unsigned int _CountOneBits64(unsigned \__int64)| |_DAddSatInt|QDADD|int _DAddSatInt(int, int)| @@ -303,7 +304,7 @@ Reads data from ARM coprocessors by using the coprocessor data transfer instruct unsigned __int64 _MoveFromCoprocessor64( unsigned int coproc, unsigned int opcode1, - unsigned int crm, + unsigned int crm ); ``` @@ -391,7 +392,7 @@ void _MoveFromCoprocessor64( unsigned __int64 value, unsigned int coproc, unsigned int opcode1, - unsigned int crm, + unsigned int crm ); ``` diff --git a/docs/intrinsics/arm64-intrinsics.md b/docs/intrinsics/arm64-intrinsics.md index 0ceb607571..8300ceea36 100644 --- a/docs/intrinsics/arm64-intrinsics.md +++ b/docs/intrinsics/arm64-intrinsics.md @@ -15,10 +15,12 @@ The Microsoft C++ compiler (MSVC) makes the following intrinsics available on th The NEON vector instruction set extensions for ARM64 provide Single Instruction Multiple Data (SIMD) capabilities. They resemble the ones in the MMX and SSE vector instruction sets that are common to x86 and x64 architecture processors. -NEON intrinsics are supported, as provided in the header file *arm64_neon.h*. The MSVC support for NEON intrinsics resembles that of the ARM64 compiler, which is documented in the [ARM NEON Intrinsic Reference](https://developer.arm.com/architectures/instruction-sets/simd-isas/neon/intrinsics) on the ARM Infocenter website. +NEON intrinsics are supported, as provided in the header file `arm64_neon.h`. The MSVC support for NEON intrinsics resembles that of the ARM64 compiler, which is documented in the [ARM NEON Intrinsic Reference](https://developer.arm.com/architectures/instruction-sets/simd-isas/neon/intrinsics) on the ARM Infocenter website. ## ARM64-specific intrinsics listing +ARM64-specific intrinsics are supported, as provided in the header file `intrin.h`. + |Function Name|Instruction|Function Prototype| |-------------------|-----------------|------------------------| |__break|BRK|void __break(int)| @@ -131,6 +133,8 @@ NEON intrinsics are supported, as provided in the header file *arm64_neon.h*. Th |_CountLeadingSigns64||unsigned int _CountLeadingSigns64(\__int64)| |_CountLeadingZeros||unsigned int _CountLeadingZeros(unsigned long)| |_CountLeadingZeros64||unsigned int _CountLeadingZeros64(unsigned \__int64)| +|_CountTrailingZeros||unsigned int _CountTrailingZeros(unsigned long)| +|_CountTrailingZeros64||unsigned int _CountTrailingZeros64(unsigned __int64)| |_CountOneBits||unsigned int _CountOneBits(unsigned long)| |_CountOneBits64||unsigned int _CountOneBits64(unsigned \__int64)| |_ReadStatusReg|MRS|\__int64 _ReadStatusReg(int)| diff --git a/docs/intrinsics/assume.md b/docs/intrinsics/assume.md index 320a7a467a..7a5f8c8c2d 100644 --- a/docs/intrinsics/assume.md +++ b/docs/intrinsics/assume.md @@ -1,12 +1,12 @@ --- description: "Learn more about: __assume" title: "__assume" -ms.date: "09/02/2019" +ms.date: 08/03/2022 f1_keywords: ["__assume", "_assume", "__assume_cpp"] helpviewer_keywords: ["__assume keyword [C++]"] ms.assetid: d8565123-b132-44b1-8235-5a8c8bff85a7 --- -# __assume +# `__assume` **Microsoft Specific** @@ -22,85 +22,80 @@ __assume( ### Parameters -*expression*\ -Any expression that is assumed to evaluate to true. +*`expression`*\ +For reachable code, any expression that is assumed to evaluate to **`true`**. Use `0` to indicate unreachable code to the optimizer. ## Remarks -The optimizer assumes that the condition represented by `expression` is true at the point where the keyword appears and remains true until `expression` is modified (for example, by assignment to a variable). Selective use of hints passed to the optimizer by **`__assume`** can improve optimization. +The optimizer assumes that the condition represented by `expression` is **`true`** at the point where the keyword appears and remains true until `expression` is modified (for example, by assignment to a variable). Selective use of hints passed to the optimizer by **`__assume`** can improve optimization. -If the **`__assume`** statement is written as a contradiction (an expression that always evaluates to false), it is always treated as `__assume(0)`. If your code isn’t behaving as expected, ensure that the `expression` you defined is valid and true, as described earlier. For more information about expected `__assume(0)` behavior, see the later remarks. +If the **`__assume`** statement is written as a contradiction (an expression that always evaluates to **`false`**), it's always treated as `__assume(0)`. If your code isn't behaving as expected, ensure that the `expression` you defined is valid and **`true`**, as described earlier. The `__assume(0)` statement is a special case. Use `__assume(0)` to indicate a code path that can't be reached. > [!WARNING] > A program must not contain an invalid **`__assume`** statement on a reachable path. If the compiler can reach an invalid **`__assume`** statement, the program might cause unpredictable and potentially dangerous behavior. -`__assume` is not a genuine intrinsic. It does not have to be declared as a function and it cannot be used in a `#pragma intrinsic` directive. Although no code is generated, the code generated by the optimizer is affected. +For compatibility with previous versions, **`_assume`** is a synonym for **`__assume`** unless compiler option [`/Za` (Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. -Use **`__assume`** in an [ASSERT](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) only when the assert is not recoverable. Do not use **`__assume`** in an assert for which you have subsequent error recovery code because the compiler might optimize away the error-handling code. +`__assume` isn't a genuine intrinsic. It doesn't have to be declared as a function and it can't be used in a `#pragma intrinsic` directive. Although no code is generated, the code generated by the optimizer is affected. -The `__assume(0)` statement is a special case. Use `__assume(0)` to indicate a code path that cannot be reached. The following example shows how to use `__assume(0)` to indicate that the default case of a switch statement cannot be reached. This shows the most typical use of `__assume(0)`. - -For compatibility with previous versions, **`_assume`** is a synonym for **`__assume`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +Use **`__assume`** in an [`ASSERT`](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) only when the assertion isn't recoverable. Don't use **`__assume`** in an assertion for which you have subsequent error recovery code because the compiler might optimize away the error-handling code. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|**`__assume`**|x86, ARM, x64, ARM64| +| Intrinsic | Architecture | +|--|--| +| **`__assume`** | x86, ARM, x64, ARM64, ARM64EC | ## Example +The following example shows how to use `__assume(0)` to indicate that the **`default`** case of a **`switch`** statement can't be reached. It's the most typical use of `__assume(0)`. Here, the programmer knows that the only possible inputs for `p` will be 1 or 2. If another value is passed in for `p`, the program becomes invalid and causes unpredictable behavior. + ```cpp // compiler_intrinsics__assume.cpp -#ifdef DEBUG -# define ASSERT(e) ( ((e) || assert(__FILE__, __LINE__) ) -#else -# define ASSERT(e) ( __assume(e) ) -#endif -void func1(int i) +void func1(int /*ignored*/) { } int main(int p) { - switch(p){ - case 1: - func1(1); - break; - case 2: - func1(-1); - break; - default: - __assume(0); - // This tells the optimizer that the default - // cannot be reached. As so, it does not have to generate - // the extra code to check that 'p' has a value - // not represented by a case arm. This makes the switch - // run faster. + switch(p) + { + case 1: + func1(1); + break; + case 2: + func1(-1); + break; + default: + __assume(0); + // This tells the optimizer that the default + // cannot be reached. As so, it does not have to generate + // the extra code to check that 'p' has a value + // not represented by a case arm. This makes the switch + // run faster. } } ``` -The use of `__assume(0)` tells the optimizer that the default case cannot be reached. The example demonstrates that the programmer knows that the only possible inputs for `p` will be 1 or 2. If another value is passed in for `p`, the program becomes invalid and causes unpredictable behavior. +As a result of the `__assume(0)` statement, the compiler doesn't generate code to test whether `p` has a value that isn't represented in a case statement. -As a result of the `__assume(0)` statement, the compiler does not generate code to test whether `p` has a value that is not represented in a case statement. For this to work, the `__assume(0)` statement must be the first statement in the body of the default case. - -Because the compiler generates code based on **`__assume`**, that code might not run correctly if the expression inside the **`__assume`** statement is false at run time. If you are not sure that the expression will always be true at run time, you can use the `assert` function to protect the code. +If you aren't sure that the expression will always be **`true`** at runtime, you can use the `assert` function to protect the code. This macro definition wraps the **`__assume`** statement with a check: ```C -#define ASSERT(e) ( ((e) || assert(__FILE__, __LINE__)), __assume(e) ) +#define ASSUME(e) (((e) || (assert(e), (e))), __assume(e)) ``` -Unfortunately, this use of `assert` prevents the compiler from performing the default-case optimization that was described earlier in this document. As an alternative, you can use a separate macro, as follows. +For the **`default`** case optimization to work, the `__assume(0)` statement must be the first statement in the body of the **`default`** case. Unfortunately, the `assert` in the `ASSUME` macro prevents the compiler from performing this optimization. As an alternative, you can use a separate macro, as shown here: ```C #ifdef DEBUG -# define NODEFAULT ASSERT(0) +// This code is supposed to be unreachable, so assert +# define NODEFAULT assert(0) #else # define NODEFAULT __assume(0) #endif - +// . . . default: NODEFAULT; ``` diff --git a/docs/intrinsics/bitscanforward-bitscanforward64.md b/docs/intrinsics/bitscanforward-bitscanforward64.md index 5e53a1c64c..04d5f4db30 100644 --- a/docs/intrinsics/bitscanforward-bitscanforward64.md +++ b/docs/intrinsics/bitscanforward-bitscanforward64.md @@ -39,7 +39,7 @@ unsigned char _BitScanForward64( ## Remarks -If a set bit is found, the bit position of the first set bit found is returned in the first parameter. If no set bit is found, 0 is returned; otherwise, 1 is returned. +If a set bit is found, the bit position of the first set bit is written to the address specified in the first parameter and the function returns 1. If no bit is found, the function returns 0 and the value written to the address in the first parameter is undefined. ## Requirements diff --git a/docs/intrinsics/bitscanreverse-bitscanreverse64.md b/docs/intrinsics/bitscanreverse-bitscanreverse64.md index df837174ab..a4067971e7 100644 --- a/docs/intrinsics/bitscanreverse-bitscanreverse64.md +++ b/docs/intrinsics/bitscanreverse-bitscanreverse64.md @@ -1,7 +1,7 @@ --- description: "Learn more about: _BitScanReverse, _BitScanReverse64" title: "_BitScanReverse, _BitScanReverse64" -ms.date: "09/02/2019" +ms.date: 07/01/2022 f1_keywords: ["_BitScanReverse64", "_BitScanReverse_cpp", "_BitScanReverse", "_BitScanReverse64_cpp"] helpviewer_keywords: ["bsr instruction", "_BitScanReverse intrinsic", "BitScanReverse intrinsic"] ms.assetid: 2520a207-af8b-4aad-9ae7-831abeadf376 @@ -28,14 +28,14 @@ unsigned char _BitScanReverse64( ### Parameters *Index*\ -[out] Loaded with the bit position of the first set bit (1) found. +[out] Loaded with the bit position of the first set bit (1) found. Otherwise, undefined. *Mask*\ [in] The 32-bit or 64-bit value to search. ## Return value -Nonzero if `Index` was set, or 0 if no set bits were found. +Nonzero if any bit was set in `Mask`, or 0 if no set bits were found. ## Requirements diff --git a/docs/intrinsics/check-isa-arch-support.md b/docs/intrinsics/check-isa-arch-support.md new file mode 100644 index 0000000000..00b066b54b --- /dev/null +++ b/docs/intrinsics/check-isa-arch-support.md @@ -0,0 +1,143 @@ +--- +description: "Learn more about: __check_isa_support, __check_arch_support" +title: "__check_isa_support, __check_arch_support" +ms.date: "11/07/2024" +f1_keywords: ["__check_isa_support", "__check_arch_support"] +helpviewer_keywords: ["__check_isa_support intrinsic", "__check_arch_support intrinsic"] +--- +# __check_isa_support, __check_arch_support + +**Microsoft Specific** + +`__check_isa_support` - detects if the processor supports the specified ISA feature and AVX10 version at run time. +`__check_arch_support` - detects if the arch flag (see [`/arch` (x86)](..\build\reference\arch-x86.md), [`/arch` (x64)](..\build\reference\arch-x64.md)) supports the specified ISA feature and AVX10 version at compile time. + +## Syntax + +```C +_Bool __check_isa_support( + unsigned feature, + unsigned avx10_version +); + +_Bool __check_arch_support( + unsigned feature, + unsigned avx10_version +); +``` + +```cpp +bool __check_isa_support( + unsigned feature, + unsigned avx10_version +); + +bool __check_arch_support( + unsigned feature, + unsigned avx10_version +); +``` + +### Parameters + +*feature*\ +[in] ISA feature to check. + +*avx10_version*\ +[in] AVX10 version to check. 0 if AVX10 version check isn't required. + +## Return value + +`__check_isa_support` returns `true` if the processor supports `feature` and `avx10_version` at run time, `false` otherwise. +`__check_arch_support` returns `true` if the `/arch` flag supports `feature` and `avx10_version` at compile time, `false` otherwise. + +## Requirements + +|Intrinsic|Architecture| +|---------------|------------------| +|`__check_isa_support`|x86, x64| +|`__check_arch_support`|x86, x64| + +**Header file** `` + +## Remarks + +The `__check_isa_support` intrinsic provides a faster alternative to the [`__cpuid`](cpuid-cpuidex.md) intrinsic to dynamically check for most frequently used CPU features. The `__check_arch_support` intrinsic provides an alternative to the [`predefined macros`](..\preprocessor\predefined-macros.md) for compile time code selection based on ISA extensions. + +The following feature values can be used in these intrinsics. These values are defined in `isa_availability.h`. + +|Feature Value Name|Description| +|---------------|------------------| +|`__IA_SUPPORT_VECTOR128`|Vector instructions with lengths up to 128 bits. This feature is enabled for SSE2 or later extensions| +|`__IA_SUPPORT_VECTOR256`|Vector instructions with lengths up to 256 bits. This feature is enabled for AVX2 or later extensions| +|`__IA_SUPPORT_VECTOR512`|Vector instructions with lengths up to 512 bits. This feature is enabled for AVX-512 or later extensions| +|`__IA_SUPPORT_AVX10`|AVX10 support. This feature is enabled for AVX10.1 or later extensions| +|`__IA_SUPPORT_SSE42`|SSE4.2 support| +|`__IA_SUPPORT_SV128X`|AVX-512 instructions for scalar of 128 bits. Can be used to signal that certain useful AVX-512 instruction like conversions can be used in scalar code| +|`__IA_SUPPORT_AVX10_2`|AVX10.2 support| +|`__IA_SUPPORT_APX`|APX support| +|`__IA_SUPPORT_FP16`|Half-precision floating-point instruction support| + +Multiple feature values can be combined using the OR(|) operator. + +The `__check_arch_support` intrinsic can always be evaluated at compile time, so using it in optimized code adds no extra instructions to execute. +Support for these intrinsics was added in Visual Studio 2022 version 17.10. + +## Example + +This example uses 256-bit AVX-512 instructions to vectorize conversion of double-precision values to 64-bit signed integer values. The tail loop for converting any source values not handled by the vector code is also used in case the vector code can't be executed. The compile-time support is checked before runtime support so that a runtime check can be avoided if possible. + +```cpp +// Compile this test with: /EHsc /O2 +#include +#include +#include +#include +using namespace std; + +#define CHECK_INSTRUCTION_SUPPORT(a,v) \ + (__check_arch_support((a),(v)) || __check_isa_support((a),(v))) + +int main() +{ + vector input = {0.3, 1.4, 2.5, 3.6, 4.7, 5.8, 6.9, 8.0, 9.1, 11.14}; + vector<__int64> output(10, 0); + int i = 0; + + if (CHECK_INSTRUCTION_SUPPORT(__IA_SUPPORT_SV128X | __IA_SUPPORT_VECTOR256, 0)) + { + for (; i < input.size() - 4; i += 4) + { + __m256i values = _mm256_cvttpd_epi64(_mm256_load_pd(&input[i])); + _mm256_storeu_epi64((void*)&output[i], values); + } + } + for (; i < input.size(); i++) + { + output[i] = input[i]; + } + + for (i = 0; i < output.size(); i++) { + cout << "output[" << i << "] = " << output[i] << endl; + } +} +``` + +```Output +output[0] = 0 +output[1] = 1 +output[2] = 2 +output[3] = 3 +output[4] = 4 +output[5] = 5 +output[6] = 6 +output[7] = 8 +output[8] = 9 +output[9] = 11 +``` + +**END Microsoft Specific** + +## See also + +[Compiler intrinsics](../intrinsics/compiler-intrinsics.md) diff --git a/docs/intrinsics/fastfail.md b/docs/intrinsics/fastfail.md index 592749c4e0..ffafc9ee25 100644 --- a/docs/intrinsics/fastfail.md +++ b/docs/intrinsics/fastfail.md @@ -13,7 +13,7 @@ Immediately terminates the calling process with minimum overhead. ## Syntax ```C -void __fastfail(unsigned int code); +__declspec(noreturn) void __fastfail(unsigned int code); ``` ### Parameters diff --git a/docs/intrinsics/index.yml b/docs/intrinsics/index.yml index a6d53048f0..9a0f48891f 100644 --- a/docs/intrinsics/index.yml +++ b/docs/intrinsics/index.yml @@ -8,6 +8,7 @@ metadata: description: Visual Studio includes assemblers and compiler intrinsics for low-level programming tasks. ms.topic: landing-page ms.date: 05/26/2020 + ms.author: twhitney ms.custom: intro-landing-hub # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new diff --git a/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md b/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md index db8af5eed1..591cbf0797 100644 --- a/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md +++ b/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: _InterlockedCompareExchange intrinsic functions" title: "_InterlockedCompareExchange intrinsic functions" -ms.date: 10/27/2021 +description: "Learn more about: _InterlockedCompareExchange intrinsic functions" +ms.date: 08/03/2022 f1_keywords: ["_InterlockedCompareExchange", "_InterlockedCompareExchange_acq", "_InterlockedCompareExchange_acq_cpp", "_InterlockedCompareExchange_cpp", "_InterlockedCompareExchange_HLEAcquire", "_InterlockedCompareExchange_HLERelease", "_InterlockedCompareExchange_nf", "_InterlockedCompareExchange_np", "_InterlockedCompareExchange_rel", "_InterlockedCompareExchange_rel_cpp", "_InterlockedCompareExchange8", "_InterlockedCompareExchange8_acq", "_InterlockedCompareExchange8_nf", "_InterlockedCompareExchange8_rel", "_InterlockedCompareExchange16", "_InterlockedCompareExchange16_acq", "_InterlockedCompareExchange16_acq_cpp", "_InterlockedCompareExchange16_cpp", "_InterlockedCompareExchange16_nf", "_InterlockedCompareExchange16_rel", "_InterlockedCompareExchange16_rel_cpp", "_InterlockedCompareExchange64", "_InterlockedCompareExchange64_acq", "_InterlockedCompareExchange64_acq_cpp", "_InterlockedCompareExchange64_cpp", "_InterlockedCompareExchange64_HLEAcquire", "_InterlockedCompareExchange64_HLERelease", "_InterlockedCompareExchange64_nf", "_InterlockedCompareExchange64_np", "_InterlockedCompareExchange64_rel", "_InterlockedCompareExchange64_rel_cpp"] helpviewer_keywords: ["_InterlockedCompareExchange intrinsic", "_InterlockedCompareExchange_acq intrinsic", "_InterlockedCompareExchange_acq_cpp intrinsic", "_InterlockedCompareExchange_cpp intrinsic", "_InterlockedCompareExchange_HLEAcquire intrinsic", "_InterlockedCompareExchange_HLERelease intrinsic", "_InterlockedCompareExchange_nf intrinsic", "_InterlockedCompareExchange_np intrinsic", "_InterlockedCompareExchange_rel intrinsic", "_InterlockedCompareExchange_rel_cpp intrinsic", "_InterlockedCompareExchange8 intrinsic", "_InterlockedCompareExchange8_acq intrinsic", "_InterlockedCompareExchange8_nf intrinsic", "_InterlockedCompareExchange8_rel intrinsic", "_InterlockedCompareExchange16 intrinsic", "_InterlockedCompareExchange16_acq intrinsic", "_InterlockedCompareExchange16_acq_cpp intrinsic", "_InterlockedCompareExchange16_cpp intrinsic", "_InterlockedCompareExchange16_nf intrinsic", "_InterlockedCompareExchange16_rel intrinsic", "_InterlockedCompareExchange16_rel_cpp intrinsic", "_InterlockedCompareExchange64 intrinsic", "_InterlockedCompareExchange64_acq intrinsic", "_InterlockedCompareExchange64_acq_cpp intrinsic", "_InterlockedCompareExchange64_cpp intrinsic", "_InterlockedCompareExchange64_HLEAcquire intrinsic", "_InterlockedCompareExchange64_HLERelease intrinsic", "_InterlockedCompareExchange64_nf intrinsic", "_InterlockedCompareExchange64_np intrinsic", "_InterlockedCompareExchange64_rel intrinsic", "_InterlockedCompareExchange64_rel_cpp intrinsic"] -ms.assetid: c3ad79c0-a523-4930-a3a4-69a65d7d5c81 --- -# _InterlockedCompareExchange intrinsic functions +# `_InterlockedCompareExchange` intrinsic functions **Microsoft Specific** @@ -134,37 +133,37 @@ __int64 _InterlockedCompareExchange64_rel( ### Parameters -*Destination*\ +*`Destination`*\ [in, out] Pointer to the destination value. The sign is ignored. -*Exchange*\ +*`Exchange`*\ [in] Exchange value. The sign is ignored. -*Comparand*\ -[in] Value to compare to destination. The sign is ignored. +*`Comparand`*\ +[in] Value to compare to the value pointed at by *`Destination`*. The sign is ignored. ## Return value -The return value is the initial value of the `Destination` pointer. +The return value is the initial value pointed at by the `Destination` pointer. ## Requirements -|Intrinsic|Architecture|Header| -|---------------|------------------|------------| -|`_InterlockedCompareExchange`, `_InterlockedCompareExchange8`, `_InterlockedCompareExchange16`, `_InterlockedCompareExchange64`|x86, ARM, x64, ARM64|\| -|`_InterlockedCompareExchange_acq`, `_InterlockedCompareExchange_nf`, `_InterlockedCompareExchange_rel`, `_InterlockedCompareExchange8_acq`, `_InterlockedCompareExchange8_nf`, `_InterlockedCompareExchange8_rel`,`_InterlockedCompareExchange16_acq`, `_InterlockedCompareExchange16_nf`, `_InterlockedCompareExchange16_rel`, `_InterlockedCompareExchange64_acq`, `_InterlockedCompareExchange64_nf`, `_InterlockedCompareExchange64_rel`,|ARM, ARM64|\| -|`_InterlockedCompareExchange_np`, `_InterlockedCompareExchange16_np`, `_InterlockedCompareExchange64_np`|x64|\| -|`_InterlockedCompareExchange_HLEAcquire`, `_InterlockedCompareExchange_HLERelease`, `_InterlockedCompareExchange64_HLEAcquire`, `_InterlockedCompareExchange64_HLERelease`|x86, x64|\| +| Intrinsic | Architecture | Header | +|--|--|--| +| `_InterlockedCompareExchange`, `_InterlockedCompareExchange8`, `_InterlockedCompareExchange16`, `_InterlockedCompareExchange64` | x86, ARM, x64, ARM64 | \ | +| `_InterlockedCompareExchange_acq`, `_InterlockedCompareExchange_nf`, `_InterlockedCompareExchange_rel`, `_InterlockedCompareExchange8_acq`, `_InterlockedCompareExchange8_nf`, `_InterlockedCompareExchange8_rel`, `_InterlockedCompareExchange16_acq`, `_InterlockedCompareExchange16_nf`, `_InterlockedCompareExchange16_rel`, `_InterlockedCompareExchange64_acq`, `_InterlockedCompareExchange64_nf`, `_InterlockedCompareExchange64_rel` | ARM, ARM64 | \ | +| `_InterlockedCompareExchange_np`, `_InterlockedCompareExchange16_np`, `_InterlockedCompareExchange64_np` | x64 | \ | +| `_InterlockedCompareExchange_HLEAcquire`, `_InterlockedCompareExchange_HLERelease`, `_InterlockedCompareExchange64_HLEAcquire`, `_InterlockedCompareExchange64_HLERelease` | x86, x64 | \ | ## Remarks -`_InterlockedCompareExchange` does an atomic comparison of the `Destination` value with the `Comparand` value. If the `Destination` value is equal to the `Comparand` value, the `Exchange` value is stored in the address specified by `Destination`. Otherwise, does no operation. +`_InterlockedCompareExchange` does an atomic comparison of the value pointed at by `Destination` with the `Comparand` value. If the `Destination` value is equal to the `Comparand` value, the `Exchange` value is stored in the address specified by `Destination`. Otherwise, does no operation. -`_InterlockedCompareExchange` provides compiler intrinsic support for the Win32 Windows SDK [InterlockedCompareExchange](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function. +`_InterlockedCompareExchange` provides compiler intrinsic support for the Win32 Windows SDK [`InterlockedCompareExchange`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function. There are several variations on `_InterlockedCompareExchange` that vary based on the data types they involve and whether processor-specific acquire or release semantics are used. -While the `_InterlockedCompareExchange` function operates on long integer values, `_InterlockedCompareExchange8` operates on 8-bit integer values, `_InterlockedCompareExchange16` operates on short integer values, and `_InterlockedCompareExchange64` operates on 64-bit integer values. +While the `_InterlockedCompareExchange` function operates on 32-bit **`long`** integer values, `_InterlockedCompareExchange8` operates on 8-bit integer values, `_InterlockedCompareExchange16` operates on 16-bit **`short`** integer values, and `_InterlockedCompareExchange64` operates on 64-bit integer values. For more information on similar intrinsics for 128-bit values, see [`_InterlockedCompareExchange128`](./interlockedcompareexchange128.md). On all ARM platforms, use the intrinsics with `_acq` and `_rel` suffixes for acquire and release semantics, such as at the beginning and end of a critical section. The ARM intrinsics with an `_nf` ("no fence") suffix don't act as a memory barrier. @@ -390,8 +389,8 @@ int main( ## See also -[_InterlockedCompareExchange128](../intrinsics/interlockedcompareexchange128.md)\ -[_InterlockedCompareExchangePointer intrinsic functions](../intrinsics/interlockedcompareexchangepointer-intrinsic-functions.md)\ +[`_InterlockedCompareExchange128`](../intrinsics/interlockedcompareexchange128.md)\ +[`_InterlockedCompareExchangePointer` intrinsic functions](../intrinsics/interlockedcompareexchangepointer-intrinsic-functions.md)\ [Compiler intrinsics](../intrinsics/compiler-intrinsics.md)\ [Keywords](../cpp/keywords-cpp.md)\ [Conflicts with the x86 Compiler](../build/x64-software-conventions.md#conflicts-with-the-x86-compiler) diff --git a/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md b/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md index a105513296..a5e5134fc0 100644 --- a/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md +++ b/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _InterlockedExchangeAdd intrinsic functions" title: "_InterlockedExchangeAdd intrinsic functions" +description: "Learn more about: _InterlockedExchangeAdd intrinsic functions" ms.date: "09/02/2019" f1_keywords: ["_InterlockedExchangeAdd64_nf", "_InterlockedExchangeAdd64_rel", "_InterlockedExchangeAdd16_rel", "_InterlockedExchangeAdd_acq", "_InterlockedExchangeAdd_nf", "_InterlockedExchangeAdd_rel", "_InterlockedExchangeAdd8_acq", "_InterlockedExchangeAdd16_nf", "_InterlockedExchangeAdd_acq_cpp", "_InterlockedExchangeAdd64_acq_cpp", "_InterlockedExchangeAdd16_acq", "_InterlockedExchangeAdd_HLERelease", "_InterlockedExchangeAdd64_cpp", "_InterlockedExchangeAdd64_HLERelease", "_InterlockedExchangeAdd64_acq", "_InterlockedExchangeAdd8", "_InterlockedExchangeAdd64", "_InterlockedExchangeAdd8_nf", "_InterlockedExchangeAdd16", "_InterlockedExchangeAdd64_rel_cpp", "_InterlockedExchangeAdd_cpp", "_InterlockedExchangeAdd8_rel", "_InterlockedExchangeAdd_HLEAcquire", "_InterlockedExchangeAdd64_HLEAcquire", "_InterlockedExchangeAdd"] helpviewer_keywords: ["_InterlockedExchangeAdd8_nf intrinsic", "InterlockedExchangeAdd64_acq intrinsic", "_InterlockedExchangeAdd8_acq intrinsic", "_InterlockedExchangeAdd64 intrinsic", "_InterlockedExchangeAdd intrinsic", "_InterlockedExchangeAdd8_rel intrinsic", "_InterlockedExchangeAdd_acq intrinsic", "_InterlockedExchangeAdd_HLEAcquire intrinsic", "_InterlockedExchangeAdd8 intrinsic", "_InterlockedExchangeAdd_rel intrinsic", "_InterlockedExchangeAdd64_HLERelease intrinsic", "_InterlockedExchangeAdd64_nf intrinsic", "InterlockedExchangeAdd_rel intrinsic", "InterlockedExchangeAdd intrinsic", "_InterlockedExchangeAdd_nf intrinsic", "_InterlockedExchangeAdd16_rel intrinsic", "InterlockedExchangeAdd_acq intrinsic", "_InterlockedExchangeAdd64_HLEAcquire intrinsic", "_InterlockedExchangeAdd16 intrinsic", "_InterlockedExchangeAdd64_acq intrinsic", "InterlockedExchangeAdd64_rel intrinsic", "_InterlockedExchangeAdd16_acq intrinsic", "InterlockedExchangeAdd64 intrinsic", "_InterlockedExchangeAdd_HLERelease intrinsic", "_InterlockedExchangeAdd16_nf intrinsic", "_InterlockedExchangeAdd64_rel intrinsic"] -ms.assetid: 25809e1f-9c60-4492-9f7c-0fb59c8d13d2 --- # _InterlockedExchangeAdd intrinsic functions @@ -115,7 +114,7 @@ The return value is the initial value of the variable pointed to by the `Addend` |---------------|------------------|------------| |`_InterlockedExchangeAdd`, `_InterlockedExchangeAdd8`, `_InterlockedExchangeAdd16`|x86, ARM, x64, ARM64|\| |`_InterlockedExchangeAdd64`|ARM, x64, ARM64|\| -|`_InterlockedExchangeAdd_acq`, `_InterlockedExchangeAdd_rel`, `_InterlockedExchangeAdd_nf`, `_InterlockedExchangeAdd8_acq`, `_InterlockedExchangeAdd8_rel`, `_InterlockedExchangeAdd8_nf`,`_InterlockedExchangeAdd16_acq`, `_InterlockedExchangeAdd16_rel`, `_InterlockedExchangeAdd16_nf`, `_InterlockedExchangeAdd64_acq`, `_InterlockedExchangeAdd64_rel`, `_InterlockedExchangeAdd64_nf`|ARM, ARM64|\| +|`_InterlockedExchangeAdd_acq`, `_InterlockedExchangeAdd_rel`, `_InterlockedExchangeAdd_nf`, `_InterlockedExchangeAdd8_acq`, `_InterlockedExchangeAdd8_rel`, `_InterlockedExchangeAdd8_nf`, `_InterlockedExchangeAdd16_acq`, `_InterlockedExchangeAdd16_rel`, `_InterlockedExchangeAdd16_nf`, `_InterlockedExchangeAdd64_acq`, `_InterlockedExchangeAdd64_rel`, `_InterlockedExchangeAdd64_nf`|ARM, ARM64|\| |`_InterlockedExchangeAdd_HLEAcquire`, `_InterlockedExchangeAdd_HLERelease`|x86, x64|\| |`_InterlockedExchangeAdd64_HLEAcquire`, `_InterlockedExchangeAdd64_HLErelease`|x64|\| diff --git a/docs/intrinsics/intrinsics-available-on-all-architectures.md b/docs/intrinsics/intrinsics-available-on-all-architectures.md index 9eb339997c..93cad134b4 100644 --- a/docs/intrinsics/intrinsics-available-on-all-architectures.md +++ b/docs/intrinsics/intrinsics-available-on-all-architectures.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Intrinsics available on all architectures" title: "Intrinsics available on all architectures" -ms.date: 02/04/2021 +ms.date: 08/30/2022 helpviewer_keywords: ["cl.exe compiler, intrinsics"] --- # Intrinsics available on all architectures @@ -153,6 +153,13 @@ The following UCRT functions have intrinsic forms on all architectures: | [`wcslen`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | string.h | | [`_wcsset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) | string.h | +In Visual Studio 2022 version 17.2 and later, these functions have intrinsic forms on x64 and ARM64 platforms: + +| Intrinsic | Header | +|--|--| +| [`log2`](../c-runtime-library/reference/log2-log2f-log2l.md) | math.h | +| [`log2f`](../c-runtime-library/reference/log2-log2f-log2l.md) | math.h | + ## See also [ARM intrinsics](../intrinsics/arm-intrinsics.md)\ diff --git a/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md b/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md index 3c6f905373..aad03f0a47 100644 --- a/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md +++ b/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _mm_insert_si64, _mm_inserti_si64" title: "_mm_insert_si64, _mm_inserti_si64" +description: "Learn more about: _mm_insert_si64, _mm_inserti_si64" ms.date: "09/02/2019" f1_keywords: ["_mm_inserti_si64", "_mm_insert_si64"] helpviewer_keywords: ["insertq instruction", "_mm_insert_si64 intrinsic", "_mm_inserti_si64 intrinsic"] -ms.assetid: 897a4b36-8b08-4b00-a18f-7850f5732d7d --- # _mm_insert_si64, _mm_inserti_si64 @@ -21,7 +20,7 @@ __m128i _mm_insert_si64( ); __m128i _mm_inserti_si64( __m128i Source1, - __m128i Source2 + __m128i Source2, int Length, int Index ); diff --git a/docs/intrinsics/mm-stream-ss.md b/docs/intrinsics/mm-stream-ss.md index 5c460ea215..6c99fef154 100644 --- a/docs/intrinsics/mm-stream-ss.md +++ b/docs/intrinsics/mm-stream-ss.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _mm_stream_ss" title: "_mm_stream_ss" -ms.date: "09/02/2019" +ms.date: 01/04/2023 f1_keywords: ["_mm_stream_ss"] helpviewer_keywords: ["movntss instruction", "_mm_stream_ss intrinsic"] ms.assetid: c53dffe9-0dfe-4063-85d3-e8987b870fce --- -# _mm_stream_ss +# `_mm_stream_ss` **Microsoft Specific** @@ -35,9 +35,9 @@ None. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|`_mm_stream_ss`|SSE4a| +| Intrinsic | Architecture | +|---|---| +| `_mm_stream_ss` | SSE4a | **Header file** \ @@ -70,7 +70,7 @@ int main() vals.m128_f32[3] = 3.; _mm_stream_ss(&f[3], vals); cout << "f[0] = " << f[0] << ", f[1] = " << f[1] << endl; - cout << "f[1] = " << f[1] << ", f[3] = " << f[3] << endl; + cout << "f[2] = " << f[2] << ", f[3] = " << f[3] << endl; } ``` @@ -85,8 +85,8 @@ Portions Copyright 2007 by Advanced Micro Devices, Inc. All rights reserved. Rep ## See also -[_mm_stream_sd](../intrinsics/mm-stream-sd.md)\ -[_mm_stream_ps](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_stream_ps)\ -[_mm_store_ss](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ss)\ -[_mm_sfence](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence)\ +[`_mm_stream_sd`](../intrinsics/mm-stream-sd.md)\ +[`_mm_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_stream_ps)\ +[`_mm_store_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ss)\ +[`_mm_sfence`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence)\ [Compiler intrinsics](../intrinsics/compiler-intrinsics.md) diff --git a/docs/intrinsics/rdtsc.md b/docs/intrinsics/rdtsc.md index 1bf37dc8e6..09268f21f7 100644 --- a/docs/intrinsics/rdtsc.md +++ b/docs/intrinsics/rdtsc.md @@ -62,4 +62,5 @@ int main() ## See also +[__rdtscp](../intrinsics/rdtscp.md)\ [Compiler intrinsics](../intrinsics/compiler-intrinsics.md) diff --git a/docs/intrinsics/rdtscp.md b/docs/intrinsics/rdtscp.md index 92816d45de..0bd25672bd 100644 --- a/docs/intrinsics/rdtscp.md +++ b/docs/intrinsics/rdtscp.md @@ -10,7 +10,7 @@ ms.assetid: f17d9a9c-88bb-44e0-b69d-d516bc1c93ee **Microsoft Specific** -Generates the `rdtscp` instruction, writes `TSC_AUX[31:0`] to memory, and returns the 64-bit Time Stamp Counter (`TSC)` result. +Generates the `rdtscp` instruction, writes `TSC_AUX[31:0]` to memory, and returns the 64-bit Time Stamp Counter (TSC) result. ## Syntax @@ -39,7 +39,7 @@ A 64-bit unsigned integer tick count. ## Remarks -The `__rdtscp` intrinsic generates the `rdtscp` instruction. To determine hardware support for this instruction, call the `__cpuid` intrinsic with `InfoType=0x80000001` and check bit 27 of `CPUInfo[3] (EDX)`. This bit is 1 if the instruction is supported, and 0 otherwise. If you run code that uses the intrinsic on hardware that doesn't support the `rdtscp` instruction, the results are unpredictable. +The `__rdtscp` intrinsic generates the `rdtscp` instruction. To determine hardware support for this instruction, call the `__cpuid` intrinsic with `InfoType=0x80000001` and check bit 27 of `CPUInfo[3] (EDX)`. This bit is 1 if the instruction is supported, and 0 otherwise. If you run code that uses the intrinsic on hardware that doesn't support the `rdtscp` instruction, the results are unpredictable. This instruction waits until all previous instructions have executed and all previous loads are globally visible. However, it isn't a serializing instruction. For more information, see the Intel and AMD manuals. diff --git a/docs/intrinsics/sentinel-conversion-functions.md b/docs/intrinsics/sentinel-conversion-functions.md index fda826a7a0..f044aa16f1 100644 --- a/docs/intrinsics/sentinel-conversion-functions.md +++ b/docs/intrinsics/sentinel-conversion-functions.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Sentinel floating-point conversion functions" title: "Sentinel conversion functions" -ms.date: 11/18/2021 +ms.date: 10/16/2023 f1_keywords: ["intrin/_cvt_dtoi_sent", "intrin/_cvt_dtoll_sent", "intrin/_cvt_dtoui_sent", "intrin/_cvt_dtoull_sent", "intrin/_cvt_ftoi_sent", "intrin/_cvt_ftoll_sent", "intrin/_cvt_ftoui_sent", "intrin/_cvt_ftoull_sent"] helpviewer_keywords: ["_cvt_dtoi_sent", "_cvt_dtoll_sent", "_cvt_dtoui_sent", "_cvt_dtoull_sent", "_cvt_ftoi_sent", "_cvt_ftoll_sent", "_cvt_ftoui_sent", "_cvt_ftoull_sent"] --- @@ -35,20 +35,20 @@ The integer-typed result of the conversion. ## Requirements -**Header**: \ +**Header**: `` **Architecture**: x86, x64 ## Remarks -These intrinsics are floating-point to integral type conversion functions that use a *sentinel* strategy: They return the result value farthest from zero as a proxy sentinel value for NaN. Any invalid conversion returns this sentinel value. The specific sentinel value returned depends on the result type. +These intrinsics are floating-point to integral type conversion functions that use a *sentinel* strategy: They return the result value farthest from zero as a proxy sentinel value for `NaN`. Any invalid conversion returns this sentinel value. The specific sentinel value returned depends on the result type. | Result type | Sentinel | *``* constant | |--|--| -| `int` | -2147483648 (0xFFFFFFFF) | `INT_MIN` | +| `int` | -2147483648 (0x80000000) | `INT_MIN` | | `unsigned int` | 4294967295 (0xFFFFFFFF) | `UINT_MAX` | -| `long long` | -9223372036854775808 (0xFFFFFFFF'FFFFFFFF) | `LLONG_MIN` | -| `unsigned long long` | 18446744073709551615 (0xFFFFFFFF'FFFFFFFF) | `ULLONG_MAX` | +| `long long` | -9223372036854775808 (0x8000000000000000) | `LLONG_MIN` | +| `unsigned long long` | 18446744073709551615 (0xFFFFFFFFFFFFFFFF) | `ULLONG_MAX` | The sentinel conversion intrinsics are available starting in Visual Studio 2019 version 16.10. diff --git a/docs/intrinsics/stosq.md b/docs/intrinsics/stosq.md index 37afa23822..bd1487ead2 100644 --- a/docs/intrinsics/stosq.md +++ b/docs/intrinsics/stosq.md @@ -15,7 +15,7 @@ Generates a store string instruction (`rep stosq`). ## Syntax ```C -void __stosb( +void __stosq( unsigned __int64* Destination, unsigned __int64 Data, size_t Count diff --git a/docs/intrinsics/toc.yml b/docs/intrinsics/toc.yml index cfbc51772b..eb04364ed4 100644 --- a/docs/intrinsics/toc.yml +++ b/docs/intrinsics/toc.yml @@ -39,6 +39,8 @@ items: href: ../intrinsics/bittestandreset-bittestandreset64.md - name: _bittestandset, _bittestandset64 href: ../intrinsics/bittestandset-bittestandset64.md + - name: __check_isa_support, __check_arch_support + href: ../intrinsics/check-isa-arch-support.md - name: __cpuid, __cpuidex href: ../intrinsics/cpuid-cpuidex.md - name: __debugbreak diff --git a/docs/intrinsics/umulh.md b/docs/intrinsics/umulh.md index a92840bf59..6aa9851d39 100644 --- a/docs/intrinsics/umulh.md +++ b/docs/intrinsics/umulh.md @@ -1,12 +1,12 @@ --- description: "Learn more about: __umulh" title: "__umulh" -ms.date: "09/02/2019" +ms.date: 09/19/2022 f1_keywords: ["__umulh"] helpviewer_keywords: ["__umulh intrinsic"] ms.assetid: d241b53a-e6f7-4af1-9f6e-84e149158f03 --- -# __umulh +# `__umulh` **Microsoft Specific** @@ -23,10 +23,10 @@ unsigned __int64 __umulh( ### Parameters -*a*\ +*`a`*\ [in] The first number to multiply. -*b*\ +*`b`*\ [in] The second number to multiply. ## Return value @@ -35,9 +35,9 @@ The high 64 bits of the 128-bit result of the multiplication. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|`__umulh`|x64| +| Intrinsic | Architecture | +|--|--| +| `__umulh` | x64, ARM64 | **Header file** \ @@ -62,13 +62,13 @@ int main() unsigned __int64 result; result = __umulh(i, j); // result has the high 64 bits // of the product. - printf_s("0x%I64x * 0x%I64x = 0x%I64x%I64x \n", i, j, result, k); + printf_s("0x%016I64x * 0x%016I64x = 0x%016I64x_%016I64x \n", i, j, result, k); return 0; } ``` ```Output -0x10 * 0xfedcba9876543210 = 0xfedcba98765432100 +0x0000000000000010 * 0xfedcba9876543210 = 0x000000000000000f_edcba98765432100 ``` **END Microsoft Specific** diff --git a/docs/intrinsics/vmx-on.md b/docs/intrinsics/vmx-on.md index 92df3a84a4..2bea8d2e6c 100644 --- a/docs/intrinsics/vmx-on.md +++ b/docs/intrinsics/vmx-on.md @@ -1,7 +1,7 @@ --- description: "Learn more about: __vmx_on" title: "__vmx_on" -ms.date: "09/02/2019" +ms.date: 05/16/2022 f1_keywords: ["__vmx_on"] helpviewer_keywords: ["VMXON instruction", "__vmx_on intrinsic"] ms.assetid: 16804991-6a75-4adf-8ec2-bc95acfa4801 @@ -16,14 +16,14 @@ Activates virtual machine extensions (VMX) operation in the processor. ```C unsigned char __vmx_on( - unsigned __int64 *VmsSupportPhysicalAddress + unsigned __int64 *VmxonRegionPhysicalAddress ); ``` ### Parameters -*VmsSupportPhysicalAddress*\ -[in] A pointer to a 64-bit physical address that points to a virtual-machine control structure (VMCS). +*`VmxonRegionPhysicalAddress`*\ +[in] A pointer to a 64-bit, 4KB-aligned physical address that points to a VMXON region. ## Return value @@ -35,7 +35,7 @@ unsigned char __vmx_on( ## Remarks -The `__vmx_on` function corresponds to the `VMXON` machine instruction. This function supports the interaction of a host's virtual machine monitor with a guest operating system and its applications. For more information, search for the document, "Intel Virtualization Technical Specification for the IA-32 Intel Architecture," document number C97063-002, at the [Intel Corporation](https://software.intel.com/articles/intel-sdm) site. +The `__vmx_on` function corresponds to the `VMXON` machine instruction. This function supports the interaction of a host's virtual machine monitor with a guest operating system and its applications. For more information, see "Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3C: System Programming Guide, Part 3" in the [Intel 64 and IA-32 Architecture Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html). ## Requirements diff --git a/docs/intrinsics/x64-amd64-intrinsics-list.md b/docs/intrinsics/x64-amd64-intrinsics-list.md index 1fdc600dda..967215bfa0 100644 --- a/docs/intrinsics/x64-amd64-intrinsics-list.md +++ b/docs/intrinsics/x64-amd64-intrinsics-list.md @@ -1,9 +1,9 @@ --- title: "x64 (amd64) intrinsics list" description: "Reference list of x64 (AMD64) intrinsics supported by the Microsoft C++ compiler in Visual Studio." -ms.date: 02/04/2021 -f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u64", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "immintrin/_addcarryx_u64", "ammintrin/_andn_u32", "ammintrin/_andn_u64", "ammintrin/_bextr_u32", "ammintrin/_bextr_u64", "ammintrin/_bextri_u32", "ammintrin/_bextri_u64", "ammintrin/_blcfill_u32", "ammintrin/_blcfill_u64", "ammintrin/_blci_u32", "ammintrin/_blci_u64", "ammintrin/_blcic_u32", "ammintrin/_blcic_u64", "ammintrin/_blcmsk_u32", "ammintrin/_blcmsk_u64", "ammintrin/_blcs_u32", "ammintrin/_blcs_u64", "ammintrin/_blsfill_u32", "ammintrin/_blsfill_u64", "ammintrin/_blsi_u32", "ammintrin/_blsi_u64", "ammintrin/_blsic_u32", "ammintrin/_blsic_u64", "ammintrin/_blsmsk_u32", "ammintrin/_blsmsk_u64", "ammintrin/_blsr_u32", "ammintrin/_blsr_u64", "immintrin/_bzhi_u32", "immintrin/_bzhi_u64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxrstor64", "immintrin/_fxsave", "immintrin/_fxsave64", "immintrin/_invpcid", "intrin/_lgdt", "ammintrin/__llwpcb", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "immintrin/_load_be_u64", "immintrin/_loadbe_i64", "ammintrin/__lwpins32", "ammintrin/__lwpins64", "ammintrin/__lwpval32", "ammintrin/__lwpval64", "ammintrin/_lzcnt_u32", "ammintrin/_lzcnt_u64", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u64", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_si64", "intrin/_mm_cvtsd_si64x", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi128_si64", "intrin/_mm_cvtsi128_si64x", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "intrin/_mm_cvtsi64_sd", "intrin/_mm_cvtsi64_si128", "intrin/_mm_cvtsi64_ss", "intrin/_mm_cvtsi64x_sd", "intrin/_mm_cvtsi64x_si128", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtss_si64", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_cvttsd_si64", "intrin/_mm_cvttsd_si64x", "intrin/_mm_cvttss_si64", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi64", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi64", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_popcnt_u64", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64x", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64x", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi64x", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi64x", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi64x", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "immintrin/_mulx_u64", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pdep_u64", "immintrin/_pext_u32", "immintrin/_pext_u64", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdrand64_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rdseed64_step", "immintrin/_readfsbase_u32", "immintrin/_readfsbase_u64", "immintrin/_readgsbase_u32", "immintrin/_readgsbase_u64", "immintrin/_rorx_u32", "immintrin/_rorx_u64", "intrin/_rsm", "immintrin/_sarx_i32", "immintrin/_sarx_i64", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shlx_u64", "immintrin/_shrx_u32", "immintrin/_shrx_u64", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_store_be_u64", "immintrin/_storebe_i64", "immintrin/_Store_HLERelease", "immintrin/_Store64_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u64", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_t1mskc_u64", "ammintrin/_tzcnt_u32", "ammintrin/_tzcnt_u64", "ammintrin/_tzmsk_u32", "ammintrin/_tzmsk_u64", "immintrin/_writefsbase_u32", "immintrin/_writefsbase_u64", "immintrin/_writegsbase_u32", "immintrin/_writegsbase_u64", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xrstor64", "immintrin/_xsave", "immintrin/_xsave64", "immintrin/_xsaveopt", "immintrin/_xsaveopt64", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_mm_add_ps", "XMMINTRIN/_mm_add_ss", "XMMINTRIN/_mm_and_ps", "XMMINTRIN/_mm_andnot_ps", "XMMINTRIN/_mm_cmpeq_ps", "XMMINTRIN/_mm_cmpeq_ss", "XMMINTRIN/_mm_cmpge_ps", "XMMINTRIN/_mm_cmpge_ss", "XMMINTRIN/_mm_cmpgt_ps", "XMMINTRIN/_mm_cmpgt_ss", "XMMINTRIN/_mm_cmple_ps", "XMMINTRIN/_mm_cmple_ss", "XMMINTRIN/_mm_cmplt_ps", "XMMINTRIN/_mm_cmplt_ss", "XMMINTRIN/_mm_cmpneq_ps", "XMMINTRIN/_mm_cmpneq_ss", "XMMINTRIN/_mm_cmpnge_ps", "XMMINTRIN/_mm_cmpnge_ss", "XMMINTRIN/_mm_cmpngt_ps", "XMMINTRIN/_mm_cmpngt_ss", "XMMINTRIN/_mm_cmpnle_ps", "XMMINTRIN/_mm_cmpnle_ss", "XMMINTRIN/_mm_cmpnlt_ps", "XMMINTRIN/_mm_cmpnlt_ss", "XMMINTRIN/_mm_cmpord_ps", "XMMINTRIN/_mm_cmpord_ss", "XMMINTRIN/_mm_cmpunord_ps", "XMMINTRIN/_mm_cmpunord_ss", "XMMINTRIN/_mm_comieq_ss", "XMMINTRIN/_mm_comige_ss", "XMMINTRIN/_mm_comigt_ss", "XMMINTRIN/_mm_comile_ss", "XMMINTRIN/_mm_comilt_ss", "XMMINTRIN/_mm_comineq_ss", "XMMINTRIN/_mm_cvt_si2ss", "XMMINTRIN/_mm_cvt_ss2si", "XMMINTRIN/_mm_cvtpi16_ps", "XMMINTRIN/_mm_cvtpi32x2_ps", "XMMINTRIN/_mm_cvtpi8_ps", "XMMINTRIN/_mm_cvtps_pi16", "XMMINTRIN/_mm_cvtps_pi8", "XMMINTRIN/_mm_cvtpu16_ps", "XMMINTRIN/_mm_cvtpu8_ps", "XMMINTRIN/_mm_cvtsi32_ss", "XMMINTRIN/_mm_cvtsi64_ss", "XMMINTRIN/_mm_cvtss_f32", "XMMINTRIN/_mm_cvtss_si32", "XMMINTRIN/_mm_cvtss_si64", "XMMINTRIN/_mm_cvtt_ss2si", "XMMINTRIN/_mm_cvttss_si32", "XMMINTRIN/_mm_cvttss_si64", "XMMINTRIN/_mm_div_ps", "XMMINTRIN/_mm_div_ss", "XMMINTRIN/_mm_getcsr", "XMMINTRIN/_mm_load_ps", "XMMINTRIN/_mm_load_ps1", "XMMINTRIN/_mm_load_ss", "XMMINTRIN/_mm_load1_ps", "XMMINTRIN/_mm_loadh_pi", "XMMINTRIN/_mm_loadl_pi", "XMMINTRIN/_mm_loadr_ps", "XMMINTRIN/_mm_loadu_ps", "XMMINTRIN/_mm_max_ps", "XMMINTRIN/_mm_max_ss", "XMMINTRIN/_mm_min_ps", "XMMINTRIN/_mm_min_ss", "XMMINTRIN/_mm_move_ss", "XMMINTRIN/_mm_movehl_ps", "XMMINTRIN/_mm_movelh_ps", "XMMINTRIN/_mm_movemask_ps", "XMMINTRIN/_mm_mul_ps", "XMMINTRIN/_mm_mul_ss", "XMMINTRIN/_mm_or_ps", "XMMINTRIN/_mm_prefetch", "XMMINTRIN/_mm_rcp_ps", "XMMINTRIN/_mm_rcp_ss", "XMMINTRIN/_mm_rsqrt_ps", "XMMINTRIN/_mm_rsqrt_ss", "XMMINTRIN/_mm_set_ps", "XMMINTRIN/_mm_set_ps1", "XMMINTRIN/_mm_set_ss", "XMMINTRIN/_mm_set1_ps", "XMMINTRIN/_mm_setcsr", "XMMINTRIN/_mm_setr_ps", "XMMINTRIN/_mm_setzero_ps", "XMMINTRIN/_mm_sfence", "XMMINTRIN/_mm_shuffle_ps", "XMMINTRIN/_mm_sqrt_ps", "XMMINTRIN/_mm_sqrt_ss", "XMMINTRIN/_mm_store_ps", "XMMINTRIN/_mm_store_ps1", "XMMINTRIN/_mm_store_ss", "XMMINTRIN/_mm_store1_ps", "XMMINTRIN/_mm_storeh_pi", "XMMINTRIN/_mm_storel_pi", "XMMINTRIN/_mm_storer_ps", "XMMINTRIN/_mm_storeu_ps", "XMMINTRIN/_mm_stream_ps", "XMMINTRIN/_mm_sub_ps", "XMMINTRIN/_mm_sub_ss", "XMMINTRIN/_mm_ucomieq_ss", "XMMINTRIN/_mm_ucomige_ss", "XMMINTRIN/_mm_ucomigt_ss", "XMMINTRIN/_mm_ucomile_ss", "XMMINTRIN/_mm_ucomilt_ss", "XMMINTRIN/_mm_ucomineq_ss", "XMMINTRIN/_mm_unpackhi_ps", "XMMINTRIN/_mm_unpacklo_ps", "XMMINTRIN/_mm_xor_ps"] -helpviewer_keywords: ["cl-exe compiler, intrinsics", "intrinsics, x64", "intrinsics, amd64", "_addcarry_u16 x64 intrinsic", "_addcarry_u32 x64 intrinsic", "_addcarry_u64 x64 intrinsic", "_addcarry_u8 x64 intrinsic", "_addcarryx_u32 x64 intrinsic", "_addcarryx_u64 x64 intrinsic", "_andn_u32 x64 intrinsic", "_andn_u64 x64 intrinsic", "_bextr_u32 x64 intrinsic", "_bextr_u64 x64 intrinsic", "_bextri_u32 x64 intrinsic", "_bextri_u64 x64 intrinsic", "_blcfill_u32 x64 intrinsic", "_blcfill_u64 x64 intrinsic", "_blci_u32 x64 intrinsic", "_blci_u64 x64 intrinsic", "_blcic_u32 x64 intrinsic", "_blcic_u64 x64 intrinsic", "_blcmsk_u32 x64 intrinsic", "_blcmsk_u64 x64 intrinsic", "_blcs_u32 x64 intrinsic", "_blcs_u64 x64 intrinsic", "_blsfill_u32 x64 intrinsic", "_blsfill_u64 x64 intrinsic", "_blsi_u32 x64 intrinsic", "_blsi_u64 x64 intrinsic", "_blsic_u32 x64 intrinsic", "_blsic_u64 x64 intrinsic", "_blsmsk_u32 x64 intrinsic", "_blsmsk_u64 x64 intrinsic", "_blsr_u32 x64 intrinsic", "_blsr_u64 x64 intrinsic", "_bzhi_u32 x64 intrinsic", "_bzhi_u64 x64 intrinsic", "_clac x64 intrinsic", "_fxrstor x64 intrinsic", "_fxrstor64 x64 intrinsic", "_fxsave x64 intrinsic", "_fxsave64 x64 intrinsic", "_invpcid x64 intrinsic", "_lgdt x64 intrinsic", "__llwpcb x64 intrinsic", "_load_be_u16 x64 intrinsic", "_loadbe_i16 x64 intrinsic", "_load_be_u32 x64 intrinsic", "_loadbe_i32 x64 intrinsic", "_load_be_u64 x64 intrinsic", "_loadbe_i64 x64 intrinsic", "__lwpins32 x64 intrinsic", "__lwpins64 x64 intrinsic", "__lwpval32 x64 intrinsic", "__lwpval64 x64 intrinsic", "_lzcnt_u32 x64 intrinsic", "_lzcnt_u64 x64 intrinsic", "_m_prefetch x64 intrinsic", "_m_prefetchw x64 intrinsic", "_mm_abs_epi16 x64 intrinsic", "_mm_abs_epi32 x64 intrinsic", "_mm_abs_epi8 x64 intrinsic", "_mm_add_epi16 x64 intrinsic", "_mm_add_epi32 x64 intrinsic", "_mm_add_epi64 x64 intrinsic", "_mm_add_epi8 x64 intrinsic", "_mm_add_pd x64 intrinsic", "_mm_add_ps x64 intrinsic", "_mm_add_sd x64 intrinsic", "_mm_add_ss x64 intrinsic", "_mm_adds_epi16 x64 intrinsic", "_mm_adds_epi8 x64 intrinsic", "_mm_adds_epu16 x64 intrinsic", "_mm_adds_epu8 x64 intrinsic", "_mm_addsub_pd x64 intrinsic", "_mm_addsub_ps x64 intrinsic", "_mm_aesdec_si128 x64 intrinsic", "_mm_aesdeclast_si128 x64 intrinsic", "_mm_aesenc_si128 x64 intrinsic", "_mm_aesenclast_si128 x64 intrinsic", "_mm_aesimc_si128 x64 intrinsic", "_mm_aeskeygenassist_si128 x64 intrinsic", "_mm_alignr_epi8 x64 intrinsic", "_mm_and_pd x64 intrinsic", "_mm_and_ps x64 intrinsic", "_mm_and_si128 x64 intrinsic", "_mm_andnot_pd x64 intrinsic", "_mm_andnot_ps x64 intrinsic", "_mm_andnot_si128 x64 intrinsic", "_mm_avg_epu16 x64 intrinsic", "_mm_avg_epu8 x64 intrinsic", "_mm_blend_epi16 x64 intrinsic", "_mm_blend_epi32 x64 intrinsic", "_mm_blend_pd x64 intrinsic", "_mm_blend_ps x64 intrinsic", "_mm_blendv_epi8 x64 intrinsic", "_mm_blendv_pd x64 intrinsic", "_mm_blendv_ps x64 intrinsic", "_mm_broadcast_ss x64 intrinsic", "_mm_broadcastb_epi8 x64 intrinsic", "_mm_broadcastd_epi32 x64 intrinsic", "_mm_broadcastq_epi64 x64 intrinsic", "_mm_broadcastsd_pd x64 intrinsic", "_mm_broadcastss_ps x64 intrinsic", "_mm_broadcastw_epi16 x64 intrinsic", "_mm_castpd_ps x64 intrinsic", "_mm_castpd_si128 x64 intrinsic", "_mm_castps_pd x64 intrinsic", "_mm_castps_si128 x64 intrinsic", "_mm_castsi128_pd x64 intrinsic", "_mm_castsi128_ps x64 intrinsic", "_mm_clflush x64 intrinsic", "_mm_clmulepi64_si128 x64 intrinsic", "_mm_cmov_si128 x64 intrinsic", "_mm_cmp_pd x64 intrinsic", "_mm_cmp_ps x64 intrinsic", "_mm_cmp_sd x64 intrinsic", "_mm_cmp_ss x64 intrinsic", "_mm_cmpeq_epi16 x64 intrinsic", "_mm_cmpeq_epi32 x64 intrinsic", "_mm_cmpeq_epi64 x64 intrinsic", "_mm_cmpeq_epi8 x64 intrinsic", "_mm_cmpeq_pd x64 intrinsic", "_mm_cmpeq_ps x64 intrinsic", "_mm_cmpeq_sd x64 intrinsic", "_mm_cmpeq_ss x64 intrinsic", "_mm_cmpestra x64 intrinsic", "_mm_cmpestrc x64 intrinsic", "_mm_cmpestri x64 intrinsic", "_mm_cmpestrm x64 intrinsic", "_mm_cmpestro x64 intrinsic", "_mm_cmpestrs x64 intrinsic", "_mm_cmpestrz x64 intrinsic", "_mm_cmpge_pd x64 intrinsic", "_mm_cmpge_ps x64 intrinsic", "_mm_cmpge_sd x64 intrinsic", "_mm_cmpge_ss x64 intrinsic", "_mm_cmpgt_epi16 x64 intrinsic", "_mm_cmpgt_epi32 x64 intrinsic", "_mm_cmpgt_epi64 x64 intrinsic", "_mm_cmpgt_epi8 x64 intrinsic", "_mm_cmpgt_pd x64 intrinsic", "_mm_cmpgt_ps x64 intrinsic", "_mm_cmpgt_sd x64 intrinsic", "_mm_cmpgt_ss x64 intrinsic", "_mm_cmpistra x64 intrinsic", "_mm_cmpistrc x64 intrinsic", "_mm_cmpistri x64 intrinsic", "_mm_cmpistrm x64 intrinsic", "_mm_cmpistro x64 intrinsic", "_mm_cmpistrs x64 intrinsic", "_mm_cmpistrz x64 intrinsic", "_mm_cmple_pd x64 intrinsic", "_mm_cmple_ps x64 intrinsic", "_mm_cmple_sd x64 intrinsic", "_mm_cmple_ss x64 intrinsic", "_mm_cmplt_epi16 x64 intrinsic", "_mm_cmplt_epi32 x64 intrinsic", "_mm_cmplt_epi8 x64 intrinsic", "_mm_cmplt_pd x64 intrinsic", "_mm_cmplt_ps x64 intrinsic", "_mm_cmplt_sd x64 intrinsic", "_mm_cmplt_ss x64 intrinsic", "_mm_cmpneq_pd x64 intrinsic", "_mm_cmpneq_ps x64 intrinsic", "_mm_cmpneq_sd x64 intrinsic", "_mm_cmpneq_ss x64 intrinsic", "_mm_cmpnge_pd x64 intrinsic", "_mm_cmpnge_ps x64 intrinsic", "_mm_cmpnge_sd x64 intrinsic", "_mm_cmpnge_ss x64 intrinsic", "_mm_cmpngt_pd x64 intrinsic", "_mm_cmpngt_ps x64 intrinsic", "_mm_cmpngt_sd x64 intrinsic", "_mm_cmpngt_ss x64 intrinsic", "_mm_cmpnle_pd x64 intrinsic", "_mm_cmpnle_ps x64 intrinsic", "_mm_cmpnle_sd x64 intrinsic", "_mm_cmpnle_ss x64 intrinsic", "_mm_cmpnlt_pd x64 intrinsic", "_mm_cmpnlt_ps x64 intrinsic", "_mm_cmpnlt_sd x64 intrinsic", "_mm_cmpnlt_ss x64 intrinsic", "_mm_cmpord_pd x64 intrinsic", "_mm_cmpord_ps x64 intrinsic", "_mm_cmpord_sd x64 intrinsic", "_mm_cmpord_ss x64 intrinsic", "_mm_cmpunord_pd x64 intrinsic", "_mm_cmpunord_ps x64 intrinsic", "_mm_cmpunord_sd x64 intrinsic", "_mm_cmpunord_ss x64 intrinsic", "_mm_com_epi16 x64 intrinsic", "_mm_com_epi32 x64 intrinsic", "_mm_com_epi64 x64 intrinsic", "_mm_com_epi8 x64 intrinsic", "_mm_com_epu16 x64 intrinsic", "_mm_com_epu32 x64 intrinsic", "_mm_com_epu64 x64 intrinsic", "_mm_com_epu8 x64 intrinsic", "_mm_comieq_sd x64 intrinsic", "_mm_comieq_ss x64 intrinsic", "_mm_comige_sd x64 intrinsic", "_mm_comige_ss x64 intrinsic", "_mm_comigt_sd x64 intrinsic", "_mm_comigt_ss x64 intrinsic", "_mm_comile_sd x64 intrinsic", "_mm_comile_ss x64 intrinsic", "_mm_comilt_sd x64 intrinsic", "_mm_comilt_ss x64 intrinsic", "_mm_comineq_sd x64 intrinsic", "_mm_comineq_ss x64 intrinsic", "_mm_crc32_u16 x64 intrinsic", "_mm_crc32_u32 x64 intrinsic", "_mm_crc32_u64 x64 intrinsic", "_mm_crc32_u8 x64 intrinsic", "_mm_cvt_si2ss x64 intrinsic", "_mm_cvt_ss2si x64 intrinsic", "_mm_cvtepi16_epi32 x64 intrinsic", "_mm_cvtepi16_epi64 x64 intrinsic", "_mm_cvtepi32_epi64 x64 intrinsic", "_mm_cvtepi32_pd x64 intrinsic", "_mm_cvtepi32_ps x64 intrinsic", "_mm_cvtepi8_epi16 x64 intrinsic", "_mm_cvtepi8_epi32 x64 intrinsic", "_mm_cvtepi8_epi64 x64 intrinsic", "_mm_cvtepu16_epi32 x64 intrinsic", "_mm_cvtepu16_epi64 x64 intrinsic", "_mm_cvtepu32_epi64 x64 intrinsic", "_mm_cvtepu8_epi16 x64 intrinsic", "_mm_cvtepu8_epi32 x64 intrinsic", "_mm_cvtepu8_epi64 x64 intrinsic", "_mm_cvtpd_epi32 x64 intrinsic", "_mm_cvtpd_ps x64 intrinsic", "_mm_cvtph_ps x64 intrinsic", "_mm_cvtps_epi32 x64 intrinsic", "_mm_cvtps_pd x64 intrinsic", "_mm_cvtps_ph x64 intrinsic", "_mm_cvtsd_f64 x64 intrinsic", "_mm_cvtsd_si32 x64 intrinsic", "_mm_cvtsd_si64 x64 intrinsic", "_mm_cvtsd_si64x x64 intrinsic", "_mm_cvtsd_ss x64 intrinsic", "_mm_cvtsi128_si32 x64 intrinsic", "_mm_cvtsi128_si64 x64 intrinsic", "_mm_cvtsi128_si64x x64 intrinsic", "_mm_cvtsi32_sd x64 intrinsic", "_mm_cvtsi32_si128 x64 intrinsic", "_mm_cvtsi64_sd x64 intrinsic", "_mm_cvtsi64_si128 x64 intrinsic", "_mm_cvtsi64_ss x64 intrinsic", "_mm_cvtsi64x_sd x64 intrinsic", "_mm_cvtsi64x_si128 x64 intrinsic", "_mm_cvtss_f32 x64 intrinsic", "_mm_cvtss_sd x64 intrinsic", "_mm_cvtss_si64 x64 intrinsic", "_mm_cvtt_ss2si x64 intrinsic", "_mm_cvttpd_epi32 x64 intrinsic", "_mm_cvttps_epi32 x64 intrinsic", "_mm_cvttsd_si32 x64 intrinsic", "_mm_cvttsd_si64 x64 intrinsic", "_mm_cvttsd_si64x x64 intrinsic", "_mm_cvttss_si64 x64 intrinsic", "_mm_div_pd x64 intrinsic", "_mm_div_ps x64 intrinsic", "_mm_div_sd x64 intrinsic", "_mm_div_ss x64 intrinsic", "_mm_dp_pd x64 intrinsic", "_mm_dp_ps x64 intrinsic", "_mm_extract_epi16 x64 intrinsic", "_mm_extract_epi32 x64 intrinsic", "_mm_extract_epi64 x64 intrinsic", "_mm_extract_epi8 x64 intrinsic", "_mm_extract_ps x64 intrinsic", "_mm_fmadd_pd x64 intrinsic", "_mm_fmadd_ps x64 intrinsic", "_mm_fmadd_sd x64 intrinsic", "_mm_fmadd_ss x64 intrinsic", "_mm_fmaddsub_pd x64 intrinsic", "_mm_fmaddsub_ps x64 intrinsic", "_mm_fmsub_pd x64 intrinsic", "_mm_fmsub_ps x64 intrinsic", "_mm_fmsub_sd x64 intrinsic", "_mm_fmsub_ss x64 intrinsic", "_mm_fmsubadd_pd x64 intrinsic", "_mm_fmsubadd_ps x64 intrinsic", "_mm_fnmadd_pd x64 intrinsic", "_mm_fnmadd_ps x64 intrinsic", "_mm_fnmadd_sd x64 intrinsic", "_mm_fnmadd_ss x64 intrinsic", "_mm_fnmsub_pd x64 intrinsic", "_mm_fnmsub_ps x64 intrinsic", "_mm_fnmsub_sd x64 intrinsic", "_mm_fnmsub_ss x64 intrinsic", "_mm_frcz_pd x64 intrinsic", "_mm_frcz_ps x64 intrinsic", "_mm_frcz_sd x64 intrinsic", "_mm_frcz_ss x64 intrinsic", "_mm_getcsr x64 intrinsic", "_mm_hadd_epi16 x64 intrinsic", "_mm_hadd_epi32 x64 intrinsic", "_mm_hadd_pd x64 intrinsic", "_mm_hadd_ps x64 intrinsic", "_mm_haddd_epi16 x64 intrinsic", "_mm_haddd_epi8 x64 intrinsic", "_mm_haddd_epu16 x64 intrinsic", "_mm_haddd_epu8 x64 intrinsic", "_mm_haddq_epi16 x64 intrinsic", "_mm_haddq_epi32 x64 intrinsic", "_mm_haddq_epi8 x64 intrinsic", "_mm_haddq_epu16 x64 intrinsic", "_mm_haddq_epu32 x64 intrinsic", "_mm_haddq_epu8 x64 intrinsic", "_mm_hadds_epi16 x64 intrinsic", "_mm_haddw_epi8 x64 intrinsic", "_mm_haddw_epu8 x64 intrinsic", "_mm_hsub_epi16 x64 intrinsic", "_mm_hsub_epi32 x64 intrinsic", "_mm_hsub_pd x64 intrinsic", "_mm_hsub_ps x64 intrinsic", "_mm_hsubd_epi16 x64 intrinsic", "_mm_hsubq_epi32 x64 intrinsic", "_mm_hsubs_epi16 x64 intrinsic", "_mm_hsubw_epi8 x64 intrinsic", "_mm_i32gather_epi32 x64 intrinsic", "_mm_i32gather_epi64 x64 intrinsic", "_mm_i32gather_pd x64 intrinsic", "_mm_i32gather_ps x64 intrinsic", "_mm_i64gather_epi32 x64 intrinsic", "_mm_i64gather_epi64 x64 intrinsic", "_mm_i64gather_pd x64 intrinsic", "_mm_i64gather_ps x64 intrinsic", "_mm_insert_epi16 x64 intrinsic", "_mm_insert_epi32 x64 intrinsic", "_mm_insert_epi64 x64 intrinsic", "_mm_insert_epi8 x64 intrinsic", "_mm_insert_ps x64 intrinsic", "_mm_lddqu_si128 x64 intrinsic", "_mm_lfence x64 intrinsic", "_mm_load_pd x64 intrinsic", "_mm_load_ps x64 intrinsic", "_mm_load_ps1 x64 intrinsic", "_mm_load_sd x64 intrinsic", "_mm_load_si128 x64 intrinsic", "_mm_load_ss x64 intrinsic", "_mm_load1_pd x64 intrinsic", "_mm_loaddup_pd x64 intrinsic", "_mm_loadh_pd x64 intrinsic", "_mm_loadh_pi x64 intrinsic", "_mm_loadl_epi64 x64 intrinsic", "_mm_loadl_pd x64 intrinsic", "_mm_loadl_pi x64 intrinsic", "_mm_loadr_pd x64 intrinsic", "_mm_loadr_ps x64 intrinsic", "_mm_loadu_pd x64 intrinsic", "_mm_loadu_ps x64 intrinsic", "_mm_loadu_si128 x64 intrinsic", "_mm_macc_epi16 x64 intrinsic", "_mm_macc_epi32 x64 intrinsic", "_mm_macc_pd x64 intrinsic", "_mm_macc_ps x64 intrinsic", "_mm_macc_sd x64 intrinsic", "_mm_macc_ss x64 intrinsic", "_mm_maccd_epi16 x64 intrinsic", "_mm_macchi_epi32 x64 intrinsic", "_mm_macclo_epi32 x64 intrinsic", "_mm_maccs_epi16 x64 intrinsic", "_mm_maccs_epi32 x64 intrinsic", "_mm_maccsd_epi16 x64 intrinsic", "_mm_maccshi_epi32 x64 intrinsic", "_mm_maccslo_epi32 x64 intrinsic", "_mm_madd_epi16 x64 intrinsic", "_mm_maddd_epi16 x64 intrinsic", "_mm_maddsd_epi16 x64 intrinsic", "_mm_maddsub_pd x64 intrinsic", "_mm_maddsub_ps x64 intrinsic", "_mm_maddubs_epi16 x64 intrinsic", "_mm_mask_i32gather_epi32 x64 intrinsic", "_mm_mask_i32gather_epi64 x64 intrinsic", "_mm_mask_i32gather_pd x64 intrinsic", "_mm_mask_i32gather_ps x64 intrinsic", "_mm_mask_i64gather_epi32 x64 intrinsic", "_mm_mask_i64gather_epi64 x64 intrinsic", "_mm_mask_i64gather_pd x64 intrinsic", "_mm_mask_i64gather_ps x64 intrinsic", "_mm_maskload_epi32 x64 intrinsic", "_mm_maskload_epi64 x64 intrinsic", "_mm_maskload_pd x64 intrinsic", "_mm_maskload_ps x64 intrinsic", "_mm_maskmoveu_si128 x64 intrinsic", "_mm_maskstore_epi32 x64 intrinsic", "_mm_maskstore_epi64 x64 intrinsic", "_mm_maskstore_pd x64 intrinsic", "_mm_maskstore_ps x64 intrinsic", "_mm_max_epi16 x64 intrinsic", "_mm_max_epi32 x64 intrinsic", "_mm_max_epi8 x64 intrinsic", "_mm_max_epu16 x64 intrinsic", "_mm_max_epu32 x64 intrinsic", "_mm_max_epu8 x64 intrinsic", "_mm_max_pd x64 intrinsic", "_mm_max_ps x64 intrinsic", "_mm_max_sd x64 intrinsic", "_mm_max_ss x64 intrinsic", "_mm_mfence x64 intrinsic", "_mm_min_epi16 x64 intrinsic", "_mm_min_epi32 x64 intrinsic", "_mm_min_epi8 x64 intrinsic", "_mm_min_epu16 x64 intrinsic", "_mm_min_epu32 x64 intrinsic", "_mm_min_epu8 x64 intrinsic", "_mm_min_pd x64 intrinsic", "_mm_min_ps x64 intrinsic", "_mm_min_sd x64 intrinsic", "_mm_min_ss x64 intrinsic", "_mm_minpos_epu16 x64 intrinsic", "_mm_monitor x64 intrinsic", "_mm_move_epi64 x64 intrinsic", "_mm_move_sd x64 intrinsic", "_mm_move_ss x64 intrinsic", "_mm_movedup_pd x64 intrinsic", "_mm_movehdup_ps x64 intrinsic", "_mm_movehl_ps x64 intrinsic", "_mm_moveldup_ps x64 intrinsic", "_mm_movelh_ps x64 intrinsic", "_mm_movemask_epi8 x64 intrinsic", "_mm_movemask_pd x64 intrinsic", "_mm_movemask_ps x64 intrinsic", "_mm_mpsadbw_epu8 x64 intrinsic", "_mm_msub_pd x64 intrinsic", "_mm_msub_ps x64 intrinsic", "_mm_msub_sd x64 intrinsic", "_mm_msub_ss x64 intrinsic", "_mm_msubadd_pd x64 intrinsic", "_mm_msubadd_ps x64 intrinsic", "_mm_mul_epi32 x64 intrinsic", "_mm_mul_epu32 x64 intrinsic", "_mm_mul_pd x64 intrinsic", "_mm_mul_ps x64 intrinsic", "_mm_mul_sd x64 intrinsic", "_mm_mul_ss x64 intrinsic", "_mm_mulhi_epi16 x64 intrinsic", "_mm_mulhi_epu16 x64 intrinsic", "_mm_mulhrs_epi16 x64 intrinsic", "_mm_mullo_epi16 x64 intrinsic", "_mm_mullo_epi32 x64 intrinsic", "_mm_mwait x64 intrinsic", "_mm_nmacc_pd x64 intrinsic", "_mm_nmacc_ps x64 intrinsic", "_mm_nmacc_sd x64 intrinsic", "_mm_nmacc_ss x64 intrinsic", "_mm_nmsub_pd x64 intrinsic", "_mm_nmsub_ps x64 intrinsic", "_mm_nmsub_sd x64 intrinsic", "_mm_nmsub_ss x64 intrinsic", "_mm_or_pd x64 intrinsic", "_mm_or_ps x64 intrinsic", "_mm_or_si128 x64 intrinsic", "_mm_packs_epi16 x64 intrinsic", "_mm_packs_epi32 x64 intrinsic", "_mm_packus_epi16 x64 intrinsic", "_mm_packus_epi32 x64 intrinsic", "_mm_pause x64 intrinsic", "_mm_perm_epi8 x64 intrinsic", "_mm_permute_pd x64 intrinsic", "_mm_permute_ps x64 intrinsic", "_mm_permute2_pd x64 intrinsic", "_mm_permute2_ps x64 intrinsic", "_mm_permutevar_pd x64 intrinsic", "_mm_permutevar_ps x64 intrinsic", "_mm_popcnt_u32 x64 intrinsic", "_mm_popcnt_u64 x64 intrinsic", "_mm_prefetch x64 intrinsic", "_mm_rcp_ps x64 intrinsic", "_mm_rcp_ss x64 intrinsic", "_mm_rot_epi16 x64 intrinsic", "_mm_rot_epi32 x64 intrinsic", "_mm_rot_epi64 x64 intrinsic", "_mm_rot_epi8 x64 intrinsic", "_mm_roti_epi16 x64 intrinsic", "_mm_roti_epi32 x64 intrinsic", "_mm_roti_epi64 x64 intrinsic", "_mm_roti_epi8 x64 intrinsic", "_mm_round_pd x64 intrinsic", "_mm_round_ps x64 intrinsic", "_mm_round_sd x64 intrinsic", "_mm_round_ss x64 intrinsic", "_mm_rsqrt_ps x64 intrinsic", "_mm_rsqrt_ss x64 intrinsic", "_mm_sad_epu8 x64 intrinsic", "_mm_set_epi16 x64 intrinsic", "_mm_set_epi32 x64 intrinsic", "_mm_set_epi64x x64 intrinsic", "_mm_set_epi8 x64 intrinsic", "_mm_set_pd x64 intrinsic", "_mm_set_ps x64 intrinsic", "_mm_set_ps1 x64 intrinsic", "_mm_set_sd x64 intrinsic", "_mm_set_ss x64 intrinsic", "_mm_set1_epi16 x64 intrinsic", "_mm_set1_epi32 x64 intrinsic", "_mm_set1_epi64x x64 intrinsic", "_mm_set1_epi8 x64 intrinsic", "_mm_set1_pd x64 intrinsic", "_mm_setcsr x64 intrinsic", "_mm_setl_epi64 x64 intrinsic", "_mm_setr_epi16 x64 intrinsic", "_mm_setr_epi32 x64 intrinsic", "_mm_setr_epi8 x64 intrinsic", "_mm_setr_pd x64 intrinsic", "_mm_setr_ps x64 intrinsic", "_mm_setzero_pd x64 intrinsic", "_mm_setzero_ps x64 intrinsic", "_mm_setzero_si128 x64 intrinsic", "_mm_sfence x64 intrinsic", "_mm_sha_epi16 x64 intrinsic", "_mm_sha_epi32 x64 intrinsic", "_mm_sha_epi64 x64 intrinsic", "_mm_sha_epi8 x64 intrinsic", "_mm_shl_epi16 x64 intrinsic", "_mm_shl_epi32 x64 intrinsic", "_mm_shl_epi64 x64 intrinsic", "_mm_shl_epi8 x64 intrinsic", "_mm_shuffle_epi32 x64 intrinsic", "_mm_shuffle_epi8 x64 intrinsic", "_mm_shuffle_pd x64 intrinsic", "_mm_shuffle_ps x64 intrinsic", "_mm_shufflehi_epi16 x64 intrinsic", "_mm_shufflelo_epi16 x64 intrinsic", "_mm_sign_epi16 x64 intrinsic", "_mm_sign_epi32 x64 intrinsic", "_mm_sign_epi8 x64 intrinsic", "_mm_sll_epi16 x64 intrinsic", "_mm_sll_epi32 x64 intrinsic", "_mm_sll_epi64 x64 intrinsic", "_mm_slli_epi16 x64 intrinsic", "_mm_slli_epi32 x64 intrinsic", "_mm_slli_epi64 x64 intrinsic", "_mm_slli_si128 x64 intrinsic", "_mm_sllv_epi32 x64 intrinsic", "_mm_sllv_epi64 x64 intrinsic", "_mm_sqrt_pd x64 intrinsic", "_mm_sqrt_ps x64 intrinsic", "_mm_sqrt_sd x64 intrinsic", "_mm_sqrt_ss x64 intrinsic", "_mm_sra_epi16 x64 intrinsic", "_mm_sra_epi32 x64 intrinsic", "_mm_srai_epi16 x64 intrinsic", "_mm_srai_epi32 x64 intrinsic", "_mm_srav_epi32 x64 intrinsic", "_mm_srl_epi16 x64 intrinsic", "_mm_srl_epi32 x64 intrinsic", "_mm_srl_epi64 x64 intrinsic", "_mm_srli_epi16 x64 intrinsic", "_mm_srli_epi32 x64 intrinsic", "_mm_srli_epi64 x64 intrinsic", "_mm_srli_si128 x64 intrinsic", "_mm_srlv_epi32 x64 intrinsic", "_mm_srlv_epi64 x64 intrinsic", "_mm_store_pd x64 intrinsic", "_mm_store_ps x64 intrinsic", "_mm_store_ps1 x64 intrinsic", "_mm_store_sd x64 intrinsic", "_mm_store_si128 x64 intrinsic", "_mm_store_ss x64 intrinsic", "_mm_store1_pd x64 intrinsic", "_mm_storeh_pd x64 intrinsic", "_mm_storeh_pi x64 intrinsic", "_mm_storel_epi64 x64 intrinsic", "_mm_storel_pd x64 intrinsic", "_mm_storel_pi x64 intrinsic", "_mm_storer_pd x64 intrinsic", "_mm_storer_ps x64 intrinsic", "_mm_storeu_pd x64 intrinsic", "_mm_storeu_ps x64 intrinsic", "_mm_storeu_si128 x64 intrinsic", "_mm_stream_load_si128 x64 intrinsic", "_mm_stream_pd x64 intrinsic", "_mm_stream_ps x64 intrinsic", "_mm_stream_si128 x64 intrinsic", "_mm_stream_si32 x64 intrinsic", "_mm_sub_epi16 x64 intrinsic", "_mm_sub_epi32 x64 intrinsic", "_mm_sub_epi64 x64 intrinsic", "_mm_sub_epi8 x64 intrinsic", "_mm_sub_pd x64 intrinsic", "_mm_sub_ps x64 intrinsic", "_mm_sub_sd x64 intrinsic", "_mm_sub_ss x64 intrinsic", "_mm_subs_epi16 x64 intrinsic", "_mm_subs_epi8 x64 intrinsic", "_mm_subs_epu16 x64 intrinsic", "_mm_subs_epu8 x64 intrinsic", "_mm_testc_pd x64 intrinsic", "_mm_testc_ps x64 intrinsic", "_mm_testc_si128 x64 intrinsic", "_mm_testnzc_pd x64 intrinsic", "_mm_testnzc_ps x64 intrinsic", "_mm_testnzc_si128 x64 intrinsic", "_mm_testz_pd x64 intrinsic", "_mm_testz_ps x64 intrinsic", "_mm_testz_si128 x64 intrinsic", "_mm_ucomieq_sd x64 intrinsic", "_mm_ucomieq_ss x64 intrinsic", "_mm_ucomige_sd x64 intrinsic", "_mm_ucomige_ss x64 intrinsic", "_mm_ucomigt_sd x64 intrinsic", "_mm_ucomigt_ss x64 intrinsic", "_mm_ucomile_sd x64 intrinsic", "_mm_ucomile_ss x64 intrinsic", "_mm_ucomilt_sd x64 intrinsic", "_mm_ucomilt_ss x64 intrinsic", "_mm_ucomineq_sd x64 intrinsic", "_mm_ucomineq_ss x64 intrinsic", "_mm_unpackhi_epi16 x64 intrinsic", "_mm_unpackhi_epi32 x64 intrinsic", "_mm_unpackhi_epi64 x64 intrinsic", "_mm_unpackhi_epi8 x64 intrinsic", "_mm_unpackhi_pd x64 intrinsic", "_mm_unpackhi_ps x64 intrinsic", "_mm_unpacklo_epi16 x64 intrinsic", "_mm_unpacklo_epi32 x64 intrinsic", "_mm_unpacklo_epi64 x64 intrinsic", "_mm_unpacklo_epi8 x64 intrinsic", "_mm_unpacklo_pd x64 intrinsic", "_mm_unpacklo_ps x64 intrinsic", "_mm_xor_pd x64 intrinsic", "_mm_xor_ps x64 intrinsic", "_mm_xor_si128 x64 intrinsic", "_mm256_abs_epi16 x64 intrinsic", "_mm256_abs_epi32 x64 intrinsic", "_mm256_abs_epi8 x64 intrinsic", "_mm256_add_epi16 x64 intrinsic", "_mm256_add_epi32 x64 intrinsic", "_mm256_add_epi64 x64 intrinsic", "_mm256_add_epi8 x64 intrinsic", "_mm256_add_pd x64 intrinsic", "_mm256_add_ps x64 intrinsic", "_mm256_adds_epi16 x64 intrinsic", "_mm256_adds_epi8 x64 intrinsic", "_mm256_adds_epu16 x64 intrinsic", "_mm256_adds_epu8 x64 intrinsic", "_mm256_addsub_pd x64 intrinsic", "_mm256_addsub_ps x64 intrinsic", "_mm256_alignr_epi8 x64 intrinsic", "_mm256_and_pd x64 intrinsic", "_mm256_and_ps x64 intrinsic", "_mm256_and_si256 x64 intrinsic", "_mm256_andnot_pd x64 intrinsic", "_mm256_andnot_ps x64 intrinsic", "_mm256_andnot_si256 x64 intrinsic", "_mm256_avg_epu16 x64 intrinsic", "_mm256_avg_epu8 x64 intrinsic", "_mm256_blend_epi16 x64 intrinsic", "_mm256_blend_epi32 x64 intrinsic", "_mm256_blend_pd x64 intrinsic", "_mm256_blend_ps x64 intrinsic", "_mm256_blendv_epi8 x64 intrinsic", "_mm256_blendv_pd x64 intrinsic", "_mm256_blendv_ps x64 intrinsic", "_mm256_broadcast_pd x64 intrinsic", "_mm256_broadcast_ps x64 intrinsic", "_mm256_broadcast_sd x64 intrinsic", "_mm256_broadcast_ss x64 intrinsic", "_mm256_broadcastb_epi8 x64 intrinsic", "_mm256_broadcastd_epi32 x64 intrinsic", "_mm256_broadcastq_epi64 x64 intrinsic", "_mm256_broadcastsd_pd x64 intrinsic", "_mm256_broadcastsi128_si256 x64 intrinsic", "_mm256_broadcastss_ps x64 intrinsic", "_mm256_broadcastw_epi16 x64 intrinsic", "_mm256_castpd_ps x64 intrinsic", "_mm256_castpd_si256 x64 intrinsic", "_mm256_castpd128_pd256 x64 intrinsic", "_mm256_castpd256_pd128 x64 intrinsic", "_mm256_castps_pd x64 intrinsic", "_mm256_castps_si256 x64 intrinsic", "_mm256_castps128_ps256 x64 intrinsic", "_mm256_castps256_ps128 x64 intrinsic", "_mm256_castsi128_si256 x64 intrinsic", "_mm256_castsi256_pd x64 intrinsic", "_mm256_castsi256_ps x64 intrinsic", "_mm256_castsi256_si128 x64 intrinsic", "_mm256_cmov_si256 x64 intrinsic", "_mm256_cmp_pd x64 intrinsic", "_mm256_cmp_ps x64 intrinsic", "_mm256_cmpeq_epi16 x64 intrinsic", "_mm256_cmpeq_epi32 x64 intrinsic", "_mm256_cmpeq_epi64 x64 intrinsic", "_mm256_cmpeq_epi8 x64 intrinsic", "_mm256_cmpgt_epi16 x64 intrinsic", "_mm256_cmpgt_epi32 x64 intrinsic", "_mm256_cmpgt_epi64 x64 intrinsic", "_mm256_cmpgt_epi8 x64 intrinsic", "_mm256_cvtepi16_epi32 x64 intrinsic", "_mm256_cvtepi16_epi64 x64 intrinsic", "_mm256_cvtepi32_epi64 x64 intrinsic", "_mm256_cvtepi32_pd x64 intrinsic", "_mm256_cvtepi32_ps x64 intrinsic", "_mm256_cvtepi8_epi16 x64 intrinsic", "_mm256_cvtepi8_epi32 x64 intrinsic", "_mm256_cvtepi8_epi64 x64 intrinsic", "_mm256_cvtepu16_epi32 x64 intrinsic", "_mm256_cvtepu16_epi64 x64 intrinsic", "_mm256_cvtepu32_epi64 x64 intrinsic", "_mm256_cvtepu8_epi16 x64 intrinsic", "_mm256_cvtepu8_epi32 x64 intrinsic", "_mm256_cvtepu8_epi64 x64 intrinsic", "_mm256_cvtpd_epi32 x64 intrinsic", "_mm256_cvtpd_ps x64 intrinsic", "_mm256_cvtph_ps x64 intrinsic", "_mm256_cvtps_epi32 x64 intrinsic", "_mm256_cvtps_pd x64 intrinsic", "_mm256_cvtps_ph x64 intrinsic", "_mm256_cvttpd_epi32 x64 intrinsic", "_mm256_cvttps_epi32 x64 intrinsic", "_mm256_div_pd x64 intrinsic", "_mm256_div_ps x64 intrinsic", "_mm256_dp_ps x64 intrinsic", "_mm256_extractf128_pd x64 intrinsic", "_mm256_extractf128_ps x64 intrinsic", "_mm256_extractf128_si256 x64 intrinsic", "_mm256_extracti128_si256 x64 intrinsic", "_mm256_fmadd_pd x64 intrinsic", "_mm256_fmadd_ps x64 intrinsic", "_mm256_fmaddsub_pd x64 intrinsic", "_mm256_fmaddsub_ps x64 intrinsic", "_mm256_fmsub_pd x64 intrinsic", "_mm256_fmsub_ps x64 intrinsic", "_mm256_fmsubadd_pd x64 intrinsic", "_mm256_fmsubadd_ps x64 intrinsic", "_mm256_fnmadd_pd x64 intrinsic", "_mm256_fnmadd_ps x64 intrinsic", "_mm256_fnmsub_pd x64 intrinsic", "_mm256_fnmsub_ps x64 intrinsic", "_mm256_frcz_pd x64 intrinsic", "_mm256_frcz_ps x64 intrinsic", "_mm256_hadd_epi16 x64 intrinsic", "_mm256_hadd_epi32 x64 intrinsic", "_mm256_hadd_pd x64 intrinsic", "_mm256_hadd_ps x64 intrinsic", "_mm256_hadds_epi16 x64 intrinsic", "_mm256_hsub_epi16 x64 intrinsic", "_mm256_hsub_epi32 x64 intrinsic", "_mm256_hsub_pd x64 intrinsic", "_mm256_hsub_ps x64 intrinsic", "_mm256_hsubs_epi16 x64 intrinsic", "_mm256_i32gather_epi32 x64 intrinsic", "_mm256_i32gather_epi64 x64 intrinsic", "_mm256_i32gather_pd x64 intrinsic", "_mm256_i32gather_ps x64 intrinsic", "_mm256_i64gather_epi32 x64 intrinsic", "_mm256_i64gather_epi64 x64 intrinsic", "_mm256_i64gather_pd x64 intrinsic", "_mm256_i64gather_ps x64 intrinsic", "_mm256_insertf128_pd x64 intrinsic", "_mm256_insertf128_ps x64 intrinsic", "_mm256_insertf128_si256 x64 intrinsic", "_mm256_inserti128_si256 x64 intrinsic", "_mm256_lddqu_si256 x64 intrinsic", "_mm256_load_pd x64 intrinsic", "_mm256_load_ps x64 intrinsic", "_mm256_load_si256 x64 intrinsic", "_mm256_loadu_pd x64 intrinsic", "_mm256_loadu_ps x64 intrinsic", "_mm256_loadu_si256 x64 intrinsic", "_mm256_macc_pd x64 intrinsic", "_mm256_macc_ps x64 intrinsic", "_mm256_madd_epi16 x64 intrinsic", "_mm256_maddsub_pd x64 intrinsic", "_mm256_maddsub_ps x64 intrinsic", "_mm256_maddubs_epi16 x64 intrinsic", "_mm256_mask_i32gather_epi32 x64 intrinsic", "_mm256_mask_i32gather_epi64 x64 intrinsic", "_mm256_mask_i32gather_pd x64 intrinsic", "_mm256_mask_i32gather_ps x64 intrinsic", "_mm256_mask_i64gather_epi32 x64 intrinsic", "_mm256_mask_i64gather_epi64 x64 intrinsic", "_mm256_mask_i64gather_pd x64 intrinsic", "_mm256_mask_i64gather_ps x64 intrinsic", "_mm256_maskload_epi32 x64 intrinsic", "_mm256_maskload_epi64 x64 intrinsic", "_mm256_maskload_pd x64 intrinsic", "_mm256_maskload_ps x64 intrinsic", "_mm256_maskstore_epi32 x64 intrinsic", "_mm256_maskstore_epi64 x64 intrinsic", "_mm256_maskstore_pd x64 intrinsic", "_mm256_maskstore_ps x64 intrinsic", "_mm256_max_epi16 x64 intrinsic", "_mm256_max_epi32 x64 intrinsic", "_mm256_max_epi8 x64 intrinsic", "_mm256_max_epu16 x64 intrinsic", "_mm256_max_epu32 x64 intrinsic", "_mm256_max_epu8 x64 intrinsic", "_mm256_max_pd x64 intrinsic", "_mm256_max_ps x64 intrinsic", "_mm256_min_epi16 x64 intrinsic", "_mm256_min_epi32 x64 intrinsic", "_mm256_min_epi8 x64 intrinsic", "_mm256_min_epu16 x64 intrinsic", "_mm256_min_epu32 x64 intrinsic", "_mm256_min_epu8 x64 intrinsic", "_mm256_min_pd x64 intrinsic", "_mm256_min_ps x64 intrinsic", "_mm256_movedup_pd x64 intrinsic", "_mm256_movehdup_ps x64 intrinsic", "_mm256_moveldup_ps x64 intrinsic", "_mm256_movemask_epi8 x64 intrinsic", "_mm256_movemask_pd x64 intrinsic", "_mm256_movemask_ps x64 intrinsic", "_mm256_mpsadbw_epu8 x64 intrinsic", "_mm256_msub_pd x64 intrinsic", "_mm256_msub_ps x64 intrinsic", "_mm256_msubadd_pd x64 intrinsic", "_mm256_msubadd_ps x64 intrinsic", "_mm256_mul_epi32 x64 intrinsic", "_mm256_mul_epu32 x64 intrinsic", "_mm256_mul_pd x64 intrinsic", "_mm256_mul_ps x64 intrinsic", "_mm256_mulhi_epi16 x64 intrinsic", "_mm256_mulhi_epu16 x64 intrinsic", "_mm256_mulhrs_epi16 x64 intrinsic", "_mm256_mullo_epi16 x64 intrinsic", "_mm256_mullo_epi32 x64 intrinsic", "_mm256_nmacc_pd x64 intrinsic", "_mm256_nmacc_ps x64 intrinsic", "_mm256_nmsub_pd x64 intrinsic", "_mm256_nmsub_ps x64 intrinsic", "_mm256_or_pd x64 intrinsic", "_mm256_or_ps x64 intrinsic", "_mm256_or_si256 x64 intrinsic", "_mm256_packs_epi16 x64 intrinsic", "_mm256_packs_epi32 x64 intrinsic", "_mm256_packus_epi16 x64 intrinsic", "_mm256_packus_epi32 x64 intrinsic", "_mm256_permute_pd x64 intrinsic", "_mm256_permute_ps x64 intrinsic", "_mm256_permute2_pd x64 intrinsic", "_mm256_permute2_ps x64 intrinsic", "_mm256_permute2f128_pd x64 intrinsic", "_mm256_permute2f128_ps x64 intrinsic", "_mm256_permute2f128_si256 x64 intrinsic", "_mm256_permute2x128_si256 x64 intrinsic", "_mm256_permute4x64_epi64 x64 intrinsic", "_mm256_permute4x64_pd x64 intrinsic", "_mm256_permutevar_pd x64 intrinsic", "_mm256_permutevar_ps x64 intrinsic", "_mm256_permutevar8x32_epi32 x64 intrinsic", "_mm256_permutevar8x32_ps x64 intrinsic", "_mm256_rcp_ps x64 intrinsic", "_mm256_round_pd x64 intrinsic", "_mm256_round_ps x64 intrinsic", "_mm256_rsqrt_ps x64 intrinsic", "_mm256_sad_epu8 x64 intrinsic", "_mm256_set_epi16 x64 intrinsic", "_mm256_set_epi32 x64 intrinsic", "_mm256_set_epi64x x64 intrinsic", "_mm256_set_epi8 x64 intrinsic", "_mm256_set_pd x64 intrinsic", "_mm256_set_ps x64 intrinsic", "_mm256_set1_epi16 x64 intrinsic", "_mm256_set1_epi32 x64 intrinsic", "_mm256_set1_epi64x x64 intrinsic", "_mm256_set1_epi8 x64 intrinsic", "_mm256_set1_pd x64 intrinsic", "_mm256_set1_ps x64 intrinsic", "_mm256_setr_epi16 x64 intrinsic", "_mm256_setr_epi32 x64 intrinsic", "_mm256_setr_epi64x x64 intrinsic", "_mm256_setr_epi8 x64 intrinsic", "_mm256_setr_pd x64 intrinsic", "_mm256_setr_ps x64 intrinsic", "_mm256_setzero_pd x64 intrinsic", "_mm256_setzero_ps x64 intrinsic", "_mm256_setzero_si256 x64 intrinsic", "_mm256_shuffle_epi32 x64 intrinsic", "_mm256_shuffle_epi8 x64 intrinsic", "_mm256_shuffle_pd x64 intrinsic", "_mm256_shuffle_ps x64 intrinsic", "_mm256_shufflehi_epi16 x64 intrinsic", "_mm256_shufflelo_epi16 x64 intrinsic", "_mm256_sign_epi16 x64 intrinsic", "_mm256_sign_epi32 x64 intrinsic", "_mm256_sign_epi8 x64 intrinsic", "_mm256_sll_epi16 x64 intrinsic", "_mm256_sll_epi32 x64 intrinsic", "_mm256_sll_epi64 x64 intrinsic", "_mm256_slli_epi16 x64 intrinsic", "_mm256_slli_epi32 x64 intrinsic", "_mm256_slli_epi64 x64 intrinsic", "_mm256_slli_si256 x64 intrinsic", "_mm256_sllv_epi32 x64 intrinsic", "_mm256_sllv_epi64 x64 intrinsic", "_mm256_sqrt_pd x64 intrinsic", "_mm256_sqrt_ps x64 intrinsic", "_mm256_sra_epi16 x64 intrinsic", "_mm256_sra_epi32 x64 intrinsic", "_mm256_srai_epi16 x64 intrinsic", "_mm256_srai_epi32 x64 intrinsic", "_mm256_srav_epi32 x64 intrinsic", "_mm256_srl_epi16 x64 intrinsic", "_mm256_srl_epi32 x64 intrinsic", "_mm256_srl_epi64 x64 intrinsic", "_mm256_srli_epi16 x64 intrinsic", "_mm256_srli_epi32 x64 intrinsic", "_mm256_srli_epi64 x64 intrinsic", "_mm256_srli_si256 x64 intrinsic", "_mm256_srlv_epi32 x64 intrinsic", "_mm256_srlv_epi64 x64 intrinsic", "_mm256_store_pd x64 intrinsic", "_mm256_store_ps x64 intrinsic", "_mm256_store_si256 x64 intrinsic", "_mm256_storeu_pd x64 intrinsic", "_mm256_storeu_ps x64 intrinsic", "_mm256_storeu_si256 x64 intrinsic", "_mm256_stream_load_si256 x64 intrinsic", "_mm256_stream_pd x64 intrinsic", "_mm256_stream_ps x64 intrinsic", "_mm256_stream_si256 x64 intrinsic", "_mm256_sub_epi16 x64 intrinsic", "_mm256_sub_epi32 x64 intrinsic", "_mm256_sub_epi64 x64 intrinsic", "_mm256_sub_epi8 x64 intrinsic", "_mm256_sub_pd x64 intrinsic", "_mm256_sub_ps x64 intrinsic", "_mm256_subs_epi16 x64 intrinsic", "_mm256_subs_epi8 x64 intrinsic", "_mm256_subs_epu16 x64 intrinsic", "_mm256_subs_epu8 x64 intrinsic", "_mm256_testc_pd x64 intrinsic", "_mm256_testc_ps x64 intrinsic", "_mm256_testc_si256 x64 intrinsic", "_mm256_testnzc_pd x64 intrinsic", "_mm256_testnzc_ps x64 intrinsic", "_mm256_testnzc_si256 x64 intrinsic", "_mm256_testz_pd x64 intrinsic", "_mm256_testz_ps x64 intrinsic", "_mm256_testz_si256 x64 intrinsic", "_mm256_unpackhi_epi16 x64 intrinsic", "_mm256_unpackhi_epi32 x64 intrinsic", "_mm256_unpackhi_epi64 x64 intrinsic", "_mm256_unpackhi_epi8 x64 intrinsic", "_mm256_unpackhi_pd x64 intrinsic", "_mm256_unpackhi_ps x64 intrinsic", "_mm256_unpacklo_epi16 x64 intrinsic", "_mm256_unpacklo_epi32 x64 intrinsic", "_mm256_unpacklo_epi64 x64 intrinsic", "_mm256_unpacklo_epi8 x64 intrinsic", "_mm256_unpacklo_pd x64 intrinsic", "_mm256_unpacklo_ps x64 intrinsic", "_mm256_xor_pd x64 intrinsic", "_mm256_xor_ps x64 intrinsic", "_mm256_xor_si256 x64 intrinsic", "_mm256_zeroall x64 intrinsic", "_mm256_zeroupper x64 intrinsic", "_mulx_u32 x64 intrinsic", "_mulx_u64 x64 intrinsic", "__nvreg_restore_fence x64 intrinsic", "__nvreg_save_fence x64 intrinsic", "_pdep_u32 x64 intrinsic", "_pdep_u64 x64 intrinsic", "_pext_u32 x64 intrinsic", "_pext_u64 x64 intrinsic", "_rdrand16_step x64 intrinsic", "_rdrand32_step x64 intrinsic", "_rdrand64_step x64 intrinsic", "_rdseed16_step x64 intrinsic", "_rdseed32_step x64 intrinsic", "_rdseed64_step x64 intrinsic", "_readfsbase_u32 x64 intrinsic", "_readfsbase_u64 x64 intrinsic", "_readgsbase_u32 x64 intrinsic", "_readgsbase_u64 x64 intrinsic", "_rorx_u32 x64 intrinsic", "_rorx_u64 x64 intrinsic", "_rsm x64 intrinsic", "_sarx_i32 x64 intrinsic", "_sarx_i64 x64 intrinsic", "_sgdt x64 intrinsic", "_shlx_u32 x64 intrinsic", "_shlx_u64 x64 intrinsic", "_shrx_u32 x64 intrinsic", "_shrx_u64 x64 intrinsic", "__slwpcb x64 intrinsic", "_stac x64 intrinsic", "_store_be_u16 x64 intrinsic", "_storebe_i16 x64 intrinsic", "_store_be_u32 x64 intrinsic", "_storebe_i32 x64 intrinsic", "_store_be_u64 x64 intrinsic", "_storebe_i64 x64 intrinsic", "_Store_HLERelease x64 intrinsic", "_Store64_HLERelease x64 intrinsic", "_StorePointer_HLERelease x64 intrinsic", "_subborrow_u16 x64 intrinsic", "_subborrow_u32 x64 intrinsic", "_subborrow_u64 x64 intrinsic", "_subborrow_u8 x64 intrinsic", "_t1mskc_u32 x64 intrinsic", "_t1mskc_u64 x64 intrinsic", "_tzcnt_u32 x64 intrinsic", "_tzcnt_u64 x64 intrinsic", "_tzmsk_u32 x64 intrinsic", "_tzmsk_u64 x64 intrinsic", "_writefsbase_u32 x64 intrinsic", "_writefsbase_u64 x64 intrinsic", "_writegsbase_u32 x64 intrinsic", "_writegsbase_u64 x64 intrinsic", "_xabort x64 intrinsic", "_xbegin x64 intrinsic", "_xend x64 intrinsic", "_xgetbv x64 intrinsic", "_xrstor x64 intrinsic", "_xrstor64 x64 intrinsic", "_xsave x64 intrinsic", "_xsave64 x64 intrinsic", "_xsaveopt x64 intrinsic", "_xsaveopt64 x64 intrinsic", "_xsetbv x64 intrinsic", "_xtest x64 intrinsic"] +ms.date: 08/30/2022 +f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u64", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "immintrin/_addcarryx_u64", "ammintrin/_andn_u32", "ammintrin/_andn_u64", "ammintrin/_bextr_u32", "ammintrin/_bextr_u64", "ammintrin/_bextri_u32", "ammintrin/_bextri_u64", "ammintrin/_blcfill_u32", "ammintrin/_blcfill_u64", "ammintrin/_blci_u32", "ammintrin/_blci_u64", "ammintrin/_blcic_u32", "ammintrin/_blcic_u64", "ammintrin/_blcmsk_u32", "ammintrin/_blcmsk_u64", "ammintrin/_blcs_u32", "ammintrin/_blcs_u64", "ammintrin/_blsfill_u32", "ammintrin/_blsfill_u64", "ammintrin/_blsi_u32", "ammintrin/_blsi_u64", "ammintrin/_blsic_u32", "ammintrin/_blsic_u64", "ammintrin/_blsmsk_u32", "ammintrin/_blsmsk_u64", "ammintrin/_blsr_u32", "ammintrin/_blsr_u64", "immintrin/_bzhi_u32", "immintrin/_bzhi_u64", "immintrin/_castf32_u32", "immintrin/_castf64_u64", "immintrin/_castu32_f32", "immintrin/_castu64_f64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxrstor64", "immintrin/_fxsave", "immintrin/_fxsave64", "immintrin/_invpcid", "intrin/_lgdt", "ammintrin/__llwpcb", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "immintrin/_load_be_u64", "immintrin/_loadbe_i64", "ammintrin/__lwpins32", "ammintrin/__lwpins64", "ammintrin/__lwpval32", "ammintrin/__lwpval64", "ammintrin/_lzcnt_u32", "ammintrin/_lzcnt_u64", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u64", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_si64", "intrin/_mm_cvtsd_si64x", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi128_si64", "intrin/_mm_cvtsi128_si64x", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "intrin/_mm_cvtsi64_sd", "intrin/_mm_cvtsi64_si128", "intrin/_mm_cvtsi64_ss", "intrin/_mm_cvtsi64x_sd", "intrin/_mm_cvtsi64x_si128", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtss_si64", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_cvttsd_si64", "intrin/_mm_cvttsd_si64x", "intrin/_mm_cvttss_si64", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi64", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi64", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_popcnt_u64", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64x", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64x", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi64x", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi64x", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi64x", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "immintrin/_mulx_u64", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pdep_u64", "immintrin/_pext_u32", "immintrin/_pext_u64", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdrand64_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rdseed64_step", "immintrin/_readfsbase_u32", "immintrin/_readfsbase_u64", "immintrin/_readgsbase_u32", "immintrin/_readgsbase_u64", "immintrin/_rorx_u32", "immintrin/_rorx_u64", "intrin/_rsm", "immintrin/_sarx_i32", "immintrin/_sarx_i64", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shlx_u64", "immintrin/_shrx_u32", "immintrin/_shrx_u64", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_store_be_u64", "immintrin/_storebe_i64", "immintrin/_Store_HLERelease", "immintrin/_Store64_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u64", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_t1mskc_u64", "ammintrin/_tzcnt_u32", "ammintrin/_tzcnt_u64", "ammintrin/_tzmsk_u32", "ammintrin/_tzmsk_u64", "immintrin/_writefsbase_u32", "immintrin/_writefsbase_u64", "immintrin/_writegsbase_u32", "immintrin/_writegsbase_u64", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xrstor64", "immintrin/_xsave", "immintrin/_xsave64", "immintrin/_xsaveopt", "immintrin/_xsaveopt64", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_mm_add_ps", "XMMINTRIN/_mm_add_ss", "XMMINTRIN/_mm_and_ps", "XMMINTRIN/_mm_andnot_ps", "XMMINTRIN/_mm_cmpeq_ps", "XMMINTRIN/_mm_cmpeq_ss", "XMMINTRIN/_mm_cmpge_ps", "XMMINTRIN/_mm_cmpge_ss", "XMMINTRIN/_mm_cmpgt_ps", "XMMINTRIN/_mm_cmpgt_ss", "XMMINTRIN/_mm_cmple_ps", "XMMINTRIN/_mm_cmple_ss", "XMMINTRIN/_mm_cmplt_ps", "XMMINTRIN/_mm_cmplt_ss", "XMMINTRIN/_mm_cmpneq_ps", "XMMINTRIN/_mm_cmpneq_ss", "XMMINTRIN/_mm_cmpnge_ps", "XMMINTRIN/_mm_cmpnge_ss", "XMMINTRIN/_mm_cmpngt_ps", "XMMINTRIN/_mm_cmpngt_ss", "XMMINTRIN/_mm_cmpnle_ps", "XMMINTRIN/_mm_cmpnle_ss", "XMMINTRIN/_mm_cmpnlt_ps", "XMMINTRIN/_mm_cmpnlt_ss", "XMMINTRIN/_mm_cmpord_ps", "XMMINTRIN/_mm_cmpord_ss", "XMMINTRIN/_mm_cmpunord_ps", "XMMINTRIN/_mm_cmpunord_ss", "XMMINTRIN/_mm_comieq_ss", "XMMINTRIN/_mm_comige_ss", "XMMINTRIN/_mm_comigt_ss", "XMMINTRIN/_mm_comile_ss", "XMMINTRIN/_mm_comilt_ss", "XMMINTRIN/_mm_comineq_ss", "XMMINTRIN/_mm_cvt_si2ss", "XMMINTRIN/_mm_cvt_ss2si", "XMMINTRIN/_mm_cvtpi16_ps", "XMMINTRIN/_mm_cvtpi32x2_ps", "XMMINTRIN/_mm_cvtpi8_ps", "XMMINTRIN/_mm_cvtps_pi16", "XMMINTRIN/_mm_cvtps_pi8", "XMMINTRIN/_mm_cvtpu16_ps", "XMMINTRIN/_mm_cvtpu8_ps", "XMMINTRIN/_mm_cvtsi32_ss", "XMMINTRIN/_mm_cvtsi64_ss", "XMMINTRIN/_mm_cvtss_f32", "XMMINTRIN/_mm_cvtss_si32", "XMMINTRIN/_mm_cvtss_si64", "XMMINTRIN/_mm_cvtt_ss2si", "XMMINTRIN/_mm_cvttss_si32", "XMMINTRIN/_mm_cvttss_si64", "XMMINTRIN/_mm_div_ps", "XMMINTRIN/_mm_div_ss", "XMMINTRIN/_mm_getcsr", "XMMINTRIN/_mm_load_ps", "XMMINTRIN/_mm_load_ps1", "XMMINTRIN/_mm_load_ss", "XMMINTRIN/_mm_load1_ps", "XMMINTRIN/_mm_loadh_pi", "XMMINTRIN/_mm_loadl_pi", "XMMINTRIN/_mm_loadr_ps", "XMMINTRIN/_mm_loadu_ps", "XMMINTRIN/_mm_max_ps", "XMMINTRIN/_mm_max_ss", "XMMINTRIN/_mm_min_ps", "XMMINTRIN/_mm_min_ss", "XMMINTRIN/_mm_move_ss", "XMMINTRIN/_mm_movehl_ps", "XMMINTRIN/_mm_movelh_ps", "XMMINTRIN/_mm_movemask_ps", "XMMINTRIN/_mm_mul_ps", "XMMINTRIN/_mm_mul_ss", "XMMINTRIN/_mm_or_ps", "XMMINTRIN/_mm_prefetch", "XMMINTRIN/_mm_rcp_ps", "XMMINTRIN/_mm_rcp_ss", "XMMINTRIN/_mm_rsqrt_ps", "XMMINTRIN/_mm_rsqrt_ss", "XMMINTRIN/_mm_set_ps", "XMMINTRIN/_mm_set_ps1", "XMMINTRIN/_mm_set_ss", "XMMINTRIN/_mm_set1_ps", "XMMINTRIN/_mm_setcsr", "XMMINTRIN/_mm_setr_ps", "XMMINTRIN/_mm_setzero_ps", "XMMINTRIN/_mm_sfence", "XMMINTRIN/_mm_shuffle_ps", "XMMINTRIN/_mm_sqrt_ps", "XMMINTRIN/_mm_sqrt_ss", "XMMINTRIN/_mm_store_ps", "XMMINTRIN/_mm_store_ps1", "XMMINTRIN/_mm_store_ss", "XMMINTRIN/_mm_store1_ps", "XMMINTRIN/_mm_storeh_pi", "XMMINTRIN/_mm_storel_pi", "XMMINTRIN/_mm_storer_ps", "XMMINTRIN/_mm_storeu_ps", "XMMINTRIN/_mm_stream_ps", "XMMINTRIN/_mm_sub_ps", "XMMINTRIN/_mm_sub_ss", "XMMINTRIN/_mm_ucomieq_ss", "XMMINTRIN/_mm_ucomige_ss", "XMMINTRIN/_mm_ucomigt_ss", "XMMINTRIN/_mm_ucomile_ss", "XMMINTRIN/_mm_ucomilt_ss", "XMMINTRIN/_mm_ucomineq_ss", "XMMINTRIN/_mm_unpackhi_ps", "XMMINTRIN/_mm_unpacklo_ps", "XMMINTRIN/_mm_xor_ps"] +helpviewer_keywords: ["cl-exe compiler, intrinsics", "intrinsics, x64", "intrinsics, amd64", "_addcarry_u16 x64 intrinsic", "_addcarry_u32 x64 intrinsic", "_addcarry_u64 x64 intrinsic", "_addcarry_u8 x64 intrinsic", "_addcarryx_u32 x64 intrinsic", "_addcarryx_u64 x64 intrinsic", "_andn_u32 x64 intrinsic", "_andn_u64 x64 intrinsic", "_bextr_u32 x64 intrinsic", "_bextr_u64 x64 intrinsic", "_bextri_u32 x64 intrinsic", "_bextri_u64 x64 intrinsic", "_blcfill_u32 x64 intrinsic", "_blcfill_u64 x64 intrinsic", "_blci_u32 x64 intrinsic", "_blci_u64 x64 intrinsic", "_blcic_u32 x64 intrinsic", "_blcic_u64 x64 intrinsic", "_blcmsk_u32 x64 intrinsic", "_blcmsk_u64 x64 intrinsic", "_blcs_u32 x64 intrinsic", "_blcs_u64 x64 intrinsic", "_blsfill_u32 x64 intrinsic", "_blsfill_u64 x64 intrinsic", "_blsi_u32 x64 intrinsic", "_blsi_u64 x64 intrinsic", "_blsic_u32 x64 intrinsic", "_blsic_u64 x64 intrinsic", "_blsmsk_u32 x64 intrinsic", "_blsmsk_u64 x64 intrinsic", "_blsr_u32 x64 intrinsic", "_blsr_u64 x64 intrinsic", "_bzhi_u32 x64 intrinsic", "_bzhi_u64 x64 intrinsic", "_castf32_u32 x64 intrinsic", "_castf64_u64 x64 intrinsic", "_castu32_f32 x64 intrinsic", "_castu64_f64 x64 intrinsic", "_clac x64 intrinsic", "_fxrstor x64 intrinsic", "_fxrstor64 x64 intrinsic", "_fxsave x64 intrinsic", "_fxsave64 x64 intrinsic", "_invpcid x64 intrinsic", "_lgdt x64 intrinsic", "__llwpcb x64 intrinsic", "_load_be_u16 x64 intrinsic", "_loadbe_i16 x64 intrinsic", "_load_be_u32 x64 intrinsic", "_loadbe_i32 x64 intrinsic", "_load_be_u64 x64 intrinsic", "_loadbe_i64 x64 intrinsic", "__lwpins32 x64 intrinsic", "__lwpins64 x64 intrinsic", "__lwpval32 x64 intrinsic", "__lwpval64 x64 intrinsic", "_lzcnt_u32 x64 intrinsic", "_lzcnt_u64 x64 intrinsic", "_m_prefetch x64 intrinsic", "_m_prefetchw x64 intrinsic", "_mm_abs_epi16 x64 intrinsic", "_mm_abs_epi32 x64 intrinsic", "_mm_abs_epi8 x64 intrinsic", "_mm_add_epi16 x64 intrinsic", "_mm_add_epi32 x64 intrinsic", "_mm_add_epi64 x64 intrinsic", "_mm_add_epi8 x64 intrinsic", "_mm_add_pd x64 intrinsic", "_mm_add_ps x64 intrinsic", "_mm_add_sd x64 intrinsic", "_mm_add_ss x64 intrinsic", "_mm_adds_epi16 x64 intrinsic", "_mm_adds_epi8 x64 intrinsic", "_mm_adds_epu16 x64 intrinsic", "_mm_adds_epu8 x64 intrinsic", "_mm_addsub_pd x64 intrinsic", "_mm_addsub_ps x64 intrinsic", "_mm_aesdec_si128 x64 intrinsic", "_mm_aesdeclast_si128 x64 intrinsic", "_mm_aesenc_si128 x64 intrinsic", "_mm_aesenclast_si128 x64 intrinsic", "_mm_aesimc_si128 x64 intrinsic", "_mm_aeskeygenassist_si128 x64 intrinsic", "_mm_alignr_epi8 x64 intrinsic", "_mm_and_pd x64 intrinsic", "_mm_and_ps x64 intrinsic", "_mm_and_si128 x64 intrinsic", "_mm_andnot_pd x64 intrinsic", "_mm_andnot_ps x64 intrinsic", "_mm_andnot_si128 x64 intrinsic", "_mm_avg_epu16 x64 intrinsic", "_mm_avg_epu8 x64 intrinsic", "_mm_blend_epi16 x64 intrinsic", "_mm_blend_epi32 x64 intrinsic", "_mm_blend_pd x64 intrinsic", "_mm_blend_ps x64 intrinsic", "_mm_blendv_epi8 x64 intrinsic", "_mm_blendv_pd x64 intrinsic", "_mm_blendv_ps x64 intrinsic", "_mm_broadcast_ss x64 intrinsic", "_mm_broadcastb_epi8 x64 intrinsic", "_mm_broadcastd_epi32 x64 intrinsic", "_mm_broadcastq_epi64 x64 intrinsic", "_mm_broadcastsd_pd x64 intrinsic", "_mm_broadcastss_ps x64 intrinsic", "_mm_broadcastw_epi16 x64 intrinsic", "_mm_castpd_ps x64 intrinsic", "_mm_castpd_si128 x64 intrinsic", "_mm_castps_pd x64 intrinsic", "_mm_castps_si128 x64 intrinsic", "_mm_castsi128_pd x64 intrinsic", "_mm_castsi128_ps x64 intrinsic", "_mm_clflush x64 intrinsic", "_mm_clmulepi64_si128 x64 intrinsic", "_mm_cmov_si128 x64 intrinsic", "_mm_cmp_pd x64 intrinsic", "_mm_cmp_ps x64 intrinsic", "_mm_cmp_sd x64 intrinsic", "_mm_cmp_ss x64 intrinsic", "_mm_cmpeq_epi16 x64 intrinsic", "_mm_cmpeq_epi32 x64 intrinsic", "_mm_cmpeq_epi64 x64 intrinsic", "_mm_cmpeq_epi8 x64 intrinsic", "_mm_cmpeq_pd x64 intrinsic", "_mm_cmpeq_ps x64 intrinsic", "_mm_cmpeq_sd x64 intrinsic", "_mm_cmpeq_ss x64 intrinsic", "_mm_cmpestra x64 intrinsic", "_mm_cmpestrc x64 intrinsic", "_mm_cmpestri x64 intrinsic", "_mm_cmpestrm x64 intrinsic", "_mm_cmpestro x64 intrinsic", "_mm_cmpestrs x64 intrinsic", "_mm_cmpestrz x64 intrinsic", "_mm_cmpge_pd x64 intrinsic", "_mm_cmpge_ps x64 intrinsic", "_mm_cmpge_sd x64 intrinsic", "_mm_cmpge_ss x64 intrinsic", "_mm_cmpgt_epi16 x64 intrinsic", "_mm_cmpgt_epi32 x64 intrinsic", "_mm_cmpgt_epi64 x64 intrinsic", "_mm_cmpgt_epi8 x64 intrinsic", "_mm_cmpgt_pd x64 intrinsic", "_mm_cmpgt_ps x64 intrinsic", "_mm_cmpgt_sd x64 intrinsic", "_mm_cmpgt_ss x64 intrinsic", "_mm_cmpistra x64 intrinsic", "_mm_cmpistrc x64 intrinsic", "_mm_cmpistri x64 intrinsic", "_mm_cmpistrm x64 intrinsic", "_mm_cmpistro x64 intrinsic", "_mm_cmpistrs x64 intrinsic", "_mm_cmpistrz x64 intrinsic", "_mm_cmple_pd x64 intrinsic", "_mm_cmple_ps x64 intrinsic", "_mm_cmple_sd x64 intrinsic", "_mm_cmple_ss x64 intrinsic", "_mm_cmplt_epi16 x64 intrinsic", "_mm_cmplt_epi32 x64 intrinsic", "_mm_cmplt_epi8 x64 intrinsic", "_mm_cmplt_pd x64 intrinsic", "_mm_cmplt_ps x64 intrinsic", "_mm_cmplt_sd x64 intrinsic", "_mm_cmplt_ss x64 intrinsic", "_mm_cmpneq_pd x64 intrinsic", "_mm_cmpneq_ps x64 intrinsic", "_mm_cmpneq_sd x64 intrinsic", "_mm_cmpneq_ss x64 intrinsic", "_mm_cmpnge_pd x64 intrinsic", "_mm_cmpnge_ps x64 intrinsic", "_mm_cmpnge_sd x64 intrinsic", "_mm_cmpnge_ss x64 intrinsic", "_mm_cmpngt_pd x64 intrinsic", "_mm_cmpngt_ps x64 intrinsic", "_mm_cmpngt_sd x64 intrinsic", "_mm_cmpngt_ss x64 intrinsic", "_mm_cmpnle_pd x64 intrinsic", "_mm_cmpnle_ps x64 intrinsic", "_mm_cmpnle_sd x64 intrinsic", "_mm_cmpnle_ss x64 intrinsic", "_mm_cmpnlt_pd x64 intrinsic", "_mm_cmpnlt_ps x64 intrinsic", "_mm_cmpnlt_sd x64 intrinsic", "_mm_cmpnlt_ss x64 intrinsic", "_mm_cmpord_pd x64 intrinsic", "_mm_cmpord_ps x64 intrinsic", "_mm_cmpord_sd x64 intrinsic", "_mm_cmpord_ss x64 intrinsic", "_mm_cmpunord_pd x64 intrinsic", "_mm_cmpunord_ps x64 intrinsic", "_mm_cmpunord_sd x64 intrinsic", "_mm_cmpunord_ss x64 intrinsic", "_mm_com_epi16 x64 intrinsic", "_mm_com_epi32 x64 intrinsic", "_mm_com_epi64 x64 intrinsic", "_mm_com_epi8 x64 intrinsic", "_mm_com_epu16 x64 intrinsic", "_mm_com_epu32 x64 intrinsic", "_mm_com_epu64 x64 intrinsic", "_mm_com_epu8 x64 intrinsic", "_mm_comieq_sd x64 intrinsic", "_mm_comieq_ss x64 intrinsic", "_mm_comige_sd x64 intrinsic", "_mm_comige_ss x64 intrinsic", "_mm_comigt_sd x64 intrinsic", "_mm_comigt_ss x64 intrinsic", "_mm_comile_sd x64 intrinsic", "_mm_comile_ss x64 intrinsic", "_mm_comilt_sd x64 intrinsic", "_mm_comilt_ss x64 intrinsic", "_mm_comineq_sd x64 intrinsic", "_mm_comineq_ss x64 intrinsic", "_mm_crc32_u16 x64 intrinsic", "_mm_crc32_u32 x64 intrinsic", "_mm_crc32_u64 x64 intrinsic", "_mm_crc32_u8 x64 intrinsic", "_mm_cvt_si2ss x64 intrinsic", "_mm_cvt_ss2si x64 intrinsic", "_mm_cvtepi16_epi32 x64 intrinsic", "_mm_cvtepi16_epi64 x64 intrinsic", "_mm_cvtepi32_epi64 x64 intrinsic", "_mm_cvtepi32_pd x64 intrinsic", "_mm_cvtepi32_ps x64 intrinsic", "_mm_cvtepi8_epi16 x64 intrinsic", "_mm_cvtepi8_epi32 x64 intrinsic", "_mm_cvtepi8_epi64 x64 intrinsic", "_mm_cvtepu16_epi32 x64 intrinsic", "_mm_cvtepu16_epi64 x64 intrinsic", "_mm_cvtepu32_epi64 x64 intrinsic", "_mm_cvtepu8_epi16 x64 intrinsic", "_mm_cvtepu8_epi32 x64 intrinsic", "_mm_cvtepu8_epi64 x64 intrinsic", "_mm_cvtpd_epi32 x64 intrinsic", "_mm_cvtpd_ps x64 intrinsic", "_mm_cvtph_ps x64 intrinsic", "_mm_cvtps_epi32 x64 intrinsic", "_mm_cvtps_pd x64 intrinsic", "_mm_cvtps_ph x64 intrinsic", "_mm_cvtsd_f64 x64 intrinsic", "_mm_cvtsd_si32 x64 intrinsic", "_mm_cvtsd_si64 x64 intrinsic", "_mm_cvtsd_si64x x64 intrinsic", "_mm_cvtsd_ss x64 intrinsic", "_mm_cvtsi128_si32 x64 intrinsic", "_mm_cvtsi128_si64 x64 intrinsic", "_mm_cvtsi128_si64x x64 intrinsic", "_mm_cvtsi32_sd x64 intrinsic", "_mm_cvtsi32_si128 x64 intrinsic", "_mm_cvtsi64_sd x64 intrinsic", "_mm_cvtsi64_si128 x64 intrinsic", "_mm_cvtsi64_ss x64 intrinsic", "_mm_cvtsi64x_sd x64 intrinsic", "_mm_cvtsi64x_si128 x64 intrinsic", "_mm_cvtss_f32 x64 intrinsic", "_mm_cvtss_sd x64 intrinsic", "_mm_cvtss_si64 x64 intrinsic", "_mm_cvtt_ss2si x64 intrinsic", "_mm_cvttpd_epi32 x64 intrinsic", "_mm_cvttps_epi32 x64 intrinsic", "_mm_cvttsd_si32 x64 intrinsic", "_mm_cvttsd_si64 x64 intrinsic", "_mm_cvttsd_si64x x64 intrinsic", "_mm_cvttss_si64 x64 intrinsic", "_mm_div_pd x64 intrinsic", "_mm_div_ps x64 intrinsic", "_mm_div_sd x64 intrinsic", "_mm_div_ss x64 intrinsic", "_mm_dp_pd x64 intrinsic", "_mm_dp_ps x64 intrinsic", "_mm_extract_epi16 x64 intrinsic", "_mm_extract_epi32 x64 intrinsic", "_mm_extract_epi64 x64 intrinsic", "_mm_extract_epi8 x64 intrinsic", "_mm_extract_ps x64 intrinsic", "_mm_fmadd_pd x64 intrinsic", "_mm_fmadd_ps x64 intrinsic", "_mm_fmadd_sd x64 intrinsic", "_mm_fmadd_ss x64 intrinsic", "_mm_fmaddsub_pd x64 intrinsic", "_mm_fmaddsub_ps x64 intrinsic", "_mm_fmsub_pd x64 intrinsic", "_mm_fmsub_ps x64 intrinsic", "_mm_fmsub_sd x64 intrinsic", "_mm_fmsub_ss x64 intrinsic", "_mm_fmsubadd_pd x64 intrinsic", "_mm_fmsubadd_ps x64 intrinsic", "_mm_fnmadd_pd x64 intrinsic", "_mm_fnmadd_ps x64 intrinsic", "_mm_fnmadd_sd x64 intrinsic", "_mm_fnmadd_ss x64 intrinsic", "_mm_fnmsub_pd x64 intrinsic", "_mm_fnmsub_ps x64 intrinsic", "_mm_fnmsub_sd x64 intrinsic", "_mm_fnmsub_ss x64 intrinsic", "_mm_frcz_pd x64 intrinsic", "_mm_frcz_ps x64 intrinsic", "_mm_frcz_sd x64 intrinsic", "_mm_frcz_ss x64 intrinsic", "_mm_getcsr x64 intrinsic", "_mm_hadd_epi16 x64 intrinsic", "_mm_hadd_epi32 x64 intrinsic", "_mm_hadd_pd x64 intrinsic", "_mm_hadd_ps x64 intrinsic", "_mm_haddd_epi16 x64 intrinsic", "_mm_haddd_epi8 x64 intrinsic", "_mm_haddd_epu16 x64 intrinsic", "_mm_haddd_epu8 x64 intrinsic", "_mm_haddq_epi16 x64 intrinsic", "_mm_haddq_epi32 x64 intrinsic", "_mm_haddq_epi8 x64 intrinsic", "_mm_haddq_epu16 x64 intrinsic", "_mm_haddq_epu32 x64 intrinsic", "_mm_haddq_epu8 x64 intrinsic", "_mm_hadds_epi16 x64 intrinsic", "_mm_haddw_epi8 x64 intrinsic", "_mm_haddw_epu8 x64 intrinsic", "_mm_hsub_epi16 x64 intrinsic", "_mm_hsub_epi32 x64 intrinsic", "_mm_hsub_pd x64 intrinsic", "_mm_hsub_ps x64 intrinsic", "_mm_hsubd_epi16 x64 intrinsic", "_mm_hsubq_epi32 x64 intrinsic", "_mm_hsubs_epi16 x64 intrinsic", "_mm_hsubw_epi8 x64 intrinsic", "_mm_i32gather_epi32 x64 intrinsic", "_mm_i32gather_epi64 x64 intrinsic", "_mm_i32gather_pd x64 intrinsic", "_mm_i32gather_ps x64 intrinsic", "_mm_i64gather_epi32 x64 intrinsic", "_mm_i64gather_epi64 x64 intrinsic", "_mm_i64gather_pd x64 intrinsic", "_mm_i64gather_ps x64 intrinsic", "_mm_insert_epi16 x64 intrinsic", "_mm_insert_epi32 x64 intrinsic", "_mm_insert_epi64 x64 intrinsic", "_mm_insert_epi8 x64 intrinsic", "_mm_insert_ps x64 intrinsic", "_mm_lddqu_si128 x64 intrinsic", "_mm_lfence x64 intrinsic", "_mm_load_pd x64 intrinsic", "_mm_load_ps x64 intrinsic", "_mm_load_ps1 x64 intrinsic", "_mm_load_sd x64 intrinsic", "_mm_load_si128 x64 intrinsic", "_mm_load_ss x64 intrinsic", "_mm_load1_pd x64 intrinsic", "_mm_loaddup_pd x64 intrinsic", "_mm_loadh_pd x64 intrinsic", "_mm_loadh_pi x64 intrinsic", "_mm_loadl_epi64 x64 intrinsic", "_mm_loadl_pd x64 intrinsic", "_mm_loadl_pi x64 intrinsic", "_mm_loadr_pd x64 intrinsic", "_mm_loadr_ps x64 intrinsic", "_mm_loadu_pd x64 intrinsic", "_mm_loadu_ps x64 intrinsic", "_mm_loadu_si128 x64 intrinsic", "_mm_macc_epi16 x64 intrinsic", "_mm_macc_epi32 x64 intrinsic", "_mm_macc_pd x64 intrinsic", "_mm_macc_ps x64 intrinsic", "_mm_macc_sd x64 intrinsic", "_mm_macc_ss x64 intrinsic", "_mm_maccd_epi16 x64 intrinsic", "_mm_macchi_epi32 x64 intrinsic", "_mm_macclo_epi32 x64 intrinsic", "_mm_maccs_epi16 x64 intrinsic", "_mm_maccs_epi32 x64 intrinsic", "_mm_maccsd_epi16 x64 intrinsic", "_mm_maccshi_epi32 x64 intrinsic", "_mm_maccslo_epi32 x64 intrinsic", "_mm_madd_epi16 x64 intrinsic", "_mm_maddd_epi16 x64 intrinsic", "_mm_maddsd_epi16 x64 intrinsic", "_mm_maddsub_pd x64 intrinsic", "_mm_maddsub_ps x64 intrinsic", "_mm_maddubs_epi16 x64 intrinsic", "_mm_mask_i32gather_epi32 x64 intrinsic", "_mm_mask_i32gather_epi64 x64 intrinsic", "_mm_mask_i32gather_pd x64 intrinsic", "_mm_mask_i32gather_ps x64 intrinsic", "_mm_mask_i64gather_epi32 x64 intrinsic", "_mm_mask_i64gather_epi64 x64 intrinsic", "_mm_mask_i64gather_pd x64 intrinsic", "_mm_mask_i64gather_ps x64 intrinsic", "_mm_maskload_epi32 x64 intrinsic", "_mm_maskload_epi64 x64 intrinsic", "_mm_maskload_pd x64 intrinsic", "_mm_maskload_ps x64 intrinsic", "_mm_maskmoveu_si128 x64 intrinsic", "_mm_maskstore_epi32 x64 intrinsic", "_mm_maskstore_epi64 x64 intrinsic", "_mm_maskstore_pd x64 intrinsic", "_mm_maskstore_ps x64 intrinsic", "_mm_max_epi16 x64 intrinsic", "_mm_max_epi32 x64 intrinsic", "_mm_max_epi8 x64 intrinsic", "_mm_max_epu16 x64 intrinsic", "_mm_max_epu32 x64 intrinsic", "_mm_max_epu8 x64 intrinsic", "_mm_max_pd x64 intrinsic", "_mm_max_ps x64 intrinsic", "_mm_max_sd x64 intrinsic", "_mm_max_ss x64 intrinsic", "_mm_mfence x64 intrinsic", "_mm_min_epi16 x64 intrinsic", "_mm_min_epi32 x64 intrinsic", "_mm_min_epi8 x64 intrinsic", "_mm_min_epu16 x64 intrinsic", "_mm_min_epu32 x64 intrinsic", "_mm_min_epu8 x64 intrinsic", "_mm_min_pd x64 intrinsic", "_mm_min_ps x64 intrinsic", "_mm_min_sd x64 intrinsic", "_mm_min_ss x64 intrinsic", "_mm_minpos_epu16 x64 intrinsic", "_mm_monitor x64 intrinsic", "_mm_move_epi64 x64 intrinsic", "_mm_move_sd x64 intrinsic", "_mm_move_ss x64 intrinsic", "_mm_movedup_pd x64 intrinsic", "_mm_movehdup_ps x64 intrinsic", "_mm_movehl_ps x64 intrinsic", "_mm_moveldup_ps x64 intrinsic", "_mm_movelh_ps x64 intrinsic", "_mm_movemask_epi8 x64 intrinsic", "_mm_movemask_pd x64 intrinsic", "_mm_movemask_ps x64 intrinsic", "_mm_mpsadbw_epu8 x64 intrinsic", "_mm_msub_pd x64 intrinsic", "_mm_msub_ps x64 intrinsic", "_mm_msub_sd x64 intrinsic", "_mm_msub_ss x64 intrinsic", "_mm_msubadd_pd x64 intrinsic", "_mm_msubadd_ps x64 intrinsic", "_mm_mul_epi32 x64 intrinsic", "_mm_mul_epu32 x64 intrinsic", "_mm_mul_pd x64 intrinsic", "_mm_mul_ps x64 intrinsic", "_mm_mul_sd x64 intrinsic", "_mm_mul_ss x64 intrinsic", "_mm_mulhi_epi16 x64 intrinsic", "_mm_mulhi_epu16 x64 intrinsic", "_mm_mulhrs_epi16 x64 intrinsic", "_mm_mullo_epi16 x64 intrinsic", "_mm_mullo_epi32 x64 intrinsic", "_mm_mwait x64 intrinsic", "_mm_nmacc_pd x64 intrinsic", "_mm_nmacc_ps x64 intrinsic", "_mm_nmacc_sd x64 intrinsic", "_mm_nmacc_ss x64 intrinsic", "_mm_nmsub_pd x64 intrinsic", "_mm_nmsub_ps x64 intrinsic", "_mm_nmsub_sd x64 intrinsic", "_mm_nmsub_ss x64 intrinsic", "_mm_or_pd x64 intrinsic", "_mm_or_ps x64 intrinsic", "_mm_or_si128 x64 intrinsic", "_mm_packs_epi16 x64 intrinsic", "_mm_packs_epi32 x64 intrinsic", "_mm_packus_epi16 x64 intrinsic", "_mm_packus_epi32 x64 intrinsic", "_mm_pause x64 intrinsic", "_mm_perm_epi8 x64 intrinsic", "_mm_permute_pd x64 intrinsic", "_mm_permute_ps x64 intrinsic", "_mm_permute2_pd x64 intrinsic", "_mm_permute2_ps x64 intrinsic", "_mm_permutevar_pd x64 intrinsic", "_mm_permutevar_ps x64 intrinsic", "_mm_popcnt_u32 x64 intrinsic", "_mm_popcnt_u64 x64 intrinsic", "_mm_prefetch x64 intrinsic", "_mm_rcp_ps x64 intrinsic", "_mm_rcp_ss x64 intrinsic", "_mm_rot_epi16 x64 intrinsic", "_mm_rot_epi32 x64 intrinsic", "_mm_rot_epi64 x64 intrinsic", "_mm_rot_epi8 x64 intrinsic", "_mm_roti_epi16 x64 intrinsic", "_mm_roti_epi32 x64 intrinsic", "_mm_roti_epi64 x64 intrinsic", "_mm_roti_epi8 x64 intrinsic", "_mm_round_pd x64 intrinsic", "_mm_round_ps x64 intrinsic", "_mm_round_sd x64 intrinsic", "_mm_round_ss x64 intrinsic", "_mm_rsqrt_ps x64 intrinsic", "_mm_rsqrt_ss x64 intrinsic", "_mm_sad_epu8 x64 intrinsic", "_mm_set_epi16 x64 intrinsic", "_mm_set_epi32 x64 intrinsic", "_mm_set_epi64x x64 intrinsic", "_mm_set_epi8 x64 intrinsic", "_mm_set_pd x64 intrinsic", "_mm_set_ps x64 intrinsic", "_mm_set_ps1 x64 intrinsic", "_mm_set_sd x64 intrinsic", "_mm_set_ss x64 intrinsic", "_mm_set1_epi16 x64 intrinsic", "_mm_set1_epi32 x64 intrinsic", "_mm_set1_epi64x x64 intrinsic", "_mm_set1_epi8 x64 intrinsic", "_mm_set1_pd x64 intrinsic", "_mm_setcsr x64 intrinsic", "_mm_setl_epi64 x64 intrinsic", "_mm_setr_epi16 x64 intrinsic", "_mm_setr_epi32 x64 intrinsic", "_mm_setr_epi8 x64 intrinsic", "_mm_setr_pd x64 intrinsic", "_mm_setr_ps x64 intrinsic", "_mm_setzero_pd x64 intrinsic", "_mm_setzero_ps x64 intrinsic", "_mm_setzero_si128 x64 intrinsic", "_mm_sfence x64 intrinsic", "_mm_sha_epi16 x64 intrinsic", "_mm_sha_epi32 x64 intrinsic", "_mm_sha_epi64 x64 intrinsic", "_mm_sha_epi8 x64 intrinsic", "_mm_shl_epi16 x64 intrinsic", "_mm_shl_epi32 x64 intrinsic", "_mm_shl_epi64 x64 intrinsic", "_mm_shl_epi8 x64 intrinsic", "_mm_shuffle_epi32 x64 intrinsic", "_mm_shuffle_epi8 x64 intrinsic", "_mm_shuffle_pd x64 intrinsic", "_mm_shuffle_ps x64 intrinsic", "_mm_shufflehi_epi16 x64 intrinsic", "_mm_shufflelo_epi16 x64 intrinsic", "_mm_sign_epi16 x64 intrinsic", "_mm_sign_epi32 x64 intrinsic", "_mm_sign_epi8 x64 intrinsic", "_mm_sll_epi16 x64 intrinsic", "_mm_sll_epi32 x64 intrinsic", "_mm_sll_epi64 x64 intrinsic", "_mm_slli_epi16 x64 intrinsic", "_mm_slli_epi32 x64 intrinsic", "_mm_slli_epi64 x64 intrinsic", "_mm_slli_si128 x64 intrinsic", "_mm_sllv_epi32 x64 intrinsic", "_mm_sllv_epi64 x64 intrinsic", "_mm_sqrt_pd x64 intrinsic", "_mm_sqrt_ps x64 intrinsic", "_mm_sqrt_sd x64 intrinsic", "_mm_sqrt_ss x64 intrinsic", "_mm_sra_epi16 x64 intrinsic", "_mm_sra_epi32 x64 intrinsic", "_mm_srai_epi16 x64 intrinsic", "_mm_srai_epi32 x64 intrinsic", "_mm_srav_epi32 x64 intrinsic", "_mm_srl_epi16 x64 intrinsic", "_mm_srl_epi32 x64 intrinsic", "_mm_srl_epi64 x64 intrinsic", "_mm_srli_epi16 x64 intrinsic", "_mm_srli_epi32 x64 intrinsic", "_mm_srli_epi64 x64 intrinsic", "_mm_srli_si128 x64 intrinsic", "_mm_srlv_epi32 x64 intrinsic", "_mm_srlv_epi64 x64 intrinsic", "_mm_store_pd x64 intrinsic", "_mm_store_ps x64 intrinsic", "_mm_store_ps1 x64 intrinsic", "_mm_store_sd x64 intrinsic", "_mm_store_si128 x64 intrinsic", "_mm_store_ss x64 intrinsic", "_mm_store1_pd x64 intrinsic", "_mm_storeh_pd x64 intrinsic", "_mm_storeh_pi x64 intrinsic", "_mm_storel_epi64 x64 intrinsic", "_mm_storel_pd x64 intrinsic", "_mm_storel_pi x64 intrinsic", "_mm_storer_pd x64 intrinsic", "_mm_storer_ps x64 intrinsic", "_mm_storeu_pd x64 intrinsic", "_mm_storeu_ps x64 intrinsic", "_mm_storeu_si128 x64 intrinsic", "_mm_stream_load_si128 x64 intrinsic", "_mm_stream_pd x64 intrinsic", "_mm_stream_ps x64 intrinsic", "_mm_stream_si128 x64 intrinsic", "_mm_stream_si32 x64 intrinsic", "_mm_sub_epi16 x64 intrinsic", "_mm_sub_epi32 x64 intrinsic", "_mm_sub_epi64 x64 intrinsic", "_mm_sub_epi8 x64 intrinsic", "_mm_sub_pd x64 intrinsic", "_mm_sub_ps x64 intrinsic", "_mm_sub_sd x64 intrinsic", "_mm_sub_ss x64 intrinsic", "_mm_subs_epi16 x64 intrinsic", "_mm_subs_epi8 x64 intrinsic", "_mm_subs_epu16 x64 intrinsic", "_mm_subs_epu8 x64 intrinsic", "_mm_testc_pd x64 intrinsic", "_mm_testc_ps x64 intrinsic", "_mm_testc_si128 x64 intrinsic", "_mm_testnzc_pd x64 intrinsic", "_mm_testnzc_ps x64 intrinsic", "_mm_testnzc_si128 x64 intrinsic", "_mm_testz_pd x64 intrinsic", "_mm_testz_ps x64 intrinsic", "_mm_testz_si128 x64 intrinsic", "_mm_ucomieq_sd x64 intrinsic", "_mm_ucomieq_ss x64 intrinsic", "_mm_ucomige_sd x64 intrinsic", "_mm_ucomige_ss x64 intrinsic", "_mm_ucomigt_sd x64 intrinsic", "_mm_ucomigt_ss x64 intrinsic", "_mm_ucomile_sd x64 intrinsic", "_mm_ucomile_ss x64 intrinsic", "_mm_ucomilt_sd x64 intrinsic", "_mm_ucomilt_ss x64 intrinsic", "_mm_ucomineq_sd x64 intrinsic", "_mm_ucomineq_ss x64 intrinsic", "_mm_unpackhi_epi16 x64 intrinsic", "_mm_unpackhi_epi32 x64 intrinsic", "_mm_unpackhi_epi64 x64 intrinsic", "_mm_unpackhi_epi8 x64 intrinsic", "_mm_unpackhi_pd x64 intrinsic", "_mm_unpackhi_ps x64 intrinsic", "_mm_unpacklo_epi16 x64 intrinsic", "_mm_unpacklo_epi32 x64 intrinsic", "_mm_unpacklo_epi64 x64 intrinsic", "_mm_unpacklo_epi8 x64 intrinsic", "_mm_unpacklo_pd x64 intrinsic", "_mm_unpacklo_ps x64 intrinsic", "_mm_xor_pd x64 intrinsic", "_mm_xor_ps x64 intrinsic", "_mm_xor_si128 x64 intrinsic", "_mm256_abs_epi16 x64 intrinsic", "_mm256_abs_epi32 x64 intrinsic", "_mm256_abs_epi8 x64 intrinsic", "_mm256_add_epi16 x64 intrinsic", "_mm256_add_epi32 x64 intrinsic", "_mm256_add_epi64 x64 intrinsic", "_mm256_add_epi8 x64 intrinsic", "_mm256_add_pd x64 intrinsic", "_mm256_add_ps x64 intrinsic", "_mm256_adds_epi16 x64 intrinsic", "_mm256_adds_epi8 x64 intrinsic", "_mm256_adds_epu16 x64 intrinsic", "_mm256_adds_epu8 x64 intrinsic", "_mm256_addsub_pd x64 intrinsic", "_mm256_addsub_ps x64 intrinsic", "_mm256_alignr_epi8 x64 intrinsic", "_mm256_and_pd x64 intrinsic", "_mm256_and_ps x64 intrinsic", "_mm256_and_si256 x64 intrinsic", "_mm256_andnot_pd x64 intrinsic", "_mm256_andnot_ps x64 intrinsic", "_mm256_andnot_si256 x64 intrinsic", "_mm256_avg_epu16 x64 intrinsic", "_mm256_avg_epu8 x64 intrinsic", "_mm256_blend_epi16 x64 intrinsic", "_mm256_blend_epi32 x64 intrinsic", "_mm256_blend_pd x64 intrinsic", "_mm256_blend_ps x64 intrinsic", "_mm256_blendv_epi8 x64 intrinsic", "_mm256_blendv_pd x64 intrinsic", "_mm256_blendv_ps x64 intrinsic", "_mm256_broadcast_pd x64 intrinsic", "_mm256_broadcast_ps x64 intrinsic", "_mm256_broadcast_sd x64 intrinsic", "_mm256_broadcast_ss x64 intrinsic", "_mm256_broadcastb_epi8 x64 intrinsic", "_mm256_broadcastd_epi32 x64 intrinsic", "_mm256_broadcastq_epi64 x64 intrinsic", "_mm256_broadcastsd_pd x64 intrinsic", "_mm256_broadcastsi128_si256 x64 intrinsic", "_mm256_broadcastss_ps x64 intrinsic", "_mm256_broadcastw_epi16 x64 intrinsic", "_mm256_castpd_ps x64 intrinsic", "_mm256_castpd_si256 x64 intrinsic", "_mm256_castpd128_pd256 x64 intrinsic", "_mm256_castpd256_pd128 x64 intrinsic", "_mm256_castps_pd x64 intrinsic", "_mm256_castps_si256 x64 intrinsic", "_mm256_castps128_ps256 x64 intrinsic", "_mm256_castps256_ps128 x64 intrinsic", "_mm256_castsi128_si256 x64 intrinsic", "_mm256_castsi256_pd x64 intrinsic", "_mm256_castsi256_ps x64 intrinsic", "_mm256_castsi256_si128 x64 intrinsic", "_mm256_cmov_si256 x64 intrinsic", "_mm256_cmp_pd x64 intrinsic", "_mm256_cmp_ps x64 intrinsic", "_mm256_cmpeq_epi16 x64 intrinsic", "_mm256_cmpeq_epi32 x64 intrinsic", "_mm256_cmpeq_epi64 x64 intrinsic", "_mm256_cmpeq_epi8 x64 intrinsic", "_mm256_cmpgt_epi16 x64 intrinsic", "_mm256_cmpgt_epi32 x64 intrinsic", "_mm256_cmpgt_epi64 x64 intrinsic", "_mm256_cmpgt_epi8 x64 intrinsic", "_mm256_cvtepi16_epi32 x64 intrinsic", "_mm256_cvtepi16_epi64 x64 intrinsic", "_mm256_cvtepi32_epi64 x64 intrinsic", "_mm256_cvtepi32_pd x64 intrinsic", "_mm256_cvtepi32_ps x64 intrinsic", "_mm256_cvtepi8_epi16 x64 intrinsic", "_mm256_cvtepi8_epi32 x64 intrinsic", "_mm256_cvtepi8_epi64 x64 intrinsic", "_mm256_cvtepu16_epi32 x64 intrinsic", "_mm256_cvtepu16_epi64 x64 intrinsic", "_mm256_cvtepu32_epi64 x64 intrinsic", "_mm256_cvtepu8_epi16 x64 intrinsic", "_mm256_cvtepu8_epi32 x64 intrinsic", "_mm256_cvtepu8_epi64 x64 intrinsic", "_mm256_cvtpd_epi32 x64 intrinsic", "_mm256_cvtpd_ps x64 intrinsic", "_mm256_cvtph_ps x64 intrinsic", "_mm256_cvtps_epi32 x64 intrinsic", "_mm256_cvtps_pd x64 intrinsic", "_mm256_cvtps_ph x64 intrinsic", "_mm256_cvttpd_epi32 x64 intrinsic", "_mm256_cvttps_epi32 x64 intrinsic", "_mm256_div_pd x64 intrinsic", "_mm256_div_ps x64 intrinsic", "_mm256_dp_ps x64 intrinsic", "_mm256_extractf128_pd x64 intrinsic", "_mm256_extractf128_ps x64 intrinsic", "_mm256_extractf128_si256 x64 intrinsic", "_mm256_extracti128_si256 x64 intrinsic", "_mm256_fmadd_pd x64 intrinsic", "_mm256_fmadd_ps x64 intrinsic", "_mm256_fmaddsub_pd x64 intrinsic", "_mm256_fmaddsub_ps x64 intrinsic", "_mm256_fmsub_pd x64 intrinsic", "_mm256_fmsub_ps x64 intrinsic", "_mm256_fmsubadd_pd x64 intrinsic", "_mm256_fmsubadd_ps x64 intrinsic", "_mm256_fnmadd_pd x64 intrinsic", "_mm256_fnmadd_ps x64 intrinsic", "_mm256_fnmsub_pd x64 intrinsic", "_mm256_fnmsub_ps x64 intrinsic", "_mm256_frcz_pd x64 intrinsic", "_mm256_frcz_ps x64 intrinsic", "_mm256_hadd_epi16 x64 intrinsic", "_mm256_hadd_epi32 x64 intrinsic", "_mm256_hadd_pd x64 intrinsic", "_mm256_hadd_ps x64 intrinsic", "_mm256_hadds_epi16 x64 intrinsic", "_mm256_hsub_epi16 x64 intrinsic", "_mm256_hsub_epi32 x64 intrinsic", "_mm256_hsub_pd x64 intrinsic", "_mm256_hsub_ps x64 intrinsic", "_mm256_hsubs_epi16 x64 intrinsic", "_mm256_i32gather_epi32 x64 intrinsic", "_mm256_i32gather_epi64 x64 intrinsic", "_mm256_i32gather_pd x64 intrinsic", "_mm256_i32gather_ps x64 intrinsic", "_mm256_i64gather_epi32 x64 intrinsic", "_mm256_i64gather_epi64 x64 intrinsic", "_mm256_i64gather_pd x64 intrinsic", "_mm256_i64gather_ps x64 intrinsic", "_mm256_insertf128_pd x64 intrinsic", "_mm256_insertf128_ps x64 intrinsic", "_mm256_insertf128_si256 x64 intrinsic", "_mm256_inserti128_si256 x64 intrinsic", "_mm256_lddqu_si256 x64 intrinsic", "_mm256_load_pd x64 intrinsic", "_mm256_load_ps x64 intrinsic", "_mm256_load_si256 x64 intrinsic", "_mm256_loadu_pd x64 intrinsic", "_mm256_loadu_ps x64 intrinsic", "_mm256_loadu_si256 x64 intrinsic", "_mm256_macc_pd x64 intrinsic", "_mm256_macc_ps x64 intrinsic", "_mm256_madd_epi16 x64 intrinsic", "_mm256_maddsub_pd x64 intrinsic", "_mm256_maddsub_ps x64 intrinsic", "_mm256_maddubs_epi16 x64 intrinsic", "_mm256_mask_i32gather_epi32 x64 intrinsic", "_mm256_mask_i32gather_epi64 x64 intrinsic", "_mm256_mask_i32gather_pd x64 intrinsic", "_mm256_mask_i32gather_ps x64 intrinsic", "_mm256_mask_i64gather_epi32 x64 intrinsic", "_mm256_mask_i64gather_epi64 x64 intrinsic", "_mm256_mask_i64gather_pd x64 intrinsic", "_mm256_mask_i64gather_ps x64 intrinsic", "_mm256_maskload_epi32 x64 intrinsic", "_mm256_maskload_epi64 x64 intrinsic", "_mm256_maskload_pd x64 intrinsic", "_mm256_maskload_ps x64 intrinsic", "_mm256_maskstore_epi32 x64 intrinsic", "_mm256_maskstore_epi64 x64 intrinsic", "_mm256_maskstore_pd x64 intrinsic", "_mm256_maskstore_ps x64 intrinsic", "_mm256_max_epi16 x64 intrinsic", "_mm256_max_epi32 x64 intrinsic", "_mm256_max_epi8 x64 intrinsic", "_mm256_max_epu16 x64 intrinsic", "_mm256_max_epu32 x64 intrinsic", "_mm256_max_epu8 x64 intrinsic", "_mm256_max_pd x64 intrinsic", "_mm256_max_ps x64 intrinsic", "_mm256_min_epi16 x64 intrinsic", "_mm256_min_epi32 x64 intrinsic", "_mm256_min_epi8 x64 intrinsic", "_mm256_min_epu16 x64 intrinsic", "_mm256_min_epu32 x64 intrinsic", "_mm256_min_epu8 x64 intrinsic", "_mm256_min_pd x64 intrinsic", "_mm256_min_ps x64 intrinsic", "_mm256_movedup_pd x64 intrinsic", "_mm256_movehdup_ps x64 intrinsic", "_mm256_moveldup_ps x64 intrinsic", "_mm256_movemask_epi8 x64 intrinsic", "_mm256_movemask_pd x64 intrinsic", "_mm256_movemask_ps x64 intrinsic", "_mm256_mpsadbw_epu8 x64 intrinsic", "_mm256_msub_pd x64 intrinsic", "_mm256_msub_ps x64 intrinsic", "_mm256_msubadd_pd x64 intrinsic", "_mm256_msubadd_ps x64 intrinsic", "_mm256_mul_epi32 x64 intrinsic", "_mm256_mul_epu32 x64 intrinsic", "_mm256_mul_pd x64 intrinsic", "_mm256_mul_ps x64 intrinsic", "_mm256_mulhi_epi16 x64 intrinsic", "_mm256_mulhi_epu16 x64 intrinsic", "_mm256_mulhrs_epi16 x64 intrinsic", "_mm256_mullo_epi16 x64 intrinsic", "_mm256_mullo_epi32 x64 intrinsic", "_mm256_nmacc_pd x64 intrinsic", "_mm256_nmacc_ps x64 intrinsic", "_mm256_nmsub_pd x64 intrinsic", "_mm256_nmsub_ps x64 intrinsic", "_mm256_or_pd x64 intrinsic", "_mm256_or_ps x64 intrinsic", "_mm256_or_si256 x64 intrinsic", "_mm256_packs_epi16 x64 intrinsic", "_mm256_packs_epi32 x64 intrinsic", "_mm256_packus_epi16 x64 intrinsic", "_mm256_packus_epi32 x64 intrinsic", "_mm256_permute_pd x64 intrinsic", "_mm256_permute_ps x64 intrinsic", "_mm256_permute2_pd x64 intrinsic", "_mm256_permute2_ps x64 intrinsic", "_mm256_permute2f128_pd x64 intrinsic", "_mm256_permute2f128_ps x64 intrinsic", "_mm256_permute2f128_si256 x64 intrinsic", "_mm256_permute2x128_si256 x64 intrinsic", "_mm256_permute4x64_epi64 x64 intrinsic", "_mm256_permute4x64_pd x64 intrinsic", "_mm256_permutevar_pd x64 intrinsic", "_mm256_permutevar_ps x64 intrinsic", "_mm256_permutevar8x32_epi32 x64 intrinsic", "_mm256_permutevar8x32_ps x64 intrinsic", "_mm256_rcp_ps x64 intrinsic", "_mm256_round_pd x64 intrinsic", "_mm256_round_ps x64 intrinsic", "_mm256_rsqrt_ps x64 intrinsic", "_mm256_sad_epu8 x64 intrinsic", "_mm256_set_epi16 x64 intrinsic", "_mm256_set_epi32 x64 intrinsic", "_mm256_set_epi64x x64 intrinsic", "_mm256_set_epi8 x64 intrinsic", "_mm256_set_pd x64 intrinsic", "_mm256_set_ps x64 intrinsic", "_mm256_set1_epi16 x64 intrinsic", "_mm256_set1_epi32 x64 intrinsic", "_mm256_set1_epi64x x64 intrinsic", "_mm256_set1_epi8 x64 intrinsic", "_mm256_set1_pd x64 intrinsic", "_mm256_set1_ps x64 intrinsic", "_mm256_setr_epi16 x64 intrinsic", "_mm256_setr_epi32 x64 intrinsic", "_mm256_setr_epi64x x64 intrinsic", "_mm256_setr_epi8 x64 intrinsic", "_mm256_setr_pd x64 intrinsic", "_mm256_setr_ps x64 intrinsic", "_mm256_setzero_pd x64 intrinsic", "_mm256_setzero_ps x64 intrinsic", "_mm256_setzero_si256 x64 intrinsic", "_mm256_shuffle_epi32 x64 intrinsic", "_mm256_shuffle_epi8 x64 intrinsic", "_mm256_shuffle_pd x64 intrinsic", "_mm256_shuffle_ps x64 intrinsic", "_mm256_shufflehi_epi16 x64 intrinsic", "_mm256_shufflelo_epi16 x64 intrinsic", "_mm256_sign_epi16 x64 intrinsic", "_mm256_sign_epi32 x64 intrinsic", "_mm256_sign_epi8 x64 intrinsic", "_mm256_sll_epi16 x64 intrinsic", "_mm256_sll_epi32 x64 intrinsic", "_mm256_sll_epi64 x64 intrinsic", "_mm256_slli_epi16 x64 intrinsic", "_mm256_slli_epi32 x64 intrinsic", "_mm256_slli_epi64 x64 intrinsic", "_mm256_slli_si256 x64 intrinsic", "_mm256_sllv_epi32 x64 intrinsic", "_mm256_sllv_epi64 x64 intrinsic", "_mm256_sqrt_pd x64 intrinsic", "_mm256_sqrt_ps x64 intrinsic", "_mm256_sra_epi16 x64 intrinsic", "_mm256_sra_epi32 x64 intrinsic", "_mm256_srai_epi16 x64 intrinsic", "_mm256_srai_epi32 x64 intrinsic", "_mm256_srav_epi32 x64 intrinsic", "_mm256_srl_epi16 x64 intrinsic", "_mm256_srl_epi32 x64 intrinsic", "_mm256_srl_epi64 x64 intrinsic", "_mm256_srli_epi16 x64 intrinsic", "_mm256_srli_epi32 x64 intrinsic", "_mm256_srli_epi64 x64 intrinsic", "_mm256_srli_si256 x64 intrinsic", "_mm256_srlv_epi32 x64 intrinsic", "_mm256_srlv_epi64 x64 intrinsic", "_mm256_store_pd x64 intrinsic", "_mm256_store_ps x64 intrinsic", "_mm256_store_si256 x64 intrinsic", "_mm256_storeu_pd x64 intrinsic", "_mm256_storeu_ps x64 intrinsic", "_mm256_storeu_si256 x64 intrinsic", "_mm256_stream_load_si256 x64 intrinsic", "_mm256_stream_pd x64 intrinsic", "_mm256_stream_ps x64 intrinsic", "_mm256_stream_si256 x64 intrinsic", "_mm256_sub_epi16 x64 intrinsic", "_mm256_sub_epi32 x64 intrinsic", "_mm256_sub_epi64 x64 intrinsic", "_mm256_sub_epi8 x64 intrinsic", "_mm256_sub_pd x64 intrinsic", "_mm256_sub_ps x64 intrinsic", "_mm256_subs_epi16 x64 intrinsic", "_mm256_subs_epi8 x64 intrinsic", "_mm256_subs_epu16 x64 intrinsic", "_mm256_subs_epu8 x64 intrinsic", "_mm256_testc_pd x64 intrinsic", "_mm256_testc_ps x64 intrinsic", "_mm256_testc_si256 x64 intrinsic", "_mm256_testnzc_pd x64 intrinsic", "_mm256_testnzc_ps x64 intrinsic", "_mm256_testnzc_si256 x64 intrinsic", "_mm256_testz_pd x64 intrinsic", "_mm256_testz_ps x64 intrinsic", "_mm256_testz_si256 x64 intrinsic", "_mm256_unpackhi_epi16 x64 intrinsic", "_mm256_unpackhi_epi32 x64 intrinsic", "_mm256_unpackhi_epi64 x64 intrinsic", "_mm256_unpackhi_epi8 x64 intrinsic", "_mm256_unpackhi_pd x64 intrinsic", "_mm256_unpackhi_ps x64 intrinsic", "_mm256_unpacklo_epi16 x64 intrinsic", "_mm256_unpacklo_epi32 x64 intrinsic", "_mm256_unpacklo_epi64 x64 intrinsic", "_mm256_unpacklo_epi8 x64 intrinsic", "_mm256_unpacklo_pd x64 intrinsic", "_mm256_unpacklo_ps x64 intrinsic", "_mm256_xor_pd x64 intrinsic", "_mm256_xor_ps x64 intrinsic", "_mm256_xor_si256 x64 intrinsic", "_mm256_zeroall x64 intrinsic", "_mm256_zeroupper x64 intrinsic", "_mulx_u32 x64 intrinsic", "_mulx_u64 x64 intrinsic", "__nvreg_restore_fence x64 intrinsic", "__nvreg_save_fence x64 intrinsic", "_pdep_u32 x64 intrinsic", "_pdep_u64 x64 intrinsic", "_pext_u32 x64 intrinsic", "_pext_u64 x64 intrinsic", "_rdrand16_step x64 intrinsic", "_rdrand32_step x64 intrinsic", "_rdrand64_step x64 intrinsic", "_rdseed16_step x64 intrinsic", "_rdseed32_step x64 intrinsic", "_rdseed64_step x64 intrinsic", "_readfsbase_u32 x64 intrinsic", "_readfsbase_u64 x64 intrinsic", "_readgsbase_u32 x64 intrinsic", "_readgsbase_u64 x64 intrinsic", "_rorx_u32 x64 intrinsic", "_rorx_u64 x64 intrinsic", "_rsm x64 intrinsic", "_sarx_i32 x64 intrinsic", "_sarx_i64 x64 intrinsic", "_sgdt x64 intrinsic", "_shlx_u32 x64 intrinsic", "_shlx_u64 x64 intrinsic", "_shrx_u32 x64 intrinsic", "_shrx_u64 x64 intrinsic", "__slwpcb x64 intrinsic", "_stac x64 intrinsic", "_store_be_u16 x64 intrinsic", "_storebe_i16 x64 intrinsic", "_store_be_u32 x64 intrinsic", "_storebe_i32 x64 intrinsic", "_store_be_u64 x64 intrinsic", "_storebe_i64 x64 intrinsic", "_Store_HLERelease x64 intrinsic", "_Store64_HLERelease x64 intrinsic", "_StorePointer_HLERelease x64 intrinsic", "_subborrow_u16 x64 intrinsic", "_subborrow_u32 x64 intrinsic", "_subborrow_u64 x64 intrinsic", "_subborrow_u8 x64 intrinsic", "_t1mskc_u32 x64 intrinsic", "_t1mskc_u64 x64 intrinsic", "_tzcnt_u32 x64 intrinsic", "_tzcnt_u64 x64 intrinsic", "_tzmsk_u32 x64 intrinsic", "_tzmsk_u64 x64 intrinsic", "_writefsbase_u32 x64 intrinsic", "_writefsbase_u64 x64 intrinsic", "_writegsbase_u32 x64 intrinsic", "_writegsbase_u64 x64 intrinsic", "_xabort x64 intrinsic", "_xbegin x64 intrinsic", "_xend x64 intrinsic", "_xgetbv x64 intrinsic", "_xrstor x64 intrinsic", "_xrstor64 x64 intrinsic", "_xsave x64 intrinsic", "_xsave64 x64 intrinsic", "_xsaveopt x64 intrinsic", "_xsaveopt64 x64 intrinsic", "_xsetbv x64 intrinsic", "_xtest x64 intrinsic"] --- # x64 (amd64) intrinsics list @@ -13,7 +13,7 @@ For information about individual intrinsics, see these resources, as appropriate - The header file. Many intrinsics are documented in comments in the header file. -- [Intel Intrinsics Guide](https://software.intel.com/sites/landingpage/IntrinsicsGuide). Use the search box to find specific intrinsics. +- [Intel Intrinsics Guide](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html). Use the search box to find specific intrinsics. - [Intel 64 and IA-32 Architectures Software Developer Manuals](https://software.intel.com/articles/intel-sdm) @@ -25,7 +25,7 @@ For information about individual intrinsics, see these resources, as appropriate ## x64 intrinsics -The following table lists the intrinsics available on x64 processors. The Technology column lists required instruction-set support. Use the [`__cpuid`](cpuid-cpuidex.md) intrinsic to determine instruction-set support at run time. If two entries are in one row, they represent different entry points for the same intrinsic. A \[1] indicates the intrinsic is available only on AMD processors. A \[2] indicates the intrinsic is available only on Intel processors. A \[3] indicates the prototype is a macro. The header required for the function prototype is listed in the Header column. The intrin.h header includes both immintrin.h and ammintrin.h for simplicity. +The following table lists the intrinsics available on x64 processors. The Technology column lists required instruction-set support. Use the [`__cpuid`](cpuid-cpuidex.md) intrinsic to determine instruction-set support at run time. If two entries are in one row, they represent different entry points for the same intrinsic. \[Macro] indicates the prototype is a macro. The header required for the function prototype is listed in the Header column. The `intrin.h` header includes both `immintrin.h` and `ammintrin.h` for simplicity. | Intrinsic name | Technology | Header | Function prototype | |--|--|--|--| @@ -33,19 +33,19 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_addcarry_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarry_u32) | | intrin.h | `unsigned char _addcarry_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | | [`_addcarry_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarry_u64) | | intrin.h | `unsigned char _addcarry_u64(unsigned char, unsigned __int64, unsigned __int64, unsigned __int64 *);` | | `_addcarry_u8` | | intrin.h | `unsigned char _addcarry_u8(unsigned char, unsigned char, unsigned char, unsigned char *);` | -| [`_addcarryx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u32) | ADX \[2] | immintrin.h | `unsigned char _addcarryx_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | -| [`_addcarryx_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u64) | ADX \[2] | immintrin.h | `unsigned char _addcarryx_u64(unsigned char, unsigned __int64, unsigned __int64, unsigned __int64 *);` | +| [`_addcarryx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u32) | ADX | immintrin.h | `unsigned char _addcarryx_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | +| [`_addcarryx_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u64) | ADX | immintrin.h | `unsigned char _addcarryx_u64(unsigned char, unsigned __int64, unsigned __int64, unsigned __int64 *);` | | [`__addgsbyte`](addgsbyte-addgsword-addgsdword-addgsqword.md) | | intrin.h | `void __addgsbyte(unsigned long, unsigned char);` | | [`__addgsdword`](addgsbyte-addgsword-addgsdword-addgsqword.md) | | intrin.h | `void __addgsdword(unsigned long, unsigned int);` | | [`__addgsqword`](addgsbyte-addgsword-addgsdword-addgsqword.md) | | intrin.h | `void __addgsqword(unsigned long, unsigned __int64);` | | [`__addgsword`](addgsbyte-addgsword-addgsdword-addgsqword.md) | | intrin.h | `void __addgsword(unsigned long, unsigned short);` | | [`_AddressOfReturnAddress`](addressofreturnaddress.md) | | intrin.h | `void * _AddressOfReturnAddress(void);` | -| `_andn_u32` | BMI \[1] | ammintrin.h | `unsigned int _andn_u32(unsigned int, unsigned int);` | -| `_andn_u64` | BMI \[1] | ammintrin.h | `unsigned __int64 _andn_u64(unsigned __int64, unsigned __int64);` | +| `_andn_u32` | BMI | ammintrin.h | `unsigned int _andn_u32(unsigned int, unsigned int);` | +| `_andn_u64` | BMI | ammintrin.h | `unsigned __int64 _andn_u64(unsigned __int64, unsigned __int64);` | | [`_bextr_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bextr_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _bextr_u32(unsigned int, unsigned int, unsigned int);` | | [`_bextr_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bextr_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _bextr_u64(unsigned __int64, unsigned int, unsigned int);` | -| `_bextri_u32` | ABM \[1] | ammintrin.h | `unsigned int _bextri_u32(unsigned int, unsigned int);` | -| `_bextri_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _bextri_u64(unsigned __int64, unsigned int);` | +| `_bextri_u32` | ABM | ammintrin.h | `unsigned int _bextri_u32(unsigned int, unsigned int);` | +| `_bextri_u64` | ABM | ammintrin.h | `unsigned __int64 _bextri_u64(unsigned __int64, unsigned int);` | | [`_BitScanForward`](bitscanforward-bitscanforward64.md) | | intrin.h | `unsigned char _BitScanForward(unsigned long*, unsigned long);` | | [`_BitScanForward64`](bitscanforward-bitscanforward64.md) | | intrin.h | `unsigned char _BitScanForward64(unsigned long*, unsigned __int64);` | | [`_BitScanReverse`](bitscanreverse-bitscanreverse64.md) | | intrin.h | `unsigned char _BitScanReverse(unsigned long*, unsigned long);` | @@ -58,28 +58,34 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_bittestandreset64`](bittestandreset-bittestandreset64.md) | | intrin.h | `unsigned char _bittestandreset64(__int64 *, __int64);` | | [`_bittestandset`](bittestandset-bittestandset64.md) | | intrin.h | `unsigned char _bittestandset(long *, long);` | | [`_bittestandset64`](bittestandset-bittestandset64.md) | | intrin.h | `unsigned char _bittestandset64(__int64 *, __int64);` | -| `_blcfill_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcfill_u32(unsigned int);` | -| `_blcfill_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blcfill_u64(unsigned __int64);` | -| `_blci_u32` | ABM \[1] | ammintrin.h | `unsigned int _blci_u32(unsigned int);` | -| `_blci_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blci_u64(unsigned __int64);` | -| `_blcic_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcic_u32(unsigned int);` | -| `_blcic_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blcic_u64(unsigned __int64);` | -| `_blcmsk_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcmsk_u32(unsigned int);` | -| `_blcmsk_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blcmsk_u64(unsigned __int64);` | -| `_blcs_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcs_u32(unsigned int);` | -| `_blcs_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blcs_u64(unsigned __int64);` | -| `_blsfill_u32` | ABM \[1] | ammintrin.h | `unsigned int _blsfill_u32(unsigned int);` | -| `_blsfill_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blsfill_u64(unsigned __int64);` | +| `_blcfill_u32` | ABM | ammintrin.h | `unsigned int _blcfill_u32(unsigned int);` | +| `_blcfill_u64` | ABM | ammintrin.h | `unsigned __int64 _blcfill_u64(unsigned __int64);` | +| `_blci_u32` | ABM | ammintrin.h | `unsigned int _blci_u32(unsigned int);` | +| `_blci_u64` | ABM | ammintrin.h | `unsigned __int64 _blci_u64(unsigned __int64);` | +| `_blcic_u32` | ABM | ammintrin.h | `unsigned int _blcic_u32(unsigned int);` | +| `_blcic_u64` | ABM | ammintrin.h | `unsigned __int64 _blcic_u64(unsigned __int64);` | +| `_blcmsk_u32` | ABM | ammintrin.h | `unsigned int _blcmsk_u32(unsigned int);` | +| `_blcmsk_u64` | ABM | ammintrin.h | `unsigned __int64 _blcmsk_u64(unsigned __int64);` | +| `_blcs_u32` | ABM | ammintrin.h | `unsigned int _blcs_u32(unsigned int);` | +| `_blcs_u64` | ABM | ammintrin.h | `unsigned __int64 _blcs_u64(unsigned __int64);` | +| `_blsfill_u32` | ABM | ammintrin.h | `unsigned int _blsfill_u32(unsigned int);` | +| `_blsfill_u64` | ABM | ammintrin.h | `unsigned __int64 _blsfill_u64(unsigned __int64);` | | [`_blsi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsi_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsi_u32(unsigned int);` | | [`_blsi_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsi_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _blsi_u64(unsigned __int64);` | -| `_blsic_u32` | ABM \[1] | ammintrin.h | `unsigned int _blsic_u32(unsigned int);` | -| `_blsic_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _blsic_u64(unsigned __int64);` | +| `_blsic_u32` | ABM | ammintrin.h | `unsigned int _blsic_u32(unsigned int);` | +| `_blsic_u64` | ABM | ammintrin.h | `unsigned __int64 _blsic_u64(unsigned __int64);` | | [`_blsmsk_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsmsk_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsmsk_u32(unsigned int);` | | [`_blsmsk_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsmsk_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _blsmsk_u64(unsigned __int64);` | | [`_blsr_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsr_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsr_u32(unsigned int);` | | [`_blsr_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsr_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _blsr_u64(unsigned __int64);` | -| [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI \[2] | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | -| [`_bzhi_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u64) | BMI \[2] | immintrin.h | `unsigned __int64 _bzhi_u64(unsigned __int64, unsigned int);` | +| [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | +| [`_bzhi_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u64) | BMI | immintrin.h | `unsigned __int64 _bzhi_u64(unsigned __int64, unsigned int);` | +| [`_castf32_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf32_u32) | | immintrin.h | `unsigned __int32 _castf32_u32 (float);` | +| [`_castf64_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf64_u64) | | immintrin.h | `unsigned __int64 _castf64_u64 (double);` | +| [`_castu32_f32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu32_f32) | | immintrin.h | `float _castu32_f32 (unsigned __int32);` | +| [`_castu64_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu64_f64) | | immintrin.h | `double _castu64_f64 (unsigned __int64 a);` | +| [`__check_isa_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_isa_support(unsigned int, unsigned int);` | +| [`__check_arch_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_arch_support(unsigned int, unsigned int);` | | `_clac` | SMAP | intrin.h | `void _clac(void);` | | [`__cpuid`](cpuid-cpuidex.md) | | intrin.h | `void __cpuid(int *, int);` | | [`__cpuidex`](cpuid-cpuidex.md) | | intrin.h | `void __cpuidex(int *, int, int);` | @@ -92,10 +98,10 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_enable`](enable.md) | | intrin.h | `void _enable(void);` | | [`__fastfail`](fastfail.md) | | intrin.h | `void __fastfail(unsigned int);` | | [`__faststorefence`](faststorefence.md) | | intrin.h | `void __faststorefence(void);` | -| [`_fxrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor) | FXSR \[2] | immintrin.h | `void _fxrstor(void const*);` | -| [`_fxrstor64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor64) | FXSR \[2] | immintrin.h | `void _fxrstor64(void const*);` | -| [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR \[2] | immintrin.h | `void _fxsave(void*);` | -| [`_fxsave64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave64) | FXSR \[2] | immintrin.h | `void _fxsave64(void*);` | +| [`_fxrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor) | FXSR | immintrin.h | `void _fxrstor(void const*);` | +| [`_fxrstor64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor64) | FXSR | immintrin.h | `void _fxrstor64(void const*);` | +| [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR | immintrin.h | `void _fxsave(void*);` | +| [`_fxsave64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave64) | FXSR | immintrin.h | `void _fxsave64(void*);` | | [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `(unsigned int __getcallerseflags());` | | [`__halt`](halt.md) | | intrin.h | `void __halt(void);` | | [`__inbyte`](inbyte.md) | | intrin.h | `unsigned char __inbyte(unsigned short);` | @@ -108,114 +114,114 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__indwordstring`](indwordstring.md) | | intrin.h | `void __indwordstring(unsigned short, unsigned long *, unsigned long);` | | [`__int2c`](int2c.md) | | intrin.h | `void __int2c(void);` | | [`_InterlockedAnd`](interlockedand-intrinsic-functions.md) | | intrin.h | `long _InterlockedAnd(long volatile *, long);` | -| [`_InterlockedAnd_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedAnd_HLEAcquire(long volatile *, long);` | -| [`_InterlockedAnd_HLERelease`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedAnd_HLERelease(long volatile *, long);` | +| [`_InterlockedAnd_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedAnd_HLEAcquire(long volatile *, long);` | +| [`_InterlockedAnd_HLERelease`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedAnd_HLERelease(long volatile *, long);` | | [`_InterlockedAnd_np`](interlockedand-intrinsic-functions.md) | | intrin.h | `long _InterlockedAnd_np(long *, long);` | | [`_InterlockedAnd16`](interlockedand-intrinsic-functions.md) | | intrin.h | `short _InterlockedAnd16(short volatile *, short);` | | [`_InterlockedAnd16_np`](interlockedand-intrinsic-functions.md) | | intrin.h | `short _InterlockedAnd16_np(short *, short);` | | [`_InterlockedAnd64`](interlockedand-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedAnd64(__int64 volatile *, __int64);` | -| [`_InterlockedAnd64_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedAnd64_HLEAcquire(__int64 volatile *, __int64);` | -| [`_InterlockedAnd64_HLERelease`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedAnd64_HLERelease(__int64 volatile *, __int64);` | +| [`_InterlockedAnd64_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedAnd64_HLEAcquire(__int64 volatile *, __int64);` | +| [`_InterlockedAnd64_HLERelease`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedAnd64_HLERelease(__int64 volatile *, __int64);` | | [`_InterlockedAnd64_np`](interlockedand-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedAnd64_np(__int64 *, __int64);` | | [`_InterlockedAnd8`](interlockedand-intrinsic-functions.md) | | intrin.h | `char _InterlockedAnd8(char volatile *, char);` | | [`_InterlockedAnd8_np`](interlockedand-intrinsic-functions.md) | | intrin.h | `char _InterlockedAnd8_np(char *, char);` | | [`_interlockedbittestandreset`](interlockedbittestandreset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandreset(long *, long);` | -| [`_interlockedbittestandreset_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset_HLEAcquire(long *, long);` | -| [`_interlockedbittestandreset_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset_HLERelease(long *, long);` | +| [`_interlockedbittestandreset_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset_HLEAcquire(long *, long);` | +| [`_interlockedbittestandreset_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset_HLERelease(long *, long);` | | [`_interlockedbittestandreset64`](interlockedbittestandreset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandreset64(__int64 *, __int64);` | -| [`_interlockedbittestandreset64_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset64_HLEAcquire(__int64 *, __int64);` | -| [`_interlockedbittestandreset64_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset64_HLERelease(__int64 *, __int64);` | +| [`_interlockedbittestandreset64_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset64_HLEAcquire(__int64 *, __int64);` | +| [`_interlockedbittestandreset64_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset64_HLERelease(__int64 *, __int64);` | | [`_interlockedbittestandset`](interlockedbittestandset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandset(long *, long);` | -| [`_interlockedbittestandset_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset_HLEAcquire(long *, long);` | -| [`_interlockedbittestandset_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset_HLERelease(long *, long);` | +| [`_interlockedbittestandset_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset_HLEAcquire(long *, long);` | +| [`_interlockedbittestandset_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset_HLERelease(long *, long);` | | [`_interlockedbittestandset64`](interlockedbittestandset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandset64(__int64 *, __int64);` | -| [`_interlockedbittestandset64_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset64_HLEAcquire(__int64 *, __int64);` | -| [`_interlockedbittestandset64_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset64_HLERelease(__int64 *, __int64);` | +| [`_interlockedbittestandset64_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset64_HLEAcquire(__int64 *, __int64);` | +| [`_interlockedbittestandset64_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset64_HLERelease(__int64 *, __int64);` | | [`_InterlockedCompareExchange`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `long _InterlockedCompareExchange (long volatile *, long, long);` | -| [`_InterlockedCompareExchange_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedCompareExchange_HLEAcquire(long volatile *, long, long);` | -| [`_InterlockedCompareExchange_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedCompareExchange_HLERelease(long volatile *, long, long);` | +| [`_InterlockedCompareExchange_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedCompareExchange_HLEAcquire(long volatile *, long, long);` | +| [`_InterlockedCompareExchange_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedCompareExchange_HLERelease(long volatile *, long, long);` | | [`_InterlockedCompareExchange_np`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `long _InterlockedCompareExchange_np (long *, long, long);` | | [`_InterlockedCompareExchange128`](interlockedcompareexchange128.md) | | intrin.h | `unsigned char _InterlockedCompareExchange128(__int64 volatile *, __int64, __int64, __int64*);` | | [`_InterlockedCompareExchange128_np`](interlockedcompareexchange128.md) | | intrin.h | `unsigned char _InterlockedCompareExchange128(__int64 volatile *, __int64, __int64, __int64*);` | | [`_InterlockedCompareExchange16`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `short _InterlockedCompareExchange16(short volatile *, short, short);` | | [`_InterlockedCompareExchange16_np`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `short _InterlockedCompareExchange16_np(short volatile *, short, short);` | | [`_InterlockedCompareExchange64`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedCompareExchange64(__int64 volatile *, __int64, __int64);` | -| [`_InterlockedCompareExchange64_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedCompareExchange64_HLEAcquire(__int64 volatile *, __int64, __int64);` | -| [`_InterlockedCompareExchange64_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedCompareExchange64_HLERelease(__int64 volatile *, __int64, __int64);` | +| [`_InterlockedCompareExchange64_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedCompareExchange64_HLEAcquire(__int64 volatile *, __int64, __int64);` | +| [`_InterlockedCompareExchange64_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedCompareExchange64_HLERelease(__int64 volatile *, __int64, __int64);` | | [`_InterlockedCompareExchange64_np`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedCompareExchange64_np(__int64 *, __int64, __int64);` | | [`_InterlockedCompareExchange8`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `char _InterlockedCompareExchange8(char volatile *, char, char);` | | [`_InterlockedCompareExchangePointer`](interlockedcompareexchangepointer-intrinsic-functions.md) | | intrin.h | `void *_InterlockedCompareExchangePointer (void *volatile *, void *, void *);` | -| [`_InterlockedCompareExchangePointer_HLEAcquire`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void *_InterlockedCompareExchangePointer_HLEAcquire(void *volatile *, void *, void *);` | -| [`_InterlockedCompareExchangePointer_HLERelease`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void *_InterlockedCompareExchangePointer_HLERelease(void *volatile *, void *, void *);` | +| [`_InterlockedCompareExchangePointer_HLEAcquire`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void *_InterlockedCompareExchangePointer_HLEAcquire(void *volatile *, void *, void *);` | +| [`_InterlockedCompareExchangePointer_HLERelease`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void *_InterlockedCompareExchangePointer_HLERelease(void *volatile *, void *, void *);` | | [`_InterlockedCompareExchangePointer_np`](interlockedcompareexchangepointer-intrinsic-functions.md) | | intrin.h | `void *_InterlockedCompareExchangePointer_np(void **, void *, void *);` | | [`_InterlockedDecrement`](interlockeddecrement-intrinsic-functions.md) | | intrin.h | `long _InterlockedDecrement(long volatile *);` | | [`_InterlockedDecrement16`](interlockeddecrement-intrinsic-functions.md) | | intrin.h | `short _InterlockedDecrement16(short volatile *);` | | [`_InterlockedDecrement64`](interlockeddecrement-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedDecrement64(__int64 volatile *);` | | [`_InterlockedExchange`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `long _InterlockedExchange(long volatile *, long);` | -| [`_InterlockedExchange_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchange_HLEAcquire(long volatile *, long);` | -| [`_InterlockedExchange_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchange_HLERelease(long volatile *, long);` | +| [`_InterlockedExchange_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchange_HLEAcquire(long volatile *, long);` | +| [`_InterlockedExchange_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchange_HLERelease(long volatile *, long);` | | [`_InterlockedExchange16`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `short _InterlockedExchange16(short volatile *, short);` | | [`_InterlockedExchange64`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedExchange64(__int64 volatile *, __int64);` | -| [`_InterlockedExchange64_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedExchange64_HLEAcquire(__int64 volatile *, __int64);` | -| [`_InterlockedExchange64_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedExchange64_HLERelease(__int64 volatile *, __int64);` | +| [`_InterlockedExchange64_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedExchange64_HLEAcquire(__int64 volatile *, __int64);` | +| [`_InterlockedExchange64_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedExchange64_HLERelease(__int64 volatile *, __int64);` | | [`_InterlockedExchange8`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `char _InterlockedExchange8(char volatile *, char);` | | [`_InterlockedExchangeAdd`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `long _InterlockedExchangeAdd(long volatile *, long);` | -| [`_InterlockedExchangeAdd_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchangeAdd_HLEAcquire(long volatile *, long);` | -| [`_InterlockedExchangeAdd_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchangeAdd_HLERelease(long volatile *, long);` | +| [`_InterlockedExchangeAdd_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchangeAdd_HLEAcquire(long volatile *, long);` | +| [`_InterlockedExchangeAdd_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchangeAdd_HLERelease(long volatile *, long);` | | [`_InterlockedExchangeAdd16`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `short _InterlockedExchangeAdd16(short volatile *, short);` | | [`_InterlockedExchangeAdd64`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedExchangeAdd64(__int64 volatile *, __int64);` | -| [`_InterlockedExchangeAdd64_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedExchangeAdd64_HLEAcquire(__int64 volatile *, __int64);` | -| [`_InterlockedExchangeAdd64_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedExchangeAdd64_HLERelease(__int64 volatile *, __int64);` | +| [`_InterlockedExchangeAdd64_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedExchangeAdd64_HLEAcquire(__int64 volatile *, __int64);` | +| [`_InterlockedExchangeAdd64_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedExchangeAdd64_HLERelease(__int64 volatile *, __int64);` | | [`_InterlockedExchangeAdd8`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `char _InterlockedExchangeAdd8(char volatile *, char);` | | [`_InterlockedExchangePointer`](interlockedexchangepointer-intrinsic-functions.md) | | intrin.h | `void * _InterlockedExchangePointer(void *volatile *, void *);` | -| [`_InterlockedExchangePointer_HLEAcquire`](interlockedexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void * _InterlockedExchangePointer_HLEAcquire(void *volatile *, void *);` | -| [`_InterlockedExchangePointer_HLERelease`](interlockedexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void * _InterlockedExchangePointer_HLERelease(void *volatile *, void *);` | +| [`_InterlockedExchangePointer_HLEAcquire`](interlockedexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void * _InterlockedExchangePointer_HLEAcquire(void *volatile *, void *);` | +| [`_InterlockedExchangePointer_HLERelease`](interlockedexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void * _InterlockedExchangePointer_HLERelease(void *volatile *, void *);` | | [`_InterlockedIncrement`](interlockedincrement-intrinsic-functions.md) | | intrin.h | `long _InterlockedIncrement(long volatile *);` | | [`_InterlockedIncrement16`](interlockedincrement-intrinsic-functions.md) | | intrin.h | `short _InterlockedIncrement16(short volatile *);` | | [`_InterlockedIncrement64`](interlockedincrement-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedIncrement64(__int64 volatile *);` | | [`_InterlockedOr`](interlockedor-intrinsic-functions.md) | | intrin.h | `long _InterlockedOr(long volatile *, long);` | -| [`_InterlockedOr_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedOr_HLEAcquire(long volatile *, long);` | -| [`_InterlockedOr_HLERelease`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedOr_HLERelease(long volatile *, long);` | +| [`_InterlockedOr_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedOr_HLEAcquire(long volatile *, long);` | +| [`_InterlockedOr_HLERelease`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedOr_HLERelease(long volatile *, long);` | | [`_InterlockedOr_np`](interlockedor-intrinsic-functions.md) | | intrin.h | `long _InterlockedOr_np(long *, long);` | | [`_InterlockedOr16`](interlockedor-intrinsic-functions.md) | | intrin.h | `short _InterlockedOr16(short volatile *, short);` | | [`_InterlockedOr16_np`](interlockedor-intrinsic-functions.md) | | intrin.h | `short _InterlockedOr16_np(short *, short);` | | [`_InterlockedOr64`](interlockedor-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedOr64(__int64 volatile *, __int64);` | -| [`_InterlockedOr64_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedOr64_HLEAcquire(__int64 volatile *, __int64);` | -| [`_InterlockedOr64_HLERelease`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedOr64_HLERelease(__int64 volatile *, __int64);` | +| [`_InterlockedOr64_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedOr64_HLEAcquire(__int64 volatile *, __int64);` | +| [`_InterlockedOr64_HLERelease`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedOr64_HLERelease(__int64 volatile *, __int64);` | | [`_InterlockedOr64_np`](interlockedor-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedOr64_np(__int64 *, __int64);` | | [`_InterlockedOr8`](interlockedor-intrinsic-functions.md) | | intrin.h | `char _InterlockedOr8(char volatile *, char);` | | [`_InterlockedOr8_np`](interlockedor-intrinsic-functions.md) | | intrin.h | `char _InterlockedOr8_np(char *, char);` | | [`_InterlockedXor`](interlockedxor-intrinsic-functions.md) | | intrin.h | `long _InterlockedXor(long volatile *, long);` | -| [`_InterlockedXor_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedXor_HLEAcquire(long volatile *, long);` | -| [`_InterlockedXor_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedXor_HLERelease(long volatile *, long);` | +| [`_InterlockedXor_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedXor_HLEAcquire(long volatile *, long);` | +| [`_InterlockedXor_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedXor_HLERelease(long volatile *, long);` | | [`_InterlockedXor_np`](interlockedxor-intrinsic-functions.md) | | intrin.h | `long _InterlockedXor_np(long *, long);` | | [`_InterlockedXor16`](interlockedxor-intrinsic-functions.md) | | intrin.h | `short _InterlockedXor16(short volatile *, short);` | | [`_InterlockedXor16_np`](interlockedxor-intrinsic-functions.md) | | intrin.h | `short _InterlockedXor16_np(short *, short);` | | [`_InterlockedXor64`](interlockedxor-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedXor64(__int64 volatile *, __int64);` | -| [`_InterlockedXor64_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedXor64_HLEAcquire(__int64 volatile *, __int64);` | -| [`_InterlockedXor64_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedXor64_HLERelease(__int64 volatile *, __int64);` | +| [`_InterlockedXor64_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedXor64_HLEAcquire(__int64 volatile *, __int64);` | +| [`_InterlockedXor64_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedXor64_HLERelease(__int64 volatile *, __int64);` | | [`_InterlockedXor64_np`](interlockedxor-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedXor64_np(__int64 *, __int64);` | | [`_InterlockedXor8`](interlockedxor-intrinsic-functions.md) | | intrin.h | `char _InterlockedXor8(char volatile *, char);` | | [`_InterlockedXor8_np`](interlockedxor-intrinsic-functions.md) | | intrin.h | `char _InterlockedXor8_np(char *, char);` | | [`__invlpg`](invlpg.md) | | intrin.h | `void __invlpg(void*);` | -| [`_invpcid`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_invpcid) | INVPCID \[2] | immintrin.h | `void _invpcid(unsigned int, void *);` | +| [`_invpcid`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_invpcid) | INVPCID | immintrin.h | `void _invpcid(unsigned int, void *);` | | [`__inword`](inword.md) | | intrin.h | `unsigned short __inword(unsigned short);` | | [`__inwordstring`](inwordstring.md) | | intrin.h | `void __inwordstring(unsigned short, unsigned short *, unsigned long);` | | `_lgdt` | | intrin.h | `void _lgdt(void*);` | | [`__lidt`](lidt.md) | | intrin.h | `void __lidt(void*);` | | [`__ll_lshift`](ll-lshift.md) | | intrin.h | `unsigned __int64 [pascal/cdecl] __ll_lshift(unsigned __int64, int);` | | [`__ll_rshift`](ll-rshift.md) | | intrin.h | `__int64 [pascal/cdecl] __ll_rshift(__int64, int);` | -| `__llwpcb` | LWP \[1] | ammintrin.h | `void __llwpcb(void *);` | -| [`_loadbe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i16&expand=3071) | MOVBE | immintrin.h | `short _loadbe_i16(void const*);` \[3] | -| [`_loadbe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i32&expand=3072) | MOVBE | immintrin.h | `int _loadbe_i32(void const*);` \[3] | -| [`_loadbe_i64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i64&expand=3073) | MOVBE | immintrin.h | `__int64 _loadbe_i64(void const*);` \[3] | -| `_load_be_u16` | MOVBE | immintrin.h | `unsigned short _load_be_u16(void const*);` \[3] | -| `_load_be_u32` | MOVBE | immintrin.h | `unsigned int _load_be_u32(void const*);` \[3] | -| `_load_be_u64` | MOVBE | immintrin.h | `unsigned __int64 _load_be_u64(void const*);` \[3] | -| `__lwpins32` | LWP \[1] | ammintrin.h | `unsigned char __lwpins32(unsigned int, unsigned int, unsigned int);` | -| `__lwpins64` | LWP \[1] | ammintrin.h | `unsigned char __lwpins64(unsigned __int64, unsigned int, unsigned int);` | -| `__lwpval32` | LWP \[1] | ammintrin.h | `void __lwpval32(unsigned int, unsigned int, unsigned int);` | -| `__lwpval64` | LWP \[1] | ammintrin.h | `void __lwpval64(unsigned __int64, unsigned int, unsigned int);` | +| `__llwpcb` | LWP | ammintrin.h | `void __llwpcb(void *);` | +| [`_loadbe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i16&expand=3071) | MOVBE | immintrin.h | `short _loadbe_i16(void const*);` \[Macro] | +| [`_loadbe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i32&expand=3072) | MOVBE | immintrin.h | `int _loadbe_i32(void const*);` \[Macro] | +| [`_loadbe_i64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i64&expand=3073) | MOVBE | immintrin.h | `__int64 _loadbe_i64(void const*);` \[Macro] | +| `_load_be_u16` | MOVBE | immintrin.h | `unsigned short _load_be_u16(void const*);` \[Macro] | +| `_load_be_u32` | MOVBE | immintrin.h | `unsigned int _load_be_u32(void const*);` \[Macro] | +| `_load_be_u64` | MOVBE | immintrin.h | `unsigned __int64 _load_be_u64(void const*);` \[Macro] | +| `__lwpins32` | LWP | ammintrin.h | `unsigned char __lwpins32(unsigned int, unsigned int, unsigned int);` | +| `__lwpins64` | LWP | ammintrin.h | `unsigned char __lwpins64(unsigned __int64, unsigned int, unsigned int);` | +| `__lwpval32` | LWP | ammintrin.h | `void __lwpval32(unsigned int, unsigned int, unsigned int);` | +| `__lwpval64` | LWP | ammintrin.h | `void __lwpval64(unsigned __int64, unsigned int, unsigned int);` | | [`__lzcnt`](lzcnt16-lzcnt-lzcnt64.md) | LZCNT | intrin.h | `unsigned int __lzcnt(unsigned int);` | | [`_lzcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_lzcnt_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _lzcnt_u32(unsigned int);` | | [`_lzcnt_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_lzcnt_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _lzcnt_u64(unsigned __int64);` | @@ -240,12 +246,12 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_epu8) | SSE2 | intrin.h | `__m128i _mm_adds_epu8(__m128i, __m128i);` | | [`_mm_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_addsub_pd) | SSE3 | intrin.h | `__m128d _mm_addsub_pd(__m128d, __m128d);` | | [`_mm_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_addsub_ps) | SSE3 | intrin.h | `__m128 _mm_addsub_ps(__m128, __m128);` | -| [`_mm_aesdec_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdec_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesdec_si128(__m128i, __m128i);` | -| [`_mm_aesdeclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdeclast_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesdeclast_si128(__m128i, __m128i);` | -| [`_mm_aesenc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenc_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesenc_si128(__m128i, __m128i);` | -| [`_mm_aesenclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenclast_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesenclast_si128(__m128i, __m128i);` | -| [`_mm_aesimc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesimc_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesimc_si128 (__m128i);` | -| [`_mm_aeskeygenassist_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aeskeygenassist_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aeskeygenassist_si128 (__m128i, const int);` | +| [`_mm_aesdec_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdec_si128) | AESNI | immintrin.h | `__m128i _mm_aesdec_si128(__m128i, __m128i);` | +| [`_mm_aesdeclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdeclast_si128) | AESNI | immintrin.h | `__m128i _mm_aesdeclast_si128(__m128i, __m128i);` | +| [`_mm_aesenc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenc_si128) | AESNI | immintrin.h | `__m128i _mm_aesenc_si128(__m128i, __m128i);` | +| [`_mm_aesenclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenclast_si128) | AESNI | immintrin.h | `__m128i _mm_aesenclast_si128(__m128i, __m128i);` | +| [`_mm_aesimc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesimc_si128) | AESNI | immintrin.h | `__m128i _mm_aesimc_si128 (__m128i);` | +| [`_mm_aeskeygenassist_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aeskeygenassist_si128) | AESNI | immintrin.h | `__m128i _mm_aeskeygenassist_si128 (__m128i, const int);` | | [`_mm_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_alignr_epi8) | SSSE3 | intrin.h | `__m128i _mm_alignr_epi8(__m128i, __m128i, int);` | | [`_mm_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_pd) | SSE2 | intrin.h | `__m128d _mm_and_pd(__m128d, __m128d);` | | [`_mm_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_ps) | SSE | intrin.h | `__m128 _mm_and_ps(__m128, __m128);` | @@ -256,19 +262,19 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_avg_epu16) | SSE2 | intrin.h | `__m128i _mm_avg_epu16(__m128i, __m128i);` | | [`_mm_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_avg_epu8) | SSE2 | intrin.h | `__m128i _mm_avg_epu8(__m128i, __m128i);` | | [`_mm_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi16) | SSE41 | intrin.h | `__m128i _mm_blend_epi16 (__m128i, __m128i, const int);` | -| [`_mm_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_blend_epi32(__m128i, __m128i, const int);` | +| [`_mm_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi32) | AVX2 | immintrin.h | `__m128i _mm_blend_epi32(__m128i, __m128i, const int);` | | [`_mm_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_pd) | SSE41 | intrin.h | `__m128d _mm_blend_pd (__m128d, __m128d, const int);` | | [`_mm_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_ps) | SSE41 | intrin.h | `__m128 _mm_blend_ps (__m128, __m128, const int);` | | [`_mm_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_epi8) | SSE41 | intrin.h | `__m128i _mm_blendv_epi8 (__m128i, __m128i, __m128i);` | | [`_mm_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_pd) | SSE41 | intrin.h | `__m128d _mm_blendv_pd(__m128d, __m128d, __m128d);` | | [`_mm_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_ps) | SSE41 | intrin.h | `__m128 _mm_blendv_ps(__m128, __m128, __m128);` | -| [`_mm_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcast_ss) | AVX \[2] | immintrin.h | `__m128 _mm_broadcast_ss(float const *);` | -| [`_mm_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastb_epi8) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastb_epi8(__m128i);` | -| [`_mm_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastd_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastd_epi32(__m128i);` | -| [`_mm_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastq_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastq_epi64(__m128i);` | -| [`_mm_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastsd_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_broadcastsd_pd(__m128d);` | -| [`_mm_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastss_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_broadcastss_ps(__m128);` | -| [`_mm_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastw_epi16) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastw_epi16(__m128i);` | +| [`_mm_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcast_ss) | AVX | immintrin.h | `__m128 _mm_broadcast_ss(float const *);` | +| [`_mm_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastb_epi8) | AVX2 | immintrin.h | `__m128i _mm_broadcastb_epi8(__m128i);` | +| [`_mm_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastd_epi32) | AVX2 | immintrin.h | `__m128i _mm_broadcastd_epi32(__m128i);` | +| [`_mm_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastq_epi64) | AVX2 | immintrin.h | `__m128i _mm_broadcastq_epi64(__m128i);` | +| [`_mm_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastsd_pd) | AVX2 | immintrin.h | `__m128d _mm_broadcastsd_pd(__m128d);` | +| [`_mm_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastss_ps) | AVX2 | immintrin.h | `__m128 _mm_broadcastss_ps(__m128);` | +| [`_mm_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastw_epi16) | AVX2 | immintrin.h | `__m128i _mm_broadcastw_epi16(__m128i);` | | [`_mm_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castpd_ps) | SSSE3 | intrin.h | `__m128 _mm_castpd_ps(__m128d);` | | [`_mm_castpd_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castpd_si128) | SSSE3 | intrin.h | `__m128i _mm_castpd_si128(__m128d);` | | [`_mm_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castps_pd) | SSSE3 | intrin.h | `__m128d _mm_castps_pd(__m128);` | @@ -276,12 +282,12 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_castsi128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castsi128_pd) | SSSE3 | intrin.h | `__m128d _mm_castsi128_pd(__m128i);` | | [`_mm_castsi128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castsi128_ps) | SSSE3 | intrin.h | `__m128 _mm_castsi128_ps(__m128i);` | | [`_mm_clflush`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clflush) | SSE2 | intrin.h | `void _mm_clflush(void const *);` | -| [`_mm_clmulepi64_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clmulepi64_si128) | PCLMULQDQ \[2] | immintrin.h | `__m128i _mm_clmulepi64_si128 (__m128i, __m128i, const int);` | -| `_mm_cmov_si128` | XOP \[1] | ammintrin.h | `__m128i _mm_cmov_si128(__m128i, __m128i, __m128i);` | -| [`_mm_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_pd) | AVX \[2] | immintrin.h | `__m128d _mm_cmp_pd(__m128d, __m128d, const int);` | -| [`_mm_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ps) | AVX \[2] | immintrin.h | `__m128 _mm_cmp_ps(__m128, __m128, const int);` | -| [`_mm_cmp_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_sd) | AVX \[2] | immintrin.h | `__m128d _mm_cmp_sd(__m128d, __m128d, const int);` | -| [`_mm_cmp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ss) | AVX \[2] | immintrin.h | `__m128 _mm_cmp_ss(__m128, __m128, const int);` | +| [`_mm_clmulepi64_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clmulepi64_si128) | PCLMULQDQ | immintrin.h | `__m128i _mm_clmulepi64_si128 (__m128i, __m128i, const int);` | +| `_mm_cmov_si128` | XOP | ammintrin.h | `__m128i _mm_cmov_si128(__m128i, __m128i, __m128i);` | +| [`_mm_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_pd) | AVX | immintrin.h | `__m128d _mm_cmp_pd(__m128d, __m128d, const int);` | +| [`_mm_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ps) | AVX | immintrin.h | `__m128 _mm_cmp_ps(__m128, __m128, const int);` | +| [`_mm_cmp_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_sd) | AVX | immintrin.h | `__m128d _mm_cmp_sd(__m128d, __m128d, const int);` | +| [`_mm_cmp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ss) | AVX | immintrin.h | `__m128 _mm_cmp_ss(__m128, __m128, const int);` | | [`_mm_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi16) | SSE2 | intrin.h | `__m128i _mm_cmpeq_epi16(__m128i, __m128i);` | | [`_mm_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi32) | SSE2 | intrin.h | `__m128i _mm_cmpeq_epi32(__m128i, __m128i);` | | [`_mm_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi64) | SSE41 | intrin.h | `__m128i _mm_cmpeq_epi64(__m128i, __m128i);` | @@ -355,14 +361,14 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_cmpunord_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_ps) | SSE | intrin.h | `__m128 _mm_cmpunord_ps(__m128, __m128);` | | [`_mm_cmpunord_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_sd) | SSE2 | intrin.h | `__m128d _mm_cmpunord_sd(__m128d, __m128d);` | | [`_mm_cmpunord_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_ss) | SSE | intrin.h | `__m128 _mm_cmpunord_ss(__m128, __m128);` | -| `_mm_com_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi16(__m128i, __m128i, int);` | -| `_mm_com_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | -| `_mm_com_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | -| `_mm_com_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi8(__m128i, __m128i, int);` | -| `_mm_com_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu16(__m128i, __m128i, int);` | -| `_mm_com_epu32` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | -| `_mm_com_epu64` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | -| `_mm_com_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu8(__m128i, __m128i, int);` | +| `_mm_com_epi16` | XOP | ammintrin.h | `__m128i _mm_com_epi16(__m128i, __m128i, int);` | +| `_mm_com_epi32` | XOP | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | +| `_mm_com_epi64` | XOP | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | +| `_mm_com_epi8` | XOP | ammintrin.h | `__m128i _mm_com_epi8(__m128i, __m128i, int);` | +| `_mm_com_epu16` | XOP | ammintrin.h | `__m128i _mm_com_epu16(__m128i, __m128i, int);` | +| `_mm_com_epu32` | XOP | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | +| `_mm_com_epu64` | XOP | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | +| `_mm_com_epu8` | XOP | ammintrin.h | `__m128i _mm_com_epu8(__m128i, __m128i, int);` | | [`_mm_comieq_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comieq_sd) | SSE2 | intrin.h | `int _mm_comieq_sd(__m128d, __m128d);` | | [`_mm_comieq_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comieq_ss) | SSE | intrin.h | `int _mm_comieq_ss(__m128, __m128);` | | [`_mm_comige_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comige_sd) | SSE2 | intrin.h | `int _mm_comige_sd(__m128d, __m128d);` | @@ -397,10 +403,10 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_cvtepu8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtepu8_epi64) | SSE41 | intrin.h | `__m128i _mm_cvtepu8_epi64 (__m128i);` | | [`_mm_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpd_epi32) | SSE2 | intrin.h | `__m128i _mm_cvtpd_epi32(__m128d);` | | [`_mm_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpd_ps) | SSE2 | intrin.h | `__m128 _mm_cvtpd_ps(__m128d);` | -| [`_mm_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtph_ps) | F16C \[2] | immintrin.h | `__m128 _mm_cvtph_ps(__m128i);` | +| [`_mm_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtph_ps) | F16C | immintrin.h | `__m128 _mm_cvtph_ps(__m128i);` | | [`_mm_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_epi32) | SSE2 | intrin.h | `__m128i _mm_cvtps_epi32(__m128);` | | [`_mm_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_pd) | SSE2 | intrin.h | `__m128d _mm_cvtps_pd(__m128);` | -| [`_mm_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_ph) | F16C \[2] | immintrin.h | `__m128i _mm_cvtps_ph(__m128, const int);` | +| [`_mm_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_ph) | F16C | immintrin.h | `__m128i _mm_cvtps_ph(__m128, const int);` | | [`_mm_cvtsd_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_f64) | SSSE3 | intrin.h | `double _mm_cvtsd_f64(__m128d);` | | [`_mm_cvtsd_si32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_si32) | SSE2 | intrin.h | `int _mm_cvtsd_si32(__m128d);` | | [`_mm_cvtsd_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_si64) | SSE2 | intrin.h | `__int64 _mm_cvtsd_si64(__m128d);` | @@ -442,64 +448,64 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_extract_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_extract_ps) | SSE41 | intrin.h | `int _mm_extract_ps(__m128, const int);` | | [`_mm_extract_si64`](mm-extract-si64-mm-extracti-si64.md) | SSE4a | intrin.h | `__m128i _mm_extract_si64(__m128i, __m128i);` | | [`_mm_extracti_si64`](mm-extract-si64-mm-extracti-si64.md) | SSE4a | intrin.h | `__m128i _mm_extracti_si64(__m128i, int, int);` | -| [`_mm_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmadd_ps (__m128, __m128, __m128);` | -| [`_mm_fmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fmadd_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fmadd_ss (__m128, __m128, __m128);` | -| [`_mm_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmaddsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmaddsub_ps (__m128, __m128, __m128);` | -| [`_mm_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmsub_ps (__m128, __m128, __m128);` | -| [`_mm_fmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsub_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fmsub_ss (__m128, __m128, __m128);` | -| [`_mm_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsubadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmsubadd_ps (__m128, __m128, __m128);` | -| [`_mm_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fnmadd_ps (__m128, __m128, __m128);` | -| [`_mm_fnmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmadd_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fnmadd_ss (__m128, __m128, __m128);` | -| [`_mm_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fnmsub_ps (__m128, __m128, __m128);` | -| [`_mm_fnmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmsub_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fnmsub_ss (__m128, __m128, __m128);` | -| `_mm_frcz_pd` | XOP \[1] | ammintrin.h | `__m128d _mm_frcz_pd(__m128d);` | -| `_mm_frcz_ps` | XOP \[1] | ammintrin.h | `__m128 _mm_frcz_ps(__m128);` | -| `_mm_frcz_sd` | XOP \[1] | ammintrin.h | `__m128d _mm_frcz_sd(__m128d, __m128d);` | -| `_mm_frcz_ss` | XOP \[1] | ammintrin.h | `__m128 _mm_frcz_ss(__m128, __m128);` | +| [`_mm_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_pd) | FMA | immintrin.h | `__m128d _mm_fmadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ps) | FMA | immintrin.h | `__m128 _mm_fmadd_ps (__m128, __m128, __m128);` | +| [`_mm_fmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_sd) | FMA | immintrin.h | `__m128d _mm_fmadd_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ss) | FMA | immintrin.h | `__m128 _mm_fmadd_ss (__m128, __m128, __m128);` | +| [`_mm_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_pd) | FMA | immintrin.h | `__m128d _mm_fmaddsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_ps) | FMA | immintrin.h | `__m128 _mm_fmaddsub_ps (__m128, __m128, __m128);` | +| [`_mm_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_pd) | FMA | immintrin.h | `__m128d _mm_fmsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ps) | FMA | immintrin.h | `__m128 _mm_fmsub_ps (__m128, __m128, __m128);` | +| [`_mm_fmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_sd) | FMA | immintrin.h | `__m128d _mm_fmsub_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ss) | FMA | immintrin.h | `__m128 _mm_fmsub_ss (__m128, __m128, __m128);` | +| [`_mm_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_pd) | FMA | immintrin.h | `__m128d _mm_fmsubadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_ps) | FMA | immintrin.h | `__m128 _mm_fmsubadd_ps (__m128, __m128, __m128);` | +| [`_mm_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_pd) | FMA | immintrin.h | `__m128d _mm_fnmadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ps) | FMA | immintrin.h | `__m128 _mm_fnmadd_ps (__m128, __m128, __m128);` | +| [`_mm_fnmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_sd) | FMA | immintrin.h | `__m128d _mm_fnmadd_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ss) | FMA | immintrin.h | `__m128 _mm_fnmadd_ss (__m128, __m128, __m128);` | +| [`_mm_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_pd) | FMA | immintrin.h | `__m128d _mm_fnmsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ps) | FMA | immintrin.h | `__m128 _mm_fnmsub_ps (__m128, __m128, __m128);` | +| [`_mm_fnmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_sd) | FMA | immintrin.h | `__m128d _mm_fnmsub_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ss) | FMA | immintrin.h | `__m128 _mm_fnmsub_ss (__m128, __m128, __m128);` | +| `_mm_frcz_pd` | XOP | ammintrin.h | `__m128d _mm_frcz_pd(__m128d);` | +| `_mm_frcz_ps` | XOP | ammintrin.h | `__m128 _mm_frcz_ps(__m128);` | +| `_mm_frcz_sd` | XOP | ammintrin.h | `__m128d _mm_frcz_sd(__m128d, __m128d);` | +| `_mm_frcz_ss` | XOP | ammintrin.h | `__m128 _mm_frcz_ss(__m128, __m128);` | | [`_mm_getcsr`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_getcsr) | SSE | intrin.h | `unsigned int _mm_getcsr(void);` | | [`_mm_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_epi16) | SSSE3 | intrin.h | `__m128i _mm_hadd_epi16(__m128i, __m128i);` | | [`_mm_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_epi32) | SSSE3 | intrin.h | `__m128i _mm_hadd_epi32(__m128i, __m128i);` | | [`_mm_hadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_pd) | SSE3 | intrin.h | `__m128d _mm_hadd_pd(__m128d, __m128d);` | | [`_mm_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_ps) | SSE3 | intrin.h | `__m128 _mm_hadd_ps(__m128, __m128);` | -| `_mm_haddd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epi16(__m128i);` | -| `_mm_haddd_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epi8(__m128i);` | -| `_mm_haddd_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epu16(__m128i);` | -| `_mm_haddd_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epu8(__m128i);` | -| `_mm_haddq_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi16(__m128i);` | -| `_mm_haddq_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi32(__m128i);` | -| `_mm_haddq_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi8(__m128i);` | -| `_mm_haddq_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu16(__m128i);` | -| `_mm_haddq_epu32` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu32(__m128i);` | -| `_mm_haddq_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu8(__m128i);` | +| `_mm_haddd_epi16` | XOP | ammintrin.h | `__m128i _mm_haddd_epi16(__m128i);` | +| `_mm_haddd_epi8` | XOP | ammintrin.h | `__m128i _mm_haddd_epi8(__m128i);` | +| `_mm_haddd_epu16` | XOP | ammintrin.h | `__m128i _mm_haddd_epu16(__m128i);` | +| `_mm_haddd_epu8` | XOP | ammintrin.h | `__m128i _mm_haddd_epu8(__m128i);` | +| `_mm_haddq_epi16` | XOP | ammintrin.h | `__m128i _mm_haddq_epi16(__m128i);` | +| `_mm_haddq_epi32` | XOP | ammintrin.h | `__m128i _mm_haddq_epi32(__m128i);` | +| `_mm_haddq_epi8` | XOP | ammintrin.h | `__m128i _mm_haddq_epi8(__m128i);` | +| `_mm_haddq_epu16` | XOP | ammintrin.h | `__m128i _mm_haddq_epu16(__m128i);` | +| `_mm_haddq_epu32` | XOP | ammintrin.h | `__m128i _mm_haddq_epu32(__m128i);` | +| `_mm_haddq_epu8` | XOP | ammintrin.h | `__m128i _mm_haddq_epu8(__m128i);` | | [`_mm_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadds_epi16) | SSSE3 | intrin.h | `__m128i _mm_hadds_epi16(__m128i, __m128i);` | -| `_mm_haddw_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddw_epi8(__m128i);` | -| `_mm_haddw_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddw_epu8(__m128i);` | +| `_mm_haddw_epi8` | XOP | ammintrin.h | `__m128i _mm_haddw_epi8(__m128i);` | +| `_mm_haddw_epu8` | XOP | ammintrin.h | `__m128i _mm_haddw_epu8(__m128i);` | | [`_mm_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_epi16) | SSSE3 | intrin.h | `__m128i _mm_hsub_epi16(__m128i, __m128i);` | | [`_mm_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_epi32) | SSSE3 | intrin.h | `__m128i _mm_hsub_epi32(__m128i, __m128i);` | | [`_mm_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_pd) | SSE3 | intrin.h | `__m128d _mm_hsub_pd(__m128d, __m128d);` | | [`_mm_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_ps) | SSE3 | intrin.h | `__m128 _mm_hsub_ps(__m128, __m128);` | -| `_mm_hsubd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubd_epi16(__m128i);` | -| `_mm_hsubq_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubq_epi32(__m128i);` | +| `_mm_hsubd_epi16` | XOP | ammintrin.h | `__m128i _mm_hsubd_epi16(__m128i);` | +| `_mm_hsubq_epi32` | XOP | ammintrin.h | `__m128i _mm_hsubq_epi32(__m128i);` | | [`_mm_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsubs_epi16) | SSSE3 | intrin.h | `__m128i _mm_hsubs_epi16(__m128i, __m128i);` | -| `_mm_hsubw_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubw_epi8(__m128i);` | -| [`_mm_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_i32gather_epi32(int const *, __m128i, const int);` | -| [`_mm_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_i32gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_i32gather_pd(double const *, __m128i, const int);` | -| [`_mm_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_i32gather_ps(float const *, __m128i, const int);` | -| [`_mm_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_i64gather_epi32(int const *, __m128i, const int);` | -| [`_mm_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_i64gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_i64gather_pd(double const *, __m128i, const int);` | -| [`_mm_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_i64gather_ps(float const *, __m128i, const int);` | +| `_mm_hsubw_epi8` | XOP | ammintrin.h | `__m128i _mm_hsubw_epi8(__m128i);` | +| [`_mm_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_i32gather_epi32(int const *, __m128i, const int);` | +| [`_mm_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_i32gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_pd) | AVX2 | immintrin.h | `__m128d _mm_i32gather_pd(double const *, __m128i, const int);` | +| [`_mm_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_ps) | AVX2 | immintrin.h | `__m128 _mm_i32gather_ps(float const *, __m128i, const int);` | +| [`_mm_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_i64gather_epi32(int const *, __m128i, const int);` | +| [`_mm_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_i64gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_pd) | AVX2 | immintrin.h | `__m128d _mm_i64gather_pd(double const *, __m128i, const int);` | +| [`_mm_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm_i64gather_ps(float const *, __m128i, const int);` | | [`_mm_insert_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi16) | SSE2 | intrin.h | `__m128i _mm_insert_epi16(__m128i, int, int);` | | [`_mm_insert_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi32) | SSE41 | intrin.h | `__m128i _mm_insert_epi32(__m128i, int, const int);` | | [`_mm_insert_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi64) | SSE41 | intrin.h | `__m128i _mm_insert_epi64(__m128i, __int64, const int);` | @@ -527,43 +533,43 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_pd) | SSE2 | intrin.h | `__m128d _mm_loadu_pd(double*);` | | [`_mm_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_ps) | SSE | intrin.h | `__m128 _mm_loadu_ps(float*);` | | [`_mm_loadu_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_si128) | SSE2 | intrin.h | `__m128i _mm_loadu_si128(__m128i*);` | -| `_mm_macc_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_macc_epi16(__m128i, __m128i, __m128i);` | -| `_mm_macc_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macc_epi32(__m128i, __m128i, __m128i);` | -| `_mm_macc_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_macc_pd(__m128d, __m128d, __m128d);` | -| `_mm_macc_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_macc_ps(__m128, __m128, __m128);` | -| `_mm_macc_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_macc_sd(__m128d, __m128d, __m128d);` | -| `_mm_macc_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_macc_ss(__m128, __m128, __m128);` | -| `_mm_maccd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_macchi_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macchi_epi32(__m128i, __m128i, __m128i);` | -| `_mm_macclo_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macclo_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccs_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccs_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maccs_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccs_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccsd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccsd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maccshi_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccshi_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccslo_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccslo_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macc_epi16` | XOP | ammintrin.h | `__m128i _mm_macc_epi16(__m128i, __m128i, __m128i);` | +| `_mm_macc_epi32` | XOP | ammintrin.h | `__m128i _mm_macc_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macc_pd` | FMA4 | ammintrin.h | `__m128d _mm_macc_pd(__m128d, __m128d, __m128d);` | +| `_mm_macc_ps` | FMA4 | ammintrin.h | `__m128 _mm_macc_ps(__m128, __m128, __m128);` | +| `_mm_macc_sd` | FMA4 | ammintrin.h | `__m128d _mm_macc_sd(__m128d, __m128d, __m128d);` | +| `_mm_macc_ss` | FMA4 | ammintrin.h | `__m128 _mm_macc_ss(__m128, __m128, __m128);` | +| `_mm_maccd_epi16` | XOP | ammintrin.h | `__m128i _mm_maccd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_macchi_epi32` | XOP | ammintrin.h | `__m128i _mm_macchi_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macclo_epi32` | XOP | ammintrin.h | `__m128i _mm_macclo_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccs_epi16` | XOP | ammintrin.h | `__m128i _mm_maccs_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maccs_epi32` | XOP | ammintrin.h | `__m128i _mm_maccs_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccsd_epi16` | XOP | ammintrin.h | `__m128i _mm_maccsd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maccshi_epi32` | XOP | ammintrin.h | `__m128i _mm_maccshi_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccslo_epi32` | XOP | ammintrin.h | `__m128i _mm_maccslo_epi32(__m128i, __m128i, __m128i);` | | [`_mm_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_madd_epi16) | SSE2 | intrin.h | `__m128i _mm_madd_epi16(__m128i, __m128i);` | -| `_mm_maddd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maddd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maddsd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maddsd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maddsub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_maddsub_pd(__m128d, __m128d, __m128d);` | -| `_mm_maddsub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_maddsub_ps(__m128, __m128, __m128);` | +| `_mm_maddd_epi16` | XOP | ammintrin.h | `__m128i _mm_maddd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maddsd_epi16` | XOP | ammintrin.h | `__m128i _mm_maddsd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maddsub_pd` | FMA4 | ammintrin.h | `__m128d _mm_maddsub_pd(__m128d, __m128d, __m128d);` | +| `_mm_maddsub_ps` | FMA4 | ammintrin.h | `__m128 _mm_maddsub_ps(__m128, __m128, __m128);` | | [`_mm_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maddubs_epi16) | SSSE3 | intrin.h | `__m128i _mm_maddubs_epi16(__m128i, __m128i);` | -| [`_mm_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i32gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i32gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_mask_i32gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | -| [`_mm_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_mask_i32gather_ps(__m128, float const *, __m128i, __m128, const int);` | -| [`_mm_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i64gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i64gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_mask_i64gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | -| [`_mm_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_mask_i64gather_ps(__m128, float const *, __m128i, __m128, const int);` | -| [`_mm_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_maskload_epi32(int const *, __m128i);` | -| [`_mm_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_maskload_epi64(__int64 const *, __m128i);` | -| [`_mm_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_pd) | AVX \[2] | immintrin.h | `__m128d _mm_maskload_pd(double const *, __m128i);` | -| [`_mm_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_ps) | AVX \[2] | immintrin.h | `__m128 _mm_maskload_ps(float const *, __m128i);` | +| [`_mm_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_mask_i32gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_mask_i32gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_pd) | AVX2 | immintrin.h | `__m128d _mm_mask_i32gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | +| [`_mm_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_ps) | AVX2 | immintrin.h | `__m128 _mm_mask_i32gather_ps(__m128, float const *, __m128i, __m128, const int);` | +| [`_mm_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_mask_i64gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_mask_i64gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_pd) | AVX2 | immintrin.h | `__m128d _mm_mask_i64gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | +| [`_mm_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm_mask_i64gather_ps(__m128, float const *, __m128i, __m128, const int);` | +| [`_mm_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi32) | AVX2 | immintrin.h | `__m128i _mm_maskload_epi32(int const *, __m128i);` | +| [`_mm_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi64) | AVX2 | immintrin.h | `__m128i _mm_maskload_epi64(__int64 const *, __m128i);` | +| [`_mm_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_pd) | AVX | immintrin.h | `__m128d _mm_maskload_pd(double const *, __m128i);` | +| [`_mm_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_ps) | AVX | immintrin.h | `__m128 _mm_maskload_ps(float const *, __m128i);` | | [`_mm_maskmoveu_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskmoveu_si128) | SSE2 | intrin.h | `void _mm_maskmoveu_si128(__m128i, __m128i, char*);` | -| [`_mm_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi32) | AVX2 \[2] | immintrin.h | `void _mm_maskstore_epi32(int *, __m128i, __m128i);` | -| [`_mm_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi64) | AVX2 \[2] | immintrin.h | `void _mm_maskstore_epi64(__int64 *, __m128i, __m128i);` | -| [`_mm_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_pd) | AVX \[2] | immintrin.h | `void _mm_maskstore_pd(double *, __m128i, __m128d);` | -| [`_mm_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_ps) | AVX \[2] | immintrin.h | `void _mm_maskstore_ps(float *, __m128i, __m128);` | +| [`_mm_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi32) | AVX2 | immintrin.h | `void _mm_maskstore_epi32(int *, __m128i, __m128i);` | +| [`_mm_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi64) | AVX2 | immintrin.h | `void _mm_maskstore_epi64(__int64 *, __m128i, __m128i);` | +| [`_mm_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_pd) | AVX | immintrin.h | `void _mm_maskstore_pd(double *, __m128i, __m128d);` | +| [`_mm_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_ps) | AVX | immintrin.h | `void _mm_maskstore_ps(float *, __m128i, __m128);` | | [`_mm_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi16) | SSE2 | intrin.h | `__m128i _mm_max_epi16(__m128i, __m128i);` | | [`_mm_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi32) | SSE41 | intrin.h | `__m128i _mm_max_epi32(__m128i, __m128i);` | | [`_mm_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi8) | SSE41 | intrin.h | `__m128i _mm_max_epi8 (__m128i, __m128i);` | @@ -599,12 +605,12 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_movemask_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_movemask_pd) | SSE2 | intrin.h | `int _mm_movemask_pd(__m128d);` | | [`_mm_movemask_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_movemask_ps) | SSE | intrin.h | `int _mm_movemask_ps(__m128);` | | [`_mm_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mpsadbw_epu8) | SSE41 | intrin.h | `__m128i _mm_mpsadbw_epu8(__m128i, __m128i, const int);` | -| `_mm_msub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msub_pd(__m128d, __m128d, __m128d);` | -| `_mm_msub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msub_ps(__m128, __m128, __m128);` | -| `_mm_msub_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msub_sd(__m128d, __m128d, __m128d);` | -| `_mm_msub_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msub_ss(__m128, __m128, __m128);` | -| `_mm_msubadd_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msubadd_pd(__m128d, __m128d, __m128d);` | -| `_mm_msubadd_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msubadd_ps(__m128, __m128, __m128);` | +| `_mm_msub_pd` | FMA4 | ammintrin.h | `__m128d _mm_msub_pd(__m128d, __m128d, __m128d);` | +| `_mm_msub_ps` | FMA4 | ammintrin.h | `__m128 _mm_msub_ps(__m128, __m128, __m128);` | +| `_mm_msub_sd` | FMA4 | ammintrin.h | `__m128d _mm_msub_sd(__m128d, __m128d, __m128d);` | +| `_mm_msub_ss` | FMA4 | ammintrin.h | `__m128 _mm_msub_ss(__m128, __m128, __m128);` | +| `_mm_msubadd_pd` | FMA4 | ammintrin.h | `__m128d _mm_msubadd_pd(__m128d, __m128d, __m128d);` | +| `_mm_msubadd_ps` | FMA4 | ammintrin.h | `__m128 _mm_msubadd_ps(__m128, __m128, __m128);` | | [`_mm_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_epi32) | SSE41 | intrin.h | `__m128i _mm_mul_epi32(__m128i, __m128i);` | | [`_mm_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_epu32) | SSE2 | intrin.h | `__m128i _mm_mul_epu32(__m128i, __m128i);` | | [`_mm_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_pd) | SSE2 | intrin.h | `__m128d _mm_mul_pd(__m128d, __m128d);` | @@ -617,14 +623,14 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_epi16) | SSE2 | intrin.h | `__m128i _mm_mullo_epi16(__m128i, __m128i);` | | [`_mm_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_epi32) | SSE41 | intrin.h | `__m128i _mm_mullo_epi32(__m128i, __m128i);` | | [`_mm_mwait`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mwait) | SSE3 | intrin.h | `void _mm_mwait(unsigned int, unsigned int);` | -| `_mm_nmacc_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmacc_pd(__m128d, __m128d, __m128d);` | -| `_mm_nmacc_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmacc_ps(__m128, __m128, __m128);` | -| `_mm_nmacc_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmacc_sd(__m128d, __m128d, __m128d);` | -| `_mm_nmacc_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmacc_ss(__m128, __m128, __m128);` | -| `_mm_nmsub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmsub_pd(__m128d, __m128d, __m128d);` | -| `_mm_nmsub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmsub_ps(__m128, __m128, __m128);` | -| `_mm_nmsub_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmsub_sd(__m128d, __m128d, __m128d);` | -| `_mm_nmsub_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmsub_ss(__m128, __m128, __m128);` | +| `_mm_nmacc_pd` | FMA4 | ammintrin.h | `__m128d _mm_nmacc_pd(__m128d, __m128d, __m128d);` | +| `_mm_nmacc_ps` | FMA4 | ammintrin.h | `__m128 _mm_nmacc_ps(__m128, __m128, __m128);` | +| `_mm_nmacc_sd` | FMA4 | ammintrin.h | `__m128d _mm_nmacc_sd(__m128d, __m128d, __m128d);` | +| `_mm_nmacc_ss` | FMA4 | ammintrin.h | `__m128 _mm_nmacc_ss(__m128, __m128, __m128);` | +| `_mm_nmsub_pd` | FMA4 | ammintrin.h | `__m128d _mm_nmsub_pd(__m128d, __m128d, __m128d);` | +| `_mm_nmsub_ps` | FMA4 | ammintrin.h | `__m128 _mm_nmsub_ps(__m128, __m128, __m128);` | +| `_mm_nmsub_sd` | FMA4 | ammintrin.h | `__m128d _mm_nmsub_sd(__m128d, __m128d, __m128d);` | +| `_mm_nmsub_ss` | FMA4 | ammintrin.h | `__m128 _mm_nmsub_ss(__m128, __m128, __m128);` | | [`_mm_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_pd) | SSE2 | intrin.h | `__m128d _mm_or_pd(__m128d, __m128d);` | | [`_mm_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_ps) | SSE | intrin.h | `__m128 _mm_or_ps(__m128, __m128);` | | [`_mm_or_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_si128) | SSE2 | intrin.h | `__m128i _mm_or_si128(__m128i, __m128i);` | @@ -633,26 +639,26 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packus_epi16) | SSE2 | intrin.h | `__m128i _mm_packus_epi16(__m128i, __m128i);` | | [`_mm_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packus_epi32) | SSE41 | intrin.h | `__m128i _mm_packus_epi32(__m128i, __m128i);` | | [`_mm_pause`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_pause) | SSE2 | intrin.h | `void _mm_pause(void);` | -| `_mm_perm_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_perm_epi8(__m128i, __m128i, __m128i);` | -| [`_mm_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_pd) | AVX \[2] | immintrin.h | `__m128d _mm_permute_pd(__m128d, int);` | -| [`_mm_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_ps) | AVX \[2] | immintrin.h | `__m128 _mm_permute_ps(__m128, int);` | -| `_mm_permute2_pd` | XOP \[1] | ammintrin.h | `__m128d _mm_permute2_pd(__m128d, __m128d, __m128i, int);` | -| `_mm_permute2_ps` | XOP \[1] | ammintrin.h | `__m128 _mm_permute2_ps(__m128, __m128, __m128i, int);` | -| [`_mm_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_pd) | AVX \[2] | immintrin.h | `__m128d _mm_permutevar_pd(__m128d, __m128i);` | -| [`_mm_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_ps) | AVX \[2] | immintrin.h | `__m128 _mm_permutevar_ps(__m128, __m128i);` | +| `_mm_perm_epi8` | XOP | ammintrin.h | `__m128i _mm_perm_epi8(__m128i, __m128i, __m128i);` | +| [`_mm_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_pd) | AVX | immintrin.h | `__m128d _mm_permute_pd(__m128d, int);` | +| [`_mm_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_ps) | AVX | immintrin.h | `__m128 _mm_permute_ps(__m128, int);` | +| `_mm_permute2_pd` | XOP | ammintrin.h | `__m128d _mm_permute2_pd(__m128d, __m128d, __m128i, int);` | +| `_mm_permute2_ps` | XOP | ammintrin.h | `__m128 _mm_permute2_ps(__m128, __m128, __m128i, int);` | +| [`_mm_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_pd) | AVX | immintrin.h | `__m128d _mm_permutevar_pd(__m128d, __m128i);` | +| [`_mm_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_ps) | AVX | immintrin.h | `__m128 _mm_permutevar_ps(__m128, __m128i);` | | [`_mm_popcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_popcnt_u32) | POPCNT | intrin.h | `int _mm_popcnt_u32(unsigned int);` | | [`_mm_popcnt_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_popcnt_u64) | POPCNT | intrin.h | `__int64 _mm_popcnt_u64(unsigned __int64);` | | [`_mm_prefetch`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_prefetch) | SSE | intrin.h | `void _mm_prefetch(char*, int);` | | [`_mm_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_rcp_ps) | SSE | intrin.h | `__m128 _mm_rcp_ps(__m128);` | | [`_mm_rcp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_rcp_ss) | SSE | intrin.h | `__m128 _mm_rcp_ss(__m128);` | -| `_mm_rot_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, __m128i);` | -| `_mm_rot_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, __m128i);` | -| `_mm_rot_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, __m128i);` | -| `_mm_rot_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, __m128i);` | -| `_mm_roti_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, int);` | -| `_mm_roti_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, int);` | -| `_mm_roti_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, int);` | -| `_mm_roti_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, int);` | +| `_mm_rot_epi16` | XOP | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, __m128i);` | +| `_mm_rot_epi32` | XOP | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, __m128i);` | +| `_mm_rot_epi64` | XOP | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, __m128i);` | +| `_mm_rot_epi8` | XOP | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, __m128i);` | +| `_mm_roti_epi16` | XOP | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, int);` | +| `_mm_roti_epi32` | XOP | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, int);` | +| `_mm_roti_epi64` | XOP | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, int);` | +| `_mm_roti_epi8` | XOP | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, int);` | | [`_mm_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_pd) | SSE41 | intrin.h | `__m128d _mm_round_pd(__m128d, const int);` | | [`_mm_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_ps) | SSE41 | intrin.h | `__m128 _mm_round_ps(__m128, const int);` | | [`_mm_round_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_sd) | SSE41 | intrin.h | `__m128d _mm_round_sd(__m128d, __m128d, const int);` | @@ -685,14 +691,14 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_setzero_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_setzero_ps) | SSE | intrin.h | `__m128 _mm_setzero_ps(void);` | | [`_mm_setzero_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_setzero_si128) | SSE2 | intrin.h | `__m128i _mm_setzero_si128(void);` | | [`_mm_sfence`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence) | SSE | intrin.h | `void _mm_sfence(void);` | -| `_mm_sha_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi16(__m128i, __m128i);` | -| `_mm_sha_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi32(__m128i, __m128i);` | -| `_mm_sha_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi64(__m128i, __m128i);` | -| `_mm_sha_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi8(__m128i, __m128i);` | -| `_mm_shl_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi16(__m128i, __m128i);` | -| `_mm_shl_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi32(__m128i, __m128i);` | -| `_mm_shl_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi64(__m128i, __m128i);` | -| `_mm_shl_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi8(__m128i, __m128i);` | +| `_mm_sha_epi16` | XOP | ammintrin.h | `__m128i _mm_sha_epi16(__m128i, __m128i);` | +| `_mm_sha_epi32` | XOP | ammintrin.h | `__m128i _mm_sha_epi32(__m128i, __m128i);` | +| `_mm_sha_epi64` | XOP | ammintrin.h | `__m128i _mm_sha_epi64(__m128i, __m128i);` | +| `_mm_sha_epi8` | XOP | ammintrin.h | `__m128i _mm_sha_epi8(__m128i, __m128i);` | +| `_mm_shl_epi16` | XOP | ammintrin.h | `__m128i _mm_shl_epi16(__m128i, __m128i);` | +| `_mm_shl_epi32` | XOP | ammintrin.h | `__m128i _mm_shl_epi32(__m128i, __m128i);` | +| `_mm_shl_epi64` | XOP | ammintrin.h | `__m128i _mm_shl_epi64(__m128i, __m128i);` | +| `_mm_shl_epi8` | XOP | ammintrin.h | `__m128i _mm_shl_epi8(__m128i, __m128i);` | | [`_mm_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_epi32) | SSE2 | intrin.h | `__m128i _mm_shuffle_epi32(__m128i, int);` | | [`_mm_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_epi8) | SSSE3 | intrin.h | `__m128i _mm_shuffle_epi8(__m128i, __m128i);` | | [`_mm_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_pd) | SSE2 | intrin.h | `__m128d _mm_shuffle_pd(__m128d, __m128d, int);` | @@ -709,8 +715,8 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_epi32) | SSE2 | intrin.h | `__m128i _mm_slli_epi32(__m128i, int);` | | [`_mm_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_epi64) | SSE2 | intrin.h | `__m128i _mm_slli_epi64(__m128i, int);` | | [`_mm_slli_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_si128) | SSE2 | intrin.h | `__m128i _mm_slli_si128(__m128i, int);` | -| [`_mm_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_sllv_epi32(__m128i, __m128i);` | -| [`_mm_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_sllv_epi64(__m128i, __m128i);` | +| [`_mm_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi32) | AVX2 | immintrin.h | `__m128i _mm_sllv_epi32(__m128i, __m128i);` | +| [`_mm_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi64) | AVX2 | immintrin.h | `__m128i _mm_sllv_epi64(__m128i, __m128i);` | | [`_mm_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_pd) | SSE2 | intrin.h | `__m128d _mm_sqrt_pd(__m128d);` | | [`_mm_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_ps) | SSE | intrin.h | `__m128 _mm_sqrt_ps(__m128);` | | [`_mm_sqrt_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_sd) | SSE2 | intrin.h | `__m128d _mm_sqrt_sd(__m128d, __m128d);` | @@ -719,7 +725,7 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_epi32) | SSE2 | intrin.h | `__m128i _mm_sra_epi32(__m128i, __m128i);` | | [`_mm_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_epi16) | SSE2 | intrin.h | `__m128i _mm_srai_epi16(__m128i, int);` | | [`_mm_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_epi32) | SSE2 | intrin.h | `__m128i _mm_srai_epi32(__m128i, int);` | -| [`_mm_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srav_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_srav_epi32(__m128i, __m128i);` | +| [`_mm_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srav_epi32) | AVX2 | immintrin.h | `__m128i _mm_srav_epi32(__m128i, __m128i);` | | [`_mm_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi16) | SSE2 | intrin.h | `__m128i _mm_srl_epi16(__m128i, __m128i);` | | [`_mm_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi32) | SSE2 | intrin.h | `__m128i _mm_srl_epi32(__m128i, __m128i);` | | [`_mm_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi64) | SSE2 | intrin.h | `__m128i _mm_srl_epi64(__m128i, __m128i);` | @@ -727,8 +733,8 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_epi32) | SSE2 | intrin.h | `__m128i _mm_srli_epi32(__m128i, int);` | | [`_mm_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_epi64) | SSE2 | intrin.h | `__m128i _mm_srli_epi64(__m128i, int);` | | [`_mm_srli_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_si128) | SSE2 | intrin.h | `__m128i _mm_srli_si128(__m128i, int);` | -| [`_mm_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_srlv_epi32(__m128i, __m128i);` | -| [`_mm_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_srlv_epi64(__m128i, __m128i);` | +| [`_mm_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi32) | AVX2 | immintrin.h | `__m128i _mm_srlv_epi32(__m128i, __m128i);` | +| [`_mm_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi64) | AVX2 | immintrin.h | `__m128i _mm_srlv_epi64(__m128i, __m128i);` | | [`_mm_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_pd) | SSE2 | intrin.h | `void _mm_store_pd(double*, __m128d);` | | [`_mm_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ps) | SSE | intrin.h | `void _mm_store_ps(float*, __m128);` | | [`_mm_store_ps1`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ps1) | SSE | intrin.h | `void _mm_store_ps1(float*, __m128);` | @@ -766,14 +772,14 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epi8) | SSE2 | intrin.h | `__m128i _mm_subs_epi8(__m128i, __m128i);` | | [`_mm_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epu16) | SSE2 | intrin.h | `__m128i _mm_subs_epu16(__m128i, __m128i);` | | [`_mm_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epu8) | SSE2 | intrin.h | `__m128i _mm_subs_epu8(__m128i, __m128i);` | -| [`_mm_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_pd) | AVX \[2] | immintrin.h | `int _mm_testc_pd(__m128d, __m128d);` | -| [`_mm_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_ps) | AVX \[2] | immintrin.h | `int _mm_testc_ps(__m128, __m128);` | +| [`_mm_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_pd) | AVX | immintrin.h | `int _mm_testc_pd(__m128d, __m128d);` | +| [`_mm_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_ps) | AVX | immintrin.h | `int _mm_testc_ps(__m128, __m128);` | | [`_mm_testc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_si128) | SSE41 | intrin.h | `int _mm_testc_si128(__m128i, __m128i);` | -| [`_mm_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_pd) | AVX \[2] | immintrin.h | `int _mm_testnzc_pd(__m128d, __m128d);` | -| [`_mm_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_ps) | AVX \[2] | immintrin.h | `int _mm_testnzc_ps(__m128, __m128);` | +| [`_mm_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_pd) | AVX | immintrin.h | `int _mm_testnzc_pd(__m128d, __m128d);` | +| [`_mm_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_ps) | AVX | immintrin.h | `int _mm_testnzc_ps(__m128, __m128);` | | [`_mm_testnzc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_si128) | SSE41 | intrin.h | `int _mm_testnzc_si128(__m128i, __m128i);` | -| [`_mm_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_pd) | AVX \[2] | immintrin.h | `int _mm_testz_pd(__m128d, __m128d);` | -| [`_mm_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_ps) | AVX \[2] | immintrin.h | `int _mm_testz_ps(__m128, __m128);` | +| [`_mm_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_pd) | AVX | immintrin.h | `int _mm_testz_pd(__m128d, __m128d);` | +| [`_mm_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_ps) | AVX | immintrin.h | `int _mm_testz_ps(__m128, __m128);` | | [`_mm_testz_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_si128) | SSE41 | intrin.h | `int _mm_testz_si128(__m128i, __m128i);` | | [`_mm_ucomieq_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_ucomieq_sd) | SSE2 | intrin.h | `int _mm_ucomieq_sd(__m128d, __m128d);` | | [`_mm_ucomieq_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_ucomieq_ss) | SSE | intrin.h | `int _mm_ucomieq_ss(__m128, __m128);` | @@ -802,340 +808,340 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_pd) | SSE2 | intrin.h | `__m128d _mm_xor_pd(__m128d, __m128d);` | | [`_mm_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_ps) | SSE | intrin.h | `__m128 _mm_xor_ps(__m128, __m128);` | | [`_mm_xor_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_si128) | SSE2 | intrin.h | `__m128i _mm_xor_si128(__m128i, __m128i);` | -| [`_mm256_abs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi16(__m256i);` | -| [`_mm256_abs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi32(__m256i);` | -| [`_mm256_abs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi8(__m256i);` | -| [`_mm256_add_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi16(__m256i, __m256i);` | -| [`_mm256_add_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi32(__m256i, __m256i);` | -| [`_mm256_add_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi64(__m256i, __m256i);` | -| [`_mm256_add_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi8(__m256i, __m256i);` | -| [`_mm256_add_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_add_pd(__m256d, __m256d);` | -| [`_mm256_add_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_add_ps(__m256, __m256);` | -| [`_mm256_adds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epi16(__m256i, __m256i);` | -| [`_mm256_adds_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epi8(__m256i, __m256i);` | -| [`_mm256_adds_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epu16(__m256i, __m256i);` | -| [`_mm256_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epu8(__m256i, __m256i);` | -| [`_mm256_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_addsub_pd(__m256d, __m256d);` | -| [`_mm256_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_addsub_ps(__m256, __m256);` | -| [`_mm256_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_alignr_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_alignr_epi8(__m256i, __m256i, const int);` | -| [`_mm256_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_and_pd(__m256d, __m256d);` | -| [`_mm256_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_and_ps(__m256, __m256);` | -| [`_mm256_and_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_and_si256(__m256i, __m256i);` | -| [`_mm256_andnot_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_andnot_pd(__m256d, __m256d);` | -| [`_mm256_andnot_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_andnot_ps(__m256, __m256);` | -| [`_mm256_andnot_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_andnot_si256(__m256i, __m256i);` | -| [`_mm256_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_avg_epu16(__m256i, __m256i);` | -| [`_mm256_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_avg_epu8(__m256i, __m256i);` | -| [`_mm256_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blend_epi16(__m256i, __m256i, const int);` | -| [`_mm256_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blend_epi32(__m256i, __m256i, const int);` | -| [`_mm256_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_blend_pd(__m256d, __m256d, const int);` | -| [`_mm256_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_blend_ps(__m256, __m256, const int);` | -| [`_mm256_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blendv_epi8(__m256i, __m256i, __m256i);` | -| [`_mm256_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_blendv_pd(__m256d, __m256d, __m256d);` | -| [`_mm256_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_blendv_ps(__m256, __m256, __m256);` | -| [`_mm256_broadcast_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_broadcast_pd(__m128d const *);` | -| [`_mm256_broadcast_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_broadcast_ps(__m128 const *);` | -| [`_mm256_broadcast_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_sd) | AVX \[2] | immintrin.h | `__m256d _mm256_broadcast_sd(double const *);` | -| [`_mm256_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ss) | AVX \[2] | immintrin.h | `__m256 _mm256_broadcast_ss(float const *);` | -| [`_mm256_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastb_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastb_epi8 (__m128i);` | -| [`_mm256_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastd_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastd_epi32(__m128i);` | -| [`_mm256_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastq_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastq_epi64(__m128i);` | -| [`_mm256_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsd_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_broadcastsd_pd(__m128d);` | -| [`_mm256_broadcastsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsi128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastsi128_si256(__m128i);` | -| [`_mm256_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastss_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_broadcastss_ps(__m128);` | -| [`_mm256_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastw_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastw_epi16(__m128i);` | -| [`_mm256_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_castpd_ps(__m256d);` | -| [`_mm256_castpd_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castpd_si256(__m256d);` | -| [`_mm256_castpd128_pd256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd128_pd256) | AVX \[2] | immintrin.h | `__m256d _mm256_castpd128_pd256(__m128d);` | -| [`_mm256_castpd256_pd128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd256_pd128) | AVX \[2] | immintrin.h | `__m128d _mm256_castpd256_pd128(__m256d);` | -| [`_mm256_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_castps_pd(__m256);` | -| [`_mm256_castps_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castps_si256(__m256);` | -| [`_mm256_castps128_ps256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps128_ps256) | AVX \[2] | immintrin.h | `__m256 _mm256_castps128_ps256(__m128);` | -| [`_mm256_castps256_ps128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps256_ps128) | AVX \[2] | immintrin.h | `__m128 _mm256_castps256_ps128(__m256);` | -| [`_mm256_castsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castsi128_si256(__m128i);` | -| [`_mm256_castsi256_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_castsi256_pd(__m256i);` | -| [`_mm256_castsi256_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_castsi256_ps(__m256i);` | -| [`_mm256_castsi256_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_si128) | AVX \[2] | immintrin.h | `__m128i _mm256_castsi256_si128(__m256i);` | -| `_mm256_cmov_si256` | XOP \[1] | ammintrin.h | `__m256i _mm256_cmov_si256(__m256i, __m256i, __m256i);` | -| [`_mm256_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cmp_pd(__m256d, __m256d, const int);` | -| [`_mm256_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_cmp_ps(__m256, __m256, const int);` | -| [`_mm256_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi16(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi32(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi64(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi8(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi16(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi32(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi64(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi8(__m256i, __m256i);` | -| [`_mm256_cvtepi16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi16_epi32(__m128i);` | -| [`_mm256_cvtepi16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi16_epi64(__m128i);` | -| [`_mm256_cvtepi32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi32_epi64(__m128i);` | -| [`_mm256_cvtepi32_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cvtepi32_pd(__m128i);` | -| [`_mm256_cvtepi32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_cvtepi32_ps(__m256i);` | -| [`_mm256_cvtepi8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi16(__m128i);` | -| [`_mm256_cvtepi8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi32(__m128i);` | -| [`_mm256_cvtepi8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi64(__m128i);` | -| [`_mm256_cvtepu16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu16_epi32(__m128i);` | -| [`_mm256_cvtepu16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu16_epi64(__m128i);` | -| [`_mm256_cvtepu32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu32_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu32_epi64(__m128i);` | -| [`_mm256_cvtepu8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi16(__m128i);` | -| [`_mm256_cvtepu8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi32(__m128i);` | -| [`_mm256_cvtepu8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi64(__m128i);` | -| [`_mm256_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_epi32) | AVX \[2] | immintrin.h | `__m128i _mm256_cvtpd_epi32(__m256d);` | -| [`_mm256_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_ps) | AVX \[2] | immintrin.h | `__m128 _mm256_cvtpd_ps(__m256d);` | -| [`_mm256_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtph_ps) | F16C \[2] | immintrin.h | `__m256 _mm256_cvtph_ps(__m128i);` | -| [`_mm256_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_cvtps_epi32(__m256);` | -| [`_mm256_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cvtps_pd(__m128);` | -| [`_mm256_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_ph) | F16C \[2] | immintrin.h | `__m128i _mm256_cvtps_ph(__m256, const int);` | -| [`_mm256_cvttpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttpd_epi32) | AVX \[2] | immintrin.h | `__m128i _mm256_cvttpd_epi32(__m256d);` | -| [`_mm256_cvttps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttps_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_cvttps_epi32(__m256);` | -| [`_mm256_div_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_div_pd(__m256d, __m256d);` | -| [`_mm256_div_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_div_ps(__m256, __m256);` | -| [`_mm256_dp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_dp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_dp_ps(__m256, __m256, const int);` | -| [`_mm256_extractf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_pd) | AVX \[2] | immintrin.h | `__m128d _mm256_extractf128_pd(__m256d, const int);` | -| [`_mm256_extractf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_ps) | AVX \[2] | immintrin.h | `__m128 _mm256_extractf128_ps(__m256, const int);` | -| [`_mm256_extractf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_si256) | AVX \[2] | immintrin.h | `__m128i _mm256_extractf128_si256(__m256i, const int);` | -| [`_mm256_extracti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extracti128_si256) | AVX2 \[2] | immintrin.h | `__m128i _mm256_extracti128_si256(__m256i, int);` | -| [`_mm256_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmaddsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmaddsub_ps (__m256, __m256, __m256);` | -| [`_mm256_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmsub_ps (__m256, __m256, __m256);` | -| [`_mm256_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmsubadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmsubadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fnmadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fnmadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fnmsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fnmsub_ps (__m256, __m256, __m256);` | -| `_mm256_frcz_pd` | XOP \[1] | ammintrin.h | `__m256d _mm256_frcz_pd(__m256d);` | -| `_mm256_frcz_ps` | XOP \[1] | ammintrin.h | `__m256 _mm256_frcz_ps(__m256);` | -| [`_mm256_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadd_epi16(__m256i, __m256i);` | -| [`_mm256_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadd_epi32(__m256i, __m256i);` | -| [`_mm256_hadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_hadd_pd(__m256d, __m256d);` | -| [`_mm256_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_hadd_ps(__m256, __m256);` | -| [`_mm256_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadds_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadds_epi16(__m256i, __m256i);` | -| [`_mm256_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsub_epi16(__m256i, __m256i);` | -| [`_mm256_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsub_epi32(__m256i, __m256i);` | -| [`_mm256_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_hsub_pd(__m256d, __m256d);` | -| [`_mm256_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_hsub_ps(__m256, __m256);` | -| [`_mm256_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsubs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsubs_epi16(__m256i, __m256i);` | -| [`_mm256_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i32gather_epi32(int const *, __m256i, const int);` | -| [`_mm256_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i32gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm256_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_i32gather_pd(double const *, __m128i, const int);` | -| [`_mm256_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_i32gather_ps(float const *, __m256i, const int);` | -| [`_mm256_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i64gather_epi32(int const *, __m256i, const int);` | -| [`_mm256_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i64gather_epi64(__int64 const *, __m256i, const int);` | -| [`_mm256_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_i64gather_pd(double const *, __m256i, const int);` | -| [`_mm256_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm256_i64gather_ps(float const *, __m256i, const int);` | -| [`_mm256_insertf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_insertf128_pd(__m256d, __m128d, int);` | -| [`_mm256_insertf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_insertf128_ps(__m256, __m128, int);` | -| [`_mm256_insertf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_insertf128_si256(__m256i, __m128i, int);` | -| [`_mm256_inserti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_inserti128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_inserti128_si256(__m256i, __m128i, int);` | -| [`_mm256_lddqu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_lddqu_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_lddqu_si256(__m256i *);` | -| [`_mm256_load_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_load_pd(double const *);` | -| [`_mm256_load_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_load_ps(float const *);` | -| [`_mm256_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_load_si256(__m256i *);` | -| [`_mm256_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_loadu_pd(double const *);` | -| [`_mm256_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_loadu_ps(float const *);` | -| [`_mm256_loadu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_loadu_si256(__m256i *);` | -| `_mm256_macc_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_macc_pd(__m256d, __m256d, __m256d);` | -| `_mm256_macc_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_macc_ps(__m256, __m256, __m256);` | -| [`_mm256_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_madd_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_madd_epi16(__m256i, __m256i);` | -| `_mm256_maddsub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_maddsub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_maddsub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_maddsub_ps(__m256, __m256, __m256);` | -| [`_mm256_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maddubs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maddubs_epi16(__m256i, __m256i);` | -| [`_mm256_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i32gather_epi32(__m256i, int const *, __m256i, __m256i, const int);` | -| [`_mm256_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i32gather_epi64(__m256i, __int64 const *, __m128i, __m256i, const int);` | -| [`_mm256_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_mask_i32gather_pd(__m256d, double const *, __m128i, __m256d, const int);` | -| [`_mm256_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_mask_i32gather_ps(__m256, float const *, __m256i, __m256, const int);` | -| [`_mm256_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm256_mask_i64gather_epi32(__m128i, int const *, __m256i, __m128i, const int);` | -| [`_mm256_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i64gather_epi64(__m256i, __int64 const *, __m256i, __m256i, const int);` | -| [`_mm256_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_mask_i64gather_pd(__m256d, double const *, __m256i, __m256d, const int);` | -| [`_mm256_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm256_mask_i64gather_ps(__m128, float const *, __m256i, __m128, const int);` | -| [`_mm256_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maskload_epi32(int const *, __m256i);` | -| [`_mm256_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maskload_epi64(__int64 const *, __m256i);` | -| [`_mm256_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_maskload_pd(double const *, __m256i);` | -| [`_mm256_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_maskload_ps(float const *, __m256i);` | -| [`_mm256_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi32) | AVX2 \[2] | immintrin.h | `void _mm256_maskstore_epi32(int *, __m256i, __m256i);` | -| [`_mm256_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi64) | AVX2 \[2] | immintrin.h | `void _mm256_maskstore_epi64(__int64 *, __m256i, __m256i);` | -| [`_mm256_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_pd) | AVX \[2] | immintrin.h | `void _mm256_maskstore_pd(double *, __m256i, __m256d);` | -| [`_mm256_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_ps) | AVX \[2] | immintrin.h | `void _mm256_maskstore_ps(float *, __m256i, __m256);` | -| [`_mm256_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi16(__m256i, __m256i);` | -| [`_mm256_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi32(__m256i, __m256i);` | -| [`_mm256_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi8(__m256i, __m256i);` | -| [`_mm256_max_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu16(__m256i, __m256i);` | -| [`_mm256_max_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu32(__m256i, __m256i);` | -| [`_mm256_max_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu8(__m256i, __m256i);` | -| [`_mm256_max_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_max_pd(__m256d, __m256d);` | -| [`_mm256_max_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_max_ps(__m256, __m256);` | -| [`_mm256_min_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi16(__m256i, __m256i);` | -| [`_mm256_min_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi32(__m256i, __m256i);` | -| [`_mm256_min_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi8(__m256i, __m256i);` | -| [`_mm256_min_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu16(__m256i, __m256i);` | -| [`_mm256_min_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu32(__m256i, __m256i);` | -| [`_mm256_min_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu8(__m256i, __m256i);` | -| [`_mm256_min_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_min_pd(__m256d, __m256d);` | -| [`_mm256_min_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_min_ps(__m256, __m256);` | -| [`_mm256_movedup_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movedup_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_movedup_pd(__m256d);` | -| [`_mm256_movehdup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movehdup_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_movehdup_ps(__m256);` | -| [`_mm256_moveldup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_moveldup_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_moveldup_ps(__m256);` | -| [`_mm256_movemask_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_epi8) | AVX2 \[2] | immintrin.h | `int _mm256_movemask_epi8(__m256i);` | -| [`_mm256_movemask_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_pd) | AVX \[2] | immintrin.h | `int _mm256_movemask_pd(__m256d);` | -| [`_mm256_movemask_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_ps) | AVX \[2] | immintrin.h | `int _mm256_movemask_ps(__m256);` | -| [`_mm256_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mpsadbw_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mpsadbw_epu8(__m256i, __m256i, const int);` | -| `_mm256_msub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_msub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_msub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_msub_ps(__m256, __m256, __m256);` | -| `_mm256_msubadd_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_msubadd_pd(__m256d, __m256d, __m256d);` | -| `_mm256_msubadd_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_msubadd_ps(__m256, __m256, __m256);` | -| [`_mm256_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mul_epi32(__m256i, __m256i);` | -| [`_mm256_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mul_epu32(__m256i, __m256i);` | -| [`_mm256_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_mul_pd(__m256d, __m256d);` | -| [`_mm256_mul_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_mul_ps(__m256, __m256);` | -| [`_mm256_mulhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhi_epi16(__m256i, __m256i);` | -| [`_mm256_mulhi_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhi_epu16(__m256i, __m256i);` | -| [`_mm256_mulhrs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhrs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhrs_epi16(__m256i, __m256i);` | -| [`_mm256_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mullo_epi16(__m256i, __m256i);` | -| [`_mm256_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mullo_epi32(__m256i, __m256i);` | -| `_mm256_nmacc_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_nmacc_pd(__m256d, __m256d, __m256d);` | -| `_mm256_nmacc_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_nmacc_ps(__m256, __m256, __m256);` | -| `_mm256_nmsub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_nmsub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_nmsub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_nmsub_ps(__m256, __m256, __m256);` | -| [`_mm256_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_or_pd(__m256d, __m256d);` | -| [`_mm256_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_or_ps(__m256, __m256);` | -| [`_mm256_or_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_or_si256(__m256i, __m256i);` | -| [`_mm256_packs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packs_epi16(__m256i, __m256i);` | -| [`_mm256_packs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packs_epi32(__m256i, __m256i);` | -| [`_mm256_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packus_epi16(__m256i, __m256i);` | -| [`_mm256_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packus_epi32(__m256i, __m256i);` | -| [`_mm256_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permute_pd(__m256d, int);` | -| [`_mm256_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permute_ps(__m256, int);` | -| `_mm256_permute2_pd` | XOP \[1] | ammintrin.h | `__m256d _mm256_permute2_pd(__m256d, __m256d, __m256i, int);` | -| `_mm256_permute2_ps` | XOP \[1] | ammintrin.h | `__m256 _mm256_permute2_ps(__m256, __m256, __m256i, int);` | -| [`_mm256_permute2f128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permute2f128_pd(__m256d, __m256d, int);` | -| [`_mm256_permute2f128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permute2f128_ps(__m256, __m256, int);` | -| [`_mm256_permute2f128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_permute2f128_si256(__m256i, __m256i, int);` | -| [`_mm256_permute2x128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2x128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permute2x128_si256(__m256i, __m256i, const int);` | -| [`_mm256_permute4x64_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permute4x64_epi64 (__m256i, const int);` | -| [`_mm256_permute4x64_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_permute4x64_pd(__m256d, const int);` | -| [`_mm256_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permutevar_pd(__m256d, __m256i);` | -| [`_mm256_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permutevar_ps(__m256, __m256i);` | -| [`_mm256_permutevar8x32_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permutevar8x32_epi32(__m256i, __m256i);` | -| [`_mm256_permutevar8x32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_permutevar8x32_ps (__m256, __m256i);` | -| [`_mm256_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rcp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_rcp_ps(__m256);` | -| [`_mm256_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_round_pd(__m256d, int);` | -| [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | -| [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | -| [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | -| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX \[2] | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | -| [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | -| [`_mm256_set_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi64x) | AVX \[2] | immintrin.h | `__m256i _mm256_set_epi64x(long long, long long, long long, long long);` | -| [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX \[2] | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | -| [`_mm256_set_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_set_pd(double, double, double, double);` | -| [`_mm256_set_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_set_ps(float, float, float, float, float, float, float, float);` | -| [`_mm256_set1_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi16) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi16(short);` | -| [`_mm256_set1_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi32(int);` | -| [`_mm256_set1_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi64x) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi64x(long long);` | -| [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi8(char);` | -| [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_set1_pd(double);` | -| [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_set1_ps(float);` | -| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX \[2] | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | -| [`_mm256_setr_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_setr_epi32(int, int, int, int, int, int, int, int);` | -| [`_mm256_setr_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi64x) | AVX \[2] | immintrin.h | `__m256i _mm256_setr_epi64x(long long, long long, long long, long long);` | -| [`_mm256_setr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi8) | AVX \[2] | immintrin.h | `(__m256i _mm256_setr_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | -| [`_mm256_setr_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_setr_pd(double, double, double, double);` | -| [`_mm256_setr_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_setr_ps(float, float, float, float, float, float, float, float);` | -| [`_mm256_setzero_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_setzero_pd(void);` | -| [`_mm256_setzero_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_setzero_ps(void);` | -| [`_mm256_setzero_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_setzero_si256(void);` | -| [`_mm256_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shuffle_epi32(__m256i, const int);` | -| [`_mm256_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shuffle_epi8(__m256i, __m256i);` | -| [`_mm256_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_shuffle_pd(__m256d, __m256d, const int);` | -| [`_mm256_shuffle_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_shuffle_ps(__m256, __m256, const int);` | -| [`_mm256_shufflehi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflehi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shufflehi_epi16(__m256i, const int);` | -| [`_mm256_shufflelo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflelo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shufflelo_epi16(__m256i, const int);` | -| [`_mm256_sign_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi16(__m256i, __m256i);` | -| [`_mm256_sign_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi32(__m256i, __m256i);` | -| [`_mm256_sign_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi8(__m256i, __m256i);` | -| [`_mm256_sll_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi16(__m256i, __m128i);` | -| [`_mm256_sll_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi32(__m256i, __m128i);` | -| [`_mm256_sll_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi64(__m256i, __m128i);` | -| [`_mm256_slli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi16(__m256i, int);` | -| [`_mm256_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi32(__m256i, int);` | -| [`_mm256_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi64(__m256i, int);` | -| [`_mm256_slli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_si256(__m256i, int);` | -| [`_mm256_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sllv_epi32(__m256i, __m256i);` | -| [`_mm256_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sllv_epi64(__m256i, __m256i);` | -| [`_mm256_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_sqrt_pd(__m256d);` | -| [`_mm256_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_sqrt_ps(__m256);` | -| [`_mm256_sra_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sra_epi16(__m256i, __m128i);` | -| [`_mm256_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sra_epi32(__m256i, __m128i);` | -| [`_mm256_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srai_epi16(__m256i, int);` | -| [`_mm256_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srai_epi32(__m256i, int);` | -| [`_mm256_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srav_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srav_epi32(__m256i, __m256i);` | -| [`_mm256_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi16(__m256i, __m128i);` | -| [`_mm256_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi32(__m256i, __m128i);` | -| [`_mm256_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi64(__m256i, __m128i);` | -| [`_mm256_srli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi16(__m256i, int);` | -| [`_mm256_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi32(__m256i, int);` | -| [`_mm256_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi64(__m256i, int);` | -| [`_mm256_srli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_si256(__m256i, int);` | -| [`_mm256_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srlv_epi32(__m256i, __m256i);` | -| [`_mm256_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srlv_epi64(__m256i, __m256i);` | -| [`_mm256_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_pd) | AVX \[2] | immintrin.h | `void _mm256_store_pd(double *, __m256d);` | -| [`_mm256_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_ps) | AVX \[2] | immintrin.h | `void _mm256_store_ps(float *, __m256);` | -| [`_mm256_store_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_si256) | AVX \[2] | immintrin.h | `void _mm256_store_si256(__m256i *, __m256i);` | -| [`_mm256_storeu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_pd) | AVX \[2] | immintrin.h | `void _mm256_storeu_pd(double *, __m256d);` | -| [`_mm256_storeu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_ps) | AVX \[2] | immintrin.h | `void _mm256_storeu_ps(float *, __m256);` | -| [`_mm256_storeu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_si256) | AVX \[2] | immintrin.h | `void _mm256_storeu_si256(__m256i *, __m256i);` | -| [`_mm256_stream_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_load_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_stream_load_si256(__m256i const *);` | -| [`_mm256_stream_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_pd) | AVX \[2] | immintrin.h | `void __mm256_stream_pd(double *, __m256d);` | -| [`_mm256_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_ps) | AVX \[2] | immintrin.h | `void _mm256_stream_ps(float *, __m256);` | -| [`_mm256_stream_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_si256) | AVX \[2] | immintrin.h | `void __mm256_stream_si256(__m256i *, __m256i);` | -| [`_mm256_sub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi16(__m256i, __m256i);` | -| [`_mm256_sub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi32(__m256i, __m256i);` | -| [`_mm256_sub_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi64(__m256i, __m256i);` | -| [`_mm256_sub_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi8(__m256i, __m256i);` | -| [`_mm256_sub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_sub_pd(__m256d, __m256d);` | -| [`_mm256_sub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_sub_ps(__m256, __m256);` | -| [`_mm256_subs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epi16(__m256i, __m256i);` | -| [`_mm256_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epi8(__m256i, __m256i);` | -| [`_mm256_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epu16(__m256i, __m256i);` | -| [`_mm256_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epu8(__m256i, __m256i);` | -| [`_mm256_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_pd) | AVX \[2] | immintrin.h | `int _mm256_testc_pd(__m256d, __m256d);` | -| [`_mm256_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_ps) | AVX \[2] | immintrin.h | `int _mm256_testc_ps(__m256, __m256);` | -| [`_mm256_testc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_si256) | AVX \[2] | immintrin.h | `int _mm256_testc_si256(__m256i, __m256i);` | -| [`_mm256_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_pd) | AVX \[2] | immintrin.h | `int _mm256_testnzc_pd(__m256d, __m256d);` | -| [`_mm256_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_ps) | AVX \[2] | immintrin.h | `int _mm256_testnzc_ps(__m256, __m256);` | -| [`_mm256_testnzc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_si256) | AVX \[2] | immintrin.h | `int _mm256_testnzc_si256(__m256i, __m256i);` | -| [`_mm256_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_pd) | AVX \[2] | immintrin.h | `int _mm256_testz_pd(__m256d, __m256d);` | -| [`_mm256_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_ps) | AVX \[2] | immintrin.h | `int _mm256_testz_ps(__m256, __m256);` | -| [`_mm256_testz_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_si256) | AVX \[2] | immintrin.h | `int _mm256_testz_si256(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi16(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi32(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi64(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi8(__m256i, __m256i);` | -| [`_mm256_unpackhi_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_unpackhi_pd(__m256d, __m256d);` | -| [`_mm256_unpackhi_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_unpackhi_ps(__m256, __m256);` | -| [`_mm256_unpacklo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi16(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi32(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi64(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi8(__m256i, __m256i);` | -| [`_mm256_unpacklo_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_unpacklo_pd(__m256d, __m256d);` | -| [`_mm256_unpacklo_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_unpacklo_ps(__m256, __m256);` | -| [`_mm256_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_xor_pd(__m256d, __m256d);` | -| [`_mm256_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_xor_ps(__m256, __m256);` | -| [`_mm256_xor_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_xor_si256(__m256i, __m256i);` | -| [`_mm256_zeroall`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroall) | AVX \[2] | immintrin.h | `void _mm256_zeroall(void);` | -| [`_mm256_zeroupper`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroupper) | AVX \[2] | immintrin.h | `void _mm256_zeroupper(void);` | +| [`_mm256_abs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi16(__m256i);` | +| [`_mm256_abs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi32) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi32(__m256i);` | +| [`_mm256_abs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi8) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi8(__m256i);` | +| [`_mm256_add_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi16) | AVX2 | immintrin.h | `__m256i _mm256_add_epi16(__m256i, __m256i);` | +| [`_mm256_add_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi32) | AVX2 | immintrin.h | `__m256i _mm256_add_epi32(__m256i, __m256i);` | +| [`_mm256_add_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi64) | AVX2 | immintrin.h | `__m256i _mm256_add_epi64(__m256i, __m256i);` | +| [`_mm256_add_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi8) | AVX2 | immintrin.h | `__m256i _mm256_add_epi8(__m256i, __m256i);` | +| [`_mm256_add_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_pd) | AVX | immintrin.h | `__m256d _mm256_add_pd(__m256d, __m256d);` | +| [`_mm256_add_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_ps) | AVX | immintrin.h | `__m256 _mm256_add_ps(__m256, __m256);` | +| [`_mm256_adds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi16) | AVX2 | immintrin.h | `__m256i _mm256_adds_epi16(__m256i, __m256i);` | +| [`_mm256_adds_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi8) | AVX2 | immintrin.h | `__m256i _mm256_adds_epi8(__m256i, __m256i);` | +| [`_mm256_adds_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu16) | AVX2 | immintrin.h | `__m256i _mm256_adds_epu16(__m256i, __m256i);` | +| [`_mm256_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu8) | AVX2 | immintrin.h | `__m256i _mm256_adds_epu8(__m256i, __m256i);` | +| [`_mm256_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_pd) | AVX | immintrin.h | `__m256d _mm256_addsub_pd(__m256d, __m256d);` | +| [`_mm256_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_ps) | AVX | immintrin.h | `__m256 _mm256_addsub_ps(__m256, __m256);` | +| [`_mm256_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_alignr_epi8) | AVX2 | immintrin.h | `__m256i _mm256_alignr_epi8(__m256i, __m256i, const int);` | +| [`_mm256_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_pd) | AVX | immintrin.h | `__m256d _mm256_and_pd(__m256d, __m256d);` | +| [`_mm256_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_ps) | AVX | immintrin.h | `__m256 _mm256_and_ps(__m256, __m256);` | +| [`_mm256_and_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_si256) | AVX2 | immintrin.h | `__m256i _mm256_and_si256(__m256i, __m256i);` | +| [`_mm256_andnot_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_pd) | AVX | immintrin.h | `__m256d _mm256_andnot_pd(__m256d, __m256d);` | +| [`_mm256_andnot_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_ps) | AVX | immintrin.h | `__m256 _mm256_andnot_ps(__m256, __m256);` | +| [`_mm256_andnot_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_si256) | AVX2 | immintrin.h | `__m256i _mm256_andnot_si256(__m256i, __m256i);` | +| [`_mm256_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu16) | AVX2 | immintrin.h | `__m256i _mm256_avg_epu16(__m256i, __m256i);` | +| [`_mm256_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu8) | AVX2 | immintrin.h | `__m256i _mm256_avg_epu8(__m256i, __m256i);` | +| [`_mm256_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi16) | AVX2 | immintrin.h | `__m256i _mm256_blend_epi16(__m256i, __m256i, const int);` | +| [`_mm256_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi32) | AVX2 | immintrin.h | `__m256i _mm256_blend_epi32(__m256i, __m256i, const int);` | +| [`_mm256_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_pd) | AVX | immintrin.h | `__m256d _mm256_blend_pd(__m256d, __m256d, const int);` | +| [`_mm256_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_ps) | AVX | immintrin.h | `__m256 _mm256_blend_ps(__m256, __m256, const int);` | +| [`_mm256_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_epi8) | AVX2 | immintrin.h | `__m256i _mm256_blendv_epi8(__m256i, __m256i, __m256i);` | +| [`_mm256_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_pd) | AVX | immintrin.h | `__m256d _mm256_blendv_pd(__m256d, __m256d, __m256d);` | +| [`_mm256_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_ps) | AVX | immintrin.h | `__m256 _mm256_blendv_ps(__m256, __m256, __m256);` | +| [`_mm256_broadcast_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_pd) | AVX | immintrin.h | `__m256d _mm256_broadcast_pd(__m128d const *);` | +| [`_mm256_broadcast_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ps) | AVX | immintrin.h | `__m256 _mm256_broadcast_ps(__m128 const *);` | +| [`_mm256_broadcast_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_sd) | AVX | immintrin.h | `__m256d _mm256_broadcast_sd(double const *);` | +| [`_mm256_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ss) | AVX | immintrin.h | `__m256 _mm256_broadcast_ss(float const *);` | +| [`_mm256_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastb_epi8) | AVX2 | immintrin.h | `__m256i _mm256_broadcastb_epi8 (__m128i);` | +| [`_mm256_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastd_epi32) | AVX2 | immintrin.h | `__m256i _mm256_broadcastd_epi32(__m128i);` | +| [`_mm256_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastq_epi64) | AVX2 | immintrin.h | `__m256i _mm256_broadcastq_epi64(__m128i);` | +| [`_mm256_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsd_pd) | AVX2 | immintrin.h | `__m256d _mm256_broadcastsd_pd(__m128d);` | +| [`_mm256_broadcastsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsi128_si256) | AVX2 | immintrin.h | `__m256i _mm256_broadcastsi128_si256(__m128i);` | +| [`_mm256_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastss_ps) | AVX2 | immintrin.h | `__m256 _mm256_broadcastss_ps(__m128);` | +| [`_mm256_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastw_epi16) | AVX2 | immintrin.h | `__m256i _mm256_broadcastw_epi16(__m128i);` | +| [`_mm256_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_ps) | AVX | immintrin.h | `__m256 _mm256_castpd_ps(__m256d);` | +| [`_mm256_castpd_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_si256) | AVX | immintrin.h | `__m256i _mm256_castpd_si256(__m256d);` | +| [`_mm256_castpd128_pd256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd128_pd256) | AVX | immintrin.h | `__m256d _mm256_castpd128_pd256(__m128d);` | +| [`_mm256_castpd256_pd128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd256_pd128) | AVX | immintrin.h | `__m128d _mm256_castpd256_pd128(__m256d);` | +| [`_mm256_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_pd) | AVX | immintrin.h | `__m256d _mm256_castps_pd(__m256);` | +| [`_mm256_castps_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_si256) | AVX | immintrin.h | `__m256i _mm256_castps_si256(__m256);` | +| [`_mm256_castps128_ps256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps128_ps256) | AVX | immintrin.h | `__m256 _mm256_castps128_ps256(__m128);` | +| [`_mm256_castps256_ps128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps256_ps128) | AVX | immintrin.h | `__m128 _mm256_castps256_ps128(__m256);` | +| [`_mm256_castsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi128_si256) | AVX | immintrin.h | `__m256i _mm256_castsi128_si256(__m128i);` | +| [`_mm256_castsi256_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_pd) | AVX | immintrin.h | `__m256d _mm256_castsi256_pd(__m256i);` | +| [`_mm256_castsi256_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_ps) | AVX | immintrin.h | `__m256 _mm256_castsi256_ps(__m256i);` | +| [`_mm256_castsi256_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_si128) | AVX | immintrin.h | `__m128i _mm256_castsi256_si128(__m256i);` | +| `_mm256_cmov_si256` | XOP | ammintrin.h | `__m256i _mm256_cmov_si256(__m256i, __m256i, __m256i);` | +| [`_mm256_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_pd) | AVX | immintrin.h | `__m256d _mm256_cmp_pd(__m256d, __m256d, const int);` | +| [`_mm256_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_ps) | AVX | immintrin.h | `__m256 _mm256_cmp_ps(__m256, __m256, const int);` | +| [`_mm256_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi16(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi32(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi64(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi8) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi8(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi16(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi32(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi64(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi8) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi8(__m256i, __m256i);` | +| [`_mm256_cvtepi16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi16_epi32(__m128i);` | +| [`_mm256_cvtepi16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi16_epi64(__m128i);` | +| [`_mm256_cvtepi32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi32_epi64(__m128i);` | +| [`_mm256_cvtepi32_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_pd) | AVX | immintrin.h | `__m256d _mm256_cvtepi32_pd(__m128i);` | +| [`_mm256_cvtepi32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_ps) | AVX | immintrin.h | `__m256 _mm256_cvtepi32_ps(__m256i);` | +| [`_mm256_cvtepi8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi16(__m128i);` | +| [`_mm256_cvtepi8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi32(__m128i);` | +| [`_mm256_cvtepi8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi64(__m128i);` | +| [`_mm256_cvtepu16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu16_epi32(__m128i);` | +| [`_mm256_cvtepu16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu16_epi64(__m128i);` | +| [`_mm256_cvtepu32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu32_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu32_epi64(__m128i);` | +| [`_mm256_cvtepu8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi16(__m128i);` | +| [`_mm256_cvtepu8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi32(__m128i);` | +| [`_mm256_cvtepu8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi64(__m128i);` | +| [`_mm256_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_epi32) | AVX | immintrin.h | `__m128i _mm256_cvtpd_epi32(__m256d);` | +| [`_mm256_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_ps) | AVX | immintrin.h | `__m128 _mm256_cvtpd_ps(__m256d);` | +| [`_mm256_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtph_ps) | F16C | immintrin.h | `__m256 _mm256_cvtph_ps(__m128i);` | +| [`_mm256_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_epi32) | AVX | immintrin.h | `__m256i _mm256_cvtps_epi32(__m256);` | +| [`_mm256_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_pd) | AVX | immintrin.h | `__m256d _mm256_cvtps_pd(__m128);` | +| [`_mm256_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_ph) | F16C | immintrin.h | `__m128i _mm256_cvtps_ph(__m256, const int);` | +| [`_mm256_cvttpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttpd_epi32) | AVX | immintrin.h | `__m128i _mm256_cvttpd_epi32(__m256d);` | +| [`_mm256_cvttps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttps_epi32) | AVX | immintrin.h | `__m256i _mm256_cvttps_epi32(__m256);` | +| [`_mm256_div_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_pd) | AVX | immintrin.h | `__m256d _mm256_div_pd(__m256d, __m256d);` | +| [`_mm256_div_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_ps) | AVX | immintrin.h | `__m256 _mm256_div_ps(__m256, __m256);` | +| [`_mm256_dp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_dp_ps) | AVX | immintrin.h | `__m256 _mm256_dp_ps(__m256, __m256, const int);` | +| [`_mm256_extractf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_pd) | AVX | immintrin.h | `__m128d _mm256_extractf128_pd(__m256d, const int);` | +| [`_mm256_extractf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_ps) | AVX | immintrin.h | `__m128 _mm256_extractf128_ps(__m256, const int);` | +| [`_mm256_extractf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_si256) | AVX | immintrin.h | `__m128i _mm256_extractf128_si256(__m256i, const int);` | +| [`_mm256_extracti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extracti128_si256) | AVX2 | immintrin.h | `__m128i _mm256_extracti128_si256(__m256i, int);` | +| [`_mm256_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_pd) | FMA | immintrin.h | `__m256d _mm256_fmadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_ps) | FMA | immintrin.h | `__m256 _mm256_fmadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_pd) | FMA | immintrin.h | `__m256d _mm256_fmaddsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_ps) | FMA | immintrin.h | `__m256 _mm256_fmaddsub_ps (__m256, __m256, __m256);` | +| [`_mm256_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_pd) | FMA | immintrin.h | `__m256d _mm256_fmsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_ps) | FMA | immintrin.h | `__m256 _mm256_fmsub_ps (__m256, __m256, __m256);` | +| [`_mm256_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_pd) | FMA | immintrin.h | `__m256d _mm256_fmsubadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_ps) | FMA | immintrin.h | `__m256 _mm256_fmsubadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_pd) | FMA | immintrin.h | `__m256d _mm256_fnmadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_ps) | FMA | immintrin.h | `__m256 _mm256_fnmadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_pd) | FMA | immintrin.h | `__m256d _mm256_fnmsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_ps) | FMA | immintrin.h | `__m256 _mm256_fnmsub_ps (__m256, __m256, __m256);` | +| `_mm256_frcz_pd` | XOP | ammintrin.h | `__m256d _mm256_frcz_pd(__m256d);` | +| `_mm256_frcz_ps` | XOP | ammintrin.h | `__m256 _mm256_frcz_ps(__m256);` | +| [`_mm256_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hadd_epi16(__m256i, __m256i);` | +| [`_mm256_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi32) | AVX2 | immintrin.h | `__m256i _mm256_hadd_epi32(__m256i, __m256i);` | +| [`_mm256_hadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_pd) | AVX | immintrin.h | `__m256d _mm256_hadd_pd(__m256d, __m256d);` | +| [`_mm256_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_ps) | AVX | immintrin.h | `__m256 _mm256_hadd_ps(__m256, __m256);` | +| [`_mm256_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadds_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hadds_epi16(__m256i, __m256i);` | +| [`_mm256_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hsub_epi16(__m256i, __m256i);` | +| [`_mm256_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi32) | AVX2 | immintrin.h | `__m256i _mm256_hsub_epi32(__m256i, __m256i);` | +| [`_mm256_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_pd) | AVX | immintrin.h | `__m256d _mm256_hsub_pd(__m256d, __m256d);` | +| [`_mm256_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_ps) | AVX | immintrin.h | `__m256 _mm256_hsub_ps(__m256, __m256);` | +| [`_mm256_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsubs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hsubs_epi16(__m256i, __m256i);` | +| [`_mm256_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_i32gather_epi32(int const *, __m256i, const int);` | +| [`_mm256_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_i32gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm256_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_i32gather_pd(double const *, __m128i, const int);` | +| [`_mm256_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_ps) | AVX2 | immintrin.h | `__m256 _mm256_i32gather_ps(float const *, __m256i, const int);` | +| [`_mm256_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_i64gather_epi32(int const *, __m256i, const int);` | +| [`_mm256_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_i64gather_epi64(__int64 const *, __m256i, const int);` | +| [`_mm256_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_i64gather_pd(double const *, __m256i, const int);` | +| [`_mm256_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm256_i64gather_ps(float const *, __m256i, const int);` | +| [`_mm256_insertf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_pd) | AVX | immintrin.h | `__m256d _mm256_insertf128_pd(__m256d, __m128d, int);` | +| [`_mm256_insertf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_ps) | AVX | immintrin.h | `__m256 _mm256_insertf128_ps(__m256, __m128, int);` | +| [`_mm256_insertf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_si256) | AVX | immintrin.h | `__m256i _mm256_insertf128_si256(__m256i, __m128i, int);` | +| [`_mm256_inserti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_inserti128_si256) | AVX2 | immintrin.h | `__m256i _mm256_inserti128_si256(__m256i, __m128i, int);` | +| [`_mm256_lddqu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_lddqu_si256) | AVX | immintrin.h | `__m256i _mm256_lddqu_si256(__m256i *);` | +| [`_mm256_load_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_pd) | AVX | immintrin.h | `__m256d _mm256_load_pd(double const *);` | +| [`_mm256_load_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_ps) | AVX | immintrin.h | `__m256 _mm256_load_ps(float const *);` | +| [`_mm256_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_si256) | AVX | immintrin.h | `__m256i _mm256_load_si256(__m256i *);` | +| [`_mm256_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_pd) | AVX | immintrin.h | `__m256d _mm256_loadu_pd(double const *);` | +| [`_mm256_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_ps) | AVX | immintrin.h | `__m256 _mm256_loadu_ps(float const *);` | +| [`_mm256_loadu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_si256) | AVX | immintrin.h | `__m256i _mm256_loadu_si256(__m256i *);` | +| `_mm256_macc_pd` | FMA4 | ammintrin.h | `__m256d _mm_macc_pd(__m256d, __m256d, __m256d);` | +| `_mm256_macc_ps` | FMA4 | ammintrin.h | `__m256 _mm_macc_ps(__m256, __m256, __m256);` | +| [`_mm256_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_madd_epi16) | AVX2 | immintrin.h | `__m256i _mm256_madd_epi16(__m256i, __m256i);` | +| `_mm256_maddsub_pd` | FMA4 | ammintrin.h | `__m256d _mm_maddsub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_maddsub_ps` | FMA4 | ammintrin.h | `__m256 _mm_maddsub_ps(__m256, __m256, __m256);` | +| [`_mm256_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maddubs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_maddubs_epi16(__m256i, __m256i);` | +| [`_mm256_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mask_i32gather_epi32(__m256i, int const *, __m256i, __m256i, const int);` | +| [`_mm256_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_mask_i32gather_epi64(__m256i, __int64 const *, __m128i, __m256i, const int);` | +| [`_mm256_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_mask_i32gather_pd(__m256d, double const *, __m128i, __m256d, const int);` | +| [`_mm256_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_ps) | AVX2 | immintrin.h | `__m256 _mm256_mask_i32gather_ps(__m256, float const *, __m256i, __m256, const int);` | +| [`_mm256_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm256_mask_i64gather_epi32(__m128i, int const *, __m256i, __m128i, const int);` | +| [`_mm256_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_mask_i64gather_epi64(__m256i, __int64 const *, __m256i, __m256i, const int);` | +| [`_mm256_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_mask_i64gather_pd(__m256d, double const *, __m256i, __m256d, const int);` | +| [`_mm256_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm256_mask_i64gather_ps(__m128, float const *, __m256i, __m128, const int);` | +| [`_mm256_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi32) | AVX2 | immintrin.h | `__m256i _mm256_maskload_epi32(int const *, __m256i);` | +| [`_mm256_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi64) | AVX2 | immintrin.h | `__m256i _mm256_maskload_epi64(__int64 const *, __m256i);` | +| [`_mm256_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_pd) | AVX | immintrin.h | `__m256d _mm256_maskload_pd(double const *, __m256i);` | +| [`_mm256_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_ps) | AVX | immintrin.h | `__m256 _mm256_maskload_ps(float const *, __m256i);` | +| [`_mm256_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi32) | AVX2 | immintrin.h | `void _mm256_maskstore_epi32(int *, __m256i, __m256i);` | +| [`_mm256_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi64) | AVX2 | immintrin.h | `void _mm256_maskstore_epi64(__int64 *, __m256i, __m256i);` | +| [`_mm256_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_pd) | AVX | immintrin.h | `void _mm256_maskstore_pd(double *, __m256i, __m256d);` | +| [`_mm256_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_ps) | AVX | immintrin.h | `void _mm256_maskstore_ps(float *, __m256i, __m256);` | +| [`_mm256_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi16) | AVX2 | immintrin.h | `__m256i _mm256_max_epi16(__m256i, __m256i);` | +| [`_mm256_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi32) | AVX2 | immintrin.h | `__m256i _mm256_max_epi32(__m256i, __m256i);` | +| [`_mm256_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi8) | AVX2 | immintrin.h | `__m256i _mm256_max_epi8(__m256i, __m256i);` | +| [`_mm256_max_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu16) | AVX2 | immintrin.h | `__m256i _mm256_max_epu16(__m256i, __m256i);` | +| [`_mm256_max_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu32) | AVX2 | immintrin.h | `__m256i _mm256_max_epu32(__m256i, __m256i);` | +| [`_mm256_max_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu8) | AVX2 | immintrin.h | `__m256i _mm256_max_epu8(__m256i, __m256i);` | +| [`_mm256_max_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_pd) | AVX | immintrin.h | `__m256d _mm256_max_pd(__m256d, __m256d);` | +| [`_mm256_max_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_ps) | AVX | immintrin.h | `__m256 _mm256_max_ps(__m256, __m256);` | +| [`_mm256_min_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi16) | AVX2 | immintrin.h | `__m256i _mm256_min_epi16(__m256i, __m256i);` | +| [`_mm256_min_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi32) | AVX2 | immintrin.h | `__m256i _mm256_min_epi32(__m256i, __m256i);` | +| [`_mm256_min_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi8) | AVX2 | immintrin.h | `__m256i _mm256_min_epi8(__m256i, __m256i);` | +| [`_mm256_min_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu16) | AVX2 | immintrin.h | `__m256i _mm256_min_epu16(__m256i, __m256i);` | +| [`_mm256_min_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu32) | AVX2 | immintrin.h | `__m256i _mm256_min_epu32(__m256i, __m256i);` | +| [`_mm256_min_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu8) | AVX2 | immintrin.h | `__m256i _mm256_min_epu8(__m256i, __m256i);` | +| [`_mm256_min_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_pd) | AVX | immintrin.h | `__m256d _mm256_min_pd(__m256d, __m256d);` | +| [`_mm256_min_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_ps) | AVX | immintrin.h | `__m256 _mm256_min_ps(__m256, __m256);` | +| [`_mm256_movedup_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movedup_pd) | AVX | immintrin.h | `__m256d _mm256_movedup_pd(__m256d);` | +| [`_mm256_movehdup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movehdup_ps) | AVX | immintrin.h | `__m256 _mm256_movehdup_ps(__m256);` | +| [`_mm256_moveldup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_moveldup_ps) | AVX | immintrin.h | `__m256 _mm256_moveldup_ps(__m256);` | +| [`_mm256_movemask_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_epi8) | AVX2 | immintrin.h | `int _mm256_movemask_epi8(__m256i);` | +| [`_mm256_movemask_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_pd) | AVX | immintrin.h | `int _mm256_movemask_pd(__m256d);` | +| [`_mm256_movemask_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_ps) | AVX | immintrin.h | `int _mm256_movemask_ps(__m256);` | +| [`_mm256_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mpsadbw_epu8) | AVX2 | immintrin.h | `__m256i _mm256_mpsadbw_epu8(__m256i, __m256i, const int);` | +| `_mm256_msub_pd` | FMA4 | ammintrin.h | `__m256d _mm_msub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_msub_ps` | FMA4 | ammintrin.h | `__m256 _mm_msub_ps(__m256, __m256, __m256);` | +| `_mm256_msubadd_pd` | FMA4 | ammintrin.h | `__m256d _mm_msubadd_pd(__m256d, __m256d, __m256d);` | +| `_mm256_msubadd_ps` | FMA4 | ammintrin.h | `__m256 _mm_msubadd_ps(__m256, __m256, __m256);` | +| [`_mm256_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mul_epi32(__m256i, __m256i);` | +| [`_mm256_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epu32) | AVX2 | immintrin.h | `__m256i _mm256_mul_epu32(__m256i, __m256i);` | +| [`_mm256_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_pd) | AVX | immintrin.h | `__m256d _mm256_mul_pd(__m256d, __m256d);` | +| [`_mm256_mul_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_ps) | AVX | immintrin.h | `__m256 _mm256_mul_ps(__m256, __m256);` | +| [`_mm256_mulhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mulhi_epi16(__m256i, __m256i);` | +| [`_mm256_mulhi_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epu16) | AVX2 | immintrin.h | `__m256i _mm256_mulhi_epu16(__m256i, __m256i);` | +| [`_mm256_mulhrs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhrs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mulhrs_epi16(__m256i, __m256i);` | +| [`_mm256_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mullo_epi16(__m256i, __m256i);` | +| [`_mm256_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mullo_epi32(__m256i, __m256i);` | +| `_mm256_nmacc_pd` | FMA4 | ammintrin.h | `__m256d _mm_nmacc_pd(__m256d, __m256d, __m256d);` | +| `_mm256_nmacc_ps` | FMA4 | ammintrin.h | `__m256 _mm_nmacc_ps(__m256, __m256, __m256);` | +| `_mm256_nmsub_pd` | FMA4 | ammintrin.h | `__m256d _mm_nmsub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_nmsub_ps` | FMA4 | ammintrin.h | `__m256 _mm_nmsub_ps(__m256, __m256, __m256);` | +| [`_mm256_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_pd) | AVX | immintrin.h | `__m256d _mm256_or_pd(__m256d, __m256d);` | +| [`_mm256_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_ps) | AVX | immintrin.h | `__m256 _mm256_or_ps(__m256, __m256);` | +| [`_mm256_or_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_si256) | AVX2 | immintrin.h | `__m256i _mm256_or_si256(__m256i, __m256i);` | +| [`_mm256_packs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_packs_epi16(__m256i, __m256i);` | +| [`_mm256_packs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi32) | AVX2 | immintrin.h | `__m256i _mm256_packs_epi32(__m256i, __m256i);` | +| [`_mm256_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi16) | AVX2 | immintrin.h | `__m256i _mm256_packus_epi16(__m256i, __m256i);` | +| [`_mm256_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi32) | AVX2 | immintrin.h | `__m256i _mm256_packus_epi32(__m256i, __m256i);` | +| [`_mm256_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_pd) | AVX | immintrin.h | `__m256d _mm256_permute_pd(__m256d, int);` | +| [`_mm256_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_ps) | AVX | immintrin.h | `__m256 _mm256_permute_ps(__m256, int);` | +| `_mm256_permute2_pd` | XOP | ammintrin.h | `__m256d _mm256_permute2_pd(__m256d, __m256d, __m256i, int);` | +| `_mm256_permute2_ps` | XOP | ammintrin.h | `__m256 _mm256_permute2_ps(__m256, __m256, __m256i, int);` | +| [`_mm256_permute2f128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_pd) | AVX | immintrin.h | `__m256d _mm256_permute2f128_pd(__m256d, __m256d, int);` | +| [`_mm256_permute2f128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_ps) | AVX | immintrin.h | `__m256 _mm256_permute2f128_ps(__m256, __m256, int);` | +| [`_mm256_permute2f128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_si256) | AVX | immintrin.h | `__m256i _mm256_permute2f128_si256(__m256i, __m256i, int);` | +| [`_mm256_permute2x128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2x128_si256) | AVX2 | immintrin.h | `__m256i _mm256_permute2x128_si256(__m256i, __m256i, const int);` | +| [`_mm256_permute4x64_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_epi64) | AVX2 | immintrin.h | `__m256i _mm256_permute4x64_epi64 (__m256i, const int);` | +| [`_mm256_permute4x64_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_pd) | AVX2 | immintrin.h | `__m256d _mm256_permute4x64_pd(__m256d, const int);` | +| [`_mm256_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_pd) | AVX | immintrin.h | `__m256d _mm256_permutevar_pd(__m256d, __m256i);` | +| [`_mm256_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_ps) | AVX | immintrin.h | `__m256 _mm256_permutevar_ps(__m256, __m256i);` | +| [`_mm256_permutevar8x32_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_epi32) | AVX2 | immintrin.h | `__m256i _mm256_permutevar8x32_epi32(__m256i, __m256i);` | +| [`_mm256_permutevar8x32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_ps) | AVX2 | immintrin.h | `__m256 _mm256_permutevar8x32_ps (__m256, __m256i);` | +| [`_mm256_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rcp_ps) | AVX | immintrin.h | `__m256 _mm256_rcp_ps(__m256);` | +| [`_mm256_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_pd) | AVX | immintrin.h | `__m256d _mm256_round_pd(__m256d, int);` | +| [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | +| [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | +| [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | +| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | +| [`_mm256_set_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi64x) | AVX | immintrin.h | `__m256i _mm256_set_epi64x(long long, long long, long long, long long);` | +| [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | +| [`_mm256_set_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_pd) | AVX | immintrin.h | `__m256d _mm256_set_pd(double, double, double, double);` | +| [`_mm256_set_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_ps) | AVX | immintrin.h | `__m256 _mm256_set_ps(float, float, float, float, float, float, float, float);` | +| [`_mm256_set1_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi16) | AVX | immintrin.h | `__m256i _mm256_set1_epi16(short);` | +| [`_mm256_set1_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi32) | AVX | immintrin.h | `__m256i _mm256_set1_epi32(int);` | +| [`_mm256_set1_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi64x) | AVX | immintrin.h | `__m256i _mm256_set1_epi64x(long long);` | +| [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX | immintrin.h | `__m256i _mm256_set1_epi8(char);` | +| [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX | immintrin.h | `__m256d _mm256_set1_pd(double);` | +| [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX | immintrin.h | `__m256 _mm256_set1_ps(float);` | +| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_setr_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi32) | AVX | immintrin.h | `__m256i _mm256_setr_epi32(int, int, int, int, int, int, int, int);` | +| [`_mm256_setr_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi64x) | AVX | immintrin.h | `__m256i _mm256_setr_epi64x(long long, long long, long long, long long);` | +| [`_mm256_setr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi8) | AVX | immintrin.h | `(__m256i _mm256_setr_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | +| [`_mm256_setr_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_pd) | AVX | immintrin.h | `__m256d _mm256_setr_pd(double, double, double, double);` | +| [`_mm256_setr_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_ps) | AVX | immintrin.h | `__m256 _mm256_setr_ps(float, float, float, float, float, float, float, float);` | +| [`_mm256_setzero_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_pd) | AVX | immintrin.h | `__m256d _mm256_setzero_pd(void);` | +| [`_mm256_setzero_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_ps) | AVX | immintrin.h | `__m256 _mm256_setzero_ps(void);` | +| [`_mm256_setzero_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_si256) | AVX | immintrin.h | `__m256i _mm256_setzero_si256(void);` | +| [`_mm256_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi32) | AVX2 | immintrin.h | `__m256i _mm256_shuffle_epi32(__m256i, const int);` | +| [`_mm256_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi8) | AVX2 | immintrin.h | `__m256i _mm256_shuffle_epi8(__m256i, __m256i);` | +| [`_mm256_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_pd) | AVX | immintrin.h | `__m256d _mm256_shuffle_pd(__m256d, __m256d, const int);` | +| [`_mm256_shuffle_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_ps) | AVX | immintrin.h | `__m256 _mm256_shuffle_ps(__m256, __m256, const int);` | +| [`_mm256_shufflehi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflehi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_shufflehi_epi16(__m256i, const int);` | +| [`_mm256_shufflelo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflelo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_shufflelo_epi16(__m256i, const int);` | +| [`_mm256_sign_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi16(__m256i, __m256i);` | +| [`_mm256_sign_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi32(__m256i, __m256i);` | +| [`_mm256_sign_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi8) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi8(__m256i, __m256i);` | +| [`_mm256_sll_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi16(__m256i, __m128i);` | +| [`_mm256_sll_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi32(__m256i, __m128i);` | +| [`_mm256_sll_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi64(__m256i, __m128i);` | +| [`_mm256_slli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi16) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi16(__m256i, int);` | +| [`_mm256_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi32) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi32(__m256i, int);` | +| [`_mm256_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi64) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi64(__m256i, int);` | +| [`_mm256_slli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_si256) | AVX2 | immintrin.h | `__m256i _mm256_slli_si256(__m256i, int);` | +| [`_mm256_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sllv_epi32(__m256i, __m256i);` | +| [`_mm256_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sllv_epi64(__m256i, __m256i);` | +| [`_mm256_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_pd) | AVX | immintrin.h | `__m256d _mm256_sqrt_pd(__m256d);` | +| [`_mm256_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_ps) | AVX | immintrin.h | `__m256 _mm256_sqrt_ps(__m256);` | +| [`_mm256_sra_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sra_epi16(__m256i, __m128i);` | +| [`_mm256_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sra_epi32(__m256i, __m128i);` | +| [`_mm256_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srai_epi16(__m256i, int);` | +| [`_mm256_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srai_epi32(__m256i, int);` | +| [`_mm256_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srav_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srav_epi32(__m256i, __m256i);` | +| [`_mm256_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi16(__m256i, __m128i);` | +| [`_mm256_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi32(__m256i, __m128i);` | +| [`_mm256_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi64(__m256i, __m128i);` | +| [`_mm256_srli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi16(__m256i, int);` | +| [`_mm256_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi32(__m256i, int);` | +| [`_mm256_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi64(__m256i, int);` | +| [`_mm256_srli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_si256) | AVX2 | immintrin.h | `__m256i _mm256_srli_si256(__m256i, int);` | +| [`_mm256_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srlv_epi32(__m256i, __m256i);` | +| [`_mm256_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srlv_epi64(__m256i, __m256i);` | +| [`_mm256_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_pd) | AVX | immintrin.h | `void _mm256_store_pd(double *, __m256d);` | +| [`_mm256_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_ps) | AVX | immintrin.h | `void _mm256_store_ps(float *, __m256);` | +| [`_mm256_store_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_si256) | AVX | immintrin.h | `void _mm256_store_si256(__m256i *, __m256i);` | +| [`_mm256_storeu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_pd) | AVX | immintrin.h | `void _mm256_storeu_pd(double *, __m256d);` | +| [`_mm256_storeu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_ps) | AVX | immintrin.h | `void _mm256_storeu_ps(float *, __m256);` | +| [`_mm256_storeu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_si256) | AVX | immintrin.h | `void _mm256_storeu_si256(__m256i *, __m256i);` | +| [`_mm256_stream_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_load_si256) | AVX2 | immintrin.h | `__m256i _mm256_stream_load_si256(__m256i const *);` | +| [`_mm256_stream_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_pd) | AVX | immintrin.h | `void __mm256_stream_pd(double *, __m256d);` | +| [`_mm256_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_ps) | AVX | immintrin.h | `void _mm256_stream_ps(float *, __m256);` | +| [`_mm256_stream_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_si256) | AVX | immintrin.h | `void __mm256_stream_si256(__m256i *, __m256i);` | +| [`_mm256_sub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi16(__m256i, __m256i);` | +| [`_mm256_sub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi32(__m256i, __m256i);` | +| [`_mm256_sub_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi64(__m256i, __m256i);` | +| [`_mm256_sub_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi8) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi8(__m256i, __m256i);` | +| [`_mm256_sub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_pd) | AVX | immintrin.h | `__m256d _mm256_sub_pd(__m256d, __m256d);` | +| [`_mm256_sub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_ps) | AVX | immintrin.h | `__m256 _mm256_sub_ps(__m256, __m256);` | +| [`_mm256_subs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_subs_epi16(__m256i, __m256i);` | +| [`_mm256_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi8) | AVX2 | immintrin.h | `__m256i _mm256_subs_epi8(__m256i, __m256i);` | +| [`_mm256_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu16) | AVX2 | immintrin.h | `__m256i _mm256_subs_epu16(__m256i, __m256i);` | +| [`_mm256_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu8) | AVX2 | immintrin.h | `__m256i _mm256_subs_epu8(__m256i, __m256i);` | +| [`_mm256_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_pd) | AVX | immintrin.h | `int _mm256_testc_pd(__m256d, __m256d);` | +| [`_mm256_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_ps) | AVX | immintrin.h | `int _mm256_testc_ps(__m256, __m256);` | +| [`_mm256_testc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_si256) | AVX | immintrin.h | `int _mm256_testc_si256(__m256i, __m256i);` | +| [`_mm256_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_pd) | AVX | immintrin.h | `int _mm256_testnzc_pd(__m256d, __m256d);` | +| [`_mm256_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_ps) | AVX | immintrin.h | `int _mm256_testnzc_ps(__m256, __m256);` | +| [`_mm256_testnzc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_si256) | AVX | immintrin.h | `int _mm256_testnzc_si256(__m256i, __m256i);` | +| [`_mm256_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_pd) | AVX | immintrin.h | `int _mm256_testz_pd(__m256d, __m256d);` | +| [`_mm256_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_ps) | AVX | immintrin.h | `int _mm256_testz_ps(__m256, __m256);` | +| [`_mm256_testz_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_si256) | AVX | immintrin.h | `int _mm256_testz_si256(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi16(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi32) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi32(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi64) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi64(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi8) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi8(__m256i, __m256i);` | +| [`_mm256_unpackhi_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_pd) | AVX | immintrin.h | `__m256d _mm256_unpackhi_pd(__m256d, __m256d);` | +| [`_mm256_unpackhi_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_ps) | AVX | immintrin.h | `__m256 _mm256_unpackhi_ps(__m256, __m256);` | +| [`_mm256_unpacklo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi16(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi32) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi32(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi64) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi64(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi8) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi8(__m256i, __m256i);` | +| [`_mm256_unpacklo_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_pd) | AVX | immintrin.h | `__m256d _mm256_unpacklo_pd(__m256d, __m256d);` | +| [`_mm256_unpacklo_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_ps) | AVX | immintrin.h | `__m256 _mm256_unpacklo_ps(__m256, __m256);` | +| [`_mm256_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_pd) | AVX | immintrin.h | `__m256d _mm256_xor_pd(__m256d, __m256d);` | +| [`_mm256_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_ps) | AVX | immintrin.h | `__m256 _mm256_xor_ps(__m256, __m256);` | +| [`_mm256_xor_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_si256) | AVX2 | immintrin.h | `__m256i _mm256_xor_si256(__m256i, __m256i);` | +| [`_mm256_zeroall`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroall) | AVX | immintrin.h | `void _mm256_zeroall(void);` | +| [`_mm256_zeroupper`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroupper) | AVX | immintrin.h | `void _mm256_zeroupper(void);` | | [`__movsb`](movsb.md) | | intrin.h | `VOID __movsb(unsigned char *, unsigned char const *, size_t);` | | [`__movsd`](movsd.md) | | intrin.h | `VOID __movsd(unsigned long *, unsigned long const *, size_t);` | | [`__movsq`](movsq.md) | | intrin.h | `VOID __movsq(unsigned __int64 *, unsigned __int64 const *, size_t);` | | [`__movsw`](movsw.md) | | intrin.h | `VOID __movsw(unsigned short *, unsigned short const *, size_t);` | | [`_mul128`](mul128.md) | | intrin.h | `__int64 _mul128(__int64, __int64, __int64 *);` | | [`__mulh`](mulh.md) | | intrin.h | `__int64 __mulh(__int64, __int64);` | -| `_mulx_u32` | BMI \[2] | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | -| `_mulx_u64` | BMI \[2] | immintrin.h | `unsigned __int64 _mulx_u64(unsigned __int64, unsigned __int64, unsigned __int64*);` | +| [`_mulx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mulx_u32) | BMI | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | +| [`_mulx_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mulx_u64) | BMI | immintrin.h | `unsigned __int64 _mulx_u64(unsigned __int64, unsigned __int64, unsigned __int64*);` | | [`__nop`](nop.md) | | intrin.h | `void __nop(void);` | | `__nvreg_restore_fence` | | intrin.h | `void __nvreg_restore_fence(void);` | | `__nvreg_save_fence` | | intrin.h | `void __nvreg_save_fence(void);` | @@ -1145,19 +1151,19 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__outdwordstring`](outdwordstring.md) | | intrin.h | `void __outdwordstring(unsigned short, unsigned long *, unsigned long);` | | [`__outword`](outword.md) | | intrin.h | `void __outword(unsigned short, unsigned short);` | | [`__outwordstring`](outwordstring.md) | | intrin.h | `void __outwordstring(unsigned short, unsigned short *, unsigned long);` | -| [`_pdep_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u32) | BMI \[2] | immintrin.h | `unsigned int _pdep_u32(unsigned int, unsigned int);` | -| [`_pdep_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u64) | BMI \[2] | immintrin.h | `unsigned __int64 _pdep_u64(unsigned __int64, unsigned __int64);` | -| [`_pext_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u32) | BMI \[2] | immintrin.h | `unsigned int _pext_u32(unsigned int, unsigned int);` | -| [`_pext_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u64) | BMI \[2] | immintrin.h | `unsigned __int64 _pext_u64(unsigned __int64, unsigned __int64);` | +| [`_pdep_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u32) | BMI | immintrin.h | `unsigned int _pdep_u32(unsigned int, unsigned int);` | +| [`_pdep_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u64) | BMI | immintrin.h | `unsigned __int64 _pdep_u64(unsigned __int64, unsigned __int64);` | +| [`_pext_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u32) | BMI | immintrin.h | `unsigned int _pext_u32(unsigned int, unsigned int);` | +| [`_pext_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u64) | BMI | immintrin.h | `unsigned __int64 _pext_u64(unsigned __int64, unsigned __int64);` | | [`__popcnt`](popcnt16-popcnt-popcnt64.md) | POPCNT | intrin.h | `unsigned int __popcnt(unsigned int);` | | [`__popcnt16`](popcnt16-popcnt-popcnt64.md) | POPCNT | intrin.h | `unsigned short __popcnt16(unsigned short);` | | [`__popcnt64`](popcnt16-popcnt-popcnt64.md) | POPCNT | intrin.h | `unsigned __int64 __popcnt64(unsigned __int64);` | -| [`_rdrand16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand16_step) | RDRAND \[2] | immintrin.h | `int _rdrand16_step(unsigned short *);` | -| [`_rdrand32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand32_step) | RDRAND \[2] | immintrin.h | `int _rdrand32_step(unsigned int *);` | -| [`_rdrand64_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand64_step) | RDRAND \[2] | immintrin.h | `int _rdrand64_step(unsigned __int64 *);` | -| [`_rdseed16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed16_step) | RDSEED \[2] | immintrin.h | `int _rdseed16_step(unsigned short *);` | -| [`_rdseed32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed32_step) | RDSEED \[2] | immintrin.h | `int _rdseed32_step(unsigned int *);` | -| [`_rdseed64_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed64_step) | RDSEED \[2] | immintrin.h | `int _rdseed64_step(unsigned __int64 *);` | +| [`_rdrand16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand16_step) | RDRAND | immintrin.h | `int _rdrand16_step(unsigned short *);` | +| [`_rdrand32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand32_step) | RDRAND | immintrin.h | `int _rdrand32_step(unsigned int *);` | +| [`_rdrand64_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand64_step) | RDRAND | immintrin.h | `int _rdrand64_step(unsigned __int64 *);` | +| [`_rdseed16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed16_step) | RDSEED | immintrin.h | `int _rdseed16_step(unsigned short *);` | +| [`_rdseed32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed32_step) | RDSEED | immintrin.h | `int _rdseed32_step(unsigned int *);` | +| [`_rdseed64_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed64_step) | RDSEED | immintrin.h | `int _rdseed64_step(unsigned __int64 *);` | | [`__rdtsc`](rdtsc.md) | | intrin.h | `unsigned __int64 __rdtsc(void);` | | [`__rdtscp`](rdtscp.md) | RDTSCP | intrin.h | `unsigned __int64 __rdtscp(unsigned int*);` | | [`_ReadBarrier`](readbarrier.md) | | intrin.h | `void _ReadBarrier(void);` | @@ -1168,10 +1174,10 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__readcr8`](readcr8.md) | | intrin.h | `unsigned __int64 __readcr8(void);` | | [`__readdr`](readdr.md) | | intrin.h | `unsigned __int64 __readdr(unsigned);` | | [`__readeflags`](readeflags.md) | | intrin.h | `unsigned __int64 __readeflags(void);` | -| [`_readfsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readfsbase_u32) | FSGSBASE \[2] | immintrin.h | `unsigned int _readfsbase_u32(void);` | -| [`_readfsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readfsbase_u64) | FSGSBASE \[2] | immintrin.h | `unsigned __int64 _readfsbase_u64(void);` | -| [`_readgsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readgsbase_u32) | FSGSBASE \[2] | immintrin.h | `unsigned int _readgsbase_u32(void);` | -| [`_readgsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readgsbase_u64) | FSGSBASE \[2] | immintrin.h | `unsigned __int64 _readgsbase_u64(void);` | +| [`_readfsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readfsbase_u32) | FSGSBASE | immintrin.h | `unsigned int _readfsbase_u32(void);` | +| [`_readfsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readfsbase_u64) | FSGSBASE | immintrin.h | `unsigned __int64 _readfsbase_u64(void);` | +| [`_readgsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readgsbase_u32) | FSGSBASE | immintrin.h | `unsigned int _readgsbase_u32(void);` | +| [`_readgsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_readgsbase_u64) | FSGSBASE | immintrin.h | `unsigned __int64 _readgsbase_u64(void);` | | [`__readgsbyte`](readgsbyte-readgsdword-readgsqword-readgsword.md) | | intrin.h | `unsigned char __readgsbyte(unsigned long);` | | [`__readgsdword`](readgsbyte-readgsdword-readgsqword-readgsword.md) | | intrin.h | `unsigned long __readgsdword(unsigned long);` | | [`__readgsqword`](readgsbyte-readgsdword-readgsqword-readgsword.md) | | intrin.h | `unsigned __int64 __readgsqword(unsigned long);` | @@ -1180,35 +1186,35 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__readpmc`](readpmc.md) | | intrin.h | `unsigned __int64 __readpmc(unsigned long);` | | [`_ReadWriteBarrier`](readwritebarrier.md) | | intrin.h | `void _ReadWriteBarrier(void);` | | [`_ReturnAddress`](returnaddress.md) | | intrin.h | `void * _ReturnAddress(void);` | -| `_rorx_u32` | BMI \[2] | immintrin.h | `unsigned int _rorx_u32(unsigned int, const unsigned int);` | -| `_rorx_u64` | BMI \[2] | immintrin.h | `unsigned __int64 _rorx_u64(unsigned __int64, const unsigned int);` | +| `_rorx_u32` | BMI | immintrin.h | `unsigned int _rorx_u32(unsigned int, const unsigned int);` | +| `_rorx_u64` | BMI | immintrin.h | `unsigned __int64 _rorx_u64(unsigned __int64, const unsigned int);` | | [`_rotl16`](rotl8-rotl16.md) | | intrin.h | `unsigned short _rotl16(unsigned short, unsigned char);` | | [`_rotl8`](rotl8-rotl16.md) | | intrin.h | `unsigned char _rotl8(unsigned char, unsigned char);` | | [`_rotr16`](rotr8-rotr16.md) | | intrin.h | `unsigned short _rotr16(unsigned short, unsigned char);` | | [`_rotr8`](rotr8-rotr16.md) | | intrin.h | `unsigned char _rotr8(unsigned char, unsigned char);` | | `_rsm` | | intrin.h | `void _rsm(void);` | -| `_sarx_i32` | BMI \[2] | immintrin.h | `int _sarx_i32(int, unsigned int);` | -| `_sarx_i64` | BMI \[2] | immintrin.h | `__int64 _sarx_i64(__int64, unsigned int);` | +| `_sarx_i32` | BMI | immintrin.h | `int _sarx_i32(int, unsigned int);` | +| `_sarx_i64` | BMI | immintrin.h | `__int64 _sarx_i64(__int64, unsigned int);` | | [`__segmentlimit`](segmentlimit.md) | | intrin.h | `unsigned long __segmentlimit(unsigned long);` | | `_sgdt` | | intrin.h | `void _sgdt(void*);` | | [`__shiftleft128`](shiftleft128.md) | | intrin.h | `unsigned __int64 __shiftleft128(unsigned __int64, unsigned __int64, unsigned char);` | | [`__shiftright128`](shiftright128.md) | | intrin.h | `unsigned __int64 __shiftright128(unsigned __int64, unsigned __int64, unsigned char);` | -| `_shlx_u32` | BMI \[2] | immintrin.h | `unsigned int _shlx_u32(unsigned int, unsigned int);` | -| `_shlx_u64` | BMI \[2] | immintrin.h | `unsigned __int64 _shlx_u64(unsigned __int64, unsigned int);` | -| `_shrx_u32` | BMI \[2] | immintrin.h | `unsigned int _shrx_u32(unsigned int, unsigned int);` | -| `_shrx_u64` | BMI \[2] | immintrin.h | `unsigned __int64 _shrx_u64(unsigned __int64, unsigned int);` | +| `_shlx_u32` | BMI | immintrin.h | `unsigned int _shlx_u32(unsigned int, unsigned int);` | +| `_shlx_u64` | BMI | immintrin.h | `unsigned __int64 _shlx_u64(unsigned __int64, unsigned int);` | +| `_shrx_u32` | BMI | immintrin.h | `unsigned int _shrx_u32(unsigned int, unsigned int);` | +| `_shrx_u64` | BMI | immintrin.h | `unsigned __int64 _shrx_u64(unsigned __int64, unsigned int);` | | [`__sidt`](sidt.md) | | intrin.h | `void __sidt(void*);` | -| `__slwpcb` | LWP \[1] | ammintrin.h | `void *__slwpcb(void);` | +| `__slwpcb` | LWP | ammintrin.h | `void *__slwpcb(void);` | | `_stac` | SMAP | intrin.h | `void _stac(void);` | -| [`_storebe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i16&expand=5141) | MOVBE | immintrin.h | `void _storebe_i16(void *, short);` \[3] | -| [`_storebe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i32&expand=5142) | MOVBE | immintrin.h | `void _storebe_i32(void *, int);` \[3] | -| [`_storebe_i64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i64&expand=5143) | MOVBE | immintrin.h | `void _storebe_i64(void *, __int64);` \[3] | -| `_store_be_u16` | MOVBE | immintrin.h | `void _store_be_u16(void *, unsigned short);` \[3] | -| `_store_be_u32` | MOVBE | immintrin.h | `void _store_be_u32(void *, unsigned int);` \[3] | -| `_store_be_u64` | MOVBE | immintrin.h | `void _store_be_u64(void *, unsigned __int64);` \[3] | -| `_Store_HLERelease` | HLE \[2] | immintrin.h | `void _Store_HLERelease(long volatile *, long);` | -| `_Store64_HLERelease` | HLE \[2] | immintrin.h | `void _Store64_HLERelease(__int64 volatile *, __int64);` | -| `_StorePointer_HLERelease` | HLE \[2] | immintrin.h | `void _StorePointer_HLERelease(void * volatile *, void *);` | +| [`_storebe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i16&expand=5141) | MOVBE | immintrin.h | `void _storebe_i16(void *, short);` \[Macro] | +| [`_storebe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i32&expand=5142) | MOVBE | immintrin.h | `void _storebe_i32(void *, int);` \[Macro] | +| [`_storebe_i64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i64&expand=5143) | MOVBE | immintrin.h | `void _storebe_i64(void *, __int64);` \[Macro] | +| `_store_be_u16` | MOVBE | immintrin.h | `void _store_be_u16(void *, unsigned short);` \[Macro] | +| `_store_be_u32` | MOVBE | immintrin.h | `void _store_be_u32(void *, unsigned int);` \[Macro] | +| `_store_be_u64` | MOVBE | immintrin.h | `void _store_be_u64(void *, unsigned __int64);` \[Macro] | +| `_Store_HLERelease` | HLE | immintrin.h | `void _Store_HLERelease(long volatile *, long);` | +| `_Store64_HLERelease` | HLE | immintrin.h | `void _Store64_HLERelease(__int64 volatile *, __int64);` | +| `_StorePointer_HLERelease` | HLE | immintrin.h | `void _StorePointer_HLERelease(void * volatile *, void *);` | | [`__stosb`](stosb.md) | | intrin.h | `void __stosb(unsigned char *, unsigned char, size_t);` | | [`__stosd`](stosd.md) | | intrin.h | `void __stosd(unsigned long *, unsigned long, size_t);` | | [`__stosq`](stosq.md) | | intrin.h | `void __stosq(unsigned __int64 *, unsigned __int64, size_t);` | @@ -1224,12 +1230,12 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__svm_vmload`](svm-vmload.md) | | intrin.h | `void __svm_vmload(size_t);` | | [`__svm_vmrun`](svm-vmrun.md) | | intrin.h | `void __svm_vmrun(size_t);` | | [`__svm_vmsave`](svm-vmsave.md) | | intrin.h | `void __svm_vmsave(size_t);` | -| `_t1mskc_u32` | ABM \[1] | ammintrin.h | `unsigned int _t1mskc_u32(unsigned int);` | -| `_t1mskc_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _t1mskc_u64(unsigned __int64);` | +| `_t1mskc_u32` | ABM | ammintrin.h | `unsigned int _t1mskc_u32(unsigned int);` | +| `_t1mskc_u64` | ABM | ammintrin.h | `unsigned __int64 _t1mskc_u64(unsigned __int64);` | | [`_tzcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_tzcnt_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _tzcnt_u32(unsigned int);` | | [`_tzcnt_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_tzcnt_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _tzcnt_u64(unsigned __int64);` | -| `_tzmsk_u32` | ABM \[1] | ammintrin.h | `unsigned int _tzmsk_u32(unsigned int);` | -| `_tzmsk_u64` | ABM \[1] | ammintrin.h | `unsigned __int64 _tzmsk_u64(unsigned __int64);` | +| `_tzmsk_u32` | ABM | ammintrin.h | `unsigned int _tzmsk_u32(unsigned int);` | +| `_tzmsk_u64` | ABM | ammintrin.h | `unsigned __int64 _tzmsk_u64(unsigned __int64);` | | [`__ud2`](ud2.md) | | intrin.h | `void __ud2(void);` | | [`_udiv128`](udiv128.md) | | intrin.h | `unsigned __int64 _udiv128(unsigned __int64, unsigned __int64, unsigned __int64, unsigned __int64 *);` | | [`_udiv64`](udiv64.md) | | intrin.h | `unsigned int _udiv64(unsigned __int64, unsigned int, unsigned int*);` | @@ -1253,27 +1259,27 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__writecr8`](writecr8.md) | | intrin.h | `void __writecr8(unsigned __int64);` | | [`__writedr`](writedr.md) | | intrin.h | `void __writedr(unsigned, unsigned __int64);` | | [`__writeeflags`](writeeflags.md) | | intrin.h | `void __writeeflags(unsigned __int64);` | -| [`_writefsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writefsbase_u32) | FSGSBASE \[2] | immintrin.h | `void _writefsbase_u32(unsigned int);` | -| [`_writefsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writefsbase_u64) | FSGSBASE \[2] | immintrin.h | `void _writefsbase_u64(unsigned __int64);` | -| [`_writegsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writegsbase_u32) | FSGSBASE \[2] | immintrin.h | `void _writegsbase_u32(unsigned int);` | -| [`_writegsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writegsbase_u64) | FSGSBASE \[2] | immintrin.h | `void _writegsbase_u64(unsigned __int64);` | +| [`_writefsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writefsbase_u32) | FSGSBASE | immintrin.h | `void _writefsbase_u32(unsigned int);` | +| [`_writefsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writefsbase_u64) | FSGSBASE | immintrin.h | `void _writefsbase_u64(unsigned __int64);` | +| [`_writegsbase_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writegsbase_u32) | FSGSBASE | immintrin.h | `void _writegsbase_u32(unsigned int);` | +| [`_writegsbase_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_writegsbase_u64) | FSGSBASE | immintrin.h | `void _writegsbase_u64(unsigned __int64);` | | [`__writegsbyte`](writegsbyte-writegsdword-writegsqword-writegsword.md) | | intrin.h | `void __writegsbyte(unsigned long, unsigned char);` | | [`__writegsdword`](writegsbyte-writegsdword-writegsqword-writegsword.md) | | intrin.h | `void __writegsdword(unsigned long, unsigned long);` | | [`__writegsqword`](writegsbyte-writegsdword-writegsqword-writegsword.md) | | intrin.h | `void __writegsqword(unsigned long, unsigned __int64);` | | [`__writegsword`](writegsbyte-writegsdword-writegsqword-writegsword.md) | | intrin.h | `void __writegsword(unsigned long, unsigned short);` | | [`__writemsr`](writemsr.md) | | intrin.h | `void __writemsr(unsigned long, unsigned __int64);` | -| [`_xabort`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xabort) | RTM \[2] | immintrin.h | `void _xabort(unsigned int);` | -| [`_xbegin`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xbegin) | RTM \[2] | immintrin.h | `unsigned _xbegin(void);` | -| [`_xend`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xend) | RTM \[2] | immintrin.h | `void _xend(void);` | -| [`_xgetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xgetbv) | XSAVE \[2] | immintrin.h | `unsigned __int64 _xgetbv(unsigned int);` | -| [`_xrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor) | XSAVE \[2] | immintrin.h | `void _xrstor(void const*, unsigned __int64);` | -| [`_xrstor64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor64) | XSAVE \[2] | immintrin.h | `void _xrstor64(void const*, unsigned __int64);` | -| [`_xsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave) | XSAVE \[2] | immintrin.h | `void _xsave(void*, unsigned __int64);` | -| [`_xsave64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave64) | XSAVE \[2] | immintrin.h | `void _xsave64(void*, unsigned __int64);` | -| [`_xsaveopt`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt) | XSAVEOPT \[2] | immintrin.h | `void _xsaveopt(void*, unsigned __int64);` | -| [`_xsaveopt64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt64) | XSAVEOPT \[2] | immintrin.h | `void _xsaveopt64(void*, unsigned __int64);` | -| [`_xsetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsetbv) | XSAVE \[2] | immintrin.h | `void _xsetbv(unsigned int, unsigned __int64);` | -| [`_xtest`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xtest) | XTEST \[2] | immintrin.h | `unsigned char _xtest(void);` | +| [`_xabort`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xabort) | RTM | immintrin.h | `void _xabort(unsigned int);` | +| [`_xbegin`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xbegin) | RTM | immintrin.h | `unsigned _xbegin(void);` | +| [`_xend`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xend) | RTM | immintrin.h | `void _xend(void);` | +| [`_xgetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xgetbv) | XSAVE | immintrin.h | `unsigned __int64 _xgetbv(unsigned int);` | +| [`_xrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor) | XSAVE | immintrin.h | `void _xrstor(void const*, unsigned __int64);` | +| [`_xrstor64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor64) | XSAVE | immintrin.h | `void _xrstor64(void const*, unsigned __int64);` | +| [`_xsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave) | XSAVE | immintrin.h | `void _xsave(void*, unsigned __int64);` | +| [`_xsave64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave64) | XSAVE | immintrin.h | `void _xsave64(void*, unsigned __int64);` | +| [`_xsaveopt`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt) | XSAVEOPT | immintrin.h | `void _xsaveopt(void*, unsigned __int64);` | +| [`_xsaveopt64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt64) | XSAVEOPT | immintrin.h | `void _xsaveopt64(void*, unsigned __int64);` | +| [`_xsetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsetbv) | XSAVE | immintrin.h | `void _xsetbv(unsigned int, unsigned __int64);` | +| [`_xtest`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xtest) | XTEST | immintrin.h | `unsigned char _xtest(void);` | ## See also diff --git a/docs/intrinsics/x86-intrinsics-list.md b/docs/intrinsics/x86-intrinsics-list.md index 600cfe8b47..502e7552b8 100644 --- a/docs/intrinsics/x86-intrinsics-list.md +++ b/docs/intrinsics/x86-intrinsics-list.md @@ -1,9 +1,9 @@ --- title: "x86 intrinsics list" description: "Reference list of x86 intrinsics supported by the Microsoft C++ compiler in Visual Studio." -ms.date: 02/04/2021 -f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "ammintrin/_andn_u32", "ammintrin/_bextr_u32", "ammintrin/_bextri_u32", "ammintrin/_blcfill_u32", "ammintrin/_blci_u32", "ammintrin/_blcic_u32", "ammintrin/_blcmsk_u32", "ammintrin/_blcs_u32", "ammintrin/_blsfill_u32", "ammintrin/_blsi_u32", "ammintrin/_blsic_u32", "ammintrin/_blsmsk_u32", "ammintrin/_blsr_u32", "immintrin/_bzhi_u32", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxsave", "immintrin/_invpcid", "intrin/_lgdt", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "ammintrin/__llwpcb", "ammintrin/__lwpins32", "ammintrin/__lwpval32", "ammintrin/_lzcnt_u32", "intrin/_m_empty", "intrin/_m_femms", "intrin/_m_from_float", "intrin/_m_from_int", "intrin/_m_maskmovq", "intrin/_m_packssdw", "intrin/_m_packsswb", "intrin/_m_packuswb", "intrin/_m_paddb", "intrin/_m_paddd", "intrin/_m_paddsb", "intrin/_m_paddsw", "intrin/_m_paddusb", "intrin/_m_paddusw", "intrin/_m_paddw", "intrin/_m_pand", "intrin/_m_pandn", "intrin/_m_pavgb", "intrin/_m_pavgusb", "intrin/_m_pavgw", "intrin/_m_pcmpeqb", "intrin/_m_pcmpeqd", "intrin/_m_pcmpeqw", "intrin/_m_pcmpgtb", "intrin/_m_pcmpgtd", "intrin/_m_pcmpgtw", "intrin/_m_pextrw", "intrin/_m_pf2id", "intrin/_m_pf2iw", "intrin/_m_pfacc", "intrin/_m_pfadd", "intrin/_m_pfcmpeq", "intrin/_m_pfcmpge", "intrin/_m_pfcmpgt", "intrin/_m_pfmax", "intrin/_m_pfmin", "intrin/_m_pfmul", "intrin/_m_pfnacc", "intrin/_m_pfpnacc", "intrin/_m_pfrcp", "intrin/_m_pfrcpit1", "intrin/_m_pfrcpit2", "intrin/_m_pfrsqit1", "intrin/_m_pfrsqrt", "intrin/_m_pfsub", "intrin/_m_pfsubr", "intrin/_m_pi2fd", "intrin/_m_pi2fw", "intrin/_m_pinsrw", "intrin/_m_pmaddwd", "intrin/_m_pmaxsw", "intrin/_m_pmaxub", "intrin/_m_pminsw", "intrin/_m_pminub", "intrin/_m_pmovmskb", "intrin/_m_pmulhrw", "intrin/_m_pmulhuw", "intrin/_m_pmulhw", "intrin/_m_pmullw", "intrin/_m_por", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_m_psadbw", "intrin/_m_pshufw", "intrin/_m_pslld", "intrin/_m_pslldi", "intrin/_m_psllq", "intrin/_m_psllqi", "intrin/_m_psllw", "intrin/_m_psllwi", "intrin/_m_psrad", "intrin/_m_psradi", "intrin/_m_psraw", "intrin/_m_psrawi", "intrin/_m_psrld", "intrin/_m_psrldi", "intrin/_m_psrlq", "intrin/_m_psrlqi", "intrin/_m_psrlw", "intrin/_m_psrlwi", "intrin/_m_psubb", "intrin/_m_psubd", "intrin/_m_psubsb", "intrin/_m_psubsw", "intrin/_m_psubusb", "intrin/_m_psubusw", "intrin/_m_psubw", "intrin/_m_pswapd", "intrin/_m_punpckhbw", "intrin/_m_punpckhdq", "intrin/_m_punpckhwd", "intrin/_m_punpcklbw", "intrin/_m_punpckldq", "intrin/_m_punpcklwd", "intrin/_m_pxor", "intrin/_m_to_float", "intrin/_m_to_int", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_abs_pi16", "intrin/_mm_abs_pi32", "intrin/_mm_abs_pi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "mmintrin/_mm_add_pi8", "mmintrin/_mm_add_pi16", "mmintrin/_mm_add_pi32", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_si64", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "mmintrin/_mm_adds_pi8", "mmintrin/_mm_adds_pi16", "mmintrin/_mm_adds_pu8", "mmintrin/_mm_adds_pu16", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_alignr_pi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "mmintrin/_mm_and_si64", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "mmintrin/_mm_andnot_si64", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "mmintrin/_mm_cmpeq_pi8", "mmintrin/_mm_cmpeq_pi16", "mmintrin/_mm_cmpeq_pi32", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "mmintrin/_mm_cmpgt_pi8", "mmintrin/_mm_cmpgt_pi16", "mmintrin/_mm_cmpgt_pi32", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_pi2ps", "intrin/_mm_cvt_ps2pi", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_pi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtpi32_pd", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "mmintrin/_mm_cvtsi32_si64", "mmintrin/_mm_cvtsi64_si32", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtt_ps2pi", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttpd_pi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "mmintrin/_mm_empty", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_pi16", "intrin/_mm_hadd_pi32", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "intrin/_mm_hadds_pi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_pi16", "intrin/_mm_hsub_pi32", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "intrin/_mm_hsubs_pi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "mmintrin/_mm_madd_pi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "intrin/_mm_maddubs_pi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_movepi64_pi64", "intrin/_mm_movpi64_epi64", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mul_su32", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "mmintrin/_mm_mulhi_pi16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mulhrs_pi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "mmintrin/_mm_mullo_pi16", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "mmintrin/_mm_or_si64", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "mmintrin/_mm_packs_pi16", "mmintrin/_mm_packs_pi32", "mmintrin/_mm_packs_pu16", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_pi16", "intrin/_mm_set_pi32", "intrin/_mm_set_pi8", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_set1_pi16", "intrin/_mm_set1_pi32", "intrin/_mm_set1_pi8", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi64", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_pi16", "intrin/_mm_setr_pi32", "intrin/_mm_setr_pi8", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_setzero_si64", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_pi8", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sign_pi16", "intrin/_mm_sign_pi32", "intrin/_mm_sign_pi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "mmintrin/_mm_sll_pi16", "mmintrin/_mm_sll_pi32", "mmintrin/_mm_sll_si64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "mmintrin/_mm_slli_pi16", "mmintrin/_mm_slli_pi32", "mmintrin/_mm_slli_si64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "mmintrin/_mm_sra_pi16", "mmintrin/_mm_sra_pi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "mmintrin/_mm_srai_pi16", "mmintrin/_mm_srai_pi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "mmintrin/_mm_srl_pi16", "mmintrin/_mm_srl_pi32", "mmintrin/_mm_srl_si64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "mmintrin/_mm_srli_pi16", "mmintrin/_mm_srli_pi32", "mmintrin/_mm_srli_si64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_pi", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "mmintrin/_mm_sub_pi8", "mmintrin/_mm_sub_pi16", "mmintrin/_mm_sub_pi32", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_si64", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "mmintrin/_mm_subs_pi8", "mmintrin/_mm_subs_pi16", "mmintrin/_mm_subs_pu8", "mmintrin/_mm_subs_pu16", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "mmintrin/_mm_unpackhi_pi8", "mmintrin/_mm_unpackhi_pi16", "mmintrin/_mm_unpackhi_pi32", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "mmintrin/_mm_unpacklo_pi8", "mmintrin/_mm_unpacklo_pi16", "mmintrin/_mm_unpacklo_pi32", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "mmintrin/_mm_xor_si64", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pext_u32", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rorx_u32", "intrin/_rsm", "immintrin/_sarx_i32", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shrx_u32", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_Store_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_tzcnt_u32", "ammintrin/_tzmsk_u32", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xsave", "immintrin/_xsaveopt", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_m_maskmovq", "XMMINTRIN/_m_pavgb", "XMMINTRIN/_m_pavgw", "XMMINTRIN/_m_pextrw", "XMMINTRIN/_m_pinsrw", "XMMINTRIN/_m_pmaxsw", "XMMINTRIN/_m_pmaxub", "XMMINTRIN/_m_pminsw", "XMMINTRIN/_m_pminub", "XMMINTRIN/_m_pmovmskb", "XMMINTRIN/_m_pmulhuw", "XMMINTRIN/_m_psadbw", "XMMINTRIN/_m_pshufw", "XMMINTRIN/_mm_avg_pu16", "XMMINTRIN/_mm_avg_pu8", "XMMINTRIN/_mm_cvt_pi2ps", "XMMINTRIN/_mm_cvt_ps2pi", "XMMINTRIN/_mm_cvtpi32_ps", "XMMINTRIN/_mm_cvtps_pi32", "XMMINTRIN/_mm_cvtt_ps2pi", "XMMINTRIN/_mm_cvttps_pi32", "XMMINTRIN/_mm_extract_pi16", "XMMINTRIN/_mm_insert_pi16", "XMMINTRIN/_mm_maskmove_si64", "XMMINTRIN/_mm_max_pi16", "XMMINTRIN/_mm_max_pu8", "XMMINTRIN/_mm_min_pi16", "XMMINTRIN/_mm_min_pu8", "XMMINTRIN/_mm_movemask_pi8", "XMMINTRIN/_mm_mulhi_pu16", "XMMINTRIN/_mm_sad_pu8", "XMMINTRIN/_mm_shuffle_pi16", "XMMINTRIN/_mm_stream_pi"] -helpviewer_keywords: ["cl.exe compiler, intrinsics", "intrinsics, x86", "_addcarry_u16 x86 intrinsic", "_addcarry_u32 x86 intrinsic", "_addcarry_u8 x86 intrinsic", "_addcarryx_u32 x86 intrinsic", "_andn_u32 x86 intrinsic", "_bextr_u32 x86 intrinsic", "_bextri_u32 x86 intrinsic", "_blcfill_u32 x86 intrinsic", "_blci_u32 x86 intrinsic", "_blcic_u32 x86 intrinsic", "_blcmsk_u32 x86 intrinsic", "_blcs_u32 x86 intrinsic", "_blsfill_u32 x86 intrinsic", "_blsi_u32 x86 intrinsic", "_blsic_u32 x86 intrinsic", "_blsmsk_u32 x86 intrinsic", "_blsr_u32 x86 intrinsic", "_bzhi_u32 x86 intrinsic", "_clac x86 intrinsic", "_fxrstor x86 intrinsic", "_fxsave x86 intrinsic", "_invpcid x86 intrinsic", "_lgdt x86 intrinsic", "_load_be_u16 x86 intrinsic", "_loadbe_i16 x86 intrinsic", "_load_be_u32 x86 intrinsic", "_loadbe_i32 x86 intrinsic", "__llwpcb x86 intrinsic", "__lwpins32 x86 intrinsic", "__lwpval32 x86 intrinsic", "_lzcnt_u32 x86 intrinsic", "_m_empty x86 intrinsic", "_m_femms x86 intrinsic", "_m_from_float x86 intrinsic", "_m_from_int x86 intrinsic", "_m_maskmovq x86 intrinsic", "_m_packssdw x86 intrinsic", "_m_packsswb x86 intrinsic", "_m_packuswb x86 intrinsic", "_m_paddb x86 intrinsic", "_m_paddd x86 intrinsic", "_m_paddsb x86 intrinsic", "_m_paddsw x86 intrinsic", "_m_paddusb x86 intrinsic", "_m_paddusw x86 intrinsic", "_m_paddw x86 intrinsic", "_m_pand x86 intrinsic", "_m_pandn x86 intrinsic", "_m_pavgb x86 intrinsic", "_m_pavgusb x86 intrinsic", "_m_pavgw x86 intrinsic", "_m_pcmpeqb x86 intrinsic", "_m_pcmpeqd x86 intrinsic", "_m_pcmpeqw x86 intrinsic", "_m_pcmpgtb x86 intrinsic", "_m_pcmpgtd x86 intrinsic", "_m_pcmpgtw x86 intrinsic", "_m_pextrw x86 intrinsic", "_m_pf2id x86 intrinsic", "_m_pf2iw x86 intrinsic", "_m_pfacc x86 intrinsic", "_m_pfadd x86 intrinsic", "_m_pfcmpeq x86 intrinsic", "_m_pfcmpge x86 intrinsic", "_m_pfcmpgt x86 intrinsic", "_m_pfmax x86 intrinsic", "_m_pfmin x86 intrinsic", "_m_pfmul x86 intrinsic", "_m_pfnacc x86 intrinsic", "_m_pfpnacc x86 intrinsic", "_m_pfrcp x86 intrinsic", "_m_pfrcpit1 x86 intrinsic", "_m_pfrcpit2 x86 intrinsic", "_m_pfrsqit1 x86 intrinsic", "_m_pfrsqrt x86 intrinsic", "_m_pfsub x86 intrinsic", "_m_pfsubr x86 intrinsic", "_m_pi2fd x86 intrinsic", "_m_pi2fw x86 intrinsic", "_m_pinsrw x86 intrinsic", "_m_pmaddwd x86 intrinsic", "_m_pmaxsw x86 intrinsic", "_m_pmaxub x86 intrinsic", "_m_pminsw x86 intrinsic", "_m_pminub x86 intrinsic", "_m_pmovmskb x86 intrinsic", "_m_pmulhrw x86 intrinsic", "_m_pmulhuw x86 intrinsic", "_m_pmulhw x86 intrinsic", "_m_pmullw x86 intrinsic", "_m_por x86 intrinsic", "_m_prefetch x86 intrinsic", "_m_prefetchw x86 intrinsic", "_m_psadbw x86 intrinsic", "_m_pshufw x86 intrinsic", "_m_pslld x86 intrinsic", "_m_pslldi x86 intrinsic", "_m_psllq x86 intrinsic", "_m_psllqi x86 intrinsic", "_m_psllw x86 intrinsic", "_m_psllwi x86 intrinsic", "_m_psrad x86 intrinsic", "_m_psradi x86 intrinsic", "_m_psraw x86 intrinsic", "_m_psrawi x86 intrinsic", "_m_psrld x86 intrinsic", "_m_psrldi x86 intrinsic", "_m_psrlq x86 intrinsic", "_m_psrlqi x86 intrinsic", "_m_psrlw x86 intrinsic", "_m_psrlwi x86 intrinsic", "_m_psubb x86 intrinsic", "_m_psubd x86 intrinsic", "_m_psubsb x86 intrinsic", "_m_psubsw x86 intrinsic", "_m_psubusb x86 intrinsic", "_m_psubusw x86 intrinsic", "_m_psubw x86 intrinsic", "_m_pswapd x86 intrinsic", "_m_punpckhbw x86 intrinsic", "_m_punpckhdq x86 intrinsic", "_m_punpckhwd x86 intrinsic", "_m_punpcklbw x86 intrinsic", "_m_punpckldq x86 intrinsic", "_m_punpcklwd x86 intrinsic", "_m_pxor x86 intrinsic", "_m_to_float x86 intrinsic", "_m_to_int x86 intrinsic", "_mm_abs_epi16 x86 intrinsic", "_mm_abs_epi32 x86 intrinsic", "_mm_abs_epi8 x86 intrinsic", "_mm_abs_pi16 x86 intrinsic", "_mm_abs_pi32 x86 intrinsic", "_mm_abs_pi8 x86 intrinsic", "_mm_add_epi16 x86 intrinsic", "_mm_add_epi32 x86 intrinsic", "_mm_add_epi64 x86 intrinsic", "_mm_add_epi8 x86 intrinsic", "_mm_add_pd x86 intrinsic", "_mm_add_pi8 x86 intrinsic", "_mm_add_pi16 x86 intrinsic", "_mm_add_pi32 x86 intrinsic", "_mm_add_ps x86 intrinsic", "_mm_add_sd x86 intrinsic", "_mm_add_si64 x86 intrinsic", "_mm_add_ss x86 intrinsic", "_mm_adds_epi16 x86 intrinsic", "_mm_adds_epi8 x86 intrinsic", "_mm_adds_epu16 x86 intrinsic", "_mm_adds_epu8 x86 intrinsic", "_mm_adds_pi8 x86 intrinsic", "_mm_adds_pi16 x86 intrinsic", "_mm_adds_pu8 x86 intrinsic", "_mm_adds_pu16 x86 intrinsic", "_mm_addsub_pd x86 intrinsic", "_mm_addsub_ps x86 intrinsic", "_mm_aesdec_si128 x86 intrinsic", "_mm_aesdeclast_si128 x86 intrinsic", "_mm_aesenc_si128 x86 intrinsic", "_mm_aesenclast_si128 x86 intrinsic", "_mm_aesimc_si128 x86 intrinsic", "_mm_aeskeygenassist_si128 x86 intrinsic", "_mm_alignr_epi8 x86 intrinsic", "_mm_alignr_pi8 x86 intrinsic", "_mm_and_pd x86 intrinsic", "_mm_and_ps x86 intrinsic", "_mm_and_si64 x86 intrinsic", "_mm_and_si128 x86 intrinsic", "_mm_andnot_pd x86 intrinsic", "_mm_andnot_ps x86 intrinsic", "_mm_andnot_si64 x86 intrinsic", "_mm_andnot_si128 x86 intrinsic", "_mm_avg_epu16 x86 intrinsic", "_mm_avg_epu8 x86 intrinsic", "_mm_blend_epi16 x86 intrinsic", "_mm_blend_epi32 x86 intrinsic", "_mm_blend_pd x86 intrinsic", "_mm_blend_ps x86 intrinsic", "_mm_blendv_epi8 x86 intrinsic", "_mm_blendv_pd x86 intrinsic", "_mm_blendv_ps x86 intrinsic", "_mm_broadcast_ss x86 intrinsic", "_mm_broadcastb_epi8 x86 intrinsic", "_mm_broadcastd_epi32 x86 intrinsic", "_mm_broadcastq_epi64 x86 intrinsic", "_mm_broadcastsd_pd x86 intrinsic", "_mm_broadcastss_ps x86 intrinsic", "_mm_broadcastw_epi16 x86 intrinsic", "_mm_castpd_ps x86 intrinsic", "_mm_castpd_si128 x86 intrinsic", "_mm_castps_pd x86 intrinsic", "_mm_castps_si128 x86 intrinsic", "_mm_castsi128_pd x86 intrinsic", "_mm_castsi128_ps x86 intrinsic", "_mm_clflush x86 intrinsic", "_mm_clmulepi64_si128 x86 intrinsic", "_mm_cmov_si128 x86 intrinsic", "_mm_cmp_pd x86 intrinsic", "_mm_cmp_ps x86 intrinsic", "_mm_cmp_sd x86 intrinsic", "_mm_cmp_ss x86 intrinsic", "_mm_cmpeq_epi16 x86 intrinsic", "_mm_cmpeq_epi32 x86 intrinsic", "_mm_cmpeq_epi64 x86 intrinsic", "_mm_cmpeq_epi8 x86 intrinsic", "_mm_cmpeq_pd x86 intrinsic", "_mm_cmpeq_pi8 x86 intrinsic", "_mm_cmpeq_pi16 x86 intrinsic", "_mm_cmpeq_pi32 x86 intrinsic", "_mm_cmpeq_ps x86 intrinsic", "_mm_cmpeq_sd x86 intrinsic", "_mm_cmpeq_ss x86 intrinsic", "_mm_cmpestra x86 intrinsic", "_mm_cmpestrc x86 intrinsic", "_mm_cmpestri x86 intrinsic", "_mm_cmpestrm x86 intrinsic", "_mm_cmpestro x86 intrinsic", "_mm_cmpestrs x86 intrinsic", "_mm_cmpestrz x86 intrinsic", "_mm_cmpge_pd x86 intrinsic", "_mm_cmpge_ps x86 intrinsic", "_mm_cmpge_sd x86 intrinsic", "_mm_cmpge_ss x86 intrinsic", "_mm_cmpgt_epi16 x86 intrinsic", "_mm_cmpgt_epi32 x86 intrinsic", "_mm_cmpgt_epi64 x86 intrinsic", "_mm_cmpgt_epi8 x86 intrinsic", "_mm_cmpgt_pi8 x86 intrinsic", "_mm_cmpgt_pi16 x86 intrinsic", "_mm_cmpgt_pi32 x86 intrinsic", "_mm_cmpgt_pd x86 intrinsic", "_mm_cmpgt_ps x86 intrinsic", "_mm_cmpgt_sd x86 intrinsic", "_mm_cmpgt_ss x86 intrinsic", "_mm_cmpistra x86 intrinsic", "_mm_cmpistrc x86 intrinsic", "_mm_cmpistri x86 intrinsic", "_mm_cmpistrm x86 intrinsic", "_mm_cmpistro x86 intrinsic", "_mm_cmpistrs x86 intrinsic", "_mm_cmpistrz x86 intrinsic", "_mm_cmple_pd x86 intrinsic", "_mm_cmple_ps x86 intrinsic", "_mm_cmple_sd x86 intrinsic", "_mm_cmple_ss x86 intrinsic", "_mm_cmplt_epi16 x86 intrinsic", "_mm_cmplt_epi32 x86 intrinsic", "_mm_cmplt_epi8 x86 intrinsic", "_mm_cmplt_pd x86 intrinsic", "_mm_cmplt_ps x86 intrinsic", "_mm_cmplt_sd x86 intrinsic", "_mm_cmplt_ss x86 intrinsic", "_mm_cmpneq_pd x86 intrinsic", "_mm_cmpneq_ps x86 intrinsic", "_mm_cmpneq_sd x86 intrinsic", "_mm_cmpneq_ss x86 intrinsic", "_mm_cmpnge_pd x86 intrinsic", "_mm_cmpnge_ps x86 intrinsic", "_mm_cmpnge_sd x86 intrinsic", "_mm_cmpnge_ss x86 intrinsic", "_mm_cmpngt_pd x86 intrinsic", "_mm_cmpngt_ps x86 intrinsic", "_mm_cmpngt_sd x86 intrinsic", "_mm_cmpngt_ss x86 intrinsic", "_mm_cmpnle_pd x86 intrinsic", "_mm_cmpnle_ps x86 intrinsic", "_mm_cmpnle_sd x86 intrinsic", "_mm_cmpnle_ss x86 intrinsic", "_mm_cmpnlt_pd x86 intrinsic", "_mm_cmpnlt_ps x86 intrinsic", "_mm_cmpnlt_sd x86 intrinsic", "_mm_cmpnlt_ss x86 intrinsic", "_mm_cmpord_pd x86 intrinsic", "_mm_cmpord_ps x86 intrinsic", "_mm_cmpord_sd x86 intrinsic", "_mm_cmpord_ss x86 intrinsic", "_mm_cmpunord_pd x86 intrinsic", "_mm_cmpunord_ps x86 intrinsic", "_mm_cmpunord_sd x86 intrinsic", "_mm_cmpunord_ss x86 intrinsic", "_mm_com_epi16 x86 intrinsic", "_mm_com_epi32 x86 intrinsic", "_mm_com_epi64 x86 intrinsic", "_mm_com_epi8 x86 intrinsic", "_mm_com_epu16 x86 intrinsic", "_mm_com_epu32 x86 intrinsic", "_mm_com_epu64 x86 intrinsic", "_mm_com_epu8 x86 intrinsic", "_mm_comieq_sd x86 intrinsic", "_mm_comieq_ss x86 intrinsic", "_mm_comige_sd x86 intrinsic", "_mm_comige_ss x86 intrinsic", "_mm_comigt_sd x86 intrinsic", "_mm_comigt_ss x86 intrinsic", "_mm_comile_sd x86 intrinsic", "_mm_comile_ss x86 intrinsic", "_mm_comilt_sd x86 intrinsic", "_mm_comilt_ss x86 intrinsic", "_mm_comineq_sd x86 intrinsic", "_mm_comineq_ss x86 intrinsic", "_mm_crc32_u16 x86 intrinsic", "_mm_crc32_u32 x86 intrinsic", "_mm_crc32_u8 x86 intrinsic", "_mm_cvt_pi2ps x86 intrinsic", "_mm_cvt_ps2pi x86 intrinsic", "_mm_cvt_si2ss x86 intrinsic", "_mm_cvt_ss2si x86 intrinsic", "_mm_cvtepi16_epi32 x86 intrinsic", "_mm_cvtepi16_epi64 x86 intrinsic", "_mm_cvtepi32_epi64 x86 intrinsic", "_mm_cvtepi32_pd x86 intrinsic", "_mm_cvtepi32_ps x86 intrinsic", "_mm_cvtepi8_epi16 x86 intrinsic", "_mm_cvtepi8_epi32 x86 intrinsic", "_mm_cvtepi8_epi64 x86 intrinsic", "_mm_cvtepu16_epi32 x86 intrinsic", "_mm_cvtepu16_epi64 x86 intrinsic", "_mm_cvtepu32_epi64 x86 intrinsic", "_mm_cvtepu8_epi16 x86 intrinsic", "_mm_cvtepu8_epi32 x86 intrinsic", "_mm_cvtepu8_epi64 x86 intrinsic", "_mm_cvtpd_epi32 x86 intrinsic", "_mm_cvtpd_pi32 x86 intrinsic", "_mm_cvtpd_ps x86 intrinsic", "_mm_cvtph_ps x86 intrinsic", "_mm_cvtpi32_pd x86 intrinsic", "_mm_cvtps_epi32 x86 intrinsic", "_mm_cvtps_pd x86 intrinsic", "_mm_cvtps_ph x86 intrinsic", "_mm_cvtsd_f64 x86 intrinsic", "_mm_cvtsd_si32 x86 intrinsic", "_mm_cvtsd_ss x86 intrinsic", "_mm_cvtsi128_si32 x86 intrinsic", "_mm_cvtsi32_sd x86 intrinsic", "_mm_cvtsi32_si128 x86 intrinsic", "_mm_cvtsi32_si64 x86 intrinsic", "_mm_cvtsi64_si32 x86 intrinsic", "_mm_cvtss_f32 x86 intrinsic", "_mm_cvtss_sd x86 intrinsic", "_mm_cvtt_ps2pi x86 intrinsic", "_mm_cvtt_ss2si x86 intrinsic", "_mm_cvttpd_epi32 x86 intrinsic", "_mm_cvttpd_pi32 x86 intrinsic", "_mm_cvttps_epi32 x86 intrinsic", "_mm_cvttsd_si32 x86 intrinsic", "_mm_div_pd x86 intrinsic", "_mm_div_ps x86 intrinsic", "_mm_div_sd x86 intrinsic", "_mm_div_ss x86 intrinsic", "_mm_dp_pd x86 intrinsic", "_mm_dp_ps x86 intrinsic", "_mm_empty x86 intrinsic", "_mm_extract_epi16 x86 intrinsic", "_mm_extract_epi32 x86 intrinsic", "_mm_extract_epi8 x86 intrinsic", "_mm_extract_ps x86 intrinsic", "_mm_fmadd_pd x86 intrinsic", "_mm_fmadd_ps x86 intrinsic", "_mm_fmadd_sd x86 intrinsic", "_mm_fmadd_ss x86 intrinsic", "_mm_fmaddsub_pd x86 intrinsic", "_mm_fmaddsub_ps x86 intrinsic", "_mm_fmsub_pd x86 intrinsic", "_mm_fmsub_ps x86 intrinsic", "_mm_fmsub_sd x86 intrinsic", "_mm_fmsub_ss x86 intrinsic", "_mm_fmsubadd_pd x86 intrinsic", "_mm_fmsubadd_ps x86 intrinsic", "_mm_fnmadd_pd x86 intrinsic", "_mm_fnmadd_ps x86 intrinsic", "_mm_fnmadd_sd x86 intrinsic", "_mm_fnmadd_ss x86 intrinsic", "_mm_fnmsub_pd x86 intrinsic", "_mm_fnmsub_ps x86 intrinsic", "_mm_fnmsub_sd x86 intrinsic", "_mm_fnmsub_ss x86 intrinsic", "_mm_frcz_pd x86 intrinsic", "_mm_frcz_ps x86 intrinsic", "_mm_frcz_sd x86 intrinsic", "_mm_frcz_ss x86 intrinsic", "_mm_getcsr x86 intrinsic", "_mm_hadd_epi16 x86 intrinsic", "_mm_hadd_epi32 x86 intrinsic", "_mm_hadd_pd x86 intrinsic", "_mm_hadd_pi16 x86 intrinsic", "_mm_hadd_pi32 x86 intrinsic", "_mm_hadd_ps x86 intrinsic", "_mm_haddd_epi16 x86 intrinsic", "_mm_haddd_epi8 x86 intrinsic", "_mm_haddd_epu16 x86 intrinsic", "_mm_haddd_epu8 x86 intrinsic", "_mm_haddq_epi16 x86 intrinsic", "_mm_haddq_epi32 x86 intrinsic", "_mm_haddq_epi8 x86 intrinsic", "_mm_haddq_epu16 x86 intrinsic", "_mm_haddq_epu32 x86 intrinsic", "_mm_haddq_epu8 x86 intrinsic", "_mm_hadds_epi16 x86 intrinsic", "_mm_hadds_pi16 x86 intrinsic", "_mm_haddw_epi8 x86 intrinsic", "_mm_haddw_epu8 x86 intrinsic", "_mm_hsub_epi16 x86 intrinsic", "_mm_hsub_epi32 x86 intrinsic", "_mm_hsub_pd x86 intrinsic", "_mm_hsub_pi16 x86 intrinsic", "_mm_hsub_pi32 x86 intrinsic", "_mm_hsub_ps x86 intrinsic", "_mm_hsubd_epi16 x86 intrinsic", "_mm_hsubq_epi32 x86 intrinsic", "_mm_hsubs_epi16 x86 intrinsic", "_mm_hsubs_pi16 x86 intrinsic", "_mm_hsubw_epi8 x86 intrinsic", "_mm_i32gather_epi32 x86 intrinsic", "_mm_i32gather_epi64 x86 intrinsic", "_mm_i32gather_pd x86 intrinsic", "_mm_i32gather_ps x86 intrinsic", "_mm_i64gather_epi32 x86 intrinsic", "_mm_i64gather_epi64 x86 intrinsic", "_mm_i64gather_pd x86 intrinsic", "_mm_i64gather_ps x86 intrinsic", "_mm_insert_epi16 x86 intrinsic", "_mm_insert_epi32 x86 intrinsic", "_mm_insert_epi8 x86 intrinsic", "_mm_insert_ps x86 intrinsic", "_mm_lddqu_si128 x86 intrinsic", "_mm_lfence x86 intrinsic", "_mm_load_pd x86 intrinsic", "_mm_load_ps x86 intrinsic", "_mm_load_ps1 x86 intrinsic", "_mm_load_sd x86 intrinsic", "_mm_load_si128 x86 intrinsic", "_mm_load_ss x86 intrinsic", "_mm_load1_pd x86 intrinsic", "_mm_loaddup_pd x86 intrinsic", "_mm_loadh_pd x86 intrinsic", "_mm_loadh_pi x86 intrinsic", "_mm_loadl_epi64 x86 intrinsic", "_mm_loadl_pd x86 intrinsic", "_mm_loadl_pi x86 intrinsic", "_mm_loadr_pd x86 intrinsic", "_mm_loadr_ps x86 intrinsic", "_mm_loadu_pd x86 intrinsic", "_mm_loadu_ps x86 intrinsic", "_mm_loadu_si128 x86 intrinsic", "_mm_macc_epi16 x86 intrinsic", "_mm_macc_epi32 x86 intrinsic", "_mm_macc_pd x86 intrinsic", "_mm_macc_ps x86 intrinsic", "_mm_macc_sd x86 intrinsic", "_mm_macc_ss x86 intrinsic", "_mm_maccd_epi16 x86 intrinsic", "_mm_macchi_epi32 x86 intrinsic", "_mm_macclo_epi32 x86 intrinsic", "_mm_maccs_epi16 x86 intrinsic", "_mm_maccs_epi32 x86 intrinsic", "_mm_maccsd_epi16 x86 intrinsic", "_mm_maccshi_epi32 x86 intrinsic", "_mm_maccslo_epi32 x86 intrinsic", "_mm_madd_epi16 x86 intrinsic", "_mm_madd_pi16 x86 intrinsic", "_mm_maddd_epi16 x86 intrinsic", "_mm_maddsd_epi16 x86 intrinsic", "_mm_maddsub_pd x86 intrinsic", "_mm_maddsub_ps x86 intrinsic", "_mm_maddubs_epi16 x86 intrinsic", "_mm_maddubs_pi16 x86 intrinsic", "_mm_mask_i32gather_epi32 x86 intrinsic", "_mm_mask_i32gather_epi64 x86 intrinsic", "_mm_mask_i32gather_pd x86 intrinsic", "_mm_mask_i32gather_ps x86 intrinsic", "_mm_mask_i64gather_epi32 x86 intrinsic", "_mm_mask_i64gather_epi64 x86 intrinsic", "_mm_mask_i64gather_pd x86 intrinsic", "_mm_mask_i64gather_ps x86 intrinsic", "_mm_maskload_epi32 x86 intrinsic", "_mm_maskload_epi64 x86 intrinsic", "_mm_maskload_pd x86 intrinsic", "_mm_maskload_ps x86 intrinsic", "_mm_maskmoveu_si128 x86 intrinsic", "_mm_maskstore_epi32 x86 intrinsic", "_mm_maskstore_epi64 x86 intrinsic", "_mm_maskstore_pd x86 intrinsic", "_mm_maskstore_ps x86 intrinsic", "_mm_max_epi16 x86 intrinsic", "_mm_max_epi32 x86 intrinsic", "_mm_max_epi8 x86 intrinsic", "_mm_max_epu16 x86 intrinsic", "_mm_max_epu32 x86 intrinsic", "_mm_max_epu8 x86 intrinsic", "_mm_max_pd x86 intrinsic", "_mm_max_ps x86 intrinsic", "_mm_max_sd x86 intrinsic", "_mm_max_ss x86 intrinsic", "_mm_mfence x86 intrinsic", "_mm_min_epi16 x86 intrinsic", "_mm_min_epi32 x86 intrinsic", "_mm_min_epi8 x86 intrinsic", "_mm_min_epu16 x86 intrinsic", "_mm_min_epu32 x86 intrinsic", "_mm_min_epu8 x86 intrinsic", "_mm_min_pd x86 intrinsic", "_mm_min_ps x86 intrinsic", "_mm_min_sd x86 intrinsic", "_mm_min_ss x86 intrinsic", "_mm_minpos_epu16 x86 intrinsic", "_mm_monitor x86 intrinsic", "_mm_move_epi64 x86 intrinsic", "_mm_move_sd x86 intrinsic", "_mm_move_ss x86 intrinsic", "_mm_movedup_pd x86 intrinsic", "_mm_movehdup_ps x86 intrinsic", "_mm_movehl_ps x86 intrinsic", "_mm_moveldup_ps x86 intrinsic", "_mm_movelh_ps x86 intrinsic", "_mm_movemask_epi8 x86 intrinsic", "_mm_movemask_pd x86 intrinsic", "_mm_movemask_ps x86 intrinsic", "_mm_movepi64_pi64 x86 intrinsic", "_mm_movpi64_epi64 x86 intrinsic", "_mm_mpsadbw_epu8 x86 intrinsic", "_mm_msub_pd x86 intrinsic", "_mm_msub_ps x86 intrinsic", "_mm_msub_sd x86 intrinsic", "_mm_msub_ss x86 intrinsic", "_mm_msubadd_pd x86 intrinsic", "_mm_msubadd_ps x86 intrinsic", "_mm_mul_epi32 x86 intrinsic", "_mm_mul_epu32 x86 intrinsic", "_mm_mul_pd x86 intrinsic", "_mm_mul_ps x86 intrinsic", "_mm_mul_sd x86 intrinsic", "_mm_mul_ss x86 intrinsic", "_mm_mul_su32 x86 intrinsic", "_mm_mulhi_epi16 x86 intrinsic", "_mm_mulhi_epu16 x86 intrinsic", "_mm_mulhi_pi16 x86 intrinsic", "_mm_mulhrs_epi16 x86 intrinsic", "_mm_mulhrs_pi16 x86 intrinsic", "_mm_mullo_epi16 x86 intrinsic", "_mm_mullo_epi32 x86 intrinsic", "_mm_mullo_pi16 x86 intrinsic", "_mm_mwait x86 intrinsic", "_mm_nmacc_pd x86 intrinsic", "_mm_nmacc_ps x86 intrinsic", "_mm_nmacc_sd x86 intrinsic", "_mm_nmacc_ss x86 intrinsic", "_mm_nmsub_pd x86 intrinsic", "_mm_nmsub_ps x86 intrinsic", "_mm_nmsub_sd x86 intrinsic", "_mm_nmsub_ss x86 intrinsic", "_mm_or_pd x86 intrinsic", "_mm_or_ps x86 intrinsic", "_mm_or_si64 x86 intrinsic", "_mm_or_si128 x86 intrinsic", "_mm_packs_epi16 x86 intrinsic", "_mm_packs_epi32 x86 intrinsic", "_mm_packs_pi16 x86 intrinsic", "_mm_packs_pi32 x86 intrinsic", "_mm_packs_pu16 x86 intrinsic", "_mm_packus_epi16 x86 intrinsic", "_mm_packus_epi32 x86 intrinsic", "_mm_pause x86 intrinsic", "_mm_perm_epi8 x86 intrinsic", "_mm_permute_pd x86 intrinsic", "_mm_permute_ps x86 intrinsic", "_mm_permute2_pd x86 intrinsic", "_mm_permute2_ps x86 intrinsic", "_mm_permutevar_pd x86 intrinsic", "_mm_permutevar_ps x86 intrinsic", "_mm_popcnt_u32 x86 intrinsic", "_mm_prefetch x86 intrinsic", "_mm_rcp_ps x86 intrinsic", "_mm_rcp_ss x86 intrinsic", "_mm_rot_epi16 x86 intrinsic", "_mm_rot_epi32 x86 intrinsic", "_mm_rot_epi64 x86 intrinsic", "_mm_rot_epi8 x86 intrinsic", "_mm_roti_epi16 x86 intrinsic", "_mm_roti_epi32 x86 intrinsic", "_mm_roti_epi64 x86 intrinsic", "_mm_roti_epi8 x86 intrinsic", "_mm_round_pd x86 intrinsic", "_mm_round_ps x86 intrinsic", "_mm_round_sd x86 intrinsic", "_mm_round_ss x86 intrinsic", "_mm_rsqrt_ps x86 intrinsic", "_mm_rsqrt_ss x86 intrinsic", "_mm_sad_epu8 x86 intrinsic", "_mm_set_epi16 x86 intrinsic", "_mm_set_epi32 x86 intrinsic", "_mm_set_epi64 x86 intrinsic", "_mm_set_epi8 x86 intrinsic", "_mm_set_pd x86 intrinsic", "_mm_set_pi16 x86 intrinsic", "_mm_set_pi32 x86 intrinsic", "_mm_set_pi8 x86 intrinsic", "_mm_set_ps x86 intrinsic", "_mm_set_ps1 x86 intrinsic", "_mm_set_sd x86 intrinsic", "_mm_set_ss x86 intrinsic", "_mm_set1_epi16 x86 intrinsic", "_mm_set1_epi32 x86 intrinsic", "_mm_set1_epi64 x86 intrinsic", "_mm_set1_epi8 x86 intrinsic", "_mm_set1_pd x86 intrinsic", "_mm_set1_pi16 x86 intrinsic", "_mm_set1_pi32 x86 intrinsic", "_mm_set1_pi8 x86 intrinsic", "_mm_setcsr x86 intrinsic", "_mm_setl_epi64 x86 intrinsic", "_mm_setr_epi16 x86 intrinsic", "_mm_setr_epi32 x86 intrinsic", "_mm_setr_epi64 x86 intrinsic", "_mm_setr_epi8 x86 intrinsic", "_mm_setr_pd x86 intrinsic", "_mm_setr_pi16 x86 intrinsic", "_mm_setr_pi32 x86 intrinsic", "_mm_setr_pi8 x86 intrinsic", "_mm_setr_ps x86 intrinsic", "_mm_setzero_pd x86 intrinsic", "_mm_setzero_ps x86 intrinsic", "_mm_setzero_si128 x86 intrinsic", "_mm_setzero_si64 x86 intrinsic", "_mm_sfence x86 intrinsic", "_mm_sha_epi16 x86 intrinsic", "_mm_sha_epi32 x86 intrinsic", "_mm_sha_epi64 x86 intrinsic", "_mm_sha_epi8 x86 intrinsic", "_mm_shl_epi16 x86 intrinsic", "_mm_shl_epi32 x86 intrinsic", "_mm_shl_epi64 x86 intrinsic", "_mm_shl_epi8 x86 intrinsic", "_mm_shuffle_epi32 x86 intrinsic", "_mm_shuffle_epi8 x86 intrinsic", "_mm_shuffle_pd x86 intrinsic", "_mm_shuffle_pi8 x86 intrinsic", "_mm_shuffle_ps x86 intrinsic", "_mm_shufflehi_epi16 x86 intrinsic", "_mm_shufflelo_epi16 x86 intrinsic", "_mm_sign_epi16 x86 intrinsic", "_mm_sign_epi32 x86 intrinsic", "_mm_sign_epi8 x86 intrinsic", "_mm_sign_pi16 x86 intrinsic", "_mm_sign_pi32 x86 intrinsic", "_mm_sign_pi8 x86 intrinsic", "_mm_sll_epi16 x86 intrinsic", "_mm_sll_epi32 x86 intrinsic", "_mm_sll_epi64 x86 intrinsic", "_mm_sll_pi16 x86 intrinsic", "_mm_sll_pi32 x86 intrinsic", "_mm_sll_si64 x86 intrinsic", "_mm_slli_epi16 x86 intrinsic", "_mm_slli_epi32 x86 intrinsic", "_mm_slli_epi64 x86 intrinsic", "_mm_slli_pi16 x86 intrinsic", "_mm_slli_pi32 x86 intrinsic", "_mm_slli_si64 x86 intrinsic", "_mm_slli_si128 x86 intrinsic", "_mm_sllv_epi32 x86 intrinsic", "_mm_sllv_epi64 x86 intrinsic", "_mm_sqrt_pd x86 intrinsic", "_mm_sqrt_ps x86 intrinsic", "_mm_sqrt_sd x86 intrinsic", "_mm_sqrt_ss x86 intrinsic", "_mm_sra_epi16 x86 intrinsic", "_mm_sra_epi32 x86 intrinsic", "_mm_sra_pi16 x86 intrinsic", "_mm_sra_pi32 x86 intrinsic", "_mm_srai_epi16 x86 intrinsic", "_mm_srai_epi32 x86 intrinsic", "_mm_srai_pi16 x86 intrinsic", "_mm_srai_pi32 x86 intrinsic", "_mm_srav_epi32 x86 intrinsic", "_mm_srl_epi16 x86 intrinsic", "_mm_srl_epi32 x86 intrinsic", "_mm_srl_epi64 x86 intrinsic", "_mm_srl_pi16 x86 intrinsic", "_mm_srl_pi32 x86 intrinsic", "_mm_srl_si64 x86 intrinsic", "_mm_srli_epi16 x86 intrinsic", "_mm_srli_epi32 x86 intrinsic", "_mm_srli_epi64 x86 intrinsic", "_mm_srli_pi16 x86 intrinsic", "_mm_srli_pi32 x86 intrinsic", "_mm_srli_si64 x86 intrinsic", "_mm_srli_si128 x86 intrinsic", "_mm_srlv_epi32 x86 intrinsic", "_mm_srlv_epi64 x86 intrinsic", "_mm_store_pd x86 intrinsic", "_mm_store_ps x86 intrinsic", "_mm_store_ps1 x86 intrinsic", "_mm_store_sd x86 intrinsic", "_mm_store_si128 x86 intrinsic", "_mm_store_ss x86 intrinsic", "_mm_store1_pd x86 intrinsic", "_mm_storeh_pd x86 intrinsic", "_mm_storeh_pi x86 intrinsic", "_mm_storel_epi64 x86 intrinsic", "_mm_storel_pd x86 intrinsic", "_mm_storel_pi x86 intrinsic", "_mm_storer_pd x86 intrinsic", "_mm_storer_ps x86 intrinsic", "_mm_storeu_pd x86 intrinsic", "_mm_storeu_ps x86 intrinsic", "_mm_storeu_si128 x86 intrinsic", "_mm_stream_load_si128 x86 intrinsic", "_mm_stream_pd x86 intrinsic", "_mm_stream_pi x86 intrinsic", "_mm_stream_ps x86 intrinsic", "_mm_stream_si128 x86 intrinsic", "_mm_stream_si32 x86 intrinsic", "_mm_sub_epi16 x86 intrinsic", "_mm_sub_epi32 x86 intrinsic", "_mm_sub_epi64 x86 intrinsic", "_mm_sub_epi8 x86 intrinsic", "_mm_sub_pd x86 intrinsic", "_mm_sub_pi8 x86 intrinsic", "_mm_sub_pi16 x86 intrinsic", "_mm_sub_pi32 x86 intrinsic", "_mm_sub_ps x86 intrinsic", "_mm_sub_sd x86 intrinsic", "_mm_sub_si64 x86 intrinsic", "_mm_sub_ss x86 intrinsic", "_mm_subs_epi16 x86 intrinsic", "_mm_subs_epi8 x86 intrinsic", "_mm_subs_epu16 x86 intrinsic", "_mm_subs_epu8 x86 intrinsic", "_mm_subs_pi8 x86 intrinsic", "_mm_subs_pi16 x86 intrinsic", "_mm_subs_pu8 x86 intrinsic", "_mm_subs_pu16 x86 intrinsic", "_mm_testc_pd x86 intrinsic", "_mm_testc_ps x86 intrinsic", "_mm_testc_si128 x86 intrinsic", "_mm_testnzc_pd x86 intrinsic", "_mm_testnzc_ps x86 intrinsic", "_mm_testnzc_si128 x86 intrinsic", "_mm_testz_pd x86 intrinsic", "_mm_testz_ps x86 intrinsic", "_mm_testz_si128 x86 intrinsic", "_mm_ucomieq_sd x86 intrinsic", "_mm_ucomieq_ss x86 intrinsic", "_mm_ucomige_sd x86 intrinsic", "_mm_ucomige_ss x86 intrinsic", "_mm_ucomigt_sd x86 intrinsic", "_mm_ucomigt_ss x86 intrinsic", "_mm_ucomile_sd x86 intrinsic", "_mm_ucomile_ss x86 intrinsic", "_mm_ucomilt_sd x86 intrinsic", "_mm_ucomilt_ss x86 intrinsic", "_mm_ucomineq_sd x86 intrinsic", "_mm_ucomineq_ss x86 intrinsic", "_mm_unpackhi_epi16 x86 intrinsic", "_mm_unpackhi_epi32 x86 intrinsic", "_mm_unpackhi_epi64 x86 intrinsic", "_mm_unpackhi_epi8 x86 intrinsic", "_mm_unpackhi_pd x86 intrinsic", "_mm_unpackhi_pi8 x86 intrinsic", "_mm_unpackhi_pi16 x86 intrinsic", "_mm_unpackhi_pi32 x86 intrinsic", "_mm_unpackhi_ps x86 intrinsic", "_mm_unpacklo_epi16 x86 intrinsic", "_mm_unpacklo_epi32 x86 intrinsic", "_mm_unpacklo_epi64 x86 intrinsic", "_mm_unpacklo_epi8 x86 intrinsic", "_mm_unpacklo_pd x86 intrinsic", "_mm_unpacklo_pi8 x86 intrinsic", "_mm_unpacklo_pi16 x86 intrinsic", "_mm_unpacklo_pi32 x86 intrinsic", "_mm_unpacklo_ps x86 intrinsic", "_mm_xor_pd x86 intrinsic", "_mm_xor_ps x86 intrinsic", "_mm_xor_si64 x86 intrinsic", "_mm_xor_si128 x86 intrinsic", "_mm256_abs_epi16 x86 intrinsic", "_mm256_abs_epi32 x86 intrinsic", "_mm256_abs_epi8 x86 intrinsic", "_mm256_add_epi16 x86 intrinsic", "_mm256_add_epi32 x86 intrinsic", "_mm256_add_epi64 x86 intrinsic", "_mm256_add_epi8 x86 intrinsic", "_mm256_add_pd x86 intrinsic", "_mm256_add_ps x86 intrinsic", "_mm256_adds_epi16 x86 intrinsic", "_mm256_adds_epi8 x86 intrinsic", "_mm256_adds_epu16 x86 intrinsic", "_mm256_adds_epu8 x86 intrinsic", "_mm256_addsub_pd x86 intrinsic", "_mm256_addsub_ps x86 intrinsic", "_mm256_alignr_epi8 x86 intrinsic", "_mm256_and_pd x86 intrinsic", "_mm256_and_ps x86 intrinsic", "_mm256_and_si256 x86 intrinsic", "_mm256_andnot_pd x86 intrinsic", "_mm256_andnot_ps x86 intrinsic", "_mm256_andnot_si256 x86 intrinsic", "_mm256_avg_epu16 x86 intrinsic", "_mm256_avg_epu8 x86 intrinsic", "_mm256_blend_epi16 x86 intrinsic", "_mm256_blend_epi32 x86 intrinsic", "_mm256_blend_pd x86 intrinsic", "_mm256_blend_ps x86 intrinsic", "_mm256_blendv_epi8 x86 intrinsic", "_mm256_blendv_pd x86 intrinsic", "_mm256_blendv_ps x86 intrinsic", "_mm256_broadcast_pd x86 intrinsic", "_mm256_broadcast_ps x86 intrinsic", "_mm256_broadcast_sd x86 intrinsic", "_mm256_broadcast_ss x86 intrinsic", "_mm256_broadcastb_epi8 x86 intrinsic", "_mm256_broadcastd_epi32 x86 intrinsic", "_mm256_broadcastq_epi64 x86 intrinsic", "_mm256_broadcastsd_pd x86 intrinsic", "_mm256_broadcastsi128_si256 x86 intrinsic", "_mm256_broadcastss_ps x86 intrinsic", "_mm256_broadcastw_epi16 x86 intrinsic", "_mm256_castpd_ps x86 intrinsic", "_mm256_castpd_si256 x86 intrinsic", "_mm256_castpd128_pd256 x86 intrinsic", "_mm256_castpd256_pd128 x86 intrinsic", "_mm256_castps_pd x86 intrinsic", "_mm256_castps_si256 x86 intrinsic", "_mm256_castps128_ps256 x86 intrinsic", "_mm256_castps256_ps128 x86 intrinsic", "_mm256_castsi128_si256 x86 intrinsic", "_mm256_castsi256_pd x86 intrinsic", "_mm256_castsi256_ps x86 intrinsic", "_mm256_castsi256_si128 x86 intrinsic", "_mm256_cmov_si256 x86 intrinsic", "_mm256_cmp_pd x86 intrinsic", "_mm256_cmp_ps x86 intrinsic", "_mm256_cmpeq_epi16 x86 intrinsic", "_mm256_cmpeq_epi32 x86 intrinsic", "_mm256_cmpeq_epi64 x86 intrinsic", "_mm256_cmpeq_epi8 x86 intrinsic", "_mm256_cmpgt_epi16 x86 intrinsic", "_mm256_cmpgt_epi32 x86 intrinsic", "_mm256_cmpgt_epi64 x86 intrinsic", "_mm256_cmpgt_epi8 x86 intrinsic", "_mm256_cvtepi16_epi32 x86 intrinsic", "_mm256_cvtepi16_epi64 x86 intrinsic", "_mm256_cvtepi32_epi64 x86 intrinsic", "_mm256_cvtepi32_pd x86 intrinsic", "_mm256_cvtepi32_ps x86 intrinsic", "_mm256_cvtepi8_epi16 x86 intrinsic", "_mm256_cvtepi8_epi32 x86 intrinsic", "_mm256_cvtepi8_epi64 x86 intrinsic", "_mm256_cvtepu16_epi32 x86 intrinsic", "_mm256_cvtepu16_epi64 x86 intrinsic", "_mm256_cvtepu32_epi64 x86 intrinsic", "_mm256_cvtepu8_epi16 x86 intrinsic", "_mm256_cvtepu8_epi32 x86 intrinsic", "_mm256_cvtepu8_epi64 x86 intrinsic", "_mm256_cvtpd_epi32 x86 intrinsic", "_mm256_cvtpd_ps x86 intrinsic", "_mm256_cvtph_ps x86 intrinsic", "_mm256_cvtps_epi32 x86 intrinsic", "_mm256_cvtps_pd x86 intrinsic", "_mm256_cvtps_ph x86 intrinsic", "_mm256_cvttpd_epi32 x86 intrinsic", "_mm256_cvttps_epi32 x86 intrinsic", "_mm256_div_pd x86 intrinsic", "_mm256_div_ps x86 intrinsic", "_mm256_dp_ps x86 intrinsic", "_mm256_extractf128_pd x86 intrinsic", "_mm256_extractf128_ps x86 intrinsic", "_mm256_extractf128_si256 x86 intrinsic", "_mm256_extracti128_si256 x86 intrinsic", "_mm256_fmadd_pd x86 intrinsic", "_mm256_fmadd_ps x86 intrinsic", "_mm256_fmaddsub_pd x86 intrinsic", "_mm256_fmaddsub_ps x86 intrinsic", "_mm256_fmsub_pd x86 intrinsic", "_mm256_fmsub_ps x86 intrinsic", "_mm256_fmsubadd_pd x86 intrinsic", "_mm256_fmsubadd_ps x86 intrinsic", "_mm256_fnmadd_pd x86 intrinsic", "_mm256_fnmadd_ps x86 intrinsic", "_mm256_fnmsub_pd x86 intrinsic", "_mm256_fnmsub_ps x86 intrinsic", "_mm256_frcz_pd x86 intrinsic", "_mm256_frcz_ps x86 intrinsic", "_mm256_hadd_epi16 x86 intrinsic", "_mm256_hadd_epi32 x86 intrinsic", "_mm256_hadd_pd x86 intrinsic", "_mm256_hadd_ps x86 intrinsic", "_mm256_hadds_epi16 x86 intrinsic", "_mm256_hsub_epi16 x86 intrinsic", "_mm256_hsub_epi32 x86 intrinsic", "_mm256_hsub_pd x86 intrinsic", "_mm256_hsub_ps x86 intrinsic", "_mm256_hsubs_epi16 x86 intrinsic", "_mm256_i32gather_epi32 x86 intrinsic", "_mm256_i32gather_epi64 x86 intrinsic", "_mm256_i32gather_pd x86 intrinsic", "_mm256_i32gather_ps x86 intrinsic", "_mm256_i64gather_epi32 x86 intrinsic", "_mm256_i64gather_epi64 x86 intrinsic", "_mm256_i64gather_pd x86 intrinsic", "_mm256_i64gather_ps x86 intrinsic", "_mm256_insertf128_pd x86 intrinsic", "_mm256_insertf128_ps x86 intrinsic", "_mm256_insertf128_si256 x86 intrinsic", "_mm256_inserti128_si256 x86 intrinsic", "_mm256_lddqu_si256 x86 intrinsic", "_mm256_load_pd x86 intrinsic", "_mm256_load_ps x86 intrinsic", "_mm256_load_si256 x86 intrinsic", "_mm256_loadu_pd x86 intrinsic", "_mm256_loadu_ps x86 intrinsic", "_mm256_loadu_si256 x86 intrinsic", "_mm256_macc_pd x86 intrinsic", "_mm256_macc_ps x86 intrinsic", "_mm256_madd_epi16 x86 intrinsic", "_mm256_maddsub_pd x86 intrinsic", "_mm256_maddsub_ps x86 intrinsic", "_mm256_maddubs_epi16 x86 intrinsic", "_mm256_mask_i32gather_epi32 x86 intrinsic", "_mm256_mask_i32gather_epi64 x86 intrinsic", "_mm256_mask_i32gather_pd x86 intrinsic", "_mm256_mask_i32gather_ps x86 intrinsic", "_mm256_mask_i64gather_epi32 x86 intrinsic", "_mm256_mask_i64gather_epi64 x86 intrinsic", "_mm256_mask_i64gather_pd x86 intrinsic", "_mm256_mask_i64gather_ps x86 intrinsic", "_mm256_maskload_epi32 x86 intrinsic", "_mm256_maskload_epi64 x86 intrinsic", "_mm256_maskload_pd x86 intrinsic", "_mm256_maskload_ps x86 intrinsic", "_mm256_maskstore_epi32 x86 intrinsic", "_mm256_maskstore_epi64 x86 intrinsic", "_mm256_maskstore_pd x86 intrinsic", "_mm256_maskstore_ps x86 intrinsic", "_mm256_max_epi16 x86 intrinsic", "_mm256_max_epi32 x86 intrinsic", "_mm256_max_epi8 x86 intrinsic", "_mm256_max_epu16 x86 intrinsic", "_mm256_max_epu32 x86 intrinsic", "_mm256_max_epu8 x86 intrinsic", "_mm256_max_pd x86 intrinsic", "_mm256_max_ps x86 intrinsic", "_mm256_min_epi16 x86 intrinsic", "_mm256_min_epi32 x86 intrinsic", "_mm256_min_epi8 x86 intrinsic", "_mm256_min_epu16 x86 intrinsic", "_mm256_min_epu32 x86 intrinsic", "_mm256_min_epu8 x86 intrinsic", "_mm256_min_pd x86 intrinsic", "_mm256_min_ps x86 intrinsic", "_mm256_movedup_pd x86 intrinsic", "_mm256_movehdup_ps x86 intrinsic", "_mm256_moveldup_ps x86 intrinsic", "_mm256_movemask_epi8 x86 intrinsic", "_mm256_movemask_pd x86 intrinsic", "_mm256_movemask_ps x86 intrinsic", "_mm256_mpsadbw_epu8 x86 intrinsic", "_mm256_msub_pd x86 intrinsic", "_mm256_msub_ps x86 intrinsic", "_mm256_msubadd_pd x86 intrinsic", "_mm256_msubadd_ps x86 intrinsic", "_mm256_mul_epi32 x86 intrinsic", "_mm256_mul_epu32 x86 intrinsic", "_mm256_mul_pd x86 intrinsic", "_mm256_mul_ps x86 intrinsic", "_mm256_mulhi_epi16 x86 intrinsic", "_mm256_mulhi_epu16 x86 intrinsic", "_mm256_mulhrs_epi16 x86 intrinsic", "_mm256_mullo_epi16 x86 intrinsic", "_mm256_mullo_epi32 x86 intrinsic", "_mm256_nmacc_pd x86 intrinsic", "_mm256_nmacc_ps x86 intrinsic", "_mm256_nmsub_pd x86 intrinsic", "_mm256_nmsub_ps x86 intrinsic", "_mm256_or_pd x86 intrinsic", "_mm256_or_ps x86 intrinsic", "_mm256_or_si256 x86 intrinsic", "_mm256_packs_epi16 x86 intrinsic", "_mm256_packs_epi32 x86 intrinsic", "_mm256_packus_epi16 x86 intrinsic", "_mm256_packus_epi32 x86 intrinsic", "_mm256_permute_pd x86 intrinsic", "_mm256_permute_ps x86 intrinsic", "_mm256_permute2_pd x86 intrinsic", "_mm256_permute2_ps x86 intrinsic", "_mm256_permute2f128_pd x86 intrinsic", "_mm256_permute2f128_ps x86 intrinsic", "_mm256_permute2f128_si256 x86 intrinsic", "_mm256_permute2x128_si256 x86 intrinsic", "_mm256_permute4x64_epi64 x86 intrinsic", "_mm256_permute4x64_pd x86 intrinsic", "_mm256_permutevar_pd x86 intrinsic", "_mm256_permutevar_ps x86 intrinsic", "_mm256_permutevar8x32_epi32 x86 intrinsic", "_mm256_permutevar8x32_ps x86 intrinsic", "_mm256_rcp_ps x86 intrinsic", "_mm256_round_pd x86 intrinsic", "_mm256_round_ps x86 intrinsic", "_mm256_rsqrt_ps x86 intrinsic", "_mm256_sad_epu8 x86 intrinsic", "_mm256_set_epi16 x86 intrinsic", "_mm256_set_epi32 x86 intrinsic", "_mm256_set_epi8 x86 intrinsic", "_mm256_set_pd x86 intrinsic", "_mm256_set_ps x86 intrinsic", "_mm256_set1_epi16 x86 intrinsic", "_mm256_set1_epi32 x86 intrinsic", "_mm256_set1_epi8 x86 intrinsic", "_mm256_set1_pd x86 intrinsic", "_mm256_set1_ps x86 intrinsic", "_mm256_setr_epi16 x86 intrinsic", "_mm256_setr_epi32 x86 intrinsic", "_mm256_setr_epi8 x86 intrinsic", "_mm256_setr_pd x86 intrinsic", "_mm256_setr_ps x86 intrinsic", "_mm256_setzero_pd x86 intrinsic", "_mm256_setzero_ps x86 intrinsic", "_mm256_setzero_si256 x86 intrinsic", "_mm256_shuffle_epi32 x86 intrinsic", "_mm256_shuffle_epi8 x86 intrinsic", "_mm256_shuffle_pd x86 intrinsic", "_mm256_shuffle_ps x86 intrinsic", "_mm256_shufflehi_epi16 x86 intrinsic", "_mm256_shufflelo_epi16 x86 intrinsic", "_mm256_sign_epi16 x86 intrinsic", "_mm256_sign_epi32 x86 intrinsic", "_mm256_sign_epi8 x86 intrinsic", "_mm256_sll_epi16 x86 intrinsic", "_mm256_sll_epi32 x86 intrinsic", "_mm256_sll_epi64 x86 intrinsic", "_mm256_slli_epi16 x86 intrinsic", "_mm256_slli_epi32 x86 intrinsic", "_mm256_slli_epi64 x86 intrinsic", "_mm256_slli_si256 x86 intrinsic", "_mm256_sllv_epi32 x86 intrinsic", "_mm256_sllv_epi64 x86 intrinsic", "_mm256_sqrt_pd x86 intrinsic", "_mm256_sqrt_ps x86 intrinsic", "_mm256_sra_epi16 x86 intrinsic", "_mm256_sra_epi32 x86 intrinsic", "_mm256_srai_epi16 x86 intrinsic", "_mm256_srai_epi32 x86 intrinsic", "_mm256_srav_epi32 x86 intrinsic", "_mm256_srl_epi16 x86 intrinsic", "_mm256_srl_epi32 x86 intrinsic", "_mm256_srl_epi64 x86 intrinsic", "_mm256_srli_epi16 x86 intrinsic", "_mm256_srli_epi32 x86 intrinsic", "_mm256_srli_epi64 x86 intrinsic", "_mm256_srli_si256 x86 intrinsic", "_mm256_srlv_epi32 x86 intrinsic", "_mm256_srlv_epi64 x86 intrinsic", "_mm256_store_pd x86 intrinsic", "_mm256_store_ps x86 intrinsic", "_mm256_store_si256 x86 intrinsic", "_mm256_storeu_pd x86 intrinsic", "_mm256_storeu_ps x86 intrinsic", "_mm256_storeu_si256 x86 intrinsic", "_mm256_stream_load_si256 x86 intrinsic", "_mm256_stream_pd x86 intrinsic", "_mm256_stream_ps x86 intrinsic", "_mm256_stream_si256 x86 intrinsic", "_mm256_sub_epi16 x86 intrinsic", "_mm256_sub_epi32 x86 intrinsic", "_mm256_sub_epi64 x86 intrinsic", "_mm256_sub_epi8 x86 intrinsic", "_mm256_sub_pd x86 intrinsic", "_mm256_sub_ps x86 intrinsic", "_mm256_subs_epi16 x86 intrinsic", "_mm256_subs_epi8 x86 intrinsic", "_mm256_subs_epu16 x86 intrinsic", "_mm256_subs_epu8 x86 intrinsic", "_mm256_testc_pd x86 intrinsic", "_mm256_testc_ps x86 intrinsic", "_mm256_testc_si256 x86 intrinsic", "_mm256_testnzc_pd x86 intrinsic", "_mm256_testnzc_ps x86 intrinsic", "_mm256_testnzc_si256 x86 intrinsic", "_mm256_testz_pd x86 intrinsic", "_mm256_testz_ps x86 intrinsic", "_mm256_testz_si256 x86 intrinsic", "_mm256_unpackhi_epi16 x86 intrinsic", "_mm256_unpackhi_epi32 x86 intrinsic", "_mm256_unpackhi_epi64 x86 intrinsic", "_mm256_unpackhi_epi8 x86 intrinsic", "_mm256_unpackhi_pd x86 intrinsic", "_mm256_unpackhi_ps x86 intrinsic", "_mm256_unpacklo_epi16 x86 intrinsic", "_mm256_unpacklo_epi32 x86 intrinsic", "_mm256_unpacklo_epi64 x86 intrinsic", "_mm256_unpacklo_epi8 x86 intrinsic", "_mm256_unpacklo_pd x86 intrinsic", "_mm256_unpacklo_ps x86 intrinsic", "_mm256_xor_pd x86 intrinsic", "_mm256_xor_ps x86 intrinsic", "_mm256_xor_si256 x86 intrinsic", "_mm256_zeroall x86 intrinsic", "_mm256_zeroupper x86 intrinsic", "_mulx_u32 x86 intrinsic", "__nvreg_restore_fence x86 intrinsic", "__nvreg_save_fence x86 intrinsic", "_pdep_u32 x86 intrinsic", "_pext_u32 x86 intrinsic", "_rdrand16_step x86 intrinsic", "_rdrand32_step x86 intrinsic", "_rdseed16_step x86 intrinsic", "_rdseed32_step x86 intrinsic", "_rorx_u32 x86 intrinsic", "_rsm x86 intrinsic", "_sarx_i32 x86 intrinsic", "_sgdt x86 intrinsic", "_shlx_u32 x86 intrinsic", "_shrx_u32 x86 intrinsic", "__slwpcb x86 intrinsic", "_stac x86 intrinsic", "_store_be_u16 x86 intrinsic", "_storebe_i16 x86 intrinsic", "_store_be_u32 x86 intrinsic", "_storebe_i32 x86 intrinsic", "_Store_HLERelease x86 intrinsic", "_StorePointer_HLERelease x86 intrinsic", "_subborrow_u16 x86 intrinsic", "_subborrow_u32 x86 intrinsic", "_subborrow_u8 x86 intrinsic", "_t1mskc_u32 x86 intrinsic", "_tzcnt_u32 x86 intrinsic", "_tzmsk_u32 x86 intrinsic", "_xabort x86 intrinsic", "_xbegin x86 intrinsic", "_xend x86 intrinsic", "_xgetbv x86 intrinsic", "_xrstor x86 intrinsic", "_xsave x86 intrinsic", "_xsaveopt x86 intrinsic", "_xsetbv x86 intrinsic", "_xtest x86 intrinsic"] +ms.date: 08/30/2022 +f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "ammintrin/_andn_u32", "ammintrin/_bextr_u32", "ammintrin/_bextri_u32", "ammintrin/_blcfill_u32", "ammintrin/_blci_u32", "ammintrin/_blcic_u32", "ammintrin/_blcmsk_u32", "ammintrin/_blcs_u32", "ammintrin/_blsfill_u32", "ammintrin/_blsi_u32", "ammintrin/_blsic_u32", "ammintrin/_blsmsk_u32", "ammintrin/_blsr_u32", "immintrin/_bzhi_u32", "immintrin/_castf32_u32", "immintrin/_castf64_u64", "immintrin/_castu32_f32", "immintrin/_castu64_f64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxsave", "immintrin/_invpcid", "intrin/_lgdt", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "ammintrin/__llwpcb", "ammintrin/__lwpins32", "ammintrin/__lwpval32", "ammintrin/_lzcnt_u32", "intrin/_m_empty", "intrin/_m_femms", "intrin/_m_from_float", "intrin/_m_from_int", "intrin/_m_maskmovq", "intrin/_m_packssdw", "intrin/_m_packsswb", "intrin/_m_packuswb", "intrin/_m_paddb", "intrin/_m_paddd", "intrin/_m_paddsb", "intrin/_m_paddsw", "intrin/_m_paddusb", "intrin/_m_paddusw", "intrin/_m_paddw", "intrin/_m_pand", "intrin/_m_pandn", "intrin/_m_pavgb", "intrin/_m_pavgusb", "intrin/_m_pavgw", "intrin/_m_pcmpeqb", "intrin/_m_pcmpeqd", "intrin/_m_pcmpeqw", "intrin/_m_pcmpgtb", "intrin/_m_pcmpgtd", "intrin/_m_pcmpgtw", "intrin/_m_pextrw", "intrin/_m_pf2id", "intrin/_m_pf2iw", "intrin/_m_pfacc", "intrin/_m_pfadd", "intrin/_m_pfcmpeq", "intrin/_m_pfcmpge", "intrin/_m_pfcmpgt", "intrin/_m_pfmax", "intrin/_m_pfmin", "intrin/_m_pfmul", "intrin/_m_pfnacc", "intrin/_m_pfpnacc", "intrin/_m_pfrcp", "intrin/_m_pfrcpit1", "intrin/_m_pfrcpit2", "intrin/_m_pfrsqit1", "intrin/_m_pfrsqrt", "intrin/_m_pfsub", "intrin/_m_pfsubr", "intrin/_m_pi2fd", "intrin/_m_pi2fw", "intrin/_m_pinsrw", "intrin/_m_pmaddwd", "intrin/_m_pmaxsw", "intrin/_m_pmaxub", "intrin/_m_pminsw", "intrin/_m_pminub", "intrin/_m_pmovmskb", "intrin/_m_pmulhrw", "intrin/_m_pmulhuw", "intrin/_m_pmulhw", "intrin/_m_pmullw", "intrin/_m_por", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_m_psadbw", "intrin/_m_pshufw", "intrin/_m_pslld", "intrin/_m_pslldi", "intrin/_m_psllq", "intrin/_m_psllqi", "intrin/_m_psllw", "intrin/_m_psllwi", "intrin/_m_psrad", "intrin/_m_psradi", "intrin/_m_psraw", "intrin/_m_psrawi", "intrin/_m_psrld", "intrin/_m_psrldi", "intrin/_m_psrlq", "intrin/_m_psrlqi", "intrin/_m_psrlw", "intrin/_m_psrlwi", "intrin/_m_psubb", "intrin/_m_psubd", "intrin/_m_psubsb", "intrin/_m_psubsw", "intrin/_m_psubusb", "intrin/_m_psubusw", "intrin/_m_psubw", "intrin/_m_pswapd", "intrin/_m_punpckhbw", "intrin/_m_punpckhdq", "intrin/_m_punpckhwd", "intrin/_m_punpcklbw", "intrin/_m_punpckldq", "intrin/_m_punpcklwd", "intrin/_m_pxor", "intrin/_m_to_float", "intrin/_m_to_int", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_abs_pi16", "intrin/_mm_abs_pi32", "intrin/_mm_abs_pi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "mmintrin/_mm_add_pi8", "mmintrin/_mm_add_pi16", "mmintrin/_mm_add_pi32", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_si64", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "mmintrin/_mm_adds_pi8", "mmintrin/_mm_adds_pi16", "mmintrin/_mm_adds_pu8", "mmintrin/_mm_adds_pu16", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_alignr_pi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "mmintrin/_mm_and_si64", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "mmintrin/_mm_andnot_si64", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "mmintrin/_mm_cmpeq_pi8", "mmintrin/_mm_cmpeq_pi16", "mmintrin/_mm_cmpeq_pi32", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "mmintrin/_mm_cmpgt_pi8", "mmintrin/_mm_cmpgt_pi16", "mmintrin/_mm_cmpgt_pi32", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_pi2ps", "intrin/_mm_cvt_ps2pi", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_pi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtpi32_pd", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "mmintrin/_mm_cvtsi32_si64", "mmintrin/_mm_cvtsi64_si32", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtt_ps2pi", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttpd_pi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "mmintrin/_mm_empty", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_pi16", "intrin/_mm_hadd_pi32", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "intrin/_mm_hadds_pi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_pi16", "intrin/_mm_hsub_pi32", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "intrin/_mm_hsubs_pi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "mmintrin/_mm_madd_pi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "intrin/_mm_maddubs_pi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_movepi64_pi64", "intrin/_mm_movpi64_epi64", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mul_su32", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "mmintrin/_mm_mulhi_pi16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mulhrs_pi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "mmintrin/_mm_mullo_pi16", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "mmintrin/_mm_or_si64", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "mmintrin/_mm_packs_pi16", "mmintrin/_mm_packs_pi32", "mmintrin/_mm_packs_pu16", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_pi16", "intrin/_mm_set_pi32", "intrin/_mm_set_pi8", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_set1_pi16", "intrin/_mm_set1_pi32", "intrin/_mm_set1_pi8", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi64", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_pi16", "intrin/_mm_setr_pi32", "intrin/_mm_setr_pi8", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_setzero_si64", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_pi8", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sign_pi16", "intrin/_mm_sign_pi32", "intrin/_mm_sign_pi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "mmintrin/_mm_sll_pi16", "mmintrin/_mm_sll_pi32", "mmintrin/_mm_sll_si64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "mmintrin/_mm_slli_pi16", "mmintrin/_mm_slli_pi32", "mmintrin/_mm_slli_si64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "mmintrin/_mm_sra_pi16", "mmintrin/_mm_sra_pi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "mmintrin/_mm_srai_pi16", "mmintrin/_mm_srai_pi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "mmintrin/_mm_srl_pi16", "mmintrin/_mm_srl_pi32", "mmintrin/_mm_srl_si64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "mmintrin/_mm_srli_pi16", "mmintrin/_mm_srli_pi32", "mmintrin/_mm_srli_si64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_pi", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "mmintrin/_mm_sub_pi8", "mmintrin/_mm_sub_pi16", "mmintrin/_mm_sub_pi32", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_si64", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "mmintrin/_mm_subs_pi8", "mmintrin/_mm_subs_pi16", "mmintrin/_mm_subs_pu8", "mmintrin/_mm_subs_pu16", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "mmintrin/_mm_unpackhi_pi8", "mmintrin/_mm_unpackhi_pi16", "mmintrin/_mm_unpackhi_pi32", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "mmintrin/_mm_unpacklo_pi8", "mmintrin/_mm_unpacklo_pi16", "mmintrin/_mm_unpacklo_pi32", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "mmintrin/_mm_xor_si64", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pext_u32", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rorx_u32", "intrin/_rsm", "immintrin/_sarx_i32", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shrx_u32", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_Store_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_tzcnt_u32", "ammintrin/_tzmsk_u32", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xsave", "immintrin/_xsaveopt", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_m_maskmovq", "XMMINTRIN/_m_pavgb", "XMMINTRIN/_m_pavgw", "XMMINTRIN/_m_pextrw", "XMMINTRIN/_m_pinsrw", "XMMINTRIN/_m_pmaxsw", "XMMINTRIN/_m_pmaxub", "XMMINTRIN/_m_pminsw", "XMMINTRIN/_m_pminub", "XMMINTRIN/_m_pmovmskb", "XMMINTRIN/_m_pmulhuw", "XMMINTRIN/_m_psadbw", "XMMINTRIN/_m_pshufw", "XMMINTRIN/_mm_avg_pu16", "XMMINTRIN/_mm_avg_pu8", "XMMINTRIN/_mm_cvt_pi2ps", "XMMINTRIN/_mm_cvt_ps2pi", "XMMINTRIN/_mm_cvtpi32_ps", "XMMINTRIN/_mm_cvtps_pi32", "XMMINTRIN/_mm_cvtt_ps2pi", "XMMINTRIN/_mm_cvttps_pi32", "XMMINTRIN/_mm_extract_pi16", "XMMINTRIN/_mm_insert_pi16", "XMMINTRIN/_mm_maskmove_si64", "XMMINTRIN/_mm_max_pi16", "XMMINTRIN/_mm_max_pu8", "XMMINTRIN/_mm_min_pi16", "XMMINTRIN/_mm_min_pu8", "XMMINTRIN/_mm_movemask_pi8", "XMMINTRIN/_mm_mulhi_pu16", "XMMINTRIN/_mm_sad_pu8", "XMMINTRIN/_mm_shuffle_pi16", "XMMINTRIN/_mm_stream_pi"] +helpviewer_keywords: ["cl.exe compiler, intrinsics", "intrinsics, x86", "_addcarry_u16 x86 intrinsic", "_addcarry_u32 x86 intrinsic", "_addcarry_u8 x86 intrinsic", "_addcarryx_u32 x86 intrinsic", "_andn_u32 x86 intrinsic", "_bextr_u32 x86 intrinsic", "_bextri_u32 x86 intrinsic", "_blcfill_u32 x86 intrinsic", "_blci_u32 x86 intrinsic", "_blcic_u32 x86 intrinsic", "_blcmsk_u32 x86 intrinsic", "_blcs_u32 x86 intrinsic", "_blsfill_u32 x86 intrinsic", "_blsi_u32 x86 intrinsic", "_blsic_u32 x86 intrinsic", "_blsmsk_u32 x86 intrinsic", "_blsr_u32 x86 intrinsic", "_bzhi_u32 x86 intrinsic", "_castf32_u32 x64 intrinsic", "_castf64_u64 x64 intrinsic", "_castu32_f32 x64 intrinsic", "_castu64_f64 x64 intrinsic", "_clac x86 intrinsic", "_fxrstor x86 intrinsic", "_fxsave x86 intrinsic", "_invpcid x86 intrinsic", "_lgdt x86 intrinsic", "_load_be_u16 x86 intrinsic", "_loadbe_i16 x86 intrinsic", "_load_be_u32 x86 intrinsic", "_loadbe_i32 x86 intrinsic", "__llwpcb x86 intrinsic", "__lwpins32 x86 intrinsic", "__lwpval32 x86 intrinsic", "_lzcnt_u32 x86 intrinsic", "_m_empty x86 intrinsic", "_m_femms x86 intrinsic", "_m_from_float x86 intrinsic", "_m_from_int x86 intrinsic", "_m_maskmovq x86 intrinsic", "_m_packssdw x86 intrinsic", "_m_packsswb x86 intrinsic", "_m_packuswb x86 intrinsic", "_m_paddb x86 intrinsic", "_m_paddd x86 intrinsic", "_m_paddsb x86 intrinsic", "_m_paddsw x86 intrinsic", "_m_paddusb x86 intrinsic", "_m_paddusw x86 intrinsic", "_m_paddw x86 intrinsic", "_m_pand x86 intrinsic", "_m_pandn x86 intrinsic", "_m_pavgb x86 intrinsic", "_m_pavgusb x86 intrinsic", "_m_pavgw x86 intrinsic", "_m_pcmpeqb x86 intrinsic", "_m_pcmpeqd x86 intrinsic", "_m_pcmpeqw x86 intrinsic", "_m_pcmpgtb x86 intrinsic", "_m_pcmpgtd x86 intrinsic", "_m_pcmpgtw x86 intrinsic", "_m_pextrw x86 intrinsic", "_m_pf2id x86 intrinsic", "_m_pf2iw x86 intrinsic", "_m_pfacc x86 intrinsic", "_m_pfadd x86 intrinsic", "_m_pfcmpeq x86 intrinsic", "_m_pfcmpge x86 intrinsic", "_m_pfcmpgt x86 intrinsic", "_m_pfmax x86 intrinsic", "_m_pfmin x86 intrinsic", "_m_pfmul x86 intrinsic", "_m_pfnacc x86 intrinsic", "_m_pfpnacc x86 intrinsic", "_m_pfrcp x86 intrinsic", "_m_pfrcpit1 x86 intrinsic", "_m_pfrcpit2 x86 intrinsic", "_m_pfrsqit1 x86 intrinsic", "_m_pfrsqrt x86 intrinsic", "_m_pfsub x86 intrinsic", "_m_pfsubr x86 intrinsic", "_m_pi2fd x86 intrinsic", "_m_pi2fw x86 intrinsic", "_m_pinsrw x86 intrinsic", "_m_pmaddwd x86 intrinsic", "_m_pmaxsw x86 intrinsic", "_m_pmaxub x86 intrinsic", "_m_pminsw x86 intrinsic", "_m_pminub x86 intrinsic", "_m_pmovmskb x86 intrinsic", "_m_pmulhrw x86 intrinsic", "_m_pmulhuw x86 intrinsic", "_m_pmulhw x86 intrinsic", "_m_pmullw x86 intrinsic", "_m_por x86 intrinsic", "_m_prefetch x86 intrinsic", "_m_prefetchw x86 intrinsic", "_m_psadbw x86 intrinsic", "_m_pshufw x86 intrinsic", "_m_pslld x86 intrinsic", "_m_pslldi x86 intrinsic", "_m_psllq x86 intrinsic", "_m_psllqi x86 intrinsic", "_m_psllw x86 intrinsic", "_m_psllwi x86 intrinsic", "_m_psrad x86 intrinsic", "_m_psradi x86 intrinsic", "_m_psraw x86 intrinsic", "_m_psrawi x86 intrinsic", "_m_psrld x86 intrinsic", "_m_psrldi x86 intrinsic", "_m_psrlq x86 intrinsic", "_m_psrlqi x86 intrinsic", "_m_psrlw x86 intrinsic", "_m_psrlwi x86 intrinsic", "_m_psubb x86 intrinsic", "_m_psubd x86 intrinsic", "_m_psubsb x86 intrinsic", "_m_psubsw x86 intrinsic", "_m_psubusb x86 intrinsic", "_m_psubusw x86 intrinsic", "_m_psubw x86 intrinsic", "_m_pswapd x86 intrinsic", "_m_punpckhbw x86 intrinsic", "_m_punpckhdq x86 intrinsic", "_m_punpckhwd x86 intrinsic", "_m_punpcklbw x86 intrinsic", "_m_punpckldq x86 intrinsic", "_m_punpcklwd x86 intrinsic", "_m_pxor x86 intrinsic", "_m_to_float x86 intrinsic", "_m_to_int x86 intrinsic", "_mm_abs_epi16 x86 intrinsic", "_mm_abs_epi32 x86 intrinsic", "_mm_abs_epi8 x86 intrinsic", "_mm_abs_pi16 x86 intrinsic", "_mm_abs_pi32 x86 intrinsic", "_mm_abs_pi8 x86 intrinsic", "_mm_add_epi16 x86 intrinsic", "_mm_add_epi32 x86 intrinsic", "_mm_add_epi64 x86 intrinsic", "_mm_add_epi8 x86 intrinsic", "_mm_add_pd x86 intrinsic", "_mm_add_pi8 x86 intrinsic", "_mm_add_pi16 x86 intrinsic", "_mm_add_pi32 x86 intrinsic", "_mm_add_ps x86 intrinsic", "_mm_add_sd x86 intrinsic", "_mm_add_si64 x86 intrinsic", "_mm_add_ss x86 intrinsic", "_mm_adds_epi16 x86 intrinsic", "_mm_adds_epi8 x86 intrinsic", "_mm_adds_epu16 x86 intrinsic", "_mm_adds_epu8 x86 intrinsic", "_mm_adds_pi8 x86 intrinsic", "_mm_adds_pi16 x86 intrinsic", "_mm_adds_pu8 x86 intrinsic", "_mm_adds_pu16 x86 intrinsic", "_mm_addsub_pd x86 intrinsic", "_mm_addsub_ps x86 intrinsic", "_mm_aesdec_si128 x86 intrinsic", "_mm_aesdeclast_si128 x86 intrinsic", "_mm_aesenc_si128 x86 intrinsic", "_mm_aesenclast_si128 x86 intrinsic", "_mm_aesimc_si128 x86 intrinsic", "_mm_aeskeygenassist_si128 x86 intrinsic", "_mm_alignr_epi8 x86 intrinsic", "_mm_alignr_pi8 x86 intrinsic", "_mm_and_pd x86 intrinsic", "_mm_and_ps x86 intrinsic", "_mm_and_si64 x86 intrinsic", "_mm_and_si128 x86 intrinsic", "_mm_andnot_pd x86 intrinsic", "_mm_andnot_ps x86 intrinsic", "_mm_andnot_si64 x86 intrinsic", "_mm_andnot_si128 x86 intrinsic", "_mm_avg_epu16 x86 intrinsic", "_mm_avg_epu8 x86 intrinsic", "_mm_blend_epi16 x86 intrinsic", "_mm_blend_epi32 x86 intrinsic", "_mm_blend_pd x86 intrinsic", "_mm_blend_ps x86 intrinsic", "_mm_blendv_epi8 x86 intrinsic", "_mm_blendv_pd x86 intrinsic", "_mm_blendv_ps x86 intrinsic", "_mm_broadcast_ss x86 intrinsic", "_mm_broadcastb_epi8 x86 intrinsic", "_mm_broadcastd_epi32 x86 intrinsic", "_mm_broadcastq_epi64 x86 intrinsic", "_mm_broadcastsd_pd x86 intrinsic", "_mm_broadcastss_ps x86 intrinsic", "_mm_broadcastw_epi16 x86 intrinsic", "_mm_castpd_ps x86 intrinsic", "_mm_castpd_si128 x86 intrinsic", "_mm_castps_pd x86 intrinsic", "_mm_castps_si128 x86 intrinsic", "_mm_castsi128_pd x86 intrinsic", "_mm_castsi128_ps x86 intrinsic", "_mm_clflush x86 intrinsic", "_mm_clmulepi64_si128 x86 intrinsic", "_mm_cmov_si128 x86 intrinsic", "_mm_cmp_pd x86 intrinsic", "_mm_cmp_ps x86 intrinsic", "_mm_cmp_sd x86 intrinsic", "_mm_cmp_ss x86 intrinsic", "_mm_cmpeq_epi16 x86 intrinsic", "_mm_cmpeq_epi32 x86 intrinsic", "_mm_cmpeq_epi64 x86 intrinsic", "_mm_cmpeq_epi8 x86 intrinsic", "_mm_cmpeq_pd x86 intrinsic", "_mm_cmpeq_pi8 x86 intrinsic", "_mm_cmpeq_pi16 x86 intrinsic", "_mm_cmpeq_pi32 x86 intrinsic", "_mm_cmpeq_ps x86 intrinsic", "_mm_cmpeq_sd x86 intrinsic", "_mm_cmpeq_ss x86 intrinsic", "_mm_cmpestra x86 intrinsic", "_mm_cmpestrc x86 intrinsic", "_mm_cmpestri x86 intrinsic", "_mm_cmpestrm x86 intrinsic", "_mm_cmpestro x86 intrinsic", "_mm_cmpestrs x86 intrinsic", "_mm_cmpestrz x86 intrinsic", "_mm_cmpge_pd x86 intrinsic", "_mm_cmpge_ps x86 intrinsic", "_mm_cmpge_sd x86 intrinsic", "_mm_cmpge_ss x86 intrinsic", "_mm_cmpgt_epi16 x86 intrinsic", "_mm_cmpgt_epi32 x86 intrinsic", "_mm_cmpgt_epi64 x86 intrinsic", "_mm_cmpgt_epi8 x86 intrinsic", "_mm_cmpgt_pi8 x86 intrinsic", "_mm_cmpgt_pi16 x86 intrinsic", "_mm_cmpgt_pi32 x86 intrinsic", "_mm_cmpgt_pd x86 intrinsic", "_mm_cmpgt_ps x86 intrinsic", "_mm_cmpgt_sd x86 intrinsic", "_mm_cmpgt_ss x86 intrinsic", "_mm_cmpistra x86 intrinsic", "_mm_cmpistrc x86 intrinsic", "_mm_cmpistri x86 intrinsic", "_mm_cmpistrm x86 intrinsic", "_mm_cmpistro x86 intrinsic", "_mm_cmpistrs x86 intrinsic", "_mm_cmpistrz x86 intrinsic", "_mm_cmple_pd x86 intrinsic", "_mm_cmple_ps x86 intrinsic", "_mm_cmple_sd x86 intrinsic", "_mm_cmple_ss x86 intrinsic", "_mm_cmplt_epi16 x86 intrinsic", "_mm_cmplt_epi32 x86 intrinsic", "_mm_cmplt_epi8 x86 intrinsic", "_mm_cmplt_pd x86 intrinsic", "_mm_cmplt_ps x86 intrinsic", "_mm_cmplt_sd x86 intrinsic", "_mm_cmplt_ss x86 intrinsic", "_mm_cmpneq_pd x86 intrinsic", "_mm_cmpneq_ps x86 intrinsic", "_mm_cmpneq_sd x86 intrinsic", "_mm_cmpneq_ss x86 intrinsic", "_mm_cmpnge_pd x86 intrinsic", "_mm_cmpnge_ps x86 intrinsic", "_mm_cmpnge_sd x86 intrinsic", "_mm_cmpnge_ss x86 intrinsic", "_mm_cmpngt_pd x86 intrinsic", "_mm_cmpngt_ps x86 intrinsic", "_mm_cmpngt_sd x86 intrinsic", "_mm_cmpngt_ss x86 intrinsic", "_mm_cmpnle_pd x86 intrinsic", "_mm_cmpnle_ps x86 intrinsic", "_mm_cmpnle_sd x86 intrinsic", "_mm_cmpnle_ss x86 intrinsic", "_mm_cmpnlt_pd x86 intrinsic", "_mm_cmpnlt_ps x86 intrinsic", "_mm_cmpnlt_sd x86 intrinsic", "_mm_cmpnlt_ss x86 intrinsic", "_mm_cmpord_pd x86 intrinsic", "_mm_cmpord_ps x86 intrinsic", "_mm_cmpord_sd x86 intrinsic", "_mm_cmpord_ss x86 intrinsic", "_mm_cmpunord_pd x86 intrinsic", "_mm_cmpunord_ps x86 intrinsic", "_mm_cmpunord_sd x86 intrinsic", "_mm_cmpunord_ss x86 intrinsic", "_mm_com_epi16 x86 intrinsic", "_mm_com_epi32 x86 intrinsic", "_mm_com_epi64 x86 intrinsic", "_mm_com_epi8 x86 intrinsic", "_mm_com_epu16 x86 intrinsic", "_mm_com_epu32 x86 intrinsic", "_mm_com_epu64 x86 intrinsic", "_mm_com_epu8 x86 intrinsic", "_mm_comieq_sd x86 intrinsic", "_mm_comieq_ss x86 intrinsic", "_mm_comige_sd x86 intrinsic", "_mm_comige_ss x86 intrinsic", "_mm_comigt_sd x86 intrinsic", "_mm_comigt_ss x86 intrinsic", "_mm_comile_sd x86 intrinsic", "_mm_comile_ss x86 intrinsic", "_mm_comilt_sd x86 intrinsic", "_mm_comilt_ss x86 intrinsic", "_mm_comineq_sd x86 intrinsic", "_mm_comineq_ss x86 intrinsic", "_mm_crc32_u16 x86 intrinsic", "_mm_crc32_u32 x86 intrinsic", "_mm_crc32_u8 x86 intrinsic", "_mm_cvt_pi2ps x86 intrinsic", "_mm_cvt_ps2pi x86 intrinsic", "_mm_cvt_si2ss x86 intrinsic", "_mm_cvt_ss2si x86 intrinsic", "_mm_cvtepi16_epi32 x86 intrinsic", "_mm_cvtepi16_epi64 x86 intrinsic", "_mm_cvtepi32_epi64 x86 intrinsic", "_mm_cvtepi32_pd x86 intrinsic", "_mm_cvtepi32_ps x86 intrinsic", "_mm_cvtepi8_epi16 x86 intrinsic", "_mm_cvtepi8_epi32 x86 intrinsic", "_mm_cvtepi8_epi64 x86 intrinsic", "_mm_cvtepu16_epi32 x86 intrinsic", "_mm_cvtepu16_epi64 x86 intrinsic", "_mm_cvtepu32_epi64 x86 intrinsic", "_mm_cvtepu8_epi16 x86 intrinsic", "_mm_cvtepu8_epi32 x86 intrinsic", "_mm_cvtepu8_epi64 x86 intrinsic", "_mm_cvtpd_epi32 x86 intrinsic", "_mm_cvtpd_pi32 x86 intrinsic", "_mm_cvtpd_ps x86 intrinsic", "_mm_cvtph_ps x86 intrinsic", "_mm_cvtpi32_pd x86 intrinsic", "_mm_cvtps_epi32 x86 intrinsic", "_mm_cvtps_pd x86 intrinsic", "_mm_cvtps_ph x86 intrinsic", "_mm_cvtsd_f64 x86 intrinsic", "_mm_cvtsd_si32 x86 intrinsic", "_mm_cvtsd_ss x86 intrinsic", "_mm_cvtsi128_si32 x86 intrinsic", "_mm_cvtsi32_sd x86 intrinsic", "_mm_cvtsi32_si128 x86 intrinsic", "_mm_cvtsi32_si64 x86 intrinsic", "_mm_cvtsi64_si32 x86 intrinsic", "_mm_cvtss_f32 x86 intrinsic", "_mm_cvtss_sd x86 intrinsic", "_mm_cvtt_ps2pi x86 intrinsic", "_mm_cvtt_ss2si x86 intrinsic", "_mm_cvttpd_epi32 x86 intrinsic", "_mm_cvttpd_pi32 x86 intrinsic", "_mm_cvttps_epi32 x86 intrinsic", "_mm_cvttsd_si32 x86 intrinsic", "_mm_div_pd x86 intrinsic", "_mm_div_ps x86 intrinsic", "_mm_div_sd x86 intrinsic", "_mm_div_ss x86 intrinsic", "_mm_dp_pd x86 intrinsic", "_mm_dp_ps x86 intrinsic", "_mm_empty x86 intrinsic", "_mm_extract_epi16 x86 intrinsic", "_mm_extract_epi32 x86 intrinsic", "_mm_extract_epi8 x86 intrinsic", "_mm_extract_ps x86 intrinsic", "_mm_fmadd_pd x86 intrinsic", "_mm_fmadd_ps x86 intrinsic", "_mm_fmadd_sd x86 intrinsic", "_mm_fmadd_ss x86 intrinsic", "_mm_fmaddsub_pd x86 intrinsic", "_mm_fmaddsub_ps x86 intrinsic", "_mm_fmsub_pd x86 intrinsic", "_mm_fmsub_ps x86 intrinsic", "_mm_fmsub_sd x86 intrinsic", "_mm_fmsub_ss x86 intrinsic", "_mm_fmsubadd_pd x86 intrinsic", "_mm_fmsubadd_ps x86 intrinsic", "_mm_fnmadd_pd x86 intrinsic", "_mm_fnmadd_ps x86 intrinsic", "_mm_fnmadd_sd x86 intrinsic", "_mm_fnmadd_ss x86 intrinsic", "_mm_fnmsub_pd x86 intrinsic", "_mm_fnmsub_ps x86 intrinsic", "_mm_fnmsub_sd x86 intrinsic", "_mm_fnmsub_ss x86 intrinsic", "_mm_frcz_pd x86 intrinsic", "_mm_frcz_ps x86 intrinsic", "_mm_frcz_sd x86 intrinsic", "_mm_frcz_ss x86 intrinsic", "_mm_getcsr x86 intrinsic", "_mm_hadd_epi16 x86 intrinsic", "_mm_hadd_epi32 x86 intrinsic", "_mm_hadd_pd x86 intrinsic", "_mm_hadd_pi16 x86 intrinsic", "_mm_hadd_pi32 x86 intrinsic", "_mm_hadd_ps x86 intrinsic", "_mm_haddd_epi16 x86 intrinsic", "_mm_haddd_epi8 x86 intrinsic", "_mm_haddd_epu16 x86 intrinsic", "_mm_haddd_epu8 x86 intrinsic", "_mm_haddq_epi16 x86 intrinsic", "_mm_haddq_epi32 x86 intrinsic", "_mm_haddq_epi8 x86 intrinsic", "_mm_haddq_epu16 x86 intrinsic", "_mm_haddq_epu32 x86 intrinsic", "_mm_haddq_epu8 x86 intrinsic", "_mm_hadds_epi16 x86 intrinsic", "_mm_hadds_pi16 x86 intrinsic", "_mm_haddw_epi8 x86 intrinsic", "_mm_haddw_epu8 x86 intrinsic", "_mm_hsub_epi16 x86 intrinsic", "_mm_hsub_epi32 x86 intrinsic", "_mm_hsub_pd x86 intrinsic", "_mm_hsub_pi16 x86 intrinsic", "_mm_hsub_pi32 x86 intrinsic", "_mm_hsub_ps x86 intrinsic", "_mm_hsubd_epi16 x86 intrinsic", "_mm_hsubq_epi32 x86 intrinsic", "_mm_hsubs_epi16 x86 intrinsic", "_mm_hsubs_pi16 x86 intrinsic", "_mm_hsubw_epi8 x86 intrinsic", "_mm_i32gather_epi32 x86 intrinsic", "_mm_i32gather_epi64 x86 intrinsic", "_mm_i32gather_pd x86 intrinsic", "_mm_i32gather_ps x86 intrinsic", "_mm_i64gather_epi32 x86 intrinsic", "_mm_i64gather_epi64 x86 intrinsic", "_mm_i64gather_pd x86 intrinsic", "_mm_i64gather_ps x86 intrinsic", "_mm_insert_epi16 x86 intrinsic", "_mm_insert_epi32 x86 intrinsic", "_mm_insert_epi8 x86 intrinsic", "_mm_insert_ps x86 intrinsic", "_mm_lddqu_si128 x86 intrinsic", "_mm_lfence x86 intrinsic", "_mm_load_pd x86 intrinsic", "_mm_load_ps x86 intrinsic", "_mm_load_ps1 x86 intrinsic", "_mm_load_sd x86 intrinsic", "_mm_load_si128 x86 intrinsic", "_mm_load_ss x86 intrinsic", "_mm_load1_pd x86 intrinsic", "_mm_loaddup_pd x86 intrinsic", "_mm_loadh_pd x86 intrinsic", "_mm_loadh_pi x86 intrinsic", "_mm_loadl_epi64 x86 intrinsic", "_mm_loadl_pd x86 intrinsic", "_mm_loadl_pi x86 intrinsic", "_mm_loadr_pd x86 intrinsic", "_mm_loadr_ps x86 intrinsic", "_mm_loadu_pd x86 intrinsic", "_mm_loadu_ps x86 intrinsic", "_mm_loadu_si128 x86 intrinsic", "_mm_macc_epi16 x86 intrinsic", "_mm_macc_epi32 x86 intrinsic", "_mm_macc_pd x86 intrinsic", "_mm_macc_ps x86 intrinsic", "_mm_macc_sd x86 intrinsic", "_mm_macc_ss x86 intrinsic", "_mm_maccd_epi16 x86 intrinsic", "_mm_macchi_epi32 x86 intrinsic", "_mm_macclo_epi32 x86 intrinsic", "_mm_maccs_epi16 x86 intrinsic", "_mm_maccs_epi32 x86 intrinsic", "_mm_maccsd_epi16 x86 intrinsic", "_mm_maccshi_epi32 x86 intrinsic", "_mm_maccslo_epi32 x86 intrinsic", "_mm_madd_epi16 x86 intrinsic", "_mm_madd_pi16 x86 intrinsic", "_mm_maddd_epi16 x86 intrinsic", "_mm_maddsd_epi16 x86 intrinsic", "_mm_maddsub_pd x86 intrinsic", "_mm_maddsub_ps x86 intrinsic", "_mm_maddubs_epi16 x86 intrinsic", "_mm_maddubs_pi16 x86 intrinsic", "_mm_mask_i32gather_epi32 x86 intrinsic", "_mm_mask_i32gather_epi64 x86 intrinsic", "_mm_mask_i32gather_pd x86 intrinsic", "_mm_mask_i32gather_ps x86 intrinsic", "_mm_mask_i64gather_epi32 x86 intrinsic", "_mm_mask_i64gather_epi64 x86 intrinsic", "_mm_mask_i64gather_pd x86 intrinsic", "_mm_mask_i64gather_ps x86 intrinsic", "_mm_maskload_epi32 x86 intrinsic", "_mm_maskload_epi64 x86 intrinsic", "_mm_maskload_pd x86 intrinsic", "_mm_maskload_ps x86 intrinsic", "_mm_maskmoveu_si128 x86 intrinsic", "_mm_maskstore_epi32 x86 intrinsic", "_mm_maskstore_epi64 x86 intrinsic", "_mm_maskstore_pd x86 intrinsic", "_mm_maskstore_ps x86 intrinsic", "_mm_max_epi16 x86 intrinsic", "_mm_max_epi32 x86 intrinsic", "_mm_max_epi8 x86 intrinsic", "_mm_max_epu16 x86 intrinsic", "_mm_max_epu32 x86 intrinsic", "_mm_max_epu8 x86 intrinsic", "_mm_max_pd x86 intrinsic", "_mm_max_ps x86 intrinsic", "_mm_max_sd x86 intrinsic", "_mm_max_ss x86 intrinsic", "_mm_mfence x86 intrinsic", "_mm_min_epi16 x86 intrinsic", "_mm_min_epi32 x86 intrinsic", "_mm_min_epi8 x86 intrinsic", "_mm_min_epu16 x86 intrinsic", "_mm_min_epu32 x86 intrinsic", "_mm_min_epu8 x86 intrinsic", "_mm_min_pd x86 intrinsic", "_mm_min_ps x86 intrinsic", "_mm_min_sd x86 intrinsic", "_mm_min_ss x86 intrinsic", "_mm_minpos_epu16 x86 intrinsic", "_mm_monitor x86 intrinsic", "_mm_move_epi64 x86 intrinsic", "_mm_move_sd x86 intrinsic", "_mm_move_ss x86 intrinsic", "_mm_movedup_pd x86 intrinsic", "_mm_movehdup_ps x86 intrinsic", "_mm_movehl_ps x86 intrinsic", "_mm_moveldup_ps x86 intrinsic", "_mm_movelh_ps x86 intrinsic", "_mm_movemask_epi8 x86 intrinsic", "_mm_movemask_pd x86 intrinsic", "_mm_movemask_ps x86 intrinsic", "_mm_movepi64_pi64 x86 intrinsic", "_mm_movpi64_epi64 x86 intrinsic", "_mm_mpsadbw_epu8 x86 intrinsic", "_mm_msub_pd x86 intrinsic", "_mm_msub_ps x86 intrinsic", "_mm_msub_sd x86 intrinsic", "_mm_msub_ss x86 intrinsic", "_mm_msubadd_pd x86 intrinsic", "_mm_msubadd_ps x86 intrinsic", "_mm_mul_epi32 x86 intrinsic", "_mm_mul_epu32 x86 intrinsic", "_mm_mul_pd x86 intrinsic", "_mm_mul_ps x86 intrinsic", "_mm_mul_sd x86 intrinsic", "_mm_mul_ss x86 intrinsic", "_mm_mul_su32 x86 intrinsic", "_mm_mulhi_epi16 x86 intrinsic", "_mm_mulhi_epu16 x86 intrinsic", "_mm_mulhi_pi16 x86 intrinsic", "_mm_mulhrs_epi16 x86 intrinsic", "_mm_mulhrs_pi16 x86 intrinsic", "_mm_mullo_epi16 x86 intrinsic", "_mm_mullo_epi32 x86 intrinsic", "_mm_mullo_pi16 x86 intrinsic", "_mm_mwait x86 intrinsic", "_mm_nmacc_pd x86 intrinsic", "_mm_nmacc_ps x86 intrinsic", "_mm_nmacc_sd x86 intrinsic", "_mm_nmacc_ss x86 intrinsic", "_mm_nmsub_pd x86 intrinsic", "_mm_nmsub_ps x86 intrinsic", "_mm_nmsub_sd x86 intrinsic", "_mm_nmsub_ss x86 intrinsic", "_mm_or_pd x86 intrinsic", "_mm_or_ps x86 intrinsic", "_mm_or_si64 x86 intrinsic", "_mm_or_si128 x86 intrinsic", "_mm_packs_epi16 x86 intrinsic", "_mm_packs_epi32 x86 intrinsic", "_mm_packs_pi16 x86 intrinsic", "_mm_packs_pi32 x86 intrinsic", "_mm_packs_pu16 x86 intrinsic", "_mm_packus_epi16 x86 intrinsic", "_mm_packus_epi32 x86 intrinsic", "_mm_pause x86 intrinsic", "_mm_perm_epi8 x86 intrinsic", "_mm_permute_pd x86 intrinsic", "_mm_permute_ps x86 intrinsic", "_mm_permute2_pd x86 intrinsic", "_mm_permute2_ps x86 intrinsic", "_mm_permutevar_pd x86 intrinsic", "_mm_permutevar_ps x86 intrinsic", "_mm_popcnt_u32 x86 intrinsic", "_mm_prefetch x86 intrinsic", "_mm_rcp_ps x86 intrinsic", "_mm_rcp_ss x86 intrinsic", "_mm_rot_epi16 x86 intrinsic", "_mm_rot_epi32 x86 intrinsic", "_mm_rot_epi64 x86 intrinsic", "_mm_rot_epi8 x86 intrinsic", "_mm_roti_epi16 x86 intrinsic", "_mm_roti_epi32 x86 intrinsic", "_mm_roti_epi64 x86 intrinsic", "_mm_roti_epi8 x86 intrinsic", "_mm_round_pd x86 intrinsic", "_mm_round_ps x86 intrinsic", "_mm_round_sd x86 intrinsic", "_mm_round_ss x86 intrinsic", "_mm_rsqrt_ps x86 intrinsic", "_mm_rsqrt_ss x86 intrinsic", "_mm_sad_epu8 x86 intrinsic", "_mm_set_epi16 x86 intrinsic", "_mm_set_epi32 x86 intrinsic", "_mm_set_epi64 x86 intrinsic", "_mm_set_epi8 x86 intrinsic", "_mm_set_pd x86 intrinsic", "_mm_set_pi16 x86 intrinsic", "_mm_set_pi32 x86 intrinsic", "_mm_set_pi8 x86 intrinsic", "_mm_set_ps x86 intrinsic", "_mm_set_ps1 x86 intrinsic", "_mm_set_sd x86 intrinsic", "_mm_set_ss x86 intrinsic", "_mm_set1_epi16 x86 intrinsic", "_mm_set1_epi32 x86 intrinsic", "_mm_set1_epi64 x86 intrinsic", "_mm_set1_epi8 x86 intrinsic", "_mm_set1_pd x86 intrinsic", "_mm_set1_pi16 x86 intrinsic", "_mm_set1_pi32 x86 intrinsic", "_mm_set1_pi8 x86 intrinsic", "_mm_setcsr x86 intrinsic", "_mm_setl_epi64 x86 intrinsic", "_mm_setr_epi16 x86 intrinsic", "_mm_setr_epi32 x86 intrinsic", "_mm_setr_epi64 x86 intrinsic", "_mm_setr_epi8 x86 intrinsic", "_mm_setr_pd x86 intrinsic", "_mm_setr_pi16 x86 intrinsic", "_mm_setr_pi32 x86 intrinsic", "_mm_setr_pi8 x86 intrinsic", "_mm_setr_ps x86 intrinsic", "_mm_setzero_pd x86 intrinsic", "_mm_setzero_ps x86 intrinsic", "_mm_setzero_si128 x86 intrinsic", "_mm_setzero_si64 x86 intrinsic", "_mm_sfence x86 intrinsic", "_mm_sha_epi16 x86 intrinsic", "_mm_sha_epi32 x86 intrinsic", "_mm_sha_epi64 x86 intrinsic", "_mm_sha_epi8 x86 intrinsic", "_mm_shl_epi16 x86 intrinsic", "_mm_shl_epi32 x86 intrinsic", "_mm_shl_epi64 x86 intrinsic", "_mm_shl_epi8 x86 intrinsic", "_mm_shuffle_epi32 x86 intrinsic", "_mm_shuffle_epi8 x86 intrinsic", "_mm_shuffle_pd x86 intrinsic", "_mm_shuffle_pi8 x86 intrinsic", "_mm_shuffle_ps x86 intrinsic", "_mm_shufflehi_epi16 x86 intrinsic", "_mm_shufflelo_epi16 x86 intrinsic", "_mm_sign_epi16 x86 intrinsic", "_mm_sign_epi32 x86 intrinsic", "_mm_sign_epi8 x86 intrinsic", "_mm_sign_pi16 x86 intrinsic", "_mm_sign_pi32 x86 intrinsic", "_mm_sign_pi8 x86 intrinsic", "_mm_sll_epi16 x86 intrinsic", "_mm_sll_epi32 x86 intrinsic", "_mm_sll_epi64 x86 intrinsic", "_mm_sll_pi16 x86 intrinsic", "_mm_sll_pi32 x86 intrinsic", "_mm_sll_si64 x86 intrinsic", "_mm_slli_epi16 x86 intrinsic", "_mm_slli_epi32 x86 intrinsic", "_mm_slli_epi64 x86 intrinsic", "_mm_slli_pi16 x86 intrinsic", "_mm_slli_pi32 x86 intrinsic", "_mm_slli_si64 x86 intrinsic", "_mm_slli_si128 x86 intrinsic", "_mm_sllv_epi32 x86 intrinsic", "_mm_sllv_epi64 x86 intrinsic", "_mm_sqrt_pd x86 intrinsic", "_mm_sqrt_ps x86 intrinsic", "_mm_sqrt_sd x86 intrinsic", "_mm_sqrt_ss x86 intrinsic", "_mm_sra_epi16 x86 intrinsic", "_mm_sra_epi32 x86 intrinsic", "_mm_sra_pi16 x86 intrinsic", "_mm_sra_pi32 x86 intrinsic", "_mm_srai_epi16 x86 intrinsic", "_mm_srai_epi32 x86 intrinsic", "_mm_srai_pi16 x86 intrinsic", "_mm_srai_pi32 x86 intrinsic", "_mm_srav_epi32 x86 intrinsic", "_mm_srl_epi16 x86 intrinsic", "_mm_srl_epi32 x86 intrinsic", "_mm_srl_epi64 x86 intrinsic", "_mm_srl_pi16 x86 intrinsic", "_mm_srl_pi32 x86 intrinsic", "_mm_srl_si64 x86 intrinsic", "_mm_srli_epi16 x86 intrinsic", "_mm_srli_epi32 x86 intrinsic", "_mm_srli_epi64 x86 intrinsic", "_mm_srli_pi16 x86 intrinsic", "_mm_srli_pi32 x86 intrinsic", "_mm_srli_si64 x86 intrinsic", "_mm_srli_si128 x86 intrinsic", "_mm_srlv_epi32 x86 intrinsic", "_mm_srlv_epi64 x86 intrinsic", "_mm_store_pd x86 intrinsic", "_mm_store_ps x86 intrinsic", "_mm_store_ps1 x86 intrinsic", "_mm_store_sd x86 intrinsic", "_mm_store_si128 x86 intrinsic", "_mm_store_ss x86 intrinsic", "_mm_store1_pd x86 intrinsic", "_mm_storeh_pd x86 intrinsic", "_mm_storeh_pi x86 intrinsic", "_mm_storel_epi64 x86 intrinsic", "_mm_storel_pd x86 intrinsic", "_mm_storel_pi x86 intrinsic", "_mm_storer_pd x86 intrinsic", "_mm_storer_ps x86 intrinsic", "_mm_storeu_pd x86 intrinsic", "_mm_storeu_ps x86 intrinsic", "_mm_storeu_si128 x86 intrinsic", "_mm_stream_load_si128 x86 intrinsic", "_mm_stream_pd x86 intrinsic", "_mm_stream_pi x86 intrinsic", "_mm_stream_ps x86 intrinsic", "_mm_stream_si128 x86 intrinsic", "_mm_stream_si32 x86 intrinsic", "_mm_sub_epi16 x86 intrinsic", "_mm_sub_epi32 x86 intrinsic", "_mm_sub_epi64 x86 intrinsic", "_mm_sub_epi8 x86 intrinsic", "_mm_sub_pd x86 intrinsic", "_mm_sub_pi8 x86 intrinsic", "_mm_sub_pi16 x86 intrinsic", "_mm_sub_pi32 x86 intrinsic", "_mm_sub_ps x86 intrinsic", "_mm_sub_sd x86 intrinsic", "_mm_sub_si64 x86 intrinsic", "_mm_sub_ss x86 intrinsic", "_mm_subs_epi16 x86 intrinsic", "_mm_subs_epi8 x86 intrinsic", "_mm_subs_epu16 x86 intrinsic", "_mm_subs_epu8 x86 intrinsic", "_mm_subs_pi8 x86 intrinsic", "_mm_subs_pi16 x86 intrinsic", "_mm_subs_pu8 x86 intrinsic", "_mm_subs_pu16 x86 intrinsic", "_mm_testc_pd x86 intrinsic", "_mm_testc_ps x86 intrinsic", "_mm_testc_si128 x86 intrinsic", "_mm_testnzc_pd x86 intrinsic", "_mm_testnzc_ps x86 intrinsic", "_mm_testnzc_si128 x86 intrinsic", "_mm_testz_pd x86 intrinsic", "_mm_testz_ps x86 intrinsic", "_mm_testz_si128 x86 intrinsic", "_mm_ucomieq_sd x86 intrinsic", "_mm_ucomieq_ss x86 intrinsic", "_mm_ucomige_sd x86 intrinsic", "_mm_ucomige_ss x86 intrinsic", "_mm_ucomigt_sd x86 intrinsic", "_mm_ucomigt_ss x86 intrinsic", "_mm_ucomile_sd x86 intrinsic", "_mm_ucomile_ss x86 intrinsic", "_mm_ucomilt_sd x86 intrinsic", "_mm_ucomilt_ss x86 intrinsic", "_mm_ucomineq_sd x86 intrinsic", "_mm_ucomineq_ss x86 intrinsic", "_mm_unpackhi_epi16 x86 intrinsic", "_mm_unpackhi_epi32 x86 intrinsic", "_mm_unpackhi_epi64 x86 intrinsic", "_mm_unpackhi_epi8 x86 intrinsic", "_mm_unpackhi_pd x86 intrinsic", "_mm_unpackhi_pi8 x86 intrinsic", "_mm_unpackhi_pi16 x86 intrinsic", "_mm_unpackhi_pi32 x86 intrinsic", "_mm_unpackhi_ps x86 intrinsic", "_mm_unpacklo_epi16 x86 intrinsic", "_mm_unpacklo_epi32 x86 intrinsic", "_mm_unpacklo_epi64 x86 intrinsic", "_mm_unpacklo_epi8 x86 intrinsic", "_mm_unpacklo_pd x86 intrinsic", "_mm_unpacklo_pi8 x86 intrinsic", "_mm_unpacklo_pi16 x86 intrinsic", "_mm_unpacklo_pi32 x86 intrinsic", "_mm_unpacklo_ps x86 intrinsic", "_mm_xor_pd x86 intrinsic", "_mm_xor_ps x86 intrinsic", "_mm_xor_si64 x86 intrinsic", "_mm_xor_si128 x86 intrinsic", "_mm256_abs_epi16 x86 intrinsic", "_mm256_abs_epi32 x86 intrinsic", "_mm256_abs_epi8 x86 intrinsic", "_mm256_add_epi16 x86 intrinsic", "_mm256_add_epi32 x86 intrinsic", "_mm256_add_epi64 x86 intrinsic", "_mm256_add_epi8 x86 intrinsic", "_mm256_add_pd x86 intrinsic", "_mm256_add_ps x86 intrinsic", "_mm256_adds_epi16 x86 intrinsic", "_mm256_adds_epi8 x86 intrinsic", "_mm256_adds_epu16 x86 intrinsic", "_mm256_adds_epu8 x86 intrinsic", "_mm256_addsub_pd x86 intrinsic", "_mm256_addsub_ps x86 intrinsic", "_mm256_alignr_epi8 x86 intrinsic", "_mm256_and_pd x86 intrinsic", "_mm256_and_ps x86 intrinsic", "_mm256_and_si256 x86 intrinsic", "_mm256_andnot_pd x86 intrinsic", "_mm256_andnot_ps x86 intrinsic", "_mm256_andnot_si256 x86 intrinsic", "_mm256_avg_epu16 x86 intrinsic", "_mm256_avg_epu8 x86 intrinsic", "_mm256_blend_epi16 x86 intrinsic", "_mm256_blend_epi32 x86 intrinsic", "_mm256_blend_pd x86 intrinsic", "_mm256_blend_ps x86 intrinsic", "_mm256_blendv_epi8 x86 intrinsic", "_mm256_blendv_pd x86 intrinsic", "_mm256_blendv_ps x86 intrinsic", "_mm256_broadcast_pd x86 intrinsic", "_mm256_broadcast_ps x86 intrinsic", "_mm256_broadcast_sd x86 intrinsic", "_mm256_broadcast_ss x86 intrinsic", "_mm256_broadcastb_epi8 x86 intrinsic", "_mm256_broadcastd_epi32 x86 intrinsic", "_mm256_broadcastq_epi64 x86 intrinsic", "_mm256_broadcastsd_pd x86 intrinsic", "_mm256_broadcastsi128_si256 x86 intrinsic", "_mm256_broadcastss_ps x86 intrinsic", "_mm256_broadcastw_epi16 x86 intrinsic", "_mm256_castpd_ps x86 intrinsic", "_mm256_castpd_si256 x86 intrinsic", "_mm256_castpd128_pd256 x86 intrinsic", "_mm256_castpd256_pd128 x86 intrinsic", "_mm256_castps_pd x86 intrinsic", "_mm256_castps_si256 x86 intrinsic", "_mm256_castps128_ps256 x86 intrinsic", "_mm256_castps256_ps128 x86 intrinsic", "_mm256_castsi128_si256 x86 intrinsic", "_mm256_castsi256_pd x86 intrinsic", "_mm256_castsi256_ps x86 intrinsic", "_mm256_castsi256_si128 x86 intrinsic", "_mm256_cmov_si256 x86 intrinsic", "_mm256_cmp_pd x86 intrinsic", "_mm256_cmp_ps x86 intrinsic", "_mm256_cmpeq_epi16 x86 intrinsic", "_mm256_cmpeq_epi32 x86 intrinsic", "_mm256_cmpeq_epi64 x86 intrinsic", "_mm256_cmpeq_epi8 x86 intrinsic", "_mm256_cmpgt_epi16 x86 intrinsic", "_mm256_cmpgt_epi32 x86 intrinsic", "_mm256_cmpgt_epi64 x86 intrinsic", "_mm256_cmpgt_epi8 x86 intrinsic", "_mm256_cvtepi16_epi32 x86 intrinsic", "_mm256_cvtepi16_epi64 x86 intrinsic", "_mm256_cvtepi32_epi64 x86 intrinsic", "_mm256_cvtepi32_pd x86 intrinsic", "_mm256_cvtepi32_ps x86 intrinsic", "_mm256_cvtepi8_epi16 x86 intrinsic", "_mm256_cvtepi8_epi32 x86 intrinsic", "_mm256_cvtepi8_epi64 x86 intrinsic", "_mm256_cvtepu16_epi32 x86 intrinsic", "_mm256_cvtepu16_epi64 x86 intrinsic", "_mm256_cvtepu32_epi64 x86 intrinsic", "_mm256_cvtepu8_epi16 x86 intrinsic", "_mm256_cvtepu8_epi32 x86 intrinsic", "_mm256_cvtepu8_epi64 x86 intrinsic", "_mm256_cvtpd_epi32 x86 intrinsic", "_mm256_cvtpd_ps x86 intrinsic", "_mm256_cvtph_ps x86 intrinsic", "_mm256_cvtps_epi32 x86 intrinsic", "_mm256_cvtps_pd x86 intrinsic", "_mm256_cvtps_ph x86 intrinsic", "_mm256_cvttpd_epi32 x86 intrinsic", "_mm256_cvttps_epi32 x86 intrinsic", "_mm256_div_pd x86 intrinsic", "_mm256_div_ps x86 intrinsic", "_mm256_dp_ps x86 intrinsic", "_mm256_extractf128_pd x86 intrinsic", "_mm256_extractf128_ps x86 intrinsic", "_mm256_extractf128_si256 x86 intrinsic", "_mm256_extracti128_si256 x86 intrinsic", "_mm256_fmadd_pd x86 intrinsic", "_mm256_fmadd_ps x86 intrinsic", "_mm256_fmaddsub_pd x86 intrinsic", "_mm256_fmaddsub_ps x86 intrinsic", "_mm256_fmsub_pd x86 intrinsic", "_mm256_fmsub_ps x86 intrinsic", "_mm256_fmsubadd_pd x86 intrinsic", "_mm256_fmsubadd_ps x86 intrinsic", "_mm256_fnmadd_pd x86 intrinsic", "_mm256_fnmadd_ps x86 intrinsic", "_mm256_fnmsub_pd x86 intrinsic", "_mm256_fnmsub_ps x86 intrinsic", "_mm256_frcz_pd x86 intrinsic", "_mm256_frcz_ps x86 intrinsic", "_mm256_hadd_epi16 x86 intrinsic", "_mm256_hadd_epi32 x86 intrinsic", "_mm256_hadd_pd x86 intrinsic", "_mm256_hadd_ps x86 intrinsic", "_mm256_hadds_epi16 x86 intrinsic", "_mm256_hsub_epi16 x86 intrinsic", "_mm256_hsub_epi32 x86 intrinsic", "_mm256_hsub_pd x86 intrinsic", "_mm256_hsub_ps x86 intrinsic", "_mm256_hsubs_epi16 x86 intrinsic", "_mm256_i32gather_epi32 x86 intrinsic", "_mm256_i32gather_epi64 x86 intrinsic", "_mm256_i32gather_pd x86 intrinsic", "_mm256_i32gather_ps x86 intrinsic", "_mm256_i64gather_epi32 x86 intrinsic", "_mm256_i64gather_epi64 x86 intrinsic", "_mm256_i64gather_pd x86 intrinsic", "_mm256_i64gather_ps x86 intrinsic", "_mm256_insertf128_pd x86 intrinsic", "_mm256_insertf128_ps x86 intrinsic", "_mm256_insertf128_si256 x86 intrinsic", "_mm256_inserti128_si256 x86 intrinsic", "_mm256_lddqu_si256 x86 intrinsic", "_mm256_load_pd x86 intrinsic", "_mm256_load_ps x86 intrinsic", "_mm256_load_si256 x86 intrinsic", "_mm256_loadu_pd x86 intrinsic", "_mm256_loadu_ps x86 intrinsic", "_mm256_loadu_si256 x86 intrinsic", "_mm256_macc_pd x86 intrinsic", "_mm256_macc_ps x86 intrinsic", "_mm256_madd_epi16 x86 intrinsic", "_mm256_maddsub_pd x86 intrinsic", "_mm256_maddsub_ps x86 intrinsic", "_mm256_maddubs_epi16 x86 intrinsic", "_mm256_mask_i32gather_epi32 x86 intrinsic", "_mm256_mask_i32gather_epi64 x86 intrinsic", "_mm256_mask_i32gather_pd x86 intrinsic", "_mm256_mask_i32gather_ps x86 intrinsic", "_mm256_mask_i64gather_epi32 x86 intrinsic", "_mm256_mask_i64gather_epi64 x86 intrinsic", "_mm256_mask_i64gather_pd x86 intrinsic", "_mm256_mask_i64gather_ps x86 intrinsic", "_mm256_maskload_epi32 x86 intrinsic", "_mm256_maskload_epi64 x86 intrinsic", "_mm256_maskload_pd x86 intrinsic", "_mm256_maskload_ps x86 intrinsic", "_mm256_maskstore_epi32 x86 intrinsic", "_mm256_maskstore_epi64 x86 intrinsic", "_mm256_maskstore_pd x86 intrinsic", "_mm256_maskstore_ps x86 intrinsic", "_mm256_max_epi16 x86 intrinsic", "_mm256_max_epi32 x86 intrinsic", "_mm256_max_epi8 x86 intrinsic", "_mm256_max_epu16 x86 intrinsic", "_mm256_max_epu32 x86 intrinsic", "_mm256_max_epu8 x86 intrinsic", "_mm256_max_pd x86 intrinsic", "_mm256_max_ps x86 intrinsic", "_mm256_min_epi16 x86 intrinsic", "_mm256_min_epi32 x86 intrinsic", "_mm256_min_epi8 x86 intrinsic", "_mm256_min_epu16 x86 intrinsic", "_mm256_min_epu32 x86 intrinsic", "_mm256_min_epu8 x86 intrinsic", "_mm256_min_pd x86 intrinsic", "_mm256_min_ps x86 intrinsic", "_mm256_movedup_pd x86 intrinsic", "_mm256_movehdup_ps x86 intrinsic", "_mm256_moveldup_ps x86 intrinsic", "_mm256_movemask_epi8 x86 intrinsic", "_mm256_movemask_pd x86 intrinsic", "_mm256_movemask_ps x86 intrinsic", "_mm256_mpsadbw_epu8 x86 intrinsic", "_mm256_msub_pd x86 intrinsic", "_mm256_msub_ps x86 intrinsic", "_mm256_msubadd_pd x86 intrinsic", "_mm256_msubadd_ps x86 intrinsic", "_mm256_mul_epi32 x86 intrinsic", "_mm256_mul_epu32 x86 intrinsic", "_mm256_mul_pd x86 intrinsic", "_mm256_mul_ps x86 intrinsic", "_mm256_mulhi_epi16 x86 intrinsic", "_mm256_mulhi_epu16 x86 intrinsic", "_mm256_mulhrs_epi16 x86 intrinsic", "_mm256_mullo_epi16 x86 intrinsic", "_mm256_mullo_epi32 x86 intrinsic", "_mm256_nmacc_pd x86 intrinsic", "_mm256_nmacc_ps x86 intrinsic", "_mm256_nmsub_pd x86 intrinsic", "_mm256_nmsub_ps x86 intrinsic", "_mm256_or_pd x86 intrinsic", "_mm256_or_ps x86 intrinsic", "_mm256_or_si256 x86 intrinsic", "_mm256_packs_epi16 x86 intrinsic", "_mm256_packs_epi32 x86 intrinsic", "_mm256_packus_epi16 x86 intrinsic", "_mm256_packus_epi32 x86 intrinsic", "_mm256_permute_pd x86 intrinsic", "_mm256_permute_ps x86 intrinsic", "_mm256_permute2_pd x86 intrinsic", "_mm256_permute2_ps x86 intrinsic", "_mm256_permute2f128_pd x86 intrinsic", "_mm256_permute2f128_ps x86 intrinsic", "_mm256_permute2f128_si256 x86 intrinsic", "_mm256_permute2x128_si256 x86 intrinsic", "_mm256_permute4x64_epi64 x86 intrinsic", "_mm256_permute4x64_pd x86 intrinsic", "_mm256_permutevar_pd x86 intrinsic", "_mm256_permutevar_ps x86 intrinsic", "_mm256_permutevar8x32_epi32 x86 intrinsic", "_mm256_permutevar8x32_ps x86 intrinsic", "_mm256_rcp_ps x86 intrinsic", "_mm256_round_pd x86 intrinsic", "_mm256_round_ps x86 intrinsic", "_mm256_rsqrt_ps x86 intrinsic", "_mm256_sad_epu8 x86 intrinsic", "_mm256_set_epi16 x86 intrinsic", "_mm256_set_epi32 x86 intrinsic", "_mm256_set_epi8 x86 intrinsic", "_mm256_set_pd x86 intrinsic", "_mm256_set_ps x86 intrinsic", "_mm256_set1_epi16 x86 intrinsic", "_mm256_set1_epi32 x86 intrinsic", "_mm256_set1_epi8 x86 intrinsic", "_mm256_set1_pd x86 intrinsic", "_mm256_set1_ps x86 intrinsic", "_mm256_setr_epi16 x86 intrinsic", "_mm256_setr_epi32 x86 intrinsic", "_mm256_setr_epi8 x86 intrinsic", "_mm256_setr_pd x86 intrinsic", "_mm256_setr_ps x86 intrinsic", "_mm256_setzero_pd x86 intrinsic", "_mm256_setzero_ps x86 intrinsic", "_mm256_setzero_si256 x86 intrinsic", "_mm256_shuffle_epi32 x86 intrinsic", "_mm256_shuffle_epi8 x86 intrinsic", "_mm256_shuffle_pd x86 intrinsic", "_mm256_shuffle_ps x86 intrinsic", "_mm256_shufflehi_epi16 x86 intrinsic", "_mm256_shufflelo_epi16 x86 intrinsic", "_mm256_sign_epi16 x86 intrinsic", "_mm256_sign_epi32 x86 intrinsic", "_mm256_sign_epi8 x86 intrinsic", "_mm256_sll_epi16 x86 intrinsic", "_mm256_sll_epi32 x86 intrinsic", "_mm256_sll_epi64 x86 intrinsic", "_mm256_slli_epi16 x86 intrinsic", "_mm256_slli_epi32 x86 intrinsic", "_mm256_slli_epi64 x86 intrinsic", "_mm256_slli_si256 x86 intrinsic", "_mm256_sllv_epi32 x86 intrinsic", "_mm256_sllv_epi64 x86 intrinsic", "_mm256_sqrt_pd x86 intrinsic", "_mm256_sqrt_ps x86 intrinsic", "_mm256_sra_epi16 x86 intrinsic", "_mm256_sra_epi32 x86 intrinsic", "_mm256_srai_epi16 x86 intrinsic", "_mm256_srai_epi32 x86 intrinsic", "_mm256_srav_epi32 x86 intrinsic", "_mm256_srl_epi16 x86 intrinsic", "_mm256_srl_epi32 x86 intrinsic", "_mm256_srl_epi64 x86 intrinsic", "_mm256_srli_epi16 x86 intrinsic", "_mm256_srli_epi32 x86 intrinsic", "_mm256_srli_epi64 x86 intrinsic", "_mm256_srli_si256 x86 intrinsic", "_mm256_srlv_epi32 x86 intrinsic", "_mm256_srlv_epi64 x86 intrinsic", "_mm256_store_pd x86 intrinsic", "_mm256_store_ps x86 intrinsic", "_mm256_store_si256 x86 intrinsic", "_mm256_storeu_pd x86 intrinsic", "_mm256_storeu_ps x86 intrinsic", "_mm256_storeu_si256 x86 intrinsic", "_mm256_stream_load_si256 x86 intrinsic", "_mm256_stream_pd x86 intrinsic", "_mm256_stream_ps x86 intrinsic", "_mm256_stream_si256 x86 intrinsic", "_mm256_sub_epi16 x86 intrinsic", "_mm256_sub_epi32 x86 intrinsic", "_mm256_sub_epi64 x86 intrinsic", "_mm256_sub_epi8 x86 intrinsic", "_mm256_sub_pd x86 intrinsic", "_mm256_sub_ps x86 intrinsic", "_mm256_subs_epi16 x86 intrinsic", "_mm256_subs_epi8 x86 intrinsic", "_mm256_subs_epu16 x86 intrinsic", "_mm256_subs_epu8 x86 intrinsic", "_mm256_testc_pd x86 intrinsic", "_mm256_testc_ps x86 intrinsic", "_mm256_testc_si256 x86 intrinsic", "_mm256_testnzc_pd x86 intrinsic", "_mm256_testnzc_ps x86 intrinsic", "_mm256_testnzc_si256 x86 intrinsic", "_mm256_testz_pd x86 intrinsic", "_mm256_testz_ps x86 intrinsic", "_mm256_testz_si256 x86 intrinsic", "_mm256_unpackhi_epi16 x86 intrinsic", "_mm256_unpackhi_epi32 x86 intrinsic", "_mm256_unpackhi_epi64 x86 intrinsic", "_mm256_unpackhi_epi8 x86 intrinsic", "_mm256_unpackhi_pd x86 intrinsic", "_mm256_unpackhi_ps x86 intrinsic", "_mm256_unpacklo_epi16 x86 intrinsic", "_mm256_unpacklo_epi32 x86 intrinsic", "_mm256_unpacklo_epi64 x86 intrinsic", "_mm256_unpacklo_epi8 x86 intrinsic", "_mm256_unpacklo_pd x86 intrinsic", "_mm256_unpacklo_ps x86 intrinsic", "_mm256_xor_pd x86 intrinsic", "_mm256_xor_ps x86 intrinsic", "_mm256_xor_si256 x86 intrinsic", "_mm256_zeroall x86 intrinsic", "_mm256_zeroupper x86 intrinsic", "_mulx_u32 x86 intrinsic", "__nvreg_restore_fence x86 intrinsic", "__nvreg_save_fence x86 intrinsic", "_pdep_u32 x86 intrinsic", "_pext_u32 x86 intrinsic", "_rdrand16_step x86 intrinsic", "_rdrand32_step x86 intrinsic", "_rdseed16_step x86 intrinsic", "_rdseed32_step x86 intrinsic", "_rorx_u32 x86 intrinsic", "_rsm x86 intrinsic", "_sarx_i32 x86 intrinsic", "_sgdt x86 intrinsic", "_shlx_u32 x86 intrinsic", "_shrx_u32 x86 intrinsic", "__slwpcb x86 intrinsic", "_stac x86 intrinsic", "_store_be_u16 x86 intrinsic", "_storebe_i16 x86 intrinsic", "_store_be_u32 x86 intrinsic", "_storebe_i32 x86 intrinsic", "_Store_HLERelease x86 intrinsic", "_StorePointer_HLERelease x86 intrinsic", "_subborrow_u16 x86 intrinsic", "_subborrow_u32 x86 intrinsic", "_subborrow_u8 x86 intrinsic", "_t1mskc_u32 x86 intrinsic", "_tzcnt_u32 x86 intrinsic", "_tzmsk_u32 x86 intrinsic", "_xabort x86 intrinsic", "_xbegin x86 intrinsic", "_xend x86 intrinsic", "_xgetbv x86 intrinsic", "_xrstor x86 intrinsic", "_xsave x86 intrinsic", "_xsaveopt x86 intrinsic", "_xsetbv x86 intrinsic", "_xtest x86 intrinsic"] --- # x86 intrinsics list @@ -25,38 +25,44 @@ For information about individual intrinsics, see these resources, as appropriate ## x86 intrinsics -The following table lists the intrinsics available on x86 processors. The Technology column lists required instruction-set support. Use the [__cpuid](cpuid-cpuidex.md) intrinsic to determine instruction-set support at run time. If two entries are in one row, they represent different entry points for the same intrinsic. A \[1] indicates the intrinsic is available only on AMD processors. A \[2] indicates the intrinsic is available only on Intel processors. A \[3] indicates the prototype is a macro. The header required for the function prototype is listed in the Header column. The intrin.h header includes both immintrin.h and ammintrin.h for simplicity. +The following table lists the intrinsics available on x86 processors. The Technology column lists required instruction-set support. Use the [`__cpuid`](cpuid-cpuidex.md) intrinsic to determine instruction-set support at run time. If two entries are in one row, they represent different entry points for the same intrinsic. \[Macro] indicates the prototype is a macro. The header required for the function prototype is listed in the Header column. The `intrin.h` header includes both `immintrin.h` and `ammintrin.h` for simplicity. | Intrinsic name | Technology | Header | Function prototype | |--|--|--|--| | `_addcarry_u16` | | intrin.h | `unsigned char _addcarry_u16(unsigned char, unsigned short, unsigned short, unsigned short *);` | | [`_addcarry_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarry_u32) | | intrin.h | `unsigned char _addcarry_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | | `_addcarry_u8` | | intrin.h | `unsigned char _addcarry_u8(unsigned char, unsigned char, unsigned char, unsigned char *);` | -| [`_addcarryx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u32) | ADX \[2] | immintrin.h | `unsigned char _addcarryx_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | +| [`_addcarryx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_addcarryx_u32) | ADX | immintrin.h | `unsigned char _addcarryx_u32(unsigned char, unsigned int, unsigned int, unsigned int *);` | | [`__addfsbyte`](addfsbyte-addfsword-addfsdword.md) | | intrin.h | `void __addfsbyte(unsigned long, unsigned char);` | | [`__addfsdword`](addfsbyte-addfsword-addfsdword.md) | | intrin.h | `void __addfsdword(unsigned long, unsigned long);` | | [`__addfsword`](addfsbyte-addfsword-addfsdword.md) | | intrin.h | `void __addfsword(unsigned long, unsigned short);` | | [`_AddressOfReturnAddress`](addressofreturnaddress.md) | | intrin.h | `void * _AddressOfReturnAddress(void);` | -| [`_andn_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_andn_u32) | BMI \[1] | ammintrin.h | `unsigned int _andn_u32(unsigned int, unsigned int);` | +| [`_andn_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_andn_u32) | BMI | ammintrin.h | `unsigned int _andn_u32(unsigned int, unsigned int);` | | [`_bextr_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bextr_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _bextr_u32(unsigned int, unsigned int, unsigned int);` | -| `_bextri_u32` | ABM \[1] | ammintrin.h | `unsigned int _bextri_u32(unsigned int, unsigned int);` | +| `_bextri_u32` | ABM | ammintrin.h | `unsigned int _bextri_u32(unsigned int, unsigned int);` | | [`_BitScanForward`](bitscanforward-bitscanforward64.md) | | intrin.h | `unsigned char _BitScanForward(unsigned long*, unsigned long);` | | [`_BitScanReverse`](bitscanreverse-bitscanreverse64.md) | | intrin.h | `unsigned char _BitScanReverse(unsigned long*, unsigned long);` | | [`_bittest`](bittest-bittest64.md) | | intrin.h | `unsigned char _bittest(long const *, long);` | | [`_bittestandcomplement`](bittestandcomplement-bittestandcomplement64.md) | | intrin.h | `unsigned char _bittestandcomplement(long *, long);` | | [`_bittestandreset`](bittestandreset-bittestandreset64.md) | | intrin.h | `unsigned char _bittestandreset(long *, long);` | | [`_bittestandset`](bittestandset-bittestandset64.md) | | intrin.h | `unsigned char _bittestandset(long *, long);` | -| `_blcfill_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcfill_u32(unsigned int);` | -| `_blci_u32` | ABM \[1] | ammintrin.h | `unsigned int _blci_u32(unsigned int);` | -| `_blcic_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcic_u32(unsigned int);` | -| `_blcmsk_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcmsk_u32(unsigned int);` | -| `_blcs_u32` | ABM \[1] | ammintrin.h | `unsigned int _blcs_u32(unsigned int);` | -| `_blsfill_u32` | ABM \[1] | ammintrin.h | `unsigned int _blsfill_u32(unsigned int);` | +| `_blcfill_u32` | ABM | ammintrin.h | `unsigned int _blcfill_u32(unsigned int);` | +| `_blci_u32` | ABM | ammintrin.h | `unsigned int _blci_u32(unsigned int);` | +| `_blcic_u32` | ABM | ammintrin.h | `unsigned int _blcic_u32(unsigned int);` | +| `_blcmsk_u32` | ABM | ammintrin.h | `unsigned int _blcmsk_u32(unsigned int);` | +| `_blcs_u32` | ABM | ammintrin.h | `unsigned int _blcs_u32(unsigned int);` | +| `_blsfill_u32` | ABM | ammintrin.h | `unsigned int _blsfill_u32(unsigned int);` | | [`_blsi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsi_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsi_u32(unsigned int);` | -| `_blsic_u32` | ABM \[1] | ammintrin.h | `unsigned int _blsic_u32(unsigned int);` | +| `_blsic_u32` | ABM | ammintrin.h | `unsigned int _blsic_u32(unsigned int);` | | [`_blsmsk_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsmsk_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsmsk_u32(unsigned int);` | | [`_blsr_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsr_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsr_u32(unsigned int);` | -| [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI \[2] | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | +| [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | +| [`_castf32_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf32_u32) | | immintrin.h | `unsigned __int32 _castf32_u32 (float);` | +| [`_castf64_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf64_u64) | | immintrin.h | `unsigned __int64 _castf64_u64 (double);` | +| [`_castu32_f32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu32_f32) | | immintrin.h | `float _castu32_f32 (unsigned __int32);` | +| [`_castu64_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu64_f64) | | immintrin.h | `double _castu64_f64 (unsigned __int64 a);` | +| [`__check_isa_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_isa_support(unsigned int, unsigned int);` | +| [`__check_arch_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_arch_support(unsigned int, unsigned int);` | | `_clac` | SMAP | intrin.h | `void _clac(void);` | | [`__cpuid`](cpuid-cpuidex.md) | | intrin.h | `void __cpuid(int *, int);` | | [`__cpuidex`](cpuid-cpuidex.md) | | intrin.h | `void __cpuidex(int *, int, int);` | @@ -67,8 +73,8 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__emulu`](emul-emulu.md) | | intrin.h | `unsigned __int64 [pascal/cdecl]__emulu(unsigned int, unsigned int);` | | [`_enable`](enable.md) | | intrin.h | `void _enable(void);` | | [`__fastfail`](fastfail.md) | | intrin.h | `void __fastfail(unsigned int);` | -| [`_fxrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor) | FXSR \[2] | immintrin.h | `void _fxrstor(void const*);` | -| [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR \[2] | immintrin.h | `void _fxsave(void*);` | +| [`_fxrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor) | FXSR | immintrin.h | `void _fxrstor(void const*);` | +| [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR | immintrin.h | `void _fxsave(void*);` | | [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `(unsigned int __getcallerseflags());` | | [`__halt`](halt.md) | | intrin.h | `void __halt(void);` | | [`__inbyte`](inbyte.md) | | intrin.h | `unsigned char __inbyte(unsigned short);` | @@ -81,69 +87,69 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__int2c`](int2c.md) | | intrin.h | `void __int2c(void);` | | [`_InterlockedAddLargeStatistic`](interlockedaddlargestatistic.md) | | intrin.h | `long _InterlockedAddLargeStatistic(__int64 volatile *, long);` | | [`_InterlockedAnd`](interlockedand-intrinsic-functions.md) | | intrin.h | `long _InterlockedAnd(long volatile *, long);` | -| [`_InterlockedAnd_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedAnd_HLEAcquire(long volatile *, long);` | -| [`_InterlockedAnd_HLERelease`](interlockedand-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedAnd_HLERelease(long volatile *, long);` | +| [`_InterlockedAnd_HLEAcquire`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedAnd_HLEAcquire(long volatile *, long);` | +| [`_InterlockedAnd_HLERelease`](interlockedand-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedAnd_HLERelease(long volatile *, long);` | | [`_InterlockedAnd16`](interlockedand-intrinsic-functions.md) | | intrin.h | `short _InterlockedAnd16(short volatile *, short);` | | [`_InterlockedAnd8`](interlockedand-intrinsic-functions.md) | | intrin.h | `char _InterlockedAnd8(char volatile *, char);` | | [`_interlockedbittestandreset`](interlockedbittestandreset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandreset(long *, long);` | -| [`_interlockedbittestandreset_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset_HLEAcquire(long *, long);` | -| [`_interlockedbittestandreset_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandreset_HLERelease(long *, long);` | +| [`_interlockedbittestandreset_HLEAcquire`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset_HLEAcquire(long *, long);` | +| [`_interlockedbittestandreset_HLERelease`](interlockedbittestandreset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandreset_HLERelease(long *, long);` | | [`_interlockedbittestandset`](interlockedbittestandset-intrinsic-functions.md) | | intrin.h | `unsigned char _interlockedbittestandset(long *, long);` | -| [`_interlockedbittestandset_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset_HLEAcquire(long *, long);` | -| [`_interlockedbittestandset_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE \[2] | immintrin.h | `unsigned char _interlockedbittestandset_HLERelease(long *, long);` | +| [`_interlockedbittestandset_HLEAcquire`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset_HLEAcquire(long *, long);` | +| [`_interlockedbittestandset_HLERelease`](interlockedbittestandset-intrinsic-functions.md) | HLE | immintrin.h | `unsigned char _interlockedbittestandset_HLERelease(long *, long);` | | [`_InterlockedCompareExchange`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `long _InterlockedCompareExchange (long volatile *, long, long);` | -| [`_InterlockedCompareExchange_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedCompareExchange_HLEAcquire(long volatile *, long, long);` | -| [`_InterlockedCompareExchange_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedCompareExchange_HLERelease(long volatile *, long, long);` | +| [`_InterlockedCompareExchange_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedCompareExchange_HLEAcquire(long volatile *, long, long);` | +| [`_InterlockedCompareExchange_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedCompareExchange_HLERelease(long volatile *, long, long);` | | [`_InterlockedCompareExchange16`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `short _InterlockedCompareExchange16(short volatile *, short, short);` | | [`_InterlockedCompareExchange64`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `__int64 _InterlockedCompareExchange64(__int64 volatile *, __int64, __int64);` | -| [`_InterlockedCompareExchange64_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedCompareExchange64_HLEAcquire(__int64 volatile *, __int64, __int64);` | -| [`_InterlockedCompareExchange64_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `__int64 _InterlockedCompareExchange64_HLERelease(__int64 volatile *, __int64, __int64);` | +| [`_InterlockedCompareExchange64_HLEAcquire`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedCompareExchange64_HLEAcquire(__int64 volatile *, __int64, __int64);` | +| [`_InterlockedCompareExchange64_HLERelease`](interlockedcompareexchange-intrinsic-functions.md) | HLE | immintrin.h | `__int64 _InterlockedCompareExchange64_HLERelease(__int64 volatile *, __int64, __int64);` | | [`_InterlockedCompareExchange8`](interlockedcompareexchange-intrinsic-functions.md) | | intrin.h | `char _InterlockedCompareExchange8(char volatile *, char, char);` | | [`_InterlockedCompareExchangePointer`](interlockedcompareexchangepointer-intrinsic-functions.md) | | intrin.h | `void *_InterlockedCompareExchangePointer (void *volatile *, void *, void *);` | -| [`_InterlockedCompareExchangePointer_HLEAcquire`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void *_InterlockedCompareExchangePointer_HLEAcquire(void *volatile *, void *, void *);` | -| [`_InterlockedCompareExchangePointer_HLERelease`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void *_InterlockedCompareExchangePointer_HLERelease(void *volatile *, void *, void *);` | +| [`_InterlockedCompareExchangePointer_HLEAcquire`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void *_InterlockedCompareExchangePointer_HLEAcquire(void *volatile *, void *, void *);` | +| [`_InterlockedCompareExchangePointer_HLERelease`](interlockedcompareexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void *_InterlockedCompareExchangePointer_HLERelease(void *volatile *, void *, void *);` | | [`_InterlockedDecrement`](interlockeddecrement-intrinsic-functions.md) | | intrin.h | `long _InterlockedDecrement(long volatile *);` | | [`_InterlockedDecrement16`](interlockeddecrement-intrinsic-functions.md) | | intrin.h | `short _InterlockedDecrement16(short volatile *);` | | [`_InterlockedExchange`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `long _InterlockedExchange(long volatile *, long);` | -| [`_InterlockedExchange_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchange_HLEAcquire(long volatile *, long);` | -| [`_InterlockedExchange_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchange_HLERelease(long volatile *, long);` | +| [`_InterlockedExchange_HLEAcquire`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchange_HLEAcquire(long volatile *, long);` | +| [`_InterlockedExchange_HLERelease`](interlockedexchange-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchange_HLERelease(long volatile *, long);` | | [`_InterlockedExchange16`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `short _InterlockedExchange16(short volatile *, short);` | | [`_InterlockedExchange8`](interlockedexchange-intrinsic-functions.md) | | intrin.h | `char _InterlockedExchange8(char volatile *, char);` | | [`_InterlockedExchangeAdd`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `long _InterlockedExchangeAdd(long volatile *, long);` | -| [`_InterlockedExchangeAdd_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchangeAdd_HLEAcquire(long volatile *, long);` | -| [`_InterlockedExchangeAdd_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedExchangeAdd_HLERelease(long volatile *, long);` | +| [`_InterlockedExchangeAdd_HLEAcquire`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchangeAdd_HLEAcquire(long volatile *, long);` | +| [`_InterlockedExchangeAdd_HLERelease`](interlockedexchangeadd-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedExchangeAdd_HLERelease(long volatile *, long);` | | [`_InterlockedExchangeAdd16`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `short _InterlockedExchangeAdd16(short volatile *, short);` | | [`_InterlockedExchangeAdd8`](interlockedexchangeadd-intrinsic-functions.md) | | intrin.h | `char _InterlockedExchangeAdd8(char volatile *, char);` | | [`_InterlockedExchangePointer`](interlockedexchangepointer-intrinsic-functions.md) | | intrin.h | `void * _InterlockedExchangePointer(void *volatile *, void *);` | -| [`_InterlockedExchangePointer_HLEAcquire`](interlockedexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void * _InterlockedExchangePointer_HLEAcquire(void *volatile *, void *);` | -| [`_InterlockedExchangePointer_HLERelease`](interlockedexchangepointer-intrinsic-functions.md) | HLE \[2] | immintrin.h | `void * _InterlockedExchangePointer_HLERelease(void *volatile *, void *);` | +| [`_InterlockedExchangePointer_HLEAcquire`](interlockedexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void * _InterlockedExchangePointer_HLEAcquire(void *volatile *, void *);` | +| [`_InterlockedExchangePointer_HLERelease`](interlockedexchangepointer-intrinsic-functions.md) | HLE | immintrin.h | `void * _InterlockedExchangePointer_HLERelease(void *volatile *, void *);` | | [`_InterlockedIncrement`](interlockedincrement-intrinsic-functions.md) | | intrin.h | `long _InterlockedIncrement(long volatile *);` | | [`_InterlockedIncrement16`](interlockedincrement-intrinsic-functions.md) | | intrin.h | `short _InterlockedIncrement16(short volatile *);` | | [`_InterlockedOr`](interlockedor-intrinsic-functions.md) | | intrin.h | `long _InterlockedOr(long volatile *, long);` | -| [`_InterlockedOr_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedOr_HLEAcquire(long volatile *, long);` | -| [`_InterlockedOr_HLERelease`](interlockedor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedOr_HLERelease(long volatile *, long);` | +| [`_InterlockedOr_HLEAcquire`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedOr_HLEAcquire(long volatile *, long);` | +| [`_InterlockedOr_HLERelease`](interlockedor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedOr_HLERelease(long volatile *, long);` | | [`_InterlockedOr16`](interlockedor-intrinsic-functions.md) | | intrin.h | `short _InterlockedOr16(short volatile *, short);` | | [`_InterlockedOr8`](interlockedor-intrinsic-functions.md) | | intrin.h | `char _InterlockedOr8(char volatile *, char);` | | [`_InterlockedXor`](interlockedxor-intrinsic-functions.md) | | intrin.h | `long _InterlockedXor(long volatile *, long);` | -| [`_InterlockedXor_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedXor_HLEAcquire(long volatile *, long);` | -| [`_InterlockedXor_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE \[2] | immintrin.h | `long _InterlockedXor_HLERelease(long volatile *, long);` | +| [`_InterlockedXor_HLEAcquire`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedXor_HLEAcquire(long volatile *, long);` | +| [`_InterlockedXor_HLERelease`](interlockedxor-intrinsic-functions.md) | HLE | immintrin.h | `long _InterlockedXor_HLERelease(long volatile *, long);` | | [`_InterlockedXor16`](interlockedxor-intrinsic-functions.md) | | intrin.h | `short _InterlockedXor16(short volatile *, short);` | | [`_InterlockedXor8`](interlockedxor-intrinsic-functions.md) | | intrin.h | `char _InterlockedXor8(char volatile *, char);` | | [`__invlpg`](invlpg.md) | | intrin.h | `void __invlpg(void*);` | -| [`_invpcid`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_invpcid) | INVPCID \[2] | immintrin.h | `void _invpcid(unsigned int, void *);` | +| [`_invpcid`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_invpcid) | INVPCID | immintrin.h | `void _invpcid(unsigned int, void *);` | | [`__inword`](inword.md) | | intrin.h | `unsigned short __inword(unsigned short);` | | [`__inwordstring`](inwordstring.md) | | intrin.h | `void __inwordstring(unsigned short, unsigned short *, unsigned long);` | | `_lgdt` | | intrin.h | `void _lgdt(void*);` | | [`__lidt`](lidt.md) | | intrin.h | `void __lidt(void*);` | | [`__ll_lshift`](ll-lshift.md) | | intrin.h | `unsigned __int64 [pascal/cdecl] __ll_lshift(unsigned __int64, int);` | | [`__ll_rshift`](ll-rshift.md) | | intrin.h | `__int64 [pascal/cdecl] __ll_rshift(__int64, int);` | -| [`_loadbe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i16&expand=3071) | MOVBE | immintrin.h | `short _loadbe_i16(void const*);` \[3] | -| [`_loadbe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i32&expand=3072) | MOVBE | immintrin.h | `int _loadbe_i32(void const*);` \[3] | -| `_load_be_u16` | MOVBE | immintrin.h | `unsigned short _load_be_u16(void const*);` \[3] | -| `_load_be_u32` | MOVBE | immintrin.h | `unsigned int _load_be_u32(void const*);` \[3] | -| `__llwpcb` | LWP \[1] | ammintrin.h | `void __llwpcb(void *);` | -| `__lwpins32` | LWP \[1] | ammintrin.h | `unsigned char __lwpins32(unsigned int, unsigned int, unsigned int);` | -| `__lwpval32` | LWP \[1] | ammintrin.h | `void __lwpval32(unsigned int, unsigned int, unsigned int);` | +| [`_loadbe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i16&expand=3071) | MOVBE | immintrin.h | `short _loadbe_i16(void const*);` \[Macro] | +| [`_loadbe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_loadbe_i32&expand=3072) | MOVBE | immintrin.h | `int _loadbe_i32(void const*);` \[Macro] | +| `_load_be_u16` | MOVBE | immintrin.h | `unsigned short _load_be_u16(void const*);` \[Macro] | +| `_load_be_u32` | MOVBE | immintrin.h | `unsigned int _load_be_u32(void const*);` \[Macro] | +| `__llwpcb` | LWP | ammintrin.h | `void __llwpcb(void *);` | +| `__lwpins32` | LWP | ammintrin.h | `unsigned char __lwpins32(unsigned int, unsigned int, unsigned int);` | +| `__lwpval32` | LWP | ammintrin.h | `void __lwpval32(unsigned int, unsigned int, unsigned int);` | | [`__lzcnt`](lzcnt16-lzcnt-lzcnt64.md) | LZCNT | intrin.h | `unsigned int __lzcnt(unsigned int);` | | [`_lzcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_lzcnt_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _lzcnt_u32(unsigned int);` | | [`__lzcnt16`](lzcnt16-lzcnt-lzcnt64.md) | LZCNT | intrin.h | `unsigned short __lzcnt16(unsigned short);` | @@ -255,9 +261,9 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_add_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_epi64) | SSE2 | intrin.h | `__m128i _mm_add_epi64(__m128i, __m128i);` | | [`_mm_add_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_epi8) | SSE2 | intrin.h | `__m128i _mm_add_epi8(__m128i, __m128i);` | | [`_mm_add_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pd) | SSE2 | intrin.h | `__m128d _mm_add_pd(__m128d, __m128d);` | -| [`_mm_add_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi8) | MMX | mmintrin.h | `__m64 _mm_add_pi8(__m64, __m64);` \[3] | -| [`_mm_add_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi16) | MMX | mmintrin.h | `__m64 _mm_add_pi16(__m64, __m64);` \[3] | -| [`_mm_add_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi32) | MMX | mmintrin.h | `__m64 _mm_add_pi32(__m64, __m64);` \[3] | +| [`_mm_add_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi8) | MMX | mmintrin.h | `__m64 _mm_add_pi8(__m64, __m64);` \[Macro] | +| [`_mm_add_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi16) | MMX | mmintrin.h | `__m64 _mm_add_pi16(__m64, __m64);` \[Macro] | +| [`_mm_add_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_pi32) | MMX | mmintrin.h | `__m64 _mm_add_pi32(__m64, __m64);` \[Macro] | | [`_mm_add_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_ps) | SSE | intrin.h | `__m128 _mm_add_ps(__m128, __m128);` | | [`_mm_add_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_sd) | SSE2 | intrin.h | `__m128d _mm_add_sd(__m128d, __m128d);` | | [`_mm_add_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_add_si64) | SSE2 | intrin.h | `__m64 _mm_add_si64(__m64, __m64);` | @@ -266,44 +272,44 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_adds_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_epi8) | SSE2 | intrin.h | `__m128i _mm_adds_epi8(__m128i, __m128i);` | | [`_mm_adds_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_epu16) | SSE2 | intrin.h | `__m128i _mm_adds_epu16(__m128i, __m128i);` | | [`_mm_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_epu8) | SSE2 | intrin.h | `__m128i _mm_adds_epu8(__m128i, __m128i);` | -| [`_mm_adds_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pi8) | MMX | mmintrin.h | `__m64 _mm_adds_pi8(__m64, __m64);` \[3] | -| [`_mm_adds_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pi16) | MMX | mmintrin.h | `__m64 _mm_adds_pi16(__m64, __m64);` \[3] | -| [`_mm_adds_pu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pu8) | MMX | mmintrin.h | `__m64 _mm_adds_pu8(__m64, __m64);` \[3] | -| [`_mm_adds_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pu16) | MMX | mmintrin.h | `__m64 _mm_adds_pu16(__m64, __m64);` \[3] | +| [`_mm_adds_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pi8) | MMX | mmintrin.h | `__m64 _mm_adds_pi8(__m64, __m64);` \[Macro] | +| [`_mm_adds_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pi16) | MMX | mmintrin.h | `__m64 _mm_adds_pi16(__m64, __m64);` \[Macro] | +| [`_mm_adds_pu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pu8) | MMX | mmintrin.h | `__m64 _mm_adds_pu8(__m64, __m64);` \[Macro] | +| [`_mm_adds_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_adds_pu16) | MMX | mmintrin.h | `__m64 _mm_adds_pu16(__m64, __m64);` \[Macro] | | [`_mm_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_addsub_pd) | SSE3 | intrin.h | `__m128d _mm_addsub_pd(__m128d, __m128d);` | | [`_mm_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_addsub_ps) | SSE3 | intrin.h | `__m128 _mm_addsub_ps(__m128, __m128);` | -| [`_mm_aesdec_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdec_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesdec_si128(__m128i, __m128i);` | -| [`_mm_aesdeclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdeclast_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesdeclast_si128(__m128i, __m128i);` | -| [`_mm_aesenc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenc_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesenc_si128(__m128i, __m128i);` | -| [`_mm_aesenclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenclast_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesenclast_si128(__m128i, __m128i);` | -| [`_mm_aesimc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesimc_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aesimc_si128 (__m128i);` | -| [`_mm_aeskeygenassist_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aeskeygenassist_si128) | AESNI \[2] | immintrin.h | `__m128i _mm_aeskeygenassist_si128 (__m128i, const int);` | +| [`_mm_aesdec_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdec_si128) | AESNI | immintrin.h | `__m128i _mm_aesdec_si128(__m128i, __m128i);` | +| [`_mm_aesdeclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesdeclast_si128) | AESNI | immintrin.h | `__m128i _mm_aesdeclast_si128(__m128i, __m128i);` | +| [`_mm_aesenc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenc_si128) | AESNI | immintrin.h | `__m128i _mm_aesenc_si128(__m128i, __m128i);` | +| [`_mm_aesenclast_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesenclast_si128) | AESNI | immintrin.h | `__m128i _mm_aesenclast_si128(__m128i, __m128i);` | +| [`_mm_aesimc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aesimc_si128) | AESNI | immintrin.h | `__m128i _mm_aesimc_si128 (__m128i);` | +| [`_mm_aeskeygenassist_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_aeskeygenassist_si128) | AESNI | immintrin.h | `__m128i _mm_aeskeygenassist_si128 (__m128i, const int);` | | [`_mm_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_alignr_epi8) | SSSE3 | intrin.h | `__m128i _mm_alignr_epi8(__m128i, __m128i, int);` | | [`_mm_alignr_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_alignr_pi8) | SSSE3 | intrin.h | `__m64 _mm_alignr_pi8(__m64, __m64, int);` | | [`_mm_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_pd) | SSE2 | intrin.h | `__m128d _mm_and_pd(__m128d, __m128d);` | | [`_mm_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_ps) | SSE | intrin.h | `__m128 _mm_and_ps(__m128, __m128);` | -| [`_mm_and_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_si64) | MMX | mmintrin.h | `__m64 _mm_and_si64(__m64, __m64);` \[3] | +| [`_mm_and_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_si64) | MMX | mmintrin.h | `__m64 _mm_and_si64(__m64, __m64);` \[Macro] | | [`_mm_and_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_and_si128) | SSE2 | intrin.h | `__m128i _mm_and_si128(__m128i, __m128i);` | | [`_mm_andnot_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_andnot_pd) | SSE2 | intrin.h | `__m128d _mm_andnot_pd(__m128d, __m128d);` | | [`_mm_andnot_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_andnot_ps) | SSE | intrin.h | `__m128 _mm_andnot_ps(__m128, __m128);` | -| [`_mm_andnot_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_andnot_si64) | MMX | mmintrin.h | `__m64 _mm_andnot_si64(__m64, __m64);` \[3] | +| [`_mm_andnot_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_andnot_si64) | MMX | mmintrin.h | `__m64 _mm_andnot_si64(__m64, __m64);` \[Macro] | | [`_mm_andnot_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_andnot_si128) | SSE2 | intrin.h | `__m128i _mm_andnot_si128(__m128i, __m128i);` | | [`_mm_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_avg_epu16) | SSE2 | intrin.h | `__m128i _mm_avg_epu16(__m128i, __m128i);` | | [`_mm_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_avg_epu8) | SSE2 | intrin.h | `__m128i _mm_avg_epu8(__m128i, __m128i);` | | [`_mm_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi16) | SSE41 | intrin.h | `__m128i _mm_blend_epi16 (__m128i, __m128i, const int);` | -| [`_mm_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_blend_epi32(__m128i, __m128i, const int);` | +| [`_mm_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_epi32) | AVX2 | immintrin.h | `__m128i _mm_blend_epi32(__m128i, __m128i, const int);` | | [`_mm_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_pd) | SSE41 | intrin.h | `__m128d _mm_blend_pd (__m128d, __m128d, const int);` | | [`_mm_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blend_ps) | SSE41 | intrin.h | `__m128 _mm_blend_ps (__m128, __m128, const int);` | | [`_mm_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_epi8) | SSE41 | intrin.h | `__m128i _mm_blendv_epi8 (__m128i, __m128i, __m128i);` | | [`_mm_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_pd) | SSE41 | intrin.h | `__m128d _mm_blendv_pd(__m128d, __m128d, __m128d);` | | [`_mm_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_ps) | SSE41 | intrin.h | `__m128 _mm_blendv_ps(__m128, __m128, __m128);` | -| [`_mm_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcast_ss) | AVX \[2] | immintrin.h | `__m128 _mm_broadcast_ss(float const *);` | -| [`_mm_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastb_epi8) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastb_epi8(__m128i);` | -| [`_mm_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastd_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastd_epi32(__m128i);` | -| [`_mm_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastq_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastq_epi64(__m128i);` | -| [`_mm_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastsd_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_broadcastsd_pd(__m128d);` | -| [`_mm_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastss_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_broadcastss_ps(__m128);` | -| [`_mm_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastw_epi16) | AVX2 \[2] | immintrin.h | `__m128i _mm_broadcastw_epi16(__m128i);` | +| [`_mm_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcast_ss) | AVX | immintrin.h | `__m128 _mm_broadcast_ss(float const *);` | +| [`_mm_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastb_epi8) | AVX2 | immintrin.h | `__m128i _mm_broadcastb_epi8(__m128i);` | +| [`_mm_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastd_epi32) | AVX2 | immintrin.h | `__m128i _mm_broadcastd_epi32(__m128i);` | +| [`_mm_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastq_epi64) | AVX2 | immintrin.h | `__m128i _mm_broadcastq_epi64(__m128i);` | +| [`_mm_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastsd_pd) | AVX2 | immintrin.h | `__m128d _mm_broadcastsd_pd(__m128d);` | +| [`_mm_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastss_ps) | AVX2 | immintrin.h | `__m128 _mm_broadcastss_ps(__m128);` | +| [`_mm_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_broadcastw_epi16) | AVX2 | immintrin.h | `__m128i _mm_broadcastw_epi16(__m128i);` | | [`_mm_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castpd_ps) | SSSE3 | intrin.h | `__m128 _mm_castpd_ps(__m128d);` | | [`_mm_castpd_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castpd_si128) | SSSE3 | intrin.h | `__m128i _mm_castpd_si128(__m128d);` | | [`_mm_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castps_pd) | SSSE3 | intrin.h | `__m128d _mm_castps_pd(__m128);` | @@ -311,20 +317,20 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_castsi128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castsi128_pd) | SSSE3 | intrin.h | `__m128d _mm_castsi128_pd(__m128i);` | | [`_mm_castsi128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_castsi128_ps) | SSSE3 | intrin.h | `__m128 _mm_castsi128_ps(__m128i);` | | [`_mm_clflush`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clflush) | SSE2 | intrin.h | `void _mm_clflush(void const *);` | -| [`_mm_clmulepi64_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clmulepi64_si128) | PCLMULQDQ \[2] | immintrin.h | `__m128i _mm_clmulepi64_si128 (__m128i, __m128i, const int);` | -| `_mm_cmov_si128` | XOP \[1] | ammintrin.h | `__m128i _mm_cmov_si128(__m128i, __m128i, __m128i);` | -| [`_mm_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_pd) | AVX \[2] | immintrin.h | `__m128d _mm_cmp_pd(__m128d, __m128d, const int);` | -| [`_mm_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ps) | AVX \[2] | immintrin.h | `__m128 _mm_cmp_ps(__m128, __m128, const int);` | -| [`_mm_cmp_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_sd) | AVX \[2] | immintrin.h | `__m128d _mm_cmp_sd(__m128d, __m128d, const int);` | -| [`_mm_cmp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ss) | AVX \[2] | immintrin.h | `__m128 _mm_cmp_ss(__m128, __m128, const int);` | +| [`_mm_clmulepi64_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_clmulepi64_si128) | PCLMULQDQ | immintrin.h | `__m128i _mm_clmulepi64_si128 (__m128i, __m128i, const int);` | +| `_mm_cmov_si128` | XOP | ammintrin.h | `__m128i _mm_cmov_si128(__m128i, __m128i, __m128i);` | +| [`_mm_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_pd) | AVX | immintrin.h | `__m128d _mm_cmp_pd(__m128d, __m128d, const int);` | +| [`_mm_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ps) | AVX | immintrin.h | `__m128 _mm_cmp_ps(__m128, __m128, const int);` | +| [`_mm_cmp_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_sd) | AVX | immintrin.h | `__m128d _mm_cmp_sd(__m128d, __m128d, const int);` | +| [`_mm_cmp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmp_ss) | AVX | immintrin.h | `__m128 _mm_cmp_ss(__m128, __m128, const int);` | | [`_mm_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi16) | SSE2 | intrin.h | `__m128i _mm_cmpeq_epi16(__m128i, __m128i);` | | [`_mm_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi32) | SSE2 | intrin.h | `__m128i _mm_cmpeq_epi32(__m128i, __m128i);` | | [`_mm_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi64) | SSE41 | intrin.h | `__m128i _mm_cmpeq_epi64(__m128i, __m128i);` | | [`_mm_cmpeq_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_epi8) | SSE2 | intrin.h | `__m128i _mm_cmpeq_epi8(__m128i, __m128i);` | | [`_mm_cmpeq_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pd) | SSE2 | intrin.h | `__m128d _mm_cmpeq_pd(__m128d, __m128d);` | -| [`_mm_cmpeq_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi8) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi8(__m64, __m64);` \[3] | -| [`_mm_cmpeq_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi16) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi16(__m64, __m64);` \[3] | -| [`_mm_cmpeq_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi32) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi32(__m64, __m64);` \[3] | +| [`_mm_cmpeq_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi8) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi8(__m64, __m64);` \[Macro] | +| [`_mm_cmpeq_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi16) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi16(__m64, __m64);` \[Macro] | +| [`_mm_cmpeq_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_pi32) | MMX | mmintrin.h | `__m64 _mm_cmpeq_pi32(__m64, __m64);` \[Macro] | | [`_mm_cmpeq_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_ps) | SSE | intrin.h | `__m128 _mm_cmpeq_ps(__m128, __m128);` | | [`_mm_cmpeq_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_sd) | SSE2 | intrin.h | `__m128d _mm_cmpeq_sd(__m128d, __m128d);` | | [`_mm_cmpeq_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpeq_ss) | SSE | intrin.h | `__m128 _mm_cmpeq_ss(__m128, __m128);` | @@ -343,9 +349,9 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_cmpgt_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_epi32) | SSE2 | intrin.h | `__m128i _mm_cmpgt_epi32(__m128i, __m128i);` | | [`_mm_cmpgt_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_epi64) | SSE42 | intrin.h | `__m128i _mm_cmpgt_epi64(__m128i, __m128i);` | | [`_mm_cmpgt_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_epi8) | SSE2 | intrin.h | `__m128i _mm_cmpgt_epi8(__m128i, __m128i);` | -| [`_mm_cmpgt_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi8) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi8(__m64, __m64);` \[3] | -| [`_mm_cmpgt_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi16) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi16(__m64, __m64);` \[3] | -| [`_mm_cmpgt_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi32) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi32(__m64, __m64);` \[3] | +| [`_mm_cmpgt_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi8) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi8(__m64, __m64);` \[Macro] | +| [`_mm_cmpgt_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi16) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi16(__m64, __m64);` \[Macro] | +| [`_mm_cmpgt_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pi32) | MMX | mmintrin.h | `__m64 _mm_cmpgt_pi32(__m64, __m64);` \[Macro] | | [`_mm_cmpgt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_pd) | SSE2 | intrin.h | `__m128d _mm_cmpgt_pd(__m128d, __m128d);` | | [`_mm_cmpgt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_ps) | SSE | intrin.h | `__m128 _mm_cmpgt_ps(__m128, __m128);` | | [`_mm_cmpgt_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpgt_sd) | SSE2 | intrin.h | `__m128d _mm_cmpgt_sd(__m128d, __m128d);` | @@ -396,14 +402,14 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_cmpunord_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_ps) | SSE | intrin.h | `__m128 _mm_cmpunord_ps(__m128, __m128);` | | [`_mm_cmpunord_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_sd) | SSE2 | intrin.h | `__m128d _mm_cmpunord_sd(__m128d, __m128d);` | | [`_mm_cmpunord_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cmpunord_ss) | SSE | intrin.h | `__m128 _mm_cmpunord_ss(__m128, __m128);` | -| `_mm_com_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi16(__m128i, __m128i, int);` | -| `_mm_com_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | -| `_mm_com_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | -| `_mm_com_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epi8(__m128i, __m128i, int);` | -| `_mm_com_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu16(__m128i, __m128i, int);` | -| `_mm_com_epu32` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | -| `_mm_com_epu64` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | -| `_mm_com_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_com_epu8(__m128i, __m128i, int);` | +| `_mm_com_epi16` | XOP | ammintrin.h | `__m128i _mm_com_epi16(__m128i, __m128i, int);` | +| `_mm_com_epi32` | XOP | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | +| `_mm_com_epi64` | XOP | ammintrin.h | `__m128i _mm_com_epi32(__m128i, __m128i, int);` | +| `_mm_com_epi8` | XOP | ammintrin.h | `__m128i _mm_com_epi8(__m128i, __m128i, int);` | +| `_mm_com_epu16` | XOP | ammintrin.h | `__m128i _mm_com_epu16(__m128i, __m128i, int);` | +| `_mm_com_epu32` | XOP | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | +| `_mm_com_epu64` | XOP | ammintrin.h | `__m128i _mm_com_epu32(__m128i, __m128i, int);` | +| `_mm_com_epu8` | XOP | ammintrin.h | `__m128i _mm_com_epu8(__m128i, __m128i, int);` | | [`_mm_comieq_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comieq_sd) | SSE2 | intrin.h | `int _mm_comieq_sd(__m128d, __m128d);` | | [`_mm_comieq_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comieq_ss) | SSE | intrin.h | `int _mm_comieq_ss(__m128, __m128);` | | [`_mm_comige_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_comige_sd) | SSE2 | intrin.h | `int _mm_comige_sd(__m128d, __m128d);` | @@ -440,19 +446,19 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpd_epi32) | SSE2 | intrin.h | `__m128i _mm_cvtpd_epi32(__m128d);` | | [`_mm_cvtpd_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpd_pi32) | SSE2 | intrin.h | `__m64 _mm_cvtpd_pi32(__m128d);` | | [`_mm_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpd_ps) | SSE2 | intrin.h | `__m128 _mm_cvtpd_ps(__m128d);` | -| [`_mm_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtph_ps) | F16C \[2] | immintrin.h | `__m128 _mm_cvtph_ps(__m128i);` | +| [`_mm_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtph_ps) | F16C | immintrin.h | `__m128 _mm_cvtph_ps(__m128i);` | | [`_mm_cvtpi32_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtpi32_pd) | SSE2 | intrin.h | `__m128d _mm_cvtpi32_pd(__m64);` | | [`_mm_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_epi32) | SSE2 | intrin.h | `__m128i _mm_cvtps_epi32(__m128);` | | [`_mm_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_pd) | SSE2 | intrin.h | `__m128d _mm_cvtps_pd(__m128);` | -| [`_mm_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_ph) | F16C \[2] | immintrin.h | `__m128i _mm_cvtps_ph(__m128, const int);` | +| [`_mm_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtps_ph) | F16C | immintrin.h | `__m128i _mm_cvtps_ph(__m128, const int);` | | [`_mm_cvtsd_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_f64) | SSSE3 | intrin.h | `double _mm_cvtsd_f64(__m128d);` | | [`_mm_cvtsd_si32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_si32) | SSE2 | intrin.h | `int _mm_cvtsd_si32(__m128d);` | | [`_mm_cvtsd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsd_ss) | SSE2 | intrin.h | `__m128 _mm_cvtsd_ss(__m128, __m128d);` | | [`_mm_cvtsi128_si32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi128_si32) | SSE2 | intrin.h | `int _mm_cvtsi128_si32(__m128i);` | | [`_mm_cvtsi32_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi32_sd) | SSE2 | intrin.h | `__m128d _mm_cvtsi32_sd(__m128d, int);` | | [`_mm_cvtsi32_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi32_si128) | SSE2 | intrin.h | `__m128i _mm_cvtsi32_si128(int);` | -| [`_mm_cvtsi32_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi32_si64) | MMX | mmintrin.h | `__m64 _mm_cvtsi32_si64(int);` \[3] | -| [`_mm_cvtsi64_si32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi64_si32) | MMX | mmintrin.h | `int _mm_cvtsi64_si32 (__m64);` \[3] | +| [`_mm_cvtsi32_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi32_si64) | MMX | mmintrin.h | `__m64 _mm_cvtsi32_si64(int);` \[Macro] | +| [`_mm_cvtsi64_si32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtsi64_si32) | MMX | mmintrin.h | `int _mm_cvtsi64_si32 (__m64);` \[Macro] | | [`_mm_cvtss_f32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtss_f32) | SSSE3 | intrin.h | `float _mm_cvtss_f32(__m128);` | | [`_mm_cvtss_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtss_sd) | SSE2 | intrin.h | `__m128d _mm_cvtss_sd(__m128d, __m128);` | | [`_mm_cvtt_ps2pi`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_cvtt_ps2pi) | SSE | intrin.h | `__m64 _mm_cvtt_ps2pi(__m128);` | @@ -467,37 +473,37 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_div_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_div_ss) | SSE | intrin.h | `__m128 _mm_div_ss(__m128, __m128);` | | [`_mm_dp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_dp_pd) | SSE41 | intrin.h | `__m128d _mm_dp_pd(__m128d, __m128d, const int);` | | [`_mm_dp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_dp_ps) | SSE41 | intrin.h | `__m128 _mm_dp_ps(__m128, __m128, const int);` | -| [`_mm_empty`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_empty) | MMX | mmintrin.h | `void _mm_empty (void);` \[3] | +| [`_mm_empty`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_empty) | MMX | mmintrin.h | `void _mm_empty (void);` \[Macro] | | [`_mm_extract_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_extract_epi16) | SSE2 | intrin.h | `int _mm_extract_epi16(__m128i, int);` | | [`_mm_extract_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_extract_epi32) | SSE41 | intrin.h | `int _mm_extract_epi32(__m128i, const int);` | | [`_mm_extract_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_extract_epi8) | SSE41 | intrin.h | `int _mm_extract_epi8 (__m128i, const int);` | | [`_mm_extract_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_extract_ps) | SSE41 | intrin.h | `int _mm_extract_ps(__m128, const int);` | | [`_mm_extract_si64`](mm-extract-si64-mm-extracti-si64.md) | SSE4a | intrin.h | `__m128i _mm_extract_si64(__m128i, __m128i);` | | [`_mm_extracti_si64`](mm-extract-si64-mm-extracti-si64.md) | SSE4a | intrin.h | `__m128i _mm_extracti_si64(__m128i, int, int);` | -| [`_mm_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmadd_ps (__m128, __m128, __m128);` | -| [`_mm_fmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fmadd_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fmadd_ss (__m128, __m128, __m128);` | -| [`_mm_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmaddsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmaddsub_ps (__m128, __m128, __m128);` | -| [`_mm_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmsub_ps (__m128, __m128, __m128);` | -| [`_mm_fmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsub_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fmsub_ss (__m128, __m128, __m128);` | -| [`_mm_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fmsubadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fmsubadd_ps (__m128, __m128, __m128);` | -| [`_mm_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmadd_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fnmadd_ps (__m128, __m128, __m128);` | -| [`_mm_fnmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmadd_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fnmadd_ss (__m128, __m128, __m128);` | -| [`_mm_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_pd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmsub_pd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ps) | FMA \[2] | immintrin.h | `__m128 _mm_fnmsub_ps (__m128, __m128, __m128);` | -| [`_mm_fnmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_sd) | FMA \[2] | immintrin.h | `__m128d _mm_fnmsub_sd (__m128d, __m128d, __m128d);` | -| [`_mm_fnmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ss) | FMA \[2] | immintrin.h | `__m128 _mm_fnmsub_ss (__m128, __m128, __m128);` | -| `_mm_frcz_pd` | XOP \[1] | ammintrin.h | `__m128d _mm_frcz_pd(__m128d);` | -| `_mm_frcz_ps` | XOP \[1] | ammintrin.h | `__m128 _mm_frcz_ps(__m128);` | -| `_mm_frcz_sd` | XOP \[1] | ammintrin.h | `__m128d _mm_frcz_sd(__m128d, __m128d);` | -| `_mm_frcz_ss` | XOP \[1] | ammintrin.h | `__m128 _mm_frcz_ss(__m128, __m128);` | +| [`_mm_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_pd) | FMA | immintrin.h | `__m128d _mm_fmadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ps) | FMA | immintrin.h | `__m128 _mm_fmadd_ps (__m128, __m128, __m128);` | +| [`_mm_fmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_sd) | FMA | immintrin.h | `__m128d _mm_fmadd_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmadd_ss) | FMA | immintrin.h | `__m128 _mm_fmadd_ss (__m128, __m128, __m128);` | +| [`_mm_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_pd) | FMA | immintrin.h | `__m128d _mm_fmaddsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmaddsub_ps) | FMA | immintrin.h | `__m128 _mm_fmaddsub_ps (__m128, __m128, __m128);` | +| [`_mm_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_pd) | FMA | immintrin.h | `__m128d _mm_fmsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ps) | FMA | immintrin.h | `__m128 _mm_fmsub_ps (__m128, __m128, __m128);` | +| [`_mm_fmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_sd) | FMA | immintrin.h | `__m128d _mm_fmsub_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsub_ss) | FMA | immintrin.h | `__m128 _mm_fmsub_ss (__m128, __m128, __m128);` | +| [`_mm_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_pd) | FMA | immintrin.h | `__m128d _mm_fmsubadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fmsubadd_ps) | FMA | immintrin.h | `__m128 _mm_fmsubadd_ps (__m128, __m128, __m128);` | +| [`_mm_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_pd) | FMA | immintrin.h | `__m128d _mm_fnmadd_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ps) | FMA | immintrin.h | `__m128 _mm_fnmadd_ps (__m128, __m128, __m128);` | +| [`_mm_fnmadd_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_sd) | FMA | immintrin.h | `__m128d _mm_fnmadd_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmadd_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmadd_ss) | FMA | immintrin.h | `__m128 _mm_fnmadd_ss (__m128, __m128, __m128);` | +| [`_mm_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_pd) | FMA | immintrin.h | `__m128d _mm_fnmsub_pd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ps) | FMA | immintrin.h | `__m128 _mm_fnmsub_ps (__m128, __m128, __m128);` | +| [`_mm_fnmsub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_sd) | FMA | immintrin.h | `__m128d _mm_fnmsub_sd (__m128d, __m128d, __m128d);` | +| [`_mm_fnmsub_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_fnmsub_ss) | FMA | immintrin.h | `__m128 _mm_fnmsub_ss (__m128, __m128, __m128);` | +| `_mm_frcz_pd` | XOP | ammintrin.h | `__m128d _mm_frcz_pd(__m128d);` | +| `_mm_frcz_ps` | XOP | ammintrin.h | `__m128 _mm_frcz_ps(__m128);` | +| `_mm_frcz_sd` | XOP | ammintrin.h | `__m128d _mm_frcz_sd(__m128d, __m128d);` | +| `_mm_frcz_ss` | XOP | ammintrin.h | `__m128 _mm_frcz_ss(__m128, __m128);` | | [`_mm_getcsr`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_getcsr) | SSE | intrin.h | `unsigned int _mm_getcsr(void);` | | [`_mm_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_epi16) | SSSE3 | intrin.h | `__m128i _mm_hadd_epi16(__m128i, __m128i);` | | [`_mm_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_epi32) | SSSE3 | intrin.h | `__m128i _mm_hadd_epi32(__m128i, __m128i);` | @@ -505,39 +511,39 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_hadd_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_pi16) | SSSE3 | intrin.h | `__m64 _mm_hadd_pi16(__m64, __m64);` | | [`_mm_hadd_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_pi32) | SSSE3 | intrin.h | `__m64 _mm_hadd_pi32(__m64, __m64);` | | [`_mm_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadd_ps) | SSE3 | intrin.h | `__m128 _mm_hadd_ps(__m128, __m128);` | -| `_mm_haddd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epi16(__m128i);` | -| `_mm_haddd_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epi8(__m128i);` | -| `_mm_haddd_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epu16(__m128i);` | -| `_mm_haddd_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddd_epu8(__m128i);` | -| `_mm_haddq_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi16(__m128i);` | -| `_mm_haddq_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi32(__m128i);` | -| `_mm_haddq_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epi8(__m128i);` | -| `_mm_haddq_epu16` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu16(__m128i);` | -| `_mm_haddq_epu32` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu32(__m128i);` | -| `_mm_haddq_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddq_epu8(__m128i);` | +| `_mm_haddd_epi16` | XOP | ammintrin.h | `__m128i _mm_haddd_epi16(__m128i);` | +| `_mm_haddd_epi8` | XOP | ammintrin.h | `__m128i _mm_haddd_epi8(__m128i);` | +| `_mm_haddd_epu16` | XOP | ammintrin.h | `__m128i _mm_haddd_epu16(__m128i);` | +| `_mm_haddd_epu8` | XOP | ammintrin.h | `__m128i _mm_haddd_epu8(__m128i);` | +| `_mm_haddq_epi16` | XOP | ammintrin.h | `__m128i _mm_haddq_epi16(__m128i);` | +| `_mm_haddq_epi32` | XOP | ammintrin.h | `__m128i _mm_haddq_epi32(__m128i);` | +| `_mm_haddq_epi8` | XOP | ammintrin.h | `__m128i _mm_haddq_epi8(__m128i);` | +| `_mm_haddq_epu16` | XOP | ammintrin.h | `__m128i _mm_haddq_epu16(__m128i);` | +| `_mm_haddq_epu32` | XOP | ammintrin.h | `__m128i _mm_haddq_epu32(__m128i);` | +| `_mm_haddq_epu8` | XOP | ammintrin.h | `__m128i _mm_haddq_epu8(__m128i);` | | [`_mm_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadds_epi16) | SSSE3 | intrin.h | `__m128i _mm_hadds_epi16(__m128i, __m128i);` | | [`_mm_hadds_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hadds_pi16) | SSSE3 | intrin.h | `__m64 _mm_hadds_pi16(__m64, __m64);` | -| `_mm_haddw_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddw_epi8(__m128i);` | -| `_mm_haddw_epu8` | XOP \[1] | ammintrin.h | `__m128i _mm_haddw_epu8(__m128i);` | +| `_mm_haddw_epi8` | XOP | ammintrin.h | `__m128i _mm_haddw_epi8(__m128i);` | +| `_mm_haddw_epu8` | XOP | ammintrin.h | `__m128i _mm_haddw_epu8(__m128i);` | | [`_mm_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_epi16) | SSSE3 | intrin.h | `__m128i _mm_hsub_epi16(__m128i, __m128i);` | | [`_mm_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_epi32) | SSSE3 | intrin.h | `__m128i _mm_hsub_epi32(__m128i, __m128i);` | | [`_mm_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_pd) | SSE3 | intrin.h | `__m128d _mm_hsub_pd(__m128d, __m128d);` | | [`_mm_hsub_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_pi16) | SSSE3 | intrin.h | `__m64 _mm_hsub_pi16(__m64, __m64);` | | [`_mm_hsub_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_pi32) | SSSE3 | intrin.h | `__m64 _mm_hsub_pi32(__m64, __m64);` | | [`_mm_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsub_ps) | SSE3 | intrin.h | `__m128 _mm_hsub_ps(__m128, __m128);` | -| `_mm_hsubd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubd_epi16(__m128i);` | -| `_mm_hsubq_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubq_epi32(__m128i);` | +| `_mm_hsubd_epi16` | XOP | ammintrin.h | `__m128i _mm_hsubd_epi16(__m128i);` | +| `_mm_hsubq_epi32` | XOP | ammintrin.h | `__m128i _mm_hsubq_epi32(__m128i);` | | [`_mm_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsubs_epi16) | SSSE3 | intrin.h | `__m128i _mm_hsubs_epi16(__m128i, __m128i);` | | [`_mm_hsubs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_hsubs_pi16) | SSSE3 | intrin.h | `__m64 _mm_hsubs_pi16(__m64, __m64);` | -| `_mm_hsubw_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_hsubw_epi8(__m128i);` | -| [`_mm_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_i32gather_epi32(int const *, __m128i, const int);` | -| [`_mm_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_i32gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_i32gather_pd(double const *, __m128i, const int);` | -| [`_mm_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_i32gather_ps(float const *, __m128i, const int);` | -| [`_mm_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_i64gather_epi32(int const *, __m128i, const int);` | -| [`_mm_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_i64gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_i64gather_pd(double const *, __m128i, const int);` | -| [`_mm_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_i64gather_ps(float const *, __m128i, const int);` | +| `_mm_hsubw_epi8` | XOP | ammintrin.h | `__m128i _mm_hsubw_epi8(__m128i);` | +| [`_mm_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_i32gather_epi32(int const *, __m128i, const int);` | +| [`_mm_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_i32gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_pd) | AVX2 | immintrin.h | `__m128d _mm_i32gather_pd(double const *, __m128i, const int);` | +| [`_mm_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i32gather_ps) | AVX2 | immintrin.h | `__m128 _mm_i32gather_ps(float const *, __m128i, const int);` | +| [`_mm_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_i64gather_epi32(int const *, __m128i, const int);` | +| [`_mm_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_i64gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_pd) | AVX2 | immintrin.h | `__m128d _mm_i64gather_pd(double const *, __m128i, const int);` | +| [`_mm_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm_i64gather_ps(float const *, __m128i, const int);` | | [`_mm_insert_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi16) | SSE2 | intrin.h | `__m128i _mm_insert_epi16(__m128i, int, int);` | | [`_mm_insert_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi32) | SSE41 | intrin.h | `__m128i _mm_insert_epi32(__m128i, int, const int);` | | [`_mm_insert_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_insert_epi8) | SSE41 | intrin.h | `__m128i _mm_insert_epi8 (__m128i, int, const int);` | @@ -564,45 +570,45 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_pd) | SSE2 | intrin.h | `__m128d _mm_loadu_pd(double*);` | | [`_mm_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_ps) | SSE | intrin.h | `__m128 _mm_loadu_ps(float*);` | | [`_mm_loadu_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_loadu_si128) | SSE2 | intrin.h | `__m128i _mm_loadu_si128(__m128i*);` | -| `_mm_macc_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_macc_epi16(__m128i, __m128i, __m128i);` | -| `_mm_macc_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macc_epi32(__m128i, __m128i, __m128i);` | -| `_mm_macc_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_macc_pd(__m128d, __m128d, __m128d);` | -| `_mm_macc_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_macc_ps(__m128, __m128, __m128);` | -| `_mm_macc_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_macc_sd(__m128d, __m128d, __m128d);` | -| `_mm_macc_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_macc_ss(__m128, __m128, __m128);` | -| `_mm_maccd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_macchi_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macchi_epi32(__m128i, __m128i, __m128i);` | -| `_mm_macclo_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_macclo_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccs_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccs_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maccs_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccs_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccsd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maccsd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maccshi_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccshi_epi32(__m128i, __m128i, __m128i);` | -| `_mm_maccslo_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_maccslo_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macc_epi16` | XOP | ammintrin.h | `__m128i _mm_macc_epi16(__m128i, __m128i, __m128i);` | +| `_mm_macc_epi32` | XOP | ammintrin.h | `__m128i _mm_macc_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macc_pd` | FMA4 | ammintrin.h | `__m128d _mm_macc_pd(__m128d, __m128d, __m128d);` | +| `_mm_macc_ps` | FMA4 | ammintrin.h | `__m128 _mm_macc_ps(__m128, __m128, __m128);` | +| `_mm_macc_sd` | FMA4 | ammintrin.h | `__m128d _mm_macc_sd(__m128d, __m128d, __m128d);` | +| `_mm_macc_ss` | FMA4 | ammintrin.h | `__m128 _mm_macc_ss(__m128, __m128, __m128);` | +| `_mm_maccd_epi16` | XOP | ammintrin.h | `__m128i _mm_maccd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_macchi_epi32` | XOP | ammintrin.h | `__m128i _mm_macchi_epi32(__m128i, __m128i, __m128i);` | +| `_mm_macclo_epi32` | XOP | ammintrin.h | `__m128i _mm_macclo_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccs_epi16` | XOP | ammintrin.h | `__m128i _mm_maccs_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maccs_epi32` | XOP | ammintrin.h | `__m128i _mm_maccs_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccsd_epi16` | XOP | ammintrin.h | `__m128i _mm_maccsd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maccshi_epi32` | XOP | ammintrin.h | `__m128i _mm_maccshi_epi32(__m128i, __m128i, __m128i);` | +| `_mm_maccslo_epi32` | XOP | ammintrin.h | `__m128i _mm_maccslo_epi32(__m128i, __m128i, __m128i);` | | [`_mm_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_madd_epi16) | SSE2 | intrin.h | `__m128i _mm_madd_epi16(__m128i, __m128i);` | -| [`_mm_madd_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_madd_pi16) | MMX | mmintrin.h | `__m64 _mm_madd_pi16(__m64, __m64);` \[3] | -| `_mm_maddd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maddd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maddsd_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_maddsd_epi16(__m128i, __m128i, __m128i);` | -| `_mm_maddsub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_maddsub_pd(__m128d, __m128d, __m128d);` | -| `_mm_maddsub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_maddsub_ps(__m128, __m128, __m128);` | +| [`_mm_madd_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_madd_pi16) | MMX | mmintrin.h | `__m64 _mm_madd_pi16(__m64, __m64);` \[Macro] | +| `_mm_maddd_epi16` | XOP | ammintrin.h | `__m128i _mm_maddd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maddsd_epi16` | XOP | ammintrin.h | `__m128i _mm_maddsd_epi16(__m128i, __m128i, __m128i);` | +| `_mm_maddsub_pd` | FMA4 | ammintrin.h | `__m128d _mm_maddsub_pd(__m128d, __m128d, __m128d);` | +| `_mm_maddsub_ps` | FMA4 | ammintrin.h | `__m128 _mm_maddsub_ps(__m128, __m128, __m128);` | | [`_mm_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maddubs_epi16) | SSSE3 | intrin.h | `__m128i _mm_maddubs_epi16(__m128i, __m128i);` | | [`_mm_maddubs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maddubs_pi16) | SSSE3 | intrin.h | `__m64 _mm_maddubs_pi16(__m64, __m64);` | -| [`_mm_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i32gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i32gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_mask_i32gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | -| [`_mm_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_mask_i32gather_ps(__m128, float const *, __m128i, __m128, const int);` | -| [`_mm_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i64gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_mask_i64gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | -| [`_mm_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m128d _mm_mask_i64gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | -| [`_mm_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm_mask_i64gather_ps(__m128, float const *, __m128i, __m128, const int);` | -| [`_mm_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_maskload_epi32(int const *, __m128i);` | -| [`_mm_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_maskload_epi64(__int64 const *, __m128i);` | -| [`_mm_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_pd) | AVX \[2] | immintrin.h | `__m128d _mm_maskload_pd(double const *, __m128i);` | -| [`_mm_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_ps) | AVX \[2] | immintrin.h | `__m128 _mm_maskload_ps(float const *, __m128i);` | +| [`_mm_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_mask_i32gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_mask_i32gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_pd) | AVX2 | immintrin.h | `__m128d _mm_mask_i32gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | +| [`_mm_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i32gather_ps) | AVX2 | immintrin.h | `__m128 _mm_mask_i32gather_ps(__m128, float const *, __m128i, __m128, const int);` | +| [`_mm_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm_mask_i64gather_epi32(__m128i, int const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_epi64) | AVX2 | immintrin.h | `__m128i _mm_mask_i64gather_epi64(__m128i, __int64 const *, __m128i, __m128i, const int);` | +| [`_mm_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_pd) | AVX2 | immintrin.h | `__m128d _mm_mask_i64gather_pd(__m128d, double const *, __m128i, __m128d, const int);` | +| [`_mm_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mask_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm_mask_i64gather_ps(__m128, float const *, __m128i, __m128, const int);` | +| [`_mm_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi32) | AVX2 | immintrin.h | `__m128i _mm_maskload_epi32(int const *, __m128i);` | +| [`_mm_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_epi64) | AVX2 | immintrin.h | `__m128i _mm_maskload_epi64(__int64 const *, __m128i);` | +| [`_mm_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_pd) | AVX | immintrin.h | `__m128d _mm_maskload_pd(double const *, __m128i);` | +| [`_mm_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskload_ps) | AVX | immintrin.h | `__m128 _mm_maskload_ps(float const *, __m128i);` | | [`_mm_maskmoveu_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskmoveu_si128) | SSE2 | intrin.h | `void _mm_maskmoveu_si128(__m128i, __m128i, char*);` | -| [`_mm_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi32) | AVX2 \[2] | immintrin.h | `void _mm_maskstore_epi32(int *, __m128i, __m128i);` | -| [`_mm_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi64) | AVX2 \[2] | immintrin.h | `void _mm_maskstore_epi64(__int64 *, __m128i, __m128i);` | -| [`_mm_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_pd) | AVX \[2] | immintrin.h | `void _mm_maskstore_pd(double *, __m128i, __m128d);` | -| [`_mm_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_ps) | AVX \[2] | immintrin.h | `void _mm_maskstore_ps(float *, __m128i, __m128);` | +| [`_mm_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi32) | AVX2 | immintrin.h | `void _mm_maskstore_epi32(int *, __m128i, __m128i);` | +| [`_mm_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_epi64) | AVX2 | immintrin.h | `void _mm_maskstore_epi64(__int64 *, __m128i, __m128i);` | +| [`_mm_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_pd) | AVX | immintrin.h | `void _mm_maskstore_pd(double *, __m128i, __m128d);` | +| [`_mm_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_maskstore_ps) | AVX | immintrin.h | `void _mm_maskstore_ps(float *, __m128i, __m128);` | | [`_mm_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi16) | SSE2 | intrin.h | `__m128i _mm_max_epi16(__m128i, __m128i);` | | [`_mm_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi32) | SSE41 | intrin.h | `__m128i _mm_max_epi32(__m128i, __m128i);` | | [`_mm_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_max_epi8) | SSE41 | intrin.h | `__m128i _mm_max_epi8 (__m128i, __m128i);` | @@ -640,12 +646,12 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_movepi64_pi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_movepi64_pi64) | SSE2 | intrin.h | `__m64 _mm_movepi64_pi64(__m128i);` | | [`_mm_movpi64_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_movpi64_epi64) | SSE2 | intrin.h | `__m128i _mm_movpi64_epi64(__m64);` | | [`_mm_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mpsadbw_epu8) | SSE41 | intrin.h | `__m128i _mm_mpsadbw_epu8(__m128i, __m128i, const int);` | -| `_mm_msub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msub_pd(__m128d, __m128d, __m128d);` | -| `_mm_msub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msub_ps(__m128, __m128, __m128);` | -| `_mm_msub_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msub_sd(__m128d, __m128d, __m128d);` | -| `_mm_msub_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msub_ss(__m128, __m128, __m128);` | -| `_mm_msubadd_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_msubadd_pd(__m128d, __m128d, __m128d);` | -| `_mm_msubadd_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_msubadd_ps(__m128, __m128, __m128);` | +| `_mm_msub_pd` | FMA4 | ammintrin.h | `__m128d _mm_msub_pd(__m128d, __m128d, __m128d);` | +| `_mm_msub_ps` | FMA4 | ammintrin.h | `__m128 _mm_msub_ps(__m128, __m128, __m128);` | +| `_mm_msub_sd` | FMA4 | ammintrin.h | `__m128d _mm_msub_sd(__m128d, __m128d, __m128d);` | +| `_mm_msub_ss` | FMA4 | ammintrin.h | `__m128 _mm_msub_ss(__m128, __m128, __m128);` | +| `_mm_msubadd_pd` | FMA4 | ammintrin.h | `__m128d _mm_msubadd_pd(__m128d, __m128d, __m128d);` | +| `_mm_msubadd_ps` | FMA4 | ammintrin.h | `__m128 _mm_msubadd_ps(__m128, __m128, __m128);` | | [`_mm_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_epi32) | SSE41 | intrin.h | `__m128i _mm_mul_epi32(__m128i, __m128i);` | | [`_mm_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_epu32) | SSE2 | intrin.h | `__m128i _mm_mul_epu32(__m128i, __m128i);` | | [`_mm_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_pd) | SSE2 | intrin.h | `__m128d _mm_mul_pd(__m128d, __m128d);` | @@ -655,52 +661,52 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_mul_su32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mul_su32) | SSE2 | intrin.h | `__m64 _mm_mul_su32(__m64, __m64);` | | [`_mm_mulhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhi_epi16) | SSE2 | intrin.h | `__m128i _mm_mulhi_epi16(__m128i, __m128i);` | | [`_mm_mulhi_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhi_epu16) | SSE2 | intrin.h | `__m128i _mm_mulhi_epu16(__m128i, __m128i);` | -| [`_mm_mulhi_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhi_pi16) | MMX | mmintrin.h | `__m64 _mm_mulhi_pi16(__m64, __m64);` \[3] | +| [`_mm_mulhi_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhi_pi16) | MMX | mmintrin.h | `__m64 _mm_mulhi_pi16(__m64, __m64);` \[Macro] | | [`_mm_mulhrs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhrs_epi16) | SSSE3 | intrin.h | `__m128i _mm_mulhrs_epi16(__m128i, __m128i);` | | [`_mm_mulhrs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mulhrs_pi16) | SSSE3 | intrin.h | `__m64 _mm_mulhrs_pi16(__m64, __m64);` | | [`_mm_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_epi16) | SSE2 | intrin.h | `__m128i _mm_mullo_epi16(__m128i, __m128i);` | | [`_mm_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_epi32) | SSE41 | intrin.h | `__m128i _mm_mullo_epi32(__m128i, __m128i);` | -| [`_mm_mullo_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_pi16) | MMX | mmintrin.h | `__m64 _mm_mullo_pi16(__m64, __m64);` \[3] | +| [`_mm_mullo_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mullo_pi16) | MMX | mmintrin.h | `__m64 _mm_mullo_pi16(__m64, __m64);` \[Macro] | | [`_mm_mwait`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_mwait) | SSE3 | intrin.h | `void _mm_mwait(unsigned int, unsigned int);` | -| `_mm_nmacc_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmacc_pd(__m128d, __m128d, __m128d);` | -| `_mm_nmacc_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmacc_ps(__m128, __m128, __m128);` | -| `_mm_nmacc_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmacc_sd(__m128d, __m128d, __m128d);` | -| `_mm_nmacc_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmacc_ss(__m128, __m128, __m128);` | -| `_mm_nmsub_pd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmsub_pd(__m128d, __m128d, __m128d);` | -| `_mm_nmsub_ps` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmsub_ps(__m128, __m128, __m128);` | -| `_mm_nmsub_sd` | FMA4 \[1] | ammintrin.h | `__m128d _mm_nmsub_sd(__m128d, __m128d, __m128d);` | -| `_mm_nmsub_ss` | FMA4 \[1] | ammintrin.h | `__m128 _mm_nmsub_ss(__m128, __m128, __m128);` | +| `_mm_nmacc_pd` | FMA4 | ammintrin.h | `__m128d _mm_nmacc_pd(__m128d, __m128d, __m128d);` | +| `_mm_nmacc_ps` | FMA4 | ammintrin.h | `__m128 _mm_nmacc_ps(__m128, __m128, __m128);` | +| `_mm_nmacc_sd` | FMA4 | ammintrin.h | `__m128d _mm_nmacc_sd(__m128d, __m128d, __m128d);` | +| `_mm_nmacc_ss` | FMA4 | ammintrin.h | `__m128 _mm_nmacc_ss(__m128, __m128, __m128);` | +| `_mm_nmsub_pd` | FMA4 | ammintrin.h | `__m128d _mm_nmsub_pd(__m128d, __m128d, __m128d);` | +| `_mm_nmsub_ps` | FMA4 | ammintrin.h | `__m128 _mm_nmsub_ps(__m128, __m128, __m128);` | +| `_mm_nmsub_sd` | FMA4 | ammintrin.h | `__m128d _mm_nmsub_sd(__m128d, __m128d, __m128d);` | +| `_mm_nmsub_ss` | FMA4 | ammintrin.h | `__m128 _mm_nmsub_ss(__m128, __m128, __m128);` | | [`_mm_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_pd) | SSE2 | intrin.h | `__m128d _mm_or_pd(__m128d, __m128d);` | | [`_mm_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_ps) | SSE | intrin.h | `__m128 _mm_or_ps(__m128, __m128);` | -| [`_mm_or_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_si64) | MMX | mmintrin.h | `__m64 _mm_or_si64(__m64, __m64);` \[3] | +| [`_mm_or_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_si64) | MMX | mmintrin.h | `__m64 _mm_or_si64(__m64, __m64);` \[Macro] | | [`_mm_or_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_or_si128) | SSE2 | intrin.h | `__m128i _mm_or_si128(__m128i, __m128i);` | | [`_mm_packs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_epi16) | SSE2 | intrin.h | `__m128i _mm_packs_epi16(__m128i, __m128i);` | | [`_mm_packs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_epi32) | SSE2 | intrin.h | `__m128i _mm_packs_epi32(__m128i, __m128i);` | -| [`_mm_packs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pi16) | MMX | mmintrin.h | `__m64 _mm_packs_pi16 (__m64, __m64);` \[3] | -| [`_mm_packs_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pi32) | MMX | mmintrin.h | `__m64 _mm_packs_pi32 (__m64, __m64);` \[3] | -| [`_mm_packs_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pu16) | MMX | mmintrin.h | `__m64 _mm_packs_pu16 (__m64, __m64);` \[3] | +| [`_mm_packs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pi16) | MMX | mmintrin.h | `__m64 _mm_packs_pi16 (__m64, __m64);` \[Macro] | +| [`_mm_packs_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pi32) | MMX | mmintrin.h | `__m64 _mm_packs_pi32 (__m64, __m64);` \[Macro] | +| [`_mm_packs_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packs_pu16) | MMX | mmintrin.h | `__m64 _mm_packs_pu16 (__m64, __m64);` \[Macro] | | [`_mm_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packus_epi16) | SSE2 | intrin.h | `__m128i _mm_packus_epi16(__m128i, __m128i);` | | [`_mm_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_packus_epi32) | SSE41 | intrin.h | `__m128i _mm_packus_epi32(__m128i, __m128i);` | | [`_mm_pause`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_pause) | SSE2 | intrin.h | `void _mm_pause(void);` | -| `_mm_perm_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_perm_epi8(__m128i, __m128i, __m128i);` | -| [`_mm_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_pd) | AVX \[2] | immintrin.h | `__m128d _mm_permute_pd(__m128d, int);` | -| [`_mm_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_ps) | AVX \[2] | immintrin.h | `__m128 _mm_permute_ps(__m128, int);` | -| `_mm_permute2_pd` | XOP \[1] | ammintrin.h | `__m128d _mm_permute2_pd(__m128d, __m128d, __m128i, int);` | -| `_mm_permute2_ps` | XOP \[1] | ammintrin.h | `__m128 _mm_permute2_ps(__m128, __m128, __m128i, int);` | -| [`_mm_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_pd) | AVX \[2] | immintrin.h | `__m128d _mm_permutevar_pd(__m128d, __m128i);` | -| [`_mm_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_ps) | AVX \[2] | immintrin.h | `__m128 _mm_permutevar_ps(__m128, __m128i);` | +| `_mm_perm_epi8` | XOP | ammintrin.h | `__m128i _mm_perm_epi8(__m128i, __m128i, __m128i);` | +| [`_mm_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_pd) | AVX | immintrin.h | `__m128d _mm_permute_pd(__m128d, int);` | +| [`_mm_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permute_ps) | AVX | immintrin.h | `__m128 _mm_permute_ps(__m128, int);` | +| `_mm_permute2_pd` | XOP | ammintrin.h | `__m128d _mm_permute2_pd(__m128d, __m128d, __m128i, int);` | +| `_mm_permute2_ps` | XOP | ammintrin.h | `__m128 _mm_permute2_ps(__m128, __m128, __m128i, int);` | +| [`_mm_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_pd) | AVX | immintrin.h | `__m128d _mm_permutevar_pd(__m128d, __m128i);` | +| [`_mm_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_permutevar_ps) | AVX | immintrin.h | `__m128 _mm_permutevar_ps(__m128, __m128i);` | | [`_mm_popcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_popcnt_u32) | POPCNT | intrin.h | `int _mm_popcnt_u32(unsigned int);` | | [`_mm_prefetch`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_prefetch) | SSE | intrin.h | `void _mm_prefetch(char*, int);` | | [`_mm_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_rcp_ps) | SSE | intrin.h | `__m128 _mm_rcp_ps(__m128);` | | [`_mm_rcp_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_rcp_ss) | SSE | intrin.h | `__m128 _mm_rcp_ss(__m128);` | -| `_mm_rot_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, __m128i);` | -| `_mm_rot_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, __m128i);` | -| `_mm_rot_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, __m128i);` | -| `_mm_rot_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, __m128i);` | -| `_mm_roti_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, int);` | -| `_mm_roti_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, int);` | -| `_mm_roti_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, int);` | -| `_mm_roti_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, int);` | +| `_mm_rot_epi16` | XOP | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, __m128i);` | +| `_mm_rot_epi32` | XOP | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, __m128i);` | +| `_mm_rot_epi64` | XOP | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, __m128i);` | +| `_mm_rot_epi8` | XOP | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, __m128i);` | +| `_mm_roti_epi16` | XOP | ammintrin.h | `__m128i _mm_rot_epi16(__m128i, int);` | +| `_mm_roti_epi32` | XOP | ammintrin.h | `__m128i _mm_rot_epi32(__m128i, int);` | +| `_mm_roti_epi64` | XOP | ammintrin.h | `__m128i _mm_rot_epi64(__m128i, int);` | +| `_mm_roti_epi8` | XOP | ammintrin.h | `__m128i _mm_rot_epi8(__m128i, int);` | | [`_mm_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_pd) | SSE41 | intrin.h | `__m128d _mm_round_pd(__m128d, const int);` | | [`_mm_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_ps) | SSE41 | intrin.h | `__m128 _mm_round_ps(__m128, const int);` | | [`_mm_round_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_round_sd) | SSE41 | intrin.h | `__m128d _mm_round_sd(__m128d, __m128d, const int);` | @@ -744,14 +750,14 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_setzero_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_setzero_si128) | SSE2 | intrin.h | `__m128i _mm_setzero_si128(void);` | | [`_mm_setzero_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_setzero_si64) | MMX | intrin.h | `__m64 _mm_setzero_si64(void);` | | [`_mm_sfence`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence) | SSE | intrin.h | `void _mm_sfence(void);` | -| `_mm_sha_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi16(__m128i, __m128i);` | -| `_mm_sha_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi32(__m128i, __m128i);` | -| `_mm_sha_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi64(__m128i, __m128i);` | -| `_mm_sha_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_sha_epi8(__m128i, __m128i);` | -| `_mm_shl_epi16` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi16(__m128i, __m128i);` | -| `_mm_shl_epi32` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi32(__m128i, __m128i);` | -| `_mm_shl_epi64` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi64(__m128i, __m128i);` | -| `_mm_shl_epi8` | XOP \[1] | ammintrin.h | `__m128i _mm_shl_epi8(__m128i, __m128i);` | +| `_mm_sha_epi16` | XOP | ammintrin.h | `__m128i _mm_sha_epi16(__m128i, __m128i);` | +| `_mm_sha_epi32` | XOP | ammintrin.h | `__m128i _mm_sha_epi32(__m128i, __m128i);` | +| `_mm_sha_epi64` | XOP | ammintrin.h | `__m128i _mm_sha_epi64(__m128i, __m128i);` | +| `_mm_sha_epi8` | XOP | ammintrin.h | `__m128i _mm_sha_epi8(__m128i, __m128i);` | +| `_mm_shl_epi16` | XOP | ammintrin.h | `__m128i _mm_shl_epi16(__m128i, __m128i);` | +| `_mm_shl_epi32` | XOP | ammintrin.h | `__m128i _mm_shl_epi32(__m128i, __m128i);` | +| `_mm_shl_epi64` | XOP | ammintrin.h | `__m128i _mm_shl_epi64(__m128i, __m128i);` | +| `_mm_shl_epi8` | XOP | ammintrin.h | `__m128i _mm_shl_epi8(__m128i, __m128i);` | | [`_mm_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_epi32) | SSE2 | intrin.h | `__m128i _mm_shuffle_epi32(__m128i, int);` | | [`_mm_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_epi8) | SSSE3 | intrin.h | `__m128i _mm_shuffle_epi8(__m128i, __m128i);` | | [`_mm_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_shuffle_pd) | SSE2 | intrin.h | `__m128d _mm_shuffle_pd(__m128d, __m128d, int);` | @@ -768,46 +774,46 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_sll_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_epi16) | SSE2 | intrin.h | `__m128i _mm_sll_epi16(__m128i, __m128i);` | | [`_mm_sll_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_epi32) | SSE2 | intrin.h | `__m128i _mm_sll_epi32(__m128i, __m128i);` | | [`_mm_sll_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_epi64) | SSE2 | intrin.h | `__m128i _mm_sll_epi64(__m128i, __m128i);` | -| [`_mm_sll_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_pi16) | MMX | mmintrin.h | `__m64 _mm_sll_pi16(__m64, __m64);` \[3] | -| [`_mm_sll_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_pi32) | MMX | mmintrin.h | `__m64 _mm_sll_pi32(__m64, __m64);` \[3] | -| [`_mm_sll_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_si64) | MMX | mmintrin.h | `__m64 _mm_sll_si64(__m64, __m64);` \[3] | +| [`_mm_sll_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_pi16) | MMX | mmintrin.h | `__m64 _mm_sll_pi16(__m64, __m64);` \[Macro] | +| [`_mm_sll_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_pi32) | MMX | mmintrin.h | `__m64 _mm_sll_pi32(__m64, __m64);` \[Macro] | +| [`_mm_sll_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sll_si64) | MMX | mmintrin.h | `__m64 _mm_sll_si64(__m64, __m64);` \[Macro] | | [`_mm_slli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_epi16) | SSE2 | intrin.h | `__m128i _mm_slli_epi16(__m128i, int);` | | [`_mm_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_epi32) | SSE2 | intrin.h | `__m128i _mm_slli_epi32(__m128i, int);` | | [`_mm_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_epi64) | SSE2 | intrin.h | `__m128i _mm_slli_epi64(__m128i, int);` | -| [`_mm_slli_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_pi16) | MMX | mmintrin.h | `__m64 _mm_slli_pi16(__m64, int);` \[3] | -| [`_mm_slli_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_pi32) | MMX | mmintrin.h | `__m64 _mm_slli_pi32(__m64, int);` \[3] | -| [`_mm_slli_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_si64) | MMX | mmintrin.h | `__m64 _mm_slli_si64(__m64, int);` \[3] | +| [`_mm_slli_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_pi16) | MMX | mmintrin.h | `__m64 _mm_slli_pi16(__m64, int);` \[Macro] | +| [`_mm_slli_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_pi32) | MMX | mmintrin.h | `__m64 _mm_slli_pi32(__m64, int);` \[Macro] | +| [`_mm_slli_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_si64) | MMX | mmintrin.h | `__m64 _mm_slli_si64(__m64, int);` \[Macro] | | [`_mm_slli_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_slli_si128) | SSE2 | intrin.h | `__m128i _mm_slli_si128(__m128i, int);` | -| [`_mm_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_sllv_epi32(__m128i, __m128i);` | -| [`_mm_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_sllv_epi64(__m128i, __m128i);` | +| [`_mm_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi32) | AVX2 | immintrin.h | `__m128i _mm_sllv_epi32(__m128i, __m128i);` | +| [`_mm_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sllv_epi64) | AVX2 | immintrin.h | `__m128i _mm_sllv_epi64(__m128i, __m128i);` | | [`_mm_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_pd) | SSE2 | intrin.h | `__m128d _mm_sqrt_pd(__m128d);` | | [`_mm_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_ps) | SSE | intrin.h | `__m128 _mm_sqrt_ps(__m128);` | | [`_mm_sqrt_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_sd) | SSE2 | intrin.h | `__m128d _mm_sqrt_sd(__m128d, __m128d);` | | [`_mm_sqrt_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sqrt_ss) | SSE | intrin.h | `__m128 _mm_sqrt_ss(__m128);` | | [`_mm_sra_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_epi16) | SSE2 | intrin.h | `__m128i _mm_sra_epi16(__m128i, __m128i);` | | [`_mm_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_epi32) | SSE2 | intrin.h | `__m128i _mm_sra_epi32(__m128i, __m128i);` | -| [`_mm_sra_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_pi16) | MMX | mmintrin.h | `__m64 _mm_sra_pi16(__m64, __m64);` \[3] | -| [`_mm_sra_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_pi32) | MMX | mmintrin.h | `__m64 _mm_sra_pi32(__m64, __m64);` \[3] | +| [`_mm_sra_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_pi16) | MMX | mmintrin.h | `__m64 _mm_sra_pi16(__m64, __m64);` \[Macro] | +| [`_mm_sra_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sra_pi32) | MMX | mmintrin.h | `__m64 _mm_sra_pi32(__m64, __m64);` \[Macro] | | [`_mm_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_epi16) | SSE2 | intrin.h | `__m128i _mm_srai_epi16(__m128i, int);` | | [`_mm_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_epi32) | SSE2 | intrin.h | `__m128i _mm_srai_epi32(__m128i, int);` | -| [`_mm_srai_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_pi16) | MMX | mmintrin.h | `__m64 _mm_srai_pi16(__m64, int);` \[3] | -| [`_mm_srai_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_pi32) | MMX | mmintrin.h | `__m64 _mm_srai_pi32(__m64, int);` \[3] | -| [`_mm_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srav_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_srav_epi32(__m128i, __m128i);` | +| [`_mm_srai_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_pi16) | MMX | mmintrin.h | `__m64 _mm_srai_pi16(__m64, int);` \[Macro] | +| [`_mm_srai_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srai_pi32) | MMX | mmintrin.h | `__m64 _mm_srai_pi32(__m64, int);` \[Macro] | +| [`_mm_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srav_epi32) | AVX2 | immintrin.h | `__m128i _mm_srav_epi32(__m128i, __m128i);` | | [`_mm_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi16) | SSE2 | intrin.h | `__m128i _mm_srl_epi16(__m128i, __m128i);` | | [`_mm_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi32) | SSE2 | intrin.h | `__m128i _mm_srl_epi32(__m128i, __m128i);` | | [`_mm_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_epi64) | SSE2 | intrin.h | `__m128i _mm_srl_epi64(__m128i, __m128i);` | -| [`_mm_srl_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_pi16) | MMX | mmintrin.h | `__m64 _mm_srl_pi16(__m64, __m64);` \[3] | -| [`_mm_srl_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_pi32) | MMX | mmintrin.h | `__m64 _mm_srl_pi32(__m64, __m64);` \[3] | -| [`_mm_srl_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_si64) | MMX | mmintrin.h | `__m64 _mm_srl_si64(__m64, __m64);` \[3] | +| [`_mm_srl_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_pi16) | MMX | mmintrin.h | `__m64 _mm_srl_pi16(__m64, __m64);` \[Macro] | +| [`_mm_srl_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_pi32) | MMX | mmintrin.h | `__m64 _mm_srl_pi32(__m64, __m64);` \[Macro] | +| [`_mm_srl_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srl_si64) | MMX | mmintrin.h | `__m64 _mm_srl_si64(__m64, __m64);` \[Macro] | | [`_mm_srli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_epi16) | SSE2 | intrin.h | `__m128i _mm_srli_epi16(__m128i, int);` | | [`_mm_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_epi32) | SSE2 | intrin.h | `__m128i _mm_srli_epi32(__m128i, int);` | | [`_mm_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_epi64) | SSE2 | intrin.h | `__m128i _mm_srli_epi64(__m128i, int);` | -| [`_mm_srli_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_pi16) | MMX | mmintrin.h | `__m64 _mm_srli_pi16(__m64, int);` \[3] | -| [`_mm_srli_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_pi32) | MMX | mmintrin.h | `__m64 _mm_srli_pi32(__m64, int);` \[3] | -| [`_mm_srli_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_si64) | MMX | mmintrin.h | `__m64 _mm_srli_si64(__m64, int);` \[3] | +| [`_mm_srli_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_pi16) | MMX | mmintrin.h | `__m64 _mm_srli_pi16(__m64, int);` \[Macro] | +| [`_mm_srli_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_pi32) | MMX | mmintrin.h | `__m64 _mm_srli_pi32(__m64, int);` \[Macro] | +| [`_mm_srli_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_si64) | MMX | mmintrin.h | `__m64 _mm_srli_si64(__m64, int);` \[Macro] | | [`_mm_srli_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srli_si128) | SSE2 | intrin.h | `__m128i _mm_srli_si128(__m128i, int);` | -| [`_mm_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm_srlv_epi32(__m128i, __m128i);` | -| [`_mm_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi64) | AVX2 \[2] | immintrin.h | `__m128i _mm_srlv_epi64(__m128i, __m128i);` | +| [`_mm_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi32) | AVX2 | immintrin.h | `__m128i _mm_srlv_epi32(__m128i, __m128i);` | +| [`_mm_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_srlv_epi64) | AVX2 | immintrin.h | `__m128i _mm_srlv_epi64(__m128i, __m128i);` | | [`_mm_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_pd) | SSE2 | intrin.h | `void _mm_store_pd(double*, __m128d);` | | [`_mm_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ps) | SSE | intrin.h | `void _mm_store_ps(float*, __m128);` | | [`_mm_store_ps1`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ps1) | SSE | intrin.h | `void _mm_store_ps1(float*, __m128);` | @@ -838,9 +844,9 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_sub_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_epi64) | SSE2 | intrin.h | `__m128i _mm_sub_epi64(__m128i, __m128i);` | | [`_mm_sub_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_epi8) | SSE2 | intrin.h | `__m128i _mm_sub_epi8(__m128i, __m128i);` | | [`_mm_sub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pd) | SSE2 | intrin.h | `__m128d _mm_sub_pd(__m128d, __m128d);` | -| [`_mm_sub_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi8) | MMX | mmintrin.h | `__m64 _mm_sub_pi8(__m64, __m64);` \[3] | -| [`_mm_sub_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi16) | MMX | mmintrin.h | `__m64 _mm_sub_pi16(__m64, __m64);` \[3] | -| [`_mm_sub_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi32) | MMX | mmintrin.h | `__m64 _mm_sub_pi32(__m64, __m64);` \[3] | +| [`_mm_sub_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi8) | MMX | mmintrin.h | `__m64 _mm_sub_pi8(__m64, __m64);` \[Macro] | +| [`_mm_sub_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi16) | MMX | mmintrin.h | `__m64 _mm_sub_pi16(__m64, __m64);` \[Macro] | +| [`_mm_sub_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_pi32) | MMX | mmintrin.h | `__m64 _mm_sub_pi32(__m64, __m64);` \[Macro] | | [`_mm_sub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_ps) | SSE | intrin.h | `__m128 _mm_sub_ps(__m128, __m128);` | | [`_mm_sub_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_sd) | SSE2 | intrin.h | `__m128d _mm_sub_sd(__m128d, __m128d);` | | [`_mm_sub_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sub_si64) | SSE2 | intrin.h | `__m64 _mm_sub_si64(__m64, __m64);` | @@ -849,18 +855,18 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epi8) | SSE2 | intrin.h | `__m128i _mm_subs_epi8(__m128i, __m128i);` | | [`_mm_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epu16) | SSE2 | intrin.h | `__m128i _mm_subs_epu16(__m128i, __m128i);` | | [`_mm_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_epu8) | SSE2 | intrin.h | `__m128i _mm_subs_epu8(__m128i, __m128i);` | -| [`_mm_subs_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pi8) | MMX | mmintrin.h | `__m64 _mm_subs_pi8(__m64, __m64);` \[3] | -| [`_mm_subs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pi16) | MMX | mmintrin.h | `__m64 _mm_subs_pi16(__m64, __m64);` \[3] | -| [`_mm_subs_pu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pu8) | MMX | mmintrin.h | `__m64 _mm_subs_pu8(__m64, __m64);` \[3] | -| [`_mm_subs_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pu16) | MMX | mmintrin.h | `__m64 _mm_subs_pu16(__m64, __m64);` \[3] | -| [`_mm_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_pd) | AVX \[2] | immintrin.h | `int _mm_testc_pd(__m128d, __m128d);` | -| [`_mm_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_ps) | AVX \[2] | immintrin.h | `int _mm_testc_ps(__m128, __m128);` | +| [`_mm_subs_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pi8) | MMX | mmintrin.h | `__m64 _mm_subs_pi8(__m64, __m64);` \[Macro] | +| [`_mm_subs_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pi16) | MMX | mmintrin.h | `__m64 _mm_subs_pi16(__m64, __m64);` \[Macro] | +| [`_mm_subs_pu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pu8) | MMX | mmintrin.h | `__m64 _mm_subs_pu8(__m64, __m64);` \[Macro] | +| [`_mm_subs_pu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_subs_pu16) | MMX | mmintrin.h | `__m64 _mm_subs_pu16(__m64, __m64);` \[Macro] | +| [`_mm_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_pd) | AVX | immintrin.h | `int _mm_testc_pd(__m128d, __m128d);` | +| [`_mm_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_ps) | AVX | immintrin.h | `int _mm_testc_ps(__m128, __m128);` | | [`_mm_testc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testc_si128) | SSE41 | intrin.h | `int _mm_testc_si128(__m128i, __m128i);` | -| [`_mm_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_pd) | AVX \[2] | immintrin.h | `int _mm_testnzc_pd(__m128d, __m128d);` | -| [`_mm_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_ps) | AVX \[2] | immintrin.h | `int _mm_testnzc_ps(__m128, __m128);` | +| [`_mm_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_pd) | AVX | immintrin.h | `int _mm_testnzc_pd(__m128d, __m128d);` | +| [`_mm_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_ps) | AVX | immintrin.h | `int _mm_testnzc_ps(__m128, __m128);` | | [`_mm_testnzc_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testnzc_si128) | SSE41 | intrin.h | `int _mm_testnzc_si128(__m128i, __m128i);` | -| [`_mm_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_pd) | AVX \[2] | immintrin.h | `int _mm_testz_pd(__m128d, __m128d);` | -| [`_mm_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_ps) | AVX \[2] | immintrin.h | `int _mm_testz_ps(__m128, __m128);` | +| [`_mm_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_pd) | AVX | immintrin.h | `int _mm_testz_pd(__m128d, __m128d);` | +| [`_mm_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_ps) | AVX | immintrin.h | `int _mm_testz_ps(__m128, __m128);` | | [`_mm_testz_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_testz_si128) | SSE41 | intrin.h | `int _mm_testz_si128(__m128i, __m128i);` | | [`_mm_ucomieq_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_ucomieq_sd) | SSE2 | intrin.h | `int _mm_ucomieq_sd(__m128d, __m128d);` | | [`_mm_ucomieq_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_ucomieq_ss) | SSE | intrin.h | `int _mm_ucomieq_ss(__m128, __m128);` | @@ -879,350 +885,350 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm_unpackhi_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_epi64) | SSE2 | intrin.h | `__m128i _mm_unpackhi_epi64(__m128i, __m128i);` | | [`_mm_unpackhi_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_epi8) | SSE2 | intrin.h | `__m128i _mm_unpackhi_epi8(__m128i, __m128i);` | | [`_mm_unpackhi_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pd) | SSE2 | intrin.h | `__m128d _mm_unpackhi_pd(__m128d, __m128d);` | -| [`_mm_unpackhi_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi8) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi8 (__m64, __m64);` \[3] | -| [`_mm_unpackhi_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi16) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi16 (__m64, __m64);` \[3] | -| [`_mm_unpackhi_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi32) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi32 (__m64, __m64);` \[3] | +| [`_mm_unpackhi_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi8) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi8 (__m64, __m64);` \[Macro] | +| [`_mm_unpackhi_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi16) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi16 (__m64, __m64);` \[Macro] | +| [`_mm_unpackhi_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_pi32) | MMX | mmintrin.h | `__m64 _mm_unpackhi_pi32 (__m64, __m64);` \[Macro] | | [`_mm_unpackhi_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpackhi_ps) | SSE | intrin.h | `__m128 _mm_unpackhi_ps(__m128, __m128);` | | [`_mm_unpacklo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_epi16) | SSE2 | intrin.h | `__m128i _mm_unpacklo_epi16(__m128i, __m128i);` | | [`_mm_unpacklo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_epi32) | SSE2 | intrin.h | `__m128i _mm_unpacklo_epi32(__m128i, __m128i);` | | [`_mm_unpacklo_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_epi64) | SSE2 | intrin.h | `__m128i _mm_unpacklo_epi64(__m128i, __m128i);` | | [`_mm_unpacklo_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_epi8) | SSE2 | intrin.h | `__m128i _mm_unpacklo_epi8(__m128i, __m128i);` | | [`_mm_unpacklo_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pd) | SSE2 | intrin.h | `__m128d _mm_unpacklo_pd(__m128d, __m128d);` | -| [`_mm_unpacklo_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi8) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi8 (__m64, __m64);` \[3] | -| [`_mm_unpacklo_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi16) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi16 (__m64, __m64);` \[3] | -| [`_mm_unpacklo_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi32) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi32 (__m64, __m64);` \[3] | +| [`_mm_unpacklo_pi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi8) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi8 (__m64, __m64);` \[Macro] | +| [`_mm_unpacklo_pi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi16) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi16 (__m64, __m64);` \[Macro] | +| [`_mm_unpacklo_pi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_pi32) | MMX | mmintrin.h | `__m64 _mm_unpacklo_pi32 (__m64, __m64);` \[Macro] | | [`_mm_unpacklo_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_unpacklo_ps) | SSE | intrin.h | `__m128 _mm_unpacklo_ps(__m128, __m128);` | | [`_mm_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_pd) | SSE2 | intrin.h | `__m128d _mm_xor_pd(__m128d, __m128d);` | | [`_mm_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_ps) | SSE | intrin.h | `__m128 _mm_xor_ps(__m128, __m128);` | -| [`_mm_xor_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_si64) | MMX | mmintrin.h | `__m64 _mm_xor_si64(__m64, __m64);` \[3] | +| [`_mm_xor_si64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_si64) | MMX | mmintrin.h | `__m64 _mm_xor_si64(__m64, __m64);` \[Macro] | | [`_mm_xor_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_xor_si128) | SSE2 | intrin.h | `__m128i _mm_xor_si128(__m128i, __m128i);` | -| [`_mm256_abs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi16(__m256i);` | -| [`_mm256_abs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi32(__m256i);` | -| [`_mm256_abs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_abs_epi8(__m256i);` | -| [`_mm256_add_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi16(__m256i, __m256i);` | -| [`_mm256_add_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi32(__m256i, __m256i);` | -| [`_mm256_add_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi64(__m256i, __m256i);` | -| [`_mm256_add_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_add_epi8(__m256i, __m256i);` | -| [`_mm256_add_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_add_pd(__m256d, __m256d);` | -| [`_mm256_add_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_add_ps(__m256, __m256);` | -| [`_mm256_adds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epi16(__m256i, __m256i);` | -| [`_mm256_adds_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epi8(__m256i, __m256i);` | -| [`_mm256_adds_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epu16(__m256i, __m256i);` | -| [`_mm256_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_adds_epu8(__m256i, __m256i);` | -| [`_mm256_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_addsub_pd(__m256d, __m256d);` | -| [`_mm256_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_addsub_ps(__m256, __m256);` | -| [`_mm256_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_alignr_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_alignr_epi8(__m256i, __m256i, const int);` | -| [`_mm256_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_and_pd(__m256d, __m256d);` | -| [`_mm256_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_and_ps(__m256, __m256);` | -| [`_mm256_and_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_and_si256(__m256i, __m256i);` | -| [`_mm256_andnot_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_andnot_pd(__m256d, __m256d);` | -| [`_mm256_andnot_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_andnot_ps(__m256, __m256);` | -| [`_mm256_andnot_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_andnot_si256(__m256i, __m256i);` | -| [`_mm256_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_avg_epu16(__m256i, __m256i);` | -| [`_mm256_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_avg_epu8(__m256i, __m256i);` | -| [`_mm256_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blend_epi16(__m256i, __m256i, const int);` | -| [`_mm256_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blend_epi32(__m256i, __m256i, const int);` | -| [`_mm256_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_blend_pd(__m256d, __m256d, const int);` | -| [`_mm256_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_blend_ps(__m256, __m256, const int);` | -| [`_mm256_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_blendv_epi8(__m256i, __m256i, __m256i);` | -| [`_mm256_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_blendv_pd(__m256d, __m256d, __m256d);` | -| [`_mm256_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_blendv_ps(__m256, __m256, __m256);` | -| [`_mm256_broadcast_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_broadcast_pd(__m128d const *);` | -| [`_mm256_broadcast_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_broadcast_ps(__m128 const *);` | -| [`_mm256_broadcast_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_sd) | AVX \[2] | immintrin.h | `__m256d _mm256_broadcast_sd(double const *);` | -| [`_mm256_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ss) | AVX \[2] | immintrin.h | `__m256 _mm256_broadcast_ss(float const *);` | -| [`_mm256_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastb_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastb_epi8 (__m128i);` | -| [`_mm256_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastd_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastd_epi32(__m128i);` | -| [`_mm256_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastq_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastq_epi64(__m128i);` | -| [`_mm256_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsd_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_broadcastsd_pd(__m128d);` | -| [`_mm256_broadcastsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsi128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastsi128_si256(__m128i);` | -| [`_mm256_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastss_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_broadcastss_ps(__m128);` | -| [`_mm256_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastw_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_broadcastw_epi16(__m128i);` | -| [`_mm256_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_castpd_ps(__m256d);` | -| [`_mm256_castpd_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castpd_si256(__m256d);` | -| [`_mm256_castpd128_pd256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd128_pd256) | AVX \[2] | immintrin.h | `__m256d _mm256_castpd128_pd256(__m128d);` | -| [`_mm256_castpd256_pd128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd256_pd128) | AVX \[2] | immintrin.h | `__m128d _mm256_castpd256_pd128(__m256d);` | -| [`_mm256_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_castps_pd(__m256);` | -| [`_mm256_castps_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castps_si256(__m256);` | -| [`_mm256_castps128_ps256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps128_ps256) | AVX \[2] | immintrin.h | `__m256 _mm256_castps128_ps256(__m128);` | -| [`_mm256_castps256_ps128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps256_ps128) | AVX \[2] | immintrin.h | `__m128 _mm256_castps256_ps128(__m256);` | -| [`_mm256_castsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_castsi128_si256(__m128i);` | -| [`_mm256_castsi256_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_castsi256_pd(__m256i);` | -| [`_mm256_castsi256_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_castsi256_ps(__m256i);` | -| [`_mm256_castsi256_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_si128) | AVX \[2] | immintrin.h | `__m128i _mm256_castsi256_si128(__m256i);` | -| `_mm256_cmov_si256` | XOP \[1] | ammintrin.h | `__m256i _mm256_cmov_si256(__m256i, __m256i, __m256i);` | -| [`_mm256_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cmp_pd(__m256d, __m256d, const int);` | -| [`_mm256_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_cmp_ps(__m256, __m256, const int);` | -| [`_mm256_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi16(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi32(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi64(__m256i, __m256i);` | -| [`_mm256_cmpeq_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpeq_epi8(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi16(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi32(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi64(__m256i, __m256i);` | -| [`_mm256_cmpgt_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cmpgt_epi8(__m256i, __m256i);` | -| [`_mm256_cvtepi16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi16_epi32(__m128i);` | -| [`_mm256_cvtepi16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi16_epi64(__m128i);` | -| [`_mm256_cvtepi32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi32_epi64(__m128i);` | -| [`_mm256_cvtepi32_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cvtepi32_pd(__m128i);` | -| [`_mm256_cvtepi32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_cvtepi32_ps(__m256i);` | -| [`_mm256_cvtepi8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi16(__m128i);` | -| [`_mm256_cvtepi8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi32(__m128i);` | -| [`_mm256_cvtepi8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepi8_epi64(__m128i);` | -| [`_mm256_cvtepu16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu16_epi32(__m128i);` | -| [`_mm256_cvtepu16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu16_epi64(__m128i);` | -| [`_mm256_cvtepu32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu32_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu32_epi64(__m128i);` | -| [`_mm256_cvtepu8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi16(__m128i);` | -| [`_mm256_cvtepu8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi32(__m128i);` | -| [`_mm256_cvtepu8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_cvtepu8_epi64(__m128i);` | -| [`_mm256_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_epi32) | AVX \[2] | immintrin.h | `__m128i _mm256_cvtpd_epi32(__m256d);` | -| [`_mm256_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_ps) | AVX \[2] | immintrin.h | `__m128 _mm256_cvtpd_ps(__m256d);` | -| [`_mm256_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtph_ps) | F16C \[2] | immintrin.h | `__m256 _mm256_cvtph_ps(__m128i);` | -| [`_mm256_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_cvtps_epi32(__m256);` | -| [`_mm256_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_cvtps_pd(__m128);` | -| [`_mm256_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_ph) | F16C \[2] | immintrin.h | `__m128i _mm256_cvtps_ph(__m256, const int);` | -| [`_mm256_cvttpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttpd_epi32) | AVX \[2] | immintrin.h | `__m128i _mm256_cvttpd_epi32(__m256d);` | -| [`_mm256_cvttps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttps_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_cvttps_epi32(__m256);` | -| [`_mm256_div_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_div_pd(__m256d, __m256d);` | -| [`_mm256_div_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_div_ps(__m256, __m256);` | -| [`_mm256_dp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_dp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_dp_ps(__m256, __m256, const int);` | -| [`_mm256_extractf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_pd) | AVX \[2] | immintrin.h | `__m128d _mm256_extractf128_pd(__m256d, const int);` | -| [`_mm256_extractf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_ps) | AVX \[2] | immintrin.h | `__m128 _mm256_extractf128_ps(__m256, const int);` | -| [`_mm256_extractf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_si256) | AVX \[2] | immintrin.h | `__m128i _mm256_extractf128_si256(__m256i, const int);` | -| [`_mm256_extracti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extracti128_si256) | AVX2 \[2] | immintrin.h | `__m128i _mm256_extracti128_si256(__m256i, int);` | -| [`_mm256_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmaddsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmaddsub_ps (__m256, __m256, __m256);` | -| [`_mm256_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmsub_ps (__m256, __m256, __m256);` | -| [`_mm256_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fmsubadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fmsubadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fnmadd_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fnmadd_ps (__m256, __m256, __m256);` | -| [`_mm256_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_pd) | FMA \[2] | immintrin.h | `__m256d _mm256_fnmsub_pd (__m256d, __m256d, __m256d);` | -| [`_mm256_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_ps) | FMA \[2] | immintrin.h | `__m256 _mm256_fnmsub_ps (__m256, __m256, __m256);` | -| `_mm256_frcz_pd` | XOP \[1] | ammintrin.h | `__m256d _mm256_frcz_pd(__m256d);` | -| `_mm256_frcz_ps` | XOP \[1] | ammintrin.h | `__m256 _mm256_frcz_ps(__m256);` | -| [`_mm256_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadd_epi16(__m256i, __m256i);` | -| [`_mm256_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadd_epi32(__m256i, __m256i);` | -| [`_mm256_hadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_hadd_pd(__m256d, __m256d);` | -| [`_mm256_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_hadd_ps(__m256, __m256);` | -| [`_mm256_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadds_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hadds_epi16(__m256i, __m256i);` | -| [`_mm256_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsub_epi16(__m256i, __m256i);` | -| [`_mm256_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsub_epi32(__m256i, __m256i);` | -| [`_mm256_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_hsub_pd(__m256d, __m256d);` | -| [`_mm256_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_hsub_ps(__m256, __m256);` | -| [`_mm256_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsubs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_hsubs_epi16(__m256i, __m256i);` | -| [`_mm256_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i32gather_epi32(int const *, __m256i, const int);` | -| [`_mm256_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i32gather_epi64(__int64 const *, __m128i, const int);` | -| [`_mm256_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_i32gather_pd(double const *, __m128i, const int);` | -| [`_mm256_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_i32gather_ps(float const *, __m256i, const int);` | -| [`_mm256_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i64gather_epi32(int const *, __m256i, const int);` | -| [`_mm256_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_i64gather_epi64(__int64 const *, __m256i, const int);` | -| [`_mm256_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_i64gather_pd(double const *, __m256i, const int);` | -| [`_mm256_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm256_i64gather_ps(float const *, __m256i, const int);` | -| [`_mm256_insertf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_insertf128_pd(__m256d, __m128d, int);` | -| [`_mm256_insertf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_insertf128_ps(__m256, __m128, int);` | -| [`_mm256_insertf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_insertf128_si256(__m256i, __m128i, int);` | -| [`_mm256_inserti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_inserti128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_inserti128_si256(__m256i, __m128i, int);` | -| [`_mm256_lddqu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_lddqu_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_lddqu_si256(__m256i *);` | -| [`_mm256_load_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_load_pd(double const *);` | -| [`_mm256_load_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_load_ps(float const *);` | -| [`_mm256_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_load_si256(__m256i *);` | -| [`_mm256_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_loadu_pd(double const *);` | -| [`_mm256_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_loadu_ps(float const *);` | -| [`_mm256_loadu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_loadu_si256(__m256i *);` | -| `_mm256_macc_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_macc_pd(__m256d, __m256d, __m256d);` | -| `_mm256_macc_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_macc_ps(__m256, __m256, __m256);` | -| [`_mm256_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_madd_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_madd_epi16(__m256i, __m256i);` | -| `_mm256_maddsub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_maddsub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_maddsub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_maddsub_ps(__m256, __m256, __m256);` | -| [`_mm256_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maddubs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maddubs_epi16(__m256i, __m256i);` | -| [`_mm256_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i32gather_epi32(__m256i, int const *, __m256i, __m256i, const int);` | -| [`_mm256_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i32gather_epi64(__m256i, __int64 const *, __m128i, __m256i, const int);` | -| [`_mm256_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_mask_i32gather_pd(__m256d, double const *, __m128i, __m256d, const int);` | -| [`_mm256_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_mask_i32gather_ps(__m256, float const *, __m256i, __m256, const int);` | -| [`_mm256_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi32) | AVX2 \[2] | immintrin.h | `__m128i _mm256_mask_i64gather_epi32(__m128i, int const *, __m256i, __m128i, const int);` | -| [`_mm256_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mask_i64gather_epi64(__m256i, __int64 const *, __m256i, __m256i, const int);` | -| [`_mm256_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_mask_i64gather_pd(__m256d, double const *, __m256i, __m256d, const int);` | -| [`_mm256_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_ps) | AVX2 \[2] | immintrin.h | `__m128 _mm256_mask_i64gather_ps(__m128, float const *, __m256i, __m128, const int);` | -| [`_mm256_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maskload_epi32(int const *, __m256i);` | -| [`_mm256_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_maskload_epi64(__int64 const *, __m256i);` | -| [`_mm256_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_maskload_pd(double const *, __m256i);` | -| [`_mm256_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_maskload_ps(float const *, __m256i);` | -| [`_mm256_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi32) | AVX2 \[2] | immintrin.h | `void _mm256_maskstore_epi32(int *, __m256i, __m256i);` | -| [`_mm256_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi64) | AVX2 \[2] | immintrin.h | `void _mm256_maskstore_epi64(__int64 *, __m256i, __m256i);` | -| [`_mm256_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_pd) | AVX \[2] | immintrin.h | `void _mm256_maskstore_pd(double *, __m256i, __m256d);` | -| [`_mm256_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_ps) | AVX \[2] | immintrin.h | `void _mm256_maskstore_ps(float *, __m256i, __m256);` | -| [`_mm256_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi16(__m256i, __m256i);` | -| [`_mm256_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi32(__m256i, __m256i);` | -| [`_mm256_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epi8(__m256i, __m256i);` | -| [`_mm256_max_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu16(__m256i, __m256i);` | -| [`_mm256_max_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu32(__m256i, __m256i);` | -| [`_mm256_max_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_max_epu8(__m256i, __m256i);` | -| [`_mm256_max_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_max_pd(__m256d, __m256d);` | -| [`_mm256_max_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_max_ps(__m256, __m256);` | -| [`_mm256_min_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi16(__m256i, __m256i);` | -| [`_mm256_min_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi32(__m256i, __m256i);` | -| [`_mm256_min_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epi8(__m256i, __m256i);` | -| [`_mm256_min_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu16(__m256i, __m256i);` | -| [`_mm256_min_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu32(__m256i, __m256i);` | -| [`_mm256_min_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_min_epu8(__m256i, __m256i);` | -| [`_mm256_min_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_min_pd(__m256d, __m256d);` | -| [`_mm256_min_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_min_ps(__m256, __m256);` | -| [`_mm256_movedup_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movedup_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_movedup_pd(__m256d);` | -| [`_mm256_movehdup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movehdup_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_movehdup_ps(__m256);` | -| [`_mm256_moveldup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_moveldup_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_moveldup_ps(__m256);` | -| [`_mm256_movemask_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_epi8) | AVX2 \[2] | immintrin.h | `int _mm256_movemask_epi8(__m256i);` | -| [`_mm256_movemask_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_pd) | AVX \[2] | immintrin.h | `int _mm256_movemask_pd(__m256d);` | -| [`_mm256_movemask_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_ps) | AVX \[2] | immintrin.h | `int _mm256_movemask_ps(__m256);` | -| [`_mm256_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mpsadbw_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mpsadbw_epu8(__m256i, __m256i, const int);` | -| `_mm256_msub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_msub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_msub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_msub_ps(__m256, __m256, __m256);` | -| `_mm256_msubadd_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_msubadd_pd(__m256d, __m256d, __m256d);` | -| `_mm256_msubadd_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_msubadd_ps(__m256, __m256, __m256);` | -| [`_mm256_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mul_epi32(__m256i, __m256i);` | -| [`_mm256_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epu32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mul_epu32(__m256i, __m256i);` | -| [`_mm256_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_mul_pd(__m256d, __m256d);` | -| [`_mm256_mul_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_mul_ps(__m256, __m256);` | -| [`_mm256_mulhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhi_epi16(__m256i, __m256i);` | -| [`_mm256_mulhi_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhi_epu16(__m256i, __m256i);` | -| [`_mm256_mulhrs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhrs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mulhrs_epi16(__m256i, __m256i);` | -| [`_mm256_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mullo_epi16(__m256i, __m256i);` | -| [`_mm256_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_mullo_epi32(__m256i, __m256i);` | -| `_mm256_nmacc_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_nmacc_pd(__m256d, __m256d, __m256d);` | -| `_mm256_nmacc_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_nmacc_ps(__m256, __m256, __m256);` | -| `_mm256_nmsub_pd` | FMA4 \[1] | ammintrin.h | `__m256d _mm_nmsub_pd(__m256d, __m256d, __m256d);` | -| `_mm256_nmsub_ps` | FMA4 \[1] | ammintrin.h | `__m256 _mm_nmsub_ps(__m256, __m256, __m256);` | -| [`_mm256_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_or_pd(__m256d, __m256d);` | -| [`_mm256_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_or_ps(__m256, __m256);` | -| [`_mm256_or_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_or_si256(__m256i, __m256i);` | -| [`_mm256_packs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packs_epi16(__m256i, __m256i);` | -| [`_mm256_packs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packs_epi32(__m256i, __m256i);` | -| [`_mm256_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packus_epi16(__m256i, __m256i);` | -| [`_mm256_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_packus_epi32(__m256i, __m256i);` | -| [`_mm256_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permute_pd(__m256d, int);` | -| [`_mm256_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permute_ps(__m256, int);` | -| `_mm256_permute2_pd` | XOP \[1] | ammintrin.h | `__m256d _mm256_permute2_pd(__m256d, __m256d, __m256i, int);` | -| `_mm256_permute2_ps` | XOP \[1] | ammintrin.h | `__m256 _mm256_permute2_ps(__m256, __m256, __m256i, int);` | -| [`_mm256_permute2f128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permute2f128_pd(__m256d, __m256d, int);` | -| [`_mm256_permute2f128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permute2f128_ps(__m256, __m256, int);` | -| [`_mm256_permute2f128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_permute2f128_si256(__m256i, __m256i, int);` | -| [`_mm256_permute2x128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2x128_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permute2x128_si256(__m256i, __m256i, const int);` | -| [`_mm256_permute4x64_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permute4x64_epi64 (__m256i, const int);` | -| [`_mm256_permute4x64_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_pd) | AVX2 \[2] | immintrin.h | `__m256d _mm256_permute4x64_pd(__m256d, const int);` | -| [`_mm256_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_permutevar_pd(__m256d, __m256i);` | -| [`_mm256_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_permutevar_ps(__m256, __m256i);` | -| [`_mm256_permutevar8x32_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_permutevar8x32_epi32(__m256i, __m256i);` | -| [`_mm256_permutevar8x32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_ps) | AVX2 \[2] | immintrin.h | `__m256 _mm256_permutevar8x32_ps (__m256, __m256i);` | -| [`_mm256_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rcp_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_rcp_ps(__m256);` | -| [`_mm256_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_round_pd(__m256d, int);` | -| [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | -| [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | -| [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | -| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX \[2] | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | -| [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | -| [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX \[2] | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | -| [`_mm256_set_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_set_pd(double, double, double, double);` | -| [`_mm256_set_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_set_ps(float, float, float, float, float, float, float, float);` | -| [`_mm256_set1_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi16) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi16(short);` | -| [`_mm256_set1_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi32(int);` | -| [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX \[2] | immintrin.h | `__m256i _mm256_set1_epi8(char);` | -| [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_set1_pd(double);` | -| [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_set1_ps(float);` | -| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX \[2] | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | -| [`_mm256_setr_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi32) | AVX \[2] | immintrin.h | `__m256i _mm256_setr_epi32(int, int, int, int, int, int, int, int);` | -| [`_mm256_setr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi8) | AVX \[2] | immintrin.h | `(__m256i _mm256_setr_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char,);` | -| [`_mm256_setr_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_setr_pd(double, double, double, double);` | -| [`_mm256_setr_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_setr_ps(float, float, float, float, float, float, float, float);` | -| [`_mm256_setzero_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_setzero_pd(void);` | -| [`_mm256_setzero_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_setzero_ps(void);` | -| [`_mm256_setzero_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_si256) | AVX \[2] | immintrin.h | `__m256i _mm256_setzero_si256(void);` | -| [`_mm256_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shuffle_epi32(__m256i, const int);` | -| [`_mm256_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shuffle_epi8(__m256i, __m256i);` | -| [`_mm256_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_shuffle_pd(__m256d, __m256d, const int);` | -| [`_mm256_shuffle_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_shuffle_ps(__m256, __m256, const int);` | -| [`_mm256_shufflehi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflehi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shufflehi_epi16(__m256i, const int);` | -| [`_mm256_shufflelo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflelo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_shufflelo_epi16(__m256i, const int);` | -| [`_mm256_sign_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi16(__m256i, __m256i);` | -| [`_mm256_sign_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi32(__m256i, __m256i);` | -| [`_mm256_sign_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sign_epi8(__m256i, __m256i);` | -| [`_mm256_sll_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi16(__m256i, __m128i);` | -| [`_mm256_sll_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi32(__m256i, __m128i);` | -| [`_mm256_sll_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sll_epi64(__m256i, __m128i);` | -| [`_mm256_slli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi16(__m256i, int);` | -| [`_mm256_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi32(__m256i, int);` | -| [`_mm256_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_epi64(__m256i, int);` | -| [`_mm256_slli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_slli_si256(__m256i, int);` | -| [`_mm256_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sllv_epi32(__m256i, __m256i);` | -| [`_mm256_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sllv_epi64(__m256i, __m256i);` | -| [`_mm256_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_sqrt_pd(__m256d);` | -| [`_mm256_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_sqrt_ps(__m256);` | -| [`_mm256_sra_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sra_epi16(__m256i, __m128i);` | -| [`_mm256_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sra_epi32(__m256i, __m128i);` | -| [`_mm256_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srai_epi16(__m256i, int);` | -| [`_mm256_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srai_epi32(__m256i, int);` | -| [`_mm256_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srav_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srav_epi32(__m256i, __m256i);` | -| [`_mm256_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi16(__m256i, __m128i);` | -| [`_mm256_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi32(__m256i, __m128i);` | -| [`_mm256_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srl_epi64(__m256i, __m128i);` | -| [`_mm256_srli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi16(__m256i, int);` | -| [`_mm256_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi32(__m256i, int);` | -| [`_mm256_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_epi64(__m256i, int);` | -| [`_mm256_srli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srli_si256(__m256i, int);` | -| [`_mm256_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srlv_epi32(__m256i, __m256i);` | -| [`_mm256_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_srlv_epi64(__m256i, __m256i);` | -| [`_mm256_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_pd) | AVX \[2] | immintrin.h | `void _mm256_store_pd(double *, __m256d);` | -| [`_mm256_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_ps) | AVX \[2] | immintrin.h | `void _mm256_store_ps(float *, __m256);` | -| [`_mm256_store_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_si256) | AVX \[2] | immintrin.h | `void _mm256_store_si256(__m256i *, __m256i);` | -| [`_mm256_storeu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_pd) | AVX \[2] | immintrin.h | `void _mm256_storeu_pd(double *, __m256d);` | -| [`_mm256_storeu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_ps) | AVX \[2] | immintrin.h | `void _mm256_storeu_ps(float *, __m256);` | -| [`_mm256_storeu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_si256) | AVX \[2] | immintrin.h | `void _mm256_storeu_si256(__m256i *, __m256i);` | -| [`_mm256_stream_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_load_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_stream_load_si256(__m256i const *);` | -| [`_mm256_stream_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_pd) | AVX \[2] | immintrin.h | `void __mm256_stream_pd(double *, __m256d);` | -| [`_mm256_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_ps) | AVX \[2] | immintrin.h | `void _mm256_stream_ps(float *, __m256);` | -| [`_mm256_stream_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_si256) | AVX \[2] | immintrin.h | `void __mm256_stream_si256(__m256i *, __m256i);` | -| [`_mm256_sub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi16(__m256i, __m256i);` | -| [`_mm256_sub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi32(__m256i, __m256i);` | -| [`_mm256_sub_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi64(__m256i, __m256i);` | -| [`_mm256_sub_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_sub_epi8(__m256i, __m256i);` | -| [`_mm256_sub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_sub_pd(__m256d, __m256d);` | -| [`_mm256_sub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_sub_ps(__m256, __m256);` | -| [`_mm256_subs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epi16(__m256i, __m256i);` | -| [`_mm256_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epi8(__m256i, __m256i);` | -| [`_mm256_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epu16(__m256i, __m256i);` | -| [`_mm256_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_subs_epu8(__m256i, __m256i);` | -| [`_mm256_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_pd) | AVX \[2] | immintrin.h | `int _mm256_testc_pd(__m256d, __m256d);` | -| [`_mm256_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_ps) | AVX \[2] | immintrin.h | `int _mm256_testc_ps(__m256, __m256);` | -| [`_mm256_testc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_si256) | AVX \[2] | immintrin.h | `int _mm256_testc_si256(__m256i, __m256i);` | -| [`_mm256_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_pd) | AVX \[2] | immintrin.h | `int _mm256_testnzc_pd(__m256d, __m256d);` | -| [`_mm256_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_ps) | AVX \[2] | immintrin.h | `int _mm256_testnzc_ps(__m256, __m256);` | -| [`_mm256_testnzc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_si256) | AVX \[2] | immintrin.h | `int _mm256_testnzc_si256(__m256i, __m256i);` | -| [`_mm256_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_pd) | AVX \[2] | immintrin.h | `int _mm256_testz_pd(__m256d, __m256d);` | -| [`_mm256_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_ps) | AVX \[2] | immintrin.h | `int _mm256_testz_ps(__m256, __m256);` | -| [`_mm256_testz_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_si256) | AVX \[2] | immintrin.h | `int _mm256_testz_si256(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi16(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi32(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi64(__m256i, __m256i);` | -| [`_mm256_unpackhi_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpackhi_epi8(__m256i, __m256i);` | -| [`_mm256_unpackhi_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_unpackhi_pd(__m256d, __m256d);` | -| [`_mm256_unpackhi_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_unpackhi_ps(__m256, __m256);` | -| [`_mm256_unpacklo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi16) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi16(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi32) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi32(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi64) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi64(__m256i, __m256i);` | -| [`_mm256_unpacklo_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi8) | AVX2 \[2] | immintrin.h | `__m256i _mm256_unpacklo_epi8(__m256i, __m256i);` | -| [`_mm256_unpacklo_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_unpacklo_pd(__m256d, __m256d);` | -| [`_mm256_unpacklo_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_unpacklo_ps(__m256, __m256);` | -| [`_mm256_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_pd) | AVX \[2] | immintrin.h | `__m256d _mm256_xor_pd(__m256d, __m256d);` | -| [`_mm256_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_ps) | AVX \[2] | immintrin.h | `__m256 _mm256_xor_ps(__m256, __m256);` | -| [`_mm256_xor_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_si256) | AVX2 \[2] | immintrin.h | `__m256i _mm256_xor_si256(__m256i, __m256i);` | -| [`_mm256_zeroall`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroall) | AVX \[2] | immintrin.h | `void _mm256_zeroall(void);` | -| [`_mm256_zeroupper`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroupper) | AVX \[2] | immintrin.h | `void _mm256_zeroupper(void);` | +| [`_mm256_abs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi16(__m256i);` | +| [`_mm256_abs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi32) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi32(__m256i);` | +| [`_mm256_abs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_abs_epi8) | AVX2 | immintrin.h | `__m256i _mm256_abs_epi8(__m256i);` | +| [`_mm256_add_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi16) | AVX2 | immintrin.h | `__m256i _mm256_add_epi16(__m256i, __m256i);` | +| [`_mm256_add_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi32) | AVX2 | immintrin.h | `__m256i _mm256_add_epi32(__m256i, __m256i);` | +| [`_mm256_add_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi64) | AVX2 | immintrin.h | `__m256i _mm256_add_epi64(__m256i, __m256i);` | +| [`_mm256_add_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_epi8) | AVX2 | immintrin.h | `__m256i _mm256_add_epi8(__m256i, __m256i);` | +| [`_mm256_add_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_pd) | AVX | immintrin.h | `__m256d _mm256_add_pd(__m256d, __m256d);` | +| [`_mm256_add_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_add_ps) | AVX | immintrin.h | `__m256 _mm256_add_ps(__m256, __m256);` | +| [`_mm256_adds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi16) | AVX2 | immintrin.h | `__m256i _mm256_adds_epi16(__m256i, __m256i);` | +| [`_mm256_adds_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epi8) | AVX2 | immintrin.h | `__m256i _mm256_adds_epi8(__m256i, __m256i);` | +| [`_mm256_adds_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu16) | AVX2 | immintrin.h | `__m256i _mm256_adds_epu16(__m256i, __m256i);` | +| [`_mm256_adds_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_adds_epu8) | AVX2 | immintrin.h | `__m256i _mm256_adds_epu8(__m256i, __m256i);` | +| [`_mm256_addsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_pd) | AVX | immintrin.h | `__m256d _mm256_addsub_pd(__m256d, __m256d);` | +| [`_mm256_addsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_addsub_ps) | AVX | immintrin.h | `__m256 _mm256_addsub_ps(__m256, __m256);` | +| [`_mm256_alignr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_alignr_epi8) | AVX2 | immintrin.h | `__m256i _mm256_alignr_epi8(__m256i, __m256i, const int);` | +| [`_mm256_and_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_pd) | AVX | immintrin.h | `__m256d _mm256_and_pd(__m256d, __m256d);` | +| [`_mm256_and_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_ps) | AVX | immintrin.h | `__m256 _mm256_and_ps(__m256, __m256);` | +| [`_mm256_and_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_and_si256) | AVX2 | immintrin.h | `__m256i _mm256_and_si256(__m256i, __m256i);` | +| [`_mm256_andnot_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_pd) | AVX | immintrin.h | `__m256d _mm256_andnot_pd(__m256d, __m256d);` | +| [`_mm256_andnot_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_ps) | AVX | immintrin.h | `__m256 _mm256_andnot_ps(__m256, __m256);` | +| [`_mm256_andnot_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_andnot_si256) | AVX2 | immintrin.h | `__m256i _mm256_andnot_si256(__m256i, __m256i);` | +| [`_mm256_avg_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu16) | AVX2 | immintrin.h | `__m256i _mm256_avg_epu16(__m256i, __m256i);` | +| [`_mm256_avg_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_avg_epu8) | AVX2 | immintrin.h | `__m256i _mm256_avg_epu8(__m256i, __m256i);` | +| [`_mm256_blend_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi16) | AVX2 | immintrin.h | `__m256i _mm256_blend_epi16(__m256i, __m256i, const int);` | +| [`_mm256_blend_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_epi32) | AVX2 | immintrin.h | `__m256i _mm256_blend_epi32(__m256i, __m256i, const int);` | +| [`_mm256_blend_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_pd) | AVX | immintrin.h | `__m256d _mm256_blend_pd(__m256d, __m256d, const int);` | +| [`_mm256_blend_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blend_ps) | AVX | immintrin.h | `__m256 _mm256_blend_ps(__m256, __m256, const int);` | +| [`_mm256_blendv_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_epi8) | AVX2 | immintrin.h | `__m256i _mm256_blendv_epi8(__m256i, __m256i, __m256i);` | +| [`_mm256_blendv_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_pd) | AVX | immintrin.h | `__m256d _mm256_blendv_pd(__m256d, __m256d, __m256d);` | +| [`_mm256_blendv_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_blendv_ps) | AVX | immintrin.h | `__m256 _mm256_blendv_ps(__m256, __m256, __m256);` | +| [`_mm256_broadcast_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_pd) | AVX | immintrin.h | `__m256d _mm256_broadcast_pd(__m128d const *);` | +| [`_mm256_broadcast_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ps) | AVX | immintrin.h | `__m256 _mm256_broadcast_ps(__m128 const *);` | +| [`_mm256_broadcast_sd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_sd) | AVX | immintrin.h | `__m256d _mm256_broadcast_sd(double const *);` | +| [`_mm256_broadcast_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcast_ss) | AVX | immintrin.h | `__m256 _mm256_broadcast_ss(float const *);` | +| [`_mm256_broadcastb_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastb_epi8) | AVX2 | immintrin.h | `__m256i _mm256_broadcastb_epi8 (__m128i);` | +| [`_mm256_broadcastd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastd_epi32) | AVX2 | immintrin.h | `__m256i _mm256_broadcastd_epi32(__m128i);` | +| [`_mm256_broadcastq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastq_epi64) | AVX2 | immintrin.h | `__m256i _mm256_broadcastq_epi64(__m128i);` | +| [`_mm256_broadcastsd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsd_pd) | AVX2 | immintrin.h | `__m256d _mm256_broadcastsd_pd(__m128d);` | +| [`_mm256_broadcastsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastsi128_si256) | AVX2 | immintrin.h | `__m256i _mm256_broadcastsi128_si256(__m128i);` | +| [`_mm256_broadcastss_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastss_ps) | AVX2 | immintrin.h | `__m256 _mm256_broadcastss_ps(__m128);` | +| [`_mm256_broadcastw_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_broadcastw_epi16) | AVX2 | immintrin.h | `__m256i _mm256_broadcastw_epi16(__m128i);` | +| [`_mm256_castpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_ps) | AVX | immintrin.h | `__m256 _mm256_castpd_ps(__m256d);` | +| [`_mm256_castpd_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd_si256) | AVX | immintrin.h | `__m256i _mm256_castpd_si256(__m256d);` | +| [`_mm256_castpd128_pd256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd128_pd256) | AVX | immintrin.h | `__m256d _mm256_castpd128_pd256(__m128d);` | +| [`_mm256_castpd256_pd128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castpd256_pd128) | AVX | immintrin.h | `__m128d _mm256_castpd256_pd128(__m256d);` | +| [`_mm256_castps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_pd) | AVX | immintrin.h | `__m256d _mm256_castps_pd(__m256);` | +| [`_mm256_castps_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps_si256) | AVX | immintrin.h | `__m256i _mm256_castps_si256(__m256);` | +| [`_mm256_castps128_ps256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps128_ps256) | AVX | immintrin.h | `__m256 _mm256_castps128_ps256(__m128);` | +| [`_mm256_castps256_ps128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castps256_ps128) | AVX | immintrin.h | `__m128 _mm256_castps256_ps128(__m256);` | +| [`_mm256_castsi128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi128_si256) | AVX | immintrin.h | `__m256i _mm256_castsi128_si256(__m128i);` | +| [`_mm256_castsi256_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_pd) | AVX | immintrin.h | `__m256d _mm256_castsi256_pd(__m256i);` | +| [`_mm256_castsi256_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_ps) | AVX | immintrin.h | `__m256 _mm256_castsi256_ps(__m256i);` | +| [`_mm256_castsi256_si128`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_castsi256_si128) | AVX | immintrin.h | `__m128i _mm256_castsi256_si128(__m256i);` | +| `_mm256_cmov_si256` | XOP | ammintrin.h | `__m256i _mm256_cmov_si256(__m256i, __m256i, __m256i);` | +| [`_mm256_cmp_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_pd) | AVX | immintrin.h | `__m256d _mm256_cmp_pd(__m256d, __m256d, const int);` | +| [`_mm256_cmp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmp_ps) | AVX | immintrin.h | `__m256 _mm256_cmp_ps(__m256, __m256, const int);` | +| [`_mm256_cmpeq_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi16(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi32(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi64(__m256i, __m256i);` | +| [`_mm256_cmpeq_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpeq_epi8) | AVX2 | immintrin.h | `__m256i _mm256_cmpeq_epi8(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi16(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi32(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi64(__m256i, __m256i);` | +| [`_mm256_cmpgt_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cmpgt_epi8) | AVX2 | immintrin.h | `__m256i _mm256_cmpgt_epi8(__m256i, __m256i);` | +| [`_mm256_cvtepi16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi16_epi32(__m128i);` | +| [`_mm256_cvtepi16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi16_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi16_epi64(__m128i);` | +| [`_mm256_cvtepi32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi32_epi64(__m128i);` | +| [`_mm256_cvtepi32_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_pd) | AVX | immintrin.h | `__m256d _mm256_cvtepi32_pd(__m128i);` | +| [`_mm256_cvtepi32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi32_ps) | AVX | immintrin.h | `__m256 _mm256_cvtepi32_ps(__m256i);` | +| [`_mm256_cvtepi8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi16(__m128i);` | +| [`_mm256_cvtepi8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi32(__m128i);` | +| [`_mm256_cvtepi8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepi8_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepi8_epi64(__m128i);` | +| [`_mm256_cvtepu16_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu16_epi32(__m128i);` | +| [`_mm256_cvtepu16_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu16_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu16_epi64(__m128i);` | +| [`_mm256_cvtepu32_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu32_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu32_epi64(__m128i);` | +| [`_mm256_cvtepu8_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi16) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi16(__m128i);` | +| [`_mm256_cvtepu8_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi32) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi32(__m128i);` | +| [`_mm256_cvtepu8_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtepu8_epi64) | AVX2 | immintrin.h | `__m256i _mm256_cvtepu8_epi64(__m128i);` | +| [`_mm256_cvtpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_epi32) | AVX | immintrin.h | `__m128i _mm256_cvtpd_epi32(__m256d);` | +| [`_mm256_cvtpd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtpd_ps) | AVX | immintrin.h | `__m128 _mm256_cvtpd_ps(__m256d);` | +| [`_mm256_cvtph_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtph_ps) | F16C | immintrin.h | `__m256 _mm256_cvtph_ps(__m128i);` | +| [`_mm256_cvtps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_epi32) | AVX | immintrin.h | `__m256i _mm256_cvtps_epi32(__m256);` | +| [`_mm256_cvtps_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_pd) | AVX | immintrin.h | `__m256d _mm256_cvtps_pd(__m128);` | +| [`_mm256_cvtps_ph`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvtps_ph) | F16C | immintrin.h | `__m128i _mm256_cvtps_ph(__m256, const int);` | +| [`_mm256_cvttpd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttpd_epi32) | AVX | immintrin.h | `__m128i _mm256_cvttpd_epi32(__m256d);` | +| [`_mm256_cvttps_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_cvttps_epi32) | AVX | immintrin.h | `__m256i _mm256_cvttps_epi32(__m256);` | +| [`_mm256_div_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_pd) | AVX | immintrin.h | `__m256d _mm256_div_pd(__m256d, __m256d);` | +| [`_mm256_div_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_div_ps) | AVX | immintrin.h | `__m256 _mm256_div_ps(__m256, __m256);` | +| [`_mm256_dp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_dp_ps) | AVX | immintrin.h | `__m256 _mm256_dp_ps(__m256, __m256, const int);` | +| [`_mm256_extractf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_pd) | AVX | immintrin.h | `__m128d _mm256_extractf128_pd(__m256d, const int);` | +| [`_mm256_extractf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_ps) | AVX | immintrin.h | `__m128 _mm256_extractf128_ps(__m256, const int);` | +| [`_mm256_extractf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extractf128_si256) | AVX | immintrin.h | `__m128i _mm256_extractf128_si256(__m256i, const int);` | +| [`_mm256_extracti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_extracti128_si256) | AVX2 | immintrin.h | `__m128i _mm256_extracti128_si256(__m256i, int);` | +| [`_mm256_fmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_pd) | FMA | immintrin.h | `__m256d _mm256_fmadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmadd_ps) | FMA | immintrin.h | `__m256 _mm256_fmadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fmaddsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_pd) | FMA | immintrin.h | `__m256d _mm256_fmaddsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmaddsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmaddsub_ps) | FMA | immintrin.h | `__m256 _mm256_fmaddsub_ps (__m256, __m256, __m256);` | +| [`_mm256_fmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_pd) | FMA | immintrin.h | `__m256d _mm256_fmsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsub_ps) | FMA | immintrin.h | `__m256 _mm256_fmsub_ps (__m256, __m256, __m256);` | +| [`_mm256_fmsubadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_pd) | FMA | immintrin.h | `__m256d _mm256_fmsubadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fmsubadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fmsubadd_ps) | FMA | immintrin.h | `__m256 _mm256_fmsubadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fnmadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_pd) | FMA | immintrin.h | `__m256d _mm256_fnmadd_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fnmadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmadd_ps) | FMA | immintrin.h | `__m256 _mm256_fnmadd_ps (__m256, __m256, __m256);` | +| [`_mm256_fnmsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_pd) | FMA | immintrin.h | `__m256d _mm256_fnmsub_pd (__m256d, __m256d, __m256d);` | +| [`_mm256_fnmsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_fnmsub_ps) | FMA | immintrin.h | `__m256 _mm256_fnmsub_ps (__m256, __m256, __m256);` | +| `_mm256_frcz_pd` | XOP | ammintrin.h | `__m256d _mm256_frcz_pd(__m256d);` | +| `_mm256_frcz_ps` | XOP | ammintrin.h | `__m256 _mm256_frcz_ps(__m256);` | +| [`_mm256_hadd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hadd_epi16(__m256i, __m256i);` | +| [`_mm256_hadd_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_epi32) | AVX2 | immintrin.h | `__m256i _mm256_hadd_epi32(__m256i, __m256i);` | +| [`_mm256_hadd_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_pd) | AVX | immintrin.h | `__m256d _mm256_hadd_pd(__m256d, __m256d);` | +| [`_mm256_hadd_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadd_ps) | AVX | immintrin.h | `__m256 _mm256_hadd_ps(__m256, __m256);` | +| [`_mm256_hadds_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hadds_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hadds_epi16(__m256i, __m256i);` | +| [`_mm256_hsub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hsub_epi16(__m256i, __m256i);` | +| [`_mm256_hsub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_epi32) | AVX2 | immintrin.h | `__m256i _mm256_hsub_epi32(__m256i, __m256i);` | +| [`_mm256_hsub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_pd) | AVX | immintrin.h | `__m256d _mm256_hsub_pd(__m256d, __m256d);` | +| [`_mm256_hsub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsub_ps) | AVX | immintrin.h | `__m256 _mm256_hsub_ps(__m256, __m256);` | +| [`_mm256_hsubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_hsubs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_hsubs_epi16(__m256i, __m256i);` | +| [`_mm256_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_i32gather_epi32(int const *, __m256i, const int);` | +| [`_mm256_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_i32gather_epi64(__int64 const *, __m128i, const int);` | +| [`_mm256_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_i32gather_pd(double const *, __m128i, const int);` | +| [`_mm256_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i32gather_ps) | AVX2 | immintrin.h | `__m256 _mm256_i32gather_ps(float const *, __m256i, const int);` | +| [`_mm256_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_i64gather_epi32(int const *, __m256i, const int);` | +| [`_mm256_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_i64gather_epi64(__int64 const *, __m256i, const int);` | +| [`_mm256_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_i64gather_pd(double const *, __m256i, const int);` | +| [`_mm256_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm256_i64gather_ps(float const *, __m256i, const int);` | +| [`_mm256_insertf128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_pd) | AVX | immintrin.h | `__m256d _mm256_insertf128_pd(__m256d, __m128d, int);` | +| [`_mm256_insertf128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_ps) | AVX | immintrin.h | `__m256 _mm256_insertf128_ps(__m256, __m128, int);` | +| [`_mm256_insertf128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_insertf128_si256) | AVX | immintrin.h | `__m256i _mm256_insertf128_si256(__m256i, __m128i, int);` | +| [`_mm256_inserti128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_inserti128_si256) | AVX2 | immintrin.h | `__m256i _mm256_inserti128_si256(__m256i, __m128i, int);` | +| [`_mm256_lddqu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_lddqu_si256) | AVX | immintrin.h | `__m256i _mm256_lddqu_si256(__m256i *);` | +| [`_mm256_load_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_pd) | AVX | immintrin.h | `__m256d _mm256_load_pd(double const *);` | +| [`_mm256_load_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_ps) | AVX | immintrin.h | `__m256 _mm256_load_ps(float const *);` | +| [`_mm256_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_load_si256) | AVX | immintrin.h | `__m256i _mm256_load_si256(__m256i *);` | +| [`_mm256_loadu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_pd) | AVX | immintrin.h | `__m256d _mm256_loadu_pd(double const *);` | +| [`_mm256_loadu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_ps) | AVX | immintrin.h | `__m256 _mm256_loadu_ps(float const *);` | +| [`_mm256_loadu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_loadu_si256) | AVX | immintrin.h | `__m256i _mm256_loadu_si256(__m256i *);` | +| `_mm256_macc_pd` | FMA4 | ammintrin.h | `__m256d _mm_macc_pd(__m256d, __m256d, __m256d);` | +| `_mm256_macc_ps` | FMA4 | ammintrin.h | `__m256 _mm_macc_ps(__m256, __m256, __m256);` | +| [`_mm256_madd_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_madd_epi16) | AVX2 | immintrin.h | `__m256i _mm256_madd_epi16(__m256i, __m256i);` | +| `_mm256_maddsub_pd` | FMA4 | ammintrin.h | `__m256d _mm_maddsub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_maddsub_ps` | FMA4 | ammintrin.h | `__m256 _mm_maddsub_ps(__m256, __m256, __m256);` | +| [`_mm256_maddubs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maddubs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_maddubs_epi16(__m256i, __m256i);` | +| [`_mm256_mask_i32gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mask_i32gather_epi32(__m256i, int const *, __m256i, __m256i, const int);` | +| [`_mm256_mask_i32gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_mask_i32gather_epi64(__m256i, __int64 const *, __m128i, __m256i, const int);` | +| [`_mm256_mask_i32gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_mask_i32gather_pd(__m256d, double const *, __m128i, __m256d, const int);` | +| [`_mm256_mask_i32gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i32gather_ps) | AVX2 | immintrin.h | `__m256 _mm256_mask_i32gather_ps(__m256, float const *, __m256i, __m256, const int);` | +| [`_mm256_mask_i64gather_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi32) | AVX2 | immintrin.h | `__m128i _mm256_mask_i64gather_epi32(__m128i, int const *, __m256i, __m128i, const int);` | +| [`_mm256_mask_i64gather_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_epi64) | AVX2 | immintrin.h | `__m256i _mm256_mask_i64gather_epi64(__m256i, __int64 const *, __m256i, __m256i, const int);` | +| [`_mm256_mask_i64gather_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_pd) | AVX2 | immintrin.h | `__m256d _mm256_mask_i64gather_pd(__m256d, double const *, __m256i, __m256d, const int);` | +| [`_mm256_mask_i64gather_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mask_i64gather_ps) | AVX2 | immintrin.h | `__m128 _mm256_mask_i64gather_ps(__m128, float const *, __m256i, __m128, const int);` | +| [`_mm256_maskload_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi32) | AVX2 | immintrin.h | `__m256i _mm256_maskload_epi32(int const *, __m256i);` | +| [`_mm256_maskload_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_epi64) | AVX2 | immintrin.h | `__m256i _mm256_maskload_epi64(__int64 const *, __m256i);` | +| [`_mm256_maskload_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_pd) | AVX | immintrin.h | `__m256d _mm256_maskload_pd(double const *, __m256i);` | +| [`_mm256_maskload_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskload_ps) | AVX | immintrin.h | `__m256 _mm256_maskload_ps(float const *, __m256i);` | +| [`_mm256_maskstore_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi32) | AVX2 | immintrin.h | `void _mm256_maskstore_epi32(int *, __m256i, __m256i);` | +| [`_mm256_maskstore_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_epi64) | AVX2 | immintrin.h | `void _mm256_maskstore_epi64(__int64 *, __m256i, __m256i);` | +| [`_mm256_maskstore_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_pd) | AVX | immintrin.h | `void _mm256_maskstore_pd(double *, __m256i, __m256d);` | +| [`_mm256_maskstore_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_maskstore_ps) | AVX | immintrin.h | `void _mm256_maskstore_ps(float *, __m256i, __m256);` | +| [`_mm256_max_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi16) | AVX2 | immintrin.h | `__m256i _mm256_max_epi16(__m256i, __m256i);` | +| [`_mm256_max_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi32) | AVX2 | immintrin.h | `__m256i _mm256_max_epi32(__m256i, __m256i);` | +| [`_mm256_max_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epi8) | AVX2 | immintrin.h | `__m256i _mm256_max_epi8(__m256i, __m256i);` | +| [`_mm256_max_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu16) | AVX2 | immintrin.h | `__m256i _mm256_max_epu16(__m256i, __m256i);` | +| [`_mm256_max_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu32) | AVX2 | immintrin.h | `__m256i _mm256_max_epu32(__m256i, __m256i);` | +| [`_mm256_max_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_epu8) | AVX2 | immintrin.h | `__m256i _mm256_max_epu8(__m256i, __m256i);` | +| [`_mm256_max_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_pd) | AVX | immintrin.h | `__m256d _mm256_max_pd(__m256d, __m256d);` | +| [`_mm256_max_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_max_ps) | AVX | immintrin.h | `__m256 _mm256_max_ps(__m256, __m256);` | +| [`_mm256_min_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi16) | AVX2 | immintrin.h | `__m256i _mm256_min_epi16(__m256i, __m256i);` | +| [`_mm256_min_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi32) | AVX2 | immintrin.h | `__m256i _mm256_min_epi32(__m256i, __m256i);` | +| [`_mm256_min_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epi8) | AVX2 | immintrin.h | `__m256i _mm256_min_epi8(__m256i, __m256i);` | +| [`_mm256_min_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu16) | AVX2 | immintrin.h | `__m256i _mm256_min_epu16(__m256i, __m256i);` | +| [`_mm256_min_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu32) | AVX2 | immintrin.h | `__m256i _mm256_min_epu32(__m256i, __m256i);` | +| [`_mm256_min_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_epu8) | AVX2 | immintrin.h | `__m256i _mm256_min_epu8(__m256i, __m256i);` | +| [`_mm256_min_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_pd) | AVX | immintrin.h | `__m256d _mm256_min_pd(__m256d, __m256d);` | +| [`_mm256_min_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_min_ps) | AVX | immintrin.h | `__m256 _mm256_min_ps(__m256, __m256);` | +| [`_mm256_movedup_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movedup_pd) | AVX | immintrin.h | `__m256d _mm256_movedup_pd(__m256d);` | +| [`_mm256_movehdup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movehdup_ps) | AVX | immintrin.h | `__m256 _mm256_movehdup_ps(__m256);` | +| [`_mm256_moveldup_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_moveldup_ps) | AVX | immintrin.h | `__m256 _mm256_moveldup_ps(__m256);` | +| [`_mm256_movemask_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_epi8) | AVX2 | immintrin.h | `int _mm256_movemask_epi8(__m256i);` | +| [`_mm256_movemask_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_pd) | AVX | immintrin.h | `int _mm256_movemask_pd(__m256d);` | +| [`_mm256_movemask_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_movemask_ps) | AVX | immintrin.h | `int _mm256_movemask_ps(__m256);` | +| [`_mm256_mpsadbw_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mpsadbw_epu8) | AVX2 | immintrin.h | `__m256i _mm256_mpsadbw_epu8(__m256i, __m256i, const int);` | +| `_mm256_msub_pd` | FMA4 | ammintrin.h | `__m256d _mm_msub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_msub_ps` | FMA4 | ammintrin.h | `__m256 _mm_msub_ps(__m256, __m256, __m256);` | +| `_mm256_msubadd_pd` | FMA4 | ammintrin.h | `__m256d _mm_msubadd_pd(__m256d, __m256d, __m256d);` | +| `_mm256_msubadd_ps` | FMA4 | ammintrin.h | `__m256 _mm_msubadd_ps(__m256, __m256, __m256);` | +| [`_mm256_mul_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mul_epi32(__m256i, __m256i);` | +| [`_mm256_mul_epu32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_epu32) | AVX2 | immintrin.h | `__m256i _mm256_mul_epu32(__m256i, __m256i);` | +| [`_mm256_mul_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_pd) | AVX | immintrin.h | `__m256d _mm256_mul_pd(__m256d, __m256d);` | +| [`_mm256_mul_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mul_ps) | AVX | immintrin.h | `__m256 _mm256_mul_ps(__m256, __m256);` | +| [`_mm256_mulhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mulhi_epi16(__m256i, __m256i);` | +| [`_mm256_mulhi_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhi_epu16) | AVX2 | immintrin.h | `__m256i _mm256_mulhi_epu16(__m256i, __m256i);` | +| [`_mm256_mulhrs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mulhrs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mulhrs_epi16(__m256i, __m256i);` | +| [`_mm256_mullo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_mullo_epi16(__m256i, __m256i);` | +| [`_mm256_mullo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_mullo_epi32) | AVX2 | immintrin.h | `__m256i _mm256_mullo_epi32(__m256i, __m256i);` | +| `_mm256_nmacc_pd` | FMA4 | ammintrin.h | `__m256d _mm_nmacc_pd(__m256d, __m256d, __m256d);` | +| `_mm256_nmacc_ps` | FMA4 | ammintrin.h | `__m256 _mm_nmacc_ps(__m256, __m256, __m256);` | +| `_mm256_nmsub_pd` | FMA4 | ammintrin.h | `__m256d _mm_nmsub_pd(__m256d, __m256d, __m256d);` | +| `_mm256_nmsub_ps` | FMA4 | ammintrin.h | `__m256 _mm_nmsub_ps(__m256, __m256, __m256);` | +| [`_mm256_or_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_pd) | AVX | immintrin.h | `__m256d _mm256_or_pd(__m256d, __m256d);` | +| [`_mm256_or_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_ps) | AVX | immintrin.h | `__m256 _mm256_or_ps(__m256, __m256);` | +| [`_mm256_or_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_or_si256) | AVX2 | immintrin.h | `__m256i _mm256_or_si256(__m256i, __m256i);` | +| [`_mm256_packs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_packs_epi16(__m256i, __m256i);` | +| [`_mm256_packs_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packs_epi32) | AVX2 | immintrin.h | `__m256i _mm256_packs_epi32(__m256i, __m256i);` | +| [`_mm256_packus_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi16) | AVX2 | immintrin.h | `__m256i _mm256_packus_epi16(__m256i, __m256i);` | +| [`_mm256_packus_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_packus_epi32) | AVX2 | immintrin.h | `__m256i _mm256_packus_epi32(__m256i, __m256i);` | +| [`_mm256_permute_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_pd) | AVX | immintrin.h | `__m256d _mm256_permute_pd(__m256d, int);` | +| [`_mm256_permute_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute_ps) | AVX | immintrin.h | `__m256 _mm256_permute_ps(__m256, int);` | +| `_mm256_permute2_pd` | XOP | ammintrin.h | `__m256d _mm256_permute2_pd(__m256d, __m256d, __m256i, int);` | +| `_mm256_permute2_ps` | XOP | ammintrin.h | `__m256 _mm256_permute2_ps(__m256, __m256, __m256i, int);` | +| [`_mm256_permute2f128_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_pd) | AVX | immintrin.h | `__m256d _mm256_permute2f128_pd(__m256d, __m256d, int);` | +| [`_mm256_permute2f128_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_ps) | AVX | immintrin.h | `__m256 _mm256_permute2f128_ps(__m256, __m256, int);` | +| [`_mm256_permute2f128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2f128_si256) | AVX | immintrin.h | `__m256i _mm256_permute2f128_si256(__m256i, __m256i, int);` | +| [`_mm256_permute2x128_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute2x128_si256) | AVX2 | immintrin.h | `__m256i _mm256_permute2x128_si256(__m256i, __m256i, const int);` | +| [`_mm256_permute4x64_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_epi64) | AVX2 | immintrin.h | `__m256i _mm256_permute4x64_epi64 (__m256i, const int);` | +| [`_mm256_permute4x64_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permute4x64_pd) | AVX2 | immintrin.h | `__m256d _mm256_permute4x64_pd(__m256d, const int);` | +| [`_mm256_permutevar_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_pd) | AVX | immintrin.h | `__m256d _mm256_permutevar_pd(__m256d, __m256i);` | +| [`_mm256_permutevar_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar_ps) | AVX | immintrin.h | `__m256 _mm256_permutevar_ps(__m256, __m256i);` | +| [`_mm256_permutevar8x32_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_epi32) | AVX2 | immintrin.h | `__m256i _mm256_permutevar8x32_epi32(__m256i, __m256i);` | +| [`_mm256_permutevar8x32_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_permutevar8x32_ps) | AVX2 | immintrin.h | `__m256 _mm256_permutevar8x32_ps (__m256, __m256i);` | +| [`_mm256_rcp_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rcp_ps) | AVX | immintrin.h | `__m256 _mm256_rcp_ps(__m256);` | +| [`_mm256_round_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_pd) | AVX | immintrin.h | `__m256d _mm256_round_pd(__m256d, int);` | +| [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | +| [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | +| [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | +| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | +| [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | +| [`_mm256_set_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_pd) | AVX | immintrin.h | `__m256d _mm256_set_pd(double, double, double, double);` | +| [`_mm256_set_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_ps) | AVX | immintrin.h | `__m256 _mm256_set_ps(float, float, float, float, float, float, float, float);` | +| [`_mm256_set1_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi16) | AVX | immintrin.h | `__m256i _mm256_set1_epi16(short);` | +| [`_mm256_set1_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi32) | AVX | immintrin.h | `__m256i _mm256_set1_epi32(int);` | +| [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX | immintrin.h | `__m256i _mm256_set1_epi8(char);` | +| [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX | immintrin.h | `__m256d _mm256_set1_pd(double);` | +| [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX | immintrin.h | `__m256 _mm256_set1_ps(float);` | +| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_setr_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi32) | AVX | immintrin.h | `__m256i _mm256_setr_epi32(int, int, int, int, int, int, int, int);` | +| [`_mm256_setr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi8) | AVX | immintrin.h | `(__m256i _mm256_setr_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | +| [`_mm256_setr_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_pd) | AVX | immintrin.h | `__m256d _mm256_setr_pd(double, double, double, double);` | +| [`_mm256_setr_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_ps) | AVX | immintrin.h | `__m256 _mm256_setr_ps(float, float, float, float, float, float, float, float);` | +| [`_mm256_setzero_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_pd) | AVX | immintrin.h | `__m256d _mm256_setzero_pd(void);` | +| [`_mm256_setzero_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_ps) | AVX | immintrin.h | `__m256 _mm256_setzero_ps(void);` | +| [`_mm256_setzero_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setzero_si256) | AVX | immintrin.h | `__m256i _mm256_setzero_si256(void);` | +| [`_mm256_shuffle_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi32) | AVX2 | immintrin.h | `__m256i _mm256_shuffle_epi32(__m256i, const int);` | +| [`_mm256_shuffle_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_epi8) | AVX2 | immintrin.h | `__m256i _mm256_shuffle_epi8(__m256i, __m256i);` | +| [`_mm256_shuffle_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_pd) | AVX | immintrin.h | `__m256d _mm256_shuffle_pd(__m256d, __m256d, const int);` | +| [`_mm256_shuffle_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shuffle_ps) | AVX | immintrin.h | `__m256 _mm256_shuffle_ps(__m256, __m256, const int);` | +| [`_mm256_shufflehi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflehi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_shufflehi_epi16(__m256i, const int);` | +| [`_mm256_shufflelo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_shufflelo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_shufflelo_epi16(__m256i, const int);` | +| [`_mm256_sign_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi16(__m256i, __m256i);` | +| [`_mm256_sign_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi32(__m256i, __m256i);` | +| [`_mm256_sign_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sign_epi8) | AVX2 | immintrin.h | `__m256i _mm256_sign_epi8(__m256i, __m256i);` | +| [`_mm256_sll_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi16(__m256i, __m128i);` | +| [`_mm256_sll_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi32(__m256i, __m128i);` | +| [`_mm256_sll_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sll_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sll_epi64(__m256i, __m128i);` | +| [`_mm256_slli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi16) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi16(__m256i, int);` | +| [`_mm256_slli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi32) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi32(__m256i, int);` | +| [`_mm256_slli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_epi64) | AVX2 | immintrin.h | `__m256i _mm256_slli_epi64(__m256i, int);` | +| [`_mm256_slli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_slli_si256) | AVX2 | immintrin.h | `__m256i _mm256_slli_si256(__m256i, int);` | +| [`_mm256_sllv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sllv_epi32(__m256i, __m256i);` | +| [`_mm256_sllv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sllv_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sllv_epi64(__m256i, __m256i);` | +| [`_mm256_sqrt_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_pd) | AVX | immintrin.h | `__m256d _mm256_sqrt_pd(__m256d);` | +| [`_mm256_sqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sqrt_ps) | AVX | immintrin.h | `__m256 _mm256_sqrt_ps(__m256);` | +| [`_mm256_sra_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sra_epi16(__m256i, __m128i);` | +| [`_mm256_sra_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sra_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sra_epi32(__m256i, __m128i);` | +| [`_mm256_srai_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srai_epi16(__m256i, int);` | +| [`_mm256_srai_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srai_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srai_epi32(__m256i, int);` | +| [`_mm256_srav_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srav_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srav_epi32(__m256i, __m256i);` | +| [`_mm256_srl_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi16(__m256i, __m128i);` | +| [`_mm256_srl_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi32(__m256i, __m128i);` | +| [`_mm256_srl_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srl_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srl_epi64(__m256i, __m128i);` | +| [`_mm256_srli_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi16) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi16(__m256i, int);` | +| [`_mm256_srli_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi32(__m256i, int);` | +| [`_mm256_srli_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srli_epi64(__m256i, int);` | +| [`_mm256_srli_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srli_si256) | AVX2 | immintrin.h | `__m256i _mm256_srli_si256(__m256i, int);` | +| [`_mm256_srlv_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi32) | AVX2 | immintrin.h | `__m256i _mm256_srlv_epi32(__m256i, __m256i);` | +| [`_mm256_srlv_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_srlv_epi64) | AVX2 | immintrin.h | `__m256i _mm256_srlv_epi64(__m256i, __m256i);` | +| [`_mm256_store_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_pd) | AVX | immintrin.h | `void _mm256_store_pd(double *, __m256d);` | +| [`_mm256_store_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_ps) | AVX | immintrin.h | `void _mm256_store_ps(float *, __m256);` | +| [`_mm256_store_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_store_si256) | AVX | immintrin.h | `void _mm256_store_si256(__m256i *, __m256i);` | +| [`_mm256_storeu_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_pd) | AVX | immintrin.h | `void _mm256_storeu_pd(double *, __m256d);` | +| [`_mm256_storeu_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_ps) | AVX | immintrin.h | `void _mm256_storeu_ps(float *, __m256);` | +| [`_mm256_storeu_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_storeu_si256) | AVX | immintrin.h | `void _mm256_storeu_si256(__m256i *, __m256i);` | +| [`_mm256_stream_load_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_load_si256) | AVX2 | immintrin.h | `__m256i _mm256_stream_load_si256(__m256i const *);` | +| [`_mm256_stream_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_pd) | AVX | immintrin.h | `void __mm256_stream_pd(double *, __m256d);` | +| [`_mm256_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_ps) | AVX | immintrin.h | `void _mm256_stream_ps(float *, __m256);` | +| [`_mm256_stream_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_stream_si256) | AVX | immintrin.h | `void __mm256_stream_si256(__m256i *, __m256i);` | +| [`_mm256_sub_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi16) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi16(__m256i, __m256i);` | +| [`_mm256_sub_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi32) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi32(__m256i, __m256i);` | +| [`_mm256_sub_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi64) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi64(__m256i, __m256i);` | +| [`_mm256_sub_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_epi8) | AVX2 | immintrin.h | `__m256i _mm256_sub_epi8(__m256i, __m256i);` | +| [`_mm256_sub_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_pd) | AVX | immintrin.h | `__m256d _mm256_sub_pd(__m256d, __m256d);` | +| [`_mm256_sub_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sub_ps) | AVX | immintrin.h | `__m256 _mm256_sub_ps(__m256, __m256);` | +| [`_mm256_subs_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi16) | AVX2 | immintrin.h | `__m256i _mm256_subs_epi16(__m256i, __m256i);` | +| [`_mm256_subs_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epi8) | AVX2 | immintrin.h | `__m256i _mm256_subs_epi8(__m256i, __m256i);` | +| [`_mm256_subs_epu16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu16) | AVX2 | immintrin.h | `__m256i _mm256_subs_epu16(__m256i, __m256i);` | +| [`_mm256_subs_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_subs_epu8) | AVX2 | immintrin.h | `__m256i _mm256_subs_epu8(__m256i, __m256i);` | +| [`_mm256_testc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_pd) | AVX | immintrin.h | `int _mm256_testc_pd(__m256d, __m256d);` | +| [`_mm256_testc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_ps) | AVX | immintrin.h | `int _mm256_testc_ps(__m256, __m256);` | +| [`_mm256_testc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testc_si256) | AVX | immintrin.h | `int _mm256_testc_si256(__m256i, __m256i);` | +| [`_mm256_testnzc_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_pd) | AVX | immintrin.h | `int _mm256_testnzc_pd(__m256d, __m256d);` | +| [`_mm256_testnzc_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_ps) | AVX | immintrin.h | `int _mm256_testnzc_ps(__m256, __m256);` | +| [`_mm256_testnzc_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testnzc_si256) | AVX | immintrin.h | `int _mm256_testnzc_si256(__m256i, __m256i);` | +| [`_mm256_testz_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_pd) | AVX | immintrin.h | `int _mm256_testz_pd(__m256d, __m256d);` | +| [`_mm256_testz_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_ps) | AVX | immintrin.h | `int _mm256_testz_ps(__m256, __m256);` | +| [`_mm256_testz_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_testz_si256) | AVX | immintrin.h | `int _mm256_testz_si256(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi16) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi16(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi32) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi32(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi64) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi64(__m256i, __m256i);` | +| [`_mm256_unpackhi_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_epi8) | AVX2 | immintrin.h | `__m256i _mm256_unpackhi_epi8(__m256i, __m256i);` | +| [`_mm256_unpackhi_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_pd) | AVX | immintrin.h | `__m256d _mm256_unpackhi_pd(__m256d, __m256d);` | +| [`_mm256_unpackhi_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpackhi_ps) | AVX | immintrin.h | `__m256 _mm256_unpackhi_ps(__m256, __m256);` | +| [`_mm256_unpacklo_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi16) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi16(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi32) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi32(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi64) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi64(__m256i, __m256i);` | +| [`_mm256_unpacklo_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_epi8) | AVX2 | immintrin.h | `__m256i _mm256_unpacklo_epi8(__m256i, __m256i);` | +| [`_mm256_unpacklo_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_pd) | AVX | immintrin.h | `__m256d _mm256_unpacklo_pd(__m256d, __m256d);` | +| [`_mm256_unpacklo_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_unpacklo_ps) | AVX | immintrin.h | `__m256 _mm256_unpacklo_ps(__m256, __m256);` | +| [`_mm256_xor_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_pd) | AVX | immintrin.h | `__m256d _mm256_xor_pd(__m256d, __m256d);` | +| [`_mm256_xor_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_ps) | AVX | immintrin.h | `__m256 _mm256_xor_ps(__m256, __m256);` | +| [`_mm256_xor_si256`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_xor_si256) | AVX2 | immintrin.h | `__m256i _mm256_xor_si256(__m256i, __m256i);` | +| [`_mm256_zeroall`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroall) | AVX | immintrin.h | `void _mm256_zeroall(void);` | +| [`_mm256_zeroupper`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_zeroupper) | AVX | immintrin.h | `void _mm256_zeroupper(void);` | | [`__movsb`](movsb.md) | | intrin.h | `void __movsb(unsigned char *, unsigned char const *, size_t);` | | [`__movsd`](movsd.md) | | intrin.h | `void __movsd(unsigned long *, unsigned long const *, size_t);` | | [`__movsw`](movsw.md) | | intrin.h | `void __movsw(unsigned short *, unsigned short const *, size_t);` | -| `_mulx_u32` | BMI \[2] | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | +| `_mulx_u32` | BMI | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | | [`__nop`](nop.md) | | intrin.h | `void __nop(void);` | | `__nvreg_restore_fence` | | intrin.h | `void __nvreg_restore_fence(void);` | | `__nvreg_save_fence` | | intrin.h | `void __nvreg_save_fence(void);` | @@ -1232,14 +1238,14 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__outdwordstring`](outdwordstring.md) | | intrin.h | `void __outdwordstring(unsigned short, unsigned long *, unsigned long);` | | [`__outword`](outword.md) | | intrin.h | `void __outword(unsigned short, unsigned short);` | | [`__outwordstring`](outwordstring.md) | | intrin.h | `void __outwordstring(unsigned short, unsigned short *, unsigned long);` | -| [`_pdep_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u32) | BMI \[2] | immintrin.h | `unsigned int _pdep_u32(unsigned int, unsigned int);` | -| [`_pext_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u32) | BMI \[2] | immintrin.h | `unsigned int _pext_u32(unsigned int, unsigned int);` | +| [`_pdep_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pdep_u32) | BMI | immintrin.h | `unsigned int _pdep_u32(unsigned int, unsigned int);` | +| [`_pext_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_pext_u32) | BMI | immintrin.h | `unsigned int _pext_u32(unsigned int, unsigned int);` | | [`__popcnt`](popcnt16-popcnt-popcnt64.md) | POPCNT | intrin.h | `unsigned int __popcnt(unsigned int);` | | [`__popcnt16`](popcnt16-popcnt-popcnt64.md) | POPCNT | intrin.h | `unsigned short __popcnt16(unsigned short);` | -| [`_rdrand16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand16_step) | RDRAND \[2] | immintrin.h | `int _rdrand16_step(unsigned short *);` | -| [`_rdrand32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand32_step) | RDRAND \[2] | immintrin.h | `int _rdrand32_step(unsigned int *);` | -| [`_rdseed16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed16_step) | RDSEED \[2] | immintrin.h | `int _rdseed16_step(unsigned short *);` | -| [`_rdseed32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed32_step) | RDSEED \[2] | immintrin.h | `int _rdseed32_step(unsigned int *);` | +| [`_rdrand16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand16_step) | RDRAND | immintrin.h | `int _rdrand16_step(unsigned short *);` | +| [`_rdrand32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdrand32_step) | RDRAND | immintrin.h | `int _rdrand32_step(unsigned int *);` | +| [`_rdseed16_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed16_step) | RDSEED | immintrin.h | `int _rdseed16_step(unsigned short *);` | +| [`_rdseed32_step`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_rdseed32_step) | RDSEED | immintrin.h | `int _rdseed32_step(unsigned int *);` | | [`__rdtsc`](rdtsc.md) | | intrin.h | `unsigned __int64 __rdtsc(void);` | | [`__rdtscp`](rdtscp.md) | RDTSCP | intrin.h | `unsigned __int64 __rdtscp(unsigned int*);` | | [`_ReadBarrier`](readbarrier.md) | | intrin.h | `void _ReadBarrier(void);` | @@ -1257,26 +1263,26 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__readpmc`](readpmc.md) | | intrin.h | `unsigned __int64 __readpmc(unsigned long);` | | [`_ReadWriteBarrier`](readwritebarrier.md) | | intrin.h | `void _ReadWriteBarrier(void);` | | [`_ReturnAddress`](returnaddress.md) | | intrin.h | `void * _ReturnAddress(void);` | -| `_rorx_u32` | BMI \[2] | immintrin.h | `unsigned int _rorx_u32(unsigned int, const unsigned int);` | +| `_rorx_u32` | BMI | immintrin.h | `unsigned int _rorx_u32(unsigned int, const unsigned int);` | | [`_rotl16`](rotl8-rotl16.md) | | intrin.h | `unsigned short _rotl16(unsigned short, unsigned char);` | | [`_rotl8`](rotl8-rotl16.md) | | intrin.h | `unsigned char _rotl8(unsigned char, unsigned char);` | | [`_rotr16`](rotr8-rotr16.md) | | intrin.h | `unsigned short _rotr16(unsigned short, unsigned char);` | | [`_rotr8`](rotr8-rotr16.md) | | intrin.h | `unsigned char _rotr8(unsigned char, unsigned char);` | | `_rsm` | | intrin.h | `void _rsm(void);` | -| `_sarx_i32` | BMI \[2] | immintrin.h | `int _sarx_i32(int, unsigned int);` | +| `_sarx_i32` | BMI | immintrin.h | `int _sarx_i32(int, unsigned int);` | | [`__segmentlimit`](segmentlimit.md) | | intrin.h | `unsigned long __segmentlimit(unsigned long);` | | `_sgdt` | | intrin.h | `void _sgdt(void*);` | -| `_shlx_u32` | BMI \[2] | immintrin.h | `unsigned int _shlx_u32(unsigned int, unsigned int);` | -| `_shrx_u32` | BMI \[2] | immintrin.h | `unsigned int _shrx_u32(unsigned int, unsigned int);` | +| `_shlx_u32` | BMI | immintrin.h | `unsigned int _shlx_u32(unsigned int, unsigned int);` | +| `_shrx_u32` | BMI | immintrin.h | `unsigned int _shrx_u32(unsigned int, unsigned int);` | | [`__sidt`](sidt.md) | | intrin.h | `void __sidt(void*);` | -| `__slwpcb` | LWP \[1] | ammintrin.h | `void *__slwpcb(void);` | +| `__slwpcb` | LWP | ammintrin.h | `void *__slwpcb(void);` | | `_stac` | SMAP | intrin.h | `void _stac(void);` | -| [`_storebe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i16&expand=5141) | MOVBE | immintrin.h | `void _storebe_i16(void *, short);` \[3] | -| [`_storebe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i32&expand=5142) | MOVBE | immintrin.h | `void _storebe_i32(void *, int);` \[3] | -| `_store_be_u16` | MOVBE | immintrin.h | `void _store_be_u16(void *, unsigned short);` \[3] | -| `_store_be_u32` | MOVBE | immintrin.h | `void _store_be_u32(void *, unsigned int);` \[3] | -| `_Store_HLERelease` | HLE \[2] | immintrin.h | `void _Store_HLERelease(long volatile *, long);` | -| `_StorePointer_HLERelease` | HLE \[2] | immintrin.h | `void _StorePointer_HLERelease(void * volatile *, void *);` | +| [`_storebe_i16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i16&expand=5141) | MOVBE | immintrin.h | `void _storebe_i16(void *, short);` \[Macro] | +| [`_storebe_i32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_storebe_i32&expand=5142) | MOVBE | immintrin.h | `void _storebe_i32(void *, int);` \[Macro] | +| `_store_be_u16` | MOVBE | immintrin.h | `void _store_be_u16(void *, unsigned short);` \[Macro] | +| `_store_be_u32` | MOVBE | immintrin.h | `void _store_be_u32(void *, unsigned int);` \[Macro] | +| `_Store_HLERelease` | HLE | immintrin.h | `void _Store_HLERelease(long volatile *, long);` | +| `_StorePointer_HLERelease` | HLE | immintrin.h | `void _StorePointer_HLERelease(void * volatile *, void *);` | | [`__stosb`](stosb.md) | | intrin.h | `void __stosb(unsigned char *, unsigned char, size_t);` | | [`__stosd`](stosd.md) | | intrin.h | `void __stosd(unsigned long *, unsigned long, size_t);` | | [`__stosw`](stosw.md) | | intrin.h | `void __stosw(unsigned short *, unsigned short, size_t);` | @@ -1290,9 +1296,9 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__svm_vmload`](svm-vmload.md) | | intrin.h | `void __svm_vmload(size_t);` | | [`__svm_vmrun`](svm-vmrun.md) | | intrin.h | `void __svm_vmrun(size_t);` | | [`__svm_vmsave`](svm-vmsave.md) | | intrin.h | `void __svm_vmsave(size_t);` | -| `_t1mskc_u32` | ABM \[1] | ammintrin.h | `unsigned int _t1mskc_u32(unsigned int);` | +| `_t1mskc_u32` | ABM | ammintrin.h | `unsigned int _t1mskc_u32(unsigned int);` | | [`_tzcnt_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_tzcnt_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _tzcnt_u32(unsigned int);` | -| `_tzmsk_u32` | ABM \[1] | ammintrin.h | `unsigned int _tzmsk_u32(unsigned int);` | +| `_tzmsk_u32` | ABM | ammintrin.h | `unsigned int _tzmsk_u32(unsigned int);` | | [`__ud2`](ud2.md) | | intrin.h | `void __ud2(void);` | | [`_udiv64`](udiv64.md) | | intrin.h | `unsigned int _udiv64(unsigned __int64, unsigned int, unsigned int *);` | | [`__ull_rshift`](ull-rshift.md) | | intrin.h | `unsigned __int64 [pascal/cdecl] __ull_rshift(unsigned __int64, int);` | @@ -1310,15 +1316,15 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__writefsdword`](writefsbyte-writefsdword-writefsqword-writefsword.md) | | intrin.h | `void __writefsdword(unsigned long, unsigned long);` | | [`__writefsword`](writefsbyte-writefsdword-writefsqword-writefsword.md) | | intrin.h | `void __writefsword(unsigned long, unsigned short);` | | [`__writemsr`](writemsr.md) | | intrin.h | `void __writemsr(unsigned long, unsigned __int64);` | -| [`_xabort`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xabort) | RTM \[2] | immintrin.h | `void _xabort(unsigned int);` | -| [`_xbegin`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xbegin) | RTM \[2] | immintrin.h | `unsigned _xbegin(void);` | -| [`_xend`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xend) | RTM \[2] | immintrin.h | `void _xend(void);` | -| [`_xgetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xgetbv) | XSAVE \[2] | immintrin.h | `unsigned __int64 _xgetbv(unsigned int);` | -| [`_xrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor) | XSAVE \[2] | immintrin.h | `void _xrstor(void const*, unsigned __int64);` | -| [`_xsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave) | XSAVE \[2] | immintrin.h | `void _xsave(void*, unsigned __int64);` | -| [`_xsaveopt`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt) | XSAVEOPT \[2] | immintrin.h | `void _xsaveopt(void*, unsigned __int64);` | -| [`_xsetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsetbv) | XSAVE \[2] | immintrin.h | `void _xsetbv(unsigned int, unsigned __int64);` | -| [`_xtest`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xtest) | XTEST \[2] | immintrin.h | `unsigned char _xtest(void);` | +| [`_xabort`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xabort) | RTM | immintrin.h | `void _xabort(unsigned int);` | +| [`_xbegin`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xbegin) | RTM | immintrin.h | `unsigned _xbegin(void);` | +| [`_xend`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xend) | RTM | immintrin.h | `void _xend(void);` | +| [`_xgetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xgetbv) | XSAVE | immintrin.h | `unsigned __int64 _xgetbv(unsigned int);` | +| [`_xrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xrstor) | XSAVE | immintrin.h | `void _xrstor(void const*, unsigned __int64);` | +| [`_xsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsave) | XSAVE | immintrin.h | `void _xsave(void*, unsigned __int64);` | +| [`_xsaveopt`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsaveopt) | XSAVEOPT | immintrin.h | `void _xsaveopt(void*, unsigned __int64);` | +| [`_xsetbv`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xsetbv) | XSAVE | immintrin.h | `void _xsetbv(unsigned int, unsigned __int64);` | +| [`_xtest`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_xtest) | XTEST | immintrin.h | `unsigned char _xtest(void);` | ## See also diff --git a/docs/linux/cmake-linux-configure.md b/docs/linux/cmake-linux-configure.md index e2badf94a2..c25b94031e 100644 --- a/docs/linux/cmake-linux-configure.md +++ b/docs/linux/cmake-linux-configure.md @@ -108,7 +108,7 @@ When you do a build: ## Choose a Linux target -When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt* file and specifies a Windows target of **x86-Debug**. To target a remote Linux system, you'll change the project settings based on your Linux compiler. For example, if you're using GCC on Linux and compiling with debug info, choose: **Linux-GCC-Debug** or **Linux-GCC-Release**. +When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt* file, and specifies a Windows target of **x86-Debug**. To target a remote Linux system, you'll change the project settings based on your Linux compiler. For example, if you're using GCC on Linux and compiling with debug info, choose: **Linux-GCC-Debug** or **Linux-GCC-Release**. If you specify a remote Linux target, your source is copied to the remote system. @@ -125,11 +125,11 @@ If you're targeting Windows Subsystem for Linux (WSL), you don't need to add a r To target WSL, select **Manage Configurations** in the configuration dropdown in the main toolbar: -![CMake Manage Configurations.](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down") +![CMake configurations drop-down with Manage Configurations selected](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down") The **CMakeSettings.json** window appears. -![Add configuration.](media/cmake-linux-configurations.png "Add a configuration to CMake settings") +![CMake settings dialog with the plus button highlighted which adds the selected configuration, which is Linux-GCC-debug.](media/cmake-linux-configurations.png ) Press **Add Configuration** (the green '+' button) and then choose **Linux-GCC-Debug** or **Linux-GCC-Release** if using GCC. Use the Clang variants if you're using the Clang/LLVM toolset. Press **Select** and then **Ctrl+S** to save the configuration. diff --git a/docs/linux/connect-to-your-remote-linux-computer.md b/docs/linux/connect-to-your-remote-linux-computer.md index 050ef04d0a..24030a4b84 100644 --- a/docs/linux/connect-to-your-remote-linux-computer.md +++ b/docs/linux/connect-to-your-remote-linux-computer.md @@ -1,9 +1,10 @@ --- -title: "Connect to your target Linux system in Visual Studio" -description: "How to connect to a remote Linux machine or Windows Subsystem for Linux from inside a Visual Studio C++ project." -ms.date: "01/8/2021" +title: "Connect to a Target Linux System by Using Visual Studio" +description: "Learn how to connect to a remote Linux machine or Windows Subsystem for Linux from inside a Visual Studio C++ project." +ms.topic: tutorial +ms.date: 03/21/2025 --- -# Connect to your target Linux system in Visual Studio +# Connect to your remote Linux system by using Visual Studio ::: moniker range="msvc-140" @@ -25,7 +26,8 @@ You can configure a Linux project to target a remote machine or the Windows Subs ::: moniker range=">=msvc-150" -When using a remote connection, Visual Studio builds C++ Linux projects on the remote machine. It doesn't matter if it's a physical machine, a VM in the cloud, or WSL. +When using a remote connection, Visual Studio builds C++ Linux projects on the remote machine. It doesn't matter if it's a physical machine, a virtual machine in the cloud, or WSL. + To build the project, Visual Studio copies the source code to your remote Linux computer. Then, the code gets compiled based on Visual Studio settings. ::: moniker-end @@ -39,7 +41,7 @@ To build the project, Visual Studio copies the source code to your remote Linux ::: moniker range=">=msvc-150" -## Set up the SSH server on the remote system +## Set up the SSH server on the remote machine If `ssh` isn't already set up and running on your Linux system, follow these steps to install it. The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7.6. However, the instructions should be the same for any distro using a moderately recent version of OpenSSH. @@ -50,7 +52,7 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste sudo service ssh start ``` -1. If you’d like the ssh server to start automatically when the system boots, enable it using systemctl: +1. If you'd like the ssh server to start automatically when the system boots, enable it using systemctl: ```bash sudo systemctl enable ssh @@ -58,17 +60,21 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste ## Set up the remote connection -1. In Visual Studio, choose **Tools > Options** on the menu bar to open the **Options** dialog. Then select **Cross Platform > Connection Manager** to open the Connection Manager dialog. +1. In Visual Studio on your local Windows system, choose **Tools > Options** on the menu bar to open the **Options** dialog. Then select **Cross Platform > Connection Manager** to open the Connection Manager dialog. If you haven't set up a connection in Visual Studio before, when you build your project for the first time, Visual Studio opens the Connection Manager dialog for you. 1. In the Connection Manager dialog, choose the **Add** button to add a new connection. - ![Screenshot showing the Connection Manager dialog.](media/settings_connectionmanager.png) + :::image type="complex" source="media/connect-to-your-remote-linux-computer/settings-connection-manager-updated.png" alt-text="Screenshot of the Visual Studio options pane."::: + In the options pane, CrossPlatform > C++ > Connection Manager is selected and the Add button is highlighted. + :::image-end::: - In either scenario, the **Connect to Remote System** window is displayed. + To edit an existing connection, choose **Edit**. In either scenario, the **Connect to Remote System** window is displayed. - ![Screenshot showing the Connect to Remote System window.](media/connect.png) + :::image type="complex" source="media/connect-to-your-remote-linux-computer/connect-updated.png" alt-text="Screenshot of the Visual Studio Connect to Remote System window."::: + In the Connect to Remote System window, there are fields for host name, port, user name, authentication type, and password. Port is set to 22. Authentication type is set to 'Password'. + :::image-end::: 1. Enter the following information: @@ -80,56 +86,66 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste | **Authentication type** | Password and Private Key are both supported | | **Password** | Password for the entered user name | | **Private key file** | Private key file created for ssh connection | - | **Passphrase** | Passphrase used with private key selected above | + | **Passphrase** | Passphrase used with private key selected previously | + + You can't select the **Connect** button until all the required fields are completed and the port is set to an integer between 1 and 65535. + + You can use either a password or a key file and passphrase for authentication. Key files are more secure than username/password. If you already have a key pair, it's possible to reuse it. - You can use either a password or a key file and passphrase for authentication. For many development scenarios, password authentication is sufficient, but key files are more secure. If you already have a key pair, it's possible to reuse it. Currently Visual Studio only supports RSA and DSA keys for remote connections. + Versions of Visual Studio before 17.10 support Elliptic Curve (EC), Rivert-Shamir-Adleman (RSA), and Digital signature algorithm (DSA) keys for remote connections. Because of security concerns, DSA keys are no longer supported in VS 17.10 and later. RSA keys were also not supported in VS 17.10 and VS 17.11 but some types are supported again in VS 17.12 and later. To create a key pair compatible with the connection manager, you can use the command: + `ssh-keygen -m pem -t ecdsa -f ` + + > [!NOTE] + > If using `ssh-keygen` to create the private key, you must specify the switch `-m pem`, or the key isn't accepted by Visual Studio. If your private key begins with `-----BEGIN OPENSSH PRIVATE KEY-----`, you must convert it with `ssh-keygen -p -f -m pem`. 1. Choose the **Connect** button to attempt a connection to the remote computer. If the connection succeeds, Visual Studio configures IntelliSense to use the remote headers. For more information, see [IntelliSense for headers on remote systems](configure-a-linux-project.md#remote_intellisense). - If the connection fails, the entry boxes that need to be changed are outlined in red. + If the connection fails, an info bar with error information appears and the fields that you might need to change are outlined in red. - ![Screenshot showing a Connection Manager Error.](media/settings_connectionmanagererror.png) + :::image type="content" source="media/connect-to-your-remote-linux-computer/settings-connection-manager-error-updated.png" alt-text="Screenshot of the Visual Studio Connect to Remote System window. The host name and port fields are outlined in red to indicate incorrect entries."::: If you use key files for authentication, make sure the target machine's SSH server is running and configured properly. + If you have trouble connecting to WSL on `localhost`, see [Fix WSL `localhost` connection problems](#fix-wsl-localhost-connection-problems). + ::: moniker-end ::: moniker range=">=msvc-160" ## Host key verification -In Visual Studio version 16.10 or later, you'll be asked to verify the server's host key fingerprint whenever Visual Studio connects to a remote system for the first time. You may be familiar with this process if you’ve used the OpenSSH command-line client or PuTTY before. The fingerprint identifies the server. Visual Studio uses the fingerprint to ensure it's connecting to the intended and trusted server. +In Visual Studio version 16.10 or later, you're asked to verify the server's host key fingerprint whenever Visual Studio connects to a remote system for the first time. You might be familiar with this process if you've used the OpenSSH command-line client or PuTTY before. The fingerprint identifies the server. Visual Studio uses the fingerprint to ensure it connects to the intended and trusted server. -The first time Visual Studio establishes a new remote connection, you'll be asked to accept or deny the host key fingerprint presented by the server. Or, anytime there are changes to a cached fingerprint. You can also verify a fingerprint on demand: select a connection in the Connection Manager and choose **Verify**. +The first time Visual Studio establishes a new remote connection, you're asked to accept or deny the host key fingerprint presented by the server. Or, anytime there are changes to a cached fingerprint. You can also verify a fingerprint on demand: select a connection in the Connection Manager and choose **Verify**. -If you upgrade to Visual Studio 16.10 or later from an older version, it treats any existing remote connections as new connections. You'll be prompted to accept the host key fingerprint first. Then, Visual Studio establishes a connection and caches the accepted fingerprint. +If you upgrade to Visual Studio 16.10 or later from an older version, it treats any existing remote connections as new connections. You're prompted to accept the host key fingerprint first. Then, Visual Studio establishes a connection and caches the accepted fingerprint. -You can also update remote connections from `ConnectionManager.exe` using the `update` argument. +You can also update remote connections from *`ConnectionManager.exe`* using the `update` argument. ## Supported SSH algorithms -Starting in Visual Studio version 16.9, support for older, insecure SSH algorithms used to encrypt data and exchange keys, has been removed. Only the following algorithms are supported. They're supported for both client-to-server and server-to-client SSH communication: +Starting in Visual Studio version 16.9, support for older, insecure SSH algorithms used to encrypt data and exchange keys is removed. Only the following algorithms are supported. They're supported for both client-to-server and server-to-client SSH communication: | Algorithm type | Supported algorithms | |--|--| -| Encryption | `aes128-cbc`
`aes128-cbc`
`aes192-cbc`
`aes192-ctr`
`aes256-cbc`
`aes256-ctr` | -| HMAC | `hmac-sha2-256`
`hmac-sha2-256` | +| Encryption | `aes128-cbc`
`aes128-ctr`
`aes192-cbc`
`aes192-ctr`
`aes256-cbc`
`aes256-ctr` | +| HMAC | `hmac-sha2-256`
`hmac-sha2-512` | | Key exchange | `diffie-hellman-group14-sha256`
`diffie-hellman-group16-sha512`
`diffie-hellman-group-exchange-sha256`
`ecdh-sha2-nistp256`
`ecdh-sha2-nistp384`
`ecdh-sha2-nistp521` | -| Host key | `ecdsa-sha2-nistp256`
`ecdsa-sha2-nistp384`
`ecdsa-sha2-nistp521`
`ssh-dss`
`ssh-rsa` | +| Host key | `ecdsa-sha2-nistp256`
`ecdsa-sha2-nistp384`
`ecdsa-sha2-nistp521`
`rsa-sha2-512`
`rsa-sha2-256` | ### Configure the SSH server First, a little background. You can't select the SSH algorithm to use from Visual Studio. Instead, the algorithm is determined during the initial handshake with the SSH server. Each side (client and server) provides a list of algorithms it supports, and then the first algorithm common to both is selected. The connection succeeds as long as there's at least one algorithm in common between Visual Studio and the server for encryption, HMAC, key exchange, and so on. -The Open SSH configuration file (*`sshd_config`*) doesn't configure which algorithm to use by default. The SSH server should use secure defaults when no algorithms are specified. Those defaults depend on the version and vendor of the SSH server. If Visual Studio doesn't support those defaults, you'll likely see an error like: "Could not connect to the remote system. No common client to server HMAC algorithm was found." The error may also appear if the SSH server is configured to use algorithms that Visual Studio doesn't support. +The Open SSH configuration file (*`sshd_config`*) doesn't configure which algorithm to use by default. The SSH server should use secure defaults when no algorithms are specified. Those defaults depend on the version and vendor of the SSH server. If Visual Studio doesn't support those defaults, you'll likely see an error like: *Could not connect to the remote system. No common client to server HMAC algorithm was found.* The error might also appear if the SSH server is configured to use algorithms that Visual Studio doesn't support. -The default SSH server on most modern Linux distributions should work with Visual Studio. However, you may be running an older SSH server that's configured to use older, insecure algorithms. The following example explains how to update to more secure versions. +The default SSH server on most modern Linux distributions should work with Visual Studio. However, you might be running an older SSH server that's configured to use older, insecure algorithms. The following example explains how to update to more secure versions. -In the following example, the SSH server uses the insecure `hmac-sha1` algorithm, which isn't supported by Visual Studio 16.9. If the SSH server uses OpenSSH, you can edit the `/etc/ssh/sshd_config` file as shown below to enable more secure algorithms. For other SSH servers, refer to the server's documentation for how to configure them. +In this example, the SSH server uses the insecure `hmac-sha1` algorithm, which Visual Studio 16.9 doesn't support. If the SSH server uses OpenSSH, you can edit the `/etc/ssh/sshd_config` file to enable more secure algorithms. For other SSH servers, refer to the server's documentation for how to configure them. -First, verify that the set of algorithms your server is using includes algorithms supported by Visual Studio. Run the following command on the remote machine to list the algorithms supported by the server: +First, verify that the set of algorithms your server is using includes algorithms supported by Visual Studio. Run the following command on the remote machine to list the algorithms supported by the server: ```bash ssh -Q cipher; ssh -Q mac; ssh -Q kex; ssh -Q key @@ -147,7 +163,7 @@ ecdsa-sha2-nistp521-cert-v01@openssh.com sk-ecdsa-sha2-nistp256-cert-v01@openssh.com ``` -The output lists all the encryption, HMAC, key exchange, and host key algorithms supported by your SSH server. If the list doesn't include algorithms supported by Visual Studio, then you'll need to upgrade your SSH server before proceeding. +The output lists all the encryption, HMAC, key exchange, and host key algorithms supported by your SSH server. If the list doesn't include algorithms supported by Visual Studio, then upgrade your SSH server before proceeding. You can enable algorithms supported by Visual Studio by editing `/etc/ssh/sshd_config` on the remote machine. The following examples show how to add various types of algorithms to that configuration file. @@ -155,7 +171,7 @@ These examples can be added anywhere in `/etc/ssh/sshd_config`. Ensure that they After editing the file, restart the SSH server (`sudo service ssh restart` on Ubuntu) and attempt to connect again from Visual Studio. -#### Cipher example +#### Cipher example Add: `Ciphers ` For example: `Ciphers aes128-cbc,aes256-cbc` @@ -173,37 +189,39 @@ For example: `KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384` #### Host key example Add: `HostKeyAlgorithms ` -For example: `HostKeyAlgorithms ssh-dss,ssh-rsa` +For example: `HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384` ## Logging for remote connections - You can enable logging to help troubleshoot connection problems. On the menu bar, select **Tools > Options**. In the **Options** dialog, select **Cross Platform > Logging**: +You can enable logging to help troubleshoot connection problems. On the menu bar, select **Tools > Options**. In the **Options** dialog, select **Cross Platform > Logging**: - ![Screenshot showing Remote Logging.](media/remote-logging-vs2019.png) +:::image type="complex" source="media/remote-logging-vs2019.png" alt-text="Screenshot of the Visual Studio options screen."::: +The options are open to Cross Platform > Connection Manager > Logging. Enable logging is checked, log to a file is checked, the logfile directory is set the documents folder, and log to the 'Cross Platform Logging' pane in the output window is checked. +:::image-end::: - Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all output from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio. +Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all output from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio. - You can configure the output to go to a file or to the **Cross Platform Logging** pane in the Output window. For MSBuild-based Linux projects, MSBuild commands sent to the remote machine aren't routed to the **Output Window** because they're emitted out-of-process. Instead, they're logged to a file, with a prefix of "msbuild_". +You can configure the output to go to a file or to the **Cross Platform Logging** pane in the Output window. For MSBuild-based Linux projects, MSBuild commands sent to the remote machine aren't routed to the **Output Window** because they're emitted out-of-process. Instead, they're logged to a file, with a prefix of `msbuild_`. ## Command-line utility for the Connection Manager -**Visual Studio 2019 version 16.5 or later**: `ConnectionManager.exe` is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see [ConnectionManager reference](connectionmanager-reference.md). +**Visual Studio 2019 version 16.5 or later**: *`ConnectionManager.exe`* is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the `ConnectionManager` command, see [ConnectionManager reference](connectionmanager-reference.md). ::: moniker-end ::: moniker range=">=msvc-150" -## TCP Port Forwarding +## TCP port forwarding -The `rsync` command is used by both MSBuild-based Linux projects and CMake projects to [copy headers from your remote system to Windows for use by IntelliSense](configure-a-linux-project.md#remote_intellisense). When you can't enable TCP port forwarding, disable the automatic download of remote headers. To disable it, use **Tools > Options > Cross Platform > Connection Manager > Remote Headers IntelliSense Manager**. If the remote system doesn't have TCP port forwarding enabled, you'll see this error when the download of remote headers for IntelliSense begins: +The `rsync` command is used by both MSBuild-based Linux projects and CMake projects to [copy headers from your remote system to Windows for use by IntelliSense](configure-a-linux-project.md#remote_intellisense). When you can't enable TCP port forwarding, disable the automatic download of remote headers. To disable it, use **Tools > Options > Cross Platform > Connection Manager > Remote Headers IntelliSense Manager**. If the remote system doesn't have TCP port forwarding enabled, this error appears when the download of remote headers for IntelliSense begins: -![Screenshot showing a Headers Error.](media/port-forwarding-headers-error.png) +:::image type="content" source="media/port-forwarding-headers-error.png" alt-text="Screenshot of a Visual Studio error message that the SSH channel couldn't be opened. The path to a log file is provided."::: +`rsync` is also used by Visual Studio's CMake support to copy source files to the remote system. If you can't enable TCP port forwarding, you can use `sftp` as your remote copy sources method. `sftp` is often slower than `rsync`, but doesn't have a dependency on TCP port forwarding. You can manage your remote copy sources method with the `remoteCopySourcesMethod` property in the [CMake Settings Editor](../build/cmakesettings-reference.md#settings-for-cmake-linux). If TCP port forwarding is disabled on your remote system, an error appears in the CMake output window the first time it invokes `rsync`. - -`rsync` is also used by Visual Studio's CMake support to copy source files to the remote system. If you can't enable TCP port forwarding, you can use `sftp` as your remote copy sources method. `sftp` is often slower than `rsync`, but doesn't have a dependency on TCP port forwarding. You can manage your remote copy sources method with the `remoteCopySourcesMethod` property in the [CMake Settings Editor](../build/cmakesettings-reference.md#settings-for-cmake-linux). If TCP port forwarding is disabled on your remote system, you'll see an error in the CMake output window the first time it invokes `rsync`. - -![Screenshot showing an Rsync Error.](media/port-forwarding-copy-error.png) +:::image type="complex" source="media/port-forwarding-copy-error.png" alt-text="Screenshot of the Visual Studio output window displaying a Rsync Error message."::: +The output window includes these messages: Verify that TCP forwarding is enabled on the server, rsync: did not see server greeting, rsync error: error starting client-server protocol (code 5) at main.c(1675) [sender=3.1.3], An SSH channel couldn't be opened. +:::image-end::: `gdbserver` can be used for debugging on embedded devices. If you can't enable TCP port forwarding, then you must use `gdb` for all remote debugging scenarios. `gdb` is used by default when debugging projects on a remote system. @@ -215,7 +233,7 @@ Visual Studio's Linux support has a dependency on TCP port forwarding. Both `rsy ::: moniker range="msvc-150" -In Visual Studio 2017, you use the same steps to connect to WSL as you use for a remote Linux machine. Use `localhost` for the **Host Name**. +In Visual Studio 2017, you use the same steps to connect to Windows Subsystem for Linux (WSL) as you use for a remote Linux machine. Use `localhost` for the **Host Name**. ::: moniker-end @@ -229,15 +247,34 @@ To configure your WSL installation to work with Visual Studio, you need the foll sudo apt install g++ gdb make ninja-build rsync zip ``` +### Fix WSL `localhost` connection problems + +When connecting to WSL on `localhost`, you might run into a conflict with the Windows `ssh` client on port 22. In WSL, change the port that `ssh` expects requests from to 23 in `/etc/ssh/sshd_config`: + +```bash +Port 23 +``` + +If you're connecting using a password, ensure that the following is set in `/etc/ssh/sshd_config`: + +```bash +# To disable tunneled clear text passwords, change to no here! +PasswordAuthentication yes +``` + +After making these changes, restart the SSH server (`sudo service ssh restart` on Ubuntu). + +Then retry your connection to `localhost` using port 23. + For more information, see [Download, install, and set up the Linux workload](download-install-and-setup-the-linux-development-workload.md). To configure an MSBuild project for WSL, see [Configure a Linux project](configure-a-linux-project.md). To configure a CMake project for WSL, see [Configure a Linux CMake project](cmake-linux-project.md). To follow step-by-step instructions for creating a simple console application with WSL, check out this introductory blog post on [C++ with Visual Studio 2019 and the Windows Subsystem for Linux (WSL)](https://devblogs.microsoft.com/cppblog/c-with-visual-studio-2019-and-windows-subsystem-for-linux-wsl/). ::: moniker-end -## See Also +## See also -[Configure a Linux project](configure-a-linux-project.md)\ -[Configure a Linux CMake project](cmake-linux-project.md)\ -[Deploy, run, and debug your Linux project](deploy-run-and-debug-your-linux-project.md)\ -[Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md) +- [Configure a Linux MSBuild C++ project in Visual Studio](configure-a-linux-project.md) +- [Create a CMake Linux project in Visual Studio](cmake-linux-project.md) +- [Deploy, run, and debug your Linux MSBuild project](deploy-run-and-debug-your-linux-project.md) +- [Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md) \ No newline at end of file diff --git a/docs/linux/connectionmanager-reference.md b/docs/linux/connectionmanager-reference.md index ac182b8990..14b4e8c152 100644 --- a/docs/linux/connectionmanager-reference.md +++ b/docs/linux/connectionmanager-reference.md @@ -1,7 +1,7 @@ --- title: "ConnectionManager reference" -description: "How to manage your remote SSH connections from a command-line tool." -ms.date: "10/7/2020" +description: "How to manage your remote SSH connections from the command-line tool ConnectionManager.exe." +ms.date: 03/14/2022 f1_keywords: ["ConnectionManager"] helpviewer_keywords: ["ConnectionManager program"] --- @@ -9,7 +9,7 @@ helpviewer_keywords: ["ConnectionManager program"] ::: moniker range="<=msvc-150" -ConnectionManager.exe is available in Visual Studio 2019 version 16.5 and later. +`ConnectionManager.exe` is available in Visual Studio 2019 version 16.5 and later. ::: moniker-end @@ -17,9 +17,9 @@ ConnectionManager.exe is available in Visual Studio 2019 version 16.5 and later. ConnectionManager.exe is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, use it to set up Visual Studio for continuous integration. You can use it in a Developer Command Prompt window. For more information about the Developer Command Prompt, see [Use the Microsoft C++ toolset from the command line](../build/building-on-the-command-line.md). -ConnectionManager.exe is available in Visual Studio 2019 version 16.5 and later. It's part of the **Linux development with C++** workload in the Visual Studio Installer. It's also installed automatically when you choose the **Connection Manager** component in the installer. It's installed in *%VCIDEInstallDir%\\Linux\\bin\\ConnectionManagerExe\\ConnectionManager.exe*. +`ConnectionManager.exe` is available in Visual Studio 2019 version 16.5 and later. It's part of the **Linux development with C++** workload in the Visual Studio Installer. It's also installed automatically when you choose the **Connection Manager** component in the installer. It's installed in `%VCIDEInstallDir%\Linux\bin\ConnectionManagerExe\ConnectionManager.exe`. -The functionality of ConnectionManager.exe is also available in Visual Studio. To manage remote development connections in the IDE, on the menu bar, choose **Tools** > **Options** to open the Options dialog. In the Options dialog, select **Cross Platform** > **Connection Manager**. +The functionality of `ConnectionManager.exe` is also available in Visual Studio. To manage remote development connections in the IDE, on the menu bar, choose **Tools** > **Options** to open the Options dialog. In the Options dialog, select **Cross Platform** > **Connection Manager**. ## Syntax @@ -29,84 +29,90 @@ The functionality of ConnectionManager.exe is also available in Visual Studio. T - **`add`** *user\@host* \[**`--port`** *port*] \[**`--password`** *password*] \[**`--privatekey`** *privatekey_file*] - Authenticates and adds a new connection. By default, it uses port 22 and password authentication. (You'll be prompted to enter a password.) Use both **-`-password`** and **`--privatekey`** to specify a password for a private key. + Authenticates and adds a new connection. By default, it uses port 22 and password authentication. (You are prompted to enter a password.) -- **`remove`** \[*connection_id* \| *user\@host* \[**`--port`** *port*]] + You can use either a password or a key file and passphrase for authentication. Key files are more secure than username/password. If you already have a key pair, it's possible to reuse it. Use both **-`-password`** and **`--privatekey`** to specify a passphrase for a private key file. - Removes a connection. If no arguments are specified, you're prompted to specify which connection to remove. - -- **`modify`** \[*default* \| *connection_id* \| *user\@host* \[**`--port`** *port*]] \[**`--property`** *key=value*] + Versions of Visual Studio before 17.10 support Elliptic Curve (EC), Rivert-Shamir-Adleman (RSA), and Digital signature algorithm (DSA) keys for remote connections. Because of security concerns, RSA and DSA keys are no longer supported in VS 17.10 and later. Only EC keys are currently supported. - Defines or modifies a property on a connection.\ - If *value* is empty, then the property *key* is deleted.\ - If authentication fails, no changes will be made.\ - If no connection is specified (what is meant by *default*, above), the user's default remote connection is used. - -- **`remove-all`** + To create a key pair compatible with the connection manager, use the command `ssh-keygen -m pem -t ecdsa -f `. If you use `ssh-keygen` to create the private key, you must specify the switch `-m pem`, or the key won't be accepted by Visual Studio. If your private key begins with `-----BEGIN OPENSSH PRIVATE KEY-----`, you must convert it with `ssh-keygen -p -f -m pem`. - Removes all stored connections. - - **`clean`** Deletes header cache for connections that no longer exist. +- **`help`** + + Displays a help screen. + - **`list`** \[**`--properties`**] - Displays information, IDs, and properties of all stored connections. + Displays information, IDs, and properties of all stored connections.
For examples, see [Commonly used properties](#commonly-used-properties). -- **`help`** +- **`modify`** \[*default* \| *connection_id* \| *user\@host* \[**`--port`** *port*]] \[**`--property`** *key=value*] - Displays a help screen. + Defines or modifies a property on a connection.\ + If *value* is empty, then the property *key* is deleted.\ + If authentication fails, no changes will be made.\ + If no connection is specified, the user's default remote connection is used. -- **`version`** +- **`remove`** \[*connection_id* \| *user\@host* \[**`--port`** *port*]] + + Removes a connection. If no arguments are specified, you're prompted to specify which connection to remove. + +- **`remove-all`** + + Removes all stored connections. - Displays version information. - - **`update`** \[*default* \| *all* \| *connection_id* \| *user\@host* \[**`--port`** *port*]] \[**`--previous`**] [**`--fingerprint`**] Added in Visual Studio 16.10. Updates the host key fingerprint of the specified connection(s). +- **`version`** + + Displays version information. + ### Options -- **`-q`**, **`--quiet`** +- **`--file`** *filename* - Prevents output to `stdout` or `stderr`. + Read connection information from the provided *filename*. -- **`--no-prompt`** +- **`--fingerprint`** - Fail instead of prompt, when appropriate. + The host key fingerprint presented by the server. Use this option with **`list`** to view a connection's fingerprint. -- **`--no-verify`** +- **`-i`** - Add or modify a connection without authentication. + Same as **`--privatekey`**. -- **`--file`** *filename* +- **`-n`**, **`--dry-run`** - Read connection information from the provided *filename*. + Does a dry run of the command. + +- **`--no-prompt`** + + Fail instead of prompt, when appropriate. - **`--no-telemetry`** Disable sending usage data back to Microsoft. Usage data is collected and sent back to Microsoft unless the **`--no-telemetry`** flag is passed. -- **`-n`**, **`--dry-run`** +- **`--no-verify`** - Does a dry run of the command. + Add or modify a connection without authentication. - **`--p`** Same as **`--password`**. - -- **`-i`** - - Same as **`--privatekey`**. - **`--previous`** Indicates that the connection(s) will be read from the previous version of connection manager, updated, and written to the new version. -- **`--fingerprint`** +- **`-q`**, **`--quiet`** - The host key fingerprint presented by the server. Use this option with **`list`** to view a connection's fingerprint. + Prevents output to `stdout` or `stderr`. ## Examples @@ -122,11 +128,21 @@ This command removes the connection that has ID 1975957870 from the list of conn ConnectionManager.exe remove 1975957870 ``` -This command overrides the choice of shell for the connection with connection ID 21212121. Supported shells are: **`sh, csh, bash, tcsh, ksh, zsh, dash`**. If the shell found on the Linux system isn't supported, then we fall back to explicitly use **`sh`** for all commands. - -```cmd -ConnectionManager.exe modify 21212121 --property shell=csh -``` +### Commonly used properties + +| Property | Description | +|--|--| +| authentication type | The type of authentication used for the connection such as: `"password"`, `"privatekey"`.
To create a connection with the authentication type set to `"privatekey"`: `ConnectionManager.exe add user@127.0.0.1 --privatekey "%USERPROFILE%\.ssh\id_rsa"`| +| `default` | A boolean indicating whether this is the default connection. The default connection is used when there's more than one connection available and the one to use isn't specified.
To set the specified connection to be the default connection: `ConnectionManager.exe modify -21212121 --property default=true` | +| `host` | The name or IP address of the remote computer.
To change the host for the specified connection to another machine, in this case, local host: `ConnectionManager.exe modify -21212121 --property host=127.0.0.1` | +| `isWsl` | Returns true if the remote session is running Windows Subsystem for Linux. | +| `password` | The password for the connection. Change the password for the specified connection with: `ConnectionManager.exe modify -21212121 --property password="xyz"`| +| `platform` | The platform of the remote computer such as `"ARM"`, `"ARM64"`, `"PPC"`, `"PPC64"`, `"x64"`, `"x86"`.| +| `port` | The port used for the connection.
Change the port for the specified connection: `ConnectionManager.exe modify -21212121 --property port=22`| +| `shell` | The preferred shell to use on the remote system. Supported shells are `sh, csh, bash, tcsh, ksh, zsh, dash`
To set the preferred shell to be zsh for the remote machine on the specified connection: `ConnectionManager.exe modify -21212121 --property shell=zsh`
If the shell found on the Linux system isn't supported, then **`sh`** is used for all commands. | +| `systemID` | The remote system type, such as `"OSX"`, `"Ubuntu"`. | +| `timeout` | The connection timeout in milliseconds. Change the timeout for the specified connection with: `ConnectionManager.exe modify -21212121 --property timeout=100` | +| `username` | The name of the user logged into the remote computer.
To add a connection for a user named `"user"` on localhost: `ConnectionManager.exe add user@127.0.0.1`| ## See also diff --git a/docs/linux/create-a-new-linux-project.md b/docs/linux/create-a-new-linux-project.md index d2d98e79f4..7002e23eef 100644 --- a/docs/linux/create-a-new-linux-project.md +++ b/docs/linux/create-a-new-linux-project.md @@ -2,7 +2,6 @@ title: "Create a Linux MSBuild C++ project in Visual Studio" ms.date: "10/15/2020" description: "Create a new MSBuild-based Linux project in Visual Studio." -ms.assetid: 5d7c1d67-bc31-4f96-8622-2b4cf91372fd --- # Create a Linux MSBuild C++ project in Visual Studio @@ -25,7 +24,7 @@ To create a new Linux project in Visual Studio 2017, follow these steps: 1. Select **File > New Project** in Visual Studio, or press **Ctrl + Shift + N**. 1. Select the **Visual C++ > Cross Platform > Linux** node, and then select the project type to create. Enter a **Name** and **Location**, and choose **OK**. - ![Screenshot showing the New Project dialog box with Visual C plus plus > Cross Platform > Linux selected, all of the project types called out, and the Name and Location text boxes also called out.](media/newproject.png) +![The New Project dialog box with Visual C plus plus > Cross Platform > Linux selected and all project types and Name and Location text boxes called out.](media/newproject.png) | Project Type | Description | | ------------ | --- | @@ -52,7 +51,7 @@ To create a new Linux project in Visual Studio, follow these steps: 1. In the **Search for templates** textbox, enter **Linux** to list the available templates for Linux projects. 1. Select the project type to create, for example **Console Application**, and then choose **Next**. Enter a **Name** and **Location**, and choose **Create**. - ![Screenshot of the new project dialog box with the language drop-down set to C++ and the platform drop-down set to Linux.](media/newproject-vs2019.png) + ![Screenshot of the new project dialog box with the language drop-down set to C plus plus and the platform drop-down set to Linux.](media/newproject-vs2019.png) | Project Type | Description | | ------------ | --- | diff --git a/docs/linux/deploy-run-and-debug-your-linux-project.md b/docs/linux/deploy-run-and-debug-your-linux-project.md index e7911b3e5b..e52bfcd132 100644 --- a/docs/linux/deploy-run-and-debug-your-linux-project.md +++ b/docs/linux/deploy-run-and-debug-your-linux-project.md @@ -1,8 +1,7 @@ --- title: "Deploy, run, and debug your Linux MSBuild C++ project in Visual Studio" description: "Describes how to compile, execute, and debug code on the remote target from inside a MSBuild-based Linux C++ project in Visual Studio." -ms.date: "08/08/2020" -ms.assetid: f7084cdb-17b1-4960-b522-f84981bea879 +ms.date: 12/5/2024 ms.custom: intro-deployment --- # Deploy, run, and debug your Linux MSBuild project @@ -34,72 +33,67 @@ There are several ways to interact with and debug your Linux project. GDB is used to debug applications running on Linux. When debugging on a remote system (not WSL) GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: ![Screenshot of the Visual Studio Linux Console App Property Pages dialog box with Configuration Properties > Debugging selected and Debugging Mode highlighted with G D B selected and highlighted from the dropdown list.](media/vs2019-debugger-settings.png) + + ::: moniker-end - ::: moniker-end + ::: moniker range="msvc-150" - ::: moniker range="msvc-150" - - GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: + GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: ![Screenshot of the Visual Studio 2017 Linux Console App Property Pages dialog box with Configuration Properties > Debugging selected and Debugging Mode highlighted with G D B selected and highlighted from the dropdown list.](media/vs2017-debugger-settings.png) + + ::: moniker-end - ::: moniker-end - - - In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system. + - In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system. To use this, you must provide a local Windows path to GDB under **Debugger Path** in **Visual Studio 2022 version 17.6** and later, or under **GDB Path** in **Visual Studio 2019 version 16.11** and earlier. For more information about where to provide the path to GDB for CMake projects, see [Additional options allowed with the gdbserver configuration (16.7 or later)](../build/configure-cmake-debugging-sessions.md#additional-options-allowed-with-the-gdbserver-configuration-167-or-later). - In **gdb** mode, the Visual Studio debugger drives GDB on the remote system. This is a better option if the local version of GDB isn't compatible with the version installed on the target computer. This is the only mode that the Linux Console window supports. - > [!NOTE] - > If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target. + > [!NOTE] + > If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target. 1. Select the remote target using the standard **Debug** toolbar in Visual Studio. - When the remote target is available, you'll see it listed by either name or IP address. - - ![Screenshot showing a Remote target.](media/remote_target.png) - - If you haven't connected to the remote target yet, you'll see an instruction to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target. + When the remote target is available, you see it listed by name or IP address: - ![Screenshot showing the Remote Architecture.](media/architecture.png) + ![Screenshot showing a Remote target IP address.](media/remote_target.png) + + If you haven't connected to the remote target yet, you see instructions to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target: -1. Set a breakpoint by clicking in the left gutter of some code that you know will execute. - - A red dot appears on the line of code where you set the breakpoint. + ![Screenshot showing the Remote Architecture, which is x64.](media/architecture.png) + +1. Set a breakpoint by clicking in the left gutter of some code that you know will execute. A red dot appears on the line of code where you set the breakpoint. 1. Press **F5** (or **Debug > Start Debugging**) to start debugging. - When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors will appear in the **Error List** window. + When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors appear in the **Error List** window. - If there are no errors, the app will start and the debugger will pause at the breakpoint. + If there are no errors, the app starts and the debugger pauses at the breakpoint: ![Screenshot showing the app has hit a breakpoint.](media/hit_breakpoint.png) - - Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**. + + Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**. 1. If you want to use the Linux Console to interact with your app, select **Debug > Linux Console**. ![Screenshot showing the Linux Console menu item.](media/consolemenu.png) - - This console will display any console output from the target computer and take input and send it to the target computer. + + This console displays console output from the target computer and takes input and sends it to the target computer. ![Screenshot showing the Linux Console window.](media/consolewindow.png) - + ## Configure other debugging options (MSBuild projects) - Command-line arguments can be passed to the executable using the **Program Arguments** item in the project's **Debugging** property page. - You can export the `DISPLAY` environment variable by using the **Pre-Launch Command** in the project's **Debugging** property pages. For example: `export DISPLAY=:0.0` ![Screenshot showing the Program Arguments property in the Property Pages dialog.](media/settings_programarguments.png) - -- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry as shown above: - - `handle SIGILL nostop noprint` - -- You can specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later. + +- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry shown above: `handle SIGILL nostop noprint`. +- Specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later. ## Debug with Attach to Process -The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require additional control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here is a simple example: +The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require more control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here's a simple example: ```xml @@ -116,7 +110,7 @@ ExePath="C:\temp\ConsoleApplication17\ConsoleApplication17\bin\x64\Debug\Console ``` -The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for additional .so libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/master/src/MICore/LaunchOptions.xsd) on GitHub. +The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for more `.so` libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/main/src/MICore/LaunchOptions.xsd) on GitHub. ::: moniker range=">=msvc-160" @@ -124,22 +118,23 @@ The **AttachOptionsForConnection** has most of the attributes you might need. Th You can separate your remote build machine from your remote debug machine for both MSBuild-based Linux projects and CMake projects that target a remote Linux machine. For example, you can now cross-compile on x64 and deploy to an ARM device when targeting IoT scenarios. -By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**. +By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**: + +![Screenshot showing the Linux remote debug machine property in the Property Pages dialog which shows the username, authentication type, and port.](media/linux-remote-debug-machine.png) -![Screenshot showing the Linux remote debug machine property in the Property Pages dialog.](media/linux-remote-debug-machine.png) +The drop-down menu for **Remote Debug Machine** is populated with all established remote connections. -The drop-down menu for **Remote Debug Machine** is populated with all established remote connections. To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**). +To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**). -By default, only the files necessary for the process to debug will be deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files will be deployed to the remote debug machine. When you click on a source file, you'll see a preview of its File Properties directly below the Solution Explorer. +By default, only the files necessary for the process to debug are deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files are deployed to the remote debug machine. When you click on a source file, you see a preview of its File Properties directly below the Solution Explorer: -![Screenshot showing the Linux deployable files specified in the Properties window.](media/linux-deployable-content.png) +![Screenshot showing the properties of the file main.cpp with the property content = False highlighted.](media/linux-deployable-content.png) The **Content** property specifies whether the file will be deployed to the remote debug machine. You can disable deployment entirely by navigating to **Property Pages** > **Configuration Manager** and unchecking **Deploy** for the desired configuration. In some cases, you may require more control over your project's deployment. For example, some files that you want to deploy might be outside of your solution or you want to customize your remote deploy directory per file or directory. In these cases, append the following code block(s) to your .vcxproj file and replace "example.cpp" with the actual file names: ```xml - @@ -157,11 +152,11 @@ In some cases, you may require more control over your project's deployment. For ### CMake projects -For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of "remoteMachineName" is synchronized with the "remoteMachineName" property in CMakeSettings.json, which corresponds to your remote build machine. These properties no longer need to match, and the value of "remoteMachineName" in launch.vs.json will dictate which remote machine is used for deploy and debug. +For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of `"remoteMachineName"` is synchronized with the `"remoteMachineName"` property in `CMakeSettings.json`, which corresponds to your remote build machine. These properties no longer need to match, and the value of `"remoteMachineName"` in `launch.vs.json` dictate which remote machine is used for deploy and debug. -![The CMake remote debug machine specified in the launch.vs.json file.](media/cmake-remote-debug-machine.png) +![The CMake remote debug machine specified in the launch_schema.json file. The remote Machine Name is ${debugInfo . remoteMachineName}](media/cmake-remote-debug-machine.png) -IntelliSense will suggest all a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**. +IntelliSense suggests a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**. If you want complete control over your deployment, you can append the following code block(s) to the launch.vs.json file. Remember to replace the placeholder values with real values: diff --git a/docs/linux/download-install-and-setup-the-linux-development-workload.md b/docs/linux/download-install-and-setup-the-linux-development-workload.md index 102bfca8ad..7187b8f44d 100644 --- a/docs/linux/download-install-and-setup-the-linux-development-workload.md +++ b/docs/linux/download-install-and-setup-the-linux-development-workload.md @@ -1,15 +1,15 @@ --- -title: "Install the C++ Linux workload in Visual Studio" -description: "How to download, install, and set up the Linux workload for C++ in Visual Studio." -ms.date: "05/03/2020" -ms.assetid: e11b40b2-f3a4-4f06-b788-73334d58dfd9 +title: "Install the C++ Linux Workload in Visual Studio" +description: "Learn how to download, install, and set up the Linux workload for C++ in Visual Studio." +ms.date: 03/25/2025 +ms.topic: how-to ms.custom: intro-installation --- # Download, install, and set up the Linux workload ::: moniker range="msvc-140" -Linux projects are supported in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +Linux projects are supported in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector for this article to Visual Studio 2017, Visual Studio 2019, or Visual Studio 2022. It's found at the top of the table of contents on this page. ::: moniker-end @@ -19,7 +19,7 @@ You can use the Visual Studio IDE on Windows to create, edit, and debug C++ proj You can work on your existing code base that uses CMake without having to convert it to a Visual Studio project. If your code base is cross-platform, you can target both Windows and Linux from within Visual Studio. For example, you can edit, build, and debug your code on Windows using Visual Studio. Then, quickly retarget the project for Linux to build and debug in a Linux environment. Linux header files are automatically copied to your local machine. Visual Studio uses them to provide full IntelliSense support (Statement Completion, Go to Definition, and so on). -For any of these scenarios, the **Linux development with C++** workload is required. +For any of these scenarios, the **Linux and embedded development with C++** workload is required. ::: moniker-end @@ -27,23 +27,25 @@ For any of these scenarios, the **Linux development with C++** workload is requi ## Visual Studio setup -1. Type "Visual Studio Installer" in the Windows search box: +1. Open the Visual Studio Installer from your Start menu. If you can't find it, type *Visual Studio Installer* in the Windows search box and look for the installer under the **Apps** results. - ![Screenshot showing the Windows search box.](media/visual-studio-installer-search.png) + :::image type="content" source="media/visual-studio-installer-search.png" alt-text="Screenshot of the Windows search box that contains the text visual studio installer."::: -1. Look for the installer under the **Apps** results and double-click it. When the installer opens, choose **Modify**, and then click on the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux development with C++** workload. +1. When the installer opens, choose **Modify**, and then click on the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux and embedded development with C++** workload. - ![Screenshot showing the Visual C++ for Linux Development workload item in Visual Studio Installer.](media/linuxworkload.png) + :::image type="complex" source="./media/linux-workload.png" alt-text="Screenshot highlighting the Visual C++ for Linux and embedded development workload item in Visual Studio Installer."::: + The Linux and embedded development workload is selected. The Installation details pane is highlighted, which lists what's included in the workload. Which includes: Visual Studio C++ core features, Windows Universal C runtime, Visual C++ for Linux development. An optional component is also selected: Visual C++ tools for CMake and Linux. + :::image-end::: -1. If you're targeting IoT or embedded platforms, go to the **Installation details** pane on the right. Under **Linux development with C++**, expand **Optional Components**, and choose the components you need. CMake support for Linux is selected by default. +1. If you're targeting IoT or embedded platforms, go to the **Installation details** pane on the right. Under **Linux and embedded development with C++**, expand **Optional Components**, and choose the components you need. CMake support for Linux is selected by default. 1. Click **Modify** to continue with the installation. ## Options for creating a Linux environment -If you don't already have a Linux machine, you can create a Linux Virtual Machine on Azure. For more information, see [Quickstart: Create a Linux virtual machine in the Azure portal](/azure/virtual-machines/linux/quick-create-portal). +If you don't already have a Linux machine, you can create a Linux virtual machine on Azure. For more information, see [Quickstart: Create a Linux virtual machine in the Azure portal](/azure/virtual-machines/linux/quick-create-portal). -On Windows 10 and later, you can install and target your favorite Linux distro on the Windows Subsystem for Linux (WSL). For more information, see [Windows Subsystem for Linux Installation Guide for Windows 10](/windows/wsl/install-win10). If you're unable to access the Windows Store, you can [manually download the WSL distro packages](/windows/wsl/install-manual). WSL is a convenient console environment, but it's not recommended for graphical applications. +On Windows 10 and later, you can install and target your favorite Linux distro on the Windows Subsystem for Linux (WSL). For more information, see [How to install Linux on Windows with WSL](/windows/wsl/install). If you're unable to access the Windows Store, you can [manually download the WSL distro packages](/windows/wsl/install-manual). WSL is a convenient console environment, but it's not recommended for graphical applications. ::: moniker-end @@ -100,9 +102,9 @@ The target Linux system must have **openssh-server**, **g++**, **gdb**, and **ma sudo apt-get install openssh-server g++ gdb make ninja-build rsync zip ``` - You may be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. + You might be prompted for your root password to run the `sudo` command. If so, enter it and continue. Once complete, the required services and tools are installed. -1. Ensure the ssh service is running on your Linux computer by running: +1. Ensure the ssh service is running on your Linux computer: ```bash sudo service ssh start @@ -138,9 +140,9 @@ The target machine running Fedora uses the **dnf** package installer. To downloa sudo dnf install openssh-server gcc-g++ gdb ninja-build make rsync zip ``` - You may be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. + You might be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. -1. Ensure the ssh service is running on your Linux computer by running: +1. Ensure the ssh service is running on your Linux computer: ```bash sudo systemctl start sshd @@ -148,11 +150,9 @@ The target machine running Fedora uses the **dnf** package installer. To downloa This command starts the service and runs it in the background, ready to accept connections. -## Next Steps +## Related content -You're now ready to create or open a Linux project and configure it to run on the target system. For more information, see: - -- [Create a new Linux MSBuild C++ project](create-a-new-linux-project.md) -- [Configure a Linux CMake project](cmake-linux-project.md) +- [Create a Linux MSBuild C++ project in Visual Studio](create-a-new-linux-project.md) +- [Create a CMake Linux project in Visual Studio](cmake-linux-project.md) ::: moniker-end diff --git a/docs/linux/index.yml b/docs/linux/index.yml index 206faf4104..0883a98df6 100644 --- a/docs/linux/index.yml +++ b/docs/linux/index.yml @@ -6,8 +6,8 @@ metadata: title: Linux development with C++ description: Learn how to use C++ in Visual Studio 2017 and later to create and debug applications for Linux. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 04/26/2020 ms.custom: intro-landing-hub diff --git a/docs/linux/linux-asan-configuration.md b/docs/linux/linux-asan-configuration.md index 127ad261d9..115a3a94c1 100644 --- a/docs/linux/linux-asan-configuration.md +++ b/docs/linux/linux-asan-configuration.md @@ -20,7 +20,7 @@ ASan is a runtime memory error detector for C/C++ that catches the following err When ASan detects an error, it stops execution immediately. If you run an ASan-enabled program in the debugger, you see a message that describes the type of error, the memory address, and the location in the source file where the error occurred: - ![Screenshot showing an ASan error message.](media/asan-error.png) + ![Screenshot showing the address sanitizer error message: heap use after free.](media/asan-error.png) You can also view the full ASan output (including where the corrupted memory was allocated/deallocated) in the Debug pane of the output window. @@ -31,26 +31,26 @@ You can also view the full ASan output (including where the corrupted memory was To enable ASan for MSBuild-based Linux projects, right-click on the project in **Solution Explorer** and select **Properties**. Next, navigate to **Configuration Properties** > **C/C++** > **Sanitizers**. ASan is enabled via compiler and linker flags, and requires your project to be recompiled to work. -![Enable ASan for an MSBuild project.](media/msbuild-asan-prop-page.png) +![Screenshot of the project property page with Configuration Properties > C/C plus plus > Sanitizers selected. Enable Address Sanitizer is set to Yes.](media/msbuild-asan-prop-page.png) You can pass optional ASan runtime flags by navigating to **Configuration Properties** > **Debugging** > **AddressSanitizer Runtime Flags**. Click the down-arrow to add or remove flags. -![Configure ASan runtime flags.](media/msbuild-asan-runtime-flags.png) +![Screenshot of the project property page with Configuration Properties > Debugging selected. Address Sanitizer Runtime Flags is `detect_leaks = 0`.](media/msbuild-asan-runtime-flags.png) ## Enable ASan for Visual Studio CMake projects > [!NOTE] > To build with CMake Presets, first enable ASan in your CMakeLists.txt file. For more information, see [Enable AddressSanitizer for Windows and Linux](../build/cmake-presets-vs.md#enable-addresssanitizer-for-windows-and-linux). -To enable ASan for CMake, right-click on the CMakeLists.txt file in **Solution Explorer** and choose **CMake Settings for Project**. +To enable ASan for CMake, right-click on the `CMakeLists.txt` file in **Solution Explorer** and choose **CMake Settings for Project**. Make sure you have a Linux configuration (for example, **Linux-Debug**) selected in the left pane of the dialog: -![Screenshot of the left pane with Linux Debug listed as one of the Configuration options.](media/linux-debug-configuration.png) +![Screenshot of the Configurations pane with x64-Debug and Linux Debug listed as the options.](media/linux-debug-configuration.png) The ASan options are under **General**. Enter the ASan runtime flags in the format "flag=value", separated by spaces. The UI incorrectly suggests using semi-colons. Use spaces or colons to separate flags. -![Screenshot of the Enable Address Sanitizer option showing some Address Sanitizer run time flags.](media/cmake-settings-asan-options.png) +![Screenshot of the Enable Address Sanitizer option showing some Address Sanitizer run time flags like detect_leaks=0.](media/cmake-settings-asan-options.png) ## Install the ASan debug symbols diff --git a/docs/linux/media/connect-to-your-remote-linux-computer/connect-updated.png b/docs/linux/media/connect-to-your-remote-linux-computer/connect-updated.png new file mode 100644 index 0000000000..7c8bb50e8a Binary files /dev/null and b/docs/linux/media/connect-to-your-remote-linux-computer/connect-updated.png differ diff --git a/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-error-updated.png b/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-error-updated.png new file mode 100644 index 0000000000..b3e8fee6ef Binary files /dev/null and b/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-error-updated.png differ diff --git a/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-updated.png b/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-updated.png new file mode 100644 index 0000000000..42b4e92a16 Binary files /dev/null and b/docs/linux/media/connect-to-your-remote-linux-computer/settings-connection-manager-updated.png differ diff --git a/docs/linux/media/connection-manager-vs2019.png b/docs/linux/media/connection-manager-vs2019.png index d4da0b9797..cfeec7a3e2 100644 Binary files a/docs/linux/media/connection-manager-vs2019.png and b/docs/linux/media/connection-manager-vs2019.png differ diff --git a/docs/linux/media/linux-general-prop-page-vs2019.png b/docs/linux/media/linux-general-prop-page-vs2019.png deleted file mode 100644 index 7ca6c7ead4..0000000000 Binary files a/docs/linux/media/linux-general-prop-page-vs2019.png and /dev/null differ diff --git a/docs/linux/media/linux-remote-debug-machine.png b/docs/linux/media/linux-remote-debug-machine.png index 1ad440c868..17eb4d3f00 100644 Binary files a/docs/linux/media/linux-remote-debug-machine.png and b/docs/linux/media/linux-remote-debug-machine.png differ diff --git a/docs/linux/media/linux-workload.png b/docs/linux/media/linux-workload.png new file mode 100644 index 0000000000..8a8baa1142 Binary files /dev/null and b/docs/linux/media/linux-workload.png differ diff --git a/docs/linux/media/linuxworkload.png b/docs/linux/media/linuxworkload.png deleted file mode 100644 index 5904de11ec..0000000000 Binary files a/docs/linux/media/linuxworkload.png and /dev/null differ diff --git a/docs/linux/media/remote-build-machine-vs2019.png b/docs/linux/media/remote-build-machine-vs2019.png index 48fed59dbc..9d9d1c23cd 100644 Binary files a/docs/linux/media/remote-build-machine-vs2019.png and b/docs/linux/media/remote-build-machine-vs2019.png differ diff --git a/docs/linux/media/remote-file-explorer-download.png b/docs/linux/media/remote-file-explorer-download.png new file mode 100644 index 0000000000..befc41cb08 Binary files /dev/null and b/docs/linux/media/remote-file-explorer-download.png differ diff --git a/docs/linux/media/remote-file-explorer-menu-item.png b/docs/linux/media/remote-file-explorer-menu-item.png new file mode 100644 index 0000000000..a118df5a61 Binary files /dev/null and b/docs/linux/media/remote-file-explorer-menu-item.png differ diff --git a/docs/linux/media/remote-file-explorer-progress.png b/docs/linux/media/remote-file-explorer-progress.png new file mode 100644 index 0000000000..95e524bf70 Binary files /dev/null and b/docs/linux/media/remote-file-explorer-progress.png differ diff --git a/docs/linux/media/remote-file-explorer-toolbar.png b/docs/linux/media/remote-file-explorer-toolbar.png new file mode 100644 index 0000000000..16ea87e721 Binary files /dev/null and b/docs/linux/media/remote-file-explorer-toolbar.png differ diff --git a/docs/linux/media/remote-file-explorer-upload.png b/docs/linux/media/remote-file-explorer-upload.png new file mode 100644 index 0000000000..062b589e60 Binary files /dev/null and b/docs/linux/media/remote-file-explorer-upload.png differ diff --git a/docs/linux/media/remote-file-explorer.png b/docs/linux/media/remote-file-explorer.png new file mode 100644 index 0000000000..db9ab3b222 Binary files /dev/null and b/docs/linux/media/remote-file-explorer.png differ diff --git a/docs/linux/media/remote-logging-vs2019.png b/docs/linux/media/remote-logging-vs2019.png index e2571dfe45..ccbea26f72 100644 Binary files a/docs/linux/media/remote-logging-vs2019.png and b/docs/linux/media/remote-logging-vs2019.png differ diff --git a/docs/linux/media/settings_general.png b/docs/linux/media/settings_general.png index 465474497c..549f9cec33 100644 Binary files a/docs/linux/media/settings_general.png and b/docs/linux/media/settings_general.png differ diff --git a/docs/linux/media/vs2019-debugger-settings.png b/docs/linux/media/vs2019-debugger-settings.png index 43d7f8787b..676aa732cb 100644 Binary files a/docs/linux/media/vs2019-debugger-settings.png and b/docs/linux/media/vs2019-debugger-settings.png differ diff --git a/docs/linux/prop-pages/debugging-linux.md b/docs/linux/prop-pages/debugging-linux.md index 09c96b4892..e6ca60889f 100644 --- a/docs/linux/prop-pages/debugging-linux.md +++ b/docs/linux/prop-pages/debugging-linux.md @@ -1,5 +1,5 @@ --- -title: "Debugger Properties (Linux C++)| Microsoft Docs" +title: Debugger Properties (Linux C++) description: "Describes the Microsoft Visual Studio Linux C++ debugger properties" ms.date: "06/07/2019" ms.assetid: 0c1c0fcc-a49b-451c-a5cb-ce9711fac064 diff --git a/docs/linux/prop-pages/makefile-linux.md b/docs/linux/prop-pages/makefile-linux.md index 6d0a0bba91..4b13726858 100644 --- a/docs/linux/prop-pages/makefile-linux.md +++ b/docs/linux/prop-pages/makefile-linux.md @@ -1,6 +1,6 @@ --- description: "Learn more about: Makefile Project Properties (Linux C++)" -title: "General Properties (Linux C++ Makefile Project)| Microsoft Docs" +title: General Properties (Linux C++ Makefile Project) ms.date: "06/07/2019" ms.assetid: 3dec6853-43f6-412b-9806-9bfad333a204 --- diff --git a/docs/linux/remote-file-explorer.md b/docs/linux/remote-file-explorer.md new file mode 100644 index 0000000000..2f4ca5327e --- /dev/null +++ b/docs/linux/remote-file-explorer.md @@ -0,0 +1,112 @@ +--- +title: "Remote file explorer" +description: "Learn how to use Remote File Explorer to view, upload, and download files on a remote machine form within Visual Studio." +ms.topic: how-to +ms.date: 06/02/2025 +--- +# Remote File Explorer + +Learn how to use **Remote File Explorer** to view, upload, and download files on a remote machine from Visual Studio. With **Remote File Explorer**, perform common file operations such as: + +- Upload files from your local machine to a remote machine +- Download files from a remote machine to your local machine +- Create folders on a remote machine +- Delete files and folders on a remote machine +- Rename files and folders on a remote machine +- Search for files and folders on a remote machine + +## Prerequisites + +Visual Studio version 17.6 or later. + +Ensure that the **Linux and embedded development with C++** workload is installed. Run the Visual Studio Installer and ensure that the **Linux and embedded development with C++** workload is selected. Also ensure that the **Remote File Explorer for Linux** component is selected, and update your installation if necessary. + +:::image type="content" source="media/linux-workload.png" alt-text="Screenshot of the Visual Studio Installer. The **Linux and embedded development with C++** workload is selected. In the installation details pane, Remote File Explorer for Linux is selected."::: + +Install and configure Secure Shell (SSH) on the remote machine. To install SSH on Linux, run these commands on the remote machine: + +```bash +sudo apt update +sudo apt install openssh-server +sudo systemctl start ssh +sudo systemctl status ssh +``` + +## View and edit files on a remote machine + +In these examples, the remote machine is a Windows Subsystem for Linux instance running on localhost port 22. The project is a new CMake project created in Visual Studio. The sample project is on the remote machine in the `C:\Users\{username}\projects\` folder. + +To open the **Remote File Explorer** in Visual Studio, choose **View** > **Other Windows** > **Remote File Explorer**. + +:::image type="content" source="media/remote-file-explorer-menu-item.png" alt-text="Screenshot of the Visual Studio View menu. Remote File Explorer is highlighted."::: + +The **Remote File Explorer** window opens: + +:::image type="content" source="media/remote-file-explorer.png" alt-text="Screenshot of the Remote File Explorer. The folder system on the remote machine is visible."::: + +If you see a message to select or create a new connection in the **Connection Manager**, ensure that the SSH server is running on the remote machine. If your remote machine is running on Windows Subsystem for Linux (WSL), ensure that the WSL instance is running. Make sure the Visual Studio debug target dropdown is set to the remote instance. To connect to a different remote machine, in the **Remote File Explorer** window's **Select the host target** dropdown, select the remote target. It may appear in a form such as `username@hostname:port`. For example, `username@localhost:22`. You can also select **Add new connection** to add a new connection to the **Connection Manager**. For more information, see [Connection manager](connect-to-your-remote-linux-computer.md). + +Open and edit files directly from the **Remote File Explorer**. To open a file, double-click the file in the **Remote File Explorer** window. The file opens in the editor window. You can also right-click the file and select **Open** from the context menu or press **Ctrl+Enter**. When you save the file, the changes are saved directly to the remote machine. + +## Upload files to a remote machine + +To upload files or directories to the remote machine, right-click the folder in the **Remote File Explorer** window where you want to upload files, and select **Upload**. + +:::image type="content" source="media/remote-file-explorer-upload.png" alt-text="Screenshot of the Remote File Explorer showing the Upload a directory and Upload files menu options."::: + +Use the folder explorer window that opens to select the file or folder you want to upload. You can drag and drop files from your local machine onto the **Remote File Explorer** window. Alternatively, use the **Upload Files** or **Upload Folder** buttons to choose the items to upload: + +## Download files from a remote machine + +To download files or directories from the remote machine, right-click the folder or file in the **Remote File Explorer** window that you want to download and select **Download**. + +:::image type="content" source="media/remote-file-explorer-download.png" alt-text="Screenshot of the Remote File Explorer displaying the menu option: Download 'asset.txt'."::: + +Use the folder explorer window that opens to select where to download the file or folder. You can also use the **Download Item** button to choose the item you want to download. + +## Monitor and cancel file operations + +Monitor the progress of uploading or downloading items in the status window at the bottom of the **Remote File Explorer** window. Select the **Cancel** button to stop the operation. + +:::image type="content" source="media/remote-file-explorer-progress.png" alt-text="Screenshot of the Remote File Explorer showing the progress indicator. The Cancel button is highlighted."::: + +## Other file operations + +Rename files and folders, create new folders, delete files and folders, and search for files and folders. + +- Rename a file or folder: right-click the file or folder and select **Rename** from the context menu, or select the rename button on the toolbar. The filename becomes editable. Type the new name for the item and press **Enter**. +- Create a new folder: right-click in the **Remote File Explorer** window and select **New Folder**. Enter a name for the new folder and press **Enter**. +- Delete a file or folder: right-click the file or folder and select **Delete** from the context menu, or select the delete button on the toolbar. Confirm the deletion in the dialog that appears. Deleting files or folders from the remote machine is a permanent action and can't be undone. +- Refresh the view: right-click in the **Remote File Explorer** window and select **Refresh** from the context menu, or select the refresh button on the toolbar, or press **F5**. It only refreshes the view of what is selected. If you have a folder selected, it refreshes the view of that folder. If you have a file selected, it refreshes the view of that file. +- Search for files: enter text in the search box at the top of the **Remote File Explorer** window to find folders or files. The search is case-insensitive and searches all files and folders under the selected item. If a folder is selected, it searches all files and folders in that folder. If a file is selected, it searches all files and folders in the same directory as that file. + +## Remote File Explorer toolbar buttons + +The **Remote File Explorer** toolbar lets you access remote file operations: + +:::image type="content" source="media/remote-file-explorer-toolbar.png" alt-text="Screenshot of the Remote File Explorer toolbar." ::: + +The highlighted buttons are, from left to right: + +- **+**: Create a new Remote Explorer window. +- **Home**: Go to the `$HOME` directory of the currently signed-in user on the remote machine. +- **Settings**: Open the settings for the **Remote File Explorer**. +- **Upload Files**: Upload files from your local machine to the remote machine. +- **Upload Folder**: Upload a folder from your local machine to the remote machine. +- **Download Item**: Download a file or folder from the remote machine to your local machine. +- **Refresh Item**: Refresh the view of the selected item. +- **Rename Item**: Rename a file or folder on the remote machine. +- **Delete Item**: Delete a file or folder on the remote machine. +- **Search**: Search for files or folders on the remote machine. + +## Remote File Explorer settings + +To change the settings for the **Remote File Explorer**, select the **Settings** button on the toolbar. The **Remote File Explorer Settings** dialog opens with the following option: + +- **Enable Dynamic File Icons for Extension-less Files**: Shows icons based on file type by checking the mime-type. Useful for Linux files without extensions so that a correct file icon is shown instead of a generic document icon. May impact performance. + +## See also + +- [The Remote File Explorer tool window of Visual Studio (video)](/shows/pure-virtual-cpp-2023/the-remote-file-explorer-tool-window-of-visual-studio) +- [Connection manager](connect-to-your-remote-linux-computer.md) +- [Create a CMake Linux project in Visual Studio](cmake-linux-project.md) \ No newline at end of file diff --git a/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md b/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md index 791a759d80..fbfacf7a4f 100644 --- a/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md +++ b/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md @@ -1,7 +1,7 @@ --- title: "Set up FIPS-compliant secure remote Linux development" description: "How to set up a FIPS-compliant cryptographic connection between Visual Studio and a Linux machine for remote development." -ms.date: "01/17/2020" +ms.date: 07/06/2022 --- # Set up FIPS-compliant secure remote Linux development @@ -32,13 +32,13 @@ The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7. sudo service ssh start ``` -1. If you’d like the ssh server to start automatically when the system boots, enable it using systemctl: +1. If you'd like the `ssh` server to start automatically when the system boots, enable it using `systemctl`: ```bash sudo systemctl enable ssh ``` -1. Open */etc/ssh/sshd_config* as root. Edit (or add, if they don’t exist) the following lines: +1. Open *`/etc/ssh/sshd_config`* as root. Edit (or add, if they don't exist) the following lines: ```config Ciphers aes256-cbc,aes192-cbc,aes128-cbc,3des-cbc @@ -48,48 +48,48 @@ The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7. ``` > [!NOTE] - > ssh-rsa is the only FIPS compliant host key algorithm VS supports. The aes\*-ctr algorithms are also FIPS compliant, but the implementation in Visual Studio isn't approved. The ecdh-\* key exchange algorithms are FIPS compliant, but Visual Studio doesn't support them. + > `ssh-rsa`, `rsa-sha2-*`, and `ecdsa-sha2-*` are the only FIPS compliant host key algorithms VS supports. For more information about the algorithms Visual Studio supports, see [Supported SSH Algorithms](connect-to-your-remote-linux-computer.md#supported-ssh-algorithms). - You're not limited to these options. You can configure ssh to use additional ciphers, host key algorithms, and so on. Some other relevant security options you may want to consider are `PermitRootLogin`, `PasswordAuthentication`, and `PermitEmptyPasswords`. For more information, see the man page for sshd_config or the article [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config). + You're not limited to these options. You can configure `ssh` to use other ciphers, host key algorithms, and so on. Some other relevant security options you may want to consider are `PermitRootLogin`, `PasswordAuthentication`, and `PermitEmptyPasswords`. For more information, see the `man` page for `sshd_config` or the article [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config). -1. After saving and closing sshd_config, restart the ssh server to apply the new configuration: +1. After saving and closing `sshd_config`, restart the ssh server to apply the new configuration: ```bash sudo service ssh restart ``` -Next, you'll create an RSA key pair on your Windows computer. Then you'll copy the public key to the remote Linux system for use by ssh. +Next, you'll create an ECDSA key pair on your Windows computer. Then you'll copy the public key to the remote Linux system for use by ssh. -### To create and use an RSA key file +### To create and use an ECDSA key file -1. On the Windows machine, generate a public/private RSA key pair by using this command: +1. On the Windows machine, generate a public/private ECDSA key pair by using this command: ```cmd - ssh-keygen -t rsa -b 4096 + ssh-keygen -t ecdsa -m PEM ``` - The command creates a public key and a private key. By default, the keys are saved to *%USERPROFILE%\\.ssh\\id_rsa* and *%USERPROFILE%\\.ssh\\id_rsa.pub*. (In Powershell, use `$env:USERPROFILE` instead of the cmd macro `%USERPROFILE%`) If you change the key name, use the changed name in the steps that follow. We recommend you use a passphrase for increased security. + The command creates a public key and a private key. By default, the keys are saved to %USERPROFILE%\.ssh\id_ecdsa and %USERPROFILE%\.ssh\id_ecdsa.pub. (In PowerShell, use $env:USERPROFILE instead of the cmd macro %USERPROFILE%) Keys generated with RSA are also supported. If you change the key name, use the changed name in the steps that follow. We recommend you use a passphrase for increased security. 1. From Windows, copy the public key to the Linux machine: ```cmd - scp %USERPROFILE%\.ssh\id_rsa.pub user@hostname: + scp %USERPROFILE%\.ssh\id_ecdsa.pub user@hostname: ``` 1. On the Linux system, add the key to the list of authorized keys, and ensure the file has the correct permissions: ```bash - cat ~/id_rsa.pub >> ~/.ssh/authorized_keys + cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` -1. Now, you can test to see if the new key works in ssh. Use it to sign in from Windows: +1. Now, you can test to see if the new key works in `ssh`. Use it to sign in from Windows: ```cmd - ssh -i %USERPROFILE%\.ssh\id_rsa user@hostname + ssh -i %USERPROFILE%\.ssh\id_ecdsa user@hostname ``` -You've successfully set up ssh, created and deployed encryption keys, and tested your connection. Now you're ready to set up the Visual Studio connection. +You've successfully set up `ssh`, created and deployed encryption keys, and tested your connection. Now you're ready to set up the Visual Studio connection. ## Connect to the remote system in Visual Studio @@ -99,22 +99,22 @@ You've successfully set up ssh, created and deployed encryption keys, and tested 1. In the Connection Manager dialog, choose the **Add** button to add a new connection. - ![Screenshot showing the Connection Manager dialog.](media/settings_connectionmanager.png) + ![Screenshot showing the options pane in the Connection Manager dialog. Cross Platform > C plus plus > Connection Manager is highlighted.](media/settings_connectionmanager.png) The **Connect to Remote System** window is displayed. - ![Screenshot showing the Connect to Remote System window.](media/connect.png) + ![Screenshot showing the Connect to Remote System window, which has text boxes for the host name, port, user name, auth type, and password.](media/connect.png) 1. In the **Connect to Remote System** dialog, enter the connection details of your remote machine. - | Entry | Description - | ----- | --- - | **Host Name** | Name or IP address of your target device - | **Port** | Port that the SSH service is running on, typically 22 - | **User name** | User to authenticate as - | **Authentication type** | Choose Private Key for a FIPS-compliant connection - | **Private key file** | Private key file created for ssh connection - | **Passphrase** | Passphrase used with private key selected above + | Entry | Description | + |--|--| + | **Host Name** | Name or IP address of your target device | + | **Port** | Port that the SSH service is running on, typically 22 | + | **User name** | User to authenticate as | + | **Authentication type** | Choose **Private Key** for a FIPS-compliant connection | + | **Private key file** | Private key file created for ssh connection | + | **Passphrase** | Passphrase used with private key selected above | Change the authentication type to **Private Key**. Enter the path to your private key in the **Private key file** field. You can use the **Browse** button to navigate to your private key file instead. Then, enter the passphrase used to encrypt your private key file in the **Passphrase** field. @@ -124,19 +124,19 @@ You've successfully set up ssh, created and deployed encryption keys, and tested If the connection fails, the entry boxes that need to be changed are outlined in red. - ![Screenshot showing a Connection Manager Error.](media/settings_connectionmanagererror.png) + ![Screenshot of the Connect to Remote System window which has host name and port text boxes outlined in red to indicate they need to be changed.](media/settings_connectionmanagererror.png) For more information on troubleshooting your connection, see [Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md). ## Command-line utility for the Connection Manager -**Visual Studio 2019 version 16.5 or later**: ConnectionManager.exe is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see [ConnectionManager reference](connectionmanager-reference.md). +**Visual Studio 2019 version 16.5 or later**: `ConnectionManager.exe` is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see [ConnectionManager reference](connectionmanager-reference.md). ## Optional: Enable or disable FIPS mode It's possible to enable FIPS mode globally in Windows. -1. To enable FIPS mode, press **Windows+R** to open the Run dialog, and then run gpedit.msc. +1. To enable FIPS mode, press **Windows+R** to open the **Run** dialog, and then run `gpedit.msc`. 1. Expand **Local Computer Policy > Computer Configuration > Windows Settings > Security Settings > Local Policies** and select **Security Options**. @@ -145,7 +145,7 @@ It's possible to enable FIPS mode globally in Windows. 1. In the **Local Security Setting** tab, select **Enabled** or **Disabled**, and then choose **OK** to save your changes. > [!WARNING] -> Enabling FIPS mode may cause some applications to break or behave unexpectedly. For more information, see the blog post [Why We’re Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037). +> Enabling FIPS mode may cause some applications to break or behave unexpectedly. For more information, see the blog post [Why We're Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037). ## Additional resources @@ -155,7 +155,7 @@ It's possible to enable FIPS mode globally in Windows. [Cryptographic Algorithm Validation Program: Validation Notes](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/Validation-Notes) (from NIST) -Microsoft blog post on [Why We’re Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037) +Microsoft blog post on [Why We're Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037) [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config) diff --git a/docs/linux/toc.yml b/docs/linux/toc.yml index 06e6695271..34c5c53245 100644 --- a/docs/linux/toc.yml +++ b/docs/linux/toc.yml @@ -7,6 +7,8 @@ items: items: - name: Connect to your remote Linux computer href: ../linux/connect-to-your-remote-linux-computer.md + - name: Remote File Explorer + href: ../linux/remote-file-explorer.md - name: Set up FIPS-compliant secure remote Linux development href: ../linux/set-up-fips-compliant-secure-remote-linux-development.md - name: ConnectionManager reference diff --git a/docs/mfc/accessing-run-time-class-information.md b/docs/mfc/accessing-run-time-class-information.md index b0fd0b53c7..c8891bb05c 100644 --- a/docs/mfc/accessing-run-time-class-information.md +++ b/docs/mfc/accessing-run-time-class-information.md @@ -33,7 +33,7 @@ You will rarely need to access the run-time class object directly. A more common 1. Call the `IsKindOf` member function for objects of that class, using the `RUNTIME_CLASS` macro to generate the `CRuntimeClass` argument, as shown here: [!code-cpp[NVC_MFCCObjectSample#2](codesnippet/cpp/accessing-run-time-class-information_2.h)] - +   [!code-cpp[NVC_MFCCObjectSample#5](codesnippet/cpp/accessing-run-time-class-information_3.cpp)] > [!NOTE] diff --git a/docs/mfc/activation-verbs.md b/docs/mfc/activation-verbs.md index 5c97e74cb5..31e35ddfed 100644 --- a/docs/mfc/activation-verbs.md +++ b/docs/mfc/activation-verbs.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Activation: Verbs" title: "Activation: Verbs" -ms.date: "11/04/2016" -helpviewer_keywords: ["verbs [MFC]", "OLE [MFC], activation", "edit verb [MFC]", "activation [MFC], verbs", "OLE [MFC], editing", "Primary verb [MFC]", "OLE activation {MFC]"] -ms.assetid: eb56ff23-1de8-43ad-abeb-dc7346ba7b70 +description: "Learn more about: Activation: Verbs" +ms.date: 11/04/2016 +helpviewer_keywords: ["verbs [MFC]", "OLE [MFC], activation", "edit verb [MFC]", "activation [MFC], verbs", "OLE [MFC], editing", "Primary verb [MFC]", "OLE activation [MFC]"] --- # Activation: Verbs diff --git a/docs/mfc/codesnippet/CPP/accessing-the-embedded-month-calendar-control_2.cpp b/docs/mfc/codesnippet/CPP/accessing-the-embedded-month-calendar-control_2.cpp index 240dd065e7..fbc30334bf 100644 --- a/docs/mfc/codesnippet/CPP/accessing-the-embedded-month-calendar-control_2.cpp +++ b/docs/mfc/codesnippet/CPP/accessing-the-embedded-month-calendar-control_2.cpp @@ -1,4 +1,3 @@ - //create and initialize the font to be used LOGFONT logFont = {0}; logFont.lfHeight = -12; diff --git a/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp b/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp index 5bb7063b2a..a54aeb9049 100644 --- a/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp +++ b/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp @@ -1,4 +1,3 @@ - // Create the bitmap button (must include the BS_OWNERDRAW style). pmyButton->Create(NULL, WS_CHILD | WS_VISIBLE | BS_OWNERDRAW, CRect(10, 10, 100, 100), pParentWnd, 1); diff --git a/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp b/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp index 0583ae03fb..63f44247ad 100644 --- a/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp +++ b/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp @@ -23,7 +23,7 @@ return FALSE; // After the following call, MFC is aware of the doc // template and will free it when the application is // shut down. The doc templates known to MFC will -// automatically be used when CWinApp:OnFileOpen() +// automatically be used when CWinApp::OnFileOpen() // or CWinApp::OnFileNew() are called. AddDocTemplate(pDocTemplate); \ No newline at end of file diff --git a/docs/mfc/codesnippet/CPP/connection-maps_3.cpp b/docs/mfc/codesnippet/CPP/connection-maps_3.cpp index cffe2a236b..cab527dac6 100644 --- a/docs/mfc/codesnippet/CPP/connection-maps_3.cpp +++ b/docs/mfc/codesnippet/CPP/connection-maps_3.cpp @@ -10,4 +10,4 @@ IUnknown* pUnkSink = mysink.GetInterface(&iid); //pUnkSrc is IUnknown of server obtained by CoCreateInstance(). //dwCookie is a cookie identifying the connection, and is needed //to terminate this connection. -AfxConnectionAdvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, &dwCookie); \ No newline at end of file +AfxConnectionAdvise(pUnkSrc, IID_ISampleSink, pUnkSink, TRUE, &dwCookie); \ No newline at end of file diff --git a/docs/mfc/codesnippet/CPP/connection-maps_4.cpp b/docs/mfc/codesnippet/CPP/connection-maps_4.cpp index 7fd1ae018a..8e5eed54a3 100644 --- a/docs/mfc/codesnippet/CPP/connection-maps_4.cpp +++ b/docs/mfc/codesnippet/CPP/connection-maps_4.cpp @@ -6,4 +6,4 @@ IUnknown* pUnkSink = mysink.GetInterface(&iid); //Terminate a connection between source and sink. //pUnkSrc is IUnknown of server obtained by CoCreateInstance(). //dwCookie is a value obtained through AfxConnectionAdvise(). -AfxConnectionUnadvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, dwCookie); \ No newline at end of file +AfxConnectionUnadvise(pUnkSrc, IID_ISampleSink, pUnkSink, TRUE, dwCookie); \ No newline at end of file diff --git a/docs/mfc/codesnippet/CPP/csingledoctemplate-class_2.cpp b/docs/mfc/codesnippet/CPP/csingledoctemplate-class_2.cpp index e811430289..bcd02c9f95 100644 --- a/docs/mfc/codesnippet/CPP/csingledoctemplate-class_2.cpp +++ b/docs/mfc/codesnippet/CPP/csingledoctemplate-class_2.cpp @@ -25,6 +25,6 @@ return FALSE; // After the following call, MFC is aware of the doc // template and will free it when the application is // shut down. The doc templates known to MFC will -// automatically be used when CWinApp:OnFileOpen() or +// automatically be used when CWinApp::OnFileOpen() or // CWinApp::OnFileNew() are called. AddDocTemplate(pDocTemplate); \ No newline at end of file diff --git a/docs/mfc/dynamic-object-creation.md b/docs/mfc/dynamic-object-creation.md index 508a2012a9..a7e77c3fe6 100644 --- a/docs/mfc/dynamic-object-creation.md +++ b/docs/mfc/dynamic-object-creation.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Dynamic Object Creation" title: "Dynamic Object Creation" +description: "Learn more about: Dynamic Object Creation" ms.date: "03/27/2020" helpviewer_keywords: ["object creation [MFC], dynamically at run time", "CObject class [MFC], dynamic object creation", "objects [MFC], creating dynamically at run time", "dynamic object creation [MFC]"] -ms.assetid: 3e0f51cb-3e24-4231-817f-1c0ce9f2d5df --- # Dynamic Object Creation @@ -17,5 +16,5 @@ This article explains how to create an object dynamically at run time. The proce ## See also -[Destroying Window Objects](tn017-destroying-window-objects.md) +[Destroying Window Objects](tn017-destroying-window-objects.md)\ [Using CObject](using-cobject.md) diff --git a/docs/mfc/form-views-mfc.md b/docs/mfc/form-views-mfc.md index 414faffdf9..05801af544 100644 --- a/docs/mfc/form-views-mfc.md +++ b/docs/mfc/form-views-mfc.md @@ -12,7 +12,7 @@ You can add forms to any Visual C++ application that supports the MFC libraries, With an SDI application, when the user chooses the **New** command, the current instance of the form continues to run but a new instance of the application with the selected form is created if one is not found. In an MDI application, the current instance of the form continues to run when the user chooses the **New** command. > [!NOTE] -> You can insert a form into a dialog-based application (one whose dialog class is based on `CDialog` and one in which no view class is implemented). However, without the document/view architecture, Visual C++ does not automatically implement the **File**|**New** functionality. You must create a way for the user to view additional forms, such as by implementing a tabbed dialog box with various property pages. +> You can insert a form into a dialog-based application (one whose dialog class is based on `CDialog` and one in which no view class is implemented). However, without the document/view architecture, Visual C++ does not automatically implement the **File** > **New** functionality. You must create a way for the user to view additional forms, such as by implementing a tabbed dialog box with various property pages. When you insert a new form into your application, Visual C++ does the following: diff --git a/docs/mfc/mfc-activex-controls-adding-custom-properties.md b/docs/mfc/mfc-activex-controls-adding-custom-properties.md index 475af7fd44..a14b72ef64 100644 --- a/docs/mfc/mfc-activex-controls-adding-custom-properties.md +++ b/docs/mfc/mfc-activex-controls-adding-custom-properties.md @@ -49,7 +49,7 @@ This same procedure can also be used to add other custom properties you want. Su 1. From the shortcut menu, click **Add** and then click **Add Property**. - This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#names-add-property-wizard). + This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#add-property-wizard). 1. In the **Property Name** box, type *CircleOffset*. diff --git a/docs/mfc/mfc-activex-controls-adding-stock-methods.md b/docs/mfc/mfc-activex-controls-adding-stock-methods.md index a5528b0104..7764a1a974 100644 --- a/docs/mfc/mfc-activex-controls-adding-stock-methods.md +++ b/docs/mfc/mfc-activex-controls-adding-stock-methods.md @@ -21,7 +21,7 @@ A stock method differs from a custom method in that it is already implemented by ## Adding a Stock Method Using the Add Method Wizard -Adding a stock method is simple using the [Add Method Wizard](../ide/adding-a-method-visual-cpp.md#add-method-wizard). The following procedure demonstrates adding the Refresh method to a control created using the MFC ActiveX Control Wizard. +Adding a stock method is simple using the [Add Method Wizard](../ide/adding-a-method-visual-cpp.md). The following procedure demonstrates adding the Refresh method to a control created using the MFC ActiveX Control Wizard. #### To add the stock Refresh method using the Add Method Wizard diff --git a/docs/mfc/mfc-activex-controls-adding-stock-properties.md b/docs/mfc/mfc-activex-controls-adding-stock-properties.md index 6d49c19c4f..8d70bbf492 100644 --- a/docs/mfc/mfc-activex-controls-adding-stock-properties.md +++ b/docs/mfc/mfc-activex-controls-adding-stock-properties.md @@ -38,7 +38,7 @@ Adding stock properties requires less code than adding custom properties because 1. From the shortcut menu, click **Add** and then click **Add Property**. - This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#names-add-property-wizard). + This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#add-property-wizard). 1. In the **Property Name** box, click **Caption**. diff --git a/docs/mfc/mfc-activex-controls-advanced-property-implementation.md b/docs/mfc/mfc-activex-controls-advanced-property-implementation.md index 32bab13f1d..0322788921 100644 --- a/docs/mfc/mfc-activex-controls-advanced-property-implementation.md +++ b/docs/mfc/mfc-activex-controls-advanced-property-implementation.md @@ -30,7 +30,7 @@ The Add Property Wizard provides a quick and easy method to implement read-only 1. From the shortcut menu, click **Add** and then click **Add Property**. - This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#names-add-property-wizard). + This opens the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#add-property-wizard). 1. In the **Property Name** box, type the name of your property. diff --git a/docs/mfc/mfc-activex-controls-using-fonts.md b/docs/mfc/mfc-activex-controls-using-fonts.md index 874de65d99..dc16f5d452 100644 --- a/docs/mfc/mfc-activex-controls-using-fonts.md +++ b/docs/mfc/mfc-activex-controls-using-fonts.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: MFC ActiveX Controls: Using Fonts" title: "MFC ActiveX Controls: Using Fonts" +description: "Learn more about: MFC ActiveX Controls: Using Fonts" ms.date: "11/19/2018" f1_keywords: ["OnFontChanged", "HeadingFont", "InternalFont"] helpviewer_keywords: ["notifications [MFC], MFC ActiveX controls fonts", "OnDraw method, MFC ActiveX controls", "InternalFont method [MFC]", "SetFont method [MFC]", "OnFontChanged method [MFC]", "IPropertyNotifySink class [MFC]", "MFC ActiveX controls [MFC], fonts", "Stock Font property [MFC]", "HeadingFont property [MFC]", "GetFont method [MFC]", "SelectStockFont method [MFC]", "fonts [MFC], ActiveX controls"] -ms.assetid: 7c51d602-3f5a-481d-84d1-a5d8a3a71761 --- # MFC ActiveX Controls: Using Fonts @@ -22,7 +21,7 @@ Stock Font properties are preimplemented by the class [COleControl](reference/co Access the font object through the [GetFont](reference/colecontrol-class.md#getfont), [SetFont](reference/colecontrol-class.md#setfont), and [InternalGetFont](reference/colecontrol-class.md#internalgetfont) functions of `COleControl`. The control user will access the font object via the `GetFont` and `SetFont` functions in the same manner as any other Get/Set property. When access to the font object is required from within a control, use the `InternalGetFont` function. -As discussed in [MFC ActiveX Controls: Properties](mfc-activex-controls-properties.md), adding stock properties is easy with the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#names-add-property-wizard). You choose the Font property, and the Add Property Wizard automatically inserts the stock Font entry into the control's dispatch map. +As discussed in [MFC ActiveX Controls: Properties](mfc-activex-controls-properties.md), adding stock properties is easy with the [Add Property Wizard](../ide/adding-a-property-visual-cpp.md#add-property-wizard). You choose the Font property, and the Add Property Wizard automatically inserts the stock Font entry into the control's dispatch map. #### To add the stock Font property using the Add Property Wizard @@ -112,7 +111,7 @@ To implement a custom Font property, you use the Add Property Wizard to add the 1. Click **Finish**. -The Add Property Wizard creates the code to add the `HeadingFont` custom property to the `CSampleCtrl` class and the SAMPLE.IDL file. Because `HeadingFont` is a Get/Set property type, the Add Property Wizard modifies the `CSampleCtrl` class's dispatch map to include a DISP_PROPERTY_EX_ID[DISP_PROPERTY_EX](reference/dispatch-maps.md#disp_property_ex) macro entry: +The Add Property Wizard creates the code to add the `HeadingFont` custom property to the `CSampleCtrl` class and the SAMPLE.IDL file. Because `HeadingFont` is a Get/Set property type, the Add Property Wizard modifies the `CSampleCtrl` class's dispatch map to include a DISP_PROPERTY_EX_ID [DISP_PROPERTY_EX](reference/dispatch-maps.md#disp_property_ex) macro entry: [!code-cpp[NVC_MFC_AxFont#5](codesnippet/cpp/mfc-activex-controls-using-fonts_5.cpp)] @@ -215,6 +214,6 @@ After these changes have been made to your project, rebuild the project and use ## See also -[MFC ActiveX Controls](mfc-activex-controls.md)
-[MFC ActiveX Controls: Using Pictures in an ActiveX Control](mfc-activex-controls-using-pictures-in-an-activex-control.md)
+[MFC ActiveX Controls](mfc-activex-controls.md)\ +[MFC ActiveX Controls: Using Pictures in an ActiveX Control](mfc-activex-controls-using-pictures-in-an-activex-control.md)\ [MFC ActiveX Controls: Using Stock Property Pages](mfc-activex-controls-using-stock-property-pages.md) diff --git a/docs/mfc/ole-background.md b/docs/mfc/ole-background.md index 859cbbf19a..2d89820a30 100644 --- a/docs/mfc/ole-background.md +++ b/docs/mfc/ole-background.md @@ -61,7 +61,7 @@ Some of the more important OLE topics are covered in the following articles: - [OLE Background: MFC Implementation](ole-background-mfc-implementation.md) -For general OLE information not found in the above articles, [search for OLE](/search/?terms=ole) in Microsoft Docs. +For general OLE information not found in the articles listed, [search for OLE](/search/?terms=ole) . ## See also diff --git a/docs/mfc/reference/add-class-from-typelib-wizard.md b/docs/mfc/reference/add-class-from-typelib-wizard.md index 763e2a4717..1f45b4a023 100644 --- a/docs/mfc/reference/add-class-from-typelib-wizard.md +++ b/docs/mfc/reference/add-class-from-typelib-wizard.md @@ -1,15 +1,52 @@ --- description: "Learn more about: Add Class from Typelib Wizard" title: "Add Class from Typelib Wizard" -ms.date: "05/09/2019" +ms.date: "03/10/2022" helpviewer_keywords: ["COM interfaces, adding classes"] ms.assetid: 96152afd-9374-4649-a6ab-b0fa2a5592a3 +ms.custom: devdivchpfy22 --- # Add Class from Typelib Wizard ::: moniker range=">=msvc-160" -This wizard is not available in Visual Studio 2019 and later. +The wizard creates a class for each interface you add from the selected type library. + +:::image type="content" source="../reference/media/add-class-from-typelib-wizard.png" alt-text="Screenshot of Add Class From Typelib Wizard."::: + +- **Implement interface from** + + Specifies the location of the type library. + + |Option|Description| + |------------|-----------------| + |**Registry**|Registered type libraries are listed in **Available type libraries**.| + |**File**|Provide the file location in **Location** for type libraries that aren't registered with the system.| + +- **Available type libraries** + + Lists the type libraries registered in the system. Select a type library from this list to display its interfaces in the **Interfaces** list. + +- **Location** + + Specifies the location of the type library. Under **Implement interface from**, select **File** to provide the type library file location. To browse to the location of the file, select the ellipsis button. + +- **Available Interfaces** + + Lists the interfaces in the type library selected in the **Available type libraries** list. + + |Transfer button|Description| + |---------------------|-----------------| + |**>**|Adds the selected interface in the **Interfaces** list. Unavailable if no interface is selected.| + |**>>**|Adds all the interfaces for the type library selected in the **Available type libraries** list.| + |**\<**|Removes the selected class in the **Implement interfaces** list. Unavailable if no class is selected.| + |**\<\<**|Removes all the classes in the **Implement interfaces** list. Unavailable if the **Implement interfaces** list is empty.| + +- **Implement interfaces** + + Specifies the class names to be generated from the interfaces added using the **>** or **>>** button. Click the box to select a class, and then use the up or down keys to scroll through the list. The wizard generates classes when you select **OK**. You can select only one class at a time in this box. + + To remove a class, select it in this list and then select **<**. Select **<<** to remove all classes in the **Implement interfaces** box. ::: moniker-end @@ -23,43 +60,43 @@ Use this wizard to add an MFC class from an available type library. The wizard c |Option|Description| |------------|-----------------| - |**Registry**|The type library is registered in the system. Registered type libraries are listed in **Available type libraries**.| - |**File**|The type library is not necessarily registered in the system but is contained in a file. You must provide the file location in **Location**.| + |**Registry**|Registered type libraries are listed in **Available type libraries**.| + |**File**|Provide the file location in **Location** for type libraries that aren't registered with the system.| - **Available type libraries** - Lists the type libraries currently registered in the system. Select a type library from this list to display its interfaces in the **Interfaces** list. + Lists the type libraries registered in the system. Select a type library from this list to display its interfaces in the **Interfaces** list. - **Location** - Specifies the location of the type library. If you click **File** under **Add Class From**, you can provide the location of the file containing the type library. To browse to the location of the file, click the ellipsis button. + Specifies the location of the type library. If you select **File** under **Add Class From**, you can provide the location of the file containing the type library. To browse to the location of the file, select the ellipsis button. - **Interfaces** - Lists the interfaces in the type library currently selected in the **Available type libraries** list. + Lists the interfaces in the type library selected in the **Available type libraries** list. |Transfer button|Description| |---------------------|-----------------| - |**>**|Adds the interface currently selected in the **Interfaces** list. Dimmed if no interface is selected.| - |**>>**|Adds all the interfaces in the type library currently selected in the **Available type libraries** list.| - |**\<**|Removes the class currently selected in the **Generated classes** list. Dimmed if no class is currently selected in the **Generated classes** list.| - |**\<\<**|Removes all the classes in the **Generated classes** list. Dimmed if the **Generated classes** list is empty.| + |**>**|Adds the interface selected in the **Interfaces** list. Unavailable if no interface is selected.| + |**>>**|Adds all the interfaces in the type library selected in the **Available type libraries** list.| + |**\<**|Removes the class selected in the **Generated classes** list. Unavailable if no class is selected in the **Generated classes** list.| + |**\<\<**|Removes all the classes in the **Generated classes** list. Unavailable if the **Generated classes** list is empty.| - **Generated classes** - Specifies the class names to be generated from the interfaces added using the **>** or **>>** button. You can click this box to select a class, and then use the up or down keys to scroll through the list, viewing each class name in the **Class** box and file name in the **File** box that the wizard generates when you click **Finish**. You can select only one class at a time in this box. + Specifies the class names to be generated from the interfaces added using the **>** or **>>** button. Click the box to select a class, and then use the up or down keys to scroll through the list, viewing each class name in the **Class** box and file name in the **File** box that the wizard generates when you select **Finish**. You can select only one class at a time in this box. - You can remove a class by selecting it in this list and clicking **<**. You do not need to select a class in the Generated classes box to remove all classes; by clicking **<<**, you remove all classes in the **Generated classes** box. + To remove a class, select it in this list and then select **<**. Select **<<** to remove all classes in the **Generated classes** box. - **Class** - Specifies the name of the class selected in the **Generated classes** box that the wizard adds when you click **Finish**. You can edit the name in the **Class** box. + Specifies the name of the class selected in the **Generated classes** box that the wizard adds when you select **Finish**. You can edit the name in the **Class** box. - **File** - Sets the name of the header file for the new class. By default, this name is based on the name you provide in **Generated classes**. Click the ellipsis button to save the file name to the location of your choice, or to append the class declaration to an existing file. If you choose an existing file, the wizard will not save it to the selected location until you click **Finish** in the wizard. + Sets the name of the header file for the new class. By default, this name is based on the name you provide in **Generated classes**. Select the ellipsis button to save the file name to the location of your choice, or to append the class declaration to an existing file. If you choose an existing file, the wizard won't save it to the selected location until you select **Finish** in the wizard. - The wizard does not overwrite a file. If you select the name of an existing file, when you click **Finish**, the wizard prompts you to indicate whether the class declaration should be appended to the contents of the file. Click **Yes** to append the file; click **No** to return to the wizard and specify another file name. + The wizard doesn't overwrite a file. If you select the name of an existing file, when you select **Finish**, the wizard prompts you to indicate whether the class declaration should be appended to the contents of the file. Select **Yes** to append the file; select **No** to return to the wizard and specify another file name. ::: moniker-end diff --git a/docs/mfc/reference/add-idl-mfc-method-wizard.md b/docs/mfc/reference/add-idl-mfc-method-wizard.md new file mode 100644 index 0000000000..4a8592c7e2 --- /dev/null +++ b/docs/mfc/reference/add-idl-mfc-method-wizard.md @@ -0,0 +1,144 @@ +--- +description: "Learn more about: Use the Microsoft Visual Studio Add IDL MFC wizard to add a method to an IDL interface in your MFC or ATL project" +title: "Add an IDL MFC method" +ms.date: "04/01/2022" +f1_keywords: ["vc.codewiz.method.overview", "vc.codewiz.method.idlattrib"] +helpviewer_keywords: ["add IDL MFC method wizard [C++]", "IDL MFC methods [C++], adding", "methods [C++], adding using wizards", "IDL attributes, add an IDL MFC method wizard"] +ms.custom: devdivchpfy22 +--- + +# Add an IDL MFC method + +The **Add IDL MFC Method** wizard adds a method to an Interface Definition Library (IDL) interface defined in your Microsoft Framework Class (MFC) project. If the project contains a class associated with the interface, the wizard also adds the method to the class. + +To use this wizard, you must be in an MFC Project, ActiveX project, or an ATL project that supports MFC. For example, if you have a Microsoft ActiveX control project, you can use the following procedure to add a method to an IDL interface in the solution. + +This wizard differs from the [Add Method](../../ide/adding-a-method-visual-cpp.md) wizard (which adds a method to an IDL interface) in the following ways: + +- It's specific to MFC, ActiveX, or ATL projects that support MFC. For ATL projects that don't support MFC, only the **Add Method** wizard is available. +- It adds the following entries if a Dispatch map is found in the project: + + ```cpp + BEGIN_DISPATCH_MAP(CMFCApplication2Doc, CDocument) + DISP_FUNCTION_ID(CMFCApplication2Doc, "methodName", dispidmethodName, internalName, VT_EMPTY, VTS_NONE) + END_DISPATCH_MAP() + ``` + +- It generates the following associated method implementation: + + ```cpp + void CMFCApplication2Doc::internalName() + { + AFX_MANAGE_STATE(AfxGetAppModuleState()); + // TODO: Add your dispatch handler code here + } + ``` + +## Add a method to an interface + +1. On the **View** menu, select **Class View**. + +1. In **Class View**, expand the project node to display the interface to which you want to add the method. + +1. Right-click the name of the interface. + +1. On the shortcut menu, select **Add** and then select **Add Method**. + +1. In the **Add IDL MFC Method** wizard, provide information about the method. + +1. Select **OK** to add the method. + +### UI element list + +The following section describes the Add IDL MFC Method wizard UI: + +:::image type="content" source="../reference/media/add-idl-mfc-method-wizard.png" alt-text="Wizard UI. Method name:DoClick, Internal name:DoClick, Return type:void, Method type:custom, Parameters:long l, char C, Attributes id:1."::: + +- **Method name** + + Set the name for the method. The following table describes the method name options depending on the kind of interface: + + |Interface kind|Method name| + |--------------------|-----------------| + |ATL dual interface, custom interface, and local custom interface|Provide your own method name.| + |MFC dispinterface|Provide your own method name or select a suggested method name from the list. If you select a name from the list, the appropriate return type appears in **Return type**, and can't be changed.| + |MFC ActiveX control dispinterface|Provide your own method name or select one of the stock methods: [DoClick](../reference/colecontrol-class.md#doclick) or [Refresh](../reference/colecontrol-class.md#refresh). For more information about stock methods, see [MFC ActiveX controls: Adding stock methods](../mfc-activex-controls-adding-stock-methods.md).| + +- **Internal name** + + Only available when **Method type** is **custom**. **Internal name** is the name that will be used in the dispatch map, the header (.h) file, and the implementation (.cpp) file. By default, this name is the same as **Method name**. It's added to the MFC dispinterface. + + If you're adding the method to an MFC or MFC ActiveX control dispinterface, you can change the method name as described by the following table: + + |Interface type|Internal name| + |--------------------|-----------------| + |ATL dual interface, custom interface, and local custom interface|Not available.| + |MFC dispinterface|Set to the method name by default. You can edit the internal name.| + |MFC ActiveX control dispinterface|You can set the internal name only for custom methods. Stock methods don't use an internal name.| + +- **Return type** + + The data type returned by the method. The standard return type for interface methods is `HRESULT`. + + If the interface is a dual interface or a custom interface, only the `HRESULT` return type is allowed. + + You can set the data type according to the kind of interface the method is being added to, as described in the following table: + + |Interface kind|Return type| + |--------------------|-----------------| + |Dual interface|`HRESULT`. Unchangeable.| + |Custom interface|`HRESULT`. Unchangeable.| + |Local custom interface|Provide your own return type or select one from the list.| + |Dispinterface|Provide your own return type or select one from the list.| + |MFC ActiveX control dispinterface|If you implement a stock method, the return type is set to the appropriate value and is unchangeable. If you select a method from the **Method name** list, and select **Custom** under **Select method type**, select a return type from the list.| + +- **Method type** + + Available only for MFC ActiveX controls. Unavailable if you provided a method name in **Method name** rather than selecting a method from the list. + + If you select one of the methods in the **Method name** list, in the **Method type** drop-down select either the **Stock** or **Custom** implementation. The selection of the method affects the return type and method implementation that the wizard provides, as described in the following table: + + |Method type|Description| + |-----------------|-----------------| + |**Stock**|The default. Inserts the default implementation of the method selected in the **Method name** list. **Return type** is unchangeable if you select **Stock**.| + |**Custom**|You provide a custom implementation for the method selected in **Method name**. You can provide your own return type or select one from the **Return type** list.| + +- **Parameters** + + Displays the method's parameters, modifiers, and types. The wizard updates the **Parameters** list as you add parameters. + +- **+** + + Add a parameter. In **Parameters**, type the parameter type, name, and any modifiers. For example, `int x`, and choose **OK**. + + If you don't provide a parameter name, the wizard ignores any **Parameter type** selections; and for ATL projects, the parameter attributes are also ignored. + +- **x** + + Removes the selected parameter from the **Parameters** list. + +- **Pencil icon** + + Edit the selected parameter. + +- **`id`** + + Sets the numeric ID that identifies the method. For more information, see [`id`](/windows/win32/midl/id) in the [MIDL reference](/windows/win32/midl/midl-language-reference). + +- **`call_as`** + + Specifies the name of the remote method to map to this local method. For more information, see [`call_as`](/windows/win32/midl/call-as) in the [MIDL reference](/windows/win32/midl/midl-language-reference). + +- **`helpcontext`** + + Specifies a context ID that lets the user view information about this method in the Help file. For more information, see [`helpcontext`](/windows/win32/Midl/helpcontext) in the [MIDL reference](/windows/win32/midl/midl-language-reference). + +- **`helpstring`** + + Specifies a text that describes the associated element. By default its *Method name*. For more information, see [helpstring](/windows/win32/Midl/helpstring) in the [MIDL reference](/windows/win32/midl/midl-language-reference). + +## See also + +[Add method wizard](../../ide/adding-a-method-visual-cpp.md)\ +[Add an IDL method wizard](../../ide/add-interface-definition-library-method-wizard.md)\ +[MFC wizards and dialog boxes](mfc-wizards-and-dialog-boxes.md) \ No newline at end of file diff --git a/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md b/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md new file mode 100644 index 0000000000..5ac27990ea --- /dev/null +++ b/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md @@ -0,0 +1,174 @@ +--- +description: "Learn more about: Use the Microsoft Visual Studio Add IDL MFC property wizard to add a property to an IDL interface in your MFC or ATL project" +title: "Add an IDL MFC property" +ms.date: "04/14/2022" +f1_keywords: ["vc.codewiz.prop.overview"] +helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "add property wizard", "stock properties, about stock properties", "stock properties"] +ms.custom: devdivchpfy22 +--- + +# Add an IDL MFC property + +The **Add IDL MFC Property** wizard adds a property to an Interface Definition Library (IDL) interface defined in your Microsoft Framework Class (MFC) project. + +To use this wizard, you must be in an MFC Project, ActiveX project, or an ATL project that supports MFC. For example, if you have a Microsoft ActiveX control project, you can use the following procedure to add a property to an IDL interface in the solution. + +## Add an IDL MFC property to your interface + +1. On the **View** menu, select **Class View**. + +1. In the [Class View](/visualstudio/ide/viewing-the-structure-of-code) pane, right-click the name of the interface to which you want to add the property. + + > [!NOTE] + > You can also add properties to dispinterfaces, which, unless the project is attributed, are nested within the library node. + +1. From the shortcut menu, choose **Add** > **Add Property**. + +1. In the **Add IDL MFC property** wizard, provide the information to create the property. + +1. Select **OK** to add the property. + +For MFC dispinterfaces: + +- If you select **Member variable** as the implementation type, a method and a variable are added to the class that implements it. +- If you select **Get/Set methods** as the implementation type, two methods are added to the class that implements it. + +## User interface element list + +The following section describes the **Add IDL MFC Property** wizard: + +:::image type="content" source="../reference/media/add-interface-definition-library-mfc-property-wizard.png" alt-text="Screenshot of Add IDL MFC Property with two parameters: int i and char c. Property type is OLE_COLOR."::: + +- **Property name** + + Sets the name of the property. + + For MFC dispinterfaces associated with ActiveX controls, you can supply your own name or you can select a stock property name from the predefined list. If you provide your own property name, the **Stock** implementation type is unavailable. + + For more information about a description of the stock properties in the list, see [stock properties](#stock-properties). + + |Interface type|Property name options| + |--------------------|-----------------| + |ATL dual interface, custom interface, and local custom interface|Provide a property name.| + |MFC dispinterface, MFC ActiveX control dispinterface|Provide a property name or select a stock property from the list.

If you select a property from the list, the appropriate value appears in the **Property type** box. You can change this type, depending on the **Implementation type** selection.| + +- **Property type** + + Sets the type of property you're adding. + + For MFC dispinterfaces, provide your own type or select from the predefined list. If you provide a stock implementation of a property, **Property type** is the stock type and can't be changed. + +- **Variable name** + + Sets the name of the member variable with which the property is associated. + + By default, the variable name is `m_`*PropertyName*. You can edit this name. + + This field is only visible for MFC dispinterfaces and if you specify **Member variable** under **Implementation type**. + +- **Notification function** + + Sets the name of the notification function called if the property changes. + + By default, the name of the notification function is `On`*PropertyName*`Changed`. You can edit this name. + + This field is only visible for MFC dispinterfaces and if you specify **Member variable** under **Implementation type**. + +- **Get function** + + Sets the name of the function to get the property. + + By default, the name of the `Get` function is `Get`*PropertyName*. You can edit this name. + + If you delete the name, the function [GetNotSupported](../../mfc/reference/colecontrol-class.md#getnotsupported) is inserted into the interface dispatch map. + + This field is only visible for MFC dispinterfaces and if you specify **Get/Set methods** under **Implementation type**. + +- **Set function** + + Sets the name of the function to set the property. + + By default, the name of the `Set` function is `Set`*PropertyName*. You can edit this name. + + If you delete the name, the function [SetNotSupported](../../mfc/reference/colecontrol-class.md#setnotsupported) is inserted into the interface dispatch map. + + This field is only visible for MFC dispinterfaces and if you specify **Get/Set methods** under **Implementation type**. + +- **Implementation type** + + Specifies how to implement the property you're adding. + + Only available for MFC dispinterfaces. + + |Implementation type|Description| + |-------------------------|-----------------| + |**Stock**|Specifies a default implementation for the property selected in **Property name**. For more information, see [stock properties](#stock-properties).
If you specify **Stock**, then **Property type**, **Parameter type**, and **Parameter name** are dimmed.| + |**Member variable**|Adds the property as a member variable.
You can add custom properties or most stock properties as member variables.
Provides default names under **Variable name** and **Notification function**. You can edit this name.
You can't specify **Member variable** for the `Caption`, `hWnd`, or `Text` properties.| + |**Get/Set methods**|Specifies the property is added as `Get`*PropertyName* and `Set`*PropertyName* functions by default. These names appear under **Get function** and **Set function**.
You can change the default **Property type**, which passes a value for the Get function.
You can specify parameters for the `Get` and `Set` functions.| + +- **Default property** + + Sets the property as the default for the interface. + + An interface can have only one default property. + + Once you specify the default property, this checkbox is unavailable for any other properties that you add to the interface. + Only available for an MFC dispinterface. + +- **Parameters** + + Displays the method's parameters and its types. + +- **+** + + Adds a parameter. In **Parameters**, type the parameter type and name and choose **OK**. For example, `int x` + +- **x** + + Removes the selected parameter from the **Parameters** list. + +- **Pencil icon** + + Edits the selected parameter. + +- **id** + + Sets the numerical ID that identifies the property. + + This option isn't available for properties of custom interfaces. + For more information, see [`id`](/windows/win32/Midl/id) in the *MIDL Reference*. + +- **helpcontext** + + Specifies a context ID that lets the user view information about this property in the Help file. + + For more information, see [`helpcontext`](/windows/win32/Midl/helpcontext) in the *MIDL Reference*. + +- **helpstring** + + Specifies a character string that's used to describe the element to which it applies. By default, it's **`property`** *Property name*. + + For more information, see [`helpstring`](/windows/win32/Midl/helpstring) in the *MIDL Reference*. + +### Stock properties + +If you're adding a property to an MFC dispinterface, you can choose one of the following stock properties from the **Property name** dropdown list: + +|Property name|Description| +|-------------------|-----------------| +|`Appearance`|Returns or sets a value that determines the appearance of the control.
The control's `Appearance` property can include or omit three-dimensional display effects. This property is an ambient read/write property.| +|`BackColor`|Returns or sets the control's ambient `BackColor` property to either a palette (RGB) color or a predefined system color.
By default, its value corresponds to the foreground color of the control's container.
This property is an ambient read/write property.| +|`BorderStyle`|Returns or sets the border style for a control.
This property is a read/write property.| +|`Caption`|Returns or sets the control's `Caption` property.
The caption is the title of the window. `Caption` has no **Member variable** implementation type.| +|`Enabled`|Returns or sets the control's `Enabled` property.
An enabled control can respond to user-generated events.| +|`Font`|Returns or sets the control's ambient font.
`Null` if the control has no font.| +|`ForeColor`|Returns or sets the control's ambient `ForeColor` property.| +|`hWnd`|Returns or sets the control's `hWnd` property.
Has no **Member variable** implementation type.| +|`ReadyState`|Returns or sets the control's `ReadyState` property.
A control can be uninitialized, initialized, loading, interactive, or complete.
For more information, see [READYSTATE](/previous-versions/aa768362\(v=vs.85\)) in the *Internet SDK*.| +|`Text`|Returns or sets the text contained in a control.
Has no **Member variable** implementation type.| + +## See Also + +[Add Property](../../ide/adding-a-property-visual-cpp.md) + +[Add IDL Property](../../ide/add-interface-definition-library-property-wizard.md) diff --git a/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md b/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md index 1d5d59a273..db0802eea7 100644 --- a/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md +++ b/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md @@ -1,32 +1,34 @@ --- -description: "Learn more about: Adding an MFC Class from a Type Library" -title: "Adding an MFC Class from a Type Library" -ms.date: "11/04/2016" +description: "Learn more about: Adding an MFC class from a type library using a Microsoft Visual Studio wizard" +title: "Add an MFC class from a type Library" +ms.date: 04/14/2022 helpviewer_keywords: ["classes [MFC], adding MFC", "MFC, adding classes from type libraries", "type libraries, adding MFC classes from"] -ms.assetid: aba40476-3cfb-47af-990e-ae2e9e0d79cf +ms.custom: devdivchpfy22 --- -# Adding an MFC Class from a Type Library +# Add an MFC class from a type library -Use this wizard to create an MFC class from an interface in an available type library. You can add an MFC class to an [MFC application](../../mfc/reference/creating-an-mfc-application.md), an [MFC DLL](../../mfc/reference/creating-an-mfc-dll-project.md), or an [MFC ActiveX control](../../mfc/reference/creating-an-mfc-activex-control.md). +Use this wizard to create an MFC class from an interface in a type library. You can add an MFC class to an [MFC application](../../mfc/reference/creating-an-mfc-application.md), an [MFC DLL](../../mfc/reference/creating-an-mfc-dll-project.md), or an [MFC ActiveX control](../../mfc/reference/creating-an-mfc-activex-control.md). > [!NOTE] -> You do not need to create your MFC project with Automation enabled to add a class from a type library. +> You don't need to create your MFC project with Automation enabled to add a class from a type library. -A type library contains a binary description of the interfaces exposed by a component, defining the methods along with their parameters and return types. Your type library must be registered for it to appear in the **Available type libraries** list in the Add Class from Typelib Wizard. +A type library contains a binary description of the interfaces exposed by a component, defining the methods along with their parameters and return types. Your type library must be registered for it to appear in the **Available type libraries** list in the wizard. -### To add an MFC class from a type library +## Add an MFC class from a type library 1. In either **Solution Explorer** or [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the name of the project to which you want to add the class. -1. From the shortcut menu, click **Add**, and then click **Add Class**. +1. From the shortcut menu, select **Add** > **New Item**. -1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the Templates pane, click **MFC Class from Typelib**, and then click **Open** to display the [Add Class from Typelib Wizard](../../mfc/reference/add-class-from-typelib-wizard.md). +1. In the **Add New Item** dialog, select **Installed** packages and then select **Visual C++**. -In the wizard, you can add more than one class in a type library. Likewise, you can add classes from more than one type library in a single wizard session. +1. In the Templates pane, select **MFC Class from Typelib**, and then select **Add** to display the [Add Class from Typelib Wizard](../../mfc/reference/add-class-from-typelib-wizard.md). -The wizard creates an MFC class, derived from [COleDispatchDriver](../../mfc/reference/coledispatchdriver-class.md), for each interface you add from the selected type library. `COleDispatchDriver` implements the client side of OLE automation. +Using the wizard, you can add more than one class in a type library. You can add classes from more than one type library in a single wizard session. + +The wizard creates an MFC class derived from [`COleDispatchDriver`](../../mfc/reference/coledispatchdriver-class.md), for each interface you add from the selected type library. `COleDispatchDriver` implements the client side of OLE automation. ## See also -[Automation Clients](../../mfc/automation-clients.md)
+[Automation Clients](../../mfc/automation-clients.md)\ [Automation Clients: Using Type Libraries](../../mfc/automation-clients-using-type-libraries.md) diff --git a/docs/mfc/reference/application-control.md b/docs/mfc/reference/application-control.md index b858a4d41b..71d0ea63f2 100644 --- a/docs/mfc/reference/application-control.md +++ b/docs/mfc/reference/application-control.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Application Control" title: "Application Control" -ms.date: "11/04/2016" +description: "Learn more about: Application Control" +ms.date: 11/04/2016 helpviewer_keywords: ["application control [MFC]"] -ms.assetid: c1f69f15-e0fe-4515-9f36-d63d31869deb --- # Application Control @@ -67,7 +66,7 @@ Call this function to access the current `COleMessageFilter`-derived object, jus ### Example [!code-cpp[NVC_MFCAutomation#3](../../mfc/codesnippet/cpp/application-control_2.cpp)] - +  [!code-cpp[NVC_MFCAutomation#4](../../mfc/codesnippet/cpp/application-control_3.cpp)] ### Requirements @@ -258,7 +257,7 @@ Nonzero if the server class is successfully registered; otherwise 0. Most applications can use `COleTemplateServer::Register` to register the application's document types. If your application's system-registry format does not fit the typical pattern, you can use `AfxOleRegisterServerClass` for more control. -The registry consists of a set of keys and values. The *rglpszRegister* and *rglpszOverwrite* arguments are arrays of pointers to strings, each consisting of a key and a value separated by a **NULL** character ( `'\0'`). Each of these strings can have replaceable parameters whose places are marked by the character sequences *%1* through *%5*. +The registry consists of a set of keys and values. The *rglpszRegister* and *rglpszOverwrite* arguments are arrays of pointers to strings, each consisting of a key and a value separated by a **NULL** character (`'\0'`). Each of these strings can have replaceable parameters whose places are marked by the character sequences *%1* through *%5*. The symbols are filled in as follows: diff --git a/docs/mfc/reference/buffercommand-enumeration.md b/docs/mfc/reference/buffercommand-enumeration.md index 347d457d89..23d430be1a 100644 --- a/docs/mfc/reference/buffercommand-enumeration.md +++ b/docs/mfc/reference/buffercommand-enumeration.md @@ -11,7 +11,7 @@ Used by [CMemFile::GetBufferPtr](cmemfile-class.md#getbufferptr) to determine wh ## Syntax -``` cpp +```cpp public enum BufferCommand { bufferRead, diff --git a/docs/mfc/reference/carchive-class.md b/docs/mfc/reference/carchive-class.md index 637d0a6d48..8d8f606693 100644 --- a/docs/mfc/reference/carchive-class.md +++ b/docs/mfc/reference/carchive-class.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: CArchive Class" title: "CArchive Class" -ms.date: "11/04/2016" +description: "Learn more about: CArchive Class" +ms.date: 11/04/2016 f1_keywords: ["CArchive", "AFX/CArchive", "AFX/CArchive::CArchive", "AFX/CArchive::Abort", "AFX/CArchive::Close", "AFX/CArchive::Flush", "AFX/CArchive::GetFile", "AFX/CArchive::GetObjectSchema", "AFX/CArchive::IsBufferEmpty", "AFX/CArchive::IsLoading", "AFX/CArchive::IsStoring", "AFX/CArchive::MapObject", "AFX/CArchive::Read", "AFX/CArchive::ReadClass", "AFX/CArchive::ReadObject", "AFX/CArchive::ReadString", "AFX/CArchive::SerializeClass", "AFX/CArchive::SetLoadParams", "AFX/CArchive::SetObjectSchema", "AFX/CArchive::SetStoreParams", "AFX/CArchive::Write", "AFX/CArchive::WriteClass", "AFX/CArchive::WriteObject", "AFX/CArchive::WriteString", "AFX/CArchive::m_pDocument"] helpviewer_keywords: ["CArchive [MFC], CArchive", "CArchive [MFC], Abort", "CArchive [MFC], Close", "CArchive [MFC], Flush", "CArchive [MFC], GetFile", "CArchive [MFC], GetObjectSchema", "CArchive [MFC], IsBufferEmpty", "CArchive [MFC], IsLoading", "CArchive [MFC], IsStoring", "CArchive [MFC], MapObject", "CArchive [MFC], Read", "CArchive [MFC], ReadClass", "CArchive [MFC], ReadObject", "CArchive [MFC], ReadString", "CArchive [MFC], SerializeClass", "CArchive [MFC], SetLoadParams", "CArchive [MFC], SetObjectSchema", "CArchive [MFC], SetStoreParams", "CArchive [MFC], Write", "CArchive [MFC], WriteClass", "CArchive [MFC], WriteObject", "CArchive [MFC], WriteString", "CArchive [MFC], m_pDocument"] --- @@ -74,7 +74,7 @@ You must create a [`CFile`](../../mfc/reference/cfile-class.md) object before yo When you construct a `CArchive` object, you attach it to an object of class `CFile` (or a derived class) that represents an open file. You also specify whether the archive will be used for loading or storing. A `CArchive` object can process not only primitive types but also objects of [`CObject`](../../mfc/reference/cobject-class.md)-derived classes designed for serialization. A serializable class usually has a `Serialize` member function, and it usually uses the [`DECLARE_SERIAL`](../../mfc/reference/run-time-object-model-services.md#declare_serial) and [`IMPLEMENT_SERIAL`](../../mfc/reference/run-time-object-model-services.md#implement_serial) macros, as described under class `CObject`. -The overloaded extraction ( `>>`) and insertion ( `<<`) operators are convenient archive programming interfaces that support both primitive types and `CObject`-derived classes. +The overloaded extraction (`>>`) and insertion (`<<`) operators are convenient archive programming interfaces that support both primitive types and `CObject`-derived classes. `CArchive` also supports programming with the MFC Windows Sockets classes [`CSocket`](../../mfc/reference/csocket-class.md) and [`CSocketFile`](../../mfc/reference/csocketfile-class.md). The [`IsBufferEmpty`](#isbufferempty) member function supports that usage. @@ -310,11 +310,11 @@ You can call `MapObject` when you store to and load from the `CArchive` object. ### Example [!code-cpp[NVC_MFCSerialization#18](../../mfc/codesnippet/cpp/carchive-class_7.h)] - +  [!code-cpp[NVC_MFCSerialization#19](../../mfc/codesnippet/cpp/carchive-class_8.cpp)] - +  [!code-cpp[NVC_MFCSerialization#20](../../mfc/codesnippet/cpp/carchive-class_9.h)] - +  [!code-cpp[NVC_MFCSerialization#21](../../mfc/codesnippet/cpp/carchive-class_10.cpp)] ## `CArchive::m_pDocument` @@ -570,7 +570,7 @@ A [`CObject`](../../mfc/reference/cobject-class.md) pointer that must be safely ### Remarks -This function is normally called by the `CArchive` extraction ( `>>`) operator overloaded for a [`CObject`](../../mfc/reference/cobject-class.md) pointer. `ReadObject`, in turn, calls the `Serialize` function of the archived class. +This function is normally called by the `CArchive` extraction (`>>`) operator overloaded for a [`CObject`](../../mfc/reference/cobject-class.md) pointer. `ReadObject`, in turn, calls the `Serialize` function of the archived class. If you supply a nonzero *`pClass`* parameter, which is obtained by the [`RUNTIME_CLASS`](../../mfc/reference/run-time-object-model-services.md#runtime_class) macro, then the function verifies the run-time class of the archived object. This assumes you have used the `IMPLEMENT_SERIAL` macro in the implementation of the class. @@ -781,7 +781,7 @@ A constant pointer to the object being stored. ### Remarks -This function is normally called by the `CArchive` insertion ( `<<`) operator overloaded for `CObject`. `WriteObject`, in turn, calls the `Serialize` function of the archived class. +This function is normally called by the `CArchive` insertion (`<<`) operator overloaded for `CObject`. `WriteObject`, in turn, calls the `Serialize` function of the archived class. You must use the `IMPLEMENT_SERIAL` macro to enable archiving. `WriteObject` writes the ASCII class name to the archive. This class name is validated later during the load process. A special encoding scheme prevents unnecessary duplication of the class name for multiple objects of the class. This scheme also prevents redundant storage of objects that are targets of more than one pointer. diff --git a/docs/mfc/reference/casyncsocket-class.md b/docs/mfc/reference/casyncsocket-class.md index d68ce7630f..9d1d045acd 100644 --- a/docs/mfc/reference/casyncsocket-class.md +++ b/docs/mfc/reference/casyncsocket-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CAsyncSocket Class" title: "CAsyncSocket Class" -ms.date: "06/25/2020" +description: "Learn more about: CAsyncSocket Class" +ms.date: 06/25/2020 f1_keywords: ["CAsyncSocket", "AFXSOCK/CAsyncSocket", "AFXSOCK/CAsyncSocket::CAsyncSocket", "AFXSOCK/CAsyncSocket::Accept", "AFXSOCK/CAsyncSocket::AsyncSelect", "AFXSOCK/CAsyncSocket::Attach", "AFXSOCK/CAsyncSocket::Bind", "AFXSOCK/CAsyncSocket::Close", "AFXSOCK/CAsyncSocket::Connect", "AFXSOCK/CAsyncSocket::Create", "AFXSOCK/CAsyncSocket::Detach", "AFXSOCK/CAsyncSocket::FromHandle", "AFXSOCK/CAsyncSocket::GetLastError", "AFXSOCK/CAsyncSocket::GetPeerName", "AFXSOCK/CAsyncSocket::GetPeerNameEx", "AFXSOCK/CAsyncSocket::GetSockName", "AFXSOCK/CAsyncSocket::GetSockNameEx", "AFXSOCK/CAsyncSocket::GetSockOpt", "AFXSOCK/CAsyncSocket::IOCtl", "AFXSOCK/CAsyncSocket::Listen", "AFXSOCK/CAsyncSocket::Receive", "AFXSOCK/CAsyncSocket::ReceiveFrom", "AFXSOCK/CAsyncSocket::ReceiveFromEx", "AFXSOCK/CAsyncSocket::Send", "AFXSOCK/CAsyncSocket::SendTo", "AFXSOCK/CAsyncSocket::SendToEx", "AFXSOCK/CAsyncSocket::SetSockOpt", "AFXSOCK/CAsyncSocket::ShutDown", "AFXSOCK/CASyncSocket::Socket", "AFXSOCK/CAsyncSocket::OnAccept", "AFXSOCK/CAsyncSocket::OnClose", "AFXSOCK/CAsyncSocket::OnConnect", "AFXSOCK/CAsyncSocket::OnOutOfBandData", "AFXSOCK/CAsyncSocket::OnReceive", "AFXSOCK/CAsyncSocket::OnSend", "AFXSOCK/CAsyncSocket::m_hSocket"] helpviewer_keywords: ["CAsyncSocket [MFC], CAsyncSocket", "CAsyncSocket [MFC], Accept", "CAsyncSocket [MFC], AsyncSelect", "CAsyncSocket [MFC], Attach", "CAsyncSocket [MFC], Bind", "CAsyncSocket [MFC], Close", "CAsyncSocket [MFC], Connect", "CAsyncSocket [MFC], Create", "CAsyncSocket [MFC], Detach", "CAsyncSocket [MFC], FromHandle", "CAsyncSocket [MFC], GetLastError", "CAsyncSocket [MFC], GetPeerName", "CAsyncSocket [MFC], GetPeerNameEx", "CAsyncSocket [MFC], GetSockName", "CAsyncSocket [MFC], GetSockNameEx", "CAsyncSocket [MFC], GetSockOpt", "CAsyncSocket [MFC], IOCtl", "CAsyncSocket [MFC], Listen", "CAsyncSocket [MFC], Receive", "CAsyncSocket [MFC], ReceiveFrom", "CAsyncSocket [MFC], ReceiveFromEx", "CAsyncSocket [MFC], Send", "CAsyncSocket [MFC], SendTo", "CAsyncSocket [MFC], SendToEx", "CAsyncSocket [MFC], SetSockOpt", "CAsyncSocket [MFC], ShutDown", "CASyncSocket [MFC], Socket", "CAsyncSocket [MFC], OnAccept", "CAsyncSocket [MFC], OnClose", "CAsyncSocket [MFC], OnConnect", "CAsyncSocket [MFC], OnOutOfBandData", "CAsyncSocket [MFC], OnReceive", "CAsyncSocket [MFC], OnSend", "CAsyncSocket [MFC], m_hSocket"] -ms.assetid: cca4d5a1-aa0f-48bd-843e-ef0e2d7fc00b --- # `CAsyncSocket` Class @@ -844,7 +843,7 @@ This routine can be used on any socket in any state. It is used to get or retrie - `FIONREAD` Determine the maximum number of bytes that can be read with one `Receive` call from this socket. The *`lpArgument`* parameter points at a `DWORD` in which `IOCtl` stores the result. If this socket is of type `SOCK_STREAM`, `FIONREAD` returns the total amount of data which can be read in a single `Receive`; this is normally the same as the total amount of data queued on the socket. If this socket is of type `SOCK_DGRAM`, `FIONREAD` returns the size of the first datagram queued on the socket. -- `SIOCATMARK` Determine whether all out-of-band data has been read. This applies only to a socket of type `SOCK_STREAM` which has been configured for in-line reception of any out-of-band data ( `SO_OOBINLINE`). If no out-of-band data is waiting to be read, the operation returns nonzero. Otherwise it returns 0, and the next `Receive` or `ReceiveFrom` performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the `SIOCATMARK` operation to determine whether any data remains. If there is any normal data preceding the "urgent" (out-of-band) data, it will be received in order. (Note that a `Receive` or `ReceiveFrom` will never mix out-of-band and normal data in the same call.) The *`lpArgument`* parameter points at a `DWORD` in which `IOCtl` stores the result. +- `SIOCATMARK` Determine whether all out-of-band data has been read. This applies only to a socket of type `SOCK_STREAM` which has been configured for in-line reception of any out-of-band data (`SO_OOBINLINE`). If no out-of-band data is waiting to be read, the operation returns nonzero. Otherwise it returns 0, and the next `Receive` or `ReceiveFrom` performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the `SIOCATMARK` operation to determine whether any data remains. If there is any normal data preceding the "urgent" (out-of-band) data, it will be received in order. (Note that a `Receive` or `ReceiveFrom` will never mix out-of-band and normal data in the same call.) The *`lpArgument`* parameter points at a `DWORD` in which `IOCtl` stores the result. This function is a subset of `ioctl()` as used in Berkeley sockets. In particular, there is no command which is equivalent to `FIOASYNC`, while `SIOCATMARK` is the only socket-level command which is supported. diff --git a/docs/mfc/reference/cbasekeyframe-class.md b/docs/mfc/reference/cbasekeyframe-class.md index 03a3f49563..40785c05ad 100644 --- a/docs/mfc/reference/cbasekeyframe-class.md +++ b/docs/mfc/reference/cbasekeyframe-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CBaseKeyFrame Class" title: "CBaseKeyFrame Class" -ms.date: "11/04/2016" +description: "Learn more about: CBaseKeyFrame Class" +ms.date: 11/04/2016 f1_keywords: ["CBaseKeyFrame", "AFXANIMATIONCONTROLLER/CBaseKeyFrame", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::CBaseKeyFrame", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::AddToStoryboard", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::GetAnimationKeyframe", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::IsAdded", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::IsKeyframeAtOffset", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::m_bAdded", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::m_bIsKeyframeAtOffset", "AFXANIMATIONCONTROLLER/CBaseKeyFrame::m_keyframe"] helpviewer_keywords: ["CBaseKeyFrame [MFC], CBaseKeyFrame", "CBaseKeyFrame [MFC], AddToStoryboard", "CBaseKeyFrame [MFC], GetAnimationKeyframe", "CBaseKeyFrame [MFC], IsAdded", "CBaseKeyFrame [MFC], IsKeyframeAtOffset", "CBaseKeyFrame [MFC], m_bAdded", "CBaseKeyFrame [MFC], m_bIsKeyframeAtOffset", "CBaseKeyFrame [MFC], m_keyframe"] -ms.assetid: 285a2eff-e7c4-43be-b5aa-737727e6866d --- # CBaseKeyFrame Class @@ -115,7 +114,7 @@ BOOL IsAdded() const; ### Return Value -TRUE if a keyframe is added to a storyboard; otehrwise FALSE. +TRUE if a keyframe is added to a storyboard; otherwise FALSE. ### Remarks diff --git a/docs/mfc/reference/cbasepane-class.md b/docs/mfc/reference/cbasepane-class.md index b2c88c5ae6..b535d8ccdd 100644 --- a/docs/mfc/reference/cbasepane-class.md +++ b/docs/mfc/reference/cbasepane-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CBasePane Class" title: "CBasePane Class" -ms.date: "11/06/2018" +description: "Learn more about: CBasePane Class" +ms.date: 11/06/2018 f1_keywords: ["CBasePane", "AFXBASEPANE/CBasePane", "AFXBASEPANE/CBasePane::AccNotifyObjectFocusEvent", "AFXBASEPANE/CBasePane::AddPane", "AFXBASEPANE/CBasePane::AdjustDockingLayout", "AFXBASEPANE/CBasePane::AdjustLayout", "AFXBASEPANE/CBasePane::CalcFixedLayout", "AFXBASEPANE/CBasePane::CanAcceptPane", "AFXBASEPANE/CBasePane::CanAutoHide", "AFXBASEPANE/CBasePane::CanBeAttached", "AFXBASEPANE/CBasePane::CanBeClosed", "AFXBASEPANE/CBasePane::CanBeDocked", "AFXBASEPANE/CBasePane::CanBeResized", "AFXBASEPANE/CBasePane::CanBeTabbedDocument", "AFXBASEPANE/CBasePane::CanFloat", "AFXBASEPANE/CBasePane::CanFocus", "AFXBASEPANE/CBasePane::CopyState", "AFXBASEPANE/CBasePane::CreateDefaultMiniframe", "AFXBASEPANE/CBasePane::CreateEx", "AFXBASEPANE/CBasePane::DockPane", "AFXBASEPANE/CBasePane::DockPaneUsingRTTI", "AFXBASEPANE/CBasePane::DockToFrameWindow", "AFXBASEPANE/CBasePane::DoesAllowDynInsertBefore", "AFXBASEPANE/CBasePane::EnableDocking", "AFXBASEPANE/CBasePane::EnableGripper", "AFXBASEPANE/CBasePane::FloatPane", "AFXBASEPANE/CBasePane::get_accHelpTopic", "AFXBASEPANE/CBasePane::get_accSelection", "AFXBASEPANE/CBasePane::GetCaptionHeight", "AFXBASEPANE/CBasePane::GetControlBarStyle", "AFXBASEPANE/CBasePane::GetCurrentAlignment", "AFXBASEPANE/CBasePane::GetDockingMode", "AFXBASEPANE/CBasePane::GetDockSiteFrameWnd", "AFXBASEPANE/CBasePane::GetEnabledAlignment", "AFXBASEPANE/CBasePane::GetMFCStyle", "AFXBASEPANE/CBasePane::GetPaneIcon", "AFXBASEPANE/CBasePane::GetPaneRow", "AFXBASEPANE/CBasePane::GetPaneStyle", "AFXBASEPANE/CBasePane::GetParentDockSite", "AFXBASEPANE/CBasePane::GetParentMiniFrame", "AFXBASEPANE/CBasePane::GetParentTabbedPane", "AFXBASEPANE/CBasePane::GetParentTabWnd", "AFXBASEPANE/CBasePane::GetRecentVisibleState", "AFXBASEPANE/CBasePane::HideInPrintPreviewMode", "AFXBASEPANE/CBasePane::InsertPane", "AFXBASEPANE/CBasePane::IsAccessibilityCompatible", "AFXBASEPANE/CBasePane::IsAutoHideMode", "AFXBASEPANE/CBasePane::IsDialogControl", "AFXBASEPANE/CBasePane::IsDocked", "AFXBASEPANE/CBasePane::IsFloating", "AFXBASEPANE/CBasePane::IsHorizontal", "AFXBASEPANE/CBasePane::IsInFloatingMultiPaneFrameWnd", "AFXBASEPANE/CBasePane::IsMDITabbed", "AFXBASEPANE/CBasePane::IsPaneVisible", "AFXBASEPANE/CBasePane::IsPointNearDockSite", "AFXBASEPANE/CBasePane::IsResizable", "AFXBASEPANE/CBasePane::IsRestoredFromRegistry", "AFXBASEPANE/CBasePane::IsTabbed", "AFXBASEPANE/CBasePane::IsVisible", "AFXBASEPANE/CBasePane::LoadState", "AFXBASEPANE/CBasePane::MoveWindow", "AFXBASEPANE/CBasePane::OnAfterChangeParent", "AFXBASEPANE/CBasePane::OnBeforeChangeParent", "AFXBASEPANE/CBasePane::OnDrawCaption", "AFXBASEPANE/CBasePane::OnMovePaneDivider", "AFXBASEPANE/CBasePane::OnPaneContextMenu", "AFXBASEPANE/CBasePane::OnRemoveFromMiniFrame", "AFXBASEPANE/CBasePane::OnSetAccData", "AFXBASEPANE/CBasePane::PaneFromPoint", "AFXBASEPANE/CBasePane::RecalcLayout", "AFXBASEPANE/CBasePane::RemovePaneFromDockManager", "AFXBASEPANE/CBasePane::SaveState", "AFXBASEPANE/CBasePane::SelectDefaultFont", "AFXBASEPANE/CBasePane::SetControlBarStyle", "AFXBASEPANE/CBasePane::SetDockingMode", "AFXBASEPANE/CBasePane::SetPaneAlignment", "AFXBASEPANE/CBasePane::SetPaneStyle", "AFXBASEPANE/CBasePane::SetWindowPos", "AFXBASEPANE/CBasePane::ShowPane", "AFXBASEPANE/CBasePane::StretchPane", "AFXBASEPANE/CBasePane::UndockPane", "AFXBASEPANE/CBasePane::DoPaint"] helpviewer_keywords: ["CBasePane [MFC], AccNotifyObjectFocusEvent", "CBasePane [MFC], AddPane", "CBasePane [MFC], AdjustDockingLayout", "CBasePane [MFC], AdjustLayout", "CBasePane [MFC], CalcFixedLayout", "CBasePane [MFC], CanAcceptPane", "CBasePane [MFC], CanAutoHide", "CBasePane [MFC], CanBeAttached", "CBasePane [MFC], CanBeClosed", "CBasePane [MFC], CanBeDocked", "CBasePane [MFC], CanBeResized", "CBasePane [MFC], CanBeTabbedDocument", "CBasePane [MFC], CanFloat", "CBasePane [MFC], CanFocus", "CBasePane [MFC], CopyState", "CBasePane [MFC], CreateDefaultMiniframe", "CBasePane [MFC], CreateEx", "CBasePane [MFC], DockPane", "CBasePane [MFC], DockPaneUsingRTTI", "CBasePane [MFC], DockToFrameWindow", "CBasePane [MFC], DoesAllowDynInsertBefore", "CBasePane [MFC], EnableDocking", "CBasePane [MFC], EnableGripper", "CBasePane [MFC], FloatPane", "CBasePane [MFC], get_accHelpTopic", "CBasePane [MFC], get_accSelection", "CBasePane [MFC], GetCaptionHeight", "CBasePane [MFC], GetControlBarStyle", "CBasePane [MFC], GetCurrentAlignment", "CBasePane [MFC], GetDockingMode", "CBasePane [MFC], GetDockSiteFrameWnd", "CBasePane [MFC], GetEnabledAlignment", "CBasePane [MFC], GetMFCStyle", "CBasePane [MFC], GetPaneIcon", "CBasePane [MFC], GetPaneRow", "CBasePane [MFC], GetPaneStyle", "CBasePane [MFC], GetParentDockSite", "CBasePane [MFC], GetParentMiniFrame", "CBasePane [MFC], GetParentTabbedPane", "CBasePane [MFC], GetParentTabWnd", "CBasePane [MFC], GetRecentVisibleState", "CBasePane [MFC], HideInPrintPreviewMode", "CBasePane [MFC], InsertPane", "CBasePane [MFC], IsAccessibilityCompatible", "CBasePane [MFC], IsAutoHideMode", "CBasePane [MFC], IsDialogControl", "CBasePane [MFC], IsDocked", "CBasePane [MFC], IsFloating", "CBasePane [MFC], IsHorizontal", "CBasePane [MFC], IsInFloatingMultiPaneFrameWnd", "CBasePane [MFC], IsMDITabbed", "CBasePane [MFC], IsPaneVisible", "CBasePane [MFC], IsPointNearDockSite", "CBasePane [MFC], IsResizable", "CBasePane [MFC], IsRestoredFromRegistry", "CBasePane [MFC], IsTabbed", "CBasePane [MFC], IsVisible", "CBasePane [MFC], LoadState", "CBasePane [MFC], MoveWindow", "CBasePane [MFC], OnAfterChangeParent", "CBasePane [MFC], OnBeforeChangeParent", "CBasePane [MFC], OnDrawCaption", "CBasePane [MFC], OnMovePaneDivider", "CBasePane [MFC], OnPaneContextMenu", "CBasePane [MFC], OnRemoveFromMiniFrame", "CBasePane [MFC], OnSetAccData", "CBasePane [MFC], PaneFromPoint", "CBasePane [MFC], RecalcLayout", "CBasePane [MFC], RemovePaneFromDockManager", "CBasePane [MFC], SaveState", "CBasePane [MFC], SelectDefaultFont", "CBasePane [MFC], SetControlBarStyle", "CBasePane [MFC], SetDockingMode", "CBasePane [MFC], SetPaneAlignment", "CBasePane [MFC], SetPaneStyle", "CBasePane [MFC], SetWindowPos", "CBasePane [MFC], ShowPane", "CBasePane [MFC], StretchPane", "CBasePane [MFC], UndockPane", "CBasePane [MFC], DoPaint"] -ms.assetid: 8163dd51-d7c7-4def-9c74-61f8ecdfad82 --- # CBasePane Class @@ -80,7 +79,7 @@ class CBasePane : public CWnd |[CBasePane::GetMFCStyle](#getmfcstyle)|Returns the pane styles specific to MFC.| |[CBasePane::GetPaneIcon](#getpaneicon)|Returns a handle to the pane icon.| |`CBasePane::GetPaneRect`|Used internally.| -|[CBasePane::GetPaneRow](#getpanerow)|Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md)object where the pane is docked.| +|[CBasePane::GetPaneRow](#getpanerow)|Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md) object where the pane is docked.| |[CBasePane::GetPaneStyle](#getpanestyle)|Returns the pane style.| |[CBasePane::GetParentDockSite](#getparentdocksite)|Returns a pointer to the parent dock site.| |[CBasePane::GetParentMiniFrame](#getparentminiframe)|Returns a pointer to the parent mini-frame window.| @@ -892,7 +891,7 @@ By setting *m_dockMode* or overriding `GetDockingMode` you can control the docki ## CBasePane::GetDockSiteFrameWnd -Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md)object where the pane is docked. +Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md) object where the pane is docked. ``` virtual CWnd* GetDockSiteFrameWnd() const; @@ -967,7 +966,7 @@ The default implementation calls [CWnd::GetIcon](../../mfc/reference/cwnd-class. ## CBasePane::GetPaneRow -Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md)object where the pane is docked. +Returns a pointer to the [CDockingPanesRow](../../mfc/reference/cdockingpanesrow-class.md) object where the pane is docked. ``` CDockingPanesRow* GetPaneRow(); diff --git a/docs/mfc/reference/cbrush-class.md b/docs/mfc/reference/cbrush-class.md index f68826bae8..e9173b9a1b 100644 --- a/docs/mfc/reference/cbrush-class.md +++ b/docs/mfc/reference/cbrush-class.md @@ -4,9 +4,8 @@ title: "CBrush Class" ms.date: "11/04/2016" f1_keywords: ["CBrush", "AFXWIN/CBrush", "AFXWIN/CBrush::CBrush", "AFXWIN/CBrush::CreateBrushIndirect", "AFXWIN/CBrush::CreateDIBPatternBrush", "AFXWIN/CBrush::CreateHatchBrush", "AFXWIN/CBrush::CreatePatternBrush", "AFXWIN/CBrush::CreateSolidBrush", "AFXWIN/CBrush::CreateSysColorBrush", "AFXWIN/CBrush::FromHandle", "AFXWIN/CBrush::GetLogBrush"] helpviewer_keywords: ["CBrush [MFC], CBrush", "CBrush [MFC], CreateBrushIndirect", "CBrush [MFC], CreateDIBPatternBrush", "CBrush [MFC], CreateHatchBrush", "CBrush [MFC], CreatePatternBrush", "CBrush [MFC], CreateSolidBrush", "CBrush [MFC], CreateSysColorBrush", "CBrush [MFC], FromHandle", "CBrush [MFC], GetLogBrush"] -ms.assetid: e5ef2c62-dd95-4973-9090-f52f605900e1 --- -# CBrush Class +# `CBrush` Class Encapsulates a Windows graphics device interface (GDI) brush. @@ -22,26 +21,26 @@ class CBrush : public CGdiObject |Name|Description| |----------|-----------------| -|[CBrush::CBrush](#cbrush)|Constructs a `CBrush` object.| +|[`CBrush::CBrush`](#cbrush)|Constructs a `CBrush` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CBrush::CreateBrushIndirect](#createbrushindirect)|Initializes a brush with the style, color, and pattern specified in a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure.| -|[CBrush::CreateDIBPatternBrush](#createdibpatternbrush)|Initializes a brush with a pattern specified by a device-independent bitmap (DIB).| -|[CBrush::CreateHatchBrush](#createhatchbrush)|Initializes a brush with the specified hatched pattern and color.| -|[CBrush::CreatePatternBrush](#createpatternbrush)|Initializes a brush with a pattern specified by a bitmap.| -|[CBrush::CreateSolidBrush](#createsolidbrush)|Initializes a brush with the specified solid color.| -|[CBrush::CreateSysColorBrush](#createsyscolorbrush)|Creates a brush that is the default system color.| -|[CBrush::FromHandle](#fromhandle)|Returns a pointer to a `CBrush` object when given a handle to a Windows `HBRUSH` object.| -|[CBrush::GetLogBrush](#getlogbrush)|Gets a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure.| +|[`CBrush::CreateBrushIndirect`](#createbrushindirect)|Initializes a brush with the style, color, and pattern specified in a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure.| +|[`CBrush::CreateDIBPatternBrush`](#createdibpatternbrush)|Initializes a brush with a pattern specified by a device-independent bitmap (DIB).| +|[`CBrush::CreateHatchBrush`](#createhatchbrush)|Initializes a brush with the specified hatched pattern and color.| +|[`CBrush::CreatePatternBrush`](#createpatternbrush)|Initializes a brush with a pattern specified by a bitmap.| +|[`CBrush::CreateSolidBrush`](#createsolidbrush)|Initializes a brush with the specified solid color.| +|[`CBrush::CreateSysColorBrush`](#createsyscolorbrush)|Creates a brush that is the default system color.| +|[`CBrush::FromHandle`](#fromhandle)|Returns a pointer to a `CBrush` object when given a handle to a Windows `HBRUSH` object.| +|[`CBrush::GetLogBrush`](#getlogbrush)|Gets a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure.| ### Public Operators |Name|Description| |----------|-----------------| -|[CBrush::operator HBRUSH](#operator_hbrush)|Returns the Windows handle attached to the `CBrush` object.| +|[`CBrush::operator HBRUSH`](#operator_hbrush)|Returns the Windows handle attached to the `CBrush` object.| ## Remarks @@ -53,17 +52,17 @@ For more information on `CBrush`, see [Graphic Objects](../../mfc/graphic-object ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CGdiObject](../../mfc/reference/cgdiobject-class.md) +[`CGdiObject`](../../mfc/reference/cgdiobject-class.md) `CBrush` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CBrush::CBrush +## `CBrush::CBrush` Constructs a `CBrush` object. @@ -76,46 +75,46 @@ explicit CBrush(CBitmap* pBitmap); ### Parameters -*crColor*
+*`crColor`*\ Specifies the foreground color of the brush as an RGB color. If the brush is hatched, this parameter specifies the color of the hatching. -*nIndex*
+*`nIndex`*\ Specifies the hatch style of the brush. It can be any one of the following values: -- HS_BDIAGONAL Downward hatch (left to right) at 45 degrees +- `HS_BDIAGONAL` Downward hatch (left to right) at 45 degrees -- HS_CROSS Horizontal and vertical crosshatch +- `HS_CROSS` Horizontal and vertical crosshatch -- HS_DIAGCROSS Crosshatch at 45 degrees +- `HS_DIAGCROSS` Crosshatch at 45 degrees -- HS_FDIAGONAL Upward hatch (left to right) at 45 degrees +- `HS_FDIAGONAL` Upward hatch (left to right) at 45 degrees -- HS_HORIZONTAL Horizontal hatch +- `HS_HORIZONTAL` Horizontal hatch -- HS_VERTICAL Vertical hatch +- `HS_VERTICAL` Vertical hatch -*pBitmap*
+*`pBitmap`*\ Points to a `CBitmap` object that specifies a bitmap with which the brush paints. ### Remarks -`CBrush` has four overloaded constructors.The constructor with no arguments constructs an uninitialized `CBrush` object that must be initialized before it can be used. +`CBrush` has four overloaded constructors. The constructor with no arguments constructs an uninitialized `CBrush` object that must be initialized before it can be used. -If you use the constructor with no arguments, you must initialize the resulting `CBrush` object with [CreateSolidBrush](#createsolidbrush), [CreateHatchBrush](#createhatchbrush), [CreateBrushIndirect](#createbrushindirect), [CreatePatternBrush](#createpatternbrush), or [CreateDIBPatternBrush](#createdibpatternbrush). If you use one of the constructors that takes arguments, then no further initialization is necessary. The constructors with arguments can throw an exception if errors are encountered, while the constructor with no arguments will always succeed. +If you use the constructor with no arguments, you must initialize the resulting `CBrush` object with [`CreateSolidBrush`](#createsolidbrush), [`CreateHatchBrush`](#createhatchbrush), [`CreateBrushIndirect`](#createbrushindirect), [`CreatePatternBrush`](#createpatternbrush), or [`CreateDIBPatternBrush`](#createdibpatternbrush). If you use one of the constructors that takes arguments, then no further initialization is necessary. The constructors with arguments can throw an exception if errors are encountered, while the constructor with no arguments will always succeed. -The constructor with a single [COLORREF](/windows/win32/gdi/colorref) parameter constructs a solid brush with the specified color. The color specifies an RGB value and can be constructed with the RGB macro in WINDOWS.H. +The constructor with a single [`COLORREF`](/windows/win32/gdi/colorref) parameter constructs a solid brush with the specified color. The color specifies an RGB value and can be constructed with the `RGB` macro in `WINDOWS.H`. -The constructor with two parameters constructs a hatch brush. The *nIndex* parameter specifies the index of a hatched pattern. The *crColor* parameter specifies the color. +The constructor with two parameters constructs a hatch brush. The *`nIndex`* parameter specifies the index of a hatched pattern. The *`crColor`* parameter specifies the color. -The constructor with a `CBitmap` parameter constructs a patterned brush. The parameter identifies a bitmap. The bitmap is assumed to have been created by using [CBitmap::CreateBitmap](../../mfc/reference/cbitmap-class.md#createbitmap), [CBitmap::CreateBitmapIndirect](../../mfc/reference/cbitmap-class.md#createbitmapindirect), [CBitmap::LoadBitmap](../../mfc/reference/cbitmap-class.md#loadbitmap), or [CBitmap::CreateCompatibleBitmap](../../mfc/reference/cbitmap-class.md#createcompatiblebitmap). The minimum size for a bitmap to be used in a fill pattern is 8 pixels by 8 pixels. +The constructor with a `CBitmap` parameter constructs a patterned brush. The parameter identifies a bitmap. The bitmap is assumed to have been created by using [`CBitmap::CreateBitmap`](../../mfc/reference/cbitmap-class.md#createbitmap), [`CBitmap::CreateBitmapIndirect`](../../mfc/reference/cbitmap-class.md#createbitmapindirect), [`CBitmap::LoadBitmap`](../../mfc/reference/cbitmap-class.md#loadbitmap), or [`CBitmap::CreateCompatibleBitmap`](../../mfc/reference/cbitmap-class.md#createcompatiblebitmap). The minimum size for a bitmap to be used in a fill pattern is 8 pixels by 8 pixels. ### Example [!code-cpp[NVC_MFCDocView#21](../../mfc/codesnippet/cpp/cbrush-class_1.cpp)] -## CBrush::CreateBrushIndirect +## `CBrush::CreateBrushIndirect` -Initializes a brush with a style, color, and pattern specified in a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure. +Initializes a brush with a style, color, and pattern specified in a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure. ``` BOOL CreateBrushIndirect(const LOGBRUSH* lpLogBrush); @@ -123,8 +122,8 @@ BOOL CreateBrushIndirect(const LOGBRUSH* lpLogBrush); ### Parameters -*lpLogBrush*
-Points to a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure that contains information about the brush. +*`lpLogBrush`*\ +Points to a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure that contains information about the brush. ### Return Value @@ -140,7 +139,7 @@ A brush created using a monochrome (1 plane, 1 bit per pixel) bitmap is drawn us [!code-cpp[NVC_MFCDocView#22](../../mfc/codesnippet/cpp/cbrush-class_2.cpp)] -## CBrush::CreateDIBPatternBrush +## `CBrush::CreateDIBPatternBrush` Initializes a brush with the pattern specified by a device-independent bitmap (DIB). @@ -156,17 +155,17 @@ BOOL CreateDIBPatternBrush( ### Parameters -*hPackedDIB*
+*`hPackedDIB`*\ Identifies a global-memory object containing a packed device-independent bitmap (DIB). -*nUsage*
-Specifies whether the `bmiColors[]` fields of the [BITMAPINFO](/windows/win32/api/wingdi/ns-wingdi-bitmapinfo) data structure (a part of the "packed DIB") contain explicit RGB values or indices into the currently realized logical palette. The parameter must be one of the following values: +*`nUsage`*\ +Specifies whether the `bmiColors[]` fields of the [`BITMAPINFO`](/windows/win32/api/wingdi/ns-wingdi-bitmapinfo) data structure (a part of the "packed DIB") contain explicit RGB values or indices into the currently realized logical palette. The parameter must be one of the following values: -- DIB_PAL_COLORS The color table consists of an array of 16-bit indexes. +- `DIB_PAL_COLORS` The color table consists of an array of 16-bit indexes. -- DIB_RGB_COLORS The color table contains literal RGB values. +- `DIB_RGB_COLORS` The color table contains literal RGB values. -*lpPackedDIB*
+*`lpPackedDIB`*\ Points to a packed DIB consisting of a `BITMAPINFO` structure immediately followed by an array of bytes defining the pixels of the bitmap. ### Return Value @@ -189,17 +188,17 @@ When an application selects a two-color DIB pattern brush into a monochrome devi For information about using the following Windows functions, see the Windows SDK: -- [CreateDIBPatternBrush](/windows/win32/api/wingdi/nf-wingdi-createdibpatternbrush) (This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0; use the `CreateDIBPatternBrushPt` function.) +- [`CreateDIBPatternBrush`](/windows/win32/api/wingdi/nf-wingdi-createdibpatternbrush) (This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0; use the `CreateDIBPatternBrushPt` function.) -- [CreateDIBPatternBrushPt](/windows/win32/api/wingdi/nf-wingdi-createdibpatternbrushpt) (This function should be used for Win32-based applications.) +- [`CreateDIBPatternBrushPt`](/windows/win32/api/wingdi/nf-wingdi-createdibpatternbrushpt) (This function should be used for Win32-based applications.) -- [GlobalAlloc](/windows/win32/api/winbase/nf-winbase-globalalloc) +- [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) ### Example [!code-cpp[NVC_MFCDocView#23](../../mfc/codesnippet/cpp/cbrush-class_3.cpp)] -## CBrush::CreateHatchBrush +## `CBrush::CreateHatchBrush` Initializes a brush with the specified hatched pattern and color. @@ -211,23 +210,23 @@ BOOL CreateHatchBrush( ### Parameters -*nIndex*
+*`nIndex`*\ Specifies the hatch style of the brush. It can be any one of the following values: -- HS_BDIAGONAL Downward hatch (left to right) at 45 degrees +- `HS_BDIAGONAL` Downward hatch (left to right) at 45 degrees -- HS_CROSS Horizontal and vertical crosshatch +- `HS_CROSS` Horizontal and vertical crosshatch -- HS_DIAGCROSS Crosshatch at 45 degrees +- `HS_DIAGCROSS` Crosshatch at 45 degrees -- HS_FDIAGONAL Upward hatch (left to right) at 45 degrees +- `HS_FDIAGONAL` Upward hatch (left to right) at 45 degrees -- HS_HORIZONTAL Horizontal hatch +- `HS_HORIZONTAL` Horizontal hatch -- HS_VERTICAL Vertical hatch +- `HS_VERTICAL` Vertical hatch -*crColor*
-Specifies the foreground color of the brush as an RGB color (the color of the hatches). See [COLORREF](/windows/win32/gdi/colorref) in the Windows SDK for more information. +*`crColor`*\ +Specifies the foreground color of the brush as an RGB color (the color of the hatches). See [`COLORREF`](/windows/win32/gdi/colorref) in the Windows SDK for more information. ### Return Value @@ -241,7 +240,7 @@ The brush can subsequently be selected as the current brush for any device conte [!code-cpp[NVC_MFCDocView#24](../../mfc/codesnippet/cpp/cbrush-class_4.cpp)] -## CBrush::CreatePatternBrush +## `CBrush::CreatePatternBrush` Initializes a brush with a pattern specified by a bitmap. @@ -251,7 +250,7 @@ BOOL CreatePatternBrush(CBitmap* pBitmap); ### Parameters -*pBitmap*
+*`pBitmap`*\ Identifies a bitmap. ### Return Value @@ -260,7 +259,7 @@ Nonzero if successful; otherwise 0. ### Remarks -The brush can subsequently be selected for any device context that supports raster operations. The bitmap identified by *pBitmap* is typically initialized by using the [CBitmap::CreateBitmap](../../mfc/reference/cbitmap-class.md#createbitmap), [CBitmap::CreateBitmapIndirect](../../mfc/reference/cbitmap-class.md#createbitmapindirect), [CBitmap::LoadBitmap](../../mfc/reference/cbitmap-class.md#loadbitmap), or [CBitmap::CreateCompatibleBitmap](../../mfc/reference/cbitmap-class.md#createcompatiblebitmap) function. +The brush can subsequently be selected for any device context that supports raster operations. The bitmap identified by *`pBitmap`* is typically initialized by using the [`CBitmap::CreateBitmap`](../../mfc/reference/cbitmap-class.md#createbitmap), [`CBitmap::CreateBitmapIndirect`](../../mfc/reference/cbitmap-class.md#createbitmapindirect), [`CBitmap::LoadBitmap`](../../mfc/reference/cbitmap-class.md#loadbitmap), or [`CBitmap::CreateCompatibleBitmap`](../../mfc/reference/cbitmap-class.md#createcompatiblebitmap) function. Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, Windows will only use the bits corresponding to the first 8 rows and columns of pixels in the upper-left corner of the bitmap. @@ -268,13 +267,13 @@ A pattern brush can be deleted without affecting the associated bitmap. This mea A brush created using a monochrome bitmap (1 color plane, 1 bit per pixel) is drawn using the current text and background colors. Pixels represented by a bit set to 0 are drawn with the current text color. Pixels represented by a bit set to 1 are drawn with the current background color. -For information about using [CreatePatternBrush](/windows/win32/api/wingdi/nf-wingdi-createpatternbrush), a Windows function, see the Windows SDK. +For information about using [`CreatePatternBrush`](/windows/win32/api/wingdi/nf-wingdi-createpatternbrush), a Windows function, see the Windows SDK. ### Example [!code-cpp[NVC_MFCDocView#25](../../mfc/codesnippet/cpp/cbrush-class_5.cpp)] -## CBrush::CreateSolidBrush +## `CBrush::CreateSolidBrush` Initializes a brush with a specified solid color. @@ -284,8 +283,8 @@ BOOL CreateSolidBrush(COLORREF crColor); ### Parameters -*crColor*
-A [COLORREF](/windows/win32/gdi/colorref) structure that specifies the color of the brush. The color specifies an RGB value and can be constructed with the RGB macro in WINDOWS.H. +*`crColor`*\ +A [`COLORREF`](/windows/win32/gdi/colorref) structure that specifies the color of the brush. The color specifies an RGB value and can be constructed with the `RGB` macro in `WINDOWS.H`. ### Return Value @@ -299,9 +298,9 @@ When an application has finished using the brush created by `CreateSolidBrush`, ### Example - See the example for [CBrush::CBrush](#cbrush). + See the example for [`CBrush::CBrush`](#cbrush). -## CBrush::CreateSysColorBrush +## `CBrush::CreateSysColorBrush` Initializes a brush color. @@ -311,8 +310,8 @@ BOOL CreateSysColorBrush(int nIndex); ### Parameters -*nIndex*
-Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements. See [GetSysColor](/windows/win32/api/winuser/nf-winuser-getsyscolor) in the Windows SDK for a list of values. +*`nIndex`*\ +Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements. See [`GetSysColor`](/windows/win32/api/winuser/nf-winuser-getsyscolor) in the Windows SDK for a list of values. ### Return Value @@ -328,9 +327,9 @@ When an application has finished using the brush created by `CreateSysColorBrush [!code-cpp[NVC_MFCDocView#26](../../mfc/codesnippet/cpp/cbrush-class_6.cpp)] -## CBrush::FromHandle +## `CBrush::FromHandle` -Returns a pointer to a `CBrush` object when given a handle to a Windows [HBRUSH](#operator_hbrush) object. +Returns a pointer to a `CBrush` object when given a handle to a Windows [`HBRUSH`](#operator_hbrush) object. ``` static CBrush* PASCAL FromHandle(HBRUSH hBrush); @@ -338,12 +337,12 @@ static CBrush* PASCAL FromHandle(HBRUSH hBrush); ### Parameters -*hBrush*
+*`hBrush`*\ HANDLE to a Windows GDI brush. ### Return Value -A pointer to a `CBrush` object if successful; otherwise NULL. +A pointer to a `CBrush` object if successful; otherwise `NULL`. ### Remarks @@ -355,7 +354,7 @@ For more information about using graphic objects, see [Graphic Objects](/windows See the example for [CBrush::CBrush](#cbrush). -## CBrush::GetLogBrush +## `CBrush::GetLogBrush` Call this member function to retrieve the `LOGBRUSH` structure. @@ -365,14 +364,14 @@ int GetLogBrush(LOGBRUSH* pLogBrush); ### Parameters -*pLogBrush*
-Points to a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure that contains information about the brush. +*`pLogBrush`*\ +Points to a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure that contains information about the brush. ### Return Value -If the function succeeds, and *pLogBrush* is a valid pointer, the return value is the number of bytes stored into the buffer. +If the function succeeds, and *`pLogBrush`* is a valid pointer, the return value is the number of bytes stored into the buffer. -If the function succeeds, and *pLogBrush* is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer. +If the function succeeds, and *`pLogBrush`* is `NULL`, the return value is the number of bytes required to hold the information the function would store into the buffer. If the function fails, the return value is 0. @@ -386,7 +385,7 @@ For example, call `GetLogBrush` to match the particular color or pattern of a bi [!code-cpp[NVC_MFCDocView#27](../../mfc/codesnippet/cpp/cbrush-class_7.cpp)] -## CBrush::operator HBRUSH +## `CBrush::operator HBRUSH` Use this operator to get the attached Windows GDI handle of the `CBrush` object. @@ -396,11 +395,11 @@ operator HBRUSH() const; ### Return Value -If successful, a handle to the Windows GDI object represented by the `CBrush` object; otherwise NULL. +If successful, a handle to the Windows GDI object represented by the `CBrush` object; otherwise `NULL`. ### Remarks -This operator is a casting operator, which supports direct use of an HBRUSH object. +This operator is a casting operator, which supports direct use of an `HBRUSH` object. For more information about using graphic objects, see [Graphic Objects](/windows/win32/gdi/graphic-objects) in the Windows SDK. @@ -410,8 +409,8 @@ For more information about using graphic objects, see [Graphic Objects](/windows ## See also -[MFC Sample PROPDLG](../../overview/visual-cpp-samples.md)
-[CGdiObject Class](../../mfc/reference/cgdiobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CBitmap Class](../../mfc/reference/cbitmap-class.md)
-[CDC Class](../../mfc/reference/cdc-class.md) +[MFC Sample `PROPDLG`](../../overview/visual-cpp-samples.md)\ +[`CGdiObject` Class](../../mfc/reference/cgdiobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CBitmap` Class](../../mfc/reference/cbitmap-class.md)\ +[`CDC` Class](../../mfc/reference/cdc-class.md) diff --git a/docs/mfc/reference/cchecklistbox-class.md b/docs/mfc/reference/cchecklistbox-class.md index 0c5b6f031b..1ef8922947 100644 --- a/docs/mfc/reference/cchecklistbox-class.md +++ b/docs/mfc/reference/cchecklistbox-class.md @@ -4,9 +4,8 @@ title: "CCheckListBox Class" ms.date: "11/04/2016" f1_keywords: ["CCheckListBox", "AFXWIN/CCheckListBox", "AFXWIN/CCheckListBox::CCheckListBox", "AFXWIN/CCheckListBox::Create", "AFXWIN/CCheckListBox::DrawItem", "AFXWIN/CCheckListBox::Enable", "AFXWIN/CCheckListBox::GetCheck", "AFXWIN/CCheckListBox::GetCheckStyle", "AFXWIN/CCheckListBox::IsEnabled", "AFXWIN/CCheckListBox::MeasureItem", "AFXWIN/CCheckListBox::OnGetCheckPosition", "AFXWIN/CCheckListBox::SetCheck", "AFXWIN/CCheckListBox::SetCheckStyle"] helpviewer_keywords: ["CCheckListBox [MFC], CCheckListBox", "CCheckListBox [MFC], Create", "CCheckListBox [MFC], DrawItem", "CCheckListBox [MFC], Enable", "CCheckListBox [MFC], GetCheck", "CCheckListBox [MFC], GetCheckStyle", "CCheckListBox [MFC], IsEnabled", "CCheckListBox [MFC], MeasureItem", "CCheckListBox [MFC], OnGetCheckPosition", "CCheckListBox [MFC], SetCheck", "CCheckListBox [MFC], SetCheckStyle"] -ms.assetid: 1dd78438-00e8-441c-b36f-9c4f9ac0d019 --- -# CCheckListBox Class +# `CCheckListBox` Class Provides the functionality of a Windows checklist box. @@ -22,68 +21,68 @@ class CCheckListBox : public CListBox |Name|Description| |----------|-----------------| -|[CCheckListBox::CCheckListBox](#cchecklistbox)|Constructs a `CCheckListBox` object.| +|[`CCheckListBox::CCheckListBox`](#cchecklistbox)|Constructs a `CCheckListBox` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CCheckListBox::Create](#create)|Creates the Windows checklist box and attaches it to the `CCheckListBox` object.| -|[CCheckListBox::DrawItem](#drawitem)|Called by the framework when a visual aspect of an owner-draw list box changes.| -|[CCheckListBox::Enable](#enable)|Enables or disables a checklist box item.| -|[CCheckListBox::GetCheck](#getcheck)|Gets the state of an item's check box.| -|[CCheckListBox::GetCheckStyle](#getcheckstyle)|Gets the style of the control's check boxes.| -|[CCheckListBox::IsEnabled](#isenabled)|Determines whether an item is enabled.| -|[CCheckListBox::MeasureItem](#measureitem)|Called by the framework when a list box with an owner-draw style is created.| -|[CCheckListBox::OnGetCheckPosition](#ongetcheckposition)|Called by the framework to get the position of an item's check box.| -|[CCheckListBox::SetCheck](#setcheck)|Sets the state of an item's check box.| -|[CCheckListBox::SetCheckStyle](#setcheckstyle)|Sets the style of the control's check boxes.| +|[`CCheckListBox::Create`](#create)|Creates the Windows checklist box and attaches it to the `CCheckListBox` object.| +|[`CCheckListBox::DrawItem`](#drawitem)|Called by the framework when a visual aspect of an owner-draw list box changes.| +|[`CCheckListBox::Enable`](#enable)|Enables or disables a checklist box item.| +|[`CCheckListBox::GetCheck`](#getcheck)|Gets the state of an item's check box.| +|[`CCheckListBox::GetCheckStyle`](#getcheckstyle)|Gets the style of the control's check boxes.| +|[`CCheckListBox::IsEnabled`](#isenabled)|Determines whether an item is enabled.| +|[`CCheckListBox::MeasureItem`](#measureitem)|Called by the framework when a list box with an owner-draw style is created.| +|[`CCheckListBox::OnGetCheckPosition`](#ongetcheckposition)|Called by the framework to get the position of an item's check box.| +|[`CCheckListBox::SetCheck`](#setcheck)|Sets the state of an item's check box.| +|[`CCheckListBox::SetCheckStyle`](#setcheckstyle)|Sets the style of the control's check boxes.| ## Remarks A "checklist box" displays a list of items, such as filenames. Each item in the list has a check box next to it that the user can check or clear. -`CCheckListBox` is only for owner-drawn controls because the list contains more than text strings. At its simplest, a checklist box contains text strings and check boxes, but you do not need to have text at all. For example, you could have a list of small bitmaps with a check box next to each item. +`CCheckListBox` is only for owner-drawn controls because the list contains more than text strings. At its simplest, a checklist box contains text strings and check boxes, but you don't need to have text at all. For example, you could have a list of small bitmaps with a check box next to each item. To create your own checklist box, you must derive your own class from `CCheckListBox`. To derive your own class, write a constructor for the derived class, then call `Create`. -If you want to handle Windows notification messages sent by a list box to its parent (usually a class derived from [CDialog](../../mfc/reference/cdialog-class.md)), add a message-map entry and message-handler member function to the parent class for each message. +If you want to handle Windows notification messages sent by a list box to its parent (usually a class derived from [`CDialog`](../../mfc/reference/cdialog-class.md)), add a message-map entry and message-handler member function to the parent class for each message. Each message-map entry takes the following form: -**ON\_**_Notification_ **(** _id_, _memberFxn_ **)** +**ON\_**_Notification_ **(** _`id`_, _`memberFxn`_ **)** -where `id` specifies the child window ID of the control sending the notification and `memberFxn` is the name of the parent member function you have written to handle the notification. +where `id` specifies the child window ID of the control sending the notification and `memberFxn` is the name of the parent member function you've written to handle the notification. The parent's function prototype is as follows: `afx_msg void memberFxn();` -There is only one message-map entry that pertains specifically to `CCheckListBox` (but see also the message-map entries for [CListBox](../../mfc/reference/clistbox-class.md)): +There's only one message-map entry that pertains specifically to `CCheckListBox` (but see also the message-map entries for [`CListBox`](../../mfc/reference/clistbox-class.md)): -- ON_CLBN_CHKCHANGE The user has changed the state of an item's checkbox. +- `ON_CLBN_CHKCHANGE` The user has changed the state of an item's checkbox. -If your checklist box is a default checklist box (a list of strings with the default-sized checkboxes to the left of each), you can use the default [CCheckListBox::DrawItem](#drawitem) to draw the checklist box. Otherwise, you must override the [CListBox::CompareItem](../../mfc/reference/clistbox-class.md#compareitem) function and the [CCheckListBox::DrawItem](#drawitem) and [CCheckListBox::MeasureItem](#measureitem) functions. +If your checklist box is a default checklist box (a list of strings with the default-sized checkboxes to the left of each), you can use the default [`CCheckListBox::DrawItem`](#drawitem) to draw the checklist box. Otherwise, you must override the [`CListBox::CompareItem`](../../mfc/reference/clistbox-class.md#compareitem) function and the [`CCheckListBox::DrawItem`](#drawitem) and [`CCheckListBox::MeasureItem`](#measureitem) functions. You can create a checklist box either from a dialog template or directly in your code. ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CListBox](../../mfc/reference/clistbox-class.md) +[`CListBox`](../../mfc/reference/clistbox-class.md) `CCheckListBox` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CCheckListBox::CCheckListBox +## `CCheckListBox::CCheckListBox` Constructs a `CCheckListBox` object. @@ -99,7 +98,7 @@ You construct a `CCheckListBox` object in two steps. First define a class derive [!code-cpp[NVC_MFCControlLadenDialog#60](../../mfc/codesnippet/cpp/cchecklistbox-class_1.cpp)] -## CCheckListBox::Create +## `CCheckListBox::Create` Creates the Windows checklist box and attaches it to the `CCheckListBox` object. @@ -113,16 +112,16 @@ virtual BOOL Create( ### Parameters -*dwStyle*
-Specifies the style of the checklist box. The style must be LBS_HASSTRINGS and either LBS_OWNERDRAWFIXED (all items in the list are the same height) or LBS_OWNERDRAWVARIABLE (items in the list are of varying heights). This style can be combined with other [list-box styles](../../mfc/reference/styles-used-by-mfc.md#list-box-styles) except LBS_USETABSTOPS. +*`dwStyle`*\ +Specifies the style of the checklist box. The style must be `LBS_HASSTRINGS` and either `LBS_OWNERDRAWFIXED` (all items in the list are the same height) or `LBS_OWNERDRAWVARIABLE` (items in the list are of varying heights). This style can be combined with other [list-box styles](../../mfc/reference/styles-used-by-mfc.md#list-box-styles) except `LBS_USETABSTOPS`. -*rect*
-Specifies the checklist-box size and position. Can be either a [CRect](../../atl-mfc-shared/reference/crect-class.md) object or a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +*`rect`*\ +Specifies the checklist-box size and position. Can be either a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -*pParentWnd*
+*`pParentWnd`*\ Specifies the checklist box's parent window (usually a `CDialog` object). It must not be NULL. -*nID*
+*`nID`*\ Specifies the checklist box's control ID. ### Return Value @@ -131,29 +130,29 @@ Nonzero if successful; otherwise 0. ### Remarks -You construct a `CCheckListBox` object in two steps. First, define a class derived from `CcheckListBox` and then call `Create`, which initializes the Windows checklist box and attaches it to the `CCheckListBox`. See [CCheckListBox::CCheckListBox](#cchecklistbox) for a sample. +You construct a `CCheckListBox` object in two steps. First, define a class derived from `CcheckListBox` and then call `Create`, which initializes the Windows checklist box and attaches it to the `CCheckListBox`. See [`CCheckListBox::CCheckListBox`](#cchecklistbox) for a sample. -When `Create` executes, Windows sends the [WM_NCCREATE](../../mfc/reference/cwnd-class.md#onnccreate), [WM_CREATE](../../mfc/reference/cwnd-class.md#oncreate), [WM_NCCALCSIZE](../../mfc/reference/cwnd-class.md#onnccalcsize), and [WM_GETMINMAXINFO](../../mfc/reference/cwnd-class.md#ongetminmaxinfo) messages to the checklist-box control. +When `Create` executes, Windows sends the [`WM_NCCREATE`](../../mfc/reference/cwnd-class.md#onnccreate), [`WM_CREATE`](../../mfc/reference/cwnd-class.md#oncreate), [`WM_NCCALCSIZE`](../../mfc/reference/cwnd-class.md#onnccalcsize), and [`WM_GETMINMAXINFO`](../../mfc/reference/cwnd-class.md#ongetminmaxinfo) messages to the checklist-box control. -These messages are handled by default by the [OnNcCreate](../../mfc/reference/cwnd-class.md#onnccreate), [OnCreate](../../mfc/reference/cwnd-class.md#oncreate), [OnNcCalcSize](../../mfc/reference/cwnd-class.md#onnccalcsize), and [OnGetMinMaxInfo](../../mfc/reference/cwnd-class.md#ongetminmaxinfo) member functions in the `CWnd` base class. To extend the default message handling, add a message map to the your derived class and override the preceding message-handler member functions. Override `OnCreate`, for example, to perform needed initialization for a new class. +These messages are handled by default by the [`OnNcCreate`](../../mfc/reference/cwnd-class.md#onnccreate), [`OnCreate`](../../mfc/reference/cwnd-class.md#oncreate), [`OnNcCalcSize`](../../mfc/reference/cwnd-class.md#onnccalcsize), and [`OnGetMinMaxInfo`](../../mfc/reference/cwnd-class.md#ongetminmaxinfo) member functions in the `CWnd` base class. To extend the default message handling, add a message map to the derived class and override the preceding message-handler member functions. Override `OnCreate`, for example, to perform needed initialization for a new class. Apply the following [window styles](../../mfc/reference/styles-used-by-mfc.md#window-styles) to a checklist-box control: -- WS_CHILD Always +- `WS_CHILD` Always -- WS_VISIBLE Usually +- `WS_VISIBLE` Usually -- WS_DISABLED Rarely +- `WS_DISABLED` Rarely -- WS_VSCROLL To add a vertical scroll bar +- `WS_VSCROLL` To add a vertical scroll bar -- WS_HSCROLL To add a horizontal scroll bar +- `WS_HSCROLL` To add a horizontal scroll bar -- WS_GROUP To group controls +- `WS_GROUP` To group controls -- WS_TABSTOP To allow tabbing to this control +- `WS_TABSTOP` To allow tabbing to this control -## CCheckListBox::DrawItem +## `CCheckListBox::DrawItem` Called by the framework when a visual aspect of an owner-drawn checklist box changes. @@ -163,20 +162,20 @@ virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct); ### Parameters -*lpDrawItemStruct*
-A long pointer to a [DRAWITEMSTRUCT](/windows/win32/api/winuser/ns-winuser-drawitemstruct) structure that contains information about the type of drawing required. +*`lpDrawItemStruct`*\ +A long pointer to a [`DRAWITEMSTRUCT`](/windows/win32/api/winuser/ns-winuser-drawitemstruct) structure that contains information about the type of drawing required. ### Remarks The `itemAction` and `itemState` members of the `DRAWITEMSTRUCT` structure define the drawing action that is to be performed. -By default, this function draws a default checkbox list, consisting of a list of strings each with a default-sized checkbox to the left. The checkbox list size is the one specified in [Create](#create). +By default, this function draws a default checkbox list, consisting of a list of strings each with a default-sized checkbox to the left. The checkbox list size is the one specified in [`Create`](#create). -Override this member function to implement drawing of owner-draw checklist boxes that are not the default, such as checklist boxes with lists that aren't strings, with variable-height items, or with checkboxes that aren't on the left. The application should restore all graphics device interface (GDI) objects selected for the display context supplied in *lpDrawItemStruct* before the termination of this member function. +Override this member function to implement drawing of owner-draw checklist boxes that aren't the default, such as checklist boxes with lists that aren't strings, with variable-height items, or with checkboxes that aren't on the left. The application should restore all graphics device interface (GDI) objects selected for the display context supplied in *`lpDrawItemStruct`* before the termination of this member function. -If checklist box items are not all the same height, the checklist box style (specified in `Create`) must be **LBS_OWNERVARIABLE**, and you must override the [MeasureItem](#measureitem) function. +If checklist box items aren't all the same height, the checklist box style (specified in `Create`) must be **`LBS_OWNERVARIABLE`**, and you must override the [`MeasureItem`](#measureitem) function. -## CCheckListBox::Enable +## `CCheckListBox::Enable` Call this function to enable or disable a checklist box item. @@ -188,13 +187,13 @@ void Enable( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the checklist box item to be enabled. -*bEnabled*
+*`bEnabled`*\ Specifies whether the item is enabled or disabled. -## CCheckListBox::GetCheck +## `CCheckListBox::GetCheck` Retrieves the state of the specified check box. @@ -204,7 +203,7 @@ int GetCheck(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of a check box that is contained in the list box. ### Return Value @@ -213,11 +212,11 @@ The state of the specified check box. The following table lists possible values. |Value|Description| |-----------|-----------------| -|BST_CHECKED|The check box is checked.| -|BST_UNCHECKED|The check box is not checked.| -|BST_INDETERMINATE|The check box state is indeterminate.| +|`BST_CHECKED`|The check box is checked.| +|`BST_UNCHECKED`|The check box isn't checked.| +|`BST_INDETERMINATE`|The check box state is indeterminate.| -## CCheckListBox::GetCheckStyle +## `CCheckListBox::GetCheckStyle` Call this function to get the checklist box's style. @@ -231,9 +230,9 @@ The style of the control's check boxes. ### Remarks -For information on possible styles, see [SetCheckStyle](#setcheckstyle). +For information on possible styles, see [`SetCheckStyle`](#setcheckstyle). -## CCheckListBox::IsEnabled +## `CCheckListBox::IsEnabled` Call this function to determine whether an item is enabled. @@ -243,14 +242,14 @@ BOOL IsEnabled(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ Index of the item. ### Return Value Nonzero if the item is enabled; otherwise 0. -## CCheckListBox::MeasureItem +## `CCheckListBox::MeasureItem` Called by the framework when a checklist box with a nondefault style is created. @@ -260,14 +259,14 @@ virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct); ### Parameters -*lpMeasureItemStruct*
-A long pointer to a [MEASUREITEMSTRUCT](/windows/win32/api/winuser/ns-winuser-measureitemstruct) structure. +*`lpMeasureItemStruct`*\ +A long pointer to a [`MEASUREITEMSTRUCT`](/windows/win32/api/winuser/ns-winuser-measureitemstruct) structure. ### Remarks -By default, this member function does nothing. Override this member function and fill in the `MEASUREITEMSTRUCT` structure to inform Windows of the dimensions of checklist-box items. If the checklist box is created with the [LBS_OWNERDRAWVARIABLE](../../mfc/reference/styles-used-by-mfc.md#list-box-styles) style, the framework calls this member function for each item in the list box. Otherwise, this member is called only once. +By default, this member function does nothing. Override this member function and fill in the `MEASUREITEMSTRUCT` structure to inform Windows of the dimensions of checklist-box items. If the checklist box is created with the [`LBS_OWNERDRAWVARIABLE`](../../mfc/reference/styles-used-by-mfc.md#list-box-styles) style, the framework calls this member function for each item in the list box. Otherwise, this member is called only once. -## CCheckListBox::OnGetCheckPosition +## `CCheckListBox::OnGetCheckPosition` The framework calls this function to get the position and size of the check box in an item. @@ -279,10 +278,10 @@ virtual CRect OnGetCheckPosition( ### Parameters -*rectItem*
+*`rectItem`*\ The position and size of the list item. -*rectCheckBox*
+*`rectCheckBox`*\ The default position and size of an item's check box. ### Return Value @@ -293,7 +292,7 @@ The position and size of an item's check box. The default implementation only returns the default position and size of the check box (`rectCheckBox`). By default, a check box is aligned in the upper-left corner of an item and is the standard check box size. There may be cases where you want the check boxes on the right, or want a larger or smaller check box. In these cases, override `OnGetCheckPosition` to change the check box position and size within the item. -## CCheckListBox::SetCheck +## `CCheckListBox::SetCheck` Sets the state of the specified check box. @@ -305,23 +304,23 @@ void SetCheck( ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of a check box that is contained in the list box. -*nCheck*
+*`nCheck`*\ The button state for the specified check box. See the Remarks section for possible values. ### Remarks -The following table lists possible values for the *nCheck* parameter. +The following table lists possible values for the *`nCheck`* parameter. |Value|Description| |-----------|-----------------| -|BST_CHECKED|Select the specified check box.| -|BST_UNCHECKED|Clear the specified check box.| -|BST_INDETERMINATE|Set the specified check box state to indeterminate.

This state is only available if the check box style is BS_AUTO3STATE or BS_3STATE. For more information, see [Button Styles](../../mfc/reference/styles-used-by-mfc.md#button-styles).| +|`BST_CHECKED`|Select the specified check box.| +|`BST_UNCHECKED`|Clear the specified check box.| +|`BST_INDETERMINATE`|Set the specified check box state to indeterminate.

This state is only available if the check box style is `BS_AUTO3STATE` or `BS_3STATE`. For more information, see [Button Styles](../../mfc/reference/styles-used-by-mfc.md#button-styles).| -## CCheckListBox::SetCheckStyle +## `CCheckListBox::SetCheckStyle` Call this function to set the style of check boxes in the checklist box. @@ -331,26 +330,25 @@ void SetCheckStyle(UINT nStyle); ### Parameters -*nStyle*
+*`nStyle`*\ Determines the style of check boxes in the checklist box. ### Remarks Valid styles are: -- BS_CHECKBOX +- `BS_CHECKBOX` -- BS_AUTOCHECKBOX +- `BS_AUTOCHECKBOX` -- BS_AUTO3STATE +- `BS_AUTO3STATE` -- BS_3STATE +- `BS_3STATE` For information on these styles, see [Button Styles](../../mfc/reference/styles-used-by-mfc.md#button-styles). ## See also -[MFC Sample TSTCON](../../overview/visual-cpp-samples.md)
-[CListBox Class](../../mfc/reference/clistbox-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CListBox Class](../../mfc/reference/clistbox-class.md) +[MFC Sample `TSTCON`](../../overview/visual-cpp-samples.md)\ +[`CListBox` Class](../../mfc/reference/clistbox-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/ccmdtarget-class.md b/docs/mfc/reference/ccmdtarget-class.md index a8fbc597aa..6c3bdf1fc0 100644 --- a/docs/mfc/reference/ccmdtarget-class.md +++ b/docs/mfc/reference/ccmdtarget-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: CCmdTarget Class" title: "CCmdTarget Class" -ms.date: "11/04/2016" +description: "Learn more about: CCmdTarget Class" +ms.date: 11/04/2016 f1_keywords: ["CCmdTarget", "AFXWIN/CCmdTarget", "AFXWIN/CCmdTarget::CCmdTarget", "AFXWIN/CCmdTarget::BeginWaitCursor", "AFXWIN/CCmdTarget::DoOleVerb", "AFXWIN/CCmdTarget::EnableAutomation", "AFXWIN/CCmdTarget::EnableConnections", "AFXWIN/CCmdTarget::EnableTypeLib", "AFXWIN/CCmdTarget::EndWaitCursor", "AFXWIN/CCmdTarget::EnumOleVerbs", "AFXWIN/CCmdTarget::FromIDispatch", "AFXWIN/CCmdTarget::GetDispatchIID", "AFXWIN/CCmdTarget::GetIDispatch", "AFXWIN/CCmdTarget::GetTypeInfoCount", "AFXWIN/CCmdTarget::GetTypeInfoOfGuid", "AFXWIN/CCmdTarget::GetTypeLib", "AFXWIN/CCmdTarget::GetTypeLibCache", "AFXWIN/CCmdTarget::IsInvokeAllowed", "AFXWIN/CCmdTarget::IsResultExpected", "AFXWIN/CCmdTarget::OnCmdMsg", "AFXWIN/CCmdTarget::OnFinalRelease", "AFXWIN/CCmdTarget::RestoreWaitCursor"] helpviewer_keywords: ["CCmdTarget [MFC], CCmdTarget", "CCmdTarget [MFC], BeginWaitCursor", "CCmdTarget [MFC], DoOleVerb", "CCmdTarget [MFC], EnableAutomation", "CCmdTarget [MFC], EnableConnections", "CCmdTarget [MFC], EnableTypeLib", "CCmdTarget [MFC], EndWaitCursor", "CCmdTarget [MFC], EnumOleVerbs", "CCmdTarget [MFC], FromIDispatch", "CCmdTarget [MFC], GetDispatchIID", "CCmdTarget [MFC], GetIDispatch", "CCmdTarget [MFC], GetTypeInfoCount", "CCmdTarget [MFC], GetTypeInfoOfGuid", "CCmdTarget [MFC], GetTypeLib", "CCmdTarget [MFC], GetTypeLibCache", "CCmdTarget [MFC], IsInvokeAllowed", "CCmdTarget [MFC], IsResultExpected", "CCmdTarget [MFC], OnCmdMsg", "CCmdTarget [MFC], OnFinalRelease", "CCmdTarget [MFC], RestoreWaitCursor"] -ms.assetid: 8883b132-2057-4ce0-a5f2-88979f8f2b13 --- -# CCmdTarget Class +# `CCmdTarget` Class The base class for the Microsoft Foundation Class Library message-map architecture. @@ -22,37 +21,37 @@ class CCmdTarget : public CObject |Name|Description| |----------|-----------------| -|[CCmdTarget::CCmdTarget](#ccmdtarget)|Constructs a `CCmdTarget` object.| +|[`CCmdTarget::CCmdTarget`](#ccmdtarget)|Constructs a `CCmdTarget` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CCmdTarget::BeginWaitCursor](#beginwaitcursor)|Displays the cursor as an hourglass cursor.| -|[CCmdTarget::DoOleVerb](#dooleverb)|Causes an action specified by an OLE verb to be performed.| -|[CCmdTarget::EnableAutomation](#enableautomation)|Allows OLE automation for the `CCmdTarget` object.| -|[CCmdTarget::EnableConnections](#enableconnections)|Enables event firing over connection points.| -|[CCmdTarget::EnableTypeLib](#enabletypelib)|Enables an object's type library.| -|[CCmdTarget::EndWaitCursor](#endwaitcursor)|Returns to the previous cursor.| -|[CCmdTarget::EnumOleVerbs](#enumoleverbs)|Enumerates an object's OLE verbs.| -|[CCmdTarget::FromIDispatch](#fromidispatch)|Returns a pointer to the `CCmdTarget` object associated with the `IDispatch` pointer.| -|[CCmdTarget::GetDispatchIID](#getdispatchiid)|Gets the primary dispatch interface ID.| -|[CCmdTarget::GetIDispatch](#getidispatch)|Returns a pointer to the `IDispatch` object associated with the `CCmdTarget` object.| -|[CCmdTarget::GetTypeInfoCount](#gettypeinfocount)|Retrieves the number of type information interfaces that an object provides.| -|[CCmdTarget::GetTypeInfoOfGuid](#gettypeinfoofguid)|Retrieves the type description that corresponds to the specified GUID.| -|[CCmdTarget::GetTypeLib](#gettypelib)|Gets a pointer to a type library.| -|[CCmdTarget::GetTypeLibCache](#gettypelibcache)|Gets the type library cache.| -|[CCmdTarget::IsInvokeAllowed](#isinvokeallowed)|Enables automation method invocation.| -|[CCmdTarget::IsResultExpected](#isresultexpected)|Returns nonzero if an automation function should return a value.| -|[CCmdTarget::OnCmdMsg](#oncmdmsg)|Routes and dispatches command messages.| -|[CCmdTarget::OnFinalRelease](#onfinalrelease)|Cleans up after the last OLE reference is released.| -|[CCmdTarget::RestoreWaitCursor](#restorewaitcursor)|Restores the hourglass cursor.| +|[`CCmdTarget::BeginWaitCursor`](#beginwaitcursor)|Displays the cursor as an hourglass cursor.| +|[`CCmdTarget::DoOleVerb`](#dooleverb)|Causes an action specified by an OLE verb to be performed.| +|[`CCmdTarget::EnableAutomation`](#enableautomation)|Allows OLE automation for the `CCmdTarget` object.| +|[`CCmdTarget::EnableConnections`](#enableconnections)|Enables event firing over connection points.| +|[`CCmdTarget::EnableTypeLib`](#enabletypelib)|Enables an object's type library.| +|[`CCmdTarget::EndWaitCursor`](#endwaitcursor)|Returns to the previous cursor.| +|[`CCmdTarget::EnumOleVerbs`](#enumoleverbs)|Enumerates an object's OLE verbs.| +|[`CCmdTarget::FromIDispatch`](#fromidispatch)|Returns a pointer to the `CCmdTarget` object associated with the `IDispatch` pointer.| +|[`CCmdTarget::GetDispatchIID`](#getdispatchiid)|Gets the primary dispatch interface ID.| +|[`CCmdTarget::GetIDispatch`](#getidispatch)|Returns a pointer to the `IDispatch` object associated with the `CCmdTarget` object.| +|[`CCmdTarget::GetTypeInfoCount`](#gettypeinfocount)|Retrieves the number of type information interfaces that an object provides.| +|[`CCmdTarget::GetTypeInfoOfGuid`](#gettypeinfoofguid)|Retrieves the type description that corresponds to the specified GUID.| +|[`CCmdTarget::GetTypeLib`](#gettypelib)|Gets a pointer to a type library.| +|[`CCmdTarget::GetTypeLibCache`](#gettypelibcache)|Gets the type library cache.| +|[`CCmdTarget::IsInvokeAllowed`](#isinvokeallowed)|Enables automation method invocation.| +|[`CCmdTarget::IsResultExpected`](#isresultexpected)|Returns nonzero if an automation function should return a value.| +|[`CCmdTarget::OnCmdMsg`](#oncmdmsg)|Routes and dispatches command messages.| +|[`CCmdTarget::OnFinalRelease`](#onfinalrelease)|Cleans up after the last OLE reference is released.| +|[`CCmdTarget::RestoreWaitCursor`](#restorewaitcursor)|Restores the hourglass cursor.| ## Remarks A message map routes commands or messages to the member functions you write to handle them. (A command is a message from a menu item, command button, or accelerator key.) -Key framework classes derived from `CCmdTarget` include [CView](../../mfc/reference/cview-class.md), [CWinApp](../../mfc/reference/cwinapp-class.md), [CDocument](../../mfc/reference/cdocument-class.md), [CWnd](../../mfc/reference/cwnd-class.md), and [CFrameWnd](../../mfc/reference/cframewnd-class.md). If you intend for a new class to handle messages, derive the class from one of these `CCmdTarget`-derived classes. You will rarely derive a class from `CCmdTarget` directly. +Key framework classes derived from `CCmdTarget` include [`CView`](../../mfc/reference/cview-class.md), [`CWinApp`](../../mfc/reference/cwinapp-class.md), [`CDocument`](../../mfc/reference/cdocument-class.md), [`CWnd`](../../mfc/reference/cwnd-class.md), and [`CFrameWnd`](../../mfc/reference/cframewnd-class.md). If you intend for a new class to handle messages, derive the class from one of these `CCmdTarget`-derived classes. You'll rarely derive a class from `CCmdTarget` directly. For an overview of command targets and `OnCmdMsg` routing, see [Command Targets](../../mfc/command-targets.md), [Command Routing](../../mfc/command-routing.md), and [Mapping Messages](../../mfc/mapping-messages.md). @@ -68,9 +67,9 @@ Dispatch maps, similar to message maps, are used to expose OLE automation `IDisp ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CCmdTarget::BeginWaitCursor +## `CCmdTarget::BeginWaitCursor` Call this function to display the cursor as an hourglass when you expect a command to take a noticeable time interval to execute. @@ -80,9 +79,9 @@ void BeginWaitCursor(); ### Remarks -The framework calls this function to show the user that it is busy, such as when a `CDocument` object loads or saves itself to a file. +The framework calls this function to show the user that it's busy, such as when a `CDocument` object loads or saves itself to a file. -The actions of `BeginWaitCursor` are not always effective outside of a single message handler as other actions, such as `OnSetCursor` handling, could change the cursor. +The actions of `BeginWaitCursor` aren't always effective outside of a single message handler as other actions, such as `OnSetCursor` handling, could change the cursor. Call `EndWaitCursor` to restore the previous cursor. @@ -90,7 +89,7 @@ Call `EndWaitCursor` to restore the previous cursor. [!code-cpp[NVC_MFCDocView#43](../../mfc/codesnippet/cpp/ccmdtarget-class_1.cpp)] -## CCmdTarget::CCmdTarget +## `CCmdTarget::CCmdTarget` Constructs a `CCmdTarget` object. @@ -98,7 +97,7 @@ Constructs a `CCmdTarget` object. CCmdTarget(); ``` -## CCmdTarget::DoOleVerb +## `CCmdTarget::DoOleVerb` Causes an action specified by an OLE verb to be performed. @@ -112,27 +111,27 @@ BOOL DoOleVerb( ### Parameters -*iVerb*
+*`iVerb`*\ Numerical identifier of the verb. -*lpMsg*
-Pointer to the [MSG](/windows/win32/api/winuser/ns-winuser-msg) structure describing the event (such as a double-click) that invoked the verb. +*`lpMsg`*\ +Pointer to the [`MSG`](/windows/win32/api/winuser/ns-winuser-msg) structure describing the event (such as a double-click) that invoked the verb. -*hWndParent*
+*`hWndParent`*\ Handle of the document window containing the object. -*lpRect*
-Pointer to the [RECT](/windows/win32/api/windef/ns-windef-rect) structure containing the coordinates, in pixels, that define an object's bounding rectangle in *hwndParent*. +*`lpRect`*\ +Pointer to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure containing the coordinates, in pixels, that define an object's bounding rectangle in *`hWndParent`*. ### Return Value -TRUE if successful, otherwise FALSE. +`TRUE` if successful, otherwise `FALSE`. ### Remarks -This member function is basically an implementation of [IOleObject::DoVerb](/windows/win32/api/oleidl/nf-oleidl-ioleobject-doverb). The possible actions are enumerated by [CCmdTarget::EnumOleVerbs](#enumoleverbs). +This member function is basically an implementation of [`IOleObject::DoVerb`](/windows/win32/api/oleidl/nf-oleidl-ioleobject-doverb). The possible actions are enumerated by [`CCmdTarget::EnumOleVerbs`](#enumoleverbs). -## CCmdTarget::EnableAutomation +## `CCmdTarget::EnableAutomation` Call this function to enable OLE automation for an object. @@ -144,7 +143,7 @@ void EnableAutomation(); This function is typically called from the constructor of your object and should only be called if a dispatch map has been declared for the class. For more information on automation see the articles [Automation Clients](../../mfc/automation-clients.md) and [Automation Servers](../../mfc/automation-servers.md). -## CCmdTarget::EnableConnections +## `CCmdTarget::EnableConnections` Enables event firing over connection points. @@ -156,7 +155,7 @@ void EnableConnections(); To enable connection points, call this member function in the constructor of your derived class. -## CCmdTarget::EnableTypeLib +## `CCmdTarget::EnableTypeLib` Enables an object's type library. @@ -168,9 +167,9 @@ void EnableTypeLib(); Call this member function in the constructor of your `CCmdTarget`-derived object if it provides type information. -## CCmdTarget::EndWaitCursor +## `CCmdTarget::EndWaitCursor` -Call this function after you have called the `BeginWaitCursor` member function to return from the hourglass cursor to the previous cursor. +Call this function after you've called the `BeginWaitCursor` member function to return from the hourglass cursor to the previous cursor. ```cpp void EndWaitCursor(); @@ -184,7 +183,7 @@ The framework also calls this member function after it has called the hourglass [!code-cpp[NVC_MFCDocView#43](../../mfc/codesnippet/cpp/ccmdtarget-class_1.cpp)] -## CCmdTarget::EnumOleVerbs +## `CCmdTarget::EnumOleVerbs` Enumerates an object's OLE verbs. @@ -194,18 +193,18 @@ BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb); ### Parameters -*ppenumOleVerb*
-A pointer to a pointer to an [IEnumOLEVERB](/windows/win32/api/oleidl/nn-oleidl-ienumoleverb) interface. +*`ppenumOleVerb`*\ +A pointer to a pointer to an [`IEnumOLEVERB`](/windows/win32/api/oleidl/nn-oleidl-ienumoleverb) interface. ### Return Value -TRUE if the object supports at least one OLE verb (in which case \* *ppenumOleVerb* points to an `IEnumOLEVERB` enumerator interface), otherwise FALSE. +`TRUE` if the object supports at least one OLE verb (in which case *`*ppenumOleVerb`* points to an `IEnumOLEVERB` enumerator interface), otherwise `FALSE`. ### Remarks -This member function is basically an implementation of [IOleObject::EnumVerbs](/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumverbs). +This member function is basically an implementation of [`IOleObject::EnumVerbs`](/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumverbs). -## CCmdTarget::FromIDispatch +## `CCmdTarget::FromIDispatch` Call this function to map an `IDispatch` pointer, received from automation member functions of a class, into the `CCmdTarget` object that implements the interfaces of the `IDispatch` object. @@ -215,18 +214,18 @@ static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch); ### Parameters -*lpDispatch*
+*`lpDispatch`*\ A pointer to an `IDispatch` object. ### Return Value -A pointer to the `CCmdTarget` object associated with *lpDispatch*. This function returns NULL if the `IDispatch` object is not recognized as a Microsoft Foundation Class `IDispatch` object. +A pointer to the `CCmdTarget` object associated with *`lpDispatch`*. This function returns `NULL` if the `IDispatch` object isn't recognized as a Microsoft Foundation Class `IDispatch` object. ### Remarks The result of this function is the inverse of a call to the member function `GetIDispatch`. -## CCmdTarget::GetDispatchIID +## `CCmdTarget::GetDispatchIID` Gets the primary dispatch interface ID. @@ -236,18 +235,18 @@ virtual BOOL GetDispatchIID(IID* pIID); ### Parameters -*pIID*
-A pointer to an interface ID (a [GUID](/windows/win32/api/guiddef/ns-guiddef-guid. +*`pIID`*\ +A pointer to an interface ID (a [GUID](/windows/win32/api/guiddef/ns-guiddef-guid)). ### Return Value -TRUE if successful, otherwise FALSE. If successful, \* *pIID* is set to the primary dispatch interface ID. +`TRUE` if successful, otherwise `FALSE`. If successful, *`*pIID`* is set to the primary dispatch interface ID. ### Remarks -Derived classes should override this member function (if not overridden, `GetDispatchIID` returns FALSE). See [COleControl](../../mfc/reference/colecontrol-class.md). +Derived classes should override this member function (if not overridden, `GetDispatchIID` returns `FALSE`). See [`COleControl`](../../mfc/reference/colecontrol-class.md). -## CCmdTarget::GetIDispatch +## `CCmdTarget::GetIDispatch` Call this member function to retrieve the `IDispatch` pointer from an automation method that either returns an `IDispatch` pointer or takes an `IDispatch` pointer by reference. @@ -257,7 +256,7 @@ LPDISPATCH GetIDispatch(BOOL bAddRef); ### Parameters -*bAddRef*
+*`bAddRef`*\ Specifies whether to increment the reference count for the object. ### Return Value @@ -266,9 +265,9 @@ The `IDispatch` pointer associated with the object. ### Remarks -For objects that call `EnableAutomation` in their constructors, making them automation enabled, this function returns a pointer to the Foundation Class implementation of `IDispatch` that is used by clients who communicate via the `IDispatch` interface. Calling this function automatically adds a reference to the pointer, so it is not necessary to make a call to [IUnknown::AddRef](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref). +For objects that call `EnableAutomation` in their constructors, making them automation enabled, this function returns a pointer to the Foundation Class implementation of `IDispatch` that is used by clients who communicate via the `IDispatch` interface. Calling this function automatically adds a reference to the pointer, so it isn't necessary to make a call to [`IUnknown::AddRef`](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref). -## CCmdTarget::GetTypeInfoCount +## `CCmdTarget::GetTypeInfoCount` Retrieves the number of type information interfaces that an object provides. @@ -282,11 +281,11 @@ The number of type information interfaces. ### Remarks -This member function basically implements [IDispatch::GetTypeInfoCount](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount). +This member function basically implements [`IDispatch::GetTypeInfoCount`](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount). -Derived classes should override this function to return the number of type information interfaces provided (either 0 or 1). If not overridden, `GetTypeInfoCount` returns 0. To override, use the [IMPLEMENT_OLETYPELIB](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeLib` and `GetTypeLibCache`. +Derived classes should override this function to return the number of type information interfaces provided (either 0 or 1). If not overridden, `GetTypeInfoCount` returns 0. To override, use the [`IMPLEMENT_OLETYPELIB`](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeLib` and `GetTypeLibCache`. -## CCmdTarget::GetTypeInfoOfGuid +## `CCmdTarget::GetTypeInfoOfGuid` Retrieves the type description that corresponds to the specified GUID. @@ -299,20 +298,20 @@ HRESULT GetTypeInfoOfGuid( ### Parameters -*lcid*
-A locale identifier ( `LCID`). +*`lcid`*\ +A locale identifier (`LCID`). -*guid*
-The [GUID](/windows/win32/api/guiddef/ns-guiddef-guid of the type description. +*`guid`*\ +The [GUID](/windows/win32/api/guiddef/ns-guiddef-guid) of the type description. -*ppTypeInfo*
+*`ppTypeInfo`*\ Pointer to a pointer to the `ITypeInfo` interface. ### Return Value -An HRESULT indicating the success or failure of the call. If successful, \* *ppTypeInfo* points to the type information interface. +An `HRESULT` indicating the success or failure of the call. If successful, *`*ppTypeInfo`* points to the type information interface. -## CCmdTarget::GetTypeLib +## `CCmdTarget::GetTypeLib` Gets a pointer to a type library. @@ -324,21 +323,21 @@ virtual HRESULT GetTypeLib( ### Parameters -*lcid*
+*`lcid`*\ A locale identifier (LCID). -*ppTypeLib*
+*`ppTypeLib`*\ A pointer to a pointer to the `ITypeLib` interface. ### Return Value -An HRESULT indicating the success or failure of the call. If successful, \* *ppTypeLib* points to the type library interface. +An `HRESULT` indicating the success or failure of the call. If successful, *`*ppTypeLib`* points to the type library interface. ### Remarks -Derived classes should override this member function (if not overridden, `GetTypeLib` returns TYPE_E_CANTLOADLIBRARY). Use the [IMPLEMENT_OLETYPELIB](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeInfoCount` and `GetTypeLibCache`. +Derived classes should override this member function (if not overridden, `GetTypeLib` returns `TYPE_E_CANTLOADLIBRARY`). Use the [`IMPLEMENT_OLETYPELIB`](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeInfoCount` and `GetTypeLibCache`. -## CCmdTarget::GetTypeLibCache +## `CCmdTarget::GetTypeLibCache` Gets the type library cache. @@ -352,11 +351,11 @@ A pointer to a `CTypeLibCache` object. ### Remarks -Derived classes should override this member function (if not overridden, `GetTypeLibCache` returns NULL). Use the [IMPLEMENT_OLETYPELIB](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeInfoCount` and `GetTypeLib`. +Derived classes should override this member function (if not overridden, `GetTypeLibCache` returns `NULL`). Use the [`IMPLEMENT_OLETYPELIB`](../../mfc/reference/type-library-access.md#implement_oletypelib) macro, which also implements `GetTypeInfoCount` and `GetTypeLib`. -## CCmdTarget::IsInvokeAllowed +## `CCmdTarget::IsInvokeAllowed` -This function is called by MFC's implementation of `IDispatch::Invoke` to determine if a given automation method (identified by *dispid*) can be invoked. +This function is called by MFC's implementation of `IDispatch::Invoke` to determine if a given automation method (identified by *`dispid`*) can be invoked. ``` virtual BOOL IsInvokeAllowed(DISPID dispid); @@ -364,18 +363,18 @@ virtual BOOL IsInvokeAllowed(DISPID dispid); ### Parameters -*dispid*
+*`dispid`*\ A dispatch ID. ### Return Value -TRUE if the method can be invoked, otherwise FALSE. +`TRUE` if the method can be invoked, otherwise `FALSE`. ### Remarks -If `IsInvokeAllowed` returns TRUE, `Invoke` proceeds to call the method; otherwise, `Invoke` will fail, returning E_UNEXPECTED. +If `IsInvokeAllowed` returns `TRUE`, `Invoke` proceeds to call the method; otherwise, `Invoke` will fail, returning `E_UNEXPECTED`. -Derived classes can override this function to return appropriate values (if not overridden, `IsInvokeAllowed` returns TRUE). See in particular [COleControl::IsInvokeAllowed](../../mfc/reference/colecontrol-class.md#isinvokeallowed). +Derived classes can override this function to return appropriate values (if not overridden, `IsInvokeAllowed` returns `TRUE`). See in particular [`COleControl::IsInvokeAllowed`](../../mfc/reference/colecontrol-class.md#isinvokeallowed). ## CCmdTarget::IsResultExpected @@ -393,11 +392,11 @@ Nonzero if an automation function should return a value; otherwise 0. The OLE interface supplies information to MFC about whether the client is using or ignoring the result of a function call, and MFC in turn uses this information to determine the result of a call to `IsResultExpected`. If production of a return value is time- or resource-intensive, you can increase efficiency by calling this function before computing the return value. -This function returns 0 only once so that you will get valid return values from other automation functions if you call them from the automation function that the client has called. +This function returns 0 only once so that you'll get valid return values from other automation functions if you call them from the automation function that the client has called. -`IsResultExpected` returns a nonzero value if called when an automation function call is not in progress. +`IsResultExpected` returns a nonzero value if called when an automation function call isn't in progress. -## CCmdTarget::OnCmdMsg +## `CCmdTarget::OnCmdMsg` Called by the framework to route and dispatch command messages and to handle the update of command user-interface objects. @@ -411,23 +410,23 @@ virtual BOOL OnCmdMsg( ### Parameters -*nID*
+*`nID`*\ Contains the command ID. -*nCode*
-Identifies the command notification code. See **Remarks** for more information about values for *nCode*. +*`nCode`*\ +Identifies the command notification code. See [**Remarks**](#oncmdmsg-remarks) for more information about values for *`nCode`*. -*pExtra*
-Used according to the value of *nCode*. See **Remarks** for more information about *pExtra*. +*`pExtra`*\ +Used according to the value of *`nCode`*. See [**Remarks**](#oncmdmsg-remarks) for more information about *`pExtra`*. -*pHandlerInfo*
-If not NULL, `OnCmdMsg` fills in the *pTarget* and *pmf* members of the *pHandlerInfo* structure instead of dispatching the command. Typically, this parameter should be NULL. +*`pHandlerInfo`*\ +If not `NULL`, `OnCmdMsg` fills in the *`pTarget`* and *`pmf`* members of the *`pHandlerInfo`* structure instead of dispatching the command. Typically, this parameter should be `NULL`. ### Return Value Nonzero if the message is handled; otherwise 0. -### Remarks +### Remarks This is the main implementation routine of the framework command architecture. @@ -435,23 +434,23 @@ At run time, `OnCmdMsg` dispatches a command to other objects or handles the com On rare occasions, you may want to override this member function to extend the framework's standard command routing. Refer to [Technical Note 21](../../mfc/tn021-command-and-message-routing.md) for advanced details of the command-routing architecture. -If you override `OnCmdMsg`, you must supply the appropriate value for *nCode*, the command notification code, and *pExtra*, which depends on the value of *nCode*. The following table lists their corresponding values: +If you override `OnCmdMsg`, you must supply the appropriate value for *`nCode`*, the command notification code, and *`pExtra`*, which depends on the value of *`nCode`*. The following table lists their corresponding values: -|*nCode* value|*pExtra* value| +|*`nCode`* value|*`pExtra`* value| |-------------------|--------------------| -|CN_COMMAND|[CCmdUI](../../mfc/reference/ccmdui-class.md)\*| -|CN_EVENT|AFX_EVENT\*| -|CN_UPDATE_COMMAND_UI|CCmdUI\*| -|CN_OLECOMMAND|[COleCmdUI](../../mfc/reference/colecmdui-class.md)\*| -|CN_OLE_UNREGISTER|NULL| +|`CN_COMMAND`|[`CCmdUI`](../../mfc/reference/ccmdui-class.md)\*| +|`CN_EVENT`|`AFX_EVENT`\*| +|`CN_UPDATE_COMMAND_UI`|`CCmdUI`\*| +|`CN_OLECOMMAND`|[`COleCmdUI`](../../mfc/reference/colecmdui-class.md)\*| +|`CN_OLE_UNREGISTER`|`NULL`| ### Example [!code-cpp[NVC_MFCDocView#44](../../mfc/codesnippet/cpp/ccmdtarget-class_2.cpp)] - +  [!code-cpp[NVC_MFCDocView#45](../../mfc/codesnippet/cpp/ccmdtarget-class_3.cpp)] -## CCmdTarget::OnFinalRelease +## `CCmdTarget::OnFinalRelease` Called by the framework when the last OLE reference to or from the object is released. @@ -463,7 +462,7 @@ virtual void OnFinalRelease(); Override this function to provide special handling for this situation. The default implementation deletes the object. -## CCmdTarget::RestoreWaitCursor +## `CCmdTarget::RestoreWaitCursor` Call this function to restore the appropriate hourglass cursor after the system cursor has changed (for example, after a message box has opened and then closed while in the middle of a lengthy operation). @@ -477,14 +476,14 @@ void RestoreWaitCursor(); ## See also -[MFC Sample ACDUAL](../../overview/visual-cpp-samples.md)
-[CObject Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CCmdUI Class](../../mfc/reference/ccmdui-class.md)
-[CDocument Class](../../mfc/reference/cdocument-class.md)
-[CDocTemplate Class](../../mfc/reference/cdoctemplate-class.md)
-[CWinApp Class](../../mfc/reference/cwinapp-class.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[CView Class](../../mfc/reference/cview-class.md)
-[CFrameWnd Class](../../mfc/reference/cframewnd-class.md)
-[COleDispatchDriver Class](../../mfc/reference/coledispatchdriver-class.md) +[MFC Sample `ACDUAL`](../../overview/visual-cpp-samples.md)\ +[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CCmdUI` Class](../../mfc/reference/ccmdui-class.md)\ +[`CDocument` Class](../../mfc/reference/cdocument-class.md)\ +[`CDocTemplate` Class](../../mfc/reference/cdoctemplate-class.md)\ +[`CWinApp` Class](../../mfc/reference/cwinapp-class.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[`CView` Class](../../mfc/reference/cview-class.md)\ +[`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md)\ +[`COleDispatchDriver` Class](../../mfc/reference/coledispatchdriver-class.md) diff --git a/docs/mfc/reference/ccmdui-class.md b/docs/mfc/reference/ccmdui-class.md index 0d90c19e9b..f110e8be15 100644 --- a/docs/mfc/reference/ccmdui-class.md +++ b/docs/mfc/reference/ccmdui-class.md @@ -96,7 +96,7 @@ TRUE to enable the item, FALSE to disable it. ### Example [!code-cpp[NVC_MFCDocView#46](../../mfc/codesnippet/cpp/ccmdui-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocView#47](../../mfc/codesnippet/cpp/ccmdui-class_2.cpp)] ## CCmdUI::m_nID diff --git a/docs/mfc/reference/ccommandlineinfo-class.md b/docs/mfc/reference/ccommandlineinfo-class.md index 364e9d93cf..0702885e23 100644 --- a/docs/mfc/reference/ccommandlineinfo-class.md +++ b/docs/mfc/reference/ccommandlineinfo-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: CCommandLineInfo Class" title: "CCommandLineInfo Class" -ms.date: "11/04/2016" +description: "Learn more about: CCommandLineInfo Class" +ms.date: 11/04/2016 f1_keywords: ["CCommandLineInfo", "AFXWIN/CCommandLineInfo", "AFXWIN/CCommandLineInfo::CCommandLineInfo", "AFXWIN/CCommandLineInfo::ParseParam", "AFXWIN/CCommandLineInfo::m_bRunAutomated", "AFXWIN/CCommandLineInfo::m_bRunEmbedded", "AFXWIN/CCommandLineInfo::m_bShowSplash", "AFXWIN/CCommandLineInfo::m_nShellCommand", "AFXWIN/CCommandLineInfo::m_strDriverName", "AFXWIN/CCommandLineInfo::m_strFileName", "AFXWIN/CCommandLineInfo::m_strPortName", "AFXWIN/CCommandLineInfo::m_strPrinterName", "AFXWIN/CCommandLineInfo::m_strRestartIdentifier"] helpviewer_keywords: ["CCommandLineInfo [MFC], CCommandLineInfo", "CCommandLineInfo [MFC], ParseParam", "CCommandLineInfo [MFC], m_bRunAutomated", "CCommandLineInfo [MFC], m_bRunEmbedded", "CCommandLineInfo [MFC], m_bShowSplash", "CCommandLineInfo [MFC], m_nShellCommand", "CCommandLineInfo [MFC], m_strDriverName", "CCommandLineInfo [MFC], m_strFileName", "CCommandLineInfo [MFC], m_strPortName", "CCommandLineInfo [MFC], m_strPrinterName", "CCommandLineInfo [MFC], m_strRestartIdentifier"] -ms.assetid: 3e313ddb-0a82-4991-87ac-a27feff4668c --- -# CCommandLineInfo Class +# `CCommandLineInfo` Class Aids in parsing the command line at application startup. @@ -22,31 +21,31 @@ class CCommandLineInfo : public CObject |Name|Description| |----------|-----------------| -|[CCommandLineInfo::CCommandLineInfo](#ccommandlineinfo)|Constructs a default `CCommandLineInfo` object.| +|[`CCommandLineInfo::CCommandLineInfo`](#ccommandlineinfo)|Constructs a default `CCommandLineInfo` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CCommandLineInfo::ParseParam](#parseparam)|Override this callback to parse individual parameters.| +|[`CCommandLineInfo::ParseParam`](#parseparam)|Override this callback to parse individual parameters.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CCommandLineInfo::m_bRunAutomated](#m_brunautomated)|Indicates the command-line `/Automation` option was found.| -|[CCommandLineInfo::m_bRunEmbedded](#m_brunembedded)|Indicates the command-line `/Embedding` option was found.| -|[CCommandLineInfo::m_bShowSplash](#m_bshowsplash)|Indicates if a splash screen should be shown.| -|[CCommandLineInfo::m_nShellCommand](#m_nshellcommand)|Indicates the shell command to be processed.| -|[CCommandLineInfo::m_strDriverName](#m_strdrivername)|Indicates the driver name if the shell command is Print To; otherwise empty.| -|[CCommandLineInfo::m_strFileName](#m_strfilename)|Indicates the file name to be opened or printed; empty if the shell command is New or DDE.| -|[CCommandLineInfo::m_strPortName](#m_strportname)|Indicates the port name if the shell command is Print To; otherwise empty.| -|[CCommandLineInfo::m_strPrinterName](#m_strprintername)|Indicates the printer name if the shell command is Print To; otherwise empty.| -|[CCommandLineInfo::m_strRestartIdentifier](#m_strrestartidentifier)|Indicates the unique restart identifier for the restart manager if the restart manager restarted the application.| +|[`CCommandLineInfo::m_bRunAutomated`](#m_brunautomated)|Indicates the command-line `/Automation` option was found.| +|[`CCommandLineInfo::m_bRunEmbedded`](#m_brunembedded)|Indicates the command-line `/Embedding` option was found.| +|[`CCommandLineInfo::m_bShowSplash`](#m_bshowsplash)|Indicates if a splash screen should be shown.| +|[`CCommandLineInfo::m_nShellCommand`](#m_nshellcommand)|Indicates the shell command to be processed.| +|[`CCommandLineInfo::m_strDriverName`](#m_strdrivername)|Indicates the driver name if the shell command is Print To; otherwise empty.| +|[`CCommandLineInfo::m_strFileName`](#m_strfilename)|Indicates the file name to be opened or printed; empty if the shell command is New or DDE.| +|[`CCommandLineInfo::m_strPortName`](#m_strportname)|Indicates the port name if the shell command is Print To; otherwise empty.| +|[`CCommandLineInfo::m_strPrinterName`](#m_strprintername)|Indicates the printer name if the shell command is Print To; otherwise empty.| +|[`CCommandLineInfo::m_strRestartIdentifier`](#m_strrestartidentifier)|Indicates the unique restart identifier for the restart manager if the restart manager restarted the application.| ## Remarks -An MFC application will typically create a local instance of this class in the [InitInstance](../../mfc/reference/cwinapp-class.md#initinstance) function of its application object. This object is then passed to [CWinApp::ParseCommandLine](../../mfc/reference/cwinapp-class.md#parsecommandline), which repeatedly calls [ParseParam](#parseparam) to fill the `CCommandLineInfo` object. The `CCommandLineInfo` object is then passed to [CWinApp::ProcessShellCommand](../../mfc/reference/cwinapp-class.md#processshellcommand) to handle the command-line arguments and flags. +An MFC application will typically create a local instance of this class in the [`InitInstance`](../../mfc/reference/cwinapp-class.md#initinstance) function of its application object. This object is then passed to [`CWinApp::ParseCommandLine`](../../mfc/reference/cwinapp-class.md#parsecommandline), which repeatedly calls [`ParseParam`](#parseparam) to fill the `CCommandLineInfo` object. The `CCommandLineInfo` object is then passed to [`CWinApp::ProcessShellCommand`](../../mfc/reference/cwinapp-class.md#processshellcommand) to handle the command-line arguments and flags. You can use this object to encapsulate the following command-line options and parameters: @@ -62,7 +61,7 @@ You can use this object to encapsulate the following command-line options and pa |*app* `/Register`

*app* `/Regserver`|Informs the application to perform any registration tasks.| |*app* `/Unregister`

*app* `/Unregserver`|Informs the application to perform any un-registration tasks.| -Derive a new class from `CCommandLineInfo` to handle other flags and parameter values. Override [ParseParam](#parseparam) to handle the new flags. +Derive a new class from `CCommandLineInfo` to handle other flags and parameter values. Override [`ParseParam`](#parseparam) to handle the new flags. ## Inheritance Hierarchy @@ -72,9 +71,9 @@ Derive a new class from `CCommandLineInfo` to handle other flags and parameter v ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CCommandLineInfo::CCommandLineInfo +## `CCommandLineInfo::CCommandLineInfo` This constructor creates a `CCommandLineInfo` object with default values. @@ -84,15 +83,15 @@ CCommandLineInfo(); ### Remarks -The default is to show the splash screen ( `m_bShowSplash=TRUE`) and to execute the New command on the File menu ( `m_nShellCommand`**=NewFile**). +The default is to show the splash screen (`m_bShowSplash=TRUE`) and to execute the **New** command on the **File** menu (`m_nShellCommand`**`=NewFile`**). -The application framework calls [ParseParam](#parseparam) to fill data members of this object. +The application framework calls [`ParseParam`](#parseparam) to fill data members of this object. ### Example [!code-cpp[NVC_MFCDocView#54](../../mfc/codesnippet/cpp/ccommandlineinfo-class_1.cpp)] -## CCommandLineInfo::m_bRunAutomated +## `CCommandLineInfo::m_bRunAutomated` Indicates that the `/Automation` flag was found on the command line. @@ -102,9 +101,9 @@ BOOL m_bRunAutomated; ### Remarks -If TRUE, this means start up as an OLE automation server. +If `TRUE`, this means start up as an OLE automation server. -## CCommandLineInfo::m_bRunEmbedded +## `CCommandLineInfo::m_bRunEmbedded` Indicates that the `/Embedding` flag was found on the command line. @@ -114,9 +113,9 @@ BOOL m_bRunEmbedded; ### Remarks -If TRUE, this means start up for editing an embedded OLE item. +If `TRUE`, this means start up for editing an embedded OLE item. -## CCommandLineInfo::m_bShowSplash +## `CCommandLineInfo::m_bShowSplash` Indicates that the splash screen should be displayed. @@ -126,9 +125,9 @@ BOOL m_bShowSplash; ### Remarks -If TRUE, this means the splash screen for this application should be displayed during startup. The default implementation of [ParseParam](#parseparam) sets this data member to TRUE if [m_nShellCommand](#m_nshellcommand) is equal to `CCommandLineInfo::FileNew`. +If `TRUE`, this means the splash screen for this application should be displayed during startup. The default implementation of [`ParseParam`](#parseparam) sets this data member to `TRUE` if [`m_nShellCommand`](#m_nshellcommand) is equal to `CCommandLineInfo::FileNew`. -## CCommandLineInfo::m_nShellCommand +## `CCommandLineInfo::m_nShellCommand` Indicates the shell command for this instance of the application. @@ -172,13 +171,13 @@ For a brief description of these values, see the following list. - `CCommandLineInfo::RestartByRestartManager` Indicates that the application was restarted by the restart manager. -- `CCommandLineInfo::FileNothing` Turns off the display of a new MDI child window on startup. By design, Application Wizard-generated MDI applications display a new child window on startup. To turn off this feature, an application can use `CCommandLineInfo::FileNothing` as the shell command when it calls [ProcessShellCommand](../../mfc/reference/cwinapp-class.md#processshellcommand). `ProcessShellCommand` is called by the `InitInstance( )` of all `CWinApp` derived classes. +- `CCommandLineInfo::FileNothing` Turns off the display of a new MDI child window on startup. By design, Application Wizard-generated MDI applications display a new child window on startup. To turn off this feature, an application can use `CCommandLineInfo::FileNothing` as the shell command when it calls [`ProcessShellCommand`](../../mfc/reference/cwinapp-class.md#processshellcommand). `ProcessShellCommand` is called by the `InitInstance( )` of all `CWinApp` derived classes. ### Example [!code-cpp[NVC_MFCDocView#55](../../mfc/codesnippet/cpp/ccommandlineinfo-class_2.cpp)] -## CCommandLineInfo::m_strDriverName +## `CCommandLineInfo::m_strDriverName` Stores the value of the third non-flag parameter on the command line. @@ -188,9 +187,9 @@ CString m_strDriverName; ### Remarks -This parameter is typically the name of the printer driver for a Print To shell command. The default implementation of [ParseParam](#parseparam) sets this data member only if the `/pt` flag was found on the command line. +This parameter is typically the name of the printer driver for a Print To shell command. The default implementation of [`ParseParam`](#parseparam) sets this data member only if the `/pt` flag was found on the command line. -## CCommandLineInfo::m_strFileName +## `CCommandLineInfo::m_strFileName` Stores the value of the first non-flag parameter on the command line. @@ -202,7 +201,7 @@ CString m_strFileName; This parameter is typically the name of the file to open. -## CCommandLineInfo::m_strPortName +## `CCommandLineInfo::m_strPortName` Stores the value of the fourth non-flag parameter on the command line. @@ -212,9 +211,9 @@ CString m_strPortName; ### Remarks -This parameter is typically the name of the printer port for a Print To shell command. The default implementation of [ParseParam](#parseparam) sets this data member only if the `/pt` flag was found on the command line. +This parameter is typically the name of the printer port for a Print To shell command. The default implementation of [`ParseParam`](#parseparam) sets this data member only if the `/pt` flag was found on the command line. -## CCommandLineInfo::m_strPrinterName +## `CCommandLineInfo::m_strPrinterName` Stores the value of the second non-flag parameter on the command line. @@ -224,9 +223,9 @@ CString m_strPrinterName; ### Remarks -This parameter is typically the name of the printer for a Print To shell command. The default implementation of [ParseParam](#parseparam) sets this data member only if the `/pt` flag was found on the command line. +This parameter is typically the name of the printer for a Print To shell command. The default implementation of [`ParseParam`](#parseparam) sets this data member only if the `/pt` flag was found on the command line. -## CCommandLineInfo::m_strRestartIdentifier +## `CCommandLineInfo::m_strRestartIdentifier` The unique restart identifier on the command line. @@ -240,7 +239,7 @@ The restart identifier is unique for each instance of the application. If the restart manager exits the application and is configured to restart it, the restart manager executes the application from the command line with the restart identifier as an optional parameter. When the restart manager uses the restart identifier, the application can reopen the previously open documents and recover autosaved files. -## CCommandLineInfo::ParseParam +## `CCommandLineInfo::ParseParam` The framework calls this function to parse/interpret individual parameters from the command line. The second version differs from the first only in Unicode projects. @@ -258,18 +257,18 @@ virtual void ParseParam( ### Parameters -*pszParam*
+*`pszParam`*\ The parameter or flag. -*bFlag*
-Indicates whether *pszParam* is a parameter or a flag. +*`bFlag`*\ +Indicates whether *`pszParam`* is a parameter or a flag. -*bLast*
+*`bLast`*\ Indicates if this is the last parameter or flag on the command line. ### Remarks -[CWinApp::ParseCommandLine](../../mfc/reference/cwinapp-class.md#parsecommandline) calls `ParseParam` once for each parameter or flag on the command line, passing the argument to *pszParam*. If the first character of the parameter is a ' **-**' or a ' **/**', then it is removed and *bFlag* is set to TRUE. When parsing the final parameter, *bLast* is set to TRUE. +[`CWinApp::ParseCommandLine`](../../mfc/reference/cwinapp-class.md#parsecommandline) calls `ParseParam` once for each parameter or flag on the command line, passing the argument to *`pszParam`*. If the first character of the parameter is a **`-`** or a **`/`**, then it's removed and *`bFlag`* is set to `TRUE`. When parsing the final parameter, *`bLast`* is set to `TRUE`. The default implementation of this function recognizes the following flags: `/p`, `/pt`, `/dde`, `/Automation`, and `/Embedding`, as shown in the following table: @@ -285,17 +284,17 @@ The default implementation of this function recognizes the following flags: `/p` |*app* `/Register`

*app* `/Regserver`|Informs the application to perform any registration tasks.| |*app* `/Unregister`

*app* `/Unregserver`|Informs the application to perform any un-registration tasks.| -This information is stored in [m_bRunAutomated](#m_brunautomated), [m_bRunEmbedded](#m_brunembedded), and [m_nShellCommand](#m_nshellcommand). Flags are marked by either a forward-slash ' **/**' or hyphen ' **-**'. +This information is stored in [`m_bRunAutomated`](#m_brunautomated), [`m_bRunEmbedded`](#m_brunembedded), and [`m_nShellCommand`](#m_nshellcommand). Flags are marked by either a forward-slash **`/`** or hyphen **`-`**. -The default implementation puts the first non-flag parameter into [m_strFileName](#m_strfilename). In the case of the `/pt` flag, the default implementation puts the second, third, and fourth non-flag parameters into [m_strPrinterName](#m_strprintername), [m_strDriverName](#m_strdrivername), and [m_strPortName](#m_strportname), respectively. +The default implementation puts the first non-flag parameter into [`m_strFileName`](#m_strfilename). In the case of the `/pt` flag, the default implementation puts the second, third, and fourth non-flag parameters into [`m_strPrinterName`](#m_strprintername), [`m_strDriverName`](#m_strdrivername), and [`m_strPortName`](#m_strportname), respectively. -The default implementation also sets [m_bShowSplash](#m_bshowsplash) to TRUE only in the case of a new file. In the case of a new file, the user has taken action involving the application itself. In any other case, including opening existing files using the shell, the user action involves the file directly. In a document-centric standpoint, the splash screen does not need to announce the application starting up. +The default implementation also sets [`m_bShowSplash`](#m_bshowsplash) to `TRUE` only in the case of a new file. In the case of a new file, the user has taken action involving the application itself. In any other case, including opening existing files using the shell, the user action involves the file directly. In a document-centric standpoint, the splash screen doesn't need to announce the application starting up. Override this function in your derived class to handle other flag and parameter values. ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CWinApp::ParseCommandLine](../../mfc/reference/cwinapp-class.md#parsecommandline)
-[CWinApp::ProcessShellCommand](../../mfc/reference/cwinapp-class.md#processshellcommand) +[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CWinApp::ParseCommandLine`](../../mfc/reference/cwinapp-class.md#parsecommandline)\ +[`CWinApp::ProcessShellCommand`](../../mfc/reference/cwinapp-class.md#processshellcommand) diff --git a/docs/mfc/reference/ccontrolbar-class.md b/docs/mfc/reference/ccontrolbar-class.md index 1384d50c93..d8ab52bf13 100644 --- a/docs/mfc/reference/ccontrolbar-class.md +++ b/docs/mfc/reference/ccontrolbar-class.md @@ -94,7 +94,7 @@ virtual CSize CalcDynamicLayout( The requested dimension of the control bar, either horizontal or vertical, depending on *dwMode*. *nMode*
-The following predefined flags are used to determine the height and width of the dynamic control bar. Use the bitwise-OR (|) operator to combine the flags. +The following predefined flags are used to determine the height and width of the dynamic control bar. Use the bitwise-OR (**`|`**) operator to combine the flags. |Layout mode flags|What it means| |-----------------------|-------------------| diff --git a/docs/mfc/reference/ccriticalsection-class.md b/docs/mfc/reference/ccriticalsection-class.md index 76880ec4a3..5f74738731 100644 --- a/docs/mfc/reference/ccriticalsection-class.md +++ b/docs/mfc/reference/ccriticalsection-class.md @@ -4,9 +4,8 @@ title: "CCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CCriticalSection", "AFXMT/CCriticalSection", "AFXMT/CCriticalSection::CCriticalSection", "AFXMT/CCriticalSection::Lock", "AFXMT/CCriticalSection::Unlock", "AFXMT/CCriticalSection::m_sect"] helpviewer_keywords: ["CCriticalSection [MFC], CCriticalSection", "CCriticalSection [MFC], Lock", "CCriticalSection [MFC], Unlock", "CCriticalSection [MFC], m_sect"] -ms.assetid: f776f74b-5b0b-4f32-9c13-2b8e4a0d7b2b --- -# CCriticalSection Class +# `CCriticalSection` Class Represents a "critical section" — a synchronization object that allows one thread at a time to access a resource or section of code. @@ -22,41 +21,41 @@ class CCriticalSection : public CSyncObject |Name|Description| |----------|-----------------| -|[CCriticalSection::CCriticalSection](#ccriticalsection)|Constructs a `CCriticalSection` object.| +|[`CCriticalSection::CCriticalSection`](#ccriticalsection)|Constructs a `CCriticalSection` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CCriticalSection::Lock](#lock)|Use to gain access to the `CCriticalSection` object.| -|[CCriticalSection::Unlock](#unlock)|Releases the `CCriticalSection` object.| +|[`CCriticalSection::Lock`](#lock)|Use to gain access to the `CCriticalSection` object.| +|[`CCriticalSection::Unlock`](#unlock)|Releases the `CCriticalSection` object.| ### Public Operators |Name|Description| |----------|-----------------| -|[CCriticalSection::operator CRITICAL_SECTION*](#operator_critical_section_star)|Retrieves a pointer to the internal CRITICAL_SECTION object.| +|[`CCriticalSection::operator CRITICAL_SECTION*`](#operator_critical_section_star)|Retrieves a pointer to the internal `CRITICAL_SECTION` object.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CCriticalSection::m_sect](#m_sect)|A CRITICAL_SECTION object.| +|[`CCriticalSection::m_sect`](#m_sect)|A `CRITICAL_SECTION` object.| ## Remarks Critical sections are useful when only one thread at a time can be allowed to modify data or some other controlled resource. For example, adding nodes to a linked list is a process that should only be allowed by one thread at a time. By using a `CCriticalSection` object to control the linked list, only one thread at a time can gain access to the list. > [!NOTE] -> The functionality of the `CCriticalSection` class is provided by an actual Win32 CRITICAL_SECTION object. +> The functionality of the `CCriticalSection` class is provided by an actual Win32 `CRITICAL_SECTION` object. -Critical sections are used instead of mutexes (see [CMutex](../../mfc/reference/cmutex-class.md)) when speed is critical and the resource will not be used across process boundaries. +Critical sections are used instead of mutexes (see [`CMutex`](../../mfc/reference/cmutex-class.md)) when speed is critical and the resource won't be used across process boundaries. There are two methods for using a `CCriticalSection` object: stand-alone and embedded in a class. -- Stand-alone method To use a stand-alone `CCriticalSection` object, construct the `CCriticalSection` object when it is needed. After a successful return from the constructor, explicitly lock the object with a call to [Lock](#lock). Call [Unlock](#unlock) when you are done accessing the critical section. This method, while clearer to someone reading your source code, is more prone to error as you must remember to lock and unlock the critical section before and after access. +- Stand-alone method To use a stand-alone `CCriticalSection` object, construct the `CCriticalSection` object when it's needed. After a successful return from the constructor, explicitly lock the object with a call to [`Lock`](#lock). Call [`Unlock`](#unlock) when you're done accessing the critical section. This method, while clearer to someone reading your source code, is more prone to error as you must remember to lock and unlock the critical section before and after access. - A more preferable method is to use the [CSingleLock](../../mfc/reference/csinglelock-class.md) class. It also has a `Lock` and `Unlock` method, but you don't have to worry about unlocking the resource if an exception occurs. + A more preferable method is to use the [`CSingleLock`](../../mfc/reference/csinglelock-class.md) class. It also has a `Lock` and `Unlock` method, but you don't have to worry about unlocking the resource if an exception occurs. - Embedded method You can also share a class with multiple threads by adding a `CCriticalSection`-type data member to the class and locking the data member when needed. @@ -64,17 +63,17 @@ For more information on using `CCriticalSection` objects, see the article [Multi ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CSyncObject](../../mfc/reference/csyncobject-class.md) +[`CSyncObject`](../../mfc/reference/csyncobject-class.md) `CCriticalSection` ## Requirements -**Header:** afxmt.h +**Header:** `afxmt.h` -## CCriticalSection::CCriticalSection +## `CCriticalSection::CCriticalSection` Constructs a `CCriticalSection` object. @@ -84,15 +83,15 @@ CCriticalSection(); ### Remarks -To access or release a `CCriticalSection` object, create a [CSingleLock](../../mfc/reference/csinglelock-class.md) object and call its [Lock](../../mfc/reference/csinglelock-class.md#lock) and [Unlock](../../mfc/reference/csinglelock-class.md#unlock) member functions. If the `CCriticalSection` object is being used stand-alone, call its [Unlock](#unlock) member function to release it. +To access or release a `CCriticalSection` object, create a [`CSingleLock`](../../mfc/reference/csinglelock-class.md) object and call its [`Lock`](../../mfc/reference/csinglelock-class.md#lock) and [`Unlock`](../../mfc/reference/csinglelock-class.md#unlock) member functions. If the `CCriticalSection` object is being used stand-alone, call its [`Unlock`](#unlock) member function to release it. -If the constructor fails to allocate the required system memory, a memory exception (of type [CMemoryException](../../mfc/reference/cmemoryexception-class.md)) is automatically thrown. +If the constructor fails to allocate the required system memory, a memory exception (of type [`CMemoryException`](../../mfc/reference/cmemoryexception-class.md)) is automatically thrown. ### Example See the example for [CCriticalSection::Lock](#lock). -## CCriticalSection::Lock +## `CCriticalSection::Lock` Call this member function to gain access to the critical section object. @@ -103,7 +102,7 @@ BOOL Lock(DWORD dwTimeout); ### Parameters -*dwTimeout*
+*`dwTimeout`* `Lock` ignores this parameter value. ### Return Value @@ -112,11 +111,11 @@ Nonzero if the function was successful; otherwise 0. ### Remarks -`Lock` is a blocking call that will not return until the critical section object is signaled (becomes available). +`Lock` is a blocking call that won't return until the critical section object is signaled (becomes available). -If timed waits are necessary, you can use a [CMutex](../../mfc/reference/cmutex-class.md) object instead of a `CCriticalSection` object. +If timed waits are necessary, you can use a [`CMutex`](../../mfc/reference/cmutex-class.md) object instead of a `CCriticalSection` object. -If `Lock` fails to allocate the necessary system memory, a memory exception (of type [CMemoryException](../../mfc/reference/cmemoryexception-class.md)) is automatically thrown. +If `Lock` fails to allocate the necessary system memory, a memory exception (of type [`CMemoryException`](../../mfc/reference/cmemoryexception-class.md)) is automatically thrown. ### Example @@ -124,7 +123,7 @@ This example demonstrates the nested critical section approach by controlling ac [!code-cpp[NVC_MFC_Utilities#11](../../mfc/codesnippet/cpp/ccriticalsection-class_1.h)] -## CCriticalSection::m_sect +## `CCriticalSection::m_sect` Contains a critical section object that is used by all `CCriticalSection` methods. @@ -132,9 +131,9 @@ Contains a critical section object that is used by all `CCriticalSection` method CRITICAL_SECTION m_sect; ``` -## CCriticalSection::operator CRITICAL_SECTION* +## `CCriticalSection::operator CRITICAL_SECTION*` -Retrieves a CRITICAL_SECTION object. +Retrieves a `CRITICAL_SECTION` object. ``` operator CRITICAL_SECTION*(); @@ -142,9 +141,9 @@ operator CRITICAL_SECTION*(); ### Remarks -Call this function to retrieve a pointer to the internal CRITICAL_SECTION object. +Call this function to retrieve a pointer to the internal `CRITICAL_SECTION` object. -## CCriticalSection::Unlock +## `CCriticalSection::Unlock` Releases the `CCriticalSection` object for use by another thread. @@ -158,14 +157,14 @@ Nonzero if the `CCriticalSection` object was owned by the thread and the release ### Remarks -If the `CCriticalSection` is being used stand-alone, `Unlock` must be called immediately after completing use of the resource controlled by the critical section. If a [CSingleLock](../../mfc/reference/csinglelock-class.md) object is being used, `CCriticalSection::Unlock` will be called by the lock object's `Unlock` member function. +If the `CCriticalSection` is being used stand-alone, `Unlock` must be called immediately after completing use of the resource controlled by the critical section. If a [`CSingleLock`](../../mfc/reference/csinglelock-class.md) object is being used, `CCriticalSection::Unlock` will be called by the lock object's `Unlock` member function. ### Example - See the example for [CCriticalSection::Lock](#lock). + See the example for [`CCriticalSection::Lock`](#lock). ## See also -[CSyncObject Class](../../mfc/reference/csyncobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CMutex Class](../../mfc/reference/cmutex-class.md) +[`CSyncObject` Class](../../mfc/reference/csyncobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CMutex` Class](../../mfc/reference/cmutex-class.md) diff --git a/docs/mfc/reference/cd2dbitmap-class.md b/docs/mfc/reference/cd2dbitmap-class.md index 576532f317..9527c8a653 100644 --- a/docs/mfc/reference/cd2dbitmap-class.md +++ b/docs/mfc/reference/cd2dbitmap-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CD2DBitmap Class" title: "CD2DBitmap Class" +description: "Learn more about: CD2DBitmap Class" ms.date: "11/04/2016" f1_keywords: ["CD2DBitmap", "AFXRENDERTARGET/CD2DBitmap", "AFXRENDERTARGET/CD2DBitmap::CD2DBitmap", "AFXRENDERTARGET/CD2DBitmap::Attach", "AFXRENDERTARGET/CD2DBitmap::CopyFromBitmap", "AFXRENDERTARGET/CD2DBitmap::CopyFromMemory", "AFXRENDERTARGET/CD2DBitmap::CopyFromRenderTarget", "AFXRENDERTARGET/CD2DBitmap::Create", "AFXRENDERTARGET/CD2DBitmap::Destroy", "AFXRENDERTARGET/CD2DBitmap::Detach", "AFXRENDERTARGET/CD2DBitmap::Get", "AFXRENDERTARGET/CD2DBitmap::GetDPI", "AFXRENDERTARGET/CD2DBitmap::GetPixelFormat", "AFXRENDERTARGET/CD2DBitmap::GetPixelSize", "AFXRENDERTARGET/CD2DBitmap::GetSize", "AFXRENDERTARGET/CD2DBitmap::IsValid", "AFXRENDERTARGET/CD2DBitmap::CommonInit", "AFXRENDERTARGET/CD2DBitmap::m_bAutoDestroyHBMP", "AFXRENDERTARGET/CD2DBitmap::m_hBmpSrc", "AFXRENDERTARGET/CD2DBitmap::m_lpszType", "AFXRENDERTARGET/CD2DBitmap::m_pBitmap", "AFXRENDERTARGET/CD2DBitmap::m_sizeDest", "AFXRENDERTARGET/CD2DBitmap::m_strPath", "AFXRENDERTARGET/CD2DBitmap::m_uiResID"] helpviewer_keywords: ["CD2DBitmap [MFC], CD2DBitmap", "CD2DBitmap [MFC], CD2DBitmap", "CD2DBitmap [MFC], Attach", "CD2DBitmap [MFC], CopyFromBitmap", "CD2DBitmap [MFC], CopyFromMemory", "CD2DBitmap [MFC], CopyFromRenderTarget", "CD2DBitmap [MFC], Create", "CD2DBitmap [MFC], Destroy", "CD2DBitmap [MFC], Detach", "CD2DBitmap [MFC], Get", "CD2DBitmap [MFC], GetDPI", "CD2DBitmap [MFC], GetPixelFormat", "CD2DBitmap [MFC], GetPixelSize", "CD2DBitmap [MFC], GetSize", "CD2DBitmap [MFC], IsValid", "CD2DBitmap [MFC], CommonInit", "CD2DBitmap [MFC], m_bAutoDestroyHBMP", "CD2DBitmap [MFC], m_hBmpSrc", "CD2DBitmap [MFC], m_lpszType", "CD2DBitmap [MFC], m_pBitmap", "CD2DBitmap [MFC], m_sizeDest", "CD2DBitmap [MFC], m_strPath", "CD2DBitmap [MFC], m_uiResID"] -ms.assetid: 2b3686f1-812c-462b-b449-9f0cb6949bf6 --- # CD2DBitmap Class @@ -70,7 +69,7 @@ class CD2DBitmap : public CD2DResource; |[CD2DBitmap::m_lpszType](#m_lpsztype)|Resource type.| |[CD2DBitmap::m_pBitmap](#m_pbitmap)|Stores a pointer to an ID2D1Bitmap object.| |[CD2DBitmap::m_sizeDest](#m_sizedest)|Bitmap destination size.| -|[CD2DBitmap::m_strPath](#m_strpath)|Botmap file path.| +|[CD2DBitmap::m_strPath](#m_strpath)|Bitmap file path.| |[CD2DBitmap::m_uiResID](#m_uiresid)|Bitmap resource ID.| ## Inheritance Hierarchy @@ -327,7 +326,7 @@ CD2DSizeU GetPixelSize() const; ### Return Value -The size, in pixels, of the bitmap.. +The size, in pixels, of the bitmap. ## CD2DBitmap::GetSize diff --git a/docs/mfc/reference/cd2dbrush-class.md b/docs/mfc/reference/cd2dbrush-class.md index 1e7dc1032f..937159f768 100644 --- a/docs/mfc/reference/cd2dbrush-class.md +++ b/docs/mfc/reference/cd2dbrush-class.md @@ -4,11 +4,10 @@ title: "CD2DBrush Class" ms.date: "11/04/2016" f1_keywords: ["CD2DBrush", "AFXRENDERTARGET/CD2DBrush", "AFXRENDERTARGET/CD2DBrush::CD2DBrush", "AFXRENDERTARGET/CD2DBrush::Attach", "AFXRENDERTARGET/CD2DBrush::Destroy", "AFXRENDERTARGET/CD2DBrush::Detach", "AFXRENDERTARGET/CD2DBrush::Get", "AFXRENDERTARGET/CD2DBrush::GetOpacity", "AFXRENDERTARGET/CD2DBrush::GetTransform", "AFXRENDERTARGET/CD2DBrush::IsValid", "AFXRENDERTARGET/CD2DBrush::SetOpacity", "AFXRENDERTARGET/CD2DBrush::SetTransform", "AFXRENDERTARGET/CD2DBrush::m_pBrush", "AFXRENDERTARGET/CD2DBrush::m_pBrushProperties"] helpviewer_keywords: ["CD2DBrush [MFC], CD2DBrush", "CD2DBrush [MFC], Attach", "CD2DBrush [MFC], Destroy", "CD2DBrush [MFC], Detach", "CD2DBrush [MFC], Get", "CD2DBrush [MFC], GetOpacity", "CD2DBrush [MFC], GetTransform", "CD2DBrush [MFC], IsValid", "CD2DBrush [MFC], SetOpacity", "CD2DBrush [MFC], SetTransform", "CD2DBrush [MFC], m_pBrush", "CD2DBrush [MFC], m_pBrushProperties"] -ms.assetid: 0d2c0857-2261-48a8-8ee0-a88cbf08499a --- -# CD2DBrush Class +# `CD2DBrush` Class -A wrapper for ID2D1Brush. +A wrapper for `ID2D1Brush`. ## Syntax @@ -22,57 +21,57 @@ class CD2DBrush : public CD2DResource; |Name|Description| |----------|-----------------| -|[CD2DBrush::CD2DBrush](#cd2dbrush)|Constructs a CD2DBrush object.| -|[CD2DBrush::~CD2DBrush](#_dtorcd2dbrush)|The destructor. Called when a D2D brush object is being destroyed.| +|[`CD2DBrush::CD2DBrush`](#cd2dbrush)|Constructs a `CD2DBrush` object.| +|[`CD2DBrush::~CD2DBrush`](#_dtorcd2dbrush)|The destructor. Called when a D2D brush object is being destroyed.| ### Public Methods |Name|Description| |----------|-----------------| -|[CD2DBrush::Attach](#attach)|Attaches existing resource interface to the object| -|[CD2DBrush::Destroy](#destroy)|Destroys a CD2DBrush object. (Overrides [CD2DResource::Destroy](../../mfc/reference/cd2dresource-class.md#destroy).)| -|[CD2DBrush::Detach](#detach)|Detaches resource interface from the object| -|[CD2DBrush::Get](#get)|Returns ID2D1Brush interface| -|[CD2DBrush::GetOpacity](#getopacity)|Gets the degree of opacity of this brush| -|[CD2DBrush::GetTransform](#gettransform)|Gets the current transform of the render target| -|[CD2DBrush::IsValid](#isvalid)|Checks resource validity (Overrides [CD2DResource::IsValid](../../mfc/reference/cd2dresource-class.md#isvalid).)| -|[CD2DBrush::SetOpacity](#setopacity)|Sets the degree of opacity of this brush| -|[CD2DBrush::SetTransform](#settransform)|Applies the specified transform to the render target, replacing the existing transformation. All subsequent drawing operations occur in the transformed space| +|[`CD2DBrush::Attach`](#attach)|Attaches existing resource interface to the object| +|[`CD2DBrush::Destroy`](#destroy)|Destroys a `CD2DBrush` object. (Overrides [`CD2DResource::Destroy`](../../mfc/reference/cd2dresource-class.md#destroy).)| +|[`CD2DBrush::Detach`](#detach)|Detaches resource interface from the object| +|[`CD2DBrush::Get`](#get)|Returns `ID2D1Brush` interface| +|[`CD2DBrush::GetOpacity`](#getopacity)|Gets the degree of opacity of this brush| +|[`CD2DBrush::GetTransform`](#gettransform)|Gets the current transform of the brush| +|[`CD2DBrush::IsValid`](#isvalid)|Checks resource validity (Overrides [`CD2DResource::IsValid`](../../mfc/reference/cd2dresource-class.md#isvalid).)| +|[`CD2DBrush::SetOpacity`](#setopacity)|Sets the degree of opacity of this brush| +|[`CD2DBrush::SetTransform`](#settransform)|Applies the specified transform to the brush, replacing the existing transformation. All subsequent drawing operations occur in the transformed space| ### Public Operators |Name|Description| |----------|-----------------| -|[CD2DBrush::operator ID2D1Brush*](#operator_id2d1brush_star)|Returns ID2D1Brush interface| +|[`CD2DBrush::operator ID2D1Brush*`](#operator_id2d1brush_star)|Returns `ID2D1Brush` interface| ### Protected Data Members |Name|Description| |----------|-----------------| -|[CD2DBrush::m_pBrush](#m_pbrush)|Stores a pointer to an ID2D1Brush object.| -|[CD2DBrush::m_pBrushProperties](#m_pbrushproperties)|Brush properties.| +|[`CD2DBrush::m_pBrush`](#m_pbrush)|Stores a pointer to an `ID2D1Brush` object.| +|[`CD2DBrush::m_pBrushProperties`](#m_pbrushproperties)|Brush properties.| ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CD2DResource](../../mfc/reference/cd2dresource-class.md) +[`CD2DResource`](../../mfc/reference/cd2dresource-class.md) `CD2DBrush` ## Requirements -**Header:** afxrendertarget.h +**Header:** `afxrendertarget.h` -## CD2DBrush::~CD2DBrush +## `CD2DBrush::~CD2DBrush` -The destructor. Called when a D2D brush object is being destroyed. +The destructor. Called when a `D2D` brush object is being destroyed. ``` virtual ~CD2DBrush(); ``` -## CD2DBrush::Attach +## `CD2DBrush::Attach` Attaches existing resource interface to the object. @@ -82,12 +81,12 @@ void Attach(ID2D1Brush* pResource); ### Parameters -*pResource*
-Existing resource interface. Cannot be NULL. +*`pResource`*\ +Existing resource interface. Can't be `NULL`. -## CD2DBrush::CD2DBrush +## `CD2DBrush::CD2DBrush` -Constructs a CD2DBrush object. +Constructs a `CD2DBrush` object. ``` CD2DBrush( @@ -98,24 +97,24 @@ CD2DBrush( ### Parameters -*pParentTarget*
+*`pParentTarget`*\ A pointer to the render target. -*pBrushProperties*
+*`pBrushProperties`*\ A pointer to the opacity and transformation of a brush. -*bAutoDestroy*
-Indicates that the object will be destroyed by owner (pParentTarget). +*`bAutoDestroy`*\ +Indicates that the owner (`pParentTarget`) destroys the object. -## CD2DBrush::Destroy +## `CD2DBrush::Destroy` -Destroys a CD2DBrush object. +Destroys a `CD2DBrush` object. ``` virtual void Destroy(); ``` -## CD2DBrush::Detach +## `CD2DBrush::Detach` Detaches resource interface from the object. @@ -127,9 +126,9 @@ ID2D1Brush* Detach(); Pointer to detached resource interface. -## CD2DBrush::Get +## `CD2DBrush::Get` -Returns ID2D1Brush interface +Returns `ID2D1Brush` interface ``` ID2D1Brush* Get(); @@ -137,9 +136,9 @@ ID2D1Brush* Get(); ### Return Value -Pointer to an ID2D1Brush interface or NULL if object is not initialized yet. +Pointer to an `ID2D1Brush` interface or `NULL` if object isn't initialized yet. -## CD2DBrush::GetOpacity +## `CD2DBrush::GetOpacity` Gets the degree of opacity of this brush @@ -149,11 +148,11 @@ FLOAT GetOpacity() const; ### Return Value -A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0 to 1 before they are multiplied together. +A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0 to 1 before they're multiplied together. -## CD2DBrush::GetTransform +## `CD2DBrush::GetTransform` -Gets the current transform of the render target +Gets the current transform of the brush ```cpp void GetTransform(D2D1_MATRIX_3X2_F* transform) const; @@ -161,10 +160,10 @@ void GetTransform(D2D1_MATRIX_3X2_F* transform) const; ### Parameters -*transform*
-When this returns, contains the current transform of the render target. This parameter is passed uninitialized. +*`transform`*\ +When this returns, contains the current transform of the brush. This parameter is passed uninitialized. -## CD2DBrush::IsValid +## `CD2DBrush::IsValid` Checks resource validity @@ -174,17 +173,17 @@ virtual BOOL IsValid() const; ### Return Value -TRUE if resource is valid; otherwise FALSE. +`TRUE` if resource is valid; otherwise `FALSE`. -## CD2DBrush::m_pBrush +## `CD2DBrush::m_pBrush` -Stores a pointer to an ID2D1Brush object. +Stores a pointer to an `ID2D1Brush` object. ``` ID2D1Brush* m_pBrush; ``` -## CD2DBrush::m_pBrushProperties +## `CD2DBrush::m_pBrushProperties` Brush properties. @@ -192,9 +191,9 @@ Brush properties. CD2DBrushProperties* m_pBrushProperties; ``` -## CD2DBrush::operator ID2D1Brush* +## `CD2DBrush::operator ID2D1Brush*` -Returns ID2D1Brush interface +Returns `ID2D1Brush` interface ``` operator ID2D1Brush*(); @@ -202,9 +201,9 @@ operator ID2D1Brush*(); ### Return Value -Pointer to an ID2D1Brush interface or NULL if object is not initialized yet. +Pointer to an `ID2D1Brush` interface or NULL if object isn't initialized yet. -## CD2DBrush::SetOpacity +## `CD2DBrush::SetOpacity` Sets the degree of opacity of this brush @@ -214,12 +213,12 @@ void SetOpacity(FLOAT opacity); ### Parameters -*opacity*
-A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0 to 1 before they are multiplied together. +*`opacity`*\ +A value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0 to 1 before they're multiplied together. -## CD2DBrush::SetTransform +## `CD2DBrush::SetTransform` -Applies the specified transform to the render target, replacing the existing transformation. All subsequent drawing operations occur in the transformed space. +Applies the specified transform to the brush, replacing the existing transformation. All subsequent drawing operations occur in the transformed space. ```cpp void SetTransform(const D2D1_MATRIX_3X2_F* transform); @@ -227,8 +226,8 @@ void SetTransform(const D2D1_MATRIX_3X2_F* transform); ### Parameters -*transform*
-The transform to apply to the render target +*`transform`*\ +The transform to apply to the brush ## See also diff --git a/docs/mfc/reference/cd2dgeometry-class.md b/docs/mfc/reference/cd2dgeometry-class.md index 1c6a4178da..e15757a976 100644 --- a/docs/mfc/reference/cd2dgeometry-class.md +++ b/docs/mfc/reference/cd2dgeometry-class.md @@ -239,7 +239,7 @@ BOOL ComputePointAtLength( ### Parameters *length*
-The distance along the geometry of the point and tangent to find. If this distance is less then 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry. +The distance along the geometry of the point and tangent to find. If this distance is less than 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry. *worldTransform*
The transform to apply to the geometry before calculating the specified point and tangent. diff --git a/docs/mfc/reference/cd2dpathgeometry-class.md b/docs/mfc/reference/cd2dpathgeometry-class.md index 26d66a55e5..c8a9259457 100644 --- a/docs/mfc/reference/cd2dpathgeometry-class.md +++ b/docs/mfc/reference/cd2dpathgeometry-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CD2DPathGeometry Class" title: "CD2DPathGeometry Class" +description: "Learn more about: CD2DPathGeometry Class" ms.date: "11/04/2016" f1_keywords: ["CD2DPathGeometry", "AFXRENDERTARGET/CD2DPathGeometry", "AFXRENDERTARGET/CD2DPathGeometry::CD2DPathGeometry", "AFXRENDERTARGET/CD2DPathGeometry::Attach", "AFXRENDERTARGET/CD2DPathGeometry::Create", "AFXRENDERTARGET/CD2DPathGeometry::Destroy", "AFXRENDERTARGET/CD2DPathGeometry::Detach", "AFXRENDERTARGET/CD2DPathGeometry::GetFigureCount", "AFXRENDERTARGET/CD2DPathGeometry::GetSegmentCount", "AFXRENDERTARGET/CD2DPathGeometry::Open", "AFXRENDERTARGET/CD2DPathGeometry::Stream", "AFXRENDERTARGET/CD2DPathGeometry::m_pPathGeometry"] helpviewer_keywords: ["CD2DPathGeometry [MFC], CD2DPathGeometry", "CD2DPathGeometry [MFC], Attach", "CD2DPathGeometry [MFC], Create", "CD2DPathGeometry [MFC], Destroy", "CD2DPathGeometry [MFC], Detach", "CD2DPathGeometry [MFC], GetFigureCount", "CD2DPathGeometry [MFC], GetSegmentCount", "CD2DPathGeometry [MFC], Open", "CD2DPathGeometry [MFC], Stream", "CD2DPathGeometry [MFC], m_pPathGeometry"] -ms.assetid: 686216eb-5080-4242-ace5-8fa1ce96307c --- # CD2DPathGeometry Class @@ -32,7 +31,7 @@ class CD2DPathGeometry : public CD2DGeometry; |[CD2DPathGeometry::Create](#create)|Creates a CD2DPathGeometry. (Overrides [CD2DResource::Create](../../mfc/reference/cd2dresource-class.md#create).)| |[CD2DPathGeometry::Destroy](#destroy)|Destroys a CD2DPathGeometry object. (Overrides [CD2DGeometry::Destroy](../../mfc/reference/cd2dgeometry-class.md#destroy).)| |[CD2DPathGeometry::Detach](#detach)|Detaches resource interface from the object| -|[CD2DPathGeometry::GetFigureCount](#getfigurecount)|Retrieves tthe number of figures in the path geometry.| +|[CD2DPathGeometry::GetFigureCount](#getfigurecount)|Retrieves the number of figures in the path geometry.| |[CD2DPathGeometry::GetSegmentCount](#getsegmentcount)|Retrieves the number of segments in the path geometry.| |[CD2DPathGeometry::Open](#open)|Retrieves the geometry sink that is used to populate the path geometry with figures and segments.| |[CD2DPathGeometry::Stream](#stream)|Copies the contents of the path geometry to the specified ID2D1GeometrySink.| @@ -127,7 +126,7 @@ Pointer to detached resource interface. ## CD2DPathGeometry::GetFigureCount -Retrieves tthe number of figures in the path geometry. +Retrieves the number of figures in the path geometry. ``` int GetFigureCount() const; diff --git a/docs/mfc/reference/cdaodatabase-class.md b/docs/mfc/reference/cdaodatabase-class.md index c096cb773c..a59cea4963 100644 --- a/docs/mfc/reference/cdaodatabase-class.md +++ b/docs/mfc/reference/cdaodatabase-class.md @@ -4,11 +4,13 @@ title: "CDaoDatabase Class" ms.date: "09/17/2019" f1_keywords: ["CDaoDatabase", "AFXDAO/CDaoDatabase", "AFXDAO/CDaoDatabase::CDaoDatabase", "AFXDAO/CDaoDatabase::CanTransact", "AFXDAO/CDaoDatabase::CanUpdate", "AFXDAO/CDaoDatabase::Close", "AFXDAO/CDaoDatabase::Create", "AFXDAO/CDaoDatabase::CreateRelation", "AFXDAO/CDaoDatabase::DeleteQueryDef", "AFXDAO/CDaoDatabase::DeleteRelation", "AFXDAO/CDaoDatabase::DeleteTableDef", "AFXDAO/CDaoDatabase::Execute", "AFXDAO/CDaoDatabase::GetConnect", "AFXDAO/CDaoDatabase::GetName", "AFXDAO/CDaoDatabase::GetQueryDefCount", "AFXDAO/CDaoDatabase::GetQueryDefInfo", "AFXDAO/CDaoDatabase::GetQueryTimeout", "AFXDAO/CDaoDatabase::GetRecordsAffected", "AFXDAO/CDaoDatabase::GetRelationCount", "AFXDAO/CDaoDatabase::GetRelationInfo", "AFXDAO/CDaoDatabase::GetTableDefCount", "AFXDAO/CDaoDatabase::GetTableDefInfo", "AFXDAO/CDaoDatabase::GetVersion", "AFXDAO/CDaoDatabase::IsOpen", "AFXDAO/CDaoDatabase::Open", "AFXDAO/CDaoDatabase::SetQueryTimeout", "AFXDAO/CDaoDatabase::m_pDAODatabase", "AFXDAO/CDaoDatabase::m_pWorkspace"] helpviewer_keywords: ["CDaoDatabase [MFC], CDaoDatabase", "CDaoDatabase [MFC], CanTransact", "CDaoDatabase [MFC], CanUpdate", "CDaoDatabase [MFC], Close", "CDaoDatabase [MFC], Create", "CDaoDatabase [MFC], CreateRelation", "CDaoDatabase [MFC], DeleteQueryDef", "CDaoDatabase [MFC], DeleteRelation", "CDaoDatabase [MFC], DeleteTableDef", "CDaoDatabase [MFC], Execute", "CDaoDatabase [MFC], GetConnect", "CDaoDatabase [MFC], GetName", "CDaoDatabase [MFC], GetQueryDefCount", "CDaoDatabase [MFC], GetQueryDefInfo", "CDaoDatabase [MFC], GetQueryTimeout", "CDaoDatabase [MFC], GetRecordsAffected", "CDaoDatabase [MFC], GetRelationCount", "CDaoDatabase [MFC], GetRelationInfo", "CDaoDatabase [MFC], GetTableDefCount", "CDaoDatabase [MFC], GetTableDefInfo", "CDaoDatabase [MFC], GetVersion", "CDaoDatabase [MFC], IsOpen", "CDaoDatabase [MFC], Open", "CDaoDatabase [MFC], SetQueryTimeout", "CDaoDatabase [MFC], m_pDAODatabase", "CDaoDatabase [MFC], m_pWorkspace"] -ms.assetid: 8ff5b342-964d-449d-bef1-d0ff56aadf6d --- # CDaoDatabase Class -Represents a connection to an Access database using Data Access Objects (DAO). DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. +Represents a connection to an Access database using Data Access Objects (DAO). + +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. ## Syntax @@ -41,7 +43,7 @@ class CDaoDatabase : public CObject |[CDaoDatabase::GetName](#getname)|Returns the name of the database currently in use.| |[CDaoDatabase::GetQueryDefCount](#getquerydefcount)|Returns the number of queries defined for the database.| |[CDaoDatabase::GetQueryDefInfo](#getquerydefinfo)|Returns information about a specified query defined in the database.| -|[CDaoDatabase::GetQueryTimeout](#getquerytimeout)|Returns the number of seconds after which database query operations will time out. Affects all subsequent open, add new, update, and edit operations and other operations on ODBC data sources (only) such as `Execute` calls.| +|[CDaoDatabase::GetQueryTimeout](#getquerytimeout)|Returns the number of seconds after which database query operations time out. Affects all subsequent open, add new, update, and edit operations and other operations on ODBC data sources (only) such as `Execute` calls.| |[CDaoDatabase::GetRecordsAffected](#getrecordsaffected)|Returns the number of records affected by the last update, edit, or add operation or by a call to `Execute`.| |[CDaoDatabase::GetRelationCount](#getrelationcount)|Returns the number of relations defined between tables in the database.| |[CDaoDatabase::GetRelationInfo](#getrelationinfo)|Returns information about a specified relation defined between tables in the database.| @@ -50,7 +52,7 @@ class CDaoDatabase : public CObject |[CDaoDatabase::GetVersion](#getversion)|Returns the version of the database engine associated with the database.| |[CDaoDatabase::IsOpen](#isopen)|Returns nonzero if the `CDaoDatabase` object is currently connected to a database.| |[CDaoDatabase::Open](#open)|Establishes a connection to a database.| -|[CDaoDatabase::SetQueryTimeout](#setquerytimeout)|Sets the number of seconds after which database query operations (on ODBC data sources only) will time out. Affects all subsequent open, add new, update, and delete operations.| +|[CDaoDatabase::SetQueryTimeout](#setquerytimeout)|Sets the number of seconds after which database query operations (on ODBC data sources only) time out. Affects all subsequent open, add new, update, and delete operations.| ### Public Data Members @@ -75,15 +77,15 @@ To create a new Microsoft Jet (.MDB) database, construct a `CDaoDatabase` object To open an existing database, construct a `CDaoDatabase` object and call its [Open](#open) member function. -Any of these techniques appends the DAO database object to the workspace's Databases collection and opens a connection to the data. When you then construct [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md), [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md), or [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) objects for operating on the connected database, pass the constructors for these objects a pointer to your `CDaoDatabase` object. When you finish using the connection, call the [Close](#close) member function and destroy the `CDaoDatabase` object. `Close` closes any recordsets you have not closed previously. +Any of these techniques appends the DAO database object to the workspace's Databases collection and opens a connection to the data. When you then construct [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md), [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md), or [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) objects for operating on the connected database, pass the constructors for these objects a pointer to your `CDaoDatabase` object. When you finish using the connection, call the [Close](#close) member function and destroy the `CDaoDatabase` object. `Close` closes any recordsets you have not already closed. ## Transactions -Database transaction processing is supplied at the workspace level — see the [BeginTrans](../../mfc/reference/cdaoworkspace-class.md#begintrans), [CommitTrans](../../mfc/reference/cdaoworkspace-class.md#committrans), and [Rollback](../../mfc/reference/cdaoworkspace-class.md#rollback) member functions of class `CDaoWorkspace`. +Database transaction processing is supplied at the workspace level—see the [BeginTrans](../../mfc/reference/cdaoworkspace-class.md#begintrans), [CommitTrans](../../mfc/reference/cdaoworkspace-class.md#committrans), and [Rollback](../../mfc/reference/cdaoworkspace-class.md#rollback) member functions of class `CDaoWorkspace`. ## ODBC Connections -The recommended way to work with ODBC data sources is to attach external tables to a Microsoft Jet (.MDB) database. +The recommended way to work with Open Database Base Connectivity (ODBC) data sources is to attach external tables to a Microsoft Jet (`.MDB`) database. ## Collections @@ -94,7 +96,7 @@ Each database maintains its own collections of tabledef, querydef, recordset, an ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) `CDaoDatabase` @@ -168,15 +170,15 @@ virtual void Close(); ### Remarks -It is good practice to close these objects yourself before you call this member function. Closing a `CDaoDatabase` object removes it from the Databases collection in the associated [workspace](../../mfc/reference/cdaoworkspace-class.md). Because `Close` does not destroy the `CDaoDatabase` object, you can reuse the object by opening the same database or a different database. +It's good practice to close these objects yourself before you call this member function. Closing a `CDaoDatabase` object removes it from the Databases collection in the associated [workspace](../../mfc/reference/cdaoworkspace-class.md). Because `Close` doesn't destroy the `CDaoDatabase` object, you can reuse the object by opening the same database or a different database. > [!CAUTION] > Call the [Update](../../mfc/reference/cdaorecordset-class.md#update) member function (if there are pending edits) and the `Close` member function on all open recordset objects before you close a database. If you exit a function that declares [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) or `CDaoDatabase` objects on the stack, the database is closed, any unsaved changes are lost, all pending transactions are rolled back, and any pending edits to your data are lost. > [!CAUTION] -> If you try to close a database object while any recordset objects are open, or if you try to close a workspace object while any database objects belonging to that specific workspace are open, those recordset objects will be closed and any pending updates or edits will be rolled back. If you try to close a workspace object while any database objects belonging to it are open, the operation closes all database objects belonging to that specific workspace object, which may result in unclosed recordset objects being closed. If you do not close your database object, MFC reports an assertion failure in debug builds. +> If you try to close a database object while any recordset objects are open, or if you try to close a workspace object while any database objects belonging to that specific workspace are open, those recordset objects will be closed and any pending updates or edits will be rolled back. If you try to close a workspace object while any database objects belonging to it are open, the operation closes all database objects belonging to that specific workspace object, which may result in unclosed recordset objects being closed. If you don't close your database object, MFC reports an assertion failure in debug builds. -If the database object is defined outside the scope of a function, and you exit the function without closing it, the database object will remain open until explicitly closed or the module in which it is defined is out of scope. +If the database object is defined outside the scope of a function, and you exit the function without closing it, the database object will remain open until explicitly closed or the module in which it's defined is out of scope. ## CDaoDatabase::Create @@ -192,7 +194,7 @@ virtual void Create( ### Parameters *lpszName*
-A string expression that is the name of the database file that you are creating. It can be the full path and filename, such as "C:\\\MYDB.MDB". You must supply a name. If you do not supply a filename extension, .MDB is appended. If your network supports the uniform naming convention (UNC), you can also specify a network path, such as "\\\\\\\MYSERVER\\\MYSHARE\\\MYDIR\\\MYDB". Only Microsoft Jet (.MDB) database files can be created using this member function. (Double backslashes are required in string literals because "\\" is the C++ escape character.) +A string expression that is the name of the database file that you are creating. It can be the full path and filename, such as "C:\\\MYDB.MDB". You must supply a name. If you don't supply a filename extension, .MDB is appended. If your network supports the uniform naming convention (UNC), you can also specify a network path, such as "\\\\\\\MYSERVER\\\MYSHARE\\\MYDIR\\\MYDB". Only Microsoft Jet (.MDB) database files can be created using this member function. (Double backslashes are required in string literals because "\\" is the C++ escape character.) *lpszLocale*
A string expression used to specify collating order for creating the database. The default value is `dbLangGeneral`. Possible values are: @@ -243,11 +245,11 @@ An integer that indicates one or more options. Possible values are: If you omit the encryption constant, an unencrypted database is created. You can specify only one version constant. If you omit a version constant, a database that uses the Microsoft Jet database version 3.0 is created. > [!CAUTION] -> If a database is not encrypted, it is possible, even if you implement user/password security, to directly read the binary disk file that constitutes the database. +> If a database is not encrypted, it's possible, even if you implement user/password security, to directly read the binary disk file that constitutes the database. ### Remarks -`Create` creates the database file and the underlying DAO database object and initializes the C++ object. The object is appended to the associated workspace's Databases collection. The database object is in an open state; do not call `Open*` after `Create`. +`Create` creates the database file and the underlying DAO database object and initializes the C++ object. The object is appended to the associated workspace's Databases collection. The database object is in an open state; don't call `Open*` after `Create`. > [!NOTE] > With `Create`, you can create only Microsoft Jet (.MDB) databases. You cannot create ISAM databases or ODBC databases. @@ -274,13 +276,13 @@ void CreateRelation(CDaoRelationInfo& relinfo); The unique name of the relation object. The name must start with a letter and can contain a maximum of 40 characters. It can include numbers and underscore characters but cannot include punctuation or spaces. *lpszTable*
-The name of the primary table in the relation. If the table does not exist, MFC throws an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). +The name of the primary table in the relation. If the table doesn't exist, MFC throws an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). *lpszForeignTable*
-The name of the foreign table in the relation. If the table does not exist, MFC throws an exception of type `CDaoException`. +The name of the foreign table in the relation. If the table doesn't exist, MFC throws an exception of type `CDaoException`. *lAttributes*
-A long value that contains information about the relationship type. You can use this value to enforce referential integrity, among other things. You can use the bitwise-OR operator ( **|**) to combine any of the following values (as long as the combination makes sense): +A long value that contains information about the relationship type. You can use this value to enforce referential integrity, among other things. You can use the bitwise-OR operator (**`|`**) to combine any of the following values (as long as the combination makes sense): - `dbRelationUnique` Relationship is one-to-one. @@ -307,7 +309,7 @@ The relationship cannot involve a query or an attached table from an external da Use the first version of the function when the relation involves one field in each of the two tables. Use the second version when the relation involves multiple fields. The maximum number of fields in a relation is 14. -This action creates an underlying DAO relation object, but this is an MFC implementation detail since MFC's encapsulation of relation objects is contained within class `CDaoDatabase`. MFC does not supply a class for relations. +This action creates an underlying DAO relation object, but this is an MFC implementation detail since MFC's encapsulation of relation objects is contained within class `CDaoDatabase`. MFC doesn't supply a class for relations. If you set the relation object's attributes to activate cascade operations, the database engine automatically updates or deletes records in one or more other tables when changes are made to related primary key tables. @@ -317,7 +319,7 @@ For related information, see the topic "CreateRelation Method" in DAO Help. ## CDaoDatabase::DeleteQueryDef -Call this member function to delete the specified querydef — saved query — from the `CDaoDatabase` object's QueryDefs collection. +Call this member function to delete the specified querydef—saved query—from the `CDaoDatabase` object's QueryDefs collection. ```cpp void DeleteQueryDef(LPCTSTR lpszName); @@ -393,7 +395,7 @@ void Execute( Pointer to a null-terminated string containing a valid SQL command to execute. *nOptions*
-An integer that specifies options relating to the integrity of the query. You can use the bitwise-OR operator ( **|**) to combine any of the following constants (provided the combination makes sense — for example, you would not combine `dbInconsistent` with `dbConsistent`): +An integer that specifies options relating to the integrity of the query. You can use the bitwise-OR operator (**`|`**) to combine any of the following constants provided the combination makes sense. For example, you would not combine `dbInconsistent` with `dbConsistent`: - `dbDenyWrite` Deny write permission to other users. @@ -412,16 +414,16 @@ An integer that specifies options relating to the integrity of the query. You ca ### Remarks -`Execute` works only for action queries or SQL pass-through queries that do not return results. It does not work for select queries, which return records. +`Execute` works only for action queries or SQL pass-through queries that don't return results. It doesn't work for select queries, which return records. For a definition and information about action queries, see the topics "Action Query" and "Execute Method" in DAO Help. > [!TIP] -> Given a syntactically correct SQL statement and proper permissions, the `Execute` member function will not fail even if not a single row can be modified or deleted. Therefore, always use the `dbFailOnError` option when using the `Execute` member function to run an update or delete query. This option causes MFC to throw an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md) and rolls back all successful changes if any of the records affected are locked and cannot be updated or deleted. Note that you can always call `GetRecordsAffected` to see how many records were affected. +> Given a syntactically correct SQL statement and proper permissions, the `Execute` member function won't fail even if not a single row can be modified or deleted. Therefore, always use the `dbFailOnError` option when using the `Execute` member function to run an update or delete query. This option causes MFC to throw an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md) and rolls back all successful changes if any of the records affected are locked and cannot be updated or deleted. Note that you can always call `GetRecordsAffected` to see how many records were affected. -Call the [GetRecordsAffected](#getrecordsaffected) member function of the database object to determine the number of records affected by the most recent `Execute` call. For example, `GetRecordsAffected` returns information about the number of records deleted, updated, or inserted when executing an action query. The count returned will not reflect changes in related tables when cascade updates or deletes are in effect. +Call the [GetRecordsAffected](#getrecordsaffected) member function of the database object to determine the number of records affected by the most recent `Execute` call. For example, `GetRecordsAffected` returns information about the number of records deleted, updated, or inserted when executing an action query. The count returned doesn't reflect changes in related tables when cascade updates or deletes are in effect. -`Execute` does not return a recordset. Using `Execute` on a query that selects records causes MFC to throw an exception of type `CDaoException`. (There is no `ExecuteSQL` member function analogous to `CDatabase::ExecuteSQL`.) +`Execute` doesn't return a recordset. Using `Execute` on a query that selects records causes MFC to throw an exception of type `CDaoException`. (There is no `ExecuteSQL` member function analogous to `CDatabase::ExecuteSQL`.) ## CDaoDatabase::GetConnect @@ -443,7 +445,7 @@ The string provides information about the source of an open database or a databa > Using the MFC DAO classes to connect to a data source via ODBC is less efficient than connecting via an attached table. > [!NOTE] -> The connection string is used to pass additional information to ODBC and certain ISAM drivers as needed. It is not used for .MDB databases. For Microsoft Jet database base tables, the connection string is an empty string ("") except when you use it for a SQL pass-through query as described under Return Value above. +> The connection string is used to pass additional information to ODBC and certain ISAM drivers as needed. It's not used for .MDB databases. For Microsoft Jet database base tables, the connection string is an empty string ("") except when you use it for a SQL pass-through query as described under Return Value above. See the [Open](#open) member function for a description of how the connection string is created. Once the connection string has been set in the `Open` call, you can later use it to check the setting to determine the type, path, user ID, Password, or ODBC data source of the database. @@ -552,7 +554,7 @@ A short integer containing the timeout value in seconds. ### Remarks -An operation might time out due to network access problems, excessive query processing time, and so on. While the setting is in effect, it affects all open, add new, update, and delete operations on any recordsets associated with this `CDaoDatabase` object. You can change the current timeout setting by calling [SetQueryTimeout](#setquerytimeout). Changing the query timeout value for a recordset after opening does not change the value for the recordset. For example, subsequent [Move](../../mfc/reference/cdaorecordset-class.md#move) operations do not use the new value. The default value is initially set when the database engine is initialized. +An operation might time out due to network access problems, excessive query processing time, and so on. While the setting is in effect, it affects all open, add new, update, and delete operations on any recordsets associated with this `CDaoDatabase` object. You can change the current timeout setting by calling [SetQueryTimeout](#setquerytimeout). Changing the query timeout value for a recordset after opening doesn't change the value for the recordset. For example, subsequent [Move](../../mfc/reference/cdaorecordset-class.md#move) operations don't use the new value. The default value is initially set when the database engine is initialized. The default value for query timeouts is taken from the Windows registry. If there is no registry setting, the default is 60 seconds. Not all databases support the ability to set a query timeout value. If you set a query timeout value of 0, no timeout occurs; and communication with the database may stop responding. This behavior may be useful during development. If the call fails, MFC throws an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). @@ -572,7 +574,7 @@ A long integer containing the number of records affected. ### Remarks -The value returned includes the number of records deleted, updated, or inserted by an action query run with `Execute`. The count returned will not reflect changes in related tables when cascade updates or deletes are in effect. +The value returned includes the number of records deleted, updated, or inserted by an action query run with `Execute`. The count returned doesn't reflect changes in related tables when cascade updates or deletes are in effect. For related information, see the topic "RecordsAffected Property" in DAO Help. @@ -746,7 +748,7 @@ Contains a pointer to the [CDaoWorkspace](../../mfc/reference/cdaoworkspace-clas ### Remarks -Use this pointer if you need to access the workspace directly — for example, to obtain pointers to other database objects in the workspace's Databases collection. +Use this pointer if you need to access the workspace directly. For example, to obtain pointers to other database objects in the workspace's Databases collection. ## CDaoDatabase::Open @@ -763,7 +765,7 @@ virtual void Open( ### Parameters *lpszName*
-A string expression that is the name of an existing Microsoft Jet (.MDB) database file. If the filename has an extension, it is required. If your network supports the uniform naming convention (UNC), you can also specify a network path, such as "\\\\\\\MYSERVER\\\MYSHARE\\\MYDIR\\\MYDB.MDB". (Double backslashes are required in string literals because "\\" is the C++ escape character.) +A string expression that is the name of an existing Microsoft Jet (.MDB) database file. If the filename has an extension, it's required. If your network supports the uniform naming convention (UNC), you can also specify a network path, such as "\\\\\\\MYSERVER\\\MYSHARE\\\MYDIR\\\MYDB.MDB". (Double backslashes are required in string literals because "\\" is the C++ escape character.) Some considerations apply when using *lpszName*. If it: @@ -771,7 +773,7 @@ Some considerations apply when using *lpszName*. If it: - Is an empty string ("") and *lpszConnect* is "ODBC;", a dialog box listing all registered ODBC data source names is displayed so the user can select a database. You should avoid direct connections to ODBC data sources; use an attached table instead. -- Otherwise does not refer to an existing database or valid ODBC data source name, MFC throws an exception of type `CDaoException`. +- Otherwise doesn't refer to an existing database or valid ODBC data source name, MFC throws an exception of type `CDaoException`. > [!NOTE] > For details about DAO error codes, see the DAOERR.H file. For related information, see the topic "Trappable Data Access Errors" in DAO Help. @@ -783,11 +785,11 @@ A Boolean value that is TRUE if the database is to be opened for exclusive (nons A Boolean value that is TRUE if the database is to be opened for read-only access and FALSE if the database is to be opened for read/write access. If you omit this argument, the database is opened for read/write access. All dependent recordsets inherit this attribute. *lpszConnect*
-A string expression used for opening the database. This string constitutes the ODBC connect arguments. You must supply the exclusive and read-only arguments to supply a source string. If the database is a Microsoft Jet database (.MDB), this string is empty (""). The syntax for the default value — **_T**("") — provides portability for Unicode as well as ANSI builds of your application. +A string expression used for opening the database. This string constitutes the ODBC connect arguments. You must supply the exclusive and read-only arguments to supply a source string. If the database is a Microsoft Jet database (.MDB), this string is empty (""). The syntax for the default value—**_T**("")—provides portability for Unicode as well as ANSI builds of your application. ### Remarks -`Open` associates the database with the underlying DAO object. You cannot use the database object to construct recordset, tabledef, or querydef objects until it is initialized. `Open` appends the database object to the associated workspace's Databases collection. +`Open` associates the database with the underlying DAO object. You cannot use the database object to construct recordset, tabledef, or querydef objects until it's initialized. `Open` appends the database object to the associated workspace's Databases collection. Use the parameters as follows: @@ -798,13 +800,13 @@ Use the parameters as follows: For related information, see the topic "OpenDatabase Method" in DAO Help. > [!NOTE] -> For better performance when accessing external databases, including ISAM databases and ODBC data sources, it is recommended that you attach external database tables to a Microsoft Jet engine database (.MDB) rather than connecting directly to the data source. +> For better performance when accessing external databases, including ISAM databases and ODBC data sources, it's recommended that you attach external database tables to a Microsoft Jet engine database (.MDB) rather than connecting directly to the data source. -It is possible for a connection attempt to time out if, for example, the DBMS host is unavailable. If the connection attempt fails, `Open` throws an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). +It's possible for a connection attempt to time out if, for example, the DBMS host is unavailable. If the connection attempt fails, `Open` throws an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). The remaining remarks apply only to ODBC databases: -If the database is an ODBC database and the parameters in your `Open` call do not contain enough information to make the connection, the ODBC driver opens a dialog box to obtain the necessary information from the user. When you call `Open`, your connection string, *lpszConnect*, is stored privately and is available by calling the [GetConnect](#getconnect) member function. +If the database is an ODBC database and the parameters in your `Open` call don't contain enough information to make the connection, the ODBC driver opens a dialog box to obtain the necessary information from the user. When you call `Open`, your connection string, *lpszConnect*, is stored privately and is available by calling the [GetConnect](#getconnect) member function. If you wish, you can open your own dialog box before you call `Open` to get information from the user, such as a password, then add that information to the connection string you pass to `Open`. Or you might want to save the connection string you pass (perhaps in the Windows registry) so you can reuse it the next time your application calls `Open` on a `CDaoDatabase` object. @@ -825,7 +827,7 @@ The number of seconds to allow before a query attempt times out. ### Remarks -An operation might time out because of network access problems, excessive query processing time, and so on. Call `SetQueryTimeout` before opening your recordset or before calling the recordset's [AddNew](../../mfc/reference/cdaorecordset-class.md#addnew), [Update](../../mfc/reference/cdaorecordset-class.md#update), or [Delete](../../mfc/reference/cdaorecordset-class.md#delete) member functions if you want to change the query timeout value. The setting affects all subsequent [Open](../../mfc/reference/cdaorecordset-class.md#open), `AddNew`, `Update`, and `Delete` calls to any recordsets associated with this `CDaoDatabase` object. Changing the query timeout value for a recordset after opening does not change the value for the recordset. For example, subsequent [Move](../../mfc/reference/cdaorecordset-class.md#move) operations do not use the new value. +An operation might time out because of network access problems, excessive query processing time, and so on. Call `SetQueryTimeout` before opening your recordset or before calling the recordset's [AddNew](../../mfc/reference/cdaorecordset-class.md#addnew), [Update](../../mfc/reference/cdaorecordset-class.md#update), or [Delete](../../mfc/reference/cdaorecordset-class.md#delete) member functions if you want to change the query timeout value. The setting affects all subsequent [Open](../../mfc/reference/cdaorecordset-class.md#open), `AddNew`, `Update`, and `Delete` calls to any recordsets associated with this `CDaoDatabase` object. Changing the query timeout value for a recordset after opening doesn't change the value for the recordset. For example, subsequent [Move](../../mfc/reference/cdaorecordset-class.md#move) operations don't use the new value. The default value for query timeouts is 60 seconds. Not all databases support the ability to set a query timeout value. If you set a query timeout value of 0, no timeout occurs; the communication with the database may stop responding. This behavior may be useful during development. diff --git a/docs/mfc/reference/cdaodatabaseinfo-structure.md b/docs/mfc/reference/cdaodatabaseinfo-structure.md index 0c65d02f3c..24d774536b 100644 --- a/docs/mfc/reference/cdaodatabaseinfo-structure.md +++ b/docs/mfc/reference/cdaodatabaseinfo-structure.md @@ -4,11 +4,13 @@ title: "CDaoDatabaseInfo Structure" ms.date: "09/17/2019" f1_keywords: ["CDaoDatabaseInfo"] helpviewer_keywords: ["CDaoDatabaseInfo structure [MFC]", "DAO (Data Access Objects), Databases collection"] -ms.assetid: 68e9e0da-8382-4fc6-8115-1b1519392ddb --- # CDaoDatabaseInfo Structure -The `CDaoDatabaseInfo` structure contains information about a database object defined for data access objects (DAO). DAO 3.6 is the final version, and it is considered obsolete. +The `CDaoDatabaseInfo` structure contains information about a database object defined for data access objects (DAO). + +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -94,7 +96,7 @@ Information retrieved by the [CDaoWorkspace::GetDatabaseInfo](../../mfc/referenc ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoerrorinfo-structure.md b/docs/mfc/reference/cdaoerrorinfo-structure.md index 686a487153..0848f939ef 100644 --- a/docs/mfc/reference/cdaoerrorinfo-structure.md +++ b/docs/mfc/reference/cdaoerrorinfo-structure.md @@ -4,11 +4,13 @@ title: "CDaoErrorInfo Structure" ms.date: "09/17/2019" f1_keywords: ["CDaoErrorInfo"] helpviewer_keywords: ["CDaoErrorInfo structure [MFC]", "DAO (Data Access Objects), Errors collection"] -ms.assetid: cd37ef71-b0b3-401d-bc2b-540c9147f532 --- # CDaoErrorInfo Structure -The `CDaoErrorInfo` structure contains information about an error object defined for data access objects (DAO). DAO 3.6 is the final version, and it is considered obsolete. +The `CDaoErrorInfo` structure contains information about an error object defined for data access objects (DAO). + +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -50,7 +52,7 @@ Information retrieved by the [CDaoException::GetErrorInfo](../../mfc/reference/c ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoexception-class.md b/docs/mfc/reference/cdaoexception-class.md index 10e48df062..7092121b13 100644 --- a/docs/mfc/reference/cdaoexception-class.md +++ b/docs/mfc/reference/cdaoexception-class.md @@ -4,15 +4,17 @@ title: "CDaoException Class" ms.date: "09/17/2019" f1_keywords: ["CDaoException", "AFXDAO/CDaoException", "AFXDAO/CDaoException::CDaoException", "AFXDAO/CDaoException::GetErrorCount", "AFXDAO/CDaoException::GetErrorInfo", "AFXDAO/CDaoException::m_nAfxDaoError", "AFXDAO/CDaoException::m_pErrorInfo", "AFXDAO/CDaoException::m_scode"] helpviewer_keywords: ["CDaoException [MFC], CDaoException", "CDaoException [MFC], GetErrorCount", "CDaoException [MFC], GetErrorInfo", "CDaoException [MFC], m_nAfxDaoError", "CDaoException [MFC], m_pErrorInfo", "CDaoException [MFC], m_scode"] -ms.assetid: b2b01fa9-7ce2-42a1-842e-40f13dc50da4 --- # CDaoException Class -Represents an exception condition arising from the MFC database classes based on data access objects (DAO). DAO 3.6 is the final version, and it is considered obsolete. +Represents an exception condition arising from the MFC database classes based on data access objects (DAO). + +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. ## Syntax -``` +```cpp class CDaoException : public CException ``` @@ -48,7 +50,7 @@ The class includes public data members you can use to determine the cause of the You can access exception objects within the scope of a [CATCH](../../mfc/reference/exception-processing.md#catch) expression. You can also throw `CDaoException` objects from your own code with the [AfxThrowDaoException](../../mfc/reference/exception-processing.md#afxthrowdaoexception) global function. -In MFC, all DAO errors are expressed as exceptions, of type `CDaoException`. When you catch an exception of this type, you can use `CDaoException` member functions to retrieve information from any DAO error objects stored in the database engine's Errors collection. As each error occurs, one or more error objects are placed in the Errors collection. (Normally the collection contains only one error object; if you are using an ODBC data source, you are more likely to get multiple error objects.) When another DAO operation generates an error, the Errors collection is cleared, and the new error object is placed in the Errors collection. DAO operations that do not generate an error have no effect on the Errors collection. +In MFC, all DAO errors are expressed as exceptions, of type `CDaoException`. When you catch an exception of this type, you can use `CDaoException` member functions to retrieve information from any DAO error objects stored in the database engine's Errors collection. As each error occurs, one or more error objects are placed in the Errors collection. (Normally the collection contains only one error object; if you're using an ODBC data source, you're more likely to get multiple error objects.) When another DAO operation generates an error, the Errors collection is cleared, and the new error object is placed in the Errors collection. DAO operations that do not generate an error have no effect on the Errors collection. For DAO error codes, see the file DAOERR.H. For related information, see the topic "Trappable Data Access Errors" in DAO Help. @@ -56,15 +58,15 @@ For more information about exception handling in general, or about `CDaoExceptio ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CException](../../mfc/reference/cexception-class.md) +[`CException`](../../mfc/reference/cexception-class.md) `CDaoException` ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoException::CDaoException @@ -78,13 +80,13 @@ CDaoException(); Ordinarily, the framework creates exception objects when its code throws an exception. You seldom need to construct an exception object explicitly. If you want to throw a `CDaoException` from your own code, call the global function [AfxThrowDaoException](../../mfc/reference/exception-processing.md#afxthrowdaoexception). -However, you might want to explicitly create an exception object if you are making direct calls to DAO via the DAO interface pointers that MFC classes encapsulate. In that case, you might need to retrieve error information from DAO. Suppose an error occurs in DAO when you call a DAO method via the DAODatabases interface to a workspace's Databases collection. +However, you might want to explicitly create an exception object if you're making direct calls to DAO via the DAO interface pointers that MFC classes encapsulate. In that case, you might need to retrieve error information from DAO. Suppose an error occurs in DAO when you call a DAO method via the DAODatabases interface to a workspace's Databases collection. ##### To retrieve the DAO error information 1. Construct a `CDaoException` object. -1. Call the exception object's [GetErrorCount](#geterrorcount) member function to determine how many error objects are in the database engine's Errors collection. (Normally only one, unless you are using an ODBC data source.) +1. Call the exception object's [GetErrorCount](#geterrorcount) member function to determine how many error objects are in the database engine's Errors collection. (Normally only one, unless you're using an ODBC data source.) 1. Call the exception object's [GetErrorInfo](#geterrorinfo) member function to retrieve one specific error object at a time, by index in the collection, via the exception object. Think of the exception object as a proxy for one DAO error object. @@ -110,10 +112,10 @@ The number of DAO error objects in the database engine's Errors collection. ### Remarks -This information is useful for looping through the Errors collection to retrieve each of the one or more DAO error objects in the collection. To retrieve an error object by index or by DAO error number, call the [GetErrorInfo](#geterrorinfo) member function. +This information is useful for looping through the Errors collection to retrieve each of one or more DAO error objects in the collection. To retrieve an error object by index or by DAO error number, call the [GetErrorInfo](#geterrorinfo) member function. > [!NOTE] -> Normally there is only one error object in the Errors collection. If you are working with an ODBC data source, however, there could be more than one. +> Normally there is only one error object in the Errors collection. If you're working with an ODBC data source, however, there could be more than one. ## CDaoException::GetErrorInfo @@ -156,13 +158,13 @@ This code is supplied in cases where a specific component of the MFC DAO classes Possible values are: -- NO_AFX_DAO_ERROR The most recent operation did not result in an MFC extended error. However, the operation could have produced other errors from DAO or OLE, so you should check [m_pErrorInfo](#m_perrorinfo) and possibly [m_scode](#m_scode). +- NO_AFX_DAO_ERROR The most recent operation didn't result in an MFC extended error. However, the operation could have produced other errors from DAO or OLE, so you should check [m_pErrorInfo](#m_perrorinfo) and possibly [m_scode](#m_scode). - AFX_DAO_ERROR_ENGINE_INITIALIZATION MFC could not initialize the Microsoft Jet database engine. OLE might have failed to initialize, or it might have been impossible to create an instance of the DAO database engine object. These problems usually suggest a bad installation of either DAO or OLE. -- AFX_DAO_ERROR_DFX_BIND An address used in a DAO record field exchange (DFX) function call does not exist or is invalid (the address was not used to bind data). You might have passed a bad address in a DFX call, or the address might have become invalid between DFX operations. +- AFX_DAO_ERROR_DFX_BIND An address used in a DAO record field exchange (DFX) function call doesn't exist or is invalid (the address wasn't used to bind data). You might have passed a bad address in a DFX call, or the address might have become invalid between DFX operations. -- AFX_DAO_ERROR_OBJECT_NOT_OPEN You attempted to open a recordset based on a querydef or a tabledef object that was not in an open state. +- AFX_DAO_ERROR_OBJECT_NOT_OPEN You attempted to open a recordset based on a querydef or a tabledef object that wasn't in an open state. ## CDaoException::m_pErrorInfo @@ -188,12 +190,11 @@ Contains a value of type `SCODE` that describes the error. ### Remarks -This is an OLE code. You will seldom need to use this value because, in almost all cases, more specific MFC or DAO error information is available in the other `CDaoException` data members. +This is an OLE code. You'll seldom need to use this value because, in almost all cases, more specific MFC or DAO error information is available in the other `CDaoException` data members. For information about SCODE, see the topic [Structure of OLE Error Codes](/windows/win32/com/structure-of-com-error-codes) in the Windows SDK. The SCODE data type maps to the HRESULT data type. ## See also -[CException Class](../../mfc/reference/cexception-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CException Class](../../mfc/reference/cexception-class.md) +[CException Class](../../mfc/reference/cexception-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md) \ No newline at end of file diff --git a/docs/mfc/reference/cdaofieldexchange-class.md b/docs/mfc/reference/cdaofieldexchange-class.md index 44eab5cdfe..47e1f63124 100644 --- a/docs/mfc/reference/cdaofieldexchange-class.md +++ b/docs/mfc/reference/cdaofieldexchange-class.md @@ -1,16 +1,16 @@ --- -description: "Learn more about: CDaoFieldExchange Class" title: "CDaoFieldExchange Class" -ms.date: "09/17/2019" +description: "Learn more about: CDaoFieldExchange Class" +ms.date: 09/17/2019 f1_keywords: ["CDaoFieldExchange", "AFXDAO/CDaoFieldExchange", "AFXDAO/CDaoFieldExchange::IsValidOperation", "AFXDAO/CDaoFieldExchange::SetFieldType", "AFXDAO/CDaoFieldExchange::m_nOperation", "AFXDAO/CDaoFieldExchange::m_prs"] helpviewer_keywords: ["CDaoFieldExchange [MFC], IsValidOperation", "CDaoFieldExchange [MFC], SetFieldType", "CDaoFieldExchange [MFC], m_nOperation", "CDaoFieldExchange [MFC], m_prs"] -ms.assetid: 350a663e-92ff-44ab-ad53-d94efa2e5823 --- # CDaoFieldExchange Class Supports the DAO record field exchange (DFX) routines used by the DAO database classes. -DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -44,7 +44,7 @@ Use this class if you are writing data exchange routines for custom data types; > The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have the "CDao" prefix. You can still access ODBC data sources with the DAO classes. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC. The DAO-based classes can access data, including through ODBC drivers, via their own database engine. They also support Data Definition Language (DDL) operations, such as adding tables via the classes instead of having to call DAO yourself. > [!NOTE] -> DAO record field exchange (DFX) is very similar to record field exchange (RFX) in the ODBC-based MFC database classes ( `CDatabase`, `CRecordset`). If you understand RFX, you will find it easy to use DFX. +> DAO record field exchange (DFX) is very similar to record field exchange (RFX) in the ODBC-based MFC database classes (`CDatabase`, `CRecordset`). If you understand RFX, you will find it easy to use DFX. A `CDaoFieldExchange` object provides the context information needed for DAO record field exchange to take place. `CDaoFieldExchange` objects support a number of operations, including binding parameters and field data members and setting various flags on the fields of the current record. DFX operations are performed on recordset-class data members of types defined by the **`enum`** **FieldType** in `CDaoFieldExchange`. Possible **FieldType** values are: @@ -60,7 +60,7 @@ The [IsValidOperation](#isvalidoperation) member function is provided for writin ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoFieldExchange::IsValidOperation @@ -89,7 +89,7 @@ Identifies the operation to be performed on the [CDaoRecordset](../../mfc/refere The `CDaoFieldExchange` object supplies the context for a number of different DFX operations on the recordset. > [!NOTE] -> The PSEUDONULL value described under the MarkForAddNew and SetFieldNull operations below is a value used to mark fields Null. The DAO record field exchange mechanism (DFX) uses this value to determine which fields have been explicitly marked Null. PSEUDONULL is not required for [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) and [COleCurrency](../../mfc/reference/colecurrency-class.md) fields. +> The `PSEUDONULL` value described under the `MarkForAddNew` and `SetFieldNull` operations below is a value used to mark fields Null. The DAO record field exchange mechanism (DFX) uses this value to determine which fields have been explicitly marked Null. `PSEUDONULL` is not required for [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) and [`COleCurrency`](../../mfc/reference/colecurrency-class.md) fields. Possible values of `m_nOperation` are: diff --git a/docs/mfc/reference/cdaofieldinfo-structure.md b/docs/mfc/reference/cdaofieldinfo-structure.md index f12c5f7317..1935ec2f72 100644 --- a/docs/mfc/reference/cdaofieldinfo-structure.md +++ b/docs/mfc/reference/cdaofieldinfo-structure.md @@ -4,13 +4,13 @@ title: "CDaoFieldInfo Structure" ms.date: "09/17/2019" f1_keywords: ["CDaoFieldInfo"] helpviewer_keywords: ["DAO (Data Access Objects), Fields collection", "CDaoFieldInfo structure [MFC]"] -ms.assetid: 91b13e3f-bdb8-440c-86fc-ba4181ea0182 --- # CDaoFieldInfo Structure The `CDaoFieldInfo` structure contains information about a field object defined for data access objects (DAO). -DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -88,7 +88,7 @@ A value that indicates the maximum size, in bytes, of a DAO field object that co |`dbGUID`|16|A Globally Unique Identifier/Universally Unique Identifier used with remote procedure calls.| *m_lAttributes*
-Specifies characteristics of a field object contained by a tabledef, recordset, querydef, or index object. The value returned can be a sum of these constants, created with the C++ bitwise-OR (**|**) operator: +Specifies characteristics of a field object contained by a tabledef, recordset, querydef, or index object. The value returned can be a sum of these constants, created with the C++ bitwise-OR (**`|`**) operator: - `dbFixedField` The field size is fixed (default for Numeric fields). @@ -100,7 +100,7 @@ Specifies characteristics of a field object contained by a tabledef, recordset, - `dbDescending` The field is sorted in descending (Z - A or 100 - 0) order (applies only to a field object in a Fields collection of an index object; in MFC, index objects are themselves contained in tabledef objects). If you omit this constant, the field is sorted in ascending (A - Z or 0 - 100) order (default). -When checking the setting of this property, you can use the C++ bitwise-AND operator (**&**) to test for a specific attribute. When setting multiple attributes, you can combine them by combining the appropriate constants with the bitwise-OR (**|**) operator. For details, see the topic "Attributes Property" in DAO Help. +When checking the setting of this property, you can use the C++ bitwise-AND operator (**`&`**) to test for a specific attribute. When setting multiple attributes, you can combine them by combining the appropriate constants with the bitwise-OR (**`|`**) operator. For details, see the topic "Attributes Property" in DAO Help. *m_nOrdinalPosition*
A value that specifies the numeric order in which you want a field represented by a DAO field object to be displayed relative to other fields. You can set this property with [CDaoTableDef::CreateField](../../mfc/reference/cdaotabledef-class.md#createfield). For details, see the topic "OrdinalPosition Property" in DAO Help. @@ -146,7 +146,7 @@ Information retrieved by the `GetFieldInfo` member function (of the class that c ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoindexfieldinfo-structure.md b/docs/mfc/reference/cdaoindexfieldinfo-structure.md index 160831669c..c75e91b586 100644 --- a/docs/mfc/reference/cdaoindexfieldinfo-structure.md +++ b/docs/mfc/reference/cdaoindexfieldinfo-structure.md @@ -4,13 +4,13 @@ title: "CDaoIndexFieldInfo Structure" ms.date: "09/17/2019" f1_keywords: ["CDaoIndexFieldInfo"] helpviewer_keywords: ["CDaoIndexFieldInfo structure [MFC]", "DAO (Data Access Objects), Index Fields collection"] -ms.assetid: 097ee8a6-83b1-4db7-8f05-d62a2deefe19 --- # CDaoIndexFieldInfo Structure The `CDaoIndexFieldInfo` structure contains information about an index field object defined for data access objects (DAO). -DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -40,7 +40,7 @@ Call the `GetIndexInfo` member function of the containing tabledef or recordset ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoindexinfo-structure.md b/docs/mfc/reference/cdaoindexinfo-structure.md index 390978f486..e7558e5bae 100644 --- a/docs/mfc/reference/cdaoindexinfo-structure.md +++ b/docs/mfc/reference/cdaoindexinfo-structure.md @@ -4,12 +4,14 @@ title: "CDaoIndexInfo Structure" ms.date: "06/25/2018" f1_keywords: ["CDaoIndexInfo"] helpviewer_keywords: ["DAO (Data Access Objects), Indexes collection", "CDaoIndexInfo structure [MFC]"] -ms.assetid: 251d8285-78ce-4716-a0b3-ccc3395fc437 --- # CDaoIndexInfo Structure The `CDaoIndexInfo` structure contains information about an index object defined for data access objects (DAO). +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ```cpp @@ -98,7 +100,7 @@ Information retrieved by the `GetIndexInfo` member function of a tabledef object ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoparameterinfo-structure.md b/docs/mfc/reference/cdaoparameterinfo-structure.md index 50b0f3407d..d2d54d4df7 100644 --- a/docs/mfc/reference/cdaoparameterinfo-structure.md +++ b/docs/mfc/reference/cdaoparameterinfo-structure.md @@ -4,11 +4,13 @@ title: "CDaoParameterInfo Structure" ms.date: "09/17/2019" f1_keywords: ["CDaoParameterInfo"] helpviewer_keywords: ["CDaoParameterInfo structure [MFC]", "DAO (Data Access Objects), Parameters collection"] -ms.assetid: 45fd53cd-cb84-4e12-b48d-7f2979f898ad --- # CDaoParameterInfo Structure -The `CDaoParameterInfo` structure contains information about a parameter object defined for data access objects (DAO). DAO 3.6 is the final version, and it is considered obsolete. +The `CDaoParameterInfo` structure contains information about a parameter object defined for data access objects (DAO). + +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. ## Syntax @@ -36,7 +38,7 @@ The value of the parameter, stored in a [COleVariant](../../mfc/reference/coleva The references to Primary and Secondary above indicate how the information is returned by the [GetParameterInfo](../../mfc/reference/cdaoquerydef-class.md#getparameterinfo) member function in class `CDaoQueryDef`. -MFC does not encapsulate DAO parameter objects in a class. DAO querydef objects underlying MFC `CDaoQueryDef` objects store parameters in their Parameters collections. To access the parameter objects in a [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) object, call the querydef object's `GetParameterInfo` member function for a particular parameter name or an index into the Parameters collection. You can use the [CDaoQueryDef::GetParameterCount](../../mfc/reference/cdaoquerydef-class.md#getparametercount) member function in conjunction with `GetParameterInfo` to loop through the Parameters collection. +The Microsoft Foundation Classes (MFC) don't encapsulate DAO parameter objects in a class. DAO querydef objects underlying MFC `CDaoQueryDef` objects store parameters in their Parameters collections. To access the parameter objects in a [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) object, call the querydef object's `GetParameterInfo` member function for a particular parameter name or an index into the Parameters collection. You can use the [CDaoQueryDef::GetParameterCount](../../mfc/reference/cdaoquerydef-class.md#getparametercount) member function in conjunction with `GetParameterInfo` to loop through the Parameters collection. Information retrieved by the [CDaoQueryDef::GetParameterInfo](../../mfc/reference/cdaoquerydef-class.md#getparameterinfo) member function is stored in a `CDaoParameterInfo` structure. Call `GetParameterInfo` for the querydef object in whose Parameters collection the parameter object is stored. @@ -47,7 +49,7 @@ Information retrieved by the [CDaoQueryDef::GetParameterInfo](../../mfc/referenc ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoquerydef-class.md b/docs/mfc/reference/cdaoquerydef-class.md index f13a031342..a8f573e692 100644 --- a/docs/mfc/reference/cdaoquerydef-class.md +++ b/docs/mfc/reference/cdaoquerydef-class.md @@ -4,15 +4,17 @@ title: "CDaoQueryDef Class" ms.date: "11/04/2016" f1_keywords: ["CDaoQueryDef", "AFXDAO/CDaoQueryDef", "AFXDAO/CDaoQueryDef::CDaoQueryDef", "AFXDAO/CDaoQueryDef::Append", "AFXDAO/CDaoQueryDef::CanUpdate", "AFXDAO/CDaoQueryDef::Close", "AFXDAO/CDaoQueryDef::Create", "AFXDAO/CDaoQueryDef::Execute", "AFXDAO/CDaoQueryDef::GetConnect", "AFXDAO/CDaoQueryDef::GetDateCreated", "AFXDAO/CDaoQueryDef::GetDateLastUpdated", "AFXDAO/CDaoQueryDef::GetFieldCount", "AFXDAO/CDaoQueryDef::GetFieldInfo", "AFXDAO/CDaoQueryDef::GetName", "AFXDAO/CDaoQueryDef::GetODBCTimeout", "AFXDAO/CDaoQueryDef::GetParameterCount", "AFXDAO/CDaoQueryDef::GetParameterInfo", "AFXDAO/CDaoQueryDef::GetParamValue", "AFXDAO/CDaoQueryDef::GetRecordsAffected", "AFXDAO/CDaoQueryDef::GetReturnsRecords", "AFXDAO/CDaoQueryDef::GetSQL", "AFXDAO/CDaoQueryDef::GetType", "AFXDAO/CDaoQueryDef::IsOpen", "AFXDAO/CDaoQueryDef::Open", "AFXDAO/CDaoQueryDef::SetConnect", "AFXDAO/CDaoQueryDef::SetName", "AFXDAO/CDaoQueryDef::SetODBCTimeout", "AFXDAO/CDaoQueryDef::SetParamValue", "AFXDAO/CDaoQueryDef::SetReturnsRecords", "AFXDAO/CDaoQueryDef::SetSQL", "AFXDAO/CDaoQueryDef::m_pDAOQueryDef", "AFXDAO/CDaoQueryDef::m_pDatabase"] helpviewer_keywords: ["CDaoQueryDef [MFC], CDaoQueryDef", "CDaoQueryDef [MFC], Append", "CDaoQueryDef [MFC], CanUpdate", "CDaoQueryDef [MFC], Close", "CDaoQueryDef [MFC], Create", "CDaoQueryDef [MFC], Execute", "CDaoQueryDef [MFC], GetConnect", "CDaoQueryDef [MFC], GetDateCreated", "CDaoQueryDef [MFC], GetDateLastUpdated", "CDaoQueryDef [MFC], GetFieldCount", "CDaoQueryDef [MFC], GetFieldInfo", "CDaoQueryDef [MFC], GetName", "CDaoQueryDef [MFC], GetODBCTimeout", "CDaoQueryDef [MFC], GetParameterCount", "CDaoQueryDef [MFC], GetParameterInfo", "CDaoQueryDef [MFC], GetParamValue", "CDaoQueryDef [MFC], GetRecordsAffected", "CDaoQueryDef [MFC], GetReturnsRecords", "CDaoQueryDef [MFC], GetSQL", "CDaoQueryDef [MFC], GetType", "CDaoQueryDef [MFC], IsOpen", "CDaoQueryDef [MFC], Open", "CDaoQueryDef [MFC], SetConnect", "CDaoQueryDef [MFC], SetName", "CDaoQueryDef [MFC], SetODBCTimeout", "CDaoQueryDef [MFC], SetParamValue", "CDaoQueryDef [MFC], SetReturnsRecords", "CDaoQueryDef [MFC], SetSQL", "CDaoQueryDef [MFC], m_pDAOQueryDef", "CDaoQueryDef [MFC], m_pDatabase"] -ms.assetid: 9676a4a3-c712-44d4-8c5d-d1cc78288d3a --- -# CDaoQueryDef Class +# `CDaoQueryDef` Class Represents a query definition, or "querydef," usually one saved in a database. +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. + ## Syntax -``` +```cpp class CDaoQueryDef : public CObject ``` @@ -39,7 +41,7 @@ class CDaoQueryDef : public CObject |[CDaoQueryDef::GetFieldCount](#getfieldcount)|Returns the number of fields defined by the querydef.| |[CDaoQueryDef::GetFieldInfo](#getfieldinfo)|Returns information about a specified field defined in the query.| |[CDaoQueryDef::GetName](#getname)|Returns the name of the querydef.| -|[CDaoQueryDef::GetODBCTimeout](#getodbctimeout)|Returns the timeout value used by ODBC (for an ODBC query) when the querydef is executed. This determines how long to allow for the query's action to complete.| +|[CDaoQueryDef::GetODBCTimeout](#getodbctimeout)|Returns the timeout value used by ODBC (for an ODBC query) when the querydef is executed which determines how long to allow for the query's action to complete.| |[CDaoQueryDef::GetParameterCount](#getparametercount)|Returns the number of parameters defined for the query.| |[CDaoQueryDef::GetParameterInfo](#getparameterinfo)|Returns information about a specified parameter to the query.| |[CDaoQueryDef::GetParamValue](#getparamvalue)|Returns the value of a specified parameter to the query.| @@ -65,10 +67,10 @@ class CDaoQueryDef : public CObject ## Remarks -A querydef is a data access object that contains the SQL statement that describes a query, and its properties, such as "Date Created" and "ODBC Timeout." You can also create temporary querydef objects without saving them, but it is convenient — and much more efficient — to save commonly reused queries in a database. A [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object maintains a collection, called the QueryDefs collection, that contains its saved querydefs. +A querydef is a data access object that contains the SQL statement that describes a query, and its properties, such as "Date Created" and "ODBC Timeout." You can also create temporary querydef objects without saving them, but it's convenient—and much more efficient—to save commonly reused queries in a database. A [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object maintains a collection, called the QueryDefs collection, that contains its saved querydefs. > [!NOTE] -> The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have the "CDao" prefix. You can still access ODBC data sources with the DAO classes. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC; the DAO-based classes can access data, including through ODBC drivers, via their own database engine. The DAO-based classes also support Data Definition Language (DDL) operations, such as adding tables via the classes, without having to call DAO directly. +> The DAO database classes are distinct from the Microsoft Foundation Class (MFC) database classes based on Open Database Connectivity (ODBC). All DAO database class names have the "CDao" prefix. You can still access ODBC data sources with the DAO classes. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC; the DAO-based classes can access data, including through ODBC drivers, via their own database engine. The DAO-based classes also support Data Definition Language (DDL) operations, such as adding tables via the classes, without having to call DAO directly. ## Usage @@ -80,9 +82,9 @@ Use querydef objects either to work with an existing saved query or to create a - To use an existing saved query, call the querydef object's [Open](#open) member function, supplying the name of the saved query. - - To create a new saved query, call the querydef object's [Create](#create) member function, supplying the name of the query. Then call [Append](#append) to save the query by appending it to the database's QueryDefs collection. `Create` puts the querydef into an open state, so after calling `Create` you do not call `Open`. + - To create a new saved query, call the querydef object's [Create](#create) member function, supplying the name of the query. Then call [Append](#append) to save the query by appending it to the database's QueryDefs collection. `Create` puts the querydef into an open state, so after calling `Create` you don't call `Open`. - - To create a temporary querydef, call `Create`. Pass an empty string for the query name. Do not call `Append`. + - To create a temporary querydef, call `Create`. Pass an empty string for the query name. Don't call `Append`. When you finish using a querydef object, call its [Close](#close) member function; then destroy the querydef object. @@ -97,13 +99,13 @@ You can use a querydef object for any of the following purposes: - To call the object's `Execute` member function to directly execute an action query or a SQL pass-through query -You can use a querydef object for any type of query, including select, action, crosstab, delete, update, append, make-table, data definition, SQL pass-through, union, and bulk queries. The query's type is determined by the content of the SQL statement that you supply. For information about query types, see the `Execute` and [GetType](#gettype) member functions. Recordsets are commonly used for row-returning queries, usually those using the **SELECT ... FROM** keywords. `Execute` is most commonly used for bulk operations. For more information, see [Execute](#execute) and [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md). +You can use a querydef object for any type of query, including select, action, crosstab, delete, update, append, make-table, data definition, SQL pass-through, union, and bulk queries. The content of the SQL statement that you supply determines the query's type. For information about query types, see the `Execute` and [`GetType`](#gettype) member functions. Recordsets are commonly used for row-returning queries, usually queries using the **SELECT ... FROM** keywords. `Execute` is most commonly used for bulk operations. For more information, see [`Execute`](#execute) and [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md). ## Querydefs and Recordsets -To use a querydef object to create a `CDaoRecordset` object, you typically create or open a querydef as described above. Then construct a recordset object, passing a pointer to your querydef object when you call [CDaoRecordset::Open](../../mfc/reference/cdaorecordset-class.md#open). The querydef you pass must be in an open state. For more information, see class [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md). +To use a querydef object to create a `CDaoRecordset` object, you typically create or open a querydef as described previously. Then construct a recordset object, passing a pointer to your querydef object when you call [`CDaoRecordset::Open`](../../mfc/reference/cdaorecordset-class.md#open). The querydef you pass must be in an open state. For more information, see class [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md). -You cannot use a querydef to create a recordset (the most common use for a querydef) unless it is in an open state. Put the querydef into an open state by calling either `Open` or `Create`. +You can't use a querydef to create a recordset (the most common use for a querydef) unless it's in an open state. Put the querydef into an open state by calling either `Open` or `Create`. ## External Databases @@ -122,7 +124,7 @@ For related information, see the topics "QueryDef Object", "QueryDefs Collection ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoQueryDef::Append @@ -140,7 +142,7 @@ If you attempt to append a temporary querydef object, MFC throws an exception of ## CDaoQueryDef::CanUpdate -Call this member function to determine whether you can modify the querydef — such as changing its name or SQL string. +Call this member function to determine whether you can modify the querydef—such as changing its name or SQL string. ``` BOOL CanUpdate(); @@ -148,17 +150,17 @@ BOOL CanUpdate(); ### Return Value -Nonzero if you are permitted to modify the querydef; otherwise 0. +Nonzero if you can modify the querydef; otherwise 0. ### Remarks You can modify the querydef if: -- It is not based on a database that is open read-only. +- It's not based on a database that is open read-only. - You have update permissions for the database. - This depends on whether you have implemented security features. MFC does not provide support for security; you must implement it yourself by calling DAO directly or by using Microsoft Access. See the topic "Permissions Property" in DAO Help. + This depends on whether you implemented security features. MFC doesn't provide support for security; you must implement it yourself by calling DAO directly or by using Microsoft Access. See the topic "Permissions Property" in DAO Help. ## CDaoQueryDef::CDaoQueryDef @@ -181,7 +183,7 @@ The object can represent an existing querydef stored in the database's QueryDefs - If the object represents a new querydef to be saved, call the object's [Create](#create) member function. This adds the object to the database's QueryDefs collection. Then call `CDaoQueryDef` member functions to set the object's attributes. Finally, call [Append](#append). -- If the object represents a temporary querydef (not to be saved in the database), call `Create`, passing an empty string for the query's name. After calling `Create`, initialize the querydef by directly setting its attributes. Do not call `Append`. +- If the object represents a temporary querydef (not to be saved in the database), call `Create`, passing an empty string for the query's name. After calling `Create`, initialize the querydef by directly setting its attributes. Don't call `Append`. To set the attributes of the querydef, you can use the [SetName](#setname), [SetSQL](#setsql), [SetConnect](#setconnect), [SetODBCTimeout](#setodbctimeout), and [SetReturnsRecords](#setreturnsrecords) member functions. @@ -197,7 +199,7 @@ virtual void Close(); ### Remarks -Closing the querydef releases the underlying DAO object but does not destroy the saved DAO querydef object or the C++ `CDaoQueryDef` object. This is not the same as [CDaoDatabase::DeleteQueryDef](../../mfc/reference/cdaodatabase-class.md#deletequerydef), which deletes the querydef from the database's QueryDefs collection in DAO (if not a temporary querydef). +Closing the querydef releases the underlying DAO object but doesn't destroy the saved DAO querydef object or the C++ `CDaoQueryDef` object. This isn't the same as [CDaoDatabase::DeleteQueryDef](../../mfc/reference/cdaodatabase-class.md#deletequerydef), which deletes the querydef from the database's QueryDefs collection in DAO (if not a temporary querydef). ## CDaoQueryDef::Create @@ -212,16 +214,16 @@ virtual void Create( ### Parameters *lpszName*
-The unique name of the query saved in the database. For details about the string, see the topic "CreateQueryDef Method" in DAO Help. If you accept the default value, an empty string, a temporary querydef is created. Such a query is not saved in the QueryDefs collection. +The unique name of the query saved in the database. For details about the string, see the topic "CreateQueryDef Method" in DAO Help. If you accept the default value, an empty string, a temporary querydef is created. Such a query isn't saved in the QueryDefs collection. *lpszSQL*
The SQL string that defines the query. If you accept the default value of NULL, you must later call [SetSQL](#setsql) to set the string. Until then, the query is undefined. You can, however, use the undefined query to open a recordset; see Remarks for details. The SQL statement must be defined before you can append the querydef to the QueryDefs collection. ### Remarks -If you pass a name in *lpszName*, you can then call [Append](#append) to save the querydef in the database's QueryDefs collection. Otherwise, the object is a temporary querydef and is not saved. In either case, the querydef is in an open state, and you can either use it to create a [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) object or call the querydef's [Execute](#execute) member function. +If you pass a name in *lpszName*, you can then call [Append](#append) to save the querydef in the database's QueryDefs collection. Otherwise, the object is a temporary querydef and isn't saved. In either case, the querydef is in an open state, and you can either use it to create a [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) object or call the querydef's [Execute](#execute) member function. -If you do not supply a SQL statement in *lpszSQL*, you cannot run the query with `Execute` but you can use it to create a recordset. In that case, MFC uses the recordset's default SQL statement. +If you don't supply a SQL statement in *lpszSQL*, you can't run the query with `Execute` but you can use it to create a recordset. In that case, MFC uses the recordset's default SQL statement. ## CDaoQueryDef::Execute @@ -234,7 +236,7 @@ virtual void Execute(int nOptions = dbFailOnError); ### Parameters *nOptions*
-An integer that determines the characteristics of the query. For related information, see the topic "Execute Method" in DAO Help. You can use the bitwise-OR operator ( **|**) to combine the following constants for this argument: +An integer that determines the characteristics of the query. For related information, see the topic "Execute Method" in DAO Help. You can use the bitwise-OR operator (**`|`**) to combine the following constants for this argument: - `dbDenyWrite` Deny write permission to other users. @@ -246,7 +248,7 @@ An integer that determines the characteristics of the query. For related informa - `dbFailOnError` Default value. Roll back updates if an error occurs and report the error to the user. -- `dbSeeChanges` Generate a run-time error if another user is changing data you are editing. +- `dbSeeChanges` Generate a run-time error if another user is changing data you're editing. > [!NOTE] > For an explanation of the terms "inconsistent" and "consistent," see the topic "Execute Method" in DAO Help. @@ -259,16 +261,16 @@ Querydef objects used for execution in this manner can only represent one of the - SQL pass-through queries -`Execute` does not work for queries that return records, such as select queries. `Execute` is commonly used for bulk operation queries, such as **UPDATE**, **INSERT**, or **SELECT INTO**, or for data definition language (DDL) operations. +`Execute` doesn't work for queries that return records, such as select queries. `Execute` is commonly used for bulk operation queries, such as **UPDATE**, **INSERT**, or **SELECT INTO**, or for data definition language (DDL) operations. > [!TIP] > The preferred way to work with ODBC data sources is to attach tables to a Microsoft Jet (.MDB) database. For more information, see the topic "Accessing External Databases with DAO" in DAO Help. -Call the [GetRecordsAffected](#getrecordsaffected) member function of the querydef object to determine the number of records affected by the most recent `Execute` call. For example, `GetRecordsAffected` returns information about the number of records deleted, updated, or inserted when executing an action query. The count returned will not reflect changes in related tables when cascade updates or deletes are in effect. +Call the [GetRecordsAffected](#getrecordsaffected) member function of the querydef object to determine the number of records affected by the most recent `Execute` call. For example, `GetRecordsAffected` returns information about the number of records deleted, updated, or inserted when executing an action query. The count returned doesn't reflect changes in related tables when cascade updates or deletes are in effect. If you include both `dbInconsistent` and `dbConsistent` or if you include neither, the result is the default, `dbInconsistent`. -`Execute` does not return a recordset. Using `Execute` on a query that selects records causes MFC to throw an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). +`Execute` doesn't return a recordset. Using `Execute` on a query that selects records causes MFC to throw an exception of type [CDaoException](../../mfc/reference/cdaoexception-class.md). ## CDaoQueryDef::GetConnect @@ -280,11 +282,11 @@ CString GetConnect(); ### Return Value -A [CString](../../atl-mfc-shared/reference/cstringt-class.md) containing the connection string for the querydef. +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) containing the connection string for the querydef. ### Remarks -This function is used only with ODBC data sources and certain ISAM drivers. It is not used with Microsoft Jet (.MDB) databases; in this case, `GetConnect` returns an empty string. For more information, see [SetConnect](#setconnect). +This function is used only with ODBC data sources and certain ISAM drivers. It's not used with Microsoft Jet (`.MDB`) databases; in this case, `GetConnect` returns an empty string. For more information, see [`SetConnect`](#setconnect). > [!TIP] > The preferred way to work with ODBC tables is to attach them to an .MDB database. For more information, see the topic "Accessing External Databases with DAO" in DAO Help. @@ -309,7 +311,7 @@ For related information, see the topic "DateCreated, LastUpdated Properties" in ## CDaoQueryDef::GetDateLastUpdated -Call this member function to get the date the querydef object was last updated — when any of its properties were changed, such as its name, its SQL string, or its connection string. +Call this member function to get the date the querydef object was last updated—when any of its properties were changed, such as its name, its SQL string, or its connection string. ``` COleDateTime GetDateLastUpdated(); @@ -317,7 +319,7 @@ COleDateTime GetDateLastUpdated(); ### Return Value -A [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) object containing the date and time the querydef was last updated. +A [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) object containing the date and time the querydef was last updated. ### Remarks @@ -337,7 +339,7 @@ The number of fields defined in the query. ### Remarks -`GetFieldCount` is useful for looping through all fields in the querydef. For that purpose, use `GetFieldCount` in conjunction with [GetFieldInfo](#getfieldinfo). +`GetFieldCount` is useful for looping through all fields in the querydef. For that purpose, use `GetFieldCount` with [`GetFieldInfo`](#getfieldinfo). ## CDaoQueryDef::GetFieldInfo @@ -373,7 +375,7 @@ Options that specify which information about the field to retrieve. The availabl - AFX_DAO_ALL_INFO Primary and secondary information plus: Default Value, Validation Text, Validation Rule *lpszName*
-A string containing the name of the desired field, for lookup by name. You can use a [CString](../../atl-mfc-shared/reference/cstringt-class.md). +A string containing the name of the desired field, for lookup by name. You can use a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md). ### Remarks @@ -428,7 +430,7 @@ The number of parameters defined in the query. ### Remarks -`GetParameterCount` is useful for looping through all parameters in the querydef. For that purpose, use `GetParameterCount` in conjunction with [GetParameterInfo](#getparameterinfo). +`GetParameterCount` is useful for looping through all parameters in the querydef. For that purpose, use `GetParameterCount` with [`GetParameterInfo`](#getparameterinfo). For related information, see the topics "Parameter Object", "Parameters Collection", and "PARAMETERS Declaration (SQL)" in DAO Help. @@ -450,23 +452,23 @@ void GetParameterInfo( ### Parameters -*nIndex*
+*`nIndex`*
The zero-based index of the desired parameter in the querydef's Parameters collection, for lookup by index. -*paraminfo*
+*`paraminfo`*
A reference to a [CDaoParameterInfo](../../mfc/reference/cdaoparameterinfo-structure.md) object that returns the information requested. -*dwInfoOptions*
+*`dwInfoOptions`*
Options that specify which information about the parameter to retrieve. The available option is listed here along with what it causes the function to return: -- AFX_DAO_PRIMARY_INFO (Default) Name, Type +- `AFX_DAO_PRIMARY_INFO` (Default) Name, Type -*lpszName*
-A string containing the name of the desired parameter, for lookup by name. You can use a [CString](../../atl-mfc-shared/reference/cstringt-class.md). +*`lpszName`*
+A string containing the name of the desired parameter, for lookup by name. You can use a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md). ### Remarks -For a description of the information returned in *paraminfo*, see the [CDaoParameterInfo](../../mfc/reference/cdaoparameterinfo-structure.md) structure. This structure has members that correspond to the descriptive information under *dwInfoOptions* above. +For a description of the information returned in *`paraminfo`*, see the [`CDaoParameterInfo`](../../mfc/reference/cdaoparameterinfo-structure.md) structure. This structure has members that correspond to the descriptive information under *`dwInfoOptions`* above. For related information, see the topic "PARAMETERS Declaration (SQL)" in DAO Help. @@ -499,7 +501,7 @@ For related information, see the topic "PARAMETERS Declaration (SQL)" in DAO Hel ## CDaoQueryDef::GetRecordsAffected -Call this member function to determine how many records were affected by the last call of [Execute](#execute). +Call this member function to determine how many records are affected by the last call of [Execute](#execute). ``` long GetRecordsAffected(); @@ -511,9 +513,9 @@ The number of records affected. ### Remarks -The count returned will not reflect changes in related tables when cascade updates or deletes are in effect. +The count returned doesn't reflect changes in related tables when cascade updates or deletes are in effect. -For related information see the topic "RecordsAffected Property" in DAO Help. +For related information, see the topic "RecordsAffected Property" in DAO Help. ## CDaoQueryDef::GetReturnsRecords @@ -547,7 +549,7 @@ The SQL statement that defines the query on which the querydef is based. ### Remarks -You will then probably parse the string for keywords, table names, and so on. +You can parse the string for keywords, table names, and so on. For related information, see the topics "SQL Property", "Comparison of Microsoft Jet Database Engine SQL and ANSI SQL", and "Querying a Database with SQL in Code" in DAO Help. @@ -587,7 +589,7 @@ The query type is set by what you specify in the querydef's SQL string when you - `dbQSetOperation` Union -- `dbQSPTBulk` Used with `dbQSQLPassThrough` to specify a query that does not return records. +- `dbQSPTBulk` Used with `dbQSQLPassThrough` to specify a query that doesn't return records. > [!NOTE] > To create a SQL pass-through query, don't set the `dbSQLPassThrough` constant. This is set automatically by the Microsoft Jet database engine when you create a querydef object and set the connection string. @@ -608,7 +610,7 @@ Nonzero if the `CDaoQueryDef` object is currently open; otherwise 0. ### Remarks -A querydef must be in an open state before you use it to call [Execute](#execute) or to create a [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) object. To put a querydef into an open state call either [Create](#create) (for a new querydef) or [Open](#open) (for an existing querydef). +A querydef must be in an open state before you use it to call [`Execute`](#execute) or to create a [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md) object. To put a querydef into an open state, call either [`Create`](#create) (for a new querydef) or [`Open`](#open) (for an existing querydef). ## CDaoQueryDef::m_pDatabase @@ -616,7 +618,7 @@ Contains a pointer to the [CDaoDatabase](../../mfc/reference/cdaodatabase-class. ### Remarks -Use this pointer if you need to access the database directly — for example, to obtain pointers to other querydef or recordset objects in the database's collections. +Use this pointer if you need to access the database directly. For example, to obtain pointers to other querydef or recordset objects in the database's collections. ## CDaoQueryDef::m_pDAOQueryDef @@ -624,7 +626,7 @@ Contains a pointer to the OLE interface for the underlying DAO querydef object. ### Remarks -This pointer is provided for completeness and consistency with the other classes. However, because MFC rather fully encapsulates DAO querydefs, you are unlikely to need it. If you do use it, do so cautiously — in particular, do not change the value of the pointer unless you know what you are doing. +This pointer is provided for completeness and consistency with the other classes. However, because MFC rather fully encapsulates DAO querydefs, you're unlikely to need it. If you do use it, do so cautiously. In particular, don't change the value of the pointer unless you know what you're doing. ## CDaoQueryDef::Open @@ -637,11 +639,11 @@ virtual void Open(LPCTSTR lpszName = NULL); ### Parameters *lpszName*
-A string that contains the name of the saved querydef to open. You can use a [CString](../../atl-mfc-shared/reference/cstringt-class.md). +A string that contains the name of the saved querydef to open. You can use a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md). ### Remarks -Once the querydef is open, you can call its [Execute](#execute) member function or use the querydef to create a [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) object. +Once the querydef is open, you can call its [`Execute`](#execute) member function or use the querydef to create a [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md) object. ## CDaoQueryDef::SetConnect @@ -658,7 +660,7 @@ A string that contains a connection string for the associated [CDaoDatabase](../ ### Remarks -The connection string is used to pass additional information to ODBC and certain ISAM drivers as needed. It is not used for Microsoft Jet (.MDB) databases. +The connection string is used to pass additional information to ODBC and certain ISAM drivers as needed. It's not used for Microsoft Jet (`.MDB`) databases. > [!TIP] > The preferred way to work with ODBC tables is to attach them to an .MDB database. @@ -669,7 +671,7 @@ For more information about the connection string's structure and examples of con ## CDaoQueryDef::SetName -Call this member function if you want to change the name of a querydef that is not temporary. +Call this member function if you want to change the name of a querydef that isn't temporary. ```cpp void SetName(LPCTSTR lpszName); @@ -699,7 +701,7 @@ The number of seconds before a query times out. ### Remarks -This member function lets you override the default number of seconds before subsequent operations on the connected data source "time out." An operation might time out due to network access problems, excessive query processing time, and so on. Call `SetODBCTimeout` prior to executing a query with this querydef if you want to change the query timeout value. (As ODBC reuses connections, the timeout value is the same for all clients on the same connection.) +This member function lets you override the default number of seconds before subsequent operations on the connected data source "time out." An operation might time out due to network access problems, excessive query processing time, and so on. Call `SetODBCTimeout` before executing a query with this querydef if you want to change the query timeout value. (As ODBC reuses connections, the timeout value is the same for all clients on the same connection.) The default value for query timeouts is 60 seconds. @@ -730,7 +732,7 @@ The ordinal position of the parameter in the querydef's Parameters collection. Y ### Remarks -The parameter must already have been established as part of the querydef's SQL string. You can access the parameter either by name or by its ordinal position in the collection. +The parameter must already be established as part of the querydef's SQL string. You can access the parameter either by name or by its ordinal position in the collection. Specify the value to set as a `COleVariant` object. For information about setting the desired value and type in your `COleVariant` object, see class [COleVariant](../../mfc/reference/colevariant-class.md). @@ -770,9 +772,9 @@ A typical use of `SetSQL` is setting up a querydef object for use in a SQL pass- ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
+[`CObject` Class](../../mfc/reference/cobject-class.md)
[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CDaoRecordset Class](../../mfc/reference/cdaorecordset-class.md)
-[CDaoDatabase Class](../../mfc/reference/cdaodatabase-class.md)
-[CDaoTableDef Class](../../mfc/reference/cdaotabledef-class.md)
-[CDaoException Class](../../mfc/reference/cdaoexception-class.md) +[`CDaoRecordset` Class](../../mfc/reference/cdaorecordset-class.md)
+[`CDaoDatabase` Class](../../mfc/reference/cdaodatabase-class.md)
+[`CDaoTableDef` Class](../../mfc/reference/cdaotabledef-class.md)
+[`CDaoException` Class](../../mfc/reference/cdaoexception-class.md) diff --git a/docs/mfc/reference/cdaoquerydefinfo-structure.md b/docs/mfc/reference/cdaoquerydefinfo-structure.md index c42b9f3333..78fed0c2d2 100644 --- a/docs/mfc/reference/cdaoquerydefinfo-structure.md +++ b/docs/mfc/reference/cdaoquerydefinfo-structure.md @@ -4,12 +4,14 @@ title: "CDaoQueryDefInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CDaoQueryDefInfo"] helpviewer_keywords: ["DAO (Data Access Objects), QueryDefs collection", "CDaoQueryDefInfo structure [MFC]"] -ms.assetid: e20837dc-e78d-4171-a195-1b4075fb5d2a --- # CDaoQueryDefInfo Structure The `CDaoQueryDefInfo` structure contains information about a querydef object defined for data access objects (DAO). +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. + ## Syntax ``` @@ -33,43 +35,43 @@ struct CDaoQueryDefInfo Uniquely names the querydef object. For more information, see the topic "Name Property" in DAO Help. Call [CDaoQueryDef::GetName](../../mfc/reference/cdaoquerydef-class.md#getname) to retrieve this property directly. *m_nType*
-A value that indicates the operational type of a querydef object. The value can be one of the following: +A value that indicates the operational type of a querydef object. The value can be one of: -- `dbQSelect` Select — the query selects records. +- `dbQSelect` Select: the query selects records. -- `dbQAction` Action — the query moves or changes data but does not return records. +- `dbQAction` Action: the query moves or changes data but doesn't return records. -- `dbQCrosstab` Crosstab — the query returns data in a spreadsheet-like format. +- `dbQCrosstab` Crosstab: the query returns data in a spreadsheet-like format. -- `dbQDelete` Delete — the query deletes a set of specified rows. +- `dbQDelete` Delete: the query deletes a set of specified rows. -- `dbQUpdate` Update — the query changes a set of records. +- `dbQUpdate` Update: the query changes a set of records. -- `dbQAppend` Append — the query adds new records to the end of a table or query. +- `dbQAppend` Append: the query adds new records to the end of a table or query. -- `dbQMakeTable` Make-table — the query creates a new table from a recordset. +- `dbQMakeTable` Make-table: the query creates a new table from a recordset. -- `dbQDDL` Data-definition — the query affects the structure of tables or their parts. +- `dbQDDL` Data-definition: the query affects the structure of tables or their parts. -- `dbQSQLPassThrough` Pass-through — the SQL statement is passed directly to the database backend, without intermediate processing. +- `dbQSQLPassThrough` Pass-through: the SQL statement is passed directly to the database backend, without intermediate processing. -- `dbQSetOperation` Union — the query creates a snapshot-type recordset object containing data from all specified records in two or more tables with any duplicate records removed. To include the duplicates, add the keyword **ALL** in the querydef's SQL statement. +- `dbQSetOperation` Union: the query creates a snapshot-type recordset object containing data from all specified records in two or more tables with any duplicate records removed. To include the duplicates, add the keyword **ALL** in the querydef's SQL statement. -- `dbQSPTBulk` Used with `dbQSQLPassThrough` to specify a query that does not return records. +- `dbQSPTBulk` Used with `dbQSQLPassThrough` to specify a query that doesn't return records. > [!NOTE] -> To create a SQL pass-through query, you do not set the `dbQSQLPassThrough` constant. This is set automatically by the Microsoft Jet database engine when you create a querydef object and set the Connect property. +> To create a SQL pass-through query, you do not set the `dbQSQLPassThrough` constant. This is set automatically by the Microsoft Jet database engine when you create a querydef object and set the `Connect` property. For more information, see the topic "Type Property" in DAO Help. *m_dateCreated*
-The date and time the querydef was created. To directly retrieve the date the querydef was created, call the [GetDateCreated](../../mfc/reference/cdaotabledef-class.md#getdatecreated) member function of the `CDaoTableDef` object associated with the table. See Comments below for more information. Also see the topic "DateCreated, LastUpdated Properties" in DAO Help. +The date and time the querydef was created. To directly retrieve the date the querydef was created, call the [GetDateCreated](../../mfc/reference/cdaotabledef-class.md#getdatecreated) member function of the `CDaoTableDef` object associated with the table. For more information, see [Remarks](#remarks). Also see the topic "DateCreated, LastUpdated Properties" in DAO Help. *m_dateLastUpdated*
-The date and time of the most recent change made to the querydef. To directly retrieve the date the table was last updated, call the [GetDateLastUpdated](../../mfc/reference/cdaoquerydef-class.md#getdatelastupdated) member function of the querydef. See Comments below for more information. And see the topic "DateCreated, LastUpdated Properties" in DAO Help. +The date and time of the most recent change made to the querydef. To directly retrieve the date the table was last updated, call the [GetDateLastUpdated](../../mfc/reference/cdaoquerydef-class.md#getdatelastupdated) member function of the querydef. For more information, see [Remarks](#remarks). Also see the topic "DateCreated, LastUpdated Properties" in DAO Help. *m_bUpdatable*
-Indicates whether changes can be made to a querydef object. If this property is TRUE, the querydef is updatable; otherwise, it is not. Updatable means the querydef object's query definition can be changed. The Updatable property of a querydef object is set to TRUE if the query definition can be updated, even if the resulting recordset is not updatable. To retrieve this property directly, call the querydef's [CanUpdate](../../mfc/reference/cdaoquerydef-class.md#canupdate) member function. For more information, see the topic "Updatable Property" in DAO Help. +Indicates whether changes can be made to a querydef object. If this property is TRUE, the querydef is updatable; otherwise, it isn't. Updatable means the querydef object's query definition can be changed. The Updatable property of a querydef object is set to TRUE if the query definition can be updated, even if the resulting recordset isn't updatable. To retrieve this property directly, call the querydef's [CanUpdate](../../mfc/reference/cdaoquerydef-class.md#canupdate) member function. For more information, see the topic "Updatable Property" in DAO Help. *m_bReturnsRecords*
Indicates whether a SQL pass-through query to an external database returns records. If this property is TRUE, the query returns records. To directly retrieve this property, call [CDaoQueryDef::GetReturnsRecords](../../mfc/reference/cdaoquerydef-class.md#getreturnsrecords). Not all SQL pass-through queries to external databases return records. For example, a SQL **UPDATE** statement updates records without returning records, while a SQL **SELECT** statement does return records. For more information, see the topic "ReturnsRecords Property" in DAO Help. @@ -81,21 +83,21 @@ The SQL statement that defines the query executed by a querydef object. The SQL Provides information about the source of a database used in a pass-through query. This information takes the form of a connect string. For more information about connect strings, and for information about retrieving the value of this property directly, see the [CDaoDatabase::GetConnect](../../mfc/reference/cdaodatabase-class.md#getconnect) member function. *m_nODBCTimeout*
-The number of seconds the Microsoft Jet database engine waits before a timeout error occurs when a query is run on an ODBC database. When you're using an ODBC database, such as Microsoft SQL Server, there may be delays because of network traffic or heavy use of the ODBC server. Rather than waiting indefinitely, you can specify how long the Microsoft Jet engine waits before it produces an error. The default timeout value is 60 seconds. You can retrieve the value of this property directly by calling the querydef's [GetODBCTimeout](../../mfc/reference/cdaoquerydef-class.md#getodbctimeout) member function. For more information, see the topic "ODBCTimeout Property" in DAO Help. +The number of seconds the Microsoft Jet database engine waits before a timeout error occurs when a query is run on an Open Database Connectivity (ODBC) database. When you're using an ODBC database, such as Microsoft SQL Server, there may be delays because of network traffic or heavy use of the ODBC server. Rather than waiting indefinitely, you can specify how long the Microsoft Jet engine waits before it produces an error. The default timeout value is 60 seconds. You can retrieve the value of this property directly by calling the querydef's [GetODBCTimeout](../../mfc/reference/cdaoquerydef-class.md#getodbctimeout) member function. For more information, see the topic "ODBCTimeout Property" in DAO Help. ## Remarks -The querydef is an object of class [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md). The references to Primary, Secondary, and All above indicate how the information is returned by the [GetQueryDefInfo](../../mfc/reference/cdaodatabase-class.md#getquerydefinfo) member function in class `CDaoDatabase`. +The querydef is an object of class [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md). The references to Primary, Secondary, and All indicate how the information is returned by the [GetQueryDefInfo](../../mfc/reference/cdaodatabase-class.md#getquerydefinfo) member function in class `CDaoDatabase`. -Information retrieved by the [CDaoDatabase::GetQueryDefInfo](../../mfc/reference/cdaodatabase-class.md#getquerydefinfo) member function is stored in a `CDaoQueryDefInfo` structure. Call `GetQueryDefInfo` for the database object in whose QueryDefs collection the querydef object is stored. `CDaoQueryDefInfo` also defines a `Dump` member function in debug builds. You can use `Dump` to dump the contents of a `CDaoQueryDefInfo` object. Class `CDaoDatabase` also supplies member functions for directly accessing all of the properties returned in a `CDaoQueryDefInfo` object, so you will probably seldom need to call `GetQueryDefInfo`. +Information retrieved by the [CDaoDatabase::GetQueryDefInfo](../../mfc/reference/cdaodatabase-class.md#getquerydefinfo) member function is stored in a `CDaoQueryDefInfo` structure. Call `GetQueryDefInfo` for the database object in whose QueryDefs collection the querydef object is stored. `CDaoQueryDefInfo` also defines a `Dump` member function in debug builds. You can use `Dump` to dump the contents of a `CDaoQueryDefInfo` object. Class `CDaoDatabase` also supplies member functions for directly accessing all of the properties returned in a `CDaoQueryDefInfo` object, so you seldom call `GetQueryDefInfo`. -When you append a new field or parameter object to the Fields or Parameters collection of a querydef object, an exception is thrown if the underlying database does not support the data type specified for the new object. +When you append a new field or parameter object to the Fields or Parameters collection of a querydef object, an exception is thrown if the underlying database doesn't support the data type specified for the new object. The date and time settings are derived from the computer on which the querydef was created or last updated. In a multiuser environment, users should get these settings directly from the file server using the **net time** command to avoid discrepancies in the DateCreated and LastUpdated property settings. ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaorecordset-class.md b/docs/mfc/reference/cdaorecordset-class.md index 1e04df6fb4..4525538078 100644 --- a/docs/mfc/reference/cdaorecordset-class.md +++ b/docs/mfc/reference/cdaorecordset-class.md @@ -1,15 +1,18 @@ --- -description: "Learn more about: CDaoRecordset Class" title: "CDaoRecordset Class" -ms.date: "08/27/2018" +description: "Learn more about: CDaoRecordset Class" +ms.date: 08/27/2018 f1_keywords: ["CDaoRecordset", "AFXDAO/CDaoRecordset", "AFXDAO/CDaoRecordset::CDaoRecordset", "AFXDAO/CDaoRecordset::AddNew", "AFXDAO/CDaoRecordset::CanAppend", "AFXDAO/CDaoRecordset::CanBookmark", "AFXDAO/CDaoRecordset::CancelUpdate", "AFXDAO/CDaoRecordset::CanRestart", "AFXDAO/CDaoRecordset::CanScroll", "AFXDAO/CDaoRecordset::CanTransact", "AFXDAO/CDaoRecordset::CanUpdate", "AFXDAO/CDaoRecordset::Close", "AFXDAO/CDaoRecordset::Delete", "AFXDAO/CDaoRecordset::DoFieldExchange", "AFXDAO/CDaoRecordset::Edit", "AFXDAO/CDaoRecordset::FillCache", "AFXDAO/CDaoRecordset::Find", "AFXDAO/CDaoRecordset::FindFirst", "AFXDAO/CDaoRecordset::FindLast", "AFXDAO/CDaoRecordset::FindNext", "AFXDAO/CDaoRecordset::FindPrev", "AFXDAO/CDaoRecordset::GetAbsolutePosition", "AFXDAO/CDaoRecordset::GetBookmark", "AFXDAO/CDaoRecordset::GetCacheSize", "AFXDAO/CDaoRecordset::GetCacheStart", "AFXDAO/CDaoRecordset::GetCurrentIndex", "AFXDAO/CDaoRecordset::GetDateCreated", "AFXDAO/CDaoRecordset::GetDateLastUpdated", "AFXDAO/CDaoRecordset::GetDefaultDBName", "AFXDAO/CDaoRecordset::GetDefaultSQL", "AFXDAO/CDaoRecordset::GetEditMode", "AFXDAO/CDaoRecordset::GetFieldCount", "AFXDAO/CDaoRecordset::GetFieldInfo", "AFXDAO/CDaoRecordset::GetFieldValue", "AFXDAO/CDaoRecordset::GetIndexCount", "AFXDAO/CDaoRecordset::GetIndexInfo", "AFXDAO/CDaoRecordset::GetLastModifiedBookmark", "AFXDAO/CDaoRecordset::GetLockingMode", "AFXDAO/CDaoRecordset::GetName", "AFXDAO/CDaoRecordset::GetParamValue", "AFXDAO/CDaoRecordset::GetPercentPosition", "AFXDAO/CDaoRecordset::GetRecordCount", "AFXDAO/CDaoRecordset::GetSQL", "AFXDAO/CDaoRecordset::GetType", "AFXDAO/CDaoRecordset::GetValidationRule", "AFXDAO/CDaoRecordset::GetValidationText", "AFXDAO/CDaoRecordset::IsBOF", "AFXDAO/CDaoRecordset::IsDeleted", "AFXDAO/CDaoRecordset::IsEOF", "AFXDAO/CDaoRecordset::IsFieldDirty", "AFXDAO/CDaoRecordset::IsFieldNull", "AFXDAO/CDaoRecordset::IsFieldNullable", "AFXDAO/CDaoRecordset::IsOpen", "AFXDAO/CDaoRecordset::Move", "AFXDAO/CDaoRecordset::MoveFirst", "AFXDAO/CDaoRecordset::MoveLast", "AFXDAO/CDaoRecordset::MoveNext", "AFXDAO/CDaoRecordset::MovePrev", "AFXDAO/CDaoRecordset::Open", "AFXDAO/CDaoRecordset::Requery", "AFXDAO/CDaoRecordset::Seek", "AFXDAO/CDaoRecordset::SetAbsolutePosition", "AFXDAO/CDaoRecordset::SetBookmark", "AFXDAO/CDaoRecordset::SetCacheSize", "AFXDAO/CDaoRecordset::SetCacheStart", "AFXDAO/CDaoRecordset::SetCurrentIndex", "AFXDAO/CDaoRecordset::SetFieldDirty", "AFXDAO/CDaoRecordset::SetFieldNull", "AFXDAO/CDaoRecordset::SetFieldValue", "AFXDAO/CDaoRecordset::SetFieldValueNull", "AFXDAO/CDaoRecordset::SetLockingMode", "AFXDAO/CDaoRecordset::SetParamValue", "AFXDAO/CDaoRecordset::SetParamValueNull", "AFXDAO/CDaoRecordset::SetPercentPosition", "AFXDAO/CDaoRecordset::Update", "AFXDAO/CDaoRecordset::m_bCheckCacheForDirtyFields", "AFXDAO/CDaoRecordset::m_nFields", "AFXDAO/CDaoRecordset::m_nParams", "AFXDAO/CDaoRecordset::m_pDAORecordset", "AFXDAO/CDaoRecordset::m_pDatabase", "AFXDAO/CDaoRecordset::m_strFilter", "AFXDAO/CDaoRecordset::m_strSort"] helpviewer_keywords: ["CDaoRecordset [MFC], CDaoRecordset", "CDaoRecordset [MFC], AddNew", "CDaoRecordset [MFC], CanAppend", "CDaoRecordset [MFC], CanBookmark", "CDaoRecordset [MFC], CancelUpdate", "CDaoRecordset [MFC], CanRestart", "CDaoRecordset [MFC], CanScroll", "CDaoRecordset [MFC], CanTransact", "CDaoRecordset [MFC], CanUpdate", "CDaoRecordset [MFC], Close", "CDaoRecordset [MFC], Delete", "CDaoRecordset [MFC], DoFieldExchange", "CDaoRecordset [MFC], Edit", "CDaoRecordset [MFC], FillCache", "CDaoRecordset [MFC], Find", "CDaoRecordset [MFC], FindFirst", "CDaoRecordset [MFC], FindLast", "CDaoRecordset [MFC], FindNext", "CDaoRecordset [MFC], FindPrev", "CDaoRecordset [MFC], GetAbsolutePosition", "CDaoRecordset [MFC], GetBookmark", "CDaoRecordset [MFC], GetCacheSize", "CDaoRecordset [MFC], GetCacheStart", "CDaoRecordset [MFC], GetCurrentIndex", "CDaoRecordset [MFC], GetDateCreated", "CDaoRecordset [MFC], GetDateLastUpdated", "CDaoRecordset [MFC], GetDefaultDBName", "CDaoRecordset [MFC], GetDefaultSQL", "CDaoRecordset [MFC], GetEditMode", "CDaoRecordset [MFC], GetFieldCount", "CDaoRecordset [MFC], GetFieldInfo", "CDaoRecordset [MFC], GetFieldValue", "CDaoRecordset [MFC], GetIndexCount", "CDaoRecordset [MFC], GetIndexInfo", "CDaoRecordset [MFC], GetLastModifiedBookmark", "CDaoRecordset [MFC], GetLockingMode", "CDaoRecordset [MFC], GetName", "CDaoRecordset [MFC], GetParamValue", "CDaoRecordset [MFC], GetPercentPosition", "CDaoRecordset [MFC], GetRecordCount", "CDaoRecordset [MFC], GetSQL", "CDaoRecordset [MFC], GetType", "CDaoRecordset [MFC], GetValidationRule", "CDaoRecordset [MFC], GetValidationText", "CDaoRecordset [MFC], IsBOF", "CDaoRecordset [MFC], IsDeleted", "CDaoRecordset [MFC], IsEOF", "CDaoRecordset [MFC], IsFieldDirty", "CDaoRecordset [MFC], IsFieldNull", "CDaoRecordset [MFC], IsFieldNullable", "CDaoRecordset [MFC], IsOpen", "CDaoRecordset [MFC], Move", "CDaoRecordset [MFC], MoveFirst", "CDaoRecordset [MFC], MoveLast", "CDaoRecordset [MFC], MoveNext", "CDaoRecordset [MFC], MovePrev", "CDaoRecordset [MFC], Open", "CDaoRecordset [MFC], Requery", "CDaoRecordset [MFC], Seek", "CDaoRecordset [MFC], SetAbsolutePosition", "CDaoRecordset [MFC], SetBookmark", "CDaoRecordset [MFC], SetCacheSize", "CDaoRecordset [MFC], SetCacheStart", "CDaoRecordset [MFC], SetCurrentIndex", "CDaoRecordset [MFC], SetFieldDirty", "CDaoRecordset [MFC], SetFieldNull", "CDaoRecordset [MFC], SetFieldValue", "CDaoRecordset [MFC], SetFieldValueNull", "CDaoRecordset [MFC], SetLockingMode", "CDaoRecordset [MFC], SetParamValue", "CDaoRecordset [MFC], SetParamValueNull", "CDaoRecordset [MFC], SetPercentPosition", "CDaoRecordset [MFC], Update", "CDaoRecordset [MFC], m_bCheckCacheForDirtyFields", "CDaoRecordset [MFC], m_nFields", "CDaoRecordset [MFC], m_nParams", "CDaoRecordset [MFC], m_pDAORecordset", "CDaoRecordset [MFC], m_pDatabase", "CDaoRecordset [MFC], m_strFilter", "CDaoRecordset [MFC], m_strSort"] -ms.assetid: 2322067f-1027-4662-a5d7-aa2fc7488630 --- # CDaoRecordset Class Represents a set of records selected from a data source. +> [!NOTE] +> Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete. + + ## Syntax ```cpp @@ -69,11 +72,11 @@ class CDaoRecordset : public CObject |[CDaoRecordset::GetRecordCount](#getrecordcount)|Returns the number of records accessed in a recordset object.| |[CDaoRecordset::GetSQL](#getsql)|Gets the SQL string used to select records for the recordset.| |[CDaoRecordset::GetType](#gettype)|Called to determine the type of a recordset: table-type, dynaset-type, or snapshot-type.| -|[CDaoRecordset::GetValidationRule](#getvalidationrule)|Returns a `CString` containing the value that validates data as it is entered into a field.| -|[CDaoRecordset::GetValidationText](#getvalidationtext)|Retrieves the text that is displayed when a validation rule is not satisfied.| -|[CDaoRecordset::IsBOF](#isbof)|Returns nonzero if the recordset has been positioned before the first record. There is no current record.| +|[CDaoRecordset::GetValidationRule](#getvalidationrule)|Returns a `CString` containing the value that validates data as it's entered into a field.| +|[CDaoRecordset::GetValidationText](#getvalidationtext)|Retrieves the text that is displayed when a validation rule isn't satisfied.| +|[CDaoRecordset::IsBOF](#isbof)|Returns nonzero if the recordset has been positioned before the first record. There's no current record.| |[CDaoRecordset::IsDeleted](#isdeleted)|Returns nonzero if the recordset is positioned on a deleted record.| -|[CDaoRecordset::IsEOF](#iseof)|Returns nonzero if the recordset has been positioned after the last record. There is no current record.| +|[CDaoRecordset::IsEOF](#iseof)|Returns nonzero if the recordset has been positioned after the last record. There's no current record.| |[CDaoRecordset::IsFieldDirty](#isfielddirty)|Returns nonzero if the specified field in the current record has been changed.| |[CDaoRecordset::IsFieldNull](#isfieldnull)|Returns nonzero if the specified field in the current record is Null (having no value).| |[CDaoRecordset::IsFieldNullable](#isfieldnullable)|Returns nonzero if the specified field in the current record can be set to Null (having no value).| @@ -107,7 +110,7 @@ class CDaoRecordset : public CObject |----------|-----------------| |[CDaoRecordset::m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields)|Contains a flag indicating whether fields are automatically marked as changed.| |[CDaoRecordset::m_nFields](#m_nfields)|Contains the number of field data members in the recordset class and the number of columns selected by the recordset from the data source.| -|[CDaoRecordset::m_nParams](#m_nparams)|Contains the number of parameter data members in the recordset class — the number of parameters passed with the recordset's query| +|[CDaoRecordset::m_nParams](#m_nparams)|Contains the number of parameter data members in the recordset class—the number of parameters passed with the recordset's query| |[CDaoRecordset::m_pDAORecordset](#m_pdaorecordset)|A pointer to the DAO interface underlying the recordset object.| |[CDaoRecordset::m_pDatabase](#m_pdatabase)|Source database for this result set. Contains a pointer to a [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object.| |[CDaoRecordset::m_strFilter](#m_strfilter)|Contains a string used to construct a SQL **WHERE** statement.| @@ -121,9 +124,9 @@ Known as "recordsets," `CDaoRecordset` objects are available in the following th - Dynaset-type recordsets are the result of a query that can have updateable records. These recordsets are a set of records that you can use to examine, add, change, or delete records from an underlying database table or tables. Dynaset-type recordsets can contain fields from one or more tables in a database. -- Snapshot-type recordsets are a static copy of a set of records that you can use to find data or generate reports. These recordsets can contain fields from one or more tables in a database but cannot be updated. +- Snapshot-type recordsets are a static copy of a set of records that you can use to find data or generate reports. These recordsets can contain fields from one or more tables in a database but can't be updated. -Each form of recordset represents a set of records fixed at the time the recordset is opened. When you scroll to a record in a table-type recordset or a dynaset-type recordset, it reflects changes made to the record after the recordset is opened, either by other users or by other recordsets in your application. (A snapshot-type recordset cannot be updated.) You can use `CDaoRecordset` directly or derive an application-specific recordset class from `CDaoRecordset`. You can then: +Each form of recordset represents a set of records fixed at the time the recordset is opened. When you scroll to a record in a table-type recordset or a dynaset-type recordset, it reflects changes made to the record after the recordset is opened, either by other users or by other recordsets in your application. (A snapshot-type recordset can't be updated.) You can use `CDaoRecordset` directly or derive an application-specific recordset class from `CDaoRecordset`. You can then: - Scroll through the records. @@ -146,7 +149,7 @@ Class `CDaoRecordset` supplies an interface similar to that of class `CRecordset You can either use `CDaoRecordset` directly or derive a class from `CDaoRecordset`. To use a recordset class in either case, open a database and construct a recordset object, passing the constructor a pointer to your `CDaoDatabase` object. You can also construct a `CDaoRecordset` object and let MFC create a temporary `CDaoDatabase` object for you. Then call the recordset's [Open](#open) member function, specifying whether the object is a table-type recordset, a dynaset-type recordset, or a snapshot-type recordset. Calling `Open` selects data from the database and retrieves the first record. -Use the object's member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a table-type recordset, a dynaset-type recordset, or a snapshot-type recordset, and whether it is updateable or read-only — this depends on the capability of the database or Open Database Connectivity (ODBC) data source. To refresh records that may have been changed or added since the `Open` call, call the object's [Requery](#requery) member function. Call the object's `Close` member function and destroy the object when you finish with it. +Use the object's member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a table-type recordset, a dynaset-type recordset, or a snapshot-type recordset, and whether it's updateable or read-only — this depends on the capability of the database or Open Database Connectivity (ODBC) data source. To refresh records that may have been changed or added since the `Open` call, call the object's [Requery](#requery) member function. Call the object's `Close` member function and destroy the object when you finish with it. `CDaoRecordset` uses DAO record field exchange (DFX) to support reading and updating of record fields through type-safe C++ members of your `CDaoRecordset` or `CDaoRecordset`-derived class. You can also implement dynamic binding of columns in a database without using the DFX mechanism using [GetFieldValue](#getfieldvalue) and [SetFieldValue](#setfieldvalue). @@ -160,7 +163,7 @@ For related information, see the topic "Recordset Object" in DAO Help. ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoRecordset::AddNew @@ -172,7 +175,7 @@ virtual void AddNew(); ### Remarks -The record's fields are initially Null. (In database terminology, Null means "having no value" and is not the same as NULL in C++.) To complete the operation, you must call the [Update](#update) member function. `Update` saves your changes to the data source. +The record's fields are initially Null. (In database terminology, Null means "having no value" and isn't the same as NULL in C++.) To complete the operation, you must call the [Update](#update) member function. `Update` saves your changes to the data source. > [!CAUTION] > If you edit a record and then scroll to another record without calling `Update`, your changes are lost without warning. @@ -181,7 +184,7 @@ If you add a record to a dynaset-type recordset by calling [AddNew](#addnew), th The position of the new record depends on the type of recordset: -- In a dynaset-type recordset, where the new record is inserted is not guaranteed. This behavior changed with Microsoft Jet 3.0 for reasons of performance and concurrency. If your goal is to make the newly added record the current record, get the bookmark of the last modified record and move to that bookmark: +- In a dynaset-type recordset, where the new record is inserted isn't guaranteed. This behavior changed with Microsoft Jet 3.0 for reasons of performance and concurrency. If your goal is to make the newly added record the current record, get the bookmark of the last modified record and move to that bookmark: [!code-cpp[NVC_MFCDatabase#1](../../mfc/codesnippet/cpp/cdaorecordset-class_1.cpp)] @@ -189,13 +192,13 @@ The position of the new record depends on the type of recordset: The record that was current before you used `AddNew` remains current. If you want to make the new record current and the recordset supports bookmarks, call [SetBookmark](#setbookmark) to the bookmark identified by the LastModified property setting of the underlying DAO recordset object. Doing so is useful for determining the value for counter (auto-increment) fields in an added record. For more information, see [GetLastModifiedBookmark](#getlastmodifiedbookmark). -If the database supports transactions, you can make your `AddNew` call part of a transaction. For more information about transactions, see class [CDaoWorkspace](../../mfc/reference/cdaoworkspace-class.md). Note that you should call [CDaoWorkspace::BeginTrans](../../mfc/reference/cdaoworkspace-class.md#begintrans) before calling `AddNew`. +If the database supports transactions, you can make your `AddNew` call part of a transaction. For more information about transactions, see class [CDaoWorkspace](../../mfc/reference/cdaoworkspace-class.md). You should call [CDaoWorkspace::BeginTrans](../../mfc/reference/cdaoworkspace-class.md#begintrans) before calling `AddNew`. -It is illegal to call `AddNew` for a recordset whose [Open](#open) member function has not been called. A `CDaoException` is thrown if you call `AddNew` for a recordset that cannot be appended. You can determine whether the recordset is updateable by calling [CanAppend](#canappend). +It's illegal to call `AddNew` for a recordset whose [`Open`](#open) member function hasn't been called. A `CDaoException` is thrown if you call `AddNew` for a recordset that can't be appended. You can determine whether the recordset is updateable by calling [CanAppend](#canappend). -The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call [SetFieldDirty](#setfielddirty) yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of **PSEUDO NULL**. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). +The framework marks changed field data members to ensure they'll be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you'll seldom need to call [SetFieldDirty](#setfielddirty) yourself, but you might sometimes want to ensure that columns are explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of **PSEUDO NULL**. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). -If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicitly set the field dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. +If the double-buffering mechanism isn't being used, then changing the value of the field doesn't automatically set the field as dirty. In this case, it's necessary to explicitly set the field dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. > [!NOTE] > If records are double-buffered (that is, automatic field checking is enabled), calling `CancelUpdate` will restore the member variables to the values they had before `AddNew` or `Edit` was called. @@ -212,7 +215,7 @@ BOOL CanAppend() const; ### Return Value -Nonzero if the recordset allows adding new records; otherwise 0. `CanAppend` will return 0 if you opened the recordset as read-only. +Nonzero if the recordset allows adding new records; otherwise 0. `CanAppend` returns 0 if you opened the recordset as read-only. ### Remarks @@ -232,7 +235,7 @@ Nonzero if the recordset supports bookmarks, otherwise 0. ### Remarks -If you are using recordsets based entirely on Microsoft Jet database engine tables, bookmarks can be used except on snapshot-type recordsets flagged as forward-only scrolling recordsets. Other database products (external ODBC data sources) may not support bookmarks. +If you're using recordsets based entirely on Microsoft Jet database engine tables, bookmarks can be used except on snapshot-type recordsets flagged as forward-only scrolling recordsets. Other database products (external ODBC data sources) may not support bookmarks. For related information, see the topic "Bookmarkable Property" in DAO Help. @@ -246,12 +249,12 @@ virtual void CancelUpdate(); ### Remarks -For example, if an application calls the `Edit` or `AddNew` member function and has not called [Update](#update), `CancelUpdate` cancels any changes made after `Edit` or `AddNew` was called. +For example, if an application calls the `Edit` or `AddNew` member function and hasn't called [`Update`](#update), `CancelUpdate` cancels any changes made after `Edit` or `AddNew` was called. > [!NOTE] > If records are double-buffered (that is, automatic field checking is enabled), calling `CancelUpdate` will restore the member variables to the values they had before `AddNew` or `Edit` was called. -If there is no `Edit` or `AddNew` operation pending, `CancelUpdate` causes MFC to throw an exception. Call the [GetEditMode](#geteditmode) member function to determine if there is a pending operation that can be canceled. +If there's no `Edit` or `AddNew` operation pending, `CancelUpdate` causes MFC to throw an exception. Call the [GetEditMode](#geteditmode) member function to determine if there's a pending operation that can be canceled. For related information, see the topic "CancelUpdate Method" in DAO Help. @@ -269,9 +272,9 @@ Nonzero if `Requery` can be called to run the recordset's query again, otherwise ### Remarks -Table-type recordsets do not support `Requery`. +Table-type recordsets don't support `Requery`. -If `Requery` is not supported, call [Close](#close) then [Open](#open) to refresh the data. You can call `Requery` to update a recordset object's underlying parameter query after the parameter values have been changed. +If `Requery` isn't supported, call [Close](#close) then [Open](#open) to refresh the data. You can call `Requery` to update a recordset object's underlying parameter query after the parameter values have been changed. For related information, see the topic "Restartable Property" in DAO Help. @@ -338,7 +341,7 @@ CDaoRecordset(CDaoDatabase* pDatabase = NULL); ### Parameters *pDatabase*
-Contains a pointer to a [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object or the value NULL. If not NULL and the `CDaoDatabase` object's `Open` member function has not been called to connect it to the data source, the recordset attempts to open it for you during its own [Open](#open) call. If you pass NULL, a `CDaoDatabase` object is constructed and connected for you using the data source information you specified if you derived your recordset class from `CDaoRecordset`. +Contains a pointer to a [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object or the value NULL. If not NULL and the `CDaoDatabase` object's `Open` member function hasn't been called to connect it to the data source, the recordset attempts to open it for you during its own [Open](#open) call. If you pass NULL, a `CDaoDatabase` object is constructed and connected for you using the data source information you specified if you derived your recordset class from `CDaoRecordset`. ### Remarks @@ -347,7 +350,7 @@ You can either use `CDaoRecordset` directly or derive an application-specific cl > [!NOTE] > If you derive a `CDaoRecordset` class, your derived class must supply its own constructor. In the constructor of your derived class, call the constructor `CDaoRecordset::CDaoRecordset`, passing the appropriate parameters along to it. -Pass NULL to your recordset constructor to have a `CDaoDatabase` object constructed and connected for you automatically. This is a useful shortcut that does not require you to construct and connect a `CDaoDatabase` object prior to constructing your recordset. If the `CDaoDatabase` object is not open, a [CDaoWorkspace](../../mfc/reference/cdaoworkspace-class.md) object will also be created for you that uses the default workspace. For more information, see [CDaoDatabase::CDaoDatabase](../../mfc/reference/cdaodatabase-class.md#cdaodatabase). +Pass NULL to your recordset constructor to have a `CDaoDatabase` object constructed and connected for you automatically. This is a useful shortcut that doesn't require you to construct and connect a `CDaoDatabase` object prior to constructing your recordset. If the `CDaoDatabase` object isn't open, a [CDaoWorkspace](../../mfc/reference/cdaoworkspace-class.md) object will also be created for you that uses the default workspace. For more information, see [CDaoDatabase::CDaoDatabase](../../mfc/reference/cdaodatabase-class.md#cdaodatabase). ## CDaoRecordset::Close @@ -359,7 +362,7 @@ virtual void Close(); ### Remarks -Because `Close` does not destroy the `CDaoRecordset` object, you can reuse the object by calling `Open` on the same data source or a different data source. +Because `Close` doesn't destroy the `CDaoRecordset` object, you can reuse the object by calling `Open` on the same data source or a different data source. All pending [AddNew](#addnew) or [Edit](#edit) statements are canceled, and all pending transactions are rolled back. If you want to preserve pending additions or edits, call [Update](#update) before you call `Close` for each recordset. @@ -379,14 +382,14 @@ virtual void Delete(); After a successful deletion, the recordset's field data members are set to a Null value, and you must explicitly call one of the recordset navigation member functions ( [Move](#move), [Seek](#seek), [SetBookmark](#setbookmark), and so on) in order to move off the deleted record. When you delete records from a recordset, there must be a current record in the recordset before you call `Delete`; otherwise, MFC throws an exception. -`Delete` removes the current record and makes it inaccessible. Although you cannot edit or use the deleted record, it remains current. Once you move to another record, however, you cannot make the deleted record current again. +`Delete` removes the current record and makes it inaccessible. Although you can't edit or use the deleted record, it remains current. Once you move to another record, however, you can't make the deleted record current again. > [!CAUTION] -> The recordset must be updatable and there must be a valid record current in the recordset when you call `Delete`. For example, if you delete a record but do not scroll to a new record before you call `Delete` again, `Delete` throws a [CDaoException](../../mfc/reference/cdaoexception-class.md). +> The recordset must be updatable and there must be a valid record current in the recordset when you call `Delete`. For example, if you delete a record but don't scroll to a new record before you call `Delete` again, `Delete` throws a [CDaoException](../../mfc/reference/cdaoexception-class.md). You can undelete a record if you use transactions and you call the [CDaoWorkspace::Rollback](../../mfc/reference/cdaoworkspace-class.md#rollback) member function. If the base table is the primary table in a cascade delete relationship, deleting the current record may also delete one or more records in a foreign table. For more information, see the definition "cascade delete" in DAO Help. -Unlike `AddNew` and `Edit`, a call to `Delete` is not followed by a call to `Update`. +Unlike `AddNew` and `Edit`, a call to `Delete` isn't followed by a call to `Update`. For related information, see the topics "AddNew Method", "Edit Method", "Delete Method", "Update Method", and "Updatable Property" in DAO Help. @@ -405,9 +408,9 @@ Contains a pointer to a `CDaoFieldExchange` object. The framework will already h ### Remarks -It also binds your parameter data members, if any, to parameter placeholders in the SQL statement string for the recordset's selection. The exchange of field data, called DAO record field exchange (DFX), works in both directions: from the recordset object's field data members to the fields of the record on the data source, and from the record on the data source to the recordset object. If you are binding columns dynamically, you are not required to implement `DoFieldExchange`. +It also binds your parameter data members, if any, to parameter placeholders in the SQL statement string for the recordset's selection. The exchange of field data, called DAO record field exchange (DFX), works in both directions: from the recordset object's field data members to the fields of the record on the data source, and from the record on the data source to the recordset object. If you're binding columns dynamically, you're not required to implement `DoFieldExchange`. -The only action you must normally take to implement `DoFieldExchange` for your derived recordset class is to create the class with ClassWizard and specify the names and data types of the field data members. You might also add code to what ClassWizard writes to specify parameter data members. If all fields are to be bound dynamically, this function will be inactive unless you specify parameter data members. +The only action you must normally take to implement `DoFieldExchange` for your derived recordset class is to create the class with ClassWizard and specify the names and data types of the field data members. You might also add code to what ClassWizard writes to specify parameter data members. If all fields are to be bound dynamically, this function is inactive unless you specify parameter data members. When you declare your derived recordset class with ClassWizard, the wizard writes an override of `DoFieldExchange` for you, which resembles the following example: @@ -428,20 +431,20 @@ Once you call the `Edit` member function, changes made to the current record's f > [!CAUTION] > If you edit a record and then perform any operation that moves to another record without first calling `Update`, your changes are lost without warning. In addition, if you close the recordset or the parent database, your edited record is discarded without warning. -In some cases, you may want to update a column by making it Null (containing no data). To do so, call `SetFieldNull` with a parameter of TRUE to mark the field Null; this also causes the column to be updated. If you want a field to be written to the data source even though its value has not changed, call `SetFieldDirty` with a parameter of TRUE. This works even if the field had the value Null. +In some cases, you may want to update a column by making it Null (containing no data). To do so, call `SetFieldNull` with a parameter of TRUE to mark the field Null; this also causes the column to be updated. If you want a field to be written to the data source even though its value hasn't changed, call `SetFieldDirty` with a parameter of TRUE. This works even if the field had the value Null. -The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call [SetFieldDirty](#setfielddirty) yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of **PSEUDO NULL**. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). +The framework marks changed field data members to ensure they'll be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you'll seldom need to call [SetFieldDirty](#setfielddirty) yourself, but you might sometimes want to ensure that columns are explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of **PSEUDO NULL**. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). -If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicitly set the field dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. +If the double-buffering mechanism isn't being used, then changing the value of the field doesn't automatically set the field as dirty. In this case, it's necessary to explicitly set the field dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. -When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time `Edit` is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it is updated in the database. If the record has changed since you called `Edit`, the `Update` operation fails and MFC throws an exception. You can change the locking mode with `SetLockingMode`. +When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time `Edit` is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it's updated in the database. If the record has changed since you called `Edit`, the `Update` operation fails and MFC throws an exception. You can change the locking mode with `SetLockingMode`. > [!NOTE] > Optimistic locking is always used on external database formats, such as ODBC and installable ISAM. -The current record remains current after you call `Edit`. To call `Edit`, there must be a current record. If there is no current record or if the recordset does not refer to an open table-type or dynaset-type recordset object, an exception occurs. Calling `Edit` causes a `CDaoException` to be thrown under the following conditions: +The current record remains current after you call `Edit`. To call `Edit`, there must be a current record. If there's no current record or if the recordset doesn't refer to an open table-type or dynaset-type recordset object, an exception occurs. Calling `Edit` causes a `CDaoException` to be thrown under the following conditions: -- There is no current record. +- There's no current record. - The database or recordset is read-only. @@ -451,7 +454,7 @@ The current record remains current after you call `Edit`. To call `Edit`, there - Another user has locked the page containing your record. -If the data source supports transactions, you can make the `Edit` call part of a transaction. Note that you should call `CDaoWorkspace::BeginTrans` before calling `Edit` and after the recordset has been opened. Also note that calling `CDaoWorkspace::CommitTrans` is not a substitute for calling `Update` to complete the `Edit` operation. For more information about transactions, see class `CDaoWorkspace`. +If the data source supports transactions, you can make the `Edit` call part of a transaction. You should call `CDaoWorkspace::BeginTrans` before calling `Edit` and after the recordset has been opened. Calling `CDaoWorkspace::CommitTrans` isn't a substitute for calling `Update` to complete the `Edit` operation. For more information about transactions, see class `CDaoWorkspace`. For related information, see the topics "AddNew Method", "Edit Method", "Delete Method", "Update Method", and "Updatable Property" in DAO Help. @@ -475,13 +478,13 @@ A [COleVariant](../../mfc/reference/colevariant-class.md) specifying a bookmark. ### Remarks -Caching improves the performance of an application that retrieves, or fetches, data from a remote server. A cache is space in local memory that holds the data most recently fetched from the server on the assumption that the data will probably be requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the data first rather than fetching it from the server, which takes more time. Using data caching on non-ODBC data sources has no effect as the data is not saved in the cache. +Caching improves the performance of an application that retrieves, or fetches, data from a remote server. A cache is space in local memory that holds the data most recently fetched from the server on the assumption that the data will probably be requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the data first rather than fetching it from the server, which takes more time. Using data caching on non-ODBC data sources has no effect as the data isn't saved in the cache. Rather than waiting for the cache to be filled with records as they are fetched, you can explicitly fill the cache at any time by calling the `FillCache` member function. This is a faster way to fill the cache because `FillCache` fetches several records at once instead of one at a time. For example, while each screenful of records is being displayed, you can have your application call `FillCache` to fetch the next screenful of records. -Any ODBC database accessed with recordset objects can have a local cache. To create the cache, open a recordset object from the remote data source, and then call the `SetCacheSize` and `SetCacheStart` member functions of the recordset. If *lSize* and *lBookmark* create a range that is partly or wholly outside the range specified by `SetCacheSize` and `SetCacheStart`, the portion of the recordset outside this range is ignored and is not loaded into the cache. If `FillCache` requests more records than remain in the remote data source, only the remaining records are fetched, and no exception is thrown. +Any ODBC database accessed with recordset objects can have a local cache. To create the cache, open a recordset object from the remote data source, and then call the `SetCacheSize` and `SetCacheStart` member functions of the recordset. If *lSize* and *lBookmark* create a range that is partly or wholly outside the range specified by `SetCacheSize` and `SetCacheStart`, the portion of the recordset outside this range is ignored and isn't loaded into the cache. If `FillCache` requests more records than remain in the remote data source, only the remaining records are fetched, and no exception is thrown. -Records fetched from the cache do not reflect changes made concurrently to the source data by other users. +Records fetched from the cache don't reflect changes made concurrently to the source data by other users. `FillCache` fetches only records not already cached. To force an update of all the cached data, call the `SetCacheSize` member function with an *lSize* parameter equal to 0, call `SetCacheSize` again with the *lSize* parameter equal to the size of the cache you originally requested, and then call `FillCache`. @@ -526,7 +529,7 @@ You can find the first, next, previous, or last instance of the string. `Find` i To locate a record in a table-type recordset, call the [Seek](#seek) member function. > [!TIP] -> The smaller the set of records you have, the more effective `Find` will be. In general, and especially with ODBC data, it is better to create a new query that retrieves just the records you want. +> The smaller the set of records you have, the more effective `Find` is. In general, and especially with ODBC data, it's better to create a new query that retrieves just the records you want. For related information, see the topic "FindFirst, FindLast, FindNext, FindPrevious Methods" in DAO Help. @@ -553,7 +556,7 @@ The `FindFirst` member function begins its search from the beginning of the reco If you want to include all the records in your search (not just those that meet a specific condition) use one of the Move operations to move from record to record. To locate a record in a table-type recordset, call the `Seek` member function. -If a record matching the criteria is not located, the current record pointer is undetermined, and `FindFirst` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. +If a record matching the criteria isn't located, the current record pointer is undetermined, and `FindFirst` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. > [!CAUTION] > If you edit the current record, be sure to save the changes by calling the `Update` member function before you move to another record. If you move to another record without updating, your changes are lost without warning. @@ -568,17 +571,17 @@ The `Find` member functions search from the location and in the direction specif |`FindPrevious`|Current record|Beginning of recordset| > [!NOTE] -> When you call `FindLast`, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this has not already been done. The first search may take longer than subsequent searches. +> When you call `FindLast`, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this hasn't already been done. The first search may take longer than subsequent searches. -Using one of the Find operations is not the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. +Using one of the Find operations isn't the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. Keep the following in mind when using the Find operations: -- If `Find` returns nonzero, the current record is not defined. In this case, you must position the current record pointer back to a valid record. +- If `Find` returns nonzero, the current record isn't defined. In this case, you must position the current record pointer back to a valid record. -- You cannot use a Find operation with a forward-only scrolling snapshot-type recordset. +- You can't use a Find operation with a forward-only scrolling snapshot-type recordset. -- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you are not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. +- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. - When working with ODBC databases and large dynasets, you may discover that using the Find operations is slow, especially when working with large recordsets. You can improve performance by using SQL queries with customized **ORDERBY** or **WHERE** clauses, parameter queries, or `CDaoQuerydef` objects that retrieve specific indexed records. @@ -607,20 +610,20 @@ The `FindLast` member function begins its search at the end of the recordset and If you want to include all the records in your search (not just those that meet a specific condition) use one of the Move operations to move from record to record. To locate a record in a table-type recordset, call the `Seek` member function. -If a record matching the criteria is not located, the current record pointer is undetermined, and `FindLast` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence after the first occurrence, and so on. +If a record matching the criteria isn't located, the current record pointer is undetermined, and `FindLast` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence after the first occurrence, and so on. > [!CAUTION] > If you edit the current record, be sure you save the changes by calling the `Update` member function before you move to another record. If you move to another record without updating, your changes are lost without warning. -Using one of the Find operations is not the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. +Using one of the Find operations isn't the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. Keep the following in mind when using the Find operations: -- If `Find` returns nonzero, the current record is not defined. In this case, you must position the current record pointer back to a valid record. +- If `Find` returns nonzero, the current record isn't defined. In this case, you must position the current record pointer back to a valid record. -- You cannot use a Find operation with a forward-only scrolling snapshot-type recordset. +- You can't use a Find operation with a forward-only scrolling snapshot-type recordset. -- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you are not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. +- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. - When working with ODBC databases and large dynasets, you may discover that using the Find operations is slow, especially when working with large recordsets. You can improve performance by using SQL queries with customized **ORDERBY** or **WHERE** clauses, parameter queries, or `CDaoQuerydef` objects that retrieve specific indexed records. @@ -649,20 +652,20 @@ The `FindNext` member function begins its search at the current record and searc If you want to include all the records in your search (not just those that meet a specific condition) use one of the Move operations to move from record to record. To locate a record in a table-type recordset, call the `Seek` member function. -If a record matching the criteria is not located, the current record pointer is undetermined, and `FindNext` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. +If a record matching the criteria isn't located, the current record pointer is undetermined, and `FindNext` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. > [!CAUTION] > If you edit the current record, be sure you save the changes by calling the `Update` member function before you move to another record. If you move to another record without updating, your changes are lost without warning. -Using one of the Find operations is not the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. +Using one of the Find operations isn't the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. Keep the following in mind when using the Find operations: -- If `Find` returns nonzero, the current record is not defined. In this case, you must position the current record pointer back to a valid record. +- If `Find` returns nonzero, the current record isn't defined. In this case, you must position the current record pointer back to a valid record. -- You cannot use a Find operation with a forward-only scrolling snapshot-type recordset. +- You can't use a Find operation with a forward-only scrolling snapshot-type recordset. -- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you are not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. +- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. - When working with ODBC databases and large dynasets, you may discover that using the Find operations is slow, especially when working with large recordsets. You can improve performance by using SQL queries with customized **ORDERBY** or **WHERE** clauses, parameter queries, or `CDaoQuerydef` objects that retrieve specific indexed records. @@ -691,20 +694,20 @@ The `FindPrev` member function begins its search at the current record and searc If you want to include all the records in your search (not just those that meet a specific condition) use one of the Move operations to move from record to record. To locate a record in a table-type recordset, call the `Seek` member function. -If a record matching the criteria is not located, the current record pointer is undetermined, and `FindPrev` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. +If a record matching the criteria isn't located, the current record pointer is undetermined, and `FindPrev` returns zero. If the recordset contains more than one record that satisfies the criteria, `FindFirst` locates the first occurrence, `FindNext` locates the next occurrence, and so on. > [!CAUTION] > If you edit the current record, be sure you save the changes by calling the `Update` member function before you move to another record. If you move to another record without updating, your changes are lost without warning. -Using one of the Find operations is not the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. +Using one of the Find operations isn't the same as calling `MoveFirst` or `MoveNext`, however, which simply makes the first or next record current without specifying a condition. You can follow a Find operation with a Move operation. Keep the following in mind when using the Find operations: -- If `Find` returns nonzero, the current record is not defined. In this case, you must position the current record pointer back to a valid record. +- If `Find` returns nonzero, the current record isn't defined. In this case, you must position the current record pointer back to a valid record. -- You cannot use a Find operation with a forward-only scrolling snapshot-type recordset. +- You can't use a Find operation with a forward-only scrolling snapshot-type recordset. -- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you are not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. +- You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, matching records may not be found. - When working with ODBC databases and large dynasets, you may discover that using the Find operations is slow, especially when working with large recordsets. You can improve performance by using SQL queries with customized **ORDERBY** or **WHERE** clauses, parameter queries, or `CDaoQuerydef` objects that retrieve specific indexed records. @@ -726,10 +729,10 @@ An integer from 0 to the number of records in the recordset. Corresponds to the The AbsolutePosition property value of the underlying DAO object is zero-based; a setting of 0 refers to the first record in the recordset. You can determine the number of populated records in the recordset by calling [GetRecordCount](#getrecordcount). Calling `GetRecordCount` may take some time because it must access all records to determine the count. -If there is no current record, as when there are no records in the recordset, - 1 is returned. If the current record is deleted, the AbsolutePosition property value is not defined, and MFC throws an exception if it is referenced. For dynaset-type recordsets, new records are added to the end of the sequence. +If there's no current record, as when there are no records in the recordset, - 1 is returned. If the current record is deleted, the AbsolutePosition property value isn't defined, and MFC throws an exception if it's referenced. For dynaset-type recordsets, new records are added to the end of the sequence. > [!NOTE] -> This property is not intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of recordset objects. In particular, the position of a given record changes when record(s) preceding it are deleted. There is also no assurance that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset is not guaranteed unless it is created with a SQL statement using an **ORDERBY** clause. +> This property isn't intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of recordset objects. In particular, the position of a given record changes when record(s) preceding it are deleted. There's also no assurance that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset isn't guaranteed unless it's created with a SQL statement using an **ORDERBY** clause. > [!NOTE] > This member function is valid only for dynaset-type and snapshot-type recordsets. @@ -752,7 +755,7 @@ Returns a value representing the bookmark on the current record. When a recordset object is created or opened, each of its records already has a unique bookmark if it supports them. Call `CanBookmark` to determine whether a recordset supports bookmarks. -You can save the bookmark for the current record by assigning the value of the bookmark to a `COleVariant` object. To quickly return to that record at any time after moving to a different record, call `SetBookmark` with a parameter corresponding to the value of that `COleVariant` object. +You can save the bookmark for the current record by assigning the value of the bookmark to a `COleVariant` object. To quickly return to that record after moving to a different record, call `SetBookmark` with a parameter corresponding to the value of that `COleVariant` object. > [!NOTE] > Calling [Requery](#requery) changes DAO bookmarks. @@ -773,7 +776,7 @@ A value that specifies the number of records in a dynaset-type recordset contain ### Remarks -Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type recordset objects. A cache is a space in local memory that holds the data most recently retrieved from the server in the event that the data will be requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time. Data that does not come from an ODBC data source is not saved in the cache. +Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type recordset objects. A cache is a space in local memory that holds the data most recently retrieved from the server in case the data is requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time. Data that doesn't come from an ODBC data source isn't saved in the cache. Any ODBC data source, such as an attached table, can have a local cache. @@ -796,7 +799,7 @@ A `COleVariant` that specifies the bookmark of the first record in the recordset The Microsoft Jet database engine requests records within the cache range from the cache, and it requests records outside the cache range from the server. > [!NOTE] -> Records retrieved from the cache do not reflect changes made concurrently to the source data by other users. +> Records retrieved from the cache don't reflect changes made concurrently to the source data by other users. For related information, see the topic "CacheSize, CacheStart Properties" in DAO Help. @@ -1015,7 +1018,7 @@ The two versions of `GetFieldValue` that return a value return a [COleVariant](. You can look up a field by name or by ordinal position. > [!NOTE] -> It is more efficient to call one of the versions of this member function that takes a `COleVariant` object reference as a parameter, rather than calling a version that returns a `COleVariant` object. The latter versions of this function are kept for backward compatibility. +> It's more efficient to call one of the versions of this member function that takes a `COleVariant` object reference as a parameter, rather than calling a version that returns a `COleVariant` object. The latter versions of this function are kept for backward compatibility. Use `GetFieldValue` and [SetFieldValue](#setfieldvalue) to dynamically bind fields at run time rather than statically binding columns using the [DoFieldExchange](#dofieldexchange) mechanism. @@ -1037,7 +1040,7 @@ The number of indexes in the table-type recordset. ### Remarks -`GetIndexCount` is useful for looping through all indexes in the recordset. For that purpose, use `GetIndexCount` in conjunction with [GetIndexInfo](#getindexinfo). If you call this member function on dynaset-type or snapshot-type recordsets, MFC throws an exception. +`GetIndexCount` is useful for looping through all indexes in the recordset. For that purpose, use `GetIndexCount` with [`GetIndexInfo`](#getindexinfo). If you call this member function on dynaset-type or snapshot-type recordsets, MFC throws an exception. For related information, see the topic "Attributes Property" in DAO Help. @@ -1099,9 +1102,9 @@ A `COleVariant` containing a bookmark that indicates the most recently added or ### Remarks -When a recordset object is created or opened, each of its records already has a unique bookmark if it supports them. Call [GetBookmark](#getbookmark) to determine if the recordset supports bookmarks. If the recordset does not support bookmarks, a `CDaoException` is thrown. +When a recordset object is created or opened, each of its records already has a unique bookmark if it supports them. Call [GetBookmark](#getbookmark) to determine if the recordset supports bookmarks. If the recordset doesn't support bookmarks, a `CDaoException` is thrown. -When you add a record, it appears at the end of the recordset, and is not the current record. To make the new record current, call `GetLastModifiedBookmark` and then call `SetBookmark` to return to the newly added record. +When you add a record, it appears at the end of the recordset, and isn't the current record. To make the new record current, call `GetLastModifiedBookmark` and then call `SetBookmark` to return to the newly added record. For related information, see the topic "LastModified Property" in DAO Help. @@ -1119,7 +1122,7 @@ Nonzero if the type of locking is pessimistic, otherwise 0 for optimistic record ### Remarks -When pessimistic locking is in effect, the data page containing the record you are editing is locked as soon as you call the [Edit](#edit) member function. The page is unlocked when you call the [Update](#update) or [Close](#close) member function or any of the Move or Find operations. +When pessimistic locking is in effect, the data page containing the record you're editing is locked as soon as you call the [Edit](#edit) member function. The page is unlocked when you call the [Update](#update) or [Close](#close) member function or any of the Move or Find operations. When optimistic locking is in effect, the data page containing the record is locked only while the record is being updated with the `Update` member function. @@ -1188,7 +1191,7 @@ A number between 0 and 100 that indicates the approximate location of the curren You can move to the last record by calling [MoveLast](#movelast) to complete the population of all recordsets, but this may take a significant amount of time. -You can call `GetPercentPosition` on all three types of recordset objects, including tables without indexes. However, you cannot call `GetPercentPosition` on forward-only scrolling snapshots, or on a recordset opened from a pass-through query against an external database. If there is no current record, or he current record has been deleted, a `CDaoException` is thrown. +You can call `GetPercentPosition` on all three types of recordset objects, including tables without indexes. However, you can't call `GetPercentPosition` on forward-only scrolling snapshots, or on a recordset opened from a pass-through query against an external database. If there's no current record, or the current record has been deleted, a `CDaoException` is thrown. For related information, see the topic "PercentPosition Property" in DAO Help. @@ -1206,13 +1209,13 @@ Returns the number of records accessed in a recordset object. ### Remarks -`GetRecordCount` does not indicate how many records are contained in a dynaset-type or snapshot-type recordset until all records have been accessed. This member function call may take a significant amount of time to complete. +`GetRecordCount` doesn't indicate how many records are contained in a dynaset-type or snapshot-type recordset until all records have been accessed. This member function call may take a significant amount of time to complete. Once the last record has been accessed, the return value indicates the total number of undeleted records in the recordset. To force the last record to be accessed, call the `MoveLast` or `FindLast` member function for the recordset. You can also use a SQL Count to determine the approximate number of records your query will return. -As your application deletes records in a dynaset-type recordset, the return value of `GetRecordCount` decreases. However, records deleted by other users are not reflected by `GetRecordCount` until the current record is positioned to a deleted record. If you execute a transaction that affects the record count and subsequently roll back the transaction, `GetRecordCount` will not reflect the actual number of remaining records. +As your application deletes records in a dynaset-type recordset, the return value of `GetRecordCount` decreases. However, records deleted by other users aren't reflected by `GetRecordCount` until the current record is positioned to a deleted record. If you execute a transaction that affects the record count and subsequently roll back the transaction, `GetRecordCount` won't reflect the actual number of remaining records. -The value of `GetRecordCount` from a snapshot-type recordset is not affected by changes in the underlying tables. +The value of `GetRecordCount` from a snapshot-type recordset isn't affected by changes in the underlying tables. The value of `GetRecordCount` from a table-type recordset reflects the approximate number of records in the table and is affected immediately as table records are added and deleted. @@ -1275,11 +1278,11 @@ CString GetValidationRule(); ### Return Value -A `CString` object containing a value that validates the data in a record as it is changed or added to a table. +A `CString` object containing a value that validates the data in a record as it's changed or added to a table. ### Remarks -This rule is text-based, and is applied each time the underlying table is changed. If the data is not legal, MFC throws an exception. The returned error message is the text of the ValidationText property of the underlying field object, if specified, or the text of the expression specified by the ValidationRule property of the underlying field object. You can call [GetValidationText](#getvalidationtext) to obtain the text of the error message. +This rule is text-based, and is applied each time the underlying table is changed. If the data isn't legal, MFC throws an exception. The returned error message is the text of the ValidationText property of the underlying field object, if specified, or the text of the expression specified by the ValidationRule property of the underlying field object. You can call [GetValidationText](#getvalidationtext) to obtain the text of the error message. For example, a field in a record that requires the day of the month might have a validation rule such as "DAY BETWEEN 1 AND 31." @@ -1295,7 +1298,7 @@ CString GetValidationText(); ### Return Value -A `CString` object containing the text of the message that is displayed if the value of a field does not satisfy the validation rule of the underlying field object. +A `CString` object containing the text of the message that is displayed if the value of a field doesn't satisfy the validation rule of the underlying field object. ### Remarks @@ -1327,7 +1330,7 @@ Effect of specific methods on `IsBOF` and `IsEOF` settings: - An `AddNew` call followed by an `Update` call that successfully inserts a new record will cause `IsBOF` to return 0, but only if `IsEOF` is already nonzero. The state of `IsEOF` will always remain unchanged. As defined by the Microsoft Jet database engine, the current record pointer of an empty recordset is at the end of a file, so any new record is inserted after the current record. -- Any `Delete` call, even if it removes the only remaining record from a recordset, will not change the value of `IsBOF` or `IsEOF`. +- Any `Delete` call, even if it removes the only remaining record from a recordset, won't change the value of `IsBOF` or `IsEOF`. This table shows which Move operations are allowed with different combinations of `IsBOF`/ `IsEOF`. @@ -1338,9 +1341,9 @@ This table shows which Move operations are allowed with different combinations o |Both nonzero|Exception|Exception|Exception|Exception| |Both 0|Allowed|Allowed|Allowed|Allowed| -Allowing a Move operation does not mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and will not generate an exception. The value of the `IsBOF` and `IsEOF` member functions may change as a result of the attempted move. +Allowing a Move operation doesn't mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and won't generate an exception. The value of the `IsBOF` and `IsEOF` member functions may change as a result of the attempted move. -The effect of Move operations that do not locate a record on the value of `IsBOF` and `IsEOF` settings is shown in the following table. +The effect of Move operations that don't locate a record on the value of `IsBOF` and `IsEOF` settings is shown in the following table. |Operations|IsBOF|IsEOF| |------|-----------|-----------| @@ -1368,9 +1371,9 @@ Nonzero if the recordset is positioned on a deleted record; otherwise 0. If you scroll to a record and `IsDeleted` returns TRUE (nonzero), then you must scroll to another record before you can perform any other recordset operations. > [!NOTE] -> You don't need to check the deleted status for records in a snapshot or table-type recordset. Because records cannot be deleted from a snapshot, there is no need to call `IsDeleted`. For table-type recordsets, deleted records are actually removed from the recordset. Once a record has been deleted, either by you, another user, or in another recordset, you cannot scroll back to that record. Therefore, there is no need to call `IsDeleted`. +> You don't need to check the deleted status for records in a snapshot or table-type recordset. Because records can't be deleted from a snapshot, there's no need to call `IsDeleted`. For table-type recordsets, deleted records are actually removed from the recordset. Once a record has been deleted, either by you, another user, or in another recordset, you can't scroll back to that record. Therefore, there's no need to call `IsDeleted`. -When you delete a record from a dynaset, it is removed from the recordset and you cannot scroll back to that record. However, if a record in a dynaset is deleted either by another user or in another recordset based on the same table, `IsDeleted` will return TRUE when you later scroll to that record. +When you delete a record from a dynaset, it's removed from the recordset and you can't scroll back to that record. However, if a record in a dynaset is deleted either by another user or in another recordset based on the same table, `IsDeleted` returns TRUE when you later scroll to that record. For related information, see the topics "Delete Method", "LastModified Property", and "EditMode Property" in DAO Help. @@ -1400,7 +1403,7 @@ Effect of specific methods on `IsBOF` and `IsEOF` settings: - An `AddNew` call followed by an `Update` call that successfully inserts a new record will cause `IsBOF` to return 0, but only if `IsEOF` is already nonzero. The state of `IsEOF` will always remain unchanged. As defined by the Microsoft Jet database engine, the current record pointer of an empty recordset is at the end of a file, so any new record is inserted after the current record. -- Any `Delete` call, even if it removes the only remaining record from a recordset, will not change the value of `IsBOF` or `IsEOF`. +- Any `Delete` call, even if it removes the only remaining record from a recordset, won't change the value of `IsBOF` or `IsEOF`. This table shows which Move operations are allowed with different combinations of `IsBOF`/ `IsEOF`. @@ -1411,9 +1414,9 @@ This table shows which Move operations are allowed with different combinations o |Both nonzero|Exception|Exception|Exception|Exception| |Both 0|Allowed|Allowed|Allowed|Allowed| -Allowing a Move operation does not mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and will not generate an exception. The value of the `IsBOF` and `IsEOF` member functions may change as a result of the attempted Move. +Allowing a Move operation doesn't mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and won't generate an exception. The value of the `IsBOF` and `IsEOF` member functions may change as a result of the attempted Move. -The effect of Move operations that do not locate a record on the value of `IsBOF` and `IsEOF` settings is shown in the following table. +The effect of Move operations that don't locate a record on the value of `IsBOF` and `IsEOF` settings is shown in the following table. |Operations|IsBOF|IsEOF| |------|-----------|-----------| @@ -1443,7 +1446,7 @@ Nonzero if the specified field data member is flagged as dirty; otherwise 0. ### Remarks -The data in all dirty field data members will be transferred to the record on the data source when the current record is updated by a call to the `Update` member function of `CDaoRecordset` (following a call to `Edit` or `AddNew`). With this knowledge, you can take further steps, such as unflagging the field data member to mark the column so it will not be written to the data source. +The data in all dirty field data members are transferred to the record on the data source when the current record is updated by a call to the `Update` member function of `CDaoRecordset` (following a call to `Edit` or `AddNew`). With this knowledge, you can take further steps, such as unflagging the field data member to mark the column so it won't be written to the data source. `IsFieldDirty` is implemented through `DoFieldExchange`. @@ -1466,7 +1469,7 @@ Nonzero if the specified field data member is flagged as Null; otherwise 0. ### Remarks -(In database terminology, Null means "having no value" and is not the same as NULL in C++.) If a field data member is flagged as Null, it is interpreted as a column of the current record for which there is no value. +(In database terminology, Null means "having no value" and isn't the same as NULL in C++.) If a field data member is flagged as Null, it's interpreted as a column of the current record for which there's no value. > [!NOTE] > In certain situations, using `IsFieldNull` can be inefficient, as the following code example illustrates: @@ -1474,11 +1477,11 @@ Nonzero if the specified field data member is flagged as Null; otherwise 0. [!code-cpp[NVC_MFCDatabase#5](../../mfc/codesnippet/cpp/cdaorecordset-class_5.cpp)] > [!NOTE] -> If you are using dynamic record binding, without deriving from `CDaoRecordset`, be sure to use VT_NULL as shown in the example. +> If you're using dynamic record binding, without deriving from `CDaoRecordset`, be sure to use VT_NULL as shown in the example. ## CDaoRecordset::IsFieldNullable -Call this member function to determine whether the specified field data member is "nullable" (can be set to a Null value; C++ NULL is not the same as Null, which, in database terminology, means "having no value"). +Call this member function to determine whether the specified field data member is "nullable" (can be set to a Null value; C++ NULL isn't the same as Null, which, in database terminology, means "having no value"). ```cpp BOOL IsFieldNullable(void* pv); @@ -1495,7 +1498,7 @@ Nonzero if the specified field data member can be made Null; otherwise 0. ### Remarks -A field that cannot be Null must have a value. If you attempt to set such a field to Null when adding or updating a record, the data source rejects the addition or update, and `Update` will throw an exception. The exception occurs when you call `Update`, not when you call `SetFieldNull`. +A field that can't be Null must have a value. If you attempt to set such a field to Null when adding or updating a record, the data source rejects the addition or update, and `Update` will throw an exception. The exception occurs when you call `Update`, not when you call `SetFieldNull`. ## CDaoRecordset::IsOpen @@ -1507,7 +1510,7 @@ BOOL IsOpen() const; ### Return Value -Nonzero if the recordset object's `Open` or `Requery` member function has previously been called and the recordset has not been closed; otherwise 0. +Nonzero if the recordset object's `Open` or `Requery` member function has previously been called and the recordset hasn't been closed; otherwise 0. ### Remarks @@ -1534,7 +1537,7 @@ The framework uses this number to manage interaction between the field data memb > [!NOTE] > This number must correspond to the number of output columns registered in `DoFieldExchange` after a call to `SetFieldType` with the parameter `CDaoFieldExchange::outputColumn`. -You can bind columns dynamically by way of `CDaoRecordset::GetFieldValue` and `CDaoRecordset::SetFieldValue`. If you do so, you do not need to increment the count in `m_nFields` to reflect the number of DFX function calls in your `DoFieldExchange` member function. +You can bind columns dynamically by way of `CDaoRecordset::GetFieldValue` and `CDaoRecordset::SetFieldValue`. If you do so, you don't need to increment the count in `m_nFields` to reflect the number of DFX function calls in your `DoFieldExchange` member function. ## CDaoRecordset::m_nParams @@ -1569,7 +1572,7 @@ Contains a pointer to the `CDaoDatabase` object through which the recordset is c This variable is set in two ways. Typically, you pass a pointer to an already open `CDaoDatabase` object when you construct the recordset object. If you pass NULL instead, `CDaoRecordset` creates a `CDaoDatabase` object for you and opens it. In either case, `CDaoRecordset` stores the pointer in this variable. -Normally you will not directly need to use the pointer stored in `m_pDatabase`. If you write your own extensions to `CDaoRecordset`, however, you might need to use the pointer. For example, you might need the pointer if you throw your own `CDaoException`(s). +Normally you'll not directly need to use the pointer stored in `m_pDatabase`. If you write your own extensions to `CDaoRecordset`, however, you might need to use the pointer. For example, you might need the pointer if you throw your own `CDaoException`(s). For related information, see the topic "Database Object" in DAO Help. @@ -1579,9 +1582,9 @@ Contains a string that is used to construct the **WHERE** clause of a SQL statem ### Remarks -It does not include the reserved word **WHERE** to filter the recordset. The use of this data member is not applicable to table-type recordsets. The use of `m_strFilter` has no effect when opening a recordset using a `CDaoQueryDef` pointer. +It doesn't include the reserved word **WHERE** to filter the recordset. The use of this data member isn't applicable to table-type recordsets. The use of `m_strFilter` has no effect when opening a recordset using a `CDaoQueryDef` pointer. -Use the U.S. date format (month-day-year) when you filter fields containing dates, even if you are not using the U.S. version of the Microsoft Jet database engine; otherwise, the data may not be filtered as you expect. +Use the U.S. date format (month-day-year) when you filter fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, the data may not be filtered as you expect. For related information, see the topic "Filter Property" in DAO Help. @@ -1593,7 +1596,7 @@ Contains a string containing the **ORDERBY** clause of a SQL statement without t You can sort on dynaset- and snapshot-type recordset objects. -You cannot sort table-type recordset objects. To determine the sort order of a table-type recordset, call [SetCurrentIndex](#setcurrentindex). +You can't sort table-type recordset objects. To determine the sort order of a table-type recordset, call [SetCurrentIndex](#setcurrentindex). The use of *m_strSort* has no effect when opening a recordset using a `CDaoQueryDef` pointer. @@ -1620,12 +1623,12 @@ You can move forward or backward. `Move( 1 )` is equivalent to `MoveNext`, and ` > Calling any of the `Move` functions throws an exception if the recordset has no records. In general, call both `IsBOF` and `IsEOF` before a Move operation to determine whether the recordset has any records. After you call `Open` or `Requery`, call either `IsBOF` or `IsEOF`. > [!NOTE] -> If you have scrolled past the beginning or end of the recordset ( `IsBOF` or `IsEOF` returns nonzero), a call to `Move` throws a `CDaoException`. +> If you have scrolled past the beginning or end of the recordset (`IsBOF` or `IsEOF` returns nonzero), a call to `Move` throws a `CDaoException`. > [!NOTE] > If you call any of the `Move` functions while the current record is being updated or added, the updates are lost without warning. -When you call `Move` on a forward-only scrolling snapshot, the *lRows* parameter must be a positive integer and bookmarks are not allowed, so you can move forward only. +When you call `Move` on a forward-only scrolling snapshot, the *lRows* parameter must be a positive integer and bookmarks aren't allowed, so you can move forward only. To make the first, last, next, or previous record in a recordset the current record, call the `MoveFirst`, `MoveLast`, `MoveNext`, or `MovePrev` member function. @@ -1641,7 +1644,7 @@ void MoveFirst(); ### Remarks -You do not have to call `MoveFirst` immediately after you open the recordset. At that time, the first record (if any) is automatically the current record. +You don't have to call `MoveFirst` immediately after you open the recordset. At that time, the first record (if any) is automatically the current record. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. In general, call both `IsBOF` and `IsEOF` before a Move operation to determine whether the recordset has any records. After you call `Open` or `Requery`, call either `IsBOF` or `IsEOF`. @@ -1651,11 +1654,11 @@ You do not have to call `MoveFirst` immediately after you open the recordset. At Use the `Move` functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call `Seek`. -If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined. +If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you don't set the current index, the order of returned records is undefined. If you call `MoveLast` on a recordset object based on a SQL query or querydef, the query is forced to completion and the recordset object is fully populated. -You cannot call the `MoveFirst` or `MovePrev` member function with a forward-only scrolling snapshot. +You can't call the `MoveFirst` or `MovePrev` member function with a forward-only scrolling snapshot. To move the position of the current record in a recordset object a specific number of records forward or backward, call `Move`. @@ -1679,7 +1682,7 @@ void MoveLast(); Use the `Move` functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call `Seek`. -If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined. +If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you don't set the current index, the order of returned records is undefined. If you call `MoveLast` on a recordset object based on a SQL query or querydef, the query is forced to completion and the recordset object is fully populated. @@ -1697,7 +1700,7 @@ void MoveNext(); ### Remarks -It is recommended that you call `IsBOF` before you attempt to move to the previous record. A call to `MovePrev` will throw a `CDaoException` if `IsBOF` returns nonzero, indicating either that you have already scrolled before the first record or that no records were selected by the recordset. +It's recommended that you call `IsBOF` before you attempt to move to the previous record. A call to `MovePrev` throws a `CDaoException` if `IsBOF` returns nonzero, indicating either that you have already scrolled before the first record or that no records were selected by the recordset. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. In general, call both `IsBOF` and `IsEOF` before a Move operation to determine whether the recordset has any records. After you call `Open` or `Requery`, call either `IsBOF` or `IsEOF`. @@ -1707,7 +1710,7 @@ It is recommended that you call `IsBOF` before you attempt to move to the previo Use the `Move` functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call `Seek`. -If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined. +If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you don't set the current index, the order of returned records is undefined. To move the position of the current record in a recordset object a specific number of records forward or backward, call `Move`. @@ -1723,7 +1726,7 @@ void MovePrev(); ### Remarks -It is recommended that you call `IsBOF` before you attempt to move to the previous record. A call to `MovePrev` will throw a `CDaoException` if `IsBOF` returns nonzero, indicating either that you have already scrolled before the first record or that no records were selected by the recordset. +It's recommended that you call `IsBOF` before you attempt to move to the previous record. A call to `MovePrev` throws a `CDaoException` if `IsBOF` returns nonzero, indicating either that you have already scrolled before the first record or that no records were selected by the recordset. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. In general, call both `IsBOF` and `IsEOF` before a Move operation to determine whether the recordset has any records. After you call `Open` or `Requery`, call either `IsBOF` or `IsEOF`. @@ -1733,9 +1736,9 @@ It is recommended that you call `IsBOF` before you attempt to move to the previo Use the `Move` functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call `Seek`. -If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined. +If the recordset refers to a table-type recordset, movement follows the table's current index. You can set the current index by using the Index property of the underlying DAO object. If you don't set the current index, the order of returned records is undefined. -You cannot call the `MoveFirst` or `MovePrev` member function with a forward-only scrolling snapshot. +You can't call the `MoveFirst` or `MovePrev` member function with a forward-only scrolling snapshot. To move the position of the current record in a recordset object a specific number of records forward or backward, call `Move`. @@ -1791,11 +1794,11 @@ One or more of the options listed below. The default value is 0. Possible values - `dbForwardOnly` The recordset is a forward-only scrolling snapshot. -- `dbSeeChanges` Generate an exception if another user is changing data you are editing. +- `dbSeeChanges` Generate an exception if another user is changing data you're editing. -- `dbDenyWrite` Other users cannot modify or add records. +- `dbDenyWrite` Other users can't modify or add records. -- `dbDenyRead` Other users cannot view records (table-type recordset only). +- `dbDenyRead` Other users can't view records (table-type recordset only). - `dbReadOnly` You can only view records; other users can modify them. @@ -1807,10 +1810,10 @@ One or more of the options listed below. The default value is 0. Possible values > The constants `dbConsistent` and `dbInconsistent` are mutually exclusive. You can use one or the other, but not both in a given instance of `Open`. *pTableDef*
-A pointer to a [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md) object. This version is valid only for table-type recordsets. When using this option, the `CDaoDatabase` pointer used to construct the `CDaoRecordset` is not used; rather, the database in which the tabledef resides is used. +A pointer to a [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md) object. This version is valid only for table-type recordsets. When using this option, the `CDaoDatabase` pointer used to construct the `CDaoRecordset` isn't used; rather, the database in which the tabledef resides is used. *pQueryDef*
-A pointer to a [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) object. This version is valid only for dynaset-type and snapshot-type recordsets. When using this option, the `CDaoDatabase` pointer used to construct the `CDaoRecordset` is not used; rather, the database in which the querydef resides is used. +A pointer to a [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) object. This version is valid only for dynaset-type and snapshot-type recordsets. When using this option, the `CDaoDatabase` pointer used to construct the `CDaoRecordset` isn't used; rather, the database in which the querydef resides is used. ### Remarks @@ -1818,21 +1821,21 @@ Before calling `Open`, you must construct the recordset object. There are severa - When you construct the recordset object, pass a pointer to a `CDaoDatabase` object that is already open. -- When you construct the recordset object, pass a pointer to a `CDaoDatabase` object that is not open. The recordset opens a `CDaoDatabase` object, but will not close it when the recordset object closes. +- When you construct the recordset object, pass a pointer to a `CDaoDatabase` object that isn't open. The recordset opens a `CDaoDatabase` object, but will not close it when the recordset object closes. - When you construct the recordset object, pass a NULL pointer. The recordset object calls `GetDefaultDBName` to get the name of the Microsoft Access .MDB file to open. The recordset then opens a `CDaoDatabase` object and keeps it open as long as the recordset is open. When you call `Close` on the recordset, the `CDaoDatabase` object is also closed. > [!NOTE] > When the recordset opens the `CDaoDatabase` object, it opens the data source with nonexclusive access. -For the version of `Open` that uses the *lpszSQL* parameter, once the recordset is open you can retrieve records in one of several ways. The first option is to have DFX functions in your `DoFieldExchange`. The second option is to use dynamic binding by calling the `GetFieldValue` member function. These options can be implemented separately or in combination. If they are combined, you will have to pass in the SQL statement yourself on the call to `Open`. +For the version of `Open` that uses the *lpszSQL* parameter, once the recordset is open you can retrieve records in one of several ways. The first option is to have DFX functions in your `DoFieldExchange`. The second option is to use dynamic binding by calling the `GetFieldValue` member function. These options can be implemented separately or in combination. If they are combined, you'll have to pass in the SQL statement yourself on the call to `Open`. -When you use the second version of `Open` where you pass in a `CDaoTableDef` object, the resulting columns will be available for you to bind via `DoFieldExchange` and the DFX mechanism, and/or bind dynamically via `GetFieldValue`. +When you use the second version of `Open` where you pass in a `CDaoTableDef` object, the resulting columns are available for you to bind via `DoFieldExchange` and the DFX mechanism, and/or bind dynamically via `GetFieldValue`. > [!NOTE] > You can only call `Open` using a `CDaoTableDef` object for table-type recordsets. -When you use the third version of `Open` where you pass in a `CDaoQueryDef` object, that query will be executed, and the resulting columns will be available for you to bind via `DoFieldExchange` and the DFX mechanism, and/or bind dynamically via `GetFieldValue`. +When you use the third version of `Open` where you pass in a `CDaoQueryDef` object, that query is executed, and the resulting columns are available for you to bind via `DoFieldExchange` and the DFX mechanism, and/or bind dynamically via `GetFieldValue`. > [!NOTE] > You can only call `Open` using a `CDaoQueryDef` object for dynaset-type and snapshot-type recordsets. @@ -1853,9 +1856,9 @@ The field data members of your recordset class are bound to the columns of the d If you want to set options for the recordset, such as a filter or sort, set `m_strSort` or `m_strFilter` after you construct the recordset object but before you call `Open`. If you want to refresh the records in the recordset after the recordset is already open, call `Requery`. -If you call `Open` on a dynaset-type or snapshot-type recordset, or if the data source refers to a SQL statement or a tabledef that represents an attached table, you cannot use `dbOpenTable` for the type argument; if you do, MFC throws an exception. To determine whether a tabledef object represents an attached table, create a [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md) object and call its [GetConnect](../../mfc/reference/cdaotabledef-class.md#getconnect) member function. +If you call `Open` on a dynaset-type or snapshot-type recordset, or if the data source refers to a SQL statement or a tabledef that represents an attached table, you can't use `dbOpenTable` for the type argument; if you do, MFC throws an exception. To determine whether a tabledef object represents an attached table, create a [CDaoTableDef](../../mfc/reference/cdaotabledef-class.md) object and call its [GetConnect](../../mfc/reference/cdaotabledef-class.md#getconnect) member function. -Use the `dbSeeChanges` flag if you wish to trap changes made by another user or another program on your machine when you are editing or deleting the same record. For example, if two users start editing the same record, the first user to call the `Update` member function succeeds. When `Update` is called by the second user, a `CDaoException` is thrown. Similarly, if the second user tries to call `Delete` to delete the record, and it has already been changed by the first user, a `CDaoException` occurs. +Use the `dbSeeChanges` flag if you wish to trap changes made by another user or another program on your machine when you're editing or deleting the same record. For example, if two users start editing the same record, the first user to call the `Update` member function succeeds. When `Update` is called by the second user, a `CDaoException` is thrown. Similarly, if the second user tries to call `Delete` to delete the record, and it has already been changed by the first user, a `CDaoException` occurs. Typically, if the user gets this `CDaoException` while updating, your code should refresh the contents of the fields and retrieve the newly modified values. If the exception occurs in the process of deleting, your code could display the new record data to the user and a message indicating that the data has recently changed. At this point, your code can request a confirmation that the user still wants to delete the record. @@ -1878,15 +1881,15 @@ If any records are returned, the first record becomes the current record. In order for the recordset to reflect the additions and deletions that you or other users are making to the data source, you must rebuild the recordset by calling `Requery`. If the recordset is a dynaset, it automatically reflects updates that you or other users make to its existing records (but not additions). If the recordset is a snapshot, you must call `Requery` to reflect edits by other users as well as additions and deletions. -For either a dynaset or a snapshot, call `Requery` any time you want to rebuild the recordset using parameter values. Set the new filter or sort by setting [m_strFilter](#m_strfilter) and [m_strSort](#m_strsort) before calling `Requery`. Set new parameters by assigning new values to parameter data members before calling `Requery`. +For either a dynaset or a snapshot, call `Requery` when you want to rebuild the recordset using parameter values. Set the new filter or sort by setting [`m_strFilter`](#m_strfilter) and [`m_strSort`](#m_strsort) before calling `Requery`. Set new parameters by assigning new values to parameter data members before calling `Requery`. -If the attempt to rebuild the recordset fails, the recordset is closed. Before you call `Requery`, you can determine whether the recordset can be requeried by calling the [CanRestart](#canrestart) member function. `CanRestart` does not guarantee that `Requery` will succeed. +If the attempt to rebuild the recordset fails, the recordset is closed. Before you call `Requery`, you can determine whether the recordset can be requeried by calling the [`CanRestart`](#canrestart) member function. `CanRestart` doesn't guarantee that `Requery` will succeed. > [!CAUTION] > Call `Requery` only after you have called `Open`. > [!NOTE] -> Calling [Requery](#requery) changes DAO bookmarks. +> Calling [`Requery`](#requery) changes DAO bookmarks. You can't call `Requery` on a dynaset-type or snapshot-type recordset if calling `CanRestart` returns 0, nor can you use it on a table-type recordset. @@ -1932,7 +1935,7 @@ A pointer to an array of variants. The array size corresponds to the number of f An integer corresponding to the size of the array, which is the number of fields in the index. > [!NOTE] -> Do not specify wildcards in the keys. Wildcards will cause `Seek` to return no matching records. +> on't specify wildcards in the keys. Wildcards will cause `Seek` to return no matching records. ### Return Value @@ -1942,19 +1945,19 @@ Nonzero if matching records are found, otherwise 0. Use the second (array) version of `Seek` to handle indexes of four fields or more. -`Seek` enables high-performance index searching on table-type recordsets. You must set the current index by calling `SetCurrentIndex` before calling `Seek`. If the index identifies a nonunique key field or fields, `Seek` locates the first record that satisfies the criteria. If you do not set an index, an exception is thrown. +`Seek` enables high-performance index searching on table-type recordsets. You must set the current index by calling `SetCurrentIndex` before calling `Seek`. If the index identifies a nonunique key field or fields, `Seek` locates the first record that satisfies the criteria. If you don't set an index, an exception is thrown. -Note that if you are not creating a UNICODE recordset, the `COleVariant` objects must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. +If you're not creating a UNICODE recordset, the `COleVariant` objects must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. When you call `Seek`, you pass one or more key values and a comparison operator ("<", "\<=", "=", ">=", or ">"). `Seek` searches through the specified key fields and locates the first record that satisfies the criteria specified by *lpszComparison* and *pKey1*. Once found, `Seek` returns nonzero, and makes that record current. If `Seek` fails to locate a match, `Seek` returns zero, and the current record is undefined. When using DAO directly, you must explicitly check the NoMatch property. If `lpszComparison` is "=", ">=", or ">", `Seek` starts at the beginning of the index. If *lpszComparison* is "<" or "<=", `Seek` starts at the end of the index and searches backward unless there are duplicate index entries at the end. In this case, `Seek` starts at an arbitrary entry among the duplicate index entries at the end of the index. -There does not have to be a current record when you use `Seek`. +There doesn't have to be a current record when you use `Seek`. To locate a record in a dynaset-type or snapshot-type recordset that satisfies a specific condition, use the Find operations. To include all records, not just those that satisfy a specific condition, use the Move operations to move from record to record. -You cannot call `Seek` on an attached table of any type because attached tables must be opened as dynaset-type or snapshot-type recordsets. However, if you call `CDaoDatabase::Open` to directly open an installable ISAM database, you can call `Seek` on tables in that database, although the performance may be slow. +You can't call `Seek` on an attached table of any type because attached tables must be opened as dynaset-type or snapshot-type recordsets. However, if you call `CDaoDatabase::Open` to directly open an installable ISAM database, you can call `Seek` on tables in that database, although the performance may be slow. For related information, see the topic "Seek Method" in DAO Help. @@ -1980,10 +1983,10 @@ Calling `SetAbsolutePosition` enables you to position the current record pointer The AbsolutePosition property value of the underlying DAO object is zero-based; a setting of 0 refers to the first record in the recordset. Setting a value greater than the number of populated records causes MFC to throw an exception. You can determine the number of populated records in the recordset by calling the `GetRecordCount` member function. -If the current record is deleted, the AbsolutePosition property value is not defined, and MFC throws an exception if it is referenced. New records are added to the end of the sequence. +If the current record is deleted, the AbsolutePosition property value isn't defined, and MFC throws an exception if it's referenced. New records are added to the end of the sequence. > [!NOTE] -> This property is not intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of recordset objects that support bookmarks. In particular, the position of a given record changes when record(s) preceding it are deleted. There is also no assurance that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset is not guaranteed unless it is created with a SQL statement using an **ORDERBY** clause. +> This property isn't intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of recordset objects that support bookmarks. In particular, the position of a given record changes when record(s) preceding it are deleted. There's also no assurance that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset isn't guaranteed unless it's created with a SQL statement using an **ORDERBY** clause. For related information, see the topic "AbsolutePosition Property" in DAO Help. @@ -2007,7 +2010,7 @@ When a recordset object is created or opened, each of its records already has a > [!NOTE] > Calling [Requery](#requery) changes DAO bookmarks. -Note that if you are not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. +If you're not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. For related information, see the topics "Bookmark Property" and Bookmarkable Property" in DAO Help. @@ -2022,13 +2025,13 @@ void SetCacheSize(long lSize); ### Parameters *lSize*
-Specifies the number of records. A typical value is 100. A setting of 0 turns off caching. The setting must be between 5 and 1200 records. The cache may use a considerable amount of memory. +Specifies the number of records. A typical value is 100. A setting of 0 turns off caching. The setting must be between 5 and 1,200 records. The cache may use a considerable amount of memory. ### Remarks -A cache is a space in local memory that holds the data most recently retrieved from the server in the event that the data will be requested again while the application is running. Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type recordset objects. When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time. Data that does not come from an ODBC data source is not saved in the cache. +A cache is a space in local memory that holds the data most recently retrieved from the server in case the data is requested again while the application is running. Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type recordset objects. When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time. Data that doesn't come from an ODBC data source isn't saved in the cache. -Any ODBC data source, such as an attached table, can have a local cache. To create the cache, open a recordset object from the remote data source, call the `SetCacheSize` and `SetCacheStart` member functions, and then call the `FillCache` member function or step through the records by using one of the Move operations. The *lSize* parameter of the `SetCacheSize` member function can be based on the number of records your application can work with at one time. For example, if you are using a recordset as the source of the data to be displayed on screen, you could pass the `SetCacheSize` *lSize* parameter as 20 to display 20 records at one time. +Any ODBC data source, such as an attached table, can have a local cache. To create the cache, open a recordset object from the remote data source, call the `SetCacheSize` and `SetCacheStart` member functions, and then call the `FillCache` member function or step through the records by using one of the Move operations. The *lSize* parameter of the `SetCacheSize` member function can be based on the number of records your application can work with at one time. For example, if you're using a recordset as the source of the data to be displayed on screen, you could pass the `SetCacheSize` *lSize* parameter as 20 to display 20 records at one time. For related information, see the topic "CacheSize, CacheStart Properties" in DAO Help. @@ -2051,11 +2054,11 @@ You can use the bookmark value of any record for the *varBookmark* parameter of The Microsoft Jet database engine requests records within the cache range from the cache, and it requests records outside the cache range from the server. -Records retrieved from the cache do not reflect changes made concurrently to the source data by other users. +Records retrieved from the cache don't reflect changes made concurrently to the source data by other users. To force an update of all the cached data, pass the *lSize* parameter of `SetCacheSize` as 0, call `SetCacheSize` again with the size of the cache you originally requested, and then call the `FillCache` member function. -Note that if you are not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. +If you're not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. For related information, see the topic CacheSize, CacheStart Properties" in DAO Help. @@ -2074,7 +2077,7 @@ A pointer containing the name of the index to be set. ### Remarks -Records in base tables are not stored in any particular order. Setting an index changes the order of records returned from the database, but it does not affect the order in which the records are stored. The specified index must already be defined. If you try to use an index object that does not exist, or if the index is not set when you call [Seek](#seek), MFC throws an exception. +Records in base tables aren't stored in any particular order. Setting an index changes the order of records returned from the database, but it doesn't affect the order in which the records are stored. The specified index must already be defined. If you try to use an index object that doesn't exist, or if the index isn't set when you call [Seek](#seek), MFC throws an exception. You can create a new index for the table by calling [CDaoTableDef::CreateIndex](../../mfc/reference/cdaotabledef-class.md#createindex) and appending the new index to the Indexes collection of the underlying tabledef by calling [CDaoTableDef::Append](../../mfc/reference/cdaotabledef-class.md#append), and then reopening the recordset. @@ -2095,18 +2098,18 @@ void SetFieldDirty( ### Parameters *pv*
-Contains the address of a field data member in the recordset or NULL. If NULL, all field data members in the recordset are flagged. (C++ NULL is not the same as Null in database terminology, which means "having no value.") +Contains the address of a field data member in the recordset or NULL. If NULL, all field data members in the recordset are flagged. (C++ NULL isn't the same as Null in database terminology, which means "having no value.") *bDirty*
TRUE if the field data member is to be flagged as "dirty" (changed). Otherwise FALSE if the field data member is to be flagged as "clean" (unchanged). ### Remarks -Marking fields as unchanged ensures the field is not updated. +Marking fields as unchanged ensures the field isn't updated. -The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call `SetFieldDirty` yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of PSEUDONULL. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). +The framework marks changed field data members to ensure they'll be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you'll seldom need to call `SetFieldDirty` yourself, but you might sometimes want to ensure that columns are explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of PSEUDONULL. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). -If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicitly set the field as dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. +If the double-buffering mechanism isn't being used, then changing the value of the field doesn't automatically set the field as dirty. In this case, it's necessary to explicitly set the field as dirty. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. > [!NOTE] > Call this member function only after you have called [Edit](#edit) or [AddNew](#addnew). @@ -2115,13 +2118,13 @@ Using NULL for the first argument of the function will apply the function to all [!code-cpp[NVC_MFCDatabase#6](../../mfc/codesnippet/cpp/cdaorecordset-class_6.cpp)] -will set only `outputColumn` fields to NULL; **param** fields will be unaffected. +will set only `outputColumn` fields to NULL; **param** fields are unaffected. To work on a **param**, you must supply the actual address of the individual **param** you want to work on, such as: [!code-cpp[NVC_MFCDatabase#7](../../mfc/codesnippet/cpp/cdaorecordset-class_7.cpp)] -This means you cannot set all **param** fields to NULL, as you can with `outputColumn` fields. +This means you can't set all **param** fields to NULL, as you can with `outputColumn` fields. `SetFieldDirty` is implemented through `DoFieldExchange`. @@ -2138,7 +2141,7 @@ void SetFieldNull( ### Parameters *pv*
-Contains the address of a field data member in the recordset or NULL. If NULL, all field data members in the recordset are flagged. (C++ NULL is not the same as Null in database terminology, which means "having no value.") +Contains the address of a field data member in the recordset or NULL. If NULL, all field data members in the recordset are flagged. (C++ NULL isn't the same as Null in database terminology, which means "having no value.") *bNull*
Nonzero if the field data member is to be flagged as having no value (Null). Otherwise 0 if the field data member is to be flagged as non-Null. @@ -2147,11 +2150,11 @@ Nonzero if the field data member is to be flagged as having no value (Null). Oth `SetFieldNull` is used for fields bound in the `DoFieldExchange` mechanism. -When you add a new record to a recordset, all field data members are initially set to a Null value and flagged as "dirty" (changed). When you retrieve a record from a data source, its columns either already have values or are Null. If it is not appropriate to make a field Null, a [CDaoException](../../mfc/reference/cdaoexception-class.md) is thrown. +When you add a new record to a recordset, all field data members are initially set to a Null value and flagged as "dirty" (changed). When you retrieve a record from a data source, its columns either already have values or are Null. If it isn't appropriate to make a field Null, a [CDaoException](../../mfc/reference/cdaoexception-class.md) is thrown. -If you are using the double-buffering mechanism, for example, if you specifically wish to designate a field of the current record as not having a value, call `SetFieldNull` with *bNull* set to TRUE to flag it as Null. If a field was previously marked Null and you now want to give it a value, simply set its new value. You do not have to remove the Null flag with `SetFieldNull`. To determine whether the field is allowed to be Null, call [IsFieldNullable](#isfieldnullable). +If you're using the double-buffering mechanism, for example, if you specifically wish to designate a field of the current record as not having a value, call `SetFieldNull` with *bNull* set to TRUE to flag it as Null. If a field was previously marked Null and you now want to give it a value, set its new value. You don't have to remove the Null flag with `SetFieldNull`. To determine whether the field is allowed to be Null, call [IsFieldNullable](#isfieldnullable). -If you are not using the double-buffering mechanism, then changing the value of the field does not automatically set the field as dirty and non-Null. You must specifically set the fields dirty and non-Null. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. +If you're not using the double-buffering mechanism, then changing the value of the field doesn't automatically set the field as dirty and non-Null. You must specifically set the fields dirty and non-Null. The flag contained in [m_bCheckCacheForDirtyFields](#m_bcheckcachefordirtyfields) controls this automatic field checking. The DFX mechanism employs the use of PSEUDONULL. For more information, see [CDaoFieldExchange::m_nOperation](../../mfc/reference/cdaofieldexchange-class.md#m_noperation). @@ -2162,7 +2165,7 @@ Using NULL for the first argument of the function will apply the function only t [!code-cpp[NVC_MFCDatabase#8](../../mfc/codesnippet/cpp/cdaorecordset-class_8.cpp)] -will set only `outputColumn` fields to NULL; **param** fields will be unaffected. +will set only `outputColumn` fields to NULL; **param** fields are unaffected. ## CDaoRecordset::SetFieldValue @@ -2204,7 +2207,7 @@ A pointer to a string containing the value of the field's contents. Use `SetFieldValue` and [GetFieldValue](#getfieldvalue) to dynamically bind fields at run time rather than statically binding columns using the [DoFieldExchange](#dofieldexchange) mechanism. -Note that if you are not creating a UNICODE recordset, you must either use a form of `SetFieldValue` that does not contain a `COleVariant` parameter, or the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. +If you're not creating a UNICODE recordset, you must either use a form of `SetFieldValue` that doesn't contain a `COleVariant` parameter, or the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. For related information, see the topics "Field Object" and "Value Property" in DAO Help. @@ -2227,7 +2230,7 @@ The name of the field in the recordset, for lookup by name. ### Remarks -C++ NULL is not the same as Null, which, in database terminology, means "having no value." +C++ NULL isn't the same as Null, which, in database terminology, means "having no value." For related information, see the topics "Field Object" and "Value Property" in DAO Help. @@ -2246,7 +2249,7 @@ A flag that indicates the type of locking. ### Remarks -When pessimistic locking is in effect, the 2K page containing the record you are editing is locked as soon as you call the `Edit` member function. The page is unlocked when you call the `Update` or `Close` member function or any of the Move or Find operations. +When pessimistic locking is in effect, the 2K page containing the record you're editing is locked as soon as you call the `Edit` member function. The page is unlocked when you call the `Update` or `Close` member function or any of the Move or Find operations. When optimistic locking is in effect, the 2K page containing the record is locked only while the record is being updated with the `Update` member function. @@ -2285,7 +2288,7 @@ The name of the parameter whose value you want to set. The parameter must already have been established as part of the recordset's SQL string. You can access the parameter either by name or by its index position in the collection. -Specify the value to set as a `COleVariant` object. For information about setting the desired value and type in your `COleVariant` object, see class [COleVariant](../../mfc/reference/colevariant-class.md). Note that if you are not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. +Specify the value to set as a `COleVariant` object. For information about setting the desired value and type in your `COleVariant` object, see class [COleVariant](../../mfc/reference/colevariant-class.md). If you're not creating a UNICODE recordset, the `COleVariant` object must be explicitly declared ANSI. This can be done by using the [COleVariant::COleVariant](../../mfc/reference/colevariant-class.md#colevariant)**(** *lpszSrc* **,** *vtSrc* **)** form of constructor with *vtSrc* set to `VT_BSTRT` (ANSI) or by using the `COleVariant` function [SetString](../../mfc/reference/colevariant-class.md#setstring)**(** *lpszSrc* **,** *vtSrc* **)** with *vtSrc* set to `VT_BSTRT`. ## CDaoRecordset::SetParamValueNull @@ -2306,7 +2309,7 @@ The name of the field in the recordset, for lookup by name. ### Remarks -C++ NULL is not the same as Null, which, in database terminology, means "having no value." +C++ NULL isn't the same as Null, which, in database terminology, means "having no value." ## CDaoRecordset::SetPercentPosition @@ -2328,7 +2331,7 @@ When working with a dynaset-type or snapshot-type recordset, first populate the Once you call `SetPercentPosition`, the record at the approximate position corresponding to that value becomes current. > [!NOTE] -> Calling `SetPercentPosition` to move the current record to a specific record in a recordset is not recommended. Call the [SetBookmark](#setbookmark) member function instead. +> Calling `SetPercentPosition` to move the current record to a specific record in a recordset isn't recommended. Call the [SetBookmark](#setbookmark) member function instead. For related information, see the topic "PercentPosition Property" in DAO Help. @@ -2351,7 +2354,7 @@ If the data source supports transactions, you can make the `Update` call (and it > [!CAUTION] > If you call `Update` without first calling either `AddNew` or `Edit`, `Update` throws a `CDaoException`. If you call `AddNew` or `Edit`, you must call `Update` before you call [MoveNext](#movenext) or close either the recordset or the data source connection. Otherwise, your changes are lost without notification. -When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time `Edit` is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it is updated in the database. If the record has changed since you called `Edit`, the `Update` operation fails and MFC throws an exception. You can change the locking mode with `SetLockingMode`. +When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time `Edit` is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it's updated in the database. If the record has changed since you called `Edit`, the `Update` operation fails and MFC throws an exception. You can change the locking mode with `SetLockingMode`. > [!NOTE] > Optimistic locking is always used on external database formats, such as ODBC and installable ISAM. diff --git a/docs/mfc/reference/cdaorecordview-class.md b/docs/mfc/reference/cdaorecordview-class.md index 616077e525..e2baaabc9e 100644 --- a/docs/mfc/reference/cdaorecordview-class.md +++ b/docs/mfc/reference/cdaorecordview-class.md @@ -4,12 +4,14 @@ title: "CDaoRecordView Class" ms.date: "11/04/2016" f1_keywords: ["CDaoRecordView", "AFXDAO/CDaoRecordView", "AFXDAO/CDaoRecordView::CDaoRecordView", "AFXDAO/CDaoRecordView::IsOnFirstRecord", "AFXDAO/CDaoRecordView::IsOnLastRecord", "AFXDAO/CDaoRecordView::OnGetRecordset", "AFXDAO/CDaoRecordView::OnMove"] helpviewer_keywords: ["CDaoRecordView [MFC], CDaoRecordView", "CDaoRecordView [MFC], IsOnFirstRecord", "CDaoRecordView [MFC], IsOnLastRecord", "CDaoRecordView [MFC], OnGetRecordset", "CDaoRecordView [MFC], OnMove"] -ms.assetid: 5aa7d0e2-bd05-413e-b216-80c404ce18ac --- # CDaoRecordView Class A view that displays database records in controls. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ``` @@ -70,7 +72,7 @@ For more information about declaring and using your record view and recordset cl ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoRecordView::CDaoRecordView diff --git a/docs/mfc/reference/cdaorelationfieldinfo-structure.md b/docs/mfc/reference/cdaorelationfieldinfo-structure.md index f77f5502ff..af98cdba7e 100644 --- a/docs/mfc/reference/cdaorelationfieldinfo-structure.md +++ b/docs/mfc/reference/cdaorelationfieldinfo-structure.md @@ -4,12 +4,14 @@ title: "CDaoRelationFieldInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CDaoRelationFieldInfo"] helpviewer_keywords: ["DAO (Data Access Objects), Relations collection", "CDaoRelationFieldInfo structure [MFC]"] -ms.assetid: 47cb89ca-dc80-47ce-96fd-cc4b88512558 --- # CDaoRelationFieldInfo Structure The `CDaoRelationFieldInfo` structure contains information about a field in a relation defined for data access objects (DAO). +> [!NOTE] +> Data Access Objects (DAO) is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ``` @@ -30,15 +32,15 @@ The name of the field in the foreign table of the relation. ## Remarks -A DAO relation object specifies the fields in a primary table and the fields in a foreign table that define the relation. The references to Primary in the structure definition above indicate how the information is returned in the `m_pFieldInfos` member of a [CDaoRelationInfo](../../mfc/reference/cdaorelationinfo-structure.md) object obtained by calling the [GetRelationInfo](../../mfc/reference/cdaodatabase-class.md#getrelationinfo) member function of class `CDaoDatabase`. +A DAO relation object specifies the fields in a primary table and the fields in a foreign table that define the relation. The references to Primary in the structure definition indicate how the information is returned in the `m_pFieldInfos` member of a [CDaoRelationInfo](../../mfc/reference/cdaorelationinfo-structure.md) object obtained by calling the [GetRelationInfo](../../mfc/reference/cdaodatabase-class.md#getrelationinfo) member function of class `CDaoDatabase`. -Relation objects and relation field objects are not represented by an MFC class. Instead, the DAO objects underlying MFC objects of class [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) contain a collection of relation objects, called the Relations collection. Each relation object, in turn, contains a collection of relation field objects. Each relation field object correlates a field in the primary table with a field in the foreign table. Taken together, the relation field objects define a group of fields in each table, which together define the relation. `CDaoDatabase` lets you access relation objects with a `CDaoRelationInfo` object by calling the `GetRelationInfo` member function. The `CDaoRelationInfo` object, then, has a data member, `m_pFieldInfos`, that points to an array of `CDaoRelationFieldInfo` objects. +Relation objects and relation field objects aren't represented by an MFC class. Instead, the DAO objects underlying MFC objects of class [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) contain a collection of relation objects, called the Relations collection. Each relation object, in turn, contains a collection of relation field objects. Each relation field object correlates a field in the primary table with a field in the foreign table. Taken together, the relation field objects define a group of fields in each table, which together define the relation. `CDaoDatabase` lets you access relation objects with a `CDaoRelationInfo` object by calling the `GetRelationInfo` member function. The `CDaoRelationInfo` object has a data member, `m_pFieldInfos`, that points to an array of `CDaoRelationFieldInfo` objects. -Call the [GetRelationInfo](../../mfc/reference/cdaodatabase-class.md#getrelationinfo) member function of the containing `CDaoDatabase` object in whose Relations collection is stored the relation object you are interested in. Then access the `m_pFieldInfos` member of the [CDaoRelationInfo](../../mfc/reference/cdaorelationinfo-structure.md) object. `CDaoRelationFieldInfo` also defines a `Dump` member function in debug builds. You can use `Dump` to dump the contents of a `CDaoRelationFieldInfo` object. +Call the [GetRelationInfo](../../mfc/reference/cdaodatabase-class.md#getrelationinfo) member function of the containing `CDaoDatabase` object in whose Relations collection is stored the relation object you're interested in. Then access the `m_pFieldInfos` member of the [CDaoRelationInfo](../../mfc/reference/cdaorelationinfo-structure.md) object. `CDaoRelationFieldInfo` also defines a `Dump` member function in debug builds. You can use `Dump` to dump the contents of a `CDaoRelationFieldInfo` object. ## Requirements -**Header:** afxdao.h +**Header:** `afxdao`.h ## See also diff --git a/docs/mfc/reference/cdaorelationinfo-structure.md b/docs/mfc/reference/cdaorelationinfo-structure.md index 5152258fe0..d93623b3d7 100644 --- a/docs/mfc/reference/cdaorelationinfo-structure.md +++ b/docs/mfc/reference/cdaorelationinfo-structure.md @@ -4,11 +4,13 @@ title: "CDaoRelationInfo Structure" ms.date: "06/25/2018" f1_keywords: ["CDaoRelationInfo"] helpviewer_keywords: ["DAO (Data Access Objects), Relations collection", "CDaoRelationInfo structure [MFC]"] -ms.assetid: 92dda090-fe72-4090-84ec-429498a48aad --- # CDaoRelationInfo Structure -The `CDaoRelationInfo` structure contains information about a relation defined between fields of two tables in a [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) object. +The `CDaoRelationInfo` structure contains information about a relation defined between fields of two tables in a [`CDaoDatabase`](../../mfc/reference/cdaodatabase-class.md) object. + +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax @@ -71,7 +73,7 @@ Information retrieved by the [CDaoDatabase::GetRelationInfo](../../mfc/reference ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaotabledef-class.md b/docs/mfc/reference/cdaotabledef-class.md index b70a9f16ed..5ad89da173 100644 --- a/docs/mfc/reference/cdaotabledef-class.md +++ b/docs/mfc/reference/cdaotabledef-class.md @@ -4,12 +4,14 @@ title: "CDaoTableDef Class" ms.date: "11/04/2016" f1_keywords: ["CDaoTableDef", "AFXDAO/CDaoTableDef", "AFXDAO/CDaoTableDef::CDaoTableDef", "AFXDAO/CDaoTableDef::Append", "AFXDAO/CDaoTableDef::CanUpdate", "AFXDAO/CDaoTableDef::Close", "AFXDAO/CDaoTableDef::Create", "AFXDAO/CDaoTableDef::CreateField", "AFXDAO/CDaoTableDef::CreateIndex", "AFXDAO/CDaoTableDef::DeleteField", "AFXDAO/CDaoTableDef::DeleteIndex", "AFXDAO/CDaoTableDef::GetAttributes", "AFXDAO/CDaoTableDef::GetConnect", "AFXDAO/CDaoTableDef::GetDateCreated", "AFXDAO/CDaoTableDef::GetDateLastUpdated", "AFXDAO/CDaoTableDef::GetFieldCount", "AFXDAO/CDaoTableDef::GetFieldInfo", "AFXDAO/CDaoTableDef::GetIndexCount", "AFXDAO/CDaoTableDef::GetIndexInfo", "AFXDAO/CDaoTableDef::GetName", "AFXDAO/CDaoTableDef::GetRecordCount", "AFXDAO/CDaoTableDef::GetSourceTableName", "AFXDAO/CDaoTableDef::GetValidationRule", "AFXDAO/CDaoTableDef::GetValidationText", "AFXDAO/CDaoTableDef::IsOpen", "AFXDAO/CDaoTableDef::Open", "AFXDAO/CDaoTableDef::RefreshLink", "AFXDAO/CDaoTableDef::SetAttributes", "AFXDAO/CDaoTableDef::SetConnect", "AFXDAO/CDaoTableDef::SetName", "AFXDAO/CDaoTableDef::SetSourceTableName", "AFXDAO/CDaoTableDef::SetValidationRule", "AFXDAO/CDaoTableDef::SetValidationText", "AFXDAO/CDaoTableDef::m_pDAOTableDef", "AFXDAO/CDaoTableDef::m_pDatabase"] helpviewer_keywords: ["CDaoTableDef [MFC], CDaoTableDef", "CDaoTableDef [MFC], Append", "CDaoTableDef [MFC], CanUpdate", "CDaoTableDef [MFC], Close", "CDaoTableDef [MFC], Create", "CDaoTableDef [MFC], CreateField", "CDaoTableDef [MFC], CreateIndex", "CDaoTableDef [MFC], DeleteField", "CDaoTableDef [MFC], DeleteIndex", "CDaoTableDef [MFC], GetAttributes", "CDaoTableDef [MFC], GetConnect", "CDaoTableDef [MFC], GetDateCreated", "CDaoTableDef [MFC], GetDateLastUpdated", "CDaoTableDef [MFC], GetFieldCount", "CDaoTableDef [MFC], GetFieldInfo", "CDaoTableDef [MFC], GetIndexCount", "CDaoTableDef [MFC], GetIndexInfo", "CDaoTableDef [MFC], GetName", "CDaoTableDef [MFC], GetRecordCount", "CDaoTableDef [MFC], GetSourceTableName", "CDaoTableDef [MFC], GetValidationRule", "CDaoTableDef [MFC], GetValidationText", "CDaoTableDef [MFC], IsOpen", "CDaoTableDef [MFC], Open", "CDaoTableDef [MFC], RefreshLink", "CDaoTableDef [MFC], SetAttributes", "CDaoTableDef [MFC], SetConnect", "CDaoTableDef [MFC], SetName", "CDaoTableDef [MFC], SetSourceTableName", "CDaoTableDef [MFC], SetValidationRule", "CDaoTableDef [MFC], SetValidationText", "CDaoTableDef [MFC], m_pDAOTableDef", "CDaoTableDef [MFC], m_pDatabase"] -ms.assetid: 7c5d2254-8475-43c4-8a6c-2d32ead194c9 --- # CDaoTableDef Class Represents the stored definition of a base table or an attached table. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ``` @@ -114,7 +116,7 @@ When you finish using a tabledef object, call its [Close](../../mfc/reference/cd ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoTableDef::Append @@ -420,7 +422,7 @@ The path as shown in the table below is the full path for the directory containi The table in [CDaoTableDef::SetConnect](#setconnect) shows possible database types and their corresponding database specifiers and paths: -For Microsoft Jet database base tables, the specifier is a empty string (""). +For Microsoft Jet database base tables, the specifier is an empty string (""). If a password is required but not provided, the ODBC driver displays a login dialog box the first time a table is accessed and again if the connection is closed and reopened. If an attached table has the `dbAttachSavePWD` attribute, the login prompt will not appear when the table is reopened. @@ -759,9 +761,9 @@ Characteristics of the table represented by the `CDaoTableDef` object and can be When setting multiple attributes, you can combine them by summing the appropriate constants using the bitwise-OR operator. Setting `dbAttachExclusive` on a nonattached table produces an exception. Combining the following values also produce an exception: -- **dbAttachExclusive | dbAttachedODBC** +- `dbAttachExclusive | dbAttachedODBC` -- **dbAttachSavePWD | dbAttachedTable** +- `dbAttachSavePWD | dbAttachedTable` For related information, see the topic "Attributes Property" in DAO Help. @@ -804,7 +806,7 @@ The following table shows possible database types and their corresponding databa |HTML Export|"HTML Export;"|" `drive`:\\\ *path*"| |Text|"Text;"|"drive:\\\path"| |ODBC|"ODBC; DATABASE= `database`; UID= *user*;PWD= *password*; DSN= *datasourcename;* LOGINTIMEOUT= *seconds;*" (This may not be a complete connection string for all servers; it is just an example. It is very important not to have spaces between the parameters.)|None| -|Exchange|"Exchange;

MAPILEVEL= *folderpath*;

[TABLETYPE={ 0 | 1 };]

[PROFILE= *profile*;]

[PWD= *password*;]

[DATABASE= `database`;]"|*"drive*:\\\ *path*\\\ *filename*.MDB"| +|Exchange|"Exchange;

MAPILEVEL= *folderpath*;

[TABLETYPE={ 0 \| 1 };]

[PROFILE= *profile*;]

[PWD= *password*;]

[DATABASE= `database`;]"|*"drive*:\\\ *path*\\\ *filename*.MDB"| > [!NOTE] > Btrieve is no longer supported as of DAO 3.5. diff --git a/docs/mfc/reference/cdaotabledefinfo-structure.md b/docs/mfc/reference/cdaotabledefinfo-structure.md index 364dd5c84d..ca83c7daed 100644 --- a/docs/mfc/reference/cdaotabledefinfo-structure.md +++ b/docs/mfc/reference/cdaotabledefinfo-structure.md @@ -4,12 +4,14 @@ title: "CDaoTableDefInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CDaoTableDefInfo"] helpviewer_keywords: ["CDaoTableDefInfo structure [MFC]", "DAO (Data Access Objects), TableDefs collection"] -ms.assetid: c01ccebb-5615-434e-883c-4f60eac943dd --- # CDaoTableDefInfo Structure The `CDaoTableDefInfo` structure contains information about a tabledef object defined for data access objects (DAO). +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ``` @@ -37,7 +39,7 @@ Uniquely names the tabledef object. To retrieve the value of this property direc Indicates whether changes can be made to the table. The quick way to determine whether a table is updatable is to open a `CDaoTableDef` object for the table and call the object's [CanUpdate](../../mfc/reference/cdaotabledef-class.md#canupdate) member function. `CanUpdate` always returns nonzero (TRUE) for a newly created tabledef object and 0 (FALSE) for an attached tabledef object. A new tabledef object can be appended only to a database for which the current user has write permission. If the table contains only nonupdatable fields, `CanUpdate` returns 0. When one or more fields are updatable, `CanUpdate` returns nonzero. You can edit only the updatable fields. For more information, see the topic "Updatable Property" in DAO Help. *m_lAttributes*
-Specifies characteristics of the table represented by the tabledef object. To retrieve the current attributes of a tabledef, call its [GetAttributes](../../mfc/reference/cdaotabledef-class.md#getattributes) member function. The value returned can be a combination of these long constants (using the bitwise-OR (**|**) operator): +Specifies characteristics of the table represented by the tabledef object. To retrieve the current attributes of a tabledef, call its [GetAttributes](../../mfc/reference/cdaotabledef-class.md#getattributes) member function. The value returned can be a combination of these long constants (using the bitwise-OR (**`|`**) operator): - `dbAttachExclusive` For databases that use the Microsoft Jet database engine, indicates the table is an attached table opened for exclusive use. @@ -82,7 +84,7 @@ The date and time settings are derived from the computer on which the base table ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdaoworkspace-class.md b/docs/mfc/reference/cdaoworkspace-class.md index b0de0bfade..777678f429 100644 --- a/docs/mfc/reference/cdaoworkspace-class.md +++ b/docs/mfc/reference/cdaoworkspace-class.md @@ -4,15 +4,17 @@ title: "CDaoWorkspace Class" ms.date: "11/04/2016" f1_keywords: ["CDaoWorkspace", "AFXDAO/CDaoWorkspace", "AFXDAO/CDaoWorkspace::CDaoWorkspace", "AFXDAO/CDaoWorkspace::Append", "AFXDAO/CDaoWorkspace::BeginTrans", "AFXDAO/CDaoWorkspace::Close", "AFXDAO/CDaoWorkspace::CommitTrans", "AFXDAO/CDaoWorkspace::CompactDatabase", "AFXDAO/CDaoWorkspace::Create", "AFXDAO/CDaoWorkspace::GetDatabaseCount", "AFXDAO/CDaoWorkspace::GetDatabaseInfo", "AFXDAO/CDaoWorkspace::GetIniPath", "AFXDAO/CDaoWorkspace::GetIsolateODBCTrans", "AFXDAO/CDaoWorkspace::GetLoginTimeout", "AFXDAO/CDaoWorkspace::GetName", "AFXDAO/CDaoWorkspace::GetUserName", "AFXDAO/CDaoWorkspace::GetVersion", "AFXDAO/CDaoWorkspace::GetWorkspaceCount", "AFXDAO/CDaoWorkspace::GetWorkspaceInfo", "AFXDAO/CDaoWorkspace::Idle", "AFXDAO/CDaoWorkspace::IsOpen", "AFXDAO/CDaoWorkspace::Open", "AFXDAO/CDaoWorkspace::RepairDatabase", "AFXDAO/CDaoWorkspace::Rollback", "AFXDAO/CDaoWorkspace::SetDefaultPassword", "AFXDAO/CDaoWorkspace::SetDefaultUser", "AFXDAO/CDaoWorkspace::SetIniPath", "AFXDAO/CDaoWorkspace::SetIsolateODBCTrans", "AFXDAO/CDaoWorkspace::SetLoginTimeout", "AFXDAO/CDaoWorkspace::m_pDAOWorkspace"] helpviewer_keywords: ["CDaoWorkspace [MFC], CDaoWorkspace", "CDaoWorkspace [MFC], Append", "CDaoWorkspace [MFC], BeginTrans", "CDaoWorkspace [MFC], Close", "CDaoWorkspace [MFC], CommitTrans", "CDaoWorkspace [MFC], CompactDatabase", "CDaoWorkspace [MFC], Create", "CDaoWorkspace [MFC], GetDatabaseCount", "CDaoWorkspace [MFC], GetDatabaseInfo", "CDaoWorkspace [MFC], GetIniPath", "CDaoWorkspace [MFC], GetIsolateODBCTrans", "CDaoWorkspace [MFC], GetLoginTimeout", "CDaoWorkspace [MFC], GetName", "CDaoWorkspace [MFC], GetUserName", "CDaoWorkspace [MFC], GetVersion", "CDaoWorkspace [MFC], GetWorkspaceCount", "CDaoWorkspace [MFC], GetWorkspaceInfo", "CDaoWorkspace [MFC], Idle", "CDaoWorkspace [MFC], IsOpen", "CDaoWorkspace [MFC], Open", "CDaoWorkspace [MFC], RepairDatabase", "CDaoWorkspace [MFC], Rollback", "CDaoWorkspace [MFC], SetDefaultPassword", "CDaoWorkspace [MFC], SetDefaultUser", "CDaoWorkspace [MFC], SetIniPath", "CDaoWorkspace [MFC], SetIsolateODBCTrans", "CDaoWorkspace [MFC], SetLoginTimeout", "CDaoWorkspace [MFC], m_pDAOWorkspace"] -ms.assetid: 64f60de6-4df1-4d4a-a65b-c489b5257d52 --- # CDaoWorkspace Class -Manages a named, password-protected database session from login to logoff, by a single user. DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. +Manages a named, password-protected database session from login to logoff, by a single user. + +> [!NOTE] +> Data Access Objects (DAO) is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. ## Syntax -``` +```cpp class CDaoWorkspace : public CObject ``` @@ -48,7 +50,7 @@ class CDaoWorkspace : public CObject |[CDaoWorkspace::IsOpen](#isopen)|Returns nonzero if the workspace is open.| |[CDaoWorkspace::Open](#open)|Explicitly opens a workspace object associated with DAO's default workspace.| |[CDaoWorkspace::RepairDatabase](#repairdatabase)|Attempts to repair a damaged database.| -|[CDaoWorkspace::Rollback](#rollback)|Ends the current transaction and does not save the changes.| +|[CDaoWorkspace::Rollback](#rollback)|Ends the current transaction and doesn't save the changes.| |[CDaoWorkspace::SetDefaultPassword](#setdefaultpassword)|Sets the password that the database engine uses when a workspace object is created without a specific password.| |[CDaoWorkspace::SetDefaultUser](#setdefaultuser)|Sets the user name that the database engine uses when a workspace object is created without a specific user name.| |[CDaoWorkspace::SetIniPath](#setinipath)|Sets the location of the Microsoft Jet database engine's initialization settings in the Windows registry.| @@ -63,18 +65,18 @@ class CDaoWorkspace : public CObject ## Remarks -In most cases, you will not need multiple workspaces, and you will not need to create explicit workspace objects; when you open database and recordset objects, they use DAO's default workspace. However, if needed, you can run multiple sessions at a time by creating additional workspace objects. Each workspace object can contain multiple open database objects in its own Databases collection. In MFC, a workspace is primarily a transaction manager, specifying a set of open databases all in the same "transaction space." +In most cases, you won't need multiple workspaces, and you won't need to create explicit workspace objects; when you open database and recordset objects, they use DAO's default workspace. However, if needed, you can run multiple sessions at a time by creating more workspace objects. Each workspace object can contain multiple open database objects in its own Databases collection. In MFC, a workspace is primarily a transaction manager, specifying a set of open databases all in the same "transaction space." > [!NOTE] > The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have a "CDao" prefix. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC. The DAO-based classes access data through the Microsoft Jet database engine, including ODBC drivers. They also support Data Definition Language (DDL) operations, such as creating databases and adding tables and fields via the classes, without having to call DAO directly. ## Capabilities -Class `CDaoWorkspace` provides the following: +Class `CDaoWorkspace` provides: - Explicit access, if needed, to a default workspace, created by initializing the database engine. Usually you use DAO's default workspace implicitly by creating database and recordset objects. -- A transaction space in which transactions apply to all databases open in the workspace. You can create additional workspaces to manage separate transaction spaces. +- A transaction space in which transactions apply to all databases open in the workspace. You can create more workspaces to manage separate transaction spaces. - An interface to many properties of the underlying Microsoft Jet database engine (see the static member functions). Opening or creating a workspace, or calling a static member function before open or create, initializes the database engine. @@ -82,7 +84,7 @@ Class `CDaoWorkspace` provides the following: ## Security -MFC does not implement the Users and Groups collections in DAO, which are used for security control. If you need those aspects of DAO, you must program them yourself via direct calls to DAO interfaces. For information, see [Technical Note 54](../../mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md). +MFC doesn't implement the Users and Groups collections in DAO, which are used for security control. If you need those aspects of DAO, you must program them yourself via direct calls to DAO interfaces. For information, see [Technical Note 54](../../mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md). ## Usage @@ -90,17 +92,17 @@ You can use class `CDaoWorkspace` to: - Explicitly open the default workspace. - Usually your use of the default workspace is implicit — when you open new [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) or [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) objects. But you might need to access it explicitly — for example, to access database engine properties or the Workspaces collection. See "Implicit Use of the Default Workspace" below. + Usually your use of the default workspace is implicit when you open new [CDaoDatabase](../../mfc/reference/cdaodatabase-class.md) or [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) objects. But you might need to access it explicitly. For example, to access database engine properties or the Workspaces collection. See "Implicit Use of the Default Workspace" below. - Create new workspaces. Call [Append](#append) if you want to add them to the Workspaces collection. - Open an existing workspace in the Workspaces collection. -Creating a new workspace that does not already exist in the Workspaces collection is described under the [Create](#create) member function. Workspace objects do not persist in any way between datababase engine sessions. If your application links MFC statically, ending the application uninitializes the database engine. If your application links with MFC dynamically, the database engine is uninitialized when the MFC DLL is unloaded. +Creating a new workspace that doesn't already exist in the Workspaces collection is described under the [Create](#create) member function. Workspace objects don't persist in any way between database engine sessions. If your application links MFC statically, ending the application uninitializes the database engine. If your application links with MFC dynamically, the database engine is uninitialized when the MFC DLL is unloaded. Explicitly opening the default workspace, or opening an existing workspace in the Workspaces collection, is described under the [Open](#open) member function. -End a workspace session by closing the workspace with the [Close](#close) member function. `Close` closes any databases you have not closed previously, rolling back any uncommitted transactions. +End a workspace session by closing the workspace with the [Close](#close) member function. `Close` closes any databases you haven't closed and rolls back any uncommitted transactions. ## Transactions @@ -110,7 +112,7 @@ DAO manages transactions at the workspace level; hence, transactions on a worksp MFC uses DAO's default workspace implicitly under the following circumstances: -- If you create a new `CDaoDatabase` object but do not do so through an existing `CDaoWorkspace` object, MFC creates a temporary workspace object for you, which corresponds to DAO's default workspace. If you do so for multiple databases, all of the database objects are associated with the default workspace. You can access a database's workspace through a `CDaoDatabase` data member. +- If you create a new `CDaoDatabase` object but don't do so through an existing `CDaoWorkspace` object, MFC creates a temporary workspace object for you, which corresponds to DAO's default workspace. If you do so for multiple databases, all of the database objects are associated with the default workspace. You can access a database's workspace through a `CDaoDatabase` data member. - Similarly, if you create a `CDaoRecordset` object without supplying a pointer to a `CDaoDatabase` object, MFC creates a temporary database object and, by extension, a temporary workspace object. You can access a recordset's database, and indirectly its workspace, through a `CDaoRecordset` data member. @@ -122,13 +124,13 @@ For information about calling DAO directly and about DAO security, see [Technica ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) `CDaoWorkspace` ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoWorkspace::Append @@ -140,7 +142,7 @@ virtual void Append(); ### Remarks -`Append` appends a newly created workspace object to the database engine's Workspaces collection. Workspaces do not persist between database engine sessions; they are stored only in memory, not on disk. You do not have to append a workspace; if you do not, you can still use it. +`Append` appends a newly created workspace object to the database engine's Workspaces collection. Workspaces don't persist between database engine sessions; they're stored only in memory, not on disk. You don't have to append a workspace; if you don't, you can still use it. An appended workspace remains in the Workspaces collection, in an active, open state, until you call its [Close](#close) member function. @@ -201,13 +203,13 @@ Closing an open workspace object releases the underlying DAO object and, if the > [!CAUTION] > Closing a workspace object closes any open databases in the workspace. This results in any recordsets open in the databases being closed as well, and any pending edits or updates are rolled back. For related information, see the [CDaoDatabase::Close](../../mfc/reference/cdaodatabase-class.md#close), [CDaoRecordset::Close](../../mfc/reference/cdaorecordset-class.md#close), [CDaoTableDef::Close](../../mfc/reference/cdaotabledef-class.md#close), and [CDaoQueryDef::Close](../../mfc/reference/cdaoquerydef-class.md#close) member functions. -Workspace objects are not permanent; they only exist while references to them exist. This means that when the database engine session ends, the workspace and its Databases collection do not persist. You must re-create them for the next session by opening your workspace and database(s) again. +Workspace objects aren't permanent; they only exist while references to them exist. This means that when the database engine session ends, the workspace, and its Databases collection don't persist. You must re-create them for the next session by opening your workspace and database(s) again. For related information, see the topic "Close Method" in DAO Help. ## CDaoWorkspace::CommitTrans -Call this member function to commit a transaction — save a group of edits and updates to one or more databases in the workspace. +Call this member function to commit a transaction which saves a group of edits and updates to one or more databases in the workspace. ```cpp void CommitTrans(); @@ -218,12 +220,12 @@ void CommitTrans(); A transaction consists of a series of changes to the database's data or its structure, beginning with a call to [BeginTrans](#begintrans). When you complete the transaction, either commit it or roll it back (cancel the changes) with [Rollback](#rollback). By default, without transactions, updates to records are committed immediately. Calling `BeginTrans` causes commitment of updates to be delayed until you call `CommitTrans`. > [!CAUTION] -> Within one workspace, transactions are always global to the workspace and are not limited to only one database or recordset. If you perform operations on more than one database or recordset within a workspace transaction, `CommitTrans` commits all pending updates, and `Rollback` restores all operations on those databases and recordsets. +> Within one workspace, transactions are always global to the workspace and aren't limited to only one database or recordset. If you perform operations on more than one database or recordset within a workspace transaction, `CommitTrans` commits all pending updates, and `Rollback` restores all operations on those databases and recordsets. When you close a database or workspace with pending transactions, the transactions are all rolled back. > [!NOTE] -> This is not a two-phase commit mechanism. If one update fails to commit, others still will commit. +> This isn't a two-phase commit mechanism. If one update fails to commit, others still will commit. ## CDaoWorkspace::CompactDatabase @@ -250,13 +252,13 @@ static void PASCAL CompactDatabase( The name of an existing, closed database. It can be a full path and filename, such as "C:\\\MYDB.MDB". If the filename has an extension, you must specify it. If your network supports the uniform naming convention (UNC), you can also specify a network path, such as "\\\\\\\MYSERVER\\\MYSHARE\\\MYDIR\\\MYDB.MDB". (Double backslashes are required in the path strings because "\\" is the C++ escape character.) *lpszDestName*
-The full path of the compacted database that you are creating. You can also specify a network path as with *lpszSrcName*. You cannot use the *lpszDestName* argument to specify the same database file as *lpszSrcName*. +The full path of the compacted database that you are creating. You can also specify a network path as with *lpszSrcName*. You can't use the *lpszDestName* argument to specify the same database file as *lpszSrcName*. *lpszPassword*
-A password, used when you want to compact a password-protected database. Note that if you use the version of `CompactDatabase` that takes a password, you must supply all parameters. Also, because this is a connect parameter, it requires special formatting, as follows: ;PWD= *lpszPassword*. For example: ;PWD="Happy". (The leading semicolon is required.) +A password, used when you want to compact a password-protected database. If you use the version of `CompactDatabase` that takes a password, you must supply all parameters. Also, because this is a connect parameter, it requires special formatting, as follows: ;PWD= *lpszPassword*. For example: ;PWD="Happy". (The leading semicolon is required.) *lpszLocale*
-A string expression used to specify collating order for creating *lpszDestName*. If you omit this argument by accepting the default value of `dbLangGeneral` (see below), the locale of the new database is the same as that of the old database. Possible values are: +A string expression used to specify collating order for creating *lpszDestName*. If you omit this argument by accepting the default value of `dbLangGeneral` (see below), the locale of the new database is the same as the old database. Possible values are: - `dbLangGeneral` English, German, French, Portuguese, Italian, and Modern Spanish @@ -289,7 +291,7 @@ A string expression used to specify collating order for creating *lpszDestName*. - `dbLangTurkish` Turkish *nOptions*
-Indicates one or more options for the target database, *lpszDestName*. If you omit this argument by accepting the default value, the *lpszDestName* will have the same encryption and the same version as *lpszSrcName*. You can combine the `dbEncrypt` or `dbDecrypt` option with one of the version options using the bitwise-OR operator. Possible values, which specify a database format, not a database engine version, are: +Indicates one or more options for the target database, *lpszDestName*. If you omit this argument by accepting the default value, the *lpszDestName* has the same encryption and the same version as *lpszSrcName*. You can combine the `dbEncrypt` or `dbDecrypt` option with one of the version options using the bitwise-OR operator. Possible values, which specify a database format, not a database engine version, are: - `dbEncrypt` Encrypt the database while compacting. @@ -303,17 +305,17 @@ Indicates one or more options for the target database, *lpszDestName*. If you om - `dbVersion30` Create a database that uses the Microsoft Jet database engine version 3.0 while compacting. -You can use `dbEncrypt` or `dbDecrypt` in the options argument to specify whether to encrypt or to decrypt the database as it is compacted. If you omit an encryption constant or if you include both `dbDecrypt` and `dbEncrypt`, *lpszDestName* will have the same encryption as *lpszSrcName*. You can use one of the version constants in the options argument to specify the version of the data format for the compacted database. This constant affects only the version of the data format of *lpszDestName*. You can specify only one version constant. If you omit a version constant, *lpszDestName* will have the same version as *lpszSrcName*. You can compact *lpszDestName* only to a version that is the same or later than that of *lpszSrcName*. +You can use `dbEncrypt` or `dbDecrypt` in the options argument to specify whether to encrypt or to decrypt the database as it is compacted. If you omit an encryption constant or if you include both `dbDecrypt` and `dbEncrypt`, *`lpszDestName`* has the same encryption as *`lpszSrcName`*. You can use one of the version constants in the options argument to specify the version of the data format for the compacted database. This constant affects only the version of the data format of *`lpszDestName`*. You can specify only one version constant. If you omit a version constant, *`lpszDestName`* will have the same version as *`lpszSrcName`*. You can compact *`lpszDestName`* only to a version that is the same or later than *`lpszSrcName`*. > [!CAUTION] -> If a database is not encrypted, it is possible, even if you implement user/password security, to directly read the binary disk file that constitutes the database. +> If a database isn't encrypted, it is possible, even if you implement user/password security, to directly read the binary disk file that constitutes the database. ### Remarks As you change data in a database, the database file can become fragmented and use more disk space than necessary. Periodically, you should compact your database to defragment the database file. The compacted database is usually smaller. You can also choose to change the collating order, the encryption, or the version of the data format while you copy and compact the database. > [!CAUTION] -> The `CompactDatabase` member function will not correctly convert a complete Microsoft Access database from one version to another. Only the data format is converted. Microsoft Access-defined objects, such as forms and reports, are not converted. However, the data is correctly converted. +> The `CompactDatabase` member function won't correctly convert a complete Microsoft Access database from one version to another. Only the data format is converted. Microsoft Access-defined objects, such as forms and reports, aren't converted. However, the data is correctly converted. > [!TIP] > You can also use `CompactDatabase` to copy a database file. @@ -352,11 +354,11 @@ The overall creation process is: 1. Optionally call [Append](#append) if you want to add the workspace to the database engine's Workspaces collection. You can work with the workspace without appending it. -After the `Create` call, the workspace object is in an open state, ready for use. You do not call `Open` after `Create`. You do not call `Create` if the workspace already exists in the Workspaces collection. `Create` initializes the database engine if it has not already been initialized for your application. +After the `Create` call, the workspace object is in an open state, ready for use. You don't call `Open` after `Create`. You don't call `Create` if the workspace already exists in the Workspaces collection. `Create` initializes the database engine if it hasn't already been initialized for your application. ## CDaoWorkspace::GetDatabaseCount -Call this member function to retrieve the number of DAO database objects in the workspace's Databases collection — the number of open databases in the workspace. +Call this member function to retrieve the number of DAO database objects in the workspace's Databases collection. Which is the number of open databases in the workspace. ``` short GetDatabaseCount(); @@ -422,7 +424,7 @@ static CString PASCAL GetIniPath(); ### Return Value -A [CString](../../atl-mfc-shared/reference/cstringt-class.md) containing the registry location. +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) containing the registry location. ### Remarks @@ -444,9 +446,9 @@ Nonzero if ODBC transactions are isolated; otherwise 0. ### Remarks -In some situations, you might need to have multiple simultaneous transactions pending on the same ODBC database. To do this, you need to open a separate workspace for each transaction. Keep in mind that although each workspace can have its own ODBC connection to the database, this slows system performance. Because transaction isolation is not normally required, ODBC connections from multiple workspace objects opened by the same user are shared by default. +In some situations, you might need to have multiple simultaneous transactions pending on the same ODBC database. To do this, you need to open a separate workspace for each transaction. Keep in mind that although each workspace can have its own ODBC connection to the database, this slows system performance. Because transaction isolation isn't normally required, ODBC connections from multiple workspace objects opened by the same user are shared by default. -Some ODBC servers, such as Microsoft SQL Server, do not allow simultaneous transactions on a single connection. If you need to have more than one transaction at a time pending against such a database, set the IsolateODBCTrans property to TRUE on each workspace as soon as you open it. This forces a separate ODBC connection for each workspace. +Some ODBC servers, such as Microsoft SQL Server, don't allow simultaneous transactions on a single connection. If you need to have more than one transaction at a time pending against such a database, set the IsolateODBCTrans property to TRUE on each workspace as soon as you open it. This forces a separate ODBC connection for each workspace. For related information, see the topic "IsolateODBCTrans Property" in DAO Help. @@ -466,7 +468,7 @@ The number of seconds before an error occurs when you attempt to log in to an OD This value represents the number of seconds before an error occurs when you attempt to log in to an ODBC database. The default LoginTimeout setting is 20 seconds. When LoginTimeout is set to 0, no timeout occurs and the communication with the data source might stop responding. -When you are attempting to log in to an ODBC database, such as Microsoft SQL Server, the connection may fail as a result of network errors or because the server is not running. Rather than waiting for the default 20 seconds to connect, you can specify how long the database engine waits before it produces an error. Logging in to the server happens implicitly as part of a number of different events, such as running a query on an external server database. +When you are attempting to log in to an ODBC database, such as Microsoft SQL Server, the connection may fail as a result of network errors or because the server isn't running. Rather than waiting for the default 20 seconds to connect, you can specify how long the database engine waits before it produces an error. Logging in to the server happens implicitly as part of different events, such as running a query on an external server database. For related information, see the topic "LoginTimeout Property" in DAO Help. @@ -480,7 +482,7 @@ CString GetName(); ### Return Value -A [CString](../../atl-mfc-shared/reference/cstringt-class.md) containing the user-defined name of the DAO workspace object. +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) containing the user-defined name of the DAO workspace object. ### Remarks @@ -498,7 +500,7 @@ CString GetUserName(); ### Return Value -A [CString](../../atl-mfc-shared/reference/cstringt-class.md) that represents the owner of the workspace object. +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) that represents the owner of the workspace object. ### Remarks @@ -516,7 +518,7 @@ static CString PASCAL GetVersion(); ### Return Value -A [CString](../../atl-mfc-shared/reference/cstringt-class.md) that indicates the version of the database engine associated with the object. +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) that indicates the version of the database engine associated with the object. ### Remarks @@ -538,7 +540,7 @@ The number of open workspaces in the Workspaces collection. ### Remarks -This count does not include any open workspaces not appended to the collection. `GetWorkspaceCount` is useful if you need to loop through all defined workspaces in the Workspaces collection. To obtain information about a given workspace in the collection, see [GetWorkspaceInfo](#getworkspaceinfo). Typical usage is to call `GetWorkspaceCount` for the number of open workspaces, then use that number as a loop index for repeated calls to `GetWorkspaceInfo`. +This count doesn't include any open workspaces not appended to the collection. `GetWorkspaceCount` is useful if you need to loop through all defined workspaces in the Workspaces collection. To obtain information about a given workspace in the collection, see [GetWorkspaceInfo](#getworkspaceinfo). Typical usage is to call `GetWorkspaceCount` for the number of open workspaces, then use that number as a loop index for repeated calls to `GetWorkspaceInfo`. ## CDaoWorkspace::GetWorkspaceInfo @@ -595,20 +597,20 @@ An action to take during the idle processing. Currently the only valid action is ### Remarks -This is often true in multiuser, multitasking environments in which there is not enough background processing time to keep all records in a recordset current. +This is often true in multiuser, multitasking environments in which there isn't enough background processing time to keep all records in a recordset current. > [!NOTE] -> Calling `Idle` is not necessary with databases created with version 3.0 of the Microsoft Jet database engine. Use `Idle` only for databases created with earlier versions. +> Calling `Idle` isn't necessary with databases created with version 3.0 of the Microsoft Jet database engine. Use `Idle` only for databases created with earlier versions. Usually, read locks are removed and data in local dynaset-type recordset objects is updated only when no other actions (including mouse movements) are occurring. If you periodically call `Idle`, you provide the database engine with time to catch up on background processing tasks by releasing unneeded read locks. Specifying the `dbFreeLocks` constant as an argument delays processing until all read locks are released. -This member function is not needed in single-user environments unless multiple instances of an application are running. The `Idle` member function may increase performance in a multiuser environment because it forces the database engine to flush data to disk, releasing locks on memory. You can also release read locks by making operations part of a transaction. +This member function isn't needed in single-user environments unless multiple instances of an application are running. The `Idle` member function may increase performance in a multiuser environment because it forces the database engine to flush data to disk, releasing locks on memory. You can also release read locks by making operations part of a transaction. For related information, see the topic "Idle Method" in DAO Help. ## CDaoWorkspace::IsOpen -Call this member function to determine whether the `CDaoWorkspace` object is open — that is, whether the MFC object has been initialized by a call to [Open](#open) or a call to [Create](#create). +Call this member function to determine whether the `CDaoWorkspace` object is open. Which means either the MFC object has been initialized by a call to [Open](#open) or a call to [Create](#create). ``` BOOL IsOpen() const; @@ -647,15 +649,15 @@ The name of the DAO workspace object to open — a string with up to 14 characte ### Remarks -After constructing a `CDaoWorkspace` object, call this member function to do one of the following: +After constructing a `CDaoWorkspace` object, call this member function to do one of: - Explicitly open the default workspace. Pass NULL for *lpszName*. - Open an existing `CDaoWorkspace` object, a member of the Workspaces collection, by name. Pass a valid name for an existing workspace object. -`Open` puts the workspace object into an open state and also initializes the database engine if it has not already been initialized for your application. +`Open` puts the workspace object into an open state and also initializes the database engine if it hasn't already been initialized for your application. -Although many `CDaoWorkspace` member functions can only be called after the workspace has been opened, the following member functions, which operate on the database engine, are available after construction of the C++ object but before a call to `Open`: +Although many `CDaoWorkspace` member functions can only be called after the workspace is opened, the following member functions, which operate on the database engine, are available after construction of the C++ object but before a call to `Open`: :::row::: :::column span=""::: @@ -692,9 +694,9 @@ The path and filename for an existing Microsoft Jet engine database file. If you ### Remarks -You must close the database specified by *lpszName* before you repair it. In a multiuser environment, other users cannot have *lpszName* open while you are repairing it. If *lpszName* is not closed or is not available for exclusive use, an error occurs. +You must close the database specified by *lpszName* before you repair it. In a multiuser environment, other users can't have *lpszName* open while you are repairing it. If *lpszName* isn't closed or isn't available for exclusive use, an error occurs. -This member function attempts to repair a database that was marked as possibly corrupt by an incomplete write operation. This can occur if an application using the Microsoft Jet database engine is closed unexpectedly because of a power outage or computer hardware problem. If you complete the operation and call the [Close](../../mfc/reference/cdaodatabase-class.md#close) member function or you quit the application in a usual way, the database will not be marked as possibly corrupt. +This member function attempts to repair a database that was marked as possibly corrupt by an incomplete write operation. This can occur if an application using the Microsoft Jet database engine is closed unexpectedly because of a power outage or computer hardware problem. If you complete the operation and call the [Close](../../mfc/reference/cdaodatabase-class.md#close) member function or you quit the application in a usual way, the database won't be marked as possibly corrupt. > [!NOTE] > After repairing a database, it is also a good idea to compact it using the [CompactDatabase](#compactdatabase) member function to defragment the file and to recover disk space. @@ -712,7 +714,7 @@ void Rollback(); ### Remarks > [!CAUTION] -> Within one workspace object, transactions are always global to the workspace and are not limited to only one database or recordset. If you perform operations on more than one database or recordset within a workspace transaction, `Rollback` restores all operations on all of those databases and recordsets. +> Within one workspace object, transactions are always global to the workspace and aren't limited to only one database or recordset. If you perform operations on more than one database or recordset within a workspace transaction, `Rollback` restores all operations on all of those databases and recordsets. If you close a workspace object without saving or rolling back any pending transactions, the transactions are automatically rolled back. If you call [CommitTrans](#committrans) or `Rollback` without first calling [BeginTrans](#begintrans), an error occurs. @@ -734,11 +736,11 @@ The default password. A password can be up to 14 characters long and can contain ### Remarks -The default password that you set applies to new workspaces you create after the call. When you create subsequent workspaces, you do not need to specify a password in the [Create](#create) call. +The default password that you set applies to new workspaces you create after the call. When you create subsequent workspaces, you don't need to specify a password in the [Create](#create) call. To use this member function: -1. Construct a `CDaoWorkspace` object but do not call `Create`. +1. Construct a `CDaoWorkspace` object but don't call `Create`. 1. Call `SetDefaultPassword` and, if you like, [SetDefaultUser](#setdefaultuser). @@ -759,15 +761,15 @@ static void PASCAL SetDefaultUser(LPCTSTR lpszDefaultUser); ### Parameters *lpszDefaultUser*
-The default user name. A user name can be 1 - 20 characters long and include alphabetic characters, accented characters, numbers, spaces, and symbols except for: " (quotation marks), / (forward slash), \ (backslash), \[ \] (brackets), : (colon), | (pipe), \< (less-than sign), > (greater-than sign), + (plus sign), = (equal sign), ; (semicolon), , ( comma), (question mark), \* (asterisk), leading spaces, and control characters (ASCII 00 to ASCII 31). For related information, see the topic "UserName Property" in DAO Help. +The default user name. A user name can be 1 - 20 characters long and include alphabetic characters, accented characters, numbers, spaces, and symbols except for: `"` (quotation marks), `/` (forward slash), `\` (backslash), `[ ]` (brackets), `:` (colon), `|` (pipe), `<` (less-than sign), `>` (greater-than sign), `+` (plus sign), `=` (equal sign), `;` (semicolon), `,` ( comma), (question mark), `*` (asterisk), leading spaces, and control characters (ASCII 00 to ASCII 31). For related information, see the topic "UserName Property" in DAO Help. ### Remarks -The default user name that you set applies to new workspaces you create after the call. When you create subsequent workspaces, you do not need to specify a user name in the [Create](#create) call. +The default user name that you set applies to new workspaces you create after the call. When you create subsequent workspaces, you don't need to specify a user name in the [Create](#create) call. To use this member function: -1. Construct a `CDaoWorkspace` object but do not call `Create`. +1. Construct a `CDaoWorkspace` object but don't call `Create`. 1. Call `SetDefaultUser` and, if you like, [SetDefaultPassword](#setdefaultpassword). @@ -797,7 +799,7 @@ Call `SetIniPath` only if you need to specify special settings. For more informa > [!NOTE] > Call `SetIniPath` during application installation, not when the application runs. `SetIniPath` must be called before you open any workspaces, databases, or recordsets; otherwise, MFC throws an exception. -You can use this mechanism to configure the database engine with user-provided registry settings. The scope of this attribute is limited to your application and cannot be changed without restarting your application. +You can use this mechanism to configure the database engine with user-provided registry settings. The scope of this attribute is limited to your application and can't be changed without restarting your application. ## CDaoWorkspace::SetIsolateODBCTrans @@ -814,9 +816,9 @@ Pass TRUE if you want to begin isolating ODBC transactions. Pass FALSE if you wa ### Remarks -In some situations, you might need to have multiple simultaneous transactions pending on the same ODBC database. To do this, you need to open a separate workspace for each transaction. Although each workspace can have its own ODBC connection to the database, this slows system performance. Because transaction isolation is not normally required, ODBC connections from multiple workspace objects opened by the same user are shared by default. +In some situations, you might need to have multiple simultaneous transactions pending on the same ODBC database. To do this, you need to open a separate workspace for each transaction. Although each workspace can have its own ODBC connection to the database, this slows system performance. Because transaction isolation isn't normally required, ODBC connections from multiple workspace objects opened by the same user are shared by default. -Some ODBC servers, such as Microsoft SQL Server, do not allow simultaneous transactions on a single connection. If you need to have more than one transaction at a time pending against such a database, set the IsolateODBCTrans property to TRUE on each workspace as soon as you open it. This forces a separate ODBC connection for each workspace. +Some ODBC servers, such as Microsoft SQL Server, don't allow simultaneous transactions on a single connection. If you need to have more than one transaction at a time pending against such a database, set the IsolateODBCTrans property to TRUE on each workspace as soon as you open it. This forces a separate ODBC connection for each workspace. ## CDaoWorkspace::SetLoginTimeout @@ -835,16 +837,16 @@ The number of seconds before an error occurs when you attempt to log in to an OD This value represents the number of seconds before an error occurs when you attempt to log in to an ODBC database. The default LoginTimeout setting is 20 seconds. When LoginTimeout is set to 0, no timeout occurs and the communication with the data source might stop responding. -When you are attempting to log in to an ODBC database, such as Microsoft SQL Server, the connection may fail as a result of network errors or because the server is not running. Rather than waiting for the default 20 seconds to connect, you can specify how long the database engine waits before it produces an error. Logging on to the server happens implicitly as part of a number of different events, such as running a query on an external server database. The timeout value is determined by the current setting of the LoginTimeout property. +When you are attempting to log in to an ODBC database, such as Microsoft SQL Server, the connection may fail as a result of network errors or because the server isn't running. Rather than waiting for the default 20 seconds to connect, you can specify how long the database engine waits before it produces an error. Logging on to the server happens implicitly as part of a number of different events, such as running a query on an external server database. The timeout value is determined by the current setting of the LoginTimeout property. For related information, see the topic "LoginTimeout Property" in DAO Help. ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
+[`CObject` Class](../../mfc/reference/cobject-class.md)
[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CDaoDatabase Class](../../mfc/reference/cdaodatabase-class.md)
-[CDaoRecordset Class](../../mfc/reference/cdaorecordset-class.md)
-[CDaoTableDef Class](../../mfc/reference/cdaotabledef-class.md)
-[CDaoQueryDef Class](../../mfc/reference/cdaoquerydef-class.md)
-[CDaoException Class](../../mfc/reference/cdaoexception-class.md) +[`CDaoDatabase` Class](../../mfc/reference/cdaodatabase-class.md)
+[`CDaoRecordset` Class](../../mfc/reference/cdaorecordset-class.md)
+[`CDaoTableDef` Class](../../mfc/reference/cdaotabledef-class.md)
+[`CDaoQueryDef` Class](../../mfc/reference/cdaoquerydef-class.md)
+[`CDaoException` Class](../../mfc/reference/cdaoexception-class.md) diff --git a/docs/mfc/reference/cdaoworkspaceinfo-structure.md b/docs/mfc/reference/cdaoworkspaceinfo-structure.md index 790e286f32..906f4cc2f3 100644 --- a/docs/mfc/reference/cdaoworkspaceinfo-structure.md +++ b/docs/mfc/reference/cdaoworkspaceinfo-structure.md @@ -4,12 +4,14 @@ title: "CDaoWorkspaceInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CDaoWorkspaceInfo"] helpviewer_keywords: ["CDaoWorkspaceInfo structure [MFC]", "DAO (Data Access Objects), Workspaces collection"] -ms.assetid: a1f4b25e-f9c6-4196-b075-d1df99c54124 --- # CDaoWorkspaceInfo Structure The `CDaoWorkspaceInfo` structure contains information about a workspace defined for data access objects (DAO) database access. +> [!NOTE] +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it's considered obsolete. + ## Syntax ``` @@ -40,7 +42,7 @@ Information retrieved by the [CDaoWorkspace::GetWorkspaceInfo](../../mfc/referen ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdatabase-class.md b/docs/mfc/reference/cdatabase-class.md index aa96521cb0..77fb3fd71c 100644 --- a/docs/mfc/reference/cdatabase-class.md +++ b/docs/mfc/reference/cdatabase-class.md @@ -193,7 +193,7 @@ You may find it convenient to embed the `CDatabase` object in your document clas This example illustrates using `CDatabase` in a `CDocument`-derived class. [!code-cpp[NVC_MFCDatabase#9](../../mfc/codesnippet/cpp/cdatabase-class_1.h)] - +  [!code-cpp[NVC_MFCDatabase#10](../../mfc/codesnippet/cpp/cdatabase-class_2.cpp)] ## `CDatabase::Close` diff --git a/docs/mfc/reference/cdatetimectrl-class.md b/docs/mfc/reference/cdatetimectrl-class.md index 47782a4a5e..095b88b964 100644 --- a/docs/mfc/reference/cdatetimectrl-class.md +++ b/docs/mfc/reference/cdatetimectrl-class.md @@ -4,9 +4,8 @@ title: "CDateTimeCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CDateTimeCtrl", "AFXDTCTL/CDateTimeCtrl", "AFXDTCTL/CDateTimeCtrl::CDateTimeCtrl", "AFXDTCTL/CDateTimeCtrl::CloseMonthCal", "AFXDTCTL/CDateTimeCtrl::Create", "AFXDTCTL/CDateTimeCtrl::GetDateTimePickerInfo", "AFXDTCTL/CDateTimeCtrl::GetIdealSize", "AFXDTCTL/CDateTimeCtrl::GetMonthCalColor", "AFXDTCTL/CDateTimeCtrl::GetMonthCalCtrl", "AFXDTCTL/CDateTimeCtrl::GetMonthCalFont", "AFXDTCTL/CDateTimeCtrl::GetMonthCalStyle", "AFXDTCTL/CDateTimeCtrl::GetRange", "AFXDTCTL/CDateTimeCtrl::GetTime", "AFXDTCTL/CDateTimeCtrl::SetFormat", "AFXDTCTL/CDateTimeCtrl::SetMonthCalColor", "AFXDTCTL/CDateTimeCtrl::SetMonthCalFont", "AFXDTCTL/CDateTimeCtrl::SetMonthCalStyle", "AFXDTCTL/CDateTimeCtrl::SetRange", "AFXDTCTL/CDateTimeCtrl::SetTime"] helpviewer_keywords: ["CDateTimeCtrl [MFC], CDateTimeCtrl", "CDateTimeCtrl [MFC], CloseMonthCal", "CDateTimeCtrl [MFC], Create", "CDateTimeCtrl [MFC], GetDateTimePickerInfo", "CDateTimeCtrl [MFC], GetIdealSize", "CDateTimeCtrl [MFC], GetMonthCalColor", "CDateTimeCtrl [MFC], GetMonthCalCtrl", "CDateTimeCtrl [MFC], GetMonthCalFont", "CDateTimeCtrl [MFC], GetMonthCalStyle", "CDateTimeCtrl [MFC], GetRange", "CDateTimeCtrl [MFC], GetTime", "CDateTimeCtrl [MFC], SetFormat", "CDateTimeCtrl [MFC], SetMonthCalColor", "CDateTimeCtrl [MFC], SetMonthCalFont", "CDateTimeCtrl [MFC], SetMonthCalStyle", "CDateTimeCtrl [MFC], SetRange", "CDateTimeCtrl [MFC], SetTime"] -ms.assetid: 7113993b-5d37-4148-939f-500a190c5bdc --- -# CDateTimeCtrl Class +# `CDateTimeCtrl` Class Encapsulates the functionality of a date and time picker control. @@ -22,28 +21,28 @@ class CDateTimeCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CDateTimeCtrl::CDateTimeCtrl](#cdatetimectrl)|Constructs a `CDateTimeCtrl` object.| +|[`CDateTimeCtrl::CDateTimeCtrl`](#cdatetimectrl)|Constructs a `CDateTimeCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CDateTimeCtrl::CloseMonthCal](#closemonthcal)|Closes the current date and time picker control.| -|[CDateTimeCtrl::Create](#create)|Creates the date and time picker control and attaches it to the `CDateTimeCtrl` object.| -|[CDateTimeCtrl::GetDateTimePickerInfo](#getdatetimepickerinfo)|Retrieves information about the current date and time picker control.| -|[CDateTimeCtrl::GetIdealSize](#getidealsize)|Returns the ideal size of the date and time picker control that is required to display the current date or time.| -|[CDateTimeCtrl::GetMonthCalColor](#getmonthcalcolor)|Retrieves the color for a given portion of the month calendar within the date and time picker control.| -|[CDateTimeCtrl::GetMonthCalCtrl](#getmonthcalctrl)|Retrieves the `CMonthCalCtrl` object associated with the date and time picker control.| -|[CDateTimeCtrl::GetMonthCalFont](#getmonthcalfont)|Retrieves the font currently used by the date and time picker control's child month calendar control.| -|[CDateTimeCtrl::GetMonthCalStyle](#getmonthcalstyle)|Gets the style of the current date and time picker control.| -|[CDateTimeCtrl::GetRange](#getrange)|Retrieves the current minimum and maximum allowed system times for a date and time picker control.| -|[CDateTimeCtrl::GetTime](#gettime)|Retrieves the currently selected time from a date and time picker control and puts it in a specified `SYSTEMTIME` structure.| -|[CDateTimeCtrl::SetFormat](#setformat)|Sets the display of a date and time picker control in accordance with a given format string.| -|[CDateTimeCtrl::SetMonthCalColor](#setmonthcalcolor)|Sets the color for a given portion of the month calendar within a date and time picker control.| -|[CDateTimeCtrl::SetMonthCalFont](#setmonthcalfont)|Sets the font that the date and time picker control's child month calendar control will use.| -|[CDateTimeCtrl::SetMonthCalStyle](#setmonthcalstyle)|Sets the style of the current date and time picker control.| -|[CDateTimeCtrl::SetRange](#setrange)|Sets the minimum and maximum allowed system times for a date and time picker control.| -|[CDateTimeCtrl::SetTime](#settime)|Sets the time in a date and time picker control.| +|[`CDateTimeCtrl::CloseMonthCal`](#closemonthcal)|Closes the current date and time picker control.| +|[`CDateTimeCtrl::Create`](#create)|Creates the date and time picker control and attaches it to the `CDateTimeCtrl` object.| +|[`CDateTimeCtrl::GetDateTimePickerInfo`](#getdatetimepickerinfo)|Retrieves information about the current date and time picker control.| +|[`CDateTimeCtrl::GetIdealSize`](#getidealsize)|Returns the ideal size of the date and time picker control that is required to display the current date or time.| +|[`CDateTimeCtrl::GetMonthCalColor`](#getmonthcalcolor)|Retrieves the color for a given portion of the month calendar within the date and time picker control.| +|[`CDateTimeCtrl::GetMonthCalCtrl`](#getmonthcalctrl)|Retrieves the `CMonthCalCtrl` object associated with the date and time picker control.| +|[`CDateTimeCtrl::GetMonthCalFont`](#getmonthcalfont)|Retrieves the font currently used by the date and time picker control's child month calendar control.| +|[`CDateTimeCtrl::GetMonthCalStyle`](#getmonthcalstyle)|Gets the style of the current date and time picker control.| +|[`CDateTimeCtrl::GetRange`](#getrange)|Retrieves the current minimum and maximum allowed system times for a date and time picker control.| +|[`CDateTimeCtrl::GetTime`](#gettime)|Retrieves the currently selected time from a date and time picker control and puts it in a specified `SYSTEMTIME` structure.| +|[`CDateTimeCtrl::SetFormat`](#setformat)|Sets the display of a date and time picker control in accordance with a given format string.| +|[`CDateTimeCtrl::SetMonthCalColor`](#setmonthcalcolor)|Sets the color for a given portion of the month calendar within a date and time picker control.| +|[`CDateTimeCtrl::SetMonthCalFont`](#setmonthcalfont)|Sets the font that the date and time picker control's child month calendar control will use.| +|[`CDateTimeCtrl::SetMonthCalStyle`](#setmonthcalstyle)|Sets the style of the current date and time picker control.| +|[`CDateTimeCtrl::SetRange`](#setrange)|Sets the minimum and maximum allowed system times for a date and time picker control.| +|[`CDateTimeCtrl::SetTime`](#settime)|Sets the time in a date and time picker control.| ## Remarks @@ -51,23 +50,23 @@ The date and time picker control (DTP control) provides a simple interface to ex You can customize the date and time picker control by applying a variety of styles to the object when you create it. See [Date and Time Picker Control Styles](/windows/win32/Controls/date-and-time-picker-control-styles) in the Windows SDK for more information about styles specific to the date and time picker control. You can set the display format of the DTP control using format styles. These format styles are described under "Format Styles" in the Windows SDK topic [Date and Time Picker Control Styles](/windows/win32/Controls/date-and-time-picker-control-styles). -The date and time picker control also uses notifications and callbacks, which are described in [Using CDateTimeCtrl](../../mfc/using-cdatetimectrl.md). +The date and time picker control also uses notifications and callbacks, which are described in [Using `CDateTimeCtrl`](../../mfc/using-cdatetimectrl.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CDateTimeCtrl` ## Requirements -**Header:** afxdtctl.h +**Header:** `afxdtctl.h` -## CDateTimeCtrl::CDateTimeCtrl +## `CDateTimeCtrl::CDateTimeCtrl` Constructs a `CDateTimeCtrl` object. @@ -75,7 +74,7 @@ Constructs a `CDateTimeCtrl` object. CDateTimeCtrl(); ``` -## CDateTimeCtrl::CloseMonthCal +## `CDateTimeCtrl::CloseMonthCal` Closes the current date and time picker control. @@ -85,7 +84,7 @@ void CloseMonthCal() const; ### Remarks -This method sends the [DTM_CLOSEMONTHCAL](/windows/win32/Controls/dtm-closemonthcal) message, which is described in the Windows SDK. +This method sends the [`DTM_CLOSEMONTHCAL`](/windows/win32/Controls/dtm-closemonthcal) message, which is described in the Windows SDK. ### Example @@ -97,7 +96,7 @@ The next code example closes the drop-down calendar for the current date and tim [!code-cpp[NVC_MFC_CDateTimeCtrl_s1#5](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_2.cpp)] -## CDateTimeCtrl::Create +## `CDateTimeCtrl::Create` Creates the date and time picker control and attaches it to the `CDateTimeCtrl` object. @@ -111,16 +110,16 @@ virtual BOOL Create( ### Parameters -*dwStyle*
+*`dwStyle`*\ Specifies the combination of date time control styles. See [Date and Time Picker Control Styles](/windows/win32/Controls/date-and-time-picker-control-styles) in the Windows SDK for more information about date and time picker styles. -*rect*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure, which is the position and size of the date and time picker control. +*`rect`*\ +A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure, which is the position and size of the date and time picker control. -*pParentWnd*
-A pointer to a [CWnd](../../mfc/reference/cwnd-class.md) object that is the parent window of the date and time picker control. It must not be NULL. +*`pParentWnd`*\ +A pointer to a [`CWnd`](../../mfc/reference/cwnd-class.md) object that is the parent window of the date and time picker control. It must not be `NULL`. -*nID*
+*`nID`*\ Specifies the date and time picker control's control ID. ### Return Value @@ -131,7 +130,7 @@ Nonzero if creation was successful; otherwise 0. ##### To create a date and time picker control -1. Call [CDateTimeCtrl](#cdatetimectrl) to construct a `CDateTimeCtrl` object. +1. Call [`CDateTimeCtrl`](#cdatetimectrl) to construct a `CDateTimeCtrl` object. 1. Call this member function, which creates the Windows date and time picker control and attaches it to the `CDateTimeCtrl` object. @@ -141,7 +140,7 @@ When you call `Create`, the common controls are initialized. [!code-cpp[NVC_MFC_CDateTimeCtrl#1](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_3.cpp)] -## CDateTimeCtrl::GetDateTimePickerInfo +## `CDateTimeCtrl::GetDateTimePickerInfo` Retrieves information about the current date and time picker control. @@ -151,16 +150,16 @@ BOOL GetDateTimePickerInfo(LPDATETIMEPICKERINFO pDateTimePickerInfo) const; ### Parameters -*pDateTimePickerInfo*\ -[out] A pointer to a [DATETIMEPICKERINFO](/windows/win32/api/commctrl/ns-commctrl-datetimepickerinfo) structure that receives a description of the current date and time picker control. The caller is responsible for allocating this structure. However, this method initializes the *cbSize* member of the structure. +*`pDateTimePickerInfo`*\ +[out] A pointer to a [`DATETIMEPICKERINFO`](/windows/win32/api/commctrl/ns-commctrl-datetimepickerinfo) structure that receives a description of the current date and time picker control. The caller is responsible for allocating this structure. However, this method initializes the *`cbSize`* member of the structure. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks -This method sends the [DTM_GETDATETIMEPICKERINFO](/windows/win32/Controls/dtm-getdatetimepickerinfo) message, which is described in the Windows SDK. +This method sends the [`DTM_GETDATETIMEPICKERINFO`](/windows/win32/Controls/dtm-getdatetimepickerinfo) message, which is described in the Windows SDK. ### Example @@ -172,7 +171,7 @@ The next code example indicates whether it successfully retrieves information ab [!code-cpp[NVC_MFC_CDateTimeCtrl_s1#4](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_4.cpp)] -## CDateTimeCtrl::GetMonthCalColor +## `CDateTimeCtrl::GetMonthCalColor` Retrieves the color for a given portion of the month calendar within the date and time picker control. @@ -182,22 +181,22 @@ COLORREF GetMonthCalColor(int iColor) const; ### Parameters -*iColor*
-An **`int`** value specifying which color area of the month calendar to retrieve. For a list of values, see the *iColor* parameter for [SetMonthCalColor](#setmonthcalcolor). +*`iColor`*\ +An **`int`** value specifying which color area of the month calendar to retrieve. For a list of values, see the *`iColor`* parameter for [`SetMonthCalColor`](#setmonthcalcolor). ### Return Value -A COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. The function returns -1 if unsuccessful. +A `COLORREF` value that represents the color setting for the specified portion of the month calendar control if successful. The function returns -1 if unsuccessful. ### Remarks -This member function implements the behavior of the Win32 message [DTM_GETMCCOLOR](/windows/win32/Controls/dtm-getmccolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`DTM_GETMCCOLOR`](/windows/win32/Controls/dtm-getmccolor), as described in the Windows SDK. ### Example [!code-cpp[NVC_MFC_CDateTimeCtrl#2](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_5.cpp)] -## CDateTimeCtrl::GetMonthCalCtrl +## `CDateTimeCtrl::GetMonthCalCtrl` Retrieves the `CMonthCalCtrl` object associated with the date and time picker control. @@ -207,17 +206,17 @@ CMonthCalCtrl* GetMonthCalCtrl() const; ### Return Value -A pointer to a [CMonthCalCtrl](../../mfc/reference/cmonthcalctrl-class.md) object, or NULL if unsuccessful or if the window is not visible. +A pointer to a [`CMonthCalCtrl`](../../mfc/reference/cmonthcalctrl-class.md) object, or `NULL` if unsuccessful or if the window isn't visible. ### Remarks -Date and time picker controls create a child month calendar control when the user clicks the drop-down arrow. When the `CMonthCalCtrl` object is no longer needed, it is destroyed, so your application must not rely on storing the object representing the date time picker control's child month calendar. +Date and time picker controls create a child month calendar control when the user selects the drop-down arrow. When the `CMonthCalCtrl` object is no longer needed, it's destroyed, so your application must not rely on storing the object representing the date time picker control's child month calendar. ### Example [!code-cpp[NVC_MFC_CDateTimeCtrl#3](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_6.cpp)] -## CDateTimeCtrl::GetMonthCalFont +## `CDateTimeCtrl::GetMonthCalFont` Gets the font currently used by the date and time picker control's month calendar control. @@ -227,13 +226,13 @@ CFont* GetMonthCalFont() const; ### Return Value -A pointer to a [CFont](../../mfc/reference/cfont-class.md) object, or NULL if unsuccessful. +A pointer to a [`CFont`](../../mfc/reference/cfont-class.md) object, or `NULL` if unsuccessful. ### Remarks The `CFont` object pointed to by the return value is a temporary object and is destroyed during the next idle processing time. -## CDateTimeCtrl::GetMonthCalStyle +## `CDateTimeCtrl::GetMonthCalStyle` Gets the style of the drop-down month calendar control that is associated with the current date and time picker control. @@ -247,9 +246,9 @@ The style of the drop-down month calendar control, which is a bitwise combinatio ### Remarks -This method sends the [DTM_GETMCSTYLE](/windows/win32/Controls/dtm-getmcstyle) message, which is described in the Windows SDK. +This method sends the [`DTM_GETMCSTYLE`](/windows/win32/Controls/dtm-getmcstyle) message, which is described in the Windows SDK. -## CDateTimeCtrl::GetRange +## `CDateTimeCtrl::GetRange` Retrieves the current minimum and maximum allowed system times for a date and time picker control. @@ -265,15 +264,15 @@ DWORD GetRange( ### Parameters -*pMinRange*
-A pointer to a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) object or a [CTime](../../atl-mfc-shared/reference/ctime-class.md) object containing the earliest time allowed in the `CDateTimeCtrl` object. +*`pMinRange`*\ +A pointer to a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) object or a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) object containing the earliest time allowed in the `CDateTimeCtrl` object. -*pMaxRange*
+*`pMaxRange`*\ A pointer to a `COleDateTime` object or a `CTime` object containing the latest time allowed in the `CDateTimeCtrl` object. ### Return Value -A DWORD value containing flags that indicate which ranges are set. If +A `DWORD` value containing flags that indicate which ranges are set. If `return value & GDTR_MAX` == 0 @@ -285,13 +284,13 @@ then the first parameter is valid. ### Remarks -This member function implements the behavior of the Win32 message [DTM_GETRANGE](/windows/win32/Controls/dtm-getrange), as described in the Windows SDK. In MFC's implementation, you can specify either `COleDateTime` or `CTime` usages. +This member function implements the behavior of the Win32 message [`DTM_GETRANGE`](/windows/win32/Controls/dtm-getrange), as described in the Windows SDK. In MFC's implementation, you can specify either `COleDateTime` or `CTime` usages. ### Example [!code-cpp[NVC_MFC_CDateTimeCtrl#4](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_7.cpp)] -## CDateTimeCtrl::GetTime +## `CDateTimeCtrl::GetTime` Retrieves the currently selected time from a date and time picker control and puts it in a specified `SYSTEMTIME` structure. @@ -303,27 +302,27 @@ DWORD GetTime(LPSYSTEMTIME pTimeDest) const; ### Parameters -*timeDest*
-In the first version, a reference to a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) object that will receive the system time information. In the second version, a reference to a [CTime](../../atl-mfc-shared/reference/ctime-class.md) object that will receive the system time information. +*`timeDest`*\ +In the first version, a reference to a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) object that will receive the system time information. In the second version, a reference to a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) object that will receive the system time information. -*pTimeDest*
-A pointer to the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure to receive the system time information. Must not be NULL. +*`pTimeDest`*\ +A pointer to the [`SYSTEMTIME`](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure to receive the system time information. Must not be `NULL`. ### Return Value -In the first version, nonzero if the time is successfully written to the `COleDateTime` object; otherwise 0. In the second and third versions, a DWORD value equal to the *dwFlag* member set in the [NMDATETIMECHANGE](/windows/win32/api/commctrl/ns-commctrl-nmdatetimechange) structure. See the **Remarks** section below for more information. +In the first version, nonzero if the time is successfully written to the `COleDateTime` object; otherwise 0. In the second and third versions, a `DWORD` value equal to the *`dwFlag`* member set in the [`NMDATETIMECHANGE`](/windows/win32/api/commctrl/ns-commctrl-nmdatetimechange) structure. See the [**Remarks**](#gettime-remarks) section below for more information. -### Remarks +### Remarks -This member function implements the behavior of the Win32 message [DTM_GETSYSTEMTIME](/windows/win32/Controls/dtm-getsystemtime), as described in the Windows SDK. In the MFC implementation of `GetTime`, you can use `COleDateTime` or `CTime` classes, or you can use a `SYSTEMTIME` structure, to store the time information. +This member function implements the behavior of the Win32 message [`DTM_GETSYSTEMTIME`](/windows/win32/Controls/dtm-getsystemtime), as described in the Windows SDK. In the MFC implementation of `GetTime`, you can use `COleDateTime` or `CTime` classes, or you can use a `SYSTEMTIME` structure, to store the time information. -The return value DWORD in the second and third versions, above, indicates whether or not the date and time picker control is set to the "no date" status, as indicated in the [NMDATETIMECHANGE](/windows/win32/api/commctrl/ns-commctrl-nmdatetimechange) structure member *dwFlags*. If the value returned equals GDT_NONE, the control is set to "no date" status, and uses the DTS_SHOWNONE style. If the value returned equals GDT_VALID, the system time is successfully stored in the destination location. +The return value `DWORD` in the second and third versions, above, indicates whether or not the date and time picker control is set to the "no date" status, as indicated in the [`NMDATETIMECHANGE`](/windows/win32/api/commctrl/ns-commctrl-nmdatetimechange) structure member *`dwFlags`*. If the value returned equals `GDT_NONE`, the control is set to "no date" status, and uses the `DTS_SHOWNONE` style. If the value returned equals `GDT_VALID`, the system time is successfully stored in the destination location. ### Example [!code-cpp[NVC_MFC_CDateTimeCtrl#5](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_8.cpp)] -## CDateTimeCtrl::GetIdealSize +## `CDateTimeCtrl::GetIdealSize` Returns the ideal size of the date and time picker control that is required to display the current date or time. @@ -333,16 +332,16 @@ BOOL GetIdealSize(LPSIZE psize) const; ### Parameters -*psize*\ -[out] Pointer to a [SIZE](/windows/win32/api/windef/ns-windef-size) structure that contains the ideal size for the control. +*`psize`*\ +[out] Pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that contains the ideal size for the control. ### Return Value -The return value is always TRUE. +The return value is always `TRUE`. ### Remarks -This method sends the [DTM_GETIDEALSIZE](/windows/win32/Controls/dtm-getidealsize) message, which is described in the Windows SDK. +This method sends the [`DTM_GETIDEALSIZE`](/windows/win32/Controls/dtm-getidealsize) message, which is described in the Windows SDK. ### Example @@ -354,7 +353,7 @@ The next code example retrieves the ideal size to display the date and time pick [!code-cpp[NVC_MFC_CDateTimeCtrl_s1#2](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_9.cpp)] -## CDateTimeCtrl::SetFormat +## `CDateTimeCtrl::SetFormat` Sets the display of a date and time picker control in accordance with a given format string. @@ -364,8 +363,8 @@ BOOL SetFormat(LPCTSTR pstrFormat); ### Parameters -*pstrFormat*
-A pointer to a zero-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style. +*`pstrFormat`*\ +A pointer to a zero-terminated format string that defines the desired display. Setting this parameter to `NULL` will reset the control to the default format string for the current style. ### Return Value @@ -376,13 +375,13 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [DTM_SETFORMAT](/windows/win32/Controls/dtm-setformat), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`DTM_SETFORMAT`](/windows/win32/Controls/dtm-setformat), as described in the Windows SDK. ### Example [!code-cpp[NVC_MFC_CDateTimeCtrl#6](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_10.cpp)] -## CDateTimeCtrl::SetMonthCalColor +## `CDateTimeCtrl::SetMonthCalColor` Sets the color for a given portion of the month calendar within a date and time picker control. @@ -394,34 +393,34 @@ COLORREF SetMonthCalColor( ### Parameters -*iColor*
+*`iColor`*\ **`int`** value specifying which area of the month calendar control to set. This value can be one of the following. |Value|Meaning| |-----------|-------------| -|MCSC_BACKGROUND|Set the background color displayed between months.| -|MCSC_MONTHBK|Set the background color displayed within a month.| -|MCSC_TEXT|Set the color used to display text within a month.| -|MCSC_TITLEBK|Set the background color displayed in the calendar's title.| -|MCSC_TITLETEXT|Set the color used to display text within the calendar's title.| -|MCSC_TRAILINGTEXT|Set the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.| +|`MCSC_BACKGROUND`|Set the background color displayed between months.| +|`MCSC_MONTHBK`|Set the background color displayed within a month.| +|`MCSC_TEXT`|Set the color used to display text within a month.| +|`MCSC_TITLEBK`|Set the background color displayed in the calendar's title.| +|`MCSC_TITLETEXT`|Set the color used to display text within the calendar's title.| +|`MCSC_TRAILINGTEXT`|Set the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.| -*ref*
-A COLORREF value representing the color that will be set for the specified area of the month calendar. +*`ref`*\ +A `COLORREF` value representing the color that will be set for the specified area of the month calendar. ### Return Value -A COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the message returns -1. +A `COLORREF` value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the message returns -1. ### Remarks -This member function implements the behavior of the Win32 message [DTM_SETMCCOLOR](/windows/win32/Controls/dtm-setmccolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`DTM_SETMCCOLOR`](/windows/win32/Controls/dtm-setmccolor), as described in the Windows SDK. ### Example See the example for [CDateTimeCtrl::GetMonthCalColor](#getmonthcalcolor). -## CDateTimeCtrl::SetMonthCalFont +## `CDateTimeCtrl::SetMonthCalFont` Sets the font that the date and time picker control's child month calendar control will use. @@ -433,15 +432,15 @@ void SetMonthCalFont( ### Parameters -*hFont*
+*`hFont`*\ Handle to the font that will be set. -*bRedraw*
-Specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to TRUE causes the control to redraw itself. +*`bRedraw`*\ +Specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to `TRUE` causes the control to redraw itself. ### Remarks -This member function implements the behavior of the Win32 message [DTM_SETMCFONT](/windows/win32/Controls/dtm-setmcfont), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`DTM_SETMCFONT`](/windows/win32/Controls/dtm-setmcfont), as described in the Windows SDK. ### Example @@ -450,7 +449,7 @@ This member function implements the behavior of the Win32 message [DTM_SETMCFONT > [!NOTE] > If you use this code, you'll want to make a member of your `CDialog`-derived class called *m_MonthFont* of type `CFont`. -## CDateTimeCtrl::SetMonthCalStyle +## `CDateTimeCtrl::SetMonthCalStyle` Sets the style of the drop-down month calendar control that is associated with the current date and time picker control. @@ -460,7 +459,7 @@ DWORD SetMonthCalStyle(DWORD dwStyle); ### Parameters -*dwStyle*\ +*`dwStyle`*\ [in] A new month calendar control style, which is a bitwise combination (OR) of month calendar control styles. For more information, see [Month Calendar Control Styles](/windows/win32/Controls/month-calendar-control-styles). ### Return Value @@ -469,7 +468,7 @@ The previous style of the drop-down month calendar control. ### Remarks -This method sends the [DTM_SETMCSTYLE](/windows/win32/Controls/dtm-setmcstyle) message, which is described in the Windows SDK. +This method sends the [`DTM_SETMCSTYLE`](/windows/win32/Controls/dtm-setmcstyle) message, which is described in the Windows SDK. ### Example @@ -481,7 +480,7 @@ The next code example sets the date and time picker control to display week numb [!code-cpp[NVC_MFC_CDateTimeCtrl_s1#3](../../mfc/reference/codesnippet/cpp/cdatetimectrl-class_12.cpp)] -## CDateTimeCtrl::SetRange +## `CDateTimeCtrl::SetRange` Sets the minimum and maximum allowed system times for a date and time picker control. @@ -497,10 +496,10 @@ BOOL SetRange( ### Parameters -*pMinRange*
-A pointer to a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) object or a [CTime](../../atl-mfc-shared/reference/ctime-class.md) object containing the earliest time allowed in the `CDateTimeCtrl` object. +*`pMinRange`*\ +A pointer to a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) object or a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) object containing the earliest time allowed in the `CDateTimeCtrl` object. -*pMaxRange*
+*`pMaxRange`*\ A pointer to a `COleDateTime` object or a `CTime` object containing the latest time allowed in the `CDateTimeCtrl` object. ### Return Value @@ -509,13 +508,13 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [DTM_SETRANGE](/windows/win32/Controls/dtm-setrange), as described in the Windows SDK. In MFC's implementation, you can specify either `COleDateTime` or `CTime` usages. If the `COleDateTime` object has a NULL status, the range will be removed. If the `CTime` pointer or the `COleDateTime` pointer is NULL, the range will be removed. +This member function implements the behavior of the Win32 message [`DTM_SETRANGE`](/windows/win32/Controls/dtm-setrange), as described in the Windows SDK. In MFC's implementation, you can specify either `COleDateTime` or `CTime` usages. If the `COleDateTime` object has a `NULL` status, the range will be removed. If the `CTime` pointer or the `COleDateTime` pointer is `NULL`, the range will be removed. ### Example - See the example for [CDateTimeCtrl::GetRange](#getrange). + See the example for [`CDateTimeCtrl::GetRange`](#getrange). -## CDateTimeCtrl::SetTime +## `CDateTimeCtrl::SetTime` Sets the time in a date and time picker control. @@ -527,11 +526,11 @@ BOOL SetTime(LPSYSTEMTIME pTimeNew = NULL); ### Parameters -*timeNew*
-A reference to a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) object containing the to which the control will be set. +*`timeNew`*\ +A reference to a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) object containing the to which the control will be set. -*pTimeNew*
-In the second version above, a pointer to a [CTime](../../atl-mfc-shared/reference/ctime-class.md) object containing the time to which the control will be set. In the third version above, a pointer to a [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure containing the time to which the control will be set. +*`pTimeNew`*\ +In the second version above, a pointer to a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) object containing the time to which the control will be set. In the third version above, a pointer to a [`SYSTEMTIME`](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure containing the time to which the control will be set. ### Return Value @@ -539,7 +538,7 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [DTM_SETSYSTEMTIME](/windows/win32/Controls/dtm-setsystemtime), as described in the Windows SDK. In the MFC implementation of `SetTime`, you can use the `COleDateTime` or `CTime` classes, or you can use a `SYSTEMTIME` structure, to set the time information. +This member function implements the behavior of the Win32 message [`DTM_SETSYSTEMTIME`](/windows/win32/Controls/dtm-setsystemtime), as described in the Windows SDK. In the MFC implementation of `SetTime`, you can use the `COleDateTime` or `CTime` classes, or you can use a `SYSTEMTIME` structure, to set the time information. ### Example @@ -547,7 +546,7 @@ This member function implements the behavior of the Win32 message [DTM_SETSYSTEM ## See also -[MFC Sample CMNCTRL1](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CMonthCalCtrl Class](../../mfc/reference/cmonthcalctrl-class.md) +[MFC Sample `CMNCTRL1`](../../overview/visual-cpp-samples.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CMonthCalCtrl` Class](../../mfc/reference/cmonthcalctrl-class.md) diff --git a/docs/mfc/reference/cdc-class.md b/docs/mfc/reference/cdc-class.md index 01cc0d8355..f40795d15e 100644 --- a/docs/mfc/reference/cdc-class.md +++ b/docs/mfc/reference/cdc-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CDC Class" title: "CDC Class" +description: "Learn more about: CDC Class" ms.date: "11/19/2018" f1_keywords: ["CDC", "AFXWIN/CDC", "AFXWIN/CDC::CDC", "AFXWIN/CDC::AbortDoc", "AFXWIN/CDC::AbortPath", "AFXWIN/CDC::AddMetaFileComment", "AFXWIN/CDC::AlphaBlend", "AFXWIN/CDC::AngleArc", "AFXWIN/CDC::Arc", "AFXWIN/CDC::ArcTo", "AFXWIN/CDC::Attach", "AFXWIN/CDC::BeginPath", "AFXWIN/CDC::BitBlt", "AFXWIN/CDC::Chord", "AFXWIN/CDC::CloseFigure", "AFXWIN/CDC::CreateCompatibleDC", "AFXWIN/CDC::CreateDC", "AFXWIN/CDC::CreateIC", "AFXWIN/CDC::DeleteDC", "AFXWIN/CDC::DeleteTempMap", "AFXWIN/CDC::Detach", "AFXWIN/CDC::DPtoHIMETRIC", "AFXWIN/CDC::DPtoLP", "AFXWIN/CDC::Draw3dRect", "AFXWIN/CDC::DrawDragRect", "AFXWIN/CDC::DrawEdge", "AFXWIN/CDC::DrawEscape", "AFXWIN/CDC::DrawFocusRect", "AFXWIN/CDC::DrawFrameControl", "AFXWIN/CDC::DrawIcon", "AFXWIN/CDC::DrawState", "AFXWIN/CDC::DrawText", "AFXWIN/CDC::DrawTextEx", "AFXWIN/CDC::Ellipse", "AFXWIN/CDC::EndDoc", "AFXWIN/CDC::EndPage", "AFXWIN/CDC::EndPath", "AFXWIN/CDC::EnumObjects", "AFXWIN/CDC::Escape", "AFXWIN/CDC::ExcludeClipRect", "AFXWIN/CDC::ExcludeUpdateRgn", "AFXWIN/CDC::ExtFloodFill", "AFXWIN/CDC::ExtTextOut", "AFXWIN/CDC::FillPath", "AFXWIN/CDC::FillRect", "AFXWIN/CDC::FillRgn", "AFXWIN/CDC::FillSolidRect", "AFXWIN/CDC::FlattenPath", "AFXWIN/CDC::FloodFill", "AFXWIN/CDC::FrameRect", "AFXWIN/CDC::FrameRgn", "AFXWIN/CDC::FromHandle", "AFXWIN/CDC::GetArcDirection", "AFXWIN/CDC::GetAspectRatioFilter", "AFXWIN/CDC::GetBkColor", "AFXWIN/CDC::GetBkMode", "AFXWIN/CDC::GetBoundsRect", "AFXWIN/CDC::GetBrushOrg", "AFXWIN/CDC::GetCharABCWidths", "AFXWIN/CDC::GetCharABCWidthsI", "AFXWIN/CDC::GetCharacterPlacement", "AFXWIN/CDC::GetCharWidth", "AFXWIN/CDC::GetCharWidthI", "AFXWIN/CDC::GetClipBox", "AFXWIN/CDC::GetColorAdjustment", "AFXWIN/CDC::GetCurrentBitmap", "AFXWIN/CDC::GetCurrentBrush", "AFXWIN/CDC::GetCurrentFont", "AFXWIN/CDC::GetCurrentPalette", "AFXWIN/CDC::GetCurrentPen", "AFXWIN/CDC::GetCurrentPosition", "AFXWIN/CDC::GetDCBrushColor", "AFXWIN/CDC::GetDCPenColor", "AFXWIN/CDC::GetDeviceCaps", "AFXWIN/CDC::GetFontData", "AFXWIN/CDC::GetFontLanguageInfo", "AFXWIN/CDC::GetGlyphOutline", "AFXWIN/CDC::GetGraphicsMode", "AFXWIN/CDC::GetHalftoneBrush", "AFXWIN/CDC::GetKerningPairs", "AFXWIN/CDC::GetLayout", "AFXWIN/CDC::GetMapMode", "AFXWIN/CDC::GetMiterLimit", "AFXWIN/CDC::GetNearestColor", "AFXWIN/CDC::GetOutlineTextMetrics", "AFXWIN/CDC::GetOutputCharWidth", "AFXWIN/CDC::GetOutputTabbedTextExtent", "AFXWIN/CDC::GetOutputTextExtent", "AFXWIN/CDC::GetOutputTextMetrics", "AFXWIN/CDC::GetPath", "AFXWIN/CDC::GetPixel", "AFXWIN/CDC::GetPolyFillMode", "AFXWIN/CDC::GetROP2", "AFXWIN/CDC::GetSafeHdc", "AFXWIN/CDC::GetStretchBltMode", "AFXWIN/CDC::GetTabbedTextExtent", "AFXWIN/CDC::GetTextAlign", "AFXWIN/CDC::GetTextCharacterExtra", "AFXWIN/CDC::GetTextColor", "AFXWIN/CDC::GetTextExtent", "AFXWIN/CDC::GetTextExtentExPointI", "AFXWIN/CDC::GetTextExtentPointI", "AFXWIN/CDC::GetTextFace", "AFXWIN/CDC::GetTextMetrics", "AFXWIN/CDC::GetViewportExt", "AFXWIN/CDC::GetViewportOrg", "AFXWIN/CDC::GetWindow", "AFXWIN/CDC::GetWindowExt", "AFXWIN/CDC::GetWindowOrg", "AFXWIN/CDC::GetWorldTransform", "AFXWIN/CDC::GradientFill", "AFXWIN/CDC::GrayString", "AFXWIN/CDC::HIMETRICtoDP", "AFXWIN/CDC::HIMETRICtoLP", "AFXWIN/CDC::IntersectClipRect", "AFXWIN/CDC::InvertRect", "AFXWIN/CDC::InvertRgn", "AFXWIN/CDC::IsPrinting", "AFXWIN/CDC::LineTo", "AFXWIN/CDC::LPtoDP", "AFXWIN/CDC::LPtoHIMETRIC", "AFXWIN/CDC::MaskBlt", "AFXWIN/CDC::ModifyWorldTransform", "AFXWIN/CDC::MoveTo", "AFXWIN/CDC::OffsetClipRgn", "AFXWIN/CDC::OffsetViewportOrg", "AFXWIN/CDC::OffsetWindowOrg", "AFXWIN/CDC::PaintRgn", "AFXWIN/CDC::PatBlt", "AFXWIN/CDC::Pie", "AFXWIN/CDC::PlayMetaFile", "AFXWIN/CDC::PlgBlt", "AFXWIN/CDC::PolyBezier", "AFXWIN/CDC::PolyBezierTo", "AFXWIN/CDC::PolyDraw", "AFXWIN/CDC::Polygon", "AFXWIN/CDC::Polyline", "AFXWIN/CDC::PolylineTo", "AFXWIN/CDC::PolyPolygon", "AFXWIN/CDC::PolyPolyline", "AFXWIN/CDC::PtVisible", "AFXWIN/CDC::RealizePalette", "AFXWIN/CDC::Rectangle", "AFXWIN/CDC::RectVisible", "AFXWIN/CDC::ReleaseAttribDC", "AFXWIN/CDC::ReleaseOutputDC", "AFXWIN/CDC::ResetDC", "AFXWIN/CDC::RestoreDC", "AFXWIN/CDC::RoundRect", "AFXWIN/CDC::SaveDC", "AFXWIN/CDC::ScaleViewportExt", "AFXWIN/CDC::ScaleWindowExt", "AFXWIN/CDC::ScrollDC", "AFXWIN/CDC::SelectClipPath", "AFXWIN/CDC::SelectClipRgn", "AFXWIN/CDC::SelectObject", "AFXWIN/CDC::SelectPalette", "AFXWIN/CDC::SelectStockObject", "AFXWIN/CDC::SetAbortProc", "AFXWIN/CDC::SetArcDirection", "AFXWIN/CDC::SetAttribDC", "AFXWIN/CDC::SetBkColor", "AFXWIN/CDC::SetBkMode", "AFXWIN/CDC::SetBoundsRect", "AFXWIN/CDC::SetBrushOrg", "AFXWIN/CDC::SetColorAdjustment", "AFXWIN/CDC::SetDCBrushColor", "AFXWIN/CDC::SetDCPenColor", "AFXWIN/CDC::SetGraphicsMode", "AFXWIN/CDC::SetLayout", "AFXWIN/CDC::SetMapMode", "AFXWIN/CDC::SetMapperFlags", "AFXWIN/CDC::SetMiterLimit", "AFXWIN/CDC::SetOutputDC", "AFXWIN/CDC::SetPixel", "AFXWIN/CDC::SetPixelV", "AFXWIN/CDC::SetPolyFillMode", "AFXWIN/CDC::SetROP2", "AFXWIN/CDC::SetStretchBltMode", "AFXWIN/CDC::SetTextAlign", "AFXWIN/CDC::SetTextCharacterExtra", "AFXWIN/CDC::SetTextColor", "AFXWIN/CDC::SetTextJustification", "AFXWIN/CDC::SetViewportExt", "AFXWIN/CDC::SetViewportOrg", "AFXWIN/CDC::SetWindowExt", "AFXWIN/CDC::SetWindowOrg", "AFXWIN/CDC::SetWorldTransform", "AFXWIN/CDC::StartDoc", "AFXWIN/CDC::StartPage", "AFXWIN/CDC::StretchBlt", "AFXWIN/CDC::StrokeAndFillPath", "AFXWIN/CDC::StrokePath", "AFXWIN/CDC::TabbedTextOut", "AFXWIN/CDC::TextOut", "AFXWIN/CDC::TransparentBlt", "AFXWIN/CDC::UpdateColors", "AFXWIN/CDC::WidenPath", "AFXWIN/CDC::m_hAttribDC", "AFXWIN/CDC::m_hDC"] helpviewer_keywords: ["CDC [MFC], CDC", "CDC [MFC], AbortDoc", "CDC [MFC], AbortPath", "CDC [MFC], AddMetaFileComment", "CDC [MFC], AlphaBlend", "CDC [MFC], AngleArc", "CDC [MFC], Arc", "CDC [MFC], ArcTo", "CDC [MFC], Attach", "CDC [MFC], BeginPath", "CDC [MFC], BitBlt", "CDC [MFC], Chord", "CDC [MFC], CloseFigure", "CDC [MFC], CreateCompatibleDC", "CDC [MFC], CreateDC", "CDC [MFC], CreateIC", "CDC [MFC], DeleteDC", "CDC [MFC], DeleteTempMap", "CDC [MFC], Detach", "CDC [MFC], DPtoHIMETRIC", "CDC [MFC], DPtoLP", "CDC [MFC], Draw3dRect", "CDC [MFC], DrawDragRect", "CDC [MFC], DrawEdge", "CDC [MFC], DrawEscape", "CDC [MFC], DrawFocusRect", "CDC [MFC], DrawFrameControl", "CDC [MFC], DrawIcon", "CDC [MFC], DrawState", "CDC [MFC], DrawText", "CDC [MFC], DrawTextEx", "CDC [MFC], Ellipse", "CDC [MFC], EndDoc", "CDC [MFC], EndPage", "CDC [MFC], EndPath", "CDC [MFC], EnumObjects", "CDC [MFC], Escape", "CDC [MFC], ExcludeClipRect", "CDC [MFC], ExcludeUpdateRgn", "CDC [MFC], ExtFloodFill", "CDC [MFC], ExtTextOut", "CDC [MFC], FillPath", "CDC [MFC], FillRect", "CDC [MFC], FillRgn", "CDC [MFC], FillSolidRect", "CDC [MFC], FlattenPath", "CDC [MFC], FloodFill", "CDC [MFC], FrameRect", "CDC [MFC], FrameRgn", "CDC [MFC], FromHandle", "CDC [MFC], GetArcDirection", "CDC [MFC], GetAspectRatioFilter", "CDC [MFC], GetBkColor", "CDC [MFC], GetBkMode", "CDC [MFC], GetBoundsRect", "CDC [MFC], GetBrushOrg", "CDC [MFC], GetCharABCWidths", "CDC [MFC], GetCharABCWidthsI", "CDC [MFC], GetCharacterPlacement", "CDC [MFC], GetCharWidth", "CDC [MFC], GetCharWidthI", "CDC [MFC], GetClipBox", "CDC [MFC], GetColorAdjustment", "CDC [MFC], GetCurrentBitmap", "CDC [MFC], GetCurrentBrush", "CDC [MFC], GetCurrentFont", "CDC [MFC], GetCurrentPalette", "CDC [MFC], GetCurrentPen", "CDC [MFC], GetCurrentPosition", "CDC [MFC], GetDCBrushColor", "CDC [MFC], GetDCPenColor", "CDC [MFC], GetDeviceCaps", "CDC [MFC], GetFontData", "CDC [MFC], GetFontLanguageInfo", "CDC [MFC], GetGlyphOutline", "CDC [MFC], GetGraphicsMode", "CDC [MFC], GetHalftoneBrush", "CDC [MFC], GetKerningPairs", "CDC [MFC], GetLayout", "CDC [MFC], GetMapMode", "CDC [MFC], GetMiterLimit", "CDC [MFC], GetNearestColor", "CDC [MFC], GetOutlineTextMetrics", "CDC [MFC], GetOutputCharWidth", "CDC [MFC], GetOutputTabbedTextExtent", "CDC [MFC], GetOutputTextExtent", "CDC [MFC], GetOutputTextMetrics", "CDC [MFC], GetPath", "CDC [MFC], GetPixel", "CDC [MFC], GetPolyFillMode", "CDC [MFC], GetROP2", "CDC [MFC], GetSafeHdc", "CDC [MFC], GetStretchBltMode", "CDC [MFC], GetTabbedTextExtent", "CDC [MFC], GetTextAlign", "CDC [MFC], GetTextCharacterExtra", "CDC [MFC], GetTextColor", "CDC [MFC], GetTextExtent", "CDC [MFC], GetTextExtentExPointI", "CDC [MFC], GetTextExtentPointI", "CDC [MFC], GetTextFace", "CDC [MFC], GetTextMetrics", "CDC [MFC], GetViewportExt", "CDC [MFC], GetViewportOrg", "CDC [MFC], GetWindow", "CDC [MFC], GetWindowExt", "CDC [MFC], GetWindowOrg", "CDC [MFC], GetWorldTransform", "CDC [MFC], GradientFill", "CDC [MFC], GrayString", "CDC [MFC], HIMETRICtoDP", "CDC [MFC], HIMETRICtoLP", "CDC [MFC], IntersectClipRect", "CDC [MFC], InvertRect", "CDC [MFC], InvertRgn", "CDC [MFC], IsPrinting", "CDC [MFC], LineTo", "CDC [MFC], LPtoDP", "CDC [MFC], LPtoHIMETRIC", "CDC [MFC], MaskBlt", "CDC [MFC], ModifyWorldTransform", "CDC [MFC], MoveTo", "CDC [MFC], OffsetClipRgn", "CDC [MFC], OffsetViewportOrg", "CDC [MFC], OffsetWindowOrg", "CDC [MFC], PaintRgn", "CDC [MFC], PatBlt", "CDC [MFC], Pie", "CDC [MFC], PlayMetaFile", "CDC [MFC], PlgBlt", "CDC [MFC], PolyBezier", "CDC [MFC], PolyBezierTo", "CDC [MFC], PolyDraw", "CDC [MFC], Polygon", "CDC [MFC], Polyline", "CDC [MFC], PolylineTo", "CDC [MFC], PolyPolygon", "CDC [MFC], PolyPolyline", "CDC [MFC], PtVisible", "CDC [MFC], RealizePalette", "CDC [MFC], Rectangle", "CDC [MFC], RectVisible", "CDC [MFC], ReleaseAttribDC", "CDC [MFC], ReleaseOutputDC", "CDC [MFC], ResetDC", "CDC [MFC], RestoreDC", "CDC [MFC], RoundRect", "CDC [MFC], SaveDC", "CDC [MFC], ScaleViewportExt", "CDC [MFC], ScaleWindowExt", "CDC [MFC], ScrollDC", "CDC [MFC], SelectClipPath", "CDC [MFC], SelectClipRgn", "CDC [MFC], SelectObject", "CDC [MFC], SelectPalette", "CDC [MFC], SelectStockObject", "CDC [MFC], SetAbortProc", "CDC [MFC], SetArcDirection", "CDC [MFC], SetAttribDC", "CDC [MFC], SetBkColor", "CDC [MFC], SetBkMode", "CDC [MFC], SetBoundsRect", "CDC [MFC], SetBrushOrg", "CDC [MFC], SetColorAdjustment", "CDC [MFC], SetDCBrushColor", "CDC [MFC], SetDCPenColor", "CDC [MFC], SetGraphicsMode", "CDC [MFC], SetLayout", "CDC [MFC], SetMapMode", "CDC [MFC], SetMapperFlags", "CDC [MFC], SetMiterLimit", "CDC [MFC], SetOutputDC", "CDC [MFC], SetPixel", "CDC [MFC], SetPixelV", "CDC [MFC], SetPolyFillMode", "CDC [MFC], SetROP2", "CDC [MFC], SetStretchBltMode", "CDC [MFC], SetTextAlign", "CDC [MFC], SetTextCharacterExtra", "CDC [MFC], SetTextColor", "CDC [MFC], SetTextJustification", "CDC [MFC], SetViewportExt", "CDC [MFC], SetViewportOrg", "CDC [MFC], SetWindowExt", "CDC [MFC], SetWindowOrg", "CDC [MFC], SetWorldTransform", "CDC [MFC], StartDoc", "CDC [MFC], StartPage", "CDC [MFC], StretchBlt", "CDC [MFC], StrokeAndFillPath", "CDC [MFC], StrokePath", "CDC [MFC], TabbedTextOut", "CDC [MFC], TextOut", "CDC [MFC], TransparentBlt", "CDC [MFC], UpdateColors", "CDC [MFC], WidenPath", "CDC [MFC], m_hAttribDC", "CDC [MFC], m_hDC"] -ms.assetid: 715b3334-cb2b-4c9c-8067-02eb7c66c8b2 --- # `CDC` Class @@ -12,7 +11,7 @@ Defines a class of device-context objects. ## Syntax -``` +```cpp class CDC : public CObject ``` @@ -49,21 +48,21 @@ class CDC : public CObject |[`CDC::DPtoHIMETRIC`](#dptohimetric)|Converts device units into `HIMETRIC` units.| |[`CDC::DPtoLP`](#dptolp)|Converts device units into logical units.| |[`CDC::Draw3dRect`](#draw3drect)|Draws a three-dimensional rectangle.| -|[`CDC::DrawDragRect`](#drawdragrect)|Erases and redraws a rectangle as it is dragged.| +|[`CDC::DrawDragRect`](#drawdragrect)|Erases and redraws a rectangle as it's dragged.| |[`CDC::DrawEdge`](#drawedge)|Draws the edges of a rectangle.| -|[`CDC::DrawEscape`](#drawescape)|Accesses drawing capabilities of a video display that are not directly available through the graphics device interface (GDI).| +|[`CDC::DrawEscape`](#drawescape)|Accesses drawing capabilities of a video display that aren't directly available through the graphics device interface (GDI).| |[`CDC::DrawFocusRect`](#drawfocusrect)|Draws a rectangle in the style used to indicate focus.| |[`CDC::DrawFrameControl`](#drawframecontrol)|Draw a frame control.| |[`CDC::DrawIcon`](#drawicon)|Draws an icon.| |[`CDC::DrawState`](#drawstate)|Displays an image and applies a visual effect to indicate a state.| |[`CDC::DrawText`](#drawtext)|Draws formatted text in the specified rectangle.| -|[`CDC::DrawTextEx`](#drawtextex)|Draws formatted text in the specified rectangle using additional formats.| +|[`CDC::DrawTextEx`](#drawtextex)|Draws formatted text in the specified rectangle using other formats.| |[`CDC::Ellipse`](#ellipse)|Draws an ellipse.| |[`CDC::EndDoc`](#enddoc)|Ends a print job started by the `StartDoc` member function.| |[`CDC::EndPage`](#endpage)|Informs the device driver that a page is ending.| |[`CDC::EndPath`](#endpath)|Closes a path bracket and selects the path defined by the bracket into the device context.| |[`CDC::EnumObjects`](#enumobjects)|Enumerates the pens and brushes available in a device context.| -|[`CDC::Escape`](#escape)|Allows applications to access facilities that are not directly available from a particular device through GDI. Also allows access to Windows escape functions. Escape calls made by an application are translated and sent to the device driver.| +|[`CDC::Escape`](#escape)|Allows applications to access facilities that aren't directly available from a particular device through GDI. Also allows access to Windows escape functions. Escape calls made by an application are translated and sent to the device driver.| |[`CDC::ExcludeClipRect`](#excludecliprect)|Creates a new clipping region that consists of the existing clipping region minus the specified rectangle.| |[`CDC::ExcludeUpdateRgn`](#excludeupdatergn)|Prevents drawing within invalid areas of a window by excluding an updated region in the window from a clipping region.| |[`CDC::ExtFloodFill`](#extfloodfill)|Fills an area with the current brush. Provides more flexibility than the [`CDC::FloodFill`](#floodfill) member function.| @@ -76,7 +75,7 @@ class CDC : public CObject |[`CDC::FloodFill`](#floodfill)|Fills an area with the current brush.| |[`CDC::FrameRect`](#framerect)|Draws a border around a rectangle.| |[`CDC::FrameRgn`](#framergn)|Draws a border around a specific region using a brush.| -|[`CDC::FromHandle`](#fromhandle)|Returns a pointer to a `CDC` object when given a handle to a device context. If a `CDC` object is not attached to the handle, a temporary `CDC` object is created and attached.| +|[`CDC::FromHandle`](#fromhandle)|Returns a pointer to a `CDC` object when given a handle to a device context. If a `CDC` object isn't attached to the handle, a temporary `CDC` object is created and attached.| |[`CDC::GetArcDirection`](#getarcdirection)|Returns the current arc direction for the device context.| |[`CDC::GetAspectRatioFilter`](#getaspectratiofilter)|Retrieves the setting for the current aspect-ratio filter.| |[`CDC::GetBkColor`](#getbkcolor)|Retrieves the current background color.| @@ -157,14 +156,14 @@ class CDC : public CObject |[`CDC::Pie`](#pie)|Draws a pie-shaped wedge.| |[`CDC::PlayMetaFile`](#playmetafile)|Plays the contents of the specified metafile on the given device. The enhanced version of `PlayMetaFile` displays the picture stored in the given enhanced-format metafile. The metafile can be played any number of times.| |[`CDC::PlgBlt`](#plgblt)|Performs a bit-block transfer of the bits of color data from the specified rectangle in the source device context to the specified parallelogram in the given device context.| -|[`CDC::PolyBezier`](#polybezier)|Draws one or more Bzier splines. The current position is neither used nor updated.| +|[`CDC::PolyBezier`](#polybezier)|Draws one or more Bzier splines. The current position isn't used or updated.| |[`CDC::PolyBezierTo`](#polybezierto)|Draws one or more Bzier splines, and moves the current position to the ending point of the last Bzier spline.| |[`CDC::PolyDraw`](#polydraw)|Draws a set of line segments and Bzier splines. This function updates the current position.| |[`CDC::Polygon`](#polygon)|Draws a polygon consisting of two or more points (vertices) connected by lines.| |[`CDC::Polyline`](#polyline)|Draws a set of line segments connecting the specified points.| |[`CDC::PolylineTo`](#polylineto)|Draws one or more straight lines and moves the current position to the ending point of the last line.| |[`CDC::PolyPolygon`](#polypolygon)|Creates two or more polygons that are filled using the current polygon-filling mode. The polygons may be disjoint or they may overlap.| -|[`CDC::PolyPolyline`](#polypolyline)|Draws multiple series of connected line segments. The current position is neither used nor updated by this function.| +|[`CDC::PolyPolyline`](#polypolyline)|Draws multiple series of connected line segments. The current position isn't used or updated by this function.| |[`CDC::PtVisible`](#ptvisible)|Specifies whether the given point is within the clipping region.| |[`CDC::RealizePalette`](#realizepalette)|Maps palette entries in the current logical palette to the system palette.| |[`CDC::Rectangle`](#rectangle)|Draws a rectangle using the current pen and fills it using the current brush.| @@ -200,7 +199,7 @@ class CDC : public CObject |[`CDC::SetMiterLimit`](#setmiterlimit)|Sets the limit for the length of miter joins for the device context.| |[`CDC::SetOutputDC`](#setoutputdc)|Sets `m_hDC`, the output device context.| |[`CDC::SetPixel`](#setpixel)|Sets the pixel at the specified point to the closest approximation of the specified color.| -|[`CDC::SetPixelV`](#setpixelv)|Sets the pixel at the specified coordinates to the closest approximation of the specified color. `SetPixelV` is faster than `SetPixel` because it does not need to return the color value of the point actually painted.| +|[`CDC::SetPixelV`](#setpixelv)|Sets the pixel at the specified coordinates to the closest approximation of the specified color. `SetPixelV` is faster than `SetPixel` because it doesn't need to return the color value of the point painted.| |[`CDC::SetPolyFillMode`](#setpolyfillmode)|Sets the polygon-filling mode.| |[`CDC::SetROP2`](#setrop2)|Sets the current drawing mode.| |[`CDC::SetStretchBltMode`](#setstretchbltmode)|Sets the bitmap-stretching mode.| @@ -239,7 +238,7 @@ class CDC : public CObject ## Remarks -The `CDC` object provides member functions for working with a device context, such as a display or printer, as well as members for working with a display context associated with the client area of a window. +The `CDC` object provides member functions for working with a device context, such as a display or printer, and members for working with a display context associated with the client area of a window. Do all drawing through the member functions of a `CDC` object. The class provides member functions for device-context operations, working with drawing tools, type-safe graphics device interface (GDI) object selection, and working with colors and palettes. It also provides member functions for getting and setting drawing attributes, mapping, working with the viewport, working with the window extent, converting coordinates, working with regions, clipping, drawing lines, and drawing simple shapes, ellipses, and polygons. Member functions are also provided for drawing text, working with fonts, using printer escapes, scrolling, and playing metafiles. @@ -250,7 +249,7 @@ To use a `CDC` object, construct it, and then call its member functions that par For specific uses, the Microsoft Foundation Class Library provides several classes derived from `CDC` . `CPaintDC` encapsulates calls to `BeginPaint` and `EndPaint`. `CClientDC` manages a display context associated with a window's client area. `CWindowDC` manages a display context associated with an entire window, including its frame and controls. `CMetaFileDC` associates a device context with a metafile. -`CDC` provides two member functions, [`GetLayout`](#getlayout) and [`SetLayout`](#setlayout), for reversing the layout of a device context, which does not inherit its layout from a window. Such right-to-left orientation is necessary for applications written for cultures, such as Arabic or Hebrew, where the character layout is not the European standard. +`CDC` provides two member functions, [`GetLayout`](#getlayout) and [`SetLayout`](#setlayout), for reversing the layout of a device context, which doesn't inherit its layout from a window. Such right-to-left orientation is necessary for applications written for cultures, such as Arabic or Hebrew, where the character layout isn't the European standard. `CDC` contains two device contexts, [`m_hDC`](#m_hdc) and [`m_hAttribDC`](#m_hattribdc), which, on creation of a `CDC` object, refer to the same device. `CDC` directs all output GDI calls to `m_hDC` and most attribute GDI calls to `m_hAttribDC`. (An example of an attribute call is `GetTextColor`, while `SetTextColor` is an output call.) @@ -303,7 +302,7 @@ This member function replaces the `ABORTDOC` printer escape. `AbortDoc` should be used to terminate the following: -- Printing operations that do not specify an abort function using [`SetAbortProc`](#setabortproc). +- Printing operations that don't specify an abort function using [`SetAbortProc`](#setabortproc). - Printing operations that have not yet reached their first `NEWFRAME` or `NEXTBAND` escape call. @@ -311,7 +310,7 @@ If an application encounters a printing error or a canceled print operation, it If the application displays a dialog box to allow the user to cancel the print operation, it must call `AbortDoc` before destroying the dialog box. -If Print Manager was used to start the print job, calling `AbortDoc` erases the entire spool job — the printer receives nothing. If Print Manager was not used to start the print job, the data may have been sent to the printer before `AbortDoc` was called. In this case, the printer driver would have reset the printer (when possible) and closed the print job. +If Print Manager was used to start the print job, calling `AbortDoc` erases the entire spool job—the printer receives nothing. If Print Manager wasn't used to start the print job, the data may have been sent to the printer before `AbortDoc` was called. In this case, the printer driver would have reset the printer (when possible) and closed the print job. ### Example @@ -331,7 +330,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -If there is an open path bracket in the device context, the path bracket is closed and the path is discarded. If there is a closed path in the device context, the path is discarded. +If there's an open path bracket in the device context, the path bracket is closed and the path is discarded. If there's a closed path in the device context, the path is discarded. ## `CDC::AddMetaFileComment` @@ -345,10 +344,10 @@ BOOL AddMetaFileComment( ### Parameters -*`nDataSize`*
+*`nDataSize`*\ Specifies the length of the comment buffer, in bytes. -*`pCommentData`*
+*`pCommentData`*\ Points to the buffer that contains the comment. ### Return Value @@ -357,7 +356,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -A comment may include any private information — for example, the source of the picture and the date it was created. A comment should begin with an application signature, followed by the data. Comments should not contain position-specific data. Position-specific data specifies the location of a record, and it should not be included because one metafile may be embedded within another metafile. This function can only be used with enhanced metafiles. +A comment may include any private information — for example, the source of the picture and the date it was created. A comment should begin with an application signature, followed by the data. Comments shouldn't contain position-specific data. Position-specific data specifies the location of a record, and it shouldn't be included because one metafile may be embedded within another metafile. This function can only be used with enhanced metafiles. ## `CDC::AlphaBlend` @@ -379,34 +378,34 @@ BOOL AlphaBlend( ### Parameters -*`xDest`*
+*`xDest`*\ Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle. -*`yDest`*
+*`yDest`*\ Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle. -*`nDestWidth`*
+*`nDestWidth`*\ Specifies the width, in logical units, of the destination rectangle. -*`nDestHeight`*
+*`nDestHeight`*\ Specifies the height, in logical units, of the destination rectangle. -*`pSrcDC`*
+*`pSrcDC`*\ A pointer to the source device context. -*`xSrc`*
+*`xSrc`*\ Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle. -*`ySrc`*
+*`ySrc`*\ Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle. -*`nSrcWidth`*
+*`nSrcWidth`*\ Specifies the width, in logical units, of the source rectangle. -*`nSrcHeight`*
+*`nSrcHeight`*\ Specifies the height, in logical units, of the source rectangle. -*`blend`*
+*`blend`*\ Specifies a [`BLENDFUNCTION`](/windows/win32/api/wingdi/ns-wingdi-blendfunction) structure. ### Return Value @@ -432,19 +431,19 @@ BOOL AngleArc( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the center of the circle. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the center of the circle. -*`nRadius`*
+*`nRadius`*\ Specifies the radius of the circle in logical units. This value must be positive. -*`fStartAngle`*
+*`fStartAngle`*\ Specifies the starting angle in degrees relative to the x-axis. -*`fSweepAngle`*
+*`fSweepAngle`*\ Specifies the sweep angle in degrees relative to the starting angle. ### Return Value @@ -457,7 +456,7 @@ The line segment is drawn from the current position to the beginning of the arc. `AngleArc` moves the current position to the ending point of the arc. The arc drawn by this function may appear to be elliptical, depending on the current transformation and mapping mode. Before drawing the arc, this function draws the line segment from the current position to the beginning of the arc. The arc is drawn by constructing an imaginary circle with the specified radius around the specified center point. The starting point of the arc is determined by measuring counterclockwise from the x-axis of the circle by the number of degrees in the start angle. The ending point is similarly located by measuring counterclockwise from the starting point by the number of degrees in the sweep angle. -If the sweep angle is greater than 360 degrees the arc is swept multiple times. This function draws lines by using the current pen. The figure is not filled. +If the sweep angle is greater than 360 degrees the arc is swept multiple times. This function draws lines by using the current pen. The figure isn't filled. ## `CDC::Arc` @@ -482,38 +481,38 @@ BOOL Arc( ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`x3`*
-Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`x3`*\ +Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`y3`*
-Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`y3`*\ +Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`x4`*
-Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`x4`*\ +Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`y4`*
-Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`y4`*\ +Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle (in logical units). You can pass either an `LPRECT` or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`ptStart`*
-Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. +*`ptStart`*\ +Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. -*`ptEnd`*
-Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point does not have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter. +*`ptEnd`*\ +Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -523,7 +522,7 @@ Nonzero if the function is successful; otherwise 0. The arc drawn by using the function is a segment of the ellipse defined by the specified bounding rectangle. -The actual starting point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified starting point intersects the ellipse. The actual ending point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified ending point intersects the ellipse. The arc is drawn in a counterclockwise direction. Since an arc is not a closed figure, it is not filled. Both the width and height of the rectangle must be greater than 2 units and less than 32,767 units. +The actual starting point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified starting point intersects the ellipse. The actual ending point of the arc is the point at which a ray drawn from the center of the bounding rectangle through the specified ending point intersects the ellipse. The arc is drawn in a counterclockwise direction. Since an arc isn't a closed figure, it isn't filled. Both the width and height of the rectangle must be greater than 2 units and less than 32,767 units. ### Example @@ -552,38 +551,38 @@ BOOL ArcTo( ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`x3`*
-Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`x3`*\ +Specifies the x-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`y3`*
-Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`y3`*\ +Specifies the y-coordinate of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`x4`*
-Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`x4`*\ +Specifies the x-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`y4`*
-Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`y4`*\ +Specifies the y-coordinate of the point that defines the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) data structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`ptStart`*
-Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point does not have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) data structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. +*`ptStart`*\ +Specifies the x- and y-coordinates of the point that defines the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) data structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. -*`ptEnd`*
-Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point does not have to lie exactly on the arc. You can pass either a `POINT` data structure or a `CPoint` object for this parameter. +*`ptEnd`*\ +Specifies the x- and y-coordinates of the point that defines the arc's ending point (in logical units). This point doesn't have to lie exactly on the arc. You can pass either a `POINT` data structure or a `CPoint` object for this parameter. ### Return Value @@ -593,7 +592,7 @@ Nonzero if the function is successful; otherwise 0. This function is similar to `CDC::Arc`, except that the current position is updated. The points ( *`x1`*, *`y1`*) and ( *`x2`*, *`y2`*) specify the bounding rectangle. An ellipse formed by the given bounding rectangle defines the curve of the arc. The arc extends counterclockwise (the default arc direction) from the point where it intersects the radial line from the center of the bounding rectangle to ( *`x3*`, *`y3`*). The arc ends where it intersects the radial line from the center of the bounding rectangle to ( *`x4`*, *`y4`*). If the starting point and ending point are the same, a complete ellipse is drawn. -A line is drawn from the current position to the starting point of the arc. If no error occurs, the current position is set to the ending point of the arc. The arc is drawn using the current pen; it is not filled. +A line is drawn from the current position to the starting point of the arc. If no error occurs, the current position is set to the ending point of the arc. The arc is drawn using the current pen; it isn't filled. ## `CDC::Attach` @@ -605,7 +604,7 @@ BOOL Attach(HDC hDC); ### Parameters -*`hDC`*
+*`hDC`*\ A Windows device context. ### Return Value @@ -656,28 +655,28 @@ BOOL BitBlt( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the destination rectangle. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the destination rectangle. -*`nWidth`*
+*`nWidth`*\ Specifies the width (in logical units) of the destination rectangle and source bitmap. -*`nHeight`*
+*`nHeight`*\ Specifies the height (in logical units) of the destination rectangle and source bitmap. -*`pSrcDC`*
-Pointer to a `CDC` object that identifies the device context from which the bitmap will be copied. It must be `NULL` if *`dwRop`* specifies a raster operation that does not include a source. +*`pSrcDC`*\ +Pointer to a `CDC` object that identifies the device context from which the bitmap will be copied. It must be `NULL` if *`dwRop`* specifies a raster operation that doesn't include a source. -*`xSrc`*
+*`xSrc`*\ Specifies the logical x-coordinate of the upper-left corner of the source bitmap. -*`ySrc`*
+*`ySrc`*\ Specifies the logical y-coordinate of the upper-left corner of the source bitmap. -*`dwRop`*
+*`dwRop`*\ Specifies the raster operation to be performed. Raster-operation codes define how the GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. See [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of the raster-operation codes for *`dwRop`* and their descriptions For a complete list of raster-operation codes, see [About Raster Operation Codes](/windows/win32/gdi/raster-operation-codes) in the Windows SDK. @@ -690,15 +689,15 @@ Nonzero if the function is successful; otherwise 0. The application can align the windows or client areas on byte boundaries to ensure that the `BitBlt` operations occur on byte-aligned rectangles. (Set the `CS_BYTEALIGNWINDOW` or `CS_BYTEALIGNCLIENT` flags when you register the window classes.) -`BitBlt` operations on byte-aligned rectangles are considerably faster than `BitBlt` operations on rectangles that are not byte aligned. If you want to specify class styles such as byte-alignment for your own device context, you will have to register a window class rather than relying on the Microsoft Foundation classes to do it for you. Use the global function [`AfxRegisterWndClass`](../../mfc/reference/application-information-and-management.md#afxregisterwndclass). +`BitBlt` operations on byte-aligned rectangles are considerably faster than `BitBlt` operations on rectangles that aren't byte aligned. If you want to specify class styles such as byte-alignment for your own device context, you'll have to register a window class rather than relying on the Microsoft Foundation classes to do it for you. Use the global function [`AfxRegisterWndClass`](../../mfc/reference/application-information-and-management.md#afxregisterwndclass). -GDI transforms *`nWidth`* and *`nHeight`*, once by using the destination device context, and once by using the source device context. If the resulting extents do not match, GDI uses the Windows `StretchBlt` function to compress or stretch the source bitmap as necessary. +GDI transforms *`nWidth`* and *`nHeight`*, once by using the destination device context, and once by using the source device context. If the resulting extents don't match, GDI uses the Windows `StretchBlt` function to compress or stretch the source bitmap as necessary. -If destination, source, and pattern bitmaps do not have the same color format, the `BitBlt` function converts the source and pattern bitmaps to match the destination. The foreground and background colors of the destination bitmap are used in the conversion. +If destination, source, and pattern bitmaps don't have the same color format, the `BitBlt` function converts the source and pattern bitmaps to match the destination. The foreground and background colors of the destination bitmap are used in the conversion. When the `BitBlt` function converts a monochrome bitmap to color, it sets white bits (1) to the background color and black bits (0) to the foreground color. The foreground and background colors of the destination device context are used. To convert color to monochrome, `BitBlt` sets pixels that match the background color to white and sets all other pixels to black. `BitBlt` uses the foreground and background colors of the color device context to convert from color to monochrome. -Note that not all device contexts support `BitBlt`. To check whether a given device context does support `BitBlt`, use the `GetDeviceCaps` member function and specify the RASTERCAPS index. +Not all device contexts support `BitBlt`. To check whether a given device context does support `BitBlt`, use the `GetDeviceCaps` member function and specify the RASTERCAPS index. ### Example @@ -735,38 +734,38 @@ BOOL Chord( ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the chord's bounding rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the chord's bounding rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the chord's bounding rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the chord's bounding rectangle (in logical units). -*`x3`*
+*`x3`*\ Specifies the x-coordinate of the point that defines the chord's starting point (in logical units). -*`y3`*
+*`y3`*\ Specifies the y-coordinate of the point that defines the chord's starting point (in logical units). -*`x4`*
+*`x4`*\ Specifies the x-coordinate of the point that defines the chord's endpoint (in logical units). -*`y4`*
+*`y4`*\ Specifies the y-coordinate of the point that defines the chord's endpoint (in logical units). -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle (in logical units). You can pass either a `LPRECT` or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`ptStart`*
-Specifies the x- and y-coordinates of the point that defines the chord's starting point (in logical units). This point does not have to lie exactly on the chord. You can pass either a `POINT` structure or a `CPoint` object for this parameter. +*`ptStart`*\ +Specifies the x- and y-coordinates of the point that defines the chord's starting point (in logical units). This point doesn't have to lie exactly on the chord. You can pass either a `POINT` structure or a `CPoint` object for this parameter. -*`ptEnd*`
-Specifies the x- and y-coordinates of the point that defines the chord's ending point (in logical units). This point does not have to lie exactly on the chord. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. +*`ptEnd`*\ +Specifies the x- and y-coordinates of the point that defines the chord's ending point (in logical units). This point doesn't have to lie exactly on the chord. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. ### Return Value @@ -776,7 +775,7 @@ Nonzero if the function is successful; otherwise 0. The ( *`x1`*, *`y1`*) and ( *`x2`*, *`y2`*) parameters specify the upper-left and lower-right corners, respectively, of a rectangle bounding the ellipse that is part of the chord. The ( *`x3`*, *`y3`*) and ( *`x4`*, *`y4`*) parameters specify the endpoints of a line that intersects the ellipse. The chord is drawn by using the selected pen and filled by using the selected brush. -The figure drawn by the `Chord` function extends up to, but does not include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. +The figure drawn by the `Chord` function extends up to, but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. ### Example @@ -796,9 +795,9 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The function closes the figure by drawing a line from the current position to the first point of the figure (usually, the point specified by the most recent call to the `MoveTo` member function) and connects the lines by using the line join style. If a figure is closed by using the `LineTo` member function instead of `CloseFigure`, end caps are used to create the corner instead of a join. `CloseFigure` should only be called if there is an open path bracket in the device context. +The function closes the figure by drawing a line from the current position to the first point of the figure (usually, the point specified by the most recent call to the `MoveTo` member function) and connects the lines by using the line join style. If a figure is closed by using the `LineTo` member function instead of `CloseFigure`, end caps are used to create the corner instead of a join. `CloseFigure` should only be called if there's an open path bracket in the device context. -A figure in a path is open unless it is explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.) Any line or curve added to the path after `CloseFigure` starts a new figure. +A figure in a path is open unless it's explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.) Any line or curve added to the path after `CloseFigure` starts a new figure. ## `CDC::CreateCompatibleDC` @@ -810,7 +809,7 @@ BOOL CreateCompatibleDC(CDC* pDC); ### Parameters -*`pDC`*
+*`pDC`*\ A pointer to a device context. If *`pDC`* is `NULL`, the function creates a memory device context that is compatible with the system display. ### Return Value @@ -843,16 +842,16 @@ BOOL CreateDC( ### Parameters -*`lpszDriverName`*
+*`lpszDriverName`*\ Points to a null-terminated string that specifies the filename (without extension) of the device driver (for example, "`EPSON`"). You can also pass a `CString` object for this parameter. -*`lpszDeviceName`*
+*`lpszDeviceName`*\ Points to a null-terminated string that specifies the name of the specific device to be supported (for example, "`EPSON FX-80`"). The *`lpszDeviceName`* parameter is used if the module supports more than one device. You can also pass a `CString` object for this parameter. -*`lpszOutput`*
+*`lpszOutput`*\ Points to a null-terminated string that specifies the file or device name for the physical output medium (file or output port). You can also pass a `CString` object for this parameter. -*`lpInitData`*
+*`lpInitData`*\ Points to a `DEVMODE` structure containing device-specific initialization data for the device driver. The Windows `DocumentProperties` function retrieves this structure filled in for a given device. The *`lpInitData`* parameter must be `NULL` if the device driver is to use the default initialization (if any) specified by the user through the Control Panel. ### Return Value @@ -879,16 +878,16 @@ BOOL CreateIC( ### Parameters -*`lpszDriverName`*
+*`lpszDriverName`*\ Points to a null-terminated string that specifies the filename (without extension) of the device driver (for example, "`EPSON`"). You can pass a `CString` object for this parameter. -*`lpszDeviceName`*
+*`lpszDeviceName`*\ Points to a null-terminated string that specifies the name of the specific device to be supported (for example, "`EPSON FX-80`"). The *`lpszDeviceName`* parameter is used if the module supports more than one device. You can pass a `CString` object for this parameter. -*`lpszOutput`*
+*`lpszOutput`*\ Points to a null-terminated string that specifies the file or device name for the physical output medium (file or port). You can pass a `CString` object for this parameter. -*`lpInitData`*
+*`lpInitData`*\ Points to device-specific initialization data for the device driver. The *`lpInitData`* parameter must be `NULL` if the device driver is to use the default initialization (if any) specified by the user through the Control Panel. See `CreateDC` for the data format for device-specific initialization. ### Return Value @@ -903,7 +902,7 @@ Device names follow these conventions: an ending colon (:) is recommended, but o ## `CDC::DeleteDC` -In general, do not call this function; the destructor will do it for you. +In general, don't call this function; the destructor will do it for you. ``` BOOL DeleteDC(); @@ -915,9 +914,9 @@ Nonzero if the function completed successfully; otherwise 0. ### Remarks -The `DeleteDC` member function deletes the Windows device contexts that are associated with `m_hDC` in the current `CDC` object. If this `CDC` object is the last active device context for a given device, the device is notified and all storage and system resources used by the device are released. +The `DeleteDC` member function deletes the Windows device contexts that are associated with `m_hDC` in the current `CDC` object. If this `CDC` object is the last active device context for a given device, all storage and system resources used by the device are released. -An application should not call `DeleteDC` if objects have been selected into the device context. Objects must first be selected out of the device context before it is deleted. +An application shouldn't call `DeleteDC` if objects have been selected into the device context. Objects must first be selected out of the device context before it's deleted. An application must not delete a device context whose handle was obtained by calling [`CWnd::GetDC`](../../mfc/reference/cwnd-class.md#getdc). Instead, it must call [`CWnd::ReleaseDC`](../../mfc/reference/cwnd-class.md#releasedc) to free the device context. The [`CClientDC`](../../mfc/reference/cclientdc-class.md) and [`CWindowDC`](../../mfc/reference/cwindowdc-class.md) classes are provided to wrap this functionality. @@ -929,7 +928,7 @@ The `DeleteDC` function is generally used to delete device contexts created with ## `CDC::DeleteTempMap` -Called automatically by the `CWinApp` idle-time handler, `DeleteTempMap` deletes any temporary `CDC` objects created by `FromHandle`, but does not destroy the device context handles ( `hDC`s) temporarily associated with the `CDC` objects. +Called automatically by the `CWinApp` idle-time handler, `DeleteTempMap` deletes any temporary `CDC` objects created by `FromHandle`, but doesn't destroy the device context handles (`hDC`s) temporarily associated with the `CDC` objects. ``` static void PASCAL DeleteTempMap(); @@ -957,12 +956,12 @@ void DPtoHIMETRIC(LPSIZE lpSize) const; ### Parameters -*`lpSize`*
+*`lpSize`*\ Points to a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. ### Remarks -If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC`, or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (e.g., `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch. +If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC`, or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (for example, `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch. ## `CDC::DPtoLP` @@ -979,16 +978,16 @@ void DPtoLP(LPSIZE lpSize) const; ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) structures or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) objects. -*`nCount`*
+*`nCount`*\ The number of points in the array. -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. This parameter is used for the simple case of converting one rectangle from device points to logical points. -*`lpSize`*
+*`lpSize`*\ Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. ### Remarks @@ -1016,25 +1015,25 @@ void Draw3dRect( ### Parameters -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`clrTopLeft`*
+*`clrTopLeft`*\ Specifies the color of the top and left sides of the three-dimensional rectangle. -*`clrBottomRight`*
+*`clrBottomRight`*\ Specifies the color of the bottom and right sides of the three-dimensional rectangle. -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the three-dimensional rectangle. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the three-dimensional rectangle. -*`cx`*
+*`cx`*\ Specifies the width of the three-dimensional rectangle. -*`cy`*
+*`cy`*\ Specifies the height of the three-dimensional rectangle. ### Remarks @@ -1061,22 +1060,22 @@ void DrawDragRect( ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of a rectangle — in this case, the end position of the rectangle being redrawn. -*`size`*
+*`size`*\ Specifies the displacement from the top-left corner of the outer border to the top-left corner of the inner border (that is, the thickness of the border) of a rectangle. -*`lpRectLast`*
+*`lpRectLast`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of the position of a rectangle — in this case, the original position of the rectangle being redrawn. -*`sizeLast`*
+*`sizeLast`*\ Specifies the displacement from the top-left corner of the outer border to the top-left corner of the inner border (that is, the thickness of the border) of the original rectangle being redrawn. -*`pBrush`*
+*`pBrush`*\ Pointer to a brush object. Set to `NULL` to use the default halftone brush. -*`pBrushLast`*
+*`pBrushLast`*\ Pointer to the last brush object used. Set to `NULL` to use the default halftone brush. ### Remarks @@ -1098,13 +1097,13 @@ BOOL DrawEdge( ### Parameters -*`lpRect`*
+*`lpRect`*\ A pointer to a `RECT` structure that contains the logical coordinates of the rectangle. -*`nEdge`*
+*`nEdge`*\ Specifies the type of inner and outer edge to draw. This parameter must be a combination of one inner-border flag and one outer-border flag. See [`DrawEdge`](/windows/win32/api/winuser/nf-winuser-drawedge) in the Windows SDK for a table of the parameter's types. -*`nFlags`*
+*`nFlags`*\ The flags that specify the type of border to be drawn. See `DrawEdge` in the Windows SDK for a table of the parameter's values. For diagonal lines, the `BF_RECT` flags specify the end point of the vector bounded by the rectangle parameter. ### Return Value @@ -1113,7 +1112,7 @@ Nonzero if successful; otherwise 0. ## `CDC::DrawEscape` -Accesses drawing capabilities of a video display that are not directly available through the graphics device interface (GDI). +Accesses drawing capabilities of a video display that aren't directly available through the graphics device interface (GDI). ``` int DrawEscape( @@ -1124,18 +1123,18 @@ int DrawEscape( ### Parameters -*`nEscape`*
+*`nEscape`*\ Specifies the escape function to be performed. -*`nInputSize`*
+*`nInputSize`*\ Specifies the number of bytes of data pointed to by the *`lpszInputData`* parameter. -*`lpszInputData`*
+*`lpszInputData`*\ Points to the input structure required for the specified escape. ### Return Value -Specifies the outcome of the function. Greater than zero if successful, except for the `QUERYESCSUPPORT` draw escape, which checks for implementation only; or zero if the escape is not implemented; or less than zero if an error occurred. +Specifies the outcome of the function. Greater than zero if successful, except for the `QUERYESCSUPPORT` draw escape, which checks for implementation only; or zero if the escape isn't implemented; or less than zero if an error occurred. ### Remarks @@ -1151,7 +1150,7 @@ void DrawFocusRect(LPCRECT lpRect); ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that specifies the logical coordinates of the rectangle to be drawn. ### Remarks @@ -1159,7 +1158,7 @@ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [` Since this is a Boolean **XOR** (`^`) function, calling this function a second time with the same rectangle removes the rectangle from the display. The rectangle drawn by this function cannot be scrolled. To scroll an area containing a rectangle drawn by this function, first call `DrawFocusRect` to remove the rectangle from the display, then scroll the area, and then call `DrawFocusRect` again to draw the rectangle in the new position. > [!CAUTION] -> `DrawFocusRect` works only in `MM_TEXT` mode. In other modes, this function does not draw the focus rectangle correctly, but it does not return error values. +> `DrawFocusRect` works only in `MM_TEXT` mode. In other modes, this function doesn't draw the focus rectangle correctly, but it doesn't return error values. ## `CDC::DrawFrameControl` @@ -1174,13 +1173,13 @@ BOOL DrawFrameControl( ### Parameters -*`lpRect`*
+*`lpRect`*\ A pointer to a `RECT` structure that contains the logical coordinates of the rectangle. -*`nType`*
+*`nType`*\ Specifies the type of frame control to draw. See the *`uType`* parameter in [`DrawFrameControl`](/windows/win32/api/winuser/nf-winuser-drawframecontrol) in the Windows SDK for a list of this parameter's possible values. -*`nState`*
+*`nState`*\ Specifies the initial state of the frame control. Can be one or more of the values described for the *`uState`* parameter in `DrawFrameControl` in the Windows SDK. Use the *`nState`* value `DFCS_ADJUSTRECT` to adjust the bounding rectangle to exclude the surrounding edge of the push button. ### Return Value @@ -1262,16 +1261,16 @@ BOOL DrawIcon( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the icon. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the icon. -*`hIcon`*
+*`hIcon`*\ Identifies the handle of the icon to be drawn. -*`point`*
+*`point`*\ Specifies the logical x- and y-coordinates of the upper-left corner of the icon. You can pass a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. ### Return Value @@ -1361,43 +1360,43 @@ BOOL DrawState( ### Parameters -*`pt`*
+*`pt`*\ Specifies the location of the image. -*`size`*
+*`size`*\ Specifies the size of the image. -*`hBitmap`*
+*`hBitmap`*\ A handle to a bitmap. -*`nFlags`*
+*`nFlags`*\ Flags that specify the image type and state. See [`DrawState`](/windows/win32/api/winuser/nf-winuser-drawstatew) in the Windows SDK for the possible *nFlags* types and states. -*`hBrush`*
+*`hBrush`*\ A handle to a brush. -*`pBitmap`*
-A pointer to a CBitmap object. +*`pBitmap`*\ +A pointer to a `CBitmap` object. -*`pBrush`*
-A pointer to a CBrush object. +*`pBrush`*\ +A pointer to a `CBrush` object. -*`hIcon`*
+*`hIcon`*\ A handle to an icon. -*`lpszText`*
+*`lpszText`*\ A pointer to text. -*`bPrefixText`*
+*`bPrefixText`*\ Text that may contain an accelerator mnemonic. The *`lData`* parameter specifies the address of the string, and the *`nTextLen`* parameter specifies the length. If *`nTextLen`* is 0, the string is assumed to be null-terminated. -*`nTextLen`*
+*`nTextLen`*\ Length of the text string pointed to by *`lpszText`*. If *`nTextLen`* is 0, the string is assumed to be null-terminated. -*`lpDrawProc`*
-A pointer to a callback function used to render an image. This parameter is required if the image type in *`nFlags`* is `DST_COMPLEX`. It is optional and can be `NULL` if the image type is `DST_TEXT`. For all other image types, this parameter is ignored. For more information about the callback function, see the [`DrawStateProc`](/windows/win32/api/winuser/nc-winuser-drawstateproc) function in the Windows SDK. +*`lpDrawProc`*\ +A pointer to a callback function used to render an image. This parameter is required if the image type in *`nFlags`* is `DST_COMPLEX`. It's optional and can be `NULL` if the image type is `DST_TEXT`. For all other image types, this parameter is ignored. For more information about the callback function, see the [`DrawStateProc`](/windows/win32/api/winuser/nc-winuser-drawstateproc) function in the Windows SDK. -*`lData`*
+*`lData`*\ Specifies information about the image. The meaning of this parameter depends on the image type. ### Return Value @@ -1406,7 +1405,7 @@ Nonzero if successful; otherwise 0. ## `CDC::DrawText` -Call this member function to format text in the given rectangle. To specify additional formatting options, use [`CDC::DrawTextEx`](#drawtextex). +Call this member function to format text in the given rectangle. To specify more formatting options, use [`CDC::DrawTextEx`](#drawtextex). ``` virtual int DrawText( @@ -1423,19 +1422,19 @@ int DrawText( ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to the string to be drawn. If *`nCount`* is -1, the string must be null-terminated. -*`nCount`*
+*`nCount`*\ Specifies the number of chars in the string. If *`nCount`* is -1, then *`lpszString`* is assumed to be a long pointer to a null-terminated string and `DrawText` computes the character count automatically. -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the rectangle (in logical coordinates) in which the text is to be formatted. -*`str`*
+*`str`*\ A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that contains the specified characters to be drawn. -*`nFormat`*
+*`nFormat`*\ Specifies the method of formatting the text. It can be any combination of the values described for the *`uFormat`* parameter in [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext) in the Windows SDK. (combine using the bitwise OR operator): > [!NOTE] @@ -1449,13 +1448,13 @@ The height of the text if the function is successful. It formats text by expanding tabs into appropriate spaces, aligning text to the left, right, or center of the given rectangle, and breaking text into lines that fit within the given rectangle. The type of formatting is specified by *`nFormat`*. -This member function uses the device context's selected font, text color, and background color to draw the text. Unless the `DT_NOCLIP` format is used, `DrawText` clips the text so that the text does not appear outside the given rectangle. All formatting is assumed to have multiple lines unless the `DT_SINGLELINE` format is given. +This member function uses the device context's selected font, text color, and background color to draw the text. Unless the `DT_NOCLIP` format is used, `DrawText` clips the text so that the text doesn't appear outside the given rectangle. All formatting is assumed to have multiple lines unless the `DT_SINGLELINE` format is given. -If the selected font is too large for the specified rectangle, the `DrawText` member function does not attempt to substitute a smaller font. +If the selected font is too large for the specified rectangle, the `DrawText` member function doesn't attempt to substitute a smaller font. If the `DT_CALCRECT` flag is specified, the rectangle specified by *`lpRect`* will be updated to reflect the width and height needed to draw the text. -If the `TA_UPDATECP` text-alignment flag has been set (see [`CDC::SetTextAlign`](#settextalign)), `DrawText` will display text starting at the current position, rather than at the left of the given rectangle. `DrawText` will not wrap text when the `TA_UPDATECP` flag has been set (that is, the `DT_WORDBREAK` flag will have no effect). +If the `TA_UPDATECP` text-alignment flag has been set (see [`CDC::SetTextAlign`](#settextalign)), `DrawText` will display text starting at the current position, rather than at the left of the given rectangle. `DrawText` won't wrap text when the `TA_UPDATECP` flag has been set (that is, the `DT_WORDBREAK` flag will have no effect). The text color may be set by [`CDC::SetTextColor`](#settextcolor). @@ -1480,26 +1479,26 @@ int DrawTextEx( ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to the string to be drawn. If *`nCount`* is -1, the string must be null terminated. -*`nCount`*
+*`nCount`*\ Specifies the number of chars in the string. If *`nCount`* is -1, then *`lpszString`* is assumed to be a long pointer to a null-terminated string and `DrawText` computes the character count automatically. -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the rectangle (in logical coordinates) in which the text is to be formatted. -*`str`*
+*`str`*\ A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that contains the specified characters to be drawn. -*`nFormat`*
+*`nFormat`*\ Specifies the method of formatting the text. It can be any combination of the values described for the *`uFormat`* parameter in [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext) in the Windows SDK. (Combine using the bitwise **OR** operator): > [!NOTE] > Some *`uFormat`* flag combinations can cause the passed string to be modified. Using `DT_MODIFYSTRING` with either `DT_END_ELLIPSIS` or `DT_PATH_ELLIPSIS` may cause the string to be modified, causing an assertion in the `CString` override. The values `DT_CALCRECT`, `DT_EXTERNALLEADING`, `DT_INTERNAL`, `DT_NOCLIP`, and `DT_NOPREFIX` cannot be used with the `DT_TABSTOP` value. -*`lpDTParams`*
-Pointer to a [`DRAWTEXTPARAMS`](/windows/win32/api/winuser/ns-winuser-drawtextparams) structure that specifies additional formatting options. This parameter can be `NULL`. +*`lpDTParams`*\ +Pointer to a [`DRAWTEXTPARAMS`](/windows/win32/api/winuser/ns-winuser-drawtextparams) structure that specifies more formatting options. This parameter can be `NULL`. ### Remarks @@ -1523,19 +1522,19 @@ BOOL Ellipse(LPCRECT lpRect); ### Parameters -*`x1`*
+*`x1`*\ Specifies the logical x-coordinate of the upper-left corner of the ellipse's bounding rectangle. -*`y1`*
+*`y1`*\ Specifies the logical y-coordinate of the upper-left corner of the ellipse's bounding rectangle. -*`x2`*
+*`x2`*\ Specifies the logical x-coordinate of the lower-right corner of the ellipse's bounding rectangle. -*`y2`*
+*`y2`*\ Specifies the logical y-coordinate of the lower-right corner of the ellipse's bounding rectangle. -*`lpRect`*
+*`lpRect`*\ Specifies the ellipse's bounding rectangle. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. ### Return Value @@ -1546,7 +1545,7 @@ Nonzero if the function is successful; otherwise 0. The center of the ellipse is the center of the bounding rectangle specified by *`x1`*, *`y1`*, *`x2`*, and *`y2`*, or *`lpRect`*. The ellipse is drawn with the current pen, and its interior is filled with the current brush. -The figure drawn by this function extends up to, but does not include, the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. +The figure drawn by this function extends up to, but doesn't include, the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. If either the width or the height of the bounding rectangle is 0, no ellipse is drawn. @@ -1568,7 +1567,7 @@ This member function replaces the `ENDDOC` printer escape, and should be called If an application encounters a printing error or a canceled print operation, it must not attempt to terminate the operation by using either `EndDoc` or [`AbortDoc`](#abortdoc). GDI automatically terminates the operation before returning the error value. -This function should not be used inside metafiles. +This function shouldn't be used inside metafiles. ### Example @@ -1627,13 +1626,13 @@ int EnumObjects( ### Parameters -*`nObjectType`*
+*`nObjectType`*\ Specifies the object type. It can have the values `OBJ_BRUSH` or `OBJ_PEN`. -*`lpfn`*
+*`lpfn`*\ Is the procedure-instance address of the application-supplied callback function. See the "Remarks" section below. -*`lpData`*
+*`lpData`*\ Points to the application-supplied data. The data is passed to the callback function along with the object information. ### Return Value @@ -1644,17 +1643,17 @@ Specifies the last value returned by the [callback function](callback-functions- For each object of a given type, the callback function that you pass is called with the information for that object. The system calls the callback function until there are no more objects or the callback function returns 0. -Note that new features of Microsoft Visual C++ let you use an ordinary function as the function passed to `EnumObjects`. The address passed to `EnumObjects` is a pointer to a function exported with **`EXPORT`** and with the Pascal calling convention. In protect-mode applications, you do not have to create this function with the Windows `MakeProcInstance` function or free the function after use with the `FreeProcInstance` Windows function. +New features of Microsoft Visual C++ let you use an ordinary function as the function passed to `EnumObjects`. The address passed to `EnumObjects` is a pointer to a function exported with **`EXPORT`** and with the Pascal calling convention. In protect-mode applications, you don't have to create this function with the Windows `MakeProcInstance` function or free the function after use with the `FreeProcInstance` Windows function. -You also do not have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in +You also don't have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in **int CALLBACK EXPORT** AFunction **(LPSTR**, **LPSTR);** to cause the compiler to emit the proper export record for export by name without aliasing. This works for most needs. For some special cases, such as exporting a function by ordinal or aliasing the export, you still need to use an **`EXPORTS`** statement in a module-definition file. -For compiling Microsoft Foundation programs, you will normally use the `/GA` and `/GEs` compiler options. The `/Gw` compiler option is not used with the Microsoft Foundation classes. (If you do use the Windows function `MakeProcInstance`, you will need to explicitly cast the returned function pointer from `FARPROC` to the type needed in this API.) Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback). +For compiling Microsoft Foundation programs, you'll normally use the `/GA` and `/GEs` compiler options. The `/Gw` compiler option isn't used with the Microsoft Foundation classes. (If you do use the Windows function `MakeProcInstance`, you'll need to explicitly cast the returned function pointer from `FARPROC` to the type needed in this API.) Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback). -Also note that all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). +Also, all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). ### Example @@ -1681,35 +1680,35 @@ int Escape( ### Parameters -*`nEscape`*
+*`nEscape`*\ Specifies the escape function to be performed. For a complete list of escape functions, see [`Escape`](/windows/win32/api/wingdi/nf-wingdi-escape) in the Windows SDK. -*`nCount`*
+*`nCount`*\ Specifies the number of bytes of data pointed to by *`lpszInData`*. -*`lpszInData`*
+*`lpszInData`*\ Points to the input data structure required for this escape. -*`lpOutData`*
+*`lpOutData`*\ Points to the structure that is to receive output from this escape. The *`lpOutData`* parameter is `NULL` if no data is returned. -*`nInputSize`*
+*`nInputSize`*\ Specifies the number of bytes of data pointed to by the *`lpszInputData`* parameter. -*`lpszInputData`*
+*`lpszInputData`*\ Points to the input structure required for the specified escape. -*`nOutputSize`*
+*`nOutputSize`*\ Specifies the number of bytes of data pointed to by the *`lpszOutputData`* parameter. -*`lpszOutputData`*
+*`lpszOutputData`*\ Points to the structure that receives output from this escape. This parameter should be `NULL` if no data is returned. ### Return Value -A positive value is returned if the function is successful, except for the `QUERYESCSUPPORT` escape, which only checks for implementation. Zero is returned if the escape is not implemented. A negative value is returned if an error occurred. The following are common error values: +A positive value is returned if the function is successful, except for the `QUERYESCSUPPORT` escape, which only checks for implementation. Zero is returned if the escape isn't implemented. A negative value is returned if an error occurred. The following are common error values: - `SP_ERROR` General error. @@ -1739,7 +1738,7 @@ For Win32 programming, `CDC` now provides six member functions that supersede th In addition, [`CDC::GetDeviceCaps`](#getdevicecaps) supports Win32 indexes that supersede other printer escapes. See [`GetDeviceCaps`](/windows/win32/api/wingdi/nf-wingdi-getdevicecaps) in the Windows SDK for more information. -This member function allows applications to access facilities of a particular device that are not directly available through GDI. +This member function allows applications to access facilities of a particular device that aren't directly available through GDI. Use the first version if your application uses predefined escape values. Use the second version if your application defines private escape values. See [`ExtEscape`](/windows/win32/api/wingdi/nf-wingdi-extescape) in the Windows SDK for more information about the second version. @@ -1759,19 +1758,19 @@ int ExcludeClipRect(LPCRECT lpRect); ### Parameters -*`x1`*
+*`x1`*\ Specifies the logical x-coordinate of the upper-left corner of the rectangle. -*`y1`*
+*`y1`*\ Specifies the logical y-coordinate of the upper-left corner of the rectangle. -*`x2`*
+*`x2`*\ Specifies the logical x-coordinate of the lower-right corner of the rectangle. -*`y2`*
+*`y2`*\ Specifies the logical y-coordinate of the lower-right corner of the rectangle. -*`lpRect`*
+*`lpRect`*\ Specifies the rectangle. Can also be a `CRect` object. ### Return Value @@ -1800,7 +1799,7 @@ int ExcludeUpdateRgn(CWnd* pWnd); ### Parameters -*`pWnd`*
+*`pWnd`*\ Points to the window object whose window is being updated. ### Return Value @@ -1829,16 +1828,16 @@ BOOL ExtFloodFill( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the point where filling begins. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the point where filling begins. -*`crColor`*
+*`crColor`*\ Specifies the color of the boundary or of the area to be filled. The interpretation of *`crColor`* depends on the value of *`nFillType`*. -*`nFillType`*
+*`nFillType`*\ Specifies the type of flood fill to be performed. It must be either of the following values: - `FLOODFILLBORDER` The fill area is bounded by the color specified by *`crColor`*. This style is identical to the filling performed by `FloodFill`. @@ -1847,7 +1846,7 @@ Specifies the type of flood fill to be performed. It must be either of the follo ### Return Value -Nonzero if the function is successful; otherwise 0 if the filling could not be completed, if the given point has the boundary color specified by *`crColor`* (if `FLOODFILLBORDER` was requested), if the given point does not have the color specified by *`crColor`* (if `FLOODFILLSURFACE` was requested), or if the point is outside the clipping region. +Nonzero if the function is successful; otherwise 0 if the filling couldn't be completed, if the given point has the boundary color specified by *`crColor`* (if `FLOODFILLBORDER` was requested), if the given point doesn't have the color specified by *`crColor`* (if `FLOODFILLSURFACE` was requested), or if the point is outside the clipping region. ### Remarks @@ -1884,32 +1883,32 @@ BOOL ExtTextOut( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the character cell for the first character in the specified string. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the top of the character cell for the first character in the specified string. -*`nOptions`*
+*`nOptions`*\ Specifies the rectangle type. This parameter can be one, both, or neither of the following values: - `ETO_CLIPPED` Specifies that text is clipped to the rectangle. - `ETO_OPAQUE` Specifies that the current background color fills the rectangle. (You can set and query the current background color with the [`SetBkColor`](#setbkcolor) and [`GetBkColor`](#getbkcolor) member functions.) -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that determines the dimensions of the rectangle. This parameter can be `NULL`. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`lpszString`*
+*`lpszString`*\ Points to the specified character string to be drawn. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the number of characters in the string. -*`lpDxWidths`*
+*`lpDxWidths`*\ Points to an array of values that indicate the distance between origins of adjacent character cells. For instance, *`lpDxWidths`*[ *`i`*] logical units will separate the origins of character cell *`i`* and character cell *`i`* + 1. If *`lpDxWidths`* is `NULL`, `ExtTextOut` uses the default spacing between characters. -*`str`*
+*`str`*\ A `CString` object that contains the specified characters to be drawn. ### Return Value @@ -1920,7 +1919,7 @@ Nonzero if the function is successful; otherwise 0. The rectangular region can be opaque (filled with the current background color), and it can be a clipping region. -If *`nOptions`* is 0 and *`lpRect`* is `NULL`, the function writes text to the device context without using a rectangular region. By default, the current position is not used or updated by the function. If an application needs to update the current position when it calls `ExtTextOut`, the application can call the `CDC` member function [`SetTextAlign`](#settextalign) with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores *`x`* and *`y`* on subsequent calls to `ExtTextOut` and uses the current position instead. When an application uses `TA_UPDATECP` to update the current position, `ExtTextOut` sets the current position either to the end of the previous line of text or to the position specified by the last element of the array pointed to by *`lpDxWidths`*, whichever is greater. +If *`nOptions`* is 0 and *`lpRect`* is `NULL`, the function writes text to the device context without using a rectangular region. By default, the current position isn't used or updated by the function. If an application needs to update the current position when it calls `ExtTextOut`, the application can call the `CDC` member function [`SetTextAlign`](#settextalign) with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores *`x`* and *`y`* on subsequent calls to `ExtTextOut` and uses the current position instead. When an application uses `TA_UPDATECP` to update the current position, `ExtTextOut` sets the current position either to the end of the previous line of text or to the position specified by the last element of the array pointed to by *`lpDxWidths`*, whichever is greater. ## `CDC::FillPath` @@ -1950,19 +1949,19 @@ void FillRect( ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that contains the logical coordinates of the rectangle to be filled. You can also pass a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object for this parameter. -*`pBrush`*
+*`pBrush`*\ Identifies the brush used to fill the rectangle. ### Remarks -The function fills the complete rectangle, including the left and top borders, but it does not fill the right and bottom borders. +The function fills the complete rectangle, including the left and top borders, but it doesn't fill the right and bottom borders. The brush needs to either be created using the [`CBrush`](../../mfc/reference/cbrush-class.md) member functions [`CreateHatchBrush`](../../mfc/reference/cbrush-class.md#createhatchbrush), [`CreatePatternBrush`](../../mfc/reference/cbrush-class.md#createpatternbrush), and [`CreateSolidBrush`](../../mfc/reference/cbrush-class.md#createsolidbrush), or retrieved by the `GetStockObject` Windows function. -When filling the specified rectangle, `FillRect` does not include the rectangle's right and bottom sides. GDI fills a rectangle up to, but does not include, the right column and bottom row, regardless of the current mapping mode. `FillRect` compares the values of the `top`, `bottom`, `left`, and `right` members of the specified rectangle. If `bottom` is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle is not drawn. +When filling the specified rectangle, `FillRect` doesn't include the rectangle's right and bottom sides. GDI fills a rectangle up to, but doesn't include, the right column and bottom row, regardless of the current mapping mode. `FillRect` compares the values of the `top`, `bottom`, `left`, and `right` members of the specified rectangle. If `bottom` is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle isn't drawn. `FillRect` is similar to [`CDC::FillSolidRect`](#fillsolidrect); however, `FillRect` takes a brush and therefore can be used to fill a rectangle with a solid color, a dithered color, hatched brushes, or a pattern. `FillSolidRect` uses only solid colors (indicated by a `COLORREF` parameter). `FillRect` usually is slower than `FillSolidRect`. @@ -1978,10 +1977,10 @@ BOOL FillRgn( ### Parameters -*`pRgn`*
+*`pRgn`*\ A pointer to the region to be filled. The coordinates for the given region are specified in logical units. -*`pBrush`*
+*`pBrush`*\ Identifies the brush to be used to fill the region. ### Return Value @@ -2015,21 +2014,21 @@ void FillSolidRect( ### Parameters -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle (in logical units). You can pass either a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) data structure or a `CRect` object for this parameter. *`clr`* Specifies the color to be used to fill the rectangle. -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the rectangle. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the destination rectangle. -*`cx`*
+*`cx`*\ Specifies the width of the rectangle. -*`cy`*
+*`cy`*\ Specifies the height of the rectangle. ### Remarks @@ -2064,18 +2063,18 @@ BOOL FloodFill( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the point where filling begins. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the point where filling begins. -*`crColor`*
+*`crColor`*\ Specifies the color of the boundary. ### Return Value -Nonzero if the function is successful; otherwise 0 is returned if the filling could not be completed, the given point has the boundary color specified by *`crColor`*, or the point is outside the clipping region. +Nonzero if the function is successful; otherwise 0 is returned if the filling couldn't be completed, the given point has the boundary color specified by *`crColor`*, or the point is outside the clipping region. ### Remarks @@ -2097,19 +2096,19 @@ void FrameRect( ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the logical coordinates of the upper-left and lower-right corners of the rectangle. You can also pass a `CRect` object for this parameter. -*`pBrush`*
+*`pBrush`*\ Identifies the brush to be used for framing the rectangle. ### Remarks The function uses the given brush to draw the border. The width and height of the border is always 1 logical unit. -If the rectangle's `bottom` coordinate is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle is not drawn. +If the rectangle's `bottom` coordinate is less than or equal to `top`, or if `right` is less than or equal to `left`, the rectangle isn't drawn. -The border drawn by `FrameRect` is in the same position as a border drawn by the `Rectangle` member function using the same coordinates (if `Rectangle` uses a pen that is 1 logical unit wide). The interior of the rectangle is not filled by `FrameRect`. +The border drawn by `FrameRect` is in the same position as a border drawn by the `Rectangle` member function using the same coordinates (if `Rectangle` uses a pen that is 1 logical unit wide). The interior of the rectangle isn't filled by `FrameRect`. ## `CDC::FrameRgn` @@ -2125,16 +2124,16 @@ BOOL FrameRgn( ### Parameters -*`pRgn`*
+*`pRgn`*\ Points to the `CRgn` object that identifies the region to be enclosed in a border. The coordinates for the given region are specified in logical units. -*`pBrush`*
+*`pBrush`*\ Points to the `CBrush` object that identifies the brush to be used to draw the border. -*`nWidth`*
+*`nWidth`*\ Specifies the width of the border in vertical brush strokes in device units. -*`nHeight`*
+*`nHeight`*\ Specifies the height of the border in horizontal brush strokes in device units. ### Return Value @@ -2155,16 +2154,16 @@ static CDC* PASCAL FromHandle(HDC hDC); ### Parameters -*`hDC`*
+*`hDC`*\ Contains a handle to a Windows device context. ### Return Value -The pointer may be temporary and should not be stored beyond immediate use. +The pointer may be temporary and shouldn't be stored beyond immediate use. ### Remarks -If a `CDC` object is not attached to the handle, a temporary `CDC` object is created and attached. +If a `CDC` object isn't attached to the handle, a temporary `CDC` object is created and attached. ### Example @@ -2238,7 +2237,7 @@ The current background mode, which can be `OPAQUE` or `TRANSPARENT`. ### Remarks -The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that is not a solid line. +The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that isn't a solid line. ## `CDC::GetBoundsRect` @@ -2252,13 +2251,13 @@ UINT GetBoundsRect( ### Parameters -*`lpRectBounds`*
+*`lpRectBounds`*\ Points to a buffer that will receive the current bounding rectangle. The rectangle is returned in logical coordinates. -*`flags`*
-Specifies whether the bounding rectangle is to be cleared after it is returned. This parameter should be zero or set to the following value: +*`flags`*\ +Specifies whether the bounding rectangle is to be cleared after it's returned. This parameter should be zero or set to the following value: -- `DCB_RESET` Forces the bounding rectangle to be cleared after it is returned. +- `DCB_RESET` Forces the bounding rectangle to be cleared after it's returned. ### Return Value @@ -2268,7 +2267,7 @@ Specifies the current state of the bounding rectangle if the function is success - `DCB_RESET` Bounding rectangle is empty. -- `DCB_SET` Bounding rectangle is not empty. +- `DCB_SET` Bounding rectangle isn't empty. - `DCB_ENABLE` Bounding accumulation is on. @@ -2311,22 +2310,22 @@ DWORD GetCharacterPlacement( ### Parameters -*`lpString`*
+*`lpString`*\ A pointer to the character string to process. -*`nCount`*
-Specifies the length of the string. For the ANSI version, it is a `BYTE` count and for the Unicode function it is a `WORD` count. For more information, see [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw). +*`nCount`*\ +Specifies the length of the string. For the ANSI version, it's a `BYTE` count and for the Unicode function it's a `WORD` count. For more information, see [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw). -*`nMaxExtent`*
+*`nMaxExtent`*\ Specifies the maximum extent (in logical units) to which the string is processed. Characters that, if processed, would exceed this extent are ignored. Computations for any required ordering or glyph arrays apply only to the included characters. This parameter is used only if the `GCP_MAXEXTENT` value is specified in the *`dwFlags`* parameter. As the function processes the input string, each character and its extent is added to the output, extent, and other arrays only if the total extent has not yet exceeded the maximum. Once the limit is reached, processing will stop. -*`lpResults`*
+*`lpResults`*\ Pointer to a [`GCP_Results`](/windows/win32/api/wingdi/ns-wingdi-gcp_resultsw) structure that receives the results of the function. -*`dwFlags`*
+*`dwFlags`*\ Specifies how to process the string into the required arrays. This parameter can be one or more of the values listed in the *`dwFlags`* section of the [`GetCharacterPlacement`](/windows/win32/api/wingdi/nf-wingdi-getcharacterplacementw) topic. -*`str`*
+*`str`*\ A pointer to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object to process. ### Return Value @@ -2357,16 +2356,16 @@ BOOL GetCharABCWidths( ### Parameters -*`nFirstChar`*
+*`nFirstChar`*\ Specifies the first character in the range of characters from the current font for which character widths are returned. -*`nLastChar`*
+*`nLastChar`*\ Specifies the last character in the range of characters from the current font for which character widths are returned. -*`lpabc`*
+*`lpabc`*\ Points to an array of [`ABC`](/windows/win32/api/wingdi/ns-wingdi-abc) structures that receive the character widths when the function returns. This array must contain at least as many `ABC` structures as there are characters in the range specified by the *`nFirstChar`* and *`nLastChar`* parameters. -*`lpABCF`*
+*`lpABCF`*\ Points to an application-supplied buffer with an array of [`ABCFLOAT`](/windows/win32/api/wingdi/ns-wingdi-abcfloat) structures to receive the character widths when the function returns. The widths returned by this function are in the IEEE floating-point format. ### Return Value @@ -2401,16 +2400,16 @@ BOOL GetCharABCWidthsI( ### Parameters -*`giFirst`*
+*`giFirst`*\ Specifies the first glyph index in the group of consecutive glyph indices from the current font. This parameter is only used if the *`pgi`* parameter is `NULL`. -*`cgi`*
+*`cgi`*\ Specifies the number of glyph indices. -*`pgi`*
+*`pgi`*\ A pointer to an array containing glyph indices. If the value is `NULL`, the *`giFirst`* parameter is used instead. The *`cgi`* parameter specifies the number of glyph indices in this array. -*`lpabc`*
+*`lpabc`*\ Pointer to an array of [`ABC`](/windows/win32/api/wingdi/ns-wingdi-abc) structures receiving the character widths. This array must contain at least as many `ABC` structures as there are glyph indices specified by the *`cgi`* parameter. ### Return Value @@ -2439,16 +2438,16 @@ BOOL GetCharWidth( ### Parameters -*`nFirstChar`*
+*`nFirstChar`*\ Specifies the first character in a consecutive group of characters in the current font. -*`nLastChar`*
+*`nLastChar`*\ Specifies the last character in a consecutive group of characters in the current font. -*`lpBuffer`*
+*`lpBuffer`*\ Points to a buffer that will receive the width values for a consecutive group of characters in the current font. -*`lpFloatBuffer`*
+*`lpFloatBuffer`*\ Points to a buffer to receive the character widths. The returned widths are in the 32-bit IEEE floating-point format. (The widths are measured along the base line of the characters.) ### Return Value @@ -2461,7 +2460,7 @@ For example, if *`nFirstChar`* identifies the letter 'a' and *`nLastChar`* ident The function stores the values in the buffer pointed to by *`lpBuffer`*. This buffer must be large enough to hold all of the widths. That is, there must be at least 26 entries in the example given. -If a character in the consecutive group of characters does not exist in a particular font, it will be assigned the width value of the default character. +If a character in the consecutive group of characters doesn't exist in a particular font, it will be assigned the width value of the default character. ## `CDC::GetCharWidthI` @@ -2477,16 +2476,16 @@ BOOL GetCharWidthI( ### Parameters -*`giFirst`*
+*`giFirst`*\ Specifies the first glyph index in the group of consecutive glyph indices from the current font. This parameter is only used if the *`pgi`* parameter is `NULL`. -*`cgi`*
+*`cgi`*\ Specifies the number of glyph indices. -*`pgi`*
+*`pgi`*\ A pointer to an array containing glyph indices. If the value is `NULL`, the *`giFirst`* parameter is used instead. The *`cgi`* parameter specifies the number of glyph indices in this array. -*`lpBuffer`*
+*`lpBuffer`*\ A pointer to a buffer that receives the widths. ### Return Value @@ -2507,7 +2506,7 @@ virtual int GetClipBox(LPRECT lpRect) const; ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that is to receive the rectangle dimensions. ### Return Value @@ -2516,7 +2515,7 @@ The clipping region's type. It can be any of the following values: - `COMPLEXREGION` Clipping region has overlapping borders. -- `ERROR` Device context is not valid. +- `ERROR` Device context isn't valid. - `NULLREGION` Clipping region is empty. @@ -2536,7 +2535,7 @@ BOOL GetColorAdjustment(LPCOLORADJUSTMENT lpColorAdjust) const; ### Parameters -*`lpColorAdjust`*
+*`lpColorAdjust`*\ Points to a [`COLORADJUSTMENT`](/windows/win32/api/wingdi/ns-wingdi-coloradjustment) data structure to receive the color adjustment values. ### Return Value @@ -2685,7 +2684,7 @@ int GetDeviceCaps(int nIndex) const; ### Parameters -*`nIndex`*
+*`nIndex`*\ Specifies the type of information to return. See [`GetDeviceCaps`](/windows/win32/api/wingdi/nf-wingdi-getdevicecaps) in the Windows SDK for a list of values. ### Return Value @@ -2710,16 +2709,16 @@ DWORD GetFontData( ### Parameters -*`dwTable`*
+*`dwTable`*\ Specifies the name of the metric table to be returned. This parameter can be one of the metric tables documented in the TrueType Font Files specification published by Microsoft Corporation. If this parameter is 0, the information is retrieved starting at the beginning of the font file. -*`dwOffset`*
+*`dwOffset`*\ Specifies the offset from the beginning of the table at which to begin retrieving information. If this parameter is 0, the information is retrieved starting at the beginning of the table specified by the *`dwTable`* parameter. If this value is greater than or equal to the size of the table, `GetFontData` returns 0. -*`lpData`*
+*`lpData`*\ Points to a buffer that will receive the font information. If this value is `NULL`, the function returns the size of the buffer required for the font data specified in the *`dwTable`* parameter. -*`cbData`*
+*`cbData`*\ Specifies the length, in bytes, of the information to be retrieved. If this parameter is 0, `GetFontData` returns the size of the data specified in the *`dwTable`* parameter. ### Return Value @@ -2732,7 +2731,7 @@ The information to retrieve is identified by specifying an offset into the font An application can sometimes use the `GetFontData` member function to save a TrueType font with a document. To do this, the application determines whether the font can be embedded and then retrieves the entire font file, specifying 0 for the *`dwTable`*, *`dwOffset`*, and *`cbData`* parameters. -Applications can determine whether a font can be embedded by checking the `otmfsType` member of the [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure. If bit 1 of `otmfsType` is set, embedding is not permitted for the font. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read only. +Applications can determine whether a font can be embedded by checking the `otmfsType` member of the [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure. If bit 1 of `otmfsType` is set, embedding isn't permitted for the font. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read only. If an application attempts to use this function to retrieve information for a non-TrueType font, the `GetFontData` member function returns -1. @@ -2768,10 +2767,10 @@ DWORD GetGlyphOutline( ### Parameters -*`nChar`*
+*`nChar`*\ Specifies the character for which information is to be returned. -*`nFormat`*
+*`nFormat`*\ Specifies the format in which the function is to return information. It can be one of the following values, or 0: |Value|Meaning| @@ -2779,23 +2778,23 @@ Specifies the format in which the function is to return information. It can be o |`GGO_BITMAP`|Returns the glyph bitmap. When the function returns, the buffer pointed to by *`lpBuffer`* contains a 1-bit-per-pixel bitmap whose rows start on doubleword boundaries.| |`GGO_NATIVE`|Returns the curve data points in the rasterizer's native format, using device units. When this value is specified, any transformation specified in *`lpmat2`* is ignored.| -When the value of *`nFormat`* is 0, the function fills in a [`GLYPHMETRICS`](/windows/win32/api/wingdi/ns-wingdi-glyphmetrics) structure but does not return glyph-outline data. +When the value of *`nFormat`* is 0, the function fills in a [`GLYPHMETRICS`](/windows/win32/api/wingdi/ns-wingdi-glyphmetrics) structure but doesn't return glyph-outline data. -*`lpgm`*
+*`lpgm`*\ Points to a `GLYPHMETRICS` structure that describes the placement of the glyph in the character cell. -*`cbBuffer`*
+*`cbBuffer`*\ Specifies the size of the buffer into which the function copies information about the outline character. If this value is 0 and the *`nFormat`* parameter is either the `GGO_BITMAP` or `GGO_NATIVE` values, the function returns the required size of the buffer. -*`lpBuffer`*
+*`lpBuffer`*\ Points to a buffer into which the function copies information about the outline character. If *`nFormat`* specifies the `GGO_NATIVE` value, the information is copied in the form of `TTPOLYGONHEADER` and `TTPOLYCURVE` structures. If this value is `NULL` and *`nFormat`* is either the `GGO_BITMAP` or `GGO_NATIVE` value, the function returns the required size of the buffer. -*`lpmat2`*
+*`lpmat2`*\ Points to a [`MAT2`](/windows/win32/api/wingdi/ns-wingdi-mat2) structure that contains a transformation matrix for the character. This parameter cannot be `NULL`, even when the `GGO_NATIVE` value is specified for *`nFormat`*. ### Return Value -The size, in bytes, of the buffer required for the retrieved information if *`cbBuffer`* is 0 or *`lpBuffer`* is `NULL`. Otherwise, it is a positive value if the function is successful, or -1 if there is an error. +The size, in bytes, of the buffer required for the retrieved information if *`cbBuffer`* is 0 or *`lpBuffer`* is `NULL`. Otherwise, it's a positive value if the function is successful, or -1 if there's an error. ### Remarks @@ -2837,9 +2836,11 @@ A pointer to a `CBrush` object if successful; otherwise `NULL`. ### Remarks -A halftone brush shows pixels that are alternately foreground and background colors to create a dithered pattern. The following is an example of a dithered pattern created by a halftone brush. +A halftone brush shows pixels that are alternately foreground and background colors to create a dithered pattern. The following diagram shows an example of a dithered pattern created by a halftone brush: -![Detail of a dithered pen stroke.](../../mfc/reference/media/vc318s1.gif "Detail of a dithered pen stroke") +:::image type="complex" source="../../mfc/reference/media/vc318s1.gif" alt-text="Diagram that shows how a dithered pen stroke is composed."::: +The diagram shows how the background color of black, and the foreground color of yellow, are combined into a pattern by alternating the black and yellow pixels with each other to create a dithered pen stroke. +:::image-end::: ## `CDC::GetKerningPairs` @@ -2853,10 +2854,10 @@ int GetKerningPairs( ### Parameters -*`nPairs`*
-Specifies the number of [`KERNINGPAIR`](/windows/win32/api/wingdi/ns-wingdi-kerningpair) structures pointed to by *`lpkrnpair`*. The function will not copy more kerning pairs than specified by *`nPairs`*. +*`nPairs`*\ +Specifies the number of [`KERNINGPAIR`](/windows/win32/api/wingdi/ns-wingdi-kerningpair) structures pointed to by *`lpkrnpair`*. The function won't copy more kerning pairs than specified by *`nPairs`*. -*`lpkrnpair`*
+*`lpkrnpair`*\ Points to an array of `KERNINGPAIR` structures that receive the kerning pairs when the function returns. This array must contain at least as many structures as specified by *`nPairs`*. If this parameter is `NULL`, the function returns the total number of kerning pairs for the font. ### Return Value @@ -2924,7 +2925,7 @@ COLORREF GetNearestColor(COLORREF crColor) const; ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the color to be matched. ### Return Value @@ -2947,13 +2948,13 @@ UINT GetOutlineTextMetrics( ### Parameters -*`lpotm`*
+*`lpotm`*\ Points to an array of [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structures. If this parameter is `NULL`, the function returns the size of the buffer required for the retrieved metric data. -*`cbData`*
+*`cbData`*\ Specifies the size, in bytes, of the buffer to which information is returned. -*`lpotm`*
+*`lpotm`*\ Points to an `OUTLINETEXTMETRIC` structure. If this parameter is `NULL`, the function returns the size of the buffer required for the retrieved metric information. ### Return Value @@ -2962,7 +2963,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure contains most of the font metric information provided with the TrueType format, including a [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure. The last four members of the `OUTLINETEXTMETRIC` structure are pointers to strings. Applications should allocate space for these strings in addition to the space required for the other members. Because there is no system-imposed limit to the size of the strings, the simplest method for allocating memory is to retrieve the required size by specifying NULL for *`lpotm`* in the first call to the `GetOutlineTextMetrics` function. +The [`OUTLINETEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-outlinetextmetricw) structure contains most of the font metric information provided with the TrueType format, including a [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure. The last four members of the `OUTLINETEXTMETRIC` structure are pointers to strings. Applications should allocate space for these strings in addition to the space required for the other members. Because there's no system-imposed limit to the size of the strings, the simplest method for allocating memory is to retrieve the required size by specifying NULL for *`lpotm`* in the first call to the `GetOutlineTextMetrics` function. ## `CDC::GetOutputCharWidth` @@ -2977,13 +2978,13 @@ BOOL GetOutputCharWidth( ### Parameters -*`nFirstChar`*
+*`nFirstChar`*\ Specifies the first character in a consecutive group of characters in the current font. -*`nLastChar`*
+*`nLastChar`*\ Specifies the last character in a consecutive group of characters in the current font. -*`lpBuffer`*
+*`lpBuffer`*\ Points to a buffer that will receive the width values for a consecutive group of characters in the current font. ### Return Value @@ -2996,7 +2997,7 @@ For example, if *`nFirstChar`* identifies the letter 'a' and *`nLastChar`* ident The function stores the values in the buffer pointed to by *`lpBuffer`*. This buffer must be large enough to hold all of the widths; that is, there must be at least 26 entries in the example given. -If a character in the consecutive group of characters does not exist in a particular font, it will be assigned the width value of the default character. +If a character in the consecutive group of characters doesn't exist in a particular font, it will be assigned the width value of the default character. ## `CDC::GetOutputTabbedTextExtent` @@ -3017,19 +3018,19 @@ CSize GetOutputTabbedTextExtent( ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to a character string to be measured. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*. -*`nTabPositions`*
+*`nTabPositions`*\ Specifies the number of tab-stop positions in the array pointed to by *`lpnTabStopPositions`*. -*`lpnTabStopPositions`*
-Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs are not allowed. +*`lpnTabStopPositions`*\ +Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs aren't allowed. -*`str`*
+*`str`*\ A `CString` object that contains the specified characters to be measured. ### Return Value @@ -3040,9 +3041,9 @@ The dimensions of the string (in logical units) in a [`CSize`](../../atl-mfc-sha If the string contains one or more tab characters, the width of the string is based upon the tab stops specified by *`lpnTabStopPositions`*. The function uses the currently selected font to compute the dimensions of the string. -The current clipping region does not offset the width and height returned by the `GetOutputTabbedTextExtent` function. +The current clipping region doesn't offset the width and height returned by the `GetOutputTabbedTextExtent` function. -Since some devices do not place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string. +Since some devices don't place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string. If *`nTabPositions`* is 0 and *`lpnTabStopPositions`* is `NULL`, tabs are expanded to eight average character widths. If *`nTabPositions`* is 1, the tab stops will be separated by the distance specified by the first value in the array to which *`lpnTabStopPositions`* points. If *`lpnTabStopPositions`* points to more than a single value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*. @@ -3060,13 +3061,13 @@ CSize GetOutputTextExtent(const CString& str) const; ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to a string of characters. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*. -*`str`*
+*`str`*\ A `CString` object that contains the specified characters to be measured. ### Return Value @@ -3075,9 +3076,9 @@ The dimensions of the string (in logical units) returned in a [`CSize`](../../at ### Remarks -The current clipping region does not affect the width and height returned by `GetOutputTextExtent`. +The current clipping region doesn't affect the width and height returned by `GetOutputTextExtent`. -Since some devices do not place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string. +Since some devices don't place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string. ## `CDC::GetOutputTextMetrics` @@ -3089,7 +3090,7 @@ BOOL GetOutputTextMetrics(LPTEXTMETRIC lpMetrics) const; ### Parameters -*`lpMetrics`*
+*`lpMetrics`*\ Points to the [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure that receives the metrics. ### Return Value @@ -3109,10 +3110,10 @@ int GetPath( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures or `CPoint` objects where the line endpoints and curve control points are placed. -*`lpTypes`*
+*`lpTypes`*\ Points to an array of bytes where the vertex types are placed. Values are one of the following: - `PT_MOVETO` Specifies that the corresponding point in *`lpPoints`* starts a disjoint figure. @@ -3127,7 +3128,7 @@ Points to an array of bytes where the vertex types are placed. Values are one of - `PT_CLOSEFIGURE` Specifies that the figure is automatically closed after the corresponding line or curve is drawn. The figure is closed by drawing a line from the line or curve endpoint to the point corresponding to the last `PT_MOVETO`. -*`nCount`*
+*`nCount`*\ Specifies the total number of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that may be placed in the *`lpPoints`* array. This value must be the same as the number of bytes that may be placed in the *`lpTypes`* array. ### Return Value @@ -3144,7 +3145,7 @@ The device context must contain a closed path. The points of the path are return ## `CDC::GetPixel` -Retrieves the RGB color value of the pixel at the point specified by *`x`* and *`y*`. +Retrieves the RGB color value of the pixel at the point specified by *`x`* and *`y`*. ``` COLORREF GetPixel( @@ -3156,22 +3157,22 @@ COLORREF GetPixel(POINT point) const; ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the point to be examined. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the point to be examined. -*`point`*
+*`point`*\ Specifies the logical x- and y-coordinates of the point to be examined. ### Return Value -For either version of the function, an RGB color value for the color of the given point. It is -1 if the coordinates do not specify a point in the clipping region. +For either version of the function, an RGB color value for the color of the given point. It's -1 if the coordinates don't specify a point in the clipping region. ### Remarks -The point must be in the clipping region. If the point is not in the clipping region, the function has no effect and returns -1. +The point must be in the clipping region. If the point isn't in the clipping region, the function has no effect and returns -1. Not all devices support the `GetPixel` function. For more information, see the `RC_BITBLT` raster capability under the [`GetDeviceCaps`](#getdevicecaps) member function. @@ -3262,19 +3263,19 @@ CSize GetTabbedTextExtent( ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to a character string. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*. -*`nTabPositions`*
+*`nTabPositions`*\ Specifies the number of tab-stop positions in the array pointed to by *`lpnTabStopPositions`*. -*`lpnTabStopPositions`*
-Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs are not allowed. +*`lpnTabStopPositions`*\ +Points to an array of integers containing the tab-stop positions in logical units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. Back tabs aren't allowed. -*`str`*
+*`str`*\ A `CString` object that contains the specified characters to be drawn. ### Return Value @@ -3285,9 +3286,9 @@ The dimensions of the string (in logical units) in a [`CSize`](../../atl-mfc-sha If the string contains one or more tab characters, the width of the string is based upon the tab stops specified by *`lpnTabStopPositions`*. The function uses the currently selected font to compute the dimensions of the string. -The current clipping region does not offset the width and height returned by the `GetTabbedTextExtent` function. +The current clipping region doesn't offset the width and height returned by the `GetTabbedTextExtent` function. -Since some devices do not place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string. +Since some devices don't place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string. If *`nTabPositions`* is 0 and *`lpnTabStopPositions`* is `NULL`, tabs are expanded to eight times the average character width. If *`nTabPositions`* is 1, the tab stops will be separated by the distance specified by the first value in the array to which *`lpnTabStopPositions`* points. If *`lpnTabStopPositions`* points to more than a single value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*. @@ -3311,7 +3312,7 @@ The status of the text-alignment flags. The return value is one or more of the f - `TA_LEFT` Specifies alignment of the y-axis and the left side of the bounding rectangle. -- `TA_NOUPDATECP` Specifies that the current position is not updated. +- `TA_NOUPDATECP` Specifies that the current position isn't updated. - `TA_RIGHT` Specifies alignment of the y-axis and the right side of the bounding rectangle. @@ -3321,7 +3322,7 @@ The status of the text-alignment flags. The return value is one or more of the f ### Remarks -The text-alignment flags determine how the `TextOut` and `ExtTextOut` member functions align a string of text in relation to the string's starting point. The text-alignment flags are not necessarily single-bit flags and may be equal to 0. To test whether a flag is set, an application should follow these steps: +The text-alignment flags determine how the `TextOut` and `ExtTextOut` member functions align a string of text in relation to the string's starting point. The text-alignment flags aren't necessarily single-bit flags and may be equal to 0. To test whether a flag is set, an application should follow these steps: 1. Apply the bitwise **OR** (`|`) operator to the flag and its related flags, grouped as follows: @@ -3383,13 +3384,13 @@ CSize GetTextExtent(const CString& str) const; ### Parameters -*`lpszString`*
+*`lpszString`*\ Points to a string of characters. You can also pass a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the number of characters in the string. -*`str`*
+*`str`*\ A `CString` object that contains the specified characters. ### Return Value @@ -3402,9 +3403,9 @@ The information is retrieved from [`m_hAttribDC`](#m_hattribdc), the attribute d By default, `GetTextExtent` assumes the text for which it retrieves the dimension is set along a horizontal line (that is, the escapement is 0). If you create a font specifying a non-zero escapement, you must convert the angle of the text explicitly to get the dimensions of the string. -The current clipping region does not affect the width and height returned by `GetTextExtent`. +The current clipping region doesn't affect the width and height returned by `GetTextExtent`. -Since some devices do not place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string. +Since some devices don't place characters in regular cell arrays (that is, they carry out kerning), the sum of the extents of the characters in a string may not be equal to the extent of the string. ## `CDC::GetTextExtentExPointI` @@ -3422,22 +3423,22 @@ BOOL GetTextExtentExPointI( ### Parameters -*`pgiIn`*
+*`pgiIn`*\ A pointer to an array of glyph indices for which extents are to be retrieved. -*`cgi`*
+*`cgi`*\ Specifies the number of glyphs in the array pointed to by *`pgiIn`*. -*`nMaxExtent`*
+*`nMaxExtent`*\ Specifies the maximum allowable width, in logical units, of the formatted string. -*`lpnFit`*
+*`lpnFit`*\ A pointer to an integer that receives a count of the maximum number of characters that will fit in the space specified by *`nMaxExtent`*. When *`lpnFit`* is `NULL`, *`nMaxExtent`* is ignored. -*`alpDx`*
-A pointer to an array of integers that receives partial glyph extents. Each element in the array gives the distance, in logical units, between the beginning of the glyph indices array and one of the glyphs that fits in the space specified by *`nMaxExtent`*. Although this array should have at least as many elements as glyph indices specified by *`cgi`*, the function fills the array with extents only for as many glyph indices as are specified by *`lpnFit`*. If *`lpnDx`* is `NULL`, the function does not compute partial string widths. +*`alpDx`*\ +A pointer to an array of integers that receives partial glyph extents. Each element in the array gives the distance, in logical units, between the beginning of the glyph indices array and one of the glyphs that fits in the space specified by *`nMaxExtent`*. Although this array should have at least as many elements as glyph indices specified by *`cgi`*, the function fills the array with extents only for as many glyph indices as are specified by *`lpnFit`*. If *`lpnDx`* is `NULL`, the function doesn't compute partial string widths. -*`lpSize`*
+*`lpSize`*\ Pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that receives the dimensions of the glyph indices array, in logical units. This value cannot be `NULL`. ### Return Value @@ -3461,13 +3462,13 @@ BOOL GetTextExtentPointI( ### Parameters -*`pgiIn`*
+*`pgiIn`*\ A pointer to an array of glyph indices for which extents are to be retrieved. -*`cgi`*
+*`cgi`*\ Specifies the number of glyphs in the array pointed to by *`pgiIn`*. -*`lpSize`*
+*`lpSize`*\ Pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that receives the dimensions of the glyph indices array, in logical units. This value cannot be `NULL`. ### Return Value @@ -3492,18 +3493,18 @@ int GetTextFace(CString& rString) const; ### Parameters -*`nCount`*
+*`nCount`*\ Specifies the size of the buffer (in bytes). If the typeface name is longer than the number of bytes specified by this parameter, the name is truncated. -*`lpszFacename`*
+*`lpszFacename`*\ Points to the buffer for the typeface name. -*`rString`*
+*`rString`*\ A reference to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object. ### Return Value -The number of bytes copied to the buffer, not including the terminating null character. It is 0 if an error occurs. +The number of bytes copied to the buffer, not including the terminating null character. It's 0 if an error occurs. ### Remarks @@ -3519,7 +3520,7 @@ BOOL GetTextMetrics(LPTEXTMETRIC lpMetrics) const; ### Parameters -*`lpMetrics`*
+*`lpMetrics`*\ Points to the [`TEXTMETRIC`](/windows/win32/api/wingdi/ns-wingdi-textmetricw) structure that receives the metrics. ### Return Value @@ -3600,7 +3601,7 @@ BOOL GetWorldTransform(XFORM& rXform) const; ### Parameters -*`rXform`*
+*`rXform`*\ Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure that receives the current world-space to page-space transformation. ### Return Value @@ -3630,19 +3631,19 @@ BOOL GradientFill( ### Parameters -*`pVertices`*
+*`pVertices`*\ Pointer to an array of [`TRIVERTEX`](/windows/win32/api/wingdi/ns-wingdi-trivertex) structures that each define a triangle vertex. -*`nVertices`*
+*`nVertices`*\ The number of vertices. -*`pMesh`*
+*`pMesh`*\ Array of [`GRADIENT_TRIANGLE`](/windows/win32/api/wingdi/ns-wingdi-gradient_triangle) structures in triangle mode, or an array of [`GRADIENT_RECT`](/windows/win32/api/wingdi/ns-wingdi-gradient_rect) structures in rectangle mode. -*`nMeshElements`*
+*`nMeshElements`*\ The number of elements (triangles or rectangles) in *`pMesh`*. -*`dwMode`*
+*`dwMode`*\ Specifies gradient fill mode. For a list of possible values, see [`GradientFill`](/windows/win32/api/wingdi/nf-wingdi-gradientfill) in the Windows SDK. ### Return Value @@ -3674,28 +3675,28 @@ virtual BOOL GrayString( ### Parameters -*`pBrush`*
+*`pBrush`*\ Identifies the brush to be used for dimming (graying). -*`lpfnOutput`*
+*`lpfnOutput`*\ Specifies the procedure-instance address of the application-supplied callback function that will draw the string. For more information, see the description of the Windows `OutputFunc` [callback function](callback-functions-used-by-mfc.md#graystring). If this parameter is `NULL`, the system uses the Windows `TextOut` function to draw the string, and *`lpData`* is assumed to be a long pointer to the character string to be output. -*`lpData`*
+*`lpData`*\ Specifies a far pointer to data to be passed to the output function. If *`lpfnOutput`* is `NULL`, *`lpData`* must be a long pointer to the string to be output. -*`nCount`*
+*`nCount`*\ Specifies the number of characters to be output. If this parameter is 0, `GrayString` calculates the length of the string (assuming that *`lpData`* is a pointer to the string). If *`nCount`* is 1 and the function pointed to by *`lpfnOutput`* returns 0, the image is shown but not dimmed. -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the starting position of the rectangle that encloses the string. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the starting position of the rectangle that encloses the string. -*`nWidth`*
+*`nWidth`*\ Specifies the width (in logical units) of the rectangle that encloses the string. If *`nWidth`* is 0, `GrayString` calculates the width of the area, assuming *`lpData`* is a pointer to the string. -*`nHeight`*
+*`nHeight`*\ Specifies the height (in logical units) of the rectangle that encloses the string. If *`nHeight`* is 0, `GrayString` calculates the height of the area, assuming *`lpData`* is a pointer to the string. ### Return Value @@ -3706,15 +3707,15 @@ Nonzero if the string is drawn, or 0 if either the `TextOut` function or the app The function dims the text regardless of the selected brush and background. The `GrayString` member function uses the currently selected font. The `MM_TEXT` mapping mode must be selected before using this function. -An application can draw dimmed (grayed) strings on devices that support a solid gray color without calling the `GrayString` member function. The system color `COLOR_GRAYTEXT` is the solid-gray system color used to draw disabled text. The application can call the `GetSysColor` Windows function to retrieve the color value of `COLOR_GRAYTEXT`. If the color is other than 0 (black), the application can call the `SetTextColor` member function to set the text color to the color value and then draw the string directly. If the retrieved color is black, the application must call `GrayString` to dim (gray) the text. +An application can draw dimmed (grayed) strings on devices that support a solid gray color without calling the `GrayString` member function. The system color `COLOR_GRAYTEXT` is the solid-gray system color used to draw disabled text. The application can call the `GetSysColor` Windows function to retrieve the color value of `COLOR_GRAYTEXT`. If the color is other than 0 (black), the application can call the `SetTextColor` member function to set the text color to the color value, and then draw the string directly. If the retrieved color is black, the application must call `GrayString` to dim (gray) the text. If *`lpfnOutput`* is `NULL`, GDI uses the Windows [`TextOut`](/windows/win32/api/wingdi/nf-wingdi-textoutw) function, and *`lpData`* is assumed to be a far pointer to the character to be output. If the characters to be output cannot be handled by the `TextOut` member function (for example, the string is stored as a bitmap), the application must supply its own output function. -Also note that all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). +All callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). The callback function passed to `GrayString` must use the **`__stdcall`** calling convention and must be exported with **`__declspec`**. -When the framework is in preview mode, a call to the `GrayString` member function is translated to a `TextOut` call, and the callback function is not called. +When the framework is in preview mode, a call to the `GrayString` member function is translated to a `TextOut` call, and the callback function isn't called. ## `CDC::HIMETRICtoDP` @@ -3726,12 +3727,12 @@ void HIMETRICtoDP(LPSIZE lpSize) const; ### Parameters -*`lpSize`*
+*`lpSize`*\ Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. ### Remarks -If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC` or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (e.g., `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch. +If the mapping mode of the device context object is `MM_LOENGLISH`, `MM_HIENGLISH`, `MM_LOMETRIC` or `MM_HIMETRIC`, then the conversion is based on the number of pixels in the physical inch. If the mapping mode is one of the other non-constrained modes (for example, `MM_TEXT`), then the conversion is based on the number of pixels in the logical inch. ## `CDC::HIMETRICtoLP` @@ -3743,7 +3744,7 @@ void HIMETRICtoLP(LPSIZE lpSize) const; ### Parameters -*`lpSize`*
+*`lpSize`*\ Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. ### Remarks @@ -3768,19 +3769,19 @@ int IntersectClipRect(LPCRECT lpRect); ### Parameters -*`x1`*
+*`x1`*\ Specifies the logical x-coordinate of the upper-left corner of the rectangle. -*`y1`*
+*`y1`*\ Specifies the logical y-coordinate of the upper-left corner of the rectangle. -*`x2`*
+*`x2`*\ Specifies the logical x-coordinate of the lower-right corner of the rectangle. -*`y2`*
+*`y2`*\ Specifies the logical y-coordinate of the lower-right corner of the rectangle. -*`lpRect`*
+*`lpRect`*\ Specifies the rectangle. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter. ### Return Value @@ -3789,7 +3790,7 @@ The new clipping region's type. It can be any one of the following values: - `COMPLEXREGION` New clipping region has overlapping borders. -- `ERROR` Device context is not valid. +- `ERROR` Device context isn't valid. - `NULLREGION` New clipping region is empty. @@ -3809,7 +3810,7 @@ void InvertRect(LPCRECT lpRect); ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a `RECT` that contains the logical coordinates of the rectangle to be inverted. You can also pass a `CRect` object for this parameter. ### Remarks @@ -3832,7 +3833,7 @@ BOOL InvertRgn(CRgn* pRgn); ### Parameters -*`pRgn`*
+*`pRgn`*\ Identifies the region to be inverted. The coordinates for the region are specified in logical units. ### Return Value @@ -3869,13 +3870,13 @@ BOOL LineTo(POINT point); ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the endpoint for the line. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the endpoint for the line. -*`point`*
+*`point`*\ Specifies the endpoint for the line. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -3905,16 +3906,16 @@ void LPtoDP(LPSIZE lpSize) const; ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of points. Each point in the array is a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. -*`nCount`*
+*`nCount`*\ The number of points in the array. -*`lpRect`*
+*`lpRect`*\ Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. This parameter is used for the common case of mapping a rectangle from logical to device units. -*`lpSize`*
+*`lpSize`*\ Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or a [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. ### Remarks @@ -3933,12 +3934,12 @@ void LPtoHIMETRIC(LPSIZE lpSize) const; ### Parameters -*`lpSize`*
+*`lpSize`*\ Points to a `SIZE` structure or a `CSize` object. ### Remarks -Use this function when you give `HIMETRIC` sizes to OLE, converting from your application's natural mapping mode. Note that the extents of the device's window and viewport will affect the result. +Use this function when you give `HIMETRIC` sizes to OLE, converting from your application's natural mapping mode. The extents of the device's window and viewport will affect the result. The conversion is accomplished by first converting the logical units into pixels using the device context's current mapping units and then converting these units into `HIMETRIC` units. @@ -3987,37 +3988,37 @@ BOOL MaskBlt( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the destination rectangle. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the destination rectangle. -*`nWidth`*
+*`nWidth`*\ Specifies the width, in logical units, of the destination rectangle and source bitmap. -*`nHeight`*
+*`nHeight`*\ Specifies the height, in logical units, of the destination rectangle and source bitmap. -*`pSrcDC`*
-Identifies the device context from which the bitmap is to be copied. It must be zero if the *`dwRop`* parameter specifies a raster operation that does not include a source. +*`pSrcDC`*\ +Identifies the device context from which the bitmap is to be copied. It must be zero if the *`dwRop`* parameter specifies a raster operation that doesn't include a source. -*`xSrc`*
+*`xSrc`*\ Specifies the logical x-coordinate of the upper-left corner of the source bitmap. -*`ySrc`*
+*`ySrc`*\ Specifies the logical y-coordinate of the upper-left corner of the source bitmap. -*`maskBitmap`*
+*`maskBitmap`*\ Identifies the monochrome mask bitmap combined with the color bitmap in the source device context. -*`xMask`*
+*`xMask`*\ Specifies the horizontal pixel offset for the mask bitmap specified by the *`maskBitmap`* parameter. -*`yMask`*
+*`yMask`*\ Specifies the vertical pixel offset for the mask bitmap specified by the *`maskBitmap`* parameter. -*`dwRop`*
+*`dwRop`*\ Specifies both foreground and background ternary raster operation codes, which the function uses to control the combination of source and destination data. The background raster operation code is stored in the high byte of the high word of this value; the foreground raster operation code is stored in the low byte of the high word of this value; the low word of this value is ignored, and should be zero. The macro `MAKEROP4` creates such combinations of foreground and background raster operation codes. See the Remarks section for a discussion of foreground and background in the context of this function. See the `BitBlt` member function for a list of common raster operation codes. ### Return Value @@ -4026,11 +4027,11 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -A value of 1 in the mask specified by *`maskBitmap`* indicates that the foreground raster operation code specified by *`dwRop`* should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by *`dwRop`* should be applied at that location. If the raster operations require a source, the mask rectangle must cover the source rectangle. If it does not, the function will fail. If the raster operations do not require a source, the mask rectangle must cover the destination rectangle. If it does not, the function will fail. +A value of 1 in the mask specified by *`maskBitmap`* indicates that the foreground raster operation code specified by *`dwRop`* should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by *`dwRop`* should be applied at that location. If the raster operations require a source, the mask rectangle must cover the source rectangle. If it doesn't, the function fails. If the raster operations don't require a source, the mask rectangle must cover the destination rectangle. If it doesn't, the function fails. If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformations are allowed. -If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format. If the mask bitmap is not a monochrome bitmap, an error occurs. When an enhanced metafile is being recorded, an error occurs (and the function returns 0) if the source device context identifies an enhanced-metafile device context. Not all devices support `MaskBlt`. An application should call `GetDeviceCaps` to determine whether a device supports this function. If no mask bitmap is supplied, this function behaves exactly like `BitBlt`, using the foreground raster operation code. The pixel offsets in the mask bitmap map to the point (0,0) in the source device context's bitmap. This is useful for cases in which a mask bitmap contains a set of masks; an application can easily apply any one of them to a mask-blitting task by adjusting the pixel offsets and rectangle sizes sent to `MaskBlt`. +If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format. If the mask bitmap isn't a monochrome bitmap, an error occurs. When an enhanced metafile is being recorded, an error occurs (and the function returns 0) if the source device context identifies an enhanced-metafile device context. Not all devices support `MaskBlt`. An application should call `GetDeviceCaps` to determine whether a device supports this function. If no mask bitmap is supplied, this function behaves exactly like `BitBlt`, using the foreground raster operation code. The pixel offsets in the mask bitmap map to the point (0,0) in the source device context's bitmap. This is useful for cases in which a mask bitmap contains a set of masks; an application can easily apply any one of them to a mask-blitting task by adjusting the pixel offsets and rectangle sizes sent to `MaskBlt`. ## `CDC::ModifyWorldTransform` @@ -4044,10 +4045,10 @@ BOOL ModifyWorldTransform( ### Parameters -*`rXform`*
+*`rXform`*\ Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure used to modify the world transformation for the given device context. -*`iMode`*
+*`iMode`*\ Specifies how the transformation data modifies the current world transformation. For a list of the values that this parameter can take, see [`ModifyWorldTransform`](/windows/win32/api/wingdi/nf-wingdi-modifyworldtransform). ### Return Value @@ -4076,13 +4077,13 @@ CPoint MoveTo(POINT point); ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the new position. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the new position. -*`point`*
+*`point`*\ Specifies the new position. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -4107,13 +4108,13 @@ int OffsetClipRgn(SIZE size); ### Parameters -*`x`*
+*`x`*\ Specifies the number of logical units to move left or right. -*`y`*
+*`y`*\ Specifies the number of logical units to move up or down. -*`size`*
+*`size`*\ Specifies the amount to offset. ### Return Value @@ -4122,7 +4123,7 @@ The new region's type. It can be any one of the following values: - `COMPLEXREGION` Clipping region has overlapping borders. -- `ERROR` Device context is not valid. +- `ERROR` Device context isn't valid. - `NULLREGION` Clipping region is empty. @@ -4144,10 +4145,10 @@ virtual CPoint OffsetViewportOrg( ### Parameters -*`nWidth`*
+*`nWidth`*\ Specifies the number of device units to add to the current origin's x-coordinate. -*`nHeight`*
+*`nHeight`*\ Specifies the number of device units to add to the current origin's y-coordinate. ### Return Value @@ -4166,10 +4167,10 @@ CPoint OffsetWindowOrg( ### Parameters -*`nWidth`*
+*`nWidth`*\ Specifies the number of logical units to add to the current origin's x-coordinate. -*`nHeight`*
+*`nHeight`*\ Specifies the number of logical units to add to the current origin's y-coordinate. ### Return Value @@ -4202,7 +4203,7 @@ BOOL PaintRgn(CRgn* pRgn); ### Parameters -*`pRgn`*
+*`pRgn`*\ Identifies the region to be filled. The coordinates for the given region are specified in logical units. ### Return Value @@ -4224,19 +4225,19 @@ BOOL PatBlt( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the upper-left corner of the rectangle that is to receive the pattern. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the upper-left corner of the rectangle that is to receive the pattern. -*`nWidth`*
+*`nWidth`*\ Specifies the width (in logical units) of the rectangle that is to receive the pattern. -*`nHeight`*
+*`nHeight`*\ Specifies the height (in logical units) of the rectangle that is to receive the pattern. -*`dwRop`*
+*`dwRop`*\ Specifies the raster-operation code. Raster-operation codes (ROPs) define how GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. This parameter can be one of the following values: - `PATCOPY` Copies pattern to destination bitmap. @@ -4282,38 +4283,38 @@ BOOL Pie( ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the bounding rectangle (in logical units). -*`x3`*
-Specifies the x-coordinate of the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`x3`*\ +Specifies the x-coordinate of the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`y3`*
-Specifies the y-coordinate of the arc's starting point (in logical units). This point does not have to lie exactly on the arc. +*`y3`*\ +Specifies the y-coordinate of the arc's starting point (in logical units). This point doesn't have to lie exactly on the arc. -*`x4`*
-Specifies the x-coordinate of the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`x4`*\ +Specifies the x-coordinate of the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`y4`*
-Specifies the y-coordinate of the arc's endpoint (in logical units). This point does not have to lie exactly on the arc. +*`y4`*\ +Specifies the y-coordinate of the arc's endpoint (in logical units). This point doesn't have to lie exactly on the arc. -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter. -*`ptStart`*
-Specifies the starting point of the arc. This point does not have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. +*`ptStart`*\ +Specifies the starting point of the arc. This point doesn't have to lie exactly on the arc. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. -*`ptEnd`*
-Specifies the endpoint of the arc. This point does not have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter. +*`ptEnd`*\ +Specifies the endpoint of the arc. This point doesn't have to lie exactly on the arc. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -4323,9 +4324,9 @@ Nonzero if the function is successful; otherwise 0. The center of the arc is the center of the bounding rectangle specified by *`x1`*, *`y1`*, *`x2`*, and *`y2`* (or by *`lpRect`*). The starting and ending points of the arc are specified by *`x3`*, *`y3`*, *`x4`*, and *`y4`* (or by *`ptStart`* and *`ptEnd`*). -The arc is drawn with the selected pen, moving in a counterclockwise direction. Two additional lines are drawn from each endpoint to the arc's center. The pie-shaped area is filled with the current brush. If *`x3`* equals *`x4`* and *`y3`* equals *`y4`*, the result is an ellipse with a single line from the center of the ellipse to the point (*`x3`*, *`y3`*) or (*`x4`*, *`y4`*). +The arc is drawn with the selected pen, moving in a counterclockwise direction. Two more lines are drawn from each endpoint to the arc's center. The pie-shaped area is filled with the current brush. If *`x3`* equals *`x4`* and *`y3`* equals *`y4`*, the result is an ellipse with a single line from the center of the ellipse to the point (*`x3`*, *`y3`*) or (*`x4`*, *`y4`*). -The figure drawn by this function extends up to but does not include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the width and the height of the bounding rectangle must be greater than 2 units and less than 32,767 units. +The figure drawn by this function extends up to but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the width and the height of the bounding rectangle must be greater than 2 units and less than 32,767 units. ### Example @@ -4345,13 +4346,13 @@ BOOL PlayMetaFile( ### Parameters -*`hMF`*
+*`hMF`*\ Identifies the metafile to be played. -*`hEnhMetaFile`*
+*`hEnhMetaFile`*\ Identifies the enhanced metafile. -*`lpBounds`*
+*`lpBounds`*\ Points to a `RECT` structure or a `CRect` object that contains the coordinates of the bounding rectangle used to display the picture. The coordinates are specified in logical units. ### Return Value @@ -4387,31 +4388,31 @@ BOOL PlgBlt( ### Parameters -*`lpPoint`*
+*`lpPoint`*\ Points to an array of three points in logical space that identifies three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram. -*`pSrcDC`*
+*`pSrcDC`*\ Identifies the source device context. -*`xSrc`*
+*`xSrc`*\ Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle. -*`ySrc`*
+*`ySrc`*\ Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle. -*`nWidth`*
+*`nWidth`*\ Specifies the width, in logical units, of the source rectangle. -*`nHeight`*
+*`nHeight`*\ Specifies the height, in logical units, of the source rectangle. -*`maskBitmap`*
+*`maskBitmap`*\ Identifies an optional monochrome bitmap that is used to mask the colors of the source rectangle. -*`xMask`*
+*`xMask`*\ Specifies the x-coordinate of the upper-left corner of the monochrome bitmap. -*`yMask`*
+*`yMask`*\ Specifies the y-coordinate of the upper-left corner of the monochrome bitmap. ### Return Value @@ -4424,13 +4425,13 @@ If the given bitmask handle identifies a valid monochrome bitmap, the function u The fourth vertex of the parallelogram (D) is defined by treating the first three points (A, B, and C) as vectors and computing D = B + C - A. -If the bitmask exists, a value of 1 in the mask indicates that the source pixel color should be copied to the destination. A value of 0 in the mask indicates that the destination pixel color is not to be changed. +If the bitmask exists, a value of 1 in the mask indicates that the source pixel color should be copied to the destination. A value of 0 in the mask indicates that the destination pixel color isn't to be changed. If the mask rectangle is smaller than the source and destination rectangles, the function replicates the mask pattern. -Scaling, translation, and reflection transformations are allowed in the source device context; however, rotation and shear transformations are not. If the mask bitmap is not a monochrome bitmap, an error occurs. The stretching mode for the destination device context is used to determine how to stretch or compress the pixels, if that is necessary. When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context. +Scaling, translation, and reflection transformations are allowed in the source device context; however, rotation and shear transformations aren't. If the mask bitmap isn't a monochrome bitmap, an error occurs. The stretching mode for the destination device context is used to determine how to stretch or compress the pixels, if that is necessary. When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context. -The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. If the source transformation has a rotation or shear, an error is returned. If the destination and source rectangles do not have the same color format, `PlgBlt` converts the source rectangle to match the destination rectangle. Not all devices support `PlgBlt`. For more information, see the description of the `RC_BITBLT` raster capability in the `CDC::GetDeviceCaps` member function. +The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. If the source transformation has a rotation or shear, an error is returned. If the destination and source rectangles don't have the same color format, `PlgBlt` converts the source rectangle to match the destination rectangle. Not all devices support `PlgBlt`. For more information, see the description of the `RC_BITBLT` raster capability in the `CDC::GetDeviceCaps` member function. If the source and destination device contexts represent incompatible devices, `PlgBlt` returns an error. @@ -4446,11 +4447,11 @@ BOOL PolyBezier( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contain the endpoints and control points of the spline(s). -*`nCount`*
-Specifies the number of points in the *`lpPoints`* array. This value must be one more than three times the number of splines to be drawn, because each Bzier spline requires two control points and an endpoint, and the initial spline requires an additional starting point. +*`nCount`*\ +Specifies the number of points in the *`lpPoints`* array. This value must be one more than three times the number of splines to be drawn, because each Bzier spline requires two control points and an endpoint, and the initial spline requires another starting point. ### Return Value @@ -4460,7 +4461,7 @@ Nonzero if the function is successful; otherwise 0. This function draws cubic Bzier splines by using the endpoints and control points specified by the *`lpPoints`* parameter. The first spline is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent spline in the sequence needs exactly three more points: the end point of the previous spline is used as the starting point, the next two points in the sequence are control points, and the third is the end point. -The current position is neither used nor updated by the `PolyBezier` function. The figure is not filled. This function draws lines by using the current pen. +The current position isn't used or updated by the `PolyBezier` function. The figure isn't filled. This function draws lines by using the current pen. ## `CDC::PolyBezierTo` @@ -4474,10 +4475,10 @@ BOOL PolyBezierTo( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the endpoints and control points. -*`nCount`*
+*`nCount`*\ Specifies the number of points in the *`lpPoints`* array. This value must be three times the number of splines to be drawn, because each Bzier spline requires two control points and an end point. ### Return Value @@ -4486,7 +4487,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -This function draws cubic Bzier splines by using the control points specified by the *`lpPoints`* parameter. The first spline is drawn from the current position to the third point by using the first two points as control points. For each subsequent spline, the function needs exactly three more points, and uses the end point of the previous spline as the starting point for the next. `PolyBezierTo` moves the current position to the end point of the last Bzier spline. The figure is not filled. This function draws lines by using the current pen. +This function draws cubic Bzier splines by using the control points specified by the *`lpPoints`* parameter. The first spline is drawn from the current position to the third point by using the first two points as control points. For each subsequent spline, the function needs exactly three more points, and uses the end point of the previous spline as the starting point for the next. `PolyBezierTo` moves the current position to the end point of the last Bzier spline. The figure isn't filled. This function draws lines by using the current pen. ### Example @@ -4505,10 +4506,10 @@ BOOL PolyDraw( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the endpoints for each line segment and the endpoints and control points for each Bzier spline. -*`lpTypes`*
+*`lpTypes`*\ Points to an array that specifies how each point in the *`lpPoints`* array is used. Values can be one of the following: - `PT_MOVETO` Specifies that this point starts a disjoint figure. This point becomes the new current position. @@ -4517,7 +4518,7 @@ Points to an array that specifies how each point in the *`lpPoints`* array is us - `PT_BEZIERTO` Specifies that this point is a control point or ending point for a Bzier spline. -`PT_BEZIERTO` types always occur in sets of three. The current position defines the starting point for the Bzier spline. The first two `PT_BEZIERTO` points are the control points, and the third `PT_BEZIERTO` point is the ending point. The ending point becomes the new current position. If there are not three consecutive `PT_BEZIERTO` points, an error results. +`PT_BEZIERTO` types always occur in sets of three. The current position defines the starting point for the Bzier spline. The first two `PT_BEZIERTO` points are the control points, and the third `PT_BEZIERTO` point is the ending point. The ending point becomes the new current position. If there aren't three consecutive `PT_BEZIERTO` points, an error results. A `PT_LINETO` or `PT_BEZIERTO` type can be combined with the following constant by using the bitwise operator **OR** to indicate that the corresponding point is the last point in a figure and the figure is closed: @@ -4525,7 +4526,7 @@ Points to an array that specifies how each point in the *`lpPoints`* array is us This flag is combined with the `PT_LINETO` type for a line, or with the `PT_BEZIERTO` type of ending point for a Bzier spline, by using the bitwise **OR** operator. The current position is set to the ending point of the closing line. -*`nCount`*
+*`nCount`*\ Specifies the total number of points in the *`lpPoints`* array, the same as the number of bytes in the *`lpTypes`* array. ### Return Value @@ -4534,7 +4535,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -This function can be used to draw disjoint figures in place of consecutive calls to `CDC::MoveTo`, `CDC::LineTo`, and `CDC::PolyBezierTo` member functions. The lines and splines are drawn using the current pen, and figures are not filled. If there is an active path started by calling the `CDC::BeginPath` member function, `PolyDraw` adds to the path. The points contained in the *`lpPoints`* array and in *`lpTypes`* indicate whether each point is part of a `CDC::MoveTo`, a `CDC::LineTo`, or a `CDC::BezierTo` operation. It is also possible to close figures. This function updates the current position. +This function can be used to draw disjoint figures in place of consecutive calls to `CDC::MoveTo`, `CDC::LineTo`, and `CDC::PolyBezierTo` member functions. The lines and splines are drawn using the current pen, and figures aren't filled. If there's an active path started by calling the `CDC::BeginPath` member function, `PolyDraw` adds to the path. The points contained in the *`lpPoints`* array and in *`lpTypes`* indicate whether each point is part of a `CDC::MoveTo`, a `CDC::LineTo`, or a `CDC::BezierTo` operation. It's also possible to close figures. This function updates the current position. ### Example @@ -4552,10 +4553,10 @@ BOOL Polygon( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of points that specifies the vertices of the polygon. Each point in the array is a `POINT` structure or a `CPoint` object. -*`nCount`*
+*`nCount`*\ Specifies the number of vertices in the array. ### Return Value @@ -4584,10 +4585,10 @@ BOOL Polyline( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of `POINT` structures or `CPoint` objects to be connected. -*`nCount`*`
+*`nCount`*`\ Specifies the number of points in the array. This value must be at least 2. ### Return Value @@ -4596,7 +4597,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The lines are drawn from the first point through subsequent points using the current pen. Unlike the `LineTo` member function, the `Polyline` function neither uses nor updates the current position. +The lines are drawn from the first point through subsequent points using the current pen. Unlike the `LineTo` member function, the `Polyline` function doesn't use or update the current position. For more information, see [`PolyLine`](/windows/win32/api/wingdi/nf-wingdi-polyline) in the Windows SDK. @@ -4612,10 +4613,10 @@ BOOL PolylineTo( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of [`POINT`](/windows/win32/api/windef/ns-windef-point) data structures that contains the vertices of the line. -*`nCount`*
+*`nCount`*\ Specifies the number of points in the array. ### Return Value @@ -4624,7 +4625,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -A line is drawn from the current position to the first point specified by the *`lpPoints`* parameter by using the current pen. For each additional line, the function draws from the ending point of the previous line to the next point specified by *`lpPoints`*. `PolylineTo` moves the current position to the ending point of the last line. If the line segments drawn by this function form a closed figure, the figure is not filled. +A line is drawn from the current position to the first point specified by the *`lpPoints`* parameter by using the current pen. For each additional line, the function draws from the ending point of the previous line to the next point specified by *`lpPoints`*. `PolylineTo` moves the current position to the ending point of the last line. If the line segments drawn by this function form a closed figure, the figure isn't filled. ## `CDC::PolyPolygon` @@ -4639,13 +4640,13 @@ BOOL PolyPolygon( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of `POINT` structures or `CPoint` objects that define the vertices of the polygons. -*`lpPolyCounts`*
+*`lpPolyCounts`*\ Points to an array of integers, each of which specifies the number of points in one of the polygons in the *`lpPoints`* array. -*`nCount`*
+*`nCount`*\ The number of entries in the *`lpPolyCounts`* array. This number specifies the number of polygons to be drawn. This value must be at least 2. ### Return Value @@ -4656,7 +4657,7 @@ Nonzero if the function is successful; otherwise 0. The polygons may be disjoint or overlapping. -Each polygon specified in a call to the `PolyPolygon` function must be closed. Unlike polygons created by the `Polygon` member function, the polygons created by `PolyPolygon` are not closed automatically. +Each polygon specified in a call to the `PolyPolygon` function must be closed. Unlike polygons created by the `Polygon` member function, the polygons created by `PolyPolygon` aren't closed automatically. The function creates two or more polygons. To create a single polygon, an application should use the `Polygon` member function. @@ -4675,13 +4676,13 @@ BOOL PolyPolyline( ### Parameters -*`lpPoints`*
+*`lpPoints`*\ Points to an array of structures that contains the vertices of the polylines. The polylines are specified consecutively. -*`lpPolyPoints`*
+*`lpPolyPoints`*\ Points to an array of variables specifying the number of points in the *`lpPoints`* array for the corresponding polygon. Each entry must be greater than or equal to 2. -*`nCount`*
+*`nCount`*\ Specifies the total number of counts in the *`lpPolyPoints`* array. ### Return Value @@ -4690,7 +4691,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The line segments are drawn by using the current pen. The figures formed by the segments are not filled. The current position is neither used nor updated by this function. +The line segments are drawn by using the current pen. The figures formed by the segments aren't filled. The current position isn't used or updated by this function. ## `CDC::PtVisible` @@ -4706,13 +4707,13 @@ BOOL PtVisible(POINT point) const; ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the point. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the point. -*`point`*
+*`point`*\ Specifies the point to check in logical coordinates. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -4729,7 +4730,7 @@ BOOL QueryAbort() const; ### Return Value -The return value is nonzero if printing should continue or if there is no abort procedure. It is 0 if the print job should be terminated. The return value is supplied by the abort function. +The return value is nonzero if printing should continue or if there's no abort procedure. It's 0 if the print job should be terminated. The return value is supplied by the abort function. ## `CDC::RealizePalette` @@ -4767,19 +4768,19 @@ BOOL Rectangle(LPCRECT lpRect); ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the rectangle (in logical units). -*`lpRect`*
+*`lpRect`*\ Specifies the rectangle in logical units. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter. ### Return Value @@ -4790,7 +4791,7 @@ Nonzero if the function is successful; otherwise 0. The interior of the rectangle is filled using the current brush. -The rectangle extends up to, but does not include, the right and bottom coordinates. This means that the height of the rectangle is *`y2`* - *`y1`* and the width of the rectangle is *`x2`* - *`x1`*. Both the width and the height of a rectangle must be greater than 2 units and less than 32,767 units. +The rectangle extends up to, but doesn't include, the right and bottom coordinates. This means that the height of the rectangle is *`y2`* - *`y1`* and the width of the rectangle is *`x2`* - *`x1`*. Both the width and the height of a rectangle must be greater than 2 units and less than 32,767 units. ### Example @@ -4806,7 +4807,7 @@ virtual BOOL RectVisible(LPCRECT lpRect) const; ### Parameters -*`lpRect`*
+*`lpRect`*\ Points to a `RECT` structure or a `CRect` object that contains the logical coordinates of the specified rectangle. ### Return Value @@ -4823,7 +4824,7 @@ virtual void ReleaseAttribDC(); ### Remarks -This does not cause a `Detach` to occur. Only the output device context is attached to the `CDC` object, and only it can be detached. +This doesn't cause a `Detach` to occur. Only the output device context is attached to the `CDC` object, and only it can be detached. ## `CDC::ReleaseOutputDC` @@ -4847,7 +4848,7 @@ BOOL ResetDC(const DEVMODE* lpDevMode); ### Parameters -*`lpDevMode`*
+*`lpDevMode`*\ A pointer to a Windows `DEVMODE` structure. ### Return Value @@ -4874,7 +4875,7 @@ virtual BOOL RestoreDC(int nSavedDC); ### Parameters -*`nSavedDC`*
+*`nSavedDC`*\ Specifies the device context to be restored. It can be a value returned by a previous `SaveDC` function call. If *`nSavedDC`* is -1, the most recently saved device context is restored. ### Return Value @@ -4885,7 +4886,7 @@ Nonzero if the specified context was restored; otherwise 0. `RestoreDC` restores the device context by popping state information off a stack created by earlier calls to the `SaveDC` member function. -The stack can contain the state information for several device contexts. If the context specified by *`nSavedDC`* is not at the top of the stack, `RestoreDC` deletes all state information between the device context specified by *`nSavedDC`* and the top of the stack. The deleted information is lost. +The stack can contain the state information for several device contexts. If the context specified by *`nSavedDC`* isn't at the top of the stack, `RestoreDC` deletes all state information between the device context specified by *`nSavedDC`* and the top of the stack. The deleted information is lost. ## `CDC::RoundRect` @@ -4907,28 +4908,28 @@ BOOL RoundRect( ### Parameters -*`x1`*
+*`x1`*\ Specifies the x-coordinate of the upper-left corner of the rectangle (in logical units). -*`y1`*
+*`y1`*\ Specifies the y-coordinate of the upper-left corner of the rectangle (in logical units). -*`x2`*
+*`x2`*\ Specifies the x-coordinate of the lower-right corner of the rectangle (in logical units). -*`y2`*
+*`y2`*\ Specifies the y-coordinate of the lower-right corner of the rectangle (in logical units). -*`x3`*
+*`x3`*\ Specifies the width of the ellipse used to draw the rounded corners (in logical units). -*`y3`*
+*`y3`*\ Specifies the height of the ellipse used to draw the rounded corners (in logical units). -*`lpRect`*
+*`lpRect`*\ Specifies the bounding rectangle in logical units. You can pass either a `CRect` object or a pointer to a `RECT` structure for this parameter. -*`point`*
+*`point`*\ The x-coordinate of *`point`* specifies the width of the ellipse to draw the rounded corners (in logical units). The y-coordinate of *`point`* specifies the height of the ellipse to draw the rounded corners (in logical units). You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -4939,7 +4940,7 @@ Nonzero if the function is successful; otherwise 0. The interior of the rectangle is filled using the current brush. -The figure this function draws extends up to but does not include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the height and the width of the bounding rectangle must be greater than 2 units and less than 32,767 units. +The figure this function draws extends up to but doesn't include the right and bottom coordinates. This means that the height of the figure is *`y2`* - *`y1`* and the width of the figure is *`x2`* - *`x1`*. Both the height and the width of the bounding rectangle must be greater than 2 units and less than 32,767 units. ### Example @@ -4955,7 +4956,7 @@ virtual int SaveDC(); ### Return Value -An integer identifying the saved device context. It is 0 if an error occurs. This return value can be used to restore the device context by calling `RestoreDC`. +An integer identifying the saved device context. It's 0 if an error occurs. This return value can be used to restore the device context by calling `RestoreDC`. ### Remarks @@ -4977,16 +4978,16 @@ virtual CSize ScaleViewportExt( ### Parameters -*`xNum`*
+*`xNum`*\ Specifies the amount by which to multiply the current x-extent. -*`xDenom`*
+*`xDenom`*\ Specifies the amount by which to divide the result of multiplying the current x-extent by the value of the *`xNum`* parameter. -*`yNum`*
+*`yNum`*\ Specifies the amount by which to multiply the current y-extent. -*`yDenom`*
+*`yDenom`*\ Specifies the amount by which to divide the result of multiplying the current y-extent by the value of the *`yNum`* parameter. ### Return Value @@ -5017,16 +5018,16 @@ virtual CSize ScaleWindowExt( ### Parameters -*`xNum`*
+*`xNum`*\ Specifies the amount by which to multiply the current x-extent. -*`xDenom`*
+*`xDenom`*\ Specifies the amount by which to divide the result of multiplying the current x-extent by the value of the *`xNum`* parameter. -*`yNum`*
+*`yNum`*\ Specifies the amount by which to multiply the current y-extent. -*`yDenom`*
+*`yDenom`*\ Specifies the amount by which to divide the result of multiplying the current y-extent by the value of the *`yNum`* parameter. ### Return Value @@ -5059,22 +5060,22 @@ BOOL ScrollDC( ### Parameters -*`dx`*
+*`dx`*\ Specifies the number of horizontal scroll units. -*`dy`*
+*`dy`*\ Specifies the number of vertical scroll units. -*`lpRectScroll`*
+*`lpRectScroll`*\ Points to the `RECT` structure or `CRect` object that contains the coordinates of the scrolling rectangle. -*`lpRectClip`*
+*`lpRectClip`*\ Points to the `RECT` structure or `CRect` object that contains the coordinates of the clipping rectangle. When this rectangle is smaller than the original one pointed to by *`lpRectScroll`*, scrolling occurs only in the smaller rectangle. -*`pRgnUpdate`*
-Identifies the region uncovered by the scrolling process. The `ScrollDC` function defines this region; it is not necessarily a rectangle. +*`pRgnUpdate`*\ +Identifies the region uncovered by the scrolling process. The `ScrollDC` function defines this region; it isn't necessarily a rectangle. -*`lpRectUpdate`*
+*`lpRectUpdate`*\ Points to the `RECT` structure or `CRect` object that receives the coordinates of the rectangle that bounds the scrolling update region. This is the largest rectangular area that requires repainting. The values in the structure or object when the function returns are in client coordinates, regardless of the mapping mode for the given device context. ### Return Value @@ -5083,9 +5084,9 @@ Nonzero if scrolling is executed; otherwise 0. ### Remarks -If *`lpRectUpdate`* is `NULL`, Windows does not compute the update rectangle. If both *`pRgnUpdate`* and *`lpRectUpdate`* are `NULL`, Windows does not compute the update region. If *`pRgnUpdate`* is not `NULL`, Windows assumes that it contains a valid pointer to the region uncovered by the scrolling process (defined by the `ScrollDC` member function). The update region returned in *`lpRectUpdate`* can be passed to `CWnd::InvalidateRgn` if required. +If *`lpRectUpdate`* is `NULL`, Windows doesn't compute the update rectangle. If both *`pRgnUpdate`* and *`lpRectUpdate`* are `NULL`, Windows doesn't compute the update region. If *`pRgnUpdate`* isn't `NULL`, Windows assumes that it contains a valid pointer to the region uncovered by the scrolling process (defined by the `ScrollDC` member function). The update region returned in *`lpRectUpdate`* can be passed to `CWnd::InvalidateRgn` if required. -An application should use the `ScrollWindow` member function of class `CWnd` when it is necessary to scroll the entire client area of a window. Otherwise, it should use `ScrollDC`. +An application should use the `ScrollWindow` member function of class `CWnd` when it's necessary to scroll the entire client area of a window. Otherwise, it should use `ScrollDC`. ## `CDC::SelectClipPath` @@ -5097,7 +5098,7 @@ BOOL SelectClipPath(int nMode); ### Parameters -*`nMode`*
+*`nMode`*\ Specifies the way to use the path. The following values are allowed: - `RGN_AND` The new clipping region includes the intersection (overlapping areas) of the current clipping region and the current path. @@ -5132,14 +5133,14 @@ int SelectClipRgn( ### Parameters -*`pRgn`*
+*`pRgn`*\ Identifies the region to be selected. - For the first version of this function, if this value is `NULL`, the entire client area is selected and output is still clipped to the window. - For the second version of this function, this handle can be `NULL` only when the `RGN_COPY` mode is specified. -*`nMode`*
+*`nMode`*\ Specifies the operation to be performed. It must be one of the following values: - `RGN_AND` The new clipping region combines the overlapping areas of the current clipping region and the region identified by *`pRgn`*. @@ -5158,7 +5159,7 @@ The region's type. It can be any of the following values: - `COMPLEXREGION` New clipping region has overlapping borders. -- `ERROR` Device context or region is not valid. +- `ERROR` Device context or region isn't valid. - `NULLREGION` New clipping region is empty. @@ -5187,33 +5188,33 @@ CGdiObject* SelectObject(CGdiObject* pObject); ### Parameters -*`pPen`*
+*`pPen`*\ A pointer to a [`CPen`](../../mfc/reference/cpen-class.md) object to be selected. -*`pBrush`*
+*`pBrush`*\ A pointer to a [`CBrush`](../../mfc/reference/cbrush-class.md) object to be selected. -*`pFont`*
+*`pFont`*\ A pointer to a [`CFont`](../../mfc/reference/cfont-class.md) object to be selected. -*`pBitmap`*
+*`pBitmap`*\ A pointer to a [`CBitmap`](../../mfc/reference/cbitmap-class.md) object to be selected. -*`pRgn`*
+*`pRgn`*\ A pointer to a [`CRgn`](../../mfc/reference/crgn-class.md) object to be selected. -*`pObject`*
+*`pObject`*\ A pointer to a [`CGdiObject`](../../mfc/reference/cgdiobject-class.md) object to be selected. ### Return Value -A pointer to the object being replaced. This is a pointer to an object of one of the classes derived from `CGdiObject`, such as `CPen`, depending on which version of the function is used. The return value is `NULL` if there is an error. This function may return a pointer to a temporary object. This temporary object is only valid during the processing of one Windows message. For more information, see `CGdiObject::FromHandle`. +A pointer to the object being replaced. This is a pointer to an object of one of the classes derived from `CGdiObject`, such as `CPen`, depending on which version of the function is used. The return value is `NULL` if there's an error. This function may return a pointer to a temporary object. This temporary object is only valid during the processing of one Windows message. For more information, see `CGdiObject::FromHandle`. The version of the member function that takes a region parameter performs the same task as the `SelectClipRgn` member function. Its return value can be any of the following: - `COMPLEXREGION` New clipping region has overlapping borders. -- `ERROR` Device context or region is not valid. +- `ERROR` Device context or region isn't valid. - `NULLREGION` New clipping region is empty. @@ -5223,9 +5224,9 @@ The version of the member function that takes a region parameter performs the sa Class `CDC` provides five versions specialized for particular kinds of GDI objects, including pens, brushes, fonts, bitmaps, and regions. The newly selected object replaces the previous object of the same type. For example, if *`pObject`* of the general version of `SelectObject` points to a [`CPen`](../../mfc/reference/cpen-class.md) object, the function replaces the current pen with the pen specified by *`pObject`*. -An application can select a bitmap into memory device contexts only and into only one memory device context at a time. The format of the bitmap must either be monochrome or compatible with the device context; if it is not, `SelectObject` returns an error. +An application can select a bitmap into memory device contexts only and into only one memory device context at a time. The format of the bitmap must either be monochrome or compatible with the device context; if it isn't, `SelectObject` returns an error. -For Windows 3.1 and later, the `SelectObject` function returns the same value whether it is used in a metafile or not. Under previous versions of Windows, `SelectObject` returned a nonzero value for success and 0 for failure when it was used in a metafile. +For Windows 3.1 and later, the `SelectObject` function returns the same value whether it's used in a metafile or not. Under previous versions of Windows, `SelectObject` returned a nonzero value for success and 0 for failure when it was used in a metafile. ## `CDC::SelectPalette` @@ -5239,21 +5240,21 @@ CPalette* SelectPalette( ### Parameters -*`pPalette`*
+*`pPalette`*\ Identifies the logical palette to be selected. This palette must already have been created with the `CPalette` member function [`CreatePalette`](../../mfc/reference/cpalette-class.md#createpalette). -*`bForceBackground`*
+*`bForceBackground`*\ Specifies whether the logical palette is forced to be a background palette. If *`bForceBackground`* is nonzero, the selected palette is always a background palette, regardless of whether the window has the input focus. If *`bForceBackground`* is 0 and the device context is attached to a window, the logical palette is a foreground palette when the window has the input focus. ### Return Value -A pointer to a `CPalette` object identifying the logical palette replaced by the palette specified by *`pPalette`*. It is `NULL` if there is an error. +A pointer to a `CPalette` object identifying the logical palette replaced by the palette specified by *`pPalette`*. It's `NULL` if there's an error. ### Remarks The new palette becomes the palette object used by GDI to control colors displayed in the device context and replaces the previous palette. -An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it is selected. If an application selects a palette into more than one device context, the device contexts must all belong to the same physical device. +An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it's selected. If an application selects a palette into more than one device context, the device contexts must all belong to the same physical device. ## `CDC::SelectStockObject` @@ -5265,7 +5266,7 @@ virtual CGdiObject* SelectStockObject(int nIndex); ### Parameters -*`nIndex`*
+*`nIndex`*\ Specifies the kind of stock object desired. It can be one of the following values: - `BLACK_BRUSH` Black brush. @@ -5296,7 +5297,7 @@ Specifies the kind of stock object desired. It can be one of the following value - `OEM_FIXED_FONT` OEM-dependent fixed font. -- `SYSTEM_FONT` The system font. By default, Windows uses the system font to draw menus, dialog-box controls, and other text. It is best, however, not to rely on `SYSTEM_FONT` to obtain the font used by dialogs and windows. Instead, use the `SystemParametersInfo` function with the `SPI_GETNONCLIENTMETRICS` parameter to retrieve the current font. `SystemParametersInfo` takes into account the current theme and provides font information for captions, menus, and message dialogs. +- `SYSTEM_FONT` The system font. By default, Windows uses the system font to draw menus, dialog-box controls, and other text. It's best, however, not to rely on `SYSTEM_FONT` to obtain the font used by dialogs and windows. Instead, use the `SystemParametersInfo` function with the `SPI_GETNONCLIENTMETRICS` parameter to retrieve the current font. `SystemParametersInfo` takes into account the current theme and provides font information for captions, menus, and message dialogs. - `SYSTEM_FIXED_FONT` The fixed-width system font used in Windows prior to version 3.0. This object is available for compatibility with earlier versions of Windows. @@ -5316,7 +5317,7 @@ int SetAbortProc(BOOL (CALLBACK* lpfn)(HDC, int)); ### Parameters -*`lpfn`*
+*`lpfn`*\ A pointer to the abort function to install as the abort procedure. For more about the callback function, see [Callback Function for `CDC::SetAbortProc`](callback-functions-used-by-mfc.md#setabortproc). ### Return Value @@ -5333,11 +5334,11 @@ Specifies the outcome of the `SetAbortProc` function. Some of the following valu ### Remarks -If an application is to allow the print job to be canceled during spooling, it must set the abort function before the print job is started with the [`StartDoc`](#startdoc) member function. The Print Manager calls the abort function during spooling to allow the application to cancel the print job or to process out-of-disk-space conditions. If no abort function is set, the print job will fail if there is not enough disk space for spooling. +If an application is to allow the print job to be canceled during spooling, it must set the abort function before the print job is started with the [`StartDoc`](#startdoc) member function. The Print Manager calls the abort function during spooling to allow the application to cancel the print job or to process out-of-disk-space conditions. If no abort function is set, the print job will fail if there isn't enough disk space for spooling. -Note that the features of Microsoft Visual C++ simplify the creation of the callback function passed to `SetAbortProc`. The address passed to the `EnumObjects` member function is a pointer to a function exported with `__declspec(dllexport)` and with the **`__stdcall`** calling convention. +The features of Microsoft Visual C++ simplify the creation of the callback function passed to `SetAbortProc`. The address passed to the `EnumObjects` member function is a pointer to a function exported with `__declspec(dllexport)` and with the **`__stdcall`** calling convention. -You also do not have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in +You also don't have to export the function name in an **`EXPORTS`** statement in your application's module-definition file. You can instead use the **`EXPORT`** function modifier, as in `BOOL CALLBACK EXPORT AFunction( HDC, int );` @@ -5345,7 +5346,7 @@ to cause the compiler to emit the proper export record for export by name withou Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback). -Also note that all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). +All callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article [Exceptions](../../mfc/exception-handling-in-mfc.md). ## `CDC::SetArcDirection` @@ -5357,7 +5358,7 @@ int SetArcDirection(int nArcDirection); ### Parameters -*`nArcDirection`*
+*`nArcDirection`*\ Specifies the new arc direction. This parameter can be either of the following values: - `AD_COUNTERCLOCKWISE` Figures drawn counterclockwise. @@ -5388,12 +5389,12 @@ virtual void SetAttribDC(HDC hDC); ### Parameters -*`hDC`*
+*`hDC`*\ A Windows device context. ### Remarks -This member function does not attach the device context to the `CDC` object. Only the output device context is attached to a `CDC` object. +This member function doesn't attach the device context to the `CDC` object. Only the output device context is attached to a `CDC` object. ## `CDC::SetBkColor` @@ -5405,7 +5406,7 @@ virtual COLORREF SetBkColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new background color. ### Return Value @@ -5428,12 +5429,12 @@ int SetBkMode(int nBkMode); ### Parameters -*`nBkMode`*
+*`nBkMode`*\ Specifies the mode to be set. This parameter can be either of the following values: - `OPAQUE` Background is filled with the current background color before the text, hatched brush, or pen is drawn. This is the default background mode. -- `TRANSPARENT` Background is not changed before drawing. +- `TRANSPARENT` Background isn't changed before drawing. ### Return Value @@ -5441,7 +5442,7 @@ The previous background mode. ### Remarks -The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that is not a solid line. +The background mode defines whether the system removes existing background colors on the drawing surface before drawing text, hatched brushes, or any pen style that isn't a solid line. ### Example @@ -5459,10 +5460,10 @@ UINT SetBoundsRect( ### Parameters -*`lpRectBounds`*
+*`lpRectBounds`*\ Points to a `RECT` structure or `CRect` object that is used to set the bounding rectangle. Rectangle dimensions are given in logical coordinates. This parameter can be `NULL`. -*`flags`*
+*`flags`*\ Specifies how the new rectangle will be combined with the accumulated rectangle. This parameter can be a combination of the following values: - `DCB_ACCUMULATE` Add the rectangle specified by *`lpRectBounds`* to the bounding rectangle (using a rectangle-union operation). @@ -5475,7 +5476,7 @@ Specifies how the new rectangle will be combined with the accumulated rectangle. The current state of the bounding rectangle, if the function is successful. Like *`flags`*, the return value can be a combination of **`DCB_`** values: -- `DCB_ACCUMULATE` The bounding rectangle is not empty. This value will always be set. +- `DCB_ACCUMULATE` The bounding rectangle isn't empty. This value will always be set. - `DCB_DISABLE` Bounds accumulation is off. @@ -5499,13 +5500,13 @@ CPoint SetBrushOrg(POINT point); ### Parameters -*`x`*
+*`x`*\ Specifies the x-coordinate (in device units) of the new origin. This value must be in the range 0-7. -*`y`*
+*`y`*\ Specifies the y-coordinate (in device units) of the new origin. This value must be in the range 0-7. -*`point`*
+*`point`*\ Specifies the x- and y-coordinates of the new origin. Each value must be in the range 0-7. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -5516,7 +5517,7 @@ The previous origin of the brush in device units. The default coordinates for the brush origin are (0, 0). To alter the origin of a brush, call the `UnrealizeObject` function for the `CBrush` object, call `SetBrushOrg`, and then call the `SelectObject` member function to select the brush into the device context. -Do not use `SetBrushOrg` with stock `CBrush` objects. +Don't use `SetBrushOrg` with stock `CBrush` objects. ## `CDC::SetColorAdjustment` @@ -5528,7 +5529,7 @@ BOOL SetColorAdjustment(const COLORADJUSTMENT* lpColorAdjust); ### Parameters -*`lpColorAdjust`*
+*`lpColorAdjust`*\ Points to a [`COLORADJUSTMENT`](/windows/win32/api/wingdi/ns-wingdi-coloradjustment) data structure containing the color adjustment values. ### Return Value @@ -5549,7 +5550,7 @@ COLORREF SetDCBrushColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new brush color. ### Return Value @@ -5572,7 +5573,7 @@ COLORREF SetDCPenColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new pen color. ### Return Value @@ -5593,7 +5594,7 @@ int SetGraphicsMode(int iMode); ### Parameters -*`iMode`*
+*`iMode`*\ Specifies the graphics mode. For a list of the values that this parameter can take, see [`SetGraphicsMode`](/windows/win32/api/wingdi/nf-wingdi-setgraphicsmode). ### Return Value @@ -5616,7 +5617,7 @@ DWORD SetLayout(DWORD dwLayout); ### Parameters -*`dwLayout`*
+*`dwLayout`*\ Device context layout and bitmap control flags. It can be a combination of the following values. |Value|Meaning| @@ -5633,7 +5634,7 @@ If unsuccessful, `GDI_ERROR`. To get extended error information, call [`GetLastE ### Remarks -Normally, you would not call `SetLayout` for a window. Rather, you control the right-to-left layout in a window by setting the [extended window styles](../../mfc/reference/styles-used-by-mfc.md#extended-window-styles) such as `WS_EX_RTLREADING`. A device context, such as a printer or a metafile, does not inherit this layout. The only way to set the device context for a right-to-left layout is by calling `SetLayout`. +Normally, you would not call `SetLayout` for a window. Rather, you control the right-to-left layout in a window by setting the [extended window styles](../../mfc/reference/styles-used-by-mfc.md#extended-window-styles) such as `WS_EX_RTLREADING`. A device context, such as a printer or a metafile, doesn't inherit this layout. The only way to set the device context for a right-to-left layout is by calling `SetLayout`. If you call **`SetLayout(LAYOUT_RTL)`**, `SetLayout` automatically changes the mapping mode to `MM_ISOTROPIC`. As a result, a subsequent call to [`GetMapMode`](#getmapmode) will return `MM_ISOTROPIC` instead of `MM_TEXT`. @@ -5651,10 +5652,10 @@ virtual int SetMapMode(int nMapMode); ### Parameters -*`nMapMode`*
+*`nMapMode`*\ Specifies the new mapping mode. It can be any one of the following values: -- `MM_ANISOTROPIC` Logical units are converted to arbitrary units with arbitrarily scaled axes. Setting the mapping mode to `MM_ANISOTROPIC` does not change the current window or viewport settings. To change the units, orientation, and scaling, call the [`SetWindowExt`](#setwindowext) and [`SetViewportExt`](#setviewportext) member functions. +- `MM_ANISOTROPIC` Logical units are converted to arbitrary units with arbitrarily scaled axes. Setting the mapping mode to `MM_ANISOTROPIC` doesn't change the current window or viewport settings. To change the units, orientation, and scaling, call the [`SetWindowExt`](#setwindowext) and [`SetViewportExt`](#setviewportext) member functions. - `MM_HIENGLISH` Each logical unit is converted to 0.001 inch. Positive x is to the right; positive y is up. @@ -5678,7 +5679,7 @@ The previous mapping mode. The mapping mode defines the unit of measure used to convert logical units to device units; it also defines the orientation of the device's x- and y-axes. GDI uses the mapping mode to convert logical coordinates into the appropriate device coordinates. The `MM_TEXT` mode allows applications to work in device pixels, where 1 unit is equal to 1 pixel. The physical size of a pixel varies from device to device. -The `MM_HIENGLISH`, `MM_HIMETRIC`, `MM_LOENGLISH`, `MM_LOMETRIC`, and `MM_TWIPS` modes are useful for applications that must draw in physically meaningful units (such as inches or millimeters). The `MM_ISOTROPIC` mode ensures a 1:1 aspect ratio, which is useful when it is important to preserve the exact shape of an image. The `MM_ANISOTROPIC` mode allows the x- and y-coordinates to be adjusted independently. +The `MM_HIENGLISH`, `MM_HIMETRIC`, `MM_LOENGLISH`, `MM_LOMETRIC`, and `MM_TWIPS` modes are useful for applications that must draw in physically meaningful units (such as inches or millimeters). The `MM_ISOTROPIC` mode ensures a 1:1 aspect ratio, which is useful when it's important to preserve the exact shape of an image. The `MM_ANISOTROPIC` mode allows the x- and y-coordinates to be adjusted independently. > [!NOTE] > If you call [`SetLayout`](#setlayout) to change the DC (device context) to right-to-left layout, `SetLayout` automatically changes the mapping mode to `MM_ISOTROPIC`. @@ -5697,7 +5698,7 @@ DWORD SetMapperFlags(DWORD dwFlag); ### Parameters -*`dwFlag`*
+*`dwFlag`*\ Specifies whether the font mapper attempts to match a font's aspect height and width to the device. When this value is `ASPECT_FILTERING`, the mapper selects only fonts whose x-aspect and y-aspect exactly match those of the specified device. ### Return Value @@ -5708,7 +5709,7 @@ The previous value of the font-mapper flag. An application can use `SetMapperFlags` to cause the font mapper to attempt to choose only a physical font that exactly matches the aspect ratio of the specified device. -An application that uses only raster fonts can use the `SetMapperFlags` function to ensure that the font selected by the font mapper is attractive and readable on the specified device. Applications that use scalable (TrueType) fonts typically do not use `SetMapperFlags`. +An application that uses only raster fonts can use the `SetMapperFlags` function to ensure that the font selected by the font mapper is attractive and readable on the specified device. Applications that use scalable (TrueType) fonts typically don't use `SetMapperFlags`. If no physical font has an aspect ratio that matches the specification in the logical font, GDI chooses a new aspect ratio and selects a font that matches this new aspect ratio. @@ -5722,7 +5723,7 @@ BOOL SetMiterLimit(float fMiterLimit); ### Parameters -*`fMiterLimit`*
+*`fMiterLimit`*\ Specifies the new miter limit for the device context. ### Return Value @@ -5743,12 +5744,12 @@ virtual void SetOutputDC(HDC hDC); ### Parameters -*`hDC`*
+*`hDC`*\ A Windows device context. ### Remarks -This member function can only be called when a device context has not been attached to the `CDC` object. This member function sets `m_hDC` but does not attach the device context to the `CDC` object. +This member function can only be called when a device context has not been attached to the `CDC` object. This member function sets `m_hDC` but doesn't attach the device context to the `CDC` object. ## `CDC::SetPixel` @@ -5767,25 +5768,25 @@ COLORREF SetPixel( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the point to be set. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the point to be set. -*`crColor`*
+*`crColor`*\ A `COLORREF` RGB value that specifies the color used to paint the point. See [`COLORREF`](/windows/win32/gdi/colorref) in the Windows SDK for a description of this value. -*`point`*
+*`point`*\ Specifies the logical x- and y-coordinates of the point to be set. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value -An RGB value for the color that the point is actually painted. This value can be different from that specified by *`crColor`* if an approximation of that color is used. If the function fails (if the point is outside the clipping region), the return value is -1. +An RGB value for the color that the point is painted. This value can be different from that specified by *`crColor`* if an approximation of that color is used. If the function fails (if the point is outside the clipping region), the return value is -1. ### Remarks -The point must be in the clipping region. If the point is not in the clipping region, the function does nothing. +The point must be in the clipping region. If the point isn't in the clipping region, the function does nothing. Not all devices support the `SetPixel` function. To determine whether a device supports `SetPixel`, call the `GetDeviceCaps` member function with the `RASTERCAPS` index and check the return value for the `RC_BITBLT` flag. @@ -5806,16 +5807,16 @@ BOOL SetPixelV( ### Parameters -*`x`*
+*`x`*\ Specifies the x-coordinate, in logical units, of the point to be set. -*`y`*
+*`y`*\ Specifies the y-coordinate, in logical units, of the point to be set. -*`crColor`*
+*`crColor`*\ Specifies the color to be used to paint the point. -*`point`*
+*`point`*\ Specifies the logical x- and y-coordinates of the point to be set. You can pass either a [`POINT`](/windows/win32/api/windef/ns-windef-point) data structure or a [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object for this parameter. ### Return Value @@ -5824,7 +5825,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The point must be in both the clipping region and the visible part of the device surface. Not all devices support the member function. For more information, see the `RC_BITBLT` capability in the `CDC::GetDeviceCaps` member function. `SetPixelV` is faster than `SetPixel` because it does not need to return the color value of the point actually painted. +The point must be in both the clipping region and the visible part of the device surface. Not all devices support the member function. For more information, see the `RC_BITBLT` capability in the `CDC::GetDeviceCaps` member function. `SetPixelV` is faster than `SetPixel` because it doesn't need to return the color value of the point painted. ## `CDC::SetPolyFillMode` @@ -5836,7 +5837,7 @@ int SetPolyFillMode(int nPolyFillMode); ### Parameters -*`nPolyFillMode`*
+*`nPolyFillMode`*\ Specifies the new filling mode. This value may be either `ALTERNATE` or `WINDING`. The default mode set in Windows is `ALTERNATE`. ### Return Value @@ -5859,7 +5860,7 @@ int SetROP2(int nDrawMode); ### Parameters -*`nDrawMode`*
+*`nDrawMode`*\ Specifies the new drawing mode. It can be any of the following values: - `R2_BLACK` Pixel is always black. @@ -5904,7 +5905,7 @@ It can be any of the values given in the Windows SDK. The drawing mode specifies how the colors of the pen and the interior of filled objects are combined with the color already on the display surface. -The drawing mode is for raster devices only; it does not apply to vector devices. Drawing modes are binary raster-operation codes representing all possible Boolean combinations of two variables, using the binary operators `&`, `|`, and `^` (exclusive `|`), and the unary operation `~`. +The drawing mode is for raster devices only; it doesn't apply to vector devices. Drawing modes are binary raster-operation codes representing all possible Boolean combinations of two variables, using the binary operators `&`, `|`, and `^` (exclusive `|`), and the unary operation `~`. ## `CDC::SetStretchBltMode` @@ -5916,7 +5917,7 @@ int SetStretchBltMode(int nStretchMode); ### Parameters -*`nStretchMode`*
+*`nStretchMode`*\ Specifies the stretching mode. It can be any of the following values: |Value|Description| @@ -5941,9 +5942,9 @@ The bitmap-stretching mode defines how information is removed from bitmaps that The `BLACKONWHITE`(`STRETCH_ANDSCANS`) and `WHITEONBLACK`(`STRETCH_ORSCANS`) modes are typically used to preserve foreground pixels in monochrome bitmaps. The `COLORONCOLOR`(`STRETCH_DELETESCANS`) mode is typically used to preserve color in color bitmaps. -The `HALFTONE` mode requires more processing of the source image than the other three modes; it is slower than the others, but produces higher quality images. Also note that `SetBrushOrgEx` must be called after setting the `HALFTONE` mode to avoid brush misalignment. +The `HALFTONE` mode requires more processing of the source image than the other three modes; it's slower than the others, but produces higher quality images. Also, `SetBrushOrgEx` must be called after setting the `HALFTONE` mode to avoid brush misalignment. -Additional stretching modes might also be available depending on the capabilities of the device driver. +More stretching modes might also be available depending on the capabilities of the device driver. ## `CDC::SetTextAlign` @@ -5955,7 +5956,7 @@ UINT SetTextAlign(UINT nFlags); ### Parameters -*`nFlags`*
+*`nFlags`*\ Specifies text-alignment flags. The flags specify the relationship between a point and a rectangle that bounds the text. The point can be either the current position or coordinates specified by a text-output function. The rectangle that bounds the text is defined by the adjacent character cells in the text string. The *`nFlags`* parameter can be one or more flags from the following three categories. Choose only one flag from each category. The first category affects text alignment in the x-direction: - `TA_CENTER` Aligns the point with the horizontal center of the bounding rectangle. @@ -5974,7 +5975,7 @@ The second category affects text alignment in the y-direction: The third category determines whether the current position is updated when text is written: -- `TA_NOUPDATECP` Does not update the current position after each call to a text-output function. This is the default setting. +- `TA_NOUPDATECP` Doesn't update the current position after each call to a text-output function. This is the default setting. - `TA_UPDATECP` Updates the current x-position after each call to a text-output function. The new position is at the right side of the bounding rectangle for the text. When this flag is set, the coordinates specified in calls to the `TextOut` member function are ignored. @@ -5996,8 +5997,8 @@ int SetTextCharacterExtra(int nCharExtra); ### Parameters -*`nCharExtra`*
-Specifies the amount of extra space (in logical units) to be added to each character. If the current mapping mode is not `MM_TEXT`, *`nCharExtra`* is transformed and rounded to the nearest pixel. +*`nCharExtra`*\ +Specifies the amount of extra space (in logical units) to be added to each character. If the current mapping mode isn't `MM_TEXT`, *`nCharExtra`* is transformed and rounded to the nearest pixel. ### Return Value @@ -6017,7 +6018,7 @@ virtual COLORREF SetTextColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the color of the text as an RGB color value. ### Return Value @@ -6026,7 +6027,7 @@ An RGB value for the previous text color. ### Remarks -The system will use this text color when writing text to this device context and also when converting bitmaps between color and monochrome device contexts. +The system uses this text color when writing text to this device context and also when converting bitmaps between color and monochrome device contexts. If the device cannot represent the specified color, the system sets the text color to the nearest physical color. The background color for a character is specified by the `SetBkColor` and `SetBkMode` member functions. @@ -6046,10 +6047,10 @@ int SetTextJustification( ### Parameters -*`nBreakExtra`*
-Specifies the total extra space to be added to the line of text (in logical units). If the current mapping mode is not `MM_TEXT`, the value given by this parameter is converted to the current mapping mode and rounded to the nearest device unit. +*`nBreakExtra`*\ +Specifies the total extra space to be added to the line of text (in logical units). If the current mapping mode isn't `MM_TEXT`, the value given by this parameter is converted to the current mapping mode and rounded to the nearest device unit. -*`nBreakCount`*
+*`nBreakCount`*\ Specifies the number of break characters in the line. ### Return Value @@ -6084,13 +6085,13 @@ CSize SetViewportExt(SIZE size); ### Parameters -*`cx`*
+*`cx`*\ Specifies the x-extent of the viewport (in device units). -*`cy`*
+*`cy`*\ Specifies the y-extent of the viewport (in device units). -*`size`*
+*`size`*\ Specifies the x- and y-extents of the viewport (in device units). ### Return Value @@ -6128,13 +6129,13 @@ CPoint SetViewportOrg(POINT point); ### Parameters -*`x`*
+*`x`*\ Specifies the x-coordinate (in device units) of the origin of the viewport. The value must be within the range of the device coordinate system. -*`y`*
+*`y`*\ Specifies the y-coordinate (in device units) of the origin of the viewport. The value must be within the range of the device coordinate system. -*`point`*
+*`point`*\ Specifies the origin of the viewport. The values must be within the range of the device coordinate system. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -6165,13 +6166,13 @@ CSize SetWindowExt(SIZE size); ### Parameters -*`cx`*
+*`cx`*\ Specifies the x-extent (in logical units) of the window. -*`cy`*
+*`cy`*\ Specifies the y-extent (in logical units) of the window. -*`size`*
+*`size`*\ Specifies the x- and y-extents (in logical units) of the window. ### Return Value @@ -6216,13 +6217,13 @@ CPoint SetWindowOrg(POINT point); ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the new origin of the window. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the new origin of the window. -*`point`*
+*`point`*\ Specifies the logical coordinates of the new origin of the window. You can pass either a `POINT` structure or a `CPoint` object for this parameter. ### Return Value @@ -6245,7 +6246,7 @@ BOOL SetWorldTransform(const XFORM& rXform); ### Parameters -*`rXform`*
+*`rXform`*\ Reference to an [`XFORM`](/windows/win32/api/wingdi/ns-wingdi-xform) structure that contains the transformation data. ### Return Value @@ -6271,10 +6272,10 @@ int StartDoc(LPCTSTR lpszDocName); ### Parameters -*`lpDocInfo`*
+*`lpDocInfo`*\ Points to a [`DOCINFO`](/windows/win32/api/wingdi/ns-wingdi-docinfow) structure containing the name of the document file and the name of the output file. -*`lpszDocName`*
+*`lpszDocName`*\ Pointer to a string containing the name of the document file. ### Return Value @@ -6285,11 +6286,11 @@ If the function fails, the return value is less than or equal to zero. ### Remarks -This ensures that documents longer than one page will not be interspersed with other jobs. +This ensures that documents longer than one page won't be interspersed with other jobs. -For Windows versions 3.1 and later, this function replaces the `STARTDOC` printer escape. Using this function ensures that documents containing more than one page are not interspersed with other print jobs. +For Windows versions 3.1 and later, this function replaces the `STARTDOC` printer escape. Using this function ensures that documents containing more than one page aren't interspersed with other print jobs. -`StartDoc` should not be used inside metafiles. +`StartDoc` shouldn't be used inside metafiles. ### Example @@ -6341,34 +6342,34 @@ BOOL StretchBlt( ### Parameters -*`x`*
+*`x`*\ Specifies the x-coordinate (in logical units) of the upper-left corner of the destination rectangle. -*`y`*
+*`y`*\ Specifies the y-coordinate (in logical units) of the upper-left corner of the destination rectangle. -*`nWidth`*
+*`nWidth`*\ Specifies the width (in logical units) of the destination rectangle. -*`nHeight`*
+*`nHeight`*\ Specifies the height (in logical units) of the destination rectangle. -*`pSrcDC`*
+*`pSrcDC`*\ Specifies the source device context. -*`xSrc`*
+*`xSrc`*\ Specifies the x-coordinate (in logical units) of the upper-left corner of the source rectangle. -*`ySrc`*
+*`ySrc`*\ Specifies the y-coordinate (in logical units) of the upper-left corner of the source rectangle. -*`nSrcWidth`*
+*`nSrcWidth`*\ Specifies the width (in logical units) of the source rectangle. -*`nSrcHeight`*
+*`nSrcHeight`*\ Specifies the height (in logical units) of the source rectangle. -*`dwRop`*
+*`dwRop`*\ Specifies the raster operation to be performed. Raster operation codes define how GDI combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. This parameter may be one of the following values: - `BLACKNESS` Turns all output black. @@ -6413,9 +6414,9 @@ The `StretchBlt` function moves the bitmap from the source device given by *`pSr The `StretchBlt` function creates a mirror image of a bitmap if the signs of the *`nSrcWidth`* and *`nWidth`* or *`nSrcHeight`* and *`nHeight`* parameters differ. If *`nSrcWidth`* and *`nWidth`* have different signs, the function creates a mirror image of the bitmap along the x-axis. If *`nSrcHeight`* and *`nHeight`* have different signs, the function creates a mirror image of the bitmap along the y-axis. -The `StretchBlt` function stretches or compresses the source bitmap in memory and then copies the result to the destination. If a pattern is to be merged with the result, it is not merged until the stretched source bitmap is copied to the destination. If a brush is used, it is the selected brush in the destination device context. The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. +The `StretchBlt` function stretches or compresses the source bitmap in memory and then copies the result to the destination. If a pattern is to be merged with the result, it isn't merged until the stretched source bitmap is copied to the destination. If a brush is used, it's the selected brush in the destination device context. The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. -If the destination, source, and pattern bitmaps do not have the same color format, `StretchBlt` converts the source and pattern bitmaps to match the destination bitmaps. The foreground and background colors of the destination device context are used in the conversion. +If the destination, source, and pattern bitmaps don't have the same color format, `StretchBlt` converts the source and pattern bitmaps to match the destination bitmaps. The foreground and background colors of the destination device context are used in the conversion. If `StretchBlt` must convert a monochrome bitmap to color, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert color to monochrome, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used. @@ -6435,7 +6436,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The device context must contain a closed path. The `StrokeAndFillPath` member function has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region will not overlap the stroked region even if the pen is wide. +The device context must contain a closed path. The `StrokeAndFillPath` member function has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region won't overlap the stroked region even if the pen is wide. ## `CDC::StrokePath` @@ -6478,28 +6479,28 @@ CSize TabbedTextOut( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the starting point of the string. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the starting point of the string. -*`lpszString`*
+*`lpszString`*\ Points to the character string to draw. You can pass either a pointer to an array of characters or a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object for this parameter. -*`nCount`*
+*`nCount`*\ Specifies the [length of the string](/windows/win32/gdi/specifying-length-of-text-output-string) pointed to by *`lpszString`*. -*`nTabPositions`*
+*`nTabPositions`*\ Specifies the number of values in the array of tab-stop positions. -*`lpnTabStopPositions`*
+*`lpnTabStopPositions`*\ Points to an array containing the tab-stop positions (in logical units). The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array. -*`nTabOrigin`*
+*`nTabOrigin`*\ Specifies the x-coordinate of the starting position from which tabs are expanded (in logical units). -*`str`*
+*`str`*\ A `CString` object that contains the specified characters. ### Return Value @@ -6512,7 +6513,7 @@ Text is written in the currently selected font. If *`nTabPositions`* is 0 and *` If *`nTabPositions`* is 1, the tab stops are separated by the distance specified by the first value in the *`lpnTabStopPositions`* array. If the *`lpnTabStopPositions`* array contains more than one value, a tab stop is set for each value in the array, up to the number specified by *`nTabPositions`*. The *`nTabOrigin`* parameter allows an application to call the `TabbedTextOut` function several times for a single line. If the application calls the function more than once with the *`nTabOrigin`* set to the same value each time, the function expands all tabs relative to the position specified by *`nTabOrigin`*. -By default, the current position is not used or updated by the function. If an application needs to update the current position when it calls the function, the application can call the [`SetTextAlign`](#settextalign) member function with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores the *`x`* and *`y`* parameters on subsequent calls to `TabbedTextOut`, using the current position instead. +By default, the current position isn't used or updated by the function. If an application needs to update the current position when it calls the function, the application can call the [`SetTextAlign`](#settextalign) member function with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores the *`x`* and *`y`* parameters on subsequent calls to `TabbedTextOut`, using the current position instead. ## `CDC::TextOut` @@ -6533,19 +6534,19 @@ BOOL TextOut( ### Parameters -*`x`*
+*`x`*\ Specifies the logical x-coordinate of the starting point of the text. -*`y`*
+*`y`*\ Specifies the logical y-coordinate of the starting point of the text. -*`lpszString`*
+*`lpszString`*\ Points to the character string to be drawn. -*`nCount`*
+*`nCount`*\ Specifies the number of characters in the string. -*`str`*
+*`str`*\ A `CString` object that contains the characters to be drawn. ### Return Value @@ -6554,7 +6555,7 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -Character origins are at the upper-left corner of the character cell. By default, the current position is not used or updated by the function. +Character origins are at the upper-left corner of the character cell. By default, the current position isn't used or updated by the function. If an application needs to update the current position when it calls `TextOut`, the application can call the `SetTextAlign` member function with *`nFlags`* set to `TA_UPDATECP`. When this flag is set, Windows ignores the *`x`* and *`y`* parameters on subsequent calls to `TextOut`, using the current position instead. @@ -6582,34 +6583,34 @@ BOOL TransparentBlt( ### Parameters -*`xDest`*
+*`xDest`*\ Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle. -*`yDest`*
+*`yDest`*\ Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle. -*`nDestWidth`*
+*`nDestWidth`*\ Specifies the width, in logical units, of the destination rectangle. -*`nDestHeight`*
+*`nDestHeight`*\ Specifies the height, in logical units, of the destination rectangle. -*`pSrcDC`*
+*`pSrcDC`*\ Pointer to the source device context. -*`xSrc`*
+*`xSrc`*\ Specifies the x-coordinate, in logical units, of the source rectangle. -*`ySrc`*
+*`ySrc`*\ Specifies the y-coordinate, in logical units, of the source rectangle. -*`nSrcWidth`*
+*`nSrcWidth`*\ Specifies the width, in logical units, of the source rectangle. -*`nSrcHeight`*
+*`nSrcHeight`*\ Specifies the height, in logical units, of the source rectangle. -*`clrTransparent`*
+*`clrTransparent`*\ The RGB color in the source bitmap to treat as transparent. ### Return Value @@ -6656,9 +6657,9 @@ This function is successful only if the current pen is a geometric pen created b ## See also -[`CObject` Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[`CPaintDC` Class](../../mfc/reference/cpaintdc-class.md)
-[`CWindowDC` Class](../../mfc/reference/cwindowdc-class.md)
-[`CClientDC` Class](../../mfc/reference/cclientdc-class.md)
+[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CPaintDC` Class](../../mfc/reference/cpaintdc-class.md)\ +[`CWindowDC` Class](../../mfc/reference/cwindowdc-class.md)\ +[`CClientDC` Class](../../mfc/reference/cclientdc-class.md)\ [`CMetaFileDC` Class](../../mfc/reference/cmetafiledc-class.md) diff --git a/docs/mfc/reference/cdhtmldialog-class.md b/docs/mfc/reference/cdhtmldialog-class.md index e0267db24a..82562ba5ad 100644 --- a/docs/mfc/reference/cdhtmldialog-class.md +++ b/docs/mfc/reference/cdhtmldialog-class.md @@ -4,9 +4,8 @@ title: "CDHtmlDialog Class" ms.date: "03/27/2019" f1_keywords: ["CDHtmlDialog", "AFXDHTML/CDHtmlDialog", "AFXDHTML/CDHtmlDialog::CDHtmlDialog", "AFXDHTML/CDHtmlDialog::CanAccessExternal", "AFXDHTML/CDHtmlDialog::CreateControlSite", "AFXDHTML/CDHtmlDialog::DDX_DHtml_AxControl", "AFXDHTML/CDHtmlDialog::DDX_DHtml_CheckBox", "AFXDHTML/CDHtmlDialog::DDX_DHtml_ElementText", "AFXDHTML/CDHtmlDialog::DDX_DHtml_Radio", "AFXDHTML/CDHtmlDialog::DDX_DHtml_SelectIndex", "AFXDHTML/CDHtmlDialog::DDX_DHtml_SelectString", "AFXDHTML/CDHtmlDialog::DDX_DHtml_SelectValue", "AFXDHTML/CDHtmlDialog::DestroyModeless", "AFXDHTML/CDHtmlDialog::EnableModeless", "AFXDHTML/CDHtmlDialog::FilterDataObject", "AFXDHTML/CDHtmlDialog::GetControlDispatch", "AFXDHTML/CDHtmlDialog::GetControlProperty", "AFXDHTML/CDHtmlDialog::GetCurrentUrl", "AFXDHTML/CDHtmlDialog::GetDHtmlDocument", "AFXDHTML/CDHtmlDialog::GetDropTarget", "AFXDHTML/CDHtmlDialog::GetElement", "AFXDHTML/CDHtmlDialog::GetElementHtml", "AFXDHTML/CDHtmlDialog::GetElementInterface", "AFXDHTML/CDHtmlDialog::GetElementProperty", "AFXDHTML/CDHtmlDialog::GetElementText", "AFXDHTML/CDHtmlDialog::GetEvent", "AFXDHTML/CDHtmlDialog::GetExternal", "AFXDHTML/CDHtmlDialog::GetHostInfo", "AFXDHTML/CDHtmlDialog::GetOptionKeyPath", "AFXDHTML/CDHtmlDialog::HideUI", "AFXDHTML/CDHtmlDialog::IsExternalDispatchSafe", "AFXDHTML/CDHtmlDialog::LoadFromResource", "AFXDHTML/CDHtmlDialog::Navigate", "AFXDHTML/CDHtmlDialog::OnBeforeNavigate", "AFXDHTML/CDHtmlDialog::OnDocumentComplete", "AFXDHTML/CDHtmlDialog::OnDocWindowActivate", "AFXDHTML/CDHtmlDialog::OnFrameWindowActivate", "AFXDHTML/CDHtmlDialog::OnInitDialog", "AFXDHTML/CDHtmlDialog::OnNavigateComplete", "AFXDHTML/CDHtmlDialog::ResizeBorder", "AFXDHTML/CDHtmlDialog::SetControlProperty", "AFXDHTML/CDHtmlDialog::SetElementHtml", "AFXDHTML/CDHtmlDialog::SetElementProperty", "AFXDHTML/CDHtmlDialog::SetElementText", "AFXDHTML/CDHtmlDialog::SetExternalDispatch", "AFXDHTML/CDHtmlDialog::SetHostFlags", "AFXDHTML/CDHtmlDialog::ShowContextMenu", "AFXDHTML/CDHtmlDialog::ShowUI", "AFXDHTML/CDHtmlDialog::TranslateAccelerator", "AFXDHTML/CDHtmlDialog::TranslateUrl", "AFXDHTML/CDHtmlDialog::UpdateUI", "AFXDHTML/CDHtmlDialog::m_bUseHtmlTitle", "AFXDHTML/CDHtmlDialog::m_nHtmlResID", "AFXDHTML/CDHtmlDialog::m_pBrowserApp", "AFXDHTML/CDHtmlDialog::m_spHtmlDoc", "AFXDHTML/CDHtmlDialog::m_strCurrentUrl", "AFXDHTML/CDHtmlDialog::m_szHtmlResID"] helpviewer_keywords: ["CDHtmlDialog [MFC], CDHtmlDialog", "CDHtmlDialog [MFC], CanAccessExternal", "CDHtmlDialog [MFC], CreateControlSite", "CDHtmlDialog [MFC], DDX_DHtml_AxControl", "CDHtmlDialog [MFC], DDX_DHtml_CheckBox", "CDHtmlDialog [MFC], DDX_DHtml_ElementText", "CDHtmlDialog [MFC], DDX_DHtml_Radio", "CDHtmlDialog [MFC], DDX_DHtml_SelectIndex", "CDHtmlDialog [MFC], DDX_DHtml_SelectString", "CDHtmlDialog [MFC], DDX_DHtml_SelectValue", "CDHtmlDialog [MFC], DestroyModeless", "CDHtmlDialog [MFC], EnableModeless", "CDHtmlDialog [MFC], FilterDataObject", "CDHtmlDialog [MFC], GetControlDispatch", "CDHtmlDialog [MFC], GetControlProperty", "CDHtmlDialog [MFC], GetCurrentUrl", "CDHtmlDialog [MFC], GetDHtmlDocument", "CDHtmlDialog [MFC], GetDropTarget", "CDHtmlDialog [MFC], GetElement", "CDHtmlDialog [MFC], GetElementHtml", "CDHtmlDialog [MFC], GetElementInterface", "CDHtmlDialog [MFC], GetElementProperty", "CDHtmlDialog [MFC], GetElementText", "CDHtmlDialog [MFC], GetEvent", "CDHtmlDialog [MFC], GetExternal", "CDHtmlDialog [MFC], GetHostInfo", "CDHtmlDialog [MFC], GetOptionKeyPath", "CDHtmlDialog [MFC], HideUI", "CDHtmlDialog [MFC], IsExternalDispatchSafe", "CDHtmlDialog [MFC], LoadFromResource", "CDHtmlDialog [MFC], Navigate", "CDHtmlDialog [MFC], OnBeforeNavigate", "CDHtmlDialog [MFC], OnDocumentComplete", "CDHtmlDialog [MFC], OnDocWindowActivate", "CDHtmlDialog [MFC], OnFrameWindowActivate", "CDHtmlDialog [MFC], OnInitDialog", "CDHtmlDialog [MFC], OnNavigateComplete", "CDHtmlDialog [MFC], ResizeBorder", "CDHtmlDialog [MFC], SetControlProperty", "CDHtmlDialog [MFC], SetElementHtml", "CDHtmlDialog [MFC], SetElementProperty", "CDHtmlDialog [MFC], SetElementText", "CDHtmlDialog [MFC], SetExternalDispatch", "CDHtmlDialog [MFC], SetHostFlags", "CDHtmlDialog [MFC], ShowContextMenu", "CDHtmlDialog [MFC], ShowUI", "CDHtmlDialog [MFC], TranslateAccelerator", "CDHtmlDialog [MFC], TranslateUrl", "CDHtmlDialog [MFC], UpdateUI", "CDHtmlDialog [MFC], m_bUseHtmlTitle", "CDHtmlDialog [MFC], m_nHtmlResID", "CDHtmlDialog [MFC], m_pBrowserApp", "CDHtmlDialog [MFC], m_spHtmlDoc", "CDHtmlDialog [MFC], m_strCurrentUrl", "CDHtmlDialog [MFC], m_szHtmlResID"] -ms.assetid: 3f941c85-87e1-4f0f-9cc5-ffee8498b312 --- -# CDHtmlDialog Class +# `CDHtmlDialog` Class Is used to create dialog boxes that use HTML rather than dialog resources to implement their user interface. @@ -22,72 +21,72 @@ class CDHtmlDialog : public CDialog, public CDHtmlEventSink |Name|Description| |----------|-----------------| -|[CDHtmlDialog::CDHtmlDialog](#cdhtmldialog)|Constructs a CDHtmlDialog object.| -|[CDHtmlDialog::~CDHtmlDialog](#_dtorcdhtmldialog)|Destroys a CDHtmlDialog object.| +|[`CDHtmlDialog::CDHtmlDialog`](#cdhtmldialog)|Constructs a CDHtmlDialog object.| +|[`CDHtmlDialog::~CDHtmlDialog`](#_dtorcdhtmldialog)|Destroys a CDHtmlDialog object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CDHtmlDialog::CanAccessExternal](#canaccessexternal)|Overridable that is called as an access check to see whether scripting objects on the loaded page can access the external dispatch of the control site. Checks to make sure the dispatch is either safe for scripting or the current zone allows for objects that are not safe for scripting.| -|[CDHtmlDialog::CreateControlSite](#createcontrolsite)|Overridable used to create a control site instance to host the WebBrowser control on the dialog.| -|[CDHtmlDialog::DDX_DHtml_AxControl](#ddx_dhtml_axcontrol)|Exchanges data between a member variable and the property value of an ActiveX control on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_CheckBox](#ddx_dhtml_checkbox)|Exchanges data between a member variable and a check box on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_ElementText](#ddx_dhtml_elementtext)|Exchanges data between a member variable and any HTML element property on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_Radio](#ddx_dhtml_radio)|Exchanges data between a member variable and a radio button on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_SelectIndex](#ddx_dhtml_selectindex)|Gets or sets the index of a list box on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_SelectString](#ddx_dhtml_selectstring)|Gets or sets the display text of a list box entry (based on the current index) on an HTML page.| -|[CDHtmlDialog::DDX_DHtml_SelectValue](#ddx_dhtml_selectvalue)|Gets or sets the value of a list box entry (based on the current index) on an HTML page.| -|[CDHtmlDialog::DestroyModeless](#destroymodeless)|Destroys a modeless dialog box.| -|[CDHtmlDialog::EnableModeless](#enablemodeless)|Enables modeless dialog boxes.| -|[CDHtmlDialog::FilterDataObject](#filterdataobject)|Allows the dialog to filter clipboard data objects created by the hosted browser.| -|[CDHtmlDialog::GetControlDispatch](#getcontroldispatch)|Retrieves the `IDispatch` interface on an ActiveX control embedded in the HTML document.| -|[CDHtmlDialog::GetControlProperty](#getcontrolproperty)|Retrieves the requested property of the specified ActiveX control.| -|[CDHtmlDialog::GetCurrentUrl](#getcurrenturl)|Retrieves the Uniform Resource Locator (URL) associated with the current document.| -|[CDHtmlDialog::GetDHtmlDocument](#getdhtmldocument)|Retrieves the IHTMLDocument2 interface on the currently loaded HTML document.| -|[CDHtmlDialog::GetDropTarget](#getdroptarget)|Called by the contained WebBrowser control when it is being used as a drop target to allow the dialog to supply an alternative [IDropTarget](/windows/win32/api/oleidl/nn-oleidl-idroptarget).| -|[CDHtmlDialog::GetElement](#getelement)|Gets an interface on an HTML element.| -|[CDHtmlDialog::GetElementHtml](#getelementhtml)|Retrieves the `innerHTML` property of an HTML element.| -|[CDHtmlDialog::GetElementInterface](#getelementinterface)|Retrieves the requested interface pointer from an HTML element.| -|[CDHtmlDialog::GetElementProperty](#getelementproperty)|Retrieves the value of an HTML element's property.| -|[CDHtmlDialog::GetElementText](#getelementtext)|Retrieves the `innerText` property of an HTML element.| -|[CDHtmlDialog::GetEvent](#getevent)|Gets the `IHTMLEventObj` pointer to the current event object.| -|[CDHtmlDialog::GetExternal](#getexternal)|Gets the host's `IDispatch` interface.| -|[CDHtmlDialog::GetHostInfo](#gethostinfo)|Retrieves the host's UI capabilities.| -|[CDHtmlDialog::GetOptionKeyPath](#getoptionkeypath)|Retrieves the registry key under which user preferences are stored.| -|[CDHtmlDialog::HideUI](#hideui)|Hides the host's UI.| -|[CDHtmlDialog::IsExternalDispatchSafe](#isexternaldispatchsafe)|Indicates whether the host's `IDispatch` interface is safe for scripting.| -|[CDHtmlDialog::LoadFromResource](#loadfromresource)|Loads the specified resource into the WebBrowser control.| -|[CDHtmlDialog::Navigate](#navigate)|Navigates to the specified URL.| -|[CDHtmlDialog::OnBeforeNavigate](#onbeforenavigate)|Called by the framework before a navigation event is fired.| -|[CDHtmlDialog::OnDocumentComplete](#ondocumentcomplete)|Called by the framework to notify an application when a document has reached the READYSTATE_COMPLETE state.| -|[CDHtmlDialog::OnDocWindowActivate](#ondocwindowactivate)|Called by the framework when the document window is activated or deactivated.| -|[CDHtmlDialog::OnFrameWindowActivate](#onframewindowactivate)|Called by the framework when the frame window is activated or deactivated.| -|[CDHtmlDialog::OnInitDialog](#oninitdialog)|Called in response to the WM_INITDIALOG message.| -|[CDHtmlDialog::OnNavigateComplete](#onnavigatecomplete)|Called by the framework after a navigation event is completed.| -|[CDHtmlDialog::ResizeBorder](#resizeborder)|Alerts the object that it needs to resize its border space.| -|[CDHtmlDialog::SetControlProperty](#setcontrolproperty)|Sets the property of an ActiveX control to a new value.| -|[CDHtmlDialog::SetElementHtml](#setelementhtml)|Sets the `innerHTML` property of an HTML element.| -|[CDHtmlDialog::SetElementProperty](#setelementproperty)|Sets a property of an HTML element.| -|[CDHtmlDialog::SetElementText](#setelementtext)|Sets the `innerText` property of an HTML element.| -|[CDHtmlDialog::SetExternalDispatch](#setexternaldispatch)|Sets the host's `IDispatch` interface.| -|[CDHtmlDialog::SetHostFlags](#sethostflags)|Sets the host's UI flags.| -|[CDHtmlDialog::ShowContextMenu](#showcontextmenu)|Called when a context menu is about to be displayed.| -|[CDHtmlDialog::ShowUI](#showui)|Shows the host's UI.| -|[CDHtmlDialog::TranslateAccelerator](#translateaccelerator)|Called to process menu accelerator-key messages.| -|[CDHtmlDialog::TranslateUrl](#translateurl)|Called to modify the URL to be loaded.| -|[CDHtmlDialog::UpdateUI](#updateui)|Called to notify the host that the command state has changed.| +|[`CDHtmlDialog::CanAccessExternal`](#canaccessexternal)|Overridable that is called as an access check to see whether scripting objects on the loaded page can access the external dispatch of the control site. Checks to make sure the dispatch is either safe for scripting or the current zone allows for objects that aren't safe for scripting.| +|[`CDHtmlDialog::CreateControlSite`](#createcontrolsite)|Overridable used to create a control site instance to host the WebBrowser control on the dialog.| +|[`CDHtmlDialog::DDX_DHtml_AxControl`](#ddx_dhtml_axcontrol)|Exchanges data between a member variable and the property value of an ActiveX control on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_CheckBox`](#ddx_dhtml_checkbox)|Exchanges data between a member variable and a check box on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_ElementText`](#ddx_dhtml_elementtext)|Exchanges data between a member variable and any HTML element property on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_Radio`](#ddx_dhtml_radio)|Exchanges data between a member variable and a radio button on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_SelectIndex`](#ddx_dhtml_selectindex)|Gets or sets the index of a list box on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_SelectString`](#ddx_dhtml_selectstring)|Gets or sets the display text of a list box entry (based on the current index) on an HTML page.| +|[`CDHtmlDialog::DDX_DHtml_SelectValue`](#ddx_dhtml_selectvalue)|Gets or sets the value of a list box entry (based on the current index) on an HTML page.| +|[`CDHtmlDialog::DestroyModeless`](#destroymodeless)|Destroys a modeless dialog box.| +|[`CDHtmlDialog::EnableModeless`](#enablemodeless)|Enables modeless dialog boxes.| +|[`CDHtmlDialog::FilterDataObject`](#filterdataobject)|Allows the dialog to filter clipboard data objects created by the hosted browser.| +|[`CDHtmlDialog::GetControlDispatch`](#getcontroldispatch)|Retrieves the `IDispatch` interface on an ActiveX control embedded in the HTML document.| +|[`CDHtmlDialog::GetControlProperty`](#getcontrolproperty)|Retrieves the requested property of the specified ActiveX control.| +|[`CDHtmlDialog::GetCurrentUrl`](#getcurrenturl)|Retrieves the Uniform Resource Locator (URL) associated with the current document.| +|[`CDHtmlDialog::GetDHtmlDocument`](#getdhtmldocument)|Retrieves the `IHTMLDocument2` interface on the currently loaded HTML document.| +|[`CDHtmlDialog::GetDropTarget`](#getdroptarget)|Called by the contained WebBrowser control when it's being used as a drop target to allow the dialog to supply an alternative [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget).| +|[`CDHtmlDialog::GetElement`](#getelement)|Gets an interface on an HTML element.| +|[`CDHtmlDialog::GetElementHtml`](#getelementhtml)|Retrieves the `innerHTML` property of an HTML element.| +|[`CDHtmlDialog::GetElementInterface`](#getelementinterface)|Retrieves the requested interface pointer from an HTML element.| +|[`CDHtmlDialog::GetElementProperty`](#getelementproperty)|Retrieves the value of an HTML element's property.| +|[`CDHtmlDialog::GetElementText`](#getelementtext)|Retrieves the `innerText` property of an HTML element.| +|[`CDHtmlDialog::GetEvent`](#getevent)|Gets the `IHTMLEventObj` pointer to the current event object.| +|[`CDHtmlDialog::GetExternal`](#getexternal)|Gets the host's `IDispatch` interface.| +|[`CDHtmlDialog::GetHostInfo`](#gethostinfo)|Retrieves the host's UI capabilities.| +|[`CDHtmlDialog::GetOptionKeyPath`](#getoptionkeypath)|Retrieves the registry key under which user preferences are stored.| +|[`CDHtmlDialog::HideUI`](#hideui)|Hides the host's UI.| +|[`CDHtmlDialog::IsExternalDispatchSafe`](#isexternaldispatchsafe)|Indicates whether the host's `IDispatch` interface is safe for scripting.| +|[`CDHtmlDialog::LoadFromResource`](#loadfromresource)|Loads the specified resource into the WebBrowser control.| +|[`CDHtmlDialog::Navigate`](#navigate)|Navigates to the specified URL.| +|[`CDHtmlDialog::OnBeforeNavigate`](#onbeforenavigate)|Called by the framework before a navigation event is fired.| +|[`CDHtmlDialog::OnDocumentComplete`](#ondocumentcomplete)|Called by the framework to notify an application when a document has reached the `READYSTATE_COMPLETE` state.| +|[`CDHtmlDialog::OnDocWindowActivate`](#ondocwindowactivate)|Called by the framework when the document window is activated or deactivated.| +|[`CDHtmlDialog::OnFrameWindowActivate`](#onframewindowactivate)|Called by the framework when the frame window is activated or deactivated.| +|[`CDHtmlDialog::OnInitDialog`](#oninitdialog)|Called in response to the `WM_INITDIALOG` message.| +|[`CDHtmlDialog::OnNavigateComplete`](#onnavigatecomplete)|Called by the framework after a navigation event is completed.| +|[`CDHtmlDialog::ResizeBorder`](#resizeborder)|Alerts the object that it needs to resize its border space.| +|[`CDHtmlDialog::SetControlProperty`](#setcontrolproperty)|Sets the property of an ActiveX control to a new value.| +|[`CDHtmlDialog::SetElementHtml`](#setelementhtml)|Sets the `innerHTML` property of an HTML element.| +|[`CDHtmlDialog::SetElementProperty`](#setelementproperty)|Sets a property of an HTML element.| +|[`CDHtmlDialog::SetElementText`](#setelementtext)|Sets the `innerText` property of an HTML element.| +|[`CDHtmlDialog::SetExternalDispatch`](#setexternaldispatch)|Sets the host's `IDispatch` interface.| +|[`CDHtmlDialog::SetHostFlags`](#sethostflags)|Sets the host's UI flags.| +|[`CDHtmlDialog::ShowContextMenu`](#showcontextmenu)|Called when a context menu is about to be displayed.| +|[`CDHtmlDialog::ShowUI`](#showui)|Shows the host's UI.| +|[`CDHtmlDialog::TranslateAccelerator`](#translateaccelerator)|Called to process menu accelerator-key messages.| +|[`CDHtmlDialog::TranslateUrl`](#translateurl)|Called to modify the URL to be loaded.| +|[`CDHtmlDialog::UpdateUI`](#updateui)|Called to notify the host that the command state has changed.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CDHtmlDialog::m_bUseHtmlTitle](#m_busehtmltitle)|Indicates whether to use the HTML document's title as the dialog caption.| -|[CDHtmlDialog::m_nHtmlResID](#m_nhtmlresid)|Resource ID of HTML resource to be displayed.| -|[CDHtmlDialog::m_pBrowserApp](#m_pbrowserapp)|A pointer to a Web browser application.| -|[CDHtmlDialog::m_spHtmlDoc](#m_sphtmldoc)|A pointer to an HTML document.| -|[CDHtmlDialog::m_strCurrentUrl](#m_strcurrenturl)|The current URL.| -|[CDHtmlDialog::m_szHtmlResID](#m_szhtmlresid)|String version of the HTML resource ID.| +|[`CDHtmlDialog::m_bUseHtmlTitle`](#m_busehtmltitle)|Indicates whether to use the HTML document's title as the dialog caption.| +|[`CDHtmlDialog::m_nHtmlResID`](#m_nhtmlresid)|Resource ID of HTML resource to be displayed.| +|[`CDHtmlDialog::m_pBrowserApp`](#m_pbrowserapp)|A pointer to a Web browser application.| +|[`CDHtmlDialog::m_spHtmlDoc`](#m_sphtmldoc)|A pointer to an HTML document.| +|[`CDHtmlDialog::m_strCurrentUrl`](#m_strcurrenturl)|The current URL.| +|[`CDHtmlDialog::m_szHtmlResID`](#m_szhtmlresid)|String version of the HTML resource ID.| ## Remarks @@ -97,48 +96,48 @@ class CDHtmlDialog : public CDialog, public CDHtmlEventSink ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) `CDHtmlSinkHandlerBase2` `CDHtmlSinkHandlerBase1` -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) `CDHtmlSinkHandler` -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CDHtmlEventSink` -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) `CDHtmlDialog` ## Requirements -**Header:** afxdhtml.h +**Header:** `afxdhtml.h` -## DDX_DHtml Helper Macros +## `DDX_DHtml` Helper Macros -The DDX_DHtml helper macros allow easy access to the commonly used properties of controls on an HTML page. +The `DDX_DHtml` helper macros allow easy access to the commonly used properties of controls on an HTML page. ### Data Exchange Macros |Name|Description| |-|-| -|[DDX_DHtml_ElementValue](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementvalue)|Sets or retrieves the Value property from the selected control.| -|[DDX_DHtml_ElementInnerText](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementinnertext)|Sets or retrieves the text between the start and end tags of the current element.| -|[DDX_DHtml_ElementInnerHtml](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementinnerhtml)|Sets or retrieves the HTML between the start and end tags of the current element.| -|[DDX_DHtml_Anchor_Href](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_anchor_href)|Sets or retrieves the destination URL or anchor point.| -|[DDX_DHtml_Anchor_Target](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_anchor_target)|Sets or retrieves the target window or frame.| -|[DDX_DHtml_Img_Src](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_img_src)|Sets or retrieves the name of an image or a video clip in the document.| -|[DDX_DHtml_Frame_Src](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_frame_src)|Sets or retrieves the URL of the associated frame.| -|[DDX_DHtml_IFrame_Src](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_iframe_src)|Sets or retrieves the URL of the associated frame.| +|[`DDX_DHtml_ElementValue`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementvalue)|Sets or retrieves the Value property from the selected control.| +|[`DDX_DHtml_ElementInnerText`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementinnertext)|Sets or retrieves the text between the start and end tags of the current element.| +|[`DDX_DHtml_ElementInnerHtml`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_elementinnerhtml)|Sets or retrieves the HTML between the start and end tags of the current element.| +|[`DDX_DHtml_Anchor_Href`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_anchor_href)|Sets or retrieves the destination URL or anchor point.| +|[`DDX_DHtml_Anchor_Target`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_anchor_target)|Sets or retrieves the target window or frame.| +|[`DDX_DHtml_Img_Src`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_img_src)|Sets or retrieves the name of an image or a video clip in the document.| +|[`DDX_DHtml_Frame_Src`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_frame_src)|Sets or retrieves the URL of the associated frame.| +|[`DDX_DHtml_IFrame_Src`](../../mfc/reference/ddx-dhtml-helper-macros.md#ddx_dhtml_iframe_src)|Sets or retrieves the URL of the associated frame.| -## CDHtmlDialog::CanAccessExternal +## `CDHtmlDialog::CanAccessExternal` -Overridable that is called as an access check to see whether scripting objects on the loaded page can access the external dispatch of the control site. Checks to make sure the dispatch is either safe for scripting or the current zone allows for objects that are not safe for scripting. +Overridable that is called as an access check to see whether scripting objects on the loaded page can access the external dispatch of the control site. Checks to make sure the dispatch is either safe for scripting or the current zone allows for objects that aren't safe for scripting. ``` virtual BOOL CanAccessExternal(); @@ -148,7 +147,7 @@ virtual BOOL CanAccessExternal(); Nonzero if successful; otherwise 0. -## CDHtmlDialog::CDHtmlDialog +## `CDHtmlDialog::CDHtmlDialog` Constructs a resource-based dynamic HTML dialog box. @@ -168,28 +167,28 @@ CDHtmlDialog( ### Parameters -*lpszTemplateName*
+*`lpszTemplateName`*\ The null-terminated string that is the name of a dialog-box template resource. -*szHtmlResID*
+*`szHtmlResID`*\ The null-terminated string that is the name of an HTML resource. -*pParentWnd*
-A pointer to the parent or owner window object (of type [CWnd](../../mfc/reference/cwnd-class.md)) to which the dialog object belongs. If it is NULL, the dialog object's parent window is set to the main application window. +*`pParentWnd`*\ +A pointer to the parent or owner window object (of type [`CWnd`](../../mfc/reference/cwnd-class.md)) to which the dialog object belongs. If it's `NULL`, the dialog object's parent window is set to the main application window. -*nIDTemplate*
+*`nIDTemplate`*\ Contains the ID number of a dialog-box template resource. -*nHtmlResID*
+*`nHtmlResID`*\ Contains the ID number of an HTML resource. ### Remarks -The second form of the constructor provides access to the dialog resource through the template name. The third form of the constructor provides access to the dialog resource through the ID of the resource template. Usually, the ID begins with the **IDD_** prefix. +The second form of the constructor provides access to the dialog resource through the template name. The third form of the constructor provides access to the dialog resource through the ID of the resource template. Usually, the ID begins with the **`IDD_`** prefix. -## CDHtmlDialog::~CDHtmlDialog +## `CDHtmlDialog::~CDHtmlDialog` -Destroys a CDHtmlDialog object. +Destroys a `CDHtmlDialog` object. ``` virtual ~CDHtmlDialog(); @@ -197,9 +196,9 @@ virtual ~CDHtmlDialog(); ### Remarks -The [CWnd::DestroyWindow](../../mfc/reference/cwnd-class.md#destroywindow) member function must be used to destroy modeless dialog boxes that are created by [CDialog::Create](../../mfc/reference/cdialog-class.md#create). +The [`CWnd::DestroyWindow`](../../mfc/reference/cwnd-class.md#destroywindow) member function must be used to destroy modeless dialog boxes that are created by [`CDialog::Create`](../../mfc/reference/cdialog-class.md#create). -## CDHtmlDialog::CreateControlSite +## `CDHtmlDialog::CreateControlSite` Overridable used to create a control site instance to host the WebBrowser control on the dialog. @@ -213,11 +212,11 @@ virtual BOOL CreateControlSite( ### Parameters -*pContainer*
-A pointer to the [COleControlContainer](../../mfc/reference/colecontrolcontainer-class.md) object +*`pContainer`*\ +A pointer to the [`COleControlContainer`](../../mfc/reference/colecontrolcontainer-class.md) object. -*ppSite*
-A pointer to a pointer to a [COleControlSite](../../mfc/reference/colecontrolsite-class.md). +*`ppSite`*\ +A pointer to a pointer to a [`COleControlSite`](../../mfc/reference/colecontrolsite-class.md). ### Return Value @@ -227,7 +226,7 @@ Nonzero if successful; otherwise 0. You can override this member function to return an instance of your own control site class. -## CDHtmlDialog::DDX_DHtml_AxControl +## `CDHtmlDialog::DDX_DHtml_AxControl` Exchanges data between a member variable and the property value of an ActiveX control on an HTML page. @@ -247,26 +246,26 @@ void DDX_DHtml_AxControl( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value of the object tag's ID parameter in the HTML source for the ActiveX control. -*dispId*
+*`dispId`*\ The dispatch ID of the property with which you want to exchange data. -*szPropName*
+*`szPropName`*\ The name of the property. -*var*
-The data member, of type VARIANT, [COleVariant](../../mfc/reference/colevariant-class.md), or [CComVariant](../../atl/reference/ccomvariant-class.md), that holds the value exchanged with the ActiveX control property. +*`var`*\ +The data member, of type `VARIANT`, [`COleVariant`](../../mfc/reference/colevariant-class.md), or [`CComVariant`](../../atl/reference/ccomvariant-class.md), that holds the value exchanged with the ActiveX control property. ### Example [!code-cpp[NVC_MFCHtmlHttp#1](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_1.cpp)] -## CDHtmlDialog::DDX_DHtml_CheckBox +## `CDHtmlDialog::DDX_DHtml_CheckBox` Exchanges data between a member variable and a check box on an HTML page. @@ -279,20 +278,20 @@ void DDX_DHtml_CheckBox( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's ID parameter. -*value*
+*`value`*\ The value being exchanged. ### Example [!code-cpp[NVC_MFCHtmlHttp#2](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_2.cpp)] -## CDHtmlDialog::DDX_DHtml_ElementText +## `CDHtmlDialog::DDX_DHtml_ElementText` Exchanges data between a member variable and any HTML element property on an HTML page. @@ -342,19 +341,19 @@ void DDX_DHtml_ElementText( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's ID parameter. -*dispId*
+*`dispId`*\ The dispatch ID of the HTML element with which you want to exchange data. -*value*
+*`value`*\ The value being exchanged. -## CDHtmlDialog::DDX_DHtml_Radio +## `CDHtmlDialog::DDX_DHtml_Radio` Exchanges data between a member variable and a radio button on an HTML page. @@ -367,16 +366,16 @@ void DDX_DHtml_Radio( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's ID parameter. -*value*
+*`value`*\ The value being exchanged. -## CDHtmlDialog::DDX_DHtml_SelectIndex +## `CDHtmlDialog::DDX_DHtml_SelectIndex` Gets or sets the index of a list box on an HTML page. @@ -389,16 +388,16 @@ void DDX_DHtml_SelectIndex( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's `id` parameter. -*value*
+*`value`*\ The value being exchanged. -## CDHtmlDialog::DDX_DHtml_SelectString +## `CDHtmlDialog::DDX_DHtml_SelectString` Gets or sets the display text of a list box entry (based on the current index) on an HTML page. @@ -411,16 +410,16 @@ void DDX_DHtml_SelectString( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's ID parameter. -*value*
+*`value`*\ The value being exchanged. -## CDHtmlDialog::DDX_DHtml_SelectValue +## `CDHtmlDialog::DDX_DHtml_SelectValue` Gets or sets the value of a list box entry (based on the current index) on an HTML page. @@ -433,20 +432,20 @@ void DDX_DHtml_SelectValue( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*szId*
+*`szId`*\ The value that you specified for the HTML control's ID parameter. -*value*
+*`value`*\ The value being exchanged. ### Example [!code-cpp[NVC_MFCHtmlHttp#3](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_3.cpp)] -## CDHtmlDialog::DestroyModeless +## `CDHtmlDialog::DestroyModeless` Detaches a modeless dialog box from the `CDHtmlDialog` object and destroys the object. @@ -454,7 +453,7 @@ Detaches a modeless dialog box from the `CDHtmlDialog` object and destroys the o void DestroyModeless(); ``` -## CDHtmlDialog::EnableModeless +## `CDHtmlDialog::EnableModeless` Enables modeless dialog boxes. @@ -464,18 +463,18 @@ STDMETHOD(EnableModeless)(BOOL fEnable); ### Parameters -*fEnable*
-See *fEnable* in [IDocHostUIHandler::EnableModeless](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753253\(v=vs.85\)) in the Windows SDK. +*`fEnable`*\ +See *`fEnable`* in [`IDocHostUIHandler::EnableModeless`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753253\(v=vs.85\)) in the Windows SDK. ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::EnableModeless](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753253\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::EnableModeless`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753253\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::FilterDataObject +## `CDHtmlDialog::FilterDataObject` Allows the dialog to filter clipboard data objects created by the hosted browser. @@ -487,23 +486,23 @@ STDMETHOD(FilterDataObject)( ### Parameters -*pDO*
-See *pDO* in [IDocHostUIHandler::FilterDataObject](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753254\(v=vs.85\)) in the Windows SDK. +*`pDO`*\ +See *`pDO`* in [`IDocHostUIHandler::FilterDataObject`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753254\(v=vs.85\)) in the Windows SDK. -*ppDORet*
-See *ppDORet* in `IDocHostUIHandler::FilterDataObject` in the Windows SDK. +*`ppDORet`*\ +See *`ppDORet`* in `IDocHostUIHandler::FilterDataObject` in the Windows SDK. ### Return Value -Returns S_FALSE. +Returns `S_FALSE`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::FilterDataObject](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753254\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::FilterDataObject`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753254\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::GetControlDispatch +## `CDHtmlDialog::GetControlDispatch` -Retrieves the `IDispatch` interface on an ActiveX control embedded in the HTML document returned by [GetDHtmlDocument](#getdhtmldocument). +Retrieves the `IDispatch` interface on an ActiveX control embedded in the HTML document returned by [`GetDHtmlDocument`](#getdhtmldocument). ``` HRESULT GetControlDispatch( @@ -513,17 +512,17 @@ HRESULT GetControlDispatch( ### Parameters -*szId*
+*`szId`*\ The HTML ID of an ActiveX control. -*ppdisp*
+*`ppdisp`*\ The `IDispatch` interface of the control if found in the Web page. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. -## CDHtmlDialog::GetControlProperty +## `CDHtmlDialog::GetControlProperty` Retrieves the requested property of the specified ActiveX control. @@ -543,27 +542,27 @@ VARIANT GetControlProperty( ### Parameters -*szId*
+*`szId`*\ The HTML ID of an ActiveX control. -*szPropName*
+*`szPropName`*\ The name of a property in the default locale of the current user. -*pdispControl*
+*`pdispControl`*\ The `IDispatch` pointer of an ActiveX control. -*dispId*
+*`dispId`*\ The dispatch ID of a property. ### Return Value -A variant containing the requested property or an empty variant if the control or property could not be found. +A variant containing the requested property or an empty variant if the control or property couldn't be found. ### Remarks The overloads are listed from least efficient at the top to most efficient at the bottom. -## CDHtmlDialog::GetCurrentUrl +## `CDHtmlDialog::GetCurrentUrl` Retrieves the Uniform Resource Locator (URL) associated with the current document. @@ -573,12 +572,12 @@ void GetCurrentUrl(CString& szUrl); ### Parameters -*szUrl*
-A [CString](../../atl-mfc-shared/reference/cstringt-class.md) object containing the URL to retrieve. +*`szUrl`*\ +A [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object containing the URL to retrieve. -## CDHtmlDialog::GetDHtmlDocument +## `CDHtmlDialog::GetDHtmlDocument` -Retrieves the [IHTMLDocument2](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752574\(v=vs.85\)) interface on the currently loaded HTML document. +Retrieves the [`IHTMLDocument2`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752574\(v=vs.85\)) interface on the currently loaded HTML document. ``` HRESULT GetDHtmlDocument(IHTMLDocument2 **pphtmlDoc); @@ -586,16 +585,16 @@ HRESULT GetDHtmlDocument(IHTMLDocument2 **pphtmlDoc); ### Parameters -*\*\*pphtmlDoc* +*`**pphtmlDoc`* A pointer to a pointer to an HTML document. ### Return Value -A standard HRESULT. Returns S_OK if successful. +A standard `HRESULT`. Returns `S_OK` if successful. -## CDHtmlDialog::GetDropTarget +## `CDHtmlDialog::GetDropTarget` -Called by the contained WebBrowser control when it is being used as a drop target to allow the dialog to supply an alternative [IDropTarget](/windows/win32/api/oleidl/nn-oleidl-idroptarget). +Called by the contained WebBrowser control when it's being used as a drop target to allow the dialog to supply an alternative [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget). ``` STDMETHOD(GetDropTarget)( @@ -605,23 +604,23 @@ STDMETHOD(GetDropTarget)( ### Parameters -*pDropTarget*
-See *pDropTarget* in [IDocHostUIHandler::GetDropTarget](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753255\(v=vs.85\)) in the Windows SDK. +*`pDropTarget`*\ +See *`pDropTarget`* in [`IDocHostUIHandler::GetDropTarget`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753255\(v=vs.85\)) in the Windows SDK. -*ppDropTarget*
-See *ppDropTarget* in `IDocHostUIHandler::GetDropTarget` in the Windows SDK. +*`ppDropTarget`*\ +See *`ppDropTarget`* in `IDocHostUIHandler::GetDropTarget` in the Windows SDK. ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::GetDropTarget](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753255\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::GetDropTarget`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753255\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::GetElement +## `CDHtmlDialog::GetElement` -Returns an interface on the HTML element specified by *szElementId*. +Returns an interface on the HTML element specified by *`szElementId`*. ``` HRESULT GetElement( @@ -636,31 +635,31 @@ HRESULT GetElement( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*ppdisp*
+*`ppdisp`*\ An `IDispatch` pointer to the requested element or collection of elements. -*pbCollection*
-A BOOL indicating whether the object represented by *ppdisp* is a single element or a collection of elements. +*`pbCollection`*\ +A `BOOL` indicating whether the object represented by *`ppdisp`* is a single element or a collection of elements. -*pphtmlElement*
+*`pphtmlElement`*\ An `IHTMLElement` pointer to the requested element. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks Use the first overload if you need to handle conditions in which there may be more than one element with the specified ID. You can use the last parameter to find out whether the returned interface pointer is to a collection or a single item. If the interface pointer is on a collection, you can query for the `IHTMLElementCollection` and use its `item` property to refer to the elements by ordinal position. -The second overload will fail if there is more than one element with the same ID in the page. +The second overload will fail if there's more than one element with the same ID in the page. -## CDHtmlDialog::GetElementHtml +## `CDHtmlDialog::GetElementHtml` -Retrieves the `innerHTML` property of the HTML element identified by *szElementId*. +Retrieves the `innerHTML` property of the HTML element identified by *`szElementId`*. ``` BSTR GetElementHtml(LPCTSTR szElementId); @@ -668,16 +667,16 @@ BSTR GetElementHtml(LPCTSTR szElementId); ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. ### Return Value -The `innerHTML` property of the HTML element identified by *szElementId* or NULL if the element could not be found. +The `innerHTML` property of the HTML element identified by *`szElementId`* or `NULL` if the element couldn't be found. -## CDHtmlDialog::GetElementInterface +## `CDHtmlDialog::GetElementInterface` -Retrieves the requested interface pointer from the HTML element identified by *szElementId*. +Retrieves the requested interface pointer from the HTML element identified by *`szElementId`*. ``` template HRESULT GetElementInterface( @@ -692,26 +691,26 @@ HRESULT GetElementInterface( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*ppvObj*
+*`ppvObj`*\ Address of a pointer that will be filled with the requested interface pointer if the element is found and the query succeeds. -*refiid*
+*`refiid`*\ The interface ID (IID) of the requested interface. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Example [!code-cpp[NVC_MFCHtmlHttp#4](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_4.cpp)] -## CDHtmlDialog::GetElementProperty +## `CDHtmlDialog::GetElementProperty` -Retrieves the value of the property identified by *dispId* from the HTML element identified by *szElementId*. +Retrieves the value of the property identified by *`dispId`* from the HTML element identified by *`szElementId`*. ``` VARIANT GetElementProperty( @@ -721,19 +720,19 @@ VARIANT GetElementProperty( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*dispId*
+*`dispId`*\ The dispatch ID of a property. ### Return Value -The value of the property or an empty variant if the property or element could not be found. +The value of the property or an empty variant if the property or element couldn't be found. -## CDHtmlDialog::GetElementText +## `CDHtmlDialog::GetElementText` -Retrieves the `innerText` property of the HTML element identified by *szElementId*. +Retrieves the `innerText` property of the HTML element identified by *`szElementId`*. ``` BSTR GetElementText(LPCTSTR szElementId); @@ -741,14 +740,14 @@ BSTR GetElementText(LPCTSTR szElementId); ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. ### Return Value -The `innerText` property of the HTML element identified by *szElementId* or NULL if the property or element could not be found. +The `innerText` property of the HTML element identified by *`szElementId`* or `NULL` if the property or element couldn't be found. -## CDHtmlDialog::GetEvent +## `CDHtmlDialog::GetEvent` Returns the `IHTMLEventObj` pointer to the current event object. @@ -758,18 +757,18 @@ HRESULT GetEvent(IHTMLEventObj** ppEventObj); ### Parameters -*ppEventObj*
+*`ppEventObj`*\ Address of a pointer that will be filled with the `IHTMLEventObj` interface pointer. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks This function should only be called from within a DHTML event handler. -## CDHtmlDialog::GetExternal +## `CDHtmlDialog::GetExternal` Gets the host's `IDispatch` interface. @@ -779,18 +778,18 @@ STDMETHOD(GetExternal)(IDispatch** ppDispatch); ### Parameters -*ppDispatch*
-See *ppDispatch* in [IDocHostUIHandler::GetExternal](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753256\(v=vs.85\)) in the Windows SDK. +*`ppDispatch`*\ +See *`ppDispatch`* in [`IDocHostUIHandler::GetExternal`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753256\(v=vs.85\)) in the Windows SDK. ### Return Value -Returns S_OK on success or E_NOTIMPL on failure. +Returns `S_OK` on success or `E_NOTIMPL` on failure. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::GetExternal](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753256\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::GetExternal`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753256\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::GetHostInfo +## `CDHtmlDialog::GetHostInfo` Retrieves the host's UI capabilities. @@ -800,18 +799,18 @@ STDMETHOD(GetHostInfo)(DOCHOSTUIINFO* pInfo); ### Parameters -*pInfo*
-See *pInfo* in [IDocHostUIHandler::GetHostInfo](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753257\(v=vs.85\)) in the Windows SDK. +*`pInfo`*\ +See *`pInfo`* in [`IDocHostUIHandler::GetHostInfo`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753257\(v=vs.85\)) in the Windows SDK. ### Return Value -Returns S_OK. +Returns `S_OK`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::GetHostInfo](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753257\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::GetHostInfo`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753257\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::GetOptionKeyPath +## `CDHtmlDialog::GetOptionKeyPath` Retrieves the registry key under which user preferences are stored. @@ -823,21 +822,21 @@ STDMETHOD(GetOptionKeyPath)( ### Parameters -*pchKey*
-See *pchKey* in [IDocHostUIHandler::GetOptionKeyPath](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753258\(v=vs.85\)) in the Windows SDK. +*`pchKey`*\ +See *`pchKey`* in [`IDocHostUIHandler::GetOptionKeyPath`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753258\(v=vs.85\)) in the Windows SDK. -*dw*
-See *dw* in `IDocHostUIHandler::GetOptionKeyPath` in the Windows SDK. +*`dw`*\ +See *`dw`* in `IDocHostUIHandler::GetOptionKeyPath` in the Windows SDK. ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::GetOptionKeyPath](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753258\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::GetOptionKeyPath`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753258\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::HideUI +## `CDHtmlDialog::HideUI` Hides the host's UI. @@ -847,13 +846,13 @@ STDMETHOD(HideUI)(void); ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::HideUI](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753259\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::HideUI`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753259\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::IsExternalDispatchSafe +## `CDHtmlDialog::IsExternalDispatchSafe` Indicates whether the host's `IDispatch` interface is safe for scripting. @@ -863,9 +862,9 @@ virtual BOOL IsExternalDispatchSafe(); ### Return Value -Returns FALSE. +Returns `FALSE`. -## CDHtmlDialog::LoadFromResource +## `CDHtmlDialog::LoadFromResource` Loads the specified resource into the WebBrowser control in the DHTML dialog. @@ -876,17 +875,17 @@ BOOL LoadFromResource(UINT nRes); ### Parameters -*lpszResource*
+*`lpszResource`*\ A pointer to a string containing the name of the resource to load. -*nRes*
+*`nRes`*\ The ID of the resource to load. ### Return Value -TRUE if successful; otherwise FALSE. +`TRUE` if successful; otherwise `FALSE`. -## CDHtmlDialog::m_bUseHtmlTitle +## `CDHtmlDialog::m_bUseHtmlTitle` Indicates whether to use the HTML document's title as the dialog caption. @@ -896,9 +895,9 @@ BOOL m_bUseHtmlTitle; ### Remarks -If **m**_ **bUseHtmlTitle** is TRUE, the dialog caption is set equal to the title of the HTML document; otherwise, the caption in the dialog resource is used. +If **`m_bUseHtmlTitle`** is `TRUE`, the dialog caption is set equal to the title of the HTML document; otherwise, the caption in the dialog resource is used. -## CDHtmlDialog::m_nHtmlResID +## `CDHtmlDialog::m_nHtmlResID` Resource ID of HTML resource to be displayed. @@ -910,7 +909,7 @@ UINT m_nHtmlResID; [!code-cpp[NVC_MFCHtmlHttp#5](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_5.cpp)] -## CDHtmlDialog::m_pBrowserApp +## `CDHtmlDialog::m_pBrowserApp` A pointer to a Web browser application. @@ -918,7 +917,7 @@ A pointer to a Web browser application. CComPtr m_pBrowserApp; ``` -## CDHtmlDialog::m_spHtmlDoc +## `CDHtmlDialog::m_spHtmlDoc` A pointer to an HTML document. @@ -926,7 +925,7 @@ A pointer to an HTML document. CComPtr m_spHtmlDoc; ``` -## CDHtmlDialog::m_strCurrentUrl +## `CDHtmlDialog::m_strCurrentUrl` The current URL. @@ -934,7 +933,7 @@ The current URL. CString m_strCurrentUrl; ``` -## CDHtmlDialog::m_szHtmlResID +## `CDHtmlDialog::m_szHtmlResID` String version of the HTML resource ID. @@ -946,9 +945,9 @@ LPTSTR m_szHtmlResID; [!code-cpp[NVC_MFCHtmlHttp#6](../../mfc/reference/codesnippet/cpp/cdhtmldialog-class_6.cpp)] -## CDHtmlDialog::Navigate +## `CDHtmlDialog::Navigate` -Navigates to the resource identified by the URL that is specified by *lpszURL*. +Navigates to the resource identified by the URL that is specified by *`lpszURL`*. ```cpp void Navigate( @@ -962,25 +961,25 @@ void Navigate( ### Parameters -*lpszURL*
+*`lpszURL`*\ A pointer to a string containing the URL to be targeted. -*dwFlags*
-The flags of a variable that specifies whether to add the resource to the history list, whether to read to the cache or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [BrowserNavConstants](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. +*`dwFlags`*\ +The flags of a variable that specifies whether to add the resource to the history list, whether to read to the cache or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [`BrowserNavConstants`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. -*lpszTargetFrameName*
+*`lpszTargetFrameName`*\ A pointer to a string that contains the name of the frame in which to display the resource. -*lpszHeaders*
-A pointer to a value that specifies the HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify such information as the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if the URL is not an HTTP URL. +*`lpszHeaders`*\ +A pointer to a value that specifies the HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify such information as the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if the URL isn't an HTTP URL. -*lpvPostData*
-A pointer to the data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, `Navigate` issues an HTTP GET transaction. This parameter is ignored if the URL is not an HTTP URL. +*`lpvPostData`*\ +A pointer to the data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter doesn't specify any post data, `Navigate` issues an HTTP GET transaction. This parameter is ignored if the URL isn't an HTTP URL. -*dwPostDataLen*
-Data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, `Navigate` issues an HTTP GET transaction. This parameter is ignored if URL is not an HTTP URL. +*`dwPostDataLen`*\ +Data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter doesn't specify any post data, `Navigate` issues an HTTP GET transaction. This parameter is ignored if URL isn't an HTTP URL. -## CDHtmlDialog::OnBeforeNavigate +## `CDHtmlDialog::OnBeforeNavigate` Called by the framework to cause an event to fire before a navigation occurs. @@ -992,15 +991,15 @@ virtual void OnBeforeNavigate( ### Parameters -*pDisp*
+*`pDisp`*\ A pointer to an `IDispatch` object. -*szUrl*
+*`szUrl`*\ A pointer to a string containing the URL to navigate to. -## CDHtmlDialog::OnDocumentComplete +## `CDHtmlDialog::OnDocumentComplete` -Called by the framework to notify an application when a document has achieved the READYSTATE_COMPLETE state. +Called by the framework to notify an application when a document has achieved the `READYSTATE_COMPLETE` state. ``` virtual void OnDocumentComplete( @@ -1010,13 +1009,13 @@ virtual void OnDocumentComplete( ### Parameters -*pDisp*
+*`pDisp`*\ A pointer to an `IDispatch` object. -*szUrl*
+*`szUrl`*\ A pointer to a string containing the URL that was navigated to. -## CDHtmlDialog::OnDocWindowActivate +## `CDHtmlDialog::OnDocWindowActivate` Called by the framework when the document window is activated or deactivated. @@ -1026,18 +1025,18 @@ STDMETHOD(OnDocWindowActivate)(BOOL fActivate); ### Parameters -*fActivate*
-See *fActivate* in [IDocHostUIHandler::OnDocWindowActivate](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753261\(v=vs.85\)) in the Windows SDK. +*`fActivate`*\ +See *`fActivate`* in [`IDocHostUIHandler::OnDocWindowActivate`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753261\(v=vs.85\)) in the Windows SDK. ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::OnDocWindowActivate](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753261\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::OnDocWindowActivate`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753261\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::OnFrameWindowActivate +## `CDHtmlDialog::OnFrameWindowActivate` Called by the framework when the frame window is activated or deactivated. @@ -1047,20 +1046,20 @@ STDMETHOD(OnFrameWindowActivate)(BOOL fActivate); ### Parameters -*fActivate*
-See *fActivate* in [IDocHostUIHandler::OnFrameWindowActivate](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753262\(v=vs.85\)) in the Windows SDK. +*`fActivate`*\ +See *`fActivate`* in [`IDocHostUIHandler::OnFrameWindowActivate`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753262\(v=vs.85\)) in the Windows SDK. ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::OnFrameWindowActivate](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753262\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::OnFrameWindowActivate`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753262\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::OnInitDialog +## `CDHtmlDialog::OnInitDialog` -Called in response to the WM_INITDIALOG message. +Called in response to the `WM_INITDIALOG` message. ``` virtual BOOL OnInitDialog(); @@ -1068,17 +1067,17 @@ virtual BOOL OnInitDialog(); ### Return Value -The default implementation returns TRUE. +The default implementation returns `TRUE`. ### Remarks This message is sent to the dialog box during the `Create`, `CreateIndirect`, or `DoModal` calls, which occur immediately before the dialog box is displayed. -Override this member function if you need to perform special processing when the dialog box is initialized. In the overridden version, first call the base class `OnInitDialog` but disregard its return value. You will normally return TRUE from your overridden member function. +Override this member function if you need to perform special processing when the dialog box is initialized. In the overridden version, first call the base class `OnInitDialog` but disregard its return value. You'll normally return `TRUE` from your overridden member function. -Windows calls the `OnInitDialog` function through the standard global dialog-box procedure common to all Microsoft Foundation Class Library dialog boxes, rather than through your message map, so you do not need a message-map entry for this member function. +Windows calls the `OnInitDialog` function through the standard global dialog-box procedure common to all Microsoft Foundation Class Library dialog boxes, rather than through your message map, so you don't need a message-map entry for this member function. -## CDHtmlDialog::OnNavigateComplete +## `CDHtmlDialog::OnNavigateComplete` Called by the framework after navigation to the specified URL is completed. @@ -1090,13 +1089,13 @@ virtual void OnNavigateComplete( ### Parameters -*pDisp*
+*`pDisp`*\ A pointer to an `IDispatch` object. -*szUrl*
+*`szUrl`*\ A pointer to a string containing the URL that was navigated to. -## CDHtmlDialog::ResizeBorder +## `CDHtmlDialog::ResizeBorder` Alerts the object that it needs to resize its border space. @@ -1109,20 +1108,20 @@ STDMETHOD(ResizeBorder)( ### Parameters -*prcBorder*
-See *prcBorder* in [IDocHostUIHandler::ResizeBorder](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753263\(v=vs.85\)) in the Windows SDK. +*`prcBorder`*\ +See *`prcBorder`* in [`IDocHostUIHandler::ResizeBorder`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753263\(v=vs.85\)) in the Windows SDK. -*pUIWindow*
-See *pUIWindow* in `IDocHostUIHandler::ResizeBorder` in the Windows SDK. +*`pUIWindow`*\ +See *`pUIWindow`* in `IDocHostUIHandler::ResizeBorder` in the Windows SDK. -*fFrameWindow*
-See *fFrameWindow* in `IDocHostUIHandler::ResizeBorder` in the Windows SDK. +*`fFrameWindow`*\ +See *`fFrameWindow`* in `IDocHostUIHandler::ResizeBorder` in the Windows SDK. ### Return Value Returns E_NOTIMPL. -## CDHtmlDialog::SetControlProperty +## `CDHtmlDialog::SetControlProperty` Sets the property of an ActiveX control to a new value. @@ -1145,22 +1144,22 @@ void SetControlProperty( ### Parameters -*szElementId*
+*`szElementId`*\ The HTML ID of an ActiveX control. -*dispId*
+*`dispId`*\ The dispatch ID of the property to set. -*pVar*
-Pointer to a VARIANT containing the new property value. +*`pVar`*\ +Pointer to a `VARIANT` containing the new property value. -*pdispControl*
+*`pdispControl`*\ Pointer to an ActiveX control's `IDispatch` interface. -*szPropName*
+*`szPropName`*\ String containing the name of the property to set. -## CDHtmlDialog::SetElementHtml +## `CDHtmlDialog::SetElementHtml` Sets the `innerHTML` property of an HTML element. @@ -1176,16 +1175,16 @@ void SetElementHtml( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*bstrText*
+*`bstrText`*\ The new value of the `innerHTML` property. -*punkElem*
+*`punkElem`*\ The `IUnknown` pointer of an HTML element. -## CDHtmlDialog::SetElementProperty +## `CDHtmlDialog::SetElementProperty` Sets a property of an HTML element. @@ -1198,16 +1197,16 @@ void SetElementProperty( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*dispId*
+*`dispId`*\ The dispatch ID of the property to set. -*pVar*
+*`pVar`*\ The new value of the property. -## CDHtmlDialog::SetElementText +## `CDHtmlDialog::SetElementText` Sets the `innerText` property of an HTML element. @@ -1223,16 +1222,16 @@ void SetElementText( ### Parameters -*szElementId*
+*`szElementId`*\ The ID of an HTML element. -*bstrText*
+*`bstrText`*\ The new value of the `innerText` property. -*punkElem*
+*`punkElem`*\ The `IUnknown` pointer of an HTML element. -## CDHtmlDialog::SetExternalDispatch +## `CDHtmlDialog::SetExternalDispatch` Sets the host's `IDispatch` interface. @@ -1242,10 +1241,10 @@ void SetExternalDispatch(IDispatch* pdispExternal); ### Parameters -*pdispExternal*
+*`pdispExternal`*\ The new `IDispatch` interface. -## CDHtmlDialog::SetHostFlags +## `CDHtmlDialog::SetHostFlags` Sets the host UI flags. @@ -1255,10 +1254,10 @@ void SetHostFlags(DWORD dwFlags); ### Parameters -*dwFlags*
-For possible values, see [DOCHOSTUIFLAG](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753277\(v=vs.85\)) in the Windows SDK. +*`dwFlags`*\ +For possible values, see [`DOCHOSTUIFLAG`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753277\(v=vs.85\)) in the Windows SDK. -## CDHtmlDialog::ShowContextMenu +## `CDHtmlDialog::ShowContextMenu` Called when a context menu is about to be displayed. @@ -1272,27 +1271,27 @@ STDMETHOD(ShowContextMenu)( ### Parameters -*dwID*
-See *dwID* in [IDocHostUIHandler::ShowContextMenu](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753264\(v=vs.85\)) in the Windows SDK. +*`dwID`*\ +See *`dwID`* in [`IDocHostUIHandler::ShowContextMenu`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753264\(v=vs.85\)) in the Windows SDK. -*ppt*
-See *ppt* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. +*`ppt`*\ +See *`ppt`* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. -*pcmdtReserved*
-See *pcmdtReserved* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. +*`pcmdtReserved`*\ +See *`pcmdtReserved`* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. -*pdispReserved*
-See *pdispReserved* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. +*`pdispReserved`*\ +See *`pdispReserved`* in `IDocHostUIHandler::ShowContextMenu` in the Windows SDK. ### Return Value -Returns S_FALSE. +Returns `S_FALSE`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::ShowContextMenu](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753264\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::ShowContextMenu`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753264\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::ShowUI +## `CDHtmlDialog::ShowUI` Shows the host's UI. @@ -1307,30 +1306,30 @@ STDMETHOD(ShowUI)( ### Parameters -*dwID*
-See *dwID* in [IDocHostUIHandler::ShowUI](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753265\(v=vs.85\)) in the Windows SDK. +*`dwID`*\ +See *`dwID`* in [`IDocHostUIHandler::ShowUI`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753265\(v=vs.85\)) in the Windows SDK. -*pActiveObject*
-See *d pActiveObject* in `IDocHostUIHandler::ShowUI` in the Windows SDK. +*`pActiveObject`*\ +See *`pActiveObject`* in `IDocHostUIHandler::ShowUI` in the Windows SDK. -*pCommandTarget*
-See *pCommandTarget* in `IDocHostUIHandler::ShowUI` in the Windows SDK. +*`pCommandTarget`*\ +See *`pCommandTarget`* in `IDocHostUIHandler::ShowUI` in the Windows SDK. -*pFrame*
-See *pFrame* in `IDocHostUIHandler::ShowUI` in the Windows SDK. +*`pFrame`*\ +See *`pFrame`* in `IDocHostUIHandler::ShowUI` in the Windows SDK. -*pDoc*
-See *pDoc* in `IDocHostUIHandler::ShowUI` in the Windows SDK. +*`pDoc`*\ +See *`pDoc`* in `IDocHostUIHandler::ShowUI` in the Windows SDK. ### Return Value -Returns S_FALSE. +Returns `S_FALSE`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::ShowUI](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753265\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::ShowUI`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753265\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::TranslateAccelerator +## `CDHtmlDialog::TranslateAccelerator` Called to process menu accelerator-key messages. @@ -1343,24 +1342,24 @@ STDMETHOD(TranslateAccelerator)( ### Parameters -*lpMsg*
-See *lpMsg* in [IDocHostUIHandler::TranslateAccelerator](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753266\(v=vs.85\)) in the Windows SDK. +*`lpMsg`*\ +See *`lpMsg`* in [`IDocHostUIHandler::TranslateAccelerator`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753266\(v=vs.85\)) in the Windows SDK. -*pguidCmdGroup*
-See *pguidCmdGroup* in `IDocHostUIHandler::TranslateAccelerator` in the Windows SDK. +*`pguidCmdGroup`*\ +See *`pguidCmdGroup`* in `IDocHostUIHandler::TranslateAccelerator` in the Windows SDK. -*nCmdID*
-See *nCmdID* in `IDocHostUIHandler::TranslateAccelerator` in the Windows SDK. +*`nCmdID`*\ +See *`nCmdID`* in `IDocHostUIHandler::TranslateAccelerator` in the Windows SDK. ### Return Value -Returns S_FALSE. +Returns `S_FALSE`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::TranslateAccelerator](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753266\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::TranslateAccelerator`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753266\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::TranslateUrl +## `CDHtmlDialog::TranslateUrl` Called to modify the URL to be loaded. @@ -1373,24 +1372,24 @@ STDMETHOD(TranslateUrl)( ### Parameters -*dwTranslate*
-See *dwTranslate* in [IDocHostUIHandler::TranslateUrl](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753267\(v=vs.85\)) in the Windows SDK. +*`dwTranslate`*\ +See *`dwTranslate`* in [`IDocHostUIHandler::TranslateUrl`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753267\(v=vs.85\)) in the Windows SDK. -*pchURLIn*
-See *pchURLIn* in `IDocHostUIHandler::TranslateUrl` in the Windows SDK. +*`pchURLIn`*\ +See *`pchURLIn`* in `IDocHostUIHandler::TranslateUrl` in the Windows SDK. -*ppchURLOut*
-See *ppchURLOut* in `IDocHostUIHandler::TranslateUrl` in the Windows SDK. +*`ppchURLOut`*\ +See *`ppchURLOut`* in `IDocHostUIHandler::TranslateUrl` in the Windows SDK. ### Return Value -Returns S_FALSE. +Returns `S_FALSE`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::TranslateUrl](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753267\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::TranslateUrl`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753267\(v=vs.85\)), as described in the Windows SDK. -## CDHtmlDialog::UpdateUI +## `CDHtmlDialog::UpdateUI` Called to notify the host that the command state has changed. @@ -1400,14 +1399,14 @@ STDMETHOD(UpdateUI)(void); ### Return Value -Returns E_NOTIMPL. +Returns `E_NOTIMPL`. ### Remarks -This member function is CDHtmlDialog's implementation of [IDocHostUIHandler::UpdateUI](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753268\(v=vs.85\)), as described in the Windows SDK. +This member function is the `CDHtmlDialog` implementation of [`IDocHostUIHandler::UpdateUI`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753268\(v=vs.85\)), as described in the Windows SDK. ## See also -[MFC Sample DHtmlExplore](../../overview/visual-cpp-samples.md)
-[DDX_DHtml Helper Macros](#ddx_dhtml_helper_macros)
+[MFC Sample `DHtmlExplore`](../../overview/visual-cpp-samples.md)\ +[`DDX_DHtml` Helper Macros](#ddx_dhtml_helper_macros)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/cdialog-class.md b/docs/mfc/reference/cdialog-class.md index 0f2eb95f52..fa6866e8b8 100644 --- a/docs/mfc/reference/cdialog-class.md +++ b/docs/mfc/reference/cdialog-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CDialog Class" title: "CDialog Class" -ms.date: "09/07/2019" +description: "Learn more about: CDialog Class" +ms.date: 09/07/2019 f1_keywords: ["CDialog", "AFXWIN/CDialog", "AFXWIN/CDialog::CDialog", "AFXWIN/CDialog::Create", "AFXWIN/CDialog::CreateIndirect", "AFXWIN/CDialog::DoModal", "AFXWIN/CDialog::EndDialog", "AFXWIN/CDialog::GetDefID", "AFXWIN/CDialog::GotoDlgCtrl", "AFXWIN/CDialog::InitModalIndirect", "AFXWIN/CDialog::MapDialogRect", "AFXWIN/CDialog::NextDlgCtrl", "AFXWIN/CDialog::OnInitDialog", "AFXWIN/CDialog::OnSetFont", "AFXWIN/CDialog::PrevDlgCtrl", "AFXWIN/CDialog::SetDefID", "AFXWIN/CDialog::SetHelpID", "AFXWIN/CDialog::OnCancel", "AFXWIN/CDialog::OnOK"] helpviewer_keywords: ["CDialog [MFC], CDialog", "CDialog [MFC], Create", "CDialog [MFC], CreateIndirect", "CDialog [MFC], DoModal", "CDialog [MFC], EndDialog", "CDialog [MFC], GetDefID", "CDialog [MFC], GotoDlgCtrl", "CDialog [MFC], InitModalIndirect", "CDialog [MFC], MapDialogRect", "CDialog [MFC], NextDlgCtrl", "CDialog [MFC], OnInitDialog", "CDialog [MFC], OnSetFont", "CDialog [MFC], PrevDlgCtrl", "CDialog [MFC], SetDefID", "CDialog [MFC], SetHelpID", "CDialog [MFC], OnCancel", "CDialog [MFC], OnOK"] -ms.assetid: ca64b77e-2cd2-47e3-8eff-c2645ad578f9 --- # CDialog Class @@ -274,7 +273,7 @@ You can call `EndDialog` at any time, even in [OnInitDialog](#oninitdialog), in ### Example [!code-cpp[NVC_MFCControlLadenDialog#64](../../mfc/codesnippet/cpp/cdialog-class_3.cpp)] - +  [!code-cpp[NVC_MFCControlLadenDialog#65](../../mfc/codesnippet/cpp/cdialog-class_4.cpp)] ## CDialog::GetDefID @@ -287,7 +286,7 @@ DWORD GetDefID() const; ### Return Value -A 32-bit value ( `DWORD`). If the default pushbutton has an ID value, the high-order word contains DC_HASDEFID and the low-order word contains the ID value. If the default pushbutton does not have an ID value, the return value is 0. +A 32-bit value (`DWORD`). If the default pushbutton has an ID value, the high-order word contains DC_HASDEFID and the low-order word contains the ID value. If the default pushbutton does not have an ID value, the return value is 0. ### Remarks diff --git a/docs/mfc/reference/cdialogex-class.md b/docs/mfc/reference/cdialogex-class.md index c34f1f0f9a..f2b25ce85e 100644 --- a/docs/mfc/reference/cdialogex-class.md +++ b/docs/mfc/reference/cdialogex-class.md @@ -4,9 +4,8 @@ title: "CDialogEx Class" ms.date: "11/04/2016" f1_keywords: ["CDialogEx", "AFXDIALOGEX/CDialogEx", "AFXDIALOGEX/CDialogEx::CDialogEx", "AFXDIALOGEX/CDialogEx::SetBackgroundColor", "AFXDIALOGEX/CDialogEx::SetBackgroundImage"] helpviewer_keywords: ["CDialogEx [MFC], CDialogEx", "CDialogEx [MFC], SetBackgroundColor", "CDialogEx [MFC], SetBackgroundImage"] -ms.assetid: a6ed3b1f-aef8-4b66-ac78-2160faf63c13 --- -# CDialogEx Class +# `CDialogEx` Class The `CDialogEx` class specifies the background color and background image of a dialog box. @@ -22,41 +21,41 @@ class CDialogEx : public CDialog |Name|Description| |----------|-----------------| -|[CDialogEx::CDialogEx](#cdialogex)|Constructs a `CDialogEx` object.| +|[`CDialogEx::CDialogEx`](#cdialogex)|Constructs a `CDialogEx` object.| |`CDialogEx::~CDialogEx`|Destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CDialogEx::SetBackgroundColor](#setbackgroundcolor)|Sets the background color of the dialog box.| -|[CDialogEx::SetBackgroundImage](#setbackgroundimage)|Sets the background image of the dialog box.| +|[`CDialogEx::SetBackgroundColor`](#setbackgroundcolor)|Sets the background color of the dialog box.| +|[`CDialogEx::SetBackgroundImage`](#setbackgroundimage)|Sets the background image of the dialog box.| ## Remarks To use the `CDialogEx` class, derive your dialog box class from the `CDialogEx` class instead of the `CDialog` class. -Dialog box images are stored in a resource file. The framework automatically deletes any image that is loaded from the resource file. To programmatically delete the current background image, call the [CDialogEx::SetBackgroundImage](#setbackgroundimage) method or implement an `OnDestroy` event handler. When you call the [CDialogEx::SetBackgroundImage](#setbackgroundimage) method, pass in an `HBITMAP` parameter as the image handle. The `CDialogEx` object will take ownership of the image and delete it if the `m_bAutoDestroyBmp` flag is `TRUE`. +Dialog box images are stored in a resource file. The framework automatically deletes any image that is loaded from the resource file. To programmatically delete the current background image, call the [`CDialogEx::SetBackgroundImage`](#setbackgroundimage) method or implement an `OnDestroy` event handler. When you call the [`CDialogEx::SetBackgroundImage`](#setbackgroundimage) method, pass in an `HBITMAP` parameter as the image handle. The `CDialogEx` object will take ownership of the image and delete it if the `m_bAutoDestroyBmp` flag is `TRUE`. -A `CDialogEx` object can be a parent of a [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) object. The [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) object calls the `CDialogEx::SetActiveMenu` method when the [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) object opens. Afterward, the `CDialogEx` object handles any menu event until the [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) object is closed. +A `CDialogEx` object can be a parent of a [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) object. The [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) object calls the `CDialogEx::SetActiveMenu` method when the [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) object opens. Afterward, the `CDialogEx` object handles any menu event until the [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) object is closed. ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) -[CDialogEx](../../mfc/reference/cdialogex-class.md) +[`CDialogEx`](../../mfc/reference/cdialogex-class.md) ## Requirements -**Header:** afxdialogex.h +**Header:** `afxdialogex.h` -## CDialogEx::CDialogEx +## `CDialogEx::CDialogEx` Constructs a `CDialogEx` object. @@ -72,23 +71,23 @@ CDialogEx( ### Parameters -*nIDTemplate*
+*`nIDTemplate`*\ [in] The resource ID of a dialog box template. -*lpszTemplateName*
+*`lpszTemplateName`*\ [in] The resource name of a dialog box template. -*pParent*
-[in] A pointer to the parent window. The default value is NULL. +*`pParent`*\ +[in] A pointer to the parent window. The default value is `NULL`. -*pParentWnd*
-[in] A pointer to the parent window. The default value is NULL. +*`pParentWnd`*\ +[in] A pointer to the parent window. The default value is `NULL`. ### Return Value ### Remarks -## CDialogEx::SetBackgroundColor +## `CDialogEx::SetBackgroundColor` Sets the background color of the dialog box. @@ -100,15 +99,15 @@ void SetBackgroundColor( ### Parameters -*color*
+*`color`*\ [in] An RGB color value. -*bRepaint*
-[in] TRUE to immediately update the screen; otherwise, FALSE. The default value is TRUE. +*`bRepaint`*\ +[in] `TRUE` to immediately update the screen; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CDialogEx::SetBackgroundImage +## `CDialogEx::SetBackgroundImage` Sets the background image of the dialog box. @@ -127,32 +126,32 @@ BOOL SetBackgroundImage( ### Parameters -*hBitmap*
+*`hBitmap`*\ [in] A handle to the background image. -*uiBmpResId*
+*`uiBmpResId`*\ [in] The resource ID of the background image. -*location*
-[in] One of the `CDialogEx::BackgroundLocation` values that specify the location of the image. Valid values include BACKGR_TILE, BACKGR_TOPLEFT, BACKGR_TOPRIGHT, BACKGR_BOTTOMLEFT, and BACKGR_BOTTOMRIGHT. The default value is BACKGR_TILE. +*`location`*\ +[in] One of the `CDialogEx::BackgroundLocation` values that specify the location of the image. Valid values include `BACKGR_TILE`, `BACKGR_TOPLEFT`, `BACKGR_TOPRIGHT`, `BACKGR_BOTTOMLEFT`, and `BACKGR_BOTTOMRIGHT`. The default value is `BACKGR_TILE`. -*bAutoDestroy*
-[in] TRUE to automatically destroy the background image; otherwise, FALSE. +*`bAutoDestroy`*\ +[in] `TRUE` to automatically destroy the background image; otherwise, `FALSE`. -*bRepaint*
-[in] TRUE to immediately redraw the dialog box; otherwise, FALSE. +*`bRepaint`*\ +[in] `TRUE` to immediately redraw the dialog box; otherwise, `FALSE`. ### Return Value -In the second method overload syntax, TRUE if the method is successful; otherwise, FALSE. +In the second method overload syntax, `TRUE` if the method is successful; otherwise, `FALSE`. ### Remarks -The image that you specify is not stretched to fit the dialog box client area. +The image that you specify isn't stretched to fit the dialog box client area. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md)
-[CContextMenuManager Class](../../mfc/reference/ccontextmenumanager-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md)\ +[`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md) diff --git a/docs/mfc/reference/cdockablepane-class.md b/docs/mfc/reference/cdockablepane-class.md index a72e015e68..7b65d85589 100644 --- a/docs/mfc/reference/cdockablepane-class.md +++ b/docs/mfc/reference/cdockablepane-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: CDockablePane Class" title: "CDockablePane Class" +description: "Learn more about: CDockablePane Class" ms.date: "07/02/2019" f1_keywords: ["CDockablePane", "AFXDOCKABLEPANE/CDockablePane", "AFXDOCKABLEPANE/CDockablePane::CDockablePane", "AFXDOCKABLEPANE/CDockablePane::AttachToTabWnd", "AFXDOCKABLEPANE/CDockablePane::CalcFixedLayout", "AFXDOCKABLEPANE/CDockablePane::CanAcceptMiniFrame", "AFXDOCKABLEPANE/CDockablePane::CanAcceptPane", "AFXDOCKABLEPANE/CDockablePane::CanAutoHide", "AFXDOCKABLEPANE/CDockablePane::CanBeAttached", "AFXDOCKABLEPANE/CDockablePane::ConvertToTabbedDocument", "AFXDOCKABLEPANE/CDockablePane::CopyState", "AFXDOCKABLEPANE/CDockablePane::Create", "AFXDOCKABLEPANE/CDockablePane::CreateDefaultPaneDivider", "AFXDOCKABLEPANE/CDockablePane::CreateEx", "AFXDOCKABLEPANE/CDockablePane::CreateTabbedPane", "AFXDOCKABLEPANE/CDockablePane::DockPaneContainer", "AFXDOCKABLEPANE/CDockablePane::DockPaneStandard", "AFXDOCKABLEPANE/CDockablePane::DockToRecentPos", "AFXDOCKABLEPANE/CDockablePane::DockToWindow", "AFXDOCKABLEPANE/CDockablePane::EnableAutohideAll", "AFXDOCKABLEPANE/CDockablePane::EnableGripper", "AFXDOCKABLEPANE/CDockablePane::GetAHRestoredRect", "AFXDOCKABLEPANE/CDockablePane::GetAHSlideMode", "AFXDOCKABLEPANE/CDockablePane::GetCaptionHeight", "AFXDOCKABLEPANE/CDockablePane::GetDefaultPaneDivider", "AFXDOCKABLEPANE/CDockablePane::GetDockingStatus", "AFXDOCKABLEPANE/CDockablePane::GetDragSensitivity", "AFXDOCKABLEPANE/CDockablePane::GetLastPercentInPaneContainer", "AFXDOCKABLEPANE/CDockablePane::GetTabArea", "AFXDOCKABLEPANE/CDockablePane::GetTabbedPaneRTC", "AFXDOCKABLEPANE/CDockablePane::HasAutoHideMode", "AFXDOCKABLEPANE/CDockablePane::HitTest", "AFXDOCKABLEPANE/CDockablePane::IsAutohideAllEnabled", "AFXDOCKABLEPANE/CDockablePane::IsAutoHideMode", "AFXDOCKABLEPANE/CDockablePane::IsDocked", "AFXDOCKABLEPANE/CDockablePane::IsHideInAutoHideMode", "AFXDOCKABLEPANE/CDockablePane::IsInFloatingMultiPaneFrameWnd", "AFXDOCKABLEPANE/CDockablePane::IsResizable", "AFXDOCKABLEPANE/CDockablePane::IsTabLocationBottom", "AFXDOCKABLEPANE/CDockablePane::IsTracked", "AFXDOCKABLEPANE/CDockablePane::IsVisible", "AFXDOCKABLEPANE/CDockablePane::OnAfterChangeParent", "AFXDOCKABLEPANE/CDockablePane::OnAfterDockFromMiniFrame", "AFXDOCKABLEPANE/CDockablePane::OnBeforeChangeParent", "AFXDOCKABLEPANE/CDockablePane::OnBeforeFloat", "AFXDOCKABLEPANE/CDockablePane::RemoveFromDefaultPaneDividier", "AFXDOCKABLEPANE/CDockablePane::ReplacePane", "AFXDOCKABLEPANE/CDockablePane::RestoreDefaultPaneDivider", "AFXDOCKABLEPANE/CDockablePane::SetAutoHideMode", "AFXDOCKABLEPANE/CDockablePane::SetAutoHideParents", "AFXDOCKABLEPANE/CDockablePane::SetLastPercentInPaneContainer", "AFXDOCKABLEPANE/CDockablePane::SetRestoredDefaultPaneDivider", "AFXDOCKABLEPANE/CDockablePane::SetTabbedPaneRTC", "AFXDOCKABLEPANE/CDockablePane::ShowPane", "AFXDOCKABLEPANE/CDockablePane::Slide", "AFXDOCKABLEPANE/CDockablePane::ToggleAutoHide", "AFXDOCKABLEPANE/CDockablePane::UndockPane", "AFXDOCKABLEPANE/CDockablePane::CheckAutoHideCondition", "AFXDOCKABLEPANE/CDockablePane::CheckStopSlideCondition", "AFXDOCKABLEPANE/CDockablePane::DrawCaption", "AFXDOCKABLEPANE/CDockablePane::OnPressButtons", "AFXDOCKABLEPANE/CDockablePane::OnSlide", "AFXDOCKABLEPANE/CDockablePane::m_bDisableAnimation", "AFXDOCKABLEPANE/CDockablePane::m_bHideInAutoHideMode", "AFXDOCKABLEPANE/CDockablePane::m_nSlideSteps"] helpviewer_keywords: ["CDockablePane [MFC], CDockablePane", "CDockablePane [MFC], AttachToTabWnd", "CDockablePane [MFC], CalcFixedLayout", "CDockablePane [MFC], CanAcceptMiniFrame", "CDockablePane [MFC], CanAcceptPane", "CDockablePane [MFC], CanAutoHide", "CDockablePane [MFC], CanBeAttached", "CDockablePane [MFC], ConvertToTabbedDocument", "CDockablePane [MFC], CopyState", "CDockablePane [MFC], Create", "CDockablePane [MFC], CreateDefaultPaneDivider", "CDockablePane [MFC], CreateEx", "CDockablePane [MFC], CreateTabbedPane", "CDockablePane [MFC], DockPaneContainer", "CDockablePane [MFC], DockPaneStandard", "CDockablePane [MFC], DockToRecentPos", "CDockablePane [MFC], DockToWindow", "CDockablePane [MFC], EnableAutohideAll", "CDockablePane [MFC], EnableGripper", "CDockablePane [MFC], GetAHRestoredRect", "CDockablePane [MFC], GetAHSlideMode", "CDockablePane [MFC], GetCaptionHeight", "CDockablePane [MFC], GetDefaultPaneDivider", "CDockablePane [MFC], GetDockingStatus", "CDockablePane [MFC], GetDragSensitivity", "CDockablePane [MFC], GetLastPercentInPaneContainer", "CDockablePane [MFC], GetTabArea", "CDockablePane [MFC], GetTabbedPaneRTC", "CDockablePane [MFC], HasAutoHideMode", "CDockablePane [MFC], HitTest", "CDockablePane [MFC], IsAutohideAllEnabled", "CDockablePane [MFC], IsAutoHideMode", "CDockablePane [MFC], IsDocked", "CDockablePane [MFC], IsHideInAutoHideMode", "CDockablePane [MFC], IsInFloatingMultiPaneFrameWnd", "CDockablePane [MFC], IsResizable", "CDockablePane [MFC], IsTabLocationBottom", "CDockablePane [MFC], IsTracked", "CDockablePane [MFC], IsVisible", "CDockablePane [MFC], OnAfterChangeParent", "CDockablePane [MFC], OnAfterDockFromMiniFrame", "CDockablePane [MFC], OnBeforeChangeParent", "CDockablePane [MFC], OnBeforeFloat", "CDockablePane [MFC], RemoveFromDefaultPaneDividier", "CDockablePane [MFC], ReplacePane", "CDockablePane [MFC], RestoreDefaultPaneDivider", "CDockablePane [MFC], SetAutoHideMode", "CDockablePane [MFC], SetAutoHideParents", "CDockablePane [MFC], SetLastPercentInPaneContainer", "CDockablePane [MFC], SetRestoredDefaultPaneDivider", "CDockablePane [MFC], SetTabbedPaneRTC", "CDockablePane [MFC], ShowPane", "CDockablePane [MFC], Slide", "CDockablePane [MFC], ToggleAutoHide", "CDockablePane [MFC], UndockPane", "CDockablePane [MFC], CheckAutoHideCondition", "CDockablePane [MFC], CheckStopSlideCondition", "CDockablePane [MFC], DrawCaption", "CDockablePane [MFC], OnPressButtons", "CDockablePane [MFC], OnSlide", "CDockablePane [MFC], m_bDisableAnimation", "CDockablePane [MFC], m_bHideInAutoHideMode", "CDockablePane [MFC], m_nSlideSteps"] -ms.assetid: e2495f4c-765f-48f9-a2e2-e45e47608d91 --- -# CDockablePane Class +# `CDockablePane` Class Implements a pane that can either be docked in a dock site or included in a tabbed pane. @@ -22,95 +21,95 @@ class CDockablePane : public CPane |Name|Description| |----------|-----------------| -|[CDockablePane::CDockablePane](#cdockablepane)|Constructs and initializes a `CDockablePane` object.| +|[`CDockablePane::CDockablePane`](#cdockablepane)|Constructs and initializes a `CDockablePane` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CDockablePane::AttachToTabWnd](#attachtotabwnd)|Attaches a pane to another pane. This creates a tabbed pane.| -|[CDockablePane::CalcFixedLayout](#calcfixedlayout)|Returns the size of the pane rectangle.| -|[CDockablePane::CanAcceptMiniFrame](#canacceptminiframe)|Determines whether the specified mini frame can be docked to the pane.| -|[CDockablePane::CanAcceptPane](#canacceptpane)|Determines whether another pane can be docked to the current pane.| -|[CDockablePane::CanAutoHide](#canautohide)|Determines whether the pane supports auto-hide mode. (Overrides [CBasePane::CanAutoHide](../../mfc/reference/cbasepane-class.md#canautohide).)| -|[CDockablePane::CanBeAttached](#canbeattached)|Determines whether the current pane can be docked to another pane.| -|[CDockablePane::ConvertToTabbedDocument](#converttotabbeddocument)|Converts one or more dockable panes to MDI tabbed documents.| -|[CDockablePane::CopyState](#copystate)|Copies the state of a dockable pane.| -|[CDockablePane::Create](#create)|Creates the Windows control and attaches it to the `CDockablePane` object.| -|[CDockablePane::CreateDefaultPaneDivider](#createdefaultpanedivider)|Creates a default divider for the pane as it is being docked to a frame window.| -|[CDockablePane::CreateEx](#createex)|Creates the Windows control and attaches it to the `CDockablePane` object.| -|[CDockablePane::CreateTabbedPane](#createtabbedpane)|Creates a tabbed pane from the current pane.| -|[CDockablePane::DockPaneContainer](#dockpanecontainer)|Docks a container to the pane.| -|[CDockablePane::DockPaneStandard](#dockpanestandard)|Docks a pane by using outline (standard) docking.| -|`CDockablePane::DockToFrameWindow`|Used internally. To dock a pane, use [CPane::DockPane](../../mfc/reference/cpane-class.md#dockpane) or [CDockablePane::DockToWindow](#docktowindow).| -|[CDockablePane::DockToRecentPos](#docktorecentpos)|Docks a pane to its stored recent docking position.| -|[CDockablePane::DockToWindow](#docktowindow)|Docks one docking pane to another docking pane.| -|[CDockablePane::EnableAutohideAll](#enableautohideall)|Enables or disables auto-hide mode for this pane together with other panes in the container.| -|[CDockablePane::EnableGripper](#enablegripper)|Shows or hides the caption (gripper).| -|[CDockablePane::GetAHRestoredRect](#getahrestoredrect)|Specifies the position of the pane when visible in auto-hide mode.| -|[CDockablePane::GetAHSlideMode](#getahslidemode)|Retrieves the auto hide slide mode for the pane.| +|[`CDockablePane::AttachToTabWnd`](#attachtotabwnd)|Attaches a pane to another pane. This creates a tabbed pane.| +|[`CDockablePane::CalcFixedLayout`](#calcfixedlayout)|Returns the size of the pane rectangle.| +|[`CDockablePane::CanAcceptMiniFrame`](#canacceptminiframe)|Determines whether the specified mini frame can be docked to the pane.| +|[`CDockablePane::CanAcceptPane`](#canacceptpane)|Determines whether another pane can be docked to the current pane.| +|[`CDockablePane::CanAutoHide`](#canautohide)|Determines whether the pane supports auto-hide mode. (Overrides [`CBasePane::CanAutoHide`](../../mfc/reference/cbasepane-class.md#canautohide).)| +|[`CDockablePane::CanBeAttached`](#canbeattached)|Determines whether the current pane can be docked to another pane.| +|[`CDockablePane::ConvertToTabbedDocument`](#converttotabbeddocument)|Converts one or more dockable panes to MDI tabbed documents.| +|[`CDockablePane::CopyState`](#copystate)|Copies the state of a dockable pane.| +|[`CDockablePane::Create`](#create)|Creates the Windows control and attaches it to the `CDockablePane` object.| +|[`CDockablePane::CreateDefaultPaneDivider`](#createdefaultpanedivider)|Creates a default divider for the pane as it is being docked to a frame window.| +|[`CDockablePane::CreateEx`](#createex)|Creates the Windows control and attaches it to the `CDockablePane` object.| +|[`CDockablePane::CreateTabbedPane`](#createtabbedpane)|Creates a tabbed pane from the current pane.| +|[`CDockablePane::DockPaneContainer`](#dockpanecontainer)|Docks a container to the pane.| +|[`CDockablePane::DockPaneStandard`](#dockpanestandard)|Docks a pane by using outline (standard) docking.| +|`CDockablePane::DockToFrameWindow`|Used internally. To dock a pane, use [`CPane::DockPane`](../../mfc/reference/cpane-class.md#dockpane) or [`CDockablePane::DockToWindow`](#docktowindow).| +|[`CDockablePane::DockToRecentPos`](#docktorecentpos)|Docks a pane to its stored recent docking position.| +|[`CDockablePane::DockToWindow`](#docktowindow)|Docks one docking pane to another docking pane.| +|[`CDockablePane::EnableAutohideAll`](#enableautohideall)|Enables or disables auto-hide mode for this pane together with other panes in the container.| +|[`CDockablePane::EnableGripper`](#enablegripper)|Shows or hides the caption (gripper).| +|[`CDockablePane::GetAHRestoredRect`](#getahrestoredrect)|Specifies the position of the pane when visible in auto-hide mode.| +|[`CDockablePane::GetAHSlideMode`](#getahslidemode)|Retrieves the auto hide slide mode for the pane.| |`CDockablePane::GetAutoHideButton`|Used internally.| |`CDockablePane::GetAutoHideToolBar`|Used internally.| -|[CDockablePane::GetCaptionHeight](#getcaptionheight)|Returns the height of the current caption.| -|[CDockablePane::GetDefaultPaneDivider](#getdefaultpanedivider)|Returns the default pane divider for the pane's container.| -|[CDockablePane::GetDockingStatus](#getdockingstatus)|Determines the ability of a pane to be docked based on the provided pointer location.| -|[CDockablePane::GetDragSensitivity](#getdragsensitivity)|Returns the drag sensitivity of a docking pane.| -|[CDockablePane::GetLastPercentInPaneContainer](#getlastpercentinpanecontainer)|Retrieves the percentage of space that a pane occupies within its container.| -|[CDockablePane::GetTabArea](#gettabarea)|Retrieves the tab area for the pane.| -|[CDockablePane::GetTabbedPaneRTC](#gettabbedpanertc)|Returns the runtime class information about a tabbed window that is created when another pane docks to the current pane.| -|[CDockablePane::HasAutoHideMode](#hasautohidemode)|Specifies whether a docking pane can be switched to auto-hide mode.| -|[CDockablePane::HitTest](#hittest)|Specifies the specific location in a pane where the user clicks a mouse.| +|[`CDockablePane::GetCaptionHeight`](#getcaptionheight)|Returns the height of the current caption.| +|[`CDockablePane::GetDefaultPaneDivider`](#getdefaultpanedivider)|Returns the default pane divider for the pane's container.| +|[`CDockablePane::GetDockingStatus`](#getdockingstatus)|Determines the ability of a pane to be docked based on the provided pointer location.| +|[`CDockablePane::GetDragSensitivity`](#getdragsensitivity)|Returns the drag sensitivity of a docking pane.| +|[`CDockablePane::GetLastPercentInPaneContainer`](#getlastpercentinpanecontainer)|Retrieves the percentage of space that a pane occupies within its container.| +|[`CDockablePane::GetTabArea`](#gettabarea)|Retrieves the tab area for the pane.| +|[`CDockablePane::GetTabbedPaneRTC`](#gettabbedpanertc)|Returns the runtime class information about a tabbed window that is created when another pane docks to the current pane.| +|[`CDockablePane::HasAutoHideMode`](#hasautohidemode)|Specifies whether a docking pane can be switched to auto-hide mode.| +|[`CDockablePane::HitTest`](#hittest)|Specifies the specific location in a pane where the user clicks a mouse.| |`CDockablePane::IsAccessibilityCompatible`|Used internally.| -|[CDockablePane::IsAutohideAllEnabled](#isautohideallenabled)|Indicates whether the docking pane and all other panes in the container can be placed in auto-hide mode.| -|[CDockablePane::IsAutoHideMode](#isautohidemode)|Determines whether a pane is in auto-hide mode.| +|[`CDockablePane::IsAutohideAllEnabled`](#isautohideallenabled)|Indicates whether the docking pane and all other panes in the container can be placed in auto-hide mode.| +|[`CDockablePane::IsAutoHideMode`](#isautohidemode)|Determines whether a pane is in auto-hide mode.| |`CDockablePane::IsChangeState`|Used internally.| -|[CDockablePane::IsDocked](#isdocked)|Determines whether the current pane is docked.| -|[CDockablePane::IsHideInAutoHideMode](#ishideinautohidemode)|Determines the behavior of a pane that is in auto-hide mode if it is shown (or hidden) by calling `ShowPane`.| -|[CDockablePane::IsInFloatingMultiPaneFrameWnd](#isinfloatingmultipaneframewnd)|Specifies whether the pane is in a multi-pane frame window.| -|[CDockablePane::IsResizable](#isresizable)|Specifies whether the pane is resizable.| -|[CDockablePane::IsTabLocationBottom](#istablocationbottom)|Specifies whether tabs are located at the top or bottom of the pane.| -|[CDockablePane::IsTracked](#istracked)|Specifies whether a pane is being dragged by the user.| -|[CDockablePane::IsVisible](#isvisible)|Determines whether the current pane is visible.| -|[CDockablePane::LoadState](#loadstate)|Used internally.| -|[CDockablePane::OnAfterChangeParent](#onafterchangeparent)|Called by the framework when the parent of a pane has changed. (Overrides [CPane::OnAfterChangeParent](../../mfc/reference/cpane-class.md#onafterchangeparent).)| -|[CDockablePane::OnAfterDockFromMiniFrame](#onafterdockfromminiframe)|Called by the framework when a floating docking bar docks at a frame window.| -|[CDockablePane::OnBeforeChangeParent](#onbeforechangeparent)|Called by the framework when the parent of the pane is about to change. (Overrides [CPane::OnBeforeChangeParent](../../mfc/reference/cpane-class.md#onbeforechangeparent).)| -|[CDockablePane::OnBeforeFloat](#onbeforefloat)|Called by the framework when a pane is about to float. (Overrides [CPane::OnBeforeFloat](../../mfc/reference/cpane-class.md#onbeforefloat).)| -|[CDockablePane::RemoveFromDefaultPaneDividier](#removefromdefaultpanedividier)|The framework calls this method when a pane is being undocked.| -|[CDockablePane::ReplacePane](#replacepane)|Replaces the pane with a specified pane.| -|[CDockablePane::RestoreDefaultPaneDivider](#restoredefaultpanedivider)|The framework calls this method as a pane is deserialized to restore the default pane divider.| +|[`CDockablePane::IsDocked`](#isdocked)|Determines whether the current pane is docked.| +|[`CDockablePane::IsHideInAutoHideMode`](#ishideinautohidemode)|Determines the behavior of a pane that is in auto-hide mode if it's shown (or hidden) by calling `ShowPane`.| +|[`CDockablePane::IsInFloatingMultiPaneFrameWnd`](#isinfloatingmultipaneframewnd)|Specifies whether the pane is in a multi-pane frame window.| +|[`CDockablePane::IsResizable`](#isresizable)|Specifies whether the pane is resizable.| +|[`CDockablePane::IsTabLocationBottom`](#istablocationbottom)|Specifies whether tabs are located at the top or bottom of the pane.| +|[`CDockablePane::IsTracked`](#istracked)|Specifies whether a pane is being dragged by the user.| +|[`CDockablePane::IsVisible`](#isvisible)|Determines whether the current pane is visible.| +|[`CDockablePane::LoadState`](#loadstate)|Used internally.| +|[`CDockablePane::OnAfterChangeParent`](#onafterchangeparent)|Called by the framework when the parent of a pane has changed. (Overrides [`CPane::OnAfterChangeParent`](../../mfc/reference/cpane-class.md#onafterchangeparent).)| +|[`CDockablePane::OnAfterDockFromMiniFrame`](#onafterdockfromminiframe)|Called by the framework when a floating docking bar docks at a frame window.| +|[`CDockablePane::OnBeforeChangeParent`](#onbeforechangeparent)|Called by the framework when the parent of the pane is about to change. (Overrides [`CPane::OnBeforeChangeParent`](../../mfc/reference/cpane-class.md#onbeforechangeparent).)| +|[`CDockablePane::OnBeforeFloat`](#onbeforefloat)|Called by the framework when a pane is about to float. (Overrides [`CPane::OnBeforeFloat`](../../mfc/reference/cpane-class.md#onbeforefloat).)| +|[`CDockablePane::RemoveFromDefaultPaneDividier`](#removefromdefaultpanedividier)|The framework calls this method when a pane is being undocked.| +|[`CDockablePane::ReplacePane`](#replacepane)|Replaces the pane with a specified pane.| +|[`CDockablePane::RestoreDefaultPaneDivider`](#restoredefaultpanedivider)|The framework calls this method as a pane is deserialized to restore the default pane divider.| |`CDockablePane::SaveState`|Used internally.| |`CDockablePane::Serialize`|Serializes the pane. (Overrides `CBasePane::Serialize`.)| -|[CDockablePane::SetAutoHideMode](#setautohidemode)|Toggles the docking pane between visible and auto-hide mode.| -|[CDockablePane::SetAutoHideParents](#setautohideparents)|Sets the auto-hide button and auto-hide toolbar for the pane.| +|[`CDockablePane::SetAutoHideMode`](#setautohidemode)|Toggles the docking pane between visible and auto-hide mode.| +|[`CDockablePane::SetAutoHideParents`](#setautohideparents)|Sets the auto-hide button and auto-hide toolbar for the pane.| |`CDockablePane::SetDefaultPaneDivider`|Used internally.| -|[CDockablePane::SetLastPercentInPaneContainer](#setlastpercentinpanecontainer)|Sets the percentage of space that a pane occupies within its container.| +|[`CDockablePane::SetLastPercentInPaneContainer`](#setlastpercentinpanecontainer)|Sets the percentage of space that a pane occupies within its container.| |`CDockablePane::SetResizeMode`|Used internally.| -|[CDockablePane::SetRestoredDefaultPaneDivider](#setrestoreddefaultpanedivider)|Sets the restored default pane divider.| -|[CDockablePane::SetTabbedPaneRTC](#settabbedpanertc)|Sets the runtime class information for a tabbed window that is created when two panes dock together.| -|[CDockablePane::ShowPane](#showpane)|Shows or hides a pane.| -|[CDockablePane::Slide](#slide)|Shows or hides a pane with a sliding animation which displays only when the pane is in auto-hide mode.| -|[CDockablePane::ToggleAutoHide](#toggleautohide)|Toggles auto-hide mode. (Overrides [CPane::ToggleAutoHide](../../mfc/reference/cpane-class.md#toggleautohide) .)| -|[CDockablePane::UndockPane](#undockpane)|Undocks a pane from either the main frame window or a miniframe window container.| -|`CDockablePane::UnSetAutoHideMode`|Used internally. To set the auto-hide mode, use [CDockablePane::SetAutoHideMode](#setautohidemode)| +|[`CDockablePane::SetRestoredDefaultPaneDivider`](#setrestoreddefaultpanedivider)|Sets the restored default pane divider.| +|[`CDockablePane::SetTabbedPaneRTC`](#settabbedpanertc)|Sets the runtime class information for a tabbed window that is created when two panes dock together.| +|[`CDockablePane::ShowPane`](#showpane)|Shows or hides a pane.| +|[`CDockablePane::Slide`](#slide)|Shows or hides a pane with a sliding animation that displays only when the pane is in auto-hide mode.| +|[`CDockablePane::ToggleAutoHide`](#toggleautohide)|Toggles auto-hide mode. (Overrides [`CPane::ToggleAutoHide`](../../mfc/reference/cpane-class.md#toggleautohide) .)| +|[`CDockablePane::UndockPane`](#undockpane)|Undocks a pane from either the main frame window or a miniframe window container.| +|`CDockablePane::UnSetAutoHideMode`|Used internally. To set the auto-hide mode, use [`CDockablePane::SetAutoHideMode`](#setautohidemode)| ### Protected Methods |Name|Description| |----------|-----------------| -|[CDockablePane::CheckAutoHideCondition](#checkautohidecondition)|Determines whether the docking pane is hidden (in auto-hide mode).| -|[CDockablePane::CheckStopSlideCondition](#checkstopslidecondition)|Determines when an auto-hide docking pane should stop sliding.| -|[CDockablePane::DrawCaption](#drawcaption)|Draws the docking pane caption (gripper).| -|[CDockablePane::OnPressButtons](#onpressbuttons)|Called when the user presses a caption button other than the AFX_HTCLOSE and AFX_HTMAXBUTTON buttons.| -|[CDockablePane::OnSlide](#onslide)|Called by the framework to render the auto-hide slide effect when the pane is either shown or hidden.| +|[`CDockablePane::CheckAutoHideCondition`](#checkautohidecondition)|Determines whether the docking pane is hidden (in auto-hide mode).| +|[`CDockablePane::CheckStopSlideCondition`](#checkstopslidecondition)|Determines when an auto-hide docking pane should stop sliding.| +|[`CDockablePane::DrawCaption`](#drawcaption)|Draws the docking pane caption (gripper).| +|[`CDockablePane::OnPressButtons`](#onpressbuttons)|Called when the user presses a caption button other than the `AFX_HTCLOSE` and `AFX_HTMAXBUTTON` buttons.| +|[`CDockablePane::OnSlide`](#onslide)|Called by the framework to render the auto-hide slide effect when the pane is either shown or hidden.| ### Data Members |Name|Description| |----------|-----------------| -|[CDockablePane::m_bDisableAnimation](#m_bdisableanimation)|Specifies whether auto-hide animation of the dockable pane is disabled.| -|[CDockablePane::m_bHideInAutoHideMode](#m_bhideinautohidemode)|Determines the behavior of the pane when the pane is in auto-hide mode.| -|[CDockablePane::m_nSlideSteps](#m_nslidesteps)|Specifies the animation speed of the pane when it is being shown or hidden when in auto-hide mode.| +|[`CDockablePane::m_bDisableAnimation`](#m_bdisableanimation)|Specifies whether auto-hide animation of the dockable pane is disabled.| +|[`CDockablePane::m_bHideInAutoHideMode`](#m_bhideinautohidemode)|Determines the behavior of the pane when the pane is in auto-hide mode.| +|[`CDockablePane::m_nSlideSteps`](#m_nslidesteps)|Specifies the animation speed of the pane when it's being shown or hidden when in auto-hide mode.| ## Remarks @@ -139,21 +138,21 @@ class CDockablePane : public CPane - Dragging a pane while displaying a drag rectangle. -To use a docking pane in your application, derive your pane class from the `CDockablePane` class. Either embed the derived object into the main frame window object or into a window object that controls the instance of your pane. Then call the [CDockablePane::Create](#create) method or the [CDockablePane::CreateEx](#createex) method when you process the WM_CREATE message in the main frame window. Finally, set up the pane object by calling [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking), [CBasePane::DockPane](../../mfc/reference/cbasepane-class.md#dockpane), or [CDockablePane::AttachToTabWnd](#attachtotabwnd). +To use a docking pane in your application, derive your pane class from the `CDockablePane` class. Either embed the derived object into the main frame window object or into a window object that controls the instance of your pane. Then call the [`CDockablePane::Create`](#create) method or the [`CDockablePane::CreateEx`](#createex) method when you process the `WM_CREATE` message in the main frame window. Finally, set up the pane object by calling [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking), [`CBasePane::DockPane`](../../mfc/reference/cbasepane-class.md#dockpane), or [`CDockablePane::AttachToTabWnd`](#attachtotabwnd). ## Customization Tips The following tips apply to `CDockablePane` objects: -- If you call [CDockablePane::AttachToTabWnd](#attachtotabwnd) for two non-tabbed, dockable panes, a pointer to a tabbed window will be returned in the *ppTabbedControlBar* parameter. You can continue to add tabs to the tabbed window by using this parameter. +- If you call [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) for two non-tabbed, dockable panes, a pointer to a tabbed window will be returned in the *`ppTabbedControlBar`* parameter. You can continue to add tabs to the tabbed window by using this parameter. -- The kind of tabbed pane that is created by [CDockablePane::AttachToTabWnd](#attachtotabwnd) is determined by the `CDockablePane` object in the *pTabControlBarAttachTo* parameter. You can call [CDockablePane::SetTabbedPaneRTC](#settabbedpanertc) to set the kind of tabbed pane that the `CDockablePane` will create. The default type is determined by the `dwTabbedStyle` of [CDockablePane::Create](#create) when you first create the `CDockablePane`. If *dwTabbedStyle* is AFX_CBRS_OUTLOOK_TABS the default type is [CMFCOutlookBar Class](../../mfc/reference/cmfcoutlookbar-class.md); if *dwTabbedStyle* is AFX_CBRS_REGULAR_TABS the default type is [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md). +- The kind of tabbed pane that is created by [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) is determined by the `CDockablePane` object in the *`pTabControlBarAttachTo`* parameter. You can call [`CDockablePane::SetTabbedPaneRTC`](#settabbedpanertc) to set the kind of tabbed pane that the `CDockablePane` will create. The default type is determined by the `dwTabbedStyle` of [`CDockablePane::Create`](#create) when you first create the `CDockablePane`. If *`dwTabbedStyle`* is `AFX_CBRS_OUTLOOK_TABS` the default type is [`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md); if *`dwTabbedStyle`* is `AFX_CBRS_REGULAR_TABS` the default type is [`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md). -- If you want to dock one dockable pane to another, call the [CDockablePane::DockToWindow](#docktowindow) method. The original pane must be docked somewhere before you call this method. +- If you want to dock one dockable pane to another, call the [`CDockablePane::DockToWindow`](#docktowindow) method. The original pane must be docked somewhere before you call this method. -- The member variable [CDockablePane::m_bHideInAutoHideMode](#m_bhideinautohidemode) controls how dockable panes behave in auto hide mode when you call [CDockablePane::ShowPane](#showpane). If this member variable is set to TRUE, dockable panes and their auto hide buttons will be hidden. Otherwise, they will slide in and out. +- The member variable [`CDockablePane::m_bHideInAutoHideMode`](#m_bhideinautohidemode) controls how dockable panes behave in auto hide mode when you call [`CDockablePane::ShowPane`](#showpane). If this member variable is set to `TRUE`, dockable panes and their auto hide buttons will be hidden. Otherwise, they'll slide in and out. -- You can disable auto-hide animation by setting the [CDockablePane::m_bDisableAnimation](#m_bdisableanimation) member variable to TRUE. +- You can disable auto-hide animation by setting the [`CDockablePane::m_bDisableAnimation`](#m_bdisableanimation) member variable to `TRUE`. ## Example @@ -164,23 +163,23 @@ The following example demonstrates how to configure a `CDockablePane` object by ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CBasePane](../../mfc/reference/cbasepane-class.md) +[`CBasePane`](../../mfc/reference/cbasepane-class.md) -[CPane](../../mfc/reference/cpane-class.md) +[`CPane`](../../mfc/reference/cpane-class.md) -[CDockablePane](../../mfc/reference/cdockablepane-class.md) +[`CDockablePane`](../../mfc/reference/cdockablepane-class.md) ## Requirements -**Header:** afxDockablePane.h +**Header:** `afxDockablePane.h` -## CDockablePane::AttachToTabWnd +## `CDockablePane::AttachToTabWnd` Attaches the current pane to a target pane, creating a tabbed pane. @@ -194,45 +193,45 @@ virtual CDockablePane* AttachToTabWnd( ### Parameters -*pTabControlBarAttachTo*
+*`pTabControlBarAttachTo`*\ [in, out] Specifies the target pane that the current pane attaches to. The target pane must be a dockable pane. -*dockMethod*
+*`dockMethod`*\ [in] Specifies the docking method. -*bSetActive*
-[in] TRUE to activate the tabbed pane after the attach operation; otherwise, FALSE. +*`bSetActive`*\ +[in] `TRUE` to activate the tabbed pane after the attach operation; otherwise, `FALSE`. -*ppTabbedControlBar*
+*`ppTabbedControlBar`*\ [out] Contains the tabbed pane that results from the attach operation. ### Return Value -A pointer to the current pane, if it is not a tabbed pane; otherwise a pointer to the tabbed pane that results from the attach operation. The return value is NULL if the current pane cannot be attached, or if an error occurs. +A pointer to the current pane, if it isn't a tabbed pane; otherwise a pointer to the tabbed pane that results from the attach operation. The return value is `NULL` if the current pane can't be attached, or if an error occurs. ### Remarks When one dockable pane attaches to another pane using this method, the following occurs: -1. The framework checks whether the target pane *pTabControlBarAttachTo* is a regular docking pane or if it is derived from [CBaseTabbedPane](../../mfc/reference/cbasetabbedpane-class.md). +1. The framework checks whether the target pane *`pTabControlBarAttachTo`* is a regular docking pane or if it's derived from [`CBaseTabbedPane`](../../mfc/reference/cbasetabbedpane-class.md). 1. If the target pane is a tabbed pane, the framework adds the current pane to it as a tab. 1. If the target pane is a regular docking pane, the framework creates a tabbed pane. - - The framework calls `pTabControlBarAttachTo->CreateTabbedPane`. The style of the new tabbed pane depends on the `m_pTabbedControlBarRTC` member. By default, this member is set to the runtime class of [CTabbedPane](../../mfc/reference/ctabbedpane-class.md). If you pass the AFX_CBRS_OUTLOOK_TABS style as the *dwTabbedStyle* parameter to the [CDockablePane::Create](#create) method, the runtime class object is set to the runtime class of [CMFCOutlookBar](../../mfc/reference/cmfcoutlookbar-class.md). You can change this member at any time to change the style of the new pane. + - The framework calls `pTabControlBarAttachTo->CreateTabbedPane`. The style of the new tabbed pane depends on the `m_pTabbedControlBarRTC` member. By default, this member is set to the runtime class of [`CTabbedPane`](../../mfc/reference/ctabbedpane-class.md). If you pass the `AFX_CBRS_OUTLOOK_TABS` style as the *`dwTabbedStyle`* parameter to the [`CDockablePane::Create`](#create) method, the runtime class object is set to the runtime class of [`CMFCOutlookBar`](../../mfc/reference/cmfcoutlookbar-class.md). You can change this member at any time to change the style of the new pane. - - When this method creates a tabbed pane, the framework replaces the pointer to *pTabControlBarAttachTo* (if the pane is docked or floating in a multi-miniframe window) with a pointer to the new tabbed pane. + - When this method creates a tabbed pane, the framework replaces the pointer to *`pTabControlBarAttachTo`* (if the pane is docked or floating in a multi-miniframe window) with a pointer to the new tabbed pane. - - The framework adds the *pTabControlBarAttachTo* pane to the tabbed pane as the first tab. The framework then adds the current pane as a second tab. + - The framework adds the *`pTabControlBarAttachTo`* pane to the tabbed pane as the first tab. The framework then adds the current pane as a second tab. -1. If the current pane is derived from `CBaseTabbedPane`, all of its tabs are moved to *pTabControlBarAttachTo* and the current pane is destroyed. Therefore, be careful when you call this method, because a pointer to the current pane may be invalid when the method returns. +1. If the current pane is derived from `CBaseTabbedPane`, all of its tabs are moved to *`pTabControlBarAttachTo`* and the current pane is destroyed. Therefore, be careful when you call this method, because a pointer to the current pane may be invalid when the method returns. -If you attach one pane to another when building a docking layout, set `dockMethod` to DM_SHOW. +If you attach one pane to another when building a docking layout, set `dockMethod` to `DM_SHOW`. You should dock the first pane before you attach another pane to it. -## CDockablePane::CalcFixedLayout +## `CDockablePane::CalcFixedLayout` Returns the size of the pane rectangle. @@ -244,17 +243,17 @@ virtual CSize CalcFixedLayout( ### Parameters -*bStretch*
+*`bStretch`*\ [in] Not used. -*bHorz*
+*`bHorz`*\ [in] Not used. ### Return Value A `CSize` object that contains the size of the pane rectangle. -## CDockablePane::CanAcceptMiniFrame +## `CDockablePane::CanAcceptMiniFrame` Determines whether the specified mini-frame can be docked to the pane. @@ -264,14 +263,14 @@ virtual BOOL CanAcceptMiniFrame(CPaneFrameWnd* pMiniFrame) const; ### Parameters -*pMiniFrame*
+*`pMiniFrame`*\ [in] Pointer to a `CPaneFrameWnd` object. ### Return Value -TRUE if *pMiniFrame* can be docked to the pane; otherwise, FALSE. +`TRUE` if *`pMiniFrame`* can be docked to the pane; otherwise, `FALSE`. -## CDockablePane::CanAcceptPane +## `CDockablePane::CanAcceptPane` Determines whether another pane can be docked to the current pane. @@ -281,12 +280,12 @@ virtual BOOL CanAcceptPane(const CBasePane* pBar) const; ### Parameters -*pBar*
+*`pBar`*\ [in] Specifies the pane to dock to the current pane. ### Return Value -TRUE if the specified pane can be docked to this pane; otherwise, FALSE. +`TRUE` if the specified pane can be docked to this pane; otherwise, `FALSE`. ### Remarks @@ -294,9 +293,9 @@ The framework calls this method before a pane is docked to the current pane. Override this function in a derived class to enable or disable docking to a specific pane. -By default, this method returns TRUE if either *pBar* or its parent is of type `CDockablePane`. +By default, this method returns `TRUE` if either *`pBar`* or its parent is of type `CDockablePane`. -## CDockablePane::CanAutoHide +## `CDockablePane::CanAutoHide` Determines whether the pane can auto-hide. @@ -306,19 +305,19 @@ virtual BOOL CanAutoHide() const; ### Return Value -TRUE if the pane can auto-hide; otherwise, FALSE. +`TRUE` if the pane can auto-hide; otherwise, `FALSE`. ### Remarks -`CDockablePane::CanAutoHide` returns FALSE in any of the following situations: +`CDockablePane::CanAutoHide` returns `FALSE` in any of the following situations: - The pane has no parent. -- The docking manager does not allow panes to auto-hide. +- The docking manager doesn't allow panes to auto-hide. -- The pane is not docked. +- The pane isn't docked. -## CDockablePane::CanBeAttached +## `CDockablePane::CanBeAttached` Determines whether the current pane can be docked to another pane. @@ -328,15 +327,15 @@ virtual BOOL CanBeAttached() const; ### Return Value -TRUE if the dockable pane can be docked to another pane or to the main frame window; otherwise, FALSE. +`TRUE` if the dockable pane can be docked to another pane or to the main frame window; otherwise, `FALSE`. ### Remarks -By default, this method always returns TRUE. Override this method in a derived class to enable or disable docking without calling [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking). +By default, this method always returns `TRUE`. Override this method in a derived class to enable or disable docking without calling [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking). -## CDockablePane::CDockablePane +## `CDockablePane::CDockablePane` -Constructs and initializes a [CDockablePane](../../mfc/reference/cdockablepane-class.md) object. +Constructs and initializes a [`CDockablePane`](../../mfc/reference/cdockablepane-class.md) object. ``` CDockablePane(); @@ -344,9 +343,9 @@ CDockablePane(); ### Remarks -After you construct a dockable pane object, call [CDockablePane::Create](#create) or [CDockablePane::CreateEx](#createex) to create it. +After you construct a dockable pane object, call [`CDockablePane::Create`](#create) or [`CDockablePane::CreateEx`](#createex) to create it. -## CDockablePane::ConvertToTabbedDocument +## `CDockablePane::ConvertToTabbedDocument` Converts one or more dockable panes to MDI tabbed documents. @@ -356,10 +355,10 @@ virtual void ConvertToTabbedDocument(BOOL bActiveTabOnly = TRUE); ### Parameters -*bActiveTabOnly*
-[in] When you convert a `CTabbedPane`, specify TRUE to convert only the active tab. Specify FALSE to convert all tabs in the pane. +*`bActiveTabOnly`*\ +[in] When you convert a `CTabbedPane`, specify `TRUE` to convert only the active tab. Specify `FALSE` to convert all tabs in the pane. -## CDockablePane::CheckAutoHideCondition +## `CDockablePane::CheckAutoHideCondition` Determines whether the docking pane is hidden (also known as autohide mode). @@ -369,15 +368,15 @@ virtual BOOL CheckAutoHideCondition(); ### Return Value -TRUE if the hide condition is met; otherwise, FALSE. +`TRUE` if the hide condition is met; otherwise, `FALSE`. ### Remarks -The framework uses a timer to periodically check whether to hide an autohide dockable pane. The method returns TRUE when the pane is not active, the pane is not being resized, and the mouse pointer is not over the pane. +The framework uses a timer to periodically check whether to hide an autohide dockable pane. The method returns `TRUE` when the pane isn't active, the pane isn't being resized, and the mouse pointer isn't over the pane. -If all the previous conditions are met, the framework calls [CDockablePane::Slide](#slide) to hide the pane. +If all the previous conditions are met, the framework calls [`CDockablePane::Slide`](#slide) to hide the pane. -## CDockablePane::CheckStopSlideCondition +## `CDockablePane::CheckStopSlideCondition` Determines when an autohide docking pane should stop sliding. @@ -387,20 +386,20 @@ virtual BOOL CheckStopSlideCondition(BOOL bDirection); ### Parameters -*bDirection*
-[in] TRUE if the pane is visible; FALSE if the pane is hidden. +*`bDirection`*\ +[in] `TRUE` if the pane is visible; `FALSE` if the pane is hidden. ### Return Value -TRUE if the stop condition is met; otherwise, FALSE. +`TRUE` if the stop condition is met; otherwise, `FALSE`. ### Remarks -When a dockable pane is set to autohide mode, the framework uses sliding effects to show or hide the pane. The framework calls this function when the pane is sliding. `CheckStopSlideCondition` returns TRUE when the pane is fully visible or when it is fully hidden. +When a dockable pane is set to autohide mode, the framework uses sliding effects to show or hide the pane. The framework calls this function when the pane is sliding. `CheckStopSlideCondition` returns `TRUE` when the pane is fully visible or when it's fully hidden. Override this method in a derived class to implement custom autohide effects. -## CDockablePane::CopyState +## `CDockablePane::CopyState` Copies the state of a dockable pane. @@ -410,26 +409,26 @@ virtual void CopyState(CDockablePane* pOrgBar); ### Parameters -*pOrgBar*
+*`pOrgBar`*\ [in] A pointer to a dockable pane. ### Remarks -`CDockablePane::CopyState` copies the state of *pOrgBar* to the current pane by calling the following methods: +`CDockablePane::CopyState` copies the state of *`pOrgBar`* to the current pane by calling the following methods: -- [CPane::CopyState](../../mfc/reference/cpane-class.md#copystate) +- [`CPane::CopyState`](../../mfc/reference/cpane-class.md#copystate) -- [CDockablePane::GetAHRestoredRect](#getahrestoredrect) +- [`CDockablePane::GetAHRestoredRect`](#getahrestoredrect) -- [CDockablePane::GetAHSlideMode](#getahslidemode) +- [`CDockablePane::GetAHSlideMode`](#getahslidemode) -- [CDockablePane::GetLastPercentInPaneContainer](#getlastpercentinpanecontainer) +- [`CDockablePane::GetLastPercentInPaneContainer`](#getlastpercentinpanecontainer) -- [CDockablePane::IsAutohideAllEnabled](#isautohideallenabled) +- [`CDockablePane::IsAutohideAllEnabled`](#isautohideallenabled) -## CDockablePane::Create +## `CDockablePane::Create` -Creates the Windows control and attaches it to the [CDockablePane](../../mfc/reference/cdockablepane-class.md) object. +Creates the Windows control and attaches it to the [`CDockablePane`](../../mfc/reference/cdockablepane-class.md) object. ``` virtual BOOL Create( @@ -456,52 +455,52 @@ virtual BOOL Create( ### Parameters -*lpszCaption*
+*`lpszCaption`*\ [in] Specifies the window name. -*pParentWnd*
+*`pParentWnd`*\ [in, out] Specifies the parent window. -*rect*
-[in] Specifies the size and position of the window, in client coordinates of *pParentWnd*. +*`rect`*\ +[in] Specifies the size and position of the window, in client coordinates of *`pParentWnd`*. -*bHasGripper*
-[in] TRUE to create the pane with a caption; otherwise, FALSE. +*`bHasGripper`*\ +[in] `TRUE` to create the pane with a caption; otherwise, `FALSE`. -*nID*
+*`nID`*\ [in] Specifies the ID of the child window. This value must be unique if you want to save docking state for this docking pane. -*dwStyle*
+*`dwStyle`*\ [in] Specifies the window style attributes. -*dwTabbedStyle*
+*`dwTabbedStyle`*\ [in] Specifies the tabbed style of a tabbed window that is created when the user drags a pane on the caption of this pane. -*dwControlBarStyle*
+*`dwControlBarStyle`*\ [in] Specifies additional style attributes. -*pContext*
+*`pContext`*\ [in, out] Specifies the create context of the window. -*lpszWindowName*
+*`lpszWindowName`*\ [in] Specifies the window name. -*sizeDefault*
+*`sizeDefault`*\ [in] Specifies the size of the window. ### Return Value -TRUE if the dockable pane is successfully created; otherwise, FALSE. +`TRUE` if the dockable pane is successfully created; otherwise, `FALSE`. ### Remarks Creates a Windows pane and attaches it to the `CDockablePane` object. -If the *dwStyle* window style has the CBRS_FLOAT_MULTI flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually. +If the *`dwStyle`* window style has the `CBRS_FLOAT_MULTI` flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually. -If the *dwTabbedStyle* parameter has the AFX_CBRS_OUTLOOK_TABS flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the [CDockablePane::AttachToTabWnd](#attachtotabwnd) method. By default, dockable panes create regular tabbed panes of type [CTabbedPane](../../mfc/reference/ctabbedpane-class.md). +If the *`dwTabbedStyle`* parameter has the `AFX_CBRS_OUTLOOK_TABS` flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) method. By default, dockable panes create regular tabbed panes of type [`CTabbedPane`](../../mfc/reference/ctabbedpane-class.md). -## CDockablePane::CreateDefaultPaneDivider +## `CDockablePane::CreateDefaultPaneDivider` Creates a default divider for the pane as it is being docked to a frame window. @@ -514,33 +513,33 @@ static CPaneDivider* __stdcall CreateDefaultPaneDivider( ### Parameters -*dwAlignment*
-[in] Specifies the side of the main frame to which the pane is being docked. If *dwAlignment* contains the CBRS_ALIGN_LEFT or CBRS_ALIGN_RIGHT flag, this method creates a vertical (`CPaneDivider::SS_VERT`) divider; otherwise, this method creates a horizontal (`CPaneDivider::SS_HORZ`) divider. +*`dwAlignment`*\ +[in] Specifies the side of the main frame to which the pane is being docked. If *`dwAlignment`* contains the `CBRS_ALIGN_LEFT` or `CBRS_ALIGN_RIGHT` flag, this method creates a vertical (`CPaneDivider::SS_VERT`) divider; otherwise, this method creates a horizontal (`CPaneDivider::SS_HORZ`) divider. -*pParent*
+*`pParent`*\ [in] Pointer to the parent frame. -*pSliderRTC*
+*`pSliderRTC`*\ [in] Not used. ### Return Value -This method returns a pointer to the newly-created divider, or NULL if divider creation fails. +This method returns a pointer to the newly-created divider, or `NULL` if divider creation fails. ### Remarks -*dwAlignment* can be any of the following values: +*`dwAlignment`* can be any of the following values: |Value|Description| |-----------|-----------------| -|CBRS_ALIGN_TOP|The pane is being docked to the top of the client area of a frame window.| -|CBRS_ALIGN_BOTTOM|The pane is being docked to the bottom of the client area of a frame window.| -|CBRS_ALIGN_LEFT|The pane is being docked to the left side of the client area of a frame window.| -|CBRS_ALIGN_RIGHT|The pane is being docked to the right side of the client area of a frame window.| +|`CBRS_ALIGN_TOP`|The pane is being docked to the top of the client area of a frame window.| +|`CBRS_ALIGN_BOTTOM`|The pane is being docked to the bottom of the client area of a frame window.| +|`CBRS_ALIGN_LEFT`|The pane is being docked to the left side of the client area of a frame window.| +|`CBRS_ALIGN_RIGHT`|The pane is being docked to the right side of the client area of a frame window.| -## CDockablePane::CreateEx +## `CDockablePane::CreateEx` -Creates the Windows control and attaches it to the [CDockablePane](../../mfc/reference/cdockablepane-class.md) object. +Creates the Windows control and attaches it to the [`CDockablePane`](../../mfc/reference/cdockablepane-class.md) object. ``` virtual BOOL CreateEx( @@ -558,49 +557,49 @@ virtual BOOL CreateEx( ### Parameters -*dwStyleEx*
+*`dwStyleEx`*\ [in] Specifies the extended style attributes for the new window. -*lpszCaption*
+*`lpszCaption`*\ [in] Specifies the window name. -*pParentWnd*
+*`pParentWnd`*\ [in, out] Specifies the parent window. -*rect*
-[in] Specifies the size and position of the window, in client coordinates of *pParentWnd*. +*`rect`*\ +[in] Specifies the size and position of the window, in client coordinates of *`pParentWnd`*. -*bHasGripper*
-[in] TRUE to create the pane with a caption; otherwise, FALSE. +*`bHasGripper`*\ +[in] `TRUE` to create the pane with a caption; otherwise, `FALSE`. -*nID*
+*`nID`*\ [in] Specifies the ID of the child window. This value must be unique if you want to save the docking state for this docking pane. -*dwStyle*
+*`dwStyle`*\ [in] Specifies the window style attributes. -*dwTabbedStyle*
+*`dwTabbedStyle`*\ [in] Specifies the tabbed style of a tabbed window that is created when the user drags a pane on the caption of this pane. -*dwControlBarStyle*
+*`dwControlBarStyle`*\ [in] Specifies the additional style attributes. -*pContext*
+*`pContext`*\ [in, out] Specifies the create context of the window. ### Return Value -TRUE if the dockable pane is successfully created; otherwise, FALSE. +`TRUE` if the dockable pane is successfully created; otherwise, `FALSE`. ### Remarks Creates a Windows pane and attaches it to the `CDockablePane` object. -If the *dwStyle* window style has the CBRS_FLOAT_MULTI flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually. +If the *`dwStyle`* window style has the `CBRS_FLOAT_MULTI` flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually. -If the *dwTabbedStyle* parameter has the AFX_CBRS_OUTLOOK_TABS flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the [CDockablePane::AttachToTabWnd](#attachtotabwnd) method. By default, dockable panes create regular tabbed panes of type [CTabbedPane](../../mfc/reference/ctabbedpane-class.md). +If the *`dwTabbedStyle`* parameter has the `AFX_CBRS_OUTLOOK_TABS` flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) method. By default, dockable panes create regular tabbed panes of type [`CTabbedPane`](../../mfc/reference/ctabbedpane-class.md). -## CDockablePane::CreateTabbedPane +## `CDockablePane::CreateTabbedPane` Creates a tabbed pane from the current pane. @@ -610,17 +609,17 @@ virtual CTabbedPane* CreateTabbedPane(); ### Return Value -The new tabbed pane, or NULL if the create operation failed. +The new tabbed pane, or `NULL` if the create operation failed. ### Remarks -The framework calls this method when it creates a tabbed pane to replace this pane. For more information, see [CDockablePane::AttachToTabWnd](#attachtotabwnd). +The framework calls this method when it creates a tabbed pane to replace this pane. For more information, see [`CDockablePane::AttachToTabWnd`](#attachtotabwnd). Override this method in a derived class to customize how tabbed panes are created and initialized. -The tabbed pane is created according to the runtime class information stored in the `m_pTabbedControlBarRTC` member, which is initialized by the [CDockablePane::CreateEx](#createex) method. +The tabbed pane is created according to the runtime class information stored in the `m_pTabbedControlBarRTC` member, which is initialized by the [`CDockablePane::CreateEx`](#createex) method. -## CDockablePane::DockPaneContainer +## `CDockablePane::DockPaneContainer` Docks a container to the pane. @@ -633,31 +632,31 @@ virtual BOOL DockPaneContainer( ### Parameters -*barContainerManager*
+*`barContainerManager`*\ [in] A reference to the container manager of the container that is being docked. -*dwAlignment*
-[in] DWORD that specifies the side of the pane to which the container is being docked. +*`dwAlignment`*\ +[in] `DWORD` that specifies the side of the pane to which the container is being docked. -*dockMethod*
+*`dockMethod`*\ [in] Not used. ### Return Value -TRUE if the container was successfully docked to the pane; otherwise, FALSE. +`TRUE` if the container was successfully docked to the pane; otherwise, `FALSE`. ### Remarks -*dwAlignment* can be any of the following values: +*`dwAlignment`* can be any of the following values: |Value|Description| |-----------|-----------------| -|CBRS_ALIGN_TOP|The container is being docked to the top of the pane.| -|CBRS_ALIGN_BOTTOM|The container is being docked to the bottom of the pane.| -|CBRS_ALIGN_LEFT|The container is being docked to the left of the pane.| -|CBRS_ALIGN_RIGHT|The container is being docked to the right of the pane.| +|`CBRS_ALIGN_TOP`|The container is being docked to the top of the pane.| +|`CBRS_ALIGN_BOTTOM`|The container is being docked to the bottom of the pane.| +|`CBRS_ALIGN_LEFT`|The container is being docked to the left of the pane.| +|`CBRS_ALIGN_RIGHT`|The container is being docked to the right of the pane.| -## CDockablePane::DockPaneStandard +## `CDockablePane::DockPaneStandard` Docks a pane by using outline (standard) docking. @@ -667,14 +666,14 @@ virtual CPane* DockPaneStandard(BOOL& bWasDocked); ### Parameters -*bWasDocked*
-[in] When the method returns, this value contains TRUE if the pane was successfully docked; otherwise, it contains FALSE. +*`bWasDocked`*\ +[in] When the method returns, this value contains `TRUE` if the pane was successfully docked; otherwise, it contains `FALSE`. ### Return Value -If the pane was docked to a tabbed window, or if a tabbed window was created as a result of docking, this method returns a pointer to the tabbed window. If the pane was otherwise successfully docked, this method returns the **`this`** pointer. If docking failed, this method returns NULL. +If the pane was docked to a tabbed window, or if a tabbed window was created as a result of docking, this method returns a pointer to the tabbed window. If the pane was otherwise successfully docked, this method returns the **`this`** pointer. If docking failed, this method returns `NULL`. -## CDockablePane::DockToRecentPos +## `CDockablePane::DockToRecentPos` Docks a pane to its stored docking position. @@ -684,13 +683,13 @@ BOOL CDockablePane::DockToRecentPos(); ### Return Value -TRUE if the pane is successfully docked; otherwise, FALSE. +`TRUE` if the pane is successfully docked; otherwise, `FALSE`. ### Remarks -Dockable panes store recent docking information in a [CRecentDockSiteInfo](../../mfc/reference/crecentdocksiteinfo-class.md) object. +Dockable panes store recent docking information in a [`CRecentDockSiteInfo`](../../mfc/reference/crecentdocksiteinfo-class.md) object. -## CDockablePane::DockToWindow +## `CDockablePane::DockToWindow` Docks one docking pane to another docking pane. @@ -703,24 +702,24 @@ virtual BOOL DockToWindow( ### Parameters -*pTargetWindow*
+*`pTargetWindow`*\ [in, out] Specifies the dockable pane to dock this pane to. -*dwAlignment*
-[in] Specifies the docking alignment for the pane. May be one of CBRS_ALIGN_LEFT, CBRS_ALIGN_TOP, CBRS_ALIGN_RIGHT, CBRS_ALIGN_BOTTOM or CBRS_ALIGN_ANY. (Defined in afxres.h.) +*`dwAlignment`*\ +[in] Specifies the docking alignment for the pane. May be one of `CBRS_ALIGN_LEFT`, `CBRS_ALIGN_TOP`, `CBRS_ALIGN_RIGHT`, `CBRS_ALIGN_BOTTOM` or `CBRS_ALIGN_ANY`. (Defined in `afxres.h`.) -*lpRect*
+*`lpRect`*\ [in] Specifies the docking rectangle for the pane. ### Return Value -TRUE if the pane was docked successfully; otherwise, FALSE. +`TRUE` if the pane was docked successfully; otherwise, `FALSE`. ### Remarks -Call this method to dock one pane to another pane with the alignment specified by *dwAlignment*. +Call this method to dock one pane to another pane with the alignment specified by *`dwAlignment`*. -## CDockablePane::DrawCaption +## `CDockablePane::DrawCaption` Draws the caption (also called the gripper) of a docking pane. @@ -732,10 +731,10 @@ virtual void DrawCaption( ### Parameters -*pDC*
+*`pDC`*\ [in] Represents the device context used for drawing. -*rectCaption*
+*`rectCaption`*\ [in] Specifies the bounding rectangle of the pane's caption. ### Remarks @@ -744,7 +743,7 @@ The framework calls this method to draw the caption of a dockable pane. Override this method in a derived class to customize the appearance of the caption. -## CDockablePane::EnableAutohideAll +## `CDockablePane::EnableAutohideAll` Enables or disables autohide mode for this pane and for other panes in the container. @@ -754,16 +753,16 @@ void EnableAutohideAll(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the autohide all feature for the dockable pane; otherwise, FALSE. +*`bEnable`*\ +[in] `TRUE` to enable the autohide all feature for the dockable pane; otherwise, `FALSE`. ### Remarks When a user holds the **Ctrl** key and clicks the pin button to switch a pane to autohide mode, all other panes in the same container are also switched to autohide mode. -Call this method with *bEnable* set to FALSE to disable this feature for a particular pane. +Call this method with *`bEnable`* set to `FALSE` to disable this feature for a particular pane. -## CDockablePane::EnableGripper +## `CDockablePane::EnableGripper` Shows or hides the caption (also called the gripper). @@ -773,16 +772,16 @@ virtual void EnableGripper(BOOL bEnable); ### Parameters -*bEnable*
-[in] TRUE to enable the caption; otherwise, FALSE. +*`bEnable`*\ +[in] `TRUE` to enable the caption; otherwise, `FALSE`. ### Remarks -When the framework creates dockable panes, they do not have the WS_STYLE window style, even if specified. This means that the pane's caption is a non-client area that is controlled by the framework, but this area differs from the standard window caption. +When the framework creates dockable panes, they don't have the `WS_STYLE` window style, even if specified. This means that the pane's caption is a non-client area that is controlled by the framework, but this area differs from the standard window caption. You can show or hide the caption at any time. The framework hides the caption when a pane is added as a tab to a tabbed window or when a pane is floated in a miniframe window. -## CDockablePane::GetAHRestoredRect +## `CDockablePane::GetAHRestoredRect` Specifies the position of the pane when in auto-hide mode. @@ -796,7 +795,7 @@ A `CRect` object that contains the position of the pane when it is in auto-hide ### Remarks -## CDockablePane::GetAHSlideMode +## `CDockablePane::GetAHSlideMode` Retrieves the auto-hide slide mode for the pane. @@ -806,11 +805,11 @@ virtual UINT GetAHSlideMode() const; ### Return Value -A UINT that specifies the auto-hide slide mode for the pane. The return value can be either AFX_AHSM_MOVE or AFX_AHSM_STRETCH, but the implementation only uses AFX_AHSM_MOVE. +A `UINT` that specifies the auto-hide slide mode for the pane. The return value can be either `AFX_AHSM_MOVE` or `AFX_AHSM_STRETCH`, but the implementation only uses `AFX_AHSM_MOVE`. ### Remarks -## CDockablePane::GetCaptionHeight +## `CDockablePane::GetCaptionHeight` Returns the height, in pixels, of the current caption. @@ -824,9 +823,9 @@ The height of the caption, in pixels. ### Remarks -The caption height is 0 if the caption was hidden by the [CDockablePane::EnableGripper](#enablegripper) method, or if the pane does not have a caption. +The caption height is 0 if the caption was hidden by the [`CDockablePane::EnableGripper`](#enablegripper) method, or if the pane doesn't have a caption. -## CDockablePane::GetDefaultPaneDivider +## `CDockablePane::GetDefaultPaneDivider` Returns the default pane divider for the pane's container. @@ -836,13 +835,13 @@ CPaneDivider* GetDefaultPaneDivider() const; ### Return Value -A valid [CPaneDivider](../../mfc/reference/cpanedivider-class.md) object if the dockable pane is docked to the main frame window, or `NULL` if the dockable pane is not docked or if it is floating. +A valid [`CPaneDivider`](../../mfc/reference/cpanedivider-class.md) object if the dockable pane is docked to the main frame window, or `NULL` if the dockable pane isn't docked or if it's floating. ### Remarks -For more information about pane dividers, see [CPaneDivider Class](../../mfc/reference/cpanedivider-class.md). +For more information about pane dividers, see [`CPaneDivider` Class](../../mfc/reference/cpanedivider-class.md). -## CDockablePane::GetDockingStatus +## `CDockablePane::GetDockingStatus` Determines the ability of a pane to be docked based on the provided pointer location. @@ -854,32 +853,32 @@ virtual AFX_CS_STATUS GetDockingStatus( ### Parameters -*pt*
+*`pt`*\ [in] The location of the pointer in screen coordinates. -*nSensitivity*
+*`nSensitivity`*\ [in] The distance, in pixels, away from the edge of a rectangle the pointer must be to enable docking. ### Return Value One of the following status values: -|AFX_CS_STATUS value|Meaning| +|`AFX_CS_STATUS` value|Meaning| |---------------------------|-------------| -|CS_NOTHING|The pointer is not over a dock site. The framework does not dock the pane.| -|CS_DOCK_IMMEDIATELY|The pointer is located over the dock site in immediate mode (the pane uses the DT_IMMEDIATE docking mode). The framework docks the pane immediately.| -|CS_DELAY_DOCK|The pointer is over a dock site that is another docking pane or is an edge of the main frame. The framework docks the pane after a delay. See the Remarks section for more information about this delay.| -|CS_DELAY_DOCK_TO_TAB|The pointer is located over a dock site that causes the pane to be docked in a tabbed window. This occurs when the pointer is located over the caption of another docking pane or over the tab area of a tabbed pane.| +|`CS_NOTHING`|The pointer isn't over a dock site. The framework doesn't dock the pane.| +|`CS_DOCK_IMMEDIATELY`|The pointer is located over the dock site in immediate mode (the pane uses the `DT_IMMEDIATE` docking mode). The framework docks the pane immediately.| +|`CS_DELAY_DOCK`|The pointer is over a dock site that is another docking pane or is an edge of the main frame. The framework docks the pane after a delay. See the Remarks section for more information about this delay.| +|`CS_DELAY_DOCK_TO_TAB`|The pointer is located over a dock site that causes the pane to be docked in a tabbed window. This occurs when the pointer is located over the caption of another docking pane or over the tab area of a tabbed pane.| ### Remarks The framework calls this method to handle docking of a floating pane. -For floating toolbars or docking panes that use the DT_IMMEDIATE docking mode, the framework delays the dock command to enable the user to move the window out of the client area of the parent frame before docking occurs. The length of the delay is measured in milliseconds and is controlled by the [CDockingManager::m_nTimeOutBeforeToolBarDock](../../mfc/reference/cdockingmanager-class.md#m_ntimeoutbeforetoolbardock) data member.. The default value of [CDockingManager::m_nTimeOutBeforeToolBarDock](../../mfc/reference/cdockingmanager-class.md#m_ntimeoutbeforetoolbardock) is 200. This behavior emulates the docking behavior of Microsoft Word 2007. +For floating toolbars or docking panes that use the `DT_IMMEDIATE` docking mode, the framework delays the dock command to enable the user to move the window out of the client area of the parent frame before docking occurs. The length of the delay is measured in milliseconds and is controlled by the [`CDockingManager::m_nTimeOutBeforeToolBarDock`](../../mfc/reference/cdockingmanager-class.md#m_ntimeoutbeforetoolbardock) data member. The default value of [`CDockingManager::m_nTimeOutBeforeToolBarDock`](../../mfc/reference/cdockingmanager-class.md#m_ntimeoutbeforetoolbardock) is 200. This behavior emulates the docking behavior of Microsoft Word 2007. -For delayed docking states (CS_DELAY_DOCK and CS_DELAY_DOCK_TO_TAB), the framework does not perform docking until the user releases the mouse button. If a pane uses the DT_STANDARD docking mode, the framework displays a rectangle at the projected docking location. If a pane uses the DT_SMART docking mode, the framework displays smart docking markers and semi-transparent rectangles at the projected docking location. To specify the docking mode for your pane, call the [CBasePane::SetDockingMode](../../mfc/reference/cbasepane-class.md#setdockingmode) method. For more information about smart docking, see [CDockingManager::GetSmartDockingParams](../../mfc/reference/cdockingmanager-class.md#getsmartdockingparams). +For delayed docking states (`CS_DELAY_DOCK` and `CS_DELAY_DOCK_TO_TAB`), the framework doesn't perform docking until the user releases the mouse button. If a pane uses the `DT_STANDARD` docking mode, the framework displays a rectangle at the projected docking location. If a pane uses the `DT_SMART` docking mode, the framework displays smart docking markers and semi-transparent rectangles at the projected docking location. To specify the docking mode for your pane, call the [`CBasePane::SetDockingMode`](../../mfc/reference/cbasepane-class.md#setdockingmode) method. For more information about smart docking, see [`CDockingManager::GetSmartDockingParams`](../../mfc/reference/cdockingmanager-class.md#getsmartdockingparams). -## CDockablePane::GetDragSensitivity +## `CDockablePane::GetDragSensitivity` Returns the drag sensitivity of a docking pane. @@ -889,11 +888,11 @@ static const CSize& GetDragSensitivity(); ### Return Value -A [CSize](../../atl-mfc-shared/reference/csize-class.md) object that contains the width and height, in pixels, of a rectangle centered on a drag point. The drag operation does not begin until the mouse pointer moves outside this rectangle. +A [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object that contains the width and height, in pixels, of a rectangle centered on a drag point. The drag operation doesn't begin until the mouse pointer moves outside this rectangle. -## CDockablePane::GetLastPercentInPaneContainer +## `CDockablePane::GetLastPercentInPaneContainer` -Retrieves the percentage of space that a pane occupies in its container ( [CPaneContainer Class](../../mfc/reference/cpanecontainer-class.md)). +Retrieves the percentage of space that a pane occupies in its container ( [`CPaneContainer` Class](../../mfc/reference/cpanecontainer-class.md)). ``` int GetLastPercentInPaneContainer() const; @@ -901,13 +900,13 @@ int GetLastPercentInPaneContainer() const; ### Return Value -An *int* that specifies the percentage of space that the pane occupies in its container. +An *`int`* that specifies the percentage of space that the pane occupies in its container. ### Remarks This method is used when the container adjusts its layout. -## CDockablePane::GetTabArea +## `CDockablePane::GetTabArea` Retrieves the tab area for the pane. @@ -919,17 +918,17 @@ virtual void GetTabArea( ### Parameters -*rectTabAreaTop*
+*`rectTabAreaTop`*\ [in] `GetTabArea` fills this variable with the tab area if tabs are located at the top of the pane. If tabs are located at the bottom of the pane, this variable is filled with an empty rectangle. -*rectTabAreaBottom*
+*`rectTabAreaBottom`*\ [in] `GetTabArea` fills this variable with the tab area if tabs are located at the bottom of the pane. If tabs are located at the top of the pane, this variable is filled with an empty rectangle. ### Remarks -This method is used only in classes that are derived from `CDockablePane` and have tabs. For more information, see [CTabbedPane::GetTabArea](../../mfc/reference/ctabbedpane-class.md#gettabarea) and [CMFCOutlookBar::GetTabArea](../../mfc/reference/cmfcoutlookbar-class.md#gettabarea). +This method is used only in classes that are derived from `CDockablePane` and have tabs. For more information, see [`CTabbedPane::GetTabArea`](../../mfc/reference/ctabbedpane-class.md#gettabarea) and [`CMFCOutlookBar::GetTabArea`](../../mfc/reference/cmfcoutlookbar-class.md#gettabarea). -## CDockablePane::GetTabbedPaneRTC +## `CDockablePane::GetTabbedPaneRTC` Returns the runtime class information about a tabbed window that is created when another pane docks to the current pane. @@ -943,11 +942,11 @@ The runtime class information for the dockable pane. ### Remarks -Call this method to retrieve the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the [CDockablePane::AttachToTabWnd](#attachtotabwnd) method to programmatically create a tabbed pane from two dockable panes. +Call this method to retrieve the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) method to programmatically create a tabbed pane from two dockable panes. -You can set the runtime class information by calling the [CDockablePane::SetTabbedPaneRTC](#settabbedpanertc) method. +You can set the runtime class information by calling the [`CDockablePane::SetTabbedPaneRTC`](#settabbedpanertc) method. -## CDockablePane::HasAutoHideMode +## `CDockablePane::HasAutoHideMode` Specifies whether a docking pane can be switched to autohide mode. @@ -957,13 +956,13 @@ virtual BOOL HasAutoHideMode() const; ### Return Value -TRUE if the dockable pane can be switched to autohide mode; otherwise, FALSE. +`TRUE` if the dockable pane can be switched to autohide mode; otherwise, `FALSE`. ### Remarks Override this method in a derived class to disable autohide mode for a specific dockable pane. -## CDockablePane::HitTest +## `CDockablePane::HitTest` Specifies the location in a pane where the user clicks a mouse. @@ -975,27 +974,27 @@ virtual int HitTest( ### Parameters -*point*
+*`point`*\ [in] Specifies the point to test. -*bDetectCaption*
-[in] TRUE if HTCAPTION should be returned if the point is on the pane's caption; otherwise, FALSE. +*`bDetectCaption`*\ +[in] `TRUE` if `HTCAPTION` should be returned if the point is on the pane's caption; otherwise, `FALSE`. ### Return Value One of the following values: -- HTNOWHERE if *point* is not in the dockable pane. +- `HTNOWHERE` if *`point`* isn't in the dockable pane. -- HTCLIENT if *point* is in the client area of the dockable pane. +- `HTCLIENT` if *`point`* is in the client area of the dockable pane. -- HTCAPTION if *point* is in the caption area of the dockable pane. +- `HTCAPTION` if *`point`* is in the caption area of the dockable pane. -- AFX_HTCLOSE if *point* is on the close button. +- `AFX_HTCLOSE` if *`point`* is on the close button. -- HTMAXBUTTON if *point* is on the pin button. +- `HTMAXBUTTON` if *`point`* is on the pin button. -## CDockablePane::IsAutohideAllEnabled +## `CDockablePane::IsAutohideAllEnabled` Indicates whether the docking pane and all other panes in the container can be switched to autohide mode. @@ -1005,15 +1004,15 @@ virtual BOOL IsAutohideAllEnabled() const; ### Return Value -TRUE if the dockable pane, and all other panes in the container, can be switched to autohide mode; otherwise, FALSE. +`TRUE` if the dockable pane, and all other panes in the container, can be switched to autohide mode; otherwise, `FALSE`. ### Remarks A user enables autohide mode by clicking the docking pin button while holding the **Ctrl** key -To enable or disable this behavior, call the [CDockablePane::EnableAutohideAll](#enableautohideall) method. +To enable or disable this behavior, call the [`CDockablePane::EnableAutohideAll`](#enableautohideall) method. -## CDockablePane::IsAutoHideMode +## `CDockablePane::IsAutoHideMode` Determines whether a pane is in autohide mode. @@ -1023,9 +1022,9 @@ virtual BOOL IsAutoHideMode() const; ### Return Value -TRUE if the dockable pane is in autohide mode; otherwise, FALSE. +`TRUE` if the dockable pane is in autohide mode; otherwise, `FALSE`. -## CDockablePane::IsDocked +## `CDockablePane::IsDocked` Determines whether the current pane is docked. @@ -1035,15 +1034,15 @@ virtual BOOL IsDocked() const; ### Return Value -TRUE if the dockable pane does not belong to a miniframe window or if it is floating in a miniframe window with another pane. FALSE if the pane is a child of a miniframe window and there are no other panes that belong to the miniframe window. +`TRUE` if the dockable pane doesn't belong to a miniframe window or if it's floating in a miniframe window with another pane. `FALSE` if the pane is a child of a miniframe window and there are no other panes that belong to the miniframe window. ### Remarks -To determine whether the pane is docked to the main frame window, call [CDockablePane::GetDefaultPaneDivider](#getdefaultpanedivider). If the method returns a non-NULL pointer, the pane is docked at the main frame window. +To determine whether the pane is docked to the main frame window, call [`CDockablePane::GetDefaultPaneDivider`](#getdefaultpanedivider). If the method returns a non-`NULL` pointer, the pane is docked at the main frame window. -## CDockablePane::IsHideInAutoHideMode +## `CDockablePane::IsHideInAutoHideMode` -Determines the behavior of a pane that is in autohide mode if it is shown (or hidden) by calling [CDockablePane::ShowPane](#showpane). +Determines the behavior of a pane that is in autohide mode if it's shown (or hidden) by calling [`CDockablePane::ShowPane`](#showpane). ``` virtual BOOL IsHideInAutoHideMode() const; @@ -1051,19 +1050,19 @@ virtual BOOL IsHideInAutoHideMode() const; ### Return Value -TRUE if the dockable pane should be hidden when in autohide mode; otherwise, FALSE. +`TRUE` if the dockable pane should be hidden when in autohide mode; otherwise, `FALSE`. ### Remarks -When a dockable pane is in autohide mode, it behaves differently when you call `ShowPane` to hide or show the pane. This behavior is controlled by the static member [CDockablePane::m_bHideInAutoHideMode](#m_bhideinautohidemode). If this member is TRUE, the dockable pane and its related autohide toolbar or autohide button is hidden or shown when you call `ShowPane`. Otherwise, the dockable pane is activated or deactivated, and its related autohide toolbar or autohide button is always visible. +When a dockable pane is in autohide mode, it behaves differently when you call `ShowPane` to hide or show the pane. This behavior is controlled by the static member [`CDockablePane::m_bHideInAutoHideMode`](#m_bhideinautohidemode). If this member is `TRUE`, the dockable pane and its related autohide toolbar or autohide button is hidden or shown when you call `ShowPane`. Otherwise, the dockable pane is activated or deactivated, and its related autohide toolbar or autohide button is always visible. Override this method in a derived class to change the default behavior for individual panes. -The default value for `m_bHideInAutoHideMode` is FALSE. +The default value for `m_bHideInAutoHideMode` is `FALSE`. -## CDockablePane::IsInFloatingMultiPaneFrameWnd +## `CDockablePane::IsInFloatingMultiPaneFrameWnd` -Specifies whether the pane is in a multi-pane frame window ( [CMultiPaneFrameWnd Class](../../mfc/reference/cmultipaneframewnd-class.md)). +Specifies whether the pane is in a multi-pane frame window ( [`CMultiPaneFrameWnd Class`](../../mfc/reference/cmultipaneframewnd-class.md)). ``` virtual BOOL IsInFloatingMultiPaneFrameWnd() const; @@ -1071,11 +1070,11 @@ virtual BOOL IsInFloatingMultiPaneFrameWnd() const; ### Return Value -TRUE if the pane is in a multi-pane frame window; otherwise, FALSE. +`TRUE` if the pane is in a multi-pane frame window; otherwise, `FALSE`. ### Remarks -## CDockablePane::IsResizable +## `CDockablePane::IsResizable` Specifies whether the pane is resizable. @@ -1085,15 +1084,15 @@ virtual BOOL IsResizable() const; ### Return Value -TRUE if the pane is resizable; otherwise, FALSE. +`TRUE` if the pane is resizable; otherwise, `FALSE`. ### Remarks -By default, dockable panes are resizable. To prevent resizing, override this method in a derived class and return FALSE. Note that a FALSE value leads to a failed **ASSERT** in [CPane::DockPane](../../mfc/reference/cpane-class.md#dockpane). Use [CDockingManager::AddPane](../../mfc/reference/cdockingmanager-class.md#addpane) instead to dock a pane within a parent frame. +By default, dockable panes are resizable. To prevent resizing, override this method in a derived class and return `FALSE`. Note that a `FALSE` value leads to a failed **`ASSERT`** in [`CPane::DockPane`](../../mfc/reference/cpane-class.md#dockpane). Use [`CDockingManager::AddPane`](../../mfc/reference/cdockingmanager-class.md#addpane) instead to dock a pane within a parent frame. -Panes that cannot be resized can neither float nor enter auto-hide mode and are always located at the outer edge of the parent frame. +Panes that can't be resized can neither float nor enter auto-hide mode and are always located at the outer edge of the parent frame. -## CDockablePane::IsTabLocationBottom +## `CDockablePane::IsTabLocationBottom` Specifies whether tabs are located at the top or bottom of the pane. @@ -1103,13 +1102,13 @@ virtual BOOL IsTabLocationBottom() const; ### Return Value -TRUE if tabs are located at the bottom of the pane; FALSE if tabs are located at the top of the pane. +`TRUE` if tabs are located at the bottom of the pane; `FALSE` if tabs are located at the top of the pane. ### Remarks -For more information, see [CTabbedPane::IsTabLocationBottom](../../mfc/reference/ctabbedpane-class.md#istablocationbottom). +For more information, see [`CTabbedPane::IsTabLocationBottom`](../../mfc/reference/ctabbedpane-class.md#istablocationbottom). -## CDockablePane::IsTracked +## `CDockablePane::IsTracked` Specifies whether a pane is being moved by the user. @@ -1119,9 +1118,9 @@ BOOL IsTracked() const; ### Return Value -TRUE if the pane is being moved; otherwise, FALSE. +`TRUE` if the pane is being moved; otherwise, `FALSE`. -## CDockablePane::IsVisible +## `CDockablePane::IsVisible` Determines whether the current pane is visible. @@ -1131,21 +1130,21 @@ virtual BOOL IsVisible() const; ### Return Value -TRUE if the dockable pane is visible; otherwise, FALSE. +`TRUE` if the dockable pane is visible; otherwise, `FALSE`. ### Remarks -Call this method to determine whether a dockable pane is visible. You can use this method instead of calling [CWnd::IsWindowVisible](../../mfc/reference/cwnd-class.md#iswindowvisible) or testing for the WS_VISIBLE style. The returned visibility state depends on whether autohide mode is enabled or disabled and on the value of the [CDockablePane::IsHideInAutoHideMode](#ishideinautohidemode) property. +Call this method to determine whether a dockable pane is visible. You can use this method instead of calling [`CWnd::IsWindowVisible`](../../mfc/reference/cwnd-class.md#iswindowvisible) or testing for the `WS_VISIBLE` style. The returned visibility state depends on whether autohide mode is enabled or disabled and on the value of the [`CDockablePane::IsHideInAutoHideMode`](#ishideinautohidemode) property. -If the dockable pane is in autohide mode and `IsHideInAutoHideMode` returns FALSE the visibility state is always FALSE. +If the dockable pane is in autohide mode and `IsHideInAutoHideMode` returns `FALSE` the visibility state is always `FALSE`. -If the dockable pane is in autohide mode and `IsHideInAutoHideMode` returns TRUE the visibility state depends on the visibility state of the related autohide toolbar. +If the dockable pane is in autohide mode and `IsHideInAutoHideMode` returns `TRUE` the visibility state depends on the visibility state of the related autohide toolbar. -If the dockable pane is not in autohide mode, the visibility state is determined by the [CBasePane::IsVisible](../../mfc/reference/cbasepane-class.md#isvisible) method. +If the dockable pane isn't in autohide mode, the visibility state is determined by the [`CBasePane::IsVisible`](../../mfc/reference/cbasepane-class.md#isvisible) method. -## ## CDockablePane::LoadState +## ## `CDockablePane::LoadState` -For internal use only. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation. +For internal use only. For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ``` virtual BOOL LoadState( @@ -1155,7 +1154,7 @@ virtual BOOL LoadState( ); ``` -## CDockablePane::m_bDisableAnimation +## `CDockablePane::m_bDisableAnimation` Specifies whether autohide animation of the dockable pane is disabled. @@ -1163,7 +1162,7 @@ Specifies whether autohide animation of the dockable pane is disabled. AFX_IMPORT_DATA static BOOL m_bDisableAnimation; ``` -## CDockablePane::m_bHideInAutoHideMode +## `CDockablePane::m_bHideInAutoHideMode` Determines the behavior of the pane when the pane is in autohide mode. @@ -1175,11 +1174,11 @@ AFX_IMPORT_DATA static BOOL m_bHideInAutoHideMode; This value affects all docking panes in the application. -If you set this member to TRUE, dockable panes are hidden or shown with their related autohide toolbars and buttons when you call [CDockablePane::ShowPane](#showpane). +If you set this member to `TRUE`, dockable panes are hidden or shown with their related autohide toolbars and buttons when you call [`CDockablePane::ShowPane`](#showpane). -If you set this member to FALSE, dockable panes are activated or deactivated when you call [CDockablePane::ShowPane](#showpane). +If you set this member to `FALSE`, dockable panes are activated or deactivated when you call [`CDockablePane::ShowPane`](#showpane). -## CDockablePane::m_nSlideSteps +## `CDockablePane::m_nSlideSteps` Specifies the animation speed of the pane when it is in autohide mode. @@ -1191,9 +1190,10 @@ AFX_IMPORT_DATA static int m_nSlideSteps; For a faster animation effect, decrease this value. For a slower animation effect, increase this value. -## CDockablePane::OnAfterChangeParent +## `CDockablePane::OnAfterChangeParent` + +For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. ``` virtual void OnAfterChangeParent(CWnd* pWndOldParent); @@ -1201,11 +1201,11 @@ virtual void OnAfterChangeParent(CWnd* pWndOldParent); ### Parameters -[in] *pWndOldParent*
+[in] *`pWndOldParent`* ### Remarks -## CDockablePane::OnAfterDockFromMiniFrame +## `CDockablePane::OnAfterDockFromMiniFrame` Called by the framework when a floating docking bar docks at a frame window. @@ -1217,7 +1217,7 @@ virtual void OnAfterDockFromMiniFrame(); By default, this method does nothing. -## CDockablePane::OnBeforeChangeParent +## `CDockablePane::OnBeforeChangeParent` The framework calls this method before it changes the parent of the pane. @@ -1229,19 +1229,19 @@ virtual void OnBeforeChangeParent( ### Parameters -*pWndNewParent*
+*`pWndNewParent`*\ [in] A pointer to the new parent window. -*bDelay*
-[in] BOOL that specifies whether to delay recalculation of the docking layout if the pane is undocked. For more information, see [CDockablePane::UndockPane](#undockpane). +*`bDelay`*\ +[in] BOOL that specifies whether to delay recalculation of the docking layout if the pane is undocked. For more information, see [`CDockablePane::UndockPane`](#undockpane). ### Remarks -If the pane is docked and the new parent does not allow docking, this method undocks the pane. +If the pane is docked and the new parent doesn't allow docking, this method undocks the pane. -If the pane is being converted to a tabbed document, this method stores its recent docking position. The framework uses the recent docking position to restore the position of the pane when it is converted back to a docked state. +If the pane is being converted to a tabbed document, this method stores its recent docking position. The framework uses the recent docking position to restore the position of the pane when it's converted back to a docked state. -## CDockablePane::OnBeforeFloat +## `CDockablePane::OnBeforeFloat` The framework calls this method before a pane transitions to a floating state. @@ -1253,23 +1253,23 @@ virtual BOOL OnBeforeFloat( ### Parameters -*rectFloat*
+*`rectFloat`*\ [in] Specifies the position and size of the pane when it is in a floating state. -*dockMethod*
-[in] Specifies the docking method. See [CPane::DockPane](../../mfc/reference/cpane-class.md#dockpane) for a list of possible values. +*`dockMethod`*\ +[in] Specifies the docking method. See [`CPane::DockPane`](../../mfc/reference/cpane-class.md#dockpane) for a list of possible values. ### Return Value -TRUE if the pane can be floated; otherwise, FALSE. +`TRUE` if the pane can be floated; otherwise, `FALSE`. ### Remarks This method is called by the framework when a pane is about to float. You can override this method in a derived class if you want to perform any processing before the pane floats. -## CDockablePane::OnPressButtons +## `CDockablePane::OnPressButtons` -Called when the user presses a caption button other than the AFX_HTCLOSE and AFX_HTMAXBUTTON buttons. +Called when the user presses a caption button other than the `AFX_HTCLOSE` and `AFX_HTMAXBUTTON` buttons. ``` virtual void OnPressButtons(UINT nHit); @@ -1277,14 +1277,14 @@ virtual void OnPressButtons(UINT nHit); ### Parameters -*nHit*
-[in] This parameter is not used. +*`nHit`*\ +[in] This parameter isn't used. ### Remarks If you add a custom button to the caption of a dockable pane, override this method to receive notifications when a user presses the button. -## CDockablePane::OnSlide +## `CDockablePane::OnSlide` Called by the framework to animate the pane when it is in autohide mode. @@ -1294,14 +1294,14 @@ virtual void OnSlide(BOOL bSlideOut); ### Parameters -*bSlideOut*
-[in] TRUE to show the pane; FALSE to hide the pane. +*`bSlideOut`*\ +[in] `TRUE` to show the pane; `FALSE` to hide the pane. ### Remarks Override this method in a derived class to implement custom autohide effects. -## CDockablePane::RemoveFromDefaultPaneDividier +## `CDockablePane::RemoveFromDefaultPaneDividier` The framework calls this method when a pane is being undocked. @@ -1311,9 +1311,9 @@ void RemoveFromDefaultPaneDividier(); ### Remarks -This method sets the default pane divider to NULL and removes the pane from its container. +This method sets the default pane divider to `NULL` and removes the pane from its container. -## CDockablePane::ReplacePane +## `CDockablePane::ReplacePane` Replaces the pane with a specified pane. @@ -1326,20 +1326,20 @@ BOOL ReplacePane( ### Parameters -*pBarToReplaceWith*
+*`pBarToReplaceWith`*\ [in] A pointer to a dockable pane. -*dockMethod*
+*`dockMethod`*\ [in] Not used. -*bRegisterWithFrame*
-[in] If TRUE, the new pane is registered with the docking manager of the parent of the old pane. The new pane is inserted at the index of the old pane in the list of panes that is maintained by the docking manager. +*`bRegisterWithFrame`*\ +[in] If `TRUE`, the new pane is registered with the docking manager of the parent of the old pane. The new pane is inserted at the index of the old pane in the list of panes that is maintained by the docking manager. ### Return Value -TRUE if the replacement is successful; otherwise, FALSE. +`TRUE` if the replacement is successful; otherwise, `FALSE`. -## CDockablePane::RestoreDefaultPaneDivider +## `CDockablePane::RestoreDefaultPaneDivider` When a pane is deserialized, the framework calls this method to restore the default pane divider. @@ -1351,7 +1351,7 @@ void RestoreDefaultPaneDivider(); The restored default pane divider replaces the current default pane divider, if it exists. -## CDockablePane::SetAutoHideMode +## `CDockablePane::SetAutoHideMode` Toggles the docking pane between visible and autohide mode. @@ -1365,29 +1365,29 @@ virtual CMFCAutoHideBar* SetAutoHideMode( ### Parameters -*bMode*
-[in] TRUE to enable autohide mode; FALSE to enable regular docking mode. +*`bMode`*\ +[in] `TRUE` to enable autohide mode; `FALSE` to enable regular docking mode. -*dwAlignment*
+*`dwAlignment`*\ [in] Specifies the alignment of the autohide pane to create. -*pCurrAutoHideBar*
-[in, out] A pointer to the current autohide toolbar. Can be NULL. +*`pCurrAutoHideBar`*\ +[in, out] A pointer to the current autohide toolbar. Can be `NULL`. -*bUseTimer*
+*`bUseTimer`*\ [in] Specifies whether to use the autohide effect when the user switches the pane to autohide mode or to hide the pane immediately. ### Return Value -The autohide toolbar that was created as a result of switching to autohide mode, or NULL. +The autohide toolbar that was created as a result of switching to autohide mode, or `NULL`. ### Remarks The framework calls this method when a user clicks the pin button to switch the dockable pane to autohide mode or to regular docking mode. -Call this method to switch a dockable pane to autohide mode programmatically. The pane must be docked to the main frame window ( [CDockablePane::GetDefaultPaneDivider](#getdefaultpanedivider) must return a valid pointer to the [CPaneDivider](../../mfc/reference/cpanedivider-class.md)). +Call this method to switch a dockable pane to autohide mode programmatically. The pane must be docked to the main frame window ( [`CDockablePane::GetDefaultPaneDivider`](#getdefaultpanedivider) must return a valid pointer to the [`CPaneDivider`](../../mfc/reference/cpanedivider-class.md)). -## CDockablePane::SetAutoHideParents +## `CDockablePane::SetAutoHideParents` Sets the auto-hide button and auto-hide toolbar for the pane. @@ -1399,13 +1399,13 @@ void SetAutoHideParents( ### Parameters -*pToolBar*
+*`pToolBar`*\ [in] Pointer to an auto-hide toolbar. -*pBtn*
+*`pBtn`*\ [in] Pointer to an auto-hide button. -## CDockablePane::SetLastPercentInPaneContainer +## `CDockablePane::SetLastPercentInPaneContainer` Sets the percentage of space that a pane occupies in its container. @@ -1415,14 +1415,14 @@ void SetLastPercentInPaneContainer(int n); ### Parameters -*n*
+*`n`*\ [in] An **`int`** that specifies the percentage of space that the pane occupies in its container. ### Remarks The framework adjusts the pane to use the new value when the layout is recalculated. -## CDockablePane::SetRestoredDefaultPaneDivider +## `CDockablePane::SetRestoredDefaultPaneDivider` Sets the restored default pane divider. @@ -1432,14 +1432,14 @@ void SetRestoredDefaultPaneDivider(HWND hRestoredSlider); ### Parameters -*hRestoredSlider*
+*`hRestoredSlider`*\ [in] A handle to a pane divider (slider). ### Remarks -A restored default pane divider is obtained when a pane is deserialized. For more information, see [CDockablePane::RestoreDefaultPaneDivider](#restoredefaultpanedivider). +A restored default pane divider is obtained when a pane is deserialized. For more information, see [`CDockablePane::RestoreDefaultPaneDivider`](#restoredefaultpanedivider). -## CDockablePane::SetTabbedPaneRTC +## `CDockablePane::SetTabbedPaneRTC` Sets the runtime class information for a tabbed window that is created when two panes dock together. @@ -1449,24 +1449,24 @@ void SetTabbedPaneRTC(CRuntimeClass* pRTC); ### Parameters -*pRTC*
+*`pRTC`*\ [in] The runtime class information for the tabbed pane. ### Remarks -Call this method to set the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the [CDockablePane::AttachToTabWnd](#attachtotabwnd) method to programmatically create a tabbed pane from two dockable panes. +Call this method to set the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the [`CDockablePane::AttachToTabWnd`](#attachtotabwnd) method to programmatically create a tabbed pane from two dockable panes. -The default runtime class is set according to the *dwTabbedStyle* parameter of [CDockablePane::Create](#create) and [CDockablePane::CreateEx](#createex). To customize the new tabbed panes, derive your class from one of the following classes: +The default runtime class is set according to the *`dwTabbedStyle`* parameter of [`CDockablePane::Create`](#create) and [`CDockablePane::CreateEx`](#createex). To customize the new tabbed panes, derive your class from one of the following classes: -- [CBaseTabbedPane Class](../../mfc/reference/cbasetabbedpane-class.md) +- [`CBaseTabbedPane` Class](../../mfc/reference/cbasetabbedpane-class.md) -- [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md) +- [`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md) -- [CMFCOutlookBar Class](../../mfc/reference/cmfcoutlookbar-class.md). +- [`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md). Then, call this method with the pointer to its runtime class information. -## CDockablePane::ShowPane +## `CDockablePane::ShowPane` Shows or hides a pane. @@ -1479,20 +1479,20 @@ virtual void ShowPane( ### Parameters -*bShow*
-[in] TRUE to show the pane; FALSE to hide the pane. +*`bShow`*\ +[in] `TRUE` to show the pane; `FALSE` to hide the pane. -*bDelay*
-[in] TRUE to delay adjusting the docking layout; FALSE to adjust the docking layout immediately. +*`bDelay`*\ +[in] `TRUE` to delay adjusting the docking layout; `FALSE` to adjust the docking layout immediately. -*bActivate*
-[in] TRUE to activate the pane when shown; otherwise, FALSE. +*`bActivate`*\ +[in] `TRUE` to activate the pane when shown; otherwise, `FALSE`. ### Remarks -Call this method instead of the [CWnd::ShowWindow](../../mfc/reference/cwnd-class.md#showwindow) when showing or hiding dockable panes. +Call this method instead of the [`CWnd::ShowWindow`](../../mfc/reference/cwnd-class.md#showwindow) when showing or hiding dockable panes. -## CDockablePane::Slide +## `CDockablePane::Slide` Animates a pane that is in autohide mode. @@ -1504,11 +1504,11 @@ virtual void Slide( ### Parameters -*bSlideOut*
-[in] TRUE to show the pane; FALSE to hide the pane. +*`bSlideOut`*\ +[in] `TRUE` to show the pane; `FALSE` to hide the pane. -*bUseTimer*
-[in] TRUE to show or hide the pane with the autohide effect; FALSE to show or hide the pane immediately. +*`bUseTimer`*\ +[in] `TRUE` to show or hide the pane with the autohide effect; `FALSE` to show or hide the pane immediately. ### Remarks @@ -1516,7 +1516,7 @@ The framework calls this method to animate a pane that is in autohide mode. This method uses the `CDockablePane::m_nSlideDefaultTimeOut` value to determine the time out for the slide effect. The default value for the time out is 1. If you customize the autohide algorithm, modify this member to change the time out. -## CDockablePane::ToggleAutoHide +## `CDockablePane::ToggleAutoHide` Toggles the pane between always visible and auto-hide mode. @@ -1526,9 +1526,9 @@ virtual void ToggleAutoHide(); ### Remarks -This method toggles auto-hide mode for the pane by calling [CDockablePane::SetAutoHideMode](#setautohidemode). +This method toggles auto-hide mode for the pane by calling [`CDockablePane::SetAutoHideMode`](#setautohidemode). -## CDockablePane::UndockPane +## `CDockablePane::UndockPane` Undocks a pane from either the main frame window or a miniframe window container. @@ -1538,19 +1538,19 @@ virtual void UndockPane(BOOL bDelay = FALSE); ### Parameters -*bDelay*
-[in] TRUE to delay calculating the docking layout; FALSE to recalculate the docking layout immediately. +*`bDelay`*\ +[in] `TRUE` to delay calculating the docking layout; `FALSE` to recalculate the docking layout immediately. ### Remarks Call this method to undock a pane from the main frame window or from a multi-miniframe window container (a pane that is floating in a single miniframe window with other panes). -You must undock a pane before you perform any external operation that is not performed by the [CDockingManager](../../mfc/reference/cdockingmanager-class.md). For example, you must undock a pane to move it programmatically from one location to another. +You must undock a pane before you perform any external operation that isn't performed by the [`CDockingManager`](../../mfc/reference/cdockingmanager-class.md). For example, you must undock a pane to move it programmatically from one location to another. -The framework automatically undocks panes before they are destroyed. +The framework automatically undocks panes before they're destroyed. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CPane Class](../../mfc/reference/cpane-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CPane` Class](../../mfc/reference/cpane-class.md) diff --git a/docs/mfc/reference/cdockablepaneadapter-class.md b/docs/mfc/reference/cdockablepaneadapter-class.md index 962eeab2d0..4c483e1e87 100644 --- a/docs/mfc/reference/cdockablepaneadapter-class.md +++ b/docs/mfc/reference/cdockablepaneadapter-class.md @@ -37,11 +37,11 @@ If you want to customize the `CDockablePaneAdapter` behavior, just derive a new [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CPane](../../mfc/reference/cpane-class.md)\ -                └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ -                    └ [CDockablePaneAdapter](../../mfc/reference/cdockablepaneadapter-class.md) + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CPane](../../mfc/reference/cpane-class.md)\ +    └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ +     └ [CDockablePaneAdapter](../../mfc/reference/cdockablepaneadapter-class.md) ## Requirements diff --git a/docs/mfc/reference/cdockingmanager-class.md b/docs/mfc/reference/cdockingmanager-class.md index fb2b4cc0e0..e3fe1e204b 100644 --- a/docs/mfc/reference/cdockingmanager-class.md +++ b/docs/mfc/reference/cdockingmanager-class.md @@ -29,7 +29,7 @@ class CDockingManager : public CObject |[CDockingManager::AdjustDockingLayout](#adjustdockinglayout)|Recalculates and adjusts the layout of all panes in a frame window.| |[CDockingManager::AdjustPaneFrames](#adjustpaneframes)|Causes the WM_NCCALCSIZE message to be sent to all panes and `CPaneFrameWnd` windows.| |[CDockingManager::AdjustRectToClientArea](#adjustrecttoclientarea)|Adjusts the alignment of a rectangle.| -|[CDockingManager::AlignAutoHidePane](#alignautohidepane)|Resizes a docking pane in autohide mode so that it takes the full width or height of the frame’s client area surrounded by dock sites.| +|[CDockingManager::AlignAutoHidePane](#alignautohidepane)|Resizes a docking pane in autohide mode so that it takes the full width or height of the frame's client area surrounded by dock sites.| |[CDockingManager::AutoHidePane](#autohidepane)|Creates an autohide toolbar.| |[CDockingManager::BringBarsToTop](#bringbarstotop)|Brings the docked bars that have the specified alignment to the top.| |[CDockingManager::BuildPanesMenu](#buildpanesmenu)|Adds names of docking panes and toolbars to a menu.| @@ -292,7 +292,7 @@ The *dwAlignment* parameter can have one of the following values: ## CDockingManager::AlignAutoHidePane -Resizes a docking pane in autohide mode so that it takes the full width or height of the frame’s client area surrounded by dock sites. +Resizes a docking pane in autohide mode so that it takes the full width or height of the frame's client area surrounded by dock sites. ```cpp void AlignAutoHidePane( diff --git a/docs/mfc/reference/cdocksite-class.md b/docs/mfc/reference/cdocksite-class.md index 49d36e675c..b8b1036236 100644 --- a/docs/mfc/reference/cdocksite-class.md +++ b/docs/mfc/reference/cdocksite-class.md @@ -81,9 +81,9 @@ The following example demonstrates how to create an object of the `CDockSite` cl [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CDockSite](../../mfc/reference/cdocksite-class.md) + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CDockSite](../../mfc/reference/cdocksite-class.md) ## Requirements diff --git a/docs/mfc/reference/cdockstate-class.md b/docs/mfc/reference/cdockstate-class.md index 93d04a208a..573f914f69 100644 --- a/docs/mfc/reference/cdockstate-class.md +++ b/docs/mfc/reference/cdockstate-class.md @@ -92,7 +92,7 @@ void LoadState(LPCTSTR lpszProfileName); ### Parameters *lpszProfileName*
-Points to a null-teminated string that specifies the name of a section in the initialization file or a key in the Windows registry where state information is stored. +Points to a null-terminated string that specifies the name of a section in the initialization file or a key in the Windows registry where state information is stored. ### Remarks diff --git a/docs/mfc/reference/cdocobjectserver-class.md b/docs/mfc/reference/cdocobjectserver-class.md index 70f2fed087..b99f2715ac 100644 --- a/docs/mfc/reference/cdocobjectserver-class.md +++ b/docs/mfc/reference/cdocobjectserver-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CDocObjectServer Class" title: "CDocObjectServer Class" -ms.date: "09/12/2018" +description: "Learn more about: CDocObjectServer Class" +ms.date: 09/12/2018 f1_keywords: ["CDocObjectServer", "AFXDOCOB/CDocObjectServer", "AFXDOCOB/CDocObjectServer::CDocObjectServer", "AFXDOCOB/CDocObjectServer::ActivateDocObject", "AFXDOCOB/CDocObjectServer::OnActivateView", "AFXDOCOB/CDocObjectServer::OnApplyViewState", "AFXDOCOB/CDocObjectServer::OnSaveViewState"] helpviewer_keywords: ["CDocObjectServer [MFC], CDocObjectServer", "CDocObjectServer [MFC], ActivateDocObject", "CDocObjectServer [MFC], OnActivateView", "CDocObjectServer [MFC], OnApplyViewState", "CDocObjectServer [MFC], OnSaveViewState"] -ms.assetid: 18cd0dff-0616-4472-b8d9-66c081bc383a --- # CDocObjectServer Class @@ -94,7 +93,7 @@ A pointer to the `IOleDocumentSite` interface implemented by the container. ### Remarks -When a DocObject is active, the client site OLE interface ( `IOleDocumentSite`) is what allows the DocObject server to communicate with its client (the container). When a DocObject server is activated, it first checks that the container implements the `IOleDocumentSite` interface. If so, [COleServerDoc::GetDocObjectServer](../../mfc/reference/coleserverdoc-class.md#getdocobjectserver) is called to see if the container supports DocObjects. By default, `GetDocObjectServer` returns NULL. You must override `COleServerDoc::GetDocObjectServer` to construct a new `CDocObjectServer` object or a derived object of your own, with pointers to the `COleServerDoc` container and its `IOleDocumentSite` interface as arguments to the constructor. +When a DocObject is active, the client site OLE interface (`IOleDocumentSite`) is what allows the DocObject server to communicate with its client (the container). When a DocObject server is activated, it first checks that the container implements the `IOleDocumentSite` interface. If so, [COleServerDoc::GetDocObjectServer](../../mfc/reference/coleserverdoc-class.md#getdocobjectserver) is called to see if the container supports DocObjects. By default, `GetDocObjectServer` returns NULL. You must override `COleServerDoc::GetDocObjectServer` to construct a new `CDocObjectServer` object or a derived object of your own, with pointers to the `COleServerDoc` container and its `IOleDocumentSite` interface as arguments to the constructor. ## CDocObjectServer::OnActivateView diff --git a/docs/mfc/reference/cdoctemplate-class.md b/docs/mfc/reference/cdoctemplate-class.md index ff92e64315..f82442239b 100644 --- a/docs/mfc/reference/cdoctemplate-class.md +++ b/docs/mfc/reference/cdoctemplate-class.md @@ -4,9 +4,8 @@ title: "CDocTemplate Class" ms.date: "11/04/2016" f1_keywords: ["CDocTemplate", "AFXWIN/CDocTemplate", "AFXWIN/CDocTemplate::CDocTemplate", "AFXWIN/CDocTemplate::AddDocument", "AFXWIN/CDocTemplate::CloseAllDocuments", "AFXWIN/CDocTemplate::CreateNewDocument", "AFXWIN/CDocTemplate::CreateNewFrame", "AFXWIN/CDocTemplate::CreateOleFrame", "AFXWIN/CDocTemplate::CreatePreviewFrame", "AFXWIN/CDocTemplate::GetDocString", "AFXWIN/CDocTemplate::GetFirstDocPosition", "AFXWIN/CDocTemplate::GetNextDoc", "AFXWIN/CDocTemplate::InitialUpdateFrame", "AFXWIN/CDocTemplate::LoadTemplate", "AFXWIN/CDocTemplate::MatchDocType", "AFXWIN/CDocTemplate::OpenDocumentFile", "AFXWIN/CDocTemplate::RemoveDocument", "AFXWIN/CDocTemplate::SaveAllModified", "AFXWIN/CDocTemplate::SetContainerInfo", "AFXWIN/CDocTemplate::SetDefaultTitle", "AFXWIN/CDocTemplate::SetPreviewInfo", "AFXWIN/CDocTemplate::SetServerInfo"] helpviewer_keywords: ["CDocTemplate [MFC], CDocTemplate", "CDocTemplate [MFC], AddDocument", "CDocTemplate [MFC], CloseAllDocuments", "CDocTemplate [MFC], CreateNewDocument", "CDocTemplate [MFC], CreateNewFrame", "CDocTemplate [MFC], CreateOleFrame", "CDocTemplate [MFC], CreatePreviewFrame", "CDocTemplate [MFC], GetDocString", "CDocTemplate [MFC], GetFirstDocPosition", "CDocTemplate [MFC], GetNextDoc", "CDocTemplate [MFC], InitialUpdateFrame", "CDocTemplate [MFC], LoadTemplate", "CDocTemplate [MFC], MatchDocType", "CDocTemplate [MFC], OpenDocumentFile", "CDocTemplate [MFC], RemoveDocument", "CDocTemplate [MFC], SaveAllModified", "CDocTemplate [MFC], SetContainerInfo", "CDocTemplate [MFC], SetDefaultTitle", "CDocTemplate [MFC], SetPreviewInfo", "CDocTemplate [MFC], SetServerInfo"] -ms.assetid: 14b41a1f-bf9d-4eac-b6a8-4c54ffcc77f6 --- -# CDocTemplate Class +# `CDocTemplate` Class An abstract base class that defines the basic functionality for document templates. @@ -22,31 +21,31 @@ class CDocTemplate : public CCmdTarget |Name|Description| |----------|-----------------| -|[CDocTemplate::CDocTemplate](#cdoctemplate)|Constructs a `CDocTemplate` object.| +|[`CDocTemplate::CDocTemplate`](#cdoctemplate)|Constructs a `CDocTemplate` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CDocTemplate::AddDocument](#adddocument)|Adds a document to a template.| -|[CDocTemplate::CloseAllDocuments](#closealldocuments)|Closes all documents associated with this template.| -|[CDocTemplate::CreateNewDocument](#createnewdocument)|Creates a new document.| -|[CDocTemplate::CreateNewFrame](#createnewframe)|Creates a new frame window containing a document and view.| -|[CDocTemplate::CreateOleFrame](#createoleframe)|Creates an OLE-enabled frame window.| -|[CDocTemplate::CreatePreviewFrame](#createpreviewframe)|Creates a child frame used for Rich Preview.| -|[CDocTemplate::GetDocString](#getdocstring)|Retrieves a string associated with the document type.| -|[CDocTemplate::GetFirstDocPosition](#getfirstdocposition)|Retrieves the position of the first document associated with this template.| -|[CDocTemplate::GetNextDoc](#getnextdoc)|Retrieves a document and the position of the next one.| -|[CDocTemplate::InitialUpdateFrame](#initialupdateframe)|Initializes the frame window, and optionally makes it visible.| -|[CDocTemplate::LoadTemplate](#loadtemplate)|Loads the resources for a given `CDocTemplate` or derived class.| -|[CDocTemplate::MatchDocType](#matchdoctype)|Determines the degree of confidence in the match between a document type and this template.| -|[CDocTemplate::OpenDocumentFile](#opendocumentfile)|Opens a file specified by a pathname.| -|[CDocTemplate::RemoveDocument](#removedocument)|Removes a document from a template.| -|[CDocTemplate::SaveAllModified](#saveallmodified)|Saves all documents associated with this template which have been modified.| -|[CDocTemplate::SetContainerInfo](#setcontainerinfo)|Determines the resources for OLE containers when editing an in-place OLE item.| -|[CDocTemplate::SetDefaultTitle](#setdefaulttitle)|Displays the default title in the document window's title bar.| -|[CDocTemplate::SetPreviewInfo](#setpreviewinfo)|Setups out of process preview handler.| -|[CDocTemplate::SetServerInfo](#setserverinfo)|Determines the resources and classes when the server document is embedded or edited in-place.| +|[`CDocTemplate::AddDocument`](#adddocument)|Adds a document to a template.| +|[`CDocTemplate::CloseAllDocuments`](#closealldocuments)|Closes all documents associated with this template.| +|[`CDocTemplate::CreateNewDocument`](#createnewdocument)|Creates a new document.| +|[`CDocTemplate::CreateNewFrame`](#createnewframe)|Creates a new frame window containing a document and view.| +|[`CDocTemplate::CreateOleFrame`](#createoleframe)|Creates an OLE-enabled frame window.| +|[`CDocTemplate::CreatePreviewFrame`](#createpreviewframe)|Creates a child frame used for Rich Preview.| +|[`CDocTemplate::GetDocString`](#getdocstring)|Retrieves a string associated with the document type.| +|[`CDocTemplate::GetFirstDocPosition`](#getfirstdocposition)|Retrieves the position of the first document associated with this template.| +|[`CDocTemplate::GetNextDoc`](#getnextdoc)|Retrieves a document and the position of the next one.| +|[`CDocTemplate::InitialUpdateFrame`](#initialupdateframe)|Initializes the frame window, and optionally makes it visible.| +|[`CDocTemplate::LoadTemplate`](#loadtemplate)|Loads the resources for a given `CDocTemplate` or derived class.| +|[`CDocTemplate::MatchDocType`](#matchdoctype)|Determines the degree of confidence in the match between a document type and this template.| +|[`CDocTemplate::OpenDocumentFile`](#opendocumentfile)|Opens a file specified by a pathname.| +|[`CDocTemplate::RemoveDocument`](#removedocument)|Removes a document from a template.| +|[`CDocTemplate::SaveAllModified`](#saveallmodified)|Saves all documents associated with this template, which have been modified.| +|[`CDocTemplate::SetContainerInfo`](#setcontainerinfo)|Determines the resources for OLE containers when editing an in-place OLE item.| +|[`CDocTemplate::SetDefaultTitle`](#setdefaulttitle)|Displays the default title in the document window's title bar.| +|[`CDocTemplate::SetPreviewInfo`](#setpreviewinfo)|Setups out of process preview handler.| +|[`CDocTemplate::SetServerInfo`](#setserverinfo)|Determines the resources and classes when the server document is embedded or edited in-place.| ## Remarks @@ -66,7 +65,7 @@ The document template contains the ID of the resources used with the document ty If your application is an OLE container and/or server, the document template also defines the ID of the menu used during in-place activation. If your application is an OLE server, the document template defines the ID of the toolbar and menu used during in-place activation. You specify these additional OLE resources by calling `SetContainerInfo` and `SetServerInfo`. -Because `CDocTemplate` is an abstract class, you cannot use the class directly. A typical application uses one of the two `CDocTemplate`-derived classes provided by the Microsoft Foundation Class Library: `CSingleDocTemplate`, which implements SDI, and `CMultiDocTemplate`, which implements MDI. See those classes for more information on using document templates. +Because `CDocTemplate` is an abstract class, you can't use the class directly. A typical application uses one of the two `CDocTemplate`-derived classes provided by the Microsoft Foundation Class Library: `CSingleDocTemplate`, which implements SDI, and `CMultiDocTemplate`, which implements MDI. See those classes for more information on using document templates. If your application requires a user-interface paradigm that is fundamentally different from SDI or MDI, you can derive your own class from `CDocTemplate`. @@ -74,17 +73,17 @@ For more information on `CDocTemplate`, see [Document Templates and the Document ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) `CDocTemplate` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CDocTemplate::AddDocument +## `CDocTemplate::AddDocument` Use this function to add a document to a template. @@ -94,14 +93,14 @@ virtual void AddDocument(CDocument* pDoc); ### Parameters -*pDoc*
+*`pDoc`*\ A pointer to the document to be added. ### Remarks -The derived classes [CMultiDocTemplate](../../mfc/reference/cmultidoctemplate-class.md) and [CSingleDocTemplate](../../mfc/reference/csingledoctemplate-class.md) override this function. If you derive your own document-template class from `CDocTemplate`, your derived class must override this function. +The derived classes [`CMultiDocTemplate`](../../mfc/reference/cmultidoctemplate-class.md) and [`CSingleDocTemplate`](../../mfc/reference/csingledoctemplate-class.md) override this function. If you derive your own document-template class from `CDocTemplate`, your derived class must override this function. -## CDocTemplate::CDocTemplate +## `CDocTemplate::CDocTemplate` Constructs a `CDocTemplate` object. @@ -115,10 +114,10 @@ CDocTemplate ( ### Parameters -*nIDResource*
+*`nIDResource`*\ Specifies the ID of the resources used with the document type. This may include menu, icon, accelerator table, and string resources. -The string resource consists of up to seven substrings separated by the '\n' character (the '\n' character is needed as a place holder if a substring is not included; however, trailing '\n' characters are not necessary); these substrings describe the document type. For information on the substrings, see [GetDocString](#getdocstring). This string resource is found in the application's resource file. For example: +The string resource consists of up to seven substrings separated by the `\n` character (the `\n` character is needed as a place holder if a substring isn't included; however, trailing `\n` characters aren't necessary); these substrings describe the document type. For information on the substrings, see [`GetDocString`](#getdocstring). This string resource is found in the application's resource file. For example: ```RC // MYCALC.RC @@ -128,22 +127,22 @@ BEGIN END ``` -Note that the string begins with a '\n' character; this is because the first substring is not used for MDI applications and so is not included. You can edit this string using the string editor; the entire string appears as a single entry in the String Editor, not as seven separate entries. +Note that the string begins with a `\n` character; this is because the first substring isn't used for MDI applications and so isn't included. You can edit this string using the string editor; the entire string appears as a single entry in the String Editor, not as seven separate entries. -*pDocClass*
+*`pDocClass`*\ Points to the `CRuntimeClass` object of the document class. This class is a `CDocument`-derived class you define to represent your documents. -*pFrameClass*
+*`pFrameClass`*\ Points to the `CRuntimeClass` object of the frame window class. This class can be a `CFrameWnd`-derived class, or it can be `CFrameWnd` itself if you want default behavior for your main frame window. -*pViewClass*
+*`pViewClass`*\ Points to the `CRuntimeClass` object of the view class. This class is a `CView`-derived class you define to display your documents. ### Remarks -Use this member function to construct a `CDocTemplate` object. Dynamically allocate a `CDocTemplate` object and pass it to [CWinApp::AddDocTemplate](../../mfc/reference/cwinapp-class.md#adddoctemplate) from the `InitInstance` member function of your application class. +Use this member function to construct a `CDocTemplate` object. Dynamically allocate a `CDocTemplate` object and pass it to [`CWinApp::AddDocTemplate`](../../mfc/reference/cwinapp-class.md#adddoctemplate) from the `InitInstance` member function of your application class. -## CDocTemplate::CloseAllDocuments +## `CDocTemplate::CloseAllDocuments` Call this member function to close all open documents. @@ -153,16 +152,16 @@ virtual void CloseAllDocuments(BOOL bEndSession); ### Parameters -*bEndSession*
+*`bEndSession`*\ Not used. ### Remarks -This member function is typically used as part of the File Exit command. The default implementation of this function calls the [CDocument::DeleteContents](../../mfc/reference/cdocument-class.md#deletecontents) member function to delete the document's data and then closes the frame windows for all the views attached to the document. +This member function is typically used as part of the File Exit command. The default implementation of this function calls the [`CDocument::DeleteContents`](../../mfc/reference/cdocument-class.md#deletecontents) member function to delete the document's data and then closes the frame windows for all the views attached to the document. Override this function if you want to require the user to perform special cleanup processing before the document is closed. For example, if the document represents a record in a database, you may want to override this function to close the database. -## CDocTemplate::CreateNewDocument +## `CDocTemplate::CreateNewDocument` Call this member function to create a new document of the type associated with this document template. @@ -172,9 +171,9 @@ virtual CDocument* CreateNewDocument(); ### Return Value -A pointer to the newly created document, or NULL if an error occurs. +A pointer to the newly created document, or `NULL` if an error occurs. -## CDocTemplate::CreateNewFrame +## `CDocTemplate::CreateNewFrame` Creates a new frame window containing a document and view. @@ -186,23 +185,23 @@ virtual CFrameWnd* CreateNewFrame( ### Parameters -*pDoc*
-The document to which the new frame window should refer. Can be NULL. +*`pDoc`*\ +The document to which the new frame window should refer. Can be `NULL`. -*pOther*
-The frame window on which the new frame window is to be based. Can be NULL. +*`pOther`*\ +The frame window on which the new frame window is to be based. Can be `NULL`. ### Return Value -A pointer to the newly created frame window, or NULL if an error occurs. +A pointer to the newly created frame window, or `NULL` if an error occurs. ### Remarks -`CreateNewFrame` uses the `CRuntimeClass` objects passed to the constructor to create a new frame window with a view and document attached. If the *pDoc* parameter is NULL, the framework outputs a TRACE message. +`CreateNewFrame` uses the `CRuntimeClass` objects passed to the constructor to create a new frame window with a view and document attached. If the *`pDoc`* parameter is `NULL`, the framework outputs a `TRACE` message. -The *pOther* parameter is used to implement the Window New command. It provides a frame window on which to model the new frame window. The new frame window is usually created invisible. Call this function to create frame windows outside the standard framework implementation of File New and File Open. +The *`pOther`* parameter is used to implement the Window New command. It provides a frame window on which to model the new frame window. The new frame window is usually created invisible. Call this function to create frame windows outside the standard framework implementation of **File New** and **File Open**. -## CDocTemplate::CreateOleFrame +## `CDocTemplate::CreateOleFrame` Creates an OLE frame window. @@ -215,24 +214,24 @@ CFrameWnd* CreateOleFrame( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ A pointer to the frame's parent window. -*pDoc*
+*`pDoc`*\ A pointer to the document to which the new OLE frame window should refer. -*bCreateView*
+*`bCreateView`*\ Determines whether a view is created along with the frame. ### Return Value -A pointer to a frame window if successful; otherwise NULL. +A pointer to a frame window if successful; otherwise `NULL`. ### Remarks -If *bCreateView* is zero, an empty frame is created. +If *`bCreateView`* is zero, an empty frame is created. -## CDocTemplate::GetDocString +## `CDocTemplate::GetDocString` Retrieves a string associated with the document type. @@ -244,23 +243,23 @@ virtual BOOL GetDocString( ### Parameters -*rString*
+*`rString`*\ A reference to a `CString` object that will contain the string when the function returns. -*index*
+*`index`*\ An index of the substring being retrieved from the string that describes the document type. This parameter can have one of the following values: - `CDocTemplate::windowTitle` Name that appears in the application window's title bar (for example, "Microsoft Excel"). Present only in the document template for SDI applications. -- `CDocTemplate::docName` Root for the default document name (for example, "Sheet"). This root, plus a number, is used for the default name of a new document of this type whenever the user chooses the New command from the File menu (for example, "Sheet1" or "Sheet2"). If not specified, "Untitled" is used as the default. +- `CDocTemplate::docName` Root for the default document name (for example, "Sheet"). This root, plus a number, is used for the default name of a new document of this type whenever the user chooses the **New** command from the **File** menu (for example, "Sheet1" or "Sheet2"). If not specified, "Untitled" is used as the default. -- `CDocTemplate::fileNewName` Name of this document type. If the application supports more than one type of document, this string is displayed in the File New dialog box (for example, "Worksheet"). If not specified, the document type is inaccessible using the File New command. +- `CDocTemplate::fileNewName` Name of this document type. If the application supports more than one type of document, this string is displayed in the **File New** dialog box (for example, "Worksheet"). If not specified, the document type is inaccessible using the **File New** command. -- `CDocTemplate::filterName` Description of the document type and a wildcard filter matching documents of this type. This string is displayed in the List Files Of Type drop-down list in the File Open dialog box (for example, "Worksheets (*.xls)"). If not specified, the document type is inaccessible using the File Open command. +- `CDocTemplate::filterName` Description of the document type and a wildcard filter matching documents of this type. This string is displayed in the **List Files Of Type** drop-down list in the **File Open** dialog box (for example, "Worksheets (*.xls)"). If not specified, the document type is inaccessible using the **File Open** command. -- `CDocTemplate::filterExt` Extension for documents of this type (for example, ".xls"). If not specified, the document type is inaccessible using the File Open command. +- `CDocTemplate::filterExt` Extension for documents of this type (for example, ".xls"). If not specified, the document type is inaccessible using the **File Open** command. -- `CDocTemplate::regFileTypeId` Identifier for the document type to be stored in the registration database maintained by Windows. This string is for internal use only (for example, "ExcelWorksheet"). If not specified, the document type cannot be registered with the Windows File Manager. +- `CDocTemplate::regFileTypeId` Identifier for the document type to be stored in the registration database maintained by Windows. This string is for internal use only (for example, "ExcelWorksheet"). If not specified, the document type can't be registered with the Windows File Manager. - `CDocTemplate::regFileTypeName` Name of the document type to be stored in the registration database. This string may be displayed in dialog boxes of applications that access the registration database (for example, "Microsoft Excel Worksheet"). @@ -270,11 +269,11 @@ Nonzero if the specified substring was found; otherwise 0. ### Remarks -Call this function to retrieve a specific substring describing the document type. The string containing these substrings is stored in the document template and is derived from a string in the resource file for the application. The framework calls this function to get the strings it needs for the application's user interface. If you have specified a filename extension for your application's documents, the framework also calls this function when adding an entry to the Windows registration database; this allows documents to be opened from the Windows File Manager. +Call this function to retrieve a specific substring describing the document type. The string containing these substrings is stored in the document template and is derived from a string in the resource file for the application. The framework calls this function to get the strings it needs for the application's user interface. If you've specified a filename extension for your application's documents, the framework also calls this function when adding an entry to the Windows registration database; this allows documents to be opened from the Windows File Manager. -Call this function only if you are deriving your own class from `CDocTemplate`. +Call this function only if you're deriving your own class from `CDocTemplate`. -## CDocTemplate::GetFirstDocPosition +## `CDocTemplate::GetFirstDocPosition` Retrieves the position of the first document associated with this template. @@ -284,17 +283,17 @@ virtual POSITION GetFirstDocPosition() const = 0; ### Return Value -A POSITION value that can be used to iterate through the list of documents associated with this document template; or NULL if the list is empty. +A `POSITION` value that can be used to iterate through the list of documents associated with this document template; or `NULL` if the list is empty. ### Remarks -Use this function to get the position of the first document in the list of documents associated with this template. Use the POSITION value as an argument to [CDocTemplate::GetNextDoc](#getnextdoc) to iterate through the list of documents associated with the template. +Use this function to get the position of the first document in the list of documents associated with this template. Use the `POSITION` value as an argument to [`CDocTemplate::GetNextDoc`](#getnextdoc) to iterate through the list of documents associated with the template. -[CSingleDocTemplate](../../mfc/reference/csingledoctemplate-class.md) and [CMultiDocTemplate](../../mfc/reference/cmultidoctemplate-class.md) both override this pure virtual function. Any class you derive from `CDocTemplate` must also override this function. +[`CSingleDocTemplate`](../../mfc/reference/csingledoctemplate-class.md) and [`CMultiDocTemplate`](../../mfc/reference/cmultidoctemplate-class.md) both override this pure virtual function. Any class you derive from `CDocTemplate` must also override this function. -## CDocTemplate::GetNextDoc +## `CDocTemplate::GetNextDoc` -Retrieves the list element identified by *rPos*, then sets *rPos* to the POSITION value of the next entry in the list. +Retrieves the list element identified by *`rPos`*, then sets *`rPos`* to the `POSITION` value of the next entry in the list. ``` virtual CDocument* GetNextDoc(POSITION& rPos) const = 0; @@ -306,18 +305,18 @@ A pointer to the next document in the list of documents associated with this tem ### Parameters -*rPos*
-A reference to a POSITION value returned by a previous call to [GetFirstDocPosition](#getfirstdocposition) or `GetNextDoc`. +*`rPos`*\ +A reference to a `POSITION` value returned by a previous call to [`GetFirstDocPosition`](#getfirstdocposition) or `GetNextDoc`. ### Remarks -If the retrieved element is the last in the list, then the new value of *rPos* is set to NULL. +If the retrieved element is the last in the list, then the new value of *`rPos`* is set to `NULL`. -You can use `GetNextDoc` in a forward iteration loop if you establish the initial position with a call to [GetFirstDocPosition](#getfirstdocposition). +You can use `GetNextDoc` in a forward iteration loop if you establish the initial position with a call to [`GetFirstDocPosition`](#getfirstdocposition). -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. -## CDocTemplate::InitialUpdateFrame +## `CDocTemplate::InitialUpdateFrame` Initializes the frame window, and optionally makes it visible. @@ -330,22 +329,22 @@ virtual void InitialUpdateFrame( ### Parameters -*pFrame*
+*`pFrame`*\ The frame window that needs the initial update. -*pDoc*
-The document to which the frame is associated. Can be NULL. +*`pDoc`*\ +The document to which the frame is associated. Can be `NULL`. -*bMakeVisible*
+*`bMakeVisible`*\ Indicates whether the frame should become visible and active. ### Remarks -Call `IntitialUpdateFrame` after creating a new frame with `CreateNewFrame`. Calling this function causes the views in that frame window to receive their `OnInitialUpdate` calls. Also, if there was not previously an active view, the primary view of the frame window is made active; the primary view is a view with a child ID of AFX_IDW_PANE_FIRST. Finally, the frame window is made visible if *bMakeVisible* is non-zero. If *bMakeVisible* is zero, the current focus and visible state of the frame window will remain unchanged. +Call `IntitialUpdateFrame` after creating a new frame with `CreateNewFrame`. Calling this function causes the views in that frame window to receive their `OnInitialUpdate` calls. Also, if there wasn't previously an active view, the primary view of the frame window is made active; the primary view is a view with a child ID of `AFX_IDW_PANE_FIRST`. Finally, the frame window is made visible if *`bMakeVisible`* is non-zero. If *`bMakeVisible`* is zero, the current focus and visible state of the frame window will remain unchanged. -It is not necessary to call this function when using the framework's implementation of File New and File Open. +It isn't necessary to call this function when using the framework's implementation of **File New** and **File Open**. -## CDocTemplate::LoadTemplate +## `CDocTemplate::LoadTemplate` Loads the resources for a given `CDocTemplate` or derived class. @@ -355,9 +354,9 @@ virtual void LoadTemplate(); ### Remarks -This member function is called by the framework to load the resources for a given `CDocTemplate` or derived class. Normally it is called during construction, except when the template is being constructed globally. In that case, the call to `LoadTemplate` is delayed until [CWinApp::AddDocTemplate](../../mfc/reference/cwinapp-class.md#adddoctemplate) is called. +This member function is called by the framework to load the resources for a given `CDocTemplate` or derived class. Normally it's called during construction, except when the template is being constructed globally. In that case, the call to `LoadTemplate` is delayed until [`CWinApp::AddDocTemplate`](../../mfc/reference/cwinapp-class.md#adddoctemplate) is called. -## CDocTemplate::MatchDocType +## `CDocTemplate::MatchDocType` Determines the degree of confidence in the match between a document type and this template. @@ -369,15 +368,15 @@ virtual Confidence MatchDocType( ### Parameters -*lpszPathName*
+*`lpszPathName`*\ Pathname of the file whose type is to be determined. -*rpDocMatch*
-Pointer to a document that is assigned the matching document, if the file specified by *lpszPathName* is already open. +*`rpDocMatch`*\ +Pointer to a document that is assigned the matching document, if the file specified by *`lpszPathName`* is already open. ### Return Value -A value from the **Confidence** enumeration, which is defined as follows: +A value from the **`Confidence`** enumeration, which is defined as follows: ``` enum Confidence @@ -395,15 +394,15 @@ enum Confidence Use this function to determine the type of document template to use for opening a file. If your application supports multiple file types, for example, you can use this function to determine which of the available document templates is appropriate for a given file by calling `MatchDocType` for each template in turn, and choosing a template according to the confidence value returned. -If the file specified by *lpszPathName* is already open, this function returns `CDocTemplate::yesAlreadyOpen` and copies the file's `CDocument` object into the object at *rpDocMatch*. +If the file specified by *`lpszPathName`* is already open, this function returns `CDocTemplate::yesAlreadyOpen` and copies the file's `CDocument` object into the object at *`rpDocMatch`*. -If the file is not open but the extension in *lpszPathName* matches the extension specified by `CDocTemplate::filterExt`, this function returns `CDocTemplate::yesAttemptNative` and sets *rpDocMatch* to NULL. For more information on `CDocTemplate::filterExt`, see [CDocTemplate::GetDocString](#getdocstring). +If the file isn't open but the extension in *`lpszPathName`* matches the extension specified by `CDocTemplate::filterExt`, this function returns `CDocTemplate::yesAttemptNative` and sets *`rpDocMatch`* to `NULL`. For more information on `CDocTemplate::filterExt`, see [`CDocTemplate::GetDocString`](#getdocstring). If neither case is true, the function returns `CDocTemplate::yesAttemptForeign`. -The default implementation does not return `CDocTemplate::maybeAttemptForeign` or `CDocTemplate::maybeAttemptNative`. Override this function to implement type-matching logic appropriate to your application, perhaps using these two values from the **Confidence** enumeration. +The default implementation doesn't return `CDocTemplate::maybeAttemptForeign` or `CDocTemplate::maybeAttemptNative`. Override this function to implement type-matching logic appropriate to your application, perhaps using these two values from the **`Confidence`** enumeration. -## CDocTemplate::OpenDocumentFile +## `CDocTemplate::OpenDocumentFile` Opens a file specified by a path. @@ -417,23 +416,23 @@ virtual CDocument* OpenDocumentFile( ### Parameters -*lpszPathName*
+*`lpszPathName`*\ [in] Pointer to the path of the file that contains the document to be opened. -*bAddToMRU*
-[in] TRUE indicates the document is one of the most recent files; FALSE indicates the document is not one of the most recent files. +*`bAddToMRU`*\ +[in] `TRUE` indicates the document is one of the most recent files; `FALSE` indicates the document isn't one of the most recent files. ### Return Value -A pointer to the document whose file is named by *lpszPathName*; NULL if unsuccessful. +A pointer to the document whose file is named by *`lpszPathName`*; `NULL` if unsuccessful. ### Remarks -Opens the file whose path is specified by *lpszPathName*. If *lpszPathName* is NULL, a new file that contains a document of the type associated with this template is created. +Opens the file whose path is specified by *`lpszPathName`*. If *`lpszPathName`* is `NULL`, a new file that contains a document of the type associated with this template is created. -## CDocTemplate::RemoveDocument +## `CDocTemplate::RemoveDocument` -Removes the document pointed to by *pDoc* from the list of documents associated with this template. +Removes the document pointed to by *`pDoc`* from the list of documents associated with this template. ``` virtual void RemoveDocument(CDocument* pDoc); @@ -441,14 +440,14 @@ virtual void RemoveDocument(CDocument* pDoc); ### Parameters -*pDoc*
+*`pDoc`*\ Pointer to the document to be removed. ### Remarks The derived classes `CMultiDocTemplate` and `CSingleDocTemplate` override this function. If you derive your own document-template class from `CDocTemplate`, your derived class must override this function. -## CDocTemplate::SaveAllModified +## `CDocTemplate::SaveAllModified` Saves all documents that have been modified. @@ -460,7 +459,7 @@ virtual BOOL SaveAllModified(); Non-zero if successful; otherwise 0. -## CDocTemplate::SetContainerInfo +## `CDocTemplate::SetContainerInfo` Determines the resources for OLE containers when editing an in-place OLE item. @@ -470,16 +469,16 @@ void SetContainerInfo(UINT nIDOleInPlaceContainer); ### Parameters -*nIDOleInPlaceContainer*
+*`nIDOleInPlaceContainer`*\ The ID of the resources used when an embedded object is activated. ### Remarks -Call this function to set the resources to be used when an OLE object is in-place activated. These resources may include menus and accelerator tables. This function is usually called in the [CWinApp::InitInstance](../../mfc/reference/cwinapp-class.md#initinstance) function of your application. +Call this function to set the resources to be used when an OLE object is in-place activated. These resources may include menus and accelerator tables. This function is usually called in the [`CWinApp::InitInstance`](../../mfc/reference/cwinapp-class.md#initinstance) function of your application. -The menu associated with *nIDOleInPlaceContainer* contains separators that allow the menu of the activated in-place item to merge with the menu of the container application. For more information about merging server and container menus, see the article [Menus and Resources (OLE)](../../mfc/menus-and-resources-ole.md). +The menu associated with *`nIDOleInPlaceContainer`* contains separators that allow the menu of the activated in-place item to merge with the menu of the container application. For more information about merging server and container menus, see the article [Menus and Resources (OLE)](../../mfc/menus-and-resources-ole.md). -## CDocTemplate::SetDefaultTitle +## `CDocTemplate::SetDefaultTitle` Call this function to load the document's default title and display it in the document's title bar. @@ -489,14 +488,14 @@ virtual void SetDefaultTitle(CDocument* pDocument) = 0; ### Parameters -*pDocument*
+*`pDocument`*\ Pointer to the document whose title is to be set. ### Remarks -For information on the default title, see the description of `CDocTemplate::docName` in [CDocTemplate::GetDocString](#getdocstring). +For information on the default title, see the description of `CDocTemplate::docName` in [`CDocTemplate::GetDocString`](#getdocstring). -## CDocTemplate::SetServerInfo +## `CDocTemplate::SetServerInfo` Determines the resources and classes when the server document is embedded or edited in-place. @@ -510,25 +509,25 @@ void SetServerInfo( ### Parameters -*nIDOleEmbedding*
+*`nIDOleEmbedding`*\ The ID of the resources used when an embedded object is opened in a separate window. -*nIDOleInPlaceServer*
+*`nIDOleInPlaceServer`*\ The ID of the resources used when an embedded object is activated in-place. -*pOleFrameClass*
-Pointer to a [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) structure containing class information for the frame window object created when in-place activation occurs. +*`pOleFrameClass`*\ +Pointer to a [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) structure containing class information for the frame window object created when in-place activation occurs. -*pOleViewClass*
+*`pOleViewClass`*\ Pointer to a `CRuntimeClass` structure containing class information for the view object created when in-place activation occurs. ### Remarks Call this member function to identify resources that will be used by the server application when the user requests activation of an embedded object. These resources consist of menus and accelerator tables. This function is usually called in the `InitInstance` of your application. -The menu associated with *nIDOleInPlaceServer* contains separators that allow the server menu to merge with the menu of the container. For more information about merging server and container menus, see the article [Menus and Resources (OLE)](../../mfc/menus-and-resources-ole.md). +The menu associated with *`nIDOleInPlaceServer`* contains separators that allow the server menu to merge with the menu of the container. For more information about merging server and container menus, see the article [Menus and Resources (OLE)](../../mfc/menus-and-resources-ole.md). -## CDocTemplate::CreatePreviewFrame +## `CDocTemplate::CreatePreviewFrame` Creates a child frame used for Rich Preview. @@ -540,10 +539,10 @@ CFrameWnd* CreatePreviewFrame( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ A pointer to a parent window (usually provided by the Shell). -*pDoc*
+*`pDoc`*\ A pointer to a document object, whose content will be previewed. ### Return Value @@ -552,7 +551,7 @@ A valid pointer to a `CFrameWnd` object, or NULL if the creation fails. ### Remarks -## CDocTemplate::SetPreviewInfo +## `CDocTemplate::SetPreviewInfo` Sets up the out of process preview handler. @@ -565,27 +564,27 @@ void SetPreviewInfo( ### Parameters -*nIDPreviewFrame*
+*`nIDPreviewFrame`*\ Specifies a resource ID of the preview frame. -*pPreviewFrameClass*
+*`pPreviewFrameClass`*\ Specifies a pointer to a runtime class information structure of the preview frame. -*pPreviewViewClass*
+*`pPreviewViewClass`*\ Specifies a pointer to a runtime class information structure of the preview view. ### Remarks ## See also -[CCmdTarget Class](../../mfc/reference/ccmdtarget-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CSingleDocTemplate Class](../../mfc/reference/csingledoctemplate-class.md)
-[CMultiDocTemplate Class](../../mfc/reference/cmultidoctemplate-class.md)
-[CDocument Class](../../mfc/reference/cdocument-class.md)
-[CView Class](../../mfc/reference/cview-class.md)
-[CScrollView Class](../../mfc/reference/cscrollview-class.md)
-[CEditView Class](../../mfc/reference/ceditview-class.md)
-[CFormView Class](../../mfc/reference/cformview-class.md)
-[CFrameWnd Class](../../mfc/reference/cframewnd-class.md)
-[CMDIChildWnd Class](../../mfc/reference/cmdichildwnd-class.md) +[`CCmdTarget` Class](../../mfc/reference/ccmdtarget-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CSingleDocTemplate` Class](../../mfc/reference/csingledoctemplate-class.md)\ +[`CMultiDocTemplate` Class](../../mfc/reference/cmultidoctemplate-class.md)\ +[`CDocument` Class](../../mfc/reference/cdocument-class.md)\ +[`CView` Class](../../mfc/reference/cview-class.md)\ +[`CScrollView` Class](../../mfc/reference/cscrollview-class.md)\ +[`CEditView` Class](../../mfc/reference/ceditview-class.md)\ +[`CFormView` Class](../../mfc/reference/cformview-class.md)\ +[`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md)\ +[`CMDIChildWnd` Class](../../mfc/reference/cmdichildwnd-class.md) diff --git a/docs/mfc/reference/cdocument-class.md b/docs/mfc/reference/cdocument-class.md index 5ab35556df..53f7c00e9c 100644 --- a/docs/mfc/reference/cdocument-class.md +++ b/docs/mfc/reference/cdocument-class.md @@ -705,9 +705,9 @@ Note that there are cases where `OnNewDocument` is called twice. This occurs whe The following examples illustrate alternative methods of initializing a document object. [!code-cpp[NVC_MFCDocView#60](../../mfc/codesnippet/cpp/cdocument-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#61](../../mfc/codesnippet/cpp/cdocument-class_6.cpp)] - +  [!code-cpp[NVC_MFCDocView#62](../../mfc/codesnippet/cpp/cdocument-class_7.cpp)] ## `CDocument::OnOpenDocument` @@ -738,11 +738,11 @@ If the user chooses the File Open command in an SDI application, the framework u The following examples illustrate alternative methods of initializing a document object. [!code-cpp[NVC_MFCDocView#60](../../mfc/codesnippet/cpp/cdocument-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#61](../../mfc/codesnippet/cpp/cdocument-class_6.cpp)] - +  [!code-cpp[NVC_MFCDocView#62](../../mfc/codesnippet/cpp/cdocument-class_7.cpp)] - +  [!code-cpp[NVC_MFCDocView#63](../../mfc/codesnippet/cpp/cdocument-class_8.cpp)] ## `CDocument::OnPreviewHandlerQueryFocus` diff --git a/docs/mfc/reference/ceditview-class.md b/docs/mfc/reference/ceditview-class.md index 618fca8547..19e9d78e46 100644 --- a/docs/mfc/reference/ceditview-class.md +++ b/docs/mfc/reference/ceditview-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CEditView Class" title: "CEditView Class" -ms.date: "11/04/2016" +description: "Learn more about: CEditView Class" +ms.date: 11/04/2016 f1_keywords: ["CEditView", "AFXEXT/CEditView", "AFXEXT/CEditView::CEditView", "AFXEXT/CEditView::FindText", "AFXEXT/CEditView::GetBufferLength", "AFXEXT/CEditView::GetEditCtrl", "AFXEXT/CEditView::GetPrinterFont", "AFXEXT/CEditView::GetSelectedText", "AFXEXT/CEditView::LockBuffer", "AFXEXT/CEditView::PrintInsideRect", "AFXEXT/CEditView::SerializeRaw", "AFXEXT/CEditView::SetPrinterFont", "AFXEXT/CEditView::SetTabStops", "AFXEXT/CEditView::UnlockBuffer", "AFXEXT/CEditView::OnFindNext", "AFXEXT/CEditView::OnReplaceAll", "AFXEXT/CEditView::OnReplaceSel", "AFXEXT/CEditView::OnTextNotFound", "AFXEXT/CEditView::dwStyleDefault"] helpviewer_keywords: ["CEditView [MFC], CEditView", "CEditView [MFC], FindText", "CEditView [MFC], GetBufferLength", "CEditView [MFC], GetEditCtrl", "CEditView [MFC], GetPrinterFont", "CEditView [MFC], GetSelectedText", "CEditView [MFC], LockBuffer", "CEditView [MFC], PrintInsideRect", "CEditView [MFC], SerializeRaw", "CEditView [MFC], SetPrinterFont", "CEditView [MFC], SetTabStops", "CEditView [MFC], UnlockBuffer", "CEditView [MFC], OnFindNext", "CEditView [MFC], OnReplaceAll", "CEditView [MFC], OnReplaceSel", "CEditView [MFC], OnTextNotFound", "CEditView [MFC], dwStyleDefault"] -ms.assetid: bf38255c-fcbe-450c-95b2-3c5e35f86c37 --- # CEditView Class @@ -427,7 +426,7 @@ Width of each tab stop, in dialog units. ### Remarks -Only a single tab-stop width is supported. ( `CEdit` objects support multiple tab widths.) Widths are in dialog units, which equal one-fourth of the average character width (based on uppercase and lowercase alphabetic characters only) of the font used at the time of printing or displaying. You should not use `CEdit::SetTabStops` because `CEditView` must cache the tab-stop value. +Only a single tab-stop width is supported. (`CEdit` objects support multiple tab widths.) Widths are in dialog units, which equal one-fourth of the average character width (based on uppercase and lowercase alphabetic characters only) of the font used at the time of printing or displaying. You should not use `CEdit::SetTabStops` because `CEditView` must cache the tab-stop value. This function modifies only the tabs of the object for which it is called. To change the tab stops for each `CEditView` object in your application, call each object's `SetTabStops` function. diff --git a/docs/mfc/reference/cevent-class.md b/docs/mfc/reference/cevent-class.md index 85aa0458a2..2ed97e9f1d 100644 --- a/docs/mfc/reference/cevent-class.md +++ b/docs/mfc/reference/cevent-class.md @@ -4,9 +4,8 @@ title: "CEvent Class" ms.date: "11/04/2016" f1_keywords: ["CEvent", "AFXMT/CEvent", "AFXMT/CEvent::CEvent", "AFXMT/CEvent::PulseEvent", "AFXMT/CEvent::ResetEvent", "AFXMT/CEvent::SetEvent", "AFXMT/CEvent::Unlock"] helpviewer_keywords: ["CEvent [MFC], CEvent", "CEvent [MFC], PulseEvent", "CEvent [MFC], ResetEvent", "CEvent [MFC], SetEvent", "CEvent [MFC], Unlock"] -ms.assetid: df676042-ce27-4702-800a-e73ff4f44395 --- -# CEvent Class +# `CEvent` Class Represents an event, which is a synchronization object that enables one thread to notify another that an event has occurred. @@ -22,16 +21,16 @@ class CEvent : public CSyncObject |Name|Description| |----------|-----------------| -|[CEvent::CEvent](#cevent)|Constructs a `CEvent` object.| +|[`CEvent::CEvent`](#cevent)|Constructs a `CEvent` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CEvent::PulseEvent](#pulseevent)|Sets the event to available (signaled), releases waiting threads, and sets the event to unavailable (nonsignaled).| -|[CEvent::ResetEvent](#resetevent)|Sets the event to unavailable (nonsignaled).| -|[CEvent::SetEvent](#setevent)|Sets the event to available (signaled) and releases any waiting threads.| -|[CEvent::Unlock](#unlock)|Releases the event object.| +|[`CEvent::PulseEvent`](#pulseevent)|Sets the event to available (signaled), releases waiting threads, and sets the event to unavailable (nonsignaled).| +|[`CEvent::ResetEvent`](#resetevent)|Sets the event to unavailable (nonsignaled).| +|[`CEvent::SetEvent`](#setevent)|Sets the event to available (signaled) and releases any waiting threads.| +|[`CEvent::Unlock`](#unlock)|Releases the event object.| ## Remarks @@ -39,22 +38,22 @@ Events are useful when a thread must know when to perform its task. For example, `CEvent` objects have two types: manual and automatic. -An automatic `CEvent` object automatically returns to a non-signaled (unavailable) state after at least one thread is released. By default, a `CEvent` object is automatic unless you pass `TRUE` for the *bManualReset* parameter during construction. +An automatic `CEvent` object automatically returns to a non-signaled (unavailable) state after at least one thread is released. By default, a `CEvent` object is automatic unless you pass `TRUE` for the *`bManualReset`* parameter during construction. -A manual `CEvent` object stays in the state set by [SetEvent](#setevent) or [ResetEvent](#resetevent) until the other function is called. To create a manual `CEvent` object, pass `TRUE` for the `bManualReset` parameter during construction. +A manual `CEvent` object stays in the state set by [`SetEvent`](#setevent) or [`ResetEvent`](#resetevent) until the other function is called. To create a manual `CEvent` object, pass `TRUE` for the `bManualReset` parameter during construction. -To use a `CEvent` object, construct the `CEvent` object when it is required. Specify the name of the event you want to wait on, and also specify that your application should initially own it. You can then access the event when the constructor returns. Call [SetEvent](#setevent) to signal (make available) the event object and then call [Unlock](#unlock) when you are done accessing the controlled resource. +To use a `CEvent` object, construct the `CEvent` object when it's required. Specify the name of the event you want to wait on, and also specify that your application should initially own it. You can then access the event when the constructor returns. Call [`SetEvent`](#setevent) to signal (make available) the event object and then call [`Unlock`](#unlock) when you're done accessing the controlled resource. -An alternative method for using `CEvent` objects is to add a variable of type `CEvent` as a data member to the class you want to control. During construction of the controlled object, call the constructor of the `CEvent` data member and specify whether the event is initially signaled, and also specifythe type of event object you want, the name of the event (if it will be used across process boundaries), and any security attributes you want. +An alternative method for using `CEvent` objects is to add a variable of type `CEvent` as a data member to the class you want to control. During construction of the controlled object, call the constructor of the `CEvent` data member and specify whether the event is initially signaled, and also specify the type of event object you want, the name of the event (if it will be used across process boundaries), and any security attributes you want. -To access a resource controlled by a `CEvent` object in this manner, first create a variable of either type [CSingleLock](../../mfc/reference/csinglelock-class.md) or type [CMultiLock](../../mfc/reference/cmultilock-class.md) in the access method of your resource. Then call the `Lock` method of the lock object (for example, [CMultiLock::Lock](../../mfc/reference/cmultilock-class.md#lock)). At this point, your thread will either gain access to the resource, wait for the resource to be released and gain access, or wait for the resource to be released, time out, and fail to gain access to the resource. In any case, your resource has been accessed in a thread-safe manner. To release the resource, call `SetEvent` to signal the event object, and then use the `Unlock` method of the lock object (for example, [CMultiLock::Unlock](../../mfc/reference/cmultilock-class.md#unlock)), or let the lock object fall out of scope. +To access a resource controlled by a `CEvent` object in this manner, first create a variable of either type [`CSingleLock`](../../mfc/reference/csinglelock-class.md) or type [`CMultiLock`](../../mfc/reference/cmultilock-class.md) in the access method of your resource. Then call the `Lock` method of the `lock` object (for example, [`CMultiLock::Lock`](../../mfc/reference/cmultilock-class.md#lock)). At this point, your thread will either gain access to the resource, wait for the resource to be released and gain access, or wait for the resource to be released, time out, and fail to gain access to the resource. In any case, your resource has been accessed in a thread-safe manner. To release the resource, call `SetEvent` to signal the event object, and then use the `Unlock` method of the `lock` object (for example, [`CMultiLock::Unlock`](../../mfc/reference/cmultilock-class.md#unlock)), or let the `lock` object fall out of scope. For more information about how to use `CEvent` objects, see [Multithreading: How to Use the Synchronization Classes](../../parallel/multithreading-how-to-use-the-synchronization-classes.md). ## Example [!code-cpp[NVC_MFC_Utilities#45](../../mfc/codesnippet/cpp/cevent-class_1.cpp)] - +  [!code-cpp[NVC_MFC_Utilities#46](../../mfc/codesnippet/cpp/cevent-class_2.cpp)] ## Inheritance Hierarchy @@ -67,9 +66,9 @@ For more information about how to use `CEvent` objects, see [Multithreading: How ## Requirements -**Header:** afxmt.h +**Header:** `afxmt.h` -## CEvent::CEvent +## `CEvent::CEvent` Constructs a named or unnamed `CEvent` object. @@ -83,28 +82,28 @@ CEvent( ### Parameters -*bInitiallyOwn*
-If TRUE, the thread for the `CMultilock` or `CSingleLock` object is enabled. Otherwise, all threads wanting to access the resource must wait. +*`bInitiallyOwn`*\ +If `TRUE`, the thread for the `CMultilock` or `CSingleLock` object is enabled. Otherwise, all threads wanting to access the resource must wait. -*bManualReset*
-If TRUE, specifies that the event object is a manual event, otherwise the event object is an automatic event. +*`bManualReset`*\ +If `TRUE`, specifies that the event object is a manual event, otherwise the event object is an automatic event. -*lpszName*
-Name of the `CEvent` object. Must be supplied if the object will be used across process boundaries. If the name matches an existing event, the constructor builds a new `CEvent` object which references the event of that name. If the name matches an existing synchronization object that is not an event, the construction will fail. If NULL, the name will be null. +*`lpszName`*\ +Name of the `CEvent` object. Must be supplied if the object will be used across process boundaries. If the name matches an existing event, the constructor builds a new `CEvent` object that references the event of that name. If the name matches an existing synchronization object that isn't an event, the construction will fail. If `NULL`, the name will be null. -*lpsaAttribute*
-Security attributes for the event object. For a full description of this structure, see [SECURITY_ATTRIBUTES](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) in the Windows SDK. +*`lpsaAttribute`*\ +Security attributes for the event object. For a full description of this structure, see [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) in the Windows SDK. ### Remarks -To access or release a `CEvent` object, create a [CMultiLock](../../mfc/reference/cmultilock-class.md) or [CSingleLock](../../mfc/reference/csinglelock-class.md) object and call its [Lock](../../mfc/reference/csinglelock-class.md#lock) and [Unlock](../../mfc/reference/csinglelock-class.md#unlock) member functions. +To access or release a `CEvent` object, create a [`CMultiLock`](../../mfc/reference/cmultilock-class.md) or [`CSingleLock`](../../mfc/reference/csinglelock-class.md) object and call its [`Lock`](../../mfc/reference/csinglelock-class.md#lock) and [`Unlock`](../../mfc/reference/csinglelock-class.md#unlock) member functions. -To change the state of a `CEvent` object to signaled (threads do not have to wait), call [SetEvent](#setevent) or [PulseEvent](#pulseevent). To set the state of a `CEvent` object to nonsignaled (threads must wait), call [ResetEvent](#resetevent). +To change the state of a `CEvent` object to signaled (threads don't have to wait), call [`SetEvent`](#setevent) or [`PulseEvent`](#pulseevent). To set the state of a `CEvent` object to nonsignaled (threads must wait), call [`ResetEvent`](#resetevent). > [!IMPORTANT] -> After creating the `CEvent` object, use [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to ensure that the mutex didn't already exist. If the mutex did exist unexpectedly, it may indicate a rogue process is squatting and may be intending to use the mutex maliciously. In this case, the recommended security-conscious procedure is to close the handle and continue as if there was a failure in creating the object. +> After creating the `CEvent` object, use [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to ensure that the mutex didn't already exist. If the mutex did exist unexpectedly, it may indicate a rogue process is squatting and may be intending to use the mutex maliciously. In this case, the recommended security-conscious procedure is to close the handle and continue as if there was a failure in creating the object. -## CEvent::PulseEvent +## `CEvent::PulseEvent` Sets the state of the event to signaled (available), releases any waiting threads, and resets it to nonsignaled (unavailable) automatically. @@ -122,11 +121,11 @@ If the event is manual, all waiting threads are released, the event is set to no If no threads are waiting, or no threads can be released immediately, `PulseEvent` sets the state of the event to nonsignaled and returns. -`PulseEvent` uses the underlying Win32 `PulseEvent` function, which can be momentarily removed from the wait state by a kernel-mode asynchronous procedure call. Therefore, `PulseEvent` is unreliable and should not be used by new applications. For more information, see the [PulseEvent function](/windows/win32/api/winbase/nf-winbase-pulseevent). +`PulseEvent` uses the underlying Win32 `PulseEvent` function, which can be momentarily removed from the wait state by a kernel-mode asynchronous procedure call. Therefore, `PulseEvent` is unreliable and shouldn't be used by new applications. For more information, see the [`PulseEvent` function](/windows/win32/api/winbase/nf-winbase-pulseevent). -## CEvent::ResetEvent +## `CEvent::ResetEvent` -Sets the state of the event to nonsignaled until explicitly set to signaled by the [SetEvent](#setevent) member function. +Sets the state of the event to nonsignaled until explicitly set to signaled by the [`SetEvent`](#setevent) member function. ``` BOOL ResetEvent(); @@ -140,9 +139,9 @@ Nonzero if the function was successful; otherwise 0. This causes all threads wishing to access this event to wait. -This member function is not used by automatic events. +This member function isn't used by automatic events. -## CEvent::SetEvent +## `CEvent::SetEvent` Sets the state of the event to signaled, releasing any waiting threads. @@ -156,9 +155,9 @@ Nonzero if the function was successful, otherwise 0. ### Remarks -If the event is manual, the event will remain signaled until [ResetEvent](#resetevent) is called. More than one thread can be released in this case. If the event is automatic, the event will remain signaled until a single thread is released. The system will then set the state of the event to nonsignaled. If no threads are waiting, the state remains signaled until one thread is released. +If the event is manual, the event will remain signaled until [`ResetEvent`](#resetevent) is called. More than one thread can be released in this case. If the event is automatic, the event will remain signaled until a single thread is released. The system will then set the state of the event to nonsignaled. If no threads are waiting, the state remains signaled until one thread is released. -## CEvent::Unlock +## `CEvent::Unlock` Releases the event object. @@ -172,9 +171,9 @@ Nonzero if the thread owned the event object and the event is an automatic event ### Remarks -This member function is called by threads that currently own an automatic event to release it after they are done, if their lock object is to be reused. If the lock object is not to be reused, this function will be called by the lock object's destructor. +This member function is called by threads that currently own an automatic event to release it after they're done, if their `lock` object is to be reused. If the `lock` object isn't to be reused, this function will be called by the `lock` object's destructor. ## See also -[CSyncObject Class](../../mfc/reference/csyncobject-class.md)
+[`CSyncObject` Class](../../mfc/reference/csyncobject-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/cexception-class.md b/docs/mfc/reference/cexception-class.md index 70b1e49b7e..93f52aba8a 100644 --- a/docs/mfc/reference/cexception-class.md +++ b/docs/mfc/reference/cexception-class.md @@ -4,9 +4,8 @@ title: "CException Class" ms.date: "11/04/2016" f1_keywords: ["CException", "AFX/CException", "AFX/CException::CException", "AFX/CException::Delete", "AFX/CException::ReportError"] helpviewer_keywords: ["CException [MFC], CException", "CException [MFC], Delete", "CException [MFC], ReportError"] -ms.assetid: cfacf14d-bfe4-4666-a5c7-38b800512920 --- -# CException Class +# `CException` Class The base class for all exceptions in the Microsoft Foundation Class Library. @@ -22,44 +21,44 @@ class AFX_NOVTABLE CException : public CObject |Name|Description| |----------|-----------------| -|[CException::CException](#cexception)|Constructs a `CException` object.| +|[`CException::CException`](#cexception)|Constructs a `CException` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CException::Delete](#delete)|Deletes a `CException` object.| -|[CException::ReportError](#reporterror)|Reports an error message in a message box to the user.| +|[`CException::Delete`](#delete)|Deletes a `CException` object.| +|[`CException::ReportError`](#reporterror)|Reports an error message in a message box to the user.| ## Remarks -Because `CException` is an abstract base class you cannot create `CException` objects directly; you must create objects of derived classes. If you need to create your own `CException`-style class, use one of the derived classes listed above as a model. Make sure that your derived class also uses `IMPLEMENT_DYNAMIC`. +Because `CException` is an abstract base class you can't create `CException` objects directly; you must create objects of derived classes. If you need to create your own `CException`-style class, use one of the derived classes listed above as a model. Make sure that your derived class also uses `IMPLEMENT_DYNAMIC`. The derived classes and their descriptions are listed below: |Name|Description| |-|-| -|[CSimpleException](../../mfc/reference/csimpleexception-class.md)|A base class for resource-critical MFC exceptions| -|[CInvalidArgException](../../mfc/reference/cinvalidargexception-class.md)|Invalid argument exception condition| -|[CMemoryException](../../mfc/reference/cmemoryexception-class.md)|Out-of-memory exception| -|[CNotSupportedException](../../mfc/reference/cnotsupportedexception-class.md)|Request for an unsupported operation| -|[CArchiveException](../../mfc/reference/carchiveexception-class.md)|Archive-specific exception| -|[CFileException](../../mfc/reference/cfileexception-class.md)|File-specific exception| -|[CResourceException](../../mfc/reference/cresourceexception-class.md)|Windows resource not found or not creatable| -|[COleException](../../mfc/reference/coleexception-class.md)|OLE exception| -|[CDBException](../../mfc/reference/cdbexception-class.md)|Database exception (that is, exception conditions arising for MFC database classes based on Open Database Connectivity)| -|[COleDispatchException](../../mfc/reference/coledispatchexception-class.md)|OLE dispatch (automation) exception| -|[CUserException](../../mfc/reference/cuserexception-class.md)|Exception that indicates that a resource could not be found| -|[CDaoException](../../mfc/reference/cdaoexception-class.md)|Data access object exception (that is, exception conditions arising for DAO classes)| -|[CInternetException](../../mfc/reference/cinternetexception-class.md)|Internet exception (that is, exception conditions arising for Internet classes).| +|[`CSimpleException`](../../mfc/reference/csimpleexception-class.md)|A base class for resource-critical MFC exceptions| +|[`CInvalidArgException`](../../mfc/reference/cinvalidargexception-class.md)|Invalid argument exception condition| +|[`CMemoryException`](../../mfc/reference/cmemoryexception-class.md)|Out-of-memory exception| +|[`CNotSupportedException`](../../mfc/reference/cnotsupportedexception-class.md)|Request for an unsupported operation| +|[`CArchiveException`](../../mfc/reference/carchiveexception-class.md)|Archive-specific exception| +|[`CFileException`](../../mfc/reference/cfileexception-class.md)|File-specific exception| +|[`CResourceException`](../../mfc/reference/cresourceexception-class.md)|Windows resource not found or not creatable| +|[`COleException`](../../mfc/reference/coleexception-class.md)|OLE exception| +|[`CDBException`](../../mfc/reference/cdbexception-class.md)|Database exception (that is, exception conditions arising for MFC database classes based on Open Database Connectivity)| +|[`COleDispatchException`](../../mfc/reference/coledispatchexception-class.md)|OLE dispatch (automation) exception| +|[`CUserException`](../../mfc/reference/cuserexception-class.md)|Exception that indicates that a resource could not be found| +|[`CDaoException`](../../mfc/reference/cdaoexception-class.md)|Data access object exception (that is, exception conditions arising for DAO classes)| +|[`CInternetException`](../../mfc/reference/cinternetexception-class.md)|Internet exception (that is, exception conditions arising for Internet classes).| -These exceptions are intended to be used with the [THROW](exception-processing.md#throw), [THROW_LAST](exception-processing.md#throw_last), [try](exception-processing.md#try), [catch](exception-processing.md#catch), [and_catch](exception-processing.md#and_catch), and [end_catch](exception-processing.md#end_catch) macros. For more information on exceptions, see [Exception Processing](exception-processing.md), or see the article [Exception Handling (MFC)](../exception-handling-in-mfc.md). +These exceptions are intended to be used with the [`THROW`](exception-processing.md#throw), [`THROW_LAST`](exception-processing.md#throw_last), [`try`](exception-processing.md#try), [`catch`](exception-processing.md#catch), [`and_catch`](exception-processing.md#and_catch), and [`end_catch`](exception-processing.md#end_catch) macros. For more information on exceptions, see [Exception Processing](exception-processing.md), or see the article [Exception Handling (MFC)](../exception-handling-in-mfc.md). -To catch a specific exception, use the appropriate derived class. To catch all types of exceptions, use `CException`, and then use [CObject::IsKindOf](cobject-class.md#iskindof) to differentiate among `CException`-derived classes. Note that `CObject::IsKindOf` works only for classes declared with the [IMPLEMENT_DYNAMIC](run-time-object-model-services.md#implement_dynamic) macro, in order to take advantage of dynamic type checking. Any `CException`-derived class that you create should use the `IMPLEMENT_DYNAMIC` macro, too. +To catch a specific exception, use the appropriate derived class. To catch all types of exceptions, use `CException`, and then use [`CObject::IsKindOf`](cobject-class.md#iskindof) to differentiate among `CException`-derived classes. Note that `CObject::IsKindOf` works only for classes declared with the [`IMPLEMENT_DYNAMIC`](run-time-object-model-services.md#implement_dynamic) macro, in order to take advantage of dynamic type checking. Any `CException`-derived class that you create should use the `IMPLEMENT_DYNAMIC` macro, too. -You can report details about exceptions to the user by calling [GetErrorMessage](cfileexception-class.md#geterrormessage) or [ReportError](#reporterror), two member functions that work with any of `CException`'s derived classes. +You can report details about exceptions to the user by calling [`GetErrorMessage`](cfileexception-class.md#geterrormessage) or [`ReportError`](#reporterror), two member functions that work with any of `CException`'s derived classes. -If an exception is caught by one of the macros, the `CException` object is deleted automatically; do not delete it yourself. If an exception is caught by using a **`catch`** keyword, it is not automatically deleted. See the article [Exception Handling (MFC)](../exception-handling-in-mfc.md) for more information about when to delete an exeption object. +If an exception is caught by one of the macros, the `CException` object is deleted automatically; don't delete it yourself. If an exception is caught by using a **`catch`** keyword, it isn't automatically deleted. See the article [Exception Handling (MFC)](../exception-handling-in-mfc.md) for more information about when to delete an exception object. ## Inheritance Hierarchy @@ -69,9 +68,9 @@ If an exception is caught by one of the macros, the `CException` object is delet ## Requirements -**Header:** afx.h +**Header:** `afx.h` -## CException::CException +## `CException::CException` This member function constructs a `CException` object. @@ -81,14 +80,14 @@ explicit CException(BOOL bAutoDelete); ### Parameters -*b_AutoDelete*
-Specify TRUE if the memory for the `CException` object has been allocated on the heap. This will cause the `CException` object to be deleted when the `Delete` member function is called to delete the exception. Specify FALSE if the `CException` object is on the stack or is a global object. In this case, the `CException` object will not be deleted when the `Delete` member function is called. +*`b_AutoDelete`*\ +Specify `TRUE` if the memory for the `CException` object has been allocated on the heap. This will cause the `CException` object to be deleted when the `Delete` member function is called to delete the exception. Specify `FALSE` if the `CException` object is on the stack or is a global object. In this case, the `CException` object won't be deleted when the `Delete` member function is called. ### Remarks -You would normally never need to call this constructor directly. A function that throws an exception should create an instance of a `CException`-derived class and call its constructor, or it should use one of the MFC throw functions, such as [AfxThrowFileException](exception-processing.md#afxthrowfileexception), to throw a predefined type. This documentation is provided only for completeness. +You would normally never need to call this constructor directly. A function that throws an exception should create an instance of a `CException`-derived class and call its constructor, or it should use one of the MFC throw functions, such as [`AfxThrowFileException`](exception-processing.md#afxthrowfileexception), to throw a predefined type. This documentation is provided only for completeness. -## CException::Delete +## `CException::Delete` This function checks to see if the `CException` object was created on the heap, and if so, it calls the **`delete`** operator on the object. @@ -98,11 +97,11 @@ void Delete(); ### Remarks -When deleting a `CException` object, use the `Delete` member function to delete the exception. Do not use the **`delete`** operator directly, because the `CException` object may be a global object or have been created on the stack. +When deleting a `CException` object, use the `Delete` member function to delete the exception. Don't use the **`delete`** operator directly, because the `CException` object may be a global object or have been created on the stack. -You can specify whether the object should be deleted when the object is constructed. For more information, see [CException::CException](#cexception). +You can specify whether the object should be deleted when the object is constructed. For more information, see [`CException::CException`](#cexception). -You only need to call `Delete` if you are using the C++ **`try`**- **`catch`** mechanism. If you are using the MFC macros **TRY** and **CATCH**, then these macros will automatically call this function. +You only need to call `Delete` if you're using the C++ **`try`**- **`catch`** mechanism. If you're using the MFC macros **`TRY`** and **`CATCH`**, then these macros will automatically call this function. ### Example @@ -144,7 +143,7 @@ catch(CMemoryException* pEx) pEx->Delete(); AfxAbort(); } -// If an exception occurrs in the CFile constructor, +// If an exception occurs in the CFile constructor, // the language will free the memory allocated by new // and will not complete the assignment to pFile. // Thus, our clean-up code needs to test for NULL. @@ -155,7 +154,7 @@ if (pFile != NULL) } ``` -## CException::ReportError +## `CException::ReportError` Call this member function to report error text in a message box to the user. @@ -167,19 +166,19 @@ virtual int ReportError( ### Parameters -*nType*
-Specifies the style of the message box. Apply any combination of the [message-box styles](styles-used-by-mfc.md#message-box-styles) to the box. If you don't specify this parameter, the default is MB_OK. +*`nType`*\ +Specifies the style of the message box. Apply any combination of the [message-box styles](styles-used-by-mfc.md#message-box-styles) to the box. If you don't specify this parameter, the default is `MB_OK`. -*nMessageID*
-Specifies the resource ID (string table entry) of a message to display if the exception object does not have an error message. If 0, the message "No error message is available" is displayed. +*`nMessageID`*\ +Specifies the resource ID (string table entry) of a message to display if the exception object doesn't have an error message. If 0, the message "No error message is available" is displayed. ### Return Value -An `AfxMessageBox` value; otherwise 0 if there is not enough memory to display the message box. See [AfxMessageBox](cstring-formatting-and-message-box-display.md#afxmessagebox) for the possible return values. +An `AfxMessageBox` value; otherwise 0 if there isn't enough memory to display the message box. See [`AfxMessageBox`](cstring-formatting-and-message-box-display.md#afxmessagebox) for the possible return values. ### Example -Here is an example of the use of `CException::ReportError`. For another example, see the example for [CATCH](exception-processing.md#catch). +Here's an example of the use of `CException::ReportError`. For another example, see the example for [`CATCH`](exception-processing.md#catch). ```cpp CFile fileInput; @@ -215,6 +214,6 @@ else ## See also -[CObject Class](cobject-class.md)
-[Hierarchy Chart](../hierarchy-chart.md)
+[`CObject` Class](cobject-class.md)\ +[Hierarchy Chart](../hierarchy-chart.md)\ [Exception Processing](exception-processing.md) diff --git a/docs/mfc/reference/cfile-class.md b/docs/mfc/reference/cfile-class.md index 0a2637261c..1621e32746 100644 --- a/docs/mfc/reference/cfile-class.md +++ b/docs/mfc/reference/cfile-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CFile Class" title: "CFile Class" -ms.date: "06/12/2018" +description: "Learn more about: CFile Class" +ms.date: 06/12/2018 f1_keywords: ["CFile", "AFX/CFile", "AFX/CFile::CFile", "AFX/CFile::Abort", "AFX/CFile::Close", "AFX/CFile::Duplicate", "AFX/CFile::Flush", "AFX/CFile::GetFileName", "AFX/CFile::GetFilePath", "AFX/CFile::GetFileTitle", "AFX/CFile::GetLength", "AFX/CFile::GetPosition", "AFX/CFile::GetStatus", "AFX/CFile::LockRange", "AFX/CFile::Open", "AFX/CFile::Read", "AFX/CFile::Remove", "AFX/CFile::Rename", "AFX/CFile::Seek", "AFX/CFile::SeekToBegin", "AFX/CFile::SeekToEnd", "AFX/CFile::SetFilePath", "AFX/CFile::SetLength", "AFX/CFile::SetStatus", "AFX/CFile::UnlockRange", "AFX/CFile::Write", "AFX/CFile::hFileNull", "AFX/CFile::m_hFile", "AFX/CFile::m_pTM"] helpviewer_keywords: ["CFile [MFC], CFile", "CFile [MFC], Abort", "CFile [MFC], Close", "CFile [MFC], Duplicate", "CFile [MFC], Flush", "CFile [MFC], GetFileName", "CFile [MFC], GetFilePath", "CFile [MFC], GetFileTitle", "CFile [MFC], GetLength", "CFile [MFC], GetPosition", "CFile [MFC], GetStatus", "CFile [MFC], LockRange", "CFile [MFC], Open", "CFile [MFC], Read", "CFile [MFC], Remove", "CFile [MFC], Rename", "CFile [MFC], Seek", "CFile [MFC], SeekToBegin", "CFile [MFC], SeekToEnd", "CFile [MFC], SetFilePath", "CFile [MFC], SetLength", "CFile [MFC], SetStatus", "CFile [MFC], UnlockRange", "CFile [MFC], Write", "CFile [MFC], hFileNull", "CFile [MFC], m_hFile", "CFile [MFC], m_pTM"] -ms.assetid: b2eb5757-d499-4e67-b044-dd7d1abaa0f8 --- # CFile Class @@ -277,7 +276,7 @@ The name of the file. For example, when you call `GetFileName` to generate a message to the user about the file `c:\windows\write\myfile.wri`, the filename, `myfile.wri`, is returned. -To return the entire path of the file, including the name, call [GetFilePath](#getfilepath). To return the title of the file ( `myfile`), call [GetFileTitle](#getfiletitle). +To return the entire path of the file, including the name, call [GetFilePath](#getfilepath). To return the title of the file (`myfile`), call [GetFileTitle](#getfiletitle). ### Example @@ -517,7 +516,7 @@ virtual BOOL Open( A string that contains the path to the desired file. The path can be relative, absolute, or a network name (UNC). *nOpenFlags*
-A UINT that defines the file's sharing and access mode. It specifies the action to take when opening the file. You can combine options by using the bitwise-OR ( **|** ) operator. One access permission and one share option are required; the `modeCreate` and `modeNoInherit` modes are optional. See the [CFile](#cfile) constructor for a list of mode options. +A UINT that defines the file's sharing and access mode. It specifies the action to take when opening the file. You can combine options by using the bitwise-OR ( **`|`** ) operator. One access permission and one share option are required; the `modeCreate` and `modeNoInherit` modes are optional. See the [CFile](#cfile) constructor for a list of mode options. *pError*
A pointer to an existing file-exception object that will receive the status of a failed operation. @@ -547,7 +546,7 @@ The following table describes the possible results of `Open`. ### Example [!code-cpp[NVC_MFCFiles#13](../../atl-mfc-shared/reference/codesnippet/cpp/cfile-class_9.cpp)] - +  [!code-cpp[NVC_MFCFiles#14](../../atl-mfc-shared/reference/codesnippet/cpp/cfile-class_10.cpp)] ## CFile::operator HANDLE diff --git a/docs/mfc/reference/cfiledialog-class.md b/docs/mfc/reference/cfiledialog-class.md index ee5d9d5e72..64c02078a8 100644 --- a/docs/mfc/reference/cfiledialog-class.md +++ b/docs/mfc/reference/cfiledialog-class.md @@ -411,7 +411,7 @@ explicit CFileDialog( [in] The parameter that specifies what type of dialog box to create. Set it to TRUE to construct a **File Open** dialog box. Set it to FALSE to construct a **File Save As** dialog box. *lpszDefExt*
-[in] The default file name extension. If the user does not include a known extension (one that has an association on the user’s computer) in the Filename box, the extension specified by *lpszDefExt* is automatically appended to the file name. If this parameter is NULL, no extension is appended. +[in] The default file name extension. If the user does not include a known extension (one that has an association on the user's computer) in the Filename box, the extension specified by *lpszDefExt* is automatically appended to the file name. If this parameter is NULL, no extension is appended. *lpszFileName*
[in] The initial file name that appears in the Filename box. If NULL, no initial file name appears. @@ -437,7 +437,7 @@ The parameter that specifies the style of the file dialog. Set it to TRUE to use Either a **File Open** or **File Save As** dialog box is constructed, depending on the value of *bOpenFileDialog*. -Specifying a default extension using *lpszDefExt* may not produce the behavior that you expect, because it is seldom predictable what extensions have file associations on the user’s computer. If you need more control over the appending of a default extension, you can derive your own class from `CFileDialog`, and override the `CFileDialog::OnFileNameOK` method to perform your own extension handling. +Specifying a default extension using *lpszDefExt* may not produce the behavior that you expect, because it is seldom predictable what extensions have file associations on the user's computer. If you need more control over the appending of a default extension, you can derive your own class from `CFileDialog`, and override the `CFileDialog::OnFileNameOK` method to perform your own extension handling. To enable the user to select multiple files, set the OFN_ALLOWMULTISELECT flag before you call [DoModal](#domodal). You must supply your own file name buffer to store the returned list of multiple file names. Do this by replacing `m_ofn.lpstrFile` with a pointer to a buffer you have allocated, after you construct the [CFileDialog](../../mfc/reference/cfiledialog-class.md), but before you call `DoModal`. Additionally, you must set `m_ofn.nMaxFile` with the number of characters in the buffer pointed to by `m_ofn.lpstrFile`. If you set the maximum number of files to be selected to *n*, the necessary buffer size is `n`*(_MAX_PATH + 1) + 1. For example: @@ -445,13 +445,13 @@ To enable the user to select multiple files, set the OFN_ALLOWMULTISELECT flag b To enable the user to resize an Explorer-style dialog box by using either the mouse or keyboard, set the OFN_ENABLESIZING flag. Setting this flag is necessary only if you provide a hook procedure or custom template. The flag works only with an Explorer-style dialog box; old-style dialog boxes cannot be resized. -The *lpszFilter* parameter is used to determine the type of file name a file must have to be displayed in the file list. The first string in the string pair describes the filter; the second string indicates the file name extension to use. Multiple extensions may be specified by using a semicolon (the ';' character) as the delimiter. The string ends with two '|' characters, followed by a NULL character. You can also use a [CString](../../atl-mfc-shared/using-cstring.md) object for this parameter. +The *lpszFilter* parameter is used to determine the type of file name a file must have to be displayed in the file list. The first string in the string pair describes the filter; the second string indicates the file name extension to use. Multiple extensions may be specified by using a semicolon (the ';' character) as the delimiter. The string ends with two vertical bar characters (`||`), followed by a NULL character. You can also use a [CString](../../atl-mfc-shared/using-cstring.md) object for this parameter. For example, Microsoft Excel allows users to open files that have extensions .xlc (chart) or .xls (worksheet), among others. The filter for Excel could be written as: [!code-cpp[NVC_MFCFiles#24](../../atl-mfc-shared/reference/codesnippet/cpp/cfiledialog-class_2.cpp)] -However, if you plan to use this string to directly update the `OPENFILENAME` structure, you should delimit your strings with the null character, '\0', instead of the vertical bars ('|'). +However, if you plan to use this string to directly update the `OPENFILENAME` structure, you should delimit your strings with the null character, `'\0'`, instead of the vertical bars (`'|'`). The *bVistaStyle* parameter is applicable only when running under Windows Vista or later. Under earlier versions of Windows, this parameter is ignored. If *bVistaStyle* is set to TRUE, when you compile a program with Visual Studio 2008 or later, the new Vista style **File Dialog** will be used. Otherwise, the previous MFC style **File Dialog** will be used. diff --git a/docs/mfc/reference/cfileexception-class.md b/docs/mfc/reference/cfileexception-class.md index 631d93f31b..4f5bd0c822 100644 --- a/docs/mfc/reference/cfileexception-class.md +++ b/docs/mfc/reference/cfileexception-class.md @@ -4,9 +4,8 @@ title: "CFileException Class" ms.date: "06/09/2020" f1_keywords: ["CFileException", "AFX/CFileException", "AFX/CFileException::CFileException", "AFX/CFileException::ErrnoToException", "AFX/CFileException::GetErrorMessage", "AFX/CFileException::OsErrorToException", "AFX/CFileException::ThrowErrno", "AFX/CFileException::ThrowOsError", "AFX/CFileException::m_cause", "AFX/CFileException::m_lOsError", "AFX/CFileException::m_strFileName"] helpviewer_keywords: ["CFileException [MFC], CFileException", "CFileException [MFC], ErrnoToException", "CFileException [MFC], GetErrorMessage", "CFileException [MFC], OsErrorToException", "CFileException [MFC], ThrowErrno", "CFileException [MFC], ThrowOsError", "CFileException [MFC], m_cause", "CFileException [MFC], m_lOsError", "CFileException [MFC], m_strFileName"] -ms.assetid: f6491bb9-bfbc-42fd-a952-b33f9b62323f --- -# CFileException Class +# `CFileException` Class Represents a file-related exception condition. @@ -22,45 +21,45 @@ class CFileException : public CException |Name|Description| |----------|-----------------| -|[CFileException::CFileException](#cfileexception)|Constructs a `CFileException` object.| +|[`CFileException::CFileException`](#cfileexception)|Constructs a `CFileException` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CFileException::ErrnoToException](#errnotoexception)|Returns cause code corresponding to a run-time error number.| -|[CFileException::GetErrorMessage](#geterrormessage)|Retrieves the message describing an exception.| -|[CFileException::OsErrorToException](#oserrortoexception)|Returns a cause code corresponding to an operating system error code.| -|[CFileException::ThrowErrno](#throwerrno)|Throws a file exception based on a runtime error number.| -|[CFileException::ThrowOsError](#throwoserror)|Throws a file exception based on an operating system error number.| +|[`CFileException::ErrnoToException`](#errnotoexception)|Returns cause code corresponding to a run-time error number.| +|[`CFileException::GetErrorMessage`](#geterrormessage)|Retrieves the message describing an exception.| +|[`CFileException::OsErrorToException`](#oserrortoexception)|Returns a cause code corresponding to an operating system error code.| +|[`CFileException::ThrowErrno`](#throwerrno)|Throws a file exception based on a runtime error number.| +|[`CFileException::ThrowOsError`](#throwoserror)|Throws a file exception based on an operating system error number.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CFileException::m_cause](#m_cause)|Contains portable code corresponding to the exception cause.| -|[CFileException::m_lOsError](#m_loserror)|Contains the related operating-system error number.| -|[CFileException::m_strFileName](#m_strfilename)|Contains the name of the file for this exception.| +|[`CFileException::m_cause`](#m_cause)|Contains portable code corresponding to the exception cause.| +|[`CFileException::m_lOsError`](#m_loserror)|Contains the related operating-system error number.| +|[`CFileException::m_strFileName`](#m_strfilename)|Contains the name of the file for this exception.| ## Remarks The `CFileException` class includes public data members that hold the portable cause code and the operating-system-specific error number. The class also provides static member functions for throwing file exceptions and for returning cause codes for both operating-system errors and C run-time errors. -`CFileException` objects are constructed and thrown in `CFile` member functions and in member functions of derived classes. You can access these objects within the scope of a **CATCH** expression. For portability, use only the cause code to get the reason for an exception. For more information about exceptions, see the article [Exception Handling (MFC)](../../mfc/exception-handling-in-mfc.md). +`CFileException` objects are constructed and thrown in `CFile` member functions and in member functions of derived classes. You can access these objects within the scope of a **`CATCH`** expression. For portability, use only the cause code to get the reason for an exception. For more information about exceptions, see the article [Exception Handling (MFC)](../../mfc/exception-handling-in-mfc.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CException](../../mfc/reference/cexception-class.md) +[`CException`](../../mfc/reference/cexception-class.md) `CFileException` ## Requirements -**Header:** afx.h +**Header:** `afx.h` -## CFileException::CFileException +## `CFileException::CFileException` Constructs a `CFileException` object that stores the cause code and the operating-system code in the object. @@ -73,23 +72,23 @@ CFileException( ### Parameters -*cause*
-An enumerated type variable that indicates the reason for the exception. See [CFileException::m_cause](#m_cause) for a list of the possible values. +*`cause`*\ +An enumerated type variable that indicates the reason for the exception. See [`CFileException::m_cause`](#m_cause) for a list of the possible values. -*lOsError*
-An operating-system-specific reason for the exception, if available. The *lOsError* parameter provides more information than *cause* does. +*`lOsError`*\ +An operating-system-specific reason for the exception, if available. The *`lOsError`* parameter provides more information than *`cause`* does. -*lpszArchiveName*
+*`lpszArchiveName`*\ Points to a string containing the name of the `CFile` object causing the exception. ### Remarks -Do not use this constructor directly, but rather call the global function [AfxThrowFileException](exception-processing.md#afxthrowfileexception). +Don't use this constructor directly, but rather call the global function [`AfxThrowFileException`](exception-processing.md#afxthrowfileexception). > [!NOTE] -> The variable *lOsError* applies only to `CFile` and `CStdioFile` objects. The `CMemFile` class does not handle this error code. +> The variable *`lOsError`* applies only to `CFile` and `CStdioFile` objects. The `CMemFile` class does not handle this error code. -## CFileException::ErrnoToException +## `CFileException::ErrnoToException` Converts a given run-time library error value to a `CFileException` enumerated error value. @@ -99,8 +98,8 @@ static int PASCAL ErrnoToException(int nErrno); ### Parameters -*nErrno*
-An integer error code as defined in the run-time include file ERRNO.H. +*`nErrno`*\ +An integer error code as defined in the run-time include file `ERRNO.H`. ### Return Value @@ -108,13 +107,13 @@ Enumerated value that corresponds to a given run-time library error value. ### Remarks -See [CFileException::m_cause](#m_cause) for a list of the possible enumerated values. +See [`CFileException::m_cause`](#m_cause) for a list of the possible enumerated values. ### Example [!code-cpp[NVC_MFCFiles#26](../../atl-mfc-shared/reference/codesnippet/cpp/cfileexception-class_1.cpp)] -## CFileException::GetErrorMessage +## `CFileException::GetErrorMessage` Retrieves text that describes an exception. @@ -127,18 +126,18 @@ virtual BOOL GetErrorMessage( ### Parameters -*lpszError*
+*`lpszError`*\ [in, out] Pointer to a buffer that receives an error message. -*nMaxError*
-[in] The maximum number of characters the specified buffer can hold. This includes the terminating null character. +*`nMaxError`*\ +[in] The maximum number of characters the specified buffer can hold. This includes the terminating `NULL` character. -*pnHelpContext*
+*`pnHelpContext`*\ [in, out] Pointer to an unsigned integer that receives the help context ID. If `NULL`, no ID is returned. ### Return Value -TRUE if the method was successful; otherwise FALSE. +`TRUE` if the method was successful; otherwise `FALSE`. ### Remarks @@ -150,7 +149,7 @@ The following example uses `CFileException::GetErrorMessage`. [!code-cpp[NVC_MFCExceptions#22](../../mfc/codesnippet/cpp/cfileexception-class_2.cpp)] -## CFileException::m_cause +## `CFileException::m_cause` Contains values defined by a `CFileException` enumerated type. @@ -166,16 +165,16 @@ This data member is a public variable of type **`int`**. The enumerators and the |--|--| | `CFileException::none` | 0: No error occurred. | | `CFileException::genericException` | 1: An unspecified error occurred. | -| `CFileException::fileNotFound` | 2: The file could not be located. | +| `CFileException::fileNotFound` | 2: The file couldn't be located. | | `CFileException::badPath` | 3: All or part of the path is invalid. | | `CFileException::tooManyOpenFiles` | 4: The permitted number of open files was exceeded. | -| `CFileException::accessDenied` | 5: The file could not be accessed. | +| `CFileException::accessDenied` | 5: The file couldn't be accessed. | | `CFileException::invalidFile` | 6: There was an attempt to use an invalid file handle. | -| `CFileException::removeCurrentDir` | 7: The current working directory cannot be removed. | +| `CFileException::removeCurrentDir` | 7: The current working directory can't be removed. | | `CFileException::directoryFull` | 8: There are no more directory entries. | | `CFileException::badSeek` | 9: There was an error trying to set the file pointer. | | `CFileException::hardIO` | 10: There was a hardware error. | -| `CFileException::sharingViolation` | 11: SHARE.EXE was not loaded, or a shared region was locked. | +| `CFileException::sharingViolation` | 11: `SHARE.EXE` wasn't loaded, or a shared region was locked. | | `CFileException::lockViolation` | 12: There was an attempt to lock a region that was already locked. | | `CFileException::diskFull` | 13: The disk is full. | | `CFileException::endOfFile` | 14: The end of file was reached. | @@ -184,13 +183,13 @@ This data member is a public variable of type **`int`**. The enumerators and the > These `CFileException` cause enumerators are distinct from the `CArchiveException` cause enumerators. > [!NOTE] -> `CArchiveException::generic` is deprecated. Use `genericException` instead. If **generic** is used in an application and built with /clr, the resulting syntax errors are not easy to decipher. +> `CArchiveException::generic` is deprecated. Use `genericException` instead. If **`generic`** is used in an application and built with `/clr`, the resulting syntax errors are not easy to decipher. ### Example [!code-cpp[NVC_MFCFiles#30](../../atl-mfc-shared/reference/codesnippet/cpp/cfileexception-class_3.cpp)] -## CFileException::m_lOsError +## `CFileException::m_lOsError` Contains the operating-system error code for this exception. @@ -200,9 +199,9 @@ LONG m_lOsError; ### Remarks -See your operating-system technical manual for a listing of error codes. This data member is a public variable of type LONG. +See your operating-system technical manual for a listing of error codes. This data member is a public variable of type `LONG`. -## CFileException::m_strFileName +## `CFileException::m_strFileName` Contains the name of the file for this exception condition. @@ -210,9 +209,9 @@ Contains the name of the file for this exception condition. CString m_strFileName; ``` -## CFileException::OsErrorToException +## `CFileException::OsErrorToException` -Returns an enumerator that corresponds to a given *lOsError* value. If the error code is unknown, then the function returns `CFileException::generic`. +Returns an enumerator that corresponds to a given *`lOsError`* value. If the error code is unknown, then the function returns `CFileException::generic`. ``` static int PASCAL OsErrorToException(LONG lOsError); @@ -220,7 +219,7 @@ static int PASCAL OsErrorToException(LONG lOsError); ### Parameters -*lOsError*
+*`lOsError`*\ An operating-system-specific error code. ### Return Value @@ -231,9 +230,9 @@ Enumerated value that corresponds to a given operating-system error value. [!code-cpp[NVC_MFCFiles#27](../../atl-mfc-shared/reference/codesnippet/cpp/cfileexception-class_4.cpp)] -## CFileException::ThrowErrno +## `CFileException::ThrowErrno` -Constructs a `CFileException` object corresponding to a given *nErrno* value, then throws the exception. +Constructs a `CFileException` object corresponding to a given *`nErrno`* value, then throws the exception. ``` static void PASCAL ThrowErrno(int nErrno, LPCTSTR lpszFileName = NULL); @@ -241,19 +240,19 @@ static void PASCAL ThrowErrno(int nErrno, LPCTSTR lpszFileName = NULL); ### Parameters -*nErrno*
-An integer error code as defined in the run-time include file ERRNO.H. +*`nErrno`*\ +An integer error code as defined in the run-time include file `ERRNO.H`. -*lpszFileName*
+*`lpszFileName`*\ A pointer to the string containing the name of the file that caused the exception, if available. ### Example [!code-cpp[NVC_MFCFiles#28](../../atl-mfc-shared/reference/codesnippet/cpp/cfileexception-class_5.cpp)] -## CFileException::ThrowOsError +## `CFileException::ThrowOsError` -Throws a `CFileException` corresponding to a given *lOsError* value. If the error code is unknown, then the function throws an exception coded as `CFileException::generic`. +Throws a `CFileException` corresponding to a given *`lOsError`* value. If the error code is unknown, then the function throws an exception coded as `CFileException::generic`. ``` static void PASCAL ThrowOsError(LONG lOsError, LPCTSTR lpszFileName = NULL); @@ -261,10 +260,10 @@ static void PASCAL ThrowOsError(LONG lOsError, LPCTSTR lpszFileName = NULL); ### Parameters -*lOsError*
+*`lOsError`*\ An operating-system-specific error code. -*lpszFileName*
+*`lpszFileName`*\ A pointer to the string containing the name of the file that caused the exception, if available. ### Example @@ -273,6 +272,6 @@ A pointer to the string containing the name of the file that caused the exceptio ## See also -[CException Class](../../mfc/reference/cexception-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[`CException` Class](../../mfc/reference/cexception-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Exception Processing](../../mfc/reference/exception-processing.md) diff --git a/docs/mfc/reference/cfindreplacedialog-class.md b/docs/mfc/reference/cfindreplacedialog-class.md index 4b10589691..e24c9f2471 100644 --- a/docs/mfc/reference/cfindreplacedialog-class.md +++ b/docs/mfc/reference/cfindreplacedialog-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CFindReplaceDialog Class" title: "CFindReplaceDialog Class" -ms.date: "11/04/2016" +description: "Learn more about: CFindReplaceDialog Class" +ms.date: 11/04/2016 f1_keywords: ["CFindReplaceDialog", "AFXDLGS/CFindReplaceDialog", "AFXDLGS/CFindReplaceDialog::CFindReplaceDialog", "AFXDLGS/CFindReplaceDialog::Create", "AFXDLGS/CFindReplaceDialog::FindNext", "AFXDLGS/CFindReplaceDialog::GetFindString", "AFXDLGS/CFindReplaceDialog::GetNotifier", "AFXDLGS/CFindReplaceDialog::GetReplaceString", "AFXDLGS/CFindReplaceDialog::IsTerminating", "AFXDLGS/CFindReplaceDialog::MatchCase", "AFXDLGS/CFindReplaceDialog::MatchWholeWord", "AFXDLGS/CFindReplaceDialog::ReplaceAll", "AFXDLGS/CFindReplaceDialog::ReplaceCurrent", "AFXDLGS/CFindReplaceDialog::SearchDown", "AFXDLGS/CFindReplaceDialog::m_fr"] helpviewer_keywords: ["CFindReplaceDialog [MFC], CFindReplaceDialog", "CFindReplaceDialog [MFC], Create", "CFindReplaceDialog [MFC], FindNext", "CFindReplaceDialog [MFC], GetFindString", "CFindReplaceDialog [MFC], GetNotifier", "CFindReplaceDialog [MFC], GetReplaceString", "CFindReplaceDialog [MFC], IsTerminating", "CFindReplaceDialog [MFC], MatchCase", "CFindReplaceDialog [MFC], MatchWholeWord", "CFindReplaceDialog [MFC], ReplaceAll", "CFindReplaceDialog [MFC], ReplaceCurrent", "CFindReplaceDialog [MFC], SearchDown", "CFindReplaceDialog [MFC], m_fr"] -ms.assetid: 610f0b5d-b398-4ef6-8c05-e9d6641e50a8 --- # CFindReplaceDialog Class @@ -98,7 +97,7 @@ CFindReplaceDialog(); Because the `CFindReplaceDialog` object is a modeless dialog box, you must construct it on the heap by using the **`new`** operator. -During destruction, the framework tries to perform a **delete this** on the pointer to the dialog box. If you created the dialog box on the stack, the **`this`** pointer does not exist and undefined behavior may result. +During destruction, the framework tries to perform a `delete this;` on the pointer to the dialog box. If you created the dialog box on the stack, the **`this`** pointer does not exist and undefined behavior may result. For more information on the construction of `CFindReplaceDialog` objects, see the [CFindReplaceDialog](../../mfc/reference/cfindreplacedialog-class.md) overview. Use the [CFindReplaceDialog::Create](#create) member function to display the dialog box. @@ -142,12 +141,12 @@ Nonzero if the dialog box object was successfully created; otherwise 0. ### Remarks -In order for the parent window to be notified of find/replace requests, you must use the Windows [RegisterWindowMessage](/windows/win32/api/winuser/nf-winuser-registerwindowmessagew) function whose return value is a message number unique to the application's instance. Your frame window should have a message map entry that declares the callback function ( `OnFindReplace` in the example that follows) that handles this registered message. The following code fragment is an example of how to do this for a frame window class named `CMyRichEditView`: +In order for the parent window to be notified of find/replace requests, you must use the Windows [RegisterWindowMessage](/windows/win32/api/winuser/nf-winuser-registerwindowmessagew) function whose return value is a message number unique to the application's instance. Your frame window should have a message map entry that declares the callback function (`OnFindReplace` in the example that follows) that handles this registered message. The following code fragment is an example of how to do this for a frame window class named `CMyRichEditView`: [!code-cpp[NVC_MFCDocView#171](../../mfc/codesnippet/cpp/cfindreplacedialog-class_2.h)] - +  [!code-cpp[NVC_MFCDocView#172](../../mfc/codesnippet/cpp/cfindreplacedialog-class_3.cpp)] - +  [!code-cpp[NVC_MFCDocView#173](../../mfc/codesnippet/cpp/cfindreplacedialog-class_4.cpp)] Within your `OnFindReplace` function, you interpret the intentions of the user by using the [CFindReplaceDialog::FindNext](#findnext) and [CFindReplaceDialog::IsTerminating](#isterminating) methods and you create the code for the find/replace operations. diff --git a/docs/mfc/reference/cfolderpickerdialog-class.md b/docs/mfc/reference/cfolderpickerdialog-class.md index ef92a2edec..de4f2750fa 100644 --- a/docs/mfc/reference/cfolderpickerdialog-class.md +++ b/docs/mfc/reference/cfolderpickerdialog-class.md @@ -4,11 +4,10 @@ title: "CFolderPickerDialog Class" ms.date: "03/27/2019" f1_keywords: ["CFolderPickerDialog", "AFXDLGS/CFolderPickerDialog", "AFXDLGS/CFolderPickerDialog::CFolderPickerDialog"] helpviewer_keywords: ["CFolderPickerDialog [MFC], CFolderPickerDialog"] -ms.assetid: 8db01684-dd1d-4e9c-989e-07a2318a8156 --- -# CFolderPickerDialog Class +# `CFolderPickerDialog` Class -CFolderPickerDialog class implements CFileDialog in the folder picker mode. +`CFolderPickerDialog` class implements `CFileDialog` in the folder picker mode. ## Syntax @@ -22,32 +21,32 @@ class CFolderPickerDialog : public CFileDialog; |Name|Description| |----------|-----------------| -|[CFolderPickerDialog::~CFolderPickerDialog](#_dtorcfolderpickerdialog)|Destructor.| -|[CFolderPickerDialog::CFolderPickerDialog](#cfolderpickerdialog)|Constructor.| +|[`CFolderPickerDialog::~CFolderPickerDialog`](#_dtorcfolderpickerdialog)|Destructor.| +|[`CFolderPickerDialog::CFolderPickerDialog`](#cfolderpickerdialog)|Constructor.| ## Remarks ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) -[CCommonDialog](../../mfc/reference/ccommondialog-class.md) +[`CCommonDialog`](../../mfc/reference/ccommondialog-class.md) -[CFileDialog](../../mfc/reference/cfiledialog-class.md) +[`CFileDialog`](../../mfc/reference/cfiledialog-class.md) `CFolderPickerDialog` ## Requirements -**Header:** afxdlgs.h +**Header:** `afxdlgs.h` -## CFolderPickerDialog::CFolderPickerDialog +## `CFolderPickerDialog::CFolderPickerDialog` Constructor. @@ -61,21 +60,21 @@ explicit CFolderPickerDialog( ### Parameters -*lpszFolder*
+*`lpszFolder`*\ Initial folder. -*dwFlags*
+*`dwFlags`*\ A combination of one or more flags that allow you to customize the dialog box. -*pParentWnd*
+*`pParentWnd`*\ A pointer to the dialog box object's parent or owner window. -*dwSize*
-The size of the OPENFILENAME structure. +*`dwSize`*\ +The size of the `OPENFILENAME` structure. ### Remarks -## CFolderPickerDialog::~CFolderPickerDialog +## `CFolderPickerDialog::~CFolderPickerDialog` Destructor. diff --git a/docs/mfc/reference/cfont-class.md b/docs/mfc/reference/cfont-class.md index 768ca7bd6a..2b22401550 100644 --- a/docs/mfc/reference/cfont-class.md +++ b/docs/mfc/reference/cfont-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CFont Class" title: "CFont Class" -ms.date: "11/04/2016" +description: "Learn more about: CFont Class" +ms.date: 11/04/2016 f1_keywords: ["CFont", "AFXWIN/CFont", "AFXWIN/CFont::CFont", "AFXWIN/CFont::CreateFont", "AFXWIN/CFont::CreateFontIndirect", "AFXWIN/CFont::CreatePointFont", "AFXWIN/CFont::CreatePointFontIndirect", "AFXWIN/CFont::FromHandle", "AFXWIN/CFont::GetLogFont"] helpviewer_keywords: ["CFont [MFC], CFont", "CFont [MFC], CreateFont", "CFont [MFC], CreateFontIndirect", "CFont [MFC], CreatePointFont", "CFont [MFC], CreatePointFontIndirect", "CFont [MFC], FromHandle", "CFont [MFC], GetLogFont"] -ms.assetid: 3fad6bfe-d6ce-4ab9-967a-5ce0aa102800 --- # `CFont` Class @@ -102,7 +101,7 @@ BOOL CreateFont( ### Parameters *`nHeight`*
-Specifies the desired height (in logical units) of the font. See the `lfHeight` member of the [`LOGFONT`](/windows/win32/api/wingdi/ns-wingdi-logfontw)structure in the Windows SDK for a description. The absolute value of *`nHeight`* must not exceed 16,384 device units after it is converted. For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size or the smallest font if all the fonts exceed the requested size. +Specifies the desired height (in logical units) of the font. See the `lfHeight` member of the [`LOGFONT`](/windows/win32/api/wingdi/ns-wingdi-logfontw) structure in the Windows SDK for a description. The absolute value of *`nHeight`* must not exceed 16,384 device units after it is converted. For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size or the smallest font if all the fonts exceed the requested size. *`nWidth`*
Specifies the average width (in logical units) of characters in the font. If *`nWidth`* is 0, the aspect ratio of the device will be matched against the digitization aspect ratio of the available fonts to find the closest match, which is determined by the absolute value of the difference. @@ -173,7 +172,7 @@ When you finish with the `CFont` object created by the `CreateFont` function, us ## `CFont::CreateFontIndirect` -Initializes a `CFont` object with the characteristics given in a [`LOGFONT`](/windows/win32/api/wingdi/ns-wingdi-logfontw)structure. +Initializes a `CFont` object with the characteristics given in a [`LOGFONT`](/windows/win32/api/wingdi/ns-wingdi-logfontw) structure. ``` BOOL CreateFontIndirect(const LOGFONT* lpLogFont); diff --git a/docs/mfc/reference/cformview-class.md b/docs/mfc/reference/cformview-class.md index 6d3eb35e30..2166ba0f16 100644 --- a/docs/mfc/reference/cformview-class.md +++ b/docs/mfc/reference/cformview-class.md @@ -4,9 +4,8 @@ title: "CFormView Class" ms.date: "11/04/2016" f1_keywords: ["CFormView", "AFXEXT/CFormView", "AFXEXT/CFormView::CFormView", "AFXEXT/CFormView::IsInitDlgCompleted"] helpviewer_keywords: ["CFormView [MFC], CFormView", "CFormView [MFC], IsInitDlgCompleted"] -ms.assetid: a99ec313-36f0-4f28-9d2b-de11de14ac19 --- -# CFormView Class +# `CFormView` Class The base class used for form views. @@ -22,43 +21,43 @@ class CFormView : public CScrollView |Name|Description| |----------|-----------------| -|[CFormView::CFormView](#cformview)|Constructs a `CFormView` object.| +|[`CFormView::CFormView`](#cformview)|Constructs a `CFormView` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CFormView::IsInitDlgCompleted](#isinitdlgcompleted)|Used for synchronization during initialization.| +|[`CFormView::IsInitDlgCompleted`](#isinitdlgcompleted)|Used for synchronization during initialization.| ## Remarks -A form view is essentially a view that contains controls. These controls are laid out based on a dialog-template resource. Use `CFormView` if you want forms in your application. These views support scrolling, as needed, using the [CScrollView](../../mfc/reference/cscrollview-class.md) functionality. +A form view is essentially a view that contains controls. These controls are laid out based on a dialog-template resource. Use `CFormView` if you want forms in your application. These views support scrolling, as needed, using the [`CScrollView`](../../mfc/reference/cscrollview-class.md) functionality. -When you are [Creating a Forms-Based Application](../../mfc/reference/creating-a-forms-based-mfc-application.md), you can base its view class on `CFormView`, making it a forms-based application. +When you're [Creating a Forms-Based Application](../../mfc/reference/creating-a-forms-based-mfc-application.md), you can base its view class on `CFormView`, making it a forms-based application. -You can also insert new [Form Topics](../../mfc/form-views-mfc.md) into document-view-based applications. Even if your application did not initially support forms, Visual C++ will add this support when you insert a new form. +You can also insert new [Form Topics](../../mfc/form-views-mfc.md) into document-view-based applications. Even if your application didn't initially support forms, Visual C++ will add this support when you insert a new form. The MFC Application Wizard and the Add Class command are the preferred methods for creating forms-based applications. If you need to create a forms-based application without using these methods, see [Creating a Forms-Based Application](../../mfc/reference/creating-a-forms-based-mfc-application.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CView](../../mfc/reference/cview-class.md) +[`CView`](../../mfc/reference/cview-class.md) -[CScrollView](../../mfc/reference/cscrollview-class.md) +[`CScrollView`](../../mfc/reference/cscrollview-class.md) `CFormView` ## Requirements -**Header:** afxext.h +**Header:** `afxext.h` -## CFormView::CFormView +## `CFormView::CFormView` Constructs a `CFormView` object. @@ -69,17 +68,17 @@ CFormView(UINT nIDTemplate); ### Parameters -*lpszTemplateName*
-Contains a null-terminated string that is the name of a dialog-template resource. +*`lpszTemplateName`*\ +Contains a `NULL`-terminated string that is the name of a dialog-template resource. -*nIDTemplate*
+*`nIDTemplate`*\ Contains the ID number of a dialog-template resource. ### Remarks When you create an object of a type derived from `CFormView`, invoke one of the constructors to create the view object and identify the dialog resource on which the view is based. You can identify the resource either by name (pass a string as the argument to the constructor) or by its ID (pass an unsigned integer as the argument). -The form-view window and child controls are not created until `CWnd::Create` is called. `CWnd::Create` is called by the framework as part of the document and view creation process, which is driven by the document template. +The form-view window and child controls aren't created until `CWnd::Create` is called. `CWnd::Create` is called by the framework as part of the document and view creation process, which is driven by the document template. > [!NOTE] > Your derived class *must* supply its own constructor. In the constructor, invoke the constructor, `CFormView::CFormView`, with the resource name or ID as an argument as shown in the preceding class overview. @@ -87,10 +86,10 @@ The form-view window and child controls are not created until `CWnd::Create` is ### Example [!code-cpp[NVC_MFCDocView#90](../../mfc/codesnippet/cpp/cformview-class_1.h)] - +  [!code-cpp[NVC_MFCDocView#91](../../mfc/codesnippet/cpp/cformview-class_2.cpp)] -## CFormView::IsInitDlgCompleted +## `CFormView::IsInitDlgCompleted` Used by MFC to ensure that initialization is completed before performing other operations. @@ -104,9 +103,8 @@ True if the initialization function for this dialog has completed. ## See also -[MFC Sample SNAPVW](../../overview/visual-cpp-samples.md)
-[MFC Sample VIEWEX](../../overview/visual-cpp-samples.md)
-[CScrollView Class](../../mfc/reference/cscrollview-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md)
-[CScrollView Class](../../mfc/reference/cscrollview-class.md) +[MFC Sample `SNAPVW`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `VIEWEX`](../../overview/visual-cpp-samples.md)\ +[`CScrollView` Class](../../mfc/reference/cscrollview-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CDialog` Class](../../mfc/reference/cdialog-class.md) diff --git a/docs/mfc/reference/cframewnd-class.md b/docs/mfc/reference/cframewnd-class.md index 8460b375a4..c3d7b3aa2b 100644 --- a/docs/mfc/reference/cframewnd-class.md +++ b/docs/mfc/reference/cframewnd-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CFrameWnd Class" title: "CFrameWnd Class" -ms.date: "11/04/2016" +description: "Learn more about: CFrameWnd Class" +ms.date: 11/04/2016 f1_keywords: ["CFrameWnd", "AFXWIN/CFrameWnd", "AFXWIN/CFrameWnd::CFrameWnd", "AFXWIN/CFrameWnd::ActivateFrame", "AFXWIN/CFrameWnd::BeginModalState", "AFXWIN/CFrameWnd::Create", "AFXWIN/CFrameWnd::CreateView", "AFXWIN/CFrameWnd::DockControlBar", "AFXWIN/CFrameWnd::EnableDocking", "AFXWIN/CFrameWnd::EndModalState", "AFXWIN/CFrameWnd::FloatControlBar", "AFXWIN/CFrameWnd::GetActiveDocument", "AFXWIN/CFrameWnd::GetActiveFrame", "AFXWIN/CFrameWnd::GetActiveView", "AFXWIN/CFrameWnd::GetControlBar", "AFXWIN/CFrameWnd::GetDockState", "AFXWIN/CFrameWnd::GetMenuBarState", "AFXWIN/CFrameWnd::GetMenuBarVisibility", "AFXWIN/CFrameWnd::GetMessageBar", "AFXWIN/CFrameWnd::GetMessageString", "AFXWIN/CFrameWnd::GetTitle", "AFXWIN/CFrameWnd::InitialUpdateFrame", "AFXWIN/CFrameWnd::InModalState", "AFXWIN/CFrameWnd::IsTracking", "AFXWIN/CFrameWnd::LoadAccelTable", "AFXWIN/CFrameWnd::LoadBarState", "AFXWIN/CFrameWnd::LoadFrame", "AFXWIN/CFrameWnd::NegotiateBorderSpace", "AFXWIN/CFrameWnd::OnBarCheck", "AFXWIN/CFrameWnd::OnContextHelp", "AFXWIN/CFrameWnd::OnSetPreviewMode", "AFXWIN/CFrameWnd::OnUpdateControlBarMenu", "AFXWIN/CFrameWnd::RecalcLayout", "AFXWIN/CFrameWnd::SaveBarState", "AFXWIN/CFrameWnd::SetActivePreviewView", "AFXWIN/CFrameWnd::SetActiveView", "AFXWIN/CFrameWnd::SetDockState", "AFXWIN/CFrameWnd::SetMenuBarState", "AFXWIN/CFrameWnd::SetMenuBarVisibility", "AFXWIN/CFrameWnd::SetMessageText", "AFXWIN/CFrameWnd::SetProgressBarPosition", "AFXWIN/CFrameWnd::SetProgressBarRange", "AFXWIN/CFrameWnd::SetProgressBarState", "AFXWIN/CFrameWnd::SetTaskbarOverlayIcon", "AFXWIN/CFrameWnd::SetTitle", "AFXWIN/CFrameWnd::ShowControlBar", "AFXWIN/CFrameWnd::ShowOwnedWindows", "AFXWIN/CFrameWnd::OnCreateClient", "AFXWIN/CFrameWnd::OnHideMenuBar", "AFXWIN/CFrameWnd::OnShowMenuBar", "AFXWIN/CFrameWnd::m_bAutoMenuEnable", "AFXWIN/CFrameWnd::rectDefault"] helpviewer_keywords: ["CFrameWnd [MFC], CFrameWnd", "CFrameWnd [MFC], ActivateFrame", "CFrameWnd [MFC], BeginModalState", "CFrameWnd [MFC], Create", "CFrameWnd [MFC], CreateView", "CFrameWnd [MFC], DockControlBar", "CFrameWnd [MFC], EnableDocking", "CFrameWnd [MFC], EndModalState", "CFrameWnd [MFC], FloatControlBar", "CFrameWnd [MFC], GetActiveDocument", "CFrameWnd [MFC], GetActiveFrame", "CFrameWnd [MFC], GetActiveView", "CFrameWnd [MFC], GetControlBar", "CFrameWnd [MFC], GetDockState", "CFrameWnd [MFC], GetMenuBarState", "CFrameWnd [MFC], GetMenuBarVisibility", "CFrameWnd [MFC], GetMessageBar", "CFrameWnd [MFC], GetMessageString", "CFrameWnd [MFC], GetTitle", "CFrameWnd [MFC], InitialUpdateFrame", "CFrameWnd [MFC], InModalState", "CFrameWnd [MFC], IsTracking", "CFrameWnd [MFC], LoadAccelTable", "CFrameWnd [MFC], LoadBarState", "CFrameWnd [MFC], LoadFrame", "CFrameWnd [MFC], NegotiateBorderSpace", "CFrameWnd [MFC], OnBarCheck", "CFrameWnd [MFC], OnContextHelp", "CFrameWnd [MFC], OnSetPreviewMode", "CFrameWnd [MFC], OnUpdateControlBarMenu", "CFrameWnd [MFC], RecalcLayout", "CFrameWnd [MFC], SaveBarState", "CFrameWnd [MFC], SetActivePreviewView", "CFrameWnd [MFC], SetActiveView", "CFrameWnd [MFC], SetDockState", "CFrameWnd [MFC], SetMenuBarState", "CFrameWnd [MFC], SetMenuBarVisibility", "CFrameWnd [MFC], SetMessageText", "CFrameWnd [MFC], SetProgressBarPosition", "CFrameWnd [MFC], SetProgressBarRange", "CFrameWnd [MFC], SetProgressBarState", "CFrameWnd [MFC], SetTaskbarOverlayIcon", "CFrameWnd [MFC], SetTitle", "CFrameWnd [MFC], ShowControlBar", "CFrameWnd [MFC], ShowOwnedWindows", "CFrameWnd [MFC], OnCreateClient", "CFrameWnd [MFC], OnHideMenuBar", "CFrameWnd [MFC], OnShowMenuBar", "CFrameWnd [MFC], m_bAutoMenuEnable", "CFrameWnd [MFC], rectDefault"] -ms.assetid: e2220aba-5bf4-4002-b960-fbcafcad01f1 --- # `CFrameWnd` Class @@ -420,7 +419,7 @@ If there is no active MDI child or the application is a single document interfac ## `CFrameWnd::GetActiveView` -Call this member function to obtain a pointer to the active view (if any) attached to a frame window ( `CFrameWnd`). +Call this member function to obtain a pointer to the active view (if any) attached to a frame window (`CFrameWnd`). ``` CView* GetActiveView() const; @@ -432,7 +431,7 @@ A pointer to the current [`CView`](../../mfc/reference/cview-class.md). If there ### Remarks -This function returns `NULL` when called for an MDI main frame window ( `CMDIFrameWnd`). In an MDI application, the MDI main frame window does not have a view associated with it. Instead, each individual child window ( `CMDIChildWnd`) has one or more associated views. The active view in an MDI application can be obtained by first finding the active MDI child window and then finding the active view for that child window. The active MDI child window can be found by calling the function `MDIGetActive` or `GetActiveFrame` as demonstrated in the following: +This function returns `NULL` when called for an MDI main frame window (`CMDIFrameWnd`). In an MDI application, the MDI main frame window does not have a view associated with it. Instead, each individual child window (`CMDIChildWnd`) has one or more associated views. The active view in an MDI application can be obtained by first finding the active MDI child window and then finding the active view for that child window. The active MDI child window can be found by calling the function `MDIGetActive` or `GetActiveFrame` as demonstrated in the following: [!code-cpp[NVC_MFCWindowing#2](../../mfc/reference/codesnippet/cpp/cframewnd-class_2.cpp)] @@ -512,7 +511,7 @@ This method returns one of the following values: - `AFX_MBV_DISPLAYONFOCUS` (0x02) - The menu is hidden by default. If the menu is hidden, press the ALT key to display the menu and give it the focus. If the menu is displayed, press the ALT or ESC key to hide it. -- `AFX_MBV_ DISPLAYONFOCUS` (0x02) | `AFX_MBV_DISPLAYONF10` (0x04) (bitwise combination (OR)) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. +- `AFX_MBV_ DISPLAYONFOCUS | AFX_MBV_DISPLAYONF10` (0x06) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. ### Remarks @@ -1015,7 +1014,7 @@ virtual void SetMenuBarVisibility(DWORD nStyle); - `AFX_MBV_DISPLAYONFOCUS` (0x02) - The menu is hidden by default. If the menu is hidden, press the ALT key to display the menu and give it the focus. If the menu is displayed, press the ALT or ESC key to hide menu. -- `AFX_MBV_DISPLAYONFOCUS` (0x02) | `AFX_MBV_DISPLAYONF10` (0x04) (bitwise combination (OR)) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. +- `AFX_MBV_DISPLAYONFOCUS | AFX_MBV_DISPLAYONF10` (0x06) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. ### Remarks diff --git a/docs/mfc/reference/cframewndex-class.md b/docs/mfc/reference/cframewndex-class.md index 9118000f73..6c54057b89 100644 --- a/docs/mfc/reference/cframewndex-class.md +++ b/docs/mfc/reference/cframewndex-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: CFrameWndEx Class" title: "CFrameWndEx Class" +description: "Learn more about: CFrameWndEx Class" ms.date: "11/04/2016" f1_keywords: ["CFrameWndEx", "AFXFRAMEWNDEX/CFrameWndEx", "AFXFRAMEWNDEX/CFrameWndEx::ActiveItemRecalcLayout", "AFXFRAMEWNDEX/CFrameWndEx::AddPane", "AFXFRAMEWNDEX/CFrameWndEx::AdjustDockingLayout", "AFXFRAMEWNDEX/CFrameWndEx::DelayUpdateFrameMenu", "AFXFRAMEWNDEX/CFrameWndEx::DockPane", "AFXFRAMEWNDEX/CFrameWndEx::DockPaneLeftOf", "AFXFRAMEWNDEX/CFrameWndEx::EnableAutoHidePanes", "AFXFRAMEWNDEX/CFrameWndEx::EnableDocking", "AFXFRAMEWNDEX/CFrameWndEx::EnableFullScreenMainMenu", "AFXFRAMEWNDEX/CFrameWndEx::EnableFullScreenMode", "AFXFRAMEWNDEX/CFrameWndEx::EnableLoadDockState", "AFXFRAMEWNDEX/CFrameWndEx::EnablePaneMenu", "AFXFRAMEWNDEX/CFrameWndEx::GetActivePopup", "AFXFRAMEWNDEX/CFrameWndEx::GetDefaultResId", "AFXFRAMEWNDEX/CFrameWndEx::GetDockingManager", "AFXFRAMEWNDEX/CFrameWndEx::GetMenuBar", "AFXFRAMEWNDEX/CFrameWndEx::GetPane", "AFXFRAMEWNDEX/CFrameWndEx::GetRibbonBar", "AFXFRAMEWNDEX/CFrameWndEx::GetTearOffBars", "AFXFRAMEWNDEX/CFrameWndEx::GetToolbarButtonToolTipText", "AFXFRAMEWNDEX/CFrameWndEx::InsertPane", "AFXFRAMEWNDEX/CFrameWndEx::IsFullScreen", "AFXFRAMEWNDEX/CFrameWndEx::IsMenuBarAvailable", "AFXFRAMEWNDEX/CFrameWndEx::IsPointNearDockSite", "AFXFRAMEWNDEX/CFrameWndEx::IsPrintPreview", "AFXFRAMEWNDEX/CFrameWndEx::LoadFrame", "AFXFRAMEWNDEX/CFrameWndEx::NegotiateBorderSpace", "AFXFRAMEWNDEX/CFrameWndEx::OnActivate", "AFXFRAMEWNDEX/CFrameWndEx::OnActivateApp", "AFXFRAMEWNDEX/CFrameWndEx::OnChangeVisualManager", "AFXFRAMEWNDEX/CFrameWndEx::OnClose", "AFXFRAMEWNDEX/CFrameWndEx::OnCloseDockingPane", "AFXFRAMEWNDEX/CFrameWndEx::OnCloseMiniFrame", "AFXFRAMEWNDEX/CFrameWndEx::OnClosePopupMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnCmdMsg", "AFXFRAMEWNDEX/CFrameWndEx::OnContextHelp", "AFXFRAMEWNDEX/CFrameWndEx::OnCreate", "AFXFRAMEWNDEX/CFrameWndEx::OnDestroy", "AFXFRAMEWNDEX/CFrameWndEx::OnDrawMenuImage", "AFXFRAMEWNDEX/CFrameWndEx::OnDrawMenuLogo", "AFXFRAMEWNDEX/CFrameWndEx::OnDWMCompositionChanged", "AFXFRAMEWNDEX/CFrameWndEx::OnExitSizeMove", "AFXFRAMEWNDEX/CFrameWndEx::OnGetMinMaxInfo", "AFXFRAMEWNDEX/CFrameWndEx::OnIdleUpdateCmdUI", "AFXFRAMEWNDEX/CFrameWndEx::OnLButtonDown", "AFXFRAMEWNDEX/CFrameWndEx::OnLButtonUp", "AFXFRAMEWNDEX/CFrameWndEx::OnMenuButtonToolHitTest", "AFXFRAMEWNDEX/CFrameWndEx::OnMenuChar", "AFXFRAMEWNDEX/CFrameWndEx::OnMouseMove", "AFXFRAMEWNDEX/CFrameWndEx::OnMoveMiniFrame", "AFXFRAMEWNDEX/CFrameWndEx::OnNcActivate", "AFXFRAMEWNDEX/CFrameWndEx::OnNcCalcSize", "AFXFRAMEWNDEX/CFrameWndEx::OnNcHitTest", "AFXFRAMEWNDEX/CFrameWndEx::OnNcMouseMove", "AFXFRAMEWNDEX/CFrameWndEx::OnNcPaint", "AFXFRAMEWNDEX/CFrameWndEx::OnPaneCheck", "AFXFRAMEWNDEX/CFrameWndEx::OnPostPreviewFrame", "AFXFRAMEWNDEX/CFrameWndEx::OnPowerBroadcast", "AFXFRAMEWNDEX/CFrameWndEx::OnSetMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnSetPreviewMode", "AFXFRAMEWNDEX/CFrameWndEx::OnSetText", "AFXFRAMEWNDEX/CFrameWndEx::OnShowCustomizePane", "AFXFRAMEWNDEX/CFrameWndEx::OnShowPanes", "AFXFRAMEWNDEX/CFrameWndEx::OnShowPopupMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnSize", "AFXFRAMEWNDEX/CFrameWndEx::OnSizing", "AFXFRAMEWNDEX/CFrameWndEx::OnSysColorChange", "AFXFRAMEWNDEX/CFrameWndEx::OnTearOffMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnToolbarContextMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnToolbarCreateNew", "AFXFRAMEWNDEX/CFrameWndEx::OnToolbarDelete", "AFXFRAMEWNDEX/CFrameWndEx::OnUpdateFrameMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnUpdateFrameTitle", "AFXFRAMEWNDEX/CFrameWndEx::OnUpdatePaneMenu", "AFXFRAMEWNDEX/CFrameWndEx::OnWindowPosChanged", "AFXFRAMEWNDEX/CFrameWndEx::PaneFromPoint", "AFXFRAMEWNDEX/CFrameWndEx::PreTranslateMessage", "AFXFRAMEWNDEX/CFrameWndEx::RecalcLayout", "AFXFRAMEWNDEX/CFrameWndEx::RemovePaneFromDockManager", "AFXFRAMEWNDEX/CFrameWndEx::SetDockState", "AFXFRAMEWNDEX/CFrameWndEx::SetPrintPreviewFrame", "AFXFRAMEWNDEX/CFrameWndEx::SetupToolbarMenu", "AFXFRAMEWNDEX/CFrameWndEx::ShowFullScreen", "AFXFRAMEWNDEX/CFrameWndEx::ShowPane", "AFXFRAMEWNDEX/CFrameWndEx::UpdateCaption", "AFXFRAMEWNDEX/CFrameWndEx::WinHelp"] helpviewer_keywords: ["CFrameWndEx [MFC], ActiveItemRecalcLayout", "CFrameWndEx [MFC], AddPane", "CFrameWndEx [MFC], AdjustDockingLayout", "CFrameWndEx [MFC], DelayUpdateFrameMenu", "CFrameWndEx [MFC], DockPane", "CFrameWndEx [MFC], DockPaneLeftOf", "CFrameWndEx [MFC], EnableAutoHidePanes", "CFrameWndEx [MFC], EnableDocking", "CFrameWndEx [MFC], EnableFullScreenMainMenu", "CFrameWndEx [MFC], EnableFullScreenMode", "CFrameWndEx [MFC], EnableLoadDockState", "CFrameWndEx [MFC], EnablePaneMenu", "CFrameWndEx [MFC], GetActivePopup", "CFrameWndEx [MFC], GetDefaultResId", "CFrameWndEx [MFC], GetDockingManager", "CFrameWndEx [MFC], GetMenuBar", "CFrameWndEx [MFC], GetPane", "CFrameWndEx [MFC], GetRibbonBar", "CFrameWndEx [MFC], GetTearOffBars", "CFrameWndEx [MFC], GetToolbarButtonToolTipText", "CFrameWndEx [MFC], InsertPane", "CFrameWndEx [MFC], IsFullScreen", "CFrameWndEx [MFC], IsMenuBarAvailable", "CFrameWndEx [MFC], IsPointNearDockSite", "CFrameWndEx [MFC], IsPrintPreview", "CFrameWndEx [MFC], LoadFrame", "CFrameWndEx [MFC], NegotiateBorderSpace", "CFrameWndEx [MFC], OnActivate", "CFrameWndEx [MFC], OnActivateApp", "CFrameWndEx [MFC], OnChangeVisualManager", "CFrameWndEx [MFC], OnClose", "CFrameWndEx [MFC], OnCloseDockingPane", "CFrameWndEx [MFC], OnCloseMiniFrame", "CFrameWndEx [MFC], OnClosePopupMenu", "CFrameWndEx [MFC], OnCmdMsg", "CFrameWndEx [MFC], OnContextHelp", "CFrameWndEx [MFC], OnCreate", "CFrameWndEx [MFC], OnDestroy", "CFrameWndEx [MFC], OnDrawMenuImage", "CFrameWndEx [MFC], OnDrawMenuLogo", "CFrameWndEx [MFC], OnDWMCompositionChanged", "CFrameWndEx [MFC], OnExitSizeMove", "CFrameWndEx [MFC], OnGetMinMaxInfo", "CFrameWndEx [MFC], OnIdleUpdateCmdUI", "CFrameWndEx [MFC], OnLButtonDown", "CFrameWndEx [MFC], OnLButtonUp", "CFrameWndEx [MFC], OnMenuButtonToolHitTest", "CFrameWndEx [MFC], OnMenuChar", "CFrameWndEx [MFC], OnMouseMove", "CFrameWndEx [MFC], OnMoveMiniFrame", "CFrameWndEx [MFC], OnNcActivate", "CFrameWndEx [MFC], OnNcCalcSize", "CFrameWndEx [MFC], OnNcHitTest", "CFrameWndEx [MFC], OnNcMouseMove", "CFrameWndEx [MFC], OnNcPaint", "CFrameWndEx [MFC], OnPaneCheck", "CFrameWndEx [MFC], OnPostPreviewFrame", "CFrameWndEx [MFC], OnPowerBroadcast", "CFrameWndEx [MFC], OnSetMenu", "CFrameWndEx [MFC], OnSetPreviewMode", "CFrameWndEx [MFC], OnSetText", "CFrameWndEx [MFC], OnShowCustomizePane", "CFrameWndEx [MFC], OnShowPanes", "CFrameWndEx [MFC], OnShowPopupMenu", "CFrameWndEx [MFC], OnSize", "CFrameWndEx [MFC], OnSizing", "CFrameWndEx [MFC], OnSysColorChange", "CFrameWndEx [MFC], OnTearOffMenu", "CFrameWndEx [MFC], OnToolbarContextMenu", "CFrameWndEx [MFC], OnToolbarCreateNew", "CFrameWndEx [MFC], OnToolbarDelete", "CFrameWndEx [MFC], OnUpdateFrameMenu", "CFrameWndEx [MFC], OnUpdateFrameTitle", "CFrameWndEx [MFC], OnUpdatePaneMenu", "CFrameWndEx [MFC], OnWindowPosChanged", "CFrameWndEx [MFC], PaneFromPoint", "CFrameWndEx [MFC], PreTranslateMessage", "CFrameWndEx [MFC], RecalcLayout", "CFrameWndEx [MFC], RemovePaneFromDockManager", "CFrameWndEx [MFC], SetDockState", "CFrameWndEx [MFC], SetPrintPreviewFrame", "CFrameWndEx [MFC], SetupToolbarMenu", "CFrameWndEx [MFC], ShowFullScreen", "CFrameWndEx [MFC], ShowPane", "CFrameWndEx [MFC], UpdateCaption", "CFrameWndEx [MFC], WinHelp"] -ms.assetid: 5830aca8-4a21-4f31-91f1-dd5477ffcc8d --- -# CFrameWndEx Class +# `CFrameWndEx` Class -Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [CFrameWnd](../../mfc/reference/cframewnd-class.md) class. +Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd`](../../mfc/reference/cframewnd-class.md) class. ## Syntax @@ -22,93 +21,93 @@ class CFrameWndEx : public CFrameWnd |Name|Description| |----------|-----------------| -|[CFrameWndEx::ActiveItemRecalcLayout](#activeitemrecalclayout)|Adjusts the layout of the OLE client item and the frame's client area.| -|`CFrameWndEx::AddDockSite`|This method is not used.| -|[CFrameWndEx::AddPane](#addpane)|Registers a control bar with the docking manager.| -|[CFrameWndEx::AdjustDockingLayout](#adjustdockinglayout)|Recalculates the layout of all panes that are docked to the frame window.| -|[CFrameWndEx::DelayUpdateFrameMenu](#delayupdateframemenu)|Sets the frame menu and then updates it when command processing is idle.| -|[CFrameWndEx::DockPane](#dockpane)|Docks the specified pane to the frame window.| -|[CFrameWndEx::DockPaneLeftOf](#dockpaneleftof)|Docks one pane to the left of another pane.| -|[CFrameWndEx::EnableAutoHidePanes](#enableautohidepanes)|Enables the auto-hide mode for the panes when they are docked to the specified sides of the main frame window.| -|[CFrameWndEx::EnableDocking](#enabledocking)|Enables the docking of the panes that belong to the frame window.| -|[CFrameWndEx::EnableFullScreenMainMenu](#enablefullscreenmainmenu)|Shows or hides the main menu in a full screen mode.| -|[CFrameWndEx::EnableFullScreenMode](#enablefullscreenmode)|Enables the full screen mode for the frame window.| -|[CFrameWndEx::EnableLoadDockState](#enableloaddockstate)|Enables or disables the loading of the docking state.| -|[CFrameWndEx::EnablePaneMenu](#enablepanemenu)|Enables or disables the automatic handling of the pane menu.| -|[CFrameWndEx::GetActivePopup](#getactivepopup)|Returns a pointer to the currently displayed pop-up menu.| -|[CFrameWndEx::GetDefaultResId](#getdefaultresid)|Returns the resource ID that you specified when the framework loaded the frame window.| -|[CFrameWndEx::GetDockingManager](#getdockingmanager)|Retrieves the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) object for the frame window.| -|[CFrameWndEx::GetMenuBar](#getmenubar)|Returns a pointer to the menu bar object attached to the frame window.| -|[CFrameWndEx::GetPane](#getpane)|Returns a pointer to the pane that has the specified ID.| -|[CFrameWndEx::GetRibbonBar](#getribbonbar)|Retrieves the ribbon bar control for the frame.| -|[CFrameWndEx::GetTearOffBars](#gettearoffbars)|Returns a list of pane objects that are in a tear-off state.| -|[CFrameWndEx::GetToolbarButtonToolTipText](#gettoolbarbuttontooltiptext)|Called by the framework when the application displays the tooltip for a toolbar button.| -|[CFrameWndEx::InsertPane](#insertpane)|Registers a pane with the docking manager.| -|[CFrameWndEx::IsFullScreen](#isfullscreen)|Determines whether the frame window is in full screen mode.| -|[CFrameWndEx::IsMenuBarAvailable](#ismenubaravailable)|Determines whether the pointer to the menu bar object is valid.| -|[CFrameWndEx::IsPointNearDockSite](#ispointneardocksite)|Indicates whether the point is located in an alignment zone.| -|[CFrameWndEx::IsPrintPreview](#isprintpreview)|Indicates whether the frame window is in print preview mode.| -|[CFrameWndEx::LoadFrame](#loadframe)|This method is called after construction to create the frame window and load its resources.| -|[CFrameWndEx::NegotiateBorderSpace](#negotiateborderspace)|Implements OLE client border negotiation.| -|[CFrameWndEx::OnActivate](#onactivate)|The framework calls this method when user input is switched to or away from the frame.| -|[CFrameWndEx::OnActivateApp](#onactivateapp)|Called by the framework when the application is either selected or deselected.| -|[CFrameWndEx::OnChangeVisualManager](#onchangevisualmanager)|Called by the framework when a change to the frame requires a change to the visual manager.| -|[CFrameWndEx::OnClose](#onclose)|The framework calls this method to close the frame.| -|[CFrameWndEx::OnCloseDockingPane](#onclosedockingpane)|Called by the framework when the user clicks the **Close** button on a docking pane.| -|[CFrameWndEx::OnCloseMiniFrame](#oncloseminiframe)|Called by the framework when the user clicks the **Close** button on a floating mini frame window.| -|[CFrameWndEx::OnClosePopupMenu](#onclosepopupmenu)|Called by the framework when an active pop-up menu processes a WM_DESTROY message.| -|[CFrameWndEx::OnCmdMsg](#oncmdmsg)|Dispatches command messages.| -|[CFrameWndEx::OnContextHelp](#oncontexthelp)|Called by the framework to display context related help.| -|[CFrameWndEx::OnCreate](#oncreate)|Called by the framework after the frame is created.| -|[CFrameWndEx::OnDestroy](#ondestroy)|Called by the framework when the frame is destroyed.| -|[CFrameWndEx::OnDrawMenuImage](#ondrawmenuimage)|Called by the framework when the application draws the image associated with a menu item.| -|[CFrameWndEx::OnDrawMenuLogo](#ondrawmenulogo)|Called by the framework when a `CMFCPopupMenu` object processes a [WM_PAINT](/windows/win32/gdi/wm-paint) message.| -|[CFrameWndEx::OnDWMCompositionChanged](#ondwmcompositionchanged)|Called by the framework when Desktop Window Manager (DWM) composition has been enabled or disabled.| -|[CFrameWndEx::OnExitSizeMove](#onexitsizemove)|Called by the framework when the frame stops moving or resizing.| -|[CFrameWndEx::OnGetMinMaxInfo](#ongetminmaxinfo)|Called by the framework when the frame is resized to set window dimension limits.| -|[CFrameWndEx::OnIdleUpdateCmdUI](#onidleupdatecmdui)|Called by the framework to update the frame display when command processing is idle.| -|[CFrameWndEx::OnLButtonDown](#onlbuttondown)|The framework calls this method when the user presses the left mouse button.| -|[CFrameWndEx::OnLButtonUp](#onlbuttonup)|The framework calls this method when the user releases the left mouse button.| -|[CFrameWndEx::OnMenuButtonToolHitTest](#onmenubuttontoolhittest)|Called by the framework when a `CMFCToolBarButton` object processes a WM_NCHITTEST message.| -|[CFrameWndEx::OnMenuChar](#onmenuchar)|Called by the framework when a menu is displayed and the user presses a key that does not correspond to a command.| -|[CFrameWndEx::OnMouseMove](#onmousemove)|The framework calls this method when the pointer moves.| -|[CFrameWndEx::OnMoveMiniFrame](#onmoveminiframe)|Called by the framework when a pane window moves.| -|[CFrameWndEx::OnNcActivate](#onncactivate)|Called by the framework when the non-client area of the frame must be redrawn to indicate a change in the active state.| -|[CFrameWndEx::OnNcCalcSize](#onnccalcsize)|Called by the framework when the size and position of the client area must be calculated.| -|[CFrameWndEx::OnNcHitTest](#onnchittest)|Called by the framework when the pointer moves or when a mouse button is pressed or released.| -|[CFrameWndEx::OnNcMouseMove](#onncmousemove)|Called by the framework when the pointer moves in a non-client area.| -|[CFrameWndEx::OnNcPaint](#onncpaint)|Called by the framework when the non-client area must be painted.| -|[CFrameWndEx::OnPaneCheck](#onpanecheck)|Called by the framework to control the visibility of a pane.| -|[CFrameWndEx::OnPostPreviewFrame](#onpostpreviewframe)|Called by the framework when the user has changed the print preview mode.| -|[CFrameWndEx::OnPowerBroadcast](#onpowerbroadcast)|Called by the framework when a power management event occurs.| -|[CFrameWndEx::OnSetMenu](#onsetmenu)|Called by the framework to replace the frame window menu.| -|[CFrameWndEx::OnSetPreviewMode](#onsetpreviewmode)|Called by the framework to set the print preview mode for the frame.| -|[CFrameWndEx::OnSetText](#onsettext)|Called by the framework to set the text of a window.| -|[CFrameWndEx::OnShowCustomizePane](#onshowcustomizepane)|Called by the framework when a quick customize pane is enabled.| -|[CFrameWndEx::OnShowPanes](#onshowpanes)|Called by the framework to show or hide panes.| -|[CFrameWndEx::OnShowPopupMenu](#onshowpopupmenu)|Called by the framework when a pop-up menu is enabled.| -|[CFrameWndEx::OnSize](#onsize)|The framework calls this method after the frame's size changes.| -|[CFrameWndEx::OnSizing](#onsizing)|The framework calls this method when the user resizes the frame.| -|[CFrameWndEx::OnSysColorChange](#onsyscolorchange)|Called by the framework when the system colors change.| -|[CFrameWndEx::OnTearOffMenu](#ontearoffmenu)|Called by the framework when a menu that has a tear-off bar is enabled.| -|[CFrameWndEx::OnToolbarContextMenu](#ontoolbarcontextmenu)|Called by the framework to build a toolbar context menu.| -|[CFrameWndEx::OnToolbarCreateNew](#ontoolbarcreatenew)|The framework calls this method to create a new toolbar.| -|[CFrameWndEx::OnToolbarDelete](#ontoolbardelete)|Called by the framework when a toolbar is deleted.| -|[CFrameWndEx::OnUpdateFrameMenu](#onupdateframemenu)|Called by the framework to set the frame menu.| -|[CFrameWndEx::OnUpdateFrameTitle](#onupdateframetitle)|The framework calls this method to update the title bar of the frame window.| -|[CFrameWndEx::OnUpdatePaneMenu](#onupdatepanemenu)|Called by the framework to update the pane menu.| -|[CFrameWndEx::OnWindowPosChanged](#onwindowposchanged)|Called by the framework when the frame size, position, or z-order has changed because of a call to a window management method.| -|[CFrameWndEx::PaneFromPoint](#panefrompoint)|Returns the docking pane that contains the specified point.| -|[CFrameWndEx::PreTranslateMessage](#pretranslatemessage)|Handles specific window messages before they are dispatched.| -|[CFrameWndEx::RecalcLayout](#recalclayout)|Adjusts the layout of the frame and its child windows.| -|[CFrameWndEx::RemovePaneFromDockManager](#removepanefromdockmanager)|Unregisters a pane and removes it from the internal list in the docking manager.| -|[CFrameWndEx::SetDockState](#setdockstate)|Restores the docking layout to the docking state stored in the registry.| -|[CFrameWndEx::SetPrintPreviewFrame](#setprintpreviewframe)|Sets the print preview frame window.| -|[CFrameWndEx::SetupToolbarMenu](#setuptoolbarmenu)|Inserts user-defined commands into a toolbar menu.| -|[CFrameWndEx::ShowFullScreen](#showfullscreen)|Switches the main frame between the full screen and the regular modes.| -|[CFrameWndEx::ShowPane](#showpane)|Shows or hides the specified pane.| -|[CFrameWndEx::UpdateCaption](#updatecaption)|Called by the framework to update the window frame caption.| -|[CFrameWndEx::WinHelp](#winhelp)|Invokes either the `WinHelp` application or context related help.| +|[`CFrameWndEx::ActiveItemRecalcLayout`](#activeitemrecalclayout)|Adjusts the layout of the OLE client item and the frame's client area.| +|`CFrameWndEx::AddDockSite`|This method isn't used.| +|[`CFrameWndEx::AddPane`](#addpane)|Registers a control bar with the docking manager.| +|[`CFrameWndEx::AdjustDockingLayout`](#adjustdockinglayout)|Recalculates the layout of all panes that are docked to the frame window.| +|[`CFrameWndEx::DelayUpdateFrameMenu`](#delayupdateframemenu)|Sets the frame menu and then updates it when command processing is idle.| +|[`CFrameWndEx::DockPane`](#dockpane)|Docks the specified pane to the frame window.| +|[`CFrameWndEx::DockPaneLeftOf`](#dockpaneleftof)|Docks one pane to the left of another pane.| +|[`CFrameWndEx::EnableAutoHidePanes`](#enableautohidepanes)|Enables the auto-hide mode for the panes when they're docked to the specified sides of the main frame window.| +|[`CFrameWndEx::EnableDocking`](#enabledocking)|Enables the docking of the panes that belong to the frame window.| +|[`CFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu)|Shows or hides the main menu in a full screen mode.| +|[`CFrameWndEx::EnableFullScreenMode`](#enablefullscreenmode)|Enables the full screen mode for the frame window.| +|[`CFrameWndEx::EnableLoadDockState`](#enableloaddockstate)|Enables or disables the loading of the docking state.| +|[`CFrameWndEx::EnablePaneMenu`](#enablepanemenu)|Enables or disables the automatic handling of the pane menu.| +|[`CFrameWndEx::GetActivePopup`](#getactivepopup)|Returns a pointer to the currently displayed pop-up menu.| +|[`CFrameWndEx::GetDefaultResId`](#getdefaultresid)|Returns the resource ID that you specified when the framework loaded the frame window.| +|[`CFrameWndEx::GetDockingManager`](#getdockingmanager)|Retrieves the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) object for the frame window.| +|[`CFrameWndEx::GetMenuBar`](#getmenubar)|Returns a pointer to the menu bar object attached to the frame window.| +|[`CFrameWndEx::GetPane`](#getpane)|Returns a pointer to the pane that has the specified ID.| +|[`CFrameWndEx::GetRibbonBar`](#getribbonbar)|Retrieves the ribbon bar control for the frame.| +|[`CFrameWndEx::GetTearOffBars`](#gettearoffbars)|Returns a list of pane objects that are in a tear-off state.| +|[`CFrameWndEx::GetToolbarButtonToolTipText`](#gettoolbarbuttontooltiptext)|Called by the framework when the application displays the tooltip for a toolbar button.| +|[`CFrameWndEx::InsertPane`](#insertpane)|Registers a pane with the docking manager.| +|[`CFrameWndEx::IsFullScreen`](#isfullscreen)|Determines whether the frame window is in full screen mode.| +|[`CFrameWndEx::IsMenuBarAvailable`](#ismenubaravailable)|Determines whether the pointer to the menu bar object is valid.| +|[`CFrameWndEx::IsPointNearDockSite`](#ispointneardocksite)|Indicates whether the point is located in an alignment zone.| +|[`CFrameWndEx::IsPrintPreview`](#isprintpreview)|Indicates whether the frame window is in print preview mode.| +|[`CFrameWndEx::LoadFrame`](#loadframe)|This method is called after construction to create the frame window and load its resources.| +|[`CFrameWndEx::NegotiateBorderSpace`](#negotiateborderspace)|Implements OLE client border negotiation.| +|[`CFrameWndEx::OnActivate`](#onactivate)|The framework calls this method when user input is switched to or away from the frame.| +|[`CFrameWndEx::OnActivateApp`](#onactivateapp)|Called by the framework when the application is either selected or deselected.| +|[`CFrameWndEx::OnChangeVisualManager`](#onchangevisualmanager)|Called by the framework when a change to the frame requires a change to the visual manager.| +|[`CFrameWndEx::OnClose`](#onclose)|The framework calls this method to close the frame.| +|[`CFrameWndEx::OnCloseDockingPane`](#onclosedockingpane)|Called by the framework when the user clicks the **Close** button on a docking pane.| +|[`CFrameWndEx::OnCloseMiniFrame`](#oncloseminiframe)|Called by the framework when the user clicks the **Close** button on a floating mini frame window.| +|[`CFrameWndEx::OnClosePopupMenu`](#onclosepopupmenu)|Called by the framework when an active pop-up menu processes a `WM_DESTROY` message.| +|[`CFrameWndEx::OnCmdMsg`](#oncmdmsg)|Dispatches command messages.| +|[`CFrameWndEx::OnContextHelp`](#oncontexthelp)|Called by the framework to display context related help.| +|[`CFrameWndEx::OnCreate`](#oncreate)|Called by the framework after the frame is created.| +|[`CFrameWndEx::OnDestroy`](#ondestroy)|Called by the framework when the frame is destroyed.| +|[`CFrameWndEx::OnDrawMenuImage`](#ondrawmenuimage)|Called by the framework when the application draws the image associated with a menu item.| +|[`CFrameWndEx::OnDrawMenuLogo`](#ondrawmenulogo)|Called by the framework when a `CMFCPopupMenu` object processes a [`WM_PAINT`](/windows/win32/gdi/wm-paint) message.| +|[`CFrameWndEx::OnDWMCompositionChanged`](#ondwmcompositionchanged)|Called by the framework when Desktop Window Manager (DWM) composition has been enabled or disabled.| +|[`CFrameWndEx::OnExitSizeMove`](#onexitsizemove)|Called by the framework when the frame stops moving or resizing.| +|[`CFrameWndEx::OnGetMinMaxInfo`](#ongetminmaxinfo)|Called by the framework when the frame is resized to set window dimension limits.| +|[`CFrameWndEx::OnIdleUpdateCmdUI`](#onidleupdatecmdui)|Called by the framework to update the frame display when command processing is idle.| +|[`CFrameWndEx::OnLButtonDown`](#onlbuttondown)|The framework calls this method when the user presses the left mouse button.| +|[`CFrameWndEx::OnLButtonUp`](#onlbuttonup)|The framework calls this method when the user releases the left mouse button.| +|[`CFrameWndEx::OnMenuButtonToolHitTest`](#onmenubuttontoolhittest)|Called by the framework when a `CMFCToolBarButton` object processes a `WM_NCHITTEST` message.| +|[`CFrameWndEx::OnMenuChar`](#onmenuchar)|Called by the framework when a menu is displayed and the user presses a key that doesn't correspond to a command.| +|[`CFrameWndEx::OnMouseMove`](#onmousemove)|The framework calls this method when the pointer moves.| +|[`CFrameWndEx::OnMoveMiniFrame`](#onmoveminiframe)|Called by the framework when a pane window moves.| +|[`CFrameWndEx::OnNcActivate`](#onncactivate)|Called by the framework when the non-client area of the frame must be redrawn to indicate a change in the active state.| +|[`CFrameWndEx::OnNcCalcSize`](#onnccalcsize)|Called by the framework when the size and position of the client area must be calculated.| +|[`CFrameWndEx::OnNcHitTest`](#onnchittest)|Called by the framework when the pointer moves or when a mouse button is pressed or released.| +|[`CFrameWndEx::OnNcMouseMove`](#onncmousemove)|Called by the framework when the pointer moves in a non-client area.| +|[`CFrameWndEx::OnNcPaint`](#onncpaint)|Called by the framework when the non-client area must be painted.| +|[`CFrameWndEx::OnPaneCheck`](#onpanecheck)|Called by the framework to control the visibility of a pane.| +|[`CFrameWndEx::OnPostPreviewFrame`](#onpostpreviewframe)|Called by the framework when the user has changed the print preview mode.| +|[`CFrameWndEx::OnPowerBroadcast`](#onpowerbroadcast)|Called by the framework when a power management event occurs.| +|[`CFrameWndEx::OnSetMenu`](#onsetmenu)|Called by the framework to replace the frame window menu.| +|[`CFrameWndEx::OnSetPreviewMode`](#onsetpreviewmode)|Called by the framework to set the print preview mode for the frame.| +|[`CFrameWndEx::OnSetText`](#onsettext)|Called by the framework to set the text of a window.| +|[`CFrameWndEx::OnShowCustomizePane`](#onshowcustomizepane)|Called by the framework when a quick customize pane is enabled.| +|[`CFrameWndEx::OnShowPanes`](#onshowpanes)|Called by the framework to show or hide panes.| +|[`CFrameWndEx::OnShowPopupMenu`](#onshowpopupmenu)|Called by the framework when a pop-up menu is enabled.| +|[`CFrameWndEx::OnSize`](#onsize)|The framework calls this method after the frame's size changes.| +|[`CFrameWndEx::OnSizing`](#onsizing)|The framework calls this method when the user resizes the frame.| +|[`CFrameWndEx::OnSysColorChange`](#onsyscolorchange)|Called by the framework when the system colors change.| +|[`CFrameWndEx::OnTearOffMenu`](#ontearoffmenu)|Called by the framework when a menu that has a tear-off bar is enabled.| +|[`CFrameWndEx::OnToolbarContextMenu`](#ontoolbarcontextmenu)|Called by the framework to build a toolbar context menu.| +|[`CFrameWndEx::OnToolbarCreateNew`](#ontoolbarcreatenew)|The framework calls this method to create a new toolbar.| +|[`CFrameWndEx::OnToolbarDelete`](#ontoolbardelete)|Called by the framework when a toolbar is deleted.| +|[`CFrameWndEx::OnUpdateFrameMenu`](#onupdateframemenu)|Called by the framework to set the frame menu.| +|[`CFrameWndEx::OnUpdateFrameTitle`](#onupdateframetitle)|The framework calls this method to update the title bar of the frame window.| +|[`CFrameWndEx::OnUpdatePaneMenu`](#onupdatepanemenu)|Called by the framework to update the pane menu.| +|[`CFrameWndEx::OnWindowPosChanged`](#onwindowposchanged)|Called by the framework when the frame size, position, or z-order has changed because of a call to a window management method.| +|[`CFrameWndEx::PaneFromPoint`](#panefrompoint)|Returns the docking pane that contains the specified point.| +|[`CFrameWndEx::PreTranslateMessage`](#pretranslatemessage)|Handles specific window messages before they're dispatched.| +|[`CFrameWndEx::RecalcLayout`](#recalclayout)|Adjusts the layout of the frame and its child windows.| +|[`CFrameWndEx::RemovePaneFromDockManager`](#removepanefromdockmanager)|Unregisters a pane and removes it from the internal list in the docking manager.| +|[`CFrameWndEx::SetDockState`](#setdockstate)|Restores the docking layout to the docking state stored in the registry.| +|[`CFrameWndEx::SetPrintPreviewFrame`](#setprintpreviewframe)|Sets the print preview frame window.| +|[`CFrameWndEx::SetupToolbarMenu`](#setuptoolbarmenu)|Inserts user-defined commands into a toolbar menu.| +|[`CFrameWndEx::ShowFullScreen`](#showfullscreen)|Switches the main frame between the full screen and the regular modes.| +|[`CFrameWndEx::ShowPane`](#showpane)|Shows or hides the specified pane.| +|[`CFrameWndEx::UpdateCaption`](#updatecaption)|Called by the framework to update the window frame caption.| +|[`CFrameWndEx::WinHelp`](#winhelp)|Invokes either the `WinHelp` application or context related help.| ## Example @@ -119,21 +118,21 @@ The following example demonstrates how to inherit a class from the `CFrameWndEx` ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CFrameWnd](../../mfc/reference/cframewnd-class.md) +[`CFrameWnd`](../../mfc/reference/cframewnd-class.md) -[CFrameWndEx](../../mfc/reference/cframewndex-class.md) +[`CFrameWndEx`](../../mfc/reference/cframewndex-class.md) ## Requirements -**Header:** afxframewndex.h +**Header:** `afxframewndex.h` -## CFrameWndEx::ActiveItemRecalcLayout +## `CFrameWndEx::ActiveItemRecalcLayout` Adjusts the layout of the OLE client item and the frame's client area. @@ -143,7 +142,7 @@ void ActiveItemRecalcLayout(); ### Remarks -## CFrameWndEx::AddPane +## `CFrameWndEx::AddPane` Registers a control bar with the docking manager. @@ -155,17 +154,17 @@ BOOL AddPane( ### Parameters -*pControlBar*
+*`pControlBar`*\ [in] A control bar pane to register. -*bTail*
-[in] TRUE if you want to add the control bar pane to the end of the list; FALSE otherwise. +*`bTail`*\ +[in] `TRUE` if you want to add the control bar pane to the end of the list; `FALSE` otherwise. ### Return Value -TRUE if the control bar was successfully registered; FALSE otherwise. +`TRUE` if the control bar was successfully registered; `FALSE` otherwise. -## CFrameWndEx::AdjustDockingLayout +## `CFrameWndEx::AdjustDockingLayout` Recalculates the layout of all panes that are docked to the frame window. @@ -175,14 +174,14 @@ virtual void AdjustDockingLayout(HDWP hdwp=NULL); ### Parameters -*hdwp*
+*`hdwp`*\ A handle to a structure that contains the positions of multiple windows. . ### Remarks -The hdwp structure is initialized by the [BeginDeferWindowPos](/windows/win32/api/winuser/nf-winuser-begindeferwindowpos) method. +The hdwp structure is initialized by the [`BeginDeferWindowPos`](/windows/win32/api/winuser/nf-winuser-begindeferwindowpos) method. -## CFrameWndEx::DelayUpdateFrameMenu +## `CFrameWndEx::DelayUpdateFrameMenu` Sets the frame menu and then updates it when command processing is idle. @@ -192,12 +191,12 @@ virtual void DelayUpdateFrameMenu(HMENU hMenuAlt); ### Parameters -*hMenuAlt*
+*`hMenuAlt`*\ [in] Handle to an alternative menu. ### Remarks -## CFrameWndEx::DockPane +## `CFrameWndEx::DockPane` Docks the specified pane to the frame window. @@ -210,28 +209,28 @@ void DockPane( ### Parameters -*pBar*
+*`pBar`*\ [in] A pointer to the control bar to be docked. -*nDockBarID*
+*`nDockBarID`*\ [in] The ID of the side of the frame window to dock to. -*lpRect*
-[in] A pointer to a constant Rect structure that specifies the window's screen position and size. +*`lpRect`*\ +[in] A pointer to a constant `Rect` structure that specifies the window's screen position and size. ### Remarks -The *nDockBarID* parameter can have one of the following values: +The *`nDockBarID`* parameter can have one of the following values: -- AFX_IDW_DOCKBAR_TOP +- `AFX_IDW_DOCKBAR_TOP` -- AFX_IDW_DOCKBAR_BOTTOM +- `AFX_IDW_DOCKBAR_BOTTOM` -- AFX_IDW_DOCKBAR_LEFT +- `AFX_IDW_DOCKBAR_LEFT` -- AFX_IDW_DOCKBAR_RIGHT +- `AFX_IDW_DOCKBAR_RIGHT` -## CFrameWndEx::DockPaneLeftOf +## `CFrameWndEx::DockPaneLeftOf` Docks the specified pane to the left of another pane. @@ -243,23 +242,23 @@ BOOL DockPaneLeftOf( ### Parameters -*pBar*
+*`pBar`*\ [in] A pointer to the pane object to be docked. -*pLeftOf*
-[in] A pointer to the pane to the left of which to dock the pane specified by *pBar*. +*`pLeftOf`*\ +[in] A pointer to the pane to the left of which to dock the pane specified by *`pBar`*. ### Return Value -TRUE if *pBar* is docked successfully. FALSE otherwise. +`TRUE` if *`pBar`* is docked successfully. `FALSE` otherwise. ### Remarks -The method takes the toolbar specified by the *pBar* parameter and docks it at the left side of the toolbar specified by *pLeftOf* parameter. +The method takes the toolbar specified by the *`pBar`* parameter and docks it at the left side of the toolbar specified by *`pLeftOf`* parameter. -## CFrameWndEx::EnableAutoHidePanes +## `CFrameWndEx::EnableAutoHidePanes` -Enables auto-hide mode for the pane when it is docked to the specified side of the main frame window. +Enables auto-hide mode for the pane when it's docked to the specified side of the main frame window. ``` BOOL EnableAutoHidePanes(DWORD dwDockStyle); @@ -267,26 +266,26 @@ BOOL EnableAutoHidePanes(DWORD dwDockStyle); ### Parameters -*dwDockStyle*
+*`dwDockStyle`*\ [in] Specifies the side of the main frame window to which to dock the pane. ### Return Value -TRUE if a bar pane is successfully docked to the frame window side that is specified by *dwDockStyle*, FALSE otherwise. +`TRUE` if a bar pane is successfully docked to the frame window side that is specified by *`dwDockStyle`*, `FALSE` otherwise. ### Remarks -*dwDockStyle* can have one of the following values: +*`dwDockStyle`* can have one of the following values: -- CBRS_ALIGN_TOP: allows the control bar to be docked to the top of the client area of a frame window. +- `CBRS_ALIGN_TOP`: allows the control bar to be docked to the top of the client area of a frame window. -- CBRS_ALIGN_BOTTOM: allows the control bar to be docked to the bottom of the client area of a frame window. +- `CBRS_ALIGN_BOTTOM`: allows the control bar to be docked to the bottom of the client area of a frame window. -- CBRS_ALIGN_LEFT: allows the control bar to be docked to the left side of the client area of a frame window. +- `CBRS_ALIGN_LEFT`: allows the control bar to be docked to the left side of the client area of a frame window. -- CBRS_ALIGN_RIGHT: allows the control bar to be docked to the right side of the client area of a frame window. +- `CBRS_ALIGN_RIGHT`: allows the control bar to be docked to the right side of the client area of a frame window. -## CFrameWndEx::EnableDocking +## `CFrameWndEx::EnableDocking` Enables the docking of the panes of the frame window. @@ -296,26 +295,26 @@ BOOL EnableDocking(DWORD dwDockStyle); ### Parameters -*dwDockStyle*
+*`dwDockStyle`*\ [in] Specifies the side of the main frame window where the pane bar docks. ### Return Value -TRUE if a bar pane can be successfully docked at the specified side. FALSE otherwise. +`TRUE` if a bar pane can be successfully docked at the specified side. `FALSE` otherwise. ### Remarks -The *dwDockStyle* parameter can have one of the following values: +The *`dwDockStyle`* parameter can have one of the following values: -- CBRS_ALIGN_TOP +- `CBRS_ALIGN_TOP` -- CBRS_ALIGN_BOTTOM +- `CBRS_ALIGN_BOTTOM` -- CBRS_ALIGN_LEFT +- `CBRS_ALIGN_LEFT` -- CBRS_ALIGN_RIGHT +- `CBRS_ALIGN_RIGHT` -## CFrameWndEx::EnableFullScreenMainMenu +## `CFrameWndEx::EnableFullScreenMainMenu` Shows or hides the main menu in a full screen mode. @@ -325,10 +324,10 @@ void EnableFullScreenMainMenu(BOOL bEnableMenu); ### Parameters -*bEnableMenu*
-[in] TRUE to show the main menu in a full screen mode, FALSE otherwise. +*`bEnableMenu`*\ +[in] `TRUE` to show the main menu in a full screen mode, `FALSE` otherwise. -## CFrameWndEx::EnableFullScreenMode +## `CFrameWndEx::EnableFullScreenMode` Enables the full-screen mode for the frame window. @@ -338,7 +337,7 @@ void EnableFullScreenMode(UINT uiFullScreenCmd); ### Parameters -*uiFullScreenCmd*
+*`uiFullScreenCmd`*\ [in] The ID of a command that enables and disables the full screen mode. ### Remarks @@ -347,9 +346,9 @@ In the full-screen mode, all docking control bars, toolbars and menu are hidden When you enable the full-screen mode, you must specify an ID of the command that enables or disables the full-screen mode. You can call `EnableFullScreenMode` from the main frame's `OnCreate` function. When a frame window is being switched to a full-screen mode, the framework creates a floating toolbar with one button that has the specified command ID. -If you want to keep the main menu on the screen, call [CFrameWndEx::EnableFullScreenMainMenu](#enablefullscreenmainmenu). +If you want to keep the main menu on the screen, call [`CFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu). -## CFrameWndEx::EnableLoadDockState +## `CFrameWndEx::EnableLoadDockState` Enables or disables the loading of the docking state. @@ -359,10 +358,10 @@ void EnableLoadDockState(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the loading of the docking state, FALSE to disable the loading of the docking state. +*`bEnable`*\ +[in] `TRUE` to enable the loading of the docking state, `FALSE` to disable the loading of the docking state. -## CFrameWndEx::EnablePaneMenu +## `CFrameWndEx::EnablePaneMenu` Enables or disables the automatic handling of the pane menu. @@ -378,25 +377,25 @@ void EnablePaneMenu( ### Parameters -*bEnable*
-[in] TRUE to enable the automatic handling of the control bar pop-up menus; FALSE to disable the automatic handling of the control bar pop-up menus. +*`bEnable`*\ +[in] `TRUE` to enable the automatic handling of the control bar pop-up menus; `FALSE` to disable the automatic handling of the control bar pop-up menus. -*uiCustomizeCmd*
+*`uiCustomizeCmd`*\ [in] The command ID of the **Customize** menu item. -*strCustomizeLabel*
+*`strCustomizeLabel`*\ [in] The label to be displayed for the **Customize** menu item -*uiViewToolbarsMenuEntryID*
+*`uiViewToolbarsMenuEntryID`*\ [in] The ID of a toolbar menu item that opens the pop-up menu in the control bar. -*bContextMenuShowsToolbarsOnly*
-[in] If TRUE, the control bar context menu displays the list of toolbars only. If FALSE, the menu displays the list of the toolbars and the docking bars. +*`bContextMenuShowsToolbarsOnly`*\ +[in] If `TRUE`, the control bar context menu displays the list of toolbars only. If `FALSE`, the menu displays the list of the toolbars and the docking bars. -*bViewMenuShowsToolbarsOnly*
-[in] If TRUE, the control bar menu displays the list of the toolbars only. If FALSE, the menu displays the list of the toolbars and the docking bars. +*`bViewMenuShowsToolbarsOnly`*\ +[in] If `TRUE`, the control bar menu displays the list of the toolbars only. If `FALSE`, the menu displays the list of the toolbars and the docking bars. -## CFrameWndEx::GetActivePopup +## `CFrameWndEx::GetActivePopup` Returns a pointer to the currently displayed pop-up menu. @@ -406,9 +405,9 @@ CMFCPopupMenu* GetActivePopup() const; ### Return Value -A pointer to the currently displayed pop-up menu; otherwise NULL. +A pointer to the currently displayed pop-up menu; otherwise `NULL`. -## CFrameWndEx::GetDefaultResId +## `CFrameWndEx::GetDefaultResId` Returns the resource ID that you specified when the framework loaded the frame window. @@ -418,11 +417,11 @@ UINT GetDefaultResId() const; ### Return Value -The resource ID value that the user specified when the framework loaded the frame window. Zero if the frame window does not have a menu bar. +The resource ID value that the user specified when the framework loaded the frame window. Zero if the frame window doesn't have a menu bar. -## CFrameWndEx::GetDockingManager +## `CFrameWndEx::GetDockingManager` -Retrieves the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) object for the frame window. +Retrieves the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) object for the frame window. ``` CDockingManager* GetDockingManager(); @@ -430,13 +429,13 @@ CDockingManager* GetDockingManager(); ### Return Value -A pointer to the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md). +A pointer to the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md). ### Remarks -The frame window creates and uses a [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) object to manage child window docking. +The frame window creates and uses a [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) object to manage child window docking. -## CFrameWndEx::GetMenuBar +## `CFrameWndEx::GetMenuBar` Returns a pointer to the menu bar object attached to the frame window. @@ -448,7 +447,7 @@ const CMFCMenuBar* GetMenuBar() const; A pointer to the menu bar object attached to the frame window. -## CFrameWndEx::GetPane +## `CFrameWndEx::GetPane` Returns a pointer to the pane that has the specified ID. @@ -458,14 +457,14 @@ CBasePane* GetPane(UINT nID); ### Parameters -*nID*
+*`nID`*\ [in] The control ID. ### Return Value -A pointer to the pane that has the specified ID. NULL if no such pane exists. +A pointer to the pane that has the specified ID. `NULL` if no such pane exists. -## CFrameWndEx::GetRibbonBar +## `CFrameWndEx::GetRibbonBar` Retrieves the ribbon bar control for the frame. @@ -475,11 +474,11 @@ CMFCRibbonBar* GetRibbonBar(); ### Return Value -Pointer to the [CMFCRibbonBar Class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. +Pointer to the [`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. ### Remarks -## CFrameWndEx::GetTearOffBars +## `CFrameWndEx::GetTearOffBars` Returns a list of pane objects that are in a tear-off state. @@ -491,7 +490,7 @@ const CObList& GetTearOffBars() const; A reference to `CObList` object that contains a collection of pointers to the pane objects that are in a tear-off state. -## CFrameWndEx::GetToolbarButtonToolTipText +## `CFrameWndEx::GetToolbarButtonToolTipText` Called by the framework when the application displays the tooltip for a toolbar button. @@ -503,21 +502,21 @@ virtual BOOL GetToolbarButtonToolTipText( ### Parameters -*pButton*
+*`pButton`*\ [in] A pointer to a toolbar button. -*strTTText*
+*`strTTText`*\ [in] The tooltip text to display for the button. ### Return Value -TRUE if the tooltip has been displayed. FALSE otherwise. +`TRUE` if the tooltip has been displayed. `FALSE` otherwise. ### Remarks By default, this method does nothing. Override this method if you want to display the tooltip for the toolbar button. -## CFrameWndEx::InsertPane +## `CFrameWndEx::InsertPane` Inserts a pane into a list of control bars and registers it with the docking manager. @@ -530,24 +529,24 @@ BOOL InsertPane( ### Parameters -*pControlBar*
+*`pControlBar`*\ A pointer to a control bar to be inserted into the list of control bars and registered with the docking manager. -*pTarget*
+*`pTarget`*\ A pointer to a control bar before or after which to insert the pane. -*bAfter*
-TRUE if you want to insert *pControlBar* after *pTarget*, FALSE otherwise. +*`bAfter`*\ +`TRUE` if you want to insert *`pControlBar`* after *`pTarget`*, `FALSE` otherwise. ### Return Value -TRUE if the control bar was successfully inserted and registered, FALSE otherwise. +`TRUE` if the control bar was successfully inserted and registered, `FALSE` otherwise. ### Remarks -You must register each control bar by using the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) to take a part in the docking layout. +You must register each control bar by using the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) to take a part in the docking layout. -## CFrameWndEx::IsFullScreen +## `CFrameWndEx::IsFullScreen` Determines whether the frame window is in full screen mode. @@ -557,13 +556,13 @@ BOOL IsFullScreen() const; ### Return Value -TRUE if the frame window is in full screen mode; otherwise FALSE. +`TRUE` if the frame window is in full screen mode; otherwise `FALSE`. ### Remarks -You can set the full screen mode by calling the [CFrameWndEx::EnableFullScreenMode](#enablefullscreenmode) method. +You can set the full screen mode by calling the [`CFrameWndEx::EnableFullScreenMode`](#enablefullscreenmode) method. -## CFrameWndEx::IsMenuBarAvailable +## `CFrameWndEx::IsMenuBarAvailable` Determines whether the pointer to the menu bar object is valid. @@ -573,9 +572,9 @@ BOOL IsMenuBarAvailable() const; ### Return Value -TRUE if the frame window has a menu bar; otherwise FALSE. +`TRUE` if the frame window has a menu bar; otherwise `FALSE`. -## CFrameWndEx::IsPointNearDockSite +## `CFrameWndEx::IsPointNearDockSite` Determines whether the point is located in an alignment zone. @@ -588,31 +587,31 @@ BOOL IsPointNearDockSite( ### Parameters -*point*
+*`point`*\ [in] The position of the point. -*dwBarAlignment*
-[out] Where the point is aligned. See the table in the Remarks section for possible values. +*`dwBarAlignment`*\ +[out] Where the point is aligned. See the table in the [Remarks](#ispointneardocksite-remarks) section for possible values. -*bOuterEdge*
-[out] TRUE if the point is located close to the frame border; FALSE if the point is located in a client area. +*`bOuterEdge`*\ +[out] `TRUE` if the point is located close to the frame border; `FALSE` if the point is located in a client area. ### Return Value -TRUE if the point is located in an alignment zone; otherwise, FALSE. +`TRUE` if the point is located in an alignment zone; otherwise, `FALSE`. -### Remarks +### Remarks -The following table lists the possible values for the *dwBarAlignment* parameter. +The following table lists the possible values for the *`dwBarAlignment`* parameter. |Value|Description| |-|-| -|CBRS_ALIGN_TOP|Aligned to the top. | -|CBRS_ALIGN_RIGHT|Aligned to the right. | -|CBRS_ALIGN_BOTTOM|Aligned to the bottom. | -|CBRS_ALIGN_LEFT|Aligned to the left. | +|`CBRS_ALIGN_TOP`|Aligned to the top. | +|`CBRS_ALIGN_RIGHT`|Aligned to the right. | +|`CBRS_ALIGN_BOTTOM`|Aligned to the bottom. | +|`CBRS_ALIGN_LEFT`|Aligned to the left. | -## CFrameWndEx::IsPrintPreview +## `CFrameWndEx::IsPrintPreview` Determines whether the frame window is in print preview mode. @@ -622,11 +621,11 @@ BOOL IsPrintPreview(); ### Return Value -TRUE if the frame window is in print preview mode; otherwise, FALSE. +`TRUE` if the frame window is in print preview mode; otherwise, `FALSE`. ### Remarks -## CFrameWndEx::LoadFrame +## `CFrameWndEx::LoadFrame` This method is called after construction to create the frame window and load its resources. @@ -640,25 +639,25 @@ virtual BOOL LoadFrame( ### Parameters -*nIDResource*
+*`nIDResource`*\ [in] The resource ID that is used to load all frame resources. -*dwDefaultStyle*
+*`dwDefaultStyle`*\ [in] The default frame window style. -*pParentWnd*
+*`pParentWnd`*\ [in] Pointer to the parent window of the frame. -*pContext*
-[in] Pointer to a [CCreateContext Structure](../../mfc/reference/ccreatecontext-structure.md) class that is used by the framework during application creation. +*`pContext`*\ +[in] Pointer to a [`CCreateContext` Structure](../../mfc/reference/ccreatecontext-structure.md) class that is used by the framework during application creation. ### Return Value -TRUE if the method was successful; otherwise, FALSE. +`TRUE` if the method was successful; otherwise, `FALSE`. ### Remarks -## CFrameWndEx::NegotiateBorderSpace +## `CFrameWndEx::NegotiateBorderSpace` Implements OLE client border negotiation. @@ -670,30 +669,30 @@ virtual BOOL NegotiateBorderSpace( ### Parameters -*nBorderCmd*
-[in] The border negotiation command. See the Remarks section for possible values. +*`nBorderCmd`*\ +[in] The border negotiation command. See the [Remarks](#negotiateborderspace-remarks) section for possible values. -*lpRectBorder*
+*`lpRectBorder`*\ [in, out] Dimensions of the border. ### Return Value -TRUE if the layout must be recalculated; otherwise, FALSE. +`TRUE` if the layout must be recalculated; otherwise, `FALSE`. -### Remarks +### Remarks -The following table lists the possible values for the *nBorderCmd* parameter. +The following table lists the possible values for the *`nBorderCmd`* parameter. -*borderGet*
+*`borderGet`*\ Get available OLE client space. -*borderRequest*
+*`borderRequest`*\ Request OLE client space. -*borderSet*
+*`borderSet`*\ Set OLE client space. -## CFrameWndEx::OnActivate +## `CFrameWndEx::OnActivate` The framework calls this method when user input is switched to or away from the frame. @@ -706,26 +705,26 @@ afx_msg void OnActivate( ### Parameters -*nState*
-[in] Whether the frame is active or inactive. See the table in the Remarks section for possible values. +*`nState`*\ +[in] Whether the frame is active or inactive. See the table in the [Remarks](#onactivate-remarks) section for possible values. -*pWndOther*
+*`pWndOther`*\ [in] Pointer to another window that is switching user input with the current one. -*bMinimized*
-[in] The minimized state of the frame. TRUE if the frame is minimized; otherwise, FALSE. +*`bMinimized`*\ +[in] The minimized state of the frame. `TRUE` if the frame is minimized; otherwise, `FALSE`. -### Remarks +### Remarks -The following table lists the possible values for the *nState* parameter. +The following table lists the possible values for the *`nState`* parameter. |Value|Description| |-|-| -|WA_ACTIVE|The frame is selected by a method other than a mouse click. | -|WA_CLICKACTIVE|The frame is selected by a mouse click. | -|WA_INACTIVE|The frame is not selected. | +|`WA_ACTIVE`|The frame is selected by a method other than a mouse click. | +|`WA_CLICKACTIVE`|The frame is selected by a mouse click. | +|`WA_INACTIVE`|The frame isn't selected. | -## CFrameWndEx::OnActivateApp +## `CFrameWndEx::OnActivateApp` Called by the framework when the application is either selected or deselected. @@ -737,15 +736,15 @@ afx_msg void OnActivateApp( ### Parameters -*bActive*
-[in] TRUE if the application is selected; FALSE if the application is not selected. +*`bActive`*\ +[in] `TRUE` if the application is selected; `FALSE` if the application isn't selected. -*dwThreadID*
-[in] This parameter is not used. +*`dwThreadID`*\ +[in] This parameter isn't used. ### Remarks -## CFrameWndEx::OnChangeVisualManager +## `CFrameWndEx::OnChangeVisualManager` Called by the framework when a change to the frame requires a change to the visual manager. @@ -757,11 +756,11 @@ afx_msg LRESULT OnChangeVisualManager( ### Parameters -*wParam*
-[in] This parameter is not used. +*`wParam`*\ +[in] This parameter isn't used. -*lParam*
-[in] This parameter is not used. +*`lParam`*\ +[in] This parameter isn't used. ### Return Value @@ -769,7 +768,7 @@ Always returns 0. ### Remarks -## CFrameWndEx::OnClose +## `CFrameWndEx::OnClose` The framework calls this method to close the frame. @@ -781,7 +780,7 @@ afx_msg void OnClose(); If the frame is in print preview mode, it sends a Windows message to close the print preview; otherwise, if the frame hosts an OLE client, the client is deactivated. -## CFrameWndEx::OnCloseDockingPane +## `CFrameWndEx::OnCloseDockingPane` Called by the framework when the user clicks the **Close** button on a docking pane. @@ -791,13 +790,13 @@ virtual BOOL OnCloseDockingPane(CDockablePane* pPane); ### Return Value -TRUE if the docking bar can be closed. FALSE otherwise +`TRUE` if the docking bar can be closed. `FALSE` otherwise ### Remarks The default implement does nothing. Override this method if you want to handle the hiding of the docking bar. -## CFrameWndEx::OnCloseMiniFrame +## `CFrameWndEx::OnCloseMiniFrame` Called by the framework when the user clicks the **Close** button on a floating mini frame window. @@ -807,15 +806,15 @@ virtual BOOL OnCloseMiniFrame(CPaneFrameWnd* pWnd); ### Return Value -TRUE if a floating mini frame window can be closed. FALSE otherwise. +`TRUE` if a floating mini frame window can be closed. `FALSE` otherwise. ### Remarks The default implementation does nothing. Override this method if you want to process the hiding of a floating mini frame window. -## CFrameWndEx::OnClosePopupMenu +## `CFrameWndEx::OnClosePopupMenu` -Called by the framework when an active pop-up menu processes a WM_DESTROY message. +Called by the framework when an active pop-up menu processes a `WM_DESTROY` message. ``` virtual void OnClosePopupMenu(CMFCPopupMenu* pMenuPopup); @@ -823,14 +822,14 @@ virtual void OnClosePopupMenu(CMFCPopupMenu* pMenuPopup); ### Parameters -*pMenuPopup*
+*`pMenuPopup`*\ A pointer to a pop-up menu. ### Remarks -The framework sends a WM_DESTROY message when it is about to close the window. Override this method if you want to handle notifications from `CMFCPopupMenu` objects that belong to the frame window when a `CMFCPopupMenu` object is processing a WM_DESTROY message sent by the framework when the window is being closed. +The framework sends a `WM_DESTROY` message when it's about to close the window. Override this method if you want to handle notifications from `CMFCPopupMenu` objects that belong to the frame window when a `CMFCPopupMenu` object is processing a `WM_DESTROY` message sent by the framework when the window is being closed. -## CFrameWndEx::OnCmdMsg +## `CFrameWndEx::OnCmdMsg` Dispatches command messages. @@ -844,25 +843,25 @@ virtual BOOL OnCmdMsg( ### Parameters -*nID*
+*`nID`*\ [in] The command ID. -*nCode*
+*`nCode`*\ [in] Command message category. -*pExtra*
+*`pExtra`*\ [in, out] Pointer to a command object. -*pHandlerInfo*
+*`pHandlerInfo`*\ [in, out] Pointer to a command handler structure. ### Return Value -TRUE if the command message was handled; otherwise, FALSE. +`TRUE` if the command message was handled; otherwise, `FALSE`. ### Remarks -## CFrameWndEx::OnContextHelp +## `CFrameWndEx::OnContextHelp` Called by the framework to display context-related help. @@ -872,7 +871,7 @@ afx_msg void OnContextHelp(); ### Remarks -## CFrameWndEx::OnCreate +## `CFrameWndEx::OnCreate` Called by the framework after the frame is created. @@ -882,8 +881,8 @@ afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct); ### Parameters -*lpCreateStruct*
-[in] A pointer to the [CREATESTRUCT Structure](/windows/win32/api/winuser/ns-winuser-createstructw) for the new frame. +*`lpCreateStruct`*\ +[in] A pointer to the [`CREATESTRUCT` Structure](/windows/win32/api/winuser/ns-winuser-createstructw) for the new frame. ### Return Value @@ -891,7 +890,7 @@ afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct); ### Remarks -## CFrameWndEx::OnDestroy +## `CFrameWndEx::OnDestroy` Called by the framework when the frame is destroyed. @@ -903,7 +902,7 @@ afx_msg void OnDestroy(); The accelerator table and all windows are destroyed. -## CFrameWndEx::OnDrawMenuImage +## `CFrameWndEx::OnDrawMenuImage` Called by the framework when the application draws the image associated with a menu item. @@ -916,26 +915,26 @@ virtual BOOL OnDrawMenuImage( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*pMenuButton*
+*`pMenuButton`*\ [in] A pointer to a menu button whose image is being rendered. -*rectImage*
+*`rectImage`*\ [in] A pointer to a `Rect` structure that specifies the screen position and size of the image. ### Return Value -TRUE if the framework successfully renders the image; FALSE otherwise. +`TRUE` if the framework successfully renders the image; `FALSE` otherwise. ### Remarks Override this method if you want to customize the image rendering for the menu items that belong to the menu bar owned by the `CFrameWndEx` derived object. -## CFrameWndEx::OnDrawMenuLogo +## `CFrameWndEx::OnDrawMenuLogo` -Called by the framework when a `CMFCPopupMenu` object processes a WM_PAINT message. +Called by the framework when a `CMFCPopupMenu` object processes a `WM_PAINT` message. ``` virtual void OnDrawMenuLogo( @@ -946,20 +945,20 @@ virtual void OnDrawMenuLogo( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*pMenu*
+*`pMenu`*\ [in] A pointer to the menu item. -*rectLogo*
+*`rectLogo`*\ [in] A reference to a constant `CRect` structure that specifies the screen position and size of the menu logo. ### Remarks Override this function if you want to display a logo on the pop-up menu that belongs to the menu bar owned by the `CFrameWndEx` derived object. -## CFrameWndEx::OnDWMCompositionChanged +## `CFrameWndEx::OnDWMCompositionChanged` Called by the framework when Desktop Window Manager (DWM) composition has been enabled or disabled. @@ -971,11 +970,11 @@ afx_msg LRESULT OnDWMCompositionChanged( ### Parameters -*wp*
-[in] This parameter is not used. +*`wp`*\ +[in] This parameter isn't used. -*lp*
-[in] This parameter is not used. +*`lp`*\ +[in] This parameter isn't used. ### Return Value @@ -983,7 +982,7 @@ Always returns 0. ### Remarks -## CFrameWndEx::OnExitSizeMove +## `CFrameWndEx::OnExitSizeMove` Called by the framework when the frame stops moving or resizing. @@ -995,11 +994,11 @@ LRESULT OnExitSizeMove( ### Parameters -*wp*
-[in] This parameter is not used. +*`wp`*\ +[in] This parameter isn't used. -*lp*
-[in] This parameter is not used. +*`lp`*\ +[in] This parameter isn't used. ### Return Value @@ -1007,7 +1006,7 @@ Always returns 0. ### Remarks -## CFrameWndEx::OnGetMinMaxInfo +## `CFrameWndEx::OnGetMinMaxInfo` Called by the framework when the frame is resized to set window dimension limits. @@ -1017,12 +1016,12 @@ afx_msg void OnGetMinMaxInfo(MINMAXINFO FAR* lpMMI); ### Parameters -*lpMMI*
-[in] Pointer to a [MINMAXINFO](/windows/win32/api/winuser/ns-winuser-minmaxinfo) structure. +*`lpMMI`*\ +[in] Pointer to a [`MINMAXINFO`](/windows/win32/api/winuser/ns-winuser-minmaxinfo) structure. ### Remarks -## CFrameWndEx::OnIdleUpdateCmdUI +## `CFrameWndEx::OnIdleUpdateCmdUI` Called by the framework to update the frame display when command processing is idle. @@ -1034,11 +1033,11 @@ afx_msg LRESULT OnIdleUpdateCmdUI( ### Parameters -*wParam*
-[in] This parameter is not used. +*`wParam`*\ +[in] This parameter isn't used. -*lParam*
-[in] This parameter is not used. +*`lParam`*\ +[in] This parameter isn't used. ### Return Value @@ -1046,7 +1045,7 @@ Always returns 0. ### Remarks -## CFrameWndEx::OnLButtonDown +## `CFrameWndEx::OnLButtonDown` The framework calls this method when the user presses the left mouse button. @@ -1058,15 +1057,15 @@ afx_msg void OnLButtonDown( ### Parameters -*nFlags*
-[in] Indicates whether the user pressed modifier keys. For possible values see the parameter *wParam* in [WM_LBUTTONDOWN Notification](/windows/win32/inputdev/wm-lbuttondown). +*`nFlags`*\ +[in] Indicates whether the user pressed modifier keys. For possible values see the parameter *`wParam`* in [`WM_LBUTTONDOWN` Notification](/windows/win32/inputdev/wm-lbuttondown). -*point*
+*`point`*\ [in] Specifies the x and y coordinates of the pointer, relative to the upper-left corner of the window. ### Remarks -## CFrameWndEx::OnLButtonUp +## `CFrameWndEx::OnLButtonUp` The framework calls this method when the user releases the left mouse button. @@ -1078,17 +1077,17 @@ afx_msg void OnLButtonUp( ### Parameters -*nFlags*
-[in] Indicates whether the user pressed modifier keys. For possible values see the parameter *wParam* in [WM_LBUTTONUP Notification](/windows/win32/inputdev/wm-lbuttonup). +*`nFlags`*\ +[in] Indicates whether the user pressed modifier keys. For possible values see the parameter *`wParam`* in [`WM_LBUTTONUP` Notification](/windows/win32/inputdev/wm-lbuttonup). -*point*
+*`point`*\ [in] Specifies the x and y coordinates of the pointer, relative to the upper-left corner of the window. ### Remarks -## CFrameWndEx::OnMenuButtonToolHitTest +## `CFrameWndEx::OnMenuButtonToolHitTest` -Called by the framework when a `CMFCToolBarButton` object processes a WM_NCHITTEST message. +Called by the framework when a `CMFCToolBarButton` object processes a `WM_NCHITTEST` message. ``` virtual BOOL OnMenuButtonToolHitTest( @@ -1098,23 +1097,23 @@ virtual BOOL OnMenuButtonToolHitTest( ### Parameters -*pButton*
+*`pButton`*\ [in] A pointer to the tool bar button. -*pTI*
+*`pTI`*\ [out] A pointer to a tool information structure. ### Return Value -TRUE if the application fills the *pTI* parameter. FALSE otherwise. +`TRUE` if the application fills the *`pTI`* parameter. `FALSE` otherwise. ### Remarks Override this method if you want to provide a tooltip information about a specific menu item. -## CFrameWndEx::OnMenuChar +## `CFrameWndEx::OnMenuChar` -Called by the framework when a menu is displayed and the user presses a key that does not correspond to a command. +Called by the framework when a menu is displayed and the user presses a key that doesn't correspond to a command. ``` afx_msg LRESULT OnMenuChar( @@ -1125,13 +1124,13 @@ afx_msg LRESULT OnMenuChar( ### Parameters -*nChar*
+*`nChar`*\ [in] Character code of the pressed key. -*nFlags*
-[in] Contains the MF_POPUP flag if the menu displayed is a submenu; contains the MF_SYSMENU flag if the menu displayed is a control menu. +*`nFlags`*\ +[in] Contains the `MF_POPUP` flag if the menu displayed is a submenu; contains the `MF_SYSMENU` flag if the menu displayed is a control menu. -*pMenu*
+*`pMenu`*\ [in] Pointer to a menu. ### Return Value @@ -1144,7 +1143,7 @@ The high-order word must be one of the following values. | `1` | The framework should close the menu. | | `2` | The framework should select one of the items displayed in the menu. The low-order word contains the ID of the command to select. | -## CFrameWndEx::OnMouseMove +## `CFrameWndEx::OnMouseMove` The framework calls this method when the pointer moves. @@ -1156,15 +1155,15 @@ afx_msg void OnMouseMove( ### Parameters -*nFlags*
-[in] Indicates whether a user pressed modifier keys. For possible values see the parameter *wParam* in [WM_MOUSEMOVE Notification](/windows/win32/inputdev/wm-mousemove). +*`nFlags`*\ +[in] Indicates whether a user pressed modifier keys. For possible values see the parameter *`wParam`* in [`WM_MOUSEMOVE` Notification](/windows/win32/inputdev/wm-mousemove). -*point*
-[in] Specifies the x and y coordinates of the pointer relative to the upper-left corner of the window. +*`point`*\ +[in] Specifies the `x` and `y` coordinates of the pointer relative to the upper-left corner of the window. ### Remarks -## CFrameWndEx::OnMoveMiniFrame +## `CFrameWndEx::OnMoveMiniFrame` Called by the framework when a pane window moves. @@ -1174,16 +1173,16 @@ virtual BOOL OnMoveMiniFrame(CWnd* pFrame); ### Parameters -*pFrame*
-[in] Pointer to the [CPaneFrameWnd Class](../../mfc/reference/cpaneframewnd-class.md) pane window. +*`pFrame`*\ +[in] Pointer to the [`CPaneFrameWnd` Class](../../mfc/reference/cpaneframewnd-class.md) pane window. ### Return Value -TRUE if the pane window was not docked; FALSE if the pane window was docked. +`TRUE` if the pane window wasn't docked; `FALSE` if the pane window was docked. ### Remarks -## CFrameWndEx::OnNcActivate +## `CFrameWndEx::OnNcActivate` Called by the framework when the non-client area of the frame must be redrawn to indicate a change in the active state. @@ -1193,8 +1192,8 @@ afx_msg BOOL OnNcActivate(BOOL bActive); ### Parameters -*bActive*
-[in] TRUE to draw the frame active; FALSE to draw the frame inactive. +*`bActive`*\ +[in] `TRUE` to draw the frame active; `FALSE` to draw the frame inactive. ### Return Value @@ -1202,7 +1201,7 @@ Nonzero to continue with default processing; 0 to prevent the non-client area fr ### Remarks -## CFrameWndEx::OnNcCalcSize +## `CFrameWndEx::OnNcCalcSize` Called by the framework when the size and position of the client area must be calculated. @@ -1214,15 +1213,15 @@ afx_msg void OnNcCalcSize( ### Parameters -*bCalcValidRects*
-[in] TRUE when the application must specify a valid client area; otherwise, FALSE. +*`bCalcValidRects`*\ +[in] `TRUE` when the application must specify a valid client area; otherwise, `FALSE`. -*lpncsp*
+*`lpncsp`*\ [in] Pointer to a `NCCALCSIZE_PARAMS` structure that contains frame dimension changes. ### Remarks -## CFrameWndEx::OnNcHitTest +## `CFrameWndEx::OnNcHitTest` Called by the framework when the pointer moves or when a mouse button is pressed or released. @@ -1232,16 +1231,16 @@ afx_msg LRESULT OnNcHitTest(CPoint point); ### Parameters -*point*
+*`point`*\ [in] The location of the pointer in screen coordinates. ### Return Value -A pointer hit enumerated value. For a list of possible values see [WM_NCHITTEST Notification](/windows/win32/inputdev/wm-nchittest). +A pointer hit enumerated value. For a list of possible values see [`WM_NCHITTEST` Notification](/windows/win32/inputdev/wm-nchittest). ### Remarks -## CFrameWndEx::OnNcMouseMove +## `CFrameWndEx::OnNcMouseMove` Called by the framework when the pointer moves in a non-client area. @@ -1253,15 +1252,15 @@ afx_msg void OnNcMouseMove( ### Parameters -*nHitTest*
-[in] A pointer hit enumerated value. For a list of possible values see [WM_NCHITTEST Notification](/windows/win32/inputdev/wm-nchittest). +*`nHitTest`*\ +[in] A pointer hit enumerated value. For a list of possible values see [`WM_NCHITTEST` Notification](/windows/win32/inputdev/wm-nchittest). -*point*
+*`point`*\ [in] The location of the pointer in screen coordinates. ### Remarks -## CFrameWndEx::OnNcPaint +## `CFrameWndEx::OnNcPaint` Called by the framework when the non-client area must be painted. @@ -1271,7 +1270,7 @@ afx_msg void OnNcPaint(); ### Remarks -## CFrameWndEx::OnPaneCheck +## `CFrameWndEx::OnPaneCheck` Called by the framework to control the visibility of a pane. @@ -1281,16 +1280,16 @@ afx_msg BOOL OnPaneCheck(UINT nID); ### Parameters -*nID*
+*`nID`*\ [in] Control ID of a pane. ### Return Value -TRUE if the command was handled; FALSE to continue with command processing. +`TRUE` if the command was handled; `FALSE` to continue with command processing. ### Remarks -## CFrameWndEx::OnPostPreviewFrame +## `CFrameWndEx::OnPostPreviewFrame` Called by the framework when the user changes the print preview mode. @@ -1302,11 +1301,11 @@ afx_msg LRESULT OnPostPreviewFrame( ### Parameters -*wParam*
-[in] This parameter is not used. +*`wParam`*\ +[in] This parameter isn't used. -*lParam*
-[in] TRUE when the frame is in print preview mode; FALSE when print preview mode is off. +*`lParam`*\ +[in] `TRUE` when the frame is in print preview mode; `FALSE` when print preview mode is off. ### Return Value @@ -1314,7 +1313,7 @@ Always returns 0. ### Remarks -## CFrameWndEx::OnPowerBroadcast +## `CFrameWndEx::OnPowerBroadcast` Called by the framework when a power management event occurs. @@ -1326,11 +1325,11 @@ afx_msg LRESULT OnPowerBroadcast( ### Parameters -*wp*
-[in] The power management event. For a list of possible values see [WM_POWERBROADCAST Message](/windows/win32/Power/wm-powerbroadcast). +*`wp`*\ +[in] The power management event. For a list of possible values see [`WM_POWERBROADCAST` Message](/windows/win32/Power/wm-powerbroadcast). -*lp*
-[in] This parameter is not used. +*`lp`*\ +[in] This parameter isn't used. ### Return Value @@ -1338,7 +1337,7 @@ Result from calling the default window procedure. ### Remarks -## CFrameWndEx::OnSetMenu +## `CFrameWndEx::OnSetMenu` Called by the framework to replace the frame window menu. @@ -1352,24 +1351,24 @@ BOOL OnSetMenu(HMENU hmenu); ### Parameters -*wp*
+*`wp`*\ [in] Handle to the new frame window menu. -*lp*
+*`lp`*\ [in] Handle to the new window menu. -*hmenu*
+*`hmenu`*\ [in] Handle to the new frame window menu. ### Return Value -LRESULT is the result from calling the default window procedure. +`LRESULT` is the result from calling the default window procedure. -BOOL is TRUE if the event was handled; otherwise, FALSE. +BOOL is `TRUE` if the event was handled; otherwise, `FALSE`. ### Remarks -## CFrameWndEx::OnSetPreviewMode +## `CFrameWndEx::OnSetPreviewMode` Called by the framework to set the print preview mode for the frame. @@ -1381,15 +1380,15 @@ virtual void OnSetPreviewMode( ### Parameters -*bPreview*
-[in] TRUE to enable print preview; FALSE to disable print preview. +*`bPreview`*\ +[in] `TRUE` to enable print preview; `FALSE` to disable print preview. -*pState*
+*`pState`*\ [in] Pointer to a `CPrintPreviewState` frame state structure. ### Remarks -## CFrameWndEx::OnSetText +## `CFrameWndEx::OnSetText` Called by the framework to set the text of a window. @@ -1401,19 +1400,19 @@ afx_msg LRESULT OnSetText( ### Parameters -*wParam*
-[in] This parameter is not used. +*`wParam`*\ +[in] This parameter isn't used. -*lParam*
+*`lParam`*\ [in] Pointer to the text for the window. ### Return Value -Return value from a call to [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowprocw). +Return value from a call to [`DefWindowProc`](/windows/win32/api/winuser/nf-winuser-defwindowprocw). ### Remarks -## CFrameWndEx::OnShowCustomizePane +## `CFrameWndEx::OnShowCustomizePane` Called by the framework when it displays a `QuickCustomizePane`. @@ -1425,21 +1424,21 @@ virtual BOOL OnShowCustomizePane( ### Parameters -*pMenuPane*
+*`pMenuPane`*\ [in] A pointer to the quick customize pane. -*uiToolbarID*
+*`uiToolbarID`*\ [in] The control ID of the toolbar to customize. ### Return Value -This method always return TRUE. +This method always returns `TRUE`. ### Remarks -The quick customize menu is a pop-up menu that appears when you click the toolbar’s customize button +The quick customize menu is a pop-up menu that appears when you click the toolbar's customize button -## CFrameWndEx::OnShowPanes +## `CFrameWndEx::OnShowPanes` Called by the framework to show or hide panes. @@ -1449,22 +1448,22 @@ virtual BOOL OnShowPanes(BOOL bShow); ### Parameters -*bShow*
-[in] TRUE if the application shows the panes; FALSE otherwise. +*`bShow`*\ +[in] `TRUE` if the application shows the panes; `FALSE` otherwise. ### Return Value -This method always return FALSE. +This method always returns `FALSE`. ### Remarks -The default implementation shows the panes if *bShow* is TRUE and the panes are hidden or when *bShow* is FALSE and the panes are visible. +The default implementation shows the panes if *`bShow`* is `TRUE` and the panes are hidden or when *`bShow`* is `FALSE` and the panes are visible. -The default implementation hides the panes if *bShow* is TRUE and the panes are visible or when *bShow* is FALSE and the panes are hidden. +The default implementation hides the panes if *`bShow`* is `TRUE` and the panes are visible or when *`bShow`* is `FALSE` and the panes are hidden. Override this method in a derived class to execute custom code when the framework shows or hides panes. -## CFrameWndEx::OnShowPopupMenu +## `CFrameWndEx::OnShowPopupMenu` Called by the framework when it displays a pop-up menu. @@ -1474,18 +1473,18 @@ virtual BOOL OnShowPopupMenu(CMFCPopupMenu* pMenu); ### Parameters -*pMenu*
+*`pMenu`*\ [in] A pointer to a pop-up menu. ### Return Value -TRUE if the pop-up menu is visible; otherwise FALSE. +`TRUE` if the pop-up menu is visible; otherwise `FALSE`. ### Remarks Override this method in a derived class to execute custom code when the framework displays a pop-up menu. For example, override this method to change the background color of the commands in a pop-up menu. -## CFrameWndEx::OnSize +## `CFrameWndEx::OnSize` Called by the framework after the frame's size changes. @@ -1498,18 +1497,18 @@ afx_msg void OnSize( ### Parameters -*nType*
-[in] The type of resizing. For possible values see the parameter *wParam* in [WM_SIZE Notification](/windows/win32/winmsg/wm-size). +*`nType`*\ +[in] The type of resizing. For possible values see the parameter *`wParam`* in [WM_SIZE Notification](/windows/win32/winmsg/wm-size). -*cx*
+*`cx`*\ [in] New width of the frame in pixels. -*cy*
+*`cy`*\ [in] New height of the frame in pixels. ### Remarks -## CFrameWndEx::OnSizing +## `CFrameWndEx::OnSizing` Called by the framework when the user resizes the frame. @@ -1521,15 +1520,15 @@ afx_msg void OnSizing( ### Parameters -*fwSide*
-[in] The edge of the frame that is moved. See the parameter *wParam* in [WM_SIZING Notification](/windows/win32/winmsg/wm-sizing). +*`fwSide`*\ +[in] The edge of the frame that is moved. See the parameter *`wParam`* in [`WM_SIZING` Notification](/windows/win32/winmsg/wm-sizing). -*pRect*
-[in, out] Pointer to a [CRect](../../atl-mfc-shared/reference/crect-class.md) or [RECT](/windows/win32/api/windef/ns-windef-rect) structure that contains the frame's coordinates. +*`pRect`*\ +[in, out] Pointer to a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) or [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that contains the frame's coordinates. ### Remarks -## CFrameWndEx::OnSysColorChange +## `CFrameWndEx::OnSysColorChange` Called by the framework when the system colors change. @@ -1539,7 +1538,7 @@ void OnSysColorChange(); ### Remarks -## CFrameWndEx::OnTearOffMenu +## `CFrameWndEx::OnTearOffMenu` Called by the framework when the application displays a menu that has a tear-off bar. @@ -1551,23 +1550,23 @@ virtual BOOL OnTearOffMenu( ### Parameters -*pMenuPopup*
+*`pMenuPopup`*\ [in] A pointer to a pop-up menu. -*pBar*
+*`pBar`*\ [in] A pointer to a tear-off bar. ### Return Value -TRUE if the pop-up menu with the tear-off bar is enabled; otherwise FALSE. +`TRUE` if the pop-up menu with the tear-off bar is enabled; otherwise `FALSE`. ### Remarks Override this method in a derived class to execute custom code when the framework displays a control bar. -The default implementation does nothing and returns TRUE. +The default implementation does nothing and returns `TRUE`. -## CFrameWndEx::OnToolbarContextMenu +## `CFrameWndEx::OnToolbarContextMenu` Called by the framework to build a toolbar pop-up menu. @@ -1579,11 +1578,11 @@ afx_msg LRESULT OnToolbarContextMenu( ### Parameters -*wp*
-[in] This parameter is not used. +*`wp`*\ +[in] This parameter isn't used. -*lp*
-[in] This parameter is not used. +*`lp`*\ +[in] This parameter isn't used. ### Return Value @@ -1591,7 +1590,7 @@ Always returns 1. ### Remarks -## CFrameWndEx::OnToolbarCreateNew +## `CFrameWndEx::OnToolbarCreateNew` The framework calls this method to create a new toolbar. @@ -1603,19 +1602,19 @@ afx_msg LRESULT OnToolbarCreateNew( ### Parameters -*wp*
-[in] This parameter is not used. +*`wp`*\ +[in] This parameter isn't used. -*lp*
+*`lp`*\ [in] Pointer to the text for the title bar of the toolbar. ### Return Value -Pointer to the new toolbar; or NULL if a toolbar was not created. +Pointer to the new toolbar; or `NULL` if a toolbar wasn't created. ### Remarks -## CFrameWndEx::OnToolbarDelete +## `CFrameWndEx::OnToolbarDelete` Called by the framework when a toolbar is deleted. @@ -1627,19 +1626,19 @@ afx_msg LRESULT OnToolbarDelete( ### Parameters -*unused*
-[in] This parameter is not used. +*`unused`*\ +[in] This parameter isn't used. -*lp*
+*`lp`*\ [in] Pointer to a toolbar. ### Return Value -TRUE if the toolbar was deleted; otherwise, FALSE. +`TRUE` if the toolbar was deleted; otherwise, `FALSE`. ### Remarks -## CFrameWndEx::OnUpdateFrameMenu +## `CFrameWndEx::OnUpdateFrameMenu` Called by the framework to set the frame menu. @@ -1649,12 +1648,12 @@ virtual void OnUpdateFrameMenu(HMENU hMenuAlt); ### Parameters -*hMenuAlt*
+*`hMenuAlt`*\ [in] Handle to the alternative menu. ### Remarks -## CFrameWndEx::OnUpdateFrameTitle +## `CFrameWndEx::OnUpdateFrameTitle` The framework calls this method to update the title bar of the frame window. @@ -1664,12 +1663,12 @@ virtual void OnUpdateFrameTitle(BOOL bAddToTitle); ### Parameters -*bAddToTitle*
-[in] TRUE to add the active document title to the frame window title bar; otherwise FALSE. +*`bAddToTitle`*\ +[in] `TRUE` to add the active document title to the frame window title bar; otherwise `FALSE`. ### Remarks -## CFrameWndEx::OnUpdatePaneMenu +## `CFrameWndEx::OnUpdatePaneMenu` Called by the framework to update the pane menu. @@ -1679,12 +1678,12 @@ afx_msg void OnUpdatePaneMenu(CCmdUI* pCmdUI); ### Parameters -*pCmdUI*
+*`pCmdUI`*\ [in] Pointer to the pane user interface object. ### Remarks -## CFrameWndEx::OnWindowPosChanged +## `CFrameWndEx::OnWindowPosChanged` Called by the framework when the frame size, position, or z-order has changed because of a call to a window management method. @@ -1694,12 +1693,12 @@ afx_msg void OnWindowPosChanged(WINDOWPOS FAR* lpwndpos); ### Parameters -*lpwndpos*
-[in] Pointer to a [WINDOWPOS](/windows/win32/api/winuser/ns-winuser-windowpos) structure that contains the new size and position. +*`lpwndpos`*\ +[in] Pointer to a [`WINDOWPOS`](/windows/win32/api/winuser/ns-winuser-windowpos) structure that contains the new size and position. ### Remarks -## CFrameWndEx::PaneFromPoint +## `CFrameWndEx::PaneFromPoint` Searches each pane for the given point. @@ -1719,34 +1718,34 @@ CBasePane* PaneFromPoint( ### Parameters -*point*
+*`point`*\ [in] The screen coordinates of the point to check. -*nSensitivity*
+*`nSensitivity`*\ [in] Expand the bounding rectangle of each control bar by this amount when searching for point. -*bExactBar*
-[in] TRUE to ignore the *nSensitivity* parameter; otherwise, FALSE. +*`bExactBar`*\ +[in] `TRUE` to ignore the *`nSensitivity`* parameter; otherwise, `FALSE`. -*pRTCBarType*
-[in] If not NULL, the method searches only the control bars of the specified type. +*`pRTCBarType`*\ +[in] If not `NULL`, the method searches only the control bars of the specified type. -*dwAlignment*
-[out] If successful, this parameter contains the side of the control bar that is closest to the specified point. Otherwise, this parameter is not initialized. +*`dwAlignment`*\ +[out] If successful, this parameter contains the side of the control bar that is closest to the specified point. Otherwise, this parameter isn't initialized. ### Return Value -A pointer to a control bar that contains the *point*; NULL if no control is found. +A pointer to a control bar that contains the *`point`*; `NULL` if no control is found. ### Remarks -This method searches all the control bars in your application for a *point*. +This method searches all the control bars in your application for a *`point`*. -Use *nSensitivity* to increase the size of the search area. Use *pRTCBarType* to restrict the types of control bars that the method searches. +Use *`nSensitivity`* to increase the size of the search area. Use *`pRTCBarType`* to restrict the types of control bars that the method searches. -## CFrameWndEx::PreTranslateMessage +## `CFrameWndEx::PreTranslateMessage` -Handles specific window messages before they are dispatched. +Handles specific window messages before they're dispatched. ``` virtual BOOL PreTranslateMessage(MSG* pMsg); @@ -1754,16 +1753,16 @@ virtual BOOL PreTranslateMessage(MSG* pMsg); ### Parameters -*pMsg*
-[in] A pointer to a [MSG](/windows/win32/api/winuser/ns-winuser-msg) structure that contains the message to process. +*`pMsg`*\ +[in] A pointer to a [`MSG`](/windows/win32/api/winuser/ns-winuser-msg) structure that contains the message to process. ### Return Value -Non-zero if the message was handled and should not be dispatched; 0 if the message was not handled and should be dispatched. +Non-zero if the message was handled and shouldn't be dispatched; 0 if the message wasn't handled and should be dispatched. ### Remarks -## CFrameWndEx::RecalcLayout +## `CFrameWndEx::RecalcLayout` Adjusts the layout of the frame and its child windows. @@ -1773,14 +1772,14 @@ virtual void RecalcLayout(BOOL bNotify = TRUE); ### Parameters -*bNotify*
+*`bNotify`*\ [in] Specifies whether to notify the OLE client item about the layout change. ### Remarks This method is called when the size of the frame window has changed or when control bars are displayed or hidden. -## CFrameWndEx::RemovePaneFromDockManager +## `CFrameWndEx::RemovePaneFromDockManager` Unregisters a pane and removes it from the docking manager. @@ -1795,28 +1794,28 @@ void RemovePaneFromDockManager( ### Parameters -*pControlBar*
+*`pControlBar`*\ [in] A pointer to the control bar pane to remove. -*bDestroy*
-[in] TRUE to destroy the control bar after removing it; FALSE otherwise. +*`bDestroy`*\ +[in] `TRUE` to destroy the control bar after removing it; `FALSE` otherwise. -*bAdjustLayout*
-[in] TRUE to adjust the docking layout; FALSE otherwise. +*`bAdjustLayout`*\ +[in] `TRUE` to adjust the docking layout; `FALSE` otherwise. -*bAutoHide*
-[in] TRUE if the control bar is in auto-hide mode; FALSE otherwise. +*`bAutoHide`*\ +[in] `TRUE` if the control bar is in auto-hide mode; `FALSE` otherwise. -*pBarReplacement*
+*`pBarReplacement`*\ [in] A pointer to a pane that replaces the removed pane. ### Remarks Use this method to remove a control bar from the docking layout of the frame window. -The [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) handles the layout of control bars. You must register each control bar with the docking manager by using the [CFrameWndEx::AddPane](#addpane) method or the [CFrameWndEx::InsertPane](#insertpane) method. +The [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) handles the layout of control bars. You must register each control bar with the docking manager by using the [`CFrameWndEx::AddPane`](#addpane) method or the [`CFrameWndEx::InsertPane`](#insertpane) method. -## CFrameWndEx::SetDockState +## `CFrameWndEx::SetDockState` Restores the docking layout to the docking state stored in the registry. @@ -1826,10 +1825,10 @@ void SetDockState(const CDockState& state); ### Parameters -*state*
+*`state`*\ The docking state. This parameter is ignored. -## CFrameWndEx::SetPrintPreviewFrame +## `CFrameWndEx::SetPrintPreviewFrame` Sets the print preview frame window. @@ -1839,12 +1838,12 @@ void SetPrintPreviewFrame(CFrameWnd* pWnd); ### Parameters -*pWnd*
+*`pWnd`*\ [in] Pointer to a print preview frame window. ### Remarks -## CFrameWndEx::SetupToolbarMenu +## `CFrameWndEx::SetupToolbarMenu` Inserts user-defined commands into a toolbar menu. @@ -1857,20 +1856,20 @@ void SetupToolbarMenu( ### Parameters -*menu*
+*`menu`*\ [in] A `CMenu` object to be modified. -*uiViewUserToolbarCmdFirst*
+*`uiViewUserToolbarCmdFirst`*\ [in] The first user-defined command. -*uiViewUserToolbarCmdLast*
+*`uiViewUserToolbarCmdLast`*\ [in] The last user-defined command. ### Remarks -The framework stores user-defined commands in a list. Use *uiViewUserToolbarCmdFirst* and *uiViewUserToolbarCmdList* to specify the indexes of the commands to insert. +The framework stores user-defined commands in a list. Use *`uiViewUserToolbarCmdFirst`* and *`uiViewUserToolbarCmdList`* to specify the indexes of the commands to insert. -## CFrameWndEx::ShowFullScreen +## `CFrameWndEx::ShowFullScreen` Switches the main frame between full-screen mode and regular mode. @@ -1878,7 +1877,7 @@ Switches the main frame between full-screen mode and regular mode. void ShowFullScreen(); ``` -## CFrameWndEx::ShowPane +## `CFrameWndEx::ShowPane` Shows or hides the specified pane. @@ -1892,19 +1891,19 @@ void ShowPane( ### Parameters -*pBar*
+*`pBar`*\ [in] A pointer to the control bar to show or hide. -*bShow*
-[in] If TRUE, the application shows the control bar. Otherwise, the application hides the control bar. +*`bShow`*\ +[in] If `TRUE`, the application shows the control bar. Otherwise, the application hides the control bar. -*bDelay*
-[in] If TRUE, delay the adjustment of the docking layout until the framework calls [CFrameWndEx::AdjustDockingLayout](#adjustdockinglayout). Otherwise, recalculate the docking layout immediately. +*`bDelay`*\ +[in] If `TRUE`, delay the adjustment of the docking layout until the framework calls [`CFrameWndEx::AdjustDockingLayout`](#adjustdockinglayout). Otherwise, recalculate the docking layout immediately. -*bActivate*
-[in] If TRUE, make the control bar active. Otherwise, display the control bar in an inactive state. +*`bActivate`*\ +[in] If `TRUE`, make the control bar active. Otherwise, display the control bar in an inactive state. -## CFrameWndEx::UpdateCaption +## `CFrameWndEx::UpdateCaption` Called by the framework to update the window frame caption. @@ -1914,7 +1913,7 @@ void UpdateCaption(); ### Remarks -## CFrameWndEx::WinHelp +## `CFrameWndEx::WinHelp` Invokes either the WinHelp application or context related help. @@ -1926,16 +1925,16 @@ virtual void WinHelp( ### Parameters -*dwData*
-Data that depends on the *nCmd* parameter. For a list of possible values see [WinHelp](/windows/win32/api/winuser/nf-winuser-winhelpw). +*`dwData`*\ +Data that depends on the *`nCmd`* parameter. For a list of possible values see [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw). -*nCmd*
-The help command. For a list of possible values see [WinHelp](/windows/win32/api/winuser/nf-winuser-winhelpw). +*`nCmd`*\ +The help command. For a list of possible values see [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw). ### Remarks ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CFrameWnd](../../mfc/reference/cframewnd-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CFrameWnd`](../../mfc/reference/cframewnd-class.md) diff --git a/docs/mfc/reference/cftpconnection-class.md b/docs/mfc/reference/cftpconnection-class.md index 5fd943b04e..aae3de670a 100644 --- a/docs/mfc/reference/cftpconnection-class.md +++ b/docs/mfc/reference/cftpconnection-class.md @@ -369,7 +369,7 @@ A pointer to a [CInternetFile](../../mfc/reference/cinternetfile-class.md) objec - An application needs a fine level of control over a file transfer. For example, the application may want to display a progress control indicate the progress of the file transfer status while downloading a file. -After calling `OpenFile` and until calling `CInternetConnection::Close`, the application can only call [CInternetFile::Read](../../mfc/reference/cinternetfile-class.md#read), [CInternetFile::Write](../../mfc/reference/cinternetfile-class.md#write), `CInternetConnection::Close`, or [CFtpFileFind::FindFile](../../mfc/reference/cftpfilefind-class.md#findfile). Calls to other FTP functions for the same FTP session will fail and set the error code to FTP_ETRANSFER_IN_PROGRESS. +After calling `OpenFile` and until calling `CInternetFile::Close`, the application can only call [CInternetFile::Read](../../mfc/reference/cinternetfile-class.md#read), [CInternetFile::Write](../../mfc/reference/cinternetfile-class.md#write), `CInternetConnection::Close`, or [CFtpFileFind::FindFile](../../mfc/reference/cftpfilefind-class.md#findfile). Calls to other FTP functions for the same FTP session will fail and set the error code to FTP_ETRANSFER_IN_PROGRESS. The *pstrFileName* parameter can be either a partially qualified filename relative to the current directory or fully qualified. A backslash (\\) or forward slash (/) can be used as the directory separator for either name. `OpenFile` translates the directory name separators to the appropriate characters before using it. diff --git a/docs/mfc/reference/cftpfilefind-class.md b/docs/mfc/reference/cftpfilefind-class.md index e5080e3719..f43026aff1 100644 --- a/docs/mfc/reference/cftpfilefind-class.md +++ b/docs/mfc/reference/cftpfilefind-class.md @@ -100,7 +100,7 @@ virtual BOOL FindFile( A pointer to a string containing the name of the file to find. If NULL, the call will do a wildcard search (*). *dwFlags*
-The flags describing how to handle this session. These flags can be combined with the bitwise OR operator (|) and are as follows: +The flags describing how to handle this session. These flags can be combined with the bitwise OR operator (**`|`**) and are as follows: - `INTERNET_FLAG_RELOAD` Get the data from the wire even if it's locally cached. This is the default flag. diff --git a/docs/mfc/reference/cgopherconnection-class.md b/docs/mfc/reference/cgopherconnection-class.md index 585855bbfe..d05ead9a3a 100644 --- a/docs/mfc/reference/cgopherconnection-class.md +++ b/docs/mfc/reference/cgopherconnection-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CGopherConnection Class" title: "CGopherConnection Class" +description: "Learn more about: CGopherConnection Class" ms.date: "11/04/2016" f1_keywords: ["CGopherConnection", "AFXINET/CGopherConnection", "AFXINET/CGopherConnection::CGopherConnection", "AFXINET/CGopherConnection::CreateLocator", "AFXINET/CGopherConnection::GetAttribute", "AFXINET/CGopherConnection::OpenFile"] helpviewer_keywords: ["CGopherConnection [MFC], CGopherConnection", "CGopherConnection [MFC], CreateLocator", "CGopherConnection [MFC], GetAttribute", "CGopherConnection [MFC], OpenFile"] -ms.assetid: b5b96aea-ac99-430e-bd84-d1372b43f78f --- # CGopherConnection Class @@ -167,8 +166,9 @@ Call this member function to retrieve specific attribute information about an it ``` BOOL GetAttribute( - CGopherLocator& refLocator CString strRequestedAttributes, - CString& strResult,); + CGopherLocator& refLocator, + CString strRequestedAttributes, + CString& strResult); ``` ### Parameters @@ -222,11 +222,11 @@ Override the *dwContext* default to set the context identifier to a value of you ## See also -[CInternetConnection Class](../../mfc/reference/cinternetconnection-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CFtpConnection Class](../../mfc/reference/cftpconnection-class.md)
-[CHttpConnection Class](../../mfc/reference/chttpconnection-class.md)
-[CInternetConnection Class](../../mfc/reference/cinternetconnection-class.md)
-[CGopherLocator Class](../../mfc/reference/cgopherlocator-class.md)
-[CGopherFile Class](../../mfc/reference/cgopherfile-class.md)
+[CInternetConnection Class](../../mfc/reference/cinternetconnection-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[CFtpConnection Class](../../mfc/reference/cftpconnection-class.md)\ +[CHttpConnection Class](../../mfc/reference/chttpconnection-class.md)\ +[CInternetConnection Class](../../mfc/reference/cinternetconnection-class.md)\ +[CGopherLocator Class](../../mfc/reference/cgopherlocator-class.md)\ +[CGopherFile Class](../../mfc/reference/cgopherfile-class.md)\ [CInternetSession Class](../../mfc/reference/cinternetsession-class.md) diff --git a/docs/mfc/reference/chtmlview-class.md b/docs/mfc/reference/chtmlview-class.md index c80f7c30ea..d19b1de124 100644 --- a/docs/mfc/reference/chtmlview-class.md +++ b/docs/mfc/reference/chtmlview-class.md @@ -69,27 +69,27 @@ class CHtmlView : public CFormView |[`CHtmlView::OnEnableModeless`](#onenablemodeless)|Called to enable or disable modeless dialog boxes when the container creates or destroys a modal dialog box.| |[`CHtmlView::OnFilterDataObject`](#onfilterdataobject)|Called on the host by Internet Explorer or MSHTML to allow the host to replace Internet Explorer or MSHTML's data object.| |[`CHtmlView::OnFrameWindowActivate`](#onframewindowactivate)|Called from [`IOleInPlaceActiveObject::OnFrameWindowActivate`](/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-onframewindowactivate) to notify the object when the container's top-level frame window is activated or deactivated.| -|[`CHtmlView::OnFullScreen`](#onfullscreen)|Called when the FullScreen property has changed.| +|[`CHtmlView::OnFullScreen`](#onfullscreen)|Called when the `FullScreen` property has changed.| |[`CHtmlView::OnGetDropTarget`](#ongetdroptarget)|Called by Internet Explorer or MSHTML when it's being used as a drop target to allow the host to supply an alternative [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget).| |[`CHtmlView::OnGetExternal`](#ongetexternal)|Called by Internet Explorer or MSHTML to obtain the host's `IDispatch` interface.| |[`CHtmlView::OnGetHostInfo`](#ongethostinfo)|Retrieves the UI capabilities of the Internet Explorer or MSHTML host.| |[`CHtmlView::OnGetOptionKeyPath`](#ongetoptionkeypath)|Returns the registry key under which Internet Explorer or MSHTML stores user preferences.| |[`CHtmlView::OnHideUI`](#onhideui)|Called when Internet Explorer or MSHTML removes its menus and toolbars.| -|[`CHtmlView::OnMenuBar`](#onmenubar)|Called when the MenuBar property has changed.| +|[`CHtmlView::OnMenuBar`](#onmenubar)|Called when the `MenuBar` property has changed.| |[`CHtmlView::OnNavigateComplete2`](#onnavigatecomplete2)|Called after navigation to a hyperlink completes (on either a window or frameset element).| |[`CHtmlView::OnNavigateError`](#onnavigateerror)|Called by the framework if navigation to a hyperlink fails.| |[`CHtmlView::OnNewWindow2`](#onnewwindow2)|Called when a new window is to be created for displaying a resource.| |[`CHtmlView::OnProgressChange`](#onprogresschange)|Called to notify an application that the progress of a download operation has been updated.| -|[`CHtmlView::OnPropertyChange`](#onpropertychange)|Called to notify an application that the [PutProperty](#putproperty) method has changed the value of a property.| +|[`CHtmlView::OnPropertyChange`](#onpropertychange)|Called to notify an application that the [`PutProperty`](#putproperty) method has changed the value of a property.| |[`CHtmlView::OnQuit`](#onquit)|Called to notify an application that the Internet Explorer application is ready to quit. (Applies to Internet Explorer only)| |[`CHtmlView::OnResizeBorder`](#onresizeborder)|Called from the Internet Explorer or MSHTML implementation of [`IOleInPlaceActiveObject::ResizeBorder`](/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-resizeborder), which alerts the object that it needs to resize its border space.| |[`CHtmlView::OnShowContextMenu`](#onshowcontextmenu)|Called from Internet Explorer or MSHTML when it's about to show its context menu.| |[`CHtmlView::OnShowUI`](#onshowui)|Called before Internet Explorer or MSHTML displays its menus and toolbars.| -|[`CHtmlView::OnStatusBar`](#onstatusbar)|Called when the StatusBar property has changed.| +|[`CHtmlView::OnStatusBar`](#onstatusbar)|Called when the `StatusBar` property has changed.| |[`CHtmlView::OnStatusTextChange`](#onstatustextchange)|Called to notify an application that the text of the status bar associated with the WebBrowser control has changed.| -|[`CHtmlView::OnTheaterMode`](#ontheatermode)|Called when the TheaterMode property has changed.| +|[`CHtmlView::OnTheaterMode`](#ontheatermode)|Called when the `TheaterMode` property has changed.| |[`CHtmlView::OnTitleChange`](#ontitlechange)|Called to notify an application if the title of a document in the WebBrowser control becomes available or changes.| -|[`CHtmlView::OnToolBar`](#ontoolbar)|Called when the ToolBar property has changed.| +|[`CHtmlView::OnToolBar`](#ontoolbar)|Called when the `ToolBar` property has changed.| |[`CHtmlView::OnTranslateAccelerator`](#ontranslateaccelerator)|Called by Internet Explorer or MSHTML when [`IOleInPlaceActiveObject::TranslateAccelerator`](/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-translateaccelerator) or [`IOleControlSite::TranslateAccelerator`](/windows/win32/api/ocidl/nf-ocidl-iolecontrolsite-translateaccelerator) is called to process menu accelerator-key messages from the container's message queue.| |[`CHtmlView::OnTranslateUrl`](#ontranslateurl)|Called by Internet Explorer or MSHTML to allow the host an opportunity to modify the URL to be loaded.| |[`CHtmlView::OnUpdateUI`](#onupdateui)|Notifies the host that the command state has changed.| @@ -120,7 +120,7 @@ class CHtmlView : public CFormView The WebBrowser control is a window in which the user can browse sites on the World Wide Web, and folders in the local file system and on a network. The WebBrowser control supports hyperlinking, Uniform Resource Locator (URL) navigation, and maintains a history list. -## Using the CHtmlView Class in an MFC Application +## Using the `CHtmlView` Class in an MFC Application In the standard MFC framework application (either SDI or MDI based), the view object is commonly derived from a specialized set of classes. These classes, all derived from `CView`, provide specialized functionality beyond that provided by `CView`. @@ -599,7 +599,7 @@ BOOL GetSilent() const; ### Return Value -Nonzero if dialog boxes cannot be displayed from the WebBrowser control; otherwise zero. +Nonzero if dialog boxes can't be displayed from the WebBrowser control; otherwise zero. ### Remarks @@ -837,7 +837,7 @@ void Navigate( A caller-allocated string that contains the URL to navigate to, or the full path of the file to display. *`dwFlags`*\ -The flags of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [BrowserNavConstants](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. +The flags of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [`BrowserNavConstants`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. *`lpszTargetFrameName`*\ A pointer to a string that contains the name of the frame in which to display the resource. @@ -887,7 +887,7 @@ void Navigate2( A pointer to an [`ITEMIDLIST`](/windows/win32/api/shtypes/ns-shtypes-itemidlist) structure. *`dwFlags`*\ -The flags of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [BrowserNavConstants](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. +The flags of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the [`BrowserNavConstants`](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768360\(v=vs.85\)) enumeration. *`lpszTargetFrameName`*\ A pointer to a string that contains the name of the frame in which to display the resource. @@ -905,7 +905,7 @@ Length in bytes of the data pointed to by the *`lpvPostData`* parameter. A pointer to a value that specifies the HTTP or HTTPS headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify such things as the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if *`URL`* isn't an HTTP or HTTPS URL. *`baPostedData`*\ -A reference to a [CByteArray](../../mfc/reference/cbytearray-class.md) object. +A reference to a [`CByteArray`](../../mfc/reference/cbytearray-class.md) object. ### Remarks @@ -1063,7 +1063,7 @@ virtual HRESULT OnFilterDataObject( ### Parameters *`pDataObject`*\ -Address of the [IDataObject](/windows/win32/api/objidl/nn-objidl-idataobject) interface supplied by Internet Explorer or MSHTML. +Address of the [`IDataObject`](/windows/win32/api/objidl/nn-objidl-idataobject) interface supplied by Internet Explorer or MSHTML. *`ppDataObject`*\ Address that receives the `IDataObject` interface pointer supplied by the host. The contents of this parameter should always be initialized to `NULL`, even if the method fails. @@ -1273,7 +1273,7 @@ The URL for which navigation failed. The name of the frame in which the resource is to be displayed, or `NULL` if no named frame was targeted for the resource. *`dwError`*\ -An error status code, if available. For a list of the possible `HRESULT` and HTTP status codes, see [NavigateError Event Status Codes.](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768365\(v=vs.85\)). +An error status code, if available. For a list of the possible `HRESULT` and HTTP status codes, see [`NavigateError` Event Status Codes.](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa768365\(v=vs.85\)). *`pbCancel`*\ Specifies whether to cancel the navigation to an error page or any further autosearch. If `TRUE` (the default), continue with navigation to an error page or autosearch; if `FALSE`, cancel navigation to an error page or autosearch. @@ -1748,7 +1748,7 @@ void Refresh2(int nLevel); ### Parameters *`nLevel`*\ -The address of the variable specifying the refresh level. The possible variables are defined in [RefreshConstants](/previous-versions/aa768363\(v=vs.85\)), in the Windows SDK. +The address of the variable specifying the refresh level. The possible variables are defined in [`RefreshConstants`](/previous-versions/aa768363\(v=vs.85\)), in the Windows SDK. ### Remarks @@ -2025,7 +2025,7 @@ Applies to Internet Explorer and WebBrowser. ## See also -[MFC Sample MFCIE](../../overview/visual-cpp-samples.md)\ +[MFC Sample `MFCIE`](../../overview/visual-cpp-samples.md)\ [`CFormView` class](../../mfc/reference/cformview-class.md)\ [Hierarchy chart](../../mfc/hierarchy-chart.md)\ [`IWebBrowser2`](/windows/win32/api/exdisp/nn-exdisp-iwebbrowser2) diff --git a/docs/mfc/reference/cimagelist-class.md b/docs/mfc/reference/cimagelist-class.md index 184a95db73..ca80bcc33e 100644 --- a/docs/mfc/reference/cimagelist-class.md +++ b/docs/mfc/reference/cimagelist-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CImageList Class" title: "CImageList Class" -ms.date: "11/04/2016" +description: "Learn more about: CImageList Class" +ms.date: 11/04/2016 f1_keywords: ["CImageList", "AFXCMN/CImageList", "AFXCMN/CImageList::CImageList", "AFXCMN/CImageList::Add", "AFXCMN/CImageList::Attach", "AFXCMN/CImageList::BeginDrag", "AFXCMN/CImageList::Copy", "AFXCMN/CImageList::Create", "AFXCMN/CImageList::DeleteImageList", "AFXCMN/CImageList::DeleteTempMap", "AFXCMN/CImageList::Detach", "AFXCMN/CImageList::DragEnter", "AFXCMN/CImageList::DragLeave", "AFXCMN/CImageList::DragMove", "AFXCMN/CImageList::DragShowNolock", "AFXCMN/CImageList::Draw", "AFXCMN/CImageList::DrawEx", "AFXCMN/CImageList::DrawIndirect", "AFXCMN/CImageList::EndDrag", "AFXCMN/CImageList::ExtractIcon", "AFXCMN/CImageList::FromHandle", "AFXCMN/CImageList::FromHandlePermanent", "AFXCMN/CImageList::GetBkColor", "AFXCMN/CImageList::GetDragImage", "AFXCMN/CImageList::GetImageCount", "AFXCMN/CImageList::GetImageInfo", "AFXCMN/CImageList::GetSafeHandle", "AFXCMN/CImageList::Read", "AFXCMN/CImageList::Remove", "AFXCMN/CImageList::Replace", "AFXCMN/CImageList::SetBkColor", "AFXCMN/CImageList::SetDragCursorImage", "AFXCMN/CImageList::SetImageCount", "AFXCMN/CImageList::SetOverlayImage", "AFXCMN/CImageList::Write", "AFXCMN/CImageList::m_hImageList"] helpviewer_keywords: ["CImageList [MFC], CImageList", "CImageList [MFC], Add", "CImageList [MFC], Attach", "CImageList [MFC], BeginDrag", "CImageList [MFC], Copy", "CImageList [MFC], Create", "CImageList [MFC], DeleteImageList", "CImageList [MFC], DeleteTempMap", "CImageList [MFC], Detach", "CImageList [MFC], DragEnter", "CImageList [MFC], DragLeave", "CImageList [MFC], DragMove", "CImageList [MFC], DragShowNolock", "CImageList [MFC], Draw", "CImageList [MFC], DrawEx", "CImageList [MFC], DrawIndirect", "CImageList [MFC], EndDrag", "CImageList [MFC], ExtractIcon", "CImageList [MFC], FromHandle", "CImageList [MFC], FromHandlePermanent", "CImageList [MFC], GetBkColor", "CImageList [MFC], GetDragImage", "CImageList [MFC], GetImageCount", "CImageList [MFC], GetImageInfo", "CImageList [MFC], GetSafeHandle", "CImageList [MFC], Read", "CImageList [MFC], Remove", "CImageList [MFC], Replace", "CImageList [MFC], SetBkColor", "CImageList [MFC], SetDragCursorImage", "CImageList [MFC], SetImageCount", "CImageList [MFC], SetOverlayImage", "CImageList [MFC], Write", "CImageList [MFC], m_hImageList"] -ms.assetid: b6d1a704-1c82-4548-8a8f-77972adc98a5 --- # `CImageList` Class @@ -359,7 +358,7 @@ Nonzero if successful; otherwise 0. ## `CImageList::DeleteTempMap` -Called automatically by the `CWinApp` idle-time handler, `DeleteTempMap` deletes any temporary `CImageList` objects created by [FromHandle](#fromhandle), but does not destroy any handles ( `hImageList`) temporarily associated with the `ImageList` objects. +Called automatically by the `CWinApp` idle-time handler, `DeleteTempMap` deletes any temporary `CImageList` objects created by [FromHandle](#fromhandle), but does not destroy any handles (`hImageList`) temporarily associated with the `ImageList` objects. ``` static void PASCAL DeleteTempMap(); diff --git a/docs/mfc/reference/cinternetexception-class.md b/docs/mfc/reference/cinternetexception-class.md index 9d9ccae462..0af84f7303 100644 --- a/docs/mfc/reference/cinternetexception-class.md +++ b/docs/mfc/reference/cinternetexception-class.md @@ -90,7 +90,7 @@ DWORD m_dwError; This error value may be a system error code, found in WINERROR.H, or an error value from WININET.H. -For a list of Win32 error codes, see [Error Codes](/windows/win32/Debug/system-error-codes). For a list of Internet-specific error messages, see . Both topics are in the Windows SDK. +For a list of Win32 error codes, see [Error Codes](/windows/win32/Debug/system-error-codes). ## See also diff --git a/docs/mfc/reference/cinternetsession-class.md b/docs/mfc/reference/cinternetsession-class.md index 88743ba0a6..bc6087fc38 100644 --- a/docs/mfc/reference/cinternetsession-class.md +++ b/docs/mfc/reference/cinternetsession-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: CInternetSession Class" title: "CInternetSession Class" +description: "Learn more about: CInternetSession Class" ms.date: "06/20/2018" f1_keywords: ["CInternetSession", "AFXINET/CInternetSession", "AFXINET/CInternetSession::CInternetSession", "AFXINET/CInternetSession::Close", "AFXINET/CInternetSession::EnableStatusCallback", "AFXINET/CInternetSession::GetContext", "AFXINET/CInternetSession::GetCookie", "AFXINET/CInternetSession::GetCookieLength", "AFXINET/CInternetSession::GetFtpConnection", "AFXINET/CInternetSession::GetGopherConnection", "AFXINET/CInternetSession::GetHttpConnection", "AFXINET/CInternetSession::OnStatusCallback", "AFXINET/CInternetSession::OpenURL", "AFXINET/CInternetSession::SetCookie", "AFXINET/CInternetSession::SetOption"] helpviewer_keywords: ["CInternetSession [MFC], CInternetSession", "CInternetSession [MFC], Close", "CInternetSession [MFC], EnableStatusCallback", "CInternetSession [MFC], GetContext", "CInternetSession [MFC], GetCookie", "CInternetSession [MFC], GetCookieLength", "CInternetSession [MFC], GetFtpConnection", "CInternetSession [MFC], GetGopherConnection", "CInternetSession [MFC], GetHttpConnection", "CInternetSession [MFC], OnStatusCallback", "CInternetSession [MFC], OpenURL", "CInternetSession [MFC], SetCookie", "CInternetSession [MFC], SetOption"] -ms.assetid: ef54feb4-9d0f-4e65-a45d-7a4cf6c40e51 --- -# CInternetSession Class +# `CInternetSession` Class Creates and initializes a single or several simultaneous Internet sessions and, if necessary, describes your connection to a proxy server. @@ -22,64 +21,64 @@ class CInternetSession : public CObject |Name|Description| |----------|-----------------| -|[CInternetSession::CInternetSession](#cinternetsession)|Constructs a `CInternetSession` object.| +|[`CInternetSession::CInternetSession`](#cinternetsession)|Constructs a `CInternetSession` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CInternetSession::Close](#close)|Closes the Internet connection when the Internet session is terminated.| -|[CInternetSession::EnableStatusCallback](#enablestatuscallback)|Establishes a status callback routine.| -|[CInternetSession::GetContext](#getcontext)|Closes the Internet connection when the Internet session is terminated.| -|[CInternetSession::GetCookie](#getcookie)|Returns cookies for the specified URL and all its parent URLs.| -|[CInternetSession::GetCookieLength](#getcookielength)|Retrieves the variable specifying the length of the cookie stored in the buffer.| -|[CInternetSession::GetFtpConnection](#getftpconnection)|Opens an FTP session with a server. Logs on the user.| -|[CInternetSession::GetGopherConnection](#getgopherconnection)|Opens a gopher server for an application that is trying to open a connection.| -|[CInternetSession::GetHttpConnection](#gethttpconnection)|Opens an HTTP server for an application that is trying to open a connection.| -|[CInternetSession::OnStatusCallback](#onstatuscallback)|Updates the status of an operation when status callback is enabled.| -|[CInternetSession::OpenURL](#openurl)|Parses and opens a URL.| -|[CInternetSession::SetCookie](#setcookie)|Sets a cookie for the specified URL.| -|[CInternetSession::SetOption](#setoption)|Sets options for the Internet session.| +|[`CInternetSession::Close`](#close)|Closes the Internet connection when the Internet session is terminated.| +|[`CInternetSession::EnableStatusCallback`](#enablestatuscallback)|Establishes a status callback routine.| +|[`CInternetSession::GetContext`](#getcontext)|Closes the Internet connection when the Internet session is terminated.| +|[`CInternetSession::GetCookie`](#getcookie)|Returns cookies for the specified URL and all its parent URLs.| +|[`CInternetSession::GetCookieLength`](#getcookielength)|Retrieves the variable specifying the length of the cookie stored in the buffer.| +|[`CInternetSession::GetFtpConnection`](#getftpconnection)|Opens an FTP session with a server. Logs on the user.| +|[`CInternetSession::GetGopherConnection`](#getgopherconnection)|Opens a gopher server for an application that is trying to open a connection.| +|[`CInternetSession::GetHttpConnection`](#gethttpconnection)|Opens an HTTP server for an application that is trying to open a connection.| +|[`CInternetSession::OnStatusCallback`](#onstatuscallback)|Updates the status of an operation when status callback is enabled.| +|[`CInternetSession::OpenURL`](#openurl)|Parses and opens a URL.| +|[`CInternetSession::SetCookie`](#setcookie)|Sets a cookie for the specified URL.| +|[`CInternetSession::SetOption`](#setoption)|Sets options for the Internet session.| ### Public Operators |Name|Description| |----------|-----------------| -|[CInternetSession::operator HINTERNET](#operator_hinternet)|A handle to the current Internet session.| +|[`CInternetSession::operator HINTERNET`](#operator_hinternet)|A handle to the current Internet session.| ## Remarks -If your Internet connection must be maintained for the duration of an application, you can create a `CInternetSession` member of the class [CWinApp](../../mfc/reference/cwinapp-class.md). +If your Internet connection must be maintained for the duration of an application, you can create a `CInternetSession` member of the class [`CWinApp`](../../mfc/reference/cwinapp-class.md). -Once you have established an Internet session, you can call [OpenURL](#openurl). `CInternetSession` then parses the URL for you by calling the global function [AfxParseURL](internet-url-parsing-globals.md#afxparseurl). Regardless of its protocol type, `CInternetSession` interprets the URL and manages it for you. It can handle requests for local files identified with the URL resource "file://". `OpenURL` will return a pointer to a [CStdioFile](../../mfc/reference/cstdiofile-class.md) object if the name you pass it is a local file. +Once you've established an Internet session, you can call [`OpenURL`](#openurl). `CInternetSession` then parses the URL for you by calling the global function [`AfxParseURL`](internet-url-parsing-globals.md#afxparseurl). Regardless of its protocol type, `CInternetSession` interprets the URL and manages it for you. It can handle requests for local files identified with the URL resource "file://". `OpenURL` will return a pointer to a [`CStdioFile`](../../mfc/reference/cstdiofile-class.md) object if the name you pass it is a local file. If you open a URL on an Internet server using `OpenURL`, you can read information from the site. If you want to perform service-specific (for example, HTTP, FTP, or gopher) actions on files located on a server, you must establish the appropriate connection with that server. To open a particular kind of connection directly to a particular service, use one of the following member functions: -- [GetGopherConnection](#getgopherconnection) to open a connection to a gopher service. +- [`GetGopherConnection`](#getgopherconnection) to open a connection to a gopher service. -- [GetHttpConnection](#gethttpconnection) to open a connection to an HTTP service. +- [`GetHttpConnection`](#gethttpconnection) to open a connection to an HTTP service. -- [GetFtpConnection](#getftpconnection) to open a connection to an FTP service. +- [`GetFtpConnection`](#getftpconnection) to open a connection to an FTP service. -[SetOption](#setoption) allows you to set the query options of your session, such as time-out values, number of retries, and so on. +[`SetOption`](#setoption) allows you to set the query options of your session, such as time-out values, number of retries, and so on. -`CInternetSession` member functions [SetCookie](#setcookie), [GetCookie](#getcookie), and [GetCookieLength](#getcookielength) provide the means to manage a Win32 cookie database, through which servers and scripts maintain state information about the client workstation. +`CInternetSession` member functions [`SetCookie`](#setcookie), [`GetCookie`](#getcookie), and [`GetCookieLength`](#getcookielength) provide the means to manage a Win32 cookie database, through which servers and scripts maintain state information about the client workstation. -For more information about basic Internet programming tasks, see the article [Internet First Steps: WinInet](../../mfc/wininet-basics.md). For general information about using the MFC WinInet classes, see the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md). +For more information about basic Internet programming tasks, see the article [Internet First Steps: `WinInet`](../../mfc/wininet-basics.md). For general information about using the MFC `WinInet` classes, see the article [Internet Programming with `WinInet`](../../mfc/win32-internet-extensions-wininet.md). > [!NOTE] -> `CInternetSession` will throw an [AfxThrowNotSupportedException](exception-processing.md#afxthrownotsupportedexception) for unsupported service types. Only the following service types are currently supported: FTP, HTTP, gopher, and file. +> `CInternetSession` will throw an [`AfxThrowNotSupportedException`](exception-processing.md#afxthrownotsupportedexception) for unsupported service types. Only the following service types are currently supported: FTP, HTTP, gopher, and file. ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md)
-    `CInternetSession` +[`CObject`](../../mfc/reference/cobject-class.md)\ + `CInternetSession` ## Requirements -**Header:** afxinet.h +**Header:** `afxinet.h` -## CInternetSession::CInternetSession +## `CInternetSession::CInternetSession` This member function is called when a `CInternetSession` object is created. @@ -95,47 +94,47 @@ CInternetSession( ### Parameters -*pstrAgent*
-A pointer to a string that identifies the name of the application or entity calling the Internet functions (for example, "Microsoft Internet Browser"). If *pstrAgent* is NULL (the default), the framework calls the global function [AfxGetAppName](application-information-and-management.md#afxgetappname), which returns a null-terminated string containing an application's name. Some protocols use this string to identify your application to the server. +*`pstrAgent`*\ +A pointer to a string that identifies the name of the application or entity calling the Internet functions (for example, "Microsoft Internet Browser"). If *`pstrAgent`* is `NULL` (the default), the framework calls the global function [`AfxGetAppName`](application-information-and-management.md#afxgetappname), which returns a null-terminated string containing an application's name. Some protocols use this string to identify your application to the server. -*dwContext*
-The context identifier for the operation. *dwContext* identifies the operation's status information returned by [CInternetSession::OnStatusCallback](#onstatuscallback). The default is set to 1; however, you can explicitly assign a specific context ID for the operation. The object and any work it does will be associated with that context ID. +*`dwContext`*\ +The context identifier for the operation. *`dwContext`* identifies the operation's status information returned by [`CInternetSession::OnStatusCallback`](#onstatuscallback). The default is set to 1; however, you can explicitly assign a specific context ID for the operation. The object and any work it does will be associated with that context ID. -*dwAccessType*
+*`dwAccessType`*\ The type of access required. The following are valid values, exactly one of which may be supplied: -- INTERNET_OPEN_TYPE_PRECONFIG Connect using preconfigured settings in the registry. This access type is set as the default. To connect through a TIS proxy, set *dwAccessType* to this value; you then set the registry appropriately. +- `INTERNET_OPEN_TYPE_PRECONFIG` Connect using preconfigured settings in the registry. This access type is set as the default. To connect through a TIS proxy, set *`dwAccessType`* to this value; you then set the registry appropriately. -- INTERNET_OPEN_TYPE_DIRECT Connect directly to Internet. +- `INTERNET_OPEN_TYPE_DIRECT` Connect directly to Internet. -- INTERNET_OPEN_TYPE_PROXY Connect through a CERN proxy. +- `INTERNET_OPEN_TYPE_PROXY` Connect through a CERN proxy. For information on connecting with different types of proxies, see [Steps in a Typical FTP Client Application](../../mfc/steps-in-a-typical-ftp-client-application.md). -*pstrProxyName*
-The name of the preferred CERN proxy if *dwAccessType* is set as INTERNET_OPEN_TYPE_PROXY. The default is NULL. +*`pstrProxyName`*\ +The name of the preferred CERN proxy if *`dwAccessType`* is set as `INTERNET_OPEN_TYPE_PROXY`. The default is `NULL`. -*pstrProxyBypass*
-A pointer to a string containing an optional list of server addresses. These addresses may be bypassed when using proxy access. If a NULL value is supplied, the bypass list will be read from the registry. This parameter is meaningful only if *dwAccessType* is set to INTERNET_OPEN_TYPE_PROXY. +*`pstrProxyBypass`*\ +A pointer to a string containing an optional list of server addresses. These addresses may be bypassed when using proxy access. If a `NULL` value is supplied, the bypass list will be read from the registry. This parameter is meaningful only if *`dwAccessType`* is set to `INTERNET_OPEN_TYPE_PROXY`. -*dwFlags*
+*`dwFlags`*\ Indicates various caching options. The default is set to 0. The possible values include: -- INTERNET_FLAG_DONT_CACHE Do not cache the data, either locally or in any gateway servers. +- `INTERNET_FLAG_DONT_CACHE` Don't cache the data, either locally or in any gateway servers. -- INTERNET_FLAG_OFFLINE Download operations are satisfied through the persistent cache only. If the item does not exist in the cache, an appropriate error code is returned. This flag may be combined with the bitwise **OR** ( **|**) operator. +- `INTERNET_FLAG_OFFLINE` Download operations are satisfied through the persistent cache only. If the item doesn't exist in the cache, an appropriate error code is returned. This flag may be combined with the bitwise "or" (`|`) operator. ### Remarks `CInternetSession` is the first Internet function called by an application. It initializes internal data structures and prepares for future calls from the application. -If no Internet connection can be opened, `CInternetSession` throws an [AfxThrowInternetException](internet-url-parsing-globals.md#afxthrowinternetexception). +If no Internet connection can be opened, `CInternetSession` throws an [`AfxThrowInternetException`](internet-url-parsing-globals.md#afxthrowinternetexception). ### Example -See the example for [CFtpFileFind](../../mfc/reference/cftpfilefind-class.md). +See the example for [`CFtpFileFind`](../../mfc/reference/cftpfilefind-class.md). -## CInternetSession::Close +## `CInternetSession::Close` Call this member function when your application has finished using the `CInternetSession` object. @@ -145,9 +144,9 @@ virtual void Close(); ### Example -See the example for [CFtpFileFind](../../mfc/reference/cftpfilefind-class.md). +See the example for [`CFtpFileFind`](../../mfc/reference/cftpfilefind-class.md). -## CInternetSession::EnableStatusCallback +## `CInternetSession::EnableStatusCallback` Call this member function to enable status callback. @@ -157,12 +156,12 @@ BOOL EnableStatusCallback(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-Specifies whether callback is enabled or disabled. The default is TRUE. +*`bEnable`*\ +Specifies whether callback is enabled or disabled. The default is `TRUE`. ### Return Value -Nonzero if successful; otherwise 0. If the call fails, determine the cause of the failure by examining the thrown [CInternetException](../../mfc/reference/cinternetexception-class.md) object. +Nonzero if successful; otherwise 0. If the call fails, determine the cause of the failure by examining the thrown [`CInternetException`](../../mfc/reference/cinternetexception-class.md) object. ### Remarks @@ -170,11 +169,11 @@ When handling status callback, you can provide status about the progress of the Because callbacks occur during the request's processing, the application should spend as little time as possible in the callback to prevent degradation of data throughput to the network. For example, putting up a dialog box in a callback may be such a lengthy operation that the server terminates the request. -The status callback cannot be removed as long as any callbacks are pending. +The status callback can't be removed as long as any callbacks are pending. To handle any operations asynchronously, you must either create your own thread or use the WinInet functions without MFC. -## CInternetSession::GetContext +## `CInternetSession::GetContext` Call this member function to get the context value for a particular application session. @@ -188,13 +187,13 @@ The application-defined context Identifier. ### Remarks -[OnStatusCallback](#onstatuscallback) uses the context ID returned by `GetContext` to report the status of a particular application. For example, when a user activates an Internet request that involves returning status information, the status callback uses the context ID to report status on that particular request. If the user activates two separate Internet requests that both involve returning status information, `OnStatusCallback` uses the context identifiers to return status about their corresponding requests. Consequently, the context identifier is used for all status callback operations, and it is associated with the session until the session is ended. +[`OnStatusCallback`](#onstatuscallback) uses the context ID returned by `GetContext` to report the status of a particular application. For example, when a user activates an Internet request that involves returning status information, the status callback uses the context ID to report status on that particular request. If the user activates two separate Internet requests that both involve returning status information, `OnStatusCallback` uses the context identifiers to return status about their corresponding requests. Consequently, the context identifier is used for all status callback operations, and it's associated with the session until the session is ended. For more information about asynchronous operations, see the article [Internet First Steps: WinInet](../../mfc/wininet-basics.md). -## CInternetSession::GetCookie +## `CInternetSession::GetCookie` -This member function implements the behavior of the Win32 function [InternetGetCookie](/windows/win32/api/wininet/nf-wininet-internetgetcookiew), as described in the Windows SDK. +This member function implements the behavior of the Win32 function [`InternetGetCookie`](/windows/win32/api/wininet/nf-wininet-internetgetcookiew), as described in the Windows SDK. ```cpp static BOOL GetCookie( @@ -211,31 +210,31 @@ static BOOL GetCookie( ### Parameters -*pstrUrl*
+*`pstrUrl`*\ A pointer to a string containing the URL. -*pstrCookieName*
+*`pstrCookieName`*\ A pointer to a string containing the name of the cookie to get for the specified URL. -*pstrCookieData*
-In the first overload, a pointer to a string containing the address of the buffer that receives the cookie data. This value can be NULL. In the second overload, a reference to a [CString](../../atl-mfc-shared/reference/cstringt-class.md) object to receive the cookie data. +*`pstrCookieData`*\ +In the first overload, a pointer to a string containing the address of the buffer that receives the cookie data. This value can be `NULL`. In the second overload, a reference to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object to receive the cookie data. -*dwBufLen*
-The variable specifying the size of the *pstrCookieData* buffer. If the function succeeds, the buffer receives the amount of data copied to the *pstrCookieData* buffer. If *pstrCookieData* is NULL, this parameter receives a value that specifies the size of the buffer necessary to copy all the cookie data. +*`dwBufLen`*\ +The variable specifying the size of the *`pstrCookieData`* buffer. If the function succeeds, the buffer receives the amount of data copied to the *`pstrCookieData`* buffer. If *`pstrCookieData`* is `NULL`, this parameter receives a value that specifies the size of the buffer necessary to copy all the cookie data. ### Return Value -Returns TRUE if successful, or FALSE otherwise. If the call fails, call the Win32 function [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to determine the cause of the error. The following error values apply: +Returns `TRUE` if successful, or `FALSE` otherwise. If the call fails, call the Win32 function [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to determine the cause of the error. The following error values apply: -- ERROR_NO_MORE_ITEMS There is no cookie for the specified URL and all its parents. +- `ERROR_NO_MORE_ITEMS` There's no cookie for the specified URL and all its parents. -- ERROR_INSUFFICIENT_BUFFER The value passed in *dwBufLen* is insufficient to copy all the cookie data. The value returned in *dwBufLen* is the size of the buffer necessary to get all the data. +- `ERROR_INSUFFICIENT_BUFFER` The value passed in *`dwBufLen`* is insufficient to copy all the cookie data. The value returned in *`dwBufLen`* is the size of the buffer necessary to get all the data. ### Remarks In the second overload, MFC retrieves the cookie data into the supplied `CString` object. -## CInternetSession::GetCookieLength +## `CInternetSession::GetCookieLength` Call this member function to get the length of the cookie stored in the buffer. @@ -247,21 +246,21 @@ static DWORD GetCookieLength( ### Parameters -*pstrUrl*
+*`pstrUrl`*\ A pointer to a string containing the URL -*pstrCookieName*
+*`pstrCookieName`*\ A pointer to a string containing the name of the cookie. ### Return Value -A DWORD value indicating the length of the cookie, stored in the buffer. Zero if no cookie with the name indicated by *pstrCookieName* exists. +A `DWORD` value indicating the length of the cookie, stored in the buffer. Zero if no cookie with the name indicated by *`pstrCookieName`* exists. ### Remarks -This value is used by [GetCookie](#getcookie). +This value is used by [`GetCookie`](#getcookie). -## CInternetSession::GetFtpConnection +## `CInternetSession::GetFtpConnection` Call this member function to establish an FTP connection and get a pointer to a `CFtpConnection` object. @@ -276,41 +275,41 @@ CFtpConnection* GetFtpConnection( ### Parameters -*pstrServer*
+*`pstrServer`*\ A pointer to a string containing the FTP server name. -*pstrUserName*
-Pointer to a null-terminated string that specifies the name of the user to log in. If NULL, the default is anonymous. +*`pstrUserName`*\ +Pointer to a null-terminated string that specifies the name of the user to log in. If `NULL`, the default is anonymous. -*pstrPassword*
-A pointer to a null-terminated string that specifies the password to use to log in. If both *pstrPassword* and *pstrUserName* are NULL, the default anonymous password is the user's email name. If *pstrPassword* is NULL (or an empty string) but *pstrUserName* is not NULL, a blank password is used. The following table describes the behavior for the four possible settings of *pstrUserName* and *pstrPassword*: +*`pstrPassword`*\ +A pointer to a null-terminated string that specifies the password to use to log in. If both *`pstrPassword`* and *`pstrUserName`* are `NULL`, the default anonymous password is the user's email name. If *`pstrPassword`* is `NULL` (or an empty string) but *`pstrUserName`* isn't `NULL`, a blank password is used. The following table describes the behavior for the four possible settings of *`pstrUserName`* and *`pstrPassword`*: -| *pstrUserName* | *pstrPassword* | Username sent to FTP server | Password sent to FTP server | +| *`pstrUserName`* | *`pstrPassword`* | Username sent to FTP server | Password sent to FTP server | |-----------------|-----------------|-----------------------------|-----------------------------| -| NULL or " " | NULL or " " | "anonymous" | User's email name | -| Non-NULL String | NULL or " " | *pstrUserName* | " " | -| NULL | Non-NULL String | ERROR | ERROR | -| Non-NULL String | Non-NULL String | *pstrUserName* | *pstrPassword* | +| `NULL` or `" "` | `NULL` or `" "` | `"anonymous"` | User's email name | +| Non-`NULL` String | `NULL` or `" "` | *`pstrUserName`* | " " | +| `NULL` | Non-`NULL` String | ERROR | ERROR | +| Non-`NULL` String | Non-`NULL` String | *`pstrUserName`* | *`pstrPassword`* | -*nPort*
+*`nPort`*\ A number that identifies the TCP/IP port to use on the server. -*bPassive*
-Specifies passive or active mode for this FTP session. If set to TRUE, it sets the Win32 API `dwFlag` to INTERNET_FLAG_PASSIVE. +*`bPassive`*\ +Specifies passive or active mode for this FTP session. If set to `TRUE`, it sets the Win32 API `dwFlag` to `INTERNET_FLAG_PASSIVE`. ### Return Value -A pointer to a [CFtpConnection](../../mfc/reference/cftpconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [CInternetException](../../mfc/reference/cinternetexception-class.md) object. +A pointer to a [`CFtpConnection`](../../mfc/reference/cftpconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [`CInternetException`](../../mfc/reference/cinternetexception-class.md) object. ### Remarks -`GetFtpConnection` connects to an FTP server, and creates and returns a pointer to a `CFTPConnection` object. It does not perform any specific operation on the server. If you intend to read or write to files, for example, you must perform those operations as separate steps. See the classes [CFtpConnection](../../mfc/reference/cftpconnection-class.md) and [CFtpFileFind](../../mfc/reference/cftpfilefind-class.md) for information about searching for files, opening files, and reading or writing to files. See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common FTP connection tasks. +`GetFtpConnection` connects to an FTP server, and creates and returns a pointer to a `CFTPConnection` object. It doesn't perform any specific operation on the server. If you intend to read or write to files, for example, you must perform those operations as separate steps. See the classes [`CFtpConnection`](../../mfc/reference/cftpconnection-class.md) and [`CFtpFileFind`](../../mfc/reference/cftpfilefind-class.md) for information about searching for files, opening files, and reading or writing to files. See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common FTP connection tasks. ### Example -See the example for [CFtpFileFind](../../mfc/reference/cftpfilefind-class.md). +See the example for [`CFtpFileFind`](../../mfc/reference/cftpfilefind-class.md). -## CInternetSession::GetGopherConnection +## `CInternetSession::GetGopherConnection` Call this member function to establish a new gopher connection and get a pointer to a `CGopherConnection` object. @@ -324,27 +323,27 @@ CGopherConnection* GetGopherConnection( ### Parameters -*pstrServer*
+*`pstrServer`*\ A pointer to a string containing the gopher server name. -*pstrUserName*
+*`pstrUserName`*\ A pointer to a string containing the user name. -*pstrPassword*
+*`pstrPassword`*\ A pointer to a string containing the access password. -*nPort*
+*`nPort`*\ A number that identifies the TCP/IP port to use on the server. ### Return Value -A pointer to a [CGopherConnection](../../mfc/reference/cgopherconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [CInternetException](../../mfc/reference/cinternetexception-class.md) object. +A pointer to a [`CGopherConnection`](../../mfc/reference/cgopherconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [`CInternetException`](../../mfc/reference/cinternetexception-class.md) object. ### Remarks -`GetGopherConnection` connects to a gopher server, and creates and returns a pointer to a `CGopherConnection` object. It does not perform any specific operation on the server. If you intend to read or write data, for example, you must perform those operations as separate steps. See the classes [CGopherConnection](../../mfc/reference/cgopherconnection-class.md), [CGopherFile](../../mfc/reference/cgopherfile-class.md), and [CGopherFileFind](../../mfc/reference/cgopherfilefind-class.md) for information about searching for files, opening files, and reading or writing to files. For information about browsing an FTP site, see the member function [OpenURL](#openurl). See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common gopher connection tasks. +`GetGopherConnection` connects to a gopher server, and creates and returns a pointer to a `CGopherConnection` object. It doesn't perform any specific operation on the server. If you intend to read or write data, for example, you must perform those operations as separate steps. See the classes [`CGopherConnection`](../../mfc/reference/cgopherconnection-class.md), [`CGopherFile`](../../mfc/reference/cgopherfile-class.md), and [`CGopherFileFind`](../../mfc/reference/cgopherfilefind-class.md) for information about searching for files, opening files, and reading or writing to files. For information about browsing an FTP site, see the member function [`OpenURL`](#openurl). See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common gopher connection tasks. -## CInternetSession::GetHttpConnection +## `CInternetSession::GetHttpConnection` Call this member function to establish an HTTP connection and get a pointer to a `CHttpConnection` object. @@ -365,30 +364,30 @@ CHttpConnection* GetHttpConnection( ### Parameters -*pstrServer*
+*`pstrServer`*\ A pointer to a string containing the HTTP server name. -*nPort*
+*`nPort`*\ A number that identifies the TCP/IP port to use on the server. -*pstrUserName*
+*`pstrUserName`*\ A pointer to a string containing the user name. -*pstrPassword*
+*`pstrPassword`*\ A pointer to a string containing the access password. -*dwflags*
-Any combination of the `INTERNET_FLAG_*` flags. See the table in the **Remarks** section of [CHttpConnection::OpenRequest](../../mfc/reference/chttpconnection-class.md#openrequest) for a description of *dwFlags* values. +*`dwflags`*\ +Any combination of the `INTERNET_FLAG_*` flags. See the table in the **Remarks** section of [`CHttpConnection::OpenRequest`](../../mfc/reference/chttpconnection-class.md#openrequest) for a description of *`dwFlags`* values. ### Return Value -A pointer to a [CHttpConnection](../../mfc/reference/chttpconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [CInternetException](../../mfc/reference/cinternetexception-class.md) object. +A pointer to a [`CHttpConnection`](../../mfc/reference/chttpconnection-class.md) object. If the call fails, determine the cause of the failure by examining the thrown [`CInternetException`](../../mfc/reference/cinternetexception-class.md) object. ### Remarks -`GetHttpConnection` connects to an HTTP server, and creates and returns a pointer to a `CHttpConnection` object. It does not perform any specific operation on the server. If you intend to query an HTTP header, for example, you must perform this operation as a separate step. See the classes [CHttpConnection](../../mfc/reference/chttpconnection-class.md) and [CHttpFile](../../mfc/reference/chttpfile-class.md) for information about operations you can perform by using a connection to an HTTP server. For information about browsing an HTTP site, see the member function [OpenURL](#openurl). See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common HTTP connection tasks. +`GetHttpConnection` connects to an HTTP server, and creates and returns a pointer to a `CHttpConnection` object. It doesn't perform any specific operation on the server. If you intend to query an HTTP header, for example, you must perform this operation as a separate step. See the classes [`CHttpConnection`](../../mfc/reference/chttpconnection-class.md) and [`CHttpFile`](../../mfc/reference/chttpfile-class.md) for information about operations you can perform by using a connection to an HTTP server. For information about browsing an HTTP site, see the member function [`OpenURL`](#openurl). See the article [Internet Programming with WinInet](../../mfc/win32-internet-extensions-wininet.md) for steps in performing common HTTP connection tasks. -## CInternetSession::OnStatusCallback +## `CInternetSession::OnStatusCallback` This member function is called by the framework to update the status when status callback is enabled and an operation is pending. @@ -402,38 +401,38 @@ virtual void OnStatusCallback( ### Parameters -*dwContext*
+*`dwContext`*\ The context value supplied by the application. -*dwInternetStatus*
-A status code which indicates why the callback is being made. See **Remarks** for a table of possible values. +*`dwInternetStatus`*\ +A status code that indicates why the callback is being made. See [**Remarks**](#onstatuscallback-remarks) for a table of possible values. -*lpvStatusInformation*
+*`lpvStatusInformation`*\ A pointer to a buffer containing information pertinent to this callback. -*dwStatusInformationLength*
-The size of *lpvStatusInformation*. +*`dwStatusInformationLength`*\ +The size of *`lpvStatusInformation`*. -### Remarks +### Remarks -You must first call [EnableStatusCallback](#enablestatuscallback) to take advantage of status callback. +You must first call [`EnableStatusCallback`](#enablestatuscallback) to take advantage of status callback. -The *dwInternetStatus* parameter indicates the operation being performed and determines what the contents of *lpvStatusInformation* will be. *dwStatusInformationLength* indicates the length of the data included in *lpvStatusInformation*. The following status values for *dwInternetStatus* are defined as follows: +The *`dwInternetStatus`* parameter indicates the operation being performed and determines what the contents of *`lpvStatusInformation`* will be. *`dwStatusInformationLength`* indicates the length of the data included in *`lpvStatusInformation`*. The following status values for *`dwInternetStatus`* are defined as follows: |Value|Meaning| |-----------|-------------| -|INTERNET_STATUS_RESOLVING_NAME|Looking up the IP address of the name contained in *lpvStatusInformation*.| -|INTERNET_STATUS_NAME_RESOLVED|Successfully found the IP address of the name contained in *lpvStatusInformation*.| -|INTERNET_STATUS_CONNECTING_TO_SERVER|Connecting to the socket address ([SOCKADDR](/windows/win32/winsock/sockaddr-2)) pointed to by *lpvStatusInformation*.| -|INTERNET_STATUS_CONNECTED_TO_SERVER|Successfully connected to the socket address (SOCKADDR) pointed to by *lpvStatusInformation*.| -|INTERNET_STATUS_SENDING_REQUEST|Sending the information request to the server. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_ REQUEST_SENT|Successfully sent the information request to the server. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_RECEIVING_RESPONSE|Waiting for the server to respond to a request. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_RESPONSE_RECEIVED|Successfully received a response from the server. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_CLOSING_CONNECTION|Closing the connection to the server. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_CONNECTION_CLOSED|Successfully closed the connection to the server. The *lpvStatusInformation* parameter is NULL.| -|INTERNET_STATUS_HANDLE_CREATED|Used by the Win32 API function [InternetConnect](/windows/win32/api/wininet/nf-wininet-internetconnectw) to indicate that it has created the new handle. This lets the application call the Win32 function [InternetCloseHandle](/windows/win32/api/wininet/nf-wininet-internetclosehandle) from another thread if the connect is taking too long. See the Windows SDKfor more information about these functions.| -|INTERNET_STATUS_HANDLE_CLOSING|Successfully terminated this handle value.| +|`INTERNET_STATUS_RESOLVING_NAME`|Looking up the IP address of the name contained in *`lpvStatusInformation`*.| +|`INTERNET_STATUS_NAME_RESOLVED`|Successfully found the IP address of the name contained in *`lpvStatusInformation`*.| +|`INTERNET_STATUS_CONNECTING_TO_SERVER`|Connecting to the socket address ([`SOCKADDR`](/windows/win32/winsock/sockaddr-2)) pointed to by *`lpvStatusInformation`*.| +|`INTERNET_STATUS_CONNECTED_TO_SERVER`|Successfully connected to the socket address (`SOCKADDR`) pointed to by *`lpvStatusInformation`*.| +|`INTERNET_STATUS_SENDING_REQUEST`|Sending the information request to the server. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_REQUEST_SENT`|Successfully sent the information request to the server. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_RECEIVING_RESPONSE`|Waiting for the server to respond to a request. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_RESPONSE_RECEIVED`|Successfully received a response from the server. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_CLOSING_CONNECTION`|Closing the connection to the server. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_CONNECTION_CLOSED`|Successfully closed the connection to the server. The *`lpvStatusInformation`* parameter is `NULL`.| +|`INTERNET_STATUS_HANDLE_CREATED`|Used by the Win32 API function [`InternetConnect`](/windows/win32/api/wininet/nf-wininet-internetconnectw) to indicate that it has created the new handle. This lets the application call the Win32 function [`InternetCloseHandle`](/windows/win32/api/wininet/nf-wininet-internetclosehandle) from another thread if the connect is taking too long. See the Windows SDKfor more information about these functions.| +|`INTERNET_STATUS_HANDLE_CLOSING`|Successfully terminated this handle value.| Override this member function to require some action before a status callback routine is performed. @@ -444,7 +443,7 @@ Override this member function to require some action before a status callback ro For more information about asynchronous operations, see the article [Internet First Steps: WinInet](../../mfc/wininet-basics.md). -## CInternetSession::OpenURL +## `CInternetSession::OpenURL` Call this member function to send the specified request to the HTTP server and allow the client to specify additional RFC822, MIME, or HTTP headers to send along with the request. @@ -459,40 +458,40 @@ CStdioFile* OpenURL( ### Parameters -*pstrURL*
-A pointer to the name of the URL to begin reading. Only URLs beginning with file:, ftp:, gopher:, or http: are supported. Asserts if *pstrURL* is NULL. +*`pstrURL`*\ +A pointer to the name of the URL to begin reading. Only URLs beginning with `file:`, `ftp:`, `gopher:`, or `http:` are supported. Asserts if *`pstrURL`* is `NULL`. -*dwContext*
+*`dwContext`*\ An application-defined value passed with the returned handle in callback. -*dwFlags*
-The flags describing how to handle this connection. See **Remarks** for more information about the valid flags. The valid flags are: +*`dwFlags`*\ +The flags describing how to handle this connection. See [**Remarks**](#openurl-remarks) for more information about the valid flags. The valid flags are: -- INTERNET_FLAG_TRANSFER_ASCII The default. Transfer the file as ASCII text. +- `INTERNET_FLAG_TRANSFER_ASCII` The default. Transfer the file as ASCII text. -- INTERNET_FLAG_TRANSFER_BINARY Transfer the file as a binary file. +- `INTERNET_FLAG_TRANSFER_BINARY` Transfer the file as a binary file. -- INTERNET_FLAG_RELOAD Get the data from the wire even if it is locally cached. +- `INTERNET_FLAG_RELOAD` Get the data from the wire even if it's locally cached. -- INTERNET_FLAG_DONT_CACHE Do not cache the data, either locally or in any gateways. +- `INTERNET_FLAG_DONT_CACHE` Don't cache the data, either locally or in any gateways. -- INTERNET_FLAG_SECURE This flag is applicable to HTTP requests only. It requests secure transactions on the wire with Secure Sockets Layer or PCT. +- `INTERNET_FLAG_SECURE` This flag is applicable to HTTP requests only. It requests secure transactions on the wire with Secure Sockets Layer or PCT. -- INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT If possible, reuse the existing connections to the server for new requests generated by `OpenUrl` instead of creating a new session for each connection request. +- `INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT` If possible, reuse the existing connections to the server for new requests generated by `OpenUrl` instead of creating a new session for each connection request. -- INTERNET_FLAG_PASSIVE Used for an FTP site. Uses passive FTP semantics. Used with [CInternetConnection](../../mfc/reference/cinternetconnection-class.md) of `OpenURL`. +- `INTERNET_FLAG_PASSIVE` Used for an FTP site. Uses passive FTP semantics. Used with [`CInternetConnection`](../../mfc/reference/cinternetconnection-class.md) of `OpenURL`. -*pstrHeaders*
+*`pstrHeaders`*\ A pointer to a string containing the headers to be sent to the HTTP server. -*dwHeadersLength*
-The length, in characters, of the additional headers. If this is -1L and *pstrHeaders* is non-NULL, then *pstrHeaders* is assumed to be zero terminated and the length is calculated. +*`dwHeadersLength`*\ +The length, in characters, of the additional headers. If this is `-1L` and *`pstrHeaders`* is non-`NULL`, then *`pstrHeaders`* is assumed to be zero terminated and the length is calculated. ### Return Value -Returns a file handle for FTP, GOPHER, HTTP, and FILE-type Internet services only. Returns NULL if parsing was unsuccessful. +Returns a file handle for FTP, GOPHER, HTTP, and FILE-type Internet services only. Returns `NULL` if parsing was unsuccessful. -The pointer that `OpenURL` returns depends on *pstrURL*'s type of service. The table below illustrates the possible pointers `OpenURL` can return. +The pointer that `OpenURL` returns depends on *`pstrURL`*'s type of service. The table below illustrates the possible pointers `OpenURL` can return. |URL type|Returns| |--------------|-------------| @@ -501,15 +500,15 @@ The pointer that `OpenURL` returns depends on *pstrURL*'s type of service. The t |`gopher://`|`CGopherFile*`| |`ftp://`|`CInternetFile*`| -### Remarks +### Remarks -The parameter *dwFlags* must include either INTERNET_FLAG_TRANSFER_ASCII or INTERNET_FLAG_TRANSFER_BINARY, but not both. The remaining flags can be combined with the bitwise **OR** operator ( **|**). +The parameter *`dwFlags`* must include either `INTERNET_FLAG_TRANSFER_ASCII` or `INTERNET_FLAG_TRANSFER_BINARY`, but not both. The remaining flags can be combined with the bitwise "or" (`|`) operator. -`OpenURL`, which wraps the Win32 function `InternetOpenURL`, allows only downloading, retrieving, and reading the data from an Internet server. `OpenURL` allows no file manipulation on a remote location, so it requires no [CInternetConnection](../../mfc/reference/cinternetconnection-class.md) object. +`OpenURL`, which wraps the Win32 function `InternetOpenURL`, allows only downloading, retrieving, and reading the data from an Internet server. `OpenURL` allows no file manipulation on a remote location, so it requires no [`CInternetConnection`](../../mfc/reference/cinternetconnection-class.md) object. To use connection-specific (that is, protocol-specific) functions, such as writing to a file, you must open a session, then open a particular kind of connection, then use that connection to open a file in the desired mode. See `CInternetConnection` for more information about connection-specific functions. -## CInternetSession::operator HINTERNET +## `CInternetSession::operator HINTERNET` Use this operator to get the Windows handle for the current Internet session. @@ -517,7 +516,7 @@ Use this operator to get the Windows handle for the current Internet session. operator HINTERNET() const; ``` -## CInternetSession::SetCookie +## `CInternetSession::SetCookie` Sets a cookie for the specified URL. @@ -530,24 +529,24 @@ static BOOL SetCookie( ### Parameters -*pstrUrl*
+*`pstrUrl`*\ A pointer to a null-terminated string that specifies the URL for which the cookie should be set. -*pstrCookieName*
+*`pstrCookieName`*\ A pointer to a string containing the name of the cookie. -*pstrCookieData*
+*`pstrCookieData`*\ A pointer to a string containing the actual string data to associate with the URL. ### Return Value -Returns TRUE if successful, or FALSE otherwise. To get the specific error code, call `GetLastError.` +Returns `TRUE` if successful, or `FALSE` otherwise. To get the specific error code, call `GetLastError`. ### Remarks -This member function implements the behavior of the Win32 message [InternetSetCookie](/windows/win32/api/wininet/nf-wininet-internetsetcookiew), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`InternetSetCookie`](/windows/win32/api/wininet/nf-wininet-internetsetcookiew), as described in the Windows SDK. -## CInternetSession::SetOption +## `CInternetSession::SetOption` Call this member function to set options for the Internet session. @@ -566,34 +565,34 @@ BOOL SetOption( ### Parameters -*dwOption*
-The Internet option to set. See [Option Flags](/windows/win32/WinInet/option-flags) in the Windows SDKfor a list of the possible options. +*`dwOption`*\ +The Internet option to set. See [Option Flags](/windows/win32/WinInet/option-flags) in the Windows SDK for a list of the possible options. -*lpBuffer*
+*`lpBuffer`*\ A buffer that contains the option setting. -*dwBufferLength*
-The length of *lpBuffer* or the size of *dwValue*. +*`dwBufferLength`*\ +The length of *`lpBuffer`* or the size of *`dwValue`*. -*dwValue*
-A DWORD that contains the option setting. +*`dwValue`*\ +A `DWORD` that contains the option setting. -*dwFlags*
+*`dwFlags`*\ Indicates various caching options. The default is set to 0. The possible values include: -- INTERNET_FLAG_DONT_CACHE Do not cache the data, either locally or in any gateway servers. +- `INTERNET_FLAG_DONT_CACHE` Don't cache the data, either locally or in any gateway servers. -- INTERNET_FLAG_OFFLINE Download operations are satisfied through the persistent cache only. If the item does not exist in the cache, an appropriate error code is returned. This flag may be combined with the bitwise **OR** ( **|**) operator. +- `INTERNET_FLAG_OFFLINE` Download operations are satisfied through the persistent cache only. If the item doesn't exist in the cache, an appropriate error code is returned. This flag may be combined with the bitwise "or" (`|`) operator. ### Return Value -If the operation was successful, a value of TRUE is returned. If an error occurred, a value of FALSE is returned. If the call fails, the Win32 function [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) may be called to determine the cause of the error. +If the operation was successful, a value of `TRUE` is returned. If an error occurred, a value of `FALSE` is returned. If the call fails, the Win32 function [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) may be called to determine the cause of the error. ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CInternetConnection Class](../../mfc/reference/cinternetconnection-class.md)
-[CHttpConnection Class](../../mfc/reference/chttpconnection-class.md)
-[CFtpConnection Class](../../mfc/reference/cftpconnection-class.md)
-[CGopherConnection Class](../../mfc/reference/cgopherconnection-class.md) +[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CInternetConnection` Class](../../mfc/reference/cinternetconnection-class.md)\ +[`CHttpConnection` Class](../../mfc/reference/chttpconnection-class.md)\ +[`CFtpConnection` Class](../../mfc/reference/cftpconnection-class.md)\ +[`CGopherConnection` Class](../../mfc/reference/cgopherconnection-class.md) diff --git a/docs/mfc/reference/clistctrl-class.md b/docs/mfc/reference/clistctrl-class.md index 301fc257e3..a9e92a75d1 100644 --- a/docs/mfc/reference/clistctrl-class.md +++ b/docs/mfc/reference/clistctrl-class.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: CListCtrl Class" title: "CListCtrl Class" -ms.date: "01/03/2022" +description: "Learn more about: CListCtrl Class" +ms.date: 06/29/2022 f1_keywords: ["CListCtrl", "AFXCMN/CListCtrl", "AFXCMN/CListCtrl::CListCtrl", "AFXCMN/CListCtrl::ApproximateViewRect", "AFXCMN/CListCtrl::Arrange", "AFXCMN/CListCtrl::CancelEditLabel", "AFXCMN/CListCtrl::Create", "AFXCMN/CListCtrl::CreateDragImage", "AFXCMN/CListCtrl::CreateEx", "AFXCMN/CListCtrl::DeleteAllItems", "AFXCMN/CListCtrl::DeleteColumn", "AFXCMN/CListCtrl::DeleteItem", "AFXCMN/CListCtrl::DrawItem", "AFXCMN/CListCtrl::EditLabel", "AFXCMN/CListCtrl::EnableGroupView", "AFXCMN/CListCtrl::EnsureVisible", "AFXCMN/CListCtrl::FindItem", "AFXCMN/CListCtrl::GetBkColor", "AFXCMN/CListCtrl::GetBkImage", "AFXCMN/CListCtrl::GetCallbackMask", "AFXCMN/CListCtrl::GetCheck", "AFXCMN/CListCtrl::GetColumn", "AFXCMN/CListCtrl::GetColumnOrderArray", "AFXCMN/CListCtrl::GetColumnWidth", "AFXCMN/CListCtrl::GetCountPerPage", "AFXCMN/CListCtrl::GetEditControl", "AFXCMN/CListCtrl::GetEmptyText", "AFXCMN/CListCtrl::GetExtendedStyle", "AFXCMN/CListCtrl::GetFirstSelectedItemPosition", "AFXCMN/CListCtrl::GetFocusedGroup", "AFXCMN/CListCtrl::GetGroupCount", "AFXCMN/CListCtrl::GetGroupInfo", "AFXCMN/CListCtrl::GetGroupInfoByIndex", "AFXCMN/CListCtrl::GetGroupMetrics", "AFXCMN/CListCtrl::GetGroupRect", "AFXCMN/CListCtrl::GetGroupState", "AFXCMN/CListCtrl::GetHeaderCtrl", "AFXCMN/CListCtrl::GetHotCursor", "AFXCMN/CListCtrl::GetHotItem", "AFXCMN/CListCtrl::GetHoverTime", "AFXCMN/CListCtrl::GetImageList", "AFXCMN/CListCtrl::GetInsertMark", "AFXCMN/CListCtrl::GetInsertMarkColor", "AFXCMN/CListCtrl::GetInsertMarkRect", "AFXCMN/CListCtrl::GetItem", "AFXCMN/CListCtrl::GetItemCount", "AFXCMN/CListCtrl::GetItemData", "AFXCMN/CListCtrl::GetItemIndexRect", "AFXCMN/CListCtrl::GetItemPosition", "AFXCMN/CListCtrl::GetItemRect", "AFXCMN/CListCtrl::GetItemSpacing", "AFXCMN/CListCtrl::GetItemState", "AFXCMN/CListCtrl::GetItemText", "AFXCMN/CListCtrl::GetNextItem", "AFXCMN/CListCtrl::GetNextItemIndex", "AFXCMN/CListCtrl::GetNextSelectedItem", "AFXCMN/CListCtrl::GetNumberOfWorkAreas", "AFXCMN/CListCtrl::GetOrigin", "AFXCMN/CListCtrl::GetOutlineColor", "AFXCMN/CListCtrl::GetSelectedColumn", "AFXCMN/CListCtrl::GetSelectedCount", "AFXCMN/CListCtrl::GetSelectionMark", "AFXCMN/CListCtrl::GetStringWidth", "AFXCMN/CListCtrl::GetSubItemRect", "AFXCMN/CListCtrl::GetTextBkColor", "AFXCMN/CListCtrl::GetTextColor", "AFXCMN/CListCtrl::GetTileInfo", "AFXCMN/CListCtrl::GetTileViewInfo", "AFXCMN/CListCtrl::GetToolTips", "AFXCMN/CListCtrl::GetTopIndex", "AFXCMN/CListCtrl::GetView", "AFXCMN/CListCtrl::GetViewRect", "AFXCMN/CListCtrl::GetWorkAreas", "AFXCMN/CListCtrl::HasGroup", "AFXCMN/CListCtrl::HitTest", "AFXCMN/CListCtrl::InsertColumn", "AFXCMN/CListCtrl::InsertGroup", "AFXCMN/CListCtrl::InsertGroupSorted", "AFXCMN/CListCtrl::InsertItem", "AFXCMN/CListCtrl::InsertMarkHitTest", "AFXCMN/CListCtrl::IsGroupViewEnabled", "AFXCMN/CListCtrl::IsItemVisible", "AFXCMN/CListCtrl::MapIDToIndex", "AFXCMN/CListCtrl::MapIndexToID", "AFXCMN/CListCtrl::MoveGroup", "AFXCMN/CListCtrl::MoveItemToGroup", "AFXCMN/CListCtrl::RedrawItems", "AFXCMN/CListCtrl::RemoveAllGroups", "AFXCMN/CListCtrl::RemoveGroup", "AFXCMN/CListCtrl::Scroll", "AFXCMN/CListCtrl::SetBkColor", "AFXCMN/CListCtrl::SetBkImage", "AFXCMN/CListCtrl::SetCallbackMask", "AFXCMN/CListCtrl::SetCheck", "AFXCMN/CListCtrl::SetColumn", "AFXCMN/CListCtrl::SetColumnOrderArray", "AFXCMN/CListCtrl::SetColumnWidth", "AFXCMN/CListCtrl::SetExtendedStyle", "AFXCMN/CListCtrl::SetGroupInfo", "AFXCMN/CListCtrl::SetGroupMetrics", "AFXCMN/CListCtrl::SetHotCursor", "AFXCMN/CListCtrl::SetHotItem", "AFXCMN/CListCtrl::SetHoverTime", "AFXCMN/CListCtrl::SetIconSpacing", "AFXCMN/CListCtrl::SetImageList", "AFXCMN/CListCtrl::SetInfoTip", "AFXCMN/CListCtrl::SetInsertMark", "AFXCMN/CListCtrl::SetInsertMarkColor", "AFXCMN/CListCtrl::SetItem", "AFXCMN/CListCtrl::SetItemCount", "AFXCMN/CListCtrl::SetItemCountEx", "AFXCMN/CListCtrl::SetItemData", "AFXCMN/CListCtrl::SetItemIndexState", "AFXCMN/CListCtrl::SetItemPosition", "AFXCMN/CListCtrl::SetItemState", "AFXCMN/CListCtrl::SetItemText", "AFXCMN/CListCtrl::SetOutlineColor", "AFXCMN/CListCtrl::SetSelectedColumn", "AFXCMN/CListCtrl::SetSelectionMark", "AFXCMN/CListCtrl::SetTextBkColor", "AFXCMN/CListCtrl::SetTextColor", "AFXCMN/CListCtrl::SetTileInfo", "AFXCMN/CListCtrl::SetTileViewInfo", "AFXCMN/CListCtrl::SetToolTips", "AFXCMN/CListCtrl::SetView", "AFXCMN/CListCtrl::SetWorkAreas", "AFXCMN/CListCtrl::SortGroups", "AFXCMN/CListCtrl::SortItems", "AFXCMN/CListCtrl::SortItemsEx", "AFXCMN/CListCtrl::SubItemHitTest", "AFXCMN/CListCtrl::Update"] helpviewer_keywords: ["CListCtrl [MFC], CListCtrl", "CListCtrl [MFC], ApproximateViewRect", "CListCtrl [MFC], Arrange", "CListCtrl [MFC], CancelEditLabel", "CListCtrl [MFC], Create", "CListCtrl [MFC], CreateDragImage", "CListCtrl [MFC], CreateEx", "CListCtrl [MFC], DeleteAllItems", "CListCtrl [MFC], DeleteColumn", "CListCtrl [MFC], DeleteItem", "CListCtrl [MFC], DrawItem", "CListCtrl [MFC], EditLabel", "CListCtrl [MFC], EnableGroupView", "CListCtrl [MFC], EnsureVisible", "CListCtrl [MFC], FindItem", "CListCtrl [MFC], GetBkColor", "CListCtrl [MFC], GetBkImage", "CListCtrl [MFC], GetCallbackMask", "CListCtrl [MFC], GetCheck", "CListCtrl [MFC], GetColumn", "CListCtrl [MFC], GetColumnOrderArray", "CListCtrl [MFC], GetColumnWidth", "CListCtrl [MFC], GetCountPerPage", "CListCtrl [MFC], GetEditControl", "CListCtrl [MFC], GetEmptyText", "CListCtrl [MFC], GetExtendedStyle", "CListCtrl [MFC], GetFirstSelectedItemPosition", "CListCtrl [MFC], GetFocusedGroup", "CListCtrl [MFC], GetGroupCount", "CListCtrl [MFC], GetGroupInfo", "CListCtrl [MFC], GetGroupInfoByIndex", "CListCtrl [MFC], GetGroupMetrics", "CListCtrl [MFC], GetGroupRect", "CListCtrl [MFC], GetGroupState", "CListCtrl [MFC], GetHeaderCtrl", "CListCtrl [MFC], GetHotCursor", "CListCtrl [MFC], GetHotItem", "CListCtrl [MFC], GetHoverTime", "CListCtrl [MFC], GetImageList", "CListCtrl [MFC], GetInsertMark", "CListCtrl [MFC], GetInsertMarkColor", "CListCtrl [MFC], GetInsertMarkRect", "CListCtrl [MFC], GetItem", "CListCtrl [MFC], GetItemCount", "CListCtrl [MFC], GetItemData", "CListCtrl [MFC], GetItemIndexRect", "CListCtrl [MFC], GetItemPosition", "CListCtrl [MFC], GetItemRect", "CListCtrl [MFC], GetItemSpacing", "CListCtrl [MFC], GetItemState", "CListCtrl [MFC], GetItemText", "CListCtrl [MFC], GetNextItem", "CListCtrl [MFC], GetNextItemIndex", "CListCtrl [MFC], GetNextSelectedItem", "CListCtrl [MFC], GetNumberOfWorkAreas", "CListCtrl [MFC], GetOrigin", "CListCtrl [MFC], GetOutlineColor", "CListCtrl [MFC], GetSelectedColumn", "CListCtrl [MFC], GetSelectedCount", "CListCtrl [MFC], GetSelectionMark", "CListCtrl [MFC], GetStringWidth", "CListCtrl [MFC], GetSubItemRect", "CListCtrl [MFC], GetTextBkColor", "CListCtrl [MFC], GetTextColor", "CListCtrl [MFC], GetTileInfo", "CListCtrl [MFC], GetTileViewInfo", "CListCtrl [MFC], GetToolTips", "CListCtrl [MFC], GetTopIndex", "CListCtrl [MFC], GetView", "CListCtrl [MFC], GetViewRect", "CListCtrl [MFC], GetWorkAreas", "CListCtrl [MFC], HasGroup", "CListCtrl [MFC], HitTest", "CListCtrl [MFC], InsertColumn", "CListCtrl [MFC], InsertGroup", "CListCtrl [MFC], InsertGroupSorted", "CListCtrl [MFC], InsertItem", "CListCtrl [MFC], InsertMarkHitTest", "CListCtrl [MFC], IsGroupViewEnabled", "CListCtrl [MFC], IsItemVisible", "CListCtrl [MFC], MapIDToIndex", "CListCtrl [MFC], MapIndexToID", "CListCtrl [MFC], MoveGroup", "CListCtrl [MFC], MoveItemToGroup", "CListCtrl [MFC], RedrawItems", "CListCtrl [MFC], RemoveAllGroups", "CListCtrl [MFC], RemoveGroup", "CListCtrl [MFC], Scroll", "CListCtrl [MFC], SetBkColor", "CListCtrl [MFC], SetBkImage", "CListCtrl [MFC], SetCallbackMask", "CListCtrl [MFC], SetCheck", "CListCtrl [MFC], SetColumn", "CListCtrl [MFC], SetColumnOrderArray", "CListCtrl [MFC], SetColumnWidth", "CListCtrl [MFC], SetExtendedStyle", "CListCtrl [MFC], SetGroupInfo", "CListCtrl [MFC], SetGroupMetrics", "CListCtrl [MFC], SetHotCursor", "CListCtrl [MFC], SetHotItem", "CListCtrl [MFC], SetHoverTime", "CListCtrl [MFC], SetIconSpacing", "CListCtrl [MFC], SetImageList", "CListCtrl [MFC], SetInfoTip", "CListCtrl [MFC], SetInsertMark", "CListCtrl [MFC], SetInsertMarkColor", "CListCtrl [MFC], SetItem", "CListCtrl [MFC], SetItemCount", "CListCtrl [MFC], SetItemCountEx", "CListCtrl [MFC], SetItemData", "CListCtrl [MFC], SetItemIndexState", "CListCtrl [MFC], SetItemPosition", "CListCtrl [MFC], SetItemState", "CListCtrl [MFC], SetItemText", "CListCtrl [MFC], SetOutlineColor", "CListCtrl [MFC], SetSelectedColumn", "CListCtrl [MFC], SetSelectionMark", "CListCtrl [MFC], SetTextBkColor", "CListCtrl [MFC], SetTextColor", "CListCtrl [MFC], SetTileInfo", "CListCtrl [MFC], SetTileViewInfo", "CListCtrl [MFC], SetToolTips", "CListCtrl [MFC], SetView", "CListCtrl [MFC], SetWorkAreas", "CListCtrl [MFC], SortGroups", "CListCtrl [MFC], SortItems", "CListCtrl [MFC], SortItemsEx", "CListCtrl [MFC], SubItemHitTest", "CListCtrl [MFC], Update"] --- @@ -427,7 +427,7 @@ CImageList* CreateDragImage( ### Parameters -*`nItem*`\ +*`nItem`*\ Index of the item whose drag image list is to be created. *`lpPoint`*\ @@ -3985,9 +3985,7 @@ int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2, UNREFERENCED_PARAMETER(lParamSort); return (int)(lParam1 - lParam2); } -``` -```cpp // Sort the items by passing in the comparison function. void CListCtrlDlg::Sort() { diff --git a/docs/mfc/reference/cmapstringtoob-class.md b/docs/mfc/reference/cmapstringtoob-class.md index 7bad946bf2..7d7404e995 100644 --- a/docs/mfc/reference/cmapstringtoob-class.md +++ b/docs/mfc/reference/cmapstringtoob-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: CMapStringToOb Class" title: "CMapStringToOb Class" -ms.date: "11/04/2016" +description: "Learn more about: CMapStringToOb Class" +ms.date: 11/04/2016 f1_keywords: ["CMapStringToOb", "AFXCOLL/CMapStringToOb", "AFXCOLL/CMapStringToOb::CMapStringToOb", "AFXCOLL/CMapStringToOb::GetCount", "AFXCOLL/CMapStringToOb::GetHashTableSize", "AFXCOLL/CMapStringToOb::GetNextAssoc", "AFXCOLL/CMapStringToOb::GetSize", "AFXCOLL/CMapStringToOb::GetStartPosition", "AFXCOLL/CMapStringToOb::HashKey", "AFXCOLL/CMapStringToOb::InitHashTable", "AFXCOLL/CMapStringToOb::IsEmpty", "AFXCOLL/CMapStringToOb::Lookup", "AFXCOLL/CMapStringToOb::LookupKey", "AFXCOLL/CMapStringToOb::RemoveAll", "AFXCOLL/CMapStringToOb::RemoveKey", "AFXCOLL/CMapStringToOb::SetAt"] helpviewer_keywords: ["CMapStringToOb [MFC], CMapStringToOb", "CMapStringToOb [MFC], GetCount", "CMapStringToOb [MFC], GetHashTableSize", "CMapStringToOb [MFC], GetNextAssoc", "CMapStringToOb [MFC], GetSize", "CMapStringToOb [MFC], GetStartPosition", "CMapStringToOb [MFC], HashKey", "CMapStringToOb [MFC], InitHashTable", "CMapStringToOb [MFC], IsEmpty", "CMapStringToOb [MFC], Lookup", "CMapStringToOb [MFC], LookupKey", "CMapStringToOb [MFC], RemoveAll", "CMapStringToOb [MFC], RemoveKey", "CMapStringToOb [MFC], SetAt"] -ms.assetid: 09653980-b885-4f3a-8594-0aeb7f94c601 --- -# CMapStringToOb Class +# `CMapStringToOb` Class A dictionary collection class that maps unique `CString` objects to `CObject` pointers. @@ -22,57 +21,57 @@ class CMapStringToOb : public CObject |Name|Description| |----------|-----------------| -|[CMapStringToOb::CMapStringToOb](#cmapstringtoob)|Constructor.| +|[`CMapStringToOb::CMapStringToOb`](#cmapstringtoob)|Constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CMapStringToOb::GetCount](#getcount)|Returns the number of elements in this map.| -|[CMapStringToOb::GetHashTableSize](#gethashtablesize)|Determines the current number of elements in the hash table.| -|[CMapStringToOb::GetNextAssoc](#getnextassoc)|Gets the next element for iterating.| -|[CMapStringToOb::GetSize](#getsize)|Returns the number of elements in this map.| -|[CMapStringToOb::GetStartPosition](#getstartposition)|Returns the position of the first element.| -|[CMapStringToOb::HashKey](#hashkey)|Calculates the hash value of a specified key.| -|[CMapStringToOb::InitHashTable](#inithashtable)|Initializes the hash table.| -|[CMapStringToOb::IsEmpty](#isempty)|Tests for the empty-map condition (no elements).| -|[CMapStringToOb::Lookup](#lookup)|Looks up a void pointer based on the void pointer key. The pointer value, not the entity it points to, is used for the key comparison.| -|[CMapStringToOb::LookupKey](#lookupkey)|Returns a reference to the key associated with the specified key value.| -|[CMapStringToOb::RemoveAll](#removeall)|Removes all the elements from this map.| -|[CMapStringToOb::RemoveKey](#removekey)|Removes an element specified by a key.| -|[CMapStringToOb::SetAt](#setat)|Inserts an element into the map; replaces an existing element if a matching key is found.| +|[`CMapStringToOb::GetCount`](#getcount)|Returns the number of elements in this map.| +|[`CMapStringToOb::GetHashTableSize`](#gethashtablesize)|Determines the current number of elements in the hash table.| +|[`CMapStringToOb::GetNextAssoc`](#getnextassoc)|Gets the next element for iterating.| +|[`CMapStringToOb::GetSize`](#getsize)|Returns the number of elements in this map.| +|[`CMapStringToOb::GetStartPosition`](#getstartposition)|Returns the position of the first element.| +|[`CMapStringToOb::HashKey`](#hashkey)|Calculates the hash value of a specified key.| +|[`CMapStringToOb::InitHashTable`](#inithashtable)|Initializes the hash table.| +|[`CMapStringToOb::IsEmpty`](#isempty)|Tests for the empty-map condition (no elements).| +|[`CMapStringToOb::Lookup`](#lookup)|Looks up a void pointer based on the void pointer key. The pointer value, not the entity it points to, is used for the key comparison.| +|[`CMapStringToOb::LookupKey`](#lookupkey)|Returns a reference to the key associated with the specified key value.| +|[`CMapStringToOb::RemoveAll`](#removeall)|Removes all the elements from this map.| +|[`CMapStringToOb::RemoveKey`](#removekey)|Removes an element specified by a key.| +|[`CMapStringToOb::SetAt`](#setat)|Inserts an element into the map; replaces an existing element if a matching key is found.| ### Public Operators |Name|Description| |----------|-----------------| -|[CMapStringToOb::operator \[ \]](#operator_at)|Inserts an element into the map — operator substitution for `SetAt`.| +|[`CMapStringToOb::operator [ ]`](#operator_at)|Inserts an element into the map — operator substitution for `SetAt`.| ## Remarks -Once you have inserted a `CString`- `CObject*` pair (element) into the map, you can efficiently retrieve or delete the pair using a string or a `CString` value as a key. You can also iterate over all the elements in the map. +Once you've inserted a `CString`- `CObject*` pair (element) into the map, you can efficiently retrieve or delete the pair using a string or a `CString` value as a key. You can also iterate over all the elements in the map. -A variable of type POSITION is used for alternate entry access in all map variations. You can use a POSITION to "remember" an entry and to iterate through the map. You might think that this iteration is sequential by key value; it is not. The sequence of retrieved elements is indeterminate. +A variable of type `POSITION` is used for alternate entry access in all map variations. You can use a `POSITION` to "remember" an entry and to iterate through the map. You might think that this iteration is sequential by key value; it isn't. The sequence of retrieved elements is indeterminate. -`CMapStringToOb` incorporates the `IMPLEMENT_SERIAL` macro to support serialization and dumping of its elements. Each element is serialized in turn if a map is stored to an archive, either with the overloaded insertion ( **<<**) operator or with the `Serialize` member function. +`CMapStringToOb` incorporates the `IMPLEMENT_SERIAL` macro to support serialization and dumping of its elements. Each element is serialized in turn if a map is stored to an archive, either with the overloaded insertion ( **`<<`**) operator or with the `Serialize` member function. If you need a diagnostic dump of the individual elements in the map (the `CString` value and the `CObject` contents), you must set the depth of the dump context to 1 or greater. -When a `CMapStringToOb` object is deleted, or when its elements are removed, the `CString` objects and the `CObject` pointers are removed. The objects referenced by the `CObject` pointers are not destroyed. +When a `CMapStringToOb` object is deleted, or when its elements are removed, the `CString` objects and the `CObject` pointers are removed. The objects referenced by the `CObject` pointers aren't destroyed. Map class derivation is similar to list derivation. See the article [Collections](../../mfc/collections.md) for an illustration of the derivation of a special-purpose list class. ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) `CMapStringToOb` ## Requirements -**Header:** afxcoll.h +**Header:** `afxcoll.h` -## CMapStringToOb::CMapStringToOb +## `CMapStringToOb::CMapStringToOb` Constructs an empty `CString`-to- `CObject*` map. @@ -82,31 +81,31 @@ CMapStringToOb(INT_PTR nBlockSize = 10); ### Parameters -*nBlockSize*
+*`nBlockSize`*\ Specifies the memory-allocation granularity for extending the map. ### Remarks -As the map grows, memory is allocated in units of *nBlockSize* entries. +As the map grows, memory is allocated in units of *`nBlockSize`* entries. The following table shows other member functions that are similar to `CMapStringToOb:: CMapStringToOb`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**CMapPtrToPtr( INT_PTR** `nBlockSize` **= 10 );**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**CMapPtrToWord( INT_PTR** `nBlockSize` **= 10 );**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**CMapStringToPtr( INT_PTR** `nBlockSize` **= 10 );**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**CMapStringToString( INT_PTR** `nBlockSize` **= 10 );**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**CMapWordToOb( INT_PTR** `nBlockSize` **= 10 );**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**MapWordToPtr( INT_PTR** `nBlockSize` **= 10 );**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`CMapPtrToPtr( INT_PTR nBlockSize = 10 );`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`CMapPtrToWord( INT_PTR nBlockSize = 10 );`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`CMapStringToPtr( INT_PTR nBlockSize = 10 );`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`CMapStringToString( INT_PTR nBlockSize = 10 );`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`CMapWordToOb( INT_PTR nBlockSize = 10 );`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`MapWordToPtr( INT_PTR nBlockSize = 10 );`**| ### Example [!code-cpp[NVC_MFCCollections#63](../../mfc/codesnippet/cpp/cmapstringtoob-class_1.cpp)] -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. -## CMapStringToOb::GetCount +## `CMapStringToOb::GetCount` Determines how many elements are in the map. @@ -124,20 +123,20 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**INT_PTR GetCount( ) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**INT_PTR GetCount( ) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**INT_PTR GetCount( ) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**INT_PTR GetCount( ) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**INT_PTR GetCount( ) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**INT_PTR GetCount( ) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`INT_PTR GetCount() const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`INT_PTR GetCount() const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`INT_PTR GetCount() const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`INT_PTR GetCount() const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`INT_PTR GetCount() const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`INT_PTR GetCount() const;`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#64](../../mfc/codesnippet/cpp/cmapstringtoob-class_2.cpp)] -## CMapStringToOb::GetHashTableSize +## `CMapStringToOb::GetHashTableSize` Determines the current number of elements in the hash table. @@ -155,16 +154,16 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**UINT GetHashTableSize( ) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**UINT GetHashTableSize( ) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**UINT GetHashTableSize( ) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**UINT GetHashTableSize( ) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**UINT GetHashTableSize( ) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**UINT GetHashTableSize( ) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`UINT GetHashTableSize() const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`UINT GetHashTableSize() const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`UINT GetHashTableSize() const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`UINT GetHashTableSize() const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`UINT GetHashTableSize() const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`UINT GetHashTableSize() const;`**| -## CMapStringToOb::GetNextAssoc +## `CMapStringToOb::GetNextAssoc` -Retrieves the map element at *rNextPosition*, then updates *rNextPosition* to refer to the next element in the map. +Retrieves the map element at *`rNextPosition`*, then updates *`rNextPosition`* to refer to the next element in the map. ```cpp void GetNextAssoc( @@ -175,41 +174,41 @@ void GetNextAssoc( ### Parameters -*rNextPosition*
+*`rNextPosition`*\ Specifies a reference to a POSITION value returned by a previous `GetNextAssoc` or `GetStartPosition` call. -*rKey*
+*`rKey`*\ Specifies the returned key of the retrieved element (a string). -*rValue*
-Specifies the returned value of the retrieved element (a `CObject` pointer). See Remarks for more about this parameter. +*`rValue`*\ +Specifies the returned value of the retrieved element (a `CObject` pointer). See [Remarks](#getnextassoc-remarks) for more about this parameter. -### Remarks +### Remarks -This function is most useful for iterating through all the elements in the map. Note that the position sequence is not necessarily the same as the key value sequence. +This function is most useful for iterating through all the elements in the map. Note that the position sequence isn't necessarily the same as the key value sequence. -If the retrieved element is the last in the map, then the new value of *rNextPosition* is set to NULL. +If the retrieved element is the last in the map, then the new value of *`rNextPosition`* is set to `NULL`. -For the *rValue* parameter, be sure to cast your object type to **CObject\*&**, which is what the compiler requires, as shown in the following example: +For the *`rValue`* parameter, be sure to cast your object type to **`CObject*&`**, which is what the compiler requires, as shown in the following example: [!code-cpp[NVC_MFCCollections#65](../../mfc/codesnippet/cpp/cmapstringtoob-class_3.cpp)] -This is not true of `GetNextAssoc` for maps based on templates. +This isn't true of `GetNextAssoc` for maps based on templates. The following table shows other member functions that are similar to `CMapStringToOb::GetNextAssoc`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, void\*&** *rKey* **, void\*&** *rValue* **) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, void\*&** *rKey* **, WORD&** *rValue* **) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, CString&** *rKey* **, void\*&** *rValue* **) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, CString&** *rKey* **, CString&** *rValue* **) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, WORD&** *rKey* **, CObject\*&** *rValue* **) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**void GetNextAssoc( POSITION&** *rNextPosition* **, WORD&** *rKey* **, void\*&** *rValue* **) const;**| +|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , void*& rKey , void*& rValue ) const;`**| +|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , void*& rKey , WORD& rValue ) const;`**| +|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , CString& rKey , void*& rValue ) const;`**| +|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , CString& rKey , CString& rValue ) const;`**| +|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , CObject*& rValue ) const;`**| +|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**`void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , void*& rValue ) const;`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#66](../../mfc/codesnippet/cpp/cmapstringtoob-class_4.cpp)] @@ -222,7 +221,7 @@ Homer : a CAge at $4766 36 Bart : a CAge at $45D4 13 ``` -## CMapStringToOb::GetSize +## `CMapStringToOb::GetSize` Returns the number of map elements. @@ -242,20 +241,20 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**INT_PTR GetSize( ) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**INT_PTR GetSize( ) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**INT_PTR GetSize( ) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**INT_PTR GetSize( ) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**INT_PTR GetSize( ) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**INT_PTR GetSize( ) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`INT_PTR GetSize() const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`INT_PTR GetSize() const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`INT_PTR GetSize() const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`INT_PTR GetSize() const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`INT_PTR GetSize() const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`INT_PTR GetSize() const;`**| ### Example [!code-cpp[NVC_MFCCollections#67](../../mfc/codesnippet/cpp/cmapstringtoob-class_5.cpp)] -## CMapStringToOb::GetStartPosition +## `CMapStringToOb::GetStartPosition` -Starts a map iteration by returning a POSITION value that can be passed to a `GetNextAssoc` call. +Starts a map iteration by returning a `POSITION` value that can be passed to a `GetNextAssoc` call. ``` POSITION GetStartPosition() const; @@ -263,28 +262,28 @@ POSITION GetStartPosition() const; ### Return Value -A POSITION value that indicates a starting position for iterating the map; or NULL if the map is empty. +A `POSITION` value that indicates a starting position for iterating the map; or `NULL` if the map is empty. ### Remarks -The iteration sequence is not predictable; therefore, the "first element in the map" has no special significance. +The iteration sequence isn't predictable; therefore, the "first element in the map" has no special significance. The following table shows other member functions that are similar to `CMapStringToOb::GetStartPosition`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**POSITION GetStartPosition( ) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**POSITION GetStartPosition( ) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**POSITION GetStartPosition( ) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**POSITION GetStartPosition( ) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**POSITION GetStartPosition( ) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**POSITION GetStartPosition( ) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`POSITION GetStartPosition() const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`POSITION GetStartPosition() const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`POSITION GetStartPosition() const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`POSITION GetStartPosition() const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`POSITION GetStartPosition() const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`POSITION GetStartPosition() const;`**| ### Example -See the example for [CMapStringToOb::GetNextAssoc](#getnextassoc). +See the example for [`CMapStringToOb::GetNextAssoc`](#getnextassoc). -## CMapStringToOb::HashKey +## `CMapStringToOb::HashKey` Calculates the hash value of a specified key. @@ -294,7 +293,7 @@ UINT HashKey(LPCTSTR key) const; ### Parameters -*key*
+*`key`*\ The key whose hash value is to be calculated. ### Return Value @@ -307,14 +306,14 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**UINT HashKey( void** \* `key` **) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**UINT HashKey( void** \* `key` **) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**UINT HashKey( LPCTSTR** `key` **) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**UINT HashKey( LPCTSTR** `key` **) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**UINT HashKey( WORD** `key` **) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**UINT HashKey( WORD** `key` **) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`UINT HashKey( void *key ) const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`UINT HashKey( void *key ) const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`UINT HashKey( LPCTSTR key ) const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`UINT HashKey( LPCTSTR key ) const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`UINT HashKey( WORD key ) const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`UINT HashKey( WORD key ) const;`**| -## CMapStringToOb::InitHashTable +## `CMapStringToOb::InitHashTable` Initializes the hash table. @@ -326,11 +325,11 @@ void InitHashTable( ### Parameters -*hashSize*
+*`hashSize`*\ Number of entries in the hash table. -*bAllocNow*
-If TRUE, allocates the hash table upon initialization; otherwise the table is allocated when needed. +*`bAllocNow`*\ +If `TRUE`, allocates the hash table upon initialization; otherwise the table is allocated when needed. ### Remarks @@ -340,14 +339,14 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**void InitHashTable( UINT** `hashSize` **, BOOL** `bAllocNow` **= TRUE );**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );`**| -## CMapStringToOb::IsEmpty +## `CMapStringToOb::IsEmpty` Determines whether the map is empty. @@ -361,22 +360,22 @@ Nonzero if this map contains no elements; otherwise 0. ### Example -See the example for [RemoveAll](#removeall). +See the example for [`RemoveAll`](#removeall). ### Remarks -The following table shows other member functions that are similar to **CMapStringToOb:: IsEmpty**. +The following table shows other member functions that are similar to **`CMapStringToOb:: IsEmpty`**. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**BOOL IsEmpty( ) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**BOOL IsEmpty( ) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**BOOL IsEmpty( ) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**BOOL IsEmpty( ) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**BOOL IsEmpty( ) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**BOOL IsEmpty( ) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`BOOL IsEmpty() const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`BOOL IsEmpty() const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`BOOL IsEmpty() const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`BOOL IsEmpty() const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`BOOL IsEmpty() const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`BOOL IsEmpty() const;`**| -## CMapStringToOb::Lookup +## `CMapStringToOb::Lookup` Returns a `CObject` pointer based on a `CString` value. @@ -388,10 +387,10 @@ BOOL Lookup( ### Parameters -*key*
+*`key`*\ Specifies the string key that identifies the element to be looked up. -*rValue*
+*`rValue`*\ Specifies the returned value from the looked-up element. ### Return Value @@ -400,26 +399,26 @@ Nonzero if the element was found; otherwise 0. ### Remarks -`Lookup` uses a hashing algorithm to quickly find the map element with a key that matches exactly ( `CString` value). +`Lookup` uses a hashing algorithm to quickly find the map element with a key that matches exactly (`CString` value). The following table shows other member functions that are similar to `CMapStringToOb::LookUp`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**BOOL Lookup( void** \* `key` **, void\*&** `rValue` **) const;**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**BOOL Lookup( void** \* `key` **, WORD&** `rValue` **) const;**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**BOOL Lookup( LPCTSTR** `key` **, void\*&** `rValue` **) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**BOOL Lookup( LPCTSTR** `key` **, CString&** `rValue` **) const;**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**BOOL Lookup( WORD** `key` **, CObject\*&** `rValue` **) const;**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**BOOL Lookup( WORD** `key` **, void\*&** `rValue` **) const;**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`BOOL Lookup( void *key , void*& rValue ) const;`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`BOOL Lookup( void *key , WORD& rValue ) const;`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`BOOL Lookup( LPCTSTR key , void*& rValue ) const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`BOOL Lookup( LPCTSTR key , CString& rValue ) const;`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`BOOL Lookup( WORD key , CObject*& rValue ) const;`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`BOOL Lookup( WORD key , void*& rValue ) const;`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#68](../../mfc/codesnippet/cpp/cmapstringtoob-class_6.cpp)] -## CMapStringToOb::LookupKey +## `CMapStringToOb::LookupKey` Returns a reference to the key associated with the specified key value. @@ -431,10 +430,10 @@ BOOL LookupKey( ### Parameters -*key*
+*`key`*\ Specifies the string key that identifies the element to be looked up. -*rKey*
+*`rKey`*\ The reference to the associated key. ### Return Value @@ -449,10 +448,10 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**BOOL LookupKey( LPCTSTR** `key` **, LPCTSTR&** `rKey` **) const;**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**BOOL LookupKey( LPCTSTR** `key` **, LPCTSTR&** `rKey` **) const;**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;`**| -## CMapStringToOb::operator [ ] +## `CMapStringToOb::operator [ ]` A convenient substitute for the `SetAt` member function. @@ -462,28 +461,28 @@ CObject*& operator[ ](lpctstr key); ### Return Value -A reference to a pointer to a `CObject` object; or NULL if the map is empty or *key* is out of range. +A reference to a pointer to a `CObject` object; or `NULL` if the map is empty or *`key`* is out of range. ### Remarks -Thus it can be used only on the left side of an assignment statement (an l-value). If there is no map element with the specified key, then a new element is created. +Thus it can be used only on the left side of an assignment statement (an `l-value`). If there's no map element with the specified key, then a new element is created. -There is no "right side" (r-value) equivalent to this operator because there is a possibility that a key may not be found in the map. Use the `Lookup` member function for element retrieval. +There's no "right side" (`r-value`) equivalent to this operator because there's a possibility that a key may not be found in the map. Use the `Lookup` member function for element retrieval. The following table shows other member functions that are similar to `CMapStringToOb::operator []`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|void\*& operator\[](void \* `key` **\);**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**WORD& operator\[](void** \* `key` **\);**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**void\*& operator\[](lpctstr** `key` **\);**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**CString& operator\[](lpctstr** `key` **\);**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**CObject\*& operator\[](word** `key` **\);**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**void\*& operator\[](word** `key` **\);**| +|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**`void*& operator[](void *key );`**| +|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**`WORD& operator[](void *key );`**| +|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**`void*& operator[](lpctstr key );`**| +|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**`CString& operator[](lpctstr key );`**| +|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**`CObject*& operator[](word key );`**| +|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**`void*& operator[](word key );`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#72](../../mfc/codesnippet/cpp/cmapstringtoob-class_7.cpp)] @@ -495,7 +494,7 @@ Operator [] example: A CMapStringToOb with 2 elements [Bart] = a CAge at $497E 13 ``` -## CMapStringToOb::RemoveAll +## `CMapStringToOb::RemoveAll` Removes all the elements from this map and destroys the `CString` key objects. @@ -505,7 +504,7 @@ void RemoveAll(); ### Remarks -The `CObject` objects referenced by each key are not destroyed. The `RemoveAll` function can cause memory leaks if you do not ensure that the referenced `CObject` objects are destroyed. +The `CObject` objects referenced by each key aren't destroyed. The `RemoveAll` function can cause memory leaks if you don't ensure that the referenced `CObject` objects are destroyed. The function works correctly if the map is already empty. @@ -513,20 +512,20 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**void RemoveAll( );**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**void RemoveAll( );**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**void RemoveAll( );**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**void RemoveAll( );**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**void RemoveAll( );**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**void RemoveAll( );**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`void RemoveAll();`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`void RemoveAll();`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`void RemoveAll();`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`void RemoveAll();`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`void RemoveAll();`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`void RemoveAll();`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#69](../../mfc/codesnippet/cpp/cmapstringtoob-class_8.cpp)] -## CMapStringToOb::RemoveKey +## `CMapStringToOb::RemoveKey` Looks up the map entry corresponding to the supplied key; then, if the key is found, removes the entry. @@ -536,7 +535,7 @@ BOOL RemoveKey(LPCTSTR key); ### Parameters -*key*
+*`key`*\ Specifies the string used for map lookup. ### Return Value @@ -545,22 +544,22 @@ Nonzero if the entry was found and successfully removed; otherwise 0. ### Remarks -This can cause memory leaks if the `CObject` object is not deleted elsewhere. +This can cause memory leaks if the `CObject` object isn't deleted elsewhere. The following table shows other member functions that are similar to `CMapStringToOb::RemoveKey`. |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**BOOL RemoveKey( void** \* `key` **);**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**BOOL RemoveKey( void** \* `key` **);**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**BOOL RemoveKey( LPCTSTR** `key` **);**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**BOOL RemoveKey( LPCTSTR** `key` **);**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**BOOL RemoveKey( WORD** `key` **);**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**BOOL RemoveKey( WORD** `key` **);**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`BOOL RemoveKey( void *key );`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`BOOL RemoveKey( void *key );`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`BOOL RemoveKey( LPCTSTR key );`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`BOOL RemoveKey( LPCTSTR key );`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`BOOL RemoveKey( WORD key );`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`BOOL RemoveKey( WORD key );`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#70](../../mfc/codesnippet/cpp/cmapstringtoob-class_9.cpp)] @@ -573,7 +572,7 @@ RemoveKey example: A CMapStringToOb with 3 elements [Bart] = a CAge at $4634 13 ``` -## CMapStringToOb::SetAt +## `CMapStringToOb::SetAt` The primary means to insert an element in a map. @@ -585,10 +584,10 @@ void SetAt( ### Parameters -*key*
+*`key`*\ Specifies the string that is the key of the new element. -*newValue*
+*`newValue`*\ Specifies the `CObject` pointer that is the value of the new element. ### Remarks @@ -599,16 +598,16 @@ The following table shows other member functions that are similar to `CMapString |Class|Member Function| |-----------|---------------------| -|[CMapPtrToPtr](../../mfc/reference/cmapptrtoptr-class.md)|**void SetAt( void** \* `key` **, void** \* `newValue` **);**| -|[CMapPtrToWord](../../mfc/reference/cmapptrtoword-class.md)|**void SetAt( void** \* `key` **, WORD** `newValue` **);**| -|[CMapStringToPtr](../../mfc/reference/cmapstringtoptr-class.md)|**void SetAt( LPCTSTR** `key` **, void** \* `newValue` **);**| -|[CMapStringToString](../../mfc/reference/cmapstringtostring-class.md)|**void SetAt( LPCTSTR** `key` **, LPCTSTR** `newValue` **);**| -|[CMapWordToOb](../../mfc/reference/cmapwordtoob-class.md)|**void SetAt( WORD** `key` **, CObject** \* `newValue` **);**| -|[CMapWordToPtr](../../mfc/reference/cmapwordtoptr-class.md)|**void SetAt( WORD** `key` **, void** \* `newValue` **);**| +|[`CMapPtrToPtr`](../../mfc/reference/cmapptrtoptr-class.md)|**`void SetAt( void *key , void *newValue );`**| +|[`CMapPtrToWord`](../../mfc/reference/cmapptrtoword-class.md)|**`void SetAt( void *key , WORD newValue );`**| +|[`CMapStringToPtr`](../../mfc/reference/cmapstringtoptr-class.md)|**`void SetAt( LPCTSTR key , void *newValue );`**| +|[`CMapStringToString`](../../mfc/reference/cmapstringtostring-class.md)|**`void SetAt( LPCTSTR key , LPCTSTR newValue );`**| +|[`CMapWordToOb`](../../mfc/reference/cmapwordtoob-class.md)|**`void SetAt( WORD key , CObject *newValue );`**| +|[`CMapWordToPtr`](../../mfc/reference/cmapwordtoptr-class.md)|**`void SetAt( WORD key , void *newValue );`**| ### Example -See [CObList::CObList](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. +See [`CObList::CObList`](../../mfc/reference/coblist-class.md#coblist) for a listing of the `CAge` class used in all collection examples. [!code-cpp[NVC_MFCCollections#71](../../mfc/codesnippet/cpp/cmapstringtoob-class_10.cpp)] @@ -625,11 +624,11 @@ after Lisa's birthday: A CMapStringToOb with 2 elements ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CMapPtrToPtr Class](../../mfc/reference/cmapptrtoptr-class.md)
-[CMapPtrToWord Class](../../mfc/reference/cmapptrtoword-class.md)
-[CMapStringToPtr Class](../../mfc/reference/cmapstringtoptr-class.md)
-[CMapStringToString Class](../../mfc/reference/cmapstringtostring-class.md)
-[CMapWordToOb Class](../../mfc/reference/cmapwordtoob-class.md)
-[CMapWordToPtr Class](../../mfc/reference/cmapwordtoptr-class.md) +[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CMapPtrToPtr` Class](../../mfc/reference/cmapptrtoptr-class.md)\ +[`CMapPtrToWord` Class](../../mfc/reference/cmapptrtoword-class.md)\ +[`CMapStringToPtr` Class](../../mfc/reference/cmapstringtoptr-class.md)\ +[`CMapStringToString` Class](../../mfc/reference/cmapstringtostring-class.md)\ +[`CMapWordToOb` Class](../../mfc/reference/cmapwordtoob-class.md)\ +[`CMapWordToPtr` Class](../../mfc/reference/cmapwordtoptr-class.md) diff --git a/docs/mfc/reference/cmdichildwndex-class.md b/docs/mfc/reference/cmdichildwndex-class.md index 22d33838a3..b1f2e320dd 100644 --- a/docs/mfc/reference/cmdichildwndex-class.md +++ b/docs/mfc/reference/cmdichildwndex-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMDIChildWndEx Class" title: "CMDIChildWndEx Class" +description: "Learn more about: CMDIChildWndEx Class" ms.date: "10/18/2018" f1_keywords: ["CMDIChildWndEx", "AFXMDICHILDWNDEX/CMDIChildWndEx", "AFXMDICHILDWNDEX/CMDIChildWndEx::ActivateTopLevelFrame", "AFXMDICHILDWNDEX/CMDIChildWndEx::AddPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::AddTabbedPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::AdjustDockingLayout", "AFXMDICHILDWNDEX/CMDIChildWndEx::CanShowOnMDITabs", "AFXMDICHILDWNDEX/CMDIChildWndEx::CanShowOnTaskBarTabs", "AFXMDICHILDWNDEX/CMDIChildWndEx::CanShowOnWindowsList", "AFXMDICHILDWNDEX/CMDIChildWndEx::DockPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::DockPaneLeftOf", "AFXMDICHILDWNDEX/CMDIChildWndEx::EnableAutoHidePanes", "AFXMDICHILDWNDEX/CMDIChildWndEx::EnableDocking", "AFXMDICHILDWNDEX/CMDIChildWndEx::EnableTaskbarThumbnailClipRect", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetDockingManager", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetDocumentName", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetFrameIcon", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetFrameText", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetRelatedTabGroup", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetTabbedPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetTabProxyWnd", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetTaskbarPreviewWnd", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetTaskbarThumbnailClipRect", "AFXMDICHILDWNDEX/CMDIChildWndEx::GetToolbarButtonToolTipText", "AFXMDICHILDWNDEX/CMDIChildWndEx::InsertPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::InvalidateIconicBitmaps", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsPointNearDockSite", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsReadOnly", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsRegisteredWithTaskbarTabs", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsTabbedPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsTaskbarTabsSupportEnabled", "AFXMDICHILDWNDEX/CMDIChildWndEx::IsTaskbarThumbnailClipRectEnabled", "AFXMDICHILDWNDEX/CMDIChildWndEx::m_dwDefaultTaskbarTabPropertyFlags", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnGetIconicLivePreviewBitmap", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnGetIconicThumbnail", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnMoveMiniFrame", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnPressTaskbarThmbnailCloseButton", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnSetPreviewMode", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnTaskbarTabThumbnailActivate", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnTaskbarTabThumbnailMouseActivate", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnTaskbarTabThumbnailStretch", "AFXMDICHILDWNDEX/CMDIChildWndEx::OnUpdateFrameTitle", "AFXMDICHILDWNDEX/CMDIChildWndEx::PaneFromPoint", "AFXMDICHILDWNDEX/CMDIChildWndEx::RecalcLayout", "AFXMDICHILDWNDEX/CMDIChildWndEx::RegisterTaskbarTab", "AFXMDICHILDWNDEX/CMDIChildWndEx::RemovePaneFromDockManager", "AFXMDICHILDWNDEX/CMDIChildWndEx::SetRelatedTabGroup", "AFXMDICHILDWNDEX/CMDIChildWndEx::SetTaskbarTabActive", "AFXMDICHILDWNDEX/CMDIChildWndEx::SetTaskbarTabOrder", "AFXMDICHILDWNDEX/CMDIChildWndEx::SetTaskbarTabProperties", "AFXMDICHILDWNDEX/CMDIChildWndEx::SetTaskbarThumbnailClipRect", "AFXMDICHILDWNDEX/CMDIChildWndEx::ShowPane", "AFXMDICHILDWNDEX/CMDIChildWndEx::UnregisterTaskbarTab", "AFXMDICHILDWNDEX/CMDIChildWndEx::UpdateTaskbarTabIcon"] helpviewer_keywords: ["CMDIChildWndEx [MFC], ActivateTopLevelFrame", "CMDIChildWndEx [MFC], AddPane", "CMDIChildWndEx [MFC], AddTabbedPane", "CMDIChildWndEx [MFC], AdjustDockingLayout", "CMDIChildWndEx [MFC], CanShowOnMDITabs", "CMDIChildWndEx [MFC], CanShowOnTaskBarTabs", "CMDIChildWndEx [MFC], CanShowOnWindowsList", "CMDIChildWndEx [MFC], DockPane", "CMDIChildWndEx [MFC], DockPaneLeftOf", "CMDIChildWndEx [MFC], EnableAutoHidePanes", "CMDIChildWndEx [MFC], EnableDocking", "CMDIChildWndEx [MFC], EnableTaskbarThumbnailClipRect", "CMDIChildWndEx [MFC], GetDockingManager", "CMDIChildWndEx [MFC], GetDocumentName", "CMDIChildWndEx [MFC], GetFrameIcon", "CMDIChildWndEx [MFC], GetFrameText", "CMDIChildWndEx [MFC], GetPane", "CMDIChildWndEx [MFC], GetRelatedTabGroup", "CMDIChildWndEx [MFC], GetTabbedPane", "CMDIChildWndEx [MFC], GetTabProxyWnd", "CMDIChildWndEx [MFC], GetTaskbarPreviewWnd", "CMDIChildWndEx [MFC], GetTaskbarThumbnailClipRect", "CMDIChildWndEx [MFC], GetToolbarButtonToolTipText", "CMDIChildWndEx [MFC], InsertPane", "CMDIChildWndEx [MFC], InvalidateIconicBitmaps", "CMDIChildWndEx [MFC], IsPointNearDockSite", "CMDIChildWndEx [MFC], IsReadOnly", "CMDIChildWndEx [MFC], IsRegisteredWithTaskbarTabs", "CMDIChildWndEx [MFC], IsTabbedPane", "CMDIChildWndEx [MFC], IsTaskbarTabsSupportEnabled", "CMDIChildWndEx [MFC], IsTaskbarThumbnailClipRectEnabled", "CMDIChildWndEx [MFC], m_dwDefaultTaskbarTabPropertyFlags", "CMDIChildWndEx [MFC], OnGetIconicLivePreviewBitmap", "CMDIChildWndEx [MFC], OnGetIconicThumbnail", "CMDIChildWndEx [MFC], OnMoveMiniFrame", "CMDIChildWndEx [MFC], OnPressTaskbarThmbnailCloseButton", "CMDIChildWndEx [MFC], OnSetPreviewMode", "CMDIChildWndEx [MFC], OnTaskbarTabThumbnailActivate", "CMDIChildWndEx [MFC], OnTaskbarTabThumbnailMouseActivate", "CMDIChildWndEx [MFC], OnTaskbarTabThumbnailStretch", "CMDIChildWndEx [MFC], OnUpdateFrameTitle", "CMDIChildWndEx [MFC], PaneFromPoint", "CMDIChildWndEx [MFC], RecalcLayout", "CMDIChildWndEx [MFC], RegisterTaskbarTab", "CMDIChildWndEx [MFC], RemovePaneFromDockManager", "CMDIChildWndEx [MFC], SetRelatedTabGroup", "CMDIChildWndEx [MFC], SetTaskbarTabActive", "CMDIChildWndEx [MFC], SetTaskbarTabOrder", "CMDIChildWndEx [MFC], SetTaskbarTabProperties", "CMDIChildWndEx [MFC], SetTaskbarThumbnailClipRect", "CMDIChildWndEx [MFC], ShowPane", "CMDIChildWndEx [MFC], UnregisterTaskbarTab", "CMDIChildWndEx [MFC], UpdateTaskbarTabIcon"] -ms.assetid: d39fec06-0bd6-4271-917d-35aae3b24d8e --- # CMDIChildWndEx Class @@ -58,11 +57,11 @@ class CMDIChildWndEx : public CMDIChildWnd |[CMDIChildWndEx::IsTabbedPane](#istabbedpane)|Returns TRUE if the MDI child window contains a docking pane. Otherwise returns FALSE.| |[CMDIChildWndEx::IsTaskbarTabsSupportEnabled](#istaskbartabssupportenabled)|Tells whether the MDI child can appear on Windows 7 taskbar tabs.| |[CMDIChildWndEx::IsTaskbarThumbnailClipRectEnabled](#istaskbarthumbnailcliprectenabled)|Tells whether automatic selection of a portion of a window's client area to display as that window's thumbnail in the taskbar is enabled or disabled.| -|[CMDIChildWndEx::m_dwDefaultTaskbarTabPropertyFlags](#m_dwdefaulttaskbartabpropertyflags)|A combination of flags, which is passed by the framework to the SetTaskbarTabProperties method, when a tab (MDI child) is being registered with Windows 7 taskbar tabs. The default combination is STPF_USEAPPTHUMBNAILWHENACTIVE | STPF_USEAPPPEEKWHENACTIVE.| +|[CMDIChildWndEx::m_dwDefaultTaskbarTabPropertyFlags](#m_dwdefaulttaskbartabpropertyflags)|A combination of flags, which is passed by the framework to the SetTaskbarTabProperties method, when a tab (MDI child) is being registered with Windows 7 taskbar tabs. The default combination is `STPF_USEAPPTHUMBNAILWHENACTIVE | STPF_USEAPPPEEKWHENACTIVE`.| |[CMDIChildWndEx::OnGetIconicLivePreviewBitmap](#ongeticoniclivepreviewbitmap)|Called by the framework when it needs to obtain a bitmap for live preview of MDI child.| |[CMDIChildWndEx::OnGetIconicThumbnail](#ongeticonicthumbnail)|Called by the framework when it needs to obtain a bitmap for iconic thumbnail of MDI child.| |[CMDIChildWndEx::OnMoveMiniFrame](#onmoveminiframe)|Called by the framework to move a mini-frame window.| -|[CMDIChildWndEx::OnPressTaskbarThmbnailCloseButton](#onpresstaskbarthmbnailclosebutton)|Called by the framework when the user presses close button on Taskbar tab thumbnail..| +|[CMDIChildWndEx::OnPressTaskbarThmbnailCloseButton](#onpresstaskbarthmbnailclosebutton)|Called by the framework when the user presses close button on Taskbar tab thumbnail.| |[CMDIChildWndEx::OnSetPreviewMode](#onsetpreviewmode)|Called by the framework to enter or exit print preview mode.| |[CMDIChildWndEx::OnTaskbarTabThumbnailActivate](#ontaskbartabthumbnailactivate)|Called by the framework when the Taskbar tab thumbnail should process WM_ACTIVATE message.| |[CMDIChildWndEx::OnTaskbarTabThumbnailMouseActivate](#ontaskbartabthumbnailmouseactivate)|Called by the framework when the Taskbar tab thumbnail should process WM_MOUSEACTIVATE message.| @@ -927,7 +926,7 @@ AFX_IMPORT_DATA static DWORD m_dwDefaultTaskbarTabPropertyFlags; ### Remarks -The default combination is STPF_USEAPPTHUMBNAILWHENACTIVE | STPF_USEAPPPEEKWHENACTIVE. +The default combination is `STPF_USEAPPTHUMBNAILWHENACTIVE | STPF_USEAPPPEEKWHENACTIVE`. ## CMDIChildWndEx::IsTaskbarThumbnailClipRectEnabled @@ -953,7 +952,7 @@ BOOL IsTaskbarTabsSupportEnabled(); ### Return Value -TRUE if the MDI child can appear on Windows 7 taskbar tabs; FALSE if the MDI child can not appear on Windows 7 taskbar tabs. +TRUE if the MDI child can appear on Windows 7 taskbar tabs; FALSE if the MDI child cannot appear on Windows 7 taskbar tabs. ### Remarks diff --git a/docs/mfc/reference/cmdiframewnd-class.md b/docs/mfc/reference/cmdiframewnd-class.md index 4a000c3fe8..8e5dc3025a 100644 --- a/docs/mfc/reference/cmdiframewnd-class.md +++ b/docs/mfc/reference/cmdiframewnd-class.md @@ -391,7 +391,7 @@ Do not call this member function if you use the framework to manage your MDI chi ### Example [!code-cpp[NVC_MFCWindowing#19](../../mfc/reference/codesnippet/cpp/cmdiframewnd-class_7.cpp)] - +  [!code-cpp[NVC_MFCWindowing#20](../../mfc/reference/codesnippet/cpp/cmdiframewnd-class_8.cpp)] ## CMDIFrameWnd::MDITile diff --git a/docs/mfc/reference/cmdiframewndex-class.md b/docs/mfc/reference/cmdiframewndex-class.md index 71ca3bc581..bae8259df3 100644 --- a/docs/mfc/reference/cmdiframewndex-class.md +++ b/docs/mfc/reference/cmdiframewndex-class.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: CMDIFrameWndEx Class" title: "CMDIFrameWndEx Class" -ms.date: "11/04/2016" -f1_keywords: ["CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ActiveItemRecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AddPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustClientArea", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustDockingLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AreMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CanCovertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ControlBarToTabbedDocument", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateDocumentWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateNewWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPaneLeftOf", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableAutoHidePanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableDocking", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMainMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableLoadDockState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabbedGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabsLastActiveActivation", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnablePaneMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetActivePopup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetDefaultResId", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMenuBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetRibbonBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetTearOffBars", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetToolbarButtonToolTipText", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::InsertPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMDITabbedGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMemberOfMDITabGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMenuBarAvailable", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPointNearDockSite", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPrintPreview", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabMoveToNextGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabNewGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::NegotiateBorderSpace", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseDockingPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnClosePopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCmdMsg", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuImage", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuLogo", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnEraseMDIClientBackground", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMenuButtonToolHitTest", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMoveMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSetPreviewMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowCustomizePane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowMDITabContextMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSizeMDIClient", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnTearOffMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnUpdateFrameMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::PaneFromPoint", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RemovePaneFromDockManager", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SaveMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetPrintPreviewFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetupToolbarMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::TabbedDocumentToControlBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateCaption", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateMDITabbedBarsIcons", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::WinHelp", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bDisableSetRedraw"] -helpviewer_keywords: ["CMDIFrameWndEx [MFC], ActiveItemRecalcLayout", "CMDIFrameWndEx [MFC], AddPane", "CMDIFrameWndEx [MFC], AdjustClientArea", "CMDIFrameWndEx [MFC], AdjustDockingLayout", "CMDIFrameWndEx [MFC], AreMDITabs", "CMDIFrameWndEx [MFC], CanCovertControlBarToMDIChild", "CMDIFrameWndEx [MFC], ControlBarToTabbedDocument", "CMDIFrameWndEx [MFC], CreateDocumentWindow", "CMDIFrameWndEx [MFC], CreateNewWindow", "CMDIFrameWndEx [MFC], DockPane", "CMDIFrameWndEx [MFC], DockPaneLeftOf", "CMDIFrameWndEx [MFC], EnableAutoHidePanes", "CMDIFrameWndEx [MFC], EnableDocking", "CMDIFrameWndEx [MFC], EnableFullScreenMainMenu", "CMDIFrameWndEx [MFC], EnableFullScreenMode", "CMDIFrameWndEx [MFC], EnableLoadDockState", "CMDIFrameWndEx [MFC], EnableMDITabbedGroups", "CMDIFrameWndEx [MFC], EnableMDITabs", "CMDIFrameWndEx [MFC], EnableMDITabsLastActiveActivation", "CMDIFrameWndEx [MFC], EnablePaneMenu", "CMDIFrameWndEx [MFC], EnableWindowsDialog", "CMDIFrameWndEx [MFC], GetActivePopup", "CMDIFrameWndEx [MFC], GetPane", "CMDIFrameWndEx [MFC], GetDefaultResId", "CMDIFrameWndEx [MFC], GetMDITabGroups", "CMDIFrameWndEx [MFC], GetMDITabs", "CMDIFrameWndEx [MFC], GetMDITabsContextMenuAllowedItems", "CMDIFrameWndEx [MFC], GetMenuBar", "CMDIFrameWndEx [MFC], GetRibbonBar", "CMDIFrameWndEx [MFC], GetTearOffBars", "CMDIFrameWndEx [MFC], GetToolbarButtonToolTipText", "CMDIFrameWndEx [MFC], InsertPane", "CMDIFrameWndEx [MFC], IsFullScreen", "CMDIFrameWndEx [MFC], IsMDITabbedGroup", "CMDIFrameWndEx [MFC], IsMemberOfMDITabGroup", "CMDIFrameWndEx [MFC], IsMenuBarAvailable", "CMDIFrameWndEx [MFC], IsPointNearDockSite", "CMDIFrameWndEx [MFC], IsPrintPreview", "CMDIFrameWndEx [MFC], LoadFrame", "CMDIFrameWndEx [MFC], LoadMDIState", "CMDIFrameWndEx [MFC], MDITabMoveToNextGroup", "CMDIFrameWndEx [MFC], MDITabNewGroup", "CMDIFrameWndEx [MFC], NegotiateBorderSpace", "CMDIFrameWndEx [MFC], OnCloseDockingPane", "CMDIFrameWndEx [MFC], OnCloseMiniFrame", "CMDIFrameWndEx [MFC], OnClosePopupMenu", "CMDIFrameWndEx [MFC], OnCmdMsg", "CMDIFrameWndEx [MFC], OnDrawMenuImage", "CMDIFrameWndEx [MFC], OnDrawMenuLogo", "CMDIFrameWndEx [MFC], OnEraseMDIClientBackground", "CMDIFrameWndEx [MFC], OnMenuButtonToolHitTest", "CMDIFrameWndEx [MFC], OnMoveMiniFrame", "CMDIFrameWndEx [MFC], OnSetPreviewMode", "CMDIFrameWndEx [MFC], OnShowCustomizePane", "CMDIFrameWndEx [MFC], OnShowMDITabContextMenu", "CMDIFrameWndEx [MFC], OnShowPanes", "CMDIFrameWndEx [MFC], OnShowPopupMenu", "CMDIFrameWndEx [MFC], OnSizeMDIClient", "CMDIFrameWndEx [MFC], OnTearOffMenu", "CMDIFrameWndEx [MFC], OnUpdateFrameMenu", "CMDIFrameWndEx [MFC], PaneFromPoint", "CMDIFrameWndEx [MFC], RecalcLayout", "CMDIFrameWndEx [MFC], RemovePaneFromDockManager", "CMDIFrameWndEx [MFC], SaveMDIState", "CMDIFrameWndEx [MFC], SetPrintPreviewFrame", "CMDIFrameWndEx [MFC], SetupToolbarMenu", "CMDIFrameWndEx [MFC], ShowFullScreen", "CMDIFrameWndEx [MFC], ShowPane", "CMDIFrameWndEx [MFC], ShowWindowsDialog", "CMDIFrameWndEx [MFC], TabbedDocumentToControlBar", "CMDIFrameWndEx [MFC], UpdateCaption", "CMDIFrameWndEx [MFC], UpdateMDITabbedBarsIcons", "CMDIFrameWndEx [MFC], WinHelp", "CMDIFrameWndEx [MFC], m_bCanCovertControlBarToMDIChild", "CMDIFrameWndEx [MFC], m_bDisableSetRedraw"] -ms.assetid: dbcafcb3-9a7a-4f11-9dfe-ba57565c81d0 +description: "Learn more about: CMDIFrameWndEx class" +ms.date: 08/16/2022 +f1_keywords: ["CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ActiveItemRecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AddPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustClientArea", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustDockingLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AreMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CanConvertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ControlBarToTabbedDocument", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateDocumentWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateNewWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPaneLeftOf", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableAutoHidePanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableDocking", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMainMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableLoadDockState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabbedGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabsLastActiveActivation", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnablePaneMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetActivePopup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetDefaultResId", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMenuBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetRibbonBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetTearOffBars", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetToolbarButtonToolTipText", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::InsertPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMDITabbedGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMemberOfMDITabGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMenuBarAvailable", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPointNearDockSite", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPrintPreview", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabMoveToNextGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabNewGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::NegotiateBorderSpace", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseDockingPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnClosePopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCmdMsg", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuImage", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuLogo", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnEraseMDIClientBackground", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMenuButtonToolHitTest", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMoveMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSetPreviewMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowCustomizePane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowMDITabContextMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSizeMDIClient", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnTearOffMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnUpdateFrameMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::PaneFromPoint", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RemovePaneFromDockManager", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SaveMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetPrintPreviewFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetupToolbarMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::TabbedDocumentToControlBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateCaption", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateMDITabbedBarsIcons", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::WinHelp", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bDisableSetRedraw"] +helpviewer_keywords: ["CMDIFrameWndEx [MFC], ActiveItemRecalcLayout", "CMDIFrameWndEx [MFC], AddPane", "CMDIFrameWndEx [MFC], AdjustClientArea", "CMDIFrameWndEx [MFC], AdjustDockingLayout", "CMDIFrameWndEx [MFC], AreMDITabs", "CMDIFrameWndEx [MFC], CanConvertControlBarToMDIChild", "CMDIFrameWndEx [MFC], ControlBarToTabbedDocument", "CMDIFrameWndEx [MFC], CreateDocumentWindow", "CMDIFrameWndEx [MFC], CreateNewWindow", "CMDIFrameWndEx [MFC], DockPane", "CMDIFrameWndEx [MFC], DockPaneLeftOf", "CMDIFrameWndEx [MFC], EnableAutoHidePanes", "CMDIFrameWndEx [MFC], EnableDocking", "CMDIFrameWndEx [MFC], EnableFullScreenMainMenu", "CMDIFrameWndEx [MFC], EnableFullScreenMode", "CMDIFrameWndEx [MFC], EnableLoadDockState", "CMDIFrameWndEx [MFC], EnableMDITabbedGroups", "CMDIFrameWndEx [MFC], EnableMDITabs", "CMDIFrameWndEx [MFC], EnableMDITabsLastActiveActivation", "CMDIFrameWndEx [MFC], EnablePaneMenu", "CMDIFrameWndEx [MFC], EnableWindowsDialog", "CMDIFrameWndEx [MFC], GetActivePopup", "CMDIFrameWndEx [MFC], GetPane", "CMDIFrameWndEx [MFC], GetDefaultResId", "CMDIFrameWndEx [MFC], GetMDITabGroups", "CMDIFrameWndEx [MFC], GetMDITabs", "CMDIFrameWndEx [MFC], GetMDITabsContextMenuAllowedItems", "CMDIFrameWndEx [MFC], GetMenuBar", "CMDIFrameWndEx [MFC], GetRibbonBar", "CMDIFrameWndEx [MFC], GetTearOffBars", "CMDIFrameWndEx [MFC], GetToolbarButtonToolTipText", "CMDIFrameWndEx [MFC], InsertPane", "CMDIFrameWndEx [MFC], IsFullScreen", "CMDIFrameWndEx [MFC], IsMDITabbedGroup", "CMDIFrameWndEx [MFC], IsMemberOfMDITabGroup", "CMDIFrameWndEx [MFC], IsMenuBarAvailable", "CMDIFrameWndEx [MFC], IsPointNearDockSite", "CMDIFrameWndEx [MFC], IsPrintPreview", "CMDIFrameWndEx [MFC], LoadFrame", "CMDIFrameWndEx [MFC], LoadMDIState", "CMDIFrameWndEx [MFC], MDITabMoveToNextGroup", "CMDIFrameWndEx [MFC], MDITabNewGroup", "CMDIFrameWndEx [MFC], NegotiateBorderSpace", "CMDIFrameWndEx [MFC], OnCloseDockingPane", "CMDIFrameWndEx [MFC], OnCloseMiniFrame", "CMDIFrameWndEx [MFC], OnClosePopupMenu", "CMDIFrameWndEx [MFC], OnCmdMsg", "CMDIFrameWndEx [MFC], OnDrawMenuImage", "CMDIFrameWndEx [MFC], OnDrawMenuLogo", "CMDIFrameWndEx [MFC], OnEraseMDIClientBackground", "CMDIFrameWndEx [MFC], OnMenuButtonToolHitTest", "CMDIFrameWndEx [MFC], OnMoveMiniFrame", "CMDIFrameWndEx [MFC], OnSetPreviewMode", "CMDIFrameWndEx [MFC], OnShowCustomizePane", "CMDIFrameWndEx [MFC], OnShowMDITabContextMenu", "CMDIFrameWndEx [MFC], OnShowPanes", "CMDIFrameWndEx [MFC], OnShowPopupMenu", "CMDIFrameWndEx [MFC], OnSizeMDIClient", "CMDIFrameWndEx [MFC], OnTearOffMenu", "CMDIFrameWndEx [MFC], OnUpdateFrameMenu", "CMDIFrameWndEx [MFC], PaneFromPoint", "CMDIFrameWndEx [MFC], RecalcLayout", "CMDIFrameWndEx [MFC], RemovePaneFromDockManager", "CMDIFrameWndEx [MFC], SaveMDIState", "CMDIFrameWndEx [MFC], SetPrintPreviewFrame", "CMDIFrameWndEx [MFC], SetupToolbarMenu", "CMDIFrameWndEx [MFC], ShowFullScreen", "CMDIFrameWndEx [MFC], ShowPane", "CMDIFrameWndEx [MFC], ShowWindowsDialog", "CMDIFrameWndEx [MFC], TabbedDocumentToControlBar", "CMDIFrameWndEx [MFC], UpdateCaption", "CMDIFrameWndEx [MFC], UpdateMDITabbedBarsIcons", "CMDIFrameWndEx [MFC], WinHelp", "CMDIFrameWndEx [MFC], m_bCanConvertControlBarToMDIChild", "CMDIFrameWndEx [MFC], m_bDisableSetRedraw"] --- -# CMDIFrameWndEx Class +# `CMDIFrameWndEx` class -Extends the functionality of [CMDIFrameWnd](../../mfc/reference/cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. +Extends the functionality of [`CMDIFrameWnd`](../../mfc/reference/cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. ## Syntax -``` +```cpp class CMDIFrameWndEx : public CMDIFrameWnd ``` @@ -22,90 +21,90 @@ class CMDIFrameWndEx : public CMDIFrameWnd |Name|Description| |----------|-----------------| -|[CMDIFrameWndEx::ActiveItemRecalcLayout](#activeitemrecalclayout)|Recalculates the layout of the active item.| -|`CMDIFrameWndEx::AddDockSite`|This method is not used.| -|[CMDIFrameWndEx::AddPane](#addpane)|Registers a pane with the docking manager.| -|[CMDIFrameWndEx::AdjustClientArea](#adjustclientarea)|Reduces the client area to allow for a border.| -|[CMDIFrameWndEx::AdjustDockingLayout](#adjustdockinglayout)|Recalculates the layout of all docked panes.| -|[CMDIFrameWndEx::AreMDITabs](#aremditabs)|Determines whether the MDI Tabs feature or the MDI Tabbed Groups feature is enabled.| -|[CMDIFrameWndEx::CanCovertControlBarToMDIChild](#cancovertcontrolbartomdichild)|Called by the framework to determine whether the frame window can convert docking panes to tabbed documents.| -|[CMDIFrameWndEx::ControlBarToTabbedDocument](#controlbartotabbeddocument)|Converts the specified docking pane to a tabbed document.| -|[CMDIFrameWndEx::CreateDocumentWindow](#createdocumentwindow)|Creates a child document window.| -|[CMDIFrameWndEx::CreateNewWindow](#createnewwindow)|Called by the framework to create a new window.| +|[`CMDIFrameWndEx::ActiveItemRecalcLayout`](#activeitemrecalclayout)|Recalculates the layout of the active item.| +|`CMDIFrameWndEx::AddDockSite`|This method isn't used.| +|[`CMDIFrameWndEx::AddPane`](#addpane)|Registers a pane with the docking manager.| +|[`CMDIFrameWndEx::AdjustClientArea`](#adjustclientarea)|Reduces the client area to allow for a border.| +|[`CMDIFrameWndEx::AdjustDockingLayout`](#adjustdockinglayout)|Recalculates the layout of all docked panes.| +|[`CMDIFrameWndEx::AreMDITabs`](#aremditabs)|Determines whether the MDI Tabs feature or the MDI Tabbed Groups feature is enabled.| +|[`CMDIFrameWndEx::CanConvertControlBarToMDIChild`](#canConvertcontrolbartomdichild)|Called by the framework to determine whether the frame window can convert docking panes to tabbed documents.| +|[`CMDIFrameWndEx::ControlBarToTabbedDocument`](#controlbartotabbeddocument)|Converts the specified docking pane to a tabbed document.| +|[`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow)|Creates a child document window.| +|[`CMDIFrameWndEx::CreateNewWindow`](#createnewwindow)|Called by the framework to create a new window.| |`CMDIFrameWndEx::CreateObject`|Used by the framework to create a dynamic instance of this class type.| -|[CMDIFrameWndEx::DockPane](#dockpane)|Docks the specified pane to the frame window.| -|[CMDIFrameWndEx::DockPaneLeftOf](#dockpaneleftof)|Docks one pane to the left of another pane.| -|[CMDIFrameWndEx::EnableAutoHidePanes](#enableautohidepanes)|Enables auto-hide mode for panes when they are docked at specified sides of the main frame window.| -|[CMDIFrameWndEx::EnableDocking](#enabledocking)|Enables docking of the panes that belong to the MDI frame window.| -|[CMDIFrameWndEx::EnableFullScreenMainMenu](#enablefullscreenmainmenu)|Shows or hides the main menu in full-screen mode.| -|[CMDIFrameWndEx::EnableFullScreenMode](#enablefullscreenmode)|Enables full-screen mode for the frame window.| -|[CMDIFrameWndEx::EnableLoadDockState](#enableloaddockstate)|Enables or disables the loading of the docking state.| -|[CMDIFrameWndEx::EnableMDITabbedGroups](#enablemditabbedgroups)|Enables or disables the MDI Tabbed Groups feature.| -|[CMDIFrameWndEx::EnableMDITabs](#enablemditabs)|Enables or disables the MDI Tabs feature. When enabled, the frame window displays a tab for each MDI child window.| -|[CMDIFrameWndEx::EnableMDITabsLastActiveActivation](#enablemditabslastactiveactivation)|Specifies whether the last active tab should be activated when the user closes the current tab.| -|[CMDIFrameWndEx::EnablePaneMenu](#enablepanemenu)|Enables or disables automatic creation and management of the pop-up pane menu, which displays a list of application panes. .| -|[CMDIFrameWndEx::EnableWindowsDialog](#enablewindowsdialog)|Inserts a menu item whose command ID calls a [CMFCWindowsManagerDialog](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) dialog box.| -|[CMDIFrameWndEx::GetActivePopup](#getactivepopup)|Returns a pointer to the currently displayed popup menu.| -|[CMDIFrameWndEx::GetPane](#getpane)|Returns a pointer to the pane that has the specified control ID.| -|[CMDIFrameWndEx::GetDefaultResId](#getdefaultresid)|Returns the ID of shared resources of the MDI frame window.| -|[CMDIFrameWndEx::GetMDITabGroups](#getmditabgroups)|Returns a list of MDI tabbed windows.| -|[CMDIFrameWndEx::GetMDITabs](#getmditabs)|Returns a reference to the underlined tabbed window.| -|[CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems](#getmditabscontextmenualloweditems)|Returns a combination of flags that determines what context menu items are valid when the MDI Tabbed Groups feature is enabled.| -|[CMDIFrameWndEx::GetMenuBar](#getmenubar)|Returns a pointer to a menu bar object attached to the frame window.| -|[CMDIFrameWndEx::GetRibbonBar](#getribbonbar)|Retrieves the ribbon bar control for the frame.| -|[CMDIFrameWndEx::GetTearOffBars](#gettearoffbars)|Returns a list of [CPane](../../mfc/reference/cpane-class.md)-derived objects that are in a tear-off state.| -|`CMDIFrameWndEx::GetThisClass`|Called by the framework to obtain a pointer to the [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| -|[CMDIFrameWndEx::GetToolbarButtonToolTipText](#gettoolbarbuttontooltiptext)|Called by the framework when the application displays the tooltip for a toolbar button.| -|[CMDIFrameWndEx::InsertPane](#insertpane)|Registers the specified pane with the docking manager.| -|[CMDIFrameWndEx::IsFullScreen](#isfullscreen)|Determines whether the frame window is in full-screen mode.| -|[CMDIFrameWndEx::IsMDITabbedGroup](#ismditabbedgroup)|Determines whether the MDI Tabbed Groups feature is enabled.| -|[CMDIFrameWndEx::IsMemberOfMDITabGroup](#ismemberofmditabgroup)|Determines whether the specified tabbed window is in the list of windows that are in MDI Tabbed Groups.| -|[CMDIFrameWndEx::IsMenuBarAvailable](#ismenubaravailable)|Determines whether the frame window has a menu bar.| -|[CMDIFrameWndEx::IsPointNearDockSite](#ispointneardocksite)|Determines whether a specified point is near the dock site.| -|[CMDIFrameWndEx::IsPrintPreview](#isprintpreview)|Determines whether the frame window is in print-preview mode.| -|[CMDIFrameWndEx::LoadFrame](#loadframe)|Creates a frame window from resource information. (Overrides `CMDIFrameWnd::LoadFrame`.)| -|[CMDIFrameWndEx::LoadMDIState](#loadmdistate)|Loads the specified layout of MDI Tabbed Groups and the list of previously opened documents.| -|[CMDIFrameWndEx::MDITabMoveToNextGroup](#mditabmovetonextgroup)|Moves the active tab from the currently active tabbed window to the next or previous tabbed group.| -|[CMDIFrameWndEx::MDITabNewGroup](#mditabnewgroup)|Creates a new tabbed group that has a single window.| -|[CMDIFrameWndEx::NegotiateBorderSpace](#negotiateborderspace)|Negotiates border space in a frame window during OLE in-place activation.| -|[CMDIFrameWndEx::OnCloseDockingPane](#onclosedockingpane)|Called by the framework when the user clicks the **Close** button on a dockable pane.| -|[CMDIFrameWndEx::OnCloseMiniFrame](#oncloseminiframe)|Called by the framework when the user clicks the **Close** button on a floating mini frame window.| -|[CMDIFrameWndEx::OnClosePopupMenu](#onclosepopupmenu)|Called by the framework when an active pop-up menu processes a WM_DESTROY message.| -|[CMDIFrameWndEx::OnCmdMsg](#oncmdmsg)|Called by the framework to route and dispatch command messages and to update command user-interface objects.| -|[CMDIFrameWndEx::OnDrawMenuImage](#ondrawmenuimage)|Called by the framework when the image associated with a menu item is drawn.| -|[CMDIFrameWndEx::OnDrawMenuLogo](#ondrawmenulogo)|Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md)processes a WM_PAINT message.| -|[CMDIFrameWndEx::OnEraseMDIClientBackground](#onerasemdiclientbackground)|Called by the framework when the MDI frame window processes a WM_ERASEBKGND message.| -|[CMDIFrameWndEx::OnMenuButtonToolHitTest](#onmenubuttontoolhittest)|Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md)object processes a WM_NCHITTEST message.| -|[CMDIFrameWndEx::OnMoveMiniFrame](#onmoveminiframe)|Called by the framework to move a mini-frame window.| -|[CMDIFrameWndEx::OnSetPreviewMode](#onsetpreviewmode)|Sets the application's main frame window print-preview mode. (Overrides [CFrameWnd::OnSetPreviewMode](../../mfc/reference/cframewnd-class.md#onsetpreviewmode).)| -|[CMDIFrameWndEx::OnShowCustomizePane](#onshowcustomizepane)|Called by the framework when a Quick Customize pane is activated.| -|[CMDIFrameWndEx::OnShowMDITabContextMenu](#onshowmditabcontextmenu)|Called by the framework when a context menu should be displayed on one of the tabs. (Valid for MDI Tabbed Groups only.)| -|[CMDIFrameWndEx::OnShowPanes](#onshowpanes)|Called by the framework to show or hide panes.| -|[CMDIFrameWndEx::OnShowPopupMenu](#onshowpopupmenu)|Called by the framework when a pop-up menu is activated.| -|[CMDIFrameWndEx::OnSizeMDIClient](#onsizemdiclient)|Called by the framework when the size of the client MDI window is changing.| -|[CMDIFrameWndEx::OnTearOffMenu](#ontearoffmenu)|Called by the framework when a menu that has a tear-off bar is activated.| -|[CMDIFrameWndEx::OnUpdateFrameMenu](#onupdateframemenu)|Called by the framework to update the frame menu. (Overrides `CMDIFrameWnd::OnUpdateFrameMenu`.)| -|[CMDIFrameWndEx::PaneFromPoint](#panefrompoint)|Returns the docking pane that contains the specified point.| -|`CMDIFrameWndEx::PreTranslateMessage`|Used by class [CWinApp](../../mfc/reference/cwinapp-class.md) to translate window messages before they are dispatched to the [TranslateMessage](/windows/win32/api/winuser/nf-winuser-translatemessage) and [DispatchMessage](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides `CMDIFrameWnd::PreTranslateMessage`.)| -|[CMDIFrameWndEx::RecalcLayout](#recalclayout)|Called by the framework to recalculate the layout of the frame window. (Overrides [CFrameWnd::RecalcLayout](../../mfc/reference/cframewnd-class.md#recalclayout).)| -|[CMDIFrameWndEx::RemovePaneFromDockManager](#removepanefromdockmanager)|Unregisters a pane and removes it from the docking manager.| -|[CMDIFrameWndEx::SaveMDIState](#savemdistate)|Saves the current layout of MDI Tabbed Groups and the list of previously opened documents.| -|[CMDIFrameWndEx::SetPrintPreviewFrame](#setprintpreviewframe)|Sets the print preview frame window.| -|[CMDIFrameWndEx::SetupToolbarMenu](#setuptoolbarmenu)|Modifies a toolbar object by searching for dummy items and replacing them with the specified user-defined items.| -|[CMDIFrameWndEx::ShowFullScreen](#showfullscreen)|Switches the main frame from regular mode to full-screen mode.| -|[CMDIFrameWndEx::ShowPane](#showpane)|Shows or hides the specified pane.| -|[CMDIFrameWndEx::ShowWindowsDialog](#showwindowsdialog)|Creates a [CMFCWindowsManagerDialog](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) box and opens it.| -|[CMDIFrameWndEx::TabbedDocumentToControlBar](#tabbeddocumenttocontrolbar)|Converts the specified tabbed document to a docking pane.| -|[CMDIFrameWndEx::UpdateCaption](#updatecaption)|Called by the framework to update the window frame caption.| -|[CMDIFrameWndEx::UpdateMDITabbedBarsIcons](#updatemditabbedbarsicons)|Sets the icon for each MDI tabbed pane.| -|[CMDIFrameWndEx::WinHelp](#winhelp)|Called by the framework to initiate the WinHelp application or context help. (Overrides [CWnd::WinHelp](../../mfc/reference/cwnd-class.md#winhelp).)| - -### Data Members +|[`CMDIFrameWndEx::DockPane`](#dockpane)|Docks the specified pane to the frame window.| +|[`CMDIFrameWndEx::DockPaneLeftOf`](#dockpaneleftof)|Docks one pane to the left of another pane.| +|[`CMDIFrameWndEx::EnableAutoHidePanes`](#enableautohidepanes)|Enables auto-hide mode for panes when they're docked at specified sides of the main frame window.| +|[`CMDIFrameWndEx::EnableDocking`](#enabledocking)|Enables docking of the panes that belong to the MDI frame window.| +|[`CMDIFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu)|Shows or hides the main menu in full-screen mode.| +|[`CMDIFrameWndEx::EnableFullScreenMode`](#enablefullscreenmode)|Enables full-screen mode for the frame window.| +|[`CMDIFrameWndEx::EnableLoadDockState`](#enableloaddockstate)|Enables or disables the loading of the docking state.| +|[`CMDIFrameWndEx::EnableMDITabbedGroups`](#enablemditabbedgroups)|Enables or disables the MDI Tabbed Groups feature.| +|[`CMDIFrameWndEx::EnableMDITabs`](#enablemditabs)|Enables or disables the MDI Tabs feature. When enabled, the frame window displays a tab for each MDI child window.| +|[`CMDIFrameWndEx::EnableMDITabsLastActiveActivation`](#enablemditabslastactiveactivation)|Specifies whether the last active tab should be activated when the user closes the current tab.| +|[`CMDIFrameWndEx::EnablePaneMenu`](#enablepanemenu)|Enables or disables automatic creation and management of the pop-up pane menu, which displays a list of application panes.| +|[`CMDIFrameWndEx::EnableWindowsDialog`](#enablewindowsdialog)|Inserts a menu item whose command ID calls a [`CMFCWindowsManagerDialog`](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) dialog box.| +|[`CMDIFrameWndEx::GetActivePopup`](#getactivepopup)|Returns a pointer to the currently displayed popup menu.| +|[`CMDIFrameWndEx::GetPane`](#getpane)|Returns a pointer to the pane that has the specified control ID.| +|[`CMDIFrameWndEx::GetDefaultResId`](#getdefaultresid)|Returns the ID of shared resources of the MDI frame window.| +|[`CMDIFrameWndEx::GetMDITabGroups`](#getmditabgroups)|Returns a list of MDI tabbed windows.| +|[`CMDIFrameWndEx::GetMDITabs`](#getmditabs)|Returns a reference to the underlined tabbed window.| +|[`CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems`](#getmditabscontextmenualloweditems)|Returns a combination of flags that determines what context menu items are valid when the MDI Tabbed Groups feature is enabled.| +|[`CMDIFrameWndEx::GetMenuBar`](#getmenubar)|Returns a pointer to a menu bar object attached to the frame window.| +|[`CMDIFrameWndEx::GetRibbonBar`](#getribbonbar)|Retrieves the ribbon bar control for the frame.| +|[`CMDIFrameWndEx::GetTearOffBars`](#gettearoffbars)|Returns a list of [`CPane`](../../mfc/reference/cpane-class.md)-derived objects that are in a tear-off state.| +|`CMDIFrameWndEx::GetThisClass`|Called by the framework to obtain a pointer to the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| +|[`CMDIFrameWndEx::GetToolbarButtonToolTipText`](#gettoolbarbuttontooltiptext)|Called by the framework when the application displays the tooltip for a toolbar button.| +|[`CMDIFrameWndEx::InsertPane`](#insertpane)|Registers the specified pane with the docking manager.| +|[`CMDIFrameWndEx::IsFullScreen`](#isfullscreen)|Determines whether the frame window is in full-screen mode.| +|[`CMDIFrameWndEx::IsMDITabbedGroup`](#ismditabbedgroup)|Determines whether the MDI Tabbed Groups feature is enabled.| +|[`CMDIFrameWndEx::IsMemberOfMDITabGroup`](#ismemberofmditabgroup)|Determines whether the specified tabbed window is in the list of windows that are in MDI Tabbed Groups.| +|[`CMDIFrameWndEx::IsMenuBarAvailable`](#ismenubaravailable)|Determines whether the frame window has a menu bar.| +|[`CMDIFrameWndEx::IsPointNearDockSite`](#ispointneardocksite)|Determines whether a specified point is near the dock site.| +|[`CMDIFrameWndEx::IsPrintPreview`](#isprintpreview)|Determines whether the frame window is in print-preview mode.| +|[`CMDIFrameWndEx::LoadFrame`](#loadframe)|Creates a frame window from resource information. (Overrides `CMDIFrameWnd::LoadFrame`.)| +|[`CMDIFrameWndEx::LoadMDIState`](#loadmdistate)|Loads the specified layout of MDI Tabbed Groups and the list of previously opened documents.| +|[`CMDIFrameWndEx::MDITabMoveToNextGroup`](#mditabmovetonextgroup)|Moves the active tab from the currently active tabbed window to the next or previous tabbed group.| +|[`CMDIFrameWndEx::MDITabNewGroup`](#mditabnewgroup)|Creates a new tabbed group that has a single window.| +|[`CMDIFrameWndEx::NegotiateBorderSpace`](#negotiateborderspace)|Negotiates border space in a frame window during OLE in-place activation.| +|[`CMDIFrameWndEx::OnCloseDockingPane`](#onclosedockingpane)|Called by the framework when the user clicks the **Close** button on a dockable pane.| +|[`CMDIFrameWndEx::OnCloseMiniFrame`](#oncloseminiframe)|Called by the framework when the user clicks the **Close** button on a floating mini frame window.| +|[`CMDIFrameWndEx::OnClosePopupMenu`](#onclosepopupmenu)|Called by the framework when an active pop-up menu processes a `WM_DESTROY` message.| +|[`CMDIFrameWndEx::OnCmdMsg`](#oncmdmsg)|Called by the framework to route and dispatch command messages and to update command user-interface objects.| +|[`CMDIFrameWndEx::OnDrawMenuImage`](#ondrawmenuimage)|Called by the framework when the image associated with a menu item is drawn.| +|[`CMDIFrameWndEx::OnDrawMenuLogo`](#ondrawmenulogo)|Called by the framework when a [`CMFCPopupMenu`](../../mfc/reference/cmfcpopupmenu-class.md) processes a `WM_PAINT` message.| +|[`CMDIFrameWndEx::OnEraseMDIClientBackground`](#onerasemdiclientbackground)|Called by the framework when the MDI frame window processes a `WM_ERASEBKGND` message.| +|[`CMDIFrameWndEx::OnMenuButtonToolHitTest`](#onmenubuttontoolhittest)|Called by the framework when a [`CMFCToolBarButton`](../../mfc/reference/cmfctoolbarbutton-class.md) object processes a `WM_NCHITTEST` message.| +|[`CMDIFrameWndEx::OnMoveMiniFrame`](#onmoveminiframe)|Called by the framework to move a mini-frame window.| +|[`CMDIFrameWndEx::OnSetPreviewMode`](#onsetpreviewmode)|Sets the application's main frame window print-preview mode. (Overrides [`CFrameWnd::OnSetPreviewMode`](../../mfc/reference/cframewnd-class.md#onsetpreviewmode).)| +|[`CMDIFrameWndEx::OnShowCustomizePane`](#onshowcustomizepane)|Called by the framework when a Quick Customize pane is activated.| +|[`CMDIFrameWndEx::OnShowMDITabContextMenu`](#onshowmditabcontextmenu)|Called by the framework when a context menu should be displayed on one of the tabs. (Valid for MDI Tabbed Groups only.)| +|[`CMDIFrameWndEx::OnShowPanes`](#onshowpanes)|Called by the framework to show or hide panes.| +|[`CMDIFrameWndEx::OnShowPopupMenu`](#onshowpopupmenu)|Called by the framework when a pop-up menu is activated.| +|[`CMDIFrameWndEx::OnSizeMDIClient`](#onsizemdiclient)|Called by the framework when the size of the client MDI window is changing.| +|[`CMDIFrameWndEx::OnTearOffMenu`](#ontearoffmenu)|Called by the framework when a menu that has a tear-off bar is activated.| +|[`CMDIFrameWndEx::OnUpdateFrameMenu`](#onupdateframemenu)|Called by the framework to update the frame menu. (Overrides `CMDIFrameWnd::OnUpdateFrameMenu`.)| +|[`CMDIFrameWndEx::PaneFromPoint`](#panefrompoint)|Returns the docking pane that contains the specified point.| +|`CMDIFrameWndEx::PreTranslateMessage`|Used by class [`CWinApp`](../../mfc/reference/cwinapp-class.md) to translate window messages before they're dispatched to the [`TranslateMessage`](/windows/win32/api/winuser/nf-winuser-translatemessage) and [`DispatchMessage`](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides `CMDIFrameWnd::PreTranslateMessage`.)| +|[`CMDIFrameWndEx::RecalcLayout`](#recalclayout)|Called by the framework to recalculate the layout of the frame window. (Overrides [`CFrameWnd::RecalcLayout`](../../mfc/reference/cframewnd-class.md#recalclayout).)| +|[`CMDIFrameWndEx::RemovePaneFromDockManager`](#removepanefromdockmanager)|Unregisters a pane and removes it from the docking manager.| +|[`CMDIFrameWndEx::SaveMDIState`](#savemdistate)|Saves the current layout of MDI Tabbed Groups and the list of previously opened documents.| +|[`CMDIFrameWndEx::SetPrintPreviewFrame`](#setprintpreviewframe)|Sets the print preview frame window.| +|[`CMDIFrameWndEx::SetupToolbarMenu`](#setuptoolbarmenu)|Modifies a toolbar object by searching for dummy items and replacing them with the specified user-defined items.| +|[`CMDIFrameWndEx::ShowFullScreen`](#showfullscreen)|Switches the main frame from regular mode to full-screen mode.| +|[`CMDIFrameWndEx::ShowPane`](#showpane)|Shows or hides the specified pane.| +|[`CMDIFrameWndEx::ShowWindowsDialog`](#showwindowsdialog)|Creates a [`CMFCWindowsManagerDialog`](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) box and opens it.| +|[`CMDIFrameWndEx::TabbedDocumentToControlBar`](#tabbeddocumenttocontrolbar)|Converts the specified tabbed document to a docking pane.| +|[`CMDIFrameWndEx::UpdateCaption`](#updatecaption)|Called by the framework to update the window frame caption.| +|[`CMDIFrameWndEx::UpdateMDITabbedBarsIcons`](#updatemditabbedbarsicons)|Sets the icon for each MDI tabbed pane.| +|[`CMDIFrameWndEx::WinHelp`](#winhelp)|Called by the framework to initiate the WinHelp application or context help. (Overrides [`CWnd::WinHelp`](../../mfc/reference/cwnd-class.md#winhelp).)| + +### Data members |Name|Description| |----------|-----------------| -|[CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild](#m_bcancovertcontrolbartomdichild)|Determines whether docking panes can be converted to MDI child windows.| -|[CMDIFrameWndEx::m_bDisableSetRedraw](#m_bdisablesetredraw)|Enables or disables redraw optimization for MDI child windows.| +|[`CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild`](#m_bcanConvertcontrolbartomdichild)|Determines whether docking panes can be converted to MDI child windows.| +|[`CMDIFrameWndEx::m_bDisableSetRedraw`](#m_bdisablesetredraw)|Enables or disables redraw optimization for MDI child windows.| ## Remarks @@ -119,23 +118,23 @@ The following example derives a class from `CMDIFrameWndEx`. This code snippet c ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CFrameWnd](../../mfc/reference/cframewnd-class.md) +[`CFrameWnd`](../../mfc/reference/cframewnd-class.md) -[CMDIFrameWnd](../../mfc/reference/cmdiframewnd-class.md) +[`CMDIFrameWnd`](../../mfc/reference/cmdiframewnd-class.md) -[CMDIFrameWndEx](../../mfc/reference/cmdiframewndex-class.md) +[`CMDIFrameWndEx`](../../mfc/reference/cmdiframewndex-class.md) ## Requirements -**Header:** afxMDIFrameWndEx.h +**Header:** `afxMDIFrameWndEx.h` -## CMDIFrameWndEx::ActiveItemRecalcLayout +## `CMDIFrameWndEx::ActiveItemRecalcLayout` Recalculates the layout of the active item. @@ -143,11 +142,11 @@ Recalculates the layout of the active item. void ActiveItemRecalcLayout(); ``` -## CMDIFrameWndEx::AddPane +## `CMDIFrameWndEx::AddPane` Registers a pane with the docking manager. -``` +```cpp BOOL AddPane( CBasePane* pControlBar, BOOL bTail=TRUE); @@ -155,103 +154,101 @@ BOOL AddPane( ### Parameters -*pControlBar*
+*`pControlBar`*\ [in] Pointer to the pane to register. -*bTail*
+*`bTail`*\ [in] Specifies whether to add this pane to the end of the list. -### Return Value +### Return value Returns a non-zero value if the pane is registered successfully. Returns 0 if the pane is already registered with the docking manager. ### Remarks -Each pane must be registered with the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md) before it can take a part in the docking layout. Use this method to notify the docking manager that you want to dock a specific pane. Once that pane is registered, the docking manager aligns it based on its alignment setting and position in the list of panes maintained by the docking manager. +Each pane must be registered with the [`CDockingManager` class](../../mfc/reference/cdockingmanager-class.md) before it can take a part in the docking layout. Use this method to notify the docking manager that you want to dock a specific pane. Once that pane is registered, the docking manager aligns it based on its alignment setting and position in the list of panes maintained by the docking manager. -## CMDIFrameWndEx::AdjustClientArea +## `CMDIFrameWndEx::AdjustClientArea` Reduces the client area to allow for a border. -``` +```cpp virtual void AdjustClientArea(); ``` -## CMDIFrameWndEx::AdjustDockingLayout +## `CMDIFrameWndEx::AdjustDockingLayout` Recalculates the layout of all docked panes. -``` +```cpp virtual void AdjustDockingLayout(HDWP hdwp=NULL); ``` ### Parameters -*hdwp*
+*`hdwp`*\ [in] Identifies the multiple-window-position structure. You can obtain this value by calling `BeginDeferWindowPos`. ### Remarks Call this member function to recalculate the layout of all panes docked to the frame window. -## CMDIFrameWndEx::AreMDITabs +## `CMDIFrameWndEx::AreMDITabs` Determines whether the MDI tabs feature or the MDI tabbed groups feature is enabled. -``` +```cpp BOOL AreMDITabs(int* pnMDITabsType=NULL) const; ``` ### Parameters -*pnMDITabsType*
+*`pnMDITabsType`*\ [out] A pointer to an integer variable that indicates which features are enabled: - 0: All features are disabled. - - 1: MDI tabs is enabled. - - 2: MDI tabbed groups is enabled. -### Return Value +### Return value -Returns TRUE if MDI tabs or MDI tabbed groups is enabled. +Returns `TRUE` if MDI tabs or MDI tabbed groups is enabled. -Returns FALSE if none of the above features is enabled. +Returns `FALSE` if none of the above features are enabled. ### Remarks -Use this function to determine whether MDI tabs or MDI tabbed groups is enabled for the frame window. Use [CMDIFrameWndEx::EnableMDITabs](#enablemditabs) to enable or disable the MDI tabs feature. +Use this function to determine whether MDI tabs or MDI tabbed groups is enabled for the frame window. Use [`CMDIFrameWndEx::EnableMDITabs`](#enablemditabs) to enable or disable the MDI tabs feature. -Use [CMDIFrameWndEx::EnableMDITabbedGroups](#enablemditabbedgroups) to enable or disable the MDI tabbed groups feature. +Use [`CMDIFrameWndEx::EnableMDITabbedGroups`](#enablemditabbedgroups) to enable or disable the MDI tabbed groups feature. -## CMDIFrameWndEx::CanCovertControlBarToMDIChild +## `CMDIFrameWndEx::CanConvertControlBarToMDIChild` Called by the framework to determine whether the frame window can convert docking panes to tabbed documents -``` -virtual BOOL CanCovertControlBarToMDIChild(); +```cpp +virtual BOOL CanConvertControlBarToMDIChild(); ``` ### Return Value -Returns TRUE if the frame window can convert docking panes to tabbed documents; otherwise returns FALSE. +Returns `TRUE` if the frame window can convert docking panes to tabbed documents; otherwise returns `FALSE`. ### Remarks -Override this method in a derived class and return TRUE to enable the conversion of docking panes to tabbed documents. Alternatively, you can set [CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild](#m_bcancovertcontrolbartomdichild) to TRUE. +Override this method in a derived class and return `TRUE` to enable the conversion of docking panes to tabbed documents. Alternatively, you can set [`CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild`](#m_bcanConvertcontrolbartomdichild) to `TRUE`. -## CMDIFrameWndEx::ControlBarToTabbedDocument +## `CMDIFrameWndEx::ControlBarToTabbedDocument` Converts the specified docking pane to a tabbed document. -``` +```cpp virtual CMDIChildWndEx* ControlBarToTabbedDocument(CDockablePane* pBar); ``` ### Parameters -*pBar*
+*`pBar`*\ A pointer to the docking pane to convert. ### Return Value @@ -260,13 +257,13 @@ Returns a pointer to the new MDI child window that contains the docking pane. ### Remarks -This method converts a docking pane to a tabbed document. When you call this method, the framework creates a [CMDIChildWndEx Class](../../mfc/reference/cmdichildwndex-class.md) object, removes the docking pane from the docking manager, and adds the docking pane to the new MDI child window. The MDI child window resizes the docking pane to cover the entire client area +This method converts a docking pane to a tabbed document. When you call this method, the framework creates a [`CMDIChildWndEx` class](../../mfc/reference/cmdichildwndex-class.md) object, removes the docking pane from the docking manager, and adds the docking pane to the new MDI child window. The MDI child window resizes the docking pane to cover the entire client area -## CMDIFrameWndEx::CreateDocumentWindow +## `CMDIFrameWndEx::CreateDocumentWindow` Creates a child document window. -``` +```cpp virtual CMDIChildWndEx* CreateDocumentWindow( LPCTSTR lpcszDocName, CObject* pObj); @@ -274,13 +271,13 @@ virtual CMDIChildWndEx* CreateDocumentWindow( ### Parameters -*lpcszDocName*
-[in] A text string that contains a document identifier. Typically, it is the full path of a document file. +*`lpcszDocName`*\ +[in] A text string that contains a document identifier. Typically, it's the full path of a document file. -*pObj*
+*`pObj`*\ [in] A pointer to a user-defined object. For example, a developer can create an application-specific data structure describing the document and telling how the document should be initialized at startup. -### Return Value +### Return value A pointer to `CMDIChildWndEx`. @@ -288,21 +285,21 @@ A pointer to `CMDIChildWndEx`. The framework calls this method when it loads the list of documents previously saved in the registry. -Override this method in order to create documents when they are being loaded from the registry. +Override this method in order to create documents when they're being loaded from the registry. ### Example The following example shows how `CreateDocumentWindow` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). -In this example, `g_strStartViewName` could be the name of a "virtual document" (for example, "Start Page") that is not actually loaded from a disk file. Therefore we need special processing to handle that case. +In this example, `g_strStartViewName` could be the name of a "virtual document" (for example, "Start Page") that isn't loaded from a disk file. Therefore we need special processing to handle that case. [!code-cpp[NVC_MFC_VisualStudioDemo#13](../../mfc/codesnippet/cpp/cmdiframewndex-class_2.cpp)] -## CMDIFrameWndEx::CreateNewWindow +## `CMDIFrameWndEx::CreateNewWindow` Called by the framework to create a new window. -``` +```cpp virtual CMDIChildWndEx* CreateNewWindow( LPCTSTR lpcszDocName, CObject* pObj); @@ -310,17 +307,17 @@ virtual CMDIChildWndEx* CreateNewWindow( ### Parameters -*lpcszDocName*
+*`lpcszDocName`*\ [in] The document name. -*pObj*
+*`pObj`*\ [in] Reserved for future use. -### Return Value +### Return value A pointer to the new window. -## CMDIFrameWndEx::DockPane +## `CMDIFrameWndEx::DockPane` Docks the specified pane to the frame window. @@ -333,18 +330,18 @@ void DockPane( ### Parameters -*pBar*
+*`pBar`*\ [in] Pointer to the pane to dock. -*nDockBarID*
+*`nDockBarID`*\ [in] Specifies which sides of the frame window to dock to. -*lpRect*
+*`lpRect`*\ [in] Not used. ### Remarks -This method docks the specified the pane to one of the sides of the frame window that was specified when [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking) and [CMDIFrameWndEx::EnableDocking](#enabledocking) were called. +This method docks the specified pane to one of the sides of the frame window that was specified when [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking) and [`CMDIFrameWndEx::EnableDocking`](#enabledocking) were called. ### Example @@ -352,11 +349,11 @@ The following example demonstrates the use of the `DockPane` method. This code s [!code-cpp[NVC_MFC_VisualStudioDemo#4](../../mfc/codesnippet/cpp/cmdiframewndex-class_3.cpp)] -## CMDIFrameWndEx::DockPaneLeftOf +## `CMDIFrameWndEx::DockPaneLeftOf` Docks one pane to the left of another pane. -``` +```cpp BOOL DockPaneLeftOf( CPane* pBar, CPane* pLeftOf); @@ -364,19 +361,19 @@ BOOL DockPaneLeftOf( ### Parameters -*pBar*
+*`pBar`*\ [in] A pointer to the docking pane. -*pLeftOf*
-[in] A pointer to the pane that serves as the dock site. . +*`pLeftOf`*\ +[in] A pointer to the pane that serves as the dock site. -### Return Value +### Return value -Returns TRUE if the operation is successful. Otherwise returns FALSE. +Returns `TRUE` if the operation is successful. Otherwise returns `FALSE`. ### Remarks -Call this method to dock several pane objects in a predefined order. This method docks the pane specified by *pBar* to the left of the pane specified by *pLeftOf*. +Call this method to dock several pane objects in a predefined order. This method docks the pane specified by *`pBar`* to the left of the pane specified by *`pLeftOf`*. ### Example @@ -384,30 +381,27 @@ The following example shows how the `DockPaneLeftOf` method is used in the [Visu [!code-cpp[NVC_MFC_VisualStudioDemo#5](../../mfc/codesnippet/cpp/cmdiframewndex-class_4.cpp)] -## CMDIFrameWndEx::EnableAutoHidePanes +## `CMDIFrameWndEx::EnableAutoHidePanes` -Enables auto-hide mode for panes when they are docked at the specified sides of the main frame window. +Enables auto-hide mode for panes when they're docked at the specified sides of the main frame window. -``` +```cpp BOOL EnableAutoHidePanes(DWORD dwDockStyle); ``` ### Parameters -*dwDockStyle*
+*`dwDockStyle`*\ [in] Specifies the sides of the main frame window that will be enabled. Use one or more of the following flags. -- CBRS_ALIGN_LEFT +- `CBRS_ALIGN_LEFT` +- `CBRS_ALIGN_RIGHT` +- `CBRS_ALIGN_TOP` +- `CBRS_ALIGN_BOTTOM` -- CBRS_ALIGN_RIGHT +### Return value -- CBRS_ALIGN_TOP - -- CBRS_ALIGN_BOTTOM - -### Return Value - -Call this function to enable auto-hide mode for panes when they are docked at the specified sides of the main frame window. +Call this function to enable auto-hide mode for panes when they're docked at the specified sides of the main frame window. ### Example @@ -417,20 +411,20 @@ The following example shows how the `EnableAutoHidePanes` method is used in the ### Remarks -## CMDIFrameWndEx::EnableDocking +## `CMDIFrameWndEx::EnableDocking` Enables docking of the panes that belong to the MDI frame window. -``` +```cpp BOOL EnableDocking(DWORD dwDockStyle); ``` ### Parameters -*dwDockStyle*
+*`dwDockStyle`*\ [in] Specifies the docking style that you want to apply. -### Return Value +### Return value ### Remarks @@ -442,7 +436,7 @@ The following example shows how the `EnableDocking` method is used in the [Visua [!code-cpp[NVC_MFC_VisualStudioDemo#7](../../mfc/codesnippet/cpp/cmdiframewndex-class_6.cpp)] -## CMDIFrameWndEx::EnableFullScreenMainMenu +## `CMDIFrameWndEx::EnableFullScreenMainMenu` Shows or hides the main menu in full-screen mode. @@ -452,12 +446,12 @@ void EnableFullScreenMainMenu(BOOL bEnableMenu); ### Parameters -*bEnableMenu*
-[in] TRUE to show the main menu in full-screen mode, or FALSE to hide it. +*`bEnableMenu`*\ +[in] `TRUE` to show the main menu in full-screen mode, or `FALSE` to hide it. ### Remarks -## CMDIFrameWndEx::EnableFullScreenMode +## `CMDIFrameWndEx::EnableFullScreenMode` Enables full-screen mode for the frame window. @@ -467,14 +461,14 @@ void EnableFullScreenMode(UINT uiFullScreenCmd); ### Parameters -*uiFullScreenCmd*
+*`uiFullScreenCmd`*\ [in] The ID of a command that enables or disables full-screen mode. ### Remarks -In full-screen mode, all docking control bars, toolbars and menus are hidden and the active view is resized to occupy the full-screen.When you enable full-screen mode, you must specify an ID of the command that enables or disables it. You can call `EnableFullScreenMode` from the main frame's `OnCreate` function. When a frame window is being switched to full-screen mode, the framework creates a floating toolbar with one button that has the specified command ID.If you want to keep the main menu on the screen, call [CMDIFrameWndEx::EnableFullScreenMainMenu](#enablefullscreenmainmenu). +In full-screen mode, all docking control bars, toolbars and menus are hidden and the active view is resized to occupy the full-screen. When you enable full-screen mode, you must specify an ID of the command that enables or disables it. You can call `EnableFullScreenMode` from the main frame's `OnCreate` function. When a frame window is being switched to full-screen mode, the framework creates a floating toolbar with one button that has the specified command ID. If you want to keep the main menu on the screen, call [`CMDIFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu). -## CMDIFrameWndEx::EnableLoadDockState +## `CMDIFrameWndEx::EnableLoadDockState` Enables or disables the loading of the docking state. @@ -484,12 +478,12 @@ void EnableLoadDockState(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the loading of the docking state, FALSE to disable the loading of the docking state. +*`bEnable`*\ +[in] `TRUE` to enable the loading of the docking state, `FALSE` to disable the loading of the docking state. ### Remarks -## CMDIFrameWndEx::EnableMDITabbedGroups +## `CMDIFrameWndEx::EnableMDITabbedGroups` Enables or disables the MDI tabbed groups feature for the frame window. @@ -501,29 +495,26 @@ void EnableMDITabbedGroups( ### Parameters -*bEnable*
-[in] If TRUE, the MDI tabbed groups feature is enabled; if FALSE, the MDI tabbed groups feature is disabled. +*`bEnable`*\ +[in] If `TRUE`, the MDI tabbed groups feature is enabled; if `FALSE`, the MDI tabbed groups feature is disabled. -*params*
+*`params`*\ [in] Specifies parameters that the framework applies to child windows that are created in the MDI client area. ### Remarks Use this method to enable or disable the MDI tabbed groups feature. This feature enables MDI applications to display child windows as tabbed windows that are aligned vertically or horizontally within the MDI client area. Groups of tabbed windows are separated by splitters. The user can resize tabbed groups by using a splitter. -- The user can: +The user can: - Drag individual tabs between groups. - - Drag individual tabs to the edge of the window to create new groups. - - Move tabs or create new groups by using a shortcut menu. - - Your application can save the current layout of tabbed windows and the list of currently opened documents. -If you call this method with *bEnable* set to FALSE, *params* is ignored. +If you call this method with *`bEnable`* set to `FALSE`, *`params`* is ignored. -Even if MDI tabbed groups is already enabled, you can call this method again to modify the settings for child windows. Call the method with *bEnable* set to TRUE and modify the members of the `CMDITabInfo` object that are specified by the *params* parameter. +Even if MDI tabbed groups is already enabled, you can call this method again to modify the settings for child windows. Call the method with *`bEnable`* set to `TRUE` and modify the members of the `CMDITabInfo` object that are specified by the *`params`* parameter. For more information about how to use MDI tabbed groups, see [MDI Tabbed Groups](../../mfc/mdi-tabbed-groups.md). @@ -533,7 +524,7 @@ The following example shows how `EnableMDITabbedGroups` is used in the [VisualSt [!code-cpp[NVC_MFC_VisualStudioDemo#8](../../mfc/codesnippet/cpp/cmdiframewndex-class_7.cpp)] -## CMDIFrameWndEx::EnableMDITabs +## `CMDIFrameWndEx::EnableMDITabs` Enables or disables the MDI Tabs feature for the MDI frame window. When enabled, the frame window displays a tab for each MDI child window. @@ -550,34 +541,34 @@ void EnableMDITabs( ### Parameters -*bEnable*
+*`bEnable`*\ Specifies whether tabs are enabled. -*bIcons*
+*`bIcons`*\ Specifies whether icons should be displayed on the tabs. -*tabLocation*
+*`tabLocation`*\ Specifies the location of the tab labels. -*bTabCloseButton*
+*`bTabCloseButton`*\ Specifies whether to display tab close buttons. -*style*
-Specifies the style of tabs. Use STYLE_3D_SCROLLED for regular tabs or STYLE_3D_ONENOTE for Microsoft OneNote tabs. +*`style`*\ +Specifies the style of tabs. Use `STYLE_3D_SCROLLED` for regular tabs or `STYLE_3D_ONENOTE` for Microsoft OneNote tabs. -*bTabCustomTooltips*
+*`bTabCustomTooltips`*\ Specifies whether custom tooltips are enabled. -*bActiveTabCloseButton*
-If TRUE, a **Close** button will be displayed on the active tab instead of on the right corner of the tab area. +*`bActiveTabCloseButton`*\ +If `TRUE`, a **Close** button will be displayed on the active tab instead of on the right corner of the tab area. ### Remarks Call this method to enable or disable the MDI tabs feature for the MDI frame window. When enabled, all child windows are displayed as tabs. -The tab labels can be located at the top or bottom of the frame, depending on the setting of the parameter *tabLocation*. You may specify either `CMFCTabCtrl::LOCATION_BOTTOM` (the default setting) or `CMFCTabCtrl::LOCATION_TOP`. +The tab labels can be located at the top or bottom of the frame, depending on the setting of the parameter *`tabLocation`*. You may specify either `CMFCTabCtrl::LOCATION_BOTTOM` (the default setting) or `CMFCTabCtrl::LOCATION_TOP`. -If *bTabCustomTooltips* is TRUE, an AFX_WM_ON_GET_TAB_TOOLTIP message will be sent to the main frame window. Your code can handle this message and provide the framework with custom tooltips for MDI tabs. +If *`bTabCustomTooltips`* is `TRUE`, an `AFX_WM_ON_GET_TAB_TOOLTIP` message will be sent to the main frame window. Your code can handle this message and provide the framework with custom tooltips for MDI tabs. ### Example @@ -585,7 +576,7 @@ The following example shows how `EnableMDITabs` is used in the [MDITabsDemo Samp [!code-cpp[NVC_MFC_MDITabsDemo#3](../../mfc/reference/codesnippet/cpp/cmdiframewndex-class_8.cpp)] -## CMDIFrameWndEx::EnableMDITabsLastActiveActivation +## `CMDIFrameWndEx::EnableMDITabsLastActiveActivation` Specifies whether the last active tab should be opened when the user closes the current tab. @@ -595,22 +586,21 @@ void EnableMDITabsLastActiveActivation(BOOL bLastActiveTab=TRUE); ### Parameters -*bLastActiveTab*
-[in] If TRUE, enable activation of the last active tab. If FALSE, disable activation of the last active tab. +*`bLastActiveTab`*\ +[in] If `TRUE`, enable activation of the last active tab. If `FALSE`, disable activation of the last active tab. ### Remarks There are two ways to open a tab when the active tab is closed: - Activate the next tab. - - Activate the previously active tab. The default implementation uses the first way. Use `EnableMDITabsLastActiveActivation` to enable the second way of tab activation. It emulates the way Windows opens MDI child windows. -## CMDIFrameWndEx::EnablePaneMenu +## `CMDIFrameWndEx::EnablePaneMenu` Enables or disables automatic creation and management of the pop-up pane menu, which displays a list of application panes. @@ -626,23 +616,23 @@ void EnablePaneMenu( ### Parameters -*bEnable*
-[in] If TRUE, automatic handling of the pane menu is enabled; if FALSE, automatic handling is disabled. +*`bEnable`*\ +[in] If `TRUE`, automatic handling of the pane menu is enabled; if `FALSE`, automatic handling is disabled. -*uiCustomizeCmd*
+*`uiCustomizeCmd`*\ [in] Command ID of the **Customize** menu item. This menu item is usually added to the end of the list of panes. -*strCustomizeLabel*
+*`strCustomizeLabel`*\ [in] The text to be displayed for the **Customize** menu item (for localization). -*uiViewToolbarsMenuEntryID*
+*`uiViewToolbarsMenuEntryID`*\ [in] Specifies the ID of a toolbar menu item that opens the pane menu. Usually this is the **Toolbars** submenu of the **View** menu. -*bContextMenuShowsToolbarsOnly*
-[in] If TRUE, the pane menu displays only a list of toolbars. If FALSE, the menu displays a list of toolbars and docking bars. +*`bContextMenuShowsToolbarsOnly`*\ +[in] If `TRUE`, the pane menu displays only a list of toolbars. If `FALSE`, the menu displays a list of toolbars and docking bars. -*bViewMenuShowsToolbarsOnly*
-[in] If TRUE, the pane menu displays only a list of toolbars. If FALSE, the menu displays a list of toolbars and docking bars. +*`bViewMenuShowsToolbarsOnly`*\ +[in] If `TRUE`, the pane menu displays only a list of toolbars. If `FALSE`, the menu displays a list of toolbars and docking bars. ### Remarks @@ -654,9 +644,9 @@ The following example shows how `EnablePaneMenu` is used in the [VisualStudioDem [!code-cpp[NVC_MFC_VisualStudioDemo#9](../../mfc/codesnippet/cpp/cmdiframewndex-class_9.cpp)] -## CMDIFrameWndEx::EnableWindowsDialog +## `CMDIFrameWndEx::EnableWindowsDialog` -Inserts a menu item whose command ID calls a [CMFCWindowsManagerDialog](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) dialog box. +Inserts a menu item whose command ID calls a [`CMFCWindowsManagerDialog`](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) dialog box. ```cpp void EnableWindowsDialog( @@ -674,21 +664,21 @@ void EnableWindowsDialog( ### Parameters -*uiMenuId*
+*`uiMenuId`*\ [in] Specifies the resource ID of a menu. -*lpszMenuText*
+*`lpszMenuText`*\ [in] Specifies the item's text. -*bShowHelpButton*
+*`bShowHelpButton`*\ [in] Specifies whether to display a **Help** button on the windows management dialog box. -*uiMenuTextResId*
+*`uiMenuTextResId`*\ [in] The string resource identifier that contains the item's text string. ### Remarks -Use this method to insert a menu item whose command calls a MDI child window management dialog box ( [CMFCWindowsManagerDialog Class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)). The new item is inserted into the menu specified by *uiMenuId*. Call `EnableWindowsDialog` when you process the WM_CREATE message. +Use this method to insert a menu item whose command calls an MDI child window management dialog box ( [`CMFCWindowsManagerDialog` class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)). The new item is inserted into the menu specified by *`uiMenuId`*. Call `EnableWindowsDialog` when you process the `WM_CREATE` message. ### Example @@ -696,162 +686,159 @@ The following example shows how `EnableWindowsDialog` is used in the [VisualStud [!code-cpp[NVC_MFC_VisualStudioDemo#10](../../mfc/codesnippet/cpp/cmdiframewndex-class_10.cpp)] -## CMDIFrameWndEx::GetActivePopup +## `CMDIFrameWndEx::GetActivePopup` Returns a pointer to the currently displayed popup menu. -``` +```cpp CMFCPopupMenu* GetActivePopup() const; ``` -### Return Value +### Return value -A pointer to the active popup menu; NULL if no popup menu is active. +A pointer to the active popup menu; `NULL` if no popup menu is active. ### Remarks -Use this function to obtain a pointer to the [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) object that is currently displayed. +Use this function to obtain a pointer to the [`CMFCPopupMenu` class](../../mfc/reference/cmfcpopupmenu-class.md) object that is currently displayed. -## CMDIFrameWndEx::GetDefaultResId +## `CMDIFrameWndEx::GetDefaultResId` Returns the ID of shared resources of the MDI frame window. -``` +```cpp UINT GetDefaultResId() const; ``` -### Return Value +### Return value A resource ID value. 0 if the frame window has no menu bar. ### Remarks -This method returns the resource ID that was specified when the MDI frame window was loaded by [CFrameWnd::LoadFrame](../../mfc/reference/cframewnd-class.md#loadframe). +This method returns the resource ID that was specified when the MDI frame window was loaded by [`CFrameWnd::LoadFrame`](../../mfc/reference/cframewnd-class.md#loadframe). -## CMDIFrameWndEx::GetMDITabGroups +## `CMDIFrameWndEx::GetMDITabGroups` Returns a list of MDI tabbed windows. -``` +```cpp const CObList& GetMDITabGroups() const; ``` -### Return Value +### Return value -A reference to a [CObList Class](../../mfc/reference/coblist-class.md) object that contains a list of tabbed windows. Do not store or modify the list. +A reference to a [`CObList` class](../../mfc/reference/coblist-class.md) object that contains a list of tabbed windows. Don't store or modify the list. ### Remarks Use this method to access the list of tabbed windows. It can be helpful if you want to change or query some parameters of individual tabbed windows. -## CMDIFrameWndEx::GetMDITabs +## `CMDIFrameWndEx::GetMDITabs` Returns a reference to the underlined tabbed window. -``` +```cpp CMFCTabCtrl& GetMDITabs(); ``` -### Return Value +### Return value A reference to the underlined tabbed window. -## CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems +## `CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems` Returns a combination of flags that determines what operations are valid when the MDI Tabbed Groups feature is enabled. -``` +```cpp DWORD GetMDITabsContextMenuAllowedItems(); ``` -### Return Value - -A bitwise-OR combination of the following flags: - -- AFX_MDI_CREATE_VERT_GROUP - can create a vertical tab group. +### Return value -- AFX_MDI_CREATE_HORZ_GROUP - can create a horizontal tab group. +A bitwise "or" (`|`) combination of the following flags: -- AFX_MDI_CAN_MOVE_PREV - can move a tab to the previous tab group. - -- AFX_MDI_CAN_MOVE_NEXT - can move a tab to the next tab group. +- `AFX_MDI_CREATE_VERT_GROUP` - can create a vertical tab group. +- `AFX_MDI_CREATE_HORZ_GROUP` - can create a horizontal tab group. +- `AFX_MDI_CAN_MOVE_PREV` - can move a tab to the previous tab group. +- `AFX_MDI_CAN_MOVE_NEXT` - can move a tab to the next tab group. ### Remarks When the MDI Tabbed Groups feature is enabled, you must know what operations are allowed on the tabs of a particular window. This method analyzes the current layout of tabbed windows and returns a combination of flags that can be used to build, for example, a shortcut menu. -You can create a new vertical tab group when all tabbed windows are aligned vertically, or when there is only one tabbed window. +You can create a new vertical tab group when all tabbed windows are aligned vertically, or when there's only one tabbed window. -You can create a new horizontal tab group when all tabbed windows are aligned horizontally, or when there is only one tabbed window. +You can create a new horizontal tab group when all tabbed windows are aligned horizontally, or when there's only one tabbed window. -You can move a tab to the previous group only if there is more than one tab in a tabbed window. +You can move a tab to the previous group only if there's more than one tab in a tabbed window. -You can move a tab to the next group only if there is more than one tab in a tabbed window. +You can move a tab to the next group only if there's more than one tab in a tabbed window. -## CMDIFrameWndEx::GetMenuBar +## `CMDIFrameWndEx::GetMenuBar` Returns a pointer to a menu bar object attached to the frame window. -``` +```cpp const CMFCMenuBar* GetMenuBar() const; ``` -### Return Value +### Return value A pointer to a menu bar object. -## CMDIFrameWndEx::GetPane +## `CMDIFrameWndEx::GetPane` Returns a pointer to the pane that has the specified control ID. -``` +```cpp CBasePane* GetPane(UINT nID); ``` ### Parameters -*nID*
+*`nID`*\ [in] The control ID. -### Return Value +### Return value -A pointer to the pane that has the specified control ID, if it exists. Otherwise, NULL. +A pointer to the pane that has the specified control ID, if it exists. Otherwise, `NULL`. -## CMDIFrameWndEx::GetRibbonBar +## `CMDIFrameWndEx::GetRibbonBar` Retrieves the ribbon bar control for the frame. -``` +```cpp CMFCRibbonBar* GetRibbonBar(); ``` -### Return Value +### Return value -Pointer to the [CMFCRibbonBar Class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. +Pointer to the [`CMFCRibbonBar` class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. ### Remarks -## CMDIFrameWndEx::GetTearOffBars +## `CMDIFrameWndEx::GetTearOffBars` Returns a list of tear-off menus. -``` +```cpp const CObList& GetTearOffBars() const; ``` -### Return Value +### Return value -A reference to a [CObList Class](../../mfc/reference/coblist-class.md) object that contains a collection of pointers to `CPane`-derived objects that are in a tear-off state. +A reference to a [`CObList` class](../../mfc/reference/coblist-class.md) object that contains a collection of pointers to `CPane`-derived objects that are in a tear-off state. ### Remarks `CMDIFrameWndEx` maintains a collection of tear-off menus. Use this method to retrieve a reference to this list. -## CMDIFrameWndEx::GetToolbarButtonToolTipText +## `CMDIFrameWndEx::GetToolbarButtonToolTipText` Called by the framework when the application displays the tooltip for a toolbar button. -``` +```cpp virtual BOOL GetToolbarButtonToolTipText( CMFCToolBarButton* pButton, CString& strTTText); @@ -859,23 +846,23 @@ virtual BOOL GetToolbarButtonToolTipText( ### Parameters -*pButton*
+*`pButton`*\ [in] A pointer to a toolbar button. -*strTTText*
+*`strTTText`*\ [in] The tooltip text to display for the button. -### Return Value +### Return value -TRUE if the tooltip has been displayed. FALSE otherwise. +`TRUE` if the tooltip has been displayed. `FALSE` otherwise. ### Remarks -## CMDIFrameWndEx::InsertPane +## `CMDIFrameWndEx::InsertPane` Registers the specified pane with the docking manager. -``` +```cpp BOOL InsertPane( CBasePane* pControlBar, CBasePane* pTarget, @@ -884,89 +871,89 @@ BOOL InsertPane( ### Parameters -*pControlBar*
+*`pControlBar`*\ [in] A pointer to the pane to be inserted. -*pTarget*
+*`pTarget`*\ [in] A pointer to the pane before or after which to insert the pane. -*bAfter*
-[in] If TRUE, *pControlBar* is inserted after *pTarget*. If FALSE, *pControlBar* is inserted before *pTarget*. +*`bAfter`*\ +[in] If `TRUE`, *`pControlBar`* is inserted after *`pTarget`*. If `FALSE`, *`pControlBar`* is inserted before *`pTarget`*. -### Return Value +### Return value -TRUE if the method successfully registers the pane, FALSE if the pane was already registered with the docking manager. +`TRUE` if the method successfully registers the pane, `FALSE` if the pane was already registered with the docking manager. ### Remarks -Use this method to tell the docking manager about a pane specified by *pControlBar*. The docking manager will align this pane according to the pane's alignment and position in the docking manager's internal list. +Use this method to tell the docking manager about a pane specified by *`pControlBar`*. The docking manager will align this pane according to the pane's alignment and position in the docking manager's internal list. -## CMDIFrameWndEx::IsFullScreen +## `CMDIFrameWndEx::IsFullScreen` Determines whether the frame window is in full-screen mode. -``` +```cpp BOOL IsFullScreen() const; ``` -### Return Value +### Return value -TRUE if the frame window is in full screen mode; otherwise FALSE. +`TRUE` if the frame window is in full screen mode; otherwise `FALSE`. ### Remarks -You can set the full screen mode by calling the [CMDIFrameWndEx::EnableFullScreenMode](#enablefullscreenmode) method. +You can set the full screen mode by calling the [`CMDIFrameWndEx::EnableFullScreenMode`](#enablefullscreenmode) method. -## CMDIFrameWndEx::IsMDITabbedGroup +## `CMDIFrameWndEx::IsMDITabbedGroup` Specifies whether the MDI Tabbed Groups feature is enabled. -``` +```cpp BOOL IsMDITabbedGroup() const; ``` -### Return Value +### Return value -TRUE if the MDI Tabbed Groups feature is enabled; otherwise FALSE. +`TRUE` if the MDI Tabbed Groups feature is enabled; otherwise `FALSE`. ### Remarks -To determine whether regular MDI tabs or the MDI Tabbed Groups feature is enabled, use [CMDIFrameWndEx::AreMDITabs](#aremditabs). +To determine whether regular MDI tabs or the MDI Tabbed Groups feature is enabled, use [`CMDIFrameWndEx::AreMDITabs`](#aremditabs). -## CMDIFrameWndEx::IsMemberOfMDITabGroup +## `CMDIFrameWndEx::IsMemberOfMDITabGroup` Determines whether the specified tabbed window is in the list of windows that are in MDI Tabbed Groups. -``` +```cpp BOOL IsMemberOfMDITabGroup(CWnd* pWnd); ``` ### Parameters -*pWnd*
+*`pWnd`*\ [in] A pointer to tabbed window. -### Return Value +### Return value -TRUE if the specified tabbed window is in the list of tabbed windows that form MDI Tabbed Groups. Otherwise FALSE. +`TRUE` if the specified tabbed window is in the list of tabbed windows that form MDI Tabbed Groups. Otherwise `FALSE`. -## CMDIFrameWndEx::IsMenuBarAvailable +## `CMDIFrameWndEx::IsMenuBarAvailable` Determines whether the frame window has a menu bar. -``` +```cpp BOOL IsMenuBarAvailable() const; ``` -### Return Value +### Return value -TRUE if the pointer to the menu bar object is not NULL; otherwise FALSE. +`TRUE` if the pointer to the menu bar object isn't `NULL`; otherwise `FALSE`. -## CMDIFrameWndEx::IsPointNearDockSite +## `CMDIFrameWndEx::IsPointNearDockSite` Determines whether a specified point is near the dock site. -``` +```cpp BOOL IsPointNearDockSite( CPoint point, DWORD& dwBarAlignment, @@ -975,42 +962,42 @@ BOOL IsPointNearDockSite( ### Parameters -*point*
+*`point`*\ [in] The specified point in screen coordinates. -*dwBarAlignment*
-[in] Specifies which edge the point is near. Possible values are CBRS_ALIGN_LEFT, CBRS_ALIGN_RIGHT, CBRS_ALIGN_TOP, and CBRS_ALIGN_BOTTOM +*`dwBarAlignment`*\ +[in] Specifies which edge the point is near. Possible values are `CBRS_ALIGN_LEFT`, `CBRS_ALIGN_RIGHT`, `CBRS_ALIGN_TOP`, and `CBRS_ALIGN_BOTTOM` -*bOuterEdge*
-[in] TRUE if the point is near the outer border of the dock site; FALSE otherwise. +*`bOuterEdge`*\ +[in] `TRUE` if the point is near the outer border of the dock site; `FALSE` otherwise. -### Return Value +### Return value -TRUE if the point is near the dock site; otherwise FALSE. +`TRUE` if the point is near the dock site; otherwise `FALSE`. ### Remarks The point is near the dock site when it is within the sensitivity set in the docking manager. The default sensitivity is 15 pixels. -## CMDIFrameWndEx::IsPrintPreview +## `CMDIFrameWndEx::IsPrintPreview` Determines whether the frame window is in print-preview mode. -``` +```cpp BOOL IsPrintPreview(); ``` -### Return Value +### Return value -TRUE if the frame window is in print-preview mode; otherwise, FALSE. +`TRUE` if the frame window is in print-preview mode; otherwise, `FALSE`. ### Remarks -## CMDIFrameWndEx::LoadFrame +## `CMDIFrameWndEx::LoadFrame` Creates a frame window from resource information. -``` +```cpp virtual BOOL LoadFrame( UINT nIDResource, DWORD dwDefaultStyle = WS_OVERLAPPEDWINDOW | FWS_ADDTOTITLE, @@ -1020,50 +1007,47 @@ virtual BOOL LoadFrame( ### Parameters -*nIDResource*
+*`nIDResource`*\ [in] The ID of a shared resource associated with the frame window. -*dwDefaultStyle*
+*`dwDefaultStyle`*\ [in] The style of the frame window. -*pParentWnd*
+*`pParentWnd`*\ [in] A pointer to the frame's parent. -*pContext*
-[in] A pointer to a [CCreateContext Structure](../../mfc/reference/ccreatecontext-structure.md). This parameter can be NULL. +*`pContext`*\ +[in] A pointer to a [`CCreateContext` Structure](../../mfc/reference/ccreatecontext-structure.md). This parameter can be `NULL`. -### Return Value +### Return value -TRUE if the method succeeds, otherwise FALSE. +`TRUE` if the method succeeds, otherwise `FALSE`. -## CMDIFrameWndEx::LoadMDIState +## `CMDIFrameWndEx::LoadMDIState` Loads the specified layout of MDI Tabbed Groups and the list of previously opened documents. -``` +```cpp virtual BOOL LoadMDIState(LPCTSTR lpszProfileName); ``` ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the profile name. -### Return Value +### Return value -TRUE if the load succeeded; FALSE if the load failed or there is no data to load. +`TRUE` if the load succeeded; `FALSE` if the load failed or there's no data to load. ### Remarks To load or save the state of MDI tabs and groups and the list of opened documents, do the following: -- Call [CMDIFrameWndEx::SaveMDIState](#savemdistate) when the main frame is being closed - -- Call [CMDIFrameWndEx::LoadMDIState](#loadmdistate) when the main frame is being created. The recommended place for this call is before the main frame is displayed for the first time. Add `CWinAppEx::EnableLoadWindowPlacement` `(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);.` Add `CWinAppEx::ReloadWindowPlacement` `(pMainFrame);` after the call to `LoadMDIState` to display the main frame at the position that was stored in the registry. - -- Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that are not stored as files. The returned string will be saved in the registry as the document identifier. The base implementation of [CMDIChildWndEx::GetDocumentName](../../mfc/reference/cmdichildwndex-class.md#getdocumentname) returns a value obtained from [CDocument::GetPathName](../../mfc/reference/cdocument-class.md#getpathname). - -- Override [CMDIFrameWndEx::CreateDocumentWindow](#createdocumentwindow) to correctly create documents when they are being loaded from the registry. The first parameter is the string that `GetDocumentName` returned. +- Call [`CMDIFrameWndEx::SaveMDIState`](#savemdistate) when the main frame is being closed +- Call [`CMDIFrameWndEx::LoadMDIState`](#loadmdistate) when the main frame is being created. The recommended place for this call is before the main frame is displayed for the first time. Add `CWinAppEx::EnableLoadWindowPlacement` `(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);.` Add `CWinAppEx::ReloadWindowPlacement` `(pMainFrame);` after the call to `LoadMDIState` to display the main frame at the position that was stored in the registry. +- Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that aren't stored as files. The returned string will be saved in the registry as the document identifier. The base implementation of [`CMDIChildWndEx::GetDocumentName`](../../mfc/reference/cmdichildwndex-class.md#getdocumentname) returns a value obtained from [`CDocument::GetPathName`](../../mfc/reference/cdocument-class.md#getpathname). +- Override [`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow) to correctly create documents when they're being loaded from the registry. The first parameter is the string that `GetDocumentName` returned. ### Example @@ -1071,7 +1055,7 @@ The following example shows how `LoadMDIState` is used in the [VisualStudioDemo [!code-cpp[NVC_MFC_VisualStudioDemo#11](../../mfc/codesnippet/cpp/cmdiframewndex-class_11.cpp)] -## CMDIFrameWndEx::MDITabMoveToNextGroup +## `CMDIFrameWndEx::MDITabMoveToNextGroup` Moves the active tab from the currently active tabbed window to the next or previous tabbed group. @@ -1081,10 +1065,10 @@ void MDITabMoveToNextGroup(BOOL bNext=TRUE); ### Parameters -*bNext*
-[in] If TRUE, move the tab to the next tabbed group. If FALSE, move it to the previous tabbed group. +*`bNext`*\ +[in] If `TRUE`, move the tab to the next tabbed group. If `FALSE`, move it to the previous tabbed group. -## CMDIFrameWndEx::MDITabNewGroup +## `CMDIFrameWndEx::MDITabNewGroup` Creates a new tabbed group that has a single window. @@ -1094,8 +1078,8 @@ void MDITabNewGroup(BOOL bVert=TRUE); ### Parameters -*bVert*
-[in] Specifies the new group alignment. If TRUE, the new group is aligned vertically. If FALSE, the new group is aligned horizontally. +*`bVert`*\ +[in] Specifies the new group alignment. If `TRUE`, the new group is aligned vertically. If `FALSE`, the new group is aligned horizontally. ### Remarks @@ -1107,47 +1091,47 @@ The following example shows how `MDITabNewGroup` is used in the [VisualStudioDem [!code-cpp[NVC_MFC_VisualStudioDemo#12](../../mfc/codesnippet/cpp/cmdiframewndex-class_12.cpp)] -## CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild +## `CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild` Specifies whether docking panes can be converted to MDI child windows. -``` -BOOL m_bCanCovertControlBarToMDIChild; +```cpp +BOOL m_bCanConvertControlBarToMDIChild; ``` ### Remarks -Indicates whether docking control bars can be converted to MDI child windows. If this flag is TRUE, the framework handles the conversion automatically when the user selects the **Tabbed Document** command. The flag is protected and you must explicitly enable this option either by setting `m_bCanCovertControlBarToMDIChild` in a constructor of a `CMDIFrameWndEx`-derived class, or by overriding `CanConvertControlBarToMDIChild`. +Indicates whether docking control bars can be converted to MDI child windows. If this flag is `TRUE`, the framework handles the conversion automatically when the user selects the **Tabbed Document** command. The flag is protected and you must explicitly enable this option either by setting `m_bCanConvertControlBarToMDIChild` in a constructor of a `CMDIFrameWndEx`-derived class, or by overriding `CanConvertControlBarToMDIChild`. The default value is `FALSE`. ### Example -The following example shows how `m_bCanCovertControlBarToMDIChild` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). +The following example shows how `m_bCanConvertControlBarToMDIChild` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). [!code-cpp[NVC_MFC_VisualStudioDemo#13](../../mfc/codesnippet/cpp/cmdiframewndex-class_2.cpp)] -## CMDIFrameWndEx::m_bDisableSetRedraw +## `CMDIFrameWndEx::m_bDisableSetRedraw` Enables or disables redraw optimization for MDI child windows. -``` +```cpp AFX_IMPORT_DATA static BOOL m_bDisableSetRedraw; ``` ### Remarks -The default value is TRUE. +The default value is `TRUE`. -Set this flag to FALSE if you want to optimize redrawing of MDI children. In this case the framework will call `SetRedraw (FALSE)` for the main frame when the application is changing the active tab. +Set this flag to `FALSE` if you want to optimize redrawing of MDI children. In this case, the framework will call `SetRedraw (FALSE)` for the main frame when the application is changing the active tab. This flag can cause unwanted effects (such as background applications that become visible). Therefore we recommend that you change the default only if you experience noticeable flickering during MDI tab activation. -## CMDIFrameWndEx::NegotiateBorderSpace +## `CMDIFrameWndEx::NegotiateBorderSpace` Negotiates border space in a frame window during OLE in-place activation. -``` +```cpp virtual BOOL NegotiateBorderSpace( UINT nBorderCmd, LPRECT lpRectBorder); @@ -1155,19 +1139,17 @@ virtual BOOL NegotiateBorderSpace( ### Parameters -*nBorderCmd*
+*`nBorderCmd`*\ [in] Contains one of the following values from the enum `CFrameWnd::BorderCmd`: - `borderGet` = 1 - - `borderRequest` = 2 - - `borderSet` = 3 -*lpRectBorder*
-[in, out] Pointer to a [RECT Structure](/windows/win32/api/windef/ns-windef-rect) or a [CRect Class](../../atl-mfc-shared/reference/crect-class.md) object that specifies the coordinates of the border. +*`lpRectBorder`*\ +[in, out] Pointer to a [`RECT` structure](/windows/win32/api/windef/ns-windef-rect) or a [`CRect` class](../../atl-mfc-shared/reference/crect-class.md) object that specifies the coordinates of the border. -### Return Value +### Return value Nonzero if the method was successful; otherwise 0. @@ -1175,74 +1157,74 @@ Nonzero if the method was successful; otherwise 0. This method is an implementation of OLE border space negotiation. -## CMDIFrameWndEx::OnCloseDockingPane +## `CMDIFrameWndEx::OnCloseDockingPane` Called by the framework when the user clicks the **Close** button on a dockable pane. -``` +```cpp virtual BOOL OnCloseDockingPane(CDockablePane* pWnd); ``` ### Parameters -*pWnd*
+*`pWnd`*\ [in] Pointer to the pane being closed. -### Return Value +### Return value -TRUE if the docking pane can be closed. Otherwise, FALSE. +`TRUE` if the docking pane can be closed. Otherwise, `FALSE`. ### Remarks -Override this method to handle hiding of docking panes. Return FALSE if you want to prevent a docking pane from being hidden. +Override this method to handle hiding of docking panes. Return `FALSE` if you want to prevent a docking pane from being hidden. -The default implementation does nothing and returns TRUE. +The default implementation does nothing and returns `TRUE`. -## CMDIFrameWndEx::OnCloseMiniFrame +## `CMDIFrameWndEx::OnCloseMiniFrame` Called by the framework when the user clicks the **Close** button on a floating mini-frame window. -``` +```cpp virtual BOOL OnCloseMiniFrame(CPaneFrameWnd*); ``` ### Parameters -*pWnd*
+*`pWnd`*\ [in] Pointer to the mini-frame window being closed. -### Return Value +### Return value -TRUE if the floating mini-frame window can be closed. Otherwise, FALSE. +`TRUE` if the floating mini-frame window can be closed. Otherwise, `FALSE`. ### Remarks -Override this method to handle hiding of floating mini-frame windows. Return FALSE if you want to prevent a floating mini-frame window from being hidden. +Override this method to handle hiding of floating mini-frame windows. Return `FALSE` if you want to prevent a floating mini-frame window from being hidden. -The default implementation does nothing and returns TRUE. +The default implementation does nothing and returns `TRUE`. -## CMDIFrameWndEx::OnClosePopupMenu +## `CMDIFrameWndEx::OnClosePopupMenu` -Called by the framework when an active pop-up menu processes a WM_DESTROY message. +Called by the framework when an active pop-up menu processes a `WM_DESTROY` message. -``` +```cpp virtual void OnClosePopupMenu(CMFCPopupMenu* pMenuPopup); ``` ### Parameters -*pMenuPopup*
+*`pMenuPopup`*\ [in] Pointer to a pop-up menu. ### Remarks -Override this method if you want to process notifications from [CMFCPopupMenu Class](../../mfc/reference/cmfcpopupmenu-class.md) objects that belong to the MDI frame window when those objects process WM_DESTROY messages. +Override this method if you want to process notifications from [`CMFCPopupMenu` class](../../mfc/reference/cmfcpopupmenu-class.md) objects that belong to the MDI frame window when those objects process `WM_DESTROY` messages. -## CMDIFrameWndEx::OnCmdMsg +## `CMDIFrameWndEx::OnCmdMsg` Called by the framework to route and dispatch command messages and to update command user-interface objects. -``` +```cpp virtual BOOL OnCmdMsg( UINT nID, int nCode, @@ -1252,27 +1234,27 @@ virtual BOOL OnCmdMsg( ### Parameters -*nID*
+*`nID`*\ [in] The command ID. -*nCode*
-[in] Identifies the command notification code. See [CCmdTarget::OnCmdMsg](../../mfc/reference/ccmdtarget-class.md#oncmdmsg) for more information about values for *nCode*. +*`nCode`*\ +[in] Identifies the command notification code. For more information about values for *`nCode`*, see [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg). -*pExtra*
-[in] Used according to the value of *nCode*. See [CCmdTarget::OnCmdMsg](../../mfc/reference/ccmdtarget-class.md#oncmdmsg) for more information about *pExtra*. +*`pExtra`*\ +[in] Used according to the value of *`nCode`*. For more information about *`pExtra`*, see [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg). -*pHandlerInfo*
-[in, out] Typically, this parameter should be NULL.If not NULL, `OnCmdMsg` fills in the `pTarget` and `pmf` members of the *pHandlerInfo* structure instead of dispatching the command. +*`pHandlerInfo`*\ +[in, out] Typically, this parameter should be `NULL`. If not `NULL`, `OnCmdMsg` fills in the `pTarget` and `pmf` members of the *`pHandlerInfo`* structure instead of dispatching the command. -### Return Value +### Return value Nonzero if the message is handled; otherwise 0. -## CMDIFrameWndEx::OnDrawMenuImage +## `CMDIFrameWndEx::OnDrawMenuImage` Called by the framework when the image associated with a menu item is drawn. -``` +```cpp virtual BOOL OnDrawMenuImage( CDC* pDC, const CMFCToolBarMenuButton* pMenuButton, @@ -1281,28 +1263,28 @@ virtual BOOL OnDrawMenuImage( ### Parameters -*pDC*
+*`pDC`*\ [in] Pointer to a device context. -*pMenuButton*
+*`pMenuButton`*\ [in] Pointer to the menu button. -*rectImage*
+*`rectImage`*\ [in] Bounding rectangle of the image. -### Return Value +### Return value -TRUE if the method draws the image. The default implementation returns FALSE. +`TRUE` if the method draws the image. The default implementation returns `FALSE`. ### Remarks Override this method if you want to customize image rendering for the menu items that belong to the menu bar owned by the `CMDIFrameWndEx`-derived object. The default implementation does nothing. -## CMDIFrameWndEx::OnDrawMenuLogo +## `CMDIFrameWndEx::OnDrawMenuLogo` -Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md)processes a WM_PAINT message. +Called by the framework when a [`CMFCPopupMenu`](../../mfc/reference/cmfcpopupmenu-class.md) processes a `WM_PAINT` message. -``` +```cpp virtual void OnDrawMenuLogo( CDC*, CMFCPopupMenu*, @@ -1313,27 +1295,27 @@ virtual void OnDrawMenuLogo( Override this function to display a logo on the pop-up menu that belongs to the menu bar owned by the `CMDIFrameWndEx`-derived object. The default implementation does nothing. -## CMDIFrameWndEx::OnEraseMDIClientBackground +## `CMDIFrameWndEx::OnEraseMDIClientBackground` -Called by the framework when the MDI frame window processes a WM_ERASEBKGND message. +Called by the framework when the MDI frame window processes a `WM_ERASEBKGND` message. -``` +```cpp virtual BOOL OnEraseMDIClientBackground(CDC*); ``` -### Return Value +### Return value -TRUE if the application processes the message and erases the background. +`TRUE` if the application processes the message and erases the background. ### Remarks -Override this member function if you want to process the WM_ERASEBKGND message in a `CMDIFrameWndEx`-derived class. +Override this member function if you want to process the `WM_ERASEBKGND` message in a `CMDIFrameWndEx`-derived class. -## CMDIFrameWndEx::OnMenuButtonToolHitTest +## `CMDIFrameWndEx::OnMenuButtonToolHitTest` -Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md)object processes a WM_NCHITTEST message. +Called by the framework when a [`CMFCToolBarButton`](../../mfc/reference/cmfctoolbarbutton-class.md) object processes a `WM_NCHITTEST` message. -``` +```cpp virtual BOOL OnMenuButtonToolHitTest( CMFCToolBarButton* pButton, TOOLINFO* pTI); @@ -1341,42 +1323,42 @@ virtual BOOL OnMenuButtonToolHitTest( ### Parameters -*pButton*
+*`pButton`*\ [in] The toolbar button. -*pTI*
-[out] Pointer to a [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure. +*`pTI`*\ +[out] Pointer to a [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure. -### Return Value +### Return value -TRUE if the application fills the *pTI* parameter. The default implementation returns FALSE. +`TRUE` if the application fills the *`pTI`* parameter. The default implementation returns `FALSE`. ### Remarks Override this method if you want to provide information about specific menu items to a tooltip. The default implementation does nothing. -## CMDIFrameWndEx::OnMoveMiniFrame +## `CMDIFrameWndEx::OnMoveMiniFrame` Called by the framework to move a mini-frame window. -``` +```cpp virtual BOOL OnMoveMiniFrame(CWnd* pFrame); ``` ### Parameters -*pFrame*
+*`pFrame`*\ [in] A pointer to a mini-frame window. -### Return Value +### Return value -TRUE if the method succeeds, otherwise FALSE. +`TRUE` if the method succeeds, otherwise `FALSE`. -## CMDIFrameWndEx::OnSetPreviewMode +## `CMDIFrameWndEx::OnSetPreviewMode` Sets the application's main frame window print-preview mode. -``` +```cpp virtual void OnSetPreviewMode( BOOL bPreview, CPrintPreviewState* pState); @@ -1384,21 +1366,21 @@ virtual void OnSetPreviewMode( ### Parameters -*bPreview*
-[in] If TRUE, sets print-preview mode. If FALSE, cancels preview mode. +*`bPreview`*\ +[in] If `TRUE`, sets print-preview mode. If `FALSE`, cancels preview mode. -*pState*
+*`pState`*\ [in] A pointer to a `CPrintPreviewState` structure. ### Remarks -This method overrides [CFrameWnd::OnSetPreviewMode](../../mfc/reference/cframewnd-class.md#onsetpreviewmode). +This method overrides [`CFrameWnd::OnSetPreviewMode`](../../mfc/reference/cframewnd-class.md#onsetpreviewmode). -## CMDIFrameWndEx::OnShowCustomizePane +## `CMDIFrameWndEx::OnShowCustomizePane` Called by the framework when a Quick Customize pane is activated. -``` +```cpp virtual BOOL OnShowCustomizePane( CMFCPopupMenu* pMenuPane, UINT uiToolbarID); @@ -1406,15 +1388,15 @@ virtual BOOL OnShowCustomizePane( ### Parameters -*pMenuPane*
+*`pMenuPane`*\ [in] A pointer to the Quick Customize pane. -*uiToolbarID*
+*`uiToolbarID`*\ [in] Control ID of the toolbar to customize. -### Return Value +### Return value -This method always returns TRUE. +This method always returns `TRUE`. ### Remarks @@ -1422,11 +1404,11 @@ The Quick Customize pane is a menu that opens when the user clicks **Customize** Override this method in a derived class to make changes in the Quick Customize pane. -## CMDIFrameWndEx::OnShowMDITabContextMenu +## `CMDIFrameWndEx::OnShowMDITabContextMenu` Called by the framework before a shortcut menu is displayed on one of the tabs. Valid for MDI Tabbed Groups only. -``` +```cpp virtual BOOL OnShowMDITabContextMenu( CPoint point, DWORD dwAllowedItems, @@ -1435,32 +1417,28 @@ virtual BOOL OnShowMDITabContextMenu( ### Parameters -*point*
+*`point`*\ [in] The location of the menu in screen coordinates. -*dwAllowedItems*
-[in] A bitwise-OR combination of flags that indicates what actions are allowed for the current tab: +*`dwAllowedItems`*\ +[in] A bitwise "or" (`|`) combination of flags that indicates what actions are allowed for the current tab: -- AFX_MDI_CREATE_VERT_GROUP - can create a vertical tab group. +- `AFX_MDI_CREATE_VERT_GROUP` - can create a vertical tab group. +- `AFX_MDI_CREATE_HORZ_GROUP` - can create a horizontal tab group. +- `AFX_MDI_CAN_MOVE_PREV` - can move a tab to the previous tab group. +- `AFX_MDI_CAN_MOVE_NEXT` - can move a tab to the next tab group. +- `AFX_MDI_CAN_BE_DOCKED` - switch a tabbed document to docked state (relevant for tabbed documents only). -- AFX_MDI_CREATE_HORZ_GROUP - can create a horizontal tab group. +*`bTabDrop`*\ +[in] `TRUE` to display the menu as a result of dragging the tab onto another tabbed group. `FALSE` to display the menu as a shortcut menu on the currently active tab. -- AFX_MDI_CAN_MOVE_PREV - can move a tab to the previous tab group. +### Return value -- AFX_MDI_CAN_MOVE_NEXT - can move a tab to the next tab group. - -- AFX_MDI_CAN_BE_DOCKED - switch a tabbed document to docked state (relevant for tabbed documents only). - -*bTabDrop*
-[in] TRUE to display the menu as a result of dragging the tab onto another tabbed group. FALSE to display the menu as a shortcut menu on the currently active tab. - -### Return Value - -Override this method in a [CMDIFrameWndEx](../../mfc/reference/cmdiframewndex-class.md)-derived class. +Override this method in a [`CMDIFrameWndEx`](../../mfc/reference/cmdiframewndex-class.md)-derived class. ### Remarks -If you do not process `OnShowMDITabContextMenu`, the shortcut menu will not be displayed. This function is generated by the **MFC Application Wizard** when you enable the MDI Tabbed Groups feature. +If you don't process `OnShowMDITabContextMenu`, the shortcut menu won't be displayed. This function is generated by the **MFC Application Wizard** when you enable the MDI Tabbed Groups feature. ### Example @@ -1468,40 +1446,40 @@ The following example shows how `OnShowMDITabContextMenu` is used in the [Visual [!code-cpp[NVC_MFC_VisualStudioDemo#14](../../mfc/codesnippet/cpp/cmdiframewndex-class_13.cpp)] -## CMDIFrameWndEx::OnShowPanes +## `CMDIFrameWndEx::OnShowPanes` Called by the framework to show or hide panes. -``` +```cpp virtual BOOL OnShowPanes(BOOL bShow); ``` ### Parameters -*bShow*
-[in] TRUE to show panes, FALSE to hide panes. +*`bShow`*\ +[in] `TRUE` to show panes, `FALSE` to hide panes. -### Return Value +### Return value -TRUE if the state of the panes changes as a result of calling this method, FALSE if the panes are already in the state specified by *bShow*. For example, if the panes are hidden and *bShow* is FALSE, the return value is FALSE. +`TRUE` if the state of the panes changes as a result of calling this method, `FALSE` if the panes are already in the state specified by *`bShow`*. For example, if the panes are hidden and *`bShow`* is `FALSE`, the Return value is `FALSE`. ### Remarks The default implementation removes the toolbar from the top-level frame window. -If [CDockingManager::m_bHideDockingBarsInContainerMode](../../mfc/reference/cdockingmanager-class.md#m_bhidedockingbarsincontainermode) is TRUE (the default), all docking panes will be hidden. +If [`CDockingManager::m_bHideDockingBarsInContainerMode`](../../mfc/reference/cdockingmanager-class.md#m_bhidedockingbarsincontainermode) is `TRUE` (the default), all docking panes will be hidden. -## CMDIFrameWndEx::OnShowPopupMenu +## `CMDIFrameWndEx::OnShowPopupMenu` Called by the framework when it opens a pop-up menu. -``` +```cpp virtual BOOL OnShowPopupMenu(CMFCPopupMenu*); ``` -### Return Value +### Return value -TRUE if the pop-up menu is to be displayed. Otherwise, FALSE. The default implementation returns TRUE. +`TRUE` if the pop-up menu is to be displayed. Otherwise, `FALSE`. The default implementation returns `TRUE`. ### Remarks @@ -1509,11 +1487,11 @@ Override this method if you want to implement special processing upon pop-up men The default implementation does nothing. -## CMDIFrameWndEx::OnSizeMDIClient +## `CMDIFrameWndEx::OnSizeMDIClient` Called by the framework when the size of the client MDI window is changing. -``` +```cpp virtual void OnSizeMDIClient( const CRect& rectOld, const CRect& rectNew); @@ -1521,19 +1499,19 @@ virtual void OnSizeMDIClient( ### Parameters -*rectOld*
+*`rectOld`*\ [in] The current size of the MDI client window. -*rectNew*
+*`rectNew`*\ [in] The new size of the MDI client window. ### Remarks -## CMDIFrameWndEx::OnTearOffMenu +## `CMDIFrameWndEx::OnTearOffMenu` Called by the framework when a menu that has a tear-off bar is activated. -``` +```cpp virtual BOOL OnTearOffMenu( CMFCPopupMenu* pMenuPopup, CPane* pBar); @@ -1541,38 +1519,38 @@ virtual BOOL OnTearOffMenu( ### Parameters -*pMenuPopup*
+*`pMenuPopup`*\ [in] A pointer to the pop-up menu. -*pBar*
+*`pBar`*\ [in] A pointer to the tear-off bar. -### Return Value +### Return value -TRUE to allow the pop-up menu with the tear-off bar to be made activate; otherwise FALSE. The default is TRUE. +`TRUE` to allow the pop-up menu with the tear-off bar to be made activate; otherwise `FALSE`. The default is `TRUE`. ### Remarks Override this function when you want to implement a special setup for the tear-off bar. The default implementation does nothing. -## CMDIFrameWndEx::OnUpdateFrameMenu +## `CMDIFrameWndEx::OnUpdateFrameMenu` Called by the framework to update the frame menu. -``` +```cpp virtual void OnUpdateFrameMenu(HMENU hMenuAlt); ``` ### Parameters -*hMenuAlt*
+*`hMenuAlt`*\ [in] A handle to a menu. -## CMDIFrameWndEx::PaneFromPoint +## `CMDIFrameWndEx::PaneFromPoint` Returns the docking pane that contains the specified point. -``` +```cpp CBasePane* PaneFromPoint( CPoint point, int nSensitivity, @@ -1588,47 +1566,47 @@ CBasePane* PaneFromPoint( ### Parameters -*point*
+*`point`*\ [in] The point (in screen coordinates). -*nSensitivity*
+*`nSensitivity`*\ [in] The window rectangle of each checked pane is enlarged in all directions by this value. -*bExactBar*
-[in] If TRUE, the *nSensitivity* parameter is ignored. +*`bExactBar`*\ +[in] If `TRUE`, the *`nSensitivity`* parameter is ignored. -*pRTCBarType*
-[in] If non- NULL, the method iterates over only the panes of the specified type. +*`pRTCBarType`*\ +[in] If non- `NULL`, the method iterates over only the panes of the specified type. -*dwAlignment*
+*`dwAlignment`*\ [out] If a pane is found, this parameter will specify which side of the pane is closest to the specified point. -### Return Value +### Return value -A pointer to a docking pane, or NULL if no control contains the point specified by *point*. +A pointer to a docking pane, or `NULL` if no control contains the point specified by *`point`*. ### Remarks -The call is redirected to the [CDockingManager Class](../../mfc/reference/cdockingmanager-class.md). See [CDockingManager::ControlBarFromPoint](../../mfc/reference/cdockingmanager-class.md#panefrompoint) for more information. +The call is redirected to the [`CDockingManager` class](../../mfc/reference/cdockingmanager-class.md). For more information, see [`CDockingManager::ControlBarFromPoint`](../../mfc/reference/cdockingmanager-class.md#panefrompoint). -## CMDIFrameWndEx::RecalcLayout +## `CMDIFrameWndEx::RecalcLayout` Called by the framework to recalculate the layout of the frame window. -``` +```cpp virtual void RecalcLayout(BOOL bNotify = TRUE); ``` ### Parameters -*bNotify*
-[in] Determines whether the active in-place item for the frame window receives notification of the layout change. If TRUE, the item is notified; otherwise FALSE. +*`bNotify`*\ +[in] Determines whether the active in-place item for the frame window receives notification of the layout change. If `TRUE`, the item is notified; otherwise `FALSE`. ### Remarks This method overrides [CFrameWnd::RecalcLayout](../../mfc/reference/cframewnd-class.md#recalclayout). -## CMDIFrameWndEx::RemovePaneFromDockManager +## `CMDIFrameWndEx::RemovePaneFromDockManager` Unregisters a pane and removes it from the docking manager. @@ -1643,59 +1621,54 @@ void RemovePaneFromDockManager( ### Parameters -*pControlBar*
+*`pControlBar`*\ [in] A pointer to a pane to be removed. -*bDestroy*
-[in] TRUE to destroy the removed pane. FALSE to not destroy it. +*`bDestroy`*\ +[in] `TRUE` to destroy the removed pane. `FALSE` to not destroy it. -*bAdjustLayout*
-[in] TRUE to adjust the docking layout immediately. If FALSE, the adjustment will occur only when a redraw event occurs for other reasons (the user resizes the window, drags the main frame, etc.). +*`bAdjustLayout`*\ +[in] `TRUE` to adjust the docking layout immediately. If `FALSE`, the adjustment will occur only when a redraw event occurs for other reasons (the user resizes the window, drags the main frame, etc.). -*bAutoHide*
-[in] TRUE to remove the pane from the list of autohide panes. FALSE to remove the pane from the list of regular panes. +*`bAutoHide`*\ +[in] `TRUE` to remove the pane from the list of autohide panes. `FALSE` to remove the pane from the list of regular panes. -*pBarReplacement*
+*`pBarReplacement`*\ [in] A pointer to a pane that replaces the removed pane. ### Remarks -You must register each pane with the docking manager to take part in the docking layout. Use [CMDIFrameWndEx::AddPane](#addpane) or [CMDIFrameWndEx::InsertPane](#insertpane) to register panes. +You must register each pane with the docking manager to take part in the docking layout. Use [`CMDIFrameWndEx::AddPane`](#addpane) or [`CMDIFrameWndEx::InsertPane`](#insertpane) to register panes. Use this method when a pane is no longer a part of the docking layout of the frame window. -## CMDIFrameWndEx::SaveMDIState +## `CMDIFrameWndEx::SaveMDIState` Saves the current layout of MDI Tabbed Groups and the list of previously opened documents. -``` +```cpp virtual BOOL SaveMDIState(LPCTSTR lpszProfileName); ``` ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the profile name. -### Return Value +### Return value -TRUE if the save succeeded; FALSE if the save failed. +`TRUE` if the save succeeded; `FALSE` if the save failed. ### Remarks To load or save the state of MDI tabs and groups and the list of opened documents, do the following: - Call `SaveMDIState` when the main frame is being closed - -- Call [CMDIFrameWndEx::LoadMDIState](#loadmdistate) when the main frame is being created. The recommended location for this call is before the main frame is displayed for the first time. - +- Call [`CMDIFrameWndEx::LoadMDIState`](#loadmdistate) when the main frame is being created. The recommended location for this call is before the main frame is displayed for the first time. - Call `CWinAppEx::EnableLoadWindowPlacement(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);` - - Call `CWinAppEx::ReloadWindowPlacement(pMainFrame)` after `LoadMDIState` to display the main frame at the position that was stored in the registry. - -- Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that are not stored as files. The returned string will be saved in the registry as a document identifier. For more information, see [CMDIChildWndEx::GetDocumentName](../../mfc/reference/cmdichildwndex-class.md#getdocumentname). - -- Override [CMDIFrameWndEx::CreateDocumentWindow](#createdocumentwindow) to correctly create documents when they are loaded from the registry. The parameter to `CreateDocumentWindow` is the string that `GetDocumentName` returned earlier. +- Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that aren't stored as files. The returned string will be saved in the registry as a document identifier. For more information, see [`CMDIChildWndEx::GetDocumentName`](../../mfc/reference/cmdichildwndex-class.md#getdocumentname). +- Override [`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow) to correctly create documents when they're loaded from the registry. The parameter to `CreateDocumentWindow` is the string that `GetDocumentName` returned earlier. ### Example @@ -1703,7 +1676,7 @@ The following example shows how `SaveMDIState` is used in the [VisualStudioDemo [!code-cpp[NVC_MFC_VisualStudioDemo#15](../../mfc/codesnippet/cpp/cmdiframewndex-class_14.cpp)] -## CMDIFrameWndEx::SetPrintPreviewFrame +## `CMDIFrameWndEx::SetPrintPreviewFrame` Sets the print preview frame window. @@ -1713,12 +1686,12 @@ void SetPrintPreviewFrame(CFrameWnd* pWnd); ### Parameters -*pWnd*
+*`pWnd`*\ [in] Pointer to a print preview frame window. ### Remarks -## CMDIFrameWndEx::SetupToolbarMenu +## `CMDIFrameWndEx::SetupToolbarMenu` Modifies a toolbar object by replacing dummy items with user-defined items. @@ -1731,16 +1704,16 @@ void SetupToolbarMenu( ### Parameters -*menu*
-[in] A reference to a [CMenu Class](../../mfc/reference/cmenu-class.md) object to be modified. +*`menu`*\ +[in] A reference to a [`CMenu` class](../../mfc/reference/cmenu-class.md) object to be modified. -*uiViewUserToolbarCmdFirst*
+*`uiViewUserToolbarCmdFirst`*\ [in] Specifies the first user-defined command. -*uiViewUserToolbarCmdLast*
+*`uiViewUserToolbarCmdLast`*\ [in] Specifies the last user-defined command. -## CMDIFrameWndEx::ShowFullScreen +## `CMDIFrameWndEx::ShowFullScreen` Switches the main frame from regular mode to full-screen mode. @@ -1750,7 +1723,7 @@ void ShowFullScreen(); ### Remarks -## CMDIFrameWndEx::ShowPane +## `CMDIFrameWndEx::ShowPane` Shows or hides the specified pane. @@ -1764,21 +1737,21 @@ void ShowPane( ### Parameters -*pBar*
+*`pBar`*\ [in] Pointer to the pane to be shown or hidden. -*bShow*
-[in] TRUE to show the pane. FALSE to hide the pane. +*`bShow`*\ +[in] `TRUE` to show the pane. `FALSE` to hide the pane. -*bDelay*
-[in] TRUE to delay the recalculation of the docking layout. FALSE to recalculate the docking layout immediately. +*`bDelay`*\ +[in] `TRUE` to delay the recalculation of the docking layout. `FALSE` to recalculate the docking layout immediately. -*bActivate*
-[in] TRUE to show the pane should as active. FALSE to show the pane as inactive. +*`bActivate`*\ +[in] `TRUE` to show the pane as active. `FALSE` to show the pane as inactive. ### Remarks -Call this method to show or hide the pane. Do not use `ShowWindow` for docking panes. +Call this method to show or hide the pane. Don't use `ShowWindow` for docking panes. ### Example @@ -1786,9 +1759,9 @@ The following example shows how `ShowPane` is used in the [VisualStudioDemo Samp [!code-cpp[NVC_MFC_VisualStudioDemo#16](../../mfc/codesnippet/cpp/cmdiframewndex-class_15.cpp)] -## CMDIFrameWndEx::ShowWindowsDialog +## `CMDIFrameWndEx::ShowWindowsDialog` -Creates a [CMFCWindowsManagerDialog](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) box and opens it. +Creates a [`CMFCWindowsManagerDialog`](../../mfc/reference/cmfcwindowsmanagerdialog-class.md) box and opens it. ```cpp void ShowWindowsDialog(); @@ -1800,26 +1773,26 @@ The following example shows how `ShowWindowsDialog` is used in the [VisualStudio [!code-cpp[NVC_MFC_VisualStudioDemo#18](../../mfc/codesnippet/cpp/cmdiframewndex-class_16.cpp)] -## CMDIFrameWndEx::TabbedDocumentToControlBar +## `CMDIFrameWndEx::TabbedDocumentToControlBar` Converts the specified tabbed document to a docking pane. -``` +```cpp virtual BOOL TabbedDocumentToControlBar(CMDIChildWndEx* pMDIChildWnd); ``` ### Parameters -*pMDIChildWnd*
+*`pMDIChildWnd`*\ A pointer to MDI child window that contains a docking pane. -### Return Value +### Return value -TRUE if the method was successful, FALSE on failure. +`TRUE` if the method was successful, `FALSE` on failure. ### Remarks -Use this method to convert a tabbed document to a docking pane. The tabbed document must have been created by using [CMDIFrameWndEx::ControlBarToTabbedDocument](#controlbartotabbeddocument). +Use this method to convert a tabbed document to a docking pane. The tabbed document must have been created by using [`CMDIFrameWndEx::ControlBarToTabbedDocument`](#controlbartotabbeddocument). ### Example @@ -1827,7 +1800,7 @@ The following example shows how `TabbedDocumentToControlBar` is used in the [Vis [!code-cpp[NVC_MFC_VisualStudioDemo#19](../../mfc/codesnippet/cpp/cmdiframewndex-class_17.cpp)] -## CMDIFrameWndEx::UpdateCaption +## `CMDIFrameWndEx::UpdateCaption` Called by the framework to update the window frame caption. @@ -1837,7 +1810,7 @@ void UpdateCaption(); ### Remarks -## CMDIFrameWndEx::UpdateMDITabbedBarsIcons +## `CMDIFrameWndEx::UpdateMDITabbedBarsIcons` Sets the icon for each MDI tabbed pane. @@ -1845,11 +1818,11 @@ Sets the icon for each MDI tabbed pane. void UpdateMDITabbedBarsIcons(); ``` -## CMDIFrameWndEx::WinHelp +## `CMDIFrameWndEx::WinHelp` Called by the framework to initiate the WinHelp application or context help. -``` +```cpp virtual void WinHelp( DWORD dwData, UINT nCmd = HELP_CONTEXT); @@ -1857,19 +1830,19 @@ virtual void WinHelp( ### Parameters -*dwData*
-[in] Specifies data as required for the type of help specified by *nCmd*. +*`dwData`*\ +[in] Specifies data as required for the type of help specified by *`nCmd`*. -*nCmd*
-[in] Specifies the type of help requested. For a list of possible values and how they affect the *dwData* parameter, see the [WinHelp Function](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. +*`nCmd`*\ +[in] Specifies the type of help requested. For more information about the possible values and how they affect the *`dwData`* parameter, see [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw). ### Remarks -This method overrides [CWnd::WinHelp](../../mfc/reference/cwnd-class.md#winhelp). +This method overrides [`CWnd::WinHelp`](../../mfc/reference/cwnd-class.md#winhelp). ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMDIFrameWnd](../../mfc/reference/cframewnd-class.md)
-[CMDIChildWndEx Class](../../mfc/reference/cmdichildwndex-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMDIFrameWnd` class](../../mfc/reference/cframewnd-class.md)\ +[`CMDIChildWndEx` class](../../mfc/reference/cmdichildwndex-class.md) diff --git a/docs/mfc/reference/cmemfile-class.md b/docs/mfc/reference/cmemfile-class.md index cef271bf9c..27a0b75dbf 100644 --- a/docs/mfc/reference/cmemfile-class.md +++ b/docs/mfc/reference/cmemfile-class.md @@ -1,10 +1,9 @@ --- title: "CMemFile Class" description: "Describes the functions available in the CMemFile class which allows you to work with memory files." -ms.date: "07/23/2020" +ms.date: 07/23/2020 f1_keywords: ["CMemFile", "AFX/CMemFile", "AFX/CMemFile::CMemFile", "AFX/CMemFile::Attach", "AFX/CMemFile::Detach", "AFX/CMemFile::Alloc", "AFX/CMemFile::Free", "AFX/CmemFile::GetBufferPtr", AFX/CMemFile::GrowFile", "AFX/CMemFile::Memcpy", "AFX/CMemFile::Realloc"] helpviewer_keywords: ["CMemFile [MFC], CMemFile", "CMemFile [MFC], Attach", "CMemFile [MFC], Detach", "CMemFile [MFC], Alloc", "CMemFile [MFC], Free", "CMemFile [MFC], GetBufferPtr", "CMemFile [MFC], GrowFile", "CMemFile [MFC], Memcpy", "CMemFile [MFC], Realloc"] -ms.assetid: 20e86515-e465-4f73-b2ea-e49789d63165 --- # CMemFile Class @@ -86,7 +85,7 @@ virtual BYTE* Alloc(SIZE_T nBytes); ### Parameters -*nBytes*
+*nBytes*\ Number of bytes of memory to be allocated. ### Return Value @@ -112,13 +111,13 @@ void Attach( ### Parameters -*lpBuffer*
+*lpBuffer*\ Pointer to the buffer to be attached to `CMemFile`. -*nBufferSize*
+*nBufferSize*\ An integer that specifies the size of the buffer in bytes. -*nGrowBytes*
+*nGrowBytes*\ The memory allocation increment in bytes. ### Remarks @@ -127,7 +126,7 @@ This causes `CMemFile` to use the block of memory as the memory file. If *nGrowBytes* is 0, `CMemFile` will set the file length to *nBufferSize*. This means that the data in the memory block before it was attached to `CMemFile` will be used as the file. Memory files created in this manner can't be grown. -Since the file can't be grown, be careful not to cause `CMemFile` to attempt to grow the file. For example, don't call the `CMemFile` overrides of [CFile:Write](../../mfc/reference/cfile-class.md#write) to write past the end or don't call [CFile:SetLength](../../mfc/reference/cfile-class.md#setlength) with a length longer than *nBufferSize*. +Since the file can't be grown, be careful not to cause `CMemFile` to attempt to grow the file. For example, don't call the `CMemFile` overrides of [CFile::Write](../../mfc/reference/cfile-class.md#write) to write past the end or don't call [CFile::SetLength](../../mfc/reference/cfile-class.md#setlength) with a length longer than *nBufferSize*. If *nGrowBytes* is greater than 0, `CMemFile` will ignore the contents of the memory block you've attached. You'll have to write the contents of the memory file from scratch using the `CMemFile` override of `CFile::Write`. If you attempt to write past the end of the file or grow the file by calling the `CMemFile` override of `CFile::SetLength`, `CMemFile` will grow the memory allocation in increments of *nGrowBytes*. Growing the memory allocation will fail if the memory block you pass to `Attach` wasn't allocated with a method compatible with [Alloc](#alloc). To be compatible with the default implementation of `Alloc`, you must allocate the memory with the run-time library function [malloc](../../c-runtime-library/reference/malloc.md) or [calloc](../../c-runtime-library/reference/calloc.md). @@ -146,13 +145,13 @@ CMemFile( ### Parameters -*nGrowBytes*
+*nGrowBytes*\ The memory allocation increment in bytes. -*lpBuffer* +*lpBuffer*\ Pointer to a buffer that receives information of the size *nBufferSize*. -*nBufferSize*
+*nBufferSize*\ An integer that specifies the size of the file buffer, in bytes. ### Remarks @@ -179,7 +178,7 @@ A pointer to the memory block that contains the contents of the memory file. ### Remarks -Calling this function also closes the `CMemFile`. You can reattach the memory block to `CMemFile` by calling [Attach](#attach). If you want to reattach the file and use the data in it, you should call [CFile::GetLength](../../mfc/reference/cfile-class.md#getlength) to get the length of the file before calling `Detach`. If you attach a memory block to `CMemFile` so that you can use its data ( `nGrowBytes` == 0), then you can't grow the memory file. +Calling this function also closes the `CMemFile`. You can reattach the memory block to `CMemFile` by calling [Attach](#attach). If you want to reattach the file and use the data in it, you should call [CFile::GetLength](../../mfc/reference/cfile-class.md#getlength) to get the length of the file before calling `Detach`. If you attach a memory block to `CMemFile` so that you can use its data (`nGrowBytes` == 0), then you can't grow the memory file. ## CMemFile::Free @@ -191,7 +190,7 @@ virtual void Free(BYTE* lpMem); ### Parameters -*lpMem*
+*lpMem*\ Pointer to the memory to be deallocated. ### Remarks @@ -213,16 +212,16 @@ virtual UINT GetBufferPtr( ### Parameters -*nCommand*
-The [bufferCommand](buffercommand-enumeration.md) to carry out (`bufferCheck`, `bufferCommit`, `bufferRead`, or `bufferWrite` ). +*nCommand*\ +The [bufferCommand](buffercommand-enumeration.md) to carry out (`bufferCheck`, `bufferCommit`, `bufferRead`, or `bufferWrite`). -*nCount*
+*nCount*\ Depending on *nCommand*, the number of bytes in the buffer to read, write, or commit. When reading from the buffer, specify -1 to return a buffer from the current position to the end of the file. -*ppBufStart*
+*ppBufStart*\ [out] The start of the buffer. Must be `NULL` when *nCommand* is `bufferCommit`. -*ppBufMax*
+*ppBufMax*\ [out] The end of the buffer. Must be `NULL` when nCommand is `bufferCommit`. ### Return Value @@ -252,7 +251,7 @@ virtual void GrowFile(SIZE_T dwNewLen); ### Parameters -*dwNewLen*
+*dwNewLen*\ New size of the memory file. ### Remarks @@ -272,13 +271,13 @@ virtual BYTE* Memcpy( ### Parameters -*lpMemTarget*
+*lpMemTarget*\ Pointer to the memory block into which the source memory will be copied. -*lpMemSource*
+*lpMemSource*\ Pointer to the source memory block. -*nBytes*
+*nBytes*\ Number of bytes to be copied. ### Return Value @@ -301,10 +300,10 @@ virtual BYTE* Realloc( ### Parameters -*lpMem*
+*lpMem*\ A pointer to the memory block to be reallocated. -*nBytes*
+*nBytes*\ New size for the memory block. ### Return Value @@ -317,5 +316,5 @@ Override this function to implement custom memory reallocation. If you override ## See also -[CFile Class](../../mfc/reference/cfile-class.md)
+[CFile Class](../../mfc/reference/cfile-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/cmenu-class.md b/docs/mfc/reference/cmenu-class.md index 2b144ffb58..70d8e40d75 100644 --- a/docs/mfc/reference/cmenu-class.md +++ b/docs/mfc/reference/cmenu-class.md @@ -1286,7 +1286,7 @@ The Windows `GetMenuCheckMarkDimensions` function retrieves the dimensions of th ### Example [!code-cpp[NVC_MFCWindowing#32](../../mfc/reference/codesnippet/cpp/cmenu-class_12.cpp)] - +  [!code-cpp[NVC_MFCWindowing#33](../../mfc/reference/codesnippet/cpp/cmenu-class_13.cpp)] ## `CMenu::SetMenuItemInfo` diff --git a/docs/mfc/reference/cmfcbasetabctrl-class.md b/docs/mfc/reference/cmfcbasetabctrl-class.md index b20f815af9..d34822e52a 100644 --- a/docs/mfc/reference/cmfcbasetabctrl-class.md +++ b/docs/mfc/reference/cmfcbasetabctrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCBaseTabCtrl Class" title: "CMFCBaseTabCtrl Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCBaseTabCtrl Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCBaseTabCtrl", "AFXBASETABCTRL/CMFCBaseTabCtrl", "AFXBASETABCTRL/CMFCBaseTabCtrl::AddIcon", "AFXBASETABCTRL/CMFCBaseTabCtrl::AddTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::ApplyRestoredTabInfo", "AFXBASETABCTRL/CMFCBaseTabCtrl::AutoDestroyWindow", "AFXBASETABCTRL/CMFCBaseTabCtrl::CalcRectEdit", "AFXBASETABCTRL/CMFCBaseTabCtrl::CleanUp", "AFXBASETABCTRL/CMFCBaseTabCtrl::ClearImageList", "AFXBASETABCTRL/CMFCBaseTabCtrl::DetachTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableActivateLastActive", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableAutoColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableCustomToolTips", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableInPlaceEdit", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableTabDetach", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnableTabSwap", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnsureVisible", "AFXBASETABCTRL/CMFCBaseTabCtrl::EnterDragMode", "AFXBASETABCTRL/CMFCBaseTabCtrl::FindTargetWnd", "AFXBASETABCTRL/CMFCBaseTabCtrl::FireChangeActiveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::FireChangingActiveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetActiveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetActiveTabColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetActiveTabTextColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetActiveWnd", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetAutoColors", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetFirstVisibleTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetFirstVisibleTabNum", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetHighlightedTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetImageList", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetImageSize", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetLastVisibleTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetLocation", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetMaxWindowSize", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabArea", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabBkColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabBorderSize", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabByID", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabCloseButton", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabFromHwnd", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabFromPoint", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabFullWidth", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabHicon", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabID", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabIcon", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabLabel", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabRect", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabsHeight", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabsRect", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabTextColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabWnd", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabWndNoWrapper", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetTabsNum", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetToolTipCtrl", "AFXBASETABCTRL/CMFCBaseTabCtrl::GetVisibleTabsNum", "AFXBASETABCTRL/CMFCBaseTabCtrl::HasImage", "AFXBASETABCTRL/CMFCBaseTabCtrl::HideSingleTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::InsertTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::InvalidateTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsActiveTabCloseButton", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsAutoColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsAutoDestroyWindow", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsColored", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsDialogControl", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsDrawNoPrefix", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsFlatFrame", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsFlatTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsHideSingleTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsIconAdded", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsInPlaceEdit", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsLeftRightRounded", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsMDITab", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsOneNoteStyle", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsPtInTabArea", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabCloseButtonHighlighted", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabCloseButtonPressed", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabDetachable", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabIconOnly", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabSwapEnabled", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsTabVisible", "AFXBASETABCTRL/CMFCBaseTabCtrl::IsVS2005Style", "AFXBASETABCTRL/CMFCBaseTabCtrl::MoveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnChangeTabs", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnDragEnter", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnDragLeave", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnDragOver", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnDrop", "AFXBASETABCTRL/CMFCBaseTabCtrl::OnRenameTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::PreTranslateMessage", "AFXBASETABCTRL/CMFCBaseTabCtrl::RecalcLayout", "AFXBASETABCTRL/CMFCBaseTabCtrl::RemoveAllTabs", "AFXBASETABCTRL/CMFCBaseTabCtrl::RemoveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::RenameTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::ResetImageList", "AFXBASETABCTRL/CMFCBaseTabCtrl::Serialize", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetActiveTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetActiveTabColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetActiveTabTextColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetAutoColors", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetDockingBarWrapperRTC", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetDrawNoPrefix", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetImageList", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetLocation", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabBkColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabBorderSize", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabHicon", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabIcon", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabIconOnly", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabLabel", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabsHeight", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabTextColor", "AFXBASETABCTRL/CMFCBaseTabCtrl::SetTabsOrder", "AFXBASETABCTRL/CMFCBaseTabCtrl::ShowTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::StartRenameTab", "AFXBASETABCTRL/CMFCBaseTabCtrl::SwapTabs", "AFXBASETABCTRL/CMFCBaseTabCtrl::CreateWrapper", "AFXBASETABCTRL/CMFCBaseTabCtrl::m_bActivateTabOnRightClick", "AFXBASETABCTRL/CMFCBaseTabCtrl::m_bAutoDestroyWindow"] helpviewer_keywords: ["CMFCBaseTabCtrl [MFC], AddIcon", "CMFCBaseTabCtrl [MFC], AddTab", "CMFCBaseTabCtrl [MFC], ApplyRestoredTabInfo", "CMFCBaseTabCtrl [MFC], AutoDestroyWindow", "CMFCBaseTabCtrl [MFC], CalcRectEdit", "CMFCBaseTabCtrl [MFC], CleanUp", "CMFCBaseTabCtrl [MFC], ClearImageList", "CMFCBaseTabCtrl [MFC], DetachTab", "CMFCBaseTabCtrl [MFC], EnableActivateLastActive", "CMFCBaseTabCtrl [MFC], EnableAutoColor", "CMFCBaseTabCtrl [MFC], EnableCustomToolTips", "CMFCBaseTabCtrl [MFC], EnableInPlaceEdit", "CMFCBaseTabCtrl [MFC], EnableTabDetach", "CMFCBaseTabCtrl [MFC], EnableTabSwap", "CMFCBaseTabCtrl [MFC], EnsureVisible", "CMFCBaseTabCtrl [MFC], EnterDragMode", "CMFCBaseTabCtrl [MFC], FindTargetWnd", "CMFCBaseTabCtrl [MFC], FireChangeActiveTab", "CMFCBaseTabCtrl [MFC], FireChangingActiveTab", "CMFCBaseTabCtrl [MFC], GetActiveTab", "CMFCBaseTabCtrl [MFC], GetActiveTabColor", "CMFCBaseTabCtrl [MFC], GetActiveTabTextColor", "CMFCBaseTabCtrl [MFC], GetActiveWnd", "CMFCBaseTabCtrl [MFC], GetAutoColors", "CMFCBaseTabCtrl [MFC], GetFirstVisibleTab", "CMFCBaseTabCtrl [MFC], GetFirstVisibleTabNum", "CMFCBaseTabCtrl [MFC], GetHighlightedTab", "CMFCBaseTabCtrl [MFC], GetImageList", "CMFCBaseTabCtrl [MFC], GetImageSize", "CMFCBaseTabCtrl [MFC], GetLastVisibleTab", "CMFCBaseTabCtrl [MFC], GetLocation", "CMFCBaseTabCtrl [MFC], GetMaxWindowSize", "CMFCBaseTabCtrl [MFC], GetTabArea", "CMFCBaseTabCtrl [MFC], GetTabBkColor", "CMFCBaseTabCtrl [MFC], GetTabBorderSize", "CMFCBaseTabCtrl [MFC], GetTabByID", "CMFCBaseTabCtrl [MFC], GetTabCloseButton", "CMFCBaseTabCtrl [MFC], GetTabFromHwnd", "CMFCBaseTabCtrl [MFC], GetTabFromPoint", "CMFCBaseTabCtrl [MFC], GetTabFullWidth", "CMFCBaseTabCtrl [MFC], GetTabHicon", "CMFCBaseTabCtrl [MFC], GetTabID", "CMFCBaseTabCtrl [MFC], GetTabIcon", "CMFCBaseTabCtrl [MFC], GetTabLabel", "CMFCBaseTabCtrl [MFC], GetTabRect", "CMFCBaseTabCtrl [MFC], GetTabsHeight", "CMFCBaseTabCtrl [MFC], GetTabsRect", "CMFCBaseTabCtrl [MFC], GetTabTextColor", "CMFCBaseTabCtrl [MFC], GetTabWnd", "CMFCBaseTabCtrl [MFC], GetTabWndNoWrapper", "CMFCBaseTabCtrl [MFC], GetTabsNum", "CMFCBaseTabCtrl [MFC], GetToolTipCtrl", "CMFCBaseTabCtrl [MFC], GetVisibleTabsNum", "CMFCBaseTabCtrl [MFC], HasImage", "CMFCBaseTabCtrl [MFC], HideSingleTab", "CMFCBaseTabCtrl [MFC], InsertTab", "CMFCBaseTabCtrl [MFC], InvalidateTab", "CMFCBaseTabCtrl [MFC], IsActiveTabCloseButton", "CMFCBaseTabCtrl [MFC], IsAutoColor", "CMFCBaseTabCtrl [MFC], IsAutoDestroyWindow", "CMFCBaseTabCtrl [MFC], IsColored", "CMFCBaseTabCtrl [MFC], IsDialogControl", "CMFCBaseTabCtrl [MFC], IsDrawNoPrefix", "CMFCBaseTabCtrl [MFC], IsFlatFrame", "CMFCBaseTabCtrl [MFC], IsFlatTab", "CMFCBaseTabCtrl [MFC], IsHideSingleTab", "CMFCBaseTabCtrl [MFC], IsIconAdded", "CMFCBaseTabCtrl [MFC], IsInPlaceEdit", "CMFCBaseTabCtrl [MFC], IsLeftRightRounded", "CMFCBaseTabCtrl [MFC], IsMDITab", "CMFCBaseTabCtrl [MFC], IsOneNoteStyle", "CMFCBaseTabCtrl [MFC], IsPtInTabArea", "CMFCBaseTabCtrl [MFC], IsTabCloseButtonHighlighted", "CMFCBaseTabCtrl [MFC], IsTabCloseButtonPressed", "CMFCBaseTabCtrl [MFC], IsTabDetachable", "CMFCBaseTabCtrl [MFC], IsTabIconOnly", "CMFCBaseTabCtrl [MFC], IsTabSwapEnabled", "CMFCBaseTabCtrl [MFC], IsTabVisible", "CMFCBaseTabCtrl [MFC], IsVS2005Style", "CMFCBaseTabCtrl [MFC], MoveTab", "CMFCBaseTabCtrl [MFC], OnChangeTabs", "CMFCBaseTabCtrl [MFC], OnDragEnter", "CMFCBaseTabCtrl [MFC], OnDragLeave", "CMFCBaseTabCtrl [MFC], OnDragOver", "CMFCBaseTabCtrl [MFC], OnDrop", "CMFCBaseTabCtrl [MFC], OnRenameTab", "CMFCBaseTabCtrl [MFC], PreTranslateMessage", "CMFCBaseTabCtrl [MFC], RecalcLayout", "CMFCBaseTabCtrl [MFC], RemoveAllTabs", "CMFCBaseTabCtrl [MFC], RemoveTab", "CMFCBaseTabCtrl [MFC], RenameTab", "CMFCBaseTabCtrl [MFC], ResetImageList", "CMFCBaseTabCtrl [MFC], Serialize", "CMFCBaseTabCtrl [MFC], SetActiveTab", "CMFCBaseTabCtrl [MFC], SetActiveTabColor", "CMFCBaseTabCtrl [MFC], SetActiveTabTextColor", "CMFCBaseTabCtrl [MFC], SetAutoColors", "CMFCBaseTabCtrl [MFC], SetDockingBarWrapperRTC", "CMFCBaseTabCtrl [MFC], SetDrawNoPrefix", "CMFCBaseTabCtrl [MFC], SetImageList", "CMFCBaseTabCtrl [MFC], SetLocation", "CMFCBaseTabCtrl [MFC], SetTabBkColor", "CMFCBaseTabCtrl [MFC], SetTabBorderSize", "CMFCBaseTabCtrl [MFC], SetTabHicon", "CMFCBaseTabCtrl [MFC], SetTabIcon", "CMFCBaseTabCtrl [MFC], SetTabIconOnly", "CMFCBaseTabCtrl [MFC], SetTabLabel", "CMFCBaseTabCtrl [MFC], SetTabsHeight", "CMFCBaseTabCtrl [MFC], SetTabTextColor", "CMFCBaseTabCtrl [MFC], SetTabsOrder", "CMFCBaseTabCtrl [MFC], ShowTab", "CMFCBaseTabCtrl [MFC], StartRenameTab", "CMFCBaseTabCtrl [MFC], SwapTabs", "CMFCBaseTabCtrl [MFC], CreateWrapper", "CMFCBaseTabCtrl [MFC], m_bActivateTabOnRightClick", "CMFCBaseTabCtrl [MFC], m_bAutoDestroyWindow"] -ms.assetid: 7270c55f-6f6e-4dd2-b0d2-291afeac3882 --- # CMFCBaseTabCtrl Class @@ -210,7 +209,7 @@ Adds a new tab to the tab control. virtual void AddTab( CWnd* pTabWnd, LPCTSTR lpszTabLabel, - UINT uiImageId = (UINT)-1,, + UINT uiImageId = (UINT)-1, BOOL bDetachable = TRUE); virtual void AddTab( @@ -317,7 +316,7 @@ virtual CWnd* CreateWrapper( ### Return Value -A pointer to wrapper derived from the `CDockablePane` class if `CreateWrapper` successfully creates a wrapper class for *pWndToWrap*. If the method fails, it retruns *pWndToWrap*. +A pointer to wrapper derived from the `CDockablePane` class if `CreateWrapper` successfully creates a wrapper class for *pWndToWrap*. If the method fails, it returns *pWndToWrap*. ### Remarks @@ -1757,7 +1756,7 @@ virtual void SetActiveTabColor(COLORREF clr); ### Remarks -The framework obtains the default background color for active tabs from the [GetSysColor](/windows/win32/api/winuser/nf-winuser-getsyscolor)method. +The framework obtains the default background color for active tabs from the [GetSysColor](/windows/win32/api/winuser/nf-winuser-getsyscolor) method. ## CMFCBaseTabCtrl::SetActiveTabTextColor @@ -2138,7 +2137,7 @@ virtual void SwapTabs( ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCTabCtrl Class](../../mfc/reference/cmfctabctrl-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[CMFCTabCtrl Class](../../mfc/reference/cmfctabctrl-class.md)\ [CMFCOutlookBarTabCtrl Class](../../mfc/reference/cmfcoutlookbartabctrl-class.md) diff --git a/docs/mfc/reference/cmfcbutton-class.md b/docs/mfc/reference/cmfcbutton-class.md index 5cf031c6e9..a244e55d07 100644 --- a/docs/mfc/reference/cmfcbutton-class.md +++ b/docs/mfc/reference/cmfcbutton-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCButton Class" title: "CMFCButton Class" +description: "Learn more about: CMFCButton Class" ms.date: "08/28/2018" f1_keywords: ["CMFCButton", "AFXBUTTON/CMFCButton", "AFXBUTTON/CMFCButton::CleanUp", "AFXBUTTON/CMFCButton::EnableFullTextTooltip", "AFXBUTTON/CMFCButton::EnableMenuFont", "AFXBUTTON/CMFCButton::EnableWindowsTheming", "AFXBUTTON/CMFCButton::GetToolTipCtrl", "AFXBUTTON/CMFCButton::IsAutoCheck", "AFXBUTTON/CMFCButton::IsAutorepeatCommandMode", "AFXBUTTON/CMFCButton::IsCheckBox", "AFXBUTTON/CMFCButton::IsChecked", "AFXBUTTON/CMFCButton::IsHighlighted", "AFXBUTTON/CMFCButton::IsPressed", "AFXBUTTON/CMFCButton::IsPushed", "AFXBUTTON/CMFCButton::IsRadioButton", "AFXBUTTON/CMFCButton::IsWindowsThemingEnabled", "AFXBUTTON/CMFCButton::SetAutorepeatMode", "AFXBUTTON/CMFCButton::SetCheckedImage", "AFXBUTTON/CMFCButton::SetFaceColor", "AFXBUTTON/CMFCButton::SetImage", "AFXBUTTON/CMFCButton::SetMouseCursor", "AFXBUTTON/CMFCButton::SetMouseCursorHand", "AFXBUTTON/CMFCButton::SetStdImage", "AFXBUTTON/CMFCButton::SetTextColor", "AFXBUTTON/CMFCButton::SetTextHotColor", "AFXBUTTON/CMFCButton::SetTooltip", "AFXBUTTON/CMFCButton::SizeToContent", "AFXBUTTON/CMFCButton::OnDraw", "AFXBUTTON/CMFCButton::OnDrawBorder", "AFXBUTTON/CMFCButton::OnDrawFocusRect", "AFXBUTTON/CMFCButton::OnDrawText", "AFXBUTTON/CMFCButton::OnFillBackground", "AFXBUTTON/CMFCButton::SelectFont", "AFXBUTTON/CMFCButton::m_bDrawFocus", "AFXBUTTON/CMFCButton::m_bHighlightChecked", "AFXBUTTON/CMFCButton::m_bRightImage", "AFXBUTTON/CMFCButton::m_bTransparent", "AFXBUTTON/CMFCButton::m_nAlignStyle", "AFXBUTTON/CMFCButton::m_nFlatStyle"] helpviewer_keywords: ["CMFCButton [MFC], CleanUp", "CMFCButton [MFC], EnableFullTextTooltip", "CMFCButton [MFC], EnableMenuFont", "CMFCButton [MFC], EnableWindowsTheming", "CMFCButton [MFC], GetToolTipCtrl", "CMFCButton [MFC], IsAutoCheck", "CMFCButton [MFC], IsAutorepeatCommandMode", "CMFCButton [MFC], IsCheckBox", "CMFCButton [MFC], IsChecked", "CMFCButton [MFC], IsHighlighted", "CMFCButton [MFC], IsPressed", "CMFCButton [MFC], IsPushed", "CMFCButton [MFC], IsRadioButton", "CMFCButton [MFC], IsWindowsThemingEnabled", "CMFCButton [MFC], SetAutorepeatMode", "CMFCButton [MFC], SetCheckedImage", "CMFCButton [MFC], SetFaceColor", "CMFCButton [MFC], SetImage", "CMFCButton [MFC], SetMouseCursor", "CMFCButton [MFC], SetMouseCursorHand", "CMFCButton [MFC], SetStdImage", "CMFCButton [MFC], SetTextColor", "CMFCButton [MFC], SetTextHotColor", "CMFCButton [MFC], SetTooltip", "CMFCButton [MFC], SizeToContent", "CMFCButton [MFC], OnDraw", "CMFCButton [MFC], OnDrawBorder", "CMFCButton [MFC], OnDrawFocusRect", "CMFCButton [MFC], OnDrawText", "CMFCButton [MFC], OnFillBackground", "CMFCButton [MFC], SelectFont", "CMFCButton [MFC], m_bDrawFocus", "CMFCButton [MFC], m_bHighlightChecked", "CMFCButton [MFC], m_bRightImage", "CMFCButton [MFC], m_bTransparent", "CMFCButton [MFC], m_nAlignStyle", "CMFCButton [MFC], m_nFlatStyle"] -ms.assetid: 4b32f57c-7a53-4734-afb9-d47e3359f62e --- # `CMFCButton` Class @@ -12,7 +11,7 @@ The `CMFCButton` class adds functionality to the [`CButton`](../../mfc/reference ## Syntax -``` +```cpp class CMFCButton : public CButton ``` @@ -46,7 +45,7 @@ class CMFCButton : public CButton |[`CMFCButton::IsPushed`](#ispushed)|Indicates whether a button is pushed.| |[`CMFCButton::IsRadioButton`](#isradiobutton)|Indicates whether a button is a radio button.| |[`CMFCButton::IsWindowsThemingEnabled`](#iswindowsthemingenabled)|Indicates whether the style of the button border corresponds to the current Windows theme.| -|`CMFCButton::OnDrawParentBackground`|Draws the background of a button's parent in the specified area. (Overrides [`AFX_GLOBAL_DATA::DrawParentBackground`](../../mfc/reference/afx-global-data-structure.md)| +|`CMFCButton::OnDrawParentBackground`|Draws the background of a button's parent in the specified area. (Overrides [`AFX_GLOBAL_DATA::DrawParentBackground`](../../mfc/reference/afx-global-data-structure.md).)| |`CMFCButton::PreTranslateMessage`|Translates window messages before they are dispatched to the [`TranslateMessage`](/windows/win32/api/winuser/nf-winuser-translatemessage) and [`DispatchMessage`](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides [`CWnd::PreTranslateMessage`](../../mfc/reference/cwnd-class.md#pretranslatemessage).)| |[`CMFCButton::SetAutorepeatMode`](#setautorepeatmode)|Sets a button to auto-repeat mode.| |[`CMFCButton::SetCheckedImage`](#setcheckedimage)|Sets the image for a checked button.| @@ -79,8 +78,8 @@ class CMFCButton : public CButton |[`CMFCButton::m_bDontUseWinXPTheme`](#m_bDontUseWinXPTheme)|Specifies whether to use Windows XP themes.| |[`CMFCButton::m_bDrawFocus`](#m_bdrawfocus)|Indicates whether to draw a focus rectangle around a button.| |[`CMFCButton::m_nFlatStyle`](#m_nflatstyle)|Specifies the style of the button, such as borderless, flat, semi-flat, or 3D.| -|[`CMFCButton::m_bGrayDisabled`](#m_bGrayDisabled)|When TRUE, enables a disabled button to be drawn as grayed-out.| -|[`CMFCButton::m_bHighlightChecked`](#m_bhighlightchecked)|Indicates whether to highlight a BS_CHECKBOX-style button when the cursor hovers over it.| +|[`CMFCButton::m_bGrayDisabled`](#m_bGrayDisabled)|When `TRUE`, enables a disabled button to be drawn as grayed-out.| +|[`CMFCButton::m_bHighlightChecked`](#m_bhighlightchecked)|Indicates whether to highlight a `BS_CHECKBOX`-style button when the cursor hovers over it.| |[`CMFCButton::m_bResponseOnButtonDown`](#m_bResponseOnButtonDown)|Indicates whether to respond to button down events.| |[`CMFCButton::m_bRightImage`](#m_brightimage)|Indicates whether to display an image on the right side of the button.| |[`CMFCButton::m_bTopImage`](#m_bTopImage)| Indicates whether the image is on top of the button.| @@ -126,7 +125,7 @@ The following example demonstrates how to configure the properties of the button Resets internal variables and frees allocated resources such as images, bitmaps, and icons. -``` +```cpp virtual void CleanUp(); ``` @@ -140,11 +139,9 @@ void EnableFullTextTooltip(BOOL bOn=TRUE); ### Parameters -*`bOn`*
+*`bOn`*\ [in] `TRUE` to display all of the text; `FALSE` to display truncated text. -### Remarks - ## `CMFCButton::EnableMenuFont` Specifies whether the button text font is the same as the application menu font. @@ -157,10 +154,10 @@ void EnableMenuFont( ### Parameters -*`bOn`*
+*`bOn`*\ [in] `TRUE` to use the application menu font as the button text font; `FALSE` to use the system font. The default is `TRUE`. -*`bRedraw`*
+*`bRedraw`*\ [in] `TRUE` to immediately redraw the screen; otherwise, `FALSE`. The default is `TRUE`. ### Remarks @@ -171,13 +168,13 @@ If you do not use this method to specify the button text font, you can specify t Specifies whether the style of the button border corresponds to the current Windows theme. -``` +```cpp static void EnableWindowsTheming(BOOL bEnable = TRUE); ``` ### Parameters -*`bEnable`*
+*`bEnable`*\ [in] `TRUE` to use the current Windows theme to draw button borders; `FALSE` to not use the Windows theme. The default is `TRUE`. ### Remarks @@ -188,7 +185,7 @@ This method affects all buttons in your application that are derived from the `C Returns a reference to the underlying tooltip control. -``` +```cpp CToolTipCtrl& GetToolTipCtrl(); ``` @@ -196,13 +193,11 @@ CToolTipCtrl& GetToolTipCtrl(); A reference to the underlying tooltip control. -### Remarks - ## `CMFCButton::IsAutoCheck` Indicates whether a check box or radio button is an automatic button. -``` +```cpp BOOL IsAutoCheck() const; ``` @@ -210,13 +205,11 @@ BOOL IsAutoCheck() const; `TRUE` if the button has style `BS_AUTOCHECKBOX` or `BS_AUTORADIOBUTTON`; otherwise, `FALSE`. -### Remarks - ## `CMFCButton::IsAutorepeatCommandMode` Indicates whether a button is set to auto-repeat mode. -``` +```cpp BOOL IsAutorepeatCommandMode() const; ``` @@ -232,7 +225,7 @@ Use the [`CMFCButton::SetAutorepeatMode`](#setautorepeatmode) method to set a bu Indicates whether a button is a check box button. -``` +```cpp BOOL IsCheckBox() const; ``` @@ -240,13 +233,11 @@ BOOL IsCheckBox() const; `TRUE` if the button has either `BS_CHECKBOX` or `BS_AUTOCHECKBOX` style; otherwise, `FALSE`. -### Remarks - ## `CMFCButton::IsChecked` Indicates whether the current button is checked. -``` +```cpp BOOL IsChecked() const; ``` @@ -262,7 +253,7 @@ The framework uses different ways to indicate that different kinds of buttons ar Indicates whether a button is highlighted. -``` +```cpp BOOL IsHighlighted() const; ``` @@ -278,7 +269,7 @@ A button becomes highlighted when the mouse hovers over the button. Indicates whether a button is pushed and highlighted. -``` +```cpp BOOL IsPressed() const; ``` @@ -286,13 +277,11 @@ BOOL IsPressed() const; `TRUE` if the button is pressed; otherwise, `FALSE`. -### Remarks - ## `CMFCButton::IsPushed` Indicates whether a button is pushed. -``` +```cpp BOOL IsPushed() const; ``` @@ -300,13 +289,11 @@ BOOL IsPushed() const; `TRUE` if the button is pushed; otherwise, `FALSE`. -### Remarks - ## `CMFCButton::IsRadioButton` Indicates whether a button is a radio button. -``` +```cpp BOOL IsRadioButton() const; ``` @@ -314,13 +301,11 @@ BOOL IsRadioButton() const; `TRUE` if the button style is `BS_RADIOBUTTON` or `BS_AUTORADIOBUTTON`; otherwise, `FALSE`. -### Remarks - ## `CMFCButton::IsWindowsThemingEnabled` Indicates whether the style of the button border corresponds to the current Windows theme. -``` +```cpp static BOOL IsWindowsThemingEnabled(); ``` @@ -328,11 +313,11 @@ static BOOL IsWindowsThemingEnabled(); `TRUE` if the style of the button border corresponds to the current Windows theme; otherwise, `FALSE`. -## `CMFCButton::m_bDontUseWinXPTheme` +## `CMFCButton::m_bDontUseWinXPTheme` Specifies whether to use Windows XP themes when drawing the button. -``` +```cpp BOOL m_bDontUseWinXPTheme; ``` @@ -340,7 +325,7 @@ BOOL m_bDontUseWinXPTheme; Indicates whether to draw a focus rectangle around a button. -``` +```cpp BOOL m_bDrawFocus; ``` @@ -354,7 +339,7 @@ The `CMFCButton` constructor initializes this member to `TRUE`. When `TRUE`, enables a disabled button to be drawn as grayed-out. -``` +```cpp BOOL m_bGrayDisabled; ``` @@ -362,7 +347,7 @@ BOOL m_bGrayDisabled; Indicates whether to highlight a `BS_CHECKBOX`-style button when the cursor hovers over it. -``` +```cpp BOOL m_bHighlightChecked; ``` @@ -374,7 +359,7 @@ Set the `m_bHighlightChecked` member to `TRUE` to specify that the framework wil Indicates whether to respond to button down events. -``` +```cpp BOOL m_bResponseOnButtonDown; ``` @@ -382,15 +367,15 @@ BOOL m_bResponseOnButtonDown; Indicates whether to display an image on the right side of the button. -``` +```cpp BOOL m_bRightImage; ``` -## `CMFCButton::m_bTopImage](#m_bTopImage)` +## `CMFCButton::m_bTopImage` Indicates whether the image is on top of the button. -``` +```cpp BOOL m_bTopImage; ``` @@ -402,7 +387,7 @@ Set the `m_bRightImage` member to `TRUE` to specify that the framework will disp Indicates whether the button is transparent. -``` +```cpp BOOL m_bTransparent; ``` @@ -414,7 +399,7 @@ Set the `m_bTransparent` member to `TRUE` to specify that the framework will mak Specifies the alignment of the button text. -``` +```cpp AlignStyle m_nAlignStyle; ``` @@ -430,11 +415,11 @@ Use one of the following `CMFCButton::AlignStyle` enumeration values to specify The `CMFCButton` constructor initializes this member to `ALIGN_CENTER`. -## `CMFCButton::m_bWasDblClk`](#m_bWasDblClk)| +## `CMFCButton::m_bWasDblClk` -Indicates whether the last click event was a double-click.| +Indicates whether the last click event was a double-click. -``` +```cpp BOOL m_bWasDblClk; ``` @@ -442,8 +427,8 @@ BOOL m_bWasDblClk; Specifies the style of the button, such as borderless, flat, semi-flat, or 3D. -``` -FlatStyle m_nFlatStyle; +```cpp +FlatStyle m_nFlatStyle; ``` ### Remarks @@ -470,7 +455,7 @@ The following example demonstrates how to set the values of the `m_nFlatStyle` m Called by the framework to draw a button. -``` +```cpp virtual void OnDraw( CDC* pDC, const CRect& rect, @@ -479,13 +464,13 @@ virtual void OnDraw( ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. -*`rect`*
+*`rect`*\ [in] A reference to a rectangle that bounds the button. -*`uiState`*
+*`uiState`*\ [in] The current button state. For more information, see the `itemState` member of the [`DRAWITEMSTRUCT` Structure](/windows/win32/api/winuser/ns-winuser-drawitemstruct) topic. ### Remarks @@ -496,7 +481,7 @@ Override this method to use your own code to draw a button. Called by the framework to draw the border of a button. -``` +```cpp virtual void OnDrawBorder( CDC* pDC, CRect& rectClient, @@ -505,13 +490,13 @@ virtual void OnDrawBorder( ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. -*`rectClient`*
+*`rectClient`*\ [in] A reference to a rectangle that bounds the button. -*`uiState`*
+*`uiState`*\ [in] The current button state. For more information, see the `itemState` member of the [`DRAWITEMSTRUCT` Structure](/windows/win32/api/winuser/ns-winuser-drawitemstruct) topic. ### Remarks @@ -522,7 +507,7 @@ Override this method to use your own code to draw the border. Called by the framework to draw the focus rectangle for a button. -``` +```cpp virtual void OnDrawFocusRect( CDC* pDC, const CRect& rectClient); @@ -530,10 +515,10 @@ virtual void OnDrawFocusRect( ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. -*`rectClient`*
+*`rectClient`*\ [in] A reference to a rectangle that bounds the button. ### Remarks @@ -544,7 +529,7 @@ Override this method to use your own code to draw the focus rectangle. Called by the framework to draw the button text. -``` +```cpp virtual void OnDrawText( CDC* pDC, const CRect& rect, @@ -555,19 +540,19 @@ virtual void OnDrawText( ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. -*`rect`*
+*`rect`*\ [in] A reference to a rectangle that bounds the button. -*`strText`*
+*`strText`*\ [in] The text to draw. -*`uiDTFlags`*
+*`uiDTFlags`*\ [in] Flags that specify how to format the text. For more information, see the *`nFormat`* parameter of the [`CDC::DrawText`](../../mfc/reference/cdc-class.md#drawtext) method. -*`uiState`*
+*`uiState`*\ [in] Reserved. ### Remarks @@ -578,7 +563,7 @@ Override this method to use your own code to draw the button text. Called by the framework to draw the background of the button text. -``` +```cpp virtual void OnFillBackground( CDC* pDC, const CRect& rectClient); @@ -586,10 +571,10 @@ virtual void OnFillBackground( ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. -*`rectClient`*
+*`rectClient`*\ [in] A reference to a rectangle that bounds the button. ### Remarks @@ -600,21 +585,19 @@ Override this method to use your own code to draw the background of a button. Retrieves the font that is associated with the specified device context. -``` +```cpp virtual CFont* SelectFont(CDC* pDC); ``` ### Parameters -*`pDC`*
+*`pDC`*\ [in] A pointer to a device context. ### Return Value Override this method to use your own code to retrieve the font. -### Remarks - ## `CMFCButton::SetAutorepeatMode` Sets a button to auto-repeat mode. @@ -625,7 +608,7 @@ void SetAutorepeatMode(int nTimeDelay=500); ### Parameters -*`nTimeDelay`*
+*`nTimeDelay`*\ [in] A nonnegative number that specifies the interval between messages that are sent to the parent window. The interval is measured in milliseconds and its default value is 500 milliseconds. Specify zero to disable auto-repeat message mode. ### Remarks @@ -659,44 +642,42 @@ void SetCheckedImage( ### Parameters -*`hIcon`*
+*`hIcon`*\ [in] Handle to the icon that contains the bitmap and mask for the new image. -*`bAutoDestroy`*
+*`bAutoDestroy`*\ [in] `TRUE` to specify that bitmap resources be destroyed automatically; otherwise, `FALSE`. The default is `TRUE`. -*`hIconHot`*
+*`hIconHot`*\ [in] Handle to the icon that contains the image for the selected state. -*`hBitmap`*
+*`hBitmap`*\ [in] Handle to the bitmap that contains the image for the non-selected state. -*`hBitmapHot`*
+*`hBitmapHot`*\ [in] Handle to the bitmap that contains the image for the selected state. -*`bMap3dColors`*
+*`bMap3dColors`*\ [in] Specifies a transparent color for the button background; that is, the face of the button. `TRUE` to use the color value RGB(192, 192, 192); `FALSE` to use the color value defined by `AFX_GLOBAL_DATA::clrBtnFace`. -*`uiBmpResId`*
+*`uiBmpResId`*\ [in] Resource ID for the non-selected image. -*`uiBmpHotResId`*
+*`uiBmpHotResId`*\ [in] Resource ID for the selected image. -*`hIconDisabled`*
+*`hIconDisabled`*\ [in] Handle to the icon for the disabled image. -*`hBitmapDisabled`*
+*`hBitmapDisabled`*\ [in] Handle to the bitmap that contains the disabled image. -*`uiBmpDsblResID`*
+*`uiBmpDsblResID`*\ [in] Resource ID of the disabled bitmap. -*`bAlphaBlend`*
+*`bAlphaBlend`*\ [in] `TRUE` to use only 32-bit images that use the alpha channel; `FALSE`, to not use only alpha channel images. The default is `FALSE`. -### Remarks - ## `CMFCButton::SetFaceColor` Sets the background color for the button text. @@ -709,17 +690,17 @@ void SetFaceColor( ### Parameters -*`crFace`*
+*`crFace`*\ [in] An RGB color value. -*`bRedraw`*
+*`bRedraw`*\ [in] `TRUE` to redraw the screen immediately; otherwise, `FALSE`. ### Remarks Use this method to define a new fill color for the button background (face). Note that the background is not filled when the [`CMFCButton::m_bTransparent`](#m_btransparent) member variable is `TRUE`. -## CMFCButton::SetImage +## `CMFCButton::SetImage` Sets the image for a button. @@ -746,44 +727,42 @@ void SetImage( ### Parameters -*`hIcon`*
+*`hIcon`*\ [in] Handle to the icon that contains the bitmap and mask for the new image. -*`bAutoDestroy`*
+*`bAutoDestroy`*\ [in] `TRUE` to specify that bitmap resources be destroyed automatically; otherwise, `FALSE`. The default is `TRUE`. -*`hIconHot`*
+*`hIconHot`*\ [in] Handle to the icon that contains the image for the selected state. -*`hBitmap`*
+*`hBitmap`*\ [in] Handle to the bitmap that contains the image for the non-selected state. -*`hBitmapHot`*
+*`hBitmapHot`*\ [in] Handle to the bitmap that contains the image for the selected state. -*`uiBmpResId`*
+*`uiBmpResId`*\ [in] Resource ID for the non-selected image. -*`uiBmpHotResId`*
+*`uiBmpHotResId`*\ [in] Resource ID for the selected image. -*`bMap3dColors`*
+*`bMap3dColors`*\ [in] Specifies a transparent color for the button background; that is, the face of the button. `TRUE` to use the color value RGB(192, 192, 192); `FALSE` to use the color value defined by `AFX_GLOBAL_DATA::clrBtnFace`. -*`hIconDisabled`*
+*`hIconDisabled`*\ [in] Handle to the icon for the disabled image. -*`hBitmapDisabled`*
+*`hBitmapDisabled`*\ [in] Handle to the bitmap that contains the disabled image. -*`uiBmpDsblResID`*
+*`uiBmpDsblResID`*\ [in] Resource ID of the disabled bitmap. -*`bAlphaBlend`*
+*`bAlphaBlend`*\ [in] `TRUE` to use only 32-bit images that use the alpha channel; `FALSE`, to not use only alpha channel images. The default is `FALSE`. -### Remarks - ### Example The following example demonstrates how to use various versions of the `SetImage` method in the `CMFCButton` class. The example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). @@ -801,7 +780,7 @@ void SetMouseCursor(HCURSOR hcursor); ### Parameters -*`hcursor`*
+*`hcursor`*\ [in] The handle of a cursor. ### Remarks @@ -840,16 +819,14 @@ void SetStdImage( ### Parameters -*`id`*
+*`id`*\ [in] One of the button image identifiers that is defined in the `CMenuImage::IMAGES_IDS` enumeration. The image values specify images such as arrows, pins, and radio buttons. -*`state`*
+*`state`*\ [in] One of the button image state identifiers that is defined in the `CMenuImages::IMAGE_STATE` enumeration. The image states specify button colors such as black, gray, light gray, white, and dark gray. The default value is `CMenuImages::ImageBlack`. -*`idDisabled`*
-[in] One of the button image identifiers that is defined in the `CMenuImage::IMAGES_IDS` enumeration. The image indicates that the button is disabled. The default value is the first button image ( `CMenuImages::IdArrowDown`). - -### Remarks +*`idDisabled`*\ +[in] One of the button image identifiers that is defined in the `CMenuImage::IMAGES_IDS` enumeration. The image indicates that the button is disabled. The default value is the first button image (`CMenuImages::IdArrowDown`). ## `CMFCButton::SetTextColor` @@ -861,11 +838,9 @@ void SetTextColor(COLORREF clrText); ### Parameters -*`clrText`*
+*`clrText`*\ [in] An RGB color value. -### Remarks - ## `CMFCButton::SetTextHotColor` Sets the color of the button text for a button that is selected. @@ -876,11 +851,9 @@ void SetTextHotColor(COLORREF clrTextHot); ### Parameters -*`clrTextHot`*
+*`clrTextHot`*\ [in] An RGB color value. -### Remarks - ## `CMFCButton::SetTooltip` Associates a tooltip with a button. @@ -891,22 +864,20 @@ void SetTooltip(LPCTSTR lpszToolTipText); ### Parameters -*`lpszToolTipText`*
+*`lpszToolTipText`*\ [in] Pointer to the text for the tooltip. Specify `NULL` to disable the tooltip. -### Remarks - ## `CMFCButton::SizeToContent` Resizes a button to contain its button text and image. -``` +```cpp virtual CSize SizeToContent(BOOL bCalcOnly=FALSE); ``` ### Parameters -*`bCalcOnly`*
+*`bCalcOnly`*\ [in] `TRUE` to calculate, but not change, the new size of the button; `FALSE` to change the size of the button. The default is `FALSE`. ### Return Value @@ -919,8 +890,8 @@ By default, this method calculates a new size that includes a horizontal margin ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[`CMFCLinkCtrl` Class](../../mfc/reference/cmfclinkctrl-class.md)
-[`CMFCColorButton` Class](../../mfc/reference/cmfccolorbutton-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMFCLinkCtrl` Class](../../mfc/reference/cmfclinkctrl-class.md)\ +[`CMFCColorButton` Class](../../mfc/reference/cmfccolorbutton-class.md)\ [`CMFCMenuButton` Class](../../mfc/reference/cmfcmenubutton-class.md) diff --git a/docs/mfc/reference/cmfccolorbar-class.md b/docs/mfc/reference/cmfccolorbar-class.md index 56ffd39bac..d24989d33b 100644 --- a/docs/mfc/reference/cmfccolorbar-class.md +++ b/docs/mfc/reference/cmfccolorbar-class.md @@ -78,7 +78,7 @@ class CMFCColorBar : public CMFCPopupMenuBar |`m_bShowDocColorsWhenDocked`|A Boolean that indicates whether to show document colors when the color bar is docked. For more information, see [CMFCColorBar::SetDocumentColors](#setdocumentcolors).| |`m_bStdColorDlg`|A Boolean that indicates whether to show the standard system color dialog box or the [CMFCColorDialog](../../mfc/reference/cmfccolordialog-class.md) dialog box. For more information, see [CMFCColorBar::EnableOtherButton](#enableotherbutton).| |`m_ColorAutomatic`|A [COLORREF](/windows/win32/gdi/colorref) that stores the current automatic color. For more information, see [CMFCColorBar::EnableOtherButton](#enableotherbutton).| -|`m_ColorNames`|An [CMap](../../mfc/reference/cmap-class.md) object that associates a set of RGB colors with their names.| +|`m_ColorNames`|A [CMap](../../mfc/reference/cmap-class.md) object that associates a set of RGB colors with their names.| |`m_colors`|A [CArray](../../mfc/reference/carray-class.md) of [COLORREF](/windows/win32/gdi/colorref) values that contains the colors that are displayed in the color bar control.| |`m_ColorSelected`|A [COLORREF](/windows/win32/gdi/colorref) value that is the color that the user has currently selected from the color bar control.| |`m_lstDocColors`|A [CList](../../mfc/reference/clist-class.md) of [COLORREF](/windows/win32/gdi/colorref) values that contains the colors that are currently used in a document.| diff --git a/docs/mfc/reference/cmfccolorpickerctrl-class.md b/docs/mfc/reference/cmfccolorpickerctrl-class.md index a00150e5a1..dc47c78a25 100644 --- a/docs/mfc/reference/cmfccolorpickerctrl-class.md +++ b/docs/mfc/reference/cmfccolorpickerctrl-class.md @@ -4,7 +4,6 @@ title: "CMFCColorPickerCtrl Class" ms.date: "11/19/2018" f1_keywords: ["CMFCColorPickerCtrl", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::CMFCColorPickerCtrl", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::GetColor", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::GetHLS", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::GetHue", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::GetLuminance", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::GetSaturation", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SelectCellHexagon", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetColor", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetHLS", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetHue", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetLuminance", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetLuminanceBarWidth", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetOriginalColor", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetPalette", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetSaturation", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::SetType", "AFXCOLORPICKERCTRL/CMFCColorPickerCtrl::DrawCursor"] helpviewer_keywords: ["CMFCColorPickerCtrl [MFC], CMFCColorPickerCtrl", "CMFCColorPickerCtrl [MFC], GetColor", "CMFCColorPickerCtrl [MFC], GetHLS", "CMFCColorPickerCtrl [MFC], GetHue", "CMFCColorPickerCtrl [MFC], GetLuminance", "CMFCColorPickerCtrl [MFC], GetSaturation", "CMFCColorPickerCtrl [MFC], SelectCellHexagon", "CMFCColorPickerCtrl [MFC], SetColor", "CMFCColorPickerCtrl [MFC], SetHLS", "CMFCColorPickerCtrl [MFC], SetHue", "CMFCColorPickerCtrl [MFC], SetLuminance", "CMFCColorPickerCtrl [MFC], SetLuminanceBarWidth", "CMFCColorPickerCtrl [MFC], SetOriginalColor", "CMFCColorPickerCtrl [MFC], SetPalette", "CMFCColorPickerCtrl [MFC], SetSaturation", "CMFCColorPickerCtrl [MFC], SetType", "CMFCColorPickerCtrl [MFC], DrawCursor"] -ms.assetid: b9bbd03c-beb0-4b55-9765-9985fd05e5dc --- # CMFCColorPickerCtrl Class @@ -12,7 +11,7 @@ The `CMFCColorPickerCtrl` class provides functionality for a control that is use ## Syntax -``` +```cpp class CMFCColorPickerCtrl : public CButton ``` @@ -22,43 +21,43 @@ class CMFCColorPickerCtrl : public CButton |Name|Description| |----------|-----------------| -|[CMFCColorPickerCtrl::CMFCColorPickerCtrl](#cmfccolorpickerctrl)|Constructs a `CMFCColorPickerCtrl` object.| +|[`CMFCColorPickerCtrl::CMFCColorPickerCtrl`](#cmfccolorpickerctrl)|Constructs a `CMFCColorPickerCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CMFCColorPickerCtrl::GetColor](#getcolor)|Retrieves the color that the user selects.| -|[CMFCColorPickerCtrl::GetHLS](#gethls)|Retrieves the hue, luminance and saturation values of the color that the user selects.| -|[CMFCColorPickerCtrl::GetHue](#gethue)|Retrieves the hue component of the color that the user selects.| -|[CMFCColorPickerCtrl::GetLuminance](#getluminance)|Retrieves the luminance component of the color that the user selects.| -|[CMFCColorPickerCtrl::GetSaturation](#getsaturation)|Retrieves the saturation component of the color that the user selects.| -|[CMFCColorPickerCtrl::SelectCellHexagon](#selectcellhexagon)|Sets the current color to the color defined by the specified RGB color components or the specified cell hexagon.| -|[CMFCColorPickerCtrl::SetColor](#setcolor)|Sets the current color to the specified RGB color value.| -|[CMFCColorPickerCtrl::SetHLS](#sethls)|Sets the current color to the specified HLS color value.| -|[CMFCColorPickerCtrl::SetHue](#sethue)|Changes the hue component of the currently selected color.| -|[CMFCColorPickerCtrl::SetLuminance](#setluminance)|Changes the luminance component of the currently selected color.| -|[CMFCColorPickerCtrl::SetLuminanceBarWidth](#setluminancebarwidth)|Sets the width of the luminance bar in the color picker control.| -|[CMFCColorPickerCtrl::SetOriginalColor](#setoriginalcolor)|Sets the initial selected color.| -|[CMFCColorPickerCtrl::SetPalette](#setpalette)|Sets the current color palette.| -|[CMFCColorPickerCtrl::SetSaturation](#setsaturation)|Changes the saturation component of the currently selected color.| -|[CMFCColorPickerCtrl::SetType](#settype)|Sets the type of color picker control to display.| +|[`CMFCColorPickerCtrl::GetColor`](#getcolor)|Retrieves the color that the user selects.| +|[`CMFCColorPickerCtrl::GetHLS`](#gethls)|Retrieves the hue, luminance and saturation values of the color that the user selects.| +|[`CMFCColorPickerCtrl::GetHue`](#gethue)|Retrieves the hue component of the color that the user selects.| +|[`CMFCColorPickerCtrl::GetLuminance`](#getluminance)|Retrieves the luminance component of the color that the user selects.| +|[`CMFCColorPickerCtrl::GetSaturation`](#getsaturation)|Retrieves the saturation component of the color that the user selects.| +|[`CMFCColorPickerCtrl::SelectCellHexagon`](#selectcellhexagon)|Sets the current color to the color defined by the specified RGB color components or the specified cell hexagon.| +|[`CMFCColorPickerCtrl::SetColor`](#setcolor)|Sets the current color to the specified RGB color value.| +|[`CMFCColorPickerCtrl::SetHLS`](#sethls)|Sets the current color to the specified HLS color value.| +|[`CMFCColorPickerCtrl::SetHue`](#sethue)|Changes the hue component of the currently selected color.| +|[`CMFCColorPickerCtrl::SetLuminance`](#setluminance)|Changes the luminance component of the currently selected color.| +|[`CMFCColorPickerCtrl::SetLuminanceBarWidth`](#setluminancebarwidth)|Sets the width of the luminance bar in the color picker control.| +|[`CMFCColorPickerCtrl::SetOriginalColor`](#setoriginalcolor)|Sets the initial selected color.| +|[`CMFCColorPickerCtrl::SetPalette`](#setpalette)|Sets the current color palette.| +|[`CMFCColorPickerCtrl::SetSaturation`](#setsaturation)|Changes the saturation component of the currently selected color.| +|[`CMFCColorPickerCtrl::SetType`](#settype)|Sets the type of color picker control to display.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CMFCColorPickerCtrl::DrawCursor](#drawcursor)|Called by the framework before a cursor that points to the selected color is displayed.| +|[`CMFCColorPickerCtrl::DrawCursor`](#drawcursor)|Called by the framework before a cursor that points to the selected color is displayed.| ## Remarks -Standard colors are selected from a hexagonal color palette, and custom colors are selected from a luminance bar where colors are specified using either red/green/blue notation or hue/satuaration/luminance notation. +Standard colors are selected from a hexagonal color palette, and custom colors are selected from a luminance bar where colors are specified using either red/green/blue notation or hue/saturation/luminance notation. The following illustration depicts several `CMFCColorPickerCtrl` objects. -![CMFCColorPickerCtrl dialog box.](../../mfc/reference/media/colorpicker.png "CMFCColorPickerCtrl dialog box") +![`CMFCColorPickerCtrl` dialog box.](../../mfc/reference/media/colorpicker.png "CMFCColorPickerCtrl dialog box") -The `CMFCColorPickerCtrl` supports two pairs of styles. The HEX and HEX_GREYSCALE styles are appropriate for standard color selection. The PICKER and LUMINANCE styles are appropriate for custom color selection. +The `CMFCColorPickerCtrl` supports two pairs of styles. The `HEX` and `HEX_GREYSCALE` styles are appropriate for standard color selection. The `PICKER` and `LUMINANCE` styles are appropriate for custom color selection. Perform the following steps to incorporate the `CMFCColorPickerCtrl` control into your dialog box: @@ -68,34 +67,23 @@ Perform the following steps to incorporate the `CMFCColorPickerCtrl` control int 1. Insert the `WM_INITDIALOG` message handler for the dialog box class. In the handler, set the type, palette, and initial selected color of the `CMFCColorPickerCtrl` control. -## Example - -The following example demonstrates how to configure a `CMFCColorPickerCtrl` object by using various methods in the `CMFCColorPickerCtrl` class. The example demonstrates how to set the type of the picker control, and how to set its color, hue, luminance, and saturation. The example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). - -[!code-cpp[NVC_MFC_NewControls#4](../../mfc/reference/codesnippet/cpp/cmfccolorpickerctrl-class_1.h)] -[!code-cpp[NVC_MFC_NewControls#5](../../mfc/reference/codesnippet/cpp/cmfccolorpickerctrl-class_2.cpp)] - ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) - -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) - -[CWnd](../../mfc/reference/cwnd-class.md) - -[CButton](../../mfc/reference/cbutton-class.md) - -[CMFCColorPickerCtrl](../../mfc/reference/cmfccolorpickerctrl-class.md) +[`CObject`](../../mfc/reference/cobject-class.md)\ +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md)\ +[`CWnd`](../../mfc/reference/cwnd-class.md)\ +[`CButton`](../../mfc/reference/cbutton-class.md)\ +[`CMFCColorPickerCtrl`](../../mfc/reference/cmfccolorpickerctrl-class.md) ## Requirements -**Header:** afxcolorpickerctrl.h +**Header:** `afxcolorpickerctrl.h` ## CMFCColorPickerCtrl::CMFCColorPickerCtrl Constructs a `CMFCColorPickerCtrl` object. -``` +```cpp CMFCColorPickerCtrl(); ``` @@ -103,11 +91,11 @@ CMFCColorPickerCtrl(); ### Remarks -## CMFCColorPickerCtrl::DrawCursor +## `CMFCColorPickerCtrl::DrawCursor` Called by the framework before a cursor that points to the selected color is displayed. -``` +```cpp virtual void DrawCursor( CDC* pDC, const CRect& rect); @@ -115,21 +103,21 @@ virtual void DrawCursor( ### Parameters -*pDC*
+`pDC`\ [in] Pointer to a device context. -*rect*
+`rect`\ [in] Specifies a rectangular area around the selected color. ### Remarks Override this method when you need to change the shape of the cursor that points to the selected color. -## CMFCColorPickerCtrl::GetColor +## `CMFCColorPickerCtrl::GetColor` Retrieves the color that the user selects. -``` +```cpp COLORREF GetColor() const; ``` @@ -139,7 +127,7 @@ The RGB value of the selected color. ### Remarks -## CMFCColorPickerCtrl::GetHLS +## `CMFCColorPickerCtrl::GetHLS` Retrieves the hue, luminance and saturation values of the color that the user selects. @@ -152,22 +140,22 @@ void GetHLS( ### Parameters -*hue*
+`hue`\ [out] Pointer to a variable of type double that receives hue information. -*luminance*
+`luminance`\ [out] Pointer to a variable of type double that receives luminance information. -*saturation*
+`saturation`\ [out] Pointer to a variable of type double that receives saturation information. ### Remarks -## CMFCColorPickerCtrl::GetHue +## `CMFCColorPickerCtrl::GetHue` Retrieves the hue component of the color that the user selects. -``` +```cpp double GetHue() const; ``` @@ -177,11 +165,11 @@ The hue component of the selected color. ### Remarks -## CMFCColorPickerCtrl::GetLuminance +## `CMFCColorPickerCtrl::GetLuminance` Retrieves the luminance component of the color that the user selects. -``` +```cpp double GetLuminance() const; ``` @@ -191,11 +179,11 @@ The luminance component of the selected color. ### Remarks -## CMFCColorPickerCtrl::GetSaturation +## `CMFCColorPickerCtrl::GetSaturation` Retrieves the saturation value of the color that the user selects. -``` +```cpp double GetSaturation() const; ``` @@ -205,7 +193,7 @@ The saturation component of the selected color. ### Remarks -## CMFCColorPickerCtrl::SelectCellHexagon +## `CMFCColorPickerCtrl::SelectCellHexagon` Sets the current color to the color defined by the specified RGB color components or the specified cell hexagon. @@ -222,19 +210,19 @@ BOOL SelectCellHexagon( ### Parameters -*R*
+`R`\ [in] The red color component. -*G*
+`G`\ [in] The green color component. -*B*
+`B`\ [in] The blue color component. -*x*
+`x`\ [in] The x-coordinate of the cursor, which points to a cell hexagon. -*y*
+`y`\ [in] The y-coordinate of the cursor, which points to a cell hexagon. ### Return Value @@ -247,7 +235,7 @@ The first overload of this method sets the current color to the color that corre The second overload of this method sets the current color to the color of the cell hexagon that is pointed to by the specified cursor location. -## CMFCColorPickerCtrl::SetColor +## `CMFCColorPickerCtrl::SetColor` Sets the current color to the specified RGB color value. @@ -257,12 +245,12 @@ void SetColor(COLORREF Color); ### Parameters -*Color*
+`Color`\ [in] An RGB color value. ### Remarks -## CMFCColorPickerCtrl::SetHLS +## `CMFCColorPickerCtrl::SetHLS` Sets the current color to the specified HLS color value. @@ -276,21 +264,21 @@ void SetHLS( ### Parameters -*hue*
+`hue`\ [in] A hue value. -*luminance*
+`luminance`\ [in] A luminance value. -*saturation*
+`saturation`\ [in] A saturation value. -*bInvalidate*
-[in] TRUE to force the window to immediately update to the new color; otherwise, FALSE. The default is TRUE. +`bInvalidate`\ +[in] `TRUE` to force the window to immediately update to the new color; otherwise, `FALSE`. The default is `TRUE`. ### Remarks -## CMFCColorPickerCtrl::SetHue +## `CMFCColorPickerCtrl::SetHue` Changes the hue of the currently selected color. @@ -300,12 +288,12 @@ void SetHue(double Hue); ### Parameters -*Hue*
+`Hue`\ [in] A hue value. ### Remarks -## CMFCColorPickerCtrl::SetLuminance +## `CMFCColorPickerCtrl::SetLuminance` Changes the luminance of the currently selected color. @@ -315,12 +303,12 @@ void SetLuminance(double Luminance); ### Parameters -*Luminance*
+`Luminance`\ [in] A luminance value. ### Remarks -## CMFCColorPickerCtrl::SetLuminanceBarWidth +## `CMFCColorPickerCtrl::SetLuminanceBarWidth` Sets the width of the luminance bar in the color picker control. @@ -330,14 +318,14 @@ void SetLuminanceBarWidth(int w); ### Parameters -*w*
+`w`\ [in] The width of the luminance bar measured in pixels. ### Remarks -Use this method to resize the luminance bar, which is on the **Custom** tab of the color picker control. The *w* parameter specifies the new width of the luminance bar. The width value is ignored if it exceeds three-fourths of the client area width. +Use this method to resize the luminance bar, which is on the **Custom** tab of the color picker control. The `w` parameter specifies the new width of the luminance bar. The width value is ignored if it exceeds three-fourths of the client area width. -## CMFCColorPickerCtrl::SetOriginalColor +## `CMFCColorPickerCtrl::SetOriginalColor` Sets the initial selected color. @@ -347,14 +335,14 @@ void SetOriginalColor(COLORREF ref); ### Parameters -*ref*
+`ref`\ [in] An RGB color value. ### Remarks Call this method when the color picker control is initialized. -## CMFCColorPickerCtrl::SetPalette +## `CMFCColorPickerCtrl::SetPalette` Sets the current color palette. @@ -364,14 +352,14 @@ void SetPalette(CPalette* pPalette); ### Parameters -*pPalette*
+`pPalette`\ [in] Pointer to a color palette. ### Remarks The color palette defines the array of colors that is presented in the color picker control. -## CMFCColorPickerCtrl::SetSaturation +## `CMFCColorPickerCtrl::SetSaturation` Changes the saturation of the currently selected color. @@ -381,12 +369,12 @@ void SetSaturation(double Saturation); ### Parameters -*Saturation*
-[in] A saturation value. +`Saturation`\ +[`in`] A saturation value. ### Remarks -## CMFCColorPickerCtrl::SetType +## `CMFCColorPickerCtrl::SetType` Sets the type of color picker control to display. @@ -396,10 +384,10 @@ void SetType(COLORTYPE colorType); ### Parameters -*colorType*
+`colorType`\ [in] A color picker control type. -The types are defined by the `CMFCColorPickerCtrl::COLORTYPE` enumeration. The possible types are LUMINANCE, PICKER, HEX and HEX_GREYSCALE. The default type is PICKER. +The types are defined by the `CMFCColorPickerCtrl::COLORTYPE` enumeration. The possible types are `LUMINANCE`, `PICKER`, `HEX` and `HEX_GREYSCALE`. The default type is `PICKER`. ### Remarks @@ -407,6 +395,6 @@ To specify a color picker control type, call this method before the Windows cont ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCColorDialog Class](../../mfc/reference/cmfccolordialog-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMFCColorDialog` Class](../../mfc/reference/cmfccolordialog-class.md) diff --git a/docs/mfc/reference/cmfcdynamiclayout-class.md b/docs/mfc/reference/cmfcdynamiclayout-class.md index 0c8f47f3f0..c41f1893c7 100644 --- a/docs/mfc/reference/cmfcdynamiclayout-class.md +++ b/docs/mfc/reference/cmfcdynamiclayout-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: CMFCDynamicLayout Class" title: "CMFCDynamicLayout Class" +description: "Learn more about: CMFCDynamicLayout Class" ms.date: "08/29/2019" f1_keywords: ["CMFCDynamicLayout", "AFXLAYOUT/CMFCDynamicLayout", "AFXLAYOUT/CMFCDynamicLayout::AddItem", "AFXLAYOUT/CMFCDynamicLayout::Adjust", "AFXLAYOUT/CMFCDynamicLayout::Create", "AFXLAYOUT/CMFCDynamicLayout::GetHostWnd", "AFXLAYOUT/CMFCDynamicLayout::GetMinSize", "AFXLAYOUT/CMFCDynamicLayout::GetWindowRect", "AFXLAYOUT/CMFCDynamicLayout::HasItem", "AFXLAYOUT/CMFCDynamicLayout::IsEmpty", "AFXLAYOUT/CMFCDynamicLayout::LoadResource", "AFXLAYOUT/CMFCDynamicLayout::SetMinSize"] -ms.assetid: c2df2976-f049-47fc-9cf0-abe3e01948bc --- # CMFCDynamicLayout Class @@ -170,7 +169,7 @@ The position and size of a child control is changed dynamically when a hosting w Retrieves the rectangle for the window's current client area. ```cpp -void GetHostWndRect(CRect& rect,); +void GetHostWndRect(CRect& rect); ``` ### Parameters @@ -503,5 +502,5 @@ A [SizeSettings](#sizesettings_structure) value that encapsulates the requested ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Classes](../../mfc/reference/mfc-classes.md) diff --git a/docs/mfc/reference/cmfceditbrowsectrl-class.md b/docs/mfc/reference/cmfceditbrowsectrl-class.md index 4026be004c..c24728b72e 100644 --- a/docs/mfc/reference/cmfceditbrowsectrl-class.md +++ b/docs/mfc/reference/cmfceditbrowsectrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCEditBrowseCtrl Class" title: "CMFCEditBrowseCtrl Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCEditBrowseCtrl Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCEditBrowseCtrl", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::EnableBrowseButton", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::EnableFileBrowseButton", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::EnableFolderBrowseButton", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::GetMode", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::OnAfterUpdate", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::OnBrowse", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::OnChangeLayout", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::OnDrawBrowseButton", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::OnIllegalFileName", "AFXEDITBROWSECTRL/CMFCEditBrowseCtrl::SetBrowseButtonImage"] helpviewer_keywords: ["CMFCEditBrowseCtrl [MFC], EnableBrowseButton", "CMFCEditBrowseCtrl [MFC], EnableFileBrowseButton", "CMFCEditBrowseCtrl [MFC], EnableFolderBrowseButton", "CMFCEditBrowseCtrl [MFC], GetMode", "CMFCEditBrowseCtrl [MFC], OnAfterUpdate", "CMFCEditBrowseCtrl [MFC], OnBrowse", "CMFCEditBrowseCtrl [MFC], OnChangeLayout", "CMFCEditBrowseCtrl [MFC], OnDrawBrowseButton", "CMFCEditBrowseCtrl [MFC], OnIllegalFileName", "CMFCEditBrowseCtrl [MFC], SetBrowseButtonImage"] -ms.assetid: 69cfd886-3d35-4bee-8901-7c88fcf9520f --- # CMFCEditBrowseCtrl Class @@ -69,7 +68,7 @@ Perform the following steps to incorporate an edit browse control in your applic 1. Embed either the `CMFCEditBrowseCtrl` object or the derived edit browse control object into the parent window object. -1. If you use the **Class Wizard** to create a dialog box, add an edit control ( `CEdit`) to the dialog box form. Also, add a variable to access the control in your header file. In your header file, change the type of the variable from `CEdit` to `CMFCEditBrowseCtrl`. The edit browse control will be created automatically. If you do not use the **Class Wizard**, add a `CMFCEditBrowseCtrl` variable to your header file and then call its `Create` method. +1. If you use the **Class Wizard** to create a dialog box, add an edit control (`CEdit`) to the dialog box form. Also, add a variable to access the control in your header file. In your header file, change the type of the variable from `CEdit` to `CMFCEditBrowseCtrl`. The edit browse control will be created automatically. If you do not use the **Class Wizard**, add a `CMFCEditBrowseCtrl` variable to your header file and then call its `Create` method. 1. If you add an edit browse control to a dialog box, use the **ClassWizard** tool to set up data exchange. @@ -306,7 +305,7 @@ Specifies the illegal file name. ### Return Value -Should return FALSE if this file name can not be passed further to the file dialog. In this case, focus is set back to the edit control and the user should continue editing. The default implementation displays a message box telling the user about the illegal file name and returns FALSE. You can override this method, correct the file name, and return TRUE for further processing. +Should return FALSE if this file name cannot be passed further to the file dialog. In this case, focus is set back to the edit control and the user should continue editing. The default implementation displays a message box telling the user about the illegal file name and returns FALSE. You can override this method, correct the file name, and return TRUE for further processing. ### Remarks diff --git a/docs/mfc/reference/cmfclistctrl-class.md b/docs/mfc/reference/cmfclistctrl-class.md index a1d657fd01..2ac870b846 100644 --- a/docs/mfc/reference/cmfclistctrl-class.md +++ b/docs/mfc/reference/cmfclistctrl-class.md @@ -4,11 +4,10 @@ title: "CMFCListCtrl Class" ms.date: "07/30/2019" f1_keywords: ["CMFCListCtrl", "AFXLISTCTRL/CMFCListCtrl", "AFXLISTCTRL/CMFCListCtrl::EnableMarkSortedColumn", "AFXLISTCTRL/CMFCListCtrl::EnableMultipleSort", "AFXLISTCTRL/CMFCListCtrl::GetHeaderCtrl", "AFXLISTCTRL/CMFCListCtrl::IsMultipleSort", "AFXLISTCTRL/CMFCListCtrl::OnCompareItems", "AFXLISTCTRL/CMFCListCtrl::OnGetCellBkColor", "AFXLISTCTRL/CMFCListCtrl::OnGetCellFont", "AFXLISTCTRL/CMFCListCtrl::OnGetCellTextColor", "AFXLISTCTRL/CMFCListCtrl::RemoveSortColumn", "AFXLISTCTRL/CMFCListCtrl::SetSortColumn", "AFXLISTCTRL/CMFCListCtrl::Sort"] helpviewer_keywords: ["CMFCListCtrl [MFC], EnableMarkSortedColumn", "CMFCListCtrl [MFC], EnableMultipleSort", "CMFCListCtrl [MFC], GetHeaderCtrl", "CMFCListCtrl [MFC], IsMultipleSort", "CMFCListCtrl [MFC], OnCompareItems", "CMFCListCtrl [MFC], OnGetCellBkColor", "CMFCListCtrl [MFC], OnGetCellFont", "CMFCListCtrl [MFC], OnGetCellTextColor", "CMFCListCtrl [MFC], RemoveSortColumn", "CMFCListCtrl [MFC], SetSortColumn", "CMFCListCtrl [MFC], Sort"] -ms.assetid: 50d16aee-138c-4f34-8690-cb75d544ef2e --- -# CMFCListCtrl Class +# `CMFCListCtrl` Class -The `CMFCListCtrl` class extends the functionality of [CListCtrl Class](../../mfc/reference/clistctrl-class.md) class by supporting the advanced header control functionality of the [CMFCHeaderCtrl Class](../../mfc/reference/cmfcheaderctrl-class.md). +The `CMFCListCtrl` class extends the functionality of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md). ## Syntax @@ -22,21 +21,21 @@ class CMFCListCtrl : public CListCtrl |Name|Description| |----------|-----------------| -|[CMFCListCtrl::EnableMarkSortedColumn](#enablemarksortedcolumn)|Enables the ability to mark a sorted column with a different background color.| -|[CMFCListCtrl::EnableMultipleSort](#enablemultiplesort)|Enables multiple sort mode.| -|[CMFCListCtrl::GetHeaderCtrl](#getheaderctrl)|Returns a reference to the underlined header control.| -|[CMFCListCtrl::IsMultipleSort](#ismultiplesort)|Checks if the list control is in multiple sort mode.| -|[CMFCListCtrl::OnCompareItems](#oncompareitems)|Called by the framework when it must compare two list control items.| -|[CMFCListCtrl::OnGetCellBkColor](#ongetcellbkcolor)|Called by the framework when it must determine the background color of an individual cell.| -|[CMFCListCtrl::OnGetCellFont](#ongetcellfont)|Called by the framework when it must obtain the font for the cell being drawn.| -|[CMFCListCtrl::OnGetCellTextColor](#ongetcelltextcolor)|Called by the framework when it must determine the text color of an individual cell.| -|[CMFCListCtrl::RemoveSortColumn](#removesortcolumn)|Removes a sort column from the list of sorted columns.| -|[CMFCListCtrl::SetSortColumn](#setsortcolumn)|Sets the current sorted column and the sort order.| -|[CMFCListCtrl::Sort](#sort)|Sorts the list control.| +|[`CMFCListCtrl::EnableMarkSortedColumn`](#enablemarksortedcolumn)|Enables the ability to mark a sorted column with a different background color.| +|[`CMFCListCtrl::EnableMultipleSort`](#enablemultiplesort)|Enables multiple sort mode.| +|[`CMFCListCtrl::GetHeaderCtrl`](#getheaderctrl)|Returns a reference to the underlined header control.| +|[`CMFCListCtrl::IsMultipleSort`](#ismultiplesort)|Checks if the list control is in multiple sort mode.| +|[`CMFCListCtrl::OnCompareItems`](#oncompareitems)|Called by the framework when it must compare two list control items.| +|[`CMFCListCtrl::OnGetCellBkColor`](#ongetcellbkcolor)|Called by the framework when it must determine the background color of an individual cell.| +|[`CMFCListCtrl::OnGetCellFont`](#ongetcellfont)|Called by the framework when it must obtain the font for the cell being drawn.| +|[`CMFCListCtrl::OnGetCellTextColor`](#ongetcelltextcolor)|Called by the framework when it must determine the text color of an individual cell.| +|[`CMFCListCtrl::RemoveSortColumn`](#removesortcolumn)|Removes a sort column from the list of sorted columns.| +|[`CMFCListCtrl::SetSortColumn`](#setsortcolumn)|Sets the current sorted column and the sort order.| +|[`CMFCListCtrl::Sort`](#sort)|Sorts the list control.| ## Remarks -`CMFCListCtrl` offers two enhancements to [CListCtrl Class](../../mfc/reference/clistctrl-class.md) class. First, it indicates that column sorting is an available option by automatically drawing a sort arrow on the header. Second, it supports data sorting on multiple columns at the same time. +`CMFCListCtrl` offers two enhancements to [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) class. First, it indicates that column sorting is an available option by automatically drawing a sort arrow on the header. Second, it supports data sorting on multiple columns at the same time. ## Example @@ -47,21 +46,21 @@ The following example demonstrates how to use various methods in the `CMFCListCt ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CListCtrl](../../mfc/reference/clistctrl-class.md) +[`CListCtrl`](../../mfc/reference/clistctrl-class.md) -[CMFCListCtrl](../../mfc/reference/cmfclistctrl-class.md) +[`CMFCListCtrl`](../../mfc/reference/cmfclistctrl-class.md) ## Requirements -**Header:** afxlistctrl.h +**Header:** `afxlistctrl.h` -## CMFCListCtrl::EnableMarkSortedColumn +## `CMFCListCtrl::EnableMarkSortedColumn` Marks the sorted columns with a different background color. @@ -73,17 +72,17 @@ void EnableMarkSortedColumn( ### Parameters -*bMark*
+*`bMark`*\ [in] A Boolean parameter that determines whether to enable a different background color. -*bRedraw*
+*`bRedraw`*\ [in] A Boolean parameter that determines whether to redraw the control immediately. ### Remarks `EnableMarkSortedColumn` uses the method `CDrawingManager::PixelAlpha` to calculate what color to use for sorted columns. The color picked is based upon the regular background color. -## CMFCListCtrl::EnableMultipleSort +## `CMFCListCtrl::EnableMultipleSort` Enables sorting the rows of data in the list control by multiple columns. @@ -93,14 +92,14 @@ void EnableMultipleSort(BOOL bEnable = TRUE); ### Parameters -*bEnable*
+*`bEnable`*\ [in] A Boolean that specifies whether to enable multiple column sort mode. ### Remarks When you enable sorting based on multiple columns, the columns do have a hierarchy. The rows of data will first be sorted by the primary column. Any equivalent values are then sorted by each subsequent column based on priority. -## CMFCListCtrl::GetHeaderCtrl +## `CMFCListCtrl::GetHeaderCtrl` Returns a reference to the header control. @@ -110,13 +109,13 @@ virtual CMFCHeaderCtrl& GetHeaderCtrl(); ### Return Value -A reference to the underlying [CMFCHeaderCtrl](../../mfc/reference/cmfcheaderctrl-class.md) object. +A reference to the underlying [`CMFCHeaderCtrl`](../../mfc/reference/cmfcheaderctrl-class.md) object. ### Remarks The header control for a list control is the window that contains the titles for the columns. It's usually positioned directly above the columns. -## CMFCListCtrl::IsMultipleSort +## `CMFCListCtrl::IsMultipleSort` Checks whether the list control currently supports sorting on multiple columns. @@ -126,13 +125,13 @@ BOOL IsMultipleSort() const; ### Return Value -TRUE if the list control supports multiple sort; FALSE otherwise. +`TRUE` if the list control supports multiple sort; `FALSE` otherwise. ### Remarks -When a [CMFCListCtrl Class](../../mfc/reference/cmfclistctrl-class.md) supports multiple sorting, the user can sort the data in the list control by multiple columns. To enable multiple sorting, call [CMFCListCtrl::EnableMultipleSort](#enablemultiplesort). +When a [`CMFCListCtrl` Class](../../mfc/reference/cmfclistctrl-class.md) supports multiple sorting, the user can sort the data in the list control by multiple columns. To enable multiple sorting, call [`CMFCListCtrl::EnableMultipleSort`](#enablemultiplesort). -## CMFCListCtrl::OnCompareItems +## `CMFCListCtrl::OnCompareItems` The framework calls this method when it compares two items. @@ -145,13 +144,13 @@ virtual int OnCompareItems( ### Parameters -*lParam1*
+*`lParam1`*\ [in] The first item to compare. -*lParam2*
+*`lParam2`*\ [in] The second item to compare. -*iColumn*
+*`iColumn`*\ [in] The index of the column that this method is sorting. ### Return Value @@ -162,7 +161,7 @@ An integer that indicates the relative position of the two items. A negative val The default implementation always returns 0. Override this function to provide your own sorting algorithm. -## CMFCListCtrl::OnGetCellBkColor +## `CMFCListCtrl::OnGetCellBkColor` The framework calls this method when it must determine the background color of an individual cell. @@ -174,21 +173,21 @@ virtual COLORREF OnGetCellBkColor( ### Parameters -*nRow*
+*`nRow`*\ [in] The row of the cell in question. -*nColumn*
+*`nColumn`*\ [in] The column of the cell in question. ### Return Value -A COLOREF value that specifies the background color of the cell. +A `COLOREF` value that specifies the background color of the cell. ### Remarks -The default implementation of `OnGetCellBkColor` does not use the supplied input parameters and instead simply calls `GetBkColor`. Therefore, by default, the whole list control will have the same background color. You can override `OnGetCellBkColor` in a derived class to mark individual cells with a separate background color. +The default implementation of `OnGetCellBkColor` doesn't use the supplied input parameters and instead simply calls `GetBkColor`. Therefore, by default, the whole list control will have the same background color. You can override `OnGetCellBkColor` in a derived class to mark individual cells with a separate background color. -## CMFCListCtrl::OnGetCellFont +## `CMFCListCtrl::OnGetCellFont` The framework calls this method when it obtains the font for an individual cell. @@ -201,13 +200,13 @@ virtual HFONT OnGetCellFont( ### Parameters -*nRow*
+*`nRow`*\ [in] The row of the cell in question. -*nColumn*
+*`nColumn`*\ [in] The column of the cell in question. -*dwData*
+*`dwData`*\ [in] User-defined data. The default implementation doesn't use this parameter. ### Return Value @@ -216,9 +215,9 @@ A handle to the font that is used for the current cell. ### Remarks -By default, this method returns NULL. All of the cells in a list control have the same font. Override this method to provide different fonts for different cells. +By default, this method returns `NULL`. All of the cells in a list control have the same font. Override this method to provide different fonts for different cells. -## CMFCListCtrl::OnGetCellTextColor +## `CMFCListCtrl::OnGetCellTextColor` The framework calls this method when it must determine the text color of an individual cell. @@ -230,21 +229,21 @@ virtual COLORREF OnGetCellTextColor( ### Parameters -*nRow*
+*`nRow`*\ [in] The row of the cell in question. -*nColumn*
+*`nColumn`*\ [in] The column of the cell in question. ### Return Value -A COLOREF value that specifies the text color of the cell. +A `COLOREF` value that specifies the text color of the cell. ### Remarks By default, this method calls `GetTextColor` regardless of input parameters. The whole list control will have the same text color. You can override `OnGetCellTextColor` in a derived class to mark individual cells with a separate text color. -## CMFCListCtrl::RemoveSortColumn +## `CMFCListCtrl::RemoveSortColumn` Removes a sort column from the list of sorted columns. @@ -254,14 +253,14 @@ void RemoveSortColumn(int iColumn); ### Parameters -*iColumn*
+*`iColumn`*\ [in] The column to remove. ### Remarks -This method removes a sort column from the header control. It calls [CMFCHeaderCtrl::RemoveSortColumn](../../mfc/reference/cmfcheaderctrl-class.md#removesortcolumn). +This method removes a sort column from the header control. It calls [`CMFCHeaderCtrl::RemoveSortColumn`](../../mfc/reference/cmfcheaderctrl-class.md#removesortcolumn). -## CMFCListCtrl::SetSortColumn +## `CMFCListCtrl::SetSortColumn` Sets the current sorted column and the sort order. @@ -274,20 +273,20 @@ void SetSortColumn( ### Parameters -*iColumn*
+*`iColumn`*\ [in] The column to sort. -*bAscending*
+*`bAscending`*\ [in] A Boolean that specifies the sort order. -*bAdd*
-[in] A Boolean that specifies whether the method adds the column indicated by *iColumn* to the list of sort columns. +*`bAdd`*\ +[in] A Boolean that specifies whether the method adds the column indicated by *`iColumn`* to the list of sort columns. ### Remarks -This method passes the input parameters to the header control by using the method [CMFCHeaderCtrl::SetSortColumn](../../mfc/reference/cmfcheaderctrl-class.md#setsortcolumn). +This method passes the input parameters to the header control by using the method [`CMFCHeaderCtrl::SetSortColumn`](../../mfc/reference/cmfcheaderctrl-class.md#setsortcolumn). -## CMFCListCtrl::Sort +## `CMFCListCtrl::Sort` Sorts the list control. @@ -300,17 +299,17 @@ virtual void Sort( ### Parameters -*iColumn*
+*`iColumn`*\ [in] The column to sort. -*bAscending*
+*`bAscending`*\ [in] A Boolean that specifies the sort order. -*bAdd*
-[in] A Boolean that specifies whether this method adds the column indicated by *iColumn* to the list of sort columns. +*`bAdd`*\ +[in] A Boolean that specifies whether this method adds the column indicated by *`iColumn`* to the list of sort columns. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CListCtrl Class](../../mfc/reference/clistctrl-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) diff --git a/docs/mfc/reference/cmfcmenubar-class.md b/docs/mfc/reference/cmfcmenubar-class.md index b541ec3c64..8b8174252b 100644 --- a/docs/mfc/reference/cmfcmenubar-class.md +++ b/docs/mfc/reference/cmfcmenubar-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCMenuBar Class" title: "CMFCMenuBar Class" +description: "Learn more about: CMFCMenuBar Class" ms.date: "10/18/2018" f1_keywords: ["CMFCMenuBar", "AFXMENUBAR/CMFCMenuBar", "AFXMENUBAR/CMFCMenuBar::AdjustLocations", "AFXMENUBAR/CMFCMenuBar::AllowChangeTextLabels", "AFXMENUBAR/CMFCMenuBar::AllowShowOnPaneMenu", "AFXMENUBAR/CMFCMenuBar::CalcFixedLayout", "AFXMENUBAR/CMFCMenuBar::CalcLayout", "AFXMENUBAR/CMFCMenuBar::CalcMaxButtonHeight", "AFXMENUBAR/CMFCMenuBar::CanBeClosed", "AFXMENUBAR/CMFCMenuBar::CanBeRestored", "AFXMENUBAR/CMFCMenuBar::Create", "AFXMENUBAR/CMFCMenuBar::CreateEx", "AFXMENUBAR/CMFCMenuBar::CreateFromMenu", "AFXMENUBAR/CMFCMenuBar::EnableHelpCombobox", "AFXMENUBAR/CMFCMenuBar::EnableMenuShadows", "AFXMENUBAR/CMFCMenuBar::GetAvailableExpandSize", "AFXMENUBAR/CMFCMenuBar::GetColumnWidth", "AFXMENUBAR/CMFCMenuBar::GetDefaultMenu", "AFXMENUBAR/CMFCMenuBar::GetDefaultMenuResId", "AFXMENUBAR/CMFCMenuBar::GetFloatPopupDirection", "AFXMENUBAR/CMFCMenuBar::GetForceDownArrows", "AFXMENUBAR/CMFCMenuBar::GetHelpCombobox", "AFXMENUBAR/CMFCMenuBar::GetHMenu", "AFXMENUBAR/CMFCMenuBar::GetMenuFont", "AFXMENUBAR/CMFCMenuBar::GetMenuItem", "AFXMENUBAR/CMFCMenuBar::GetRowHeight", "AFXMENUBAR/CMFCMenuBar::GetSystemButton", "AFXMENUBAR/CMFCMenuBar::GetSystemButtonsCount", "AFXMENUBAR/CMFCMenuBar::GetSystemMenu", "AFXMENUBAR/CMFCMenuBar::HighlightDisabledItems", "AFXMENUBAR/CMFCMenuBar::IsButtonExtraSizeAvailable", "AFXMENUBAR/CMFCMenuBar::IsHighlightDisabledItems", "AFXMENUBAR/CMFCMenuBar::IsMenuShadows", "AFXMENUBAR/CMFCMenuBar::IsRecentlyUsedMenus", "AFXMENUBAR/CMFCMenuBar::IsShowAllCommands", "AFXMENUBAR/CMFCMenuBar::IsShowAllCommandsDelay", "AFXMENUBAR/CMFCMenuBar::LoadState", "AFXMENUBAR/CMFCMenuBar::OnChangeHot", "AFXMENUBAR/CMFCMenuBar::OnDefaultMenuLoaded", "AFXMENUBAR/CMFCMenuBar::OnSendCommand", "AFXMENUBAR/CMFCMenuBar::OnSetDefaultButtonText", "AFXMENUBAR/CMFCMenuBar::OnToolHitTest", "AFXMENUBAR/CMFCMenuBar::PreTranslateMessage", "AFXMENUBAR/CMFCMenuBar::RestoreOriginalstate", "AFXMENUBAR/CMFCMenuBar::SaveState", "AFXMENUBAR/CMFCMenuBar::SetDefaultMenuResId", "AFXMENUBAR/CMFCMenuBar::SetForceDownArrows", "AFXMENUBAR/CMFCMenuBar::SetMaximizeMode", "AFXMENUBAR/CMFCMenuBar::SetMenuButtonRTC", "AFXMENUBAR/CMFCMenuBar::SetMenuFont", "AFXMENUBAR/CMFCMenuBar::SetRecentlyUsedMenus", "AFXMENUBAR/CMFCMenuBar::SetShowAllCommands"] helpviewer_keywords: ["CMFCMenuBar [MFC], AdjustLocations", "CMFCMenuBar [MFC], AllowChangeTextLabels", "CMFCMenuBar [MFC], AllowShowOnPaneMenu", "CMFCMenuBar [MFC], CalcFixedLayout", "CMFCMenuBar [MFC], CalcLayout", "CMFCMenuBar [MFC], CalcMaxButtonHeight", "CMFCMenuBar [MFC], CanBeClosed", "CMFCMenuBar [MFC], CanBeRestored", "CMFCMenuBar [MFC], Create", "CMFCMenuBar [MFC], CreateEx", "CMFCMenuBar [MFC], CreateFromMenu", "CMFCMenuBar [MFC], EnableHelpCombobox", "CMFCMenuBar [MFC], EnableMenuShadows", "CMFCMenuBar [MFC], GetAvailableExpandSize", "CMFCMenuBar [MFC], GetColumnWidth", "CMFCMenuBar [MFC], GetDefaultMenu", "CMFCMenuBar [MFC], GetDefaultMenuResId", "CMFCMenuBar [MFC], GetFloatPopupDirection", "CMFCMenuBar [MFC], GetForceDownArrows", "CMFCMenuBar [MFC], GetHelpCombobox", "CMFCMenuBar [MFC], GetHMenu", "CMFCMenuBar [MFC], GetMenuFont", "CMFCMenuBar [MFC], GetMenuItem", "CMFCMenuBar [MFC], GetRowHeight", "CMFCMenuBar [MFC], GetSystemButton", "CMFCMenuBar [MFC], GetSystemButtonsCount", "CMFCMenuBar [MFC], GetSystemMenu", "CMFCMenuBar [MFC], HighlightDisabledItems", "CMFCMenuBar [MFC], IsButtonExtraSizeAvailable", "CMFCMenuBar [MFC], IsHighlightDisabledItems", "CMFCMenuBar [MFC], IsMenuShadows", "CMFCMenuBar [MFC], IsRecentlyUsedMenus", "CMFCMenuBar [MFC], IsShowAllCommands", "CMFCMenuBar [MFC], IsShowAllCommandsDelay", "CMFCMenuBar [MFC], LoadState", "CMFCMenuBar [MFC], OnChangeHot", "CMFCMenuBar [MFC], OnDefaultMenuLoaded", "CMFCMenuBar [MFC], OnSendCommand", "CMFCMenuBar [MFC], OnSetDefaultButtonText", "CMFCMenuBar [MFC], OnToolHitTest", "CMFCMenuBar [MFC], PreTranslateMessage", "CMFCMenuBar [MFC], RestoreOriginalstate", "CMFCMenuBar [MFC], SaveState", "CMFCMenuBar [MFC], SetDefaultMenuResId", "CMFCMenuBar [MFC], SetForceDownArrows", "CMFCMenuBar [MFC], SetMaximizeMode", "CMFCMenuBar [MFC], SetMenuButtonRTC", "CMFCMenuBar [MFC], SetMenuFont", "CMFCMenuBar [MFC], SetRecentlyUsedMenus", "CMFCMenuBar [MFC], SetShowAllCommands"] -ms.assetid: 8a3ce4c7-b012-4dc0-b4f8-53c10b4b86b8 --- # CMFCMenuBar Class @@ -663,7 +662,7 @@ When you configure a menu bar to display recently used items, the menu bar displ - Display the full menu after the user clicks the arrow at the bottom of the menu. -By default, all `CMFCMenuBar` objects use the option to display the full menu after a short delay. This option cannot be changed programmatically in the `CMFCMenuBar` class. However, a user can change the behavior during toolbar customization by using the **Customize** dialog box.. +By default, all `CMFCMenuBar` objects use the option to display the full menu after a short delay. This option cannot be changed programmatically in the `CMFCMenuBar` class. However, a user can change the behavior during toolbar customization by using the **Customize** dialog box. ## CMFCMenuBar::LoadState @@ -977,6 +976,6 @@ If a menu does not display all the menu commands, it hides the commands that are ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ [CMFCToolBar Class](../../mfc/reference/cmfctoolbar-class.md) diff --git a/docs/mfc/reference/cmfcpreviewctrlimpl-class.md b/docs/mfc/reference/cmfcpreviewctrlimpl-class.md index 22d3cb1583..0dc7d37952 100644 --- a/docs/mfc/reference/cmfcpreviewctrlimpl-class.md +++ b/docs/mfc/reference/cmfcpreviewctrlimpl-class.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: CMFCPreviewCtrlImpl Class" title: "CMFCPreviewCtrlImpl Class" +description: "Learn more about: CMFCPreviewCtrlImpl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPreviewCtrlImpl", "AFXWIN/CMFCPreviewCtrlImpl", "AFXWIN/CMFCPreviewCtrlImpl::CMFCPreviewCtrlImpl", "AFXWIN/CMFCPreviewCtrlImpl::Create", "AFXWIN/CMFCPreviewCtrlImpl::Destroy", "AFXWIN/CMFCPreviewCtrlImpl::Focus", "AFXWIN/CMFCPreviewCtrlImpl::GetDocument", "AFXWIN/CMFCPreviewCtrlImpl::Redraw", "AFXWIN/CMFCPreviewCtrlImpl::SetDocument", "AFXWIN/CMFCPreviewCtrlImpl::SetHost", "AFXWIN/CMFCPreviewCtrlImpl::SetPreviewVisuals", "AFXWIN/CMFCPreviewCtrlImpl::SetRect", "AFXWIN/CMFCPreviewCtrlImpl::DoPaint", "AFXWIN/CMFCPreviewCtrlImpl::m_clrBackColor", "AFXWIN/CMFCPreviewCtrlImpl::m_clrTextColor", "AFXWIN/CMFCPreviewCtrlImpl::m_font", "AFXWIN/CMFCPreviewCtrlImpl::m_pDocument"] helpviewer_keywords: ["CMFCPreviewCtrlImpl [MFC], CMFCPreviewCtrlImpl", "CMFCPreviewCtrlImpl [MFC], Create", "CMFCPreviewCtrlImpl [MFC], Destroy", "CMFCPreviewCtrlImpl [MFC], Focus", "CMFCPreviewCtrlImpl [MFC], GetDocument", "CMFCPreviewCtrlImpl [MFC], Redraw", "CMFCPreviewCtrlImpl [MFC], SetDocument", "CMFCPreviewCtrlImpl [MFC], SetHost", "CMFCPreviewCtrlImpl [MFC], SetPreviewVisuals", "CMFCPreviewCtrlImpl [MFC], SetRect", "CMFCPreviewCtrlImpl [MFC], DoPaint", "CMFCPreviewCtrlImpl [MFC], m_clrBackColor", "CMFCPreviewCtrlImpl [MFC], m_clrTextColor", "CMFCPreviewCtrlImpl [MFC], m_font", "CMFCPreviewCtrlImpl [MFC], m_pDocument"] -ms.assetid: 06257fa0-54c9-478d-9d68-c9698c3f93ed --- -# CMFCPreviewCtrlImpl Class +# `CMFCPreviewCtrlImpl` Class This class implements a window that is placed on a host window provided by the Shell for Rich Preview. ## Syntax -``` +```cpp class CMFCPreviewCtrlImpl : public CWnd; ``` @@ -22,37 +21,37 @@ class CMFCPreviewCtrlImpl : public CWnd; |Name|Description| |----------|-----------------| -|[CMFCPreviewCtrlImpl::~CMFCPreviewCtrlImpl](#dtor)|Destructs a preview control object.| -|[CMFCPreviewCtrlImpl::CMFCPreviewCtrlImpl](#cmfcpreviewctrlimpl)|Constructs a preview control object.| +|[`CMFCPreviewCtrlImpl::~CMFCPreviewCtrlImpl`](#dtor)|Destructs a preview control object.| +|[`CMFCPreviewCtrlImpl::CMFCPreviewCtrlImpl`](#cmfcpreviewctrlimpl)|Constructs a preview control object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CMFCPreviewCtrlImpl::Create](#create)|Overloaded. Called by a Rich Preview handler to create the Windows window.| -|[CMFCPreviewCtrlImpl::Destroy](#destroy)|Called by a Rich Preview handler when it needs to destroy this control.| -|[CMFCPreviewCtrlImpl::Focus](#focus)|Sets input focus to this control.| -|[CMFCPreviewCtrlImpl::GetDocument](#getdocument)|Returns a document connected to this preview control.| -|[CMFCPreviewCtrlImpl::Redraw](#redraw)|Tells this control to redraw.| -|[CMFCPreviewCtrlImpl::SetDocument](#setdocument)|Called by the preview handler to create a relationship between the document implementation and the preview control.| -|[CMFCPreviewCtrlImpl::SetHost](#sethost)|Sets a new parent for this control.| -|[CMFCPreviewCtrlImpl::SetPreviewVisuals](#setpreviewvisuals)|Called by a Rich Preview handler when it needs to set visuals of rich preview content.| -|[CMFCPreviewCtrlImpl::SetRect](#setrect)|Sets a new bounding rectangle for this control.| +|[`CMFCPreviewCtrlImpl::Create`](#create)|Overloaded. Called by a Rich Preview handler to create the Windows window.| +|[`CMFCPreviewCtrlImpl::Destroy`](#destroy)|Called by a Rich Preview handler when it needs to destroy this control.| +|[`CMFCPreviewCtrlImpl::Focus`](#focus)|Sets input focus to this control.| +|[`CMFCPreviewCtrlImpl::GetDocument`](#getdocument)|Returns a document connected to this preview control.| +|[`CMFCPreviewCtrlImpl::Redraw`](#redraw)|Tells this control to redraw.| +|[`CMFCPreviewCtrlImpl::SetDocument`](#setdocument)|Called by the preview handler to create a relationship between the document implementation and the preview control.| +|[`CMFCPreviewCtrlImpl::SetHost`](#sethost)|Sets a new parent for this control.| +|[`CMFCPreviewCtrlImpl::SetPreviewVisuals`](#setpreviewvisuals)|Called by a Rich Preview handler when it needs to set visuals of rich preview content.| +|[`CMFCPreviewCtrlImpl::SetRect`](#setrect)|Sets a new bounding rectangle for this control.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CMFCPreviewCtrlImpl::DoPaint](#dopaint)|Called by the framework to render the preview.| +|[`CMFCPreviewCtrlImpl::DoPaint`](#dopaint)|Called by the framework to render the preview.| ### Protected Data Members |Name|Description| |----------|-----------------| -|[CMFCPreviewCtrlImpl::m_clrBackColor](#m_clrbackcolor)|Background color of preview window.| -|[CMFCPreviewCtrlImpl::m_clrTextColor](#m_clrtextcolor)|Text color of preview window.| -|[CMFCPreviewCtrlImpl::m_font](#m_font)|Font used to display text in the preview window.| -|[CMFCPreviewCtrlImpl::m_pDocument](#m_pdocument)|A pointer to a document whose content is previewed in the control.| +|[`CMFCPreviewCtrlImpl::m_clrBackColor`](#m_clrbackcolor)|Background color of preview window.| +|[`CMFCPreviewCtrlImpl::m_clrTextColor`](#m_clrtextcolor)|Text color of preview window.| +|[`CMFCPreviewCtrlImpl::m_font`](#m_font)|Font used to display text in the preview window.| +|[`CMFCPreviewCtrlImpl::m_pDocument`](#m_pdocument)|A pointer to a document whose content is previewed in the control.| ## Requirements @@ -60,99 +59,101 @@ class CMFCPreviewCtrlImpl : public CWnd; ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[CObject](cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[CCmdTarget](ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[CWnd](cwnd-class.md) -[CMFCPreviewCtrlImpl](../../mfc/reference/cmfcpreviewctrlimpl-class.md) +[CMFCPreviewCtrlImpl](cmfcpreviewctrlimpl-class.md) -## CMFCPreviewCtrlImpl::CMFCPreviewCtrlImpl +## `CMFCPreviewCtrlImpl::CMFCPreviewCtrlImpl` Constructs a preview control object. ### Syntax +```cpp CMFCPreviewCtrlImpl(); +``` -## CMFCPreviewCtrlImpl::Create +## `CMFCPreviewCtrlImpl::Create` Overloaded. Called by a Rich Preview handler to create the Windows window. ### Syntax -``` +```cpp virtual BOOL Create( - HWND hWndParent, - const RECT* prc + HWND hWndParent, + const RECT* prc ); virtual BOOL Create( - HWND hWndParent, - const RECT* prc, - CCreateContext* pContext + HWND hWndParent, + const RECT* prc, + CCreateContext* pContext ); ``` ### Parameters -*hWndParent*
+*`hWndParent`*\ A handle to the host window supplied by the Shell for Rich Preview. -*prc*
+*`prc`*\ Specifies the initial size and position of the window. -*pContext*
+*`pContext`*\ A pointer to a creation context. ### Return Value -TRUE if creation succeeded; otherwise FALSE. +`TRUE` if creation succeeded; otherwise `FALSE`. -## CMFCPreviewCtrlImpl::Destroy +## `CMFCPreviewCtrlImpl::Destroy` Called by a Rich Preview handler when it needs to destroy this control. ### Syntax -``` +```cpp virtual void Destroy(); ``` -## CMFCPreviewCtrlImpl::DoPaint +## `CMFCPreviewCtrlImpl::DoPaint` Called by the framework to render the preview. ### Syntax -``` +```cpp virtual void DoPaint( - CPaintDC* pDC + CPaintDC* pDC ); ``` ### Parameters -*pDC*
+*`pDC`*\ A pointer to a device context for painting. -## CMFCPreviewCtrlImpl::Focus +## `CMFCPreviewCtrlImpl::Focus` Sets input focus to this control. ### Syntax -``` +```cpp virtual void Focus(); ``` -## CMFCPreviewCtrlImpl::GetDocument +## `CMFCPreviewCtrlImpl::GetDocument` Returns a document connected to this preview control. ### Syntax -``` +```cpp ATL::IDocument* GetDocument(); ``` @@ -160,55 +161,57 @@ ATL::IDocument* GetDocument(); A pointer to a document, whose content is previewed in the control. -## CMFCPreviewCtrlImpl::m_clrBackColor +## `CMFCPreviewCtrlImpl::m_clrBackColor` Background color of the preview window. ### Syntax -``` +```cpp COLORREF m_clrBackColor; ``` -## CMFCPreviewCtrlImpl::m_clrTextColor +## `CMFCPreviewCtrlImpl::m_clrTextColor` Text color of the preview window. ### Syntax -``` +```cpp COLORREF m_clrTextColor; ``` -## CMFCPreviewCtrlImpl::m_font Font used to display text in the preview window. +## `CMFCPreviewCtrlImpl::m_font` + +Font used to display text in the preview window. ### Syntax -``` +```cpp CFont m_font; ``` -## CMFCPreviewCtrlImpl::m_pDocument +## `CMFCPreviewCtrlImpl::m_pDocument` A pointer to a document whose content is previewed in the control. ### Syntax -``` +```cpp ATL::IDocument* m_pDocument; ``` -## CMFCPreviewCtrlImpl::Redraw +## `CMFCPreviewCtrlImpl::Redraw` Tells this control to redraw. ### Syntax -``` +```cpp virtual void Redraw(); ``` -## CMFCPreviewCtrlImpl::SetDocument +## `CMFCPreviewCtrlImpl::SetDocument` Called by the preview handler to create a relationship between the document implementation and the preview control. @@ -216,88 +219,88 @@ Called by the preview handler to create a relationship between the document impl ```cpp void SetDocument( - IDocument* pDocument + IDocument* pDocument ); ``` ### Parameters -*pDocument*
+*`pDocument`*\ A pointer to the document implementation. -## CMFCPreviewCtrlImpl::SetHost +## `CMFCPreviewCtrlImpl::SetHost` Sets a new parent for this control. ### Syntax -``` +```cpp virtual void SetHost( - HWND hWndParent + HWND hWndParent ); ``` ### Parameters -*hWndParent*
+*`hWndParent`*\ A handle to the new parent window. -## CMFCPreviewCtrlImpl::SetPreviewVisuals +## `CMFCPreviewCtrlImpl::SetPreviewVisuals` Called by a Rich Preview handler when it needs to set visuals of rich preview content. ### Syntax -``` +```cpp virtual void SetPreviewVisuals( - COLORREF clrBack, - COLORREF clrText, - const LOGFONTW *plf + COLORREF clrBack, + COLORREF clrText, + const LOGFONTW *plf ); ``` ### Parameters -*clrBack*
+*`clrBack`*\ Background color of preview window. -*clrText*
+*`clrText`*\ Text color of preview window. -*plf*
+*`plf`*\ Font used to display text in the preview window. -## CMFCPreviewCtrlImpl::SetRect +## `CMFCPreviewCtrlImpl::SetRect` Sets a new bounding rectangle for this control. ### Syntax -``` +```cpp virtual void SetRect( - const RECT* prc, - BOOL bRedraw + const RECT* prc, + BOOL bRedraw ); ``` ### Parameters -*prc*
+*`prc`*\ Specifies the new size and position of the preview control. -*bRedraw*
+*`bRedraw`*\ Specifies whether the control should be redrawn. ### Remarks Usually a new bounding rectangle is set when the host control is resized. -## CMFCPreviewCtrlImpl::~CMFCPreviewCtrlImpl +## `CMFCPreviewCtrlImpl::~CMFCPreviewCtrlImpl` Destructs a preview control object. ### Syntax -``` +```cpp virtual ~CMFCPreviewCtrlImpl(); ``` diff --git a/docs/mfc/reference/cmfcpropertygridctrl-class.md b/docs/mfc/reference/cmfcpropertygridctrl-class.md index 882a9702db..585e3e775f 100644 --- a/docs/mfc/reference/cmfcpropertygridctrl-class.md +++ b/docs/mfc/reference/cmfcpropertygridctrl-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: CMFCPropertyGridCtrl Class" title: "CMFCPropertyGridCtrl Class" +description: "Learn more about: CMFCPropertyGridCtrl Class" ms.date: "11/19/2018" f1_keywords: ["CMFCPropertyGridCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::CMFCPropertyGridCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::accSelect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::AddProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::AlwaysShowUserToolTip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::CloseColorPopup", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::Create", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::DeleteProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::DrawControlBarColors", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::EnableDescriptionArea", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::EnableHeaderCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::EnsureVisible", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::ExpandAll", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::FindItemByData", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accChildCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accFocus", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accHelp", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accHelpTopic", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accKeyboardShortcut", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::get_accSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetBkColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetBoldFont", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetCurSel", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetCustomColors", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetDescriptionHeight", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetDescriptionRows", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetHeaderCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetHeaderHeight", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetLeftColumnWidth", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetListRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetPropertyColumnWidth", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetPropertyCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetRowHeight", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetScrollBarCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::GetTextColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::HitTest", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::InitHeader", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsAlphabeticMode", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsDescriptionArea", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsGroupNameFullWidth", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsHeaderCtrl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsMarkModifiedProperties", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsShowDragContext", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::IsVSDotNetLook", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::MarkModifiedProperties", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::RemoveAll", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::ResetOriginalValues", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetAlphabeticMode", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetBoolLabels", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetCurSel", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetCustomColors", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetDescriptionRows", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetGroupNameFullWidth", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetListDelimiter", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetShowDragContext", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::SetVSDotNetLook", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::UpdateColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::AdjustLayout", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::CompareProps", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::EditItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::EndEditItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::Init", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnChangeSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnClickButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnDrawBorder", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnDrawDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnDrawList", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnDrawProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnPropertyChanged", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::OnSelectCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridCtrl::ValidateItemData"] helpviewer_keywords: ["CMFCPropertyGridCtrl [MFC], CMFCPropertyGridCtrl", "CMFCPropertyGridCtrl [MFC], accSelect", "CMFCPropertyGridCtrl [MFC], AddProperty", "CMFCPropertyGridCtrl [MFC], AlwaysShowUserToolTip", "CMFCPropertyGridCtrl [MFC], CloseColorPopup", "CMFCPropertyGridCtrl [MFC], Create", "CMFCPropertyGridCtrl [MFC], DeleteProperty", "CMFCPropertyGridCtrl [MFC], DrawControlBarColors", "CMFCPropertyGridCtrl [MFC], EnableDescriptionArea", "CMFCPropertyGridCtrl [MFC], EnableHeaderCtrl", "CMFCPropertyGridCtrl [MFC], EnsureVisible", "CMFCPropertyGridCtrl [MFC], ExpandAll", "CMFCPropertyGridCtrl [MFC], FindItemByData", "CMFCPropertyGridCtrl [MFC], get_accChildCount", "CMFCPropertyGridCtrl [MFC], get_accFocus", "CMFCPropertyGridCtrl [MFC], get_accHelp", "CMFCPropertyGridCtrl [MFC], get_accHelpTopic", "CMFCPropertyGridCtrl [MFC], get_accKeyboardShortcut", "CMFCPropertyGridCtrl [MFC], get_accSelection", "CMFCPropertyGridCtrl [MFC], GetBkColor", "CMFCPropertyGridCtrl [MFC], GetBoldFont", "CMFCPropertyGridCtrl [MFC], GetCurSel", "CMFCPropertyGridCtrl [MFC], GetCustomColors", "CMFCPropertyGridCtrl [MFC], GetDescriptionHeight", "CMFCPropertyGridCtrl [MFC], GetDescriptionRows", "CMFCPropertyGridCtrl [MFC], GetHeaderCtrl", "CMFCPropertyGridCtrl [MFC], GetHeaderHeight", "CMFCPropertyGridCtrl [MFC], GetLeftColumnWidth", "CMFCPropertyGridCtrl [MFC], GetListRect", "CMFCPropertyGridCtrl [MFC], GetProperty", "CMFCPropertyGridCtrl [MFC], GetPropertyColumnWidth", "CMFCPropertyGridCtrl [MFC], GetPropertyCount", "CMFCPropertyGridCtrl [MFC], GetRowHeight", "CMFCPropertyGridCtrl [MFC], GetScrollBarCtrl", "CMFCPropertyGridCtrl [MFC], GetTextColor", "CMFCPropertyGridCtrl [MFC], HitTest", "CMFCPropertyGridCtrl [MFC], InitHeader", "CMFCPropertyGridCtrl [MFC], IsAlphabeticMode", "CMFCPropertyGridCtrl [MFC], IsAlwaysShowUserToolTip", "CMFCPropertyGridCtrl [MFC], IsDescriptionArea", "CMFCPropertyGridCtrl [MFC], IsGroupNameFullWidth", "CMFCPropertyGridCtrl [MFC], IsHeaderCtrl", "CMFCPropertyGridCtrl [MFC], IsMarkModifiedProperties", "CMFCPropertyGridCtrl [MFC], IsShowDragContext", "CMFCPropertyGridCtrl [MFC], IsVSDotNetLook", "CMFCPropertyGridCtrl [MFC], MarkModifiedProperties", "CMFCPropertyGridCtrl [MFC], RemoveAll", "CMFCPropertyGridCtrl [MFC], ResetOriginalValues", "CMFCPropertyGridCtrl [MFC], SetAlphabeticMode", "CMFCPropertyGridCtrl [MFC], SetBoolLabels", "CMFCPropertyGridCtrl [MFC], SetCurSel", "CMFCPropertyGridCtrl [MFC], SetCustomColors", "CMFCPropertyGridCtrl [MFC], SetDescriptionRows", "CMFCPropertyGridCtrl [MFC], SetGroupNameFullWidth", "CMFCPropertyGridCtrl [MFC], SetListDelimiter", "CMFCPropertyGridCtrl [MFC], SetShowDragContext", "CMFCPropertyGridCtrl [MFC], SetVSDotNetLook", "CMFCPropertyGridCtrl [MFC], UpdateColor", "CMFCPropertyGridCtrl [MFC], AdjustLayout", "CMFCPropertyGridCtrl [MFC], CompareProps", "CMFCPropertyGridCtrl [MFC], EditItem", "CMFCPropertyGridCtrl [MFC], EndEditItem", "CMFCPropertyGridCtrl [MFC], Init", "CMFCPropertyGridCtrl [MFC], OnChangeSelection", "CMFCPropertyGridCtrl [MFC], OnClickButton", "CMFCPropertyGridCtrl [MFC], OnDrawBorder", "CMFCPropertyGridCtrl [MFC], OnDrawDescription", "CMFCPropertyGridCtrl [MFC], OnDrawList", "CMFCPropertyGridCtrl [MFC], OnDrawProperty", "CMFCPropertyGridCtrl [MFC], OnPropertyChanged", "CMFCPropertyGridCtrl [MFC], OnSelectCombo", "CMFCPropertyGridCtrl [MFC], ValidateItemData"] -ms.assetid: 95877cae-2311-4a2a-9031-0c8c3cf0a5f9 --- # CMFCPropertyGridCtrl Class -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. +For more detail see the source code located in the **`mfc`** folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. Supports an editable property grid control that can display properties in alphabetical or hierarchical order. @@ -24,106 +23,106 @@ class CMFCPropertyGridCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CMFCPropertyGridCtrl::CMFCPropertyGridCtrl](#cmfcpropertygridctrl)|Constructs a `CMFCPropertyGridCtrl` object.| +|[`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`](#cmfcpropertygridctrl)|Constructs a `CMFCPropertyGridCtrl` object.| |`CMFCPropertyGridCtrl::~CMFCPropertyGridCtrl`|Destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|`CMFCPropertyGridCtrl::accHitTest`|Called by the framework to retrieve the child element or child object at a given point on the screen. (Overrides [CWnd::accHitTest](../../mfc/reference/cwnd-class.md#acchittest).)| -|`CMFCPropertyGridCtrl::accLocation`|Called by the framework to retrieve the specified object's current screen location. (Overrides [CWnd::accLocation](../../mfc/reference/cwnd-class.md#acclocation).)| -|[CMFCPropertyGridCtrl::accSelect](#accselect)|Called by the framework to modify the selection or move the keyboard focus of the specified object. (Overrides [CWnd::accSelect](../../mfc/reference/cwnd-class.md#accselect).)| -|[CMFCPropertyGridCtrl::AddProperty](#addproperty)|Adds a new property to a property grid control.| -|[CMFCPropertyGridCtrl::AlwaysShowUserToolTip](#alwaysshowusertooltip)|| -|[CMFCPropertyGridCtrl::CloseColorPopup](#closecolorpopup)|Closes the color selection dialog box.| -|[CMFCPropertyGridCtrl::Create](#create)|Creates a property grid control and attaches it to the property grid control object.| -|[CMFCPropertyGridCtrl::DeleteProperty](#deleteproperty)|Deletes the specified property from the property grid control.| -|[CMFCPropertyGridCtrl::DrawControlBarColors](#drawcontrolbarcolors)|| -|[CMFCPropertyGridCtrl::EnableDescriptionArea](#enabledescriptionarea)|Enables or disables the description area that is displayed underneath the list of properties.| -|[CMFCPropertyGridCtrl::EnableHeaderCtrl](#enableheaderctrl)|Enables or disables the header control at the top of the property grid control.| -|[CMFCPropertyGridCtrl::EnsureVisible](#ensurevisible)|Scrolls a property grid control and expands property items until the specified property is visible.| -|[CMFCPropertyGridCtrl::ExpandAll](#expandall)|Expands or collapses all property grid control nodes.| -|[CMFCPropertyGridCtrl::FindItemByData](#finditembydata)|Retrieves the property that is associated with a user-defined DWORD value.| -|`CMFCPropertyGridCtrl::get_accChild`|Called by the framework to retrieve the address of an `IDispatch` interface for the specified child. (Overrides [CWnd::get_accChild](../../mfc/reference/cwnd-class.md#get_accchild).)| -|[CMFCPropertyGridCtrl::get_accChildCount](#get_accchildcount)|Called by the framework to retrieve the number of children belonging to this object. (Overrides [CWnd::get_accChildCount](../../mfc/reference/cwnd-class.md#get_accchildcount).)| -|`CMFCPropertyGridCtrl::get_accDefaultAction`|Called by the framework to retrieve a string that describes the object's default action. (Overrides [CWnd::get_accDefaultAction](../../mfc/reference/cwnd-class.md#get_accdefaultaction).)| -|`CMFCPropertyGridCtrl::get_accDescription`|Called by framework to retrieve a string that describes the visual appearance of the specified object. (Overrides [CWnd::get_accDescription](../../mfc/reference/cwnd-class.md#get_accdescription).)| -|[CMFCPropertyGridCtrl::get_accFocus](#get_accfocus)|Called by the framework to retrieve the object that has the keyboard focus. (Overrides [CWnd::get_accFocus](../../mfc/reference/cwnd-class.md#get_accfocus).)| -|[CMFCPropertyGridCtrl::get_accHelp](#get_acchelp)|Called by the framework to retrieve an object's `Help` property string. (Overrides [CWnd::get_accHelp](../../mfc/reference/cwnd-class.md#get_acchelp).)| -|[CMFCPropertyGridCtrl::get_accHelpTopic](#get_acchelptopic)|Called by the framework to retrieve the full path of the **WinHelp** file associated with the specified object and the identifier of the appropriate topic within that file. (Overrides [CWnd::get_accHelpTopic](../../mfc/reference/cwnd-class.md#get_acchelptopic).)| -|[CMFCPropertyGridCtrl::get_accKeyboardShortcut](#get_acckeyboardshortcut)|Called by the framework to retrieve the specified object's shortcut key or access key. (Overrides [CWnd::get_accKeyboardShortcut](../../mfc/reference/cwnd-class.md#get_acckeyboardshortcut).)| -|`CMFCPropertyGridCtrl::get_accName`|Called by the framework to retrieve the name of the specified object. (Overrides [CWnd::get_accName](../../mfc/reference/cwnd-class.md#get_accname).)| -|`CMFCPropertyGridCtrl::get_accRole`|Called by the framework to retrieve information that describes the role of the specified object. (Overrides [CWnd::get_accRole](../../mfc/reference/cwnd-class.md#get_accrole).)| -|[CMFCPropertyGridCtrl::get_accSelection](#get_accselection)|Called by the framework to retrieve the selected children of this object. (Overrides [CWnd::get_accSelection](../../mfc/reference/cwnd-class.md#get_accselection).)| -|`CMFCPropertyGridCtrl::get_accState`|Called by the framework to retrieve the current state of the specified object. (Overrides [CWnd::get_accState](../../mfc/reference/cwnd-class.md#get_accstate).)| -|`CMFCPropertyGridCtrl::get_accValue`|Called by the framework to retrieve the value of the specified object. (Overrides [CWnd::get_accValue](../../mfc/reference/cwnd-class.md#get_accvalue).)| -|[CMFCPropertyGridCtrl::GetBkColor](#getbkcolor)|Retrieves the background color of the current property grid control.| -|[CMFCPropertyGridCtrl::GetBoldFont](#getboldfont)|Retrieves the Windows font that of text in the current property grid control in bold style.| -|[CMFCPropertyGridCtrl::GetCurSel](#getcursel)|Retrieves the currently selected property.| -|[CMFCPropertyGridCtrl::GetCustomColors](#getcustomcolors)|Retrieves the custom colors that are currently defined for property grid control elements.| -|[CMFCPropertyGridCtrl::GetDescriptionHeight](#getdescriptionheight)|Retrieves the height of the description area located at the bottom of the property grid control.| -|[CMFCPropertyGridCtrl::GetDescriptionRows](#getdescriptionrows)|Retrieves the number of rows in the description area of the current property grid control.| -|[CMFCPropertyGridCtrl::GetHeaderCtrl](#getheaderctrl)|Retrieves the internal [CMFCHeaderCtrl](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control.| -|[CMFCPropertyGridCtrl::GetHeaderHeight](#getheaderheight)|Retrieves the height of the property grid control header.| -|[CMFCPropertyGridCtrl::GetLeftColumnWidth](#getleftcolumnwidth)|Retrieves the width of the left column of the current property grid control, which contains the name of each property.| -|[CMFCPropertyGridCtrl::GetListRect](#getlistrect)|Retrieves the bounding rectangle of the property grid control.| -|[CMFCPropertyGridCtrl::GetProperty](#getproperty)|Retrieves a pointer to the property object that corresponds to the specified index of a property grid control item.| -|[CMFCPropertyGridCtrl::GetPropertyColumnWidth](#getpropertycolumnwidth)|Retrieves the current width of the column that contains property values.| -|[CMFCPropertyGridCtrl::GetPropertyCount](#getpropertycount)|Retrieves the number of properties in a property grid control.| -|[CMFCPropertyGridCtrl::GetRowHeight](#getrowheight)|Retrieves the height of a row in the property grid control.| -|[CMFCPropertyGridCtrl::GetScrollBarCtrl](#getscrollbarctrl)|Retrieves a pointer to the scroll bar control in the property grid control. (Overrides [CWnd::GetScrollBarCtrl](../../mfc/reference/cwnd-class.md#getscrollbarctrl).)| -|[CMFCPropertyGridCtrl::GetTextColor](#gettextcolor)|Retrieves the color of the text of property items in the current property grid control.| -|`CMFCPropertyGridCtrl::GetThisClass`|Used by the framework to obtain a pointer to the [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| -|[CMFCPropertyGridCtrl::HitTest](#hittest)|Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point.| -|[CMFCPropertyGridCtrl::InitHeader](#initheader)|Initializes the internal [CMFCHeaderCtrl](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control.| -|[CMFCPropertyGridCtrl::IsAlphabeticMode](#isalphabeticmode)|Indicates whether a property grid control is in alphabetic mode.| -|[CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip](#isalwaysshowusertooltip)|| -|[CMFCPropertyGridCtrl::IsDescriptionArea](#isdescriptionarea)|Indicates whether the description area of the property grid control is displayed.| -|[CMFCPropertyGridCtrl::IsGroupNameFullWidth](#isgroupnamefullwidth)|Indicates whether each property group name is displayed across the width of the current property grid control.| -|[CMFCPropertyGridCtrl::IsHeaderCtrl](#isheaderctrl)|Indicates whether the header control is displayed.| -|[CMFCPropertyGridCtrl::IsMarkModifiedProperties](#ismarkmodifiedproperties)|Indicates how the property grid control displays modified properties.| -|[CMFCPropertyGridCtrl::IsShowDragContext](#isshowdragcontext)|Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.| -|[CMFCPropertyGridCtrl::IsVSDotNetLook](#isvsdotnetlook)|Indicates whether the appearance of the property grid control is in the style that is used by VS .NET.| -|[CMFCPropertyGridCtrl::MarkModifiedProperties](#markmodifiedproperties)|Specifies how to display modified properties.| -|`CMFCPropertyGridCtrl::PreTranslateMessage`|Used by class [CWinApp](../../mfc/reference/cwinapp-class.md) to translate window messages before they are dispatched to the [TranslateMessage](/windows/win32/api/winuser/nf-winuser-translatemessage) and [DispatchMessage](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides [CWnd::PreTranslateMessage](../../mfc/reference/cwnd-class.md#pretranslatemessage).)| -|[CMFCPropertyGridCtrl::RemoveAll](#removeall)|Removes all property objects from a property grid control.| -|[CMFCPropertyGridCtrl::ResetOriginalValues](#resetoriginalvalues)|Restores the original value of all properties.| -|[CMFCPropertyGridCtrl::SetAlphabeticMode](#setalphabeticmode)|Sets or resets alphabetical mode.| -|[CMFCPropertyGridCtrl::SetBoolLabels](#setboollabels)|Specifies the text of Boolean labels.| -|[CMFCPropertyGridCtrl::SetCurSel](#setcursel)|Selects a property in a property grid control.| -|[CMFCPropertyGridCtrl::SetCustomColors](#setcustomcolors)|Specifies custom colors for various property grid control elements.| -|[CMFCPropertyGridCtrl::SetDescriptionRows](#setdescriptionrows)|Specifies the number of rows to display in the description section of the current property grid control.| -|[CMFCPropertyGridCtrl::SetGroupNameFullWidth](#setgroupnamefullwidth)|Specifies whether to display the full width of the category name for a group of properties in the current property grid control.| -|[CMFCPropertyGridCtrl::SetListDelimiter](#setlistdelimiter)|Defines a character that will be used as a delimiter in a list of property values.| -|[CMFCPropertyGridCtrl::SetShowDragContext](#setshowdragcontext)|Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.| -|[CMFCPropertyGridCtrl::SetVSDotNetLook](#setvsdotnetlook)|Sets the appearance of the property grid control to the style that is used in VS .NET.| -|[CMFCPropertyGridCtrl::UpdateColor](#updatecolor)|Sets the color value of the currently selected color property.| +|`CMFCPropertyGridCtrl::accHitTest`|Called by the framework to retrieve the child element or child object at a given point on the screen. (Overrides [`CWnd::accHitTest`](../../mfc/reference/cwnd-class.md#acchittest).)| +|`CMFCPropertyGridCtrl::accLocation`|Called by the framework to retrieve the specified object's current screen location. (Overrides [`CWnd::accLocation`](../../mfc/reference/cwnd-class.md#acclocation).)| +|[`CMFCPropertyGridCtrl::accSelect`](#accselect)|Called by the framework to modify the selection or move the keyboard focus of the specified object. (Overrides [`CWnd::accSelect`](../../mfc/reference/cwnd-class.md#accselect).)| +|[`CMFCPropertyGridCtrl::AddProperty`](#addproperty)|Adds a new property to a property grid control.| +|[`CMFCPropertyGridCtrl::AlwaysShowUserToolTip`](#alwaysshowusertooltip)|| +|[`CMFCPropertyGridCtrl::CloseColorPopup`](#closecolorpopup)|Closes the color selection dialog box.| +|[`CMFCPropertyGridCtrl::Create`](#create)|Creates a property grid control and attaches it to the property grid control object.| +|[`CMFCPropertyGridCtrl::DeleteProperty`](#deleteproperty)|Deletes the specified property from the property grid control.| +|[`CMFCPropertyGridCtrl::DrawControlBarColors`](#drawcontrolbarcolors)|| +|[`CMFCPropertyGridCtrl::EnableDescriptionArea`](#enabledescriptionarea)|Enables or disables the description area that is displayed underneath the list of properties.| +|[`CMFCPropertyGridCtrl::EnableHeaderCtrl`](#enableheaderctrl)|Enables or disables the header control at the top of the property grid control.| +|[`CMFCPropertyGridCtrl::EnsureVisible`](#ensurevisible)|Scrolls a property grid control and expands property items until the specified property is visible.| +|[`CMFCPropertyGridCtrl::ExpandAll`](#expandall)|Expands or collapses all property grid control nodes.| +|[`CMFCPropertyGridCtrl::FindItemByData`](#finditembydata)|Retrieves the property that is associated with a user-defined `DWORD` value.| +|`CMFCPropertyGridCtrl::get_accChild`|Called by the framework to retrieve the address of an `IDispatch` interface for the specified child. (Overrides [`CWnd::get_accChild`](../../mfc/reference/cwnd-class.md#get_accchild).)| +|[`CMFCPropertyGridCtrl::get_accChildCount`](#get_accchildcount)|Called by the framework to retrieve the number of children belonging to this object. (Overrides [`CWnd::get_accChildCount`](../../mfc/reference/cwnd-class.md#get_accchildcount).)| +|`CMFCPropertyGridCtrl::get_accDefaultAction`|Called by the framework to retrieve a string that describes the object's default action. (Overrides [`CWnd::get_accDefaultAction`](../../mfc/reference/cwnd-class.md#get_accdefaultaction).)| +|`CMFCPropertyGridCtrl::get_accDescription`|Called by framework to retrieve a string that describes the visual appearance of the specified object. (Overrides [`CWnd::get_accDescription`](../../mfc/reference/cwnd-class.md#get_accdescription).)| +|[`CMFCPropertyGridCtrl::get_accFocus`](#get_accfocus)|Called by the framework to retrieve the object that has the keyboard focus. (Overrides [`CWnd::get_accFocus`](../../mfc/reference/cwnd-class.md#get_accfocus).)| +|[`CMFCPropertyGridCtrl::get_accHelp`](#get_acchelp)|Called by the framework to retrieve an object's `Help` property string. (Overrides [`CWnd::get_accHelp`](../../mfc/reference/cwnd-class.md#get_acchelp).)| +|[`CMFCPropertyGridCtrl::get_accHelpTopic`](#get_acchelptopic)|Called by the framework to retrieve the full path of the **`WinHelp`** file associated with the specified object and the identifier of the appropriate topic within that file. (Overrides [`CWnd::get_accHelpTopic`](../../mfc/reference/cwnd-class.md#get_acchelptopic).)| +|[`CMFCPropertyGridCtrl::get_accKeyboardShortcut`](#get_acckeyboardshortcut)|Called by the framework to retrieve the specified object's shortcut key or access key. (Overrides [`CWnd::get_accKeyboardShortcut`](../../mfc/reference/cwnd-class.md#get_acckeyboardshortcut).)| +|`CMFCPropertyGridCtrl::get_accName`|Called by the framework to retrieve the name of the specified object. (Overrides [`CWnd::get_accName`](../../mfc/reference/cwnd-class.md#get_accname).)| +|`CMFCPropertyGridCtrl::get_accRole`|Called by the framework to retrieve information that describes the role of the specified object. (Overrides [`CWnd::get_accRole`](../../mfc/reference/cwnd-class.md#get_accrole).)| +|[`CMFCPropertyGridCtrl::get_accSelection`](#get_accselection)|Called by the framework to retrieve the selected children of this object. (Overrides [`CWnd::get_accSelection`](../../mfc/reference/cwnd-class.md#get_accselection).)| +|`CMFCPropertyGridCtrl::get_accState`|Called by the framework to retrieve the current state of the specified object. (Overrides [`CWnd::get_accState`](../../mfc/reference/cwnd-class.md#get_accstate).)| +|`CMFCPropertyGridCtrl::get_accValue`|Called by the framework to retrieve the value of the specified object. (Overrides [`CWnd::get_accValue`](../../mfc/reference/cwnd-class.md#get_accvalue).)| +|[`CMFCPropertyGridCtrl::GetBkColor`](#getbkcolor)|Retrieves the background color of the current property grid control.| +|[`CMFCPropertyGridCtrl::GetBoldFont`](#getboldfont)|Retrieves the Windows font that of text in the current property grid control in bold style.| +|[`CMFCPropertyGridCtrl::GetCurSel`](#getcursel)|Retrieves the currently selected property.| +|[`CMFCPropertyGridCtrl::GetCustomColors`](#getcustomcolors)|Retrieves the custom colors that are currently defined for property grid control elements.| +|[`CMFCPropertyGridCtrl::GetDescriptionHeight`](#getdescriptionheight)|Retrieves the height of the description area located at the bottom of the property grid control.| +|[`CMFCPropertyGridCtrl::GetDescriptionRows`](#getdescriptionrows)|Retrieves the number of rows in the description area of the current property grid control.| +|[`CMFCPropertyGridCtrl::GetHeaderCtrl`](#getheaderctrl)|Retrieves the internal [`CMFCHeaderCtrl`](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control.| +|[`CMFCPropertyGridCtrl::GetHeaderHeight`](#getheaderheight)|Retrieves the height of the property grid control header.| +|[`CMFCPropertyGridCtrl::GetLeftColumnWidth`](#getleftcolumnwidth)|Retrieves the width of the left column of the current property grid control, which contains the name of each property.| +|[`CMFCPropertyGridCtrl::GetListRect`](#getlistrect)|Retrieves the bounding rectangle of the property grid control.| +|[`CMFCPropertyGridCtrl::GetProperty`](#getproperty)|Retrieves a pointer to the property object that corresponds to the specified index of a property grid control item.| +|[`CMFCPropertyGridCtrl::GetPropertyColumnWidth`](#getpropertycolumnwidth)|Retrieves the current width of the column that contains property values.| +|[`CMFCPropertyGridCtrl::GetPropertyCount`](#getpropertycount)|Retrieves the number of properties in a property grid control.| +|[`CMFCPropertyGridCtrl::GetRowHeight`](#getrowheight)|Retrieves the height of a row in the property grid control.| +|[`CMFCPropertyGridCtrl::GetScrollBarCtrl`](#getscrollbarctrl)|Retrieves a pointer to the scroll bar control in the property grid control. (Overrides [`CWnd::GetScrollBarCtrl`](../../mfc/reference/cwnd-class.md#getscrollbarctrl).)| +|[`CMFCPropertyGridCtrl::GetTextColor`](#gettextcolor)|Retrieves the color of the text of property items in the current property grid control.| +|`CMFCPropertyGridCtrl::GetThisClass`|Used by the framework to obtain a pointer to the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| +|[`CMFCPropertyGridCtrl::HitTest`](#hittest)|Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point.| +|[`CMFCPropertyGridCtrl::InitHeader`](#initheader)|Initializes the internal [`CMFCHeaderCtrl`](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control.| +|[`CMFCPropertyGridCtrl::IsAlphabeticMode`](#isalphabeticmode)|Indicates whether a property grid control is in alphabetic mode.| +|[`CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip`](#isalwaysshowusertooltip)|| +|[`CMFCPropertyGridCtrl::IsDescriptionArea`](#isdescriptionarea)|Indicates whether the description area of the property grid control is displayed.| +|[`CMFCPropertyGridCtrl::IsGroupNameFullWidth`](#isgroupnamefullwidth)|Indicates whether each property group name is displayed across the width of the current property grid control.| +|[`CMFCPropertyGridCtrl::IsHeaderCtrl`](#isheaderctrl)|Indicates whether the header control is displayed.| +|[`CMFCPropertyGridCtrl::IsMarkModifiedProperties`](#ismarkmodifiedproperties)|Indicates how the property grid control displays modified properties.| +|[`CMFCPropertyGridCtrl::IsShowDragContext`](#isshowdragcontext)|Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.| +|[`CMFCPropertyGridCtrl::IsVSDotNetLook`](#isvsdotnetlook)|Indicates whether the appearance of the property grid control is in the style that is used by VS .NET.| +|[`CMFCPropertyGridCtrl::MarkModifiedProperties`](#markmodifiedproperties)|Specifies how to display modified properties.| +|`CMFCPropertyGridCtrl::PreTranslateMessage`|Used by class [`CWinApp`](../../mfc/reference/cwinapp-class.md) to translate window messages before they are dispatched to the [`TranslateMessage`](/windows/win32/api/winuser/nf-winuser-translatemessage) and [`DispatchMessage`](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides [`CWnd::PreTranslateMessage`](../../mfc/reference/cwnd-class.md#pretranslatemessage).)| +|[`CMFCPropertyGridCtrl::RemoveAll`](#removeall)|Removes all property objects from a property grid control.| +|[`CMFCPropertyGridCtrl::ResetOriginalValues`](#resetoriginalvalues)|Restores the original value of all properties.| +|[`CMFCPropertyGridCtrl::SetAlphabeticMode`](#setalphabeticmode)|Sets or resets alphabetical mode.| +|[`CMFCPropertyGridCtrl::SetBoolLabels`](#setboollabels)|Specifies the text of Boolean labels.| +|[`CMFCPropertyGridCtrl::SetCurSel`](#setcursel)|Selects a property in a property grid control.| +|[`CMFCPropertyGridCtrl::SetCustomColors`](#setcustomcolors)|Specifies custom colors for various property grid control elements.| +|[`CMFCPropertyGridCtrl::SetDescriptionRows`](#setdescriptionrows)|Specifies the number of rows to display in the description section of the current property grid control.| +|[`CMFCPropertyGridCtrl::SetGroupNameFullWidth`](#setgroupnamefullwidth)|Specifies whether to display the full width of the category name for a group of properties in the current property grid control.| +|[`CMFCPropertyGridCtrl::SetListDelimiter`](#setlistdelimiter)|Defines a character that will be used as a delimiter in a list of property values.| +|[`CMFCPropertyGridCtrl::SetShowDragContext`](#setshowdragcontext)|Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns.| +|[`CMFCPropertyGridCtrl::SetVSDotNetLook`](#setvsdotnetlook)|Sets the appearance of the property grid control to the style that is used in VS .NET.| +|[`CMFCPropertyGridCtrl::UpdateColor`](#updatecolor)|Sets the color value of the currently selected color property.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CMFCPropertyGridCtrl::AdjustLayout](#adjustlayout)|Redraws the property grid control and its properties.| -|[CMFCPropertyGridCtrl::CompareProps](#compareprops)|Called by the property grid control to sort properties.| -|[CMFCPropertyGridCtrl::EditItem](#edititem)|Called by the framework when the user starts to modify a property.| -|[CMFCPropertyGridCtrl::EndEditItem](#endedititem)|Called by the framework when the user stops modifying a property.| -|[CMFCPropertyGridCtrl::Init](#init)|Called by the framework to initialize a property grid control.| -|[CMFCPropertyGridCtrl::OnChangeSelection](#onchangeselection)|Called by the framework when the current selection is changed.| -|[CMFCPropertyGridCtrl::OnClickButton](#onclickbutton)|Called by the framework when a property button is clicked.| -|[CMFCPropertyGridCtrl::OnDrawBorder](#ondrawborder)|Called by the framework to draw a border around a property grid control.| -|[CMFCPropertyGridCtrl::OnDrawDescription](#ondrawdescription)|Called by the framework to draw the description area and display the description text.| -|[CMFCPropertyGridCtrl::OnDrawList](#ondrawlist)|Called by the framework to display the list of properties in the property grid control.| -|[CMFCPropertyGridCtrl::OnDrawProperty](#ondrawproperty)|Called by the framework to display a property.| -|[CMFCPropertyGridCtrl::OnPropertyChanged](#onpropertychanged)|Called by the framework when the value of a property is changed.| -|[CMFCPropertyGridCtrl::OnSelectCombo](#onselectcombo)|Called by the framework when a property that contains a combo box control is selected.| -|[CMFCPropertyGridCtrl::ValidateItemData](#validateitemdata)|Called by the framework to validate property data.| +|[`CMFCPropertyGridCtrl::AdjustLayout`](#adjustlayout)|Redraws the property grid control and its properties.| +|[`CMFCPropertyGridCtrl::CompareProps`](#compareprops)|Called by the property grid control to sort properties.| +|[`CMFCPropertyGridCtrl::EditItem`](#edititem)|Called by the framework when the user starts to modify a property.| +|[`CMFCPropertyGridCtrl::EndEditItem`](#endedititem)|Called by the framework when the user stops modifying a property.| +|[`CMFCPropertyGridCtrl::Init`](#init)|Called by the framework to initialize a property grid control.| +|[`CMFCPropertyGridCtrl::OnChangeSelection`](#onchangeselection)|Called by the framework when the current selection is changed.| +|[`CMFCPropertyGridCtrl::OnClickButton`](#onclickbutton)|Called by the framework when a property button is clicked.| +|[`CMFCPropertyGridCtrl::OnDrawBorder`](#ondrawborder)|Called by the framework to draw a border around a property grid control.| +|[`CMFCPropertyGridCtrl::OnDrawDescription`](#ondrawdescription)|Called by the framework to draw the description area and display the description text.| +|[`CMFCPropertyGridCtrl::OnDrawList`](#ondrawlist)|Called by the framework to display the list of properties in the property grid control.| +|[`CMFCPropertyGridCtrl::OnDrawProperty`](#ondrawproperty)|Called by the framework to display a property.| +|[`CMFCPropertyGridCtrl::OnPropertyChanged`](#onpropertychanged)|Called by the framework when the value of a property is changed.| +|[`CMFCPropertyGridCtrl::OnSelectCombo`](#onselectcombo)|Called by the framework when a property that contains a combo box control is selected.| +|[`CMFCPropertyGridCtrl::ValidateItemData`](#validateitemdata)|Called by the framework to validate property data.| ## Remarks -The `CMFCPropertyGridCtrl` class displays a property grid control that contains editable properties derived from the [CMFCPropertyGridProperty](../../mfc/reference/cmfcpropertygridproperty-class.md) class. Each property can represent a type and it can contain subitems. The property grid control supports a resizable area at the bottom that can display the description of a selected property. +The `CMFCPropertyGridCtrl` class displays a property grid control that contains editable properties derived from the [`CMFCPropertyGridProperty`](../../mfc/reference/cmfcpropertygridproperty-class.md) class. Each property can represent a type and it can contain subitems. The property grid control supports a resizable area at the bottom that can display the description of a selected property. -To use a property grid control, construct a `CMFCPropertyGridCtrl` object and then call the [CMFCPropertyGridCtrl::Create](#create) method. Use the [CMFCPropertyGridCtrl::AddProperty](#addproperty) method to add properties to the list. +To use a property grid control, construct a `CMFCPropertyGridCtrl` object and then call the [`CMFCPropertyGridCtrl::Create`](#create) method. Use the [`CMFCPropertyGridCtrl::AddProperty`](#addproperty) method to add properties to the list. ## Selection Properties @@ -133,10 +132,10 @@ The following table lists four selection property types: |Class|Description| |-----------|-----------------| -|[CMFCPropertyGridProperty Class](../../mfc/reference/cmfcpropertygridproperty-class.md)|A general purpose property that is used to specify the value of strings, Booleans, dates and so on.| -|[CMFCPropertyGridColorProperty Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md)|A property that is used to select a color value.| -|[CMFCPropertyGridFileProperty Class](../../mfc/reference/cmfcpropertygridfileproperty-class.md)|A property that is used to select a file.| -|[CMFCPropertyGridFontProperty Class](../../mfc/reference/cmfcpropertygridfontproperty-class.md)|A property that is used to select a font.| +|[`CMFCPropertyGridProperty` Class](../../mfc/reference/cmfcpropertygridproperty-class.md)|A general purpose property that is used to specify the value of strings, Booleans, dates and so on.| +|[`CMFCPropertyGridColorProperty` Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md)|A property that is used to select a color value.| +|[`CMFCPropertyGridFileProperty` Class](../../mfc/reference/cmfcpropertygridfileproperty-class.md)|A property that is used to select a file.| +|[`CMFCPropertyGridFontProperty` Class](../../mfc/reference/cmfcpropertygridfontproperty-class.md)|A property that is used to select a font.| ## Illustrations @@ -156,19 +155,19 @@ The following example demonstrates how to configure a property grid control obje ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CMFCPropertyGridCtrl](../../mfc/reference/cmfcpropertygridctrl-class.md) +[`CMFCPropertyGridCtrl`](../../mfc/reference/cmfcpropertygridctrl-class.md) ## Requirements -**Header:** afxpropertygridctrl.h +**Header:** `afxpropertygridctrl.h` -## CMFCPropertyGridCtrl::accSelect +## `CMFCPropertyGridCtrl::accSelect` ``` virtual HRESULT accSelect( @@ -178,14 +177,14 @@ virtual HRESULT accSelect( ### Parameters -[in] *flagsSelect*
-[in] *varChild*
+[in] *`flagsSelect`*\ +[in] *`varChild`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::AddProperty +## `CMFCPropertyGridCtrl::AddProperty` Adds a new property to a property grid control. @@ -198,14 +197,14 @@ int AddProperty( ### Parameters -*pProp*
+*`pProp`*\ [in] Pointer to a property. -*bRedraw*
-[in] TRUE to redraw the property immediately; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property immediately; otherwise, `FALSE`. The default value is `TRUE`. -*bAdjustLayout*
-[in] TRUE to recalculate how to draw the text and value of the property, and then draw the property; FALSE to use existing calculations to draw the property. The default value is TRUE. +*`bAdjustLayout`*\ +[in] `TRUE` to recalculate how to draw the text and value of the property, and then draw the property; `FALSE` to use existing calculations to draw the property. The default value is `TRUE`. ### Return Value @@ -213,9 +212,9 @@ If this method succeeds, the zero-based index of the position in the property gr ### Remarks -This method adds a pointer to the specified property to the end of the list of properties in the property grid control. Do not destroy the properties or allow them to go out of scope before the grid control is destroyed. When you are done with the property grid control, call [CMFCPropertyGridCtrl::RemoveAll](#removeall) to delete all the added properties. The AddProperty method fails if the specified property has already been added to the list. +This method adds a pointer to the specified property to the end of the list of properties in the property grid control. Don't destroy the properties or allow them to go out of scope before the grid control is destroyed. When you're done with the property grid control, call [`CMFCPropertyGridCtrl::RemoveAll`](#removeall) to delete all the added properties. The AddProperty method fails if the specified property has already been added to the list. -## CMFCPropertyGridCtrl::AdjustLayout +## `CMFCPropertyGridCtrl::AdjustLayout` Redraws the property grid control and its properties. @@ -227,7 +226,7 @@ virtual void AdjustLayout(); This method recalculates how to draw the entire property grid control and its properties, including images, fonts, and controls. -## CMFCPropertyGridCtrl::AlwaysShowUserToolTip +## `CMFCPropertyGridCtrl::AlwaysShowUserToolTip` ```cpp void AlwaysShowUserToolTip(BOOL bShow = TRUE); @@ -235,11 +234,11 @@ void AlwaysShowUserToolTip(BOOL bShow = TRUE); ### Parameters -[in] *bShow*
+[in] *`bShow`* ### Remarks -## CMFCPropertyGridCtrl::CloseColorPopup +## `CMFCPropertyGridCtrl::CloseColorPopup` Closes the color selection dialog box. @@ -249,9 +248,9 @@ virtual void CloseColorPopup(); ### Remarks -For more information about the color selection dialog box, see [CMFCPropertyGridColorProperty Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md). +For more information about the color selection dialog box, see [`CMFCPropertyGridColorProperty` Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md). -## CMFCPropertyGridCtrl::CMFCPropertyGridCtrl +## `CMFCPropertyGridCtrl::CMFCPropertyGridCtrl` Constructs a `CMFCPropertyGridCtrl` object. @@ -263,7 +262,7 @@ CMFCPropertyGridCtrl(); ### Remarks -## CMFCPropertyGridCtrl::CompareProps +## `CMFCPropertyGridCtrl::CompareProps` Called by the property grid control to sort properties. @@ -275,25 +274,25 @@ virtual int CompareProps( ### Parameters -*pProp1*
+*`pProp1`*\ A pointer to a property. -*pProp2*
+*`pProp2`*\ A pointer to a property. ### Return Value |Return Value|Description| |------------------|-----------------| -|< 0|The name of the *pProp1* parameter is less than the name of the *pProp2* parameter.| -|0|The name of the *pProp1* parameter is equal to the name of the *pProp2* parameter.| -|> 0|The name of the *pProp1* object is greater than the name of the *pProp2* parameter.| +|< 0|The name of the *`pProp1`* parameter is less than the name of the *`pProp2`* parameter.| +|0|The name of the *`pProp1`* parameter is equal to the name of the *`pProp2`* parameter.| +|> 0|The name of the *`pProp1`* object is greater than the name of the *`pProp2`* parameter.| ### Remarks -By default, this method uses the [CString::Compare](../../atl-mfc-shared/reference/cstringt-class.md#compare) method to compare the `CMFCPropertyGridProperty::m_strName` members of the specified parameters. +By default, this method uses the [`CString::Compare`](../../atl-mfc-shared/reference/cstringt-class.md#compare) method to compare the `CMFCPropertyGridProperty::m_strName` members of the specified parameters. -## CMFCPropertyGridCtrl::Create +## `CMFCPropertyGridCtrl::Create` Creates a property grid control and attaches it to the property grid control object. @@ -307,25 +306,25 @@ virtual BOOL Create( ### Parameters -*dwStyle*
-[in] A bitwise combination (OR) of [window styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). +*`dwStyle`*\ +[in] A bitwise combination "or" (`|`) of [window styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). -*rect*
-[in] A bounding rectangle that specifies the size and position of the window, in client coordinates of *pParentWnd*. +*`rect`*\ +[in] A bounding rectangle that specifies the size and position of the window, in client coordinates of *`pParentWnd`*. -*pParentWnd*
-[in] Pointer to the parent window. Must not be NULL. +*`pParentWnd`*\ +[in] Pointer to the parent window. Must not be `NULL`. -*nID*
+*`nID`*\ [in] The ID of the child window. ### Return Value -TRUE if the window was created successfully; otherwise, FALSE. +`TRUE` if the window was created successfully; otherwise, `FALSE`. ### Remarks -To create a property grid control, first call [CMFCPropertyGridCtrl::CMFCPropertyGridCtrl](#cmfcpropertygridctrl) to construct a property grid object. Then call `CMFCPropertyGridCtrl::Create`. +To create a property grid control, first call [`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`](#cmfcpropertygridctrl) to construct a property grid object. Then call `CMFCPropertyGridCtrl::Create`. ### Example @@ -333,7 +332,7 @@ The following example demonstrates how to use the `Create` method in `CMFCProper [!code-cpp[NVC_MFC_NewControls#15](../../mfc/reference/codesnippet/cpp/cmfcpropertygridctrl-class_6.cpp)] -## CMFCPropertyGridCtrl::DeleteProperty +## `CMFCPropertyGridCtrl::DeleteProperty` Deletes the specified property from the property grid control. @@ -346,24 +345,24 @@ BOOL DeleteProperty( ### Parameters -*pProp*
+*`pProp`*\ [in] Pointer to a property. -*bRedraw*
-[in] TRUE to redraw the property grid control; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property grid control; otherwise, `FALSE`. The default value is `TRUE`. -*bAdjustLayout*
-[in] TRUE to recalculate how to draw all the text, images, and items in the property grid control, and then draw the control; otherwise, FALSE. The default value is TRUE. +*`bAdjustLayout`*\ +[in] `TRUE` to recalculate how to draw all the text, images, and items in the property grid control, and then draw the control; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks Use this method to delete a property, and any sub-items, from the property grid control. -## CMFCPropertyGridCtrl::DrawControlBarColors +## `CMFCPropertyGridCtrl::DrawControlBarColors` ``` BOOL DrawControlBarColors() const; @@ -373,7 +372,7 @@ BOOL DrawControlBarColors() const; ### Remarks -## CMFCPropertyGridCtrl::EditItem +## `CMFCPropertyGridCtrl::EditItem` Called by the framework when the user starts to modify a property. @@ -385,19 +384,19 @@ virtual BOOL EditItem( ### Parameters -*pProp*
+*`pProp`*\ [in] Pointer to a property. -*lptClick*
-[in] The point on the property grid control that the user clicked to begin the edit operation. The point is in the client coordinates of the control. The default value is NULL. +*`lptClick`*\ +[in] The point on the property grid control that the user clicked to begin the edit operation. The point is in the client coordinates of the control. The default value is `NULL`. ### Return Value -TRUE if method is successful; otherwise, FALSE. +`TRUE` if method is successful; otherwise, `FALSE`. ### Remarks -## CMFCPropertyGridCtrl::EnableDescriptionArea +## `CMFCPropertyGridCtrl::EnableDescriptionArea` Enables or disables the description area that is displayed underneath the list of properties in the property grid control. @@ -407,14 +406,14 @@ void EnableDescriptionArea(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the description area; FALSE to disable the description area. The default value is TRUE. +*`bEnable`*\ +[in] `TRUE` to enable the description area; `FALSE` to disable the description area. The default value is `TRUE`. ### Remarks The description area is displayed at the bottom of the property grid control. By default, the description area is disabled and not visible. -## CMFCPropertyGridCtrl::EnableHeaderCtrl +## `CMFCPropertyGridCtrl::EnableHeaderCtrl` Enables or disables the header control at the top of the property grid control. @@ -427,16 +426,16 @@ void EnableHeaderCtrl( ### Parameters -*bEnable*
-[in] TRUE to enable the header control; FALSE to disable the header control. The default value is TRUE. +*`bEnable`*\ +[in] `TRUE` to enable the header control; `FALSE` to disable the header control. The default value is `TRUE`. -*lpszLeftColumn*
-[in] The title of the left column of the header control. The default value is **Property**. +*`lpszLeftColumn`*\ +[in] The title of the left column of the header control. The default value is **`Property`**. -*lpszRightColumn*
-[in] The title of the right column of the header control. The default value is **Value**. +*`lpszRightColumn`*\ +[in] The title of the right column of the header control. The default value is **`Value`**. -## CMFCPropertyGridCtrl::EndEditItem +## `CMFCPropertyGridCtrl::EndEditItem` Called by the framework when the user finishes modifying a property. @@ -446,16 +445,16 @@ virtual BOOL EndEditItem(BOOL bUpdateData=TRUE); ### Parameters -*bUpdateData*
-[in] TRUE to specify that the modified property data must be validated when the edit operation is complete; otherwise, FALSE. The default value is TRUE. +*`bUpdateData`*\ +[in] `TRUE` to specify that the modified property data must be validated when the edit operation is complete; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -TRUE if the edit operation ends successfully; FALSE if the modified property data is not valid or if the editing operation should continue. +`TRUE` if the edit operation ends successfully; `FALSE` if the modified property data isn't valid or if the editing operation should continue. ### Remarks -## CMFCPropertyGridCtrl::EnsureVisible +## `CMFCPropertyGridCtrl::EnsureVisible` Scrolls a property grid control and expands property items until the specified property is visible. @@ -467,15 +466,15 @@ void EnsureVisible( ### Parameters -*pProp*
+*`pProp`*\ [in] Pointer to a property. -*bExpandParents*
-[in] TRUE to expand parent items to make the specified property visible; otherwise, FALSE. The default is FALSE. +*`bExpandParents`*\ +[in] `TRUE` to expand parent items to make the specified property visible; otherwise, `FALSE`. The default is `FALSE`. ### Remarks -## CMFCPropertyGridCtrl::ExpandAll +## `CMFCPropertyGridCtrl::ExpandAll` Expands or collapses all property grid control nodes. @@ -485,14 +484,14 @@ void ExpandAll(BOOL bExpand=TRUE); ### Parameters -*bExpand*
-[in] TRUE to expand all nodes; FALSE to collapse all nodes. The default value is TRUE. +*`bExpand`*\ +[in] `TRUE` to expand all nodes; `FALSE` to collapse all nodes. The default value is `TRUE`. ### Remarks -## CMFCPropertyGridCtrl::FindItemByData +## `CMFCPropertyGridCtrl::FindItemByData` -Retrieves the property that is associated with a user-defined DWORD value. +Retrieves the property that is associated with a user-defined `DWORD` value. ``` CMFCPropertyGridProperty* FindItemByData( @@ -502,21 +501,21 @@ CMFCPropertyGridProperty* FindItemByData( ### Parameters -*dwData*
-[in] A DWORD value. +*`dwData`*\ +[in] A `DWORD` value. -*bSearchSubItems*
-[in] TRUE to search property sub-items; otherwise, FALSE. The default value is TRUE. +*`bSearchSubItems`*\ +[in] `TRUE` to search property sub-items; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -A pointer to the associated property object if this method succeeds; otherwise, NULL. +A pointer to the associated property object if this method succeeds; otherwise, `NULL`. ### Remarks -Use the [CMFCPropertyGridCtrl::CMFCPropertyGridCtrl](#cmfcpropertygridctrl) constructor or [CMFCPropertyGridProperty::SetData](../../mfc/reference/cmfcpropertygridproperty-class.md#setdata) method to associate a DWORD with a property. +Use the [`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`](#cmfcpropertygridctrl) constructor or [`CMFCPropertyGridProperty::SetData`](../../mfc/reference/cmfcpropertygridproperty-class.md#setdata) method to associate a `DWORD` with a property. -## CMFCPropertyGridCtrl::get_accChildCount +## `CMFCPropertyGridCtrl::get_accChildCount` ``` virtual HRESULT get_accChildCount(long* pcountChildren); @@ -524,13 +523,13 @@ virtual HRESULT get_accChildCount(long* pcountChildren); ### Parameters -[in] *pcountChildren*
+[in] *`pcountChildren`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::get_accFocus +## `CMFCPropertyGridCtrl::get_accFocus` ``` virtual HRESULT get_accFocus(VARIANT* pvarChild); @@ -538,13 +537,13 @@ virtual HRESULT get_accFocus(VARIANT* pvarChild); ### Parameters -[in] *pvarChild*
+[in] *`pvarChild`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::get_accHelp +## `CMFCPropertyGridCtrl::get_accHelp` ``` virtual HRESULT get_accHelp( @@ -554,14 +553,14 @@ virtual HRESULT get_accHelp( ### Parameters -[in] *varChild*
-[in] *pszHelp*
+[in] *`varChild`*\ +[in] *`pszHelp`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::get_accHelpTopic +## `CMFCPropertyGridCtrl::get_accHelpTopic` ``` virtual HRESULT get_accHelpTopic( @@ -572,15 +571,15 @@ virtual HRESULT get_accHelpTopic( ### Parameters -[in] *pszHelpFile*
-[in] *varChild*
-[in] *pidTopic*
+[in] *`pszHelpFile`*\ +[in] *`varChild`*\ +[in] *`pidTopic`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::get_accKeyboardShortcut +## `CMFCPropertyGridCtrl::get_accKeyboardShortcut` ``` virtual HRESULT get_accKeyboardShortcut( @@ -590,14 +589,14 @@ virtual HRESULT get_accKeyboardShortcut( ### Parameters -[in] *varChild*
-[in] *pszKeyboardShortcut*
+[in] *`varChild`*\ +[in] *`pszKeyboardShortcut`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::get_accSelection +## `CMFCPropertyGridCtrl::get_accSelection` ``` virtual HRESULT get_accSelection(VARIANT* pvarChildren); @@ -605,13 +604,13 @@ virtual HRESULT get_accSelection(VARIANT* pvarChildren); ### Parameters -[in] *pvarChildren*
+[in] *`pvarChildren`* ### Return Value ### Remarks -## CMFCPropertyGridCtrl::GetBkColor +## `CMFCPropertyGridCtrl::GetBkColor` Retrieves the background color of the current property grid control. @@ -625,9 +624,9 @@ An RGB color value. ### Remarks -This method retrieves the color that the framework uses to draw the background of the current property grid control. The [CMFCPropertyGridCtrl::GetTextColor](#gettextcolor) method retrieves the foreground color. +This method retrieves the color that the framework uses to draw the background of the current property grid control. The [`CMFCPropertyGridCtrl::GetTextColor`](#gettextcolor) method retrieves the foreground color. -## CMFCPropertyGridCtrl::GetBoldFont +## `CMFCPropertyGridCtrl::GetBoldFont` Retrieves the Windows font that is used to draw text in the current property grid control in bold style. @@ -637,9 +636,9 @@ CFont& GetBoldFont(); ### Return Value -A reference to a [CFont](../../mfc/reference/cfont-class.md) object that describes the characteristics of a bold font. +A reference to a [`CFont`](../../mfc/reference/cfont-class.md) object that describes the characteristics of a bold font. -## CMFCPropertyGridCtrl::GetCurSel +## `CMFCPropertyGridCtrl::GetCurSel` Retrieves the currently selected property. @@ -653,7 +652,7 @@ A pointer to the property object that corresponds to the selected item in the pr ### Remarks -## CMFCPropertyGridCtrl::GetCustomColors +## `CMFCPropertyGridCtrl::GetCustomColors` Retrieves the custom colors that are currently defined for property grid control elements. @@ -670,32 +669,32 @@ void GetCustomColors( ### Parameters -*clrBackground*
+*`clrBackground`*\ [out] The background color of property values. -*clrText*
+*`clrText`*\ [out] The color of property names and property value text. -*clrGroupBackground*
+*`clrGroupBackground`*\ [out] The background color of a property group. -*clrGroupText*
+*`clrGroupText`*\ [out] The color of text in the property group. -*clrDescriptionBackground*
+*`clrDescriptionBackground`*\ [out] The background color of the description area. -*clrDescriptionText*
+*`clrDescriptionText`*\ [out] The color of text in the description area. -*clrLine*
+*`clrLine`*\ [out] The color of lines that are drawn between properties. ### Remarks -Use the [CMFCPropertyGridCtrl::SetCustomColors](#setcustomcolors) method to set custom colors. +Use the [`CMFCPropertyGridCtrl::SetCustomColors`](#setcustomcolors) method to set custom colors. -## CMFCPropertyGridCtrl::GetDescriptionHeight +## `CMFCPropertyGridCtrl::GetDescriptionHeight` Retrieves the height of the description area, which is located at the bottom of the property grid control. @@ -711,9 +710,9 @@ The height of the description area, in pixels. The height of the description area is calculated automatically and is set to 1/4 the height of the property grid control. -Use the [CMFCPropertyGridCtrl::EnableDescriptionArea](#enabledescriptionarea) method to display or hide the description area. Use the [CMFCPropertyGridCtrl::IsDescriptionArea](#isdescriptionarea) method to determine whether the description area is displayed or hidden. +Use the [`CMFCPropertyGridCtrl::EnableDescriptionArea`](#enabledescriptionarea) method to display or hide the description area. Use the [`CMFCPropertyGridCtrl::IsDescriptionArea`](#isdescriptionarea) method to determine whether the description area is displayed or hidden. -## CMFCPropertyGridCtrl::GetDescriptionRows +## `CMFCPropertyGridCtrl::GetDescriptionRows` Retrieves the number of rows in the description area of the current property grid control. @@ -727,11 +726,11 @@ The number of rows in the description area of the current property grid control. ### Remarks -The [CMFCPropertyGridCtrl::CMFCPropertyGridCtrl](#cmfcpropertygridctrl) constructor initializes the description area to 3 rows. +The [`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`](#cmfcpropertygridctrl) constructor initializes the description area to 3 rows. -## CMFCPropertyGridCtrl::GetHeaderCtrl +## `CMFCPropertyGridCtrl::GetHeaderCtrl` -Retrieves the internal [CMFCHeaderCtrl](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control. +Retrieves the internal [`CMFCHeaderCtrl`](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control. ``` virtual CMFCHeaderCtrl& GetHeaderCtrl(); @@ -741,7 +740,7 @@ virtual CMFCHeaderCtrl& GetHeaderCtrl(); A reference to a `CMFCHeaderCtrl` object. -## CMFCPropertyGridCtrl::GetHeaderHeight +## `CMFCPropertyGridCtrl::GetHeaderHeight` Retrieves the height of the header of a property grid control. @@ -755,7 +754,7 @@ The height of the header, in pixels. ### Remarks -## CMFCPropertyGridCtrl::GetLeftColumnWidth +## `CMFCPropertyGridCtrl::GetLeftColumnWidth` Retrieves of the width of the left column of the current property grid control, which contains the name of each property. @@ -771,7 +770,7 @@ The width of the name column. The right column of a property grid control contains the value of each property. -## CMFCPropertyGridCtrl::GetListRect +## `CMFCPropertyGridCtrl::GetListRect` Retrieves the bounding rectangle of the property grid control. @@ -781,11 +780,11 @@ CRect GetListRect() const; ### Return Value -The bounding rectangle of the property grid control. This rectange does not include the description area and header. +The bounding rectangle of the property grid control. This rectange doesn't include the description area and header. ### Remarks -## CMFCPropertyGridCtrl::GetProperty +## `CMFCPropertyGridCtrl::GetProperty` Retrieves a pointer to the property object that corresponds to the specified index of an item in a property grid control. @@ -795,10 +794,10 @@ CMFCPropertyGridProperty* GetProperty(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of a property grid control item. -This method asserts if the *nIndex* parameter is less than zero or greater than or equal to the number of properties. +This method asserts if the *`nIndex`* parameter is less than zero or greater than or equal to the number of properties. ### Return Value @@ -806,7 +805,7 @@ A pointer to the property object that corresponds to the specified index if this ### Remarks -## CMFCPropertyGridCtrl::GetPropertyColumnWidth +## `CMFCPropertyGridCtrl::GetPropertyColumnWidth` Retrieves the current width of the column that contains property values. @@ -822,7 +821,7 @@ The current width of the column that contains property values. The column on the right in the property grid control contains the property values. A customer can use the split box of the property grid control to change the width of the values column. -## CMFCPropertyGridCtrl::GetPropertyCount +## `CMFCPropertyGridCtrl::GetPropertyCount` Retrieves the number of properties in a property grid control. @@ -836,7 +835,7 @@ The number of properties. ### Remarks -## CMFCPropertyGridCtrl::GetRowHeight +## `CMFCPropertyGridCtrl::GetRowHeight` Retrieves the height of a row in the property grid control. @@ -852,7 +851,7 @@ The height of a row. The height of a row is equal to the current font height plus 4 pixels. -## CMFCPropertyGridCtrl::GetScrollBarCtrl +## `CMFCPropertyGridCtrl::GetScrollBarCtrl` Retrieves a pointer to the scroll bar control in the property grid control. @@ -862,18 +861,18 @@ virtual CScrollBar* GetScrollBarCtrl(int nBar) const; ### Parameters -*nBar*
-[in] The orientation of the scroll bar, which must be SB_VERT. +*`nBar`*\ +[in] The orientation of the scroll bar, which must be `SB_VERT`. ### Return Value -A pointer to a scroll bar object, or NULL if there is no scroll bar or the scroll bar orientation is SB_HORZ. +A pointer to a scroll bar object, or `NULL` if there's no scroll bar or the scroll bar orientation is `SB_HORZ`. ### Remarks Use this method to gain direct access to the vertical scroll bar control. -## CMFCPropertyGridCtrl::GetTextColor +## `CMFCPropertyGridCtrl::GetTextColor` Retrieves the color that is used to draw the text of property items in the current property grid control. @@ -887,9 +886,9 @@ An RGB color value. ### Remarks -This method retrieves the color that the framework uses to draw the foreground of the current property grid control. The [CMFCPropertyGridCtrl::GetBkColor](#getbkcolor) method retrieves the background color. +This method retrieves the color that the framework uses to draw the foreground of the current property grid control. The [`CMFCPropertyGridCtrl::GetBkColor`](#getbkcolor) method retrieves the background color. -## CMFCPropertyGridCtrl::HitTest +## `CMFCPropertyGridCtrl::HitTest` Retrieves a pointer to the property object that corresponds to a property grid control item if a specified point is in the item. This method also indicates the area in the property grid control that contains the point. @@ -902,26 +901,26 @@ CMFCPropertyGridProperty* HitTest( ### Parameters -*pt*
+*`pt`*\ [in] A point, in client coordinates. -*pnArea*
+*`pnArea`*\ [in, out] A pointer to a `ClickArea` variable. When this method returns, the variable indicates the *property area* that contains the specified point. For more information about a property area, see Remarks. -*bPropsOnly*
-[in] TRUE to test only the property area; FALSE to test the *description area* if the specified point is not in the property area. The default value is FALSE. For more information about the description area, see Remarks. +*`bPropsOnly`*\ +[in] `TRUE` to test only the property area; `FALSE` to test the *description area* if the specified point isn't in the property area. The default value is `FALSE`. For more information about the description area, see Remarks. ### Return Value -If the *bPropsOnly* parameter is TRUE and the specified point is in a property area, the return value is a pointer to the corresponding property object. In addition, the *pnArea* parameter is set to the particular area that contains the specified point. Otherwise, the return value is NULL and the *pnArea* parameter is not modified. +If the *`bPropsOnly`* parameter is `TRUE` and the specified point is in a property area, the return value is a pointer to the corresponding property object. In addition, the *`pnArea`* parameter is set to the particular area that contains the specified point. Otherwise, the return value is `NULL` and the *`pnArea`* parameter isn't modified. -If the *bPropsOnly* parameter is FALSE, the return value is always NULL. However, if the specified point is in the description area, the *pnArea* parameter is set to `CMFCPropertyGridProperty::ClickDescription`. +If the *`bPropsOnly`* parameter is `FALSE`, the return value is always `NULL`. However, if the specified point is in the description area, the *`pnArea`* parameter is set to `CMFCPropertyGridProperty::ClickDescription`. ### Remarks -The term *property area* refers to any one of the name, value, or expand box areas of a property grid control item. The *description area* is the zone at the bottom of a property grid control. When you click a property grid control item, the description area displays a description of the corresponding property. +The term *property area* refers to any one of the name, value, or expand box areas of a property grid control item. The *description area* is the zone at the bottom of a property grid control. When you select a property grid control item, the description area displays a description of the corresponding property. -This method sets the value of the variable that the *pnArea* parameter points to. The following table lists the possible values and corresponding areas. +This method sets the value of the variable that the *`pnArea`* parameter points to. The following table lists the possible values and corresponding areas. |Value|Area| |-----------|----------| @@ -930,7 +929,7 @@ This method sets the value of the variable that the *pnArea* parameter points to |`ClickArea::ClickValue`|Property value.| |`CMFCPropertyGridProperty::ClickDescription`|Property grid control description area.| -## CMFCPropertyGridCtrl::Init +## `CMFCPropertyGridCtrl::Init` Called by the framework to initialize a property grid control. @@ -940,15 +939,15 @@ virtual void Init(); ### Remarks -## CMFCPropertyGridCtrl::InitHeader +## `CMFCPropertyGridCtrl::InitHeader` -Initializes the internal [CMFCHeaderCtrl](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control. +Initializes the internal [`CMFCHeaderCtrl`](../../mfc/reference/cmfcheaderctrl-class.md) object that the framework uses to display the current property grid control. ``` virtual void InitHeader(); ``` -## CMFCPropertyGridCtrl::IsAlphabeticMode +## `CMFCPropertyGridCtrl::IsAlphabeticMode` Indicates whether a property grid control is in alphabetic mode. @@ -958,15 +957,15 @@ BOOL IsAlphabeticMode() const; ### Return Value -TRUE if the property grid control is in alphabetic mode; otherwise FALSE. +`TRUE` if the property grid control is in alphabetic mode; otherwise `FALSE`. ### Remarks When the property grid control is in alphabetic mode, all properties are sorted alphabetically by their names. Otherwise, properties are grouped under their parent nodes. -Use the [CMFCPropertyGridCtrl::SetAlphabeticMode](#setalphabeticmode) method to enable or disable alphabetic mode. +Use the [`CMFCPropertyGridCtrl::SetAlphabeticMode`](#setalphabeticmode) method to enable or disable alphabetic mode. -## CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip +## `CMFCPropertyGridCtrl::IsAlwaysShowUserToolTip` ``` BOOL IsAlwaysShowUserToolTip() const; @@ -976,7 +975,7 @@ BOOL IsAlwaysShowUserToolTip() const; ### Remarks -## CMFCPropertyGridCtrl::IsDescriptionArea +## `CMFCPropertyGridCtrl::IsDescriptionArea` Indicates whether the description area of the property grid control is displayed. @@ -986,13 +985,13 @@ BOOL IsDescriptionArea() const; ### Return Value -TRUE if the description area is displayed; otherwise, FALSE. +`TRUE` if the description area is displayed; otherwise, `FALSE`. ### Remarks -Use the [CMFCPropertyGridCtrl::EnableDescriptionArea](#enabledescriptionarea) method to hide or display the description area. +Use the [`CMFCPropertyGridCtrl::EnableDescriptionArea`](#enabledescriptionarea) method to hide or display the description area. -## CMFCPropertyGridCtrl::IsGroupNameFullWidth +## `CMFCPropertyGridCtrl::IsGroupNameFullWidth` Indicates whether each property group name is displayed across the width of the current property grid control. @@ -1002,13 +1001,13 @@ BOOL IsGroupNameFullWidth() const; ### Return Value -TRUE if group names are displayed across the width of the property grid control; FALSE if group names are truncated by the right (value) column of the control. +`TRUE` if group names are displayed across the width of the property grid control; `FALSE` if group names are truncated by the right (value) column of the control. ### Remarks A *group* is a collection of related properties in a property grid control. If the control is displayed hierarchically, the *group name* is displayed as a category title in the row above the group. -## CMFCPropertyGridCtrl::IsHeaderCtrl +## `CMFCPropertyGridCtrl::IsHeaderCtrl` Indicates whether the header control is displayed. @@ -1018,13 +1017,13 @@ BOOL IsHeaderCtrl() const; ### Return Value -TRUE if the header control is displayed; otherwise FALSE. +`TRUE` if the header control is displayed; otherwise `FALSE`. ### Remarks -Use the [CMFCPropertyGridCtrl::EnableHeaderCtrl](#enableheaderctrl) method to hide or display the header control. +Use the [`CMFCPropertyGridCtrl::EnableHeaderCtrl`](#enableheaderctrl) method to hide or display the header control. -## CMFCPropertyGridCtrl::IsMarkModifiedProperties +## `CMFCPropertyGridCtrl::IsMarkModifiedProperties` Indicates how the property grid control displays modified properties. @@ -1034,11 +1033,11 @@ BOOL IsMarkModifiedProperties() const; ### Return Value -TRUE if bold style is used to display modified properties; FALSE if regular style is used to display modified properties. +`TRUE` if bold style is used to display modified properties; `FALSE` if regular style is used to display modified properties. ### Remarks -## CMFCPropertyGridCtrl::IsShowDragContext +## `CMFCPropertyGridCtrl::IsShowDragContext` Indicates whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns. @@ -1048,13 +1047,13 @@ BOOL IsShowDragContext() const; ### Return Value -TRUE if the framework redraws the name and value columns during a resize operation; FALSE if the framework redraws the columns after the drag operation is completed. +`TRUE` if the framework redraws the name and value columns during a resize operation; `FALSE` if the framework redraws the columns after the drag operation is completed. ### Remarks -The user can resize the name and value columns of a property grid control by dragging the split bar that is between the columns. If the drag context is displayed, the name and value columns are resized as long as the user drags the split bar. Otherwise, the split bar moves but the columns are not redrawn until the drag operation is completed. +The user can resize the name and value columns of a property grid control by dragging the split bar that is between the columns. If the drag context is displayed, the name and value columns are resized as long as the user drags the split bar. Otherwise, the split bar moves but the columns aren't redrawn until the drag operation is completed. -## CMFCPropertyGridCtrl::IsVSDotNetLook +## `CMFCPropertyGridCtrl::IsVSDotNetLook` Indicates whether the appearance of the property grid control is in the style of Visual Studio .NET. @@ -1064,13 +1063,13 @@ BOOL IsVSDotNetLook() const; ### Return Value -TRUE if the property grid control is in the style of Visual Studio .NET; otherwise, FALSE. +`TRUE` if the property grid control is in the style of Visual Studio .NET; otherwise, `FALSE`. ### Remarks -Use the [CMFCPropertyGridCtrl::SetVSDotNetLook](#setvsdotnetlook) method to set the property grid control to the style of Visual Studio .NET. +Use the [`CMFCPropertyGridCtrl::SetVSDotNetLook`](#setvsdotnetlook) method to set the property grid control to the style of Visual Studio .NET. -## CMFCPropertyGridCtrl::MarkModifiedProperties +## `CMFCPropertyGridCtrl::MarkModifiedProperties` Specifies how to display modified properties. @@ -1082,15 +1081,15 @@ void MarkModifiedProperties( ### Parameters -*bMark*
-[in] TRUE to display modified properties in bold style; FALSE to display modified properties in regular style. The default value is TRUE. +*`bMark`*\ +[in] `TRUE` to display modified properties in bold style; `FALSE` to display modified properties in regular style. The default value is `TRUE`. -*bRedraw*
-[in] TRUE to redraw the property grid control immediately; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property grid control immediately; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCPropertyGridCtrl::OnChangeSelection +## `CMFCPropertyGridCtrl::OnChangeSelection` Called by the framework when the current selection is changed. @@ -1102,17 +1101,17 @@ virtual void OnChangeSelection( ### Parameters -*pNewSel*\ +*`pNewSel`*\ [in] Pointer to the newly selected property. -*pOldSel*\ +*`pOldSel`*\ [in] Pointer to the previously selected property. ### Remarks The default implementation of this method does nothing. -## CMFCPropertyGridCtrl::OnClickButton +## `CMFCPropertyGridCtrl::OnClickButton` Called by the framework when a property button is clicked. @@ -1122,14 +1121,14 @@ virtual void OnClickButton(CPoint point); ### Parameters -*point*
+*`point`*\ [in] A point, in client coordinates. ### Remarks By default, this method updates the current property value. -## CMFCPropertyGridCtrl::OnDrawBorder +## `CMFCPropertyGridCtrl::OnDrawBorder` Called by the framework to draw a border around a property grid control. @@ -1139,12 +1138,12 @@ virtual void OnDrawBorder(CDC* pDC); ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. ### Remarks -## CMFCPropertyGridCtrl::OnDrawDescription +## `CMFCPropertyGridCtrl::OnDrawDescription` Called by the framework to draw the description area and display the description text. @@ -1156,17 +1155,17 @@ virtual void OnDrawDescription( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rect*
+*`rect`*\ [in] A rectangle that specifies where to draw the description area. ### Remarks -Use the [CMFCPropertyGridCtrl::EnableDescriptionArea](#enabledescriptionarea) method to display the description area. +Use the [`CMFCPropertyGridCtrl::EnableDescriptionArea`](#enabledescriptionarea) method to display the description area. -## CMFCPropertyGridCtrl::OnDrawList +## `CMFCPropertyGridCtrl::OnDrawList` Called by the framework to display the list of properties in the property grid control. @@ -1176,12 +1175,12 @@ virtual void OnDrawList(CDC* pDC); ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. ### Remarks -## CMFCPropertyGridCtrl::OnDrawProperty +## `CMFCPropertyGridCtrl::OnDrawProperty` Called by the framework to display a property. @@ -1193,19 +1192,19 @@ virtual int OnDrawProperty( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*pProp*
+*`pProp`*\ [in] A pointer to a property object. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks -## CMFCPropertyGridCtrl::OnPropertyChanged +## `CMFCPropertyGridCtrl::OnPropertyChanged` Called by the framework when the value of a property is changed. @@ -1215,14 +1214,14 @@ virtual void OnPropertyChanged(CMFCPropertyGridProperty* pProp) const; ### Parameters -*pProp*
+*`pProp`*\ [in] A pointer to a property object whose value has changed. ### Remarks -By default, this method sends the [AFX_WM_PROPERTY_CHANGED](../../mfc/reference/afx-messages.md) message to the owner of the property grid control. +By default, this method sends the [`AFX_WM_PROPERTY_CHANGED`](../../mfc/reference/afx-messages.md) message to the owner of the property grid control. -## CMFCPropertyGridCtrl::OnSelectCombo +## `CMFCPropertyGridCtrl::OnSelectCombo` Called by the framework when a property that contains a combo box control is selected. @@ -1232,7 +1231,7 @@ void OnSelectCombo(); ### Remarks -## CMFCPropertyGridCtrl::RemoveAll +## `CMFCPropertyGridCtrl::RemoveAll` Removes all property objects from a property grid control. @@ -1242,7 +1241,7 @@ void RemoveAll(); ### Remarks -## CMFCPropertyGridCtrl::ResetOriginalValues +## `CMFCPropertyGridCtrl::ResetOriginalValues` Restores the original values of all properties. @@ -1252,12 +1251,12 @@ void ResetOriginalValues(BOOL bRedraw=TRUE); ### Parameters -*bRedraw*
-[in] TRUE to redraw the property list; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property list; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCPropertyGridCtrl::SetAlphabeticMode +## `CMFCPropertyGridCtrl::SetAlphabeticMode` Sets or resets alphabetic mode. @@ -1267,14 +1266,14 @@ void SetAlphabeticMode(BOOL bSet=TRUE); ### Parameters -*bSet*
-[in] TRUE to set alphabetic mode; FALSE reset alphabetic mode. The default value is TRUE. +*`bSet`*\ +[in] `TRUE` to set alphabetic mode; `FALSE` reset alphabetic mode. The default value is `TRUE`. ### Remarks When the property grid control is in alphabetic mode, the control sorts all the properties it contains by their property name. -## CMFCPropertyGridCtrl::SetBoolLabels +## `CMFCPropertyGridCtrl::SetBoolLabels` Specifies the text of Boolean labels. @@ -1286,15 +1285,15 @@ void SetBoolLabels( ### Parameters -*lpszTrue*
+*`lpszTrue`*\ [in] The text string to display for the Boolean value of true. -*lpszFalse*
+*`lpszFalse`*\ [in] The text string to display for the Boolean value of false. ### Remarks -## CMFCPropertyGridCtrl::SetCurSel +## `CMFCPropertyGridCtrl::SetCurSel` Selects a property in a property grid control. @@ -1306,17 +1305,17 @@ void SetCurSel( ### Parameters -*pProp*
+*`pProp`*\ [in] A pointer to a property object. -*bRedraw*
-[in] TRUE to redraw the property grid control immediately; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property grid control immediately; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks Use this method to cancel the selection of the current item in the property grid control and then select the item that corresponds to the specified property. -## CMFCPropertyGridCtrl::SetCustomColors +## `CMFCPropertyGridCtrl::SetCustomColors` Specifies custom colors for various elements of the property grid control. @@ -1333,34 +1332,34 @@ void SetCustomColors( ### Parameters -*clrBackground*
+*`clrBackground`*\ [in] The background color of property values. -*clrText*
+*`clrText`*\ [in] The color of property names and property value text. -*clrGroupBackground*
+*`clrGroupBackground`*\ [in] The background color of a property group. -*clrGroupText*
+*`clrGroupText`*\ [in] The new text color of property group. -*clrDescriptionBackground*
+*`clrDescriptionBackground`*\ [in] The background color of the description area. -*clrDescriptionText*
+*`clrDescriptionText`*\ [in] The color of text in the description area. -*clrLine*
+*`clrLine`*\ [in] The color of lines that are drawn between properties. ### Remarks For any parameter, specify the `((COLORREF)-1)` color value to use the default color for that element of the property grid control. -To customize the appearance of a specific property, derive a class from the [CMFCPropertyGridProperty](../../mfc/reference/cmfcpropertygridproperty-class.md) class and then override the [CMFCPropertyGridProperty::OnDrawName](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawname), [CMFCPropertyGridProperty::OnDrawValue](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawvalue), [CMFCPropertyGridProperty::OnDrawExpandBox](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawexpandbox), and [CMFCPropertyGridProperty::OnDrawButton](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawbutton) methods. +To customize the appearance of a specific property, derive a class from the [`CMFCPropertyGridProperty`](../../mfc/reference/cmfcpropertygridproperty-class.md) class and then override the [`CMFCPropertyGridProperty::OnDrawName`](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawname), [`CMFCPropertyGridProperty::OnDrawValue`](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawvalue), [`CMFCPropertyGridProperty::OnDrawExpandBox`](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawexpandbox), and [`CMFCPropertyGridProperty::OnDrawButton`](../../mfc/reference/cmfcpropertygridproperty-class.md#ondrawbutton) methods. -## CMFCPropertyGridCtrl::SetDescriptionRows +## `CMFCPropertyGridCtrl::SetDescriptionRows` Specifies the number of rows to display in the description section of the current property grid control. @@ -1370,10 +1369,10 @@ void SetDescriptionRows(int nDescRows); ### Parameters -*nDescRows*
+*`nDescRows`*\ [in] The number of rows to display in the property description. -## CMFCPropertyGridCtrl::SetGroupNameFullWidth +## `CMFCPropertyGridCtrl::SetGroupNameFullWidth` Specifies whether to display the full width of the category name for a group of properties in the current property grid control. @@ -1385,11 +1384,11 @@ void SetGroupNameFullWidth( ### Parameters -*bGroupNameFullWidth*
-[in] TRUE to display the complete width of the category name regardless of the width of the property name column. FALSE to limit the width of the category name to the width of the property name column. The default value is TRUE. +*`bGroupNameFullWidth`*\ +[in] `TRUE` to display the complete width of the category name regardless of the width of the property name column. `FALSE` to limit the width of the category name to the width of the property name column. The default value is `TRUE`. -*bRedraw*
-[in] TRUE to update the property grid control immediately; FALSE to update the control when the next redraw event occurs. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to update the property grid control immediately; `FALSE` to update the control when the next redraw event occurs. The default value is `TRUE`. ### Remarks @@ -1397,7 +1396,7 @@ The property grid control consists of a resizable *property name* column and a * The terms *group name* and *category name* are used interchangeably in this method. The category name is displayed on a row that heads a set of related properties and values. This method specifies whether the width of the property name column also specifies the width of the displayed category name. -## CMFCPropertyGridCtrl::SetListDelimiter +## `CMFCPropertyGridCtrl::SetListDelimiter` Defines a character that is used as a delimiter in a list of property values. @@ -1407,16 +1406,16 @@ void SetListDelimiter(TCHAR c); ### Parameters -*c*
+*`c`*\ [in] A character to serve as a delimiter. ### Remarks -Use this method to define a delimiter character in a list of property values that are used in the [CMFCPropertyGridProperty::CMFCPropertyGridProperty](../../mfc/reference/cmfcpropertygridproperty-class.md#cmfcpropertygridproperty) constructor. In that constructor, set the *bIsValueList* parameter to TRUE. +Use this method to define a delimiter character in a list of property values that are used in the [`CMFCPropertyGridProperty::CMFCPropertyGridProperty`](../../mfc/reference/cmfcpropertygridproperty-class.md#cmfcpropertygridproperty) constructor. In that constructor, set the *`bIsValueList`* parameter to `TRUE`. -By default, the [CMFCPropertyGridCtrl::CMFCPropertyGridCtrl](#cmfcpropertygridctrl) constructor sets the delimiter character to comma (','). +By default, the [`CMFCPropertyGridCtrl::CMFCPropertyGridCtrl`](#cmfcpropertygridctrl) constructor sets the delimiter character to comma (','). -## CMFCPropertyGridCtrl::SetShowDragContext +## `CMFCPropertyGridCtrl::SetShowDragContext` Specifies whether the framework redraws the name and value columns of the current property grid control when a user resizes the columns. @@ -1426,14 +1425,14 @@ void SetShowDragContext(BOOL bShowDragContext = TRUE); ### Parameters -*bShowDragContext*
-[in] TRUE to redraw the name and value columns during a resize operation; FALSE to redraw the columns after the drag operation is completed. The default value is TRUE. +*`bShowDragContext`*\ +[in] `TRUE` to redraw the name and value columns during a resize operation; `FALSE` to redraw the columns after the drag operation is completed. The default value is `TRUE`. ### Remarks -The user can resize the name and value columns of a property grid control by dragging the split bar that is between the columns. If the drag context is displayed, the name and value columns are resized as long as the user drags the split bar. Otherwise, the split bar moves but the columns are not redrawn until the drag operation is completed. +The user can resize the name and value columns of a property grid control by dragging the split bar that is between the columns. If the drag context is displayed, the name and value columns are resized as long as the user drags the split bar. Otherwise, the split bar moves but the columns aren't redrawn until the drag operation is completed. -## CMFCPropertyGridCtrl::SetVSDotNetLook +## `CMFCPropertyGridCtrl::SetVSDotNetLook` Sets the appearance of the property grid control to the style that is used in Visual Studio .NET. @@ -1443,12 +1442,12 @@ void SetVSDotNetLook(BOOL bSet=TRUE); ### Parameters -*bSet*
-[in] TRUE to set the property grid control to the style that is used in Visual Studio .NET; otherwise, FALSE. The default value is TRUE. +*`bSet`*\ +[in] `TRUE` to set the property grid control to the style that is used in Visual Studio .NET; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCPropertyGridCtrl::UpdateColor +## `CMFCPropertyGridCtrl::UpdateColor` Sets the color value of the currently selected color property. @@ -1458,14 +1457,14 @@ virtual void UpdateColor(COLORREF color); ### Parameters -*color*
+*`color`*\ [in] An RGB color value. ### Remarks -This method asserts in debug mode if the currently selected property of the property grid control is not a color property. +This method asserts in debug mode if the currently selected property of the property grid control isn't a color property. -## CMFCPropertyGridCtrl::ValidateItemData +## `CMFCPropertyGridCtrl::ValidateItemData` Called by the framework to validate property data. @@ -1475,20 +1474,20 @@ virtual BOOL ValidateItemData(CMFCPropertyGridProperty* pProp); ### Parameters -*pProp*\ -[in] Pointer to a property. This parameter is not used. +*`pProp`*\ +[in] Pointer to a property. This parameter isn't used. ### Return Value -Always TRUE. +Always `TRUE`. ### Remarks -The [CMFCPropertyGridCtrl::EndEditItem](#endedititem) method calls this method to validate data. By default, this method does not use its *pProp* parameter and its return value is always TRUE. +The [`CMFCPropertyGridCtrl::EndEditItem`](#endedititem) method calls this method to validate data. By default, this method doesn't use its *`pProp`* parameter and its return value is always `TRUE`. -If you override this method, return TRUE if the specified property data is valid. Otherwise, return FALSE, in which case the framework does not update the property. +If you override this method, return `TRUE` if the specified property data is valid. Otherwise, return `FALSE`, in which case the framework doesn't update the property. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Classes](../../mfc/reference/mfc-classes.md) diff --git a/docs/mfc/reference/cmfcpropertygridproperty-class.md b/docs/mfc/reference/cmfcpropertygridproperty-class.md index f7ae107fc4..8bf3752df3 100644 --- a/docs/mfc/reference/cmfcpropertygridproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridproperty-class.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: CMFCPropertyGridProperty Class" -title: "CMFCPropertyGridProperty Class" -ms.date: "11/04/2016" +title: "CMFCPropertyGridProperty class" +description: "Learn more about: CMFCPropertyGridProperty class" +ms.date: 10/12/2022 f1_keywords: ["CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AddOption", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AddSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AdjustButtonRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AdjustInPlaceEditRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AllowEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateInPlaceEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateSpinControl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Enable", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::EnableSpinControl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Expand", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::FormatProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetData", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetExpandedSubItems", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetHierarchyLevel", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetNameTooltip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOption", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOptionCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetParent", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetSubItemsCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetValueTooltip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::HitTest", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsAllowEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsEnabled", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsExpanded", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsGroup", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsInPlaceEditing", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsModified", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsParentExpanded", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsSelected", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsVisible", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnCloseCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDblClk", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawExpandBox", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnEndEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnKillSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnPosSizeChanged", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnRClickName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnRClickValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSelectCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSetCursor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSetSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnUpdateValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::PushChar", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Redraw", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::RemoveAllOptions", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::RemoveSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::ResetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetData", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Show", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::HasButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Init", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsValueChanged", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnCtlColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDestroyWindow", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnKillFocus", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatDouble", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatFloat", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatLong", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatShort"] helpviewer_keywords: ["CMFCPropertyGridProperty [MFC], CMFCPropertyGridProperty", "CMFCPropertyGridProperty [MFC], AddOption", "CMFCPropertyGridProperty [MFC], AddSubItem", "CMFCPropertyGridProperty [MFC], AdjustButtonRect", "CMFCPropertyGridProperty [MFC], AdjustInPlaceEditRect", "CMFCPropertyGridProperty [MFC], AllowEdit", "CMFCPropertyGridProperty [MFC], CreateInPlaceEdit", "CMFCPropertyGridProperty [MFC], CreateSpinControl", "CMFCPropertyGridProperty [MFC], Enable", "CMFCPropertyGridProperty [MFC], EnableSpinControl", "CMFCPropertyGridProperty [MFC], Expand", "CMFCPropertyGridProperty [MFC], FormatProperty", "CMFCPropertyGridProperty [MFC], GetData", "CMFCPropertyGridProperty [MFC], GetDescription", "CMFCPropertyGridProperty [MFC], GetExpandedSubItems", "CMFCPropertyGridProperty [MFC], GetHierarchyLevel", "CMFCPropertyGridProperty [MFC], GetName", "CMFCPropertyGridProperty [MFC], GetNameTooltip", "CMFCPropertyGridProperty [MFC], GetOption", "CMFCPropertyGridProperty [MFC], GetOptionCount", "CMFCPropertyGridProperty [MFC], GetOriginalValue", "CMFCPropertyGridProperty [MFC], GetParent", "CMFCPropertyGridProperty [MFC], GetRect", "CMFCPropertyGridProperty [MFC], GetSubItem", "CMFCPropertyGridProperty [MFC], GetSubItemsCount", "CMFCPropertyGridProperty [MFC], GetValue", "CMFCPropertyGridProperty [MFC], GetValueTooltip", "CMFCPropertyGridProperty [MFC], HitTest", "CMFCPropertyGridProperty [MFC], IsAllowEdit", "CMFCPropertyGridProperty [MFC], IsEnabled", "CMFCPropertyGridProperty [MFC], IsExpanded", "CMFCPropertyGridProperty [MFC], IsGroup", "CMFCPropertyGridProperty [MFC], IsInPlaceEditing", "CMFCPropertyGridProperty [MFC], IsModified", "CMFCPropertyGridProperty [MFC], IsParentExpanded", "CMFCPropertyGridProperty [MFC], IsSelected", "CMFCPropertyGridProperty [MFC], IsVisible", "CMFCPropertyGridProperty [MFC], OnClickButton", "CMFCPropertyGridProperty [MFC], OnClickName", "CMFCPropertyGridProperty [MFC], OnClickValue", "CMFCPropertyGridProperty [MFC], OnCloseCombo", "CMFCPropertyGridProperty [MFC], OnDblClk", "CMFCPropertyGridProperty [MFC], OnDrawButton", "CMFCPropertyGridProperty [MFC], OnDrawDescription", "CMFCPropertyGridProperty [MFC], OnDrawExpandBox", "CMFCPropertyGridProperty [MFC], OnDrawName", "CMFCPropertyGridProperty [MFC], OnDrawValue", "CMFCPropertyGridProperty [MFC], OnEdit", "CMFCPropertyGridProperty [MFC], OnEndEdit", "CMFCPropertyGridProperty [MFC], OnKillSelection", "CMFCPropertyGridProperty [MFC], OnPosSizeChanged", "CMFCPropertyGridProperty [MFC], OnRClickName", "CMFCPropertyGridProperty [MFC], OnRClickValue", "CMFCPropertyGridProperty [MFC], OnSelectCombo", "CMFCPropertyGridProperty [MFC], OnSetCursor", "CMFCPropertyGridProperty [MFC], OnSetSelection", "CMFCPropertyGridProperty [MFC], OnUpdateValue", "CMFCPropertyGridProperty [MFC], PushChar", "CMFCPropertyGridProperty [MFC], Redraw", "CMFCPropertyGridProperty [MFC], RemoveAllOptions", "CMFCPropertyGridProperty [MFC], RemoveSubItem", "CMFCPropertyGridProperty [MFC], ResetOriginalValue", "CMFCPropertyGridProperty [MFC], SetData", "CMFCPropertyGridProperty [MFC], SetDescription", "CMFCPropertyGridProperty [MFC], SetName", "CMFCPropertyGridProperty [MFC], SetOriginalValue", "CMFCPropertyGridProperty [MFC], SetValue", "CMFCPropertyGridProperty [MFC], Show", "CMFCPropertyGridProperty [MFC], CreateCombo", "CMFCPropertyGridProperty [MFC], HasButton", "CMFCPropertyGridProperty [MFC], Init", "CMFCPropertyGridProperty [MFC], IsSubItem", "CMFCPropertyGridProperty [MFC], IsValueChanged", "CMFCPropertyGridProperty [MFC], OnCtlColor", "CMFCPropertyGridProperty [MFC], OnDestroyWindow", "CMFCPropertyGridProperty [MFC], OnKillFocus", "CMFCPropertyGridProperty [MFC], m_strFormatDouble", "CMFCPropertyGridProperty [MFC], m_strFormatFloat", "CMFCPropertyGridProperty [MFC], m_strFormatLong", "CMFCPropertyGridProperty [MFC], m_strFormatShort"] -ms.assetid: 36f3fabe-0efe-468b-8a0b-5a7956db38a2 --- -# CMFCPropertyGridProperty Class +# `CMFCPropertyGridProperty` class A `CMFCPropertyGridProperty` object represents a list item in a property list control. - For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. + For more detail, see the source code located in the **`mfc`** folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ## Syntax -``` +```cpp class CMFCPropertyGridProperty : public CObject ``` @@ -24,131 +23,131 @@ class CMFCPropertyGridProperty : public CObject |Name|Description| |----------|-----------------| -|[CMFCPropertyGridProperty::CMFCPropertyGridProperty](#cmfcpropertygridproperty)|Constructs a `CMFCPropertyGridProperty` object.| +|[`CMFCPropertyGridProperty::CMFCPropertyGridProperty`](#cmfcpropertygridproperty)|Constructs a `CMFCPropertyGridProperty` object.| |`CMFCPropertyGridProperty::~CMFCPropertyGridProperty`|Destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CMFCPropertyGridProperty::AddOption](#addoption)|Adds a new list item to a property list control.| -|[CMFCPropertyGridProperty::AddSubItem](#addsubitem)|Adds a child item to a property.| -|[CMFCPropertyGridProperty::AdjustButtonRect](#adjustbuttonrect)|Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button.| -|[CMFCPropertyGridProperty::AdjustInPlaceEditRect](#adjustinplaceeditrect)|Retrieves the boundaries of the text box and optional spin button control that are used to set a property value.| -|[CMFCPropertyGridProperty::AllowEdit](#allowedit)|Makes a property either editable or read-only.| -|[CMFCPropertyGridProperty::CreateInPlaceEdit](#createinplaceedit)|Called by the framework to create an editable control for a property.| -|[CMFCPropertyGridProperty::CreateSpinControl](#createspincontrol)|Called by the framework to create an editable spin button control.| -|[CMFCPropertyGridProperty::Enable](#enable)|Enables or disables a property.| -|[CMFCPropertyGridProperty::EnableSpinControl](#enablespincontrol)|Enables or disables a spin button control that is used to modify a property value.| -|[CMFCPropertyGridProperty::Expand](#expand)|Expands or collapses a property that contains sub-properties.| -|[CMFCPropertyGridProperty::FormatProperty](#formatproperty)|Formats the text representation of a property value.| -|[CMFCPropertyGridProperty::GetData](#getdata)|Retrieves a DWORD value that is associated with a property.| -|[CMFCPropertyGridProperty::GetDescription](#getdescription)|Retrieves a property description.| -|[CMFCPropertyGridProperty::GetExpandedSubItems](#getexpandedsubitems)|Retrieves the number of expanded sub-items.| -|[CMFCPropertyGridProperty::GetHierarchyLevel](#gethierarchylevel)|Retrieves the zero-based index of the property's hierarchy level.| -|[CMFCPropertyGridProperty::GetName](#getname)|Retrieves the name of the property.| -|[CMFCPropertyGridProperty::GetNameTooltip](#getnametooltip)|Called by the framework to display the name of the property in a tooltip.| -|[CMFCPropertyGridProperty::GetOption](#getoption)|Retrieves the text of the option that is specified by an index.| -|[CMFCPropertyGridProperty::GetOptionCount](#getoptioncount)|Retrieves the number of options that belong to a property.| -|[CMFCPropertyGridProperty::GetOriginalValue](#getoriginalvalue)|Retrieves the initial value of the current property.| -|[CMFCPropertyGridProperty::GetParent](#getparent)|Retrieves a pointer to a parent property.| -|[CMFCPropertyGridProperty::GetRect](#getrect)|Retrieves the bounding rectangle of a property.| -|[CMFCPropertyGridProperty::GetSubItem](#getsubitem)|Retrieves a sub-property identified by a zero-based index.| -|[CMFCPropertyGridProperty::GetSubItemsCount](#getsubitemscount)|Retrieves the number of sub-items.| -|`CMFCPropertyGridProperty::GetThisClass`|Used by the framework to obtain a pointer to the [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| -|[CMFCPropertyGridProperty::GetValue](#getvalue)|Retrieves a property value.| -|[CMFCPropertyGridProperty::GetValueTooltip](#getvaluetooltip)|Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.| -|[CMFCPropertyGridProperty::HitTest](#hittest)|Points to the property object that corresponds to the property list item that corresponds to a point.| -|[CMFCPropertyGridProperty::IsAllowEdit](#isallowedit)|Indicates whether a property is editable.| -|[CMFCPropertyGridProperty::IsEnabled](#isenabled)|Indicates whether a property is enabled or disabled.| -|[CMFCPropertyGridProperty::IsExpanded](#isexpanded)|Indicates whether a property is expanded or collapsed.| -|[CMFCPropertyGridProperty::IsGroup](#isgroup)|Indicates whether the current property represents a group.| -|[CMFCPropertyGridProperty::IsInPlaceEditing](#isinplaceediting)|Indicates whether the current property is editable.| -|[CMFCPropertyGridProperty::IsModified](#ismodified)|Indicates whether the current property is modified.| -|[CMFCPropertyGridProperty::IsParentExpanded](#isparentexpanded)|Indicates whether the parents of the current property are expanded.| -|[CMFCPropertyGridProperty::IsSelected](#isselected)|Indicates whether the current property is selected.| -|[CMFCPropertyGridProperty::IsVisible](#isvisible)|Indicates whether the current property is visible.| -|[CMFCPropertyGridProperty::OnClickButton](#onclickbutton)|Called by the framework when the user clicks a button that is contained in a property.| -|[CMFCPropertyGridProperty::OnClickName](#onclickname)|Called by a parent property list control when a user clicks the name field of a property.| -|[CMFCPropertyGridProperty::OnClickValue](#onclickvalue)|Called by a parent property list control when a user clicks the value field of a property.| -|[CMFCPropertyGridProperty::OnCloseCombo](#onclosecombo)|Called by the framework when a combo box that is contained in a property is closed.| -|[CMFCPropertyGridProperty::OnDblClk](#ondblclk)|Called by the framework when the user double clicks a property.| -|[CMFCPropertyGridProperty::OnDrawButton](#ondrawbutton)|Called by the framework to draw a button that is contained in a property.| -|[CMFCPropertyGridProperty::OnDrawDescription](#ondrawdescription)|Called by the framework to display the property description.| -|[CMFCPropertyGridProperty::OnDrawExpandBox](#ondrawexpandbox)|Called by the framework to draw an expand box control near a property that contains sub-properties.| -|[CMFCPropertyGridProperty::OnDrawName](#ondrawname)|Called by the framework to display the property name.| -|[CMFCPropertyGridProperty::OnDrawValue](#ondrawvalue)|Called by the framework to display the property value.| -|[CMFCPropertyGridProperty::OnEdit](#onedit)|Called by the framework when the user is about to modify a property value.| -|[CMFCPropertyGridProperty::OnEndEdit](#onendedit)|Called by the framework when the user is finished modifying a property value.| -|[CMFCPropertyGridProperty::OnKillSelection](#onkillselection)|| -|[CMFCPropertyGridProperty::OnPosSizeChanged](#onpossizechanged)|| -|[CMFCPropertyGridProperty::OnRClickName](#onrclickname)|Called by the framework when the user clicks the right mouse button in the property name area.| -|[CMFCPropertyGridProperty::OnRClickValue](#onrclickvalue)|Called by the framework when the user clicks the right mouse button in the property value area.| -|[CMFCPropertyGridProperty::OnSelectCombo](#onselectcombo)|Called by the framework when the user selects an item from the editable combo box.| -|[CMFCPropertyGridProperty::OnSetCursor](#onsetcursor)|Called by the framework when the mouse pointer moves to a property item.| -|[CMFCPropertyGridProperty::OnSetSelection](#onsetselection)|| -|[CMFCPropertyGridProperty::OnUpdateValue](#onupdatevalue)|Called by the framework when the value of an editable property has changed.| -|[CMFCPropertyGridProperty::PushChar](#pushchar)|Called from the property list control when the property is selected and the user enters a new character.| -|[CMFCPropertyGridProperty::Redraw](#redraw)|Redraws the property.| -|[CMFCPropertyGridProperty::RemoveAllOptions](#removealloptions)|Removes all options (items) from a property.| -|[CMFCPropertyGridProperty::RemoveSubItem](#removesubitem)|Removes the specified sub-item.| -|[CMFCPropertyGridProperty::ResetOriginalValue](#resetoriginalvalue)|Restores the original value of an edited property.| -|[CMFCPropertyGridProperty::SetData](#setdata)|Associates a DWORD value with a property.| -|[CMFCPropertyGridProperty::SetDescription](#setdescription)|Specifies the text that describes the current property.| -|[CMFCPropertyGridProperty::SetName](#setname)|Sets the name of a property.| -|[CMFCPropertyGridProperty::SetOriginalValue](#setoriginalvalue)|Sets the original value of an editable property.| -|[CMFCPropertyGridProperty::SetValue](#setvalue)|Sets the value of a property grid property.| -|[CMFCPropertyGridProperty::Show](#show)|Shows or hides a property.| +|[`CMFCPropertyGridProperty::AddOption`](#addoption)|Adds a new list item to a property list control.| +|[`CMFCPropertyGridProperty::AddSubItem`](#addsubitem)|Adds a child item to a property.| +|[`CMFCPropertyGridProperty::AdjustButtonRect`](#adjustbuttonrect)|Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button.| +|[`CMFCPropertyGridProperty::AdjustInPlaceEditRect`](#adjustinplaceeditrect)|Retrieves the boundaries of the text box and optional spin button control that are used to set a property value.| +|[`CMFCPropertyGridProperty::AllowEdit`](#allowedit)|Makes a property either editable or read-only.| +|[`CMFCPropertyGridProperty::CreateInPlaceEdit`](#createinplaceedit)|Called by the framework to create an editable control for a property.| +|[`CMFCPropertyGridProperty::CreateSpinControl`](#createspincontrol)|Called by the framework to create an editable spin button control.| +|[`CMFCPropertyGridProperty::Enable`](#enable)|Enables or disables a property.| +|[`CMFCPropertyGridProperty::EnableSpinControl`](#enablespincontrol)|Enables or disables a spin button control that is used to modify a property value.| +|[`CMFCPropertyGridProperty::Expand`](#expand)|Expands or collapses a property that contains subproperties.| +|[`CMFCPropertyGridProperty::FormatProperty`](#formatproperty)|Formats the text representation of a property value.| +|[`CMFCPropertyGridProperty::GetData`](#getdata)|Retrieves a DWORD value that is associated with a property.| +|[`CMFCPropertyGridProperty::GetDescription`](#getdescription)|Retrieves a property description.| +|[`CMFCPropertyGridProperty::GetExpandedSubItems`](#getexpandedsubitems)|Retrieves the number of expanded subitems.| +|[`CMFCPropertyGridProperty::GetHierarchyLevel`](#gethierarchylevel)|Retrieves the zero-based index of the property's hierarchy level.| +|[`CMFCPropertyGridProperty::GetName`](#getname)|Retrieves the name of the property.| +|[`CMFCPropertyGridProperty::GetNameTooltip`](#getnametooltip)|Called by the framework to display the name of the property in a tooltip.| +|[`CMFCPropertyGridProperty::GetOption`](#getoption)|Retrieves the text of the option that is specified by an index.| +|[`CMFCPropertyGridProperty::GetOptionCount`](#getoptioncount)|Retrieves the number of options that belong to a property.| +|[`CMFCPropertyGridProperty::GetOriginalValue`](#getoriginalvalue)|Retrieves the initial value of the current property.| +|[`CMFCPropertyGridProperty::GetParent`](#getparent)|Retrieves a pointer to a parent property.| +|[`CMFCPropertyGridProperty::GetRect`](#getrect)|Retrieves the bounding rectangle of a property.| +|[`CMFCPropertyGridProperty::GetSubItem`](#getsubitem)|Retrieves a subproperty identified by a zero-based index.| +|[`CMFCPropertyGridProperty::GetSubItemsCount`](#getsubitemscount)|Retrieves the number of subitems.| +|`CMFCPropertyGridProperty::GetThisClass`|Used by the framework to obtain a pointer to the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| +|[`CMFCPropertyGridProperty::GetValue`](#getvalue)|Retrieves a property value.| +|[`CMFCPropertyGridProperty::GetValueTooltip`](#getvaluetooltip)|Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.| +|[`CMFCPropertyGridProperty::HitTest`](#hittest)|Points to the property object that corresponds to the property list item that corresponds to a point.| +|[`CMFCPropertyGridProperty::IsAllowEdit`](#isallowedit)|Indicates whether a property is editable.| +|[`CMFCPropertyGridProperty::IsEnabled`](#isenabled)|Indicates whether a property is enabled or disabled.| +|[`CMFCPropertyGridProperty::IsExpanded`](#isexpanded)|Indicates whether a property is expanded or collapsed.| +|[`CMFCPropertyGridProperty::IsGroup`](#isgroup)|Indicates whether the current property represents a group.| +|[`CMFCPropertyGridProperty::IsInPlaceEditing`](#isinplaceediting)|Indicates whether the current property is editable.| +|[`CMFCPropertyGridProperty::IsModified`](#ismodified)|Indicates whether the current property is modified.| +|[`CMFCPropertyGridProperty::IsParentExpanded`](#isparentexpanded)|Indicates whether the parents of the current property are expanded.| +|[`CMFCPropertyGridProperty::IsSelected`](#isselected)|Indicates whether the current property is selected.| +|[`CMFCPropertyGridProperty::IsVisible`](#isvisible)|Indicates whether the current property is visible.| +|[`CMFCPropertyGridProperty::OnClickButton`](#onclickbutton)|Called by the framework when the user selects a button that is contained in a property.| +|[`CMFCPropertyGridProperty::OnClickName`](#onclickname)|Called by a parent property list control when a user selects the name field of a property.| +|[`CMFCPropertyGridProperty::OnClickValue`](#onclickvalue)|Called by a parent property list control when a user selects the value field of a property.| +|[`CMFCPropertyGridProperty::OnCloseCombo`](#onclosecombo)|Called by the framework when a combo box that is contained in a property is closed.| +|[`CMFCPropertyGridProperty::OnDblClk`](#ondblclk)|Called by the framework when the user double clicks a property.| +|[`CMFCPropertyGridProperty::OnDrawButton`](#ondrawbutton)|Called by the framework to draw a button that is contained in a property.| +|[`CMFCPropertyGridProperty::OnDrawDescription`](#ondrawdescription)|Called by the framework to display the property description.| +|[`CMFCPropertyGridProperty::OnDrawExpandBox`](#ondrawexpandbox)|Called by the framework to draw an expand box control near a property that contains subproperties.| +|[`CMFCPropertyGridProperty::OnDrawName`](#ondrawname)|Called by the framework to display the property name.| +|[`CMFCPropertyGridProperty::OnDrawValue`](#ondrawvalue)|Called by the framework to display the property value.| +|[`CMFCPropertyGridProperty::OnEdit`](#onedit)|Called by the framework when the user is about to modify a property value.| +|[`CMFCPropertyGridProperty::OnEndEdit`](#onendedit)|Called by the framework when the user is finished modifying a property value.| +|[`CMFCPropertyGridProperty::OnKillSelection`](#onkillselection)|| +|[`CMFCPropertyGridProperty::OnPosSizeChanged`](#onpossizechanged)|| +|[`CMFCPropertyGridProperty::OnRClickName`](#onrclickname)|Called by the framework when the user selects the right mouse button in the property name area.| +|[`CMFCPropertyGridProperty::OnRClickValue`](#onrclickvalue)|Called by the framework when the user selects the right mouse button in the property value area.| +|[`CMFCPropertyGridProperty::OnSelectCombo`](#onselectcombo)|Called by the framework when the user selects an item from the editable combo box.| +|[`CMFCPropertyGridProperty::OnSetCursor`](#onsetcursor)|Called by the framework when the mouse pointer moves to a property item.| +|[`CMFCPropertyGridProperty::OnSetSelection`](#onsetselection)|| +|[`CMFCPropertyGridProperty::OnUpdateValue`](#onupdatevalue)|Called by the framework when the value of an editable property has changed.| +|[`CMFCPropertyGridProperty::PushChar`](#pushchar)|Called from the property list control when the property is selected and the user enters a new character.| +|[`CMFCPropertyGridProperty::Redraw`](#redraw)|Redraws the property.| +|[`CMFCPropertyGridProperty::RemoveAllOptions`](#removealloptions)|Removes all options (items) from a property.| +|[`CMFCPropertyGridProperty::RemoveSubItem`](#removesubitem)|Removes the specified subitem.| +|[`CMFCPropertyGridProperty::ResetOriginalValue`](#resetoriginalvalue)|Restores the original value of an edited property.| +|[`CMFCPropertyGridProperty::SetData`](#setdata)|Associates a DWORD value with a property.| +|[`CMFCPropertyGridProperty::SetDescription`](#setdescription)|Specifies the text that describes the current property.| +|[`CMFCPropertyGridProperty::SetName`](#setname)|Sets the name of a property.| +|[`CMFCPropertyGridProperty::SetOriginalValue`](#setoriginalvalue)|Sets the original value of an editable property.| +|[`CMFCPropertyGridProperty::SetValue`](#setvalue)|Sets the value of a property grid property.| +|[`CMFCPropertyGridProperty::Show`](#show)|Shows or hides a property.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CMFCPropertyGridProperty::CreateCombo](#createcombo)|Called by the framework to add a combo box to a property.| -|[CMFCPropertyGridProperty::HasButton](#hasbutton)|Indicates whether a property contains a button.| -|[CMFCPropertyGridProperty::Init](#init)|Called by the framework to initialize a property object.| -|[CMFCPropertyGridProperty::IsSubItem](#issubitem)|Indicates whether the specified property is a sub-item of the current property.| -|[CMFCPropertyGridProperty::IsValueChanged](#isvaluechanged)|Indicates whether the value of the current property has changed.| -|[CMFCPropertyGridProperty::OnCtlColor](#onctlcolor)|Called by the framework when it must retrieve a brush to fill the background color of a property.| -|[CMFCPropertyGridProperty::OnDestroyWindow](#ondestroywindow)|Called by the framework when a property is destroyed or when editing is finished.| -|[CMFCPropertyGridProperty::OnKillFocus](#onkillfocus)|Called by the framework when the property loses the input focus.| +|[`CMFCPropertyGridProperty::CreateCombo`](#createcombo)|Called by the framework to add a combo box to a property.| +|[`CMFCPropertyGridProperty::HasButton`](#hasbutton)|Indicates whether a property contains a button.| +|[`CMFCPropertyGridProperty::Init`](#init)|Called by the framework to initialize a property object.| +|[`CMFCPropertyGridProperty::IsSubItem`](#issubitem)|Indicates whether the specified property is a subitem of the current property.| +|[`CMFCPropertyGridProperty::IsValueChanged`](#isvaluechanged)|Indicates whether the value of the current property has changed.| +|[`CMFCPropertyGridProperty::OnCtlColor`](#onctlcolor)|Called by the framework when it must retrieve a brush to fill the background color of a property.| +|[`CMFCPropertyGridProperty::OnDestroyWindow`](#ondestroywindow)|Called by the framework when a property is destroyed or when editing is finished.| +|[`CMFCPropertyGridProperty::OnKillFocus`](#onkillfocus)|Called by the framework when the property loses the input focus.| ### Data Members |Name|Description| |----------|-----------------| -|[CMFCPropertyGridProperty::m_strFormatDouble](#m_strformatdouble)|Format string for a value of type double.| -|[CMFCPropertyGridProperty::m_strFormatFloat](#m_strformatfloat)|Format string for a value of type float.| -|[CMFCPropertyGridProperty::m_strFormatLong](#m_strformatlong)|Format string for a value of type long.| -|[CMFCPropertyGridProperty::m_strFormatShort](#m_strformatshort)|Format string for a value of type short.| +|[`CMFCPropertyGridProperty::m_strFormatDouble`](#m_strformatdouble)|Format string for a value of type double.| +|[`CMFCPropertyGridProperty::m_strFormatFloat`](#m_strformatfloat)|Format string for a value of type float.| +|[`CMFCPropertyGridProperty::m_strFormatLong`](#m_strformatlong)|Format string for a value of type long.| +|[`CMFCPropertyGridProperty::m_strFormatShort`](#m_strformatshort)|Format string for a value of type short.| ## Remarks -Use a `CMFCPropertyGridProperty` object to represent a property, which you then add to a property list control. For more information, see [CMFCPropertyGridCtrl Class](../../mfc/reference/cmfcpropertygridctrl-class.md). +Use a `CMFCPropertyGridProperty` object to represent a property, which you then add to a property list control. For more information, see [`CMFCPropertyGridCtrl` Class](../../mfc/reference/cmfcpropertygridctrl-class.md). A property object can represent data types such as strings, dates, and Boolean or integer values. It can contain child properties, or it can contain a control such as a combo box or a button control. ## Example -The following example demonstrates how to construct a `CMFCPropertyGridProperty` object. The example also demonstrates how to use various methods in the `CMFCPropertyGridProperty` class to add an option, add a sub-item, enable a property, and show a property. This example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). +The following example demonstrates how to construct a `CMFCPropertyGridProperty` object. The example also demonstrates how to use various methods in the `CMFCPropertyGridProperty` class to add an option, add a subitem, enable a property, and show a property. This example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). [!code-cpp[NVC_MFC_NewControls#27](../../mfc/reference/codesnippet/cpp/cmfcpropertygridproperty-class_1.cpp)] ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CMFCPropertyGridProperty](../../mfc/reference/cmfcpropertygridproperty-class.md) +[`CMFCPropertyGridProperty`](../../mfc/reference/cmfcpropertygridproperty-class.md) ## Requirements -**Header:** afxpropertygridctrl.h +**Header:** `afxpropertygridctrl.h` -## CMFCPropertyGridProperty::AddOption +## `CMFCPropertyGridProperty::AddOption` Adds a new list item to a property list control. -``` +```cpp BOOL AddOption( LPCTSTR lpszOption, BOOL bInsertUnique=TRUE); @@ -156,44 +155,42 @@ BOOL AddOption( ### Parameters -*lpszOption*
+*`lpszOption`*\ [in] The list item (option) to add. -*bInsertUnique*
-[in] TRUE to add the list item only if it does not already exist; otherwise, FALSE. The default value is TRUE. +*`bInsertUnique`*\ +[in] `TRUE` to add the list item only if it doesn't already exist; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -TRUE, which means that the list item is added. Otherwise, FALSE, which means that the list item is not added because the *bInsertUnique* parameter is TRUE and the list item specified by the *lpszOption* parameter already exists. +`TRUE`, which means that the list item is added. Otherwise, `FALSE`, which means that the list item isn't added because the *`bInsertUnique`* parameter is `TRUE` and the list item specified by the *`lpszOption`* parameter already exists. -### Remarks - -## CMFCPropertyGridProperty::AddSubItem +## `CMFCPropertyGridProperty::AddSubItem` Adds a child item to a property. -``` +```cpp BOOL AddSubItem(CMFCPropertyGridProperty* pProp); ``` ### Parameters -*pProp*
+*`pProp`*\ [in] Pointer to a property to add. ### Return Value -TRUE if the specified property is successfully added as a child property. FALSE if the property is not added because it already occurs in the parent property. +`TRUE` if the specified property is successfully added as a child property. `FALSE` if the property isn't added because it already occurs in the parent property. ### Remarks -Use this method to create a hierarchical list of parent and child properties. After a child property is added, the parent property automatically displays an expand box control that is designated by a plus sign (+). When the user clicks the plus sign, the parent property expands and displays any child property items. +Use this method to create a hierarchical list of parent and child properties. After a child property is added, the parent property automatically displays an expand box control that is designated by a plus sign (**+**). When the user selects the plus sign, the parent property expands and displays any child property items. -## CMFCPropertyGridProperty::AdjustButtonRect +## `CMFCPropertyGridProperty::AdjustButtonRect` Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button. -``` +```cpp virtual void AdjustButtonRect(); ``` @@ -201,17 +198,15 @@ virtual void AdjustButtonRect(); By default, this method: -- Adjusts the width of the button equal to the height of the button plus 3 pixels. - -- Moves the bounding rectangle of the button to the right edge of the property - +- Adjusts the width of the button equal to the height of the button plus three pixels. +- Moves the bounding rectangle of the button to the right edge of the property. - Shifts the button 1 pixel below the top edge of the property. -## CMFCPropertyGridProperty::AdjustInPlaceEditRect +## `CMFCPropertyGridProperty::AdjustInPlaceEditRect` Retrieves the boundaries of the text box and optional spin button control that are used to set a property value. -``` +```cpp virtual void AdjustInPlaceEditRect( CRect& rectEdit, CRect& rectSpin); @@ -219,17 +214,17 @@ virtual void AdjustInPlaceEditRect( ### Parameters -*rectEdit*
+*`rectEdit`*\ [out] When this method returns, a rectangle that specifies the boundaries of the text box for the property value. -*rectSpin*
-[out] When this method returns, a rectangle that specifies the boundaries of the spin button control for the property value. Or, if the property does not support a spin button, an empty rectangle. +*`rectSpin`*\ +[out] When this method returns, a rectangle that specifies the boundaries of the spin button control for the property value. Or, if the property doesn't support a spin button, an empty rectangle. ### Remarks The value area of a property consists of a text box and possibly an *option button*, such as a spin button control. This method calculates the dimensions of the text box and option button and then returns those values in the specified parameters. -## CMFCPropertyGridProperty::AllowEdit +## `CMFCPropertyGridProperty::AllowEdit` Makes a property either editable or read-only. @@ -239,16 +234,14 @@ void AllowEdit(BOOL bAllow=TRUE); ### Parameters -*bAllow*
-[in] TRUE to make the property editable; FALSE to make the property read-only. The default value is TRUE. +*`bAllow`*\ +[in] `TRUE` to make the property editable; `FALSE` to make the property read-only. The default value is `TRUE`. -### Remarks - -## CMFCPropertyGridProperty::CMFCPropertyGridProperty +## `CMFCPropertyGridProperty::CMFCPropertyGridProperty` Constructs a `CMFCPropertyGridProperty` object. -``` +```cpp CMFCPropertyGridProperty( const CString& strGroupName, DWORD_PTR dwData=0, @@ -266,40 +259,38 @@ CMFCPropertyGridProperty( ### Parameters -*strGroupName*
+*`strGroupName`*\ [in] The group name. A *group* is a collection of related properties in a property grid control. If the control is displayed hierarchically, the *group name* is displayed as a category title in the row above the group. -*dwData*
+*`dwData`*\ [in] Application-specific data, such as an integer or a pointer to other data that is associated with the property. The default value is 0. -*strName*
+*`strName`*\ [in] The name of the property. -*varValue*
+*`varValue`*\ [in] The property value. -*lpszDescr*
-[in] The property description. The default value is NULL. +*`lpszDescr`*\ +[in] The property description. The default value is `NULL`. -*lpszEditMask*
-[in] The edit mask, if the property is a masked edit control. The default value is NULL. +*`lpszEditMask`*\ +[in] The edit mask, if the property is a masked edit control. The default value is `NULL`. -*lpszEditTemplate*
-[in] The edit template, if the property is a masked edit control. The default value is NULL. +*`lpszEditTemplate`*\ +[in] The edit template, if the property is a masked edit control. The default value is `NULL`. -*lpszValidChars*
-[in] A list of valid characters, if the property is a masked edit control. The default value is NULL. +*`lpszValidChars`*\ +[in] A list of valid characters, if the property is a masked edit control. The default value is `NULL`. -*bIsValueList*
-[in] TRUE if the property represents a list of values; FALSE if the property represents a single value. The default value is FALSE. +*`bIsValueList`*\ +[in] `TRUE` if the property represents a list of values; `FALSE` if the property represents a single value. The default value is `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::CreateCombo +## `CMFCPropertyGridProperty::CreateCombo` Called by the framework to add a combo box to a property. -``` +```cpp virtual CComboBox* CreateCombo( CWnd* pWndParent, CRect rect); @@ -307,23 +298,21 @@ virtual CComboBox* CreateCombo( ### Parameters -*pWndParent*
+*`pWndParent`*\ [in] Pointer to the parent window of the combo box. -*rect*
+*`rect`*\ [in] The bounding rectangle of the combo box. ### Return Value -Pointer to a new [CComboBox](../../mfc/reference/ccombobox-class.md) object. +Pointer to a new [`CComboBox`](../../mfc/reference/ccombobox-class.md) object. -### Remarks - -## CMFCPropertyGridProperty::CreateInPlaceEdit +## `CMFCPropertyGridProperty::CreateInPlaceEdit` Called by the framework to create an editable control for a property. -``` +```cpp virtual CWnd* CreateInPlaceEdit( CRect rectEdit, BOOL& bDefaultFormat); @@ -331,44 +320,44 @@ virtual CWnd* CreateInPlaceEdit( ### Parameters -*rectEdit*
+*`rectEdit`*\ [in] The bounding rectangle of the editable control. -*bDefaultFormat*
-[in] TRUE to use the default property format to set the text of the editable control; otherwise, FALSE. +*`bDefaultFormat`*\ +[in] `TRUE` to use the default property format to set the text of the editable control; otherwise, `FALSE`. ### Return Value -A pointer to the editable control if this method succeeds; otherwise, NULL. +A pointer to the editable control if this method succeeds; otherwise, `NULL`. ### Remarks -This method uses the values of the *varValue*, *lpszEditMask*, *lpszEditTemplate*, and *lpszValidChars* parameters that are specified in the [CMFCPropertyGridProperty](../../mfc/reference/cmfcpropertygridproperty-class.md) class constructor. By default, this method supports the *varValue* variant types. This includes VT_BSTR, VT_R4, VT_R8, VT_UI1, VT_I2, VT_INT, VT_UINT, VT_I4, VT_UI2, VT_UI4, and VT_BOOL. +This method uses the values of the *`varValue`*, *`lpszEditMask`*, *`lpszEditTemplate`*, and *`lpszValidChars`* parameters that are specified in the [`CMFCPropertyGridProperty`](../../mfc/reference/cmfcpropertygridproperty-class.md) class constructor. By default, this method supports the *`varValue`* variant types. This includes `VT_BSTR`, `VT_R4`, `VT_R8`, `VT_UI1`, `VT_I2`, `VT_INT`, `VT_UINT`, `VT_I4`, `VT_UI2`, `VT_UI4`, and `VT_BOOL`. -This method creates a [CMFCMaskedEdit](../../mfc/reference/cmfcmaskededit-class.md) control if one or more of the *lpszEditMask*, *lpszEditTemplate*, or *lpszValidChars* parameters are specified; otherwise, it creates a [CEdit](../../mfc/reference/cedit-class.md) control. +This method creates a [`CMFCMaskedEdit`](../../mfc/reference/cmfcmaskededit-class.md) control if one or more of the *`lpszEditMask`*, *`lpszEditTemplate`*, or *`lpszValidChars`* parameters are specified; otherwise, it creates a [`CEdit`](../../mfc/reference/cedit-class.md) control. -## CMFCPropertyGridProperty::CreateSpinControl +## `CMFCPropertyGridProperty::CreateSpinControl` Called by the framework to create an editable spin button control. -``` +```cpp virtual CSpinButtonCtrl* CreateSpinControl(CRect rectSpin); ``` ### Parameters -*rectSpin*
+*`rectSpin`*\ [in] A rectangle that defines where the editable spin button control is created. ### Return Value -A pointer to a new [CMFCSpinButtonCtrl](../../mfc/reference/cmfcspinbuttonctrl-class.md) object that is cast as a pointer to a [CSpinButtonCtrl](../../mfc/reference/cspinbuttonctrl-class.md) object. +A pointer to a new [`CMFCSpinButtonCtrl`](../../mfc/reference/cmfcspinbuttonctrl-class.md) object that is cast as a pointer to a [`CSpinButtonCtrl`](../../mfc/reference/cspinbuttonctrl-class.md) object. ### Remarks -Call the [CMFCPropertyGridProperty::EnableSpinControl](#enablespincontrol) method to display an editable spin button control at the right edge of the property. +Call the [`CMFCPropertyGridProperty::EnableSpinControl`](#enablespincontrol) method to display an editable spin button control at the right edge of the property. -## CMFCPropertyGridProperty::Enable +## `CMFCPropertyGridProperty::Enable` Enables or disables a property. @@ -378,12 +367,10 @@ void Enable(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the property; FALSE to disable the property. Disabled properties do not respond to mouse or keyboard input. The default value is TRUE. - -### Remarks +*`bEnable`*\ +[in] `TRUE` to enable the property; `FALSE` to disable the property. Disabled properties don't respond to mouse or keyboard input. The default value is `TRUE`. -## CMFCPropertyGridProperty::EnableSpinControl +## `CMFCPropertyGridProperty::EnableSpinControl` Enables or disables a spin button control that is used to modify a property value. @@ -396,24 +383,24 @@ void EnableSpinControl( ### Parameters -*bEnable*
-[in] TRUE to enable the spin button control; FALSE to disable the spin button control. The default value is TRUE. +*`bEnable`*\ +[in] `TRUE` to enable the spin button control; `FALSE` to disable the spin button control. The default value is `TRUE`. -*nMin*
+*`nMin`*\ [in] The minimum value of the spin button control. The default value is 0. -*nMax*
+*`nMax`*\ [in] The maximum value of the spin button control. The default value is 0. ### Remarks The framework automatically creates a spin button control when a property is about to be edited. -The property type, which is specified by the *varValue* parameter of the [CMFCPropertyGridProperty::CMFCPropertyGridProperty](#cmfcpropertygridproperty) constructor, must be a supported variant type. Otherwise, this method asserts in debug mode. The supported types include VT_INT, VT_UINT, VT_I2, VT_I4, VT_UI2, and VT_UI4. +The property type, which is specified by the *`varValue`* parameter of the [`CMFCPropertyGridProperty::CMFCPropertyGridProperty`](#cmfcpropertygridproperty) constructor, must be a supported variant type. Otherwise, this method asserts in debug mode. The supported types include `VT_INT`, `VT_UINT`, `VT_I2`, `VT_I4`, `VT_UI2`, and `VT_UI4`. -## CMFCPropertyGridProperty::Expand +## `CMFCPropertyGridProperty::Expand` -Expands or collapses a property that contains sub-properties. +Expands or collapses a property that contains subproperties. ```cpp void Expand(BOOL bExpand=TRUE); @@ -421,16 +408,14 @@ void Expand(BOOL bExpand=TRUE); ### Parameters -*bExpand*
-[in] TRUE to expand the property; FALSE to collapse the property. The default value is TRUE. - -### Remarks +*`bExpand`*\ +[in] `TRUE` to expand the property; `FALSE` to collapse the property. The default value is `TRUE`. -## CMFCPropertyGridProperty::FormatProperty +## `CMFCPropertyGridProperty::FormatProperty` Formats the text representation of a property value. -``` +```cpp virtual CString FormatProperty(); ``` @@ -442,27 +427,27 @@ The text representation of the property value. This method is called by the framework before the property value is displayed. -## CMFCPropertyGridProperty::GetData +## `CMFCPropertyGridProperty::GetData` -Retrieves a DWORD value that is associated with a property. +Retrieves a `DWORD` value that is associated with a property. -``` +```cpp DWORD_PTR GetData() const; ``` ### Return Value -A DWORD value. +A `DWORD` value. ### Remarks -The data that is returned is an application-specific value, such as a number or a pointer to other data. Specify the data value when you construct the property or when you call the [CMFCPropertyGridProperty::SetData](#setdata) method. +The data that is returned is an application-specific value, such as a number or a pointer to other data. Specify the data value when you construct the property or when you call the [`CMFCPropertyGridProperty::SetData`](#setdata) method. -## CMFCPropertyGridProperty::GetDescription +## `CMFCPropertyGridProperty::GetDescription` Retrieves a property description. -``` +```cpp const CString& GetDescription() const; ``` @@ -474,30 +459,28 @@ A text string that contains the property description. Property list control also uses this method to display the description of the property. -## CMFCPropertyGridProperty::GetExpandedSubItems +## `CMFCPropertyGridProperty::GetExpandedSubItems` -Retrieves the number of expanded sub-items. +Retrieves the number of expanded subitems. -``` +```cpp int GetExpandedSubItems(BOOL bIncludeHidden=TRUE) const; ``` ### Parameters -*bIncludeHidden*\ -[in] TRUE to include the hidden sub-items in the count; otherwise, FALSE. The default value is TRUE. +*`bIncludeHidden`*\ +[in] `TRUE` to include the hidden subitems in the count; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -The number of expanded sub-items. +The number of expanded subitems. -### Remarks - -## CMFCPropertyGridProperty::GetHierarchyLevel +## `CMFCPropertyGridProperty::GetHierarchyLevel` Retrieves the zero-based index of the property's hierarchy level. -``` +```cpp int GetHierarchyLevel() const; ``` @@ -505,13 +488,11 @@ int GetHierarchyLevel() const; The property's hierarchical level. -### Remarks - -## CMFCPropertyGridProperty::GetName +## `CMFCPropertyGridProperty::GetName` Retrieves the name of the property. -``` +```cpp LPCTSTR GetName() const; ``` @@ -519,13 +500,11 @@ LPCTSTR GetName() const; Pointer to a string that contains the name of the property. -### Remarks - -## CMFCPropertyGridProperty::GetNameTooltip +## `CMFCPropertyGridProperty::GetNameTooltip` Called by the framework to display the name of the property in a tooltip. -``` +```cpp virtual CString GetNameTooltip(); ``` @@ -533,32 +512,28 @@ virtual CString GetNameTooltip(); A string that contains the property name. By default, the return value is the empty string. -### Remarks - -## CMFCPropertyGridProperty::GetOption +## `CMFCPropertyGridProperty::GetOption` Retrieves the text of the option that is specified by an index. -``` +```cpp LPCTSTR GetOption(int nIndex) const; ``` ### Parameters -*nIndex*
+*`nIndex`*\ The zero-based index of the property list item (option) to retrieve. ### Return Value Pointer to a string that contains the option text. -### Remarks - -## CMFCPropertyGridProperty::GetOptionCount +## `CMFCPropertyGridProperty::GetOptionCount` Retrieves the number of options that belong to a property. -``` +```cpp int GetOptionCount() const; ``` @@ -568,13 +543,13 @@ The number of property list items (options) that are contained in the property c ### Remarks -Call the [CMFCPropertyGridProperty::AddOption](#addoption) method to add items to the property list. Call the [CMFCPropertyGridProperty::RemoveAllOptions](#removealloptions) method to remove all items. +Call the [`CMFCPropertyGridProperty::AddOption`](#addoption) method to add items to the property list. Call the [`CMFCPropertyGridProperty::RemoveAllOptions`](#removealloptions) method to remove all items. -## CMFCPropertyGridProperty::GetOriginalValue +## `CMFCPropertyGridProperty::GetOriginalValue` Retrieves the initial value of the current property. -``` +```cpp const COleVariant& GetOriginalValue() const; ``` @@ -586,48 +561,44 @@ The original value of the current property. Use this method to undo the effect of an edit operation that changes the value of the current property. -The original value of the current property is set by the [CMFCPropertyGridProperty::CMFCPropertyGridProperty](#cmfcpropertygridproperty) constructor, modified by the [CMFCPropertyGridProperty::SetOriginalValue](#setoriginalvalue) method, and reset by the [CMFCPropertyGridProperty::ResetOriginalValue](#resetoriginalvalue) method. +The original value of the current property is set by the [`CMFCPropertyGridProperty::CMFCPropertyGridProperty`](#cmfcpropertygridproperty) constructor, modified by the [`CMFCPropertyGridProperty::SetOriginalValue`](#setoriginalvalue) method, and reset by the [`CMFCPropertyGridProperty::ResetOriginalValue`](#resetoriginalvalue) method. -## CMFCPropertyGridProperty::GetParent +## `CMFCPropertyGridProperty::GetParent` Retrieves a pointer to a parent property. -``` +```cpp CMFCPropertyGridProperty* GetParent() const; ``` ### Return Value -A pointer to a parent property object, or NULL for the top-level property. - -### Remarks +A pointer to a parent property object, or `NULL` for the top-level property. -## CMFCPropertyGridProperty::GetRect +## `CMFCPropertyGridProperty::GetRect` Retrieves the bounding rectangle of a property. -``` +```cpp CRect GetRect() const; ``` ### Return Value -A [CRect](../../atl-mfc-shared/reference/crect-class.md) object that describes the bounding rectangle. - -### Remarks +A [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that describes the bounding rectangle. -## CMFCPropertyGridProperty::GetSubItem +## `CMFCPropertyGridProperty::GetSubItem` -Retrieves a sub-property identified by a zero-based index. +Retrieves a subproperty identified by a zero-based index. -``` +```cpp CMFCPropertyGridProperty* GetSubItem(int nIndex) const; ``` ### Parameters -*nIndex*
-[in] The zero-based index of the property to retrieve. This parameter is invalid if it is less than zero or greater than or equal to the number of sub-properties. +*`nIndex`*\ +[in] The zero-based index of the property to retrieve. This parameter is invalid if it's less than zero or greater than or equal to the number of subproperties. ### Return Value @@ -635,15 +606,13 @@ A pointer to a property object that is a child item of this property. -or- -In retail mode, NULL if the *nIndex* parameter is invalid. In debug mode, this method asserts. +In retail mode, `NULL` if the *`nIndex`* parameter is invalid. In debug mode, this method asserts. -### Remarks +## `CMFCPropertyGridProperty::GetSubItemsCount` -## CMFCPropertyGridProperty::GetSubItemsCount +Retrieves the number of subitems. -Retrieves the number of sub-items. - -``` +```cpp int GetSubItemsCount() const; ``` @@ -651,13 +620,11 @@ int GetSubItemsCount() const; The number of child items. -### Remarks - -## CMFCPropertyGridProperty::GetValue +## `CMFCPropertyGridProperty::GetValue` Retrieves a property value. -``` +```cpp virtual const _variant_t& GetValue() const; ``` @@ -665,13 +632,11 @@ virtual const _variant_t& GetValue() const; A variant that contains the property value. -### Remarks - -## CMFCPropertyGridProperty::GetValueTooltip +## `CMFCPropertyGridProperty::GetValueTooltip` Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip. -``` +```cpp virtual CString GetValueTooltip(); ``` @@ -679,27 +644,23 @@ virtual CString GetValueTooltip(); A `CString` object containing the textual representation of the property value. By default, this value is the empty string. -### Remarks - -## CMFCPropertyGridProperty::HasButton +## `CMFCPropertyGridProperty::HasButton` Indicates whether a property contains a button. -``` +```cpp virtual BOOL HasButton() const; ``` ### Return Value -TRUE if a property contains a button (or property list); otherwise, FALSE. - -### Remarks +`TRUE` if a property contains a button (or property list); otherwise, `FALSE`. -## CMFCPropertyGridProperty::HitTest +## `CMFCPropertyGridProperty::HitTest` Points to the property object that corresponds to the property list item that corresponds to a point. -``` +```cpp CMFCPropertyGridProperty* HitTest( CPoint point, CMFCPropertyGridProperty::ClickArea* pnArea=NULL); @@ -712,35 +673,35 @@ CMFCPropertyGridProperty* HitTest( ### Parameters -*point*
+*`point`*\ [in] The point to test, in client coordinates. This parameter is typically the current mouse pointer location. -*pt*
+*`pt`*\ [in] The point to test, in client coordinates. -*pnArea*
-[out] When this method returns, indicates the area that contains the specified point. For more information, see Remarks. The default value is NULL. +*`pnArea`*\ +[out] When this method returns, indicates the area that contains the specified point. For more information, see Remarks. The default value is `NULL`. -*bPropsOnly*
-[in] TRUE to test any area in the property control; FALSE to test only the description area. The default value is FALSE. +*`bPropsOnly`*\ +[in] `TRUE` to test any area in the property control; `FALSE` to test only the description area. The default value is `FALSE`. ### Return Value -A pointer to a property object or NULL. +A pointer to a property object or `NULL`. ### Remarks -By default, this method tests property sub-items if the specified point is not found within any of the property items. +By default, this method tests property subitems if the specified point isn't found within any of the property items. -The following table lists the values that can be returned to the *pnArea* parameter. +The following table lists the values that can be returned to the *`pnArea`* parameter. |Area|Description| |----------|-----------------| -|`ClickArea::ClickExpandBox`|The expand box control, which is designated by a plus sign (+).| +|`ClickArea::ClickExpandBox`|The expand box control, which is designated by a plus sign (**+**).| |`ClickArea::ClickName`|The property name.| |`ClickArea::ClickValue`|The property value.| -## CMFCPropertyGridProperty::Init +## `CMFCPropertyGridProperty::Init` Called by the framework to initialize a property object. @@ -748,248 +709,222 @@ Called by the framework to initialize a property object. void Init(); ``` -### Remarks - -## CMFCPropertyGridProperty::IsAllowEdit +## `CMFCPropertyGridProperty::IsAllowEdit` Indicates whether a property is editable. -``` +```cpp BOOL IsAllowEdit() const; ``` ### Return Value -TRUE if the property is editable; otherwise FALSE. - -### Remarks +`TRUE` if the property is editable; otherwise `FALSE`. -## CMFCPropertyGridProperty::IsEnabled +## `CMFCPropertyGridProperty::IsEnabled` Indicates whether a property is enabled or disabled. -``` +```cpp BOOL IsEnabled() const; ``` ### Return Value -TRUE if the property is enabled; FALSE if the property is disabled. +`TRUE` if the property is enabled; `FALSE` if the property is disabled. ### Remarks Tells whether a property is enabled or disabled. -## CMFCPropertyGridProperty::IsExpanded +## `CMFCPropertyGridProperty::IsExpanded` Indicates whether a property is expanded or collapsed. -``` +```cpp BOOL IsExpanded() const; ``` ### Return Value -TRUE if the property is expanded; FALSE if the property is collapsed. - -### Remarks +`TRUE` if the property is expanded; `FALSE` if the property is collapsed. -## CMFCPropertyGridProperty::IsGroup +## `CMFCPropertyGridProperty::IsGroup` Indicates whether the current property represents a group. -``` +```cpp BOOL IsGroup() const; ``` ### Return Value -TRUE if the current property object represents a group; FALSE if the property represents a value. +`TRUE` if the current property object represents a group; `FALSE` if the property represents a value. ### Remarks A *group* is a collection of related properties in a property grid control. If the control is displayed hierarchically, the *group name* is displayed as a category title in the row above the group. -## CMFCPropertyGridProperty::IsInPlaceEditing +## `CMFCPropertyGridProperty::IsInPlaceEditing` Indicates whether the current property is editable. -``` +```cpp BOOL IsInPlaceEditing() const; ``` ### Return Value -TRUE if the current property is editable; otherwise, FALSE. +`TRUE` if the current property is editable; otherwise, `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::IsModified +## `CMFCPropertyGridProperty::IsModified` Indicates whether the current property is modified. -``` +```cpp BOOL IsModified() const; ``` ### Return Value -TRUE if the property is modified; otherwise, FALSE. +`TRUE` if the property is modified; otherwise, `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::IsParentExpanded +## `CMFCPropertyGridProperty::IsParentExpanded` Indicates whether the parents of the current property are expanded. -``` +```cpp BOOL IsParentExpanded() const; ``` ### Return Value -TRUE if all parents of the current property are expanded; FALSE if the parent properties are collapsed. - -### Remarks +`TRUE` if all parents of the current property are expanded; `FALSE` if the parent properties are collapsed. -## CMFCPropertyGridProperty::IsSelected +## `CMFCPropertyGridProperty::IsSelected` Indicates whether the current property is selected. -``` +```cpp virtual BOOL IsSelected() const; ``` ### Return Value -TRUE if the current property is selected; otherwise, FALSE. - -### Remarks +`TRUE` if the current property is selected; otherwise, `FALSE`. -## CMFCPropertyGridProperty::IsSubItem +## `CMFCPropertyGridProperty::IsSubItem` -Indicates whether the specified property is a sub-item of the current property. +Indicates whether the specified property is a subitem of the current property. -``` +```cpp BOOL IsSubItem(CMFCPropertyGridProperty* pProp) const; ``` ### Parameters -*pProp*
+*`pProp`*\ [in] A pointer to a property. ### Return Value -TRUE if the specified property is a sub-item of the current property; otherwise, FALSE. +`TRUE` if the specified property is a subitem of the current property; otherwise, `FALSE`. -## CMFCPropertyGridProperty::IsValueChanged +## `CMFCPropertyGridProperty::IsValueChanged` Indicates whether the value of the current property has changed. -``` +```cpp virtual BOOL IsValueChanged() const; ``` ### Return Value -TRUE if the value of the current property has changed; otherwise, FALSE. +`TRUE` if the value of the current property has changed; otherwise, `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::IsVisible +## `CMFCPropertyGridProperty::IsVisible` Indicates whether the current property is visible. -``` +```cpp BOOL IsVisible() const; ``` ### Return Value -TRUE if the current property is visible; otherwise; FALSE. +`TRUE` if the current property is visible; otherwise; `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::m_strFormatDouble +## `CMFCPropertyGridProperty::m_strFormatDouble` Holds a format string for a value of type double. -``` +```cpp static CString m_strFormatDouble; ``` -### Remarks - -## CMFCPropertyGridProperty::m_strFormatFloat +## `CMFCPropertyGridProperty::m_strFormatFloat` Holds a format string for a value of type float. -``` +```cpp static CString m_strFormatFloat; ``` -### Remarks - -## CMFCPropertyGridProperty::m_strFormatLong +## `CMFCPropertyGridProperty::m_strFormatLong` Holds a format string for a value of type long. -``` +```cpp static CString m_strFormatLong; ``` -### Remarks - -## CMFCPropertyGridProperty::m_strFormatShort +## `CMFCPropertyGridProperty::m_strFormatShort` Holds a format string for a value of type short. -``` +```cpp static CString m_strFormatShort; ``` -### Remarks - -## CMFCPropertyGridProperty::OnClickButton +## `CMFCPropertyGridProperty::OnClickButton` -Called by the framework when the user clicks a button that is contained in a property. +Called by the framework when the user selects a button that is contained in a property. -``` +```cpp virtual void OnClickButton(CPoint point); ``` ### Parameters -*point*
+*`point`*\ [in] A point, in client coordinates. ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnClickName +## `CMFCPropertyGridProperty::OnClickName` -Called by a parent property list control when a user clicks the name field of a property. +Called by a parent property list control when a user selects the name field of a property. -``` +```cpp virtual void OnClickName(CPoint C); ``` ### Parameters -*C*\ +*`C`*\ [in] A point, in client coordinates. ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnClickValue +## `CMFCPropertyGridProperty::OnClickValue` -Called by a parent property list control when a user clicks the value field of a property. +Called by a parent property list control when a user selects the value field of a property. -``` +```cpp virtual BOOL OnClickValue( UINT uiMsg, CPoint point); @@ -997,35 +932,33 @@ virtual BOOL OnClickValue( ### Parameters -*uiMsg*
+*`uiMsg`*\ [in] A mouse message. -*point*
+*`point`*\ [in] A point, in client coordinates. ### Return Value -TRUE if the specified mouse message is processed by this method; otherwise, FALSE. +`TRUE` if the specified mouse message is processed by this method; otherwise, `FALSE`. ### Remarks -By default, this method returns FALSE if the current property is not editable. Otherwise, the edit or spin control that is associated with this property processes the specified mouse message, and then this method returns TRUE. +By default, this method returns `FALSE` if the current property isn't editable. Otherwise, the edit or spin control that is associated with this property processes the specified mouse message, and then this method returns `TRUE`. -## CMFCPropertyGridProperty::OnCloseCombo +## `CMFCPropertyGridProperty::OnCloseCombo` Called by the framework when a combo box that is contained in a property is closed. -``` +```cpp virtual void OnCloseCombo(); ``` -### Remarks - -## CMFCPropertyGridProperty::OnCtlColor +## `CMFCPropertyGridProperty::OnCtlColor` Called by the framework when it must retrieve a brush to fill the background color of a property. -``` +```cpp virtual HBRUSH OnCtlColor( CDC* pDC, UINT nCtlColor); @@ -1033,54 +966,50 @@ virtual HBRUSH OnCtlColor( ### Parameters -*pDC*
+*`pDC`*\ [in] Pointer to a device context. -*nCtlColor*
-[in] (This parameter is not used.) +*`nCtlColor`*\ +[in] (This parameter isn't used.) ### Return Value -The handle to a brush if this method is successful; otherwise, NULL. - -### Remarks +The handle to a brush if this method is successful; otherwise, `NULL`. -## CMFCPropertyGridProperty::OnDblClk +## `CMFCPropertyGridProperty::OnDblClk` Called by the framework when the user double clicks a property. -``` +```cpp virtual BOOL OnDblClk(CPoint point); ``` ### Parameters -*point*
+*`point`*\ [in] A point, in client coordinates. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks By default, this method selects the next property item in the property list control. -## CMFCPropertyGridProperty::OnDestroyWindow +## `CMFCPropertyGridProperty::OnDestroyWindow` Called by the framework when a property is destroyed or when editing is finished. -``` +```cpp virtual void OnDestroyWindow(); ``` -### Remarks - -## CMFCPropertyGridProperty::OnDrawButton +## `CMFCPropertyGridProperty::OnDrawButton` Called by the framework to draw a button that is contained in a property. -``` +```cpp virtual void OnDrawButton( CDC* pDC, CRect rectButton); @@ -1088,19 +1017,17 @@ virtual void OnDrawButton( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rectButton*
+*`rectButton`*\ [in] A bounding rectangle that specifies where to draw a button. -### Remarks - -## CMFCPropertyGridProperty::OnDrawDescription +## `CMFCPropertyGridProperty::OnDrawDescription` Called by the framework to draw the property description. -``` +```cpp virtual void OnDrawDescription( CDC* pDC, CRect rect); @@ -1108,21 +1035,21 @@ virtual void OnDrawDescription( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rect*
+*`rect`*\ [in] A bounding rectangle that specifies where to draw the property description. ### Remarks By default, this method draws the property name and description in the font used by the parent property list control. The property description is drawn in regular style and the property name is drawn in bold style. -## CMFCPropertyGridProperty::OnDrawExpandBox +## `CMFCPropertyGridProperty::OnDrawExpandBox` -Called by the framework to draw an expand box control near a property that contains sub-properties. +Called by the framework to draw an expand box control near a property that contains subproperties. -``` +```cpp virtual void OnDrawExpandBox( CDC* pDC, CRect rectExpand); @@ -1130,21 +1057,21 @@ virtual void OnDrawExpandBox( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rectExpand*
+*`rectExpand`*\ [in] A bounding rectangle that specifies where to draw the expand box control. ### Remarks -Click the expand box control to expand or collapse a list of sub-properties. The expand box control is designated by a square that contains a plus (+) or minus (-) sign. A plus sign indicates that the property can be expanded to show a list of sub-properties. A minus sign indicates that the list can be collapsed to show only the property. +Select the expand box control to expand or collapse a list of subproperties. The expand box control is designated by a square that contains a plus (**+**) or minus (**-**) sign. A plus sign indicates that the property can be expanded to show a list of subproperties. A minus sign indicates that the list can be collapsed to show only the property. -## CMFCPropertyGridProperty::OnDrawName +## `CMFCPropertyGridProperty::OnDrawName` Called by the framework to display the property name. -``` +```cpp virtual void OnDrawName( CDC* pDC, CRect rect); @@ -1152,19 +1079,17 @@ virtual void OnDrawName( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rect*
+*`rect`*\ [in] A bounding rectangle that specifies where to draw the property name. -### Remarks - -## CMFCPropertyGridProperty::OnDrawValue +## `CMFCPropertyGridProperty::OnDrawValue` Called by the framework to display the property value. -``` +```cpp virtual void OnDrawValue( CDC* pDC, CRect rect); @@ -1172,122 +1097,120 @@ virtual void OnDrawValue( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rect*
+*`rect`*\ [in] A bounding rectangle that specifies where to draw the property value. -### Remarks - -## CMFCPropertyGridProperty::OnEdit +## `CMFCPropertyGridProperty::OnEdit` Called by the framework when the user is about to modify a property value. -``` +```cpp virtual BOOL OnEdit(LPPOINT lptClick); ``` ### Parameters -*lptClick*
-[in] (This parameter is not used.) A pointer to a point, in client coordinates. +*`lptClick`*\ +[in] (This parameter isn't used.) A pointer to a point, in client coordinates. ### Return Value -TRUE if the edit operation starts successfully; otherwise, FALSE. +`TRUE` if the edit operation starts successfully; otherwise, `FALSE`. ### Remarks This function is called by the framework when the user is about to modify a property value. By default, this method starts the appropriate editor for a combo box control or a spin control. -## CMFCPropertyGridProperty::OnEndEdit +## `CMFCPropertyGridProperty::OnEndEdit` Called by the framework when the user is finished modifying a property value. -``` +```cpp virtual BOOL OnEndEdit(); ``` ### Return Value -This method always returns TRUE. +This method always returns `TRUE`. ### Remarks -By default, this method destroys the current editing control and then returns TRUE. +By default, this method destroys the current editing control and then returns `TRUE`. -## CMFCPropertyGridProperty::OnKillFocus +## `CMFCPropertyGridProperty::OnKillFocus` Called by the framework when the property loses the input focus. -``` +```cpp virtual BOOL OnKillFocus(CWnd*); ``` ### Parameters -*CWnd*\ +*`CWnd`*\ [in] (Not used.) Pointer to a window. ### Return Value -This method always returns TRUE. +This method always returns `TRUE`. ### Remarks -By default, this method does nothing and then returns TRUE. If you override this method, return TRUE if the framework can end the edit operation when the property loses the input focus. +By default, this method does nothing and then returns `TRUE`. If you override this method, return `TRUE` if the framework can end the edit operation when the property loses the input focus. -## CMFCPropertyGridProperty::OnKillSelection +## `CMFCPropertyGridProperty::OnKillSelection` -``` +```cpp virtual void OnKillSelection(CMFCPropertyGridProperty*); ``` ### Parameters -[in] *`CMFCPropertyGridProperty*`*
+[in] *`CMFCPropertyGridProperty*`* ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnPosSizeChanged +## `CMFCPropertyGridProperty::OnPosSizeChanged` -``` +```cpp virtual void OnPosSizeChanged(CRect); ``` ### Parameters -[in] *CRect*
+[in] *`CRect`* ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnRClickName +## `CMFCPropertyGridProperty::OnRClickName` -Called by the framework when the user clicks the right mouse button in the property name area. +Called by the framework when the user selects the right mouse button in the property name area. -``` +```cpp virtual void OnRClickName(CPoint C); ``` ### Parameters -*C*\ +*`C`*\ [in] A point, in client coordinates. ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnRClickValue +## `CMFCPropertyGridProperty::OnRClickValue` -Called by the framework when the user clicks the right mouse button in the property value area. +Called by the framework when the user selects the right mouse button in the property value area. -``` +```cpp virtual void OnRClickValue( CPoint C, BOOL B); @@ -1295,21 +1218,21 @@ virtual void OnRClickValue( ### Parameters -*C*\ +*`C`*\ [in] A point, in client coordinates. -*B*\ +*`B`*\ [in] A Boolean. ### Remarks -By default, this method does nothing and the *B* parameter has no predefined purpose. +By default, this method does nothing and the *`B`* parameter has no predefined purpose. -## CMFCPropertyGridProperty::OnSelectCombo +## `CMFCPropertyGridProperty::OnSelectCombo` Called by the framework when the user selects an item from the editable combo box. -``` +```cpp virtual void OnSelectCombo(); ``` @@ -1317,72 +1240,70 @@ virtual void OnSelectCombo(); By default, this method uses the text of the selected item to update the property value. -## CMFCPropertyGridProperty::OnSetCursor +## `CMFCPropertyGridProperty::OnSetCursor` Called by the framework when the mouse pointer moves to a property item. -``` +```cpp virtual BOOL OnSetCursor() const; ``` ### Return Value -TRUE if the current property is a variant type or a list of values, and this method successfully loads the insertion point (I-beam) mouse cursor; otherwise, FALSE. +`TRUE` if the current property is a variant type or a list of values, and this method successfully loads the insertion point (I-beam) mouse cursor; otherwise, `FALSE`. ### Remarks -This method supports the following variant types: VT_INT, VT_I2, VT_I4, VT_UINT, VT_UI1, VT_UI2, VT_UI4, VT_R4, VT_R8, and VT_BSTR. +This method supports the following variant types: `VT_INT`, `VT_I2`, `VT_I4`, `VT_UINT`, `VT_UI1`, `VT_UI2`, `VT_UI4`, `VT_R4`, `VT_R8`, and `VT_BSTR`. -## CMFCPropertyGridProperty::OnSetSelection +## `CMFCPropertyGridProperty::OnSetSelection` -``` -virtual void OnSetSelection CMFCPropertyGridProperty*); +```cpp +virtual void OnSetSelection(CMFCPropertyGridProperty*); ``` ### Parameters -[in] *`CMFCPropertyGridProperty*`*
+[in] *`CMFCPropertyGridProperty*`* ### Remarks By default, this method does nothing. -## CMFCPropertyGridProperty::OnUpdateValue +## `CMFCPropertyGridProperty::OnUpdateValue` Called by the framework when the value of an editable property has changed. -``` +```cpp virtual BOOL OnUpdateValue(); ``` ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. -### Remarks - -## CMFCPropertyGridProperty::PushChar +## `CMFCPropertyGridProperty::PushChar` Called from the property list control when the property is selected and the user enters a new character. -``` +```cpp virtual BOOL PushChar(UINT nChar); ``` ### Parameters -*nChar*
+*`nChar`*\ [in] A character. ### Return Value -TRUE if the edit operation is continuing; otherwise, FALSE. +`TRUE` if the edit operation is continuing; otherwise, `FALSE`. ### Remarks -This method supports a property that is either a list of values or one of the following variant types: VT_INT, VT_I2, VT_I4, VT_UINT, VT_UI1, VT_UI2, VT_UI4, VT_R4, VT_R8, and VT_BSTR. +This method supports a property that is either a list of values or one of the following variant types: `VT_INT`, `VT_I2`, `VT_I4`, `VT_UINT`, `VT_UI1`, `VT_UI2`, `VT_UI4`, `VT_R4`, `VT_R8`, and `VT_BSTR`. -## CMFCPropertyGridProperty::Redraw +## `CMFCPropertyGridProperty::Redraw` Redraws the property. @@ -1390,9 +1311,7 @@ Redraws the property. void Redraw(); ``` -### Remarks - -## CMFCPropertyGridProperty::RemoveAllOptions +## `CMFCPropertyGridProperty::RemoveAllOptions` Removes all options (items) from a property. @@ -1404,11 +1323,11 @@ void RemoveAllOptions(); Options are also known as the list items of a property list control. -## CMFCPropertyGridProperty::RemoveSubItem +## `CMFCPropertyGridProperty::RemoveSubItem` -Removes the specified sub-item. +Removes the specified subitem. -``` +```cpp BOOL RemoveSubItem( CMFCPropertyGridProperty*& pProp, BOOL bDelete=TRUE); @@ -1416,31 +1335,29 @@ BOOL RemoveSubItem( ### Parameters -*pProp*
-[in] Pointer to a property sub-item. +*`pProp`*\ +[in] Pointer to a property subitem. -*bDelete*
-[in] TRUE to delete the property object that is specified by the *pProp* parameter; otherwise, FALSE. The default value is TRUE. +*`bDelete`*\ +[in] `TRUE` to delete the property object that is specified by the *`pProp`* parameter; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value ### Remarks -Specify FALSE for the *bDelete* parameter if you intend to move the specified sub-item; that is, remove the sub-item and then add it elsewhere. +Specify `FALSE` for the *`bDelete`* parameter if you intend to move the specified subitem; that is, remove the subitem and then add it elsewhere. -## CMFCPropertyGridProperty::ResetOriginalValue +## `CMFCPropertyGridProperty::ResetOriginalValue` Restores the original value of an edited property. -``` +```cpp virtual void ResetOriginalValue(); ``` -### Remarks - -## CMFCPropertyGridProperty::SetData +## `CMFCPropertyGridProperty::SetData` -Associates a DWORD value with a property. +Associates a `DWORD` value with a property. ```cpp void SetData(DWORD_PTR dwData); @@ -1448,14 +1365,14 @@ void SetData(DWORD_PTR dwData); ### Parameters -*dwData*
+*`dwData`*\ [in] An application-specific 32-bit value, such as an integer or a pointer to other data. ### Remarks -Use the [CMFCPropertyGridProperty::GetData](#getdata) method to retrieve the DWORD value. Use the [CMFCPropertyGridCtrl::FindItemByData](../../mfc/reference/cmfcpropertygridctrl-class.md#finditembydata) method to locate the property list item that is associated with the specified DWORD value. +Use the [`CMFCPropertyGridProperty::GetData`](#getdata) method to retrieve the `DWORD` value. Use the [`CMFCPropertyGridCtrl::FindItemByData`](../../mfc/reference/cmfcpropertygridctrl-class.md#finditembydata) method to locate the property list item that is associated with the specified `DWORD` value. -## CMFCPropertyGridProperty::SetDescription +## `CMFCPropertyGridProperty::SetDescription` Specifies the text that describes the current property. @@ -1465,12 +1382,10 @@ void SetDescription(const CString& strDescr); ### Parameters -*strDescr*
+*`strDescr`*\ [in] Text that describes the current property. -### Remarks - -## CMFCPropertyGridProperty::SetName +## `CMFCPropertyGridProperty::SetName` Sets the name of a property. @@ -1482,47 +1397,56 @@ void SetName( ### Parameters -*lpszName*
+*`lpszName`*\ [in] The property name. -*bRedraw*
-[in] TRUE to redraw the property immediately; otherwise, FALSE. The default value is TRUE. +*`bRedraw`*\ +[in] `TRUE` to redraw the property immediately; otherwise, `FALSE`. The default value is `TRUE`. -### Remarks - -## CMFCPropertyGridProperty::SetOriginalValue +## `CMFCPropertyGridProperty::SetOriginalValue` Sets the original value of an editable property. -``` +```cpp virtual void SetOriginalValue(const COleVariant& varValue); ``` ### Parameters -*varValue*
+*`varValue`*\ [in] A value. ### Remarks -Use the [CMFCPropertyGridProperty::ResetOriginalValue](#resetoriginalvalue) method to reset the original value of an edited property. +Use the [`CMFCPropertyGridProperty::ResetOriginalValue`](#resetoriginalvalue) method to reset the original value of an edited property. -## CMFCPropertyGridProperty::SetValue +## `CMFCPropertyGridProperty::SetValue` Sets the value of a property grid property. -``` +```cpp virtual void SetValue(const _variant_t& varValue); ``` ### Parameters -*varValue*
-[in] A reference to a value. +*`varValue`*\ +[in] A reference to the value to set the property to. -### Remarks +### Example: `SetValue` + +```cpp +void SetPropBarValue(UINT propId, const DWORD& barPropDwordValue) +{ + auto property = propertiesGridCtrlList.FindItemByData(propId); + if (property != nullptr) + { + property->SetValue(static_cast<_variant_t >(barPropDwordValue == 1)); // set value to true or false depending on dword value + } +} +``` -## CMFCPropertyGridProperty::Show +## `CMFCPropertyGridProperty::Show` Shows or hides a property. @@ -1534,14 +1458,14 @@ void Show( ### Parameters -*bShow*
-[in] TRUE to display the current property and its sub-items; FALSE to hide the current property and its sub-items. The default value is TRUE. +*`bShow`*\ +[in] `TRUE` to display the current property and its subitems; `FALSE` to hide the current property and its subitems. The default value is `TRUE`. -*bAdjustLayout*
-[in] TRUE to recalculate how to draw the label and value of a property and then draw the property; FALSE to use existing calculations to draw the property. The default value is TRUE. +*`bAdjustLayout`*\ +[in] `TRUE` to recalculate how to draw the label and value of a property and then draw the property; `FALSE` to use existing calculations to draw the property. The default value is `TRUE`. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCPropertyGridCtrl Class](../../mfc/reference/cmfcpropertygridctrl-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMFCPropertyGridCtrl` class](../../mfc/reference/cmfcpropertygridctrl-class.md) diff --git a/docs/mfc/reference/cmfcrebar-class.md b/docs/mfc/reference/cmfcrebar-class.md index edf17e6c6e..355e63c99e 100644 --- a/docs/mfc/reference/cmfcrebar-class.md +++ b/docs/mfc/reference/cmfcrebar-class.md @@ -52,10 +52,10 @@ The following example demonstrates how to use various methods in the `CMFCReBar` [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CPane](../../mfc/reference/cpane-class.md)\ -                └ [CMFCReBar](../../mfc/reference/cmfcrebar-class.md) + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CPane](../../mfc/reference/cpane-class.md)\ +    └ [CMFCReBar](../../mfc/reference/cmfcrebar-class.md) ## Requirements diff --git a/docs/mfc/reference/cmfcribbonbar-class.md b/docs/mfc/reference/cmfcribbonbar-class.md index 8271d48243..b3ec1757ee 100644 --- a/docs/mfc/reference/cmfcribbonbar-class.md +++ b/docs/mfc/reference/cmfcribbonbar-class.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: CMFCRibbonBar Class" title: "CMFCRibbonBar Class" +description: "Learn more about: CMFCRibbonBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar::ActivateContextCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddContextCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddMainCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddPrintPreviewCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddQATOnlyCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddToTabs", "AFXRIBBONBAR/CMFCRibbonBar::CreateEx", "AFXRIBBONBAR/CMFCRibbonBar::Create", "AFXRIBBONBAR/CMFCRibbonBar::DeactivateKeyboardFocus", "AFXRIBBONBAR/CMFCRibbonBar::DrawMenuImage", "AFXRIBBONBAR/CMFCRibbonBar::DWMCompositionChanged", "AFXRIBBONBAR/CMFCRibbonBar::EnableKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::EnablePrintPreview", "AFXRIBBONBAR/CMFCRibbonBar::EnableToolTips", "AFXRIBBONBAR/CMFCRibbonBar::FindByData", "AFXRIBBONBAR/CMFCRibbonBar::FindByID", "AFXRIBBONBAR/CMFCRibbonBar::FindCategoryIndexByData", "AFXRIBBONBAR/CMFCRibbonBar::ForceRecalcLayout", "AFXRIBBONBAR/CMFCRibbonBar::GetActiveCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetCaptionHeight", "AFXRIBBONBAR/CMFCRibbonBar::GetCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryCount", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryHeight", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryIndex", "AFXRIBBONBAR/CMFCRibbonBar::GetContextName", "AFXRIBBONBAR/CMFCRibbonBar::GetDroppedDown", "AFXRIBBONBAR/CMFCRibbonBar::GetElementsByID", "AFXRIBBONBAR/CMFCRibbonBar::GetApplicationButton", "AFXRIBBONBAR/CMFCRibbonBar::GetFocused", "AFXRIBBONBAR/CMFCRibbonBar::GetHideFlags", "AFXRIBBONBAR/CMFCRibbonBar::GetItemIDsList", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavigationLevel", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavLevelCurrent", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavLevelParent", "AFXRIBBONBAR/CMFCRibbonBar::GetMainCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetQATCommandsLocation", "AFXRIBBONBAR/CMFCRibbonBar::GetQATDroppedDown", "AFXRIBBONBAR/CMFCRibbonBar::GetQuickAccessCommands", "AFXRIBBONBAR/CMFCRibbonBar::GetQuickAccessToolbarLocation", "AFXRIBBONBAR/CMFCRibbonBar::GetTabTrancateRatio", "AFXRIBBONBAR/CMFCRibbonBar::GetTooltipFixedWidthLargeImage", "AFXRIBBONBAR/CMFCRibbonBar::GetTooltipFixedWidthRegular", "AFXRIBBONBAR/CMFCRibbonBar::GetVisibleCategoryCount", "AFXRIBBONBAR/CMFCRibbonBar::HideAllContextCategories", "AFXRIBBONBAR/CMFCRibbonBar::HideKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::HitTest", "AFXRIBBONBAR/CMFCRibbonBar::IsKeyTipEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsMainRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar::IsPrintPreviewEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsQATEmpty", "AFXRIBBONBAR/CMFCRibbonBar::IsQuickAccessToolbarOnTop", "AFXRIBBONBAR/CMFCRibbonBar::IsReplaceFrameCaption", "AFXRIBBONBAR/CMFCRibbonBar::IsShowGroupBorder", "AFXRIBBONBAR/CMFCRibbonBar::IsToolTipDescrEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsToolTipEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsTransparentCaption", "AFXRIBBONBAR/CMFCRibbonBar::IsWindows7Look", "AFXRIBBONBAR/CMFCRibbonBar::LoadFromResource", "AFXRIBBONBAR/CMFCRibbonBar::OnClickButton", "AFXRIBBONBAR/CMFCRibbonBar::OnEditContextMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnRTLChanged", "AFXRIBBONBAR/CMFCRibbonBar::OnSetAccData", "AFXRIBBONBAR/CMFCRibbonBar::OnShowRibbonContextMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnShowRibbonQATMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnSysKeyDown", "AFXRIBBONBAR/CMFCRibbonBar::OnSysKeyUp", "AFXRIBBONBAR/CMFCRibbonBar::PopTooltip", "AFXRIBBONBAR/CMFCRibbonBar::PreTranslateMessage", "AFXRIBBONBAR/CMFCRibbonBar::RecalcLayout", "AFXRIBBONBAR/CMFCRibbonBar::RemoveAllCategories", "AFXRIBBONBAR/CMFCRibbonBar::RemoveAllFromTabs", "AFXRIBBONBAR/CMFCRibbonBar::RemoveCategory", "AFXRIBBONBAR/CMFCRibbonBar::SaveToXMLBuffer", "AFXRIBBONBAR/CMFCRibbonBar::SaveToXMLFile", "AFXRIBBONBAR/CMFCRibbonBar::SetActiveCategory", "AFXRIBBONBAR/CMFCRibbonBar::SetActiveMDIChild", "AFXRIBBONBAR/CMFCRibbonBar::SetElementKeys", "AFXRIBBONBAR/CMFCRibbonBar::SetApplicationButton", "AFXRIBBONBAR/CMFCRibbonBar::SetKeyboardNavigationLevel", "AFXRIBBONBAR/CMFCRibbonBar::SetMaximizeMode", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessCommands", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessDefaultState", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessToolbarOnTop", "AFXRIBBONBAR/CMFCRibbonBar::SetTooltipFixedWidth", "AFXRIBBONBAR/CMFCRibbonBar::SetWindows7Look", "AFXRIBBONBAR/CMFCRibbonBar::ShowCategory", "AFXRIBBONBAR/CMFCRibbonBar::ShowContextCategories", "AFXRIBBONBAR/CMFCRibbonBar::ShowKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::ToggleMimimizeState", "AFXRIBBONBAR/CMFCRibbonBar::TranslateChar"] helpviewer_keywords: ["CMFCRibbonBar [MFC], ActivateContextCategory", "CMFCRibbonBar [MFC], AddCategory", "CMFCRibbonBar [MFC], AddContextCategory", "CMFCRibbonBar [MFC], AddMainCategory", "CMFCRibbonBar [MFC], AddPrintPreviewCategory", "CMFCRibbonBar [MFC], AddQATOnlyCategory", "CMFCRibbonBar [MFC], AddToTabs", "CMFCRibbonBar [MFC], CreateEx", "CMFCRibbonBar [MFC], Create", "CMFCRibbonBar [MFC], DeactivateKeyboardFocus", "CMFCRibbonBar [MFC], DrawMenuImage", "CMFCRibbonBar [MFC], DWMCompositionChanged", "CMFCRibbonBar [MFC], EnableKeyTips", "CMFCRibbonBar [MFC], EnablePrintPreview", "CMFCRibbonBar [MFC], EnableToolTips", "CMFCRibbonBar [MFC], FindByData", "CMFCRibbonBar [MFC], FindByID", "CMFCRibbonBar [MFC], FindCategoryIndexByData", "CMFCRibbonBar [MFC], ForceRecalcLayout", "CMFCRibbonBar [MFC], GetActiveCategory", "CMFCRibbonBar [MFC], GetCaptionHeight", "CMFCRibbonBar [MFC], GetCategory", "CMFCRibbonBar [MFC], GetCategoryCount", "CMFCRibbonBar [MFC], GetCategoryHeight", "CMFCRibbonBar [MFC], GetCategoryIndex", "CMFCRibbonBar [MFC], GetContextName", "CMFCRibbonBar [MFC], GetDroppedDown", "CMFCRibbonBar [MFC], GetElementsByID", "CMFCRibbonBar [MFC], GetApplicationButton", "CMFCRibbonBar [MFC], GetFocused", "CMFCRibbonBar [MFC], GetHideFlags", "CMFCRibbonBar [MFC], GetItemIDsList", "CMFCRibbonBar [MFC], GetKeyboardNavigationLevel", "CMFCRibbonBar [MFC], GetKeyboardNavLevelCurrent", "CMFCRibbonBar [MFC], GetKeyboardNavLevelParent", "CMFCRibbonBar [MFC], GetMainCategory", "CMFCRibbonBar [MFC], GetQATCommandsLocation", "CMFCRibbonBar [MFC], GetQATDroppedDown", "CMFCRibbonBar [MFC], GetQuickAccessCommands", "CMFCRibbonBar [MFC], GetQuickAccessToolbarLocation", "CMFCRibbonBar [MFC], GetTabTrancateRatio", "CMFCRibbonBar [MFC], GetTooltipFixedWidthLargeImage", "CMFCRibbonBar [MFC], GetTooltipFixedWidthRegular", "CMFCRibbonBar [MFC], GetVisibleCategoryCount", "CMFCRibbonBar [MFC], HideAllContextCategories", "CMFCRibbonBar [MFC], HideKeyTips", "CMFCRibbonBar [MFC], HitTest", "CMFCRibbonBar [MFC], IsKeyTipEnabled", "CMFCRibbonBar [MFC], IsMainRibbonBar", "CMFCRibbonBar [MFC], IsPrintPreviewEnabled", "CMFCRibbonBar [MFC], IsQATEmpty", "CMFCRibbonBar [MFC], IsQuickAccessToolbarOnTop", "CMFCRibbonBar [MFC], IsReplaceFrameCaption", "CMFCRibbonBar [MFC], IsShowGroupBorder", "CMFCRibbonBar [MFC], IsToolTipDescrEnabled", "CMFCRibbonBar [MFC], IsToolTipEnabled", "CMFCRibbonBar [MFC], IsTransparentCaption", "CMFCRibbonBar [MFC], IsWindows7Look", "CMFCRibbonBar [MFC], LoadFromResource", "CMFCRibbonBar [MFC], OnClickButton", "CMFCRibbonBar [MFC], OnEditContextMenu", "CMFCRibbonBar [MFC], OnRTLChanged", "CMFCRibbonBar [MFC], OnSetAccData", "CMFCRibbonBar [MFC], OnShowRibbonContextMenu", "CMFCRibbonBar [MFC], OnShowRibbonQATMenu", "CMFCRibbonBar [MFC], OnSysKeyDown", "CMFCRibbonBar [MFC], OnSysKeyUp", "CMFCRibbonBar [MFC], PopTooltip", "CMFCRibbonBar [MFC], PreTranslateMessage", "CMFCRibbonBar [MFC], RecalcLayout", "CMFCRibbonBar [MFC], RemoveAllCategories", "CMFCRibbonBar [MFC], RemoveAllFromTabs", "CMFCRibbonBar [MFC], RemoveCategory", "CMFCRibbonBar [MFC], SaveToXMLBuffer", "CMFCRibbonBar [MFC], SaveToXMLFile", "CMFCRibbonBar [MFC], SetActiveCategory", "CMFCRibbonBar [MFC], SetActiveMDIChild", "CMFCRibbonBar [MFC], SetElementKeys", "CMFCRibbonBar [MFC], SetApplicationButton", "CMFCRibbonBar [MFC], SetKeyboardNavigationLevel", "CMFCRibbonBar [MFC], SetMaximizeMode", "CMFCRibbonBar [MFC], SetQuickAccessCommands", "CMFCRibbonBar [MFC], SetQuickAccessDefaultState", "CMFCRibbonBar [MFC], SetQuickAccessToolbarOnTop", "CMFCRibbonBar [MFC], SetTooltipFixedWidth", "CMFCRibbonBar [MFC], SetWindows7Look", "CMFCRibbonBar [MFC], ShowCategory", "CMFCRibbonBar [MFC], ShowContextCategories", "CMFCRibbonBar [MFC], ShowKeyTips", "CMFCRibbonBar [MFC], ToggleMimimizeState", "CMFCRibbonBar [MFC], TranslateChar"] -ms.assetid: a65d06fa-1a28-4cc0-8971-bc9d7c9198fe --- -# CMFCRibbonBar Class +# `CMFCRibbonBar` Class The `CMFCRibbonBar` class implements a ribbon bar similar to that used in Office 2007. -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. +For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ## Syntax @@ -30,127 +29,127 @@ class CMFCRibbonBar : public CPane |Name|Description| |----------|-----------------| -|[CMFCRibbonBar::ActivateContextCategory](#activatecontextcategory)|Activates a context category that is already visible.| -|[CMFCRibbonBar::AddCategory](#addcategory)|Adds a new ribbon category to the ribbon.| -|[CMFCRibbonBar::AddContextCategory](#addcontextcategory)|Adds a context category.| -|[CMFCRibbonBar::AddMainCategory](#addmaincategory)|Adds a new main ribbon category.| -|[CMFCRibbonBar::AddPrintPreviewCategory](#addprintpreviewcategory)|| -|[CMFCRibbonBar::AddQATOnlyCategory](#addqatonlycategory)|| -|[CMFCRibbonBar::AddToTabs](#addtotabs)|Add a ribbon element to the right side of a ribbon bar.| -|[CMFCRibbonBar::CreateEx](#createex)|Creates a control bar and attaches it to the [CPane](../../mfc/reference/cpane-class.md) object. (Overrides [CPane::CreateEx](../../mfc/reference/cpane-class.md#createex).)| -|[CMFCRibbonBar::Create](#create)|Creates a ribbon bar control and attaches it to a ribbon bar.| -|[CMFCRibbonBar::DeactivateKeyboardFocus](#deactivatekeyboardfocus)|| -|[CMFCRibbonBar::DrawMenuImage](#drawmenuimage)|| -|[CMFCRibbonBar::DWMCompositionChanged](#dwmcompositionchanged)|| -|[CMFCRibbonBar::EnableKeyTips](#enablekeytips)|Enable or disable key tips for the ribbon control.| -|[CMFCRibbonBar::EnablePrintPreview](#enableprintpreview)|Enable the **Print Preview** tab.| -|[CMFCRibbonBar::EnableToolTips](#enabletooltips)|Enables or disables tooltips and tooltip descriptions on the ribbon bar.| -|[CMFCRibbonBar::FindByData](#findbydata)|Find a ribbon element by using data that a user specifies.| -|[CMFCRibbonBar::FindByID](#findbyid)|Finds a ribbon element that has the specified command id.| -|[CMFCRibbonBar::FindCategoryIndexByData](#findcategoryindexbydata)|Finds the index of the ribbon category that contains the user-defined data.| -|[CMFCRibbonBar::ForceRecalcLayout](#forcerecalclayout)|| -|[CMFCRibbonBar::GetActiveCategory](#getactivecategory)|Gets a pointer to an active category.| -|[CMFCRibbonBar::GetCaptionHeight](#getcaptionheight)|Returns the caption height. (Overrides [CBasePane::GetCaptionHeight](../../mfc/reference/cbasepane-class.md#getcaptionheight).)| -|[CMFCRibbonBar::GetCategory](#getcategory)|Gets the pointer to a category located at a specified index.| -|[CMFCRibbonBar::GetCategoryCount](#getcategorycount)|Gets the number of the ribbon categories in the ribbon bar.| -|[CMFCRibbonBar::GetCategoryHeight](#getcategoryheight)|| -|[CMFCRibbonBar::GetCategoryIndex](#getcategoryindex)|Returns the index of a ribbon category.| -|[CMFCRibbonBar::GetContextName](#getcontextname)|Retrieves the name of the context category caption that you specify by using an ID.| -|[CMFCRibbonBar::GetDroppedDown](#getdroppeddown)|| -|[CMFCRibbonBar::GetElementsByID](#getelementsbyid)|Gets an array that contains the pointers to all the ribbon elements that have the specified ID.| -|[CMFCRibbonBar::GetApplicationButton](#getapplicationbutton)|Gets a pointer to a ribbon button.| -|[CMFCRibbonBar::GetFocused](#getfocused)|Returns a focused element.| -|[CMFCRibbonBar::GetHideFlags](#gethideflags)|| -|[CMFCRibbonBar::GetItemIDsList](#getitemidslist)|| -|[CMFCRibbonBar::GetKeyboardNavigationLevel](#getkeyboardnavigationlevel)|| -|[CMFCRibbonBar::GetKeyboardNavLevelCurrent](#getkeyboardnavlevelcurrent)|| -|[CMFCRibbonBar::GetKeyboardNavLevelParent](#getkeyboardnavlevelparent)|| -|[CMFCRibbonBar::GetMainCategory](#getmaincategory)|Returns a pointer to the ribbon category that is currently selected.| -|[CMFCRibbonBar::GetQATCommandsLocation](#getqatcommandslocation)|| -|[CMFCRibbonBar::GetQATDroppedDown](#getqatdroppeddown)|| -|[CMFCRibbonBar::GetQuickAccessCommands](#getquickaccesscommands)|Fills a list that contains the command IDs of all the elements that appear on the Quick Access Toolbar.| -|[CMFCRibbonBar::GetQuickAccessToolbarLocation](#getquickaccesstoolbarlocation)|| -|[CMFCRibbonBar::GetTabTrancateRatio](#gettabtrancateratio)|| -|[CMFCRibbonBar::GetTooltipFixedWidthLargeImage](#gettooltipfixedwidthlargeimage)|| -|[CMFCRibbonBar::GetTooltipFixedWidthRegular](#gettooltipfixedwidthregular)|| -|[CMFCRibbonBar::GetVisibleCategoryCount](#getvisiblecategorycount)|| -|[CMFCRibbonBar::HideAllContextCategories](#hideallcontextcategories)|Hides all the categories that are active and visible.| -|[CMFCRibbonBar::HideKeyTips](#hidekeytips)|| -|[CMFCRibbonBar::HitTest](#hittest)|Finds a pointer to the ribbon element that is located at the specified point in the ribbon bar's client coordinates.| -|[CMFCRibbonBar::IsKeyTipEnabled](#iskeytipenabled)|Determines whether keytips are enabled.| -|[CMFCRibbonBar::IsMainRibbonBar](#ismainribbonbar)|| -|[CMFCRibbonBar::IsPrintPreviewEnabled](#isprintpreviewenabled)|Determines whether the **Print Preview** tab is enabled.| -|[CMFCRibbonBar::IsQATEmpty](#isqatempty)|| -|[CMFCRibbonBar::IsQuickAccessToolbarOnTop](#isquickaccesstoolbarontop)|Specifies whether the Quick Access Toolbar is located above the ribbon bar.| -|[CMFCRibbonBar::IsReplaceFrameCaption](#isreplaceframecaption)|Determines whether the ribbon bar replaces the main frame caption, or is added below the frame caption.| -|[CMFCRibbonBar::IsShowGroupBorder](#isshowgroupborder)|| -|[CMFCRibbonBar::IsToolTipDescrEnabled](#istooltipdescrenabled)|Determines whether the tooltip descriptions are enabled.| -|[CMFCRibbonBar::IsToolTipEnabled](#istooltipenabled)|Determines whether the tooltips for the ribbon bar are enabled.| -|[CMFCRibbonBar::IsTransparentCaption](#istransparentcaption)|| -|[CMFCRibbonBar::IsWindows7Look](#iswindows7look)|Indicates whether the ribbon has Windows 7-style look (small rectangular application button).| -|[CMFCRibbonBar::LoadFromResource](#loadfromresource)|Overloaded. Loads a Ribbon Bar from application resources.| -|[CMFCRibbonBar::OnClickButton](#onclickbutton)|| -|[CMFCRibbonBar::OnEditContextMenu](#oneditcontextmenu)|| -|[CMFCRibbonBar::OnRTLChanged](#onrtlchanged)|(Overrides `CPane::OnRTLChanged`.)| -|[CMFCRibbonBar::OnSetAccData](#onsetaccdata)|(Overrides [CBasePane::OnSetAccData](../../mfc/reference/cbasepane-class.md#onsetaccdata).)| -|[CMFCRibbonBar::OnShowRibbonContextMenu](#onshowribboncontextmenu)|| -|[CMFCRibbonBar::OnShowRibbonQATMenu](#onshowribbonqatmenu)|| -|[CMFCRibbonBar::OnSysKeyDown](#onsyskeydown)|| -|[CMFCRibbonBar::OnSysKeyUp](#onsyskeyup)|| -|[CMFCRibbonBar::PopTooltip](#poptooltip)|| -|[CMFCRibbonBar::PreTranslateMessage](#pretranslatemessage)|(Overrides `CBasePane::PreTranslateMessage`.)| -|[CMFCRibbonBar::RecalcLayout](#recalclayout)|(Overrides [CPane::RecalcLayout](../../mfc/reference/cpane-class.md#recalclayout).)| -|[CMFCRibbonBar::RemoveAllCategories](#removeallcategories)|Removes all the ribbon categories from the ribbon bar.| -|[CMFCRibbonBar::RemoveAllFromTabs](#removeallfromtabs)|Removes all ribbon elements from the tab area.| -|[CMFCRibbonBar::RemoveCategory](#removecategory)|Removes the ribbon category that is located at the specified index.| -|[CMFCRibbonBar::SaveToXMLBuffer](#savetoxmlbuffer)|Saves the Ribbon Bar to a buffer.| -|[CMFCRibbonBar::SaveToXMLFile](#savetoxmlfile)|Saves the Ribbon Bar to XML file.| -|[CMFCRibbonBar::SetActiveCategory](#setactivecategory)|Sets a specified ribbon category to active.| -|[CMFCRibbonBar::SetActiveMDIChild](#setactivemdichild)|| -|[CMFCRibbonBar::SetElementKeys](#setelementkeys)|Sets the specified keytips for all ribbon elements that have the specified command ID.| -|[CMFCRibbonBar::SetApplicationButton](#setapplicationbutton)|Assigns an application ribbon button to the ribbon bar.| -|[CMFCRibbonBar::SetKeyboardNavigationLevel](#setkeyboardnavigationlevel)|| -|[CMFCRibbonBar::SetMaximizeMode](#setmaximizemode)|| -|[CMFCRibbonBar::SetQuickAccessCommands](#setquickaccesscommands)|Adds one or more ribbon elements to the Quick Access Toolbar.| -|[CMFCRibbonBar::SetQuickAccessDefaultState](#setquickaccessdefaultstate)|Specifies the default state for the Quick Access Toolbar.| -|[CMFCRibbonBar::SetQuickAccessToolbarOnTop](#setquickaccesstoolbarontop)|Positions the Quick Access Toolbar (QAT) above or below the ribbon bar.| -|[CMFCRibbonBar::SetTooltipFixedWidth](#settooltipfixedwidth)|| -|[CMFCRibbonBar::SetWindows7Look](#setwindows7look)|Enable/disable ribbon Windows 7-style look (small rectangular application button)| -|[CMFCRibbonBar::ShowCategory](#showcategory)|Shows or hides the specified ribbon category.| -|[CMFCRibbonBar::ShowContextCategories](#showcontextcategories)|Shows or hides the context categories that have the specified ID.| -|[CMFCRibbonBar::ShowKeyTips](#showkeytips)|| -|[CMFCRibbonBar::ToggleMimimizeState](#togglemimimizestate)|Toggles the ribbon bar between the minimized and maximized states..| -|[CMFCRibbonBar::TranslateChar](#translatechar)|| +|[`CMFCRibbonBar::ActivateContextCategory`](#activatecontextcategory)|Activates a context category that is already visible.| +|[`CMFCRibbonBar::AddCategory`](#addcategory)|Adds a new ribbon category to the ribbon.| +|[`CMFCRibbonBar::AddContextCategory`](#addcontextcategory)|Adds a context category.| +|[`CMFCRibbonBar::AddMainCategory`](#addmaincategory)|Adds a new main ribbon category.| +|[`CMFCRibbonBar::AddPrintPreviewCategory`](#addprintpreviewcategory)|| +|[`CMFCRibbonBar::AddQATOnlyCategory`](#addqatonlycategory)|| +|[`CMFCRibbonBar::AddToTabs`](#addtotabs)|Add a ribbon element to the right side of a ribbon bar.| +|[`CMFCRibbonBar::CreateEx`](#createex)|Creates a control bar and attaches it to the [`CPane`](../../mfc/reference/cpane-class.md) object. (Overrides [`CPane::CreateEx`](../../mfc/reference/cpane-class.md#createex).)| +|[`CMFCRibbonBar::Create`](#create)|Creates a ribbon bar control and attaches it to a ribbon bar.| +|[`CMFCRibbonBar::DeactivateKeyboardFocus`](#deactivatekeyboardfocus)|| +|[`CMFCRibbonBar::DrawMenuImage`](#drawmenuimage)|| +|[`CMFCRibbonBar::DWMCompositionChanged`](#dwmcompositionchanged)|| +|[`CMFCRibbonBar::EnableKeyTips`](#enablekeytips)|Enable or disable key tips for the ribbon control.| +|[`CMFCRibbonBar::EnablePrintPreview`](#enableprintpreview)|Enable the **Print Preview** tab.| +|[`CMFCRibbonBar::EnableToolTips`](#enabletooltips)|Enables or disables tooltips and tooltip descriptions on the ribbon bar.| +|[`CMFCRibbonBar::FindByData`](#findbydata)|Find a ribbon element by using data that a user specifies.| +|[`CMFCRibbonBar::FindByID`](#findbyid)|Finds a ribbon element that has the specified command ID.| +|[`CMFCRibbonBar::FindCategoryIndexByData`](#findcategoryindexbydata)|Finds the index of the ribbon category that contains the user-defined data.| +|[`CMFCRibbonBar::ForceRecalcLayout`](#forcerecalclayout)|| +|[`CMFCRibbonBar::GetActiveCategory`](#getactivecategory)|Gets a pointer to an active category.| +|[`CMFCRibbonBar::GetCaptionHeight`](#getcaptionheight)|Returns the caption height. (Overrides [`CBasePane::GetCaptionHeight`](../../mfc/reference/cbasepane-class.md#getcaptionheight).)| +|[`CMFCRibbonBar::GetCategory`](#getcategory)|Gets the pointer to a category located at a specified index.| +|[`CMFCRibbonBar::GetCategoryCount`](#getcategorycount)|Gets the number of the ribbon categories in the ribbon bar.| +|[`CMFCRibbonBar::GetCategoryHeight`](#getcategoryheight)|| +|[`CMFCRibbonBar::GetCategoryIndex`](#getcategoryindex)|Returns the index of a ribbon category.| +|[`CMFCRibbonBar::GetContextName`](#getcontextname)|Retrieves the name of the context category caption that you specify by using an ID.| +|[`CMFCRibbonBar::GetDroppedDown`](#getdroppeddown)|| +|[`CMFCRibbonBar::GetElementsByID`](#getelementsbyid)|Gets an array that contains the pointers to all the ribbon elements that have the specified ID.| +|[`CMFCRibbonBar::GetApplicationButton`](#getapplicationbutton)|Gets a pointer to a ribbon button.| +|[`CMFCRibbonBar::GetFocused`](#getfocused)|Returns a focused element.| +|[`CMFCRibbonBar::GetHideFlags`](#gethideflags)|| +|[`CMFCRibbonBar::GetItemIDsList`](#getitemidslist)|| +|[`CMFCRibbonBar::GetKeyboardNavigationLevel`](#getkeyboardnavigationlevel)|| +|[`CMFCRibbonBar::GetKeyboardNavLevelCurrent`](#getkeyboardnavlevelcurrent)|| +|[`CMFCRibbonBar::GetKeyboardNavLevelParent`](#getkeyboardnavlevelparent)|| +|[`CMFCRibbonBar::GetMainCategory`](#getmaincategory)|Returns a pointer to the ribbon category that is currently selected.| +|[`CMFCRibbonBar::GetQATCommandsLocation`](#getqatcommandslocation)|| +|[`CMFCRibbonBar::GetQATDroppedDown`](#getqatdroppeddown)|| +|[`CMFCRibbonBar::GetQuickAccessCommands`](#getquickaccesscommands)|Fills a list that contains the command IDs of all the elements that appear on the Quick Access Toolbar.| +|[`CMFCRibbonBar::GetQuickAccessToolbarLocation`](#getquickaccesstoolbarlocation)|| +|[`CMFCRibbonBar::GetTabTrancateRatio`](#gettabtrancateratio)|| +|[`CMFCRibbonBar::GetTooltipFixedWidthLargeImage`](#gettooltipfixedwidthlargeimage)|| +|[`CMFCRibbonBar::GetTooltipFixedWidthRegular`](#gettooltipfixedwidthregular)|| +|[`CMFCRibbonBar::GetVisibleCategoryCount`](#getvisiblecategorycount)|| +|[`CMFCRibbonBar::HideAllContextCategories`](#hideallcontextcategories)|Hides all the categories that are active and visible.| +|[`CMFCRibbonBar::HideKeyTips`](#hidekeytips)|| +|[`CMFCRibbonBar::HitTest`](#hittest)|Finds a pointer to the ribbon element that is located at the specified point in the ribbon bar's client coordinates.| +|[`CMFCRibbonBar::IsKeyTipEnabled`](#iskeytipenabled)|Determines whether keytips are enabled.| +|[`CMFCRibbonBar::IsMainRibbonBar`](#ismainribbonbar)|| +|[`CMFCRibbonBar::IsPrintPreviewEnabled`](#isprintpreviewenabled)|Determines whether the **Print Preview** tab is enabled.| +|[`CMFCRibbonBar::IsQATEmpty`](#isqatempty)|| +|[`CMFCRibbonBar::IsQuickAccessToolbarOnTop`](#isquickaccesstoolbarontop)|Specifies whether the Quick Access Toolbar is located above the ribbon bar.| +|[`CMFCRibbonBar::IsReplaceFrameCaption`](#isreplaceframecaption)|Determines whether the ribbon bar replaces the main frame caption, or is added below the frame caption.| +|[`CMFCRibbonBar::IsShowGroupBorder`](#isshowgroupborder)|| +|[`CMFCRibbonBar::IsToolTipDescrEnabled`](#istooltipdescrenabled)|Determines whether the tooltip descriptions are enabled.| +|[`CMFCRibbonBar::IsToolTipEnabled`](#istooltipenabled)|Determines whether the tooltips for the ribbon bar are enabled.| +|[`CMFCRibbonBar::IsTransparentCaption`](#istransparentcaption)|| +|[`CMFCRibbonBar::IsWindows7Look`](#iswindows7look)|Indicates whether the ribbon has Windows 7-style look (small rectangular application button).| +|[`CMFCRibbonBar::LoadFromResource`](#loadfromresource)|Overloaded. Loads a Ribbon Bar from application resources.| +|[`CMFCRibbonBar::OnClickButton`](#onclickbutton)|| +|[`CMFCRibbonBar::OnEditContextMenu`](#oneditcontextmenu)|| +|[`CMFCRibbonBar::OnRTLChanged`](#onrtlchanged)|(Overrides `CPane::OnRTLChanged`.)| +|[`CMFCRibbonBar::OnSetAccData`](#onsetaccdata)|(Overrides [`CBasePane::OnSetAccData`](../../mfc/reference/cbasepane-class.md#onsetaccdata).)| +|[`CMFCRibbonBar::OnShowRibbonContextMenu`](#onshowribboncontextmenu)|| +|[`CMFCRibbonBar::OnShowRibbonQATMenu`](#onshowribbonqatmenu)|| +|[`CMFCRibbonBar::OnSysKeyDown`](#onsyskeydown)|| +|[`CMFCRibbonBar::OnSysKeyUp`](#onsyskeyup)|| +|[`CMFCRibbonBar::PopTooltip`](#poptooltip)|| +|[`CMFCRibbonBar::PreTranslateMessage`](#pretranslatemessage)|(Overrides `CBasePane::PreTranslateMessage`.)| +|[`CMFCRibbonBar::RecalcLayout`](#recalclayout)|(Overrides [`CPane::RecalcLayout`](../../mfc/reference/cpane-class.md#recalclayout).)| +|[`CMFCRibbonBar::RemoveAllCategories`](#removeallcategories)|Removes all the ribbon categories from the ribbon bar.| +|[`CMFCRibbonBar::RemoveAllFromTabs`](#removeallfromtabs)|Removes all ribbon elements from the tab area.| +|[`CMFCRibbonBar::RemoveCategory`](#removecategory)|Removes the ribbon category that is located at the specified index.| +|[`CMFCRibbonBar::SaveToXMLBuffer`](#savetoxmlbuffer)|Saves the Ribbon Bar to a buffer.| +|[`CMFCRibbonBar::SaveToXMLFile`](#savetoxmlfile)|Saves the Ribbon Bar to XML file.| +|[`CMFCRibbonBar::SetActiveCategory`](#setactivecategory)|Sets a specified ribbon category to active.| +|[`CMFCRibbonBar::SetActiveMDIChild`](#setactivemdichild)|| +|[`CMFCRibbonBar::SetElementKeys`](#setelementkeys)|Sets the specified keytips for all ribbon elements that have the specified command ID.| +|[`CMFCRibbonBar::SetApplicationButton`](#setapplicationbutton)|Assigns an application ribbon button to the ribbon bar.| +|[`CMFCRibbonBar::SetKeyboardNavigationLevel`](#setkeyboardnavigationlevel)|| +|[`CMFCRibbonBar::SetMaximizeMode`](#setmaximizemode)|| +|[`CMFCRibbonBar::SetQuickAccessCommands`](#setquickaccesscommands)|Adds one or more ribbon elements to the Quick Access Toolbar.| +|[`CMFCRibbonBar::SetQuickAccessDefaultState`](#setquickaccessdefaultstate)|Specifies the default state for the Quick Access Toolbar.| +|[`CMFCRibbonBar::SetQuickAccessToolbarOnTop`](#setquickaccesstoolbarontop)|Positions the Quick Access Toolbar (QAT) above or below the ribbon bar.| +|[`CMFCRibbonBar::SetTooltipFixedWidth`](#settooltipfixedwidth)|| +|[`CMFCRibbonBar::SetWindows7Look`](#setwindows7look)|Enable/disable ribbon Windows 7-style look (small rectangular application button)| +|[`CMFCRibbonBar::ShowCategory`](#showcategory)|Shows or hides the specified ribbon category.| +|[`CMFCRibbonBar::ShowContextCategories`](#showcontextcategories)|Shows or hides the context categories that have the specified ID.| +|[`CMFCRibbonBar::ShowKeyTips`](#showkeytips)|| +|[`CMFCRibbonBar::ToggleMimimizeState`](#togglemimimizestate)|Toggles the ribbon bar between the minimized and maximized states.| +|[`CMFCRibbonBar::TranslateChar`](#translatechar)|| ## Remarks -Microsoft introduced the Office Fluent Ribbon when it simultaneously released Microsoft Office 2007. This ribbon bar is not just a new control. It represents a new user-interface paradigm. The ribbon is a pane that contains a set of tabs called categories. Each category is logically split into ribbon panels and each panel can contain various controls and command buttons. +Microsoft introduced the Office Fluent Ribbon when it simultaneously released Microsoft Office 2007. This ribbon bar isn't just a new control. It represents a new user-interface paradigm. The ribbon is a pane that contains a set of tabs called categories. Each category is logically split into ribbon panels and each panel can contain various controls and command buttons. The elements that appear on the ribbon bar expand and contract to make the best use of available space. For example, if a ribbon panel has insufficient space to display its elements, it becomes a menu button that displays subitems on a pop-up menu. The ribbon bar behaves as a static (non-floating) control bar and can be docked at the top of a frame. -You can use the `CMFCRibbonStatusBar` class to implement a status bar similar to the one used in Office 2007. A ribbon category contains (and displays) a group of [ribbon panels](../../mfc/reference/cmfcribbonpanel-class.md). Each ribbon panel contains one or more ribbon elements, which are derived from [CMFCRibbonBaseElement](../../mfc/reference/cmfcribbonbaseelement-class.md). +You can use the `CMFCRibbonStatusBar` class to implement a status bar similar to the one used in Office 2007. A ribbon category contains (and displays) a group of [ribbon panels](../../mfc/reference/cmfcribbonpanel-class.md). Each ribbon panel contains one or more ribbon elements, which are derived from [`CMFCRibbonBaseElement`](../../mfc/reference/cmfcribbonbaseelement-class.md). For information about how to add a ribbon bar to your existing MFC application, see [Walkthrough: Updating the MFC Scribble Application](../../mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CBasePane](../../mfc/reference/cbasepane-class.md) +[`CBasePane`](../../mfc/reference/cbasepane-class.md) -[CPane](../../mfc/reference/cpane-class.md) +[`CPane`](../../mfc/reference/cpane-class.md) -[CMFCRibbonBar](../../mfc/reference/cmfcribbonbar-class.md) +[`CMFCRibbonBar`](../../mfc/reference/cmfcribbonbar-class.md) ## Requirements -**Header:** afxribbonbar.h +**Header:** `afxribbonbar.h` -## CMFCRibbonBar::ActivateContextCategory +## `CMFCRibbonBar::ActivateContextCategory` Activates a context category that is already visible. @@ -160,14 +159,14 @@ BOOL ActivateContextCategory(UINT uiContextID); ### Parameters -*uiContextID*
+*`uiContextID`*\ [in] The context category ID. ### Return Value -TRUE if a context category with *uiContextID* is found and activated; otherwise FALSE. +`TRUE` if a context category with *`uiContextID`* is found and activated; otherwise `FALSE`. -## CMFCRibbonBar::AddCategory +## `CMFCRibbonBar::AddCategory` Creates and initializes a new ribbon category for the ribbon bar. @@ -186,34 +185,34 @@ CMFCRibbonCategory* AddCategory( ### Parameters -*lpszName*
+*`lpszName`*\ [in] Name of the ribbon category. -*uiSmallImagesResID*
+*`uiSmallImagesResID`*\ [in] Resource ID of the small image list for the ribbon category. -*uiLargeImagesResID*
+*`uiLargeImagesResID`*\ [in] Resource ID of the large image list for the ribbon category. -*sizeSmallImage*
+*`sizeSmallImage`*\ [in] Specifies the size of small images for the ribbon category. -*sizeLargeImage*
+*`sizeLargeImage`*\ [in] Specifies the size of large images for the ribbon category. -*nInsertAt*
+*`nInsertAt`*\ [in] Zero based index of the category location. -*pRTI*
-[in] Pointer to a [CMFCRibbonCategory Class](../../mfc/reference/cmfcribboncategory-class.md) run-time class to dynamically create a ribbon category at run-time. +*`pRTI`*\ +[in] Pointer to a [`CMFCRibbonCategory` Class](../../mfc/reference/cmfcribboncategory-class.md) run-time class to dynamically create a ribbon category at run-time. ### Return Value -A pointer to the new ribbon category if the method was successful; otherwise, NULL. +A pointer to the new ribbon category if the method was successful; otherwise, `NULL`. ### Remarks -If the *pRTI* parameter is not NULL, the new ribbon category is created dynamically using the run-time class. +If the *`pRTI`* parameter isn't `NULL`, the new ribbon category is created dynamically using the run-time class. ### Example @@ -221,7 +220,7 @@ The following example demonstrates how to use the `AddCategory` method in the `C [!code-cpp[NVC_MFC_RibbonApp#5](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_1.cpp)] -## CMFCRibbonBar::AddContextCategory +## `CMFCRibbonBar::AddContextCategory` Creates and initializes a new context category for the ribbon bar. @@ -242,60 +241,60 @@ CMFCRibbonCategory* AddContextCategory( ### Parameters -*lpszName*
+*`lpszName`*\ [in] Name of the category. -*lpszContextName*
+*`lpszContextName`*\ [in] Name of the context category caption. -*uiContextID*
+*`uiContextID`*\ [in] Context ID. -*clrContext*
+*`clrContext`*\ [in] Color of the context category caption. -*uiSmallImagesResID*
+*`uiSmallImagesResID`*\ [in] Resource ID of the small image of a context category. -*uiLargeImagesResID*
+*`uiLargeImagesResID`*\ [in] Resource ID of the large image of a context category. -*sizeSmallImage*
+*`sizeSmallImage`*\ [in] Size of a small image. -*sizeLargeImage*
+*`sizeLargeImage`*\ [in] Size of a large image. -*pRTI*
+*`pRTI`*\ [in] Pointer to a runtime class. ### Return Value -A pointer to the newly created category, or NULL if the `CreateObject` method of *pRTI* cannot create the specified category. +A pointer to the newly created category, or `NULL` if the `CreateObject` method of *`pRTI`* can't create the specified category. ### Remarks -Use this function to add a context category. Context categories are a special type of category that can be shown or hidden at runtime, depending on the current application context. For example, when the user selects an object, you can display special tabs with context categories which you use to change the specific selected object. +Use this function to add a context category. Context categories are a special type of category that can be shown or hidden at runtime, depending on the current application context. For example, when the user selects an object, you can display special tabs with context categories, which you use to change the specific selected object. The color of a context category can be one of the following values: -- AFX_CategoryColor_None +- `AFX_CategoryColor_None` -- AFX_CategoryColor_Red +- `AFX_CategoryColor_Red` -- AFX_CategoryColor_Orange +- `AFX_CategoryColor_Orange` -- AFX_CategoryColor_Yellow +- `AFX_CategoryColor_Yellow` -- AFX_CategoryColor_Green +- `AFX_CategoryColor_Green` -- AFX_CategoryColor_Blue +- `AFX_CategoryColor_Blue` -- AFX_CategoryColor_Indigo +- `AFX_CategoryColor_Indigo` -- AFX_CategoryColor_Violet +- `AFX_CategoryColor_Violet` -## CMFCRibbonBar::AddMainCategory +## `CMFCRibbonBar::AddMainCategory` Creates a new main ribbon category for the ribbon bar. @@ -312,28 +311,28 @@ CMFCRibbonMainPanel* AddMainCategory( ### Parameters -*lpszName*
+*`lpszName`*\ [in] Name of the main ribbon category. -*uiSmallImagesResID*
+*`uiSmallImagesResID`*\ [in] Resource ID of small images. -*uiLargeImagesResID*
+*`uiLargeImagesResID`*\ [in] Resource ID of large images. -*sizeSmallImage*
+*`sizeSmallImage`*\ [in] The size of small images. -*sizeLargeImage*
+*`sizeLargeImage`*\ [in] The size of large images. ### Return Value -Pointer to the new main ribbon category if the method was successful; otherwise, NULL. +Pointer to the new main ribbon category if the method was successful; otherwise, `NULL`. ### Remarks -If a main ribbon category already exists, it is deleted. +If a main ribbon category already exists, it's deleted. ### Example @@ -341,7 +340,7 @@ The following example demonstrates how to use the `AddMainCategory` method in th [!code-cpp[NVC_MFC_RibbonApp#4](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_2.cpp)] -## CMFCRibbonBar::AddPrintPreviewCategory +## `CMFCRibbonBar::AddPrintPreviewCategory` Creates a print preview category on the ribbon bar. @@ -351,13 +350,13 @@ CMFCRibbonCategory* AddPrintPreviewCategory(); ### Return Value -A pointer to the new ribbon category if the method was successful; otherwise, NULL. +A pointer to the new ribbon category if the method was successful; otherwise, `NULL`. ### Remarks This method creates a ribbon category and the controls that it needs in order to provide a print preview. -## CMFCRibbonBar::AddQATOnlyCategory +## `CMFCRibbonBar::AddQATOnlyCategory` Creates a quick access toolbar ribbon category. @@ -371,24 +370,24 @@ CMFCRibbonCategory* AddQATOnlyCategory( ### Parameters -*lpszName*
+*`lpszName`*\ [in] Name of the category. -*uiSmallImagesResID*
+*`uiSmallImagesResID`*\ [in] Resource ID of the image list for the category. -*sizeSmallImage*
+*`sizeSmallImage`*\ [in] Size of images for ribbon elements in the category. ### Return Value -A pointer to the new category if the method was successful; otherwise, NULL. +A pointer to the new category if the method was successful; otherwise, `NULL`. ### Remarks The quick access toolbar ribbon category is only used on the quick access toolbar customization dialog box. -## CMFCRibbonBar::AddToTabs +## `CMFCRibbonBar::AddToTabs` Adds the specified ribbon element to the tabs row of the ribbon bar. @@ -398,16 +397,16 @@ void AddToTabs(CMFCRibbonBaseElement* pElement); ### Parameters -*pElement*
+*`pElement`*\ [in] Pointer to a ribbon element. ### Remarks The ribbon element is positioned before any system buttons. -## CMFCRibbonBar::CMFCRibbonBar +## `CMFCRibbonBar::CMFCRibbonBar` -Constructs and initializes a [CMFCRibbonBar](../../mfc/reference/cmfcribbonbar-class.md) object. +Constructs and initializes a [`CMFCRibbonBar`](../../mfc/reference/cmfcribbonbar-class.md) object. ``` CMFCRibbonBar(BOOL bReplaceFrameCaption = TRUE); @@ -415,12 +414,12 @@ CMFCRibbonBar(BOOL bReplaceFrameCaption = TRUE); ### Parameters -*bReplaceFrameCaption*
-[in] TRUE for the ribbon bar to replace the caption of the main frame window; FALSE to locate the ribbon bar under the caption of the main frame window. +*`bReplaceFrameCaption`*\ +[in] `TRUE` for the ribbon bar to replace the caption of the main frame window; `FALSE` to locate the ribbon bar under the caption of the main frame window. ### Remarks -## CMFCRibbonBar::Create +## `CMFCRibbonBar::Create` Creates a window for the ribbon bar. @@ -433,18 +432,18 @@ BOOL Create( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ [in] Pointer to the parent window for the ribbon bar. -*dwStyle*
+*`dwStyle`*\ [in] A logical combination of styles for the new window. -*nID*
+*`nID`*\ [in] ID of the new window. ### Return Value -TRUE if the window was created; otherwise FALSE. +`TRUE` if the window was created; otherwise `FALSE`. ### Remarks @@ -454,7 +453,7 @@ The following example demonstrates how to use the `Create` method of the `CMFCRi [!code-cpp[NVC_MFC_RibbonApp#1](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_3.cpp)] -## CMFCRibbonBar::CreateEx +## `CMFCRibbonBar::CreateEx` Creates a window for the ribbon bar. @@ -468,25 +467,25 @@ BOOL CreateEx( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ [in] Pointer to the parent window for the ribbon bar. -*dwCtrlStyle*
-[in] This parameter is not used. +*`dwCtrlStyle`*\ +[in] This parameter isn't used. -*dwStyle*
+*`dwStyle`*\ [in] A logical combination of styles for the new window. -*nID*
+*`nID`*\ [in] ID of the new window. ### Return Value -TRUE if the window was created; otherwise FALSE. +`TRUE` if the window was created; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::DeactivateKeyboardFocus +## `CMFCRibbonBar::DeactivateKeyboardFocus` Closes all keytip controls on the ribbon bar. @@ -496,12 +495,12 @@ void DeactivateKeyboardFocus(BOOL bSetFocus = TRUE); ### Parameters -*bSetFocus*
-[in] TRUE to set the focus to the parent window of the ribbon bar. +*`bSetFocus`*\ +[in] `TRUE` to set the focus to the parent window of the ribbon bar. ### Remarks -## CMFCRibbonBar::DrawMenuImage +## `CMFCRibbonBar::DrawMenuImage` Draws the image for a menu button. @@ -514,22 +513,22 @@ BOOL DrawMenuImage( ### Parameters -*pDC*
+*`pDC`*\ [in] Pointer to a device context for the menu button. -*pMenuItem*
+*`pMenuItem`*\ [in] Pointer to a toolbar menu button. -*rectImage*
+*`rectImage`*\ [in] The display rectangle for a menu button. ### Return Value -TRUE if the image was drawn; otherwise FALSE. +`TRUE` if the image was drawn; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::DWMCompositionChanged +## `CMFCRibbonBar::DWMCompositionChanged` Adjusts the display of the ribbon bar when Desktop Window Manager (DWM) composition is enabled or disabled. @@ -539,7 +538,7 @@ virtual void DWMCompositionChanged(); ### Remarks -## CMFCRibbonBar::EnableKeyTips +## `CMFCRibbonBar::EnableKeyTips` Enables or disables the keytip feature for the ribbon bar. @@ -549,14 +548,14 @@ void EnableKeyTips(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the keytips feature; FALSE to disable the keytips feature. +*`bEnable`*\ +[in] `TRUE` to enable the keytips feature; `FALSE` to disable the keytips feature. ### Remarks -When you enable this feature, key tips are displayed when the user presses the ALT or F10 button. When the user presses ALT key, key tips are displayed with a 200 millisecond delay. This delay allows for shortcuts to be executed so that the pressed ALT key does not interfere with other combinations that include the ALT key. +When you enable this feature, key tips are displayed when the user presses the **ALT** or **F10** keys. When the user presses **ALT** key, key tips are displayed with a 200 millisecond delay. This delay allows for shortcuts to be executed so that the pressed **ALT** key doesn't interfere with other combinations that include the **ALT** key. -## CMFCRibbonBar::EnablePrintPreview +## `CMFCRibbonBar::EnablePrintPreview` Enables or disables the **Print Preview** feature. @@ -566,16 +565,16 @@ void EnablePrintPreview(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable the **Print Preview** feature; FALSE to disable the **Print Preview** feature. +*`bEnable`*\ +[in] `TRUE` to enable the **Print Preview** feature; `FALSE` to disable the **Print Preview** feature. ### Remarks -If *bEnable* is FALSE and a print preview category exists, it is deleted. +If *`bEnable`* is `FALSE` and a print preview category exists, it's deleted. By default the **Print Preview** feature is enabled. -## CMFCRibbonBar::EnableToolTips +## `CMFCRibbonBar::EnableToolTips` Enables or disables tooltips and optional tooltip descriptions on the ribbon bar. @@ -587,17 +586,17 @@ void EnableToolTips( ### Parameters -*bEnable*
-[in] TRUE to enable tooltips on the ribbon bar; FALSE to disable tooltips on the ribbon bar. +*`bEnable`*\ +[in] `TRUE` to enable tooltips on the ribbon bar; `FALSE` to disable tooltips on the ribbon bar. -*bEnableDescr*
-[in] TRUE to enable tooltip descriptions on the tooltip; FALSE to disable tooltip descriptions on the tooltip. +*bEnableDescr*\ +[in] `TRUE` to enable tooltip descriptions on the tooltip; `FALSE` to disable tooltip descriptions on the tooltip. ### Remarks -The *bEnable* parameter determines whether tooltips are displayed when the mouse hovers over a ribbon element. The *bEnableDescr* parameter determines whether additional descriptive text appears with the tooltip text. +The *`bEnable`* parameter determines whether tooltips are displayed when the mouse hovers over a ribbon element. The *`bEnableDescr`* parameter determines whether additional descriptive text appears with the tooltip text. -## CMFCRibbonBar::FindByData +## `CMFCRibbonBar::FindByData` Retrieves a pointer to a ribbon element if it has the specified data and visibility. @@ -609,21 +608,21 @@ CMFCRibbonBaseElement* FindByData( ### Parameters -*dwData*
+*`dwData`*\ [in] The data associated with a ribbon element. -*bVisibleOnly*
-[in] TRUE to search visible ribbon elements only; FALSE to search all ribbon elements. +*`bVisibleOnly`*\ +[in] `TRUE` to search visible ribbon elements only; `FALSE` to search all ribbon elements. ### Return Value -A pointer to a ribbon element if it has the specified data and visibility; otherwise NULL. +A pointer to a ribbon element if it has the specified data and visibility; otherwise `NULL`. ### Remarks A ribbon element is any control that you can add to the ribbon, such as a ribbon button, or a ribbon category, or a ribbon slider. -## CMFCRibbonBar::FindByID +## `CMFCRibbonBar::FindByID` Retrieves a pointer to the ribbon element that has the specified command ID and search values. @@ -636,26 +635,26 @@ CMFCRibbonBaseElement* FindByID( ### Parameters -*uiCmdID*
+*`uiCmdID`*\ [in] Command ID for a ribbon element. -*bVisibleOnly*
-[in] TRUE to search visible ribbon elements only; FALSE to search all ribbon elements. +*`bVisibleOnly`*\ +[in] `TRUE` to search visible ribbon elements only; `FALSE` to search all ribbon elements. -*bExcludeQAT*
-[in] TRUE to exclude quick access toolbar elements from the search; otherwise, FALSE. +*`bExcludeQAT`*\ +[in] `TRUE` to exclude quick access toolbar elements from the search; otherwise, `FALSE`. ### Return Value -A pointer to a ribbon element if it has the specified command ID and search values; otherwise, NULL. +A pointer to a ribbon element if it has the specified command ID and search values; otherwise, `NULL`. ### Remarks A ribbon element is any ribbon control that can be added to the ribbon, such as a ribbon button, or a ribbon category, or a ribbon slider. -In general, there can be more than one ribbon element that has the same command ID. If you want to obtain pointers to all ribbon elements that use a specified command ID, use the [CMFCRibbonBar::GetElementsByID](#getelementsbyid) method. +In general, there can be more than one ribbon element that has the same command ID. If you want to obtain pointers to all ribbon elements that use a specified command ID, use the [`CMFCRibbonBar::GetElementsByID`](#getelementsbyid) method. -## CMFCRibbonBar::FindCategoryIndexByData +## `CMFCRibbonBar::FindCategoryIndexByData` Retrieves the index of the ribbon category that contains the specified data. @@ -665,14 +664,14 @@ int FindCategoryIndexByData(DWORD dwData) const; ### Parameters -*dwData*
+*`dwData`*\ [in] The data associated with a ribbon category. ### Return Value The zero-based index of a ribbon category if the method was successful; otherwise -1. -## CMFCRibbonBar::ForceRecalcLayout +## `CMFCRibbonBar::ForceRecalcLayout` Adjusts the layout of all items in the ribbon bar and parent window and redraws the whole window. @@ -682,7 +681,7 @@ void ForceRecalcLayout(); ### Remarks -## CMFCRibbonBar::GetActiveCategory +## `CMFCRibbonBar::GetActiveCategory` Retrieves a pointer to the active ribbon category. @@ -692,15 +691,15 @@ CMFCRibbonCategory* GetActiveCategory() const; ### Return Value -A pointer to the active ribbon category; or NULL if no category is active. +A pointer to the active ribbon category; or `NULL` if no category is active. ### Remarks A category is active if it has the focus. By default, the active category is the first category on the left side of the ribbon bar. -The main category is displayed when the user presses the application button and it cannot be the active category. +The main category is displayed when the user presses the application button and it can't be the active category. -## CMFCRibbonBar::GetApplicationButton +## `CMFCRibbonBar::GetApplicationButton` Retrieves a pointer to the application button. @@ -710,9 +709,9 @@ CMFCRibbonApplicationButton* GetApplicationButton() const; ### Return Value -A pointer to the application button; or NULL if the button has not been set. +A pointer to the application button; or `NULL` if the button hasn't been set. -## CMFCRibbonBar::GetCaptionHeight +## `CMFCRibbonBar::GetCaptionHeight` Retrieves the height of the caption area for the ribbon bar. @@ -726,7 +725,7 @@ The height, in pixels, of the caption area for the ribbon bar. ### Remarks -## CMFCRibbonBar::GetCategory +## `CMFCRibbonBar::GetCategory` Retrieves a pointer to the ribbon category at the specified index. @@ -736,14 +735,14 @@ CMFCRibbonCategory* GetCategory(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of a ribbon category in the list of ribbon categories that is contained in the ribbon bar. ### Return Value -A pointer to the ribbon category at the specified index; otherwise, NULL if *nIndex* was out of range. +A pointer to the ribbon category at the specified index; otherwise, `NULL` if *`nIndex`* was out of range. -## CMFCRibbonBar::GetCategoryCount +## `CMFCRibbonBar::GetCategoryCount` Retrieves the number of ribbon categories in the ribbon bar. @@ -755,7 +754,7 @@ int GetCategoryCount() const; The number of the ribbon categories in the ribbon bar. -## CMFCRibbonBar::GetCategoryHeight +## `CMFCRibbonBar::GetCategoryHeight` Retrieves the height of the category. @@ -771,7 +770,7 @@ The height of the category. The category height includes the height of the category tab. -## CMFCRibbonBar::GetCategoryIndex +## `CMFCRibbonBar::GetCategoryIndex` Retrieves the index of the specified ribbon category. @@ -781,14 +780,14 @@ int GetCategoryIndex(CMFCRibbonCategory* pCategory) const; ### Parameters -*pCategory*
+*`pCategory`*\ [in] Pointer to a ribbon category. ### Return Value -The zero-based index of a ribbon category specified by *pCategory*; or -1 if the ribbon category is not found. +The zero-based index of a ribbon category specified by *`pCategory`*; or -1 if the ribbon category isn't found. -## CMFCRibbonBar::GetContextName +## `CMFCRibbonBar::GetContextName` Retrieves the name of the context category caption specified by a context ID. @@ -800,17 +799,17 @@ BOOL GetContextName( ### Parameters -*uiContextID*
+*`uiContextID`*\ [in] A ribbon category context ID. -*strName*
+*`strName`*\ [out] The name of a context category caption. ### Return Value -TRUE if the method was successful; otherwise, FALSE if *uiContextID* was zero or the context category caption was not found. +`TRUE` if the method was successful; otherwise, `FALSE` if *`uiContextID`* was zero or the context category caption wasn't found. -## CMFCRibbonBar::GetDroppedDown +## `CMFCRibbonBar::GetDroppedDown` Retrieves the ribbon element that is currently dropped down. @@ -820,11 +819,11 @@ virtual CMFCRibbonBaseElement* GetDroppedDown(); ### Return Value -The ribbon element that is currently dropped down; or NULL if no ribbon element is currently dropped down. +The ribbon element that is currently dropped down; or `NULL` if no ribbon element is currently dropped down. ### Remarks -## CMFCRibbonBar::GetElementsByID +## `CMFCRibbonBar::GetElementsByID` Retrieves an array of pointers to all ribbon elements that have a specific command ID. @@ -836,17 +835,17 @@ void GetElementsByID( ### Parameters -*uiCmdID*
+*`uiCmdID`*\ [in] Command ID of a ribbon element. -*arButtons*
+*`arButtons`*\ [out] An array of pointers to ribbon elements. ### Remarks Multiple ribbon elements can have the same command ID because some ribbon elements can be copied to the quick access toolbar. -## CMFCRibbonBar::GetHideFlags +## `CMFCRibbonBar::GetHideFlags` Retrieves the flags that indicate how much of the ribbon bar is visible. @@ -864,10 +863,10 @@ The following table lists the possible combination of flags for the return value |Flag|Description| |-|-| -|AFX_RIBBONBAR_HIDE_ELEMENTS|The ribbon bar is minimized vertically and only the category tabs, main button, and quick access toolbar are visible. | -|AFX_RIBBONBAR_HIDE_ALL|The width of the ribbon bar is less than the minimum width and is completely hidden. | +|`AFX_RIBBONBAR_HIDE_ELEMENTS`|The ribbon bar is minimized vertically and only the category tabs, main button, and quick access toolbar are visible. | +|`AFX_RIBBONBAR_HIDE_ALL`|The width of the ribbon bar is less than the minimum width and is completely hidden. | -## CMFCRibbonBar::GetItemIDsList +## `CMFCRibbonBar::GetItemIDsList` Retrieves the command IDs for the specified collection of ribbon elements on the ribbon bar. @@ -878,15 +877,15 @@ void GetItemIDsList(CList& lstItems, ### Parameters -*lstItems*
+*`lstItems`*\ [out] The list of command IDs for ribbon elements that are contained in the ribbon bar. -*bHiddenOnly*
-[in] TRUE to exclude ribbon elements that are displayed; FALSE to include all ribbon elements in the ribbon bar. +*`bHiddenOnly`*\ +[in] `TRUE` to exclude ribbon elements that are displayed; `FALSE` to include all ribbon elements in the ribbon bar. ### Remarks -## CMFCRibbonBar::GetKeyboardNavigationLevel +## `CMFCRibbonBar::GetKeyboardNavigationLevel` Retrieves the current navigation level as the user presses the keytips that are contained on the ribbon bar. @@ -900,13 +899,13 @@ The current navigation level as the user presses the keytips that are contained |Value|Description| |-|-| -|-1|Keytips are not displayed.| +|-1|Keytips aren't displayed.| |0|Keytips are displayed.| |1|User has pressed a displayed keytip.| ### Remarks -## CMFCRibbonBar::GetKeyboardNavLevelCurrent +## `CMFCRibbonBar::GetKeyboardNavLevelCurrent` Retrieves the current keyboard navigation object on the ribbon bar. @@ -916,13 +915,13 @@ CObject* GetKeyboardNavLevelCurrent() const; ### Return Value -The current keyboard navigation object on the ribbon bar; otherwise NULL if no object currently displays keytips. +The current keyboard navigation object on the ribbon bar; otherwise `NULL` if no object currently displays keytips. ### Remarks The object that is currently displaying keytips is the current keyboard navigation object. -## CMFCRibbonBar::GetKeyboardNavLevelParent +## `CMFCRibbonBar::GetKeyboardNavLevelParent` Retrieves the parent keyboard navigation object on the ribbon bar. @@ -932,13 +931,13 @@ CObject* GetKeyboardNavLevelParent() const; ### Return Value -The parent keyboard navigation object on the ribbon bar; otherwise NULL. +The parent keyboard navigation object on the ribbon bar; otherwise `NULL`. ### Remarks When the user presses a keytip on the ribbon bar, the current keyboard navigation object becomes the parent keyboard navigation object. -## CMFCRibbonBar::GetMainCategory +## `CMFCRibbonBar::GetMainCategory` Retrieves a pointer to the main ribbon category. @@ -954,7 +953,7 @@ A pointer to the main ribbon category. The main ribbon category contains the main ribbon panel. -## CMFCRibbonBar::GetQATCommandsLocation +## `CMFCRibbonBar::GetQATCommandsLocation` Retrieves the display rectangle for the commands section of the quick access toolbar. @@ -968,9 +967,9 @@ The display rectangle for the commands section of the quick access toolbar. ### Remarks -The commands section of the display rectangle does not include the customization button. +The commands section of the display rectangle doesn't include the customization button. -## CMFCRibbonBar::GetQATDroppedDown +## `CMFCRibbonBar::GetQATDroppedDown` Retrieves a pointer to the ribbon element on the quick access toolbar that has its pop-up menu dropped down. @@ -984,7 +983,7 @@ A pointer to the ribbon element on the quick access toolbar that has its pop-up ### Remarks -## CMFCRibbonBar::GetQuickAccessCommands +## `CMFCRibbonBar::GetQuickAccessCommands` Retrieves a list of command IDs for the ribbon elements on the quick access toolbar. @@ -994,14 +993,14 @@ void GetQuickAccessCommands(CList& lstCommands); ### Parameters -*lstCommands*
+*`lstCommands`*\ [out] The list of command IDs for the ribbon elements on the quick access toolbar. ### Remarks -The list does not contain ribbon elements that are control separators. +The list doesn't contain ribbon elements that are control separators. -## CMFCRibbonBar::GetQuickAccessToolbarLocation +## `CMFCRibbonBar::GetQuickAccessToolbarLocation` Retrieves the display rectangle for the quick access toolbar. @@ -1015,7 +1014,7 @@ The display rectangle for the quick access toolbar. ### Remarks -## CMFCRibbonBar::GetTabTrancateRatio +## `CMFCRibbonBar::GetTabTrancateRatio` Retrieves the percent size reduction in the display width of the category tabs. @@ -1029,9 +1028,9 @@ The percent size reduction in the display width of the category tabs. ### Remarks -Category tabs are reduced in width when there is not enough width on the ribbon bar. +Category tabs are reduced in width when there isn't enough width on the ribbon bar. -## CMFCRibbonBar::GetTooltipFixedWidthLargeImage +## `CMFCRibbonBar::GetTooltipFixedWidthLargeImage` Retrieves the large size of tooltip width for the ribbon bar. @@ -1047,7 +1046,7 @@ The large size of tooltip width in pixels. If the large size of tooltip width is 0, the width varies. -## CMFCRibbonBar::GetTooltipFixedWidthRegular +## `CMFCRibbonBar::GetTooltipFixedWidthRegular` Retrieves the regular size of tooltip width for the ribbon bar. @@ -1063,7 +1062,7 @@ The regular size of tooltip width in pixels. If the regular size of tooltip width is 0, the width varies. -## CMFCRibbonBar::GetVisibleCategoryCount +## `CMFCRibbonBar::GetVisibleCategoryCount` Retrieves the number of visible categories on the ribbon bar. @@ -1077,7 +1076,7 @@ The number of visible categories on the ribbon bar. ### Remarks -## CMFCRibbonBar::HideAllContextCategories +## `CMFCRibbonBar::HideAllContextCategories` Hides all the context categories on the ribbon bar. @@ -1087,13 +1086,13 @@ BOOL HideAllContextCategories(); ### Return Value -TRUE if at least one context category was hidden; otherwise, FALSE. +`TRUE` if at least one context category was hidden; otherwise, `FALSE`. ### Remarks If a context category is active, the active category is reset to the first visible category in the category list. -## CMFCRibbonBar::HideKeyTips +## `CMFCRibbonBar::HideKeyTips` Hides all keytips on the ribbon bar. @@ -1103,7 +1102,7 @@ void HideKeyTips(); ### Remarks -## CMFCRibbonBar::HitTest +## `CMFCRibbonBar::HitTest` Retrieves a pointer to the ribbon element specified by the location of the point. @@ -1116,24 +1115,24 @@ virtual CMFCRibbonBaseElement* HitTest( ### Parameters -*point*
+*`point`*\ [in] Location of the point in ribbon bar coordinates. -*bCheckActiveCategory*
-[in] TRUE to search the active category; FALSE not to search the active category. +*`bCheckActiveCategory`*\ +[in] `TRUE` to search the active category; `FALSE` not to search the active category. -*bCheckPanelCaption*
-[in] TRUE to test the caption of the ribbon panel with the point located in it; FALSE not to test the caption of the ribbon panel with the point located in it. See the Remarks section for more information. +*`bCheckPanelCaption`*\ +[in] `TRUE` to test the caption of the ribbon panel with the point located in it; `FALSE` not to test the caption of the ribbon panel with the point located in it. See the [Remarks](#hittest-remarks) section for more information. ### Return Value -A pointer to the ribbon element located at the specified point; otherwise NULL if the point is not located in a ribbon element. +A pointer to the ribbon element located at the specified point; otherwise `NULL` if the point isn't located in a ribbon element. -### Remarks +### Remarks -The caption of the ribbon panel with the point located in it is not tested unless the *bCheckActiveCategory* parameter is TRUE. +The caption of the ribbon panel with the point located in it isn't tested unless the *`bCheckActiveCategory`* parameter is `TRUE`. -## CMFCRibbonBar::IsKeyTipEnabled +## `CMFCRibbonBar::IsKeyTipEnabled` Indicates whether the keytips feature is enabled. @@ -1143,9 +1142,9 @@ BOOL IsKeyTipEnabled() const; ### Return Value -TRUE if the keytips feature is enabled; otherwise FALSE. +`TRUE` if the keytips feature is enabled; otherwise `FALSE`. -## CMFCRibbonBar::IsMainRibbonBar +## `CMFCRibbonBar::IsMainRibbonBar` Indicates whether the ribbon bar is the primary ribbon bar. @@ -1155,13 +1154,13 @@ virtual BOOL IsMainRibbonBar() const; ### Return Value -Always returns TRUE. +Always returns `TRUE`. ### Remarks -By default this method always returns TRUE. Override this method to indicate whether the ribbon bar is the primary ribbon bar. +By default this method always returns `TRUE`. Override this method to indicate whether the ribbon bar is the primary ribbon bar. -## CMFCRibbonBar::IsPrintPreviewEnabled +## `CMFCRibbonBar::IsPrintPreviewEnabled` Indicates whether the **Print Preview** feature is enabled. @@ -1171,9 +1170,9 @@ BOOL IsPrintPreviewEnabled() const; ### Return Value -TRUE if the **Print Preview** feature is enabled; otherwise FALSE. +`TRUE` if the **Print Preview** feature is enabled; otherwise `FALSE`. -## CMFCRibbonBar::IsQATEmpty +## `CMFCRibbonBar::IsQATEmpty` Indicates whether the quick access toolbar contains command buttons. @@ -1183,11 +1182,11 @@ BOOL IsQATEmpty() const; ### Return Value -TRUE if the quick access toolbar contains command buttons; otherwise FALSE. +`TRUE` if the quick access toolbar contains command buttons; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::IsQuickAccessToolbarOnTop +## `CMFCRibbonBar::IsQuickAccessToolbarOnTop` Indicates whether the quick access toolbar is located over or under the ribbon bar. @@ -1197,9 +1196,9 @@ BOOL IsQuickAccessToolbarOnTop() const; ### Return Value -TRUE if the quick access toolbar is located over the ribbon bar; FALSE if the quick access toolbar is located under the ribbon bar. +`TRUE` if the quick access toolbar is located over the ribbon bar; `FALSE` if the quick access toolbar is located under the ribbon bar. -## CMFCRibbonBar::IsReplaceFrameCaption +## `CMFCRibbonBar::IsReplaceFrameCaption` Indicates whether the ribbon bar replaces or is under the caption of the main frame window. @@ -1209,9 +1208,9 @@ BOOL IsReplaceFrameCaption() const; ### Return Value -TRUE if the ribbon bar replaces the caption of the main frame window; FALSE if ribbon bar is under the caption of the main frame window. +`TRUE` if the ribbon bar replaces the caption of the main frame window; `FALSE` if ribbon bar is under the caption of the main frame window. -## CMFCRibbonBar::IsShowGroupBorder +## `CMFCRibbonBar::IsShowGroupBorder` Indicates whether button groups located on the ribbon bar display a group border. @@ -1221,18 +1220,18 @@ virtual BOOL IsShowGroupBorder(CMFCRibbonButtonsGroup* pGroup) const; ### Parameters -*pGroup*
-[in] This parameter is not used. +*`pGroup`*\ +[in] This parameter isn't used. ### Return Value -Always returns FALSE. +Always returns `FALSE`. ### Remarks -By default this method always returns FALSE. Override this method to indicate whether button groups located on the ribbon bar display a group border. +By default this method always returns `FALSE`. Override this method to indicate whether button groups located on the ribbon bar display a group border. -## CMFCRibbonBar::IsToolTipDescrEnabled +## `CMFCRibbonBar::IsToolTipDescrEnabled` Indicates whether tooltip descriptions are enabled. @@ -1242,13 +1241,13 @@ BOOL IsToolTipDescrEnabled() const; ### Return Value -TRUE if tooltip descriptions are enabled; FALSE if tooltip descriptions are disabled. +`TRUE` if tooltip descriptions are enabled; `FALSE` if tooltip descriptions are disabled. ### Remarks Tooltip descriptions are additional descriptive text displayed with the tooltip text. -## CMFCRibbonBar::IsToolTipEnabled +## `CMFCRibbonBar::IsToolTipEnabled` Indicates whether tooltips are enabled or disabled for the ribbon bar. @@ -1258,9 +1257,9 @@ BOOL IsToolTipEnabled() const; ### Return Value -TRUE if tooltips are enabled; FALSE if tooltips are disabled. +`TRUE` if tooltips are enabled; `FALSE` if tooltips are disabled. -## CMFCRibbonBar::IsTransparentCaption +## `CMFCRibbonBar::IsTransparentCaption` Indicates whether the display is set for Windows Aero color scheme. @@ -1270,13 +1269,13 @@ BOOL IsTransparentCaption() const; ### Return Value -TRUE if the color scheme is Windows Aero; otherwise FALSE. +`TRUE` if the color scheme is Windows Aero; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::OnClickButton +## `CMFCRibbonBar::OnClickButton` -This method is retained for backward compatibility with existing applications and should not be used for new development. +This method is retained for backward compatibility with existing applications and shouldn't be used for new development. ``` virtual void OnClickButton( @@ -1286,15 +1285,15 @@ virtual void OnClickButton( ### Parameters -*pButton*
+*`pButton`*\ [in] Pointer to the button that was clicked. -*point*
-[in] This parameter is not used. +*`point`*\ +[in] This parameter isn't used. ### Remarks -## CMFCRibbonBar::OnEditContextMenu +## `CMFCRibbonBar::OnEditContextMenu` ``` virtual void OnEditContextMenu( @@ -1304,12 +1303,12 @@ virtual void OnEditContextMenu( ### Parameters -[in] *pEdit*
-[in] *point*
+[in] *`pEdit`*\ +[in] *`point`* ### Remarks -## CMFCRibbonBar::OnRTLChanged +## `CMFCRibbonBar::OnRTLChanged` Called by the framework when the layout changes direction. @@ -1319,16 +1318,16 @@ virtual void OnRTLChanged(BOOL bIsRTL); ### Parameters -*bIsRTL*
-[in] TRUE if the layout is right-to-left; FALSE if the layout is left-to-right. +*`bIsRTL`*\ +[in] `TRUE` if the layout is right-to-left; `FALSE` if the layout is left-to-right. ### Remarks This method adjusts the layout of all controls on the ribbon bar for the new layout direction. -## CMFCRibbonBar::OnSetAccData +## `CMFCRibbonBar::OnSetAccData` -This method is internal to the Framework and is not intended to be called from user code. +This method is internal to the Framework and isn't intended to be called from user code. ``` BOOL OnSetAccData(long lVal); @@ -1336,16 +1335,16 @@ BOOL OnSetAccData(long lVal); ### Parameters -long *lVal* +long *`lVal`* The index of the accessible object. ### Return Value -S_OK if successful; otherwise FALSE or S_FALSE. +`S_OK` if successful; otherwise `FALSE` or `S_FALSE`. ### Remarks -## CMFCRibbonBar::OnShowRibbonContextMenu +## `CMFCRibbonBar::OnShowRibbonContextMenu` ``` virtual BOOL OnShowRibbonContextMenu( @@ -1357,16 +1356,16 @@ virtual BOOL OnShowRibbonContextMenu( ### Parameters -[in] *pWnd*
-[in] *x*
-[in] *y*
-[in] *pHit*
+[in] *`pWnd`*\ +[in] *`x`*\ +[in] *`y`*\ +[in] *`pHit`* ### Return Value ### Remarks -## CMFCRibbonBar::OnShowRibbonQATMenu +## `CMFCRibbonBar::OnShowRibbonQATMenu` ``` virtual BOOL OnShowRibbonQATMenu( @@ -1378,18 +1377,18 @@ virtual BOOL OnShowRibbonQATMenu( ### Parameters -[in] *pWnd*
-[in] *x*
-[in] *y*
-[in] *pHit*
+[in] *`pWnd`*\ +[in] *`x`*\ +[in] *`y`*\ +[in] *`pHit`* ### Return Value ### Remarks -## CMFCRibbonBar::OnSysKeyDown +## `CMFCRibbonBar::OnSysKeyDown` -Called by the framework when the user presses the F10 key or holds down the ALT key and then presses another key. +Called by the framework when the user presses the **F10** key or holds down the **ALT** key and then presses another key. ``` BOOL OnSysKeyDown( @@ -1400,24 +1399,24 @@ BOOL OnSysKeyDown( ### Parameters -*pFrameWnd*
+*`pFrameWnd`*\ [in] Pointer to the parent main frame window of the ribbon bar. -*wParam*
+*`wParam`*\ [in] Virtual key code of the key being pressed. -*lParam*
+*`lParam`*\ [in] Keyboard state flags when the key was pressed. ### Return Value -TRUE if the keystroke event was processed; otherwise FALSE. +`TRUE` if the keystroke event was processed; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::OnSysKeyUp +## `CMFCRibbonBar::OnSysKeyUp` -Called by the framework when the user releases the F10 key, the ALT key, or a key that was pressed when the ALT key was held down. +Called by the framework when the user releases the **F10** key, the **ALT** key, or a key that was pressed when the **ALT** key was held down. ``` BOOL OnSysKeyUp( @@ -1428,22 +1427,22 @@ BOOL OnSysKeyUp( ### Parameters -*pFrameWnd*
+*`pFrameWnd`*\ [in] Pointer to the parent main frame window of the ribbon bar. -*wParam*
+*`wParam`*\ [in] Virtual key code of the key being released. -*lParam*
-[in] This parameter is not used. +*`lParam`*\ +[in] This parameter isn't used. ### Return Value -TRUE if the keystroke event was processed; otherwise FALSE. +`TRUE` if the keystroke event was processed; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::PopTooltip +## `CMFCRibbonBar::PopTooltip` Removes a tooltip from view. @@ -1453,7 +1452,7 @@ void PopTooltip(); ### Remarks -## CMFCRibbonBar::PreTranslateMessage +## `CMFCRibbonBar::PreTranslateMessage` Determines if the specified message is processed by the ribbon bar. @@ -1463,16 +1462,16 @@ virtual BOOL PreTranslateMessage(MSG* pMsg); ### Parameters -*pMsg*
+*`pMsg`*\ [in] Pointer to a message. ### Return Value -TRUE if the message was processed by the ribbon bar; otherwise FALSE. +`TRUE` if the message was processed by the ribbon bar; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::RecalcLayout +## `CMFCRibbonBar::RecalcLayout` Adjusts the layout of all controls on the ribbon bar. @@ -1484,7 +1483,7 @@ virtual void RecalcLayout(); After layout adjustment, the display of the ribbon bar is updated. -## CMFCRibbonBar::RemoveAllCategories +## `CMFCRibbonBar::RemoveAllCategories` Deletes all ribbon categories from the ribbon bar. @@ -1496,7 +1495,7 @@ void RemoveAllCategories(); This method deletes all ribbon categories from memory and from the category list. -## CMFCRibbonBar::RemoveAllFromTabs +## `CMFCRibbonBar::RemoveAllFromTabs` Removes all ribbon elements from the tab area. @@ -1506,9 +1505,9 @@ void RemoveAllFromTabs(); ### Remarks -Use this function if you want to remove all the elements that you added to the tab area by using [CMFCRibbonBar::AddToTabs](#addtotabs) method. +Use this function if you want to remove all the elements that you added to the tab area by using [`CMFCRibbonBar::AddToTabs`](#addtotabs) method. -## CMFCRibbonBar::RemoveCategory +## `CMFCRibbonBar::RemoveCategory` Deletes the specified ribbon category from the ribbon bar. @@ -1518,18 +1517,18 @@ BOOL RemoveCategory(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of a category in the list of ribbon categories that is contained in the ribbon bar. ### Return Value -TRUE if the specified ribbon category was deleted; otherwise FALSE. +`TRUE` if the specified ribbon category was deleted; otherwise `FALSE`. ### Remarks The specified ribbon category is deleted from memory and from the category list. -## CMFCRibbonBar::SetActiveCategory +## `CMFCRibbonBar::SetActiveCategory` Sets the specified ribbon category as the active category. @@ -1541,23 +1540,23 @@ BOOL SetActiveCategory( ### Parameters -*pCategory*
+*`pCategory`*\ [in] A ribbon category that is contained in the ribbon bar. -*bForceRestore*
-[in] TRUE to maximize the ribbon bar if it is minimized; FALSE to display the active category in a pop-up window if the ribbon bar is minimized. +*`bForceRestore`*\ +[in] `TRUE` to maximize the ribbon bar if it's minimized; `FALSE` to display the active category in a pop-up window if the ribbon bar is minimized. ### Return Value -TRUE if the specified category was set as the active category; otherwise FALSE. +`TRUE` if the specified category was set as the active category; otherwise `FALSE`. ### Remarks -The main ribbon category cannot be the active category. +The main ribbon category can't be the active category. -If the category specified by *pCategory* is not displayed, it cannot be set as the active category. +If the category specified by *`pCategory`* isn't displayed, it can't be set as the active category. -## CMFCRibbonBar::SetActiveMDIChild +## `CMFCRibbonBar::SetActiveMDIChild` Associates the system buttons on the ribbon bar that belong to a multiple-document interface (MDI) child window to the specified MDI child window. @@ -1567,12 +1566,12 @@ void SetActiveMDIChild(CWnd* pWnd); ### Parameters -*pWnd*
+*`pWnd`*\ [in] Pointer to an MDI child window. ### Remarks -## CMFCRibbonBar::SetApplicationButton +## `CMFCRibbonBar::SetApplicationButton` Assigns an application ribbon button to the ribbon bar. @@ -1584,10 +1583,10 @@ void SetApplicationButton( ### Parameters -*pButton*
+*`pButton`*\ [in] A pointer to the application ribbon button. -*sizeButton*
+*`sizeButton`*\ [in] The size of the application ribbon button. ### Remarks @@ -1600,7 +1599,7 @@ The following example demonstrates how to use the `SetApplicationButton` method [!code-cpp[NVC_MFC_RibbonApp#3](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_4.cpp)] -## CMFCRibbonBar::SetElementKeys +## `CMFCRibbonBar::SetElementKeys` Sets the keytips for all ribbon elements that have the specified command ID. @@ -1613,24 +1612,24 @@ BOOL SetElementKeys( ### Parameters -*uiCmdID*
+*`uiCmdID`*\ [in] The command ID of a ribbon element. -*lpszKeys*
+*`lpszKeys`*\ [in] The keytip. -*lpszMenuKeys*
+*`lpszMenuKeys`*\ [in] The menu keytip. ### Return Value -TRUE if the keytips of at least one ribbon element are set; otherwise FALSE. +`TRUE` if the keytips of at least one ribbon element are set; otherwise `FALSE`. ### Remarks The optional menu keytip is for ribbon elements with a split button that opens a popup menu. -## CMFCRibbonBar::SetKeyboardNavigationLevel +## `CMFCRibbonBar::SetKeyboardNavigationLevel` Sets the keyboard navigation level as the user presses the keytips that are contained on the ribbon bar. @@ -1642,17 +1641,17 @@ void SetKeyboardNavigationLevel( ### Parameters -*pLevel*
+*`pLevel`*\ [in] Pointer to the current keyboard navigation object. -*bSetFocus*
-[in] TRUE to set the keyboard focus to the ribbon bar. +*`bSetFocus`*\ +[in] `TRUE` to set the keyboard focus to the ribbon bar. ### Remarks -Keyboard navigation of the ribbon bar starts when the user presses the ALT or F10 key. The user selects the next navigation level by pressing a keytip on the ribbon bar. The user can return to the previous navigation level by pressing the escape key. +Keyboard navigation of the ribbon bar starts when the user presses the **ALT** or **F10** key. The user selects the next navigation level by pressing a keytip on the ribbon bar. The user can return to the previous navigation level by pressing the escape key. -## CMFCRibbonBar::SetMaximizeMode +## `CMFCRibbonBar::SetMaximizeMode` Adjusts the ribbon bar when the window size of a multiple-document interface (MDI) child window enters or leaves the maximized state. @@ -1664,17 +1663,17 @@ void SetMaximizeMode( ### Parameters -*bMax*
-[in] TRUE to display the system buttons for an MDI child window on the ribbon bar; FALSE to remove the system buttons for an MDI child window from the ribbon bar. +*`bMax`*\ +[in] `TRUE` to display the system buttons for an MDI child window on the ribbon bar; `FALSE` to remove the system buttons for an MDI child window from the ribbon bar. -*pWnd*
+*`pWnd`*\ [in] Pointer to the main frame window for the ribbon bar. ### Remarks The ribbon bar displays system buttons for an MDI child window in the tab row when an MDI child window is maximized. -## CMFCRibbonBar::SetQuickAccessCommands +## `CMFCRibbonBar::SetQuickAccessCommands` Adds one or more ribbon elements to the Quick Access Toolbar. @@ -1686,11 +1685,11 @@ void SetQuickAccessCommands( ### Parameters -*lstCommands*
+*`lstCommands`*\ [in] The list of commands to be placed on the Quick Access Toolbar. -*bRecalcLayout*
-[in] TRUE if want to redraw the ribbon after you add the ribbon elements; FALSE otherwise. +*`bRecalcLayout`*\ +[in] `TRUE` if want to redraw the ribbon after you add the ribbon elements; `FALSE` otherwise. ### Example @@ -1698,7 +1697,7 @@ The following example demonstrates how to use the `SetQuickAccessCommands` metho [!code-cpp[NVC_MFC_RibbonApp#8](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_5.cpp)] -## CMFCRibbonBar::SetQuickAccessDefaultState +## `CMFCRibbonBar::SetQuickAccessDefaultState` Sets the quick access toolbar to the default state. @@ -1708,7 +1707,7 @@ void SetQuickAccessDefaultState(const CMFCRibbonQuickAccessToolBarDefaultState& ### Parameters -*state*
+*`state`*\ [in] The quick access toolbar default state. ### Remarks @@ -1721,7 +1720,7 @@ The following example demonstrates how to use the `SetQuickAccessDefaultState` m [!code-cpp[NVC_MFC_RibbonApp#9](../../mfc/reference/codesnippet/cpp/cmfcribbonbar-class_6.cpp)] -## CMFCRibbonBar::SetQuickAccessToolbarOnTop +## `CMFCRibbonBar::SetQuickAccessToolbarOnTop` Positions the quick access toolbar above or below the ribbon bar. @@ -1731,10 +1730,10 @@ void SetQuickAccessToolbarOnTop(BOOL bOnTop); ### Parameters -*bOnTop*
-[in] TRUE to position the quick access toolbar above the ribbon bar; FALSE to position the quick access toolbar below the ribbon bar. +*`bOnTop`*\ +[in] `TRUE` to position the quick access toolbar above the ribbon bar; `FALSE` to position the quick access toolbar below the ribbon bar. -## CMFCRibbonBar::SetTooltipFixedWidth +## `CMFCRibbonBar::SetTooltipFixedWidth` Sets the regular and large sizes of tooltip fixed widths for the ribbon bar. @@ -1746,17 +1745,17 @@ void SetTooltipFixedWidth( ### Parameters -*nWidthRegular*
+*`nWidthRegular`*\ [in] The width, in pixels, of a regular fixed sized tooltip. -*nWidthLargeImage*
+*`nWidthLargeImage`*\ [in] The width, in pixels, of a large fixed sized tooltip. ### Remarks Setting a parameter to 0 causes the corresponding width to vary. -## CMFCRibbonBar::ShowCategory +## `CMFCRibbonBar::ShowCategory` Shows or hides the specified ribbon category. @@ -1768,13 +1767,13 @@ void ShowCategory( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The index of the ribbon category. -*bShow*
-[in] If TRUE, show the ribbon category; otherwise, hide the ribbon category. +*`bShow`*\ +[in] If `TRUE`, show the ribbon category; otherwise, hide the ribbon category. -## CMFCRibbonBar::ShowContextCategories +## `CMFCRibbonBar::ShowContextCategories` Shows or hides the context categories that have the specified ID. @@ -1786,13 +1785,13 @@ void ShowContextCategories( ### Parameters -*uiContextID*
+*`uiContextID`*\ [in] The context category ID. -*bShow*
-[in] If TRUE, show the categories that have the specified ID; otherwise, hide the categories that have the specified ID. +*`bShow`*\ +[in] If `TRUE`, show the categories that have the specified ID; otherwise, hide the categories that have the specified ID. -## CMFCRibbonBar::ShowKeyTips +## `CMFCRibbonBar::ShowKeyTips` Shows the keytips for each ribbon element on the ribbon bar. @@ -1802,7 +1801,7 @@ void ShowKeyTips(); ### Remarks -## CMFCRibbonBar::ToggleMimimizeState +## `CMFCRibbonBar::ToggleMimimizeState` Toggles the ribbon bar between the minimized and maximized states. @@ -1816,7 +1815,7 @@ The misspelling in the method name is a known issue. In the minimized state, the ribbon control is hidden and only the tabs are displayed. When the user clicks a tab, the ribbon control is displayed as a popup window. The window closes when the user clicks away or executes a command. -## CMFCRibbonBar::TranslateChar +## `CMFCRibbonBar::TranslateChar` Determines whether the specified keystroke character code is processed by the ribbon bar. @@ -1826,18 +1825,18 @@ virtual BOOL TranslateChar(UINT nChar); ### Parameters -*nChar*
+*`nChar`*\ [in] A user keystroke character code. ### Return Value -TRUE if the character code was processed by the ribbon bar; otherwise FALSE. +`TRUE` if the character code was processed by the ribbon bar; otherwise `FALSE`. ### Remarks The keytips feature enables users to navigate the ribbon bar by using the keyboard. -## CMFCRibbonBar::GetFocused +## `CMFCRibbonBar::GetFocused` Returns a focused element. @@ -1847,13 +1846,13 @@ virtual CMFCRibbonBaseElement* GetFocused(); ### Return Value -A pointer to a focused element or NULL. +A pointer to a focused element or `NULL`. ### Remarks -## CMFCRibbonBar::IsWindows7Look +## `CMFCRibbonBar::IsWindows7Look` -Indicates whether the ribbon has Windows 7 look (small rectangular application button). +Indicates whether the ribbon has a Windows 7 look (small rectangular application button). ``` BOOL IsWindows7Look() const; @@ -1861,11 +1860,11 @@ BOOL IsWindows7Look() const; ### Return Value -TRUE if the ribbon has Windows 7 look; otherwise FALSE. +`TRUE` if the ribbon has a Windows 7 look; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::LoadFromResource +## `CMFCRibbonBar::LoadFromResource` Overloaded. Loads a Ribbon Bar from application resources. @@ -1883,25 +1882,25 @@ virtual BOOL LoadFromResource( ### Parameters -*uiXMLResID*
+*`uiXMLResID`*\ Specifies resource ID of XML string with Ribbon Bar information. -*lpszResType*
-Specifies type of the resource located at *uiXMLResID*. +*`lpszResType`*\ +Specifies type of the resource located at *`uiXMLResID`*. -*hInstance*
-Handle to the module whose executable file contains the resource. If *hInstance* is NULL, the system loads the resource from the module that was used to create the current process. +*`hInstance`*\ +Handle to the module whose executable file contains the resource. If *`hInstance`* is `NULL`, the system loads the resource from the module that was used to create the current process. -*lpszXMLResID*
+*`lpszXMLResID`*\ Specifies resource ID (in string form) with Ribbon Bar information. ### Return Value -TRUE if load succeeds; otherwise FALSE. +`TRUE` if load succeeds; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::SaveToXMLBuffer +## `CMFCRibbonBar::SaveToXMLBuffer` Saves the Ribbon Bar to a buffer. @@ -1911,16 +1910,16 @@ UINT SaveToXMLBuffer(LPBYTE* ppBuffer) const; ### Parameters -*ppBuffer*
-When this function returns, *ppBuffer* points to a buffer allocated by this method and contains Ribbon Bar information in XML format. +*`ppBuffer`*\ +When this function returns, *`ppBuffer`* points to a buffer allocated by this method and contains Ribbon Bar information in XML format. ### Return Value -TRUE if successful; otherwise FALSE. +`TRUE` if successful; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::SaveToXMLFile +## `CMFCRibbonBar::SaveToXMLFile` Saves the Ribbon Bar to an XML file. @@ -1930,18 +1929,18 @@ BOOL SaveToXMLFile(LPCTSTR lpszFilePath) const; ### Parameters -*lpszFilePath*
+*`lpszFilePath`*\ Specifies the output file. ### Return Value -TRUE if successful; otherwise FALSE. +`TRUE` if successful; otherwise `FALSE`. ### Remarks -## CMFCRibbonBar::SetWindows7Look +## `CMFCRibbonBar::SetWindows7Look` -Enables or disables Windows 7 look (small rectangular application button) for the Ribbon. +Enables or disables a Windows 7 look (small rectangular application button) for the Ribbon. ```cpp void SetWindows7Look( @@ -1951,20 +1950,20 @@ void SetWindows7Look( ### Parameters -*bWindows7Look*
-TRUE sets Windows 7 look; FALSE otherwise. +*`bWindows7Look`*\ +`TRUE` sets a Windows 7 look; `FALSE` otherwise. -*bRecalc*
-TRUE recalculates the ribbon layout; FALSE otherwise. +*`bRecalc`*\ +`TRUE` recalculates the ribbon layout; `FALSE` otherwise. ### Remarks ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CPane Class](../../mfc/reference/cpane-class.md)
-[CMFCRibbonCategory Class](../../mfc/reference/cmfcribboncategory-class.md)
-[CMFCRibbonPanel Class](../../mfc/reference/cmfcribbonpanel-class.md)
-[CMFCRibbonBaseElement Class](../../mfc/reference/cmfcribbonbaseelement-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CPane` Class](../../mfc/reference/cpane-class.md)\ +[`CMFCRibbonCategory` Class](../../mfc/reference/cmfcribboncategory-class.md)\ +[`CMFCRibbonPanel` Class](../../mfc/reference/cmfcribbonpanel-class.md)\ +[`CMFCRibbonBaseElement` Class](../../mfc/reference/cmfcribbonbaseelement-class.md)\ [Walkthrough: Updating the MFC Scribble Application](../../mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md) diff --git a/docs/mfc/reference/cmfcribbonbaseelement-class.md b/docs/mfc/reference/cmfcribbonbaseelement-class.md index 27c7ee698a..7f320909b9 100644 --- a/docs/mfc/reference/cmfcribbonbaseelement-class.md +++ b/docs/mfc/reference/cmfcribbonbaseelement-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCRibbonBaseElement Class" title: "CMFCRibbonBaseElement Class" +description: "Learn more about: CMFCRibbonBaseElement Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonBaseElement", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::AddToKeyList", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::AddToListBox", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CanBeAddedToQuickAccessToolBar", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CanBeCompacted", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CanBeStretched", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CanBeStretchedHorizontally", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CleanUpSizes", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::ClosePopupMenu", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::CopyFrom", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::DestroyCtrl", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::DrawImage", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::Find", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::FindByData", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::FindByID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::FindByOriginal", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetCompactSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetData", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetDescription", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetDroppedDown", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetElements", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetElementsByID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetHighlighted", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetImageSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetIntermediateSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetKeys", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetKeyTipRect", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetKeyTipSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetLocationInGroup", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetMenuKeys", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetNotifyID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetOriginal", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetParentCategory", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetParentPanel", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetParentRibbonBar", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetParentWnd", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetPressed", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetQuickAccessToolBarID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetRect", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetRegularSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetText", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetToolTipText", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::GetTopLevelRibbonBar", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HasCompactMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HasFocus", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HasIntermediateMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HasLargeMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HasMenu", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::HitTest", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsAlignByColumn", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsAlwaysLargeImage", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsAutoRepeatMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsChecked", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsCompactMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsDefaultMenuLook", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsDisabled", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsDroppedDown", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsFocused", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsGalleryIcon", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsHighlighted", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsIntermediateMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsLargeMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsMenuMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsPressed", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsQATMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsSeparator", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsShowGroupBorder", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsShowTooltipOnBottom", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsTabStop", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsTextAlwaysOnRight", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsVisible", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::IsWholeRowHeight", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::NotifyCommand", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::NotifyHighlightListItem", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnAddToQAToolbar", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnAfterChangeRect", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnAutoRepeat", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnCalcTextSize", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnChangeMenuHighlight", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnDraw", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnDrawKeyTip", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnDrawMenuImage", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnDrawOnList", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnKey", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnMenuKey", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnRTLChanged", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnShow", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnShowPopupMenu", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::PostMenuCommand", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::Redraw", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetACCData", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetCompactMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetData", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetDefaultMenuLook", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetDescription", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetID", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetInitialMode", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetKeys", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetOriginal", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetParentCategory", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetParentMenu", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetParentRibbonBar", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetRect", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetText", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetTextAlwaysOnRight", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetToolTipText", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::SetVisible", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::StretchHorizontally", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::StretchToWholeRow", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::UpdateTooltipInfo", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnProcessKey", "AFXBASERIBBONELEMENT/CMFCRibbonBaseElement::OnSetFocus"] helpviewer_keywords: ["CMFCRibbonBaseElement [MFC], AddToKeyList", "CMFCRibbonBaseElement [MFC], AddToListBox", "CMFCRibbonBaseElement [MFC], CanBeAddedToQuickAccessToolBar", "CMFCRibbonBaseElement [MFC], CanBeCompacted", "CMFCRibbonBaseElement [MFC], CanBeStretched", "CMFCRibbonBaseElement [MFC], CanBeStretchedHorizontally", "CMFCRibbonBaseElement [MFC], CleanUpSizes", "CMFCRibbonBaseElement [MFC], ClosePopupMenu", "CMFCRibbonBaseElement [MFC], CopyFrom", "CMFCRibbonBaseElement [MFC], DestroyCtrl", "CMFCRibbonBaseElement [MFC], DrawImage", "CMFCRibbonBaseElement [MFC], Find", "CMFCRibbonBaseElement [MFC], FindByData", "CMFCRibbonBaseElement [MFC], FindByID", "CMFCRibbonBaseElement [MFC], FindByOriginal", "CMFCRibbonBaseElement [MFC], GetCompactSize", "CMFCRibbonBaseElement [MFC], GetData", "CMFCRibbonBaseElement [MFC], GetDescription", "CMFCRibbonBaseElement [MFC], GetDroppedDown", "CMFCRibbonBaseElement [MFC], GetElements", "CMFCRibbonBaseElement [MFC], GetElementsByID", "CMFCRibbonBaseElement [MFC], GetHighlighted", "CMFCRibbonBaseElement [MFC], GetID", "CMFCRibbonBaseElement [MFC], GetImageSize", "CMFCRibbonBaseElement [MFC], GetIntermediateSize", "CMFCRibbonBaseElement [MFC], GetKeys", "CMFCRibbonBaseElement [MFC], GetKeyTipRect", "CMFCRibbonBaseElement [MFC], GetKeyTipSize", "CMFCRibbonBaseElement [MFC], GetLocationInGroup", "CMFCRibbonBaseElement [MFC], GetMenuKeys", "CMFCRibbonBaseElement [MFC], GetNotifyID", "CMFCRibbonBaseElement [MFC], GetOriginal", "CMFCRibbonBaseElement [MFC], GetParentCategory", "CMFCRibbonBaseElement [MFC], GetParentPanel", "CMFCRibbonBaseElement [MFC], GetParentRibbonBar", "CMFCRibbonBaseElement [MFC], GetParentWnd", "CMFCRibbonBaseElement [MFC], GetPressed", "CMFCRibbonBaseElement [MFC], GetQuickAccessToolBarID", "CMFCRibbonBaseElement [MFC], GetRect", "CMFCRibbonBaseElement [MFC], GetRegularSize", "CMFCRibbonBaseElement [MFC], GetSize", "CMFCRibbonBaseElement [MFC], GetText", "CMFCRibbonBaseElement [MFC], GetToolTipText", "CMFCRibbonBaseElement [MFC], GetTopLevelRibbonBar", "CMFCRibbonBaseElement [MFC], HasCompactMode", "CMFCRibbonBaseElement [MFC], HasFocus", "CMFCRibbonBaseElement [MFC], HasIntermediateMode", "CMFCRibbonBaseElement [MFC], HasLargeMode", "CMFCRibbonBaseElement [MFC], HasMenu", "CMFCRibbonBaseElement [MFC], HitTest", "CMFCRibbonBaseElement [MFC], IsAlignByColumn", "CMFCRibbonBaseElement [MFC], IsAlwaysLargeImage", "CMFCRibbonBaseElement [MFC], IsAutoRepeatMode", "CMFCRibbonBaseElement [MFC], IsChecked", "CMFCRibbonBaseElement [MFC], IsCompactMode", "CMFCRibbonBaseElement [MFC], IsDefaultMenuLook", "CMFCRibbonBaseElement [MFC], IsDisabled", "CMFCRibbonBaseElement [MFC], IsDroppedDown", "CMFCRibbonBaseElement [MFC], IsFocused", "CMFCRibbonBaseElement [MFC], IsGalleryIcon", "CMFCRibbonBaseElement [MFC], IsHighlighted", "CMFCRibbonBaseElement [MFC], IsIntermediateMode", "CMFCRibbonBaseElement [MFC], IsLargeMode", "CMFCRibbonBaseElement [MFC], IsMenuMode", "CMFCRibbonBaseElement [MFC], IsPressed", "CMFCRibbonBaseElement [MFC], IsQATMode", "CMFCRibbonBaseElement [MFC], IsSeparator", "CMFCRibbonBaseElement [MFC], IsShowGroupBorder", "CMFCRibbonBaseElement [MFC], IsShowTooltipOnBottom", "CMFCRibbonBaseElement [MFC], IsTabStop", "CMFCRibbonBaseElement [MFC], IsTextAlwaysOnRight", "CMFCRibbonBaseElement [MFC], IsVisible", "CMFCRibbonBaseElement [MFC], IsWholeRowHeight", "CMFCRibbonBaseElement [MFC], NotifyCommand", "CMFCRibbonBaseElement [MFC], NotifyHighlightListItem", "CMFCRibbonBaseElement [MFC], OnAddToQAToolbar", "CMFCRibbonBaseElement [MFC], OnAfterChangeRect", "CMFCRibbonBaseElement [MFC], OnAutoRepeat", "CMFCRibbonBaseElement [MFC], OnCalcTextSize", "CMFCRibbonBaseElement [MFC], OnChangeMenuHighlight", "CMFCRibbonBaseElement [MFC], OnDraw", "CMFCRibbonBaseElement [MFC], OnDrawKeyTip", "CMFCRibbonBaseElement [MFC], OnDrawMenuImage", "CMFCRibbonBaseElement [MFC], OnDrawOnList", "CMFCRibbonBaseElement [MFC], OnKey", "CMFCRibbonBaseElement [MFC], OnMenuKey", "CMFCRibbonBaseElement [MFC], OnRTLChanged", "CMFCRibbonBaseElement [MFC], OnShow", "CMFCRibbonBaseElement [MFC], OnShowPopupMenu", "CMFCRibbonBaseElement [MFC], PostMenuCommand", "CMFCRibbonBaseElement [MFC], Redraw", "CMFCRibbonBaseElement [MFC], SetACCData", "CMFCRibbonBaseElement [MFC], SetCompactMode", "CMFCRibbonBaseElement [MFC], SetData", "CMFCRibbonBaseElement [MFC], SetDefaultMenuLook", "CMFCRibbonBaseElement [MFC], SetDescription", "CMFCRibbonBaseElement [MFC], SetID", "CMFCRibbonBaseElement [MFC], SetInitialMode", "CMFCRibbonBaseElement [MFC], SetKeys", "CMFCRibbonBaseElement [MFC], SetOriginal", "CMFCRibbonBaseElement [MFC], SetParentCategory", "CMFCRibbonBaseElement [MFC], SetParentMenu", "CMFCRibbonBaseElement [MFC], SetParentRibbonBar", "CMFCRibbonBaseElement [MFC], SetRect", "CMFCRibbonBaseElement [MFC], SetText", "CMFCRibbonBaseElement [MFC], SetTextAlwaysOnRight", "CMFCRibbonBaseElement [MFC], SetToolTipText", "CMFCRibbonBaseElement [MFC], SetVisible", "CMFCRibbonBaseElement [MFC], StretchHorizontally", "CMFCRibbonBaseElement [MFC], StretchToWholeRow", "CMFCRibbonBaseElement [MFC], UpdateTooltipInfo", "CMFCRibbonBaseElement [MFC], OnProcessKey", "CMFCRibbonBaseElement [MFC], OnSetFocus"] -ms.assetid: 419ea91b-5062-44cc-b0a3-f87d29566f62 --- # CMFCRibbonBaseElement Class @@ -131,7 +130,7 @@ class CMFCRibbonBaseElement : public CObject |[CMFCRibbonBaseElement::SetParentCategory](#setparentcategory)|Sets the parent category for the ribbon element.| |[CMFCRibbonBaseElement::SetParentMenu](#setparentmenu)|Sets the parent menu container for the ribbon element.| |[CMFCRibbonBaseElement::SetParentRibbonBar](#setparentribbonbar)|Sets the parent ribbon bar for the ribbon element.| -|[CMFCRibbonBaseElement::SetRect](#setrect)|Sets the dimensions fot he display rectangle for the ribbon element.| +|[CMFCRibbonBaseElement::SetRect](#setrect)|Sets the dimensions of the display rectangle for the ribbon element.| |[CMFCRibbonBaseElement::SetText](#settext)|Sets the text for the ribbon element.| |[CMFCRibbonBaseElement::SetTextAlwaysOnRight](#settextalwaysonright)|Sets the text for the ribbon element to display on the right.| |[CMFCRibbonBaseElement::SetToolTipText](#settooltiptext)|Sets the tooltip text for the ribbon element.| @@ -2042,5 +2041,5 @@ TRUE if the ribbon element is focused; otherwise FALSE. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Classes](../../mfc/reference/mfc-classes.md) diff --git a/docs/mfc/reference/cmfcribboncategory-class.md b/docs/mfc/reference/cmfcribboncategory-class.md index 242d0f8fb9..74d7ee56cb 100644 --- a/docs/mfc/reference/cmfcribboncategory-class.md +++ b/docs/mfc/reference/cmfcribboncategory-class.md @@ -838,7 +838,7 @@ Only ribbon elements that are contained in the ribbon category are tested. ## CMFCRibbonCategory::HitTestScrollButtons -If a point falls within a ribbon category’s left or right scroll button, returns a pointer to that button. +If a point falls within a ribbon category's left or right scroll button, returns a pointer to that button. ``` CMFCRibbonBaseElement* HitTestScrollButtons(CPoint point) const; diff --git a/docs/mfc/reference/cmfcribboncheckbox-class.md b/docs/mfc/reference/cmfcribboncheckbox-class.md index 57ce564c55..dd35d63440 100644 --- a/docs/mfc/reference/cmfcribboncheckbox-class.md +++ b/docs/mfc/reference/cmfcribboncheckbox-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCRibbonCheckBox Class" title: "CMFCRibbonCheckBox Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCRibbonCheckBox Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCRibbonCheckBox", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::CMFCRibbonCheckBox", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::GetCompactSize", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::GetIntermediateSize", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::GetRegularSize", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::IsDrawTooltipImage", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::OnDraw", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::OnDrawMenuImage", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::OnDrawOnList", "AFXRIBBONCHECKBOX/CMFCRibbonCheckBox::SetACCData"] helpviewer_keywords: ["CMFCRibbonCheckBox [MFC], CMFCRibbonCheckBox", "CMFCRibbonCheckBox [MFC], GetCompactSize", "CMFCRibbonCheckBox [MFC], GetIntermediateSize", "CMFCRibbonCheckBox [MFC], GetRegularSize", "CMFCRibbonCheckBox [MFC], IsDrawTooltipImage", "CMFCRibbonCheckBox [MFC], OnDraw", "CMFCRibbonCheckBox [MFC], OnDrawMenuImage", "CMFCRibbonCheckBox [MFC], OnDrawOnList", "CMFCRibbonCheckBox [MFC], SetACCData"] -ms.assetid: 3a6c3891-c8d1-4af0-b954-7b9ab048782a --- # CMFCRibbonCheckBox Class @@ -131,7 +130,7 @@ A `CSize` object containing the intermediate size of the check box. ### Remarks -If not overridden, calculates the intermediate size as the default check box size ( `AFX_CHECK_BOX_DEFAULT_SIZE`) plus the text size, plus margins. +If not overridden, calculates the intermediate size as the default check box size (`AFX_CHECK_BOX_DEFAULT_SIZE`) plus the text size, plus margins. ## CMFCRibbonCheckBox::GetRegularSize diff --git a/docs/mfc/reference/cmfcribboncolorbutton-class.md b/docs/mfc/reference/cmfcribboncolorbutton-class.md index 3ad6148fb5..29ea27176b 100644 --- a/docs/mfc/reference/cmfcribboncolorbutton-class.md +++ b/docs/mfc/reference/cmfcribboncolorbutton-class.md @@ -241,7 +241,7 @@ The size of the color buttons in the drop-down color palette. ## CMFCRibbonColorButton::GetColumns -Gets the number of items in a row of the ribbon color button’s gallery display. +Gets the number of items in a row of the ribbon color button's gallery display. ``` int GetColumns() const; diff --git a/docs/mfc/reference/cmfcribboncontextcaption-class.md b/docs/mfc/reference/cmfcribboncontextcaption-class.md index 0cbbbcd3aa..ce8c6bd89a 100644 --- a/docs/mfc/reference/cmfcribboncontextcaption-class.md +++ b/docs/mfc/reference/cmfcribboncontextcaption-class.md @@ -81,7 +81,7 @@ The color of the caption can be set by calling [CMFCRibbonCategory::SetTabColor] ## CMFCRibbonContextCaption::GetRightTabX -Retrieves the position of the right-hand edge of the category’s ribbon tab. +Retrieves the position of the right-hand edge of the category's ribbon tab. ``` int GetRightTabX() const; @@ -89,7 +89,7 @@ int GetRightTabX() const; ### Return Value -Returns the right-hand X-value of the enclosing rectangle of the `CMFCRibbonCategory` object’s ribbon tab, or a value of -1 if the tab is truncated. +Returns the right-hand X-value of the enclosing rectangle of the `CMFCRibbonCategory` object's ribbon tab, or a value of -1 if the tab is truncated. ### Remarks diff --git a/docs/mfc/reference/cmfcribbonfontcombobox-class.md b/docs/mfc/reference/cmfcribbonfontcombobox-class.md index 3582dbb7f9..e37df6dfc0 100644 --- a/docs/mfc/reference/cmfcribbonfontcombobox-class.md +++ b/docs/mfc/reference/cmfcribbonfontcombobox-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCRibbonFontComboBox Class" title: "CMFCRibbonFontComboBox Class" +description: "Learn more about: CMFCRibbonFontComboBox Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonFontComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::CMFCRibbonFontComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::BuildFonts", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::GetCharSet", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::GetFontDesc", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::GetFontType", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::GetPitchAndFamily", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::RebuildFonts", "AFXRIBBONCOMBOBOX/CMFCRibbonFontComboBox::SetFont"] helpviewer_keywords: ["CMFCRibbonFontComboBox [MFC], CMFCRibbonFontComboBox", "CMFCRibbonFontComboBox [MFC], BuildFonts", "CMFCRibbonFontComboBox [MFC], GetCharSet", "CMFCRibbonFontComboBox [MFC], GetFontDesc", "CMFCRibbonFontComboBox [MFC], GetFontType", "CMFCRibbonFontComboBox [MFC], GetPitchAndFamily", "CMFCRibbonFontComboBox [MFC], RebuildFonts", "CMFCRibbonFontComboBox [MFC], SetFont"] -ms.assetid: 33b4db50-df4f-45fa-8f05-2e6e73c31435 --- # CMFCRibbonFontComboBox Class @@ -110,7 +109,7 @@ CMFCRibbonFontComboBox( [in] Specifies which font types to display in the combo box. Valid options are DEVICE_FONTTYPE, RASTER_FONTTYPE, and TRUETYPE_FONTTYPE, or any bitwise combination thereof. *nCharSet*
-[in] Filters the fonts in the combo box to those that belong to the specified character set.. +[in] Filters the fonts in the combo box to those that belong to the specified character set. *nPitchAndFamily*
[in] Specifies the pitch and the family of the fonts that are displayed in the combo box. @@ -224,6 +223,6 @@ Pitch and the family (see LOGFONT in the Windows SDK documentation). ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ [CMFCRibbonComboBox Class](../../mfc/reference/cmfcribboncombobox-class.md) diff --git a/docs/mfc/reference/cmfcribbongallery-class.md b/docs/mfc/reference/cmfcribbongallery-class.md index b86fd74dc2..38ba418a4e 100644 --- a/docs/mfc/reference/cmfcribbongallery-class.md +++ b/docs/mfc/reference/cmfcribbongallery-class.md @@ -84,8 +84,8 @@ The following example demonstrates how to use various methods in the `CMFCRibbon [CObject](../../mfc/reference/cobject-class.md)\ └ [CMFCRibbonBaseElement](../../mfc/reference/cmfcribbonbaseelement-class.md)\ -    └ [CMFCRibbonButton](../../mfc/reference/cmfcribbonbutton-class.md)\ -        └ [CMFCRibbonGallery](../../mfc/reference/cmfcribbongallery-class.md) + └ [CMFCRibbonButton](../../mfc/reference/cmfcribbonbutton-class.md)\ +  └ [CMFCRibbonGallery](../../mfc/reference/cmfcribbongallery-class.md) ## Requirements diff --git a/docs/mfc/reference/cmfcribbongallerymenubutton-class.md b/docs/mfc/reference/cmfcribbongallerymenubutton-class.md index dfc162862f..675fee0b13 100644 --- a/docs/mfc/reference/cmfcribbongallerymenubutton-class.md +++ b/docs/mfc/reference/cmfcribbongallerymenubutton-class.md @@ -71,8 +71,8 @@ BOOL CMainFrame::OnShowPopupMenu (CMFCPopupMenu* pMenuPopup) [CObject](../../mfc/reference/cobject-class.md)\ └ [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md)\ -    └ [CMFCToolBarMenuButton](../../mfc/reference/cmfctoolbarmenubutton-class.md)\ -        └ [CMFCRibbonGalleryMenuButton](../../mfc/reference/cmfcribbongallerymenubutton-class.md) + └ [CMFCToolBarMenuButton](../../mfc/reference/cmfctoolbarmenubutton-class.md)\ +  └ [CMFCRibbonGalleryMenuButton](../../mfc/reference/cmfcribbongallerymenubutton-class.md) ## Requirements diff --git a/docs/mfc/reference/cmfcribbonlinkctrl-class.md b/docs/mfc/reference/cmfcribbonlinkctrl-class.md index 14e3be9f0b..1eaa093ba6 100644 --- a/docs/mfc/reference/cmfcribbonlinkctrl-class.md +++ b/docs/mfc/reference/cmfcribbonlinkctrl-class.md @@ -50,8 +50,8 @@ After you create a hyperlink, add it to a panel by calling [CMFCRibbonPanel::Add [CObject](../../mfc/reference/cobject-class.md)\ └ [CMFCRibbonBaseElement](../../mfc/reference/cmfcribbonbaseelement-class.md)\ -    └ [CMFCRibbonButton](../../mfc/reference/cmfcribbonbutton-class.md)\ -        └ [CMFCRibbonLinkCtrl](../../mfc/reference/cmfcribbonlinkctrl-class.md) + └ [CMFCRibbonButton](../../mfc/reference/cmfcribbonbutton-class.md)\ +  └ [CMFCRibbonLinkCtrl](../../mfc/reference/cmfcribbonlinkctrl-class.md) ## Requirements diff --git a/docs/mfc/reference/cmfcribbonpanel-class.md b/docs/mfc/reference/cmfcribbonpanel-class.md index ae0c4cf2d4..2a81fe3a7a 100644 --- a/docs/mfc/reference/cmfcribbonpanel-class.md +++ b/docs/mfc/reference/cmfcribbonpanel-class.md @@ -968,7 +968,6 @@ If you want to add a custom element (for example, a color button) to the ribbon The following example shows how to use the `SetElementRTCByID` method: ``` - // Load and add toolbar with standard buttons. This toolbar // should display a custom color button with id ID_CHAR_COLOR: diff --git a/docs/mfc/reference/cmfctabctrl-class.md b/docs/mfc/reference/cmfctabctrl-class.md index a76ea976a3..d59039a359 100644 --- a/docs/mfc/reference/cmfctabctrl-class.md +++ b/docs/mfc/reference/cmfctabctrl-class.md @@ -4,9 +4,8 @@ title: "CMFCTabCtrl Class" ms.date: "08/28/2019" f1_keywords: ["CMFCTabCtrl", "AFXTABCTRL/CMFCTabCtrl", "AFXTABCTRL/CMFCTabCtrl::ActivateMDITab", "AFXTABCTRL/CMFCTabCtrl::AllowDestroyEmptyTabbedPane", "AFXTABCTRL/CMFCTabCtrl::AutoSizeWindow", "AFXTABCTRL/CMFCTabCtrl::CalcRectEdit", "AFXTABCTRL/CMFCTabCtrl::Create", "AFXTABCTRL/CMFCTabCtrl::EnableActiveTabCloseButton", "AFXTABCTRL/CMFCTabCtrl::EnableInPlaceEdit", "AFXTABCTRL/CMFCTabCtrl::EnableTabDocumentsMenu", "AFXTABCTRL/CMFCTabCtrl::EnsureVisible", "AFXTABCTRL/CMFCTabCtrl::GetDocumentIcon", "AFXTABCTRL/CMFCTabCtrl::GetFirstVisibleTabNum", "AFXTABCTRL/CMFCTabCtrl::GetResizeMode", "AFXTABCTRL/CMFCTabCtrl::GetScrollBar", "AFXTABCTRL/CMFCTabCtrl::GetTabArea", "AFXTABCTRL/CMFCTabCtrl::GetTabMaxWidth", "AFXTABCTRL/CMFCTabCtrl::GetTabsHeight", "AFXTABCTRL/CMFCTabCtrl::GetTabsRect", "AFXTABCTRL/CMFCTabCtrl::GetWndArea", "AFXTABCTRL/CMFCTabCtrl::HideActiveWindowHorzScrollBar", "AFXTABCTRL/CMFCTabCtrl::HideInactiveWindow", "AFXTABCTRL/CMFCTabCtrl::HideNoTabs", "AFXTABCTRL/CMFCTabCtrl::HideSingleTab", "AFXTABCTRL/CMFCTabCtrl::IsActiveInMDITabGroup", "AFXTABCTRL/CMFCTabCtrl::IsActiveTabBoldFont", "AFXTABCTRL/CMFCTabCtrl::IsActiveTabCloseButton", "AFXTABCTRL/CMFCTabCtrl::IsDrawFrame", "AFXTABCTRL/CMFCTabCtrl::IsFlatFrame", "AFXTABCTRL/CMFCTabCtrl::IsFlatTab", "AFXTABCTRL/CMFCTabCtrl::IsLeftRightRounded", "AFXTABCTRL/CMFCTabCtrl::IsMDITabGroup", "AFXTABCTRL/CMFCTabCtrl::IsOneNoteStyle", "AFXTABCTRL/CMFCTabCtrl::IsSharedScroll", "AFXTABCTRL/CMFCTabCtrl::IsTabDocumentsMenu", "AFXTABCTRL/CMFCTabCtrl::IsVS2005Style", "AFXTABCTRL/CMFCTabCtrl::ModifyTabStyle", "AFXTABCTRL/CMFCTabCtrl::OnDragEnter", "AFXTABCTRL/CMFCTabCtrl::OnDragOver", "AFXTABCTRL/CMFCTabCtrl::OnShowTabDocumentsMenu", "AFXTABCTRL/CMFCTabCtrl::SetActiveInMDITabGroup", "AFXTABCTRL/CMFCTabCtrl::SetActiveTab", "AFXTABCTRL/CMFCTabCtrl::SetActiveTabBoldFont", "AFXTABCTRL/CMFCTabCtrl::SetDrawFrame", "AFXTABCTRL/CMFCTabCtrl::SetFlatFrame", "AFXTABCTRL/CMFCTabCtrl::SetImageList", "AFXTABCTRL/CMFCTabCtrl::SetResizeMode", "AFXTABCTRL/CMFCTabCtrl::SetTabMaxWidth", "AFXTABCTRL/CMFCTabCtrl::StopResize", "AFXTABCTRL/CMFCTabCtrl::SynchronizeScrollBar", "AFXTABCTRL/CMFCTabCtrl::m_bEnableActivate"] helpviewer_keywords: ["CMFCTabCtrl [MFC], ActivateMDITab", "CMFCTabCtrl [MFC], AllowDestroyEmptyTabbedPane", "CMFCTabCtrl [MFC], AutoSizeWindow", "CMFCTabCtrl [MFC], CalcRectEdit", "CMFCTabCtrl [MFC], Create", "CMFCTabCtrl [MFC], EnableActiveTabCloseButton", "CMFCTabCtrl [MFC], EnableInPlaceEdit", "CMFCTabCtrl [MFC], EnableTabDocumentsMenu", "CMFCTabCtrl [MFC], EnsureVisible", "CMFCTabCtrl [MFC], GetDocumentIcon", "CMFCTabCtrl [MFC], GetFirstVisibleTabNum", "CMFCTabCtrl [MFC], GetResizeMode", "CMFCTabCtrl [MFC], GetScrollBar", "CMFCTabCtrl [MFC], GetTabArea", "CMFCTabCtrl [MFC], GetTabMaxWidth", "CMFCTabCtrl [MFC], GetTabsHeight", "CMFCTabCtrl [MFC], GetTabsRect", "CMFCTabCtrl [MFC], GetWndArea", "CMFCTabCtrl [MFC], HideActiveWindowHorzScrollBar", "CMFCTabCtrl [MFC], HideInactiveWindow", "CMFCTabCtrl [MFC], HideNoTabs", "CMFCTabCtrl [MFC], HideSingleTab", "CMFCTabCtrl [MFC], IsActiveInMDITabGroup", "CMFCTabCtrl [MFC], IsActiveTabBoldFont", "CMFCTabCtrl [MFC], IsActiveTabCloseButton", "CMFCTabCtrl [MFC], IsDrawFrame", "CMFCTabCtrl [MFC], IsFlatFrame", "CMFCTabCtrl [MFC], IsFlatTab", "CMFCTabCtrl [MFC], IsLeftRightRounded", "CMFCTabCtrl [MFC], IsMDITabGroup", "CMFCTabCtrl [MFC], IsOneNoteStyle", "CMFCTabCtrl [MFC], IsSharedScroll", "CMFCTabCtrl [MFC], IsTabDocumentsMenu", "CMFCTabCtrl [MFC], IsVS2005Style", "CMFCTabCtrl [MFC], ModifyTabStyle", "CMFCTabCtrl [MFC], OnDragEnter", "CMFCTabCtrl [MFC], OnDragOver", "CMFCTabCtrl [MFC], OnShowTabDocumentsMenu", "CMFCTabCtrl [MFC], SetActiveInMDITabGroup", "CMFCTabCtrl [MFC], SetActiveTab", "CMFCTabCtrl [MFC], SetActiveTabBoldFont", "CMFCTabCtrl [MFC], SetDrawFrame", "CMFCTabCtrl [MFC], SetFlatFrame", "CMFCTabCtrl [MFC], SetImageList", "CMFCTabCtrl [MFC], SetResizeMode", "CMFCTabCtrl [MFC], SetTabMaxWidth", "CMFCTabCtrl [MFC], StopResize", "CMFCTabCtrl [MFC], SynchronizeScrollBar", "CMFCTabCtrl [MFC], m_bEnableActivate"] -ms.assetid: d441385d-2c72-4203-96fa-deae2273da35 --- -# CMFCTabCtrl Class +# `CMFCTabCtrl` Class The `CMFCTabCtrl` class provides functionality for a tab control. The tab control displays a dockable window with flat or three-dimensional tabs at its top or bottom. The tabs can display text and an image and can change color when active. @@ -29,68 +28,68 @@ class CMFCTabCtrl : public CMFCBaseTabCtrl |Name|Description| |----------|-----------------| -|[CMFCTabCtrl::ActivateMDITab](#activatemditab)|Displays the specified tab of the current tab control and sets the focus on that tab.| -|[CMFCTabCtrl::AllowDestroyEmptyTabbedPane](#allowdestroyemptytabbedpane)|| -|[CMFCTabCtrl::AutoSizeWindow](#autosizewindow)|Specifies whether the framework is to resize the client area of all tab control windows when a user interface element of the tab control changes.| -|[CMFCTabCtrl::CalcRectEdit](#calcrectedit)|Deflates the size of the specified tab area. (Overrides `CMFCBaseTabCtrl::CalcRectEdit`.)| -|[CMFCTabCtrl::Create](#create)|Creates the tab control and attaches it to the `CMFCTabCtrl` object.| +|[`CMFCTabCtrl::ActivateMDITab`](#activatemditab)|Displays the specified tab of the current tab control and sets the focus on that tab.| +|[`CMFCTabCtrl::AllowDestroyEmptyTabbedPane`](#allowdestroyemptytabbedpane)|| +|[`CMFCTabCtrl::AutoSizeWindow`](#autosizewindow)|Specifies whether the framework is to resize the client area of all tab control windows when a user interface element of the tab control changes.| +|[`CMFCTabCtrl::CalcRectEdit`](#calcrectedit)|Deflates the size of the specified tab area. (Overrides `CMFCBaseTabCtrl::CalcRectEdit`).| +|[`CMFCTabCtrl::Create`](#create)|Creates the tab control and attaches it to the `CMFCTabCtrl` object.| |`CMFCTabCtrl::CreateObject`|Used by the framework to create a dynamic instance of this class type.| -|[CMFCTabCtrl::EnableActiveTabCloseButton](#enableactivetabclosebutton)|Shows or hides a Close button ( **X**) on the active tab.| -|[CMFCTabCtrl::EnableInPlaceEdit](#enableinplaceedit)|Enables or disables editable tab labels. (Overrides [CMFCBaseTabCtrl::EnableInPlaceEdit](../../mfc/reference/cmfcbasetabctrl-class.md#enableinplaceedit).)| -|[CMFCTabCtrl::EnableTabDocumentsMenu](#enabletabdocumentsmenu)|Replaces two buttons that scroll the window tabs with a button that opens a menu of tabbed windows.| -|[CMFCTabCtrl::EnsureVisible](#ensurevisible)|Ensures that a tab is visible.| -|[CMFCTabCtrl::GetDocumentIcon](#getdocumenticon)|Retrieves the symbol that is associated with a tab in a popup menu of tabbed windows.| -|[CMFCTabCtrl::GetFirstVisibleTabNum](#getfirstvisibletabnum)|Retrieves the index of the first tab that is visible in the current tab control.| -|[CMFCTabCtrl::GetResizeMode](#getresizemode)|Retrieves a value that specifies how the current tab control can be resized.| -|[CMFCTabCtrl::GetScrollBar](#getscrollbar)|Retrieves a pointer to the scroll bar object that is associated with the tab control.| -|[CMFCTabCtrl::GetTabArea](#gettabarea)|Retrieves the bounding rectangle of the tab label area at the top or bottom of the tab control. (Overrides [CMFCBaseTabCtrl::GetTabArea](../../mfc/reference/cmfcbasetabctrl-class.md#gettabarea).)| -|`CMFCTabCtrl::GetTabFromPoint`|Retrieves the tab that contains a specified point. (Overrides [CMFCBaseTabCtrl::GetTabFromPoint](../../mfc/reference/cmfcbasetabctrl-class.md#gettabfrompoint).)| -|[CMFCTabCtrl::GetTabMaxWidth](#gettabmaxwidth)|Retrieves the maximum width of a tab.| -|[CMFCTabCtrl::GetTabsHeight](#gettabsheight)|Retrieves the height of the tab area of the current tab control.| -|[CMFCTabCtrl::GetTabsRect](#gettabsrect)|Retrieves a rectangle that bounds the tab area of the current tab control. (Overrides [CMFCBaseTabCtrl::GetTabsRect](../../mfc/reference/cmfcbasetabctrl-class.md#gettabsrect).)| -|`CMFCTabCtrl::GetThisClass`|Used by the framework to obtain a pointer to the [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| -|[CMFCTabCtrl::GetWndArea](#getwndarea)|Retrieves the boundary of the client area of the current tab control.| -|[CMFCTabCtrl::HideActiveWindowHorzScrollBar](#hideactivewindowhorzscrollbar)|Hides the horizontal scroll bar, if any, of the active window.| -|[CMFCTabCtrl::HideInactiveWindow](#hideinactivewindow)|Specifies whether the framework is to display inactive tab control windows.| -|[CMFCTabCtrl::HideNoTabs](#hidenotabs)|Enables or disables drawing the tab area if there are no visible tabs.| -|[CMFCTabCtrl::HideSingleTab](#hidesingletab)|Enables or disables drawing a tab when there is a single tabbed window. (Overrides [CMFCBaseTabCtrl::HideSingleTab](../../mfc/reference/cmfcbasetabctrl-class.md#hidesingletab).)| -|[CMFCTabCtrl::IsActiveInMDITabGroup](#isactiveinmditabgroup)|Indicates whether the current tab of a tab control is the active tab in an multiple document interface tab group.| -|[CMFCTabCtrl::IsActiveTabBoldFont](#isactivetabboldfont)|Indicates whether the text of the active tab is displayed using a bold font.| -|[CMFCTabCtrl::IsActiveTabCloseButton](#isactivetabclosebutton)|Indicates whether the Close button ( **X**) is displayed on an active tab or the upper-right corner of the tab area.| -|[CMFCTabCtrl::IsDrawFrame](#isdrawframe)|Indicates whether the tabbed window draws a frame rectangle around embedded panes.| -|[CMFCTabCtrl::IsFlatFrame](#isflatframe)|Indicates whether the frame around the tab area is flat or 3D.| -|[CMFCTabCtrl::IsFlatTab](#isflattab)|Indicates whether the appearance of the tabs in the current tab control is flat or not.| -|[CMFCTabCtrl::IsLeftRightRounded](#isleftrightrounded)|Indicates whether the appearance of the left and right side of a tab in the current tab control is rounded.| -|[CMFCTabCtrl::IsMDITabGroup](#ismditabgroup)|Indicates whether the current tab control is contained in the client area of a multiple-document interface window.| -|[CMFCTabCtrl::IsOneNoteStyle](#isonenotestyle)|Indicates whether the current tab control is displayed in the style of Microsoft OneNote.| -|`CMFCTabCtrl::IsPtInTabArea`|Determines if a point is inside the tab area. (Overrides [CMFCBaseTabCtrl::IsPtInTabArea](../../mfc/reference/cmfcbasetabctrl-class.md#isptintabarea).)| -|[CMFCTabCtrl::IsSharedScroll](#issharedscroll)|Indicates whether the current tab control has a scroll bar that can scroll its tabs as a group.| -|[CMFCTabCtrl::IsTabDocumentsMenu](#istabdocumentsmenu)|Indicates whether the tab control displays scroll buttons or a button that displays a menu of tabbed windows.| -|[CMFCTabCtrl::IsVS2005Style](#isvs2005style)|Indicates whether tabs are displayed in the style of Visual Studio .NET 2005.| -|[CMFCTabCtrl::ModifyTabStyle](#modifytabstyle)|Specifies the appearance of tabs in the current tab control.| -|`CMFCTabCtrl::MoveTab`|Moves a tab to another tab position. (Overrides [CMFCBaseTabCtrl::MoveTab](../../mfc/reference/cmfcbasetabctrl-class.md#movetab).)| -|[CMFCTabCtrl::OnDragEnter](#ondragenter)|Called by the framework when the cursor is first dragged into the tab control window.| -|[CMFCTabCtrl::OnDragOver](#ondragover)|Called by the framework during a drag operation when the mouse is moved over the drop target window. (Overrides [CMFCBaseTabCtrl::OnDragOver](../../mfc/reference/cmfcbasetabctrl-class.md#ondragover).)| -|[CMFCTabCtrl::OnShowTabDocumentsMenu](#onshowtabdocumentsmenu)|Displays a popup menu of tabbed windows, waits until the user selects a tab, and makes the selected tab the active tab.| -|`CMFCTabCtrl::PreTranslateMessage`|Translates window messages before they are dispatched to the [TranslateMessage](/windows/win32/api/winuser/nf-winuser-translatemessage) and [DispatchMessage](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides [CMFCBaseTabCtrl::PreTranslateMessage](../../mfc/reference/cmfcbasetabctrl-class.md#pretranslatemessage).)| -|`CMFCTabCtrl::RecalcLayout`|Recalculates the internal layout of the tab control. (Overrides [CMFCBaseTabCtrl::RecalcLayout](../../mfc/reference/cmfcbasetabctrl-class.md#recalclayout).)| -|[CMFCTabCtrl::SetActiveInMDITabGroup](#setactiveinmditabgroup)|Sets the current tab of a tab control as the active tab in an multiple document interface tab group.| -|[CMFCTabCtrl::SetActiveTab](#setactivetab)|Activates a tab. (Overrides [CMFCBaseTabCtrl::SetActiveTab](../../mfc/reference/cmfcbasetabctrl-class.md#setactivetab).)| -|[CMFCTabCtrl::SetActiveTabBoldFont](#setactivetabboldfont)|Enables or disables use of a bold font on active tabs.| -|[CMFCTabCtrl::SetDrawFrame](#setdrawframe)|Enables or disables drawing a frame rectangle around an embedded bar.| -|[CMFCTabCtrl::SetFlatFrame](#setflatframe)|Specifies whether to draw a flat or a 3D frame around the tab area.| -|[CMFCTabCtrl::SetImageList](#setimagelist)|Specifies an image list. (Overrides [CMFCBaseTabCtrl::SetImageList](../../mfc/reference/cmfcbasetabctrl-class.md#setimagelist).)| -|[CMFCTabCtrl::SetResizeMode](#setresizemode)|Specifies how the current tab control can be resized and then redisplays the control.| -|[CMFCTabCtrl::SetTabMaxWidth](#settabmaxwidth)|Specifies the maximum tab width in a tabbed window.| -|[CMFCTabCtrl::StopResize](#stopresize)|Terminates the current resize operation on the tab control.| -|`CMFCTabCtrl::SwapTabs`|Swaps a pair of tabs. (Overrides [CMFCBaseTabCtrl::SwapTabs](../../mfc/reference/cmfcbasetabctrl-class.md#swaptabs).)| -|[CMFCTabCtrl::SynchronizeScrollBar](#synchronizescrollbar)|Draws a horizontal scroll bar on a tab control that displays flat tabs.| +|[`CMFCTabCtrl::EnableActiveTabCloseButton`](#enableactivetabclosebutton)|Shows or hides a Close button ( **X**) on the active tab.| +|[`CMFCTabCtrl::EnableInPlaceEdit`](#enableinplaceedit)|Enables or disables editable tab labels. (Overrides [`CMFCBaseTabCtrl::EnableInPlaceEdit`](../../mfc/reference/cmfcbasetabctrl-class.md#enableinplaceedit).)| +|[`CMFCTabCtrl::EnableTabDocumentsMenu`](#enabletabdocumentsmenu)|Replaces two buttons that scroll the window tabs with a button that opens a menu of tabbed windows.| +|[`CMFCTabCtrl::EnsureVisible`](#ensurevisible)|Ensures that a tab is visible.| +|[`CMFCTabCtrl::GetDocumentIcon`](#getdocumenticon)|Retrieves the symbol that is associated with a tab in a popup menu of tabbed windows.| +|[`CMFCTabCtrl::GetFirstVisibleTabNum`](#getfirstvisibletabnum)|Retrieves the index of the first tab that is visible in the current tab control.| +|[`CMFCTabCtrl::GetResizeMode`](#getresizemode)|Retrieves a value that specifies how the current tab control can be resized.| +|[`CMFCTabCtrl::GetScrollBar`](#getscrollbar)|Retrieves a pointer to the scroll bar object that is associated with the tab control.| +|[`CMFCTabCtrl::GetTabArea`](#gettabarea)|Retrieves the bounding rectangle of the tab label area at the top or bottom of the tab control. (Overrides [`CMFCBaseTabCtrl::GetTabArea`](../../mfc/reference/cmfcbasetabctrl-class.md#gettabarea).)| +|`CMFCTabCtrl::GetTabFromPoint`|Retrieves the tab that contains a specified point. (Overrides [`CMFCBaseTabCtrl::GetTabFromPoint`](../../mfc/reference/cmfcbasetabctrl-class.md#gettabfrompoint).)| +|[`CMFCTabCtrl::GetTabMaxWidth`](#gettabmaxwidth)|Retrieves the maximum width of a tab.| +|[`CMFCTabCtrl::GetTabsHeight`](#gettabsheight)|Retrieves the height of the tab area of the current tab control.| +|[`CMFCTabCtrl::GetTabsRect`](#gettabsrect)|Retrieves a rectangle that bounds the tab area of the current tab control. (Overrides [`CMFCBaseTabCtrl::GetTabsRect`](../../mfc/reference/cmfcbasetabctrl-class.md#gettabsrect).)| +|`CMFCTabCtrl::GetThisClass`|Used by the framework to obtain a pointer to the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| +|[`CMFCTabCtrl::GetWndArea`](#getwndarea)|Retrieves the boundary of the client area of the current tab control.| +|[`CMFCTabCtrl::HideActiveWindowHorzScrollBar`](#hideactivewindowhorzscrollbar)|Hides the horizontal scroll bar, if any, of the active window.| +|[`CMFCTabCtrl::HideInactiveWindow`](#hideinactivewindow)|Specifies whether the framework is to display inactive tab control windows.| +|[`CMFCTabCtrl::HideNoTabs`](#hidenotabs)|Enables or disables drawing the tab area if there are no visible tabs.| +|[`CMFCTabCtrl::HideSingleTab`](#hidesingletab)|Enables or disables drawing a tab when there's a single tabbed window. (Overrides [`CMFCBaseTabCtrl::HideSingleTab`](../../mfc/reference/cmfcbasetabctrl-class.md#hidesingletab).)| +|[`CMFCTabCtrl::IsActiveInMDITabGroup`](#isactiveinmditabgroup)|Indicates whether the current tab of a tab control is the active tab in a multiple document interface tab group.| +|[`CMFCTabCtrl::IsActiveTabBoldFont`](#isactivetabboldfont)|Indicates whether the text of the active tab is displayed using a bold font.| +|[`CMFCTabCtrl::IsActiveTabCloseButton`](#isactivetabclosebutton)|Indicates whether the Close button ( **X**) is displayed on an active tab or the upper-right corner of the tab area.| +|[`CMFCTabCtrl::IsDrawFrame`](#isdrawframe)|Indicates whether the tabbed window draws a frame rectangle around embedded panes.| +|[`CMFCTabCtrl::IsFlatFrame`](#isflatframe)|Indicates whether the frame around the tab area is flat or 3D.| +|[`CMFCTabCtrl::IsFlatTab`](#isflattab)|Indicates whether the appearance of the tabs in the current tab control is flat or not.| +|[`CMFCTabCtrl::IsLeftRightRounded`](#isleftrightrounded)|Indicates whether the appearance of the left and right side of a tab in the current tab control is rounded.| +|[`CMFCTabCtrl::IsMDITabGroup`](#ismditabgroup)|Indicates whether the current tab control is contained in the client area of a multiple-document interface window.| +|[`CMFCTabCtrl::IsOneNoteStyle`](#isonenotestyle)|Indicates whether the current tab control is displayed in the style of Microsoft OneNote.| +|`CMFCTabCtrl::IsPtInTabArea`|Determines if a point is inside the tab area. (Overrides [`CMFCBaseTabCtrl::IsPtInTabArea`](../../mfc/reference/cmfcbasetabctrl-class.md#isptintabarea).)| +|[`CMFCTabCtrl::IsSharedScroll`](#issharedscroll)|Indicates whether the current tab control has a scroll bar that can scroll its tabs as a group.| +|[`CMFCTabCtrl::IsTabDocumentsMenu`](#istabdocumentsmenu)|Indicates whether the tab control displays scroll buttons or a button that displays a menu of tabbed windows.| +|[`CMFCTabCtrl::IsVS2005Style`](#isvs2005style)|Indicates whether tabs are displayed in the style of Visual Studio .NET 2005.| +|[`CMFCTabCtrl::ModifyTabStyle`](#modifytabstyle)|Specifies the appearance of tabs in the current tab control.| +|`CMFCTabCtrl::MoveTab`|Moves a tab to another tab position. (Overrides [`CMFCBaseTabCtrl::MoveTab`](../../mfc/reference/cmfcbasetabctrl-class.md#movetab).)| +|[`CMFCTabCtrl::OnDragEnter`](#ondragenter)|Called by the framework when the cursor is first dragged into the tab control window.| +|[`CMFCTabCtrl::OnDragOver`](#ondragover)|Called by the framework during a drag operation when the mouse is moved over the drop target window. (Overrides [`CMFCBaseTabCtrl::OnDragOver`](../../mfc/reference/cmfcbasetabctrl-class.md#ondragover).)| +|[`CMFCTabCtrl::OnShowTabDocumentsMenu`](#onshowtabdocumentsmenu)|Displays a popup menu of tabbed windows, waits until the user selects a tab, and makes the selected tab the active tab.| +|`CMFCTabCtrl::PreTranslateMessage`|Translates window messages before they're dispatched to the [`TranslateMessage`](/windows/win32/api/winuser/nf-winuser-translatemessage) and [`DispatchMessage`](/windows/win32/api/winuser/nf-winuser-dispatchmessage) Windows functions. (Overrides [`CMFCBaseTabCtrl::PreTranslateMessage`](../../mfc/reference/cmfcbasetabctrl-class.md#pretranslatemessage).)| +|`CMFCTabCtrl::RecalcLayout`|Recalculates the internal layout of the tab control. (Overrides [`CMFCBaseTabCtrl::RecalcLayout`](../../mfc/reference/cmfcbasetabctrl-class.md#recalclayout).)| +|[`CMFCTabCtrl::SetActiveInMDITabGroup`](#setactiveinmditabgroup)|Sets the current tab of a tab control as the active tab in a multiple document interface tab group.| +|[`CMFCTabCtrl::SetActiveTab`](#setactivetab)|Activates a tab. (Overrides [`CMFCBaseTabCtrl::SetActiveTab`](../../mfc/reference/cmfcbasetabctrl-class.md#setactivetab).)| +|[`CMFCTabCtrl::SetActiveTabBoldFont`](#setactivetabboldfont)|Enables or disables use of a bold font on active tabs.| +|[`CMFCTabCtrl::SetDrawFrame`](#setdrawframe)|Enables or disables drawing a frame rectangle around an embedded bar.| +|[`CMFCTabCtrl::SetFlatFrame`](#setflatframe)|Specifies whether to draw a flat or a 3D frame around the tab area.| +|[`CMFCTabCtrl::SetImageList`](#setimagelist)|Specifies an image list. (Overrides [`CMFCBaseTabCtrl::SetImageList`](../../mfc/reference/cmfcbasetabctrl-class.md#setimagelist).)| +|[`CMFCTabCtrl::SetResizeMode`](#setresizemode)|Specifies how the current tab control can be resized and then redisplays the control.| +|[`CMFCTabCtrl::SetTabMaxWidth`](#settabmaxwidth)|Specifies the maximum tab width in a tabbed window.| +|[`CMFCTabCtrl::StopResize`](#stopresize)|Terminates the current resize operation on the tab control.| +|`CMFCTabCtrl::SwapTabs`|Swaps a pair of tabs. (Overrides [`CMFCBaseTabCtrl::SwapTabs`](../../mfc/reference/cmfcbasetabctrl-class.md#swaptabs).)| +|[`CMFCTabCtrl::SynchronizeScrollBar`](#synchronizescrollbar)|Draws a horizontal scroll bar on a tab control that displays flat tabs.| ### Data Members |Name|Description| |----------|-----------------| -|[CMFCTabCtrl::m_bEnableActivate](#m_benableactivate)|Prevents the active view from losing focus when a new tab is inserted and enabled.| +|[`CMFCTabCtrl::m_bEnableActivate`](#m_benableactivate)|Prevents the active view from losing focus when a new tab is inserted and enabled.| ## Remarks @@ -108,33 +107,33 @@ The `CMFCTabCtrl` class supports: - Detachable tabbed windows. -The `CMFCTabCtrl` class can be used with a dialog box, but is intended for applications that use docking control bars like Microsoft Excel and Visual Studio. For more information, see [CDockablePane Class](../../mfc/reference/cdockablepane-class.md). +The `CMFCTabCtrl` class can be used with a dialog box, but is intended for applications that use docking control bars like Microsoft Excel and Visual Studio. For more information, see [`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md). Follow these steps to add a resizable, docking tab control in your application: -1. Create an instance of [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md). +1. Create an instance of [`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md). -1. Call [CDockablePane::Create](../../mfc/reference/cdockablepane-class.md#create). +1. Call [`CDockablePane::Create`](../../mfc/reference/cdockablepane-class.md#create). -1. Use [CBaseTabbedPane::AddTab](../../mfc/reference/cbasetabbedpane-class.md#addtab) or [CMFCBaseTabCtrl::InsertTab](../../mfc/reference/cmfcbasetabctrl-class.md#inserttab) to add new tabs. +1. Use [`CBaseTabbedPane::AddTab`](../../mfc/reference/cbasetabbedpane-class.md#addtab) or [`CMFCBaseTabCtrl::InsertTab`](../../mfc/reference/cmfcbasetabctrl-class.md#inserttab) to add new tabs. -1. Call [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking) so that the current docking tab control can dock at the main frame window. +1. Call [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking) so that the current docking tab control can dock at the main frame window. -1. Call [CFrameWndEx::DockPane](../../mfc/reference/cframewndex-class.md#dockpane) to dock the tabbed window at the main frame. +1. Call [`CFrameWndEx::DockPane`](../../mfc/reference/cframewndex-class.md#dockpane) to dock the tabbed window at the main frame. -For an example of how to create a tabbed window as a docking control bar, see [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md). To use `CMFCTabCtrl` as a non-docking control, create a `CMFCTabCtrl` object and then call [CMFCTabCtrl::Create](#create). +For an example of how to create a tabbed window as a docking control bar, see [`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md). To use `CMFCTabCtrl` as a non-docking control, create a `CMFCTabCtrl` object and then call [`CMFCTabCtrl::Create`](#create). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CMFCBaseTabCtrl](../../mfc/reference/cmfcbasetabctrl-class.md) +[`CMFCBaseTabCtrl`](../../mfc/reference/cmfcbasetabctrl-class.md) -[CMFCTabCtrl](../../mfc/reference/cmfctabctrl-class.md) +[`CMFCTabCtrl`](../../mfc/reference/cmfctabctrl-class.md) ## Example @@ -145,9 +144,9 @@ The following example demonstrates how to use various methods in the `CMFCTabCtr ## Requirements -**Header:** afxtabctrl.h +**Header:** `afxtabctrl.h` -## CMFCTabCtrl::ActivateMDITab +## `CMFCTabCtrl::ActivateMDITab` Displays the specified tab of the current tab control and sets the focus on that tab. @@ -157,12 +156,12 @@ void ActivateMDITab(int nTab = -1); ### Parameters -*nTab*
+*`nTab`*\ [in] The zero-based index of a tab to display, or -1 to specify the currently active tab. -## CMFCTabCtrl::AllowDestroyEmptyTabbedPane +## `CMFCTabCtrl::AllowDestroyEmptyTabbedPane` -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. +For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ``` virtual BOOL AllowDestroyEmptyTabbedPane() const; @@ -170,11 +169,11 @@ virtual BOOL AllowDestroyEmptyTabbedPane() const; ### Return Value -Always TRUE. +Always `TRUE`. ### Remarks -## CMFCTabCtrl::AutoSizeWindow +## `CMFCTabCtrl::AutoSizeWindow` Specifies whether the framework is to resize the client area of all tab control windows when a user interface element of the tab control changes. @@ -184,12 +183,12 @@ void AutoSizeWindow(BOOL bAutoSize = TRUE); ### Parameters -*bAutoSize*
-[in] TRUE to automatically resize tab control windows; otherwise, FALSE. The default value is TRUE. +*`bAutoSize`*\ +[in] `TRUE` to automatically resize tab control windows; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::Create +## `CMFCTabCtrl::Create` Creates the tab control and attaches it to the `CMFCTabCtrl` object. @@ -205,48 +204,48 @@ BOOL Create( ### Parameters -*style*
+*`style`*\ [in] The style of the tab control. For more information, see Remarks. -*rect*
+*`rect`*\ [in] A rectangle that bounds the tab control. -*pParentWnd*
-[in] A pointer to a parent window. Must not be NULL. +*`pParentWnd`*\ +[in] A pointer to a parent window. Must not be `NULL`. -*nID*
+*`nID`*\ [in] The ID of the tab control. -*location*
-[in] The location of tabs. The default value is LOCATION_BOTTOM. For more information, see Remarks. +*`location`*\ +[in] The location of tabs. The default value is `LOCATION_BOTTOM`. For more information, see [Remarks](#create-remarks). -*bCloseBtn*
-[in] TRUE to display a close button on the tab; otherwise, FALSE. The default value is FALSE. +*`bCloseBtn`*\ +[in] `TRUE` to display a close button on the tab; otherwise, `FALSE`. The default value is `FALSE`. ### Return Value -TRUE if successful; otherwise, FALSE. +`TRUE` if successful; otherwise, `FALSE`. -### Remarks +### Remarks -The following table describes the values you can specify for the *style* parameter. +The following table describes the values you can specify for the *`style`* parameter. |Style|Description| |-----------|-----------------| -|STYLE_3D|Creates a tab control with a three-dimensional appearance.| -|STYLE_FLAT|Creates a tab control with flat tabs.| -|STYLE_FLAT_SHARED_HORZ_SCROLL|Creates a tab control with flat tabs and a scroll bar that can scroll the tabs if they are clipped by a parent window.| -|STYLE_3D_ONENOTE|Creates a tab control in the style of Microsoft OneNote.| -|STYLE_3D_VS2005|Creates a tab control in the style of Microsoft Visual Studio 2005.| -|STYLE_3D_ROUNDED|Creates a tab control with rounded tabs in the style of Microsoft Visual Studio 2005.| -|STYLE_3D_ROUNDED_SCROLL|Creates a tab control with rounded tabs and scroll buttons in the style of Microsoft Visual Studio 2005.| +|`STYLE_3D`|Creates a tab control with a three-dimensional appearance.| +|`STYLE_FLAT`|Creates a tab control with flat tabs.| +|`STYLE_FLAT_SHARED_HORZ_SCROLL`|Creates a tab control with flat tabs and a scroll bar that can scroll the tabs if they're clipped by a parent window.| +|`STYLE_3D_ONENOTE`|Creates a tab control in the style of Microsoft OneNote.| +|`STYLE_3D_VS2005`|Creates a tab control in the style of Microsoft Visual Studio 2005.| +|`STYLE_3D_ROUNDED`|Creates a tab control with rounded tabs in the style of Microsoft Visual Studio 2005.| +|`STYLE_3D_ROUNDED_SCROLL`|Creates a tab control with rounded tabs and scroll buttons in the style of Microsoft Visual Studio 2005.| -The following table lists the values you can specify for the *location* parameter. +The following table lists the values you can specify for the *`location`* parameter. |Location|Description| |--------------|-----------------| -|LOCATION_BOTTOM|Tabs are located at the bottom of the tab control.| -|LOCATION_TOP|Tabs are located at the top of the tab control.| +|`LOCATION_BOTTOM`|Tabs are located at the bottom of the tab control.| +|`LOCATION_TOP`|Tabs are located at the top of the tab control.| ### Example @@ -255,7 +254,7 @@ The following example demonstrates how to use the `Create` method in the `CMFCTa [!code-cpp[NVC_MFC_StateCollection#1](../../mfc/reference/codesnippet/cpp/cmfctabctrl-class_1.h)] [!code-cpp[NVC_MFC_StateCollection#2](../../mfc/reference/codesnippet/cpp/cmfctabctrl-class_3.cpp)] -## CMFCTabCtrl::CalcRectEdit +## `CMFCTabCtrl::CalcRectEdit` Deflates the size of the specified tab area. @@ -265,16 +264,16 @@ virtual void CalcRectEdit(CRect& rectEdit); ### Parameters -*rectEdit*
+*`rectEdit`*\ [in] A rectangle that specifies the area of a tab. ### Remarks This method is called when you change the label of a tab. This method deflates the left and right sides of the specified rectangle by one-half the current tab height, and deflates the top and bottom by one unit. -## CMFCTabCtrl::EnableActiveTabCloseButton +## `CMFCTabCtrl::EnableActiveTabCloseButton` -Shows or hides a Close button ( **X**) on the active tab. +Shows or hides a **Close** button ( **`X`**) on the active tab. ```cpp void EnableActiveTabCloseButton(BOOL bEnable=TRUE); @@ -282,10 +281,10 @@ void EnableActiveTabCloseButton(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to display the Close button on the active tab; FALSE to display the Close button on the upper-right corner of the tab area. The default value is TRUE. +*`bEnable`*\ +[in] `TRUE` to display the **Close** button on the active tab; `FALSE` to display the **Close** button on the upper-right corner of the tab area. The default value is `TRUE`. -## CMFCTabCtrl::EnableInPlaceEdit +## `CMFCTabCtrl::EnableInPlaceEdit` Enables or disables editable tab labels. @@ -295,12 +294,12 @@ virtual void EnableInPlaceEdit(BOOL bEnable); ### Parameters -*bEnable*
-[in] TRUE to enable editable tab labels; FALSE to disable editable tab labels. +*`bEnable`*\ +[in] `TRUE` to enable editable tab labels; `FALSE` to disable editable tab labels. ### Remarks -## CMFCTabCtrl::EnableTabDocumentsMenu +## `CMFCTabCtrl::EnableTabDocumentsMenu` Toggles between a user interface that uses two buttons to scroll the window tabs and an interface that displays a pop-up menu of tabbed windows. @@ -310,14 +309,14 @@ void EnableTabDocumentsMenu(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to display a pop-up menu of tabbed window labels; FALSE to display forward and backward scroll buttons. The default value is TRUE. +*`bEnable`*\ +[in] `TRUE` to display a pop-up menu of tabbed window labels; `FALSE` to display forward and backward scroll buttons. The default value is `TRUE`. ### Remarks When the user clicks a tab label, the framework displays the corresponding tabbed window. If the tab label is visible, the tabbed window is opened without changing its position. If the user selects a document from the pop-up menu and the corresponding tabbed window is off screen, the tabbed window becomes the first tab. -## CMFCTabCtrl::EnsureVisible +## `CMFCTabCtrl::EnsureVisible` Ensures that a tab is visible. @@ -327,18 +326,18 @@ virtual BOOL EnsureVisible(int iTab); ### Parameters -*iTab*
+*`iTab`*\ [in] The zero-based index of a tab. ### Return Value -TRUE if it is successful; FALSE if the *iTab* parameter index is invalid. +`TRUE` if it's successful; `FALSE` if the *`iTab`* parameter index is invalid. ### Remarks -Use this method to guarantee that the specified tab is visible. The tab control will scroll if it is required. +Use this method to guarantee that the specified tab is visible. The tab control will scroll if it's required. -## CMFCTabCtrl::GetDocumentIcon +## `CMFCTabCtrl::GetDocumentIcon` Retrieves the image that is associated with a tab in a pop-up menu of tabbed windows. @@ -348,14 +347,14 @@ static HICON __stdcall GetDocumentIcon(UINT nCmdID); ### Parameters -*nCmdID*
+*`nCmdID`*\ [in] The command ID of a tab in a pop-up menu of tabbed windows. ### Return Value The handle of a bitmap image. -## CMFCTabCtrl::GetFirstVisibleTabNum +## `CMFCTabCtrl::GetFirstVisibleTabNum` Retrieves the index of the first tab that is visible in the current tab control. @@ -369,9 +368,9 @@ The zero-based index of a tab in the tab control. ### Remarks -Use this method only when the tab control is displayed in the style of Microsoft OneNote. Use the [CMFCTabCtrl::IsOneNoteStyle](#isonenotestyle) method to determine the style. +Use this method only when the tab control is displayed in the style of Microsoft OneNote. Use the [`CMFCTabCtrl::IsOneNoteStyle`](#isonenotestyle) method to determine the style. -## CMFCTabCtrl::GetResizeMode +## `CMFCTabCtrl::GetResizeMode` Retrieves a value that specifies how the current tab control can be resized. @@ -381,9 +380,9 @@ ResizeMode GetResizeMode() const; ### Return Value -One of the `CMFCTabCtrl::ResizeMode` enumeration values that specifies how the tab control can be resized. For a list of possible values, see the Remarks section of the [CMFCTabCtrl::SetResizeMode](#setresizemode) method. +One of the `CMFCTabCtrl::ResizeMode` enumeration values that specifies how the tab control can be resized. For a list of possible values, see the Remarks section of the [`CMFCTabCtrl::SetResizeMode`](#setresizemode) method. -## CMFCTabCtrl::GetScrollBar +## `CMFCTabCtrl::GetScrollBar` Retrieves a pointer to the scroll bar object that is associated with the tab control. @@ -393,13 +392,13 @@ CScrollBar* GetScrollBar(); ### Return Value -A pointer to a scrollbar object, or a NULL if the tab control was not created by using the STYLE_FLAT_SHARED_HORZ_SCROLL style. +A pointer to a scrollbar object, or a `NULL` if the tab control wasn't created by using the `STYLE_FLAT_SHARED_HORZ_SCROLL` style. ### Remarks -Use this method to access the tab control's embedded scroll bar. A scroll bar object is created only when the tab control has the STYLE_FLAT_SHARED_HORZ_SCROLL style. +Use this method to access the tab control's embedded scroll bar. A scroll bar object is created only when the tab control has the `STYLE_FLAT_SHARED_HORZ_SCROLL` style. -## CMFCTabCtrl::GetTabArea +## `CMFCTabCtrl::GetTabArea` Retrieves the bounding rectangle of the tab label area at the top or bottom of the tab control. @@ -411,17 +410,17 @@ void GetTabArea( ### Parameters -*rectTabAreaTop*
+*`rectTabAreaTop`*\ [out] When this method returns, this reference contains a rectangle that bounds the top tab label area. The rectangle is in client coordinates. This reference is empty if no tab label area exists at the top of the tab control. -*rectTabAreaBottom*
+*`rectTabAreaBottom`*\ [out] When this method returns, this reference contains a rectangle that bounds the bottom tab label area. The rectangle is in client coordinates. This reference is empty if no tab label area exists at the bottom of the tab control. ### Remarks Use this method to determine the size and position of the tab area in the tabbed window. -## CMFCTabCtrl::GetTabMaxWidth +## `CMFCTabCtrl::GetTabMaxWidth` Retrieves the maximum width of a tab. @@ -437,7 +436,7 @@ Maximum width of a tab, in pixels. If the return value is 0, the tab width is un Use the [CMFCTabCtrl::SetTabMaxWidth](#settabmaxwidth) method to set maximum tab width. -## CMFCTabCtrl::GetTabsHeight +## `CMFCTabCtrl::GetTabsHeight` Retrieves the height of the tab area of the current tab control. @@ -449,7 +448,7 @@ virtual int GetTabsHeight() const; The height of the tab area if any tab is visible, or zero if no tab is visible. -## CMFCTabCtrl::GetTabsRect +## `CMFCTabCtrl::GetTabsRect` Retrieves a rectangle that bounds the tab area of the current tab control. @@ -459,10 +458,10 @@ virtual void GetTabsRect(CRect& rect) const; ### Parameters -*rect*
-[out] When this method returns, the *rect* parameter contains a rectangle that bounds the tab area. +*`rect`*\ +[out] When this method returns, the *`rect`* parameter contains a rectangle that bounds the tab area. -## CMFCTabCtrl::GetWndArea +## `CMFCTabCtrl::GetWndArea` Retrieves the boundary of the client area of the current tab control. @@ -472,12 +471,12 @@ void GetWndArea(CRect& rect) const; ### Parameters -*rect*
+*`rect`*\ [in, out] When this method returns, this parameter contains a rectangle that bounds the current tab control. ### Remarks -## CMFCTabCtrl::HideActiveWindowHorzScrollBar +## `CMFCTabCtrl::HideActiveWindowHorzScrollBar` Hides the horizontal scroll bar, if any, in the active window. @@ -489,7 +488,7 @@ void HideActiveWindowHorzScrollBar(); Use this method to prevent the tab control from blinking when the user switches between tab control pages. -## CMFCTabCtrl::HideInactiveWindow +## `CMFCTabCtrl::HideInactiveWindow` Specifies whether the framework displays inactive tab control windows. @@ -499,12 +498,12 @@ void HideInactiveWindow(BOOL bHide = TRUE); ### Parameters -*bHide*
-[in] TRUE not to display an inactive window; FALSE to display an inactive window. The default value is TRUE. +*`bHide`*\ +[in] `TRUE` not to display an inactive window; `FALSE` to display an inactive window. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::HideNoTabs +## `CMFCTabCtrl::HideNoTabs` Enables or disables drawing of the tab area if there are no visible tabs. @@ -514,14 +513,14 @@ void HideNoTabs(BOOL bHide=TRUE); ### Parameters -*bHide*
-[in] TRUE to enable drawing the tab area; FALSE to disable drawing. The default value is TRUE. +*`bHide`*\ +[in] `TRUE` to enable drawing the tab area; `FALSE` to disable drawing. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::HideSingleTab +## `CMFCTabCtrl::HideSingleTab` -Enables or disables tab drawing if there is a single tabbed window. +Enables or disables tab drawing if there's a single tabbed window. ``` virtual void HideSingleTab(BOOL bHide=TRUE); @@ -529,12 +528,12 @@ virtual void HideSingleTab(BOOL bHide=TRUE); ### Parameters -*bHide*
-[in] TRUE to not draw a tab for a single tabbed window; FALSE to draw a single tab. The default value is TRUE. +*`bHide`*\ +[in] `TRUE` to not draw a tab for a single tabbed window; `FALSE` to draw a single tab. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::IsActiveInMDITabGroup +## `CMFCTabCtrl::IsActiveInMDITabGroup` Indicates whether the current tab of a tab control is the active tab in a multiple document interface tab group. @@ -544,13 +543,13 @@ BOOL IsActiveInMDITabGroup() const; ### Return Value -TRUE if the current tab of a tab control is the active tab in an MDI tab group; otherwise, FALSE. +`TRUE` if the current tab of a tab control is the active tab in an MDI tab group; otherwise, `FALSE`. ### Remarks You can organize multiple document windows into either vertical or horizontal tab groups and easily shuffle documents from one tab group to another. -## CMFCTabCtrl::IsActiveTabBoldFont +## `CMFCTabCtrl::IsActiveTabBoldFont` Indicates whether the text of the active tab is displayed using a bold font. @@ -560,15 +559,15 @@ BOOL IsActiveTabBoldFont() const; ### Return Value -TRUE if the active tab is displayed using the bold font; otherwise, FALSE. +`TRUE` if the active tab is displayed using the bold font; otherwise, `FALSE`. ### Remarks -Use the [CMFCTabCtrl::SetActiveTabBoldFont](#setactivetabboldfont) method to change the active tab font. +Use the [`CMFCTabCtrl::SetActiveTabBoldFont`](#setactivetabboldfont) method to change the active tab font. -## CMFCTabCtrl::IsActiveTabCloseButton +## `CMFCTabCtrl::IsActiveTabCloseButton` -Indicates whether the Close button ( **X**) is displayed on an active tab or on the upper-right corner of the tab area. +Indicates whether the **Close** button ( **X**) is displayed on an active tab or on the upper-right corner of the tab area. ``` virtual BOOL IsActiveTabCloseButton() const; @@ -576,11 +575,11 @@ virtual BOOL IsActiveTabCloseButton() const; ### Return Value -TRUE if the Close button is displayed on the active tab; FALSE if the Close button is displayed on the upper-right corner of the tab area. +`TRUE` if the **Close** button is displayed on the active tab; `FALSE` if the **Close** button is displayed on the upper-right corner of the tab area. ### Remarks -## CMFCTabCtrl::IsDrawFrame +## `CMFCTabCtrl::IsDrawFrame` Indicates whether the tabbed window draws a frame rectangle around embedded panes. @@ -590,13 +589,13 @@ BOOL IsDrawFrame() const; ### Return Value -TRUE if a frame rectangle is drawn; otherwise, FALSE. +`TRUE` if a frame rectangle is drawn; otherwise, `FALSE`. ### Remarks -Use the [CMFCTabCtrl::SetDrawFrame](#setdrawframe) method to enable or disable drawing a frame rectangle. +Use the [`CMFCTabCtrl::SetDrawFrame`](#setdrawframe) method to enable or disable drawing a frame rectangle. -## CMFCTabCtrl::IsFlatFrame +## `CMFCTabCtrl::IsFlatFrame` Indicates whether the frame around the tab area is flat or 3D. @@ -606,13 +605,13 @@ BOOL IsFlatFrame() const; ### Return Value -TRUE if the frame around the tab area is flat; FALSE if the frame is three-dimensional. +`TRUE` if the frame around the tab area is flat; `FALSE` if the frame is three-dimensional. ### Remarks -Use the [CMFCTabCtrl::SetFlatFrame](#setflatframe) method to change how the frame is drawn. +Use the [`CMFCTabCtrl::SetFlatFrame`](#setflatframe) method to change how the frame is drawn. -## CMFCTabCtrl::IsFlatTab +## `CMFCTabCtrl::IsFlatTab` Indicates whether the appearance of the tabs in the current tab control is flat or not. @@ -622,9 +621,9 @@ virtual BOOL IsFlatTab() const; ### Return Value -TRUE if the appearance of the tabs in the current tab control is flat; otherwise, FALSE. +`TRUE` if the appearance of the tabs in the current tab control is flat; otherwise, `FALSE`. -## CMFCTabCtrl::IsLeftRightRounded +## `CMFCTabCtrl::IsLeftRightRounded` Indicates whether the appearance of the left and right side of a tab in the current tab control is rounded. @@ -634,9 +633,9 @@ virtual BOOL IsLeftRightRounded() const; ### Return Value -TRUE if the sides of each tab is rounded; otherwise, FALSE. +`TRUE` if the sides of each tab are rounded; otherwise, `FALSE`. -## CMFCTabCtrl::IsMDITabGroup +## `CMFCTabCtrl::IsMDITabGroup` Indicates whether the current tab control is contained in the client area of a multiple-document interface window. @@ -646,9 +645,9 @@ virtual BOOL IsMDITabGroup() const; ### Return Value -TRUE if the current tab control is in an MDI client area window; otherwise, FALSE. +`TRUE` if the current tab control is in an MDI client area window; otherwise, `FALSE`. -## CMFCTabCtrl::IsOneNoteStyle +## `CMFCTabCtrl::IsOneNoteStyle` Indicates whether the current tab control is displayed in the style of Microsoft OneNote. @@ -658,9 +657,9 @@ virtual BOOL IsOneNoteStyle() const; ### Return Value -TRUE if the tab control is displayed in the style of Microsoft OneNote; otherwise, FALSE. +`TRUE` if the tab control is displayed in the style of Microsoft OneNote; otherwise, `FALSE`. -## CMFCTabCtrl::IsSharedScroll +## `CMFCTabCtrl::IsSharedScroll` Indicates whether the current tab control has a scroll bar that can scroll its tabs as a group. @@ -670,13 +669,13 @@ BOOL IsSharedScroll() const; ### Return Value -TRUE if the tab control has a shared scroll bar; otherwise, FALSE. +`TRUE` if the tab control has a shared scroll bar; otherwise, `FALSE`. ### Remarks -This method returns TRUE if the *style* parameter of the [CMFCTabCtrl::Create](#create) method is STYLE_FLAT_SHARED_HORZ_SCROLL. +This method returns `TRUE` if the *`style`* parameter of the [`CMFCTabCtrl::Create`](#create) method is `STYLE_FLAT_SHARED_HORZ_SCROLL`. -## CMFCTabCtrl::IsTabDocumentsMenu +## `CMFCTabCtrl::IsTabDocumentsMenu` Indicates whether the tab control displays scroll buttons or a button that displays a menu of tabbed windows. @@ -686,13 +685,13 @@ BOOL IsTabDocumentsMenu() const; ### Return Value -TRUE if tabbed windows are scrolled using a popup menu of tabbed window labels; FALSE if tabbed windows are scrolled using forward and backward scroll buttons. +`TRUE` if tabbed windows are scrolled using a popup menu of tabbed window labels; `FALSE` if tabbed windows are scrolled using forward and backward scroll buttons. ### Remarks -Use the [CMFCTabCtrl::EnableTabDocumentsMenu](#enabletabdocumentsmenu) method to specify the method of scrolling tabbed windows. +Use the [`CMFCTabCtrl::EnableTabDocumentsMenu`](#enabletabdocumentsmenu) method to specify the method of scrolling tabbed windows. -## CMFCTabCtrl::IsVS2005Style +## `CMFCTabCtrl::IsVS2005Style` Indicates whether tabs are drawn using the style of Visual Studio 2005. @@ -702,13 +701,13 @@ virtual BOOL IsVS2005Style() const; ### Return Value -TRUE if tabs are drawn using the style of Visual Studio 2005; otherwise, FALSE. +`TRUE` if tabs are drawn using the style of Visual Studio 2005; otherwise, `FALSE`. ### Remarks -Use the *style* parameter of the [CMFCTabCtrl::Create](#create) method to specify how tabs are drawn. +Use the *`style`* parameter of the [`CMFCTabCtrl::Create`](#create) method to specify how tabs are drawn. -## CMFCTabCtrl::m_bEnableActivate +## `CMFCTabCtrl::m_bEnableActivate` Prevents the active view from losing focus when a new tab is inserted and enabled. @@ -718,9 +717,9 @@ static BOOL m_bEnableActivate; ### Remarks -The focus is usually taken by a new tabbed window when the tab is inserted and made active. Set the `CMFCTabCtrl::m_bEnableActivate` member variable to FALSE to retain the original focus. The default value is TRUE. +The focus is usually taken by a new tabbed window when the tab is inserted and made active. Set the `CMFCTabCtrl::m_bEnableActivate` member variable to `FALSE` to retain the original focus. The default value is `TRUE`. -## CMFCTabCtrl::ModifyTabStyle +## `CMFCTabCtrl::ModifyTabStyle` Specifies the appearance of tabs in the current tab control. @@ -730,29 +729,29 @@ BOOL ModifyTabStyle(Style style); ### Parameters -*style*
-[in] One of the enumeration values that specifies the appearance of the tab control. For more information, see the table in Remarks. +*`style`*\ +[in] One of the enumeration values that specifies the appearance of the tab control. For more information, see the table in [Remarks](#modifytabstyle-remarks). ### Return Value -Always TRUE. +Always `TRUE`. -### Remarks +### Remarks -The value of the *style* parameter can be one of the following `CMFCTabCtrl::Style` enumerations. +The value of the *`style`* parameter can be one of the following `CMFCTabCtrl::Style` enumerations. |Name|Description| |----------|-----------------| -|STYLE_3D|Displays three-dimensional, rectangular tabs that have round corners.| -|STYLE_3D_ONENOTE|Displays three-dimensional tabs that have one vertical side and one slanted side and that have rounded corners.| -|STYLE_3D_ROUNDED|Displays three-dimensional tabs that have slanted sides and rounded corners.| -|STYLE_3D_ROUNDED_SCROLL|Displays three-dimensional tabs that have slanted sides and rounded corners. If there are more tabs than can be displayed at the same time, the framework displays a drop-down arrow and a menu of tabs to make active.| -|STYLE_3D_SCROLLED|Displays three-dimensional, rectangular tabs. If there are more tabs than can be displayed at the same time, the framework displays a drop-down arrow and a menu of tabs to make active.| -|STYLE_3D_VS2005|Displays three-dimensional, rounded tabs that have one slanted side and one vertical side.| -|STYLE_FLAT|Displays two-dimensional tabs that have slanted left and right sides.| -|STYLE_FLAT_SHARED_HORZ_SCROLL|Displays two-dimensional tabs. If there are more tabs than can be displayed at the same time, the framework displays scroll arrows at the ends of the tab area.| +|`STYLE_3D`|Displays three-dimensional, rectangular tabs that have round corners.| +|`STYLE_3D_ONENOTE`|Displays three-dimensional tabs that have one vertical side and one slanted side and that have rounded corners.| +|`STYLE_3D_ROUNDED`|Displays three-dimensional tabs that have slanted sides and rounded corners.| +|`STYLE_3D_ROUNDED_SCROLL`|Displays three-dimensional tabs that have slanted sides and rounded corners. If there are more tabs than can be displayed at the same time, the framework displays a drop-down arrow and a menu of tabs to make active.| +|`STYLE_3D_SCROLLED`|Displays three-dimensional, rectangular tabs. If there are more tabs than can be displayed at the same time, the framework displays a drop-down arrow and a menu of tabs to make active.| +|`STYLE_3D_VS2005`|Displays three-dimensional, rounded tabs that have one slanted side and one vertical side.| +|`STYLE_FLAT`|Displays two-dimensional tabs that have slanted left and right sides.| +|`STYLE_FLAT_SHARED_HORZ_SCROLL`|Displays two-dimensional tabs. If there are more tabs than can be displayed at the same time, the framework displays scroll arrows at the ends of the tab area.| -## CMFCTabCtrl::OnDragEnter +## `CMFCTabCtrl::OnDragEnter` Called by the framework during a drag-and-drop operation when the cursor first enters the window of the current tab control. @@ -765,26 +764,26 @@ virtual DROPEFFECT OnDragEnter( ### Parameters -*pDataObject*
+*`pDataObject`*\ [in] Points to a data object that contains data that the user drags. -*dwKeyState*
-[in] Contains the state of the modifier keys. This parameter is a bitwise combination (OR) of the following values: MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. For more information, see the **Message Parameters** section of [About Mouse Input](/windows/win32/inputdev/about-mouse-input). +*`dwKeyState`*\ +[in] Contains the state of the modifier keys. This parameter is a bitwise combination "or" (`|`) of the following values: `MK_CONTROL`, `MK_SHIFT`, `MK_ALT`, `MK_LBUTTON`, `MK_MBUTTON`, and `MK_RBUTTON`. For more information, see the **Message Parameters** section of [About Mouse Input](/windows/win32/inputdev/about-mouse-input#message-parameters). -*point*
+*`point`*\ [in] Contains the current location of the cursor in client coordinates. ### Return Value -Always DROPEFFECT_NONE, which means that the drop target cannot accept the data. +Always `DROPEFFECT_NONE`, which means that the drop target can't accept the data. ### Remarks Use this method to support a drag-and-drop operation. Override this method to implement your own custom behavior. -By default, this method only calls `CMFCTabCtrl::OnDragOver`, which always returns DROPEFFECT_NONE. +By default, this method only calls `CMFCTabCtrl::OnDragOver`, which always returns `DROPEFFECT_NONE`. -## CMFCTabCtrl::OnDragOver +## `CMFCTabCtrl::OnDragOver` Called by the framework during a drag operation when the mouse is moved over the drop target window. @@ -797,24 +796,24 @@ virtual DROPEFFECT OnDragOver( ### Parameters -*pDataObject*
-[in] Pointer to a [COleDataObject](../../mfc/reference/coledataobject-class.md) object that is being dragged over the drop target. +*`pDataObject`*\ +[in] Pointer to a [`COleDataObject`](../../mfc/reference/coledataobject-class.md) object that is being dragged over the drop target. -*dwKeyState*
-[in] The state of the modifier keys, which is a bitwise combination (OR) of MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. For more information, see "Message Parameters" in [About Mouse Input](/windows/win32/inputdev/about-mouse-input). +*`dwKeyState`*\ +[in] The state of the modifier keys, which is a bitwise combination "or" (`|`) of `MK_CONTROL`, `MK_SHIFT`, `MK_ALT`, `MK_LBUTTON`, `MK_MBUTTON`, and `MK_RBUTTON`. For more information, see "Message Parameters" in [About Mouse Input](/windows/win32/inputdev/about-mouse-input#message-parameters). -*point*
+*`point`*\ [in] The current mouse position. ### Return Value -Always DROPEFFECT_NONE. +Always `DROPEFFECT_NONE`. ### Remarks -Override this method with your custom implementation. For more information, see the [CView::OnDragOver](../../mfc/reference/cview-class.md#ondragover) method. +Override this method with your custom implementation. For more information, see the [`CView::OnDragOver`](../../mfc/reference/cview-class.md#ondragover) method. -## CMFCTabCtrl::OnShowTabDocumentsMenu +## `CMFCTabCtrl::OnShowTabDocumentsMenu` Displays a pop-up menu of tabbed windows, waits until the user selects a tab, and makes the selected tab the active tab. @@ -824,12 +823,12 @@ virtual void OnShowTabDocumentsMenu(CPoint point); ### Parameters -*point*
+*`point`*\ [in] The coordinates of where to display the pop-up menu. ### Remarks -## CMFCTabCtrl::SetActiveInMDITabGroup +## `CMFCTabCtrl::SetActiveInMDITabGroup` Sets the current tab of a tab control as the active tab in a multiple document interface tab group. @@ -839,14 +838,14 @@ void SetActiveInMDITabGroup(BOOL bActive); ### Parameters -*bActive*
-[in] TRUE to make the current tab the active tab; FALSE to make the current tab inactive. +*`bActive`*\ +[in] `TRUE` to make the current tab the active tab; `FALSE` to make the current tab inactive. ### Remarks You can organize multiple document windows into either vertical or horizontal tab groups and easily shuffle documents from one tab group to another. -## CMFCTabCtrl::SetActiveTab +## `CMFCTabCtrl::SetActiveTab` Activates a tab. @@ -856,20 +855,20 @@ virtual BOOL SetActiveTab(int iTab); ### Parameters -*iTab*
+*`iTab`*\ [in] Specifies the zero-based index of the tab to activate. ### Return Value -TRUE if the specified tab was made active; FALSE if the specified *iTab* parameter value is invalid. +`TRUE` if the specified tab was made active; `FALSE` if the specified *`iTab`* parameter value is invalid. ### Remarks This sends the `AFX_WM_CHANGE_ACTIVE_TAB` notification to the parent window and the parent's frame of the tab control. -The `SetActiveTab` method automatically calls the [CMFCTabCtrl::HideActiveWindowHorzScrollBar](#hideactivewindowhorzscrollbar) method to prevent the screen from blinking. +The `SetActiveTab` method automatically calls the [`CMFCTabCtrl::HideActiveWindowHorzScrollBar`](#hideactivewindowhorzscrollbar) method to prevent the screen from blinking. -## CMFCTabCtrl::SetActiveTabBoldFont +## `CMFCTabCtrl::SetActiveTabBoldFont` Enables or disables use of a bold font on active tabs. @@ -879,12 +878,12 @@ void SetActiveTabBoldFont(BOOL bIsBold=TRUE); ### Parameters -*bIsBold*
-[in] TRUE to use a bold font to display the label of the active tab; FALSE to use the standard font to display the label. The default value is TRUE. +*`bIsBold`*\ +[in] `TRUE` to use a bold font to display the label of the active tab; `FALSE` to use the standard font to display the label. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::SetDrawFrame +## `CMFCTabCtrl::SetDrawFrame` Specifies whether a frame rectangle is drawn around an embedded bar. @@ -894,12 +893,12 @@ void SetDrawFrame(BOOL bDraw=TRUE); ### Parameters -*bDraw*
-[in] TRUE to display a frame rectangle around an embedded bar; otherwise, FALSE. The default value is TRUE. +*`bDraw`*\ +[in] `TRUE` to display a frame rectangle around an embedded bar; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::SetFlatFrame +## `CMFCTabCtrl::SetFlatFrame` Specifies whether to draw a flat or a 3D frame around the tab area. @@ -911,15 +910,15 @@ void SetFlatFrame( ### Parameters -*bFlat*
-[in] TRUE to draw a flat (2D) frame around the tab area; FALSE to draw a three-dimensional (3D) frame. The default value is TRUE. +*`bFlat`*\ +[in] `TRUE` to draw a flat (2D) frame around the tab area; `FALSE` to draw a three-dimensional (3D) frame. The default value is `TRUE`. -*bRepaint*
-[in] TRUE to redraw the window immediately; otherwise, FALSE. The default value is TRUE. +*`bRepaint`*\ +[in] `TRUE` to redraw the window immediately; otherwise, `FALSE`. The default value is `TRUE`. ### Remarks -## CMFCTabCtrl::SetImageList +## `CMFCTabCtrl::SetImageList` Specifies an image list. @@ -934,29 +933,29 @@ virtual BOOL SetImageList(HIMAGELIST hImageList); ### Parameters -*uiID*
+*`uiID`*\ [in] The ID of a bitmap resource that contains the image list. -*cx*
+*`cx`*\ [in] The width of each image, in pixels. The default value is 15. -*clrTransp*
+*`clrTransp`*\ [in] The transparent image color. The parts of the image that are this color will be transparent. The default value is the color magenta, RGB(255,0,255). -*hImageList*
+*`hImageList`*\ [in] A handle to a preloaded image list. ### Return Value -TRUE if this method is successful. FALSE if the tab control is created by using a flat style or if the first method overload cannot load the bitmap that is specified by the *uiID* parameter. +`TRUE` if this method is successful. `FALSE` if the tab control is created by using a flat style or if the first method overload can't load the bitmap that is specified by the *`uiID`* parameter. ### Remarks Use this method to set an image list for the tab control. The images from the image list are displayed next to the tab label. This method recalculates the tab height so that the tab is sized to contain both the image and the text. -Use the [CMFCBaseTabCtrl::AddTab](../../mfc/reference/cmfcbasetabctrl-class.md#addtab) method that is inherited by the tab control to specify the index of the image to display. +Use the [`CMFCBaseTabCtrl::AddTab`](../../mfc/reference/cmfcbasetabctrl-class.md#addtab) method that is inherited by the tab control to specify the index of the image to display. -## CMFCTabCtrl::SetResizeMode +## `CMFCTabCtrl::SetResizeMode` Specifies how the current tab control can be resized and then redisplays the control. @@ -966,20 +965,20 @@ void SetResizeMode(ResizeMode resizeMode); ### Parameters -*resizeMode*
-[in] One of the `CMFCTabCtrl::ResizeMode` enumeration values that specifies how the tab control can be resized. For a list of possible values, see the table in Remarks. +*`resizeMode`*\ +[in] One of the `CMFCTabCtrl::ResizeMode` enumeration values that specifies how the tab control can be resized. For a list of possible values, see the table in [Remarks](#setresizemode-remarks). -### Remarks +### Remarks The *resizeMode* parameter can be one of the following `ResizeMode` enumeration values. |Name|Description| |----------|-----------------| -|RESIZE_NO|The tab control cannot be resized.| -|RESIZE_VERT|The tab control can be resized vertically but not horizontally.| -|RESIZE_HORIZ|The tab control can be resized horizontally but not vertically.| +|`RESIZE_NO`|The tab control can't be resized.| +|`RESIZE_VERT`|The tab control can be resized vertically but not horizontally.| +|`RESIZE_HORIZ`|The tab control can be resized horizontally but not vertically.| -## CMFCTabCtrl::SetTabMaxWidth +## `CMFCTabCtrl::SetTabMaxWidth` Specifies the maximum tab width in a tabbed window. @@ -989,14 +988,14 @@ void SetTabMaxWidth(int nTabMaxWidth); ### Parameters -*nTabMaxWidth*
+*`nTabMaxWidth`*\ [in] The maximum tab width, in pixels. ### Remarks -Use this method to limit the width of each tab in a tabbed window. This method is useful if tabs have very long labels. The [CMFCTabCtrl](../../mfc/reference/cmfctabctrl-class.md) class constructor initializes the maximum tab width to 0, which actually means that the width is not limited. +Use this method to limit the width of each tab in a tabbed window. This method is useful if tabs have very long labels. The [`CMFCTabCtrl`](../../mfc/reference/cmfctabctrl-class.md) class constructor initializes the maximum tab width to 0, which actually means that the width isn't limited. -## CMFCTabCtrl::StopResize +## `CMFCTabCtrl::StopResize` Terminates the current resize operation on the tab control. @@ -1006,10 +1005,10 @@ void StopResize(BOOL bCancel); ### Parameters -*bCancel*
-[in] TRUE to abandon the current resize operation; FALSE to complete the current resize operation. In either case, the framework stops drawing the resize rectangle. +*`bCancel`*\ +[in] `TRUE` to abandon the current resize operation; `FALSE` to complete the current resize operation. In either case, the framework stops drawing the resize rectangle. -## CMFCTabCtrl::SynchronizeScrollBar +## `CMFCTabCtrl::SynchronizeScrollBar` Draws a horizontal scroll bar on a tab control that displays flat tabs. @@ -1019,12 +1018,12 @@ BOOL SynchronizeScrollBar(SCROLLINFO* pScrollInfo = NULL); ### Parameters -*pScrollInfo*
-[out] Pointer to a [SCROLLINFO](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure or NULL. When this method returns, and if this parameter is not NULL, the structure contains all the parameters of the scroll bar. The default value is NULL. +*`pScrollInfo`*\ +[out] Pointer to a [`SCROLLINFO`](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure or `NULL`. When this method returns, and if this parameter isn't `NULL`, the structure contains all the parameters of the scroll bar. The default value is `NULL`. ### Return Value -TRUE if this method succeeds; otherwise, FALSE. +`TRUE` if this method succeeds; otherwise, `FALSE`. ### Remarks @@ -1032,7 +1031,7 @@ This method affects only a tab control that displays flat tabs. The scroll bar i ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CDockablePane Class](../../mfc/reference/cdockablepane-class.md)
-[CMFCBaseTabCtrl Class](../../mfc/reference/cmfcbasetabctrl-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md)\ +[`CMFCBaseTabCtrl` Class](../../mfc/reference/cmfcbasetabctrl-class.md) diff --git a/docs/mfc/reference/cmfctaskspane-class.md b/docs/mfc/reference/cmfctaskspane-class.md index 8644aab7a7..3f76674307 100644 --- a/docs/mfc/reference/cmfctaskspane-class.md +++ b/docs/mfc/reference/cmfctaskspane-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCTasksPane Class" title: "CMFCTasksPane Class" -ms.date: "07/02/2019" +description: "Learn more about: CMFCTasksPane Class" +ms.date: 07/02/2019 f1_keywords: ["CMFCTasksPane", "AFXTASKSPANE/CMFCTasksPane", "AFXTASKSPANE/CMFCTasksPane::CMFCTasksPane", "AFXTASKSPANE/CMFCTasksPane::AddGroup", "AFXTASKSPANE/CMFCTasksPane::AddLabel", "AFXTASKSPANE/CMFCTasksPane::AddMRUFilesList", "AFXTASKSPANE/CMFCTasksPane::AddPage", "AFXTASKSPANE/CMFCTasksPane::AddSeparator", "AFXTASKSPANE/CMFCTasksPane::AddTask", "AFXTASKSPANE/CMFCTasksPane::AddWindow", "AFXTASKSPANE/CMFCTasksPane::CollapseAllGroups", "AFXTASKSPANE/CMFCTasksPane::CollapseGroup", "AFXTASKSPANE/CMFCTasksPane::CreateDefaultMiniframe", "AFXTASKSPANE/CMFCTasksPane::CreateMenu", "AFXTASKSPANE/CMFCTasksPane::EnableAnimation", "AFXTASKSPANE/CMFCTasksPane::EnableGroupCollapse", "AFXTASKSPANE/CMFCTasksPane::EnableHistoryMenuButtons", "AFXTASKSPANE/CMFCTasksPane::EnableNavigationToolbar", "AFXTASKSPANE/CMFCTasksPane::EnableOffsetCustomControls", "AFXTASKSPANE/CMFCTasksPane::EnableScrollButtons", "AFXTASKSPANE/CMFCTasksPane::EnableWrapLabels", "AFXTASKSPANE/CMFCTasksPane::EnableWrapTasks", "AFXTASKSPANE/CMFCTasksPane::GetActivePage", "AFXTASKSPANE/CMFCTasksPane::GetGroupCaptionHeight", "AFXTASKSPANE/CMFCTasksPane::GetGroupCaptionHorzOffset", "AFXTASKSPANE/CMFCTasksPane::GetGroupCaptionVertOffset", "AFXTASKSPANE/CMFCTasksPane::GetGroupCount", "AFXTASKSPANE/CMFCTasksPane::GetGroupLocation", "AFXTASKSPANE/CMFCTasksPane::GetGroupVertOffset", "AFXTASKSPANE/CMFCTasksPane::GetHorzMargin", "AFXTASKSPANE/CMFCTasksPane::GetNextPages", "AFXTASKSPANE/CMFCTasksPane::GetPageByGroup", "AFXTASKSPANE/CMFCTasksPane::GetPagesCount", "AFXTASKSPANE/CMFCTasksPane::GetPreviousPages", "AFXTASKSPANE/CMFCTasksPane::GetScrollBarCtrl", "AFXTASKSPANE/CMFCTasksPane::GetTask", "AFXTASKSPANE/CMFCTasksPane::GetTaskCount", "AFXTASKSPANE/CMFCTasksPane::GetTaskGroup", "AFXTASKSPANE/CMFCTasksPane::GetTaskLocation", "AFXTASKSPANE/CMFCTasksPane::GetTasksHorzOffset", "AFXTASKSPANE/CMFCTasksPane::GetTasksIconHorzOffset", "AFXTASKSPANE/CMFCTasksPane::GetTasksIconVertOffset", "AFXTASKSPANE/CMFCTasksPane::GetVertMargin", "AFXTASKSPANE/CMFCTasksPane::IsAccessibilityCompatible", "AFXTASKSPANE/CMFCTasksPane::IsAnimationEnabled", "AFXTASKSPANE/CMFCTasksPane::IsBackButtonEnabled", "AFXTASKSPANE/CMFCTasksPane::IsForwardButtonEnabled", "AFXTASKSPANE/CMFCTasksPane::IsGroupCollapseEnabled", "AFXTASKSPANE/CMFCTasksPane::IsHistoryMenuButtonsEnabled", "AFXTASKSPANE/CMFCTasksPane::IsNavigationToolbarEnabled", "AFXTASKSPANE/CMFCTasksPane::IsToolBox", "AFXTASKSPANE/CMFCTasksPane::IsWrapLabelsEnabled", "AFXTASKSPANE/CMFCTasksPane::IsWrapTasksEnabled", "AFXTASKSPANE/CMFCTasksPane::LoadState", "AFXTASKSPANE/CMFCTasksPane::OnCancel", "AFXTASKSPANE/CMFCTasksPane::OnClickTask", "AFXTASKSPANE/CMFCTasksPane::OnOK", "AFXTASKSPANE/CMFCTasksPane::OnPressBackButton", "AFXTASKSPANE/CMFCTasksPane::OnPressForwardButton", "AFXTASKSPANE/CMFCTasksPane::OnPressHomeButton", "AFXTASKSPANE/CMFCTasksPane::OnPressOtherButton", "AFXTASKSPANE/CMFCTasksPane::OnSetAccData", "AFXTASKSPANE/CMFCTasksPane::OnUpdateCmdUI", "AFXTASKSPANE/CMFCTasksPane::PreTranslateMessage", "AFXTASKSPANE/CMFCTasksPane::RecalcLayout", "AFXTASKSPANE/CMFCTasksPane::RemoveAllGroups", "AFXTASKSPANE/CMFCTasksPane::RemoveAllPages", "AFXTASKSPANE/CMFCTasksPane::RemoveAllTasks", "AFXTASKSPANE/CMFCTasksPane::RemoveGroup", "AFXTASKSPANE/CMFCTasksPane::RemovePage", "AFXTASKSPANE/CMFCTasksPane::RemoveTask", "AFXTASKSPANE/CMFCTasksPane::SaveState", "AFXTASKSPANE/CMFCTasksPane::Serialize", "AFXTASKSPANE/CMFCTasksPane::SetActivePage", "AFXTASKSPANE/CMFCTasksPane::SetCaption", "AFXTASKSPANE/CMFCTasksPane::SetGroupCaptionHeight", "AFXTASKSPANE/CMFCTasksPane::SetGroupCaptionHorzOffset", "AFXTASKSPANE/CMFCTasksPane::SetGroupCaptionVertOffset", "AFXTASKSPANE/CMFCTasksPane::SetGroupName", "AFXTASKSPANE/CMFCTasksPane::SetGroupTextColor", "AFXTASKSPANE/CMFCTasksPane::SetGroupVertOffset", "AFXTASKSPANE/CMFCTasksPane::SetHorzMargin", "AFXTASKSPANE/CMFCTasksPane::SetIconsList", "AFXTASKSPANE/CMFCTasksPane::SetPageCaption", "AFXTASKSPANE/CMFCTasksPane::SetTaskName", "AFXTASKSPANE/CMFCTasksPane::SetTasksIconHorzOffset", "AFXTASKSPANE/CMFCTasksPane::SetTasksIconVertOffset", "AFXTASKSPANE/CMFCTasksPane::SetTaskTextColor", "AFXTASKSPANE/CMFCTasksPane::SetTasksHorzOffset", "AFXTASKSPANE/CMFCTasksPane::SetVertMargin", "AFXTASKSPANE/CMFCTasksPane::SetWindowHeight", "AFXTASKSPANE/CMFCTasksPane::ShowCommandMessageString", "AFXTASKSPANE/CMFCTasksPane::ShowTask", "AFXTASKSPANE/CMFCTasksPane::ShowTaskByCmdId", "AFXTASKSPANE/CMFCTasksPane::Update", "AFXTASKSPANE/CMFCTasksPane::OnActivateTasksPanePage"] helpviewer_keywords: ["CMFCTasksPane [MFC], CMFCTasksPane", "CMFCTasksPane [MFC], AddGroup", "CMFCTasksPane [MFC], AddLabel", "CMFCTasksPane [MFC], AddMRUFilesList", "CMFCTasksPane [MFC], AddPage", "CMFCTasksPane [MFC], AddSeparator", "CMFCTasksPane [MFC], AddTask", "CMFCTasksPane [MFC], AddWindow", "CMFCTasksPane [MFC], CollapseAllGroups", "CMFCTasksPane [MFC], CollapseGroup", "CMFCTasksPane [MFC], CreateDefaultMiniframe", "CMFCTasksPane [MFC], CreateMenu", "CMFCTasksPane [MFC], EnableAnimation", "CMFCTasksPane [MFC], EnableGroupCollapse", "CMFCTasksPane [MFC], EnableHistoryMenuButtons", "CMFCTasksPane [MFC], EnableNavigationToolbar", "CMFCTasksPane [MFC], EnableOffsetCustomControls", "CMFCTasksPane [MFC], EnableScrollButtons", "CMFCTasksPane [MFC], EnableWrapLabels", "CMFCTasksPane [MFC], EnableWrapTasks", "CMFCTasksPane [MFC], GetActivePage", "CMFCTasksPane [MFC], GetGroupCaptionHeight", "CMFCTasksPane [MFC], GetGroupCaptionHorzOffset", "CMFCTasksPane [MFC], GetGroupCaptionVertOffset", "CMFCTasksPane [MFC], GetGroupCount", "CMFCTasksPane [MFC], GetGroupLocation", "CMFCTasksPane [MFC], GetGroupVertOffset", "CMFCTasksPane [MFC], GetHorzMargin", "CMFCTasksPane [MFC], GetNextPages", "CMFCTasksPane [MFC], GetPageByGroup", "CMFCTasksPane [MFC], GetPagesCount", "CMFCTasksPane [MFC], GetPreviousPages", "CMFCTasksPane [MFC], GetScrollBarCtrl", "CMFCTasksPane [MFC], GetTask", "CMFCTasksPane [MFC], GetTaskCount", "CMFCTasksPane [MFC], GetTaskGroup", "CMFCTasksPane [MFC], GetTaskLocation", "CMFCTasksPane [MFC], GetTasksHorzOffset", "CMFCTasksPane [MFC], GetTasksIconHorzOffset", "CMFCTasksPane [MFC], GetTasksIconVertOffset", "CMFCTasksPane [MFC], GetVertMargin", "CMFCTasksPane [MFC], IsAccessibilityCompatible", "CMFCTasksPane [MFC], IsAnimationEnabled", "CMFCTasksPane [MFC], IsBackButtonEnabled", "CMFCTasksPane [MFC], IsForwardButtonEnabled", "CMFCTasksPane [MFC], IsGroupCollapseEnabled", "CMFCTasksPane [MFC], IsHistoryMenuButtonsEnabled", "CMFCTasksPane [MFC], IsNavigationToolbarEnabled", "CMFCTasksPane [MFC], IsToolBox", "CMFCTasksPane [MFC], IsWrapLabelsEnabled", "CMFCTasksPane [MFC], IsWrapTasksEnabled", "CMFCTasksPane [MFC], LoadState", "CMFCTasksPane [MFC], OnCancel", "CMFCTasksPane [MFC], OnClickTask", "CMFCTasksPane [MFC], OnOK", "CMFCTasksPane [MFC], OnPressBackButton", "CMFCTasksPane [MFC], OnPressForwardButton", "CMFCTasksPane [MFC], OnPressHomeButton", "CMFCTasksPane [MFC], OnPressOtherButton", "CMFCTasksPane [MFC], OnSetAccData", "CMFCTasksPane [MFC], OnUpdateCmdUI", "CMFCTasksPane [MFC], PreTranslateMessage", "CMFCTasksPane [MFC], RecalcLayout", "CMFCTasksPane [MFC], RemoveAllGroups", "CMFCTasksPane [MFC], RemoveAllPages", "CMFCTasksPane [MFC], RemoveAllTasks", "CMFCTasksPane [MFC], RemoveGroup", "CMFCTasksPane [MFC], RemovePage", "CMFCTasksPane [MFC], RemoveTask", "CMFCTasksPane [MFC], SaveState", "CMFCTasksPane [MFC], Serialize", "CMFCTasksPane [MFC], SetActivePage", "CMFCTasksPane [MFC], SetCaption", "CMFCTasksPane [MFC], SetGroupCaptionHeight", "CMFCTasksPane [MFC], SetGroupCaptionHorzOffset", "CMFCTasksPane [MFC], SetGroupCaptionVertOffset", "CMFCTasksPane [MFC], SetGroupName", "CMFCTasksPane [MFC], SetGroupTextColor", "CMFCTasksPane [MFC], SetGroupVertOffset", "CMFCTasksPane [MFC], SetHorzMargin", "CMFCTasksPane [MFC], SetIconsList", "CMFCTasksPane [MFC], SetPageCaption", "CMFCTasksPane [MFC], SetTaskName", "CMFCTasksPane [MFC], SetTasksIconHorzOffset", "CMFCTasksPane [MFC], SetTasksIconVertOffset", "CMFCTasksPane [MFC], SetTaskTextColor", "CMFCTasksPane [MFC], SetTasksHorzOffset", "CMFCTasksPane [MFC], SetVertMargin", "CMFCTasksPane [MFC], SetWindowHeight", "CMFCTasksPane [MFC], ShowCommandMessageString", "CMFCTasksPane [MFC], ShowTask", "CMFCTasksPane [MFC], ShowTaskByCmdId", "CMFCTasksPane [MFC], Update", "CMFCTasksPane [MFC], OnActivateTasksPanePage"] -ms.assetid: b456328e-2525-4642-b78b-9edd1a1a7d3f --- # CMFCTasksPane Class @@ -171,11 +170,11 @@ The following example demonstrates how to construct a `CMFCTasksPane` object and [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CPane](../../mfc/reference/cpane-class.md)\ -                └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ -                    └ `CMFCTasksPane` + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CPane](../../mfc/reference/cpane-class.md)\ +    └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ +     └ `CMFCTasksPane` ## Requirements @@ -1461,7 +1460,7 @@ void SetGroupCaptionHeight(int n = -1); Call this method to customize the margins of the task pane elements. -If *n* is -1, the framework determines the margin value by using the visual manager ( `CMFCVisualManager::GetTasksPaneGroupCaptionHeight`). The default caption height is 25 pixels. +If *n* is -1, the framework determines the margin value by using the visual manager (`CMFCVisualManager::GetTasksPaneGroupCaptionHeight`). The default caption height is 25 pixels. ## CMFCTasksPane::SetGroupCaptionHorzOffset diff --git a/docs/mfc/reference/cmfctoolbar-class.md b/docs/mfc/reference/cmfctoolbar-class.md index f76268e6c9..e71eb71307 100644 --- a/docs/mfc/reference/cmfctoolbar-class.md +++ b/docs/mfc/reference/cmfctoolbar-class.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: CMFCToolBar Class" title: "CMFCToolBar Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCToolBar Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCToolBar", "AFXTOOLBAR/CMFCToolBar", "AFXTOOLBAR/CMFCToolBar::AddBasicCommand", "AFXTOOLBAR/CMFCToolBar::AddCommandUsage", "AFXTOOLBAR/CMFCToolBar::AddToolBarForImageCollection", "AFXTOOLBAR/CMFCToolBar::AdjustLayout", "AFXTOOLBAR/CMFCToolBar::AdjustSize", "AFXTOOLBAR/CMFCToolBar::AllowChangeTextLabels", "AFXTOOLBAR/CMFCToolBar::AreTextLabels", "AFXTOOLBAR/CMFCToolBar::AutoGrayInactiveImages", "AFXTOOLBAR/CMFCToolBar::ButtonToIndex", "AFXTOOLBAR/CMFCToolBar::CalcFixedLayout", "AFXTOOLBAR/CMFCToolBar::CalcSize", "AFXTOOLBAR/CMFCToolBar::CanHandleSiblings", "AFXTOOLBAR/CMFCToolBar::CleanUpImages", "AFXTOOLBAR/CMFCToolBar::CleanUpLockedImages", "AFXTOOLBAR/CMFCToolBar::CanBeClosed", "AFXTOOLBAR/CMFCToolBar::CanBeRestored", "AFXTOOLBAR/CMFCToolBar::CanFocus", "AFXTOOLBAR/CMFCToolBar::CommandToIndex", "AFXTOOLBAR/CMFCToolBar::Create", "AFXTOOLBAR/CMFCToolBar::CreateEx", "AFXTOOLBAR/CMFCToolBar::Deactivate", "AFXTOOLBAR/CMFCToolBar::EnableCustomizeButton", "AFXTOOLBAR/CMFCToolBar::EnableDocking", "AFXTOOLBAR/CMFCToolBar::EnableLargeIcons", "AFXTOOLBAR/CMFCToolBar::EnableQuickCustomization", "AFXTOOLBAR/CMFCToolBar::EnableReflections", "AFXTOOLBAR/CMFCToolBar::EnableTextLabels", "AFXTOOLBAR/CMFCToolBar::FromHandlePermanent", "AFXTOOLBAR/CMFCToolBar::GetAllButtons", "AFXTOOLBAR/CMFCToolBar::GetAllToolbars", "AFXTOOLBAR/CMFCToolBar::GetBasicCommands", "AFXTOOLBAR/CMFCToolBar::GetButton", "AFXTOOLBAR/CMFCToolBar::GetButtonInfo", "AFXTOOLBAR/CMFCToolBar::GetButtonSize", "AFXTOOLBAR/CMFCToolBar::GetButtonStyle", "AFXTOOLBAR/CMFCToolBar::GetButtonText", "AFXTOOLBAR/CMFCToolBar::GetColdImages", "AFXTOOLBAR/CMFCToolBar::GetColumnWidth", "AFXTOOLBAR/CMFCToolBar::GetCommandButtons", "AFXTOOLBAR/CMFCToolBar::GetCount", "AFXTOOLBAR/CMFCToolBar::GetCustomizeButton", "AFXTOOLBAR/CMFCToolBar::GetDefaultImage", "AFXTOOLBAR/CMFCToolBar::GetDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetDisabledMenuImages", "AFXTOOLBAR/CMFCToolBar::GetDroppedDownMenu", "AFXTOOLBAR/CMFCToolBar::GetGrayDisabledButtons", "AFXTOOLBAR/CMFCToolBar::GetHighlightedButton", "AFXTOOLBAR/CMFCToolBar::GetHotBorder", "AFXTOOLBAR/CMFCToolBar::GetHotTextColor", "AFXTOOLBAR/CMFCToolBar::GetHwndLastFocus", "AFXTOOLBAR/CMFCToolBar::GetOVERWRITESetText", "AFXTOOLBAR/CMFCToolBar::GetImageSize", "AFXTOOLBAR/CMFCToolBar::GetImages", "AFXTOOLBAR/CMFCToolBar::GetImagesOffset", "AFXTOOLBAR/CMFCToolBar::GetInvalidateItemRect", "AFXTOOLBAR/CMFCToolBar::GetItemID", "AFXTOOLBAR/CMFCToolBar::GetItemRect", "AFXTOOLBAR/CMFCToolBar::GetLargeColdImages", "AFXTOOLBAR/CMFCToolBar::GetLargeDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetLargeImages", "AFXTOOLBAR/CMFCToolBar::GetLockedColdImages", "AFXTOOLBAR/CMFCToolBar::GetLockedDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetLockedImages", "AFXTOOLBAR/CMFCToolBar::GetLockedImageSize", "AFXTOOLBAR/CMFCToolBar::GetLockedMenuImages", "AFXTOOLBAR/CMFCToolBar::GetMenuButtonSize", "AFXTOOLBAR/CMFCToolBar::GetMenuImageSize", "AFXTOOLBAR/CMFCToolBar::GetMenuImages", "AFXTOOLBAR/CMFCToolBar::GetOrigButtons", "AFXTOOLBAR/CMFCToolBar::GetOrigResetButtons", "AFXTOOLBAR/CMFCToolBar::GetResourceID", "AFXTOOLBAR/CMFCToolBar::GetRouteCommandsViaFrame", "AFXTOOLBAR/CMFCToolBar::GetRowHeight", "AFXTOOLBAR/CMFCToolBar::GetShowTooltips", "AFXTOOLBAR/CMFCToolBar::GetSiblingToolBar", "AFXTOOLBAR/CMFCToolBar::GetUserImages", "AFXTOOLBAR/CMFCToolBar::HitTest", "AFXTOOLBAR/CMFCToolBar::InsertButton", "AFXTOOLBAR/CMFCToolBar::InsertSeparator", "AFXTOOLBAR/CMFCToolBar::InvalidateButton", "AFXTOOLBAR/CMFCToolBar::IsAddRemoveQuickCustomize", "AFXTOOLBAR/CMFCToolBar::IsAltCustomizeMode", "AFXTOOLBAR/CMFCToolBar::IsAutoGrayInactiveImages", "AFXTOOLBAR/CMFCToolBar::IsBasicCommand", "AFXTOOLBAR/CMFCToolBar::IsButtonExtraSizeAvailable", "AFXTOOLBAR/CMFCToolBar::IsButtonHighlighted", "AFXTOOLBAR/CMFCToolBar::IsCommandPermitted", "AFXTOOLBAR/CMFCToolBar::IsCommandRarelyUsed", "AFXTOOLBAR/CMFCToolBar::IsCustomizeMode", "AFXTOOLBAR/CMFCToolBar::IsDragButton", "AFXTOOLBAR/CMFCToolBar::IsExistCustomizeButton", "AFXTOOLBAR/CMFCToolBar::IsFloating", "AFXTOOLBAR/CMFCToolBar::IsLargeIcons", "AFXTOOLBAR/CMFCToolBar::IsLastCommandFromButton", "AFXTOOLBAR/CMFCToolBar::IsLocked", "AFXTOOLBAR/CMFCToolBar::IsOneRowWithSibling", "AFXTOOLBAR/CMFCToolBar::IsUserDefined", "AFXTOOLBAR/CMFCToolBar::LoadBitmap", "AFXTOOLBAR/CMFCToolBar::LoadBitmapEx", "AFXTOOLBAR/CMFCToolBar::LoadParameters", "AFXTOOLBAR/CMFCToolBar::LoadState", "AFXTOOLBAR/CMFCToolBar::LoadToolBar", "AFXTOOLBAR/CMFCToolBar::LoadToolBarEx", "AFXTOOLBAR/CMFCToolBar::OnChangeHot", "AFXTOOLBAR/CMFCToolBar::OnFillBackground", "AFXTOOLBAR/CMFCToolBar::OnReset", "AFXTOOLBAR/CMFCToolBar::OnSetAccData", "AFXTOOLBAR/CMFCToolBar::OnSetDefaultButtonText", "AFXTOOLBAR/CMFCToolBar::RemoveAllButtons", "AFXTOOLBAR/CMFCToolBar::RemoveButton", "AFXTOOLBAR/CMFCToolBar::RemoveStateFromRegistry", "AFXTOOLBAR/CMFCToolBar::ReplaceButton", "AFXTOOLBAR/CMFCToolBar::ResetAll", "AFXTOOLBAR/CMFCToolBar::ResetAllImages", "AFXTOOLBAR/CMFCToolBar::RestoreOriginalState", "AFXTOOLBAR/CMFCToolBar::SaveState", "AFXTOOLBAR/CMFCToolBar::SetBasicCommands", "AFXTOOLBAR/CMFCToolBar::SetButtonInfo", "AFXTOOLBAR/CMFCToolBar::SetButtonStyle", "AFXTOOLBAR/CMFCToolBar::SetButtonText", "AFXTOOLBAR/CMFCToolBar::SetButtons", "AFXTOOLBAR/CMFCToolBar::SetCommandUsageOptions", "AFXTOOLBAR/CMFCToolBar::SetCustomizeMode", "AFXTOOLBAR/CMFCToolBar::SetGrayDisabledButtons", "AFXTOOLBAR/CMFCToolBar::SetHeight", "AFXTOOLBAR/CMFCToolBar::SetHotBorder", "AFXTOOLBAR/CMFCToolBar::SetHotTextColor", "AFXTOOLBAR/CMFCToolBar::SetLargeIcons", "AFXTOOLBAR/CMFCToolBar::SetLockedSizes", "AFXTOOLBAR/CMFCToolBar::SetMenuSizes", "AFXTOOLBAR/CMFCToolBar::SetNonPermittedCommands", "AFXTOOLBAR/CMFCToolBar::SetOneRowWithSibling", "AFXTOOLBAR/CMFCToolBar::SetPermament", "AFXTOOLBAR/CMFCToolBar::SetRouteCommandsViaFrame", "AFXTOOLBAR/CMFCToolBar::SetShowTooltips", "AFXTOOLBAR/CMFCToolBar::SetSiblingToolBar", "AFXTOOLBAR/CMFCToolBar::SetSizes", "AFXTOOLBAR/CMFCToolBar::SetToolBarBtnText", "AFXTOOLBAR/CMFCToolBar::SetTwoRowsWithSibling", "AFXTOOLBAR/CMFCToolBar::SetUserImages", "AFXTOOLBAR/CMFCToolBar::StretchPane", "AFXTOOLBAR/CMFCToolBar::TranslateChar", "AFXTOOLBAR/CMFCToolBar::UpdateButton", "AFXTOOLBAR/CMFCToolBar::WrapToolBar", "AFXTOOLBAR/CMFCToolBar::AllowShowOnList", "AFXTOOLBAR/CMFCToolBar::CalcMaxButtonHeight", "AFXTOOLBAR/CMFCToolBar::DoPaint", "AFXTOOLBAR/CMFCToolBar::DrawButton", "AFXTOOLBAR/CMFCToolBar::DrawSeparator", "AFXTOOLBAR/CMFCToolBar::OnUserToolTip", "AFXTOOLBAR/CMFCToolBar::m_bDontScaleImages", "AFXTOOLBAR/CMFCToolBar::m_dblLargeImageRatio"] helpviewer_keywords: ["CMFCToolBar [MFC], AddBasicCommand", "CMFCToolBar [MFC], AddCommandUsage", "CMFCToolBar [MFC], AddToolBarForImageCollection", "CMFCToolBar [MFC], AdjustLayout", "CMFCToolBar [MFC], AdjustSize", "CMFCToolBar [MFC], AllowChangeTextLabels", "CMFCToolBar [MFC], AreTextLabels", "CMFCToolBar [MFC], AutoGrayInactiveImages", "CMFCToolBar [MFC], ButtonToIndex", "CMFCToolBar [MFC], CalcFixedLayout", "CMFCToolBar [MFC], CalcSize", "CMFCToolBar [MFC], CanHandleSiblings", "CMFCToolBar [MFC], CleanUpImages", "CMFCToolBar [MFC], CleanUpLockedImages", "CMFCToolBar [MFC], CanBeClosed", "CMFCToolBar [MFC], CanBeRestored", "CMFCToolBar [MFC], CanFocus", "CMFCToolBar [MFC], CanHandleSiblings", "CMFCToolBar [MFC], CommandToIndex", "CMFCToolBar [MFC], Create", "CMFCToolBar [MFC], CreateEx", "CMFCToolBar [MFC], Deactivate", "CMFCToolBar [MFC], EnableCustomizeButton", "CMFCToolBar [MFC], EnableDocking", "CMFCToolBar [MFC], EnableLargeIcons", "CMFCToolBar [MFC], EnableQuickCustomization", "CMFCToolBar [MFC], EnableReflections", "CMFCToolBar [MFC], EnableTextLabels", "CMFCToolBar [MFC], FromHandlePermanent", "CMFCToolBar [MFC], GetAllButtons", "CMFCToolBar [MFC], GetAllToolbars", "CMFCToolBar [MFC], GetBasicCommands", "CMFCToolBar [MFC], GetButton", "CMFCToolBar [MFC], GetButtonInfo", "CMFCToolBar [MFC], GetButtonSize", "CMFCToolBar [MFC], GetButtonStyle", "CMFCToolBar [MFC], GetButtonText", "CMFCToolBar [MFC], GetColdImages", "CMFCToolBar [MFC], GetColumnWidth", "CMFCToolBar [MFC], GetCommandButtons", "CMFCToolBar [MFC], GetCount", "CMFCToolBar [MFC], GetCustomizeButton", "CMFCToolBar [MFC], GetDefaultImage", "CMFCToolBar [MFC], GetDisabledImages", "CMFCToolBar [MFC], GetDisabledMenuImages", "CMFCToolBar [MFC], GetDroppedDownMenu", "CMFCToolBar [MFC], GetGrayDisabledButtons", "CMFCToolBar [MFC], GetHighlightedButton", "CMFCToolBar [MFC], GetHotBorder", "CMFCToolBar [MFC], GetHotTextColor", "CMFCToolBar [MFC], GetHwndLastFocus", "CMFCToolBar [MFC], GetIgnoreSetText", "CMFCToolBar [MFC], GetImageSize", "CMFCToolBar [MFC], GetImages", "CMFCToolBar [MFC], GetImagesOffset", "CMFCToolBar [MFC], GetInvalidateItemRect", "CMFCToolBar [MFC], GetItemID", "CMFCToolBar [MFC], GetItemRect", "CMFCToolBar [MFC], GetLargeColdImages", "CMFCToolBar [MFC], GetLargeDisabledImages", "CMFCToolBar [MFC], GetLargeImages", "CMFCToolBar [MFC], GetLockedColdImages", "CMFCToolBar [MFC], GetLockedDisabledImages", "CMFCToolBar [MFC], GetLockedImages", "CMFCToolBar [MFC], GetLockedImageSize", "CMFCToolBar [MFC], GetLockedMenuImages", "CMFCToolBar [MFC], GetMenuButtonSize", "CMFCToolBar [MFC], GetMenuImageSize", "CMFCToolBar [MFC], GetMenuImages", "CMFCToolBar [MFC], GetOrigButtons", "CMFCToolBar [MFC], GetOrigResetButtons", "CMFCToolBar [MFC], GetResourceID", "CMFCToolBar [MFC], GetRouteCommandsViaFrame", "CMFCToolBar [MFC], GetRowHeight", "CMFCToolBar [MFC], GetShowTooltips", "CMFCToolBar [MFC], GetSiblingToolBar", "CMFCToolBar [MFC], GetUserImages", "CMFCToolBar [MFC], HitTest", "CMFCToolBar [MFC], InsertButton", "CMFCToolBar [MFC], InsertSeparator", "CMFCToolBar [MFC], InvalidateButton", "CMFCToolBar [MFC], IsAddRemoveQuickCustomize", "CMFCToolBar [MFC], IsAltCustomizeMode", "CMFCToolBar [MFC], IsAutoGrayInactiveImages", "CMFCToolBar [MFC], IsBasicCommand", "CMFCToolBar [MFC], IsButtonExtraSizeAvailable", "CMFCToolBar [MFC], IsButtonHighlighted", "CMFCToolBar [MFC], IsCommandPermitted", "CMFCToolBar [MFC], IsCommandRarelyUsed", "CMFCToolBar [MFC], IsCustomizeMode", "CMFCToolBar [MFC], IsDragButton", "CMFCToolBar [MFC], IsExistCustomizeButton", "CMFCToolBar [MFC], IsFloating", "CMFCToolBar [MFC], IsLargeIcons", "CMFCToolBar [MFC], IsLastCommandFromButton", "CMFCToolBar [MFC], IsLocked", "CMFCToolBar [MFC], IsOneRowWithSibling", "CMFCToolBar [MFC], IsUserDefined", "CMFCToolBar [MFC], LoadBitmap", "CMFCToolBar [MFC], LoadBitmapEx", "CMFCToolBar [MFC], LoadParameters", "CMFCToolBar [MFC], LoadState", "CMFCToolBar [MFC], LoadToolBar", "CMFCToolBar [MFC], LoadToolBarEx", "CMFCToolBar [MFC], OnChangeHot", "CMFCToolBar [MFC], OnFillBackground", "CMFCToolBar [MFC], OnReset", "CMFCToolBar [MFC], OnSetAccData", "CMFCToolBar [MFC], OnSetDefaultButtonText", "CMFCToolBar [MFC], RemoveAllButtons", "CMFCToolBar [MFC], RemoveButton", "CMFCToolBar [MFC], RemoveStateFromRegistry", "CMFCToolBar [MFC], ReplaceButton", "CMFCToolBar [MFC], ResetAll", "CMFCToolBar [MFC], ResetAllImages", "CMFCToolBar [MFC], RestoreOriginalState", "CMFCToolBar [MFC], SaveState", "CMFCToolBar [MFC], SetBasicCommands", "CMFCToolBar [MFC], SetButtonInfo", "CMFCToolBar [MFC], SetButtonStyle", "CMFCToolBar [MFC], SetButtonText", "CMFCToolBar [MFC], SetButtons", "CMFCToolBar [MFC], SetCommandUsageOptions", "CMFCToolBar [MFC], SetCustomizeMode", "CMFCToolBar [MFC], SetGrayDisabledButtons", "CMFCToolBar [MFC], SetHeight", "CMFCToolBar [MFC], SetHotBorder", "CMFCToolBar [MFC], SetHotTextColor", "CMFCToolBar [MFC], SetLargeIcons", "CMFCToolBar [MFC], SetLockedSizes", "CMFCToolBar [MFC], SetMenuSizes", "CMFCToolBar [MFC], SetNonPermittedCommands", "CMFCToolBar [MFC], SetOneRowWithSibling", "CMFCToolBar [MFC], SetPermament", "CMFCToolBar [MFC], SetRouteCommandsViaFrame", "CMFCToolBar [MFC], SetShowTooltips", "CMFCToolBar [MFC], SetSiblingToolBar", "CMFCToolBar [MFC], SetSizes", "CMFCToolBar [MFC], SetToolBarBtnText", "CMFCToolBar [MFC], SetTwoRowsWithSibling", "CMFCToolBar [MFC], SetUserImages", "CMFCToolBar [MFC], StretchPane", "CMFCToolBar [MFC], TranslateChar", "CMFCToolBar [MFC], UpdateButton", "CMFCToolBar [MFC], WrapToolBar", "CMFCToolBar [MFC], AllowShowOnList", "CMFCToolBar [MFC], CalcMaxButtonHeight", "CMFCToolBar [MFC], DoPaint", "CMFCToolBar [MFC], DrawButton", "CMFCToolBar [MFC], DrawSeparator", "CMFCToolBar [MFC], OnUserToolTip", "CMFCToolBar [MFC], m_bDontScaleImages", "CMFCToolBar [MFC], m_dblLargeImageRatio"] -ms.assetid: e7679c01-fb94-44c0-98c6-3af955292fb5 --- -# CMFCToolBar Class +# `CMFCToolBar` Class -The `CMFCToolBar` class resembles [CToolBar Class](../../mfc/reference/ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. +The `CMFCToolBar` class resembles [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. +For more detail, see the source code located in your Visual Studio installation, for example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ## Syntax @@ -31,171 +30,171 @@ class CMFCToolBar : public CMFCBaseToolBar |Name|Description| |----------|-----------------| -|[CMFCToolBar::AddBasicCommand](#addbasiccommand)|Adds a menu command to the list of commands that are always displayed when a user opens a menu.| -|[CMFCToolBar::AddCommandUsage](#addcommandusage)|Increments by one the counter that is associated with the given command.| -|[CMFCToolBar::AddToolBarForImageCollection](#addtoolbarforimagecollection)|Adds images from the user interface resources to the collection of images in the application.| -|[CMFCToolBar::AdjustLayout](#adjustlayout)|Recalculates the size and position of a toolbar. (Overrides [CBasePane::AdjustLayout](../../mfc/reference/cbasepane-class.md#adjustlayout)).| -|[CMFCToolBar::AdjustSize](#adjustsize)|Recalculates the size of the toolbar.| -|[CMFCToolBar::AllowChangeTextLabels](#allowchangetextlabels)|Specifies whether text labels can be shown under images on the toolbar buttons.| -|[CMFCToolBar::AreTextLabels](#aretextlabels)|Specifies whether text labels under images are currently displayed on the toolbar buttons.| -|[CMFCToolBar::AutoGrayInactiveImages](#autograyinactiveimages)|Enable or disables the automatic generation of inactive button images.| -|[CMFCToolBar::ButtonToIndex](#buttontoindex)|Returns the index of a specified [CMFCToolBarButton Class](../../mfc/reference/cmfctoolbarbutton-class.md) object in this toolbar.| -|[CMFCToolBar::CalcFixedLayout](#calcfixedlayout)|Calculates the horizontal size of the toolbar. (Overrides [CBasePane::CalcFixedLayout](../../mfc/reference/cbasepane-class.md#calcfixedlayout).)| -|[CMFCToolBar::CalcSize](#calcsize)|Called by the framework as part of the layout calculation process. (Overrides [CPane::CalcSize](../../mfc/reference/cpane-class.md#calcsize).)| -|[CMFCToolBar::CanHandleSiblings](#canhandlesiblings)|Determines whether the toolbar and its sibling are positioned on the same pane.| -|[CMFCToolBar::CleanUpImages](#cleanupimages)|Frees the system resources allocated for toolbar images.| -|[CMFCToolBar::CleanUpLockedImages](#cleanuplockedimages)|Frees the system resources allocated for locked toolbar images.| -|[CMFCToolBar::CanBeClosed](#canbeclosed)|Specifies whether a user can close the toolbar. (Overrides [CBasePane::CanBeClosed](../../mfc/reference/cbasepane-class.md#canbeclosed).)| -|[CMFCToolBar::CanBeRestored](#canberestored)|Determines whether the system can restore a toolbar to its original state after customization.| -|[CMFCToolBar::CanFocus](#canfocus)|Specifies whether the pane can receive focus. (Overrides [CBasePane::CanFocus](../../mfc/reference/cbasepane-class.md#canfocus).)| -|[CMFCToolBar::CanHandleSiblings](#canhandlesiblings)|Determines whether the toolbar and its sibling are positioned on the same pane.| -|[CMFCToolBar::CommandToIndex](#commandtoindex)|Returns the index of the button in the toolbar with a specified command ID.| -|[CMFCToolBar::Create](#create)|Creates a `CMFCToolBar` object.| -|[CMFCToolBar::CreateEx](#createex)|Creates a `CMFCToolBar` object that uses additional style options, such as large icons.| -|[CMFCToolBar::Deactivate](#deactivate)|Deactivates the toolbar.| -|[CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton)|Enables or disables the **Add or Remove Buttons** button that appears on the end of the toolbar.| -|[CMFCToolBar::EnableDocking](#enabledocking)|Enables docking of the pane to the main frame. (Overrides [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking).)| -|[CMFCToolBar::EnableLargeIcons](#enablelargeicons)|Enables or disables large icons on toolbar buttons.| -|[CMFCToolBar::EnableQuickCustomization](#enablequickcustomization)|Enables or disables the quick customization of toolbars so that the user can press the **Alt** key and drag a button to a new location.| -|[CMFCToolBar::EnableReflections](#enablereflections)|Enables or disables command reflection.| -|[CMFCToolBar::EnableTextLabels](#enabletextlabels)|Enables or disables text labels under toolbar button images.| -|[CMFCToolBar::FromHandlePermanent](#fromhandlepermanent)|Retrieves a pointer to the `CMFCToolBar` object that contains the given window handle.| -|[CMFCToolBar::GetAllButtons](#getallbuttons)|Returns a read-only list of buttons in a toolbar.| -|[CMFCToolBar::GetAllToolbars](#getalltoolbars)|Returns a read-only list of all toolbars in the application.| -|[CMFCToolBar::GetBasicCommands](#getbasiccommands)|Returns a read-only list of the basic commands defined in the application.| -|[CMFCToolBar::GetButton](#getbutton)|Returns a pointer to the `CMFCToolBarButton` object that has a specified toolbar button index.| -|[CMFCToolBar::GetButtonInfo](#getbuttoninfo)|Returns the command ID, style, and image index of the button at a specified index.| -|[CMFCToolBar::GetButtonSize](#getbuttonsize)|Returns the dimensions of each button on the toolbar.| -|[CMFCToolBar::GetButtonStyle](#getbuttonstyle)|Returns the current style of the toolbar button that is located at the specified index.| -|[CMFCToolBar::GetButtonText](#getbuttontext)|Returns the text label of a button that has a specified index.| -|[CMFCToolBar::GetColdImages](#getcoldimages)|Returns a pointer to the collection of cold toolbar button images in the application.| -|[CMFCToolBar::GetColumnWidth](#getcolumnwidth)|Returns the width of the toolbar buttons.| -|[CMFCToolBar::GetCommandButtons](#getcommandbuttons)|Returns a list of buttons that have a specified command ID from all toolbars in the application.| -|[CMFCToolBar::GetCount](#getcount)|Returns the number of buttons and separators on the toolbar.| -|[CMFCToolBar::GetCustomizeButton](#getcustomizebutton)|Retrieves a pointer to the `CMFCCustomizeButton` object that is associated with the toolbar.| -|[CMFCToolBar::GetDefaultImage](#getdefaultimage)|Returns the index of the default image for a toolbar button with a specified command ID.| -|[CMFCToolBar::GetDisabledImages](#getdisabledimages)|Returns a pointer to the collection of images that are used for disabled toolbar buttons in the application.| -|[CMFCToolBar::GetDisabledMenuImages](#getdisabledmenuimages)|Returns a pointer to the collection of images that are used for disabled menu buttons in the application.| -|[CMFCToolBar::GetDroppedDownMenu](#getdroppeddownmenu)|Retrieves a pointer to the menu button object that is currently displaying its sub-menu.| -|[CMFCToolBar::GetGrayDisabledButtons](#getgraydisabledbuttons)|Specifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images.| -|[CMFCToolBar::GetHighlightedButton](#gethighlightedbutton)|Returns a pointer to the toolbar button that is currently highlighted.| -|[CMFCToolBar::GetHotBorder](#gethotborder)|Determines whether the toolbar buttons are hot-tracked.| -|[CMFCToolBar::GetHotTextColor](#gethottextcolor)|Returns the text color of the highlighted toolbar buttons.| -|[CMFCToolBar::GetHwndLastFocus](#gethwndlastfocus)|Returns a handle to the window that had the input focus just before the toolbar did.| -|[CMFCToolBar::GetIgnoreSetText](#getignoresettext)|Specifies whether calls to set button labels are ignored.| -|[CMFCToolBar::GetImageSize](#getimagesize)|Returns the current size of toolbar button images.| -|[CMFCToolBar::GetImages](#getimages)|Returns a pointer to the collection of default button images in the application.| -|[CMFCToolBar::GetImagesOffset](#getimagesoffset)|Returns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images.| -|[CMFCToolBar::GetInvalidateItemRect](#getinvalidateitemrect)|Retrieves the region of the client area that must be redrawn for the button at the given index.| -|[CMFCToolBar::GetItemID](#getitemid)|Returns the command ID of the toolbar button at a specified index.| -|[CMFCToolBar::GetItemRect](#getitemrect)|Returns the bounding rectangle of the button at a specified index.| -|[CMFCToolBar::GetLargeColdImages](#getlargecoldimages)|Returns a pointer to the collection of large cold toolbar button images in the application.| -|[CMFCToolBar::GetLargeDisabledImages](#getlargedisabledimages)|Returns a pointer to the collection of large disabled toolbar button images in the application.| -|[CMFCToolBar::GetLargeImages](#getlargeimages)|Returns a pointer to the collection of large toolbar button images in the application.| -|[CMFCToolBar::GetLockedColdImages](#getlockedcoldimages)|Returns a pointer to the collection of locked cold images in the toolbar.| -|[CMFCToolBar::GetLockedDisabledImages](#getlockeddisabledimages)|Returns a pointer to the collection of locked disabled images in the toolbar.| -|[CMFCToolBar::GetLockedImages](#getlockedimages)|Returns a pointer to the collection of locked button images in the toolbar.| -|[CMFCToolBar::GetLockedImageSize](#getlockedimagesize)|Returns the default size of locked toolbar images.| -|[CMFCToolBar::GetLockedMenuImages](#getlockedmenuimages)|Returns a pointer to the collection of locked toolbar menu images in the toolbar.| -|[CMFCToolBar::GetMenuButtonSize](#getmenubuttonsize)|Returns the size of menu buttons in the application.| -|[CMFCToolBar::GetMenuImageSize](#getmenuimagesize)|Returns the size of menu button images in the application.| -|[CMFCToolBar::GetMenuImages](#getmenuimages)|Returns a pointer to the collection of menu button images in the application.| -|[CMFCToolBar::GetOrigButtons](#getorigbuttons)|Retrieves the collection of non-customized buttons of the toolbar.| -|[CMFCToolBar::GetOrigResetButtons](#getorigresetbuttons)|Retrieves the collection of non-customized reset buttons of the toolbar.| -|[CMFCToolBar::GetResourceID](#getresourceid)|Retrieves the resource ID of the toolbar.| -|[CMFCToolBar::GetRouteCommandsViaFrame](#getroutecommandsviaframe)|Determines which object, the parent frame or the owner, sends commands to the toolbar.| -|[CMFCToolBar::GetRowHeight](#getrowheight)|Returns the height of toolbar buttons.| -|[CMFCToolBar::GetShowTooltips](#getshowtooltips)|Specifies whether tool tips are displayed for toolbar buttons.| -|[CMFCToolBar::GetSiblingToolBar](#getsiblingtoolbar)|Retrieves the sibling of the toolbar.| -|[CMFCToolBar::GetUserImages](#getuserimages)|Returns a pointer to the collection of user-defined toolbar button images in the application.| -|[CMFCToolBar::HitTest](#hittest)|Returns the index of the toolbar button that is located at the specified position.| -|[CMFCToolBar::InsertButton](#insertbutton)|Inserts a button into the toolbar.| -|[CMFCToolBar::InsertSeparator](#insertseparator)|Inserts a separator into the toolbar.| -|[CMFCToolBar::InvalidateButton](#invalidatebutton)|Invalidates the client area of the toolbar button that exists at the provided index.| -|[CMFCToolBar::IsAddRemoveQuickCustomize](#isaddremovequickcustomize)|Determines whether a user can add or remove toolbar buttons by using the **Customize** menu option.| -|[CMFCToolBar::IsAltCustomizeMode](#isaltcustomizemode)|Specifies whether *quick customization* is being used to drag a button.| -|[CMFCToolBar::IsAutoGrayInactiveImages](#isautograyinactiveimages)|Specifies whether the automatic generation of inactive (non-highlighted) button images is enabled.| -|[CMFCToolBar::IsBasicCommand](#isbasiccommand)|Determines whether a command is on the list of basic commands.| -|[CMFCToolBar::IsButtonExtraSizeAvailable](#isbuttonextrasizeavailable)|Determines whether the toolbar can display buttons that have extended borders.| -|[CMFCToolBar::IsButtonHighlighted](#isbuttonhighlighted)|Determines whether a button on the toolbar is highlighted.| -|[CMFCToolBar::IsCommandPermitted](#iscommandpermitted)|Determines whether a command is permitted.| -|[CMFCToolBar::IsCommandRarelyUsed](#iscommandrarelyused)|Determines whether a command is rarely used (see [CMFCToolBar::SetCommandUsageOptions](#setcommandusageoptions)).| -|[CMFCToolBar::IsCustomizeMode](#iscustomizemode)|Specifies whether the toolbar framework is in customization mode.| -|[CMFCToolBar::IsDragButton](#isdragbutton)|Determines whether a toolbar button is being dragged.| -|[CMFCToolBar::IsExistCustomizeButton](#isexistcustomizebutton)|Determines whether the toolbar contains the **Customize** button.| -|[CMFCToolBar::IsFloating](#isfloating)|Determines whether the toolbar is floating.| -|[CMFCToolBar::IsLargeIcons](#islargeicons)|Specifies whether toolbars in the application currently display large icons.| -|[CMFCToolBar::IsLastCommandFromButton](#islastcommandfrombutton)|Determines whether the most recently executed command was sent from the specified toolbar button.| -|[CMFCToolBar::IsLocked](#islocked)|Determines whether the toolbar is locked.| -|[CMFCToolBar::IsOneRowWithSibling](#isonerowwithsibling)|Determines whether the toolbar and its sibling toolbar are positioned on the same row.| -|[CMFCToolBar::IsUserDefined](#isuserdefined)|Specifies whether the toolbar is user-defined.| -|[CMFCToolBar::LoadBitmap](#loadbitmap)|Loads toolbar images from application resources.| -|[CMFCToolBar::LoadBitmapEx](#loadbitmapex)|Loads toolbar images from application resources. Includes large images.| -|[CMFCToolBar::LoadParameters](#loadparameters)|Loads global toolbar options from the Windows registry.| -|[CMFCToolBar::LoadState](#loadstate)|Loads the toolbar state information from the Windows registry. (Overrides [CPane::LoadState](../../mfc/reference/cpane-class.md#loadstate).)| -|[CMFCToolBar::LoadToolBar](#loadtoolbar)|Loads the toolbar from application resources.| -|[CMFCToolBar::LoadToolBarEx](#loadtoolbarex)|Loads the toolbar from application resources by using the `CMFCToolBarInfo` helper class to enable the application to use large images.| -|[CMFCToolBar::OnChangeHot](#onchangehot)|Called by the framework when a user selects a button on the toolbar.| -|[CMFCToolBar::OnFillBackground](#onfillbackground)|Called by the framework from [CBasePane::DoPaint](../../mfc/reference/cbasepane-class.md#dopaint) to fill the toolbar background.| -|[CMFCToolBar::OnReset](#onreset)|Restores the toolbar to its original state.| -|[CMFCToolBar::OnSetAccData](#onsetaccdata)|(Overrides [CBasePane::OnSetAccData](../../mfc/reference/cbasepane-class.md#onsetaccdata).)| -|[CMFCToolBar::OnSetDefaultButtonText](#onsetdefaultbuttontext)|Restores the text of a toolbar button to its default state.| +|[`CMFCToolBar::AddBasicCommand`](#addbasiccommand)|Adds a menu command to the list of commands that are always displayed when a user opens a menu.| +|[`CMFCToolBar::AddCommandUsage`](#addcommandusage)|Increments by one the counter that is associated with the given command.| +|[`CMFCToolBar::AddToolBarForImageCollection`](#addtoolbarforimagecollection)|Adds images from the user interface resources to the collection of images in the application.| +|[`CMFCToolBar::AdjustLayout`](#adjustlayout)|Recalculates the size and position of a toolbar. (Overrides [`CBasePane::AdjustLayout`](../../mfc/reference/cbasepane-class.md#adjustlayout)).| +|[`CMFCToolBar::AdjustSize`](#adjustsize)|Recalculates the size of the toolbar.| +|[`CMFCToolBar::AllowChangeTextLabels`](#allowchangetextlabels)|Specifies whether text labels can be shown under images on the toolbar buttons.| +|[`CMFCToolBar::AreTextLabels`](#aretextlabels)|Specifies whether text labels under images are currently displayed on the toolbar buttons.| +|[`CMFCToolBar::AutoGrayInactiveImages`](#autograyinactiveimages)|Enable or disables the automatic generation of inactive button images.| +|[`CMFCToolBar::ButtonToIndex`](#buttontoindex)|Returns the index of a specified [`CMFCToolBarButton` Class](../../mfc/reference/cmfctoolbarbutton-class.md) object in this toolbar.| +|[`CMFCToolBar::CalcFixedLayout`](#calcfixedlayout)|Calculates the horizontal size of the toolbar. (Overrides [`CBasePane::CalcFixedLayout`](../../mfc/reference/cbasepane-class.md#calcfixedlayout).)| +|[`CMFCToolBar::CalcSize`](#calcsize)|Called by the framework as part of the layout calculation process. (Overrides [`CPane::CalcSize`](../../mfc/reference/cpane-class.md#calcsize).)| +|[`CMFCToolBar::CanHandleSiblings`](#canhandlesiblings)|Determines whether the toolbar and its sibling are positioned on the same pane.| +|[`CMFCToolBar::CleanUpImages`](#cleanupimages)|Frees the system resources allocated for toolbar images.| +|[`CMFCToolBar::CleanUpLockedImages`](#cleanuplockedimages)|Frees the system resources allocated for locked toolbar images.| +|[`CMFCToolBar::CanBeClosed`](#canbeclosed)|Specifies whether a user can close the toolbar. (Overrides [`CBasePane::CanBeClosed`](../../mfc/reference/cbasepane-class.md#canbeclosed).)| +|[`CMFCToolBar::CanBeRestored`](#canberestored)|Determines whether the system can restore a toolbar to its original state after customization.| +|[`CMFCToolBar::CanFocus`](#canfocus)|Specifies whether the pane can receive focus. (Overrides [`CBasePane::CanFocus`](../../mfc/reference/cbasepane-class.md#canfocus).)| +|[`CMFCToolBar::CanHandleSiblings`](#canhandlesiblings)|Determines whether the toolbar and its sibling are positioned on the same pane.| +|[`CMFCToolBar::CommandToIndex`](#commandtoindex)|Returns the index of the button in the toolbar with a specified command ID.| +|[`CMFCToolBar::Create`](#create)|Creates a `CMFCToolBar` object.| +|[`CMFCToolBar::CreateEx`](#createex)|Creates a `CMFCToolBar` object that uses additional style options, such as large icons.| +|[`CMFCToolBar::Deactivate`](#deactivate)|Deactivates the toolbar.| +|[`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton)|Enables or disables the **Add or Remove Buttons** button that appears on the end of the toolbar.| +|[`CMFCToolBar::EnableDocking`](#enabledocking)|Enables docking of the pane to the main frame. (Overrides [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking).)| +|[`CMFCToolBar::EnableLargeIcons`](#enablelargeicons)|Enables or disables large icons on toolbar buttons.| +|[`CMFCToolBar::EnableQuickCustomization`](#enablequickcustomization)|Enables or disables the quick customization of toolbars so that the user can press the **Alt** key and drag a button to a new location.| +|[`CMFCToolBar::EnableReflections`](#enablereflections)|Enables or disables command reflection.| +|[`CMFCToolBar::EnableTextLabels`](#enabletextlabels)|Enables or disables text labels under toolbar button images.| +|[`CMFCToolBar::FromHandlePermanent`](#fromhandlepermanent)|Retrieves a pointer to the `CMFCToolBar` object that contains the given window handle.| +|[`CMFCToolBar::GetAllButtons`](#getallbuttons)|Returns a read-only list of buttons in a toolbar.| +|[`CMFCToolBar::GetAllToolbars`](#getalltoolbars)|Returns a read-only list of all toolbars in the application.| +|[`CMFCToolBar::GetBasicCommands`](#getbasiccommands)|Returns a read-only list of the basic commands defined in the application.| +|[`CMFCToolBar::GetButton`](#getbutton)|Returns a pointer to the `CMFCToolBarButton` object that has a specified toolbar button index.| +|[`CMFCToolBar::GetButtonInfo`](#getbuttoninfo)|Returns the command ID, style, and image index of the button at a specified index.| +|[`CMFCToolBar::GetButtonSize`](#getbuttonsize)|Returns the dimensions of each button on the toolbar.| +|[`CMFCToolBar::GetButtonStyle`](#getbuttonstyle)|Returns the current style of the toolbar button that is located at the specified index.| +|[`CMFCToolBar::GetButtonText`](#getbuttontext)|Returns the text label of a button that has a specified index.| +|[`CMFCToolBar::GetColdImages`](#getcoldimages)|Returns a pointer to the collection of cold toolbar button images in the application.| +|[`CMFCToolBar::GetColumnWidth`](#getcolumnwidth)|Returns the width of the toolbar buttons.| +|[`CMFCToolBar::GetCommandButtons`](#getcommandbuttons)|Returns a list of buttons that have a specified command ID from all toolbars in the application.| +|[`CMFCToolBar::GetCount`](#getcount)|Returns the number of buttons and separators on the toolbar.| +|[`CMFCToolBar::GetCustomizeButton`](#getcustomizebutton)|Retrieves a pointer to the `CMFCCustomizeButton` object that is associated with the toolbar.| +|[`CMFCToolBar::GetDefaultImage`](#getdefaultimage)|Returns the index of the default image for a toolbar button with a specified command ID.| +|[`CMFCToolBar::GetDisabledImages`](#getdisabledimages)|Returns a pointer to the collection of images that are used for disabled toolbar buttons in the application.| +|[`CMFCToolBar::GetDisabledMenuImages`](#getdisabledmenuimages)|Returns a pointer to the collection of images that are used for disabled menu buttons in the application.| +|[`CMFCToolBar::GetDroppedDownMenu`](#getdroppeddownmenu)|Retrieves a pointer to the menu button object that is currently displaying its sub-menu.| +|[`CMFCToolBar::GetGrayDisabledButtons`](#getgraydisabledbuttons)|Specifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images.| +|[`CMFCToolBar::GetHighlightedButton`](#gethighlightedbutton)|Returns a pointer to the toolbar button that is currently highlighted.| +|[`CMFCToolBar::GetHotBorder`](#gethotborder)|Determines whether the toolbar buttons are hot-tracked.| +|[`CMFCToolBar::GetHotTextColor`](#gethottextcolor)|Returns the text color of the highlighted toolbar buttons.| +|[`CMFCToolBar::GetHwndLastFocus`](#gethwndlastfocus)|Returns a handle to the window that had the input focus just before the toolbar did.| +|[`CMFCToolBar::GetIgnoreSetText`](#getignoresettext)|Specifies whether calls to set button labels are ignored.| +|[`CMFCToolBar::GetImageSize`](#getimagesize)|Returns the current size of toolbar button images.| +|[`CMFCToolBar::GetImages`](#getimages)|Returns a pointer to the collection of default button images in the application.| +|[`CMFCToolBar::GetImagesOffset`](#getimagesoffset)|Returns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images.| +|[`CMFCToolBar::GetInvalidateItemRect`](#getinvalidateitemrect)|Retrieves the region of the client area that must be redrawn for the button at the given index.| +|[`CMFCToolBar::GetItemID`](#getitemid)|Returns the command ID of the toolbar button at a specified index.| +|[`CMFCToolBar::GetItemRect`](#getitemrect)|Returns the bounding rectangle of the button at a specified index.| +|[`CMFCToolBar::GetLargeColdImages`](#getlargecoldimages)|Returns a pointer to the collection of large cold toolbar button images in the application.| +|[`CMFCToolBar::GetLargeDisabledImages`](#getlargedisabledimages)|Returns a pointer to the collection of large disabled toolbar button images in the application.| +|[`CMFCToolBar::GetLargeImages`](#getlargeimages)|Returns a pointer to the collection of large toolbar button images in the application.| +|[`CMFCToolBar::GetLockedColdImages`](#getlockedcoldimages)|Returns a pointer to the collection of locked cold images in the toolbar.| +|[`CMFCToolBar::GetLockedDisabledImages`](#getlockeddisabledimages)|Returns a pointer to the collection of locked disabled images in the toolbar.| +|[`CMFCToolBar::GetLockedImages`](#getlockedimages)|Returns a pointer to the collection of locked button images in the toolbar.| +|[`CMFCToolBar::GetLockedImageSize`](#getlockedimagesize)|Returns the default size of locked toolbar images.| +|[`CMFCToolBar::GetLockedMenuImages`](#getlockedmenuimages)|Returns a pointer to the collection of locked toolbar menu images in the toolbar.| +|[`CMFCToolBar::GetMenuButtonSize`](#getmenubuttonsize)|Returns the size of menu buttons in the application.| +|[`CMFCToolBar::GetMenuImageSize`](#getmenuimagesize)|Returns the size of menu button images in the application.| +|[`CMFCToolBar::GetMenuImages`](#getmenuimages)|Returns a pointer to the collection of menu button images in the application.| +|[`CMFCToolBar::GetOrigButtons`](#getorigbuttons)|Retrieves the collection of non-customized buttons of the toolbar.| +|[`CMFCToolBar::GetOrigResetButtons`](#getorigresetbuttons)|Retrieves the collection of non-customized reset buttons of the toolbar.| +|[`CMFCToolBar::GetResourceID`](#getresourceid)|Retrieves the resource ID of the toolbar.| +|[`CMFCToolBar::GetRouteCommandsViaFrame`](#getroutecommandsviaframe)|Determines which object, the parent frame or the owner, sends commands to the toolbar.| +|[`CMFCToolBar::GetRowHeight`](#getrowheight)|Returns the height of toolbar buttons.| +|[`CMFCToolBar::GetShowTooltips`](#getshowtooltips)|Specifies whether tool tips are displayed for toolbar buttons.| +|[`CMFCToolBar::GetSiblingToolBar`](#getsiblingtoolbar)|Retrieves the sibling of the toolbar.| +|[`CMFCToolBar::GetUserImages`](#getuserimages)|Returns a pointer to the collection of user-defined toolbar button images in the application.| +|[`CMFCToolBar::HitTest`](#hittest)|Returns the index of the toolbar button that is located at the specified position.| +|[`CMFCToolBar::InsertButton`](#insertbutton)|Inserts a button into the toolbar.| +|[`CMFCToolBar::InsertSeparator`](#insertseparator)|Inserts a separator into the toolbar.| +|[`CMFCToolBar::InvalidateButton`](#invalidatebutton)|Invalidates the client area of the toolbar button that exists at the provided index.| +|[`CMFCToolBar::IsAddRemoveQuickCustomize`](#isaddremovequickcustomize)|Determines whether a user can add or remove toolbar buttons by using the **Customize** menu option.| +|[`CMFCToolBar::IsAltCustomizeMode`](#isaltcustomizemode)|Specifies whether *quick customization* is being used to drag a button.| +|[`CMFCToolBar::IsAutoGrayInactiveImages`](#isautograyinactiveimages)|Specifies whether the automatic generation of inactive (non-highlighted) button images is enabled.| +|[`CMFCToolBar::IsBasicCommand`](#isbasiccommand)|Determines whether a command is on the list of basic commands.| +|[`CMFCToolBar::IsButtonExtraSizeAvailable`](#isbuttonextrasizeavailable)|Determines whether the toolbar can display buttons that have extended borders.| +|[`CMFCToolBar::IsButtonHighlighted`](#isbuttonhighlighted)|Determines whether a button on the toolbar is highlighted.| +|[`CMFCToolBar::IsCommandPermitted`](#iscommandpermitted)|Determines whether a command is permitted.| +|[`CMFCToolBar::IsCommandRarelyUsed`](#iscommandrarelyused)|Determines whether a command is rarely used (see [`CMFCToolBar::SetCommandUsageOptions`](#setcommandusageoptions)).| +|[`CMFCToolBar::IsCustomizeMode`](#iscustomizemode)|Specifies whether the toolbar framework is in customization mode.| +|[`CMFCToolBar::IsDragButton`](#isdragbutton)|Determines whether a toolbar button is being dragged.| +|[`CMFCToolBar::IsExistCustomizeButton`](#isexistcustomizebutton)|Determines whether the toolbar contains the **Customize** button.| +|[`CMFCToolBar::IsFloating`](#isfloating)|Determines whether the toolbar is floating.| +|[`CMFCToolBar::IsLargeIcons`](#islargeicons)|Specifies whether toolbars in the application currently display large icons.| +|[`CMFCToolBar::IsLastCommandFromButton`](#islastcommandfrombutton)|Determines whether the most recently executed command was sent from the specified toolbar button.| +|[`CMFCToolBar::IsLocked`](#islocked)|Determines whether the toolbar is locked.| +|[`CMFCToolBar::IsOneRowWithSibling`](#isonerowwithsibling)|Determines whether the toolbar and its sibling toolbar are positioned on the same row.| +|[`CMFCToolBar::IsUserDefined`](#isuserdefined)|Specifies whether the toolbar is user-defined.| +|[`CMFCToolBar::LoadBitmap`](#loadbitmap)|Loads toolbar images from application resources.| +|[`CMFCToolBar::LoadBitmapEx`](#loadbitmapex)|Loads toolbar images from application resources. Includes large images.| +|[`CMFCToolBar::LoadParameters`](#loadparameters)|Loads global toolbar options from the Windows registry.| +|[`CMFCToolBar::LoadState`](#loadstate)|Loads the toolbar state information from the Windows registry. (Overrides [`CPane::LoadState`](../../mfc/reference/cpane-class.md#loadstate).)| +|[`CMFCToolBar::LoadToolBar`](#loadtoolbar)|Loads the toolbar from application resources.| +|[`CMFCToolBar::LoadToolBarEx`](#loadtoolbarex)|Loads the toolbar from application resources by using the `CMFCToolBarInfo` helper class to enable the application to use large images.| +|[`CMFCToolBar::OnChangeHot`](#onchangehot)|Called by the framework when a user selects a button on the toolbar.| +|[`CMFCToolBar::OnFillBackground`](#onfillbackground)|Called by the framework from [`CBasePane::DoPaint`](../../mfc/reference/cbasepane-class.md#dopaint) to fill the toolbar background.| +|[`CMFCToolBar::OnReset`](#onreset)|Restores the toolbar to its original state.| +|[`CMFCToolBar::OnSetAccData`](#onsetaccdata)|(Overrides [`CBasePane::OnSetAccData`](../../mfc/reference/cbasepane-class.md#onsetaccdata).)| +|[`CMFCToolBar::OnSetDefaultButtonText`](#onsetdefaultbuttontext)|Restores the text of a toolbar button to its default state.| |`CMFCToolBar::OnUpdateCmdUI`|Used internally.| -|[CMFCToolBar::RemoveAllButtons](#removeallbuttons)|Removes all buttons from the toolbar.| -|[CMFCToolBar::RemoveButton](#removebutton)|Removes the button with the specified index from the toolbar.| -|[CMFCToolBar::RemoveStateFromRegistry](#removestatefromregistry)|Deletes the state information for the toolbar from the Windows registry.| -|[CMFCToolBar::ReplaceButton](#replacebutton)|Replaces a toolbar button with another toolbar button.| -|[CMFCToolBar::ResetAll](#resetall)|Restores all toolbars to their original states.| -|[CMFCToolBar::ResetAllImages](#resetallimages)|Clears all toolbar image collections in the application.| -|[CMFCToolBar::RestoreOriginalState](#restoreoriginalstate)|Restores the original state of a toolbar.| -|[CMFCToolBar::SaveState](#savestate)|Saves the state information for the toolbar in the Windows registry. (Overrides [CPane::SaveState](../../mfc/reference/cpane-class.md#savestate).)| +|[`CMFCToolBar::RemoveAllButtons`](#removeallbuttons)|Removes all buttons from the toolbar.| +|[`CMFCToolBar::RemoveButton`](#removebutton)|Removes the button with the specified index from the toolbar.| +|[`CMFCToolBar::RemoveStateFromRegistry`](#removestatefromregistry)|Deletes the state information for the toolbar from the Windows registry.| +|[`CMFCToolBar::ReplaceButton`](#replacebutton)|Replaces a toolbar button with another toolbar button.| +|[`CMFCToolBar::ResetAll`](#resetall)|Restores all toolbars to their original states.| +|[`CMFCToolBar::ResetAllImages`](#resetallimages)|Clears all toolbar image collections in the application.| +|[`CMFCToolBar::RestoreOriginalState`](#restoreoriginalstate)|Restores the original state of a toolbar.| +|[`CMFCToolBar::SaveState`](#savestate)|Saves the state information for the toolbar in the Windows registry. (Overrides [`CPane::SaveState`](../../mfc/reference/cpane-class.md#savestate).)| |`CMFCToolBar::Serialize`|(Overrides `CBasePane::Serialize`.)| -|[CMFCToolBar::SetBasicCommands](#setbasiccommands)|Sets the list of commands that are always displayed when a user opens a menu.| -|[CMFCToolBar::SetButtonInfo](#setbuttoninfo)|Sets the command ID, style, and image ID of a toolbar button.| -|[CMFCToolBar::SetButtonStyle](#setbuttonstyle)|Sets the style of the toolbar button at the given index.| -|[CMFCToolBar::SetButtonText](#setbuttontext)|Sets the text label of a toolbar button.| -|[CMFCToolBar::SetButtons](#setbuttons)|Sets the buttons for the toolbar.| -|[CMFCToolBar::SetCommandUsageOptions](#setcommandusageoptions)|Specifies when rarely used commands do not appear in the menu of the application.| -|[CMFCToolBar::SetCustomizeMode](#setcustomizemode)|Enables or disables customization mode for all toolbars in the application.| -|[CMFCToolBar::SetGrayDisabledButtons](#setgraydisabledbuttons)|Specifies whether the disabled buttons on the toolbar are dimmed or if disabled images are used for the disabled buttons.| -|[CMFCToolBar::SetHeight](#setheight)|Sets the height of the toolbar.| -|[CMFCToolBar::SetHotBorder](#sethotborder)|Specifies whether toolbar buttons are hot-tracked.| -|[CMFCToolBar::SetHotTextColor](#sethottextcolor)|Sets the text color for hot toolbar buttons.| -|[CMFCToolBar::SetLargeIcons](#setlargeicons)|Specifies whether toolbar buttons display large icons.| -|[CMFCToolBar::SetLockedSizes](#setlockedsizes)|Sets the sizes of locked buttons and locked images on the toolbar.| -|[CMFCToolBar::SetMenuSizes](#setmenusizes)|Sets the size of toolbar menu buttons and their images.| -|[CMFCToolBar::SetNonPermittedCommands](#setnonpermittedcommands)|Sets the list of commands that cannot be executed by the user.| -|[CMFCToolBar::SetOneRowWithSibling](#setonerowwithsibling)|Positions the toolbar and its sibling on the same row.| -|[CMFCToolBar::SetPermament](#setpermament)|Specifies whether a user can close the toolbar.| -|[CMFCToolBar::SetRouteCommandsViaFrame](#setroutecommandsviaframe)|Specifies whether the parent frame or the owner sends commands to the toolbar.| -|[CMFCToolBar::SetShowTooltips](#setshowtooltips)|Specifies whether the framework displays tool tips.| -|[CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar)|Specifies the sibling of the toolbar.| -|[CMFCToolBar::SetSizes](#setsizes)|Specifies the sizes of buttons and images on all toolbars.| -|[CMFCToolBar::SetToolBarBtnText](#settoolbarbtntext)|Specifies properties of a button on the toolbar.| -|[CMFCToolBar::SetTwoRowsWithSibling](#settworowswithsibling)|Positions the toolbar and its sibling on separate rows.| -|[CMFCToolBar::SetUserImages](#setuserimages)|Sets the collection of user-defined images in the application.| -|[CMFCToolBar::StretchPane](#stretchpane)|Stretches the toolbar vertically or horizontally. (Overrides [CBasePane::StretchPane](../../mfc/reference/cbasepane-class.md#stretchpane).)| -|[CMFCToolBar::TranslateChar](#translatechar)|Executes a button command if the specified key code corresponds to a valid keyboard shortcut.| -|[CMFCToolBar::UpdateButton](#updatebutton)|Updates the state of the specified button.| -|[CMFCToolBar::WrapToolBar](#wraptoolbar)|Repositions toolbar buttons within the given dimensions.| +|[`CMFCToolBar::SetBasicCommands`](#setbasiccommands)|Sets the list of commands that are always displayed when a user opens a menu.| +|[`CMFCToolBar::SetButtonInfo`](#setbuttoninfo)|Sets the command ID, style, and image ID of a toolbar button.| +|[`CMFCToolBar::SetButtonStyle`](#setbuttonstyle)|Sets the style of the toolbar button at the given index.| +|[`CMFCToolBar::SetButtonText`](#setbuttontext)|Sets the text label of a toolbar button.| +|[`CMFCToolBar::SetButtons`](#setbuttons)|Sets the buttons for the toolbar.| +|[`CMFCToolBar::SetCommandUsageOptions`](#setcommandusageoptions)|Specifies when rarely used commands do not appear in the menu of the application.| +|[`CMFCToolBar::SetCustomizeMode`](#setcustomizemode)|Enables or disables customization mode for all toolbars in the application.| +|[`CMFCToolBar::SetGrayDisabledButtons`](#setgraydisabledbuttons)|Specifies whether the disabled buttons on the toolbar are dimmed or if disabled images are used for the disabled buttons.| +|[`CMFCToolBar::SetHeight`](#setheight)|Sets the height of the toolbar.| +|[`CMFCToolBar::SetHotBorder`](#sethotborder)|Specifies whether toolbar buttons are hot-tracked.| +|[`CMFCToolBar::SetHotTextColor`](#sethottextcolor)|Sets the text color for hot toolbar buttons.| +|[`CMFCToolBar::SetLargeIcons`](#setlargeicons)|Specifies whether toolbar buttons display large icons.| +|[`CMFCToolBar::SetLockedSizes`](#setlockedsizes)|Sets the sizes of locked buttons and locked images on the toolbar.| +|[`CMFCToolBar::SetMenuSizes`](#setmenusizes)|Sets the size of toolbar menu buttons and their images.| +|[`CMFCToolBar::SetNonPermittedCommands`](#setnonpermittedcommands)|Sets the list of commands that cannot be executed by the user.| +|[`CMFCToolBar::SetOneRowWithSibling`](#setonerowwithsibling)|Positions the toolbar and its sibling on the same row.| +|[`CMFCToolBar::SetPermament`](#setpermament)|Specifies whether a user can close the toolbar.| +|[`CMFCToolBar::SetRouteCommandsViaFrame`](#setroutecommandsviaframe)|Specifies whether the parent frame or the owner sends commands to the toolbar.| +|[`CMFCToolBar::SetShowTooltips`](#setshowtooltips)|Specifies whether the framework displays tool tips.| +|[`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar)|Specifies the sibling of the toolbar.| +|[`CMFCToolBar::SetSizes`](#setsizes)|Specifies the sizes of buttons and images on all toolbars.| +|[`CMFCToolBar::SetToolBarBtnText`](#settoolbarbtntext)|Specifies properties of a button on the toolbar.| +|[`CMFCToolBar::SetTwoRowsWithSibling`](#settworowswithsibling)|Positions the toolbar and its sibling on separate rows.| +|[`CMFCToolBar::SetUserImages`](#setuserimages)|Sets the collection of user-defined images in the application.| +|[`CMFCToolBar::StretchPane`](#stretchpane)|Stretches the toolbar vertically or horizontally. (Overrides [`CBasePane::StretchPane`](../../mfc/reference/cbasepane-class.md#stretchpane).)| +|[`CMFCToolBar::TranslateChar`](#translatechar)|Executes a button command if the specified key code corresponds to a valid keyboard shortcut.| +|[`CMFCToolBar::UpdateButton`](#updatebutton)|Updates the state of the specified button.| +|[`CMFCToolBar::WrapToolBar`](#wraptoolbar)|Repositions toolbar buttons within the given dimensions.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CMFCToolBar::AllowShowOnList](#allowshowonlist)|Determines whether the toolbar is displayed in the list on the **Toolbars** pane of the **Customize** dialog box.| -|[CMFCToolBar::CalcMaxButtonHeight](#calcmaxbuttonheight)|Calculates the maximum height of a button in the toolbar.| -|[CMFCToolBar::DoPaint](#dopaint)|Repaints a toolbar.| -|[CMFCToolBar::DrawButton](#drawbutton)|Repaints a toolbar button.| -|[CMFCToolBar::DrawSeparator](#drawseparator)|Repaints a separator on a toolbar.| -|[CMFCToolBar::OnUserToolTip](#onusertooltip)|Called by the framework when the tooltip for a button is about to be displayed.| +|[`CMFCToolBar::AllowShowOnList`](#allowshowonlist)|Determines whether the toolbar is displayed in the list on the **Toolbars** pane of the **Customize** dialog box.| +|[`CMFCToolBar::CalcMaxButtonHeight`](#calcmaxbuttonheight)|Calculates the maximum height of a button in the toolbar.| +|[`CMFCToolBar::DoPaint`](#dopaint)|Repaints a toolbar.| +|[`CMFCToolBar::DrawButton`](#drawbutton)|Repaints a toolbar button.| +|[`CMFCToolBar::DrawSeparator`](#drawseparator)|Repaints a separator on a toolbar.| +|[`CMFCToolBar::OnUserToolTip`](#onusertooltip)|Called by the framework when the tooltip for a button is about to be displayed.| ### Data Members |Name|Description| |----------|-----------------| -|[CMFCToolBar::m_bDontScaleImages](#m_bdontscaleimages)|Specifies whether to scale or not toolbar images in high DPI mode.| -|[CMFCToolBar::m_dblLargeImageRatio](#m_dbllargeimageratio)|Specifies the ratio between the dimension (height or width) of large images and the dimension of regular images.| +|[`CMFCToolBar::m_bDontScaleImages`](#m_bdontscaleimages)|Specifies whether to scale or not toolbar images in high DPI mode.| +|[`CMFCToolBar::m_dblLargeImageRatio`](#m_dbllargeimageratio)|Specifies the ratio between the dimension (height or width) of large images and the dimension of regular images.| ## Remarks @@ -203,13 +202,13 @@ To incorporate a `CMFCToolBar` object into your application, follow these steps: 1. Add a `CMFCToolBar` object to the main frame window. -1. When you process the WM_CREATE message for the main frame window, call either [CMFCToolBar::Create](#create) or [CMFCToolBar::CreateEx](#createex) to create the toolbar and specify its style. +1. When you process the WM_CREATE message for the main frame window, call either [`CMFCToolBar::Create`](#create) or [`CMFCToolBar::CreateEx`](#createex) to create the toolbar and specify its style. -1. Call [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking) to specify the docking style. +1. Call [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking) to specify the docking style. -To insert a special button, such as a combo box or drop-down toolbar, reserve a dummy button in the parent resource, and replace the dummy button at runtime by using [CMFCToolBar::ReplaceButton](#replacebutton). For more information, see [Walkthrough: Putting Controls On Toolbars](../walkthrough-putting-controls-on-toolbars.md). +To insert a special button, such as a combo box or drop-down toolbar, reserve a dummy button in the parent resource, and replace the dummy button at runtime by using [`CMFCToolBar::ReplaceButton`](#replacebutton). For more information, see [Walkthrough: Putting Controls On Toolbars](../walkthrough-putting-controls-on-toolbars.md). -`CMFCToolBar` is the base class for the MFC Library classes [CMFCMenuBar Class](../../mfc/reference/cmfcmenubar-class.md), [CMFCPopupMenuBar Class](../../mfc/reference/cmfcpopupmenubar-class.md), and [CMFCDropDownToolBar Class](../../mfc/reference/cmfcdropdowntoolbar-class.md). +`CMFCToolBar` is the base class for the MFC Library classes [`CMFCMenuBar` Class](../../mfc/reference/cmfcmenubar-class.md), [`CMFCPopupMenuBar` Class](../../mfc/reference/cmfcpopupmenubar-class.md), and [`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md). ## Example @@ -220,25 +219,25 @@ The following example demonstrates how to use various methods in the `CMFCToolBa ## Requirements -**Header:** afxtoolbar.h +**Header:** `afxtoolbar.h` ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CBasePane](../../mfc/reference/cbasepane-class.md) +[`CBasePane`](../../mfc/reference/cbasepane-class.md) -[CPane](../../mfc/reference/cpane-class.md) +[`CPane`](../../mfc/reference/cpane-class.md) -[CMFCBaseToolBar](../../mfc/reference/cmfcbasetoolbar-class.md) +[`CMFCBaseToolBar`](../../mfc/reference/cmfcbasetoolbar-class.md) `CMFCToolBar` -## CMFCToolBar::AddBasicCommand +## `CMFCToolBar::AddBasicCommand` Adds a menu command to the list of commands that are always displayed when a user opens a menu. @@ -248,16 +247,16 @@ static void __stdcall AddBasicCommand(UINT uiCmd); ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] Specifies the command to add. ### Remarks A basic command is always displayed when the menu is opened. This method is meaningful when the user chooses to view recently used commands. -Use the [CMFCToolBar::SetBasicCommands](#setbasiccommands) method to set the list of commands that are always displayed when a user opens a menu. Use the [CMFCToolBar::GetBasicCommands](#getbasiccommands) method to retrieve the list of basic commands that is used by your application. +Use the [`CMFCToolBar::SetBasicCommands`](#setbasiccommands) method to set the list of commands that are always displayed when a user opens a menu. Use the [`CMFCToolBar::GetBasicCommands`](#getbasiccommands) method to retrieve the list of basic commands that is used by your application. -## CMFCToolBar::AddCommandUsage +## `CMFCToolBar::AddCommandUsage` Increments by one the counter that is associated with the given command. @@ -267,7 +266,7 @@ static void __stdcall AddCommandUsage(UINT uiCommand); ### Parameters -*uiCommand*
+*`uiCommand`*\ [in] Specifies the command counter to increment. ### Remarks @@ -276,9 +275,9 @@ The framework calls this method when the user selects a menu item. The framework uses command counters to display recently used menu items. -This method increments the command counter by using the [CMFCCmdUsageCount::AddCmd](../../mfc/reference/cmfccmdusagecount-class.md#addcmd) method. +This method increments the command counter by using the [`CMFCCmdUsageCount::AddCmd`](../../mfc/reference/cmfccmdusagecount-class.md#addcmd) method. -## CMFCToolBar::AddToolBarForImageCollection +## `CMFCToolBar::AddToolBarForImageCollection` Adds images from the user interface resources to the collection of images in the application. @@ -294,33 +293,33 @@ static BOOL __stdcall AddToolBarForImageCollection( ### Parameters -*uiResID*
+*`uiResID`*\ [in] Resource ID of a toolbar with images to load. -*uiBmpResID*
+*`uiBmpResID`*\ [in] Resource ID of a bitmap with toolbar images. -*uiColdResID*
+*`uiColdResID`*\ [in] Resource ID of a bitmap with "cold" toolbar images. -*uiMenuResID*
+*`uiMenuResID`*\ [in] Resource ID of a bitmap with menu images. -*uiDisabledResID*
+*`uiDisabledResID`*\ [in] Resource ID of a bitmap with disabled toolbar images. -*uiMenuDisabledResID*
+*`uiMenuDisabledResID`*\ [in] Resource ID of a bitmap with disabled menu images. ### Return Value -TRUE if the method succeeds; FALSE if *uiResID* or *uiBmpResID* do not specify valid resources, or another error occurs. +`TRUE` if the method succeeds; `FALSE` if *`uiResID`* or *`uiBmpResID`* do not specify valid resources, or another error occurs. ### Remarks -Call this method to load a bitmap with toolbar images and add it to the collection of toolbar images. This method creates a temporary toolbar object and calls [CMFCToolBar::LoadToolBar](#loadtoolbar). +Call this method to load a bitmap with toolbar images and add it to the collection of toolbar images. This method creates a temporary toolbar object and calls [`CMFCToolBar::LoadToolBar`](#loadtoolbar). -## CMFCToolBar::AdjustLayout +## `CMFCToolBar::AdjustLayout` Recalculates the size and position of a toolbar. @@ -336,7 +335,7 @@ The framework calls this method every time that the layout of the toolbar must b Override this method to provide your own dynamic layout in classes that you derive from `CMFCToolbar`. -## CMFCToolBar::AdjustSize +## `CMFCToolBar::AdjustSize` Recalculates the size of the toolbar. @@ -348,9 +347,9 @@ void AdjustSize(); This method makes sure that the toolbar fits in the bounds of the parent frame. This method does nothing if the toolbar has no parent frame. -The [CMFCToolBar::AdjustLayout](#adjustlayout) method calls this method to recalculate the size if the parent of the toolbar is not a `CMFCReBar` object. +The [`CMFCToolBar::AdjustLayout`](#adjustlayout) method calls this method to recalculate the size if the parent of the toolbar is not a `CMFCReBar` object. -## CMFCToolBar::AllowChangeTextLabels +## `CMFCToolBar::AllowChangeTextLabels` Specifies whether text labels can be shown under images on the toolbar buttons. @@ -360,17 +359,17 @@ virtual BOOL AllowChangeTextLabels() const; ### Return Value -TRUE if it is allowed to display text labels below images; otherwise FALSE. +`TRUE` if it is allowed to display text labels below images; otherwise `FALSE`. ### Remarks This method is called by the customization dialog box to determine whether to enable a **Show text labels** check-box on the **Toolbars** page for the selected toolbar. -The default implementation returns TRUE. +The default implementation returns `TRUE`. -Override this method in an object derived from `CMFCToolBar` and return FALSE when you do not want the user to decide whether text labels are displayed on toolbar buttons under the images. +Override this method in an object derived from `CMFCToolBar` and return `FALSE` when you do not want the user to decide whether text labels are displayed on toolbar buttons under the images. -## CMFCToolBar::AllowShowOnList +## `CMFCToolBar::AllowShowOnList` Determines whether the toolbar is displayed in the list of toolbars on the **Toolbars** pane of the **Customize** dialog box. @@ -380,15 +379,15 @@ virtual BOOL AllowShowOnList() const; ### Return Value -TRUE if the toolbar object can be displayed in the list box on the toolbar customization page; otherwise FALSE. +`TRUE` if the toolbar object can be displayed in the list box on the toolbar customization page; otherwise `FALSE`. ### Remarks This method is called by the framework to determine whether the list on the toolbar customization page should include a particular object derived from `CMFCToolBar`. -The default implementation always returns TRUE. Override this method when you do not want a toolbar to appear in the toolbars list in the customization dialog box. +The default implementation always returns `TRUE`. Override this method when you do not want a toolbar to appear in the toolbars list in the customization dialog box. -## CMFCToolBar::AreTextLabels +## `CMFCToolBar::AreTextLabels` Specifies whether text labels under images are currently displayed on the toolbar buttons. @@ -398,13 +397,13 @@ BOOL AreTextLabels() const; ### Return Value -TRUE if the toolbar buttons display text labels below images; otherwise FALSE. +`TRUE` if the toolbar buttons display text labels below images; otherwise `FALSE`. ### Remarks -Use [CMFCToolBar::EnableTextLabels](#enabletextlabels) to specify whether the text is displayed. The default value is FALSE. Call [CMFCToolBar::AllowChangeTextLabels](#allowchangetextlabels) to specify whether the user can change this setting in the customization dialog box. +Use [`CMFCToolBar::EnableTextLabels`](#enabletextlabels) to specify whether the text is displayed. The default value is `FALSE`. Call [`CMFCToolBar::AllowChangeTextLabels`](#allowchangetextlabels) to specify whether the user can change this setting in the customization dialog box. -## CMFCToolBar::AutoGrayInactiveImages +## `CMFCToolBar::AutoGrayInactiveImages` Enable or disables the automatic generation of inactive button images. @@ -417,24 +416,24 @@ static void AutoGrayInactiveImages( ### Parameters -*bEnable*
-[in] A Boolean value that specifies whether to dim inactive images. If this parameter is TRUE, inactive images are dimmed. Otherwise, inactive images are not dimmed. +*`bEnable`*\ +[in] A Boolean value that specifies whether to dim inactive images. If this parameter is `TRUE`, inactive images are dimmed. Otherwise, inactive images are not dimmed. -*nGrayImagePercentage*
-[in] Specifies the luminance percentage for inactive images. If *bEnable* is FALSE, this value is ignored. +*`nGrayImagePercentage`*\ +[in] Specifies the luminance percentage for inactive images. If *`bEnable`* is `FALSE`, this value is ignored. -*bRedrawAllToolbars*
-[in] A Boolean value that specifies whether to redraw all toolbars in the application. If this parameter is TRUE, this method redraws all toolbars. +*`bRedrawAllToolbars`*\ +[in] A Boolean value that specifies whether to redraw all toolbars in the application. If this parameter is `TRUE`, this method redraws all toolbars. ### Remarks -If *bEnable* is TRUE, the framework uses *nGrayImagePercentage* to generate inactive images from the regular images. Otherwise, you must provide the set of inactive images by using the [CMFCToolBar::GetColdImages](#getcoldimages) method. By default, this option is disabled. +If *`bEnable`* is `TRUE`, the framework uses *`nGrayImagePercentage`* to generate inactive images from the regular images. Otherwise, you must provide the set of inactive images by using the [`CMFCToolBar::GetColdImages`](#getcoldimages) method. By default, this option is disabled. -For more information about the *nGrayImagePercentage* parameter, see [CMFCToolBarImages::GrayImages](../../mfc/reference/cmfctoolbarimages-class.md#grayimages). +For more information about the *`nGrayImagePercentage`* parameter, see [`CMFCToolBarImages::GrayImages`](../../mfc/reference/cmfctoolbarimages-class.md#grayimages). -## CMFCToolBar::ButtonToIndex +## `CMFCToolBar::ButtonToIndex` -Returns the index of a specified [CMFCToolBarButton Class](../../mfc/reference/cmfctoolbarbutton-class.md) object in this toolbar. +Returns the index of a specified [`CMFCToolBarButton` Class](../../mfc/reference/cmfctoolbarbutton-class.md) object in this toolbar. ``` int ButtonToIndex(const CMFCToolBarButton* pButton) const; @@ -442,14 +441,14 @@ int ButtonToIndex(const CMFCToolBarButton* pButton) const; ### Parameters -*pButton*
+*`pButton`*\ [in] A pointer to the toolbar button object. ### Return Value -Index of *pButton* in the internal list of toolbar buttons; or -1 if the specified button is not on this toolbar. +Index of *`pButton`* in the internal list of toolbar buttons; or -1 if the specified button is not on this toolbar. -## CMFCToolBar::CalcFixedLayout +## `CMFCToolBar::CalcFixedLayout` Calculates the horizontal size of the toolbar. @@ -461,11 +460,11 @@ virtual CSize CalcFixedLayout( ### Parameters -*bStretch*
-[in] TRUE to stretch the toolbar to the size of the parent frame. +*`bStretch`*\ +[in] `TRUE` to stretch the toolbar to the size of the parent frame. -*bHorz*
-[in] TRUE to orient the toolbar horizontally; FALSE to orient the toolbar vertically. +*`bHorz`*\ +[in] `TRUE` to orient the toolbar horizontally; `FALSE` to orient the toolbar vertically. ### Return Value @@ -473,11 +472,11 @@ A `CSize` object that specifies the size of the toolbar. ### Remarks -This method calculates the size of the toolbar by using the `CMFCToolBar::CalcLayout` method. It passes the LM_STRETCH flag for the *dwMode* parameter if *bStretch* is TRUE. It passes the LM_HORZ flag if *bHorz* is TRUE. +This method calculates the size of the toolbar by using the `CMFCToolBar::CalcLayout` method. It passes the `LM_STRETCH` flag for the *`dwMode`* parameter if *`bStretch`* is `TRUE`. It passes the `LM_HORZ` flag if *`bHorz`* is `TRUE`. See the VisualStudioDemo sample for an example that uses this method. -## CMFCToolBar::CalcMaxButtonHeight +## `CMFCToolBar::CalcMaxButtonHeight` Calculates the maximum height of buttons in the toolbar. @@ -495,7 +494,7 @@ This method calculates the maximum height among all toolbar buttons on the toolb Override this method in a class derived from `CMFCToolBar` to provide your own height calculation. -## CMFCToolBar::CalcSize +## `CMFCToolBar::CalcSize` Called by the framework as part of the layout calculation process. @@ -505,8 +504,8 @@ virtual CSize CalcSize(BOOL bVertDock); ### Parameters -*bVertDock*
-[in] TRUE to specify that the toolbar is docked vertically; FALSE to specify that the toolbar is docked horizontally. +*`bVertDock`*\ +[in] `TRUE` to specify that the toolbar is docked vertically; `FALSE` to specify that the toolbar is docked horizontally. ### Return Value @@ -516,9 +515,9 @@ A `CSize` object that specifies the overall size of the buttons on the toolbar. This method considers the attributes that affect the size of each button, such as the area of the text label and the border size. -If the toolbar contains no buttons, this method returns the reserved size of a single button by using the [CMFCToolBar::GetButtonSize](#getbuttonsize) method. +If the toolbar contains no buttons, this method returns the reserved size of a single button by using the [`CMFCToolBar::GetButtonSize`](#getbuttonsize) method. -## CMFCToolBar::CanBeClosed +## `CMFCToolBar::CanBeClosed` Specifies whether a user can close the toolbar. @@ -528,15 +527,15 @@ virtual BOOL CanBeClosed() const; ### Return Value -TRUE if the toolbar can be closed by the user; otherwise FALSE. +`TRUE` if the toolbar can be closed by the user; otherwise `FALSE`. ### Remarks -The framework calls this method to determine whether the user can close a toolbar. If the method returns TRUE, the framework enables the SC_CLOSE command in the system menu of the toolbar and the user can close the toolbar by using a check box in the list of toolbars in the customization dialog box. +The framework calls this method to determine whether the user can close a toolbar. If the method returns `TRUE`, the framework enables the `SC_CLOSE` command in the system menu of the toolbar and the user can close the toolbar by using a check box in the list of toolbars in the customization dialog box. -The default implementation returns TRUE. Override this method in a class derived from `CMFCToolBar` to make toolbar objects that cannot be closed by the user. +The default implementation returns `TRUE`. Override this method in a class derived from `CMFCToolBar` to make toolbar objects that cannot be closed by the user. -## CMFCToolBar::CanBeRestored +## `CMFCToolBar::CanBeRestored` Determines whether the system can restore a toolbar to its original state after customization. @@ -546,19 +545,19 @@ virtual BOOL CanBeRestored() const; ### Return Value -TRUE if the toolbar can be restored from the application resources; otherwise FALSE. +`TRUE` if the toolbar can be restored from the application resources; otherwise `FALSE`. ### Remarks The framework calls this method to determine whether a toolbar can be returned to its original state after customization. The original state is loaded from the application resources. -If `CanBeRestored` returns TRUE, the **Toolbars** page of the customization dialog box enables the **Reset** button for the selected toolbar. +If `CanBeRestored` returns `TRUE`, the **Toolbars** page of the customization dialog box enables the **Reset** button for the selected toolbar. -The default implementation returns TRUE if the original resource ID of the toolbar when it was loaded is non-zero. Usually, only user-defined toolbars cannot be restored. +The default implementation returns `TRUE` if the original resource ID of the toolbar when it was loaded is non-zero. Usually, only user-defined toolbars cannot be restored. You can override the `CanBeRestored` method to customize this behavior in derived classes. -## CMFCToolBar::CanFocus +## `CMFCToolBar::CanFocus` Specifies whether the pane can receive focus. @@ -568,13 +567,13 @@ virtual BOOL CanFocus() const; ### Return Value -This method returns FALSE. +This method returns `FALSE`. ### Remarks -This method overrides the base class implementation, [CBasePane::CanFocus](../../mfc/reference/cbasepane-class.md#canfocus), because toolbar objects cannot receive focus. +This method overrides the base class implementation, [`CBasePane::CanFocus`](../../mfc/reference/cbasepane-class.md#canfocus), because toolbar objects cannot receive focus. -## CMFCToolBar::CanHandleSiblings +## `CMFCToolBar::CanHandleSiblings` Determines whether the toolbar and its sibling are positioned on the same pane. @@ -584,15 +583,15 @@ BOOL CanHandleSiblings(); ### Return Value -TRUE if the toolbar has a sibling and the toolbar and its sibling are positioned on the same pane; otherwise FALSE. +`TRUE` if the toolbar has a sibling and the toolbar and its sibling are positioned on the same pane; otherwise `FALSE`. ### Remarks -The internal CMFCCustomizeButton::CreatePopupMenu method calls this method to determine how to show the **Customize** pop-up menu. If this method returns TRUE, the framework displays the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. +The internal `CMFCCustomizeButton::CreatePopupMenu` method calls this method to determine how to show the **Customize** pop-up menu. If this method returns `TRUE`, the framework displays the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. -You typically do not have to use this method. To enable the **Customize** button that appears on the toolbar, call the [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton) method. To enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons, call [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar). +You typically do not have to use this method. To enable the **Customize** button that appears on the toolbar, call the [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton) method. To enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons, call [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar). -## CMFCToolBar::CleanUpImages +## `CMFCToolBar::CleanUpImages` Frees the system resources allocated for toolbar images. @@ -604,7 +603,7 @@ static void CMFCToolBar::CleanUpImages(); The framework calls this method when an application shuts down. -## CMFCToolBar::CleanUpLockedImages +## `CMFCToolBar::CleanUpLockedImages` Frees the system resources allocated for locked toolbar images. @@ -616,7 +615,7 @@ void CleanUpLockedImages(); Call this method when the visual style of your application changes. See the VisualStudioDemo sample for an example that uses this method. -## CMFCToolBar::CommandToIndex +## `CMFCToolBar::CommandToIndex` Returns the index of the button in the toolbar with a specified command ID. @@ -628,10 +627,10 @@ int CommandToIndex( ### Parameters -*nIDFind*
+*`nIDFind`*\ [in] Specifies the command ID. -*iIndexFirst*
+*`iIndexFirst`*\ [in] Specifies the initial index to start from. ### Return Value @@ -642,9 +641,9 @@ Zero-based index of the toolbar button if the method was successful; -1 if there A `CMFCToolBar` object maintains an internal list of the buttons on the toolbar. Call this function to retrieve the index of a button in the list given the command ID of the button. -If *iIndex* is greater than 0, this method ignores any button on the toolbar that has an index less than *iIndex*. +If *`iIndex`* is greater than 0, this method ignores any button on the toolbar that has an index less than *`iIndex`*. -## CMFCToolBar::Create +## `CMFCToolBar::Create` Creates a `CMFCToolBar` object. @@ -657,24 +656,24 @@ virtual BOOL Create( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ [in] A pointer to the parent window of the toolbar. -*dwStyle*
+*`dwStyle`*\ [in] The toolbar style. See [Toolbar Control and Button Styles](/windows/win32/Controls/toolbar-control-and-button-styles) in the Windows SDK for the list of styles. -*nID*
+*`nID`*\ [in] The ID of the child window of the toolbar. ### Return Value -TRUE if this method succeeds; otherwise FALSE. +`TRUE` if this method succeeds; otherwise `FALSE`. ### Remarks -This method creates a control bar and attaches it to the toolbar. It creates the control bar with the TBSTYLE_FLAT style. Call [CMFCToolBar::CreateEx](#createex) if you want a different control bar style. +This method creates a control bar and attaches it to the toolbar. It creates the control bar with the TBSTYLE_FLAT style. Call [`CMFCToolBar::CreateEx`](#createex) if you want a different control bar style. -## CMFCToolBar::CreateEx +## `CMFCToolBar::CreateEx` Creates a `CMFCToolBar` object that uses additional style options, such as large icons. @@ -692,19 +691,19 @@ virtual BOOL CreateEx( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ [in] A pointer to the parent window of the toolbar. -*dwCtrlStyle*
+*`dwCtrlStyle`*\ [in] Additional styles for creating the embedded control bar object. -*dwStyle*
+*`dwStyle`*\ [in] The toolbar style. See [Toolbar Control and Button Styles](/windows/win32/Controls/toolbar-control-and-button-styles) for a list of appropriate styles. -*rcBorders*
+*`rcBorders`*\ [in] A `CRect` object that specifies the widths of the toolbar window borders. -*nID*
+*`nID`*\ [in] The ID of the child window of the toolbar. ### Return Value @@ -715,7 +714,7 @@ Nonzero if this method succeeds; otherwise 0. This method creates a control bar and attaches it to the toolbar. -Call this method instead of [CMFCToolBar::Create](#create) when you want to provide specific styles. For example, set *dwCtrlStyle* to TBSTYLE_FLAT | TBSTYLE_TRANSPARENT to create a toolbar that resembles the toolbars that are used by Internet Explorer 4. +Call this method instead of [`CMFCToolBar::Create`](#create) when you want to provide specific styles. For example, set *`dwCtrlStyle`* to `TBSTYLE_FLAT` | `TBSTYLE_TRANSPARENT` to create a toolbar that resembles the toolbars that are used by Internet Explorer 4. ### Example @@ -724,7 +723,7 @@ The following example demonstrates how to use the `CreateEx` method of the `CMFC [!code-cpp[NVC_MFC_IEDemo#6](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_1.h)] [!code-cpp[NVC_MFC_IEDemo#7](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_3.cpp)] -## CMFCToolBar::Deactivate +## `CMFCToolBar::Deactivate` Deactivates the toolbar. @@ -736,7 +735,7 @@ virtual void Deactivate(); This method deactivates the toolbar by removing the focus from the highlighted toolbar button. The framework calls this method when the toolbar loses focus or is destroyed. -## CMFCToolBar::DoPaint +## `CMFCToolBar::DoPaint` Repaints a toolbar. @@ -746,7 +745,7 @@ virtual void DoPaint(CDC* pDC); ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. ### Remarks @@ -755,7 +754,7 @@ This method is called by the framework when a part of the toolbar must be repain Override this method to customize the appearance of an object derived from `CMFCToolBar`. -## CMFCToolBar::DrawButton +## `CMFCToolBar::DrawButton` Repaints a toolbar button. @@ -770,32 +769,32 @@ virtual BOOL DrawButton( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*pButton*
+*`pButton`*\ [in] A pointer to a button to draw. -*pImages*
+*`pImages`*\ [in] A pointer to the toolbar images. -*bHighlighted*
-[in] TRUE if the button is highlighted; otherwise FALSE. +*`bHighlighted`*\ +[in] `TRUE` if the button is highlighted; otherwise `FALSE`. -*bDrawDisabledImages*
-[in] TRUE if disabled buttons are dimmed; otherwise FALSE. +*`bDrawDisabledImages`*\ +[in] `TRUE` if disabled buttons are dimmed; otherwise `FALSE`. ### Return Value -TRUE if the button was repainted; FALSE if the button is hidden. +`TRUE` if the button was repainted; `FALSE` if the button is hidden. ### Remarks -The [CMFCToolBar::DrawButton](#drawbutton) method calls this method when a toolbar button must be repainted. +The [`CMFCToolBar::DrawButton`](#drawbutton) method calls this method when a toolbar button must be repainted. Override this method if you want to customize the appearance of buttons on your toolbar. -## CMFCToolBar::DrawSeparator +## `CMFCToolBar::DrawSeparator` Repaints a separator on a toolbar. @@ -808,22 +807,22 @@ virtual void DrawSeparator( ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. -*rect*
+*`rect`*\ [in] The bounding rectangle of the location where the separator is drawn, in pixels. -*bHorz*
-[in] TRUE if the separator is horizontal, FALSE if the separator is vertical. +*`bHorz`*\ +[in] `TRUE` if the separator is horizontal, `FALSE` if the separator is vertical. ### Remarks -[CMFCToolBar::DoPaint](#dopaint) calls this method for each [CMFCToolBar::DrawSeparator](#drawseparator) object that has the TBBS_SEPARATOR style, instead of calling [CMFCToolBar::DrawButton](#drawbutton) for those buttons. +[`CMFCToolBar::DoPaint`](#dopaint) calls this method for each [`CMFCToolBar::DrawSeparator`](#drawseparator) object that has the `TBBS_SEPARATOR` style, instead of calling [`CMFCToolBar::DrawButton`](#drawbutton) for those buttons. -Override this method in a class derived from [CMFCToolBar](../../mfc/reference/cmfctoolbar-class.md) to customize the appearance of separators on the toolbar. The default implementation calls [CMFCVisualManager::OnDrawSeparator](../../mfc/reference/cmfcvisualmanager-class.md#ondrawseparator) to draw a separator whose appearance is determined by the current visual manager. +Override this method in a class derived from [`CMFCToolBar`](../../mfc/reference/cmfctoolbar-class.md) to customize the appearance of separators on the toolbar. The default implementation calls [`CMFCVisualManager::OnDrawSeparator`](../../mfc/reference/cmfcvisualmanager-class.md#ondrawseparator) to draw a separator whose appearance is determined by the current visual manager. -## CMFCToolBar::EnableCustomizeButton +## `CMFCToolBar::EnableCustomizeButton` Enables or disables the Customize button that appears on the toolbar. @@ -843,30 +842,30 @@ void EnableCustomizeButton( ### Parameters -*bEnable*
+*`bEnable`*\ [in] Enables or disables the Customize button. -*iCustomizeCmd*
+*`iCustomizeCmd`*\ [in] The command ID of the Customize button. -*strCustomizeText*
+*`strCustomizeText`*\ [in] The text label of the Customize button. -*uiCustomizeTextResId*
+*`uiCustomizeTextResId`*\ [in] The resource string ID of the Customize button label. -*bQuickCustomize*
+*`bQuickCustomize`*\ [in] Enables or disables the **Add or Remove Buttons** option on the menu that drops down from the button. ### Remarks -If *iCustomizeCmd* is -1, the framework displays the Customize button when multiple toolbar buttons do not fit in the toolbar area. The button displays a double left-pointing arrow, or chevron, which indicates that there are more buttons. +If *`iCustomizeCmd`* is -1, the framework displays the Customize button when multiple toolbar buttons do not fit in the toolbar area. The button displays a double left-pointing arrow, or chevron, which indicates that there are more buttons. -If *iCustomizeCmd* specifies a valid command ID, and *bEnable* is TRUE, the Customize button is always displayed. The button has a small down arrow and opens a menu that contains a command. This command uses the text label specified by *strCustomizeText*. If *bQuickCustomize* is also TRUE, the menu displays the **Add or Remove Buttons** option. +If *`iCustomizeCmd`* specifies a valid command ID, and *`bEnable`* is `TRUE`, the Customize button is always displayed. The button has a small down arrow and opens a menu that contains a command. This command uses the text label specified by *`strCustomizeText`*. If *`bQuickCustomize`* is also `TRUE`, the menu displays the **Add or Remove Buttons** option. -The framework dynamically adds to the menu any buttons that do not fit in the toolbar area before the item that is specified by *iCustomizeCmd*. The chevron is displayed next to the down arrow. +The framework dynamically adds to the menu any buttons that do not fit in the toolbar area before the item that is specified by *`iCustomizeCmd`*. The chevron is displayed next to the down arrow. -## CMFCToolBar::EnableDocking +## `CMFCToolBar::EnableDocking` Enables docking of the pane to the main frame. @@ -876,14 +875,14 @@ virtual void EnableDocking(DWORD dwAlignment); ### Parameters -*dwAlignment*
+*`dwAlignment`*\ [in] Specifies the docking alignment to enable. ### Remarks -This method extends the base class implementation, [CBasePane::EnableDocking](../../mfc/reference/cbasepane-class.md#enabledocking), by setting the `CBasePane::m_dwControlBarStyle` data member to AFX_CBRS_FLOAT. This method then passes *dwAlignment* to the base class implementation. +This method extends the base class implementation, [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking), by setting the `CBasePane::m_dwControlBarStyle` data member to `AFX_CBRS_FLOAT`. This method then passes *`dwAlignment`* to the base class implementation. -## CMFCToolBar::EnableLargeIcons +## `CMFCToolBar::EnableLargeIcons` Enables or disables large icons on toolbar buttons. @@ -893,14 +892,14 @@ void EnableLargeIcons(BOOL bEnable); ### Parameters -*bEnable*
-[in] TRUE to enable large icons, FALSE to disable large icons. +*`bEnable`*\ +[in] `TRUE` to enable large icons, `FALSE` to disable large icons. ### Remarks By default, large icons are enabled. -## CMFCToolBar::EnableQuickCustomization +## `CMFCToolBar::EnableQuickCustomization` Enables or disables the quick customization of toolbars so that the user can press the **Alt** key and drag a button to a new location. @@ -910,10 +909,10 @@ static void EnableQuickCustomization(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable quick customization, FALSE to disable quick customization. +*`bEnable`*\ +[in] `TRUE` to enable quick customization, `FALSE` to disable quick customization. -## CMFCToolBar::EnableReflections +## `CMFCToolBar::EnableReflections` Enables or disables command reflection. @@ -923,8 +922,8 @@ void EnableReflections(BOOL bEnable = TRUE); ### Parameters -*bEnable*
-[in] TRUE to enable command reflection; FALSE to disable command reflection. +*`bEnable`*\ +[in] `TRUE` to enable command reflection; `FALSE` to disable command reflection. ### Remarks @@ -932,7 +931,7 @@ Call this method to enable command reflection for toolbar buttons that contain e For more information about command reflection, see [TN062: Message Reflection for Windows Controls](../../mfc/tn062-message-reflection-for-windows-controls.md). -## CMFCToolBar::EnableTextLabels +## `CMFCToolBar::EnableTextLabels` Enables or disables text labels under toolbar button images. @@ -942,14 +941,14 @@ void EnableTextLabels(BOOL bEnable=TRUE); ### Parameters -*bEnable*
-TRUE if text labels appear under toolbar button images; otherwise FALSE. +*`bEnable`*\ +`TRUE` if text labels appear under toolbar button images; otherwise `FALSE`. ### Remarks -If text labels are enabled, all buttons on the toolbar are enlarged to provide space for the labels to be displayed under the images. The customization dialog box has a **Show text label** check-box on the **Toolbars** page. When the user selects a toolbar and checks this option, the framework calls `EnableTextLabels` for the selected toolbar. You can disable the check-box for an object derived from [CMFCToolBar](../../mfc/reference/cmfctoolbar-class.md) by returning FALSE from [CMFCToolBar::AllowChangeTextLabels](#allowchangetextlabels) . +If text labels are enabled, all buttons on the toolbar are enlarged to provide space for the labels to be displayed under the images. The customization dialog box has a **Show text label** check-box on the **Toolbars** page. When the user selects a toolbar and checks this option, the framework calls `EnableTextLabels` for the selected toolbar. You can disable the check-box for an object derived from [`CMFCToolBar`](../../mfc/reference/cmfctoolbar-class.md) by returning `FALSE` from [`CMFCToolBar::AllowChangeTextLabels`](#allowchangetextlabels) . -## CMFCToolBar::FromHandlePermanent +## `CMFCToolBar::FromHandlePermanent` Retrieves a pointer to the `CMFCToolBar` object that contains the given window handle. @@ -959,18 +958,18 @@ static CMFCToolBar* __stdcall FromHandlePermanent(HWND hwnd); ### Parameters -*hwnd*
+*`hwnd`*\ [in] The window handle to look for. ### Return Value -A pointer to the `CMFCToolBar` object that contains the given window handle, or NULL if no corresponding `CMFCToolBar` object exists. +A pointer to the `CMFCToolBar` object that contains the given window handle, or `NULL` if no corresponding `CMFCToolBar` object exists. ### Remarks This shared method examines each toolbar in the application for the `CMFCToolBar` object that contains the given window handle. -## CMFCToolBar::GetAllButtons +## `CMFCToolBar::GetAllButtons` Returns a read-only list of buttons in a toolbar. @@ -980,9 +979,9 @@ const CObList& GetAllButtons() const; ### Return Value -A constant reference to a [CObList Class](../../mfc/reference/coblist-class.md) object, which contains a collection of [CMFCToolBarButton Class](../../mfc/reference/cmfctoolbarbutton-class.md) objects. +A constant reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object, which contains a collection of [`CMFCToolBarButton` Class](../../mfc/reference/cmfctoolbarbutton-class.md) objects. -## CMFCToolBar::GetAllToolbars +## `CMFCToolBar::GetAllToolbars` Returns a read-only list of all toolbars in the application. @@ -992,9 +991,9 @@ static const CObList& GetAllToolbars(); ### Return Value -A const reference to a [CObList Class](../../mfc/reference/coblist-class.md) object that contains a collection of `CMFCToolBar` objects. +A const reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object that contains a collection of `CMFCToolBar` objects. -## CMFCToolBar::GetBasicCommands +## `CMFCToolBar::GetBasicCommands` Returns a read-only list of the basic commands defined in the application. @@ -1004,15 +1003,15 @@ static const CList& GetBasicCommands(); ### Return Value -A const reference to a [CList Class](../../mfc/reference/clist-class.md) object that contains a collection of basic commands. +A const reference to a [`CList` Class](../../mfc/reference/clist-class.md) object that contains a collection of basic commands. ### Remarks -Add basic commands by calling [CMFCToolBar::AddBasicCommand](#addbasiccommand) or [CMFCToolBar::SetBasicCommands](#setbasiccommands). +Add basic commands by calling [`CMFCToolBar::AddBasicCommand`](#addbasiccommand) or [`CMFCToolBar::SetBasicCommands`](#setbasiccommands). -## CMFCToolBar::GetButton +## `CMFCToolBar::GetButton` -Returns a pointer to the [CMFCToolBarButton Class](../../mfc/reference/cmfctoolbarbutton-class.md) object at a specified index. +Returns a pointer to the [`CMFCToolBarButton` Class](../../mfc/reference/cmfctoolbarbutton-class.md) object at a specified index. ``` CMFCToolBarButton* GetButton(int iIndex) const; @@ -1020,14 +1019,14 @@ CMFCToolBarButton* GetButton(int iIndex) const; ### Parameters -*iIndex*
+*`iIndex`*\ [in] Specifies the index of the button to return. ### Return Value -A pointer to the toolbar button if it exists; or NULL if there is no such button. +A pointer to the toolbar button if it exists; or `NULL` if there is no such button. -## CMFCToolBar::GetButtonInfo +## `CMFCToolBar::GetButtonInfo` Returns the command ID, style, and image index of the button at a specified index. @@ -1041,25 +1040,25 @@ void GetButtonInfo( ### Parameters -*nIndex*
+*`nIndex`*\ [in] Specifies the index of the button in the list of buttons on the toolbar. -*nID*
+*`nID`*\ [out] The command ID of a button. -*nStyle*
+*`nStyle`*\ [out] The style of the button. -*iImage*
+*`iImage`*\ [out] The index of the image for the button. ### Remarks -The `GetButtonInfo` method finds a toolbar button at the specified index and retrieves the command ID, style and image index of the button. +The `GetButtonInfo` method finds a toolbar button at the specified index and retrieves the command ID, style, and image index of the button. -If the button at the specified index does not exist, the framework sets *nID* and *nStyle* to 0, and *iImage* to -1 when the method returns. +If the button at the specified index does not exist, the framework sets *`nID`* and *`nStyle`* to 0, and *`iImage`* to -1 when the method returns. -## CMFCToolBar::GetButtonSize +## `CMFCToolBar::GetButtonSize` Returns the dimensions of each button on the toolbar. @@ -1069,13 +1068,13 @@ CSize GetButtonSize() const; ### Return Value -A [CSize Class](../../atl-mfc-shared/reference/csize-class.md) object that specifies the dimensions of each button on the toolbar. +A [`CSize` Class](../../atl-mfc-shared/reference/csize-class.md) object that specifies the dimensions of each button on the toolbar. ### Remarks -Call [CMFCToolBar::SetSizes](#setsizes) or [CMFCToolBar::SetLockedSizes](#setlockedsizes) to set the dimensions of each button on the toolbar. +Call [`CMFCToolBar::SetSizes`](#setsizes) or [`CMFCToolBar::SetLockedSizes`](#setlockedsizes) to set the dimensions of each button on the toolbar. -## CMFCToolBar::GetButtonStyle +## `CMFCToolBar::GetButtonStyle` Returns the current style of the toolbar button that is located at the specified index. @@ -1085,7 +1084,7 @@ UINT GetButtonStyle(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ [in] Specifies the index of a toolbar button. ### Return Value @@ -1094,9 +1093,9 @@ A value that specifies the style of the toolbar button. . See [ToolBar Control S ### Remarks -Call [CMFCToolBar::SetButtonStyle](#setbuttonstyle) to set the style of a toolbar button +Call [`CMFCToolBar::SetButtonStyle`](#setbuttonstyle) to set the style of a toolbar button -## CMFCToolBar::GetButtonText +## `CMFCToolBar::GetButtonText` Returns the text label of a button that has a specified index. @@ -1110,10 +1109,10 @@ void GetButtonText( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The index of a toolbar button. -*rString*
+*`rString`*\ [out] The label text of the toolbar button. ### Return Value @@ -1122,9 +1121,9 @@ The label text of the toolbar button. ### Remarks -Call [CMFCToolBar::SetButtonText](#setbuttontext) or [CMFCToolBar::SetToolBarBtnText](#settoolbarbtntext) to set the text label. +Call [`CMFCToolBar::SetButtonText`](#setbuttontext) or [`CMFCToolBar::SetToolBarBtnText`](#settoolbarbtntext) to set the text label. -## CMFCToolBar::GetColdImages +## `CMFCToolBar::GetColdImages` Returns a pointer to the collection of cold toolbar button images in the application. @@ -1138,9 +1137,9 @@ A pointer to the collection of cold toolbar button images. ### Remarks -Cold images are the images that are used when the user is not interacting with the toolbar buttons. Call [CMFCToolBar::LoadBitmapEx](#loadbitmapex) or [CMFCToolBar::LoadBitmap](#loadbitmap) to load the cold images. +Cold images are the images that are used when the user is not interacting with the toolbar buttons. Call [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) or [`CMFCToolBar::LoadBitmap`](#loadbitmap) to load the cold images. -## CMFCToolBar::GetColumnWidth +## `CMFCToolBar::GetColumnWidth` Returns the width of the toolbar buttons. @@ -1156,7 +1155,7 @@ A value that specifies the width of toolbar buttons. The framework calls this method to calculate toolbar layout. Override this method in a derived class to specify a different column width for your toolbar. -## CMFCToolBar::GetCommandButtons +## `CMFCToolBar::GetCommandButtons` Returns a list of buttons that have a specified command ID from all toolbars in the application. @@ -1168,17 +1167,17 @@ static int GetCommandButtons( ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] The command ID of the buttons. -*listButtons*
-[out] A reference to a [CObList Class](../../mfc/reference/coblist-class.md) object that receives the list of toolbar buttons. +*`listButtons`*\ +[out] A reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object that receives the list of toolbar buttons. ### Return Value The number of buttons that have the specified command ID. -## CMFCToolBar::GetCount +## `CMFCToolBar::GetCount` Returns the number of buttons and separators on the toolbar. @@ -1190,7 +1189,7 @@ int GetCount() const; The number of buttons and separators on the toolbar. -## CMFCToolBar::GetCustomizeButton +## `CMFCToolBar::GetCustomizeButton` Retrieves a pointer to the `CMFCCustomizeButton` object that is associated with the toolbar. @@ -1204,11 +1203,11 @@ A pointer to the `CMFCCustomizeButton` object that is associated with the toolba ### Remarks -This method retrieves the **Customize** button that appears at the end of the toolbar. Use the [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton) method to add the **Customize** button to your toolbar. +This method retrieves the **Customize** button that appears at the end of the toolbar. Use the [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton) method to add the **Customize** button to your toolbar. -You can call the [CMFCToolBar::IsExistCustomizeButton](#isexistcustomizebutton) method to determine whether the toolbar contains a valid `CMFCCustomizeButton` object. +You can call the [`CMFCToolBar::IsExistCustomizeButton`](#isexistcustomizebutton) method to determine whether the toolbar contains a valid `CMFCCustomizeButton` object. -## CMFCToolBar::GetDefaultImage +## `CMFCToolBar::GetDefaultImage` Returns the index of the default image for a toolbar button with a specified command ID. @@ -1218,7 +1217,7 @@ static int GetDefaultImage(UINT uiID); ### Parameters -*uiID*
+*`uiID`*\ [in] Specifies the command ID of the button. ### Return Value @@ -1227,9 +1226,9 @@ The index of the toolbar image in the shared list of images. ### Remarks -Use this shared method to retrieve the index of the default image for a toolbar button with the specified command ID. The return value is an index into the shared collection of toolbar button images for all toolbars in the application. Call the [CMFCToolBar::GetImages](#getimages) method to obtain a pointer to this collection. +Use this shared method to retrieve the index of the default image for a toolbar button with the specified command ID. The return value is an index into the shared collection of toolbar button images for all toolbars in the application. Call the [`CMFCToolBar::GetImages`](#getimages) method to obtain a pointer to this collection. -## CMFCToolBar::GetDisabledImages +## `CMFCToolBar::GetDisabledImages` Returns a pointer to the collection of images that are used for disabled toolbar buttons in the application. @@ -1243,9 +1242,9 @@ A pointer to the collection of disabled toolbar button images. ### Remarks -Load the disabled toolbar button images by using the [CMFCToolBarEditBoxButton Class](../../mfc/reference/cmfctoolbareditboxbutton-class.md) and [CMFCToolBar::LoadBitmap](#loadbitmap) methods. +Load the disabled toolbar button images by using the [`CMFCToolBarEditBoxButton` Class](../../mfc/reference/cmfctoolbareditboxbutton-class.md) and [`CMFCToolBar::LoadBitmap`](#loadbitmap) methods. -## CMFCToolBar::GetDisabledMenuImages +## `CMFCToolBar::GetDisabledMenuImages` Returns a pointer to the collection of images that are used for disabled menu buttons in the application. @@ -1259,9 +1258,9 @@ A pointer to the collection of disabled menu images. ### Remarks -Load the disabled images by using the [CMFCToolBarEditBoxButton Class](../../mfc/reference/cmfctoolbareditboxbutton-class.md) method. +Load the disabled images by using the [`CMFCToolBarEditBoxButton` Class](../../mfc/reference/cmfctoolbareditboxbutton-class.md) method. -## CMFCToolBar::GetDroppedDownMenu +## `CMFCToolBar::GetDroppedDownMenu` Retrieves a pointer to the menu button object that is currently displaying its sub-menu. @@ -1271,18 +1270,18 @@ CMFCToolBarMenuButton* GetDroppedDownMenu(int* pIndex = NULL) const; ### Parameters -*pIndex*
+*`pIndex`*\ [out] Receives the index of the button in the collection of toolbar buttons. ### Return Value -A pointer to the menu button object that is displaying its sub-menu or NULL if no menu is displaying its sub-menu. +A pointer to the menu button object that is displaying its sub-menu or `NULL` if no menu is displaying its sub-menu. ### Remarks -If this method returns a non- NULL value and *pIndex* is not NULL, the value pointed to by *pIndex* is set to the index of the menu button in the collection of toolbar buttons. +If this method returns a non-null value and *`pIndex`* is not `NULL`, the value pointed to by *`pIndex`* is set to the index of the menu button in the collection of toolbar buttons. -## CMFCToolBar::GetGrayDisabledButtons +## `CMFCToolBar::GetGrayDisabledButtons` Specifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images. @@ -1292,13 +1291,13 @@ BOOL GetGrayDisabledButtons() const; ### Return Value -TRUE to dim the images of disabled buttons; FALSE to obtain images from the collection of disabled images. +`TRUE` to dim the images of disabled buttons; `FALSE` to obtain images from the collection of disabled images. ### Remarks -Use [CMFCToolBar::SetGrayDisabledButtons](#setgraydisabledbuttons) to switch between dimmed images and the images from the collection of disabled images. +Use [`CMFCToolBar::SetGrayDisabledButtons`](#setgraydisabledbuttons) to switch between dimmed images and the images from the collection of disabled images. -## CMFCToolBar::GetHighlightedButton +## `CMFCToolBar::GetHighlightedButton` Returns a pointer to the toolbar button that is currently highlighted. @@ -1308,13 +1307,13 @@ CMFCToolBarButton* GetHighlightedButton() const; ### Return Value -A pointer to a toolbar button object; or NULL if no button is highlighted. +A pointer to a toolbar button object; or `NULL` if no button is highlighted. ### Remarks -A toolbar button is highlighted if it has keyboard focus. A toolbar button is also highlighted if the toolbar buttons are hot-tracked in this application (for more information, see [CMFCToolBar::GetHotBorder](#gethotborder) and [CMFCToolBar::SetHotBorder](#sethotborder)) and the mouse is pointing at it when no toolbar button or menu item has keyboard focus. +A toolbar button is highlighted if it has keyboard focus. A toolbar button is also highlighted if the toolbar buttons are hot-tracked in this application (for more information, see [`CMFCToolBar::GetHotBorder`](#gethotborder) and [`CMFCToolBar::SetHotBorder`](#sethotborder)) and the mouse is pointing at it when no toolbar button or menu item has keyboard focus. -## CMFCToolBar::GetHotBorder +## `CMFCToolBar::GetHotBorder` Determines whether the toolbar buttons are *hot-tracked*. If a button is hot-tracked, it is highlighted when the mouse moves across it. @@ -1324,13 +1323,13 @@ BOOL GetHotBorder() const; ### Return Value -TRUE if the toolbar buttons are hot-tracked; otherwise, FALSE. +`TRUE` if the toolbar buttons are hot-tracked; otherwise, `FALSE`. ### Remarks By default, toolbar buttons are hot-tracked. -## CMFCToolBar::GetHotTextColor +## `CMFCToolBar::GetHotTextColor` Returns the text color of the highlighted toolbar buttons. @@ -1340,13 +1339,13 @@ static COLORREF GetHotTextColor(); ### Return Value -A [COLORREF](/windows/win32/gdi/colorref) value that represent the current highlighted text color. +A [`COLORREF`](/windows/win32/gdi/colorref) value that represents the current highlighted text color. ### Remarks -Call [CMFCToolBar::SetHotTextColor](#sethottextcolor) to set a new text color for highlighted toolbar buttons. +Call [`CMFCToolBar::SetHotTextColor`](#sethottextcolor) to set a new text color for highlighted toolbar buttons. -## CMFCToolBar::GetHwndLastFocus +## `CMFCToolBar::GetHwndLastFocus` Returns a handle to the window that had the input focus just before the toolbar did. @@ -1356,13 +1355,13 @@ HWND GetHwndLastFocus() const; ### Return Value -A handle to window that is not derived from [CMFCBaseToolBar Class](../../mfc/reference/cmfcbasetoolbar-class.md), which previously had the input focus; or NULL if there is no such window. +A handle to window that is not derived from [`CMFCBaseToolBar` Class](../../mfc/reference/cmfcbasetoolbar-class.md), which previously had the input focus; or `NULL` if there is no such window. ### Remarks When a `CMFCToolBar` control receives the input focus, it stores a handle to the window that lost the focus so that it can restore it later. -## CMFCToolBar::GetIgnoreSetText +## `CMFCToolBar::GetIgnoreSetText` Specifies whether calls to set button labels are ignored. @@ -1372,11 +1371,11 @@ BOOL GetIgnoreSetText() const; ### Return Value -TRUE if calls to set button labels are ignored; otherwise, FALSE. +`TRUE` if calls to set button labels are ignored; otherwise, `FALSE`. ### Remarks -## CMFCToolBar::GetImages +## `CMFCToolBar::GetImages` Returns a pointer to the collection of default button images in the application. @@ -1386,13 +1385,13 @@ static CMFCToolBarImages* GetImages(); ### Return Value -A pointer to the [CMFCToolBarImages Class](../../mfc/reference/cmfctoolbarimages-class.md) object that contains the collection of default images for all toolbars in the application. +A pointer to the [`CMFCToolBarImages` Class](../../mfc/reference/cmfctoolbarimages-class.md) object that contains the collection of default images for all toolbars in the application. ### Remarks -This shared method provides access to the collection of all default toolbar images for the application. Call the [CMFCToolBar::LoadBitmap](#loadbitmap) method to add images to the collection. +This shared method provides access to the collection of all default toolbar images for the application. Call the [`CMFCToolBar::LoadBitmap`](#loadbitmap) method to add images to the collection. -## CMFCToolBar::GetImageSize +## `CMFCToolBar::GetImageSize` Returns the current size of toolbar button images. @@ -1402,9 +1401,9 @@ CSize GetImageSize() const; ### Return Value -A [CSize Class](../../atl-mfc-shared/reference/csize-class.md) object that represents the current size of toolbar button images. +A [`CSize` Class](../../atl-mfc-shared/reference/csize-class.md) object that represents the current size of toolbar button images. -## CMFCToolBar::GetImagesOffset +## `CMFCToolBar::GetImagesOffset` Returns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images. @@ -1418,13 +1417,13 @@ The index offset of the toolbar images. ### Remarks -All toolbar default images are stored in the global [CMFCToolBarImages Class](../../mfc/reference/cmfctoolbarimages-class.md) list. The images for each button in the toolbar are stored consecutively in that list. To compute the index of the image, add the index of the button in the toolbar to the offset of the beginning of the list of images for that toolbar button. +All toolbar default images are stored in the global [`CMFCToolBarImages` Class](../../mfc/reference/cmfctoolbarimages-class.md) list. The images for each button in the toolbar are stored consecutively in that list. To compute the index of the image, add the index of the button in the toolbar to the offset of the beginning of the list of images for that toolbar button. -Call [CMFCToolBar::ButtonToIndex](#buttontoindex) to obtain the index of a toolbar button given a pointer to the button. +Call [`CMFCToolBar::ButtonToIndex`](#buttontoindex) to obtain the index of a toolbar button given a pointer to the button. -Call [CMFCToolBar::GetImages](#getimages) to obtain a pointer to the collection of toolbar images. +Call [`CMFCToolBar::GetImages`](#getimages) to obtain a pointer to the collection of toolbar images. -## CMFCToolBar::GetInvalidateItemRect +## `CMFCToolBar::GetInvalidateItemRect` Retrieves the region of the client area that must be redrawn for the button at the given index. @@ -1436,17 +1435,17 @@ virtual void GetInvalidateItemRect( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The index of the button for which to retrieve the client area. -*lpRect*
-[out] A pointer to a RECT object that receives the region of the client area. +*`lpRect`*\ +[out] A pointer to a `RECT` object that receives the region of the client area. ### Remarks -The *lpRect* parameter must not be NULL. If no button exists at the provided index, *lpRect* receives a RECT object that is initialized to zero. +The *`lpRect`* parameter must not be `NULL`. If no button exists at the provided index, *`lpRect`* receives a `RECT` object that is initialized to zero. -## CMFCToolBar::GetItemID +## `CMFCToolBar::GetItemID` Returns the command ID of the toolbar button at a specified index. @@ -1456,14 +1455,14 @@ UINT GetItemID(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ [in] Specifies the index of the toolbar button. ### Return Value The command ID of the toolbar button; or zero if the button with the specified index does not exist. -## CMFCToolBar::GetItemRect +## `CMFCToolBar::GetItemRect` Returns the bounding rectangle of the button at a specified index. @@ -1475,15 +1474,15 @@ virtual void GetItemRect( ### Parameters -*nIndex*
+*`nIndex`*\ [in] Specifies the index of a toolbar button. -*lpRect*
+*`lpRect`*\ [out] A pointer to `CRect` object that receives the coordinates of the image bounding rectangle. ### Remarks -The `CRect` object to which *lpRect* points is set to 0 if a button at the specified index does not exist. +The `CRect` object to which *`lpRect`* points is set to 0 if a button at the specified index does not exist. ### Example @@ -1492,7 +1491,7 @@ The following example demonstrates how to use the `GetItemRect` method of the `C [!code-cpp[NVC_MFC_IEDemo#6](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_1.h)] [!code-cpp[NVC_MFC_IEDemo#9](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_4.cpp)] -## CMFCToolBar::GetLargeColdImages +## `CMFCToolBar::GetLargeColdImages` Returns a pointer to the collection of large cold toolbar button images in the application. @@ -1506,9 +1505,9 @@ A pointer to the collection of large cold images. ### Remarks -Cold images are the images that are used when the user is not interacting with the toolbar buttons. Call [CMFCToolBar::LoadBitmapEx](#loadbitmapex) to load the large cold images. +Cold images are the images that are used when the user is not interacting with the toolbar buttons. Call [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) to load the large cold images. -## CMFCToolBar::GetLargeDisabledImages +## `CMFCToolBar::GetLargeDisabledImages` Returns a pointer to the collection of large disabled toolbar button images in the application. @@ -1522,9 +1521,9 @@ A pointer to the collection of large disabled toolbar button images. ### Remarks -Large images are large versions of the regular toolbar button images. Call [CMFCToolBar::LoadBitmapEx](#loadbitmapex) or [CMFCToolBar::LoadBitmap](#loadbitmap) to load the large images. +Large images are large versions of the regular toolbar button images. Call [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) or [`CMFCToolBar::LoadBitmap`](#loadbitmap) to load the large images. -## CMFCToolBar::GetLargeImages +## `CMFCToolBar::GetLargeImages` Returns a pointer to the collection of large toolbar button images in the application. @@ -1538,9 +1537,9 @@ A pointer to the collection of large toolbar button images. ### Remarks -Large images are large versions of the regular toolbar button images. Call [CMFCToolBar::LoadBitmapEx](#loadbitmapex) to load the large images. +Large images are large versions of the regular toolbar button images. Call [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) to load the large images. -## CMFCToolBar::GetLockedColdImages +## `CMFCToolBar::GetLockedColdImages` Returns a pointer to the collection of locked cold images in the toolbar. @@ -1550,17 +1549,17 @@ CMFCToolBarImages* GetLockedColdImages(); ### Return Value -A pointer to the collection of locked cold images, or NULL if the toolbar is not locked. +A pointer to the collection of locked cold images, or `NULL` if the toolbar is not locked. ### Remarks Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. Cold images are the images that are used when the user is not interacting with the toolbar buttons. -This method returns NULL if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [CMFCToolBar::IsLocked](#islocked). +This method returns `NULL` if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [`CMFCToolBar::IsLocked`](#islocked). -Call the [CMFCToolBar::LoadBitmapEx](#loadbitmapex) method to load the locked cold images. +Call the [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) method to load the locked cold images. -## CMFCToolBar::GetLockedDisabledImages +## `CMFCToolBar::GetLockedDisabledImages` Returns a pointer to the collection of locked disabled images in the toolbar. @@ -1570,17 +1569,17 @@ CMFCToolBarImages* GetLockedDisabledImages(); ### Return Value -A pointer to the collection of locked disabled images, or NULL if the toolbar is not locked. +A pointer to the collection of locked disabled images, or `NULL` if the toolbar is not locked. ### Remarks -Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. Disabled images are the images that the framework uses when a button has the TBBS_DISABLED style. +Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. Disabled images are the images that the framework uses when a button has the `TBBS_DISABLED` style. -This method returns NULL if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [CMFCToolBar::IsLocked](#islocked). +This method returns `NULL` if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [`CMFCToolBar::IsLocked`](#islocked). -Call the [CMFCToolBar::LoadBitmapEx](#loadbitmapex) method to load the locked disabled images. +Call the [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) method to load the locked disabled images. -## CMFCToolBar::GetLockedImages +## `CMFCToolBar::GetLockedImages` Returns a pointer to the collection of locked button images in the toolbar. @@ -1590,15 +1589,15 @@ CMFCToolBarImages* GetLockedImages(); ### Return Value -A pointer to the collection of locked toolbar button images, or NULL if the toolbar is not locked. +A pointer to the collection of locked toolbar button images, or `NULL` if the toolbar is not locked. ### Remarks Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. -This method returns NULL if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [CMFCToolBar::IsLocked](#islocked). +This method returns `NULL` if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [`CMFCToolBar::IsLocked`](#islocked). -## CMFCToolBar::GetLockedImageSize +## `CMFCToolBar::GetLockedImageSize` Returns the default size of locked toolbar images. @@ -1614,11 +1613,11 @@ A `CSize` structure that specifies the size of locked toolbar images or an empty Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. -This method returns a `CSize` structure with zero width and zero height if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [CMFCToolBar::IsLocked](#islocked). +This method returns a `CSize` structure with zero width and zero height if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [`CMFCToolBar::IsLocked`](#islocked). -Call the [CMFCToolBar::SetLockedSizes](#setlockedsizes) method to specify the locked image size. +Call the [`CMFCToolBar::SetLockedSizes`](#setlockedsizes) method to specify the locked image size. -## CMFCToolBar::GetLockedMenuImages +## `CMFCToolBar::GetLockedMenuImages` Returns a pointer to the collection of locked toolbar menu images in the toolbar. @@ -1628,17 +1627,17 @@ CMFCToolBarImages* GetLockedMenuImages(); ### Return Value -A pointer to the collection of locked toolbar menu images, or NULL if the toolbar is not locked. +A pointer to the collection of locked toolbar menu images, or `NULL` if the toolbar is not locked. ### Remarks Locked images are versions of the regular toolbar menu images that the framework uses when the user cannot customize the toolbar. -This method returns NULL if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [CMFCToolBar::IsLocked](#islocked). +This method returns `NULL` if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see [`CMFCToolBar::IsLocked`](#islocked). -Call the [CMFCToolBar::LoadBitmapEx](#loadbitmapex) method to load the locked menu images. +Call the [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) method to load the locked menu images. -## CMFCToolBar::GetMenuButtonSize +## `CMFCToolBar::GetMenuButtonSize` Returns the size of menu buttons in the application. @@ -1654,9 +1653,9 @@ A `CSize` object that represents the size of menu buttons, in pixels. The size of menu buttons on toolbars is maintained as a global variable and can be retrieved by this static method. -Call [CMFCToolBar::SetMenuSizes](#setmenusizes) to set this global variable. +Call [`CMFCToolBar::SetMenuSizes`](#setmenusizes) to set this global variable. -## CMFCToolBar::GetMenuImages +## `CMFCToolBar::GetMenuImages` Returns a pointer to the collection of menu button images in the application. @@ -1670,11 +1669,11 @@ A pointer to the collection of menu images. ### Remarks -Call the [CMFCToolBar::LoadBitmapEx](#loadbitmapex) method to load the menu images. +Call the [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex) method to load the menu images. -Call the [CMFCToolBar::SetMenuSizes](#setmenusizes) method to set the size of buttons and their images. +Call the [`CMFCToolBar::SetMenuSizes`](#setmenusizes) method to set the size of buttons and their images. -## CMFCToolBar::GetMenuImageSize +## `CMFCToolBar::GetMenuImageSize` Returns the size of menu button images in the application. @@ -1688,9 +1687,9 @@ A `CSize` object that represents the size of menu images. ### Remarks -This method returns the size of images on toolbar menu buttons that is maintained as a global variable. Call [CMFCToolBar::SetMenuSizes](#setmenusizes) to set this global variable. +This method returns the size of images on toolbar menu buttons that is maintained as a global variable. Call [`CMFCToolBar::SetMenuSizes`](#setmenusizes) to set this global variable. -## CMFCToolBar::GetOrigButtons +## `CMFCToolBar::GetOrigButtons` Retrieves the collection of non-customized buttons of the toolbar. @@ -1704,11 +1703,11 @@ A reference to the list of non-customized buttons of the toolbar. ### Remarks -The framework creates a copy of toolbar buttons before they are customized by the user. The [CMFCToolBar::SetButtons](#setbuttons) method adds a copy of each button in the provided array to the list of original buttons. The [CMFCToolBar::RestoreOriginalState](#restoreoriginalstate) method restores the original state of the toolbar by loading it from the resource file. +The framework creates a copy of toolbar buttons before they are customized by the user. The [`CMFCToolBar::SetButtons`](#setbuttons) method adds a copy of each button in the provided array to the list of original buttons. The [`CMFCToolBar::RestoreOriginalState`](#restoreoriginalstate) method restores the original state of the toolbar by loading it from the resource file. -To set the list of original buttons for your toolbar, call the [CMFCToolBar::SetOrigButtons](#setorigbuttons) method. +To set the list of original buttons for your toolbar, call the [`CMFCToolBar::SetOrigButtons`](#setorigbuttons) method. -## CMFCToolBar::GetOrigResetButtons +## `CMFCToolBar::GetOrigResetButtons` Retrieves the collection of non-customized reset buttons of the toolbar. @@ -1722,11 +1721,11 @@ A reference to the list of non-customized reset buttons of the toolbar. ### Remarks -When the user clicks the **Reset** button during customization mode, the framework uses this method to restore buttons that were removed from the toolbar. +When the user selects the **Reset** button during customization mode, the framework uses this method to restore buttons that were removed from the toolbar. -The [CMFCToolBar::SetButtons](#setbuttons) method adds a copy of each toolbar button to the list of original reset buttons after it calls the [CMFCToolBar::OnReset](#onreset) method. You can override the [CMFCToolBar::OnReset](#onreset) method to customize the appearance of buttons after the user presses the **Reset** button. +The [`CMFCToolBar::SetButtons`](#setbuttons) method adds a copy of each toolbar button to the list of original reset buttons after it calls the [`CMFCToolBar::OnReset`](#onreset) method. You can override the [`CMFCToolBar::OnReset`](#onreset) method to customize the appearance of buttons after the user presses the **Reset** button. -## CMFCToolBar::GetResourceID +## `CMFCToolBar::GetResourceID` Retrieves the resource ID of the toolbar. @@ -1740,9 +1739,9 @@ The resource ID of the toolbar. ### Remarks -Call the [CMFCToolBar::LoadToolBarEx](#loadtoolbarex) method to set the resource ID of the toolbar. +Call the [`CMFCToolBar::LoadToolBarEx`](#loadtoolbarex) method to set the resource ID of the toolbar. -## CMFCToolBar::GetRouteCommandsViaFrame +## `CMFCToolBar::GetRouteCommandsViaFrame` Determines which object, the parent frame or the owner, sends commands to the toolbar. @@ -1756,11 +1755,11 @@ Nonzero if the parent frame sends commands to the toolbar; 0 if the owner sends ### Remarks -By default, the parent frame sends commands to the toolbar. Call [CMFCToolBar::SetRouteCommandsViaFrame](#setroutecommandsviaframe) to change this behavior. +By default, the parent frame sends commands to the toolbar. Call [`CMFCToolBar::SetRouteCommandsViaFrame`](#setroutecommandsviaframe) to change this behavior. If this method returns a nonzero value, you can retrieve a pointer to the parent frame object by using the `CMFCToolBar::GetCommandTarget` method. See the VisualStudioDemo sample for an example that uses this method. -## CMFCToolBar::GetRowHeight +## `CMFCToolBar::GetRowHeight` Returns the height of toolbar buttons. @@ -1776,7 +1775,7 @@ The height of toolbar buttons, in pixels. The framework calls this method to calculate toolbar layout. Override this method in a derived class to specify a different height for your toolbar. -## CMFCToolBar::GetShowTooltips +## `CMFCToolBar::GetShowTooltips` Specifies whether tool tips are displayed for toolbar buttons. @@ -1786,13 +1785,13 @@ static BOOL GetShowTooltips(); ### Return Value -TRUE if tool tips are shown for toolbar buttons; otherwise FALSE. +`TRUE` if tool tips are shown for toolbar buttons; otherwise `FALSE`. ### Remarks -By default tool tips are shown. You can change this static flag by calling [CMFCToolBar::SetShowTooltips](#setshowtooltips). +By default tool tips are shown. You can change this static flag by calling [`CMFCToolBar::SetShowTooltips`](#setshowtooltips). -## CMFCToolBar::GetSiblingToolBar +## `CMFCToolBar::GetSiblingToolBar` Retrieves the sibling of the toolbar. @@ -1806,9 +1805,9 @@ A pointer to the sibling toolbar. ### Remarks -For more information about how to enable the **Show Buttons on One Row** and **Show Buttons on Two Rows** buttons, see [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar). +For more information about how to enable the **Show Buttons on One Row** and **Show Buttons on Two Rows** buttons, see [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar). -## CMFCToolBar::GetUserImages +## `CMFCToolBar::GetUserImages` Returns a pointer to the collection of user-defined toolbar button images in the application. @@ -1822,9 +1821,9 @@ A pointer to the collection of user-defined toolbar button images for all toolba ### Remarks -Call the [CMFCToolBar::SetUserImages](#setuserimages) method to set the collection of user-defined images in the application. +Call the [`CMFCToolBar::SetUserImages`](#setuserimages) method to set the collection of user-defined images in the application. -## CMFCToolBar::HitTest +## `CMFCToolBar::HitTest` Returns the index of the toolbar button that is located at the specified position. @@ -1834,14 +1833,14 @@ virtual int HitTest(CPoint point); ### Parameters -*point*
+*`point`*\ [in] The point to be tested, in client coordinates. ### Return Value The index of the button that is located at the specified position, or -1 if there is no such button or the button is a separator. -## CMFCToolBar::InsertButton +## `CMFCToolBar::InsertButton` Inserts a button into the toolbar. @@ -1857,10 +1856,10 @@ virtual int InsertButton( ### Parameters -*button*
+*`button`*\ [in] Specifies the button to insert. -*iInsertAt*
+*`iInsertAt`*\ [in] Specifies the zero-based position to insert the button at. ### Return Value @@ -1869,11 +1868,11 @@ The position at which the button was inserted or -1 if an error occurs. ### Remarks -If *iInsertAt* is -1, this method adds the button to the end of the list of toolbar buttons. +If *`iInsertAt`* is -1, this method adds the button to the end of the list of toolbar buttons. -Call the [CMFCToolBar::InsertSeparator](#insertseparator) method to insert a separator into the toolbar. +Call the [`CMFCToolBar::InsertSeparator`](#insertseparator) method to insert a separator into the toolbar. -## CMFCToolBar::InsertSeparator +## `CMFCToolBar::InsertSeparator` Inserts a separator into the toolbar. @@ -1883,7 +1882,7 @@ virtual int InsertSeparator(INT_PTR iInsertAt=-1); ### Parameters -*iInsertAt*
+*`iInsertAt`*\ [in] Specifies the zero-based position to insert the separator at. This parameter must be larger than 0. ### Return Value @@ -1892,13 +1891,13 @@ The position at which the separator was inserted or -1 if an error occurs. ### Remarks -Call this method to insert a separator between two existing buttons. If *iInsertAt* is -1, this method adds the separator to the end of the list of toolbar buttons. +Call this method to insert a separator between two existing buttons. If *`iInsertAt`* is -1, this method adds the separator to the end of the list of toolbar buttons. You cannot use this method to add a separator to an empty toolbar. -Call the [CMFCToolBar::InsertButton](#insertbutton) method to insert a button into the toolbar. +Call the [`CMFCToolBar::InsertButton`](#insertbutton) method to insert a button into the toolbar. -## CMFCToolBar::InvalidateButton +## `CMFCToolBar::InvalidateButton` Invalidates the client area of the toolbar button that exists at the provided index. @@ -1908,18 +1907,18 @@ CMFCToolBarButton* InvalidateButton(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of the button in the toolbar. ### Return Value -A pointer to the `CMFCToolBarButton` object that exists at the provided index or NULL if no such object exists. +A pointer to the `CMFCToolBarButton` object that exists at the provided index or `NULL` if no such object exists. ### Remarks -The framework calls this method when it updates the client area that is associated with a toolbar button. It calls the [CWnd::InvalidateRect](../../mfc/reference/cwnd-class.md#invalidaterect) method with the client rectangle of the `CMFCToolBarButton` object that exists at the provided index. +The framework calls this method when it updates the client area that is associated with a toolbar button. It calls the [`CWnd::InvalidateRect`](../../mfc/reference/cwnd-class.md#invalidaterect) method with the client rectangle of the `CMFCToolBarButton` object that exists at the provided index. -## CMFCToolBar::IsAddRemoveQuickCustomize +## `CMFCToolBar::IsAddRemoveQuickCustomize` Determines whether a user can add or remove toolbar buttons by using the **Customize** menu option. @@ -1929,13 +1928,13 @@ BOOL IsAddRemoveQuickCustomize(); ### Return Value -TRUE if a user can use the **Customize** menu option to modify the toolbar; otherwise, FALSE. +`TRUE` if a user can use the **Customize** menu option to modify the toolbar; otherwise, `FALSE`. ### Remarks -## CMFCToolBar::IsAltCustomizeMode +## `CMFCToolBar::IsAltCustomizeMode` -Specifies whether *quick customization* is being used to drag a button. When quick customization is enabled, a user can press and hold the Alt key and drag a button to a new location. +Specifies whether *quick customization* is being used to drag a button. When quick customization is enabled, a user can press and hold the **Alt** key and drag a button to a new location. ``` static BOOL __stdcall IsAltCustomizeMode(); @@ -1943,11 +1942,11 @@ static BOOL __stdcall IsAltCustomizeMode(); ### Return Value -TRUE if quick customization is being used to drag a button; otherwise, FALSE. +`TRUE` if quick customization is being used to drag a button; otherwise, `FALSE`. ### Remarks -## CMFCToolBar::IsAutoGrayInactiveImages +## `CMFCToolBar::IsAutoGrayInactiveImages` Specifies whether the automatic generation of inactive (non-highlighted) button images is enabled. @@ -1957,13 +1956,13 @@ static BOOL IsAutoGrayInactiveImages(); ### Return Value -TRUE if the option to automatically dim inactive images is enabled; otherwise FALSE. +`TRUE` if the option to automatically dim inactive images is enabled; otherwise `FALSE`. ### Remarks -You can enable or disable automatic dimming of inactive images by calling [CMFCToolBar::AutoGrayInactiveImages](#autograyinactiveimages). +You can enable or disable automatic dimming of inactive images by calling [`CMFCToolBar::AutoGrayInactiveImages`](#autograyinactiveimages). -## CMFCToolBar::IsBasicCommand +## `CMFCToolBar::IsBasicCommand` Determines whether a command is on the list of basic commands. @@ -1973,18 +1972,18 @@ static BOOL IsBasicCommand(UINT uiCmd); ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] Specifies the command to check. ### Return Value -TRUE if the specified command belongs to the list of basic commands; otherwise FALSE. +`TRUE` if the specified command belongs to the list of basic commands; otherwise `FALSE`. ### Remarks -This static method determines whether the command specified by *uiCmd* belongs to the global list of basic commands. You can change the list of basic commands by calling [CMFCToolBar::AddBasicCommand](#addbasiccommand) or [CMFCToolBar::SetBasicCommands](#setbasiccommands). +This static method determines whether the command specified by *`uiCmd`* belongs to the global list of basic commands. You can change the list of basic commands by calling [`CMFCToolBar::AddBasicCommand`](#addbasiccommand) or [`CMFCToolBar::SetBasicCommands`](#setbasiccommands). -## CMFCToolBar::IsButtonExtraSizeAvailable +## `CMFCToolBar::IsButtonExtraSizeAvailable` Determines whether the toolbar can display buttons that have extended borders. @@ -1994,15 +1993,15 @@ virtual BOOL IsButtonExtraSizeAvailable() const; ### Return Value -TRUE if the bar can display buttons with the extra border size; otherwise FALSE. +`TRUE` if the bar can display buttons with the extra border size; otherwise `FALSE`. ### Remarks -The toolbar object returns TRUE if it can display buttons that have extended borders. A toolbar button calls this method when it handles the [CMFCToolBarButton::OnChangeParentWnd](../../mfc/reference/cmfctoolbarbutton-class.md#onchangeparentwnd) notification and will set its internal extra border size flag accordingly. This internal flag may be retrieved later by calling [CMFCToolBarButton::IsExtraSize](../../mfc/reference/cmfctoolbarbutton-class.md#isextrasize). +The toolbar object returns `TRUE` if it can display buttons that have extended borders. A toolbar button calls this method when it handles the [`CMFCToolBarButton::OnChangeParentWnd`](../../mfc/reference/cmfctoolbarbutton-class.md#onchangeparentwnd) notification and will set its internal extra border size flag accordingly. This internal flag may be retrieved later by calling [`CMFCToolBarButton::IsExtraSize`](../../mfc/reference/cmfctoolbarbutton-class.md#isextrasize). -Override this method in a class derived from `CMFCToolBar` and return TRUE if your bar can display the toolbar buttons with the extra border size and return FALSE otherwise. The default implementation returns TRUE. +Override this method in a class derived from `CMFCToolBar` and return `TRUE` if your bar can display the toolbar buttons with the extra border size and return `FALSE` otherwise. The default implementation returns `TRUE`. -## CMFCToolBar::IsButtonHighlighted +## `CMFCToolBar::IsButtonHighlighted` Determines whether the specified button is highlighted. @@ -2012,16 +2011,16 @@ BOOL IsButtonHighlighted(int iButton) const; ### Parameters -*iButton*
+*`iButton`*\ [in] Specifies the index of a toolbar button. ### Return Value -TRUE if the specified button is highlighted; otherwise, FALSE. +`TRUE` if the specified button is highlighted; otherwise, `FALSE`. ### Remarks -## CMFCToolBar::IsCommandPermitted +## `CMFCToolBar::IsCommandPermitted` Determines whether a command is permitted. @@ -2031,20 +2030,20 @@ static BOOL IsCommandPermitted(UINT uiCmd); ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] Specifies the command to check. ### Return Value -TRUE if the specified command is permitted; otherwise FALSE. +`TRUE` if the specified command is permitted; otherwise `FALSE`. ### Remarks -This static method determines whether the command specified by *uiCmd* belongs to the global list of non-permitted commands. +This static method determines whether the command specified by *`uiCmd`* belongs to the global list of non-permitted commands. -You can change the list of non-permitted commands by calling [CMFCToolBar::SetNonPermittedCommands](#setnonpermittedcommands). +You can change the list of non-permitted commands by calling [`CMFCToolBar::SetNonPermittedCommands`](#setnonpermittedcommands). -## CMFCToolBar::IsCommandRarelyUsed +## `CMFCToolBar::IsCommandRarelyUsed` Determines whether a command is rarely used. @@ -2054,16 +2053,16 @@ static BOOL IsCommandRarelyUsed(UINT uiCmd); ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] Specifies the command to check. ### Return Value -TRUE if the specified command is rarely used; otherwise FALSE. +`TRUE` if the specified command is rarely used; otherwise `FALSE`. ### Remarks -The `IsCommandRarelyUsed` method returns FALSE when one or more of the following conditions occur: +The `IsCommandRarelyUsed` method returns `FALSE` when one or more of the following conditions occur: - The specified command belongs to the list of basic commands @@ -2075,7 +2074,7 @@ The `IsCommandRarelyUsed` method returns FALSE when one or more of the following - More than 20% of command calls are calls to the specified command. -## CMFCToolBar::IsCustomizeMode +## `CMFCToolBar::IsCustomizeMode` Specifies whether the toolbar framework is in customization mode. @@ -2085,15 +2084,15 @@ static BOOL IsCustomizeMode(); ### Return Value -TRUE if the framework is in customization mode; otherwise FALSE. +`TRUE` if the framework is in customization mode; otherwise `FALSE`. ### Remarks -You can toggle customization mode by calling [CMFCToolBar::SetCustomizeMode](#setcustomizemode). +You can toggle customization mode by calling [`CMFCToolBar::SetCustomizeMode`](#setcustomizemode). -The framework changes the mode when the user invokes the customization dialog box ( [CMFCToolBarsCustomizeDialog Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)). +The framework changes the mode when the user invokes the customization dialog box ( [`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)). -## CMFCToolBar::IsDragButton +## `CMFCToolBar::IsDragButton` Determines whether a toolbar button is being dragged. @@ -2103,16 +2102,16 @@ BOOL IsDragButton(const CMFCToolBarButton* pButton) const; ### Parameters -*pButton*
+*`pButton`*\ [in] Pointer to a toolbar button. ### Return Value -TRUE if the specified button is being dragged; otherwise, FALSE. +`TRUE` if the specified button is being dragged; otherwise, `FALSE`. ### Remarks -## CMFCToolBar::IsExistCustomizeButton +## `CMFCToolBar::IsExistCustomizeButton` Determines whether the toolbar contains the **Customize** button. @@ -2122,15 +2121,15 @@ BOOL IsExistCustomizeButton(); ### Return Value -TRUE if the toolbar contains the **Customize** button; otherwise FALSE. +`TRUE` if the toolbar contains the **Customize** button; otherwise `FALSE`. ### Remarks -If this method returns TRUE, the [CMFCToolBar::GetCustomizeButton](#getcustomizebutton) method returns a pointer to the **Customize** button that appears at the end of the toolbar. +If this method returns `TRUE`, the [`CMFCToolBar::GetCustomizeButton`](#getcustomizebutton) method returns a pointer to the **Customize** button that appears at the end of the toolbar. -Use the [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton) method to add the **Customize** button to your toolbar. +Use the [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton) method to add the **Customize** button to your toolbar. -## CMFCToolBar::IsFloating +## `CMFCToolBar::IsFloating` Determines whether the toolbar is floating. @@ -2140,9 +2139,9 @@ virtual BOOL IsFloating() const; ### Return Value -TRUE if the toolbar is floating; otherwise, FALSE. +`TRUE` if the toolbar is floating; otherwise, `FALSE`. -## CMFCToolBar::IsLargeIcons +## `CMFCToolBar::IsLargeIcons` Specifies whether toolbars in the application currently display large icons. @@ -2152,15 +2151,15 @@ static BOOL IsLargeIcons(); ### Return Value -TRUE if the application is using large icons; otherwise FALSE. +`TRUE` if the application is using large icons; otherwise `FALSE`. ### Remarks -Call [CMFCToolBar::SetLargeIcons](#setlargeicons) to toggle between large icons and regular icons. +Call [`CMFCToolBar::SetLargeIcons`](#setlargeicons) to toggle between large icons and regular icons. The framework automatically changes the mode when the user toggles the **Large icons** check-box on the **Options** page of the **Customization** dialog box. -## CMFCToolBar::IsLastCommandFromButton +## `CMFCToolBar::IsLastCommandFromButton` Determines whether the most recently executed command was sent from the specified toolbar button. @@ -2170,18 +2169,18 @@ static BOOL IsLastCommandFromButton(CMFCToolBarButton* pButton); ### Parameters -*pButton*
+*`pButton`*\ [in] Pointer to button. ### Return Value -TRUE if the last command was sent from the button that *pButton* specifies; otherwise FALSE. +`TRUE` if the last command was sent from the button that *`pButton`* specifies; otherwise `FALSE`. ### Remarks -This method obtains a pointer to a [MSG Structure](/windows/win32/api/winuser/ns-winuser-msg) by calling `CWnd::GetCurrentMessage`. It then compares the HWND of the button with the `MSG::lParam` and `MSG::hwnd` members to determine whether the button was the source of the command. +This method obtains a pointer to a [`MSG` Structure](/windows/win32/api/winuser/ns-winuser-msg) by calling `CWnd::GetCurrentMessage`. It then compares the `HWND` of the button with the `MSG::lParam` and `MSG::hwnd` members to determine whether the button was the source of the command. -## CMFCToolBar::IsLocked +## `CMFCToolBar::IsLocked` Determines whether the toolbar is locked. @@ -2191,15 +2190,15 @@ BOOL IsLocked() const; ### Return Value -TRUE if the toolbar is locked; otherwise, FALSE. +`TRUE` if the toolbar is locked; otherwise, `FALSE`. ### Remarks -This method returns TRUE when the user cannot perform customization tasks such as repositioning toolbar buttons. +This method returns `TRUE` when the user cannot perform customization tasks such as repositioning toolbar buttons. -Locked toolbars use separate image lists. For more information about these image lists, see [CMFCToolBar::LoadBitmapEx](#loadbitmapex). +Locked toolbars use separate image lists. For more information about these image lists, see [`CMFCToolBar::LoadBitmapEx`](#loadbitmapex). -## CMFCToolBar::IsOneRowWithSibling +## `CMFCToolBar::IsOneRowWithSibling` Determines whether the toolbar and its sibling toolbar are positioned on the same row. @@ -2209,15 +2208,15 @@ BOOL IsOneRowWithSibling(); ### Return Value -TRUE if the toolbar and its sibling are positioned on the same row; otherwise FALSE. +`TRUE` if the toolbar and its sibling are positioned on the same row; otherwise `FALSE`. ### Remarks -The [CMFCCustomizeButton::CreatePopupMenu](internal-classes.md) method calls this method to determine how to show the **Customize** pop-up menu. If this method returns TRUE, the framework displays the **Show Buttons on One Row** button. Otherwise, the framework displays the **Show Buttons on Two Rows** button. +The [`CMFCCustomizeButton::CreatePopupMenu`](internal-classes.md) method calls this method to determine how to show the **Customize** pop-up menu. If this method returns `TRUE`, the framework displays the **Show Buttons on One Row** button. Otherwise, the framework displays the **Show Buttons on Two Rows** button. -You typically do not have to use this method. To enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons, call [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar). +You typically do not have to use this method. To enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons, call [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar). -## CMFCToolBar::IsResourceChanged +## `CMFCToolBar::IsResourceChanged` ``` virtual BOOL IsResourceChanged() const; @@ -2227,7 +2226,7 @@ virtual BOOL IsResourceChanged() const; ### Remarks -## CMFCToolBar::IsSibling +## `CMFCToolBar::IsSibling` ``` BOOL IsSibling(); @@ -2237,7 +2236,7 @@ BOOL IsSibling(); ### Remarks -## CMFCToolBar::IsUserDefined +## `CMFCToolBar::IsUserDefined` Specifies whether the toolbar is user-defined. @@ -2247,9 +2246,9 @@ BOOL IsUserDefined() const; ### Return Value -TRUE if the toolbar was created by the user; otherwise FALSE. +`TRUE` if the toolbar was created by the user; otherwise `FALSE`. -## CMFCToolBar::LoadBitmap +## `CMFCToolBar::LoadBitmap` Loads toolbar images from application resources. @@ -2265,22 +2264,22 @@ virtual BOOL LoadBitmap( ### Parameters -*uiResID*
+*`uiResID`*\ [in] The resource ID of the bitmap that refers to the hot toolbar images. -*uiColdResID*
+*`uiColdResID`*\ [in] The resource ID of the bitmap that refers to the cold toolbar images. -*uiMenuResID*
+*`uiMenuResID`*\ [in] The resource ID of the bitmap that refers to the regular menu images. -*bLocked*
-[in] TRUE to lock the toolbar; otherwise FALSE. +*`bLocked`*\ +[in] `TRUE` to lock the toolbar; otherwise `FALSE`. -*uiDisabledResID*
+*`uiDisabledResID`*\ [in] The resource ID of the bitmap that refers to the disabled toolbar images. -*uiMenuDisabledResID*
+*`uiMenuDisabledResID`*\ [in] The resource ID of the bitmap that refers to the disabled menu images. ### Return Value @@ -2289,11 +2288,11 @@ Nonzero if the method succeeds; otherwise 0. ### Remarks -The [CMFCToolBar::LoadToolBarEx](#loadtoolbarex) method calls this method to load the images that are associated with the toolbar. Override this method to perform custom loading of image resources. +The [`CMFCToolBar::LoadToolBarEx`](#loadtoolbarex) method calls this method to load the images that are associated with the toolbar. Override this method to perform custom loading of image resources. Call the `LoadBitmapEx` method to load additional images after you create the toolbar. -## CMFCToolBar::LoadBitmapEx +## `CMFCToolBar::LoadBitmapEx` ``` virtual BOOL LoadBitmapEx( @@ -2303,14 +2302,14 @@ virtual BOOL LoadBitmapEx( ### Parameters -[in] *params*
-[in] *bLocked*
+[in] *`params`*\ +[in] *`bLocked`* ### Return Value ### Remarks -## CMFCToolBar::LoadLargeIconsState +## `CMFCToolBar::LoadLargeIconsState` ``` static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL); @@ -2318,13 +2317,13 @@ static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *lpszProfileName*
+[in] *`lpszProfileName`* ### Return Value ### Remarks -## CMFCToolBar::LoadParameters +## `CMFCToolBar::LoadParameters` Loads global toolbar options from the Windows registry. @@ -2334,7 +2333,7 @@ static BOOL LoadParameters(LPCTSTR lpszProfileName=NULL); ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the relative path of the Windows registry key. ### Return Value @@ -2345,9 +2344,9 @@ Nonzero if the method succeeds; otherwise 0. This method loads global parameters such as the menu animation type, the menu shadow style, and whether to display large icons from the Windows registry. -The [CWinAppEx::LoadState](../../mfc/reference/cwinappex-class.md#loadstate) method calls this method as a part of the initialization process of the application. +The [`CWinAppEx::LoadState`](../../mfc/reference/cwinappex-class.md#loadstate) method calls this method as a part of the initialization process of the application. -## CMFCToolBar::LoadState +## `CMFCToolBar::LoadState` Loads the toolbar state information from the Windows registry. @@ -2360,13 +2359,13 @@ virtual BOOL LoadState( ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the relative path of the Windows registry key. -*nIndex*
+*`nIndex`*\ [in] Specifies the control ID of the toolbar. -*uiID*
+*`uiID`*\ [in] Specifies the resource ID of the toolbar. ### Return Value @@ -2375,9 +2374,9 @@ Nonzero if the method succeeds; otherwise 0. ### Remarks -The framework calls this method as a part of the initialization process of the application. For more information, see [CWinAppEx::LoadState](../../mfc/reference/cwinappex-class.md#loadstate). +The framework calls this method as a part of the initialization process of the application. For more information, see [`CWinAppEx::LoadState`](../../mfc/reference/cwinappex-class.md#loadstate). -## CMFCToolBar::LoadToolBar +## `CMFCToolBar::LoadToolBar` Loads the toolbar from application resources. @@ -2394,25 +2393,25 @@ virtual BOOL LoadToolBar( ### Parameters -*uiResID*
+*`uiResID`*\ [in] The resource ID of the toolbar. -*uiColdResID*
+*`uiColdResID`*\ [in] The resource ID of the bitmap that refers to the cold toolbar images. -*uiMenuResID*
+*`uiMenuResID`*\ [in] The resource ID of the bitmap that refers to the regular menu images. -*bLocked*
-[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is *TRUE*, the toolbar is locked. Otherwise, the toolbar is not locked. +*`bLocked`*\ +[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is *`TRUE`*, the toolbar is locked. Otherwise, the toolbar is not locked. -*uiDisabledResID*
+*`uiDisabledResID`*\ [in] The resource ID of the bitmap that refers to the disabled toolbar images. -*uiMenuDisabledResID*
+*`uiMenuDisabledResID`*\ [in] The resource ID of the bitmap that refers to the disabled menu images. -*uiHotResID*
+*`uiHotResID`*\ [in] The resource ID of the bitmap that refers to the hot toolbar images. ### Return Value @@ -2430,7 +2429,7 @@ The following example demonstrates how to use the `LoadToolBar` method in the `C [!code-cpp[NVC_MFC_IEDemo#6](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_1.h)] [!code-cpp[NVC_MFC_IEDemo#7](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_3.cpp)] -## CMFCToolBar::LoadToolBarEx +## `CMFCToolBar::LoadToolBarEx` Loads the toolbar from application resources by using the `CMFCToolBarInfo` helper class to enable the application to use large images. @@ -2443,14 +2442,14 @@ virtual BOOL LoadToolBarEx( ### Parameters -*uiToolbarResID*
+*`uiToolbarResID`*\ [in] The resource ID of the toolbar. -*params*
+*`params`*\ [in] A reference to a `CMFCToolBarInfo` object that contains the resource IDs for the toolbar images. -*bLocked*
-[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is TRUE, the toolbar is locked. Otherwise, the toolbar is not locked. +*`bLocked`*\ +[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is `TRUE`, the toolbar is locked. Otherwise, the toolbar is not locked. ### Return Value @@ -2460,7 +2459,7 @@ Nonzero if the method succeeds; otherwise 0. Call this method to load toolbar images from the application resources. -## CMFCToolBar::m_dblLargeImageRatio +## `CMFCToolBar::m_dblLargeImageRatio` Specifies the ratio between the dimension (height or width) of large images and the dimension of regular images. @@ -2474,7 +2473,7 @@ The default ratio is 2. You can change this value to make large toolbar images l The framework uses this data member when you do not specify a set of large images. For example, if you provide only the set of small images with size 16x16 and want the large images to have the size 24x24, set this data member to 1.5. -## CMFCToolBar::NextMenu +## `CMFCToolBar::NextMenu` ``` virtual BOOL NextMenu(); @@ -2484,7 +2483,7 @@ virtual BOOL NextMenu(); ### Remarks -## CMFCToolBar::OnBeforeRemoveButton +## `CMFCToolBar::OnBeforeRemoveButton` ``` virtual BOOL OnBeforeRemoveButton( @@ -2494,17 +2493,17 @@ virtual BOOL OnBeforeRemoveButton( ### Parameters -*pButton*
+*`pButton`*\ [in] Unused. -*dropEffect*
+*`dropEffect`*\ [in] Unused. ### Return Value ### Remarks -## CMFCToolBar::OnChangeHot +## `CMFCToolBar::OnChangeHot` Called by the framework when a user selects a button on the toolbar. @@ -2514,14 +2513,14 @@ virtual void OnChangeHot(int iHot); ### Parameters -*iHot*
+*`iHot`*\ [in] Specifies the index of the toolbar button that is selected; or -1 if no toolbar button is selected. ### Remarks Override this method to process notifications that the user selected a button on a toolbar. -## CMFCToolBar::OnChangeVisualManager +## `CMFCToolBar::OnChangeVisualManager` ``` virtual void OnChangeVisualManager(); @@ -2529,9 +2528,9 @@ virtual void OnChangeVisualManager(); ### Remarks -## CMFCToolBar::OnFillBackground +## `CMFCToolBar::OnFillBackground` -Called by the framework from [CBasePane::DoPaint](../../mfc/reference/cbasepane-class.md#dopaint) to fill the toolbar background. +Called by the framework from [`CBasePane::DoPaint`](../../mfc/reference/cbasepane-class.md#dopaint) to fill the toolbar background. ``` virtual void OnFillBackground(CDC* pDC); @@ -2539,16 +2538,16 @@ virtual void OnFillBackground(CDC* pDC); ### Parameters -*pDC*
+*`pDC`*\ [in] A pointer to a device context. ### Remarks -[CMFCToolBar::DoPaint](#dopaint) calls this method when the background of a toolbar has been filled. The default implementation does nothing. +[`CMFCToolBar::DoPaint`](#dopaint) calls this method when the background of a toolbar has been filled. The default implementation does nothing. Override this method to draw custom background in derived classes. -## CMFCToolBar::OnGlobalFontsChanged +## `CMFCToolBar::OnGlobalFontsChanged` ``` virtual void OnGlobalFontsChanged(); @@ -2556,7 +2555,7 @@ virtual void OnGlobalFontsChanged(); ### Remarks -## CMFCToolBar::OnReset +## `CMFCToolBar::OnReset` Restores the toolbar to its original state. @@ -2570,7 +2569,7 @@ Override this method to handle notification about a toolbar reset. The default implementation does nothing. Override `OnReset` in a class derived from `CMFCToolBar` when the toolbar has dummy buttons that must be replaced when the toolbar returns to its original state. -## CMFCToolBar::OnSetAccData +## `CMFCToolBar::OnSetAccData` ``` virtual BOOL OnSetAccData(long lVal); @@ -2578,13 +2577,13 @@ virtual BOOL OnSetAccData(long lVal); ### Parameters -[in] *lVal*
+[in] *`lVal`* ### Return Value ### Remarks -## CMFCToolBar::OnSetDefaultButtonText +## `CMFCToolBar::OnSetDefaultButtonText` Restores the text of a toolbar button to its default state. @@ -2594,12 +2593,12 @@ virtual BOOL OnSetDefaultButtonText(CMFCToolBarButton* pButton); ### Parameters -*pButton*
+*`pButton`*\ [in] Points to a button, whose text is being set. ### Return Value -TRUE ifthe text was successfully restored; otherwise FALSE. +`TRUE` ifthe text was successfully restored; otherwise `FALSE`. ### Remarks @@ -2607,7 +2606,7 @@ Override this method to process notifications that the text of a toolbar button The default implementation loads the text of a button from the application resources. -## CMFCToolBar::OnUserToolTip +## `CMFCToolBar::OnUserToolTip` Called by the framework when the tooltip for a button is about to be displayed. @@ -2619,23 +2618,23 @@ virtual BOOL OnUserToolTip( ### Parameters -*pButton*
+*`pButton`*\ [in] Points to a toolbar button for which a tooltip is to be displayed. -*strTTText*
+*`strTTText`*\ [out] A reference to `CString` object that receives the text of the tooltip. ### Return Value -TRUE if *strTTText* was populated with tooltip text; otherwise FALSE. +`TRUE` if *`strTTText`* was populated with tooltip text; otherwise `FALSE`. ### Remarks -The framework calls this method when the tooltip for a toolbar button is about to be displayed. If `OnUserToolTip` returns TRUE, the framework displays a tooltip which contains the text returned by `OnUserToolTip` in *strTTText*. Otherwise, the tooltip contains the button text. +The framework calls this method when the tooltip for a toolbar button is about to be displayed. If `OnUserToolTip` returns `TRUE`, the framework displays a tooltip that contains the text returned by `OnUserToolTip` in *`strTTText`*. Otherwise, the tooltip contains the button text. -Override `OnUserToolTip` to customize tool tips of toolbar buttons. The default implementation calls [CMFCToolBar::OnUserToolTip](#onusertooltip) to obtain the tooltip text. +Override `OnUserToolTip` to customize tool tips of toolbar buttons. The default implementation calls [`CMFCToolBar::OnUserToolTip`](#onusertooltip) to obtain the tooltip text. -## CMFCToolBar::PrevMenu +## `CMFCToolBar::PrevMenu` ``` virtual BOOL PrevMenu(); @@ -2645,9 +2644,9 @@ virtual BOOL PrevMenu(); ### Remarks -## CMFCToolBar::ProcessCommand +## `CMFCToolBar::ProcessCommand` -Posts a WM_COMMAND message to the window that owns the toolbar. +Posts a `WM_COMMAND` message to the window that owns the toolbar. ``` BOOL ProcessCommand(CMFCToolBarButton* pButton); @@ -2655,20 +2654,20 @@ BOOL ProcessCommand(CMFCToolBarButton* pButton); ### Parameters -*pButton*
+*`pButton`*\ [in] Pointer to a button on the toolbar. ### Return Value -This method should always return TRUE. MFC uses FALSE values internally. +This method should always return `TRUE`. MFC uses `FALSE` values internally. ### Remarks -This method posts a WM_COMMAND message to the window that owns the toolbar by calling [CWnd::PostMessage](../../mfc/reference/cwnd-class.md#postmessage) and passing the command ID of the specified button as the *wParam* parameter. +This method posts a `WM_COMMAND` message to the window that owns the toolbar by calling [`CWnd::PostMessage`](../../mfc/reference/cwnd-class.md#postmessage) and passing the command ID of the specified button as the *`wParam`* parameter. -Use the [ON_COMMAND](message-map-macros-mfc.md#on_command) macro to map the WM_COMMAND message to a member function. +Use the [`ON_COMMAND`](message-map-macros-mfc.md#on_command) macro to map the `WM_COMMAND` message to a member function. -## CMFCToolBar::RemoveAllButtons +## `CMFCToolBar::RemoveAllButtons` Removes all buttons and separators from the toolbar. @@ -2680,7 +2679,7 @@ virtual void RemoveAllButtons(); The framework calls this method when it recreates or destroys a toolbar. -## CMFCToolBar::RemoveButton +## `CMFCToolBar::RemoveButton` Removes from the toolbar the button that has the specified index. @@ -2690,20 +2689,20 @@ virtual BOOL RemoveButton(int iIndex); ### Parameters -*iIndex*
+*`iIndex`*\ [in] Specifies the zero-based index of the button to remove. ### Return Value -TRUE if the method succeeds, or FALSE if the specified index is invalid or the index refers to the **Customize** button. +`TRUE` if the method succeeds, or `FALSE` if the specified index is invalid or the index refers to the **Customize** button. ### Remarks This method updates additional toolbar attributes that are affected by the removal of the button. For example, this method removes nonessential separators from the toolbar and rebuilds the table of shortcut keys. -For more information about the **Customize** button, see [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton). +For more information about the **Customize** button, see [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton). -## CMFCToolBar::RemoveStateFromRegistry +## `CMFCToolBar::RemoveStateFromRegistry` Deletes the state information for the toolbar from the Windows registry. @@ -2716,14 +2715,14 @@ virtual BOOL RemoveStateFromRegistry( ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the registry key where the state information is located. -*nIndex*
+*`nIndex`*\ [in] The control ID of the toolbar. -*uiID*
-[in] The resource ID of the toolbar. If this parameter is -1, this method uses the [CWnd::GetDlgCtrlID](../../mfc/reference/cwnd-class.md#getdlgctrlid) method to retrieve the resource ID. +*`uiID`*\ +[in] The resource ID of the toolbar. If this parameter is -1, this method uses the [`CWnd::GetDlgCtrlID`](../../mfc/reference/cwnd-class.md#getdlgctrlid) method to retrieve the resource ID. ### Return Value @@ -2735,7 +2734,7 @@ The framework calls this method when it deletes a user-defined toolbar. Override this method if you store additional state information in the Windows registry. -## CMFCToolBar::ReplaceButton +## `CMFCToolBar::ReplaceButton` Replaces a toolbar button with another toolbar button. @@ -2748,14 +2747,14 @@ int ReplaceButton( ### Parameters -*uiCmd*
+*`uiCmd`*\ [in] The command ID of the button to replace. -*button*
+*`button`*\ [in] A reference to the `CMFCToolBarButton` to insert. -*bAll*
-[in] A Boolean value that specifies whether to replace all buttons that have the command ID specified by *uiCmd*. If this parameter is TRUE, all buttons that have the specified command ID are replaced. Otherwise, the first button is replaced. +*`bAll`*\ +[in] A Boolean value that specifies whether to replace all buttons that have the command ID specified by *`uiCmd`*. If this parameter is `TRUE`, all buttons that have the specified command ID are replaced. Otherwise, the first button is replaced. ### Return Value @@ -2772,7 +2771,7 @@ The following example demonstrates how to use the `ReplaceButton` method in the [!code-cpp[NVC_MFC_IEDemo#6](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_1.h)] [!code-cpp[NVC_MFC_IEDemo#10](../../mfc/reference/codesnippet/cpp/cmfctoolbar-class_5.cpp)] -## CMFCToolBar::ResetAll +## `CMFCToolBar::ResetAll` Restores all toolbars to their original states. @@ -2782,9 +2781,9 @@ static void __stdcall ResetAll(); ### Remarks -This method calls the [CMFCToolBar::RestoreOriginalState](#restoreoriginalstate) method on each toolbar in the application that can be restored. It uses the [CMFCToolBar::CanBeRestored](#canberestored) method to determine whether a toolbar can be restored. +This method calls the [`CMFCToolBar::RestoreOriginalState`](#restoreoriginalstate) method on each toolbar in the application that can be restored. It uses the [`CMFCToolBar::CanBeRestored`](#canberestored) method to determine whether a toolbar can be restored. -## CMFCToolBar::ResetAllImages +## `CMFCToolBar::ResetAllImages` Clears all toolbar image collections in the application. @@ -2794,9 +2793,9 @@ static void __stdcall ResetAllImages(); ### Remarks -This method clears the image collections that are initialized by the [CMFCToolBar::LoadToolBar](#loadtoolbar) and [CMFCToolBar::LoadBitmap](#loadbitmap) methods. +This method clears the image collections that are initialized by the [`CMFCToolBar::LoadToolBar`](#loadtoolbar) and [`CMFCToolBar::LoadBitmap`](#loadbitmap) methods. -## CMFCToolBar::ResetImages +## `CMFCToolBar::ResetImages` ``` virtual void ResetImages(); @@ -2804,7 +2803,7 @@ virtual void ResetImages(); ### Remarks -## CMFCToolBar::RestoreFocus +## `CMFCToolBar::RestoreFocus` ``` virtual void RestoreFocus(); @@ -2812,7 +2811,7 @@ virtual void RestoreFocus(); ### Remarks -## CMFCToolBar::RestoreOriginalState +## `CMFCToolBar::RestoreOriginalState` Restores the original state of a toolbar. @@ -2822,15 +2821,15 @@ virtual BOOL RestoreOriginalState(); ### Return Value -TRUE if the method succeeds, or FALSE if the method fails or the toolbar is user-defined. +`TRUE` if the method succeeds, or `FALSE` if the method fails or the toolbar is user-defined. ### Remarks -This method loads the toolbar from the resource file by using the [CMFCToolBar::LoadToolBar](#loadtoolbar) method. +This method loads the toolbar from the resource file by using the [`CMFCToolBar::LoadToolBar`](#loadtoolbar) method. The framework calls this method when the user chooses the **Reset All** button on the **Toolbars** page of a customization dialog box. -## CMFCToolBar::SaveParameters +## `CMFCToolBar::SaveParameters` ``` static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL); @@ -2838,13 +2837,13 @@ static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *lpszProfileName*
+[in] *`lpszProfileName`* ### Return Value ### Remarks -## CMFCToolBar::SaveState +## `CMFCToolBar::SaveState` Saves the state information for the toolbar in the Windows registry. @@ -2857,13 +2856,13 @@ virtual BOOL SaveState( ### Parameters -*lpszProfileName*
+*`lpszProfileName`*\ [in] Specifies the relative path of the Windows registry key. -*nIndex*
+*`nIndex`*\ [in] The control ID of the toolbar. -*uiID*
+*`uiID`*\ [in] The resource ID of the toolbar. ### Return Value @@ -2872,9 +2871,9 @@ Nonzero if the method succeeds; otherwise 0. ### Remarks -The framework calls this method when it saves the application state to the registry. For more information, see [CWinAppEx::SaveState](../../mfc/reference/cwinappex-class.md#savestate). +The framework calls this method when it saves the application state to the registry. For more information, see [`CWinAppEx::SaveState`](../../mfc/reference/cwinappex-class.md#savestate). -## CMFCToolBar::SetBasicCommands +## `CMFCToolBar::SetBasicCommands` Sets the list of commands that are always displayed when a user opens a menu. @@ -2884,18 +2883,18 @@ static void __stdcall SetBasicCommands(CList& lstCommands); ### Parameters -*lstCommands*
+*`lstCommands`*\ [in] A reference to a `CList` object that contains a collection of commands. ### Remarks A basic command is always displayed when the menu is opened. This method is meaningful when the user chooses to view recently used commands. -Use the [CMFCToolBar::AddBasicCommand](#addbasiccommand) method to add a command to the list of basic commands. Use the [CMFCToolBar::GetBasicCommands](#getbasiccommands) method to retrieve the list of basic commands that is used by your application. +Use the [`CMFCToolBar::AddBasicCommand`](#addbasiccommand) method to add a command to the list of basic commands. Use the [`CMFCToolBar::GetBasicCommands`](#getbasiccommands) method to retrieve the list of basic commands that is used by your application. See the Explorer sample for an example that uses this method. -## CMFCToolBar::SetButtonInfo +## `CMFCToolBar::SetButtonInfo` Sets the command ID, style, and image ID of a toolbar button. @@ -2909,27 +2908,27 @@ void SetButtonInfo( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of the button whose properties are set. -*nID*
+*`nID`*\ [in] The command ID of the button. -*nStyle*
+*`nStyle`*\ [in] The style of the button. See [ToolBar Control Styles](../../mfc/reference/toolbar-control-styles.md) for the list of available toolbar button styles. -*iImage*
+*`iImage`*\ [in] The zero-based image index of the button (that is, the index in the collection of toolbar images). ### Remarks Call this method to set the properties of a toolbar button. -In Debug builds, this method generates an assertion failure if the index that is specified by *nIndex* is invalid. +In Debug builds, this method generates an assertion failure if the index that is specified by *`nIndex`* is invalid. -Call the [CMFCToolBar::SetButtonStyle](#setbuttonstyle) method to set only the style of the button. +Call the [`CMFCToolBar::SetButtonStyle`](#setbuttonstyle) method to set only the style of the button. -## CMFCToolBar::SetButtons +## `CMFCToolBar::SetButtons` Sets the buttons for the toolbar. @@ -2942,14 +2941,14 @@ virtual BOOL SetButtons( ### Parameters -*lpIDArray*
+*`lpIDArray`*\ [in] A pointer to the array of command IDs of the buttons to insert. -*nIDCount*
-[in] The number of items in *lpIDArray*. +*`nIDCount`*\ +[in] The number of items in *`lpIDArray`*. -*bRemapImages*
-[in] A Boolean value that specifies whether to associate the existing button images with the inserted buttons. If this parameter is TRUE, the images are remapped. +*`bRemapImages`*\ +[in] A Boolean value that specifies whether to associate the existing button images with the inserted buttons. If this parameter is `TRUE`, the images are remapped. ### Return Value @@ -2959,9 +2958,9 @@ Nonzero if the method succeeds; otherwise 0. Call this method to remove existing buttons from a toolbar and insert a collection of new buttons. -This method adds the **Customize** button to the toolbar and sends the AFX_WM_RESETTOOLBAR message to the parent window of the toolbar. For more information about the **Customize** button, see [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton). +This method adds the **Customize** button to the toolbar and sends the `AFX_WM_RESETTOOLBAR` message to the parent window of the toolbar. For more information about the **Customize** button, see [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton). -## CMFCToolBar::SetButtonStyle +## `CMFCToolBar::SetButtonStyle` Sets the style of the toolbar button at the given index. @@ -2973,17 +2972,17 @@ virtual void SetButtonStyle( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The zero-based index of the toolbar button whose style is to be set. -*nStyle*
+*`nStyle`*\ [in] The style of the button. See [ToolBar Control Styles](../../mfc/reference/toolbar-control-styles.md) for the list of available toolbar button styles. ### Remarks -This method removes the TBBS_PRESSED style if *nStyle* is TBBS_DISABLED because the user cannot click a disabled button. +This method removes the `TBBS_PRESSED` style if *`nStyle`* is `TBBS_DISABLED` because the user cannot select a disabled button. -## CMFCToolBar::SetButtonText +## `CMFCToolBar::SetButtonText` Sets the text label of a toolbar button. @@ -2995,21 +2994,21 @@ BOOL SetButtonText( ### Parameters -*nIndex*
+*`nIndex`*\ [in] The index of the toolbar button. -*lpszText*
-[in] The text label of the toolbar button. Must be non- NULL. +*`lpszText`*\ +[in] The text label of the toolbar button. Must be non-null. ### Return Value -TRUE if the method succeeds; otherwise FALSE. +`TRUE` if the method succeeds; otherwise `FALSE`. ### Remarks -This method returns FALSE if the provided index does not refer to a valid toolbar button. +This method returns `FALSE` if the provided index does not refer to a valid toolbar button. -## CMFCToolBar::SetCommandUsageOptions +## `CMFCToolBar::SetCommandUsageOptions` Specifies when rarely used commands do not appear in the menu of the application. @@ -3021,23 +3020,23 @@ static BOOL SetCommandUsageOptions( ### Parameters -*nStartCount*
+*`nStartCount`*\ [in] Specifies the number of times that commands must be executed before the framework shows only the basic and recently-used commands. -*nMinUsagePercentage*
+*`nMinUsagePercentage`*\ [in] The percentage of times that a command must be executed to be considered a recently-used command. ### Return Value -FALSE if *nMinUsagePercentage* is equal to or larger than 100; otherwise TRUE. +`FALSE` if *`nMinUsagePercentage`* is equal to or larger than 100; otherwise `TRUE`. ### Remarks -Call this method to customize the algorithm that the framework uses to determine how basic and recently used menu items appear. For more information about basic commands, see [CMFCToolBar::AddBasicCommand](#addbasiccommand). +Call this method to customize the algorithm that the framework uses to determine how basic and recently used menu items appear. For more information about basic commands, see [`CMFCToolBar::AddBasicCommand`](#addbasiccommand). -This class uses the `CMFCCmdUsageCount` class to track the usage count of commands. For more information about this class, see [CMFCCmdUsageCount Class](../../mfc/reference/cmfccmdusagecount-class.md). +This class uses the `CMFCCmdUsageCount` class to track the usage count of commands. For more information about this class, see [`CMFCCmdUsageCount` Class](../../mfc/reference/cmfccmdusagecount-class.md). -## CMFCToolBar::SetCustomizeMode +## `CMFCToolBar::SetCustomizeMode` Enables or disables customization mode for all toolbars in the application. @@ -3047,18 +3046,18 @@ static BOOL __stdcall SetCustomizeMode(BOOL bSet=TRUE); ### Parameters -*bSet*
-[in] A Boolean value that specifies whether to enable or disable customization mode. Set this parameter to TRUE to enable customization mode or FALSE to disable it. +*`bSet`*\ +[in] A Boolean value that specifies whether to enable or disable customization mode. Set this parameter to `TRUE` to enable customization mode or `FALSE` to disable it. ### Return Value -TRUE if calling this method changes the customization mode; otherwise FALSE. +`TRUE` if calling this method changes the customization mode; otherwise `FALSE`. ### Remarks -This method adjusts the layout of and redraws each toolbar in the application. Call the [CMFCToolBar::IsCustomizeMode](#iscustomizemode) method to determine whether the application is in customization mode, +This method adjusts the layout of and redraws each toolbar in the application. Call the [`CMFCToolBar::IsCustomizeMode`](#iscustomizemode) method to determine whether the application is in customization mode, -## CMFCToolBar::SetGrayDisabledButtons +## `CMFCToolBar::SetGrayDisabledButtons` Specifies whether unavailable buttons on the toolbar are dimmed, or whether button-unavailable images are used. @@ -3068,14 +3067,14 @@ void SetGrayDisabledButtons(BOOL bGrayDisabledButtons); ### Parameters -*bGrayDisabledButtons*
-[in] A Boolean value that specifies how to display unavailable buttons. If this parameter is TRUE, the framework dims the buttons. Otherwise, the framework uses the collection of button-unavailable images. +*`bGrayDisabledButtons`*\ +[in] A Boolean value that specifies how to display unavailable buttons. If this parameter is `TRUE`, the framework dims the buttons. Otherwise, the framework uses the collection of button-unavailable images. ### Remarks By default, unavailable buttons are dimmed. -## CMFCToolBar::SetHeight +## `CMFCToolBar::SetHeight` Sets the height of the toolbar. @@ -3085,14 +3084,14 @@ void SetHeight(int cyHeight); ### Parameters -*cyHeight*
+*`cyHeight`*\ [in] The height of the toolbar, in pixels. ### Remarks This method redraws the toolbar after it sets the height. -## CMFCToolBar::SetHelpMode +## `CMFCToolBar::SetHelpMode` ``` static void __stdcall SetHelpMode(BOOL bOn = TRUE); @@ -3100,11 +3099,11 @@ static void __stdcall SetHelpMode(BOOL bOn = TRUE); ### Parameters -[in] *bOn*
+[in] *`bOn`* ### Remarks -## CMFCToolBar::SetHot +## `CMFCToolBar::SetHot` ``` BOOL SetHot(CMFCToolBarButton* pMenuButton); @@ -3112,13 +3111,13 @@ BOOL SetHot(CMFCToolBarButton* pMenuButton); ### Parameters -[in] *pMenuButton*
+[in] *`pMenuButton`* ### Return Value ### Remarks -## CMFCToolBar::SetHotBorder +## `CMFCToolBar::SetHotBorder` Specifies whether toolbar buttons are hot-tracked. @@ -3128,16 +3127,16 @@ void SetHotBorder(BOOL bShowHotBorder); ### Parameters -*bShowHotBorder*
-[in] A Boolean value that specifies whether to hot-track toolbar buttons. If this parameter is TRUE, the toolbar hot-tracks its buttons. Otherwise, the toolbar does not hot-track its buttons. +*`bShowHotBorder`*\ +[in] A Boolean value that specifies whether to hot-track toolbar buttons. If this parameter is `TRUE`, the toolbar hot-tracks its buttons. Otherwise, the toolbar does not hot-track its buttons. ### Remarks If a button is hot-tracked, the framework highlights the button when the mouse moves across it. By default, each toolbar hot-tracks its buttons. -Call the [CMFCToolBar::GetHotBorder](#gethotborder) method to determine whether the toolbar hot-tracks its buttons. +Call the [`CMFCToolBar::GetHotBorder`](#gethotborder) method to determine whether the toolbar hot-tracks its buttons. -## CMFCToolBar::SetHotTextColor +## `CMFCToolBar::SetHotTextColor` Sets the text color for hot toolbar buttons. @@ -3147,14 +3146,14 @@ static void SetHotTextColor(COLORREF clrText); ### Parameters -*clrText*
+*`clrText`*\ [in] Specifies the text color for toolbar buttons that are hot-tracked. ### Remarks -For more information about hot-tracked toolbar buttons, see [CMFCToolBar::GetHotBorder](#gethotborder) and [CMFCToolBar::SetHotBorder](#sethotborder). +For more information about hot-tracked toolbar buttons, see [`CMFCToolBar::GetHotBorder`](#gethotborder) and [`CMFCToolBar::SetHotBorder`](#sethotborder). -## CMFCToolBar::SetIgnoreSetText +## `CMFCToolBar::SetIgnoreSetText` ```cpp void SetIgnoreSetText(BOOL bValue); @@ -3162,11 +3161,11 @@ void SetIgnoreSetText(BOOL bValue); ### Parameters -[in] *bValue*
+[in] *`bValue`* ### Remarks -## CMFCToolBar::SetLargeIcons +## `CMFCToolBar::SetLargeIcons` Specifies whether toolbar buttons display large icons. @@ -3176,8 +3175,8 @@ static void SetLargeIcons(BOOL bLargeIcons=TRUE); ### Parameters -*bLargeIcons*
-[in] A Boolean value that specifies which icons to use. If this parameter is TRUE, the framework displays large icons. Otherwise, the framework displays regular icons. +*`bLargeIcons`*\ +[in] A Boolean value that specifies which icons to use. If this parameter is `TRUE`, the framework displays large icons. Otherwise, the framework displays regular icons. ### Remarks @@ -3185,9 +3184,9 @@ The framework calls this method when the user changes the state of the **Large I By default, the framework displays regular icons. -For more information about the **Customize** dialog box, see [CMFCToolBarsCustomizeDialog Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md). +For more information about the **Customize** dialog box, see [`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md). -## CMFCToolBar::SetLockedSizes +## `CMFCToolBar::SetLockedSizes` Sets the sizes of locked buttons and locked images on the toolbar. @@ -3200,22 +3199,22 @@ void SetLockedSizes( ### Parameters -*sizeButton*
+*`sizeButton`*\ [in] Specifies the size of locked toolbar buttons. -*sizeImage*
+*`sizeImage`*\ [in] Specifies the size of locked toolbar images. -*bDontScale*
+*`bDontScale`*\ Specifies whether to scale or not locked toolbar images in high DPI mode. ### Remarks The default size of locked buttons is 23x22 pixels. The default size of locked images is 16x15 pixels. -Call the [CMFCToolBar::GetLockedImageSize](#getlockedimagesize) method to retrieve the size of locked images. Call the [CMFCToolBar::GetButtonSize](#getbuttonsize) method to retrieve the size of locked toolbar buttons. +Call the [`CMFCToolBar::GetLockedImageSize`](#getlockedimagesize) method to retrieve the size of locked images. Call the [`CMFCToolBar::GetButtonSize`](#getbuttonsize) method to retrieve the size of locked toolbar buttons. -## CMFCToolBar::SetMaskMode +## `CMFCToolBar::SetMaskMode` ```cpp void SetMaskMode(BOOL bMasked); @@ -3223,11 +3222,11 @@ void SetMaskMode(BOOL bMasked); ### Parameters -[in] *bMasked*
+[in] *`bMasked`* ### Remarks -## CMFCToolBar::SetMenuSizes +## `CMFCToolBar::SetMenuSizes` Sets the size of toolbar menu buttons and their images. @@ -3239,21 +3238,21 @@ static void __stdcall SetMenuSizes( ### Parameters -*sizeButton*
+*`sizeButton`*\ [in] Specifies the size of toolbar buttons, in pixels. -*sizeImage*
+*`sizeImage`*\ [in] Specifies the size of toolbar images, in pixels. ### Remarks By default, menu buttons and their images have an undefined size. -Call the [CMFCToolBar::GetMenuButtonSize](#getmenubuttonsize) method to determine the size of menu buttons and the [CMFCToolBar::GetMenuImageSize](#getmenuimagesize) method to determine the size of menu button images. +Call the [`CMFCToolBar::GetMenuButtonSize`](#getmenubuttonsize) method to determine the size of menu buttons and the [`CMFCToolBar::GetMenuImageSize`](#getmenuimagesize) method to determine the size of menu button images. See the IEDemo and MSMoneyDemo samples for examples that use this method. -## CMFCToolBar::SetNonPermittedCommands +## `CMFCToolBar::SetNonPermittedCommands` Sets the list of commands that cannot be executed by the user. @@ -3263,7 +3262,7 @@ static void SetNonPermittedCommands(CList& lstCommands); ### Parameters -*lstCommands*
+*`lstCommands`*\ [in] A reference to a `CList` object that contains the commands that cannot be executed by the user. ### Remarks @@ -3272,7 +3271,7 @@ Call this method to prevent the user from selecting certain commands. For exampl This method clears the previous list of non-permitted commands. By default, the list of non-permitted commands is empty. -## CMFCToolBar::SetOneRowWithSibling +## `CMFCToolBar::SetOneRowWithSibling` Positions the toolbar and its sibling on the same row. @@ -3282,13 +3281,13 @@ void SetOneRowWithSibling(); ### Remarks -The framework calls this method when the user clicks the **Show Buttons on One Row** button. +The framework calls this method when the user selects the **Show Buttons on One Row** button. -Call the [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar) method to enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. If you call [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar) for this toolbar, the sibling toolbar is moved to the row of this toolbar. Otherwise, this toolbar is moved to the row of the sibling. +Call the [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar) method to enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. If you call [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar) for this toolbar, the sibling toolbar is moved to the row of this toolbar. Otherwise, this toolbar is moved to the row of the sibling. -The framework calls the [CMFCToolBar::SetTwoRowsWithSibling](#settworowswithsibling) method when the user clicks the **Show Buttons on Two Rows** button. +The framework calls the [`CMFCToolBar::SetTwoRowsWithSibling`](#settworowswithsibling) method when the user selects the **Show Buttons on Two Rows** button. -## CMFCToolBar::SetOrigButtons +## `CMFCToolBar::SetOrigButtons` ```cpp void SetOrigButtons(const CObList& lstOrigButtons); @@ -3296,11 +3295,11 @@ void SetOrigButtons(const CObList& lstOrigButtons); ### Parameters -[in] *lstOrigButtons*
+[in] *`lstOrigButtons`* ### Remarks -## CMFCToolBar::SetPermament +## `CMFCToolBar::SetPermament` Specifies whether a user can close the toolbar. @@ -3310,16 +3309,16 @@ void SetPermament(BOOL bPermament=TRUE); ### Parameters -*bPermament*
-[in] A Boolean value that specifies whether a user can close the toolbar. If this parameter is TRUE, a user cannot close the toolbar. Otherwise, a user can close the toolbar. +*`bPermament`*\ +[in] A Boolean value that specifies whether a user can close the toolbar. If this parameter is `TRUE`, a user cannot close the toolbar. Otherwise, a user can close the toolbar. ### Remarks By default, a user can close each toolbar. -Call the [CMFCToolBar::CanBeClosed](#canbeclosed) method to determine whether a user can close the toolbar. +Call the [`CMFCToolBar::CanBeClosed`](#canbeclosed) method to determine whether a user can close the toolbar. -## CMFCToolBar::SetRouteCommandsViaFrame +## `CMFCToolBar::SetRouteCommandsViaFrame` Specifies whether the parent frame or the owner sends commands to the toolbar. @@ -3329,14 +3328,14 @@ void SetRouteCommandsViaFrame(BOOL bValue); ### Parameters -*bValue*
-[in] If this parameter is TRUE, the parent frame sends commands to the toolbar. Otherwise, the owner sends commands to the toolbar. +*`bValue`*\ +[in] If this parameter is `TRUE`, the parent frame sends commands to the toolbar. Otherwise, the owner sends commands to the toolbar. ### Remarks -By default, the parent frame sends commands to the toolbar. Call the [CMFCToolBar::GetRouteCommandsViaFrame](#getroutecommandsviaframe) method to determine whether the parent frame or the owner sends commands to the toolbar. +By default, the parent frame sends commands to the toolbar. Call the [`CMFCToolBar::GetRouteCommandsViaFrame`](#getroutecommandsviaframe) method to determine whether the parent frame or the owner sends commands to the toolbar. -## CMFCToolBar::SetShowTooltips +## `CMFCToolBar::SetShowTooltips` Specifies whether the framework displays tool tips. @@ -3346,16 +3345,16 @@ static void SetShowTooltips(BOOL bValue); ### Parameters -*bValue*
-[in] If this parameter is TRUE, the framework shows tool tips. Otherwise, the framework hides tool tips. +*`bValue`*\ +[in] If this parameter is `TRUE`, the framework shows tool tips. Otherwise, the framework hides tool tips. ### Remarks By default, the framework shows tool tips. -Call the [CMFCToolBar::GetShowTooltips](#getshowtooltips) method to determine whether the framework shows tool tips. +Call the [`CMFCToolBar::GetShowTooltips`](#getshowtooltips) method to determine whether the framework shows tool tips. -## CMFCToolBar::SetSiblingToolBar +## `CMFCToolBar::SetSiblingToolBar` Specifies the sibling of the toolbar. @@ -3365,18 +3364,18 @@ void SetSiblingToolBar(CMFCToolBar* pBrotherToolbar); ### Parameters -*pBrotherToolbar*
+*`pBrotherToolbar`*\ [in] A pointer to the sibling toolbar. ### Remarks This method enables the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons that are shown when the user displays the **Customize** pop-up menu. Call this method when you want to enable the user to specify whether related toolbars appear on the same row or on different rows. -Call this method after you enable the **Customize** button that appears on the toolbar. To enable the **Customize** button, call the [CMFCToolBar::EnableCustomizeButton](#enablecustomizebutton) method. +Call this method after you enable the **Customize** button that appears on the toolbar. To enable the **Customize** button, call the [`CMFCToolBar::EnableCustomizeButton`](#enablecustomizebutton) method. -To retrieve the sibling of a toolbar, call [CMFCToolBar::GetSiblingToolBar](#getsiblingtoolbar). +To retrieve the sibling of a toolbar, call [`CMFCToolBar::GetSiblingToolBar`](#getsiblingtoolbar). -## CMFCToolBar::SetSizes +## `CMFCToolBar::SetSizes` Specifies the sizes of buttons and images on all toolbars. @@ -3388,19 +3387,19 @@ static void __stdcall SetSizes( ### Parameters -*sizeButton*
+*`sizeButton`*\ [in] The size of toolbar buttons, in pixels. -*sizeImage*
+*`sizeImage`*\ [in] The size of toolbar button images, in pixels. ### Remarks The default size of toolbar buttons is 23x22 pixels. The default size of toolbar button images is 16x15 pixels. -Call the [CMFCToolBar::GetImageSize](#getimagesize) method to retrieve the size of toolbar button images. Call the [CMFCToolBar::GetButtonSize](#getbuttonsize) method to retrieve the size of toolbar buttons. +Call the [`CMFCToolBar::GetImageSize`](#getimagesize) method to retrieve the size of toolbar button images. Call the [`CMFCToolBar::GetButtonSize`](#getbuttonsize) method to retrieve the size of toolbar buttons. -## CMFCToolBar::SetToolBarBtnText +## `CMFCToolBar::SetToolBarBtnText` Specifies properties of a button on the toolbar. @@ -3414,25 +3413,25 @@ void SetToolBarBtnText( ### Parameters -*nBtnIndex*
+*`nBtnIndex`*\ [in] The zero-based index of the toolbar button in the list of toolbar buttons. -*szText*
+*`szText`*\ [in] Specifies the text label of the toolbar button. -*bShowText*
-[in] If this parameter is TRUE, the framework shows the text label. Otherwise, the framework hides the text label. +*`bShowText`*\ +[in] If this parameter is `TRUE`, the framework shows the text label. Otherwise, the framework hides the text label. -*bShowImage*
-[in] If this parameter is TRUE, the framework shows the toolbar button image. Otherwise, the framework hides the toolbar button image. +*`bShowImage`*\ +[in] If this parameter is `TRUE`, the framework shows the toolbar button image. Otherwise, the framework hides the toolbar button image. ### Remarks By default, the framework shows the images of toolbar buttons but does not show the text label of toolbar buttons. -In Debug builds, this method generates an assertion failure if *nBtnIndex* does not refer to a valid toolbar button or the toolbar button is a separator. +In Debug builds, this method generates an assertion failure if *`nBtnIndex`* does not refer to a valid toolbar button or the toolbar button is a separator. -## CMFCToolBar::SetTwoRowsWithSibling +## `CMFCToolBar::SetTwoRowsWithSibling` Positions the toolbar and its sibling on separate rows. @@ -3442,13 +3441,13 @@ void SetTwoRowsWithSibling(); ### Remarks -The framework calls this method when the user clicks the **Show Buttons on Two Rows** button. +The framework calls this method when the user selects the **Show Buttons on Two Rows** button. -Call the [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar) method to enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. If you call [CMFCToolBar::SetSiblingToolBar](#setsiblingtoolbar) for this toolbar, the sibling toolbar is moved to a separate row. Otherwise, this toolbar is moved to a separate row. +Call the [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar) method to enable the **Show Buttons on One Row** or **Show Buttons on Two Rows** buttons. If you call [`CMFCToolBar::SetSiblingToolBar`](#setsiblingtoolbar) for this toolbar, the sibling toolbar is moved to a separate row. Otherwise, this toolbar is moved to a separate row. -The framework calls the [CMFCToolBar::SetOneRowWithSibling](#setonerowwithsibling) method when the user clicks the **Show Buttons on One Row** button. +The framework calls the [`CMFCToolBar::SetOneRowWithSibling`](#setonerowwithsibling) method when the user selects the **Show Buttons on One Row** button. -## CMFCToolBar::SetUserImages +## `CMFCToolBar::SetUserImages` Sets the collection of user-defined images in the application. @@ -3458,7 +3457,7 @@ static BOOL SetUserImages(CMFCToolBarImages* pUserImages); ### Parameters -*pUserImages*
+*`pUserImages`*\ [in] A pointer to the collection of user-defined images. ### Return Value @@ -3467,15 +3466,15 @@ Nonzero if the method succeeds; otherwise 0 if the specified `CMFCToolBarImages` ### Remarks -The framework uses user-defined images to draw toolbar buttons that are customized by the user. The image list specified by *pUserImages* is shared among all toolbars in the application. +The framework uses user-defined images to draw toolbar buttons that are customized by the user. The image list specified by *`pUserImages`* is shared among all toolbars in the application. This method generates an assertion failure in Debug builds if the specified `CMFCToolBarImages` object is not valid or has an image size that differs from the default image size of the toolbar. The OutlookDemo, ToolTipDemo, and VisualStudioDemo samples use this method to set the global collection of user-defined images. They load the file that is named UserImages.bmp, which is located in the working directory of the application. -Call the [CMFCToolBar::GetUserImages](#getuserimages) method to retrieve the collection of user-defined images in the application. +Call the [`CMFCToolBar::GetUserImages`](#getuserimages) method to retrieve the collection of user-defined images in the application. -## CMFCToolBar::StretchPane +## `CMFCToolBar::StretchPane` Stretches the toolbar vertically or horizontally, and repositions the buttons if necessary. @@ -3487,11 +3486,11 @@ virtual CSize StretchPane( ### Parameters -*nLength*
+*`nLength`*\ [in] The amount, in pixels, by which to stretch the pane. -*bVert*
-[in] If TRUE, stretches the pane vertically. If FALSE, stretches the pane horizontally. +*`bVert`*\ +[in] If `TRUE`, stretches the pane vertically. If `FALSE`, stretches the pane horizontally. ### Return Value @@ -3499,11 +3498,11 @@ A `CSize` object that specifies the size of the toolbar client area. ### Remarks -This method calls [CMFCToolBar::WrapToolBar](#wraptoolbar) to reposition the buttons within the stretched toolbar. +This method calls [`CMFCToolBar::WrapToolBar`](#wraptoolbar) to reposition the buttons within the stretched toolbar. -The return value is determined by calling [CMFCToolBar::CalcSize](#calcsize). +The return value is determined by calling [`CMFCToolBar::CalcSize`](#calcsize). -## CMFCToolBar::TranslateChar +## `CMFCToolBar::TranslateChar` Executes a button command if the specified key code corresponds to a valid keyboard shortcut. @@ -3513,18 +3512,18 @@ virtual BOOL TranslateChar(UINT nChar); ### Parameters -*nChar*
-[in] Specifies a virtual key code. For a list of standard virtual key codes, see Winuser.h +*`nChar`*\ +[in] Specifies a virtual key code. For a list of standard virtual key codes, see `Winuser.h` ### Return Value -FALSE if the specified key code is either unprintable or does not correspond to a valid keyboard shortcut; TRUE if the specified key code corresponds to a drop-down menu option; otherwise, the return value from [CMFCToolBar::ProcessCommand](#processcommand). +`FALSE` if the specified key code is either unprintable or does not correspond to a valid keyboard shortcut; `TRUE` if the specified key code corresponds to a drop-down menu option; otherwise, the return value from [`CMFCToolBar::ProcessCommand`](#processcommand). ### Remarks -The framework calls this method when a key is pressed together with the Alt key. +The framework calls this method when a key is pressed together with the **Alt** key. -## CMFCToolBar::UpdateButton +## `CMFCToolBar::UpdateButton` Updates the state of the specified button. @@ -3534,12 +3533,12 @@ void UpdateButton(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ [in] Specifies the zero-based index of the button to update. ### Remarks -## CMFCToolBar::WrapToolBar +## `CMFCToolBar::WrapToolBar` Repositions toolbar buttons within the given dimensions. @@ -3554,19 +3553,19 @@ int WrapToolBar( ### Parameters -*nWidth*
+*`nWidth`*\ [in] Maximum width of the toolbar. -*nHeight*
+*`nHeight`*\ [in] Maximum height of the toolbar. Not used if the toolbar is floating. -*pDC*
-[in] Pointer to a device context. If NULL, the device context for the toolbar is used. +*`pDC`*\ +[in] Pointer to a device context. If `NULL`, the device context for the toolbar is used. -*nColumnWidth*
+*`nColumnWidth`*\ [in] Button width. If -1, the current width is used. -[in] m *nRowHeight* +[in] `m` *`nRowHeight`* Button height. If -1, the current height is used. ### Return Value @@ -3577,21 +3576,20 @@ The number of rows of buttons on the toolbar. This method repositions buttons within the toolbar, wrapping buttons to additional rows if necessary. -## CMFCToolBar::m_bDontScaleImages +## `CMFCToolBar::m_bDontScaleImages` Specifies whether or not to scale toolbar images in high DPI mode. +Set to `TRUE` to prevent image scaling when an image size doesn't match a button size. ``` AFX_IMPORT_DATA static BOOL m_bDontScaleImages; ``` -### Remarks - ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCMenuBar Class](../../mfc/reference/cmfcmenubar-class.md)
-[CMFCPopupMenuBar Class](../../mfc/reference/cmfcpopupmenubar-class.md)
-[CMFCDropDownToolBar Class](../../mfc/reference/cmfcdropdowntoolbar-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CMFCMenuBar` Class](../../mfc/reference/cmfcmenubar-class.md)\ +[`CMFCPopupMenuBar` Class](../../mfc/reference/cmfcpopupmenubar-class.md)\ +[`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md)\ [Walkthrough: Putting Controls On Toolbars](../../mfc/walkthrough-putting-controls-on-toolbars.md) diff --git a/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md b/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md index 788354e40d..af756deef3 100644 --- a/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md +++ b/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md @@ -518,7 +518,7 @@ virtual BOOL OnAssignKey(ACCEL* pAccel); ### Parameters *pAccel*
-[in, out] Pointer to the proposed keyboard assigment that is expressed as an [ACCEL](/windows/win32/api/winuser/ns-winuser-accel) struct. +[in, out] Pointer to the proposed keyboard assignment that is expressed as an [ACCEL](/windows/win32/api/winuser/ns-winuser-accel) struct. ### Return Value diff --git a/docs/mfc/reference/cmfctooltipctrl-class.md b/docs/mfc/reference/cmfctooltipctrl-class.md index 5c4d7f2204..9f75f1de91 100644 --- a/docs/mfc/reference/cmfctooltipctrl-class.md +++ b/docs/mfc/reference/cmfctooltipctrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCToolTipCtrl Class" title: "CMFCToolTipCtrl Class" +description: "Learn more about: CMFCToolTipCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolTipCtrl", "AFXTOOLTIPCTRL/CMFCToolTipCtrl", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::GetIconSize", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::GetParams", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnDrawBorder", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnDrawDescription", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnDrawIcon", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnDrawLabel", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnDrawSeparator", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::OnFillBackground", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::SetDescription", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::SetFixedWidth", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::SetHotRibbonButton", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::SetLocation", "AFXTOOLTIPCTRL/CMFCToolTipCtrl::SetParams"] helpviewer_keywords: ["CMFCToolTipCtrl [MFC], GetIconSize", "CMFCToolTipCtrl [MFC], GetParams", "CMFCToolTipCtrl [MFC], OnDrawBorder", "CMFCToolTipCtrl [MFC], OnDrawDescription", "CMFCToolTipCtrl [MFC], OnDrawIcon", "CMFCToolTipCtrl [MFC], OnDrawLabel", "CMFCToolTipCtrl [MFC], OnDrawSeparator", "CMFCToolTipCtrl [MFC], OnFillBackground", "CMFCToolTipCtrl [MFC], SetDescription", "CMFCToolTipCtrl [MFC], SetFixedWidth", "CMFCToolTipCtrl [MFC], SetHotRibbonButton", "CMFCToolTipCtrl [MFC], SetLocation", "CMFCToolTipCtrl [MFC], SetParams"] -ms.assetid: 9fbfcfb1-a8ab-417f-ae29-9a9ca85ee58f --- # CMFCToolTipCtrl Class @@ -149,7 +148,7 @@ const CMFCToolTipInfo& GetParams() const; ### Return Value -The current tooltip display settings , which are stored in a [CMFCToolTipInfo Class](../../mfc/reference/cmfctooltipinfo-class.md) object. +The current tooltip display settings, which are stored in a [CMFCToolTipInfo Class](../../mfc/reference/cmfctooltipinfo-class.md) object. ## CMFCToolTipCtrl::OnDrawBorder @@ -391,9 +390,9 @@ Whenever the tooltip is displayed, it is drawn by using the colors and visual st ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CToolTipCtrl Class](../../mfc/reference/ctooltipctrl-class.md)
-[CTooltipManager Class](../../mfc/reference/ctooltipmanager-class.md)
-[CMFCToolTipInfo Class](../../mfc/reference/cmfctooltipinfo-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[CToolTipCtrl Class](../../mfc/reference/ctooltipctrl-class.md)\ +[CTooltipManager Class](../../mfc/reference/ctooltipmanager-class.md)\ +[CMFCToolTipInfo Class](../../mfc/reference/cmfctooltipinfo-class.md)\ [CWinAppEx Class](../../mfc/reference/cwinappex-class.md) diff --git a/docs/mfc/reference/cmfcvisualmanager-class.md b/docs/mfc/reference/cmfcvisualmanager-class.md index 30656dd923..fe9a063078 100644 --- a/docs/mfc/reference/cmfcvisualmanager-class.md +++ b/docs/mfc/reference/cmfcvisualmanager-class.md @@ -556,7 +556,7 @@ An application can only have one `CMFCVisualManager` object associated with it. ## CMFCVisualManager::GetMDITabsBordersSize -The framework calls this method to determine the border size of a MDITabs window before it draws the window. +The framework calls this method to determine the border size of an MDITabs window before it draws the window. ``` virtual int GetMDITabsBordersSize(); diff --git a/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md b/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md index a2ca2ffc89..b7e77059dc 100644 --- a/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md +++ b/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMFCVisualManagerOffice2003 Class" title: "CMFCVisualManagerOffice2003 Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCVisualManagerOffice2003 Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCVisualManagerOffice2003", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::DrawComboBorderWinXP", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::DrawComboDropButtonWinXP", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::DrawCustomizeButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::DrawPushButtonWinXP", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetBaseThemeColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetHighlightMenuItemColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetPropertyGridGroupColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetPropertyGridGroupTextColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetShowAllMenuItemsHeight", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetSmartDockingBaseGuideColors", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetSmartDockingHighlightToneColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetTabFrameColors", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetToolBarCustomizeButtonMargin", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetToolbarDisabledColor", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::GetToolTipInfo", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsDefaultWinXPColorsEnabled", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsDockingTabHasBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsHighlightOneNoteTabs", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsOffsetPressedButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsStatusBarOfficeXPLook", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsToolbarRoundShape", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsUseGlobalTheme", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::IsWindowsThemingSupported", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawAutoHideButtonBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawBarGripper", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawBrowseButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawButtonBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawCaptionBarBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawCheckBoxEx", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawComboBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawComboDropButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawControlBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawExpandingBox", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawHeaderCtrlBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawMenuBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawOutlookBarSplitter", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawOutlookPageButtonBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawPaneBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawPaneCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawPopupWindowBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawPopupWindowButtonBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawPopupWindowCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonButtonsGroup", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonCategoryCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonCategoryTab", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonProgressBar", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonQuickAccessToolBarSeparator", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonSliderChannel", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonSliderThumb", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonSliderZoomButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawRibbonStatusBarPane", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawScrollButtons", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawSeparator", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawShowAllMenuItems", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawStatusBarPaneBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawStatusBarProgress", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawStatusBarSizeBox", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTab", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTabsButtonBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTask", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTasksGroupAreaBorder", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTasksGroupCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnDrawTearOffCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnErasePopupWindowButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnEraseTabsArea", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnEraseTabsButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnEraseTabsFrame", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillAutoHideButtonBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillBarBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillButtonInterior", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillCommandsListBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillHeaderCtrlBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillHighlightedArea", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillOutlookBarCaption", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillOutlookPageButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillPopupWindowBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillTab", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillTasksGroupInterior", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnFillTasksPaneBackground", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnHighlightQuickCustomizeMenuButton", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnHighlightRarelyUsedMenuItems", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::OnUpdateSystemColors", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::SetDefaultWinXPColors", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::SetStatusBarOfficeXPLook", "AFXVISUALMANAGEROFFICE2003/CMFCVisualManagerOffice2003::SetUseGlobalTheme"] helpviewer_keywords: ["CMFCVisualManagerOffice2003 Class [MFC]"] -ms.assetid: 115482cd-e349-450a-8dc4-c6023d092aab --- # CMFCVisualManagerOffice2003 Class @@ -1265,7 +1264,7 @@ Override this method in a derived visual manager to customize the appearance of ## CMFCVisualManagerOffice2003::OnDrawRibbonProgressBar -The framework calls this method when it draws a [CMFCRibbonProgressBar Class](../../mfc/reference/cmfcribbonprogressbar-class.md)object. +The framework calls this method when it draws a [CMFCRibbonProgressBar Class](../../mfc/reference/cmfcribbonprogressbar-class.md) object. ``` virtual void OnDrawRibbonProgressBar( diff --git a/docs/mfc/reference/cmfcvisualmanagervs2005-class.md b/docs/mfc/reference/cmfcvisualmanagervs2005-class.md index fc636e4728..4f612c6a6d 100644 --- a/docs/mfc/reference/cmfcvisualmanagervs2005-class.md +++ b/docs/mfc/reference/cmfcvisualmanagervs2005-class.md @@ -23,7 +23,7 @@ class CMFCVisualManagerVS2005 : public CMFCVisualManagerOffice2003 |Name|Description| |----------|-----------------| |[CMFCVisualManagerVS2005::GetDockingTabsBordersSize](#getdockingtabsborderssize)|The framework calls this method when it draws a pane that is docked and tabbed. (Overrides [CMFCVisualManager::GetDockingTabsBordersSize](../../mfc/reference/cmfcvisualmanager-class.md#getdockingtabsborderssize).)| -|[CMFCVisualManagerVS2005::GetMDITabsBordersSize](#getmditabsborderssize)|The framework calls this method to determine the border size of a MDITabs window before it draws the window. (Overrides [CMFCVisualManager::GetMDITabsBordersSize](../../mfc/reference/cmfcvisualmanager-class.md#getmditabsborderssize).)| +|[CMFCVisualManagerVS2005::GetMDITabsBordersSize](#getmditabsborderssize)|The framework calls this method to determine the border size of an MDITabs window before it draws the window. (Overrides [CMFCVisualManager::GetMDITabsBordersSize](../../mfc/reference/cmfcvisualmanager-class.md#getmditabsborderssize).)| |[CMFCVisualManagerVS2005::GetPropertyGridGroupColor](#getpropertygridgroupcolor)|(Overrides [CMFCVisualManagerOffice2003::GetPropertyGridGroupColor](../../mfc/reference/cmfcvisualmanageroffice2003-class.md#getpropertygridgroupcolor).)| |[CMFCVisualManagerVS2005::GetTabFrameColors](#gettabframecolors)|(Overrides [CMFCVisualManagerOffice2003::GetTabFrameColors](../../mfc/reference/cmfcvisualmanageroffice2003-class.md#gettabframecolors).)| |[CMFCVisualManagerVS2005::HasOverlappedAutoHideButtons](#hasoverlappedautohidebuttons)|Returns whether auto-hide buttons overlap in the current visual manager. (Overrides [CMFCVisualManager::HasOverlappedAutoHideButtons](../../mfc/reference/cmfcvisualmanager-class.md#hasoverlappedautohidebuttons).)| diff --git a/docs/mfc/reference/cminiframewnd-class.md b/docs/mfc/reference/cminiframewnd-class.md index 6b0df289be..c62e43effd 100644 --- a/docs/mfc/reference/cminiframewnd-class.md +++ b/docs/mfc/reference/cminiframewnd-class.md @@ -114,7 +114,7 @@ Specifies the window style attributes. These can include standard window styles - MFS_BLOCKSYSMENU Disables access to the system menu and the control menu, and converts them to part of the caption (title bar). -See [CWnd::Create](../../mfc/reference/cwnd-class.md#create) for a description of possible window style values. The typical combination used for mini-frame windows is WS_POPUP|WS_CAPTION|WS_SYSMENU. +See [CWnd::Create](../../mfc/reference/cwnd-class.md#create) for a description of possible window style values. The typical combination used for mini-frame windows is `WS_POPUP|WS_CAPTION|WS_SYSMENU`. *rect*
A `RECT` structure specifying the desired dimensions of the window. diff --git a/docs/mfc/reference/cmonthcalctrl-class.md b/docs/mfc/reference/cmonthcalctrl-class.md index 75cfdbbb96..8b9469c32a 100644 --- a/docs/mfc/reference/cmonthcalctrl-class.md +++ b/docs/mfc/reference/cmonthcalctrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMonthCalCtrl Class" title: "CMonthCalCtrl Class" -ms.date: "11/04/2016" +description: "Learn more about: CMonthCalCtrl Class" +ms.date: 11/04/2016 f1_keywords: ["CMonthCalCtrl", "AFXDTCTL/CMonthCalCtrl", "AFXDTCTL/CMonthCalCtrl::CMonthCalCtrl", "AFXDTCTL/CMonthCalCtrl::Create", "AFXDTCTL/CMonthCalCtrl::GetCalendarBorder", "AFXDTCTL/CMonthCalCtrl::GetCalendarCount", "AFXDTCTL/CMonthCalCtrl::GetCalendarGridInfo", "AFXDTCTL/CMonthCalCtrl::GetCalID", "AFXDTCTL/CMonthCalCtrl::GetColor", "AFXDTCTL/CMonthCalCtrl::GetCurrentView", "AFXDTCTL/CMonthCalCtrl::GetCurSel", "AFXDTCTL/CMonthCalCtrl::GetFirstDayOfWeek", "AFXDTCTL/CMonthCalCtrl::GetMaxSelCount", "AFXDTCTL/CMonthCalCtrl::GetMaxTodayWidth", "AFXDTCTL/CMonthCalCtrl::GetMinReqRect", "AFXDTCTL/CMonthCalCtrl::GetMonthDelta", "AFXDTCTL/CMonthCalCtrl::GetMonthRange", "AFXDTCTL/CMonthCalCtrl::GetRange", "AFXDTCTL/CMonthCalCtrl::GetSelRange", "AFXDTCTL/CMonthCalCtrl::GetToday", "AFXDTCTL/CMonthCalCtrl::HitTest", "AFXDTCTL/CMonthCalCtrl::IsCenturyView", "AFXDTCTL/CMonthCalCtrl::IsDecadeView", "AFXDTCTL/CMonthCalCtrl::IsMonthView", "AFXDTCTL/CMonthCalCtrl::IsYearView", "AFXDTCTL/CMonthCalCtrl::SetCalendarBorder", "AFXDTCTL/CMonthCalCtrl::SetCalendarBorderDefault", "AFXDTCTL/CMonthCalCtrl::SetCalID", "AFXDTCTL/CMonthCalCtrl::SetCenturyView", "AFXDTCTL/CMonthCalCtrl::SetColor", "AFXDTCTL/CMonthCalCtrl::SetCurrentView", "AFXDTCTL/CMonthCalCtrl::SetCurSel", "AFXDTCTL/CMonthCalCtrl::SetDayState", "AFXDTCTL/CMonthCalCtrl::SetDecadeView", "AFXDTCTL/CMonthCalCtrl::SetFirstDayOfWeek", "AFXDTCTL/CMonthCalCtrl::SetMaxSelCount", "AFXDTCTL/CMonthCalCtrl::SetMonthDelta", "AFXDTCTL/CMonthCalCtrl::SetMonthView", "AFXDTCTL/CMonthCalCtrl::SetRange", "AFXDTCTL/CMonthCalCtrl::SetSelRange", "AFXDTCTL/CMonthCalCtrl::SetToday", "AFXDTCTL/CMonthCalCtrl::SetYearView", "AFXDTCTL/CMonthCalCtrl::SizeMinReq", "AFXDTCTL/CMonthCalCtrl::SizeRectToMin"] helpviewer_keywords: ["CMonthCalCtrl [MFC], CMonthCalCtrl", "CMonthCalCtrl [MFC], Create", "CMonthCalCtrl [MFC], GetCalendarBorder", "CMonthCalCtrl [MFC], GetCalendarCount", "CMonthCalCtrl [MFC], GetCalendarGridInfo", "CMonthCalCtrl [MFC], GetCalID", "CMonthCalCtrl [MFC], GetColor", "CMonthCalCtrl [MFC], GetCurrentView", "CMonthCalCtrl [MFC], GetCurSel", "CMonthCalCtrl [MFC], GetFirstDayOfWeek", "CMonthCalCtrl [MFC], GetMaxSelCount", "CMonthCalCtrl [MFC], GetMaxTodayWidth", "CMonthCalCtrl [MFC], GetMinReqRect", "CMonthCalCtrl [MFC], GetMonthDelta", "CMonthCalCtrl [MFC], GetMonthRange", "CMonthCalCtrl [MFC], GetRange", "CMonthCalCtrl [MFC], GetSelRange", "CMonthCalCtrl [MFC], GetToday", "CMonthCalCtrl [MFC], HitTest", "CMonthCalCtrl [MFC], IsCenturyView", "CMonthCalCtrl [MFC], IsDecadeView", "CMonthCalCtrl [MFC], IsMonthView", "CMonthCalCtrl [MFC], IsYearView", "CMonthCalCtrl [MFC], SetCalendarBorder", "CMonthCalCtrl [MFC], SetCalendarBorderDefault", "CMonthCalCtrl [MFC], SetCalID", "CMonthCalCtrl [MFC], SetCenturyView", "CMonthCalCtrl [MFC], SetColor", "CMonthCalCtrl [MFC], SetCurrentView", "CMonthCalCtrl [MFC], SetCurSel", "CMonthCalCtrl [MFC], SetDayState", "CMonthCalCtrl [MFC], SetDecadeView", "CMonthCalCtrl [MFC], SetFirstDayOfWeek", "CMonthCalCtrl [MFC], SetMaxSelCount", "CMonthCalCtrl [MFC], SetMonthDelta", "CMonthCalCtrl [MFC], SetMonthView", "CMonthCalCtrl [MFC], SetRange", "CMonthCalCtrl [MFC], SetSelRange", "CMonthCalCtrl [MFC], SetToday", "CMonthCalCtrl [MFC], SetYearView", "CMonthCalCtrl [MFC], SizeMinReq", "CMonthCalCtrl [MFC], SizeRectToMin"] -ms.assetid: a42f6bd6-ab5c-4335-82f8-839982fc64a2 --- # CMonthCalCtrl Class @@ -320,7 +319,7 @@ A pointer to a [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemti ### Return Value -Nonzero if successful; otherwize 0. +Nonzero if successful; otherwise 0. ### Remarks diff --git a/docs/mfc/reference/cmousemanager-class.md b/docs/mfc/reference/cmousemanager-class.md index 10ca342ab2..92e14a9af3 100644 --- a/docs/mfc/reference/cmousemanager-class.md +++ b/docs/mfc/reference/cmousemanager-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CMouseManager Class" title: "CMouseManager Class" +description: "Learn more about: CMouseManager Class" ms.date: "11/04/2016" f1_keywords: ["CMouseManager", "AFXMOUSEMANAGER/CMouseManager", "AFXMOUSEMANAGER/CMouseManager::AddView", "AFXMOUSEMANAGER/CMouseManager::GetViewDblClickCommand", "AFXMOUSEMANAGER/CMouseManager::GetViewIconId", "AFXMOUSEMANAGER/CMouseManager::GetViewIdByName", "AFXMOUSEMANAGER/CMouseManager::GetViewNames", "AFXMOUSEMANAGER/CMouseManager::LoadState", "AFXMOUSEMANAGER/CMouseManager::SaveState", "AFXMOUSEMANAGER/CMouseManager::SetCommandForDblClk"] helpviewer_keywords: ["CMouseManager [MFC], AddView", "CMouseManager [MFC], GetViewDblClickCommand", "CMouseManager [MFC], GetViewIconId", "CMouseManager [MFC], GetViewIdByName", "CMouseManager [MFC], GetViewNames", "CMouseManager [MFC], LoadState", "CMouseManager [MFC], SaveState", "CMouseManager [MFC], SetCommandForDblClk"] -ms.assetid: a4d05017-4e44-4a40-8b57-4ece0de20481 --- # CMouseManager Class @@ -33,7 +32,7 @@ class CMouseManager : public CObject ## Remarks -The `CMouseManager` class maintains a collection of `CView` objects. Each view is identified by a name and by an ID. These views are shown in the **Customization** dialog box. The user can change the command that is associated with any view through the **Customization** dialog box. The associated command is executed when the user double-clicks in that view. To support this from a coding perspective, you must process the WM_LBUTTONDBLCLK message and call the [CWinAppEx::OnViewDoubleClick](../../mfc/reference/cwinappex-class.md#onviewdoubleclick) function in the code for that `CView` object.. +The `CMouseManager` class maintains a collection of `CView` objects. Each view is identified by a name and by an ID. These views are shown in the **Customization** dialog box. The user can change the command that is associated with any view through the **Customization** dialog box. The associated command is executed when the user double-clicks in that view. To support this from a coding perspective, you must process the WM_LBUTTONDBLCLK message and call the [CWinAppEx::OnViewDoubleClick](../../mfc/reference/cwinappex-class.md#onviewdoubleclick) function in the code for that `CView` object. You should not create a `CMouseManager` object manually. It will be created by the framework of your application. It will also be destroyed automatically when the user exits the application. To get a pointer to the mouse manager for your application, call [CWinAppEx::GetMouseManager](../../mfc/reference/cwinappex-class.md#getmousemanager). @@ -246,7 +245,7 @@ If *uiCmd* is set to 0, the specified view is no longer associated with a comman ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CWinAppEx Class](../../mfc/reference/cwinappex-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[CWinAppEx Class](../../mfc/reference/cwinappex-class.md)\ [Keyboard and Mouse Customization](../../mfc/keyboard-and-mouse-customization.md) diff --git a/docs/mfc/reference/cobarray-class.md b/docs/mfc/reference/cobarray-class.md index 2f8d493a34..40abda7c8d 100644 --- a/docs/mfc/reference/cobarray-class.md +++ b/docs/mfc/reference/cobarray-class.md @@ -4,7 +4,6 @@ description: "API reference for the `CObArray` `MFC` class which stores `CObject ms.date: "08/27/2020" f1_keywords: ["CObArray", "AFXCOLL/CObArray", "AFXCOLL/CObArray::CObArray", "AFXCOLL/CObArray::Add", "AFXCOLL/CObArray::Append", "AFXCOLL/CObArray::Copy", "AFXCOLL/CObArray::ElementAt", "AFXCOLL/CObArray::FreeExtra", "AFXCOLL/CObArray::GetAt", "AFXCOLL/CObArray::GetCount", "AFXCOLL/CObArray::GetData", "AFXCOLL/CObArray::GetSize", "AFXCOLL/CObArray::GetUpperBound", "AFXCOLL/CObArray::InsertAt", "AFXCOLL/CObArray::IsEmpty", "AFXCOLL/CObArray::RemoveAll", "AFXCOLL/CObArray::RemoveAt", "AFXCOLL/CObArray::SetAt", "AFXCOLL/CObArray::SetAtGrow", "AFXCOLL/CObArray::SetSize"] helpviewer_keywords: ["CObArray [MFC], CObArray", "CObArray [MFC], Add", "CObArray [MFC], Append", "CObArray [MFC], Copy", "CObArray [MFC], ElementAt", "CObArray [MFC], FreeExtra", "CObArray [MFC], GetAt", "CObArray [MFC], GetCount", "CObArray [MFC], GetData", "CObArray [MFC], GetSize", "CObArray [MFC], GetUpperBound", "CObArray [MFC], InsertAt", "CObArray [MFC], IsEmpty", "CObArray [MFC], RemoveAll", "CObArray [MFC], RemoveAt", "CObArray [MFC], SetAt", "CObArray [MFC], SetAtGrow", "CObArray [MFC], SetSize"] -ms.assetid: 27894efd-2370-4776-9ed9-24a98492af17 --- # `CObArray` Class @@ -294,7 +293,7 @@ The following table shows other member functions that are similar to `CObArray:: ### Example - See the example for [`CObArray::GetData`](#getdata). +See the example for [`CObArray::GetData`](#getdata). ## `CObArray::GetAt` @@ -325,7 +324,7 @@ The following table shows other member functions that are similar to `CObArray:: |[`CByteArray`](../../mfc/reference/cbytearray-class.md)|`BYTE GetAt(INT_PTR nIndex) const;`| |[`CDWordArray`](../../mfc/reference/cdwordarray-class.md)|`DWORD GetAt(INT_PTR nIndex) const;`| |[`CPtrArray`](../../mfc/reference/cptrarray-class.md)|`void* GetAt(INT_PTR nIndex) const;`| -|[`CStringArray`](../../mfc/reference/cstringarray-class.md)|`CString GetAt(INT_PTR nIndex) const;`| +|[`CStringArray`](../../mfc/reference/cstringarray-class.md)|`const CString& GetAt(INT_PTR nIndex) const;`| |[`CUIntArray`](../../mfc/reference/cuintarray-class.md)|`UINT GetAt(INT_PTR nIndex) const;`| |[`CWordArray`](../../mfc/reference/cwordarray-class.md)|`WORD GetAt(INT_PTR nIndex) const;`| diff --git a/docs/mfc/reference/coblist-class.md b/docs/mfc/reference/coblist-class.md index 04a2556298..f62fd186b8 100644 --- a/docs/mfc/reference/coblist-class.md +++ b/docs/mfc/reference/coblist-class.md @@ -4,9 +4,8 @@ title: "CObList Class" ms.date: "11/04/2016" f1_keywords: ["CObList", "AFXCOLL/CObList", "AFXCOLL/CObList::CObList", "AFXCOLL/CObList::AddHead", "AFXCOLL/CObList::AddTail", "AFXCOLL/CObList::Find", "AFXCOLL/CObList::FindIndex", "AFXCOLL/CObList::GetAt", "AFXCOLL/CObList::GetCount", "AFXCOLL/CObList::GetHead", "AFXCOLL/CObList::GetHeadPosition", "AFXCOLL/CObList::GetNext", "AFXCOLL/CObList::GetPrev", "AFXCOLL/CObList::GetSize", "AFXCOLL/CObList::GetTail", "AFXCOLL/CObList::GetTailPosition", "AFXCOLL/CObList::InsertAfter", "AFXCOLL/CObList::InsertBefore", "AFXCOLL/CObList::IsEmpty", "AFXCOLL/CObList::RemoveAll", "AFXCOLL/CObList::RemoveAt", "AFXCOLL/CObList::RemoveHead", "AFXCOLL/CObList::RemoveTail", "AFXCOLL/CObList::SetAt"] helpviewer_keywords: ["CObList [MFC], CObList", "CObList [MFC], AddHead", "CObList [MFC], AddTail", "CObList [MFC], Find", "CObList [MFC], FindIndex", "CObList [MFC], GetAt", "CObList [MFC], GetCount", "CObList [MFC], GetHead", "CObList [MFC], GetHeadPosition", "CObList [MFC], GetNext", "CObList [MFC], GetPrev", "CObList [MFC], GetSize", "CObList [MFC], GetTail", "CObList [MFC], GetTailPosition", "CObList [MFC], InsertAfter", "CObList [MFC], InsertBefore", "CObList [MFC], IsEmpty", "CObList [MFC], RemoveAll", "CObList [MFC], RemoveAt", "CObList [MFC], RemoveHead", "CObList [MFC], RemoveTail", "CObList [MFC], SetAt"] -ms.assetid: 80699c93-33d8-4f8b-b8cf-7b58aeab64ca --- -# CObList Class +# `CObList` Class Supports ordered lists of nonunique `CObject` pointers accessible sequentially or by pointer value. @@ -22,52 +21,52 @@ class CObList : public CObject |Name|Description| |----------|-----------------| -|[CObList::CObList](#coblist)|Constructs an empty list for `CObject` pointers.| +|[`CObList::CObList`](#coblist)|Constructs an empty list for `CObject` pointers.| ### Public Methods |Name|Description| |----------|-----------------| -|[CObList::AddHead](#addhead)|Adds an element (or all the elements in another list) to the head of the list (makes a new head).| -|[CObList::AddTail](#addtail)|Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).| -|[CObList::Find](#find)|Gets the position of an element specified by pointer value.| -|[CObList::FindIndex](#findindex)|Gets the position of an element specified by a zero-based index.| -|[CObList::GetAt](#getat)|Gets the element at a given position.| -|[CObList::GetCount](#getcount)|Returns the number of elements in this list.| -|[CObList::GetHead](#gethead)|Returns the head element of the list (cannot be empty).| -|[CObList::GetHeadPosition](#getheadposition)|Returns the position of the head element of the list.| -|[CObList::GetNext](#getnext)|Gets the next element for iterating.| -|[CObList::GetPrev](#getprev)|Gets the previous element for iterating.| -|[CObList::GetSize](#getsize)|Returns the number of elements in this list.| -|[CObList::GetTail](#gettail)|Returns the tail element of the list (cannot be empty).| -|[CObList::GetTailPosition](#gettailposition)|Returns the position of the tail element of the list.| -|[CObList::InsertAfter](#insertafter)|Inserts a new element after a given position.| -|[CObList::InsertBefore](#insertbefore)|Inserts a new element before a given position.| -|[CObList::IsEmpty](#isempty)|Tests for the empty list condition (no elements).| -|[CObList::RemoveAll](#removeall)|Removes all the elements from this list.| -|[CObList::RemoveAt](#removeat)|Removes an element from this list, specified by position.| -|[CObList::RemoveHead](#removehead)|Removes the element from the head of the list.| -|[CObList::RemoveTail](#removetail)|Removes the element from the tail of the list.| -|[CObList::SetAt](#setat)|Sets the element at a given position.| +|[`CObList::AddHead`](#addhead)|Adds an element (or all the elements in another list) to the head of the list (makes a new head).| +|[`CObList::AddTail`](#addtail)|Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).| +|[`CObList::Find`](#find)|Gets the position of an element specified by pointer value.| +|[`CObList::FindIndex`](#findindex)|Gets the position of an element specified by a zero-based index.| +|[`CObList::GetAt`](#getat)|Gets the element at a given position.| +|[`CObList::GetCount`](#getcount)|Returns the number of elements in this list.| +|[`CObList::GetHead`](#gethead)|Returns the head element of the list (can't be empty).| +|[`CObList::GetHeadPosition`](#getheadposition)|Returns the position of the head element of the list.| +|[`CObList::GetNext`](#getnext)|Gets the next element for iterating.| +|[`CObList::GetPrev`](#getprev)|Gets the previous element for iterating.| +|[`CObList::GetSize`](#getsize)|Returns the number of elements in this list.| +|[`CObList::GetTail`](#gettail)|Returns the tail element of the list (can't be empty).| +|[`CObList::GetTailPosition`](#gettailposition)|Returns the position of the tail element of the list.| +|[`CObList::InsertAfter`](#insertafter)|Inserts a new element after a given position.| +|[`CObList::InsertBefore`](#insertbefore)|Inserts a new element before a given position.| +|[`CObList::IsEmpty`](#isempty)|Tests for the empty list condition (no elements).| +|[`CObList::RemoveAll`](#removeall)|Removes all the elements from this list.| +|[`CObList::RemoveAt`](#removeat)|Removes an element from this list, specified by position.| +|[`CObList::RemoveHead`](#removehead)|Removes the element from the head of the list.| +|[`CObList::RemoveTail`](#removetail)|Removes the element from the tail of the list.| +|[`CObList::SetAt`](#setat)|Sets the element at a given position.| ## Remarks `CObList` lists behave like doubly-linked lists. -A variable of type POSITION is a key for the list. You can use a POSITION variable both as an iterator to traverse a list sequentially and as a bookmark to hold a place. A position is not the same as an index, however. +A variable of type `POSITION` is a key for the list. You can use a `POSITION` variable both as an iterator to traverse a list sequentially and as a bookmark to hold a place. A position isn't the same as an index, however. -Element insertion is very fast at the list head, at the tail, and at a known POSITION. A sequential search is necessary to look up an element by value or index. This search can be slow if the list is long. +Element insertion is very fast at the list head, at the tail, and at a known `POSITION`. A sequential search is necessary to look up an element by value or index. This search can be slow if the list is long. -`CObList` incorporates the IMPLEMENT_SERIAL macro to support serialization and dumping of its elements. If a list of `CObject` pointers is stored to an archive, either with an overloaded insertion operator or with the `Serialize` member function, each `CObject` element is serialized in turn. +`CObList` incorporates the `IMPLEMENT_SERIAL` macro to support serialization and dumping of its elements. If a list of `CObject` pointers is stored to an archive, either with an overloaded insertion operator or with the `Serialize` member function, each `CObject` element is serialized in turn. If you need a dump of individual `CObject` elements in the list, you must set the depth of the dump context to 1 or greater. When a `CObList` object is deleted, or when its elements are removed, only the `CObject` pointers are removed, not the objects they reference. -You can derive your own classes from `CObList`. Your new list class, designed to hold pointers to objects derived from `CObject`, adds new data members and new member functions. Note that the resulting list is not strictly type safe, because it allows insertion of any `CObject` pointer. +You can derive your own classes from `CObList`. Your new list class, designed to hold pointers to objects derived from `CObject`, adds new data members and new member functions. Note that the resulting list isn't strictly type safe, because it allows insertion of any `CObject` pointer. > [!NOTE] -> You must use the [IMPLEMENT_SERIAL](run-time-object-model-services.md#implement_serial) macro in the implementation of your derived class if you intend to serialize the list. +> You must use the [`IMPLEMENT_SERIAL`](run-time-object-model-services.md#implement_serial) macro in the implementation of your derived class if you intend to serialize the list. For more information on using `CObList`, see the article [Collections](../../mfc/collections.md). @@ -79,9 +78,9 @@ For more information on using `CObList`, see the article [Collections](../../mfc ## Requirements -**Header:** afxcoll.h +**Header:** `afxcoll.h` -## CObList::AddHead +## `CObList::AddHead` Adds a new element or list of elements to the head of this list. @@ -92,22 +91,22 @@ void AddHead(CObList* pNewList); ### Parameters -*newElement*
+*`newElement`*\ The `CObject` pointer to be added to this list. -*pNewList*
-A pointer to another `CObList` list. The elements in *pNewList* will be added to this list. +*`pNewList`*\ +A pointer to another `CObList` list. The elements in *`pNewList`* will be added to this list. ### Return Value -The first version returns the POSITION value of the newly inserted element. +The first version returns the `POSITION` value of the newly inserted element. The following table shows other member functions that are similar to `CObList::AddHead`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION AddHead( void** \* `newElement` **);**

**void AddHead( CPtrList** \* `pNewList` **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION AddHead(const CString&** `newElement` **);**

**POSITION AddHead(LPCTSTR** `newElement` **);**

**void AddHead(CStringList** \* `pNewList` **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION AddHead( void * newElement );`

`void AddHead( CPtrList * pNewList );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION AddHead(const CString& newElement );`

`POSITION AddHead(LPCTSTR newElement );`

`void AddHead(CStringList * pNewList );`| ### Remarks @@ -115,7 +114,7 @@ The list can be empty before the operation. ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#89](../../mfc/codesnippet/cpp/coblist-class_1.cpp)] @@ -127,7 +126,7 @@ a CAge at $44A8 40 a CAge at $442A 21 ``` -## CObList::AddTail +## `CObList::AddTail` Adds a new element or list of elements to the tail of this list. @@ -138,15 +137,15 @@ void AddTail(CObList* pNewList); ### Parameters -*newElement*
+*`newElement`*\ The `CObject` pointer to be added to this list. -*pNewList*
-A pointer to another `CObList` list. The elements in *pNewList* will be added to this list. +*`pNewList`*\ +A pointer to another `CObList` list. The elements in *`pNewList`* will be added to this list. ### Return Value -The first version returns the POSITION value of the newly inserted element. +The first version returns the `POSITION` value of the newly inserted element. ### Remarks @@ -156,12 +155,12 @@ The following table shows other member functions that are similar to `CObList::A |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION AddTail( void** \* `newElement` **);**

**void AddTail( CPtrList** \* `pNewList` **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION AddTail( const CString&** `newElement` **);**

**POSITION AddTail( LPCTSTR** `newElement` **);**

**void AddTail( CStringList** \* `pNewList` **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION AddTail( void * newElement );`

`void AddTail( CPtrList * pNewList );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION AddTail( const CString& newElement );`

`POSITION AddTail( LPCTSTR newElement );`

`void AddTail( CStringList * pNewList );`| ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#90](../../mfc/codesnippet/cpp/coblist-class_2.cpp)] @@ -173,7 +172,7 @@ a CAge at $444A 21 a CAge at $4526 40 ``` -## CObList::CObList +## `CObList::CObList` Constructs an empty `CObject` pointer list. @@ -183,19 +182,19 @@ CObList(INT_PTR nBlockSize = 10); ### Parameters -*nBlockSize*
+*`nBlockSize`*\ The memory-allocation granularity for extending the list. ### Remarks -As the list grows, memory is allocated in units of *nBlockSize* entries. If a memory allocation fails, a `CMemoryException` is thrown. +As the list grows, memory is allocated in units of *`nBlockSize`* entries. If a memory allocation fails, a `CMemoryException` is thrown. The following table shows other member functions that are similar to `CObList::CObList`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**CPtrList( INT_PTR** `nBlockSize` **= 10 );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**CStringList( INT_PTR** `nBlockSize` **= 10 );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`CPtrList( INT_PTR nBlockSize = 10 );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`CStringList( INT_PTR nBlockSize = 10 );`| ### Example @@ -207,7 +206,7 @@ Below is an example of `CObList` constructor usage: [!code-cpp[NVC_MFCCollections#92](../../mfc/codesnippet/cpp/coblist-class_4.cpp)] -## CObList::Find +## `CObList::Find` Searches the list sequentially to find the first `CObject` pointer matching the specified `CObject` pointer. @@ -219,15 +218,15 @@ POSITION Find( ### Parameters -*searchValue*
+*`searchValue`*\ The object pointer to be found in this list. -*startAfter*
+*`startAfter`*\ The start position for the search. ### Return Value -A POSITION value that can be used for iteration or object pointer retrieval; NULL if the object is not found. +A `POSITION` value that can be used for iteration or object pointer retrieval; `NULL` if the object isn't found. ### Remarks @@ -237,18 +236,18 @@ The following table shows other member functions that are similar to `CObList::F |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION Find( void** \* `searchValue` **, POSITION** `startAfter` **= NULL ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION Find( LPCTSTR** `searchValue` **, POSITION** `startAfter` **= NULL ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION Find( void *searchValue , POSITION startAfter = NULL ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION Find( LPCTSTR searchValue , POSITION startAfter = NULL ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#93](../../mfc/codesnippet/cpp/coblist-class_5.cpp)] -## CObList::FindIndex +## `CObList::FindIndex` -Uses the value of *nIndex* as an index into the list. +Uses the value of *`nIndex`* as an index into the list. ``` POSITION FindIndex(INT_PTR nIndex) const; @@ -256,12 +255,12 @@ POSITION FindIndex(INT_PTR nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ The zero-based index of the list element to be found. ### Return Value -A POSITION value that can be used for iteration or object pointer retrieval; NULL if *nIndex* is too large. (The framework generates an assertion if *nIndex* is negative.) +A `POSITION` value that can be used for iteration or object pointer retrieval; `NULL` if *`nIndex`* is too large. (The framework generates an assertion if *`nIndex`* is negative.) ### Remarks @@ -271,18 +270,18 @@ The following table shows other member functions that are similar to `CObList::F |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION FindIndex( INT_PTR** `nIndex` **) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION FindIndex( INT_PTR** `nIndex` **) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION FindIndex( INT_PTR nIndex ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION FindIndex( INT_PTR nIndex ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#94](../../mfc/codesnippet/cpp/coblist-class_6.cpp)] -## CObList::GetAt +## `CObList::GetAt` -A variable of type POSITION is a key for the list. +A variable of type `POSITION` is a key for the list. ``` CObject*& GetAt(POSITION position); @@ -291,31 +290,31 @@ const CObject*& GetAt(POSITION position) const; ### Parameters -*position*
-A POSITION value returned by a previous `GetHeadPosition` or `Find` member function call. +*`position`*\ +A `POSITION` value returned by a previous `GetHeadPosition` or `Find` member function call. ### Return Value -See the return value description for [GetHead](#gethead). +See the return value description for [`GetHead`](#gethead). ### Remarks -It is not the same as an index, and you cannot operate on a POSITION value yourself. `GetAt` retrieves the `CObject` pointer associated with a given position. +It isn't the same as an index, and you can't operate on a `POSITION` value yourself. `GetAt` retrieves the `CObject` pointer associated with a given position. -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. The following table shows other member functions that are similar to `CObList::GetAt`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**const void\*& GetAt( POSITION** *position* **) const;**

**void\*& GetAt( POSITION** *position* **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**const CString& GetAt( POSITION** *position* **) const;**

**CString& GetAt( POSITION** *position* **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`const void*& GetAt( POSITION position ) const;`

`void*& GetAt( POSITION position );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`const CString& GetAt( POSITION position ) const;`

`CString& GetAt( POSITION position );`| ### Example - See the example for [FindIndex](#findindex). + See the example for [`FindIndex`](#findindex). -## CObList::GetCount +## `CObList::GetCount` Gets the number of elements in this list. @@ -331,16 +330,16 @@ The following table shows other member functions that are similar to `CObList::G |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**INT_PTR GetCount( ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**INT_PTR GetCount( ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`INT_PTR GetCount( ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`INT_PTR GetCount( ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#95](../../mfc/codesnippet/cpp/coblist-class_7.cpp)] -## CObList::GetHead +## `CObList::GetHead` Gets the `CObject` pointer that represents the head element of this list. @@ -357,24 +356,24 @@ If the list is accessed directly or through a pointer to a `CObList`, then `GetH ### Remarks -You must ensure that the list is not empty before calling `GetHead`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [IsEmpty](#isempty) to verify that the list contains elements. +You must ensure that the list isn't empty before calling `GetHead`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [`IsEmpty`](#isempty) to verify that the list contains elements. The following table shows other member functions that are similar to `CObList::GetHead`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**const void\*& GetHead( ) const; void\*& GetHead( );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**const CString& GetHead( ) const; CString& GetHead( );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`const void*& GetHead( ) const; void*& GetHead( );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`const CString& GetHead( ) const; CString& GetHead( );`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. The following example illustrates the use of `GetHead` on the left side of an assignment statement. [!code-cpp[NVC_MFCCollections#96](../../mfc/codesnippet/cpp/coblist-class_8.cpp)] -## CObList::GetHeadPosition +## `CObList::GetHeadPosition` Gets the position of the head element of this list. @@ -384,24 +383,24 @@ POSITION GetHeadPosition() const; ### Return Value -A POSITION value that can be used for iteration or object pointer retrieval; NULL if the list is empty. +A `POSITION` value that can be used for iteration or object pointer retrieval; `NULL` if the list is empty. The following table shows other member functions that are similar to `CObList::GetHeadPosition`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION GetHeadPosition( ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION GetHeadPosition( ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION GetHeadPosition( ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION GetHeadPosition( ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#97](../../mfc/codesnippet/cpp/coblist-class_9.cpp)] -## CObList::GetNext +## `CObList::GetNext` -Gets the list element identified by *rPosition*, then sets *rPosition* to the `POSITION` value of the next entry in the list. +Gets the list element identified by *`rPosition`*, then sets *`rPosition`* to the `POSITION` value of the next entry in the list. ``` CObject*& GetNext(POSITION& rPosition); @@ -410,22 +409,22 @@ const CObject* GetNext(POSITION& rPosition) const; ### Parameters -*rPosition*
-A reference to a POSITION value returned by a previous `GetNext`, `GetHeadPosition`, or other member function call. +*`rPosition`*\ +A reference to a `POSITION` value returned by a previous `GetNext`, `GetHeadPosition`, or other member function call. ### Return Value -See the return value description for [GetHead](#gethead). +See the return value description for [`GetHead`](#gethead). ### Remarks You can use `GetNext` in a forward iteration loop if you establish the initial position with a call to `GetHeadPosition` or `Find`. -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. -If the retrieved element is the last in the list, then the new value of *rPosition* is set to NULL. +If the retrieved element is the last in the list, then the new value of *`rPosition`* is set to `NULL`. -It is possible to remove an element during an iteration. See the example for [RemoveAt](#removeat). +It's possible to remove an element during an iteration. See the example for [`RemoveAt`](#removeat). > [!NOTE] > As of MFC 8.0 the const version of this method has changed to return `const CObject*` instead of `const CObject*&`. This change was made to bring the compiler into conformance with the C++ standard. @@ -434,12 +433,12 @@ The following table shows other member functions that are similar to `CObList::G |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|`void*& GetNext( POSITION&` `rPosition` `);`

`const void* GetNext( POSITION&` `rPosition` `) const;`| -|[CStringList](../../mfc/reference/cstringlist-class.md)|`CString& GetNext( POSITION&` `rPosition` `);`

`const CString& GetNext( POSITION&` `rPosition` `) const;`| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void*& GetNext( POSITION&` `rPosition` `);`

`const void* GetNext( POSITION&` `rPosition` `) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`CString& GetNext( POSITION&` `rPosition` `);`

`const CString& GetNext( POSITION&` `rPosition` `) const;`| ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#98](../../mfc/codesnippet/cpp/coblist-class_10.cpp)] @@ -450,9 +449,9 @@ a CAge at $479C 40 a CAge at $46C0 21 ``` -## CObList::GetPrev +## `CObList::GetPrev` -Gets the list element identified by *rPosition*, then sets *rPosition* to the POSITION value of the previous entry in the list. +Gets the list element identified by *`rPosition`*, then sets *`rPosition`* to the `POSITION` value of the previous entry in the list. ``` CObject*& GetPrev(POSITION& rPosition); @@ -461,20 +460,20 @@ const CObject* GetPrev(POSITION& rPosition) const; ### Parameters -*rPosition*
-A reference to a POSITION value returned by a previous `GetPrev` or other member function call. +*`rPosition`*\ +A reference to a `POSITION` value returned by a previous `GetPrev` or other member function call. ### Return Value -See the return value description for [GetHead](#gethead). +See the return value description for [`GetHead`](#gethead). ### Remarks You can use `GetPrev` in a reverse iteration loop if you establish the initial position with a call to `GetTailPosition` or `Find`. -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. -If the retrieved element is the first in the list, then the new value of *rPosition* is set to NULL. +If the retrieved element is the first in the list, then the new value of *`rPosition`* is set to `NULL`. > [!NOTE] > As of MFC 8.0 the const version of this method has changed to return `const CObject*` instead of `const CObject*&`. This change was made to bring the compiler into conformance with the C++ standard. @@ -483,12 +482,12 @@ The following table shows other member functions that are similar to `CObList::G |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|`void*& GetPrev( POSITION&` `rPosition` `);`

`const void* GetPrev( POSITION&` `rPosition` `) const;`| -|[CStringList](../../mfc/reference/cstringlist-class.md)|`CString& GetPrev( POSITION&` `rPosition` `);`

`const CString& GetPrev( POSITION&` `rPosition` `) const;`| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void*& GetPrev( POSITION&` `rPosition` `);`

`const void* GetPrev( POSITION&` `rPosition` `) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`CString& GetPrev( POSITION&` `rPosition` `);`

`const CString& GetPrev( POSITION&` `rPosition` `) const;`| ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#99](../../mfc/codesnippet/cpp/coblist-class_11.cpp)] @@ -499,7 +498,7 @@ a CAge at $421C 21 a CAge at $421C 40 ``` -## CObList::GetSize +## `CObList::GetSize` Returns the number of list elements. @@ -519,16 +518,16 @@ The following table shows other member functions that are similar to `CObList::G |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**INT_PTR GetSize( ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**INT_PTR GetSize( ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`INT_PTR GetSize( ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`INT_PTR GetSize( ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#100](../../mfc/codesnippet/cpp/coblist-class_12.cpp)] -## CObList::GetTail +## `CObList::GetTail` Gets the `CObject` pointer that represents the tail element of this list. @@ -539,28 +538,28 @@ const CObject*& GetTail() const; ### Return Value -See the return value description for [GetHead](#gethead). +See the return value description for [`GetHead`](#gethead). ### Remarks -You must ensure that the list is not empty before calling `GetTail`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [IsEmpty](#isempty) to verify that the list contains elements. +You must ensure that the list isn't empty before calling `GetTail`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [`IsEmpty`](#isempty) to verify that the list contains elements. The following table shows other member functions that are similar to `CObList::GetTail`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**const void\*& GetTail( ) const; void\*& GetTail( );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**const CString& GetTail( ) const; CString& GetTail( );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`const void*& GetTail( ) const; void*& GetTail( );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`const CString& GetTail( ) const; CString& GetTail( );`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#101](../../mfc/codesnippet/cpp/coblist-class_13.cpp)] -## CObList::GetTailPosition +## `CObList::GetTailPosition` -Gets the position of the tail element of this list; **NULL** if the list is empty. +Gets the position of the tail element of this list; **`NULL`** if the list is empty. ``` POSITION GetTailPosition() const; @@ -568,22 +567,22 @@ POSITION GetTailPosition() const; ### Return Value -A POSITION value that can be used for iteration or object pointer retrieval; NULL if the list is empty. +A `POSITION` value that can be used for iteration or object pointer retrieval; `NULL` if the list is empty. The following table shows other member functions that are similar to `CObList::GetTailPosition`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION GetTailPosition( ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION GetTailPosition( ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION GetTailPosition( ) const;`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION GetTailPosition( ) const;`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#102](../../mfc/codesnippet/cpp/coblist-class_14.cpp)] -## CObList::InsertAfter +## `CObList::InsertAfter` Adds an element to this list after the element at the specified position. @@ -595,26 +594,26 @@ POSITION InsertAfter( ### Parameters -*position*
-A POSITION value returned by a previous `GetNext`, `GetPrev`, or `Find` member function call. +*`position`*\ +A `POSITION` value returned by a previous `GetNext`, `GetPrev`, or `Find` member function call. -*newElement*
+*`newElement`*\ The object pointer to be added to this list. The following table shows other member functions that are similar to `CObList::InsertAfter`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION InsertAfter( POSITION** *position* **, void** \* `newElement` **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION InsertAfter( POSITION** *position* **, const CString&** `newElement` **);**

**POSITION InsertAfter( POSITION** *position* **, LPCTSTR** `newElement` **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION InsertAfter( POSITION position , void * newElement );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION InsertAfter( POSITION position , const CString& newElement );`

`POSITION InsertAfter( POSITION position , LPCTSTR newElement );`| ### Return Value -A POSITION value which is the same as the *position* parameter. +A `POSITION` value that is the same as the *`position`* parameter. ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#103](../../mfc/codesnippet/cpp/coblist-class_15.cpp)] @@ -627,7 +626,7 @@ a CAge at $4A64 65 a CAge at $4968 21 ``` -## CObList::InsertBefore +## `CObList::InsertBefore` Adds an element to this list before the element at the specified position. @@ -639,26 +638,26 @@ POSITION InsertBefore( ### Parameters -*position*
-A POSITION value returned by a previous `GetNext`, `GetPrev`, or `Find` member function call. +*`position`*\ +A `POSITION` value returned by a previous `GetNext`, `GetPrev`, or `Find` member function call. -*newElement*
+*`newElement`*\ The object pointer to be added to this list. ### Return Value -A POSITION value that can be used for iteration or object pointer retrieval; NULL if the list is empty. +A `POSITION` value that can be used for iteration or object pointer retrieval; `NULL` if the list is empty. The following table shows other member functions that are similar to `CObList::InsertBefore`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**POSITION InsertBefore( POSITION** *position* **, void** \* `newElement` **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**POSITION InsertBefore( POSITION** *position* **, const CString&** `newElement` **);**

**POSITION InsertBefore( POSITION** *position* **, LPCTSTR** `newElement` **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`POSITION InsertBefore( POSITION position , void * newElement );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`POSITION InsertBefore( POSITION position , const CString& newElement );`

`POSITION InsertBefore( POSITION position , LPCTSTR newElement );`| ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#104](../../mfc/codesnippet/cpp/coblist-class_16.cpp)] @@ -671,7 +670,7 @@ a CAge at $4B02 65 a CAge at $49E6 21 ``` -## CObList::IsEmpty +## `CObList::IsEmpty` Indicates whether this list contains no elements. @@ -687,14 +686,14 @@ The following table shows other member functions that are similar to `CObList::I |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**BOOL IsEmpty( ) const;**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**BOOL IsEmpty( ) const;**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|**BOOL IsEmpty( ) const;**| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|**BOOL IsEmpty( ) const;**| ### Example - See the example for [RemoveAll](#removeall). + See the example for [`RemoveAll`](#removeall). -## CObList::RemoveAll +## `CObList::RemoveAll` Removes all the elements from this list and frees the associated `CObList` memory. @@ -712,16 +711,16 @@ The following table shows other member functions that are similar to `CObList::R |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**void RemoveAll( );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**void RemoveAll( );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void RemoveAll( );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`void RemoveAll( );`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#105](../../mfc/codesnippet/cpp/coblist-class_17.cpp)] -## CObList::RemoveAt +## `CObList::RemoveAt` Removes the specified element from this list. @@ -731,27 +730,27 @@ void RemoveAt(POSITION position); ### Parameters -*position*
+*`position`*\ The position of the element to be removed from the list. ### Remarks When you remove an element from a `CObList`, you remove the object pointer from the list. It is your responsibility to delete the objects themselves. -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. The following table shows other member functions that are similar to `CObList::RemoveAt`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**void RemoveAt( POSITION** *position* **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**void RemoveAt( POSITION** *position* **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void RemoveAt( POSITION position );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`void RemoveAt( POSITION position );`| ### Example - Be careful when removing an element during a list iteration. The following example shows a removal technique that guarantees a valid **POSITION** value for [GetNext](#getnext). + Be careful when removing an element during a list iteration. The following example shows a removal technique that guarantees a valid **`POSITION`** value for [`GetNext`](#getnext). -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#106](../../mfc/codesnippet/cpp/coblist-class_18.cpp)] @@ -763,7 +762,7 @@ The results from this program are as follows: `a CAge at $4B22 21` -## CObList::RemoveHead +## `CObList::RemoveHead` Removes the element from the head of the list and returns a pointer to it. @@ -777,22 +776,22 @@ The `CObject` pointer previously at the head of the list. ### Remarks -You must ensure that the list is not empty before calling `RemoveHead`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [IsEmpty](#isempty) to verify that the list contains elements. +You must ensure that the list isn't empty before calling `RemoveHead`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [`IsEmpty`](#isempty) to verify that the list contains elements. The following table shows other member functions that are similar to `CObList::RemoveHead`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**void\* RemoveHead( );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**CString RemoveHead( );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void* RemoveHead( );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`CString RemoveHead( );`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#107](../../mfc/codesnippet/cpp/coblist-class_19.cpp)] -## CObList::RemoveTail +## `CObList::RemoveTail` Removes the element from the tail of the list and returns a pointer to it. @@ -806,22 +805,22 @@ A pointer to the object that was at the tail of the list. ### Remarks -You must ensure that the list is not empty before calling `RemoveTail`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [IsEmpty](#isempty) to verify that the list contains elements. +You must ensure that the list isn't empty before calling `RemoveTail`. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use [`IsEmpty`](#isempty) to verify that the list contains elements. The following table shows other member functions that are similar to `CObList::RemoveTail`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**void\* RemoveTail( );**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**CString RemoveTail( );**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void* RemoveTail( );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`CString RemoveTail( );`| ### Example -See [CObList::CObList](#coblist) for a listing of the `CAge` class. +See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#108](../../mfc/codesnippet/cpp/coblist-class_20.cpp)] -## CObList::SetAt +## `CObList::SetAt` Sets the element at a given position. @@ -833,28 +832,28 @@ void SetAt( ### Parameters -*pos*
-The POSITION of the element to be set. +*`pos`*\ +The `POSITION` of the element to be set. -*newElement*
+*`newElement`*\ The `CObject` pointer to be written to the list. ### Remarks -A variable of type POSITION is a key for the list. It is not the same as an index, and you cannot operate on a POSITION value yourself. `SetAt` writes the `CObject` pointer to the specified position in the list. +A variable of type `POSITION` is a key for the list. It isn't the same as an index, and you can't operate on a `POSITION` value yourself. `SetAt` writes the `CObject` pointer to the specified position in the list. -You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts. +You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. The following table shows other member functions that are similar to `CObList::SetAt`. |Class|Member Function| |-----------|---------------------| -|[CPtrList](../../mfc/reference/cptrlist-class.md)|**void SetAt( POSITION** `pos` **, const CString&** `newElement` **);**| -|[CStringList](../../mfc/reference/cstringlist-class.md)|**void SetAt( POSITION** `pos` **, LPCTSTR** `newElement` **);**| +|[`CPtrList`](../../mfc/reference/cptrlist-class.md)|`void SetAt( POSITION pos , const CString& newElement );`| +|[`CStringList`](../../mfc/reference/cstringlist-class.md)|`void SetAt( POSITION pos , LPCTSTR newElement );`| ### Example - See [CObList::CObList](#coblist) for a listing of the `CAge` class. + See [`CObList::CObList`](#coblist) for a listing of the `CAge` class. [!code-cpp[NVC_MFCCollections#109](../../mfc/codesnippet/cpp/coblist-class_21.cpp)] @@ -868,7 +867,7 @@ a CAge at $4DB8 65 ## See also -[CObject Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CStringList Class](../../mfc/reference/cstringlist-class.md)
-[CPtrList Class](../../mfc/reference/cptrlist-class.md) +[`CObject` Class](../../mfc/reference/cobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CStringList` Class](../../mfc/reference/cstringlist-class.md)\ +[`CPtrList` Class](../../mfc/reference/cptrlist-class.md) diff --git a/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h b/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h index e34c0f5e23..c428acdc93 100644 --- a/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h +++ b/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h @@ -1,5 +1,5 @@ public: -// Variable to access programatically defined command link control. +// Variable to access programmatically defined command link control. CButton m_cmdLink; -// Variable to access programatically defined split button control. +// Variable to access programmatically defined split button control. CButton m_splitButton; \ No newline at end of file diff --git a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp index b6138fdf94..170c9fff5e 100644 --- a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp +++ b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp @@ -1,5 +1,5 @@ CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this, - TRUE /* Automatic menus scaning */); + TRUE /* Automatic menus scanning */); CSliderButton btnSlider(ID_SLIDER); btnSlider.SetRange(0, 100); diff --git a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_3.cpp b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_3.cpp index bed3f47541..88446128e8 100644 --- a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_3.cpp +++ b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_3.cpp @@ -1,5 +1,5 @@ CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this, - TRUE /* Automatic menus scaning */, + TRUE /* Automatic menus scanning */, AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS | AFX_CUSTOMIZE_MENU_ANIMATIONS); diff --git a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_4.cpp b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_4.cpp index 78fa084d09..e01076e8ae 100644 --- a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_4.cpp +++ b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_4.cpp @@ -1,5 +1,5 @@ CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this, - TRUE /* Automatic menus scaning */, + TRUE /* Automatic menus scanning */, AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS | AFX_CUSTOMIZE_MENU_ANIMATIONS, // default parameters &lstCustomPages); // pointer to the list of runtime classes of the custom property pages \ No newline at end of file diff --git a/docs/mfc/reference/codesnippet/CPP/cpagerctrl-class_5.cpp b/docs/mfc/reference/codesnippet/CPP/cpagerctrl-class_5.cpp index 8d26f62201..faf40bf858 100644 --- a/docs/mfc/reference/codesnippet/CPP/cpagerctrl-class_5.cpp +++ b/docs/mfc/reference/codesnippet/CPP/cpagerctrl-class_5.cpp @@ -1,4 +1,3 @@ - void CCSplitButton_s2Dlg::OnXIsbuttoninvisible() { BOOL bLeft = m_pager.IsButtonInvisible(PGB_TOPORLEFT); diff --git a/docs/mfc/reference/coleclientitem-class.md b/docs/mfc/reference/coleclientitem-class.md index 6bbc2c72fc..356cf6cdba 100644 --- a/docs/mfc/reference/coleclientitem-class.md +++ b/docs/mfc/reference/coleclientitem-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleClientItem Class" title: "COleClientItem Class" -ms.date: "07/02/2019" +description: "Learn more about: COleClientItem Class" +ms.date: 07/02/2019 f1_keywords: ["COleClientItem", "AFXOLE/COleClientItem", "AFXOLE/COleClientItem::COleClientItem", "AFXOLE/COleClientItem::Activate", "AFXOLE/COleClientItem::ActivateAs", "AFXOLE/COleClientItem::AttachDataObject", "AFXOLE/COleClientItem::CanCreateFromData", "AFXOLE/COleClientItem::CanCreateLinkFromData", "AFXOLE/COleClientItem::CanPaste", "AFXOLE/COleClientItem::CanPasteLink", "AFXOLE/COleClientItem::Close", "AFXOLE/COleClientItem::ConvertTo", "AFXOLE/COleClientItem::CopyToClipboard", "AFXOLE/COleClientItem::CreateCloneFrom", "AFXOLE/COleClientItem::CreateFromClipboard", "AFXOLE/COleClientItem::CreateFromData", "AFXOLE/COleClientItem::CreateFromFile", "AFXOLE/COleClientItem::CreateLinkFromClipboard", "AFXOLE/COleClientItem::CreateLinkFromData", "AFXOLE/COleClientItem::CreateLinkFromFile", "AFXOLE/COleClientItem::CreateNewItem", "AFXOLE/COleClientItem::CreateStaticFromClipboard", "AFXOLE/COleClientItem::CreateStaticFromData", "AFXOLE/COleClientItem::Deactivate", "AFXOLE/COleClientItem::DeactivateUI", "AFXOLE/COleClientItem::Delete", "AFXOLE/COleClientItem::DoDragDrop", "AFXOLE/COleClientItem::DoVerb", "AFXOLE/COleClientItem::Draw", "AFXOLE/COleClientItem::GetActiveView", "AFXOLE/COleClientItem::GetCachedExtent", "AFXOLE/COleClientItem::GetClassID", "AFXOLE/COleClientItem::GetClipboardData", "AFXOLE/COleClientItem::GetDocument", "AFXOLE/COleClientItem::GetDrawAspect", "AFXOLE/COleClientItem::GetExtent", "AFXOLE/COleClientItem::GetIconFromRegistry", "AFXOLE/COleClientItem::GetIconicMetafile", "AFXOLE/COleClientItem::GetInPlaceWindow", "AFXOLE/COleClientItem::GetItemState", "AFXOLE/COleClientItem::GetLastStatus", "AFXOLE/COleClientItem::GetLinkUpdateOptions", "AFXOLE/COleClientItem::GetType", "AFXOLE/COleClientItem::GetUserType", "AFXOLE/COleClientItem::IsInPlaceActive", "AFXOLE/COleClientItem::IsLinkUpToDate", "AFXOLE/COleClientItem::IsModified", "AFXOLE/COleClientItem::IsOpen", "AFXOLE/COleClientItem::IsRunning", "AFXOLE/COleClientItem::OnActivate", "AFXOLE/COleClientItem::OnActivateUI", "AFXOLE/COleClientItem::OnChange", "AFXOLE/COleClientItem::OnDeactivate", "AFXOLE/COleClientItem::OnDeactivateUI", "AFXOLE/COleClientItem::OnGetClipboardData", "AFXOLE/COleClientItem::OnInsertMenus", "AFXOLE/COleClientItem::OnRemoveMenus", "AFXOLE/COleClientItem::OnSetMenu", "AFXOLE/COleClientItem::OnShowControlBars", "AFXOLE/COleClientItem::OnUpdateFrameTitle", "AFXOLE/COleClientItem::ReactivateAndUndo", "AFXOLE/COleClientItem::Release", "AFXOLE/COleClientItem::Reload", "AFXOLE/COleClientItem::Run", "AFXOLE/COleClientItem::SetDrawAspect", "AFXOLE/COleClientItem::SetExtent", "AFXOLE/COleClientItem::SetHostNames", "AFXOLE/COleClientItem::SetIconicMetafile", "AFXOLE/COleClientItem::SetItemRects", "AFXOLE/COleClientItem::SetLinkUpdateOptions", "AFXOLE/COleClientItem::SetPrintDevice", "AFXOLE/COleClientItem::UpdateLink", "AFXOLE/COleClientItem::CanActivate", "AFXOLE/COleClientItem::OnChangeItemPosition", "AFXOLE/COleClientItem::OnDeactivateAndUndo", "AFXOLE/COleClientItem::OnDiscardUndoState", "AFXOLE/COleClientItem::OnGetClipRect", "AFXOLE/COleClientItem::OnGetItemPosition", "AFXOLE/COleClientItem::OnGetWindowContext", "AFXOLE/COleClientItem::OnScrollBy", "AFXOLE/COleClientItem::OnShowItem"] helpviewer_keywords: ["COleClientItem [MFC], COleClientItem", "COleClientItem [MFC], Activate", "COleClientItem [MFC], ActivateAs", "COleClientItem [MFC], AttachDataObject", "COleClientItem [MFC], CanCreateFromData", "COleClientItem [MFC], CanCreateLinkFromData", "COleClientItem [MFC], CanPaste", "COleClientItem [MFC], CanPasteLink", "COleClientItem [MFC], Close", "COleClientItem [MFC], ConvertTo", "COleClientItem [MFC], CopyToClipboard", "COleClientItem [MFC], CreateCloneFrom", "COleClientItem [MFC], CreateFromClipboard", "COleClientItem [MFC], CreateFromData", "COleClientItem [MFC], CreateFromFile", "COleClientItem [MFC], CreateLinkFromClipboard", "COleClientItem [MFC], CreateLinkFromData", "COleClientItem [MFC], CreateLinkFromFile", "COleClientItem [MFC], CreateNewItem", "COleClientItem [MFC], CreateStaticFromClipboard", "COleClientItem [MFC], CreateStaticFromData", "COleClientItem [MFC], Deactivate", "COleClientItem [MFC], DeactivateUI", "COleClientItem [MFC], Delete", "COleClientItem [MFC], DoDragDrop", "COleClientItem [MFC], DoVerb", "COleClientItem [MFC], Draw", "COleClientItem [MFC], GetActiveView", "COleClientItem [MFC], GetCachedExtent", "COleClientItem [MFC], GetClassID", "COleClientItem [MFC], GetClipboardData", "COleClientItem [MFC], GetDocument", "COleClientItem [MFC], GetDrawAspect", "COleClientItem [MFC], GetExtent", "COleClientItem [MFC], GetIconFromRegistry", "COleClientItem [MFC], GetIconicMetafile", "COleClientItem [MFC], GetInPlaceWindow", "COleClientItem [MFC], GetItemState", "COleClientItem [MFC], GetLastStatus", "COleClientItem [MFC], GetLinkUpdateOptions", "COleClientItem [MFC], GetType", "COleClientItem [MFC], GetUserType", "COleClientItem [MFC], IsInPlaceActive", "COleClientItem [MFC], IsLinkUpToDate", "COleClientItem [MFC], IsModified", "COleClientItem [MFC], IsOpen", "COleClientItem [MFC], IsRunning", "COleClientItem [MFC], OnActivate", "COleClientItem [MFC], OnActivateUI", "COleClientItem [MFC], OnChange", "COleClientItem [MFC], OnDeactivate", "COleClientItem [MFC], OnDeactivateUI", "COleClientItem [MFC], OnGetClipboardData", "COleClientItem [MFC], OnInsertMenus", "COleClientItem [MFC], OnRemoveMenus", "COleClientItem [MFC], OnSetMenu", "COleClientItem [MFC], OnShowControlBars", "COleClientItem [MFC], OnUpdateFrameTitle", "COleClientItem [MFC], ReactivateAndUndo", "COleClientItem [MFC], Release", "COleClientItem [MFC], Reload", "COleClientItem [MFC], Run", "COleClientItem [MFC], SetDrawAspect", "COleClientItem [MFC], SetExtent", "COleClientItem [MFC], SetHostNames", "COleClientItem [MFC], SetIconicMetafile", "COleClientItem [MFC], SetItemRects", "COleClientItem [MFC], SetLinkUpdateOptions", "COleClientItem [MFC], SetPrintDevice", "COleClientItem [MFC], UpdateLink", "COleClientItem [MFC], CanActivate", "COleClientItem [MFC], OnChangeItemPosition", "COleClientItem [MFC], OnDeactivateAndUndo", "COleClientItem [MFC], OnDiscardUndoState", "COleClientItem [MFC], OnGetClipRect", "COleClientItem [MFC], OnGetItemPosition", "COleClientItem [MFC], OnGetWindowContext", "COleClientItem [MFC], OnScrollBy", "COleClientItem [MFC], OnShowItem"] -ms.assetid: 7f571b7c-2758-4839-847a-0cf1ef643128 --- # COleClientItem Class @@ -1434,7 +1433,7 @@ Override this function to apply special rules to the resize/move operation. If t ## COleClientItem::OnDeactivate -Called by the framework when the OLE item transitions from the in-place active state ( `activeState`) to the loaded state, meaning that it is deactivated after an in-place activation. +Called by the framework when the OLE item transitions from the in-place active state (`activeState`) to the loaded state, meaning that it is deactivated after an in-place activation. ``` virtual void OnDeactivate(); diff --git a/docs/mfc/reference/colecmdui-class.md b/docs/mfc/reference/colecmdui-class.md index 954ba6ac62..93442684f9 100644 --- a/docs/mfc/reference/colecmdui-class.md +++ b/docs/mfc/reference/colecmdui-class.md @@ -34,7 +34,7 @@ class COleCmdUI : public CCmdUI ## Remarks -In an application that is not enabled for DocObjects, when the user views a menu in the application, MFC processes UPDATE_COMMAND_UI notifcations. Each notification is given a [CCmdUI](../../mfc/reference/ccmdui-class.md) object that can be manipulated to reflect the state of a particular command. However, when your application is enabled for DocObjects, MFC processes UPDATE_OLE_COMMAND_UI notifications and assigns `COleCmdUI` objects. +In an application that is not enabled for DocObjects, when the user views a menu in the application, MFC processes UPDATE_COMMAND_UI notifications. Each notification is given a [CCmdUI](../../mfc/reference/ccmdui-class.md) object that can be manipulated to reflect the state of a particular command. However, when your application is enabled for DocObjects, MFC processes UPDATE_OLE_COMMAND_UI notifications and assigns `COleCmdUI` objects. `COleCmdUI` allows a DocObject to receive commands that originate in its container's user interface (such as FileNew, Open, Print, and so on), and allows a container to receive commands that originate in the DocObject's user interface. Although `IDispatch` could be used to dispatch the same commands, `IOleCommandTarget` provides a simpler way to query and execute because it relies on a standard set of commands, usually without arguments, and no type information is involved. `COleCmdUI` can be used to enable, update, and set other properties of DocObject user interface commands. When you want to invoke the command, call [COleServerDoc::OnExecOleCmd](../../mfc/reference/coleserverdoc-class.md#onexecolecmd). diff --git a/docs/mfc/reference/colecontrolsite-class.md b/docs/mfc/reference/colecontrolsite-class.md index e3cbd72fc0..1e7c3602a6 100644 --- a/docs/mfc/reference/colecontrolsite-class.md +++ b/docs/mfc/reference/colecontrolsite-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleControlSite Class" title: "COleControlSite Class" -ms.date: "11/04/2016" +description: "Learn more about: COleControlSite Class" +ms.date: 11/04/2016 f1_keywords: ["COleControlSite", "AFXOCC/COleControlSite", "AFXOCC/COleControlSite::COleControlSite", "AFXOCC/COleControlSite::BindDefaultProperty", "AFXOCC/COleControlSite::BindProperty", "AFXOCC/COleControlSite::CreateControl", "AFXOCC/COleControlSite::DestroyControl", "AFXOCC/COleControlSite::DoVerb", "AFXOCC/COleControlSite::EnableDSC", "AFXOCC/COleControlSite::EnableWindow", "AFXOCC/COleControlSite::FreezeEvents", "AFXOCC/COleControlSite::GetDefBtnCode", "AFXOCC/COleControlSite::GetDlgCtrlID", "AFXOCC/COleControlSite::GetEventIID", "AFXOCC/COleControlSite::GetExStyle", "AFXOCC/COleControlSite::GetProperty", "AFXOCC/COleControlSite::GetStyle", "AFXOCC/COleControlSite::GetWindowText", "AFXOCC/COleControlSite::InvokeHelper", "AFXOCC/COleControlSite::InvokeHelperV", "AFXOCC/COleControlSite::IsDefaultButton", "AFXOCC/COleControlSite::IsWindowEnabled", "AFXOCC/COleControlSite::ModifyStyle", "AFXOCC/COleControlSite::ModifyStyleEx", "AFXOCC/COleControlSite::MoveWindow", "AFXOCC/COleControlSite::QuickActivate", "AFXOCC/COleControlSite::SafeSetProperty", "AFXOCC/COleControlSite::SetDefaultButton", "AFXOCC/COleControlSite::SetDlgCtrlID", "AFXOCC/COleControlSite::SetFocus", "AFXOCC/COleControlSite::SetProperty", "AFXOCC/COleControlSite::SetPropertyV", "AFXOCC/COleControlSite::SetWindowPos", "AFXOCC/COleControlSite::SetWindowText", "AFXOCC/COleControlSite::ShowWindow", "AFXOCC/COleControlSite::GetControlInfo", "AFXOCC/COleControlSite::m_bIsWindowless", "AFXOCC/COleControlSite::m_ctlInfo", "AFXOCC/COleControlSite::m_dwEventSink", "AFXOCC/COleControlSite::m_dwMiscStatus", "AFXOCC/COleControlSite::m_dwPropNotifySink", "AFXOCC/COleControlSite::m_dwStyle", "AFXOCC/COleControlSite::m_hWnd", "AFXOCC/COleControlSite::m_iidEvents", "AFXOCC/COleControlSite::m_nID", "AFXOCC/COleControlSite::m_pActiveObject", "AFXOCC/COleControlSite::m_pCtrlCont", "AFXOCC/COleControlSite::m_pInPlaceObject", "AFXOCC/COleControlSite::m_pObject", "AFXOCC/COleControlSite::m_pWindowlessObject", "AFXOCC/COleControlSite::m_pWndCtrl", "AFXOCC/COleControlSite::m_rect"] helpviewer_keywords: ["COleControlSite [MFC], COleControlSite", "COleControlSite [MFC], BindDefaultProperty", "COleControlSite [MFC], BindProperty", "COleControlSite [MFC], CreateControl", "COleControlSite [MFC], DestroyControl", "COleControlSite [MFC], DoVerb", "COleControlSite [MFC], EnableDSC", "COleControlSite [MFC], EnableWindow", "COleControlSite [MFC], FreezeEvents", "COleControlSite [MFC], GetDefBtnCode", "COleControlSite [MFC], GetDlgCtrlID", "COleControlSite [MFC], GetEventIID", "COleControlSite [MFC], GetExStyle", "COleControlSite [MFC], GetProperty", "COleControlSite [MFC], GetStyle", "COleControlSite [MFC], GetWindowText", "COleControlSite [MFC], InvokeHelper", "COleControlSite [MFC], InvokeHelperV", "COleControlSite [MFC], IsDefaultButton", "COleControlSite [MFC], IsWindowEnabled", "COleControlSite [MFC], ModifyStyle", "COleControlSite [MFC], ModifyStyleEx", "COleControlSite [MFC], MoveWindow", "COleControlSite [MFC], QuickActivate", "COleControlSite [MFC], SafeSetProperty", "COleControlSite [MFC], SetDefaultButton", "COleControlSite [MFC], SetDlgCtrlID", "COleControlSite [MFC], SetFocus", "COleControlSite [MFC], SetProperty", "COleControlSite [MFC], SetPropertyV", "COleControlSite [MFC], SetWindowPos", "COleControlSite [MFC], SetWindowText", "COleControlSite [MFC], ShowWindow", "COleControlSite [MFC], GetControlInfo", "COleControlSite [MFC], m_bIsWindowless", "COleControlSite [MFC], m_ctlInfo", "COleControlSite [MFC], m_dwEventSink", "COleControlSite [MFC], m_dwMiscStatus", "COleControlSite [MFC], m_dwPropNotifySink", "COleControlSite [MFC], m_dwStyle", "COleControlSite [MFC], m_hWnd", "COleControlSite [MFC], m_iidEvents", "COleControlSite [MFC], m_nID", "COleControlSite [MFC], m_pActiveObject", "COleControlSite [MFC], m_pCtrlCont", "COleControlSite [MFC], m_pInPlaceObject", "COleControlSite [MFC], m_pObject", "COleControlSite [MFC], m_pWindowlessObject", "COleControlSite [MFC], m_pWndCtrl", "COleControlSite [MFC], m_rect"] -ms.assetid: 43970644-5eab-434a-8ba6-56d144ff1e3f --- # COleControlSite Class @@ -358,7 +357,7 @@ Specifies whether the control site wishes to stop accepting events. Nonzero if t ### Remarks -If *bFreeze* is TRUE, the control site requests the control to stop fring events. If *bFreeze* is FALSE, the control site requests the control to continue firing events. +If *bFreeze* is TRUE, the control site requests the control to stop firing events. If *bFreeze* is FALSE, the control site requests the control to continue firing events. > [!NOTE] > The control is not required to stop firing events if requested by the control site. It can continue firing but all subsequent events will be ignored by the control site. @@ -646,7 +645,7 @@ DWORD m_dwMiscStatus; ### Remarks -For more information, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc)in the Windows SDK. +For more information, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. ## COleControlSite::m_dwPropNotifySink @@ -722,7 +721,7 @@ LPOLEOBJECT m_pObject; ## COleControlSite::m_pWindowlessObject -Contains the `IOleInPlaceObjectWindowless`[IOleInPlaceObjectWindowless](/windows/win32/api/ocidl/nn-ocidl-ioleinplaceobjectwindowless) interface of the control. +Contains the [`IOleInPlaceObjectWindowless`](/windows/win32/api/ocidl/nn-ocidl-ioleinplaceobjectwindowless) interface of the control. ``` IOleInPlaceObjectWindowless* m_pWindowlessObject; @@ -774,7 +773,7 @@ Nonzero if the styles are changed, otherwise zero. The control's stock Enabled property will be modified to match the setting for WS_DISABLED. The control's stock Border Style property will be modified to match the requested setting for WS_BORDER. All other styles are applied directly to the control's window handle, if one is present. -Modifies the window styles of the control. Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDK for information about the available window styles. +Modifies the window styles of the control. Styles to be added or removed can be combined by using the bitwise OR (**`|`**) operator. See the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDK for information about the available window styles. If *nFlags* is nonzero, `ModifyStyle` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: @@ -818,7 +817,7 @@ Nonzero if the styles are changed, otherwise zero. The control's stock Appearance property will be modified to match the setting for WS_EX_CLIENTEDGE. All other extended window styles are applied directly to the control's window handle, if one is present. -Modifies the window extended styles of the control site object. Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDK for information about the available window styles. +Modifies the window extended styles of the control site object. Styles to be added or removed can be combined by using the bitwise OR (**`|`**) operator. See the [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDK for information about the available window styles. If *nFlags* is nonzero, `ModifyStyleEx` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: @@ -1012,7 +1011,7 @@ Pointer to the list of arguments. ### Remarks -Extra parameters for the method or property being invoked can be passeed using the *arg_list* parameter. If `SetProperty` encounters an error, an exception is thrown. +Extra parameters for the method or property being invoked can be passed using the *arg_list* parameter. If `SetProperty` encounters an error, an exception is thrown. The type of exception is determined by the return value of the attempt to set the property or method. If the return value is `DISP_E_EXCEPTION`, a `COleDispatchExcpetion` is thrown; otherwise a `COleException`. diff --git a/docs/mfc/reference/colecurrency-class.md b/docs/mfc/reference/colecurrency-class.md index d208b9739d..76b2741245 100644 --- a/docs/mfc/reference/colecurrency-class.md +++ b/docs/mfc/reference/colecurrency-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleCurrency Class" title: "COleCurrency Class" -ms.date: "08/29/2019" +description: "Learn more about: COleCurrency Class" +ms.date: 08/29/2019 f1_keywords: ["COleCurrency", "AFXDISP/COleCurrency", "AFXDISP/COleCurrency::COleCurrency", "AFXDISP/COleCurrency::Format", "AFXDISP/COleCurrency::GetStatus", "AFXDISP/COleCurrency::ParseCurrency", "AFXDISP/COleCurrency::SetCurrency", "AFXDISP/COleCurrency::SetStatus", "AFXDISP/COleCurrency::m_cur", "AFXDISP/COleCurrency::m_status"] helpviewer_keywords: ["COleCurrency [MFC], COleCurrency", "COleCurrency [MFC], Format", "COleCurrency [MFC], GetStatus", "COleCurrency [MFC], ParseCurrency", "COleCurrency [MFC], SetCurrency", "COleCurrency [MFC], SetStatus", "COleCurrency [MFC], m_cur", "COleCurrency [MFC], m_status"] -ms.assetid: 3a36e345-303f-46fb-a57c-858274378a8d --- # COleCurrency Class @@ -290,7 +289,7 @@ A brief description of each operator follows: - **operator =(** `curSrc` **)** The value and status of the operand, an existing `COleCurrency` object are copied into this `COleCurrency` object. -- **operator =(** *varSrc* **)** If the conversion of the `VARIANT` value (or [COleVariant](../../mfc/reference/colevariant-class.md) object) to a currency ( `VT_CY`) is successful, the converted value is copied into this `COleCurrency` object and its status is set to valid. If the conversion is not successful, the value of the `COleCurrency` object is set to 0 and its status to invalid. +- **operator =(** *varSrc* **)** If the conversion of the `VARIANT` value (or [COleVariant](../../mfc/reference/colevariant-class.md) object) to a currency (`VT_CY`) is successful, the converted value is copied into this `COleCurrency` object and its status is set to valid. If the conversion is not successful, the value of the `COleCurrency` object is set to 0 and its status to invalid. For more information, see the [CURRENCY](/windows/win32/api/wtypes/ns-wtypes-cy-r1) and [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) entries in the Windows SDK. @@ -486,7 +485,7 @@ BOOL operator>=(const COleCurrency& cur) const; ### Remarks > [!NOTE] -> The return value of the ordering operations ( **<**, **\<=**, **>**, **>=**) is undefined if the status of either operand is null or invalid. The equality operators ( `==`, `!=`) consider the status of the operands. +> The return value of the ordering operations ( **<**, **\<=**, **>**, **>=**) is undefined if the status of either operand is null or invalid. The equality operators (`==`, `!=`) consider the status of the operands. ### Example diff --git a/docs/mfc/reference/coledataobject-class.md b/docs/mfc/reference/coledataobject-class.md index c56df1d52c..66f054c745 100644 --- a/docs/mfc/reference/coledataobject-class.md +++ b/docs/mfc/reference/coledataobject-class.md @@ -96,7 +96,7 @@ Nonzero if successful; otherwise 0. ### Remarks > [!NOTE] -> Calling this function locks the Clipboard until this data object is released. The data object is released in the destructor for the `COleDataObject`. For more information, see [OpenClipboard](/windows/win32/api/winuser/nf-winuser-openclipboard) and [CloseClipboard](/windows/win32/api/winuser/nf-winuser-closeclipboard) in the Win32 documention. +> Calling this function locks the Clipboard until this data object is released. The data object is released in the destructor for the `COleDataObject`. For more information, see [OpenClipboard](/windows/win32/api/winuser/nf-winuser-openclipboard) and [CloseClipboard](/windows/win32/api/winuser/nf-winuser-closeclipboard) in the Win32 documentation. ## COleDataObject::BeginEnumFormats diff --git a/docs/mfc/reference/coledatasource-class.md b/docs/mfc/reference/coledatasource-class.md index 5cb2cc3bd9..8d0101c035 100644 --- a/docs/mfc/reference/coledatasource-class.md +++ b/docs/mfc/reference/coledatasource-class.md @@ -227,7 +227,7 @@ For more information, see [RegisterClipboardFormat](/windows/win32/api/winuser/n ## COleDataSource::DoDragDrop -Call the `DoDragDrop` member function to perform a drag-and-drop operation for this data source, typically in an [CWnd::OnLButtonDown](../../mfc/reference/cwnd-class.md#onlbuttondown) handler. +Call the `DoDragDrop` member function to perform a drag-and-drop operation for this data source, typically in a [CWnd::OnLButtonDown](../../mfc/reference/cwnd-class.md#onlbuttondown) handler. ``` DROPEFFECT DoDragDrop( diff --git a/docs/mfc/reference/coledocument-class.md b/docs/mfc/reference/coledocument-class.md index c8ad83bdfb..fe1959bf1a 100644 --- a/docs/mfc/reference/coledocument-class.md +++ b/docs/mfc/reference/coledocument-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleDocument Class" title: "COleDocument Class" +description: "Learn more about: COleDocument Class" ms.date: "11/04/2016" f1_keywords: ["COleDocument", "AFXOLE/COleDocument", "AFXOLE/COleDocument::COleDocument", "AFXOLE/COleDocument::AddItem", "AFXOLE/COleDocument::ApplyPrintDevice", "AFXOLE/COleDocument::EnableCompoundFile", "AFXOLE/COleDocument::GetInPlaceActiveItem", "AFXOLE/COleDocument::GetNextClientItem", "AFXOLE/COleDocument::GetNextItem", "AFXOLE/COleDocument::GetNextServerItem", "AFXOLE/COleDocument::GetPrimarySelectedItem", "AFXOLE/COleDocument::GetStartPosition", "AFXOLE/COleDocument::HasBlankItems", "AFXOLE/COleDocument::OnShowViews", "AFXOLE/COleDocument::RemoveItem", "AFXOLE/COleDocument::UpdateModifiedFlag", "AFXOLE/COleDocument::OnEditChangeIcon", "AFXOLE/COleDocument::OnEditConvert", "AFXOLE/COleDocument::OnEditLinks", "AFXOLE/COleDocument::OnFileSendMail", "AFXOLE/COleDocument::OnUpdateEditChangeIcon", "AFXOLE/COleDocument::OnUpdateEditLinksMenu", "AFXOLE/COleDocument::OnUpdateObjectVerbMenu", "AFXOLE/COleDocument::OnUpdatePasteLinkMenu", "AFXOLE/COleDocument::OnUpdatePasteMenu"] helpviewer_keywords: ["COleDocument [MFC], COleDocument", "COleDocument [MFC], AddItem", "COleDocument [MFC], ApplyPrintDevice", "COleDocument [MFC], EnableCompoundFile", "COleDocument [MFC], GetInPlaceActiveItem", "COleDocument [MFC], GetNextClientItem", "COleDocument [MFC], GetNextItem", "COleDocument [MFC], GetNextServerItem", "COleDocument [MFC], GetPrimarySelectedItem", "COleDocument [MFC], GetStartPosition", "COleDocument [MFC], HasBlankItems", "COleDocument [MFC], OnShowViews", "COleDocument [MFC], RemoveItem", "COleDocument [MFC], UpdateModifiedFlag", "COleDocument [MFC], OnEditChangeIcon", "COleDocument [MFC], OnEditConvert", "COleDocument [MFC], OnEditLinks", "COleDocument [MFC], OnFileSendMail", "COleDocument [MFC], OnUpdateEditChangeIcon", "COleDocument [MFC], OnUpdateEditLinksMenu", "COleDocument [MFC], OnUpdateObjectVerbMenu", "COleDocument [MFC], OnUpdatePasteLinkMenu", "COleDocument [MFC], OnUpdatePasteMenu"] -ms.assetid: dc2ecb99-03e1-44c7-bb69-48056dd1b672 --- # COleDocument Class @@ -64,9 +63,9 @@ class COleDocument : public CDocument If you are writing a simple container application, derive your document class from `COleDocument`. If you are writing a container application that supports linking to the embedded items contained by its documents, derive your document class from [COleLinkingDoc](../../mfc/reference/colelinkingdoc-class.md). If you are writing a server application or combination container/server, derive your document class from [COleServerDoc](../../mfc/reference/coleserverdoc-class.md). `COleLinkingDoc` and `COleServerDoc` are derived from `COleDocument`, so these classes inherit all the services available in `COleDocument` and `CDocument`. -To use `COleDocument`, derive a class from it and add functionality to manage the application's non-OLE data as well as embedded or linked items. If you define `CDocItem`-derived classes to store the application's native data, you can use the default implementation defined by `COleDocument` to store both your OLE and non-OLE data. You can also design your own data structures for storing your non-OLE data separately from the OLE items. For more information, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md).. +To use `COleDocument`, derive a class from it and add functionality to manage the application's non-OLE data as well as embedded or linked items. If you define `CDocItem`-derived classes to store the application's native data, you can use the default implementation defined by `COleDocument` to store both your OLE and non-OLE data. You can also design your own data structures for storing your non-OLE data separately from the OLE items. For more information, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md). -`CDocument` supports sending your document via mail if mail support (MAPI) is present. `COleDocument` has updated [OnFileSendMail](#onfilesendmail) to handle compound documents correctly. For more information, see the articles [MAPI](../../mfc/mapi.md) and [MAPI Support in MFC](../../mfc/mapi-support-in-mfc.md).. +`CDocument` supports sending your document via mail if mail support (MAPI) is present. `COleDocument` has updated [OnFileSendMail](#onfilesendmail) to handle compound documents correctly. For more information, see the articles [MAPI](../../mfc/mapi.md) and [MAPI Support in MFC](../../mfc/mapi-support-in-mfc.md). ## Inheritance Hierarchy @@ -153,7 +152,7 @@ Specifies whether compound file support is enabled or disabled. ### Remarks -This is also called structured storage. You typically call this function from the constructor of your `COleDocument`-derived class. For more information about compound documents, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md).. +This is also called structured storage. You typically call this function from the constructor of your `COleDocument`-derived class. For more information about compound documents, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md). If you do not call this member function, documents will be stored in a nonstructured ("flat") file format. @@ -356,7 +355,7 @@ afx_msg void OnFileSendMail(); Unlike the implementation of `OnFileSendMail` for `CDocument`, this function handles compound files correctly. -For more information, see the [MAPI Topics](../../mfc/mapi.md) and [MAPI Support in MFC](../../mfc/mapi-support-in-mfc.md) articles.. +For more information, see the [MAPI Topics](../../mfc/mapi.md) and [MAPI Support in MFC](../../mfc/mapi-support-in-mfc.md) articles. ## COleDocument::OnShowViews @@ -491,7 +490,7 @@ This allows the framework to prompt the user to save the document before closing ## See also -[MFC Sample CONTAINER](../../overview/visual-cpp-samples.md)
-[MFC Sample MFCBIND](../../overview/visual-cpp-samples.md)
-[CDocument Class](../../mfc/reference/cdocument-class.md)
+[MFC Sample CONTAINER](../../overview/visual-cpp-samples.md)\ +[MFC Sample MFCBIND](../../overview/visual-cpp-samples.md)\ +[CDocument Class](../../mfc/reference/cdocument-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/coledroptarget-class.md b/docs/mfc/reference/coledroptarget-class.md index 7a77978f8b..302ff8d19d 100644 --- a/docs/mfc/reference/coledroptarget-class.md +++ b/docs/mfc/reference/coledroptarget-class.md @@ -293,7 +293,7 @@ Points to the data object that contains the data to be dropped. The effect that the user chose for the default drop operation based on the current key state. It can be DROPEFFECT_NONE. Drop effects are discussed in the Remarks section. *dropList*
-A list of the drop effects that the drop source supports. Drop effect values can be combined using the bitwise OR (**|**) operation. Drop effects are discussed in the Remarks section. +A list of the drop effects that the drop source supports. Drop effect values can be combined using the bitwise OR (**`|`**) operation. Drop effects are discussed in the Remarks section. *point*
Contains the location of the cursor, in pixels, relative to the screen. diff --git a/docs/mfc/reference/coleipframewndex-class.md b/docs/mfc/reference/coleipframewndex-class.md index 69d2da9c47..51faf2f152 100644 --- a/docs/mfc/reference/coleipframewndex-class.md +++ b/docs/mfc/reference/coleipframewndex-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: COleIPFrameWndEx Class" title: "COleIPFrameWndEx Class" -ms.date: "11/04/2016" +description: "Learn more about: COleIPFrameWndEx Class" +ms.date: 11/04/2016 f1_keywords: ["COleIPFrameWndEx", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::AddDockSite", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::AddPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::AdjustDockingLayout", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::DockPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::DockPaneLeftOf", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::EnableAutoHidePanes", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::EnableDocking", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::EnablePaneMenu", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetActivePopup", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetContainerFrameWindow", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetDefaultResId", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetDockFrame", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetDockingManager", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetMainFrame", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetMenuBar", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetTearOffBars", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::GetToolbarButtonToolTipText", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::InsertPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::IsMenuBarAvailable", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::IsPointNearDockSite", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::LoadFrame", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnCloseDockingPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnCloseMiniFrame", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnClosePopupMenu", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnCmdMsg", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnDrawMenuImage", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnDrawMenuLogo", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnMenuButtonToolHitTest", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnMoveMiniFrame", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnSetPreviewMode", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnShowCustomizePane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnShowPanes", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnShowPopupMenu", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::OnTearOffMenu", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::PaneFromPoint", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::PreTranslateMessage", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::RecalcLayout", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::RemovePaneFromDockManager", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::SetDockState", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::SetupToolbarMenu", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::ShowPane", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::WinHelpA", "AFXOLEIPFRAMEWNDEX/COleIPFrameWndEx::InitUserToobars"] helpviewer_keywords: ["COleIPFrameWndEx [MFC], AddDockSite", "COleIPFrameWndEx [MFC], AddPane", "COleIPFrameWndEx [MFC], AdjustDockingLayout", "COleIPFrameWndEx [MFC], DockPane", "COleIPFrameWndEx [MFC], DockPaneLeftOf", "COleIPFrameWndEx [MFC], EnableAutoHidePanes", "COleIPFrameWndEx [MFC], EnableDocking", "COleIPFrameWndEx [MFC], EnablePaneMenu", "COleIPFrameWndEx [MFC], GetActivePopup", "COleIPFrameWndEx [MFC], GetContainerFrameWindow", "COleIPFrameWndEx [MFC], GetDefaultResId", "COleIPFrameWndEx [MFC], GetDockFrame", "COleIPFrameWndEx [MFC], GetDockingManager", "COleIPFrameWndEx [MFC], GetMainFrame", "COleIPFrameWndEx [MFC], GetMenuBar", "COleIPFrameWndEx [MFC], GetPane", "COleIPFrameWndEx [MFC], GetTearOffBars", "COleIPFrameWndEx [MFC], GetToolbarButtonToolTipText", "COleIPFrameWndEx [MFC], InsertPane", "COleIPFrameWndEx [MFC], IsMenuBarAvailable", "COleIPFrameWndEx [MFC], IsPointNearDockSite", "COleIPFrameWndEx [MFC], LoadFrame", "COleIPFrameWndEx [MFC], OnCloseDockingPane", "COleIPFrameWndEx [MFC], OnCloseMiniFrame", "COleIPFrameWndEx [MFC], OnClosePopupMenu", "COleIPFrameWndEx [MFC], OnCmdMsg", "COleIPFrameWndEx [MFC], OnDrawMenuImage", "COleIPFrameWndEx [MFC], OnDrawMenuLogo", "COleIPFrameWndEx [MFC], OnMenuButtonToolHitTest", "COleIPFrameWndEx [MFC], OnMoveMiniFrame", "COleIPFrameWndEx [MFC], OnSetPreviewMode", "COleIPFrameWndEx [MFC], OnShowCustomizePane", "COleIPFrameWndEx [MFC], OnShowPanes", "COleIPFrameWndEx [MFC], OnShowPopupMenu", "COleIPFrameWndEx [MFC], OnTearOffMenu", "COleIPFrameWndEx [MFC], PaneFromPoint", "COleIPFrameWndEx [MFC], PreTranslateMessage", "COleIPFrameWndEx [MFC], RecalcLayout", "COleIPFrameWndEx [MFC], RemovePaneFromDockManager", "COleIPFrameWndEx [MFC], SetDockState", "COleIPFrameWndEx [MFC], SetupToolbarMenu", "COleIPFrameWndEx [MFC], ShowPane", "COleIPFrameWndEx [MFC], WinHelpA", "COleIPFrameWndEx [MFC], InitUserToobars"] -ms.assetid: ebff1560-a1eb-4854-af00-95d4a192bd55 --- # COleIPFrameWndEx Class -The `COleIPFrameWndEx` class implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [COleIPFrameWnd](../../mfc/reference/coleipframewnd-class.md)class. +The `COleIPFrameWndEx` class implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [COleIPFrameWnd](../../mfc/reference/coleipframewnd-class.md) class. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. ## Syntax @@ -50,8 +49,8 @@ class COleIPFrameWndEx : public COleIPFrameWnd |[COleIPFrameWndEx::OnClosePopupMenu](#onclosepopupmenu)|Called by the framework when an active pop-up menu processes a WM_DESTROY message.| |[COleIPFrameWndEx::OnCmdMsg](#oncmdmsg)|(Overrides `CFrameWnd::OnCmdMsg`.)| |[COleIPFrameWndEx::OnDrawMenuImage](#ondrawmenuimage)|Called by the framework when the image associated with a menu item is drawn.| -|[COleIPFrameWndEx::OnDrawMenuLogo](#ondrawmenulogo)|Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md)object processes a WM_PAINT message.| -|[COleIPFrameWndEx::OnMenuButtonToolHitTest](#onmenubuttontoolhittest)|Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md)object processes WM_NCHITTEST message.| +|[COleIPFrameWndEx::OnDrawMenuLogo](#ondrawmenulogo)|Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md) object processes a WM_PAINT message.| +|[COleIPFrameWndEx::OnMenuButtonToolHitTest](#onmenubuttontoolhittest)|Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md) object processes WM_NCHITTEST message.| |[COleIPFrameWndEx::OnMoveMiniFrame](#onmoveminiframe)|| |[COleIPFrameWndEx::OnSetPreviewMode](#onsetpreviewmode)|Call this member function to set the application's main frame window into and out of print-preview mode. (Overrides [CFrameWnd::OnSetPreviewMode](../../mfc/reference/cframewnd-class.md#onsetpreviewmode).)| |[COleIPFrameWndEx::OnShowCustomizePane](#onshowcustomizepane)|| @@ -571,7 +570,7 @@ Override this method if you want to customize image drawing for the menu items t ## COleIPFrameWndEx::OnDrawMenuLogo -Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md)object processes a WM_PAINT message. +Called by the framework when a [CMFCPopupMenu](../../mfc/reference/cmfcpopupmenu-class.md) object processes a WM_PAINT message. ``` virtual void OnDrawMenuLogo( @@ -597,7 +596,7 @@ Override this method to display a logo on the pop-up menu associated with the me ## COleIPFrameWndEx::OnMenuButtonToolHitTest -Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md)object processes a WM_NCHITTEST message. +Called by the framework when a [CMFCToolBarButton](../../mfc/reference/cmfctoolbarbutton-class.md) object processes a WM_NCHITTEST message. ``` virtual BOOL OnMenuButtonToolHitTest( diff --git a/docs/mfc/reference/colelinkingdoc-class.md b/docs/mfc/reference/colelinkingdoc-class.md index a0e41b5128..a0e9bc5858 100644 --- a/docs/mfc/reference/colelinkingdoc-class.md +++ b/docs/mfc/reference/colelinkingdoc-class.md @@ -130,7 +130,7 @@ A pointer to the specified item; NULL if the item is not found. ### Remarks -The default `COleLinkingDoc` implementation always returns NULL. This function is overriden in the derived class `COleServerDoc` to search the list of OLE server items for a linked item with the specified name (the name comparison is case sensitive). Override this function if you have implemented your own method of storing or retrieving linked server items. +The default `COleLinkingDoc` implementation always returns NULL. This function is overridden in the derived class `COleServerDoc` to search the list of OLE server items for a linked item with the specified name (the name comparison is case sensitive). Override this function if you have implemented your own method of storing or retrieving linked server items. ## COleLinkingDoc::Register diff --git a/docs/mfc/reference/coleobjectfactory-class.md b/docs/mfc/reference/coleobjectfactory-class.md index 72f3cce4fc..e1b3a5411d 100644 --- a/docs/mfc/reference/coleobjectfactory-class.md +++ b/docs/mfc/reference/coleobjectfactory-class.md @@ -178,7 +178,7 @@ BOOL IsLicenseValid(); ### Return Value -TRUE if successul; otherwise false. +TRUE if successful; otherwise false. ## COleObjectFactory::IsRegistered diff --git a/docs/mfc/reference/colepastespecialdialog-class.md b/docs/mfc/reference/colepastespecialdialog-class.md index ba39324f30..cfc6e49021 100644 --- a/docs/mfc/reference/colepastespecialdialog-class.md +++ b/docs/mfc/reference/colepastespecialdialog-class.md @@ -328,7 +328,7 @@ enum Selection { }; ``` -Brief desccriptions of these values follow: +Brief descriptions of these values follow: - `COlePasteSpecialDialog::pasteLink` The Paste Link radio button was checked and the chosen format was a standard OLE format. diff --git a/docs/mfc/reference/coleserverdoc-class.md b/docs/mfc/reference/coleserverdoc-class.md index 59f7a9c34b..b81a4ff6fd 100644 --- a/docs/mfc/reference/coleserverdoc-class.md +++ b/docs/mfc/reference/coleserverdoc-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleServerDoc Class" title: "COleServerDoc Class" +description: "Learn more about: COleServerDoc Class" ms.date: "11/04/2016" f1_keywords: ["COleServerDoc", "AFXOLE/COleServerDoc", "AFXOLE/COleServerDoc::COleServerDoc", "AFXOLE/COleServerDoc::ActivateDocObject", "AFXOLE/COleServerDoc::ActivateInPlace", "AFXOLE/COleServerDoc::DeactivateAndUndo", "AFXOLE/COleServerDoc::DiscardUndoState", "AFXOLE/COleServerDoc::GetClientSite", "AFXOLE/COleServerDoc::GetEmbeddedItem", "AFXOLE/COleServerDoc::GetItemClipRect", "AFXOLE/COleServerDoc::GetItemPosition", "AFXOLE/COleServerDoc::GetZoomFactor", "AFXOLE/COleServerDoc::IsDocObject", "AFXOLE/COleServerDoc::IsEmbedded", "AFXOLE/COleServerDoc::IsInPlaceActive", "AFXOLE/COleServerDoc::NotifyChanged", "AFXOLE/COleServerDoc::NotifyClosed", "AFXOLE/COleServerDoc::NotifyRename", "AFXOLE/COleServerDoc::NotifySaved", "AFXOLE/COleServerDoc::OnDeactivate", "AFXOLE/COleServerDoc::OnDeactivateUI", "AFXOLE/COleServerDoc::OnDocWindowActivate", "AFXOLE/COleServerDoc::OnResizeBorder", "AFXOLE/COleServerDoc::OnShowControlBars", "AFXOLE/COleServerDoc::OnUpdateDocument", "AFXOLE/COleServerDoc::RequestPositionChange", "AFXOLE/COleServerDoc::SaveEmbedding", "AFXOLE/COleServerDoc::ScrollContainerBy", "AFXOLE/COleServerDoc::UpdateAllItems", "AFXOLE/COleServerDoc::CreateInPlaceFrame", "AFXOLE/COleServerDoc::DestroyInPlaceFrame", "AFXOLE/COleServerDoc::GetDocObjectServer", "AFXOLE/COleServerDoc::OnClose", "AFXOLE/COleServerDoc::OnExecOleCmd", "AFXOLE/COleServerDoc::OnFrameWindowActivate", "AFXOLE/COleServerDoc::OnGetEmbeddedItem", "AFXOLE/COleServerDoc::OnReactivateAndUndo", "AFXOLE/COleServerDoc::OnSetHostNames", "AFXOLE/COleServerDoc::OnSetItemRects", "AFXOLE/COleServerDoc::OnShowDocument"] helpviewer_keywords: ["COleServerDoc [MFC], COleServerDoc", "COleServerDoc [MFC], ActivateDocObject", "COleServerDoc [MFC], ActivateInPlace", "COleServerDoc [MFC], DeactivateAndUndo", "COleServerDoc [MFC], DiscardUndoState", "COleServerDoc [MFC], GetClientSite", "COleServerDoc [MFC], GetEmbeddedItem", "COleServerDoc [MFC], GetItemClipRect", "COleServerDoc [MFC], GetItemPosition", "COleServerDoc [MFC], GetZoomFactor", "COleServerDoc [MFC], IsDocObject", "COleServerDoc [MFC], IsEmbedded", "COleServerDoc [MFC], IsInPlaceActive", "COleServerDoc [MFC], NotifyChanged", "COleServerDoc [MFC], NotifyClosed", "COleServerDoc [MFC], NotifyRename", "COleServerDoc [MFC], NotifySaved", "COleServerDoc [MFC], OnDeactivate", "COleServerDoc [MFC], OnDeactivateUI", "COleServerDoc [MFC], OnDocWindowActivate", "COleServerDoc [MFC], OnResizeBorder", "COleServerDoc [MFC], OnShowControlBars", "COleServerDoc [MFC], OnUpdateDocument", "COleServerDoc [MFC], RequestPositionChange", "COleServerDoc [MFC], SaveEmbedding", "COleServerDoc [MFC], ScrollContainerBy", "COleServerDoc [MFC], UpdateAllItems", "COleServerDoc [MFC], CreateInPlaceFrame", "COleServerDoc [MFC], DestroyInPlaceFrame", "COleServerDoc [MFC], GetDocObjectServer", "COleServerDoc [MFC], OnClose", "COleServerDoc [MFC], OnExecOleCmd", "COleServerDoc [MFC], OnFrameWindowActivate", "COleServerDoc [MFC], OnGetEmbeddedItem", "COleServerDoc [MFC], OnReactivateAndUndo", "COleServerDoc [MFC], OnSetHostNames", "COleServerDoc [MFC], OnSetItemRects", "COleServerDoc [MFC], OnShowDocument"] -ms.assetid: a9cdd96a-e0ac-43bb-9203-2c29237e965c --- # COleServerDoc Class @@ -477,7 +476,7 @@ This function restores the container application's user interface to its origina The undo state information should be unconditionally released at this point. -For more information, see the article [Activation](../../mfc/activation-cpp.md).. +For more information, see the article [Activation](../../mfc/activation-cpp.md). ## COleServerDoc::OnDeactivateUI @@ -515,7 +514,7 @@ Specifies whether the document window is to be activated or deactivated. The default implementation removes or adds the frame-level user interface elements as appropriate. Override this function if you want to perform additional actions when the document containing your item is activated or deactivated. -For more information, see the article [Activation](../../mfc/activation-cpp.md).. +For more information, see the article [Activation](../../mfc/activation-cpp.md). ## COleServerDoc::OnExecOleCmd @@ -599,7 +598,7 @@ Specifies whether the frame window is to be activated or deactivated. The default implementation cancels any help modes the frame window might be in. Override this function if you want to perform special processing when the frame window is activated or deactivated. -For more information, see the article [Activation](../../mfc/activation-cpp.md).. +For more information, see the article [Activation](../../mfc/activation-cpp.md). ## COleServerDoc::OnGetEmbeddedItem @@ -860,9 +859,9 @@ This function calls the `OnUpdate` member function for each of the document's it ## See also -[MFC Sample HIERSVR](../../overview/visual-cpp-samples.md)
-[COleLinkingDoc Class](../../mfc/reference/colelinkingdoc-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[COleDocument Class](../../mfc/reference/coledocument-class.md)
-[COleLinkingDoc Class](../../mfc/reference/colelinkingdoc-class.md)
+[MFC Sample HIERSVR](../../overview/visual-cpp-samples.md)\ +[COleLinkingDoc Class](../../mfc/reference/colelinkingdoc-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[COleDocument Class](../../mfc/reference/coledocument-class.md)\ +[COleLinkingDoc Class](../../mfc/reference/colelinkingdoc-class.md)\ [COleTemplateServer Class](../../mfc/reference/coletemplateserver-class.md) diff --git a/docs/mfc/reference/colestreamfile-class.md b/docs/mfc/reference/colestreamfile-class.md index 053820436c..964fe4e4dd 100644 --- a/docs/mfc/reference/colestreamfile-class.md +++ b/docs/mfc/reference/colestreamfile-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleStreamFile Class" title: "COleStreamFile Class" +description: "Learn more about: COleStreamFile Class" ms.date: "11/04/2016" f1_keywords: ["COleStreamFile", "AFXOLE/COleStreamFile", "AFXOLE/COleStreamFile::COleStreamFile", "AFXOLE/COleStreamFile::Attach", "AFXOLE/COleStreamFile::CreateMemoryStream", "AFXOLE/COleStreamFile::CreateStream", "AFXOLE/COleStreamFile::Detach", "AFXOLE/COleStreamFile::GetStream", "AFXOLE/COleStreamFile::OpenStream"] helpviewer_keywords: ["COleStreamFile [MFC], COleStreamFile", "COleStreamFile [MFC], Attach", "COleStreamFile [MFC], CreateMemoryStream", "COleStreamFile [MFC], CreateStream", "COleStreamFile [MFC], Detach", "COleStreamFile [MFC], GetStream", "COleStreamFile [MFC], OpenStream"] -ms.assetid: e4f93698-e17c-4a18-a7c0-4b4df8eb4d93 --- # COleStreamFile Class @@ -41,7 +40,7 @@ An `IStorage` object must exist before the stream can be opened or created unles `COleStreamFile` objects are manipulated exactly like [CFile](../../mfc/reference/cfile-class.md) objects. -For more information about manipulating streams and storages, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md).. +For more information about manipulating streams and storages, see the article [Containers: Compound Files](../../mfc/containers-compound-files.md). For more information, see [IStream](/windows/win32/api/objidl/nn-objidl-istream) and [IStorage](/windows/win32/api/objidl/nn-objidl-istorage) in the Windows SDK. @@ -222,5 +221,5 @@ For more information, see [IStorage::OpenStream](/windows/win32/api/objidl/nf-ob ## See also -[CFile Class](../../mfc/reference/cfile-class.md)
+[CFile Class](../../mfc/reference/cfile-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/colevariant-class.md b/docs/mfc/reference/colevariant-class.md index 7879d57253..f3bc198514 100644 --- a/docs/mfc/reference/colevariant-class.md +++ b/docs/mfc/reference/colevariant-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: COleVariant Class" title: "COleVariant Class" -ms.date: "11/04/2016" +description: "Learn more about: COleVariant Class" +ms.date: 11/04/2016 f1_keywords: ["COleVariant", "AFXDISP/COleVariant", "AFXDISP/COleVariant::COleVariant", "AFXDISP/COleVariant::Attach", "AFXDISP/COleVariant::ChangeType", "AFXDISP/COleVariant::Clear", "AFXDISP/COleVariant::Detach", "AFXDISP/COleVariant::GetByteArrayFromVariantArray", "AFXDISP/COleVariant::SetString"] helpviewer_keywords: ["COleVariant [MFC], COleVariant", "COleVariant [MFC], Attach", "COleVariant [MFC], ChangeType", "COleVariant [MFC], Clear", "COleVariant [MFC], Detach", "COleVariant [MFC], GetByteArrayFromVariantArray", "COleVariant [MFC], SetString"] -ms.assetid: e1b5cd4a-b066-4b9b-b48b-6215ed52d998 --- # COleVariant Class @@ -52,7 +51,7 @@ This data type is used in OLE automation. Specifically, the [DISPPARAMS](/window > [!NOTE] > This class is derived from the `VARIANT` structure. This means you can pass a `COleVariant` in a parameter that calls for a `VARIANT` and that the data members of the `VARIANT` structure are accessible data members of `COleVariant`. -The two related MFC classes [COleCurrency](../../mfc/reference/colecurrency-class.md) and [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) encapsulate the variant data types CURRENCY ( `VT_CY`) and DATE ( `VT_DATE`). The `COleVariant` class is used extensively in the DAO classes; see these classes for typical usage of this class, for example [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) and [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md). +The two related MFC classes [COleCurrency](../../mfc/reference/colecurrency-class.md) and [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) encapsulate the variant data types CURRENCY (`VT_CY`) and DATE (`VT_DATE`). The `COleVariant` class is used extensively in the DAO classes; see these classes for typical usage of this class, for example [CDaoQueryDef](../../mfc/reference/cdaoquerydef-class.md) and [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md). For more information, see the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant), [CURRENCY](/windows/win32/api/wtypes/ns-wtypes-cy-r1), [DISPPARAMS](/windows/win32/api/oaidl/ns-oaidl-dispparams), and [IDispatch::Invoke](/windows/win32/api/oaidl/nf-oaidl-idispatch-invoke) entries in the Windows SDK. @@ -150,7 +149,7 @@ A [CByteArray](../../mfc/reference/cbytearray-class.md) object to be copied into A [CLongBinary](../../mfc/reference/clongbinary-class.md) object to be copied into the new `COleVariant` object. *pidl*
-A pointer to a [ITEMIDLIST](/windows/win32/api/shtypes/ns-shtypes-itemidlist) structure to be copied into the new `COleVariant` object. +A pointer to an [ITEMIDLIST](/windows/win32/api/shtypes/ns-shtypes-itemidlist) structure to be copied into the new `COleVariant` object. ### Remarks diff --git a/docs/mfc/reference/collection-class-helpers.md b/docs/mfc/reference/collection-class-helpers.md index 4db4679689..ca02e0d281 100644 --- a/docs/mfc/reference/collection-class-helpers.md +++ b/docs/mfc/reference/collection-class-helpers.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Collection Class Helpers" title: "Collection Class Helpers" -ms.date: "11/04/2016" +description: "Learn more about: Collection Class Helpers" +ms.date: 11/04/2016 helpviewer_keywords: ["DestructElements function", "ConstructElements function", "SerializeElements function", "collection classes [MFC], helper functions", "helper functions collection class [MFC]"] -ms.assetid: bc3a2368-9edd-4748-9e6a-13cba79517ca --- # Collection Class Helpers @@ -57,7 +56,7 @@ The `CMap` calls use the `CMap` template parameters *KEY* and *ARG_KEY*. The default implementation returns the result of the comparison of *\*pElement1* and *\*pElement2*. Override this function so that it compares the elements in a way that is appropriate for your application. -The C++ language defines the comparison operator ( `==`) for simple types (**`char`**, **`int`**, **`float`**, and so on) but does not define a comparison operator for classes and structures. If you want to use `CompareElements` or to instantiate one of the collection classes that uses it, you must either define the comparison operator or overload `CompareElements` with a version that returns appropriate values. +The C++ language defines the comparison operator (`==`) for simple types (**`char`**, **`int`**, **`float`**, and so on) but does not define a comparison operator for classes and structures. If you want to use `CompareElements` or to instantiate one of the collection classes that uses it, you must either define the comparison operator or overload `CompareElements` with a version that returns appropriate values. ### Requirements diff --git a/docs/mfc/reference/connection-maps.md b/docs/mfc/reference/connection-maps.md index dda5d5f1d1..021a53eead 100644 --- a/docs/mfc/reference/connection-maps.md +++ b/docs/mfc/reference/connection-maps.md @@ -1,174 +1,174 @@ --- -description: "Learn more about: Connection Maps" title: "Connection Maps" -ms.date: "11/04/2016" +description: "Learn more about: Connection Maps" +ms.date: 8/1/2023 helpviewer_keywords: ["connection maps"] -ms.assetid: 1f25a9bc-6d09-4614-99cf-dc38e8ddfa73 --- -# Connection Maps + +# Connection maps OLE controls are able to expose interfaces to other applications. These interfaces only allow access from a container into that control. If an OLE control wants to access external interfaces of other OLE objects, a connection point must be established. This connection point allows a control outgoing access to external dispatch maps, such as event maps or notification functions. -The Microsoft Foundation Class Library offers a programming model that supports connection points. In this model, "connection maps" are used to designate interfaces or connection points for the OLE control. Connection maps contain one macro for each connection point. For more information on connection maps, see the [CConnectionPoint](../../mfc/reference/cconnectionpoint-class.md) class. +The Microsoft Foundation Class Library offers a programming model that supports connection points. In this model, "connection maps" are used to designate interfaces or connection points for the OLE control. Connection maps contain one macro for each connection point. For more information on connection maps, see the [`CConnectionPoint`](../../mfc/reference/cconnectionpoint-class.md) class. -Typically, a control will support just two connection points: one for events and one for property notifications. These are implemented by the `COleControl` base class and require no additional work by the control writer. Any additional connection points you want to implement in your class must be added manually. To support connection maps and points, MFC provides the following macros: +Typically, a control supports just two connection points: one for events and one for property notifications. These are implemented by the `COleControl` base class and require no extra work by the control writer. Any other connection points you want to implement in your class must be added manually. To support connection maps and points, MFC provides the following macros: -### Connection Map Declaration and Demarcation +### Connection Map declaration and demarcation |Name|Description| |-|-| -|[BEGIN_CONNECTION_PART](#begin_connection_part)|Declares an embedded class that implements an additional connection point (must be used in the class declaration).| -|[END_CONNECTION_PART](#end_connection_part)|Ends the declaration of a connection point (must be used in the class declaration).| -|[CONNECTION_IID](#connection_iid)|Specifies the interface ID of the control's connection point.| -|[DECLARE_CONNECTION_MAP](#declare_connection_map)|Declares that a connection map will be used in a class (must be used in the class declaration).| -|[BEGIN_CONNECTION_MAP](#begin_connection_map)|Begins the definition of a connection map (must be used in the class implementation).| -|[END_CONNECTION_MAP](#end_connection_map)|Ends the definition of a connection map (must be used in the class implementation).| -|[CONNECTION_PART](#connection_part)|Specifies a connection point in the control's connection map.| +|[`BEGIN_CONNECTION_PART`](#BEGIN_CONNECTION_PART)|Declares an embedded class that implements an additional connection point (must be used in the class declaration).| +|[`END_CONNECTION_PART`](#END_CONNECTION_PART)|Ends the declaration of a connection point (must be used in the class declaration).| +|[`CONNECTION_IID`](#CONNECTION_IID)|Specifies the interface ID of the control's connection point.| +|[`DECLARE_CONNECTION_MAP`](#DECLARE_CONNECTION_MAP)|Declares that a connection map will be used in a class (must be used in the class declaration).| +|[`BEGIN_CONNECTION_MAP`](#BEGIN_CONNECTION_MAP)|Begins the definition of a connection map (must be used in the class implementation).| +|[`END_CONNECTION_MAP`](#END_CONNECTION_MAP)|Ends the definition of a connection map (must be used in the class implementation).| +|[`CONNECTION_PART`](#CONNECTION_PART)|Specifies a connection point in the control's connection map.| The following functions assist a sink in establishing and disconnecting a connection using connection points: -### Initialization/Termination of Connection Points +### Initialization/termination of connection points |Name|Description| |-|-| -|[AfxConnectionAdvise](#afxconnectionadvise)|Establishes a connection between a source and a sink.| -|[AfxConnectionUnadvise](#afxconnectionunadvise)|Breaks a connection between a source and a sink.| +|[`AfxConnectionAdvise`](#AfxConnectionAdvise)|Establishes a connection between a source and a sink.| +|[`AfxConnectionUnadvise`](#AfxConnectionUnadvise)|Breaks a connection between a source and a sink.| -## BEGIN_CONNECTION_PART +## `BEGIN_CONNECTION_PART` -Use the BEGIN_CONNECTION_PART macro to begin the definition of additional connection points beyond the event and property notification connection points. +Use the `BEGIN_CONNECTION_PART` macro to begin the definition of additional connection points beyond the event and property notification connection points. -``` +```cpp BEGIN_CONNECTION_PART(theClass, localClass) ``` ### Parameters -*theClass*
+*`theClass`* Specifies the name of the control class whose connection point this is. -*localClass*
+*`localClass`* Specifies the name of the local class that implements the connection point. ### Remarks -In the declaration (.h) file that defines the member functions for your class, start the connection point with the BEGIN_CONNECTION_PART macro, then add the CONNECTION_IID macro and any other member functions you wish to implement, and complete the connection point map with the END_CONNECTION_PART macro. +In the declaration (`.h`) file that defines the member functions for your class, start the connection point with the `BEGIN_CONNECTION_PART` macro. Then add the `CONNECTION_IID` macro and any other member functions you wish to implement. Finally, complete the connection point map with the `END_CONNECTION_PART` macro. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## END_CONNECTION_PART +## `END_CONNECTION_PART` Ends the declaration of your connection point. -``` +```cpp END_CONNECTION_PART(localClass) ``` ### Parameters -*localClass*
+*`localClass`*\ Specifies the name of the local class that implements the connection point. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## CONNECTION_IID +## `CONNECTION_IID` -Use between the BEGIN_CONNECTION_PART and END_CONNECTION_PART macros to define an interface ID for a connection point supported by your OLE control. +Use between the `BEGIN_CONNECTION_PART` and `END_CONNECTION_PART` macros to define an interface ID for a connection point supported by your OLE control. -``` +```cpp CONNECTION_IID(iid) ``` ### Parameters -*iid*
+*`iid`*\ The interface ID of the interface called by the connection point. ### Remarks -The *iid* argument is an interface ID used to identify the interface that the connection point will call on its connected sinks. For example: +The *`iid`* argument is an interface ID used to identify the interface that the connection point calls on its connected sinks. For example: [!code-cpp[NVC_MFCConnectionPoints#10](../../mfc/codesnippet/cpp/connection-maps_1.h)] -specifies a connection point that calls the `ISinkInterface` interface. +Specifies a connection point that calls the `ISinkInterface` interface. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## DECLARE_CONNECTION_MAP +## `DECLARE_CONNECTION_MAP` Each `COleControl`-derived class in your program can provide a connection map to specify additional connection points that your control supports. -``` +```cpp DECLARE_CONNECTION_MAP() ``` ### Remarks -If your control supports additional points, use the DECLARE_CONNECTION_MAP macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_CONNECTION_MAP macro, CONNECTION_PART macros for each of the control's connection points, and the END_CONNECTION_MAP macro to declare the end of the connection map. +If your control supports additional points, use the `DECLARE_CONNECTION_MAP` macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the `BEGIN_CONNECTION_MAP` macro, `CONNECTION_PART` macros for each of the control's connection points, and the `END_CONNECTION_MAP` macro to declare the end of the connection map. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## BEGIN_CONNECTION_MAP +## `BEGIN_CONNECTION_MAP` Each `COleControl`-derived class in your program can provide a connection map to specify connection points that your control will support. -``` +```cpp BEGIN_CONNECTION_MAP(theClass, theBase) ``` ### Parameters -*theClass*
+*`theClass`*\ Specifies the name of the control class whose connection map this is. -*theBase*
-Specifies the name of the base class of *theClass*. +*`theBase`*\ +Specifies the name of the base class of *`theClass`*. ### Remarks -In the implementation (.CPP) file that defines the member functions for your class, start the connection map with the BEGIN_CONNECTION_MAP macro, then add macro entries for each of your connection points using the [CONNECTION_PART](#connection_part) macro. Finally, complete the connection map with the [END_CONNECTION_MAP](#end_connection_map) macro. +In the implementation (`.CPP`) file that defines the member functions for your class, start the connection map with the `BEGIN_CONNECTION_MAP` macro, then add macro entries for each of your connection points using the [`CONNECTION_PART`](#CONNECTION_PART) macro. Finally, complete the connection map with the [`END_CONNECTION_MAP`](#END_CONNECTION_MAP) macro. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## END_CONNECTION_MAP +## `END_CONNECTION_MAP` Ends the definition of your connection map. -``` +```cpp END_CONNECTION_MAP() ``` ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## CONNECTION_PART +## `CONNECTION_PART` Maps a connection point for your OLE control to a specific interface ID. -``` +```cpp CONNECTION_PART(theClass, iid, localClass) ``` ### Parameters -*theClass*
+*`theClass`*\ Specifies the name of the control class whose connection point this is. -*iid*
+*`iid`*\ The interface ID of the interface called by the connection point. -*localClass*
+*`localClass`*\ Specifies the name of the local class that implements the connection point. ### Remarks @@ -177,17 +177,17 @@ For example: [!code-cpp[NVC_MFCConnectionPoints#2](../../mfc/codesnippet/cpp/connection-maps_2.cpp)] -implements a connection map, with a connection point, that calls the `IID_ISinkInterface` interface . +implements a connection map, with a connection point, that calls the `IID_ISinkInterface` interface. ### Requirements - **Header** afxdisp.h +**Header** `afxdisp.h` -## AfxConnectionAdvise +## `AfxConnectionAdvise` -Call this function to establish a connection between a source, specified by *pUnkSrc*, and a sink, specified by *pUnkSink*. +Call this function to establish a connection between a source, specified by *`pUnkSrc`*, and a sink, specified by *`pUnkSink`*. -``` +```cpp BOOL AFXAPI AfxConnectionAdvise( LPUNKNOWN pUnkSrc, REFIID iid, @@ -198,20 +198,24 @@ BOOL AFXAPI AfxConnectionAdvise( ### Parameters -*pUnkSrc*
+*`pUnkSrc`*\ A pointer to the object that calls the interface. -*pUnkSink*
+*`pUnkSink`*\ A pointer to the object that implements the interface. -*iid*
+*`iid`*\ The interface ID of the connection. -*bRefCount*
-TRUE indicates that creating the connection should cause the reference count of *pUnkSink* to be incremented. FALSE indicates that the reference count should not be incremented. +*`bRefCount`*\ +For out-of-process connections, this parameter must be `TRUE`, and indicates that creating the connection should cause the reference count of *`pUnkSink`* to be incremented. + +For in-process connections, `TRUE` indicates that creating the connection should cause the reference count of *`pUnkSink`* to be incremented. `FALSE` indicates that the reference count shouldn't be incremented. + +**Warning**: In general, it can't be predicted which connections are in-process and which connections are out-of-process, so it is recommended to always set this parameter to `TRUE`. -*pdwCookie*
-A pointer to a DWORD where a connection identifier is returned. This value should be passed as the *dwCookie* parameter to `AfxConnectionUnadvise` when disconnecting the connection. +*`pdwCookie`*\ +A pointer to a `DWORD` where a connection identifier is returned. This value should be passed as the *`dwCookie`* parameter to `AfxConnectionUnadvise` when disconnecting the connection. ### Return Value @@ -223,13 +227,13 @@ Nonzero if a connection was established; otherwise 0. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## AfxConnectionUnadvise +## `AfxConnectionUnadvise` -Call this function to disconnect a connection between a source, specified by *pUnkSrc*, and a sink, specified by *pUnkSink*. +Call this function to disconnect a connection between a source, specified by *`pUnkSrc`*, and a sink, specified by *`pUnkSink`*. -``` +```cpp BOOL AFXAPI AfxConnectionUnadvise( LPUNKNOWN pUnkSrc, REFIID iid, @@ -240,22 +244,26 @@ BOOL AFXAPI AfxConnectionUnadvise( ### Parameters -*pUnkSrc*
+*`pUnkSrc`*\ A pointer to the object that calls the interface. -*pUnkSink*
+*`pUnkSink`*\ A pointer to the object that implements the interface. -*iid*
+*`iid`*\ The interface ID of the connection point interface. -*bRefCount*
-TRUE indicates that disconnecting the connection should cause the reference count of *pUnkSink* to be decremented. FALSE indicates that the reference count should not be decremented. +*`bRefCount`*\ +For out-of-process connections, this parameter must be `TRUE`, and indicates that creating the connection should cause the reference count of *`pUnkSink`* to be decremented. + +For in-process connections, `TRUE` indicates that creating the connection should cause the reference count of *`pUnkSink`* to be decremented. `FALSE` indicates that the reference count shouldn't be decremented. -*dwCookie*
+**Warning**: In general, it can't be predicted which connections are in-process and which connections are out-of-process, so it is recommended to always set this parameter to `TRUE`. + +*`dwCookie`*\ The connection identifier returned by `AfxConnectionAdvise`. -### Return Value +### Return value Nonzero if a connection was disconnected; otherwise 0. @@ -265,8 +273,8 @@ Nonzero if a connection was disconnected; otherwise 0. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` ## See also -[Macros and Globals](../../mfc/reference/mfc-macros-and-globals.md) +[Macros and Globals](../../mfc/reference/mfc-macros-and-globals.md) \ No newline at end of file diff --git a/docs/mfc/reference/cpaintdc-class.md b/docs/mfc/reference/cpaintdc-class.md index 87f34ec39d..dc01823c28 100644 --- a/docs/mfc/reference/cpaintdc-class.md +++ b/docs/mfc/reference/cpaintdc-class.md @@ -4,11 +4,10 @@ title: "CPaintDC Class" ms.date: "11/04/2016" f1_keywords: ["CPaintDC", "AFXWIN/CPaintDC", "AFXWIN/CPaintDC::CPaintDC", "AFXWIN/CPaintDC::m_ps", "AFXWIN/CPaintDC::m_hWnd"] helpviewer_keywords: ["CPaintDC [MFC], CPaintDC", "CPaintDC [MFC], m_ps", "CPaintDC [MFC], m_hWnd"] -ms.assetid: 7e245baa-bf9b-403e-a637-7218adf28fab --- -# CPaintDC Class +# `CPaintDC` Class -A device-context class derived from [CDC](../../mfc/reference/cdc-class.md). +A device-context class derived from [`CDC`](../../mfc/reference/cdc-class.md). ## Syntax @@ -22,43 +21,43 @@ class CPaintDC : public CDC |Name|Description| |----------|-----------------| -|[CPaintDC::CPaintDC](#cpaintdc)|Constructs a `CPaintDC` connected to the specified [CWnd](../../mfc/reference/cwnd-class.md).| +|[`CPaintDC::CPaintDC`](#cpaintdc)|Constructs a `CPaintDC` connected to the specified [`CWnd`](../../mfc/reference/cwnd-class.md).| ### Public Data Members |Name|Description| |----------|-----------------| -|[CPaintDC::m_ps](#m_ps)|Contains the [PAINTSTRUCT](/windows/win32/api/winuser/ns-winuser-paintstruct) used to paint the client area.| +|[`CPaintDC::m_ps`](#m_ps)|Contains the [`PAINTSTRUCT`](/windows/win32/api/winuser/ns-winuser-paintstruct) used to paint the client area.| ### Protected Data Members |Name|Description| |----------|-----------------| -|[CPaintDC::m_hWnd](#m_hwnd)|The HWND to which this `CPaintDC` object is attached.| +|[`CPaintDC::m_hWnd`](#m_hwnd)|The `HWND` to which this `CPaintDC` object is attached.| ## Remarks -It performs a [CWnd::BeginPaint](../../mfc/reference/cwnd-class.md#beginpaint) at construction time and [CWnd::EndPaint](../../mfc/reference/cwnd-class.md#endpaint) at destruction time. +It performs a [`CWnd::BeginPaint`](../../mfc/reference/cwnd-class.md#beginpaint) at construction time and [`CWnd::EndPaint`](../../mfc/reference/cwnd-class.md#endpaint) at destruction time. -A `CPaintDC` object can only be used when responding to a [WM_PAINT](/windows/win32/gdi/wm-paint) message, usually in your `OnPaint` message-handler member function. +A `CPaintDC` object can only be used when responding to a [`WM_PAINT`](/windows/win32/gdi/wm-paint) message, usually in your `OnPaint` message-handler member function. For more information on using `CPaintDC`, see [Device Contexts](../../mfc/device-contexts.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CDC](../../mfc/reference/cdc-class.md) +[`CDC`](../../mfc/reference/cdc-class.md) `CPaintDC` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CPaintDC::CPaintDC +## `CPaintDC::CPaintDC` -Constructs a `CPaintDC` object, prepares the application window for painting, and stores the [PAINTSTRUCT](/windows/win32/api/winuser/ns-winuser-paintstruct) structure in the [m_ps](#m_ps) member variable. +Constructs a `CPaintDC` object, prepares the application window for painting, and stores the [`PAINTSTRUCT`](/windows/win32/api/winuser/ns-winuser-paintstruct) structure in the [`m_ps`](#m_ps) member variable. ``` explicit CPaintDC(CWnd* pWnd); @@ -66,18 +65,18 @@ explicit CPaintDC(CWnd* pWnd); ### Parameters -*pWnd*
+*`pWnd`*\ Points to the `CWnd` object to which the `CPaintDC` object belongs. ### Remarks -An exception (of type `CResourceException`) is thrown if the Windows [GetDC](/windows/win32/api/winuser/nf-winuser-getdc) call fails. A device context may not be available if Windows has already allocated all of its available device contexts. Your application competes for the five common display contexts available at any given time under Windows. +An exception (of type `CResourceException`) is thrown if the Windows [`GetDC`](/windows/win32/api/winuser/nf-winuser-getdc) call fails. A device context may not be available if Windows has already allocated all of its available device contexts. Your application competes for the five common display contexts available at any given time under Windows. ### Example [!code-cpp[NVC_MFCDocView#97](../../mfc/codesnippet/cpp/cpaintdc-class_1.cpp)] -## CPaintDC::m_hWnd +## `CPaintDC::m_hWnd` The `HWND` to which this `CPaintDC` object is attached. @@ -87,15 +86,15 @@ HWND m_hWnd; ### Remarks -*m_hWnd* is a protected variable of type HWND. +*`m_hWnd`* is a protected variable of type `HWND`. ### Example [!code-cpp[NVC_MFCDocView#98](../../mfc/codesnippet/cpp/cpaintdc-class_2.cpp)] -## CPaintDC::m_ps +## `CPaintDC::m_ps` -`m_ps` is a public member variable of type [PAINTSTRUCT](/windows/win32/api/winuser/ns-winuser-paintstruct). +`m_ps` is a public member variable of type [`PAINTSTRUCT`](/windows/win32/api/winuser/ns-winuser-paintstruct). ``` PAINTSTRUCT m_ps; @@ -103,7 +102,7 @@ PAINTSTRUCT m_ps; ### Remarks -It is the `PAINTSTRUCT` that is passed to and filled out by [CWnd::BeginPaint](../../mfc/reference/cwnd-class.md#beginpaint). +It's the `PAINTSTRUCT` that is passed to and filled out by [`CWnd::BeginPaint`](../../mfc/reference/cwnd-class.md#beginpaint). The `PAINTSTRUCT` contains information that the application uses to paint the client area of the window associated with a `CPaintDC` object. @@ -111,10 +110,10 @@ Note that you can access the device-context handle through the `PAINTSTRUCT`. Ho ### Example - See the example for [CPaintDC::m_hWnd](#m_hwnd). + See the example for [`CPaintDC::m_hWnd`](#m_hwnd). ## See also -[MFC Sample MDI](../../overview/visual-cpp-samples.md)
-[CDC Class](../../mfc/reference/cdc-class.md)
+[MFC Sample MDI](../../overview/visual-cpp-samples.md)\ +[`CDC` Class](../../mfc/reference/cdc-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/cpanecontainer-class.md b/docs/mfc/reference/cpanecontainer-class.md index b259352e61..46fbe336ba 100644 --- a/docs/mfc/reference/cpanecontainer-class.md +++ b/docs/mfc/reference/cpanecontainer-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: CPaneContainer Class" title: "CPaneContainer Class" +description: "Learn more about: CPaneContainer Class" ms.date: "11/04/2016" f1_keywords: ["CPaneContainer", "AFXPANECONTAINER/CPaneContainer", "AFXPANECONTAINER/CPaneContainer::CPaneContainer", "AFXPANECONTAINER/CPaneContainer::AddPane", "AFXPANECONTAINER/CPaneContainer::AddRef", "AFXPANECONTAINER/CPaneContainer::AddSubPaneContainer", "AFXPANECONTAINER/CPaneContainer::CalcAvailablePaneSpace", "AFXPANECONTAINER/CPaneContainer::CalcAvailableSpace", "AFXPANECONTAINER/CPaneContainer::CalculateRecentSize", "AFXPANECONTAINER/CPaneContainer::CheckPaneDividerVisibility", "AFXPANECONTAINER/CPaneContainer::Copy", "AFXPANECONTAINER/CPaneContainer::DeletePane", "AFXPANECONTAINER/CPaneContainer::FindSubPaneContainer", "AFXPANECONTAINER/CPaneContainer::FindTabbedPane", "AFXPANECONTAINER/CPaneContainer::GetAssociatedSiblingPaneIDs", "AFXPANECONTAINER/CPaneContainer::GetLeftPane", "AFXPANECONTAINER/CPaneContainer::GetLeftPaneContainer", "AFXPANECONTAINER/CPaneContainer::GetMinSize", "AFXPANECONTAINER/CPaneContainer::GetMinSizeLeft", "AFXPANECONTAINER/CPaneContainer::GetMinSizeRight", "AFXPANECONTAINER/CPaneContainer::GetNodeCount", "AFXPANECONTAINER/CPaneContainer::GetPaneDivider", "AFXPANECONTAINER/CPaneContainer::GetParentPaneContainer", "AFXPANECONTAINER/CPaneContainer::GetRecentPaneDividerRect", "AFXPANECONTAINER/CPaneContainer::GetRecentPaneDividerStyle", "AFXPANECONTAINER/CPaneContainer::GetRecentPercent", "AFXPANECONTAINER/CPaneContainer::GetRefCount", "AFXPANECONTAINER/CPaneContainer::GetResizeStep", "AFXPANECONTAINER/CPaneContainer::GetRightPane", "AFXPANECONTAINER/CPaneContainer::GetRightPaneContainer", "AFXPANECONTAINER/CPaneContainer::GetTotalReferenceCount", "AFXPANECONTAINER/CPaneContainer::GetWindowRect", "AFXPANECONTAINER/CPaneContainer::IsDisposed", "AFXPANECONTAINER/CPaneContainer::IsEmpty", "AFXPANECONTAINER/CPaneContainer::IsLeftPane", "AFXPANECONTAINER/CPaneContainer::IsLeftPaneContainer", "AFXPANECONTAINER/CPaneContainer::IsLeftPartEmpty", "AFXPANECONTAINER/CPaneContainer::IsRightPartEmpty", "AFXPANECONTAINER/CPaneContainer::IsVisible", "AFXPANECONTAINER/CPaneContainer::Move", "AFXPANECONTAINER/CPaneContainer::OnDeleteHidePane", "AFXPANECONTAINER/CPaneContainer::OnMoveInternalPaneDivider", "AFXPANECONTAINER/CPaneContainer::OnShowPane", "AFXPANECONTAINER/CPaneContainer::Release", "AFXPANECONTAINER/CPaneContainer::ReleaseEmptyPaneContainer", "AFXPANECONTAINER/CPaneContainer::RemoveNonValidPanes", "AFXPANECONTAINER/CPaneContainer::RemovePane", "AFXPANECONTAINER/CPaneContainer::Resize", "AFXPANECONTAINER/CPaneContainer::ResizePane", "AFXPANECONTAINER/CPaneContainer::ResizePartOfPaneContainer", "AFXPANECONTAINER/CPaneContainer::Serialize", "AFXPANECONTAINER/CPaneContainer::SetPane", "AFXPANECONTAINER/CPaneContainer::SetPaneContainer", "AFXPANECONTAINER/CPaneContainer::SetPaneDivider", "AFXPANECONTAINER/CPaneContainer::SetParentPaneContainer", "AFXPANECONTAINER/CPaneContainer::SetRecentPercent", "AFXPANECONTAINER/CPaneContainer::SetUpByID", "AFXPANECONTAINER/CPaneContainer::StoreRecentDockSiteInfo", "AFXPANECONTAINER/CPaneContainer::StretchPaneContainer"] helpviewer_keywords: ["CPaneContainer [MFC], CPaneContainer", "CPaneContainer [MFC], AddPane", "CPaneContainer [MFC], AddRef", "CPaneContainer [MFC], AddSubPaneContainer", "CPaneContainer [MFC], CalcAvailablePaneSpace", "CPaneContainer [MFC], CalcAvailableSpace", "CPaneContainer [MFC], CalculateRecentSize", "CPaneContainer [MFC], CheckPaneDividerVisibility", "CPaneContainer [MFC], Copy", "CPaneContainer [MFC], DeletePane", "CPaneContainer [MFC], FindSubPaneContainer", "CPaneContainer [MFC], FindTabbedPane", "CPaneContainer [MFC], GetAssociatedSiblingPaneIDs", "CPaneContainer [MFC], GetLeftPane", "CPaneContainer [MFC], GetLeftPaneContainer", "CPaneContainer [MFC], GetMinSize", "CPaneContainer [MFC], GetMinSizeLeft", "CPaneContainer [MFC], GetMinSizeRight", "CPaneContainer [MFC], GetNodeCount", "CPaneContainer [MFC], GetPaneDivider", "CPaneContainer [MFC], GetParentPaneContainer", "CPaneContainer [MFC], GetRecentPaneDividerRect", "CPaneContainer [MFC], GetRecentPaneDividerStyle", "CPaneContainer [MFC], GetRecentPercent", "CPaneContainer [MFC], GetRefCount", "CPaneContainer [MFC], GetResizeStep", "CPaneContainer [MFC], GetRightPane", "CPaneContainer [MFC], GetRightPaneContainer", "CPaneContainer [MFC], GetTotalReferenceCount", "CPaneContainer [MFC], GetWindowRect", "CPaneContainer [MFC], IsDisposed", "CPaneContainer [MFC], IsEmpty", "CPaneContainer [MFC], IsLeftPane", "CPaneContainer [MFC], IsLeftPaneContainer", "CPaneContainer [MFC], IsLeftPartEmpty", "CPaneContainer [MFC], IsRightPartEmpty", "CPaneContainer [MFC], IsVisible", "CPaneContainer [MFC], Move", "CPaneContainer [MFC], OnDeleteHidePane", "CPaneContainer [MFC], OnMoveInternalPaneDivider", "CPaneContainer [MFC], OnShowPane", "CPaneContainer [MFC], Release", "CPaneContainer [MFC], ReleaseEmptyPaneContainer", "CPaneContainer [MFC], RemoveNonValidPanes", "CPaneContainer [MFC], RemovePane", "CPaneContainer [MFC], Resize", "CPaneContainer [MFC], ResizePane", "CPaneContainer [MFC], ResizePartOfPaneContainer", "CPaneContainer [MFC], Serialize", "CPaneContainer [MFC], SetPane", "CPaneContainer [MFC], SetPaneContainer", "CPaneContainer [MFC], SetPaneDivider", "CPaneContainer [MFC], SetParentPaneContainer", "CPaneContainer [MFC], SetRecentPercent", "CPaneContainer [MFC], SetUpByID", "CPaneContainer [MFC], StoreRecentDockSiteInfo", "CPaneContainer [MFC], StretchPaneContainer"] -ms.assetid: beb79e08-f611-4d66-ba04-053baa79bf86 --- # CPaneContainer Class -The `CPaneContainer` class is a basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer.` It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [CPaneContainerManager](../../mfc/reference/cpanecontainermanager-class.md) object. +The `CPaneContainer` class is a basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer`. It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [CPaneContainerManager](../../mfc/reference/cpanecontainermanager-class.md) object. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -843,7 +842,7 @@ virtual int StretchPaneContainer( ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CObject Class](../../mfc/reference/cobject-class.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[CObject Class](../../mfc/reference/cobject-class.md)\ [CPaneContainerManager Class](../../mfc/reference/cpanecontainermanager-class.md) diff --git a/docs/mfc/reference/cpanedivider-class.md b/docs/mfc/reference/cpanedivider-class.md index 30585e316b..23ca314fbe 100644 --- a/docs/mfc/reference/cpanedivider-class.md +++ b/docs/mfc/reference/cpanedivider-class.md @@ -92,9 +92,9 @@ The following example demonstrates how to get a `CPaneDivider` object from a `CW [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CPaneDivider](../../mfc/reference/cpanedivider-class.md) + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CPaneDivider](../../mfc/reference/cpanedivider-class.md) ## Requirements diff --git a/docs/mfc/reference/cpen-class.md b/docs/mfc/reference/cpen-class.md index c551db62e4..c891d6bff1 100644 --- a/docs/mfc/reference/cpen-class.md +++ b/docs/mfc/reference/cpen-class.md @@ -4,9 +4,8 @@ title: "CPen Class" ms.date: "11/04/2016" f1_keywords: ["CPen", "AFXWIN/CPen", "AFXWIN/CPen::CPen", "AFXWIN/CPen::CreatePen", "AFXWIN/CPen::CreatePenIndirect", "AFXWIN/CPen::FromHandle", "AFXWIN/CPen::GetExtLogPen", "AFXWIN/CPen::GetLogPen"] helpviewer_keywords: ["CPen [MFC], CPen", "CPen [MFC], CreatePen", "CPen [MFC], CreatePenIndirect", "CPen [MFC], FromHandle", "CPen [MFC], GetExtLogPen", "CPen [MFC], GetLogPen"] -ms.assetid: 93175a3a-d46c-4768-be8d-863254f97a5f --- -# CPen Class +# `CPen` Class Encapsulates a Windows graphics device interface (GDI) pen. @@ -22,23 +21,23 @@ class CPen : public CGdiObject |Name|Description| |----------|-----------------| -|[CPen::CPen](#cpen)|Constructs a `CPen` object.| +|[`CPen::CPen`](#cpen)|Constructs a `CPen` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPen::CreatePen](#createpen)|Creates a logical cosmetic or geometric pen with the specified style, width, and brush attributes, and attaches it to the `CPen` object.| -|[CPen::CreatePenIndirect](#createpenindirect)|Creates a pen with the style, width, and color given in a [LOGPEN](/windows/win32/api/wingdi/ns-wingdi-logpen) structure, and attaches it to the `CPen` object.| -|[CPen::FromHandle](#fromhandle)|Returns a pointer to a `CPen` object when given a Windows HPEN.| -|[CPen::GetExtLogPen](#getextlogpen)|Gets an [EXTLOGPEN](/windows/win32/api/wingdi/ns-wingdi-extlogpen) underlying structure.| -|[CPen::GetLogPen](#getlogpen)|Gets a [LOGPEN](/windows/win32/api/wingdi/ns-wingdi-logpen) underlying structure.| +|[`CPen::CreatePen`](#createpen)|Creates a logical cosmetic or geometric pen with the specified style, width, and brush attributes, and attaches it to the `CPen` object.| +|[`CPen::CreatePenIndirect`](#createpenindirect)|Creates a pen with the style, width, and color given in a [`LOGPEN`](/windows/win32/api/wingdi/ns-wingdi-logpen) structure, and attaches it to the `CPen` object.| +|[`CPen::FromHandle`](#fromhandle)|Returns a pointer to a `CPen` object when given a Windows HPEN.| +|[`CPen::GetExtLogPen`](#getextlogpen)|Gets an [`EXTLOGPEN`](/windows/win32/api/wingdi/ns-wingdi-extlogpen) underlying structure.| +|[`CPen::GetLogPen`](#getlogpen)|Gets a [`LOGPEN`](/windows/win32/api/wingdi/ns-wingdi-logpen) underlying structure.| ### Public Operators |Name|Description| |----------|-----------------| -|[CPen::operator HPEN](#operator_hpen)|Returns the Windows handle attached to the `CPen` object.| +|[`CPen::operator HPEN`](#operator_hpen)|Returns the Windows handle attached to the `CPen` object.| ## Remarks @@ -46,17 +45,17 @@ For more information on using `CPen`, see [Graphic Objects](../../mfc/graphic-ob ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CGdiObject](../../mfc/reference/cgdiobject-class.md) +[`CGdiObject`](../../mfc/reference/cgdiobject-class.md) `CPen` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CPen::CPen +## `CPen::CPen` Constructs a `CPen` object. @@ -78,69 +77,69 @@ CPen( ### Parameters -*nPenStyle*
+*`nPenStyle`*\ Specifies the pen style. This parameter in the first version of the constructor can be one of the following values: -- PS_SOLID Creates a solid pen. +- `PS_SOLID` Creates a solid pen. -- PS_DASH Creates a dashed pen. Valid only when the pen width is 1 or less, in device units. +- `PS_DASH` Creates a dashed pen. Valid only when the pen width is 1 or less, in device units. -- PS_DOT Creates a dotted pen. Valid only when the pen width is 1 or less, in device units. +- `PS_DOT` Creates a dotted pen. Valid only when the pen width is 1 or less, in device units. -- PS_DASHDOT Creates a pen with alternating dashes and dots. Valid only when the pen width is 1 or less, in device units. +- `PS_DASHDOT` Creates a pen with alternating dashes and dots. Valid only when the pen width is 1 or less, in device units. -- PS_DASHDOTDOT Creates a pen with alternating dashes and double dots. Valid only when the pen width is 1 or less, in device units. +- `PS_DASHDOTDOT` Creates a pen with alternating dashes and double dots. Valid only when the pen width is 1 or less, in device units. -- PS_NULL Creates a null pen. +- `PS_NULL` Creates a null pen. -- PS_INSIDEFRAME Creates a pen that draws a line inside the frame of closed shapes produced by the Windows GDI output functions that specify a bounding rectangle (for example, the `Ellipse`, `Rectangle`, `RoundRect`, `Pie`, and `Chord` member functions). When this style is used with Windows GDI output functions that do not specify a bounding rectangle (for example, the `LineTo` member function), the drawing area of the pen is not limited by a frame. +- `PS_INSIDEFRAME` Creates a pen that draws a line inside the frame of closed shapes produced by the Windows GDI output functions that specify a bounding rectangle (for example, the `Ellipse`, `Rectangle`, `RoundRect`, `Pie`, and `Chord` member functions). When this style is used with Windows GDI output functions that don't specify a bounding rectangle (for example, the `LineTo` member function), the drawing area of the pen isn't limited by a frame. -The second version of the `CPen` constructor specifies a combination of type, style, end cap, and join attributes. The values from each category should be combined by using the bitwise OR operator (|). The pen type can be one of the following values: +The second version of the `CPen` constructor specifies a combination of type, style, end cap, and join attributes. The values from each category should be combined by using the bitwise "or" (`|`) operator. The pen type can be one of the following values: -- PS_GEOMETRIC Creates a geometric pen. +- `PS_GEOMETRIC` Creates a geometric pen. -- PS_COSMETIC Creates a cosmetic pen. +- `PS_COSMETIC` Creates a cosmetic pen. - The second version of the `CPen` constructor adds the following pen styles for *nPenStyle*: + The second version of the `CPen` constructor adds the following pen styles for *`nPenStyle`*: -- PS_ALTERNATE Creates a pen that sets every other pixel. (This style is applicable only for cosmetic pens.) +- `PS_ALTERNATE` Creates a pen that sets every other pixel. (This style is applicable only for cosmetic pens.) -- PS_USERSTYLE Creates a pen that uses a styling array supplied by the user. +- `PS_USERSTYLE` Creates a pen that uses a styling array supplied by the user. The end cap can be one of the following values: -- PS_ENDCAP_ROUND End caps are round. +- `PS_ENDCAP_ROUND` End caps are round. -- PS_ENDCAP_SQUARE End caps are square. +- `PS_ENDCAP_SQUARE` End caps are square. -- PS_ENDCAP_FLAT End caps are flat. +- `PS_ENDCAP_FLAT` End caps are flat. The join can be one of the following values: -- PS_JOIN_BEVEL Joins are beveled. +- `PS_JOIN_BEVEL` Joins are beveled. -- PS_JOIN_MITER Joins are mitered when they are within the current limit set by the [SetMiterLimit](/windows/win32/api/wingdi/nf-wingdi-setmiterlimit) function. If the join exceeds this limit, it is beveled. +- `PS_JOIN_MITER` Joins are mitered when they are within the current limit set by the [`SetMiterLimit`](/windows/win32/api/wingdi/nf-wingdi-setmiterlimit) function. If the join exceeds this limit, it's beveled. -- PS_JOIN_ROUND Joins are round. +- `PS_JOIN_ROUND` Joins are round. -*nWidth*
+*`nWidth`*\ Specifies the width of the pen. -- For the first version of the constructor, if this value is 0, the width in device units is always 1 pixel, regardless of the mapping mode. +- For the first version of the constructor, a value of 0 will be treated similarly to a value of 1, except that the width will not be affected by scale-transform operations that are in effect for the Graphics object that the pen is used for; the width will always be 1 pixel. -- For the second version of the constructor, if *nPenStyle* is PS_GEOMETRIC, the width is given in logical units. If *nPenStyle* is PS_COSMETIC, the width must be set to 1. +- For the second version of the constructor, if *`nPenStyle`* is `PS_GEOMETRIC`, the width is given in logical units. If *`nPenStyle`* is `PS_COSMETIC`, the width must be set to 1. -*crColor*
+*`crColor`*\ Contains an RGB color for the pen. -*pLogBrush*
-Points to a `LOGBRUSH` structure. If *nPenStyle* is PS_COSMETIC, the *lbColor* member of the `LOGBRUSH` structure specifies the color of the pen and the *lbStyle* member of the `LOGBRUSH` structure must be set to BS_SOLID. If *nPenStyle* is PS_GEOMETRIC, all members must be used to specify the brush attributes of the pen. +*`pLogBrush`*\ +Points to a `LOGBRUSH` structure. If *`nPenStyle`* is `PS_COSMETIC`, the *`lbColor`* member of the `LOGBRUSH` structure specifies the color of the pen and the *`lbStyle`* member of the `LOGBRUSH` structure must be set to `BS_SOLID`. If *`nPenStyle`* is `PS_GEOMETRIC`, all members must be used to specify the brush attributes of the pen. -*nStyleCount*
-Specifies the length, in doubleword units, of the *lpStyle* array. This value must be zero if *nPenStyle* is not PS_USERSTYLE. +*`nStyleCount`*\ +Specifies the length, in doubleword units, of the *`lpStyle`* array. This value must be zero if *`nPenStyle`* isn't `PS_USERSTYLE`. -*lpStyle*
-Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be NULL if *nPenStyle* is not PS_USERSTYLE. +*`lpStyle`*\ +Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be `NULL` if *`nPenStyle`* isn't `PS_USERSTYLE`. ### Remarks @@ -152,7 +151,7 @@ If you use the constructor that takes arguments, then no further initialization [!code-cpp[NVC_MFCDocView#99](../../mfc/codesnippet/cpp/cpen-class_1.cpp)] -## CPen::CreatePen +## `CPen::CreatePen` Creates a logical cosmetic or geometric pen with the specified style, width, and brush attributes, and attaches it to the `CPen` object. @@ -172,27 +171,27 @@ BOOL CreatePen( ### Parameters -*nPenStyle*
-Specifies the style for the pen. For a list of possible values, see the *nPenStyle* parameter in the [CPen](#cpen) constructor. +*`nPenStyle`*\ +Specifies the style for the pen. For a list of possible values, see the *`nPenStyle`* parameter in the [`CPen`](#cpen) constructor. -*nWidth*
+*`nWidth`*\ Specifies the width of the pen. -- For the first version of `CreatePen`, if this value is 0, the width in device units is always 1 pixel, regardless of the mapping mode. +- For the first version of `CreatePen`, a value of 0 will be treated similarly to a value of 1, except that the width will not be affected by scale-transform operations that are in effect for the Graphics object that the pen is used for; the width will always be 1 pixel. -- For the second version of `CreatePen`, if *nPenStyle* is PS_GEOMETRIC, the width is given in logical units. If *nPenStyle* is PS_COSMETIC, the width must be set to 1. +- For the second version of `CreatePen`, if *`nPenStyle`* is `PS_GEOMETRIC`, the width is given in logical units. If *`nPenStyle`* is `PS_COSMETIC`, the width must be set to 1. -*crColor*
+*`crColor`*\ Contains an RGB color for the pen. -*pLogBrush*
-Points to a [LOGBRUSH](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure. If *nPenStyle* is PS_COSMETIC, the `lbColor` member of the `LOGBRUSH` structure specifies the color of the pen and the *lbStyle* member of the `LOGBRUSH` structure must be set to BS_SOLID. If nPenStyle is PS_GEOMETRIC, all members must be used to specify the brush attributes of the pen. +*`pLogBrush`*\ +Points to a [`LOGBRUSH`](/windows/win32/api/wingdi/ns-wingdi-logbrush) structure. If *`nPenStyle`* is `PS_COSMETIC`, the `lbColor` member of the `LOGBRUSH` structure specifies the color of the pen and the *`lbStyle`* member of the `LOGBRUSH` structure must be set to `BS_SOLID`. If `nPenStyle` is `PS_GEOMETRIC`, all members must be used to specify the brush attributes of the pen. -*nStyleCount*
-Specifies the length, in doubleword units, of the *lpStyle* array. This value must be zero if *nPenStyle* is not PS_USERSTYLE. +*`nStyleCount`*\ +Specifies the length, in doubleword units, of the *`lpStyle`* array. This value must be zero if *`nPenStyle`* isn't `PS_USERSTYLE`. -*lpStyle*
-Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be NULL if *nPenStyle* is not PS_USERSTYLE. +*`lpStyle`*\ +Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be `NULL` if *`nPenStyle`* isn't `PS_USERSTYLE`. ### Return Value @@ -202,27 +201,27 @@ Nonzero if successful, or zero if the method fails. The first version of `CreatePen` initializes a pen with the specified style, width, and color. The pen can be subsequently selected as the current pen for any device context. -Pens that have a width greater than 1 pixel should always have either the PS_NULL, PS_SOLID, or PS_INSIDEFRAME style. +Pens that have a width greater than 1 pixel should always have either the `PS_NULL`, `PS_SOLID`, or `PS_INSIDEFRAME` style. -If a pen has the PS_INSIDEFRAME style and a color that does not match a color in the logical color table, the pen is drawn with a dithered color. The PS_SOLID pen style cannot be used to create a pen with a dithered color. The style PS_INSIDEFRAME is identical to PS_SOLID if the pen width is less than or equal to 1. +If a pen has the `PS_INSIDEFRAME` style and a color that doesn't match a color in the logical color table, the pen is drawn with a dithered color. The `PS_SOLID` pen style can't be used to create a pen with a dithered color. The style `PS_INSIDEFRAME` is identical to `PS_SOLID` if the pen width is less than or equal to 1. -The second version of `CreatePen` initializes a logical cosmetic or geometric pen that has the specified style, width, and brush attributes. The width of a cosmetic pen is always 1; the width of a geometric pen is always specified in world units. After an application creates a logical pen, it can select that pen into a device context by calling the [CDC::SelectObject](../../mfc/reference/cdc-class.md#selectobject) function. After a pen is selected into a device context, it can be used to draw lines and curves. +The second version of `CreatePen` initializes a logical cosmetic or geometric pen that has the specified style, width, and brush attributes. The width of a cosmetic pen is always 1; the width of a geometric pen is always specified in world units. After an application creates a logical pen, it can select that pen into a device context by calling the [`CDC::SelectObject`](../../mfc/reference/cdc-class.md#selectobject) function. After a pen is selected into a device context, it can be used to draw lines and curves. -- If *nPenStyle* is PS_COSMETIC and PS_USERSTYLE, the entries in the *lpStyle* array specify lengths of dashes and spaces in style units. A style unit is defined by the device in which the pen is used to draw a line. +- If *`nPenStyle`* is `PS_COSMETIC` and `PS_USERSTYLE`, the entries in the *`lpStyle`* array specify lengths of dashes and spaces in style units. A style unit is defined by the device in which the pen is used to draw a line. -- If *nPenStyle* is PS_GEOMETRIC and PS_USERSTYLE, the entries in the *lpStyle* array specify lengths of dashes and spaces in logical units. +- If *`nPenStyle`* is `PS_GEOMETRIC` and `PS_USERSTYLE`, the entries in the *`lpStyle`* array specify lengths of dashes and spaces in logical units. -- If *nPenStyle* is PS_ALTERNATE, the style unit is ignored and every other pixel is set. +- If *`nPenStyle`* is `PS_ALTERNATE`, the style unit is ignored and every other pixel is set. -When an application no longer requires a given pen, it should call the [CGdiObject::DeleteObject](../../mfc/reference/cgdiobject-class.md#deleteobject) member function or destroy the `CPen` object so the resource is no longer in use. An application should not delete a pen when the pen is selected in a device context. +When an application no longer requires a given pen, it should call the [`CGdiObject::DeleteObject`](../../mfc/reference/cgdiobject-class.md#deleteobject) member function or destroy the `CPen` object so the resource is no longer in use. An application shouldn't delete a pen when the pen is selected in a device context. ### Example [!code-cpp[NVC_MFCDocView#100](../../mfc/codesnippet/cpp/cpen-class_2.cpp)] -## CPen::CreatePenIndirect +## `CPen::CreatePenIndirect` -Initializes a pen that has the style, width, and color given in the structure pointed to by *lpLogPen*. +Initializes a pen that has the style, width, and color given in the structure pointed to by *`lpLogPen`*. ``` BOOL CreatePenIndirect(LPLOGPEN lpLogPen); @@ -230,8 +229,8 @@ BOOL CreatePenIndirect(LPLOGPEN lpLogPen); ### Parameters -*lpLogPen*
-Points to the Windows [LOGPEN](/windows/win32/api/Wingdi/ns-wingdi-logpen) structure that contains information about the pen. +*`lpLogPen`*\ +Points to the Windows [`LOGPEN`](/windows/win32/api/Wingdi/ns-wingdi-logpen) structure that contains information about the pen. ### Return Value @@ -239,15 +238,15 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -Pens that have a width greater than 1 pixel should always have either the PS_NULL, PS_SOLID, or PS_INSIDEFRAME style. +Pens that have a width greater than 1 pixel should always have either the `PS_NULL`, `PS_SOLID`, or `PS_INSIDEFRAME` style. -If a pen has the PS_INSIDEFRAME style and a color that does not match a color in the logical color table, the pen is drawn with a dithered color. The PS_INSIDEFRAME style is identical to PS_SOLID if the pen width is less than or equal to 1. +If a pen has the `PS_INSIDEFRAME` style and a color that doesn't match a color in the logical color table, the pen is drawn with a dithered color. The `PS_INSIDEFRAME` style is identical to `PS_SOLID` if the pen width is less than or equal to 1. ### Example [!code-cpp[NVC_MFCDocView#101](../../mfc/codesnippet/cpp/cpen-class_3.cpp)] -## CPen::FromHandle +## `CPen::FromHandle` Returns a pointer to a `CPen` object given a handle to a Windows GDI pen object. @@ -257,22 +256,22 @@ static CPen* PASCAL FromHandle(HPEN hPen); ### Parameters -*hPen*
+*`hPen`*\ `HPEN` handle to Windows GDI pen. ### Return Value -A pointer to a `CPen` object if successful; otherwise NULL. +A pointer to a `CPen` object if successful; otherwise `NULL`. ### Remarks -If a `CPen` object is not attached to the handle, a temporary `CPen` object is created and attached. This temporary `CPen` object is valid only until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. In other words, the temporary object is only valid during the processing of one window message. +If a `CPen` object isn't attached to the handle, a temporary `CPen` object is created and attached. This temporary `CPen` object is valid only until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. In other words, the temporary object is only valid during the processing of one window message. ### Example [!code-cpp[NVC_MFCDocView#105](../../mfc/codesnippet/cpp/cpen-class_4.cpp)] -## CPen::GetExtLogPen +## `CPen::GetExtLogPen` Gets an `EXTLOGPEN` underlying structure. @@ -282,8 +281,8 @@ int GetExtLogPen(EXTLOGPEN* pLogPen); ### Parameters -*pLogPen*
-Points to an [EXTLOGPEN](/windows/win32/api/wingdi/ns-wingdi-extlogpen) structure that contains information about the pen. +*`pLogPen`*\ +Points to an [`EXTLOGPEN`](/windows/win32/api/wingdi/ns-wingdi-extlogpen) structure that contains information about the pen. ### Return Value @@ -295,13 +294,13 @@ The `EXTLOGPEN` structure defines the style, width, and brush attributes of a pe See the following topics in the Windows SDK for information about pen attributes: -- [GetObject](/windows/win32/api/wingdi/nf-wingdi-getobject) +- [`GetObject`](/windows/win32/api/wingdi/nf-wingdi-getobject) -- [EXTLOGPEN](/windows/win32/api/wingdi/ns-wingdi-extlogpen) +- [`EXTLOGPEN`](/windows/win32/api/wingdi/ns-wingdi-extlogpen) -- [LOGPEN](/windows/win32/api/wingdi/ns-wingdi-logpen) +- [`LOGPEN`](/windows/win32/api/wingdi/ns-wingdi-logpen) -- [ExtCreatePen](/windows/win32/api/wingdi/nf-wingdi-extcreatepen) +- [`ExtCreatePen`](/windows/win32/api/wingdi/nf-wingdi-extcreatepen) ### Example @@ -309,7 +308,7 @@ The following code example demonstrates calling `GetExtLogPen` to retrieve a pen [!code-cpp[NVC_MFCDocView#102](../../mfc/codesnippet/cpp/cpen-class_5.cpp)] -## CPen::GetLogPen +## `CPen::GetLogPen` Gets a `LOGPEN` underlying structure. @@ -319,8 +318,8 @@ int GetLogPen(LOGPEN* pLogPen); ### Parameters -*pLogPen*
-Points to a [LOGPEN](/windows/win32/api/wingdi/ns-wingdi-logpen) structure to contain information about the pen. +*`pLogPen`*\ +Points to a [`LOGPEN`](/windows/win32/api/wingdi/ns-wingdi-logpen) structure to contain information about the pen. ### Return Value @@ -334,9 +333,9 @@ For example, call `GetLogPen` to match the particular style of pen. See the following topics in the Windows SDK for information about pen attributes: -- [GetObject](/windows/win32/api/wingdi/nf-wingdi-getobject) +- [`GetObject`](/windows/win32/api/wingdi/nf-wingdi-getobject) -- [LOGPEN](/windows/win32/api/wingdi/ns-wingdi-logpen) +- [`LOGPEN`](/windows/win32/api/wingdi/ns-wingdi-logpen) ### Example @@ -344,7 +343,7 @@ The following code example demonstrates calling `GetLogPen` to retrieve a pen ch [!code-cpp[NVC_MFCDocView#103](../../mfc/codesnippet/cpp/cpen-class_6.cpp)] -## CPen::operator HPEN +## `CPen::operator HPEN` Gets the attached Windows GDI handle of the `CPen` object. @@ -354,11 +353,11 @@ operator HPEN() const; ### Return Value -If successful, a handle to the Windows GDI object represented by the `CPen` object; otherwise NULL. +If successful, a handle to the Windows GDI object represented by the `CPen` object; otherwise `NULL`. ### Remarks -This operator is a casting operator, which supports direct use of an HPEN object. +This operator is a casting operator, which supports direct use of an `HPEN` object. For more information about using graphic objects, see the article [Graphic Objects](/windows/win32/gdi/graphic-objects) in Windows SDK. @@ -368,6 +367,6 @@ For more information about using graphic objects, see the article [Graphic Objec ## See also -[CGdiObject Class](../../mfc/reference/cgdiobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CBrush Class](../../mfc/reference/cbrush-class.md) +[`CGdiObject` Class](../../mfc/reference/cgdiobject-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CBrush` Class](../../mfc/reference/cbrush-class.md) diff --git a/docs/mfc/reference/cprintdialog-class.md b/docs/mfc/reference/cprintdialog-class.md index 0053a21801..d4c03521ce 100644 --- a/docs/mfc/reference/cprintdialog-class.md +++ b/docs/mfc/reference/cprintdialog-class.md @@ -4,9 +4,8 @@ title: "CPrintDialog Class" ms.date: "11/04/2016" f1_keywords: ["CPrintDialog", "AFXDLGS/CPrintDialog", "AFXDLGS/CPrintDialog::CPrintDialog", "AFXDLGS/CPrintDialog::CreatePrinterDC", "AFXDLGS/CPrintDialog::DoModal", "AFXDLGS/CPrintDialog::GetCopies", "AFXDLGS/CPrintDialog::GetDefaults", "AFXDLGS/CPrintDialog::GetDeviceName", "AFXDLGS/CPrintDialog::GetDevMode", "AFXDLGS/CPrintDialog::GetDriverName", "AFXDLGS/CPrintDialog::GetFromPage", "AFXDLGS/CPrintDialog::GetPortName", "AFXDLGS/CPrintDialog::GetPrinterDC", "AFXDLGS/CPrintDialog::GetToPage", "AFXDLGS/CPrintDialog::PrintAll", "AFXDLGS/CPrintDialog::PrintCollate", "AFXDLGS/CPrintDialog::PrintRange", "AFXDLGS/CPrintDialog::PrintSelection", "AFXDLGS/CPrintDialog::m_pd"] helpviewer_keywords: ["CPrintDialog [MFC], CPrintDialog", "CPrintDialog [MFC], CreatePrinterDC", "CPrintDialog [MFC], DoModal", "CPrintDialog [MFC], GetCopies", "CPrintDialog [MFC], GetDefaults", "CPrintDialog [MFC], GetDeviceName", "CPrintDialog [MFC], GetDevMode", "CPrintDialog [MFC], GetDriverName", "CPrintDialog [MFC], GetFromPage", "CPrintDialog [MFC], GetPortName", "CPrintDialog [MFC], GetPrinterDC", "CPrintDialog [MFC], GetToPage", "CPrintDialog [MFC], PrintAll", "CPrintDialog [MFC], PrintCollate", "CPrintDialog [MFC], PrintRange", "CPrintDialog [MFC], PrintSelection", "CPrintDialog [MFC], m_pd"] -ms.assetid: 5bdb2424-adf8-433d-a97c-df11a83bc4e4 --- -# CPrintDialog Class +# `CPrintDialog` Class Encapsulates the services provided by the Windows common dialog box for printing. @@ -22,62 +21,62 @@ class CPrintDialog : public CCommonDialog |Name|Description| |----------|-----------------| -|[CPrintDialog::CPrintDialog](#cprintdialog)|Constructs a `CPrintDialog` object.| +|[`CPrintDialog::CPrintDialog`](#cprintdialog)|Constructs a `CPrintDialog` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPrintDialog::CreatePrinterDC](#createprinterdc)|Creates a printer device context without displaying the Print dialog box.| -|[CPrintDialog::DoModal](#domodal)|Displays the dialog box and allows the user to make a selection.| -|[CPrintDialog::GetCopies](#getcopies)|Retrieves the number of copies requested.| -|[CPrintDialog::GetDefaults](#getdefaults)|Retrieves device defaults without displaying a dialog box.| -|[CPrintDialog::GetDeviceName](#getdevicename)|Retrieves the name of the currently selected printer device.| -|[CPrintDialog::GetDevMode](#getdevmode)|Retrieves the `DEVMODE` structure.| -|[CPrintDialog::GetDriverName](#getdrivername)|Retrieves the name of the currently selected printer driver.| -|[CPrintDialog::GetFromPage](#getfrompage)|Retrieves the starting page of the print range.| -|[CPrintDialog::GetPortName](#getportname)|Retrieves the name of the currently selected printer port.| -|[CPrintDialog::GetPrinterDC](#getprinterdc)|Retrieves a handle to the printer device context.| -|[CPrintDialog::GetToPage](#gettopage)|Retrieves the ending page of the print range.| -|[CPrintDialog::PrintAll](#printall)|Determines whether to print all pages of the document.| -|[CPrintDialog::PrintCollate](#printcollate)|Determines whether collated copies are requested.| -|[CPrintDialog::PrintRange](#printrange)|Determines whether to print only a specified range of pages.| -|[CPrintDialog::PrintSelection](#printselection)|Determines whether to print only the currently selected items.| +|[`CPrintDialog::CreatePrinterDC`](#createprinterdc)|Creates a printer device context without displaying the Print dialog box.| +|[`CPrintDialog::DoModal`](#domodal)|Displays the dialog box and allows the user to make a selection.| +|[`CPrintDialog::GetCopies`](#getcopies)|Retrieves the number of copies requested.| +|[`CPrintDialog::GetDefaults`](#getdefaults)|Retrieves device defaults without displaying a dialog box.| +|[`CPrintDialog::GetDeviceName`](#getdevicename)|Retrieves the name of the currently selected printer device.| +|[`CPrintDialog::GetDevMode`](#getdevmode)|Retrieves the `DEVMODE` structure.| +|[`CPrintDialog::GetDriverName`](#getdrivername)|Retrieves the name of the currently selected printer driver.| +|[`CPrintDialog::GetFromPage`](#getfrompage)|Retrieves the starting page of the print range.| +|[`CPrintDialog::GetPortName`](#getportname)|Retrieves the name of the currently selected printer port.| +|[`CPrintDialog::GetPrinterDC`](#getprinterdc)|Retrieves a handle to the printer device context.| +|[`CPrintDialog::GetToPage`](#gettopage)|Retrieves the ending page of the print range.| +|[`CPrintDialog::PrintAll`](#printall)|Determines whether to print all pages of the document.| +|[`CPrintDialog::PrintCollate`](#printcollate)|Determines whether collated copies are requested.| +|[`CPrintDialog::PrintRange`](#printrange)|Determines whether to print only a specified range of pages.| +|[`CPrintDialog::PrintSelection`](#printselection)|Determines whether to print only the currently selected items.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CPrintDialog::m_pd](#m_pd)|A structure used to customize a `CPrintDialog` object.| +|[`CPrintDialog::m_pd`](#m_pd)|A structure used to customize a `CPrintDialog` object.| ## Remarks Common print dialog boxes provide an easy way to implement Print and Print Setup dialog boxes in a manner consistent with Windows standards. > [!NOTE] -> The `CPrintDialogEx` class encapsulates the services provided by the Windows Print property sheet. For more information see the [CPrintDialogEx](../../mfc/reference/cprintdialogex-class.md) overview. +> The `CPrintDialogEx` class encapsulates the services provided by the Windows Print property sheet. For more information, see the [`CPrintDialogEx`](../../mfc/reference/cprintdialogex-class.md) overview. -`CPrintDialog`'s functionality is superseded by that of [CPageSetupDialog](../../mfc/reference/cpagesetupdialog-class.md), which is designed to provide you with a common dialog box for both print setup and page setup. +`CPrintDialog`'s functionality is superseded by that of [`CPageSetupDialog`](../../mfc/reference/cpagesetupdialog-class.md), which is designed to provide you with a common dialog box for both print setup and page setup. You can rely on the framework to handle many aspects of the printing process for your application. In this case, the framework automatically displays the Windows common dialog box for printing. You can also have the framework handle printing for your application but override the common Print dialog box with your own print dialog box. For more information about using the framework to handle printing tasks, see the article [Printing](../../mfc/printing.md). -If you want your application to handle printing without the framework's involvement, you can use the `CPrintDialog` class "as is" with the constructor provided, or you can derive your own dialog class from `CPrintDialog` and write a constructor to suit your needs. In either case, these dialog boxes will behave like standard MFC dialog boxes because they are derived from class `CCommonDialog`. +If you want your application to handle printing without the framework's involvement, you can use the `CPrintDialog` class "as is" with the constructor provided, or you can derive your own dialog class from `CPrintDialog` and write a constructor to suit your needs. In either case, these dialog boxes will behave like standard MFC dialog boxes because they're derived from class `CCommonDialog`. -To use a `CPrintDialog` object, first create the object using the `CPrintDialog` constructor. Once the dialog box has been constructed, you can set or modify any values in the [m_pd](#m_pd) structure to initialize the values of the dialog box's controls. The `m_pd` structure is of type [PRINTDLG](/windows/win32/api/commdlg/ns-commdlg-printdlga). For more information on this structure, see the Windows SDK. +To use a `CPrintDialog` object, first create the object using the `CPrintDialog` constructor. Once the dialog box has been constructed, you can set or modify any values in the [`m_pd`](#m_pd) structure to initialize the values of the dialog box's controls. The `m_pd` structure is of type [`PRINTDLG`](/windows/win32/api/commdlg/ns-commdlg-printdlga). For more information on this structure, see the Windows SDK. -If you do not supply your own handles in `m_pd` for the `hDevMode` and `hDevNames` members, be sure to call the Windows function `GlobalFree` for these handles when you are done with the dialog box. When using the framework's Print Setup implementation provided by `CWinApp::OnFilePrintSetup`, you do not have to free these handles. The handles are maintained by `CWinApp` and are freed in `CWinApp`'s destructor. It is only necessary to free these handles when using `CPrintDialog` stand-alone. +If you don't supply your own handles in `m_pd` for the `hDevMode` and `hDevNames` members, be sure to call the Windows function `GlobalFree` for these handles when you're done with the dialog box. When using the framework's Print Setup implementation provided by `CWinApp::OnFilePrintSetup`, you don't have to free these handles. The handles are maintained by `CWinApp` and are freed in `CWinApp`'s destructor. It's only necessary to free these handles when using `CPrintDialog` stand-alone. -After initializing the dialog box controls, call the `DoModal` member function to display the dialog box and allow the user to select print options. `DoModal` returns whether the user selected the OK (IDOK) or Cancel (IDCANCEL) button. +After initializing the dialog box controls, call the `DoModal` member function to display the dialog box and allow the user to select print options. `DoModal` returns whether the user selected the **OK** (`IDOK`) or **Cancel** (`IDCANCEL`) button. -If `DoModal` returns IDOK, you can use one of `CPrintDialog`'s member functions to retrieve the information input by the user. +If `DoModal` returns `IDOK`, you can use one of `CPrintDialog`'s member functions to retrieve the information input by the user. The `CPrintDialog::GetDefaults` member function is useful for retrieving the current printer defaults without displaying a dialog box. This member function requires no user interaction. You can use the Windows `CommDlgExtendedError` function to determine whether an error occurred during initialization of the dialog box and to learn more about the error. For more information on this function, see the Windows SDK. -`CPrintDialog` relies on the COMMDLG.DLL file that ships with Windows versions 3.1 and later. +`CPrintDialog` relies on the `COMMDLG.DLL` file that ships with Windows versions 3.1 and later. -To customize the dialog box, derive a class from `CPrintDialog`, provide a custom dialog template, and add a message map to process the notification messages from the extended controls. Any unprocessed messages should be passed on to the base class. Customizing the hook function is not required. +To customize the dialog box, derive a class from `CPrintDialog`, provide a custom dialog template, and add a message map to process the notification messages from the extended controls. Any unprocessed messages should be passed on to the base class. Customizing the hook function isn't required. To process the same message differently depending on whether the dialog box is Print or Print Setup, you must derive a class for each dialog box. You must also override the Windows `AttachOnSetup` function, which handles the creation of a new dialog box when the Print Setup button is selected within a Print dialog box. @@ -85,23 +84,23 @@ For more information on using `CPrintDialog`, see [Common Dialog Classes](../../ ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) -[CCommonDialog](../../mfc/reference/ccommondialog-class.md) +[`CCommonDialog`](../../mfc/reference/ccommondialog-class.md) `CPrintDialog` ## Requirements -**Header:** afxdlgs.h +**Header:** `afxdlgs.h` -## CPrintDialog::CPrintDialog +## `CPrintDialog::CPrintDialog` Constructs either a Windows Print or Print Setup dialog object. @@ -114,28 +113,28 @@ CPrintDialog( ### Parameters -*bPrintSetupOnly*
-Specifies whether the standard Windows Print dialog box or Print Setup dialog box is displayed. Set this parameter to TRUE to display the standard Windows Print Setup dialog box. Set it to FALSE to display the Windows Print dialog box. If *bPrintSetupOnly* is FALSE, a Print Setup option button is still displayed in the Print dialog box. +*`bPrintSetupOnly`*\ +Specifies whether the standard Windows Print dialog box or Print Setup dialog box is displayed. Set this parameter to `TRUE` to display the standard Windows Print Setup dialog box. Set it to `FALSE` to display the Windows Print dialog box. If *`bPrintSetupOnly`* is `FALSE`, a Print Setup option button is still displayed in the Print dialog box. -*dwFlags*
-One or more flags you can use to customize the settings of the dialog box, combined using the bitwise OR operator. For example, the PD_ALLPAGES flag sets the default print range to all pages of the document. See the [PRINTDLG](/windows/win32/api/commdlg/ns-commdlg-printdlga) structure in the Windows SDK for more information on these flags. +*`dwFlags`*\ +One or more flags you can use to customize the settings of the dialog box, combined using the bitwise OR operator. For example, the `PD_ALLPAGES` flag sets the default print range to all pages of the document. See the [`PRINTDLG`](/windows/win32/api/commdlg/ns-commdlg-printdlga) structure in the Windows SDK for more information on these flags. -*pParentWnd*
+*`pParentWnd`*\ A pointer to the dialog box's parent or owner window. ### Remarks This member function only constructs the object. Use the `DoModal` member function to display the dialog box. -Note that when you call the constructor with *bPrintSetupOnly* set to FALSE, the PD_RETURNDC flag is automatically used. After calling `DoModal`, `GetDefaults`, or `GetPrinterDC`, a printer DC will be returned in `m_pd.hDC`. This DC must be freed with a call to [DeleteDC](/windows/win32/api/wingdi/nf-wingdi-deletedc) by the caller of `CPrintDialog`. +Note that when you call the constructor with *`bPrintSetupOnly`* set to `FALSE`, the `PD_RETURNDC` flag is automatically used. After calling `DoModal`, `GetDefaults`, or `GetPrinterDC`, a printer DC will be returned in `m_pd.hDC`. This DC must be freed with a call to [`DeleteDC`](/windows/win32/api/wingdi/nf-wingdi-deletedc) by the caller of `CPrintDialog`. ### Example [!code-cpp[NVC_MFCDocView#174](../../mfc/codesnippet/cpp/cprintdialog-class_1.cpp)] -## CPrintDialog::CreatePrinterDC +## `CPrintDialog::CreatePrinterDC` -Creates a printer device context (DC) from the [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea) and [DEVNAMES](/windows/win32/api/commdlg/ns-commdlg-devnames) structures. +Creates a printer device context (DC) from the [`DEVMODE`](/windows/win32/api/wingdi/ns-wingdi-devmodea) and [`DEVNAMES`](/windows/win32/api/commdlg/ns-commdlg-devnames) structures. ``` HDC CreatePrinterDC(); @@ -153,7 +152,7 @@ This DC is assumed to be the current printer DC, and any other previously obtain [!code-cpp[NVC_MFCDocView#106](../../mfc/codesnippet/cpp/cprintdialog-class_2.cpp)] -## CPrintDialog::DoModal +## `CPrintDialog::DoModal` Displays the Windows common print dialog box and allows the user to select various printing options such as the number of copies, page range, and whether copies should be collated. @@ -163,9 +162,9 @@ virtual INT_PTR DoModal(); ### Return Value -IDOK or IDCANCEL. If IDCANCEL is returned, call the Windows [CommDlgExtendedError](/windows/win32/api/commdlg/nf-commdlg-commdlgextendederror) function to determine whether an error occurred. +`IDOK` or `IDCANCEL`. If `IDCANCEL` is returned, call the Windows [`CommDlgExtendedError`](/windows/win32/api/commdlg/nf-commdlg-commdlgextendederror) function to determine whether an error occurred. -IDOK and IDCANCEL are constants that indicate whether the user selected the OK or Cancel button. +`IDOK` and `IDCANCEL` are constants that indicate whether the user selected the **OK** or **Cancel** button. ### Remarks @@ -173,13 +172,13 @@ If you want to initialize the various print dialog options by setting members of After calling `DoModal`, you can call other member functions to retrieve the settings or information input by the user into the dialog box. -Note that when you call the constructor with *bPrintSetupOnly* set to FALSE, the PD_RETURNDC flag is automatically used. After calling `DoModal`, `GetDefaults`, or `GetPrinterDC`, a printer DC will be returned in `m_pd.hDC`. This DC must be freed with a call to [DeleteDC](/windows/win32/api/wingdi/nf-wingdi-deletedc) by the caller of `CPrintDialog`. +Note that when you call the constructor with *`bPrintSetupOnly`* set to `FALSE`, the `PD_RETURNDC` flag is automatically used. After calling `DoModal`, `GetDefaults`, or `GetPrinterDC`, a printer DC will be returned in `m_pd.hDC`. This DC must be freed with a call to [`DeleteDC`](/windows/win32/api/wingdi/nf-wingdi-deletedc) by the caller of `CPrintDialog`. ### Example - See the example for [CPrintDialog::CreatePrinterDC](#createprinterdc). + See the example for [`CPrintDialog::CreatePrinterDC`](#createprinterdc). -## CPrintDialog::GetCopies +## `CPrintDialog::GetCopies` Retrieves the number of copies requested. @@ -197,9 +196,9 @@ Call this function after calling `DoModal` to retrieve the number of copies requ ### Example - See the example for [CPrintDialog::PrintCollate](#printcollate). + See the example for [`CPrintDialog::PrintCollate`](#printcollate). -## CPrintDialog::GetDefaults +## `CPrintDialog::GetDefaults` Retrieves the device defaults of the default printer without displaying a dialog box. @@ -215,9 +214,9 @@ Nonzero if the function was successful; otherwise 0. The retrieved values are placed in the `m_pd` structure. -In some cases, a call to this function will call the [constructor](#cprintdialog) for `CPrintDialog` with *bPrintSetupOnly* set to FALSE. In these cases, a printer DC and `hDevNames` and `hDevMode` (two handles located in the `m_pd` data member) are automatically allocated. +In some cases, a call to this function will call the [constructor](#cprintdialog) for `CPrintDialog` with *`bPrintSetupOnly`* set to `FALSE`. In these cases, a printer DC and `hDevNames` and `hDevMode` (two handles located in the `m_pd` data member) are automatically allocated. -If the constructor for `CPrintDialog` was called with *bPrintSetupOnly* set to FALSE, this function will not only return `hDevNames` and `hDevMode` located in `m_pd.hDevNames` and `m_pd.hDevMode`) to the caller, but will also return a printer DC in `m_pd.hDC`. It is the responsibility of the caller to delete the printer DC and call the Windows [GlobalFree](/windows/win32/api/winbase/nf-winbase-globalfree) function on the handles when you are finished with the `CPrintDialog` object. +If the constructor for `CPrintDialog` was called with *`bPrintSetupOnly`* set to `FALSE`, this function won't only return `hDevNames` and `hDevMode` located in `m_pd.hDevNames` and `m_pd.hDevMode`) to the caller, but will also return a printer DC in `m_pd.hDC`. It's the responsibility of the caller to delete the printer DC and call the Windows [`GlobalFree`](/windows/win32/api/winbase/nf-winbase-globalfree) function on the handles when you're finished with the `CPrintDialog` object. ### Example @@ -225,7 +224,7 @@ This code fragment gets the default printer's device context and reports to the [!code-cpp[NVC_MFCDocView#107](../../mfc/codesnippet/cpp/cprintdialog-class_3.cpp)] -## CPrintDialog::GetDeviceName +## `CPrintDialog::GetDeviceName` Retrieves the name of the currently selected printer device. @@ -239,15 +238,15 @@ The name of the currently selected printer. ### Remarks -Call this function after calling [DoModal](#domodal) to retrieve the name of the currently selected printer, or after calling [GetDefaults](#getdefaults) to retrieve the current device defaults of the default printer. Use a pointer to the `CString` object returned by `GetDeviceName` as the value of `lpszDeviceName` in a call to [CDC::CreateDC](../../mfc/reference/cdc-class.md#createdc). +Call this function after calling [`DoModal`](#domodal) to retrieve the name of the currently selected printer, or after calling [`GetDefaults`](#getdefaults) to retrieve the current device defaults of the default printer. Use a pointer to the `CString` object returned by `GetDeviceName` as the value of `lpszDeviceName` in a call to [`CDC::CreateDC`](../../mfc/reference/cdc-class.md#createdc). ### Example -This code fragment shows the user's default printer name and the port it is connected to, along with the spooler name the printer uses. The code might show a message box that says, "Your default printer is HP LaserJet IIIP on \\\server\share using winspool.", for example. +This code fragment shows the user's default printer name and the port it's connected to, along with the spooler name the printer uses. The code might show a message box that says, "Your default printer is HP LaserJet IIIP on \\\server\share using winspool.", for example. [!code-cpp[NVC_MFCDocView#108](../../mfc/codesnippet/cpp/cprintdialog-class_4.cpp)] -## CPrintDialog::GetDevMode +## `CPrintDialog::GetDevMode` Retrieves the `DEVMODE` structure. @@ -257,17 +256,17 @@ LPDEVMODE GetDevMode() const; ### Return Value -The [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea) data structure, which contains information about the device initialization and environment of a print driver. You must unlock the memory taken by this structure with the Windows [GlobalUnlock](/windows/win32/api/winbase/nf-winbase-globalunlock) function, which is described in the Windows SDK. +The [`DEVMODE`](/windows/win32/api/wingdi/ns-wingdi-devmodea) data structure, which contains information about the device initialization and environment of a print driver. You must unlock the memory taken by this structure with the Windows [`GlobalUnlock`](/windows/win32/api/winbase/nf-winbase-globalunlock) function, which is described in the Windows SDK. ### Remarks -Call this function after calling [DoModal](#domodal) or [GetDefaults](#getdefaults) to retrieve information about the printing device. +Call this function after calling [`DoModal`](#domodal) or [`GetDefaults`](#getdefaults) to retrieve information about the printing device. ### Example - See the example for [CPrintDialog::PrintCollate](#printcollate). + See the example for [`CPrintDialog::PrintCollate`](#printcollate). -## CPrintDialog::GetDriverName +## `CPrintDialog::GetDriverName` Retrieves the name of the currently selected printer driver. @@ -281,13 +280,13 @@ A `CString` specifying the system-defined driver name. ### Remarks -Call this function after calling [DoModal](#domodal) or [GetDefaults](#getdefaults) to retrieve the name of the system-defined printer device driver. Use a pointer to the `CString` object returned by `GetDriverName` as the value of `lpszDriverName` in a call to [CDC::CreateDC](../../mfc/reference/cdc-class.md#createdc). +Call this function after calling [`DoModal`](#domodal) or [`GetDefaults`](#getdefaults) to retrieve the name of the system-defined printer device driver. Use a pointer to the `CString` object returned by `GetDriverName` as the value of `lpszDriverName` in a call to [`CDC::CreateDC`](../../mfc/reference/cdc-class.md#createdc). ### Example - See the example for [CPrintDialog::GetDeviceName](#getdevicename). + See the example for [`CPrintDialog::GetDeviceName`](#getdevicename). -## CPrintDialog::GetFromPage +## `CPrintDialog::GetFromPage` Retrieves the starting page of the print range. @@ -305,9 +304,9 @@ Call this function after calling `DoModal` to retrieve the starting page number ### Example - See the example for [CPrintDialog::m_pd](#m_pd). + See the example for [`CPrintDialog::m_pd`](#m_pd). -## CPrintDialog::GetPortName +## `CPrintDialog::GetPortName` Retrieves the name of the currently selected printer port. @@ -321,13 +320,13 @@ The name of the currently selected printer port. ### Remarks -Call this function after calling [DoModal](#domodal) or [GetDefaults](#getdefaults) to retrieve the name of the currently selected printer port. +Call this function after calling [`DoModal`](#domodal) or [`GetDefaults`](#getdefaults) to retrieve the name of the currently selected printer port. ### Example See the example for [CPrintDialog::GetDeviceName](#getdevicename). -## CPrintDialog::GetPrinterDC +## `CPrintDialog::GetPrinterDC` Retrieves a handle to the printer device context. @@ -337,17 +336,17 @@ HDC GetPrinterDC() const; ### Return Value -A handle to the printer device context if successful; otherwise NULL. +A handle to the printer device context if successful; otherwise `NULL`. ### Remarks -If the *bPrintSetupOnly* parameter of the `CPrintDialog` constructor was FALSE (indicating that the Print dialog box is displayed), then `GetPrinterDC` returns a handle to the printer device context. You must call the Windows [DeleteDC](/windows/win32/api/wingdi/nf-wingdi-deletedc) function to delete the device context when you are done using it. +If the *`bPrintSetupOnly`* parameter of the `CPrintDialog` constructor was `FALSE` (indicating that the Print dialog box is displayed), then `GetPrinterDC` returns a handle to the printer device context. You must call the Windows [`DeleteDC`](/windows/win32/api/wingdi/nf-wingdi-deletedc) function to delete the device context when you're done using it. ### Example [!code-cpp[NVC_MFCDocView#109](../../mfc/codesnippet/cpp/cprintdialog-class_5.cpp)] -## CPrintDialog::GetToPage +## `CPrintDialog::GetToPage` Retrieves the ending page of the print range. @@ -365,9 +364,9 @@ Call this function after calling `DoModal` to retrieve the ending page number in ### Example - See the example for [CPrintDialog::m_pd](#m_pd). + See the example for [`CPrintDialog::m_pd`](#m_pd). -## CPrintDialog::m_pd +## `CPrintDialog::m_pd` A structure whose members store the characteristics of the dialog object. @@ -377,15 +376,15 @@ PRINTDLG& m_pd; ### Remarks -After constructing a `CPrintDialog` object, you can use `m_pd` to set various aspects of the dialog box before calling the [DoModal](#domodal) member function. For more information on the `m_pd` structure, see [PRINTDLG](/windows/win32/api/commdlg/ns-commdlg-printdlga) in the Windows SDK. +After constructing a `CPrintDialog` object, you can use `m_pd` to set various aspects of the dialog box before calling the [`DoModal`](#domodal) member function. For more information on the `m_pd` structure, see [`PRINTDLG`](/windows/win32/api/commdlg/ns-commdlg-printdlga) in the Windows SDK. -If you modify the `m_pd` data member directly, you will override any default behavior. +If you modify the `m_pd` data member directly, you'll override any default behavior. ### Example [!code-cpp[NVC_MFCDocView#111](../../mfc/codesnippet/cpp/cprintdialog-class_6.cpp)] -## CPrintDialog::PrintAll +## `CPrintDialog::PrintAll` Determines whether to print all pages of the document. @@ -403,9 +402,9 @@ Call this function after calling `DoModal` to determine whether to print all pag ### Example - See the example for [CPrintDialog::m_pd](#m_pd). + See the example for [`CPrintDialog::m_pd`](#m_pd). -## CPrintDialog::PrintCollate +## `CPrintDialog::PrintCollate` Determines whether collated copies are requested. @@ -425,7 +424,7 @@ Call this function after calling `DoModal` to determine whether the printer shou [!code-cpp[NVC_MFCDocView#110](../../mfc/codesnippet/cpp/cprintdialog-class_7.cpp)] -## CPrintDialog::PrintRange +## `CPrintDialog::PrintRange` Determines whether to print only a specified range of pages. @@ -443,9 +442,9 @@ Call this function after calling `DoModal` to determine whether to print only a ### Example - See the example for [CPrintDialog::m_pd](#m_pd). + See the example for [`CPrintDialog::m_pd`](#m_pd). -## CPrintDialog::PrintSelection +## `CPrintDialog::PrintSelection` Determines whether to print only the currently selected items. @@ -463,11 +462,11 @@ Call this function after calling `DoModal` to determine whether to print only th ### Example - See the example for [CPrintDialog::m_pd](#m_pd). + See the example for [`CPrintDialog::m_pd`](#m_pd). ## See also -[MFC Sample DIBLOOK](../../overview/visual-cpp-samples.md)
-[CCommonDialog Class](../../mfc/reference/ccommondialog-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CPrintInfo Structure](../../mfc/reference/cprintinfo-structure.md) +[MFC Sample `DIBLOOK`](../../overview/visual-cpp-samples.md)\ +[`CCommonDialog` Class](../../mfc/reference/ccommondialog-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CPrintInfo` Structure](../../mfc/reference/cprintinfo-structure.md) diff --git a/docs/mfc/reference/cprogressctrl-class.md b/docs/mfc/reference/cprogressctrl-class.md index 322020aea3..d6eaee5292 100644 --- a/docs/mfc/reference/cprogressctrl-class.md +++ b/docs/mfc/reference/cprogressctrl-class.md @@ -4,9 +4,8 @@ title: "CProgressCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CProgressCtrl", "AFXCMN/CProgressCtrl", "AFXCMN/CProgressCtrl::CProgressCtrl", "AFXCMN/CProgressCtrl::Create", "AFXCMN/CProgressCtrl::CreateEx", "AFXCMN/CProgressCtrl::GetBarColor", "AFXCMN/CProgressCtrl::GetBkColor", "AFXCMN/CProgressCtrl::GetPos", "AFXCMN/CProgressCtrl::GetRange", "AFXCMN/CProgressCtrl::GetState", "AFXCMN/CProgressCtrl::GetStep", "AFXCMN/CProgressCtrl::OffsetPos", "AFXCMN/CProgressCtrl::SetBarColor", "AFXCMN/CProgressCtrl::SetBkColor", "AFXCMN/CProgressCtrl::SetMarquee", "AFXCMN/CProgressCtrl::SetPos", "AFXCMN/CProgressCtrl::SetRange", "AFXCMN/CProgressCtrl::SetState", "AFXCMN/CProgressCtrl::SetStep", "AFXCMN/CProgressCtrl::StepIt"] helpviewer_keywords: ["CProgressCtrl [MFC], CProgressCtrl", "CProgressCtrl [MFC], Create", "CProgressCtrl [MFC], CreateEx", "CProgressCtrl [MFC], GetBarColor", "CProgressCtrl [MFC], GetBkColor", "CProgressCtrl [MFC], GetPos", "CProgressCtrl [MFC], GetRange", "CProgressCtrl [MFC], GetState", "CProgressCtrl [MFC], GetStep", "CProgressCtrl [MFC], OffsetPos", "CProgressCtrl [MFC], SetBarColor", "CProgressCtrl [MFC], SetBkColor", "CProgressCtrl [MFC], SetMarquee", "CProgressCtrl [MFC], SetPos", "CProgressCtrl [MFC], SetRange", "CProgressCtrl [MFC], SetState", "CProgressCtrl [MFC], SetStep", "CProgressCtrl [MFC], StepIt"] -ms.assetid: 222630f4-1598-4026-8198-51649b1192ab --- -# CProgressCtrl Class +# `CProgressCtrl` Class Provides the functionality of the Windows common progress bar control. @@ -22,29 +21,29 @@ class CProgressCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CProgressCtrl::CProgressCtrl](#cprogressctrl)|Constructs a `CProgressCtrl` object.| +|[`CProgressCtrl::CProgressCtrl`](#cprogressctrl)|Constructs a `CProgressCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CProgressCtrl::Create](#create)|Creates a progress bar control and attaches it to a `CProgressCtrl` object.| -|[CProgressCtrl::CreateEx](#createex)|Creates a progress control with the specified Windows extended styles and attaches it to a `CProgressCtrl` object.| -|[CProgressCtrl::GetBarColor](#getbarcolor)|Gets the color of the progress indicator bar for the current progress bar control.| -|[CProgressCtrl::GetBkColor](#getbkcolor)|Gets the background color of the current progress bar.| -|[CProgressCtrl::GetPos](#getpos)|Gets the current position of the progress bar.| -|[CProgressCtrl::GetRange](#getrange)|Gets the lower and upper limits of the range of the progress bar control.| -|[CProgressCtrl::GetState](#getstate)|Gets the state of the current progress bar control.| -|[CProgressCtrl::GetStep](#getstep)|Retrieves the step increment for the progress bar of the current progress bar control.| -|[CProgressCtrl::OffsetPos](#offsetpos)|Advances the current position of a progress bar control by a specified increment and redraws the bar to reflect the new position.| -|[CProgressCtrl::SetBarColor](#setbarcolor)|Sets the color of the progress indicator bar in the current progress bar control.| -|[CProgressCtrl::SetBkColor](#setbkcolor)|Sets the background color for the progress bar.| -|[CProgressCtrl::SetMarquee](#setmarquee)|Turns marquee mode on or off for the current progress bar control.| -|[CProgressCtrl::SetPos](#setpos)|Sets the current position for a progress bar control and redraws the bar to reflect the new position.| -|[CProgressCtrl::SetRange](#setrange)|Sets the minimum and maximum ranges for a progress bar control and redraws the bar to reflect the new ranges.| -|[CProgressCtrl::SetState](#setstate)|Sets the state of the current progress bar control.| -|[CProgressCtrl::SetStep](#setstep)|Specifies the step increment for a progress bar control.| -|[CProgressCtrl::StepIt](#stepit)|Advances the current position for a progress bar control by the step increment (see [SetStep](#setstep)) and redraws the bar to reflect the new position.| +|[`CProgressCtrl::Create`](#create)|Creates a progress bar control and attaches it to a `CProgressCtrl` object.| +|[`CProgressCtrl::CreateEx`](#createex)|Creates a progress control with the specified Windows extended styles and attaches it to a `CProgressCtrl` object.| +|[`CProgressCtrl::GetBarColor`](#getbarcolor)|Gets the color of the progress indicator bar for the current progress bar control.| +|[`CProgressCtrl::GetBkColor`](#getbkcolor)|Gets the background color of the current progress bar.| +|[`CProgressCtrl::GetPos`](#getpos)|Gets the current position of the progress bar.| +|[`CProgressCtrl::GetRange`](#getrange)|Gets the lower and upper limits of the range of the progress bar control.| +|[`CProgressCtrl::GetState`](#getstate)|Gets the state of the current progress bar control.| +|[`CProgressCtrl::GetStep`](#getstep)|Retrieves the step increment for the progress bar of the current progress bar control.| +|[`CProgressCtrl::OffsetPos`](#offsetpos)|Advances the current position of a progress bar control by a specified increment and redraws the bar to reflect the new position.| +|[`CProgressCtrl::SetBarColor`](#setbarcolor)|Sets the color of the progress indicator bar in the current progress bar control.| +|[`CProgressCtrl::SetBkColor`](#setbkcolor)|Sets the background color for the progress bar.| +|[`CProgressCtrl::SetMarquee`](#setmarquee)|Turns marquee mode on or off for the current progress bar control.| +|[`CProgressCtrl::SetPos`](#setpos)|Sets the current position for a progress bar control and redraws the bar to reflect the new position.| +|[`CProgressCtrl::SetRange`](#setrange)|Sets the minimum and maximum ranges for a progress bar control and redraws the bar to reflect the new ranges.| +|[`CProgressCtrl::SetState`](#setstate)|Sets the state of the current progress bar control.| +|[`CProgressCtrl::SetStep`](#setstep)|Specifies the step increment for a progress bar control.| +|[`CProgressCtrl::StepIt`](#stepit)|Advances the current position for a progress bar control by the step increment (see [`SetStep`](#setstep)) and redraws the bar to reflect the new position.| ## Remarks @@ -52,23 +51,23 @@ A progress bar control is a window that an application can use to indicate the p A progress bar control has a range and a current position. The range represents the total duration of the operation, and the current position represents the progress the application has made toward completing the operation. The window procedure uses the range and the current position to determine the percentage of the progress bar to fill with the highlight color. Because the range and current position values are expressed as signed integers, the possible range of current position values is from -2,147,483,648 to 2,147,483,647 inclusive. -For more information on using `CProgressCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using CProgressCtrl](../../mfc/using-cprogressctrl.md). +For more information on using `CProgressCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using `CProgressCtrl`](../../mfc/using-cprogressctrl.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CProgressCtrl` ## Requirements -**Header:** afxcmn.h +**Header:** `afxcmn.h` -## CProgressCtrl::CProgressCtrl +## `CProgressCtrl::CProgressCtrl` Constructs a `CProgressCtrl` object. @@ -84,7 +83,7 @@ After constructing the `CProgressCtrl` object, call `CProgressCtrl::Create` to c [!code-cpp[NVC_MFC_CProgressCtrl#1](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_1.cpp)] -## CProgressCtrl::Create +## `CProgressCtrl::Create` Creates a progress bar control and attaches it to a `CProgressCtrl` object. @@ -98,20 +97,20 @@ virtual BOOL Create( ### Parameters -*dwStyle*
-Specifies the progress bar control's style. Apply any combination of window stylesdescribed in [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK, in addition to the following progress bar control styles, to the control: +*`dwStyle`*\ +Specifies the progress bar control's style. Apply any combination of window stylesdescribed in [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK, in addition to the following progress bar control styles, to the control: -- PBS_VERTICAL Displays progress information vertically, top to bottom. Without this flag, the progress bar control displays horizontally, left to right. +- `PBS_VERTICAL` Displays progress information vertically, top to bottom. Without this flag, the progress bar control displays horizontally, left to right. -- PBS_SMOOTH Displays gradual, smooth filling in the progress bar control. Without this flag, the control will fill with blocks. +- `PBS_SMOOTH` Displays gradual, smooth filling in the progress bar control. Without this flag, the control will fill with blocks. -*rect*
-Specifies the progress bar control's size and position. It can be either a [CRect](../../atl-mfc-shared/reference/crect-class.md) object or a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. Because the control must be a child window, the specified coordinates are relative to the client area of the *pParentWnd*. +*`rect`*\ +Specifies the progress bar control's size and position. It can be either a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. Because the control must be a child window, the specified coordinates are relative to the client area of the *`pParentWnd`*. -*pParentWnd*
+*`pParentWnd`*\ Specifies the progress bar control's parent window, usually a `CDialog`. It must not be NULL. -*nID*
+*`nID`*\ Specifies the progress bar control's ID. ### Return Value @@ -126,7 +125,7 @@ You construct a `CProgressCtrl` object in two steps. First, call the constructor [!code-cpp[NVC_MFC_CProgressCtrl#2](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_2.cpp)] -## CProgressCtrl::CreateEx +## `CProgressCtrl::CreateEx` Creates a control (a child window) and associates it with the `CProgressCtrl` object. @@ -141,19 +140,19 @@ virtual BOOL CreateEx( ### Parameters -*dwExStyle*
-Specifies the extended style of the control being created. For a list of extended Windows styles, see the *dwExStyle* parameter for [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwExStyle`*\ +Specifies the extended style of the control being created. For a list of extended Windows styles, see the *`dwExStyle`* parameter for [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. -*dwStyle*
-Specifies the progress bar control's style. Apply any combination of window styles described in [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. +*`dwStyle`*\ +Specifies the progress bar control's style. Apply any combination of window styles described in [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. -*rect*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *pParentWnd*. +*`rect`*\ +A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *`pParentWnd`*. -*pParentWnd*
+*`pParentWnd`*\ A pointer to the window that is the control's parent. -*nID*
+*`nID`*\ The control's child-window ID. ### Return Value @@ -162,9 +161,9 @@ Nonzero if successful; otherwise 0. ### Remarks -Use `CreateEx` instead of [Create](#create) to apply extended Windows styles, specified by the Windows extended style preface **WS_EX_**. +Use `CreateEx` instead of [`Create`](#create) to apply extended Windows styles, specified by the Windows extended style preface **`WS_EX_`**. -## CProgressCtrl::GetBarColor +## `CProgressCtrl::GetBarColor` Gets the color of the progress indicator bar for the current progress bar control. @@ -174,13 +173,13 @@ COLORREF GetBarColor() const; ### Return Value -The color of the current progress bar, represented as a [COLORREF](/windows/win32/gdi/colorref) value, or CLR_DEFAULT if the progress indicator bar color is the default color. +The color of the current progress bar, represented as a [`COLORREF`](/windows/win32/gdi/colorref) value, or `CLR_DEFAULT` if the progress indicator bar color is the default color. ### Remarks -This method sends the [PBM_GETBARCOLOR](/windows/win32/Controls/pbm-getbarcolor) message, which is described in the Windows SDK. +This method sends the [`PBM_GETBARCOLOR`](/windows/win32/Controls/pbm-getbarcolor) message, which is described in the Windows SDK. -## CProgressCtrl::GetBkColor +## `CProgressCtrl::GetBkColor` Gets the background color of the current progress bar. @@ -190,13 +189,13 @@ COLORREF GetBkColor() const; ### Return Value -The background color of the current progress bar, represented as a [COLORREF](/windows/win32/gdi/colorref) value. +The background color of the current progress bar, represented as a [`COLORREF`](/windows/win32/gdi/colorref) value. ### Remarks -This method sends the [PBM_GETBKCOLOR](/windows/win32/Controls/pbm-getbkcolor) message, which is described in the Windows SDK. +This method sends the [`PBM_GETBKCOLOR`](/windows/win32/Controls/pbm-getbkcolor) message, which is described in the Windows SDK. -## CProgressCtrl::GetPos +## `CProgressCtrl::GetPos` Retrieves the current position of the progress bar. @@ -210,13 +209,13 @@ The position of the progress bar control. ### Remarks -The position of the progress bar control is not the physical location on the screen, but rather is between the upper and lower range indicated in [SetRange](#setrange). +The position of the progress bar control isn't the physical location on the screen, but rather is between the upper and lower range indicated in [`SetRange`](#setrange). ### Example [!code-cpp[NVC_MFC_CProgressCtrl#3](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_3.cpp)] -## CProgressCtrl::GetRange +## `CProgressCtrl::GetRange` Gets the current lower and upper limits, or range, of the progress bar control. @@ -228,21 +227,21 @@ void GetRange( ### Parameters -*nLower*
+*`nLower`*\ A reference to an integer receiving the lower limit of the progress bar control. -*nUpper*
+*`nUpper`*\ A reference to an integer receiving the upper limit of the progress bar control. ### Remarks -This function copies the values of the lower and upper limits to the integers referenced by *nLower* and *nUpper*, respectively. +This function copies the values of the lower and upper limits to the integers referenced by *`nLower`* and *`nUpper`*, respectively. ### Example [!code-cpp[NVC_MFC_CProgressCtrl#4](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_4.cpp)] -## CProgressCtrl::GetState +## `CProgressCtrl::GetState` Gets the state of the current progress bar control. @@ -262,7 +261,7 @@ The state of the current progress bar control, which is one of the following val ### Remarks -This method sends the [PBM_GETSTATE](/windows/win32/Controls/pbm-getstate) message, which is described in the Windows SDK. +This method sends the [`PBM_GETSTATE`](/windows/win32/Controls/pbm-getstate) message, which is described in the Windows SDK. ### Example @@ -274,7 +273,7 @@ The next code example retrieves the state of the current progress bar control. [!code-cpp[NVC_MFC_CProgressCtrl_s1#5](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_6.cpp)] -## CProgressCtrl::GetStep +## `CProgressCtrl::GetStep` Retrieves the step increment for the progress bar of the current progress bar control. @@ -288,9 +287,9 @@ The step increment of the progress bar. ### Remarks -The step increment is the amount by which a call to [CProgressCtrl::StepIt](#stepit) increases the current position of the progress bar. +The step increment is the amount by which a call to [`CProgressCtrl::StepIt`](#stepit) increases the current position of the progress bar. -This method sends the [PBM_GETSTEP](/windows/win32/Controls/pbm-getstep) message, which is described in the Windows SDK. +This method sends the [`PBM_GETSTEP`](/windows/win32/Controls/pbm-getstep) message, which is described in the Windows SDK. ### Example @@ -302,9 +301,9 @@ The next code example retrieves the step increment of the current progress bar c [!code-cpp[NVC_MFC_CProgressCtrl_s1#3](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_7.cpp)] -## CProgressCtrl::OffsetPos +## `CProgressCtrl::OffsetPos` -Advances the progress bar control's current position by the increment specified by *nPos* and redraws the bar to reflect the new position. +Advances the progress bar control's current position by the increment specified by *`nPos`* and redraws the bar to reflect the new position. ``` int OffsetPos(int nPos); @@ -312,7 +311,7 @@ int OffsetPos(int nPos); ### Parameters -*nPos*
+*`nPos`*\ Amount to advance the position. ### Return Value @@ -323,7 +322,7 @@ The previous position of the progress bar control. [!code-cpp[NVC_MFC_CProgressCtrl#5](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_8.cpp)] -## CProgressCtrl::SetBarColor +## `CProgressCtrl::SetBarColor` Sets the color of the progress indicator bar in the current progress bar control. @@ -333,18 +332,18 @@ COLORREF SetBarColor(COLORREF clrBar); ### Parameters -*clrBar*\ -[in] A [COLORREF](/windows/win32/gdi/colorref) value that specifies the new color of the progress indicator bar. Specify CLR_DEFAULT to cause the progress bar to use its default color. +*`clrBar`*\ +[in] A [`COLORREF`](/windows/win32/gdi/colorref) value that specifies the new color of the progress indicator bar. Specify `CLR_DEFAULT` to cause the progress bar to use its default color. ### Return Value -The previous color of the progress indicator bar, represented as a [COLORREF](/windows/win32/gdi/colorref) value, or CLR_DEFAULT if the color of the progress indicator bar is the default color. +The previous color of the progress indicator bar, represented as a [`COLORREF`](/windows/win32/gdi/colorref) value, or `CLR_DEFAULT` if the color of the progress indicator bar is the default color. ### Remarks -The `SetBarColor` method sets the progress bar color only if a Windows Vista [theme](/windows/win32/Controls/visual-styles-overview) is not in effect. +The `SetBarColor` method sets the progress bar color only if a Windows Vista [theme](/windows/win32/Controls/visual-styles-overview) isn't in effect. -This method sends the [PBM_SETBARCOLOR](/windows/win32/Controls/pbm-setbarcolor) message, which is described in the Windows SDK. +This method sends the [`PBM_SETBARCOLOR`](/windows/win32/Controls/pbm-setbarcolor) message, which is described in the Windows SDK. ### Example @@ -356,7 +355,7 @@ The next code example changes the color of the progress bar to red, green, blue, [!code-cpp[NVC_MFC_CProgressCtrl_s1#1](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_9.cpp)] -## CProgressCtrl::SetBkColor +## `CProgressCtrl::SetBkColor` Sets the background color for the progress bar. @@ -366,18 +365,18 @@ COLORREF SetBkColor(COLORREF clrNew); ### Parameters -*clrNew*
-A COLORREF value that specifies the new background color. Specify the CLR_DEFAULT value to use the default background color for the progress bar. +*`clrNew`*\ +A `COLORREF` value that specifies the new background color. Specify the `CLR_DEFAULT` value to use the default background color for the progress bar. ### Return Value -The [COLORREF](/windows/win32/gdi/colorref) value indicating the previous background color, or CLR_DEFAULT if the background color is the default color. +The [`COLORREF`](/windows/win32/gdi/colorref) value indicating the previous background color, or `CLR_DEFAULT` if the background color is the default color. ### Example [!code-cpp[NVC_MFC_CProgressCtrl#6](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_10.cpp)] -## CProgressCtrl::SetMarquee +## `CProgressCtrl::SetMarquee` Turns marquee mode on or off for the current progress bar control. @@ -389,21 +388,21 @@ BOOL SetMarquee( ### Parameters -*fMarqueeMode*\ -[in] TRUE to turn marquee mode on, or FALSE to turn marquee mode off. +*`fMarqueeMode`*\ +[in] `TRUE` to turn marquee mode on, or `FALSE` to turn marquee mode off. -*nInterval*\ +*`nInterval`*\ [in] Time in milliseconds between updates of the marquee animation. ### Return Value -This method always returns TRUE. +This method always returns `TRUE`. ### Remarks When marquee mode is turned on, the progress bar is animated and scrolls like a sign on a theater marquee. -This method sends the [PBM_SETMARQUEE](/windows/win32/Controls/pbm-setmarquee) message, which is described in the Windows SDK. +This method sends the [`PBM_SETMARQUEE`](/windows/win32/Controls/pbm-setmarquee) message, which is described in the Windows SDK. ### Example @@ -415,9 +414,9 @@ The next code example starts and stops the marquee scrolling animation. [!code-cpp[NVC_MFC_CProgressCtrl_s1#2](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_11.cpp)] -## CProgressCtrl::SetPos +## `CProgressCtrl::SetPos` -Sets the progress bar control's current position as specified by *nPos* and redraws the bar to reflect the new position. +Sets the progress bar control's current position as specified by *`nPos`* and redraws the bar to reflect the new position. ``` int SetPos(int nPos); @@ -425,7 +424,7 @@ int SetPos(int nPos); ### Parameters -*nPos*
+*`nPos`*\ New position of the progress bar control. ### Return Value @@ -434,13 +433,13 @@ The previous position of the progress bar control. ### Remarks -The position of the progress bar control is not the physical location on the screen, but rather is between the upper and lower range indicated in [SetRange](#setrange). +The position of the progress bar control isn't the physical location on the screen, but rather is between the upper and lower range indicated in [`SetRange`](#setrange). ### Example [!code-cpp[NVC_MFC_CProgressCtrl#7](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_12.cpp)] -## CProgressCtrl::SetRange +## `CProgressCtrl::SetRange` Sets the upper and lower limits of the progress bar control's range and redraws the bar to reflect the new ranges. @@ -456,10 +455,10 @@ void SetRange32( ### Parameters -*nLower*
+*`nLower`*\ Specifies the lower limit of the range (default is zero). -*nUpper*
+*`nUpper`*\ Specifies the upper limit of the range (default is 100). ### Remarks @@ -470,7 +469,7 @@ The member function `SetRange32` sets the 32-bit range for the progress control. [!code-cpp[NVC_MFC_CProgressCtrl#8](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_13.cpp)] -## CProgressCtrl::SetState +## `CProgressCtrl::SetState` Sets the state of the current progress bar control. @@ -493,7 +492,7 @@ The previous state of the current progress bar control. ### Remarks -This method sends the [PBM_SETSTATE](/windows/win32/Controls/pbm-setstate) message, which is described in the Windows SDK. +This method sends the [`PBM_SETSTATE`](/windows/win32/Controls/pbm-setstate) message, which is described in the Windows SDK. ### Example @@ -505,7 +504,7 @@ The next code example sets the state of the current progress bar control to Paus [!code-cpp[NVC_MFC_CProgressCtrl_s1#4](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_14.cpp)] -## CProgressCtrl::SetStep +## `CProgressCtrl::SetStep` Specifies the step increment for a progress bar control. @@ -515,7 +514,7 @@ int SetStep(int nStep); ### Parameters -*nStep*
+*`nStep`*\ New step increment. ### Return Value @@ -532,7 +531,7 @@ The default step increment is 10. [!code-cpp[NVC_MFC_CProgressCtrl#9](../../mfc/reference/codesnippet/cpp/cprogressctrl-class_15.cpp)] -## CProgressCtrl::StepIt +## `CProgressCtrl::StepIt` Advances the current position for a progress bar control by the step increment and redraws the bar to reflect the new position. @@ -554,6 +553,6 @@ The step increment is set by the `CProgressCtrl::SetStep` member function. ## See also -[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
+[MFC Sample `CMNCTRL2`](../../overview/visual-cpp-samples.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/cpropertypage-class.md b/docs/mfc/reference/cpropertypage-class.md index 17f516ce48..cfddd645de 100644 --- a/docs/mfc/reference/cpropertypage-class.md +++ b/docs/mfc/reference/cpropertypage-class.md @@ -4,9 +4,8 @@ title: "CPropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["CPropertyPage", "AFXDLGS/CPropertyPage", "AFXDLGS/CPropertyPage::CPropertyPage", "AFXDLGS/CPropertyPage::CancelToClose", "AFXDLGS/CPropertyPage::Construct", "AFXDLGS/CPropertyPage::GetPSP", "AFXDLGS/CPropertyPage::OnApply", "AFXDLGS/CPropertyPage::OnCancel", "AFXDLGS/CPropertyPage::OnKillActive", "AFXDLGS/CPropertyPage::OnOK", "AFXDLGS/CPropertyPage::OnQueryCancel", "AFXDLGS/CPropertyPage::OnReset", "AFXDLGS/CPropertyPage::OnSetActive", "AFXDLGS/CPropertyPage::OnWizardBack", "AFXDLGS/CPropertyPage::OnWizardFinish", "AFXDLGS/CPropertyPage::OnWizardNext", "AFXDLGS/CPropertyPage::QuerySiblings", "AFXDLGS/CPropertyPage::SetModified", "AFXDLGS/CPropertyPage::m_psp"] helpviewer_keywords: ["CPropertyPage [MFC], CPropertyPage", "CPropertyPage [MFC], CancelToClose", "CPropertyPage [MFC], Construct", "CPropertyPage [MFC], GetPSP", "CPropertyPage [MFC], OnApply", "CPropertyPage [MFC], OnCancel", "CPropertyPage [MFC], OnKillActive", "CPropertyPage [MFC], OnOK", "CPropertyPage [MFC], OnQueryCancel", "CPropertyPage [MFC], OnReset", "CPropertyPage [MFC], OnSetActive", "CPropertyPage [MFC], OnWizardBack", "CPropertyPage [MFC], OnWizardFinish", "CPropertyPage [MFC], OnWizardNext", "CPropertyPage [MFC], QuerySiblings", "CPropertyPage [MFC], SetModified", "CPropertyPage [MFC], m_psp"] -ms.assetid: d9000a21-aa81-4530-85d9-f43432afb4dc --- -# CPropertyPage Class +# `CPropertyPage` Class Represents individual pages of a property sheet, otherwise known as a tab dialog box. @@ -22,59 +21,59 @@ class CPropertyPage : public CDialog |Name|Description| |----------|-----------------| -|[CPropertyPage::CPropertyPage](#cpropertypage)|Constructs a `CPropertyPage` object.| +|[`CPropertyPage::CPropertyPage`](#cpropertypage)|Constructs a `CPropertyPage` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPropertyPage::CancelToClose](#canceltoclose)|Changes the OK button to read Close, and disables the Cancel button, after an unrecoverable change in the page of a modal property sheet.| -|[CPropertyPage::Construct](#construct)|Constructs a `CPropertyPage` object. Use `Construct` if you want to specify your parameters at run time, or if you are using arrays.| -|[CPropertyPage::GetPSP](#getpsp)|Retrieves the Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object.| -|[CPropertyPage::OnApply](#onapply)|Called by the framework when the Apply Now button is clicked.| -|[CPropertyPage::OnCancel](#oncancel)|Called by the framework when the Cancel button is clicked.| -|[CPropertyPage::OnKillActive](#onkillactive)|Called by the framework when the current page is no longer the active page. Perform data validation here.| -|[CPropertyPage::OnOK](#onok)|Called by the framework when the OK, Apply Now, or Close button is clicked.| -|[CPropertyPage::OnQueryCancel](#onquerycancel)|Called by the framework when the Cancel button is clicked, and before the cancel has taken place.| -|[CPropertyPage::OnReset](#onreset)|Called by the framework when the Cancel button is clicked.| -|[CPropertyPage::OnSetActive](#onsetactive)|Called by the framework when the page is made the active page.| -|[CPropertyPage::OnWizardBack](#onwizardback)|Called by the framework when the Back button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::OnWizardFinish](#onwizardfinish)|Called by the framework when the Finish button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::OnWizardNext](#onwizardnext)|Called by the framework when the Next button is clicked while using a wizard-type property sheet.| -|[CPropertyPage::QuerySiblings](#querysiblings)|Forwards the message to each page of the property sheet.| -|[CPropertyPage::SetModified](#setmodified)|Call to activate or deactivate the Apply Now button.| +|[`CPropertyPage::CancelToClose`](#canceltoclose)|Changes the **OK** button to read **Close**, and disables the **Cancel** button, after an unrecoverable change in the page of a modal property sheet.| +|[`CPropertyPage::Construct`](#construct)|Constructs a `CPropertyPage` object. Use `Construct` if you want to specify your parameters at run time, or if you're using arrays.| +|[`CPropertyPage::GetPSP`](#getpsp)|Retrieves the Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object.| +|[`CPropertyPage::OnApply`](#onapply)|Called by the framework when the **Apply Now** button is clicked.| +|[`CPropertyPage::OnCancel`](#oncancel)|Called by the framework when the **Cancel** button is clicked.| +|[`CPropertyPage::OnKillActive`](#onkillactive)|Called by the framework when the current page is no longer the active page. Perform data validation here.| +|[`CPropertyPage::OnOK`](#onok)|Called by the framework when the **OK**, **Apply Now**, or **Close** button is clicked.| +|[`CPropertyPage::OnQueryCancel`](#onquerycancel)|Called by the framework when the **Cancel** button is clicked, and before the cancel has taken place.| +|[`CPropertyPage::OnReset`](#onreset)|Called by the framework when the **Cancel** button is clicked.| +|[`CPropertyPage::OnSetActive`](#onsetactive)|Called by the framework when the page is made the active page.| +|[`CPropertyPage::OnWizardBack`](#onwizardback)|Called by the framework when the **Back** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::OnWizardFinish`](#onwizardfinish)|Called by the framework when the **Finish** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::OnWizardNext`](#onwizardnext)|Called by the framework when the **Next** button is clicked while using a wizard-type property sheet.| +|[`CPropertyPage::QuerySiblings`](#querysiblings)|Forwards the message to each page of the property sheet.| +|[`CPropertyPage::SetModified`](#setmodified)|Call to activate or deactivate the **Apply Now** button.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CPropertyPage::m_psp](#m_psp)|The Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure. Provides access to basic property page parameters.| +|[`CPropertyPage::m_psp`](#m_psp)|The Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure. Provides access to basic property page parameters.| ## Remarks -As with standard dialog boxes, you derive a class from `CPropertyPage` for each page in your property sheet. To use `CPropertyPage`-derived objects, first create a [CPropertySheet](../../mfc/reference/cpropertysheet-class.md) object, and then create an object for each page that goes in the property sheet. Call [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage) for each page in the sheet, and then display the property sheet by calling [CPropertySheet::DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) for a modal property sheet, or [CPropertySheet::Create](../../mfc/reference/cpropertysheet-class.md#create) for a modeless property sheet. +As with standard dialog boxes, you derive a class from `CPropertyPage` for each page in your property sheet. To use `CPropertyPage`-derived objects, first create a [`CPropertySheet`](../../mfc/reference/cpropertysheet-class.md) object, and then create an object for each page that goes in the property sheet. Call [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage) for each page in the sheet, and then display the property sheet by calling [`CPropertySheet::DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) for a modal property sheet, or [`CPropertySheet::Create`](../../mfc/reference/cpropertysheet-class.md#create) for a modeless property sheet. -You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages do not have tabs, and only one property page is visible at a time. Also, instead of having OK and Apply Now buttons, a wizard-type tab dialog box has a Back button, a Next or Finish button, and a Cancel button. +You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages don't have tabs, and only one property page is visible at a time. Also, instead of having **OK** and **Apply Now** buttons, a wizard-type tab dialog box has a **Back** button, a **Next** or **Finish** button, and a **Cancel** button. -For more information on establishing a property sheet as a wizard, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). For more information on using `CPropertyPage` objects, see the article [Property Sheets and Property Pages](../../mfc/property-sheets-and-property-pages-in-mfc.md). +For more information on establishing a property sheet as a wizard, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). For more information on using `CPropertyPage` objects, see the article [Property Sheets and Property Pages](../../mfc/property-sheets-and-property-pages-in-mfc.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CDialog](../../mfc/reference/cdialog-class.md) +[`CDialog`](../../mfc/reference/cdialog-class.md) `CPropertyPage` ## Requirements -**Header:** afxdlgs.h +**Header:** `afxdlgs.h` -## CPropertyPage::CancelToClose +## `CPropertyPage::CancelToClose` Call this function after an unrecoverable change has been made to the data in a page of a modal property sheet. @@ -84,15 +83,15 @@ void CancelToClose(); ### Remarks -This function will change the OK button to Close and disable the Cancel button. This change alerts the user that a change is permanent and the modifications cannot be cancelled. +This function will change the **OK** button to **Close** and disable the **Cancel** button. This change alerts the user that a change is permanent and the modifications can't be canceled. -The `CancelToClose` member function does nothing in a modeless property sheet, because a modeless property sheet does not have a Cancel button by default. +The `CancelToClose` member function does nothing in a modeless property sheet, because a modeless property sheet doesn't have a **Cancel** button by default. ### Example See the example for [CPropertyPage::QuerySiblings](#querysiblings). -## CPropertyPage::Construct +## `CPropertyPage::Construct` Call this member function to construct a `CPropertyPage` object. @@ -120,32 +119,32 @@ void Construct( ### Parameters -*nIDTemplate*
+*`nIDTemplate`*\ ID of the template used for this page. -*nIDCaption*
+*`nIDCaption`*\ ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page. -*lpszTemplateName*
+*`lpszTemplateName`*\ Contains a null-terminated string that is the name of a template resource. -*nIDHeaderTitle*
+*`nIDHeaderTitle`*\ ID of the name to be placed in the title location of the property page header. By default, 0. -*nIDHeaderSubTitle*
+*`nIDHeaderSubTitle`*\ ID of the name to be placed in the subtitle location of the property page header. By default, 0. ### Remarks The object is displayed after all of the following conditions are met: -- The page has been added to a property sheet using [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage). +- The page has been added to a property sheet using [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage). -- The property sheet's [DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) or [Create](../../mfc/reference/cpropertysheet-class.md#create) function has been called. +- The property sheet's [`DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) or [`Create`](../../mfc/reference/cpropertysheet-class.md#create) function has been called. - The user has selected (tabbed to) this page. -Call `Construct` if one of the other class constructors has not been called. The `Construct` member function is flexible because you can leave the parameter statement blank and then specify multiple parameters and construction at any point in your code. +Call `Construct` if one of the other class constructors hasn't been called. The `Construct` member function is flexible because you can leave the parameter statement blank and then specify multiple parameters and construction at any point in your code. You must use `Construct` when you work with arrays, and you must call `Construct` for each member of the array so that the data members are assigned proper values. @@ -153,7 +152,7 @@ You must use `Construct` when you work with arrays, and you must call `Construct [!code-cpp[NVC_MFCDocView#112](../../mfc/codesnippet/cpp/cpropertypage-class_1.cpp)] -## CPropertyPage::CPropertyPage +## `CPropertyPage::CPropertyPage` Constructs a `CPropertyPage` object. @@ -187,41 +186,41 @@ CPropertyPage( ### Parameters -*nIDTemplate*
+*`nIDTemplate`*\ ID of the template used for this page. -*nIDCaption*
+*`nIDCaption`*\ ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page. -*dwSize*
-*lpszTemplateName* -Points to a string containing the name of the template for this page. Cannot be NULL. +*`dwSize`*\ +*`lpszTemplateName`* +Points to a string containing the name of the template for this page. Can't be `NULL`. -*nIDHeaderTitle*
+*`nIDHeaderTitle`*\ ID of the name to be placed in the title location of the property page header. -*nIDHeaderSubTitle*
+*`nIDHeaderSubTitle`*\ ID of the name to be placed in the subtitle location of the property page header. ### Remarks The object is displayed after all of the following conditions are met: -- The page has been added to a property sheet using [CPropertySheet::AddPage](../../mfc/reference/cpropertysheet-class.md#addpage). +- The page has been added to a property sheet using [`CPropertySheet::AddPage`](../../mfc/reference/cpropertysheet-class.md#addpage). -- The property sheet's [DoModal](../../mfc/reference/cpropertysheet-class.md#domodal) or [Create](../../mfc/reference/cpropertysheet-class.md#create) function has been called. +- The property sheet's [`DoModal`](../../mfc/reference/cpropertysheet-class.md#domodal) or [`Create`](../../mfc/reference/cpropertysheet-class.md#create) function has been called. - The user has selected (tabbed to) this page. -If you have multiple parameters (for example, if you are using an array), use [CPropertySheet::Construct](../../mfc/reference/cpropertysheet-class.md#construct) instead of `CPropertyPage`. +If you have multiple parameters (for example, if you're using an array), use [`CPropertySheet::Construct`](../../mfc/reference/cpropertysheet-class.md#construct) instead of `CPropertyPage`. ### Example [!code-cpp[NVC_MFCDocView#113](../../mfc/codesnippet/cpp/cpropertypage-class_2.cpp)] -## CPropertyPage::GetPSP +## `CPropertyPage::GetPSP` -Retrieves the Windows [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object. +Retrieves the Windows [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2) structure associated with the `CPropertyPage` object. ``` const PROPSHEETPAGE& GetPSP() const; @@ -233,9 +232,9 @@ PROPSHEETPAGE& GetPSP(); A reference to the `PROPSHEETPAGE` structure. -## CPropertyPage::m_psp +## `CPropertyPage::m_psp` -`m_psp` is a structure whose members store the characteristics of [PROPSHEETPAGE](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2). +`m_psp` is a structure whose members store the characteristics of [`PROPSHEETPAGE`](/windows/win32/api/prsht/ns-prsht-propsheetpagea_v2). ``` PROPSHEETPAGE m_psp; @@ -243,7 +242,7 @@ PROPSHEETPAGE m_psp; ### Remarks -Use this structure to initialize the appearance of a property page after it is constructed. +Use this structure to initialize the appearance of a property page after it's constructed. For more information on this structure, including a listing of its members, see `PROPSHEETPAGE` in the Windows SDK. @@ -251,9 +250,9 @@ For more information on this structure, including a listing of its members, see [!code-cpp[NVC_MFCDocView#128](../../mfc/codesnippet/cpp/cpropertypage-class_3.cpp)] -## CPropertyPage::OnApply +## `CPropertyPage::OnApply` -This member function is called by the framework when the user chooses the OK or the Apply Now button. +This member function is called by the framework when the user chooses the **OK** or the **Apply Now** button. ``` virtual BOOL OnApply(); @@ -265,21 +264,21 @@ Nonzero if the changes are accepted; otherwise 0. ### Remarks -When the framework calls this function, changes made on all property pages in the property sheet are accepted, the property sheet retains focus, and `OnApply` returns TRUE (the value 1). Before `OnApply` can be called by the framework, you must have called [SetModified](#setmodified) and set its parameter to TRUE. This will activate the Apply Now button as soon as the user makes a change on the property page. +When the framework calls this function, changes made on all property pages in the property sheet are accepted, the property sheet retains focus, and `OnApply` returns `TRUE` (the value 1). Before `OnApply` can be called by the framework, you must have called [`SetModified`](#setmodified) and set its parameter to `TRUE`. This will activate the **Apply Now** button as soon as the user makes a change on the property page. -Override this member function to specify what action your program takes when the user clicks the Apply Now button. When overriding, the function should return TRUE to accept changes and FALSE to prevent changes from taking effect. +Override this member function to specify what action your program takes when the user selects the **Apply Now** button. When overriding, the function should return `TRUE` to accept changes and `FALSE` to prevent changes from taking effect. The default implementation of `OnApply` calls `OnOK`. -For more information about notification messages sent when the user presses the Apply Now or OK button in a property sheet, see [PSN_APPLY](/windows/win32/Controls/psn-apply) in the Windows SDK. +For more information about notification messages sent when the user presses the **Apply Now** or **OK** button in a property sheet, see [`PSN_APPLY`](/windows/win32/Controls/psn-apply) in the Windows SDK. ### Example See the example for [CPropertyPage::OnOK](#onok). -## CPropertyPage::OnCancel +## `CPropertyPage::OnCancel` -This member function is called by the framework when the Cancel button is selected. +This member function is called by the framework when the **Cancel** button is selected. ``` virtual void OnCancel(); @@ -287,13 +286,13 @@ virtual void OnCancel(); ### Remarks -Override this member function to perform Cancel button actions. The default negates any changes that have been made. +Override this member function to perform **Cancel** button actions. The default negates any changes that have been made. ### Example [!code-cpp[NVC_MFCDocView#114](../../mfc/codesnippet/cpp/cpropertypage-class_4.cpp)] -## CPropertyPage::OnKillActive +## `CPropertyPage::OnKillActive` This member function is called by the framework when the page is no longer the active page. @@ -309,17 +308,17 @@ Nonzero if data was updated successfully, otherwise 0. Override this member function to perform special data validation tasks. -The default implementation of this member function copies settings from the controls in the property page to the member variables of the property page. If the data was not updated successfully due to a dialog data validation (DDV) error, the page retains focus. +The default implementation of this member function copies settings from the controls in the property page to the member variables of the property page. If the data wasn't updated successfully due to a dialog data validation (DDV) error, the page retains focus. -After this member function returns successfully, the framework will call the page's [OnOK](#onok) function. +After this member function returns successfully, the framework will call the page's [`OnOK`](#onok) function. ### Example [!code-cpp[NVC_MFCDocView#115](../../mfc/codesnippet/cpp/cpropertypage-class_5.cpp)] -## CPropertyPage::OnOK +## `CPropertyPage::OnOK` -This member function is called by the framework when the user chooses either the OK or the Apply Now button, immediately after the framework calls [OnKillActive](#onkillactive). +This member function is called by the framework when the user chooses either the **OK** or the **Apply Now** button, immediately after the framework calls [`OnKillActive`](#onkillactive). ``` virtual void OnOK(); @@ -327,7 +326,7 @@ virtual void OnOK(); ### Remarks -When the user chooses either the OK or the Apply Now button, the framework receives the [PSN_APPLY](/windows/win32/Controls/psn-apply) notification from the property page. The call to `OnOK` won't be made if you call [CPropertySheet::PressButton](../../mfc/reference/cpropertysheet-class.md#pressbutton) because the property page does not send the notification in that case. +When the user chooses either the **OK** or the **Apply Now** button, the framework receives the [`PSN_APPLY`](/windows/win32/Controls/psn-apply) notification from the property page. The call to `OnOK` won't be made if you call [`CPropertySheet::PressButton`](../../mfc/reference/cpropertysheet-class.md#pressbutton) because the property page doesn't send the notification in that case. Override this member function to implement additional behavior specific to the currently active page when user dismisses the entire property sheet. @@ -337,9 +336,9 @@ The default implementation of this member function marks the page as "clean" to [!code-cpp[NVC_MFCDocView#116](../../mfc/codesnippet/cpp/cpropertypage-class_6.cpp)] -## CPropertyPage::OnQueryCancel +## `CPropertyPage::OnQueryCancel` -This member function is called by the framework when the user clicks the Cancel button and before the cancel action has taken place. +This member function is called by the framework when the user selects the **Cancel** button and before the cancel action has taken place. ``` virtual BOOL OnQueryCancel(); @@ -347,21 +346,21 @@ virtual BOOL OnQueryCancel(); ### Return Value -Returns FALSE to prevent the cancel operation or TRUE to allow it. +Returns `FALSE` to prevent the cancel operation or `TRUE` to allow it. ### Remarks -Override this member function to specify an action the program takes when the user clicks the Cancel button. +Override this member function to specify an action the program takes when the user selects the **Cancel** button. -The default implementation of `OnQueryCancel` returns TRUE. +The default implementation of `OnQueryCancel` returns `TRUE`. ### Example [!code-cpp[NVC_MFCDocView#117](../../mfc/codesnippet/cpp/cpropertypage-class_7.cpp)] -## CPropertyPage::OnReset +## `CPropertyPage::OnReset` -This member function is called by the framework when the user chooses the Cancel button. +This member function is called by the framework when the user chooses the **Cancel** button. ``` virtual void OnReset(); @@ -369,9 +368,9 @@ virtual void OnReset(); ### Remarks -When the framework calls this function, changes to all property pages that were made by the user previously choosing the Apply Now button are discarded, and the property sheet retains focus. +When the framework calls this function, changes to all property pages that were made by the user previously choosing the **Apply Now** button are discarded, and the property sheet retains focus. -Override this member function to specify what action the program takes when the user clicks the Cancel button. +Override this member function to specify what action the program takes when the user selects the **Cancel** button. The default implementation of `OnReset` does nothing. @@ -379,7 +378,7 @@ The default implementation of `OnReset` does nothing. See the example for [CPropertyPage::OnCancel](#oncancel). -## CPropertyPage::OnSetActive +## `CPropertyPage::OnSetActive` This member function is called by the framework when the page is chosen by the user and becomes the active page. @@ -401,9 +400,9 @@ The default implementation creates the window for the page, if not previously cr See the example for [CPropertySheet::SetFinishText](../../mfc/reference/cpropertysheet-class.md#setfinishtext). -## CPropertyPage::OnWizardBack +## `CPropertyPage::OnWizardBack` -This member function is called by the framework when the user clicks on the Back button in a wizard. +This member function is called by the framework when the user selects the **Back** button in a wizard. ``` virtual LRESULT OnWizardBack(); @@ -415,17 +414,17 @@ virtual LRESULT OnWizardBack(); ### Remarks -Override this member function to specify some action the user must take when the Back button is pressed. +Override this member function to specify some action the user must take when the **Back** button is pressed. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example [!code-cpp[NVC_MFCDocView#118](../../mfc/codesnippet/cpp/cpropertypage-class_8.cpp)] -## CPropertyPage::OnWizardFinish +## `CPropertyPage::OnWizardFinish` -This member function is called by the framework when the user clicks on the Finish button in a wizard. +This member function is called by the framework when the user selects the **Finish** button in a wizard. ``` virtual BOOL OnWizardFinish(); @@ -437,27 +436,27 @@ Nonzero if the property sheet is destroyed when the wizard finishes; otherwise z ### Remarks -When a user clicks the **Finish** button in a wizard, the framework calls this function; when `OnWizardFinish` returns TRUE (a nonzero value), the property sheet is able to be destroyed (but is not actually destroyed). Call `DestroyWindow` to destroy the property sheet. Do not call `DestroyWindow` from `OnWizardFinish`; doing so will cause heap corruption or other errors. +When a user selects the **Finish** button in a wizard, the framework calls this function; when `OnWizardFinish` returns `TRUE` (a nonzero value), the property sheet is able to be destroyed (but isn't actually destroyed). Call `DestroyWindow` to destroy the property sheet. Don't call `DestroyWindow` from `OnWizardFinish`; doing so will cause heap corruption or other errors. -You can override this member function to specify some action the user must take when the Finish button is pressed. When overriding this function, return FALSE to prevent the property sheet from being destroyed. +You can override this member function to specify some action the user must take when the **Finish** button is pressed. When overriding this function, return `FALSE` to prevent the property sheet from being destroyed. -For more information about notification messages sent when the user presses the Finish button in a wizard property sheet, see [PSN_WIZFINISH](/windows/win32/Controls/psn-wizfinish) in the Windows SDK. +For more information about notification messages sent when the user presses the **Finish** button in a wizard property sheet, see [`PSN_WIZFINISH`](/windows/win32/Controls/psn-wizfinish) in the Windows SDK. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example [!code-cpp[NVC_MFCDocView#119](../../mfc/codesnippet/cpp/cpropertypage-class_9.cpp)] - +  [!code-cpp[NVC_MFCDocView#120](../../mfc/codesnippet/cpp/cpropertypage-class_10.cpp)] - +  [!code-cpp[NVC_MFCDocView#121](../../mfc/codesnippet/cpp/cpropertypage-class_11.cpp)] - +  [!code-cpp[NVC_MFCDocView#122](../../mfc/codesnippet/cpp/cpropertypage-class_12.cpp)] -## CPropertyPage::OnWizardNext +## `CPropertyPage::OnWizardNext` -This member function is called by the framework when the user clicks on the Next button in a wizard. +This member function is called by the framework when the user selects the **Next** button in a wizard. ``` virtual LRESULT OnWizardNext(); @@ -469,15 +468,15 @@ virtual LRESULT OnWizardNext(); ### Remarks -Override this member function to specify some action the user must take when the Next button is pressed. +Override this member function to specify some action the user must take when the **Next** button is pressed. -For more information on how to make a wizard-type property sheet, see [CPropertySheet::SetWizardMode](../../mfc/reference/cpropertysheet-class.md#setwizardmode). +For more information on how to make a wizard-type property sheet, see [`CPropertySheet::SetWizardMode`](../../mfc/reference/cpropertysheet-class.md#setwizardmode). ### Example [!code-cpp[NVC_MFCDocView#123](../../mfc/codesnippet/cpp/cpropertypage-class_13.cpp)] -## CPropertyPage::QuerySiblings +## `CPropertyPage::QuerySiblings` Call this member function to forward a message to each page in the property sheet. @@ -489,10 +488,10 @@ LRESULT QuerySiblings( ### Parameters -*wParam*
+*`wParam`*\ Specifies additional message-dependent information. -*lParam*
+*`lParam`*\ Specifies additional message-dependent information ### Return Value @@ -501,19 +500,19 @@ The nonzero value from a page in the property sheet, or 0 if all pages return a ### Remarks -If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. +If a page returns a nonzero value, the property sheet doesn't send the message to subsequent pages. ### Example [!code-cpp[NVC_MFCDocView#124](../../mfc/codesnippet/cpp/cpropertypage-class_14.cpp)] - +  [!code-cpp[NVC_MFCDocView#125](../../mfc/codesnippet/cpp/cpropertypage-class_15.cpp)] - +  [!code-cpp[NVC_MFCDocView#126](../../mfc/codesnippet/cpp/cpropertypage-class_16.cpp)] -## CPropertyPage::SetModified +## `CPropertyPage::SetModified` -Call this member function to enable or disable the Apply Now button, based on whether the settings in the property page should be applied to the appropriate external object. +Call this member function to enable or disable the **Apply Now** button, based on whether the settings in the property page should be applied to the appropriate external object. ```cpp void SetModified(BOOL bChanged = TRUE); @@ -521,12 +520,12 @@ void SetModified(BOOL bChanged = TRUE); ### Parameters -*bChanged*
-TRUE to indicate that the property page settings have been modified since the last time they were applied; FALSE to indicate that the property page settings have been applied, or should be ignored. +*`bChanged`*\ +`TRUE` to indicate that the property page settings have been modified since the last time they were applied; `FALSE` to indicate that the property page settings have been applied, or should be ignored. ### Remarks -The framework keeps track of which pages are "dirty," that is, property pages for which you have called `SetModified( TRUE )`. The Apply Now button will always be enabled if you call `SetModified( TRUE )` for one of the pages. The Apply Now button will be disabled when you call `SetModified( FALSE )` for one of the pages, but only if none of the other pages is "dirty." +The framework keeps track of which pages are "dirty," that is, property pages for which you have called `SetModified( TRUE )`. The **Apply Now** button will always be enabled if you call `SetModified( TRUE )` for one of the pages. The **Apply Now** button will be disabled when you call `SetModified( FALSE )` for one of the pages, but only if none of the other pages is "dirty." ### Example @@ -534,11 +533,10 @@ The framework keeps track of which pages are "dirty," that is, property pages fo ## See also -[MFC Sample CMNCTRL1](../../overview/visual-cpp-samples.md)
-[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)
-[MFC Sample PROPDLG](../../overview/visual-cpp-samples.md)
-[MFC Sample SNAPVW](../../overview/visual-cpp-samples.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CPropertySheet Class](../../mfc/reference/cpropertysheet-class.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md) +[MFC Sample `CMNCTRL1`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `CMNCTRL2`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `PROPDLG`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `SNAPVW`](../../overview/visual-cpp-samples.md)\ +[`CDialog` Class](../../mfc/reference/cdialog-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md) diff --git a/docs/mfc/reference/cpropertysheet-class.md b/docs/mfc/reference/cpropertysheet-class.md index 0ab6b76fe9..000ec9eb63 100644 --- a/docs/mfc/reference/cpropertysheet-class.md +++ b/docs/mfc/reference/cpropertysheet-class.md @@ -315,7 +315,7 @@ To display a modal property sheet, call [`DoModal`](#domodal) instead. ### Example [!code-cpp[NVC_MFCDocView#132](../../mfc/codesnippet/cpp/cpropertysheet-class_4.cpp)] - +  [!code-cpp[NVC_MFCDocView#133](../../mfc/codesnippet/cpp/cpropertysheet-class_5.cpp)] ## `CPropertySheet::DoModal` @@ -750,9 +750,9 @@ If you want to change the text on the Finish button or hide the Next and Back bu A `CPropertySheet` has three wizard property pages: `CStylePage`, `CColorPage`, and `CShapePage`. The code fragment below shows how to enable and disable the **Back** and **Next** buttons on the wizard property page. [!code-cpp[NVC_MFCDocView#140](../../mfc/codesnippet/cpp/cpropertysheet-class_13.cpp)] - +  [!code-cpp[NVC_MFCDocView#141](../../mfc/codesnippet/cpp/cpropertysheet-class_14.cpp)] - +  [!code-cpp[NVC_MFCDocView#138](../../mfc/codesnippet/cpp/cpropertysheet-class_11.cpp)] ## `CPropertySheet::SetWizardMode` diff --git a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md index b22221af98..06aa373199 100644 --- a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md +++ b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md @@ -4,11 +4,10 @@ title: "Creating a Web Browser-Style MFC Application" ms.date: "06/25/2018" f1_keywords: ["vc.appwiz.mfcweb.project"] helpviewer_keywords: ["MFC, Web applications", "Web browsers, creating from MFC architecture", "Web browsers", "Web applications [MFC], creating"] -ms.assetid: 257f8c03-33c3-428c-832e-0b70aff6168d --- # Creating a Web Browser-Style MFC Application -A Web browser-style application can access information from the Internet (such as HTML or active documents) or an intranet, as well as folders in the local file system and on a network. By deriving the application's view class from [CHtmlView](../../mfc/reference/chtmlview-class.md), effectively you make the application a Web browser by providing the view with the WebBrowser control. +A Web browser-style application can access information from the Internet (such as HTML or active documents) or an intranet, as well as folders in the local file system and on a network. By deriving the application's view class from [`CHtmlView`](../../mfc/reference/chtmlview-class.md), effectively you make the application a Web browser by providing the view with the WebBrowser control. ## To create a Web browser application based on the MFC document/view architecture @@ -20,16 +19,16 @@ A Web browser-style application can access information from the Internet (such a 1. Select any other options you want built into the skeleton application. -1. Click **Finish**. +1. Select **Finish**. The WebBrowser control supports Web browsing through hyperlinks and Uniform Resource Locator (URL) navigation. The control maintains a history list that allows the user to browse forward and backward through previously browsed sites, folders, and documents. The control directly handles the navigation, hyperlinks, history lists, favorites, and security. Applications can use the WebBrowser control as an active document container to host active documents as well. Thus, richly formatted documents such as Microsoft Excel spreadsheets or Word documents can be opened and edited in place from within the WebBrowser control. The WebBrowser control is also an ActiveX control container that can host any ActiveX control. > [!NOTE] > The WebBrowser ActiveX control (and therefore `CHtmlView`) is available only to applications running under Windows versions in which Internet Explorer 4.0 or later has been installed. -Because `CHtmlView` simply implements the Microsoft Web browser control, its support for printing is not like other [CView](../../mfc/reference/cview-class.md)-derived classes. Rather, the WebBrowser control implements the printer user interface and printing. As a result, `CHtmlView` does not support print preview, and the framework does not provide for other printing support functions: for example, [CView::OnPreparePrinting](../../mfc/reference/cview-class.md#onprepareprinting), [CView::OnBeginPrinting](../../mfc/reference/cview-class.md#onbeginprinting), and [CView::OnEndPrinting](../../mfc/reference/cview-class.md#onendprinting), which are available in other MFC applications. +Because `CHtmlView` simply implements the Microsoft Web browser control, its support for printing isn't like other [`CView`](../../mfc/reference/cview-class.md)-derived classes. Rather, the WebBrowser control implements the printer user interface and printing. As a result, `CHtmlView` doesn't support print preview, and the framework doesn't provide for other printing support functions: for example, [`CView::OnPreparePrinting`](../../mfc/reference/cview-class.md#onprepareprinting), [`CView::OnBeginPrinting`](../../mfc/reference/cview-class.md#onbeginprinting), and [`CView::OnEndPrinting`](../../mfc/reference/cview-class.md#onendprinting), which are available in other MFC applications. -`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [OnInitialUpdate](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Microsoft Visual C++ Web site: +`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [`OnInitialUpdate`](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Microsoft Visual C++ Web site: ```cpp void CWebView::OnInitialUpdate() @@ -38,13 +37,13 @@ void CWebView::OnInitialUpdate() // TODO: This code navigates to a popular spot on the web. // Change the code to go where you'd like. - Navigate2(_T("http://www.docs.microsoft.com/"), + Navigate2(_T("https://learn.microsoft.com/"), NULL, NULL); } ``` -You can replace this site with one of your own, or you can use the [LoadFromResource](../../mfc/reference/chtmlview-class.md#loadfromresource) member function to open an HTML page that resides in the project's resource script as the default content for the view. For example: +You can replace this site with one of your own, or you can use the [`LoadFromResource`](../../mfc/reference/chtmlview-class.md#loadfromresource) member function to open an HTML page that resides in the project's resource script as the default content for the view. For example: ```cpp void CWebView::OnInitialUpdate() @@ -59,8 +58,8 @@ void CWebView::OnInitialUpdate() ## See also -[MFC Sample MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet)
-[MFC Application Wizard](../../mfc/reference/mfc-application-wizard.md)
-[Set compiler and build properties](../../build/working-with-project-properties.md)
-[Property Pages](../../build/reference/property-pages-visual-cpp.md)
+[MFC Sample MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet)\ +[MFC Application Wizard](../../mfc/reference/mfc-application-wizard.md)\ +[Set compiler and build properties](../../build/working-with-project-properties.md)\ +[Property Pages](../../build/reference/property-pages-visual-cpp.md)\ [Set compiler and build properties](../../build/working-with-project-properties.md) diff --git a/docs/mfc/reference/creating-an-mfc-activex-control.md b/docs/mfc/reference/creating-an-mfc-activex-control.md index 8dd33f2f43..af40e85640 100644 --- a/docs/mfc/reference/creating-an-mfc-activex-control.md +++ b/docs/mfc/reference/creating-an-mfc-activex-control.md @@ -28,7 +28,7 @@ The easiest way to create an MFC ActiveX control is to use the [MFC ActiveX Cont After you have created your project, you can view the files created in **Solution Explorer**. For more information about the files the wizard creates for your project, see the project-generated file ReadMe.txt. For more information about the file types, see [File Types Created for Visual Studio C++ projects](../../build/reference/file-types-created-for-visual-cpp-projects.md). -After you have created your project, you can use the code wizards to add [functions](../../ide/adding-a-member-function-visual-cpp.md#add-member-function-wizard), [variables](../../ide/adding-a-member-variable-visual-cpp.md#add-member-variable-wizard), [events](../../ide/adding-an-event-visual-cpp.md#add-event-wizard), [properties](../../ide/adding-a-property-visual-cpp.md#names-add-property-wizard), and [methods](../../ide/adding-a-method-visual-cpp.md#add-method-wizard). For more information about customizing your ActiveX control, see [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md). +After you have created your project, you can use the code wizards to add [functions](../../ide/adding-a-member-function-visual-cpp.md#add-member-function-wizard), [variables](../../ide/adding-a-member-variable-visual-cpp.md#add-member-variable-wizard), [events](../../ide/adding-an-event-visual-cpp.md#add-event-wizard), [properties](../../ide/adding-a-property-visual-cpp.md), and [methods](../../ide/adding-a-method-visual-cpp.md). For more information about customizing your ActiveX control, see [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md). ## See also diff --git a/docs/mfc/reference/creating-an-mfc-application.md b/docs/mfc/reference/creating-an-mfc-application.md index eebadcf949..5a981ca05c 100644 --- a/docs/mfc/reference/creating-an-mfc-application.md +++ b/docs/mfc/reference/creating-an-mfc-application.md @@ -1,9 +1,8 @@ --- description: "Learn more about: Creating an MFC Application" title: "Creating an MFC Application" -ms.date: "08/28/2019" +ms.date: 02/11/2023 helpviewer_keywords: ["applications [MFC]", "MFC, creating applications", "MFC applications"] -ms.assetid: b8b8aa08-9c49-404c-8078-b42079ac18f0 --- # Creating an MFC Application @@ -32,35 +31,40 @@ The easiest way to create an MFC application is to use the MFC Application Wizar 1. Modify the defaults as needed, then press **Create** to open the **MFC Application Wizard**. 1. Modify the configuration values as needed, then press **Finish**. -For more information, see [Creating a Forms-Based MFC Application](creating-a-forms-based-mfc-application.md). +For more information, see [Creating a forms-based MFC application](creating-a-forms-based-mfc-application.md). -![Screenshot of the MFC Application wizard in Visual Studios 2019.](media/mfc-app-wizard.png) +:::image type="complex" source="media/mfc-app-wizard.png" alt-text="Screenshot of the MFC Application wizard in Visual Studios 2022."::: +The dialog shows options for the application type, which is set to single document. Application type options include tabbed documents, which is checked, and document/view architecture support, which is checked. There are other options for project style, resource language, and so on, that are set to their default values. +:::image-end::: ## To create an MFC console application An MFC console application is a command-line program that uses MFC libraries but runs in the console window. 1. From the main menu, choose **File** > **New** > **Project**. -1. Enter "Desktop" into the search box and then choose **Windows Desktop Wizard** from the result list. -1. Modify the project name as needed, then press **Next** to open the **Windows Desktop Wizard**. -1. Check the **MFC Headers** box and set other values as needed, then press **Finish**. - -![Screenshot of the Windows Desktop wizard in Visual Studios 2019.](media/windows-desktop-wizard.png) +1. Enter "Desktop" into the search box and then choose **Windows Desktop Wizard** from the result list, then press **Next**. +1. Modify the project name and location as needed, then press **Create** to open the **Windows Desktop Wizard**. +1. Check the **MFC Headers** box and set other values as needed, then press **OK**. +:::image type="complex" source="media/windows-desktop-wizard.png" alt-text="Screenshot of the Windows Desktop Project wizard in Visual Studios 2022."::: +The dialog shows the application type, set to Console Application (.exe). Under Additional Options, Precompiled header is checked as is MFC headers. Precompiled header is checked automatically when MFC headers is checked. +:::image-end::: ::: moniker-end ::: moniker range="=msvc-150" ## To create an MFC forms or dialog-based application -1. From the main menu, choose **File** > **New** > **Project**. -1. Under the **Installed** templates, choose **Visual C++** > **MFC/ATL**. If you don't see these, use the Visual Studio Installer to add them. -1. Choose **MFC Application** from the center pane. -1. Modify the configuration values as needed, then press **Finish**. +1. From the Visual Studio main menu, choose **File** > **New** > **Project**. +1. Under the **Installed** templates, choose **Visual C++** > **MFC/ATL**. If you don't see these, use the Visual Studio Installer to add MFC/ATL functionality. You can access the installer from the Visual Studio menu via **Tools** > **Get Tools and Features...** In the installer, select **Individual components** and search for **mfc** and then select the appropriate library for your machine such as **Visual C++ MFC for x86 and x64 with Spectre Mitigations**. +1. Choose **MFC App** from the center pane. +1. Modify the configuration values as needed, then press **OK**. For more information, see [Creating a Forms-Based MFC Application](creating-a-forms-based-mfc-application.md). -![Screenshot of the MFC Application wizard in Visual Studios 2017.](media/mfc-app-wizard.png) +:::image type="complex" source="media/mfc-app-wizard.png" alt-text="Screenshot of the MFC Application wizard in Visual Studios 2017."::: +The dialog shows the various settings set to their default, such as the application type set to console application.exe; precompiled header is checked and security development lifecycle (SDL) is checked. Add common headers for: MFC isn't checked, but you select it. +:::image-end::: ## To create an MFC console application @@ -68,11 +72,13 @@ An MFC console application is a command-line program that uses MFC libraries but 1. From the main menu, choose **File** > **New** > **Project**. 1. Under the **Installed** templates, choose **Visual C++** > **Windows Desktop**. -1. Choose **Windows Desktop Wizard** from the center pane. +1. From the center pane, choose **Windows Desktop Wizard**. 1. Modify the project name as needed, then press **OK** to open the **Windows Desktop Wizard**. -1. Check the **MFC Headers** box and set other values as needed, then press **Finish**. +1. Check the **MFC Headers** box and set other values as needed, then press **OK**. -![Screenshot of the Windows Desktop wizard in Visual Studios 2017.](media/windows-desktop-wizard-2017.png) +:::image type="complex" source="media/windows-desktop-wizard.png" alt-text="Screenshot of the Windows Desktop Project wizard in Visual Studios 2017."::: +The dialog shows the application type set to Console Application (.exe). Under additional options, Precompiled header is checked and MFC headers is checked. +:::image-end::: ::: moniker-end @@ -87,7 +93,9 @@ An MFC console application is a command-line program that uses MFC libraries but For more information, see [Creating a Forms-Based MFC Application](creating-a-forms-based-mfc-application.md). -![Screenshot of the MFC Application wizard in Visual Studios 2015.](media/mfc-app-wizard-2015.png) +:::image type="complex" source="media/mfc-app-wizard-2015.png" alt-text="Screenshot of the MFC Application wizard in Visual Studios 2015."::: +The dialog lists the current project settings such as: tabbed multiple document interface, no database support, no compound document support, customizable menu bar and toolbar interface, Visual Studio 2008 application appearance, Visual Studio project style, and restart manager support. +:::image-end::: ## To create an MFC console application @@ -105,5 +113,5 @@ Once your project is created, you can view the files created in **Solution Explo ## See also -[Adding Functionality with Code Wizards](../../ide/adding-functionality-with-code-wizards-cpp.md)
+[Adding Functionality with Code Wizards](../../ide/adding-functionality-with-code-wizards-cpp.md)\ [Property Pages](../../build/reference/property-pages-visual-cpp.md) diff --git a/docs/mfc/reference/crebarctrl-class.md b/docs/mfc/reference/crebarctrl-class.md index 5dc690832f..7d66ed8b7f 100644 --- a/docs/mfc/reference/crebarctrl-class.md +++ b/docs/mfc/reference/crebarctrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CReBarCtrl Class" title: "CReBarCtrl Class" -ms.date: "11/19/2018" +description: "Learn more about: CReBarCtrl Class" +ms.date: 11/19/2018 f1_keywords: ["CReBarCtrl", "AFXCMN/CReBarCtrl", "AFXCMN/CReBarCtrl::CReBarCtrl", "AFXCMN/CReBarCtrl::BeginDrag", "AFXCMN/CReBarCtrl::Create", "AFXCMN/CReBarCtrl::CreateEx", "AFXCMN/CReBarCtrl::DeleteBand", "AFXCMN/CReBarCtrl::DragMove", "AFXCMN/CReBarCtrl::EndDrag", "AFXCMN/CReBarCtrl::GetBandBorders", "AFXCMN/CReBarCtrl::GetBandCount", "AFXCMN/CReBarCtrl::GetBandInfo", "AFXCMN/CReBarCtrl::GetBandMargins", "AFXCMN/CReBarCtrl::GetBarHeight", "AFXCMN/CReBarCtrl::GetBarInfo", "AFXCMN/CReBarCtrl::GetBkColor", "AFXCMN/CReBarCtrl::GetColorScheme", "AFXCMN/CReBarCtrl::GetDropTarget", "AFXCMN/CReBarCtrl::GetExtendedStyle", "AFXCMN/CReBarCtrl::GetImageList", "AFXCMN/CReBarCtrl::GetPalette", "AFXCMN/CReBarCtrl::GetRect", "AFXCMN/CReBarCtrl::GetRowCount", "AFXCMN/CReBarCtrl::GetRowHeight", "AFXCMN/CReBarCtrl::GetTextColor", "AFXCMN/CReBarCtrl::GetToolTips", "AFXCMN/CReBarCtrl::HitTest", "AFXCMN/CReBarCtrl::IDToIndex", "AFXCMN/CReBarCtrl::InsertBand", "AFXCMN/CReBarCtrl::MaximizeBand", "AFXCMN/CReBarCtrl::MinimizeBand", "AFXCMN/CReBarCtrl::MoveBand", "AFXCMN/CReBarCtrl::PushChevron", "AFXCMN/CReBarCtrl::RestoreBand", "AFXCMN/CReBarCtrl::SetBandInfo", "AFXCMN/CReBarCtrl::SetBandWidth", "AFXCMN/CReBarCtrl::SetBarInfo", "AFXCMN/CReBarCtrl::SetBkColor", "AFXCMN/CReBarCtrl::SetColorScheme", "AFXCMN/CReBarCtrl::SetExtendedStyle", "AFXCMN/CReBarCtrl::SetImageList", "AFXCMN/CReBarCtrl::SetOwner", "AFXCMN/CReBarCtrl::SetPalette", "AFXCMN/CReBarCtrl::SetTextColor", "AFXCMN/CReBarCtrl::SetToolTips", "AFXCMN/CReBarCtrl::SetWindowTheme", "AFXCMN/CReBarCtrl::ShowBand", "AFXCMN/CReBarCtrl::SizeToRect"] helpviewer_keywords: ["CReBarCtrl [MFC], CReBarCtrl", "CReBarCtrl [MFC], BeginDrag", "CReBarCtrl [MFC], Create", "CReBarCtrl [MFC], CreateEx", "CReBarCtrl [MFC], DeleteBand", "CReBarCtrl [MFC], DragMove", "CReBarCtrl [MFC], EndDrag", "CReBarCtrl [MFC], GetBandBorders", "CReBarCtrl [MFC], GetBandCount", "CReBarCtrl [MFC], GetBandInfo", "CReBarCtrl [MFC], GetBandMargins", "CReBarCtrl [MFC], GetBarHeight", "CReBarCtrl [MFC], GetBarInfo", "CReBarCtrl [MFC], GetBkColor", "CReBarCtrl [MFC], GetColorScheme", "CReBarCtrl [MFC], GetDropTarget", "CReBarCtrl [MFC], GetExtendedStyle", "CReBarCtrl [MFC], GetImageList", "CReBarCtrl [MFC], GetPalette", "CReBarCtrl [MFC], GetRect", "CReBarCtrl [MFC], GetRowCount", "CReBarCtrl [MFC], GetRowHeight", "CReBarCtrl [MFC], GetTextColor", "CReBarCtrl [MFC], GetToolTips", "CReBarCtrl [MFC], HitTest", "CReBarCtrl [MFC], IDToIndex", "CReBarCtrl [MFC], InsertBand", "CReBarCtrl [MFC], MaximizeBand", "CReBarCtrl [MFC], MinimizeBand", "CReBarCtrl [MFC], MoveBand", "CReBarCtrl [MFC], PushChevron", "CReBarCtrl [MFC], RestoreBand", "CReBarCtrl [MFC], SetBandInfo", "CReBarCtrl [MFC], SetBandWidth", "CReBarCtrl [MFC], SetBarInfo", "CReBarCtrl [MFC], SetBkColor", "CReBarCtrl [MFC], SetColorScheme", "CReBarCtrl [MFC], SetExtendedStyle", "CReBarCtrl [MFC], SetImageList", "CReBarCtrl [MFC], SetOwner", "CReBarCtrl [MFC], SetPalette", "CReBarCtrl [MFC], SetTextColor", "CReBarCtrl [MFC], SetToolTips", "CReBarCtrl [MFC], SetWindowTheme", "CReBarCtrl [MFC], ShowBand", "CReBarCtrl [MFC], SizeToRect"] -ms.assetid: 154570d7-e48c-425d-8c7e-c64542bcb4cc --- # CReBarCtrl Class @@ -337,7 +336,7 @@ void GetBandMargins(PMARGINS pMargins); ### Parameters *pMargins*
-A pointer to a [MARGINS](/windows/win32/api/uxtheme/ns-uxtheme-margins)structure that will receive the information. +A pointer to a [MARGINS](/windows/win32/api/uxtheme/ns-uxtheme-margins) structure that will receive the information. ### Remarks diff --git a/docs/mfc/reference/crecordset-class.md b/docs/mfc/reference/crecordset-class.md index 92a816b386..4029567072 100644 --- a/docs/mfc/reference/crecordset-class.md +++ b/docs/mfc/reference/crecordset-class.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: CRecordset Class" title: "CRecordset Class" -ms.date: "11/04/2016" +description: "Learn more about: CRecordset Class" +ms.date: "05/11/2022" f1_keywords: ["CRecordset", "AFXDB/CRecordset", "AFXDB/CRecordset::CRecordset", "AFXDB/CRecordset::AddNew", "AFXDB/CRecordset::CanAppend", "AFXDB/CRecordset::CanBookmark", "AFXDB/CRecordset::Cancel", "AFXDB/CRecordset::CancelUpdate", "AFXDB/CRecordset::CanRestart", "AFXDB/CRecordset::CanScroll", "AFXDB/CRecordset::CanTransact", "AFXDB/CRecordset::CanUpdate", "AFXDB/CRecordset::CheckRowsetError", "AFXDB/CRecordset::Close", "AFXDB/CRecordset::Delete", "AFXDB/CRecordset::DoBulkFieldExchange", "AFXDB/CRecordset::DoFieldExchange", "AFXDB/CRecordset::Edit", "AFXDB/CRecordset::FlushResultSet", "AFXDB/CRecordset::GetBookmark", "AFXDB/CRecordset::GetDefaultConnect", "AFXDB/CRecordset::GetDefaultSQL", "AFXDB/CRecordset::GetFieldValue", "AFXDB/CRecordset::GetODBCFieldCount", "AFXDB/CRecordset::GetODBCFieldInfo", "AFXDB/CRecordset::GetRecordCount", "AFXDB/CRecordset::GetRowsetSize", "AFXDB/CRecordset::GetRowsFetched", "AFXDB/CRecordset::GetRowStatus", "AFXDB/CRecordset::GetSQL", "AFXDB/CRecordset::GetStatus", "AFXDB/CRecordset::GetTableName", "AFXDB/CRecordset::IsBOF", "AFXDB/CRecordset::IsDeleted", "AFXDB/CRecordset::IsEOF", "AFXDB/CRecordset::IsFieldDirty", "AFXDB/CRecordset::IsFieldNull", "AFXDB/CRecordset::IsFieldNullable", "AFXDB/CRecordset::IsOpen", "AFXDB/CRecordset::Move", "AFXDB/CRecordset::MoveFirst", "AFXDB/CRecordset::MoveLast", "AFXDB/CRecordset::MoveNext", "AFXDB/CRecordset::MovePrev", "AFXDB/CRecordset::OnSetOptions", "AFXDB/CRecordset::OnSetUpdateOptions", "AFXDB/CRecordset::Open", "AFXDB/CRecordset::RefreshRowset", "AFXDB/CRecordset::Requery", "AFXDB/CRecordset::SetAbsolutePosition", "AFXDB/CRecordset::SetBookmark", "AFXDB/CRecordset::SetFieldDirty", "AFXDB/CRecordset::SetFieldNull", "AFXDB/CRecordset::SetLockingMode", "AFXDB/CRecordset::SetParamNull", "AFXDB/CRecordset::SetRowsetCursorPosition", "AFXDB/CRecordset::SetRowsetSize", "AFXDB/CRecordset::Update", "AFXDB/CRecordset::m_hstmt", "AFXDB/CRecordset::m_nFields", "AFXDB/CRecordset::m_nParams", "AFXDB/CRecordset::m_pDatabase", "AFXDB/CRecordset::m_strFilter", "AFXDB/CRecordset::m_strSort"] helpviewer_keywords: ["CRecordset [MFC], CRecordset", "CRecordset [MFC], AddNew", "CRecordset [MFC], CanAppend", "CRecordset [MFC], CanBookmark", "CRecordset [MFC], Cancel", "CRecordset [MFC], CancelUpdate", "CRecordset [MFC], CanRestart", "CRecordset [MFC], CanScroll", "CRecordset [MFC], CanTransact", "CRecordset [MFC], CanUpdate", "CRecordset [MFC], CheckRowsetError", "CRecordset [MFC], Close", "CRecordset [MFC], Delete", "CRecordset [MFC], DoBulkFieldExchange", "CRecordset [MFC], DoFieldExchange", "CRecordset [MFC], Edit", "CRecordset [MFC], FlushResultSet", "CRecordset [MFC], GetBookmark", "CRecordset [MFC], GetDefaultConnect", "CRecordset [MFC], GetDefaultSQL", "CRecordset [MFC], GetFieldValue", "CRecordset [MFC], GetODBCFieldCount", "CRecordset [MFC], GetODBCFieldInfo", "CRecordset [MFC], GetRecordCount", "CRecordset [MFC], GetRowsetSize", "CRecordset [MFC], GetRowsFetched", "CRecordset [MFC], GetRowStatus", "CRecordset [MFC], GetSQL", "CRecordset [MFC], GetStatus", "CRecordset [MFC], GetTableName", "CRecordset [MFC], IsBOF", "CRecordset [MFC], IsDeleted", "CRecordset [MFC], IsEOF", "CRecordset [MFC], IsFieldDirty", "CRecordset [MFC], IsFieldNull", "CRecordset [MFC], IsFieldNullable", "CRecordset [MFC], IsOpen", "CRecordset [MFC], Move", "CRecordset [MFC], MoveFirst", "CRecordset [MFC], MoveLast", "CRecordset [MFC], MoveNext", "CRecordset [MFC], MovePrev", "CRecordset [MFC], OnSetOptions", "CRecordset [MFC], OnSetUpdateOptions", "CRecordset [MFC], Open", "CRecordset [MFC], RefreshRowset", "CRecordset [MFC], Requery", "CRecordset [MFC], SetAbsolutePosition", "CRecordset [MFC], SetBookmark", "CRecordset [MFC], SetFieldDirty", "CRecordset [MFC], SetFieldNull", "CRecordset [MFC], SetLockingMode", "CRecordset [MFC], SetParamNull", "CRecordset [MFC], SetRowsetCursorPosition", "CRecordset [MFC], SetRowsetSize", "CRecordset [MFC], Update", "CRecordset [MFC], m_hstmt", "CRecordset [MFC], m_nFields", "CRecordset [MFC], m_nParams", "CRecordset [MFC], m_pDatabase", "CRecordset [MFC], m_strFilter", "CRecordset [MFC], m_strSort"] -ms.assetid: dd89a21d-ef39-4aab-891b-1e373d67c855 --- -# `CRecordset` Class +# `CRecordset` class Represents a set of records selected from a data source. ## Syntax -``` +```cpp class CRecordset : public CObject ``` ## Members -### Public Constructors +### Public constructors |Name|Description| |----------|-----------------| |[`CRecordset::CRecordset`](#crecordset)|Constructs a `CRecordset` object. Your derived class must provide a constructor that calls this one.| -### Public Methods +### Public methods |Name|Description| |----------|-----------------| @@ -43,7 +42,7 @@ class CRecordset : public CObject |[`CRecordset::DoBulkFieldExchange`](#dobulkfieldexchange)|Called to exchange bulk rows of data from the data source to the recordset. Implements bulk record field exchange (Bulk RFX).| |[`CRecordset::DoFieldExchange`](#dofieldexchange)|Called to exchange data (in both directions) between the field data members of the recordset and the corresponding record on the data source. Implements record field exchange (RFX).| |[`CRecordset::Edit`](#edit)|Prepares for changes to the current record. Call `Update` to complete the edit.| -|[`CRecordset::FlushResultSet`](#flushresultset)|Returns nonzero if there is another result set to be retrieved, when using a predefined query.| +|[`CRecordset::FlushResultSet`](#flushresultset)|Returns nonzero if there's another result set to be retrieved, when using a predefined query.| |[`CRecordset::GetBookmark`](#getbookmark)|Assigns the bookmark value of a record to the parameter object.| |[`CRecordset::GetDefaultConnect`](#getdefaultconnect)|Called to get the default connection string.| |[`CRecordset::GetDefaultSQL`](#getdefaultsql)|Called to get the default SQL string to execute.| @@ -57,9 +56,9 @@ class CRecordset : public CObject |[`CRecordset::GetSQL`](#getsql)|Gets the SQL string used to select records for the recordset.| |[`CRecordset::GetStatus`](#getstatus)|Gets the status of the recordset: the index of the current record and whether a final count of the records has been obtained.| |[`CRecordset::GetTableName`](#gettablename)|Gets the name of the table on which the recordset is based.| -|[`CRecordset::IsBOF`](#isbof)|Returns nonzero if the recordset has been positioned before the first record. There is no current record.| +|[`CRecordset::IsBOF`](#isbof)|Returns nonzero if the recordset has been positioned before the first record. There's no current record.| |[`CRecordset::IsDeleted`](#isdeleted)|Returns nonzero if the recordset is positioned on a deleted record.| -|[`CRecordset::IsEOF`](#iseof)|Returns nonzero if the recordset has been positioned after the last record. There is no current record.| +|[`CRecordset::IsEOF`](#iseof)|Returns nonzero if the recordset has been positioned after the last record. There's no current record.| |[`CRecordset::IsFieldDirty`](#isfielddirty)|Returns nonzero if the specified field in the current record has been changed.| |[`CRecordset::IsFieldNull`](#isfieldnull)|Returns nonzero if the specified field in the current record is null (has no value).| |[`CRecordset::IsFieldNullable`](#isfieldnullable)|Returns nonzero if the specified field in the current record can be set to null (having no value).| @@ -84,7 +83,7 @@ class CRecordset : public CObject |[`CRecordset::SetRowsetSize`](#setrowsetsize)|Specifies the number of records you wish to retrieve during a fetch.| |[`CRecordset::Update`](#update)|Completes an `AddNew` or `Edit` operation by saving the new or edited data on the data source.| -### Public Data Members +### Public data members |Name|Description| |----------|-----------------| @@ -97,10 +96,10 @@ class CRecordset : public CObject ## Remarks -Known as "recordsets," `CRecordset` objects are typically used in two forms: dynasets and snapshots. A dynaset stays synchronized with data updates made by other users. A snapshot is a static view of the data. Each form represents a set of records fixed at the time the recordset is opened, but when you scroll to a record in a dynaset, it reflects changes subsequently made to the record, either by other users or by other recordsets in your application. +Known as "recordsets," `CRecordset` objects are typically used in two forms: dynasets and snapshots. A dynaset stays synchronized with data updates made by other users. A snapshot is a static view of the data. Each form represents a set of records fixed at the time the recordset is opened. When you scroll to a record in a dynaset, it reflects changes made to the record, either by other users or by other recordsets in your application. > [!NOTE] -> If you are working with the Data Access Objects (DAO) classes rather than the Open Database Connectivity (ODBC) classes, use class [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md) instead. For more information, see the article [Overview: Database Programming](../../data/data-access-programming-mfc-atl.md). +> If you're working with the Data Access Objects (DAO) classes rather than the Open Database Connectivity (ODBC) classes, use class [`CDaoRecordset`](../../mfc/reference/cdaorecordset-class.md) instead. For more information, see [Overview: Database Programming](../../data/data-access-programming-mfc-atl.md). To work with either kind of recordset, you typically derive an application-specific recordset class from `CRecordset`. Recordsets select records from a data source, and you can then: @@ -114,13 +113,13 @@ To work with either kind of recordset, you typically derive an application-speci - Parameterize the recordset to customize its selection with information not known until run time. -To use your class, open a database and construct a recordset object, passing the constructor a pointer to your `CDatabase` object. Then call the recordset's `Open` member function, where you can specify whether the object is a dynaset or a snapshot. Calling `Open` selects data from the data source. After the recordset object is opened, use its member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a dynaset or a snapshot, whether it is updatable or read-only (this depends on the capability of the Open Database Connectivity (ODBC) data source), and whether you have implemented bulk row fetching. To refresh records that may have been changed or added since the `Open` call, call the object's `Requery` member function. Call the object's `Close` member function and destroy the object when you finish with it. +To use your class, open a database and construct a recordset object, passing the constructor a pointer to your `CDatabase` object. Then call the recordset's `Open` member function, where you can specify whether the object is a dynaset or a snapshot. Calling `Open` selects data from the data source. After the recordset object is opened, use its member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a dynaset or a snapshot, whether it's updatable or read-only (this depends on the capability of the Open Database Connectivity (ODBC) data source), and whether you've implemented bulk row fetching. To refresh records that may have been changed or added since the `Open` call, call the object's `Requery` member function. Call the object's `Close` member function and destroy the object when you finish with it. In a derived `CRecordset` class, record field exchange (RFX) or bulk record field exchange (Bulk RFX) is used to support reading and updating of record fields. For more information about recordsets and record field exchange, see the articles [Overview: Database Programming](../../data/data-access-programming-mfc-atl.md), [Recordset (ODBC)](../../data/odbc/recordset-odbc.md), [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md), and [Record Field Exchange (RFX)](../../data/odbc/record-field-exchange-rfx.md). For a focus on dynasets and snapshots, see the articles [Dynaset](../../data/odbc/dynaset.md) and [Snapshot](../../data/odbc/snapshot.md). -## Inheritance Hierarchy +## Inheritance hierarchy [`CObject`](../../mfc/reference/cobject-class.md) @@ -134,44 +133,44 @@ For more information about recordsets and record field exchange, see the article Prepares for adding a new record to the table. -``` +```cpp virtual void AddNew(); ``` ### Remarks -You must call the [`Requery`](#requery) member function to see the newly added record. The record's fields are initially Null. (In database terminology, Null means "having no value" and is not the same as NULL in C++.) To complete the operation, you must call the [`Update`](#update) member function. `Update` saves your changes to the data source. +You must call the [`Requery`](#requery) member function to see the newly added record. The record's fields are initially Null. (In database terminology, Null means "having no value" and isn't the same as NULL in C++.) To complete the operation, you must call the [`Update`](#update) member function. `Update` saves your changes to the data source. > [!NOTE] -> If you have implemented bulk row fetching, you cannot call `AddNew`. This will result in a failed assertion. Although class `CRecordset` does not provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you can't call `AddNew`. This will result in a failed assertion. Although class `CRecordset` doesn't provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -`AddNew` prepares a new, empty record using the recordset's field data members. After you call `AddNew`, set the values you want in the recordset's field data members. (You do not have to call the [Edit](#edit) member function for this purpose; use `Edit` only for existing records.) When you subsequently call `Update`, changed values in the field data members are saved on the data source. +`AddNew` prepares a new, empty record using the recordset's field data members. After you call `AddNew`, set the values you want in the recordset's field data members. (You don't have to call the [Edit](#edit) member function for this purpose; use `Edit` only for existing records.) When you call `Update`, changed values in the field data members are saved on the data source. > [!CAUTION] > If you scroll to a new record before you call `Update`, the new record is lost, and no warning is given. -If the data source supports transactions, you can make your `AddNew` call part of a transaction. For more information about transactions, see class [`CDatabase`](../../mfc/reference/cdatabase-class.md). Note that you should call [`CDatabase::BeginTrans`](../../mfc/reference/cdatabase-class.md#begintrans) before calling `AddNew`. +If the data source supports transactions, you can make your `AddNew` call part of a transaction. For more information about transactions, see class [`CDatabase`](../../mfc/reference/cdatabase-class.md). Call [`CDatabase::BeginTrans`](../../mfc/reference/cdatabase-class.md#begintrans) before calling `AddNew`. > [!NOTE] -> For dynasets, new records are added to the recordset as the last record. Added records are not added to snapshots; you must call `Requery` to refresh the recordset. +> For dynasets, new records are added to the recordset as the last record. Added records aren't added to snapshots; you must call `Requery` to refresh the recordset. -It is illegal to call `AddNew` for a recordset whose `Open` member function has not been called. A `CDBException` is thrown if you call `AddNew` for a recordset that cannot be appended to. You can determine whether the recordset is updatable by calling [`CanAppend`](#canappend). +It's illegal to call `AddNew` for a recordset whose `Open` member function hasn't been called. A `CDBException` is thrown if you call `AddNew` for a recordset that can't be appended to. You can determine whether the recordset is updatable by calling [`CanAppend`](#canappend). For more information, see the following articles: [Recordset: How Recordsets Update Records (ODBC)](../../data/odbc/recordset-how-recordsets-update-records-odbc.md), [Recordset: Adding, Updating, and Deleting Records (ODBC)](../../data/odbc/recordset-adding-updating-and-deleting-records-odbc.md), and [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). ### Example -See the article [Transaction: Performing a Transaction in a Recordset (ODBC)](../../data/odbc/transaction-performing-a-transaction-in-a-recordset-odbc.md). +see [Transaction: Performing a Transaction in a Recordset (ODBC)](../../data/odbc/transaction-performing-a-transaction-in-a-recordset-odbc.md). ## `CRecordset::CanAppend` Determines whether the previously opened recordset allows you to add new records. -``` +```cpp BOOL CanAppend() const; ``` -### Return Value +### Return value Nonzero if the recordset allows adding new records; otherwise 0. `CanAppend` will return 0 if you opened the recordset as read-only. @@ -179,20 +178,20 @@ Nonzero if the recordset allows adding new records; otherwise 0. `CanAppend` wil Determines whether the recordset allows you to mark records using bookmarks. -``` +```cpp BOOL CanBookmark() const; ``` -### Return Value +### Return value Nonzero if the recordset supports bookmarks; otherwise 0. ### Remarks -This function is independent of the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. `CanBookmark` indicates whether the given ODBC driver and cursor type support bookmarks. `CRecordset::useBookmarks` indicates whether bookmarks will be available, provided they are supported. +This function is independent of the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. `CanBookmark` indicates whether the given ODBC driver and cursor type support bookmarks. `CRecordset::useBookmarks` indicates whether bookmarks will be available, provided they're supported. > [!NOTE] -> Bookmarks are not supported on forward-only recordsets. +> Bookmarks aren't supported on forward-only recordsets. For more information about bookmarks and recordset navigation, see the articles [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md) and [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md). @@ -206,7 +205,7 @@ void Cancel(); ### Remarks -Note that the MFC ODBC classes no longer use asynchronous processing; to perform an asychronous operation, you must directly call the ODBC API function `SQLSetConnectOption`. For more information, see the topic "Executing Functions Asynchronously" in the *ODBC SDK Programmer's Guide*. +The MFC ODBC classes no longer use asynchronous processing; to perform an asynchronous operation, you must directly call the ODBC API function `SQLSetConnectOption`. For more information, see "Executing Functions Asynchronously" in the *ODBC SDK Programmer's Guide*. ## `CRecordset::CancelUpdate` @@ -219,21 +218,21 @@ void CancelUpdate(); ### Remarks > [!NOTE] -> This member function is not applicable on recordsets that are using bulk row fetching, since such recordsets cannot call `Edit`, `AddNew`, or `Update`. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> This member function isn't applicable on recordsets that are using bulk row fetching, since such recordsets can't call `Edit`, `AddNew`, or `Update`. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). If automatic dirty field checking is enabled, `CancelUpdate` will restore the member variables to the values they had before `Edit` or `AddNew` was called; otherwise, any value changes will remain. By default, automatic field checking is enabled when the recordset is opened. To disable it, you must specify the `CRecordset::noDirtyFieldCheck` in the *`dwOptions`* parameter of the [Open](#open) member function. -For more information about updating data, see the article [Recordset: Adding, Updating, and Deleting Records (ODBC)](../../data/odbc/recordset-adding-updating-and-deleting-records-odbc.md). +For more information about updating data, see [Recordset: Adding, Updating, and Deleting Records (ODBC)](../../data/odbc/recordset-adding-updating-and-deleting-records-odbc.md). ## `CRecordset::CanRestart` Determines whether the recordset allows restarting its query (to refresh its records) by calling the `Requery` member function. -``` +```cpp BOOL CanRestart() const; ``` -### Return Value +### Return value Nonzero if requery is allowed; otherwise 0. @@ -241,43 +240,43 @@ Nonzero if requery is allowed; otherwise 0. Determines whether the recordset allows scrolling. -``` +```cpp BOOL CanScroll() const; ``` -### Return Value +### Return value Nonzero if the recordset allows scrolling; otherwise 0. ### Remarks -For more information about scrolling, see the article [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md). +For more information about scrolling, see [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md). ## `CRecordset::CanTransact` Determines whether the recordset allows transactions. -``` +```cpp BOOL CanTransact() const; ``` -### Return Value +### Return value Nonzero if the recordset allows transactions; otherwise 0. ### Remarks -For more information, see the article [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). +For more information, see [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). ## `CRecordset::CanUpdate` Determines whether the recordset can be updated. -``` +```cpp BOOL CanUpdate() const; ``` -### Return Value +### Return value Nonzero if the recordset can be updated; otherwise 0. @@ -289,20 +288,20 @@ A recordset might be read-only if the underlying data source is read-only or if Called to handle errors generated during record fetching. -``` +```cpp virtual void CheckRowsetError(RETCODE nRetCode); ``` ### Parameters -*`nRetCode`*
+*`nRetCode`*\ An ODBC API function return code. For details, see Remarks. ### Remarks This virtual member function handles errors that occur when records are fetched, and is useful during bulk row fetching. You may want to consider overriding `CheckRowsetError` to implement your own error handling. -`CheckRowsetError` is called automatically in a cursor navigation operation, such as `Open`, `Requery`, or any `Move` operation. It is passed the return value of the ODBC API function `SQLExtendedFetch`. The following table lists the possible values for the *`nRetCode`* parameter. +`CheckRowsetError` is called automatically in a cursor navigation operation, such as `Open`, `Requery`, or any `Move` operation. It's passed the return value of the ODBC API function `SQLExtendedFetch`. The following table lists the possible values for the *`nRetCode`* parameter. |nRetCode|Description| |--------------|-----------------| @@ -311,15 +310,15 @@ This virtual member function handles errors that occur when records are fetched, |`SQL_NO_DATA_FOUND`|All rows from the result set have been fetched.| |`SQL_ERROR`|Function failed. Additional information can be obtained by calling `SQLError`.| |`SQL_INVALID_HANDLE`|Function failed due to an invalid environment handle, connection handle, or statement handle. This indicates a programming error. No additional information is available from `SQLError`.| -|`SQL_STILL_EXECUTING`|A function that was started asynchronously is still executing. Note that by default, MFC will never pass this value to `CheckRowsetError`; MFC will continue calling `SQLExtendedFetch` until it no longer returns `SQL_STILL_EXECUTING`.| +|`SQL_STILL_EXECUTING`|A function that was started asynchronously is still executing. By default, MFC will never pass this value to `CheckRowsetError`; MFC will continue calling `SQLExtendedFetch` until it no longer returns `SQL_STILL_EXECUTING`.| -For more information about `SQLError`, see the Windows SDK. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about `SQLError`, see the Windows SDK. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::Close` Closes the recordset. -``` +```cpp virtual void Close(); ``` @@ -337,14 +336,14 @@ You can call `Open` again after calling `Close`. This lets you reuse the records Constructs a `CRecordset` object. -``` +```cpp CRecordset(CDatabase* pDatabase = NULL); ``` ### Parameters -*`pDatabase`*
-Contains a pointer to a `CDatabase` object or the value `NULL`. If not `NULL` and the `CDatabase` object's `Open` member function has not been called to connect it to the data source, the recordset attempts to open it for you during its own `Open` call. If you pass `NULL`, a `CDatabase` object is constructed and connected for you using the data source information you specified when you derived your recordset class with ClassWizard. +*`pDatabase`*\ +Contains a pointer to a `CDatabase` object or the value `NULL`. If not `NULL` and the `CDatabase` object's `Open` member function hasn't been called to connect it to the data source, the recordset attempts to open it for you during its own `Open` call. If you pass `NULL`, a `CDatabase` object is constructed and connected for you using the data source information you specified when you derived your recordset class with ClassWizard. ### Remarks @@ -353,31 +352,31 @@ You can either use `CRecordset` directly or derive an application-specific class > [!NOTE] > A derived class *must* supply its own constructor. In the constructor of your derived class, call the constructor `CRecordset::CRecordset`, passing the appropriate parameters along to it. -Pass `NULL` to your recordset constructor to have a `CDatabase` object constructed and connected for you automatically. This is a useful shorthand that does not require you to construct and connect a `CDatabase` object prior to constructing your recordset. +Pass `NULL` to your recordset constructor to have a `CDatabase` object constructed and connected for you automatically. This is a useful shorthand that doesn't require you to construct and connect a `CDatabase` object prior to constructing your recordset. ### Example -For more information, see the article [Recordset: Declaring a Class for a Table (ODBC)](../../data/odbc/recordset-declaring-a-class-for-a-table-odbc.md). +For more information, see [Recordset: Declaring a Class for a Table (ODBC)](../../data/odbc/recordset-declaring-a-class-for-a-table-odbc.md). ## `CRecordset::Delete` Deletes the current record. -``` +```cpp virtual void Delete(); ``` ### Remarks -After a successful deletion, the recordset's field data members are set to a Null value, and you must explicitly call one of the `Move` functions in order to move off the deleted record. Once you move off the deleted record, it is not possible to return to it. If the data source supports transactions, you can make the `Delete` call part of a transaction. For more information, see the article [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). +After a successful deletion, the recordset's field data members are set to a Null value, and you must explicitly call one of the `Move` functions in order to move off the deleted record. Once you move off the deleted record, it's not possible to return to it. If the data source supports transactions, you can make the `Delete` call part of a transaction. For more information, see [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). > [!NOTE] -> If you have implemented bulk row fetching, you cannot call `Delete`. This will result in a failed assertion. Although class `CRecordset` does not provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you can't call `Delete`. This will result in a failed assertion. Although class `CRecordset` doesn't provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). > [!CAUTION] -> The recordset must be updatable and there must be a valid record current in the recordset when you call `Delete`; otherwise, an error occurs. For example, if you delete a record but do not scroll to a new record before you call `Delete` again, `Delete` throws a [CDBException](../../mfc/reference/cdbexception-class.md). +> The recordset must be updatable and there must be a valid record current in the recordset when you call `Delete`; otherwise, an error occurs. For example, if you delete a record but don't scroll to a new record before you call `Delete` again, `Delete` throws a [CDBException](../../mfc/reference/cdbexception-class.md). -Unlike [`AddNew`](#addnew) and [`Edit`](#edit), a call to `Delete` is not followed by a call to [`Update`](#update). If a `Delete` call fails, the field data members are left unchanged. +Unlike [`AddNew`](#addnew) and [`Edit`](#edit), a call to `Delete` isn't followed by a call to [`Update`](#update). If a `Delete` call fails, the field data members are left unchanged. ### Example @@ -389,88 +388,88 @@ This example shows a recordset created on the frame of a function. The example a Called to exchange bulk rows of data from the data source to the recordset. Implements bulk record field exchange (Bulk RFX). -``` +```cpp virtual void DoBulkFieldExchange(CFieldExchange* pFX); ``` ### Parameters -*`pFX`*
+*`pFX`*\ A pointer to a [`CFieldExchange`](../../mfc/reference/cfieldexchange-class.md) object. The framework will already have set up this object to specify a context for the field exchange operation. ### Remarks When bulk row fetching is implemented, the framework calls this member function to automatically transfer data from the data source to your recordset object. `DoBulkFieldExchange` also binds your parameter data members, if any, to parameter placeholders in the SQL statement string for the recordset's selection. -If bulk row fetching is not implemented, the framework calls [`DoFieldExchange`](#dofieldexchange). To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option of the *dwOptions* parameter in the [`Open`](#open) member function. +If bulk row fetching isn't implemented, the framework calls [`DoFieldExchange`](#dofieldexchange). To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option of the *dwOptions* parameter in the [`Open`](#open) member function. > [!NOTE] -> `DoBulkFieldExchange` is available only if you are using a class derived from `CRecordset`. If you have created a recordset object directly from `CRecordset`, you must call the [`GetFieldValue`](#getfieldvalue) member function to retrieve data. +> `DoBulkFieldExchange` is available only if you're using a class derived from `CRecordset`. If you've created a recordset object directly from `CRecordset`, you must call the [`GetFieldValue`](#getfieldvalue) member function to retrieve data. -Bulk record field exchange (Bulk RFX) is similar to record field exchange (RFX). Data is automatically transferred from the data source to the recordset object. However, you cannot call `AddNew`, `Edit`, `Delete`, or `Update` to transfer changes back to the data source. Class `CRecordset` currently does not provide a mechanism for updating bulk rows of data; however, you can write your own functions by using the ODBC API function `SQLSetPos`. +Bulk record field exchange (Bulk RFX) is similar to record field exchange (RFX). Data is automatically transferred from the data source to the recordset object. However, you can't call `AddNew`, `Edit`, `Delete`, or `Update` to transfer changes back to the data source. Class `CRecordset` currently doesn't provide a mechanism for updating bulk rows of data; however, you can write your own functions by using the ODBC API function `SQLSetPos`. -Note that ClassWizard does not support bulk record field exchange; therefore, you must override `DoBulkFieldExchange` manually by writing calls to the Bulk RFX functions. For more information about these functions, see the topic [Record Field Exchange Functions](../../mfc/reference/record-field-exchange-functions.md). +ClassWizard doesn't support bulk record field exchange; therefore, you must override `DoBulkFieldExchange` manually by writing calls to the Bulk RFX functions. For more information about these functions, see [Record Field Exchange Functions](../../mfc/reference/record-field-exchange-functions.md). -For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). For related information, see the article [Record Field Exchange (RFX)](../../data/odbc/record-field-exchange-rfx.md). +For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). For related information, see [Record Field Exchange (RFX)](../../data/odbc/record-field-exchange-rfx.md). ## `CRecordset::DoFieldExchange` Called to exchange data (in both directions) between the field data members of the recordset and the corresponding record on the data source. Implements record field exchange (RFX). -``` +```cpp virtual void DoFieldExchange(CFieldExchange* pFX); ``` ### Parameters -*`pFX`*
+*`pFX`*\ A pointer to a [`CFieldExchange`](../../mfc/reference/cfieldexchange-class.md) object. The framework will already have set up this object to specify a context for the field exchange operation. ### Remarks -When bulk row fetching is not implemented, the framework calls this member function to automatically exchange data between the field data members of your recordset object and the corresponding columns of the current record on the data source. `DoFieldExchange` also binds your parameter data members, if any, to parameter placeholders in the SQL statement string for the recordset's selection. +When bulk row fetching isn't implemented, the framework calls this member function to automatically exchange data between the field data members of your recordset object and the corresponding columns of the current record on the data source. `DoFieldExchange` also binds your parameter data members, if any, to parameter placeholders in the SQL statement string for the recordset's selection. If bulk row fetching is implemented, the framework calls [`DoBulkFieldExchange`](#dobulkfieldexchange). To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option of the *`dwOptions`* parameter in the [`Open`](#open) member function. > [!NOTE] -> `DoFieldExchange` is available only if you are using a class derived from `CRecordset`. If you have created a recordset object directly from `CRecordset`, you must call the [GetFieldValue](#getfieldvalue) member function to retrieve data. +> `DoFieldExchange` is available only if you're using a class derived from `CRecordset`. If you've created a recordset object directly from `CRecordset`, you must call the [GetFieldValue](#getfieldvalue) member function to retrieve data. The exchange of field data, called record field exchange (RFX), works in both directions: from the recordset object's field data members to the fields of the record on the data source, and from the record on the data source to the recordset object. -The only action you must normally take to implement `DoFieldExchange` for your derived recordset class is to create the class with ClassWizard and specify the names and data types of the field data members. You might also add code to what ClassWizard writes to specify parameter data members or to deal with any columns you bind dynamically. For more information, see the article [Recordset: Dynamically Binding Data Columns (ODBC)](../../data/odbc/recordset-dynamically-binding-data-columns-odbc.md). +The only action you must normally take to implement `DoFieldExchange` for your derived recordset class is to create the class with ClassWizard and specify the names and data types of the field data members. You might also add code to what ClassWizard writes to specify parameter data members or to deal with any columns you bind dynamically. For more information, see [Recordset: Dynamically Binding Data Columns (ODBC)](../../data/odbc/recordset-dynamically-binding-data-columns-odbc.md). When you declare your derived recordset class with ClassWizard, the wizard writes an override of `DoFieldExchange` for you, which resembles the following example: [!code-cpp[NVC_MFCDatabase#19](../../mfc/codesnippet/cpp/crecordset-class_3.cpp)] -For more information about the RFX functions, see the topic [Record Field Exchange Functions](../../mfc/reference/record-field-exchange-functions.md). +For more information about the RFX functions, see [Record Field Exchange Functions](../../mfc/reference/record-field-exchange-functions.md). -For further examples and details about `DoFieldExchange`, see the article [Record Field Exchange: How RFX Works](../../data/odbc/record-field-exchange-how-rfx-works.md). For general information about RFX, see the article [Record Field Exchange](../../data/odbc/record-field-exchange-rfx.md). +For further examples and details about `DoFieldExchange`, see [Record Field Exchange: How RFX Works](../../data/odbc/record-field-exchange-how-rfx-works.md). For general information about RFX, see [Record Field Exchange](../../data/odbc/record-field-exchange-rfx.md). ## `CRecordset::Edit` Allows changes to the current record. -``` +```cpp virtual void Edit(); ``` ### Remarks -After you call `Edit`, you can change the field data members by directly resetting their values. The operation is completed when you subsequently call the [`Update`](#update) member function to save your changes on the data source. +After you call `Edit`, you can change the field data members by directly resetting their values. The operation is completed when you call the [`Update`](#update) member function to save your changes on the data source. > [!NOTE] -> If you have implemented bulk row fetching, you cannot call `Edit`. This will result in a failed assertion. Although class `CRecordset` does not provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you can't call `Edit`. This will result in a failed assertion. Although class `CRecordset` doesn't provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). `Edit` saves the values of the recordset's data members. If you call `Edit`, make changes, then call `Edit` again, the record's values are restored to what they were before the first `Edit` call. -In some cases, you may want to update a column by making it Null (containing no data). To do so, call [`SetFieldNull`](#setfieldnull) with a parameter of TRUE to mark the field Null; this also causes the column to be updated. If you want a field to be written to the data source even though its value has not changed, call [`SetFieldDirty`](#setfielddirty) with a parameter of TRUE. This works even if the field had the value Null. +In some cases, you may want to update a column by making it Null (containing no data). To do so, call [`SetFieldNull`](#setfieldnull) with a parameter of TRUE to mark the field Null; this also causes the column to be updated. If you want a field to be written to the data source even though its value hasn't changed, call [`SetFieldDirty`](#setfielddirty) with a parameter of TRUE. This works even if the field had the value Null. -If the data source supports transactions, you can make the `Edit` call part of a transaction. Note that you should call [`CDatabase::BeginTrans`](../../mfc/reference/cdatabase-class.md#begintrans) before calling `Edit` and after the recordset has been opened. Also note that calling [`CDatabase::CommitTrans`](../../mfc/reference/cdatabase-class.md#committrans) is not a substitute for calling `Update` to complete the `Edit` operation. For more information about transactions, see class [`CDatabase`](../../mfc/reference/cdatabase-class.md). +If the data source supports transactions, you can make the `Edit` call part of a transaction. Call [`CDatabase::BeginTrans`](../../mfc/reference/cdatabase-class.md#begintrans) before calling `Edit` and after the recordset has been opened. Also, calling [`CDatabase::CommitTrans`](../../mfc/reference/cdatabase-class.md#committrans) isn't a substitute for calling `Update` to complete the `Edit` operation. For more information about transactions, see class [`CDatabase`](../../mfc/reference/cdatabase-class.md). Depending on the current locking mode, the record being updated may be locked by `Edit` until you call `Update` or scroll to another record, or it may be locked only during the `Edit` call. You can change the locking mode with [`SetLockingMode`](#setlockingmode). -The previous value of the current record is restored if you scroll to a new record before calling `Update`. A `CDBException` is thrown if you call `Edit` for a recordset that cannot be updated or if there is no current record. +The previous value of the current record is restored if you scroll to a new record before calling `Update`. A `CDBException` is thrown if you call `Edit` for a recordset that can't be updated or if there's no current record. For more information, see the articles [Transaction (ODBC)](../../data/odbc/transaction-odbc.md) and [Recordset: Locking Records (ODBC)](../../data/odbc/recordset-locking-records-odbc.md). @@ -482,17 +481,17 @@ For more information, see the articles [Transaction (ODBC)](../../data/odbc/tran Retrieves the next result set of a predefined query (stored procedure), if there are multiple result sets. -``` +```cpp BOOL FlushResultSet(); ``` -### Return Value +### Return value Nonzero if there are more result sets to be retrieved; otherwise 0. ### Remarks -You should call `FlushResultSet` only when you are completely finished with the cursor on the current result set. Note that when you retrieve the next result set by calling `FlushResultSet`, your cursor is not valid on that result set; you should call the [`MoveNext`](#movenext) member function after calling `FlushResultSet`. +You should call `FlushResultSet` only when you're finished with the cursor on the current result set. When you retrieve the next result set by calling `FlushResultSet`, your cursor isn't valid on that result set; you should call the [`MoveNext`](#movenext) member function after calling `FlushResultSet`. If a predefined query uses an output parameter or input/output parameters, you must call `FlushResultSet` until it returns `FALSE`(the value 0), in order to obtain these parameter values. @@ -505,7 +504,7 @@ Your stored procedure needs to have bound fields if you want to call `FlushResul The following code assumes that `COutParamRecordset` is a `CRecordset`-derived object based on a predefined query with an input parameter and an output parameter, and having multiple result sets. Note the structure of the [`DoFieldExchange`](#dofieldexchange) override. [!code-cpp[NVC_MFCDatabase#21](../../mfc/codesnippet/cpp/crecordset-class_5.cpp)] - +  [!code-cpp[NVC_MFCDatabase#22](../../mfc/codesnippet/cpp/crecordset-class_6.cpp)] ## `CRecordset::GetBookmark` @@ -518,15 +517,15 @@ void GetBookmark(CDBVariant& varBookmark); ### Parameters -*`varBookmark`*
+*`varBookmark`*\ A reference to a [`CDBVariant`](../../mfc/reference/cdbvariant-class.md) object representing the bookmark on the current record. ### Remarks -To determine if bookmarks are supported on the recordset, call [`CanBookmark`](#canbookmark). To make bookmarks available if they are supported, you must set the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. +To determine if bookmarks are supported on the recordset, call [`CanBookmark`](#canbookmark). To make bookmarks available if they're supported, you must set the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. > [!NOTE] -> If bookmarks are unsupported or unavailable, calling `GetBookmark` will result in an exception being thrown. Bookmarks are not supported on forward-only recordsets. +> If bookmarks are unsupported or unavailable, calling `GetBookmark` will result in an exception being thrown. Bookmarks aren't supported on forward-only recordsets. `GetBookmark` assigns the value of the bookmark for the current record to a `CDBVariant` object. To return to that record at any time after moving to a different record, call [`SetBookmark`](#setbookmark) with the corresponding `CDBVariant` object. @@ -539,27 +538,27 @@ For more information about bookmarks and recordset navigation, see the articles Called to get the default connection string. -``` +```cpp virtual CString GetDefaultConnect(); ``` -### Return Value +### Return value A `CString` that contains the default connection string. ### Remarks -The framework calls this member function to get the default connection string for the data source on which the recordset is based. `ClassWizard` implements this function for you by identifying the same data source you use in `ClassWizard` to get information about tables and columns. You will probably find it convenient to rely on this default connection while developing your application. But the default connection may not be appropriate for users of your application. If that is the case, you should reimplement this function, discarding `ClassWizard`'s version. For more information about connection strings, see the article [Data Source (ODBC)](../../data/odbc/data-source-odbc.md). +The framework calls this member function to get the default connection string for the data source on which the recordset is based. `ClassWizard` implements this function for you by identifying the same data source you use in `ClassWizard` to get information about tables and columns. You'll probably find it convenient to rely on this default connection while developing your application. But the default connection may not be appropriate for users of your application. If that is the case, you should reimplement this function, discarding `ClassWizard`'s version. For more information about connection strings, see [Data Source (ODBC)](../../data/odbc/data-source-odbc.md). ## `CRecordset::GetDefaultSQL` Called to get the default SQL string to execute. -``` +```cpp virtual CString GetDefaultSQL(); ``` -### Return Value +### Return value A `CString` that contains the default SQL statement. @@ -571,10 +570,10 @@ You indirectly define the default SQL statement by declaring your recordset clas If you need the SQL statement string for your own use, call `GetSQL`, which returns the SQL statement used to select the recordset's records when it was opened. You can edit the default SQL string in your class's override of `GetDefaultSQL`. For example, you could specify a call to a predefined query using a **`CALL`** statement. (Note, however, that if you edit `GetDefaultSQL`, you also need to modify `m_nFields` to match the number of columns in the data source.) -For more information, see the article [Recordset: Declaring a Class for a Table (ODBC)](../../data/odbc/recordset-declaring-a-class-for-a-table-odbc.md). +For more information, see [Recordset: Declaring a Class for a Table (ODBC)](../../data/odbc/recordset-declaring-a-class-for-a-table-odbc.md). > [!CAUTION] -> The table name will be empty if the framework could not identify a table name, if multiple table names were supplied, or if a **`CALL`** statement could not be interpreted. Note that when using a **`CALL`** statement, you must not insert whitespace between the curly brace and the **`CALL`** keyword, nor should you insert whitespace before the curly brace or before the **`SELECT`** keyword in a **`SELECT`** statement. +> The table name will be empty if the framework could not identify a table name, if multiple table names were supplied, or if a **`CALL`** statement could not be interpreted. When you use a **`CALL`** statement, don't insert whitespace between the curly brace and the **`CALL`** keyword, nor before the curly brace or before the **`SELECT`** keyword in a **`SELECT`** statement. ## `CRecordset::GetFieldValue` @@ -586,6 +585,16 @@ void GetFieldValue( CDBVariant& varValue, short nFieldType = DEFAULT_FIELD_TYPE); +void GetFieldValue( + LPCTSTR lpszName, + CStringA& strValue +); + +void GetFieldValue( + LPCTSTR lpszName, + CStringW& strValue +); + void GetFieldValue( short nIndex, CDBVariant& varValue, @@ -602,13 +611,13 @@ void GetFieldValue( ### Parameters -*`lpszName`*
+*`lpszName`*\ The name of a field. *`varValue`* A reference to a [`CDBVariant`](../../mfc/reference/cdbvariant-class.md) object that will store the field's value. -*`nFieldType`*
+*`nFieldType`*\ The ODBC C data type of the field. Using the default value, `DEFAULT_FIELD_TYPE`, forces `GetFieldValue` to determine the C data type from the SQL data type, based on the following table. Otherwise, you can specify the data type directly or choose a compatible data type; for example, you can store any data type into `SQL_C_CHAR`. |C data type|SQL data type| @@ -625,22 +634,22 @@ The ODBC C data type of the field. Using the default value, `DEFAULT_FIELD_TYPE` For more information about ODBC data types, see the topics "SQL Data Types" and "C Data Types" in Appendix D of the Windows SDK. -*`nIndex`*
+*`nIndex`*\ The zero-based index of the field. -*`strValue`*
+*`strValue`*\ A reference to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that will store the field's value converted to text, regardless of the field's data type. ### Remarks You can look up a field either by name or by index. You can store the field value in either a `CDBVariant` object or a `CString` object. -If you have implemented bulk row fetching, the current record is always positioned on the first record in a rowset. To use `GetFieldValue` on a record within a given rowset, you must first call the [`SetRowsetCursorPosition`](#setrowsetcursorposition) member function to move the cursor to the desired row within that rowset. Then call `GetFieldValue` for that row. To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option of the *`dwOptions`* parameter in the [`Open`](#open) member function. +If you've implemented bulk row fetching, the current record is always positioned on the first record in a rowset. To use `GetFieldValue` on a record within a given rowset, you must first call the [`SetRowsetCursorPosition`](#setrowsetcursorposition) member function to move the cursor to the desired row within that rowset. Then call `GetFieldValue` for that row. To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option of the *`dwOptions`* parameter in the [`Open`](#open) member function. -You can use `GetFieldValue` to dynamically fetch fields at run time rather than statically binding them at design time. For example, if you have declared a recordset object directly from `CRecordset`, you must use `GetFieldValue` to retrieve the field data; record field exchange (RFX), or bulk record field exchange (Bulk RFX), is not implemented. +You can use `GetFieldValue` to dynamically fetch fields at run time rather than statically binding them at design time. For example, if you've declared a recordset object directly from `CRecordset`, you must use `GetFieldValue` to retrieve the field data; record field exchange (RFX), or bulk record field exchange (Bulk RFX), isn't implemented. > [!NOTE] -> If you declare a recordset object without deriving from `CRecordset`, do not have the ODBC Cursor Library loaded. The cursor library requires that the recordset have at least one bound column; however, when you use `CRecordset` directly, none of the columns are bound. The member functions [`CDatabase::OpenEx`](../../mfc/reference/cdatabase-class.md#openex) and [`CDatabase::Open`](../../mfc/reference/cdatabase-class.md#open) control whether the cursor library will be loaded. +> If you declare a recordset object without deriving from `CRecordset`, don't have the ODBC Cursor Library loaded. The cursor library requires that the recordset have at least one bound column; however, when you use `CRecordset` directly, none of the columns are bound. The member functions [`CDatabase::OpenEx`](../../mfc/reference/cdatabase-class.md#openex) and [`CDatabase::Open`](../../mfc/reference/cdatabase-class.md#open) control whether the cursor library will be loaded. `GetFieldValue` calls the ODBC API function `SQLGetData`. If your driver outputs the value SQL_NO_TOTAL for the actual length of the field value, `GetFieldValue` throws an exception. For more information about `SQLGetData`, see the Windows SDK. @@ -651,25 +660,25 @@ The following sample code illustrates calls to `GetFieldValue` for a recordset o [!code-cpp[NVC_MFCDatabase#23](../../mfc/codesnippet/cpp/crecordset-class_7.cpp)] > [!NOTE] -> Unlike the DAO class `CDaoRecordset`, `CRecordset` does not have a `SetFieldValue` member function. If you create an object directly from `CRecordset`, it is effectively read-only. +> Unlike the DAO class `CDaoRecordset`, `CRecordset` doesn't have a `SetFieldValue` member function. If you create an object directly from `CRecordset`, it's effectively read-only. -For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::GetODBCFieldCount` Retrieves the total number of fields in your recordset object. -``` +```cpp short GetODBCFieldCount() const; ``` -### Return Value +### Return value The number of fields in the recordset. ### Remarks -For more information about creating recordsets, see the article [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). +For more information about creating recordsets, see [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). ## `CRecordset::GetODBCFieldInfo` @@ -687,13 +696,13 @@ void GetODBCFieldInfo( ### Parameters -*`lpszName`*
+*`lpszName`*\ The name of a field. -*`fieldinfo`*
+*`fieldinfo`*\ A reference to a `CODBCFieldInfo` structure. -*`nIndex`*
+*`nIndex`*\ The zero-based index of the field. ### Remarks @@ -702,64 +711,64 @@ One version of the function lets you look up a field by name. The other version For a description about the information returned, see the [`CODBCFieldInfo`](../../mfc/reference/codbcfieldinfo-structure.md) structure. -For more information about creating recordsets, see the article [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). +For more information about creating recordsets, see [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). ## `CRecordset::GetRecordCount` Determines the size of the recordset. -``` +```cpp long GetRecordCount() const; ``` -### Return Value +### Return value -The number of records in the recordset; 0 if the recordset contains no records; or -1 if the record count cannot be determined. +The number of records in the recordset; 0 if the recordset contains no records; or -1 if the record count can't be determined. ### Remarks > [!CAUTION] -> The record count is maintained as a "high water mark," the highest-numbered record yet seen as the user moves through the records. The total number of records is only known after the user has moved beyond the last record. For performance reasons, the count is not updated when you call `MoveLast`. To count the records yourself, call `MoveNext` repeatedly until `IsEOF` returns nonzero. Adding a record via `CRecordset:AddNew` and `Update` increases the count; deleting a record via `CRecordset::Delete` decreases the count. +> The record count is maintained as a "high water mark," the highest-numbered record yet seen as the user moves through the records. The total number of records is only known after the user has moved beyond the last record. For performance reasons, the count isn't updated when you call `MoveLast`. To count the records yourself, call `MoveNext` repeatedly until `IsEOF` returns nonzero. Adding a record via `CRecordset::AddNew` and `Update` increases the count; deleting a record via `CRecordset::Delete` decreases the count. ## `CRecordset::GetRowsetSize` Obtains the current setting for the number of rows you wish to retrieve during a given fetch. -``` +```cpp DWORD GetRowsetSize() const; ``` -### Return Value +### Return value The number of rows to retrieve during a given fetch. ### Remarks -If you are using bulk row fetching, the default rowset size when the recordset is opened is 25; otherwise, it is 1. +If you're using bulk row fetching, the default rowset size when the recordset is opened is 25; otherwise, it's 1. To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. To change the setting for the rowset size, call [`SetRowsetSize`](#setrowsetsize). -For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::GetRowsFetched` -Determines how many records were actually retrieved after a fetch. +Determines how many records were retrieved after a fetch. -``` +```cpp DWORD GetRowsFetched() const; ``` -### Return Value +### Return value The number of rows retrieved from the data source after a given fetch. ### Remarks -This is useful when you have implemented bulk row fetching. The rowset size normally indicates how many rows will be retrieved from a fetch; however, the total number of rows in the recordset also affects how many rows will be retrieved in a rowset. For example, if your recordset has 10 records with a rowset size setting of 4, then looping through the recordset by calling `MoveNext` will result in the final rowset having only 2 records. +This is useful when you've implemented bulk row fetching. The rowset size normally indicates how many rows will be retrieved from a fetch. However, the total number of rows in the recordset also affects how many rows will be retrieved in a rowset. For example, if your recordset has 10 records with a rowset size setting of four, then looping through the recordset by calling `MoveNext` will result in the final rowset having only two records. To implement bulk row fetching, you must specify the `CRecordset::useMultiRowFetch` option in the *dwOptions* parameter of the [`Open`](#open) member function. To specify the rowset size, call [SetRowsetSize](#setrowsetsize). -For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ### Example @@ -769,16 +778,16 @@ For more information about bulk row fetching, see the article [Recordset: Fetchi Obtains the status for a row in the current rowset. -``` +```cpp WORD GetRowStatus(WORD wRow) const; ``` ### Parameters -*`wRow`*
+*`wRow`*\ The one-based position of a row in the current rowset. This value can range from 1 to the size of the rowset. -### Return Value +### Return value A status value for the row. For details, see Remarks. @@ -793,7 +802,7 @@ A status value for the row. For details, see Remarks. |`SQL_ROW_DELETED`|The row has been deleted.| |`SQL_ROW_ADDED`|The row has been added.| |`SQL_ROW_ERROR`|The row is unretrievable due to an error.| -|`SQL_ROW_NOROW`|There is no row that corresponds to *`wRow`*.| +|`SQL_ROW_NOROW`|No row corresponds to *`wRow`*.| For more information, see the ODBC API function `SQLExtendedFetch` in the Windows SDK. @@ -807,8 +816,8 @@ void GetStatus(CRecordsetStatus& rStatus) const; ### Parameters -*`rStatus`*
-A reference to a `CRecordsetStatus` object. See the Remarks section for more information. +*`rStatus`*\ +A reference to a `CRecordsetStatus` object. For more information, see [Remarks](#remarks). ### Remarks @@ -826,7 +835,7 @@ struct CRecordsetStatus The two members of `CRecordsetStatus` have the following meanings: -- `m_lCurrentRecord` Contains the zero-based index of the current record in the recordset, if known. If the index cannot be determined, this member contains `AFX_CURRENT_RECORD_UNDEFINED` (-2). If `IsBOF` is TRUE (empty recordset or attempt to scroll before first record), then `m_lCurrentRecord` is set to `AFX_CURRENT_RECORD_BOF` (-1). If on the first record, then it is set to 0, second record 1, and so on. +- `m_lCurrentRecord` Contains the zero-based index of the current record in the recordset, if known. If the index can't be determined, this member contains `AFX_CURRENT_RECORD_UNDEFINED` (-2). If `IsBOF` is TRUE (empty recordset or attempt to scroll before first record), then `m_lCurrentRecord` is set to `AFX_CURRENT_RECORD_BOF` (-1). If on the first record, then it's set to 0, second record 1, and so on. - `m_bRecordCountFinal` Nonzero if the total number of records in the recordset has been determined. Generally this must be accomplished by starting at the beginning of the recordset and calling `MoveNext` until `IsEOF` returns nonzero. If this member is zero, the record count as returned by `GetRecordCount`, if not -1, is only a "high water mark" count of the records. @@ -834,11 +843,11 @@ The two members of `CRecordsetStatus` have the following meanings: Call this member function to get the SQL statement that was used to select the recordset's records when it was opened. -``` +```cpp const CString& GetSQL() const; ``` -### Return Value +### Return value A **`const`** reference to a `CString` that contains the SQL statement. @@ -846,7 +855,7 @@ A **`const`** reference to a `CString` that contains the SQL statement. This will generally be a SQL **`SELECT`** statement. The string returned by `GetSQL` is read-only. -The string returned by `GetSQL` is typically different from any string you may have passed to the recordset in the *`lpszSQL`* parameter to the `Open` member function. This is because the recordset constructs a full SQL statement based on what you passed to `Open`, what you specified with `ClassWizard`, what you may have specified in the `m_strFilter` and `m_strSort` data members, and any parameters you may have specified. For details about how the recordset constructs this SQL statement, see the article [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). +The string returned by `GetSQL` is typically different from any string you may have passed to the recordset in the *`lpszSQL`* parameter to the `Open` member function. This is because the recordset constructs a full SQL statement based on what you passed to `Open`, what you specified with `ClassWizard`, what you may have specified in the `m_strFilter` and `m_strSort` data members, and any parameters you may have specified. For details about how the recordset constructs this SQL statement, see [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). > [!NOTE] > Call this member function only after calling [`Open`](#open). @@ -855,11 +864,11 @@ The string returned by `GetSQL` is typically different from any string you may h Gets the name of the SQL table on which the recordset's query is based. -``` +```cpp const CString& GetTableName() const; ``` -### Return Value +### Return value A **`const`** reference to a `CString` that contains the table name, if the recordset is based on a table; otherwise, an empty string. @@ -872,21 +881,21 @@ A **`const`** reference to a `CString` that contains the table name, if the reco ## `CRecordset::IsBOF` -Returns nonzero if the recordset has been positioned before the first record. There is no current record. +Returns nonzero if the recordset has been positioned before the first record. There's no current record. -``` +```cpp BOOL IsBOF() const; ``` -### Return Value +### Return value -Nonzero if the recordset contains no records or if you have scrolled backward before the first record; otherwise 0. +Nonzero if the recordset contains no records or if you've scrolled backward before the first record; otherwise 0. ### Remarks -Call this member function before you scroll from record to record to learn whether you have gone before the first record of the recordset. You can also use `IsBOF` along with `IsEOF` to determine whether the recordset contains any records or is empty. Immediately after you call `Open`, if the recordset contains no records, `IsBOF` returns nonzero.When you open a recordset that has at least one record, the first record is the current record and `IsBOF` returns 0. +Call this member function before you scroll from record to record to learn whether you've gone before the first record of the recordset. You can also use `IsBOF` along with `IsEOF` to determine whether the recordset contains any records or is empty. Immediately after you call `Open`, if the recordset contains no records, `IsBOF` returns nonzero. When you open a recordset that has at least one record, the first record is the current record and `IsBOF` returns 0. -If the first record is the current record and you call `MovePrev`, `IsBOF` will subsequently return nonzero. If `IsBOF` returns nonzero and you call `MovePrev`, an error occurs. If `IsBOF` returns nonzero, the current record is undefined, and any action that requires a current record will result in an error. +If the first record is the current record and you call `MovePrev`, `IsBOF` will return nonzero. If `IsBOF` returns nonzero and you call `MovePrev`, an error occurs. If `IsBOF` returns nonzero, the current record is undefined, and any action that requires a current record will result in an error. ### Example @@ -898,11 +907,11 @@ This example uses `IsBOF` and `IsEOF` to detect the limits of a recordset as the Determines whether the current record has been deleted. -``` +```cpp BOOL IsDeleted() const; ``` -### Return Value +### Return value Nonzero if the recordset is positioned on a deleted record; otherwise 0. @@ -915,25 +924,25 @@ The result of `IsDeleted` depends on many factors, such as your recordset type, For more information about `CRecordset::skipDeletedRecords` and driver packing, see the [Open](#open) member function. > [!NOTE] -> If you have implemented bulk row fetching, you should not call `IsDeleted`. Instead, call the [GetRowStatus](#getrowstatus) member function. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you should not call `IsDeleted`. Instead, call the [GetRowStatus](#getrowstatus) member function. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::IsEOF` -Returns nonzero if the recordset has been positioned after the last record. There is no current record. +Returns nonzero if the recordset has been positioned after the last record. There's no current record. -``` +```cpp BOOL IsEOF() const; ``` -### Return Value +### Return value -Nonzero if the recordset contains no records or if you have scrolled beyond the last record; otherwise 0. +Nonzero if the recordset contains no records or if you've scrolled beyond the last record; otherwise 0. ### Remarks -Call this member function as you scroll from record to record to learn whether you have gone beyond the last record of the recordset. You can also use `IsEOF` to determine whether the recordset contains any records or is empty. Immediately after you call `Open`, if the recordset contains no records, `IsEOF` returns nonzero. When you open a recordset that has at least one record, the first record is the current record and `IsEOF` returns 0. +Call this member function as you scroll from record to record to learn whether you've gone beyond the last record of the recordset. You can also use `IsEOF` to determine whether the recordset contains any records or is empty. Immediately after you call `Open`, if the recordset contains no records, `IsEOF` returns nonzero. When you open a recordset that has at least one record, the first record is the current record and `IsEOF` returns 0. -If the last record is the current record when you call `MoveNext`, `IsEOF` will subsequently return nonzero. If `IsEOF` returns nonzero and you call `MoveNext`, an error occurs. If `IsEOF` returns nonzero, the current record is undefined, and any action that requires a current record will result in an error. +If the last record is the current record when you call `MoveNext`, `IsEOF` will return nonzero. If `IsEOF` returns nonzero and you call `MoveNext`, an error occurs. If `IsEOF` returns nonzero, the current record is undefined, and any action that requires a current record will result in an error. ### Example @@ -943,16 +952,16 @@ See the example for [`IsBOF`](#isbof). Determines whether the specified field data member has been changed since [`Edit`](#edit) or [`AddNew`](#addnew) was called. -``` +```cpp BOOL IsFieldDirty(void* pv); ``` ### Parameters -*`pv`*
+*`pv`*\ A pointer to the field data member whose status you want to check, or `NULL` to determine if any of the fields are dirty. -### Return Value +### Return value Nonzero if the specified field data member has changed since calling `AddNew` or `Edit`; otherwise 0. @@ -961,37 +970,37 @@ Nonzero if the specified field data member has changed since calling `AddNew` or The data in all dirty field data members will be transferred to the record on the data source when the current record is updated by a call to the [`Update`](#update) member function of `CRecordset` (following a call to `Edit` or `AddNew`). > [!NOTE] -> This member function is not applicable on recordsets that are using bulk row fetching. If you have implemented bulk row fetching, then `IsFieldDirty` will always return FALSE and will result in a failed assertion. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> This member function isn't applicable on recordsets that are using bulk row fetching. If you've implemented bulk row fetching, then `IsFieldDirty` will always return FALSE and will result in a failed assertion. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -Calling `IsFieldDirty` will reset the effects of preceding calls to [SetFieldDirty](#setfielddirty) since the dirty status of the field is re-evaluated. In the `AddNew` case, if the current field value differs from the pseudo null value, the field status is set dirty. In the `Edit` case, if the field value differs from the cached value, then the field status is set dirty. +Calling `IsFieldDirty` will reset the effects of preceding calls to [SetFieldDirty](#setfielddirty) since the dirty status of the field is reevaluated. In the `AddNew` case, if the current field value differs from the pseudo null value, the field status is set dirty. In the `Edit` case, if the field value differs from the cached value, then the field status is set dirty. `IsFieldDirty` is implemented through [`DoFieldExchange`](#dofieldexchange). -For more information on the dirty flag, see the article [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). +For more information on the dirty flag, see [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). ## `CRecordset::IsFieldNull` Returns nonzero if the specified field in the current record is Null (has no value). -``` +```cpp BOOL IsFieldNull(void* pv); ``` ### Parameters -*`pv`*
+*`pv`*\ A pointer to the field data member whose status you want to check, or `NULL` to determine if any of the fields are Null. -### Return Value +### Return value Nonzero if the specified field data member is flagged as Null; otherwise 0. ### Remarks -Call this member function to determine whether the specified field data member of a recordset has been flagged as Null. (In database terminology, Null means "having no value" and is not the same as NULL in C++.) If a field data member is flagged as Null, it is interpreted as a column of the current record for which there is no value. +Call this member function to determine whether the specified field data member of a recordset has been flagged as Null. (In database terminology, Null means "having no value" and isn't the same as `NULL` in C++.) If a field data member is flagged as Null, it's interpreted as a column of the current record for which there's no value. > [!NOTE] -> This member function is not applicable on recordsets that are using bulk row fetching. If you have implemented bulk row fetching, then `IsFieldNull` will always return `FALSE` and will result in a failed assertion. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> This member function isn't applicable on recordsets that are using bulk row fetching. If you've implemented bulk row fetching, then `IsFieldNull` will always return `FALSE` and will result in a failed assertion. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). `IsFieldNull` is implemented through [`DoFieldExchange`](#dofieldexchange). @@ -999,23 +1008,23 @@ Call this member function to determine whether the specified field data member o Returns nonzero if the specified field in the current record can be set to Null (having no value). -``` +```cpp BOOL IsFieldNullable(void* pv); ``` ### Parameters -*`pv`*
+*`pv`*\ A pointer to the field data member whose status you want to check, or `NULL` to determine if any of the fields can be set to a Null value. ### Remarks -Call this member function to determine whether the specified field data member is "nullable" (can be set to a Null value; C++ `NULL` is not the same as Null, which, in database terminology, means "having no value"). +Call this member function to determine whether the specified field data member is "nullable" (can be set to a Null value; C++ `NULL` isn't the same as Null, which, in database terminology, means "having no value"). > [!NOTE] -> If you have implemented bulk row fetching, you cannot call `IsFieldNullable`. Instead, call the [`GetODBCFieldInfo`](#getodbcfieldinfo) member function to determine whether a field can be set to a Null value. Note that you can always call `GetODBCFieldInfo`, regardless of whether you have implemented bulk row fetching. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you can't call `IsFieldNullable`. Instead, call the [`GetODBCFieldInfo`](#getodbcfieldinfo) member function to determine whether a field can be set to a Null value. You can always call `GetODBCFieldInfo`, regardless of whether you've implemented bulk row fetching. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -A field that cannot be Null must have a value. If you attempt to set a such a field to Null when adding or updating a record, the data source rejects the addition or update, and [`Update`](#update) will throw an exception. The exception occurs when you call `Update`, not when you call [`SetFieldNull`](#setfieldnull). +A field that can't be Null must have a value. If you attempt to set a such a field to Null when adding or updating a record, the data source rejects the addition or update, and [`Update`](#update) will throw an exception. The exception occurs when you call `Update`, not when you call [`SetFieldNull`](#setfieldnull). Using `NULL` for the first argument of the function will apply the function only to `outputColumn` fields, not `param` fields. For instance, the call @@ -1027,7 +1036,7 @@ To work on `param` fields, you must supply the actual address of the individual [!code-cpp[NVC_MFCDatabase#27](../../mfc/codesnippet/cpp/crecordset-class_11.cpp)] -This means you cannot set all `param` fields to `NULL`, as you can with `outputColumn` fields. +This means you can't set all `param` fields to `NULL`, as you can with `outputColumn` fields. `IsFieldNullable` is implemented through [DoFieldExchange](#dofieldexchange). @@ -1035,13 +1044,13 @@ This means you cannot set all `param` fields to `NULL`, as you can with `outputC Determines if the recordset is already open. -``` +```cpp BOOL IsOpen() const; ``` -### Return Value +### Return value -Nonzero if the recordset object's [`Open`](#open) or [`Requery`](#requery) member function has previously been called and the recordset has not been closed; otherwise 0. +Nonzero if the recordset object's [`Open`](#open) or [`Requery`](#requery) member function has previously been called and the recordset hasn't been closed; otherwise 0. ## `CRecordset::m_hstmt` @@ -1052,9 +1061,9 @@ Contains a handle to the ODBC statement data structure, of type `HSTMT`, associa Each query to an ODBC data source is associated with an `HSTMT`. > [!CAUTION] -> Do not use `m_hstmt` before [`Open`](#open) has been called. +> Don't use `m_hstmt` before [`Open`](#open) has been called. -Normally you do not need to access the `HSTMT` directly, but you might need it for direct execution of SQL statements. The `ExecuteSQL` member function of class `CDatabase` provides an example of using `m_hstmt`. +Normally you don't need to access the `HSTMT` directly, but you might need it for direct execution of SQL statements. The `ExecuteSQL` member function of class `CDatabase` provides an example of using `m_hstmt`. ## `CRecordset::m_nFields` @@ -1062,7 +1071,7 @@ Contains the number of field data members in the recordset class; that is, the n ### Remarks -The constructor for the recordset class must initialize `m_nFields` with the correct number. If you have not implemented bulk row fetching, `ClassWizard` writes this initialization for you when you use it to declare your recordset class. You can also write it manually. +The constructor for the recordset class must initialize `m_nFields` with the correct number. If you haven't implemented bulk row fetching, `ClassWizard` writes this initialization for you when you use it to declare your recordset class. You can also write it manually. The framework uses this number to manage interaction between the field data members and the corresponding columns of the current record on the data source. @@ -1075,7 +1084,7 @@ For more information, see the articles [Recordset: Dynamically Binding Data Colu ### Example -See the article [Record Field Exchange: Using RFX](../../data/odbc/record-field-exchange-using-rfx.md). +see [Record Field Exchange: Using RFX](../../data/odbc/record-field-exchange-using-rfx.md). ## `CRecordset::m_nParams` @@ -1102,7 +1111,7 @@ Contains a pointer to the `CDatabase` object through which the recordset is conn This variable is set in two ways. Typically, you pass a pointer to an already connected `CDatabase` object when you construct the recordset object. If you pass `NULL` instead, `CRecordset` creates a `CDatabase` object for you and connects it. In either case, `CRecordset` stores the pointer in this variable. -Normally you will not directly need to use the pointer stored in `m_pDatabase`. If you write your own extensions to `CRecordset`, however, you might need to use the pointer. For example, you might need the pointer if you throw your own `CDBException`s. Or you might need it if you need to do something using the same `CDatabase` object, such as running transactions, setting timeouts, or calling the `ExecuteSQL` member function of class `CDatabase` to execute SQL statements directly. +Normally you won't directly need to use the pointer stored in `m_pDatabase`. If you write your own extensions to `CRecordset`, however, you might need to use the pointer. For example, you might need the pointer if you throw your own `CDBException`s. Or you might need it if you need to do something using the same `CDatabase` object, such as running transactions, setting timeouts, or calling the `ExecuteSQL` member function of class `CDatabase` to execute SQL statements directly. ## `CRecordset::m_strFilter` @@ -1114,11 +1123,11 @@ The recordset uses this string to constrain (or filter) the records it selects d `WHERE search-condition` -Note that you do not include the **`WHERE`** keyword in your string. The framework supplies it. +Don't include the **`WHERE`** keyword in your string. The framework supplies it. -You can also parameterize your filter string by placing '' placeholders in it, declaring a parameter data member in your class for each placeholder, and passing parameters to the recordset at run time. This lets you construct the filter at run time. For more information, see the article [Recordset: Parameterizing a Recordset (ODBC)](../../data/odbc/recordset-parameterizing-a-recordset-odbc.md). +You can also parameterize your filter string by placing '' placeholders in it, declaring a parameter data member in your class for each placeholder, and passing parameters to the recordset at run time. This lets you construct the filter at run time. For more information, see [Recordset: Parameterizing a Recordset (ODBC)](../../data/odbc/recordset-parameterizing-a-recordset-odbc.md). -For more information about SQL **`WHERE`** clauses, see the article [SQL](../../data/odbc/sql.md). For more information about selecting and filtering records, see the article [Recordset: Filtering Records (ODBC)](../../data/odbc/recordset-filtering-records-odbc.md). +For more information about SQL **`WHERE`** clauses, see [SQL](../../data/odbc/sql.md). For more information about selecting and filtering records, see [Recordset: Filtering Records (ODBC)](../../data/odbc/recordset-filtering-records-odbc.md). ### Example @@ -1136,9 +1145,9 @@ The recordset uses this string to sort the records it selects during the `Open` where a sort-specification is an integer or a column name. You can also specify ascending or descending order (the order is ascending by default) by appending "ASC" or "DESC" to the column list in the sort string. The selected records are sorted first by the first column listed, then by the second, and so on. For example, you might order a "Customers" recordset by last name, then first name. The number of columns you can list depends on the data source. For more information, see the Windows SDK. -Note that you do not include the **`ORDER BY`** keyword in your string. The framework supplies it. +Don't include the **`ORDER BY`** keyword in your string. The framework supplies it. -For more information about SQL clauses, see the article [SQL](../../data/odbc/sql.md). For more information about sorting records, see the article [Recordset: Sorting Records (ODBC)](../../data/odbc/recordset-sorting-records-odbc.md). +For more information about SQL clauses, see [SQL](../../data/odbc/sql.md). For more information about sorting records, see [Recordset: Sorting Records (ODBC)](../../data/odbc/recordset-sorting-records-odbc.md). ### Example @@ -1148,7 +1157,7 @@ For more information about SQL clauses, see the article [SQL](../../data/odbc/sq Moves the current record pointer within the recordset, either forward or backward. -``` +```cpp virtual void Move( long nRows, WORD wFetchType = SQL_FETCH_RELATIVE); @@ -1156,10 +1165,10 @@ virtual void Move( ### Parameters -*`nRows`*
+*`nRows`*\ The number of rows to move forward or backward. Positive values move forward, toward the end of the recordset. Negative values move backward, toward the beginning. -*`wFetchType`*
+*`wFetchType`*\ Determines the rowset that `Move` will fetch. For details, see Remarks. ### Remarks @@ -1167,9 +1176,9 @@ Determines the rowset that `Move` will fetch. For details, see Remarks. If you pass a value of 0 for *`nRows`*, `Move` refreshes the current record; `Move` will end any current `AddNew` or `Edit` mode, and will restore the current record's value before `AddNew` or `Edit` was called. > [!NOTE] -> When you move through a recordset, you cannot skip deleted records. See [`CRecordset::IsDeleted`](#isdeleted) for more information. When you open a `CRecordset` with the `skipDeletedRecords` option set, `Move` asserts if the *`nRows`* parameter is 0. This behavior prevents the refresh of rows that are deleted by other client applications using the same data. See the *`dwOption`* parameter in [`Open`](#open) for a description of `skipDeletedRecords`. +> When you move through a recordset, you can't skip deleted records. See [`CRecordset::IsDeleted`](#isdeleted) for more information. When you open a `CRecordset` with the `skipDeletedRecords` option set, `Move` asserts if the *`nRows`* parameter is 0. This behavior prevents the refresh of rows that are deleted by other client applications using the same data. See the *`dwOption`* parameter in [`Open`](#open) for a description of `skipDeletedRecords`. -`Move` repositions the recordset by rowsets. Based on the values for *`nRows`* and *`wFetchType`*, `Move` fetches the appropriate rowset and then makes the first record in that rowset the current record. If you have not implemented bulk row fetching, then the rowset size is always 1. When fetching a rowset, `Move` directly calls the [`CheckRowsetError`](#checkrowseterror) member function to handle any errors resulting from the fetch. +`Move` repositions the recordset by rowsets. Based on the values for *`nRows`* and *`wFetchType`*, `Move` fetches the appropriate rowset and then makes the first record in that rowset the current record. If you haven't implemented bulk row fetching, then the rowset size is always 1. When fetching a rowset, `Move` directly calls the [`CheckRowsetError`](#checkrowseterror) member function to handle any errors resulting from the fetch. Depending on the values you pass, `Move` is equivalent to other `CRecordset` member functions. In particular, the value of *`wFetchType`* may indicate a member function that is more intuitive and often the preferred method for moving the current record. @@ -1192,12 +1201,12 @@ The following table lists the possible values for *`wFetchType`*, the rowset tha > Calling `Move` throws an exception if the recordset has no records. To determine whether the recordset has any records, call [`IsBOF`](#isbof) and [`IsEOF`](#iseof). > [!NOTE] -> If you have scrolled past the beginning or end of the recordset (`IsBOF` or `IsEOF` returns nonzero), calling a `Move` function will possibly throw a `CDBException`. For example, if `IsEOF` returns nonzero and `IsBOF` does not, then `MoveNext` will throw an exception, but `MovePrev` will not. +> If you've scrolled past the beginning or end of the recordset (`IsBOF` or `IsEOF` returns nonzero), calling a `Move` function will possibly throw a `CDBException`. For example, if `IsEOF` returns nonzero and `IsBOF` doesn't, then `MoveNext` will throw an exception, but `MovePrev` won't. > [!NOTE] > If you call `Move` while the current record is being updated or added, the updates are lost without warning. -For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). For related information, see the ODBC API function `SQLExtendedFetch` in the Windows SDK. +For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). For related information, see the ODBC API function `SQLExtendedFetch` in the Windows SDK. ### Example @@ -1215,13 +1224,13 @@ void MoveFirst(); Regardless of whether bulk row fetching has been implemented, this will always be the first record in the recordset. -You do not have to call `MoveFirst` immediately after you open the recordset. At that time, the first record (if any) is automatically the current record. +You don't have to call `MoveFirst` immediately after you open the recordset. At that time, the first record (if any) is automatically the current record. > [!NOTE] -> This member function is not valid for forward-only recordsets. +> This member function isn't valid for forward-only recordsets. > [!NOTE] -> When you move through a recordset, you cannot skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. +> When you move through a recordset, you can't skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. To determine whether the recordset has any records, call `IsBOF` and `IsEOF`. @@ -1229,7 +1238,7 @@ You do not have to call `MoveFirst` immediately after you open the recordset. At > [!NOTE] > If you call any of the `Move` functions while the current record is being updated or added, the updates are lost without warning. -For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ### Example @@ -1245,13 +1254,13 @@ void MoveLast(); ### Remarks -If you have not implemented bulk row fetching, your recordset has a rowset size of 1, so `MoveLast` simply moves to the last record in the recordset. +If you haven't implemented bulk row fetching, your recordset has a rowset size of 1, so `MoveLast` moves to the last record in the recordset. > [!NOTE] -> This member function is not valid for forward-only recordsets. +> This member function isn't valid for forward-only recordsets. > [!NOTE] -> When you move through a recordset, you cannot skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. +> When you move through a recordset, you can't skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. To determine whether the recordset has any records, call `IsBOF` and `IsEOF`. @@ -1259,7 +1268,7 @@ If you have not implemented bulk row fetching, your recordset has a rowset size > [!NOTE] > If you call any of the `Move` functions while the current record is being updated or added, the updates are lost without warning. -For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ### Example @@ -1275,21 +1284,21 @@ void MoveNext(); ### Remarks -If you have not implemented bulk row fetching, your recordset has a rowset size of 1, so `MoveNext` simply moves to the next record. +If you haven't implemented bulk row fetching, your recordset has a rowset size of 1, so `MoveNext` moves to the next record. > [!NOTE] -> When you move through a recordset, you cannot skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. +> When you move through a recordset, you can't skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. To determine whether the recordset has any records, call `IsBOF` and `IsEOF`. > [!NOTE] -> It is also recommended that you call `IsEOF` before calling `MoveNext`. For example, if you have scrolled past the end of the recordset, `IsEOF` will return nonzero; a subsequent call to `MoveNext` would throw an exception. +> It's also recommended that you call `IsEOF` before calling `MoveNext`. For example, if you've scrolled past the end of the recordset, `IsEOF` will return nonzero; a subsequent call to `MoveNext` would throw an exception. > [!NOTE] > If you call any of the `Move` functions while the current record is being updated or added, the updates are lost without warning. -For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ### Example @@ -1305,24 +1314,24 @@ void MovePrev(); ### Remarks -If you have not implemented bulk row fetching, your recordset has a rowset size of 1, so `MovePrev` simply moves to the previous record. +If you haven't implemented bulk row fetching, your recordset has a rowset size of 1, so `MovePrev` moves to the previous record. > [!NOTE] -> This member function is not valid for forward-only recordsets. +> This member function isn't valid for forward-only recordsets. > [!NOTE] -> When you move through a recordset, you cannot skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. +> When you move through a recordset, you can't skip deleted records. See the [`IsDeleted`](#isdeleted) member function for details. > [!CAUTION] > Calling any of the `Move` functions throws an exception if the recordset has no records. To determine whether the recordset has any records, call `IsBOF` and `IsEOF`. > [!NOTE] -> It is also recommended that you call `IsBOF` before calling `MovePrev`. For example, if you have scrolled ahead of the beginning of the recordset, `IsBOF` will return nonzero; a subsequent call to `MovePrev` would throw an exception. +> It's also recommended that you call `IsBOF` before calling `MovePrev`. For example, if you've scrolled ahead of the beginning of the recordset, `IsBOF` will return nonzero; a subsequent call to `MovePrev` would throw an exception. > [!NOTE] > If you call any of the `Move` functions while the current record is being updated or added, the updates are lost without warning. -For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about recordset navigation, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ### Example @@ -1332,13 +1341,13 @@ For more information about recordset navigation, see the articles [Recordset: Sc Called to set options (used on selection) for the specified ODBC statement. -``` +```cpp virtual void OnSetOptions(HSTMT hstmt); ``` ### Parameters -*`hstmt`*
+*`hstmt`*\ The `HSTMT` of the ODBC statement whose options are to be set. ### Remarks @@ -1347,19 +1356,19 @@ Call `OnSetOptions` to set options (used on selection) for the specified ODBC st Override `OnSetOptions` to set options specific to the driver or the data source. For example, if your data source supports opening for exclusive access, you might override `OnSetOptions` to take advantage of that ability. -For more information about cursors, see the article [ODBC](../../data/odbc/odbc-basics.md). +For more information about cursors, see [ODBC](../../data/odbc/odbc-basics.md). ## `CRecordset::OnSetUpdateOptions` Called to set options (used on update) for the specified ODBC statement. -``` +```cpp virtual void OnSetUpdateOptions(HSTMT hstmt); ``` ### Parameters -*`hstmt`*
+*`hstmt`*\ The `HSTMT` of the ODBC statement whose options are to be set. ### Remarks @@ -1368,13 +1377,13 @@ Call `OnSetUpdateOptions` to set options (used on update) for the specified ODBC Override `OnSetUpdateOptions` to set options of an ODBC statement before that statement is used to access a database. -For more information about cursors, see the article [ODBC](../../data/odbc/odbc-basics.md). +For more information about cursors, see [ODBC](../../data/odbc/odbc-basics.md). ## `CRecordset::Open` Opens the recordset by retrieving the table or performing the query that the recordset represents. -``` +```cpp virtual BOOL Open( UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE, LPCTSTR lpszSQL = NULL, @@ -1383,25 +1392,25 @@ virtual BOOL Open( ### Parameters -*`nOpenType`*
+*`nOpenType`*\ Accept the default value, `AFX_DB_USE_DEFAULT_TYPE`, or use one of the following values from the `enum OpenType`: -- `CRecordset::dynaset` A recordset with bi-directional scrolling. The membership and ordering of the records are determined when the recordset is opened, but changes made by other users to the data values are visible following a fetch operation. Dynasets are also known as keyset-driven recordsets. +- `CRecordset::dynaset` A recordset with bi-directional scrolling. Opening the recordset determines the membership and ordering of the records, but changes made by other users to the data values are visible following a fetch operation. Dynasets are also known as keyset-driven recordsets. -- `CRecordset::snapshot` A static recordset with bi-directional scrolling. The membership and ordering of the records are determined when the recordset is opened; the data values are determined when the records are fetched. Changes made by other users are not visible until the recordset is closed and then reopened. +- `CRecordset::snapshot` A static recordset with bi-directional scrolling. Opening the recordset determines the membership and ordering of the records. Fetching a record determines the data values. Changes made by other users aren't visible until the recordset is closed and then reopened. -- `CRecordset::dynamic` A recordset with bi-directional scrolling. Changes made by other users to the membership, ordering, and data values are visible following a fetch operation. Note that many ODBC drivers do not support this type of recordset. +- `CRecordset::dynamic` A recordset with bi-directional scrolling. Changes made by other users to the membership, ordering, and data values are visible following a fetch operation. Many ODBC drivers don't support this type of recordset. - `CRecordset::forwardOnly` A read-only recordset with only forward scrolling. For `CRecordset`, the default value is `CRecordset::snapshot`. The default-value mechanism allows the Visual C++ wizards to interact with both ODBC `CRecordset` and DAO `CDaoRecordset`, which have different defaults. -For more information about these recordset types, see the article [Recordset (ODBC)](../../data/odbc/recordset-odbc.md). For related information, see the article "Using Block and Scrollable Cursors" in the Windows SDK. +For more information about these recordset types, see [Recordset (ODBC)](../../data/odbc/recordset-odbc.md). For related information, see "Using Block and Scrollable Cursors" in the Windows SDK. > [!CAUTION] -> If the requested type is not supported, the framework throws an exception. +> If the requested type isn't supported, the framework throws an exception. -*`lpszSQL`*
+*`lpszSQL`*\ A string pointer containing one of the following: - A `NULL` pointer. @@ -1410,39 +1419,39 @@ A string pointer containing one of the following: - A SQL **`SELECT`** statement (optionally with a SQL **`WHERE`** or **`ORDER BY`** clause). -- A **`CALL`** statement specifying the name of a predefined query (stored procedure). Be careful that you do not insert whitespace between the curly brace and the **`CALL`** keyword. +- A **`CALL`** statement specifying the name of a predefined query (stored procedure). Be careful to not insert whitespace between the curly brace and the **`CALL`** keyword. For more information about this string, see the table and the discussion of ClassWizard's role under the [Remarks](#remarks) section. > [!NOTE] > The order of the columns in your result set must match the order of the RFX or Bulk RFX function calls in your [`DoFieldExchange`](#dofieldexchange) or [`DoBulkFieldExchange`](#dobulkfieldexchange) function override. -*`dwOptions`*
-A bitmask which can specify a combination of the values listed below. Some of these are mutually exclusive. The default value is **`none`**. +*`dwOptions`*\ +A bitmask, which can specify a combination of the values listed below. Some of these are mutually exclusive. The default value is **`none`**. -- `CRecordset::none` No options set. This parameter value is mutually exclusive with all other values. By default, the recordset can be updated with [`Edit`](#edit) or [`Delete`](#delete) and allows appending new records with [`AddNew`](#addnew). Updatability depends on the data source as well as on the *`nOpenType`* option you specify. Optimization for bulk additions is not available. Bulk row fetching will not be implemented. Deleted records will not be skipped during recordset navigation. Bookmarks are not available. Automatic dirty field checking is implemented. +- `CRecordset::none` No options set. This parameter value is mutually exclusive with all other values. By default, the recordset can be updated with [`Edit`](#edit) or [`Delete`](#delete) and allows appending new records with [`AddNew`](#addnew). Updatability depends on the data source and the *`nOpenType`* option you specify. Optimization for bulk additions isn't available. Bulk row fetching won't be implemented. Deleted records won't be skipped during recordset navigation. Bookmarks aren't available. Automatic dirty field checking is implemented. -- `CRecordset::appendOnly` Do not allow `Edit` or `Delete` on the recordset. Allow `AddNew` only. This option is mutually exclusive with `CRecordset::readOnly`. +- `CRecordset::appendOnly` Don't allow `Edit` or `Delete` on the recordset. Allow `AddNew` only. This option is mutually exclusive with `CRecordset::readOnly`. - `CRecordset::readOnly` Open the recordset as read-only. This option is mutually exclusive with `CRecordset::appendOnly`. -- `CRecordset::optimizeBulkAdd` Use a prepared SQL statement to optimize adding many records at one time. Applies only if you are not using the ODBC API function `SQLSetPos` to update the recordset. The first update determines which fields are marked dirty. This option is mutually exclusive with `CRecordset::useMultiRowFetch`. +- `CRecordset::optimizeBulkAdd` Use a prepared SQL statement to optimize adding many records at one time. Applies only if you aren't using the ODBC API function `SQLSetPos` to update the recordset. The first update determines which fields are marked dirty. This option is mutually exclusive with `CRecordset::useMultiRowFetch`. -- `CRecordset::useMultiRowFetch` Implement bulk row fetching to allow multiple rows to be retrieved in a single fetch operation. This is an advanced feature designed to improve performance; however, bulk record field exchange is not supported by `ClassWizard`. This option is mutually exclusive with `CRecordset::optimizeBulkAdd`. Note that if you specify `CRecordset::useMultiRowFetch`, then the option `CRecordset::noDirtyFieldCheck` will be turned on automatically (double buffering will not be available); on forward-only recordsets, the option `CRecordset::useExtendedFetch` will be turned on automatically. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +- `CRecordset::useMultiRowFetch` Implement bulk row fetching to allow multiple rows to be retrieved in a single fetch operation. This is an advanced feature designed to improve performance; however, bulk record field exchange isn't supported by `ClassWizard`. This option is mutually exclusive with `CRecordset::optimizeBulkAdd`. If you specify `CRecordset::useMultiRowFetch`, then the option `CRecordset::noDirtyFieldCheck` will be turned on automatically (double buffering won't be available); on forward-only recordsets, the option `CRecordset::useExtendedFetch` will be turned on automatically. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -- `CRecordset::skipDeletedRecords` Skip all deleted records when navigating through the recordset. This will slow performance in certain relative fetches. This option is not valid on forward-only recordsets. If you call [`Move`](#move) with the *nRows* parameter set to 0, and the `CRecordset::skipDeletedRecords` option set, `Move` will assert. Note that `CRecordset::skipDeletedRecords` is similar to *driver packing*, which means that deleted rows are removed from the recordset. However, if your driver packs records, then it will skip only those records that you delete; it will not skip records deleted by other users while the recordset is open. `CRecordset::skipDeletedRecords` will skip rows deleted by other users. +- `CRecordset::skipDeletedRecords` Skip all deleted records when navigating through the recordset. This will slow performance in certain relative fetches. This option isn't valid on forward-only recordsets. If you call [`Move`](#move) with the *nRows* parameter set to 0, and the `CRecordset::skipDeletedRecords` option set, `Move` will assert. `CRecordset::skipDeletedRecords` is similar to *driver packing*, which means that deleted rows are removed from the recordset. However, if your driver packs records, then it will skip only those records that you delete; it won't skip records deleted by other users while the recordset is open. `CRecordset::skipDeletedRecords` will skip rows deleted by other users. -- `CRecordset::useBookmarks` May use bookmarks on the recordset, if supported. Bookmarks slow data retrieval but improve performance for data navigation. Not valid on forward-only recordsets. For more information, see the article [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). +- `CRecordset::useBookmarks` May use bookmarks on the recordset, if supported. Bookmarks slow data retrieval but improve performance for data navigation. Not valid on forward-only recordsets. For more information, see [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). -- `CRecordset::noDirtyFieldCheck` Turn off automatic dirty field checking (double buffering). This will improve performance; however, you must manually mark fields as dirty by calling the `SetFieldDirty` and `SetFieldNull` member functions.Note that double buffering in class `CRecordset` is similar to double buffering in class `CDaoRecordset`. However, in `CRecordset`, you cannot enable double buffering on individual fields; you either enable it for all fields or disable it for all fields. Note that if you specify the option `CRecordset::useMultiRowFetch`, then `CRecordset::noDirtyFieldCheck` will be turned on automatically; however, `SetFieldDirty` and `SetFieldNull` cannot be used on recordsets that implement bulk row fetching. +- `CRecordset::noDirtyFieldCheck` Turn off automatic dirty field checking (double buffering). This will improve performance; however, you must manually mark fields as dirty by calling the `SetFieldDirty` and `SetFieldNull` member functions. Double buffering in class `CRecordset` is similar to double buffering in class `CDaoRecordset`. However, in `CRecordset`, you can't enable double buffering on individual fields; you either enable it for all fields or disable it for all fields. If you specify the option `CRecordset::useMultiRowFetch`, then `CRecordset::noDirtyFieldCheck` is turned on automatically; however, `SetFieldDirty` and `SetFieldNull` can't be used on recordsets that implement bulk row fetching. -- `CRecordset::executeDirect` Do not use a prepared SQL statement. For improved performance, specify this option if the `Requery` member function will never be called. +- `CRecordset::executeDirect` Don't use a prepared SQL statement. For improved performance, specify this option if the `Requery` member function will never be called. - `CRecordset::useExtendedFetch` Implement `SQLExtendedFetch` instead of `SQLFetch`. This is designed for implementing bulk row fetching on forward-only recordsets. If you specify the option `CRecordset::useMultiRowFetch` on a forward-only recordset, then `CRecordset::useExtendedFetch` will be turned on automatically. -- `CRecordset::userAllocMultiRowBuffers` The user will allocate storage buffers for the data. Use this option in conjunction with `CRecordset::useMultiRowFetch` if you want to allocate your own storage; otherwise, the framework will automatically allocate the necessary storage. For more information, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). Note that specifying `CRecordset::userAllocMultiRowBuffers` without specifying `CRecordset::useMultiRowFetch` will result in a failed assertion. +- `CRecordset::userAllocMultiRowBuffers` The user will allocate storage buffers for the data. Use this option with `CRecordset::useMultiRowFetch` if you want to allocate your own storage. Otherwise, the framework will automatically allocate the necessary storage. For more information, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). Specifying `CRecordset::userAllocMultiRowBuffers` without specifying `CRecordset::useMultiRowFetch` results in a failed assertion. -### Return Value +### Return value Nonzero if the `CRecordset` object was successfully opened; otherwise 0 if [`CDatabase::Open`](../../mfc/reference/cdatabase-class.md#open) (if called) returns 0. @@ -1450,10 +1459,10 @@ Nonzero if the `CRecordset` object was successfully opened; otherwise 0 if [`CDa You must call this member function to run the query defined by the recordset. Before calling `Open`, you must construct the recordset object. -This recordset's connection to the data source depends on how you construct the recordset before calling `Open`. If you pass a [`CDatabase`](../../mfc/reference/cdatabase-class.md) object to the recordset constructor that has not been connected to the data source, this member function uses [`GetDefaultConnect`](#getdefaultconnect) to attempt to open the database object. If you pass NULL to the recordset constructor, the constructor constructs a `CDatabase` object for you, and `Open` attempts to connect the database object. For details on closing the recordset and the connection under these varying circumstances, see [`Close`](#close). +This recordset's connection to the data source depends on how you construct the recordset before calling `Open`. If you pass a [`CDatabase`](../../mfc/reference/cdatabase-class.md) object to the recordset constructor that hasn't been connected to the data source, this member function uses [`GetDefaultConnect`](#getdefaultconnect) to attempt to open the database object. If you pass NULL to the recordset constructor, the constructor constructs a `CDatabase` object for you, and `Open` attempts to connect the database object. For details on closing the recordset and the connection under these varying circumstances, see [`Close`](#close). > [!NOTE] -> Access to a data source through a `CRecordset` object is always shared. Unlike the `CDaoRecordset` class, you cannot use a `CRecordset` object to open a data source with exclusive access. +> Access to a data source through a `CRecordset` object is always shared. Unlike the `CDaoRecordset` class, you can't use a `CRecordset` object to open a data source with exclusive access. When you call `Open`, a query, usually a SQL **`SELECT`** statement, selects records based on criteria shown in the following table. @@ -1465,17 +1474,17 @@ When you call `Open`, a query, usually a SQL **`SELECT`** statement, selects rec |**`SELECT`** column-list **`FROM`** table-list|The specified columns from the specified table(s).|`"SELECT CustId, CustName FROM`

`Customer"`| > [!CAUTION] -> Be careful that you do not insert extra whitespace in your SQL string. For example, if you insert whitespace between the curly brace and the **`CALL`** keyword, MFC will misinterpret the SQL string as a table name and incorporate it into a **`SELECT`** statement, which will result in an exception being thrown. Similarly, if your predefined query uses an output parameter, do not insert whitespace between the curly brace and the '' symbol. Finally, you must not insert whitespace before the curly brace in a **`CALL`** statement or before the **`SELECT`** keyword in a **`SELECT`** statment. +> Don't insert extra whitespace in your SQL string. For example, if you insert whitespace between the curly brace and the **`CALL`** keyword, MFC will misinterpret the SQL string as a table name and incorporate it into a **`SELECT`** statement, which will result in an exception being thrown. Similarly, if your predefined query uses an output parameter, don't insert whitespace between the curly brace and the '' symbol. Finally, you must not insert whitespace before the curly brace in a **`CALL`** statement or before the **`SELECT`** keyword in a **`SELECT`** statement. -The usual procedure is to pass `NULL` to `Open`; in this case, `Open` calls [GetDefaultSQL](#getdefaultsql). If you are using a derived `CRecordset` class, `GetDefaultSQL` gives the table name(s) you specified in `ClassWizard`. You can instead specify other information in the `lpszSQL` parameter. +The usual procedure is to pass `NULL` to `Open`; in this case, `Open` calls [GetDefaultSQL](#getdefaultsql). If you're using a derived `CRecordset` class, `GetDefaultSQL` gives the table name(s) you specified in `ClassWizard`. You can instead specify other information in the `lpszSQL` parameter. -Whatever you pass, `Open` constructs a final SQL string for the query (the string may have SQL **`WHERE`** and **`ORDER BY`** clauses appended to the `lpszSQL` string you passed) and then executes the query. You can examine the constructed string by calling [`GetSQL`](#getsql) after calling `Open`. For additional details about how the recordset constructs a SQL statement and selects records, see the article [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). +Whatever you pass, `Open` constructs a final SQL string for the query (the string may have SQL **`WHERE`** and **`ORDER BY`** clauses appended to the `lpszSQL` string you passed) and then executes the query. You can examine the constructed string by calling [`GetSQL`](#getsql) after calling `Open`. For more details about how the recordset constructs a SQL statement and selects records, see [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md). The field data members of your recordset class are bound to the columns of the data selected. If any records are returned, the first record becomes the current record. If you want to set options for the recordset, such as a filter or sort, specify these after you construct the recordset object but before you call `Open`. If you want to refresh the records in the recordset after the recordset is already open, call [`Requery`](#requery). -For more information, including additional examples, see the articles [Recordset (ODBC)](../../data/odbc/recordset-odbc.md), [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md), and [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). +For more information, including more examples, see [Recordset (ODBC)](../../data/odbc/recordset-odbc.md), [Recordset: How Recordsets Select Records (ODBC)](../../data/odbc/recordset-how-recordsets-select-records-odbc.md), and [Recordset: Creating and Closing Recordsets (ODBC)](../../data/odbc/recordset-creating-and-closing-recordsets-odbc.md). ### Example @@ -1495,10 +1504,10 @@ void RefreshRowset( ### Parameters -*`wRow`*
+*`wRow`*\ The one-based position of a row in the current rowset. This value can range from zero to the size of the rowset. -*`wLockType`*
+*`wLockType`*\ A value indicating how to lock the row after it has been refreshed. For details, see Remarks. ### Remarks @@ -1515,17 +1524,17 @@ To use `RefreshRowset`, you must have implemented bulk row fetching by specifyin |`SQL_LOCK_EXCLUSIVE`|The driver or data source locks the row exclusively. Not all data sources support this type of lock.| |`SQL_LOCK_UNLOCK`|The driver or data source unlocks the row. Not all data sources support this type of lock.| -For more information about `SQLSetPos`, see the Windows SDK. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about `SQLSetPos`, see the Windows SDK. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::Requery` Rebuilds (refreshes) a recordset. -``` +```cpp virtual BOOL Requery(); ``` -### Return Value +### Return value Nonzero if the recordset was successfully rebuilt; otherwise 0. @@ -1533,14 +1542,14 @@ Nonzero if the recordset was successfully rebuilt; otherwise 0. If any records are returned, the first record becomes the current record. -In order for the recordset to reflect the additions and deletions that you or other users are making to the data source, you must rebuild the recordset by calling `Requery`. If the recordset is a dynaset, it automatically reflects updates that you or other users make to its existing records (but not additions). If the recordset is a snapshot, you must call `Requery` to reflect edits by other users as well as additions and deletions. +In order for the recordset to reflect the additions and deletions that you or other users are making to the data source, you must rebuild the recordset by calling `Requery`. If the recordset is a dynaset, it automatically reflects updates that you or other users make to its existing records (but not additions). If the recordset is a snapshot, you must call `Requery` to reflect edits by other users and additions and deletions. -For either a dynaset or a snapshot, call `Requery` any time you want to rebuild the recordset using a new filter or sort, or new parameter values. Set the new filter or sort property by assigning new values to `m_strFilter` and `m_strSort` before calling `Requery`. Set new parameters by assigning new values to parameter data members before calling `Requery`. If the filter and sort strings are unchanged, you can reuse the query, which improves performance. +For either a dynaset or a snapshot, call `Requery` anytime you want to rebuild the recordset using a new filter or sort, or new parameter values. Set the new filter or sort property by assigning new values to `m_strFilter` and `m_strSort` before calling `Requery`. Set new parameters by assigning new values to parameter data members before calling `Requery`. If the filter and sort strings are unchanged, you can reuse the query, which improves performance. -If the attempt to rebuild the recordset fails, the recordset is closed. Before you call `Requery`, you can determine whether the recordset can be requeried by calling the `CanRestart` member function. `CanRestart` does not guarantee that `Requery` will succeed. +If the attempt to rebuild the recordset fails, the recordset is closed. Before you call `Requery`, you can determine whether the recordset can be requeried by calling the `CanRestart` member function. `CanRestart` doesn't guarantee that `Requery` will succeed. > [!CAUTION] -> Call `Requery` only after you have called [`Open`](#open). +> Call `Requery` only after you've called [`Open`](#open). ### Example @@ -1558,7 +1567,7 @@ void SetAbsolutePosition(long nRows); ### Parameters -*`nRows`*
+*`nRows`*\ The one-based ordinal position for the current record in the recordset. ### Remarks @@ -1566,14 +1575,14 @@ The one-based ordinal position for the current record in the recordset. `SetAbsolutePosition` moves the current record pointer based on this ordinal position. > [!NOTE] -> This member function is not valid on forward-only recordsets. +> This member function isn't valid on forward-only recordsets. For ODBC recordsets, an absolute position setting of 1 refers to the first record in the recordset; a setting of 0 refers to the beginning-of-file (BOF) position. -You can also pass negative values to `SetAbsolutePosition`. In this case the recordset's position is evaluated from the end of the recordset. For example, `SetAbsolutePosition( -1 )` moves the current record pointer to the last record in the recordset. +You can also pass negative values to `SetAbsolutePosition`. In this case, the recordset's position is evaluated from the end of the recordset. For example, `SetAbsolutePosition( -1 )` moves the current record pointer to the last record in the recordset. > [!NOTE] -> Absolute position is not intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position, since a record's position changes when preceding records are deleted. In addition, you cannot be assured that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset is not guaranteed unless it is created with a SQL statement using an **`ORDER BY`** clause. +> Absolute position isn't intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position, since a record's position changes when preceding records are deleted. In addition, you can't be assured that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset isn't guaranteed unless it's created with a SQL statement using an **`ORDER BY`** clause. For more information about recordset navigation and bookmarks, see the articles [Recordset: Scrolling (ODBC)](../../data/odbc/recordset-scrolling-odbc.md) and [Recordset: Bookmarks and Absolute Positions (ODBC)](../../data/odbc/recordset-bookmarks-and-absolute-positions-odbc.md). @@ -1587,15 +1596,15 @@ void SetBookmark(const CDBVariant& varBookmark); ### Parameters -*`varBookmark`*
+*`varBookmark`*\ A reference to a [`CDBVariant`](../../mfc/reference/cdbvariant-class.md) object containing the bookmark value for a specific record. ### Remarks -To determine if bookmarks are supported on the recordset, call [`CanBookmark`](#canbookmark). To make bookmarks available if they are supported, you must set the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. +To determine if bookmarks are supported on the recordset, call [`CanBookmark`](#canbookmark). To make bookmarks available if they're supported, you must set the `CRecordset::useBookmarks` option in the *`dwOptions`* parameter of the [`Open`](#open) member function. > [!NOTE] -> If bookmarks are unsupported or unavailable, calling `SetBookmark` will result in an exception being thrown. Bookmarks are not supported on forward-only recordsets. +> If bookmarks are unsupported or unavailable, calling `SetBookmark` will result in an exception being thrown. Bookmarks aren't supported on forward-only recordsets. To first retrieve the bookmark for the current record, call [`GetBookmark`](#getbookmark), which saves the bookmark value to a `CDBVariant` object. Later, you can return to that record by calling `SetBookmark` using the saved bookmark value. @@ -1614,23 +1623,23 @@ void SetFieldDirty(void* pv, BOOL bDirty = TRUE); ### Parameters -*`pv`*
-Contains the address of a field data member in the recordset or `NUL`L. If `NULL`, all field data members in the recordset are flagged. (C++ `NULL` is not the same as Null in database terminology, which means "having no value.") +*`pv`*\ +Contains the address of a field data member in the recordset or `NULL`. If `NULL`, all field data members in the recordset are flagged. (C++ `NULL` isn't the same as Null in database terminology, which means "having no value.") -*`bDirty`*
+*`bDirty`*\ `TRUE` if the field data member is to be flagged as "dirty" (changed). Otherwise `FALSE` if the field data member is to be flagged as "clean" (unchanged). ### Remarks -Marking fields as unchanged ensures the field is not updated and results in less SQL traffic. +Marking fields as unchanged ensures the field isn't updated and results in less SQL traffic. > [!NOTE] -> This member function is not applicable on recordsets that are using bulk row fetching. If you have implemented bulk row fetching, then `SetFieldDirty` will result in a failed assertion. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> This member function isn't applicable on recordsets that are using bulk row fetching. If you've implemented bulk row fetching, then `SetFieldDirty` will result in a failed assertion. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -The framework marks changed field data members to ensure they will be written to the record on the data source by the record field exchange (RFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call `SetFieldDirty` yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. +The framework marks changed field data members to ensure they'll be written to the record on the data source by the record field exchange (RFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you'll seldom need to call `SetFieldDirty` yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. > [!CAUTION] -> Call this member function only after you have called [`Edit`](#edit) or [`AddNew`](#addnew). +> Call this member function only after you've called [`Edit`](#edit) or [`AddNew`](#addnew). Using `NULL` for the first argument of the function will apply the function only to `outputColumn` fields, not `param` fields. For instance, the call @@ -1642,7 +1651,7 @@ To work on `param` fields, you must supply the actual address of the individual [!code-cpp[NVC_MFCDatabase#27](../../mfc/codesnippet/cpp/crecordset-class_11.cpp)] -This means you cannot set all `param` fields to `NULL`, as you can with `outputColumn` fields. +This means you can't set all `param` fields to `NULL`, as you can with `outputColumn` fields. ## `CRecordset::SetFieldNull` @@ -1654,10 +1663,10 @@ void SetFieldNull(void* pv, BOOL bNull = TRUE); ### Parameters -*`pv`*
-Contains the address of a field data member in the recordset or `NULL`. If `NULL`, all field data members in the recordset are flagged. (C++ `NULL` is not the same as Null in database terminology, which means "having no value.") +*`pv`*\ +Contains the address of a field data member in the recordset or `NULL`. If `NULL`, all field data members in the recordset are flagged. (C++ `NULL` isn't the same as Null in database terminology, which means "having no value.") -*`bNull`*
+*`bNull`*\ Nonzero if the field data member is to be flagged as having no value (Null). Otherwise 0 if the field data member is to be flagged as non-Null. ### Remarks @@ -1665,12 +1674,12 @@ Nonzero if the field data member is to be flagged as having no value (Null). Oth When you add a new record to a recordset, all field data members are initially set to a Null value and flagged as "dirty" (changed). When you retrieve a record from a data source, its columns either already have values or are Null. > [!NOTE] -> Do not call this member function on recordsets that are using bulk row fetching. If you have implemented bulk row fetching, calling `SetFieldNull` results in a failed assertion. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> Don't call this member function on recordsets that are using bulk row fetching. If you've implemented bulk row fetching, calling `SetFieldNull` results in a failed assertion. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). -If you specifically wish to designate a field of the current record as not having a value, call `SetFieldNull` with *`bNull`* set to `TRUE` to flag it as Null. If a field was previously marked Null and you now want to give it a value, simply set its new value. You do not have to remove the Null flag with `SetFieldNull`. To determine whether the field is allowed to be Null, call `IsFieldNullable`. +If you specifically wish to designate a field of the current record as not having a value, call `SetFieldNull` with *`bNull`* set to `TRUE` to flag it as Null. If a field was previously marked Null and you now want to give it a value, set its new value. You don't have to remove the Null flag with `SetFieldNull`. To determine whether the field is allowed to be Null, call `IsFieldNullable`. > [!CAUTION] -> Call this member function only after you have called [`Edit`](#edit) or [`AddNew`](#addnew). +> Call this member function only after you've called [`Edit`](#edit) or [`AddNew`](#addnew). Using `NULL` for the first argument of the function will apply the function only to `outputColumn` fields, not `param` fields. For instance, the call @@ -1682,7 +1691,7 @@ To work on `param` fields, you must supply the actual address of the individual [!code-cpp[NVC_MFCDatabase#27](../../mfc/codesnippet/cpp/crecordset-class_11.cpp)] -This means you cannot set all `param` fields to `NULL`, as you can with `outputColumn` fields. +This means you can't set all `param` fields to `NULL`, as you can with `outputColumn` fields. > [!NOTE] > When setting parameters to Null, a call to `SetFieldNull` before the recordset is opened results in an assertion. In this case, call [`SetParamNull`](#setparamnull). @@ -1699,7 +1708,7 @@ void SetLockingMode(UINT nMode); ### Parameters -*`nMode`*
+*`nMode`*\ Contains one of the following values from the `enum LockMode`: - `optimistic` Optimistic locking locks the record being updated only during the call to `Update`. @@ -1722,15 +1731,15 @@ void SetParamNull( ### Parameters -*`nIndex`*
+*`nIndex`*\ The zero-based index of the parameter. -*`bNull`*
+*`bNull`*\ If `TRUE` (the default value), the parameter is flagged as Null. Otherwise, the parameter is flagged as non-Null. ### Remarks -Unlike [`SetFieldNull`](#setfieldnull), you can call `SetParamNull` before you have opened the recordset. +Unlike [`SetFieldNull`](#setfieldnull), you can call `SetParamNull` before you've opened the recordset. `SetParamNull` is typically used with predefined queries (stored procedures). @@ -1744,10 +1753,10 @@ void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE); ### Parameters -*`wRow`*
+*`wRow`*\ The one-based position of a row in the current rowset. This value can range from 1 to the size of the rowset. -*`wLockType`*
+*`wLockType`*\ Value indicating how to lock the row after it has been refreshed. For details, see Remarks. ### Remarks @@ -1764,19 +1773,19 @@ To use `SetRowsetCursorPosition`, you must have implemented bulk row fetching by |`SQL_LOCK_EXCLUSIVE`|The driver or data source locks the row exclusively. Not all data sources support this type of lock.| |`SQL_LOCK_UNLOCK`|The driver or data source unlocks the row. Not all data sources support this type of lock.| -For more information about `SQLSetPos`, see the Windows SDK. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about `SQLSetPos`, see the Windows SDK. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::SetRowsetSize` Specifies the number of records you wish to retrieve during a fetch. -``` +```cpp virtual void SetRowsetSize(DWORD dwNewRowsetSize); ``` ### Parameters -*`dwNewRowsetSize`*
+*`dwNewRowsetSize`*\ The number of rows to retrieve during a given fetch. ### Remarks @@ -1789,21 +1798,21 @@ This virtual member function specifies how many rows you wish to retrieve during Call `SetRowsetSize` before calling `Open` to initially set the rowset size for the recordset. The default rowset size when implementing bulk row fetching is 25. > [!NOTE] -> Use caution when calling `SetRowsetSize`. If you are manually allocating storage for the data (as specified by the `CRecordset::userAllocMultiRowBuffers` option of the dwOptions parameter in `Open`), you should check whether you need to reallocate these storage buffers after you call `SetRowsetSize`, but before you perform any cursor navigation operation. +> Use caution when calling `SetRowsetSize`. If you're manually allocating storage for the data (as specified by the `CRecordset::userAllocMultiRowBuffers` option of the dwOptions parameter in `Open`), you should check whether you need to reallocate these storage buffers after you call `SetRowsetSize`, but before you perform any cursor navigation operation. To obtain the current setting for the rowset size, call [`GetRowsetSize`](#getrowsetsize). -For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). ## `CRecordset::Update` Completes an `AddNew` or `Edit` operation by saving the new or edited data on the data source. -``` +```cpp virtual BOOL Update(); ``` -### Return Value +### Return value Nonzero if one record was successfully updated; otherwise 0 if no columns have changed. If no records were updated, or if more than one record was updated, an exception is thrown. An exception is also thrown for any other failure on the data source. @@ -1812,24 +1821,24 @@ Nonzero if one record was successfully updated; otherwise 0 if no columns have c Call this member function after a call to the [`AddNew`](#addnew) or [`Edit`](#edit) member function. This call is required to complete the `AddNew` or `Edit` operation. > [!NOTE] -> If you have implemented bulk row fetching, you cannot call `Update`. This will result in a failed assertion. Although class `CRecordset` does not provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see the article [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). +> If you've implemented bulk row fetching, you can't call `Update`. This will result in a failed assertion. Although class `CRecordset` doesn't provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function `SQLSetPos`. For more information about bulk row fetching, see [Recordset: Fetching Records in Bulk (ODBC)](../../data/odbc/recordset-fetching-records-in-bulk-odbc.md). Both `AddNew` and `Edit` prepare an edit buffer in which the added or edited data is placed for saving to the data source. `Update` saves the data. Only those fields marked or detected as changed are updated. -If the data source supports transactions, you can make the `Update` call (and its corresponding `AddNew` or `Edit` call) part of a transaction. For more information about transactions, see the article [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). +If the data source supports transactions, you can make the `Update` call (and its corresponding `AddNew` or `Edit` call) part of a transaction. For more information about transactions, see [Transaction (ODBC)](../../data/odbc/transaction-odbc.md). > [!CAUTION] > If you call `Update` without first calling either `AddNew` or `Edit`, `Update` throws a `CDBException`. If you call `AddNew` or `Edit`, you must call `Update` before you call a `Move` operation or before you close either the recordset or the data source connection. Otherwise, your changes are lost without notification. -For details on handling `Update` failures, see the article [Recordset: How Recordsets Update Records (ODBC)](../../data/odbc/recordset-how-recordsets-update-records-odbc.md). +For details on handling `Update` failures, see [Recordset: How Recordsets Update Records (ODBC)](../../data/odbc/recordset-how-recordsets-update-records-odbc.md). ### Example -See the article [Transaction: Performing a Transaction in a Recordset (ODBC)](../../data/odbc/transaction-performing-a-transaction-in-a-recordset-odbc.md). +see [Transaction: Performing a Transaction in a Recordset (ODBC)](../../data/odbc/transaction-performing-a-transaction-in-a-recordset-odbc.md). ## See also -[`CObject` Class](../../mfc/reference/cobject-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[`CDatabase` Class](../../mfc/reference/cdatabase-class.md)
-[`CRecordView` Class](../../mfc/reference/crecordview-class.md) +[`CObject` class](../../mfc/reference/cobject-class.md)\ +[Hierarchy chart](../../mfc/hierarchy-chart.md)\ +[`CDatabase` class](../../mfc/reference/cdatabase-class.md)\ +[`CRecordView` class](../../mfc/reference/crecordview-class.md) diff --git a/docs/mfc/reference/crgn-class.md b/docs/mfc/reference/crgn-class.md index 3e1cf67d0b..d0cadf2e71 100644 --- a/docs/mfc/reference/crgn-class.md +++ b/docs/mfc/reference/crgn-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CRgn Class" title: "CRgn Class" -ms.date: "11/04/2016" +description: "Learn more about: CRgn Class" +ms.date: 11/04/2016 f1_keywords: ["CRgn", "AFXWIN/CRgn", "AFXWIN/CRgn::CRgn", "AFXWIN/CRgn::CombineRgn", "AFXWIN/CRgn::CopyRgn", "AFXWIN/CRgn::CreateEllipticRgn", "AFXWIN/CRgn::CreateEllipticRgnIndirect", "AFXWIN/CRgn::CreateFromData", "AFXWIN/CRgn::CreateFromPath", "AFXWIN/CRgn::CreatePolygonRgn", "AFXWIN/CRgn::CreatePolyPolygonRgn", "AFXWIN/CRgn::CreateRectRgn", "AFXWIN/CRgn::CreateRectRgnIndirect", "AFXWIN/CRgn::CreateRoundRectRgn", "AFXWIN/CRgn::EqualRgn", "AFXWIN/CRgn::FromHandle", "AFXWIN/CRgn::GetRegionData", "AFXWIN/CRgn::GetRgnBox", "AFXWIN/CRgn::OffsetRgn", "AFXWIN/CRgn::PtInRegion", "AFXWIN/CRgn::RectInRegion", "AFXWIN/CRgn::SetRectRgn"] helpviewer_keywords: ["CRgn [MFC], CRgn", "CRgn [MFC], CombineRgn", "CRgn [MFC], CopyRgn", "CRgn [MFC], CreateEllipticRgn", "CRgn [MFC], CreateEllipticRgnIndirect", "CRgn [MFC], CreateFromData", "CRgn [MFC], CreateFromPath", "CRgn [MFC], CreatePolygonRgn", "CRgn [MFC], CreatePolyPolygonRgn", "CRgn [MFC], CreateRectRgn", "CRgn [MFC], CreateRectRgnIndirect", "CRgn [MFC], CreateRoundRectRgn", "CRgn [MFC], EqualRgn", "CRgn [MFC], FromHandle", "CRgn [MFC], GetRegionData", "CRgn [MFC], GetRgnBox", "CRgn [MFC], OffsetRgn", "CRgn [MFC], PtInRegion", "CRgn [MFC], RectInRegion", "CRgn [MFC], SetRectRgn"] -ms.assetid: d904da84-76aa-481e-8780-b09485f49e64 --- # CRgn Class @@ -37,7 +36,7 @@ class CRgn : public CGdiObject |[CRgn::CreatePolygonRgn](#createpolygonrgn)|Initializes a `CRgn` object with a polygonal region. The system closes the polygon automatically, if necessary, by drawing a line from the last vertex to the first.| |[CRgn::CreatePolyPolygonRgn](#createpolypolygonrgn)|Initializes a `CRgn` object with a region consisting of a series of closed polygons. The polygons may be disjoint, or they may overlap.| |[CRgn::CreateRectRgn](#createrectrgn)|Initializes a `CRgn` object with a rectangular region.| -|[CRgn::CreateRectRgnIndirect](#createrectrgnindirect)|Initializes a `CRgn` object with a rectangular region defined by a [RECT](/windows/win32/api/windef/ns-windef-rect)tructure.| +|[CRgn::CreateRectRgnIndirect](#createrectrgnindirect)|Initializes a `CRgn` object with a rectangular region defined by a [RECT](/windows/win32/api/windef/ns-windef-rect) structure.| |[CRgn::CreateRoundRectRgn](#createroundrectrgn)|Initializes a `CRgn` object with a rectangular region with rounded corners.| |[CRgn::EqualRgn](#equalrgn)|Checks two `CRgn` objects to determine whether they are equivalent.| |[CRgn::FromHandle](#fromhandle)|Returns a pointer to a `CRgn` object when given a handle to a Windows region.| @@ -250,7 +249,7 @@ BOOL CreateFromData( ### Parameters *lpXForm*
-Points to an [XFORM](/windows/win32/api/wingdi/ns-wingdi-xform)ata structure that defines the transformation to be performed on the region. If this pointer is NULL, the identity transformation is used. +Points to an [XFORM](/windows/win32/api/wingdi/ns-wingdi-xform) data structure that defines the transformation to be performed on the region. If this pointer is NULL, the identity transformation is used. *nCount*
Specifies the number of bytes pointed to by *pRgnData*. diff --git a/docs/mfc/reference/cricheditctrl-class.md b/docs/mfc/reference/cricheditctrl-class.md index 21cda42093..95466b4037 100644 --- a/docs/mfc/reference/cricheditctrl-class.md +++ b/docs/mfc/reference/cricheditctrl-class.md @@ -1195,7 +1195,7 @@ Contains the index value for the desired line in the text of the edit control, o ### Return Value -The character index of the line specified in *`nLine`* or -1 if the specified line number is greater then the number of lines in the edit control. +The character index of the line specified in *`nLine`* or -1 if the specified line number is greater than the number of lines in the edit control. ### Remarks @@ -1972,7 +1972,7 @@ For more information, see [`EM_STREAMIN`](/windows/win32/Controls/em-streamin) m ### Example [!code-cpp[NVC_MFC_CRichEditCtrl#34](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_34.cpp)] - +  [!code-cpp[NVC_MFC_CRichEditCtrl#35](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_35.cpp)] ## `CRichEditCtrl::StreamOut` @@ -2018,7 +2018,7 @@ For more information, see [`EM_STREAMOUT`](/windows/win32/Controls/em-streamout) ### Example [!code-cpp[NVC_MFC_CRichEditCtrl#36](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_36.cpp)] - +  [!code-cpp[NVC_MFC_CRichEditCtrl#37](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_37.cpp)] ## `CRichEditCtrl::Undo` diff --git a/docs/mfc/reference/cricheditdoc-class.md b/docs/mfc/reference/cricheditdoc-class.md index 700f069196..3897e50c9b 100644 --- a/docs/mfc/reference/cricheditdoc-class.md +++ b/docs/mfc/reference/cricheditdoc-class.md @@ -24,7 +24,7 @@ class CRichEditDoc : public COleServerDoc |----------|-----------------| |[CRichEditDoc::CreateClientItem](#createclientitem)|Called to perform cleanup of the document.| |[CRichEditDoc::GetStreamFormat](#getstreamformat)|Indicates whether stream input and output should include formatting information.| -|[CRichEditDoc::GetView](#getview)|Retrieves the asssociated [CRichEditView](../../mfc/reference/cricheditview-class.md) object.| +|[CRichEditDoc::GetView](#getview)|Retrieves the associated [CRichEditView](../../mfc/reference/cricheditview-class.md) object.| ### Public Data Members diff --git a/docs/mfc/reference/cscrollbar-class.md b/docs/mfc/reference/cscrollbar-class.md index 6218955b56..b5e379b529 100644 --- a/docs/mfc/reference/cscrollbar-class.md +++ b/docs/mfc/reference/cscrollbar-class.md @@ -4,9 +4,8 @@ title: "CScrollBar Class" ms.date: "11/04/2016" f1_keywords: ["CScrollBar", "AFXWIN/CScrollBar", "AFXWIN/CScrollBar::CScrollBar", "AFXWIN/CScrollBar::Create", "AFXWIN/CScrollBar::EnableScrollBar", "AFXWIN/CScrollBar::GetScrollBarInfo", "AFXWIN/CScrollBar::GetScrollInfo", "AFXWIN/CScrollBar::GetScrollLimit", "AFXWIN/CScrollBar::GetScrollPos", "AFXWIN/CScrollBar::GetScrollRange", "AFXWIN/CScrollBar::SetScrollInfo", "AFXWIN/CScrollBar::SetScrollPos", "AFXWIN/CScrollBar::SetScrollRange", "AFXWIN/CScrollBar::ShowScrollBar"] helpviewer_keywords: ["CScrollBar [MFC], CScrollBar", "CScrollBar [MFC], Create", "CScrollBar [MFC], EnableScrollBar", "CScrollBar [MFC], GetScrollBarInfo", "CScrollBar [MFC], GetScrollInfo", "CScrollBar [MFC], GetScrollLimit", "CScrollBar [MFC], GetScrollPos", "CScrollBar [MFC], GetScrollRange", "CScrollBar [MFC], SetScrollInfo", "CScrollBar [MFC], SetScrollPos", "CScrollBar [MFC], SetScrollRange", "CScrollBar [MFC], ShowScrollBar"] -ms.assetid: f3735ca5-73ea-46dc-918b-4d824c9fe47f --- -# CScrollBar Class +# `CScrollBar` Class Provides the functionality of a Windows scroll-bar control. @@ -22,33 +21,33 @@ class CScrollBar : public CWnd |Name|Description| |----------|-----------------| -|[CScrollBar::CScrollBar](#cscrollbar)|Constructs a `CScrollBar` object.| +|[`CScrollBar::CScrollBar`](#cscrollbar)|Constructs a `CScrollBar` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CScrollBar::Create](#create)|Creates the Windows scroll bar and attaches it to the `CScrollBar` object.| -|[CScrollBar::EnableScrollBar](#enablescrollbar)|Enables or disables one or both arrows of a scroll bar.| -|[CScrollBar::GetScrollBarInfo](#getscrollbarinfo)|Retrieves information about the scroll bar using a `SCROLLBARINFO` structure.| -|[CScrollBar::GetScrollInfo](#getscrollinfo)|Retrieves information about the scroll bar.| -|[CScrollBar::GetScrollLimit](#getscrolllimit)|Retrieves the limit of the scroll bar| -|[CScrollBar::GetScrollPos](#getscrollpos)|Retrieves the current position of a scroll box.| -|[CScrollBar::GetScrollRange](#getscrollrange)|Retrieves the current minimum and maximum scroll-bar positions for the given scroll bar.| -|[CScrollBar::SetScrollInfo](#setscrollinfo)|Sets information about the scroll bar.| -|[CScrollBar::SetScrollPos](#setscrollpos)|Sets the current position of a scroll box.| -|[CScrollBar::SetScrollRange](#setscrollrange)|Sets minimum and maximum position values for the given scroll bar.| -|[CScrollBar::ShowScrollBar](#showscrollbar)|Shows or hides a scroll bar.| +|[`CScrollBar::Create`](#create)|Creates the Windows scroll bar and attaches it to the `CScrollBar` object.| +|[`CScrollBar::EnableScrollBar`](#enablescrollbar)|Enables or disables one or both arrows of a scroll bar.| +|[`CScrollBar::GetScrollBarInfo`](#getscrollbarinfo)|Retrieves information about the scroll bar using a `SCROLLBARINFO` structure.| +|[`CScrollBar::GetScrollInfo`](#getscrollinfo)|Retrieves information about the scroll bar.| +|[`CScrollBar::GetScrollLimit`](#getscrolllimit)|Retrieves the limit of the scroll bar| +|[`CScrollBar::GetScrollPos`](#getscrollpos)|Retrieves the current position of a scroll box.| +|[`CScrollBar::GetScrollRange`](#getscrollrange)|Retrieves the current minimum and maximum scroll-bar positions for the given scroll bar.| +|[`CScrollBar::SetScrollInfo`](#setscrollinfo)|Sets information about the scroll bar.| +|[`CScrollBar::SetScrollPos`](#setscrollpos)|Sets the current position of a scroll box.| +|[`CScrollBar::SetScrollRange`](#setscrollrange)|Sets minimum and maximum position values for the given scroll bar.| +|[`CScrollBar::ShowScrollBar`](#showscrollbar)|Shows or hides a scroll bar.| ## Remarks -You create a scroll-bar control in two steps. First, call the constructor `CScrollBar` to construct the `CScrollBar` object, then call the [Create](#create) member function to create the Windows scroll-bar control and attach it to the `CScrollBar` object. +You create a scroll-bar control in two steps. First, call the constructor `CScrollBar` to construct the `CScrollBar` object, then call the [`Create`](#create) member function to create the Windows scroll-bar control and attach it to the `CScrollBar` object. If you create a `CScrollBar` object within a dialog box (through a dialog resource), the `CScrollBar` is automatically destroyed when the user closes the dialog box. If you create a `CScrollBar` object within a window, you may also need to destroy it. -If you create the `CScrollBar` object on the stack, it is destroyed automatically. If you create the `CScrollBar` object on the heap by using the **`new`** function, you must call **`delete`** on the object to destroy it when the user terminates the Windows scroll bar. +If you create the `CScrollBar` object on the stack, it's destroyed automatically. If you create the `CScrollBar` object on the heap by using the **`new`** function, you must call **`delete`** on the object to destroy it when the user terminates the Windows scroll bar. If you allocate any memory in the `CScrollBar` object, override the `CScrollBar` destructor to dispose of the allocations. @@ -56,19 +55,19 @@ For related information about using `CScrollBar`, see [Controls](../../mfc/contr ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CScrollBar` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CScrollBar::Create +## `CScrollBar::Create` Creates the Windows scroll bar and attaches it to the `CScrollBar` object. @@ -82,16 +81,16 @@ virtual BOOL Create( ### Parameters -*dwStyle*
+*`dwStyle`*\ Specifies the scroll bar's style. Apply any combination of [scroll-bar styles](../../mfc/reference/styles-used-by-mfc.md#scroll-bar-styles) to the scroll bar. -*rect*
+*`rect`*\ Specifies the scroll bar's size and position. Can be either a `RECT` structure or a `CRect` object. -*pParentWnd*
-Specifies the scroll bar's parent window, usually a `CDialog` object. It must not be NULL. +*`pParentWnd`*\ +Specifies the scroll bar's parent window, usually a `CDialog` object. It must not be `NULL`. -*nID*
+*`nID`*\ The scroll bar's control ID. ### Return Value @@ -104,19 +103,19 @@ You construct a `CScrollBar` object in two steps. First, call the constructor, w Apply the following [window styles](../../mfc/reference/styles-used-by-mfc.md#window-styles) to a scroll bar: -- WS_CHILD Always +- `WS_CHILD` Always -- WS_VISIBLE Usually +- `WS_VISIBLE` Usually -- WS_DISABLED Rarely +- `WS_DISABLED` Rarely -- WS_GROUP To group controls +- `WS_GROUP` To group controls ### Example [!code-cpp[NVC_MFC_CScrollBar#1](../../mfc/reference/codesnippet/cpp/cscrollbar-class_1.cpp)] -## CScrollBar::CScrollBar +## `CScrollBar::CScrollBar` Constructs a `CScrollBar` object. @@ -132,7 +131,7 @@ After constructing the object, call the `Create` member function to create and i [!code-cpp[NVC_MFC_CScrollBar#2](../../mfc/reference/codesnippet/cpp/cscrollbar-class_2.h)] -## CScrollBar::EnableScrollBar +## `CScrollBar::EnableScrollBar` Enables or disables one or both arrows of a scroll bar. @@ -142,16 +141,16 @@ BOOL EnableScrollBar(UINT nArrowFlags = ESB_ENABLE_BOTH); ### Parameters -*nArrowFlags*
+*`nArrowFlags`*\ Specifies whether the scroll arrows are enabled or disabled and which arrows are enabled or disabled. This parameter can be one of the following values: -- ESB_ENABLE_BOTH Enables both arrows of a scroll bar. +- `ESB_ENABLE_BOTH` Enables both arrows of a scroll bar. -- ESB_DISABLE_LTUP Disables the left arrow of a horizontal scroll bar or the up arrow of a vertical scroll bar. +- `ESB_DISABLE_LTUP` Disables the left arrow of a horizontal scroll bar or the up arrow of a vertical scroll bar. -- ESB_DISABLE_RTDN Disables the right arrow of a horizontal scroll bar or the down arrow of a vertical scroll bar. +- `ESB_DISABLE_RTDN` Disables the right arrow of a horizontal scroll bar or the down arrow of a vertical scroll bar. -- ESB_DISABLE_BOTH Disables both arrows of a scroll bar. +- `ESB_DISABLE_BOTH` Disables both arrows of a scroll bar. ### Return Value @@ -159,9 +158,9 @@ Nonzero if the arrows are enabled or disabled as specified; otherwise 0, which i ### Example - See the example for [CScrollBar::SetScrollRange](#setscrollrange). + See the example for [`CScrollBar::SetScrollRange`](#setscrollrange). -## CScrollBar::GetScrollBarInfo +## `CScrollBar::GetScrollBarInfo` Retrieves the information that the `SCROLLBARINFO` structure maintains about a scroll bar. @@ -171,18 +170,18 @@ BOOL GetScrollBarInfo(PSCROLLBARINFO pScrollInfo) const; ### Parameters -*pScrollInfo*
-A pointer to the [SCROLLBARINFO](/windows/win32/api/winuser/ns-winuser-scrollbarinfo) structure. +*`pScrollInfo`*\ +A pointer to the [`SCROLLBARINFO`](/windows/win32/api/winuser/ns-winuser-scrollbarinfo) structure. ### Return Value -Returns TRUE on success, FALSE on failure. +Returns `TRUE` on success, `FALSE` on failure. ### Remarks -This member function emulates the functionality of the [SBM_SCROLLBARINFO](/windows/win32/Controls/sbm-getscrollbarinfo) message, as described in the Windows SDK. +This member function emulates the functionality of the [`SBM_SCROLLBARINFO`](/windows/win32/Controls/sbm-getscrollbarinfo) message, as described in the Windows SDK. -## CScrollBar::GetScrollInfo +## `CScrollBar::GetScrollInfo` Retrieves the information that the `SCROLLINFO` structure maintains about a scroll bar. @@ -194,29 +193,29 @@ BOOL GetScrollInfo( ### Parameters -*lpScrollInfo*
-A pointer to a [SCROLLINFO](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure. See the Windows SDK for more information about this structure. +*`lpScrollInfo`*\ +A pointer to a [`SCROLLINFO`](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure. See the Windows SDK for more information about this structure. -*nMask*
-Specifies the scroll bar parameters to retrieve. Typical usage, SIF_ALL, specifies a combination of SIF_PAGE, SIF_POS, SIF_TRACKPOS, and SIF_RANGE. See `SCROLLINFO` for more information on the nMask values. +*`nMask`*\ +Specifies the scroll bar parameters to retrieve. Typical usage, `SIF_ALL`, specifies a combination of `SIF_PAGE`, `SIF_POS`, `SIF_TRACKPOS`, and `SIF_RANGE`. See `SCROLLINFO` for more information on the `nMask` values. ### Return Value -If the message retrieved any values, the return is TRUE. Otherwise, it is FALSE. +If the message retrieved any values, the return is `TRUE`. Otherwise, it's `FALSE`. ### Remarks `GetScrollInfo` enables applications to use 32-bit scroll positions. -The [SCROLLINFO](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure contains information about a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (the thumb). See the `SCROLLINFO` structure topic in the Windows SDK for more information about changing the structure defaults. +The [`SCROLLINFO`](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure contains information about a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (the thumb). See the `SCROLLINFO` structure topic in the Windows SDK for more information about changing the structure defaults. -The MFC Windows message handlers that indicate scroll bar position, [CWnd::OnHScroll, and [CWnd::OnVScroll](../../mfc/reference/cwnd-class.md#onvscroll), provide only 16 bits of position data. `GetScrollInfo` and `SetScrollInfo` provide 32 bits of scroll bar position data. Thus, an application can call `GetScrollInfo` while processing either `CWnd::OnHScroll` or `CWnd::OnVScroll` to obtain 32-bit scroll bar position data. +The MFC Windows message handlers that indicate scroll bar position, [`CWnd::OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll), and [`CWnd::OnVScroll`](../../mfc/reference/cwnd-class.md#onvscroll), provide only 16 bits of position data. `GetScrollInfo` and `SetScrollInfo` provide 32 bits of scroll bar position data. Thus, an application can call `GetScrollInfo` while processing either `CWnd::OnHScroll` or `CWnd::OnVScroll` to obtain 32-bit scroll bar position data. ### Example - See the example for [CWnd::OnHScroll](../../mfc/reference/cwnd-class.md#onhscroll). + See the example for [`CWnd::OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll). -## CScrollBar::GetScrollLimit +## `CScrollBar::GetScrollLimit` Retrieves the maximum scrolling position of the scroll bar. @@ -230,9 +229,9 @@ Specifies the maximum position of a scroll bar if successful; otherwise 0. ### Example - See the example for [CWnd::OnHScroll](../../mfc/reference/cwnd-class.md#onhscroll). + See the example for [`CWnd::OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll). -## CScrollBar::GetScrollPos +## `CScrollBar::GetScrollPos` Retrieves the current position of a scroll box. @@ -250,11 +249,11 @@ The current position is a relative value that depends on the current scrolling r ### Example - See the example for [CWnd::OnHScroll](../../mfc/reference/cwnd-class.md#onhscroll). + See the example for [`CWnd::OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll). -## CScrollBar::GetScrollRange +## `CScrollBar::GetScrollRange` -Copies the current minimum and maximum scroll-bar positions for the given scroll bar to the locations specified by *lpMinPos* and *lpMaxPos*. +Copies the current minimum and maximum scroll-bar positions for the given scroll bar to the locations specified by *`lpMinPos`* and *`lpMaxPos`*. ```cpp void GetScrollRange( @@ -264,10 +263,10 @@ void GetScrollRange( ### Parameters -*lpMinPos*
+*`lpMinPos`*\ Points to the integer variable that is to receive the minimum position. -*lpMaxPos*
+*`lpMaxPos`*\ Points to the integer variable that is to receive the maximum position. ### Remarks @@ -276,9 +275,9 @@ The default range for a scroll-bar control is empty (both values are 0). ### Example - See the example for [CWnd::OnHScroll](../../mfc/reference/cwnd-class.md#onhscroll). + See the example for [`CWnd::OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll). -## CScrollBar::SetScrollInfo +## `CScrollBar::SetScrollInfo` Sets the information that the `SCROLLINFO` structure maintains about a scroll bar. @@ -290,29 +289,29 @@ BOOL SetScrollInfo( ### Parameters -*lpScrollInfo*
-A pointer to a [SCROLLINFO](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure. +*`lpScrollInfo`*\ +A pointer to a [`SCROLLINFO`](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure. -*bRedraw*
-Specifies whether the scroll bar should be redrawn to reflect the new information. If *bRedraw* is TRUE, the scroll bar is redrawn. If it is FALSE, it is not redrawn. The scroll bar is redrawn by default. +*`bRedraw`*\ +Specifies whether the scroll bar should be redrawn to reflect the new information. If *`bRedraw`* is `TRUE`, the scroll bar is redrawn. If it's `FALSE`, it isn't redrawn. The scroll bar is redrawn by default. ### Return Value -If successful, the return is TRUE. Otherwise, it is FALSE. +If successful, the return is `TRUE`. Otherwise, it's `FALSE`. ### Remarks You must provide the values required by the `SCROLLINFO` structure parameters, including the flag values. -The `SCROLLINFO` structure contains information about a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (the thumb). See the [SCROLLINFO](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure topic in the Windows SDK for more information about changing the structure defaults. +The `SCROLLINFO` structure contains information about a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (the thumb). See the [`SCROLLINFO`](/windows/win32/api/winuser/ns-winuser-scrollinfo) structure topic in the Windows SDK for more information about changing the structure defaults. ### Example [!code-cpp[NVC_MFC_CScrollBar#3](../../mfc/reference/codesnippet/cpp/cscrollbar-class_3.cpp)] -## CScrollBar::SetScrollPos +## `CScrollBar::SetScrollPos` -Sets the current position of a scroll box to that specified by *nPos* and, if specified, redraws the scroll bar to reflect the new position. +Sets the current position of a scroll box to that specified by *`nPos`* and, if specified, redraws the scroll bar to reflect the new position. ``` int SetScrollPos( @@ -322,11 +321,11 @@ int SetScrollPos( ### Parameters -*nPos*
+*`nPos`*\ Specifies the new position for the scroll box. It must be within the scrolling range. -*bRedraw*
-Specifies whether the scroll bar should be redrawn to reflect the new position. If *bRedraw* is TRUE, the scroll bar is redrawn. If it is FALSE, it is not redrawn. The scroll bar is redrawn by default. +*`bRedraw`*\ +Specifies whether the scroll bar should be redrawn to reflect the new position. If *`bRedraw`* is `TRUE`, the scroll bar is redrawn. If it's `FALSE`, it isn't redrawn. The scroll bar is redrawn by default. ### Return Value @@ -334,13 +333,13 @@ Specifies the previous position of the scroll box if successful; otherwise 0. ### Remarks -Set *bRedraw* to FALSE whenever the scroll bar will be redrawn by a subsequent call to another function to avoid having the scroll bar redrawn twice within a short interval. +Set *`bRedraw`* to `FALSE` whenever the scroll bar will be redrawn by a subsequent call to another function to avoid having the scroll bar redrawn twice within a short interval. ### Example See the example for [CScrollBar::SetScrollRange](#setscrollrange). -## CScrollBar::SetScrollRange +## `CScrollBar::SetScrollRange` Sets minimum and maximum position values for the given scroll bar. @@ -353,30 +352,30 @@ void SetScrollRange( ### Parameters -*nMinPos*
+*`nMinPos`*\ Specifies the minimum scrolling position. -*nMaxPos*
+*`nMaxPos`*\ Specifies the maximum scrolling position. -*bRedraw*
-Specifies whether the scroll bar should be redrawn to reflect the change. If *bRedraw* is TRUE, the scroll bar is redrawn; if FALSE, it is not redrawn. It is redrawn by default. +*`bRedraw`*\ +Specifies whether the scroll bar should be redrawn to reflect the change. If *`bRedraw`* is `TRUE`, the scroll bar is redrawn; if `FALSE`, it isn't redrawn. It's redrawn by default. ### Remarks -Set *nMinPos* and *nMaxPos* to 0 to hide standard scroll bars. +Set *`nMinPos`* and *`nMaxPos`* to 0 to hide standard scroll bars. -Do not call this function to hide a scroll bar while processing a scroll-bar notification message. +Don't call this function to hide a scroll bar while processing a scroll-bar notification message. -If a call to `SetScrollRange` immediately follows a call to the `SetScrollPos` member function, set *bRedraw* in `SetScrollPos` to 0 to prevent the scroll bar from being redrawn twice. +If a call to `SetScrollRange` immediately follows a call to the `SetScrollPos` member function, set *`bRedraw`* in `SetScrollPos` to 0 to prevent the scroll bar from being redrawn twice. -The difference between the values specified by *nMinPos* and *nMaxPos* must not be greater than 32,767. The default range for a scroll-bar control is empty (both *nMinPos* and *nMaxPos* are 0). +The difference between the values specified by *`nMinPos`* and *`nMaxPos`* must not be greater than 32,767. The default range for a scroll-bar control is empty (both *`nMinPos`* and *`nMaxPos`* are 0). ### Example [!code-cpp[NVC_MFC_CScrollBar#4](../../mfc/reference/codesnippet/cpp/cscrollbar-class_4.cpp)] -## CScrollBar::ShowScrollBar +## `CScrollBar::ShowScrollBar` Shows or hides a scroll bar. @@ -386,25 +385,24 @@ void ShowScrollBar(BOOL bShow = TRUE); ### Parameters -*bShow*
-Specifies whether the scroll bar is shown or hidden. If this parameter is TRUE, the scroll bar is shown; otherwise it is hidden. +*`bShow`*\ +Specifies whether the scroll bar is shown or hidden. If this parameter is `TRUE`, the scroll bar is shown; otherwise it's hidden. ### Remarks -An application should not call this function to hide a scroll bar while processing a scroll-bar notification message. +An application shouldn't call this function to hide a scroll bar while processing a scroll-bar notification message. ### Example - See the example for [CScrollBar::Create](#create). + See the example for [`CScrollBar::Create`](#create). ## See also -[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[CButton Class](../../mfc/reference/cbutton-class.md)
-[CComboBox Class](../../mfc/reference/ccombobox-class.md)
-[CEdit Class](../../mfc/reference/cedit-class.md)
-[CListBox Class](../../mfc/reference/clistbox-class.md)
-[CStatic Class](../../mfc/reference/cstatic-class.md)
-[CDialog Class](../../mfc/reference/cdialog-class.md) +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CButton` Class](../../mfc/reference/cbutton-class.md)\ +[`CComboBox` Class](../../mfc/reference/ccombobox-class.md)\ +[`CEdit` Class](../../mfc/reference/cedit-class.md)\ +[`CListBox` Class](../../mfc/reference/clistbox-class.md)\ +[`CStatic` Class](../../mfc/reference/cstatic-class.md)\ +[`CDialog` Class](../../mfc/reference/cdialog-class.md) diff --git a/docs/mfc/reference/cscrollview-class.md b/docs/mfc/reference/cscrollview-class.md index 8a147cf0a8..17e1c7e1bd 100644 --- a/docs/mfc/reference/cscrollview-class.md +++ b/docs/mfc/reference/cscrollview-class.md @@ -4,11 +4,10 @@ title: "CScrollView Class" ms.date: "11/04/2016" f1_keywords: ["CScrollView", "AFXWIN/CScrollView", "AFXWIN/CScrollView::CScrollView", "AFXWIN/CScrollView::CheckScrollBars", "AFXWIN/CScrollView::FillOutsideRect", "AFXWIN/CScrollView::GetDeviceScrollPosition", "AFXWIN/CScrollView::GetDeviceScrollSizes", "AFXWIN/CScrollView::GetScrollPosition", "AFXWIN/CScrollView::GetTotalSize", "AFXWIN/CScrollView::ResizeParentToFit", "AFXWIN/CScrollView::ScrollToPosition", "AFXWIN/CScrollView::SetScaleToFitSize", "AFXWIN/CScrollView::SetScrollSizes"] helpviewer_keywords: ["CScrollView [MFC], CScrollView", "CScrollView [MFC], CheckScrollBars", "CScrollView [MFC], FillOutsideRect", "CScrollView [MFC], GetDeviceScrollPosition", "CScrollView [MFC], GetDeviceScrollSizes", "CScrollView [MFC], GetScrollPosition", "CScrollView [MFC], GetTotalSize", "CScrollView [MFC], ResizeParentToFit", "CScrollView [MFC], ScrollToPosition", "CScrollView [MFC], SetScaleToFitSize", "CScrollView [MFC], SetScrollSizes"] -ms.assetid: 4ba16dac-1acb-4be0-bb55-5fb695b6948d --- -# CScrollView Class +# `CScrollView` Class -A [CView](../../mfc/reference/cview-class.md) with scrolling capabilities. +A [`CView`](../../mfc/reference/cview-class.md) with scrolling capabilities. ## Syntax @@ -22,26 +21,26 @@ class CScrollView : public CView |Name|Description| |----------|-----------------| -|[CScrollView::CScrollView](#cscrollview)|Constructs a `CScrollView` object.| +|[`CScrollView::CScrollView`](#cscrollview)|Constructs a `CScrollView` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CScrollView::CheckScrollBars](#checkscrollbars)|Indicates whether the scroll view has horizontal and vertical scroll bars.| -|[CScrollView::FillOutsideRect](#filloutsiderect)|Fills the area of a view outside the scrolling area.| -|[CScrollView::GetDeviceScrollPosition](#getdevicescrollposition)|Gets the current scroll position in device units.| -|[CScrollView::GetDeviceScrollSizes](#getdevicescrollsizes)|Gets the current mapping mode, the total size, and the line and page sizes of the scrollable view. Sizes are in device units.| -|[CScrollView::GetScrollPosition](#getscrollposition)|Gets the current scroll position in logical units.| -|[CScrollView::GetTotalSize](#gettotalsize)|Gets the total size of the scroll view in logical units.| -|[CScrollView::ResizeParentToFit](#resizeparenttofit)|Causes the size of the view to dictate the size of its frame.| -|[CScrollView::ScrollToPosition](#scrolltoposition)|Scrolls the view to a given point, specified in logical units.| -|[CScrollView::SetScaleToFitSize](#setscaletofitsize)|Puts the scroll view into scale-to-fit mode.| -|[CScrollView::SetScrollSizes](#setscrollsizes)|Sets the scroll view's mapping mode, total size, and horizontal and vertical scroll amounts.| +|[`CScrollView::CheckScrollBars`](#checkscrollbars)|Indicates whether the scroll view has horizontal and vertical scroll bars.| +|[`CScrollView::FillOutsideRect`](#filloutsiderect)|Fills the area of a view outside the scrolling area.| +|[`CScrollView::GetDeviceScrollPosition`](#getdevicescrollposition)|Gets the current scroll position in device units.| +|[`CScrollView::GetDeviceScrollSizes`](#getdevicescrollsizes)|Gets the current mapping mode, the total size, and the line and page sizes of the scrollable view. Sizes are in device units.| +|[`CScrollView::GetScrollPosition`](#getscrollposition)|Gets the current scroll position in logical units.| +|[`CScrollView::GetTotalSize`](#gettotalsize)|Gets the total size of the scroll view in logical units.| +|[`CScrollView::ResizeParentToFit`](#resizeparenttofit)|Causes the size of the view to dictate the size of its frame.| +|[`CScrollView::ScrollToPosition`](#scrolltoposition)|Scrolls the view to a given point, specified in logical units.| +|[`CScrollView::SetScaleToFitSize`](#setscaletofitsize)|Puts the scroll view into scale-to-fit mode.| +|[`CScrollView::SetScrollSizes`](#setscrollsizes)|Sets the scroll view's mapping mode, total size, and horizontal and vertical scroll amounts.| ## Remarks -You can handle standard scrolling yourself in any class derived from `CView` by overriding the message-mapped [OnHScroll](../../mfc/reference/cwnd-class.md#onhscroll) and [OnVScroll](../../mfc/reference/cwnd-class.md#onvscroll) member functions. But `CScrollView` adds the following features to its `CView` capabilities: +You can handle standard scrolling yourself in any class derived from `CView` by overriding the message-mapped [`OnHScroll`](../../mfc/reference/cwnd-class.md#onhscroll) and [`OnVScroll`](../../mfc/reference/cwnd-class.md#onvscroll) member functions. But `CScrollView` adds the following features to its `CView` capabilities: - It manages window and viewport sizes and mapping modes. @@ -49,49 +48,49 @@ You can handle standard scrolling yourself in any class derived from `CView` by - It scrolls automatically in response to messages from the keyboard, a non-scrolling mouse, or the IntelliMouse wheel. -To scroll automatically in response to messages from the keyboard, add a WM_KEYDOWN message, and test for VK_DOWN, VK_PREV and call [SetScrollPos](/windows/win32/api/winuser/nf-winuser-setscrollpos). +To scroll automatically in response to messages from the keyboard, add a `WM_KEYDOWN` message, and test for `VK_DOWN`, `VK_PREV` and call [`SetScrollPos`](/windows/win32/api/winuser/nf-winuser-setscrollpos). -You can handle mouse wheel scrolling yourself by overriding the message-mapped [OnMouseWheel](../../mfc/reference/cwnd-class.md#onmousewheel) and [OnRegisteredMouseWheel](../../mfc/reference/cwnd-class.md#onregisteredmousewheel) member functions. As they are for `CScrollView`, these member functions support the recommended behaviour for [WM_MOUSEWHEEL](/windows/win32/inputdev/wm-mousewheel), the wheel rotation message. +You can handle mouse wheel scrolling yourself by overriding the message-mapped [`OnMouseWheel`](../../mfc/reference/cwnd-class.md#onmousewheel) and [`OnRegisteredMouseWheel`](../../mfc/reference/cwnd-class.md#onregisteredmousewheel) member functions. As they are for `CScrollView`, these member functions support the recommended behavior for [`WM_MOUSEWHEEL`](/windows/win32/inputdev/wm-mousewheel), the wheel rotation message. -To take advantage of automatic scrolling, derive your view class from `CScrollView` instead of from `CView`. When the view is first created, if you want to calculate the size of the scrollable view based on the size of the document, call the `SetScrollSizes` member function from your override of either [CView::OnInitialUpdate](../../mfc/reference/cview-class.md#oninitialupdate) or [CView::OnUpdate](../../mfc/reference/cview-class.md#onupdate). (You must write your own code to query the size of the document. For an example, see the [Scribble sample](../../overview/visual-cpp-samples.md).) +To take advantage of automatic scrolling, derive your view class from `CScrollView` instead of from `CView`. When the view is first created, if you want to calculate the size of the scrollable view based on the size of the document, call the `SetScrollSizes` member function from your override of either [`CView::OnInitialUpdate`](../../mfc/reference/cview-class.md#oninitialupdate) or [`CView::OnUpdate`](../../mfc/reference/cview-class.md#onupdate). (You must write your own code to query the size of the document. For an example, see the [Scribble sample](../../overview/visual-cpp-samples.md).) -The call to the `SetScrollSizes` member function sets the view's mapping mode, the total dimensions of the scroll view, and the amounts to scroll horizontally and vertically. All sizes are in logical units. The logical size of the view is usually calculated from data stored in the document, but in some cases you may want to specify a fixed size. For examples of both approaches, see [CScrollView::SetScrollSizes](#setscrollsizes). +The call to the `SetScrollSizes` member function sets the view's mapping mode, the total dimensions of the scroll view, and the amounts to scroll horizontally and vertically. All sizes are in logical units. The logical size of the view is usually calculated from data stored in the document, but in some cases you may want to specify a fixed size. For examples of both approaches, see [`CScrollView::SetScrollSizes`](#setscrollsizes). You specify the amounts to scroll horizontally and vertically in logical units. By default, if the user clicks a scroll bar shaft outside of the scroll box, `CScrollView` scrolls a "page." If the user clicks a scroll arrow at either end of a scroll bar, `CScrollView` scrolls a "line." By default, a page is 1/10 of the total size of the view; a line is 1/10 of the page size. Override these default values by passing custom sizes in the `SetScrollSizes` member function. For example, you might set the horizontal size to some fraction of the width of the total size and the vertical size to the height of a line in the current font. -Instead of scrolling, `CScrollView` can automatically scale the view to the current window size. In this mode, the view has no scroll bars and the logical view is stretched or shrunk to exactly fit the window's client area. To use this scale-to-fit capability, call [CScrollView::SetScaleToFitSize](#setscaletofitsize). (Call either `SetScaleToFitSize` or `SetScrollSizes`, but not both.) +Instead of scrolling, `CScrollView` can automatically scale the view to the current window size. In this mode, the view has no scroll bars and the logical view is stretched or shrunk to exactly fit the window's client area. To use this scale-to-fit capability, call [`CScrollView::SetScaleToFitSize`](#setscaletofitsize). (Call either `SetScaleToFitSize` or `SetScrollSizes`, but not both.) Before the `OnDraw` member function of your derived view class is called, `CScrollView` automatically adjusts the viewport origin for the `CPaintDC` device-context object that it passes to `OnDraw`. -To adjust the viewport origin for the scrolling window, `CScrollView` overrides [CView::OnPrepareDC](../../mfc/reference/cview-class.md#onpreparedc). This adjustment is automatic for the `CPaintDC` device context that `CScrollView` passes to `OnDraw`, but you must call `CScrollView::OnPrepareDC` yourself for any other device contexts you use, such as a `CClientDC`. You can override `CScrollView::OnPrepareDC` to set the pen, background color, and other drawing attributes, but call the base class to do scaling. +To adjust the viewport origin for the scrolling window, `CScrollView` overrides [`CView::OnPrepareDC`](../../mfc/reference/cview-class.md#onpreparedc). This adjustment is automatic for the `CPaintDC` device context that `CScrollView` passes to `OnDraw`, but you must call `CScrollView::OnPrepareDC` yourself for any other device contexts you use, such as a `CClientDC`. You can override `CScrollView::OnPrepareDC` to set the pen, background color, and other drawing attributes, but call the base class to do scaling. Scroll bars can appear in three places relative to a view, as shown in the following cases: -- Standard window-style scroll bars can be set for the view using the WS_HSCROLL and WS_VSCROLL[Windows Styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). +- Standard window-style scroll bars can be set for the view using the `WS_HSCROLL` and `WS_VSCROLL` [Windows Styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). -- Scroll-bar controls can also be added to the frame containing the view, in which case the framework forwards WM_HSCROLL and WM_VSCROLL messages from the frame window to the currently active view. +- Scroll-bar controls can also be added to the frame containing the view, in which case the framework forwards `WM_HSCROLL` and `WM_VSCROLL` messages from the frame window to the currently active view. -- The framework also forwards scroll messages from a `CSplitterWnd` splitter control to the currently active splitter pane (a view). When placed in a [CSplitterWnd](../../mfc/reference/csplitterwnd-class.md) with shared scroll bars, a `CScrollView` object will use the shared ones rather than creating its own. +- The framework also forwards scroll messages from a `CSplitterWnd` splitter control to the currently active splitter pane (a view). When placed in a [`CSplitterWnd`](../../mfc/reference/csplitterwnd-class.md) with shared scroll bars, a `CScrollView` object will use the shared ones rather than creating its own. For more information on using `CScrollView`, see [Document/View Architecture](../../mfc/document-view-architecture.md) and [Derived View Classes Available in MFC](../../mfc/derived-view-classes-available-in-mfc.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CView](../../mfc/reference/cview-class.md) +[`CView`](../../mfc/reference/cview-class.md) `CScrollView` ## Requirements -**Header:** afxwin.h +**Header:** `afxwin.h` -## CScrollView::CheckScrollBars +## `CScrollView::CheckScrollBars` Call this member function to determine if the scroll view has horizontal and vertical bars. @@ -103,13 +102,13 @@ void CheckScrollBars( ### Parameters -*bHasHorzBar*
+*`bHasHorzBar`*\ Indicates the application has a horizontal scroll bar. -*bHasVertBar*
+*`bHasVertBar`*\ Indicates the application has a vertical scroll bar. -## CScrollView::CScrollView +## `CScrollView::CScrollView` Constructs a `CScrollView` object. @@ -121,7 +120,7 @@ CScrollView(); You must call either `SetScrollSizes` or `SetScaleToFitSize` before the scroll view is usable. -## CScrollView::FillOutsideRect +## `CScrollView::FillOutsideRect` Call `FillOutsideRect` to fill the area of the view that appears outside of the scrolling area. @@ -133,10 +132,10 @@ void FillOutsideRect( ### Parameters -*pDC*
+*`pDC`*\ Device context in which the filling is to be done. -*pBrush*
+*`pBrush`*\ Brush with which the area is to be filled. ### Remarks @@ -147,7 +146,7 @@ Use `FillOutsideRect` in your scroll view's `OnEraseBkgnd` handler function to p [!code-cpp[NVC_MFCDocView#164](../../mfc/codesnippet/cpp/cscrollview-class_1.cpp)] -## CScrollView::GetDeviceScrollPosition +## `CScrollView::GetDeviceScrollPosition` Call `GetDeviceScrollPosition` when you need the current horizontal and vertical positions of the scroll boxes in the scroll bars. @@ -165,7 +164,7 @@ This coordinate pair corresponds to the location in the document to which the up `GetDeviceScrollPosition` returns values in device units. If you want logical units, use `GetScrollPosition` instead. -## CScrollView::GetDeviceScrollSizes +## `CScrollView::GetDeviceScrollSizes` `GetDeviceScrollSizes` gets the current mapping mode, the total size, and the line and page sizes of the scrollable view. @@ -179,23 +178,23 @@ void GetDeviceScrollSizes( ### Parameters -*nMapMode*
+*`nMapMode`*\ Returns the current mapping mode for this view. For a list of possible values, see `SetScrollSizes`. -*sizeTotal*
+*`sizeTotal`*\ Returns the current total size of the scroll view in device units. -*sizePage*
+*`sizePage`*\ Returns the current horizontal and vertical amounts to scroll in each direction in response to a mouse click in a scroll-bar shaft. The `cx` member contains the horizontal amount. The `cy` member contains the vertical amount. -*sizeLine*
+*`sizeLine`*\ Returns the current horizontal and vertical amounts to scroll in each direction in response to a mouse click in a scroll arrow. The `cx` member contains the horizontal amount. The `cy` member contains the vertical amount. ### Remarks Sizes are in device units. This member function is rarely called. -## CScrollView::GetScrollPosition +## `CScrollView::GetScrollPosition` Call `GetScrollPosition` when you need the current horizontal and vertical positions of the scroll boxes in the scroll bars. @@ -213,7 +212,7 @@ This coordinate pair corresponds to the location in the document to which the up `GetScrollPosition` returns values in logical units. If you want device units, use `GetDeviceScrollPosition` instead. -## CScrollView::GetTotalSize +## `CScrollView::GetTotalSize` Call `GetTotalSize` to retrieve the current horizontal and vertical sizes of the scroll view. @@ -225,7 +224,7 @@ CSize GetTotalSize() const; The total size of the scroll view in logical units. The horizontal size is in the `cx` member of the `CSize` return value. The vertical size is in the `cy` member. -## CScrollView::ResizeParentToFit +## `CScrollView::ResizeParentToFit` Call `ResizeParentToFit` to let the size of your view dictate the size of its frame window. @@ -235,18 +234,18 @@ void ResizeParentToFit(BOOL bShrinkOnly = TRUE); ### Parameters -*bShrinkOnly*
-The kind of resizing to perform. The default value, TRUE, shrinks the frame window if appropriate. Scroll bars will still appear for large views or small frame windows. A value of FALSE causes the view always to resize the frame window exactly. This can be somewhat dangerous since the frame window could get too big to fit inside the multiple document interface (MDI) frame window or the screen. +*`bShrinkOnly`*\ +The kind of resizing to perform. The default value, `TRUE`, shrinks the frame window if appropriate. Scroll bars will still appear for large views or small frame windows. A value of `FALSE` causes the view always to resize the frame window exactly. This can be somewhat dangerous since the frame window could get too big to fit inside the multiple document interface (MDI) frame window or the screen. ### Remarks -This is recommended only for views in MDI child frame windows. Use `ResizeParentToFit` in the `OnInitialUpdate` handler function of your derived `CScrollView` class. For an example of this member function, see [CScrollView::SetScrollSizes](#setscrollsizes). +This is recommended only for views in MDI child frame windows. Use `ResizeParentToFit` in the `OnInitialUpdate` handler function of your derived `CScrollView` class. For an example of this member function, see [`CScrollView::SetScrollSizes`](#setscrollsizes). -`ResizeParentToFit` assumes that the size of the view window has been set. If the view window size has not been set when `ResizeParentToFit` is called, you will get an assertion. To ensure that this does not happen, make the following call before calling `ResizeParentToFit`: +`ResizeParentToFit` assumes that the size of the view window has been set. If the view window size hasn't been set when `ResizeParentToFit` is called, you'll get an assertion. To ensure that this doesn't happen, make the following call before calling `ResizeParentToFit`: [!code-cpp[NVC_MFCDocView#165](../../mfc/codesnippet/cpp/cscrollview-class_2.cpp)] -## CScrollView::ScrollToPosition +## `CScrollView::ScrollToPosition` Call `ScrollToPosition` to scroll to a given point in the view. @@ -256,14 +255,14 @@ void ScrollToPosition(POINT pt); ### Parameters -*pt*
-The point to scroll to, in logical units. The `x` member must be a positive value (greater than or equal to 0, up to the total size of the view). The same is true for the `y` member when the mapping mode is MM_TEXT. The `y` member is negative in mapping modes other than MM_TEXT. +*`pt`*\ +The point to scroll to, in logical units. The `x` member must be a positive value (greater than or equal to 0, up to the total size of the view). The same is true for the `y` member when the mapping mode is `MM_TEXT`. The `y` member is negative in mapping modes other than `MM_TEXT`. ### Remarks The view will be scrolled so that this point is at the upper-left corner of the window. This member function must not be called if the view is scaled to fit. -## CScrollView::SetScaleToFitSize +## `CScrollView::SetScaleToFitSize` Call `SetScaleToFitSize` when you want to scale the viewport size to the current window size automatically. @@ -273,22 +272,22 @@ void SetScaleToFitSize(SIZE sizeTotal); ### Parameters -*sizeTotal*
+*`sizeTotal`*\ The horizontal and vertical sizes to which the view is to be scaled. The scroll view's size is measured in logical units. The horizontal size is contained in the `cx` member. The vertical size is contained in the `cy` member. Both `cx` and `cy` must be greater than or equal to 0. ### Remarks With scroll bars, only a portion of the logical view may be visible at any time. But with the scale-to-fit capability, the view has no scroll bars and the logical view is stretched or shrunk to exactly fit the window's client area. When the window is resized, the view draws its data at a new scale based on the size of the window. -You'll typically place the call to `SetScaleToFitSize` in your override of the view's `OnInitialUpdate` member function. If you do not want automatic scaling, call the `SetScrollSizes` member function instead. +You'll typically place the call to `SetScaleToFitSize` in your override of the view's `OnInitialUpdate` member function. If you don't want automatic scaling, call the `SetScrollSizes` member function instead. `SetScaleToFitSize` can be used to implement a "Zoom to Fit" operation. Use `SetScrollSizes` to reinitialize scrolling. -`SetScaleToFitSize` assumes that the size of the view window has been set. If the view window size has not been set when `SetScaleToFitSize` is called, you will get an assertion. To ensure that this does not happen, make the following call before calling `SetScaleToFitSize`: +`SetScaleToFitSize` assumes that the size of the view window has been set. If the view window size hasn't been set when `SetScaleToFitSize` is called, you'll get an assertion. To ensure that this doesn't happen, make the following call before calling `SetScaleToFitSize`: [!code-cpp[NVC_MFCDocView#165](../../mfc/codesnippet/cpp/cscrollview-class_2.cpp)] -## CScrollView::SetScrollSizes +## `CScrollView::SetScrollSizes` Call `SetScrollSizes` when the view is about to be updated. @@ -302,34 +301,34 @@ void SetScrollSizes( ### Parameters -*nMapMode*
+*`nMapMode`*\ The mapping mode to set for this view. Possible values include: |Mapping Mode|Logical Unit|Positive y-axis Extends...| |------------------|------------------|---------------------------------| -|MM_TEXT|1 pixel|Downward| -|MM_HIMETRIC|0.01 mm|Upward| -|MM_TWIPS|1/1440 in|Upward| -|MM_HIENGLISH|0.001 in|Upward| -|MM_LOMETRIC|0.1 mm|Upward| -|MM_LOENGLISH|0.01 in|Upward| +|`MM_TEXT`|1 pixel|Downward| +|`MM_HIMETRIC`|0.01 mm|Upward| +|`MM_TWIPS`|1/1440 in|Upward| +|`MM_HIENGLISH`|0.001 in|Upward| +|`MM_LOMETRIC`|0.1 mm|Upward| +|`MM_LOENGLISH`|0.01 in|Upward| -All of these modes are defined by Windows. Two standard mapping modes, MM_ISOTROPIC and MM_ANISOTROPIC, are not used for `CScrollView`. The class library provides the `SetScaleToFitSize` member function for scaling the view to window size. Column three in the table above describes the coordinate orientation. +All of these modes are defined by Windows. Two standard mapping modes, `MM_ISOTROPIC` and `MM_ANISOTROPIC`, aren't used for `CScrollView`. The class library provides the `SetScaleToFitSize` member function for scaling the view to window size. Column three in the table above describes the coordinate orientation. -*sizeTotal*
+*`sizeTotal`*\ The total size of the scroll view. The `cx` member contains the horizontal extent. The `cy` member contains the vertical extent. Sizes are in logical units. Both `cx` and `cy` must be greater than or equal to 0. -*sizePage*
+*`sizePage`*\ The horizontal and vertical amounts to scroll in each direction in response to a mouse click in a scroll-bar shaft. The `cx` member contains the horizontal amount. The `cy` member contains the vertical amount. -*sizeLine*
+*`sizeLine`*\ The horizontal and vertical amounts to scroll in each direction in response to a mouse click in a scroll arrow. The `cx` member contains the horizontal amount. The `cy` member contains the vertical amount. ### Remarks Call it in your override of the `OnUpdate` member function to adjust scrolling characteristics when, for example, the document is initially displayed or when it changes size. -You will typically obtain size information from the view's associated document by calling a document member function, perhaps called `GetMyDocSize`, that you supply with your derived document class. The following code shows this approach: +You'll typically obtain size information from the view's associated document by calling a document member function, perhaps called `GetMyDocSize`, that you supply with your derived document class. The following code shows this approach: [!code-cpp[NVC_MFCDocView#166](../../mfc/codesnippet/cpp/cscrollview-class_3.cpp)] @@ -337,18 +336,17 @@ Alternatively, you might sometimes need to set a fixed size, as in the following [!code-cpp[NVC_MFCDocView#167](../../mfc/codesnippet/cpp/cscrollview-class_4.cpp)] -You must set the mapping mode to any of the Windows mapping modes except MM_ISOTROPIC or MM_ANISOTROPIC. If you want to use an unconstrained mapping mode, call the `SetScaleToFitSize` member function instead of `SetScrollSizes`. +You must set the mapping mode to any of the Windows mapping modes except `MM_ISOTROPIC` or `MM_ANISOTROPIC`. If you want to use an unconstrained mapping mode, call the `SetScaleToFitSize` member function instead of `SetScrollSizes`. ### Example [!code-cpp[NVC_MFCDocView#168](../../mfc/codesnippet/cpp/cscrollview-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#169](../../mfc/codesnippet/cpp/cscrollview-class_6.cpp)] ## See also -[MFC Sample DIBLOOK](../../overview/visual-cpp-samples.md)
-[CView Class](../../mfc/reference/cview-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CView Class](../../mfc/reference/cview-class.md)
-[CSplitterWnd Class](../../mfc/reference/csplitterwnd-class.md) +[MFC Sample `DIBLOOK`](../../overview/visual-cpp-samples.md)\ +[`CView` Class](../../mfc/reference/cview-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CSplitterWnd` Class](../../mfc/reference/csplitterwnd-class.md) diff --git a/docs/mfc/reference/csemaphore-class.md b/docs/mfc/reference/csemaphore-class.md index fce78fae48..a31a4590ab 100644 --- a/docs/mfc/reference/csemaphore-class.md +++ b/docs/mfc/reference/csemaphore-class.md @@ -4,15 +4,14 @@ title: "CSemaphore Class" ms.date: "11/04/2016" f1_keywords: ["CSemaphore", "AFXMT/CSemaphore", "AFXMT/CSemaphore::CSemaphore"] helpviewer_keywords: ["CSemaphore [MFC], CSemaphore"] -ms.assetid: 385fc7e4-8f86-4be2-85e1-d23b38c12f7f --- # CSemaphore Class -An object of class `CSemaphore` represents a "semaphore" — a synchronization object that allows a limited number of threads in one or more processes to access a Maintains a count of the number of threads currently accessing a specified resource. +An object of class `CSemaphore` represents a "semaphore". A semaphore is a synchronization object that controls access to shared resources and prevents race conditions. ## Syntax -``` +```cpp class CSemaphore : public CSyncObject ``` @@ -22,17 +21,17 @@ class CSemaphore : public CSyncObject |Name|Description| |----------|-----------------| -|[CSemaphore::CSemaphore](#csemaphore)|Constructs a `CSemaphore` object.| +|[`CSemaphore::CSemaphore`](#csemaphore)|Constructs a `CSemaphore` object.| ## Remarks -Semaphores are useful in controlling access to a shared resource that can only support a limited number of users. The current count of the `CSemaphore` object is the number of additional users allowed. When the count reaches zero, all attempts to use the resource controlled by the `CSemaphore` object will be inserted into a system queue and wait until they either time out or the count rises above 0. The maximum number of users who can access the controlled resource at one time is specified during construction of the `CSemaphore` object. +Semaphores are useful in controlling access to a shared resource that can only support a limited number of users. The current count of the `CSemaphore` object is the number of other users allowed. When the count reaches zero, all attempts to use the resource controlled by the `CSemaphore` object are inserted into a system queue and wait until they either time out, or the count rises above 0. The maximum number of users who can access the controlled resource at one time is specified during construction of the `CSemaphore` object. -To use a `CSemaphore` object, construct the `CSemaphore` object when it is needed. Specify the name of the semaphore you wish to wait on, and that your application should initially own it. You can then access the semaphore when the constructor returns. Call [CSyncObject::Unlock](../../mfc/reference/csyncobject-class.md#unlock) when you are done accessing the controlled resource. +To use a `CSemaphore` object, construct the `CSemaphore` object when it is needed. Specify the name of the semaphore you wish to wait on, and that your application should initially own it. You can then access the semaphore when the constructor returns. Call [`CSyncObject::Unlock`](../../mfc/reference/csyncobject-class.md#unlock) when you're done accessing the controlled resource. -An alternative method for using `CSemaphore` objects is to add a variable of type `CSemaphore` as a data member to the class you wish to control. During construction of the controlled object, call the constructor of the `CSemaphore` data member specifying the initial access count, maximum access count, name of the semaphore (if it will be used across process boundaries), and desired security attributes. +An alternative method for using `CSemaphore` objects is to add a variable of type `CSemaphore` as a data member to the class you wish to control. During construction of the controlled object, call the constructor of the `CSemaphore` data member specifying the initial access count, maximum access count, name of the semaphore (if it is used across process boundaries), and desired security attributes. -To access resources controlled by `CSemaphore` objects in this manner, first create a variable of either type [CSingleLock](../../mfc/reference/csinglelock-class.md) or type [CMultiLock](../../mfc/reference/cmultilock-class.md) in your resource's access member function. Then call the lock object's `Lock` member function (for example, [CSingleLock::Lock](../../mfc/reference/csinglelock-class.md#lock)). At this point, your thread will either gain access to the resource, wait for the resource to be released and gain access, or wait for the resource to be released and time out, failing to gain access to the resource. In any case, your resource has been accessed in a thread-safe manner. To release the resource, use the lock object's `Unlock` member function (for example, [CSingleLock::Unlock](../../mfc/reference/csinglelock-class.md#unlock)), or allow the lock object to fall out of scope. +To access resources controlled by `CSemaphore` objects in this manner, first create a variable of either type [CSingleLock](../../mfc/reference/csinglelock-class.md) or type [CMultiLock](../../mfc/reference/cmultilock-class.md) in your resource's access member function. Then call the lock object's `Lock` member function (for example, [CSingleLock::Lock](../../mfc/reference/csinglelock-class.md#lock)). At this point, your thread will either gain access to the resource, wait for the resource to be released and gain access, or wait for the resource to be released and time out, failing to gain access to the resource. In any case, your resource is accessed in a thread-safe manner. To release the resource, use the lock object's `Unlock` member function (for example, [CSingleLock::Unlock](../../mfc/reference/csinglelock-class.md#unlock)), or allow the lock object to fall out of scope. Alternatively, you can create a `CSemaphore` object stand-alone, and access it explicitly before attempting to access the controlled resource. This method, while clearer to someone reading your source code, is more prone to error. @@ -54,7 +53,7 @@ For more information on how to use `CSemaphore` objects, see the article [Multit Constructs a named or unnamed `CSemaphore` object. -``` +```cpp CSemaphore( LONG lInitialCount = 1, LONG lMaxCount = 1, @@ -64,26 +63,26 @@ CSemaphore( ### Parameters -*lInitialCount*
+*`lInitialCount`*\ The initial usage count for the semaphore. Must be greater than or equal to 0, and less than or equal to *lMaxCount*. -*lMaxCount*
+*`lMaxCount`*\ The maximum usage count for the semaphore. Must be greater than 0. -*pstrName*
-The name of the semaphore. Must be supplied if the semaphore will be accessed across process boundaries. If `NULL`, the object will be unnamed. If the name matches an existing semaphore, the constructor builds a new `CSemaphore` object which references the semaphore of that name. If the name matches an existing synchronization object that is not a semaphore, the construction will fail. +*`pstrName`*\ +The name of the semaphore. Must be supplied if the semaphore is accessed across process boundaries. If `NULL`, the object will be unnamed. If the name matches an existing semaphore, the constructor builds a new `CSemaphore` object which references the semaphore of that name. If the name matches an existing synchronization object that isn't a semaphore, the construction fails. -*lpsaAttributes*
+*`lpsaAttributes`*\ Security attributes for the semaphore object. For a full description of this structure, see [SECURITY_ATTRIBUTES](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) in the Windows SDK. ### Remarks -To access or release a `CSemaphore` object, create a [CMultiLock](../../mfc/reference/cmultilock-class.md) or [CSingleLock](../../mfc/reference/csinglelock-class.md) object and call its [Lock](../../mfc/reference/csinglelock-class.md#lock) and [Unlock](../../mfc/reference/csinglelock-class.md#unlock) member functions. +To access or release a `CSemaphore` object, create a [`CMultiLock`](../../mfc/reference/cmultilock-class.md) or [`CSingleLock`](../../mfc/reference/csinglelock-class.md) object and call its [`Lock`](../../mfc/reference/csinglelock-class.md#lock) and [Unlock](../../mfc/reference/csinglelock-class.md#unlock) member functions. > [!IMPORTANT] -> After creating the `CSemaphore` object, use [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to ensure that the mutex did not already exist. If the mutex did exist unexpectedly, it may indicate a rogue process is squatting and may be intending to use the mutex maliciously. In this case, the recommended security-conscious procedure is to close the handle and continue as if there was a failure in creating the object. +> After creating the `CSemaphore` object, use [`GetLastError`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) to ensure that the mutex didn't already exist. If the mutex did exist unexpectedly, it may indicate a rogue process is squatting and may be intending to use the mutex maliciously. In this case, the recommended security-conscious procedure is to close the handle and continue as if there was a failure in creating the object. ## See also -[CSyncObject Class](../../mfc/reference/csyncobject-class.md)
+[`CSyncObject` Class](../../mfc/reference/csyncobject-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/csingledoctemplate-class.md b/docs/mfc/reference/csingledoctemplate-class.md index a8ad3922e2..ef86c37389 100644 --- a/docs/mfc/reference/csingledoctemplate-class.md +++ b/docs/mfc/reference/csingledoctemplate-class.md @@ -103,7 +103,7 @@ Dynamically allocate a `CSingleDocTemplate` object and pass it to `CWinApp::AddD ### Example [!code-cpp[NVC_MFCDocViewSDI#13](../../mfc/codesnippet/cpp/csingledoctemplate-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocViewSDI#14](../../mfc/codesnippet/cpp/csingledoctemplate-class_2.cpp)] ## See also diff --git a/docs/mfc/reference/csinglelock-class.md b/docs/mfc/reference/csinglelock-class.md index 8f52c5a4b6..25559869d5 100644 --- a/docs/mfc/reference/csinglelock-class.md +++ b/docs/mfc/reference/csinglelock-class.md @@ -4,9 +4,8 @@ title: "CSingleLock Class" ms.date: "11/04/2016" f1_keywords: ["CSingleLock", "AFXMT/CSingleLock", "AFXMT/CSingleLock::CSingleLock", "AFXMT/CSingleLock::IsLocked", "AFXMT/CSingleLock::Lock", "AFXMT/CSingleLock::Unlock"] helpviewer_keywords: ["CSingleLock [MFC], CSingleLock", "CSingleLock [MFC], IsLocked", "CSingleLock [MFC], Lock", "CSingleLock [MFC], Unlock"] -ms.assetid: 7dae7288-8066-4a3e-85e0-78d28bfc6bc8 --- -# CSingleLock Class +# `CSingleLock` Class Represents the access-control mechanism used in controlling access to a resource in a multithreaded program. @@ -22,25 +21,25 @@ class CSingleLock |Name|Description| |----------|-----------------| -|[CSingleLock::CSingleLock](#csinglelock)|Constructs a `CSingleLock` object.| +|[`CSingleLock::CSingleLock`](#csinglelock)|Constructs a `CSingleLock` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CSingleLock::IsLocked](#islocked)|Determines if the object is locked.| -|[CSingleLock::Lock](#lock)|Waits on a synchronization object.| -|[CSingleLock::Unlock](#unlock)|Releases a synchronization object.| +|[`CSingleLock::IsLocked`](#islocked)|Determines if the object is locked.| +|[`CSingleLock::Lock`](#lock)|Waits on a synchronization object.| +|[`CSingleLock::Unlock`](#unlock)|Releases a synchronization object.| ## Remarks -`CSingleLock` does not have a base class. +`CSingleLock` doesn't have a base class. -In order to use the synchronization classes [CSemaphore](../../mfc/reference/csemaphore-class.md), [CMutex](../../mfc/reference/cmutex-class.md), [CCriticalSection](../../mfc/reference/ccriticalsection-class.md), and [CEvent](../../mfc/reference/cevent-class.md), you must create either a `CSingleLock` or [CMultiLock](../../mfc/reference/cmultilock-class.md) object to wait on and release the synchronization object. Use `CSingleLock` when you only need to wait on one object at a time. Use `CMultiLock` when there are multiple objects that you could use at a particular time. +In order to use the synchronization classes [`CSemaphore`](../../mfc/reference/csemaphore-class.md), [`CMutex`](../../mfc/reference/cmutex-class.md), [`CCriticalSection`](../../mfc/reference/ccriticalsection-class.md), and [`CEvent`](../../mfc/reference/cevent-class.md), you must create either a `CSingleLock` or [`CMultiLock`](../../mfc/reference/cmultilock-class.md) object to wait on and release the synchronization object. Use `CSingleLock` when you only need to wait on one object at a time. Use `CMultiLock` when there are multiple objects that you could use at a particular time. -To use a `CSingleLock` object, call its constructor inside a member function in the controlled resource's class. Then call the [IsLocked](#islocked) member function to determine if the resource is available. If it is, continue with the remainder of the member function. If the resource is unavailable, either wait for a specified amount of time for the resource to be released, or return failure. After use of the resource is complete, either call the [Unlock](#unlock) function if the `CSingleLock` object is to be used again, or allow the `CSingleLock` object to be destroyed. +To use a `CSingleLock` object, call its constructor inside a member function in the controlled resource's class. Then call the [`IsLocked`](#islocked) member function to determine if the resource is available. If it is, continue with the remainder of the member function. If the resource is unavailable, either wait for a specified amount of time for the resource to be released, or return failure. After use of the resource is complete, either call the [`Unlock`](#unlock) function if the `CSingleLock` object is to be used again, or allow the `CSingleLock` object to be destroyed. -`CSingleLock` objects require the presence of an object derived from [CSyncObject](../../mfc/reference/csyncobject-class.md). This is usually a data member of the controlled resource's class. For more information on how to use `CSingleLock` objects, see the article [Multithreading: How to Use the Synchronization Classes](../../parallel/multithreading-how-to-use-the-synchronization-classes.md). +`CSingleLock` objects require the presence of an object derived from [`CSyncObject`](../../mfc/reference/csyncobject-class.md). This is usually a data member of the controlled resource's class. For more information on how to use `CSingleLock` objects, see the article [Multithreading: How to Use the Synchronization Classes](../../parallel/multithreading-how-to-use-the-synchronization-classes.md). ## Inheritance Hierarchy @@ -48,9 +47,9 @@ To use a `CSingleLock` object, call its constructor inside a member function in ## Requirements -**Header:** afxmt.h +**Header:** `afxmt.h` -## CSingleLock::CSingleLock +## `CSingleLock::CSingleLock` Constructs a `CSingleLock` object. @@ -62,10 +61,10 @@ explicit CSingleLock( ### Parameters -*pObject*
-Points to the synchronization object to be accessed. Cannot be NULL. +*`pObject`*\ +Points to the synchronization object to be accessed. Can't be `NULL`. -*bInitialLock*
+*`bInitialLock`*\ Specifies whether to initially attempt to access the supplied object. ### Remarks @@ -76,7 +75,7 @@ This function is generally called from within an access member function of the c [!code-cpp[NVC_MFC_Utilities#19](../../mfc/codesnippet/cpp/csinglelock-class_1.h)] -## CSingleLock::IsLocked +## `CSingleLock::IsLocked` Determines if the object associated with the `CSingleLock` object is nonsignaled (unavailable). @@ -92,7 +91,7 @@ Nonzero if the object is locked; otherwise 0. [!code-cpp[NVC_MFC_Utilities#20](../../mfc/codesnippet/cpp/csinglelock-class_2.h)] -## CSingleLock::Lock +## `CSingleLock::Lock` Call this function to gain access to the resource controlled by the synchronization object supplied to the `CSingleLock` constructor. @@ -102,8 +101,8 @@ BOOL Lock(DWORD dwTimeOut = INFINITE); ### Parameters -*dwTimeOut*
-Specifies the amount of time to wait for the synchronization object to be available (signaled). If INFINITE, `Lock` will wait until the object is signaled before returning. +*`dwTimeOut`*\ +Specifies the amount of time to wait for the synchronization object to be available (signaled). If `INFINITE`, `Lock` will wait until the object is signaled before returning. ### Return Value @@ -111,13 +110,13 @@ Nonzero if the function was successful; otherwise 0. ### Remarks -If the synchronization object is signaled, `Lock` will return successfully and the thread now owns the object. If the synchronization object is nonsignaled (unavailable), `Lock` will wait for the synchronization object to become signaled up to the number of milliseconds specified in the *dwTimeOut* parameter. If the synchronization object did not become signaled in the specified amount of time, `Lock` returns failure. +If the synchronization object is signaled, `Lock` will return successfully and the thread now owns the object. If the synchronization object is nonsignaled (unavailable), `Lock` will wait for the synchronization object to become signaled up to the number of milliseconds specified in the *`dwTimeOut`* parameter. If the synchronization object didn't become signaled in the specified amount of time, `Lock` returns failure. ### Example [!code-cpp[NVC_MFC_Utilities#21](../../mfc/codesnippet/cpp/csinglelock-class_3.h)] -## CSingleLock::Unlock +## `CSingleLock::Unlock` Releases the synchronization object owned by `CSingleLock`. @@ -131,11 +130,11 @@ BOOL Unlock( ### Parameters -*lCount*
-Number of accesses to release. Must be greater than 0. If the specified amount would cause the object's count to exceed its maximum, the count is not changed and the function returns FALSE. +*`lCount`*\ +Number of accesses to release. Must be greater than 0. If the specified amount would cause the object's count to exceed its maximum, the count isn't changed and the function returns `FALSE`. -*lPrevCount*
-Points to a variable to receive the previous count of the synchronization object. If NULL, the previous count is not returned. +*`lPrevCount`*\ +Points to a variable to receive the previous count of the synchronization object. If `NULL`, the previous count isn't returned. ### Return Value @@ -153,5 +152,5 @@ If you need to release more than one access count of a semaphore, use the second ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CMultiLock Class](../../mfc/reference/cmultilock-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CMultiLock` Class](../../mfc/reference/cmultilock-class.md) diff --git a/docs/mfc/reference/csliderctrl-class.md b/docs/mfc/reference/csliderctrl-class.md index e73eae797c..28afb9140d 100644 --- a/docs/mfc/reference/csliderctrl-class.md +++ b/docs/mfc/reference/csliderctrl-class.md @@ -4,9 +4,8 @@ title: "CSliderCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CSliderCtrl", "AFXCMN/CSliderCtrl", "AFXCMN/CSliderCtrl::CSliderCtrl", "AFXCMN/CSliderCtrl::ClearSel", "AFXCMN/CSliderCtrl::ClearTics", "AFXCMN/CSliderCtrl::Create", "AFXCMN/CSliderCtrl::CreateEx", "AFXCMN/CSliderCtrl::GetBuddy", "AFXCMN/CSliderCtrl::GetChannelRect", "AFXCMN/CSliderCtrl::GetLineSize", "AFXCMN/CSliderCtrl::GetNumTics", "AFXCMN/CSliderCtrl::GetPageSize", "AFXCMN/CSliderCtrl::GetPos", "AFXCMN/CSliderCtrl::GetRange", "AFXCMN/CSliderCtrl::GetRangeMax", "AFXCMN/CSliderCtrl::GetRangeMin", "AFXCMN/CSliderCtrl::GetSelection", "AFXCMN/CSliderCtrl::GetThumbLength", "AFXCMN/CSliderCtrl::GetThumbRect", "AFXCMN/CSliderCtrl::GetTic", "AFXCMN/CSliderCtrl::GetTicArray", "AFXCMN/CSliderCtrl::GetTicPos", "AFXCMN/CSliderCtrl::GetToolTips", "AFXCMN/CSliderCtrl::SetBuddy", "AFXCMN/CSliderCtrl::SetLineSize", "AFXCMN/CSliderCtrl::SetPageSize", "AFXCMN/CSliderCtrl::SetPos", "AFXCMN/CSliderCtrl::SetRange", "AFXCMN/CSliderCtrl::SetRangeMax", "AFXCMN/CSliderCtrl::SetRangeMin", "AFXCMN/CSliderCtrl::SetSelection", "AFXCMN/CSliderCtrl::SetThumbLength", "AFXCMN/CSliderCtrl::SetTic", "AFXCMN/CSliderCtrl::SetTicFreq", "AFXCMN/CSliderCtrl::SetTipSide", "AFXCMN/CSliderCtrl::SetToolTips"] helpviewer_keywords: ["CSliderCtrl [MFC], CSliderCtrl", "CSliderCtrl [MFC], ClearSel", "CSliderCtrl [MFC], ClearTics", "CSliderCtrl [MFC], Create", "CSliderCtrl [MFC], CreateEx", "CSliderCtrl [MFC], GetBuddy", "CSliderCtrl [MFC], GetChannelRect", "CSliderCtrl [MFC], GetLineSize", "CSliderCtrl [MFC], GetNumTics", "CSliderCtrl [MFC], GetPageSize", "CSliderCtrl [MFC], GetPos", "CSliderCtrl [MFC], GetRange", "CSliderCtrl [MFC], GetRangeMax", "CSliderCtrl [MFC], GetRangeMin", "CSliderCtrl [MFC], GetSelection", "CSliderCtrl [MFC], GetThumbLength", "CSliderCtrl [MFC], GetThumbRect", "CSliderCtrl [MFC], GetTic", "CSliderCtrl [MFC], GetTicArray", "CSliderCtrl [MFC], GetTicPos", "CSliderCtrl [MFC], GetToolTips", "CSliderCtrl [MFC], SetBuddy", "CSliderCtrl [MFC], SetLineSize", "CSliderCtrl [MFC], SetPageSize", "CSliderCtrl [MFC], SetPos", "CSliderCtrl [MFC], SetRange", "CSliderCtrl [MFC], SetRangeMax", "CSliderCtrl [MFC], SetRangeMin", "CSliderCtrl [MFC], SetSelection", "CSliderCtrl [MFC], SetThumbLength", "CSliderCtrl [MFC], SetTic", "CSliderCtrl [MFC], SetTicFreq", "CSliderCtrl [MFC], SetTipSide", "CSliderCtrl [MFC], SetToolTips"] -ms.assetid: dd12b084-4eda-4550-a810-8f3cfb06b871 --- -# CSliderCtrl Class +# `CSliderCtrl` Class Provides the functionality of the Windows common slider control. @@ -22,45 +21,45 @@ class CSliderCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CSliderCtrl::CSliderCtrl](#csliderctrl)|Constructs a `CSliderCtrl` object.| +|[`CSliderCtrl::CSliderCtrl`](#csliderctrl)|Constructs a `CSliderCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CSliderCtrl::ClearSel](#clearsel)|Clears the current selection in a slider control.| -|[CSliderCtrl::ClearTics](#cleartics)|Removes the current tick marks from a slider control.| -|[CSliderCtrl::Create](#create)|Creates a slider control and attaches it to a `CSliderCtrl` object.| -|[CSliderCtrl::CreateEx](#createex)|Creates a slider control with the specified Windows extended styles and attaches it to a `CSliderCtrl` object.| -|[CSliderCtrl::GetBuddy](#getbuddy)|Retrieves the handle to a slider control buddy window at a given location.| -|[CSliderCtrl::GetChannelRect](#getchannelrect)|Retrieves the size of the slider control's channel.| -|[CSliderCtrl::GetLineSize](#getlinesize)|Retrieves the line size of a slider control.| -|[CSliderCtrl::GetNumTics](#getnumtics)|Retrieves the number of tick marks in a slider control.| -|[CSliderCtrl::GetPageSize](#getpagesize)|Retrieves the page size of a slider control.| -|[CSliderCtrl::GetPos](#getpos)|Retrieves the current position of the slider.| -|[CSliderCtrl::GetRange](#getrange)|Retrieves the minimum and maximum positions for a slider.| -|[CSliderCtrl::GetRangeMax](#getrangemax)|Retrieves the maximum position for a slider.| -|[CSliderCtrl::GetRangeMin](#getrangemin)|Retrieves the minimum position for a slider.| -|[CSliderCtrl::GetSelection](#getselection)|Retrieves the range of the current selection.| -|[CSliderCtrl::GetThumbLength](#getthumblength)|Retrieves the length of the slider in the current trackbar control.| -|[CSliderCtrl::GetThumbRect](#getthumbrect)|Retrieves the size of the slider control's thumb.| -|[CSliderCtrl::GetTic](#gettic)|Retrieves the position of the specified tick mark.| -|[CSliderCtrl::GetTicArray](#getticarray)|Retrieves the array of tick mark positions for a slider control.| -|[CSliderCtrl::GetTicPos](#getticpos)|Retrieves the position of the specified tick mark, in client coordinates.| -|[CSliderCtrl::GetToolTips](#gettooltips)|Retrieves the handle to the tooltip control assigned to the slider control, if any.| -|[CSliderCtrl::SetBuddy](#setbuddy)|Assigns a window as the buddy window for a slider control.| -|[CSliderCtrl::SetLineSize](#setlinesize)|Sets the line size of a slider control.| -|[CSliderCtrl::SetPageSize](#setpagesize)|Sets the page size of a slider control.| -|[CSliderCtrl::SetPos](#setpos)|Sets the current position of the slider.| -|[CSliderCtrl::SetRange](#setrange)|Sets the minimum and maximum positions for a slider.| -|[CSliderCtrl::SetRangeMax](#setrangemax)|Sets the maximum position for a slider.| -|[CSliderCtrl::SetRangeMin](#setrangemin)|Sets the minimum position for a slider.| -|[CSliderCtrl::SetSelection](#setselection)|Sets the range of the current selection.| -|[CSliderCtrl::SetThumbLength](#setthumblength)|Sets the length of the slider in the current trackbar control.| -|[CSliderCtrl::SetTic](#settic)|Sets the position of the specified tick mark.| -|[CSliderCtrl::SetTicFreq](#setticfreq)|Sets the frequency of tick marks per slider control increment.| -|[CSliderCtrl::SetTipSide](#settipside)|Positions a tooltip control used by a trackbar control.| -|[CSliderCtrl::SetToolTips](#settooltips)|Assigns a tooltip control to a slider control.| +|[`CSliderCtrl::ClearSel`](#clearsel)|Clears the current selection in a slider control.| +|[`CSliderCtrl::ClearTics`](#cleartics)|Removes the current tick marks from a slider control.| +|[`CSliderCtrl::Create`](#create)|Creates a slider control and attaches it to a `CSliderCtrl` object.| +|[`CSliderCtrl::CreateEx`](#createex)|Creates a slider control with the specified Windows extended styles and attaches it to a `CSliderCtrl` object.| +|[`CSliderCtrl::GetBuddy`](#getbuddy)|Retrieves the handle to a slider control buddy window at a given location.| +|[`CSliderCtrl::GetChannelRect`](#getchannelrect)|Retrieves the size of the slider control's channel.| +|[`CSliderCtrl::GetLineSize`](#getlinesize)|Retrieves the line size of a slider control.| +|[`CSliderCtrl::GetNumTics`](#getnumtics)|Retrieves the number of tick marks in a slider control.| +|[`CSliderCtrl::GetPageSize`](#getpagesize)|Retrieves the page size of a slider control.| +|[`CSliderCtrl::GetPos`](#getpos)|Retrieves the current position of the slider.| +|[`CSliderCtrl::GetRange`](#getrange)|Retrieves the minimum and maximum positions for a slider.| +|[`CSliderCtrl::GetRangeMax`](#getrangemax)|Retrieves the maximum position for a slider.| +|[`CSliderCtrl::GetRangeMin`](#getrangemin)|Retrieves the minimum position for a slider.| +|[`CSliderCtrl::GetSelection`](#getselection)|Retrieves the range of the current selection.| +|[`CSliderCtrl::GetThumbLength`](#getthumblength)|Retrieves the length of the slider in the current trackbar control.| +|[`CSliderCtrl::GetThumbRect`](#getthumbrect)|Retrieves the size of the slider control's thumb.| +|[`CSliderCtrl::GetTic`](#gettic)|Retrieves the position of the specified tick mark.| +|[`CSliderCtrl::GetTicArray`](#getticarray)|Retrieves the array of tick mark positions for a slider control.| +|[`CSliderCtrl::GetTicPos`](#getticpos)|Retrieves the position of the specified tick mark, in client coordinates.| +|[`CSliderCtrl::GetToolTips`](#gettooltips)|Retrieves the handle to the tooltip control assigned to the slider control, if any.| +|[`CSliderCtrl::SetBuddy`](#setbuddy)|Assigns a window as the buddy window for a slider control.| +|[`CSliderCtrl::SetLineSize`](#setlinesize)|Sets the line size of a slider control.| +|[`CSliderCtrl::SetPageSize`](#setpagesize)|Sets the page size of a slider control.| +|[`CSliderCtrl::SetPos`](#setpos)|Sets the current position of the slider.| +|[`CSliderCtrl::SetRange`](#setrange)|Sets the minimum and maximum positions for a slider.| +|[`CSliderCtrl::SetRangeMax`](#setrangemax)|Sets the maximum position for a slider.| +|[`CSliderCtrl::SetRangeMin`](#setrangemin)|Sets the minimum position for a slider.| +|[`CSliderCtrl::SetSelection`](#setselection)|Sets the range of the current selection.| +|[`CSliderCtrl::SetThumbLength`](#setthumblength)|Sets the length of the slider in the current trackbar control.| +|[`CSliderCtrl::SetTic`](#settic)|Sets the position of the specified tick mark.| +|[`CSliderCtrl::SetTicFreq`](#setticfreq)|Sets the frequency of tick marks per slider control increment.| +|[`CSliderCtrl::SetTipSide`](#settipside)|Positions a tooltip control used by a trackbar control.| +|[`CSliderCtrl::SetToolTips`](#settooltips)|Assigns a tooltip control to a slider control.| ## Remarks @@ -72,25 +71,25 @@ This control (and therefore the `CSliderCtrl` class) is available only to progra The slider moves in increments that you specify when you create it. For example, if you specify that the slider should have a range of five, the slider can only occupy six positions: a position at the left side of the slider control and one position for each increment in the range. Typically, each of these positions is identified by a tick mark. -You create a slider by using the constructor and the `Create` member function of `CSliderCtrl`. Once you have created a slider control, you can use member functions in `CSliderCtrl` to change many of its properties. Changes that you can make include setting the minimum and maximum positions for the slider, drawing tick marks, setting a selection range, and repositioning the slider. +You create a slider by using the constructor and the `Create` member function of `CSliderCtrl`. Once you've created a slider control, you can use member functions in `CSliderCtrl` to change many of its properties. Changes that you can make include setting the minimum and maximum positions for the slider, drawing tick marks, setting a selection range, and repositioning the slider. -For more information on using `CSliderCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using CSliderCtrl](../../mfc/using-csliderctrl.md). +For more information on using `CSliderCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using `CSliderCtrl`](../../mfc/using-csliderctrl.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CSliderCtrl` ## Requirements -**Header:** afxcmn.h +**Header:** `afxcmn.h` -## CSliderCtrl::ClearSel +## `CSliderCtrl::ClearSel` Clears the current selection in a slider control. @@ -100,10 +99,10 @@ void ClearSel(BOOL bRedraw = FALSE); ### Parameters -*bRedraw*
-Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is cleared; otherwise the slider is not redrawn. +*`bRedraw`*\ +Redraw flag. If this parameter is `TRUE`, the slider is redrawn after the selection is cleared; otherwise the slider isn't redrawn. -## CSliderCtrl::ClearTics +## `CSliderCtrl::ClearTics` Removes the current tick marks from a slider control. @@ -113,10 +112,10 @@ void ClearTics(BOOL bRedraw = FALSE); ### Parameters -*bRedraw*
-Redraw flag. If this parameter is TRUE, the slider is redrawn after the tick marks are cleared; otherwise the slider is not redrawn. +*`bRedraw`*\ +Redraw flag. If this parameter is `TRUE`, the slider is redrawn after the tick marks are cleared; otherwise the slider isn't redrawn. -## CSliderCtrl::Create +## `CSliderCtrl::Create` Creates a slider control and attaches it to a `CSliderCtrl` object. @@ -130,16 +129,16 @@ virtual BOOL Create( ### Parameters -*dwStyle*
+*`dwStyle`*\ Specifies the slider control's style. Apply any combination of [slider control styles](/windows/win32/Controls/trackbar-control-styles), described in the Windows SDK, to the control. -*rect*
-Specifies the slider control's size and position. It can be either a [CRect](../../atl-mfc-shared/reference/crect-class.md) object or a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +*`rect`*\ +Specifies the slider control's size and position. It can be either a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -*pParentWnd*
-Specifies the slider control's parent window, usually a `CDialog`. It must not be NULL. +*`pParentWnd`*\ +Specifies the slider control's parent window, usually a `CDialog`. It must not be `NULL`. -*nID*
+*`nID`*\ Specifies the slider control's ID. ### Return Value @@ -150,11 +149,11 @@ Nonzero if initialization was successful; otherwise 0. You construct a `CSliderCtrl` in two steps. First, call the constructor, and then call `Create`, which creates the slider control and attaches it to the `CSliderCtrl` object. -Depending on the values set for *dwStyle*, the slider control can have either a vertical or horizontal orientation. It can have tick marks on either side, both sides, or neither. It can also be used to specify a range of consecutive values. +Depending on the values set for *`dwStyle`*, the slider control can have either a vertical or horizontal orientation. It can have tick marks on either side, both sides, or neither. It can also be used to specify a range of consecutive values. -To apply extended window styles to the slider control, call [CreateEx](#createex) instead of `Create`. +To apply extended window styles to the slider control, call [`CreateEx`](#createex) instead of `Create`. -## CSliderCtrl::CreateEx +## `CSliderCtrl::CreateEx` Creates a control (a child window) and associates it with the `CSliderCtrl` object. @@ -169,19 +168,19 @@ virtual BOOL CreateEx( ### Parameters -*dwExStyle*
-Specifies the extended style of the control being created. For a list of extended Windows styles, see the *dwExStyle* parameter for [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwExStyle`*\ +Specifies the extended style of the control being created. For a list of extended Windows styles, see the *`dwExStyle`* parameter for [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. -*dwStyle*
+*`dwStyle`*\ Specifies the slider control's style. Apply any combination of [slider control styles](/windows/win32/Controls/trackbar-control-styles), described in the Windows SDK, to the control. -*rect*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *pParentWnd*. +*`rect`*\ +A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *`pParentWnd`*. -*pParentWnd*
+*`pParentWnd`*\ A pointer to the window that is the control's parent. -*nID*
+*`nID`*\ The control's child-window ID. ### Return Value @@ -190,9 +189,9 @@ Nonzero if successful; otherwise 0. ### Remarks -Use `CreateEx` instead of [Create](#create) to apply extended Windows styles, specified by the Windows extended style preface **WS_EX_**. +Use `CreateEx` instead of [`Create`](#create) to apply extended Windows styles, specified by the Windows extended style preface **`WS_EX_`**. -## CSliderCtrl::CSliderCtrl +## `CSliderCtrl::CSliderCtrl` Constructs a `CSliderCtrl` object. @@ -200,7 +199,7 @@ Constructs a `CSliderCtrl` object. CSliderCtrl(); ``` -## CSliderCtrl::GetBuddy +## `CSliderCtrl::GetBuddy` Retrieves the handle to a slider control buddy window at a given location. @@ -210,22 +209,22 @@ CWnd* GetBuddy(BOOL fLocation = TRUE) const; ### Parameters -*fLocation*
+*`fLocation`*\ A Boolean value that indicates which of two buddy window handles to retrieve. Can be one of the following values: -- TRUE Retrieves the handle to the buddy to the left of the slider. If the slider control uses the TBS_VERT style, the message will retrieve the buddy above the slider. +- `TRUE` Retrieves the handle to the buddy to the left of the slider. If the slider control uses the `TBS_VERT` style, the message will retrieve the buddy above the slider. -- FALSE Retrieves the handle to the buddy to the right of the slider. If the slider control uses the TBS_VERT style, the message will retrieve the buddy below the slider. +- `FALSE` Retrieves the handle to the buddy to the right of the slider. If the slider control uses the `TBS_VERT` style, the message will retrieve the buddy below the slider. ### Return Value -A pointer to a [CWnd](../../mfc/reference/cwnd-class.md) object that is the buddy window at the location specified by *fLocation*, or NULL if no buddy window exists at that location. +A pointer to a [`CWnd`](../../mfc/reference/cwnd-class.md) object that is the buddy window at the location specified by *`fLocation`*, or `NULL` if no buddy window exists at that location. ### Remarks -This member function implements the behavior of the Win32 message [TBM_GETBUDDY](/windows/win32/Controls/tbm-getbuddy), as described in the Windows SDK. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. +This member function implements the behavior of the Win32 message [`TBM_GETBUDDY`](/windows/win32/Controls/tbm-getbuddy), as described in the Windows SDK. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. -## CSliderCtrl::GetChannelRect +## `CSliderCtrl::GetChannelRect` Retrieves the size and position of the bounding rectangle for a slider control's channel. @@ -235,14 +234,14 @@ void GetChannelRect(LPRECT lprc) const; ### Parameters -*lprc*
-A pointer to a [CRect](../../atl-mfc-shared/reference/crect-class.md) object that contains the size and position of the channel's bounding rectangle when the function returns. +*`lprc`*\ +A pointer to a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that contains the size and position of the channel's bounding rectangle when the function returns. ### Remarks The channel is the area over which the slider moves and which contains the highlight when a range is selected. -## CSliderCtrl::GetLineSize +## `CSliderCtrl::GetLineSize` Retrieves the size of the line for a slider control. @@ -256,9 +255,9 @@ The size of a line for the slider control. ### Remarks -The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notifications. The default setting for the line size is 1. +The line size affects how much the slider moves for the `TB_LINEUP` and `TB_LINEDOWN` notifications. The default setting for the line size is 1. -## CSliderCtrl::GetNumTics +## `CSliderCtrl::GetNumTics` Retrieves the number of tick marks in a slider control. @@ -270,7 +269,7 @@ UINT GetNumTics() const; The number of tick marks in the slider control. -## CSliderCtrl::GetPageSize +## `CSliderCtrl::GetPageSize` Retrieves the size of the page for a slider control. @@ -284,9 +283,9 @@ The size of a page for the slider control. ### Remarks -The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notifications. +The page size affects how much the slider moves for the `TB_PAGEUP` and `TB_PAGEDOWN` notifications. -## CSliderCtrl::GetPos +## `CSliderCtrl::GetPos` Retrieves the current position of the slider in a slider control. @@ -298,7 +297,7 @@ int GetPos() const; The current position. -## CSliderCtrl::GetRange +## `CSliderCtrl::GetRange` Retrieves the maximum and minimum positions for the slider in a slider control. @@ -310,17 +309,17 @@ void GetRange( ### Parameters -*nMin*
+*`nMin`*\ Reference to an integer that receives the minimum position. -*nMax*
+*`nMax`*\ Reference to an integer that receives the maximum position. ### Remarks -This function copies the values into the integers referenced by *nMin* and *nMax*. +This function copies the values into the integers referenced by *`nMin`* and *`nMax`*. -## CSliderCtrl::GetRangeMax +## `CSliderCtrl::GetRangeMax` Retrieves the maximum position for the slider in a slider control. @@ -332,7 +331,7 @@ int GetRangeMax() const; The control's maximum position. -## CSliderCtrl::GetRangeMin +## `CSliderCtrl::GetRangeMin` Retrieves the minimum position for the slider in a slider control. @@ -344,7 +343,7 @@ int GetRangeMin() const; The control's minimum position. -## CSliderCtrl::GetSelection +## `CSliderCtrl::GetSelection` Retrieves the starting and ending positions of the current selection in a slider control. @@ -356,13 +355,13 @@ void GetSelection( ### Parameters -*nMin*
+*`nMin`*\ Reference to an integer that receives the starting position of the current selection. -*nMax*
+*`nMax`*\ Reference to an integer that receives the ending position of the current selection. -## CSliderCtrl::GetThumbLength +## `CSliderCtrl::GetThumbLength` Retrieves the length of the slider in the current trackbar control. @@ -376,9 +375,9 @@ The length of the slider, in pixels. ### Remarks -This method sends the [TBM_GETTHUMBLENGTH](/windows/win32/Controls/tbm-getthumblength) message, which is described in the Windows SDK. +This method sends the [`TBM_GETTHUMBLENGTH`](/windows/win32/Controls/tbm-getthumblength) message, which is described in the Windows SDK. -## CSliderCtrl::GetThumbRect +## `CSliderCtrl::GetThumbRect` Retrieves the size and position of the bounding rectangle for the slider (thumb) in a slider control. @@ -388,10 +387,10 @@ void GetThumbRect(LPRECT lprc) const; ### Parameters -*lprc*
+*`lprc`*\ A pointer to a `CRect` object that contains the bounding rectangle for the slider when the function returns. -## CSliderCtrl::GetTic +## `CSliderCtrl::GetTic` Retrieves the position of a tick mark in a slider control. @@ -401,14 +400,14 @@ int GetTic(int nTic) const; ### Parameters -*nTic*
+*`nTic`*\ Zero-based index identifying a tick mark. ### Return Value -The position of the specified tick mark or - 1 if *nTic* does not specify a valid index. +The position of the specified tick mark or - 1 if *`nTic`* doesn't specify a valid index. -## CSliderCtrl::GetTicArray +## `CSliderCtrl::GetTicArray` Retrieves the address of the array containing the positions of tick marks for a slider control. @@ -420,7 +419,7 @@ DWORD* GetTicArray() const; The address of the array containing tick mark positions for the slider control. -## CSliderCtrl::GetTicPos +## `CSliderCtrl::GetTicPos` Retrieves the current physical position of a tick mark in a slider control. @@ -430,14 +429,14 @@ int GetTicPos(int nTic) const; ### Parameters -*nTic*
+*`nTic`*\ Zero-based index identifying a tick mark. ### Return Value -The physical position, in client coordinates, of the specified tick mark or - 1 if *nTic* does not specify a valid index. +The physical position, in client coordinates, of the specified tick mark or - 1 if *`nTic`* doesn't specify a valid index. -## CSliderCtrl::GetToolTips +## `CSliderCtrl::GetToolTips` Retrieves the handle to the tooltip control assigned to the slider control, if any. @@ -447,15 +446,15 @@ CToolTipCtrl* GetToolTips() const; ### Return Value -A pointer to a [CToolTipCtrl](../../mfc/reference/ctooltipctrl-class.md) object, or NULL if tooltips are not in use. If the slider control does not use the TBS_TOOLTIPS style, the return value is NULL. +A pointer to a [`CToolTipCtrl`](../../mfc/reference/ctooltipctrl-class.md) object, or `NULL` if tooltips aren't in use. If the slider control doesn't use the `TBS_TOOLTIPS` style, the return value is `NULL`. ### Remarks -This member function implements the behavior of the Win32 message [TBM_GETTOOLTIPS](/windows/win32/Controls/tbm-gettooltips), as described in the Windows SDK. Note that this member function returns a `CToolTipCtrl` object instead of a handle to a control. +This member function implements the behavior of the Win32 message [`TBM_GETTOOLTIPS`](/windows/win32/Controls/tbm-gettooltips), as described in the Windows SDK. Note that this member function returns a `CToolTipCtrl` object instead of a handle to a control. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. -## CSliderCtrl::SetBuddy +## `CSliderCtrl::SetBuddy` Assigns a window as the buddy window for a slider control. @@ -467,27 +466,27 @@ CWnd* SetBuddy( ### Parameters -*pWndBuddy*
+*`pWndBuddy`*\ A pointer to a `CWnd` object that will be set as the slider control's buddy. -*fLocation*
+*`fLocation`*\ Value specifying the location at which to display the buddy window. This value can be one of the following: -- TRUE The buddy will appear to the left of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears above the trackbar control. +- `TRUE` The buddy will appear to the left of the trackbar if the trackbar control uses the `TBS_HORZ` style. If the trackbar uses the `TBS_VERT` style, the buddy appears above the trackbar control. -- FALSE The buddy will appear to the right of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears below the trackbar control. +- `FALSE` The buddy will appear to the right of the trackbar if the trackbar control uses the `TBS_HORZ` style. If the trackbar uses the `TBS_VERT` style, the buddy appears below the trackbar control. ### Return Value -A pointer to a [CWnd](../../mfc/reference/cwnd-class.md) object that was previously assigned to the slider control at that location. +A pointer to a [`CWnd`](../../mfc/reference/cwnd-class.md) object that was previously assigned to the slider control at that location. ### Remarks -This member function implements the behavior of the Win32 message [TBM_SETBUDDY](/windows/win32/Controls/tbm-setbuddy), as described in the Windows SDK. Note that this member function uses pointers to `CWnd` objects, rather than window handles for both its return value and parameter. +This member function implements the behavior of the Win32 message [`TBM_SETBUDDY`](/windows/win32/Controls/tbm-setbuddy), as described in the Windows SDK. Note that this member function uses pointers to `CWnd` objects, rather than window handles for both its return value and parameter. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. -## CSliderCtrl::SetLineSize +## `CSliderCtrl::SetLineSize` Sets the size of the line for a slider control. @@ -497,7 +496,7 @@ int SetLineSize(int nSize); ### Parameters -*nSize*
+*`nSize`*\ The new line size of the slider control. ### Return Value @@ -506,9 +505,9 @@ The previous line size. ### Remarks -The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notifications. +The line size affects how much the slider moves for the `TB_LINEUP` and `TB_LINEDOWN` notifications. -## CSliderCtrl::SetPageSize +## `CSliderCtrl::SetPageSize` Sets the size of the page for a slider control. @@ -518,7 +517,7 @@ int SetPageSize(int nSize); ### Parameters -*nSize*
+*`nSize`*\ The new page size of the slider control. ### Return Value @@ -527,9 +526,9 @@ The previous page size. ### Remarks -The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notifications. +The page size affects how much the slider moves for the `TB_PAGEUP` and `TB_PAGEDOWN` notifications. -## CSliderCtrl::SetPos +## `CSliderCtrl::SetPos` Sets the current position of the slider in a slider control. @@ -539,10 +538,10 @@ void SetPos(int nPos); ### Parameters -*nPos*
+*`nPos`*\ Specifies the new slider position. -## CSliderCtrl::SetRange +## `CSliderCtrl::SetRange` Sets the range (minimum and maximum positions) for the slider in a slider control. @@ -555,16 +554,16 @@ void SetRange( ### Parameters -*nMin*
+*`nMin`*\ Minimum position for the slider. -*nMax*
+*`nMax`*\ Maximum position for the slider. -*bRedraw*
-The redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set; otherwise the slider is not redrawn. +*`bRedraw`*\ +The redraw flag. If this parameter is `TRUE`, the slider is redrawn after the range is set; otherwise the slider isn't redrawn. -## CSliderCtrl::SetRangeMax +## `CSliderCtrl::SetRangeMax` Sets the maximum range for the slider in a slider control. @@ -576,13 +575,13 @@ void SetRangeMax( ### Parameters -*nMax*
+*`nMax`*\ Maximum position for the slider. -*bRedraw*
-The redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set; otherwise the slider is not redrawn. +*`bRedraw`*\ +The redraw flag. If this parameter is `TRUE`, the slider is redrawn after the range is set; otherwise the slider isn't redrawn. -## CSliderCtrl::SetRangeMin +## `CSliderCtrl::SetRangeMin` Sets the minimum range for the slider in a slider control. @@ -594,13 +593,13 @@ void SetRangeMin( ### Parameters -*nMin*
+*`nMin`*\ Minimum position for the slider. -*bRedraw*
-The redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set; otherwise the slider is not redrawn. +*`bRedraw`*\ +The redraw flag. If this parameter is `TRUE`, the slider is redrawn after the range is set; otherwise the slider isn't redrawn. -## CSliderCtrl::SetSelection +## `CSliderCtrl::SetSelection` Sets the starting and ending positions for the current selection in a slider control. @@ -612,13 +611,13 @@ void SetSelection( ### Parameters -*nMin*
+*`nMin`*\ Starting position for the slider. -*nMax*
+*`nMax`*\ Ending position for the slider. -## CSliderCtrl::SetThumbLength +## `CSliderCtrl::SetThumbLength` Sets the length of the slider in the current trackbar control. @@ -628,14 +627,14 @@ void SetThumbLength(int nLength); ### Parameters -*nLength*\ +*`nLength`*\ [in] Length of the slider, in pixels. ### Remarks -This method requires that the trackbar control be set to [TBS_FIXEDLENGTH](/windows/win32/Controls/trackbar-control-styles) style. +This method requires that the trackbar control be set to [`TBS_FIXEDLENGTH`](/windows/win32/Controls/trackbar-control-styles) style. -This method sends the [TBM_SETTHUMBLENGTH](/windows/win32/Controls/tbm-setthumblength) message, which is described in the Windows SDK. +This method sends the [`TBM_SETTHUMBLENGTH`](/windows/win32/Controls/tbm-setthumblength) message, which is described in the Windows SDK. ### Example @@ -647,7 +646,7 @@ The next code example sets the trackbar control's thumb component to twice its d [!code-cpp[NVC_MFC_CSliderCtrl_s1#2](../../mfc/reference/codesnippet/cpp/csliderctrl-class_2.cpp)] -## CSliderCtrl::SetTic +## `CSliderCtrl::SetTic` Sets the position of a tick mark in a slider control. @@ -657,14 +656,14 @@ BOOL SetTic(int nTic); ### Parameters -*nTic*
+*`nTic`*\ Position of the tick mark. This parameter must specify a positive value. ### Return Value Nonzero if the tick mark is set; otherwise 0. -## CSliderCtrl::SetTicFreq +## `CSliderCtrl::SetTicFreq` Sets the frequency with which tick marks are displayed in a slider. @@ -674,16 +673,16 @@ void SetTicFreq(int nFreq); ### Parameters -*nFreq*
+*`nFreq`*\ Frequency of the tick marks. ### Remarks For example, if the frequency is set to 2, a tick mark is displayed for every other increment in the slider's range. The default setting for the frequency is 1 (that is, every increment in the range is associated with a tick mark). -You must create the control with the TBS_AUTOTICKS style to use this function. For more information, see [CSliderCtrl::Create](#create). +You must create the control with the `TBS_AUTOTICKS` style to use this function. For more information, see [`CSliderCtrl::Create`](#create). -## CSliderCtrl::SetTipSide +## `CSliderCtrl::SetTipSide` Positions a tooltip control used by a trackbar control. @@ -693,18 +692,18 @@ int SetTipSide(int nLocation); ### Parameters -*nLocation*
-Value representing the location at which to display the tooltip control. For a list of possible values, see the Win32 message [TBM_SETTIPSIDE](/windows/win32/Controls/tbm-settipside), as described in the Windows SDK. +*`nLocation`*\ +Value representing the location at which to display the tooltip control. For a list of possible values, see the Win32 message [`TBM_SETTIPSIDE`](/windows/win32/Controls/tbm-settipside), as described in the Windows SDK. ### Return Value -A value that represents the tooltip control's previous location. The return value equals one of the possible values for *nLocation*. +A value that represents the tooltip control's previous location. The return value equals one of the possible values for *`nLocation`*. ### Remarks -This member function implements the behavior of the Win32 message TBM_SETTIPSIDE, as described in the Windows SDK. Slider controls that use the TBS_TOOLTIPS style display tooltips. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. +This member function implements the behavior of the Win32 message `TBM_SETTIPSIDE`, as described in the Windows SDK. Slider controls that use the `TBS_TOOLTIPS` style display tooltips. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. -## CSliderCtrl::SetToolTips +## `CSliderCtrl::SetToolTips` Assigns a tooltip control to a slider control. @@ -714,16 +713,16 @@ void SetToolTips(CToolTipCtrl* pWndTip); ### Parameters -*pWndTip*
-A pointer to a [CToolTipCtrl](../../mfc/reference/ctooltipctrl-class.md) object containing the tooltips to use with the slider control. +*`pWndTip`*\ +A pointer to a [`CToolTipCtrl`](../../mfc/reference/ctooltipctrl-class.md) object containing the tooltips to use with the slider control. ### Remarks -This member function implements the behavior of the Win32 message [TBM_SETTOOLTIPS](/windows/win32/Controls/tbm-settooltips), as described in the Windows SDK. When a slider control is created with the TBS_TOOLTIPS style, it creates a default tooltip control that appears next to the slider, displaying the slider's current position. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. +This member function implements the behavior of the Win32 message [`TBM_SETTOOLTIPS`](/windows/win32/Controls/tbm-settooltips), as described in the Windows SDK. When a slider control is created with the `TBS_TOOLTIPS` style, it creates a default tooltip control that appears next to the slider, displaying the slider's current position. For a description of the slider control styles, see [Trackbar Control Styles](/windows/win32/Controls/trackbar-control-styles) in the Windows SDK. ## See also -[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CProgressCtrl Class](../../mfc/reference/cprogressctrl-class.md) +[MFC Sample `CMNCTRL2`](../../overview/visual-cpp-samples.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CProgressCtrl` Class](../../mfc/reference/cprogressctrl-class.md) diff --git a/docs/mfc/reference/csocket-class.md b/docs/mfc/reference/csocket-class.md index 437001deb4..b7cb5b69c9 100644 --- a/docs/mfc/reference/csocket-class.md +++ b/docs/mfc/reference/csocket-class.md @@ -99,9 +99,9 @@ For more information, see [Windows Sockets: Using Sockets with Archives](../../m ### Example [!code-cpp[NVC_MFCSocketThread#1](../../mfc/reference/codesnippet/cpp/csocket-class_2.h)] - +  [!code-cpp[NVC_MFCSocketThread#2](../../mfc/reference/codesnippet/cpp/csocket-class_3.cpp)] - +  [!code-cpp[NVC_MFCSocketThread#3](../../mfc/reference/codesnippet/cpp/csocket-class_4.cpp)] ## `CSocket::CancelBlockingCall` diff --git a/docs/mfc/reference/cspinbuttonctrl-class.md b/docs/mfc/reference/cspinbuttonctrl-class.md index b9e1628b64..ccd132b239 100644 --- a/docs/mfc/reference/cspinbuttonctrl-class.md +++ b/docs/mfc/reference/cspinbuttonctrl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CSpinButtonCtrl Class" title: "CSpinButtonCtrl Class" +description: "Learn more about: CSpinButtonCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CSpinButtonCtrl", "AFXCMN/CSpinButtonCtrl", "AFXCMN/CSpinButtonCtrl::CSpinButtonCtrl", "AFXCMN/CSpinButtonCtrl::Create", "AFXCMN/CSpinButtonCtrl::CreateEx", "AFXCMN/CSpinButtonCtrl::GetAccel", "AFXCMN/CSpinButtonCtrl::GetBase", "AFXCMN/CSpinButtonCtrl::GetBuddy", "AFXCMN/CSpinButtonCtrl::GetPos", "AFXCMN/CSpinButtonCtrl::GetRange", "AFXCMN/CSpinButtonCtrl::SetAccel", "AFXCMN/CSpinButtonCtrl::SetBase", "AFXCMN/CSpinButtonCtrl::SetBuddy", "AFXCMN/CSpinButtonCtrl::SetPos", "AFXCMN/CSpinButtonCtrl::SetRange"] helpviewer_keywords: ["CSpinButtonCtrl [MFC], CSpinButtonCtrl", "CSpinButtonCtrl [MFC], Create", "CSpinButtonCtrl [MFC], CreateEx", "CSpinButtonCtrl [MFC], GetAccel", "CSpinButtonCtrl [MFC], GetBase", "CSpinButtonCtrl [MFC], GetBuddy", "CSpinButtonCtrl [MFC], GetPos", "CSpinButtonCtrl [MFC], GetRange", "CSpinButtonCtrl [MFC], SetAccel", "CSpinButtonCtrl [MFC], SetBase", "CSpinButtonCtrl [MFC], SetBuddy", "CSpinButtonCtrl [MFC], SetPos", "CSpinButtonCtrl [MFC], SetRange"] -ms.assetid: 509bfd76-1c5a-4af6-973f-e133c0b87734 --- # CSpinButtonCtrl Class @@ -71,7 +70,7 @@ For more information on using `CSpinButtonCtrl`, see [Controls](../../mfc/contro ## CSpinButtonCtrl::Create -Creates a spin button control and attaches it to a `CSpinButtonCtrl` object.. +Creates a spin button control and attaches it to a `CSpinButtonCtrl` object. ``` virtual BOOL Create( @@ -366,7 +365,7 @@ The member function `SetRange32` sets the 32-bit range for the spin button contr ## See also -[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[MFC Sample CMNCTRL2](../../overview/visual-cpp-samples.md)\ +[CWnd Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [CSliderCtrl Class](../../mfc/reference/csliderctrl-class.md) diff --git a/docs/mfc/reference/csplitterwnd-class.md b/docs/mfc/reference/csplitterwnd-class.md index 15dece13f8..da72f6e13b 100644 --- a/docs/mfc/reference/csplitterwnd-class.md +++ b/docs/mfc/reference/csplitterwnd-class.md @@ -4,9 +4,8 @@ title: "CSplitterWnd Class" ms.date: "11/04/2016" f1_keywords: ["CSplitterWnd", "AFXEXT/CSplitterWnd", "AFXEXT/CSplitterWnd::CSplitterWnd", "AFXEXT/CSplitterWnd::ActivateNext", "AFXEXT/CSplitterWnd::CanActivateNext", "AFXEXT/CSplitterWnd::Create", "AFXEXT/CSplitterWnd::CreateScrollBarCtrl", "AFXEXT/CSplitterWnd::CreateStatic", "AFXEXT/CSplitterWnd::CreateView", "AFXEXT/CSplitterWnd::DeleteColumn", "AFXEXT/CSplitterWnd::DeleteRow", "AFXEXT/CSplitterWnd::DeleteView", "AFXEXT/CSplitterWnd::DoKeyboardSplit", "AFXEXT/CSplitterWnd::DoScroll", "AFXEXT/CSplitterWnd::DoScrollBy", "AFXEXT/CSplitterWnd::GetActivePane", "AFXEXT/CSplitterWnd::GetColumnCount", "AFXEXT/CSplitterWnd::GetColumnInfo", "AFXEXT/CSplitterWnd::GetPane", "AFXEXT/CSplitterWnd::GetRowCount", "AFXEXT/CSplitterWnd::GetRowInfo", "AFXEXT/CSplitterWnd::GetScrollStyle", "AFXEXT/CSplitterWnd::IdFromRowCol", "AFXEXT/CSplitterWnd::IsChildPane", "AFXEXT/CSplitterWnd::IsTracking", "AFXEXT/CSplitterWnd::RecalcLayout", "AFXEXT/CSplitterWnd::SetActivePane", "AFXEXT/CSplitterWnd::SetColumnInfo", "AFXEXT/CSplitterWnd::SetRowInfo", "AFXEXT/CSplitterWnd::SetScrollStyle", "AFXEXT/CSplitterWnd::SplitColumn", "AFXEXT/CSplitterWnd::SplitRow", "AFXEXT/CSplitterWnd::OnDraw", "AFXEXT/CSplitterWnd::OnDrawSplitter", "AFXEXT/CSplitterWnd::OnInvertTracker"] helpviewer_keywords: ["CSplitterWnd [MFC], CSplitterWnd", "CSplitterWnd [MFC], ActivateNext", "CSplitterWnd [MFC], CanActivateNext", "CSplitterWnd [MFC], Create", "CSplitterWnd [MFC], CreateScrollBarCtrl", "CSplitterWnd [MFC], CreateStatic", "CSplitterWnd [MFC], CreateView", "CSplitterWnd [MFC], DeleteColumn", "CSplitterWnd [MFC], DeleteRow", "CSplitterWnd [MFC], DeleteView", "CSplitterWnd [MFC], DoKeyboardSplit", "CSplitterWnd [MFC], DoScroll", "CSplitterWnd [MFC], DoScrollBy", "CSplitterWnd [MFC], GetActivePane", "CSplitterWnd [MFC], GetColumnCount", "CSplitterWnd [MFC], GetColumnInfo", "CSplitterWnd [MFC], GetPane", "CSplitterWnd [MFC], GetRowCount", "CSplitterWnd [MFC], GetRowInfo", "CSplitterWnd [MFC], GetScrollStyle", "CSplitterWnd [MFC], IdFromRowCol", "CSplitterWnd [MFC], IsChildPane", "CSplitterWnd [MFC], IsTracking", "CSplitterWnd [MFC], RecalcLayout", "CSplitterWnd [MFC], SetActivePane", "CSplitterWnd [MFC], SetColumnInfo", "CSplitterWnd [MFC], SetRowInfo", "CSplitterWnd [MFC], SetScrollStyle", "CSplitterWnd [MFC], SplitColumn", "CSplitterWnd [MFC], SplitRow", "CSplitterWnd [MFC], OnDraw", "CSplitterWnd [MFC], OnDrawSplitter", "CSplitterWnd [MFC], OnInvertTracker"] -ms.assetid: fd0de258-6dbe-4552-9e47-a39de0471d51 --- -# CSplitterWnd Class +# `CSplitterWnd` Class Provides the functionality of a splitter window, which is a window that contains multiple panes. @@ -22,65 +21,65 @@ class CSplitterWnd : public CWnd |Name|Description| |----------|-----------------| -|[CSplitterWnd::CSplitterWnd](#csplitterwnd)|Call to construct a `CSplitterWnd` object.| +|[`CSplitterWnd::CSplitterWnd`](#csplitterwnd)|Call to construct a `CSplitterWnd` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CSplitterWnd::ActivateNext](#activatenext)|Performs the Next Pane or Previous Pane command.| -|[CSplitterWnd::CanActivateNext](#canactivatenext)|Checks to see if the Next Pane or Previous Pane command is currently possible.| -|[CSplitterWnd::Create](#create)|Call to create a dynamic splitter window and attach it to the `CSplitterWnd` object.| -|[CSplitterWnd::CreateScrollBarCtrl](#createscrollbarctrl)|Creates a shared scroll bar control.| -|[CSplitterWnd::CreateStatic](#createstatic)|Call to create a static splitter window and attach it to the `CSplitterWnd` object.| -|[CSplitterWnd::CreateView](#createview)|Call to create a pane in a splitter window.| -|[CSplitterWnd::DeleteColumn](#deletecolumn)|Deletes a column from the splitter window.| -|[CSplitterWnd::DeleteRow](#deleterow)|Deletes a row from the splitter window.| -|[CSplitterWnd::DeleteView](#deleteview)|Deletes a view from the splitter window.| -|[CSplitterWnd::DoKeyboardSplit](#dokeyboardsplit)|Performs the keyboard split command, usually "Window Split."| -|[CSplitterWnd::DoScroll](#doscroll)|Performs synchronized scrolling of split windows.| -|[CSplitterWnd::DoScrollBy](#doscrollby)|Scrolls split windows by a given number of pixels.| -|[CSplitterWnd::GetActivePane](#getactivepane)|Determines the active pane from the focus or active view in the frame.| -|[CSplitterWnd::GetColumnCount](#getcolumncount)|Returns the current pane column count.| -|[CSplitterWnd::GetColumnInfo](#getcolumninfo)|Returns information on the specified column.| -|[CSplitterWnd::GetPane](#getpane)|Returns the pane at the specified row and column.| -|[CSplitterWnd::GetRowCount](#getrowcount)|Returns the current pane row count.| -|[CSplitterWnd::GetRowInfo](#getrowinfo)|Returns information on the specified row.| -|[CSplitterWnd::GetScrollStyle](#getscrollstyle)|Returns the shared scroll-bar style.| -|[CSplitterWnd::IdFromRowCol](#idfromrowcol)|Returns the child window ID of the pane at the specified row and column.| -|[CSplitterWnd::IsChildPane](#ischildpane)|Call to determine whether the window is currently a child pane of this splitter window.| -|[CSplitterWnd::IsTracking](#istracking)|Determines if splitter bar is currently being moved.| -|[CSplitterWnd::RecalcLayout](#recalclayout)|Call to redisplay the splitter window after adjusting row or column size.| -|[CSplitterWnd::SetActivePane](#setactivepane)|Sets a pane to be the active one in the frame.| -|[CSplitterWnd::SetColumnInfo](#setcolumninfo)|Call to set the specified column information.| -|[CSplitterWnd::SetRowInfo](#setrowinfo)|Call to set the specified row information.| -|[CSplitterWnd::SetScrollStyle](#setscrollstyle)|Specifies the new scroll-bar style for the splitter window's shared scroll-bar support.| -|[CSplitterWnd::SplitColumn](#splitcolumn)|Indicates where a frame window splits vertically.| -|[CSplitterWnd::SplitRow](#splitrow)|Indicates where a frame window splits horizontally.| +|[`CSplitterWnd::ActivateNext`](#activatenext)|Performs the Next Pane or Previous Pane command.| +|[`CSplitterWnd::CanActivateNext`](#canactivatenext)|Checks to see if the Next Pane or Previous Pane command is currently possible.| +|[`CSplitterWnd::Create`](#create)|Call to create a dynamic splitter window and attach it to the `CSplitterWnd` object.| +|[`CSplitterWnd::CreateScrollBarCtrl`](#createscrollbarctrl)|Creates a shared scroll bar control.| +|[`CSplitterWnd::CreateStatic`](#createstatic)|Call to create a static splitter window and attach it to the `CSplitterWnd` object.| +|[`CSplitterWnd::CreateView`](#createview)|Call to create a pane in a splitter window.| +|[`CSplitterWnd::DeleteColumn`](#deletecolumn)|Deletes a column from the splitter window.| +|[`CSplitterWnd::DeleteRow`](#deleterow)|Deletes a row from the splitter window.| +|[`CSplitterWnd::DeleteView`](#deleteview)|Deletes a view from the splitter window.| +|[`CSplitterWnd::DoKeyboardSplit`](#dokeyboardsplit)|Performs the keyboard split command, usually "Window Split."| +|[`CSplitterWnd::DoScroll`](#doscroll)|Performs synchronized scrolling of split windows.| +|[`CSplitterWnd::DoScrollBy`](#doscrollby)|Scrolls split windows by a given number of pixels.| +|[`CSplitterWnd::GetActivePane`](#getactivepane)|Determines the active pane from the focus or active view in the frame.| +|[`CSplitterWnd::GetColumnCount`](#getcolumncount)|Returns the current pane column count.| +|[`CSplitterWnd::GetColumnInfo`](#getcolumninfo)|Returns information on the specified column.| +|[`CSplitterWnd::GetPane`](#getpane)|Returns the pane at the specified row and column.| +|[`CSplitterWnd::GetRowCount`](#getrowcount)|Returns the current pane row count.| +|[`CSplitterWnd::GetRowInfo`](#getrowinfo)|Returns information on the specified row.| +|[`CSplitterWnd::GetScrollStyle`](#getscrollstyle)|Returns the shared scroll-bar style.| +|[`CSplitterWnd::IdFromRowCol`](#idfromrowcol)|Returns the child window ID of the pane at the specified row and column.| +|[`CSplitterWnd::IsChildPane`](#ischildpane)|Call to determine whether the window is currently a child pane of this splitter window.| +|[`CSplitterWnd::IsTracking`](#istracking)|Determines if splitter bar is currently being moved.| +|[`CSplitterWnd::RecalcLayout`](#recalclayout)|Call to redisplay the splitter window after adjusting row or column size.| +|[`CSplitterWnd::SetActivePane`](#setactivepane)|Sets a pane to be the active one in the frame.| +|[`CSplitterWnd::SetColumnInfo`](#setcolumninfo)|Call to set the specified column information.| +|[`CSplitterWnd::SetRowInfo`](#setrowinfo)|Call to set the specified row information.| +|[`CSplitterWnd::SetScrollStyle`](#setscrollstyle)|Specifies the new scroll-bar style for the splitter window's shared scroll-bar support.| +|[`CSplitterWnd::SplitColumn`](#splitcolumn)|Indicates where a frame window splits vertically.| +|[`CSplitterWnd::SplitRow`](#splitrow)|Indicates where a frame window splits horizontally.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CSplitterWnd::OnDraw](#ondraw)|Called by the framework to draw the splitter window.| -|[CSplitterWnd::OnDrawSplitter](#ondrawsplitter)|Renders an image of a split window.| -|[CSplitterWnd::OnInvertTracker](#oninverttracker)|Renders the image of a split window to be the same size and shape as the frame window.| +|[`CSplitterWnd::OnDraw`](#ondraw)|Called by the framework to draw the splitter window.| +|[`CSplitterWnd::OnDrawSplitter`](#ondrawsplitter)|Renders an image of a split window.| +|[`CSplitterWnd::OnInvertTracker`](#oninverttracker)|Renders the image of a split window to be the same size and shape as the frame window.| ## Remarks -A pane is usually an application-specific object derived from [CView](../../mfc/reference/cview-class.md), but it can be any [CWnd](../../mfc/reference/cwnd-class.md) object that has the appropriate child window ID. +A pane is usually an application-specific object derived from [`CView`](../../mfc/reference/cview-class.md), but it can be any [`CWnd`](../../mfc/reference/cwnd-class.md) object that has the appropriate child window ID. -A `CSplitterWnd` object is usually embedded in a parent [CFrameWnd](../../mfc/reference/cframewnd-class.md) or [CMDIChildWnd](../../mfc/reference/cmdichildwnd-class.md) object. Create a `CSplitterWnd` object using the following steps: +A `CSplitterWnd` object is usually embedded in a parent [`CFrameWnd`](../../mfc/reference/cframewnd-class.md) or [`CMDIChildWnd`](../../mfc/reference/cmdichildwnd-class.md) object. Create a `CSplitterWnd` object using the following steps: 1. Embed a `CSplitterWnd` member variable in the parent frame. -2. Override the parent frame's [CFrameWnd::OnCreateClient](../../mfc/reference/cframewnd-class.md#oncreateclient) member function. +2. Override the parent frame's [`CFrameWnd::OnCreateClient`](../../mfc/reference/cframewnd-class.md#oncreateclient) member function. -3. From within the overridden `OnCreateClient`, call the [Create](#create) or [CreateStatic](#createstatic) member function of `CSplitterWnd`. +3. From within the overridden `OnCreateClient`, call the [`Create`](#create) or [`CreateStatic`](#createstatic) member function of `CSplitterWnd`. Call the `Create` member function to create a dynamic splitter window. A dynamic splitter window typically is used to create and scroll a number of individual panes, or views, of the same document. The framework automatically creates an initial pane for the splitter; then the framework creates, resizes, and disposes of additional panes as the user operates the splitter window's controls. -When you call `Create`, you specify a minimum row height and column width that determine when the panes are too small to be fully displayed. After you call `Create`, you can adjust these minimums by calling the [SetColumnInfo](#setcolumninfo) and [SetRowInfo](#setrowinfo) member functions. +When you call `Create`, you specify a minimum row height and column width that determine when the panes are too small to be fully displayed. After you call `Create`, you can adjust these minimums by calling the [`SetColumnInfo`](#setcolumninfo) and [`SetRowInfo`](#setrowinfo) member functions. Also use the `SetColumnInfo` and `SetRowInfo` member functions to set an "ideal" width for a column and "ideal" height for a row. When the framework displays a splitter window, it first displays the parent frame, then the splitter window. The framework then lays out the panes in columns and rows according to their ideal dimensions, working from the upper-left to the lower-right corner of the splitter window's client area. @@ -88,15 +87,15 @@ All panes in a dynamic splitter window must be of the same class. Familiar appli Use the `CreateStatic` member function to create a static splitter window. The user can change only the size of the panes in a static splitter window, not their number or order. -You must specifically create all the static splitter's panes when you create the static splitter. Make sure you create all the panes before the parent frame's `OnCreateClient` member function returns, or the framework will not display the window correctly. +You must specifically create all the static splitter's panes when you create the static splitter. Make sure you create all the panes before the parent frame's `OnCreateClient` member function returns, or the framework won't display the window correctly. -The `CreateStatic` member function automatically initializes a static splitter with a minimum row height and column width of 0. After you call `Create`, adjust these minimums by calling the [SetColumnInfo](#setcolumninfo) and [SetRowInfo](#setrowinfo) member functions. Also use `SetColumnInfo` and `SetRowInfo` after you call `CreateStatic` to indicate desired ideal pane dimensions. +The `CreateStatic` member function automatically initializes a static splitter with a minimum row height and column width of 0. After you call `Create`, adjust these minimums by calling the [`SetColumnInfo`](#setcolumninfo) and [`SetRowInfo`](#setrowinfo) member functions. Also use `SetColumnInfo` and `SetRowInfo` after you call `CreateStatic` to indicate desired ideal pane dimensions. The individual panes of a static splitter often belong to different classes. For examples of static splitter windows, see the graphics editor and the Windows File Manager. A splitter window supports special scroll bars (apart from the scroll bars that panes may have). These scroll bars are children of the `CSplitterWnd` object and are shared with the panes. -You create these special scroll bars when you create the splitter window. For example, a `CSplitterWnd` that has one row, two columns, and the WS_VSCROLL style will display a vertical scroll bar that is shared by the two panes. When the user moves the scroll bar, WM_VSCROLL messages are sent to both panes. When the panes set the scroll-bar position, the shared scroll bar is set. +You create these special scroll bars when you create the splitter window. For example, a `CSplitterWnd` that has one row, two columns, and the `WS_VSCROLL` style will display a vertical scroll bar that is shared by the two panes. When the user moves the scroll bar, `WM_VSCROLL` messages are sent to both panes. When the panes set the scroll-bar position, the shared scroll bar is set. For further information on splitter windows, see [Technical Note 29](../../mfc/tn029-splitter-windows.md). @@ -104,23 +103,23 @@ For more information on how to create dynamic splitter windows, see: - MFC sample [Scribble](../../overview/visual-cpp-samples.md) -- MFC sample [VIEWEX](../../overview/visual-cpp-samples.md). +- MFC sample [`VIEWEX`](../../overview/visual-cpp-samples.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CSplitterWnd` ## Requirements -**Header:** afxext.h +**Header:** `afxext.h` -## CSplitterWnd::ActivateNext +## `CSplitterWnd::ActivateNext` Called by the framework to perform the Next Pane or Previous Pane command. @@ -130,14 +129,14 @@ virtual void ActivateNext(BOOL bPrev = FALSE); ### Parameters -*bPrev*
-Indicates which window to activate. **TRUE** for previous; **FALSE** for next. +*`bPrev`*\ +Indicates which window to activate. **`TRUE`** for previous; **`FALSE`** for next. ### Remarks -This member function is a high level command that is used by the [CView](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. +This member function is a high level command that is used by the [`CView`](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. -## CSplitterWnd::CanActivateNext +## `CSplitterWnd::CanActivateNext` Called by the framework to check to see if the Next Pane or Previous Pane command is currently possible. @@ -147,8 +146,8 @@ virtual BOOL CanActivateNext(BOOL bPrev = FALSE); ### Parameters -*bPrev*
-Indicates which window to activate. **TRUE** for previous; **FALSE** for next. +*`bPrev`*\ +Indicates which window to activate. **`TRUE`** for previous; **`FALSE`** for next. ### Return Value @@ -156,9 +155,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function is a high level command that is used by the [CView](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. +This member function is a high level command that is used by the [`CView`](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. -## CSplitterWnd::Create +## `CSplitterWnd::Create` To create a dynamic splitter window, call the `Create` member function. @@ -175,26 +174,26 @@ virtual BOOL Create( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ The parent frame window of the splitter window. -*nMaxRows*
+*`nMaxRows`*\ The maximum number of rows in the splitter window. This value must not exceed 2. -*nMaxCols*
+*`nMaxCols`*\ The maximum number of columns in the splitter window. This value must not exceed 2. -*sizeMin*
+*`sizeMin`*\ Specifies the minimum size at which a pane may be displayed. -*pContext*
-A pointer to a [CCreateContext](../../mfc/reference/ccreatecontext-structure.md) structure. In most cases, this can be the *pContext* passed to the parent frame window. +*`pContext`*\ +A pointer to a [`CCreateContext`](../../mfc/reference/ccreatecontext-structure.md) structure. In most cases, this can be the *`pContext`* passed to the parent frame window. -*dwStyle*
+*`dwStyle`*\ Specifies the window style. -*nID*
-The child window ID of the window. The ID can be AFX_IDW_PANE_FIRST unless the splitter window is nested inside another splitter window. +*`nID`*\ +The child window ID of the window. The ID can be `AFX_IDW_PANE_FIRST` unless the splitter window is nested inside another splitter window. ### Return Value @@ -202,17 +201,17 @@ Nonzero if successful; otherwise 0. ### Remarks -You can embed a `CSplitterWnd` in a parent [CFrameWnd](../../mfc/reference/cframewnd-class.md) or [CMDIChildWnd](../../mfc/reference/cmdichildwnd-class.md) object by taking the following steps: +You can embed a `CSplitterWnd` in a parent [`CFrameWnd`](../../mfc/reference/cframewnd-class.md) or [`CMDIChildWnd`](../../mfc/reference/cmdichildwnd-class.md) object by taking the following steps: 1. Embed a `CSplitterWnd` member variable in the parent frame. -1. Override the parent frame's [CFrameWnd::OnCreateClient](../../mfc/reference/cframewnd-class.md#oncreateclient) member function. +1. Override the parent frame's [`CFrameWnd::OnCreateClient`](../../mfc/reference/cframewnd-class.md#oncreateclient) member function. 1. Call the `Create` member function from within the overridden `OnCreateClient`. -When you create a splitter window from within a parent frame, pass the parent frame's *pContext* parameter to the splitter window. Otherwise, this parameter can be NULL. +When you create a splitter window from within a parent frame, pass the parent frame's *`pContext`* parameter to the splitter window. Otherwise, this parameter can be `NULL`. -The initial minimum row height and column width of a dynamic splitter window are set by the *sizeMin* parameter. These minimums, which determine whether a pane is too small to be shown in its entirety, can be changed with the [SetRowInfo](#setrowinfo) and [SetColumnInfo](#setcolumninfo) member functions. +The initial minimum row height and column width of a dynamic splitter window are set by the *`sizeMin`* parameter. These minimums, which determine whether a pane is too small to be shown in its entirety, can be changed with the [`SetRowInfo`](#setrowinfo) and [`SetColumnInfo`](#setcolumninfo) member functions. For more on dynamic splitter windows, see "Splitter Windows" in the article [Multiple Document Types, Views, and Frame Windows](../../mfc/multiple-document-types-views-and-frame-windows.md), [Technical Note 29](../../mfc/tn029-splitter-windows.md), and the `CSplitterWnd` class overview. @@ -220,7 +219,7 @@ For more on dynamic splitter windows, see "Splitter Windows" in the article [Mul [!code-cpp[NVC_MFCWindowing#125](../../mfc/reference/codesnippet/cpp/csplitterwnd-class_1.cpp)] -## CSplitterWnd::CreateScrollBarCtrl +## `CSplitterWnd::CreateScrollBarCtrl` Called by the framework to create a shared scroll bar control. @@ -232,11 +231,11 @@ virtual BOOL CreateScrollBarCtrl( ### Parameters -*dwStyle*
+*`dwStyle`*\ Specifies the window style. -*nID*
-The child window ID of the window. The ID can be AFX_IDW_PANE_FIRST unless the splitter window is nested inside another splitter window. +*`nID`*\ +The child window ID of the window. The ID can be `AFX_IDW_PANE_FIRST` unless the splitter window is nested inside another splitter window. ### Return Value @@ -246,7 +245,7 @@ Nonzero if successful; otherwise 0. Override `CreateScrollBarCtrl` to include extra controls next to a scroll bar. The default behavior is to create normal Windows scroll bar controls. -## CSplitterWnd::CreateStatic +## `CSplitterWnd::CreateStatic` To create a static splitter window, call the `CreateStatic` member function. @@ -261,20 +260,20 @@ virtual BOOL CreateStatic( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ The parent frame window of the splitter window. -*nRows*
+*`nRows`*\ The number of rows. This value must not exceed 16. -*nCols*
+*`nCols`*\ The number of columns. This value must not exceed 16. -*dwStyle*
+*`dwStyle`*\ Specifies the window style. -*nID*
-The child window ID of the window. The ID can be AFX_IDW_PANE_FIRST unless the splitter window is nested inside another splitter window. +*`nID`*\ +The child window ID of the window. The ID can be `AFX_IDW_PANE_FIRST` unless the splitter window is nested inside another splitter window. ### Return Value @@ -282,25 +281,25 @@ Nonzero if successful; otherwise 0. ### Remarks -A `CSplitterWnd` is usually embedded in a parent `CFrameWnd` or [CMDIChildWnd](../../mfc/reference/cmdichildwnd-class.md) object by taking the following steps: +A `CSplitterWnd` is usually embedded in a parent `CFrameWnd` or [`CMDIChildWnd`](../../mfc/reference/cmdichildwnd-class.md) object by taking the following steps: 1. Embed a `CSplitterWnd` member variable in the parent frame. 1. Override the parent frame's `OnCreateClient` member function. -1. Call the `CreateStatic` member function from within the overridden [CFrameWnd::OnCreateClient](../../mfc/reference/cframewnd-class.md#oncreateclient). +1. Call the `CreateStatic` member function from within the overridden [`CFrameWnd::OnCreateClient`](../../mfc/reference/cframewnd-class.md#oncreateclient). A static splitter window contains a fixed number of panes, often from different classes. -When you create a static splitter window, you must at the same time create all its panes. The [CreateView](#createview) member function is usually used for this purpose, but you can create other nonview classes as well. +When you create a static splitter window, you must at the same time create all its panes. The [`CreateView`](#createview) member function is usually used for this purpose, but you can create other nonview classes as well. -The initial minimum row height and column width for a static splitter window is 0. These minimums, which determine when a pane is too small to be shown in its entirety, can be changed with the [SetRowInfo](#setrowinfo) and [SetColumnInfo](#setcolumninfo) member functions. +The initial minimum row height and column width for a static splitter window is 0. These minimums, which determine when a pane is too small to be shown in its entirety, can be changed with the [`SetRowInfo`](#setrowinfo) and [`SetColumnInfo`](#setcolumninfo) member functions. -To add scroll bars to a static splitter window, add the WS_HSCROLL and WS_VSCROLL styles to *dwStyle*. +To add scroll bars to a static splitter window, add the `WS_HSCROLL` and `WS_VSCROLL` styles to *`dwStyle`*. See "Splitter Windows" in the article [Multiple Document Types, Views, and Frame Windows](../../mfc/multiple-document-types-views-and-frame-windows.md), [Technical Note 29](../../mfc/tn029-splitter-windows.md), and the `CSplitterWnd` class overview for more on static splitter windows. -## CSplitterWnd::CreateView +## `CSplitterWnd::CreateView` Creates the panes for a static splitter window. @@ -315,20 +314,20 @@ virtual BOOL CreateView( ### Parameters -*row*
+*`row`*\ Specifies the splitter window row in which to place the new view. -*col*
+*`col`*\ Specifies the splitter window column in which to place the new view. -*pViewClass*
-Specifies the [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) of the new view. +*`pViewClass`*\ +Specifies the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) of the new view. -*sizeInit*
+*`sizeInit`*\ Specifies the initial size of the new view. -*pContext*
-A pointer to a creation context used to create the view (usually the *pContext* passed into the parent frame's overridden [CFrameWnd::OnCreateClient](../../mfc/reference/cframewnd-class.md#oncreateclient) member function in which the splitter window is being created). +*`pContext`*\ +A pointer to a creation context used to create the view (usually the *`pContext`* passed into the parent frame's overridden [`CFrameWnd::OnCreateClient`](../../mfc/reference/cframewnd-class.md#oncreateclient) member function in which the splitter window is being created). ### Return Value @@ -344,7 +343,7 @@ The framework also calls this member function to create new panes when the user [!code-cpp[NVC_MFCWindowing#4](../../mfc/reference/codesnippet/cpp/csplitterwnd-class_2.cpp)] -## CSplitterWnd::CSplitterWnd +## `CSplitterWnd::CSplitterWnd` Call to construct a `CSplitterWnd` object. @@ -354,9 +353,9 @@ CSplitterWnd(); ### Remarks -Construct a `CSplitterWnd` object in two steps. First, call the constructor, which creates the `CSplitterWnd` object, and then call the [Create](#create) member function, which creates the splitter window and attaches it to the `CSplitterWnd` object. +Construct a `CSplitterWnd` object in two steps. First, call the constructor, which creates the `CSplitterWnd` object, and then call the [`Create`](#create) member function, which creates the splitter window and attaches it to the `CSplitterWnd` object. -## CSplitterWnd::DeleteColumn +## `CSplitterWnd::DeleteColumn` Deletes a column from the splitter window. @@ -366,14 +365,14 @@ virtual void DeleteColumn(int colDelete); ### Parameters -*colDelete*
+*`colDelete`*\ Specifies the column to be deleted. ### Remarks -This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the SPLS_DYNAMIC_SPLIT style). It can be customized, along with the virtual function [CreateView](#createview), to implement more advanced dynamic splitters. +This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the `SPLS_DYNAMIC_SPLIT` style). It can be customized, along with the virtual function [`CreateView`](#createview), to implement more advanced dynamic splitters. -## CSplitterWnd::DeleteRow +## `CSplitterWnd::DeleteRow` Deletes a row from the splitter window. @@ -383,14 +382,14 @@ virtual void DeleteRow(int rowDelete); ### Parameters -*rowDelete*
+*`rowDelete`*\ Specifies the row to be deleted. ### Remarks -This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the SPLS_DYNAMIC_SPLIT style). It can be customized, along with the virtual function [CreateView](#createview), to implement more advanced dynamic splitters. +This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the `SPLS_DYNAMIC_SPLIT` style). It can be customized, along with the virtual function [`CreateView`](#createview), to implement more advanced dynamic splitters. -## CSplitterWnd::DeleteView +## `CSplitterWnd::DeleteView` Deletes a view from the splitter window. @@ -402,19 +401,19 @@ virtual void DeleteView( ### Parameters -*row*
+*`row`*\ Specifies the splitter window row at which to delete the view. -*col*
+*`col`*\ Specifies the splitter window column at which to delete the view. ### Remarks -If the active view is being deleted, the next view will become active. The default implementation assumes the view will auto delete in [PostNcDestroy](../../mfc/reference/cwnd-class.md#postncdestroy). +If the active view is being deleted, the next view will become active. The default implementation assumes the view will auto delete in [`PostNcDestroy`](../../mfc/reference/cwnd-class.md#postncdestroy). -This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the SPLS_DYNAMIC_SPLIT style). It can be customized, along with the virtual function [CreateView](#createview), to implement more advanced dynamic splitters. +This member function is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the `SPLS_DYNAMIC_SPLIT` style). It can be customized, along with the virtual function [`CreateView`](#createview), to implement more advanced dynamic splitters. -## CSplitterWnd::DoKeyboardSplit +## `CSplitterWnd::DoKeyboardSplit` Performs the keyboard split command, usually "Window Split." @@ -428,9 +427,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function is a high level command that is used by the [CView](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. +This member function is a high level command that is used by the [`CView`](../../mfc/reference/cview-class.md) class to delegate to the `CSplitterWnd` implementation. -## CSplitterWnd::DoScroll +## `CSplitterWnd::DoScroll` Performs synchronized scrolling of split windows. @@ -443,26 +442,26 @@ virtual BOOL DoScroll( ### Parameters -*pViewFrom*
+*`pViewFrom`*\ A pointer to the view from which the scrolling message originates. -*nScrollCode*
+*`nScrollCode`*\ A scroll-bar code that indicates the user's scrolling request. This parameter is composed of two parts: a low-order byte, which determines the type of scrolling occurring horizontally, and a high-order byte, which determines the type of scrolling occurring vertically: -- SB_BOTTOM Scrolls to bottom. +- `SB_BOTTOM` Scrolls to bottom. -- SB_LINEDOWN Scrolls one line down. +- `SB_LINEDOWN` Scrolls one line down. -- SB_LINEUP Scrolls one line up. +- `SB_LINEUP` Scrolls one line up. -- SB_PAGEDOWN Scrolls one page down. +- `SB_PAGEDOWN` Scrolls one page down. -- SB_PAGEUP Scrolls one page up. +- `SB_PAGEUP` Scrolls one page up. -- SB_TOP Scrolls to top. +- `SB_TOP` Scrolls to top. -*bDoScroll*
-Determines whether the specified scrolling action occurs. If *bDoScroll* is TRUE (that is, if a child window exists, and if the split windows have a scroll range), then the specified scrolling action can take place; if *bDoScroll* is FALSE (that is, if no child window exists, or the split views have no scroll range), then scrolling does not occur. +*`bDoScroll`*\ +Determines whether the specified scrolling action occurs. If *`bDoScroll`* is `TRUE` (that is, if a child window exists, and if the split windows have a scroll range), then the specified scrolling action can take place; if *`bDoScroll`* is `FALSE` (that is, if no child window exists, or the split views have no scroll range), then scrolling doesn't occur. ### Return Value @@ -472,7 +471,7 @@ Nonzero if synchronized scrolling occurs; otherwise 0. This member function is called by the framework to perform synchronized scrolling of split windows when the view receives a scroll message. Override to require an action by the user before synchronized scrolling is allowed. -## CSplitterWnd::DoScrollBy +## `CSplitterWnd::DoScrollBy` Scrolls split windows by a given number of pixels. @@ -485,14 +484,14 @@ virtual BOOL DoScrollBy( ### Parameters -*pViewFrom*
+*`pViewFrom`*\ A pointer to the view from which the scrolling message originates. -*sizeScroll*
+*`sizeScroll`*\ Number of pixels to be scrolled horizontally and vertically. -*bDoScroll*
-Determines whether the specified scrolling action occurs. If *bDoScroll* is TRUE (that is, if a child window exists, and if the split windows have a scroll range), then the specified scrolling action can take place; if *bDoScroll* is FALSE (that is, if no child window exists, or the split views have no scroll range), then scrolling does not occur. +*`bDoScroll`*\ +Determines whether the specified scrolling action occurs. If *`bDoScroll`* is `TRUE` (that is, if a child window exists, and if the split windows have a scroll range), then the specified scrolling action can take place; if *`bDoScroll`* is `FALSE` (that is, if no child window exists, or the split views have no scroll range), then scrolling doesn't occur. ### Return Value @@ -500,11 +499,11 @@ Nonzero if synchronized scrolling occurs; otherwise 0. ### Remarks -This member function is called by the framework in response to a scroll message, to perform synchronized scrolling of the split windows by the amount, in pixels, indicated by *sizeScroll*. Positive values indicate scrolling down and to the right; negative values indicate scrolling up and to the left. +This member function is called by the framework in response to a scroll message, to perform synchronized scrolling of the split windows by the amount, in pixels, indicated by *`sizeScroll`*. Positive values indicate scrolling down and to the right; negative values indicate scrolling up and to the left. Override to require an action by the user before allowing scroll. -## CSplitterWnd::GetActivePane +## `CSplitterWnd::GetActivePane` Determines the active pane from the focus or active view in the frame. @@ -516,21 +515,21 @@ virtual CWnd* GetActivePane( ### Parameters -*pRow*
+*`pRow`*\ A pointer to an **`int`** to retrieve the row number of the active pane. -*pCol*
+*`pCol`*\ A pointer to an **`int`** to retrieve the column number of the active pane. ### Return Value -Pointer to the active pane. NULL if no active pane exists. +Pointer to the active pane. `NULL` if no active pane exists. ### Remarks This member function is called by the framework to determine the active pane in a splitter window. Override to require an action by the user before getting the active pane. -## CSplitterWnd::GetColumnCount +## `CSplitterWnd::GetColumnCount` Returns the current pane column count. @@ -542,7 +541,7 @@ int GetColumnCount() const; Returns the current number of columns in the splitter. For a static splitter, this will also be the maximum number of columns. -## CSplitterWnd::GetColumnInfo +## `CSplitterWnd::GetColumnInfo` Returns information on the specified column. @@ -555,16 +554,16 @@ void GetColumnInfo( ### Parameters -*col*
+*`col`*\ Specifies a column. -*cxCur*
+*`cxCur`*\ A reference to an **`int`** to be set to the current width of the column. -*cxMin*
+*`cxMin`*\ A reference to an **`int`** to be set to the current minimum width of the column. -## CSplitterWnd::GetPane +## `CSplitterWnd::GetPane` Returns the pane at the specified row and column. @@ -576,17 +575,17 @@ CWnd* GetPane( ### Parameters -*row*
+*`row`*\ Specifies a row. -*col*
+*`col`*\ Specifies a column. ### Return Value -Returns the pane at the specified row and column. The returned pane is usually a [CView](../../mfc/reference/cview-class.md)-derived class. +Returns the pane at the specified row and column. The returned pane is usually a [`CView`](../../mfc/reference/cview-class.md)-derived class. -## CSplitterWnd::GetRowCount +## `CSplitterWnd::GetRowCount` Returns the current pane row count. @@ -598,7 +597,7 @@ int GetRowCount() const; Returns the current number of rows in the splitter window. For a static splitter window, this will also be the maximum number of rows. -## CSplitterWnd::GetRowInfo +## `CSplitterWnd::GetRowInfo` Returns information on the specified row. @@ -611,20 +610,20 @@ void GetRowInfo( ### Parameters -*row*
+*`row`*\ Specifies a row. -*cyCur*
+*`cyCur`*\ Reference to **`int`** to be set to the current height of the row in pixels. -*cyMin*
+*`cyMin`*\ Reference to **`int`** to be set to the current minimum height of the row in pixels. ### Remarks -Call this member function to obtain information about the specified row. The *cyCur* parameter is filled with the current height of the specified row, and *cyMin* is filled with the minimum height of the row. +Call this member function to obtain information about the specified row. The *`cyCur`* parameter is filled with the current height of the specified row, and *`cyMin`* is filled with the minimum height of the row. -## CSplitterWnd::GetScrollStyle +## `CSplitterWnd::GetScrollStyle` Returns the shared scroll-bar style for the splitter window. @@ -636,13 +635,13 @@ DWORD GetScrollStyle() const; One or more of the following windows style flags, if successful: -- WS_HSCROLL If the splitter currently manages shared horizontal scroll bars. +- `WS_HSCROLL` If the splitter currently manages shared horizontal scroll bars. -- WS_VSCROLL If the splitter currently manages shared vertical scroll bars. +- `WS_VSCROLL` If the splitter currently manages shared vertical scroll bars. -If zero, the splitter window does not currently manage any shared scroll bars. +If zero, the splitter window doesn't currently manage any shared scroll bars. -## CSplitterWnd::IdFromRowCol +## `CSplitterWnd::IdFromRowCol` Obtains the child window ID for the pane at the specified row and column. @@ -654,10 +653,10 @@ int IdFromRowCol( ### Parameters -*row*
+*`row`*\ Specifies the splitter window row. -*col*
+*`col`*\ Specifies the splitter window column. ### Return Value @@ -672,9 +671,9 @@ This member function is used for creating nonviews as panes and may be called be [!code-cpp[NVC_MFCWindowing#5](../../mfc/reference/codesnippet/cpp/csplitterwnd-class_3.cpp)] -## CSplitterWnd::IsChildPane +## `CSplitterWnd::IsChildPane` -Determines whether *pWnd* is currently a child pane of this splitter window. +Determines whether *`pWnd`* is currently a child pane of this splitter window. ``` BOOL IsChildPane( @@ -685,18 +684,18 @@ BOOL IsChildPane( ### Parameters -*pWnd*
-A pointer to a [CWnd](../../mfc/reference/cwnd-class.md) object to be tested. +*`pWnd`*\ +A pointer to a [`CWnd`](../../mfc/reference/cwnd-class.md) object to be tested. -*pRow*
+*`pRow`*\ A pointer to an **`int`** in which to store row number. -*pCol*
+*`pCol`*\ A pointer to an **`int`** in which to store a column number. ### Return Value -If nonzero, *pWnd* is currently a child pane of this splitter window, and *pRow* and *pCol* are filled in with the position of the pane in the splitter window. If *pWnd* is not a child pane of this splitter window, 0 is returned. +If nonzero, *`pWnd`* is currently a child pane of this splitter window, and *`pRow`* and *`pCol`* are filled in with the position of the pane in the splitter window. If *`pWnd`* isn't a child pane of this splitter window, 0 is returned. ### Remarks @@ -704,9 +703,9 @@ In Visual C++ versions prior to 6.0, this function was defined as `BOOL IsChildPane(CWnd* pWnd, int& row, int& col);` -This version is now obsolete and should not be used. +This version is now obsolete and shouldn't be used. -## CSplitterWnd::IsTracking +## `CSplitterWnd::IsTracking` Call this member function to determine if the splitter bar in the window is currently being moved. @@ -718,7 +717,7 @@ BOOL IsTracking(); Nonzero if a splitter operation is in progress; otherwise 0. -## CSplitterWnd::OnDrawSplitter +## `CSplitterWnd::OnDrawSplitter` Renders an image of a split window. @@ -731,22 +730,22 @@ virtual void OnDrawSplitter( ### Parameters -*pDC*
-A pointer to the device context in which to draw. If *pDC* is NULL, then [CWnd::RedrawWindow](../../mfc/reference/cwnd-class.md#redrawwindow) is called by the framework and no split window is drawn. +*`pDC`*\ +A pointer to the device context in which to draw. If *`pDC`* is `NULL`, then [`CWnd::RedrawWindow`](../../mfc/reference/cwnd-class.md#redrawwindow) is called by the framework and no split window is drawn. -*nType*
+*`nType`*\ A value of the `enum ESplitType`, which can be one of the following: - `splitBox` The splitter drag box. - `splitBar` The bar that appears between the two split windows. -- `splitIntersection` The intersection of the split windows. This element will not be called when running on Windows 95/98. +- `splitIntersection` The intersection of the split windows. This element won't be called when running on Windows 95/98. - `splitBorder` The split window borders. -*rect*
-A reference to a [CRect](../../atl-mfc-shared/reference/crect-class.md) object specifying the size and shape of the split windows. +*`rect`*\ +A reference to a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object specifying the size and shape of the split windows. ### Remarks @@ -754,7 +753,7 @@ This member function is called by the framework to draw and specify the exact ch For more on dynamic splitter windows, see "Splitter Windows" in the article [Multiple Document Types, Views, and Frame Windows](../../mfc/multiple-document-types-views-and-frame-windows.md), [Technical Note 29](../../mfc/tn029-splitter-windows.md), and the `CSplitterWnd` class overview. -## CSplitterWnd::OnInvertTracker +## `CSplitterWnd::OnInvertTracker` Renders the image of a split window to be the same size and shape as the frame window. @@ -764,7 +763,7 @@ virtual void OnInvertTracker(const CRect& rect); ### Parameters -*rect*
+*`rect`*\ Reference to a `CRect` object specifying the tracking rectangle. ### Remarks @@ -773,7 +772,7 @@ This member function is called by the framework during resizing of splitters. Ov For more on dynamic splitter windows, see "Splitter Windows" in the article [Multiple Document Types, Views, and Frame Windows](../../mfc/multiple-document-types-views-and-frame-windows.md), [Technical Note 29](../../mfc/tn029-splitter-windows.md), and the `CSplitterWnd` class overview. -## CSplitterWnd::RecalcLayout +## `CSplitterWnd::RecalcLayout` Call to redisplay the splitter window after adjusting row or column size. @@ -783,15 +782,15 @@ virtual void RecalcLayout(); ### Remarks -Call this member function to correctly redisplay the splitter window after you have adjusted row and column sizes with the [SetRowInfo](#setrowinfo) and [SetColumnInfo](#setcolumninfo) member functions. If you change row and column sizes as part of the creation process before the splitter window is visible, it is not necessary to call this member function. +Call this member function to correctly redisplay the splitter window after you have adjusted row and column sizes with the [`SetRowInfo`](#setrowinfo) and [`SetColumnInfo`](#setcolumninfo) member functions. If you change row and column sizes as part of the creation process before the splitter window is visible, it isn't necessary to call this member function. The framework calls this member function whenever the user resizes the splitter window or moves a split. ### Example - See the example for [CSplitterWnd::SetColumnInfo](#setcolumninfo). + See the example for [`CSplitterWnd::SetColumnInfo`](#setcolumninfo). -## CSplitterWnd::SetActivePane +## `CSplitterWnd::SetActivePane` Sets a pane to be the active one in the frame. @@ -804,22 +803,22 @@ virtual void SetActivePane( ### Parameters -*row*
-If *pWnd* is NULL, specifies the row in the pane that will be active. +*`row`*\ +If *`pWnd`* is `NULL`, specifies the row in the pane that will be active. -*col*
-If *pWnd* is NULL, specifies the column in the pane that will be active. +*`col`*\ +If *`pWnd`* is `NULL`, specifies the column in the pane that will be active. -*pWnd*
-A pointer to a `CWnd` object. If NULL, the pane specified by *row* and *col* is set active. If not NULL, specifies the pane that is set active. +*`pWnd`*\ +A pointer to a `CWnd` object. If `NULL`, the pane specified by *`row`* and *`col`* is set active. If not `NULL`, specifies the pane that is set active. ### Remarks This member function is called by the framework to set a pane as active when the user changes the focus to a pane within the frame window. You can explicitly call `SetActivePane` to change the focus to the specified view. -Specify pane by providing either row and column, **or** by providing *pWnd*. +Specify pane by providing either row and column, **or** by providing *`pWnd`*. -## CSplitterWnd::SetColumnInfo +## `CSplitterWnd::SetColumnInfo` Call to set the specified column information. @@ -832,13 +831,13 @@ void SetColumnInfo( ### Parameters -*col*
+*`col`*\ Specifies a splitter window column. -*cxIdeal*
+*`cxIdeal`*\ Specifies an ideal width for the splitter window column in pixels. -*cxMin*
+*`cxMin`*\ Specifies a minimum width for the splitter window column in pixels. ### Remarks @@ -851,7 +850,7 @@ When the framework displays the splitter window, it lays out the panes in column [!code-cpp[NVC_MFCWindowing#6](../../mfc/reference/codesnippet/cpp/csplitterwnd-class_4.cpp)] -## CSplitterWnd::SetRowInfo +## `CSplitterWnd::SetRowInfo` Call to set the specified row information. @@ -864,13 +863,13 @@ void SetRowInfo( ### Parameters -*row*
+*`row`*\ Specifies a splitter window row. -*cyIdeal*
+*`cyIdeal`*\ Specifies an ideal height for the splitter window row in pixels. -*cyMin*
+*`cyMin`*\ Specifies a minimum height for the splitter window row in pixels. ### Remarks @@ -879,7 +878,7 @@ Call this member function to set a new minimum height and ideal height for a row When the framework displays the splitter window, it lays out the panes in columns and rows according to their ideal dimensions, working from the upper-left to the lower-right corner of the splitter window's client area. -## CSplitterWnd::SetScrollStyle +## `CSplitterWnd::SetScrollStyle` Specifies the new scroll style for the splitter window's shared scroll-bar support. @@ -889,18 +888,18 @@ void SetScrollStyle(DWORD dwStyle); ### Parameters -*dwStyle*
+*`dwStyle`*\ The new scroll style for the splitter window's shared scroll-bar support, which can be one of the following values: -- WS_HSCROLL Create/show horizontal shared scroll bars. +- `WS_HSCROLL` Create/show horizontal shared scroll bars. -- WS_VSCROLL Create/show vertical shared scroll bars. +- `WS_VSCROLL` Create/show vertical shared scroll bars. ### Remarks -Once a scroll bar is created it will not be destroyed even if `SetScrollStyle` is called without that style; instead those scroll bars are hidden. This allows the scroll bars to retain their state even though they are hidden. After calling `SetScrollStyle` it is necessary to call [RecalcLayout](#recalclayout) for all the changes to take effect. +Once a scroll bar is created, it will not be destroyed even if `SetScrollStyle` is called without that style; instead those scroll bars are hidden. This allows the scroll bars to retain their state even though they're hidden. After calling `SetScrollStyle`, it's necessary to call [`RecalcLayout`](#recalclayout) for all the changes to take effect. -## CSplitterWnd::SplitColumn +## `CSplitterWnd::SplitColumn` Indicates where a frame window splits vertically. @@ -910,7 +909,7 @@ virtual BOOL SplitColumn(int cxBefore); ### Parameters -*cxBefore*
+*`cxBefore`*\ The position, in pixels, before which the split occurs. ### Return Value @@ -921,9 +920,9 @@ Nonzero if successful; otherwise 0. This member function is called when a vertical splitter window is created. `SplitColumn` indicates the default location where the split occurs. -`SplitColumn` is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the SPLS_DYNAMIC_SPLIT style). It can be customized, along with the virtual function [CreateView](#createview), to implement more advanced dynamic splitters. +`SplitColumn` is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the `SPLS_DYNAMIC_SPLIT` style). It can be customized, along with the virtual function [`CreateView`](#createview), to implement more advanced dynamic splitters. -## CSplitterWnd::SplitRow +## `CSplitterWnd::SplitRow` Indicates where a frame window splits horizontally. @@ -933,7 +932,7 @@ virtual BOOL SplitRow(int cyBefore); ### Parameters -*cyBefore*
+*`cyBefore`*\ The position, in pixels, before which the split occurs. ### Return Value @@ -944,9 +943,9 @@ Nonzero if successful; otherwise 0. This member function is called when a horizontal splitter window is created. `SplitRow` indicates the default location where the split occurs. -`SplitRow` is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the SPLS_DYNAMIC_SPLIT style). It can be customized, along with the virtual function [CreateView](#createview), to implement more advanced dynamic splitters. +`SplitRow` is called by the framework to implement the logic of the dynamic splitter window (that is, if the splitter window has the `SPLS_DYNAMIC_SPLIT` style). It can be customized, along with the virtual function [`CreateView`](#createview), to implement more advanced dynamic splitters. -## CSplitterWnd::OnDraw +## `CSplitterWnd::OnDraw` Called by the framework to draw the splitter window. @@ -956,15 +955,14 @@ virtual void OnDraw(CDC* pDC); ### Parameters -*pDC*
+*`pDC`*\ A pointer to a device context. ### Remarks ## See also -[MFC Sample VIEWEX](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CView Class](../../mfc/reference/cview-class.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md) +[MFC Sample `VIEWEX`](../../overview/visual-cpp-samples.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CView` Class](../../mfc/reference/cview-class.md) diff --git a/docs/mfc/reference/cstatusbar-class.md b/docs/mfc/reference/cstatusbar-class.md index 3a7b614c75..ff4116ac64 100644 --- a/docs/mfc/reference/cstatusbar-class.md +++ b/docs/mfc/reference/cstatusbar-class.md @@ -462,9 +462,9 @@ After you call `SetPaneText`, you must add a UI update handler to display the ne ### Example [!code-cpp[NVC_MFCDocView#176](../../mfc/codesnippet/cpp/cstatusbar-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocView#177](../../mfc/codesnippet/cpp/cstatusbar-class_2.cpp)] - +  [!code-cpp[NVC_MFCDocView#178](../../mfc/codesnippet/cpp/cstatusbar-class_3.cpp)] ## See also diff --git a/docs/mfc/reference/cstdiofile-class.md b/docs/mfc/reference/cstdiofile-class.md index d8d19f0816..fd2ff46ab5 100644 --- a/docs/mfc/reference/cstdiofile-class.md +++ b/docs/mfc/reference/cstdiofile-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CStdioFile Class" title: "CStdioFile Class" -ms.date: "08/29/2019" +description: "Learn more about: CStdioFile Class" +ms.date: 08/29/2019 f1_keywords: ["CStdioFile", "AFX/CStdioFile", "AFX/CStdioFile::CStdioFile", "AFX/CStdioFile::Open", "AFX/CStdioFile::ReadString", "AFX/CStdioFile::Seek", "AFX/CStdioFile::WriteString", "AFX/CStdioFile::m_pStream"] helpviewer_keywords: ["CStdioFile [MFC], CStdioFile", "CStdioFile [MFC], Open", "CStdioFile [MFC], ReadString", "CStdioFile [MFC], Seek", "CStdioFile [MFC], WriteString", "CStdioFile [MFC], m_pStream"] -ms.assetid: 88c2274c-4f0e-4327-882a-557ba4b3ae15 --- # `CStdioFile` Class @@ -149,7 +148,7 @@ virtual BOOL Open( A string that is the path to the desired file. The path can be relative or absolute. *`nOpenFlags`*
-Sharing and access mode. Specifies the action to take when opening the file. You can combine options by using the bitwise-OR (|) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional. +Sharing and access mode. Specifies the action to take when opening the file. You can combine options by using the bitwise-OR (**`|`**) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional. *`pError`*
A pointer to an existing file-exception object that will receive the status of a failed operation. @@ -181,7 +180,7 @@ virtual BOOL ReadString(CString& rString); Specifies a pointer to a user-supplied buffer that will receive a null-terminated text string. *`nMax`*
-Specifies the maximum number of characters to read, not counting the terminating null character. +Specifies the maximum number of characters to write into the *`lpsz`* buffer, including the terminating null. *`rString`*
A reference to a `CString` object that will contain the string when the function returns. @@ -260,7 +259,7 @@ Specifies a pointer to a buffer that contains a null-terminated string. ### Remarks -The terminating null character ( `\0`) is not written to the file. This method writes newline characters in *`lpsz`* to the file as a carriage return-line feed pair. +The terminating null character (`\0`) is not written to the file. This method writes newline characters in *`lpsz`* to the file as a carriage return-line feed pair. If you want to write data that is not null-terminated to a file, use `CStdioFile::Write` or [`CFile::Write`](../../mfc/reference/cfile-class.md#write). diff --git a/docs/mfc/reference/cstringarray-class.md b/docs/mfc/reference/cstringarray-class.md index 34af72a6b3..f8d656bcbb 100644 --- a/docs/mfc/reference/cstringarray-class.md +++ b/docs/mfc/reference/cstringarray-class.md @@ -4,7 +4,6 @@ title: "CStringArray Class" ms.date: "11/04/2016" f1_keywords: ["CStringArray", "AFXCOLL/CStringArray", "AFXCOLL/CStringArray::CStringArray", "AFXCOLL/CStringArray::Add", "AFXCOLL/CStringArray::Append", "AFXCOLL/CStringArray::Copy", "AFXCOLL/CStringArray::ElementAt", "AFXCOLL/CStringArray::FreeExtra", "AFXCOLL/CStringArray::GetAt", "AFXCOLL/CStringArray::GetCount", "AFXCOLL/CStringArray::GetData", "AFXCOLL/CStringArray::GetSize", "AFXCOLL/CStringArray::GetUpperBound", "AFXCOLL/CStringArray::InsertAt", "AFXCOLL/CStringArray::IsEmpty", "AFXCOLL/CStringArray::RemoveAll", "AFXCOLL/CStringArray::RemoveAt", "AFXCOLL/CStringArray::SetAt", "AFXCOLL/CStringArray::SetAtGrow", "AFXCOLL/CStringArray::SetSize"] helpviewer_keywords: ["CStringArray [MFC], CStringArray", "CStringArray [MFC], Add", "CStringArray [MFC], Append", "CStringArray [MFC], Copy", "CStringArray [MFC], ElementAt", "CStringArray [MFC], FreeExtra", "CStringArray [MFC], GetAt", "CStringArray [MFC], GetCount", "CStringArray [MFC], GetData", "CStringArray [MFC], GetSize", "CStringArray [MFC], GetUpperBound", "CStringArray [MFC], InsertAt", "CStringArray [MFC], IsEmpty", "CStringArray [MFC], RemoveAll", "CStringArray [MFC], RemoveAt", "CStringArray [MFC], SetAt", "CStringArray [MFC], SetAtGrow", "CStringArray [MFC], SetSize"] -ms.assetid: 6c637e06-bba8-4c08-b0fc-cf8cb067ce34 --- # `CStringArray` Class @@ -12,7 +11,7 @@ Supports arrays of [`CString`](../../atl-mfc-shared/using-cstring.md) objects. ## Syntax -``` +```cpp class CStringArray : public CObject ``` @@ -24,7 +23,7 @@ The member functions of `CStringArray` are similar to the member functions of cl for example, translates to -`CString CStringArray::GetAt( int ) const;` +`const CString& CStringArray::GetAt( int ) const;` and diff --git a/docs/mfc/reference/cstringlist-class.md b/docs/mfc/reference/cstringlist-class.md index 2271be4c0e..06dfe5f2c0 100644 --- a/docs/mfc/reference/cstringlist-class.md +++ b/docs/mfc/reference/cstringlist-class.md @@ -4,9 +4,8 @@ title: "CStringList Class" ms.date: "11/04/2016" f1_keywords: ["CStringList", "AFXCOLL/CStringList", "AFXCOLL/CStringList::CStringList", "AFXCOLL/CStringList::AddHead", "AFXCOLL/CStringList::AddTail", "AFXCOLL/CStringList::Find", "AFXCOLL/CStringList::FindIndex", "AFXCOLL/CStringList::GetAt", "AFXCOLL/CStringList::GetCount", "AFXCOLL/CStringList::GetHead", "AFXCOLL/CStringList::GetHeadPosition", "AFXCOLL/CStringList::GetNext", "AFXCOLL/CStringList::GetPrev", "AFXCOLL/CStringList::GetSize", "AFXCOLL/CStringList::GetTail", "AFXCOLL/CStringList::GetTailPosition", "AFXCOLL/CStringList::InsertAfter", "AFXCOLL/CStringList::InsertBefore", "AFXCOLL/CStringList::IsEmpty", "AFXCOLL/CStringList::RemoveAll", "AFXCOLL/CStringList::RemoveAt", "AFXCOLL/CStringList::RemoveHead", "AFXCOLL/CStringList::RemoveTail", "AFXCOLL/CStringList::SetAt"] helpviewer_keywords: ["CStringList [MFC], CStringList", "CStringList [MFC], AddHead", "CStringList [MFC], AddTail", "CStringList [MFC], Find", "CStringList [MFC], FindIndex", "CStringList [MFC], GetAt", "CStringList [MFC], GetCount", "CStringList [MFC], GetHead", "CStringList [MFC], GetHeadPosition", "CStringList [MFC], GetNext", "CStringList [MFC], GetPrev", "CStringList [MFC], GetSize", "CStringList [MFC], GetTail", "CStringList [MFC], GetTailPosition", "CStringList [MFC], InsertAfter", "CStringList [MFC], InsertBefore", "CStringList [MFC], IsEmpty", "CStringList [MFC], RemoveAll", "CStringList [MFC], RemoveAt", "CStringList [MFC], RemoveHead", "CStringList [MFC], RemoveTail", "CStringList [MFC], SetAt"] -ms.assetid: 310a7edb-263c-4bd2-ac43-0bfbfddc5a33 --- -# CStringList Class +# `CStringList` Class Supports lists of `CString` objects. @@ -18,7 +17,7 @@ class CStringList : public CObject ## Members -The member functions of `CStringList` are similar to the member functions of class [CObList](../../mfc/reference/coblist-class.md). Because of this similarity, you can use the `CObList` reference documentation for member function specifics. Wherever you see a `CObject` pointer as a return value, substitute a `CString` (not a `CString` pointer). Wherever you see a `CObject` pointer as a function parameter, substitute an `LPCTSTR`. +The member functions of `CStringList` are similar to the member functions of class [`CObList`](../../mfc/reference/coblist-class.md). Because of this similarity, you can use the `CObList` reference documentation for member function specifics. Wherever you see a `CObject` pointer as a return value, substitute a `CString` (not a `CString` pointer). Wherever you see a `CObject` pointer as a function parameter, substitute an `LPCTSTR`. `CObject*& CObList::GetHead() const;` @@ -38,39 +37,39 @@ translates to |Name|Description| |----------|-----------------| -|[CStringList::CStringList](../../mfc/reference/coblist-class.md#coblist)|Constructs an empty list.| +|[`CStringList::CStringList`](../../mfc/reference/coblist-class.md#coblist)|Constructs an empty list.| ### Public Methods |Name|Description| |----------|-----------------| -|[CStringList::AddHead](../../mfc/reference/coblist-class.md#addhead)|Adds an element (or all the elements in another list) to the head of the list (makes a new head).| -|[CStringList::AddTail](../../mfc/reference/coblist-class.md#addtail)|Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).| -|[CStringList::Find](../../mfc/reference/coblist-class.md#find)|Gets the position of an element specified by pointer value.| -|[CStringList::FindIndex](../../mfc/reference/coblist-class.md#findindex)|Gets the position of an element specified by a zero-based index.| -|[CStringList::GetAt](../../mfc/reference/coblist-class.md#getat)|Gets the element at a given position.| -|[CStringList::GetCount](../../mfc/reference/coblist-class.md#getcount)|Returns the number of elements in this list.| -|[CStringList::GetHead](../../mfc/reference/coblist-class.md#gethead)|Returns the head element of the list (cannot be empty).| -|[CStringList::GetHeadPosition](../../mfc/reference/coblist-class.md#getheadposition)|Returns the position of the head element of the list.| -|[CStringList::GetNext](../../mfc/reference/coblist-class.md#getnext)|Gets the next element for iterating.| -|[CStringList::GetPrev](../../mfc/reference/coblist-class.md#getprev)|Gets the previous element for iterating.| -|[CStringList::GetSize](../../mfc/reference/coblist-class.md#getsize)|Returns the number of elements in this list.| -|[CStringList::GetTail](../../mfc/reference/coblist-class.md#gettail)|Returns the tail element of the list (cannot be empty).| -|[CStringList::GetTailPosition](../../mfc/reference/coblist-class.md#gettailposition)|Returns the position of the tail element of the list.| -|[CStringList::InsertAfter](../../mfc/reference/coblist-class.md#insertafter)|Inserts a new element after a given position.| -|[CStringList::InsertBefore](../../mfc/reference/coblist-class.md#insertbefore)|Inserts a new element before a given position.| -|[CStringList::IsEmpty](../../mfc/reference/coblist-class.md#isempty)|Tests for the empty list condition (no elements).| -|[CStringList::RemoveAll](../../mfc/reference/coblist-class.md#removeall)|Removes all the elements from this list.| -|[CStringList::RemoveAt](../../mfc/reference/coblist-class.md#removeat)|Removes an element from this list, specified by position.| -|[CStringList::RemoveHead](../../mfc/reference/coblist-class.md#removehead)|Removes the element from the head of the list.| -|[CStringList::RemoveTail](../../mfc/reference/coblist-class.md#removetail)|Removes the element from the tail of the list.| -|[CStringList::SetAt](../../mfc/reference/coblist-class.md#setat)|Sets the element at a given position.| +|[`CStringList::AddHead`](../../mfc/reference/coblist-class.md#addhead)|Adds an element (or all the elements in another list) to the head of the list (makes a new head).| +|[`CStringList::AddTail`](../../mfc/reference/coblist-class.md#addtail)|Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).| +|[`CStringList::Find`](../../mfc/reference/coblist-class.md#find)|Gets the position of an element specified by pointer value.| +|[`CStringList::FindIndex`](../../mfc/reference/coblist-class.md#findindex)|Gets the position of an element specified by a zero-based index.| +|[`CStringList::GetAt`](../../mfc/reference/coblist-class.md#getat)|Gets the element at a given position.| +|[`CStringList::GetCount`](../../mfc/reference/coblist-class.md#getcount)|Returns the number of elements in this list.| +|[`CStringList::GetHead`](../../mfc/reference/coblist-class.md#gethead)|Returns the head element of the list (can't be empty).| +|[`CStringList::GetHeadPosition`](../../mfc/reference/coblist-class.md#getheadposition)|Returns the position of the head element of the list.| +|[`CStringList::GetNext`](../../mfc/reference/coblist-class.md#getnext)|Gets the next element for iterating.| +|[`CStringList::GetPrev`](../../mfc/reference/coblist-class.md#getprev)|Gets the previous element for iterating.| +|[`CStringList::GetSize`](../../mfc/reference/coblist-class.md#getsize)|Returns the number of elements in this list.| +|[`CStringList::GetTail`](../../mfc/reference/coblist-class.md#gettail)|Returns the tail element of the list (can't be empty).| +|[`CStringList::GetTailPosition`](../../mfc/reference/coblist-class.md#gettailposition)|Returns the position of the tail element of the list.| +|[`CStringList::InsertAfter`](../../mfc/reference/coblist-class.md#insertafter)|Inserts a new element after a given position.| +|[`CStringList::InsertBefore`](../../mfc/reference/coblist-class.md#insertbefore)|Inserts a new element before a given position.| +|[`CStringList::IsEmpty`](../../mfc/reference/coblist-class.md#isempty)|Tests for the empty list condition (no elements).| +|[`CStringList::RemoveAll`](../../mfc/reference/coblist-class.md#removeall)|Removes all the elements from this list.| +|[`CStringList::RemoveAt`](../../mfc/reference/coblist-class.md#removeat)|Removes an element from this list, specified by position.| +|[`CStringList::RemoveHead`](../../mfc/reference/coblist-class.md#removehead)|Removes the element from the head of the list.| +|[`CStringList::RemoveTail`](../../mfc/reference/coblist-class.md#removetail)|Removes the element from the tail of the list.| +|[`CStringList::SetAt`](../../mfc/reference/coblist-class.md#setat)|Sets the element at a given position.| ## Remarks All comparisons are done by value, meaning that the characters in the string are compared instead of the addresses of the strings. -`CStringList` incorporates the IMPLEMENT_SERIAL macro to support serialization and dumping of its elements. If a list of `CString` objects is stored to an archive, either with an overloaded insertion operator or with the `Serialize` member function, each `CString` element is serialized in turn. +`CStringList` incorporates the `IMPLEMENT_SERIAL` macro to support serialization and dumping of its elements. If a list of `CString` objects is stored to an archive, either with an overloaded insertion operator or with the `Serialize` member function, each `CString` element is serialized in turn. If you need a dump of individual `CString` elements, you must set the depth of the dump context to 1 or greater. @@ -78,16 +77,16 @@ For more information on using `CStringList`, see the article [Collections](../.. ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) `CStringList` ## Requirements -**Header:** afxcoll.h +**Header:** `afxcoll.h` ## See also -[MFC Sample COLLECT](../../overview/visual-cpp-samples.md)
-[CObject Class](../../mfc/reference/cobject-class.md)
+[MFC Sample `COLLECT`](../../overview/visual-cpp-samples.md)\ +[`CObject` Class](../../mfc/reference/cobject-class.md)\ [Hierarchy Chart](../../mfc/hierarchy-chart.md) diff --git a/docs/mfc/reference/ctabctrl-class.md b/docs/mfc/reference/ctabctrl-class.md index 8416886a1d..dc43226fbd 100644 --- a/docs/mfc/reference/ctabctrl-class.md +++ b/docs/mfc/reference/ctabctrl-class.md @@ -1,7 +1,7 @@ --- title: "CTabCtrl Class" description: "Learn more about: CTabCtrl Class" -ms.date: "1/29/2021" +ms.date: 1/29/2021 f1_keywords: ["CTabCtrl", "AFXCMN/CTabCtrl", "AFXCMN/CTabCtrl::CTabCtrl", "AFXCMN/CTabCtrl::AdjustRect", "AFXCMN/CTabCtrl::Create", "AFXCMN/CTabCtrl::CreateEx", "AFXCMN/CTabCtrl::DeleteAllItems", "AFXCMN/CTabCtrl::DeleteItem", "AFXCMN/CTabCtrl::DeselectAll", "AFXCMN/CTabCtrl::DrawItem", "AFXCMN/CTabCtrl::GetCurFocus", "AFXCMN/CTabCtrl::GetCurSel", "AFXCMN/CTabCtrl::GetExtendedStyle", "AFXCMN/CTabCtrl::GetImageList", "AFXCMN/CTabCtrl::GetItem", "AFXCMN/CTabCtrl::GetItemCount", "AFXCMN/CTabCtrl::GetItemRect", "AFXCMN/CTabCtrl::GetItemState", "AFXCMN/CTabCtrl::GetRowCount", "AFXCMN/CTabCtrl::GetToolTips", "AFXCMN/CTabCtrl::HighlightItem", "AFXCMN/CTabCtrl::HitTest", "AFXCMN/CTabCtrl::InsertItem", "AFXCMN/CTabCtrl::RemoveImage", "AFXCMN/CTabCtrl::SetCurFocus", "AFXCMN/CTabCtrl::SetCurSel", "AFXCMN/CTabCtrl::SetExtendedStyle", "AFXCMN/CTabCtrl::SetImageList", "AFXCMN/CTabCtrl::SetItem", "AFXCMN/CTabCtrl::SetItemExtra", "AFXCMN/CTabCtrl::SetItemSize", "AFXCMN/CTabCtrl::SetItemState", "AFXCMN/CTabCtrl::SetMinTabWidth", "AFXCMN/CTabCtrl::SetPadding", "AFXCMN/CTabCtrl::SetToolTips"] helpviewer_keywords: ["CTabCtrl [MFC], CTabCtrl", "CTabCtrl [MFC], AdjustRect", "CTabCtrl [MFC], Create", "CTabCtrl [MFC], CreateEx", "CTabCtrl [MFC], DeleteAllItems", "CTabCtrl [MFC], DeleteItem", "CTabCtrl [MFC], DeselectAll", "CTabCtrl [MFC], DrawItem", "CTabCtrl [MFC], GetCurFocus", "CTabCtrl [MFC], GetCurSel", "CTabCtrl [MFC], GetExtendedStyle", "CTabCtrl [MFC], GetImageList", "CTabCtrl [MFC], GetItem", "CTabCtrl [MFC], GetItemCount", "CTabCtrl [MFC], GetItemRect", "CTabCtrl [MFC], GetItemState", "CTabCtrl [MFC], GetRowCount", "CTabCtrl [MFC], GetToolTips", "CTabCtrl [MFC], HighlightItem", "CTabCtrl [MFC], HitTest", "CTabCtrl [MFC], InsertItem", "CTabCtrl [MFC], RemoveImage", "CTabCtrl [MFC], SetCurFocus", "CTabCtrl [MFC], SetCurSel", "CTabCtrl [MFC], SetExtendedStyle", "CTabCtrl [MFC], SetImageList", "CTabCtrl [MFC], SetItem", "CTabCtrl [MFC], SetItemExtra", "CTabCtrl [MFC], SetItemSize", "CTabCtrl [MFC], SetItemState", "CTabCtrl [MFC], SetMinTabWidth", "CTabCtrl [MFC], SetPadding", "CTabCtrl [MFC], SetToolTips"] --- @@ -366,7 +366,7 @@ Index into the tab control's image list, or -1 if there is no image for the tab. - `lParam` - Application-defined data associated with the tab. If there are more than 4 bytes of application-defined data per tab, an application must define a structure and use it instead of the `TCITEM` structure. The first member of the application-defined structure must be a [`TCITEMHEADER`](/windows/win32/api/commctrl/ns-commctrl-tcitemheaderw)structure. The `TCITEMHEADER` structure is identical to the `TCITEM` structure, but without the `lParam` member. The difference between the size of your structure and the size of the `TCITEMHEADER` structure should equal the number of extra bytes per tab. + Application-defined data associated with the tab. If there are more than 4 bytes of application-defined data per tab, an application must define a structure and use it instead of the `TCITEM` structure. The first member of the application-defined structure must be a [`TCITEMHEADER`](/windows/win32/api/commctrl/ns-commctrl-tcitemheaderw) structure. The `TCITEMHEADER` structure is identical to the `TCITEM` structure, but without the `lParam` member. The difference between the size of your structure and the size of the `TCITEMHEADER` structure should equal the number of extra bytes per tab. ### Example diff --git a/docs/mfc/reference/ctaskdialog-class.md b/docs/mfc/reference/ctaskdialog-class.md index 9c685c3560..2f1d87a819 100644 --- a/docs/mfc/reference/ctaskdialog-class.md +++ b/docs/mfc/reference/ctaskdialog-class.md @@ -685,7 +685,7 @@ virtual HRESULT OnHelp(); ### Return Value -The default implementation returns S_OK. +The default implementation returns S_FALSE. ### Remarks diff --git a/docs/mfc/reference/ctoolbar-class.md b/docs/mfc/reference/ctoolbar-class.md index cf94c96183..983d20748b 100644 --- a/docs/mfc/reference/ctoolbar-class.md +++ b/docs/mfc/reference/ctoolbar-class.md @@ -4,9 +4,8 @@ title: "CToolBar Class" ms.date: "11/04/2016" f1_keywords: ["CToolBar", "AFXEXT/CToolBar", "AFXEXT/CToolBar::CToolBar", "AFXEXT/CToolBar::CommandToIndex", "AFXEXT/CToolBar::Create", "AFXEXT/CToolBar::CreateEx", "AFXEXT/CToolBar::GetButtonInfo", "AFXEXT/CToolBar::GetButtonStyle", "AFXEXT/CToolBar::GetButtonText", "AFXEXT/CToolBar::GetItemID", "AFXEXT/CToolBar::GetItemRect", "AFXEXT/CToolBar::GetToolBarCtrl", "AFXEXT/CToolBar::LoadBitmap", "AFXEXT/CToolBar::LoadToolBar", "AFXEXT/CToolBar::SetBitmap", "AFXEXT/CToolBar::SetButtonInfo", "AFXEXT/CToolBar::SetButtons", "AFXEXT/CToolBar::SetButtonStyle", "AFXEXT/CToolBar::SetButtonText", "AFXEXT/CToolBar::SetHeight", "AFXEXT/CToolBar::SetSizes"] helpviewer_keywords: ["CToolBar [MFC], CToolBar", "CToolBar [MFC], CommandToIndex", "CToolBar [MFC], Create", "CToolBar [MFC], CreateEx", "CToolBar [MFC], GetButtonInfo", "CToolBar [MFC], GetButtonStyle", "CToolBar [MFC], GetButtonText", "CToolBar [MFC], GetItemID", "CToolBar [MFC], GetItemRect", "CToolBar [MFC], GetToolBarCtrl", "CToolBar [MFC], LoadBitmap", "CToolBar [MFC], LoadToolBar", "CToolBar [MFC], SetBitmap", "CToolBar [MFC], SetButtonInfo", "CToolBar [MFC], SetButtons", "CToolBar [MFC], SetButtonStyle", "CToolBar [MFC], SetButtonText", "CToolBar [MFC], SetHeight", "CToolBar [MFC], SetSizes"] -ms.assetid: e868da26-5e07-4607-9651-e2f863ad9059 --- -# CToolBar Class +# `CToolBar` Class Control bars that have a row of bitmapped buttons and optional separators. @@ -22,36 +21,36 @@ class CToolBar : public CControlBar |Name|Description| |----------|-----------------| -|[CToolBar::CToolBar](#ctoolbar)|Constructs a `CToolBar` object.| +|[`CToolBar::CToolBar`](#ctoolbar)|Constructs a `CToolBar` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CToolBar::CommandToIndex](#commandtoindex)|Returns the index of a button with the given command ID.| -|[CToolBar::Create](#create)|Creates the Windows toolbar and attaches it to the `CToolBar` object.| -|[CToolBar::CreateEx](#createex)|Creates a `CToolBar` object with additional styles for the embedded `CToolBarCtrl` object.| -|[CToolBar::GetButtonInfo](#getbuttoninfo)|Retrieves the ID, style, and image number of a button.| -|[CToolBar::GetButtonStyle](#getbuttonstyle)|Retrieves the style for a button.| -|[CToolBar::GetButtonText](#getbuttontext)|Retrieves the text that will appear on a button.| -|[CToolBar::GetItemID](#getitemid)|Returns the command ID of a button or separator at the given index.| -|[CToolBar::GetItemRect](#getitemrect)|Retrieves the display rectangle for the item at the given index.| -|[CToolBar::GetToolBarCtrl](#gettoolbarctrl)|Allows direct access to the underlying common control.| -|[CToolBar::LoadBitmap](#loadbitmap)|Loads the bitmap containing bitmap-button images.| -|[CToolBar::LoadToolBar](#loadtoolbar)|Loads a toolbar resource created with the resource editor.| -|[CToolBar::SetBitmap](#setbitmap)|Sets a bitmapped image.| -|[CToolBar::SetButtonInfo](#setbuttoninfo)|Sets the ID, style, and image number of a button.| -|[CToolBar::SetButtons](#setbuttons)|Sets button styles and an index of button images within the bitmap.| -|[CToolBar::SetButtonStyle](#setbuttonstyle)|Sets the style for a button.| -|[CToolBar::SetButtonText](#setbuttontext)|Sets the text that will appear on a button.| -|[CToolBar::SetHeight](#setheight)|Sets the height of the toolbar.| -|[CToolBar::SetSizes](#setsizes)|Sets the sizes of buttons and their bitmaps.| +|[`CToolBar::CommandToIndex`](#commandtoindex)|Returns the index of a button with the given command ID.| +|[`CToolBar::Create`](#create)|Creates the Windows toolbar and attaches it to the `CToolBar` object.| +|[`CToolBar::CreateEx`](#createex)|Creates a `CToolBar` object with additional styles for the embedded `CToolBarCtrl` object.| +|[`CToolBar::GetButtonInfo`](#getbuttoninfo)|Retrieves the ID, style, and image number of a button.| +|[`CToolBar::GetButtonStyle`](#getbuttonstyle)|Retrieves the style for a button.| +|[`CToolBar::GetButtonText`](#getbuttontext)|Retrieves the text that will appear on a button.| +|[`CToolBar::GetItemID`](#getitemid)|Returns the command ID of a button or separator at the given index.| +|[`CToolBar::GetItemRect`](#getitemrect)|Retrieves the display rectangle for the item at the given index.| +|[`CToolBar::GetToolBarCtrl`](#gettoolbarctrl)|Allows direct access to the underlying common control.| +|[`CToolBar::LoadBitmap`](#loadbitmap)|Loads the bitmap containing bitmap-button images.| +|[`CToolBar::LoadToolBar`](#loadtoolbar)|Loads a toolbar resource created with the resource editor.| +|[`CToolBar::SetBitmap`](#setbitmap)|Sets a bitmapped image.| +|[`CToolBar::SetButtonInfo`](#setbuttoninfo)|Sets the ID, style, and image number of a button.| +|[`CToolBar::SetButtons`](#setbuttons)|Sets button styles and an index of button images within the bitmap.| +|[`CToolBar::SetButtonStyle`](#setbuttonstyle)|Sets the style for a button.| +|[`CToolBar::SetButtonText`](#setbuttontext)|Sets the text that will appear on a button.| +|[`CToolBar::SetHeight`](#setheight)|Sets the height of the toolbar.| +|[`CToolBar::SetSizes`](#setsizes)|Sets the sizes of buttons and their bitmaps.| ## Remarks -The buttons can act like pushbuttons, check-box buttons, or radio buttons. `CToolBar` objects are usually embedded members of frame-window objects derived from the class [CFrameWnd](../../mfc/reference/cframewnd-class.md) or [CMDIFrameWnd](../../mfc/reference/cmdiframewnd-class.md). +The buttons can act like pushbuttons, check-box buttons, or radio buttons. `CToolBar` objects are usually embedded members of frame-window objects derived from the class [`CFrameWnd`](../../mfc/reference/cframewnd-class.md) or [`CMDIFrameWnd`](../../mfc/reference/cmdiframewnd-class.md). -[CToolBar::GetToolBarCtrl](#gettoolbarctrl), a member function new to MFC 4.0, allows you to take advantage of the Windows common control's support for toolbar customization and additional functionality. `CToolBar` member functions give you most of the functionality of the Windows common controls; however, when you call `GetToolBarCtrl`, you can give your toolbars even more of the characteristics of Windows 95/98 toolbars. When you call `GetToolBarCtrl`, it will return a reference to a `CToolBarCtrl` object. See [CToolBarCtrl](../../mfc/reference/ctoolbarctrl-class.md) for more information about designing toolbars using Windows common controls. For more general information about common controls, see [Common Controls](/windows/win32/Controls/common-controls-intro) in the Windows SDK. +[`CToolBar::GetToolBarCtrl`](#gettoolbarctrl), a member function new to MFC 4.0, allows you to take advantage of the Windows common control's support for toolbar customization and additional functionality. `CToolBar` member functions give you most of the functionality of the Windows common controls; however, when you call `GetToolBarCtrl`, you can give your toolbars even more of the characteristics of Windows 95/98 toolbars. When you call `GetToolBarCtrl`, it will return a reference to a `CToolBarCtrl` object. See [`CToolBarCtrl`](../../mfc/reference/ctoolbarctrl-class.md) for more information about designing toolbars using Windows common controls. For more general information about common controls, see [Common Controls](/windows/win32/Controls/common-controls-intro) in the Windows SDK. Visual C++ provides you with two methods to create a toolbar. To create a toolbar resource using the Resource Editor, follow these steps: @@ -59,25 +58,25 @@ Visual C++ provides you with two methods to create a toolbar. To create a toolba 1. Construct the `CToolBar` object. -1. Call the [Create](#create) (or [CreateEx](#createex)) function to create the Windows toolbar and attach it to the `CToolBar` object. +1. Call the [`Create`](#create) (or [`CreateEx`](#createex)) function to create the Windows toolbar and attach it to the `CToolBar` object. -1. Call [LoadToolBar](#loadtoolbar) to load the toolbar resource. +1. Call [`LoadToolBar`](#loadtoolbar) to load the toolbar resource. Otherwise, follow these steps: 1. Construct the `CToolBar` object. -1. Call the [Create](#create) (or [CreateEx](#createex)) function to create the Windows toolbar and attach it to the `CToolBar` object. +1. Call the [`Create`](#create) (or [`CreateEx`](#createex)) function to create the Windows toolbar and attach it to the `CToolBar` object. -1. Call [LoadBitmap](#loadbitmap) to load the bitmap that contains the toolbar button images. +1. Call [`LoadBitmap`](#loadbitmap) to load the bitmap that contains the toolbar button images. -1. Call [SetButtons](#setbuttons) to set the button style and associate each button with an image in the bitmap. +1. Call [`SetButtons`](#setbuttons) to set the button style and associate each button with an image in the bitmap. All the button images in the toolbar are taken from one bitmap, which must contain one image for each button. All images must be the same size; the default is 16 pixels wide and 15 pixels high. Images must be side by side in the bitmap. -The `SetButtons` function takes a pointer to an array of control IDs and an integer that specifies the number of elements in the array. The function sets each button's ID to the value of the corresponding element of the array and assigns each button an image index, which specifies the position of the button's image in the bitmap. If an array element has the value ID_SEPARATOR, no image index is assigned. +The `SetButtons` function takes a pointer to an array of control IDs and an integer that specifies the number of elements in the array. The function sets each button's ID to the value of the corresponding element of the array and assigns each button an image index, which specifies the position of the button's image in the bitmap. If an array element has the value `ID_SEPARATOR`, no image index is assigned. -The order of the images in the bitmap is typically the order in which they are drawn on the screen, but you can use the [SetButtonInfo](#setbuttoninfo) function to change the relationship between image order and drawing order. +The order of the images in the bitmap is typically the order in which they're drawn on the screen, but you can use the [`SetButtonInfo`](#setbuttoninfo) function to change the relationship between image order and drawing order. All buttons in a toolbar are the same size. The default is 24 x 22 pixels, in accordance with *Windows Interface Guidelines for Software Design*. Any additional space between the image and button dimensions is used to form a border around the image. @@ -88,33 +87,33 @@ Each button has one image. The various button states and styles (pressed, up, do Toolbar buttons imitate pushbuttons by default. However, toolbar buttons can also imitate check-box buttons or radio buttons. Check-box buttons have three states: checked, cleared, and indeterminate. Radio buttons have only two states: checked and cleared. -To set an individual button or separator style without pointing to an array, call [GetButtonStyle](#getbuttonstyle) to retrieve the style, and then call [SetButtonStyle](#setbuttonstyle) instead of `SetButtons`. `SetButtonStyle` is most useful when you want to change a button's style at run time. +To set an individual button or separator style without pointing to an array, call [`GetButtonStyle`](#getbuttonstyle) to retrieve the style, and then call [`SetButtonStyle`](#setbuttonstyle) instead of `SetButtons`. `SetButtonStyle` is most useful when you want to change a button's style at run time. -To assign text to appear on a button, call [GetButtonText](#getbuttontext) to retrieve the text to appear on the button, and then call [SetButtonText](#setbuttontext) to set the text. +To assign text to appear on a button, call [`GetButtonText`](#getbuttontext) to retrieve the text to appear on the button, and then call [`SetButtonText`](#setbuttontext) to set the text. -To create a check-box button, assign it the style TBBS_CHECKBOX or use a `CCmdUI` object's `SetCheck` member function in an ON_UPDATE_COMMAND_UI handler. Calling `SetCheck` turns a pushbutton into a check-box button. Pass `SetCheck` an argument of 0 for unchecked, 1 for checked, or 2 for indeterminate. +To create a check-box button, assign it the style `TBBS_CHECKBOX` or use a `CCmdUI` object's `SetCheck` member function in an `ON_UPDATE_COMMAND_UI` handler. Calling `SetCheck` turns a pushbutton into a check-box button. Pass `SetCheck` an argument of 0 for unchecked, 1 for checked, or 2 for indeterminate. -To create a radio button, call a [CCmdUI](../../mfc/reference/ccmdui-class.md) object's [SetRadio](../../mfc/reference/ccmdui-class.md#setradio) member function from an ON_UPDATE_COMMAND_UI handler. Pass `SetRadio` an argument of 0 for unchecked or nonzero for checked. In order to provide a radio group's mutually exclusive behavior, you must have ON_UPDATE_COMMAND_UI handlers for all of the buttons in the group. +To create a radio button, call a [`CCmdUI`](../../mfc/reference/ccmdui-class.md) object's [`SetRadio`](../../mfc/reference/ccmdui-class.md#setradio) member function from an `ON_UPDATE_COMMAND_UI` handler. Pass `SetRadio` an argument of 0 for unchecked or nonzero for checked. In order to provide a radio group's mutually exclusive behavior, you must have `ON_UPDATE_COMMAND_UI` handlers for all of the buttons in the group. For more information on using `CToolBar`, see the article [MFC Toolbar Implementation](../../mfc/mfc-toolbar-implementation.md) and [Technical Note 31: Control Bars](../../mfc/tn031-control-bars.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) -[CControlBar](../../mfc/reference/ccontrolbar-class.md) +[`CControlBar`](../../mfc/reference/ccontrolbar-class.md) `CToolBar` ## Requirements -**Header:** afxext.h +**Header:** `afxext.h` -## CToolBar::CommandToIndex +## `CToolBar::CommandToIndex` This member function returns the index of the first toolbar button, starting at position 0, whose command ID matches `nIDFind`. @@ -124,14 +123,14 @@ int CommandToIndex(UINT nIDFind) const; ### Parameters -*nIDFind*
+*`nIDFind`*\ Command ID of a toolbar button. ### Return Value The index of the button, or -1 if no button has the given command ID. -## CToolBar::Create +## `CToolBar::Create` This member function creates a Windows toolbar (a child window) and associates it with the `CToolBar` object. @@ -144,31 +143,31 @@ virtual BOOL Create( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ Pointer to the window that is the toolbar's parent. -*dwStyle*
+*`dwStyle`*\ The toolbar style. Additional toolbar styles supported are: -- CBRS_TOP Control bar is at top of the frame window. +- `CBRS_TOP` Control bar is at top of the frame window. -- CBRS_BOTTOM Control bar is at bottom of the frame window. +- `CBRS_BOTTOM` Control bar is at bottom of the frame window. -- CBRS_NOALIGN Control bar is not repositioned when the parent is resized. +- `CBRS_NOALIGN` Control bar isn't repositioned when the parent is resized. -- CBRS_TOOLTIPS Control bar displays tool tips. +- `CBRS_TOOLTIPS` Control bar displays tool tips. -- CBRS_SIZE_DYNAMIC Control bar is dynamic. +- `CBRS_SIZE_DYNAMIC` Control bar is dynamic. -- CBRS_SIZE_FIXED Control bar is fixed. +- `CBRS_SIZE_FIXED` Control bar is fixed. -- CBRS_FLOATING Control bar is floating. +- `CBRS_FLOATING` Control bar is floating. -- CBRS_FLYBY Status bar displays information about the button. +- `CBRS_FLYBY` Status bar displays information about the button. -- CBRS_HIDE_INPLACE Control bar is not displayed to the user. +- `CBRS_HIDE_INPLACE` Control bar isn't displayed to the user. -*nID*
+*`nID`*\ The toolbar's child-window ID. ### Return Value @@ -183,7 +182,7 @@ It also sets the toolbar height to a default value. [!code-cpp[NVC_MFCDocView#179](../../mfc/codesnippet/cpp/ctoolbar-class_1.cpp)] -## CToolBar::CreateEx +## `CToolBar::CreateEx` Call this function to create a Windows toolbar (a child window) and associate it with the `CToolBar` object. @@ -202,19 +201,19 @@ virtual BOOL CreateEx( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ Pointer to the window that is the toolbar's parent. -*dwCtrlStyle*
-Additional styles for the creation of the embedded [CToolBarCtrl](../../mfc/reference/ctoolbarctrl-class.md) object. By default, this value is set to TBSTYLE_FLAT. For a complete list of toolbar styles, see *dwStyle*. +*`dwCtrlStyle`*\ +Additional styles for the creation of the embedded [`CToolBarCtrl`](../../mfc/reference/ctoolbarctrl-class.md) object. By default, this value is set to `TBSTYLE_FLAT`. For a complete list of toolbar styles, see *`dwStyle`*. -*dwStyle*
+*`dwStyle`*\ The toolbar style. See [Toolbar Control and Button Styles](/windows/win32/Controls/toolbar-control-and-button-styles) in the Windows SDK for a list of appropriate styles. -*rcBorders*
-A [CRect](../../atl-mfc-shared/reference/crect-class.md) object that defines the widths of the toolbar window borders. These borders are set to 0,0,0,0 by default, thereby resulting in a toolbar window with no borders. +*`rcBorders`*\ +A [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that defines the widths of the toolbar window borders. These borders are set to 0,0,0,0 by default, thereby resulting in a toolbar window with no borders. -*nID*
+*`nID`*\ The toolbar's child-window ID. ### Return Value @@ -225,13 +224,13 @@ Nonzero if successful; otherwise 0. It also sets the toolbar height to a default value. -Use `CreateEx`, instead of [Create](#create), when certain styles need to be present during the creation of the embedded tool bar control. For example, set *dwCtrlStyle* to TBSTYLE_FLAT | TBSTYLE_TRANSPARENT to create a toolbar that resembles the Internet Explorer 4 toolbars. +Use `CreateEx`, instead of [`Create`](#create), when certain styles need to be present during the creation of the embedded tool bar control. For example, set *`dwCtrlStyle`* to `TBSTYLE_FLAT | TBSTYLE_TRANSPARENT` to create a toolbar that resembles the Internet Explorer 4 toolbars. ### Example [!code-cpp[NVC_MFCDocView#180](../../mfc/codesnippet/cpp/ctoolbar-class_2.cpp)] -## CToolBar::CToolBar +## `CToolBar::CToolBar` This member function constructs a `CToolBar` object and sets the default sizes. @@ -241,11 +240,11 @@ CToolBar(); ### Remarks -Call the [Create](#create) member function to create the toolbar window. +Call the [`Create`](#create) member function to create the toolbar window. -## CToolBar::GetButtonInfo +## `CToolBar::GetButtonInfo` -This member function retrieves the control ID, style, and image index of the toolbar button or separator at the location specified by *nIndex.* +This member function retrieves the control ID, style, and image index of the toolbar button or separator at the location specified by *`nIndex`*. ```cpp void GetButtonInfo( @@ -257,25 +256,25 @@ void GetButtonInfo( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the toolbar button or separator whose information is to be retrieved. -*nID*
+*`nID`*\ Reference to a UINT that is set to the command ID of the button. -*nStyle*
+*`nStyle`*\ Reference to a UINT that is set to the style of the button. -*iImage*
+*`iImage`*\ Reference to an integer that is set to the index of the button's image within the bitmap. ### Remarks -Those values are assigned to the variables referenced by *nID*, *nStyle*, and *iImage*. The image index is the position of the image within the bitmap that contains images for all the toolbar buttons. The first image is at position 0. +Those values are assigned to the variables referenced by *`nID`*, *`nStyle`*, and *`iImage`*. The image index is the position of the image within the bitmap that contains images for all the toolbar buttons. The first image is at position 0. -If *nIndex* specifies a separator, *iImage* is set to the separator width in pixels. +If *`nIndex`* specifies a separator, *`iImage`* is set to the separator width in pixels. -## CToolBar::GetButtonStyle +## `CToolBar::GetButtonStyle` Call this member function to retrieve the style of a button or separator on the toolbar. @@ -285,18 +284,18 @@ UINT GetButtonStyle(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ The index of the toolbar button or separator style to be retrieved. ### Return Value -The style of the button or separator specified by *nIndex*. +The style of the button or separator specified by *`nIndex`*. ### Remarks -A button's style determines how the button appears and how it responds to user input. See [SetButtonStyle](#setbuttonstyle) for examples of button styles. +A button's style determines how the button appears and how it responds to user input. See [`SetButtonStyle`](#setbuttonstyle) for examples of button styles. -## CToolBar::GetButtonText +## `CToolBar::GetButtonText` Call this member function to retrieve the text that appears on a button. @@ -310,11 +309,11 @@ void GetButtonText( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the text to be retrieved. -*rString*
-A reference to a [CString](../../atl-mfc-shared/reference/cstringt-class.md) object that will contain the text to be retrieved. +*`rString`*\ +A reference to a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) object that will contain the text to be retrieved. ### Return Value @@ -324,9 +323,9 @@ A `CString` object containing the button text. The second form of this member function fills a `CString` object with the string text. -## CToolBar::GetItemID +## `CToolBar::GetItemID` -This member function returns the command ID of the button or separator specified by *nIndex*. +This member function returns the command ID of the button or separator specified by *`nIndex`*. ``` UINT GetItemID(int nIndex) const; @@ -334,20 +333,20 @@ UINT GetItemID(int nIndex) const; ### Parameters -*nIndex*
+*`nIndex`*\ Index of the item whose ID is to be retrieved. ### Return Value -The command ID of the button or separator specified by *nIndex*. +The command ID of the button or separator specified by *`nIndex`*. ### Remarks -Separators return ID_SEPARATOR. +Separators return `ID_SEPARATOR`. -## CToolBar::GetItemRect +## `CToolBar::GetItemRect` -This member function fills the `RECT` structure whose address is contained in *lpRect* with the coordinates of the button or separator specified by *nIndex*. +This member function fills the `RECT` structure whose address is contained in *`lpRect`* with the coordinates of the button or separator specified by *`nIndex`*. ``` virtual void GetItemRect( @@ -357,11 +356,11 @@ virtual void GetItemRect( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the item (button or separator) whose rectangle coordinates are to be retrieved. -*lpRect*
-Address of the [RECT](/windows/win32/api/windef/ns-windef-rect) structure that will contain the item's coordinates. +*`lpRect`*\ +Address of the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that will contain the item's coordinates. ### Remarks @@ -371,9 +370,9 @@ Use `GetItemRect` to get the coordinates of a separator you want to replace with ### Example - See the example for [CToolBar::SetSizes](#setsizes). + See the example for [`CToolBar::SetSizes`](#setsizes). -## CToolBar::GetToolBarCtrl +## `CToolBar::GetToolBarCtrl` This member function allows direct access to the underlying common control. @@ -387,7 +386,7 @@ A reference to a `CToolBarCtrl` object. ### Remarks -Use `GetToolBarCtrl` to take advantage of the functionality of the Windows toolbar common control, and to take advantage of the support [CToolBarCtrl](../../mfc/reference/ctoolbarctrl-class.md) provides for toolbar customization. +Use `GetToolBarCtrl` to take advantage of the functionality of the Windows toolbar common control, and to take advantage of the support [`CToolBarCtrl`](../../mfc/reference/ctoolbarctrl-class.md) provides for toolbar customization. For more information about using common controls, see the article [Controls](../../mfc/controls-mfc.md) and [Common Controls](/windows/win32/Controls/common-controls-intro) in the Windows SDK. @@ -395,7 +394,7 @@ For more information about using common controls, see the article [Controls](../ [!code-cpp[NVC_MFCDocViewSDI#15](../../mfc/codesnippet/cpp/ctoolbar-class_3.cpp)] -## CToolBar::LoadBitmap +## `CToolBar::LoadBitmap` Call this member function to load the bitmap specified by `lpszResourceName` or `nIDResource`. @@ -406,10 +405,10 @@ BOOL LoadBitmap(UINT nIDResource); ### Parameters -*lpszResourceName*
+*`lpszResourceName`*\ Pointer to the resource name of the bitmap to be loaded. -*nIDResource*
+*`nIDResource`*\ Resource ID of the bitmap to be loaded. ### Return Value @@ -418,14 +417,14 @@ Nonzero if successful; otherwise 0. ### Remarks -The bitmap should contain one image for each toolbar button. If the images are not of the standard size (16 pixels wide and 15 pixels high), call [SetSizes](#setsizes) to set the button sizes and their images. +The bitmap should contain one image for each toolbar button. If the images aren't of the standard size (16 pixels wide and 15 pixels high), call [`SetSizes`](#setsizes) to set the button sizes and their images. > [!WARNING] > `CToolBar` supports bitmaps with a maximum of 16 colors. When you load an image into a toolbar editor, Visual Studio automatically converts the image to a 16-color bitmap, if necessary, and displays a warning message if the image was converted. If you use an image with more than 16 colors (using an external editor to edit the image), the application might behave unexpectedly. -## CToolBar::LoadToolBar +## `CToolBar::LoadToolBar` -Call this member function to load the toolbar specified by *lpszResourceName* or *nIDResource*. +Call this member function to load the toolbar specified by *`lpszResourceName`* or *`nIDResource`*. ``` BOOL LoadToolBar(LPCTSTR lpszResourceName); @@ -434,10 +433,10 @@ BOOL LoadToolBar(UINT nIDResource); ### Parameters -*lpszResourceName*
+*`lpszResourceName`*\ Pointer to the resource name of the toolbar to be loaded. -*nIDResource*
+*`nIDResource`*\ Resource ID of the toolbar to be loaded. ### Return Value @@ -450,9 +449,9 @@ See [toolbar editor](../../windows/toolbar-editor.md) in for more information ab ### Example - See the example for [CToolBar::CreateEx](#createex). + See the example for [`CToolBar::CreateEx`](#createex). -## CToolBar::SetBitmap +## `CToolBar::SetBitmap` Call this member function to set the bitmap image for the toolbar. @@ -462,7 +461,7 @@ BOOL SetBitmap(HBITMAP hbmImageWell); ### Parameters -*hbmImageWell*
+*`hbmImageWell`*\ Handle of a bitmap image that is associated with a toolbar. ### Return Value @@ -473,7 +472,7 @@ Nonzero if successful; otherwise 0. For example, call `SetBitmap` to change the bitmapped image after the user takes an action on a document that changes the action of a button. -## CToolBar::SetButtonInfo +## `CToolBar::SetButtonInfo` Call this member function to set the button's command ID, style, and image number. @@ -487,46 +486,46 @@ void SetButtonInfo( ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of the button or separator for which information is to be set. -*nID*
+*`nID`*\ The value to which the button's command ID is set. -*nStyle*
+*`nStyle`*\ The new button style. The following button styles are supported: -- TBBS_BUTTON Standard pushbutton (default) +- `TBBS_BUTTON` Standard pushbutton (default) -- TBBS_SEPARATOR Separator +- `TBBS_SEPARATOR` Separator -- TBBS_CHECKBOX Auto check-box button +- `TBBS_CHECKBOX` Auto check-box button -- TBBS_GROUP Marks the start of a group of buttons +- `TBBS_GROUP` Marks the start of a group of buttons -- TBBS_CHECKGROUP Marks the start of a group of check-box buttons +- `TBBS_CHECKGROUP` Marks the start of a group of check-box buttons -- TBBS_DROPDOWN Creates a drop-down list button. +- `TBBS_DROPDOWN` Creates a drop-down list button. -- TBBS_AUTOSIZE The button's width will be calculated based on the text of the button, not on the size of the image. +- `TBBS_AUTOSIZE` The button's width will be calculated based on the text of the button, not on the size of the image. -- TBBS_NOPREFIX The button text will not have an accelerator prefix associated with it. +- `TBBS_NOPREFIX` The button text won't have an accelerator prefix associated with it. -*iImage*
+*`iImage`*\ New index for the button's image within the bitmap. ### Remarks -For separators, which have the style TBBS_SEPARATOR, this function sets the separator's width in pixels to the value stored in *iImage*. +For separators, which have the style `TBBS_SEPARATOR`, this function sets the separator's width in pixels to the value stored in *`iImage`*. > [!NOTE] -> You can also set button states using the *nStyle* parameter; however, because button states are controlled by the [ON_UPDATE_COMMAND_UI](message-map-macros-mfc.md#on_update_command_ui) handler, any state you set using `SetButtonInfo` will be lost during the next idle processing. See [How to Update User-Interface Objects](../../mfc/how-to-update-user-interface-objects.md) and [TN031: Control Bars](../../mfc/tn031-control-bars.md) for more information. +> You can also set button states using the *`nStyle`* parameter; however, because button states are controlled by the [`ON_UPDATE_COMMAND_UI`](message-map-macros-mfc.md#on_update_command_ui) handler, any state you set using `SetButtonInfo` will be lost during the next idle processing. See [How to Update User-Interface Objects](../../mfc/how-to-update-user-interface-objects.md) and [TN031: Control Bars](../../mfc/tn031-control-bars.md) for more information. -For information on bitmap images and buttons, see the [CToolBar](../../mfc/reference/ctoolbar-class.md) Overview and [CToolBar::LoadBitmap](#loadbitmap). +For information on bitmap images and buttons, see the [`CToolBar`](../../mfc/reference/ctoolbar-class.md) Overview and [`CToolBar::LoadBitmap`](#loadbitmap). -## CToolBar::SetButtons +## `CToolBar::SetButtons` -This member function sets each toolbar button's command ID to the value specified by the corresponding element of the array *lpIDArray*. +This member function sets each toolbar button's command ID to the value specified by the corresponding element of the array *`lpIDArray`*. ``` BOOL SetButtons( @@ -536,11 +535,11 @@ BOOL SetButtons( ### Parameters -*lpIDArray*
+*`lpIDArray`*\ Pointer to an array of command Ids. It can be NULL to allocate empty buttons. -*nIDCount*
-Number of elements in the array pointed to by *lpIDArray*. +*`nIDCount`*\ +Number of elements in the array pointed to by *`lpIDArray`*. ### Return Value @@ -548,13 +547,13 @@ Nonzero if successful; otherwise 0. ### Remarks -If an element of the array has the value ID_SEPARATOR, a separator is created in the corresponding position of the toolbar. This function also sets each button's style to TBBS_BUTTON and each separator's style to TBBS_SEPARATOR, and assigns an image index to each button. The image index specifies the position of the button's image within the bitmap. +If an element of the array has the value `ID_SEPARATOR`, a separator is created in the corresponding position of the toolbar. This function also sets each button's style to `TBBS_BUTTON` and each separator's style to `TBBS_SEPARATOR`, and assigns an image index to each button. The image index specifies the position of the button's image within the bitmap. -You do not need to account for separators in the bitmap because this function does not assign image indexes for separators. If your toolbar has buttons at positions 0, 1, and 3 and a separator at position 2, the images at positions 0, 1, and 2 in your bitmap are assigned to the buttons at positions 0, 1, and 3, respectively. +You don't need to account for separators in the bitmap because this function doesn't assign image indexes for separators. If your toolbar has buttons at positions 0, 1, and 3 and a separator at position 2, the images at positions 0, 1, and 2 in your bitmap are assigned to the buttons at positions 0, 1, and 3, respectively. -If *lpIDArray* is NULL, this function allocates space for the number of items specified by *nIDCount*. Use [SetButtonInfo](#setbuttoninfo) to set each item's attributes. +If *`lpIDArray`* is NULL, this function allocates space for the number of items specified by *`nIDCount`*. Use [`SetButtonInfo`](#setbuttoninfo) to set each item's attributes. -## CToolBar::SetButtonStyle +## `CToolBar::SetButtonStyle` Call this member function to set the style of a button or separator, or to group buttons. @@ -566,38 +565,38 @@ void SetButtonStyle( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the button or separator whose information is to be set. -*nStyle*
+*`nStyle`*\ The button style. The following button styles are supported: -- TBBS_BUTTON Standard pushbutton (default) +- `TBBS_BUTTON` Standard pushbutton (default) -- TBBS_SEPARATOR Separator +- `TBBS_SEPARATOR` Separator -- TBBS_CHECKBOX Auto check-box button +- `TBBS_CHECKBOX` Auto check-box button -- TBBS_GROUP Marks the start of a group of buttons +- `TBBS_GROUP` Marks the start of a group of buttons -- TBBS_CHECKGROUP Marks the start of a group of check-box buttons +- `TBBS_CHECKGROUP` Marks the start of a group of check-box buttons -- TBBS_DROPDOWN Creates a drop-down list button +- `TBBS_DROPDOWN` Creates a drop-down list button -- TBBS_AUTOSIZE The button's width will be calculated based on the text of the button, not on the size of the image +- `TBBS_AUTOSIZE` The button's width will be calculated based on the text of the button, not on the size of the image -- TBBS_NOPREFIX The button text will not have an accelerator prefix associated with it +- `TBBS_NOPREFIX` The button text won't have an accelerator prefix associated with it ### Remarks A button's style determines how the button appears and how it responds to user input. -Before calling `SetButtonStyle`, call the [GetButtonStyle](#getbuttonstyle) member function to retrieve the button or separator style. +Before calling `SetButtonStyle`, call the [`GetButtonStyle`](#getbuttonstyle) member function to retrieve the button or separator style. > [!NOTE] -> You can also set button states using the *nStyle* parameter; however, because button states are controlled by the [ON_UPDATE_COMMAND_UI](message-map-macros-mfc.md#on_update_command_ui) handler, any state you set using `SetButtonStyle` will be lost during the next idle processing. See [How to Update User-Interface Objects](../../mfc/how-to-update-user-interface-objects.md) and [TN031: Control Bars](../../mfc/tn031-control-bars.md) for more information. +> You can also set button states using the *`nStyle`* parameter; however, because button states are controlled by the [`ON_UPDATE_COMMAND_UI`](message-map-macros-mfc.md#on_update_command_ui) handler, any state you set using `SetButtonStyle` will be lost during the next idle processing. See [How to Update User-Interface Objects](../../mfc/how-to-update-user-interface-objects.md) and [TN031: Control Bars](../../mfc/tn031-control-bars.md) for more information. -## CToolBar::SetButtonText +## `CToolBar::SetButtonText` Call this function to set the text on a button. @@ -609,10 +608,10 @@ BOOL SetButtonText( ### Parameters -*nIndex*
+*`nIndex`*\ Index of the button whose text is to be set. -*lpszText*
+*`lpszText`*\ Points to the text to be set on a button. ### Return Value @@ -621,11 +620,11 @@ Nonzero if successful; otherwise 0. ### Example - See the example for [CToolBar::GetToolBarCtrl](#gettoolbarctrl). + See the example for [`CToolBar::GetToolBarCtrl`](#gettoolbarctrl). -## CToolBar::SetHeight +## `CToolBar::SetHeight` -This member function sets the toolbar's height to the value, in pixels, specified in *cyHeight*. +This member function sets the toolbar's height to the value, in pixels, specified in *`cyHeight`*. ```cpp void SetHeight(int cyHeight); @@ -633,18 +632,18 @@ void SetHeight(int cyHeight); ### Parameters -*cyHeight*
+*`cyHeight`*\ The height in pixels of the toolbar. ### Remarks -After calling [SetSizes](#setsizes), use this member function to override the standard toolbar height. If the height is too small, the buttons will be clipped at the bottom. +After calling [`SetSizes`](#setsizes), use this member function to override the standard toolbar height. If the height is too small, the buttons will be clipped at the bottom. -If this function is not called, the framework uses the size of the button to determine the toolbar height. +If this function isn't called, the framework uses the size of the button to determine the toolbar height. -## CToolBar::SetSizes +## `CToolBar::SetSizes` -Call this member function to set the toolbar's buttons to the size, in pixels, specified in *sizeButton*. +Call this member function to set the toolbar's buttons to the size, in pixels, specified in *`sizeButton`*. ```cpp void SetSizes( @@ -654,17 +653,17 @@ void SetSizes( ### Parameters -*sizeButton*
+*`sizeButton`*\ The size in pixels of each button. -*sizeImage*
+*`sizeImage`*\ The size in pixels of each image. ### Remarks -The *sizeImage* parameter must contain the size, in pixels, of the images in the toolbar's bitmap. The dimensions in *sizeButton* must be sufficient to hold the image plus 7 pixels extra in width and 6 pixels extra in height. This function also sets the toolbar height to fit the buttons. +The *`sizeImage`* parameter must contain the size, in pixels, of the images in the toolbar's bitmap. The dimensions in *`sizeButton`* must be sufficient to hold the image plus 7 pixels extra in width and 6 pixels extra in height. This function also sets the toolbar height to fit the buttons. -Call this member function only for toolbars that do not follow *Windows Interface Guidelines for Software Design* recommendations for button and image sizes. +Call this member function only for toolbars that don't follow *Windows Interface Guidelines for Software Design* recommendations for button and image sizes. ### Example @@ -672,10 +671,9 @@ Call this member function only for toolbars that do not follow *Windows Interfac ## See also -[MFC Sample CTRLBARS](../../overview/visual-cpp-samples.md)
-[MFC Sample DLGCBR32](../../overview/visual-cpp-samples.md)
-[MFC Sample DOCKTOOL](../../overview/visual-cpp-samples.md)
-[CControlBar Class](../../mfc/reference/ccontrolbar-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CToolBarCtrl Class](../../mfc/reference/ctoolbarctrl-class.md)
-[CControlBar Class](../../mfc/reference/ccontrolbar-class.md) +[MFC Sample `CTRLBARS`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `DLGCBR32`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `DOCKTOOL`](../../overview/visual-cpp-samples.md)\ +[`CControlBar` Class](../../mfc/reference/ccontrolbar-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CToolBarCtrl` Class](../../mfc/reference/ctoolbarctrl-class.md) diff --git a/docs/mfc/reference/ctoolbarctrl-class.md b/docs/mfc/reference/ctoolbarctrl-class.md index dd9eb9520b..e213031818 100644 --- a/docs/mfc/reference/ctoolbarctrl-class.md +++ b/docs/mfc/reference/ctoolbarctrl-class.md @@ -4,9 +4,8 @@ title: "CToolBarCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CToolBarCtrl", "AFXCMN/CToolBarCtrl", "AFXCMN/CToolBarCtrl::CToolBarCtrl", "AFXCMN/CToolBarCtrl::AddBitmap", "AFXCMN/CToolBarCtrl::AddButtons", "AFXCMN/CToolBarCtrl::AddString", "AFXCMN/CToolBarCtrl::AddStrings", "AFXCMN/CToolBarCtrl::AutoSize", "AFXCMN/CToolBarCtrl::ChangeBitmap", "AFXCMN/CToolBarCtrl::CheckButton", "AFXCMN/CToolBarCtrl::CommandToIndex", "AFXCMN/CToolBarCtrl::Create", "AFXCMN/CToolBarCtrl::CreateEx", "AFXCMN/CToolBarCtrl::Customize", "AFXCMN/CToolBarCtrl::DeleteButton", "AFXCMN/CToolBarCtrl::EnableButton", "AFXCMN/CToolBarCtrl::GetAnchorHighlight", "AFXCMN/CToolBarCtrl::GetBitmap", "AFXCMN/CToolBarCtrl::GetBitmapFlags", "AFXCMN/CToolBarCtrl::GetButton", "AFXCMN/CToolBarCtrl::GetButtonCount", "AFXCMN/CToolBarCtrl::GetButtonInfo", "AFXCMN/CToolBarCtrl::GetButtonSize", "AFXCMN/CToolBarCtrl::GetColorScheme", "AFXCMN/CToolBarCtrl::GetDisabledImageList", "AFXCMN/CToolBarCtrl::GetDropTarget", "AFXCMN/CToolBarCtrl::GetExtendedStyle", "AFXCMN/CToolBarCtrl::GetHotImageList", "AFXCMN/CToolBarCtrl::GetHotItem", "AFXCMN/CToolBarCtrl::GetImageList", "AFXCMN/CToolBarCtrl::GetInsertMark", "AFXCMN/CToolBarCtrl::GetInsertMarkColor", "AFXCMN/CToolBarCtrl::GetItemRect", "AFXCMN/CToolBarCtrl::GetMaxSize", "AFXCMN/CToolBarCtrl::GetMaxTextRows", "AFXCMN/CToolBarCtrl::GetMetrics", "AFXCMN/CToolBarCtrl::GetPadding", "AFXCMN/CToolBarCtrl::GetPressedImageList", "AFXCMN/CToolBarCtrl::GetRect", "AFXCMN/CToolBarCtrl::GetRows", "AFXCMN/CToolBarCtrl::GetState", "AFXCMN/CToolBarCtrl::GetString", "AFXCMN/CToolBarCtrl::GetStyle", "AFXCMN/CToolBarCtrl::GetToolTips", "AFXCMN/CToolBarCtrl::HideButton", "AFXCMN/CToolBarCtrl::HitTest", "AFXCMN/CToolBarCtrl::Indeterminate", "AFXCMN/CToolBarCtrl::InsertButton", "AFXCMN/CToolBarCtrl::InsertMarkHitTest", "AFXCMN/CToolBarCtrl::IsButtonChecked", "AFXCMN/CToolBarCtrl::IsButtonEnabled", "AFXCMN/CToolBarCtrl::IsButtonHidden", "AFXCMN/CToolBarCtrl::IsButtonHighlighted", "AFXCMN/CToolBarCtrl::IsButtonIndeterminate", "AFXCMN/CToolBarCtrl::IsButtonPressed", "AFXCMN/CToolBarCtrl::LoadImages", "AFXCMN/CToolBarCtrl::MapAccelerator", "AFXCMN/CToolBarCtrl::MarkButton", "AFXCMN/CToolBarCtrl::MoveButton", "AFXCMN/CToolBarCtrl::PressButton", "AFXCMN/CToolBarCtrl::ReplaceBitmap", "AFXCMN/CToolBarCtrl::RestoreState", "AFXCMN/CToolBarCtrl::SaveState", "AFXCMN/CToolBarCtrl::SetAnchorHighlight", "AFXCMN/CToolBarCtrl::SetBitmapSize", "AFXCMN/CToolBarCtrl::SetButtonInfo", "AFXCMN/CToolBarCtrl::SetButtonSize", "AFXCMN/CToolBarCtrl::SetButtonStructSize", "AFXCMN/CToolBarCtrl::SetButtonWidth", "AFXCMN/CToolBarCtrl::SetCmdID", "AFXCMN/CToolBarCtrl::SetColorScheme", "AFXCMN/CToolBarCtrl::SetDisabledImageList", "AFXCMN/CToolBarCtrl::SetDrawTextFlags", "AFXCMN/CToolBarCtrl::SetExtendedStyle", "AFXCMN/CToolBarCtrl::SetHotImageList", "AFXCMN/CToolBarCtrl::SetHotItem", "AFXCMN/CToolBarCtrl::SetImageList", "AFXCMN/CToolBarCtrl::SetIndent", "AFXCMN/CToolBarCtrl::SetInsertMark", "AFXCMN/CToolBarCtrl::SetInsertMarkColor", "AFXCMN/CToolBarCtrl::SetMaxTextRows", "AFXCMN/CToolBarCtrl::SetMetrics", "AFXCMN/CToolBarCtrl::SetOwner", "AFXCMN/CToolBarCtrl::SetPadding", "AFXCMN/CToolBarCtrl::SetPressedImageList", "AFXCMN/CToolBarCtrl::SetRows", "AFXCMN/CToolBarCtrl::SetState", "AFXCMN/CToolBarCtrl::SetStyle", "AFXCMN/CToolBarCtrl::SetToolTips", "AFXCMN/CToolBarCtrl::SetWindowTheme"] helpviewer_keywords: ["CToolBarCtrl [MFC], CToolBarCtrl", "CToolBarCtrl [MFC], AddBitmap", "CToolBarCtrl [MFC], AddButtons", "CToolBarCtrl [MFC], AddString", "CToolBarCtrl [MFC], AddStrings", "CToolBarCtrl [MFC], AutoSize", "CToolBarCtrl [MFC], ChangeBitmap", "CToolBarCtrl [MFC], CheckButton", "CToolBarCtrl [MFC], CommandToIndex", "CToolBarCtrl [MFC], Create", "CToolBarCtrl [MFC], CreateEx", "CToolBarCtrl [MFC], Customize", "CToolBarCtrl [MFC], DeleteButton", "CToolBarCtrl [MFC], EnableButton", "CToolBarCtrl [MFC], GetAnchorHighlight", "CToolBarCtrl [MFC], GetBitmap", "CToolBarCtrl [MFC], GetBitmapFlags", "CToolBarCtrl [MFC], GetButton", "CToolBarCtrl [MFC], GetButtonCount", "CToolBarCtrl [MFC], GetButtonInfo", "CToolBarCtrl [MFC], GetButtonSize", "CToolBarCtrl [MFC], GetColorScheme", "CToolBarCtrl [MFC], GetDisabledImageList", "CToolBarCtrl [MFC], GetDropTarget", "CToolBarCtrl [MFC], GetExtendedStyle", "CToolBarCtrl [MFC], GetHotImageList", "CToolBarCtrl [MFC], GetHotItem", "CToolBarCtrl [MFC], GetImageList", "CToolBarCtrl [MFC], GetInsertMark", "CToolBarCtrl [MFC], GetInsertMarkColor", "CToolBarCtrl [MFC], GetItemRect", "CToolBarCtrl [MFC], GetMaxSize", "CToolBarCtrl [MFC], GetMaxTextRows", "CToolBarCtrl [MFC], GetMetrics", "CToolBarCtrl [MFC], GetPadding", "CToolBarCtrl [MFC], GetPressedImageList", "CToolBarCtrl [MFC], GetRect", "CToolBarCtrl [MFC], GetRows", "CToolBarCtrl [MFC], GetState", "CToolBarCtrl [MFC], GetString", "CToolBarCtrl [MFC], GetStyle", "CToolBarCtrl [MFC], GetToolTips", "CToolBarCtrl [MFC], HideButton", "CToolBarCtrl [MFC], HitTest", "CToolBarCtrl [MFC], Indeterminate", "CToolBarCtrl [MFC], InsertButton", "CToolBarCtrl [MFC], InsertMarkHitTest", "CToolBarCtrl [MFC], IsButtonChecked", "CToolBarCtrl [MFC], IsButtonEnabled", "CToolBarCtrl [MFC], IsButtonHidden", "CToolBarCtrl [MFC], IsButtonHighlighted", "CToolBarCtrl [MFC], IsButtonIndeterminate", "CToolBarCtrl [MFC], IsButtonPressed", "CToolBarCtrl [MFC], LoadImages", "CToolBarCtrl [MFC], MapAccelerator", "CToolBarCtrl [MFC], MarkButton", "CToolBarCtrl [MFC], MoveButton", "CToolBarCtrl [MFC], PressButton", "CToolBarCtrl [MFC], ReplaceBitmap", "CToolBarCtrl [MFC], RestoreState", "CToolBarCtrl [MFC], SaveState", "CToolBarCtrl [MFC], SetAnchorHighlight", "CToolBarCtrl [MFC], SetBitmapSize", "CToolBarCtrl [MFC], SetButtonInfo", "CToolBarCtrl [MFC], SetButtonSize", "CToolBarCtrl [MFC], SetButtonStructSize", "CToolBarCtrl [MFC], SetButtonWidth", "CToolBarCtrl [MFC], SetCmdID", "CToolBarCtrl [MFC], SetColorScheme", "CToolBarCtrl [MFC], SetDisabledImageList", "CToolBarCtrl [MFC], SetDrawTextFlags", "CToolBarCtrl [MFC], SetExtendedStyle", "CToolBarCtrl [MFC], SetHotImageList", "CToolBarCtrl [MFC], SetHotItem", "CToolBarCtrl [MFC], SetImageList", "CToolBarCtrl [MFC], SetIndent", "CToolBarCtrl [MFC], SetInsertMark", "CToolBarCtrl [MFC], SetInsertMarkColor", "CToolBarCtrl [MFC], SetMaxTextRows", "CToolBarCtrl [MFC], SetMetrics", "CToolBarCtrl [MFC], SetOwner", "CToolBarCtrl [MFC], SetPadding", "CToolBarCtrl [MFC], SetPressedImageList", "CToolBarCtrl [MFC], SetRows", "CToolBarCtrl [MFC], SetState", "CToolBarCtrl [MFC], SetStyle", "CToolBarCtrl [MFC], SetToolTips", "CToolBarCtrl [MFC], SetWindowTheme"] -ms.assetid: 8f2f8ad2-05d7-4975-8715-3f2eed795248 --- -# CToolBarCtrl Class +# `CToolBarCtrl` Class Provides the functionality of the Windows toolbar common control. @@ -22,99 +21,99 @@ class CToolBarCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CToolBarCtrl::CToolBarCtrl](#ctoolbarctrl)|Constructs a `CToolBarCtrl` object.| +|[`CToolBarCtrl::CToolBarCtrl`](#ctoolbarctrl)|Constructs a `CToolBarCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CToolBarCtrl::AddBitmap](#addbitmap)|Adds one or more bitmap button images to the list of button images available for a toolbar control.| -|[CToolBarCtrl::AddButtons](#addbuttons)|Adds one or more buttons to a toolbar control.| -|[CToolBarCtrl::AddString](#addstring)|Adds a new string, passed as a resource ID, to the toolbar's internal list of strings.| -|[CToolBarCtrl::AddStrings](#addstrings)|Adds a new string or strings, passed as a pointer to a buffer of null-separated strings, to the toolbar's internal list of strings.| -|[CToolBarCtrl::AutoSize](#autosize)|Resizes a toolbar control.| -|[CToolBarCtrl::ChangeBitmap](#changebitmap)|Changes the bitmap for a button in the current toolbar control.| -|[CToolBarCtrl::CheckButton](#checkbutton)|Checks or clears a given button in a toolbar control.| -|[CToolBarCtrl::CommandToIndex](#commandtoindex)|Retrieves the zero-based index for the button associated with the specified command identifier.| -|[CToolBarCtrl::Create](#create)|Creates a toolbar control and attaches it to a `CToolBarCtrl` object.| -|[CToolBarCtrl::CreateEx](#createex)|Creates a toolbar control with the specified Windows extended styles and attaches it to a `CToolBarCtrl` object.| -|[CToolBarCtrl::Customize](#customize)|Displays the Customize Toolbar dialog box.| -|[CToolBarCtrl::DeleteButton](#deletebutton)|Deletes a button from the toolbar control.| -|[CToolBarCtrl::EnableButton](#enablebutton)|Enables or disables the specified button in a toolbar control.| -|[CToolBarCtrl::GetAnchorHighlight](#getanchorhighlight)|Retrieves the anchor highlight setting for a toolbar.| -|[CToolBarCtrl::GetBitmap](#getbitmap)|Retrieves the index of the bitmap associated with a button in a toolbar.| -|[CToolBarCtrl::GetBitmapFlags](#getbitmapflags)|Gets flags associated with the toolbar's bitmap.| -|[CToolBarCtrl::GetButton](#getbutton)|Retrieves information about the specified button in a toolbar control.| -|[CToolBarCtrl::GetButtonCount](#getbuttoncount)|Retrieves a count of the buttons currently in the toolbar control.| -|[CToolBarCtrl::GetButtonInfo](#getbuttoninfo)|Retrieves the information for a button in a toolbar.| -|[CToolBarCtrl::GetButtonSize](#getbuttonsize)|Retrieves the current width and height of toolbar buttons, in pixels.| -|[CToolBarCtrl::GetColorScheme](#getcolorscheme)|Retrieves the color scheme of the current toolbar control.| -|[CToolBarCtrl::GetDisabledImageList](#getdisabledimagelist)|Retrieves the image list that a toolbar control uses to display disabled buttons.| -|[CToolBarCtrl::GetDropTarget](#getdroptarget)|Retrieves the [IDropTarget](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface for a toolbar control.| -|[CToolBarCtrl::GetExtendedStyle](#getextendedstyle)|Retrieves the extended styles for a toolbar control.| -|[CToolBarCtrl::GetHotImageList](#gethotimagelist)|Retrieves the image list that a toolbar control uses to display "hot" buttons. A hot button appears highlighted when the mouse pointer is above it.| -|[CToolBarCtrl::GetHotItem](#gethotitem)|Retrieves the index of the hot item in a toolbar.| -|[CToolBarCtrl::GetImageList](#getimagelist)|Retrieves the image list that a toolbar control uses to display buttons in their default state.| -|[CToolBarCtrl::GetInsertMark](#getinsertmark)|Retrieves the current insertion mark for the toolbar.| -|[CToolBarCtrl::GetInsertMarkColor](#getinsertmarkcolor)|Retrieves the color used to draw the insertion mark for the toolbar.| -|[CToolBarCtrl::GetItemRect](#getitemrect)|Retrieves the bounding rectangle of a button in a toolbar control.| -|[CToolBarCtrl::GetMaxSize](#getmaxsize)|Retrieves the total size of all of the visible buttons and separators in the toolbar.| -|[CToolBarCtrl::GetMaxTextRows](#getmaxtextrows)|Retrieves the maximum number of text rows displayed on a toolbar button.| -|[CToolBarCtrl::GetMetrics](#getmetrics)|Retrieves the metrics of a toolbar control.| -|[CToolBarCtrl::GetPadding](#getpadding)|Retrieves the horizontal and vertical padding of the current toolbar control.| -|[CToolBarCtrl::GetPressedImageList](#getpressedimagelist)|Retrieves the image list that the current toolbar control uses to represent buttons in the pressed state.| -|[CToolBarCtrl::GetRect](#getrect)|Retrieves the bounding rectangle for a specified toolbar button.| -|[CToolBarCtrl::GetRows](#getrows)|Retrieves the number of rows of buttons currently displayed in the toolbar.| -|[CToolBarCtrl::GetState](#getstate)|Retrieves information about the state of the specified button in a toolbar control, such as whether it is enabled, pressed, or checked.| -|[CToolBarCtrl::GetString](#getstring)|Retrieves a toolbar string.| -|[CToolBarCtrl::GetStyle](#getstyle)|Retrieves the styles currently in use for a toolbar control.| -|[CToolBarCtrl::GetToolTips](#gettooltips)|Retrieves the handle of the tool tip control, if any, associated with the toolbar control.| -|[CToolBarCtrl::HideButton](#hidebutton)|Hides or shows the specified button in a toolbar control.| -|[CToolBarCtrl::HitTest](#hittest)|Determines where a point lies in a toolbar control.| -|[CToolBarCtrl::Indeterminate](#indeterminate)|Sets or clears the indeterminate (gray) state of the specified button in a toolbar control.| -|[CToolBarCtrl::InsertButton](#insertbutton)|Inserts a button in a toolbar control.| -|[CToolBarCtrl::InsertMarkHitTest](#insertmarkhittest)|Retrieves the insertion mark information for a point in a toolbar.| -|[CToolBarCtrl::IsButtonChecked](#isbuttonchecked)|Tells whether the specified button in a toolbar control is checked.| -|[CToolBarCtrl::IsButtonEnabled](#isbuttonenabled)|Tells whether the specified button in a toolbar control is enabled.| -|[CToolBarCtrl::IsButtonHidden](#isbuttonhidden)|Tells whether the specified button in a toolbar control is hidden.| -|[CToolBarCtrl::IsButtonHighlighted](#isbuttonhighlighted)|Checks the highlight state of the toolbar button.| -|[CToolBarCtrl::IsButtonIndeterminate](#isbuttonindeterminate)|Tells whether the state of the specified button in a toolbar control is indeterminate (gray).| -|[CToolBarCtrl::IsButtonPressed](#isbuttonpressed)|Tells whether the specified button in a toolbar control is pressed.| -|[CToolBarCtrl::LoadImages](#loadimages)|Loads bitmaps into a toolbar control's image list.| -|[CToolBarCtrl::MapAccelerator](#mapaccelerator)|Maps an accelerator character to a toolbar button.| -|[CToolBarCtrl::MarkButton](#markbutton)|Sets the highlight state of a given button in a toolbar control.| -|[CToolBarCtrl::MoveButton](#movebutton)|Moves a button from one index to another.| -|[CToolBarCtrl::PressButton](#pressbutton)|Presses or releases the specified button in a toolbar control.| -|[CToolBarCtrl::ReplaceBitmap](#replacebitmap)|Replaces the existing bitmap in the current toolbar control with a new bitmap.| -|[CToolBarCtrl::RestoreState](#restorestate)|Restores the state of the toolbar control.| -|[CToolBarCtrl::SaveState](#savestate)|Saves the state of the toolbar control.| -|[CToolBarCtrl::SetAnchorHighlight](#setanchorhighlight)|Sets the anchor highlight setting for a toolbar.| -|[CToolBarCtrl::SetBitmapSize](#setbitmapsize)|Sets the size of the bitmapped images to be added to a toolbar control.| -|[CToolBarCtrl::SetButtonInfo](#setbuttoninfo)|Sets the information for an existing button in a toolbar.| -|[CToolBarCtrl::SetButtonSize](#setbuttonsize)|Sets the size of the buttons to be added to a toolbar control.| -|[CToolBarCtrl::SetButtonStructSize](#setbuttonstructsize)|Specifies the size of the `TBBUTTON` structure.| -|[CToolBarCtrl::SetButtonWidth](#setbuttonwidth)|Sets the minimum and maximum button widths in the toolbar control.| -|[CToolBarCtrl::SetCmdID](#setcmdid)|Sets the command identifier to be sent to the owner window when the specified button is pressed.| -|[CToolBarCtrl::SetColorScheme](#setcolorscheme)|Sets the color scheme of the current toolbar control.| -|[CToolBarCtrl::SetDisabledImageList](#setdisabledimagelist)|Sets the image list that the toolbar control will use to display disabled buttons.| -|[CToolBarCtrl::SetDrawTextFlags](#setdrawtextflags)|Sets the flags in the Win32 function [DrawText](/windows/win32/api/winuser/nf-winuser-drawtext), which is used to draw the text in the specified rectangle, formatted according to how the flags are set.| -|[CToolBarCtrl::SetExtendedStyle](#setextendedstyle)|Sets the extended styles for a toolbar control.| -|[CToolBarCtrl::SetHotImageList](#sethotimagelist)|Sets the image list that the toolbar control will use to display "hot" buttons.| -|[CToolBarCtrl::SetHotItem](#sethotitem)|Sets the hot item in a toolbar.| -|[CToolBarCtrl::SetImageList](#setimagelist)|Sets the image list that the toolbar will use to display buttons that are in their default state.| -|[CToolBarCtrl::SetIndent](#setindent)|Sets the indentation for the first button in a toolbar control.| -|[CToolBarCtrl::SetInsertMark](#setinsertmark)|Sets the current insertion mark for the toolbar.| -|[CToolBarCtrl::SetInsertMarkColor](#setinsertmarkcolor)|Sets the color used to draw the insertion mark for the toolbar.| -|[CToolBarCtrl::SetMaxTextRows](#setmaxtextrows)|Sets the maximum number of text rows displayed on a toolbar button.| -|[CToolBarCtrl::SetMetrics](#setmetrics)|Sets the metrics of a toolbar control.| -|[CToolBarCtrl::SetOwner](#setowner)|Sets the window to receive notification messages from the toolbar control.| -|[CToolBarCtrl::SetPadding](#setpadding)|Sets the horizontal and vertical padding of the current toolbar control.| -|[CToolBarCtrl::SetPressedImageList](#setpressedimagelist)|Sets the image list that the current toolbar control uses to represent buttons in the pressed state.| -|[CToolBarCtrl::SetRows](#setrows)|Sets the number of rows of buttons displayed in the toolbar.| -|[CToolBarCtrl::SetState](#setstate)|Sets the state for the specified button in a toolbar control.| -|[CToolBarCtrl::SetStyle](#setstyle)|Sets the styles for a toolbar control.| -|[CToolBarCtrl::SetToolTips](#settooltips)|Associates a tool tip control with the toolbar control.| -|[CToolBarCtrl::SetWindowTheme](#setwindowtheme)|Sets the visual style of a toolbar control.| +|[`CToolBarCtrl::AddBitmap`](#addbitmap)|Adds one or more bitmap button images to the list of button images available for a toolbar control.| +|[`CToolBarCtrl::AddButtons`](#addbuttons)|Adds one or more buttons to a toolbar control.| +|[`CToolBarCtrl::AddString`](#addstring)|Adds a new string, passed as a resource ID, to the toolbar's internal list of strings.| +|[`CToolBarCtrl::AddStrings`](#addstrings)|Adds a new string or strings, passed as a pointer to a buffer of `NULL`-separated strings, to the toolbar's internal list of strings.| +|[`CToolBarCtrl::AutoSize`](#autosize)|Resizes a toolbar control.| +|[`CToolBarCtrl::ChangeBitmap`](#changebitmap)|Changes the bitmap for a button in the current toolbar control.| +|[`CToolBarCtrl::CheckButton`](#checkbutton)|Checks or clears a given button in a toolbar control.| +|[`CToolBarCtrl::CommandToIndex`](#commandtoindex)|Retrieves the zero-based index for the button associated with the specified command identifier.| +|[`CToolBarCtrl::Create`](#create)|Creates a toolbar control and attaches it to a `CToolBarCtrl` object.| +|[`CToolBarCtrl::CreateEx`](#createex)|Creates a toolbar control with the specified Windows extended styles and attaches it to a `CToolBarCtrl` object.| +|[`CToolBarCtrl::Customize`](#customize)|Displays the Customize Toolbar dialog box.| +|[`CToolBarCtrl::DeleteButton`](#deletebutton)|Deletes a button from the toolbar control.| +|[`CToolBarCtrl::EnableButton`](#enablebutton)|Enables or disables the specified button in a toolbar control.| +|[`CToolBarCtrl::GetAnchorHighlight`](#getanchorhighlight)|Retrieves the anchor highlight setting for a toolbar.| +|[`CToolBarCtrl::GetBitmap`](#getbitmap)|Retrieves the index of the bitmap associated with a button in a toolbar.| +|[`CToolBarCtrl::GetBitmapFlags`](#getbitmapflags)|Gets flags associated with the toolbar's bitmap.| +|[`CToolBarCtrl::GetButton`](#getbutton)|Retrieves information about the specified button in a toolbar control.| +|[`CToolBarCtrl::GetButtonCount`](#getbuttoncount)|Retrieves a count of the buttons currently in the toolbar control.| +|[`CToolBarCtrl::GetButtonInfo`](#getbuttoninfo)|Retrieves the information for a button in a toolbar.| +|[`CToolBarCtrl::GetButtonSize`](#getbuttonsize)|Retrieves the current width and height of toolbar buttons, in pixels.| +|[`CToolBarCtrl::GetColorScheme`](#getcolorscheme)|Retrieves the color scheme of the current toolbar control.| +|[`CToolBarCtrl::GetDisabledImageList`](#getdisabledimagelist)|Retrieves the image list that a toolbar control uses to display disabled buttons.| +|[`CToolBarCtrl::GetDropTarget`](#getdroptarget)|Retrieves the [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface for a toolbar control.| +|[`CToolBarCtrl::GetExtendedStyle`](#getextendedstyle)|Retrieves the extended styles for a toolbar control.| +|[`CToolBarCtrl::GetHotImageList`](#gethotimagelist)|Retrieves the image list that a toolbar control uses to display "hot" buttons. A hot button appears highlighted when the mouse pointer is above it.| +|[`CToolBarCtrl::GetHotItem`](#gethotitem)|Retrieves the index of the hot item in a toolbar.| +|[`CToolBarCtrl::GetImageList`](#getimagelist)|Retrieves the image list that a toolbar control uses to display buttons in their default state.| +|[`CToolBarCtrl::GetInsertMark`](#getinsertmark)|Retrieves the current insertion mark for the toolbar.| +|[`CToolBarCtrl::GetInsertMarkColor`](#getinsertmarkcolor)|Retrieves the color used to draw the insertion mark for the toolbar.| +|[`CToolBarCtrl::GetItemRect`](#getitemrect)|Retrieves the bounding rectangle of a button in a toolbar control.| +|[`CToolBarCtrl::GetMaxSize`](#getmaxsize)|Retrieves the total size of all of the visible buttons and separators in the toolbar.| +|[`CToolBarCtrl::GetMaxTextRows`](#getmaxtextrows)|Retrieves the maximum number of text rows displayed on a toolbar button.| +|[`CToolBarCtrl::GetMetrics`](#getmetrics)|Retrieves the metrics of a toolbar control.| +|[`CToolBarCtrl::GetPadding`](#getpadding)|Retrieves the horizontal and vertical padding of the current toolbar control.| +|[`CToolBarCtrl::GetPressedImageList`](#getpressedimagelist)|Retrieves the image list that the current toolbar control uses to represent buttons in the pressed state.| +|[`CToolBarCtrl::GetRect`](#getrect)|Retrieves the bounding rectangle for a specified toolbar button.| +|[`CToolBarCtrl::GetRows`](#getrows)|Retrieves the number of rows of buttons currently displayed in the toolbar.| +|[`CToolBarCtrl::GetState`](#getstate)|Retrieves information about the state of the specified button in a toolbar control, such as whether it's enabled, pressed, or checked.| +|[`CToolBarCtrl::GetString`](#getstring)|Retrieves a toolbar string.| +|[`CToolBarCtrl::GetStyle`](#getstyle)|Retrieves the styles currently in use for a toolbar control.| +|[`CToolBarCtrl::GetToolTips`](#gettooltips)|Retrieves the handle of the tool tip control, if any, associated with the toolbar control.| +|[`CToolBarCtrl::HideButton`](#hidebutton)|Hides or shows the specified button in a toolbar control.| +|[`CToolBarCtrl::HitTest`](#hittest)|Determines where a point lies in a toolbar control.| +|[`CToolBarCtrl::Indeterminate`](#indeterminate)|Sets or clears the indeterminate (gray) state of the specified button in a toolbar control.| +|[`CToolBarCtrl::InsertButton`](#insertbutton)|Inserts a button in a toolbar control.| +|[`CToolBarCtrl::InsertMarkHitTest`](#insertmarkhittest)|Retrieves the insertion mark information for a point in a toolbar.| +|[`CToolBarCtrl::IsButtonChecked`](#isbuttonchecked)|Tells whether the specified button in a toolbar control is checked.| +|[`CToolBarCtrl::IsButtonEnabled`](#isbuttonenabled)|Tells whether the specified button in a toolbar control is enabled.| +|[`CToolBarCtrl::IsButtonHidden`](#isbuttonhidden)|Tells whether the specified button in a toolbar control is hidden.| +|[`CToolBarCtrl::IsButtonHighlighted`](#isbuttonhighlighted)|Checks the highlight state of the toolbar button.| +|[`CToolBarCtrl::IsButtonIndeterminate`](#isbuttonindeterminate)|Tells whether the state of the specified button in a toolbar control is indeterminate (gray).| +|[`CToolBarCtrl::IsButtonPressed`](#isbuttonpressed)|Tells whether the specified button in a toolbar control is pressed.| +|[`CToolBarCtrl::LoadImages`](#loadimages)|Loads bitmaps into a toolbar control's image list.| +|[`CToolBarCtrl::MapAccelerator`](#mapaccelerator)|Maps an accelerator character to a toolbar button.| +|[`CToolBarCtrl::MarkButton`](#markbutton)|Sets the highlight state of a given button in a toolbar control.| +|[`CToolBarCtrl::MoveButton`](#movebutton)|Moves a button from one index to another.| +|[`CToolBarCtrl::PressButton`](#pressbutton)|Presses or releases the specified button in a toolbar control.| +|[`CToolBarCtrl::ReplaceBitmap`](#replacebitmap)|Replaces the existing bitmap in the current toolbar control with a new bitmap.| +|[`CToolBarCtrl::RestoreState`](#restorestate)|Restores the state of the toolbar control.| +|[`CToolBarCtrl::SaveState`](#savestate)|Saves the state of the toolbar control.| +|[`CToolBarCtrl::SetAnchorHighlight`](#setanchorhighlight)|Sets the anchor highlight setting for a toolbar.| +|[`CToolBarCtrl::SetBitmapSize`](#setbitmapsize)|Sets the size of the bitmapped images to be added to a toolbar control.| +|[`CToolBarCtrl::SetButtonInfo`](#setbuttoninfo)|Sets the information for an existing button in a toolbar.| +|[`CToolBarCtrl::SetButtonSize`](#setbuttonsize)|Sets the size of the buttons to be added to a toolbar control.| +|[`CToolBarCtrl::SetButtonStructSize`](#setbuttonstructsize)|Specifies the size of the `TBBUTTON` structure.| +|[`CToolBarCtrl::SetButtonWidth`](#setbuttonwidth)|Sets the minimum and maximum button widths in the toolbar control.| +|[`CToolBarCtrl::SetCmdID`](#setcmdid)|Sets the command identifier to be sent to the owner window when the specified button is pressed.| +|[`CToolBarCtrl::SetColorScheme`](#setcolorscheme)|Sets the color scheme of the current toolbar control.| +|[`CToolBarCtrl::SetDisabledImageList`](#setdisabledimagelist)|Sets the image list that the toolbar control will use to display disabled buttons.| +|[`CToolBarCtrl::SetDrawTextFlags`](#setdrawtextflags)|Sets the flags in the Win32 function [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext), which is used to draw the text in the specified rectangle, formatted according to how the flags are set.| +|[`CToolBarCtrl::SetExtendedStyle`](#setextendedstyle)|Sets the extended styles for a toolbar control.| +|[`CToolBarCtrl::SetHotImageList`](#sethotimagelist)|Sets the image list that the toolbar control will use to display "hot" buttons.| +|[`CToolBarCtrl::SetHotItem`](#sethotitem)|Sets the hot item in a toolbar.| +|[`CToolBarCtrl::SetImageList`](#setimagelist)|Sets the image list that the toolbar will use to display buttons that are in their default state.| +|[`CToolBarCtrl::SetIndent`](#setindent)|Sets the indentation for the first button in a toolbar control.| +|[`CToolBarCtrl::SetInsertMark`](#setinsertmark)|Sets the current insertion mark for the toolbar.| +|[`CToolBarCtrl::SetInsertMarkColor`](#setinsertmarkcolor)|Sets the color used to draw the insertion mark for the toolbar.| +|[`CToolBarCtrl::SetMaxTextRows`](#setmaxtextrows)|Sets the maximum number of text rows displayed on a toolbar button.| +|[`CToolBarCtrl::SetMetrics`](#setmetrics)|Sets the metrics of a toolbar control.| +|[`CToolBarCtrl::SetOwner`](#setowner)|Sets the window to receive notification messages from the toolbar control.| +|[`CToolBarCtrl::SetPadding`](#setpadding)|Sets the horizontal and vertical padding of the current toolbar control.| +|[`CToolBarCtrl::SetPressedImageList`](#setpressedimagelist)|Sets the image list that the current toolbar control uses to represent buttons in the pressed state.| +|[`CToolBarCtrl::SetRows`](#setrows)|Sets the number of rows of buttons displayed in the toolbar.| +|[`CToolBarCtrl::SetState`](#setstate)|Sets the state for the specified button in a toolbar control.| +|[`CToolBarCtrl::SetStyle`](#setstyle)|Sets the styles for a toolbar control.| +|[`CToolBarCtrl::SetToolTips`](#settooltips)|Associates a tool tip control with the toolbar control.| +|[`CToolBarCtrl::SetWindowTheme`](#setwindowtheme)|Sets the visual style of a toolbar control.| ## Remarks @@ -122,55 +121,55 @@ This control (and therefore the `CToolBarCtrl` class) is available only to progr A Windows toolbar common control is a rectangular child window that contains one or more buttons. These buttons can display a bitmap image, a string, or both. When the user chooses a button, it sends a command message to the toolbar's owner window. Typically, the buttons in a toolbar correspond to items in the application's menu; they provide a more direct way for the user to access an application's commands. -`CToolBarCtrl` objects contain several important internal data structures: a list of button image bitmaps or an image list, a list of button label strings, and a list of `TBBUTTON` structures which associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a `CToolBarCtrl` object, you must set up these data structures. The list of strings can only be used for button labels; you cannot retrieve strings from the toolbar. +`CToolBarCtrl` objects contain several important internal data structures: a list of button image bitmaps or an image list, a list of button label strings, and a list of `TBBUTTON` structures that associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a `CToolBarCtrl` object, you must set up these data structures. The list of strings can only be used for button labels; you can't retrieve strings from the toolbar. -To use a `CToolBarCtrl` object, you will typically follow these steps: +To use a `CToolBarCtrl` object, you'll typically follow these steps: 1. Construct the `CToolBarCtrl` object. -1. Call [Create](#create) to create the Windows toolbar common control and attach it to the `CToolBarCtrl` object. Indicate the style of toolbar by using styles, such as TBSTYLE_TRANSPARENT for a transparent toolbar or TBSTYLE_DROPDOWN for a toolbar that supports drop-down style buttons. +1. Call [`Create`](#create) to create the Windows toolbar common control and attach it to the `CToolBarCtrl` object. Indicate the style of toolbar by using styles, such as `TBSTYLE_TRANSPARENT` for a transparent toolbar or `TBSTYLE_DROPDOWN` for a toolbar that supports drop-down style buttons. 1. Identify how you want the buttons on the toolbar displayed: - - To use bitmap images for buttons, add the button bitmaps to the toolbar by calling [AddBitmap](#addbitmap). + - To use bitmap images for buttons, add the button bitmaps to the toolbar by calling [`AddBitmap`](#addbitmap). - - To use images displayed from an image list for buttons, specify the image list by calling [SetImageList](#setimagelist), [SetHotImageList](#sethotimagelist), or [SetDisabledImageList](#setdisabledimagelist). + - To use images displayed from an image list for buttons, specify the image list by calling [`SetImageList`](#setimagelist), [`SetHotImageList`](#sethotimagelist), or [`SetDisabledImageList`](#setdisabledimagelist). - - To use string labels for buttons, add the strings to the toolbar by calling [AddString](#addstring) and/or [AddStrings](#addstrings). + - To use string labels for buttons, add the strings to the toolbar by calling [`AddString`](#addstring) and/or [`AddStrings`](#addstrings). -1. Add button structures to the toolbar by calling [AddButtons](#addbuttons). +1. Add button structures to the toolbar by calling [`AddButtons`](#addbuttons). -1. If you want tool tips for a toolbar button in an owner window that is not a `CFrameWnd`, you need to handle the TTN_NEEDTEXT messages in the toolbar's owner window as described in [Handling Tool Tip Notifications](../../mfc/handling-tool-tip-notifications.md). If the parent window of the toolbar is derived from `CFrameWnd`, tool tips are displayed without any extra effort from you because `CFrameWnd` provides a default handler. +1. If you want tool tips for a toolbar button in an owner window that isn't a `CFrameWnd`, you need to handle the `TTN_NEEDTEXT` messages in the toolbar's owner window as described in [Handling Tool Tip Notifications](../../mfc/handling-tool-tip-notifications.md). If the parent window of the toolbar is derived from `CFrameWnd`, tool tips are displayed without any extra effort from you because `CFrameWnd` provides a default handler. 1. If you want your user to be able to customize the toolbar, handle customization notification messages in the owner window as described in [Handling Customization Notifications](../../mfc/handling-customization-notifications.md). -You can use [SaveState](#savestate) to save the current state of a toolbar control in the registry and [RestoreState](#restorestate) to restore the state based on information previously stored in the registry. In addition to saving the toolbar state between uses of the application, applications typically store the state before the user begins customizing the toolbar in case the user later wants to restore the toolbar to its original state. +You can use [`SaveState`](#savestate) to save the current state of a toolbar control in the registry and [`RestoreState`](#restorestate) to restore the state based on information previously stored in the registry. In addition to saving the toolbar state between uses of the application, applications typically store the state before the user begins customizing the toolbar in case the user later wants to restore the toolbar to its original state. ## Support for Internet Explorer Version 4.0 and Later To support functionality introduced in Internet Explorer, version 4.0 and later, MFC provides image list support and transparent and flat styles for toolbar controls. -A transparent toolbar allows the client under the toolbar to show through. To create a transparent toolbar, use both TBSTYLE_FLAT and TBSTYLE_TRANSPARENT styles. Transparent toolbars feature hot tracking; that is, when the mouse pointer moves over a hot button on the toolbar, the button's appearance changes. Toolbars created with just the TBSTYLE_FLAT style will contain buttons that are not transparent. +A transparent toolbar allows the client under the toolbar to show through. To create a transparent toolbar, use both `TBSTYLE_FLAT` and `TBSTYLE_TRANSPARENT` styles. Transparent toolbars feature hot tracking; that is, when the mouse pointer moves over a hot button on the toolbar, the button's appearance changes. Toolbars created with just the `TBSTYLE_FLAT` style will contain buttons that aren't transparent. -Image list support allows a control greater flexibility for default behavior, hot images, and disabled images. Use [GetImageList](#getimagelist), [GetHotImageList](#gethotimagelist), and [GetDisabledImageList](#getdisabledimagelist) with the transparent toolbar to manipulate the image according to its state: +Image list support allows a control greater flexibility for default behavior, hot images, and disabled images. Use [`GetImageList`](#getimagelist), [`GetHotImageList`](#gethotimagelist), and [`GetDisabledImageList`](#getdisabledimagelist) with the transparent toolbar to manipulate the image according to its state: -For more information on using `CToolBarCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using CToolBarCtrl](../../mfc/using-ctoolbarctrl.md). +For more information on using `CToolBarCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using `CToolBarCtrl`](../../mfc/using-ctoolbarctrl.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CToolBarCtrl` ## Requirements -**Header:** afxcmn.h +**Header:** `afxcmn.h` -## CToolBarCtrl::AddBitmap +## `CToolBarCtrl::AddBitmap` Adds one or more button images to the list of button images stored in the toolbar control. @@ -186,13 +185,13 @@ int AddBitmap( ### Parameters -*nNumButtons*
+*`nNumButtons`*\ Number of button images in the bitmap. -*nBitmapID*
+*`nBitmapID`*\ Resource identifier of the bitmap that contains the button image or images to add. -*pBitmap*
+*`pBitmap`*\ Pointer to the `CBitmap` object that contains the button image or images to add. ### Return Value @@ -201,9 +200,9 @@ Zero-based index of the first new image if successful; otherwise - 1. ### Remarks -You can use the Windows API [CreateMappedBitmap](/windows/win32/api/commctrl/nf-commctrl-createmappedbitmap) to map colors before adding the bitmap to the toolbar. If you pass a pointer to a `CBitMap` object, you must ensure that the bitmap is not destroyed until after the toolbar is destroyed. +You can use the Windows API [`CreateMappedBitmap`](/windows/win32/api/commctrl/nf-commctrl-createmappedbitmap) to map colors before adding the bitmap to the toolbar. If you pass a pointer to a `CBitMap` object, you must ensure that the bitmap isn't destroyed until after the toolbar is destroyed. -## CToolBarCtrl::AddButtons +## `CToolBarCtrl::AddButtons` Adds one or more buttons to a toolbar control. @@ -215,11 +214,11 @@ BOOL AddButtons( ### Parameters -*nNumButtons*
+*`nNumButtons`*\ Number of buttons to add. -*lpButtons*
-Address of an array of `TBBUTTON` structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by *nNumButtons*. +*`lpButtons`*\ +Address of an array of `TBBUTTON` structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by *`nNumButtons`*. ### Return Value @@ -227,7 +226,7 @@ Nonzero if successful; otherwise zero. ### Remarks -The *lpButtons* pointer points to an array of `TBBUTTON` structures. Each `TBBUTTON` structure associates the button being added with the button's style, image and/or string, command ID, state, and user-defined data: +The *`lpButtons`* pointer points to an array of `TBBUTTON` structures. Each `TBBUTTON` structure associates the button being added with the button's style, image and/or string, command ID, state, and user-defined data: ```cpp typedef struct _TBBUTTON { @@ -248,37 +247,37 @@ The members are as follows: - `idCommand` - Command identifier associated with the button. This identifier is sent in a WM_COMMAND message when the button is chosen. If the `fsStyle` member has the TBSTYLE_SEP value, this member must be zero. + Command identifier associated with the button. This identifier is sent in a `WM_COMMAND` message when the button is chosen. If the `fsStyle` member has the `TBSTYLE_SEP` value, this member must be zero. - `fsState` Button state flags. It can be a combination of the values listed below: - - TBSTATE_CHECKED The button has the TBSTYLE_CHECKED style and is being pressed. + - `TBSTATE_CHECKED` The button has the `TBSTYLE_CHECKED` style and is being pressed. - - TBSTATE_ENABLED The button accepts user input. A button that does not have this state does not accept user input and is grayed. + - `TBSTATE_ENABLED` The button accepts user input. A button that doesn't have this state doesn't accept user input and is grayed. - - TBSTATE_HIDDEN The button is not visible and cannot receive user input. + - `TBSTATE_HIDDEN` The button isn't visible and can't receive user input. - - TBSTATE_INDETERMINATE The button is grayed. + - `TBSTATE_INDETERMINATE` The button is grayed. - - TBSTATE_PRESSED The button is being pressed. + - `TBSTATE_PRESSED` The button is being pressed. - - TBSTATE_WRAP A line break follows the button. The button must also have the TBSTATE_ENABLED state. + - `TBSTATE_WRAP` A line break follows the button. The button must also have the `TBSTATE_ENABLED` state. - `fsStyle` Button style. It can be a combination of the values listed below: - - TBSTYLE_BUTTON Creates a standard push button. + - `TBSTYLE_BUTTON` Creates a standard push button. - - TBSTYLE_CHECK Creates a button that toggles between the pressed and unpressed states each time the user clicks it. The button has a different background color when it is in the pressed state. + - `TBSTYLE_CHECK` Creates a button that toggles between the pressed and unpressed states each time the user clicks it. The button has a different background color when it is in the pressed state. - - TBSTYLE_CHECKGROUP Creates a check button that stays pressed until another button in the group is pressed. + - `TBSTYLE_CHECKGROUP` Creates a check button that stays pressed until another button in the group is pressed. - - TBSTYLE_GROUP Creates a button that stays pressed until another button in the group is pressed. + - `TBSTYLE_GROUP` Creates a button that stays pressed until another button in the group is pressed. - - TBSTYLE_SEP Creates a separator, providing a small gap between button groups. A button that has this style does not receive user input. + - `TBSTYLE_SEP` Creates a separator, providing a small gap between button groups. A button that has this style doesn't receive user input. - `dwData` @@ -286,11 +285,11 @@ The members are as follows: - `iString` - Zero-based index of the string to use as the button's label, -1 if there is no string for this button. + Zero-based index of the string to use as the button's label, -1 if there's no string for this button. -The image and/or string whose index you provide must have previously been added to the toolbar control's list using [AddBitmap](#addbitmap), [AddString](#addstring), and/or [AddStrings](#addstrings). +The image and/or string whose index you provide must have previously been added to the toolbar control's list using [`AddBitmap`](#addbitmap), [`AddString`](#addstring), and/or [`AddStrings`](#addstrings). -## CToolBarCtrl::AddString +## `CToolBarCtrl::AddString` Adds a new string, passed as a resource ID, to the toolbar's internal list of strings. @@ -300,14 +299,14 @@ int AddString(UINT nStringID); ### Parameters -*nStringID*
+*`nStringID`*\ Resource identifier of the string resource to add to the toolbar control's string list. ### Return Value The zero-based index of the first new string added if successful; otherwise -1. -## CToolBarCtrl::AddStrings +## `CToolBarCtrl::AddStrings` Adds a new string or strings to the list of strings available for a toolbar control. @@ -317,8 +316,8 @@ int AddStrings(LPCTSTR lpszStrings); ### Parameters -*lpszStrings*
-Address of a buffer that contains one or more null-terminated strings to add to the toolbar's string list. The last string must be terminated with two null characters. +*`lpszStrings`*\ +Address of a buffer that contains one or more `NULL`-terminated strings to add to the toolbar's string list. The last string must be terminated with two `NULL` characters. ### Return Value @@ -326,7 +325,7 @@ The zero-based index of the first new string added if successful; otherwise -1. ### Remarks -Strings in the buffer must be separated by a null character. You must ensure that the last string has two null terminators. To properly format a constant string, you might write it as: +Strings in the buffer must be separated by a `NULL` character. You must ensure that the last string has two `NULL` terminators. To properly format a constant string, you might write it as: [!code-cpp[NVC_MFCControlLadenDialog#72](../../mfc/codesnippet/cpp/ctoolbarctrl-class_1.cpp)] @@ -334,9 +333,9 @@ or: [!code-cpp[NVC_MFCControlLadenDialog#73](../../mfc/codesnippet/cpp/ctoolbarctrl-class_2.cpp)] -You should not pass a `CString` object to this function since it is not possible to have more than one null character in a `CString`. +You shouldn't pass a `CString` object to this function since it isn't possible to have more than one `NULL` character in a `CString`. -## CToolBarCtrl::AutoSize +## `CToolBarCtrl::AutoSize` Resizes the entire toolbar control. @@ -348,7 +347,7 @@ void AutoSize(); You should call this function when the size of the parent window changes or when the size of the toolbar changes (such as when you set the button or bitmap size, or add strings). -## CToolBarCtrl::ChangeBitmap +## `CToolBarCtrl::ChangeBitmap` Changes the bitmap for a button in the current toolbar control. @@ -360,21 +359,21 @@ BOOL ChangeBitmap( ### Parameters -*idButton*\ +*`idButton`*\ [in] Command identifier of the button that is to receive a new bitmap. -*iBitmap*\ +*`iBitmap`*\ [in] Zero-based index of an image in the current toolbar control's image list. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks If this method is successful, the system displays the specified image in the specified button. -This method sends the [TB_CHANGEBITMAP](/windows/win32/Controls/tb-changebitmap) message, which is described in the Windows SDK. +This method sends the [`TB_CHANGEBITMAP`](/windows/win32/Controls/tb-changebitmap) message, which is described in the Windows SDK. ### Example @@ -382,7 +381,7 @@ The following code example changes the bitmap for the **File Save** button to th [!code-cpp[NVC_MFC_CToolBarCtrl_s1#1](../../mfc/reference/codesnippet/cpp/ctoolbarctrl-class_3.cpp)] -## CToolBarCtrl::CheckButton +## `CToolBarCtrl::CheckButton` Checks or clears a given button in a toolbar control. @@ -394,11 +393,11 @@ BOOL CheckButton( ### Parameters -*nID*
+*`nID`*\ Command identifier of the button to check or clear. -*bCheck*
-TRUE to check the button, FALSE to clear it. +*`bCheck`*\ +`TRUE` to check the button, `FALSE` to clear it. ### Return Value @@ -406,9 +405,9 @@ Nonzero if successful; otherwise zero. ### Remarks -When a button has been checked, it appears to have been pressed. If you want to change more than one button state, consider calling [SetState](#setstate) instead. +When a button has been checked, it appears to have been pressed. If you want to change more than one button state, consider calling [`SetState`](#setstate) instead. -## CToolBarCtrl::CommandToIndex +## `CToolBarCtrl::CommandToIndex` Retrieves the zero-based index for the button associated with the specified command identifier. @@ -418,7 +417,7 @@ UINT CommandToIndex(UINT nID) const; ### Parameters -*nID*
+*`nID`*\ Command ID whose button index you want to find. ### Return Value @@ -427,7 +426,7 @@ The zero-based index for the button associated with the command ID. ### Remarks -## CToolBarCtrl::Create +## `CToolBarCtrl::Create` Creates a toolbar control and attaches it to a `CToolBarCtrl` object. @@ -441,43 +440,43 @@ virtual BOOL Create( ### Parameters -*dwStyle*
-Specifies the toolbar control's style. Toolbars must always have the WS_CHILD style. In addition, you can specify any combination of toolbar styles and window styles as described under **Remarks**. +*`dwStyle`*\ +Specifies the toolbar control's style. Toolbars must always have the `WS_CHILD` style. In addition, you can specify any combination of toolbar styles and window styles as described under [**Remarks**](#create-remarks). -*rect*
-Optionally specifies the toolbar control's size and position. It can be either a [CRect](../../atl-mfc-shared/reference/crect-class.md) object or a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +*`rect`*\ +Optionally specifies the toolbar control's size and position. It can be either a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -*pParentWnd*
-Specifies the toolbar control's parent window. It must not be NULL. +*`pParentWnd`*\ +Specifies the toolbar control's parent window. It must not be `NULL`. -*nID*
+*`nID`*\ Specifies the toolbar control's ID. ### Return Value Nonzero if successful; otherwise zero. -### Remarks +### Remarks You construct a `CToolBarCtrl` in two steps. First, call the constructor, and then call `Create`, which creates the toolbar control and attaches it to the `CToolBarCtrl` object. Apply the following window styles to a toolbar control. -- WS_CHILD Always +- `WS_CHILD` Always -- WS_VISIBLE Usually +- `WS_VISIBLE` Usually -- WS_DISABLED Rarely +- `WS_DISABLED` Rarely -See [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for a description of window styles. +See [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for a description of window styles. Optionally, apply a combination of [common control styles](/windows/win32/Controls/common-control-styles), as described in the Windows SDK. Apply a combination of toolbar styles to either the control or the buttons themselves. The styles are described in the topic [Toolbar Control and Button Styles](/windows/win32/Controls/toolbar-control-and-button-styles) in the Windows SDK. -To use extended toolbar styles, call [SetExtendedStyle](#setextendedstyle) after you call `Create`. To create a toolbar with extended window styles, call [CToolBarCtrl::CreateEx](#createex) instead of `Create`. +To use extended toolbar styles, call [`SetExtendedStyle`](#setextendedstyle) after you call `Create`. To create a toolbar with extended window styles, call [`CToolBarCtrl::CreateEx`](#createex) instead of `Create`. -The toolbar control automatically sets the size and position of the toolbar window. The height is based on the height of the buttons in the toolbar. The width is the same as the width of the parent window's client area. The CCS_TOP and CCS_BOTTOM styles determine whether the toolbar is positioned along the top or bottom of the client area. By default, a toolbar has the CCS_TOP style. +The toolbar control automatically sets the size and position of the toolbar window. The height is based on the height of the buttons in the toolbar. The width is the same as the width of the parent window's client area. The `CCS_TOP` and `CCS_BOTTOM` styles determine whether the toolbar is positioned along the top or bottom of the client area. By default, a toolbar has the `CCS_TOP` style. -## CToolBarCtrl::CreateEx +## `CToolBarCtrl::CreateEx` Creates a control (a child window) and associates it with the `CToolBarCtrl` object. @@ -492,19 +491,19 @@ virtual BOOL CreateEx( ### Parameters -*dwExStyle*
-Specifies the extended style of the control being created. For a list of extended Windows styles, see the *dwExStyle* parameter for [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwExStyle`*\ +Specifies the extended style of the control being created. For a list of extended Windows styles, see the *`dwExStyle`* parameter for [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. -*dwStyle*
-Specifies the toolbar control's style. Toolbars must always have the WS_CHILD style. In addition, you can specify any combination of toolbar styles and window styles as described in the **Remarks** section of [Create](#create). +*`dwStyle`*\ +Specifies the toolbar control's style. Toolbars must always have the `WS_CHILD` style. In addition, you can specify any combination of toolbar styles and window styles as described in the [**Remarks**](#create-remarks) section of [`Create`](#create). -*rect*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *pParentWnd*. +*`rect`*\ +A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *`pParentWnd`*. -*pParentWnd*
+*`pParentWnd`*\ A pointer to the window that is the control's parent. -*nID*
+*`nID`*\ The control's child-window ID. ### Return Value @@ -513,9 +512,9 @@ Nonzero if successful; otherwise 0. ### Remarks -Use `CreateEx` instead of [Create](#create) to apply extended Windows styles, specified by the Windows extended style preface **WS_EX_**. `CreateEx` creates the control with the extended Windows styles specified by *dwExStyle*. Set extended styles specific to a control using [SetExtendedStyle](#setextendedstyle). For example, use `CreateEx` to set such styles as WS_EX_CONTEXTHELP, but use `SetExtendedStyle` to set such styles as TBSTYLE_EX_DRAWDDARROWS. For more information, see the styles described in [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles) in the Windows SDK. +Use `CreateEx` instead of [`Create`](#create) to apply extended Windows styles, specified by the Windows extended style preface **`WS_EX_`**. `CreateEx` creates the control with the extended Windows styles specified by *`dwExStyle`*. Set extended styles specific to a control using [`SetExtendedStyle`](#setextendedstyle). For example, use `CreateEx` to set such styles as `WS_EX_CONTEXTHELP`, but use `SetExtendedStyle` to set such styles as `TBSTYLE_EX_DRAWDDARROWS`. For more information, see the styles described in [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles) in the Windows SDK. -## CToolBarCtrl::CToolBarCtrl +## `CToolBarCtrl::CToolBarCtrl` Constructs a `CToolBarCtrl` object. @@ -525,9 +524,9 @@ CToolBarCtrl(); ### Remarks -You must call [Create](#create) to make the toolbar usable. +You must call [`Create`](#create) to make the toolbar usable. -## CToolBarCtrl::Customize +## `CToolBarCtrl::Customize` Displays the Customize Toolbar dialog box. @@ -537,9 +536,9 @@ void Customize(); ### Remarks -This dialog box allows the user to customize the toolbar by adding and deleting buttons. To support customization, your toolbar's parent window must handle the customization notification messages as described in [Handling Customization Notifications](../../mfc/handling-customization-notifications.md). Your toolbar must also have been created with the CCS_ADJUSTABLE style, as described in [CToolBarCtrl::Create](#create). +This dialog box allows the user to customize the toolbar by adding and deleting buttons. To support customization, your toolbar's parent window must handle the customization notification messages as described in [Handling Customization Notifications](../../mfc/handling-customization-notifications.md). Your toolbar must also have been created with the `CCS_ADJUSTABLE` style, as described in [`CToolBarCtrl::Create`](#create). -## CToolBarCtrl::DeleteButton +## `CToolBarCtrl::DeleteButton` Deletes a button from the toolbar control. @@ -549,7 +548,7 @@ BOOL DeleteButton(int nIndex); ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of the button to delete. ### Return Value @@ -558,7 +557,7 @@ Nonzero if successful; otherwise zero. ### Remarks -## CToolBarCtrl::EnableButton +## `CToolBarCtrl::EnableButton` Enables or disables the specified button in a toolbar control. @@ -570,11 +569,11 @@ BOOL EnableButton( ### Parameters -*nID*
+*`nID`*\ Command identifier of the button to enable or disable. -*bEnable*
-TRUE to enable the button; FALSE to disable the button. +*`bEnable`*\ +`TRUE` to enable the button; `FALSE` to disable the button. ### Return Value @@ -582,9 +581,9 @@ Nonzero if successful; otherwise zero. ### Remarks -When a button has been enabled, it can be pressed and checked. If you want to change more than one button state, consider calling [SetState](#setstate) instead. +When a button has been enabled, it can be pressed and checked. If you want to change more than one button state, consider calling [`SetState`](#setstate) instead. -## CToolBarCtrl::GetAnchorHighlight +## `CToolBarCtrl::GetAnchorHighlight` Retrieves the anchor highlight setting for a toolbar. @@ -598,9 +597,9 @@ If nonzero, anchor highlighting is enabled. If zero, anchor highlighting is disa ### Remarks -This member function implements the behavior of the Win32 message [TB_GETANCHORHIGHLIGHT](/windows/win32/Controls/tb-getanchorhighlight), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETANCHORHIGHLIGHT`](/windows/win32/Controls/tb-getanchorhighlight), as described in the Windows SDK. -## CToolBarCtrl::GetBitmap +## `CToolBarCtrl::GetBitmap` Retrieves the index of the bitmap associated with a button in a toolbar. @@ -610,7 +609,7 @@ int GetBitmap(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button whose bitmap index is to be retrieved. ### Return Value @@ -619,9 +618,9 @@ Returns the index of the bitmap if successful, or zero otherwise. ### Remarks -Implements the functionality of [TB_GETBITMAP](/windows/win32/Controls/tb-getbitmap) in the Windows SDK. +Implements the functionality of [`TB_GETBITMAP`](/windows/win32/Controls/tb-getbitmap) in the Windows SDK. -## CToolBarCtrl::GetBitmapFlags +## `CToolBarCtrl::GetBitmapFlags` Retrieves the bitmap flags from the toolbar. @@ -631,13 +630,13 @@ UINT GetBitmapFlags() const; ### Return Value -A UINT that has the TBBF_LARGE flag set if the display can support large toolbar bitmaps, clear otherwise. +A `UINT` that has the `TBBF_LARGE` flag set if the display can support large toolbar bitmaps, clear otherwise. ### Remarks -You should call it after creating the toolbar but before adding bitmaps to the toolbar. The return value indicates whether the display supports large bitmaps or not. If the display supports large bitmaps and if you choose to use them, call [SetBitmapSize](#setbitmapsize) and [SetButtonSize](#setbuttonsize) before adding your large bitmap using [AddBitmap](#addbitmap). +You should call it after creating the toolbar but before adding bitmaps to the toolbar. The return value indicates whether the display supports large bitmaps or not. If the display supports large bitmaps and if you choose to use them, call [`SetBitmapSize`](#setbitmapsize) and [`SetButtonSize`](#setbuttonsize) before adding your large bitmap using [`AddBitmap`](#addbitmap). -## CToolBarCtrl::GetButton +## `CToolBarCtrl::GetButton` Retrieves information about the specified button in a toolbar control. @@ -649,17 +648,17 @@ BOOL GetButton( ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of the button for which to retrieve information. -*lpButton*
-Address of the `TBBUTTON` structure that is to receive a copy of the button information. See [CToolBarCtrl::AddButtons](#addbuttons) for information about the `TBBUTTON` structure. +*`lpButton`*\ +Address of the `TBBUTTON` structure that is to receive a copy of the button information. See [`CToolBarCtrl::AddButtons`](#addbuttons) for information about the `TBBUTTON` structure. ### Return Value Nonzero if successful; otherwise zero. -## CToolBarCtrl::GetButtonCount +## `CToolBarCtrl::GetButtonCount` Retrieves a count of the buttons currently in the toolbar control. @@ -671,7 +670,7 @@ int GetButtonCount() const; The count of the buttons. -## CToolBarCtrl::GetButtonInfo +## `CToolBarCtrl::GetButtonInfo` Retrieves the information for a button in a toolbar. @@ -683,11 +682,11 @@ int GetButtonInfo( ### Parameters -*nID*
+*`nID`*\ The button identifier. -*ptbbi*
-A pointer to a [TBBUTTONINFO](/windows/win32/api/commctrl/ns-commctrl-tbbuttoninfow) structure that receives the button information. +*`ptbbi`*\ +A pointer to a [`TBBUTTONINFO`](/windows/win32/api/commctrl/ns-commctrl-tbbuttoninfow) structure that receives the button information. ### Return Value @@ -695,9 +694,9 @@ The zero-based index of the button, if successful; otherwise -1. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETBUTTONINFO](/windows/win32/Controls/tb-getbuttoninfo), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETBUTTONINFO`](/windows/win32/Controls/tb-getbuttoninfo), as described in the Windows SDK. -## CToolBarCtrl::GetButtonSize +## `CToolBarCtrl::GetButtonSize` Gets the size of a toolbar button. @@ -707,9 +706,9 @@ DWORD GetButtonSize() const; ### Return Value -A DWORD value that contains the width and height values in the LOWORD and HIWORD, respectively. +A `DWORD` value that contains the width and height values in the `LOWORD` and `HIWORD`, respectively. -## CToolBarCtrl::GetButtonText +## `CToolBarCtrl::GetButtonText` Retrieves the display text of a specified button on the current toolbar control. @@ -719,18 +718,18 @@ CString GetButtonText(int idButton) const; ### Parameters -*idButton*\ +*`idButton`*\ [in] The identifier for the button whose display text is retrieved. ### Return Value -A [CString](../../atl-mfc-shared/using-cstring.md) that contains the display text of the specified button. +A [`CString`](../../atl-mfc-shared/using-cstring.md) that contains the display text of the specified button. ### Remarks -This method sends the [TB_GETBUTTONTEXT](/windows/win32/Controls/tb-getbuttontext) message, which is described in the Windows SDK. +This method sends the [`TB_GETBUTTONTEXT`](/windows/win32/Controls/tb-getbuttontext) message, which is described in the Windows SDK. -## CToolBarCtrl::GetColorScheme +## `CToolBarCtrl::GetColorScheme` Retrieves the color scheme of the current toolbar control. @@ -740,18 +739,18 @@ BOOL GetColorScheme(COLORSCHEME* lpColorScheme) const; ### Parameters -*lpColorScheme*\ -[out] Pointer to a [COLORSCHEME](/windows/win32/api/commctrl/ns-commctrl-colorscheme) structure that receives the color scheme information. When this method returns, the structure describes the highlight color and shadow color of the toolbar control. +*`lpColorScheme`*\ +[out] Pointer to a [`COLORSCHEME`](/windows/win32/api/commctrl/ns-commctrl-colorscheme) structure that receives the color scheme information. When this method returns, the structure describes the highlight color and shadow color of the toolbar control. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks -This method sends the [TB_GETCOLORSCHEME](/windows/win32/Controls/tb-getcolorscheme) message, which is described in the Windows SDK. +This method sends the [`TB_GETCOLORSCHEME`](/windows/win32/Controls/tb-getcolorscheme) message, which is described in the Windows SDK. -## CToolBarCtrl::GetDisabledImageList +## `CToolBarCtrl::GetDisabledImageList` Retrieves the image list that a toolbar control uses to display disabled buttons. @@ -761,15 +760,15 @@ CImageList* GetDisabledImageList() const; ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object, or NULL if no disabled image list is set. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object, or `NULL` if no disabled image list is set. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETDISABLEDIMAGELIST](/windows/win32/Controls/tb-getdisabledimagelist), as described in the Windows SDK. The MFC implementation of `GetDisabledImageList` uses a `CImageList` object containing the toolbar control's button images, rather than a handle to an image list. +This member function implements the behavior of the Win32 message [`TB_GETDISABLEDIMAGELIST`](/windows/win32/Controls/tb-getdisabledimagelist), as described in the Windows SDK. The MFC implementation of `GetDisabledImageList` uses a `CImageList` object containing the toolbar control's button images, rather than a handle to an image list. -## CToolBarCtrl::GetDropTarget +## `CToolBarCtrl::GetDropTarget` -Retrieves the [IDropTarget](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface for a toolbar control. +Retrieves the [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface for a toolbar control. ``` HRESULT GetDropTarget(IDropTarget** ppDropTarget) const; @@ -777,18 +776,18 @@ HRESULT GetDropTarget(IDropTarget** ppDropTarget) const; ### Parameters -*ppDropTarget*
-A pointer to an [IDropTarget](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface pointer. If an error occurs, a NULL pointer is placed in this address. +*`ppDropTarget`*\ +A pointer to an [`IDropTarget`](/windows/win32/api/oleidl/nn-oleidl-idroptarget) interface pointer. If an error occurs, a `NULL` pointer is placed in this address. ### Return Value -Returns an HRESULT value indicating success or failure of the operation. +Returns an `HRESULT` value indicating success or failure of the operation. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETOBJECT](/windows/win32/Controls/tb-getobject), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETOBJECT`](/windows/win32/Controls/tb-getobject), as described in the Windows SDK. -## CToolBarCtrl::GetExtendedStyle +## `CToolBarCtrl::GetExtendedStyle` Retrieves the extended styles for a toolbar control. @@ -798,13 +797,13 @@ DWORD GetExtendedStyle() const; ### Return Value -A DWORD that represents the extended styles currently in use for the toolbar control. For a list of styles, see [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles), in the Windows SDK. +A `DWORD` that represents the extended styles currently in use for the toolbar control. For a list of styles, see [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles), in the Windows SDK. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETEXTENDEDSTYLE](/windows/win32/Controls/tb-getextendedstyle), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETEXTENDEDSTYLE`](/windows/win32/Controls/tb-getextendedstyle), as described in the Windows SDK. -## CToolBarCtrl::GetHotImageList +## `CToolBarCtrl::GetHotImageList` Retrieves the image list that a toolbar control uses to display "hot" buttons. A hot button appears highlighted when the mouse pointer is above it. @@ -814,13 +813,13 @@ CImageList* GetHotImageList() const; ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object, or NULL if no disabled image list is set. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object, or `NULL` if no disabled image list is set. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETHOTIMAGELIST](/windows/win32/Controls/tb-gethotimagelist), as described in the Windows SDK. A hot button appears highlighted when the mouse pointer is above it. +This member function implements the behavior of the Win32 message [`TB_GETHOTIMAGELIST`](/windows/win32/Controls/tb-gethotimagelist), as described in the Windows SDK. A hot button appears highlighted when the mouse pointer is above it. -## CToolBarCtrl::GetHotItem +## `CToolBarCtrl::GetHotItem` Retrieves the index of the hot item in a toolbar. @@ -834,9 +833,9 @@ The zero-based index of the hot item in a toolbar. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETHOTITEM](/windows/win32/Controls/tb-gethotitem), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETHOTITEM`](/windows/win32/Controls/tb-gethotitem), as described in the Windows SDK. -## CToolBarCtrl::GetImageList +## `CToolBarCtrl::GetImageList` Retrieves the image list that a toolbar control uses to display buttons in their default state. @@ -846,13 +845,13 @@ CImageList* GetImageList() const; ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object, or NULL if no image list is set. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object, or `NULL` if no image list is set. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETIMAGELIST](/windows/win32/Controls/tb-getimagelist), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETIMAGELIST`](/windows/win32/Controls/tb-getimagelist), as described in the Windows SDK. -## CToolBarCtrl::GetInsertMark +## `CToolBarCtrl::GetInsertMark` Retrieves the current insertion mark for the toolbar. @@ -862,14 +861,14 @@ void GetInsertMark(TBINSERTMARK* ptbim) const; ### Parameters -*ptbim*
-A pointer to a [TBINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that receives the insertion mark. +*`ptbim`*\ +A pointer to a [`TBINSERTMARK`](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that receives the insertion mark. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETINSERTMARK](/windows/win32/Controls/tb-getinsertmark), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETINSERTMARK`](/windows/win32/Controls/tb-getinsertmark), as described in the Windows SDK. -## CToolBarCtrl::GetInsertMarkColor +## `CToolBarCtrl::GetInsertMarkColor` Retrieves the color used to draw the insertion mark for the toolbar. @@ -879,13 +878,13 @@ COLORREF GetInsertMarkColor() const; ### Return Value -A COLORREF value that contains the current insertion mark color. +A `COLORREF` value that contains the current insertion mark color. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETINSERTMARKCOLOR](/windows/win32/Controls/tb-getinsertmarkcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETINSERTMARKCOLOR`](/windows/win32/Controls/tb-getinsertmarkcolor), as described in the Windows SDK. -## CToolBarCtrl::GetItemRect +## `CToolBarCtrl::GetItemRect` Retrieves the bounding rectangle of a button in a toolbar control. @@ -897,11 +896,11 @@ BOOL GetItemRect( ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of the button for which to retrieve information. -*lpRect*
-Address of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or a [CRect](../../atl-mfc-shared/reference/crect-class.md) object that receives the coordinates of the bounding rectangle. +*`lpRect`*\ +Address of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that receives the coordinates of the bounding rectangle. ### Return Value @@ -909,9 +908,9 @@ Nonzero if successful; otherwise zero. ### Remarks -This function does not retrieve the bounding rectangle for buttons whose state is set to TBSTATE_HIDDEN. +This function doesn't retrieve the bounding rectangle for buttons whose state is set to `TBSTATE_HIDDEN`. -## CToolBarCtrl::GetMaxSize +## `CToolBarCtrl::GetMaxSize` Retrieves the total size of all of the visible buttons and separators in the toolbar. @@ -921,8 +920,8 @@ BOOL GetMaxSize(LPSIZE pSize) const; ### Parameters -*pSize*
-A pointer to a [SIZE](/windows/win32/api/windef/ns-windef-size) structure that receives the size of the items. +*`pSize`*\ +A pointer to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure that receives the size of the items. ### Return Value @@ -930,9 +929,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETMAXSIZE](/windows/win32/Controls/tb-getmaxsize), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETMAXSIZE`](/windows/win32/Controls/tb-getmaxsize), as described in the Windows SDK. -## CToolBarCtrl::GetMaxTextRows +## `CToolBarCtrl::GetMaxTextRows` Retrieves the maximum number of text rows displayed on a toolbar button. @@ -944,7 +943,7 @@ int GetMaxTextRows() const; The maximum number of text rows displayed on a toolbar button. -## CToolBarCtrl::GetMetrics +## `CToolBarCtrl::GetMetrics` Retrieves the metrics of the `CToolBarCtrl` object. @@ -954,14 +953,14 @@ void GetMetrics(LPTBMETRICS ptbm) const; ### Parameters -*ptbm*
-A pointer to the [TBMETRICS](/windows/win32/api/commctrl/ns-commctrl-tbmetrics) structure of the `CToolBarCtrl` object. +*`ptbm`*\ +A pointer to the [`TBMETRICS`](/windows/win32/api/commctrl/ns-commctrl-tbmetrics) structure of the `CToolBarCtrl` object. ### Remarks -This member function emulates the functionality of the [TB_GETMETRICS](/windows/win32/Controls/tb-getmetrics) message, as described in the Windows SDK. +This member function emulates the functionality of the [`TB_GETMETRICS`](/windows/win32/Controls/tb-getmetrics) message, as described in the Windows SDK. -## CToolBarCtrl::GetPadding +## `CToolBarCtrl::GetPadding` Retrieves the horizontal and vertical padding of the current toolbar control. @@ -973,21 +972,21 @@ BOOL GetPadding( ### Parameters -*pnHorzPadding*\ +*`pnHorzPadding`*\ [out] An integer that receives the horizontal padding of the toolbar control, in pixels. -*pnVertPadding*\ +*`pnVertPadding`*\ [out] An integer that receives the vertical padding of the toolbar control, in pixels. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks -This method sends the [TB_GETPADDING](/windows/win32/Controls/tb-getpadding) message, which is described in the Windows SDK. +This method sends the [`TB_GETPADDING`](/windows/win32/Controls/tb-getpadding) message, which is described in the Windows SDK. -## CToolBarCtrl::GetPressedImageList +## `CToolBarCtrl::GetPressedImageList` Retrieves the image list that the current toolbar control uses to represent buttons in the pressed state. @@ -997,13 +996,13 @@ CImageList* GetPressedImageList(); ### Return Value -Pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) that contains the image list for the current control, or NULL if no such image list is set. +Pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) that contains the image list for the current control, or `NULL` if no such image list is set. ### Remarks -This method sends the [TB_GETPRESSEDIMAGELIST](/windows/win32/Controls/tb-getpressedimagelist) message, which is described in the Windows SDK. +This method sends the [`TB_GETPRESSEDIMAGELIST`](/windows/win32/Controls/tb-getpressedimagelist) message, which is described in the Windows SDK. -## CToolBarCtrl::GetRect +## `CToolBarCtrl::GetRect` Retrieves the bounding rectangle for a specified toolbar button. @@ -1015,21 +1014,21 @@ BOOL GetRect( ### Parameters -*nID*
+*`nID`*\ The button identifier. -*lpRect*
-A pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure to receive the bounding rectangle information. +*`lpRect`*\ +A pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure to receive the bounding rectangle information. ### Return Value -TRUE if successful; otherwise FALSE. +`TRUE` if successful; otherwise `FALSE`. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETRECT](/windows/win32/Controls/tb-getrect), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETRECT`](/windows/win32/Controls/tb-getrect), as described in the Windows SDK. -## CToolBarCtrl::GetRows +## `CToolBarCtrl::GetRows` Retrieves the number of rows of buttons currently displayed by the toolbar control. @@ -1043,11 +1042,11 @@ Number of rows of buttons currently displayed on the toolbar. ### Remarks -Note that the number of rows will always be one unless the toolbar was created with the TBSTYLE_WRAPABLE style. +Note that the number of rows will always be one unless the toolbar was created with the `TBSTYLE_WRAPABLE` style. -## CToolBarCtrl::GetState +## `CToolBarCtrl::GetState` -Retrieves information about the state of the specified button in a toolbar control, such as whether it is enabled, pressed, or checked. +Retrieves information about the state of the specified button in a toolbar control, such as whether it's enabled, pressed, or checked. ``` int GetState(int nID) const; @@ -1055,18 +1054,18 @@ int GetState(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button for which to retrieve information. ### Return Value -The button state information if successful or - 1 otherwise. The button state information can be a combination of the values listed in [CToolBarCtrl::AddButtons](#addbuttons). +The button state information if successful or -1 otherwise. The button state information can be a combination of the values listed in [`CToolBarCtrl::AddButtons`](#addbuttons). ### Remarks -This function is especially handy if you want to retrieve more than one of the button states. To just retrieve one state, use one of the following member functions: [IsButtonEnabled](#isbuttonenabled), [IsButtonChecked](#isbuttonchecked), [IsButtonPressed](#isbuttonpressed), [IsButtonHidden](#isbuttonhidden), or [IsButtonIndeterminate](#isbuttonindeterminate). However, the `GetState` member function is the only way to detect the TBSTATE_WRAP button state. +This function is especially handy if you want to retrieve more than one of the button states. To just retrieve one state, use one of the following member functions: [`IsButtonEnabled`](#isbuttonenabled), [`IsButtonChecked`](#isbuttonchecked), [`IsButtonPressed`](#isbuttonpressed), [`IsButtonHidden`](#isbuttonhidden), or [`IsButtonIndeterminate`](#isbuttonindeterminate). However, the `GetState` member function is the only way to detect the `TBSTATE_WRAP` button state. -## CToolBarCtrl::GetString +## `CToolBarCtrl::GetString` Retrieves a toolbar string. @@ -1083,16 +1082,16 @@ int GetString( ### Parameters -*nString*
+*`nString`*\ Index of the string. -*lpstrString*
+*`lpstrString`*\ Pointer to a buffer used to return the string. -*cchMaxLen*
+*`cchMaxLen`*\ Length of the buffer in bytes. -*str*
+*`str`*\ The string. ### Return Value @@ -1101,9 +1100,9 @@ The length of the string if successful, -1 if not. ### Remarks -This member function implements the behavior of the Win32 message [TB_GETSTRING](/windows/win32/Controls/tb-getstring), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_GETSTRING`](/windows/win32/Controls/tb-getstring), as described in the Windows SDK. -## CToolBarCtrl::GetStyle +## `CToolBarCtrl::GetStyle` Gets the styles currently applied to a toolbar control. @@ -1113,9 +1112,9 @@ DWORD GetStyle() const; ### Return Value -A DWORD containing a combination of [toolbar control styles](/windows/win32/Controls/toolbar-control-and-button-styles), as described in the Windows SDK. +A `DWORD` containing a combination of [toolbar control styles](/windows/win32/Controls/toolbar-control-and-button-styles), as described in the Windows SDK. -## CToolBarCtrl::GetToolTips +## `CToolBarCtrl::GetToolTips` Retrieves the handle of the tool tip control, if any, associated with the toolbar control. @@ -1125,13 +1124,13 @@ CToolTipCtrl* GetToolTips() const; ### Return Value -A pointer to the [CToolTipCtrl](../../mfc/reference/ctooltipctrl-class.md) object associated with this toolbar or NULL if the toolbar has no associated tool tip control. +A pointer to the [`CToolTipCtrl`](../../mfc/reference/ctooltipctrl-class.md) object associated with this toolbar or `NULL` if the toolbar has no associated tool tip control. ### Remarks Since the toolbar control normally creates and maintains its own tool tip control, most programs don't need to call this function. -## CToolBarCtrl::HitTest +## `CToolBarCtrl::HitTest` Determines where a point lies in a toolbar control. @@ -1141,20 +1140,20 @@ int HitTest(LPPOINT ppt) const; ### Parameters -*ppt*
-A pointer to a [POINT](/windows/win32/api/windef/ns-windef-point) structure that contains the x-coordinate of the hit test in the `x` member and the y-coordinate of the hit test in the `y` member. The coordinates are relative to the toolbar's client area. +*`ppt`*\ +A pointer to a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure that contains the x-coordinate of the hit test in the `x` member and the y-coordinate of the hit test in the `y` member. The coordinates are relative to the toolbar's client area. ### Return Value An integer value indicating the location of a point on a toolbar. If the value is zero or a positive value, this return value is the zero-based index of the nonseparator item in which the point lies. -If the return value is negative, the point does not lie within a button. The absolute value of the return value is the index of a separator item or the nearest nonseparator item. +If the return value is negative, the point doesn't lie within a button. The absolute value of the return value is the index of a separator item or the nearest nonseparator item. ### Remarks -This member function implements the behavior of the Win32 message [TB_HITTEST](/windows/win32/Controls/tb-hittest), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_HITTEST`](/windows/win32/Controls/tb-hittest), as described in the Windows SDK. -## CToolBarCtrl::HideButton +## `CToolBarCtrl::HideButton` Hides or shows the specified button in a toolbar control. @@ -1166,11 +1165,11 @@ BOOL HideButton( ### Parameters -*nID*
+*`nID`*\ Command identifier of the button to hide or show. -*bHide*
-TRUE to hide the button, FALSE to show it. +*`bHide`*\ +`TRUE` to hide the button, `FALSE` to show it. ### Return Value @@ -1178,9 +1177,9 @@ Nonzero if successful; otherwise zero. ### Remarks -If you want to change more than one button state, consider calling [SetState](#setstate) instead. +If you want to change more than one button state, consider calling [`SetState`](#setstate) instead. -## CToolBarCtrl::Indeterminate +## `CToolBarCtrl::Indeterminate` Sets or clears the indeterminate state of the specified button in a toolbar control. @@ -1192,11 +1191,11 @@ BOOL Indeterminate( ### Parameters -*nID*
+*`nID`*\ Command identifier of the button whose indeterminate state is to be set or cleared. -*bIndeterminate*
-TRUE to set the indeterminate state for the specified button, FALSE to clear it. +*`bIndeterminate`*\ +`TRUE` to set the indeterminate state for the specified button, `FALSE` to clear it. ### Return Value @@ -1204,9 +1203,9 @@ Nonzero if successful; otherwise zero. ### Remarks -Indeterminate buttons are displayed grayed, such as the way the bold button on the toolbar of a word processor would look when the text selected contains both bold and regular characters. If you want to change more than one button state, consider calling [SetState](#setstate) instead. +Indeterminate buttons are displayed grayed, such as the way the bold button on the toolbar of a word processor would look when the text selected contains both bold and regular characters. If you want to change more than one button state, consider calling [`SetState`](#setstate) instead. -## CToolBarCtrl::InsertButton +## `CToolBarCtrl::InsertButton` Inserts a button in a toolbar control. @@ -1218,11 +1217,11 @@ BOOL InsertButton( ### Parameters -*nIndex*
+*`nIndex`*\ Zero-based index of a button. This function inserts the new button to the left of this button. -*lpButton*
-Address of a `TBBUTTON` structure containing information about the button to insert. See [CToolBarCtrl::AddButtons](#addbuttons) for a description of the `TBBUTTON` structure. +*`lpButton`*\ +Address of a `TBBUTTON` structure containing information about the button to insert. See [`CToolBarCtrl::AddButtons`](#addbuttons) for a description of the `TBBUTTON` structure. ### Return Value @@ -1230,9 +1229,9 @@ Nonzero if successful; otherwise zero. ### Remarks -The image and/or string whose index you provide must have previously been added to the toolbar control's list using [AddBitmap](#addbitmap), [AddString](#addstring), and/or [AddStrings](#addstrings). +The image and/or string whose index you provide must have previously been added to the toolbar control's list using [`AddBitmap`](#addbitmap), [`AddString`](#addstring), and/or [`AddStrings`](#addstrings). -## CToolBarCtrl::InsertMarkHitTest +## `CToolBarCtrl::InsertMarkHitTest` Retrieves the insertion mark information for a point in a toolbar. @@ -1244,11 +1243,11 @@ BOOL InsertMarkHitTest( ### Parameters -*ppt*
-A pointer to a [POINT](/windows/win32/api/windef/ns-windef-point) structure that contains the hit test coordinates, relative to the client area of the toolbar. +*`ppt`*\ +A pointer to a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure that contains the hit test coordinates, relative to the client area of the toolbar. -*ptbim*
-A pointer to a [TBINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that receives the insertion mark information. +*`ptbim`*\ +A pointer to a [`TBINSERTMARK`](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that receives the insertion mark information. ### Return Value @@ -1256,9 +1255,9 @@ Nonzero if successful; otherwise zero. ### Remarks -This member function implements the behavior of the Win32 message [TB_INSERTMARKHITTEST](/windows/win32/Controls/tb-insertmarkhittest), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_INSERTMARKHITTEST`](/windows/win32/Controls/tb-insertmarkhittest), as described in the Windows SDK. -## CToolBarCtrl::IsButtonChecked +## `CToolBarCtrl::IsButtonChecked` Determines whether the specified button in a toolbar control is checked. @@ -1268,7 +1267,7 @@ BOOL IsButtonChecked(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button in the toolbar. ### Return Value @@ -1277,9 +1276,9 @@ Nonzero if the button is checked; otherwise zero. ### Remarks -Consider calling [GetState](#getstate) if you want to retrieve more than one button state. +Consider calling [`GetState`](#getstate) if you want to retrieve more than one button state. -## CToolBarCtrl::IsButtonEnabled +## `CToolBarCtrl::IsButtonEnabled` Determines whether the specified button in a toolbar control is enabled. @@ -1289,7 +1288,7 @@ BOOL IsButtonEnabled(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button in the toolbar. ### Return Value @@ -1298,9 +1297,9 @@ Nonzero if the button is enabled; otherwise zero. ### Remarks -Consider calling [GetState](#getstate) if you want to retrieve more than one button state. +Consider calling [`GetState`](#getstate) if you want to retrieve more than one button state. -## CToolBarCtrl::IsButtonHidden +## `CToolBarCtrl::IsButtonHidden` Determines whether the specified button in a toolbar control is hidden. @@ -1310,7 +1309,7 @@ BOOL IsButtonHidden(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button in the toolbar. ### Return Value @@ -1319,9 +1318,9 @@ Nonzero if the button is hidden; otherwise zero. ### Remarks -Consider calling [GetState](#getstate) if you want to retrieve more than one button state. +Consider calling [`GetState`](#getstate) if you want to retrieve more than one button state. -## CToolBarCtrl::IsButtonHighlighted +## `CToolBarCtrl::IsButtonHighlighted` Checks the highlight state of a toolbar button. @@ -1331,14 +1330,14 @@ BOOL IsButtonHighlighted(int nID) const; ### Parameters -*nID*
+*`nID`*\ [in] The command ID for the toolbar button. ### Return Value -Positive integer if the button is highlighted, 0 if the button is not highlighted, or -1 if an error occurs. +Positive integer if the button is highlighted, 0 if the button isn't highlighted, or -1 if an error occurs. -## CToolBarCtrl::IsButtonIndeterminate +## `CToolBarCtrl::IsButtonIndeterminate` Determines whether the specified button in a toolbar control is indeterminate. @@ -1348,18 +1347,18 @@ BOOL IsButtonIndeterminate(int nID) const; ### Parameters -*nID*
+*`nID`*\ [in] Command identifier of the button in the toolbar. ### Return Value -Positive integer if the button is indeterminate, zero if the button is not indeterminate, or -1 if an error occurs. +Positive integer if the button is indeterminate, zero if the button isn't indeterminate, or -1 if an error occurs. ### Remarks -Indeterminate buttons are displayed dimmed, such as the way the bold button on the toolbar of a word processor looks when the selected text contains both bold and regular characters. Consider calling [GetState](#getstate) if you want to retrieve more than one button state. +Indeterminate buttons are displayed dimmed, such as the way the bold button on the toolbar of a word processor looks when the selected text contains both bold and regular characters. Consider calling [`GetState`](#getstate) if you want to retrieve more than one button state. -## CToolBarCtrl::IsButtonPressed +## `CToolBarCtrl::IsButtonPressed` Determines whether the specified button in a toolbar control is pressed. @@ -1369,7 +1368,7 @@ BOOL IsButtonPressed(int nID) const; ### Parameters -*nID*
+*`nID`*\ Command identifier of the button in the toolbar. ### Return Value @@ -1378,9 +1377,9 @@ Nonzero if the button is pressed, otherwise zero. ### Remarks -Consider calling [GetState](#getstate) if you want to retrieve more than one button state. +Consider calling [`GetState`](#getstate) if you want to retrieve more than one button state. -## CToolBarCtrl::LoadImages +## `CToolBarCtrl::LoadImages` Loads bitmaps into a toolbar control's image list. @@ -1392,26 +1391,26 @@ void LoadImages( ### Parameters -*iBitmapID*
-ID of a bitmap that contains the images to be loaded. To specify your own bitmap resource, set this parameter to the ID of a bitmap resource and set *hInst* to NULL. Your bitmap resource will be added to the image list as a single image. You can add standard, system-defined bitmaps by setting *hinst* to HINST_COMMCTRL and setting this parameter to one of the following IDs: +*`iBitmapID`*\ +ID of a bitmap that contains the images to be loaded. To specify your own bitmap resource, set this parameter to the ID of a bitmap resource and set *`hInst`* to `NULL`. Your bitmap resource will be added to the image list as a single image. You can add standard, system-defined bitmaps by setting *`hinst`* to `HINST_COMMCTRL` and setting this parameter to one of the following IDs: |Bitmap ID|Description| |---------------|-----------------| -|IDB_HIST_LARGE_COLOR|Explorer bitmaps in large size| -|IDB_HIST_SMALL_COLOR|Explorer bitmaps in small size| -|IDB_STD_LARGE_COLOR|Standard bitmaps in large size| -|IDB_STD_SMALL_COLOR|Standard bitmaps in small size| -|IDB_VIEW_LARGE_COLOR|View bitmaps in large size| -|IDB_VIEW_SMALL_COLOR|View bitmaps in small size| +|`IDB_HIST_LARGE_COLOR`|Explorer bitmaps in large size| +|`IDB_HIST_SMALL_COLOR`|Explorer bitmaps in small size| +|`IDB_STD_LARGE_COLOR`|Standard bitmaps in large size| +|`IDB_STD_SMALL_COLOR`|Standard bitmaps in small size| +|`IDB_VIEW_LARGE_COLOR`|View bitmaps in large size| +|`IDB_VIEW_SMALL_COLOR`|View bitmaps in small size| -*hinst*
-Program instance handle to the calling application. This parameter can be HINST_COMMCTRL to load a standard image list. +*`hinst`*\ +Program instance handle to the calling application. This parameter can be `HINST_COMMCTRL` to load a standard image list. ### Remarks -This member function implements the behavior of the Win32 message [TB_LOADIMAGES](/windows/win32/Controls/tb-loadimages), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_LOADIMAGES`](/windows/win32/Controls/tb-loadimages), as described in the Windows SDK. -## CToolBarCtrl::MapAccelerator +## `CToolBarCtrl::MapAccelerator` Maps an accelerator character to a toolbar button. @@ -1423,11 +1422,11 @@ BOOL MapAccelerator( ### Parameters -*chAccel*
+*`chAccel`*\ Accelerator character to be mapped. This character is the same character that is underlined in the button's text. -*pIDBtn*
-A pointer to a UINT that receives the command identifier of the button that corresponds to the accelerator specified in *chAccel*. +*`pIDBtn`*\ +A pointer to a `UINT` that receives the command identifier of the button that corresponds to the accelerator specified in *`chAccel`*. ### Return Value @@ -1435,9 +1434,9 @@ Nonzero if successful; otherwise zero. ### Remarks -This member function implements the behavior of the Win32 message [TB_MAPACCELERATOR](/windows/win32/Controls/tb-mapaccelerator), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_MAPACCELERATOR`](/windows/win32/Controls/tb-mapaccelerator), as described in the Windows SDK. -## CToolBarCtrl::MarkButton +## `CToolBarCtrl::MarkButton` Sets the highlight state of a given button in a toolbar control. @@ -1449,11 +1448,11 @@ BOOL MarkButton( ### Parameters -*nID*
+*`nID`*\ The button identifier. -*fHighlight*
-Specifies the highlight state to be set. By default, TRUE. If set to FALSE, the button is set to its default state. +*`fHighlight`*\ +Specifies the highlight state to be set. By default, `TRUE`. If set to `FALSE`, the button is set to its default state. ### Return Value @@ -1461,9 +1460,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [TB_MARKBUTTON](/windows/win32/Controls/tb-markbutton), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_MARKBUTTON`](/windows/win32/Controls/tb-markbutton), as described in the Windows SDK. -## CToolBarCtrl::MoveButton +## `CToolBarCtrl::MoveButton` Moves a button from one index to another. @@ -1475,10 +1474,10 @@ BOOL MoveButton( ### Parameters -*nOldPos*
+*`nOldPos`*\ The zero-based index of the button to be moved. -*nNewPos*
+*`nNewPos`*\ The zero-based index of the button's destination. ### Return Value @@ -1487,9 +1486,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [TB_MOVEBUTTON](/windows/win32/Controls/tb-movebutton), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_MOVEBUTTON`](/windows/win32/Controls/tb-movebutton), as described in the Windows SDK. -## CToolBarCtrl::PressButton +## `CToolBarCtrl::PressButton` Presses or releases the specified button in a toolbar control. @@ -1499,23 +1498,23 @@ BOOL PressButton(int nID, BOOL bPress = TRUE); ### Parameters -*nID*
+*`nID`*\ [in] Command identifier of the button to press or release. -*bPress*
-[in] TRUE to press the specified button; FALSE to release the specified button. The default value is TRUE. +*`bPress`*\ +[in] `TRUE` to press the specified button; `FALSE` to release the specified button. The default value is `TRUE`. ### Return Value -TRUE if the method is successful; otherwise, FALSE. +`TRUE` if the method is successful; otherwise, `FALSE`. ### Remarks -If you want to change more than one button state, consider calling [SetState](#setstate) instead. +If you want to change more than one button state, consider calling [`SetState`](#setstate) instead. -This method sends the [TB_PRESSBUTTON](/windows/win32/Controls/tb-pressbutton) message, which is described in the Windows SDK. +This method sends the [`TB_PRESSBUTTON`](/windows/win32/Controls/tb-pressbutton) message, which is described in the Windows SDK. -## CToolBarCtrl::ReplaceBitmap +## `CToolBarCtrl::ReplaceBitmap` Replaces the existing bitmap in the current toolbar control with a new bitmap. @@ -1525,16 +1524,16 @@ BOOL ReplaceBitmap(LPTBREPLACEBITMAP pReplaceBitmap); ### Parameters -*pReplaceBitmap*\ -[in] Pointer to a [TBREPLACEBITMAP](/windows/win32/api/commctrl/ns-commctrl-tbreplacebitmap) structure that describes the bitmap to be replaced and the new bitmap. +*`pReplaceBitmap`*\ +[in] Pointer to a [`TBREPLACEBITMAP`](/windows/win32/api/commctrl/ns-commctrl-tbreplacebitmap) structure that describes the bitmap to be replaced and the new bitmap. ### Return Value -TRUE if this method is successful; otherwise, FALSE. +`TRUE` if this method is successful; otherwise, `FALSE`. ### Remarks -This method sends the [TB_REPLACEBITMAP](/windows/win32/Controls/tb-replacebitmap) message, which is described in the Windows SDK. +This method sends the [`TB_REPLACEBITMAP`](/windows/win32/Controls/tb-replacebitmap) message, which is described in the Windows SDK. ### Example @@ -1542,7 +1541,7 @@ The following code example replaces the bitmap for the standard toolbar with a d [!code-cpp[NVC_MFC_CToolBarCtrl_s1#2](../../mfc/reference/codesnippet/cpp/ctoolbarctrl-class_4.cpp)] -## CToolBarCtrl::RestoreState +## `CToolBarCtrl::RestoreState` Restores the state of the toolbar control from the location in the registry specified by the parameters. @@ -1555,24 +1554,24 @@ void RestoreState( ### Parameters -*hKeyRoot*
+*`hKeyRoot`*\ Identifies a currently open key in the registry or any of the following predefined reserved handle values: -- HKEY_CLASSES_ROOT +- `HKEY_CLASSES_ROOT` -- HKEY_CURRENT_USER +- `HKEY_CURRENT_USER` -- HKEY_LOCAL_MACHINE +- `HKEY_LOCAL_MACHINE` -- HKEY_USERS +- `HKEY_USERS` -*lpszSubKey*
-Points to a null-terminated string containing the name of the subkey with which a value is associated. This parameter can be null or a pointer to an empty string. If the parameter is NULL, the value will be added to the key identified by the *hKeyRoot* parameter. +*`lpszSubKey`*\ +Points to a `NULL`-terminated string containing the name of the subkey with which a value is associated. This parameter can be `NULL` or a pointer to an empty string. If the parameter is `NULL`, the value will be added to the key identified by the *`hKeyRoot`* parameter. -*lpszValueName*
-Points to a string containing the name of the value to retrieve. If a value with this name is not already present in the key, the function adds it to the key. +*`lpszValueName`*\ +Points to a string containing the name of the value to retrieve. If a value with this name isn't already present in the key, the function adds it to the key. -## CToolBarCtrl::SaveState +## `CToolBarCtrl::SaveState` Saves the state of the toolbar control in the location in the registry specified by the parameters. @@ -1585,24 +1584,24 @@ void SaveState( ### Parameters -*hKeyRoot*
+*`hKeyRoot`*\ Identifies a currently open key in the registry or any of the following predefined reserved handle values: -- HKEY_CLASSES_ROOT +- `HKEY_CLASSES_ROOT` -- HKEY_CURRENT_USER +- `HKEY_CURRENT_USER` -- HKEY_LOCAL_MACHINE +- `HKEY_LOCAL_MACHINE` -- HKEY_USERS +- `HKEY_USERS` -*lpszSubKey*
-Points to a null-terminated string containing the name of the subkey with which a value is associated. This parameter can be null or a pointer to an empty string. If the parameter is NULL, the value will be added to the key identified by the *hKeyRoot* parameter. +*`lpszSubKey`*\ +Points to a `NULL`-terminated string containing the name of the subkey with which a value is associated. This parameter can be `NULL` or a pointer to an empty string. If the parameter is `NULL`, the value will be added to the key identified by the *`hKeyRoot`* parameter. -*lpszValueName*
-Points to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key. +*`lpszValueName`*\ +Points to a string containing the name of the value to set. If a value with this name isn't already present in the key, the function adds it to the key. -## CToolBarCtrl::SetAnchorHighlight +## `CToolBarCtrl::SetAnchorHighlight` Sets the anchor highlight setting for a toolbar. @@ -1612,18 +1611,18 @@ BOOL SetAnchorHighlight(BOOL fAnchor = TRUE); ### Parameters -*fAnchor*
+*`fAnchor`*\ [in] Specifies if anchor highlighting is enabled or disabled. If this value is nonzero, anchor highlighting will be enabled. If this value is zero, anchor highlighting will be disabled ### Return Value -The previous anchor setting. If highlighting was enabled, this value is nonzero. If highlighting was not enabled, this value is zero. +The previous anchor setting. If highlighting was enabled, this value is nonzero. If highlighting wasn't enabled, this value is zero. ### Remarks -This method implements the behavior of the Win32 message [TB_SETANCHORHIGHLIGHT](/windows/win32/Controls/tb-setanchorhighlight), as described in the Windows SDK. +This method implements the behavior of the Win32 message [`TB_SETANCHORHIGHLIGHT`](/windows/win32/Controls/tb-setanchorhighlight), as described in the Windows SDK. -## CToolBarCtrl::SetBitmapSize +## `CToolBarCtrl::SetBitmapSize` Sets the size of the actual bitmapped images to be added to a toolbar control. @@ -1633,7 +1632,7 @@ BOOL SetBitmapSize(CSize size); ### Parameters -*size*
+*`size`*\ Width and height, in pixels, of the bitmapped images. ### Return Value @@ -1642,9 +1641,9 @@ Nonzero if successful; otherwise zero. ### Remarks -This function must be called only before adding any bitmaps to the toolbar. If the application does not explicitly set the bitmap size, it defaults to 16 by 15 pixels. +This function must be called only before adding any bitmaps to the toolbar. If the application doesn't explicitly set the bitmap size, it defaults to 16 by 15 pixels. -## CToolBarCtrl::SetButtonInfo +## `CToolBarCtrl::SetButtonInfo` Sets the information for an existing button in a toolbar. @@ -1656,11 +1655,11 @@ BOOL SetButtonInfo( ### Parameters -*nID*
+*`nID`*\ The button identifier. -*ptbbi*
-A pointer to a [TBBUTTONINFO](/windows/win32/api/commctrl/ns-commctrl-tbbuttoninfow) structure that receives the button information. +*`ptbbi`*\ +A pointer to a [`TBBUTTONINFO`](/windows/win32/api/commctrl/ns-commctrl-tbbuttoninfow) structure that receives the button information. ### Return Value @@ -1668,9 +1667,9 @@ Nonzero if successful; otherwise 0. ### Remarks -The member function implements the behavior of the Win32 message [TB_SETBUTTONINFO](/windows/win32/Controls/tb-setbuttoninfo), as described in the Windows SDK. +The member function implements the behavior of the Win32 message [`TB_SETBUTTONINFO`](/windows/win32/Controls/tb-setbuttoninfo), as described in the Windows SDK. -## CToolBarCtrl::SetButtonSize +## `CToolBarCtrl::SetButtonSize` Sets the size of the buttons in the toolbar control. @@ -1680,7 +1679,7 @@ BOOL SetButtonSize(CSize size); ### Parameters -*size*
+*`size`*\ Width and height, in pixels, of the buttons. ### Return Value @@ -1689,13 +1688,13 @@ Nonzero if successful; otherwise zero. ### Remarks -The button size must always be at least as large as the bitmap size it encloses. This function must be called only before adding any bitmaps to the toolbar. If the application does not explicitly set the button size, it defaults to 24 by 22 pixels. +The button size must always be at least as large as the bitmap size it encloses. This function must be called only before adding any bitmaps to the toolbar. If the application doesn't explicitly set the button size, it defaults to 24 by 22 pixels. ### Example - See the example for [CToolBar::GetToolBarCtrl](../../mfc/reference/ctoolbar-class.md#gettoolbarctrl). + See the example for [`CToolBar::GetToolBarCtrl`](../../mfc/reference/ctoolbar-class.md#gettoolbarctrl). -## CToolBarCtrl::SetButtonStructSize +## `CToolBarCtrl::SetButtonStructSize` Specifies the size of the `TBBUTTON` structure. @@ -1705,16 +1704,16 @@ void SetButtonStructSize(int nSize); ### Parameters -*nSize*
+*`nSize`*\ Size, in bytes, of the `TBBUTTON` structure. ### Remarks If you wanted to store extra data in the `TBBUTTON` structure, you could either derive a new structure from `TBBUTTON`, adding the members you needed, or create a new structure that contains a `TBBUTTON` structure as its first member. You would then call this function to tell the toolbar control the size of the new structure. -See [CToolBarCtrl::AddButtons](#addbuttons) for more information on the `TBBUTTON` structure. +See [`CToolBarCtrl::AddButtons`](#addbuttons) for more information on the `TBBUTTON` structure. -## CToolBarCtrl::SetButtonWidth +## `CToolBarCtrl::SetButtonWidth` Sets the minimum and maximum button widths in the toolbar control. @@ -1726,10 +1725,10 @@ BOOL SetButtonWidth( ### Parameters -*cxMin*
+*`cxMin`*\ Minimum button width, in pixels. Toolbar buttons will never be narrower than this value. -*cxMax*
+*`cxMax`*\ Maximum button width, in pixels. If button text is too wide, the control displays it with ellipsis points. ### Return Value @@ -1738,9 +1737,9 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETBUTTONWIDTH](/windows/win32/Controls/tb-setbuttonwidth), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETBUTTONWIDTH`](/windows/win32/Controls/tb-setbuttonwidth), as described in the Windows SDK. -## CToolBarCtrl::SetCmdID +## `CToolBarCtrl::SetCmdID` Sets the command identifier that will be sent to the owner window when the specified button is pressed. @@ -1752,17 +1751,17 @@ BOOL SetCmdID( ### Parameters -*nIndex*
+*`nIndex`*\ The zero-based index of the button whose command ID is to be set. -*nID*
+*`nID`*\ The command ID to set the selected button to. ### Return Value Returns nonzero if successful; otherwise zero. -## CToolBarCtrl::SetColorScheme +## `CToolBarCtrl::SetColorScheme` Sets the color scheme of the current toolbar control. @@ -1772,14 +1771,14 @@ void SetColorScheme(const COLORSCHEME* lpColorScheme); ### Parameters -*lpColorScheme*\ -[in] Pointer to a [COLORSCHEME](/windows/win32/api/commctrl/ns-commctrl-colorscheme) structure that describes the highlight color and shadow color of the toolbar control. +*`lpColorScheme`*\ +[in] Pointer to a [`COLORSCHEME`](/windows/win32/api/commctrl/ns-commctrl-colorscheme) structure that describes the highlight color and shadow color of the toolbar control. ### Remarks This method has no effect if a Windows Vista visual theme is set. -This method sends the [TB_SETCOLORSCHEME](/windows/win32/Controls/tb-setcolorscheme) message, which is described in the Windows SDK. +This method sends the [`TB_SETCOLORSCHEME`](/windows/win32/Controls/tb-setcolorscheme) message, which is described in the Windows SDK. ### Example @@ -1787,7 +1786,7 @@ The following code example sets the color scheme for the current toolbar control [!code-cpp[NVC_MFC_CToolBarCtrl_s1#3](../../mfc/reference/codesnippet/cpp/ctoolbarctrl-class_5.cpp)] -## CToolBarCtrl::SetDisabledImageList +## `CToolBarCtrl::SetDisabledImageList` Sets the image list that the toolbar control will use to display disabled buttons. @@ -1797,20 +1796,20 @@ CImageList* SetDisabledImageList(CImageList* pImageList); ### Parameters -*pImageList*
+*`pImageList`*\ A pointer to a `CImageList` object containing the images to be used by the toolbar control to display disabled button images. ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display disabled button images. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display disabled button images. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETDISABLEDIMAGELIST](/windows/win32/Controls/tb-setdisabledimagelist), as described in the Windows SDK. The MFC implementation of `SetDisabledImageList` uses a `CImageList` object containing the toolbar control's disabled button images, rather than a handle to an image list. +This member function implements the behavior of the Win32 message [`TB_SETDISABLEDIMAGELIST`](/windows/win32/Controls/tb-setdisabledimagelist), as described in the Windows SDK. The MFC implementation of `SetDisabledImageList` uses a `CImageList` object containing the toolbar control's disabled button images, rather than a handle to an image list. -## CToolBarCtrl::SetDrawTextFlags +## `CToolBarCtrl::SetDrawTextFlags` -Sets the flags in the Win32 function [DrawText](/windows/win32/api/winuser/nf-winuser-drawtext), which is used to draw the text in the specified rectangle, formatted according to how the flags are set. +Sets the flags in the Win32 function [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext), which is used to draw the text in the specified rectangle, formatted according to how the flags are set. ``` DWORD SetDrawTextFlags( @@ -1820,21 +1819,21 @@ DWORD SetDrawTextFlags( ### Parameters -*dwMask*
-A combination of one or more of the DT_ flags, specified in the Win32 function [DrawText](/windows/win32/api/winuser/nf-winuser-drawtext), that indicates which bits in *dwDTFlags* will be used when drawing the text. +*`dwMask`*\ +A combination of one or more of the `DT_` flags, specified in the Win32 function [`DrawText`](/windows/win32/api/winuser/nf-winuser-drawtext), that indicates which bits in *`dwDTFlags`* will be used when drawing the text. -*dwDTFlags*
-A combination of one or more of the DT_ flags, specified in the Win32 function `DrawText`, that indicate how the button text will be drawn. This value is passed to `DrawText` when the button text is drawn. +*`dwDTFlags`*\ +A combination of one or more of the `DT_` flags, specified in the Win32 function `DrawText`, that indicate how the button text will be drawn. This value is passed to `DrawText` when the button text is drawn. ### Return Value -A DWORD containing the previous text drawing flags. +A `DWORD` containing the previous text drawing flags. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETDRAWTEXTFLAGS](/windows/win32/Controls/tb-setdrawtextflags), as described in the Windows SDK. This member function sets the flags in the Win32 function `DrawText`, which draws text in the specified rectangle, formatted according to how the flags are set. +This member function implements the behavior of the Win32 message [`TB_SETDRAWTEXTFLAGS`](/windows/win32/Controls/tb-setdrawtextflags), as described in the Windows SDK. This member function sets the flags in the Win32 function `DrawText`, which draws text in the specified rectangle, formatted according to how the flags are set. -## CToolBarCtrl::SetExtendedStyle +## `CToolBarCtrl::SetExtendedStyle` Sets the extended styles for a toolbar control. @@ -1844,18 +1843,18 @@ DWORD SetExtendedStyle(DWORD dwExStyle); ### Parameters -*dwExStyle*
+*`dwExStyle`*\ A value specifying the new extended styles. This parameter can be a combination of the toolbar extended styles. ### Return Value -A DWORD that represents the previous extended styles. For a list of styles, see [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles), in the Windows SDK. +A `DWORD` that represents the previous extended styles. For a list of styles, see [Toolbar Extended Styles](/windows/win32/Controls/toolbar-extended-styles), in the Windows SDK. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETEXTENDEDSTYLE](/windows/win32/Controls/tb-setextendedstyle), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETEXTENDEDSTYLE`](/windows/win32/Controls/tb-setextendedstyle), as described in the Windows SDK. -## CToolBarCtrl::SetHotImageList +## `CToolBarCtrl::SetHotImageList` Sets the image list that the toolbar control will use to display "hot" buttons. @@ -1865,20 +1864,20 @@ CImageList* SetHotImageList(CImageList* pImageList); ### Parameters -*pImageList*
+*`pImageList`*\ A pointer to a `CImageList` object containing the images to be used by the toolbar control to display hot button images. ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display hot button images. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display hot button images. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETHOTIMAGELIST](/windows/win32/Controls/tb-sethotimagelist), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETHOTIMAGELIST`](/windows/win32/Controls/tb-sethotimagelist), as described in the Windows SDK. The MFC implementation of `SetHotImageList` uses a `CImageList` object containing the toolbar control's hot button images, rather than a handle to an image list. A hot button appears highlighted when the pointer is above it. -## CToolBarCtrl::SetHotItem +## `CToolBarCtrl::SetHotItem` Sets the hot item in a toolbar. @@ -1888,7 +1887,7 @@ int SetHotItem(int nHot); ### Parameters -*nHot*
+*`nHot`*\ The zero-based index number of the item that will be made hot. If this value is -1, none of the items will be hot. ### Return Value @@ -1897,9 +1896,9 @@ The index of the previous hot item, or -1 if there was no hot item. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETHOTITEM](/windows/win32/Controls/tb-sethotitem), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETHOTITEM`](/windows/win32/Controls/tb-sethotitem), as described in the Windows SDK. -## CToolBarCtrl::SetImageList +## `CToolBarCtrl::SetImageList` Sets the image list that the toolbar will use to display buttons that are in their default state. @@ -1909,20 +1908,20 @@ CImageList* SetImageList(CImageList* pImageList); ### Parameters -*pImageList*
+*`pImageList`*\ A pointer to a `CImageList` object containing the images to be used by the toolbar control to display button images in their default state. ### Return Value -A pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display button images in their default state. +A pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) object that was previously used by the toolbar control to display button images in their default state. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETIMAGELIST](/windows/win32/Controls/tb-setimagelist), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETIMAGELIST`](/windows/win32/Controls/tb-setimagelist), as described in the Windows SDK. The MFC implementation of `SetImageList` uses a `CImageList` object containing the toolbar control's button images, rather than a handle to an image list. -## CToolBarCtrl::SetIndent +## `CToolBarCtrl::SetIndent` Sets the indentation for the first button in a toolbar control. @@ -1932,14 +1931,14 @@ BOOL SetIndent(int iIndent); ### Parameters -*iIndent*
+*`iIndent`*\ The value specifying the indentation, in pixels. ### Return Value Nonzero if successful; otherwise zero. -## CToolBarCtrl::SetInsertMark +## `CToolBarCtrl::SetInsertMark` Sets the current insertion mark for the toolbar. @@ -1949,14 +1948,14 @@ void SetInsertMark(TBINSERTMARK* ptbim); ### Parameters -*ptbim*
-A pointer to the [TBINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that contains the insertion mark. +*`ptbim`*\ +A pointer to the [`TBINSERTMARK`](/windows/win32/api/commctrl/ns-commctrl-tbinsertmark) structure that contains the insertion mark. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETINSERTMARK](/windows/win32/Controls/tb-setinsertmark), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETINSERTMARK`](/windows/win32/Controls/tb-setinsertmark), as described in the Windows SDK. -## CToolBarCtrl::SetInsertMarkColor +## `CToolBarCtrl::SetInsertMarkColor` Sets the color used to draw the insertion mark for the toolbar. @@ -1966,18 +1965,18 @@ COLORREF SetInsertMarkColor(COLORREF clrNew); ### Parameters -*clrNew*
-A COLORREF value that contains the new insertion mark color. +*`clrNew`*\ +A `COLORREF` value that contains the new insertion mark color. ### Return Value -A COLORREF value that contains the previous insertion mark color. +A `COLORREF` value that contains the previous insertion mark color. ### Remarks -This member function implements the behavior of the Win32 message [TB_SETINSERTMARKCOLOR](/windows/win32/Controls/tb-setinsertmarkcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TB_SETINSERTMARKCOLOR`](/windows/win32/Controls/tb-setinsertmarkcolor), as described in the Windows SDK. -## CToolBarCtrl::SetMaxTextRows +## `CToolBarCtrl::SetMaxTextRows` Sets the maximum number of text rows displayed on a toolbar button. @@ -1987,14 +1986,14 @@ BOOL SetMaxTextRows(int iMaxRows); ### Parameters -*iMaxRows*
+*`iMaxRows`*\ Maximum number of rows to be set. ### Return Value Nonzero if successful; otherwise zero. -## CToolBarCtrl::SetMetrics +## `CToolBarCtrl::SetMetrics` Sets the metrics of the `CToolBarCtrl` object. @@ -2004,14 +2003,14 @@ void SetMetrics(LPTBMETRICS ptbm); ### Parameters -*ptbm*
-A pointer to the [TBMETRICS](/windows/win32/api/commctrl/ns-commctrl-tbmetrics) structure of the `CToolBarCtrl` object. +*`ptbm`*\ +A pointer to the [`TBMETRICS`](/windows/win32/api/commctrl/ns-commctrl-tbmetrics) structure of the `CToolBarCtrl` object. ### Remarks -This member function emulates the functionality of the [TB_SETMETRICS](/windows/win32/Controls/tb-setmetrics) message, as described in the Windows SDK. +This member function emulates the functionality of the [`TB_SETMETRICS`](/windows/win32/Controls/tb-setmetrics) message, as described in the Windows SDK. -## CToolBarCtrl::SetOwner +## `CToolBarCtrl::SetOwner` Sets the owner window for the toolbar control. @@ -2021,14 +2020,14 @@ void SetOwner(CWnd* pWnd); ### Parameters -*pWnd*
+*`pWnd`*\ Pointer to the `CWnd` or `CWnd`-derived object that will be the new owner window for the toolbar control. ### Remarks The owner window is the window that receives notifications from the toolbar. -## CToolBarCtrl::SetPadding +## `CToolBarCtrl::SetPadding` Sets the horizontal and vertical padding of the current toolbar control. @@ -2040,19 +2039,19 @@ DWORD SetPadding( ### Parameters -*nHorzPadding*\ +*`nHorzPadding`*\ [in] Specifies the horizontal padding of the toolbar control, in pixels. -*nVertPadding*\ +*`nVertPadding`*\ [in] Specifies the vertical padding of the toolbar control, in pixels. ### Return Value -A DWORD whose low word contains the previous horizontal padding value, and whose high word contains the previous vertical padding value. The padding values are measured in pixels. +A `DWORD` whose low word contains the previous horizontal padding value, and whose high word contains the previous vertical padding value. The padding values are measured in pixels. ### Remarks -This method sends the [TB_SETPADDING](/windows/win32/Controls/tb-setpadding) message, which is described in the Windows SDK. +This method sends the [`TB_SETPADDING`](/windows/win32/Controls/tb-setpadding) message, which is described in the Windows SDK. ### Example @@ -2060,7 +2059,7 @@ The following code example sets the horizontal and vertical padding of the curre [!code-cpp[NVC_MFC_CToolBarCtrl_s1#4](../../mfc/reference/codesnippet/cpp/ctoolbarctrl-class_6.cpp)] -## CToolBarCtrl::SetPressedImageList +## `CToolBarCtrl::SetPressedImageList` Sets the image list that the current toolbar control uses to represent buttons in the pressed state. @@ -2072,19 +2071,19 @@ CImagelist* SetPressedImageList( ### Parameters -*iImageID*\ +*`iImageID`*\ [in] The zero-based index of the image list. Set this parameter to zero if you use only one image list. -*pImageList*\ -[in] Pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) that contains the new image list. +*`pImageList`*\ +[in] Pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) that contains the new image list. ### Return Value -Pointer to a [CImageList](../../mfc/reference/cimagelist-class.md) that contains the previous image list for the current control, or NULL if no such image list was set. +Pointer to a [`CImageList`](../../mfc/reference/cimagelist-class.md) that contains the previous image list for the current control, or `NULL` if no such image list was set. ### Remarks -This method sends the [TB_SETPRESSEDIMAGELIST](/windows/win32/Controls/tb-setpressedimagelist) message, which is described in the Windows SDK. +This method sends the [`TB_SETPRESSEDIMAGELIST`](/windows/win32/Controls/tb-setpressedimagelist) message, which is described in the Windows SDK. ### Example @@ -2092,7 +2091,7 @@ The following code example sets the pressed image list to be the same as the def [!code-cpp[NVC_MFC_CToolBarCtrl_s1#5](../../mfc/reference/codesnippet/cpp/ctoolbarctrl-class_7.cpp)] -## CToolBarCtrl::SetRows +## `CToolBarCtrl::SetRows` Asks the toolbar control to resize itself to the requested number of rows. @@ -2105,30 +2104,30 @@ void SetRows( ### Parameters -*nRows*
+*`nRows`*\ Requested number of rows. -*bLarger*
-Tells whether to use more rows or fewer rows if the toolbar cannot be resized to the requested number of rows. +*`bLarger`*\ +Tells whether to use more rows or fewer rows if the toolbar can't be resized to the requested number of rows. -*lpRect*
-Points to the [CRect](../../atl-mfc-shared/reference/crect-class.md) object or [RECT](/windows/win32/api/windef/ns-windef-rect) structure that will receive the new bounding rectangle of the toolbar. +*`lpRect`*\ +Points to the [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that will receive the new bounding rectangle of the toolbar. ### Remarks -If the toolbar cannot resize itself to the requested number or rows, it will resize itself to either the next larger or next smaller valid size, depending on the value of *bLarger*. If *bLarger* is TRUE, the new number of rows will be larger than the number requested. If *bLarger* is FALSE, the new number of rows will be smaller than the number requested. +If the toolbar can't resize itself to the requested number or rows, it will resize itself to either the next larger or next smaller valid size, depending on the value of *`bLarger`*. If *`bLarger`* is `TRUE`, the new number of rows will be larger than the number requested. If *`bLarger`* is `FALSE`, the new number of rows will be smaller than the number requested. -A given number of rows is valid for the toolbar if the buttons can be arranged such that all of the rows have the same number of buttons (except perhaps the last row). For example, a toolbar that contains four buttons could not be sized to three rows because the last two rows would have to be shorter. If you attempted to size it to three rows, you would get four rows if *bLarger* was TRUE and two rows if *bLarger* was FALSE. +A given number of rows is valid for the toolbar if the buttons can be arranged such that all of the rows have the same number of buttons (except perhaps the last row). For example, a toolbar that contains four buttons couldn't be sized to three rows because the last two rows would have to be shorter. If you attempted to size it to three rows, you would get four rows if *`bLarger`* was `TRUE` and two rows if *`bLarger`* was `FALSE`. -If there are separators in the toolbar, the rules for when a given number of rows is valid are more complicated. The layout is computed such that button groups (buttons with a separator before the first and the last button in the group) are never broken up on several rows unless the group cannot fit on one row. +If there are separators in the toolbar, the rules for when a given number of rows is valid are more complicated. The layout is computed such that button groups (buttons with a separator before the first and the last button in the group) are never broken up on several rows unless the group can't fit on one row. -If a group does not fit on one row, the next group will start on the next row even if it would fit on the row where the large group ended. The purpose of this rule is to make the separation between large groups more noticeable. The resulting vertical separators are counted as rows. +If a group doesn't fit on one row, the next group will start on the next row even if it would fit on the row where the large group ended. The purpose of this rule is to make the separation between large groups more noticeable. The resulting vertical separators are counted as rows. -Note also that the `SetRows` member function will always chose the layout that results in the smallest toolbar size. Creating a toolbar with the TBSTYLE_WRAPABLE style and then resizing the control will simply apply the method outlined above given the width of the control. +Note also that the `SetRows` member function will always choose the layout that results in the smallest toolbar size. Creating a toolbar with the `TBSTYLE_WRAPABLE` style and then resizing the control will simply apply the method outlined above given the width of the control. -This function can only be called for toolbars that were created with the TBSTYLE_WRAPABLE style. +This function can only be called for toolbars that were created with the `TBSTYLE_WRAPABLE` style. -## CToolBarCtrl::SetState +## `CToolBarCtrl::SetState` Sets the state for the specified button in a toolbar control. @@ -2140,11 +2139,11 @@ BOOL SetState( ### Parameters -*nID*
+*`nID`*\ Command identifier of the button. -*nState*
-State flags. It can be a combination of the values listed for button states in [CToolBarCtrl::AddButtons](#addbuttons). +*`nState`*\ +State flags. It can be a combination of the values listed for button states in [`CToolBarCtrl::AddButtons`](#addbuttons). ### Return Value @@ -2152,9 +2151,9 @@ Nonzero if successful; otherwise zero. ### Remarks -This function is especially handy if you want to set more than one of the button states. To just set one state, use one of the following member functions: [EnableButton](#enablebutton), [CheckButton](#checkbutton), [HideButton](#hidebutton), [Indeterminate](#indeterminate), or [PressButton](#pressbutton). +This function is especially handy if you want to set more than one of the button states. To just set one state, use one of the following member functions: [`EnableButton`](#enablebutton), [`CheckButton`](#checkbutton), [`HideButton`](#hidebutton), [`Indeterminate`](#indeterminate), or [`PressButton`](#pressbutton). -## CToolBarCtrl::SetStyle +## `CToolBarCtrl::SetStyle` Sets the styles for a toolbar control. @@ -2164,10 +2163,10 @@ void SetStyle(DWORD dwStyle); ### Parameters -*dwStyle*
-A DWORD containing a combination of [toolbar control styles](/windows/win32/Controls/toolbar-control-and-button-styles), as described in the Windows SDK. +*`dwStyle`*\ +A `DWORD` containing a combination of [toolbar control styles](/windows/win32/Controls/toolbar-control-and-button-styles), as described in the Windows SDK. -## CToolBarCtrl::SetToolTips +## `CToolBarCtrl::SetToolTips` Associates a tool tip control with a toolbar control. @@ -2177,10 +2176,10 @@ void SetToolTips(CToolTipCtrl* pTip); ### Parameters -*pTip*
-Pointer to the [CToolTipCtrl](../../mfc/reference/ctooltipctrl-class.md) object. +*`pTip`*\ +Pointer to the [`CToolTipCtrl`](../../mfc/reference/ctooltipctrl-class.md) object. -## CToolBarCtrl::SetWindowTheme +## `CToolBarCtrl::SetWindowTheme` Sets the visual style of the `CToolBarCtrl` object. @@ -2190,21 +2189,21 @@ HRESULT SetWindowTheme(LPCWSTR pszSubAppName); ### Parameters -*pszSubAppName*
+*`pszSubAppName`*\ A pointer to a Unicode string that contains the toolbar visual style to set. ### Return Value -The return value is not used. +The return value isn't used. ### Remarks -This member function emulates the functionality of the [TB_SETWINDOWTHEME](/windows/win32/Controls/tb-setwindowtheme) message, as described in the Windows SDK. +This member function emulates the functionality of the [`TB_SETWINDOWTHEME`](/windows/win32/Controls/tb-setwindowtheme) message, as described in the Windows SDK. ## See also -[MFC Sample CMNCTRL1](../../overview/visual-cpp-samples.md)
-[MFC Sample MFCIE](../../overview/visual-cpp-samples.md)
-[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CToolBar Class](../../mfc/reference/ctoolbar-class.md) +[MFC Sample `CMNCTRL1`](../../overview/visual-cpp-samples.md)\ +[MFC Sample `MFCIE`](../../overview/visual-cpp-samples.md)\ +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CToolBar` Class](../../mfc/reference/ctoolbar-class.md) diff --git a/docs/mfc/reference/ctooltipctrl-class.md b/docs/mfc/reference/ctooltipctrl-class.md index 5be07ff1ad..ceaf49a6f0 100644 --- a/docs/mfc/reference/ctooltipctrl-class.md +++ b/docs/mfc/reference/ctooltipctrl-class.md @@ -4,11 +4,10 @@ title: "CToolTipCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CToolTipCtrl", "AFXCMN/CToolTipCtrl", "AFXCMN/CToolTipCtrl::CToolTipCtrl", "AFXCMN/CToolTipCtrl::Activate", "AFXCMN/CToolTipCtrl::AddTool", "AFXCMN/CToolTipCtrl::AdjustRect", "AFXCMN/CToolTipCtrl::Create", "AFXCMN/CToolTipCtrl::CreateEx", "AFXCMN/CToolTipCtrl::DelTool", "AFXCMN/CToolTipCtrl::GetBubbleSize", "AFXCMN/CToolTipCtrl::GetCurrentTool", "AFXCMN/CToolTipCtrl::GetDelayTime", "AFXCMN/CToolTipCtrl::GetMargin", "AFXCMN/CToolTipCtrl::GetMaxTipWidth", "AFXCMN/CToolTipCtrl::GetText", "AFXCMN/CToolTipCtrl::GetTipBkColor", "AFXCMN/CToolTipCtrl::GetTipTextColor", "AFXCMN/CToolTipCtrl::GetTitle", "AFXCMN/CToolTipCtrl::GetToolCount", "AFXCMN/CToolTipCtrl::GetToolInfo", "AFXCMN/CToolTipCtrl::HitTest", "AFXCMN/CToolTipCtrl::Pop", "AFXCMN/CToolTipCtrl::Popup", "AFXCMN/CToolTipCtrl::RelayEvent", "AFXCMN/CToolTipCtrl::SetDelayTime", "AFXCMN/CToolTipCtrl::SetMargin", "AFXCMN/CToolTipCtrl::SetMaxTipWidth", "AFXCMN/CToolTipCtrl::SetTipBkColor", "AFXCMN/CToolTipCtrl::SetTipTextColor", "AFXCMN/CToolTipCtrl::SetTitle", "AFXCMN/CToolTipCtrl::SetToolInfo", "AFXCMN/CToolTipCtrl::SetToolRect", "AFXCMN/CToolTipCtrl::SetWindowTheme", "AFXCMN/CToolTipCtrl::Update", "AFXCMN/CToolTipCtrl::UpdateTipText"] helpviewer_keywords: ["CToolTipCtrl [MFC], CToolTipCtrl", "CToolTipCtrl [MFC], Activate", "CToolTipCtrl [MFC], AddTool", "CToolTipCtrl [MFC], AdjustRect", "CToolTipCtrl [MFC], Create", "CToolTipCtrl [MFC], CreateEx", "CToolTipCtrl [MFC], DelTool", "CToolTipCtrl [MFC], GetBubbleSize", "CToolTipCtrl [MFC], GetCurrentTool", "CToolTipCtrl [MFC], GetDelayTime", "CToolTipCtrl [MFC], GetMargin", "CToolTipCtrl [MFC], GetMaxTipWidth", "CToolTipCtrl [MFC], GetText", "CToolTipCtrl [MFC], GetTipBkColor", "CToolTipCtrl [MFC], GetTipTextColor", "CToolTipCtrl [MFC], GetTitle", "CToolTipCtrl [MFC], GetToolCount", "CToolTipCtrl [MFC], GetToolInfo", "CToolTipCtrl [MFC], HitTest", "CToolTipCtrl [MFC], Pop", "CToolTipCtrl [MFC], Popup", "CToolTipCtrl [MFC], RelayEvent", "CToolTipCtrl [MFC], SetDelayTime", "CToolTipCtrl [MFC], SetMargin", "CToolTipCtrl [MFC], SetMaxTipWidth", "CToolTipCtrl [MFC], SetTipBkColor", "CToolTipCtrl [MFC], SetTipTextColor", "CToolTipCtrl [MFC], SetTitle", "CToolTipCtrl [MFC], SetToolInfo", "CToolTipCtrl [MFC], SetToolRect", "CToolTipCtrl [MFC], SetWindowTheme", "CToolTipCtrl [MFC], Update", "CToolTipCtrl [MFC], UpdateTipText"] -ms.assetid: 8973f70c-b73a-46c7-908d-758f364b9a97 --- -# CToolTipCtrl Class +# `CToolTipCtrl` Class -Encapsulates the functionality of a "tool tip control," a small pop-up window that displays a single line of text describing the purpose of a tool in an application. +Encapsulates the functionality of a "tooltip control," a small pop-up window that displays a single line of text describing the purpose of a tool in an application. ## Syntax @@ -22,74 +21,74 @@ class CToolTipCtrl : public CWnd |Name|Description| |----------|-----------------| -|[CToolTipCtrl::CToolTipCtrl](#ctooltipctrl)|Constructs a `CToolTipCtrl` object.| +|[`CToolTipCtrl::CToolTipCtrl`](#ctooltipctrl)|Constructs a `CToolTipCtrl` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CToolTipCtrl::Activate](#activate)|Activates and deactivates the tool tip control.| -|[CToolTipCtrl::AddTool](#addtool)|Registers a tool with the tool tip control.| -|[CToolTipCtrl::AdjustRect](#adjustrect)|Converts between a tool tip control's text display rectangle and its window rectangle.| -|[CToolTipCtrl::Create](#create)|Creates a tool tip control and attaches it to a `CToolTipCtrl` object.| -|[CToolTipCtrl::CreateEx](#createex)|Creates a tool tip control with the specified Windows extended styles and attaches it to a `CToolTipCtrl` object.| -|[CToolTipCtrl::DelTool](#deltool)|Removes a tool from the tool tip control.| -|[CToolTipCtrl::GetBubbleSize](#getbubblesize)|Retrieves the size of the tool tip.| -|[CToolTipCtrl::GetCurrentTool](#getcurrenttool)|Retrieves information, such as the size, position, and text, of the tooltip window that the current tooltip control displays.| -|[CToolTipCtrl::GetDelayTime](#getdelaytime)|Retrieves the initial, pop-up, and reshow durations that are currently set for a tool tip control.| -|[CToolTipCtrl::GetMargin](#getmargin)|Retrieves the top, left, bottom, and right margins that are set for a tool tip window.| -|[CToolTipCtrl::GetMaxTipWidth](#getmaxtipwidth)|Retrieves the maximum width for a tool tip window.| -|[CToolTipCtrl::GetText](#gettext)|Retrieves the text that a tool tip control maintains for a tool.| -|[CToolTipCtrl::GetTipBkColor](#gettipbkcolor)|Retrieves the background color in a tool tip window.| -|[CToolTipCtrl::GetTipTextColor](#gettiptextcolor)|Retrieves the text color in a tool tip window.| -|[CToolTipCtrl::GetTitle](#gettitle)|Retrieves the title of the current tooltip control.| -|[CToolTipCtrl::GetToolCount](#gettoolcount)|Retrieves a count of the tools maintained by a tool tip control.| -|[CToolTipCtrl::GetToolInfo](#gettoolinfo)|Retrieves the information that a tool tip control maintains about a tool.| -|[CToolTipCtrl::HitTest](#hittest)|Tests a point to determine whether it is within the bounding rectangle of the given tool. If so, retrieves information about the tool.| -|[CToolTipCtrl::Pop](#pop)|Removes a displayed tool tip window from view.| -|[CToolTipCtrl::Popup](#popup)|Causes the current ToolTip control to display at the coordinates of the last mouse message.| -|[CToolTipCtrl::RelayEvent](#relayevent)|Passes a mouse message to a tool tip control for processing.| -|[CToolTipCtrl::SetDelayTime](#setdelaytime)|Sets the initial, pop-up, and reshow durations for a tool tip control.| -|[CToolTipCtrl::SetMargin](#setmargin)|Sets the top, left, bottom, and right margins for a tool tip window.| -|[CToolTipCtrl::SetMaxTipWidth](#setmaxtipwidth)|Sets the maximum width for a tool tip window.| -|[CToolTipCtrl::SetTipBkColor](#settipbkcolor)|Sets the background color in a tool tip window.| -|[CToolTipCtrl::SetTipTextColor](#settiptextcolor)|Sets the text color in a tool tip window.| -|[CToolTipCtrl::SetTitle](#settitle)|Adds a standard icon and title string to a tool tip.| -|[CToolTipCtrl::SetToolInfo](#settoolinfo)|Sets the information that a tool tip maintains for a tool.| -|[CToolTipCtrl::SetToolRect](#settoolrect)|Sets a new bounding rectangle for a tool.| -|[CToolTipCtrl::SetWindowTheme](#setwindowtheme)|Sets the visual style of the tool tip window.| -|[CToolTipCtrl::Update](#update)|Forces the current tool to be redrawn.| -|[CToolTipCtrl::UpdateTipText](#updatetiptext)|Sets the tool tip text for a tool.| +|[`CToolTipCtrl::Activate`](#activate)|Activates and deactivates the tooltip control.| +|[`CToolTipCtrl::AddTool`](#addtool)|Registers a tool with the tooltip control.| +|[`CToolTipCtrl::AdjustRect`](#adjustrect)|Converts between a tooltip control's text display rectangle and its window rectangle.| +|[`CToolTipCtrl::Create`](#create)|Creates a tooltip control and attaches it to a `CToolTipCtrl` object.| +|[`CToolTipCtrl::CreateEx`](#createex)|Creates a tooltip control with the specified Windows extended styles and attaches it to a `CToolTipCtrl` object.| +|[`CToolTipCtrl::DelTool`](#deltool)|Removes a tool from the tooltip control.| +|[`CToolTipCtrl::GetBubbleSize`](#getbubblesize)|Retrieves the size of the tooltip.| +|[`CToolTipCtrl::GetCurrentTool`](#getcurrenttool)|Retrieves information, such as the size, position, and text, of the tooltip window that the current tooltip control displays.| +|[`CToolTipCtrl::GetDelayTime`](#getdelaytime)|Retrieves the initial, pop-up, and reshow durations that are currently set for a tooltip control.| +|[`CToolTipCtrl::GetMargin`](#getmargin)|Retrieves the top, left, bottom, and right margins that are set for a tooltip window.| +|[`CToolTipCtrl::GetMaxTipWidth`](#getmaxtipwidth)|Retrieves the maximum width for a tooltip window.| +|[`CToolTipCtrl::GetText`](#gettext)|Retrieves the text that a tooltip control maintains for a tool.| +|[`CToolTipCtrl::GetTipBkColor`](#gettipbkcolor)|Retrieves the background color in a tooltip window.| +|[`CToolTipCtrl::GetTipTextColor`](#gettiptextcolor)|Retrieves the text color in a tooltip window.| +|[`CToolTipCtrl::GetTitle`](#gettitle)|Retrieves the title of the current tooltip control.| +|[`CToolTipCtrl::GetToolCount`](#gettoolcount)|Retrieves a count of the tools maintained by a tooltip control.| +|[`CToolTipCtrl::GetToolInfo`](#gettoolinfo)|Retrieves the information that a tooltip control maintains about a tool.| +|[`CToolTipCtrl::HitTest`](#hittest)|Tests a point to determine whether it is within the bounding rectangle of the given tool. If so, retrieves information about the tool.| +|[`CToolTipCtrl::Pop`](#pop)|Removes a displayed tooltip window from view.| +|[`CToolTipCtrl::Popup`](#popup)|Causes the current tooltip control to display at the coordinates of the last mouse message.| +|[`CToolTipCtrl::RelayEvent`](#relayevent)|Passes a mouse message to a tooltip control for processing.| +|[`CToolTipCtrl::SetDelayTime`](#setdelaytime)|Sets the initial, pop-up, and reshow durations for a tooltip control.| +|[`CToolTipCtrl::SetMargin`](#setmargin)|Sets the top, left, bottom, and right margins for a tooltip window.| +|[`CToolTipCtrl::SetMaxTipWidth`](#setmaxtipwidth)|Sets the maximum width for a tooltip window.| +|[`CToolTipCtrl::SetTipBkColor`](#settipbkcolor)|Sets the background color in a tooltip window.| +|[`CToolTipCtrl::SetTipTextColor`](#settiptextcolor)|Sets the text color in a tooltip window.| +|[`CToolTipCtrl::SetTitle`](#settitle)|Adds a standard icon and title string to a tooltip.| +|[`CToolTipCtrl::SetToolInfo`](#settoolinfo)|Sets the information that a tooltip maintains for a tool.| +|[`CToolTipCtrl::SetToolRect`](#settoolrect)|Sets a new bounding rectangle for a tool.| +|[`CToolTipCtrl::SetWindowTheme`](#setwindowtheme)|Sets the visual style of the tooltip window.| +|[`CToolTipCtrl::Update`](#update)|Forces the current tool to be redrawn.| +|[`CToolTipCtrl::UpdateTipText`](#updatetiptext)|Sets the tooltip text for a tool.| ## Remarks -A "tool" is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area. A tool tip is hidden most of the time, appearing only when the user puts the cursor on a tool and leaves it there for approximately one-half second. The tool tip appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off the tool. +A "tool" is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area. A tooltip is hidden most of the time, appearing only when the user puts the cursor on a tool and leaves it there for approximately one-half second. The tooltip appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off the tool. -`CToolTipCtrl` provides the functionality to control the initial time and duration of the tool tip, the margin widths surrounding the tool tip text, the width of the tool tip window itself, and the background and text color of the tool tip. A single tool tip control can provide information for more than one tool. +`CToolTipCtrl` provides the functionality to control the initial time and duration of the tooltip, the margin widths surrounding the tooltip text, the width of the tooltip window itself, and the background and text color of the tooltip. A single tooltip control can provide information for more than one tool. -The `CToolTipCtrl` class provides the functionality of the Windows common tool tip control. This control (and therefore the `CToolTipCtrl` class) is available only to programs running under Windows 95/98 and Windows NT versions 3.51 and later. +The `CToolTipCtrl` class provides the functionality of the Windows common tooltip control. This control (and therefore the `CToolTipCtrl` class) is available only to programs running under Windows 95/98 and Windows NT versions 3.51 and later. -For more information about enabling tool tips, see [Tool Tips in Windows not Derived from CFrameWnd](../../mfc/tool-tips-in-windows-not-derived-from-cframewnd.md). +For more information about enabling tooltips, see [Tool Tips in Windows not Derived from `CFrameWnd`](../../mfc/tool-tips-in-windows-not-derived-from-cframewnd.md). -For more information on using `CToolTipCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using CToolTipCtrl](../../mfc/using-ctooltipctrl.md). +For more information on using `CToolTipCtrl`, see [Controls](../../mfc/controls-mfc.md) and [Using `CToolTipCtrl`](../../mfc/using-ctooltipctrl.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWnd](../../mfc/reference/cwnd-class.md) +[`CWnd`](../../mfc/reference/cwnd-class.md) `CToolTipCtrl` ## Requirements -**Header:** afxcmn.h +**Header:** `afxcmn.h` -## CToolTipCtrl::Activate +## `CToolTipCtrl::Activate` -Call this function to activate or deactivate a tool tip control. +Call this function to activate or deactivate a tooltip control. ```cpp void Activate(BOOL bActivate); @@ -97,22 +96,22 @@ void Activate(BOOL bActivate); ### Parameters -*bActivate*
-Specifies whether the tool tip control is to be activated or deactivated. +*`bActivate`*\ +Specifies whether the tooltip control is to be activated or deactivated. ### Remarks -If *bActivate* is TRUE, the control is activated; if FALSE, it is deactivated. +If *`bActivate`* is `TRUE`, the control is activated; if `FALSE`, it is deactivated. -When a tool tip control is active, the tool tip information appears when the cursor is on a tool that is registered with the control; when it is inactive, the tool tip information does not appear, even when the cursor is on a tool. +When a tooltip control is active, the tooltip information appears when the cursor is on a tool that is registered with the control; when it is inactive, the tooltip information does not appear, even when the cursor is on a tool. ### Example - See the example for [CPropertySheet::GetTabControl](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). + See the example for [`CPropertySheet::GetTabControl`](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). -## CToolTipCtrl::AddTool +## `CToolTipCtrl::AddTool` -Registers a tool with the tool tip control. +Registers a tool with the tooltip control. ``` BOOL AddTool( @@ -130,20 +129,20 @@ BOOL AddTool( ### Parameters -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDText*
+*`nIDText`*\ ID of the string resource that contains the text for the tool. -*lpRectTool*
-Pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure containing coordinates of the tool's bounding rectangle. The coordinates are relative to the upper-left corner of the client area of the window identified by *pWnd*. +*`lpRectTool`*\ +Pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure containing coordinates of the tool's bounding rectangle. The coordinates are relative to the upper-left corner of the client area of the window identified by *`pWnd`*. -*nIDTool*
+*`nIDTool`*\ ID of the tool. -*lpszText*
-Pointer to the text for the tool. If this parameter contains the value LPSTR_TEXTCALLBACK, TTN_NEEDTEXT notification messages go to the parent of the window that *pWnd* points to. +*`lpszText`*\ +Pointer to the text for the tool. If this parameter contains the value `LPSTR_TEXTCALLBACK`, `TTN_NEEDTEXT` notification messages go to the parent of the window that *`pWnd`* points to. ### Return Value @@ -151,18 +150,18 @@ Nonzero if successful; otherwise 0. ### Remarks -The *lpRectTool* and *nIDTool* parameters must both be valid, or if *lpRectTool* is NULL, *nIDTool* must be 0. +The *`lpRectTool`* and *`nIDTool`* parameters must both be valid, or if *`lpRectTool`* is `NULL`, *`nIDTool`* must be 0. -A tool tip control can be associated with more than one tool. Call this function to register a tool with the tool tip control, so that the information stored in the tool tip is displayed when the cursor is on the tool. +A tooltip control can be associated with more than one tool. Call this function to register a tool with the tooltip control, so that the information stored in the tooltip is displayed when the cursor is on the tool. > [!NOTE] -> You cannot set a tool tip to a static control using `AddTool`. +> You cannot set a tooltip to a static control using `AddTool`. ### Example - See the example for [CPropertySheet::GetTabControl](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). + See the example for [`CPropertySheet::GetTabControl`](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). -## CToolTipCtrl::AdjustRect +## `CToolTipCtrl::AdjustRect` Converts between a tooltip control's text display rectangle and its window rectangle. @@ -174,11 +173,11 @@ BOOL AdjustRect( ### Parameters -*lprc*
-Pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure that holds either a tool tip window rectangle or a text display rectangle. +*`lprc`*\ +Pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that holds either a tooltip window rectangle or a text display rectangle. -*bLarger*
-If TRUE, *lprc* is used to specify a text-display rectangle, and it receives the corresponding window rectangle. If FALSE, *lprc* is used to specify a window rectangle, and it receives the corresponding text display rectangle. +*`bLarger`*\ +If `TRUE`, *`lprc`* is used to specify a text-display rectangle, and it receives the corresponding window rectangle. If `FALSE`, *`lprc`* is used to specify a window rectangle, and it receives the corresponding text display rectangle. ### Return Value @@ -186,13 +185,13 @@ Nonzero if the rectangle is successfully adjusted; otherwise 0. ### Remarks -This member function calculates a tool tip control's text display rectangle from its window rectangle, or the tool tip window rectangle needed to display a specified text display rectangle. +This member function calculates a tooltip control's text display rectangle from its window rectangle, or the tooltip window rectangle needed to display a specified text display rectangle. -This member function implements the behavior of the Win32 message [TTM_ADJUSTRECT](/windows/win32/Controls/ttm-adjustrect), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_ADJUSTRECT`](/windows/win32/Controls/ttm-adjustrect), as described in the Windows SDK. -## CToolTipCtrl::Create +## `CToolTipCtrl::Create` -Creates a tool tip control and attaches it to a `CToolTipCtrl` object. +Creates a tooltip control and attaches it to a `CToolTipCtrl` object. ``` virtual BOOL Create(CWnd* pParentWnd, DWORD dwStyle = 0); @@ -200,11 +199,11 @@ virtual BOOL Create(CWnd* pParentWnd, DWORD dwStyle = 0); ### Parameters -*pParentWnd*
-Specifies the tool tip control's parent window, usually a `CDialog`. It must not be NULL. +*`pParentWnd`*\ +Specifies the tooltip control's parent window, usually a `CDialog`. It must not be `NULL`. -*dwStyle*
-Specifies the tool tip control's style. See the **Remarks** section for more information. +*`dwStyle`*\ +Specifies the tooltip control's style. See the **Remarks** section for more information. ### Return Value @@ -212,26 +211,26 @@ Nonzero if the `CToolTipCtrl` object is successfully created; otherwise 0. ### Remarks -You construct a `CToolTipCtrl` in two steps. First, call the constructor to construct the `CToolTipCtrl` object, and then call `Create` to create the tool tip control and attach it to the `CToolTipCtrl` object. +You construct a `CToolTipCtrl` in two steps. First, call the constructor to construct the `CToolTipCtrl` object, and then call `Create` to create the tooltip control and attach it to the `CToolTipCtrl` object. -The *dwStyle* parameter can be any combination of [Window Styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). In addition, a tool tip control has two class-specific styles: TTS_ALWAYSTIP and TTS_NOPREFIX. +The *`dwStyle`* parameter can be any combination of [Window Styles](../../mfc/reference/styles-used-by-mfc.md#window-styles). In addition, a tooltip control has two class-specific styles: `TTS_ALWAYSTIP` and `TTS_NOPREFIX`. |Style|Meaning| |-----------|-------------| -|TTS_ALWAYSTIP|Specifies that the tool tip will appear when the cursor is on a tool, regardless of whether the tool tip control's owner window is active or inactive. Without this style, the tool tip control appears when the tool's owner window is active, but not when it is inactive.| -|TTS_NOPREFIX|This style prevents the system from stripping the ampersand (&) character from a string. If a tool tip control does not have the TTS_NOPREFIX style, the system automatically strips ampersand characters, allowing an application to use the same string as both a menu item and as text in a tool tip control.| +|`TTS_ALWAYSTIP`|Specifies that the tooltip will appear when the cursor is on a tool, regardless of whether the tooltip control's owner window is active or inactive. Without this style, the tooltip control appears when the tool's owner window is active, but not when it is inactive.| +|`TTS_NOPREFIX`|This style prevents the system from stripping the ampersand (`&`) character from a string. If a tooltip control does not have the `TTS_NOPREFIX` style, the system automatically strips ampersand characters, allowing an application to use the same string as both a menu item and as text in a tooltip control.| -A tool tip control has the WS_POPUP and WS_EX_TOOLWINDOW window styles, regardless of whether you specify them when creating the control. +A tooltip control has the `WS_POPUP` and `WS_EX_TOOLWINDOW` window styles, regardless of whether you specify them when creating the control. -To create a tool tip control with extended windows styles, call [CToolTipCtrl::CreateEx](#createex) instead of `Create`. +To create a tooltip control with extended windows styles, call [`CToolTipCtrl::CreateEx`](#createex) instead of `Create`. ### Example - See the example for [CPropertySheet::GetTabControl](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). + See the example for [`CPropertySheet::GetTabControl`](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). -## CToolTipCtrl::CreateEx +## `CToolTipCtrl::CreateEx` -Creates a control (a child window) and associate it with the `CToolTipCtrl` object. +Creates a control (a child window) and associates it with the `CToolTipCtrl` object. ``` virtual BOOL CreateEx( @@ -242,14 +241,14 @@ virtual BOOL CreateEx( ### Parameters -*pParentWnd*
+*`pParentWnd`*\ A pointer to the window that is the control's parent. -*dwStyle*
-Specifies the tool tip control's style. See the **Remarks** section of [Create](#create) for more information. +*`dwStyle`*\ +Specifies the tooltip control's style. See the **Remarks** section of [`Create`](#create) for more information. -*dwStyleEx*
-Specifies the extended style of the control being created. For a list of extended Windows styles, see the *dwExStyle* parameter for [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwStyleEx`*\ +Specifies the extended style of the control being created. For a list of extended Windows styles, see the *`dwExStyle`* parameter for [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. ### Return Value @@ -257,9 +256,9 @@ Nonzero if successful otherwise 0. ### Remarks -Use `CreateEx` instead of `Create` to apply extended Windows styles, specified by the Windows extended style preface **WS_EX_**. +Use `CreateEx` instead of `Create` to apply extended Windows styles, specified by the Windows extended style preface **`WS_EX_`**. -## CToolTipCtrl::CToolTipCtrl +## `CToolTipCtrl::CToolTipCtrl` Constructs a `CToolTipCtrl` object. @@ -275,9 +274,9 @@ You must call `Create` after constructing the object. [!code-cpp[NVC_MFCControlLadenDialog#74](../../mfc/codesnippet/cpp/ctooltipctrl-class_1.h)] -## CToolTipCtrl::DelTool +## `CToolTipCtrl::DelTool` -Removes the tool specified by *pWnd* and *nIDTool* from the collection of tools supported by a tool tip control. +Removes the tool specified by *`pWnd`* and *`nIDTool`* from the collection of tools supported by a tooltip control. ```cpp void DelTool( @@ -287,15 +286,15 @@ void DelTool( ### Parameters -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDTool*
+*`nIDTool`*\ ID of the tool. -## CToolTipCtrl::GetBubbleSize +## `CToolTipCtrl::GetBubbleSize` -Retrieves the size of the tool tip. +Retrieves the size of the tooltip. ``` CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const; @@ -303,18 +302,18 @@ CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const; ### Parameters -*lpToolInfo*
-A pointer to the tool tip's [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure. +*`lpToolInfo`*\ +A pointer to the tooltip's [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure. ### Return Value -The size of the tool tip. +The size of the tooltip. ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETBUBBLESIZE](/windows/win32/Controls/ttm-getbubblesize), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETBUBBLESIZE`](/windows/win32/Controls/ttm-getbubblesize), as described in the Windows SDK. -## CToolTipCtrl::GetCurrentTool +## `CToolTipCtrl::GetCurrentTool` Retrieves information, such as the size, position, and text, of the tooltip window displayed by the current tooltip control. @@ -324,16 +323,16 @@ BOOL GetCurrentTool(LPTOOLINFO lpToolInfo) const; ### Parameters -*lpToolInfo*\ -[out] Pointer to a [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that receives information about the current tooltip window. +*`lpToolInfo`*\ +[out] Pointer to a [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that receives information about the current tooltip window. ### Return Value -TRUE if the information is retrieved successfully; otherwise, FALSE. +`TRUE` if the information is retrieved successfully; otherwise, `FALSE`. ### Remarks -This method sends the [TTM_GETCURRENTTOOL](/windows/win32/Controls/ttm-getcurrenttool) message, which is described in the Windows SDK. +This method sends the [`TTM_GETCURRENTTOOL`](/windows/win32/Controls/ttm-getcurrenttool) message, which is described in the Windows SDK. ### Example @@ -341,9 +340,9 @@ The following code example retrieves information about the current tooltip windo [!code-cpp[NVC_MFC_CToolBarCtrl_s1#6](../../mfc/reference/codesnippet/cpp/ctooltipctrl-class_2.cpp)] -## CToolTipCtrl::GetDelayTime +## `CToolTipCtrl::GetDelayTime` -Retrieves the initial, pop-up, and reshow durations currently set for a tool tip control. +Retrieves the initial, pop-up, and reshow durations currently set for a tooltip control. ``` int GetDelayTime(DWORD dwDuration) const; @@ -351,14 +350,14 @@ int GetDelayTime(DWORD dwDuration) const; ### Parameters -*dwDuration*
+*`dwDuration`*\ Flag that specifies which duration value will be retrieved. This parameter can be one of the following values: -- TTDT_AUTOPOP Retrieve the length of time the tool tip window remains visible if the pointer is stationary within a tool's bounding rectangle. +- `TTDT_AUTOPOP` Retrieve the length of time the tooltip window remains visible if the pointer is stationary within a tool's bounding rectangle. -- TTDT_INITIAL Retrieve the length of time the pointer must remain stationary within a tool's bounding rectangle before the tool tip window appears. +- `TTDT_INITIAL` Retrieve the length of time the pointer must remain stationary within a tool's bounding rectangle before the tooltip window appears. -- TTDT_RESHOW Retrieve the length of time it takes for subsequent tool tip windows to appear as the pointer moves from one tool to another. +- `TTDT_RESHOW` Retrieve the length of time it takes for subsequent tooltip windows to appear as the pointer moves from one tool to another. ### Return Value @@ -366,11 +365,11 @@ The specified delay time, in milliseconds ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETDELAYTIME](/windows/win32/Controls/ttm-getdelaytime), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETDELAYTIME`](/windows/win32/Controls/ttm-getdelaytime), as described in the Windows SDK. -## CToolTipCtrl::GetMargin +## `CToolTipCtrl::GetMargin` -Retrieves the top, left, bottom, and right margins set for a tool tip window. +Retrieves the top, left, bottom, and right margins set for a tooltip window. ```cpp void GetMargin(LPRECT lprc) const; @@ -378,23 +377,23 @@ void GetMargin(LPRECT lprc) const; ### Parameters -*lprc*
-Address of a `RECT` structure that will receive the margin information. The members of the [RECT](/windows/win32/api/windef/ns-windef-rect) structure do not define a bounding rectangle. For the purpose of this message, the structure members are interpreted as follows: +*`lprc`*\ +Address of a `RECT` structure that will receive the margin information. The members of the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure do not define a bounding rectangle. For the purpose of this message, the structure members are interpreted as follows: |Member|Representation| |------------|--------------------| -|`top`|Distance between top border and top of tool tip text, in pixels.| +|`top`|Distance between top border and top of tooltip text, in pixels.| |`left`|Distance between left border and left end of tip text, in pixels.| |`bottom`|Distance between bottom border and bottom of tip text, in pixels.| |`right`|Distance between right border and right end of tip text, in pixels.| ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETMARGIN](/windows/win32/Controls/ttm-getmargin), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETMARGIN`](/windows/win32/Controls/ttm-getmargin), as described in the Windows SDK. -## CToolTipCtrl::GetMaxTipWidth +## `CToolTipCtrl::GetMaxTipWidth` -Retrieves the maximum width for a tool tip window. +Retrieves the maximum width for a tooltip window. ``` int GetMaxTipWidth() const; @@ -402,15 +401,15 @@ int GetMaxTipWidth() const; ### Return Value -The maximum width for a tool tip window. +The maximum width for a tooltip window. ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETMAXTIPWIDTH](/windows/win32/Controls/ttm-getmaxtipwidth), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETMAXTIPWIDTH`](/windows/win32/Controls/ttm-getmaxtipwidth), as described in the Windows SDK. -## CToolTipCtrl::GetText +## `CToolTipCtrl::GetText` -Retrieves the text that a tool tip control maintains for a tool. +Retrieves the text that a tooltip control maintains for a tool. ```cpp void GetText( @@ -421,22 +420,22 @@ void GetText( ### Parameters -*str*
+*`str`*\ Reference to a `CString` object that receives the tool's text. -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDTool*
+*`nIDTool`*\ ID of the tool. ### Remarks -The *pWnd* and *nIDTool* parameters identify the tool. If that tool has been previously registered with the tool tip control through a previous call to `CToolTipCtrl::AddTool`, the object referenced by the *str* parameter is assigned the tool's text. +The *`pWnd`* and *`nIDTool`* parameters identify the tool. If that tool has been previously registered with the tooltip control through a previous call to `CToolTipCtrl::AddTool`, the object referenced by the *`str`* parameter is assigned the tool's text. -## CToolTipCtrl::GetTipBkColor +## `CToolTipCtrl::GetTipBkColor` -Retrieves the background color in a tool tip window. +Retrieves the background color in a tooltip window. ``` COLORREF GetTipBkColor() const; @@ -444,15 +443,15 @@ COLORREF GetTipBkColor() const; ### Return Value -A [COLORREF](/windows/win32/gdi/colorref) value that represents the background color. +A [`COLORREF`](/windows/win32/gdi/colorref) value that represents the background color. ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETTIPBKCOLOR](/windows/win32/Controls/ttm-gettipbkcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETTIPBKCOLOR`](/windows/win32/Controls/ttm-gettipbkcolor), as described in the Windows SDK. -## CToolTipCtrl::GetTipTextColor +## `CToolTipCtrl::GetTipTextColor` -Retrieves the text color in a tool tip window. +Retrieves the text color in a tooltip window. ``` COLORREF GetTipTextColor() const; @@ -460,13 +459,13 @@ COLORREF GetTipTextColor() const; ### Return Value -A [COLORREF](/windows/win32/gdi/colorref) value that represents the text color. +A [`COLORREF`](/windows/win32/gdi/colorref) value that represents the text color. ### Remarks -This member function implements the behavior of the Win32 message [TTM_GETTIPTEXTCOLOR](/windows/win32/Controls/ttm-gettiptextcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_GETTIPTEXTCOLOR`](/windows/win32/Controls/ttm-gettiptextcolor), as described in the Windows SDK. -## CToolTipCtrl::GetTitle +## `CToolTipCtrl::GetTitle` Retrieves the title of the current tooltip control. @@ -476,16 +475,16 @@ void GetTitle(PTTGETTITLE pttgt) const; ### Parameters -*pttgt*\ -[out] Pointer to a [TTGETTITLE](/windows/win32/api/commctrl/ns-commctrl-ttgettitle) structure that contains information about the ToolTip control. When this method returns, the *pszTitle* member of the [TTGETTITLE](/windows/win32/api/commctrl/ns-commctrl-ttgettitle) structure points to the text of the title. +*`pttgt`*\ +[out] Pointer to a [`TTGETTITLE`](/windows/win32/api/commctrl/ns-commctrl-ttgettitle) structure that contains information about the tooltip control. When this method returns, the *`pszTitle`* member of the [`TTGETTITLE`](/windows/win32/api/commctrl/ns-commctrl-ttgettitle) structure points to the text of the title. ### Remarks -This method sends the [TTM_GETTITLE](/windows/win32/Controls/ttm-gettitle) message, which is described in the Windows SDK. +This method sends the [`TTM_GETTITLE`](/windows/win32/Controls/ttm-gettitle) message, which is described in the Windows SDK. -## CToolTipCtrl::GetToolCount +## `CToolTipCtrl::GetToolCount` -Retrieves a count of the tools registered with the tool tip control. +Retrieves a count of the tools registered with the tooltip control. ``` int GetToolCount() const; @@ -493,11 +492,11 @@ int GetToolCount() const; ### Return Value -A count of tools registered with the tool tip control. +A count of tools registered with the tooltip control. -## CToolTipCtrl::GetToolInfo +## `CToolTipCtrl::GetToolInfo` -Retrieves the information that a tool tip control maintains about a tool. +Retrieves the information that a tooltip control maintains about a tool. ``` BOOL GetToolInfo( @@ -508,13 +507,13 @@ BOOL GetToolInfo( ### Parameters -*ToolInfo*
+*`ToolInfo`*\ Reference to a `TOOLINFO` object that receives the tool's text. -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDTool*
+*`nIDTool`*\ ID of the tool. ### Return Value @@ -523,9 +522,9 @@ Nonzero if successful; otherwise 0. ### Remarks -The `hwnd` and `uId` members of the [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure referenced by *CToolInfo* identify the tool. If that tool has been registered with the tool tip control through a previous call to `AddTool`, the `TOOLINFO` structure is filled with information about the tool. +The `hwnd` and `uId` members of the [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure referenced by *`CToolInfo`* identify the tool. If that tool has been registered with the tooltip control through a previous call to `AddTool`, the `TOOLINFO` structure is filled with information about the tool. -## CToolTipCtrl::HitTest +## `CToolTipCtrl::HitTest` Tests a point to determine whether it is within the bounding rectangle of the given tool and, if so, retrieve information about the tool. @@ -538,14 +537,14 @@ BOOL HitTest( ### Parameters -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*pt*
+*`pt`*\ Pointer to a `CPoint` object containing the coordinates of the point to be tested. -*lpToolInfo*
-Pointer to [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that contains information about the tool. +*`lpToolInfo`*\ +Pointer to [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that contains information about the tool. ### Return Value @@ -553,7 +552,7 @@ Nonzero if the point specified by the hit-test information is within the tool's ### Remarks -If this function returns a nonzero value, the structure pointed to by *lpToolInfo* is filled with information on the tool within whose rectangle the point lies. +If this function returns a nonzero value, the structure pointed to by *`lpToolInfo`* is filled with information on the tool within whose rectangle the point lies. The `TTHITTESTINFO` structure is defined as follows: @@ -575,11 +574,11 @@ typedef struct _TT_HITTESTINFO { // tthti - `ti` - Information about the tool. For more information about the `TOOLINFO` structure, see [CToolTipCtrl::GetToolInfo](#gettoolinfo). + Information about the tool. For more information about the `TOOLINFO` structure, see [`CToolTipCtrl::GetToolInfo`](#gettoolinfo). -## CToolTipCtrl::Pop +## `CToolTipCtrl::Pop` -Removes a displayed tool tip window from the view. +Removes a displayed tooltip window from the view. ```cpp void Pop(); @@ -587,9 +586,9 @@ void Pop(); ### Remarks -This member function implements the behavior of the Win32 message [TTM_POP](/windows/win32/Controls/ttm-pop), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_POP`](/windows/win32/Controls/ttm-pop), as described in the Windows SDK. -## CToolTipCtrl::Popup +## `CToolTipCtrl::Popup` Causes the current tooltip control to display at the coordinates of the last mouse message. @@ -599,7 +598,7 @@ void Popup(); ### Remarks -This method sends the [TTM_POPUP](/windows/win32/Controls/ttm-popup) message, which is described in the Windows SDK. +This method sends the [`TTM_POPUP`](/windows/win32/Controls/ttm-popup) message, which is described in the Windows SDK. ### Example @@ -607,9 +606,9 @@ The following code example displays a tooltip window. [!code-cpp[NVC_MFC_CToolBarCtrl_s1#7](../../mfc/reference/codesnippet/cpp/ctooltipctrl-class_3.cpp)] -## CToolTipCtrl::RelayEvent +## `CToolTipCtrl::RelayEvent` -Passes a mouse message to a tool tip control for processing. +Passes a mouse message to a tooltip control for processing. ```cpp void RelayEvent(LPMSG lpMsg); @@ -617,26 +616,26 @@ void RelayEvent(LPMSG lpMsg); ### Parameters -*lpMsg*
-Pointer to a [MSG](/windows/win32/api/winuser/ns-winuser-msg) structure that contains the message to relay. +*`lpMsg`*\ +Pointer to a [`MSG`](/windows/win32/api/winuser/ns-winuser-msg) structure that contains the message to relay. ### Remarks -A tool tip control processes only the following messages, which are sent to it by `RelayEvent`: +A tooltip control processes only the following messages, which are sent to it by `RelayEvent`: -|WM_LBUTTONDOWN|WM_MOUSEMOVE| +|`WM_LBUTTONDOWN`|`WM_MOUSEMOVE`| |---------------------|-------------------| -|WM_LBUTTONUP|WM_RBUTTONDOWN| -|WM_MBUTTONDOWN|WM_RBUTTONUP| -|WM_MBUTTONUP|| +|`WM_LBUTTONUP`|`WM_RBUTTONDOWN`| +|`WM_MBUTTONDOWN`|`WM_RBUTTONUP`| +|`WM_MBUTTONUP`|| ### Example - See the example for [CPropertySheet::GetTabControl](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). + See the example for [`CPropertySheet::GetTabControl`](../../mfc/reference/cpropertysheet-class.md#gettabcontrol). -## CToolTipCtrl::SetDelayTime +## `CToolTipCtrl::SetDelayTime` -Sets the delay time for a tool tip control. +Sets the delay time for a tooltip control. ```cpp void SetDelayTime(UINT nDelay); @@ -648,22 +647,22 @@ void SetDelayTime( ### Parameters -*nDelay*
+*`nDelay`*\ Specifies the new delay time, in milliseconds. -*dwDuration*
-Flag that specifies which duration value will be retrieved. See [CToolTipCtrl::GetDelayTime](#getdelaytime) for a description of the valid values. +*`dwDuration`*\ +Flag that specifies which duration value will be retrieved. See [`CToolTipCtrl::GetDelayTime`](#getdelaytime) for a description of the valid values. -*iTime*
+*`iTime`*\ The specified delay time, in milliseconds. ### Remarks -The delay time is the length of time the cursor must remain on a tool before the tool tip window appears. The default delay time is 500 milliseconds. +The delay time is the length of time the cursor must remain on a tool before the tooltip window appears. The default delay time is 500 milliseconds. -## CToolTipCtrl::SetMargin +## `CToolTipCtrl::SetMargin` -Sets the top, left, bottom, and right margins for a tool tip window. +Sets the top, left, bottom, and right margins for a tooltip window. ```cpp void SetMargin(LPRECT lprc); @@ -671,16 +670,16 @@ void SetMargin(LPRECT lprc); ### Parameters -*lprc*
-Address of a `RECT` structure that contains the margin information to be set. The members of the `RECT` structure do not define a bounding rectangle. See [CToolTipCtrl::GetMargin](#getmargin) for a description of the margin information. +*`lprc`*\ +Address of a `RECT` structure that contains the margin information to be set. The members of the `RECT` structure do not define a bounding rectangle. See [`CToolTipCtrl::GetMargin`](#getmargin) for a description of the margin information. ### Remarks -This member function implements the behavior of the Win32 message [TTM_SETMARGIN](/windows/win32/Controls/ttm-setmargin), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_SETMARGIN`](/windows/win32/Controls/ttm-setmargin), as described in the Windows SDK. -## CToolTipCtrl::SetMaxTipWidth +## `CToolTipCtrl::SetMaxTipWidth` -Sets the maximum width for a tool tip window. +Sets the maximum width for a tooltip window. ``` int SetMaxTipWidth(int iWidth); @@ -688,8 +687,8 @@ int SetMaxTipWidth(int iWidth); ### Parameters -*iWidth*
-The maximum tool tip window width to be set. +*`iWidth`*\ +The maximum tooltip window width to be set. ### Return Value @@ -697,11 +696,11 @@ The previous maximum tip width. ### Remarks -This member function implements the behavior of the Win32 message [TTM_SETMAXTIPWIDTH](/windows/win32/Controls/ttm-setmaxtipwidth), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_SETMAXTIPWIDTH`](/windows/win32/Controls/ttm-setmaxtipwidth), as described in the Windows SDK. -## CToolTipCtrl::SetTipBkColor +## `CToolTipCtrl::SetTipBkColor` -Sets the background color in a tool tip window. +Sets the background color in a tooltip window. ```cpp void SetTipBkColor(COLORREF clr); @@ -709,16 +708,16 @@ void SetTipBkColor(COLORREF clr); ### Parameters -*clr*
+*`clr`*\ The new background color. ### Remarks -This member function implements the behavior of the Win32 message [TTM_SETTIPBKCOLOR](/windows/win32/Controls/ttm-settipbkcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_SETTIPBKCOLOR`](/windows/win32/Controls/ttm-settipbkcolor), as described in the Windows SDK. -## CToolTipCtrl::SetTipTextColor +## `CToolTipCtrl::SetTipTextColor` -Sets the text color in a tool tip window. +Sets the text color in a tooltip window. ```cpp void SetTipTextColor(COLORREF clr); @@ -726,16 +725,16 @@ void SetTipTextColor(COLORREF clr); ### Parameters -*clr*
+*`clr`*\ The new text color. ### Remarks -This member function implements the behavior of the Win32 message [TTM_SETTIPTEXTCOLOR](/windows/win32/Controls/ttm-settiptextcolor), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_SETTIPTEXTCOLOR`](/windows/win32/Controls/ttm-settiptextcolor), as described in the Windows SDK. -## CToolTipCtrl::SetTitle +## `CToolTipCtrl::SetTitle` -Adds a standard icon and title string to a tool tip. +Adds a standard icon and title string to a tooltip. ``` BOOL SetTitle( @@ -745,10 +744,10 @@ BOOL SetTitle( ### Parameters -*uIcon*
-See *icon* in [TTM_SETTITLE](/windows/win32/Controls/ttm-settitle) in the Windows SDK. +*`uIcon`*\ +See *`icon`* in [`TTM_SETTITLE`](/windows/win32/Controls/ttm-settitle) in the Windows SDK. -*lpstrTitle*
+*`lpstrTitle`*\ Pointer to the title string. ### Return Value @@ -757,11 +756,11 @@ Nonzero if successful; otherwise 0. ### Remarks -This member function implements the behavior of the Win32 message [TTM_SETTITLE](/windows/win32/Controls/ttm-settitle), as described in the Windows SDK. +This member function implements the behavior of the Win32 message [`TTM_SETTITLE`](/windows/win32/Controls/ttm-settitle), as described in the Windows SDK. -## CToolTipCtrl::SetToolInfo +## `CToolTipCtrl::SetToolInfo` -Sets the information that a tool tip maintains for a tool. +Sets the information that a tooltip maintains for a tool. ```cpp void SetToolInfo(LPTOOLINFO lpToolInfo); @@ -769,10 +768,10 @@ void SetToolInfo(LPTOOLINFO lpToolInfo); ### Parameters -*lpToolInfo*
-A pointer to a [TOOLINFO](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that specifies the information to set. +*`lpToolInfo`*\ +A pointer to a [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure that specifies the information to set. -## CToolTipCtrl::SetToolRect +## `CToolTipCtrl::SetToolRect` Sets a new bounding rectangle for a tool. @@ -785,18 +784,18 @@ void SetToolRect( ### Parameters -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDTool*
+*`nIDTool`*\ ID of the tool. -*lpRect*
-Pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure specifying the new bounding rectangle. +*`lpRect`*\ +Pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure specifying the new bounding rectangle. -## CToolTipCtrl::SetWindowTheme +## `CToolTipCtrl::SetWindowTheme` -Sets the visual style of the tool tip window. +Sets the visual style of the tooltip window. ``` HRESULT SetWindowTheme(LPCWSTR pszSubAppName); @@ -804,7 +803,7 @@ HRESULT SetWindowTheme(LPCWSTR pszSubAppName); ### Parameters -*pszSubAppName*
+*`pszSubAppName`*\ A pointer to a Unicode string that contains the visual style to set. ### Return Value @@ -813,9 +812,9 @@ The return value is not used. ### Remarks -This member function emulates the functionality of the [TTM_SETWINDOWTHEME](/windows/win32/Controls/ttm-setwindowtheme) message, as described in the Windows SDK. +This member function emulates the functionality of the [`TTM_SETWINDOWTHEME`](/windows/win32/Controls/ttm-setwindowtheme) message, as described in the Windows SDK. -## CToolTipCtrl::Update +## `CToolTipCtrl::Update` Forces the current tool to be redrawn. @@ -823,9 +822,9 @@ Forces the current tool to be redrawn. void Update(); ``` -## CToolTipCtrl::UpdateTipText +## `CToolTipCtrl::UpdateTipText` -Updates the tool tip text for this control's tools. +Updates the tooltip text for this control's tools. ```cpp void UpdateTipText( @@ -841,20 +840,20 @@ void UpdateTipText( ### Parameters -*lpszText*
+*`lpszText`*\ Pointer to the text for the tool. -*pWnd*
+*`pWnd`*\ Pointer to the window that contains the tool. -*nIDTool*
+*`nIDTool`*\ ID of the tool. -*nIDText*
+*`nIDText`*\ ID of the string resource that contains the text for the tool. ## See also -[CWnd Class](../../mfc/reference/cwnd-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[CToolBar Class](../../mfc/reference/ctoolbar-class.md) +[`CWnd` Class](../../mfc/reference/cwnd-class.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`CToolBar` Class](../../mfc/reference/ctoolbar-class.md) diff --git a/docs/mfc/reference/ctreectrl-class.md b/docs/mfc/reference/ctreectrl-class.md index 83e6a7fccb..81ce2a29cb 100644 --- a/docs/mfc/reference/ctreectrl-class.md +++ b/docs/mfc/reference/ctreectrl-class.md @@ -2154,7 +2154,7 @@ The *`lParam1`* and *`lParam2`* parameters correspond to the `lParam` member of ### Example [!code-cpp[NVC_MFC_CTreeCtrl#38](../../mfc/reference/codesnippet/cpp/ctreectrl-class_46.cpp)] - +  [!code-cpp[NVC_MFC_CTreeCtrl#39](../../mfc/reference/codesnippet/cpp/ctreectrl-class_47.cpp)] ## See also diff --git a/docs/mfc/reference/ctypedptrarray-class.md b/docs/mfc/reference/ctypedptrarray-class.md index 5bdf3ccd14..db37f7ca4a 100644 --- a/docs/mfc/reference/ctypedptrarray-class.md +++ b/docs/mfc/reference/ctypedptrarray-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CTypedPtrArray Class" title: "CTypedPtrArray Class" -ms.date: "11/04/2016" +description: "Learn more about: CTypedPtrArray Class" +ms.date: 11/04/2016 f1_keywords: ["CTypedPtrArray", "AFXTEMPL/CTypedPtrArray", "AFXTEMPL/CTypedPtrArray::Add", "AFXTEMPL/CTypedPtrArray::Append", "AFXTEMPL/CTypedPtrArray::Copy", "AFXTEMPL/CTypedPtrArray::ElementAt", "AFXTEMPL/CTypedPtrArray::GetAt", "AFXTEMPL/CTypedPtrArray::InsertAt", "AFXTEMPL/CTypedPtrArray::SetAt", "AFXTEMPL/CTypedPtrArray::SetAtGrow"] helpviewer_keywords: ["CTypedPtrArray [MFC], Add", "CTypedPtrArray [MFC], Append", "CTypedPtrArray [MFC], Copy", "CTypedPtrArray [MFC], ElementAt", "CTypedPtrArray [MFC], GetAt", "CTypedPtrArray [MFC], InsertAt", "CTypedPtrArray [MFC], SetAt", "CTypedPtrArray [MFC], SetAtGrow"] -ms.assetid: e3ecdf1a-a889-4156-92dd-ddbd36ccd919 --- # CTypedPtrArray Class @@ -20,7 +19,7 @@ class CTypedPtrArray : public BASE_CLASS #### Parameters *BASE_CLASS*
-Base class of the typed pointer array class; must be an array class ( `CObArray` or `CPtrArray`). +Base class of the typed pointer array class; must be an array class (`CObArray` or `CPtrArray`). *TYPE*
Type of the elements stored in the base-class array. diff --git a/docs/mfc/reference/ctypedptrlist-class.md b/docs/mfc/reference/ctypedptrlist-class.md index 9eefb3d44a..d06daa00f4 100644 --- a/docs/mfc/reference/ctypedptrlist-class.md +++ b/docs/mfc/reference/ctypedptrlist-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CTypedPtrList Class" title: "CTypedPtrList Class" -ms.date: "11/04/2016" +description: "Learn more about: CTypedPtrList Class" +ms.date: 11/04/2016 f1_keywords: ["CTypedPtrList", "AFXTEMPL/CTypedPtrList", "AFXTEMPL/CTypedPtrList::AddHead", "AFXTEMPL/CTypedPtrList::AddTail", "AFXTEMPL/CTypedPtrList::GetAt", "AFXTEMPL/CTypedPtrList::GetHead", "AFXTEMPL/CTypedPtrList::GetNext", "AFXTEMPL/CTypedPtrList::GetPrev", "AFXTEMPL/CTypedPtrList::GetTail", "AFXTEMPL/CTypedPtrList::RemoveHead", "AFXTEMPL/CTypedPtrList::RemoveTail", "AFXTEMPL/CTypedPtrList::SetAt"] helpviewer_keywords: ["CTypedPtrList [MFC], AddHead", "CTypedPtrList [MFC], AddTail", "CTypedPtrList [MFC], GetAt", "CTypedPtrList [MFC], GetHead", "CTypedPtrList [MFC], GetNext", "CTypedPtrList [MFC], GetPrev", "CTypedPtrList [MFC], GetTail", "CTypedPtrList [MFC], RemoveHead", "CTypedPtrList [MFC], RemoveTail", "CTypedPtrList [MFC], SetAt"] -ms.assetid: c273096e-1756-4340-864b-4a08b674a65e --- # CTypedPtrList Class @@ -20,7 +19,7 @@ class CTypedPtrList : public BASE_CLASS #### Parameters *BASE_CLASS*
-Base class of the typed pointer list class; must be a pointer list class ( `CObList` or `CPtrList`). +Base class of the typed pointer list class; must be a pointer list class (`CObList` or `CPtrList`). *TYPE*
Type of the elements stored in the base-class list. @@ -61,7 +60,7 @@ For more information on using `CTypedPtrList`, see the articles [Collections](.. This example creates an instance of `CTypedPtrList`, adds one object, serializes the list to disk, and then deletes the object: [!code-cpp[NVC_MFCCollections#110](../../mfc/codesnippet/cpp/ctypedptrlist-class_1.cpp)] - +  [!code-cpp[NVC_MFCCollections#111](../../mfc/codesnippet/cpp/ctypedptrlist-class_2.cpp)] ## Inheritance Hierarchy diff --git a/docs/mfc/reference/ctypedptrmap-class.md b/docs/mfc/reference/ctypedptrmap-class.md index 03721557f8..1e8ac54c64 100644 --- a/docs/mfc/reference/ctypedptrmap-class.md +++ b/docs/mfc/reference/ctypedptrmap-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CTypedPtrMap Class" title: "CTypedPtrMap Class" -ms.date: "11/04/2016" +description: "Learn more about: CTypedPtrMap Class" +ms.date: 11/04/2016 f1_keywords: ["CTypedPtrMap", "AFXTEMPL/CTypedPtrMap", "AFXTEMPL/CTypedPtrMap::GetNextAssoc", "AFXTEMPL/CTypedPtrMap::Lookup", "AFXTEMPL/CTypedPtrMap::RemoveKey", "AFXTEMPL/CTypedPtrMap::SetAt"] helpviewer_keywords: ["CTypedPtrMap [MFC], GetNextAssoc", "CTypedPtrMap [MFC], Lookup", "CTypedPtrMap [MFC], RemoveKey", "CTypedPtrMap [MFC], SetAt"] -ms.assetid: 9f377385-c6e9-4471-8b40-8fe220c50164 --- # CTypedPtrMap Class @@ -20,7 +19,7 @@ class CTypedPtrMap : public BASE_CLASS #### Parameters *BASE_CLASS*
-Base class of the typed pointer map class; must be a pointer map class ( `CMapPtrToPtr`, `CMapPtrToWord`, `CMapWordToPtr`, or `CMapStringToPtr`). +Base class of the typed pointer map class; must be a pointer map class (`CMapPtrToPtr`, `CMapPtrToWord`, `CMapWordToPtr`, or `CMapStringToPtr`). *KEY*
Class of the object used as the key to the map. diff --git a/docs/mfc/reference/cview-class.md b/docs/mfc/reference/cview-class.md index 35f6eed0e9..42e892ac90 100644 --- a/docs/mfc/reference/cview-class.md +++ b/docs/mfc/reference/cview-class.md @@ -292,7 +292,7 @@ A value from the `DROPEFFECT` enumerated type, which indicates the type of drop - `DROPEFFECT_NONE` The data object cannot be dropped in this window. -- `DROPEFFECT_LINK` for `MK_CONTROL` | `MK_SHIFT` Creates a linkage between the object and its server. +- `DROPEFFECT_LINK` for `MK_CONTROL|MK_SHIFT` Creates a linkage between the object and its server. - `DROPEFFECT_COPY` for `MK_CONTROL` Creates a copy of the dropped object. @@ -346,7 +346,7 @@ A value from the `DROPEFFECT` enumerated type, which indicates the type of drop - `DROPEFFECT_NONE` The data object cannot be dropped in this window. -- `DROPEFFECT_LINK` for `MK_CONTROL` | `MK_SHIFT` Creates a linkage between the object and its server. +- `DROPEFFECT_LINK` for `MK_CONTROL|MK_SHIFT` Creates a linkage between the object and its server. - `DROPEFFECT_COPY` for `MK_CONTROL` Creates a copy of the dropped object. @@ -384,7 +384,7 @@ A value from the `DROPEFFECT` enumerated type, which indicates the type of drop - `DROPEFFECT_NONE` The data object cannot be dropped in this window. -- `DROPEFFECT_LINK` for `MK_CONTROL` | `MK_SHIFT` Creates a linkage between the object and its server. +- `DROPEFFECT_LINK` for `MK_CONTROL|MK_SHIFT` Creates a linkage between the object and its server. - `DROPEFFECT_COPY` for `MK_CONTROL` Creates a copy of the dropped object. @@ -494,7 +494,7 @@ The drop effect that resulted from the drop attempt at the location specified by The default implementation is to do nothing and return a dummy value ( -1 ) to indicate that the framework should call the [`OnDrop`](#ondrop) handler. -Override this function to implement the effect of an right mouse-button drag and drop. Right mouse-button drag and drop typically displays a menu of choices when the right mouse-button is released. +Override this function to implement the effect of a right mouse-button drag and drop. Right mouse-button drag and drop typically displays a menu of choices when the right mouse-button is released. Your override of `OnDropEx` should query for the right mouse-button. You can call [`GetKeyState`](/windows/win32/api/winuser/nf-winuser-getkeystate) or store the right mouse-button state from your [`OnDragEnter`](#ondragenter) handler. diff --git a/docs/mfc/reference/cwinapp-class.md b/docs/mfc/reference/cwinapp-class.md index 21cdc641e9..ac07d50b58 100644 --- a/docs/mfc/reference/cwinapp-class.md +++ b/docs/mfc/reference/cwinapp-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CWinApp Class" title: "CWinApp Class" -ms.date: "07/15/2019" +description: "Learn more about: CWinApp Class" +ms.date: 07/15/2019 f1_keywords: ["CWinApp", "AFXWIN/CWinApp", "AFXWIN/CWinApp::CWinApp", "AFXWIN/CWinApp::AddDocTemplate", "AFXWIN/CWinApp::AddToRecentFileList", "AFXWIN/CWinApp::ApplicationRecoveryCallback", "AFXWIN/CWinApp::CloseAllDocuments", "AFXWIN/CWinApp::CreatePrinterDC", "AFXWIN/CWinApp::DelRegTree", "AFXWIN/CWinApp::DoMessageBox", "AFXWIN/CWinApp::DoWaitCursor", "AFXWIN/CWinApp::EnableD2DSupport", "AFXWIN/CWinApp::EnableHtmlHelp", "AFXWIN/CWinApp::EnableTaskbarInteraction", "AFXWIN/CWinApp::ExitInstance", "AFXWIN/CWinApp::GetApplicationRecoveryParameter", "AFXWIN/CWinApp::GetApplicationRecoveryPingInterval", "AFXWIN/CWinApp::GetApplicationRestartFlags", "AFXWIN/CWinApp::GetAppRegistryKey", "AFXWIN/CWinApp::GetDataRecoveryHandler", "AFXWIN/CWinApp::GetFirstDocTemplatePosition", "AFXWIN/CWinApp::GetHelpMode", "AFXWIN/CWinApp::GetNextDocTemplate", "AFXWIN/CWinApp::GetPrinterDeviceDefaults", "AFXWIN/CWinApp::GetProfileBinary", "AFXWIN/CWinApp::GetProfileInt", "AFXWIN/CWinApp::GetProfileString", "AFXWIN/CWinApp::GetSectionKey", "AFXWIN/CWinApp::HideApplication", "AFXWIN/CWinApp::HtmlHelp", "AFXWIN/CWinApp::InitInstance", "AFXWIN/CWinApp::IsTaskbarInteractionEnabled", "AFXWIN/CWinApp::LoadCursor", "AFXWIN/CWinApp::LoadIcon", "AFXWIN/CWinApp::LoadOEMCursor", "AFXWIN/CWinApp::LoadOEMIcon", "AFXWIN/CWinApp::LoadStandardCursor", "AFXWIN/CWinApp::LoadStandardIcon", "AFXWIN/CWinApp::OnDDECommand", "AFXWIN/CWinApp::OnIdle", "AFXWIN/CWinApp::OpenDocumentFile", "AFXWIN/CWinApp::ParseCommandLine", "AFXWIN/CWinApp::PreTranslateMessage", "AFXWIN/CWinApp::ProcessMessageFilter", "AFXWIN/CWinApp::ProcessShellCommand", "AFXWIN/CWinApp::ProcessWndProcException", "AFXWIN/CWinApp::Register", "AFXWIN/CWinApp::RegisterWithRestartManager", "AFXWIN/CWinApp::ReopenPreviousFilesAtRestart", "AFXWIN/CWinApp::RestartInstance", "AFXWIN/CWinApp::RestoreAutosavedFilesAtRestart", "AFXWIN/CWinApp::Run", "AFXWIN/CWinApp::RunAutomated", "AFXWIN/CWinApp::RunEmbedded", "AFXWIN/CWinApp::SaveAllModified", "AFXWIN/CWinApp::SelectPrinter", "AFXWIN/CWinApp::SetHelpMode", "AFXWIN/CWinApp::SupportsApplicationRecovery", "AFXWIN/CWinApp::SupportsAutosaveAtInterval", "AFXWIN/CWinApp::SupportsAutosaveAtRestart", "AFXWIN/CWinApp::SupportsRestartManager", "AFXWIN/CWinApp::Unregister", "AFXWIN/CWinApp::WinHelp", "AFXWIN/CWinApp::WriteProfileBinary", "AFXWIN/CWinApp::WriteProfileInt", "AFXWIN/CWinApp::WriteProfileString", "AFXWIN/CWinApp::EnableShellOpen", "AFXWIN/CWinApp::LoadStdProfileSettings", "AFXWIN/CWinApp::OnContextHelp", "AFXWIN/CWinApp::OnFileNew", "AFXWIN/CWinApp::OnFileOpen", "AFXWIN/CWinApp::OnFilePrintSetup", "AFXWIN/CWinApp::OnHelp", "AFXWIN/CWinApp::OnHelpFinder", "AFXWIN/CWinApp::OnHelpIndex", "AFXWIN/CWinApp::OnHelpUsing", "AFXWIN/CWinApp::RegisterShellFileTypes", "AFXWIN/CWinApp::SetAppID", "AFXWIN/CWinApp::SetRegistryKey", "AFXWIN/CWinApp::UnregisterShellFileTypes", "AFXWIN/CWinApp::m_bHelpMode", "AFXWIN/CWinApp::m_eHelpType", "AFXWIN/CWinApp::m_hInstance", "AFXWIN/CWinApp::m_lpCmdLine", "AFXWIN/CWinApp::m_nCmdShow", "AFXWIN/CWinApp::m_pActiveWnd", "AFXWIN/CWinApp::m_pszAppID", "AFXWIN/CWinApp::m_pszAppName", "AFXWIN/CWinApp::m_pszExeName", "AFXWIN/CWinApp::m_pszHelpFilePath", "AFXWIN/CWinApp::m_pszProfileName", "AFXWIN/CWinApp::m_pszRegistryKey", "AFXWIN/CWinApp::m_dwRestartManagerSupportFlags", "AFXWIN/CWinApp::m_nAutosaveInterval", "AFXWIN/CWinApp::m_pDataRecoveryHandler"] helpviewer_keywords: ["CWinApp [MFC], CWinApp", "CWinApp [MFC], AddDocTemplate", "CWinApp [MFC], AddToRecentFileList", "CWinApp [MFC], ApplicationRecoveryCallback", "CWinApp [MFC], CloseAllDocuments", "CWinApp [MFC], CreatePrinterDC", "CWinApp [MFC], DelRegTree", "CWinApp [MFC], DoMessageBox", "CWinApp [MFC], DoWaitCursor", "CWinApp [MFC], EnableD2DSupport", "CWinApp [MFC], EnableHtmlHelp", "CWinApp [MFC], EnableTaskbarInteraction", "CWinApp [MFC], ExitInstance", "CWinApp [MFC], GetApplicationRecoveryParameter", "CWinApp [MFC], GetApplicationRecoveryPingInterval", "CWinApp [MFC], GetApplicationRestartFlags", "CWinApp [MFC], GetAppRegistryKey", "CWinApp [MFC], GetDataRecoveryHandler", "CWinApp [MFC], GetFirstDocTemplatePosition", "CWinApp [MFC], GetHelpMode", "CWinApp [MFC], GetNextDocTemplate", "CWinApp [MFC], GetPrinterDeviceDefaults", "CWinApp [MFC], GetProfileBinary", "CWinApp [MFC], GetProfileInt", "CWinApp [MFC], GetProfileString", "CWinApp [MFC], GetSectionKey", "CWinApp [MFC], HideApplication", "CWinApp [MFC], HtmlHelp", "CWinApp [MFC], InitInstance", "CWinApp [MFC], IsTaskbarInteractionEnabled", "CWinApp [MFC], LoadCursor", "CWinApp [MFC], LoadIcon", "CWinApp [MFC], LoadOEMCursor", "CWinApp [MFC], LoadOEMIcon", "CWinApp [MFC], LoadStandardCursor", "CWinApp [MFC], LoadStandardIcon", "CWinApp [MFC], OnDDECommand", "CWinApp [MFC], OnIdle", "CWinApp [MFC], OpenDocumentFile", "CWinApp [MFC], ParseCommandLine", "CWinApp [MFC], PreTranslateMessage", "CWinApp [MFC], ProcessMessageFilter", "CWinApp [MFC], ProcessShellCommand", "CWinApp [MFC], ProcessWndProcException", "CWinApp [MFC], Register", "CWinApp [MFC], RegisterWithRestartManager", "CWinApp [MFC], ReopenPreviousFilesAtRestart", "CWinApp [MFC], RestartInstance", "CWinApp [MFC], RestoreAutosavedFilesAtRestart", "CWinApp [MFC], Run", "CWinApp [MFC], RunAutomated", "CWinApp [MFC], RunEmbedded", "CWinApp [MFC], SaveAllModified", "CWinApp [MFC], SelectPrinter", "CWinApp [MFC], SetHelpMode", "CWinApp [MFC], SupportsApplicationRecovery", "CWinApp [MFC], SupportsAutosaveAtInterval", "CWinApp [MFC], SupportsAutosaveAtRestart", "CWinApp [MFC], SupportsRestartManager", "CWinApp [MFC], Unregister", "CWinApp [MFC], WinHelp", "CWinApp [MFC], WriteProfileBinary", "CWinApp [MFC], WriteProfileInt", "CWinApp [MFC], WriteProfileString", "CWinApp [MFC], EnableShellOpen", "CWinApp [MFC], LoadStdProfileSettings", "CWinApp [MFC], OnContextHelp", "CWinApp [MFC], OnFileNew", "CWinApp [MFC], OnFileOpen", "CWinApp [MFC], OnFilePrintSetup", "CWinApp [MFC], OnHelp", "CWinApp [MFC], OnHelpFinder", "CWinApp [MFC], OnHelpIndex", "CWinApp [MFC], OnHelpUsing", "CWinApp [MFC], RegisterShellFileTypes", "CWinApp [MFC], SetAppID", "CWinApp [MFC], SetRegistryKey", "CWinApp [MFC], UnregisterShellFileTypes", "CWinApp [MFC], m_bHelpMode", "CWinApp [MFC], m_eHelpType", "CWinApp [MFC], m_hInstance", "CWinApp [MFC], m_lpCmdLine", "CWinApp [MFC], m_nCmdShow", "CWinApp [MFC], m_pActiveWnd", "CWinApp [MFC], m_pszAppID", "CWinApp [MFC], m_pszAppName", "CWinApp [MFC], m_pszExeName", "CWinApp [MFC], m_pszHelpFilePath", "CWinApp [MFC], m_pszProfileName", "CWinApp [MFC], m_pszRegistryKey", "CWinApp [MFC], m_dwRestartManagerSupportFlags", "CWinApp [MFC], m_nAutosaveInterval", "CWinApp [MFC], m_pDataRecoveryHandler"] -ms.assetid: e426a3cd-0d15-40d6-bd55-beaa5feb2343 --- # CWinApp Class @@ -962,7 +961,7 @@ HCURSOR LoadOEMCursor(UINT nIDCursor) const; ### Parameters *nIDCursor*
-An **OCR_** manifest constant identifier that specifies a predefined Windows cursor. You must have `#define OEMRESOURCE` before `#include \` to gain access to the **OCR_** constants in WINDOWS.H. +An **OCR_** manifest constant identifier that specifies a predefined Windows cursor. You must have `#define OEMRESOURCE` before `#include ` to gain access to the **OCR_** constants in WINDOWS.H. ### Return Value @@ -975,7 +974,7 @@ Use the `LoadOEMCursor` or [LoadStandardCursor](#loadstandardcursor) member func ### Example [!code-cpp[NVC_MFCWindowing#45](../../mfc/reference/codesnippet/cpp/cwinapp-class_12.h)] - +  [!code-cpp[NVC_MFCWindowing#46](../../mfc/reference/codesnippet/cpp/cwinapp-class_13.cpp)] ## CWinApp::LoadOEMIcon @@ -989,7 +988,7 @@ HICON LoadOEMIcon(UINT nIDIcon) const; ### Parameters *nIDIcon*
-An **OIC_** manifest constant identifier that specifies a predefined Windows icon. You must have `#define OEMRESOURCE` before `#include \` to access the **OIC_** constants in WINDOWS.H. +An **OIC_** manifest constant identifier that specifies a predefined Windows icon. You must have `#define OEMRESOURCE` before `#include ` to access the **OIC_** constants in WINDOWS.H. ### Return Value @@ -1386,7 +1385,7 @@ See [Technical Note 22](../../mfc/tn022-standard-commands-implementation.md) for ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnFileOpen @@ -1406,7 +1405,7 @@ For information on default behavior and guidance on how to override this member ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnFilePrintSetup @@ -1426,7 +1425,7 @@ For information on default behavior and guidance on how to override this member ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnHelp @@ -1535,7 +1534,7 @@ The framework calls this method to open the named [CDocument](../../mfc/referenc ``` virtual CDocument* OpenDocumentFile( - LPCTSTR lpszFileName + LPCTSTR lpszFileName, BOOL bAddToMRU = TRUE); ``` @@ -1621,7 +1620,7 @@ virtual BOOL ProcessMessageFilter( Specifies a hook code. This member function uses the code to determine how to process *lpMsg.* *lpMsg*
-A pointer to a Windows [MSG](/windows/win32/api/winuser/ns-winuser-msg)tructure. +A pointer to a Windows [MSG](/windows/win32/api/winuser/ns-winuser-msg) structure. ### Return Value @@ -1692,7 +1691,7 @@ virtual LRESULT ProcessWndProcException( A pointer to an uncaught exception. *pMsg*
-A [MSG](/windows/win32/api/winuser/ns-winuser-msg)tructure that contains information about the windows message that caused the framework to throw an exception. +A [MSG](/windows/win32/api/winuser/ns-winuser-msg) structure that contains information about the windows message that caused the framework to throw an exception. ### Return Value @@ -1936,7 +1935,7 @@ void SelectPrinter( ### Parameters *hDevNames*
-A handle to a [DEVNAMES](/windows/win32/api/commdlg/ns-commdlg-devnames)tructure that identifies the driver, device, and output port names of a specific printer. +A handle to a [DEVNAMES](/windows/win32/api/commdlg/ns-commdlg-devnames) structure that identifies the driver, device, and output port names of a specific printer. *hDevMode*
A handle to a [DEVMODE](/windows/win32/api/wingdi/ns-wingdi-devmodea) structure that specifies information about the device initialization and environment of a printer. diff --git a/docs/mfc/reference/cwinappex-class.md b/docs/mfc/reference/cwinappex-class.md index c6c79b83af..85b0987718 100644 --- a/docs/mfc/reference/cwinappex-class.md +++ b/docs/mfc/reference/cwinappex-class.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: CWinAppEx Class" title: "CWinAppEx Class" +description: "Learn more about: CWinAppEx Class" ms.date: "11/04/2016" f1_keywords: ["CWinAppEx", "AFXWINAPPEX/CWinAppEx", "AFXWINAPPEX/CWinAppEx::CWinAppEx", "AFXWINAPPEX/CWinAppEx::CleanState", "AFXWINAPPEX/CWinAppEx::EnableLoadWindowPlacement", "AFXWINAPPEX/CWinAppEx::EnableTearOffMenus", "AFXWINAPPEX/CWinAppEx::EnableUserTools", "AFXWINAPPEX/CWinAppEx::ExitInstance", "AFXWINAPPEX/CWinAppEx::GetBinary", "AFXWINAPPEX/CWinAppEx::GetContextMenuManager", "AFXWINAPPEX/CWinAppEx::GetDataVersion", "AFXWINAPPEX/CWinAppEx::GetDataVersionMajor", "AFXWINAPPEX/CWinAppEx::GetDataVersionMinor", "AFXWINAPPEX/CWinAppEx::GetInt", "AFXWINAPPEX/CWinAppEx::GetKeyboardManager", "AFXWINAPPEX/CWinAppEx::GetMouseManager", "AFXWINAPPEX/CWinAppEx::GetObject", "AFXWINAPPEX/CWinAppEx::GetRegSectionPath", "AFXWINAPPEX/CWinAppEx::GetRegistryBase", "AFXWINAPPEX/CWinAppEx::GetSectionBinary", "AFXWINAPPEX/CWinAppEx::GetSectionInt", "AFXWINAPPEX/CWinAppEx::GetSectionObject", "AFXWINAPPEX/CWinAppEx::GetSectionString", "AFXWINAPPEX/CWinAppEx::GetShellManager", "AFXWINAPPEX/CWinAppEx::GetString", "AFXWINAPPEX/CWinAppEx::GetTooltipManager", "AFXWINAPPEX/CWinAppEx::GetUserToolsManager", "AFXWINAPPEX/CWinAppEx::InitContextMenuManager", "AFXWINAPPEX/CWinAppEx::InitKeyboardManager", "AFXWINAPPEX/CWinAppEx::InitMouseManager", "AFXWINAPPEX/CWinAppEx::InitShellManager", "AFXWINAPPEX/CWinAppEx::InitTooltipManager", "AFXWINAPPEX/CWinAppEx::IsResourceSmartUpdate", "AFXWINAPPEX/CWinAppEx::IsStateExists", "AFXWINAPPEX/CWinAppEx::LoadState", "AFXWINAPPEX/CWinAppEx::OnAppContextHelp", "AFXWINAPPEX/CWinAppEx::OnViewDoubleClick", "AFXWINAPPEX/CWinAppEx::OnWorkspaceIdle", "AFXWINAPPEX/CWinAppEx::SaveState", "AFXWINAPPEX/CWinAppEx::SetRegistryBase", "AFXWINAPPEX/CWinAppEx::ShowPopupMenu", "AFXWINAPPEX/CWinAppEx::WriteBinary", "AFXWINAPPEX/CWinAppEx::WriteInt", "AFXWINAPPEX/CWinAppEx::WriteObject", "AFXWINAPPEX/CWinAppEx::WriteSectionBinary", "AFXWINAPPEX/CWinAppEx::WriteSectionInt", "AFXWINAPPEX/CWinAppEx::WriteSectionObject", "AFXWINAPPEX/CWinAppEx::WriteSectionString", "AFXWINAPPEX/CWinAppEx::WriteString", "AFXWINAPPEX/CWinAppEx::LoadCustomState", "AFXWINAPPEX/CWinAppEx::LoadWindowPlacement", "AFXWINAPPEX/CWinAppEx::OnClosingMainFrame", "AFXWINAPPEX/CWinAppEx::PreLoadState", "AFXWINAPPEX/CWinAppEx::PreSaveState", "AFXWINAPPEX/CWinAppEx::ReloadWindowPlacement", "AFXWINAPPEX/CWinAppEx::SaveCustomState", "AFXWINAPPEX/CWinAppEx::StoreWindowPlacement", "AFXWINAPPEX/CWinAppEx::m_bForceImageReset"] helpviewer_keywords: ["CWinAppEx [MFC], CWinAppEx", "CWinAppEx [MFC], CleanState", "CWinAppEx [MFC], EnableLoadWindowPlacement", "CWinAppEx [MFC], EnableTearOffMenus", "CWinAppEx [MFC], EnableUserTools", "CWinAppEx [MFC], ExitInstance", "CWinAppEx [MFC], GetBinary", "CWinAppEx [MFC], GetContextMenuManager", "CWinAppEx [MFC], GetDataVersion", "CWinAppEx [MFC], GetDataVersionMajor", "CWinAppEx [MFC], GetDataVersionMinor", "CWinAppEx [MFC], GetInt", "CWinAppEx [MFC], GetKeyboardManager", "CWinAppEx [MFC], GetMouseManager", "CWinAppEx [MFC], GetObject", "CWinAppEx [MFC], GetRegSectionPath", "CWinAppEx [MFC], GetRegistryBase", "CWinAppEx [MFC], GetSectionBinary", "CWinAppEx [MFC], GetSectionInt", "CWinAppEx [MFC], GetSectionObject", "CWinAppEx [MFC], GetSectionString", "CWinAppEx [MFC], GetShellManager", "CWinAppEx [MFC], GetString", "CWinAppEx [MFC], GetTooltipManager", "CWinAppEx [MFC], GetUserToolsManager", "CWinAppEx [MFC], InitContextMenuManager", "CWinAppEx [MFC], InitKeyboardManager", "CWinAppEx [MFC], InitMouseManager", "CWinAppEx [MFC], InitShellManager", "CWinAppEx [MFC], InitTooltipManager", "CWinAppEx [MFC], IsResourceSmartUpdate", "CWinAppEx [MFC], IsStateExists", "CWinAppEx [MFC], LoadState", "CWinAppEx [MFC], OnAppContextHelp", "CWinAppEx [MFC], OnViewDoubleClick", "CWinAppEx [MFC], OnWorkspaceIdle", "CWinAppEx [MFC], SaveState", "CWinAppEx [MFC], SetRegistryBase", "CWinAppEx [MFC], ShowPopupMenu", "CWinAppEx [MFC], WriteBinary", "CWinAppEx [MFC], WriteInt", "CWinAppEx [MFC], WriteObject", "CWinAppEx [MFC], WriteSectionBinary", "CWinAppEx [MFC], WriteSectionInt", "CWinAppEx [MFC], WriteSectionObject", "CWinAppEx [MFC], WriteSectionString", "CWinAppEx [MFC], WriteString", "CWinAppEx [MFC], LoadCustomState", "CWinAppEx [MFC], LoadWindowPlacement", "CWinAppEx [MFC], OnClosingMainFrame", "CWinAppEx [MFC], PreLoadState", "CWinAppEx [MFC], PreSaveState", "CWinAppEx [MFC], ReloadWindowPlacement", "CWinAppEx [MFC], SaveCustomState", "CWinAppEx [MFC], StoreWindowPlacement", "CWinAppEx [MFC], m_bForceImageReset"] -ms.assetid: a3d3e053-3e22-463f-9444-c73abb1bb9d7 --- -# CWinAppEx Class +# `CWinAppEx` class `CWinAppEx` handles the application state, saves the state to the registry, loads the state from the registry, initializes application managers, and provides links to those same application managers. -For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. +For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ## Syntax -``` +```cpp class CWinAppEx : public CWinApp ``` @@ -24,77 +23,77 @@ class CWinAppEx : public CWinApp |Name|Description| |----------|-----------------| -|[CWinAppEx::CWinAppEx](#cwinappex)|Constructs a `CWinAppEx` object.| +|[`CWinAppEx::CWinAppEx`](#cwinappex)|Constructs a `CWinAppEx` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CWinAppEx::CleanState](#cleanstate)|Removes information about the application from the Windows registry.| -|[CWinAppEx::EnableLoadWindowPlacement](#enableloadwindowplacement)|Specifies whether the application will load the initial size and location of the main frame window from the registry.| -|[CWinAppEx::EnableTearOffMenus](#enabletearoffmenus)|Enables tear-off menus for the application.| -|[CWinAppEx::EnableUserTools](#enableusertools)|Enables the user to create custom menu commands in the application.| -|[CWinAppEx::ExitInstance](#exitinstance)|Called by the framework from within the `Run` member function to exit this instance of the application. (Overrides [CWinApp::ExitInstance](../../mfc/reference/cwinapp-class.md#exitinstance).)| -|[CWinAppEx::GetBinary](#getbinary)|Reads binary data that is associated with the specified registry value.| -|[CWinAppEx::GetContextMenuManager](#getcontextmenumanager)|Returns a pointer to the global [CContextMenuManager](../../mfc/reference/ccontextmenumanager-class.md) object.| -|[CWinAppEx::GetDataVersion](#getdataversion)|| -|[CWinAppEx::GetDataVersionMajor](#getdataversionmajor)|Returns the major version of the application saved in the Windows registry.| -|[CWinAppEx::GetDataVersionMinor](#getdataversionminor)|Returns the minor version of the application saved in the Windows registry.| -|[CWinAppEx::GetInt](#getint)|Reads numeric data that is associated with the specified value from the registry.| -|[CWinAppEx::GetKeyboardManager](#getkeyboardmanager)|Returns a pointer to the global [CKeyboardManager](../../mfc/reference/ckeyboardmanager-class.md) object.| -|[CWinAppEx::GetMouseManager](#getmousemanager)|Returns a pointer to the global [CMouseManager](../../mfc/reference/cmousemanager-class.md) object.| -|[CWinAppEx::GetObject](#getobject)|Reads `CObject`-derived data that is associated with the specified value from the registry.| -|[CWinAppEx::GetRegSectionPath](#getregsectionpath)|Returns a string that is the path of a registry key. This path concatenates the supplied relative path with the application path.| -|[CWinAppEx::GetRegistryBase](#getregistrybase)|Returns the registry path for the application.| -|[CWinAppEx::GetSectionBinary](#getsectionbinary)|Reads binary data that is associated with the specified key and value from the registry.| -|[CWinAppEx::GetSectionInt](#getsectionint)|Reads numeric data from the registry associated with the specified key and value.| -|[CWinAppEx::GetSectionObject](#getsectionobject)|Reads `CObject` data that is associated with the specified key and value from the registry.| -|[CWinAppEx::GetSectionString](#getsectionstring)|Reads string data that is associated with the specified key and value from the registry.| -|[CWinAppEx::GetShellManager](#getshellmanager)|Returns a pointer to the global [CShellManager](../../mfc/reference/cshellmanager-class.md) object.| -|[CWinAppEx::GetString](#getstring)|Reads string data that is associated with the specified value from the registry.| -|[CWinAppEx::GetTooltipManager](#gettooltipmanager)|Returns a pointer to the global [CTooltipManager](../../mfc/reference/ctooltipmanager-class.md) object.| -|[CWinAppEx::GetUserToolsManager](#getusertoolsmanager)|Returns a pointer to the global [CUserToolsManager](../../mfc/reference/cusertoolsmanager-class.md) object.| -|[CWinAppEx::InitContextMenuManager](#initcontextmenumanager)|Initializes the `CContextMenuManager` object.| -|[CWinAppEx::InitKeyboardManager](#initkeyboardmanager)|Initializes the `CKeyboardManager` object.| -|[CWinAppEx::InitMouseManager](#initmousemanager)|Initializes the `CMouseManager` object.| -|[CWinAppEx::InitShellManager](#initshellmanager)|Initializes the `CShellManager` class| -|[CWinAppEx::InitTooltipManager](#inittooltipmanager)|Initializes the `CTooltipManager` class.| -|[CWinAppEx::IsResourceSmartUpdate](#isresourcesmartupdate)|| -|[CWinAppEx::IsStateExists](#isstateexists)|Indicates whether the specified key is in the registry.| -|[CWinAppEx::LoadState](#loadstate)|Loads the application state from the registry.| -|[CWinAppEx::OnAppContextHelp](#onappcontexthelp)|Called by the framework when the user requests context help for the **Customization** dialog box.| -|[CWinAppEx::OnViewDoubleClick](#onviewdoubleclick)|Calls the user-defined command when the user double-clicks anywhere in the application.| -|[CWinAppEx::OnWorkspaceIdle](#onworkspaceidle)|| -|[CWinAppEx::SaveState](#savestate)|Writes the state of the application framework to the Windows registry.| -|[CWinAppEx::SetRegistryBase](#setregistrybase)|Sets the path of the default registry key. This key will serve as a root for all subsequent registry calls.| -|[CWinAppEx::ShowPopupMenu](#showpopupmenu)|Displays a popup menu.| -|[CWinAppEx::WriteBinary](#writebinary)|Writes the binary data to the specified registry value.| -|[CWinAppEx::WriteInt](#writeint)|Writes the numeric data to the specified registry value.| -|[CWinAppEx::WriteObject](#writeobject)|Writes data that is derived from the [CObject Class](../../mfc/reference/cobject-class.md) to the specified registry value.| -|[CWinAppEx::WriteSectionBinary](#writesectionbinary)|Writes the binary data to a value of the specified registry key.| -|[CWinAppEx::WriteSectionInt](#writesectionint)|Writes the numeric data to a value of the specified registry key.| -|[CWinAppEx::WriteSectionObject](#writesectionobject)|Writes data derived from the `CObject` class to a value of the specified registry key.| -|[CWinAppEx::WriteSectionString](#writesectionstring)|Writes the string data to a value of the specified registry key.| -|[CWinAppEx::WriteString](#writestring)|Writes the string data to the specified registry value.| +|[`CWinAppEx::CleanState`](#cleanstate)|Removes information about the application from the Windows registry.| +|[`CWinAppEx::EnableLoadWindowPlacement`](#enableloadwindowplacement)|Specifies whether the application will load the initial size and location of the main frame window from the registry.| +|[`CWinAppEx::EnableTearOffMenus`](#enabletearoffmenus)|Enables tear-off menus for the application.| +|[`CWinAppEx::EnableUserTools`](#enableusertools)|Enables the user to create custom menu commands in the application.| +|[`CWinAppEx::ExitInstance`](#exitinstance)|Called by the framework from within the `Run` member function to exit this instance of the application. (Overrides [`CWinApp::ExitInstance`](../../mfc/reference/cwinapp-class.md#exitinstance).)| +|[`CWinAppEx::GetBinary`](#getbinary)|Reads binary data that is associated with the specified registry value.| +|[`CWinAppEx::GetContextMenuManager`](#getcontextmenumanager)|Returns a pointer to the global [`CContextMenuManager`](../../mfc/reference/ccontextmenumanager-class.md) object.| +|[`CWinAppEx::GetDataVersion`](#getdataversion)|| +|[`CWinAppEx::GetDataVersionMajor`](#getdataversionmajor)|Returns the major version of the application saved in the Windows registry.| +|[`CWinAppEx::GetDataVersionMinor`](#getdataversionminor)|Returns the minor version of the application saved in the Windows registry.| +|[`CWinAppEx::GetInt`](#getint)|Reads numeric data that is associated with the specified value from the registry.| +|[`CWinAppEx::GetKeyboardManager`](#getkeyboardmanager)|Returns a pointer to the global [`CKeyboardManager`](../../mfc/reference/ckeyboardmanager-class.md) object.| +|[`CWinAppEx::GetMouseManager`](#getmousemanager)|Returns a pointer to the global [`CMouseManager`](../../mfc/reference/cmousemanager-class.md) object.| +|[`CWinAppEx::GetObject`](#getobject)|Reads `CObject`-derived data that is associated with the specified value from the registry.| +|[`CWinAppEx::GetRegSectionPath`](#getregsectionpath)|Returns a string that is the path of a registry key. This path concatenates the supplied relative path with the application path.| +|[`CWinAppEx::GetRegistryBase`](#getregistrybase)|Returns the registry path for the application.| +|[`CWinAppEx::GetSectionBinary`](#getsectionbinary)|Reads binary data that is associated with the specified key and value from the registry.| +|[`CWinAppEx::GetSectionInt`](#getsectionint)|Reads numeric data from the registry associated with the specified key and value.| +|[`CWinAppEx::GetSectionObject`](#getsectionobject)|Reads `CObject` data that is associated with the specified key and value from the registry.| +|[`CWinAppEx::GetSectionString`](#getsectionstring)|Reads string data that is associated with the specified key and value from the registry.| +|[`CWinAppEx::GetShellManager`](#getshellmanager)|Returns a pointer to the global [`CShellManager`](../../mfc/reference/cshellmanager-class.md) object.| +|[`CWinAppEx::GetString`](#getstring)|Reads string data that is associated with the specified value from the registry.| +|[`CWinAppEx::GetTooltipManager`](#gettooltipmanager)|Returns a pointer to the global [`CTooltipManager`](../../mfc/reference/ctooltipmanager-class.md) object.| +|[`CWinAppEx::GetUserToolsManager`](#getusertoolsmanager)|Returns a pointer to the global [`CUserToolsManager`](../../mfc/reference/cusertoolsmanager-class.md) object.| +|[`CWinAppEx::InitContextMenuManager`](#initcontextmenumanager)|Initializes the `CContextMenuManager` object.| +|[`CWinAppEx::InitKeyboardManager`](#initkeyboardmanager)|Initializes the `CKeyboardManager` object.| +|[`CWinAppEx::InitMouseManager`](#initmousemanager)|Initializes the `CMouseManager` object.| +|[`CWinAppEx::InitShellManager`](#initshellmanager)|Initializes the `CShellManager` class| +|[`CWinAppEx::InitTooltipManager`](#inittooltipmanager)|Initializes the `CTooltipManager` class.| +|[`CWinAppEx::IsResourceSmartUpdate`](#isresourcesmartupdate)|| +|[`CWinAppEx::IsStateExists`](#isstateexists)|Indicates whether the specified key is in the registry.| +|[`CWinAppEx::LoadState`](#loadstate)|Loads the application state from the registry.| +|[`CWinAppEx::OnAppContextHelp`](#onappcontexthelp)|Called by the framework when the user requests context help for the **Customization** dialog box.| +|[`CWinAppEx::OnViewDoubleClick`](#onviewdoubleclick)|Calls the user-defined command when the user double-clicks anywhere in the application.| +|[`CWinAppEx::OnWorkspaceIdle`](#onworkspaceidle)|| +|[`CWinAppEx::SaveState`](#savestate)|Writes the state of the application framework to the Windows registry.| +|[`CWinAppEx::SetRegistryBase`](#setregistrybase)|Sets the path of the default registry key. This key will serve as a root for all subsequent registry calls.| +|[`CWinAppEx::ShowPopupMenu`](#showpopupmenu)|Displays a popup menu.| +|[`CWinAppEx::WriteBinary`](#writebinary)|Writes the binary data to the specified registry value.| +|[`CWinAppEx::WriteInt`](#writeint)|Writes the numeric data to the specified registry value.| +|[`CWinAppEx::WriteObject`](#writeobject)|Writes data that is derived from the [`CObject` Class](../../mfc/reference/cobject-class.md) to the specified registry value.| +|[`CWinAppEx::WriteSectionBinary`](#writesectionbinary)|Writes the binary data to a value of the specified registry key.| +|[`CWinAppEx::WriteSectionInt`](#writesectionint)|Writes the numeric data to a value of the specified registry key.| +|[`CWinAppEx::WriteSectionObject`](#writesectionobject)|Writes data derived from the `CObject` class to a value of the specified registry key.| +|[`CWinAppEx::WriteSectionString`](#writesectionstring)|Writes the string data to a value of the specified registry key.| +|[`CWinAppEx::WriteString`](#writestring)|Writes the string data to the specified registry value.| ### Protected Methods |Name|Description| |----------|-----------------| -|[CWinAppEx::LoadCustomState](#loadcustomstate)|Called by the framework when the application state has been loaded.| -|[CWinAppEx::LoadWindowPlacement](#loadwindowplacement)|Called by the framework when it loads the size and location of your application from the registry. The loaded data includes the size and location of the main frame at the time your application last closed.| -|[CWinAppEx::OnClosingMainFrame](#onclosingmainframe)|Called by the framework when a main frame window is processing WM_CLOSE.| -|[CWinAppEx::PreLoadState](#preloadstate)|Called by the framework immediately before the application state is loaded.| -|[CWinAppEx::PreSaveState](#presavestate)|Called by the framework immediately before the application state is saved.| -|[CWinAppEx::ReloadWindowPlacement](#reloadwindowplacement)|Reloads the size and location of the supplied window from the registry| -|[CWinAppEx::SaveCustomState](#savecustomstate)|Called by the framework after it writes the application state to the registry.| -|[CWinAppEx::StoreWindowPlacement](#storewindowplacement)|Called by the framework to write the size and location of the main frame to the registry.| +|[`CWinAppEx::LoadCustomState`](#loadcustomstate)|Called by the framework when the application state has been loaded.| +|[`CWinAppEx::LoadWindowPlacement`](#loadwindowplacement)|Called by the framework when it loads the size and location of your application from the registry. The loaded data includes the size and location of the main frame at the time your application last closed.| +|[`CWinAppEx::OnClosingMainFrame`](#onclosingmainframe)|Called by the framework when a main frame window is processing `WM_CLOSE`.| +|[`CWinAppEx::PreLoadState`](#preloadstate)|Called by the framework immediately before the application state is loaded.| +|[`CWinAppEx::PreSaveState`](#presavestate)|Called by the framework immediately before the application state is saved.| +|[`CWinAppEx::ReloadWindowPlacement`](#reloadwindowplacement)|Reloads the size and location of the supplied window from the registry| +|[`CWinAppEx::SaveCustomState`](#savecustomstate)|Called by the framework after it writes the application state to the registry.| +|[`CWinAppEx::StoreWindowPlacement`](#storewindowplacement)|Called by the framework to write the size and location of the main frame to the registry.| ### Data Members |Name|Description| |----------|-----------------| -|[CWinAppEx::m_bForceImageReset](#m_bforceimagereset)|Specifies whether the framework will reset all toolbar images when the frame window that contains the toolbar is loaded.| +|[`CWinAppEx::m_bForceImageReset`](#m_bforceimagereset)|Specifies whether the framework will reset all toolbar images when the frame window that contains the toolbar is loaded.| ## Remarks @@ -104,25 +103,25 @@ Much of the functionality provided by the MFC framework depends on the `CWinAppE - Derive the main application class from `CWinAppEx`. -After you incorporate `CWinAppEx` into your application, you can initialize any one of the application managers. Before you use an application manager, you must initialize it by calling the appropriate initialize method. To obtain a pointer to a specific manager, call the associated get method. The `CWinAppEx` class manages the following application managers: [CMouseManager Class](../../mfc/reference/cmousemanager-class.md), [CContextMenuManager Class](../../mfc/reference/ccontextmenumanager-class.md), [CKeyboardManager Class](../../mfc/reference/ckeyboardmanager-class.md), [CUserToolsManager Class](../../mfc/reference/cusertoolsmanager-class.md), and [CMenuTearOffManager Class](../../mfc/reference/cmenutearoffmanager-class.md). +After you incorporate `CWinAppEx` into your application, you can initialize any one of the application managers. Before you use an application manager, you must initialize it by calling the appropriate initialize method. To obtain a pointer to a specific manager, call the associated get method. The `CWinAppEx` class manages the following application managers: [`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md), [`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md), [`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md), [`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md), and [`CMenuTearOffManager` Class](../../mfc/reference/cmenutearoffmanager-class.md). ## Inheritance Hierarchy -[CObject](../../mfc/reference/cobject-class.md) +[`CObject`](../../mfc/reference/cobject-class.md) -[CCmdTarget](../../mfc/reference/ccmdtarget-class.md) +[`CCmdTarget`](../../mfc/reference/ccmdtarget-class.md) -[CWinThread](../../mfc/reference/cwinthread-class.md) +[`CWinThread`](../../mfc/reference/cwinthread-class.md) -[CWinApp](../../mfc/reference/cwinapp-class.md) +[`CWinApp`](../../mfc/reference/cwinapp-class.md) -[CWinAppEx](../../mfc/reference/cwinappex-class.md) +[`CWinAppEx`](../../mfc/reference/cwinappex-class.md) ## Requirements -**Header:** afxwinappex.h +**Header:** `afxwinappex.h` -## CWinAppEx::CleanState +## `CWinAppEx::CleanState` Removes all the information about the application from the Windows registry. @@ -132,7 +131,7 @@ virtual BOOL CleanState(LPCTSTR lpszSectionName=NULL); ### Parameters -*lpszSectionName*
+*`lpszSectionName`*\ [in] A string that contains a path of a registry key. ### Return Value @@ -141,9 +140,9 @@ Nonzero if the method was successful; otherwise 0. ### Remarks -This method clears application data from a specific section of the registry. You can specify the section to clear by using the parameter *lpszSectionName*. If *lpszSectionName* is NULL, this method will use the default registry path stored in the `CWinAppEx` object. To get the default registry path, use [CWinAppEx::GetRegistryBase](#getregistrybase). +This method clears application data from a specific section of the registry. You can specify the section to clear by using the parameter *`lpszSectionName`*. If *`lpszSectionName`* is `NULL`, this method will use the default registry path stored in the `CWinAppEx` object. To get the default registry path, use [CWinAppEx::GetRegistryBase](#getregistrybase). -## CWinAppEx::CWinAppEx +## `CWinAppEx::CWinAppEx` Constructs a `CWinAppEx` object. @@ -153,14 +152,14 @@ CWinAppEx(BOOL bResourceSmartUpdate = FALSE); ### Parameters -*bResourceSmartUpdate*
+*`bResourceSmartUpdate`*\ [in] A Boolean parameter that specifies whether the workspace object should detect and handle resource updates. ### Remarks -The `CWinAppEx` class has initialization methods, provides functionality for saving and loading application information to the registry, and controls global application settings. It also enables you to use global managers such as the [CKeyboardManager Class](../../mfc/reference/ckeyboardmanager-class.md) and the [CUserToolsManager Class](../../mfc/reference/cusertoolsmanager-class.md). Each application can have only one instance of the `CWinAppEx` class. +The `CWinAppEx` class has initialization methods, provides functionality for saving and loading application information to the registry, and controls global application settings. It also enables you to use global managers such as the [`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md) and the [`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md). Each application can have only one instance of the `CWinAppEx` class. -## CWinAppEx::EnableLoadWindowPlacement +## `CWinAppEx::EnableLoadWindowPlacement` Specifies whether the application will load the initial size and location of the main frame window from the registry. @@ -170,16 +169,16 @@ void EnableLoadWindowPlacement(BOOL bEnable = TRUE); ### Parameters -*bEnable*
+*`bEnable`*\ [in] Specifies whether the application loads the initial size and location of the main frame window from the registry. ### Remarks -By default, the size and location of the main frame is loaded from the registry together with other application settings. This occurs during [CWinAppEx::LoadState](#loadstate). If you do not want to load the initial window placement from the registry, call this method with *bEnable* set to FALSE. +By default, the size and location of the main frame is loaded from the registry together with other application settings. This occurs during [`CWinAppEx::LoadState`](#loadstate). If you don't want to load the initial window placement from the registry, call this method with *`bEnable`* set to `FALSE`. -## CWinAppEx::EnableTearOffMenus +## `CWinAppEx::EnableTearOffMenus` -Creates and initializes a [CMenuTearOffManager](../../mfc/reference/cmenutearoffmanager-class.md) object. +Creates and initializes a [`CMenuTearOffManager`](../../mfc/reference/cmenutearoffmanager-class.md) object. ``` BOOL EnableTearOffMenus( @@ -190,26 +189,26 @@ BOOL EnableTearOffMenus( ### Parameters -*lpszRegEntry*
+*`lpszRegEntry`*\ [in] A string that contains the path of a registry key. The application uses this registry key to store information for the tear-off menus. -*uiCmdFirst*
+*`uiCmdFirst`*\ [in] The first tear off menu ID. -*uiCmdLast*
+*`uiCmdLast`*\ [in] The last tear off menu ID. ### Return Value -TRUE if the `CMenuTearOffManager` is created and initialized successfully; FALSE if an error occurs or if the `CMenuTearOffManager` already exists. +`TRUE` if the `CMenuTearOffManager` is created and initialized successfully; `FALSE` if an error occurs or if the `CMenuTearOffManager` already exists. ### Remarks Use this function to enable tear-off menus in your application. You should call this function from `InitInstance`. -## CWinAppEx::EnableUserTools +## `CWinAppEx::EnableUserTools` -Enables the user to create custom menu commands that reduce keystrokes in your application. This method creates a [CUserToolsManager](../../mfc/reference/cusertoolsmanager-class.md) object. +Enables the user to create custom menu commands that reduce keystrokes in your application. This method creates a [`CUserToolsManager`](../../mfc/reference/cusertoolsmanager-class.md) object. ``` BOOL EnableUserTools( @@ -223,37 +222,37 @@ BOOL EnableUserTools( ### Parameters -*uiCmdToolsDummy*
+*`uiCmdToolsDummy`*\ [in] An unsigned integer that the framework uses as a placeholder for the command ID of the user tools menu. -*uiCmdFirst*
+*`uiCmdFirst`*\ [in] The command ID for the first user tool command. -*uiCmdLast*
+*`uiCmdLast`*\ [in] The command ID for the last user tool command. -*pToolRTC*
+*`pToolRTC`*\ [in] A class that the `CUserToolsManager` object uses to create new user tools. -*uArgMenuID*
+*`uArgMenuID`*\ [in] The argument menu ID. -*uInitDirMenuID*
+*`uInitDirMenuID`*\ [in] The menu ID for the initial tool directory. ### Return Value -TRUE if the method creates and initializes a `CUserToolsManager` object; FALSE if the method fails or if a `CUserToolsManager` object already exists. +`TRUE` if the method creates and initializes a `CUserToolsManager` object; `FALSE` if the method fails or if a `CUserToolsManager` object already exists. ### Remarks When you enable user-defined tools, the framework automatically supports a dynamic menu that can be extended during customization. The framework associates each new item with an external command. The framework invokes these commands when the user selects the appropriate item from the **Tools** menu. -Every time the user adds a new item, the framework creates a new object. The class type for the new object is defined by *pToolRTC*. The *pToolRTC* class type must be derived from the [CUserTool Class](../../mfc/reference/cusertool-class.md). +Every time the user adds a new item, the framework creates a new object. The class type for the new object is defined by *`pToolRTC`*. The *`pToolRTC`* class type must be derived from the [`CUserTool` Class](../../mfc/reference/cusertool-class.md). For more information about user tools and how to incorporate them into your application, see [User-defined Tools](../../mfc/user-defined-tools.md). -## CWinAppEx::ExitInstance +## `CWinAppEx::ExitInstance` ``` virtual int ExitInstance(); @@ -263,7 +262,7 @@ virtual int ExitInstance(); ### Remarks -## CWinAppEx::GetBinary +## `CWinAppEx::GetBinary` Reads binary data from a specified registry key. @@ -276,28 +275,28 @@ BOOL GetBinary( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry key. -*ppData*
+*`ppData`*\ [out] A pointer to the buffer that the method fills with the binary data. -*pBytes*
+*`pBytes`*\ [out] A pointer to an unsigned integer that the method uses to write the number of bytes read. ### Return Value -TRUE if successful; FALSE otherwise. +`TRUE` if successful; `FALSE` otherwise. ### Remarks -This method reads binary data written to the registry. To write data to the registry, use the methods [CWinAppEx::WriteBinary](#writebinary) and [CWinAppEx::WriteSectionBinary](#writesectionbinary). +This method reads binary data written to the registry. To write data to the registry, use the methods [`CWinAppEx::WriteBinary`](#writebinary) and [`CWinAppEx::WriteSectionBinary`](#writesectionbinary). -The *lpszEntry* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetContextMenuManager +## `CWinAppEx::GetContextMenuManager` -Returns a pointer to the global [CContextMenuManager](../../mfc/reference/ccontextmenumanager-class.md) object. +Returns a pointer to the global [`CContextMenuManager`](../../mfc/reference/ccontextmenumanager-class.md) object. ``` CContextMenuManager* GetContextMenuManager(); @@ -309,9 +308,9 @@ A pointer to the global `CContextMenuManager` object. ### Remarks -If the CContextMenuManager object is not initialized, this function calls [CWinAppEx::InitContextMenuManager](#initcontextmenumanager) before it returns a pointer. +If the `CContextMenuManager` object isn't initialized, this function calls [`CWinAppEx::InitContextMenuManager`](#initcontextmenumanager) before it returns a pointer. -## CWinAppEx::GetDataVersion +## `CWinAppEx::GetDataVersion` ``` int GetDataVersion() const; @@ -321,9 +320,9 @@ int GetDataVersion() const; ### Remarks -## CWinAppEx::GetDataVersionMajor +## `CWinAppEx::GetDataVersionMajor` -Returns the major version of the application that is saved in the Windows registry when you call [CWinAppEx::SaveState](#savestate). +Returns the major version of the application that is saved in the Windows registry when you call [`CWinAppEx::SaveState`](#savestate). ``` int GetDataVersionMajor() const; @@ -333,9 +332,9 @@ int GetDataVersionMajor() const; An integer value that contains the major version number. -## CWinAppEx::GetDataVersionMinor +## `CWinAppEx::GetDataVersionMinor` -Returns the minor version of the application that is saved in the Windows registry when you call [CWinAppEx::SaveState](#savestate). +Returns the minor version of the application that is saved in the Windows registry when you call [`CWinAppEx::SaveState`](#savestate). ``` int GetDataVersionMinor() const; @@ -345,7 +344,7 @@ int GetDataVersionMinor() const; An integer value that contains the minor version number. -## CWinAppEx::GetInt +## `CWinAppEx::GetInt` Reads integer data from a specified registry key. @@ -357,25 +356,25 @@ int GetInt( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry entry. -*nDefault*
-[in] The default value that the method returns if the specified registry entry does not exist. +*`nDefault`*\ +[in] The default value that the method returns if the specified registry entry doesn't exist. ### Return Value -The registry data if the method was successful; otherwise *nDefault*. +The registry data if the method was successful; otherwise *`nDefault`*. ### Remarks -This method reads integer data from the registry. If there is no integer data associated with the registry key indicated by *lpszEntry*, this method returns *nDefault*. To write data to the registry, use the methods [CWinAppEx::WriteSectionInt](#writesectionint) and [CWinAppEx::WriteInt](#writeint). +This method reads integer data from the registry. If there's no integer data associated with the registry key indicated by *`lpszEntry`*, this method returns *`nDefault`*. To write data to the registry, use the methods [`CWinAppEx::WriteSectionInt`](#writesectionint) and [`CWinAppEx::WriteInt`](#writeint). -The *lpszEntry* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetKeyboardManager +## `CWinAppEx::GetKeyboardManager` -Returns a pointer to the global [CKeyboardManager](../../mfc/reference/ckeyboardmanager-class.md) object. +Returns a pointer to the global [`CKeyboardManager`](../../mfc/reference/ckeyboardmanager-class.md) object. ``` CKeyboardManager* GetKeyboardManager(); @@ -387,11 +386,11 @@ A pointer to the global `CKeyboardManager` object. ### Remarks -If the keyboard manager is not initialized, this function calls [CWinAppEx::InitKeyboardManager](#initkeyboardmanager) before it returns a pointer. +If the keyboard manager isn't initialized, this function calls [`CWinAppEx::InitKeyboardManager`](#initkeyboardmanager) before it returns a pointer. -## CWinAppEx::GetMouseManager +## `CWinAppEx::GetMouseManager` -Returns a pointer to the global [CMouseManager](../../mfc/reference/cmousemanager-class.md) object. +Returns a pointer to the global [`CMouseManager`](../../mfc/reference/cmousemanager-class.md) object. ``` CMouseManager* GetMouseManager(); @@ -403,11 +402,11 @@ A pointer to the global `CMouseManager` object. ### Remarks -If the mouse manager is not initialized,, this function calls [CWinAppEx::InitMouseManager](#initmousemanager) before it returns a pointer. +If the mouse manager isn't initialized, this function calls [`CWinAppEx::InitMouseManager`](#initmousemanager) before it returns a pointer. -## CWinAppEx::GetObject +## `CWinAppEx::GetObject` -Reads [CObject](../../mfc/reference/cobject-class.md)-dervied data from the registry. +Reads [`CObject`](../../mfc/reference/cobject-class.md)-dervied data from the registry. ``` BOOL GetObject( @@ -417,10 +416,10 @@ BOOL GetObject( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the relative path of a registry entry. -*obj*
+*`obj`*\ [out] A reference to a `CObject`. The method uses this reference to store the registry data. ### Return Value @@ -429,11 +428,11 @@ Nonzero if the method was successful; otherwise 0. ### Remarks -This method reads data from the registry that is derived from `CObject`. To write `CObject` data to the registry, use either [CWinAppEx::WriteObject](#writeobject) or [CWinAppEx::WriteSectionObject](#writesectionobject). +This method reads data from the registry that is derived from `CObject`. To write `CObject` data to the registry, use either [`CWinAppEx::WriteObject`](#writeobject) or [`CWinAppEx::WriteSectionObject`](#writesectionobject). -The *lpszEntry* parameter is the name of a registry entry that is located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry that is located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetRegistryBase +## `CWinAppEx::GetRegistryBase` Retrieves the default registry path for the application. @@ -447,9 +446,9 @@ A string that contains the path of the default registry location. ### Remarks -All methods of the [CWinAppEx Class](../../mfc/reference/cwinappex-class.md) that access the registry start in a default location. Use this method to retrieve a path of the default registry location. Use [CWinAppEx::SetRegistryBase](#setregistrybase) to change the default registry location. +All methods of the [`CWinAppEx` Class](../../mfc/reference/cwinappex-class.md) that access the registry start in a default location. Use this method to retrieve a path of the default registry location. Use [`CWinAppEx::SetRegistryBase`](#setregistrybase) to change the default registry location. -## CWinAppEx::GetRegSectionPath +## `CWinAppEx::GetRegSectionPath` Creates and returns the absolute path of a registry key. @@ -459,7 +458,7 @@ CString GetRegSectionPath(LPCTSTR szSectionAdd = _T("")); ### Parameters -*szSectionAdd*
+*`szSectionAdd`*\ [in] A string that contains the relative path of a registry key. ### Return Value @@ -468,9 +467,9 @@ A `CString` that contains the absolute path of a registry key. ### Remarks -This method defines the registry key's absolute path by appending the relative path in *szSectionAdd* to the default registry location for your application. To get the default registry key, use the method [CWinAppEx::GetRegistryBase](#getregistrybase). +This method defines the registry key's absolute path by appending the relative path in *`szSectionAdd`* to the default registry location for your application. To get the default registry key, use the method [`CWinAppEx::GetRegistryBase`](#getregistrybase). -## CWinAppEx::GetSectionBinary +## `CWinAppEx::GetSectionBinary` Reads binary data from the registry. @@ -484,29 +483,29 @@ BOOL GetSectionBinary( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the relative path of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to read. -*ppData*
+*`ppData`*\ [out] A pointer to the buffer where the method stores the data. -*pBytes*
-[out] A pointer to an unsigned integer. The method writes the size of *ppData* to this parameter. +*`pBytes`*\ +[out] A pointer to an unsigned integer. The method writes the size of *`ppData`* to this parameter. ### Return Value -TRUE if successful; otherwise FALSE. +`TRUE` if successful; otherwise `FALSE`. ### Remarks -This method reads binary data that is written to the registry using the methods [CWinAppEx::WriteBinary](#writebinary) and [CWinAppEx::WriteSectionBinary](#writesectionbinary). +This method reads binary data that is written to the registry using the methods [`CWinAppEx::WriteBinary`](#writebinary) and [`CWinAppEx::WriteSectionBinary`](#writesectionbinary). -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetSectionInt +## `CWinAppEx::GetSectionInt` Reads integer data from the registry. @@ -519,28 +518,28 @@ int GetSectionInt( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the relative path of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to read. -*nDefault*
-[in] The default value to return if the specified value does not exist. +*`nDefault`*\ +[in] The default value to return if the specified value doesn't exist. ### Return Value -The integer data that is stored in the specified registry value; *nDefault* if the data does not exist. +The integer data that is stored in the specified registry value; *`nDefault`* if the data doesn't exist. ### Remarks -Use the methods [CWinAppEx::WriteInt](#writeint) and [CWinAppEx::WriteSectionInt](#writesectionint) to write integer data to the registry. +Use the methods [`CWinAppEx::WriteInt`](#writeint) and [`CWinAppEx::WriteSectionInt`](#writesectionint) to write integer data to the registry. -The *lpszSubSection* parameter is not an absolute path of a registry entry. It is a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't an absolute path of a registry entry. It's a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetSectionObject +## `CWinAppEx::GetSectionObject` -Reads [CObject](../../mfc/reference/cobject-class.md) registry data from the registry. +Reads [`CObject`](../../mfc/reference/cobject-class.md) registry data from the registry. ``` BOOL GetSectionObject( @@ -551,13 +550,13 @@ BOOL GetSectionObject( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the relative path of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to read. -*obj*
+*`obj`*\ [out] A reference to a `CObject`. The method uses this `CObject` to store the registry data. ### Return Value @@ -566,11 +565,11 @@ Nonzero if successful; otherwise 0. ### Remarks -This method reads data from the registry. The data read is `CObject` data, or data for a class derived from `CObject`. To write `CObject` data to the registry, use either [CWinAppEx::WriteObject](#writeobject) or [CWinAppEx::WriteSectionObject](#writesectionobject). +This method reads data from the registry. The data read is `CObject` data, or data for a class derived from `CObject`. To write `CObject` data to the registry, use either [`CWinAppEx::WriteObject`](#writeobject) or [`CWinAppEx::WriteSectionObject`](#writesectionobject). -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetSectionString +## `CWinAppEx::GetSectionString` Reads string data from the registry. @@ -583,28 +582,28 @@ CString GetSectionString( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the relative path of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to read. -*lpszDefault*
-[in] The default value to return if the specified value does not exist. +*`lpszDefault`*\ +[in] The default value to return if the specified value doesn't exist. ### Return Value -The string data stored in the specified registry value if the data exists; otherwise *lpszDefault*. +The string data stored in the specified registry value if the data exists; otherwise *`lpszDefault`*. ### Remarks -This method reads string data written to the registry. Use [CWinAppEx::WriteString](#writestring) and [CWinAppEx::WriteSectionString](#writesectionstring) to write string data to the registry. +This method reads string data written to the registry. Use [`CWinAppEx::WriteString`](#writestring) and [`CWinAppEx::WriteSectionString`](#writesectionstring) to write string data to the registry. -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetShellManager +## `CWinAppEx::GetShellManager` -Returns a pointer to the global [CShellManager](../../mfc/reference/cshellmanager-class.md) object. +Returns a pointer to the global [`CShellManager`](../../mfc/reference/cshellmanager-class.md) object. ``` CShellManager* GetShellManager(); @@ -616,9 +615,9 @@ A pointer to the global `CShellManager` object. ### Remarks -If the `CShellManager` object is not initialized, this function calls [CWinAppEx::InitShellManager](#initshellmanager) before it returns a pointer. +If the `CShellManager` object isn't initialized, this function calls [`CWinAppEx::InitShellManager`](#initshellmanager) before it returns a pointer. -## CWinAppEx::GetString +## `CWinAppEx::GetString` Reads string data from a specified registry key. @@ -630,25 +629,25 @@ CString GetString( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry key -*lpzDefault*
-[in] The default value that the method returns if the specified registry entry does not exist. +*`lpzDefault`*\ +[in] The default value that the method returns if the specified registry entry doesn't exist. ### Return Value -The string data stored in the registry if successful; *lpszDefault* otherwise. +The string data stored in the registry if successful; *`lpszDefault`* otherwise. ### Remarks -This method reads string data written to the registry. To write data to the registry, use the methods [CWinAppEx::WriteString](#writestring) or [CWinAppEx::WriteSectionString](#writesectionstring). +This method reads string data written to the registry. To write data to the registry, use the methods [`CWinAppEx::WriteString`](#writestring) or [`CWinAppEx::WriteSectionString`](#writesectionstring). -The *lpszEntry* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::GetTooltipManager +## `CWinAppEx::GetTooltipManager` -Returns a pointer to the global [CTooltipManager](../../mfc/reference/ctooltipmanager-class.md) object. +Returns a pointer to the global [`CTooltipManager`](../../mfc/reference/ctooltipmanager-class.md) object. ``` CTooltipManager* GetTooltipManager(); @@ -660,11 +659,11 @@ A pointer to the global `CTooltipManager` object. ### Remarks -If the `CTooltipManager` object is not initialized, this function calls [CWinAppEx::InitTooltipManager](#inittooltipmanager) before it returns a pointer. +If the `CTooltipManager` object isn't initialized, this function calls [`CWinAppEx::InitTooltipManager`](#inittooltipmanager) before it returns a pointer. -## CWinAppEx::GetUserToolsManager +## `CWinAppEx::GetUserToolsManager` -Returns a pointer to the global [CUserToolsManager](../../mfc/reference/cusertoolsmanager-class.md) object. +Returns a pointer to the global [`CUserToolsManager`](../../mfc/reference/cusertoolsmanager-class.md) object. ``` CUserToolsManager* GetUserToolsManager(); @@ -672,15 +671,15 @@ CUserToolsManager* GetUserToolsManager(); ### Return Value -A pointer to the global `CUserToolsManager` object; NULL if user tools management is not enabled for the application. +A pointer to the global `CUserToolsManager` object; `NULL` if user tools management isn't enabled for the application. ### Remarks -Before you retrieve a pointer to the `CUserToolsManager` object, you must initialize the manager by calling [CWinAppEx::EnableUserTools](#enableusertools). +Before you retrieve a pointer to the `CUserToolsManager` object, you must initialize the manager by calling [`CWinAppEx::EnableUserTools`](#enableusertools). -## CWinAppEx::InitContextMenuManager +## `CWinAppEx::InitContextMenuManager` -Initializes the [CContextMenuManager](../../mfc/reference/ccontextmenumanager-class.md) object. +Initializes the [`CContextMenuManager`](../../mfc/reference/ccontextmenumanager-class.md) object. ``` BOOL InitContextMenuManager(); @@ -688,17 +687,17 @@ BOOL InitContextMenuManager(); ### Return Value -Nonzero if the method creates the CContextMenuManager object; 0 if the `CContextMenuManager` object already exists. +Nonzero if the method creates the `CContextMenuManager` object; 0 if the `CContextMenuManager` object already exists. ### Remarks -If you call [CWinAppEx::GetContextMenuManager](#getcontextmenumanager), the default implementation of that method calls `InitContextMenuManager`. +If you call [`CWinAppEx::GetContextMenuManager`](#getcontextmenumanager), the default implementation of that method calls `InitContextMenuManager`. -If your application already has a context menu manager and you call `InitContextMenuManager`, your application will have an [ASSERT](diagnostic-services.md#assert) failure. Therefore, you should not call `InitContextMenuManager` if you create a `CContextMenuManager` object directly. If you are not using a custom `CContextMenuManager`, you should use `GetContextMenuManager` to create a `CContextMenuManager` object. +If your application already has a context menu manager and you call `InitContextMenuManager`, your application will have an [`ASSERT`](diagnostic-services.md#assert) failure. Therefore, you shouldn't call `InitContextMenuManager` if you create a `CContextMenuManager` object directly. If you aren't using a custom `CContextMenuManager`, you should use `GetContextMenuManager` to create a `CContextMenuManager` object. -## CWinAppEx::InitKeyboardManager +## `CWinAppEx::InitKeyboardManager` -Initializes the [CKeyboardManager](../../mfc/reference/ckeyboardmanager-class.md) object. +Initializes the [`CKeyboardManager`](../../mfc/reference/ckeyboardmanager-class.md) object. ``` BOOL InitKeyboardManager(); @@ -710,13 +709,13 @@ Nonzero if the method creates the `CKeyboardManager` object; 0 if the `CKeyboard ### Remarks -If you call [CWinAppEx::GetKeyboardManager](#getkeyboardmanager), the default implementation of that method calls `InitKeyboardManager`. +If you call [`CWinAppEx::GetKeyboardManager`](#getkeyboardmanager), the default implementation of that method calls `InitKeyboardManager`. -If your application already has a keyboard manager and you call `InitKeyboardManager`, your application will have an [ASSERT](diagnostic-services.md#assert) failure. Therefore, you should not call `InitKeyboardManager` if you create a `CKeyboardManager` object directly. If you are not using a custom `CKeyboardManager`, you should use `GetKeyboardManager` to create a `CKeyboardManager` object. +If your application already has a keyboard manager and you call `InitKeyboardManager`, your application will have an [`ASSERT`](diagnostic-services.md#assert) failure. Therefore, you shouldn't call `InitKeyboardManager` if you create a `CKeyboardManager` object directly. If you aren't using a custom `CKeyboardManager`, you should use `GetKeyboardManager` to create a `CKeyboardManager` object. -## CWinAppEx::InitMouseManager +## `CWinAppEx::InitMouseManager` -Initializes the [CMouseManager](../../mfc/reference/cmousemanager-class.md) object. +Initializes the [`CMouseManager`](../../mfc/reference/cmousemanager-class.md) object. ``` BOOL InitMouseManager(); @@ -728,13 +727,13 @@ Nonzero if the method creates the `CMouseManager` object; 0 if the `CMouseManage ### Remarks -If you call [CWinAppEx::GetMouseManager](#getmousemanager), the default implementation of that method calls `InitMouseManager`. +If you call [`CWinAppEx::GetMouseManager`](#getmousemanager), the default implementation of that method calls `InitMouseManager`. -If your application already has a mouse manager and you call `InitMouseManager`, your application will have an [ASSERT](diagnostic-services.md#assert) failure. Therefore you should not call `InitMouseManager` if you create a `CMouseManager` object directly. If you are not using a custom `CMouseManager`, you should use `GetMouseManager` to create a `CMouseManager` object. +If your application already has a mouse manager and you call `InitMouseManager`, your application will have an [`ASSERT`](diagnostic-services.md#assert) failure. Therefore you shouldn't call `InitMouseManager` if you create a `CMouseManager` object directly. If you aren't using a custom `CMouseManager`, you should use `GetMouseManager` to create a `CMouseManager` object. -## CWinAppEx::InitShellManager +## `CWinAppEx::InitShellManager` -Initializes the [CShellManager](../../mfc/reference/cshellmanager-class.md) object. +Initializes the [`CShellManager`](../../mfc/reference/cshellmanager-class.md) object. ``` BOOL InitShellManager(); @@ -746,13 +745,13 @@ Nonzero if the method creates the `CShellManager` object; 0 if the `CShellManage ### Remarks -If you call [CWinAppEx::GetShellManager](#getshellmanager), the default implementation of that method calls `InitShellManager`. +If you call [`CWinAppEx::GetShellManager`](#getshellmanager), the default implementation of that method calls `InitShellManager`. -If your application already has a shell manager and you call `InitShellManager`, your application raises an [ASSERT](diagnostic-services.md#assert) failure. Therefore, do not call `InitShellManager` if you create a `CShellManager` object directly. If you are not using a custom `CShellManager`, use `GetShellManager` to create a `CShellManager` object. +If your application already has a shell manager and you call `InitShellManager`, your application raises an [`ASSERT`](diagnostic-services.md#assert) failure. Therefore, don't call `InitShellManager` if you create a `CShellManager` object directly. If you aren't using a custom `CShellManager`, use `GetShellManager` to create a `CShellManager` object. -## CWinAppEx::InitTooltipManager +## `CWinAppEx::InitTooltipManager` -Initializes the [CTooltipManager](../../mfc/reference/ctooltipmanager-class.md) object. +Initializes the [`CTooltipManager`](../../mfc/reference/ctooltipmanager-class.md) object. ``` BOOL InitTooltipManager(); @@ -764,11 +763,11 @@ Nonzero if the method creates the `CTooltipManager` object; 0 if the `CTooltipMa ### Remarks -If you call [CWinAppEx::GetTooltipManager](#gettooltipmanager), the default implementation of that method calls `InitTooltipManager`. +If you call [`CWinAppEx::GetTooltipManager`](#gettooltipmanager), the default implementation of that method calls `InitTooltipManager`. -If your application already has a tooltip manager and you call `InitTooltipManager`, your application will have an [ASSERT](diagnostic-services.md#assert) failure. Therefore, you should not call `InitTooltipManager` if you create a `CTooltipManager` object directly. If you are not using a custom `CTooltipManager`, you should use `GetTooltipManager` to create a `CTooltipManager` object. +If your application already has a tooltip manager and you call `InitTooltipManager`, your application will have an [`ASSERT`](diagnostic-services.md#assert) failure. Therefore, you shouldn't call `InitTooltipManager` if you create a `CTooltipManager` object directly. If you aren't using a custom `CTooltipManager`, you should use `GetTooltipManager` to create a `CTooltipManager` object. -## CWinAppEx::IsResourceSmartUpdate +## `CWinAppEx::IsResourceSmartUpdate` ``` BOOL IsResourceSmartUpdate() const; @@ -778,7 +777,7 @@ BOOL IsResourceSmartUpdate() const; ### Remarks -## CWinAppEx::IsStateExists +## `CWinAppEx::IsStateExists` Indicates whether the specified key is in the registry. @@ -788,14 +787,14 @@ BOOL IsStateExists(LPCTSTR lpszSectionName); ### Parameters -*lpszSectionName*
+*`lpszSectionName`*\ [in] A string that contains a path of a registry key. ### Return Value Nonzero if the key is in the registry; otherwise 0. -## CWinAppEx::LoadCustomState +## `CWinAppEx::LoadCustomState` The framework calls this method after it loads the state of the application from the registry. @@ -807,9 +806,9 @@ virtual void LoadCustomState(); Override this method if you want to do any processing after the application loads the state from the registry. By default, this method does nothing. -In order to load custom state information from the registry, the information must first be saved by using [CWinAppEx::SaveCustomState](#savecustomstate). +In order to load custom state information from the registry, the information must first be saved by using [`CWinAppEx::SaveCustomState`](#savecustomstate). -## CWinAppEx::LoadState +## `CWinAppEx::LoadState` Reads the application state from the Windows registry. @@ -833,13 +832,13 @@ virtual BOOL LoadState( ### Parameters -*pFrame*
+*`pFrame`*\ [in] A pointer to a frame window object. The method applies the state information in the registry to this frame window. -*lpszSectionName*
+*`lpszSectionName`*\ [in] A string that contains the relative path of a registry key. -*pFrameImpl*
+*`pFrameImpl`*\ [in] A pointer to a `CFrameImpl` object. The method applies the state information in the registry to this frame window. ### Return Value @@ -848,13 +847,13 @@ Nonzero if successful; 0 otherwise. ### Remarks -This method loads the state of the application and any state information for a frame window. The loaded information for the frame window is applied to the supplied frame window. If you do not supply a frame window, only the application state information is loaded. The application information includes the state of the [CMouseManager Class](../../mfc/reference/cmousemanager-class.md), [CContextMenuManager Class](../../mfc/reference/ccontextmenumanager-class.md), [CKeyboardManager Class](../../mfc/reference/ckeyboardmanager-class.md), and the [CUserToolsManager Class](../../mfc/reference/cusertoolsmanager-class.md). +This method loads the state of the application and any state information for a frame window. The loaded information for the frame window is applied to the supplied frame window. If you don't supply a frame window, only the application state information is loaded. The application information includes the state of the [`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md), [`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md), [`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md), and the [`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md). The default implementation of `CFrameImpl::OnLoadFrame` calls `LoadState`. -The *lpszSectionName* parameter is not the absolute path for a registry entry. It is a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSectionName`* parameter isn't the absolute path for a registry entry. It's a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::LoadWindowPlacement +## `CWinAppEx::LoadWindowPlacement` Called by the framework when it loads the size and location of the main frame window from the registry. @@ -867,14 +866,14 @@ virtual BOOL LoadWindowPlacement( ### Parameters -*rectNormalPosition*
+*`rectNormalPosition`*\ [out] A rectangle that contains the coordinates of the main frame window when it is in the restored position. -*nFlags*
+*`nFlags`*\ [out] Flags that control the position of the minimized window and how the operating system switches between a minimized window and a restored window. -*nShowCmd*
-[out] An integer that specifies the show state of the window. For more information about possible values, see [CWnd::ShowWindow](../../mfc/reference/cwnd-class.md#showwindow). +*`nShowCmd`*\ +[out] An integer that specifies the show state of the window. For more information about possible values, see [`CWnd::ShowWindow`](../../mfc/reference/cwnd-class.md#showwindow). ### Return Value @@ -882,11 +881,11 @@ Nonzero if successful; 0 otherwise. ### Remarks -By default, MFC automatically loads the previous position and state of the main frame window when the application starts. For more information about how this information is stored in the registry, see [CWinAppEx::StoreWindowPlacement](#storewindowplacement). +By default, MFC automatically loads the previous position and state of the main frame window when the application starts. For more information about how this information is stored in the registry, see [`CWinAppEx::StoreWindowPlacement`](#storewindowplacement). Override this method if you want to load additional information about the main frame window. -## CWinAppEx::m_bForceImageReset +## `CWinAppEx::m_bForceImageReset` Specifies whether the framework resets all toolbar images when it reloads the frame window that contains the toolbar. @@ -898,7 +897,7 @@ BOOL m_bForceImageReset; The `m_bForceImageReset` data member is a protected variable. -## CWinAppEx::OnAppContextHelp +## `CWinAppEx::OnAppContextHelp` The framework calls this method when the user requests context help for the **Customization** dialog box. @@ -910,19 +909,19 @@ virtual void OnAppContextHelp( ### Parameters -*pWndControl*
+*`pWndControl`*\ [in] A pointer to a window object for which the user invoked context help. -*dwHelpIDArray[]*
+*`dwHelpIDArray[]`*\ [in] A reserved value. ### Remarks -This method is currently reserved for future use. The default implementation does nothing and it is currently not called by the framework. +This method is currently reserved for future use. The default implementation does nothing and it's currently not called by the framework. -## CWinAppEx::OnClosingMainFrame +## `CWinAppEx::OnClosingMainFrame` -The framework calls this method when a frame window is processing WM_CLOSE. +The framework calls this method when a frame window is processing `WM_CLOSE`. ``` virtual void OnClosingMainFrame(CFrameImpl* pFrameImpl); @@ -930,14 +929,14 @@ virtual void OnClosingMainFrame(CFrameImpl* pFrameImpl); ### Parameters -*pFrameImpl*
+*`pFrameImpl`*\ [in] A pointer to a `CFrameImpl` object. ### Remarks -The default implementation of this method saves the state of *pFrameImpl*. +The default implementation of this method saves the state of *`pFrameImpl`*. -## CWinAppEx::OnViewDoubleClick +## `CWinAppEx::OnViewDoubleClick` Calls the user-defined command that is associated with a view when the user double-clicks anywhere within that view. @@ -949,21 +948,21 @@ virtual BOOL OnViewDoubleClick( ### Parameters -*pWnd*
-[in] A pointer to an object derived from the [CView Class](../../mfc/reference/cview-class.md). +*`pWnd`*\ +[in] A pointer to an object derived from the [`CView` Class](../../mfc/reference/cview-class.md). -*iViewId*
+*`iViewId`*\ [in] The view ID. ### Return Value -TRUE if the framework finds a command; otherwise FALSE. +`TRUE` if the framework finds a command; otherwise `FALSE`. ### Remarks -In order to support custom mouse behavior, you must call this function when you process the WM_LBUTTONDBLCLK message. This method will execute the command associated with the view ID supplied by *iViewId*. For more information about custom mouse behavior, see [Keyboard and Mouse Customization](../../mfc/keyboard-and-mouse-customization.md). +In order to support custom mouse behavior, you must call this function when you process the `WM_LBUTTONDBLCLK` message. This method will execute the command associated with the view ID supplied by *`iViewId`*. For more information about custom mouse behavior, see [Keyboard and Mouse Customization](../../mfc/keyboard-and-mouse-customization.md). -## CWinAppEx::OnWorkspaceIdle +## `CWinAppEx::OnWorkspaceIdle` ``` virtual BOOL OnWorkspaceIdle(CWnd*); @@ -971,13 +970,13 @@ virtual BOOL OnWorkspaceIdle(CWnd*); ### Parameters -[in] *`CWnd*`*
+[in] *`CWnd*`* ### Return Value ### Remarks -## CWinAppEx::PreLoadState +## `CWinAppEx::PreLoadState` The framework calls this method immediately before it loads the state of the application from the registry. @@ -989,7 +988,7 @@ virtual void PreLoadState(); Override this method if you want to do any processing immediately before the framework loads the application state. -## CWinAppEx::PreSaveState +## `CWinAppEx::PreSaveState` The framework calls this method immediately before it saves the application state. @@ -1001,7 +1000,7 @@ virtual void PreSaveState(); Override this method if you want to do any processing immediately before the framework saves the application state. -## CWinAppEx::ReloadWindowPlacement +## `CWinAppEx::ReloadWindowPlacement` Reloads the size and location of a window from the registry. @@ -1011,18 +1010,18 @@ virtual BOOL ReloadWindowPlacement(CFrameWnd* pFrame); ### Parameters -*pFrame*
+*`pFrame`*\ [in] A pointer to a frame window. ### Return Value -Nonzero if the method was successful; 0 if the load failed or there is no data to load. +Nonzero if the method was successful; 0 if the load failed or there's no data to load. ### Remarks -Use the function [CWinAppEx::StoreWindowPlacement](#storewindowplacement) to write the size and location of a window to the registry. +Use the function [`CWinAppEx::StoreWindowPlacement`](#storewindowplacement) to write the size and location of a window to the registry. -## CWinAppEx::SaveCustomState +## `CWinAppEx::SaveCustomState` The framework calls this method after it saves the state of the application to the registry. @@ -1034,7 +1033,7 @@ virtual void SaveCustomState(); Override this method if you want to do any processing after the application saves the state to the registry. By default, this method does nothing. -## CWinAppEx::SaveState +## `CWinAppEx::SaveState` Writes the application state to the Windows registry. @@ -1058,26 +1057,26 @@ BOOL SaveState( ### Parameters -*lpszSectionName*
+*`lpszSectionName`*\ [in] A string that contains the relative path of a registry key. -*pFrameImpl*
+*`pFrameImpl`*\ [in] A pointer to a `CFrameImpl` object. This frame is saved to the Windows registry. -*pFrame*
+*`pFrame`*\ [in] A pointer to a frame window object. This frame is saved to the Windows registry. ### Return Value -TRUE if successful; FALSE otherwise. +`TRUE` if successful; `FALSE` otherwise. ### Remarks -This method saves the state of the application and any state information for the provided frame window. If you do not provide a frame window, the method only saves the application state. The application information includes the state of the [CMouseManager Class](../../mfc/reference/cmousemanager-class.md), [CContextMenuManager Class](../../mfc/reference/ccontextmenumanager-class.md), [CKeyboardManager Class](../../mfc/reference/ckeyboardmanager-class.md), and the [CUserToolsManager Class](../../mfc/reference/cusertoolsmanager-class.md). +This method saves the state of the application and any state information for the provided frame window. If you don't provide a frame window, the method only saves the application state. The application information includes the state of the [`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md), [`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md), [`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md), and the [`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md). -The *lpszSectionName* parameter is not the absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSectionName`* parameter isn't the absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -## CWinAppEx::SetRegistryBase +## `CWinAppEx::SetRegistryBase` Sets the default registry path for the application. @@ -1087,7 +1086,7 @@ LPCTSTR SetRegistryBase(LPCTSTR lpszSectionName = NULL); ### Parameters -*lpszSectionName*
+*`lpszSectionName`*\ [in] A string that contains the path of a registry key. ### Return Value @@ -1096,9 +1095,9 @@ A string that contains the path of the default registry location. ### Remarks -All methods of the [CWinAppEx Class](../../mfc/reference/cwinappex-class.md) that access the registry start in a default location. Use this method to change that default registry location. Use [CWinAppEx::GetRegistryBase](#getregistrybase) to retrieve the default registry location. +All methods of the [`CWinAppEx` Class](../../mfc/reference/cwinappex-class.md) that access the registry start in a default location. Use this method to change that default registry location. Use [`CWinAppEx::GetRegistryBase`](#getregistrybase) to retrieve the default registry location. -## CWinAppEx::ShowPopupMenu +## `CWinAppEx::ShowPopupMenu` Displays a popup menu. @@ -1111,13 +1110,13 @@ virtual BOOL ShowPopupMenu( ### Parameters -*uiMenuResId*
+*`uiMenuResId`*\ [in] A menu resource ID. -*point*
-[in] A [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) that specifies the position of the menu in screen coordinates. +*`point`*\ +[in] A [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) that specifies the position of the menu in screen coordinates. -*pWnd*
+*`pWnd`*\ [in] A pointer to the window that owns the popup menu. ### Return Value @@ -1126,11 +1125,11 @@ Nonzero if the popup menu is displayed successfully; 0 otherwise. ### Remarks -This method displays the menu associated with *uiMenuResId*. +This method displays the menu associated with *`uiMenuResId`*. -To support popup menus, you must have a [CContextMenuManager](../../mfc/reference/ccontextmenumanager-class.md) object. If you have not initialized the `CContextMenuManager` object, `ShowPopupMenu` will fail. +To support popup menus, you must have a [`CContextMenuManager`](../../mfc/reference/ccontextmenumanager-class.md) object. If you haven't initialized the `CContextMenuManager` object, `ShowPopupMenu` will fail. -## CWinAppEx::StoreWindowPlacement +## `CWinAppEx::StoreWindowPlacement` Called by the framework to write the size and location of the main frame window to the registry. @@ -1143,13 +1142,13 @@ virtual BOOL StoreWindowPlacement( ### Parameters -*nFlags*
+*`nFlags`*\ [in] Flags that control the position of the minimized window and how the operating system switches between a minimized window and a restored window. -*nShowCmd*
-[in] An integer that specifies the show state of the window. For more information about possible values, see [CWnd::ShowWindow](../../mfc/reference/cwnd-class.md#showwindow). +*`nShowCmd`*\ +[in] An integer that specifies the show state of the window. For more information about possible values, see [`CWnd::ShowWindow`](../../mfc/reference/cwnd-class.md#showwindow). -*rectNormalPosition*
+*`rectNormalPosition`*\ [in] A rectangle that contains the coordinates of the main frame window when it is in the restored state. ### Return Value @@ -1158,11 +1157,11 @@ Nonzero if successful; 0 otherwise. ### Remarks -By default, MFC automatically saves the position and state of the main frame window before the application exits. This information is stored in the Windows registry under the WindowPlacement key in the default registry location for your application. For more information about the default registry location of your application, see [CWinAppEx::GetRegistryBase](#getregistrybase). +By default, MFC automatically saves the position and state of the main frame window before the application exits. This information is stored in the Windows registry under the WindowPlacement key in the default registry location for your application. For more information about the default registry location of your application, see [`CWinAppEx::GetRegistryBase`](#getregistrybase). Override this method if you want to store additional information about the main frame window. -## CWinAppEx::WriteBinary +## `CWinAppEx::WriteBinary` Writes binary data to the registry. @@ -1175,26 +1174,26 @@ BOOL WriteBinary( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry key. -*pData*
+*`pData`*\ [in] The data to store. -*nBytes*
-[in] The size of *pData* in bytes. +*`nBytes`*\ +[in] The size of *`pData`* in bytes. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszEntry* parameter is the name of a registry entry that is located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry that is located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -If the key specified by *lpszEntry* does not exist, this method will create it. +If the key specified by *`lpszEntry`* doesn't exist, this method will create it. -## CWinAppEx::WriteInt +## `CWinAppEx::WriteInt` Writes numeric data to the registry. @@ -1206,25 +1205,25 @@ BOOL WriteInt( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry key. -*nValue*
+*`nValue`*\ [in] The data to store. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszEntry* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -If the key specified by *lpszEntry* does not exist, this method will create it. +If the key specified by *`lpszEntry`* doesn't exist, this method will create it. -## CWinAppEx::WriteObject +## `CWinAppEx::WriteObject` -Writes data derived from the [CObject Class](../../mfc/reference/cobject-class.md) to the registry. +Writes data derived from the [`CObject` Class](../../mfc/reference/cobject-class.md) to the registry. ``` BOOL WriteObject( @@ -1234,21 +1233,21 @@ BOOL WriteObject( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to set. -*obj*
+*`obj`*\ [in] A reference to `CObject` data that the method will store. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -This method writes the *obj* data to the specified value under the default registry key. Use [CWinAppEx::GetRegistryBase](#getregistrybase) to determine the current registry key. +This method writes the *`obj`* data to the specified value under the default registry key. Use [`CWinAppEx::GetRegistryBase`](#getregistrybase) to determine the current registry key. -## CWinAppEx::WriteSectionBinary +## `CWinAppEx::WriteSectionBinary` Writes binary data to a value in the registry. @@ -1262,29 +1261,29 @@ BOOL WriteSectionBinary( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the name of a registry key -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to set. -*pData*
+*`pData`*\ [in] The data to write to the registry. -*nBytes*
-[in] The size of *pData* in bytes. +*`nBytes`*\ +[in] The size of *`pData`* in bytes. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszSubSection* parameter is not the absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't the absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -If the key specified by *lpszEntry* does not exist, this method will create it. +If the key specified by *`lpszEntry`* doesn't exist, this method will create it. -## CWinAppEx::WriteSectionInt +## `CWinAppEx::WriteSectionInt` Writes numeric data to the registry. @@ -1297,28 +1296,28 @@ BOOL WriteSectionInt( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the relative path of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to set. -*nValue*
+*`nValue`*\ [in] The data to write to the registry. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -If the key specified by *lpszEntry* does not exist, this method will create it. +If the key specified by *`lpszEntry`* doesn't exist, this method will create it. -## CWinAppEx::WriteSectionObject +## `CWinAppEx::WriteSectionObject` -Writes data derived from the [CObject Class](../../mfc/reference/cobject-class.md) to a specific registry value. +Writes data derived from the [`CObject` Class](../../mfc/reference/cobject-class.md) to a specific registry value. ``` BOOL WriteSectionObject( @@ -1329,26 +1328,26 @@ BOOL WriteSectionObject( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the name of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of the value to set. -*obj*
+*`obj`*\ [in] The data to store. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase), respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase), respectively. -If the value specified by *lpszEntry* does not exist under the registry key specified by *lpszSubSection*, this method will create that value. +If the value specified by *`lpszEntry`* doesn't exist under the registry key specified by *`lpszSubSection`*, this method will create that value. -## CWinAppEx::WriteSectionString +## `CWinAppEx::WriteSectionString` Writes string data to a value in the registry. @@ -1361,26 +1360,26 @@ BOOL WriteSectionString( ### Parameters -*lpszSubSection*
+*`lpszSubSection`*\ [in] A string that contains the name of a registry key. -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the value to set. -*lpszValue*
+*`lpszValue`*\ [in] The string data to write to the registry. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszSubSection* parameter is not an absolute path for a registry entry. It is a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase), respectively. +The *`lpszSubSection`* parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase), respectively. -If the value specified by *lpszEntry* does not exist under *lpszSubSection*, this method will create it. +If the value specified by *`lpszEntry`* doesn't exist under *`lpszSubSection`*, this method will create it. -## CWinAppEx::WriteString +## `CWinAppEx::WriteString` Writes string data to the registry. @@ -1392,28 +1391,28 @@ BOOL WriteString( ### Parameters -*lpszEntry*
+*`lpszEntry`*\ [in] A string that contains the name of a registry key. -*lpszValue*
+*`lpszValue`*\ [in] The data to store. ### Return Value -TRUE if this method is successful; otherwise FALSE. +`TRUE` if this method is successful; otherwise `FALSE`. ### Remarks -The *lpszEntry* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [CWinAppEx::GetRegistryBase](#getregistrybase) and [CWinAppEx::SetRegistryBase](#setregistrybase) respectively. +The *`lpszEntry`* parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods [`CWinAppEx::GetRegistryBase`](#getregistrybase) and [`CWinAppEx::SetRegistryBase`](#setregistrybase) respectively. -If the key specified by *lspzEntry* does not exist, this method will create it. +If the key specified by *`lspzEntry`* doesn't exist, this method will create it. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[Classes](../../mfc/reference/mfc-classes.md)
-[CWinApp Class](../../mfc/reference/cwinapp-class.md)
-[CMouseManager Class](../../mfc/reference/cmousemanager-class.md)
-[CContextMenuManager Class](../../mfc/reference/ccontextmenumanager-class.md)
-[CKeyboardManager Class](../../mfc/reference/ckeyboardmanager-class.md)
-[CUserToolsManager Class](../../mfc/reference/cusertoolsmanager-class.md) +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[Classes](../../mfc/reference/mfc-classes.md)\ +[`CWinApp` Class](../../mfc/reference/cwinapp-class.md)\ +[`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md)\ +[`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md)\ +[`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md)\ +[`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md) diff --git a/docs/mfc/reference/cwindowdc-class.md b/docs/mfc/reference/cwindowdc-class.md index 19f890b5ce..e27c7be752 100644 --- a/docs/mfc/reference/cwindowdc-class.md +++ b/docs/mfc/reference/cwindowdc-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CWindowDC Class" title: "CWindowDC Class" -ms.date: "11/04/2016" +description: "Learn more about: CWindowDC Class" +ms.date: 11/04/2016 f1_keywords: ["CWindowDC", "AFXWIN/CWindowDC", "AFXWIN/CWindowDC::CWindowDC", "AFXWIN/CWindowDC::m_hWnd"] helpviewer_keywords: ["CWindowDC [MFC], CWindowDC", "CWindowDC [MFC], m_hWnd"] -ms.assetid: 876a3641-4cde-471c-b0d1-fe58b32af79c --- # CWindowDC Class @@ -32,7 +31,7 @@ class CWindowDC : public CDC ## Remarks -Calls the Windows function [GetWindowDC](/windows/win32/api/winuser/nf-winuser-getwindowdc)at construction time and [ReleaseDC](/windows/win32/api/winuser/nf-winuser-releasedc) at destruction time. This means that a `CWindowDC` object accesses the entire screen area of a [CWnd](../../mfc/reference/cwnd-class.md) (both client and nonclient areas). +Calls the Windows function [GetWindowDC](/windows/win32/api/winuser/nf-winuser-getwindowdc) at construction time and [ReleaseDC](/windows/win32/api/winuser/nf-winuser-releasedc) at destruction time. This means that a `CWindowDC` object accesses the entire screen area of a [CWnd](../../mfc/reference/cwnd-class.md) (both client and nonclient areas). For more information on using `CWindowDC`, see [Device Contexts](../../mfc/device-contexts.md). diff --git a/docs/mfc/reference/cwinformsview-class.md b/docs/mfc/reference/cwinformsview-class.md index b681ae885a..624a55aadf 100644 --- a/docs/mfc/reference/cwinformsview-class.md +++ b/docs/mfc/reference/cwinformsview-class.md @@ -70,7 +70,7 @@ A pointer to the data type of the Windows Forms user control. In the following example, the `CUserView` class inherits from `CWinFormsView` and passes the type of `UserControl1` to the `CWinFormsView` constructor. `UserControl1` is a custom-built control in ControlLibrary1.dll. [!code-cpp[NVC_MFC_Managed#1](../../mfc/reference/codesnippet/cpp/cwinformsview-class_1.h)] - +  [!code-cpp[NVC_MFC_Managed#2](../../mfc/reference/codesnippet/cpp/cwinformsview-class_2.cpp)] ## CWinFormsView::GetControl diff --git a/docs/mfc/reference/cwnd-class.md b/docs/mfc/reference/cwnd-class.md index 7c3e7054d3..7465c5223e 100644 --- a/docs/mfc/reference/cwnd-class.md +++ b/docs/mfc/reference/cwnd-class.md @@ -4,7 +4,6 @@ title: "CWnd Class" ms.date: "8/25/2021" f1_keywords: ["CWnd", "AFXWIN/CWnd", "AFXWIN/CWnd::CWnd", "AFXWIN/CWnd::accDoDefaultAction", "AFXWIN/CWnd::accHitTest", "AFXWIN/CWnd::accLocation", "AFXWIN/CWnd::accNavigate", "AFXWIN/CWnd::accSelect", "AFXWIN/CWnd::AnimateWindow", "AFXWIN/CWnd::ArrangeIconicWindows", "AFXWIN/CWnd::Attach", "AFXWIN/CWnd::BeginModalState", "AFXWIN/CWnd::BeginPaint", "AFXWIN/CWnd::BindDefaultProperty", "AFXWIN/CWnd::BindProperty", "AFXWIN/CWnd::BringWindowToTop", "AFXWIN/CWnd::CalcWindowRect", "AFXWIN/CWnd::CancelToolTips", "AFXWIN/CWnd::CenterWindow", "AFXWIN/CWnd::ChangeClipboardChain", "AFXWIN/CWnd::CheckDlgButton", "AFXWIN/CWnd::CheckRadioButton", "AFXWIN/CWnd::ChildWindowFromPoint", "AFXWIN/CWnd::ClientToScreen", "AFXWIN/CWnd::CloseWindow", "AFXWIN/CWnd::ContinueModal", "AFXWIN/CWnd::Create", "AFXWIN/CWnd::CreateAccessibleProxy", "AFXWIN/CWnd::CreateCaret", "AFXWIN/CWnd::CreateControl", "AFXWIN/CWnd::CreateEx", "AFXWIN/CWnd::CreateGrayCaret", "AFXWIN/CWnd::CreateSolidCaret", "AFXWIN/CWnd::DeleteTempMap", "AFXWIN/CWnd::DestroyWindow", "AFXWIN/CWnd::Detach", "AFXWIN/CWnd::DlgDirList", "AFXWIN/CWnd::DlgDirListComboBox", "AFXWIN/CWnd::DlgDirSelect", "AFXWIN/CWnd::DlgDirSelectComboBox", "AFXWIN/CWnd::DragAcceptFiles", "AFXWIN/CWnd::DragDetect", "AFXWIN/CWnd::DrawAnimatedRects", "AFXWIN/CWnd::DrawCaption", "AFXWIN/CWnd::DrawMenuBar", "AFXWIN/CWnd::EnableActiveAccessibility", "AFXWIN/CWnd::EnableDynamicLayout", "AFXWIN/CWnd::EnableD2DSupport", "AFXWIN/CWnd::EnableScrollBar", "AFXWIN/CWnd::EnableScrollBarCtrl", "AFXWIN/CWnd::EnableToolTips", "AFXWIN/CWnd::EnableTrackingToolTips", "AFXWIN/CWnd::EnableWindow", "AFXWIN/CWnd::EndModalLoop", "AFXWIN/CWnd::EndModalState", "AFXWIN/CWnd::EndPaint", "AFXWIN/CWnd::ExecuteDlgInit", "AFXWIN/CWnd::FilterToolTipMessage", "AFXWIN/CWnd::FindWindow", "AFXWIN/CWnd::FindWindowEx", "AFXWIN/CWnd::FlashWindow", "AFXWIN/CWnd::FlashWindowEx", "AFXWIN/CWnd::FromHandle", "AFXWIN/CWnd::FromHandlePermanent", "AFXWIN/CWnd::get_accChild", "AFXWIN/CWnd::get_accChildCount", "AFXWIN/CWnd::get_accDefaultAction", "AFXWIN/CWnd::get_accDescription", "AFXWIN/CWnd::get_accFocus", "AFXWIN/CWnd::get_accHelp", "AFXWIN/CWnd::get_accHelpTopic", "AFXWIN/CWnd::get_accKeyboardShortcut", "AFXWIN/CWnd::get_accName", "AFXWIN/CWnd::get_accParent", "AFXWIN/CWnd::get_accRole", "AFXWIN/CWnd::get_accSelection", "AFXWIN/CWnd::get_accState", "AFXWIN/CWnd::get_accValue", "AFXWIN/CWnd::GetActiveWindow", "AFXWIN/CWnd::GetAncestor", "AFXWIN/CWnd::GetCapture", "AFXWIN/CWnd::GetCaretPos", "AFXWIN/CWnd::GetCheckedRadioButton", "AFXWIN/CWnd::GetClientRect", "AFXWIN/CWnd::GetClipboardOwner", "AFXWIN/CWnd::GetClipboardViewer", "AFXWIN/CWnd::GetControlUnknown", "AFXWIN/CWnd::GetDC", "AFXWIN/CWnd::GetDCEx", "AFXWIN/CWnd::GetDCRenderTarget", "AFXWIN/CWnd::GetDescendantWindow", "AFXWIN/CWnd::GetDesktopWindow", "AFXWIN/CWnd::GetDlgCtrlID", "AFXWIN/CWnd::GetDlgItem", "AFXWIN/CWnd::GetDlgItemInt", "AFXWIN/CWnd::GetDlgItemText", "AFXWIN/CWnd::GetDSCCursor", "AFXWIN/CWnd::GetDynamicLayout", "AFXWIN/CWnd::GetExStyle", "AFXWIN/CWnd::GetFocus", "AFXWIN/CWnd::GetFont", "AFXWIN/CWnd::GetForegroundWindow", "AFXWIN/CWnd::GetIcon", "AFXWIN/CWnd::GetLastActivePopup", "AFXWIN/CWnd::GetLayeredWindowAttributes", "AFXWIN/CWnd::GetMenu", "AFXWIN/CWnd::GetNextDlgGroupItem", "AFXWIN/CWnd::GetNextDlgTabItem", "AFXWIN/CWnd::GetNextWindow", "AFXWIN/CWnd::GetOleControlSite", "AFXWIN/CWnd::GetOpenClipboardWindow", "AFXWIN/CWnd::GetOwner", "AFXWIN/CWnd::GetParent", "AFXWIN/CWnd::GetParentFrame", "AFXWIN/CWnd::GetParentOwner", "AFXWIN/CWnd::GetProperty", "AFXWIN/CWnd::GetRenderTarget", "AFXWIN/CWnd::GetSafeHwnd", "AFXWIN/CWnd::GetSafeOwner", "AFXWIN/CWnd::GetScrollBarCtrl", "AFXWIN/CWnd::GetScrollBarInfo", "AFXWIN/CWnd::GetScrollInfo", "AFXWIN/CWnd::GetScrollLimit", "AFXWIN/CWnd::GetScrollPos", "AFXWIN/CWnd::GetScrollRange", "AFXWIN/CWnd::GetStyle", "AFXWIN/CWnd::GetSystemMenu", "AFXWIN/CWnd::GetTitleBarInfo", "AFXWIN/CWnd::GetTopLevelFrame", "AFXWIN/CWnd::GetTopLevelOwner", "AFXWIN/CWnd::GetTopLevelParent", "AFXWIN/CWnd::GetTopWindow", "AFXWIN/CWnd::GetUpdateRect", "AFXWIN/CWnd::GetUpdateRgn", "AFXWIN/CWnd::GetWindow", "AFXWIN/CWnd::GetWindowContextHelpId", "AFXWIN/CWnd::GetWindowDC", "AFXWIN/CWnd::GetWindowedChildCount", "AFXWIN/CWnd::GetWindowInfo", "AFXWIN/CWnd::GetWindowlessChildCount", "AFXWIN/CWnd::GetWindowPlacement", "AFXWIN/CWnd::GetWindowRect", "AFXWIN/CWnd::GetWindowRgn", "AFXWIN/CWnd::GetWindowText", "AFXWIN/CWnd::GetWindowTextLength", "AFXWIN/CWnd::HideCaret", "AFXWIN/CWnd::HiliteMenuItem", "AFXWIN/CWnd::HtmlHelp", "AFXWIN/CWnd::Invalidate", "AFXWIN/CWnd::InvalidateRect", "AFXWIN/CWnd::InvalidateRgn", "AFXWIN/CWnd::InvokeHelper", "AFXWIN/CWnd::IsChild", "AFXWIN/CWnd::IsD2DSupportEnabled", "AFXWIN/CWnd::IsDialogMessage", "AFXWIN/CWnd::IsDlgButtonChecked", "AFXWIN/CWnd::IsDynamicLayoutEnabled", "AFXWIN/CWnd::IsIconic", "AFXWIN/CWnd::IsTouchWindow", "AFXWIN/CWnd::IsWindowEnabled", "AFXWIN/CWnd::IsWindowVisible", "AFXWIN/CWnd::IsZoomed", "AFXWIN/CWnd::KillTimer", "AFXWIN/CWnd::LockWindowUpdate", "AFXWIN/CWnd::MapWindowPoints", "AFXWIN/CWnd::MessageBox", "AFXWIN/CWnd::ModifyStyle", "AFXWIN/CWnd::ModifyStyleEx", "AFXWIN/CWnd::MoveWindow", "AFXWIN/CWnd::NotifyWinEvent", "AFXWIN/CWnd::OnAmbientProperty", "AFXWIN/CWnd::OnDrawIconicThumbnailOrLivePreview", "AFXWIN/CWnd::OnHelp", "AFXWIN/CWnd::OnHelpFinder", "AFXWIN/CWnd::OnHelpIndex", "AFXWIN/CWnd::OnHelpUsing", "AFXWIN/CWnd::OnToolHitTest", "AFXWIN/CWnd::OpenClipboard", "AFXWIN/CWnd::PaintWindowlessControls", "AFXWIN/CWnd::PostMessage", "AFXWIN/CWnd::PreCreateWindow", "AFXWIN/CWnd::PreSubclassWindow", "AFXWIN/CWnd::PreTranslateMessage", "AFXWIN/CWnd::Print", "AFXWIN/CWnd::PrintClient", "AFXWIN/CWnd::PrintWindow", "AFXWIN/CWnd::RedrawWindow", "AFXWIN/CWnd::RegisterTouchWindow", "AFXWIN/CWnd::ReleaseDC", "AFXWIN/CWnd::RepositionBars", "AFXWIN/CWnd::RunModalLoop", "AFXWIN/CWnd::ScreenToClient", "AFXWIN/CWnd::ScrollWindow", "AFXWIN/CWnd::ScrollWindowEx", "AFXWIN/CWnd::SendChildNotifyLastMsg", "AFXWIN/CWnd::SendDlgItemMessage", "AFXWIN/CWnd::SendMessage", "AFXWIN/CWnd::SendMessageToDescendants", "AFXWIN/CWnd::SendNotifyMessage", "AFXWIN/CWnd::SetActiveWindow", "AFXWIN/CWnd::SetCapture", "AFXWIN/CWnd::SetCaretPos", "AFXWIN/CWnd::SetClipboardViewer", "AFXWIN/CWnd::SetDlgCtrlID", "AFXWIN/CWnd::SetDlgItemInt", "AFXWIN/CWnd::SetDlgItemText", "AFXWIN/CWnd::SetFocus", "AFXWIN/CWnd::SetFont", "AFXWIN/CWnd::SetForegroundWindow", "AFXWIN/CWnd::SetIcon", "AFXWIN/CWnd::SetLayeredWindowAttributes", "AFXWIN/CWnd::SetMenu", "AFXWIN/CWnd::SetOwner", "AFXWIN/CWnd::SetParent", "AFXWIN/CWnd::SetProperty", "AFXWIN/CWnd::SetRedraw", "AFXWIN/CWnd::SetScrollInfo", "AFXWIN/CWnd::SetScrollPos", "AFXWIN/CWnd::SetScrollRange", "AFXWIN/CWnd::SetTimer", "AFXWIN/CWnd::SetWindowContextHelpId", "AFXWIN/CWnd::SetWindowPlacement", "AFXWIN/CWnd::SetWindowPos", "AFXWIN/CWnd::SetWindowRgn", "AFXWIN/CWnd::SetWindowText", "AFXWIN/CWnd::ShowCaret", "AFXWIN/CWnd::ShowOwnedPopups", "AFXWIN/CWnd::ShowScrollBar", "AFXWIN/CWnd::ShowWindow", "AFXWIN/CWnd::SubclassDlgItem", "AFXWIN/CWnd::SubclassWindow", "AFXWIN/CWnd::UnlockWindowUpdate", "AFXWIN/CWnd::UnsubclassWindow", "AFXWIN/CWnd::UpdateData", "AFXWIN/CWnd::UpdateDialogControls", "AFXWIN/CWnd::UpdateLayeredWindow", "AFXWIN/CWnd::UpdateWindow", "AFXWIN/CWnd::ValidateRect", "AFXWIN/CWnd::ValidateRgn", "AFXWIN/CWnd::WindowFromPoint", "AFXWIN/CWnd::WinHelp", "AFXWIN/CWnd::Default", "AFXWIN/CWnd::DefWindowProc", "AFXWIN/CWnd::DoDataExchange", "AFXWIN/CWnd::GetCurrentMessage", "AFXWIN/CWnd::InitDynamicLayout", "AFXWIN/CWnd::LoadDynamicLayoutResource", "AFXWIN/CWnd::OnActivate", "AFXWIN/CWnd::OnActivateApp", "AFXWIN/CWnd::OnAppCommand", "AFXWIN/CWnd::OnAskCbFormatName", "AFXWIN/CWnd::OnCancelMode", "AFXWIN/CWnd::OnCaptureChanged", "AFXWIN/CWnd::OnChangeCbChain", "AFXWIN/CWnd::OnChangeUIState", "AFXWIN/CWnd::OnChar", "AFXWIN/CWnd::OnCharToItem", "AFXWIN/CWnd::OnChildActivate", "AFXWIN/CWnd::OnChildNotify", "AFXWIN/CWnd::OnClipboardUpdate", "AFXWIN/CWnd::OnClose", "AFXWIN/CWnd::OnColorizationColorChanged", "AFXWIN/CWnd::OnCommand", "AFXWIN/CWnd::OnCompacting", "AFXWIN/CWnd::OnCompareItem", "AFXWIN/CWnd::OnCompositionChanged", "AFXWIN/CWnd::OnContextMenu", "AFXWIN/CWnd::OnCopyData", "AFXWIN/CWnd::OnCreate", "AFXWIN/CWnd::OnCtlColor", "AFXWIN/CWnd::OnDeadChar", "AFXWIN/CWnd::OnDeleteItem", "AFXWIN/CWnd::OnDestroy", "AFXWIN/CWnd::OnDestroyClipboard", "AFXWIN/CWnd::OnDeviceChange", "AFXWIN/CWnd::OnDevModeChange", "AFXWIN/CWnd::OnDrawClipboard", "AFXWIN/CWnd::OnDrawItem", "AFXWIN/CWnd::OnDropFiles", "AFXWIN/CWnd::OnEnable", "AFXWIN/CWnd::OnEndSession", "AFXWIN/CWnd::OnEnterIdle", "AFXWIN/CWnd::OnEnterMenuLoop", "AFXWIN/CWnd::OnEnterSizeMove", "AFXWIN/CWnd::OnEraseBkgnd", "AFXWIN/CWnd::OnExitMenuLoop", "AFXWIN/CWnd::OnExitSizeMove", "AFXWIN/CWnd::OnFontChange", "AFXWIN/CWnd::OnGetDlgCode", "AFXWIN/CWnd::OnGetMinMaxInfo", "AFXWIN/CWnd::OnHelpInfo", "AFXWIN/CWnd::OnHotKey", "AFXWIN/CWnd::OnHScroll", "AFXWIN/CWnd::OnHScrollClipboard", "AFXWIN/CWnd::OnIconEraseBkgnd", "AFXWIN/CWnd::OnInitMenu", "AFXWIN/CWnd::OnInitMenuPopup", "AFXWIN/CWnd::OnInputDeviceChange", "AFXWIN/CWnd::OnInputLangChange", "AFXWIN/CWnd::OnInputLangChangeRequest", "AFXWIN/CWnd::OnKeyDown", "AFXWIN/CWnd::OnKeyUp", "AFXWIN/CWnd::OnKillFocus", "AFXWIN/CWnd::OnLButtonDblClk", "AFXWIN/CWnd::OnLButtonDown", "AFXWIN/CWnd::OnLButtonUp", "AFXWIN/CWnd::OnMButtonDblClk", "AFXWIN/CWnd::OnMButtonDown", "AFXWIN/CWnd::OnMButtonUp", "AFXWIN/CWnd::OnMDIActivate", "AFXWIN/CWnd::OnMeasureItem", "AFXWIN/CWnd::OnMenuChar", "AFXWIN/CWnd::OnMenuDrag", "AFXWIN/CWnd::OnMenuGetObject", "AFXWIN/CWnd::OnMenuRButtonUp", "AFXWIN/CWnd::OnMenuSelect", "AFXWIN/CWnd::OnMouseActivate", "AFXWIN/CWnd::OnMouseHover", "AFXWIN/CWnd::OnMouseHWheel", "AFXWIN/CWnd::OnMouseLeave", "AFXWIN/CWnd::OnMouseMove", "AFXWIN/CWnd::OnMouseWheel", "AFXWIN/CWnd::OnMove", "AFXWIN/CWnd::OnMoving", "AFXWIN/CWnd::OnNcActivate", "AFXWIN/CWnd::OnNcCalcSize", "AFXWIN/CWnd::OnNcCreate", "AFXWIN/CWnd::OnNcDestroy", "AFXWIN/CWnd::OnNcHitTest", "AFXWIN/CWnd::OnNcLButtonDblClk", "AFXWIN/CWnd::OnNcLButtonDown", "AFXWIN/CWnd::OnNcLButtonUp", "AFXWIN/CWnd::OnNcMButtonDblClk", "AFXWIN/CWnd::OnNcMButtonDown", "AFXWIN/CWnd::OnNcMButtonUp", "AFXWIN/CWnd::OnNcMouseHover", "AFXWIN/CWnd::OnNcMouseLeave", "AFXWIN/CWnd::OnNcMouseMove", "AFXWIN/CWnd::OnNcPaint", "AFXWIN/CWnd::OnNcRButtonDblClk", "AFXWIN/CWnd::OnNcRButtonDown", "AFXWIN/CWnd::OnNcRButtonUp", "AFXWIN/CWnd::OnNcRenderingChanged", "AFXWIN/CWnd::OnNcXButtonDblClk", "AFXWIN/CWnd::OnNcXButtonDown", "AFXWIN/CWnd::OnNcXButtonUp", "AFXWIN/CWnd::OnNextMenu", "AFXWIN/CWnd::OnNotify", "AFXWIN/CWnd::OnNotifyFormat", "AFXWIN/CWnd::OnPaint", "AFXWIN/CWnd::OnPaintClipboard", "AFXWIN/CWnd::OnPaletteChanged", "AFXWIN/CWnd::OnPaletteIsChanging", "AFXWIN/CWnd::OnParentNotify", "AFXWIN/CWnd::OnPowerBroadcast", "AFXWIN/CWnd::OnQueryDragIcon", "AFXWIN/CWnd::OnQueryEndSession", "AFXWIN/CWnd::OnQueryNewPalette", "AFXWIN/CWnd::OnQueryOpen", "AFXWIN/CWnd::OnQueryUIState", "AFXWIN/CWnd::OnRawInput", "AFXWIN/CWnd::OnRButtonDblClk", "AFXWIN/CWnd::OnRButtonDown", "AFXWIN/CWnd::OnRButtonUp", "AFXWIN/CWnd::OnRenderAllFormats", "AFXWIN/CWnd::OnRenderFormat", "AFXWIN/CWnd::OnSessionChange", "AFXWIN/CWnd::OnSetCursor", "AFXWIN/CWnd::OnSetFocus", "AFXWIN/CWnd::OnSettingChange", "AFXWIN/CWnd::OnShowWindow", "AFXWIN/CWnd::OnSize", "AFXWIN/CWnd::OnSizeClipboard", "AFXWIN/CWnd::OnSizing", "AFXWIN/CWnd::OnSpoolerStatus", "AFXWIN/CWnd::OnStyleChanged", "AFXWIN/CWnd::OnStyleChanging", "AFXWIN/CWnd::OnSysChar", "AFXWIN/CWnd::OnSysColorChange", "AFXWIN/CWnd::OnSysCommand", "AFXWIN/CWnd::OnSysDeadChar", "AFXWIN/CWnd::OnSysKeyDown", "AFXWIN/CWnd::OnSysKeyUp", "AFXWIN/CWnd::OnTCard", "AFXWIN/CWnd::OnTimeChange", "AFXWIN/CWnd::OnTimer", "AFXWIN/CWnd::OnTouchInput", "AFXWIN/CWnd::OnTouchInputs", "AFXWIN/CWnd::OnUniChar", "AFXWIN/CWnd::OnUnInitMenuPopup", "AFXWIN/CWnd::OnUpdateUIState", "AFXWIN/CWnd::OnUserChanged", "AFXWIN/CWnd::OnVKeyToItem", "AFXWIN/CWnd::OnVScroll", "AFXWIN/CWnd::OnVScrollClipboard", "AFXWIN/CWnd::OnWindowPosChanged", "AFXWIN/CWnd::OnWindowPosChanging", "AFXWIN/CWnd::OnWinIniChange", "AFXWIN/CWnd::OnWndMsg", "AFXWIN/CWnd::OnXButtonDblClk", "AFXWIN/CWnd::OnXButtonDown", "AFXWIN/CWnd::OnXButtonUp", "AFXWIN/CWnd::PostNcDestroy", "AFXWIN/CWnd::ReflectChildNotify", "AFXWIN/CWnd::ReflectLastMsg", "AFXWIN/CWnd::ResizeDynamicLayout", "AFXWIN/CWnd::WindowProc", "AFXWIN/CWnd::m_hWnd"] helpviewer_keywords: ["CWnd [MFC], CWnd", "CWnd [MFC], accDoDefaultAction", "CWnd [MFC], accHitTest", "CWnd [MFC], accLocation", "CWnd [MFC], accNavigate", "CWnd [MFC], accSelect", "CWnd [MFC], AnimateWindow", "CWnd [MFC], ArrangeIconicWindows", "CWnd [MFC], Attach", "CWnd [MFC], BeginModalState", "CWnd [MFC], BeginPaint", "CWnd [MFC], BindDefaultProperty", "CWnd [MFC], BindProperty", "CWnd [MFC], BringWindowToTop", "CWnd [MFC], CalcWindowRect", "CWnd [MFC], CancelToolTips", "CWnd [MFC], CenterWindow", "CWnd [MFC], ChangeClipboardChain", "CWnd [MFC], CheckDlgButton", "CWnd [MFC], CheckRadioButton", "CWnd [MFC], ChildWindowFromPoint", "CWnd [MFC], ClientToScreen", "CWnd [MFC], CloseWindow", "CWnd [MFC], ContinueModal", "CWnd [MFC], Create", "CWnd [MFC], CreateAccessibleProxy", "CWnd [MFC], CreateCaret", "CWnd [MFC], CreateControl", "CWnd [MFC], CreateEx", "CWnd [MFC], CreateGrayCaret", "CWnd [MFC], CreateSolidCaret", "CWnd [MFC], DeleteTempMap", "CWnd [MFC], DestroyWindow", "CWnd [MFC], Detach", "CWnd [MFC], DlgDirList", "CWnd [MFC], DlgDirListComboBox", "CWnd [MFC], DlgDirSelect", "CWnd [MFC], DlgDirSelectComboBox", "CWnd [MFC], DragAcceptFiles", "CWnd [MFC], DragDetect", "CWnd [MFC], DrawAnimatedRects", "CWnd [MFC], DrawCaption", "CWnd [MFC], DrawMenuBar", "CWnd [MFC], EnableActiveAccessibility", "CWnd [MFC], EnableDynamicLayout", "CWnd [MFC], EnableD2DSupport", "CWnd [MFC], EnableScrollBar", "CWnd [MFC], EnableScrollBarCtrl", "CWnd [MFC], EnableToolTips", "CWnd [MFC], EnableTrackingToolTips", "CWnd [MFC], EnableWindow", "CWnd [MFC], EndModalLoop", "CWnd [MFC], EndModalState", "CWnd [MFC], EndPaint", "CWnd [MFC], ExecuteDlgInit", "CWnd [MFC], FilterToolTipMessage", "CWnd [MFC], FindWindow", "CWnd [MFC], FindWindowEx", "CWnd [MFC], FlashWindow", "CWnd [MFC], FlashWindowEx", "CWnd [MFC], FromHandle", "CWnd [MFC], FromHandlePermanent", "CWnd [MFC], get_accChild", "CWnd [MFC], get_accChildCount", "CWnd [MFC], get_accDefaultAction", "CWnd [MFC], get_accDescription", "CWnd [MFC], get_accFocus", "CWnd [MFC], get_accHelp", "CWnd [MFC], get_accHelpTopic", "CWnd [MFC], get_accKeyboardShortcut", "CWnd [MFC], get_accName", "CWnd [MFC], get_accParent", "CWnd [MFC], get_accRole", "CWnd [MFC], get_accSelection", "CWnd [MFC], get_accState", "CWnd [MFC], get_accValue", "CWnd [MFC], GetActiveWindow", "CWnd [MFC], GetAncestor", "CWnd [MFC], GetCapture", "CWnd [MFC], GetCaretPos", "CWnd [MFC], GetCheckedRadioButton", "CWnd [MFC], GetClientRect", "CWnd [MFC], GetClipboardOwner", "CWnd [MFC], GetClipboardViewer", "CWnd [MFC], GetControlUnknown", "CWnd [MFC], GetDC", "CWnd [MFC], GetDCEx", "CWnd [MFC], GetDCRenderTarget", "CWnd [MFC], GetDescendantWindow", "CWnd [MFC], GetDesktopWindow", "CWnd [MFC], GetDlgCtrlID", "CWnd [MFC], GetDlgItem", "CWnd [MFC], GetDlgItemInt", "CWnd [MFC], GetDlgItemText", "CWnd [MFC], GetDSCCursor", "CWnd [MFC], GetDynamicLayout", "CWnd [MFC], GetExStyle", "CWnd [MFC], GetFocus", "CWnd [MFC], GetFont", "CWnd [MFC], GetForegroundWindow", "CWnd [MFC], GetIcon", "CWnd [MFC], GetLastActivePopup", "CWnd [MFC], GetLayeredWindowAttributes", "CWnd [MFC], GetMenu", "CWnd [MFC], GetNextDlgGroupItem", "CWnd [MFC], GetNextDlgTabItem", "CWnd [MFC], GetNextWindow", "CWnd [MFC], GetOleControlSite", "CWnd [MFC], GetOpenClipboardWindow", "CWnd [MFC], GetOwner", "CWnd [MFC], GetParent", "CWnd [MFC], GetParentFrame", "CWnd [MFC], GetParentOwner", "CWnd [MFC], GetProperty", "CWnd [MFC], GetRenderTarget", "CWnd [MFC], GetSafeHwnd", "CWnd [MFC], GetSafeOwner", "CWnd [MFC], GetScrollBarCtrl", "CWnd [MFC], GetScrollBarInfo", "CWnd [MFC], GetScrollInfo", "CWnd [MFC], GetScrollLimit", "CWnd [MFC], GetScrollPos", "CWnd [MFC], GetScrollRange", "CWnd [MFC], GetStyle", "CWnd [MFC], GetSystemMenu", "CWnd [MFC], GetTitleBarInfo", "CWnd [MFC], GetTopLevelFrame", "CWnd [MFC], GetTopLevelOwner", "CWnd [MFC], GetTopLevelParent", "CWnd [MFC], GetTopWindow", "CWnd [MFC], GetUpdateRect", "CWnd [MFC], GetUpdateRgn", "CWnd [MFC], GetWindow", "CWnd [MFC], GetWindowContextHelpId", "CWnd [MFC], GetWindowDC", "CWnd [MFC], GetWindowedChildCount", "CWnd [MFC], GetWindowInfo", "CWnd [MFC], GetWindowlessChildCount", "CWnd [MFC], GetWindowPlacement", "CWnd [MFC], GetWindowRect", "CWnd [MFC], GetWindowRgn", "CWnd [MFC], GetWindowText", "CWnd [MFC], GetWindowTextLength", "CWnd [MFC], HideCaret", "CWnd [MFC], HiliteMenuItem", "CWnd [MFC], HtmlHelp", "CWnd [MFC], Invalidate", "CWnd [MFC], InvalidateRect", "CWnd [MFC], InvalidateRgn", "CWnd [MFC], InvokeHelper", "CWnd [MFC], IsChild", "CWnd [MFC], IsD2DSupportEnabled", "CWnd [MFC], IsDialogMessage", "CWnd [MFC], IsDlgButtonChecked", "CWnd [MFC], IsDynamicLayoutEnabled", "CWnd [MFC], IsIconic", "CWnd [MFC], IsTouchWindow", "CWnd [MFC], IsWindowEnabled", "CWnd [MFC], IsWindowVisible", "CWnd [MFC], IsZoomed", "CWnd [MFC], KillTimer", "CWnd [MFC], LockWindowUpdate", "CWnd [MFC], MapWindowPoints", "CWnd [MFC], MessageBox", "CWnd [MFC], ModifyStyle", "CWnd [MFC], ModifyStyleEx", "CWnd [MFC], MoveWindow", "CWnd [MFC], NotifyWinEvent", "CWnd [MFC], OnAmbientProperty", "CWnd [MFC], OnDrawIconicThumbnailOrLivePreview", "CWnd [MFC], OnHelp", "CWnd [MFC], OnHelpFinder", "CWnd [MFC], OnHelpIndex", "CWnd [MFC], OnHelpUsing", "CWnd [MFC], OnToolHitTest", "CWnd [MFC], OpenClipboard", "CWnd [MFC], PaintWindowlessControls", "CWnd [MFC], PostMessage", "CWnd [MFC], PreCreateWindow", "CWnd [MFC], PreSubclassWindow", "CWnd [MFC], PreTranslateMessage", "CWnd [MFC], Print", "CWnd [MFC], PrintClient", "CWnd [MFC], PrintWindow", "CWnd [MFC], RedrawWindow", "CWnd [MFC], RegisterTouchWindow", "CWnd [MFC], ReleaseDC", "CWnd [MFC], RepositionBars", "CWnd [MFC], RunModalLoop", "CWnd [MFC], ScreenToClient", "CWnd [MFC], ScrollWindow", "CWnd [MFC], ScrollWindowEx", "CWnd [MFC], SendChildNotifyLastMsg", "CWnd [MFC], SendDlgItemMessage", "CWnd [MFC], SendMessage", "CWnd [MFC], SendMessageToDescendants", "CWnd [MFC], SendNotifyMessage", "CWnd [MFC], SetActiveWindow", "CWnd [MFC], SetCapture", "CWnd [MFC], SetCaretPos", "CWnd [MFC], SetClipboardViewer", "CWnd [MFC], SetDlgCtrlID", "CWnd [MFC], SetDlgItemInt", "CWnd [MFC], SetDlgItemText", "CWnd [MFC], SetFocus", "CWnd [MFC], SetFont", "CWnd [MFC], SetForegroundWindow", "CWnd [MFC], SetIcon", "CWnd [MFC], SetLayeredWindowAttributes", "CWnd [MFC], SetMenu", "CWnd [MFC], SetOwner", "CWnd [MFC], SetParent", "CWnd [MFC], SetProperty", "CWnd [MFC], SetRedraw", "CWnd [MFC], SetScrollInfo", "CWnd [MFC], SetScrollPos", "CWnd [MFC], SetScrollRange", "CWnd [MFC], SetTimer", "CWnd [MFC], SetWindowContextHelpId", "CWnd [MFC], SetWindowPlacement", "CWnd [MFC], SetWindowPos", "CWnd [MFC], SetWindowRgn", "CWnd [MFC], SetWindowText", "CWnd [MFC], ShowCaret", "CWnd [MFC], ShowOwnedPopups", "CWnd [MFC], ShowScrollBar", "CWnd [MFC], ShowWindow", "CWnd [MFC], SubclassDlgItem", "CWnd [MFC], SubclassWindow", "CWnd [MFC], UnlockWindowUpdate", "CWnd [MFC], UnsubclassWindow", "CWnd [MFC], UpdateData", "CWnd [MFC], UpdateDialogControls", "CWnd [MFC], UpdateLayeredWindow", "CWnd [MFC], UpdateWindow", "CWnd [MFC], ValidateRect", "CWnd [MFC], ValidateRgn", "CWnd [MFC], WindowFromPoint", "CWnd [MFC], WinHelp", "CWnd [MFC], Default", "CWnd [MFC], DefWindowProc", "CWnd [MFC], DoDataExchange", "CWnd [MFC], GetCurrentMessage", "CWnd [MFC], InitDynamicLayout", "CWnd [MFC], LoadDynamicLayoutResource", "CWnd [MFC], OnActivate", "CWnd [MFC], OnActivateApp", "CWnd [MFC], OnAppCommand", "CWnd [MFC], OnAskCbFormatName", "CWnd [MFC], OnCancelMode", "CWnd [MFC], OnCaptureChanged", "CWnd [MFC], OnChangeCbChain", "CWnd [MFC], OnChangeUIState", "CWnd [MFC], OnChar", "CWnd [MFC], OnCharToItem", "CWnd [MFC], OnChildActivate", "CWnd [MFC], OnChildNotify", "CWnd [MFC], OnClipboardUpdate", "CWnd [MFC], OnClose", "CWnd [MFC], OnColorizationColorChanged", "CWnd [MFC], OnCommand", "CWnd [MFC], OnCompacting", "CWnd [MFC], OnCompareItem", "CWnd [MFC], OnCompositionChanged", "CWnd [MFC], OnContextMenu", "CWnd [MFC], OnCopyData", "CWnd [MFC], OnCreate", "CWnd [MFC], OnCtlColor", "CWnd [MFC], OnDeadChar", "CWnd [MFC], OnDeleteItem", "CWnd [MFC], OnDestroy", "CWnd [MFC], OnDestroyClipboard", "CWnd [MFC], OnDeviceChange", "CWnd [MFC], OnDevModeChange", "CWnd [MFC], OnDrawClipboard", "CWnd [MFC], OnDrawItem", "CWnd [MFC], OnDropFiles", "CWnd [MFC], OnEnable", "CWnd [MFC], OnEndSession", "CWnd [MFC], OnEnterIdle", "CWnd [MFC], OnEnterMenuLoop", "CWnd [MFC], OnEnterSizeMove", "CWnd [MFC], OnEraseBkgnd", "CWnd [MFC], OnExitMenuLoop", "CWnd [MFC], OnExitSizeMove", "CWnd [MFC], OnFontChange", "CWnd [MFC], OnGetDlgCode", "CWnd [MFC], OnGetMinMaxInfo", "CWnd [MFC], OnHelpInfo", "CWnd [MFC], OnHotKey", "CWnd [MFC], OnHScroll", "CWnd [MFC], OnHScrollClipboard", "CWnd [MFC], OnIconEraseBkgnd", "CWnd [MFC], OnInitMenu", "CWnd [MFC], OnInitMenuPopup", "CWnd [MFC], OnInputDeviceChange", "CWnd [MFC], OnInputLangChange", "CWnd [MFC], OnInputLangChangeRequest", "CWnd [MFC], OnKeyDown", "CWnd [MFC], OnKeyUp", "CWnd [MFC], OnKillFocus", "CWnd [MFC], OnLButtonDblClk", "CWnd [MFC], OnLButtonDown", "CWnd [MFC], OnLButtonUp", "CWnd [MFC], OnMButtonDblClk", "CWnd [MFC], OnMButtonDown", "CWnd [MFC], OnMButtonUp", "CWnd [MFC], OnMDIActivate", "CWnd [MFC], OnMeasureItem", "CWnd [MFC], OnMenuChar", "CWnd [MFC], OnMenuDrag", "CWnd [MFC], OnMenuGetObject", "CWnd [MFC], OnMenuRButtonUp", "CWnd [MFC], OnMenuSelect", "CWnd [MFC], OnMouseActivate", "CWnd [MFC], OnMouseHover", "CWnd [MFC], OnMouseHWheel", "CWnd [MFC], OnMouseLeave", "CWnd [MFC], OnMouseMove", "CWnd [MFC], OnMouseWheel", "CWnd [MFC], OnMove", "CWnd [MFC], OnMoving", "CWnd [MFC], OnNcActivate", "CWnd [MFC], OnNcCalcSize", "CWnd [MFC], OnNcCreate", "CWnd [MFC], OnNcDestroy", "CWnd [MFC], OnNcHitTest", "CWnd [MFC], OnNcLButtonDblClk", "CWnd [MFC], OnNcLButtonDown", "CWnd [MFC], OnNcLButtonUp", "CWnd [MFC], OnNcMButtonDblClk", "CWnd [MFC], OnNcMButtonDown", "CWnd [MFC], OnNcMButtonUp", "CWnd [MFC], OnNcMouseHover", "CWnd [MFC], OnNcMouseLeave", "CWnd [MFC], OnNcMouseMove", "CWnd [MFC], OnNcPaint", "CWnd [MFC], OnNcRButtonDblClk", "CWnd [MFC], OnNcRButtonDown", "CWnd [MFC], OnNcRButtonUp", "CWnd [MFC], OnNcRenderingChanged", "CWnd [MFC], OnNcXButtonDblClk", "CWnd [MFC], OnNcXButtonDown", "CWnd [MFC], OnNcXButtonUp", "CWnd [MFC], OnNextMenu", "CWnd [MFC], OnNotify", "CWnd [MFC], OnNotifyFormat", "CWnd [MFC], OnPaint", "CWnd [MFC], OnPaintClipboard", "CWnd [MFC], OnPaletteChanged", "CWnd [MFC], OnPaletteIsChanging", "CWnd [MFC], OnParentNotify", "CWnd [MFC], OnPowerBroadcast", "CWnd [MFC], OnQueryDragIcon", "CWnd [MFC], OnQueryEndSession", "CWnd [MFC], OnQueryNewPalette", "CWnd [MFC], OnQueryOpen", "CWnd [MFC], OnQueryUIState", "CWnd [MFC], OnRawInput", "CWnd [MFC], OnRButtonDblClk", "CWnd [MFC], OnRButtonDown", "CWnd [MFC], OnRButtonUp", "CWnd [MFC], OnRenderAllFormats", "CWnd [MFC], OnRenderFormat", "CWnd [MFC], OnSessionChange", "CWnd [MFC], OnSetCursor", "CWnd [MFC], OnSetFocus", "CWnd [MFC], OnSettingChange", "CWnd [MFC], OnShowWindow", "CWnd [MFC], OnSize", "CWnd [MFC], OnSizeClipboard", "CWnd [MFC], OnSizing", "CWnd [MFC], OnSpoolerStatus", "CWnd [MFC], OnStyleChanged", "CWnd [MFC], OnStyleChanging", "CWnd [MFC], OnSysChar", "CWnd [MFC], OnSysColorChange", "CWnd [MFC], OnSysCommand", "CWnd [MFC], OnSysDeadChar", "CWnd [MFC], OnSysKeyDown", "CWnd [MFC], OnSysKeyUp", "CWnd [MFC], OnTCard", "CWnd [MFC], OnTimeChange", "CWnd [MFC], OnTimer", "CWnd [MFC], OnTouchInput", "CWnd [MFC], OnTouchInputs", "CWnd [MFC], OnUniChar", "CWnd [MFC], OnUnInitMenuPopup", "CWnd [MFC], OnUpdateUIState", "CWnd [MFC], OnUserChanged", "CWnd [MFC], OnVKeyToItem", "CWnd [MFC], OnVScroll", "CWnd [MFC], OnVScrollClipboard", "CWnd [MFC], OnWindowPosChanged", "CWnd [MFC], OnWindowPosChanging", "CWnd [MFC], OnWinIniChange", "CWnd [MFC], OnWndMsg", "CWnd [MFC], OnXButtonDblClk", "CWnd [MFC], OnXButtonDown", "CWnd [MFC], OnXButtonUp", "CWnd [MFC], PostNcDestroy", "CWnd [MFC], ReflectChildNotify", "CWnd [MFC], ReflectLastMsg", "CWnd [MFC], ResizeDynamicLayout", "CWnd [MFC], WindowProc", "CWnd [MFC], m_hWnd"] -ms.assetid: 49a832ee-bc34-4126-88b3-bc1d9974f6c4 --- # `CWnd` Class @@ -711,9 +710,9 @@ Nonzero if successful; otherwise 0. This example shows how to use `Attach` and `Detach` to map to the MDI client window. [!code-cpp[NVC_MFCWindowing#67](../../mfc/reference/codesnippet/cpp/cwnd-class_2.h)] - +  [!code-cpp[NVC_MFCWindowing#68](../../mfc/reference/codesnippet/cpp/cwnd-class_3.cpp)] - +  [!code-cpp[NVC_MFCWindowing#69](../../mfc/reference/codesnippet/cpp/cwnd-class_4.cpp)] ## `CWnd::BeginModalState` @@ -2059,7 +2058,7 @@ The default tool tips provided for your windows by `EnableToolTips` do not have ### Example [!code-cpp[NVC_MFCWindowing#91](../../mfc/reference/codesnippet/cpp/cwnd-class_30.cpp)] - +  [!code-cpp[NVC_MFCWindowing#92](../../mfc/reference/codesnippet/cpp/cwnd-class_31.cpp)] ## `CWnd::EnableTrackingToolTips` @@ -4863,10 +4862,10 @@ The following shows the various system icons that can be used in a message box: |Icon|Macro| |-|-| -|![Stop or X icon.](../../mfc/reference/media/vc364f1.gif)|`MB_ICONHAND`, `MB_ICONSTOP`, and `MB_ICONERROR`| -|![Help or question mark icon.](../../mfc/reference/media/vc364f2.gif)|MB_ICONQUESTION| -|![Important or exclamation point icon.](../../mfc/reference/media/vc364f3.gif)|MB_ICONEXCLAMATION and MB_ICONWARNING| -|![Information or letter I icon.](../../mfc/reference/media/vc364f4.gif)|MB_ICONASTERISK and MB_ICONINFORMATION| +|![Stop or X icon, consisting of a red circle with a white x in the middle.](../../mfc/reference/media/vc364f1.gif)|`MB_ICONHAND`, `MB_ICONSTOP`, and `MB_ICONERROR`| +|![Help or question mark icon, consisting of a thought bubble icon with a question mark in it.](../../mfc/reference/media/vc364f2.gif)|MB_ICONQUESTION| +|![Important or exclamation point icon, consisting of a yellow triangle with a black exclamation point in it.](../../mfc/reference/media/vc364f3.gif)|MB_ICONEXCLAMATION and MB_ICONWARNING| +|![Information or letter I icon, consiting of a thought bubble with a lowercase letter i in it.](../../mfc/reference/media/vc364f4.gif)|MB_ICONASTERISK and MB_ICONINFORMATION| ### Example @@ -4900,7 +4899,7 @@ Nonzero if style was successfully modified; otherwise, 0. ### Remarks -Styles to be added or removed can be combined by using the bitwise OR (|) operator. See the topics [Window Styles](/windows/win32/winmsg/window-styles) and [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for information about the available window styles. +Styles to be added or removed can be combined by using the bitwise OR (**`|`**) operator. See the topics [Window Styles](/windows/win32/winmsg/window-styles) and [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for information about the available window styles. If *`nFlags`* is nonzero, `ModifyStyle` calls the Windows API function [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) and redraws the window by combining *`nFlags`* with the following four preset flags: @@ -4949,7 +4948,7 @@ Nonzero if style was successfully modified; otherwise, 0. ### Remarks -Styles to be added or removed can be combined by using the bitwise `OR` (|) operator. See the topics [Extended Window Styles](../../mfc/reference/styles-used-by-mfc.md#extended-window-styles) in this book and [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK for information about the available extended styles +Styles to be added or removed can be combined by using the bitwise-OR (**`|`**) operator. See the topics [Extended Window Styles](../../mfc/reference/styles-used-by-mfc.md#extended-window-styles) in this book and [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK for information about the available extended styles If *`nFlags`* is nonzero, `ModifyStyleEx` calls the Windows API function [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) and redraws the window by combining *`nFlags`* with the following four preset flags: @@ -9091,7 +9090,7 @@ A pointer to a [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) - *`uId`* = `(UINT)hWndChild` Handle to a child window -- *`uFlags`* |= `TTF_IDISHWND` Handle of the tool +- *`uFlags`* |= `TTF_IDISHWND` Handle of the tool - *`lpszText`* = `LPSTR_TEXTCALLBACK` Pointer to the string that is to be displayed in the specified window diff --git a/docs/mfc/reference/dao-database-engine-initialization-and-termination.md b/docs/mfc/reference/dao-database-engine-initialization-and-termination.md index ab7e957bd3..67e0826e34 100644 --- a/docs/mfc/reference/dao-database-engine-initialization-and-termination.md +++ b/docs/mfc/reference/dao-database-engine-initialization-and-termination.md @@ -21,7 +21,6 @@ DAO is used with Access databases and is supported through Office 2013. DAO 3.6 This function initializes the DAO database engine. ``` - void AfxDaoInit(); throw(CDaoException*); @@ -42,7 +41,6 @@ For related information, and for an example of calling `AfxDaoInit`, see [Techni This function terminates the DAO database engine. ``` - void AfxDaoTerm(); ``` diff --git a/docs/mfc/reference/diagnostic-services.md b/docs/mfc/reference/diagnostic-services.md index 7824b52f10..18c273ec9e 100644 --- a/docs/mfc/reference/diagnostic-services.md +++ b/docs/mfc/reference/diagnostic-services.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Diagnostic Services" title: "Diagnostic Services" -ms.date: "11/04/2016" +description: "Learn more about: Diagnostic Services" +ms.date: 06/29/2022 helpviewer_keywords: ["diagnosi [MFC]s, diagnostic services", "diagnostic macros [MFC], list of general MFC", "services [MFC], diagnostic", "MFC, diagnostic services", "general diagnostic functions and variables [MFC]", "diagnostics [MFC], diagnostic functions and variables", "diagnostics [MFC], list of general MFC", "diagnosis [MFC], diagnostic functions and variables", "diagnosis [MFC], list of general MFC", "general diagnostic macros in MFC", "diagnostic macros [MFC]", "diagnostic services [MFC]", "object diagnostic functions in MFC", "diagnostics [MFC], diagnostic services", "diagnostic functions and variables [MFC]"] -ms.assetid: 8d78454f-9fae-49c2-88c9-d3fabd5393e8 --- # Diagnostic Services @@ -77,20 +76,20 @@ Suppresses compiler warnings for the use of deprecated MFC functions. ### Syntax -``` +```cpp _AFX_SECURE_NO_WARNINGS ``` ### Example -This code sample would cause a compiler warning if _AFX_SECURE_NO_WARNINGS were not defined. +This code sample causes a compiler warning if `_AFX_SECURE_NO_WARNINGS` isn't defined. ```cpp // define this before including any afx files in *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier) #define _AFX_SECURE_NO_WARNINGS -``` -```cpp +// . . . + CRichEditCtrl* pRichEdit = new CRichEditCtrl; pRichEdit->Create(WS_CHILD|WS_VISIBLE|WS_BORDER|ES_MULTILINE, CRect(10,10,100,200), pParentWnd, 1); @@ -105,7 +104,7 @@ Call this function to cause a break (at the location of the call to `AfxDebugBre ### Syntax ```cpp -void AfxDebugBreak( ); +void AfxDebugBreak(); ``` ### Remarks @@ -120,13 +119,13 @@ void AfxDebugBreak( ); Evaluates its argument. -``` +```cpp ASSERT(booleanExpression) ``` ### Parameters -*booleanExpression*
+*booleanExpression*\ Specifies an expression (including pointer values) that evaluates to nonzero or 0. ### Remarks @@ -156,16 +155,16 @@ In the Release version of MFC, ASSERT does not evaluate the expression and thus This macro asserts that the object pointed to is an object of the specified class, or is an object of a class derived from the specified class. -``` +```cpp ASSERT_KINDOF(classname, pobject) ``` ### Parameters -*classname*
+*classname*\ The name of a `CObject`-derived class. -*pobject*
+*pobject*\ A pointer to a class object. ### Remarks @@ -178,7 +177,7 @@ Using the `ASSERT_KINDOF` macro is exactly the same as coding: [!code-cpp[NVC_MFCDocView#195](../../mfc/codesnippet/cpp/diagnostic-services_4.cpp)] -This function works only for classes declared with the [DECLARE_DYNAMIC](run-time-object-model-services.md#declare_dynamic or [DECLARE_SERIAL](run-time-object-model-services.md#declare_serial) macro. +This function works only for classes declared with the [DECLARE_DYNAMIC](run-time-object-model-services.md#declare_dynamic) or [DECLARE_SERIAL](run-time-object-model-services.md#declare_serial) macro. > [!NOTE] > This function is available only in the Debug version of MFC. @@ -191,13 +190,13 @@ This function works only for classes declared with the [DECLARE_DYNAMIC](run-tim Use to test your assumptions about the validity of an object's internal state. -``` +```cpp ASSERT_VALID(pObject) ``` ### Parameters -*pObject*
+*pObject*\ Specifies an object of a class derived from `CObject` that has an overriding version of the `AssertValid` member function. ### Remarks @@ -223,8 +222,8 @@ For more information and examples, see [Debugging MFC Applications](/visualstudi Assists in finding memory leaks. -``` -#define new DEBUG_NEW +```cpp +#define new DEBUG_NEW ``` ### Remarks @@ -250,7 +249,7 @@ Once you insert this directive, the preprocessor will insert DEBUG_NEW wherever In debug mode (when the **_DEBUG** symbol is defined), DEBUG_ONLY evaluates its argument. -``` +```cpp DEBUG_ONLY(expression) ``` @@ -274,14 +273,14 @@ Use to validate data correctness. ### Syntax -``` -ENSURE( booleanExpression ) -ENSURE_VALID( booleanExpression ) +```cpp +ENSURE(booleanExpression) +ENSURE_VALID(booleanExpression) ``` ### Parameters -*booleanExpression*
+*booleanExpression*\ Specifies a boolean expression to be tested. ### Remarks @@ -306,7 +305,7 @@ Expands to the name of the file that is being compiled. ### Syntax -``` +```cpp THIS_FILE ``` @@ -334,9 +333,9 @@ static char THIS_FILE[] = __FILE__; Sends the specified string to the debugger of the current application. -``` +```cpp TRACE(exp) -TRACE(DWORD category, UINT level, LPCSTR lpszFormat, ...) +TRACE(DWORD category, UINT level, LPCSTR lpszFormat, ...) ``` ### Remarks @@ -355,13 +354,13 @@ For more information, see [Debugging MFC Applications](/visualstudio/debugger/mf In the Debug version of MFC, evaluates its argument. -``` +```cpp VERIFY(booleanExpression) ``` ### Parameters -*booleanExpression*
+*booleanExpression*\ Specifies an expression (including pointer values) that evaluates to nonzero or 0. ### Remarks @@ -388,8 +387,8 @@ In the Release version of MFC, VERIFY evaluates the expression but does not prin Provides basic object-dumping capability in your application. -``` -CDumpContext afxDump; +```cpp +CDumpContext afxDump; ``` ### Remarks @@ -420,7 +419,7 @@ void AfxDump(const CObject* pOb); ### Parameters -*pOb*
+*pOb*\ A pointer to an object of a class derived from `CObject`. ### Remarks @@ -437,8 +436,8 @@ Your program code should not call `AfxDump`, but should instead call the `Dump` This variable is accessible from a debugger or your program and allows you to tune allocation diagnostics. -``` -int afxMemDF; +```cpp +int afxMemDF; ``` ### Remarks @@ -490,8 +489,8 @@ This function can be used to check the return values of calls to OLE functions i This function validates the free memory pool and prints error messages as required. -``` -BOOL AfxCheckMemory(); +```cpp +BOOL AfxCheckMemory(); ``` ### Return Value @@ -533,7 +532,7 @@ void AfxDump(const CObject* pOb); ### Parameters -*pOb*
+*pOb*\ A pointer to an object of a class derived from `CObject`. ### Remarks @@ -556,8 +555,8 @@ void AFXAPI AfxDumpStack(DWORD dwTarget = AFX_STACK_DUMP_TARGET_DEFAULT); ### Parameters -*dwTarget*
-Indicates the target of the dump output. Possible values, which can be combined using the bitwise-OR ( **|**) operator, are as follows: +*dwTarget*\ +Indicates the target of the dump output. Possible values, which can be combined using the bitwise-OR (**`|`**) operator, are as follows: - AFX_STACK_DUMP_TARGET_TRACE Sends output by means of the [TRACE](#trace) macro. The TRACE macro generates output in debug builds only; it generates no output in release builds. Also, TRACE can be redirected to other targets besides the debugger. @@ -626,13 +625,13 @@ To use this function successfully: Enables and disables the memory leak dump in the AFX_DEBUG_STATE destructor. -``` +```cpp BOOL AFXAPI AfxEnableMemoryLeakDump(BOOL bDump); ``` ### Parameters -*bDump*
+*bDump*\ [in] TRUE indicates the memory leak dump is enabled; FALSE indicates the memory leak dump is disabled. ### Return Value @@ -656,13 +655,13 @@ If your application loads another library before the MFC library, some memory al Diagnostic memory tracking is normally enabled in the Debug version of MFC. -``` +```cpp BOOL AfxEnableMemoryTracking(BOOL bTrack); ``` ### Parameters -*bTrack*
+*bTrack*\ Setting this value to TRUE turns on memory tracking; FALSE turns it off. ### Return Value @@ -690,7 +689,7 @@ For more information on `AfxEnableMemoryTracking`, see [Debugging MFC Applicatio Tests a memory address to make sure it represents a currently active memory block that was allocated by the diagnostic version of **`new`**. -``` +```cpp BOOL AfxIsMemoryBlock( const void* p, UINT nBytes, @@ -699,13 +698,13 @@ BOOL AfxIsMemoryBlock( ### Parameters -*p*
+*p*\ Points to the block of memory to be tested. -*nBytes*
+*nBytes*\ Contains the length of the memory block in bytes. -*plRequestNumber*
+*plRequestNumber*\ Points to a **`long`** integer that will be filled in with the memory block's allocation sequence number, or zero if it does not represent a currently active memory block. ### Return Value @@ -728,7 +727,7 @@ It also checks the specified size against the original allocated size. If the fu Tests any memory address to ensure that it is contained entirely within the program's memory space. -``` +```cpp BOOL AfxIsValidAddress( const void* lp, UINT nBytes, @@ -737,13 +736,13 @@ BOOL AfxIsValidAddress( ### Parameters -*lp*
+*lp*\ Points to the memory address to be tested. -*nBytes*
+*nBytes*\ Contains the number of bytes of memory to be tested. -*bReadWrite*
+*bReadWrite*\ Specifies whether the memory is both for reading and writing (TRUE) or just reading (FALSE). ### Return Value @@ -768,18 +767,18 @@ The address is not restricted to blocks allocated by **`new`**. Use this function to determine whether a pointer to a string is valid. -``` -BOOL AfxIsValidString( +```cpp +BOOL AfxIsValidString( LPCSTR lpsz, int nLength = -1); ``` ### Parameters -*lpsz*
+*lpsz*\ The pointer to test. -*nLength*
+*nLength*\ Specifies the length of the string to be tested, in bytes. A value of -1 indicates that the string will be null-terminated. ### Return Value @@ -800,13 +799,13 @@ In non-debug builds, nonzero if *lpsz* is not NULL; otherwise 0. Sets a hook that enables calling of the specified function before each memory block is allocated. -``` +```cpp AFX_ALLOC_HOOK AfxSetAllocHook(AFX_ALLOC_HOOK pfnAllocHook); ``` ### Parameters -*pfnAllocHook*
+*pfnAllocHook*\ Specifies the name of the function to call. See the Remarks for the prototype of an allocation function. ### Return Value @@ -819,13 +818,13 @@ The Microsoft Foundation Class Library debug-memory allocator can call a user-de **BOOL AFXAPI AllocHook( size_t** `nSize`**, BOOL** `bObject`**, LONG** `lRequestNumber` **);** -*nSize*
+*nSize*\ The size of the proposed memory allocation. -*bObject*
+*bObject*\ TRUE if the allocation is for a `CObject`-derived object; otherwise FALSE. -*lRequestNumber*
+*lRequestNumber*\ The memory allocation's sequence number. Note that the AFXAPI calling convention implies that the callee must remove the parameters from the stack. @@ -847,10 +846,10 @@ AFXAPI AfxDoForAllClasses( ### Parameters -*pfn*
+*pfn*\ Points to an iteration function to be called for each class. The function arguments are a pointer to a `CRuntimeClass` object and a void pointer to extra data that the caller supplies to the function. -*pContext*
+*pContext*\ Points to optional data that the caller can supply to the iteration function. This pointer can be NULL. ### Remarks @@ -863,7 +862,7 @@ Serializable `CObject`-derived classes are classes derived using the DECLARE_SER ### Example [!code-cpp[NVC_MFCCollections#113](../../mfc/codesnippet/cpp/diagnostic-services_16.cpp)] - +  [!code-cpp[NVC_MFCCollections#114](../../mfc/codesnippet/cpp/diagnostic-services_17.cpp)] ### Requirements @@ -882,10 +881,10 @@ void AfxDoForAllObjects( ### Parameters -*pfn*
+*pfn*\ Points to an iteration function to execute for each object. The function arguments are a pointer to a `CObject` and a void pointer to extra data that the caller supplies to the function. -*pContext*
+*pContext*\ Points to optional data that the caller can supply to the iteration function. This pointer can be NULL. ### Remarks @@ -898,10 +897,10 @@ Stack, global, or embedded objects are not enumerated. The pointer passed to `Af ### Example [!code-cpp[NVC_MFCCollections#115](../../mfc/codesnippet/cpp/diagnostic-services_18.cpp)] - +  [!code-cpp[NVC_MFCCollections#116](../../mfc/codesnippet/cpp/diagnostic-services_19.cpp)] ## See also -[Macros and Globals](mfc-macros-and-globals.md)
+[Macros and Globals](mfc-macros-and-globals.md)\ [CObject::Dump](cobject-class.md#dump) diff --git a/docs/mfc/reference/dialog-data-exchange-functions-for-ole-controls.md b/docs/mfc/reference/dialog-data-exchange-functions-for-ole-controls.md index 37cc40288a..7df654e281 100644 --- a/docs/mfc/reference/dialog-data-exchange-functions-for-ole-controls.md +++ b/docs/mfc/reference/dialog-data-exchange-functions-for-ole-controls.md @@ -245,7 +245,7 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ## DDX_OCInt -The `DDX_OCInt` function manages the transfer of **`int`** (or **`long`**) data between a property of an OLE control in a dialog box, form view, or control view object and a **`int`** (or **`long`**) data member of the dialog box, form view, or control view object. +The `DDX_OCInt` function manages the transfer of **`int`** (or **`long`**) data between a property of an OLE control in a dialog box, form view, or control view object and an **`int`** (or **`long`**) data member of the dialog box, form view, or control view object. ```cpp void AFXAPI DDX_OCInt( diff --git a/docs/mfc/reference/event-sink-maps.md b/docs/mfc/reference/event-sink-maps.md index e8d550c045..e1475a88c7 100644 --- a/docs/mfc/reference/event-sink-maps.md +++ b/docs/mfc/reference/event-sink-maps.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Event Sink Maps" title: "Event Sink Maps" -ms.date: "11/04/2016" +description: "Learn more about: Event Sink Maps" +ms.date: 11/04/2016 helpviewer_keywords: ["event sink maps [MFC]"] -ms.assetid: a9757eb2-5f4a-45ec-a2cd-ce5eec85b16f --- # Event Sink Maps @@ -158,7 +157,7 @@ For a list of the **VTS_** constants, see [EVENT_CUSTOM](event-maps.md#event_cus ### Example -The following example demonstrates an event handler, for the MouseDown event, implemented for three controls ( IDC_MYCTRL1 through IDC_MYCTRL3). The event handler function, `OnRangeMouseDown`, is declared in the header file of the dialog class ( `CMyDlg`) as: +The following example demonstrates an event handler, for the MouseDown event, implemented for three controls ( IDC_MYCTRL1 through IDC_MYCTRL3). The event handler function, `OnRangeMouseDown`, is declared in the header file of the dialog class (`CMyDlg`) as: [!code-cpp[NVC_MFCAutomation#12](../../mfc/codesnippet/cpp/event-sink-maps_2.h)] @@ -248,7 +247,6 @@ For a list of the **VTS_** constants, see [EVENT_CUSTOM](event-maps.md#event_cus Use the ON_PROPNOTIFY_RANGE macro to define an event sink map entry for handling property notifications from any OLE control having a control ID within a contiguous range of IDs. ``` - ON_PROPNOTIFY_RANGE(theClass, idFirst, idLast, dispid, pfnRequest, pfnChanged) ``` @@ -281,7 +279,6 @@ Pointer to a member function that handles the `OnChanged` notification for this The ON_PROPNOTIFY_REFLECT macro, when used in the event sink map of an OLE control's wrapper class, receives property notifications sent by the control before they are handled by the control's container. ``` - ON_PROPNOTIFY_REFLECT(theClass, dispid, pfnRequest, pfnChanged) ``` diff --git a/docs/mfc/reference/extension-dll-macros.md b/docs/mfc/reference/extension-dll-macros.md index f7dc3c4d10..a3682634f7 100644 --- a/docs/mfc/reference/extension-dll-macros.md +++ b/docs/mfc/reference/extension-dll-macros.md @@ -79,7 +79,7 @@ For more information on module states and MFC, see [Managing the state data of M **Header:** \ -## `AfxOleInitModule` +## `AfxOleInitModule` For OLE support from a regular MFC DLL that is dynamically linked to MFC, call this function in your regular MFC DLL's `CWinApp::InitInstance` function to initialize the MFC OLE DLL. @@ -329,6 +329,6 @@ MFC extension DLLs need to call [`AfxInitExtensionModule`](#afxinitextensionmodu ## See also -[Macros and globals](mfc-macros-and-globals.md)
-[`AfxMessageBox`](cstring-formatting-and-message-box-display.md#afxmessagebox)
-[Managing the state data of MFC modules](../managing-the-state-data-of-mfc-modules.md)
+[Macros and globals](mfc-macros-and-globals.md)\ +[`AfxMessageBox`](cstring-formatting-and-message-box-display.md#afxmessagebox)\ +[Managing the state data of MFC modules](../managing-the-state-data-of-mfc-modules.md) diff --git a/docs/mfc/reference/internal-classes.md b/docs/mfc/reference/internal-classes.md index 09c3177594..09282b431f 100644 --- a/docs/mfc/reference/internal-classes.md +++ b/docs/mfc/reference/internal-classes.md @@ -4,11 +4,10 @@ title: "Internal Classes" ms.date: "11/04/2016" f1_keywords: ["CPreviewViewEx", "m_bPreMultiplyCheck", "CMFCRibbonPanelMenuBar.IsCategoryPopup", "CMFCCustomizeMenuButton.SetSiblingsButton"] helpviewer_keywords: ["UpdateTabs method [MFC]", "Start method [MFC]", "IsLast method [MFC]", "EnableAutoHidePanes method [MFC]", "CMFCOutlookBarScrollButton class [MFC]", "CMFCToolBarsListPropertyPage, constructor", "SetExtraSize method [MFC]", "FindNextRegisteredWithTaskbarMDIChild", "CMFCRibbonCommandsListBox, constructor", "EnableMenuItemImage method [MFC]", "OnInitDialog method [MFC]", "RecalcLayout method [MFC]", "OnGetItemSize method [MFC]", "ParseToolBarImages method [MFC]", "CreateFromMenu method [MFC]", "CMFCOutlookBarToolBar, constructor", "CSmartDockingGroupGuidesManager class [MFC]", "OnSetCursor method [MFC]", "CMFCToolBarDropSource class [MFC]", "CTagManager class [MFC]", "OnChangeParentWnd method [MFC]", "UpdateButtons method [MFC]", "CFullScreenImpl class [MFC], destructor", "FillInterior method [MFC]", "AddPaneContainer method [MFC]", "CDocumentAdapter, constructor", "EnableBrowseButton method [MFC]", "CMFCControlRendererInfo class [MFC], constructor", "FillFromCategory method [MFC]", "CRecentPaneContainerInfo class [MFC]", "ReadRect method [MFC]", "ClearUserCmdImages method [MFC]", "CMFCToolBarsOptionsPropertyPage, constructor", "CMFCMousePropertyPage class [MFC]", "SetActive method [MFC]", "RemoveMenu method [MFC]", "OnOK method [MFC]", "IsMenuBarAvailable method [MFC]", "CMFCRibbonCommandsListBox class [MFC]", "InsertPane method [MFC]", "SetPressed method [MFC]", "Destroy method [MFC]", "SetACCData method [MFC]", "GetOwner method [MFC]", "SetFullScreenID method [MFC]", "CFrameImpl class [MFC], constructor", "SetDockingWnd method [MFC]", "CauseCancelMode method [MFC]", "OnDropEx method [MFC]", "CMFCPropertySheetCategoryInfo class [MFC]", "GetExtraSize method [MFC]", "CMFCRibbonKeyTip class [MFC]", "ClearChunkList [MFC]", "CMFCToolBarsListPropertyPage class [MFC]", "CVSToolsListBox class [MFC]", "SetMaxHeight method [MFC]", "OnDrawMenuLogo method [MFC]", "CacheY method [MFC]", "~CDocumentAdapter, destructor", "GetImageSize method [MFC]", "EnableTabsArea method [MFC]", "CMFCToolBarMenuButtonsButton class [MFC]", "CFullScreenImpl class [MFC]", "COleCntrFrameWndEx, constructor", "EditItem method [MFC]", "cxIcon [MFC]", "OnMouseMove method [MFC]", "~CMFCControlRenderer destructor", "GetButtonID method [MFC]", "CPaneContainerGC class [MFC]", "CMFCControlRendererInfo class [MFC], destructor", "nFrameCount", "m_clrTransparent", "SetAllCategory method [MFC]", "CMFCToolBarsKeyboardPropertyPage class [MFC]", "GetScrollBarCtrl method [MFC]", "InitializeSearchContent", "ParseColor method [MFC]", "ShowFullScreen method [MFC]", "IsFirstInRow method [MFC]", "GetText method [MFC]", "EnableCheck method [MFC]", "SetNewUserToolBarRTC method [MFC]", "OnDragEnter method [MFC]", "OnChooseItem method [MFC]", "OnClosePopupMenu method [MFC]", "CMFCCaptionButtonEx class [MFC]", "IsMenuItemWithoutImage method [MFC]", "CFullScreenImpl class [MFC], constructor", "CMFCTabButton class [MFC]", "CMFCToolBarsCommandsPropertyPage class [MFC]", "CMFCToolBarsOptionsPropertyPage class [MFC]", "CMFCRibbonGalleryIcon, constructor", "OnKillActive method [MFC]", "Register method [MFC]", "CanBeDropped method [MFC]", "CopyFrom method [MFC]", "CSmartDockingManager class [MFC]", "SelectButton method [MFC]", "CMFCToolBarMenuButtonsButton, constructor", "BeginReadChunks", "CSmartDockingGroupGuidesWnd class [MFC]", "EnableMainMenu method [MFC]", "Create method [MFC]", "m_pParentDoc data member", "IsCategoryPopup method [MFC]", "OnDblClk method [MFC]", "ReadToolTipInfo method [MFC]", "OnCustomizeMode method [MFC]", "IsLeftScroll method [MFC]", "OnChangeVisualManager method [MFC]", "OnClick method [MFC]", "EnableScaleLargeImages method [MFC]", "SetParentToolbar method [MFC]", "CMFCRibbonPanelMenu class [MFC]", "SetDockState method [MFC]", "Cache method [MFC]", "SetRadio method [MFC]", "CMFCStatusBarPaneInfo class [MFC]", "IsDefaultDraw method [MFC]", "CMFCRibbonCmdUI class [MFC]", "CMFCToolBarEditCtrl class [MFC]", "OnSetPreviewMode method [MFC]", "nID", "EnableCustomizeMenu method [MFC]", "IsEmptyMenuAllowed method [MFC]", "m_rectCorners", "ExcludeTag method [MFC]", "CMFCCustomizeMenuButton, constructor", "AdjustDockingLayout method [MFC]", "GetToolTipText method [MFC]", "ReadBool method [MFC]", "GetButtonNum method [MFC]", "SetUserImages method [MFC]", "GetContainer", "COleCntrFrameWndEx class [MFC]", "Assign method [MFC]", "CMFCCaptionButtonEx, constructor", "LoadFromResource method [MFC]", "GetFullScreenRect method [MFC]", "OnPaint method [MFC]", "GetTopLevelRibbonBar method [MFC]", "CMFCRibbonPanelMenu, constructor", "AddItem method [MFC]", "CMFCToolBarSystemMenuButton, constructor", "CMFCDropDownListBox, constructor", "IsQATPopup method [MFC]", "ParseControlRendererInfo method [MFC]", "nProgressTotal", "SetMenuMode method [MFC]", "GetHighlightedGuideNo method [MFC]", "m_rectImage", "lpszToolTip", "RemoveChunk", "GetElement method [MFC]", "clrProgressBarDest", "operator= method [MFC]", "ParseString method [MFC]", "GetItemData method [MFC]", "CMFCProperySheetListBox class [MFC]", "ShowToolBar method [MFC]", "SetCurSel method [MFC]", "CMFCRibbonKeyboardCustomizeDialog, constructor", "EnableCustomization method [MFC]", "GetSysMenu method [MFC]", "ShowPlaceAt method [MFC]", "AdjustPos method [MFC]", "Show method [MFC]", "GetDC method [MFC]", "ShowMenu method [MFC]", "GetItemText method [MFC]", "GetCommandIndex method [MFC]", "IsGrayDisabledButtons method [MFC]", "OnCmdMsg method [MFC]", "CMemDC class [MFC], constructor", "LoadFrame method [MFC]", "OnPosChange method [MFC]", "COleServerDocEx class [MFC]", "IsFirstInColumn method [MFC]", "ReadControlRendererInfo method [MFC]", "IsAlwaysClose method [MFC]", "Mirror method [MFC]", "~CFullScreenImpl destructor", "OnShowPopupMenu method [MFC]", "GetBuffer method [MFC]", "SetRect method [MFC]", "OnSendCommand method [MFC]", "GetCommand method [MFC]", "CMFCToolBarSpinEditBoxButton, constructor", "OnBrowse method [MFC]", "SetTaskPaneCaptionButtons method [MFC]", "SetSeparator method [MFC]", "CMFCToolBarsCommandsListBox class [MFC]", "SetImages method [MFC]", "GetFullScreenMinMaxInfo method [MFC]", "OnCloseDockingPane method [MFC]", "CMFCRibbonPanelMenuBar, constructor", "FillAll method [MFC]", "IsRibbonMiniToolBar method [MFC]", "clrProgressBar", "OnAfterRenameItem method [MFC]", "CMFCPropertySheetCategoryInfo, constructor", "SmoothResize", "ResetContent method [MFC]", "CPngImage class [MFC]", "OnCalculateSize method [MFC]", "OnDragOver method [MFC]", "LockSize method [MFC]", "SetTaskbarTabOrder", "IsEditable method [MFC]", "GetResId method [MFC]", "SetItemData method [MFC]", "GetActivePopup method [MFC]", "GetCategory method [MFC]", "lpszText", "SetControlbarsMenuId method [MFC]", "Track method [MFC]", "IsEditFocused method [MFC]", "CMFCRibbonRichEditCtrl class [MFC]", "CMFCToolBarsMenuPropertyPage class [MFC]", "bProgressText", "OnDrawMenuImage method [MFC]", "IsFirst method [MFC]", "CMFCToolBarsListCheckBox class [MFC]", "RestoreRecentlyUsedState method [MFC]", "GetContainerFrameWindow method [MFC]", "Size method [MFC]", "MeasureItem method [MFC]", "OnToolHitTest method [MFC]", "IsVistaDC method [MFC]", "SetPipeStyle method [MFC]", "OnDraw method [MFC]", "OnAfterMoveItemUp method [MFC]", "OnEndEditLabel method [MFC]", "ShowTabbedAt method [MFC]", "CloseDelayedSubMenu method [MFC]", "CalcBorderSize method [MFC]", "OnUserToolTip method [MFC]", "LoadFromStream", "rect", "GetButtonsCount method [MFC]", "AdjustLocations method [MFC]", "GetTearOffBars method [MFC]", "GetDefaultResId method [MFC]", "SetVisible method [MFC]", "Clear method [MFC]", "CMFCControlRenderer class [MFC]", "CMFCToolBarSpinEditBoxButton class [MFC]", "DrawItem method [MFC]", "IsMDIChildButton method [MFC]", "clrText", "SetGrayDisabledButtons method [MFC]", "RestoreState method [MFC]", "IsMainPanel method [MFC]", "EnableDragFromList method [MFC]", "m_strBmpResID", "IsPipeStyle method [MFC]", "m_rectSides", "SaveMenuBar method [MFC]", "GiveFeedback method [MFC]", "m_bPreMultiplyCheck", "GetParentRibbonMenuBar method [MFC]", "IsButtonExtraSizeAvailable method [MFC]", "AddDockSite method [MFC]", "CMFCRibbonQuickAccessToolBar class [MFC]", "CSmartDockingStandaloneGuide class [MFC]", "IsMirror method [MFC]", "SetDefaultDraw method [MFC]", "CMFCTasksPanePropertyPage class [MFC]", "RestoreDelayedSubMenu method [MFC]", "CloseContextMenu method [MFC]", "cxText", "OnClickButton method [MFC]", "AdjustClientArea method [MFC]", "GetMDITabs method [MFC]", "CPreviewViewEx class [MFC]", "OnGetImage method [MFC]", "IsPointNearDockSite method [MFC]", "ShowTabbedPlaceAt method [MFC]", "GetResourceID method [MFC]", "SetMenuRightAlign method [MFC]", "CMFCToolBarNameDialog class [MFC]", "CVSListBoxEditCtrl class [MFC]", "nCurrFrame", "EnableButton method [MFC]", "CTagManager class [MFC], destructor", "FindChunk", "operator =", "OnAfterCreatePopupMenu method [MFC]", "SetupToolbarMenu method [MFC]", "CMFCCustomizeMenuButton class [MFC]", "CDocumentAdapter class [MFC]", "CMFCControlRendererInfo class [MFC]", "AddString method [MFC]", "CMFCColorPropertySheet, constructor", "CMFCControlRenderer class [MFC], constructor", "CMemDC class [MFC], destructor", "CMenuImages class [MFC]", "CleanUp method [MFC]"] -ms.assetid: 3e2276aa-b02a-4781-97ba-ea074045e9e2 --- # Internal Classes -The following classes are used internally in MFC. For completeness, this section describes these internal classes, but they are not intended to be used directly in your code. +The following classes are used internally in MFC. For completeness, this section describes these internal classes, but they aren't intended to be used directly in your code. ## In This Section @@ -17,7 +16,7 @@ The following classes are used internally in MFC. For completeness, this section |`CCommandManager Class`|The `CCommandManager` class manages commands and their association with images.| |`CDialogImpl Class (MFC)`|Provides implementation details to dialog box-based classes, such as `CDialogEx`.| |`CDocumentAdapter Class`|Implements IDocument interface required for Search and Organize handlers.| -|`CFrameImpl Class`|The `CFrameImpl` class handles toolbar customization for the following frame window classes: [CFrameWndEx Class](../../mfc/reference/cframewndex-class.md), [CMDIFrameWndEx Class](../../mfc/reference/cmdiframewndex-class.md), and [COleIPFrameWndEx Class](../../mfc/reference/coleipframewndex-class.md).| +|`CFrameImpl Class`|The `CFrameImpl` class handles toolbar customization for the following frame window classes: [`CFrameWndEx` Class](../../mfc/reference/cframewndex-class.md), [`CMDIFrameWndEx` Class](../../mfc/reference/cmdiframewndex-class.md), and [`COleIPFrameWndEx` Class](../../mfc/reference/coleipframewndex-class.md).| |`CFullScreenImpl Class`|Implements full-screen functionality common to SDI and MDI applications.| |`CMDIClientAreaWnd Class`|The `CMDIClientAreaWnd` class is a helper class that simplifies implementation of MDI tabs and MDI tabbed groups.| |`CMemDC Class`|A helper class for a memory device context. The memory device context supports offscreen drawing.| @@ -25,7 +24,7 @@ The following classes are used internally in MFC. For completeness, this section |`CMenuImages Class`|Provides the functionality to display predefined images such as close buttons, maximize buttons, radio buttons, and arrows.| |`CMFCCaptionButtonEx Class`|Holds the non-client area of system caption buttons.| |`CMFCCaptionMenuButton Class`|Represents a menu button that is located in the caption area of a task pane or toolbar.| -|`CMFCColorPropertySheet Class`|Used by [CMFCColorDialog Class](../../mfc/reference/cmfccolordialog-class.md) to provide a tabbed dialog box.| +|`CMFCColorPropertySheet Class`|Used by [`CMFCColorDialog` Class](../../mfc/reference/cmfccolordialog-class.md) to provide a tabbed dialog box.| |`CMFCControlBarImpl Class`|Provides implementation details to control bar-based classes, such as `CMFCReBar` and `CMFCToolBar`.| |`CMFCControlRenderer Class`|A helper class that handles image rendering.| |`CMFCControlRendererInfo Class`|A helper class for passing parameters to `CMFCControlRenderer` class.| diff --git a/docs/mfc/reference/media/add-class-from-typelib-wizard.png b/docs/mfc/reference/media/add-class-from-typelib-wizard.png new file mode 100644 index 0000000000..e7386d9e8c Binary files /dev/null and b/docs/mfc/reference/media/add-class-from-typelib-wizard.png differ diff --git a/docs/mfc/reference/media/add-idl-mfc-method-wizard.png b/docs/mfc/reference/media/add-idl-mfc-method-wizard.png new file mode 100644 index 0000000000..f2604b4758 Binary files /dev/null and b/docs/mfc/reference/media/add-idl-mfc-method-wizard.png differ diff --git a/docs/mfc/reference/media/add-interface-definition-library-mfc-property-wizard.png b/docs/mfc/reference/media/add-interface-definition-library-mfc-property-wizard.png new file mode 100644 index 0000000000..3f20202da3 Binary files /dev/null and b/docs/mfc/reference/media/add-interface-definition-library-mfc-property-wizard.png differ diff --git a/docs/mfc/reference/media/mfc-app-wizard.png b/docs/mfc/reference/media/mfc-app-wizard.png index df57384024..2068071223 100644 Binary files a/docs/mfc/reference/media/mfc-app-wizard.png and b/docs/mfc/reference/media/mfc-app-wizard.png differ diff --git a/docs/mfc/reference/media/windows-desktop-wizard-2017.png b/docs/mfc/reference/media/windows-desktop-wizard-2017.png deleted file mode 100644 index 07a43109d6..0000000000 Binary files a/docs/mfc/reference/media/windows-desktop-wizard-2017.png and /dev/null differ diff --git a/docs/mfc/reference/media/windows-desktop-wizard.png b/docs/mfc/reference/media/windows-desktop-wizard.png index 21fae3a3a4..832196599d 100644 Binary files a/docs/mfc/reference/media/windows-desktop-wizard.png and b/docs/mfc/reference/media/windows-desktop-wizard.png differ diff --git a/docs/mfc/reference/mfc-activex-control-wizard.md b/docs/mfc/reference/mfc-activex-control-wizard.md index cb90373e87..e949d307fa 100644 --- a/docs/mfc/reference/mfc-activex-control-wizard.md +++ b/docs/mfc/reference/mfc-activex-control-wizard.md @@ -1,14 +1,15 @@ --- description: "Learn more about: MFC ActiveX Control Wizard" title: "MFC ActiveX Control Wizard" -ms.date: "09/12/2018" +ms.date: "03/04/2022" f1_keywords: ["vc.appwiz.mfc.ctl.overview"] helpviewer_keywords: ["ActiveX controls [MFC], MFC", "MFC ActiveX controls [MFC], wizards", "OLE controls [MFC], creating", "MFC ActiveX Control Wizard", "OLE controls [MFC]"] ms.assetid: f19d698c-bdc3-4c74-af97-3d6ccb441b75 +ms.custom: devdivchpfy22 --- # MFC ActiveX Control Wizard -An ActiveX control is a specific type of [automation server](../../mfc/automation-servers.md); it is a reusable component. The application hosting the ActiveX control is the [automation client](../../mfc/automation-clients.md) of that control. If your goal is to create such a reusable component, then use this wizard to create your control. See [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md) for more information. +An ActiveX control is a specific type of [automation server](../../mfc/automation-servers.md); it's a reusable component. The application hosting the ActiveX control is the [automation client](../../mfc/automation-clients.md) of that control. If your goal is to create such a reusable component, then use this wizard to create your control. For more information, see [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md). >[!IMPORTANT] > ActiveX is a legacy technology that should not be used for new development. For more information about modern technologies that supersede ActiveX, see [ActiveX Controls](../activex-controls.md). @@ -17,7 +18,7 @@ Alternately, you can create an automation server MFC application using the [MFC An ActiveX control created with this wizard can have a user interface, or it can be invisible. You can indicate this option in the [Control Settings](../../mfc/reference/control-settings-mfc-activex-control-wizard.md) page in the wizard. A timer control is an example of an ActiveX control that you would want to be invisible. -ActiveX controls can have a complex user interface. Some controls might be like encapsulated forms: a single control containing many fields, each a Windows control in its own right. For example, an auto parts object implemented as an MFC ActiveX control might present a form-like user interface through which users could read and edit the part number, part name, and other information. See [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md) for more information. +ActiveX controls can have a complex user interface. Some controls might be like encapsulated forms: a single control containing many fields, each a Windows control in its own right. For example, a machine part object implemented as an MFC ActiveX control might present a form-like user interface. Users could use the UI to read and edit the part number, part name, and other information. For more information, see [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md). If you need to create a container for your ActiveX objects, see [Create an ActiveX Control Container](../../mfc/reference/creating-an-mfc-activex-control-container.md). @@ -43,13 +44,13 @@ The following sample list shows tasks and types of enhancements for your ActiveX ## Overview -This wizard page describes the current application settings for the MFC ActiveX control project you are creating. By default, the wizard creates a project as follows: +This wizard page describes the current application settings for the MFC ActiveX control project you're creating. By default, the wizard creates a project as follows: -- The default project generates no run-time license or help files. You can change these default settings on the [Application Settings](../../mfc/reference/application-settings-mfc-activex-control-wizard.md) page. Only the selections you make on this page of the ActiveX Control Wizard are reflected on the **Overview** page. +- The default project generates no run-time license or help files. You can change these default settings on the [Settings](../../mfc/reference/application-settings-mfc-activex-control-wizard.md) page. Only the selections you make on this page of the ActiveX Control Wizard are reflected on the **Overview** page. - The project includes a control class and a property page class, based on the name of the project. You can edit the names of your project and file names on the [Control Names](../../mfc/reference/control-names-mfc-activex-control-wizard.md) page. -- The control is based on no existing Windows control, activates when it becomes visible, has a user interface, and includes an **About** dialog box. You can change these default settings on the [Control Settings](../../mfc/reference/control-settings-mfc-activex-control-wizard.md) page. +- The control is based on no existing Windows control, activates when it becomes visible, has a user interface, and includes an **About** dialog box. You can change these default settings on the [Settings](../../mfc/reference/control-settings-mfc-activex-control-wizard.md) page. ## See also diff --git a/docs/mfc/reference/mfc-application-wizard.md b/docs/mfc/reference/mfc-application-wizard.md index 39317444e7..81d79ea6b6 100644 --- a/docs/mfc/reference/mfc-application-wizard.md +++ b/docs/mfc/reference/mfc-application-wizard.md @@ -4,7 +4,6 @@ title: "MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.overview"] helpviewer_keywords: ["MFC Application Wizard", "executable files, creating"] -ms.assetid: 227ac090-921d-4b2f-be0a-66a5f4cab0d4 --- # MFC Application Wizard @@ -15,7 +14,7 @@ The MFC Application Wizard generates an application that, when compiled, impleme ## Overview -This wizard page describes the current application settings for the MFC application that you are creating. By default, the wizard creates a project as follows: +This wizard page describes the current application settings for the MFC application that you're creating. By default, the wizard creates a project as follows: - [Application Type, MFC Application Wizard](../../mfc/reference/application-type-mfc-application-wizard.md) @@ -57,22 +56,22 @@ This wizard page describes the current application settings for the MFC applicat - [Generated Classes, MFC Application Wizard](../../mfc/reference/generated-classes-mfc-application-wizard.md) - - The project's view class is derived from the [CView Class](../../mfc/reference/cview-class.md). + - The project's view class is derived from the [`CView` Class](../../mfc/reference/cview-class.md). - - The project's application class is derived from the [CWinAppEx Class](../../mfc/reference/cwinappex-class.md). + - The project's application class is derived from the [`CWinAppEx` Class](../../mfc/reference/cwinappex-class.md). - - The project's document class is derived from the [CDocument Class](../../mfc/reference/cdocument-class.md). + - The project's document class is derived from the [`CDocument` Class](../../mfc/reference/cdocument-class.md). - - The project's main frame class is derived from the [CMDIFrameWndEx Class](../../mfc/reference/cmdiframewndex-class.md). + - The project's main frame class is derived from the [`CMDIFrameWndEx` Class](../../mfc/reference/cmdiframewndex-class.md). - - The project's child frame class is derived from the [CMDIChildWndEx Class](../../mfc/reference/cmdichildwndex-class.md). + - The project's child frame class is derived from the [`CMDIChildWndEx` Class](../../mfc/reference/cmdichildwndex-class.md). -To change these default settings, click the appropriate tab title in the left column of the wizard and make the changes on the page that appears. +To change these default settings, select the appropriate tab title in the left column of the wizard and make the changes on the page that appears. After you create an MFC application project, you can add objects or controls to your project using Visual C++ [code wizards](../../ide/adding-functionality-with-code-wizards-cpp.md). ## See also -[Creating an MFC Application](../../mfc/reference/creating-an-mfc-application.md)
-[MFC Desktop Applications](../../mfc/mfc-desktop-applications.md)
+[Creating an MFC Application](../../mfc/reference/creating-an-mfc-application.md)\ +[MFC Desktop Applications](../../mfc/mfc-desktop-applications.md)\ [Using the Classes to Write Applications for Windows](../../mfc/using-the-classes-to-write-applications-for-windows.md) diff --git a/docs/mfc/reference/mfc-class-wizard.md b/docs/mfc/reference/mfc-class-wizard.md index a905191217..ea0eb4c71b 100644 --- a/docs/mfc/reference/mfc-class-wizard.md +++ b/docs/mfc/reference/mfc-class-wizard.md @@ -4,7 +4,6 @@ title: "MFC Class Wizard" ms.date: "09/06/2019" f1_keywords: ["vc.wizards.classwizard"] helpviewer_keywords: ["MFC Class Wizard"] -ms.assetid: 8b0dd867-5d07-4214-99be-2a1c1995e6d9 --- # MFC Class Wizard @@ -14,7 +13,7 @@ There are three ways to open the **Class Wizard**: - On the **Project** menu, choose **Class Wizard**. - Type **Ctrl** > **Shift** > **X**. -- In **Class View**, right click on a class or the project node and choose **Class Wizard**. +- In **Class View**, right-click on a class or the project node and choose **Class Wizard**. ![Class Wizard.](media/class-wizard.png "MFC Class Wizard") @@ -34,7 +33,7 @@ There are three ways to open the **Class Wizard**: - **Add Class** - Enables you add a new class to your MFC project. + Lets you add a new class to your MFC project. - **Base class** @@ -66,19 +65,19 @@ There are three ways to open the **Class Wizard**: Lets you add, delete, edit, or search for a command and its message handler. - To add a handler, click **Add Handler**, or double-click an item in the **Object IDs** list or **Messages** list. The resulting function name, ID, and message are displayed in the **Member functions** list. + To add a handler, select **Add Handler**, or double-click an item in the **Object IDs** list or **Messages** list. The resulting function name, ID, and message are displayed in the **Member functions** list. - To delete a handler, select an item in the **Member functions** list and then click **Delete Handler**. + To delete a handler, select an item in the **Member functions** list and then select **Delete Handler**. - To modify a handler, double-click the corresponding item in the **Member functions** list. Or, select an item in the list box and then click **Edit Code**. + To modify a handler, double-click the corresponding item in the **Member functions** list. Or, select an item in the list box and then select **Edit Code**. - **Messages** Lets you add, delete, edit, or search for a message and its message handler. - To add a handler, click **Add Handler**, or double-click an item in the **Messages** list. + To add a handler, select **Add Handler**, or double-click an item in the **Messages** list. - To add a custom message, click **Add Custom Message** or press the Enter key, and then specify values in the **Add Custom Message** dialog box. In that dialog box, you can also select **Registered Message** to handle a window message that is guaranteed to be unique throughout the operating system. + To add a custom message, select **Add Custom Message** or press the Enter key, and then specify values in the **Add Custom Message** dialog box. In that dialog box, you can also select **Registered Message** to handle a window message that is guaranteed to be unique throughout the operating system. - **Virtual Functions** @@ -92,13 +91,13 @@ There are three ways to open the **Class Wizard**: Lets you add, delete, or search for a method, and also go to the definition or declaration of a method. - To add a method, click **Add Method**, and then specify values in the **Add Method** dialog box. + To add a method, select **Add Method**, and then specify values in the **Add Method** dialog box. - To delete a method, select an item in the **Methods** list and then click **Delete Method**. + To delete a method, select an item in the **Methods** list and then select **Delete Method**. - To display a declaration, select an item in the **Methods** list and then click **Go to Declaration.** + To display a declaration, select an item in the **Methods** list and then select **Go to Declaration.** - To display a definition, double-click an item in the **Methods** list. Or, select an item in the **Methods** list and then click the **Go to Definition** button. + To display a definition, double-click an item in the **Methods** list. Or, select an item in the **Methods** list and then select the **Go to Definition** button. ## See also diff --git a/docs/mfc/reference/mfc-classes.md b/docs/mfc/reference/mfc-classes.md index 1b2c709b60..83c30958f5 100644 --- a/docs/mfc/reference/mfc-classes.md +++ b/docs/mfc/reference/mfc-classes.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: MFC` Classes" -title: "MFC` Classes" -ms.date: "11/04/2016" +title: "MFC Classes" +description: "Learn more about: MFC Classes" +ms.date: 11/04/2016 helpviewer_keywords: ["MFC, classes", "classes [MFC], MFC"] -ms.assetid: 7b6db805-a572-43fd-9046-0fa6e3663e63 --- # MFC Classes @@ -17,1285 +16,1285 @@ The classes in the following list are included in the Microsoft Foundation Class ## In This Section -[`CAccelerateDecelerateTransition` Class](../../mfc/reference/cacceleratedeceleratetransition-class.md)
+[`CAccelerateDecelerateTransition` Class](cacceleratedeceleratetransition-class.md)\ Implements an accelerate-decelerate transition. -[`CAnimateCtrl` Class](../../mfc/reference/canimatectrl-class.md)
+[`CAnimateCtrl` Class](canimatectrl-class.md)\ Provides the functionality of the Windows common animation control. -[`CAnimationBaseObject` Class](../../mfc/reference/canimationbaseobject-class.md)
+[`CAnimationBaseObject` Class](canimationbaseobject-class.md)\ The base class for all animation objects. -[`CAnimationColor` Class](../../mfc/reference/canimationcolor-class.md)
+[`CAnimationColor` Class](canimationcolor-class.md)\ Implements the functionality of a color whose red, green, and blue components can be animated. -[`CAnimationController` Class](../../mfc/reference/canimationcontroller-class.md)
+[`CAnimationController` Class](canimationcontroller-class.md)\ Implements the animation controller, which provides a central interface for creating and managing animations. -[`CAnimationGroup` Class](../../mfc/reference/canimationgroup-class.md)
+[`CAnimationGroup` Class](canimationgroup-class.md)\ Implements the animation controller, which provides a central interface for creating and managing animations. -[`CAnimationManagerEventHandler` Class](../../mfc/reference/canimationmanagereventhandler-class.md)
+[`CAnimationManagerEventHandler` Class](canimationmanagereventhandler-class.md)\ Implements a callback, which is called by the Animation API when a status of an animation manager is changed. -[`CAnimationPoint` Class](../../mfc/reference/canimationpoint-class.md)
+[`CAnimationPoint` Class](canimationpoint-class.md)\ Implements the functionality of a point whose coordinates can be animated. -[`CAnimationRect` Class](../../mfc/reference/canimationrect-class.md)
+[`CAnimationRect` Class](canimationrect-class.md)\ Implements the functionality of a rectangle whose sides can be animated. -[`CAnimationSize` Class](../../mfc/reference/canimationsize-class.md)
+[`CAnimationSize` Class](canimationsize-class.md)\ Implements the functionality of a size object whose dimensions can be animated. -[`CAnimationStoryboardEventHandler` Class](../../mfc/reference/canimationstoryboardeventhandler-class.md)
+[`CAnimationStoryboardEventHandler` Class](canimationstoryboardeventhandler-class.md)\ Implements a callback, which is called by the Animation API when the status of a storyboard is changed or a storyboard is updated. -[`CAnimationTimerEventHandler` Class](../../mfc/reference/canimationtimereventhandler-class.md)
+[`CAnimationTimerEventHandler` Class](canimationtimereventhandler-class.md)\ Implements a callback, which is called by the Animation API when timing events occur. -[`CAnimationValue` Class](../../mfc/reference/canimationvalue-class.md)
+[`CAnimationValue` Class](canimationvalue-class.md)\ Implements the functionality of animation object that has one value. -[`CAnimationVariable` Class](../../mfc/reference/canimationvariable-class.md)
+[`CAnimationVariable` Class](canimationvariable-class.md)\ Represents an animation variable. -[`CAnimationVariableChangeHandler` Class](../../mfc/reference/canimationvariablechangehandler-class.md)
+[`CAnimationVariableChangeHandler` Class](canimationvariablechangehandler-class.md)\ Implements a callback, which is called by the Animation API when the value of an animation variable changes. -[`CAnimationVariableIntegerChangeHandler` Class](../../mfc/reference/canimationvariableintegerchangehandler-class.md)
+[`CAnimationVariableIntegerChangeHandler` Class](canimationvariableintegerchangehandler-class.md)\ Implements a callback, which is called by the Animation API when the value of an animation variable changes. -[`CArchive` Class](../../mfc/reference/carchive-class.md)
+[`CArchive` Class](carchive-class.md)\ Lets you save a complex network of objects in a permanent binary form (usually disk storage) that persists after those objects are deleted. -[`CArchiveException` Class](../../mfc/reference/carchiveexception-class.md)
+[`CArchiveException` Class](carchiveexception-class.md)\ Represents a serialization exception condition. -[`CArray` Class](../../mfc/reference/carray-class.md)
+[`CArray` Class](carray-class.md)\ Supports arrays that resemble` C arrays, but can dynamically reduce and grow as necessary. -[`CAsyncMonikerFile` Class](../../mfc/reference/casyncmonikerfile-class.md)
+[`CAsyncMonikerFile` Class](casyncmonikerfile-class.md)\ Provides functionality for the use of asynchronous monikers in ActiveX controls (formerly OLE controls). -[`CAsyncSocket` Class](../../mfc/reference/casyncsocket-class.md)
+[`CAsyncSocket` Class](casyncsocket-class.md)\ Represents a Windows Socket, which is an endpoint of network communication. -[`CAutoHideDockSite` Class](../../mfc/reference/cautohidedocksite-class.md)
-Extends the [`CDockSite` Class](../../mfc/reference/cdocksite-class.md) to implement auto-hide dock panes. +[`CAutoHideDockSite` Class](cautohidedocksite-class.md)\ +Extends the [`CDockSite` Class](cdocksite-class.md) to implement auto-hide dock panes. -[`CBaseKeyFrame` Class](../../mfc/reference/cbasekeyframe-class.md)
+[`CBaseKeyFrame` Class](cbasekeyframe-class.md)\ Implements the basic functionality of a keyframe. -[`CBasePane` Class](../../mfc/reference/cbasepane-class.md)
+[`CBasePane` Class](cbasepane-class.md)\ Base class for all panes. -[`CBaseTabbedPane` Class](../../mfc/reference/cbasetabbedpane-class.md)
-Extends the functionality of the [`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md) to support the creation of tabbed windows. +[`CBaseTabbedPane` Class](cbasetabbedpane-class.md)\ +Extends the functionality of the [`CDockablePane` Class](cdockablepane-class.md) to support the creation of tabbed windows. -[`CBaseTransition` Class](../../mfc/reference/cbasetransition-class.md)
+[`CBaseTransition` Class](cbasetransition-class.md)\ Represents a basic transition. -[`CBitmap` Class](../../mfc/reference/cbitmap-class.md)
+[`CBitmap` Class](cbitmap-class.md)\ Encapsulates a Windows graphics device interface (GDI) bitmap and provides member functions to manipulate the bitmap. -[`CBitmapButton` Class](../../mfc/reference/cbitmapbutton-class.md)
+[`CBitmapButton` Class](cbitmapbutton-class.md)\ Creates pushbutton controls labeled with bitmapped images instead of text. -[`CBitmapRenderTarget` Class](../../mfc/reference/cbitmaprendertarget-class.md)
+[`CBitmapRenderTarget` Class](cbitmaprendertarget-class.md)\ A wrapper for `ID2D1BitmapRenderTarget`. -[`CBrush` Class](../../mfc/reference/cbrush-class.md)
+[`CBrush` Class](cbrush-class.md)\ Encapsulates a Windows graphics device interface (GDI) brush. -[`CButton` Class](../../mfc/reference/cbutton-class.md)
+[`CButton` Class](cbutton-class.md)\ Provides the functionality of Windows button controls. -[`CByteArray` Class](../../mfc/reference/cbytearray-class.md)
+[`CByteArray` Class](cbytearray-class.md)\ Supports dynamic arrays of bytes. -[`CCachedDataPathProperty` Class](../../mfc/reference/ccacheddatapathproperty-class.md)
+[`CCachedDataPathProperty` Class](ccacheddatapathproperty-class.md)\ Implements an OLE control property transferred asynchronously and cached in a memory file. -[`CCheckListBox` Class](../../mfc/reference/cchecklistbox-class.md)
+[`CCheckListBox` Class](cchecklistbox-class.md)\ Provides the functionality of a Windows checklist box. -[`CClientDC` Class](../../mfc/reference/cclientdc-class.md)
+[`CClientDC` Class](cclientdc-class.md)\ Handles the calling of the Windows functions [`GetDC`](/windows/win32/api/winuser/nf-winuser-getdc) at construction time and [`ReleaseDC`](/windows/win32/api/winuser/nf-winuser-releasedc) at destruction time. -[`CCmdTarget` Class](../../mfc/reference/ccmdtarget-class.md)
+[`CCmdTarget` Class](ccmdtarget-class.md)\ Base class for the Microsoft Foundation Class Library message-map architecture. -[`CCmdUI` Class](../../mfc/reference/ccmdui-class.md)
+[`CCmdUI` Class](ccmdui-class.md)\ Used only within an `ON_UPDATE_COMMAND_UI` handler in a `CCmdTarget`-derived class. -[`CColorDialog` Class](../../mfc/reference/ccolordialog-class.md)
+[`CColorDialog` Class](ccolordialog-class.md)\ Lets you incorporate a color-selection dialog box into your application. -[`CComboBox` Class](../../mfc/reference/ccombobox-class.md)
+[`CComboBox` Class](ccombobox-class.md)\ Provides the functionality of a Windows combo box. -[`CComboBoxEx` Class](../../mfc/reference/ccomboboxex-class.md)
+[`CComboBoxEx` Class](ccomboboxex-class.md)\ Extends the combo box control by providing support for image lists. -[`CCommandLineInfo` Class](../../mfc/reference/ccommandlineinfo-class.md)
+[`CCommandLineInfo` Class](ccommandlineinfo-class.md)\ Aids in parsing the command line at application startup. -[`CCommonDialog` Class](../../mfc/reference/ccommondialog-class.md)
+[`CCommonDialog` Class](ccommondialog-class.md)\ The base class for classes that encapsulate functionality of the Windows common dialogs. -[`CConnectionPoint` Class](../../mfc/reference/cconnectionpoint-class.md)
+[`CConnectionPoint` Class](cconnectionpoint-class.md)\ Defines a special type of interface used to communicate with other OLE objects, called a "connection point." -[`CConstantTransition` Class](../../mfc/reference/cconstanttransition-class.md)
+[`CConstantTransition` Class](cconstanttransition-class.md)\ Encapsulates a constant transition. -[`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md)
+[`CContextMenuManager` Class](ccontextmenumanager-class.md)\ Manages shortcut menus, also known as context menus. -[`CControlBar` Class](../../mfc/reference/ccontrolbar-class.md)
-Base class for the control-bar classes [`CStatusBar` Class](../../mfc/reference/cstatusbar-class.md), [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), [`CDialogBar` Class](../../mfc/reference/cdialogbar-class.md), [`CReBar` Class](../../mfc/reference/crebar-class.md), and [`COleResizeBar` Class](../../mfc/reference/coleresizebar-class.md). +[`CControlBar` Class](ccontrolbar-class.md)\ +Base class for the control-bar classes [`CStatusBar` Class](cstatusbar-class.md), [`CToolBar` Class](ctoolbar-class.md), [`CDialogBar` Class](cdialogbar-class.md), [`CReBar` Class](crebar-class.md), and [`COleResizeBar` Class](coleresizebar-class.md). -[`CCriticalSection` Class](../../mfc/reference/ccriticalsection-class.md)
+[`CCriticalSection` Class](ccriticalsection-class.md)\ Represents a "critical section", which is a synchronization object that enables one thread at a time to access a resource or section of code. -[`CCtrlView` Class](../../mfc/reference/cctrlview-class.md)
+[`CCtrlView` Class](cctrlview-class.md)\ Adapts the document-view architecture to the common controls supported by Windows 98 and Windows NT versions 3.51 and later. -[`CCubicTransition` Class](../../mfc/reference/ccubictransition-class.md)
+[`CCubicTransition` Class](ccubictransition-class.md)\ Encapsulates a cubic transition. -[`CCustomInterpolator` Class](../../mfc/reference/ccustominterpolator-class.md)
+[`CCustomInterpolator` Class](ccustominterpolator-class.md)\ Implements a basic interpolator. -[`CCustomTransition` Class](../../mfc/reference/ccustomtransition-class.md)
+[`CCustomTransition` Class](ccustomtransition-class.md)\ Implements a custom transition. -[`CD2DBitmap` Class](../../mfc/reference/cd2dbitmap-class.md)
+[`CD2DBitmap` Class](cd2dbitmap-class.md)\ A wrapper for `ID2D1Bitmap`. -[`CD2DBitmapBrush` Class](../../mfc/reference/cd2dbitmapbrush-class.md)
+[`CD2DBitmapBrush` Class](cd2dbitmapbrush-class.md)\ A wrapper for `ID2D1BitmapBrush`. -[`CD2DBrush` Class](../../mfc/reference/cd2dbrush-class.md)
+[`CD2DBrush` Class](cd2dbrush-class.md)\ A wrapper for `ID2D1Brush`. -[`CD2DBrushProperties` Class](../../mfc/reference/cd2dbrushproperties-class.md)
+[`CD2DBrushProperties` Class](cd2dbrushproperties-class.md)\ A wrapper for `D2D1_BRUSH_PROPERTIES`. -[`CD2DEllipse` Class](../../mfc/reference/cd2dellipse-class.md)
+[`CD2DEllipse` Class](cd2dellipse-class.md)\ A wrapper for `D2D1_BRUSH_PROPERTIES`. -[`CD2DGeometry` Class](../../mfc/reference/cd2dgeometry-class.md)
+[`CD2DGeometry` Class](cd2dgeometry-class.md)\ A wrapper for `ID2D1Geometry`. -[`CD2DGeometrySink` Class](../../mfc/reference/cd2dgeometrysink-class.md)
+[`CD2DGeometrySink` Class](cd2dgeometrysink-class.md)\ A wrapper for `ID2D1GeometrySink`. -[`CD2DGradientBrush` Class](../../mfc/reference/cd2dgradientbrush-class.md)
+[`CD2DGradientBrush` Class](cd2dgradientbrush-class.md)\ The base class of the `CD2DLinearGradientBrush` and the `CD2DRadialGradientBrush` classes. -[`CD2DLayer` Class](../../mfc/reference/cd2dlayer-class.md)
+[`CD2DLayer` Class](cd2dlayer-class.md)\ A wrapper for `ID2D1Layer`. -[`CD2DLinearGradientBrush` Class](../../mfc/reference/cd2dlineargradientbrush-class.md)
+[`CD2DLinearGradientBrush` Class](cd2dlineargradientbrush-class.md)\ A wrapper for `ID2D1LinearGradientBrush`. -[`CD2DMesh` Class](../../mfc/reference/cd2dmesh-class.md)
+[`CD2DMesh` Class](cd2dmesh-class.md)\ A wrapper for `ID2D1Mesh`. -[`CD2DPathGeometry` Class](../../mfc/reference/cd2dpathgeometry-class.md)
+[`CD2DPathGeometry` Class](cd2dpathgeometry-class.md)\ A wrapper for `ID2D1PathGeometry`. -[`CD2DPointF` Class](../../mfc/reference/cd2dpointf-class.md)
+[`CD2DPointF` Class](cd2dpointf-class.md)\ A wrapper for `D2D1_POINT_2F`. -[`CD2DPointU` Class](../../mfc/reference/cd2dpointu-class.md)
+[`CD2DPointU` Class](cd2dpointu-class.md)\ A wrapper for `D2D1_POINT_2U`. -[`CD2DRadialGradientBrush` Class](../../mfc/reference/cd2dradialgradientbrush-class.md)
+[`CD2DRadialGradientBrush` Class](cd2dradialgradientbrush-class.md)\ A wrapper for `ID2D1RadialGradientBrush`. -[`CD2DRectF` Class](../../mfc/reference/cd2drectf-class.md)
+[`CD2DRectF` Class](cd2drectf-class.md)\ A wrapper for `D2D1_RECT_F`. -[`CD2DRectU` Class](../../mfc/reference/cd2drectu-class.md)
+[`CD2DRectU` Class](cd2drectu-class.md)\ A wrapper for `D2D1_RECT_U`. -[`CD2DResource` Class](../../mfc/reference/cd2dresource-class.md)
-An abstract class that provides a interface for creating and managing `D2D` resources such as brushes, layers, and texts. +[`CD2DResource` Class](cd2dresource-class.md)\ +An abstract class that provides an interface for creating and managing `D2D` resources such as brushes, layers, and texts. -[`CD2DRoundedRect` Class](../../mfc/reference/cd2droundedrect-class.md)
+[`CD2DRoundedRect` Class](cd2droundedrect-class.md)\ A wrapper for `D2D1_ROUNDED_RECT`. -[`CD2DSizeF` Class](../../mfc/reference/cd2dsizef-class.md)
+[`CD2DSizeF` Class](cd2dsizef-class.md)\ A wrapper for `D2D1_SIZE_F`. -[`CD2DSizeU` Class](../../mfc/reference/cd2dsizeu-class.md)
+[`CD2DSizeU` Class](cd2dsizeu-class.md)\ A wrapper for `D2D1_SIZE_U`. -[`CD2DSolidColorBrush` Class](../../mfc/reference/cd2dsolidcolorbrush-class.md)
+[`CD2DSolidColorBrush` Class](cd2dsolidcolorbrush-class.md)\ A wrapper for `ID2D1SolidColorBrush`. -[`CD2DTextFormat` Class](../../mfc/reference/cd2dtextformat-class.md)
+[`CD2DTextFormat` Class](cd2dtextformat-class.md)\ A wrapper for `IDWriteTextFormat`. -[`CD2DTextLayout` Class](../../mfc/reference/cd2dtextlayout-class.md)
+[`CD2DTextLayout` Class](cd2dtextlayout-class.md)\ A wrapper for `IDWriteTextLayout`. -[`CDaoDatabase` Class](../../mfc/reference/cdaodatabase-class.md)
+[`CDaoDatabase` Class](cdaodatabase-class.md)\ Represents a connection to a database through which you can operate on the data. -[`CDaoException` Class](../../mfc/reference/cdaoexception-class.md)
+[`CDaoException` Class](cdaoexception-class.md)\ Represents an exception condition arising from the MFC database classes based on data access objects (DAO). -[`CDaoFieldExchange` Class](../../mfc/reference/cdaofieldexchange-class.md)
+[`CDaoFieldExchange` Class](cdaofieldexchange-class.md)\ Supports the DAO record field exchange (DFX) routines used by the DAO database classes. -[`CDaoQueryDef` Class](../../mfc/reference/cdaoquerydef-class.md)
+[`CDaoQueryDef` Class](cdaoquerydef-class.md)\ Represents a query definition, or "querydef," usually one saved in a database. -[`CDaoRecordset` Class](../../mfc/reference/cdaorecordset-class.md)
+[`CDaoRecordset` Class](cdaorecordset-class.md)\ Represents a set of records selected from a data source. -[`CDaoRecordView` Class](../../mfc/reference/cdaorecordview-class.md)
+[`CDaoRecordView` Class](cdaorecordview-class.md)\ A view that displays database records in controls. -[`CDaoTableDef` Class](../../mfc/reference/cdaotabledef-class.md)
+[`CDaoTableDef` Class](cdaotabledef-class.md)\ Represents the stored definition of a base table or an attached table. -[`CDaoWorkspace` Class](../../mfc/reference/cdaoworkspace-class.md)
+[`CDaoWorkspace` Class](cdaoworkspace-class.md)\ Manages a named, password-protected database session from login to logoff, by a single user. -[`CDatabase` Class](../../mfc/reference/cdatabase-class.md)
+[`CDatabase` Class](cdatabase-class.md)\ Represents a connection to a data source, through which you can operate on the data source. -[`CDataExchange` Class](../../mfc/reference/cdataexchange-class.md)
+[`CDataExchange` Class](cdataexchange-class.md)\ Supports the dialog data exchange (DDX) and dialog data validation (DDV) routines used by the Microsoft Foundation classes. -[`CDataPathProperty` Class](../../mfc/reference/cdatapathproperty-class.md)
+[`CDataPathProperty` Class](cdatapathproperty-class.md)\ Implements an OLE control property that can be loaded asynchronously. -[`CDataRecoveryHandler` Class](../../mfc/reference/cdatarecoveryhandler-class.md)
+[`CDataRecoveryHandler` Class](cdatarecoveryhandler-class.md)\ Autosaves documents and restores them if an application unexpectedly exits. -[`CDateTimeCtrl` Class](../../mfc/reference/cdatetimectrl-class.md)
+[`CDateTimeCtrl` Class](cdatetimectrl-class.md)\ Encapsulates the functionality of a date and time picker control. -[`CDBException` Class](../../mfc/reference/cdbexception-class.md)
+[`CDBException` Class](cdbexception-class.md)\ Represents an exception condition arising from the database classes. -[`CDBVariant` Class](../../mfc/reference/cdbvariant-class.md)
+[`CDBVariant` Class](cdbvariant-class.md)\ Represents a variant data type for the MFC ODBC classes. -[`CDC` Class](../../mfc/reference/cdc-class.md)
+[`CDC` Class](cdc-class.md)\ Defines a class of device-context objects. -[`CDCRenderTarget` Class](../../mfc/reference/cdcrendertarget-class.md)
+[`CDCRenderTarget` Class](cdcrendertarget-class.md)\ A wrapper for `ID2D1DCRenderTarget`. -[`CDHtmlDialog` Class](../../mfc/reference/cdhtmldialog-class.md)
+[`CDHtmlDialog` Class](cdhtmldialog-class.md)\ Used to create dialog boxes that use HTML rather than dialog resources to implement their user interface. -[`CDialog` Class](../../mfc/reference/cdialog-class.md)
+[`CDialog` Class](cdialog-class.md)\ Base class used for displaying dialog boxes on the screen. -[`CDialogBar` Class](../../mfc/reference/cdialogbar-class.md)
+[`CDialogBar` Class](cdialogbar-class.md)\ Provides the functionality of a Windows modeless dialog box in a control bar. -[`CDialogEx` Class](../../mfc/reference/cdialogex-class.md)
+[`CDialogEx` Class](cdialogex-class.md)\ Specifies the background color and background image of a dialog box. -[`CDiscreteTransition` Class](../../mfc/reference/cdiscretetransition-class.md)
+[`CDiscreteTransition` Class](cdiscretetransition-class.md)\ Encapsulates a discrete transition. -[`CDocItem` Class](../../mfc/reference/cdocitem-class.md)
+[`CDocItem` Class](cdocitem-class.md)\ The base class for document items, which are components of a document's data. -[`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md)
+[`CDockablePane` Class](cdockablepane-class.md)\ Implements a pane that can either be docked in a dock site or included in a tabbed pane. -[`CDockablePaneAdapter` Class](../../mfc/reference/cdockablepaneadapter-class.md)
+[`CDockablePaneAdapter` Class](cdockablepaneadapter-class.md)\ Provides docking support for `CWnd`-derived panes. -[`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md)
+[`CDockingManager` Class](cdockingmanager-class.md)\ Implements the core functionality that controls docking layout in a main frame window. -[`CDockingPanesRow` Class](../../mfc/reference/cdockingpanesrow-class.md)
+[`CDockingPanesRow` Class](cdockingpanesrow-class.md)\ Manages a list of panes that are located in the same horizontal or vertical row (column) of a dock site. -[`CDockSite` Class](../../mfc/reference/cdocksite-class.md)
-Provides functionality for arranging panes that are derived from the [`CPane` Class](../../mfc/reference/cpane-class.md) into sets of rows. +[`CDockSite` Class](cdocksite-class.md)\ +Provides functionality for arranging panes that are derived from the [`CPane` Class](cpane-class.md) into sets of rows. -[`CDockState` Class](../../mfc/reference/cdockstate-class.md)
+[`CDockState` Class](cdockstate-class.md)\ A serialized `CObject` class that loads, unloads, or clears the state of one or more docking control bars in persistent memory (a file). -[`CDocObjectServer` Class](../../mfc/reference/cdocobjectserver-class.md)
+[`CDocObjectServer` Class](cdocobjectserver-class.md)\ Implements the additional OLE interfaces needed to make a normal `COleDocument` server into a full DocObject server: `IOleDocument`, `IOleDocumentView`, `IOleCommandTarget`, and `IPrint`. -[`CDocObjectServerItem` Class](../../mfc/reference/cdocobjectserveritem-class.md)
+[`CDocObjectServerItem` Class](cdocobjectserveritem-class.md)\ Implements OLE server verbs specifically for DocObject servers. -[`CDocTemplate` Class](../../mfc/reference/cdoctemplate-class.md)
+[`CDocTemplate` Class](cdoctemplate-class.md)\ An abstract base class that defines the basic functionality for document templates. -[`CDocument` Class](../../mfc/reference/cdocument-class.md)
+[`CDocument` Class](cdocument-class.md)\ Provides the basic functionality for user-defined document classes. -[`CDragListBox` Class](../../mfc/reference/cdraglistbox-class.md)
+[`CDragListBox` Class](cdraglistbox-class.md)\ In addition to providing the functionality of a Windows list box, the `CDragListBox` class lets the user move list box items, such as filenames, within the list box. -[`CDrawingManager` Class](../../mfc/reference/cdrawingmanager-class.md)
+[`CDrawingManager` Class](cdrawingmanager-class.md)\ Implements complex drawing algorithms. -[`CDumpContext` Class](../../mfc/reference/cdumpcontext-class.md)
+[`CDumpContext` Class](cdumpcontext-class.md)\ Supports stream-oriented diagnostic output in the form of human-readable text. -[`CDWordArray` Class](../../mfc/reference/cdwordarray-class.md)
+[`CDWordArray` Class](cdwordarray-class.md)\ Supports arrays of 32-bit doublewords. -[`CEdit` Class](../../mfc/reference/cedit-class.md)
+[`CEdit` Class](cedit-class.md)\ Provides the functionality of a Windows edit control. -[`CEditView` Class](../../mfc/reference/ceditview-class.md)
+[`CEditView` Class](ceditview-class.md)\ A type of view class that provides the functionality of a Windows edit control and can be used to implement simple text-editor functionality. -[`CEvent` Class](../../mfc/reference/cevent-class.md)
+[`CEvent` Class](cevent-class.md)\ Represents an "event", which is a synchronization object that enables one thread to notify another that an event has occurred. -[`CException` Class](../../mfc/reference/cexception-class.md)
+[`CException` Class](cexception-class.md)\ The base class for all exceptions in the Microsoft Foundation Class Library. -[`CFieldExchange` Class](../../mfc/reference/cfieldexchange-class.md)
+[`CFieldExchange` Class](cfieldexchange-class.md)\ Supports the record field exchange (RFX) and bulk record field exchange (Bulk RFX) routines used by the database classes. -[`CFile` Class](../../mfc/reference/cfile-class.md)
+[`CFile` Class](cfile-class.md)\ The base class for Microsoft Foundation Class file classes. -[`CFileDialog` Class](../../mfc/reference/cfiledialog-class.md)
+[`CFileDialog` Class](cfiledialog-class.md)\ Encapsulates the common file dialog box for Windows. -[`CFileException` Class](../../mfc/reference/cfileexception-class.md)
+[`CFileException` Class](cfileexception-class.md)\ Represents a file-related exception condition. -[`CFileFind` Class](../../mfc/reference/cfilefind-class.md)
-Performs local file searches and is the base class for [`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md) and [`CFtpFileFind` Class](../../mfc/reference/cftpfilefind-class.md), which perform Internet file searches. +[`CFileFind` Class](cfilefind-class.md)\ +Performs local file searches and is the base class for [`CGopherFileFind` Class](cgopherfilefind-class.md) and [`CFtpFileFind` Class](cftpfilefind-class.md), which perform Internet file searches. -[`CFindReplaceDialog` Class](../../mfc/reference/cfindreplacedialog-class.md)
+[`CFindReplaceDialog` Class](cfindreplacedialog-class.md)\ Lets you implement standard string Find/Replace dialog boxes in your application. -[`CFolderPickerDialog` Class](../../mfc/reference/cfolderpickerdialog-class.md)
+[`CFolderPickerDialog` Class](cfolderpickerdialog-class.md)\ Implements `CFileDialog` in the folder picker mode. -[`CFont` Class](../../mfc/reference/cfont-class.md)
+[`CFont` Class](cfont-class.md)\ Encapsulates a Windows graphics device interface (GDI) font and provides member functions for manipulating the font. -[`CFontDialog` Class](../../mfc/reference/cfontdialog-class.md)
+[`CFontDialog` Class](cfontdialog-class.md)\ Lets you incorporate a font-selection dialog box into your application. -[`CFontHolder` Class](../../mfc/reference/cfontholder-class.md)
+[`CFontHolder` Class](cfontholder-class.md)\ Implements the stock Font property and encapsulates the functionality of a Windows font object and the `IFont` interface. -[`CFormView` Class](../../mfc/reference/cformview-class.md)
+[`CFormView` Class](cformview-class.md)\ The base class used for form views. -[`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md)
+[`CFrameWnd` Class](cframewnd-class.md)\ Provides the functionality of a Windows single document interface (SDI) overlapped or pop-up frame window, along with members for managing the window. -[`CFrameWndEx` Class](../../mfc/reference/cframewndex-class.md)
-Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md) class. +[`CFrameWndEx` Class](cframewndex-class.md)\ +Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd` Class](cframewnd-class.md) class. -[`CFtpConnection` Class](../../mfc/reference/cftpconnection-class.md)
+[`CFtpConnection` Class](cftpconnection-class.md)\ Manages your FTP connection to an Internet server and enables direct manipulation of directories and files on that server. -[`CFtpFileFind` Class](../../mfc/reference/cftpfilefind-class.md)
+[`CFtpFileFind` Class](cftpfilefind-class.md)\ Aids in Internet file searches of FTP servers. -[`CGdiObject` Class](../../mfc/reference/cgdiobject-class.md)
+[`CGdiObject` Class](cgdiobject-class.md)\ Provides a base class for various kinds of Windows graphics device interface (GDI) objects such as bitmaps, regions, brushes, pens, palettes, and fonts. -[`CGopherConnection` Class](../../mfc/reference/cgopherconnection-class.md)
+[`CGopherConnection` Class](cgopherconnection-class.md)\ Manages your connection to a gopher Internet server. -[`CGopherFile` Class](../../mfc/reference/cgopherfile-class.md)
+[`CGopherFile` Class](cgopherfile-class.md)\ Provides the functionality to find and read files on a gopher server. -[`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md)
+[`CGopherFileFind` Class](cgopherfilefind-class.md)\ Aids in Internet file searches of gopher servers. -[`CGopherLocator` Class](../../mfc/reference/cgopherlocator-class.md)
-Gets a gopher "locator" from a gopher server, determines the locator's type, and makes the locator available to [`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md). +[`CGopherLocator` Class](cgopherlocator-class.md)\ +Gets a gopher "locator" from a gopher server, determines the locator's type, and makes the locator available to [`CGopherFileFind` Class](cgopherfilefind-class.md). -[`CHeaderCtrl` Class](../../mfc/reference/cheaderctrl-class.md)
+[`CHeaderCtrl` Class](cheaderctrl-class.md)\ Provides the functionality of the Windows common header control. -[`CHotKeyCtrl` Class](../../mfc/reference/chotkeyctrl-class.md)
+[`CHotKeyCtrl` Class](chotkeyctrl-class.md)\ Provides the functionality of the Windows common hot key control. -[`CHtmlEditCtrl` Class](../../mfc/reference/chtmleditctrl-class.md)
+[`CHtmlEditCtrl` Class](chtmleditctrl-class.md)\ Provides the functionality of the `WebBrowser` ActiveX control in an MFC window. -[`CHtmlEditCtrlBase` Class](../../mfc/reference/chtmleditctrlbase-class.md)
+[`CHtmlEditCtrlBase` Class](chtmleditctrlbase-class.md)\ Represents an HTML editing component. -[`CHtmlEditDoc` Class](../../mfc/reference/chtmleditdoc-class.md)
-With [`CHtmlEditView` Class](../../mfc/reference/chtmleditview-class.md), provides the functionality of the WebBrowser editing platform within the context of the MFC document-view architecture. +[`CHtmlEditDoc` Class](chtmleditdoc-class.md)\ +With [`CHtmlEditView` Class](chtmleditview-class.md), provides the functionality of the WebBrowser editing platform within the context of the MFC document-view architecture. -[`CHtmlEditView` Class](../../mfc/reference/chtmleditview-class.md)
+[`CHtmlEditView` Class](chtmleditview-class.md)\ Provides the functionality of the WebBrowser editing platform within the context of MFC's document/view architecture. -[`CHtmlView` Class](../../mfc/reference/chtmlview-class.md)
+[`CHtmlView` Class](chtmlview-class.md)\ Provides the functionality of the WebBrowser control within the context of MFC's document/view architecture. -[`CHttpConnection` Class](../../mfc/reference/chttpconnection-class.md)
+[`CHttpConnection` Class](chttpconnection-class.md)\ Manages your connection to an HTTP server. -[`CHttpFile` Class](../../mfc/reference/chttpfile-class.md)
+[`CHttpFile` Class](chttpfile-class.md)\ Provides the functionality to request and read files on an HTTP server. -[`CHwndRenderTarget` Class](../../mfc/reference/chwndrendertarget-class.md)
+[`CHwndRenderTarget` Class](chwndrendertarget-class.md)\ A wrapper for `ID2D1HwndRenderTarget`. -[`CImageList` Class](../../mfc/reference/cimagelist-class.md)
+[`CImageList` Class](cimagelist-class.md)\ Provides the functionality of the Windows common image list control. -[`CInstantaneousTransition` Class](../../mfc/reference/cinstantaneoustransition-class.md)
+[`CInstantaneousTransition` Class](cinstantaneoustransition-class.md)\ Encapsulates an instantaneous transition. -[`CInternetConnection` Class](../../mfc/reference/cinternetconnection-class.md)
+[`CInternetConnection` Class](cinternetconnection-class.md)\ Manages your connection to an Internet server. -[`CInternetException` Class](../../mfc/reference/cinternetexception-class.md)
+[`CInternetException` Class](cinternetexception-class.md)\ Represents an exception condition related to an Internet operation. -[`CInternetFile` Class](../../mfc/reference/cinternetfile-class.md)
+[`CInternetFile` Class](cinternetfile-class.md)\ Enables access to files on remote systems that use Internet protocols. -[`CInternetSession` Class](../../mfc/reference/cinternetsession-class.md)
+[`CInternetSession` Class](cinternetsession-class.md)\ Creates and initializes a single or several simultaneous Internet sessions and, if necessary, describes your connection to a proxy server. -[`CInterpolatorBase` Class](../../mfc/reference/cinterpolatorbase-class.md)
+[`CInterpolatorBase` Class](cinterpolatorbase-class.md)\ Implements a callback, which is called by the Animation API when it has to calculate a new value of an animation variable. -[`CInvalidArgException` Class](../../mfc/reference/cinvalidargexception-class.md)
+[`CInvalidArgException` Class](cinvalidargexception-class.md)\ This class represents an invalid argument exception condition. -[`CIPAddressCtrl` Class](../../mfc/reference/cipaddressctrl-class.md)
+[`CIPAddressCtrl` Class](cipaddressctrl-class.md)\ Provides the functionality of the Windows common IP Address control. -[`CJumpList` Class](../../mfc/reference/cjumplist-class.md)
+[`CJumpList` Class](cjumplist-class.md)\ The list of shortcuts revealed when you right click on an icon in the task bar. -[`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md)
+[`CKeyboardManager` Class](ckeyboardmanager-class.md)\ Manages shortcut key tables for the main frame window and child frame windows. -[`CKeyFrame` Class](../../mfc/reference/ckeyframe-class.md)
+[`CKeyFrame` Class](ckeyframe-class.md)\ Represents an animation keyframe. -[`CLinearTransition` Class](../../mfc/reference/clineartransition-class.md)
+[`CLinearTransition` Class](clineartransition-class.md)\ Encapsulates a linear transition. -[`CLinearTransitionFromSpeed` Class](../../mfc/reference/clineartransitionfromspeed-class.md)
+[`CLinearTransitionFromSpeed` Class](clineartransitionfromspeed-class.md)\ Encapsulates a linear-speed transition. -[`CLinkCtrl` Class](../../mfc/reference/clinkctrl-class.md)
+[`CLinkCtrl` Class](clinkctrl-class.md)\ Provides the functionality of the Windows common SysLink control. -[`CList` Class](../../mfc/reference/clist-class.md)
+[`CList` Class](clist-class.md)\ Supports ordered lists of nonunique objects accessible sequentially or by value. -[`CListBox` Class](../../mfc/reference/clistbox-class.md)
+[`CListBox` Class](clistbox-class.md)\ Provides the functionality of a Windows list box. -[`CListCtrl` Class](../../mfc/reference/clistctrl-class.md)
+[`CListCtrl` Class](clistctrl-class.md)\ Encapsulates the functionality of a "list view control," which displays a collection of items each consisting of an icon (from an image list) and a label. -[`CListView` Class](../../mfc/reference/clistview-class.md)
-Simplifies use of the list control and of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md), the class that encapsulates list-control functionality, with MFC's document-view architecture. +[`CListView` Class](clistview-class.md)\ +Simplifies use of the list control and of [`CListCtrl` Class](clistctrl-class.md), the class that encapsulates list-control functionality, with MFC's document-view architecture. -[`CLongBinary` Class](../../mfc/reference/clongbinary-class.md)
+[`CLongBinary` Class](clongbinary-class.md)\ Simplifies working with very large binary data objects (often called BLOBs, or "binary large objects") in a database. -[`CMap` Class](../../mfc/reference/cmap-class.md)
+[`CMap` Class](cmap-class.md)\ A dictionary collection class that maps unique keys to values. -[`CMapPtrToPtr` Class](../../mfc/reference/cmapptrtoptr-class.md)
+[`CMapPtrToPtr` Class](cmapptrtoptr-class.md)\ Supports maps of void pointers keyed by void pointers. -[`CMapPtrToWord` Class](../../mfc/reference/cmapptrtoword-class.md)
+[`CMapPtrToWord` Class](cmapptrtoword-class.md)\ Supports maps of 16-bit words keyed by void pointers. -[`CMapStringToOb` Class](../../mfc/reference/cmapstringtoob-class.md)
+[`CMapStringToOb` Class](cmapstringtoob-class.md)\ A dictionary collection class that maps unique `CString` objects to `CObject` pointers. -[`CMapStringToPtr` Class](../../mfc/reference/cmapstringtoptr-class.md)
+[`CMapStringToPtr` Class](cmapstringtoptr-class.md)\ Supports maps of void pointers keyed by `CString` objects. -[`CMapStringToString` Class](../../mfc/reference/cmapstringtostring-class.md)
+[`CMapStringToString` Class](cmapstringtostring-class.md)\ Supports maps of `CString` objects keyed by `CString` objects. -[`CMapWordToOb` Class](../../mfc/reference/cmapwordtoob-class.md)
+[`CMapWordToOb` Class](cmapwordtoob-class.md)\ Supports maps of `CObject` pointers keyed by 16-bit words. -[`CMapWordToPtr` Class](../../mfc/reference/cmapwordtoptr-class.md)
+[`CMapWordToPtr` Class](cmapwordtoptr-class.md)\ Supports maps of void pointers keyed by 16-bit words. -[`CMDIChildWnd` Class](../../mfc/reference/cmdichildwnd-class.md)
+[`CMDIChildWnd` Class](cmdichildwnd-class.md)\ Provides the functionality of a Windows multiple document interface (MDI) child window, along with members for managing the window. -[`CMDIChildWndEx` Class](../../mfc/reference/cmdichildwndex-class.md)
-Provides the functionality of a Windows multiple document interface (MDI) child window. It extends the functionality of [`CMDIChildWnd` Class](../../mfc/reference/cmdichildwnd-class.md). The framework requires this class when an MDI application uses certain MFC classes. +[`CMDIChildWndEx` Class](cmdichildwndex-class.md)\ +Provides the functionality of a Windows multiple document interface (MDI) child window. It extends the functionality of [`CMDIChildWnd` Class](cmdichildwnd-class.md). The framework requires this class when an MDI application uses certain MFC classes. -[`CMDIFrameWnd` Class](../../mfc/reference/cmdiframewnd-class.md)
+[`CMDIFrameWnd` Class](cmdiframewnd-class.md)\ Provides the functionality of a Windows multiple document interface (MDI) frame window, along with members for managing the window. -[`CMDIFrameWndEx` Class](../../mfc/reference/cmdiframewndex-class.md)
-Extends the functionality of [`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. +[`CMDIFrameWndEx` Class](cmdiframewndex-class.md)\ +Extends the functionality of [`CFrameWnd` Class](cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. -[`CMDITabInfo` Class](../../mfc/reference/cmditabinfo-class.md)
-Used to pass parameters to [`CMDIFrameWndEx::EnableMDITabbedGroups`](../../mfc/reference/cmdiframewndex-class.md#enablemditabbedgroups) method. Set members of this class to control the behavior of MDI tabbed groups. +[`CMDITabInfo` Class](cmditabinfo-class.md)\ +Used to pass parameters to [`CMDIFrameWndEx::EnableMDITabbedGroups`](cmdiframewndex-class.md#enablemditabbedgroups) method. Set members of this class to control the behavior of MDI tabbed groups. -[`CMemFile` Class](../../mfc/reference/cmemfile-class.md)
-The [`CFile` Class](../../mfc/reference/cfile-class.md)-derived class that supports memory files. +[`CMemFile` Class](cmemfile-class.md)\ +The [`CFile` Class](cfile-class.md)-derived class that supports memory files. -[`CMemoryException` Class](../../mfc/reference/cmemoryexception-class.md)
+[`CMemoryException` Class](cmemoryexception-class.md)\ Represents an out-of-memory exception condition. -[`CMenu` Class](../../mfc/reference/cmenu-class.md)
+[`CMenu` Class](cmenu-class.md)\ An encapsulation of the Windows `HMENU`. -[`CMenuTearOffManager` Class](../../mfc/reference/cmenutearoffmanager-class.md)
+[`CMenuTearOffManager` Class](cmenutearoffmanager-class.md)\ Manages tear-off menus. A tear-off menu is a menu on the menu bar. The user can remove a tear-off menu from the menu bar, causing the tear-off menu to float. -[`CMetaFileDC` Class](../../mfc/reference/cmetafiledc-class.md)
+[`CMetaFileDC` Class](cmetafiledc-class.md)\ Implements a Windows metafile, which contains a sequence of graphics device interface (GDI) commands that you can replay to create a desired image or text. -[`CMFCAcceleratorKey` Class](../../mfc/reference/cmfcacceleratorkey-class.md)
+[`CMFCAcceleratorKey` Class](cmfcacceleratorkey-class.md)\ Helper class that implements virtual key mapping and formatting. -[`CMFCAcceleratorKeyAssignCtrl` Class](../../mfc/reference/cmfcacceleratorkeyassignctrl-class.md)
-Extends the [`CEdit` Class](../../mfc/reference/cedit-class.md) to support extra system buttons such as ALT, CONTROL, and SHIFT. +[`CMFCAcceleratorKeyAssignCtrl` Class](cmfcacceleratorkeyassignctrl-class.md)\ +Extends the [`CEdit` Class](cedit-class.md) to support extra system buttons such as ALT, CONTROL, and SHIFT. -[`CMFCAutoHideButton` Class](../../mfc/reference/cmfcautohidebutton-class.md)
-A button that displays or hides a [`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md) that is configured to hide. +[`CMFCAutoHideButton` Class](cmfcautohidebutton-class.md)\ +A button that displays or hides a [`CDockablePane` Class](cdockablepane-class.md) that is configured to hide. -[`CMFCBaseTabCtrl` Class](../../mfc/reference/cmfcbasetabctrl-class.md)
+[`CMFCBaseTabCtrl` Class](cmfcbasetabctrl-class.md)\ Implements the base functionality for tabbed windows. -[`CMFCButton` Class](../../mfc/reference/cmfcbutton-class.md)
-Adds functionality to the [`CButton` Class](../../mfc/reference/cbutton-class.md) class such as aligning button text, combining button text and an image, selecting a cursor, and specifying a tool tip. +[`CMFCButton` Class](cmfcbutton-class.md)\ +Adds functionality to the [`CButton` Class](cbutton-class.md) class such as aligning button text, combining button text and an image, selecting a cursor, and specifying a tool tip. -[`CMFCCaptionBar` Class](../../mfc/reference/cmfccaptionbar-class.md)
+[`CMFCCaptionBar` Class](cmfccaptionbar-class.md)\ Control bar that can display three elements: a button, a text label, and a bitmap. It can only display one element of each type at a time. You can align each element to the left or right edges of the control or to the center. You can also apply a flat or 3D style to the top and bottom borders of the caption bar. -[`CMFCCaptionButton` Class](../../mfc/reference/cmfccaptionbutton-class.md)
+[`CMFCCaptionButton` Class](cmfccaptionbutton-class.md)\ Implements a button that is displayed on the caption bar for a docking pane or a mini-frame window. Typically, the framework creates caption buttons automatically. -[`CMFCColorBar` Class](../../mfc/reference/cmfccolorbar-class.md)
+[`CMFCColorBar` Class](cmfccolorbar-class.md)\ Represents a docking control bar that can select colors in a document or application. -[`CMFCColorButton` Class](../../mfc/reference/cmfccolorbutton-class.md)
-The `CMFCColorButton` and [`CMFCColorBar` Class](../../mfc/reference/cmfccolorbar-class.md) classes are used together to implement a color picker control. +[`CMFCColorButton` Class](cmfccolorbutton-class.md)\ +The `CMFCColorButton` and [`CMFCColorBar` Class](cmfccolorbar-class.md) classes are used together to implement a color picker control. -[`CMFCColorDialog` Class](../../mfc/reference/cmfccolordialog-class.md)
+[`CMFCColorDialog` Class](cmfccolordialog-class.md)\ Represents a color selection dialog box. -[`CMFCColorMenuButton` Class](../../mfc/reference/cmfccolormenubutton-class.md)
+[`CMFCColorMenuButton` Class](cmfccolormenubutton-class.md)\ Supports a menu command or a toolbar button that starts a color picker dialog box. -[`CMFCColorPickerCtrl` Class](../../mfc/reference/cmfccolorpickerctrl-class.md)
+[`CMFCColorPickerCtrl` Class](cmfccolorpickerctrl-class.md)\ Provides functionality for a control that is used to select colors. -[`CMFCDesktopAlertDialog` Class](../../mfc/reference/cmfcdesktopalertdialog-class.md)
-Used together with the [`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md) to display a custom dialog in a popup window. +[`CMFCDesktopAlertDialog` Class](cmfcdesktopalertdialog-class.md)\ +Used together with the [`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md) to display a custom dialog in a popup window. -[`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md)
+[`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md)\ Implements the functionality of a modeless dialog box which appears on the screen to inform the user about an event. -[`CMFCDesktopAlertWndInfo` Class](../../mfc/reference/cmfcdesktopalertwndinfo-class.md)
-Used with the [`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md). It specifies the controls that are displayed if the desktop alert window pops up. +[`CMFCDesktopAlertWndInfo` Class](cmfcdesktopalertwndinfo-class.md)\ +Used with the [`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md). It specifies the controls that are displayed if the desktop alert window pops up. -[`CMFCDragFrameImpl` Class](../../mfc/reference/cmfcdragframeimpl-class.md)
+[`CMFCDragFrameImpl` Class](cmfcdragframeimpl-class.md)\ Draws the drag rectangle that appears when the user drags a pane in the standard dock mode. -[`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md)
+[`CMFCDropDownToolBar` Class](cmfcdropdowntoolbar-class.md)\ A toolbar that appears when the user presses and holds a top-level toolbar button. -[`CMFCDropDownToolbarButton` Class](../../mfc/reference/cmfcdropdowntoolbarbutton-class.md)
-A type of toolbar button that behaves like a regular button when it is clicked. However, it opens a drop-down toolbar ([`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md) if the user presses and holds the toolbar button down. +[`CMFCDropDownToolbarButton` Class](cmfcdropdowntoolbarbutton-class.md)\ +A type of toolbar button that behaves like a regular button when it is clicked. However, it opens a drop-down toolbar ([`CMFCDropDownToolBar` Class](cmfcdropdowntoolbar-class.md)) if the user presses and holds the toolbar button down. -[`CMFCDynamicLayout` Class](../../mfc/reference/cmfcdynamiclayout-class.md)
+[`CMFCDynamicLayout` Class](cmfcdynamiclayout-class.md)\ Specifies how controls in a window are moved and resized as the user resizes the window. -[`CMFCEditBrowseCtrl` Class](../../mfc/reference/cmfceditbrowsectrl-class.md)
+[`CMFCEditBrowseCtrl` Class](cmfceditbrowsectrl-class.md)\ Supports the edit browse control, which is an editable text box that optionally contains a browse button. When the user clicks the browse button, the control performs a custom action or displays a standard dialog box that contains a file browser or a folder browser. -[`CMFCFilterChunkValueImpl` Class](../../mfc/reference/cmfcfilterchunkvalueimpl-class.md)
+[`CMFCFilterChunkValueImpl` Class](cmfcfilterchunkvalueimpl-class.md)\ Simplifies both chunk and property value pair logic. -[`CMFCFontComboBox` Class](../../mfc/reference/cmfcfontcombobox-class.md)
+[`CMFCFontComboBox` Class](cmfcfontcombobox-class.md)\ Creates a combo box control that contains a list of fonts. -[`CMFCFontInfo` Class](../../mfc/reference/cmfcfontinfo-class.md)
+[`CMFCFontInfo` Class](cmfcfontinfo-class.md)\ Describes the name and other attributes of a font. -[`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md)
+[`CMFCHeaderCtrl` Class](cmfcheaderctrl-class.md)\ Supports sorting multiple columns in a header control. -[`CMFCImageEditorDialog` Class](../../mfc/reference/cmfcimageeditordialog-class.md)
+[`CMFCImageEditorDialog` Class](cmfcimageeditordialog-class.md)\ Supports an image editor dialog box. -[`CMFCKeyMapDialog` Class](../../mfc/reference/cmfckeymapdialog-class.md)
+[`CMFCKeyMapDialog` Class](cmfckeymapdialog-class.md)\ Supports a control that maps commands to keys on the keyboard. -[`CMFCLinkCtrl` Class](../../mfc/reference/cmfclinkctrl-class.md)
+[`CMFCLinkCtrl` Class](cmfclinkctrl-class.md)\ Displays a button as a hyperlink and invokes the link's target when the button is clicked. -[`CMFCListCtrl` Class](../../mfc/reference/cmfclistctrl-class.md)
-Extends the functionality of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md). +[`CMFCListCtrl` Class](cmfclistctrl-class.md)\ +Extends the functionality of [`CListCtrl` Class](clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](cmfcheaderctrl-class.md). -[`CMFCMaskedEdit` Class](../../mfc/reference/cmfcmaskededit-class.md)
+[`CMFCMaskedEdit` Class](cmfcmaskededit-class.md)\ Supports a masked edit control, which validates user input against a mask and displays the validated results according to a template. -[`CMFCMenuBar` Class](../../mfc/reference/cmfcmenubar-class.md)
+[`CMFCMenuBar` Class](cmfcmenubar-class.md)\ A menu bar that implements docking. -[`CMFCMenuButton` Class](../../mfc/reference/cmfcmenubutton-class.md)
+[`CMFCMenuButton` Class](cmfcmenubutton-class.md)\ A button that displays a pop-up menu and reports on the user's menu selections. -[`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md)
-A tabbed pane with the visual appearance of the **Navigation Pane** in Microsoft Outlook 2000 or Outlook 2003. The `CMFCOutlookBar` object contains a [`CMFCOutlookBarTabCtrl` Class](../../mfc/reference/cmfcoutlookbartabctrl-class.md) object and a series of tabs. The tabs can be either [`CMFCOutlookBarPane` Class](../../mfc/reference/cmfcoutlookbarpane-class.md) objects or `CWnd`-derived objects. To the user, the Outlook bar appears as a series of buttons and a display area. When the user clicks a button, the corresponding control or button pane is displayed. +[`CMFCOutlookBar` Class](cmfcoutlookbar-class.md)\ +A tabbed pane with the visual appearance of the **Navigation Pane** in Microsoft Outlook 2000 or Outlook 2003. The `CMFCOutlookBar` object contains a [`CMFCOutlookBarTabCtrl` Class](cmfcoutlookbartabctrl-class.md) object and a series of tabs. The tabs can be either [`CMFCOutlookBarPane` Class](cmfcoutlookbarpane-class.md) objects or `CWnd`-derived objects. To the user, the Outlook bar appears as a series of buttons and a display area. When the user clicks a button, the corresponding control or button pane is displayed. -[`CMFCOutlookBarPane` Class](../../mfc/reference/cmfcoutlookbarpane-class.md)
-A control derived from [`CMFCToolBar` Class](../../mfc/reference/cmfctoolbar-class.md) that can be inserted into an Outlook bar ([`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md)). The Outlook bar pane contains a column of large buttons. The user can scroll up and down the list of buttons if it is larger than the pane. When the user detaches an Outlook bar pane from the Outlook bar, it can float or dock in the main frame window. +[`CMFCOutlookBarPane` Class](cmfcoutlookbarpane-class.md)\ +A control derived from [`CMFCToolBar` Class](cmfctoolbar-class.md) that can be inserted into an Outlook bar ([`CMFCOutlookBar` Class](cmfcoutlookbar-class.md)). The Outlook bar pane contains a column of large buttons. The user can scroll up and down the list of buttons if it is larger than the pane. When the user detaches an Outlook bar pane from the Outlook bar, it can float or dock in the main frame window. -[`CMFCOutlookBarTabCtrl` Class](../../mfc/reference/cmfcoutlookbartabctrl-class.md)
+[`CMFCOutlookBarTabCtrl` Class](cmfcoutlookbartabctrl-class.md)\ A tab control that has the visual appearance of the **Navigation Pane** in Microsoft Outlook. -[`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md)
+[`CMFCPopupMenu` Class](cmfcpopupmenu-class.md)\ Implements Windows pop-up menu functionality and extends it by adding features such as tear-off menus and tooltips. -[`CMFCPopupMenuBar` Class](../../mfc/reference/cmfcpopupmenubar-class.md)
+[`CMFCPopupMenuBar` Class](cmfcpopupmenubar-class.md)\ A menu bar embedded into a pop-up menu. -[`CMFCPreviewCtrlImpl` Class](../../mfc/reference/cmfcpreviewctrlimpl-class.md)
+[`CMFCPreviewCtrlImpl` Class](cmfcpreviewctrlimpl-class.md)\ Implements a window that is placed on a host window provided by the Shell for Rich Preview. -[`CMFCPropertyGridColorProperty` Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md)
+[`CMFCPropertyGridColorProperty` Class](cmfcpropertygridcolorproperty-class.md)\ Supports a property list control item that opens a color selection dialog box. -[`CMFCPropertyGridCtrl` Class](../../mfc/reference/cmfcpropertygridctrl-class.md)
+[`CMFCPropertyGridCtrl` Class](cmfcpropertygridctrl-class.md)\ Supports an editable property grid control that can display properties in alphabetical or hierarchical order. -[`CMFCPropertyGridFileProperty` Class](../../mfc/reference/cmfcpropertygridfileproperty-class.md)
+[`CMFCPropertyGridFileProperty` Class](cmfcpropertygridfileproperty-class.md)\ Supports a property list control item that opens a file selection dialog box. -[`CMFCPropertyGridFontProperty` Class](../../mfc/reference/cmfcpropertygridfontproperty-class.md)
+[`CMFCPropertyGridFontProperty` Class](cmfcpropertygridfontproperty-class.md)\ Supports a property list control item that opens a font selection dialog box. -[`CMFCPropertyGridProperty` Class](../../mfc/reference/cmfcpropertygridproperty-class.md)
+[`CMFCPropertyGridProperty` Class](cmfcpropertygridproperty-class.md)\ Represents a list item in a property list control. -[`CMFCPropertyPage` Class](../../mfc/reference/cmfcpropertypage-class.md)
+[`CMFCPropertyPage` Class](cmfcpropertypage-class.md)\ Supports the display of pop-up menus on a property page. -[`CMFCPropertySheet` Class](../../mfc/reference/cmfcpropertysheet-class.md)
+[`CMFCPropertySheet` Class](cmfcpropertysheet-class.md)\ Supports a property sheet where each property page is denoted by a page tab, a toolbar button, a tree control node, or a list item. -[`CMFCReBar` Class](../../mfc/reference/cmfcrebar-class.md)
+[`CMFCReBar` Class](cmfcrebar-class.md)\ Control bar that provides layout, persistence, and state information for rebar controls. -[`CMFCRibbonApplicationButton` Class](../../mfc/reference/cmfcribbonapplicationbutton-class.md)
+[`CMFCRibbonApplicationButton` Class](cmfcribbonapplicationbutton-class.md)\ Implements a special button located in the top-left corner of the application window. When clicked, the button opens a menu that usually contains common **File** commands like **Open**, **Save**, and **Exit**. -[`CMFCRibbonBaseElement` Class](../../mfc/reference/cmfcribbonbaseelement-class.md)
-Base class for all elements that you can add to a [`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md). Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes. +[`CMFCRibbonBaseElement` Class](cmfcribbonbaseelement-class.md)\ +Base class for all elements that you can add to a [`CMFCRibbonBar` Class](cmfcribbonbar-class.md). Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes. -[`CMFCRibbonButton` Class](../../mfc/reference/cmfcribbonbutton-class.md)
+[`CMFCRibbonButton` Class](cmfcribbonbutton-class.md)\ Implements buttons that you can position on ribbon bar elements such as panels, Quick Access Toolbars, and pop-up menus. -[`CMFCRibbonButtonsGroup` Class](../../mfc/reference/cmfcribbonbuttonsgroup-class.md)
+[`CMFCRibbonButtonsGroup` Class](cmfcribbonbuttonsgroup-class.md)\ Lets you organize a set of ribbon buttons into a group. All buttons in the group are directly adjacent to each other horizontally and enclosed in a border. -[`CMFCRibbonCategory` Class](../../mfc/reference/cmfcribboncategory-class.md)
-Implements a ribbon tab that contains a group of [`CMFCRibbonPanel` Class](../../mfc/reference/cmfcribbonpanel-class.md). +[`CMFCRibbonCategory` Class](cmfcribboncategory-class.md)\ +Implements a ribbon tab that contains a group of [`CMFCRibbonPanel` Class](cmfcribbonpanel-class.md). -[`CMFCRibbonCheckBox` Class](../../mfc/reference/cmfcribboncheckbox-class.md)
+[`CMFCRibbonCheckBox` Class](cmfcribboncheckbox-class.md)\ Implements a check box that you can add to a ribbon panel, Quick Access Toolbar, or popup menu. -[`CMFCRibbonColorButton` Class](../../mfc/reference/cmfcribboncolorbutton-class.md)
+[`CMFCRibbonColorButton` Class](cmfcribboncolorbutton-class.md)\ Implements a color button that you can add to a ribbon bar. The ribbon color button displays a drop-down menu that contains one or more color palettes. -[`CMFCRibbonComboBox` Class](../../mfc/reference/cmfcribboncombobox-class.md)
+[`CMFCRibbonComboBox` Class](cmfcribboncombobox-class.md)\ Implements a combo box control that you can add to a ribbon bar, a ribbon panel, or a ribbon popup menu. -[`CMFCRibbonContextCaption` Class](../../mfc/reference/cmfcribboncontextcaption-class.md)
+[`CMFCRibbonContextCaption` Class](cmfcribboncontextcaption-class.md)\ Implements a colored caption that appears at the top of a ribbon category or a context category. -[`CMFCRibbonEdit` Class](../../mfc/reference/cmfcribbonedit-class.md)
+[`CMFCRibbonEdit` Class](cmfcribbonedit-class.md)\ Implements an edit control that is positioned on a ribbon. -[`CMFCRibbonFontComboBox` Class](../../mfc/reference/cmfcribbonfontcombobox-class.md)
+[`CMFCRibbonFontComboBox` Class](cmfcribbonfontcombobox-class.md)\ Implements a combo box that contains a list of fonts. You place the combo box on a ribbon panel. -[`CMFCRibbonGallery` Class](../../mfc/reference/cmfcribbongallery-class.md)
+[`CMFCRibbonGallery` Class](cmfcribbongallery-class.md)\ Implements Office 2007-style ribbon galleries. -[`CMFCRibbonGalleryMenuButton` Class](../../mfc/reference/cmfcribbongallerymenubutton-class.md)
+[`CMFCRibbonGalleryMenuButton` Class](cmfcribbongallerymenubutton-class.md)\ Implements a ribbon menu button that contains ribbon galleries. -[`CMFCRibbonLabel` Class](../../mfc/reference/cmfcribbonlabel-class.md)
+[`CMFCRibbonLabel` Class](cmfcribbonlabel-class.md)\ Implements a non-clickable text label for a ribbon. -[`CMFCRibbonLinkCtrl` Class](../../mfc/reference/cmfcribbonlinkctrl-class.md)
+[`CMFCRibbonLinkCtrl` Class](cmfcribbonlinkctrl-class.md)\ Implements a hyperlink that is positioned on a ribbon. The hyperlink opens a Web page when you click it. -[`CMFCRibbonMainPanel` Class](../../mfc/reference/cmfcribbonmainpanel-class.md)
-Implements a ribbon panel that displays when you click the [`CMFCRibbonApplicationButton` Class](../../mfc/reference/cmfcribbonapplicationbutton-class.md). +[`CMFCRibbonMainPanel` Class](cmfcribbonmainpanel-class.md)\ +Implements a ribbon panel that displays when you click the [`CMFCRibbonApplicationButton` Class](cmfcribbonapplicationbutton-class.md). -[`CMFCRibbonMiniToolBar` Class](../../mfc/reference/cmfcribbonminitoolbar-class.md)
+[`CMFCRibbonMiniToolBar` Class](cmfcribbonminitoolbar-class.md)\ Implements a contextual popup toolbar. -[`CMFCRibbonPanel` Class](../../mfc/reference/cmfcribbonpanel-class.md)
+[`CMFCRibbonPanel` Class](cmfcribbonpanel-class.md)\ Implements a panel that contains a set of ribbon elements. When the panel is drawn, it displays as many elements as possible, given the size of the panel. -[`CMFCRibbonProgressBar` Class](../../mfc/reference/cmfcribbonprogressbar-class.md)
+[`CMFCRibbonProgressBar` Class](cmfcribbonprogressbar-class.md)\ Implements a control that visually indicates the progress of a lengthy operation. -[`CMFCRibbonSlider` Class](../../mfc/reference/cmfcribbonslider-class.md)
+[`CMFCRibbonSlider` Class](cmfcribbonslider-class.md)\ Implements a slider control that you can add to a ribbon bar or ribbon status bar. The ribbon slider control resembles the zoom sliders that appear in Office 2007 applications. -[`CMFCRibbonStatusBar` Class](../../mfc/reference/cmfcribbonstatusbar-class.md)
+[`CMFCRibbonStatusBar` Class](cmfcribbonstatusbar-class.md)\ Implements a status bar control that can display ribbon elements. -[`CMFCRibbonStatusBarPane` Class](../../mfc/reference/cmfcribbonstatusbarpane-class.md)
+[`CMFCRibbonStatusBarPane` Class](cmfcribbonstatusbarpane-class.md)\ Implements a ribbon element that you can add to a ribbon status bar. -[`CMFCRibbonUndoButton` Class](../../mfc/reference/cmfcribbonundobutton-class.md)
+[`CMFCRibbonUndoButton` Class](cmfcribbonundobutton-class.md)\ Implements a split button, a small button with a downward pointing triangle on the rightmost part of the main button. Users can click the triangle to display a drop-down list of their most recently performed actions. Users can then select one or more actions from the drop-down list. However, if the user clicks the button, only the last (the most recently added) action on the drop-down list is undone. You should populate the list with actions as the user performs them. -[`CMFCShellListCtrl` Class](../../mfc/reference/cmfcshelllistctrl-class.md)
+[`CMFCShellListCtrl` Class](cmfcshelllistctrl-class.md)\ Provides Windows list control functionality and expands it by including the ability to display a list of shell items. -[`CMFCShellTreeCtrl` Class](../../mfc/reference/cmfcshelltreectrl-class.md)
-Extends [`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md) functionality by displaying a hierarchy of Shell items. +[`CMFCShellTreeCtrl` Class](cmfcshelltreectrl-class.md)\ +Extends [`CTreeCtrl` Class](ctreectrl-class.md) functionality by displaying a hierarchy of Shell items. -[`CMFCSpinButtonCtrl` Class](../../mfc/reference/cmfcspinbuttonctrl-class.md)
+[`CMFCSpinButtonCtrl` Class](cmfcspinbuttonctrl-class.md)\ Supports a visual manager that draws a spin button control. -[`CMFCStatusBar` Class](../../mfc/reference/cmfcstatusbar-class.md)
+[`CMFCStatusBar` Class](cmfcstatusbar-class.md)\ Implements a status bar similar to the `CStatusBar` class. However, the `CMFCStatusBar` class has features not offered by the `CStatusBar` class, such as the ability to display images, animations, and progress bars; and the ability to respond to mouse double-clicks. -[`CMFCTabCtrl` Class](../../mfc/reference/cmfctabctrl-class.md)
+[`CMFCTabCtrl` Class](cmfctabctrl-class.md)\ Provides functionality for a tab control. The tab control displays a dockable window with flat or three-dimensional tabs at its top or bottom. The tabs can display text and an image and can change color when active. -[`CMFCTabToolTipInfo Structure](../../mfc/reference/cmfctabtooltipinfo-structure.md)
+[`CMFCTabToolTipInfo` Structure](cmfctabtooltipinfo-structure.md)\ Provides information about the MDI tab that the user is hovering over. -[`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md)
+[`CMFCTasksPane` Class](cmfctaskspane-class.md)\ Implements a list of clickable items (tasks). -[`CMFCTasksPaneTask` Class](../../mfc/reference/cmfctaskspanetask-class.md)
-Helper class that represents tasks for the task pane control ([`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md)). The task object represents an item in the task group ([`CMFCTasksPaneTaskGroup` Class](../../mfc/reference/cmfctaskspanetaskgroup-class.md)). Each task can have a command that the framework executes when a user clicks on the task and an icon that appears to the left of the task name. +[`CMFCTasksPaneTask` Class](cmfctaskspanetask-class.md)\ +Helper class that represents tasks for the task pane control ([`CMFCTasksPane` Class](cmfctaskspane-class.md)). The task object represents an item in the task group ([`CMFCTasksPaneTaskGroup` Class](cmfctaskspanetaskgroup-class.md)). Each task can have a command that the framework executes when a user clicks on the task and an icon that appears to the left of the task name. -[`CMFCTasksPaneTaskGroup` Class](../../mfc/reference/cmfctaskspanetaskgroup-class.md)
-Helper class used by the [`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md) control. Objects of type `CMFCTasksPaneTaskGroup` represent a *task group*. The task group is a list of items that the framework displays in a separate box that has a collapse button. The box can have an optional caption (group name). If a group is collapsed, the list of tasks is not visible. +[`CMFCTasksPaneTaskGroup` Class](cmfctaskspanetaskgroup-class.md)\ +Helper class used by the [`CMFCTasksPane` Class](cmfctaskspane-class.md) control. Objects of type `CMFCTasksPaneTaskGroup` represent a *task group*. The task group is a list of items that the framework displays in a separate box that has a collapse button. The box can have an optional caption (group name). If a group is collapsed, the list of tasks is not visible. -[`CMFCToolBar` Class](../../mfc/reference/cmfctoolbar-class.md)
-Resembles [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. +[`CMFCToolBar` Class](cmfctoolbar-class.md)\ +Resembles [`CToolBar` Class](ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. -[`CMFCToolBarImages` Class](../../mfc/reference/cmfctoolbarimages-class.md)
+[`CMFCToolBarImages` Class](cmfctoolbarimages-class.md)\ Manages toolbar images loaded from application resources or from files. -[`CMFCToolBarInfo` Class](../../mfc/reference/cmfctoolbarinfo-class.md)
-Contains the resource IDs of toolbar images in various states. `CMFCToolBarInfo` is a helper class that is used as a parameter of the [`CMFCToolBar::LoadToolBarEx`](../../mfc/reference/cmfctoolbar-class.md#loadtoolbarex) method. +[`CMFCToolBarInfo` Class](cmfctoolbarinfo-class.md)\ +Contains the resource IDs of toolbar images in various states. `CMFCToolBarInfo` is a helper class that is used as a parameter of the [`CMFCToolBar::LoadToolBarEx`](cmfctoolbar-class.md#loadtoolbarex) method. -[`CMFCToolBarMenuButton` Class](../../mfc/reference/cmfctoolbarmenubutton-class.md)
+[`CMFCToolBarMenuButton` Class](cmfctoolbarmenubutton-class.md)\ A toolbar button that contains a pop-up menu. -[`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)
-A modeless tab dialog box ([`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md)) that enables the user to customize the toolbars, menus, keyboard shortcuts, user-defined tools, and visual style in an application. Typically, the user accesses this dialog box by selecting **Customize** from the **Tools** menu. +[`CMFCToolBarsCustomizeDialog` Class](cmfctoolbarscustomizedialog-class.md)\ +A modeless tab dialog box ([`CPropertySheet` Class](cpropertysheet-class.md)) that enables the user to customize the toolbars, menus, keyboard shortcuts, user-defined tools, and visual style in an application. Typically, the user accesses this dialog box by selecting **Customize** from the **Tools** menu. -[`CMFCToolTipCtrl` Class](../../mfc/reference/cmfctooltipctrl-class.md)
-An extended tooltip implementation based on the [`CToolTipCtrl` Class](../../mfc/reference/ctooltipctrl-class.md). A tooltip based on the `CMFCToolTipCtrl` class can display an icon, a label, and a description. You can customize its visual appearance by using a gradient fill, custom text and border colors, bold text, rounded corners, or a balloon style. +[`CMFCToolTipCtrl` Class](cmfctooltipctrl-class.md)\ +An extended tooltip implementation based on the [`CToolTipCtrl` Class](ctooltipctrl-class.md). A tooltip based on the `CMFCToolTipCtrl` class can display an icon, a label, and a description. You can customize its visual appearance by using a gradient fill, custom text and border colors, bold text, rounded corners, or a balloon style. -[`CMFCToolTipInfo` Class](../../mfc/reference/cmfctooltipinfo-class.md)
+[`CMFCToolTipInfo` Class](cmfctooltipinfo-class.md)\ Stores information about the visual appearance of tooltips. -[`CMFCVisualManager` Class](../../mfc/reference/cmfcvisualmanager-class.md)
+[`CMFCVisualManager` Class](cmfcvisualmanager-class.md)\ Provides support for changing the appearance of your application at a global level. The `CMFCVisualManager` class works together with a class that provides instructions to draw the GUI controls of your application using a consistent style. These other classes are referred to as visual managers and they inherit from `CMFCBaseVisualManager`. -[`CMFCVisualManagerOffice2003` Class](../../mfc/reference/cmfcvisualmanageroffice2003-class.md)
+[`CMFCVisualManagerOffice2003` Class](cmfcvisualmanageroffice2003-class.md)\ Gives an application a Microsoft Office 2003 appearance. -[`CMFCVisualManagerOffice2007` Class](../../mfc/reference/cmfcvisualmanageroffice2007-class.md)
+[`CMFCVisualManagerOffice2007` Class](cmfcvisualmanageroffice2007-class.md)\ Gives an application a Microsoft Office 2007 appearance. -[`CMFCVisualManagerVS2005` Class](../../mfc/reference/cmfcvisualmanagervs2005-class.md)
+[`CMFCVisualManagerVS2005` Class](cmfcvisualmanagervs2005-class.md)\ Gives an application a Microsoft Visual Studio 2005 appearance. -[`CMFCVisualManagerWindows` Class](../../mfc/reference/cmfcvisualmanagerwindows-class.md)
+[`CMFCVisualManagerWindows` Class](cmfcvisualmanagerwindows-class.md)\ Mimics the appearance of Microsoft Windows XP or Microsoft Vista when the user selects a Windows XP or Vista theme. -[`CMFCVisualManagerWindows7` Class](../../mfc/reference/cmfcvisualmanagerwindows7-class.md)
+[`CMFCVisualManagerWindows7` Class](cmfcvisualmanagerwindows7-class.md)\ Gives an application the appearance of a Windows 7 application. -[`CMFCWindowsManagerDialog` Class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)
-Enables a user to manage MDI child windows in a MDI application. +[`CMFCWindowsManagerDialog` Class](cmfcwindowsmanagerdialog-class.md)\ +Enables a user to manage MDI child windows in an MDI application. -[`CMiniFrameWnd` Class](../../mfc/reference/cminiframewnd-class.md)
+[`CMiniFrameWnd` Class](cminiframewnd-class.md)\ Represents a half-height frame window typically seen around floating toolbars. -[`CMonikerFile` Class](../../mfc/reference/cmonikerfile-class.md)
+[`CMonikerFile` Class](cmonikerfile-class.md)\ Represents a stream of data ([`IStream`](/windows/win32/api/objidl/nn-objidl-istream)) named by an [`IMoniker`](/windows/win32/api/objidl/nn-objidl-imoniker). -[`CMonthCalCtrl` Class](../../mfc/reference/cmonthcalctrl-class.md)
+[`CMonthCalCtrl` Class](cmonthcalctrl-class.md)\ Encapsulates the functionality of a month calendar control. -[`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md)
-Lets a user associate different commands with a particular [`CView` Class](../../mfc/reference/cview-class.md) object when the user double-clicks inside that view. +[`CMouseManager` Class](cmousemanager-class.md)\ +Lets a user associate different commands with a particular [`CView` Class](cview-class.md) object when the user double-clicks inside that view. -[`CMultiDocTemplate` Class](../../mfc/reference/cmultidoctemplate-class.md)
+[`CMultiDocTemplate` Class](cmultidoctemplate-class.md)\ Defines a document template that implements the multiple document interface (MDI). -[`CMultiLock` Class](../../mfc/reference/cmultilock-class.md)
+[`CMultiLock` Class](cmultilock-class.md)\ Represents the access-control mechanism used in controlling access to resources in a multithreaded program. -[`CMultiPageDHtmlDialog` Class](../../mfc/reference/cmultipagedhtmldialog-class.md)
+[`CMultiPageDHtmlDialog` Class](cmultipagedhtmldialog-class.md)\ A multipage dialog displays multiple HTML pages sequentially and handles the events from each page. -[`CMultiPaneFrameWnd` Class](../../mfc/reference/cmultipaneframewnd-class.md)
-Extends [`CPaneFrameWnd` Class](../../mfc/reference/cpaneframewnd-class.md). It can support multiple panes. Instead of a single embedded handle to a control bar, `CMultiPaneFrameWnd` contains a [`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md) object that enables the user to dock one `CMultiPaneFrameWnd` to another and dynamically create multiple floating, tabbed windows. +[`CMultiPaneFrameWnd` Class](cmultipaneframewnd-class.md)\ +Extends [`CPaneFrameWnd` Class](cpaneframewnd-class.md). It can support multiple panes. Instead of a single embedded handle to a control bar, `CMultiPaneFrameWnd` contains a [`CPaneContainerManager` Class](cpanecontainermanager-class.md) object that enables the user to dock one `CMultiPaneFrameWnd` to another and dynamically create multiple floating, tabbed windows. -[`CMutex` Class](../../mfc/reference/cmutex-class.md)
+[`CMutex` Class](cmutex-class.md)\ Represents a mutex, which is a synchronization object that allows one thread mutually exclusive access to a resource. -[`CNetAddressCtrl` Class](../../mfc/reference/cnetaddressctrl-class.md)
+[`CNetAddressCtrl` Class](cnetaddressctrl-class.md)\ The `CNetAddressCtrl` class represents the network address control, which you can use to input and validate the format of IPv4, IPv6, and named DNS addresses. -[`CNotSupportedException` Class](../../mfc/reference/cnotsupportedexception-class.md)
+[`CNotSupportedException` Class](cnotsupportedexception-class.md)\ Represents an exception that is the result of a request for an unsupported feature. -[`CObArray` Class](../../mfc/reference/cobarray-class.md)
+[`CObArray` Class](cobarray-class.md)\ Supports arrays of `CObject` pointers. -[`CObject` Class](../../mfc/reference/cobject-class.md)
+[`CObject` Class](cobject-class.md)\ The principal base class for the Microsoft Foundation Class Library. -[`CObList` Class](../../mfc/reference/coblist-class.md)
+[`CObList` Class](coblist-class.md)\ Supports ordered lists of non-unique `CObject` pointers accessible sequentially or by pointer value. -[`COccManager` Class](../../mfc/reference/coccmanager-class.md)
+[`COccManager` Class](coccmanager-class.md)\ Manages various custom control sites; implemented by `COleControlContainer` and `COleControlSite` objects. -[`COleBusyDialog` Class](../../mfc/reference/colebusydialog-class.md)
+[`COleBusyDialog` Class](colebusydialog-class.md)\ Used for the OLE Server Not Responding or Server Busy dialog boxes. -[`COleChangeIconDialog` Class](../../mfc/reference/colechangeicondialog-class.md)
+[`COleChangeIconDialog` Class](colechangeicondialog-class.md)\ Used for the OLE Change Icon dialog box. -[`COleChangeSourceDialog` Class](../../mfc/reference/colechangesourcedialog-class.md)
+[`COleChangeSourceDialog` Class](colechangesourcedialog-class.md)\ Used for the OLE Change Source dialog box. -[`COleClientItem` Class](../../mfc/reference/coleclientitem-class.md)
+[`COleClientItem` Class](coleclientitem-class.md)\ Defines the container interface to OLE items. -[`COleCmdUI` Class](../../mfc/reference/colecmdui-class.md)
+[`COleCmdUI` Class](colecmdui-class.md)\ Implements a method for MFC to update the state of user-interface objects related to the `IOleCommandTarget`-driven features of your application. -[`COleControl` Class](../../mfc/reference/colecontrol-class.md)
+[`COleControl` Class](colecontrol-class.md)\ A powerful base class for developing OLE controls. -[`COleControlContainer` Class](../../mfc/reference/colecontrolcontainer-class.md)
+[`COleControlContainer` Class](colecontrolcontainer-class.md)\ Acts as a control container for ActiveX controls. -[`COleControlModule` Class](../../mfc/reference/colecontrolmodule-class.md)
+[`COleControlModule` Class](colecontrolmodule-class.md)\ The base class from which you derive an OLE control module object. -[`COleControlSite` Class](../../mfc/reference/colecontrolsite-class.md)
+[`COleControlSite` Class](colecontrolsite-class.md)\ Provides support for custom client-side control interfaces. -[`COleConvertDialog` Class](../../mfc/reference/coleconvertdialog-class.md)
+[`COleConvertDialog` Class](coleconvertdialog-class.md)\ For more information, see the [`OLEUICONVERT`](/windows/win32/api/oledlg/ns-oledlg-oleuiconvertw) structure in the Windows SDK. -[`COleCurrency` Class](../../mfc/reference/colecurrency-class.md)
+[`COleCurrency` Class](colecurrency-class.md)\ Encapsulates the `CURRENCY` data type of OLE automation. -[`COleDataObject` Class](../../mfc/reference/coledataobject-class.md)
+[`COleDataObject` Class](coledataobject-class.md)\ Used in data transfers for retrieving data in various formats from the Clipboard, through drag and drop, or from an embedded OLE item. -[`COleDataSource` Class](../../mfc/reference/coledatasource-class.md)
+[`COleDataSource` Class](coledatasource-class.md)\ Acts as a cache into which an application places the data that it will offer during data transfer operations, such as Clipboard or drag-and-drop operations. -[`COleDBRecordView` Class](../../mfc/reference/coledbrecordview-class.md)
+[`COleDBRecordView` Class](coledbrecordview-class.md)\ A view that displays database records in controls. -[`COleDialog` Class](../../mfc/reference/coledialog-class.md)
+[`COleDialog` Class](coledialog-class.md)\ Provides functionality common to dialog boxes for OLE. -[`COleDispatchDriver` Class](../../mfc/reference/coledispatchdriver-class.md)
+[`COleDispatchDriver` Class](coledispatchdriver-class.md)\ Implements the client side of OLE automation. -[`COleDispatchException` Class](../../mfc/reference/coledispatchexception-class.md)
+[`COleDispatchException` Class](coledispatchexception-class.md)\ Handles exceptions specific to the OLE `IDispatch` interface, which is a key part of OLE automation. -[`COleDocObjectItem` Class](../../mfc/reference/coledocobjectitem-class.md)
+[`COleDocObjectItem` Class](coledocobjectitem-class.md)\ Implements Active document containment. -[`COleDocument` Class](../../mfc/reference/coledocument-class.md)
+[`COleDocument` Class](coledocument-class.md)\ The base class for OLE documents that support visual editing. -[`COleDropSource` Class](../../mfc/reference/coledropsource-class.md)
+[`COleDropSource` Class](coledropsource-class.md)\ Enables data to be dragged to a drop target. -[`COleDropTarget` Class](../../mfc/reference/coledroptarget-class.md)
+[`COleDropTarget` Class](coledroptarget-class.md)\ Provides the communication mechanism between a window and the OLE libraries. -[`COleException` Class](../../mfc/reference/coleexception-class.md)
+[`COleException` Class](coleexception-class.md)\ Represents an exception condition related to an OLE operation. -[`COleInsertDialog` Class](../../mfc/reference/coleinsertdialog-class.md)
+[`COleInsertDialog` Class](coleinsertdialog-class.md)\ Used for the OLE Insert Object dialog box. -[`COleIPFrameWnd` Class](../../mfc/reference/coleipframewnd-class.md)
+[`COleIPFrameWnd` Class](coleipframewnd-class.md)\ The base for your application's in-place editing window. -[`COleIPFrameWndEx` Class](../../mfc/reference/coleipframewndex-class.md)
-Implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [`COleIPFrameWnd`](../../mfc/reference/coleipframewnd-class.md) class. +[`COleIPFrameWndEx` Class](coleipframewndex-class.md)\ +Implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [`COleIPFrameWnd`](coleipframewnd-class.md) class. -[`COleLinkingDoc` Class](../../mfc/reference/colelinkingdoc-class.md)
+[`COleLinkingDoc` Class](colelinkingdoc-class.md)\ The base class for OLE container documents that support linking to the embedded items they contain. -[`COleLinksDialog` Class](../../mfc/reference/colelinksdialog-class.md)
+[`COleLinksDialog` Class](colelinksdialog-class.md)\ Used for the OLE Edit Links dialog box. -[`COleMessageFilter` Class](../../mfc/reference/colemessagefilter-class.md)
+[`COleMessageFilter` Class](colemessagefilter-class.md)\ Manages the concurrency required by the interaction of OLE applications. -[`COleObjectFactory` Class](../../mfc/reference/coleobjectfactory-class.md)
+[`COleObjectFactory` Class](coleobjectfactory-class.md)\ Implements the OLE class factory, which creates OLE objects such as servers, automation objects, and documents. -[`COlePasteSpecialDialog` Class](../../mfc/reference/colepastespecialdialog-class.md)
+[`COlePasteSpecialDialog` Class](colepastespecialdialog-class.md)\ Used for the OLE Paste Special dialog box. -[`COlePropertiesDialog` Class](../../mfc/reference/colepropertiesdialog-class.md)
+[`COlePropertiesDialog` Class](colepropertiesdialog-class.md)\ Encapsulates the Windows common OLE Object Properties dialog box. -[`COlePropertyPage` Class](../../mfc/reference/colepropertypage-class.md)
+[`COlePropertyPage` Class](colepropertypage-class.md)\ Used to display the properties of a custom control in a graphical interface, similar to a dialog box. -[`COleResizeBar` Class](../../mfc/reference/coleresizebar-class.md)
+[`COleResizeBar` Class](coleresizebar-class.md)\ A type of control bar that supports resizing of in-place OLE items. -[`COleSafeArray` Class](../../mfc/reference/colesafearray-class.md)
+[`COleSafeArray` Class](colesafearray-class.md)\ A class for working with arrays of arbitrary type and dimension. -[`COleServerDoc` Class](../../mfc/reference/coleserverdoc-class.md)
+[`COleServerDoc` Class](coleserverdoc-class.md)\ The base class for OLE server documents. -[`COleServerItem` Class](../../mfc/reference/coleserveritem-class.md)
+[`COleServerItem` Class](coleserveritem-class.md)\ Provides the server interface to OLE items. -[`COleStreamFile` Class](../../mfc/reference/colestreamfile-class.md)
+[`COleStreamFile` Class](colestreamfile-class.md)\ Represents a stream of data (`IStream`) in a compound file as part of OLE Structured Storage. -[`COleTemplateServer` Class](../../mfc/reference/coletemplateserver-class.md)
+[`COleTemplateServer` Class](coletemplateserver-class.md)\ Used for OLE visual editing servers, automation servers, and link containers (applications that support links to embeddings). -[`COleUpdateDialog` Class](../../mfc/reference/coleupdatedialog-class.md)
+[`COleUpdateDialog` Class](coleupdatedialog-class.md)\ Used for a special case of the OLE Edit Links dialog box, which should be used when you need to update only existing linked or embedded objects in a document. -[`COleVariant` Class](../../mfc/reference/colevariant-class.md)
+[`COleVariant` Class](colevariant-class.md)\ Encapsulates the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) data type. -[`CPagerCtrl` Class](../../mfc/reference/cpagerctrl-class.md)
+[`CPagerCtrl` Class](cpagerctrl-class.md)\ The `CPagerCtrl` class wraps the Windows pager control, which can scroll into view a contained window that does not fit the containing window. -[`CPageSetupDialog` Class](../../mfc/reference/cpagesetupdialog-class.md)
+[`CPageSetupDialog` Class](cpagesetupdialog-class.md)\ Encapsulates the services provided by the Windows common OLE Page Setup dialog box with additional support for setting and modifying print margins. -[`CPaintDC` Class](../../mfc/reference/cpaintdc-class.md)
-A device-context class derived from [`CDC` Class](../../mfc/reference/cdc-class.md). +[`CPaintDC` Class](cpaintdc-class.md)\ +A device-context class derived from [`CDC` Class](cdc-class.md). -[`CPalette` Class](../../mfc/reference/cpalette-class.md)
+[`CPalette` Class](cpalette-class.md)\ Encapsulates a Windows color palette. -[`CPane` Class](../../mfc/reference/cpane-class.md)
-Enhancement of the [`CControlBar` Class](../../mfc/reference/ccontrolbar-class.md). If you are upgrading an existing MFC project, you need to replace all occurrences of `CControlBar` with `CPane`. +[`CPane` Class](cpane-class.md)\ +Enhancement of the [`CControlBar` Class](ccontrolbar-class.md). If you are upgrading an existing MFC project, you need to replace all occurrences of `CControlBar` with `CPane`. -[`CPaneContainer` Class](../../mfc/reference/cpanecontainer-class.md)
-Basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer`. It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md) object. +[`CPaneContainer` Class](cpanecontainer-class.md)\ +Basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer`. It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [`CPaneContainerManager` Class](cpanecontainermanager-class.md) object. -[`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md)
+[`CPaneContainerManager` Class](cpanecontainermanager-class.md)\ Manages the storage and display of the current docking layout. -[`CPaneDialog` Class](../../mfc/reference/cpanedialog-class.md)
+[`CPaneDialog` Class](cpanedialog-class.md)\ Supports a modeless, dockable dialog box. -[`CPaneDivider` Class](../../mfc/reference/cpanedivider-class.md)
+[`CPaneDivider` Class](cpanedivider-class.md)\ Divides two panes, divides two groups of panes, or separates a group of panes from the client area of the main frame window. -[`CPaneFrameWnd` Class](../../mfc/reference/cpaneframewnd-class.md)
+[`CPaneFrameWnd` Class](cpaneframewnd-class.md)\ Implements a mini-frame window that contains one pane. The pane fills the client area of the window. -[`CParabolicTransitionFromAcceleration` Class](../../mfc/reference/cparabolictransitionfromacceleration-class.md)
+[`CParabolicTransitionFromAcceleration` Class](cparabolictransitionfromacceleration-class.md)\ Encapsulates a parabolic-acceleration transition. -[`CPen` Class](../../mfc/reference/cpen-class.md)
+[`CPen` Class](cpen-class.md)\ Encapsulates a Windows graphics device interface (GDI) pen. -[`CPictureHolder` Class](../../mfc/reference/cpictureholder-class.md)
+[`CPictureHolder` Class](cpictureholder-class.md)\ Implements a Picture property, which lets the user display a picture in your control. -[`CPoint` Class](../../atl-mfc-shared/reference/cpoint-class.md)
+[`CPoint` Class](../../atl-mfc-shared/reference/cpoint-class.md)\ Similar to the Windows `POINT` structure. -[`CPrintDialog` Class](../../mfc/reference/cprintdialog-class.md)
+[`CPrintDialog` Class](cprintdialog-class.md)\ Encapsulates the services provided by the Windows common dialog box for printing. -[`CPrintDialogEx` Class](../../mfc/reference/cprintdialogex-class.md)
+[`CPrintDialogEx` Class](cprintdialogex-class.md)\ Encapsulates the services provided by the Windows Print property sheet. -[`CProgressCtrl` Class](../../mfc/reference/cprogressctrl-class.md)
+[`CProgressCtrl` Class](cprogressctrl-class.md)\ Provides the functionality of the Windows common progress bar control. -[`CPropertyPage` Class](../../mfc/reference/cpropertypage-class.md)
+[`CPropertyPage` Class](cpropertypage-class.md)\ Represents individual pages of a property sheet, otherwise known as a tab dialog box. -[`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md)
+[`CPropertySheet` Class](cpropertysheet-class.md)\ Represents property sheets, also known as tab dialog boxes. -[`CPropExchange` Class](../../mfc/reference/cpropexchange-class.md)
+[`CPropExchange` Class](cpropexchange-class.md)\ Supports the implementation of persistence for your OLE controls. -[`CPtrArray` Class](../../mfc/reference/cptrarray-class.md)
+[`CPtrArray` Class](cptrarray-class.md)\ Supports arrays of void pointers. -[`CPtrList` Class](../../mfc/reference/cptrlist-class.md)
+[`CPtrList` Class](cptrlist-class.md)\ Supports lists of void pointers. -[`CReBar` Class](../../mfc/reference/crebar-class.md)
+[`CReBar` Class](crebar-class.md)\ A control bar that provides layout, persistence, and state information for rebar controls. -[`CReBarCtrl` Class](../../mfc/reference/crebarctrl-class.md)
+[`CReBarCtrl` Class](crebarctrl-class.md)\ Encapsulates the functionality of a rebar control, which is a container for a child window. -[`CRecentDockSiteInfo` Class](../../mfc/reference/crecentdocksiteinfo-class.md)
-Helper class that stores recent state information for the [`CPane` Class](../../mfc/reference/cpane-class.md). +[`CRecentDockSiteInfo` Class](crecentdocksiteinfo-class.md)\ +Helper class that stores recent state information for the [`CPane` Class](cpane-class.md). -[`CRecentFileList` Class](../../mfc/reference/crecentfilelist-class.md)
+[`CRecentFileList` Class](crecentfilelist-class.md)\ Supports control of the most recently used (MRU) file list. -[`CRecordset` Class](../../mfc/reference/crecordset-class.md)
+[`CRecordset` Class](crecordset-class.md)\ Represents a set of records selected from a data source. -[`CRecordView` Class](../../mfc/reference/crecordview-class.md)
+[`CRecordView` Class](crecordview-class.md)\ A view that displays database records in controls. -[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)
+[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)\ Similar to a Windows [`RECT` structure](/windows/win32/api/windef/ns-windef-rect). -[`CRectTracker` Class](../../mfc/reference/crecttracker-class.md)
+[`CRectTracker` Class](crecttracker-class.md)\ Enables an item to be displayed, moved, and resized in different fashions. -[`CRenderTarget` Class](../../mfc/reference/crendertarget-class.md)
+[`CRenderTarget` Class](crendertarget-class.md)\ A wrapper for `ID2D1RenderTarget`. -[`CResourceException` Class](../../mfc/reference/cresourceexception-class.md)
+[`CResourceException` Class](cresourceexception-class.md)\ Generated when Windows cannot find or allocate a requested resource. -[`CReversalTransition` Class](../../mfc/reference/creversaltransition-class.md)
+[`CReversalTransition` Class](creversaltransition-class.md)\ Encapsulates a reversal transition. -[`CRgn` Class](../../mfc/reference/crgn-class.md)
+[`CRgn` Class](crgn-class.md)\ Encapsulates a Windows graphics device interface (GDI) region. -[`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md)
-With [`CRichEditView` Class](../../mfc/reference/cricheditview-class.md) and [`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditCntrItem` Class](cricheditcntritem-class.md)\ +With [`CRichEditView` Class](cricheditview-class.md) and [`CRichEditDoc` Class](cricheditdoc-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CRichEditCtrl` Class](../../mfc/reference/cricheditctrl-class.md)
+[`CRichEditCtrl` Class](cricheditctrl-class.md)\ Provides the functionality of the rich edit control. -[`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md)
-With [`CRichEditView` Class](../../mfc/reference/cricheditview-class.md) and [`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditDoc` Class](cricheditdoc-class.md)\ +With [`CRichEditView` Class](cricheditview-class.md) and [`CRichEditCntrItem` Class](cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CRichEditView` Class](../../mfc/reference/cricheditview-class.md)
-With [`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md) and [`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditView` Class](cricheditview-class.md)\ +With [`CRichEditDoc` Class](cricheditdoc-class.md) and [`CRichEditCntrItem` Class](cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CScrollBar` Class](../../mfc/reference/cscrollbar-class.md)
+[`CScrollBar` Class](cscrollbar-class.md)\ Provides the functionality of a Windows scroll-bar control. -[`CScrollView` Class](../../mfc/reference/cscrollview-class.md)
-A [`CView` Class](../../mfc/reference/cview-class.md) with scrolling capabilities. +[`CScrollView` Class](cscrollview-class.md)\ +A [`CView` Class](cview-class.md) with scrolling capabilities. -[`CSemaphore` Class](../../mfc/reference/csemaphore-class.md)
+[`CSemaphore` Class](csemaphore-class.md)\ Represents a "semaphore", which is a synchronization object that allows a limited number of threads in one or more processes to access aMaintains a count of the number of threads currently accessing a specified resource. -[`CSettingsStore` Class](../../mfc/reference/csettingsstore-class.md)
+[`CSettingsStore` Class](csettingsstore-class.md)\ Wraps Windows API functions, providing an object-oriented interface that you use to access the registry. -[`CSettingsStoreSP` Class](../../mfc/reference/csettingsstoresp-class.md)
-Helper class that you can use to create instances of the [`CSettingsStore` Class](../../mfc/reference/csettingsstore-class.md). +[`CSettingsStoreSP` Class](csettingsstoresp-class.md)\ +Helper class that you can use to create instances of the [`CSettingsStore` Class](csettingsstore-class.md). -[`CSharedFile` Class](../../mfc/reference/csharedfile-class.md)
-The [`CMemFile` Class](../../mfc/reference/cmemfile-class.md)-derived class that supports shared memory files. +[`CSharedFile` Class](csharedfile-class.md)\ +The [`CMemFile` Class](cmemfile-class.md)-derived class that supports shared memory files. -[`CShellManager` Class](../../mfc/reference/cshellmanager-class.md)
+[`CShellManager` Class](cshellmanager-class.md)\ Implements several methods that enable you to work with pointers to identifier lists (PIDLs). -[`CSimpleException` Class](../../mfc/reference/csimpleexception-class.md)
+[`CSimpleException` Class](csimpleexception-class.md)\ This class is a base class for resource-critical MFC exceptions. -[`CSingleDocTemplate` Class](../../mfc/reference/csingledoctemplate-class.md)
+[`CSingleDocTemplate` Class](csingledoctemplate-class.md)\ Defines a document template that implements the single document interface (SDI). -[`CSingleLock` Class](../../mfc/reference/csinglelock-class.md)
+[`CSingleLock` Class](csinglelock-class.md)\ Represents the access-control mechanism used in controlling access to a resource in a multithreaded program. -[`CSinusoidalTransitionFromRange` Class](../../mfc/reference/csinusoidaltransitionfromrange-class.md)
+[`CSinusoidalTransitionFromRange` Class](csinusoidaltransitionfromrange-class.md)\ Encapsulates a sinusoidal-range transition that has a given range of oscillation. -[`CSinusoidalTransitionFromVelocity` Class](../../mfc/reference/csinusoidaltransitionfromvelocity-class.md)
+[`CSinusoidalTransitionFromVelocity` Class](csinusoidaltransitionfromvelocity-class.md)\ Encapsulates a sinusoidal-velocity transition that has an amplitude that is determined by the initial velocity of the animation variable. -[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md)
+[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md)\ Similar to the Windows [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure, which implements a relative coordinate or position. -[`CSliderCtrl` Class](../../mfc/reference/csliderctrl-class.md)
+[`CSliderCtrl` Class](csliderctrl-class.md)\ Provides the functionality of the Windows common slider control. -[`CSmartDockingInfo` Class](../../mfc/reference/csmartdockinginfo-class.md)
+[`CSmartDockingInfo` Class](csmartdockinginfo-class.md)\ Defines the appearance of smart docking markers. -[`CSmoothStopTransition` Class](../../mfc/reference/csmoothstoptransition-class.md)
+[`CSmoothStopTransition` Class](csmoothstoptransition-class.md)\ Encapsulates a smooth-stop transition. -[`CSocket` Class](../../mfc/reference/csocket-class.md)
+[`CSocket` Class](csocket-class.md)\ Derives from `CAsyncSocket`, and represents a higher level of abstraction of the Windows Sockets API. -[`CSocketFile` Class](../../mfc/reference/csocketfile-class.md)
+[`CSocketFile` Class](csocketfile-class.md)\ A `CFile` object used for sending and receiving data across a network via Windows Sockets. -[`CSpinButtonCtrl` Class](../../mfc/reference/cspinbuttonctrl-class.md)
+[`CSpinButtonCtrl` Class](cspinbuttonctrl-class.md)\ Provides the functionality of the Windows common spin button control. -[`CSplitButton` Class](../../mfc/reference/csplitbutton-class.md)
+[`CSplitButton` Class](csplitbutton-class.md)\ Represents a split button control. The split button control performs a default behavior when a user clicks the main part of the button, and displays a drop-down menu when a user clicks the drop-down arrow of the button. -[`CSplitterWnd` Class](../../mfc/reference/csplitterwnd-class.md)
+[`CSplitterWnd` Class](csplitterwnd-class.md)\ Provides the functionality of a splitter window, which is a window that contains multiple panes. -[`CSplitterWndEx` Class](csplitterwndex-class.md)
+[`CSplitterWndEx` Class](csplitterwndex-class.md)\ Represents a customized splitter window. -[`CStatic` Class](../../mfc/reference/cstatic-class.md)
+[`CStatic` Class](cstatic-class.md)\ Provides the functionality of a Windows static control. -[`CStatusBar` Class](../../mfc/reference/cstatusbar-class.md)
+[`CStatusBar` Class](cstatusbar-class.md)\ A control bar with a row of text output panes, or "indicators". -[`CStatusBarCtrl` Class](../../mfc/reference/cstatusbarctrl-class.md)
+[`CStatusBarCtrl` Class](cstatusbarctrl-class.md)\ Provides the functionality of the Windows common status bar control. -[`CStdioFile` Class](../../mfc/reference/cstdiofile-class.md)
+[`CStdioFile` Class](cstdiofile-class.md)\ Represents a C run-time stream file as opened by the run-time function [`fopen`, `_wfopen`](../../c-runtime-library/reference/fopen-wfopen.md). -[`CStringArray` Class](../../mfc/reference/cstringarray-class.md)
+[`CStringArray` Class](cstringarray-class.md)\ Supports arrays of `CString` objects. -[`CStringList` Class](../../mfc/reference/cstringlist-class.md)
+[`CStringList` Class](cstringlist-class.md)\ Supports lists of `CString` objects. -[`CSyncObject` Class](../../mfc/reference/csyncobject-class.md)
+[`CSyncObject` Class](csyncobject-class.md)\ A pure virtual class that provides functionality common to the synchronization objects in Win32. -[`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md)
+[`CTabbedPane` Class](ctabbedpane-class.md)\ Implements the functionality of a pane with detachable tabs. -[`CTabCtrl` Class](../../mfc/reference/ctabctrl-class.md)
+[`CTabCtrl` Class](ctabctrl-class.md)\ Provides the functionality of the Windows common tab control. -[`CTabView` Class](../../mfc/reference/ctabview-class.md)
-Simplifies the use of the tab control class ([`CTabView` Class](../../mfc/reference/ctabview-class.md)) in applications that use MFC's document/view architecture. +[`CTabView` Class](ctabview-class.md)\ +Simplifies the use of the tab control class ([`CTabView` Class](ctabview-class.md)) in applications that use MFC's document/view architecture. -[`CTaskDialog` Class](../../mfc/reference/ctaskdialog-class.md)
+[`CTaskDialog` Class](ctaskdialog-class.md)\ A pop-up dialog box that functions like a message box but can display additional information to the user. The `CTaskDialog` also includes functionality for gathering information from the user. -[`CToolBar` Class](../../mfc/reference/ctoolbar-class.md)
+[`CToolBar` Class](ctoolbar-class.md)\ Control bars that have a row of bitmapped buttons and optional separators. -[`CToolBarCtrl` Class](../../mfc/reference/ctoolbarctrl-class.md)
+[`CToolBarCtrl` Class](ctoolbarctrl-class.md)\ Provides the functionality of the Windows toolbar common control. -[`CToolTipCtrl` Class](../../mfc/reference/ctooltipctrl-class.md)
+[`CToolTipCtrl` Class](ctooltipctrl-class.md)\ Encapsulates the functionality of a "tool tip control", a small pop-up window that displays a single line of text describing the purpose of a tool in an application. -[`CTooltipManager` Class](../../mfc/reference/ctooltipmanager-class.md)
+[`CTooltipManager` Class](ctooltipmanager-class.md)\ Maintains runtime information about tooltips. The `CTooltipManager` class is instantiated one time per application. -[`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md)
+[`CTreeCtrl` Class](ctreectrl-class.md)\ Provides the functionality of the Windows common tree view control. -[`CTreeView` Class](../../mfc/reference/ctreeview-class.md)
-Simplifies use of the tree control and of [`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md), the class that encapsulates tree-control functionality, with MFC's document-view architecture. +[`CTreeView` Class](ctreeview-class.md)\ +Simplifies use of the tree control and of [`CTreeCtrl` Class](ctreectrl-class.md), the class that encapsulates tree-control functionality, with MFC's document-view architecture. -[`CTypedPtrArray` Class](../../mfc/reference/ctypedptrarray-class.md)
+[`CTypedPtrArray` Class](ctypedptrarray-class.md)\ Provides a type-safe "wrapper" for objects of class `CPtrArray` or `CObArray`. -[`CTypedPtrList` Class](../../mfc/reference/ctypedptrlist-class.md)
+[`CTypedPtrList` Class](ctypedptrlist-class.md)\ Provides a type-safe "wrapper" for objects of class `CPtrList`. -[`CTypedPtrMap` Class](../../mfc/reference/ctypedptrmap-class.md)
+[`CTypedPtrMap` Class](ctypedptrmap-class.md)\ Provides a type-safe "wrapper" for objects of the pointer-map classes `CMapPtrToPtr`, `CMapPtrToWord`, `CMapWordToPtr`, and `CMapStringToPtr`. -[`CUIntArray` Class](../../mfc/reference/cuintarray-class.md)
+[`CUIntArray` Class](cuintarray-class.md)\ Supports arrays of unsigned integers. -[`CUserException` Class](../../mfc/reference/cuserexception-class.md)
+[`CUserException` Class](cuserexception-class.md)\ Thrown to stop an end-user operation. -[`CUserTool` Class](../../mfc/reference/cusertool-class.md)
-Menu item that runs an external application. The **Tools** tab of the **Customize** dialog box ([`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)) enables the user to add user tools, and to specify the name, command, arguments, and initial directory for each user tool. +[`CUserTool` Class](cusertool-class.md)\ +Menu item that runs an external application. The **Tools** tab of the **Customize** dialog box ([`CMFCToolBarsCustomizeDialog` Class](cmfctoolbarscustomizedialog-class.md)) enables the user to add user tools, and to specify the name, command, arguments, and initial directory for each user tool. -[`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md)
-Maintains the collection of [`CUserTool` Class](../../mfc/reference/cusertool-class.md) objects in an application. A user tool is a menu item that runs an external application. The `CUserToolsManager` object enables the user or developer to add new user tools to the application. It supports the execution of the commands associated with user tools, and it also saves information about user tools in the Windows registry. +[`CUserToolsManager` Class](cusertoolsmanager-class.md)\ +Maintains the collection of [`CUserTool` Class](cusertool-class.md) objects in an application. A user tool is a menu item that runs an external application. The `CUserToolsManager` object enables the user or developer to add new user tools to the application. It supports the execution of the commands associated with user tools, and it also saves information about user tools in the Windows registry. -[`CView` Class](../../mfc/reference/cview-class.md)
+[`CView` Class](cview-class.md)\ Provides the basic functionality for user-defined view classes. -[`CVSListBox` Class](../../mfc/reference/cvslistbox-class.md)
+[`CVSListBox` Class](cvslistbox-class.md)\ Supports an editable list control. -[`CWaitCursor` Class](../../mfc/reference/cwaitcursor-class.md)
+[`CWaitCursor` Class](cwaitcursor-class.md)\ Provides a one-line way to show a wait cursor, which is usually displayed as an hourglass, while you're doing a lengthy operation. -[`CWinApp` Class](../../mfc/reference/cwinapp-class.md)
+[`CWinApp` Class](cwinapp-class.md)\ The base class from which you derive a Windows application object. -[`CWinAppEx` Class](../../mfc/reference/cwinappex-class.md)
+[`CWinAppEx` Class](cwinappex-class.md)\ Handles the application state, saves the state to the registry, loads the state from the registry, initializes application managers, and provides links to those same application managers. -[`CWindowDC` Class](../../mfc/reference/cwindowdc-class.md)
+[`CWindowDC` Class](cwindowdc-class.md)\ Derived from `CDC`. -[`CWinFormsControl` Class](../../mfc/reference/cwinformscontrol-class.md)
+[`CWinFormsControl` Class](cwinformscontrol-class.md)\ Provides the basic functionality for hosting of a Windows Forms control. -[`CWinFormsDialog` Class](../../mfc/reference/cwinformsdialog-class.md)
+[`CWinFormsDialog` Class](cwinformsdialog-class.md)\ A wrapper for an MFC dialog class that hosts a Windows Forms user control. -[`CWinFormsView` Class](../../mfc/reference/cwinformsview-class.md)
+[`CWinFormsView` Class](cwinformsview-class.md)\ Provides generic functionality for hosting of a Windows Forms control as an MFC view. -[`CWinThread` Class](../../mfc/reference/cwinthread-class.md)
+[`CWinThread` Class](cwinthread-class.md)\ Represents a thread of execution within an application. -[`CWnd` Class](../../mfc/reference/cwnd-class.md)
+[`CWnd` Class](cwnd-class.md)\ Provides the base functionality of all window classes in the Microsoft Foundation Class Library. -[`CWordArray` Class](../../mfc/reference/cwordarray-class.md)
+[`CWordArray` Class](cwordarray-class.md)\ Supports arrays of 16-bit words. ## Related Sections -[MFC Desktop Applications](../../mfc/mfc-desktop-applications.md)
+[MFC Desktop Applications](../mfc-desktop-applications.md)\ Contains links to topics about the classes, global functions, global variables, and macros that make up the MFC Library. diff --git a/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md b/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md index ea7aadc03a..6a99fce2ec 100644 --- a/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md +++ b/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md @@ -23,3 +23,4 @@ The Microsoft Foundation Class (MFC) wizards generate boilerplate code for vario |[ATL Support in an MFC Project](../../mfc/reference/adding-atl-support-to-your-mfc-project.md)|Creates headers and macros that are required by the Active Template Library (ATL).| |[MFC Class Wizard](../../mfc/reference/mfc-class-wizard.md)|Creates an .h file and a .cpp file.| |[MFC Desktop Applications](../../mfc/mfc-desktop-applications.md)|Links to the MFC documentation.| +|[IDL MFC Method Wizard](../../mfc/reference/add-idl-mfc-method-wizard.md)| Add a method to an IDL interface in an MFC project.| \ No newline at end of file diff --git a/docs/mfc/reference/registering-ole-controls.md b/docs/mfc/reference/registering-ole-controls.md index 8de8baa13d..8dd7892cce 100644 --- a/docs/mfc/reference/registering-ole-controls.md +++ b/docs/mfc/reference/registering-ole-controls.md @@ -224,7 +224,7 @@ This function updates the registry with the type library name and its location o ### Example [!code-cpp[NVC_MFCAutomation#7](../../mfc/codesnippet/cpp/registering-ole-controls_3.cpp)] - +  [!code-cpp[NVC_MFCAutomation#8](../../mfc/codesnippet/cpp/registering-ole-controls_4.cpp)] ### Requirements diff --git a/docs/mfc/reference/run-time-object-model-services.md b/docs/mfc/reference/run-time-object-model-services.md index 4269f4e41b..b33e44f8ff 100644 --- a/docs/mfc/reference/run-time-object-model-services.md +++ b/docs/mfc/reference/run-time-object-model-services.md @@ -3,13 +3,12 @@ description: "Learn more about: Run-Time Object Model Services" title: "Run-Time Object Model Services" ms.date: "03/27/2019" helpviewer_keywords: ["run-time object model services macros"] -ms.assetid: 4a3e79df-2ee3-43a4-8193-20298828de85 --- # Run-Time Object Model Services -The classes [CObject](../../mfc/reference/cobject-class.md) and [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from `CObject` inherit this functionality. +The classes [`CObject`](../../mfc/reference/cobject-class.md) and [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from `CObject` inherit this functionality. -Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information is not supported directly by the C++ language. +Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information isn't supported directly by the C++ language. Serialization is the process of writing or reading an object's contents to or from a file. You can use serialization to store an object's contents even after the application exits. The object can then be read from the file when the application is restarted. Such data objects are said to be "persistent." @@ -17,19 +16,19 @@ Dynamic object creation enables you to create an object of a specified class at The following table lists the MFC macros that support run-time class information, serialization, and dynamic creation. -For more information on these run-time object services and serialization, see the article [CObject Class: Accessing Run-Time Class Information](../../mfc/accessing-run-time-class-information.md). +For more information on these run-time object services and serialization, see the article [`CObject` Class: Accessing Run-Time Class Information](../../mfc/accessing-run-time-class-information.md). ### Run-Time Object Model Services Macros |Name|Description| |-|-| -|[DECLARE_DYNAMIC](#declare_dynamic)|Enables access to run-time class information (must be used in the class declaration).| -|[DECLARE_DYNCREATE](#declare_dyncreate)|Enables dynamic creation and access to run-time class information (must be used in the class declaration).| -|[DECLARE_SERIAL](#declare_serial)|Enables serialization and access to run-time class information (must be used in the class declaration).| -|[IMPLEMENT_DYNAMIC](#implement_dynamic)|Enables access to run-time class information (must be used in the class implementation).| -|[IMPLEMENT_DYNCREATE](#implement_dyncreate)|Enables dynamic creation and access to run-time information (must be used in the class implementation).| -|[IMPLEMENT_SERIAL](#implement_serial)|Permits serialization and access to run-time class information (must be used in the class implementation).| -|[RUNTIME_CLASS](#runtime_class)|Returns the `CRuntimeClass` structure that corresponds to the named class.| +|[`DECLARE_DYNAMIC`](#declare_dynamic)|Enables access to run-time class information (must be used in the class declaration).| +|[`DECLARE_DYNCREATE`](#declare_dyncreate)|Enables dynamic creation and access to run-time class information (must be used in the class declaration).| +|[`DECLARE_SERIAL`](#declare_serial)|Enables serialization and access to run-time class information (must be used in the class declaration).| +|[`IMPLEMENT_DYNAMIC`](#implement_dynamic)|Enables access to run-time class information (must be used in the class implementation).| +|[`IMPLEMENT_DYNCREATE`](#implement_dyncreate)|Enables dynamic creation and access to run-time information (must be used in the class implementation).| +|[`IMPLEMENT_SERIAL`](#implement_serial)|Permits serialization and access to run-time class information (must be used in the class implementation).| +|[`RUNTIME_CLASS`](#runtime_class)|Returns the `CRuntimeClass` structure that corresponds to the named class.| OLE frequently requires the dynamic creation of objects at run time. For example, an OLE server application must be able to create OLE items dynamically in response to a request from a client. Similarly, an automation server must be able to create items in response to requests from automation clients. @@ -39,16 +38,16 @@ The Microsoft Foundation Class Library provides two macros specific to OLE. |Name|Description| |-|-| -|[AFX_COMCTL32_IF_EXISTS](#afx_comctl32_if_exists)|Determines whether the Common Controls library implements the specified API.| -|[AFX_COMCTL32_IF_EXISTS2](#afx_comctl32_if_exists2)|Determines whether the Common Controls library implements the specified API.| -|[DECLARE_OLECREATE](#declare_olecreate)|Enables objects to be created through OLE automation.| -|[DECLARE_OLECTLTYPE](#declare_olectltype)|Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| -|[DECLARE_PROPPAGEIDS](#declare_proppageids)|Declares that the OLE control provides a list of property pages to display its properties.| -|[IMPLEMENT_OLECREATE](#implement_olecreate)|Enables objects to be created by the OLE system.| -|[IMPLEMENT_OLECTLTYPE](#implement_olectltype)|Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| -|[IMPLEMENT_OLECREATE_FLAGS](#implement_olecreate_flags)|Either this macro or [IMPLEMENT_OLECREATE](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. | +|[`AFX_COMCTL32_IF_EXISTS`](#afx_comctl32_if_exists)|Determines whether the Common Controls library implements the specified API.| +|[`AFX_COMCTL32_IF_EXISTS2`](#afx_comctl32_if_exists2)|Determines whether the Common Controls library implements the specified API.| +|[`DECLARE_OLECREATE`](#declare_olecreate)|Enables objects to be created through OLE automation.| +|[`DECLARE_OLECTLTYPE`](#declare_olectltype)|Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| +|[`DECLARE_PROPPAGEIDS`](#declare_proppageids)|Declares that the OLE control provides a list of property pages to display its properties.| +|[`IMPLEMENT_OLECREATE`](#implement_olecreate)|Enables objects to be created by the OLE system.| +|[`IMPLEMENT_OLECTLTYPE`](#implement_olectltype)|Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class.| +|[`IMPLEMENT_OLECREATE_FLAGS`](#implement_olecreate_flags)|Either this macro or [`IMPLEMENT_OLECREATE`](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. | -## AFX_COMCTL32_IF_EXISTS +## `AFX_COMCTL32_IF_EXISTS` Determines whether the Common Controls library implements the specified API. @@ -60,20 +59,20 @@ AFX_COMCTL32_IF_EXISTS( proc ); ### Parameters -*proc*
+*`proc`*\ Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. ### Remarks -Use this macro to determine whether the Common Controls library the function specified by *proc* (instead of calling [GetProcAddress](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). +Use this macro to determine whether the Common Controls library the function specified by *`proc`* (instead of calling [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). ### Requirements -afxcomctl32.h, afxcomctl32.inl +`afxcomctl32.h`, `afxcomctl32.inl` -## AFX_COMCTL32_IF_EXISTS2 +## `AFX_COMCTL32_IF_EXISTS2` -Determines whether the Common Controls library implements the specified API (this is the Unicode version of [AFX_COMCTL32_IF_EXISTS](#afx_comctl32_if_exists)). +Determines whether the Common Controls library implements the specified API (this is the Unicode version of [`AFX_COMCTL32_IF_EXISTS`](#afx_comctl32_if_exists)). ### Syntax @@ -83,18 +82,18 @@ AFX_COMCTL32_IF_EXISTS2( proc ); ### Parameters -*proc*
+*`proc`*\ Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode. ### Remarks -Use this macro to determine whether the Common Controls library the function specified by *proc* (instead of calling [GetProcAddress](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). This macro is the Unicode version of AFX_COMCTL32_IF_EXISTS. +Use this macro to determine whether the Common Controls library the function specified by *`proc`* (instead of calling [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress). This macro is the Unicode version of `AFX_COMCTL32_IF_EXISTS`. ### Requirements -afxcomctl32.h, afxcomctl32.inl +`afxcomctl32.h`, `afxcomctl32.inl` -## DECLARE_DYNAMIC +## `DECLARE_DYNAMIC` Adds the ability to access run-time information about an object's class when deriving a class from `CObject`. @@ -104,28 +103,28 @@ DECLARE_DYNAMIC(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks -Add the DECLARE_DYNAMIC macro to the header (.h) module for the class, then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_DYNAMIC` macro to the header (`.h`) module for the class, then include that module in all `.cpp` modules that need access to objects of this class. -If you use the DECLARE_ DYNAMIC and IMPLEMENT_DYNAMIC macros as described, you can then use the RUNTIME_CLASS macro and the `CObject::IsKindOf` function to determine the class of your objects at run time. +If you use the `DECLARE_DYNAMIC` and `IMPLEMENT_DYNAMIC` macros as described, you can then use the `RUNTIME_CLASS` macro and the `CObject::IsKindOf` function to determine the class of your objects at run time. -If DECLARE_DYNAMIC is included in the class declaration, then IMPLEMENT_DYNAMIC must be included in the class implementation. +If `DECLARE_DYNAMIC` is included in the class declaration, then `IMPLEMENT_DYNAMIC` must be included in the class implementation. -For more information on the DECLARE_DYNAMIC macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_DYNAMIC` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example -See the example for [IMPLEMENT_DYNAMIC](#implement_dynamic). +See the example for [`IMPLEMENT_DYNAMIC`](#implement_dynamic). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_DYNCREATE +## `DECLARE_DYNCREATE` Enables objects of `CObject`-derived classes to be created dynamically at run time. @@ -135,31 +134,31 @@ DECLARE_DYNCREATE(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks The framework uses this ability to create new objects dynamically. For example, the new view created when you open a new document. Document, view, and frame classes should support dynamic creation because the framework needs to create them dynamically. -Add the DECLARE_DYNCREATE macro in the .h module for the class, then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_DYNCREATE` macro in the `.h` module for the class, then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation. +If `DECLARE_DYNCREATE` is included in the class declaration, then `IMPLEMENT_DYNCREATE` must be included in the class implementation. -For more information on the DECLARE_DYNCREATE macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_DYNCREATE` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). > [!NOTE] -> The DECLARE_DYNCREATE macro includes all the functionality of DECLARE_DYNAMIC. +> The `DECLARE_DYNCREATE` macro includes all the functionality of `DECLARE_DYNAMIC`. ### Example -See the example for [IMPLEMENT_DYNCREATE](#implement_dyncreate). +See the example for [`IMPLEMENT_DYNCREATE`](#implement_dyncreate). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_OLECTLTYPE +## `DECLARE_OLECTLTYPE` Declares the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class. @@ -171,18 +170,18 @@ DECLARE_OLECTLTYPE( class_name ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class. ### Remarks -`GetUserTypeNameID` and `GetMiscStatus` are pure virtual functions, declared in `COleControl`. Because these functions are pure virtual, they must be overridden in your control class. In addition to DECLARE_OLECTLTYPE, you must add the IMPLEMENT_OLECTLTYPE macro to your control class declaration. +`GetUserTypeNameID` and `GetMiscStatus` are pure virtual functions, declared in `COleControl`. Because these functions are pure virtual, they must be overridden in your control class. In addition to `DECLARE_OLECTLTYPE`, you must add the `IMPLEMENT_OLECTLTYPE` macro to your control class declaration. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## DECLARE_PROPPAGEIDS +## `DECLARE_PROPPAGEIDS` Declares that the OLE control provides a list of property pages to display its properties. @@ -194,20 +193,20 @@ DECLARE_PROPPAGEIDS( class_name ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class that owns the property pages. ### Remarks -Use the `DECLARE_PROPPAGEIDS` macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the `BEGIN_PROPPAGEIDS` macro, macro entries for each of your control's property pages, and the `END_PROPPAGEIDS` macro to declare the end of the property page list. +Use the `DECLARE_PROPPAGEIDS` macro at the end of your class declaration. Then, in the `.cpp` file that defines the member functions for the class, use the `BEGIN_PROPPAGEIDS` macro, macro entries for each of your control's property pages, and the `END_PROPPAGEIDS` macro to declare the end of the property page list. For more information on property pages, see the article [ActiveX Controls: Property Pages](../mfc-activex-controls-property-pages.md). ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## DECLARE_SERIAL +## `DECLARE_SERIAL` Generates the C++ header code necessary for a `CObject`-derived class that can be serialized. @@ -217,24 +216,24 @@ DECLARE_SERIAL(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks Serialization is the process of writing or reading the contents of an object to and from a file. -Use the DECLARE_SERIAL macro in an .h module, and then include that module in all .cpp modules that need access to objects of this class. +Use the `DECLARE_SERIAL` macro in an `.h` module, and then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_SERIAL is included in the class declaration, then IMPLEMENT_SERIAL must be included in the class implementation. +If `DECLARE_SERIAL` is included in the class declaration, then `IMPLEMENT_SERIAL` must be included in the class implementation. -The DECLARE_SERIAL macro includes all the functionality of DECLARE_DYNAMIC and DECLARE_DYNCREATE. +The `DECLARE_SERIAL` macro includes all the functionality of `DECLARE_DYNAMIC` and `DECLARE_DYNCREATE`. -You can use the AFX_API macro to automatically export the `CArchive` extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code: +You can use the `AFX_API` macro to automatically export the `CArchive` extraction operator for classes that use the `DECLARE_SERIAL` and `IMPLEMENT_SERIAL` macros. Bracket the class declarations (located in the `.h` file) with the following code: [!code-cpp[NVC_MFCCObjectSample#20](../../mfc/codesnippet/cpp/run-time-object-model-services_1.h)] -For more information on the DECLARE_SERIAL macro, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information on the `DECLARE_SERIAL` macro, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -242,9 +241,9 @@ For more information on the DECLARE_SERIAL macro, see [CObject Class Topics](../ ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_DYNAMIC +## `IMPLEMENT_DYNAMIC` Generates the C++ code necessary for a dynamic `CObject`-derived class with run-time access to the class name and position within the hierarchy. @@ -254,31 +253,31 @@ IMPLEMENT_DYNAMIC(class_name, base_class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The name of the base class. ### Remarks -Use the IMPLEMENT_DYNAMIC macro in a .cpp module, and then link the resulting object code only once. +Use the `IMPLEMENT_DYNAMIC` macro in a `.cpp` module, and then link the resulting object code only once. -For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example [!code-cpp[NVC_MFCCObjectSample#2](../../mfc/codesnippet/cpp/run-time-object-model-services_3.h)] - +  [!code-cpp[NVC_MFCCObjectSample#3](../../mfc/codesnippet/cpp/run-time-object-model-services_4.cpp)] ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_DYNCREATE +## `IMPLEMENT_DYNCREATE` -Enables objects of `CObject`-derived classes to be created dynamically at run time when used with the DECLARE_DYNCREATE macro. +Enables objects of `CObject`-derived classes to be created dynamically at run time when used with the `DECLARE_DYNCREATE` macro. ``` IMPLEMENT_DYNCREATE(class_name, base_class_name) @@ -286,35 +285,35 @@ IMPLEMENT_DYNCREATE(class_name, base_class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The actual name of the base class. ### Remarks -The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the IMPLEMENT_DYNCREATE macro in the class implementation file. For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the `IMPLEMENT_DYNCREATE` macro in the class implementation file. For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). -If you use the DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE macros, you can then use the RUNTIME_CLASS macro and the `CObject::IsKindOf` member function to determine the class of your objects at run time. +If you use the `DECLARE_DYNCREATE` and `IMPLEMENT_DYNCREATE` macros, you can then use the `RUNTIME_CLASS` macro and the `CObject::IsKindOf` member function to determine the class of your objects at run time. -If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation. +If `DECLARE_DYNCREATE` is included in the class declaration, then `IMPLEMENT_DYNCREATE` must be included in the class implementation. Note that this macro definition will invoke the default constructor for your class. If a non-trivial constructor is explicitly implemented by the class, it must also explicitly implement the default constructor as well. The default constructor can be added to the class's **`private`** or **`protected`** member sections to prevent it from being called from outside the class implementation. ### Example [!code-cpp[NVC_MFCCObjectSample#22](../../mfc/codesnippet/cpp/run-time-object-model-services_5.h)] - +  [!code-cpp[NVC_MFCCObjectSample#23](../../mfc/codesnippet/cpp/run-time-object-model-services_6.cpp)] ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## IMPLEMENT_OLECREATE_FLAGS +## `IMPLEMENT_OLECREATE_FLAGS` -Either this macro or [IMPLEMENT_OLECREATE](#implement_olecreate) must appear in the implementation file for any class that uses DECLARE_OLECREATE. +Either this macro or [`IMPLEMENT_OLECREATE`](#implement_olecreate) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. ### Syntax @@ -325,38 +324,38 @@ IMPLEMENT_OLECREATE_FLAGS( class_name, external_name, nFlags, ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*external_name*
+*`external_name`*\ The object name exposed to other applications (enclosed in quotation marks). -*nFlags*
+*`nFlags`*\ Contains one or more of the following flags: - `afxRegInsertable` Allows the control to appear in the Insert Object dialog box for OLE objects. -- `afxRegApartmentThreading` Sets the threading model in the registry to ThreadingModel=Apartment. -- `afxRegFreeThreading` Sets the threading model in the registry to ThreadingModel=Free. +- `afxRegApartmentThreading` Sets the threading model in the registry to `ThreadingModel=Apartment`. +- `afxRegFreeThreading` Sets the threading model in the registry to `ThreadingModel=Free`. -You can combine the two flags `afxRegApartmentThreading` and `afxRegFreeThreading` to set ThreadingModel=Both. See [InprocServer32](/windows/win32/com/inprocserver32) in the Windows SDK for more information on threading model registration. +You can combine the two flags `afxRegApartmentThreading` and `afxRegFreeThreading` to set ThreadingModel=Both. See [`InprocServer32`](/windows/win32/com/inprocserver32) in the Windows SDK for more information on threading model registration. -*l*, *w1*, *w2*, *b1*, *b2*, *b3*, *b4*, *b5*, *b6*, *b7*, *b8* +*`l`*, *`w1`*, *`w2`*, *`b1`*, *`b2`*, *`b3`*, *`b4`*, *`b5`*, *`b6`*, *`b7`*, *`b8`* Components of the class's CLSID. ### Remarks > [!NOTE] -> If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the *nFlags* parameter. If you want to support only the single-treading model, use IMPLEMENT_OLECREATE. +> If you use `IMPLEMENT_OLECREATE_FLAGS`, you can specify which threading model your object supports by using the *`nFlags`* parameter. If you want to support only the single-treading model, use `IMPLEMENT_OLECREATE`. The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server. -The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **WORD**s, and eight **BYTE**s, as represented by *l*, *w1*, *w2*, and *b1* through *b8* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. +The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **`WORD`**s, and eight **`BYTE`**s, as represented by *`l`*, *`w1`*, *`w2`*, and *`b1`* through *`b8`* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. ### Requirements -**Header:** afxdisp.h +**Header:** `afxdisp.h` -## IMPLEMENT_OLECTLTYPE +## `IMPLEMENT_OLECTLTYPE` Implements the `GetUserTypeNameID` and `GetMiscStatus` member functions of your control class. @@ -368,29 +367,29 @@ DECLARE_OLECTLTYPE( class_name, idsUserTypeName, dwOleMisc ) ### Parameters -*class_name*
+*`class_name`*\ The name of the control class. -*idsUserTypeName*
+*`idsUserTypeName`*\ The resource ID of a string containing the external name of the control. -*dwOleMisc*
-An enumeration containing one or more flags. For more information on this enumeration, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. +*`dwOleMisc`*\ +An enumeration containing one or more flags. For more information on this enumeration, see [`OLEMISC`](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. ### Remarks -In addition to IMPLEMENT_OLECTLTYPE, you must add the DECLARE_OLECTLTYPE macro to your control class declaration. +In addition to `IMPLEMENT_OLECTLTYPE`, you must add the `DECLARE_OLECTLTYPE` macro to your control class declaration. -The `GetUserTypeNameID` member function returns the resource string that identifies your control class. `GetMiscStatus` returns the OLEMISC bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the OLEMISC settings, see [OLEMISC](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. +The `GetUserTypeNameID` member function returns the resource string that identifies your control class. `GetMiscStatus` returns the `OLEMISC` bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the `OLEMISC` settings, see [`OLEMISC`](/windows/win32/api/oleidl/ne-oleidl-olemisc) in the Windows SDK. > [!NOTE] -> The default settings used by the ActiveX ControlWizard are: OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_INSIDEOUT, OLEMISC_CANTLINKINSIDE, and OLEMISC_RECOMPOSEONRESIZE. +> The default settings used by the ActiveX ControlWizard are: `OLEMISC_ACTIVATEWHENVISIBLE`, `OLEMISC_SETCLIENTSITEFIRST`, `OLEMISC_INSIDEOUT`, `OLEMISC_CANTLINKINSIDE`, and `OLEMISC_RECOMPOSEONRESIZE`. ### Requirements -**Header:** afxctl.h +**Header:** `afxctl.h` -## IMPLEMENT_SERIAL +## `IMPLEMENT_SERIAL` Generates the C++ code necessary for a dynamic `CObject`-derived class with run-time access to the class name and position within the hierarchy. @@ -400,24 +399,24 @@ IMPLEMENT_SERIAL(class_name, base_class_name, wSchema) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*base_class_name*
+*`base_class_name`*\ The name of the base class. -*wSchema*
+*`wSchema`*\ A UINT "version number" that will be encoded in the archive to enable a deserializing program to identify and handle data created by earlier program versions. The class schema number must not be -1. ### Remarks -Use the IMPLEMENT_SERIAL macro in a .cpp module; then link the resulting object code only once. +Use the `IMPLEMENT_SERIAL` macro in a `.cpp` module; then link the resulting object code only once. -You can use the AFX_API macro to automatically export the `CArchive` extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code: +You can use the `AFX_API` macro to automatically export the `CArchive` extraction operator for classes that use the `DECLARE_SERIAL` and `IMPLEMENT_SERIAL` macros. Bracket the class declarations (located in the `.h` file) with the following code: [!code-cpp[NVC_MFCCObjectSample#20](../../mfc/codesnippet/cpp/run-time-object-model-services_1.h)] -For more information, see the [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see the [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -425,9 +424,9 @@ For more information, see the [CObject Class Topics](../../mfc/using-cobject.md) ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## RUNTIME_CLASS +## `RUNTIME_CLASS` Gets the run-time class structure from the name of a C++ class. @@ -437,14 +436,14 @@ RUNTIME_CLASS(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class (not enclosed in quotation marks). ### Remarks -RUNTIME_CLASS returns a pointer to a [CRuntimeClass](../../mfc/reference/cruntimeclass-structure.md) structure for the class specified by *class_name*. Only `CObject`-derived classes declared with DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL will return pointers to a `CRuntimeClass` structure. +`RUNTIME_CLASS` returns a pointer to a [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) structure for the class specified by *`class_name`*. Only `CObject`-derived classes declared with `DECLARE_DYNAMIC`, `DECLARE_DYNCREATE`, or `DECLARE_SERIAL` will return pointers to a `CRuntimeClass` structure. -For more information, see [CObject Class Topics](../../mfc/using-cobject.md). +For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example @@ -452,9 +451,9 @@ For more information, see [CObject Class Topics](../../mfc/using-cobject.md). ### Requirements -**Header:** afx.h +**Header:** `afx.h` -## DECLARE_OLECREATE +## `DECLARE_OLECREATE` Enables objects of `CCmdTarget`-derived classes to be created through OLE automation. @@ -464,24 +463,24 @@ DECLARE_OLECREATE(class_name) ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. ### Remarks This macro enables other OLE-enabled applications to create objects of this type. -Add the DECLARE_OLECREATE macro in the .h module for the class, and then include that module in all .cpp modules that need access to objects of this class. +Add the `DECLARE_OLECREATE` macro in the `.h` module for the class, and then include that module in all `.cpp` modules that need access to objects of this class. -If DECLARE_OLECREATE is included in the class declaration, then IMPLEMENT_OLECREATE must be included in the class implementation. A class declaration using DECLARE_OLECREATE must also use DECLARE_DYNCREATE or DECLARE_SERIAL. +If `DECLARE_OLECREATE` is included in the class declaration, then `IMPLEMENT_OLECREATE` must be included in the class implementation. A class declaration using `DECLARE_OLECREATE` must also use `DECLARE_DYNCREATE` or `DECLARE_SERIAL`. ### Requirements -**Header**: afxdisp.h +**Header**: `afxdisp.h` -## IMPLEMENT_OLECREATE +## `IMPLEMENT_OLECREATE` -Either this macro or [IMPLEMENT_OLECREATE_FLAGS](#implement_olecreate_flags) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. +Either this macro or [`IMPLEMENT_OLECREATE_FLAGS`](#implement_olecreate_flags) must appear in the implementation file for any class that uses `DECLARE_OLECREATE`. ``` IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) @@ -489,30 +488,30 @@ IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6 ### Parameters -*class_name*
+*`class_name`*\ The actual name of the class. -*external_name*
+*`external_name`*\ The object name exposed to other applications (enclosed in quotation marks). -*l*, *w1*, *w2*, *b1*, *b2*, *b3*, *b4*, *b5*, *b6*, *b7*, *b8* +*`l`*, *`w1`*, *`w2`*, *`b1`*, *`b2`*, *`b3`*, *`b4`*, *`b5`*, *`b6`*, *`b7`*, *`b8`* Components of the class's CLSID. ### Remarks > [!NOTE] -> If you use IMPLEMENT_OLECREATE, by default, you support only the single threading model. If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the *nFlags* parameter. +> If you use `IMPLEMENT_OLECREATE`, by default, you support only the single threading model. If you use `IMPLEMENT_OLECREATE_FLAGS`, you can specify which threading model your object supports by using the *`nFlags`* parameter. The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server. -The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **WORD**s, and eight **BYTE**s, as represented by *l*, *w1*, *w2*, and *b1* through *b8* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. +The OLE class ID is a unique 128-bit identifier for the object. It consists of one **`long`**, two **`WORD`**s, and eight **`BYTE`**s, as represented by *`l`*, *`w1`*, *`w2`*, and *`b1`* through *`b8`* in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required. ### Requirements -**Header**: afxdisp.h +**Header**: `afxdisp.h` ## See also -[Macros and Globals](mfc-macros-and-globals.md)
-[Isolation of the MFC Common Controls Library](../isolation-of-the-mfc-common-controls-library.md)
+[Macros and Globals](mfc-macros-and-globals.md)\ +[Isolation of the MFC Common Controls Library](../isolation-of-the-mfc-common-controls-library.md)\ [CLSID Key](/windows/win32/com/clsid-key-hklm) diff --git a/docs/mfc/reference/standard-dialog-data-exchange-routines.md b/docs/mfc/reference/standard-dialog-data-exchange-routines.md index 441a31f462..0af24a8c46 100644 --- a/docs/mfc/reference/standard-dialog-data-exchange-routines.md +++ b/docs/mfc/reference/standard-dialog-data-exchange-routines.md @@ -3,39 +3,38 @@ description: "Learn more about: Standard Dialog Data Exchange Routines" title: "Standard Dialog Data Exchange Routines" ms.date: "11/04/2016" helpviewer_keywords: ["standard dialog, data exchange routines"] -ms.assetid: c6adb7f3-f9af-4cc5-a9ea-315c5b60ad1a --- # Standard Dialog Data Exchange Routines This topic lists the standard dialog data exchange (DDX) routines used for common MFC dialog controls. > [!NOTE] -> The standard dialog data exchange routines are defined in the header file afxdd_.h. However, applications should include afxwin.h. +> The standard dialog data exchange routines are defined in the header file `afxdd_.h`. However, applications should include `afxwin.h`. ### DDX Functions |Name|Description| |-|-| -|[DDX_CBIndex](#ddx_cbindex)|Initializes or retrieves the index of the current selection of a combo box control.| -|[DDX_CBString](#ddx_cbstring)|Initializes or retrieves the current contents of the edit field of a combo box control.| -|[DDX_CBStringExact](#ddx_cbstringexact)|Initializes or retrieves the current contents of the edit field of a combo box control.| -|[DDX_Check](#ddx_check)|Initializes or retrieves the current state of a check box control.| -|[DDX_Control](#ddx_control)|Subclasses a given control within a dialog box.| -|[DDX_DateTimeCtrl](#ddx_datetimectrl)|Initializes or retrieves date and/or time data of a date and time picker control.| -|[DDX_IPAddress](#ddx_ipaddress)|Initializes or retrieves the current value of an IP address control.| -|[DDX_LBIndex](#ddx_lbindex)|Initializes or retrieves the index of the current selection of a list box control.| -|[DDX_LBString](#ddx_lbstring)|Initializes or retrieves the current selection within a list box control.| -|[DDX_LBStringExact](#ddx_lbstringexact)|Initializes or retrieves the current selection within a list box control.| -|[DDX_ManagedControl](#ddx_managedcontrol)|Creates a .NET control matching the control's resource ID.| -|[DDX_MonthCalCtrl](#ddx_monthcalctrl)|Initializes or retrieves the current value of a month calendar control.| -|[DDX_Radio](#ddx_radio)|Initializes or retrieves the 0-based index of the radio control that is currently checked within a radio control group.| -|[DDX_Scroll](#ddx_scroll)|Initializes or retrieves the current position of a scroll control's thumb.| -|[DDX_Slider](#ddx_slider)|Initializes or retrieves the current position of a slider control's thumb.| -|[DDX_Text](#ddx_text)|Initializes or retrieves the current value of an edit control.| - -## DDX_CBIndex - -The `DDX_CBIndex` function manages the transfer of **`int`** data between a combo box control in a dialog box, form view, or control view object and a **`int`** data member of the dialog box, form view, or control view object. +|[`DDX_CBIndex`](#ddx_cbindex)|Initializes or retrieves the index of the current selection of a combo box control.| +|[`DDX_CBString`](#ddx_cbstring)|Initializes or retrieves the current contents of the edit field of a combo box control.| +|[`DDX_CBStringExact`](#ddx_cbstringexact)|Initializes or retrieves the current contents of the edit field of a combo box control.| +|[`DDX_Check`](#ddx_check)|Initializes or retrieves the current state of a check box control.| +|[`DDX_Control`](#ddx_control)|Subclasses a given control within a dialog box.| +|[`DDX_DateTimeCtrl`](#ddx_datetimectrl)|Initializes or retrieves date and/or time data of a date and time picker control.| +|[`DDX_IPAddress`](#ddx_ipaddress)|Initializes or retrieves the current value of an IP address control.| +|[`DDX_LBIndex`](#ddx_lbindex)|Initializes or retrieves the index of the current selection of a list box control.| +|[`DDX_LBString`](#ddx_lbstring)|Initializes or retrieves the current selection within a list box control.| +|[`DDX_LBStringExact`](#ddx_lbstringexact)|Initializes or retrieves the current selection within a list box control.| +|[`DDX_ManagedControl`](#ddx_managedcontrol)|Creates a .NET control matching the control's resource ID.| +|[`DDX_MonthCalCtrl`](#ddx_monthcalctrl)|Initializes or retrieves the current value of a month calendar control.| +|[`DDX_Radio`](#ddx_radio)|Initializes or retrieves the 0-based index of the radio control that is currently checked within a radio control group.| +|[`DDX_Scroll`](#ddx_scroll)|Initializes or retrieves the current position of a scroll control's thumb.| +|[`DDX_Slider`](#ddx_slider)|Initializes or retrieves the current position of a slider control's thumb.| +|[`DDX_Text`](#ddx_text)|Initializes or retrieves the current value of an edit control.| + +## `DDX_CBIndex` + +The `DDX_CBIndex` function manages the transfer of **`int`** data between a combo box control in a dialog box, form view, or control view object and an **`int`** data member of the dialog box, form view, or control view object. ```cpp void AFXAPI DDX_CBIndex( @@ -46,26 +45,26 @@ void AFXAPI DDX_CBIndex( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the combo box control associated with the control property. -*index*
+*`index`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_CBIndex` is called, *index* is set to the index of the current combo box selection. If no item is selected, *index* is set to 0. +When `DDX_CBIndex` is called, *`index`* is set to the index of the current combo box selection. If no item is selected, *`index`* is set to 0. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_CBString +## `DDX_CBString` The `DDX_CBString` function manages the transfer of `CString` data between the edit control of a combo box control in a dialog box, form view, or control view object and a `CString` data member of the dialog box, form view, or control view object. @@ -78,18 +77,18 @@ void AFXAPI DDX_CBString( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the combo box control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_CBString` is called, *value* is set to the current combo box selection. If no item is selected, *value* is set to a string of zero length. +When `DDX_CBString` is called, *`value`* is set to the current combo box selection. If no item is selected, *`value`* is set to a string of zero length. > [!NOTE] > If the combo box is a drop-down list box, the value exchanged is limited to 255 characters. @@ -98,9 +97,9 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_CBStringExact +## `DDX_CBStringExact` The `DDX_CBStringExact` function manages the transfer of `CString` data between the edit control of a combo box control in a dialog box, form view, or control view object and a `CString` data member of the dialog box, form view, or control view object. @@ -113,18 +112,18 @@ void AFXAPI DDX_CBStringExact( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the combo box control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_CBStringExact` is called, *value* is set to the current combo box selection. If no item is selected, *value* is set to a string of zero length. +When `DDX_CBStringExact` is called, *`value`* is set to the current combo box selection. If no item is selected, *`value`* is set to a string of zero length. > [!NOTE] > If the combo box is a drop-down list box, the value exchanged is limited to 255 characters. @@ -133,9 +132,9 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Check +## `DDX_Check` The `DDX_Check` function manages the transfer of **`int`** data between a check box control in a dialog box, form view, or control view object and a **`int`** data member of the dialog box, form view, or control view object. @@ -148,28 +147,28 @@ void AFXAPI DDX_Check( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the check box control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_Check` is called, *value* is set to the current state of the check box control. For a list of the possible state values, see [BM_GETCHECK](/windows/win32/Controls/bm-getcheck) in the Windows SDK. +When `DDX_Check` is called, *`value`* is set to the current state of the check box control. For a list of the possible state values, see [`BM_GETCHECK`](/windows/win32/Controls/bm-getcheck) in the Windows SDK. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Control +## `DDX_Control` -The `DDX_Control` function subclasses the control, specified by *nIDC*, of the dialog box, form view, or control view object. +The `DDX_Control` function subclasses the control, specified by *`nIDC`*, of the dialog box, form view, or control view object. ```cpp void AFXAPI DDX_Control( @@ -180,28 +179,28 @@ void AFXAPI DDX_Control( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. -*nIDC*
+*`nIDC`*\ The resource ID of the control to be subclassed. -*rControl*
+*`rControl`*\ A reference to a member variable of the dialog box, form view, or control view object related to the specified control. ### Remarks -The *pDX* object is supplied by the framework when the `DoDataExchange` function is called. Therefore, `DDX_Control` should only be called within your override of `DoDataExchange`. +The *`pDX`* object is supplied by the framework when the `DoDataExchange` function is called. Therefore, `DDX_Control` should only be called within your override of `DoDataExchange`. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_DateTimeCtrl +## `DDX_DateTimeCtrl` -The `DDX_DateTimeCtrl` function manages the transfer of date and/or time data between a date and time picker control ( [CDateTimeCtrl](../../mfc/reference/cdatetimectrl-class.md)) in a dialog box or form view object and either a [CTime](../../atl-mfc-shared/reference/ctime-class.md) or a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) data member of the dialog box or form view object. +The `DDX_DateTimeCtrl` function manages the transfer of date and/or time data between a date and time picker control ( [`CDateTimeCtrl`](../../mfc/reference/cdatetimectrl-class.md)) in a dialog box or form view object and either a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) or a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) data member of the dialog box or form view object. ```cpp void AFXAPI DDX_DateTimeCtrl( @@ -222,28 +221,28 @@ void AFXAPI DDX_DateTimeCtrl( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object. -*nIDC*
+*`nIDC`*\ The resource ID of the date and time picker control associated with the member variable. -*value*
+*`value`*\ In the first two versions, a reference to a `CTime` or `COleDateTime` member variable, dialog box, form view, or control view object with which data is exchanged. In the third version, a reference to a `CString` data member control view object. ### Remarks -When `DDX_DateTimeCtrl` is called, *value* is set to the current state of the date and time picker control, or the control is set to *value*, depending on the direction of the exchange. +When `DDX_DateTimeCtrl` is called, *`value`* is set to the current state of the date and time picker control, or the control is set to *`value`*, depending on the direction of the exchange. -In the third version above, `DDX_DateTimeCtrl` manages the transfer of `CString` data between a date time control and a [CString](../../atl-mfc-shared/reference/cstringt-class.md) data member of the control view object. The string is formatted using the current locale's rules for formatting dates and times. +In the third version above, `DDX_DateTimeCtrl` manages the transfer of `CString` data between a date time control and a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) data member of the control view object. The string is formatted using the current locale's rules for formatting dates and times. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_ManagedControl +## `DDX_ManagedControl` Creates a .NET control matching the control's resource ID. @@ -259,26 +258,26 @@ void DDX_ManagedControl( ### Parameters -*pDX*
-A pointer to a [CDataExchange Class](cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. +*`pDX`*\ +A pointer to a [`CDataExchange` Class](cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the control associated with the control property. -*control*
-A reference to a [CWinFormsControl Class](cwinformscontrol-class.md) object. +*`control`*\ +A reference to a [`CWinFormsControl` Class](cwinformscontrol-class.md) object. ### Remarks -`DDX_ManagedControl` calls [CWinFormsControl::CreateManagedControl](cwinformscontrol-class.md#createmanagedcontrol) to create a control matching the resource control ID. Use `DDX_ManagedControl` to create controls from resource IDs in [CDialog::OnInitDialog](cdialog-class.md#oninitdialog). For data exchange, you do not need to use the DDX/DDV functions with Windows Forms controls. +`DDX_ManagedControl` calls [`CWinFormsControl::CreateManagedControl`](cwinformscontrol-class.md#createmanagedcontrol) to create a control matching the resource control ID. Use `DDX_ManagedControl` to create controls from resource IDs in [`CDialog::OnInitDialog`](cdialog-class.md#oninitdialog). For data exchange, you do not need to use the DDX/DDV functions with Windows Forms controls. For more information, see [How to: Do DDX/DDV Data Binding with Windows Forms](../../dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md). ### Requirements -**Header:** afxwinforms.h +**Header:** `afxwinforms.h` -## DDX_IPAddress +## `DDX_IPAddress` The `DDX_IPAddress` function manages the transfer of data between an IP Address control and a data member of the control view object. @@ -291,14 +290,14 @@ void AFXAPI DDX_IPAddress( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the IP Address control associated with the control property. -*value*
-A reference to the DWORD containing the four-field value of the IP Address control. The fields are filled or read as follows. +*`value`*\ +A reference to the `DWORD` containing the four-field value of the IP Address control. The fields are filled or read as follows. |Field|Bits containing the field value| |-----------|-------------------------------------| @@ -307,19 +306,19 @@ A reference to the DWORD containing the four-field value of the IP Address contr |1|16 through 23| |0|24 through 31| -Use the Win32 [IPM_GETADDRESS](/windows/win32/Controls/ipm-getaddress) to read the value, or use [IPM_SETADDRESS](/windows/win32/Controls/ipm-setaddress) to fill the value. These messages are described in the Windows SDK. +Use the Win32 [`IPM_GETADDRESS`](/windows/win32/Controls/ipm-getaddress) to read the value, or use [`IPM_SETADDRESS`](/windows/win32/Controls/ipm-setaddress) to fill the value. These messages are described in the Windows SDK. ### Remarks -When `DDX_IPAddress` is called, *value* is either read from the IP Address control, or *value* is written to the control, depending on the direction of the exchange. +When `DDX_IPAddress` is called, *`value`* is either read from the IP Address control, or *`value`* is written to the control, depending on the direction of the exchange. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_LBIndex +## `DDX_LBIndex` The `DDX_LBIndex` function manages the transfer of **`int`** data between a list box control in a dialog box, form view, or control view object and an **`int`** data member of the dialog box, form view, or control view object. @@ -332,26 +331,26 @@ void AFXAPI DDX_LBIndex( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the list box control associated with the control property. -*index*
+*`index`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_LBIndex` is called, *index* is set to the index of the current list box selection. If no item is selected, *index* is set to -1. +When `DDX_LBIndex` is called, *`index`* is set to the index of the current list box selection. If no item is selected, *`index`* is set to -1. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_LBString +## `DDX_LBString` The `DDX_LBString` function manages the transfer of `CString` data between a list box control in a dialog box, form view, or control view object and a `CString` data member of the dialog box, form view, or control view object. @@ -364,20 +363,20 @@ void AFXAPI DDX_LBString( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the list box control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_LBString` is called to transfer data to a list box control, the first item in the control whose beginning matches *value* is selected. (To match the entire item rather than just a prefix, use [DDX_LBStringExact](#ddx_lbstringexact).) If there are no matches, no items are selected. The matching is case-insensitive. +When `DDX_LBString` is called to transfer data to a list box control, the first item in the control whose beginning matches *`value`* is selected. (To match the entire item rather than just a prefix, use [`DDX_LBStringExact`](#ddx_lbstringexact).) If there are no matches, no items are selected. The matching is case-insensitive. -When `DDX_LBString` is called to transfer data from a list box control, *value* is set to the current list box selection. If no item is selected, *value* is set to a string of zero length. +When `DDX_LBString` is called to transfer data from a list box control, *`value`* is set to the current list box selection. If no item is selected, *`value`* is set to a string of zero length. > [!NOTE] > If the list box is a drop-down list box, the value exchanged is limited to 255 characters. @@ -386,9 +385,9 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_LBStringExact +## `DDX_LBStringExact` The `DDX_CBStringExact` function manages the transfer of `CString` data between the edit control of a list box control in a dialog box, form view, or control view object and a `CString` data member of the dialog box, form view, or control view object. @@ -401,20 +400,20 @@ void AFXAPI DDX_LBStringExact( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the list box control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_LBStringExact` is called to transfer data to a list box control, the first item in the control that matches *value* is selected. (To match just a prefix rather than the entire item, use [DDX_LBString](#ddx_lbstring).) If there are no matches, no items are selected. The matching is case-insensitive. +When `DDX_LBStringExact` is called to transfer data to a list box control, the first item in the control that matches *`value`* is selected. (To match just a prefix rather than the entire item, use [`DDX_LBString`](#ddx_lbstring).) If there are no matches, no items are selected. The matching is case-insensitive. -When `DDX_CBStringExact` is called to transfer data from a list box control, *value* is set to the current list box selection. If no item is selected, *value* is set to a string of zero length. +When `DDX_CBStringExact` is called to transfer data from a list box control, *`value`* is set to the current list box selection. If no item is selected, *`value`* is set to a string of zero length. > [!NOTE] > If the list box is a drop-down list box, the value exchanged is limited to 255 characters. @@ -423,11 +422,11 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_MonthCalCtrl +## `DDX_MonthCalCtrl` -The `DDX_MonthCalCtrl` function manages the transfer of date data between a month calendar control ( [CMonthCalCtrl](../../mfc/reference/cmonthcalctrl-class.md)) in a dialog box, form view, or control view object and either a [CTime](../../atl-mfc-shared/reference/ctime-class.md) or a [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md) data member of the dialog box, form view, or control view object. +The `DDX_MonthCalCtrl` function manages the transfer of date data between a month calendar control ( [`CMonthCalCtrl`](../../mfc/reference/cmonthcalctrl-class.md)) in a dialog box, form view, or control view object and either a [`CTime`](../../atl-mfc-shared/reference/ctime-class.md) or a [`COleDateTime`](../../atl-mfc-shared/reference/coledatetime-class.md) data member of the dialog box, form view, or control view object. ```cpp void AFXAPI DDX_MonthCalCtrl( @@ -443,13 +442,13 @@ void AFXAPI DDX_MonthCalCtrl( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object. -*nIDC*
+*`nIDC`*\ The resource ID of the month calendar control associated with the member variable. -*value*
+*`value`*\ A reference to a `CTime` or `COleDateTime` member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks @@ -457,15 +456,15 @@ A reference to a `CTime` or `COleDateTime` member variable of the dialog box, fo > [!NOTE] > The control manages a date value only. The time fields in the time object are set to reflect the creation time of the control window, or whatever time was set in the control with a call to `CMonthCalCtrl::SetCurSel`. -When `DDX_MonthCalCtrl` is called, *value* is set to the current state of the month calendar control. +When `DDX_MonthCalCtrl` is called, *`value`* is set to the current state of the month calendar control. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Radio +## `DDX_Radio` The `DDX_Radio` function manages the transfer of **`int`** data between a radio control group in a dialog box, form view, or control view object and a **`int`** data member of the dialog box, form view, or control view object. The value of the **`int`** data member is determined according to which radio button within the group is selected. @@ -478,18 +477,18 @@ void AFXAPI DDX_Radio( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the first radio control in the group. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged. ### Remarks -When `DDX_Radio` is called, *value* is set to the current state of the radio control group. The value is set as a 0-based index of the radio control that is currently checked, or -1 if no radio controls are checked. +When `DDX_Radio` is called, *`value`* is set to the current state of the radio control group. The value is set as a 0-based index of the radio control that is currently checked, or -1 if no radio controls are checked. For example, in case that the first radio button in the group is checked (the button with WS_GROUP style) the value of the **`int`** member is 0 and so on. @@ -497,9 +496,9 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Scroll +## `DDX_Scroll` The `DDX_Scroll` function manages the transfer of **`int`** data between a scroll-bar control in a dialog box, form view, or control view object and an **`int`** data member of the dialog box, form view, or control view object. @@ -512,26 +511,26 @@ void AFXAPI DDX_Scroll( ### Parameters -*pDX*
+*`pDX`*\ A pointer to a `CDataExchange` object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the scroll-bar control associated with the control property. -*value*
+*`value`*\ A reference to a member variable of the dialog box, form view or control view object with which data is exchanged. ### Remarks -When `DDX_Scroll` is called, *value* is set to the current position of the control's thumb. For more information on the values associated with the current position of the control's thumb, see [GetScrollPos](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. +When `DDX_Scroll` is called, *`value`* is set to the current position of the control's thumb. For more information on the values associated with the current position of the control's thumb, see [`GetScrollPos`](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Slider +## `DDX_Slider` The `DDX_Slider` function manages the transfer of **`int`** data between a slider control in a dialog box or form view and an **`int`** data member of the dialog box or form view object. @@ -544,28 +543,28 @@ void AFXAPI DDX_Slider( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The resource ID of the slider control. -*value*
+*`value`*\ A reference to the value to be exchanged. This parameter holds or sets the slider control's current position. ### Remarks -When `DDX_Slider` is called, *value* is set to the current position of the control's thumb, or the value receives the position, depending on the direction of the exchange. +When `DDX_Slider` is called, *`value`* is set to the current position of the control's thumb, or the value receives the position, depending on the direction of the exchange. -For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). For information about slider controls, see [Using CSliderCtrl](../../mfc/using-csliderctrl.md). +For more information about DDX, see [Dialog Data Exchange and Validation](../../mfc/dialog-data-exchange-and-validation.md). For information about slider controls, see [Using `CSliderCtrl`](../../mfc/using-csliderctrl.md). ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` -## DDX_Text +## `DDX_Text` -The `DDX_Text` function manages the transfer of **`int`**, **UINT**, **`long`**, DWORD, `CString`, **`float`**, or **`double`** data between an edit control in a dialog box, form view, or control view and a [CString](../../atl-mfc-shared/reference/cstringt-class.md) data member of the dialog box, form view, or control view object. +The `DDX_Text` function manages the transfer of **`int`**, **`UINT`**, **`long`**, `DWORD`, `CString`, **`float`**, or **`double`** data between an edit control in a dialog box, form view, or control view and a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md) data member of the dialog box, form view, or control view object. ```cpp void AFXAPI DDX_Text( @@ -626,14 +625,14 @@ void AFXAPI DDX_Text( ### Parameters -*pDX*
-A pointer to a [CDataExchange](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. +*`pDX`*\ +A pointer to a [`CDataExchange`](../../mfc/reference/cdataexchange-class.md) object. The framework supplies this object to establish the context of the data exchange, including its direction. -*nIDC*
+*`nIDC`*\ The ID of an edit control in the dialog box, form view, or control view object. -*value*
-A reference to a data member in the dialog box, form view, or control view object. The data type of *value* depends on which of the overloaded versions of `DDX_Text` you use. +*`value`*\ +A reference to a data member in the dialog box, form view, or control view object. The data type of *`value`* depends on which of the overloaded versions of `DDX_Text` you use. ### Remarks @@ -641,11 +640,11 @@ For more information about DDX, see [Dialog Data Exchange and Validation](../../ ### Requirements - **Header** afxdd_.h + **Header** `afxdd_.h` ## See also -[Standard Dialog Data Validation Routines](standard-dialog-data-validation-routines.md)
-[Macros and Globals](mfc-macros-and-globals.md)
-[CWinFormsControl::CreateManagedControl](cwinformscontrol-class.md#createmanagedcontrol)
-[CDialog::OnInitDialog](cdialog-class.md#oninitdialog) +[Standard Dialog Data Validation Routines](standard-dialog-data-validation-routines.md)\ +[Macros and Globals](mfc-macros-and-globals.md)\ +[`CWinFormsControl::CreateManagedControl`](cwinformscontrol-class.md#createmanagedcontrol)\ +[`CDialog::OnInitDialog`](cdialog-class.md#oninitdialog) diff --git a/docs/mfc/reference/styles-used-by-mfc.md b/docs/mfc/reference/styles-used-by-mfc.md index 3afec125db..7dc94df529 100644 --- a/docs/mfc/reference/styles-used-by-mfc.md +++ b/docs/mfc/reference/styles-used-by-mfc.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Styles Used by MFC" title: "Styles Used by MFC" -ms.date: "06/20/2018" +description: "Learn more about: Styles Used by MFC" +ms.date: 06/20/2018 helpviewer_keywords: ["button objects (CButton), button styles", "button styles [MFC]", "buttons, MFC toolbars", "combo boxes [MFC], styles", "edit styles [MFC]", "extended window styles [MFC]", "frame windows [MFC], styles", "list boxes [MFC], styles", "message-box styles [MFC]", "scroll bars [MFC], styles", "scroll-bar styles [MFC]", "static styles [MFC]", "styles [MFC], button objects", "styles [MFC], MFC", "styles [MFC], windows", "styles [MFC]", "window styles, in MFC", "window styles [MFC]", "BS_3STATE constant [MFC]", "BS_AUTO3STATE constant [MFC]", "BS_AUTOCHECKBOX constant [MFC]", "BS_AUTORADIOBUTTON constant [MFC]", "BS_BITMAP constant [MFC]", "BS_BOTTOM constant [MFC]", "BS_CENTER constant [MFC]", "BS_CHECKBOX constant [MFC]", "BS_DEFPUSHBUTTON constant [MFC]", "BS_FLAT constant [MFC]", "BS_GROUPBOX constant [MFC]", "BS_ICON constant [MFC]", "BS_LEFT constant [MFC]", "BS_LEFTTEXT constant [MFC]", "BS_MULTILINE constant [MFC]", "BS_NOTIFY constant [MFC]", "BS_OWNERDRAW constant [MFC]", "BS_PUSHBUTTON constant [MFC]", "BS_PUSHLIKE constant [MFC]", "BS_RADIOBUTTON constant [MFC]", "BS_RIGHT constant [MFC]", "BS_RIGHTBUTTON constant [MFC]", "BS_TEXT constant [MFC]", "BS_TOP constant [MFC]", "BS_USERBUTTON constant [MFC]", "BS_VCENTER constant [MFC]", "CBS_AUTOHSCROLL constant [MFC]", "CBS_DISABLENOSCROLL constant [MFC]", "CBS_DROPDOWN constant [MFC]", "CBS_DROPDOWNLIST constant [MFC]", "CBS_HASSTRINGS constant [MFC]", "CBS_LOWERCASE constant [MFC]", "CBS_NOINTEGRALHEIGHT constant [MFC]", "CBS_OEMCONVERT constant [MFC]", "CBS_OWNERDRAWFIXED constant [MFC]", "CBS_OWNERDRAWVARIABLE constant [MFC]", "CBS_SIMPLE constant [MFC]", "CBS_SORT constant [MFC]", "CBS_UPPERCASE constant [MFC]", "ES_AUTOHSCROLL constant [MFC]", "ES_AUTOVSCROLL constant [MFC]", "ES_CENTER constant [MFC]", "ES_LEFT constant [MFC]", "ES_LOWERCASE constant [MFC]", "ES_MULTILINE constant [MFC]", "ES_NOHIDESEL constant [MFC]", "ES_NUMBER constant [MFC]", "ES_OEMCONVERT constant [MFC]", "ES_PASSWORD constant [MFC]", "ES_READONLY constant [MFC]", "ES_RIGHT constant [MFC]", "ES_UPPERCASE constant [MFC]", "ES_WANTRETURN constant [MFC]", "FWS_ADDTOTITLE constant [MFC]", "FWS_PREFIXTITLE constant [MFC]", "FWS_SNAPTOBARS constant [MFC]", "LBS_DISABLENOSCROLL constant [MFC]", "LBS_EXTENDEDSEL constant [MFC]", "LBS_HASSTRINGS constant [MFC]", "LBS_MULTICOLUMN constant [MFC]", "LBS_MULTIPLESEL constant [MFC]", "LBS_NODATA constant [MFC]", "LBS_NOINTEGRALHEIGHT constant [MFC]", "LBS_NOREDRAW constant [MFC]", "LBS_NOSEL constant [MFC]", "LBS_NOTIFY constant [MFC]", "LBS_OWNERDRAWFIXED constant [MFC]", "LBS_OWNERDRAWVARIABLE constant [MFC]", "LBS_SORT constant [MFC]", "LBS_STANDARD constant [MFC]", "LBS_USETABSTOPS constant [MFC]", "LBS_WANTKEYBOARDINPUT constant [MFC]", "MB_ABORTRETRYOVERWRITE constant [MFC]", "MB_APPLMODAL constant [MFC]", "MB_DEFBUTTON1 constant [MFC]", "MB_DEFBUTTON2 constant [MFC]", "MB_DEFBUTTON3 constant [MFC]", "MB_ICONEXCLAMATION constant [MFC]", "MB_ICONINFORMATION constant [MFC]", "MB_ICONQUESTION constant [MFC]", "MB_ICONSTOP constant [MFC]", "MB_OK constant [MFC]", "MB_OKCANCEL constant [MFC]", "MB_RETRYCANCEL constant [MFC]", "MB_SYSTEMMODAL constant [MFC]", "MB_TASKMODAL constant [MFC]", "MB_YESNO constant [MFC]", "MB_YESNOCANCEL constant [MFC]", "SBS_BOTTOMALIGN constant [MFC]", "SBS_HORZ constant [MFC]", "SBS_LEFTALIGN constant [MFC]", "SBS_RIGHTALIGN constant [MFC]", "SBS_SIZEBOX constant [MFC]", "SBS_SIZEBOXBOTTOMRIGHTALIGN constant [MFC]", "SBS_SIZEBOXTOPLEFTALIGN constant [MFC]", "SBS_TOPALIGN constant [MFC]", "SBS_VERT constant [MFC]", "SS_BITMAP constant [MFC]", "SS_BLACKFRAME constant [MFC]", "SS_BLACKRECT constant [MFC]", "SS_CENTER constant [MFC]", "SS_CENTERIMAGE constant [MFC]", "SS_ENDELLIPSIS constant [MFC]", "SS_ENHMETAFILE constant [MFC]", "SS_ETCHEDFRAME constant [MFC]", "SS_ETCHEDHORZ constant [MFC]", "SS_ETCHEDVERT constant [MFC]", "SS_GRAYFRAME constant [MFC]", "SS_GRAYRECT constant [MFC]", "SS_ICON constant [MFC]", "SS_LEFT constant [MFC]", "SS_LEFTNOWORDWRAP constant [MFC]", "SS_NOPREFIX constant [MFC]", "SS_NOTIFY constant [MFC]", "SS_OWNERDRAW constant [MFC]", "SS_PATHELLIPSIS constant [MFC]", "SS_REALSIZEIMAGE constant [MFC]", "SS_RIGHT constant [MFC]", "SS_RIGHTJUST constant [MFC]", "SS_SIMPLE constant [MFC]", "SS_SUNKEN constant [MFC]", "SS_USERITEM constant [MFC]", "SS_WHITEFRAME constant [MFC]", "SS_WHITERECT constant [MFC]", "SS_WORDELLIPSIS constant [MFC]", "WS_BORDER constant [MFC]", "WS_CAPTION constant [MFC]", "WS_CHILD constant [MFC]", "WS_CHILDWINDOW constant [MFC]", "WS_CLIPCHILDREN constant [MFC]", "WS_CLIPSIBLINGS constant [MFC]", "WS_DISABLED constant [MFC]", "WS_DLGFRAME constant [MFC]", "WS_GROUP constant [MFC]", "WS_HSCROLL constant [MFC]", "WS_ICONIC constant [MFC]", "WS_MAXIMIZE constant [MFC]", "WS_MAXIMIZEBOX constant [MFC]", "WS_MINIMIZE constant [MFC]", "WS_MINIMIZEBOX constant [MFC]", "WS_OVERLAPPED constant [MFC]", "WS_OVERLAPPEDWINDOW constant [MFC]", "WS_POPUP constant [MFC]", "WS_POPUPWINDOW constant [MFC]", "WS_SIZEBOX constant [MFC]", "WS_SYSMENU constant [MFC]", "WS_TABSTOP constant [MFC]", "WS_THICKFRAME constant [MFC]", "WS_TILED constant [MFC]", "WS_TILEDWINDOW constant [MFC]", "WS_VISIBLE constant [MFC]", "WS_VSCROLL constant [MFC]", "WS_EX_ACCEPTFILES constant [MFC]", "WS_EX_APPWINDOW constant [MFC]", "WS_EX_CLIENTEDGE constant [MFC]", "WS_EX_CONTEXTHELP constant [MFC]", "WS_EX_CONTROLPARENT constant [MFC]", "WS_EX_DLGMODALFRAME constant [MFC]", "WS_EX_LEFT constant [MFC]", "WS_EX_LEFTSCROLLBAR constant [MFC]", "WS_EX_LTRREADING constant [MFC]", "WS_EX_MDICHILD constant [MFC]", "WS_EX_NOPARENTNOTIFY constant [MFC]", "WS_EX_OVERLAPPEDWINDOW constant [MFC]", "WS_EX_PALETTEWINDOW constant [MFC]", "WS_EX_RIGHT constant [MFC]", "WS_EX_RIGHTSCROLLBAR constant [MFC]", "WS_EX_RTLREADING constant [MFC]", "WS_EX_STATICEDGE constant [MFC]", "WS_EX_TOOLWINDOW constant [MFC]", "WS_EX_TOPMOST constant [MFC]", "WS_EX_TRANSPARENT constant [MFC]", "WS_EX_WINDOWEDGE constant [MFC]"] -ms.assetid: d3b9af37-31b5-4c97-a8ad-189fd724b04c --- # Styles Used by MFC @@ -11,7 +10,7 @@ Use the following style flags to specify window or control appearance and behavi ## Button styles -Button styles apply to [`CButton Class`](../../mfc/reference/cbutton-class.md) objects, such as radio buttons, check boxes and pushbuttons. Specify a combination of styles in the *`dwStyle`* parameter of [`CButton::Create`](../../mfc/reference/cbutton-class.md#create). For more information on button styles in Windows, see [Button Styles (Windows)](/windows/win32/Controls/button-styles). +Button styles apply to [`CButton Class`](cbutton-class.md) objects, such as radio buttons, check boxes and pushbuttons. Specify a combination of styles in the *`dwStyle`* parameter of [`CButton::Create`](cbutton-class.md#create). For more information on button styles in Windows, see [Button Styles (Windows)](/windows/win32/Controls/button-styles). ### Button types @@ -24,8 +23,8 @@ The following table lists button types. You can optionally choose one of the fol |`BS_AUTOCHECKBOX`|Creates a check box button with two states: `BST_CHECKED` and `BST_UNCHECKED`. Clicking on the button sends a `BN_CLICKED` notification to the owner window and changes the state of the button. By default, associated text is displayed to the right of the check box. To display text to the left of the check box, use the `BS_LEFTTEXT` or `BS_RIGHTBUTTON` style.| |`BS_AUTORADIOBUTTON`|Creates a radio button with two states: `BST_CHECKED` and `BST_UNCHECKED`. Radio buttons are usually used in groups, with each group having a maximum of one checked option at a time. Clicking on the button sends a `BN_CLICKED` notification to the owner window, sets the state of the clicked radio button to `BST_CHECKED`, and sets the states of all other radio buttons in the button group to `BST_UNCHECKED`. By default, associated text is displayed to the right of the radio button. To display text to the left of the radio button, use the `BS_LEFTTEXT` or `BS_RIGHTBUTTON` style.| |`BS_CHECKBOX`|Creates a check box button with two states: `BST_CHECKED` and `BST_UNCHECKED`. Clicking on the button sends a `BN_CLICKED` notification to the owner window but does not change the state of the button. By default, associated text is displayed to the right of the check box. To display text to the left of the check box, use the `BS_LEFTTEXT` or `BS_RIGHTBUTTON` style.| -|`BS_COMMANDLINK`|Creates a command link button. A command link button is a command button specific to Windows Vista that displays a green arrow to the left of the main text and a note below the main text. You can set the note text using [`CButton::SetNote`](../../mfc/reference/cbutton-class.md#setnote).| -|`BS_DEFCOMMANDLINK`|Creates a command link button. A command link button is a command button specific to Windows Vista that displays a green arrow to the left of the main text and a note below the main text. You can set the note text using [`CButton::SetNote`](../../mfc/reference/cbutton-class.md#setnote). If the button is in a dialog box, pressing the ENTER key sends a `BN_CLICKED` notification to the dialog box even when the button does not have the input focus.| +|`BS_COMMANDLINK`|Creates a command link button. A command link button is a command button specific to Windows Vista that displays a green arrow to the left of the main text and a note below the main text. You can set the note text using [`CButton::SetNote`](cbutton-class.md#setnote).| +|`BS_DEFCOMMANDLINK`|Creates a command link button. A command link button is a command button specific to Windows Vista that displays a green arrow to the left of the main text and a note below the main text. You can set the note text using [`CButton::SetNote`](cbutton-class.md#setnote). If the button is in a dialog box, pressing the ENTER key sends a `BN_CLICKED` notification to the dialog box even when the button does not have the input focus.| |`BS_DEFPUSHBUTTON`|Creates a command button that has a heavy black border. If the button is in a dialog box, pressing the ENTER key sends a `BN_CLICKED` notification to the dialog box even when the button does not have the input focus.| |`BS_DEFSPLITBUTTON`|Creates a split button. A split button is a command button specific to Windows Vista that contains a button adjacent to a drop-down arrow. When you click the button, the default command is executed. When you click the drop-down arrow, a menu of additional commands appears. If the split button is in a dialog box, pressing the ENTER key sends a `BN_CLICKED` notification to the dialog box even when the button does not have the input focus| |`BS_GROUPBOX`|Creates a rectangle in which other buttons can be grouped. Text associated with this style is displayed in the rectangle's upper-left corner.| @@ -100,7 +99,7 @@ The following combo-box styles are available in MFC. For more information about ## Edit styles -Edit styles apply to [`CEdit` Class](../../mfc/reference/cedit-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CEdit::Create`](../../mfc/reference/cedit-class.md#create). For more information about edit control styles in Windows, see [Edit Control Styles (Windows)](/windows/win32/Controls/edit-control-styles). +Edit styles apply to [`CEdit` Class](cedit-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CEdit::Create`](cedit-class.md#create). For more information about edit control styles in Windows, see [Edit Control Styles (Windows)](/windows/win32/Controls/edit-control-styles). |Style|Description| |-----------|-----------------| @@ -121,17 +120,17 @@ Edit styles apply to [`CEdit` Class](../../mfc/reference/cedit-class.md) objects ## Frame-window styles -Frame-window styles apply to [`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CFrameWnd::Create`](../../mfc/reference/cframewnd-class.md#create). +Frame-window styles apply to [`CFrameWnd` Class](cframewnd-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CFrameWnd::Create`](cframewnd-class.md#create). |Style|Description| |-----------|-----------------| |`FWS_ADDTOTITLE`|Specifies information to append to the end of a frame window title. For example, "Microsoft Draw - Drawing in Document1". You can specify the strings displayed in the Document Template Strings tab in the Application Wizard. If you need to turn this option off, override the `CWnd::PreCreateWindow` member function.| |`FWS_PREFIXTITLE`|Shows the document name before the application name in a frame window title. For example, "Document - WordPad". You can specify the strings displayed in the Document Template Strings tab in the Application Wizard. If you need to turn this option off, override the `CWnd::PreCreateWindow` member function.| -|FWS_SNAPTOBARS|Controls sizing of the frame window that encloses a control bar when it is in a floating window rather than docked to a frame window. This style sizes the window to fit the control bar.| +|`FWS_SNAPTOBARS`|Controls sizing of the frame window that encloses a control bar when it is in a floating window rather than docked to a frame window. This style sizes the window to fit the control bar.| ## List-box styles -List-box styles apply to [`CListBox` Class](../../mfc/reference/clistbox-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CListBox::Create`](../../mfc/reference/clistbox-class.md#create). For more information about list box styles in Windows, see [List Box Styles (Windows)](/windows/win32/Controls/list-box-styles). +List-box styles apply to [`CListBox` Class](clistbox-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CListBox::Create`](clistbox-class.md#create). For more information about list box styles in Windows, see [List Box Styles (Windows)](/windows/win32/Controls/list-box-styles). |Style|Description| |-----------|-----------------| @@ -154,7 +153,7 @@ List-box styles apply to [`CListBox` Class](../../mfc/reference/clistbox-class.m ## Message-box styles -Message-box styles apply to [`AfxMessageBox`](../../mfc/reference/cstring-formatting-and-message-box-display.md#afxmessagebox) items. Specify a combination of styles in the *`nType`* parameter of `AfxMessageBox`. For more information about message box styles in Windows, see [`MessageBox` Function (Windows)](/windows/win32/api/winuser/nf-winuser-messagebox). +Message-box styles apply to [`AfxMessageBox`](cstring-formatting-and-message-box-display.md#afxmessagebox) items. Specify a combination of styles in the *`nType`* parameter of `AfxMessageBox`. For more information about message box styles in Windows, see [`MessageBox` Function (Windows)](/windows/win32/api/winuser/nf-winuser-messagebox). The following message-box styles are available. @@ -196,7 +195,7 @@ The following message-box styles are available. ## Scroll-bar styles -Scroll-bar styles apply to [`CScrollBar` Class](../../mfc/reference/cscrollbar-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CScrollBar::Create`](../../mfc/reference/cscrollbar-class.md#create). For more information about scroll bar control styles in Windows, see [Scroll Bar Control Styles (Windows)](/windows/win32/Controls/scroll-bar-control-styles). +Scroll-bar styles apply to [`CScrollBar` Class](cscrollbar-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CScrollBar::Create`](cscrollbar-class.md#create). For more information about scroll bar control styles in Windows, see [Scroll Bar Control Styles (Windows)](/windows/win32/Controls/scroll-bar-control-styles). |Style|Description| |-----------|-----------------| @@ -213,7 +212,7 @@ Scroll-bar styles apply to [`CScrollBar` Class](../../mfc/reference/cscrollbar-c ## Static styles -Static styles apply to [`CStatic` Class](../../mfc/reference/cstatic-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CStatic::Create`](../../mfc/reference/cstatic-class.md#create). For more information about static control styles in Windows, see [Static Control Styles (Windows)](/windows/win32/Controls/static-control-styles). +Static styles apply to [`CStatic` Class](cstatic-class.md) objects. Specify a combination of styles in the *`dwStyle`* parameter of [`CStatic::Create`](cstatic-class.md#create). For more information about static control styles in Windows, see [Static Control Styles (Windows)](/windows/win32/Controls/static-control-styles). |Style|Description| |-----------|-----------------| @@ -247,7 +246,7 @@ Static styles apply to [`CStatic` Class](../../mfc/reference/cstatic-class.md) o ## Window styles -Window styles apply to [`CWnd` Class](../../mfc/reference/cwnd-class.md) objects. Specify a combination of styles in the *dwStyle* parameter of [`CWnd::Create`](../../mfc/reference/cwnd-class.md#create) or [`CWnd::CreateEx`](../../mfc/reference/cwnd-class.md#createex). For more information about window styles in Windows, see [Window Styles (Windows)](/windows/win32/winmsg/window-styles). +Window styles apply to [`CWnd` Class](cwnd-class.md) objects. Specify a combination of styles in the *dwStyle* parameter of [`CWnd::Create`](cwnd-class.md#create) or [`CWnd::CreateEx`](cwnd-class.md#createex). For more information about window styles in Windows, see [Window Styles (Windows)](/windows/win32/winmsg/window-styles). |Style|Description| |-----------|-----------------| @@ -281,7 +280,7 @@ Window styles apply to [`CWnd` Class](../../mfc/reference/cwnd-class.md) objects ## Extended window styles -Extended window styles apply to [`CWnd` Class](../../mfc/reference/cwnd-class.md) objects. Specify a combination of styles in the *`dwExStyle`* parameter of [`CWnd::CreateEx`](../../mfc/reference/cwnd-class.md#createex). For more information about extended window styles in Windows, see [Extended Window Styles (Windows)](/windows/win32/winmsg/extended-window-styles). +Extended window styles apply to [`CWnd` Class](cwnd-class.md) objects. Specify a combination of styles in the *`dwExStyle`* parameter of [`CWnd::CreateEx`](cwnd-class.md#createex). For more information about extended window styles in Windows, see [Extended Window Styles (Windows)](/windows/win32/winmsg/extended-window-styles). |Style|Description| |-----------|-----------------| @@ -310,21 +309,21 @@ Extended window styles apply to [`CWnd` Class](../../mfc/reference/cwnd-class.md ## See also -[MFC Class Overview](../../mfc/class-library-overview.md)
-[`CWnd::Create`](../../mfc/reference/cwnd-class.md#create)
-[`CWnd::CreateEx`](../../mfc/reference/cwnd-class.md#createex)
-[`CEdit::Create`](../../mfc/reference/cedit-class.md#create)
-[`CScrollBar::Create`](../../mfc/reference/cscrollbar-class.md#create)
-[`CStatic::Create`](../../mfc/reference/cstatic-class.md#create)
-[`AfxMessageBox`](../../mfc/reference/cstring-formatting-and-message-box-display.md#afxmessagebox)
-[`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww)
-[`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw)
-[Button Styles (Windows)](/windows/win32/Controls/button-styles)
-[Combo Box Styles (Windows)](/windows/win32/Controls/combo-box-styles)
-[Edit Control Styles (Windows)](/windows/win32/Controls/edit-control-styles)
-[List Box Styles (Windows)](/windows/win32/Controls/list-box-styles)
-[`MessageBox` Function (Windows)](/windows/win32/api/winuser/nf-winuser-messagebox)
-[Scroll Bar Control Styles (Windows)](/windows/win32/Controls/scroll-bar-control-styles)
-[Static Control Styles (Windows)](/windows/win32/Controls/static-control-styles)
-[Window Styles (Windows)](/windows/win32/winmsg/window-styles)
+[MFC Class Overview](../class-library-overview.md)\ +[`CWnd::Create`](cwnd-class.md#create)\ +[`CWnd::CreateEx`](cwnd-class.md#createex)\ +[`CEdit::Create`](cedit-class.md#create)\ +[`CScrollBar::Create`](cscrollbar-class.md#create)\ +[`CStatic::Create`](cstatic-class.md#create)\ +[`AfxMessageBox`](cstring-formatting-and-message-box-display.md#afxmessagebox)\ +[`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww)\ +[`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw)\ +[Button Styles (Windows)](/windows/win32/Controls/button-styles)\ +[Combo Box Styles (Windows)](/windows/win32/Controls/combo-box-styles)\ +[Edit Control Styles (Windows)](/windows/win32/Controls/edit-control-styles)\ +[List Box Styles (Windows)](/windows/win32/Controls/list-box-styles)\ +[`MessageBox` Function (Windows)](/windows/win32/api/winuser/nf-winuser-messagebox)\ +[Scroll Bar Control Styles (Windows)](/windows/win32/Controls/scroll-bar-control-styles)\ +[Static Control Styles (Windows)](/windows/win32/Controls/static-control-styles)\ +[Window Styles (Windows)](/windows/win32/winmsg/window-styles)\ [Extended Window Styles (Windows)](/windows/win32/winmsg/extended-window-styles) diff --git a/docs/mfc/reference/variant-parameter-type-constants.md b/docs/mfc/reference/variant-parameter-type-constants.md index e71f99e6d8..0304c57c92 100644 --- a/docs/mfc/reference/variant-parameter-type-constants.md +++ b/docs/mfc/reference/variant-parameter-type-constants.md @@ -14,7 +14,7 @@ The following is a list of class constants: ## Variant Data Constants -- VTS_COLOR A 32-bit integer used to represent a RGB color value. +- VTS_COLOR A 32-bit integer used to represent an RGB color value. - VTS_FONT A pointer to the `IFontDisp` interface of an OLE font object. diff --git a/docs/mfc/reference/wm-message-handlers-a-c.md b/docs/mfc/reference/wm-message-handlers-a-c.md index 258e0e85ec..e6e35de0fc 100644 --- a/docs/mfc/reference/wm-message-handlers-a-c.md +++ b/docs/mfc/reference/wm-message-handlers-a-c.md @@ -4,34 +4,33 @@ title: "WM_ Message Handlers: A - C" ms.date: "11/04/2016" f1_keywords: ["ON_WM_CREATE", "ON_WM_COMPACTING", "ON_WM_CHARTOITEM", "ON_WM_ASKCBFORMATNAME", "ON_WM_CTLCOLOR", "ON_WM_COMPAREITEM", "ON_WM_CHILDACTIVATE", "ON_WM_CONTEXTMENU", "ON_WM_ACTIVATE", "ON_WM_CANCELMODE", "ON_WM_CLOSE", "ON_WM_CAPTURECHANGED", "ON_WM_ACTIVATEAPP", "ON_WM_CHAR", "ON_WM_CHANGECBCHAIN"] helpviewer_keywords: ["ON_WM_COMPACTING [MFC]", "ON_WM_COMPAREITEM [MFC]", "ON_WM_CLOSE [MFC]", "ON_WM_CTLCOLOR [MFC]", "ON_WM_CHAR [MFC]", "ON_WM_CAPTURECHANGED [MFC]", "ON_WM_CHARTOITEM [MFC]", "ON_WM_CREATE [MFC]", "ON_WM_ACTIVATE [MFC]", "ON_WM_CONTEXTMENU [MFC]", "ON_WM_CANCELMODE [MFC]", "ON_WM_ASKCBFORMATNAME [MFC]", "ON_WM_CHILDACTIVATE [MFC]", "WM_ messages [MFC]", "ON_WM_ACTIVATEAPP [MFC]", "ON_WM_CHANGECBCHAIN"] -ms.assetid: 4e315896-d646-4b87-b0ab-41a4a753b045 --- -# WM_ Message Handlers: A - C +# `WM_` Message Handlers: A - C The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| |---------------|------------------------| -|ON_WM_ACTIVATE()|afx_msg void [OnActivate](../../mfc/reference/cwnd-class.md#onactivate)(UINT, CWnd\*, BOOL);| -|ON_WM_ACTIVATEAPP()|afx_msg void [OnActivateApp](../../mfc/reference/cwnd-class.md#onactivateapp)(BOOL, DWORD);| -|ON_WM_APPCOMMAND()|afx_msg void [OnAppCommand](../../mfc/reference/cwnd-class.md#onappcommand)(CWnd\*, UINT, UINT, UINT);| -|ON_WM_ASKCBFORMATNAME()|afx_msg void [OnAskCbFormatName](../../mfc/reference/cwnd-class.md#onaskcbformatname)(UINT, LPSTR);| -|ON_WM_CANCELMODE()|afx_msg void [OnCancelMode](../../mfc/reference/cwnd-class.md#oncancelmode)();| -|ON_WM_CAPTURECHANGED()|afx_msg void [OnCaptureChanged](../../mfc/reference/cwnd-class.md#oncapturechanged)(CWnd\*);| -|ON_WM_CHANGECBCHAIN()|afx_msg void [OnChangeCbChain](../../mfc/reference/cwnd-class.md#onchangecbchain)(HWND, HWND);| -|ON_WM_CHAR()|afx_msg void [OnChar](../../mfc/reference/cwnd-class.md#onchar)(UINT, UINT, UINT);| -|ON_WM_CHARTOITEM()|afx_msg int [OnCharToItem](../../mfc/reference/cwnd-class.md#onchartoitem)(UINT, CWnd\*, UINT);| -|ON_WM_CHILDACTIVATE()|afx_msg void [OnChildActivate](../../mfc/reference/cwnd-class.md#onchildactivate)();| -|ON_WM_CLIPBOARDUPDATE()|afx_msg void [OnClipboardUpdate](../../mfc/reference/cwnd-class.md#onclipboardupdate)();| -|ON_WM_CLOSE()|afx_msg void [OnClose](../../mfc/reference/cwnd-class.md#onclose)();| -|ON_WM_COMPACTING()|afx_msg void [OnCompacting](../../mfc/reference/cwnd-class.md#oncompacting)(UINT);| -|ON_WM_COMPAREITEM()|afx_msg int [OnCompareItem](../../mfc/reference/cwnd-class.md#oncompareitem)(LPCOMPAREITEMSTRUCT);| -|ON_WM_CONTEXTMENU()|afx_msg void [OnContextMenu](../../mfc/reference/cwnd-class.md#oncontextmenu)(CWnd\*, CPoint);| -|ON_WM_COPYDATA()|afx_msg BOOL [OnCopyData](../../mfc/reference/cwnd-class.md#oncopydata)(CWnd\* pWnd, COPYDATASTRUCT\* pCopyDataStruct);| -|ON_WM_CREATE()|afx_msg int [OnCreate](../../mfc/reference/cwnd-class.md#oncreate)(LPCREATESTRUCT);| -|ON_WM_CTLCOLOR()|afx_msg HBRUSH [OnCtlColor](../../mfc/reference/cwnd-class.md#onctlcolor)(CDC\*, CWnd\*, UINT);| +|`ON_WM_ACTIVATE()`|`afx_msg void` [`OnActivate`](../../mfc/reference/cwnd-class.md#onactivate)`(UINT, CWnd*, BOOL);`| +|`ON_WM_ACTIVATEAPP()`|`afx_msg void` [`OnActivateApp`](../../mfc/reference/cwnd-class.md#onactivateapp)`(BOOL, DWORD);`| +|`ON_WM_APPCOMMAND()`|`afx_msg void` [`OnAppCommand`](../../mfc/reference/cwnd-class.md#onappcommand)`(CWnd*, UINT, UINT, UINT);`| +|`ON_WM_ASKCBFORMATNAME()`|`afx_msg void` [`OnAskCbFormatName`](../../mfc/reference/cwnd-class.md#onaskcbformatname)`(UINT, LPSTR);`| +|`ON_WM_CANCELMODE()`|`afx_msg void` [`OnCancelMode`](../../mfc/reference/cwnd-class.md#oncancelmode)`();`| +|`ON_WM_CAPTURECHANGED()`|`afx_msg void` [`OnCaptureChanged`](../../mfc/reference/cwnd-class.md#oncapturechanged)`(CWnd*);`| +|`ON_WM_CHANGECBCHAIN()`|`afx_msg void` [`OnChangeCbChain`](../../mfc/reference/cwnd-class.md#onchangecbchain)`(HWND, HWND);`| +|`ON_WM_CHAR()`|`afx_msg void` [`OnChar`](../../mfc/reference/cwnd-class.md#onchar)`(UINT, UINT, UINT);`| +|`ON_WM_CHARTOITEM()`|`afx_msg int` [`OnCharToItem`](../../mfc/reference/cwnd-class.md#onchartoitem)`(UINT, CWnd*, UINT);`| +|`ON_WM_CHILDACTIVATE()`|`afx_msg void` [`OnChildActivate`](../../mfc/reference/cwnd-class.md#onchildactivate)`();`| +|`ON_WM_CLIPBOARDUPDATE()`|`afx_msg void` [`OnClipboardUpdate`](../../mfc/reference/cwnd-class.md#onclipboardupdate)`();`| +|`ON_WM_CLOSE()`|`afx_msg void` [`OnClose`](../../mfc/reference/cwnd-class.md#onclose)`();`| +|`ON_WM_COMPACTING()`|`afx_msg void` [`OnCompacting`](../../mfc/reference/cwnd-class.md#oncompacting)`(UINT);`| +|`ON_WM_COMPAREITEM()`|`afx_msg int` [`OnCompareItem`](../../mfc/reference/cwnd-class.md#oncompareitem)`(LPCOMPAREITEMSTRUCT);`| +|`ON_WM_CONTEXTMENU()`|`afx_msg void` [`OnContextMenu`](../../mfc/reference/cwnd-class.md#oncontextmenu)`(CWnd*, CPoint);`| +|`ON_WM_COPYDATA()`|`afx_msg BOOL` [`OnCopyData`](../../mfc/reference/cwnd-class.md#oncopydata)`(CWnd* pWnd, COPYDATASTRUCT* pCopyDataStruct);`| +|`ON_WM_CREATE()`|`afx_msg int` [`OnCreate`](../../mfc/reference/cwnd-class.md#oncreate)`(LPCREATESTRUCT);`| +|`ON_WM_CTLCOLOR()`|`afx_msg HBRUSH` [`OnCtlColor`](../../mfc/reference/cwnd-class.md#onctlcolor)`(CDC*, CWnd*, UINT);`| ## See also -[Message Maps](../../mfc/reference/message-maps-mfc.md)
-[Handlers for WM_ Messages](../../mfc/reference/handlers-for-wm-messages.md) +[Message Maps](../../mfc/reference/message-maps-mfc.md)\ +[Handlers for `WM_` Messages](../../mfc/reference/handlers-for-wm-messages.md) diff --git a/docs/mfc/setting-the-dialog-boxs-background-color.md b/docs/mfc/setting-the-dialog-boxs-background-color.md index 76b102465c..7935340160 100644 --- a/docs/mfc/setting-the-dialog-boxs-background-color.md +++ b/docs/mfc/setting-the-dialog-boxs-background-color.md @@ -1,17 +1,33 @@ --- -description: "Learn more about: Setting the Dialog Box’s Background Color" -title: "Setting the Dialog Box’s Background Color" -ms.date: "07/12/2018" +description: "Learn more about: Setting the Dialog Box's Background Color" +title: "Setting the Dialog Box's Background Color" +ms.date: 11/17/2023 helpviewer_keywords: ["CSS, background attributes in styles [MFC]", "HTML element formatting, background attributes", "colors, dialog box", "dialog boxes [MFC], colors", "background colors, dialog boxes", "MFC dialog boxes [MFC], colors"] -ms.assetid: 05ee28a4-f3ae-4203-84ac-022f266ff2ab --- -# Setting the Dialog Box’s Background Color +# Setting the Dialog Box's Background Color -You can set the background color of your dialog boxes by handling WM_CTLCOLOR messages for the dialog box window. The color you set is used for only the specified dialog box. +You can set the background color of your dialog boxes by handling `WM_CTLCOLOR` messages for the dialog box window. The color you set is used for only the specified dialog box. -See [codexpert blog](https://codexpert.ro/blog/2013/03/13/painting-the-dialog-backround/) for an example. +For example, the following code fragment sets the background color of the dialog box to dark grey. The `OnCtlColor` member function is called whenever the dialog box is redrawn: + +```cpp +HBRUSH CAboutDlg::OnCtlColor(CDC* pDC, CWnd* pWnd, UINT nCtlColor) +{ + return (HBRUSH)GetStockObject(DKGRAY_BRUSH); +} +``` + +For the previous code fragment to work: +- add `virtual HBRUSH OnCtlColor(CDC* pDC, CWnd* pWnd, UINT nCtlColor);` to the `protected:` section of the class definition for your dialog. +- add the following to the class definition for your dialog, and change `CMyDialog` to the name of your dialog class: + +```cpp +BEGIN_MESSAGE_MAP(CMyDialog, CDialogEx) + ON_WM_CTLCOLOR() +END_MESSAGE_MAP() +``` ## See also -[Working with Dialog Boxes in MFC](../mfc/life-cycle-of-a-dialog-box.md)
+[Working with Dialog Boxes in MFC](../mfc/life-cycle-of-a-dialog-box.md)\ [Handling Windows Messages in Your Dialog Box](../mfc/handling-windows-messages-in-your-dialog-box.md) diff --git a/docs/mfc/storing-and-loading-cobjects-via-an-archive.md b/docs/mfc/storing-and-loading-cobjects-via-an-archive.md index 174a0a762e..ccbafa9bdb 100644 --- a/docs/mfc/storing-and-loading-cobjects-via-an-archive.md +++ b/docs/mfc/storing-and-loading-cobjects-via-an-archive.md @@ -21,7 +21,7 @@ Therefore, whether you use the `CArchive` **<\<** and **>>** operators, versus c The following example illustrates the cases: [!code-cpp[NVC_MFCSerialization#36](../mfc/codesnippet/cpp/storing-and-loading-cobjects-via-an-archive_1.h)] - +  [!code-cpp[NVC_MFCSerialization#37](../mfc/codesnippet/cpp/storing-and-loading-cobjects-via-an-archive_2.cpp)] In summary, if your serializable class defines an embedded `CObject` as a member, you should *not* use the `CArchive` **<\<** and **>>** operators for that object, but should call the `Serialize` function instead. Also, if your serializable class defines a pointer to a `CObject` (or an object derived from `CObject`) as a member, but constructs this other object in its own constructor, you should also call `Serialize`. diff --git a/docs/mfc/tn001-window-class-registration.md b/docs/mfc/tn001-window-class-registration.md index 66924f88cc..9a528229ab 100644 --- a/docs/mfc/tn001-window-class-registration.md +++ b/docs/mfc/tn001-window-class-registration.md @@ -50,7 +50,7 @@ Two icons support MDI applications with single document types: one icon for the `CFrameWnd::LoadFrame` will register a `WNDCLASS` using the icon ID you specify as the first parameter and the following standard attributes: -- class style : CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW; +- class style : `CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW;` - icon AFX_IDI_STD_FRAME diff --git a/docs/mfc/tn002-persistent-object-data-format.md b/docs/mfc/tn002-persistent-object-data-format.md index da977b57ee..46c468bb74 100644 --- a/docs/mfc/tn002-persistent-object-data-format.md +++ b/docs/mfc/tn002-persistent-object-data-format.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: TN002: Persistent Object Data Format" title: "TN002: Persistent Object Data Format" -ms.date: "11/04/2016" +description: "Learn more about: TN002: Persistent Object Data Format" +ms.date: 11/04/2016 helpviewer_keywords: ["VERSIONABLE_SCHEMA macro [MFC]", "persistent object data", "CArchive class [MFC], support for persistent data", "persistent C++ objects [MFC]", "TN002"] -ms.assetid: 553fe01d-c587-4c8d-a181-3244a15c2be9 --- # TN002: Persistent Object Data Format @@ -56,7 +55,7 @@ If the object has not been saved before, there are two possibilities to consider The descriptor for this class is then inserted into the archive using the `CRuntimeClass::Store` method. `CRuntimeClass::Store` inserts the schema number of the class (see below) and the ASCII text name of the class. Note that the use of the ASCII text name does not guarantee uniqueness of the archive across applications. Therefore, you should tag your data files to prevent corruption. Following the insertion of the class information, the archive puts the object into the *m_pStoreMap* and then calls the `Serialize` method to insert class-specific data. Placing the object into the *m_pStoreMap* before calling `Serialize` prevents multiple copies of the object from being saved to the store. -When returning to the initial caller (usually the root of the network of objects), you must call [CArchive::Close](../mfc/reference/carchive-class.md#close). If you plan to perform other [CFile](../mfc/reference/cfile-class.md)operations, you must call the `CArchive` method [Flush](../mfc/reference/carchive-class.md#flush) to prevent corruption of the archive. +When returning to the initial caller (usually the root of the network of objects), you must call [CArchive::Close](../mfc/reference/carchive-class.md#close). If you plan to perform other [CFile](../mfc/reference/cfile-class.md) operations, you must call the `CArchive` method [Flush](../mfc/reference/carchive-class.md#flush) to prevent corruption of the archive. > [!NOTE] > This implementation imposes a hard limit of 0x3FFFFFFE indices per archive context. This number represents the maximum number of unique objects and classes that can be saved in a single archive, but a single disk file can have an unlimited number of archive contexts. diff --git a/docs/mfc/tn014-custom-controls.md b/docs/mfc/tn014-custom-controls.md index 6cfdbcff96..d6eb5e03e1 100644 --- a/docs/mfc/tn014-custom-controls.md +++ b/docs/mfc/tn014-custom-controls.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: TN014: Custom Controls" title: "TN014: Custom Controls" +description: "Learn more about: TN014: Custom Controls" ms.date: "06/28/2018" f1_keywords: ["vc.controls"] helpviewer_keywords: ["TN014", "custom controls [MFC]"] -ms.assetid: 1917a498-f643-457c-b570-9a0af7dbf7bb --- # TN014: Custom Controls @@ -39,44 +38,44 @@ By using self-draw controls you can build reusable control classes that use owne - For self-draw buttons: ```cpp - CButton:DrawItem(LPDRAWITEMSTRUCT); + CButton::DrawItem(LPDRAWITEMSTRUCT); // insert code to draw this button ``` - For self-draw menus: ```cpp - CMenu:MeasureItem(LPMEASUREITEMSTRUCT); + CMenu::MeasureItem(LPMEASUREITEMSTRUCT); // insert code to measure the size of an item in this menu - CMenu:DrawItem(LPDRAWITEMSTRUCT); + CMenu::DrawItem(LPDRAWITEMSTRUCT); // insert code to draw an item in this menu ``` - For self-draw list boxes: ```cpp - CListBox:MeasureItem(LPMEASUREITEMSTRUCT); + CListBox::MeasureItem(LPMEASUREITEMSTRUCT); // insert code to measure the size of an item in this list box - CListBox:DrawItem(LPDRAWITEMSTRUCT); + CListBox::DrawItem(LPDRAWITEMSTRUCT); // insert code to draw an item in this list box - CListBox:CompareItem(LPCOMPAREITEMSTRUCT); + CListBox::CompareItem(LPCOMPAREITEMSTRUCT); // insert code to compare two items in this list box if LBS_SORT - CListBox:DeleteItem(LPDELETEITEMSTRUCT); + CListBox::DeleteItem(LPDELETEITEMSTRUCT); // insert code to delete an item from this list box ``` - For self-draw combo boxes: ```cpp - CComboBox:MeasureItem(LPMEASUREITEMSTRUCT); + CComboBox::MeasureItem(LPMEASUREITEMSTRUCT); // insert code to measure the size of an item in this combo box - CComboBox:DrawItem(LPDRAWITEMSTRUCT); + CComboBox::DrawItem(LPDRAWITEMSTRUCT); // insert code to draw an item in this combo box - CComboBox:CompareItem(LPCOMPAREITEMSTRUCT); + CComboBox::CompareItem(LPCOMPAREITEMSTRUCT); // insert code to compare two items in this combo box if CBS_SORT - CComboBox:DeleteItem(LPDELETEITEMSTRUCT); + CComboBox::DeleteItem(LPDELETEITEMSTRUCT); // insert code to delete an item from this combo box ``` @@ -118,7 +117,7 @@ There are three common ways these are related: - `CWnd` is attached to an existing `HWND` and you can modify the behavior in a derived class. This is called dynamic subclassing because we are changing the behavior, and therefore the class, of a Windows object at run time. -You can achieve dynamic subclassing by using the methods [CWnd::SubclassWindow](../mfc/reference/cwnd-class.md#subclasswindow) and[CWnd::SubclassDlgItem](../mfc/reference/cwnd-class.md#subclassdlgitem). +You can achieve dynamic subclassing by using the methods [CWnd::SubclassWindow](../mfc/reference/cwnd-class.md#subclasswindow) and [CWnd::SubclassDlgItem](../mfc/reference/cwnd-class.md#subclassdlgitem). Both routines attach a `CWnd` object to an existing `HWND`. `SubclassWindow` takes the `HWND` directly. `SubclassDlgItem` is a helper function that takes a control ID and the parent window. `SubclassDlgItem` is designed for attaching C++ objects to dialog controls created from a dialog template. @@ -126,5 +125,5 @@ See the [CTRLTEST](../overview/visual-cpp-samples.md) example for several exampl ## See also -[Technical Notes by Number](../mfc/technical-notes-by-number.md)
+[Technical Notes by Number](../mfc/technical-notes-by-number.md)\ [Technical Notes by Category](../mfc/technical-notes-by-category.md) diff --git a/docs/mfc/tn017-destroying-window-objects.md b/docs/mfc/tn017-destroying-window-objects.md index 248d3d91b9..f50a0b32b7 100644 --- a/docs/mfc/tn017-destroying-window-objects.md +++ b/docs/mfc/tn017-destroying-window-objects.md @@ -1,22 +1,22 @@ --- -description: "Learn more about: TN017: Destroying Window Objects" -title: "TN017: Destroying Window Objects" -ms.date: "11/04/2016" +description: "Learn more about: TN017: Destroying window objects" +title: "TN017: Destroying window objects" +ms.date: 06/03/2022 f1_keywords: ["vc.objects"] helpviewer_keywords: ["destroying windows", "TN017", "PostNcDestroy method [MFC]"] ms.assetid: 5bf208a5-5683-439b-92a1-547c5ded26cd --- -# TN017: Destroying Window Objects +# TN017: Destroying window objects -This note describes the use of the [CWnd::PostNcDestroy](../mfc/reference/cwnd-class.md#postncdestroy) method. Use this method if you want to do customized allocation of `CWnd`-derived objects. This note also explains why you should use [CWnd::DestroyWindow](../mfc/reference/cwnd-class.md#destroywindow) to destroy a C++ Windows object instead of the **`delete`** operator. +This note describes the use of the [`CWnd::PostNcDestroy`](../mfc/reference/cwnd-class.md#postncdestroy) method. Use this method if you want to do customized allocation of `CWnd`-derived objects. This note also explains why you should use [`CWnd::DestroyWindow`](../mfc/reference/cwnd-class.md#destroywindow) to destroy a C++ Windows object instead of the **`delete`** operator. -If you follow the guidelines in this topic, you will have few cleanup problems. These problems can result from issues such as forgetting to delete/free C++ memory, forgetting to free system resources like `HWND`s, or freeing objects too many times. +If you follow the guidelines in this article, you'll have few cleanup problems. These problems can result from issues such as forgetting to delete/free C++ memory, forgetting to free system resources like `HWND`s, or freeing objects too many times. -## The Problem +## The problem Each windows object (object of a class derived from `CWnd`) represents both a C++ object and an `HWND`. C++ objects are allocated in the application's heap and `HWND`s are allocated in system resources by the window manager. Because there are several ways to destroy a window object, we must provide a set of rules that prevent system resource or memory leaks. These rules must also prevent objects and Windows handles from being destroyed more than one time. -## Destroying Windows +## Destroying windows The following are the two permitted ways to destroy a Windows object: @@ -24,24 +24,24 @@ The following are the two permitted ways to destroy a Windows object: - Explicitly deleting with the **`delete`** operator. -The first case is by far the most common. This case applies even if your code does not call `DestroyWindow` directly. When the user directly closes a frame window, this action generates the WM_CLOSE message, and the default response to this message is to call `DestroyWindow.` When a parent window is destroyed, Windows calls `DestroyWindow` for all its children. +The first case is by far the most common. This case applies even if your code doesn't call `DestroyWindow` directly. When the user directly closes a frame window, this action generates the WM_CLOSE message, and the default response to this message is to call `DestroyWindow`. When a parent window is destroyed, Windows calls `DestroyWindow` for all its children. The second case, the use of the **`delete`** operator on Windows objects, should be rare. The following are some cases where using **`delete`** is the correct choice. -## Auto Cleanup with CWnd::PostNcDestroy +## Auto cleanup with `CWnd::PostNcDestroy` -When the system destroys a Windows window, the last Windows message sent to the window is WM_NCDESTROY. The default `CWnd` handler for that message is [CWnd::OnNcDestroy](../mfc/reference/cwnd-class.md#onncdestroy). `OnNcDestroy` will detach the `HWND` from the C++ object and call the virtual function `PostNcDestroy`. Some classes override this function to delete the C++ object. +When the system destroys a Windows window, the last Windows message sent to the window is `WM_NCDESTROY`. The default `CWnd` handler for that message is [`CWnd::OnNcDestroy`](../mfc/reference/cwnd-class.md#onncdestroy). `OnNcDestroy` will detach the `HWND` from the C++ object and call the virtual function `PostNcDestroy`. Some classes override this function to delete the C++ object. -The default implementation of `CWnd::PostNcDestroy` does nothing, which is appropriate for window objects that are allocated on the stack frame or embedded in other objects. This is not appropriate for window objects that are designed to be allocated on the heap without any other objects. In other words, it is not appropriate for window objects that are not embedded in other C++ objects. +The default implementation of `CWnd::PostNcDestroy` does nothing, which is appropriate for window objects that are allocated on the stack frame or embedded in other objects. This behavior isn't appropriate for window objects designed for allocation on the heap without any other objects. In other words, it isn't appropriate for window objects that aren't embedded in other C++ objects. -Those classes that are designed to be allocated alone on the heap override the `PostNcDestroy` method to perform a **delete this**. This statement will free any memory associated with the C++ object. Even though the default `CWnd` destructor calls `DestroyWindow` if *m_hWnd* is non-NULL, this does not lead to infinite recursion because the handle will be detached and NULL during the cleanup phase. +Classes designed for allocation alone on the heap override the `PostNcDestroy` method to perform a `delete this;`. This statement will free any memory associated with the C++ object. Even though the default `CWnd` destructor calls `DestroyWindow` if *`m_hWnd`* isn't `NULL`, this call doesn't lead to infinite recursion because the handle will be detached and `NULL` during the cleanup phase. > [!NOTE] -> The system usually calls `CWnd::PostNcDestroy` after it processes the Windows WM_NCDESTROY message and the `HWND` and the C++ window object are no longer connected. The system will also call `CWnd::PostNcDestroy` in the implementation of most [CWnd::Create](../mfc/reference/cwnd-class.md#create) calls if failure occurs. The auto cleanup rules are described later in this topic. +> The system usually calls `CWnd::PostNcDestroy` after it processes the Windows `WM_NCDESTROY` message and the `HWND` and the C++ window object are no longer connected. The system will also call `CWnd::PostNcDestroy` in the implementation of most [`CWnd::Create`](../mfc/reference/cwnd-class.md#create) calls if failure occurs. The auto cleanup rules are described later in this article. -## Auto Cleanup Classes +## Auto cleanup classes -The following classes are not designed for auto-cleanup. They are typically embedded in other C++ objects or on the stack: +The following classes aren't designed for auto-cleanup. They're typically embedded in other C++ objects or on the stack: - All standard Windows controls (`CStatic`, `CEdit`, `CListBox`, and so on). @@ -57,34 +57,34 @@ The following classes are not designed for auto-cleanup. They are typically embe - The default dialogs created by ClassWizard. -The following classes are designed for auto-cleanup. They are typically allocated by themselves on the heap: +The following classes are designed for auto-cleanup. They're typically allocated by themselves on the heap: - Main frame windows (derived directly or indirectly from `CFrameWnd`). - View windows (derived directly or indirectly from `CView`). -If you want to break these rules, you must override the `PostNcDestroy` method in your derived class. To add auto-cleanup to your class, call your base class and then do a **delete this**. To remove auto-cleanup from your class, call `CWnd::PostNcDestroy` directly instead of the `PostNcDestroy` method of your direct base class. +If you want to break these rules, you must override the `PostNcDestroy` method in your derived class. To add auto-cleanup to your class, call your base class and then do a `delete this;`. To remove auto-cleanup from your class, call `CWnd::PostNcDestroy` directly instead of the `PostNcDestroy` method of your direct base class. The most common use of changing auto cleanup behavior is to create a modeless dialog that can be allocated on the heap. -## When to Call delete +## When to call `delete` We recommend that you call `DestroyWindow` to destroy a Windows object, either the C++ method or the global `DestroyWindow` API. -Do not call the global `DestroyWindow` API to destroy a MDI Child window. You should use the virtual method `CWnd::DestroyWindow` instead. +Don't call the global `DestroyWindow` API to destroy an MDI Child window. You should use the virtual method `CWnd::DestroyWindow` instead. -For C++ Window objects that do not perform auto-cleanup, using the **`delete`** operator can cause a memory leak when you try to call `DestroyWindow` in the `CWnd::~CWnd` destructor if the VTBL does not point to the correctly derived class. This occurs because the system cannot find the appropriate destroy method to call. Using `DestroyWindow` instead of **`delete`** avoids these problems. Because this can be a subtle error, compiling in debug mode will generate the following warning if you are at risk. +For C++ Window objects that don't perform auto-cleanup, using the **`delete`** operator can cause a memory leak when you try to call `DestroyWindow` in the `CWnd::~CWnd` destructor if the `VTBL` doesn't point to the correctly derived class. The leak occurs because the system can't find the appropriate destroy method to call. Using `DestroyWindow` instead of **`delete`** avoids these problems. Because this error can be subtle, compiling in debug mode will generate the following warning if you are at risk. -``` +```Output Warning: calling DestroyWindow in CWnd::~CWnd OnDestroy or PostNcDestroy in derived class will not be called ``` -In the case of C++ Windows objects that do perform auto-cleanup, you must call `DestroyWindow`. If you use the **`delete`** operator directly, the MFC diagnostic memory allocator will notify you that you are freeing memory two times. The two occurrences are your first explicit call and the indirect call to **delete this** in the auto-cleanup implementation of `PostNcDestroy`. +For C++ Windows objects that do perform auto-cleanup, you must call `DestroyWindow`. If you use the **`delete`** operator directly, the MFC diagnostic memory allocator will notify you that you're freeing memory two times. The two occurrences are your first explicit call and the indirect call to `delete this;` in the auto-cleanup implementation of `PostNcDestroy`. -After calling `DestroyWindow` on a non-auto-cleanup object, the C++ object will still be around, but *m_hWnd* will be NULL. After calling `DestroyWindow` on an auto-cleanup object, the C++ object will be gone, freed by the C++ delete operator in the auto-cleanup implementation of `PostNcDestroy`. +After you call `DestroyWindow` on a non-auto-cleanup object, the C++ object will still be around, but *`m_hWnd`* will be `NULL`. After you call `DestroyWindow` on an auto-cleanup object, the C++ object will be gone, freed by the C++ delete operator in the auto-cleanup implementation of `PostNcDestroy`. ## See also -[Technical Notes by Number](../mfc/technical-notes-by-number.md)
-[Technical Notes by Category](../mfc/technical-notes-by-category.md) +[Technical notes by number](../mfc/technical-notes-by-number.md)\ +[Technical notes by category](../mfc/technical-notes-by-category.md) diff --git a/docs/mfc/tn021-command-and-message-routing.md b/docs/mfc/tn021-command-and-message-routing.md index 611ecc09d5..597613bdc7 100644 --- a/docs/mfc/tn021-command-and-message-routing.md +++ b/docs/mfc/tn021-command-and-message-routing.md @@ -190,7 +190,7 @@ MFC extends that to allow for scroll bar controls to be either child or siblings On a side note, there are two **CWnd** derived classes where the scroll bar styles specified at create time are trapped and not passed to Windows. When passed to a creation routine, **WS_HSCROLL** and **WS_VSCROLL** can be independently set, but after creation cannot be changed. Of course, you should not directly test or set the WS_SCROLL style bits of the window that they created. -For **CMDIFrameWnd** the scroll bar styles you pass in to **Create** or **LoadFrame** are used to create the MDICLIENT. If you wish to have a scrollable MDICLIENT area (like the Windows Program Manager) be sure to set both scroll bar styles (**WS_HSCROLL** | **WS_VSCROLL**) for the style used to create the **CMDIFrameWnd**. +For **CMDIFrameWnd** the scroll bar styles you pass in to **Create** or **LoadFrame** are used to create the MDICLIENT. If you wish to have a scrollable MDICLIENT area (like the Windows Program Manager) be sure to set both scroll bar styles (`WS_HSCROLL | WS_VSCROLL`) for the style used to create the **CMDIFrameWnd**. For **CSplitterWnd** the scroll bar styles apply to the special shared scroll bars for the splitter regions. For static splitter windows, you will normally not set either scroll bar style. For dynamic splitter windows, you will usually have the scroll bar style set for the direction you will split, That is, **WS_HSCROLL** if you can split rows, **WS_VSCROLL** if you can split columns. diff --git a/docs/mfc/tn028-context-sensitive-help-support.md b/docs/mfc/tn028-context-sensitive-help-support.md index 1a5ff078b5..0999251621 100644 --- a/docs/mfc/tn028-context-sensitive-help-support.md +++ b/docs/mfc/tn028-context-sensitive-help-support.md @@ -74,7 +74,6 @@ To override this functionality and the way that a Help context is determined, yo ## WM_COMMANDHELP ``` - afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam) ``` @@ -103,7 +102,6 @@ If the user chooses a command from the menu, it is handled as help on that comma ## WM_HELPHITTEST ``` - afx_msg LRESULT CWnd::OnHelpHitTest( WPARAM, LPARAM lParam) ``` diff --git a/docs/mfc/tn031-control-bars.md b/docs/mfc/tn031-control-bars.md index 230cefbd0c..cdd945cff4 100644 --- a/docs/mfc/tn031-control-bars.md +++ b/docs/mfc/tn031-control-bars.md @@ -49,7 +49,7 @@ The `CControlBar` class gives standard implementation for: - Supporting the implementation of derived classes. -C++ control bar objects will usually be embedded as members of a `CFrameWnd` derived class, and will be cleaned up when the parent `HWND` and object are destroyed. If you need to allocate a control bar object on the heap, you can simply set the *m_bAutoDestruct* member to **TRUE** to make the control bar "**delete this**" when the `HWND` is destroyed. +C++ control bar objects will usually be embedded as members of a `CFrameWnd` derived class, and will be cleaned up when the parent `HWND` and object are destroyed. If you need to allocate a control bar object on the heap, you can simply set the *m_bAutoDestruct* member to **TRUE** to make the control bar invoke `delete this;` when the `HWND` is destroyed. > [!NOTE] > If you create your own `CControlBar`-derived class, rather than using one of MFC's derived classes, such as `CStatusBar`, `CToolBar`, or `CDialogBar`, you will need to set the *m_dwStyle* data member. This can be done in the override of `Create`: @@ -176,13 +176,13 @@ The six official Windows Interface Application Design Guide button styles are re - Up = 0 -- Mouse Down = TBBS_PRESSED (| any other style) +- Mouse Down = TBBS_PRESSED (\| any other style) - Disabled = TBBS_DISABLED - Down = TBBS_CHECKED -- Down Disabled = TBBS_CHECKED | TBBS_DISABLED +- Down Disabled = TBBS_CHECKED \| TBBS_DISABLED - Indeterminate = TBBS_INDETERMINATE diff --git a/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md b/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md index e0ab4fbfd9..efb943db14 100644 --- a/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md +++ b/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: TN035: Using Multiple Resource Files and Header Files with Visual C++" -title: "TN035: Using Multiple Resource Files and Header Files with Visual C++" +description: "Learn more about: TN035: Using multiple resource files and header files with Visual C++" +title: "TN035: Using multiple resource files and header files with Visual C++" ms.date: "11/04/2016" f1_keywords: ["vc.resources"] helpviewer_keywords: ["resource files, multiple", "TN035"] ms.assetid: 1f08ce5e-a912-44cc-ac56-7dd93ad73fb6 --- -# TN035: Using Multiple Resource Files and Header Files with Visual C++ +# TN035: Using multiple resource files and header files with Visual C++ > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -15,57 +15,64 @@ This note describes how the Visual C++ resource editor supports multiple resourc - When might you want to split a project into multiple resource files and/or header files, and how you do it -- How do you share a common header .H file between two .RC files +- How do you share a common header `.H` file between two `.RC` files -- How do you divide project resources into multiple .RC files +- How do you divide project resources into multiple `.RC` files -- How do you (and the tools) manage build dependencies between .RC, .CPP, and .H files +- How do you (and the tools) manage build dependencies between `.RC`, `.CPP`, and `.H` files -You should be aware that if you add an additional resource file to your project, ClassWizard will not recognize the resources in the added file. +You should be aware that if you add an additional resource file to your project, ClassWizard won't recognize the resources in the added file. This note is structured to answer the above questions as follows: -- **Overview of How Visual C++ Manages Resource Files and Header Files** provides an overview of how the Resource Set Includes command in Visual C++ lets you use multiple resource files and header files in the same project. +- **Overview of how Visual C++ manages resource files and header files** provides an overview of how the Resource Set Includes command in Visual C++ lets you use multiple resource files and header files in the same project. -- **Analysis of AppWizard-created .RC and .H Files** looks at the multiple resource and header files that are used by an AppWizard-created application. These files serve as a good model for additional resource files and header files you might want to add to your project. +- **Analysis of AppWizard-created `.RC` and `.H` Files** looks at the multiple resource and header files that are used by an AppWizard-created application. These files serve as a good model for additional resource files and header files you might want to add to your project. -- **Including Additional Header Files** describes where you might want to include multiple header files, and provides details how to do so. +- **Including additional header files** describes where you might want to include multiple header files, and provides details how to do so. -- **Sharing a Header File Between Two .RC Files** shows how you can share one header file between multiple .RC files in different projects, or perhaps in the same project. +- **Sharing a header file between two `.RC` files** shows how you can share one header file between multiple `.RC` files in different projects, or perhaps in the same project. -- **Using Multiple Resource Files in the Same Project** describes where you might want to break up your project into multiple .RC files, and provides details how to do so. +- **Using multiple resource files in the same project** describes where you might want to break up your project into multiple `.RC` files, and provides details how to do so. -- **Enforcement of Non-Editable Visual C++ Files** describes how you can make sure Visual C++ does not edit and unintentionally reformat a custom resource. +- **Enforcement of non-editable Visual C++ files** describes how you can make sure Visual C++ doesn't edit and unintentionally reformat a custom resource. -- **Managing Symbols Shared by Multiple Visual C++-Edited .RC Files** describes how to share the same symbols across multiple .RC files and how to avoid assigning duplicate ID numeric values. +- **Managing symbols shared by multiple Visual C++-edited `.RC` files** describes how to share the same symbols across multiple `.RC` files and how to avoid assigning duplicate ID numeric values. -- **Managing Dependencies Between .RC, .CPP, and .H Files** describes how Visual C++ avoids unnecessary recompiling .CPP files that are dependent on resource symbol files. +- **Managing dependencies between `.RC`, `.CPP`, and `.H` files** describes how Visual C++ avoids unnecessary recompiling `.CPP` files that are dependent on resource symbol files. -- **How Visual C++ Manages Set Includes Information** provides technical details about how Visual C++ keeps track of multiple (nested) .RC files and multiple header files that are #include'd by an .RC file. +- **How Visual C++ manages Set Includes information** provides technical details about how Visual C++ keeps track of multiple (nested) `.RC` files and multiple header files that are included by an `.RC` file. -## Overview of How Visual C++ Manages Resource Files and Header Files +## Overview of how Visual C++ manages resource files and header files -Visual C++ manages a single .RC resource file and a corresponding .H header file as a tightly coupled pair of files. When you edit and save resources in an .RC file, you indirectly edit and save symbols in the corresponding .H file. Although you can open and edit multiple .RC files at a time (using Visual C++'s MDI user interface) for any given .RC file you indirectly edit exactly one corresponding header file. +Visual C++ manages a single `.RC` resource file and a corresponding `.H` header file as a tightly coupled pair of files. When you edit and save resources in an `.RC` file, you indirectly edit and save symbols in the corresponding `.H` file. Although you can open and edit multiple `.RC` files at a time (using Visual C++'s MDI user interface), for any given `.RC` file you indirectly edit exactly one corresponding header file. -### Symbol Header File +### Resource View's Resource Includes dialog -By default, Visual C++ always names the corresponding header file RESOURCE.H, regardless of the name of the resource file (e.g., MYAPP.RC). Using the **Resource Includes** command from the **View** menu in Visual C++, you can change the name of this header file by updating the Symbol Header File file in the **Set Includes** dialog box. +To access the **Resource Includes**, open the **Resource View** then right-click the `.RC` file and select **Resource Includes**. -### Read-Only Symbol Directives +#### Symbol Header File -Although Visual C++ only edits one header file for any given .RC file, Visual C++ supports references to symbols defined in additional read-only header files. Using the **Resource Includes** command from the **View** menu in Visual C++, you can specify any number of additional read-only header files as Read-Only Symbol Directives. The "read-only" restriction means that when you add a new resource in the .RC file, you can use a symbol defined in the read-only header file; but if you delete the resource, the symbol still remains defined in the read-only header file. You cannot change the numeric value assigned to a read-only symbol. +By default, Visual C++ always names the corresponding header file `RESOURCE.H`, regardless of the name of the resource file (for example, `MYAPP.RC`). The **Symbol Header File:** section in the **Resource Includes** dialog in Visual C++, lets you change the name of this header file. Enter a new file name in the section's edit box. -### Compile-Time Directives +> [!NOTE] +> resource files not located in the same directory as the `.RC` file must prepend a relative path with escaped-'\\' to be read properly. + +#### Read-Only Symbol Directives + +Although Visual C++ only edits one header file for any given `.RC` file, Visual C++ supports references to symbols defined in additional read-only header files. The **Read-Only Symbol Directives:** section in the **Resource Includes** dialog lets you specify any number of additional read-only header files as Read-Only Symbol Directives. The "read-only" restriction means that when you add a new resource in the `.RC` file, you can use a symbol defined in the read-only header file. However, if you delete the resource, the symbol still remains defined in the read-only header file. You can't change the numeric value assigned to a read-only symbol. + +#### Compile-Time Directives -Visual C++ also supports nesting of resource files, where one .RC file is #include'd within another. When you edit a given .RC file using Visual C++, any resources in the #include'd files are not visible. But when you compile the .RC file, the #include'd files are also compiled. Using the **Resource Includes** command from the **View** menu in Visual C++, you can specify any number of #include'd .RC files as Compile-Time Directives. +Visual C++ also supports nesting of resource files, where one `.RC` file is included within another by using a `#include` directive. When you edit a given `.RC` file using Visual C++, any resources in the included files aren't visible. But when you compile the `.RC` file, the included files are also compiled. The **Compile-Time Directives:** section in the **Resources Includes** dialog lets you specify any number of `.RC` files to include as Compile-Time Directives. -Note what happens if you read into Visual C++ an .RC file that #include's another .RC file that is *not* specified as a Compile-Time Directive. This situation might arise when you bring to Visual C++ an .RC file that you had been previously maintaining manually with a text editor. When Visual C++ reads the #include'd .RC file, it merges the #include'd resources into the parent .RC file. When you save the parent .RC file, the #include statement, in effect, will be replaced by the #include'd resources. If you do not want this merge to happen, you should remove the #include statement from the parent .RC file *prior* to reading it into Visual C++; then using Visual C++, add back the same #include statement as a Compile-Time Directive. +Note what happens if you read into Visual C++ an `.RC` file that includes another `.RC` file that isn't* specified as a Compile-Time Directive. This situation might arise when you bring to Visual C++ an `.RC` file that you had been previously maintaining manually with a text editor. When Visual C++ reads the included `.RC` file, it merges the included resources into the parent `.RC` file. When you save the parent `.RC` file, the `#include` statement, in effect, will be replaced by the included resources. If you don't want this merge to happen, you should remove the `#include` statement from the parent `.RC` file *prior* to reading it into Visual C++; then using Visual C++, add back the same `#include` statement as a Compile-Time Directive. -Visual C++ saves in an .RC file the three kinds of above Set Includes information (Symbol Header File, Read-Only Symbol Directives, and Compile-Time Directives) in #include directives *and* in TEXTINCLUDE resources. The TEXTINCLUDE resources, an implementation detail that you do not normally need to deal with, are explained in [How Visual C++ Manages Set Includes Information](#_mfcnotes_tn035_set_includes). +Visual C++ saves in an `.RC` file the three kinds of above Set Includes information (Symbol Header File, Read-Only Symbol Directives, and Compile-Time Directives) in `#include` directives *and* in `TEXTINCLUDE` resources. The `TEXTINCLUDE` resources, an implementation detail that you don't normally need to deal with, are explained in [How Visual C++ manages set includes information](#_mfcnotes_tn035_set_includes). -## Analysis of AppWizard-Created .RC and .H Files +## Analysis of AppWizard-created `.RC` and `.H` files -Examining the application code produced by AppWizard provides insight into how Visual C++ manages multiple resource files and header files. The code excerpts examined below are from a MYAPP application produced by AppWizard using the default options. +Examining the application code produced by AppWizard provides insight into how Visual C++ manages multiple resource files and header files. The code excerpts examined below are from a `MYAPP` application produced by AppWizard using the default options. An AppWizard-created application uses multiple resource files and multiple header files, as summarized in the diagram below: @@ -83,10 +90,10 @@ An AppWizard-created application uses multiple resource files and multiple heade You can view these multiple file relationships using the Visual C++ File/Set Includes command. -MYAPP.RC\ +`MYAPP.RC`\ The application resource file that you edit using Visual C++. -RESOURCE.H is the application-specific header file. It is always named RESOURCE.H by AppWizard, consistent with Visual C++'s default naming of the header file. The #include for this header file is the first statement in the resource file (MYAPP.RC): +`RESOURCE.H` is the application-specific header file. It's always named `RESOURCE.H` by AppWizard, consistent with Visual C++'s default naming of the header file. The `#include` for this header file is the first statement in the resource file (`MYAPP.RC`): ```rc //Microsoft Visual C++ generated resource script @@ -94,22 +101,22 @@ RESOURCE.H is the application-specific header file. It is always named RESOURCE. #include "resource.h" ``` -RES\MYAPP.RC2\ -Contains resources that will not be edited by Visual C++ but will be included in the final compiled .EXE file. AppWizard creates no such resources by default, since Visual C++ can edit all of the standard resources, including the version resource (a new feature in this release). An empty file is generated by AppWizard in case you wish to add your own custom formatted resources to this file. +`RES\MYAPP.RC2`\ +Contains resources that won't be edited by Visual C++ but will be included in the final compiled `.EXE` file. AppWizard creates no such resources by default, since Visual C++ can edit all of the standard resources, including the version resource (a new feature in this release). An empty file is generated by AppWizard in case you wish to add your own custom formatted resources to this file. -If you use custom formatted resources, you can add them to RES\MYAPP.RC2 and edit them using the Visual C++ text editor. +If you use custom formatted resources, you can add them to `RES\MYAPP.RC2` and edit them using the Visual C++ text editor. -AFXRES.RC and AFXPRINT.RC contain standard resources required by certain features of the framework. Like RES\MYAPP.RC2, these two framework-provided resource files are #include'd at the end of MYAPP.RC, and they are specified in the Compile-Time Directives of the Set Includes dialog box. Thus, you do not directly view or edit these framework resources while you edit MYAPP.RC in Visual C++, but they are compiled into the application's binary .RES file and final .EXE file. For more information on the standard framework resources, including procedures for modifying them, see [Technical Note 23](../mfc/tn023-standard-mfc-resources.md). +`AFXRES.RC` and `AFXPRINT.RC` contain standard resources required by certain features of the framework. Like `RES\MYAPP.RC2`, these two framework-provided resource files are included at the end of `MYAPP.RC`, and they're specified in the Compile-Time Directives of the Set Includes dialog box. Thus, you don't directly view or edit these framework resources while you edit `MYAPP.RC` in Visual C++, but they're compiled into the application's binary `.RES` file and final `.EXE` file. For more information on the standard framework resources, including procedures for modifying them, see [Technical Note 23](../mfc/tn023-standard-mfc-resources.md). -AFXRES.H defines standard symbols, such as `ID_FILE_NEW`, used by the framework and specifically used in AFXRES.RC. AFXRES.H also #include's WINRES.H, which contains a subset of WINDOWS.H that are needed by Visual C++ generated .RC files as well as AFXRES.RC. The symbols defined in AFXRES.H are available as you edit the application resource file (MYAPP.RC). For example, `ID_FILE_NEW` is used for the File New menu item in MYAPP.RC's menu resource. You cannot change or delete these framework-defined symbols. +`AFXRES.H` defines standard symbols, such as `ID_FILE_NEW`, used by the framework and specifically used in `AFXRES.RC`. `AFXRES.H` also uses `#include` to include `WINRES.H`, which contains a subset of `WINDOWS.H` that's needed by Visual C++ generated `.RC` files and `AFXRES.RC`. The symbols defined in `AFXRES.H` are available as you edit the application resource file (`MYAPP.RC`). For example, `ID_FILE_NEW` is used for the `File` `New` menu item in the `MYAPP.RC` file's menu resource. You can't change or delete these framework-defined symbols. -## Including Additional Header Files +## Including additional header files -The AppWizard-created application includes only two header files: RESOURCE.H and AFXRES.H. Only RESOURCE.H is application-specific. You may need to include additional read-only header files in the following cases: +The AppWizard-created application includes only two header files: `RESOURCE.H` and `AFXRES.H`. Only `RESOURCE.H` is application-specific. You may need to include additional read-only header files in the following cases: The header file is provided by an external source, or you want to share the header file among multiple projects or multiple parts of the same project. -The header file has formatting and comments that you do not want Visual C++ to change or filter out when it saves the file. For example, maybe you want to preserve #define's that use symbolic arithmetic such as: +The header file has formatting and comments that you don't want Visual C++ to change or filter out when it saves the file. For example, maybe you want to preserve #define's that use symbolic arithmetic such as: ```h #define RED 0 @@ -121,7 +128,7 @@ The header file has formatting and comments that you do not want Visual C++ to c #define ID_GREEN_BUTTON (ID_COLOR_BUTTON + GREEN) ``` -You can include additional read-only header files by using the **Resource Includes** command to specify the #include statement as a second Read-Only Symbol Directive, as in: +You can include additional read-only header files by using the **Resource Includes** command to specify the `#include` statement as a second Read-Only Symbol Directive, as in: ```rc #include "afxres.h" @@ -143,9 +150,9 @@ The new file relationship diagram now looks like this: AFXPRINT.RC ``` -## Sharing a Header File Between Two .RC Files +## Sharing a header file between two `.RC` files -You may want to share a header file between two .RC files that are in different projects, or possibly the same project. To do so, simply apply the Read-Only Directives technique described above to both .RC files. In the case where the two .RC files are for different applications (different projects), the result is illustrated in the following diagram: +You may want to share a header file between two `.RC` files that are in different projects, or possibly the same project. To do so, apply the Read-Only Directives technique described above to both `.RC` files. In the case where the two `.RC` files are for different applications (different projects), the result is illustrated in the following diagram: ```Diagram RESOURCE.H AFXRES.H RESOURCE.H @@ -159,23 +166,23 @@ RES\MYAPP1.RC2 AFXRES.RC RES\MYAPP2.RC2 AFXPRINT.RC ``` -The case where the second header file is shared by two .RC files in the same application (project) is discussed below. +The case where the second header file is shared by two `.RC` files in the same application (project) is discussed below. -## Using Multiple Resource Files in the Same Project +## Using multiple resource files in the same project -Visual C++ and the Resource Compiler support multiple .RC files in the same project through #include's of one .RC file within another. Multiple nesting is allowed. There are various reasons to split your project's resources into multiple .RC files: +Visual C++ and the Resource Compiler support multiple `.RC` files in the same project through `#include` directives that include one `.RC` file within another. Multiple nesting is allowed. There are various reasons to split your project's resources into multiple `.RC` files: -- It is easier to manage a large number of resources among multiple project team members if you split the resources into multiple .RC files. If you use a source control management package for checking out files and checking in changes, splitting the resources into multiple .RC files will give you finer control over managing changes to resources. +- It's easier to manage a large number of resources among multiple project team members if you split the resources into multiple `.RC` files. If you use a source control management package for checking out files and checking in changes, splitting the resources into multiple `.RC` files will give you finer control over managing changes to resources. -- If you want to use preprocessor directives, such as #ifdef, #endif, and #define, for portions of your resources, you must isolate them in read-only resources that will be compiled by the Resource Compiler. +- If you want to use preprocessor directives, such as `#ifdef`, `#endif`, and `#define`, for portions of your resources, you must isolate them in read-only resources that will be compiled by the Resource Compiler. -- Component .RC files will load and save faster in Visual C++ than one composite .RC file. +- Component `.RC` files will load and save faster in Visual C++ than one composite `.RC` file. -- If you want to maintain a resource with a text editor in a human-readable form, you should keep it in a .RC file separate from the one Visual C++ edits. +- If you want to maintain a resource with a text editor in a human-readable form, you should keep it in a `.RC` file separate from the one Visual C++ edits. -- If you need to keep a user-defined resource in a binary or text form that is interpretable by another specialized data editor, then you should keep it in a separate .RC file so Visual C++ does not change the format to hexadecimal data. The .WAV (sound) file resources in the MFC Advanced Concepts sample [SPEAKN](../overview/visual-cpp-samples.md) are a good example. +- If you need to keep a user-defined resource in a binary or text form that is interpretable by another specialized data editor, then you should keep it in a separate `.RC` file so Visual C++ doesn't change the format to hexadecimal data. The `.WAV` (sound) file resources in the MFC Advanced Concepts sample [SPEAKN](../overview/visual-cpp-samples.md) are a good example. -You can #include a SECOND.RC in the Compile-Time Directives in the Set Includes dialog box: +You can include `SECOND.RC` in the Compile-Time Directives in the Set Includes dialog box: ```h #include "res\myapp.rc2" // non-Visual C++ edited resources @@ -200,11 +207,11 @@ The result is illustrated in the following diagram: AFXPRINT.RC ``` -Using Compile-Time Directives, you can organize your Visual C++-editable and non-editable resources into multiple .RC files, where the "master" MYAPP.RC does nothing but #include the other .RC files. If you are using a Visual Studio C++ project .MAK file, then you should include the "master" .RC file in the project so that all the #include'd resources are compiled with your application. +Using Compile-Time Directives, you can organize your Visual C++-editable and non-editable resources into multiple `.RC` files, where the main `MYAPP.RC` does nothing but `#include` the other `.RC` files. If you're using a Visual Studio C++ project `.MAK` file, then you should include the main `.RC` file in the project so that all the included resources are compiled with your application. -## Enforcement of Noneditable Visual C++ Files +## Enforcement of non-editable Visual C++ files -The AppWizard-created RES\MYAPP.RC2 file is an example of a file that contains resources that you do *not* want to accidentally read into Visual C++ and then write it back out with loss of formatting information. To protect against this, place the following lines in the beginning of the RES\MYAPP.RC2 file: +The AppWizard-created `RES\MYAPP.RC2` file is an example of a file that contains resources that you don't want to accidentally read into Visual C++ and then write back out with loss of formatting information. To protect against this problem, place the following lines in the beginning of the `RES\MYAPP.RC2` file: ```rc2 #ifdef APSTUDIO_INVOKED @@ -212,17 +219,17 @@ The AppWizard-created RES\MYAPP.RC2 file is an example of a file that contains r #endif //APSTUDIO_INVOKED ``` -When Visual C++ compiles the .RC file, it defines `APSTUDIO_INVOKED` as well as `RC_INVOKED`. If the AppWizard-created file structure is corrupted and Visual C++ reads the #error line above, it reports a fatal error and abort the reading of the .RC file. +When Visual C++ compiles the `.RC` file, it defines both `APSTUDIO_INVOKED` and `RC_INVOKED`. If the AppWizard-created file structure is corrupted and Visual C++ reads the #error line above, it reports a fatal error and aborts the reading of the `.RC` file. -## Managing Symbols Shared by Multiple Visual C++-Edited .RC Files +## Managing symbols shared by multiple Visual C++-edited `.RC` files -Two issues arise when you split up your resources into multiple .RC files that you want to edit separately in Visual C++: +Two issues arise when you split up your resources into multiple `.RC` files that you want to edit separately in Visual C++: -- You might want to share the same symbols across multiple .RC files. +- You might want to share the same symbols across multiple `.RC` files. - You need to help Visual C++ avoid assigning the same ID numeric values to distinct resources (symbols). -The following diagram illustrates an organization of .RC and .H files that deals with the first issue: +The following diagram illustrates an organization of `.RC` and `.H` files that deals with the first issue: ```Diagram MYAPP.RC @@ -234,13 +241,13 @@ MYSTRS.H / MYSHARED.H \ MYMENUS.H MYSTRS.RC MYMENUS.RC ``` -In this example, string resources are kept in one resource file, MYSTRS.RC, and menus are kept in another, MYMENUS.RC. Some symbols, such as for commands, may need to be shared between the two files. For example, a ID_TOOLS_SPELL may be the menu command ID for the Spell item in a Tools menu; and it may also be the string ID of the command prompt displayed by the framework in the application's main window status bar. +In this example, string resources are kept in one resource file, `MYSTRS.RC`, and menus are kept in another, `MYMENUS.RC`. Some symbols, such as for commands, may need to be shared between the two files. For example, a `ID_TOOLS_SPELL` may be the menu command ID for the Spell item in a Tools menu; and it may also be the string ID of the command prompt displayed by the framework in the application's main window status bar. -The ID_TOOLS_SPELL symbol is kept in the shared header file, MYSHARED.H. You maintain this shared header file manually with a text editor; Visual C++ does not directly edit it. In the two resource files MYSTRS.RC and MYMENUS.RC, you specify #include MYSHARED.H in the Read-Only Directives for MYAPP.RC, using the **Resource Includes** command, as described earlier. +The `ID_TOOLS_SPELL` symbol is kept in the shared header file, `MYSHARED.H`. You maintain this shared header file manually with a text editor; Visual C++ doesn't directly edit it. In the two resource files `MYSTRS.RC` and `MYMENUS.RC`, you specify `#include "MYSHARED.H"` in the Read-Only Directives for `MYAPP.RC`, using the **Resource Includes** command, as described earlier. -It is most convenient to anticipate a symbol you will share before you attempt to use it to identify any resource. Add the symbol to the shared header file and, if you have not already #include'd the shared header file in the Read-Only Directives for the .RC file, do so before using the symbol. If you did not anticipate sharing the symbol in this way, then you will have to manually (using a text editor) move the #define statement for the symbol from, say, MYMENUS.H to MYSHARED.H before using it in MYSTRS.RC. +It's most convenient to anticipate a symbol you'll share before you attempt to use it to identify any resource. Add the symbol to the shared header file and, if you haven't already included the shared header file in the Read-Only Directives for the `.RC` file, do so before using the symbol. If you didn't anticipate sharing the symbol in this way, then you'll have to manually (using a text editor) move the #define statement for the symbol from, say, `MYMENUS.H` to `MYSHARED.H` before using it in `MYSTRS.RC`. -When you manage symbols in multiple .RC files, you also must help Visual C++ avoid assigning the same ID numeric values to distinct resources (symbols). For any given .RC file, Visual C++ incrementally assigns IDs in each of four ID domains. Between editing sessions, Visual C++ keeps track of the last ID it assigned in each of the domains in the symbol header file for the .RC file. Here is what the APS_NEXT values are for an empty (new) .RC file: +When you manage symbols in multiple `.RC` files, you also must help Visual C++ avoid assigning the same ID numeric values to distinct resources (symbols). For any given `.RC` file, Visual C++ incrementally assigns IDs in each of four ID domains. Between editing sessions, Visual C++ keeps track of the last ID it assigned in each of the domains in the Symbol Header File for the `.RC` file. Here's what the `APS_NEXT` values are for an empty (new) `.RC` file: ```rc #define _APS_NEXT_RESOURCE_VALUE 101 @@ -257,11 +264,11 @@ When you manage symbols in multiple .RC files, you also must help Visual C++ avo `_APS_NEXT_SYMED_VALUE` is the next symbol value that will be issued when you manually assign a symbol value using the New command in the Symbol Browser. -Visual C++ starts with slightly higher values that the lowest legal value when creating a new .RC file. AppWizard will also initialize these values to something more appropriate for MFC applications. For more information about ID value ranges, see [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md). +Visual C++ starts with slightly higher values that the lowest legal value when creating a new `.RC` file. AppWizard will also initialize these values to something more appropriate for MFC applications. For more information about ID value ranges, see [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md). -Now every time you create a new resource file, even in the same project, Visual C++ defines the same `_APS_NEXT_` values. This means that if you add, say, multiple dialogs in two different .RC files, it is highly likely that the same #define value will be assigned to different dialogs. For example, IDD_MY_DLG1 in the first .RC file might be assigned the same number, 101, as IDD_MY_DLG2 in a second .RC file. +Now every time you create a new resource file, even in the same project, Visual C++ defines the same `_APS_NEXT_` values. It means that if you add, say, multiple dialogs in two different `.RC` files, it's highly likely that the same #define value will be assigned to different dialogs. For example, `IDD_MY_DLG1` in the first `.RC` file might be assigned the same number, 101, as `IDD_MY_DLG2` in a second `.RC` file. -To avoid this, you should reserve a separate numeric range for each of the four domains of IDs in the respective .RC files. Do this by manually updating the `_APS_NEXT` values in each of the .RC files **before** you start adding resources. For example, if the first .RC file uses the default `_APS_NEXT` values, then you might want to assign the following `_APS_NEXT` values to the second .RC file: +To avoid this issue, you should reserve a separate numeric range for each of the four domains of IDs in the respective `.RC` files. Set the ranges by manually updating the `_APS_NEXT` values in each of the `.RC` files **before** you start adding resources. For example, if the first `.RC` file uses the default `_APS_NEXT` values, then you might want to assign the following `_APS_NEXT` values to the second `.RC` file: ```rc #define _APS_NEXT_RESOURCE_VALUE 2000 @@ -270,23 +277,23 @@ To avoid this, you should reserve a separate numeric range for each of the four #define _APS_NEXT_SYMED_VALUE 2000 ``` -Of course, it is still possible that Visual C++ will assign so many IDs in the first .RC file that the numeric values start to overlap those reserved for the second .RC file. You should reserve sufficiently large ranges so that this does not happen. +Of course, it's still possible that Visual C++ will assign so many IDs in the first `.RC` file that the numeric values start to overlap the ones reserved for the second `.RC` file. You should reserve sufficiently large ranges so that this collision doesn't happen. -## Managing Dependencies Between .RC, .CPP, and .H Files +## Managing dependencies between `.RC`, `.CPP`, and `.H` files -When Visual C++ saves an .RC file, it also saves symbol changes to the corresponding RESOURCE.H file. Any of your .CPP files that refer to resources in the .RC file must #include the RESOURCE.H file, usually from within your project's master header file. This leads to an undesirable side-effect because of the development environment's internal project management which scans source files for header dependencies. Every time you add a new symbol in Visual C++, all the .CPP files that #include RESOURCE.H would need to be recompiled. +When Visual C++ saves an `.RC` file, it also saves symbol changes to the corresponding `RESOURCE.H` file. Any of your `.CPP` files that refer to resources in the `.RC` file must use `#include` to include the `RESOURCE.H` file, usually from within your project's main header file. This inclusion leads to an undesirable side-effect because of the development environment's internal project management, which scans source files for header dependencies. Every time you add a new symbol in Visual C++, all the `.CPP` files that have `#include "RESOURCE.H"` directives would need to be recompiled. -Visual C++, circumvents the dependency on RESOURCE.H by including the following comment as the first line of the RESOURCE.H file: +Visual C++, circumvents the dependency on `RESOURCE.H` by including the following comment as the first line of the `RESOURCE.H` file: ```h //{{NO_DEPENDENCIES}} ``` -The development environment interprets this comment by ignoring the changes to RESOURCE.H so that dependent .CPP files will not need to be recompiled. +The development environment interprets this comment by ignoring the changes to `RESOURCE.H` so that dependent `.CPP` files won't need to be recompiled. -Visual C++ always adds the //{{NO_DEPENDENCIES}} comment line to a .RC file when it saves the file. In some cases, circumventing of the build dependency on RESOURCE.H may lead to run-time errors undetected at link time. For example, if you use the Symbol Browser to change the numeric value assigned to a symbol for a resource, the resource will not be correctly found and loaded at application run-time if the .CPP file referring to the resource is not recompiled. In such cases, you should explicitly recompile any .CPP files that you know are affected by the symbol changes in RESOURCE.H or select **Rebuild All**. If you have the need to frequently change symbol values for a certain group of resources, you will probably find it more convenient and safer to break out these symbols into a separate read-only header file, as described in the above section [Including Additional Header Files](#_mfcnotes_tn035_including). +Visual C++ always adds the `//{{NO_DEPENDENCIES}}` comment line to a `.RC` file when it saves the file. In some cases, circumventing of the build dependency on `RESOURCE.H` may lead to run-time errors undetected at link time. For example, if you use the Symbol Browser to change the numeric value assigned to a symbol for a resource, the resource won't be correctly found and loaded at application run-time if the `.CPP` file referring to the resource isn't recompiled. In such cases, you should explicitly recompile any `.CPP` files that you know are affected by the symbol changes in `RESOURCE.H` or select **Rebuild All**. If you have the need to frequently change symbol values for a certain group of resources, you'll probably find it more convenient and safer to break out these symbols into a separate read-only header file, as described in the above section [Including Additional Header Files](#_mfcnotes_tn035_including). -## How Visual C++ Manages Set Includes Information +## How Visual C++ manages Set Includes information As discussed above, the File menu Set Includes command lets you specify three types of information: @@ -296,29 +303,29 @@ As discussed above, the File menu Set Includes command lets you specify three ty - Compile-Time Directives -The following describes how Visual C++ maintains this information in a .RC file. You do not need this information to use Visual C++, but it may enhance your understanding so that you can more confidently use the Set Includes feature. +The following table describes how Visual C++ maintains this information in a `.RC` file. You don't need this information to use Visual C++, but it may enhance your understanding so that you can more confidently use the Set Includes feature. -Each of the above three types of Set Includes information is stored in the .RC file in two forms: (1) as #include or other directives interpretable by the Resource Compiler, and (2) as special TEXTINCLUDE resources interpretable only by Visual C++. +Each of the above three types of Set Includes information is stored in the `.RC` file in two forms: (1) as `#include` or other directives interpretable by the Resource Compiler, and (2) as special `TEXTINCLUDE` resources interpretable only by Visual C++. -The purpose of the TEXTINCLUDE resource is to safely store Set Include information in a form that is readily presentable in Visual C++'s **Set Includes** dialog box. TEXTINCLUDE is a *resource type* defined by Visual C++. Visual C++ recognizes three specific TEXTINCLUDE resources that have the resource identification numbers 1, 2 and 3: +The purpose of the `TEXTINCLUDE` resource is to safely store Set Include information in a form that is readily presentable in Visual C++'s **Set Includes** dialog box. `TEXTINCLUDE` is a *resource type* defined by Visual C++. Visual C++ recognizes three specific `TEXTINCLUDE` resources that have the resource identification numbers 1, 2 and 3: -|TEXTINCLUDE resource ID|Type of Set Includes information| +|`TEXTINCLUDE` resource ID|Type of Set Includes information| |-----------------------------|--------------------------------------| |1|Symbol Header File| |2|Read-Only Symbol Directives| |3|Compile-Time Directives| -Each of the three types of Set Includes information is illustrated by the default MYAPP.RC and RESOURCE.H files created by AppWizard, as described below. The extra \0 and "" tokens between BEGIN and END blocks are required by the RC syntax to specify zero terminated strings and the double quote character respectively. +Each of the three types of Set Includes information is illustrated by the default `MYAPP.RC` and `RESOURCE.H` files created by AppWizard, as described below. The extra `\0` and `""` tokens between `BEGIN` and `END` blocks are required by the RC syntax to specify zero terminated strings and the double quote character respectively. ### Symbol Header File -The form of the Symbol Header File information interpreted by the Resource Compiler is simply a #include statement: +The form of the Symbol Header File information interpreted by the Resource Compiler is simply a `#include` statement: ```rc #include "resource.h" ``` -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 1 TEXTINCLUDE DISCARDABLE @@ -329,13 +336,13 @@ END ### Read-Only Symbol Directives -Read-Only Symbol Directives are included at the top of MYAPP.RC in the following form interpretable by the Resource Compiler: +Read-Only Symbol Directives are included at the top of `MYAPP.RC` in the following form interpretable by the Resource Compiler: ```rc #include "afxres.h" ``` -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 2 TEXTINCLUDE DISCARDABLE @@ -347,7 +354,7 @@ END ### Compile-Time Directives -Compile-Time Directives are included at the end of MYAPP.RC in the following form interpretable by the Resource Compiler: +Compile-Time Directives are included at the end of `MYAPP.RC` in the following form interpretable by the Resource Compiler: ```rc #ifndef APSTUDIO_INVOKED @@ -362,9 +369,9 @@ Compile-Time Directives are included at the end of MYAPP.RC in the following for #endif // not APSTUDIO_INVOKED ``` -The #ifndef APSTUDIO_INVOKED directive instructs Visual C++ to skip over Compile-Time Directives. +The `#ifndef APSTUDIO_INVOKED` directive instructs Visual C++ to skip over Compile-Time Directives. -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 3 TEXTINCLUDE DISCARDABLE diff --git a/docs/mfc/tn038-mfc-ole-iunknown-implementation.md b/docs/mfc/tn038-mfc-ole-iunknown-implementation.md index a7e7375d13..f9dd6560fb 100644 --- a/docs/mfc/tn038-mfc-ole-iunknown-implementation.md +++ b/docs/mfc/tn038-mfc-ole-iunknown-implementation.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: TN038: MFC/OLE IUnknown Implementation" title: "TN038: MFC-OLE IUnknown Implementation" +description: "Learn more about: TN038: MFC/OLE IUnknown Implementation" ms.date: "06/28/2018" helpviewer_keywords: ["aggregation macros [MFC]", "COM interfaces, base interface", "IUnknown interface", "END_INTERFACE_MAP macro [MFC]", "TN038", "BEGIN_INTERFACE_PART macro [MFC]", "DECLARE_INTERFACE_MAP macro [MFC]", "BEGIN_INTERFACE_MAP macro [MFC]", "OLE [MFC], implementing IUnknown interface", "METHOD_PROLOGUE macro [MFC]", "STDMETHOD macro [MFC]", "END_INTERFACE_PART macro [MFC]", "INTERFACE_PART macro"] -ms.assetid: 19d946ba-beaf-4881-85c6-0b598d7f6f11 --- # TN038: MFC/OLE IUnknown Implementation @@ -518,7 +517,7 @@ END_INTERFACE_PART(MyAdviseSink) would define a local class called XMyAdviseSink derived from IAdviseSink, and a member of the class in which it is declared called m_xMyAdviseSink.Note: > [!NOTE] -> The lines beginning with `STDMETHOD`_ are essentially copied from OLE2.H and modified slightly. Copying them from OLE2.H can reduce errors that are hard to resolve. +> The lines beginning with `STDMETHOD_` are essentially copied from OLE2.H and modified slightly. Copying them from OLE2.H can reduce errors that are hard to resolve. ### BEGIN_INTERFACE_MAP and END_INTERFACE_MAP — Macro Descriptions diff --git a/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md b/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md index e4ea7fce5a..9838cef62c 100644 --- a/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md +++ b/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md @@ -276,7 +276,7 @@ At this point, OCLIENT is a functional OLE container application. It is possible One of the most interesting features of OLE is in-place activation (or "Visual Editing"). This feature allows the server application to take over portions of the container's user interface to provided a more seamless editing interface for the user. To implement in-place activation to OCLIENT, some special resources need to be added, as well as some additional code. These resources and the code are normally provided by AppWizard — in fact, much of the code here was borrowed directly from a fresh AppWizard application with "Container" support. -First of all, it is necessary to add a menu resource to be used when there is an item which is in-place active. You can create this extra menu resource in Visual C++ by copying the IDR_OCLITYPE resource and removing all but the File and Window pop-ups. Two separator bars are inserted between the File and Window pop-ups to indicate the separation of groups (it should look like: File || Window). For more information on what these separators mean and how the server and container menus are merged see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). +First of all, it is necessary to add a menu resource to be used when there is an item which is in-place active. You can create this extra menu resource in Visual C++ by copying the IDR_OCLITYPE resource and removing all but the File and Window pop-ups. Two separator bars are inserted between the File and Window pop-ups to indicate the separation of groups (it should look like: `File || Window`). For more information on what these separators mean and how the server and container menus are merged see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). Once you have these menus created, you need to let the framework know about them. This is done by calling `CDocTemplate::SetContainerInfo` for the document template before you add it to the document template list in your InitInstance. The new code to register the document template looks like this: @@ -629,7 +629,7 @@ To add "Visual Editing" (or in-place activation) to this server application, the - You need to tell the framework about these special resources and classes. -The menu resource is easy to create. Run Visual C++, copy the menu resource IDR_HIERSVRTYPE to a menu resource called IDR_HIERSVRTYPE_SRVR_IP. Modify the menu so that only the Edit and Help menu popups are left. Add two separators to the menu in between the Edit and Help menus (it should look like: Edit || Help). For more information on what these separators mean and how the server and container menus are merged, see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). +The menu resource is easy to create. Run Visual C++, copy the menu resource IDR_HIERSVRTYPE to a menu resource called IDR_HIERSVRTYPE_SRVR_IP. Modify the menu so that only the Edit and Help menu popups are left. Add two separators to the menu in between the Edit and Help menus (it should look like: `Edit || Help`). For more information on what these separators mean and how the server and container menus are merged, see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). The bitmap for the subset toolbar can be easily created by copying the one from a fresh AppWizard generated application with a "Server" option checked. This bitmap can then be imported into Visual C++. Be sure to give the bitmap an ID of IDR_HIERSVRTYPE_SRVR_IP. diff --git a/docs/mfc/toc.yml b/docs/mfc/toc.yml index b5010afabe..eff745b744 100644 --- a/docs/mfc/toc.yml +++ b/docs/mfc/toc.yml @@ -1025,7 +1025,7 @@ items: href: creating-modeless-dialog-boxes.md - name: Using a dialog template in memory href: using-a-dialog-template-in-memory.md - - name: Setting the dialog box’s background color + - name: Setting the dialog box's background color href: setting-the-dialog-boxs-background-color.md - name: Initializing the dialog box href: initializing-the-dialog-box.md @@ -2916,5 +2916,9 @@ items: href: reference/adding-atl-support-to-your-mfc-project.md - name: Details of ATL support added by the ATL wizard href: reference/details-of-atl-support-added-by-the-atl-wizard.md + - name: Add a method to an IDL interface in a MFC project + href: reference/add-idl-mfc-method-wizard.md + - name: Add a property to an IDL interface in a MFC project + href: reference/add-interface-definition-library-mfc-property-wizard.md - name: MFC class wizard - href: reference/mfc-class-wizard.md \ No newline at end of file + href: reference/mfc-class-wizard.md \ No newline at end of file diff --git a/docs/mfc/walkthrough-adding-a-ctaskdialog-to-an-application.md b/docs/mfc/walkthrough-adding-a-ctaskdialog-to-an-application.md index 6a21fdfad1..1174ea2988 100644 --- a/docs/mfc/walkthrough-adding-a-ctaskdialog-to-an-application.md +++ b/docs/mfc/walkthrough-adding-a-ctaskdialog-to-an-application.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Walkthrough: Adding a CTaskDialog to an Application" +description: "Learn how to add a CTaskDialog to a MFC application" title: "Walkthrough: Adding a CTaskDialog to an Application" -ms.date: "04/25/2019" +ms.date: "2/7/2025" helpviewer_keywords: ["CTaskDialog, adding", "walkthroughs [MFC], dialogs"] -ms.assetid: 3a62abb8-2d86-4bec-bdb8-5784d5f9a9f8 --- -# Walkthrough: Adding a CTaskDialog to an Application +# Walkthrough: Adding a CTaskDialog to an application -This walkthrough introduces the [CTaskDialog Class](../mfc/reference/ctaskdialog-class.md) and shows you how to add one to your application. +This walkthrough introduces the [`CTaskDialog` class](../mfc/reference/ctaskdialog-class.md) and shows how to add it to your application. -The `CTaskDialog` is a task dialog box that replaces the Windows message box in Windows Vista or later. The `CTaskDialog` improves the original message box and adds functionality. The Windows message box is still supported in Visual Studio. +The `CTaskDialog` is a task dialog box that replaces the Windows message box in Windows Vista or later. The `CTaskDialog` improves on the original message box and adds functionality. The Windows message box is still supported in Visual Studio. > [!NOTE] -> Versions of Windows earlier than Windows Vista do not support the `CTaskDialog`. You must program an alternative dialog box option if you want to show a message to a user who runs your application on an earlier version of Windows. You can use the static method [CTaskDialog::IsSupported](../mfc/reference/ctaskdialog-class.md#issupported) to determine at run time whether a user's computer can display a `CTaskDialog`. In addition, the `CTaskDialog` is only available when your application is built with the Unicode library. +> Versions of Windows earlier than Windows Vista don't support the `CTaskDialog`. You must program an alternative dialog box option if you want to show a message to a user who runs your application on an earlier version of Windows. You can use the static method [CTaskDialog::IsSupported](../mfc/reference/ctaskdialog-class.md#issupported) to determine at run time whether a user's computer can display a `CTaskDialog`. In addition, the `CTaskDialog` is only available when your application is built with the Unicode library. The `CTaskDialog` supports several optional elements to gather and display information. For example, a `CTaskDialog` can display command links, customized buttons, customized icons, and a footer. The `CTaskDialog` also has several methods that enable you to query the state of the task dialog box to determine what optional elements the user selected. @@ -21,37 +20,30 @@ The `CTaskDialog` supports several optional elements to gather and display infor You need the following components to complete this walkthrough: - Visual Studio 2010 or later - - Windows Vista or later -## Replacing a Windows Message Box with a CTaskDialog - -The following procedure demonstrates the most basic use of the `CTaskDialog`, which is to replace the Windows message box. This example also changes the icon associated with the task dialog box. Changing the icon makes the `CTaskDialog` appear same to the Windows message box. - -### To Replace a Windows Message Box with a CTaskDialog +## Replace the Windows message box with a CTaskDialog -1. Use the **MFC Application Wizard** to create an MFC application with all the default settings. See [Walkthrough: Using the New MFC Shell Controls](walkthrough-using-the-new-mfc-shell-controls.md) for instructions on how to open the wizard for your version of Visual Studio. +The following demonstrates the most basic use of the `CTaskDialog`, which is to replace the Windows message box. This example also changes the icon associated with the task dialog box. Changing the icon makes the `CTaskDialog` appear similar to the Windows message box. +1. Use the **MFC Application Wizard** to create a Microsoft Foundation Classes (MFC) application with all the default settings. See [Walkthrough: Using the New MFC Shell Controls](walkthrough-using-the-new-mfc-shell-controls.md) for instructions on how to open the wizard for your version of Visual Studio. 1. Call it *MyProject*. - -1. Use the **Solution Explorer** to open the file MyProject.cpp. - +1. Use the **Solution Explorer** to open `MyProject.cpp`. 1. Add `#include "afxtaskdialog.h"` after the list of includes. - 1. Find the method `CMyProjectApp::InitInstance`. Insert the following lines of code before the `return TRUE;` statement. This code creates the strings that we use in either the Windows message box or in the `CTaskDialog`. ```cpp CString message("My message to the user"); CString dialogTitle("My Task Dialog title"); CString emptyString; - ``` - -1. Add the following code after the code from step 4. This code guarantees that the user's computer supports the `CTaskDialog`. If the dialog isn't supported, the application displays a Windows message box instead. - ```cpp + // Check whether the user's computer supports `CTaskDialog`. + // If not, display a Windows message box instead. if (CTaskDialog::IsSupported()) { - + CTaskDialog taskDialog(message, emptyString, dialogTitle, TDCBF_OK_BUTTON); + taskDialog.SetMainIcon(TD_WARNING_ICON); // Set the icon to be the same as the Windows message box + taskDialog.DoModal(); } else { @@ -59,45 +51,18 @@ The following procedure demonstrates the most basic use of the `CTaskDialog`, wh } ``` -1. Insert the following code between the brackets after the **`if`** statement from step 5. This code creates the `CTaskDialog`. - - ```cpp - CTaskDialog taskDialog(message, emptyString, dialogTitle, TDCBF_OK_BUTTON); - ``` - -1. On the next line, add the following code. This code sets the warning icon. - - ```cpp - taskDialog.SetMainIcon(TD_WARNING_ICON); - ``` - -1. On the next line, add the following code. This code displays the task dialog box. - - ```cpp - taskDialog.DoModal(); - ``` - -You can avoid step 7 if you don't want the `CTaskDialog` to display the same icon as the Windows message box. If you avoid that step, the `CTaskDialog` has no icon when the application displays it. - Compile and run the application. The application displays the task dialog box after it starts. -## Adding Functionality to the CTaskDialog - -The following procedure shows you how to add functionality to the `CTaskDialog` that you created in the previous procedure. The example code shows you how to execute specific instructions based on the user's selections. - -### To Add Functionality to the CTaskDialog +## Add functionality to the CTaskDialog -1. Navigate to the **Resource View**. If you can't see the **Resource View**, you can open it from the **View** menu. +The following shows you how to add functionality to the `CTaskDialog` that you created in the previous procedure. The example code shows you how to execute specific instructions based on the user's selections. -1. Expand the **Resource View** until you can select the **String Table** folder. Expand it and double-click the **String Table** entry. - -1. Scroll to the bottom of the string table and add a new entry. Change the ID to `TEMP_LINE1`. Set the caption to **Command Line 1**. - -1. Add another new entry. Change the ID to `TEMP_LINE2`. Set the caption to **Command Line 2**. - -1. Navigate back to MyProject.cpp. - -1. After `CString emptyString;`, add the following code: +1. Navigate to the **Resource View** via **View** > **Other Windows** > **Resource View**. +1. Expand the **Resource View** to the **String Table** folder. Expand it and double-click **String Table**. +1. Scroll to the bottom of the string table and add a new entry. Change the ID to `TEMP_LINE1`. Set the caption to `Command Line 1`. +1. Add another new entry. Change the ID to `TEMP_LINE2`. Set the caption to `Command Line 2`. +1. Navigate back to `MyProject.cpp`. +1. In the `CMyProjectApp::InitInstance()` function, after `CString emptyString;` add the following code: ```cpp CString expandedLabel("Hide extra information"); @@ -109,67 +74,52 @@ The following procedure shows you how to add functionality to the `CTaskDialog` ```cpp taskDialog.SetMainInstruction(L"Warning"); - taskDialog.SetCommonButtons( - TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON); + taskDialog.SetCommonButtons(TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON); taskDialog.LoadCommandControls(TEMP_LINE1, TEMP_LINE2); - taskDialog.SetExpansionArea( - expansionInfo, collapsedLabel, expandedLabel); - taskDialog.SetFooterText(L"This is the a small footnote to the user"); + taskDialog.SetExpansionArea(expansionInfo, collapsedLabel, expandedLabel); + taskDialog.SetFooterText(L"This is a small footnote to the user"); taskDialog.SetVerificationCheckboxText(L"Remember your selection"); - ``` - -1. Add the following line of code that displays the task dialog box to the user and retrieves the user's selection: - - ```cpp INT_PTR result = taskDialog.DoModal(); - ``` - -1. Insert the following code after the call to `taskDialog.DoModal()`. This section of code processes the user's input: - ```cpp if (taskDialog.GetVerificationCheckboxState()) { - // PROCESS IF the user selects the verification checkbox + // Your code if the user selects the verification checkbox } switch (result) { - case TEMP_LINE1: - // PROCESS IF the first command line - break; - case TEMP_LINE2: - // PROCESS IF the second command line - break; - case IDYES: - // PROCESS IF the user clicks yes - break; - case IDNO: - // PROCESS IF the user clicks no - break; - case IDCANCEL: - // PROCESS IF the user clicks cancel - break; - default: - // This case should not be hit because closing - // the dialog box results in IDCANCEL - break; + case TEMP_LINE1: + // PROCESS IF the first command line + break; + case TEMP_LINE2: + // PROCESS IF the second command line + break; + case IDYES: + // PROCESS IF the user clicks yes + break; + case IDNO: + // PROCESS IF the user clicks no + break; + case IDCANCEL: + // PROCESS IF the user clicks cancel + break; + default: + // This case should not be hit because closing + // the dialog box results in IDCANCEL + break; } ``` -In the code in step 9, replace the comments that start with `PROCESS IF` with the code that you want to execute under the specified conditions. - Compile and run the application. The application displays the task dialog box that uses the new controls and additional information. ## Displaying a CTaskDialog Without Creating a CTaskDialog Object -The following procedure shows you how to display a `CTaskDialog` without first creating a `CTaskDialog` object. This example continues the previous procedures. +The following shows you how to display a `CTaskDialog` without first creating a `CTaskDialog` object. This example continues the previous procedures. ### To Display a CTaskDialog Without Creating a CTaskDialog Object -1. Open the MyProject.cpp file if it isn't already open. - -1. Navigate to the closing bracket for the `if (CTaskDialog::IsSupported())` statement. - +1. Open the `MyProject.cpp` file. +1. In the `CMyProjectApp::InitInstance()` function, navigate to the closing bracket for the `if (CTaskDialog::IsSupported())` statement. 1. Insert the following code immediately before the closing bracket of the **`if`** statement (before the **`else`** block): ```cpp @@ -180,12 +130,12 @@ The following procedure shows you how to display a `CTaskDialog` without first c TEMP_LINE2); ``` -Compile and run the application. The application displays two task dialog boxes. The first dialog box is from the **To Add Functionality to the CTaskDialog** procedure; the second dialog box is from the last procedure. +Compile and run the application. The application displays two task dialog boxes. The first dialog box is from the **To Add Functionality to the CTaskDialog** procedure; the second dialog box is from the previous procedure. These examples don't demonstrate all the available options for a `CTaskDialog`, but should help you get started. See [CTaskDialog Class](../mfc/reference/ctaskdialog-class.md) for a full description of the class. ## See also -[Dialog Boxes](../mfc/dialog-boxes.md)
-[CTaskDialog Class](../mfc/reference/ctaskdialog-class.md)
+[Dialog Boxes](../mfc/dialog-boxes.md)\ +[CTaskDialog Class](../mfc/reference/ctaskdialog-class.md)\ [CTaskDialog::CTaskDialog](../mfc/reference/ctaskdialog-class.md#ctaskdialog) diff --git a/docs/mfc/windows-sockets-using-class-casyncsocket.md b/docs/mfc/windows-sockets-using-class-casyncsocket.md index b0a5671636..992332b73a 100644 --- a/docs/mfc/windows-sockets-using-class-casyncsocket.md +++ b/docs/mfc/windows-sockets-using-class-casyncsocket.md @@ -1,16 +1,16 @@ --- -description: "Learn more about: Windows Sockets: Using Class CAsyncSocket" title: "Windows Sockets: Using Class CAsyncSocket" +description: "Learn more about: Windows Sockets: Using Class CAsyncSocket" ms.date: "6/8/2021" helpviewer_keywords: ["CAsyncSocket class [MFC], programming model", "Windows Sockets [MFC], asynchronous", "sockets [MFC], converting between Unicode and MBCS strings", "SOCKET handle", "sockets [MFC], asynchronous operation", "Windows Sockets [MFC], converting Unicode and MBCS strings"] --- # Windows Sockets: Using Class `CAsyncSocket` -This article explains how to use class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md). This class encapsulates the Windows Sockets API at a very low level. `CAsyncSocket` is for use by programmers who know network communications in detail but want the convenience of callbacks for notification of network events. Based on this assumption, this article provides only basic instruction. You should probably consider using `CAsyncSocket` if you want Windows Sockets' ease of dealing with multiple network protocols in an MFC application but don't want to sacrifice flexibility. You might also feel that you can get better efficiency by programming the communications more directly yourself than you could using the more general alternative model of class `CSocket`. +This article explains how to use class [`CAsyncSocket`](reference/casyncsocket-class.md). This class encapsulates the Windows Sockets API at a very low level. `CAsyncSocket` is for use by programmers who know network communications in detail but want the convenience of callbacks for notification of network events. Based on this assumption, this article provides only basic instruction. You should probably consider using `CAsyncSocket` if you want Windows Sockets' ease of dealing with multiple network protocols in an MFC application but don't want to sacrifice flexibility. You might also feel that you can get better efficiency by programming the communications more directly yourself than you could using the more general alternative model of class `CSocket`. `CAsyncSocket` is documented in the *MFC Reference*. Visual C++ also supplies the Windows Sockets specification, located in the Windows SDK. The details are left to you. Visual C++ doesn't supply a sample application for `CAsyncSocket`. -If you aren't highly knowledgeable about network communications and want a simple solution, use class [`CSocket`](../mfc/reference/csocket-class.md) with a `CArchive` object. See [Windows Sockets: Using Sockets with Archives](../mfc/windows-sockets-using-sockets-with-archives.md) for more information. +If you aren't highly knowledgeable about network communications and want a simple solution, use class [`CSocket`](reference/csocket-class.md) with a `CArchive` object. See [Windows Sockets: Using Sockets with Archives](windows-sockets-using-sockets-with-archives.md) for more information. This article covers: @@ -22,19 +22,19 @@ This article covers: #### To use `CAsyncSocket` -1. Construct a [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md) object and use the object to create the underlying **`SOCKET`** handle. +1. Construct a [`CAsyncSocket`](reference/casyncsocket-class.md) object and use the object to create the underlying **`SOCKET`** handle. Creation of a socket follows the MFC pattern of two-stage construction. For example: - [!code-cpp[NVC_MFCSimpleSocket#3](../mfc/codesnippet/cpp/windows-sockets-using-class-casyncsocket_1.cpp)] + [!code-cpp[NVC_MFCSimpleSocket#3](codesnippet/cpp/windows-sockets-using-class-casyncsocket_1.cpp)] -or- - [!code-cpp[NVC_MFCSimpleSocket#4](../mfc/codesnippet/cpp/windows-sockets-using-class-casyncsocket_2.cpp)] + [!code-cpp[NVC_MFCSimpleSocket#4](codesnippet/cpp/windows-sockets-using-class-casyncsocket_2.cpp)] - The first constructor above creates a `CAsyncSocket` object on the stack. The second constructor creates a `CAsyncSocket` on the heap. The first [`Create`](../mfc/reference/casyncsocket-class.md#create) call above uses the default parameters to create a stream socket. The second `Create` call creates a datagram socket with a specified port and address. (You can use either `Create` version with either construction method.) + The first constructor above creates a `CAsyncSocket` object on the stack. The second constructor creates a `CAsyncSocket` on the heap. The first [`Create`](reference/casyncsocket-class.md#create) call above uses the default parameters to create a stream socket. The second `Create` call creates a datagram socket with a specified port and address. (You can use either `Create` version with either construction method.) The parameters to `Create` are: @@ -48,34 +48,34 @@ This article covers: This is your Internet Protocol (IP) address on the network. You'll probably always rely on the default value for this parameter. - The terms "port" and "socket address" are explained in [Windows Sockets: Ports and Socket Addresses](../mfc/windows-sockets-ports-and-socket-addresses.md). + The terms "port" and "socket address" are explained in [Windows Sockets: Ports and Socket Addresses](windows-sockets-ports-and-socket-addresses.md). -1. If the socket is a client, connect the socket object to a server socket, using [`CAsyncSocket::Connect`](../mfc/reference/casyncsocket-class.md#connect). +1. If the socket is a client, connect the socket object to a server socket, using [`CAsyncSocket::Connect`](reference/casyncsocket-class.md#connect). -or- - If the socket is a server, set the socket to begin listening (with [`CAsyncSocket::Listen`](../mfc/reference/casyncsocket-class.md#listen)) for connect attempts from a client. Upon receiving a connection request, accept it with [`CAsyncSocket::Accept`](../mfc/reference/casyncsocket-class.md#accept). + If the socket is a server, set the socket to begin listening (with [`CAsyncSocket::Listen`](reference/casyncsocket-class.md#listen)) for connect attempts from a client. Upon receiving a connection request, accept it with [`CAsyncSocket::Accept`](reference/casyncsocket-class.md#accept). After accepting a connection, you can do tasks like validating passwords. > [!NOTE] - > The `Accept` member function takes a reference to a new, empty `CSocket` object as its parameter. You must construct this object before you call `Accept`. If this socket object goes out of scope, the connection closes. Don't call `Create` for this new socket object. For an example, see the article [Windows Sockets: Sequence of Operations](../mfc/windows-sockets-sequence-of-operations.md). + > The `Accept` member function takes a reference to a new, empty `CSocket` object as its parameter. You must construct this object before you call `Accept`. If this socket object goes out of scope, the connection closes. Don't call `Create` for this new socket object. For an example, see the article [Windows Sockets: Sequence of Operations](windows-sockets-sequence-of-operations.md). 1. Carry out communications with other sockets by calling the `CAsyncSocket` object's member functions that encapsulate the Windows Sockets API functions. - See the Windows Sockets specification and class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md) in the *MFC Reference*. + See the Windows Sockets specification and class [`CAsyncSocket`](reference/casyncsocket-class.md) in the *MFC Reference*. 1. Destroy the `CAsyncSocket` object. If you created the socket object on the stack, its destructor is called when the containing function goes out of scope. If you created the socket object on the heap, using the **`new`** operator, you're responsible for using the **`delete`** operator to destroy the object. - The destructor calls the object's [`Close`](../mfc/reference/casyncsocket-class.md#close) member function before destroying the object. + The destructor calls the object's [`Close`](reference/casyncsocket-class.md#close) member function before destroying the object. -For an example of this sequence in code (actually for a `CSocket` object), see [Windows Sockets: Sequence of Operations](../mfc/windows-sockets-sequence-of-operations.md). +For an example of this sequence in code (actually for a `CSocket` object), see [Windows Sockets: Sequence of Operations](windows-sockets-sequence-of-operations.md). ## Your responsibilities with `CAsyncSocket` -When you create an object of class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md), the object encapsulates a Windows **`SOCKET`** handle and supplies operations on that handle. When you use `CAsyncSocket`, you must deal with all the issues you might face if using the API directly. For example: +When you create an object of class [`CAsyncSocket`](reference/casyncsocket-class.md), the object encapsulates a Windows **`SOCKET`** handle and supplies operations on that handle. When you use `CAsyncSocket`, you must deal with all the issues you might face if using the API directly. For example: - "Blocking" scenarios. @@ -83,16 +83,16 @@ When you create an object of class [`CAsyncSocket`](../mfc/reference/casyncsocke - Converting between Unicode and multibyte character set (MBCS) strings. -For definitions of these terms and additional information, see [Windows Sockets: Blocking](../mfc/windows-sockets-blocking.md), [Windows Sockets: Byte Ordering](../mfc/windows-sockets-byte-ordering.md), [Windows Sockets: Converting Strings](../mfc/windows-sockets-converting-strings.md). +For definitions of these terms and additional information, see [Windows Sockets: Blocking](windows-sockets-blocking.md), [Windows Sockets: Byte Ordering](windows-sockets-byte-ordering.md), [Windows Sockets: Converting Strings](windows-sockets-converting-strings.md). Despite these issues, class `CAsyncSocket` may be the right choice for you if your application requires all the flexibility and control you can get. If not, consider using class `CSocket` instead. `CSocket` hides many details from you: it pumps Windows messages during blocking calls and gives you access to `CArchive`, which manages byte order differences and string conversion for you. For more information, see: -- [Windows Sockets: Background](../mfc/windows-sockets-background.md)\ -- [Windows Sockets: Stream Sockets](../mfc/windows-sockets-stream-sockets.md)\ -- [Windows Sockets: Datagram Sockets](../mfc/windows-sockets-datagram-sockets.md) +- [Windows Sockets: Background](windows-sockets-background.md) +- [Windows Sockets: Stream Sockets](windows-sockets-stream-sockets.md) +- [Windows Sockets: Datagram Sockets](windows-sockets-datagram-sockets.md) ## See also -[Windows Sockets in MFC](../mfc/windows-sockets-in-mfc.md) +[Windows Sockets in MFC](windows-sockets-in-mfc.md) diff --git a/docs/overview/compiler-versions.md b/docs/overview/compiler-versions.md new file mode 100644 index 0000000000..60666e3f29 --- /dev/null +++ b/docs/overview/compiler-versions.md @@ -0,0 +1,135 @@ +--- +description: "Learn more about Microsoft Visual C++ compiler versioning." +title: "Microsoft Visual C++ compiler versioning (Visual C++)" +ms.date: 02/12/2025 +ms.service: "visual-cpp" +ms.subservice: "tools" +helpviewer_keywords: ["Visual C++, platforms supported", "platforms [C++]"] +--- +# Microsoft Visual C++ compiler versioning + +The Microsoft Visual C++ compiler version consists of four fields: + +M - major version (two digits)\ +N - minor version (two digits)\ +B - build version (five digits)\ +R - revision version + +Microsoft-specific compiler macros encode these fields as follows: + +`_MSC_VER` = MMNN\ +`_MSC_FULL_VER` = MMNNBBBBB\ +`_MSC_BUILD` = R + +For example, the compiler version for Visual Studio 2022 version 17.9.0 is 19.39.33519: +- The major version is 19 +- The minor version is 39 +- The build version is 33519 +- The revision version is 0 + +The macros reflect these values like this: +- `_MSC_VER = 1939` +- `_MSC_FULL_VER = 193933519` +- `_MSC_BUILD` (the revision) is 0. + +>[!Note] +>Visual Studio 2019 16.8 and 16.9 share the same major and minor versions, and so have the same value for `_MSC_VER`. As do Visual Studio 2019 16.10 and 16.11. To distinguish them, use `_MSC_FULL_VER` as described in [Service releases starting with Visual Studio 2017](#service-releases-starting-with-visual-studio-2017). + +## A brief history of Visual C++ compiler versioning + +### Visual Studio 6.0 through Visual Studio 2015 (14.0) + +- For major releases, `_MSC_VER` increases by 100. `_MSC_FULL_VER` increases by 10,000,000. +- For minor releases, `_MSC_VER` increases by 10. `_MSC_FULL_VER` increases by 1,000,000. + + >[!Note] + > Visual Studio .NET 2003 was considered a minor release. + +### Visual Studio 2017 and later + +- For major releases, the minor version increases by 10. +- For minor releases, the minor version increases by 1 starting with Visual Studio 2017 version 15.3. + +### Service releases starting with Visual Studio 2017 + +Servicing releases are distinguished by `_MSC_FULL_VER`. The build field (the BBBBB in the MMNNBBBBB version number) typically increases by 1. + +For example, two cases where `_MSC_FULL_VER` is useful is to distinguish Visual Studio 2019 16.8 from 16.9, and Visual Studio 2019 16.10 from 16.11. That's because those versions share the same major and minor versions, and so have the same value for `_MSC_VER`. + +To distinguish these versions, use `_MSC_FULL_VER`.\ +The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.8 is 192829333.\ +The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.9 is 192829910. + +## Version macros + +Recall that the version number consists of four fields: + +M - major version (two digits)\ +N - minor version (two digits)\ +B - build version (five digits)\ +R - revision version + +**[`_MSC_VER`](../preprocessor/predefined-macros.md)** distinguishes between major and minor releases. It has the form: MMNN. + +**[`_MSC_FULL_VER`](../preprocessor/predefined-macros.md)** represents the major, minor, and build version of the compiler. It has the form: MMNNBBBBB. Use it to distinguish between different versions of the compiler, including servicing releases. For more information about Visual Studio 2019 16.8, 16.9, 16.10 and 16.11, see [Service releases starting with Visual Studio 2017](#service-releases-starting-with-visual-studio-2017). + +**[`_MSC_BUILD`](../preprocessor/predefined-macros.md)** represents the build version of the compiler. It has the form: R. Use it to distinguish between servicing releases. + +When the major version changed between Visual Studio 2013 and Visual Studio 2015, `_MSC_VER` reflected the change by going from 1800 to 1900. + +An example of a minor change is from Visual Studio 2022 17.1 to Visual Studio 2022 17.2. In that case, `_MSC_VER` changed from 1931 to 1932. + +The following table lists the Visual C++ compiler `_MSC_VER` for each Visual Studio release: + +| Visual Studio version | `_MSC_VER` | +|--|--| +| Visual Studio 6.0 | 1200 | +| Visual Studio .NET 2002 (7.0) | 1300 | +| Visual Studio .NET 2003 (7.1) | 1310 | +| Visual Studio 2005 (8.0) | 1400 | +| Visual Studio 2008 (9.0) | 1500 | +| Visual Studio 2010 (10.0) | 1600 | +| Visual Studio 2012 (11.0) | 1700 | +| Visual Studio 2013 (12.0) | 1800 | +| Visual Studio 2015 (14.0) | 1900 | +| Visual Studio 2017 RTW (15.0) | 1910 | +| Visual Studio 2017 version 15.3 | 1911 | +| Visual Studio 2017 version 15.5 | 1912 | +| Visual Studio 2017 version 15.6 | 1913 | +| Visual Studio 2017 version 15.7 | 1914 | +| Visual Studio 2017 version 15.8 | 1915 | +| Visual Studio 2017 version 15.9 | 1916 | +| Visual Studio 2019 RTW 16.0 | 1920 | +| Visual Studio 2019 version 16.1 | 1921 | +| Visual Studio 2019 version 16.2 | 1922 | +| Visual Studio 2019 version 16.3 | 1923 | +| Visual Studio 2019 version 16.4 | 1924 | +| Visual Studio 2019 version 16.5 | 1925 | +| Visual Studio 2019 version 16.6 | 1926 | +| Visual Studio 2019 version 16.7 | 1927 | +| Visual Studio 2019 version 16.8, 16.9 a | 1928 | +| Visual Studio 2019 version 16.10, 16.11 b | 1929 | +| Visual Studio 2022 RTW 17.0 | 1930 | +| Visual Studio 2022 version 17.1 | 1931 | +| Visual Studio 2022 version 17.2 | 1932 | +| Visual Studio 2022 version 17.3 | 1933 | +| Visual Studio 2022 version 17.4 | 1934 | +| Visual Studio 2022 version 17.5 | 1935 | +| Visual Studio 2022 version 17.6 | 1936 | +| Visual Studio 2022 version 17.7 | 1937 | +| Visual Studio 2022 version 17.8 | 1938 | +| Visual Studio 2022 version 17.9 | 1939 | +| Visual Studio 2022 version 17.10 | 1940 | +| Visual Studio 2022 version 17.11 | 1941 | +| Visual Studio 2022 version 17.12 | 1942 | +| Visual Studio 2022 version 17.13 | 1943 | +| Visual Studio 2022 version 17.14 | 1944 | + +a Visual Studio 2019 16.8 and 16.9 share the same major and minor versions (and so have the same value for `_MSC_VER`). To distinguish them, use `_MSC_FULL_VER`. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.8 is 192829333. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.9 is 192829910. + +b Visual Studio 2019 16.10 and 16.11 share the same major and minor versions (and so have the same value for `_MSC_VER`). To distinguish them, use `_MSC_FULL_VER`. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.10 is 192929917. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 16.11 is 192930129. + +## See also + +[`_MSC_VER`](../preprocessor/predefined-macros.md)\ +[Visual C++ compiler version blog post](https://devblogs.microsoft.com/cppblog/visual-c-compiler-version/) diff --git a/docs/overview/cpp-conformance-improvements-2017.md b/docs/overview/cpp-conformance-improvements-2017.md index 888a71e825..557e798336 100644 --- a/docs/overview/cpp-conformance-improvements-2017.md +++ b/docs/overview/cpp-conformance-improvements-2017.md @@ -2,7 +2,8 @@ title: "C++ conformance improvements in Visual Studio 2017" description: "Microsoft C/C++ in Visual Studio 2017 is progressing toward full conformance with the C++20 language standard." ms.date: 04/18/2021 -ms.technology: "cpp-language" +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2017 @@ -32,15 +33,15 @@ the message parameter for **`static_assert`** is optional. For more information, ### C++17: `[[fallthrough]]` attribute -In **`/std:c++17`** mode and later, the `[[fallthrough]]` attribute can be used in the context of switch statements as a hint to the compiler that the fall-through behavior is intended. This attribute prevents the compiler from issuing warnings in such cases. For more information, see [P0188R0 - Wording for `[[fallthrough]]` attribute](https://wg21.link/p0188r0). +In **`/std:c++17`** mode and later, the `[[fallthrough]]` attribute can be used in the context of switch statements as a hint to the compiler that the fall-through behavior is intended. This attribute prevents the compiler from issuing warnings in such cases. For more information, see [`P0188R0 - Wording for [[fallthrough]] attribute`](https://wg21.link/p0188r0). ### Generalized range-based `for` loops -Range-based `for` loops no longer require that `begin()` and `end()` return objects of the same type. This change enables `end()` to return a sentinel as used by ranges in [`range-v3`](https://github.com/ericniebler/range-v3) and the completed-but-not-quite-published Ranges Technical Specification. For more information, see [P0184R0 - Generalizing the Range-Based `for` Loop](https://wg21.link/p0184r0). +Range-based `for` loops no longer require that `begin()` and `end()` return objects of the same type. This change enables `end()` to return a sentinel as used by ranges in [`range-v3`](https://github.com/ericniebler/range-v3) and the completed-but-not-quite-published Ranges Technical Specification. For more information, see [`P0184R0 - Generalizing the Range-Based for Loop`](https://wg21.link/p0184r0). ### Copy-list-initialization -Visual Studio 2017 correctly raises compiler errors related to object creation using initializer lists. These errors weren't caught in Visual Studio 2015, and could lead to crashes or undefined runtime behavior. As per [N4594 13.3.1.7p1](https://wg21.link/n4594), in *`copy-list-initialization`*, the compiler is required to consider an explicit constructor for overload resolution. However, it must raise an error if that particular overload gets chosen. +Visual Studio 2017 correctly raises compiler errors related to object creation using initializer lists. These errors weren't caught in Visual Studio 2015, and could lead to crashes or undefined runtime behavior. As per [`N4594 13.3.1.7p1`](https://wg21.link/n4594), in *`copy-list-initialization`*, the compiler is required to consider an explicit constructor for overload resolution. However, it must raise an error if that particular overload gets chosen. The following two examples compile in Visual Studio 2015 but not in Visual Studio 2017. @@ -148,7 +149,7 @@ To correct the error, either declare the `array::size()` function as **`constexp ### Class types passed to variadic functions -In Visual Studio 2017, classes or structs that are passed to a variadic function such as `printf` must be trivially copyable. When passing such objects, the compiler simply makes a bitwise copy and doesn't call the constructor or destructor. +In Visual Studio 2017, classes or structs that are passed to a variadic function such as `printf` must be trivially copyable. When such objects are passed, the compiler simply makes a bitwise copy and doesn't call the constructor or destructor. ```cpp #include @@ -250,7 +251,7 @@ template class ListHead; // C2955: 'ListNodeMember': ### Expression-SFINAE -To support expression-SFINAE, the compiler now parses **`decltype`** arguments when the templates are declared rather than instantiated. So, if a non-dependent specialization is found in the decltype argument, it's not deferred to instantiation-time. It's processed immediately, and any resulting errors are diagnosed at that time. +To support expression-SFINAE, the compiler now parses **`decltype`** arguments when the templates are declared rather than instantiated. So, if a non-dependent specialization is found in the **`decltype`** argument, it's not deferred until instantiation-time. It's processed immediately, and any resulting errors are diagnosed at that time. The following example shows such a compiler error that is raised at the point of declaration: @@ -379,23 +380,23 @@ New syntax to enable only a single namespace identifier in an attribute list. Fo ### Structured bindings -It's now possible in a single declaration to store a value with individual names for its components, when the value is an array, a `std::tuple` or `std::pair`, or has all public non-static data members. For more information, see [P0144R0 - Structured Bindings](https://wg21.link/p0144r0) and [Returning multiple values from a function](../cpp/functions-cpp.md#multi_val). +It's now possible in a single declaration to store a value with individual names for its components, when the value is an array, a `std::tuple` or `std::pair`, or has all public non-static data members. For more information, see [`P0144R0 - Structured Bindings`](https://wg21.link/p0144r0) and [Returning multiple values from a function](../cpp/functions-cpp.md#multi_val). ### Construction rules for `enum class` values -There's now an implicit conversion for scoped enumerations that's non-narrowing. It converts from a scoped enumeration's underlying type to the enumeration itself. The conversion is available when its definition doesn't introduce an enumerator, and when the source uses a list-initialization syntax. For more information, see [P0138R2 - Construction Rules for `enum class` Values](https://wg21.link/p0138r2) and [Enumerations](../cpp/enumerations-cpp.md#no_enumerators). +There's now an implicit conversion for scoped enumerations that's non-narrowing. It converts from a scoped enumeration's underlying type to the enumeration itself. The conversion is available when its definition doesn't introduce an enumerator, and when the source uses a list-initialization syntax. For more information, see [`P0138R2 - Construction Rules for enum class Values`](https://wg21.link/p0138r2) and [Enumerations](../cpp/enumerations-cpp.md#no_enumerators). ### Capturing `*this` by value -The **`*this`** object in a lambda expression may now be captured by value. This change enables scenarios in which the lambda is invoked in parallel and asynchronous operations, especially on newer machine architectures. For more information, see [P0018R3 - Lambda Capture of \*this by Value as \[=,\*this\]](https://wg21.link/p0018r3). +The **`*this`** object in a lambda expression may now be captured by value. This change enables scenarios in which the lambda is invoked in parallel and asynchronous operations, especially on newer machine architectures. For more information, see [`P0018R3 - Lambda Capture of *this by Value as [=,*this]`](https://wg21.link/p0018r3). ### Removing `operator++` for `bool` -`operator++` is no longer supported on **`bool`** types. For more information, see [P0002R1 - Remove Deprecated operator++(bool)](https://wg21.link/p0002r1). +`operator++` is no longer supported on **`bool`** types. For more information, see [`P0002R1 - Remove Deprecated operator++(bool)`](https://wg21.link/p0002r1). ### Removing deprecated `register` keyword -The **`register`** keyword, previously deprecated (and ignored by the compiler), is now removed from the language. For more information, see [P0001R1 - Remove Deprecated Use of the `register` Keyword](https://wg21.link/p0001r1). +The **`register`** keyword, previously deprecated (and ignored by the compiler), is now removed from the language. For more information, see [`P0001R1 - Remove Deprecated Use of the register Keyword`](https://wg21.link/p0001r1). ### Calls to deleted member templates @@ -784,7 +785,7 @@ In earlier versions of Visual Studio, the compiler always gave a **`constexpr`** ### Removing dynamic exception specifications -[P0003R5](https://wg21.link/p0003r5) Dynamic exception specifications were deprecated in C++11. the feature is removed from C++17, but the (still) deprecated `throw()` specification is kept strictly as an alias for `noexcept(true)`. For more information, see [Dynamic exception specification removal and `noexcept`](#noexcept_removal). +[P0003R5](https://wg21.link/p0003r5) Dynamic exception specifications were deprecated in C++11. The feature is removed from C++17, but the (still) deprecated `throw()` specification is kept strictly as an alias for `noexcept(true)`. For more information, see [Dynamic exception specification removal and `noexcept`](#noexcept_removal). ### `not_fn()` @@ -1300,7 +1301,7 @@ int main() ### C++17 Library Fundamentals V1 -[P0220R1](https://wg21.link/p0220r1) incorporates Library Fundamentals Technical Specification for C++17 into the standard. Covers updates to \, \, \, \, \, \, \, and \. +[P0220R1](https://wg21.link/p0220r1) incorporates Library Fundamentals Technical Specification for C++17 into the standard. Covers updates to *``*, *``*, *``*, *``*, *``*, *``*, *``*, and *``*. ### C++17: Improving class template argument deduction for the standard library @@ -1450,13 +1451,13 @@ void sample(A<0> *p) [P0030R1](https://wg21.link/p0030r1) Adds three new overloads to `std::hypot`, for types **`float`**, **`double`**, and **`long double`**, each of which has three input parameters. -### C++17: \ +### C++17: *``* [P0218R1](https://wg21.link/p0218r1) Adopts the File System TS into the standard with a few wording modifications. ### C++17: Mathematical special functions -[P0226R1](https://wg21.link/p0220r1) Adopts previous technical specifications for Mathematical Special Functions into the standard \ header. +[P0226R1](https://wg21.link/p0220r1) Adopts previous technical specifications for Mathematical Special Functions into the standard *``* header. ### C++17: Deduction guides for the standard library @@ -1464,7 +1465,7 @@ void sample(A<0> *p) ### C++17: Repairing elementary string conversions -[P0682R1](https://wg21.link/p0682r1) Move the new elementary string conversion functions from P0067R5 into a new header \ and make other improvements, including changing error handling to use `std::errc` instead of `std::error_code`. +[P0682R1](https://wg21.link/p0682r1) Move the new elementary string conversion functions from P0067R5 into a new header *``* and make other improvements, including changing error handling to use `std::errc` instead of `std::error_code`. ### C++17: `constexpr` for `char_traits` (partial) @@ -1472,7 +1473,7 @@ void sample(A<0> *p) ### C++17: Default argument in the primary class template -This behavior change is a precondition for [P0091R3 - Template argument deduction for class templates](https://wg21.link/p0091r3). +This behavior change is a precondition for [`P0091R3 - Template argument deduction for class templates`](https://wg21.link/p0091r3). Previously, the compiler ignored the default argument in the primary class template: @@ -1500,7 +1501,7 @@ void S::f(int) {} // Default argument is used ### Dependent name resolution -This behavior change is a precondition for [P0091R3 - Template argument deduction for class templates](https://wg21.link/p0091r3). +This behavior change is a precondition for [`P0091R3 - Template argument deduction for class templates`](https://wg21.link/p0091r3). In the following example, the compiler in Visual Studio 15.6 and earlier resolves `D::type` to `B::type` in the primary class template. @@ -1564,7 +1565,7 @@ struct D : B D d; ``` -To fix the error, change the B() expression to B\(). +To fix the error, change the `B()` expression to `B()`. ### `constexpr` aggregate initialization @@ -1642,7 +1643,7 @@ using X [[deprecated("msg")]] = T; Two-phase name lookup requires that non-dependent names used in template bodies must be visible to the template at definition time. Previously, the Microsoft C++ compiler would leave an unfound name as not looked up until instantiation time. Now, it requires that non-dependent names are bound in the template body. -One way this can manifest is with lookup into dependent base classes. Previously, the compiler allowed the use of names that are defined in dependent base classes. That's because they'd be looked up during instantiation time when all the types are resolved. Now that code is treated as an error. In these cases, you can force the variable to be looked up at instantiation time by qualifying it with the base class type or otherwise making it dependent, for example, by adding a `this->` pointer. +One way this can manifest is with lookup into dependent base classes. Previously, the compiler allowed the use of names that are defined in dependent base classes. It's because they'd be looked up during instantiation time when all the types are resolved. Now that code is treated as an error. In these cases, you can force the variable to be looked up at instantiation time by qualifying it with the base class type or otherwise making it dependent, for example, by adding a `this->` pointer. In [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode, the following code now raises C3861: @@ -1745,7 +1746,7 @@ int main() } ``` -To fix the error, use `offsetof` as defined via \: +To fix the error, use `offsetof` as defined via *``*: ```cpp #include @@ -1767,7 +1768,7 @@ int main() Previous versions of the Microsoft C++ compiler didn't detect that a base-class had cv-qualifiers if it was also subject to pack expansion. -In Visual Studio 2017 version 15.8, in [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode the following code raises C3770: +In Visual Studio 2017 version 15.8, in [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode, the following code raises C3770: ```cpp template diff --git a/docs/overview/cpp-conformance-improvements-2019.md b/docs/overview/cpp-conformance-improvements-2019.md index 8b3be8d805..e3b390b72f 100644 --- a/docs/overview/cpp-conformance-improvements-2019.md +++ b/docs/overview/cpp-conformance-improvements-2019.md @@ -1,8 +1,9 @@ --- title: "C++ conformance improvements in Visual Studio 2019" description: "Microsoft C++ in Visual Studio is progressing toward full conformance with the C++20 language standard." -ms.date: 10/23/2021 -ms.technology: "cpp-language" +ms.date: 06/29/2022 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2019 @@ -23,7 +24,7 @@ Modules are now officially in the C++20 standard. Improved support was added in ### Modified specification of aggregate type -The specification of an aggregate type has changed in C++20 (see [Prohibit aggregates with user-declared constructors](https://wg21.link/p1008r1)). In Visual Studio 2019, under **`/std:c++latest`** (or **`/std:c++20`** starting in Visual Studio 2019 version 16.11), a class with any user-declared constructor (for example, including a constructor declared `= default` or `= delete`) isn't an aggregate. Previously, only user-provided constructors would disqualify a class from being an aggregate. This change puts more restrictions on how such types can be initialized. +The specification of an aggregate type has changed in C++20 (see [Prohibit aggregates with user-declared constructors](https://wg21.link/p1008r1)). In Visual Studio 2019, under **`/std:c++latest`** (or **`/std:c++20`** in Visual Studio 2019 version 16.11 and later), a class with any user-declared constructor (for example, including a constructor declared `= default` or `= delete`) isn't an aggregate. Previously, only user-provided constructors would disqualify a class from being an aggregate. This change puts more restrictions on how such types can be initialized. The following code compiles without errors in Visual Studio 2017 but raises errors C2280 and C2440 in Visual Studio 2019 under **`/std:c++20`** or **`/std:c++latest`**: @@ -66,7 +67,16 @@ To avoid the errors, insert a space in the offending line before the final angle ### References to types with mismatched cv-qualifiers -Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference. The compiler now creates a temporary, as required by the standard. In Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019, the compiler raises warning C4172: +>[!Note] +> This change only affects Visual Studio 2019 versions 16.0 through 16.8. It was reverted starting in Visual Studio 2019 version 16.9 + +Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference. + +The compiler for Visual Studio 2019 versions 16.0 through 16.8 instead creates a temporary, as was required by the standard at that time. Later, the standard retroactively changed making the previous behavior of Visual Studio 2017 and earlier correct, and the behavior of Visual Studio 2019 version 16.0 through 16.8 wrong. Consequently, this change was reverted starting in Visual Studio 2019 version 16.9. + +See [Similar types and reference binding](#similar-types-and-reference-binding) for a related change. + +As an example, in Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019 versions 16.0 through 16.8, the compiler raises warning C4172. Starting with Visual Studio 2019 version 16.9, the code once again compiles without warnings: ```cpp struct X @@ -318,7 +328,7 @@ The Microsoft C++ team was recently made aware of a security issue in which the The only use of inline assembler within a lambda expression that we have found 'in the wild' was to capture the return address. In this scenario, you can capture the return address on all platforms simply by using a compiler intrinsic `_ReturnAddress()`. -The following code produces C7552 in both Visual Studio 2017 15.9 and in Visual Studio 2019: +The following code produces [C7553](../error-messages/compiler-errors-2/compiler-error-c7553.md) in Visual Studio 2017 15.9 and later versions of Visual Studio: ```cpp #include @@ -330,7 +340,7 @@ int f() auto lambda = [&] { - __asm { // C7552: inline assembler is not supported in a lambda + __asm { // C7553: inline assembler is not supported in a lambda mov eax, x mov y, eax @@ -435,7 +445,7 @@ The unordered container `reserve` function now actually reserves for N elements, - Added the overloads for container merge and extract member functions that accept rvalue containers. For more information, see [P0083 "Splicing Maps And Sets"](https://wg21.link/p0083r3) -### `std::basic_istream::read` processing of `\r\n`` =>`\n` +### `std::basic_istream::read` processing of `\r\n` => `\n` `std::basic_istream::read` was fixed to not write into parts of the supplied buffer temporarily as part of `\r\n` to `\n` processing. This change gives up some of the performance advantage that was gained in Visual Studio 2017 15.8 for reads larger than 4K in size. However, efficiency improvements from avoiding three virtual calls per character are still present. @@ -445,17 +455,17 @@ The `std::bitset` constructor no longer reads the ones and zeroes in reverse ord ### `std::pair::operator=` regression -Fixed a regression in the `std::pair` assignment operator introduced when implementing [LWG 2729 "Missing SFINAE on `std::pair::operator=`";](https://cplusplus.github.io/LWG/issue2729). It now correctly accepts types convertible to `std::pair` again. +We fixed a regression in the `std::pair` assignment operator introduced when implementing [LWG 2729 "Missing SFINAE on `std::pair::operator=`";](https://cplusplus.github.io/LWG/issue2729). It now correctly accepts types convertible to `std::pair` again. ### Non-deduced contexts for `add_const_t` -Fixed a minor type traits bug, where `add_const_t` and related functions are supposed to be a non-deduced context. In other words, `add_const_t` should be an alias for `typename add_const::type`, not `const T`. +We fixed a minor type traits bug, where `add_const_t` and related functions are supposed to be a non-deduced context. In other words, `add_const_t` should be an alias for `typename add_const::type`, not `const T`. ## Conformance improvements in 16.1 ### char8_t -[P0482r6](https://wg21.link/p0482r6). C++20 adds a new character type that is used to represent UTF-8 code units. `u8` string literals in C++20 have type `const char8_t[N]` instead of `const char[N]`, which was the case previously. Similar changes have been proposed for the C standard in [N2231](https://wg14.link/n2231). Suggestions for **`char8_t`** backward compatibility remediation are given in [P1423r3](https://wg21.link/p1423r3). The Microsoft C++ compiler adds support for **`char8_t`** in Visual Studio 2019 version 16.1 when you specify the [`/Zc:char8_t`](../build/reference/zc-char8-t.md) compiler option. It can be reverted to C++17 behavior via **`/Zc:char8_t-`**. The EDG compiler that powers IntelliSense doesn't yet support it in Visual Studio 2019 version 16.1. You may see spurious IntelliSense-only errors that don't affect the actual compilation. +[P0482r6](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0482r6.html). C++20 adds a new character type that is used to represent UTF-8 code units. `u8` string literals in C++20 have type `const char8_t[N]` instead of `const char[N]`, which was the case previously. Similar changes have been proposed for the C standard in [N2231](https://open-std.org/jtc1/sc22/wg14/www/docs/n2231.htm). Suggestions for **`char8_t`** backward compatibility remediation are given in [P1423r3](https://wg21.link/p1423r3). The Microsoft C++ compiler adds support for **`char8_t`** in Visual Studio 2019 version 16.1 when you specify the [`/Zc:char8_t`](../build/reference/zc-char8-t.md) compiler option. It can be reverted to C++17 behavior via **`/Zc:char8_t-`**. The EDG compiler that powers IntelliSense doesn't yet support it in Visual Studio 2019 version 16.1. You may see spurious IntelliSense-only errors that don't affect the actual compilation. #### Example @@ -466,7 +476,7 @@ const char8_t* s = u8"Hello"; // C++20 ### `std::type_identity` metafunction and `std::identity` function object -[P0887R1 type_identity](https://wg21.link/p0887r1). The deprecated `std::identity` class template extension has been removed, and replaced with the C++20 `std::type_identity` metafunction and `std::identity` function object. Both are available only under **`/std:c++latest`** (**`/std:c++20`** starting in Visual Studio 2019 version 16.11). +[P0887R1 type_identity](https://wg21.link/p0887r1). The deprecated `std::identity` class template extension has been removed, and replaced with the C++20 `std::type_identity` metafunction and `std::identity` function object. Both are available only under **`/std:c++latest`** (**`/std:c++20`** in Visual Studio 2019 version 16.11 and later). The following example produces deprecation warning C4996 for `std::identity` (defined in \) in Visual Studio 2017: @@ -493,7 +503,7 @@ long j = static_cast(i); ### Syntax checks for generic lambdas -The new lambda processor enables some conformance-mode syntactic checks in generic lambdas, under **`/std:c++latest`** (**`/std:c++20`** starting in Visual Studio 2019 version 16.11) or under any other language mode with [`/Zc:lambda`](../build/reference/zc-lambda.md) in Visual Studio 2019 version 16.9 or later (previously available as **`/experimental:newLambdaProcessor`** beginning in Visual Studio 2019 version 16.3). +The new lambda processor enables some conformance-mode syntactic checks in generic lambdas, under **`/std:c++latest`** (**`/std:c++20`** in Visual Studio 2019 version 16.11 and later) or under any other language mode with [`/Zc:lambda`](../build/reference/zc-lambda.md) in Visual Studio 2019 version 16.9 or later (previously available as **`/experimental:newLambdaProcessor`** beginning in Visual Studio 2019 version 16.3). The legacy lambda processor compiles this example without warnings, but the new lambda processor produces error C2760: @@ -517,11 +527,11 @@ void f() { ### Argument-dependent lookup for function calls -[P0846R0](https://wg21.link/p0846r0) (C++20) Increased ability to find function templates via argument-dependent lookup for function-call expressions with explicit template arguments. Requires **`/std:c++latest`** (or **`/std:c++20`** starting in Visual Studio 2019 version 16.11). +[P0846R0](https://wg21.link/p0846r0) (C++20) Increased ability to find function templates via argument-dependent lookup for function-call expressions with explicit template arguments. Requires **`/std:c++latest`** (or **`/std:c++20`** in Visual Studio 2019 version 16.11 and later). ### Designated initialization -[P0329R4](https://wg21.link/p0329r4) (C++20) *Designated initialization* allows specific members to be selected in aggregate initialization by using the `Type t { .member = expr }` syntax. Requires **`/std:c++latest`** (or **`/std:c++20`** starting in Visual Studio 2019 version 16.11). +[P0329R4](https://wg21.link/p0329r4) (C++20) *Designated initialization* allows specific members to be selected in aggregate initialization by using the `Type t { .member = expr }` syntax. Requires **`/std:c++latest`** (or **`/std:c++20`** in Visual Studio 2019 version 16.11 and later). ### Ranking of enum conversion to its fixed underlying type @@ -586,7 +596,7 @@ int main() ### `noexcept` `constexpr` functions -**`constexpr`** functions are no longer considered **`noexcept`** by default when used in a constant expression. This behavior change comes from the resolution of Core Working Group (CWG) [1351](https://wg21.link/cwg1351) and is enabled in [`/permissive-`](../build/reference/permissive-standards-conformance.md). The following example compiles in Visual Studio 2019 version 16.1 and earlier, but produces C2338 in Visual Studio 2019 version 16.2: +**`constexpr`** functions are no longer considered **`noexcept`** by default when used in a constant expression. This behavior change comes from the resolution of Core Working Group (CWG) [CWG 1351](https://wg21.link/cwg1351) and is enabled in [`/permissive-`](../build/reference/permissive-standards-conformance.md). The following example compiles in Visual Studio 2019 version 16.1 and earlier, but produces C2338 in Visual Studio 2019 version 16.2: ```cpp constexpr int f() { return 0; } @@ -616,7 +626,7 @@ C++20 has deprecated the usual arithmetic conversions on operands, where: For more information, see [P1120R0](https://wg21.link/p1120r0). -In Visual Studio 2019 version 16.2 and later, the following code produces a level 4 warning when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** starting in Visual Studio 2019 version 16.11): +In Visual Studio 2019 version 16.2 and later, the following code produces a level 4 C5054 warning when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** in Visual Studio 2019 version 16.11 and later): ```cpp enum E1 { a }; @@ -636,7 +646,7 @@ int main() { } ``` -Using a binary operation between an enumeration and a floating-point type is now a warning when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** starting in Visual Studio 2019 version 16.11): +Using a binary operation between an enumeration and a floating-point type is now a level 1 C5055 warning when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** in Visual Studio 2019 version 16.11 and later): ```cpp enum E1 { a }; @@ -656,7 +666,7 @@ int main() { ### Equality and relational comparisons of arrays -Equality and relational comparisons between two operands of array type are deprecated in C++20 ([P1120R0](https://wg21.link/p1120r0)). In other words, a comparison operation between two arrays (despite rank and extent similarities) is now a warning. Starting in Visual Studio 2019 version 16.2, the following code produces C5056 when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** starting in Visual Studio 2019 version 16.11): +Equality and relational comparisons between two operands of array type are deprecated in C++20 ([P1120R0](https://wg21.link/p1120r0)). In other words, a comparison operation between two arrays (despite rank and extent similarities) is now a warning. In Visual Studio 2019 version 16.2 and later, the following code produces level 1 warning C5056 when the **`/std:c++latest`** compiler option is enabled (**`/std:c++20`** in Visual Studio 2019 version 16.11 and later): ```cpp int main() { @@ -779,7 +789,6 @@ struct Comparer { return a.a < b.a; } }; - ``` ## Conformance improvements in Visual Studio 2019 version 16.3 @@ -818,7 +827,7 @@ int main() { ### New keywords `requires` and `concept` -New keywords **`requires`** and **`concept`** have been added to the Microsoft C++ compiler. If you attempt to use either one as an identifier in **`/std:c++20`** or **`/std:c++latest`** mode, the compiler will raise C2059: "syntax error". +New keywords **`requires`** and **`concept`** have been added to the Microsoft C++ compiler. If you attempt to use either one as an identifier in **`/std:c++20`** or **`/std:c++latest`** mode, the compiler raises C2059 to indicate a syntax error. ### Constructors as type names disallowed @@ -844,7 +853,7 @@ class Foo { ### Stricter checking of `extern "C"` functions -If an **`extern "C"`** function was declared in different namespaces, previous versions of the Microsoft C++ compiler didn't check whether the declarations were compatible. Starting in Visual Studio 2019 version 16.3, the compiler checks for compatibility. In [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode, the following code produces errors C2371 and C2733: +If an **`extern "C"`** function was declared in different namespaces, previous versions of the Microsoft C++ compiler didn't check whether the declarations were compatible. In Visual Studio 2019 version 16.3 and later, the compiler checks for compatibility. In [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode, the following code produces errors C2371 and C2733: ```cpp using BOOL = int; @@ -934,7 +943,7 @@ In conformance mode (enabled by [`/permissive-`](../build/reference/permissive-s This change can lead to different warning diagnostics being generated, and behavior differences for arithmetic operations on literals. -The following example shows the new behavior in Visual Studio 2019 version 16.4. The `i` variable is now of type **`unsigned int`**. That's why the warning is raised. The high-order bits of the variable `j` are set to 0. +The following example shows the new behavior in Visual Studio 2019 version 16.4. The `i` variable is now of type **`unsigned int`**, so the warning is raised. The high-order bits of the variable `j` are set to 0. ```cpp void f(int r) { @@ -1240,7 +1249,7 @@ void f() { Previously, thread-local variables in DLLs weren't correctly initialized. Other than on the thread that loaded the DLL, they weren't initialized before first use on threads that existed before the DLL was loaded. This defect has now been corrected. Thread-local variables in such a DLL get initialized immediately before their first use on such threads. -This new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. Or, by adding the `[[msvc:no_tls_guard]]` attribute to particular thread local variables. +This new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. Or, by adding the `[[msvc::no_tls_guard]]` attribute to particular thread local variables. ### Better diagnosis of call to deleted functions @@ -1373,7 +1382,7 @@ There are many possible fixes: ### `switch` warnings for C -Starting in Visual Studio 2019 version 16.6, the compiler implements some preexisting C++ warnings for code compiled as C. The following warnings are now enabled at different levels: C4060, C4061, C4062, C4063, C4064, C4065, C4808, and C4809. Warnings C4065 and C4060 are disabled by default in C. +In Visual Studio 2019 version 16.6 and later, the compiler implements some preexisting C++ warnings for code compiled as C. The following warnings are now enabled at different levels: C4060, C4061, C4062, C4063, C4064, C4065, C4808, and C4809. Warnings C4065 and C4060 are disabled by default in C. The warnings trigger on missing **`case`** statements, undefined **`enum`**, and bad **`bool`** switch statements (that is, ones that contain too many cases). For example: @@ -1407,7 +1416,7 @@ int main() { ### Unnamed classes in `typedef` declarations -Starting in Visual Studio 2019 version 16.6, the behavior of **`typedef`** declarations has been restricted to conform to [P1766R1](https://wg21.link/P1766R1). With this update, unnamed classes within a **`typedef`** declaration can't have any members other than: +In Visual Studio 2019 version 16.6 and later, the behavior of **`typedef`** declarations has been restricted to conform to [P1766R1](https://wg21.link/P1766R1). With this update, unnamed classes within a **`typedef`** declaration can't have any members other than: - non-static data members with no default member initializers, - member classes, or @@ -1447,7 +1456,7 @@ typedef struct S_ : B { ### Default argument import in C++/CLI -An increasing number of APIs have default arguments in .NET Core. That's why we now support default argument import in C++/CLI. This change can break existing code where multiple overloads are declared, as in this example: +An increasing number of APIs have default arguments in .NET Core. So, we now support default argument import in C++/CLI. This change can break existing code where multiple overloads are declared, as in this example: ```cpp public class R { @@ -1883,7 +1892,7 @@ struct promise_type { #### Type of `yield_value` -In C++20, the promise `yield_value` function must return an awaitable. In **`/await`** mode, the `yield_value` function was permitted to return **`void`**, and would always suspend. Such functions can be replaced with a function that returns `std::suspend_always`. +In C++20, the promise `yield_value` function must return an awaitable type. In **`/await`** mode, the `yield_value` function was permitted to return **`void`**, and would always suspend. Such functions can be replaced with a function that returns `std::suspend_always`. ```cpp // /await @@ -1925,14 +1934,14 @@ C++20 doesn't support coroutines with a return type that includes a placeholder auto my_generator() { ... co_yield next; -}; +} // /std:c++latest #include std::experimental::generator my_generator() { ... co_yield next; -}; +} ``` #### Return type of `return_value` @@ -2068,10 +2077,14 @@ With this change, a destructor is also potentially throwing if it has a virtual ### Similar types and reference binding -Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). With this change, code that previously bound a reference to a temporary may now bind directly when the types involved differ only by cv-qualifiers. +Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). This affected Visual Studio 2019 versions 16.0 through 16.8. + +With this change, starting in Visual Studio 2019 version 16.9, code that previously bound a reference to a temporary in Visual Studio 2019 version 16.0 through 16.8 may now bind directly when the types involved differ only by cv-qualifiers. Visual Studio 2019 version 16.9 implements the changed behavior in all **`/std`** compiler modes. It's potentially a source breaking change. +See [References to types with mismatched cv-qualifiers](#references-to-types-with-mismatched-cv-qualifiers) for a related change. + This sample shows the changed behavior: ```cpp @@ -2160,7 +2173,7 @@ bool f(S a, S b) { } ``` -However, the compiler wouldn't invoke the comparison function the author might expect. The code above should have rewritten `a < b` as `(a <=> b) < 0`. Instead, the compiler used the `operator bool()` user-defined conversion function and compared `bool(a) < bool(b)`. Starting in Visual Studio 2019 version 16.9, the compiler rewrites the expression using the expected spaceship operator expression. +However, the compiler wouldn't invoke the comparison function the author might expect. The code above should have rewritten `a < b` as `(a <=> b) < 0`. Instead, the compiler used the `operator bool()` user-defined conversion function and compared `bool(a) < bool(b)`. In Visual Studio 2019 version 16.9 and later, the compiler rewrites the expression using the expected spaceship operator expression. #### Source breaking change @@ -2180,7 +2193,7 @@ struct Derived : Base { bool b = Base{} == Derived{}; ``` -In C++17, this code would be accepted because of the derived-to-base conversion of `Derived` on the right-hand side of the expression. In C++20, the synthesized expression candidate is also added: `Derived{} == Base{}`. Because of the rules in the standard about which function wins based on conversions, it turns out that the choice between `Base::operator==` and `Derived::operator==` is undecidable. That's because the conversion sequences in the two expressions are no better or worse than each other, so the example code results in an ambiguity. +In C++17, this code would be accepted because of the derived-to-base conversion of `Derived` on the right-hand side of the expression. In C++20, the synthesized expression candidate is also added: `Derived{} == Base{}`. Because of the rules in the standard about which function wins based on conversions, it turns out that the choice between `Base::operator==` and `Derived::operator==` is undecidable. Because the conversion sequences in the two expressions are no better or worse than each other, the example code results in an ambiguity. To resolve the ambiguity, add a new candidate that won't be subject to the two conversion sequences: @@ -2236,7 +2249,7 @@ void f(A); f(C{}); ``` -Earlier versions of the compiler would incorrectly convert the argument of `f` from type `C` to an `A` by using the templated converting constructor of `A`. Standard C++ requires use of the conversion operator `B::operator A` instead. Starting in Visual Studio 2019 version 16.10, the overload resolution behavior is changed to use the correct overload. +Earlier versions of the compiler would incorrectly convert the argument of `f` from type `C` to an `A` by using the templated converting constructor of `A`. Standard C++ requires use of the conversion operator `B::operator A` instead. In Visual Studio 2019 version 16.10 and later, the overload resolution behavior is changed to use the correct overload. This change can also correct the chosen overload in some other situations: @@ -2265,7 +2278,7 @@ void f(Derived &d) ### Incorrect parsing of floating-point literals -Starting in Visual Studio 2019 version 16.10, floating-point literals are parsed based on their actual type. Earlier versions of the compiler always parsed a floating-point literal as if it had type **`double`** and then converted the result to the actual type. This behavior could lead to incorrect rounding and rejection of valid values: +In Visual Studio 2019 version 16.10 and later, floating-point literals are parsed based on their actual type. Earlier versions of the compiler always parsed a floating-point literal as if it had type **`double`** and then converted the result to the actual type. This behavior could lead to incorrect rounding and rejection of valid values: ```cpp // The binary representation is '0x15AE43FE' in VS2019 16.9 @@ -2288,7 +2301,7 @@ struct S { S s(4, &s); ``` -The compiler wouldn't declare the variable `s` until it parsed the whole declaration, including the constructor arguments. The lookup of the `s` in the constructor argument list would fail. Starting in Visual Studio 2019 version 16.10, this example now compiles correctly. +The compiler wouldn't declare the variable `s` until it parsed the whole declaration, including the constructor arguments. The lookup of the `s` in the constructor argument list would fail. In Visual Studio 2019 version 16.10 and later, this example now compiles correctly. Unfortunately, this change can break existing code, as in this example: @@ -2300,11 +2313,13 @@ S s(1, nullptr); // outer s } ``` -In earlier versions of the compiler, when it looks up `s` in the constructor arguments for the "inner" declaration of `s`, it finds the previous declaration ("outer" `s`) and the code compiles. Starting in version 16.10, the compiler emits warning [C4700](../error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md) instead. That's because the compiler now declares the "inner" `s` before parsing the constructor arguments. So, the `s` lookup finds the "inner" `s`, which hasn't been initialized yet. +In earlier versions of the compiler, when it looks up `s` in the constructor arguments for the "inner" declaration of `s`, it finds the previous declaration ("outer" `s`) and the code compiles. Starting in version 16.10, the compiler emits warning [C4700](../error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md) instead. It's because the compiler now declares the "inner" `s` before parsing the constructor arguments. So, the `s` lookup finds the "inner" `s`, which hasn't been initialized yet. ### Explicitly specialized member of a class template -Earlier versions of the compiler incorrectly marked an explicit specialization of a class template member as `inline` if it was also defined in the primary template. This behavior meant the compiler would sometimes reject conforming code. Starting in Visual Studio 2019 version 16.10, an explicit specialization is no longer implicitly marked as `inline` in **`/permissive-`** mode. Consider this example: +Earlier versions of the compiler incorrectly marked an explicit specialization of a class template member as `inline` if it was also defined in the primary template. This behavior meant the compiler would sometimes reject conforming code. In Visual Studio 2019 version 16.10 and later, an explicit specialization is no longer implicitly marked as `inline` in **`/permissive-`** mode. Consider this example: + +Source file `s.h`: ```cpp // s.h @@ -2315,11 +2330,15 @@ struct S { template<> int S::f() { return 2; } ``` +Source file `s.cpp`: + ```cpp // s.cpp #include "s.h" ``` +Source file `main.cpp`: + ```cpp // main.cpp #include "s.h" @@ -2337,7 +2356,7 @@ template<> inline int S::f() { return 2; } ### Deduced return type name mangling -Starting in Visual Studio 2019 version 16.10, the compiler changed how it generates mangled names for functions that have deduced return types. For example, consider these functions: +In Visual Studio 2019 version 16.10 and later, the compiler changed how it generates mangled names for functions that have deduced return types. For example, consider these functions: ```cpp auto f() { return 0; } @@ -2377,11 +2396,15 @@ Earlier versions of the compiler would include the deduced return type as part o The new compiler behavior can produce a binary breaking change. Consider this example: +Source file `a.cpp`: + ```cpp // a.cpp auto f() { return 1; } ``` +Source file `main.cpp`: + ```cpp // main.cpp int f(); @@ -2398,7 +2421,7 @@ Previous versions of the compiler would silently ignore certain uses of a `nodis static [[nodiscard]] int f() { return 1; } ``` -Starting in Visual Studio 2019 version 16.10, the compiler emits level 4 warning C5240 instead: +In Visual Studio 2019 version 16.10 and later, the compiler emits level 4 warning C5240 instead: ```Console a.cpp(1): warning C5240: 'nodiscard': attribute is ignored in this syntactic position @@ -2412,7 +2435,7 @@ To fix this issue, move the attribute to the correct syntactic position: ### Warning for `include` directives with system header-names in module purview -Starting in Visual Studio 2019 version 16.10, the compiler emits a warning to prevent a common module interface authoring mistake. If you include a standard library header after an `export module` statement, the compiler emits warning C5244. Here's an example: +In Visual Studio 2019 version 16.10 and later, the compiler emits a warning to prevent a common module interface authoring mistake. If you include a standard library header after an `export module` statement, the compiler emits warning C5244. Here's an example: ```cpp export module m; @@ -2441,7 +2464,7 @@ void f(std::vector); ### Warning for unused internal linkage functions -Starting in Visual Studio 2019 version 16.10, the compiler warns in more situations where an unreferenced function with internal linkage has been removed. Earlier versions of the compiler would emit warning [C4505](../error-messages/compiler-warnings/compiler-warning-level-4-c4505.md) for the following code: +In Visual Studio 2019 version 16.10 and later, the compiler warns in more situations where an unreferenced function with internal linkage has been removed. Earlier versions of the compiler would emit warning [C4505](../error-messages/compiler-warnings/compiler-warning-level-4-c4505.md) for the following code: ```cpp static void f() // warning C4505: 'f': unreferenced function with internal linkage has been removed @@ -2467,7 +2490,7 @@ auto f2() // warning C5245: 'f2': unreferenced function with internal linkage ha ### Warning on brace elision -Starting in Visual Studio 2019 version 16.10, the compiler warns on initialization lists that don't use braces for subobjects. The compiler emits [off-by-default](../preprocessor/compiler-warnings-that-are-off-by-default.md) warning C5246. +In Visual Studio 2019 version 16.10 and later, the compiler warns on initialization lists that don't use braces for subobjects. The compiler emits [off-by-default](../preprocessor/compiler-warnings-that-are-off-by-default.md) warning C5246. Here's an example: @@ -2492,7 +2515,7 @@ S2 s2{ { 1, 2 }, 3 }; ### Correctly detect if a `const` object isn't initialized -Starting in Visual Studio 2019 version 16.10, the compiler now emits error C2737 when you attempt to define a `const` object that isn't fully initialized: +In Visual Studio 2019 version 16.10 and later, the compiler now emits error C2737 when you attempt to define a `const` object that isn't fully initialized: ```cpp struct S { @@ -2518,7 +2541,7 @@ struct S { ### `/std:c++20` compiler mode -Starting in Visual Studio 2019 version 16.11, the compiler now supports the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler mode. Previously, C++20 features were available only in [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) mode in Visual Studio 2019. Features that originally required **`/std:c++latest`** mode now work in **`/std:c++20`** mode or later in the latest versions of Visual Studio. +In Visual Studio 2019 version 16.11 and later, the compiler now supports the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler mode. Previously, C++20 features were available only in [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) mode in Visual Studio 2019. C++20 features that originally required **`/std:c++latest`** mode now work in **`/std:c++20`** mode or later in the latest versions of Visual Studio. ## See also diff --git a/docs/overview/cpp-conformance-improvements.md b/docs/overview/cpp-conformance-improvements.md index 7fd93ff907..2249e10efa 100644 --- a/docs/overview/cpp-conformance-improvements.md +++ b/docs/overview/cpp-conformance-improvements.md @@ -1,18 +1,948 @@ --- title: "C++ conformance improvements in Visual Studio 2022" description: "Microsoft C++ in Visual Studio is improving standards conformance and fixing bugs regularly." -ms.date: 10/23/2021 -ms.technology: "cpp-language" +ms.date: 05/13/2025 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 -Microsoft C/C++ in Visual Studio (MSVC) makes conformance improvements and bug fixes in every release. This article lists the improvements by major release, then by version. To jump directly to the changes for a specific version, use the list below **In this article**. +Microsoft C/C++ in Visual Studio (MSVC) makes conformance improvements and bug fixes in every release. This article lists the significant improvements by major release, then by version. To jump directly to the changes for a specific version, use the **In this article** links at the top of this article. -This document lists the changes in Visual Studio 2022. For a guide to the changes in Visual Studio 2019, see [C++ conformance improvements in Visual Studio 2019](cpp-conformance-improvements-2019.md). For changes in Visual Studio 2017, see [C++ conformance improvements in Visual Studio 2017](cpp-conformance-improvements-2017.md). For a complete list of previous conformance improvements, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). +This document lists the changes in Visual Studio 2022. -## Conformance improvements in Visual Studio 2022 version 17.0 +For changes in earlier versions of Visual Studio: -Visual Studio 2022 version 17.0 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C++ compiler. +| Version | Conformance improvements link | +|---|---| +| 2019 | [C++ conformance improvements in Visual Studio 2019](cpp-conformance-improvements-2019.md) | +| 2017 | [C++ conformance improvements in Visual Studio 2017](cpp-conformance-improvements-2017.md) | +| 2003-2015 | [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md) | + +## Conformance improvements in Visual Studio 2022 version 17.14 + +Visual Studio 2022 version 17.14 includes the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Conformance improvements + +- Standard library hardening ([P3471R4](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p3471r4.html)) turns some instances of undefined behavior in the standard library into a call to [__fastfail](../intrinsics/fastfail.md). Off by default. Define `_MSVC_STL_HARDENING=1` project-wide to enable. + +### Enhanced behavior + +- Implemented "destructor tombstones" to mitigate use-after-free mistakes. Off by default. Define `_MSVC_STL_DESTRUCTOR_TOMBSTONES=1` project-wide to enable. + +### Bug fixes + +- Fixed errant compiler errors when using `` in a CUDA project. +- Fixed a compiler issue where the address of a local variable could "leak" during `constexpr` evaluation. For example: + + ```cpp + const unsigned & func() + { + const int x = 0; + constexpr const unsigned & r1 = x; // Previously accepted, now an error + return r1; + } + + auto r = func(); // Previously, the local address leaked + ``` + + **Example #2** + + ```cpp + #include + + void test() + { + constexpr std::initializer_list xs { 1, 2, 3 }; // Previously accepted, now an error + + static constexpr std::initializer_list ys { 1, 2, 3 }; // Correct usage - note use of static + } + ``` + +- Code compiled with `/permissive-` no longer accepts a combination of `friend` and `static` on a declaration. The fix is usually to remove `static` from the declaration. For example: + + ```cpp + struct S + { + friend static void f(); // Previously accepted, now emits error C2440: 'static' cannot be used with 'friend' + }; + ``` + +- Reference binding to volatile-qualified types fixed when referring to a base or derived class. For example: + + ```cpp + struct A {}; + struct B : public A {}; + + void f(A&); // 1 + void f(const volatile A&); // 2 + + f(B{}); // Previously called 2. This is ill-formed under /permissive- or /Zc:referenceBinding. Chooses 1 if relaxed reference binding rules are enabled. + ``` + +For an in-depth summary of changes made to the Standard Template Library, including conformance changes, bug fixes, and performance improvements, see [STL Changelog VS 2022 17.14](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1714). + +## Conformance improvements in Visual Studio 2022 version 17.13 + +Visual Studio 2022 version 17.13 includes the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +For an in-depth summary of changes made to the Standard Template Library, including conformance changes, bug fixes, and performance improvements, see [STL Changelog VS 2022 17.13](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1713). + +### Argument-dependent lookup (ADL) + +Language constructs such as range-for and structured bindings have special argument-dependent lookup rules for certain identifiers such as `begin`, `end`, or `get`. Previously, this lookup included candidates from the `std` namespace, even when namespace `std` isn't part of the ordinary set of associated namespaces for argument-dependent lookup. + +Programs that introduced declarations to `std` for these constructs no longer compile. Instead, the declarations should be in a normal associated namespace for the types involved (possibly including the global namespace). + +```cpp +template +struct Foo {}; + +namespace std +{ + // To correct the program, move these declarations from std to the global namespace + template + T* begin(Foo& f); + template + T* end(Foo& f); +} + +void f(Foo foo) +{ + for (auto x : foo) // Previously compiled. Now emits error C3312: no callable 'begin' function found for type 'Foo' + { + ... + } +} +``` + +### Can't modify implementation-reserved macros + +Previously, the compiler permitted changing or undefining certain implementation-provided macros such as `_MSC_EXTENSIONS`. Altering the definition of certain macros can result in undefined behavior. + +Attempting to alter or undefine certain reserved macro names now results in the level-1 warning `C5308`. In `/permissive-` mode, this warning is treated as an error. + +```cpp +#undef _MSC_EXTENSIONS // Warning C5308: Modifying reserved macro name `_MSC_EXTENSIONS` may cause undefined behavior +``` + +## Conformance improvements in Visual Studio 2022 version 17.12 + +Visual Studio 2022 version 17.12 includes the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +For an in-depth summary of changes made to the Standard Template Library, including conformance changes, bug fixes, and performance improvements, see [STL Changelog VS 2022 17.12](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1712). + +### `_com_ptr_t::operator bool()` is now explicit + +This is a source/binary breaking change. + +The implicit conversion to `bool` from `_com_ptr_t` instances can be surprising or lead to compiler errors. [C.164: Avoid implicit conversion operators](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c164-avoid-implicit-conversion-operators) in the C++ Core Guidelines discourage implicit conversion functions. And `_com_ptr_t` contained implicit conversions to both `bool` and `Interface*`. These two implicit conversions can lead to ambiguities. + +To address this, the conversion to `bool` is now explicit. The conversion to `Interface*` is unchanged. + +A macro is provided to opt-out of this new behavior and restore the previous implicit conversion. Compile with `/D_COM_DISABLE_EXPLICIT_OPERATOR_BOOL` to opt-out of this change. We recommend that you modify the code to not rely on implicit conversions. + +For example: + +```cpp +#include + +template +using _com_ptr = _com_ptr_t<_com_IIID>; + +int main() +{ + _com_ptr unk; + if (unk) // Still valid + { + // ... + } + bool b = unk; // Still valid. + int v = unk; // Previously permitted, now emits C2240: cannot convert from '_com_ptr_t<_com_IIID>' to 'int' +} +``` + +### Constant expressions are no longer always `noexcept` in permissive mode + +This is a source/binary breaking change. + +A constant expression was always `noexcept`, even if it involved a function call to a function declared with a potentially throwing exception specification. This wording was removed in C++17, although the Microsoft Visual C++ compiler still supported it in `/permissive` mode in all C++ language versions. + +This `/permissive` mode behavior is removed. Constant expressions are no longer given special implicit behavior. + +The `noexcept` specifier on `constexpr` functions is now respected in all modes. This change is required for correct implementation of later core issue resolutions that rely on the standard `noexcept` behavior. + +For example: + +```cpp +constexpr int f(bool b) noexcept(false) +{ + if (b) + { + throw 1; + } + else + { + return 1; + } +} + +void g(bool b) +{ + noexcept(f(b)); // false. No change to behavior + noexcept(f(true)); // false. No change to behavior + noexcept(f(false)); // false. Was true in /permissive mode only in previous versions. +} +``` + +## Conformance improvements in Visual Studio 2022 version 17.11 + +Visual Studio 2022 version 17.11 includes the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +For an in-depth summary of changes made to the Standard Template Library, including conformance changes, bug fixes, and performance improvements, see [STL Changelog VS 2022 17.11](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1711). + +### Print blank lines with `println` + +Per [P3142R0](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p3142r0.pdf), it's now easy to generate a blank line with `println`. This feature is available when compiling with `/std:c++latest`. +Before this change, you wrote: `println("");` Now you write: `println();`. +- `println();` is equivalent to `println(stdout);` +- `println(FILE* stream);` is equivalent to `println(stream, "\n");` + +### Implemented `range_formatter` + +Per [P2286R8](https://wg21.link/P2286R8), `range_formatter` is now implemented. This feature is available when compiling with `/std:c++latest`. + +## Conformance improvements in Visual Studio 2022 version 17.10 + +Visual Studio 2022 version 17.10 includes the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +For an in-depth summary of changes made to the Standard Template Library, including conformance changes, bug fixes, and performance improvements, see [STL Changelog VS 2022 17.10](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1710). + +### Conversion operator specialization with explicitly specified return type + +The compiler used to specialize conversion operators incorrectly in some cases, which could lead to a mismatched return type. These invalid specializations no longer happen. This is a source code breaking change. + +```cpp +// Example 1 +struct S +{ + template operator const T*(); +}; + +void test() +{ + S{}.operator int*(); // this is invalid now + S{}.operator const int*(); // this is valid +} +``` + +```cpp +// Example 2 +// In some cases, the overload resolution result may change +struct S +{ + template operator T*(); // overload 1 + template operator const T*(); // overload 2 +}; + +void test() +{ + S{}.operator int*(); // this used to call overload 2, now it calls overload 1 +} +``` + +### Added Support for `#elifdef` and `#elifndef` + +Support added for WG21 [P2334R1](https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2021/p2334r1.pdf) (C++23) and WG14 [N2645](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2645.pdf) (C++23) which introduced the `#elifdef` and `#elifndef` preprocessor directives. +Requires `/std:clatest` or `/std:c++latest`. + +Before: + +```cpp +#ifdef __cplusplus + #include +#elif !defined(__STDC_NO_ATOMICS__) + #include +#else + #include +#endif +``` + +After: + +```cpp +#ifdef __cplusplus + #include +#elifndef __STDC_NO_ATOMICS__ + #include +#else + #include +#endif +``` + +### Application of `_Alignas` on a structured type in C + +Applies to the C language (C17 and later). Also added to Microsoft Visual Studio 17.9 + +In versions of Visual C++ before Visual Studio 2022 version 17.9, if the `_Alignas` specifier appeared next to a structured type in a declaration, it wasn't applied correctly according to the ISO-C Standard. + +```cpp +// compile with /std:c17 +#include + +struct Outer +{ + _Alignas(32) struct Inner { int i; } member1; + struct Inner member2; +}; +static_assert(offsetof(struct Outer, member2)==4, "incorrect alignment"); +``` + +According to the ISO-C Standard, this code should compile without `static_assert` emitting a diagnostic. + +The `_Alignas` directive applies only to the member variable `member1`. It must not change the alignment of `struct Inner`. However, before Visual Studio 17.9.1, the diagnostic "incorrect alignment" was emitted. The compiler aligned `member2` to an offset of 32 bytes within the `struct Outer` type. + +This is a binary breaking change, so a warning is now emitted when this change takes effect. Warning C5274 is now emitted at warning level 1 for the previous example: ` +warning C5274: behavior change: _Alignas no longer applies to the type 'Inner' (only applies to declared data objects)`. + +Also, in previous versions of Visual Studio, when the `_Alignas` specifier appeared next to an anonymous type declaration, it was ignored. + +```cpp +// compile with /std:c17 +#include +struct S +{ + _Alignas(32) struct { int anon_member; }; + int k; +}; + +static_assert(offsetof(struct S, k)==4, "incorrect offsetof"); +static_assert(sizeof(struct S)==32, "incorrect size"); +``` + +Previously, both `static_assert` statements failed when compiling this code. Now the code compiles, but emits the following level 1 warnings: + +```c +warning C5274: behavior change: _Alignas no longer applies to the type '' (only applies to declared data objects) +warning C5273: behavior change: _Alignas on anonymous type no longer ignored (promoted members will align) +``` + +To get the previous behavior, replace `_Alignas(N)` with `__declspec(align(N))`. Unlike `_Alignas`, `declspec(align)` applies to the type. + +### Improved warning C4706 + +This is a source code breaking change. Previously, the compiler didn't detect the convention of wrapping an assignment in parentheses, if assignment was intended, to suppress [warning C4706](../error-messages/compiler-warnings/compiler-warning-level-4-c4706.md) about assignment within a conditional expression. The compiler now detects the parentheses and suppresses the warning. + +```cpp +#pragma warning(error: 4706) + +struct S +{ + auto mf() + { + if (value = 9) + return value + 4; + else + return value; + } + + int value = 9; +}; +``` + +The compiler now also emits the warning in cases where the function isn't referenced. Previously, because `mf` is an inline function that isn't referenced, warning C4706 wasn't emitted for this code. Now the warning is emitted: + +```cpp +error C4706: assignment used as a condition +note: if an assignment is intended you can enclose it in parentheses, '(e1 = e2)', to silence this warning +``` + +To fix this warning, either use an equality operator, `value == 9`, if this is what was intended. Or, wrap the assignment in parentheses, `(value = 9)`, if assignment is intended. Otherwise, since the function is unreferenced, remove it. + +## Conformance improvements in Visual Studio 2022 version 17.9 + +Visual Studio 2022 version 17.9 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +For a broader summary of changes made to the Standard Template Library, see [STL Changelog VS 2022 17.9](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-179). + +### Application of `_Alignas` on a structured type in C + +In versions of Visual C++ before Visual Studio 2022 version 17.9, when `_Alignas` appeared next to a structure type in a declaration, it wasn't applied correctly according to the ISO-C Standard. For example: + +```c +// compile with /std:c17 +#include +struct Outer +{ + _Alignas(32) struct Inner { int i; } member1; + struct Inner member2; +}; +static_assert(offsetof(struct Outer, member2)==4, "incorrect alignment"); +``` + +According to the ISO-C Standard, this code should compile without the `static_assert` emitting a diagnostic. The `_Alignas` directive applies only to the member variable `member1`. It must not change the alignment of `struct Inner`. However, before release 17.9.1 of Visual Studio, the diagnostic "incorrect alignment" was emitted. The compiler aligned `member2` to a 32 byte offset within `struct Outer`. + +Fixing this is a binary breaking change, so when this change in behavior is applied a warning is emitted. For the preceding code, Warning C5274, "`_Alignas` no longer applies to the type 'Inner' (only applies to declared data objects)" is now emitted at warning level 1. + +In previous versions of Visual Studio, `_Alignas` was ignored when it appeared next to an anonymous type declaration. For example: + +```c +// compile with /std:c17 +#include +struct S { + _Alignas(32) struct { int anon_member; }; + int k; +}; +static_assert(offsetof(struct S, k)==4, "incorrect offsetof"); +static_assert(sizeof(struct S)==32, "incorrect size"); +``` + +Previously, both `static_assert` statements failed when compiling this code. The code now compiles, but with the following level 1 warnings: + +```c +warning C5274: behavior change: _Alignas no longer applies to the type '' (only applies to declared data objects) +warning C5273: behavior change: _Alignas on anonymous type no longer ignored (promoted members will align) +``` + +If you want the earlier behavior, replace `_Alignas(N)` with `__declspec(align(N))`. Unlike `_Alignas`, `declspec(align)` can be applied to a type. + +### `__VA_OPT__` is enabled as an extension under `/Zc:preprocessor` + +`__VA_OPT__` was added to C++20 and C23. Previous to its addition, there wasn't a standard way to elide a comma in a variadic macro. To provide better backward compatibility, `__VA_OPT__` is enabled under the token based preprocessor `/Zc:preprocessor` across all language versions. + +For example, this now compiles without error: + +```cpp +#define LOG_WRAPPER(message, ...) WRITE_LOG(__LINE__, message __VA_OPT__(, __VA_ARGS__)) + +// Failed to build under /std:c11, now succeeds. +LOG_WRAPPER("Log message"); +LOG_WRAPPER("Log message with %s", "argument") +``` + +### C23 language ### + +For C23, the following are available when using the `/std:clatest` compiler switch: + +[`typeof`](../c-language/typeof-c.md)\ +[`typeof_unqual`](../c-language/typeof-unqual-c.md) + +The following are available for all C language versions: + +[`__typeof__`](../c-language/typeof-c.md)\ +[`__typeof_unqual__`](../c-language/typeof-unqual-c.md) + +### C++ Standard Library + +**C++23 features** + +- `formattable`, `range_format`, `format_kind`, and `set_debug_format()` as part of [P2286R8 Formatting Ranges](https://wg21.link/P2286R8) +- `` per [P0009R18](https://wg21.link/P0009R18) and subsequent wording changes that were applied to the C++23 Standard. +- `format()` pointers per [P2510R3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2510r3.pdf). + +## Conformance improvements in Visual Studio 2022 version 17.8 + +Visual Studio 2022 version 17.8 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### `/FU` issues an error + +The C compiler used to accept the `/FU` option, even though it hasn't support managed compilation for some time. It now issues an error. Projects that pass this option need to restrict it to C++/CLI projects only. + +### C++ Standard Library + +The C++23 named modules `std` and `std.compat` are now available when compiling with `/std:c++20`. + +For a broader summary of changes made to the C++ Standard Library, see [STL Changelog VS 2022 17.8](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-178). + +## Conformance improvements in Visual Studio 2022 version 17.7 + +Visual Studio 2022 version 17.7 contains the following highlighted conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Added `/std:clatest` to the C compiler + +This switch behaves like the `/std:c++latest` switch for the C++ compiler. The switch enables all currently implemented compiler and standard library features proposed for the next draft C standard, as well as some in-progress and experimental features. + +### C++ Standard Library + +The `` library is now supported. See [P2093R14 Formatted output](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2093r14.html). + +Implemented `views::cartesian_product`. + +For a broader summary of changes made to the Standard Template Library, see [STL Changelog VS 2022 17.7](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-177). + +### `using` conformance + +Previously, the `using` directive could cause names from used namespaces to remain visible when they shouldn't. This could cause unqualified name lookup to find a name in a namespace even when there's no `using` directive active. + +Here are some examples of the new and old behavior.\ +References in the following comments to "(1)" mean the call to `f(t)` in namespace `A`: + +```cpp +namespace A +{ + template + auto f2(T t) + { + return f(t); // (1) Unqualified lookup should not find anything + } +} + +namespace B +{ + template + auto f(T t) noexcept + { // Previous behavior: This function was erroneously found during unqualified lookup at (1) + return A::f2(t); + } +} + +namespace C +{ + template + struct S {}; + + template + U&& f(U&&) noexcept; // New behavior: ADL at (1) correctly finds this function +} + +namespace D +{ + using namespace B; + + void h() + { + D::f(C::S()); + } +} +``` + +The same underlying issue can cause code that previously compiled to now be rejected: + +```cpp +#include +namespace Addin {} +namespace Gui +{ + using namespace Addin; +} + +namespace Addin +{ + using namespace std; +} + +// This previously compiled, but now emits error C2065 for undeclared name 'allocator'. +// This should be declared as 'std::allocator' because the using directive nominating +// 'std' is not active at this point. +template > +class resource_list +{ +}; + +namespace Gui +{ + typedef resource_list intlist; +} +``` + +## Conformance improvements in Visual Studio 2022 version 17.6 + +Visual Studio 2022 version 17.6 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Compound `volatile` assignments no longer deprecated + +C++20 deprecated applying certain operators to types qualified with `volatile`. For example, when the following code is compiled with `cl /std:c++20 /Wall test.cpp`: + +```cpp +void f(volatile int& expr) +{ + ++expr; +} +``` + +The compiler produces `test.cpp(3): warning C5214: applying '++' to an operand with a volatile qualified type is deprecated in C++20`. + +In C++20, compound assignment operators (operators of the form `@=`) were deprecated. In C++23, compound operators excluded in C++20 are no longer deprecated. For example, in C++23 the following code doesn't produce a warning, whereas it does in C++20: + +```cpp +void f(volatile int& e1, int e2) +{ + e1 += e2; +} +``` + +For more information about this change, see [CWG:2654](https://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#2654) + +### Rewriting equality in expressions is less of a breaking change (P2468R2) + +In C++20, [P2468R2](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2468r2.html) changed the compiler to accept code such as: + +```cpp +struct S +{ + bool operator==(const S&); + bool operator!=(const S&); +}; +bool b = S{} != S{}; +``` + +The compiler accepts this code, which means that the compiler is more strict with code such as: + +```cpp +struct S +{ + operator bool() const; + bool operator==(const S&); +}; + +bool b = S{} == S{}; +``` + +Version 17.5 of the compiler accepts this program. Version 17.6 of the compiler rejects it. To fix it, add `const` to `operator==` to remove the ambiguity. Or, add a corresponding `operator!=` to the definition as shown in the following example: + +```cpp +struct S +{ + operator bool() const; + bool operator==(const S&); + bool operator!=(const S&); +}; + +bool b = S{} == S{}; +``` + +Microsoft C/C++ compiler versions 17.5 and 17.6 accept the previous program, and calls `S::operator==` in both versions. + +The general programming model outlined in P2468R2 is that if there's a corresponding `operator!=` for a type, it typically suppresses the rewrite behavior. Adding a corresponding `operator!=` is the suggested fix for code that previously compiled in C++17. For more information, see [Programming Model](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2468r2.html#programming-model). + +## Conformance improvements in Visual Studio 2022 version 17.4 + +Visual Studio 2022 version 17.4 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Underlying types of unscoped `enum` with no fixed type + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly determine the underlying type of an unscoped enumeration with no fixed base type. Under [`/Zc:enumTypes`](../build/reference/zc-enumtypes.md), we now correctly implement the standard behavior. + +The C++ Standard requires the underlying type of an **`enum`** to be large enough to hold all enumerators in that **`enum`**. Sufficiently large enumerators can set the underlying type of the **`enum`** to **`unsigned int`**, **`long long`**, or **`unsigned long long`**. Previously, such **`enum`** types always had an underlying type of **`int`** in the Microsoft compiler, regardless of enumerator values. + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. It's off by default, and not enabled by **`/permissive-`**, because the fix might affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. + +#### Example + +```cpp +enum Unsigned +{ + A = 0xFFFFFFFF // Value 'A' does not fit in 'int'. +}; + +// Previously, failed this static_assert. Now passes with /Zc:enumTypes. +static_assert(std::is_same_v, unsigned int>); + +template +void f(T x) +{ +} + +int main() +{ + // Previously called f, now calls f. + f(+A); +} + +// Previously this enum would have an underlying type of `int`, but Standard C++ requires this to have +// a 64-bit underlying type. Using /Zc:enumTypes changes the size of this enum from 4 to 8, which could +// impact binary compatibility with code compiled with an earlier compiler version or without the switch. +enum Changed +{ + X = -1, + Y = 0xFFFFFFFF +}; +``` + +### Types of enumerators within an `enum` definition with no fixed underlying type + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly model the types of enumerators. It could assume an incorrect type in enumerations without a fixed underlying type before the closing brace of the enumeration. Under [`/Zc:enumTypes`](../build/reference/zc-enumtypes.md), the compiler now correctly implements the standard behavior. + +The C++ Standard specifies that within an enumeration definition of no fixed underlying type, initializers determine the types of enumerators. Or, for the enumerators with no initializer, by the type of the previous enumerator (accounting for overflow). Previously, such enumerators were always given the deduced type of the enumeration, with a placeholder for the underlying type (typically **`int`**). + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. It's off by default, and not enabled by **`/permissive-`**, because the fix might affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. + +#### Example + +```cpp +enum Enum { + A = 'A', + B = sizeof(A) +}; + +static_assert(B == 1); // previously failed, now succeeds under /Zc:enumTypes +``` + +In this example the enumerator `A` should have type **`char`** before the closing brace of the enumeration, so `B` should be initialized using `sizeof(char)`. Before the **`/Zc:enumTypes`** fix, `A` had enumeration type `Enum` with a deduced underlying type **`int`**, and `B` was initialized using `sizeof(Enum)`, or 4. + +## Conformance improvements in Visual Studio 2022 version 17.3 + +Visual Studio 2022 version 17.3 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### C: Improved modifier compatibility checking between pointers + +The C compiler didn't properly compare modifiers between pointers, especially `void*`. This defect could result in an improper diagnosis of incompatibility between `const int**` and `void*` and compatibility between `int* volatile*` and `void*`. + +#### Example + +```c +void fn(void* pv) { (pv); } + +int main() +{ + int t = 42; + int* pt = &t; + int* volatile * i = &pt; + fn(i); // Now raises C4090 + const int** j = &pt; + fn(j); // No longer raises C4090 +} +``` + +## Conformance improvements in Visual Studio 2022 version 17.2 + +Visual Studio 2022 version 17.2 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Unterminated bidirectional character warnings + +Visual Studio 2022 version 17.2 adds level 3 warning C5255 for unterminated Unicode bidirectional characters in comments and strings. The warning addresses a security concern described in [Trojan Source: Invisible Vulnerabilities](https://www.trojansource.codes/trojan-source.pdf) by Nicholas Boucher and Ross Anderson. For more information on Unicode bidirectional characters, see [Unicode® Standard Annex #9: UNICODE BIDIRECTIONAL ALGORITHM](https://unicode.org/reports/tr9/). + +Warning C5255 only addresses files that, after conversion, contain Unicode bidirectional characters. This warning applies to UTF-8, UTF-16, and UTF-32 files, so the proper source-encoding must be provided. This change is a source breaking change. + +#### Example (before/after) + +In versions of Visual Studio before Visual Studio 2022 version 17.2, an unterminated bidirectional character didn't produce a warning. Visual Studio 2022 version 17.2 produces warning C5255: + +```cpp +// bidi.cpp +int main() { + const char *access_level = "user"; + // The following source line contains bidirectional Unicode characters equivalent to: + // if ( strcmp(access_level, "user\u202e \u2066// Check if admin \u2069 \u2066") ) { + // In most editors, it's rendered as: + // if ( strcmp(access_level, "user") ) { // Check if admin + if ( strcmp(access_level, "user‮ ⁦// Check if admin ⁩ ⁦") ) { + printf("You are an admin.\n"); + } + return 0; +} + +/* build output +bidi.cpp(8): warning C5255: unterminated bidirectional character encountered: 'U+202e' +bidi.cpp(8): warning C5255: unterminated bidirectional character encountered: 'U+2066' +*/ +``` + +### `from_chars()` `float` tiebreaker + +Visual Studio 2022 version 17.2 fixes a bug in `` `from_chars()` `float` tiebreaker rules that produced incorrect results. This bug affected decimal strings that were at the exact midpoint of consecutive `float` values, within a narrow range. (The smallest and largest affected values were `32768.009765625` and `131071.98828125`, respectively.) The tiebreaker rule wanted to round to "even," and "even" happened to be "down," but the implementation incorrectly rounded "up" (`double` was unaffected.) For more information and implementation details, see [microsoft/STL#2366](https://github.com/microsoft/STL/pull/2366). + +This change affects runtime behavior in the specified range of cases: + +#### Example + +```cpp +// from_chars_float.cpp +#include +#include +#include +#include +#include +using namespace std; +int main() { + const double dbl = 32768.009765625; + const auto sv = "32768.009765625"sv; + float flt = 0.0f; + const auto result = from_chars(sv.data(), sv.data() + sv.size(), flt); + assert(result.ec == errc{}); + printf("from_chars() returned: %.1000g\n", flt); + printf("This rounded %s.\n", flt < dbl ? "DOWN" : "UP"); +} +``` + +In versions before Visual Studio 2022 version 17.2: + +```Output +C:\Temp>cl /EHsc /nologo /W4 /std:c++17 from_chars_float.cpp && from_chars_float +from_chars_float.cpp +from_chars() returned: 32768.01171875 +This rounded UP. +``` + +In Visual Studio 2022 version 17.2 and after: + +```Output +C:\Temp>cl /EHsc /nologo /W4 /std:c++17 from_chars_float.cpp && from_chars_float +from_chars_float.cpp +from_chars() returned: 32768.0078125 +This rounded DOWN. +``` + +### `/Zc:__STDC__` makes `__STDC__` available for C + +The C standard requires that a conforming C implementation defines `__STDC__` as `1`. Due to the behavior of the UCRT, which doesn't expose POSIX functions when `__STDC__` is `1`, it isn't possible to define this macro for C by default without introducing breaking changes to the stable language versions. Visual Studio 2022 version 17.2 and later add a conformance option [`/Zc:__STDC__`](../build/reference/zc-stdc.md) that defines this macro. There's no negative version of the option. Currently, we plan to use this option by default for future versions of C. + +This change is a source breaking change. It applies when C11 or C17 mode is enabled (**`/std:c11`** or **`/std:c17`**) and **`/Zc:__STDC__`** is specified. + +#### Example + +```c +// test__STDC__.c +#include +#include +#include + +int main() { +#if __STDC__ + int f = _open("file.txt", _O_RDONLY); + _close(f); +#else + int f = open("file.txt", O_RDONLY); + close(f); +#endif +} + +/* Command line behavior + +C:\Temp>cl /EHsc /W4 /Zc:__STDC__ test__STDC__.c && test__STDC__ + +*/ +``` + +### Warning for missing braces + +Warning C5246 reports missing braces during aggregate initialization of a subobject. Before Visual Studio 2022 version 17.2, the warning didn't handle the case of an anonymous `struct` or `union`. + +This change is a source breaking change. It applies when the off-by-default warning C5246 is enabled. + +#### Example + +In Visual Studio 2022 version 17.2 and later, this code now causes an error: + +```cpp +struct S { + union { + float f[4]; + double d[2]; + }; +}; + +void f() +{ + S s = { 1.0f, 2.0f, 3.14f, 4.0f }; +} + +/* Command line behavior +cl /Wall /c t.cpp + +t.cpp(10): warning C5246: 'anonymous struct or union': the initialization of a subobject should be wrapped in braces +*/ +``` + +To resolve this issue, add braces to the initializer: + +```cpp +void f() +{ + S s = { { 1.0f, 2.0f, 3.14f, 4.0f } }; +} +``` + +## Conformance improvements in Visual Studio 2022 version 17.1 + +Visual Studio 2022 version 17.1 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Detect ill-formed capture default in nonlocal lambda-expressions + +The C++ Standard only allows a lambda expression in block scope to have a capture-default. In Visual Studio 2022 version 17.1 and later, the compiler detects when a capture default isn't allowed in a nonlocal lambda expression. It emits a new level 4 warning, C5253. + +This change is a source breaking change. It applies in any mode that uses the new lambda processor: **`/Zc:lambda`**, **`/std:c++20`**, or **`/std:c++latest`**. + +#### Example + +In Visual Studio 2022 version 17.1 this code now emits an error: + +```cpp +#pragma warning(error:5253) + +auto incr = [=](int value) { return value + 1; }; + +// capture_default.cpp(3,14): error C5253: a nonlocal lambda cannot have a capture default +// auto incr = [=](int value) { return value + 1; }; +// ^ +``` + +To fix this issue, remove the capture default: + +```cpp +#pragma warning(error:5253) + +auto incr = [](int value) { return value + 1; }; +``` + +### C4028 is now C4133 for function-to-pointer operations + +Before Visual Studio 2022 version 17.1, the compiler reported an incorrect error message on certain pointer-to-function comparisons in C code. The incorrect message was reported when you compared two function pointers that had the same argument counts but incompatible types. Now, we issue a different warning that complains about pointer-to-function incompatibility rather than function parameter mismatch. + +This change is a source breaking change. It applies when code is compiled as C. + +#### Example + +```C +int f1(int); +int f2(char*); +int main(void) +{ + return (f1 == f2); +} +// Old warning: +// C4028: formal parameter 1 different from declaration +// New warning: +// C4113: 'int (__cdecl *)(char *)' differs in parameter lists from 'int (__cdecl *)(int)' +``` + +### Error on a nondependent `static_assert` + +In Visual Studio 2022 version 17.1 and later, if the expression associated with a `static_assert` isn't a dependent expression, the compiler evaluates the expression when it's parsed. If the expression evaluates to `false`, the compiler emits an error. Previously, if the `static_assert` was within the body of a function template (or within the body of a member function of a class template), the compiler wouldn't perform this analysis. + +This change is a source breaking change. It applies in any mode that implies **`/permissive-`** or **`/Zc:static_assert`**. This change in behavior can be disabled by using the **`/Zc:static_assert-`** compiler option. + +#### Example + +In Visual Studio 2022 version 17.1 and later, this code now causes an error: + +```cpp +template +void f() +{ + static_assert(false, "BOOM!"); +} +``` + +To fix this issue, make the expression dependent. For example: + +```cpp +template +constexpr bool dependent_false = false; + +template +void f() +{ + static_assert(dependent_false, "BOOM!"); +} +``` + +With this change, the compiler only emits an error if the function template `f` is instantiated. + +## Conformance improvements in Visual Studio 2022 version 17.0 + +Visual Studio 2022 version 17.0 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. ### Warning on bitfield width for enumeration type @@ -51,7 +981,7 @@ bool f(int *p) } ``` -WG21 paper [N3478](https://wg21.link/n3478) removed this oversight. MSVC has now implemented this change. When the example is compiled by using **`/permissive-`** (and **`/diagnostics:caret`**), it emits the following error: +WG21 paper [N3478](https://wg21.link/n3478) removed this oversight. This change is implemented in MSVC. When the example is compiled by using **`/permissive-`** (and **`/diagnostics:caret`**), it emits the following error: ```Output t.cpp(3,14): error C7664: '>=': ordered comparison of pointer and integer zero ('int *' and 'int') diff --git a/docs/overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md b/docs/overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md index 82b3daf9fd..5fff09d04d 100644 --- a/docs/overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md +++ b/docs/overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md @@ -2,9 +2,10 @@ title: "How to report a problem with the Microsoft C++ toolset" description: How to create a good problem report and repro information for the Microsoft C++ toolset. ms.date: "09/24/2019" -ms.technology: "cpp-ide" -author: "corob-msft" -ms.author: "corob" +ms.service: "visual-cpp" +ms.subservice: "ide" +author: "tylermsft" +ms.author: "twhitney" --- # How to report a problem with the Microsoft C++ toolset or documentation @@ -12,9 +13,9 @@ If you find problems in the Microsoft C++ compiler (MSVC), the linker, or other ## How to report a C++ toolset issue -The best way to let us know about a problem is to send us a report that includes a description of the problem you've discovered. It should have all the details about how you build your program. And it should include a *repro*, a complete test case we can use to reproduce the problem on our own machines. This information lets us quickly verify that the problem exists in our code and isn't local to your environment. It helps us determine whether it affects other versions of the compiler, and to diagnose its cause. +The best way to let us know about a problem is to send us a report that includes a description of the problem you discovered. It should have all the details about how you build your program. And it should include a *repro*, a complete test case we can use to reproduce the problem on our own machines. This information lets us quickly verify that the problem exists in our code and isn't local to your environment. It helps us determine whether it affects other versions of the compiler, and to diagnose its cause. -In the sections below, you'll read about what makes a good report. We describe how to generate a repro for the kind of issue you've found, and how to send your report to the product team. Your reports are important to us and to other developers like you. Thank you for helping us improve Microsoft C++! +In the following sections, read about what makes a good report. We describe how to generate a repro for the kind of issue you found, and how to send your report to the product team. Your reports are important to us and to other developers like you. Thank you for helping us improve Microsoft C++! ## How to prepare your report @@ -65,15 +66,15 @@ Copy and paste the entire output into your report. ### The command line -We need the exact command line, cl.exe and all of its arguments, used to build your code. That's so we can build it in exactly the same way on our machines. It's important because the problem you've found might only exist when building with a certain argument or combination of arguments. +We need the exact command line, cl.exe and all of its arguments, used to build your code. That's so we can build it in exactly the same way on our machines. It's important because the problem you found might only exist when building with a certain argument or combination of arguments. The best place to find this information is in the build log immediately after you experience the problem. It ensures that the command line contains exactly the same arguments that might contribute to the problem. #### To report the contents of the command line -1. Locate the **CL.command.1.tlog** file and open it. By default, this file is located in your Documents folder in \\Visual Studio *version*\\Projects\\*SolutionName*\\*ProjectName*\\*Configuration*\\*ProjectName*.tlog\\CL.command.1.tlog, or in your User folder under \\Source\\Repos\\*SolutionName*\\*ProjectName*\\*Configuration*\\*ProjectName*.tlog\\CL.command.1.tlog. It may be in a different location if you use another build system, or if you've changed the default location for your project. +1. Locate the **CL.command.1.tlog** file and open it. By default, this file is located in your Documents folder in \\Visual Studio *version*\\Projects\\*SolutionName*\\*ProjectName*\\*Configuration*\\*ProjectName*.tlog\\CL.command.1.tlog, or in your User folder under \\Source\\Repos\\*SolutionName*\\*ProjectName*\\*Configuration*\\*ProjectName*.tlog\\CL.command.1.tlog. It may be in a different location if you use another build system, or if you changed the default location for your project. - Inside this file, you'll find the names of your source code files, followed by the command-line arguments used to compile them, each on separate lines. + Inside this file, find the names of your source code files, followed by the command-line arguments used to compile them, each on separate lines. 1. Locate the line that contains the name of the source code file where the problem occurs. The line below it contains the corresponding cl.exe command arguments. @@ -81,19 +82,19 @@ Copy and paste the entire command line into your report. ### A description of the problem -We need a detailed description of the problem you've found. That's so we can verify that we see the same effect on our machines. It's also sometimes useful for us to know what you were trying to accomplish, and what you expected to happen. +We need a detailed description of the problem you found. That's so we can verify that we see the same effect on our machines. It's also sometimes useful for us to know what you were trying to accomplish, and what you expected to happen. -A good description provides the **exact error messages** given by the toolset, or the exact runtime behavior you see. We need this information to verify that we've properly reproduced the issue. Include **all** of the compiler output, not just the last error message. We need to see everything that led up to the issue you report. If you can duplicate the issue by using the command-line compiler, that compiler output is preferred. The IDE and other build systems may filter the error messages you see, or only capture the first line of an error message. +A good description provides the **exact error messages** given by the toolset, or the exact runtime behavior you see. We need this information to verify that we properly reproduced the issue. Include **all** of the compiler output, not just the last error message. We need to see everything that led up to the issue you report. If you can duplicate the issue by using the command-line compiler, that compiler output is preferred. The IDE and other build systems may filter the error messages you see, or only capture the first line of an error message. If the issue is that the compiler accepts invalid code and doesn't generate a diagnostic, include that in your report. -To report a runtime behavior problem, include an **exact copy** of what the program prints, and what you expect to see. Ideally, you'll embed it in the output statement itself, for example, `printf("This should be 5: %d\n", actual_result);`. If your program crashes or hangs, mention that as well. +To report a runtime behavior problem, include an **exact copy** of what the program prints, and what you expect to see. Ideally, embed it in the output statement itself, for example, `printf("This should be 5: %d\n", actual_result);`. If your program crashes or hangs, mention that as well. -Add any other details that might help us diagnose the problem you found, such as any work-arounds you've discovered. Try not to repeat information found elsewhere in your report. +Add any other details that might help us diagnose the problem you found, such as any work-arounds you discovered. Try not to repeat information found elsewhere in your report. ### The repro -A *repro* is a complete, self-contained source code example. It reproducibly demonstrates the problem you've found, hence the name. We need a repro so that we can reproduce the error on our machines. The code should be sufficient by itself to create a basic executable that compiles and runs. Or, that *would* compile and run, if not for the problem you've found. A repro isn't a code snippet. It should have complete functions and classes, and contain all the necessary #include directives, even for the standard headers. +A *repro* is a complete, self-contained source code example. It reproducibly demonstrates the problem you found, hence the name. We need a repro so that we can reproduce the error on our machines. The code should be sufficient by itself to create a basic executable that compiles and runs. Or, that *would* compile and run, if not for the problem you found. A repro isn't a code snippet. It should have complete functions and classes, and contain all the necessary #include directives, even for the standard headers. #### What makes a good repro @@ -103,9 +104,9 @@ A good repro is: - **Self-Contained.** Repros should avoid unnecessary dependencies. If you can reproduce the problem without third-party libraries, then do so. If you can reproduce the problem without any library code besides simple output statements (for example, `puts("this shouldn't compile");`, `std::cout << value;`, and `printf("%d\n", value);`), then do so. It's ideal if the example can be condensed to a single source code file, without reference to any user headers. Reducing the amount of code we have to consider as a possible contributor to the problem is enormously helpful to us. -- **Against the latest compiler version.** Repros should use the most recent update to the latest version of the toolset whenever possible. Or, use the most recent prerelease version of the next update or next major release. Problems you may find in older versions of the toolset have often been fixed in newer versions. Fixes are backported to older versions only in exceptional circumstances. +- **Against the latest compiler version.** Repros should use the most recent update to the latest version of the toolset whenever possible. Or, use the most recent prerelease version of the next update or next major release. Problems you may find in older versions of the toolset are often fixed in newer versions. Fixes are backported to older versions only in exceptional circumstances. -- **Checked against other compilers** if relevant. Repros that involve portable C++ code should verify behavior against other compilers if possible. The C++ standard ultimately determines program correctness, and no compiler is perfect. However, when Clang and GCC accept your code without a diagnostic, and MSVC doesn't, you've probably found a bug in our compiler. (Other possibilities include differences in Unix and Windows behavior, or different levels of C++ standards implementation, and so on.) When all the compilers reject your code, then it's likely that your code is incorrect. Seeing different error messages may help you diagnose the issue yourself. +- **Checked against other compilers** if relevant. Repros that involve portable C++ code should verify behavior against other compilers if possible. The C++ standard ultimately determines program correctness, and no compiler is perfect. However, when Clang and GCC accept your code without a diagnostic, and MSVC doesn't, you probably found a bug in our compiler. (Other possibilities include differences in Unix and Windows behavior, or different levels of C++ standards implementation, and so on.) When all the compilers reject your code, then it's likely that your code is incorrect. Seeing different error messages may help you diagnose the issue yourself. You can find lists of online compilers to test your code against in [Online C++ compilers](https://isocpp.org/blog/2013/01/online-c-compilers) on the ISO C++ website, or this curated [List of Online C++ Compilers](https://arnemertz.github.io/online-compilers/) on GitHub. Some specific examples include [Wandbox](https://wandbox.org/) and [Compiler Explorer](https://godbolt.org/). @@ -168,7 +169,7 @@ If the line that begins with **INTERNAL COMPILER ERROR** mentions link.exe, rath #### Linker crash -Linker crashes occur during the linking phase, after the compiler has run. Typically, the linker will emit [Linker Tools Error LNK1000](../error-messages/tool-errors/linker-tools-error-lnk1000.md). +Linker crashes occur during the linking phase, after the compiler has run. Typically, the linker emits [Linker Tools Error LNK1000](../error-messages/tool-errors/linker-tools-error-lnk1000.md). > [!NOTE] > If the output mentions C1001 or involves Link-Time Code Generation, refer to [Backend (code generation) crash](#backend-code-generation-crash) instead. @@ -213,7 +214,7 @@ If incremental linking is enabled, and the crash occurred only after a successfu #### Bad code generation -Bad code generation is rare. It occurs when the compiler mistakenly generates incorrect code that causes your application to crash at runtime. Instead, it should generate correct code, or detect a problem at compile time. If you believe the problem you've found results in bad code generation, treat your report the same as a [Backend (code generation) crash](#backend-code-generation-crash). +Bad code generation is rare. It occurs when the compiler mistakenly generates incorrect code that causes your application to crash at runtime. Instead, it should generate correct code, or detect a problem at compile time. If you believe the problem you found results in bad code generation, treat your report the same as a [Backend (code generation) crash](#backend-code-generation-crash). For this kind of crash, provide a [Link repro](#link-repros) if you're using the **/GL** command-line argument to cl.exe. Provide a [Preprocessed repro](#preprocessed-repros) if not. @@ -221,11 +222,11 @@ For this kind of crash, provide a [Link repro](#link-repros) if you're using the To help us track down the source of the problem, a [good repro](#what-makes-a-good-repro) is vital. Before you do any of the steps outlined below for specific kinds of repros, try to condense the code that demonstrates the problem as much as possible. Try to eliminate or minimize dependencies, required headers, and libraries. Limit the compiler options and preprocessor definitions used, if possible. -Below are instructions for generating the various kinds of repros you'll use to report different kinds of problems. +Below are instructions for generating the various kinds of repros to use to report different kinds of problems. ### Preprocessed repros -A *Preprocessed repro* is a single source file that demonstrates a problem. It's generated from the output of the C preprocessor. To create one, use the **/P** compiler option on the original repro source file. This option inlines the included headers to remove dependencies on additional source and header files. The option also resolves macros, #ifdef conditionals, and other preprocessor commands that could depend on your local environment. +A *Preprocessed repro* is a single source file that demonstrates a problem. It's generated from the output of the C preprocessor. To create one, use the **/P** compiler option on the original repro source file. This option inlines the included headers to remove dependencies on other source and header files. The option also resolves macros, #ifdef conditionals, and other preprocessor commands that could depend on your local environment. > [!NOTE] > Preprocessed repros are not as useful for problems that might be the result of bugs in our standard library implementation, because we will often want to substitute our latest, in-progress implementation to see whether we've already fixed the problem. In this case, don't preprocess the repro, and if you can't reduce the problem to a single source file, package your code into a .zip file or similar, or consider using an IDE project repro. For more information, see [Other repros](#other-repros). @@ -240,9 +241,9 @@ A *Preprocessed repro* is a single source file that demonstrates a problem. It's 1. In the developer command prompt console window, enter the command **cl /P** *arguments* *filename.cpp*. For *arguments*, use the list of arguments you captured above. *filename.cpp* is the name of your repro source file. This command replicates the command line you used for the repro, but stops the compilation after the preprocessor pass. Then it writes the preprocessed source code to *filename.i*. -If you're preprocessing a C++/CX source code file, or you're using the C++ Modules feature, some additional steps are required. For more information, see the sections below. +If you're preprocessing a C++/CX source code file, or you're using the C++ Modules feature, some more steps are required. For more information, see the sections below. -After you've generated the preprocessed file, it's a good idea to make sure that the problem still repros when you compile the preprocessed file. +After you generate the preprocessed file, it's a good idea to make sure that the problem still repros when you compile the preprocessed file. #### To confirm the preprocessed file still repros the error @@ -298,7 +299,7 @@ If you're using the Modules feature of the C++ compiler, there are some differen 1. In the developer command prompt console window, enter the command **cl /P** *arguments* *modulename.ixx*. The *arguments* are the arguments captured above, and *modulename.ixx* is the name of the file that creates the module interface. -After you've generated the preprocessed files, it's a good idea to make sure the problem still repros when you use the preprocessed file. +After you generate the preprocessed files, it's a good idea to make sure the problem still repros when you use the preprocessed file. #### To confirm the preprocessed file still repros the error @@ -328,7 +329,7 @@ A *link repro* is the linker-generated contents of a directory, specified either 1. To build the repro project in Visual Studio, in the developer command prompt console window, enter the command **devenv**. It ensures that the value of the **link\_repro** environment variable is visible to Visual Studio. To build the project at the command line, use the command-line arguments captured above to duplicate the repro build. -1. Build your repro project, and confirm that the expected problem has occurred. +1. Build your repro project, and confirm that the expected problem occurred. 1. Close Visual Studio, if you used it to do the build. @@ -356,29 +357,32 @@ Create your repro as a minimal IDE project, then package it by compressing the e ## Ways to send your report -You have a couple of good ways to get your report to us. You can use Visual Studio's built-in [Report a Problem Tool](/visualstudio/ide/how-to-report-a-problem-with-visual-studio), or the [Visual Studio Developer Community]( https://aka.ms/feedback/report?space=62) page. There's also a **Product feedback** button at the bottom of this page. The choice depends on whether you want to use the built-in tools in the IDE to capture screenshots and organize your report. If you prefer not to, you can use the Developer Community website directly. +You have a couple of good ways to get your report to us. You can use Visual Studio's built-in [problem reporting tool](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) or the [Visual Studio Developer Community](https://aka.ms/feedback/report?space=62) page. There's also a **Product feedback** button at the bottom of this page. The choice depends on whether you want to use the built-in tools in the IDE to capture screenshots and organize your report. If you prefer not to, you can use the Developer Community website directly. > [!NOTE] > Regardless of how you submit your report, Microsoft respects your privacy. Microsoft is committed to compliance with all data privacy laws and regulations. For information about how we treat the data that you send us, see the [Microsoft Privacy Statement](https://privacy.microsoft.com/privacystatement). ### Use the Report a Problem tool -The **Report a Problem** tool in Visual Studio is a way for Visual Studio users to report problems with just a few clicks. It pops up a simple form to send detailed information about the problem you've found. You can then submit your report without ever leaving the IDE. +The **Report a Problem** tool in Visual Studio is a way for Visual Studio users to report problems with just a few clicks. It pops up a simple form to send detailed information about the problem you found. You can then submit your report without ever leaving the IDE. Reporting your problem through the **Report a Problem** tool is easy and convenient from the IDE. You can access it from the title bar by choosing the **Send Feedback** icon next to the **Quick Launch** search box. Or, you can find it on the menu bar in **Help** > **Send Feedback** > **Report a Problem**. -When you choose to report a problem, first search the Developer Community for similar problems. In case your problem has been reported before, upvote the report and add comments with additional specifics. If you don't see a similar problem, choose the **Report new problem** button at the bottom of the Visual Studio Feedback dialog and follow the steps to report your problem. +When you choose to report a problem, first search the Developer Community for similar problems. In case your problem has been reported before, upvote the report and add comments with more specifics. If you don't see a similar problem, choose the **Report new problem** button at the bottom of the Visual Studio Feedback dialog and follow the steps to report your problem. ### Use the Visual Studio Developer Community pages The Visual Studio Developer Community pages are another convenient way to report problems and find solutions for Visual Studio and the C++ compiler, tools, and libraries. There are specific Developer Community pages for [Visual Studio](https://aka.ms/feedback/report?space=8), [Visual Studio for Mac](https://aka.ms/feedback/report?space=41), [.NET](https://aka.ms/feedback/report?space=61), [C++](https://aka.ms/feedback/report?space=62), [Azure DevOps](https://aka.ms/feedback/report?space=21), and [Azure DevOps Server](https://aka.ms/feedback/report?space=22). -Beneath the community tabs, near the top of each page, is a search box. You can use it to find posts that report problems similar to yours. You may find a solution or other useful information related to your problem is already available. If someone has reported the same problem before, then upvote and comment on that report, rather than create a new problem report. To comment, vote, or report a new problem, you may be asked to sign in to your Visual Studio account. The first time you sign in, you'll have to agree to give the Developer Community app access to your profile. +Beneath the community tabs, near the top of each page, is a search box. You can use it to find posts that report problems similar to yours. You may find a solution or other useful information related to your problem is already available. If someone has reported the same problem before, then upvote and comment on that report, rather than create a new problem report. To comment, vote, or report a new problem, you may be asked to sign in to your Visual Studio account. The first time you sign in, you have to agree to give the Developer Community app access to your profile. + +For issues with the C++ compiler, linker, and other tools and libraries, first search the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) page. If you search for your problem, and it isn't already reported, choose the **Report a problem** button next to the search box. You can include your repro code and command line, screenshots, links to related discussions, and any other information you think is relevant and useful. -For issues with the C++ compiler, linker, and other tools and libraries, first search the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) page. If you search for your problem, and it hasn't been reported before, choose the **Report a problem** button next to the search box. You can include your repro code and command line, screenshots, links to related discussions, and any other information you think is relevant and useful. +> [!TIP] +> Information in the initial Developer Community report will always be public. If this is a concern, see the next section about [Reports and privacy](#reports-and-privacy). > [!TIP] -> For other kinds of problems you might find in Visual Studio that are unrelated to the C++ toolset (For example, UI issues, broken IDE functionality, or general crashes), use the **Report a Problem** tool in the IDE. This is the best choice, due to its screenshot capabilities and its ability to record UI actions that lead to the problem you've found. These kinds of errors can also be looked up on the Visual Studio [Developer Community](https://aka.ms/feedback/report?space=8) site. For more information, see [How to report a problem with Visual Studio](/visualstudio/ide/how-to-report-a-problem-with-visual-studio). +> For other kinds of problems you might find in Visual Studio that are unrelated to the C++ toolset (For example, UI issues, broken IDE functionality, or general crashes), use the **Report a Problem** tool in the IDE. This is the best choice, due to its screenshot capabilities and its ability to record UI actions that lead to the problem you found. These kinds of errors can also be looked up on the Visual Studio [Developer Community](https://aka.ms/feedback/report?space=8) site. For more information, see [How to report a problem with Visual Studio](/visualstudio/ide/how-to-report-a-problem-with-visual-studio). ### Reports and privacy @@ -404,6 +408,6 @@ To maintain your privacy and keep your sensitive information out of public view, ## How to report a C++ documentation issue -We use GitHub issues to track problems reported in our documentation. You can now create GitHub issues directly from a content page, which enables you interact in a much richer way with writers and product teams. If you see an issue with a document, a bad code sample, a confusing explanation, a critical omission, or even just a typo, you can easily let us know. Scroll to the bottom of the page and select **Sign in to give documentation feedback**. You'll need to create a GitHub account if you don't have one already. When you have a GitHub account, you can see all of our documentation issues and their status. You also get notifications when changes are made for the issue you reported. For more information, see [A New Feedback System Is Coming to docs.microsoft.com](/teamblog/a-new-feedback-system-is-coming-to-docs). +We use GitHub issues to track problems reported in our documentation. You can now create GitHub issues directly from a content page, which enables you interact in a richer way with writers and product teams. If you see an issue with a document, a bad code sample, a confusing explanation, a critical omission, or even just a typo, you can easily let us know. Scroll to the bottom of the page and select **Sign in to give documentation feedback**. You need to create a GitHub account if you don't have one already. When you have a GitHub account, you can see all of our documentation issues and their status. You also get notifications when changes are made for the issue you reported. For more information, see our [Feedback System blog entry](/teamblog/a-new-feedback-system-is-coming-to-docs). -You create a documentation issue on GitHub when you use the documentation feedback button. The issue is automatically filled in with some information about the page you created the issue on. That's how we know where the problem is located, so don't edit this information. Just append the details about what's wrong, and if you like, a suggested fix. [Our C++ docs are open source](https://github.com/MicrosoftDocs/cpp-docs/), so if you'd like to submit a fix yourself, you can. For more information about how you can contribute to our documentation, see our [Contributing guide](https://github.com/MicrosoftDocs/cpp-docs/blob/master/CONTRIBUTING.md) on GitHub. +You create a documentation issue on GitHub when you use the documentation feedback button. The issue is automatically filled in with some information about the page you created the issue on. That's how we know where the problem is located, so don't edit this information. Just append the details about what's wrong, and if you like, a suggested fix. [Our C++ docs are open source](https://github.com/MicrosoftDocs/cpp-docs/), so if you'd like to submit a fix yourself, you can. For more information about how you can contribute to our documentation, see our [Contributing guide](https://github.com/MicrosoftDocs/cpp-docs/blob/main/CONTRIBUTING.md) on GitHub. diff --git a/docs/overview/languages-cpp.md b/docs/overview/languages-cpp.md index b02dc239e2..8618404b3e 100644 --- a/docs/overview/languages-cpp.md +++ b/docs/overview/languages-cpp.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: Languages" title: "Languages" -ms.date: "03/29/2019" -helpviewer_keywords: ["C lanugage", "C++ Language", "Assembly Language", "Compiler Intrinsics"] +description: "Learn more about: Languages" +ms.date: 03/29/2019 +helpviewer_keywords: ["C language", "C++ Language", "Assembly Language", "Compiler Intrinsics"] --- # Languages diff --git a/docs/overview/libraries-cpp.md b/docs/overview/libraries-cpp.md index 92e9640c76..9dcb18514d 100644 --- a/docs/overview/libraries-cpp.md +++ b/docs/overview/libraries-cpp.md @@ -5,7 +5,7 @@ ms.date: "11/18/2018" --- # Libraries -Visual Studio includes the following libraries when you install one or more of the C++ workloads. For information about installing 3rd-party libraries, see [vcpkg](https://vcpkg.io/). +Visual Studio includes the following libraries when you install one or more of the C++ workloads. For information about installing 3rd-party libraries, see [vcpkg](/vcpkg/). ## Standard Libraries diff --git a/docs/overview/media/build-insights-filter-by-project.png b/docs/overview/media/build-insights-filter-by-project.png new file mode 100644 index 0000000000..4a2f902081 Binary files /dev/null and b/docs/overview/media/build-insights-filter-by-project.png differ diff --git a/docs/overview/media/build-insights-run-on-selected-files.png b/docs/overview/media/build-insights-run-on-selected-files.png new file mode 100644 index 0000000000..1a5c0f8556 Binary files /dev/null and b/docs/overview/media/build-insights-run-on-selected-files.png differ diff --git a/docs/overview/media/build-insights-view-explanations.png b/docs/overview/media/build-insights-view-explanations.png new file mode 100644 index 0000000000..3b33e677bc Binary files /dev/null and b/docs/overview/media/build-insights-view-explanations.png differ diff --git a/docs/overview/media/cmake-intellisense.png b/docs/overview/media/cmake-intellisense.png new file mode 100644 index 0000000000..7f55a9ca39 Binary files /dev/null and b/docs/overview/media/cmake-intellisense.png differ diff --git a/docs/overview/media/cmake-module-intellisense.png b/docs/overview/media/cmake-module-intellisense.png new file mode 100644 index 0000000000..0d66cfc4df Binary files /dev/null and b/docs/overview/media/cmake-module-intellisense.png differ diff --git a/docs/overview/media/command-line-argument-dropdown.png b/docs/overview/media/command-line-argument-dropdown.png new file mode 100644 index 0000000000..9f38ed0e6f Binary files /dev/null and b/docs/overview/media/command-line-argument-dropdown.png differ diff --git a/docs/overview/media/copilot-fix-my-code-suggestion.png b/docs/overview/media/copilot-fix-my-code-suggestion.png new file mode 100644 index 0000000000..6f9ffb6cbc Binary files /dev/null and b/docs/overview/media/copilot-fix-my-code-suggestion.png differ diff --git a/docs/overview/media/copilot-fix-my-code.png b/docs/overview/media/copilot-fix-my-code.png new file mode 100644 index 0000000000..480b05db75 Binary files /dev/null and b/docs/overview/media/copilot-fix-my-code.png differ diff --git a/docs/overview/media/copilot-rename.png b/docs/overview/media/copilot-rename.png new file mode 100644 index 0000000000..7919d0d70a Binary files /dev/null and b/docs/overview/media/copilot-rename.png differ diff --git a/docs/overview/media/copilot-smart-variable-explanation.png b/docs/overview/media/copilot-smart-variable-explanation.png new file mode 100644 index 0000000000..6d39d04e0d Binary files /dev/null and b/docs/overview/media/copilot-smart-variable-explanation.png differ diff --git a/docs/overview/media/copilot-smart-variable-inspection.png b/docs/overview/media/copilot-smart-variable-inspection.png new file mode 100644 index 0000000000..8680b64068 Binary files /dev/null and b/docs/overview/media/copilot-smart-variable-inspection.png differ diff --git a/docs/overview/media/custom-cmake-option.png b/docs/overview/media/custom-cmake-option.png new file mode 100644 index 0000000000..531ede1c60 Binary files /dev/null and b/docs/overview/media/custom-cmake-option.png differ diff --git a/docs/overview/media/debugger-inline-return-values.png b/docs/overview/media/debugger-inline-return-values.png new file mode 100644 index 0000000000..5a56492bbe Binary files /dev/null and b/docs/overview/media/debugger-inline-return-values.png differ diff --git a/docs/overview/media/github-copilot-install-option-expanded.png b/docs/overview/media/github-copilot-install-option-expanded.png new file mode 100644 index 0000000000..8e0c210239 Binary files /dev/null and b/docs/overview/media/github-copilot-install-option-expanded.png differ diff --git a/docs/overview/media/github-copilot-install-option.png b/docs/overview/media/github-copilot-install-option.png new file mode 100644 index 0000000000..7210c4ce6b Binary files /dev/null and b/docs/overview/media/github-copilot-install-option.png differ diff --git a/docs/overview/media/github-copilot-quick-info.png b/docs/overview/media/github-copilot-quick-info.png new file mode 100644 index 0000000000..c01f573bbb Binary files /dev/null and b/docs/overview/media/github-copilot-quick-info.png differ diff --git a/docs/overview/media/hover-preview.png b/docs/overview/media/hover-preview.png new file mode 100644 index 0000000000..a293f13ab4 Binary files /dev/null and b/docs/overview/media/hover-preview.png differ diff --git a/docs/overview/media/include-diagnostics-improved.png b/docs/overview/media/include-diagnostics-improved.png new file mode 100644 index 0000000000..326070a28e Binary files /dev/null and b/docs/overview/media/include-diagnostics-improved.png differ diff --git a/docs/overview/media/include-diagnostics.png b/docs/overview/media/include-diagnostics.png new file mode 100644 index 0000000000..cfab83b0cf Binary files /dev/null and b/docs/overview/media/include-diagnostics.png differ diff --git a/docs/overview/media/memory-layout-window.png b/docs/overview/media/memory-layout-window.png new file mode 100644 index 0000000000..31e237e4c8 Binary files /dev/null and b/docs/overview/media/memory-layout-window.png differ diff --git a/docs/overview/media/model-picker.png b/docs/overview/media/model-picker.png new file mode 100644 index 0000000000..287be12cea Binary files /dev/null and b/docs/overview/media/model-picker.png differ diff --git a/docs/overview/media/unified-github-copilot-button.png b/docs/overview/media/unified-github-copilot-button.png new file mode 100644 index 0000000000..1d112b98f9 Binary files /dev/null and b/docs/overview/media/unified-github-copilot-button.png differ diff --git a/docs/overview/media/vs2022-copilot-comment-example.png b/docs/overview/media/vs2022-copilot-comment-example.png new file mode 100644 index 0000000000..523959124d Binary files /dev/null and b/docs/overview/media/vs2022-copilot-comment-example.png differ diff --git a/docs/overview/media/vs2022-copilot-edit-session-example.png b/docs/overview/media/vs2022-copilot-edit-session-example.png new file mode 100644 index 0000000000..4d154f0bd0 Binary files /dev/null and b/docs/overview/media/vs2022-copilot-edit-session-example.png differ diff --git a/docs/overview/media/vs2022-copilot-edit-session.png b/docs/overview/media/vs2022-copilot-edit-session.png new file mode 100644 index 0000000000..d4a5e14951 Binary files /dev/null and b/docs/overview/media/vs2022-copilot-edit-session.png differ diff --git a/docs/overview/media/vs2022-copilot-git-changes-review.png b/docs/overview/media/vs2022-copilot-git-changes-review.png new file mode 100644 index 0000000000..b42accbd5f Binary files /dev/null and b/docs/overview/media/vs2022-copilot-git-changes-review.png differ diff --git a/docs/overview/overview-of-cpp-development.md b/docs/overview/overview-of-cpp-development.md index c982da9593..8032f92a34 100644 --- a/docs/overview/overview-of-cpp-development.md +++ b/docs/overview/overview-of-cpp-development.md @@ -3,8 +3,8 @@ title: "Overview of C++ development in Visual Studio" description: "The Visual Studio IDE supports C++ development on Windows, Linux, Android and iOS with a code editor, debugger, test frameworks, static analyzers, and other programming tools." ms.date: "12/02/2019" helpviewer_keywords: ["Visual C++, development tools"] -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" +ms.author: "twhitney" --- # Overview of C++ development in Visual Studio @@ -54,11 +54,11 @@ Source control enables you to coordinate work among multiple developers, isolate ::: moniker-end -For more information about Git integration with repos in Azure, see [Share your code with Visual Studio 2017 and Azure Repos Git](/azure/devops/repos/git/share-your-code-in-git-vs-2017). For information about Git integration with GitHub, see [GitHub Extension for Visual Studio](https://visualstudio.github.com/). +For more information about Git integration with repos in Azure, see [Share your code with Azure Repos and Visual Studio](/azure/devops/repos/git/share-your-code-in-git-vs). For information about Git integration with GitHub, see [Visual Studio and GitHub: Better together](https://visualstudio.github.com/). ## Obtain libraries -Use the [vcpkg](https://vcpkg.io/) package manager to obtain and install third-party libraries. Over 1700 open-source library packages are currently available in the catalog. +Use the [vcpkg](/vcpkg/) package manager to obtain and install third-party libraries. Over 1700 open-source library packages are currently available in the catalog. ## Create user interfaces with designers @@ -66,9 +66,9 @@ If your program has a user interface, you can use a designer to quickly populate ![Screenshot of the Designer and Toolbox windows.](media/vs2017-toolbox-designer.png "Visual Studio 2017 Toolbox and designer") -For more information about designing a user interface for a Universal Windows Platform app, see [Design and UI](https://developer.microsoft.com/windows/design). - -For more information about creating a user interface for an MFC application, see [MFC Desktop Applications](../mfc/mfc-desktop-applications.md). For information about Win32 Windows programs, see [Windows Desktop Applications](../windows/desktop-applications-visual-cpp.md). +- For more information about designing a user interface for a Universal Windows Platform app, see [Design and UI](https://developer.microsoft.com/windows/design). +- For more information about creating a user interface for an MFC application, see [MFC Desktop Applications](../mfc/mfc-desktop-applications.md). +- For information about Win32 Windows programs, see [Windows C++ desktop application types](../windows/overview-of-windows-programming-in-cpp.md). ## Write code diff --git a/docs/overview/supported-platforms-visual-cpp.md b/docs/overview/supported-platforms-visual-cpp.md index 422178f56d..8c6f293023 100644 --- a/docs/overview/supported-platforms-visual-cpp.md +++ b/docs/overview/supported-platforms-visual-cpp.md @@ -2,7 +2,8 @@ description: "Learn more about: Supported Platforms (Visual C++)" title: "Supported Platforms (Visual C++)" ms.date: 11/09/2021 -ms.technology: "cpp-tools" +ms.service: "visual-cpp" +ms.subservice: "tools" helpviewer_keywords: ["Visual C++, platforms supported", "platforms [C++]"] --- # Supported platforms (Visual C++) diff --git a/docs/overview/toc.yml b/docs/overview/toc.yml index 6835b304bd..66d418921e 100644 --- a/docs/overview/toc.yml +++ b/docs/overview/toc.yml @@ -2,7 +2,7 @@ items: - name: Microsoft C/C++ in Visual Studio expanded: false items: - - name: C++ in Visual Studio + - name: C and C++ in Visual Studio href: ../overview/visual-cpp-in-visual-studio.md - name: Overview of C++ development in Visual Studio href: ../overview/overview-of-cpp-development.md @@ -12,8 +12,6 @@ items: href: ../overview/what-s-new-for-cpp-2019.md - name: What's new for C++ in Visual Studio 2017 href: ../overview/what-s-new-for-cpp-2017.md - - name: What's new for Microsoft C++ docs - href: ../overview/whats-new-cpp-docs.md - name: C++ conformance improvements in Visual Studio 2022 href: ../overview/cpp-conformance-improvements.md - name: C++ conformance improvements in Visual Studio 2019 @@ -24,6 +22,8 @@ items: href: ../overview/visual-cpp-language-conformance.md - name: Supported target platforms href: ../overview/supported-platforms-visual-cpp.md + - name: Microsoft C++ compiler versions + href: compiler-versions.md - name: C++ Tools and Features in Visual Studio Editions href: ../overview/visual-cpp-tools-and-features-in-visual-studio-editions.md - name: Install C11 and C17 support in Visual Studio diff --git a/docs/overview/visual-cpp-help-and-community.md b/docs/overview/visual-cpp-help-and-community.md index d644ef5dc4..3cd59d14be 100644 --- a/docs/overview/visual-cpp-help-and-community.md +++ b/docs/overview/visual-cpp-help-and-community.md @@ -1,9 +1,9 @@ --- title: "Microsoft C/C++ help and community" -description: "This article lists various additional resources for help and information on Visual Studio and the Microsoft C/C++ compiler and tools." -ms.date: 11/05/2020 -ms.technology: "cpp-ide" -ms.assetid: 6bc23c18-fcd9-47bc-bff2-17537700be4a +description: "This article lists various resources for help and information on Visual Studio and the Microsoft C/C++ compiler and tools." +ms.date: 03/03/2022 +ms.service: "visual-cpp" +ms.subservice: "ide" --- # Microsoft C/C++ help and community @@ -23,18 +23,18 @@ Here's where to get help and information about how to write C++ code and use the You can view Microsoft developer content online. This content is updated regularly. -You can also download and view the content locally in the offline Help Viewer. The offline documentation is organized by books of related content, which are also updated periodically. You can download the books you are interested in as they become available. For more information, see [Microsoft Help Viewer](/visualstudio/ide/microsoft-help-viewer). +You can also download and view the content locally in the offline Help Viewer. The offline documentation is organized by books of related content, which are also updated periodically. You can download the books you're interested in as they become available. For more information, see [Microsoft Help Viewer](/visualstudio/ide/microsoft-help-viewer). -Many sections of the documentation are also available in PDF form. These sections have a **Download PDF** link below the table of contents on docs.microsoft.com. +Many sections of the documentation are also available in PDF form. These sections have a **Download PDF** link below the table of contents on Microsoft Learn. ## Related sites - [C++ Team Blog](https://devblogs.microsoft.com/cppblog/): Contains posts on various subjects by the experts on Microsoft's C++ product team. -- [Channel 9](https://channel9.msdn.com/): Contains video interviews and lectures. Use the search box on the Channel 9 home page to find C++ content. +- [Shows](/shows): Contains video interviews and lectures. Select `Browse all shows` on the Shows home page to find C++ content. -- [Visual Studio website](https://visualstudio.microsoft.com/): Contains articles and news about Visual Studio and related development tools. This site also hosts Visual Studio downloads and redistributable files. +- [Visual Studio website](https://visualstudio.microsoft.com/): Contains articles and news about Visual Studio and related development tools. This site also hosts Visual Studio downloads and Redistributable files. -- [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html): Official Microsoft forums where you can post questions about C++ and Visual Studio and get answers from Microsoft and from experts in the community. +- [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html): Official Microsoft forums where you can post questions about C++ and Visual Studio and get answers from Microsoft and from experts in the community. - [Visual Studio C++ Developer Community](https://aka.ms/vsfeedback/browsecpp): Forums for reporting problems in the C++ compiler and tools or the IDE, or for making product suggestions. You can vote for your favorite ideas or bug reports, or add a new one. This site is monitored by the development team. diff --git a/docs/overview/visual-cpp-in-visual-studio.md b/docs/overview/visual-cpp-in-visual-studio.md index 2c58a4d817..30012947ca 100644 --- a/docs/overview/visual-cpp-in-visual-studio.md +++ b/docs/overview/visual-cpp-in-visual-studio.md @@ -1,8 +1,9 @@ --- title: "C and C++ in Visual Studio" -description: "Learn how to use the Microsoft C/C++ compiler, code editor, and related tools in Visual Studio to develop programs for Windows, Linux, Android and iOS." -ms.date: 09/20/2021 -ms.technology: "cpp-ide" +description: "Learn how to use the Microsoft C/C++ compiler and related tools to develop C++ and assembly programs for Windows, Linux, Android, and iOS." +ms.date: 09/29/2022 +ms.service: "visual-cpp" +ms.subservice: "ide" helpviewer_keywords: ["Visual C++, home page"] --- # C and C++ in Visual Studio @@ -43,14 +44,20 @@ helpviewer_keywords: ["Visual C++, home page"] :::moniker-end -Microsoft Visual C++ (MSVC) refers to the C++, C, and assembly language development tools and libraries available as part of Visual Studio on Windows. These tools and libraries let you create Universal Windows Platform (UWP) apps, native Windows desktop and server applications, cross-platform libraries and apps that run on Windows, Linux, Android, and iOS, as well as managed apps and libraries that use the .NET Framework. You can use MSVC to write anything from simple console apps to the most sophisticated and complex apps for Windows desktop, from device drivers and operating system components to cross-platform games for mobile devices, and from the smallest IoT devices to multi-server high performance computing in the Azure cloud. +Microsoft Visual C++ (MSVC) refers to the C++, C, and assembly language development tools and libraries available as part of Visual Studio on Windows. These tools and libraries let you create native Windows desktop and server applications, Universal Windows Platform (UWP) apps, or managed apps and libraries that use the .NET Framework. Create cross-platform libraries and apps that run on Windows, Linux, Android, and iOS. You can use MSVC to write anything from simple console apps to the most sophisticated and complex apps for Windows desktop. Write device drivers and operating system components or cross-platform games for mobile devices. Target anything from the smallest IoT devices to multi-server high performance computing in the Azure cloud. -Visual Studio 2015, 2017 and 2019 can be installed side-by-side. You can use Visual Studio 2019 (compiler toolset v142) or Visual Studio 2017 (v141) to edit and build programs using the toolset from Visual Studio 2017 (v141) and Visual Studio 2015 (v140). +Visual Studio 2015, 2017, 2019, and 2022 can be installed side-by-side. You can use Visual Studio 2019 (compiler toolset v142) or Visual Studio 2017 (v141) to edit and build programs using the toolset from Visual Studio 2017 (v141) and Visual Studio 2015 (v140). -## What's New and Conformance History +## What's new for C++ in Visual Studio -[What's New for C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md)\ -Find out what's new in Visual Studio. +[What's New for C++ in Visual Studio 2022](what-s-new-for-visual-cpp-in-visual-studio.md)\ +Find out what's new in Visual Studio 2022. + +[What's New for C++ in Visual Studio 2019](./what-s-new-for-cpp-2019.md)\ +Find out what's new in Visual Studio 2019. + +[What's New for C++ in Visual Studio 2017](./what-s-new-for-cpp-2017.md)\ +Find out what's new in Visual Studio 2017. [What's New for C++ in Visual Studio 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md)\ Find out what was new in C++ for each version of Visual Studio from 2003 through 2015. @@ -64,13 +71,13 @@ Find feature-level language conformance status in the MSVC compiler by Visual St [Microsoft C/C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md)\ Learn about the breaking changes in previous versions. -## Install Visual Studio and upgrade from earlier versions +## Install Visual Studio C++ and upgrade from earlier versions [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md)\ Download Visual Studio and install the Microsoft C/C++ toolset. [Microsoft C++ porting and upgrading guide](../porting/visual-cpp-porting-and-upgrading-guide.md)\ -Guidance for porting code and upgrading projects to Visual Studio 2015 or later to take advantage of greater compiler conformance to the C++ standard as well as greatly improved compilation times and security features such as Spectre mitigation. +Guidance for porting code and upgrading projects to Visual Studio 2015 or later. Take advantage of greater compiler conformance to the C++ standard, greatly improved compilation times, and security features such as Spectre mitigation. [C++ tools and features in Visual Studio editions](visual-cpp-tools-and-features-in-visual-studio-editions.md)\ Find out about different Visual Studio editions. @@ -78,7 +85,7 @@ Find out about different Visual Studio editions. [Supported platforms](supported-platforms-visual-cpp.md)\ Find out which platforms the Microsoft C/C++ compiler supports. -## Learn C++ +## Learn C++ using Visual Studio [Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)\ Learn more about modern C++ programming techniques based on C++11 and later that enable you to write fast, safe code and avoid many of the pitfalls of C-style programming. @@ -92,7 +99,7 @@ Start learning how to write C++ in Visual Studio. [Visual Studio C++ samples](visual-cpp-samples.md)\ Information about the C++ code samples provided by Microsoft. -## C++ development tools +## Visual Studio C/C++ development tools [Overview of C++ development in Visual Studio](overview-of-cpp-development.md)\ How to use the Visual Studio IDE to create projects, edit code, link to libraries, compile, debug, create unit tests, do static analysis, deploy, and more. @@ -112,22 +119,22 @@ Use SAL annotations or the C++ Core Guidelines checkers to perform static analys [Write unit tests for C/C++ in Visual Studio](/visualstudio/test/writing-unit-tests-for-c-cpp)\ Create unit tests using the Microsoft Unit Testing Framework for C++, Google Test, Boost.Test, or CTest. -## Write applications in C++ +## Write C/C++ applications using Visual Studio -[Universal Windows Apps (C++)](../cppcx/universal-windows-apps-cpp.md)\ -Find guides and reference content on the Windows Developer Center. For information about developing UWP apps, see [Intro to the Universal Windows Platform](/windows/uwp/get-started/universal-application-platform-guide) and [Create your first UWP app using C++](/windows/uwp/get-started/create-a-basic-windows-10-app-in-cpp). - -[Desktop applications (C++)](../windows/desktop-applications-visual-cpp.md)\ +[Windows C++ desktop application types](../windows/overview-of-windows-programming-in-cpp.md)\ Learn how to create traditional native C++ desktop applications for Windows. [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md)\ Learn how to create DLLs that enable interoperability between native C++ and .NET programs written in languages such as C# or Visual Basic. +[Universal Windows Apps (C++)](../cppcx/universal-windows-apps-cpp.md)\ +Find guides and reference content on the Windows Developer Center. For information about developing UWP apps, see [Intro to the Universal Windows Platform](/windows/uwp/get-started/universal-application-platform-guide) and [Create your first UWP app using C++](/windows/uwp/get-started/create-a-basic-windows-10-app-in-cpp). + [Linux programming](../linux/index.yml)\ Use the Visual Studio IDE to code and deploy to a remote Linux machine for compilation with GCC. [Create C/C++ DLLs in Visual Studio](../build/dlls-in-visual-cpp.md)\ -Find out how to use Win32, ATL, and MFC to create Windows desktop DLLs, and provides information about how to compile and register your DLL. +Find out how to use Win32, ATL, and MFC to create Windows desktop DLLs. Provides information about how to compile and register your DLL. [Parallel programming](../parallel/parallel-programming-in-visual-cpp.md)\ Learn how to use the Parallel Patterns Library, C++ AMP, OpenMP, and other features that are related to multithreading on Windows. @@ -144,21 +151,27 @@ Connect to databases using ODBC and OLE DB. [Text and strings](../text/text-and-strings-in-visual-cpp.md)\ Learn about working with different text and string formats and encodings for local and international development. -## Languages reference +## C/C++ language reference [C++ language reference](../cpp/cpp-language-reference.md)\ The reference guide to the Microsoft implementation of the C++ programming language. +[C language reference](../c-language/c-language-reference.md)\ +The reference guide to the Microsoft implementation of the C programming language. + [C/C++ preprocessor reference](../preprocessor/c-cpp-preprocessor-reference.md)\ A common reference to the shared C and C++ language preprocessor. -[C language reference](../c-language/c-language-reference.md)\ -The reference guide to the Microsoft implementation of the C programming language. +[C++/CX language reference](../cppcx/visual-c-language-reference-c-cx.md)\ +The reference guide to the Microsoft extensions to the C++ language for creating C++ Universal Windows Platform apps, C++ Windows runtime components that can be consumed by JavaScript-based Windows apps, and Windows DirectX games and graphics-intensive apps. + +[C++/CLI language reference](https://www.ecma-international.org/wp-content/uploads/ECMA-372_1st_edition_december_2005.pdf)\ +The ECMA standard for the C++/CLI programming language. [Compiler intrinsics and assembly language](../intrinsics/compiler-intrinsics-and-assembly-language.md)\ Guides to the compiler intrinsics supported or implemented by the Microsoft C/C++ compilers on each platform. -## C++ Libraries in Visual Studio +## C/C++ libraries available in Visual Studio The following sections provide information about the different C and C++ libraries that are included in Visual Studio. @@ -186,14 +199,14 @@ Universal Windows Platform (UWP) apps and components. [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md)\ Programming for the common language runtime (CLR). -## Third-party open source C++ libraries +## Third-party open source C++ libraries in Visual Studio -The cross-platform **vcpkg** command-line tool greatly simplifies the discovery and installation of over 900 C++ open source libraries. For more information, see [vcpkg](https://vcpkg.io/). +The cross-platform **vcpkg** command-line tool greatly simplifies the discovery and installation of over 900 C++ open source libraries. For more information, see [vcpkg](/vcpkg/). -## Feedback and community +## Visual Studio C++ feedback and community -[Microsoft Docs Q&A](/answers/topics/c%2B%2B.html)\ -Microsoft Docs hosts searchable forums for questions and answers. Add a `C++` tag to your post for community assistance on C++-related issues. +[Microsoft Learn Q&A](/answers/topics/c%2B%2B.html)\ +Microsoft Learn hosts searchable forums for questions and answers. Add a `C++` tag to your post for community assistance on C++-related issues. [How to report a problem with the Microsoft C/C++ toolset](how-to-report-a-problem-with-the-visual-cpp-toolset.md)\ Learn how to create effective error reports against the Microsoft C/C++ toolset (compiler, linker, and other tools), and ways to submit your report. diff --git a/docs/overview/visual-cpp-language-conformance.md b/docs/overview/visual-cpp-language-conformance.md index 153c1c2c6c..f24433753c 100644 --- a/docs/overview/visual-cpp-language-conformance.md +++ b/docs/overview/visual-cpp-language-conformance.md @@ -1,12 +1,13 @@ --- title: "Microsoft C/C++ language conformance" description: "Microsoft C and C++ conformance updates by Visual Studio version." -ms.date: 11/08/2021 -ms.technology: "cpp-language" +ms.date: 03/01/2023 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # Microsoft C/C++ language conformance by Visual Studio version -Standards conformance for the Microsoft C/C++ compiler in Visual Studio (MSVC) is a work in progress. Here's a summary of our ISO Standard C and C++ language and library conformance by Visual Studio version. Each C++ compiler and standard library feature name links to the ISO Standard C++ proposal paper that describes the feature, if one is available at publication time. The **Supported** column lists the Visual Studio version in which support for the feature first appeared. +Standards conformance for the Microsoft C/C++ compiler in Visual Studio (MSVC) is a work in progress. Here's a summary of ISO Standard C and C++ language and library conformance by Visual Studio version. Each C++ compiler and standard library feature name has a link to the ISO Standard C++ proposal paper that describes the feature, when one is available at publication time. The **Supported** column lists the Visual Studio version in which support for the feature first appeared. For details on conformance improvements, see [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md). For a list of other changes, see [What's New for Visual C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md). For conformance changes in earlier versions, see [Visual C++ change history](../porting/visual-cpp-change-history-2003-2015.md) and [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For current news from the C++ team, visit the [C++ team blog](https://devblogs.microsoft.com/cppblog/). @@ -17,12 +18,13 @@ For details on conformance improvements, see [C++ conformance improvements in Vi | Feature | Supported | |--|--| -| __C++03/11 Core language features__ | __Supported__ | +| **C++03/11 Core language features** | **Supported** | |  Everything else | VS 2015 [A](#note_A) | |  Two-phase name lookup | VS 2017 15.7 [B](#note_B) | |  [`N2634 Expression SFINAE`](https://wg21.link/N2634) | VS 2017 15.7 | |  [`N1653 C99 preprocessor`](https://wg21.link/N1653) | VS 2019 16.6 [C](#note_C) | -| __C++14 Core language features__ | __Supported__ | +| **C++03/11 Core language features (Defect reports)** | **Supported** | +| **C++14 Core language features** | **Supported** | |  [`N3323 Tweaked wording for contextual conversions`](https://wg21.link/N3323) | VS 2013 | |  [`N3472 Binary literals`](https://wg21.link/N3472) | VS 2015 | |  [`N3638 auto and decltype(auto) return types`](https://wg21.link/n3638) | VS 2015 | @@ -34,7 +36,7 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`N3651 Variable templates`](https://wg21.link/n3651) | VS 2015 Update 2 | |  [`N3652 Extended constexpr`](https://wg21.link/n3652) | VS 2017 15.0 | |  [`N3653 Default member initializers for aggregates`](https://wg21.link/n3653) | VS 2017 15.0 | -| __C++17 Core language features__ | __Supported__ | +| **C++17 Core language features** | **Supported** | |  [`N4086 Removing trigraphs`](https://wg21.link/n4086) | VS 2010 [14](#note_14) | |  [`N3922 New rules for auto with braced-init-lists`](https://wg21.link/n3922) | VS 2015 [14](#note_14) | |  [`N4051 typename in template template-parameters`](https://wg21.link/n4051) | VS 2015 [14](#note_14) | @@ -76,7 +78,7 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`P0145R3 Refining expression evaluation order`](https://wg21.link/p0145r3)
 [`P0400R0 Order of evaluation of function arguments`](https://wg21.link/p0400r0) | VS 2017 15.7 [17](#note_17) | |  [`P0195R2 Pack expansions in using-declarations`](https://wg21.link/p0195r2) | VS 2017 15.7 [17](#note_17) | |  [`P0283R2 Ignoring unrecognized attributes`](https://wg21.link/p0283r2) | VS 2015 [14](#note_14) | -| __C++17 Core language features (Defect reports)__ | __Supported__ | +| **C++17 Core language features (Defect reports)** | **Supported** | |  [`P0702R1 Fixing class template argument deduction for initializer-list ctors`](https://wg21.link/p0702r1) | VS 2017 15.7 [17](#note_17) | |  [`P0961R1 Relaxing the structured bindings customization point finding rules`](https://wg21.link/p0961r1) | VS 2019 16.0 [17](#note_17) | |  [`P0969R0 Allowing structured bindings to accessible members`](https://wg21.link/p0969r0) | VS 2019 16.0 [17](#note_17) | @@ -85,10 +87,10 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`P1825R0 Merged wording for P0527R1 and P1155R3, more implicit moves`](https://wg21.link/p1825r0) | VS 2019 16.4 [17](#note_17) | |  [`P0929R2 Checking for abstract class types`](https://wg21.link/P0929R2) | VS 2019 16.5 [17](#note_17) | |  [`P0962R1 Relaxing the range-for loop customization point finding rules`](https://wg21.link/p0962r1) | VS 2019 16.5 [17](#note_17) | -|  [`P0859R0 CWG 1581: When are constexpr member functions defined`](https://wg21.link/p0859r0) | Partial in VS 2019 16.7 [E](#note_E) | +|  [`P0859R0 CWG 1581: When are constexpr member functions defined`](https://wg21.link/p0859r0) | Partial in VS 2019 16.7 [E](#note_E), Full in VS 2022 17.1 | |  [`P1009R2 Array size deduction in new-expressions`](https://wg21.link/P1009R2) | VS 2019 16.7 [17](#note_17) | |  [`P1286R2 Contra CWG DR1778`](https://wg21.link/P1286R2) | VS 2019 16.8 [17](#note_17) | -| __C++20 Core language features__ | __Supported__ | +| **C++20 Core language features** | **Supported** | |  [`P0641R2 const mismatch with defaulted copy constructor`](https://wg21.link/P0641R2) | VS 2015 [14](#note_14) | |  [`P0704R1 Fixing const lvalue ref-qualified pointers to members`](https://wg21.link/p0704r1) | VS 2015 [14](#note_14) | |  [`P1041R4 Make char16_t/char32_t string literals be UTF-16/32`](https://wg21.link/P1041R4) | VS 2015 [14](#note_14) | @@ -114,7 +116,7 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`P1099R5 Using enum`](https://wg21.link/P1099R5) | VS 2019 16.4 [20](#note_20) | |  [`P1186R3 When do you actually use <=>`](https://wg21.link/P1186R3) | VS 2019 16.4 [20](#note_20) | |  [`P1630R1 Spaceship needs a tune-up`](https://wg21.link/P1630R1) | VS 2019 16.4 [20](#note_20) | -|  [`P0306R4 Adding __VA_OPT__ for comma omission and comma deletion`](https://wg21.link/P0306R4) | VS 2019 16.5 [20](#note_20) | +|  [`P0306R4 Adding __VA_OPT__ for comma omission and comma deletion`](https://wg21.link/P0306R4) | VS 2019 16.5. To provide better backward compatibility, `__VA_OPT__` is enabled under `/Zc:preprocessor` across all language versions. | |  [`P0614R1 Range-based for-loops with initializers`](https://wg21.link/P0614R1) | VS 2019 16.5 [20](#note_20) | |  [`P0683R1 Default member initializers for bit-fields`](https://wg21.link/P0683R1) | VS 2019 16.5 [20](#note_20) | |  [`P1002R1 try-catch blocks in constexpr functions`](https://wg21.link/P1002R1) | VS 2019 16.5 [20](#note_20) | @@ -174,6 +176,50 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`P1353R0 Missing feature-test macros`](https://wg21.link/P1353R0) | VS 2019 16.10 [20](#note_20) | |  [`P0735R1 Interaction of memory_order_consume with release sequences`](https://wg21.link/P0735R1) | N/A | |  [`P1236R1 Signed integers are two's complement`](https://wg21.link/P1236R1) | N/A | +| **C++23 Core language features** | **Supported** | +|  [`P0330R8 Literal Suffix for (signed) size_t`](https://wg21.link/p0330r8) | no | +|  [`P0847R7 Deducing this`](https://wg21.link/p0847r7) | no | +|  [`P0849R8 auto(x): decay-copy in the language`](https://wg21.link/p0849r8) | no | +|  [`P1102R2 Down with ()!`](https://wg21.link/p1102r2) | no | +|  [`P1169R4 static operator()`](https://wg21.link/p1169r4) | no | +|  [`P1401R5 Narrowing contextual conversions to bool`](https://wg21.link/p1401r5) | no | +|  [`P1467R9 Extended floating-point types and standard names`](https://wg21.link/p1467r9) | no | +|  [`P1774R8 Portable assumptions`](https://wg21.link/p1774r8) | no | +|  [`P1787R6 Declarations and where to find them`](https://wg21.link/p1787r6) | no | +|  [`P1847R4 Make declaration order layout mandated`](https://wg21.link/p1847r4) | VS 2022 17.0 [23](#note_23) | +|  [`P1938R3 if consteval`](https://wg21.link/p1938r3) | no | +|  [`P1949R7 C++ Identifier Syntax using Unicode Standard Annex 31`](https://wg21.link/p1949r7) | no | +|  [`P2029R4 Proposed resolution for core issues 411, 1656, and 2333; numeric and universal character escapes in character and string literals`](https://wg21.link/p2029r4) | no | +|  [`P2036R3 Change scope of lambda trailing-return-type`](https://wg21.link/p2036r3) | no | +|  [`P2071R2 Named universal character escapes`](https://wg21.link/p2071r2) | no | +|  [`P2128R6 Multidimensional subscript operator`](https://wg21.link/p2128r6) | no | +|  [`P2156R1 Allow Duplicate Attributes`](https://wg21.link/p2156r1) | no | +|  [`P2173R1 Attributes on Lambda-Expressions`](https://wg21.link/p2173r1) | no | +|  [`P2186R2 Remove Garbage Collection Support`](https://wg21.link/p2186r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2201R1 Mixed string literal concatenation`](https://wg21.link/p2201r1) | no | +|  [`P2223R2 Trimming whitespaces before line splicing`](https://wg21.link/p2223r2) | no | +|  [`P2242R3 Non-literal variables (and labels and gotos) in constexpr functions`](https://wg21.link/p2242r3) | no | +|  [`P2246R1 Character encoding of diagnostic text`](https://wg21.link/p2246r1) | VS 2022 17.0 [23](#note_23) | +|  [`P2266R3 Simpler implicit move`](https://wg21.link/p2266r3) | no | +|  [`P2280R4 Using unknown pointers and references in constant expressions`](https://wg21.link/p2280r4) | no | +|  [`P2290R3 Delimited escape sequences`](https://wg21.link/p2290r3) | no | +|  [`P2295R6 Support for UTF-8 as a portable source file encoding`](https://wg21.link/p2295r6) | no | +|  [`P2314R4 Character sets and encodings`](https://wg21.link/p2314r4) | no | +|  [`P2316R2 Consistent character literal encoding`](https://wg21.link/p2316r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2324R2 Labels at the end of compound statements (C compatibility)`](https://wg21.link/p2324r2) | no | +|  [`P2327R1 De-deprecating volatile compound operations`](https://wg21.link/p2327r1) | no | +|  [`P2334R1 preprocessing directives elifdef and elifndef`](https://wg21.link/p2334r1) | no | +|  [`P2360R0 Extend init-statement to allow alias-declaration`](https://wg21.link/p2360r0) | no | +|  [`P2362R3 Remove non-encodable wide character literals and multicharacter wide character literals`](https://wg21.link/p2362r3) | no | +|  [`P2437R1 Support for #warning`](https://wg21.link/p2437r1) | no | +|  [`P2448R2 Relaxing some constexpr restrictions`](https://wg21.link/p2448r2) | no | +|  [`P2460R2 Relax requirements on wchar_t to match existing practices`](https://wg21.link/p2460r2) | no | +|  [`P2468R2 The Equality Operator You Are Looking For`](https://wg21.link/p2468r2) | no | +|  [`P2493R0 Missing feature test macros for C++20 core papers`](https://wg21.link/p2493r0) | no | +|  [`P2493R0 Missing feature test macros for C++20 core papers`](https://wg21.link/p2493r0) | no | +|  [`P2513R4 char8_t Compatibility and Portability Fix`](https://wg21.link/p2513r4) | VS 2022 17.4 [DR](#note_DR) | +|  [`P2579R0 Mitigation strategies for P2036 ”Changing scope for lambda trailing-return-type”`](https://wg21.link/p2579r0) | no | +|  [`P2582R1 Wording for class template argument deduction from inherited constructors`](https://wg21.link/p2582r1) | no | ## C++ Standard library features @@ -181,7 +227,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve | Feature | Supported | |--|--| -| __C++14 Standard library features__ | __Supported__ | +| **C++14 Standard library features** | **Supported** | |  [`N3462 SFINAE-Friendly result_of`](https://wg21.link/n3462) | VS 2015.2 | |  [`N3302 constexpr For `](https://wg21.link/n3302) | VS 2015 | |  [`N3469 constexpr For `](https://wg21.link/n3469) | VS 2015 | @@ -207,7 +253,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`N3421 Transparent Operator Functors (less<>, etc.)`](https://wg21.link/n3421) | VS 2013 | |  [`N3655 Alias Templates For (decay_t, etc.)`](https://wg21.link/n3655) | VS 2013 | |  [`N3656 make_unique()`](https://wg21.link/n3656) | VS 2013 | -| __C++17 Standard library features__ | __Supported__ | +| **C++17 Standard library features** | **Supported** | |  [`N3911 void_t`](https://wg21.link/n3911) | VS 2015 [14](#note_14) | |  [`N4089 Safe Conversions In unique_ptr`](https://wg21.link/n4089) | VS 2015 [14](#note_14) | |  [`N4169 invoke()`](https://wg21.link/n4169) | VS 2015 [14](#note_14) | @@ -288,13 +334,13 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P0604R0 Changing is_callable/result_of To invoke_result, is_invocable, is_nothrow_invocable`](https://wg21.link/p0604r0) | VS 2017 15.3 [17](#note_17) | |  [`P0607R0 Inline Variables for the Standard Library`](https://wg21.link/p0607r0) | VS 2017 15.5 [17](#note_17) | |  [`P0618R0 Deprecating `](https://wg21.link/p0618r0) | VS 2017 15.5 [17](#note_17) | +| **C++17 Standard library features (Defect reports)** | **Supported** | |  [`P0682R1 Repairing Elementary String Conversions`](https://wg21.link/P0682R1) | VS 2015 15.7 [17](#note_17) | -|  [`P2162R2 Inheriting from std::variant`](https://wg21.link/P2162R2) | VS 2022 17.0 [17](#note_17) | -| __C++20 Standard library features__ | __Supported__ | +|  [`P1164R1 Making create_directory() Intuitive`](https://wg21.link/P1164R1) | VS 2019 16.0 [14](#note_14) | +| **C++20 Standard library features** | **Supported** | |  [`P0809R0 Comparing Unordered Containers`](https://wg21.link/p0809r0) | VS 2010 [14](#note_14) | |  [`P0858R0 Constexpr Iterator Requirements`](https://wg21.link/p0858r0) | VS 2017 15.3 [17](#note_17) | |  [`P0777R1 Avoiding Unnecessary Decay`](https://wg21.link/p0777r1) | VS 2017 15.7 [14](#note_14) | -|  [`P1164R1 Making create_directory() Intuitive`](https://wg21.link/P1164R1) | VS 2019 16.0 [20](#note_20) | |  [`P0550R2 remove_cvref`](https://wg21.link/p0550r2) | VS 2019 16.0 [20](#note_20) | |  [`P0318R1 unwrap_reference, unwrap_ref_decay`](https://wg21.link/p0318r1) | VS 2019 16.1 [20](#note_20) | |  [`P0457R2 starts_with()/ends_with() For basic_string/basic_string_view`](https://wg21.link/p0457r2) | VS 2019 16.1 [20](#note_20) | @@ -319,7 +365,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P0340R3 SFINAE-Friendly underlying_type`](https://wg21.link/P0340R3) | VS 2019 16.5 [14](#note_14) | |  [`P0356R5 bind_front()`](https://wg21.link/P0356R5) | VS 2019 16.5 [20](#note_20) | |  [`P0439R0 enum class memory_order`](https://wg21.link/p0439r0) | VS 2019 16.5 [20](#note_20) | -|  [`P0553R4 Rotating And Counting Functions`](https://wg21.link/P0553R4) | VS 2019 16.5 [20](#note_20) | +|  [`P0553R4 Rotating And Counting Functions`](https://wg21.link/P0553R4) | VS 2019 16.5 [20](#note_20) | |  [`P0556R3 ispow2(), ceil2(), floor2(), log2p1()`](https://wg21.link/P0556R3) | VS 2019 16.5 [20](#note_20) | |  [`P0595R2 is_constant_evaluated()`](https://wg21.link/P0595R2) | VS 2019 16.5 [20](#note_20) | |  [`P0631R8 Math Constants`](https://wg21.link/P0631R8) | VS 2019 16.5 [20](#note_20) | @@ -331,9 +377,9 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P1227R2 Signed std::ssize(), Unsigned span::size()`](https://wg21.link/P1227R2) | VS 2019 16.5 [20](#note_20) | |  [`P1355R2 Narrow Contract For ceil2()`](https://wg21.link/P1355R2) | VS 2019 16.5 [20](#note_20) | |  [`P1357R1 is_bounded_array, is_unbounded_array`](https://wg21.link/P1357R1) | VS 2019 16.5 [20](#note_20) | -|  [`P1612R1 Relocating endian To `](https://wg21.link/P1612R1) | VS 2019 16.5 [20](#note_20) | -|  [`P1651R0 bind_front() Should Not Unwrap reference_wrapper`](https://wg21.link/P1651R0) | VS 2019 16.5 [20](#note_20) | -|  [`P1690R1 Refining Heterogeneous Lookup For Unordered Containers`](https://wg21.link/P1690R1) | VS 2019 16.5 [20](#note_20) | +|  [`P1612R1 Relocating endian To `](https://wg21.link/P1612R1) | VS 2019 16.5 [20](#note_20) | +|  [`P1651R0 bind_front() Should Not Unwrap reference_wrapper`](https://wg21.link/P1651R0) | VS 2019 16.5 [20](#note_20) | +|  [`P1690R1 Refining Heterogeneous Lookup For Unordered Containers`](https://wg21.link/P1690R1) | VS 2019 16.5 [20](#note_20) | |  [`P1902R1 Missing Feature-Test Macros 2017-2019`](https://wg21.link/P1902R1) | VS 2019 16.5 [14](#note_14) | |  [`P0122R7 `](https://wg21.link/p0122r7)
 [`P1024R3 Enhancing span usability`](https://wg21.link/p1024r3)
 [`P1085R2 Removing span comparisons`](https://wg21.link/p1085r2)
 [`P1394R4 Range constructor for span`](https://wg21.link/p1394r4)
 [`P1872R0 span should have size_type, not index_type`](https://wg21.link/p1872r0) | VS 2019 16.6 [20](#note_20) | |  [`P0202R3 constexpr for and exchange()`](https://wg21.link/p0202r3) | VS 2019 16.6 [20](#note_20) | @@ -394,23 +440,68 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P1502R1 Standard Library Header Units`](https://wg21.link/P1502R1) | VS 2019 16.10 [20](#note_20) | |  [`P1614R2 Adding Spaceship <=> To The Library`](https://wg21.link/P1614R2) | VS 2019 16.10 [20](#note_20) | |  [`P1285R0 Improving Completeness Requirements For Type Traits`](https://wg21.link/P1285R0) | N/A | -| __C++20 Standard library features (Defect reports)__ | __Supported__ | +| **C++20 Standard library features (Defect reports)** | **Supported** | |  [`P2325R3 Views Should Not Be Required To Be Default Constructible`](https://wg21.link/P2325r3) | VS 2022 17.0 [20abi](#note_20abi) | |  [`P2328R1 join_view should join all views of ranges`](https://wg21.link/P2328R1) | VS 2022 17.0 [20abi](#note_20abi) | |  [`P2367R0 Remove misuses of list-initialization from clause 24 ranges`](https://wg21.link/P2367R0) | VS 2022 17.0 [20abi](#note_20abi) | -| __C++23 Standard library features__ | __Supported__ | -|  [`P0401R6 Providing size feedback in the allocator interface`](https://wg21.link/P0401R6) | VS 2022 17.0 [23](#note_23) | -|  [`P0881R7 `](https://wg21.link/p0881r7) | No | -|  [`P0943R6 Supporting C Atomics In C++`](https://wg21.link/P0943R6) | VS 2022 17.0 [T](#note_T) | -|  [`P1048R1 is_scoped_enum`](https://wg21.link/P1048R1) | VS 2022 17.0 [23](#note_23) | -|  [`P1132R7 out_ptr(), inout_ptr()`](https://wg21.link/P1132R7) | VS 2022 17.0 [23](#note_23) | -|  [`P1679R3 contains() for basic_string/basic_string_view`](https://wg21.link/P1679R3) | VS 2022 17.0 [23](#note_23) | -|  [`P1682R3 to_underlying() for enumerations`](https://wg21.link/P1682R3) | VS 2022 17.0 [23](#note_23) | -|  [`P1951R1 Default template arguments for pair's forwarding constructor`](https://wg21.link/P1951R1) | VS 2022 17.0 [23](#note_23) | -|  [`P1989R2 Range Constructor For string_view`](https://wg21.link/P1989R2) | VS 2022 17.0 [23](#note_23) | +|  [`P2259R1 Partial LWG issue resolution: repairing Input Range Adaptors and counted_iterator`](https://wg21.link/P2259R1) | VS 2022 17.0 [23](#note_23) | +| **C++23 Standard library features** | **Supported** | +|  [`P0288R9 move_only_function​`](https://wg21.link/p0288r9) | VS 2022 17.2 [23](#note_23) | +|  [`P0323R12 ​​`](https://wg21.link/p0323r12) | VS 2022 17.3 [23](#note_23) | +|  [`P0401R6 Providing Size Feedback In The Allocator Interface​`](https://wg21.link/p0401r6) | VS 2022 17.0 [23](#note_23) | +|  [`P0448R4 ​`](https://wg21.link/p0448r4) | VS 2022 17.1 [23](#note_23) | +|  [`P0627R6 unreachable()​`](https://wg21.link/p0627r6) | VS 2022 17.2 [23](#note_23) | +|  [`P0798R8 Monadic Operations For optional​`](https://wg21.link/p0798r8) | VS 2022 17.2 [23](#note_23) | +|  [`P0849R8 auto(x): decay-copy In The Language​`](https://wg21.link/p0849r8) | VS 2022 17.4 [23](#note_23) | +|  [`P0881R7 ​`](https://wg21.link/p0881r7) | VS 2022 17.4 [23](#note_23) | +|  [`P0943R6 Supporting C Atomics In C++​`](https://wg21.link/p0943r6) | VS 2022 17.1 [23](#note_23) | +|  [`P1048R1 is_scoped_enum​`](https://wg21.link/p1048r1) | VS 2022 17.0 [23](#note_23) | +|  [`P1072R10 basic_string::resize_and_overwrite​`](https://wg21.link/p1072r10) | VS 2022 17.1 [23](#note_23) | +|  [`P1132R7 out_ptr(), inout_ptr()​`](https://wg21.link/p1132r7) | VS 2022 17.0 [23](#note_23) | +|  [`P1147R1 Printing volatile Pointers​`](https://wg21.link/p1147r1) | VS 2022 17.1 [23](#note_23) | +|  [`P1206R7 Conversions From Ranges To Containers​`](https://wg21.link/p1206r7) | VS 2022 17.4 [23](#note_23) | +|  [`P1272R4 byteswap()​`](https://wg21.link/p1272r4) | VS 2022 17.1 [23](#note_23) | +|  [`P1328R1 constexpr type_info::operator==()​`](https://wg21.link/p1328r1) | VS 2022 17.4 [23](#note_23) | +|  [`P1413R3 Deprecate aligned_storage And aligned_union​​`](https://wg21.link/p1413r3) | VS 2022 17.3 [23](#note_23) | +|  [`P1425R4 Iterator Pair Constructors For stack And queue​`](https://wg21.link/p1425r4) | VS 2022 17.1 [23](#note_23) | +|  [`P1518R2 Stop Overconstraining Allocators In Container Deduction Guides​`](https://wg21.link/p1518r2) | VS 2022 17.1 [23](#note_23) | +|  [`P1659R3 ranges::starts_with, ranges::ends_with​`](https://wg21.link/p1659r3) | VS 2022 17.1 [23](#note_23) | +|  [`P1679R3 contains() For basic_string/basic_string_view​`](https://wg21.link/p1679r3) | VS 2022 17.0 [23](#note_23) | +|  [`P1682R3 to_underlying() For Enumerations​`](https://wg21.link/p1682r3) | VS 2022 17.0 [23](#note_23) | +|  [`P1899R3 views::stride​`](https://wg21.link/p1899r3) | VS 2022 17.4 [23](#note_23) | +|  [`P1951R1 Default Template Arguments For pair's Forwarding Constructor​`](https://wg21.link/p1951r1) | VS 2022 17.0 [23](#note_23) | +|  [`P1989R2 Range Constructor For string_view​`](https://wg21.link/p1989r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2077R3 Heterogeneous Erasure Overloads For Associative Containers​`](https://wg21.link/p2077r3) | VS 2022 17.2 [23](#note_23) | +|  [`P2136R3 invoke_r()​`](https://wg21.link/p2136r3) | VS 2022 17.1 [23](#note_23) | +|  [`P2162R2 Inheriting from std::variant`](https://wg21.link/P2162R2) | VS 2022 17.0 [17](#note_17) | |  [`P2166R1 Prohibit basic_string and basic_string_view from being constructed from nullptr`](https://wg21.link/P2166R1) | VS 2022 17.0 [23](#note_23), [R](#note_R) | |  [`P2186R2 Removed garbage collection support`](https://wg21.link/P2186R2) | VS 2022 17.0 [23](#note_23), [Q](#note_Q) | -|  [`P2259R1 Partial LWG issue resolution: repairing Input Range Adaptors and counted_iterator`](https://wg21.link/P2259R1) | VS 2022 17.0 [23](#note_23), [S](#note_S) | +|  [`P2251R1 Require span And basic_string_view To Be Trivially Copyable​`](https://wg21.link/p2251r1) | VS 2022 17.1 [23](#note_23) | +|  [`P2273R3 constexpr unique_ptr​​`](https://wg21.link/p2273r3) | VS 2022 17.3 [23](#note_23) | +|  [`P2291R3 constexpr Integral ​`](https://wg21.link/p2291r3) | VS 2022 17.4 [23](#note_23) | +|  [`P2302R4 ranges::contains, ranges::contains_subrange​`](https://wg21.link/p2302r4) | VS 2022 17.4 [23](#note_23) | +|  [`P2321R2 std::zip​`](https://wg21.link/p2321r2) | partial in VS 2022 17.5 [23](#note_23) | +|  [`P2322R6 ranges::fold_left, ranges::fold_right, etc.​`](https://wg21.link/p2322r6) | VS 2022 17.5 [23](#note_23) | +|  [`P2387R3 Pipe Support For User-Defined Range Adaptors​`](https://wg21.link/p2387r3) | VS 2022 17.4 [23](#note_23) | +|  [`P2393R1 Cleaning Up Integer-Class Types​`](https://wg21.link/p2393r1) | VS 2022 17.2 [23](#note_23) | +|  [`P2401R0 Conditional noexcept For exchange()​`](https://wg21.link/p2401r0) | VS 2022 17.1 [23](#note_23) | +|  [`P2408R5 Ranges Iterators As Inputs To Non-Ranges Algorithms​`](https://wg21.link/p2408r5) | VS 2022 17.4 [23](#note_23) | +|  [`P2417R2 More constexpr bitset​`](https://wg21.link/p2417r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2419R2 Clarify Handling Of Encodings In Localized Formatting Of chrono Types​`](https://wg21.link/p2419r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2438R2 string::substr() &&​`](https://wg21.link/p2438r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2440R1 ranges::iota, ranges::shift_left, ranges::shift_right​`](https://wg21.link/p2440r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2441R2 views::join_with​`](https://wg21.link/p2441r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2442R1 Windowing Range Adaptors: views::chunk, views::slide​​`](https://wg21.link/p2442r1) | VS 2022 17.3 [23](#note_23) | +|  [`P2443R1 views::chunk_by​​`](https://wg21.link/p2443r1) | VS 2022 17.3 [23](#note_23) | +|  [`P2445R1 forward_like()​`](https://wg21.link/p2445r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2446R2 views::as_rvalue​`](https://wg21.link/p2446r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2465R3 Standard Library Modules std And std.compat​`](https://wg21.link/p2465r3) | no | +|  [`P2494R2 Relaxing Range Adaptors To Allow Move-Only Types​`](https://wg21.link/p2494r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2499R0 string_view Range Constructor Should Be explicit​`](https://wg21.link/p2499r0) | VS 2022 17.4 [23](#note_23) | +|  [`P2508R1 basic_format_string, format_string, wformat_string​`](https://wg21.link/p2508r1) | VS 2022 17.5 [23](#note_23) | +|  [`P2517R1 Conditional noexcept For apply()​`](https://wg21.link/p2517r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2520R0 move_iterator Should Be A Random-Access Iterator​​`](https://wg21.link/p2520r0) | VS 2022 17.4 [23](#note_23) | +|  [`P2549R1 unexpected::error()`](https://wg21.link/p2549r1) | VS 2022 17.3 [23](#note_23) | A group of papers listed together indicates a Standard feature along with one or more approved improvements or expansions. These features are implemented together. @@ -418,7 +509,7 @@ A group of papers listed together indicates a Standard feature along with one or | Feature | Supported | |--|--| -| __C99 Standard library features__ | __Supported__ | +| **C99 Standard library features** | **Supported** | |  Alternative spellings macros `` | VS 2015 | |  Wide character support `` and `` | VS 2015 | |  Complex support in `` | Partial in VS 2015 [K](#note_K) | @@ -435,12 +526,12 @@ A group of papers listed together indicates a Standard feature along with one or |  `boolean` type in `` | VS 2015 | |  `va_copy` macro | VS 2015 | |  Additional `strftime` conversion specifiers | Partial in VS 2015 [L](#note_L) | -| __C11 Standard library features__ | __Supported__ | +| **C11 Standard library features** | **Supported** | |  Alignment specifiers `` | VS 2019 16.8 [C11](#note_C11), [2104](#note_2104) | |  `aligned_alloc` | No [M](#note_M) | |  No return specifiers `` | VS 2019 16.8 [C11](#note_C11), [2104](#note_2104) | -|  Threading support `` | No | -|  Atomic support `` | No | +|  Threading support `` | yes | +|  Atomic support `` | experimental | |  `char16_t`, `char32_t` `` | VS 2019 16.8 [C11](#note_C11) | |  `gets()` removed | VS 2019 16.8 [C11](#note_C11), [N](#note_N) | |  `gets_s()` | VS 2019 16.8 [C11](#note_C11) | @@ -450,49 +541,55 @@ A group of papers listed together indicates a Standard feature along with one or |  `quick_exit` | VS 2019 16.8 [C11](#note_C11) | |  `` macros | VS 2019 16.8 [C11](#note_C11) | |  floating point characteristics `` | VS 2019 16.8 [C11](#note_C11) | +|  C11 threads `` | VS 2022 17.8 [C11](#note_C11) | ### Supported values -__No__ Not yet implemented.\ -__Partial__ The implementation is incomplete. For more information, see the [Notes](#notes) section.\ -__VS 2010__ Supported in Visual Studio 2010.\ -__VS 2013__ Supported in Visual Studio 2013.\ -__VS 2015__ Supported in Visual Studio 2015 (RTW).\ -__VS 2015.2__ and __VS 2015.3__ indicate features that are supported in Visual Studio 2015 Update 2 and Visual Studio 2015 Update 3, respectively.\ -__VS 2017 15.0__ Supported in Visual Studio 2017 version 15.0 (RTW).\ -__VS 2017 15.3__ Supported in Visual Studio 2017 version 15.3.\ -__VS 2017 15.5__ Supported in Visual Studio 2017 version 15.5.\ -__VS 2017 15.7__ Supported in Visual Studio 2017 version 15.7.\ -__VS 2019 16.0__ Supported in Visual Studio 2019 version 16.0 (RTW).\ -__VS 2019 16.1__ Supported in Visual Studio 2019 version 16.1.\ -__VS 2019 16.2__ Supported in Visual Studio 2019 version 16.2.\ -__VS 2019 16.3__ Supported in Visual Studio 2019 version 16.3.\ -__VS 2019 16.4__ Supported in Visual Studio 2019 version 16.4.\ -__VS 2019 16.5__ Supported in Visual Studio 2019 version 16.5.\ -__VS 2019 16.6__ Supported in Visual Studio 2019 version 16.6.\ -__VS 2019 16.7__ Supported in Visual Studio 2019 version 16.7.\ -__VS 2019 16.8__ Supported in Visual Studio 2019 version 16.8.\ -__VS 2019 16.9__ Supported in Visual Studio 2019 version 16.9.\ -__VS 2019 16.10__ Supported in Visual Studio 2019 version 16.10.\ -__VS 2022 17.0__ Supported in Visual Studio 2022 version 17.0. +**No** Not yet implemented.\ +**Partial** The implementation is incomplete. For more information, see the [Notes](#notes) section.\ +**VS 2010** Supported in Visual Studio 2010.\ +**VS 2013** Supported in Visual Studio 2013.\ +**VS 2015** Supported in Visual Studio 2015 (RTW).\ +**VS 2015.2** and **VS 2015.3** indicate features that are supported in Visual Studio 2015 Update 2 and Visual Studio 2015 Update 3, respectively.\ +**VS 2017 15.0** Supported in Visual Studio 2017 version 15.0 (RTW).\ +**VS 2017 15.3** Supported in Visual Studio 2017 version 15.3.\ +**VS 2017 15.5** Supported in Visual Studio 2017 version 15.5.\ +**VS 2017 15.7** Supported in Visual Studio 2017 version 15.7.\ +**VS 2019 16.0** Supported in Visual Studio 2019 version 16.0 (RTW).\ +**VS 2019 16.1** Supported in Visual Studio 2019 version 16.1.\ +**VS 2019 16.2** Supported in Visual Studio 2019 version 16.2.\ +**VS 2019 16.3** Supported in Visual Studio 2019 version 16.3.\ +**VS 2019 16.4** Supported in Visual Studio 2019 version 16.4.\ +**VS 2019 16.5** Supported in Visual Studio 2019 version 16.5.\ +**VS 2019 16.6** Supported in Visual Studio 2019 version 16.6.\ +**VS 2019 16.7** Supported in Visual Studio 2019 version 16.7.\ +**VS 2019 16.8** Supported in Visual Studio 2019 version 16.8.\ +**VS 2019 16.9** Supported in Visual Studio 2019 version 16.9.\ +**VS 2019 16.10** Supported in Visual Studio 2019 version 16.10.\ +**VS 2022 17.0** Supported in Visual Studio 2022 version 17.0.\ +**VS 2022 17.1** Supported in Visual Studio 2022 version 17.1.\ +**VS 2022 17.2** Supported in Visual Studio 2022 version 17.2.\ +**VS 2022 17.3** Supported in Visual Studio 2022 version 17.3.\ +**VS 2022 17.4** Supported in Visual Studio 2022 version 17.4.\ +**VS 2022 17.5** Supported in Visual Studio 2022 version 17.5. ### Notes - __A__ In [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) mode, dynamic exception specifications remain unimplemented, and `throw()` is still treated as a synonym for `__declspec(nothrow)`. In C++17, dynamic exception specifications were mostly removed by P0003R5, leaving one vestige: `throw()` is deprecated and required to behave as a synonym for **`noexcept`**. In [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode, MSVC now conforms to the Standard by giving `throw()` the same behavior as **`noexcept`**, that is, enforcement via termination. + **A** In [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) mode, dynamic exception specifications remain unimplemented, and `throw()` is still treated as a synonym for `__declspec(nothrow)`. In C++17, dynamic exception specifications were mostly removed by P0003R5, except for one vestige: `throw()` is deprecated and required to behave as a synonym for **`noexcept`**. In [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode, MSVC now conforms to the Standard by giving `throw()` the same behavior as **`noexcept`**, that is, enforcement via termination. -The compiler option [`/Zc:noexceptTypes`](../build/reference/zc-noexcepttypes.md) requests our old behavior of `__declspec(nothrow)`. It's likely that `throw()` will be removed in a future version of C++. To help with migrating code in response to these changes in the Standard and our implementation, new compiler warnings for exception specification issues have been added under [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and [`/permissive-`](../build/reference/permissive-standards-conformance.md). +The compiler option [`/Zc:noexceptTypes`](../build/reference/zc-noexcepttypes.md) requests the old behavior of `__declspec(nothrow)`. It's likely that `throw()` will be removed in a future version of C++. To help with migrating code in response to these changes in the Standard and the Microsoft implementation, new compiler warnings for exception specification issues are added under [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and [`/permissive-`](../build/reference/permissive-standards-conformance.md). - __B__ Supported in [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode in Visual Studio 2017 version 15.7. For more information, see [Two-phase name lookup support comes to MSVC](https://devblogs.microsoft.com/cppblog/two-phase-name-lookup-support-comes-to-msvc/). + **B** Supported in [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode in Visual Studio 2017 version 15.7. For more information, see [`Two-phase name lookup support comes to MSVC`](https://devblogs.microsoft.com/cppblog/two-phase-name-lookup-support-comes-to-msvc/). - __C__ Starting in Visual Studio 2019 version 16.6, the compiler fully implements the C99 preprocessor via the [`/Zc:preprocessor`](../build/reference/zc-conformance.md) option. (Before version 16.6, starting in Visual Studio 2017 version 15.8, the compiler provides support for the C99 preprocessor via the [`/experimental:preprocessor`](../build/reference/experimental-preprocessor.md) compiler option.) This option is on by default when the compiler option [`/std:c11`](../build/reference/std-specify-language-standard-version.md) or [`/std:c17`](../build/reference/std-specify-language-standard-version.md) is specified. + **C** In Visual Studio 2019 version 16.6 and later versions, the compiler fully implements the standard C99 preprocessor via the [`/Zc:preprocessor`](../build/reference/zc-conformance.md) option. (In Visual Studio 2017 versions 15.8 through 16.5, the compiler supports the standard C99 preprocessor via the [`/experimental:preprocessor`](../build/reference/experimental-preprocessor.md) compiler option.) This option is on by default when the compiler option [`/std:c11`](../build/reference/std-specify-language-standard-version.md) or [`/std:c17`](../build/reference/std-specify-language-standard-version.md) is specified. - __D__ Supported under [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) with a suppressible warning, [`C4984`](../error-messages/compiler-warnings/compiler-warning-c4984.md). + **D** Supported under [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) with a suppressible warning, [`C4984`](../error-messages/compiler-warnings/compiler-warning-c4984.md). - __E__ The implementation is sufficient to support the C++20 Standard Library. A complete implementation requires a binary breaking change. + **E** The implementation is sufficient to support the C++20 Standard Library. A complete implementation requires a binary breaking change. - __F__ Features removed when the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option is specified. To re-enable these features (to ease the transition to newer language modes), use these macros: `_HAS_AUTO_PTR_ETC`, `_HAS_FUNCTION_ALLOCATOR_SUPPORT`, `_HAS_OLD_IOSTREAMS_MEMBERS`, and `_HAS_UNEXPECTED`. + **F** Features removed when the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option is specified. To re-enable these features (to ease the transition to newer language modes), use these macros: `_HAS_AUTO_PTR_ETC`, `_HAS_FUNCTION_ALLOCATOR_SUPPORT`, `_HAS_OLD_IOSTREAMS_MEMBERS`, and `_HAS_UNEXPECTED`. - __G__ C++17's parallel algorithms library is complete. Complete doesn't mean every algorithm is parallelized in every case. The most important algorithms have been parallelized, and execution policy signatures are provided even where we don't parallelize algorithms. Our implementation's central internal header, \, contains the following "Parallel Algorithms Notes": C++ allows an implementation to implement parallel algorithms as calls to the serial algorithms. This implementation parallelizes several common algorithm calls, but not all. + **G** C++17's parallel algorithms library is complete. Complete doesn't mean that every algorithm is parallelized in every case. The most important algorithms have been parallelized. Execution policy signatures are provided even where the implementation doesn't parallelize algorithms. The central internal header, ``, contains the following "Parallel Algorithms Notes": C++ allows an implementation to implement parallel algorithms as calls to the serial algorithms. This implementation parallelizes several common algorithm calls, but not all. The following algorithms are parallelized: @@ -504,52 +601,52 @@ These algorithms aren't presently parallelized: - `copy`, `copy_n`, `fill`, `fill_n`, `move`, `reverse`, `reverse_copy`, `rotate`, `rotate_copy`, `shift_left`, `shift_right`, `swap_ranges` - Confusion over user parallelism requirements exists for these algorithms, which are likely in the above category anyway: - `generate`, `generate_n` -- Effective parallelism of these algorithms may be infeasible: +- Effective parallelism of these algorithms might be infeasible: - `partial_sort`, `partial_sort_copy` -- These algorithms haven't been evaluated yet. We may implement parallelism in a future release: +- These algorithms haven't been evaluated yet. The library might implement parallelism in a future release: - `copy_if`, `includes`, `inplace_merge`, `lexicographical_compare`, `max_element`, `merge`, `min_element`, `minmax_element`, `nth_element`, `partition_copy`, `remove_copy`, `remove_copy_if`, `replace_copy`, `replace_copy_if`, `set_symmetric_difference`, `set_union`, `stable_partition`, `unique`, `unique_copy` - __H__ This is a wholly new implementation, incompatible with the previous `std::experimental` version, made necessary by symlink support, bug fixes, and changes in standard-required behavior. Currently, `` provides both the new `std::filesystem` and the previous `std::experimental::filesystem`. The `` header provides only the old experimental implementation. The experimental implementation will be removed in the next ABI-breaking release of the libraries. + **H** This is a wholly new implementation, incompatible with the previous `std::experimental` version, made necessary by symlink support, bug fixes, and changes in standard-required behavior. Currently, `` provides both the new `std::filesystem` and the previous `std::experimental::filesystem`. The `` header provides only the old experimental implementation. Expect removal of the experimental implementation in the next ABI-breaking release of the libraries. - __I__ Supported by a compiler intrinsic. + **I** Supported by a compiler intrinsic. - __J__ `std::byte` is enabled by [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later, but because it can conflict with the Windows SDK headers in some cases, it has a fine-grained opt-out macro. To disable it, define `_HAS_STD_BYTE` as `0`. + **J** `std::byte` is enabled by [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later, but because it can conflict with the Windows SDK headers in some cases, it has a fine-grained opt-out macro. To disable it, define `_HAS_STD_BYTE` as `0`. - __K__ MSVC doesn't support the `_Complex` keyword or native complex types. The Universal CRT `` uses implementation-specific macros to achieve the same effect. For more information, see [C complex math support](../c-runtime-library/complex-math-support.md). + **K** MSVC doesn't support the `_Complex` keyword or native complex types. The Universal CRT `` uses implementation-specific macros to achieve the same effect. For more information, see [C complex math support](../c-runtime-library/complex-math-support.md). - __L__ The Universal CRT doesn't implement the `strftime` `E` and `O` alternative conversion modifiers. These modifiers are ignored (for example, `%Oe` behaves the same as `%e`). The modifiers aren't supported by the underlying locale APIs. + **L** The Universal CRT doesn't implement the `strftime` `E` and `O` alternative conversion modifiers. These modifiers are ignored (for example, `%Oe` behaves the same as `%e`). The modifiers aren't supported by the underlying locale APIs. - __M__ The Universal CRT doesn't implement C11 `aligned_alloc`, but does provide [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md) and [`_aligned_free`](../c-runtime-library/reference/aligned-free.md). Because the Windows operating system doesn't support aligned allocations, this function is unlikely to be implemented. + **M** The Universal CRT doesn't implement C11 `aligned_alloc`, but does provide [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md) and [`_aligned_free`](../c-runtime-library/reference/aligned-free.md). Because the Windows operating system doesn't support aligned allocations, this function is unlikely to be implemented. - __N__ The declaration is removed, but the export for the function remains for backward compatibility. + **N** The declaration is removed, but the export for the function remains for backward compatibility. - __O__ Certain bounds-checking functions are unimplemented, or have different signatures, or aren't part of the C11 or C17 standard. These functions are unimplemented: `abort_handler_s`, `ignore_handler_s`, `memset_s`, `set_constraint_handler_s`, `snprintf_s`, `snwprintf_s`, `strerrorlen_s`, `vsnwprintf_s`. These functions have different signatures: `gmtime_s`, `localtime_s`, `qsort_s`, `strtok_s`, `vsnprintf_s`, `wcstok_s`. These functions don't appear in the standard: `clearerr_s`, `fread_s`. + **O** Certain bounds-checking functions are unimplemented, or have different signatures, or aren't part of the C11 or C17 standard. These functions are unimplemented: `abort_handler_s`, `ignore_handler_s`, `memset_s`, `set_constraint_handler_s`, `snprintf_s`, `snwprintf_s`, `strerrorlen_s`, `vsnwprintf_s`. These functions have different signatures: `gmtime_s`, `localtime_s`, `qsort_s`, `strtok_s`, `vsnprintf_s`, `wcstok_s`. These functions don't appear in the standard: `clearerr_s`, `fread_s`. - __P__ Support was added in VS 2019 16.10. Support for Clang was added in VS 2022 17.0. + **P** Support was added in Visual Studio 2019 version 16.10. Support for Clang was added in Visual Studio 2022 version 17.0. - __Q__ This removes `declare_reachable`, `undeclare_reachable`, `declare_no_pointers`, `undeclare_no_pointers`, `get_pointer_safety`. Previously, these functions had no effect. + **Q** This removes `declare_reachable`, `undeclare_reachable`, `declare_no_pointers`, `undeclare_no_pointers`, `get_pointer_safety`. Previously, these functions had no effect. - __R__ This is a common **source-breaking** change. However, code that previously had undefined behavior at runtime will now be rejected with compiler errors. + **R** This is a common **source-breaking** change. However, code that previously had undefined behavior at runtime is now rejected with compiler errors. - __S__ The `counted_iterator` part is implemented; the input range adaptors part isn't yet implemented. + **S** Input range adaptors and `counted_iterator` are implemented in VS 2022 17.0. A future update to Visual Studio 2019 version 16.11 is planned to incorporate these changes. - __T__ `` is currently supported when compiling as C++ (`/std:c++latest`). It isn't yet supported when compiling as C (`/std:c11` and `/std:c17`) + **T** `` is currently supported when compiled as C++ (`/std:c++latest`). It isn't yet supported when compiled as C (`/std:c11` and `/std:c17`) - __14__ These C++17 and C++20 features are always enabled, even when [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) (the default) is specified. The reason is either because the feature was implemented before the introduction of the **`/std`** options, or because conditional implementation was undesirably complex. + **14** These C++17 and C++20 features are always enabled, even when [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) (the default) is specified. The reason is either because the feature was implemented before the introduction of the **`/std`** options, or because conditional implementation was undesirably complex. - __17__ These features are enabled by the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option. + **17** These features are enabled by the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option. - __20__ In versions through Visual Studio 2019 version 16.10, these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Visual Studio 2019 version 16.11 added the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler option to enable these features. + **20** In versions through Visual Studio 2019 version 16.10, these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Visual Studio 2019 version 16.11 added the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler option to enable these features. - __20abi__ Because of ongoing post-release work on the C++20 standard, ``, the formatting parts of `` (which rely on ``), and the range factories and range adaptors from `` (everything that needs the `view` concept) are only available under **`/std:c++latest`**. We'll make these features available under **`/std:c++20`** after reaching agreement with WG21 that no further ABI-breaking changes are necessary. The remaining parts of `` and the algorithms that apply to ranges are enabled under the **`/std:c++20`** compiler option starting in Visual Studio 2019 version 16.11. + **20abi** Because of ongoing post-release work on the C++20 standard, ``, the formatting parts of `` (which rely on ``), and the range factories and range adaptors from `` (everything that needs the `view` concept) are only available under **`/std:c++latest`**. Expect these features under **`/std:c++20`** after agreement is reached with WG21 that no further ABI-breaking changes are necessary. The remaining parts of `` and the algorithms that apply to ranges are enabled under the **`/std:c++20`** compiler option in Visual Studio 2019 version 16.11 and later versions. - __23__ In Visual Studio 2022 version 17.0 and up, these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. + **23** In Visual Studio 2022 version 17.0 and up, these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. - __C11__ Compiler support for C11 and C17 requires Visual Studio 2019 version 16.8 or higher. Except as noted, C11 and C17 library support requires Windows SDK build 10.0.20211.0 or higher. For more information on how to install support for C11 and C17, see [Install C11 and C17 support in Visual Studio](./install-c17-support.md). + **C11** Compiler support for C11 and C17 requires Visual Studio 2019 version 16.8 or higher. Except as noted, C11 and C17 library support requires Windows SDK build 10.0.20211.0 or higher. For more information on how to install support for C11 and C17, see [Install C11 and C17 support in Visual Studio](./install-c17-support.md). - __DR__ These features are enabled in all C++ [`/std`](../build/reference/std-specify-language-standard-version.md) compiler option modes. The C++ Standard committee adopted this change as a retroactive Defect Report to C++11 and all later versions. + **DR** These features are enabled in all C++ [`/std`](../build/reference/std-specify-language-standard-version.md) compiler option modes. The C++ Standard committee adopted this change as a retroactive Defect Report to C++11 and all later versions. - __2104__ C11 library support for this feature requires Windows SDK build 10.0.20348.0 (version 2104) or higher. + **2104** C11 library support for this feature requires Windows SDK build 10.0.20348.0 (version 2104) or higher. ## See also diff --git a/docs/overview/visual-cpp-samples.md b/docs/overview/visual-cpp-samples.md index 433f20e896..3898b2ae6c 100644 --- a/docs/overview/visual-cpp-samples.md +++ b/docs/overview/visual-cpp-samples.md @@ -1,15 +1,15 @@ --- title: "Visual Studio C++ Samples" -description: "Summary descriptions of the samples available in the archived Visual Studio C++ samples repository on GitHub." -ms.date: "03/23/2020" -ms.technology: "cpp-language" -ms.assetid: 76798022-5886-48e7-a7f2-f99352b15cbf +description: "Learn about the samples available in the archived Visual Studio C++ samples repository on GitHub." +ms.date: 03/25/2025 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- -# Visual Studio C++ Samples +# Visual Studio C++ samples Samples for Visual Studio C++ are available on the web. Microsoft has produced many C++ samples that demonstrate different functionalities across multiple technologies. Here are a few of the places to find additional samples: -- [Microsoft Docs samples - C++](/samples/browse/?term=c%2B%2B) +- [C++ code samples](/samples/browse/?term=c%2B%2B) - [Windows samples on GitHub](https://microsoft.github.io/windows/) @@ -21,7 +21,24 @@ Samples for Visual Studio C++ are available on the web. Microsoft has produced m ## Archived C++ samples on GitHub -Visual Studio included C++ sample code in previous versions. The sample code was either installed with Visual Studio, or was available as a separate download. Many articles in our documentation refer to these samples. They don't get installed by Visual Studio anymore. Instead, a repository is available on GitHub. The tables below have descriptions for each sample, and links to the sample's directory in the repository. +Previous versions of Visual Studio included C++ sample code. The sample code was either installed with Visual Studio, or was available as a separate download. Many articles in our documentation refer to these samples. They don't get installed by Visual Studio anymore. Instead, a repository is available on GitHub. The following tables have descriptions for each sample, and links to the sample's directory in the repository. + +- [ATL samples](#atl-samples) +- [CLR and language samples](#clr-and-language-samples---windows-forms) +- [COM events samples](#com-events-samples) +- [ComTypeLibfor7 samples](#comtypelibfor7-samples) +- [Compiler samples](#compiler-samples) +- [CRT samples](#crt-samples) +- [Debugging samples](#debugging-samples) +- [Fusion samples](#fusion-samples) +- [Hilo sample](#hilo-sample) +- [International samples](#international-samples) +- [Language samples](#language-samples---general) +- [MFC samples](#mfc-samples) +- [ODBC samples](#odbc-samples) +- [OS samples](#os-samples) +- [Unix samples](#unix-samples) +- [Windows 8 samples](#windows-8-samples) [!INCLUDE[note_security_samplecode](includes/note_security_samplecode_md.md)] @@ -34,10 +51,10 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [ActiveDoc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to implement an Active Document Server. | | [Async](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Downloads data asynchronously from a URL. | | [ATLButton](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Creates a button that displays itself with three different bitmaps depending on its state. | -| [ATLDuck](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates using connection points with ATL controls. | +| [ATLDuck](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to use connection points with ATL controls. | | [ATLSecurity](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Shows how to use the ATL security classes to examine security settings. | | [ATLTraceTool](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Displays the output generated by the `ATLTRACE2` macro. | -| [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates the implementation and use of connection points (the IConnectionPointContainer and IConnectionPoint interfaces) in a multithreaded environment. | +| [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates the implementation and use of connection points (the `IConnectionPointContainer` and `IConnectionPoint` interfaces) in a multithreaded environment. | | [CThreadPool](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Shows how to use a thread pool in an application and how implementing a thread pool can improve the application's performance. | | [DCOM](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to call a COM object (implemented in a Windows service) from multiple clients, running on different machines. | | [MFCATL](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates how ATL COM objects can be used in an MFC server EXE. | @@ -72,7 +89,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [CatDB](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Displays the schema information, such as tables and columns, of OLE DB providers. | | [DBViewer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates a mid-level application that relies on the `CManualAccessor` class to take full control of data bindings for your applications. | -| [DynamicConsumer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates using dynamic accessor and schema rowset classes to read metadata from a database. | +| [DynamicConsumer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates how to use dynamic accessor and schema rowset classes to read metadata from a database. | | [MultiRead](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Reads through a table in a database using multiple threads. | ### ATL samples - OLEDB - Provider @@ -88,7 +105,6 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [BirthdayPicker](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/Windows%20Forms) | Shows how the .NET Framework resource mechanism can be used in C++ applications. It also demonstrates some common Window Forms components. | | [Calculator](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/Windows%20Forms) | Implements a simple pocket calculator using C++ and the .NET Framework Windows Forms classes. | -| Scribble (using MFC) | An MFC implementation of the Scribble sample, updated and extended to include new .NET functionality. | | [Scribble (Windows Forms)](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/General) | A Windows Forms implementation of the Scribble sample, updated and extended to include new .NET functionality. | | [STLCLR](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/CLR/stlclr/StlClr%20Sample) | Demonstrates some of the capabilities available when using the STL/CLR Library. | @@ -109,9 +125,9 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Illustrates the use and implementation of connection points (the `IConnectionPointContainer` and `IConnectionPoint` interfaces) in a multithreaded environment. | | [DCOM](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates how to call a COM object (implemented in a Windows service) from multiple clients, running on different computers. | | [FreeThrd](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates a multithreaded client and free-threaded server with compiler COM support. | -| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an in-process Automation server application with compiler COM support. | +| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an in-process automation server application with compiler COM support. | | [Labrador](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Implements an EXE server that doesn't have any user interface. | -| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an Automation server application with compiler COM support. | +| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an automation server application with compiler COM support. | ## Compiler samples @@ -119,7 +135,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| -| [ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Compiler) | Demonstrates how to map C/C++ compiler flags from other compilers to the Visual C++ compiler (cl.exe). | +| [ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Compiler) | Demonstrates how to map C/C++ compiler flags from other compilers to the Visual C++ compiler (`cl.exe`). | ### Compiler samples - MASM @@ -137,10 +153,10 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [CPUID](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Determines the capabilities of the CPU being run. | | [CRT_Dbg1](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the basic debugging features of the C run-time libraries. | -| [CRT_Dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the C run-time debugging hook functions. | +| [CRT_Dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the C runtime debugging hook functions. | | [DFACObjs](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Shows how to use the _CrtDoForAllClientObjects C run-time function to iterate through a linked list of client objects. | -| [Report](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the C run-time debugging report functions. | -| [RTC](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the run-time error checks feature. | +| [Report](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the C runtime debugging report functions. | +| [RTC](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the runtime error checks feature. | | [SecureCRT](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | This sample demonstrates how to upgrade code that used deprecated CRT functions to increase code security. | ## Debugging samples @@ -159,7 +175,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| -| [Hilo](https://github.com/Microsoft/VCSamples/tree/master/VC2013Samples/Hilo) | Hilo is a series of articles and sample applications. They demonstrate the power of Windows 7, Visual Studio and C++ to build high performance, responsive client applications. Hilo provides both source code and guidance that will help you design and develop compelling, touch-enabled Windows applications of your own.

This sample has been updated for Visual Studio 2013. It includes a hot fix to the *AsyncLoaderMemoryManager.cpp* file (in lines 36 and 37), which addresses a common crash issue. | +| [Hilo](https://github.com/Microsoft/VCSamples/tree/master/VC2013Samples/Hilo) | Hilo is a series of articles and sample applications. They demonstrate the power of Windows 7, Visual Studio and C++ to build high performance, responsive client applications. Hilo provides both source code and guidance that help you design and develop compelling, touch-enabled Windows applications of your own. | ## International samples @@ -201,13 +217,13 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| | [Button](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates use of an in-place active menu, a stock property page, and the About box control option. | -| [Circ](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates ActiveX control basics. These include control painting, stock and custom properties, stock and custom events, use of colors and fonts, the stock Font property page, the default property page, and versioning. | +| [Circ](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates ActiveX control basics. These include control painting, stock and custom properties, stock and custom events, use of colors and fonts, the stock font property page, the default property page, and versioning. | | [CmnCtrl](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates some of the new controls available with MFC on wiprlhext: The command link button (`CButton`), the pager control (`CPagerCtrl`), the split button (`CSplitButton`), and the network address control (`CNetAddressCtrl`). | | [Contain](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates a Visual Editing Container Application. | | [Image](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates how to use MFC to build an ActiveX control that downloads data asynchronously. | | [Licensed](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | A control that enforces use of a design-time and run-time license. | | [Localize](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | A control with a localized user interface that demonstrates use of separate type libraries and resource dynamic-link libraries (DLLs) for localization. | -| [NetAddr](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates use of the Windows Vista "Net Address Verifier" control. | +| [NetAddr](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates use of the Windows Vista *Net Address Verifier* control. | | [Pal](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Control that displays the colors of a palette. It demonstrates read-only properties, persistent Get/Set properties, persistent parameterized properties, and picture properties. | | [Push](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Control subclassed from a Windows owner-drawn button control. It demonstrates stock properties, custom events, and picture holders. | | [RegSvr](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates the invocation of Self-Registration Code. | @@ -227,7 +243,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [CtrlBars](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Custom toolbar and status bar, dialog bar, and floating palette. | | [CtrlTest](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Owner-draw list box and menu, custom control, bitmap button, spin control. | | [DBVList](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Uses the `CListView` and `CDaoRecordset` classes to implement the virtual list view functionality available for the list view common control. | -| [DIBLook](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Demonstrates the Use of DIBs and Color Palettes. | +| [DIBLook](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Demonstrates the use of DIBs and color palettes. | | [DlgCbr32](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Adding a toolbar and a status bar to a dialog-based application. | | [DlgTempl](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Demonstrates the dynamic creation of dialog templates. | | [DockTool](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/general) | Dragging and floating toolbars that are dockable. | @@ -258,23 +274,23 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [DHTMLExplore](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet) | Demonstrates handling DHTML events and using DHTML DDX. | | [HTMLEdit](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet) | Wraps the Internet Explorer MSHTML editing control. | -| [MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet) | Demonstrates the MFC `CHtmlView` and `CReBar` Classes. | +| [MFCIE](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet) | Demonstrates the MFC `CHtmlView` and `CReBar` classes. | | [Scheduler](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/internet) | Demonstrates how to create an HTML-based dialog box using the Visual C++ libraries classes. | ### MFC samples - OLE | Sample name | Description | |--|--| -| [ACDual](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Demonstrates how to add dual interface support to an MFC-based Automation server. | -| [AutoClik](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Illustrates Automation features. Includes AUTODRIV, a simple Automation client application that drives the AUTOCLIK sample application. | +| [ACDual](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Demonstrates how to add dual interface support to an MFC-based automation server. | +| [AutoClik](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Illustrates automation features. Includes AUTODRIV, a simple Automation client application that drives the AUTOCLIK sample application. | | [CalcDriv](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Automation client. | | [DrawCli](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Full-featured object-oriented drawing application that is also an ActiveX Visual Editing container. | -| [HierSvr](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Demonstrates a Server Application with OLE Drag and Drop. | -| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | An in-process Automation server that can be loaded as a DLL in the client's address space. | -| [IPDrive](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | A simple Automation client application that drives the INPROC sample application. | -| [MFCBind](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Shows how to create an Active document (formerly known as a DocObject) container. | -| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | An Automation server that implements a simple calculator. | -| [OClient](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | ActiveX Visual Editing container application, with drag and drop. | +| [HierSvr](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Demonstrates a server application with OLE Drag and Drop. | +| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | An in-process automation server that can be loaded as a DLL in the client's address space. | +| [IPDrive](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | A simple automation client application that drives the INPROC sample application. | +| [MFCBind](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Shows how to create an active document (formerly known as a DocObject) container. | +| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | An automation server that implements a simple calculator. | +| [OClient](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | ActiveX visual editing container application, with drag and drop. | | [OLEView](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Implementing an OLE object browser through custom OLE interfaces. | | [SuperPad](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Demonstrates a visual editing server that edits text using CEditView. | | [TstCon](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/ole) | Implements an ActiveX control container using MFC's support for OLE embedding. You can use TSTCON to test ActiveX controls, change their properties, and invoke their methods. | @@ -306,7 +322,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [OutlookDemo](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Demonstrates how to create an application similar to Outlook 2003/2007. | | [OutlookMultiViews](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Demonstrates how to switch between multiple views on a single document in an SDI application. The sample uses the Outlook bar control to list the available views and switch between them. | | [OwnerDrawMenu](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Illustrates how to draw popup menu items dynamically. | -| [PaletteDemo](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Illustrates how to create a multi-column toolbar with an owner-draw information area. Click 2, 3 or 4 buttons on the Standard toolbar to change at runtime the number of columns of the custom toolbar. | +| [PaletteDemo](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Illustrates how to create a multi-column toolbar with an owner-draw information area. Click 2, 3, or 4 buttons on the Standard toolbar to change at runtime the number of columns of the custom toolbar. | | [PropSheetDemo](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Illustrates the following types of Property Sheet control: simple, with tabs at the left side, with tree control at the left side, OneNote-style tabs, list of items at the left side. | | [RebarTest](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Demonstrates a customizable Rebar control that hosts a toolbar. | | [RibbonGadgets](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack) | Illustrates various controls that can be hosted in the Ribbon Control. At the bottom of the main frame, you can find the Source Code window with source code text, which outlines how to create a particular gadget. | @@ -349,7 +365,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| -| [Unix - ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples) | Demonstrates a wrapper that maps flags from the Sun Forte and gcc compilers to the Microsoft Visual C++ compiler (cl.exe). | +| [Unix - ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples) | Demonstrates a wrapper that maps flags from the Sun Forte and gcc compilers to the Microsoft Visual C++ compiler (`cl.exe`). | ## Windows 8 samples @@ -362,27 +378,27 @@ More information is available about the programming models, platforms, languages | [Background Transfer sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the power-friendly, cost-aware, and flexible behavior of the Background Transfer API for Windows Runtime applications. Provided sample scenarios cover file downloads and uploads. | | [CryptoWinRT sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the new Cryptography APIs. | | [Print sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how apps can integrate the Windows print experience. The scenarios demonstrated in this sample include: Printing from the app by using the charms bar and the print contract, Printing from within the app experience, and more. | -| [HttpClient sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the use of the HttpClient class and the IXMLHTTPRequest2 interface to upload and download various types of content from an HTTP server using the networking features provided by the Windows Runtime. | -| [Accelerometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Accelerometer` API. This sample allows the user to view the acceleration forces along the X-, Y-, and Z-axes for a 3-axis accelerometer. You can choose one of three scenarios. | +| [HttpClient sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the use of the `HttpClient` class and the `IXMLHTTPRequest2` interface to upload and download various types of content from an HTTP server using the networking features provided by the Windows Runtime. | +| [Accelerometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Accelerometer` API. This sample allows the user to view the acceleration forces along the X-, Y-, and Z-axes for a three-axis accelerometer. You can choose one of three scenarios. | | [Account picture name sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates different ways of getting the name of the user that is currently logged in. It also demonstrates how to get and set the image used for the user's tile. | | [App settings sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the ApplicationSettings API and settings flyouts to integrate an app's settings UI with the Settings charm. The sample uses the `Windows.UI.ApplicationSettings` namespace and `WinJS.UI.SettingsFlyout`. | | [Windows Store device app for camera sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to create a Windows Store device app for a camera. A Windows Store device app is provided by an IHV or OEM to differentiate the capture experience for a particular camera. | | [Getting started with C++ simple blog reader sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The sample demonstrates some basic principles of Windows Store app development in native C++ using XAML to define the user interface. It's a complete working version of the application discussed on the Windows Developer Center. | -| [Reading and writing data sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the DataReader and DataWriter classes to store and retrieve data. | +| [Reading and writing data sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `DataReader` and `DataWriter` classes to store and retrieve data. | | [Application data sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows you how to store and retrieve data that is specific to each user and Windows Store app using the Windows Runtime application data APIs. Application data includes session state, user preferences, and other settings. | -| [Custom driver access sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use CreateDeviceAccessInstance and IDeviceIoControl to access a specialized device. | +| [Custom driver access sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use `CreateDeviceAccessInstance` and `IDeviceIoControl` to access a specialized device. | | [XAML ListView and GridView essentials sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the GridView and ListView controls. | | [Animation metrics sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the Animation Metrics APIs in `Windows.UI.Core.AnimationMetrics` to access the raw parameters that define the animations in the Windows Animation Library. | -| [Playback Manager msAudioCategory sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to select the correct msAudioCategory category for an audio-video (AV) stream to configure it as an audio playback stream. | +| [Playback Manager msAudioCategory sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to select the correct `msAudioCategory` category for an audio-video (AV) stream to configure it as an audio playback stream. | | [XAML DirectX 3D shooting game sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the implementation of a simple first person 3-D game using DirectX (Direct3D 11.1, Direct2D, XInput, and XAudio2) and XAML in a C++ app. XAML is used for the heads-up display and game state messages. | | [XAML scrolling, panning, and zooming sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the ScrollViewer control to pan and zoom. | | [XAML FlipView control sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the FlipView control to enable users to flip through a collection. | -| [Gyrometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Gyrometer` API. This sample allows the user to view the angular velocity along the X-, Y-, and Z-axis for a 3-axis gyrometer. | +| [Gyrometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Gyrometer` API. This sample allows the user to view the angular velocity along the X-, Y-, and Z-axis for a three-axis gyrometer. | | [Device app for printers SDK sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to create a device app for printers that can be activated from the tile contract, the printTaskSettings contract, and from toast displayed by backgroundTask in response to print driver event. | | [Background task sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows you how to create and register background tasks using the Windows Runtime background task API. A background task is triggered by a system or time event, and can be constrained by one or more conditions. | -| [StreamSocket sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the basics of the StreamSocket class using the networking features provided by the Windows Runtime. The client component of the sample creates a TCP socket to make a network connection, uses the socket to send data, and more. | +| [StreamSocket sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the basics of the `StreamSocket` class using the networking features provided by the Windows Runtime. The client component of the sample creates a TCP socket to make a network connection, uses the socket to send data, and more. | | [Scheduled notifications sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use scheduled and recurring tile updates and toast notifications for an app. This ability enables you to specify a precise time to deliver the notification, even if the app isn't running. | -| [Playback Manager Companion Sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to select the correct msAudioCategory category for an audio-video stream to configure it as an audio playback stream. | +| [Playback Manager Companion Sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to select the correct `msAudioCategory` category for an audio-video stream to configure it as an audio playback stream. | | [OrientationSensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.OrientationSensor` API. It allows the user to view the rotation matrix and Quaternion values that reflect the current device orientation. | | [File access sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to create, read, write, copy and delete a file, how to retrieve file properties, and how to track a file or folder so that your app can access it again. This sample uses `Windows.Storage` and `Windows.Storage.AccessCache` API. | | [Removable storage sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The removable storage sample demonstrates how to transfer files to and from removable storage devices. This sample requires a removable storage device connected to the system, such as a camera, media player, cellular phone, or a USB thumb drive. | @@ -397,7 +413,7 @@ More information is available about the programming models, platforms, languages | [DirectX 3D shooting game sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the implementation of a simple first person 3-D game using DirectX (Direct3D 11.1, Direct2D, XInput, and XAudio2) in a C++ app. | | [XAML AppBar control sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the AppBar control to present navigation, commands, and tools to users. The app bar is hidden by default and appears when users swipe a finger from the top or bottom edge of the screen. | | [Date and time formatting sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the DateTimeFormatter class in the `Windows.Globalization.DateTimeFormatting` namespace to display dates and times according to the user's preferences. | -| [Secondary tiles sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to pin and use a secondary tile. That's a tile that directly accesses a specific, non-default section or experience within an app, such as a saved game, or a specific friend in a social networking app. | +| [Secondary tiles sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to pin and use a secondary tile. That's a tile that directly accesses a specific, nondefault section or experience within an app, such as a saved game, or a specific friend in a social networking app. | | [Input Touch hit testing sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample uses a polygon shapes puzzle to demonstrate how to handle pointer input, implement custom hit testing for touch input, and process manipulations in a Windows Store app using C++ and DirectX. | | [Network information sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the Windows Runtime Network Information APIs. | | [Input Simplified ink sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use ink functionality in Windows Store apps. | @@ -406,11 +422,11 @@ More information is available about the programming models, platforms, languages | [Check if current session is remote sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the use of `Windows.System.RemoteDesktop` API. | | [Application resources and localization sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use application resources to separate localizable content from application code. The sample uses the `Windows.ApplicationModel.Resources.Core` and `Windows.Globalization` namespaces, and `WinJS.Resources`. | | [Context menu sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to create a context menu and how to replace the default context menu for text. This sample uses `Windows.UI.Popups` API, including the PopupMenu and the oncontextmenu event. | -| [Geolocation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The Geolocation sample demonstrates how to use the Geolocation API to get the geographic location of the user's PC. An app can use the Geolocation API to get location one time, or it can continuously track the location. | +| [Geolocation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The Geolocation sample demonstrates how to use the Geolocation API to get the geographic location of the user's PC. An app can use the `Geolocation` API to get location one time, or it can continuously track the location. | | [Message dialog sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use a MessageDialog for displaying dialogs, setting commands and their actions, and changing the default button. The `Windows.UI.Popups` namespace contains the MessageDialog class. | | [MediaStreamSource media extension sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to support the Microsoft Silverlight MediaStreamSource concept in a Windows Store app. | | [DirectWrite vertical text sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample uses DirectWrite and Direct2D to properly display vertical text in a custom layout shape. | -| [DXGI swap chain rotation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the IDXGISwapChain1::SetRotation method and how you can use the method in conjunction with prerotated content to improve presentation performance. | +| [DXGI swap chain rotation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the IDXGISwapChain1::SetRotation method and how you can use the method with prerotated content to improve presentation performance. | | [Direct2D custom image effects sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to implement custom Direct2D Effects using standard pixel, vertex, and compute shaders. | | [DirectX touch input sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates touch and mouse navigation of a 3-D environment in a C++ app with Direct3D. | | [XInput game controller sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the use of the XInput APIs in a C++ app. It reads input from an Xbox game controller and displays data about the analog stick movements and button presses. | @@ -425,14 +441,14 @@ More information is available about the programming models, platforms, languages | [Display orientation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the `DisplayProperties` class to set the display orientation in an app. | | [Direct2D interpolation modes sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows the various interpolation modes used by Direct2D. | | [Globalization preferences sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the `Windows.System.UserProfile.GlobalizationPreferences` class to obtain the user's globalization preferences. It also shows how to use the `GeographicRegion` and `Language` classes. | -| [Direct2D geometry realization sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how multi-core geometry tessellation can help reduce geometry rendering time. Using opacity masks and meshes is an alternative to traditional geometry rendering that may be better in some situations. | +| [Direct2D geometry realization sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how multi-core geometry tessellation can help reduce geometry rendering time. Using opacity masks and meshes is an alternative to traditional geometry rendering that might be better in some situations. | | [Language font mapping sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to obtain language-specific font recommendations using the `LanguageFontGroup` class in the `Windows.Globalization.Fonts` namespace. | -| [Inclinometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Inclinometer` API. This sample allows the user to view the angles of incline about the X-, Y-, and Z-axis for a 3-axis inclinometer. | +| [Inclinometer sensor sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Devices.Sensors.Inclinometer` API. This sample allows the user to view the angles of incline about the X-, Y-, and Z-axis for a three-axis inclinometer. | | [XAML high contrast style sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates various techniques for implementing support for high contrast mode in your app. Support for high contrast mode is important to make your app accessible to people with eyesight problems. | | [Input Device capabilities sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to query the input devices that are connected to the user's device. And, how to support the pointer, touch, pen/stylus, mouse, and keyboard input modes of Windows Store apps. | | [EAS policies for mail clients sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how mail clients can retrieved device information and work with supplied Exchange Active Sync (EAS) policies. Windows Store apps can configure their mail clients to stay compliant with the given EAS policies. | | [DatagramSocket sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the basics of the `DatagramSocket` class using the networking features provided by the Windows Runtime. The client component of the sample creates a UDP socket, uses the socket to send and receive data, and closes the socket. | -| [DirectWrite hello world sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use DirectWrite and Direct2D to render the text "Hello World" to a `CoreWindow`. | +| [DirectWrite hello world sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use DirectWrite and Direct2D to render the text *Hello World* to a `CoreWindow`. | | [Compression sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to read structured data from a file and write compressed data to a new file and how to read compressed data and write decompressed data to a new file. Many applications need to compress and decompress data. | | [Network status background sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to determine a change in Internet connection profile by registering a background task handler for Network Status Change event using an Internet Present condition. | | [App package information sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows you how to get package information using the Windows Runtime packaging API. Users acquire your Windows Store app as an app package. Windows uses the information in an app package to install the app on a per-user basis. | @@ -473,7 +489,7 @@ More information is available about the programming models, platforms, languages | [Playlist sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to create, save, display, and edit a playlist of audio files. This sample uses classes that are in the `Windows.Media.Playlists` namespace. | | [Media Server client sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to create a Media Server client using the Media Server API. The Media Server sample demonstrates how to browse a Digital Media Server programmatically on your local network, and display all of its video files. | | [Direct2D magazine app sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use Direct2D, DirectWrite, Windows Imaging Component (WIC), and XAML to build an app with a magazine-type presentation. | -| [Mobile broadband account and device management sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the Windows 8 Mobile Broadband API (`Windows.Networking.NetworkOperators`) employed by Mobile Network Operators (MNO). It demonstrates how to use the MobileBroadbandAccount APIs to retrieve and display available Mobile Broadband accounts. | +| [Mobile broadband account and device management sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the Windows 8 Mobile Broadband API (`Windows.Networking.NetworkOperators`) employed by Mobile Network Operators (MNO). It demonstrates how to use the `MobileBroadbandAccount` APIs to retrieve and display available Mobile Broadband accounts. | | [Proximity sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the `PeerFinder` and `ProximityDevice` classes to communicate with nearby computers. You can use the `Proximity` API to exchange small messages during a tap gesture or set up a socket connection between peer apps. | | [Creating a Windows Runtime in-process component sample (C++CX) (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to create a component in C++/CX that's used in C++/CX, JavaScript, and C# client code. The OvenServer project contains a runtime class named `Oven`, which implements an `IOven` interface and an `IAppliance` interface. | | [Device auto rotation preferences sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `DisplayProperties` class to handle and verify device rotation events. | @@ -495,14 +511,14 @@ More information is available about the programming models, platforms, languages | [Device enumeration sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the Device Enumeration API to find available devices and look for device information. The sample presents two scenarios: In the first scenario, the Device Enumeration API is used to look for specific device interfaces. | | [DirectWrite paragraph text sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use DirectWrite and Direct2D to render paragraph text to a `CoreWindow`. And, apply justification and character spacing to the layout. | | [Responding to the appearance of the on-screen keyboard sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | [This documentation is preliminary and is subject to change.] This sample shows how to listen for and respond to the appearance of the onscreen soft keyboard. When focus is given to an element that requires text input on a device that doesn't have a keyboard. | -| [XAML data binding sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates basic data binding techniques using the Binding class and Binding markup extension. | +| [XAML data binding sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates basic data binding techniques using the `Binding` class and `Binding` markup extension. | | [Direct3D tutorial sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample is a five-lesson tutorial. It provides an introduction to the Direct3D API, and introduces the concepts and code used in many of the other DirectX samples. | | [Direct2D effects photo adjustment app sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows various common photo manipulation techniques using Direct2D Effects. This sample is divided into several parts. Lesson 1: Shows the basics of loading and drawing an image using Direct2D Effects. | | [Windows Audio Session (WASAPI) sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | Demonstrates how to do various audio related tasks using the Windows Audio Session API (WASAPI). | | [User domain name sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the domain-related functionality provided by the `UserInformation` class of the `Windows.System.UserProfile` namespace. The UserInformation class enables an app to get and set information about the user. | | [USSD message management sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates network account management using the USSD protocol with GSM-capable mobile broadband devices. USSD is typically used for account management of a mobile broadband profile by the Mobile Network Operator (MNO). | | [Bing Maps Trip Optimizer sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The sample demonstrates how to use JavaScript and Visual C++ and to create app for Windows 8 named Bing Maps Trip Optimizer. Bing Maps Trip Optimizer uses JavaScript to define the UI, and C++ for a computationally expensive algorithm in parallel. | -| [Direct2D and DirectWrite animated text on a path sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use Direct2D and DirectWrite to render a string of text along an animated, non-linear geometric path. The app renders "Hello, World!" repeated several times in different languages along a Bezier curve. | +| [Direct2D and DirectWrite animated text on a path sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use Direct2D and DirectWrite to render a string of text along an animated, nonlinear geometric path. The app renders "Hello, World!" repeated several times in different languages along a Bezier curve. | | [Wi-Fi hotspot authentication sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the Windows 8 Mobile Broadband API (`Windows.Networking.NetworkOperators`) for Wi-Fi hotspot authentication. Use this mechanism as an alternative to configuring static credentials for a Wi-Fi hotspot. | | [XAML images sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates various techniques for displaying and manipulating images in your app using the Image control and the BitmapImage class. | | [HomeGroup app sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use a `HomeGroup` to open, search, and share files. This sample uses some of the `HomeGroup` options found in the `Windows.Storage.Pickers` and `Windows.Storage.KnownFolders`. | @@ -527,9 +543,9 @@ More information is available about the programming models, platforms, languages | [Direct2D command list sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the use of a command list. It's used for recording a set of vector commands, creating an image brush from the command list, and then filling a rectangle geometry with it. The command list preserves resolution independence of the vector. | | [ControlChannelTrigger XMLHTTPRequest sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | The sample shows how to use the `ControlChannelTrigger` class to enable a Windows Store app using `IXMLHTTPRequest2` to be always connected and always reachable. This sample demonstrates the use of background network notifications in a Windows Store app. | | [XInput and JavaScript controller sketch sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to wrap the XInput C++ API in a Windows Runtime component. Then, it calls it from a Windows Store app using JavaScript. This sample implements a sketch app that lets you use the Xbox game controller to select line thickness and more. | -| [Direct2D convolve matrix effect sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the Direct2D Effects convolve matrix effect. This sample has some example convolution kernel matrices: Passthrough (no-op), Box blur (width 5), Simple edge detect, Simple sharpen, Emboss, Vertical smear (height 10) theses and more. | +| [Direct2D convolve matrix effect sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates the Direct2D Effects convolve matrix effect. This sample has some example convolution kernel matrices: Passthrough (no-op), Box blur (width 5), Simple edge detect, Simple sharpen, Emboss, Vertical smear (height 10) these and more. | | [DirectX swap chain implementation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to receive `CoreWindow` events in a native application, and how to connect a DirectX swap chain to the application view. | -| [Credential picker sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Security.Credentials.UI.CredentialPicker` class to retrieve credentials. These credentials may be passed to APIs that require them, for example, `HttpClient`. | +| [Credential picker sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use the `Windows.Security.Credentials.UI.CredentialPicker` class to retrieve credentials. These credentials might be passed to APIs that require them, for example, `HttpClient`. | | [Direct2D animation sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to use Direct2D to render and animate a Direct2D primitive along a spiral path. | | [Sharing content target app sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how an app can receive content shared from another app. This sample uses classes from the `Windows.ApplicationModel.DataTransfer` and `Windows.ApplicationModel.DataTransfer.Share` namespaces. | | [Direct2D save to image file sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to render to the screen using Direct2D and DirectWrite. And, how to save the rendered image to disk using the WIC API. | @@ -537,7 +553,7 @@ More information is available about the programming models, platforms, languages | [Creating a Windows Runtime in-process component sample (C#) (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to create a component in C# that's used in C++/CX, JavaScript, and C# client code. The OvenServer project contains a runtime class named `Oven`, which implements an `IOven` interface and an `IAppliance` interface. | | [Push and periodic notifications client-side sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how a client app can register and listen for push notifications sent from a web server. Push notifications can be used to update a badge or a tile, raise a toast notification, or launch a background task. | | [Portable device API sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample shows how to access the `IPortableDevice` COM API from a C++ app. To learn how to access the `IPortableDevice` COM API from a Desktop C++ app, refer to the Portable Devices COM API Sample. | -| [PlayToReceiver sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to create a software Play To receiver. To advertise the software Play To Receiver, click the Start Receiver button. To stop the receiver, click the Stop Receiver button. | +| [PlayToReceiver sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to create a software Play To receiver. To advertise the software Play To receiver, select the **Start Receiver** button. To stop the receiver, select the **Stop Receiver** button. | | [Lock screen personalization sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the `LockScreen` API to set the current user's lock screen image. This sample uses classes from the `Windows.System.UserProfile` namespace. | | [Credential locker sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates how to use the WinRT `PasswordVault` APIs, and how to use the credential locker to store web credentials. Specific scenarios include a single user with a single resource, and multiple users with a single resource. | | [Media engine native C++ video playback sample (Windows 8)](https://github.com/Microsoft/VCSamples/tree/master/VC2012Samples/Windows%208%20samples/C%2B%2B/Windows%208%20app%20samples) | This sample demonstrates video playback using the `MediaEngine` API in a native C++ app. | diff --git a/docs/overview/what-s-new-for-cpp-2017.md b/docs/overview/what-s-new-for-cpp-2017.md index 0e0670a9b0..ada04edf00 100644 --- a/docs/overview/what-s-new-for-cpp-2017.md +++ b/docs/overview/what-s-new-for-cpp-2017.md @@ -2,7 +2,8 @@ title: "What's new for C++ in Visual Studio 2017" description: "The new features and fixes in the Microsoft C/C++ compiler and tools in Visual Studio 2017." ms.date: 10/04/2021 -ms.technology: "cpp-ide" +ms.service: "visual-cpp" +ms.subservice: "ide" ms.custom: intro-whats-new --- # What's new for C++ in Visual Studio 2017 @@ -54,11 +55,11 @@ This release brings several improvements in optimization, code generation, tools - Versioning: The value of the built-in preprocessor macro **\_MSC\_VER** is now being monotonically updated at every Visual C++ toolset update. For more information, see [Visual C++ Compiler Version](https://devblogs.microsoft.com/cppblog/visual-c-compiler-version/). - New toolset layout: The compiler and related build tools have a new location and directory structure on your development machine. The new layout enables side-by-side installations of multiple versions of the compiler. For more information, see [Compiler Tools Layout in Visual Studio 2017](https://devblogs.microsoft.com/cppblog/compiler-tools-layout-in-visual-studio-15/). - Improved diagnostics: The output window now shows the column where an error occurs. For more information, see [C++ compiler diagnostics improvements in VS "15" Preview 5](https://devblogs.microsoft.com/cppblog/c-compiler-diagnostics-improvements-in-vs-15-rc/). -- When using coroutines, the experimental keyword **yield** (available under the **`/await`** option) has been removed. Your code should be updated to use `co_yield` instead. For more information, see [`yield` keyword to become `co_yield` in VS 2017](https://devblogs.microsoft.com/cppblog/yield-keyword-to-become-co_yield-in-vs-2017/). +- When using coroutines, the experimental keyword **yield** (available under the **`/await`** option) was removed. Your code should be updated to use `co_yield` instead. For more information, see [`yield` keyword to become `co_yield` in VS 2017](https://devblogs.microsoft.com/cppblog/yield-keyword-to-become-co_yield-in-vs-2017/). ##### Visual Studio 2017 version 15.3 -Additional improvements to diagnostics in the compiler. For more information, see [Diagnostic Improvements in Visual Studio 2017 15.3.0](https://devblogs.microsoft.com/cppblog/diagnostic-improvements-in-vs2017-15-3-0/). +Improvements to diagnostics in the compiler. For more information, see [Diagnostic Improvements in Visual Studio 2017 15.3.0](https://devblogs.microsoft.com/cppblog/diagnostic-improvements-in-vs2017-15-3-0/). ##### Visual Studio 2017 version 15.5 @@ -80,7 +81,7 @@ The [`/Zc:noexceptTypes-`](../build/reference/zc-noexcepttypes.md) option can be ##### Visual Studio 2017 RTM (version 15.0) -- Minor `basic_string` `_ITERATOR_DEBUG_LEVEL != 0` diagnostics improvements. When an IDL check gets tripped in string machinery, it will now report the specific behavior that caused the trip. For example, instead of "string iterator not dereferencable" you'll get "cannot dereference string iterator because it is out of range (e.g. an end iterator)". +- Minor `basic_string` `_ITERATOR_DEBUG_LEVEL != 0` diagnostics improvements. When an IDL check gets tripped in string machinery, it now reports the specific behavior that caused the trip. For example, instead of "string iterator not dereferencable" you get "cannot dereference string iterator because it is out of range (e.g. an end iterator)". - Fixed the `std::promise` move assignment operator, which previously could cause code to block forever. - Fixed compiler errors with the `atomic` implicit conversion to `T*`. - `pointer_traits` now correctly detects `Ptr::rebind`. @@ -95,7 +96,7 @@ There are more standard library improvements in Visual Studio 2017 RTM. For a co - Standard library containers now clamp their `max_size()` to `numeric_limits::max()` rather than the `max()` of `size_type`. This change ensures that the result of `distance()` on iterators from that container is representable in the return type of `distance()`. - Fixed missing specialization `auto_ptr`. -- The `for_each_n()`, `generate_n()`, and `search_n()` algorithms previously failed to compile if the length argument wasn't an integral type. They now attempt to convert non-integral lengths to the iterators' `difference_type`. +- The `for_each_n()`, `generate_n()`, and `search_n()` algorithms previously failed to compile if the length argument wasn't an integral type. They now attempt to convert nonintegral lengths to the iterators' `difference_type`. - `normal_distribution` no longer emits warnings inside the standard library about narrowing from double to float. - Fixed some `basic_string` operations that used `npos` instead of `max_size()` when checking for maximum size overflow. - `condition_variable::wait_for(lock, relative_time, predicate)` would wait for the entire relative time if there was a spurious wake. Now it waits for only a single interval of the relative time. @@ -107,19 +108,19 @@ There are more standard library improvements in Visual Studio 2017 RTM. For a co - The unordered containers didn't swap their hash functions or predicates when the containers themselves were swapped. Now they do. - Many container swap operations are now marked **`noexcept`** (as our standard library never intends to throw an exception when detecting the non-`propagate_on_container_swap` non-equal-allocator undefined behavior condition). - Many `vector` operations are now marked **`noexcept`**. -- The standard library will now enforce matching allocator `value_type` (in C++17 mode) with an opt-out escape hatch. +- The standard library now enforces matching allocator `value_type` (in C++17 mode) with an opt-out escape hatch. - Fixed some conditions where self-range-insert into `basic_string` would scramble the strings contents. (Note: self-range-insert into vectors is still prohibited by the Standard.) - `basic_string::shrink_to_fit()` is no longer affected by the allocator's `propagate_on_container_swap`. - `std::decay` now handles abominable function types, that is, function types that are cv-qualified, ref-qualified, or both. - Changed include directives to use proper case sensitivity and forward slashes, improving portability. -- Fixed warning C4061 "enumerator '*enumerator*' in switch of enum '*enumeration*' is not explicitly handled by a case label". This warning is off-by-default and was fixed as an exception to the standard library's general policy for warnings. (The standard library is **`/W4`** clean, but doesn't attempt to be **`/Wall`** clean. Many off-by-default warnings are unusually noisy, and aren't intended to be used on a regular basis.) +- Fixed warning C4061 "enumerator '*enumerator*' in switch of enum '*enumeration*' is not explicitly handled by a case label." This warning is off-by-default and was fixed as an exception to the standard library's general policy for warnings. (The standard library is **`/W4`** clean, but doesn't attempt to be **`/Wall`** clean. Many off-by-default warnings are unusually noisy, and aren't intended to be used on a regular basis.) - Improved `std::list` debug checks. List iterators now check `operator->()`, and `list::unique()` now marks iterators as invalidated. - Fixed uses-allocator metaprogramming in `tuple`. ##### Visual Studio 2017 version 15.5 - `std::partition` now calls the predicate `N` times instead of `N + 1` times, as the standard requires. -- Attempts to avoid magic statics in version 15.3 have been repaired in version 15.5. +- Attempts to avoid magic statics in version 15.3 are repaired in version 15.5. - `std::atomic` no longer requires `T` to be default constructible. - Heap algorithms that take logarithmic time behave differently when iterator debugging is enabled. They no longer do a linear time assertion that the input is in fact a heap. - `__declspec(allocator)` is now guarded for C1XX only, to prevent warnings from Clang, which doesn't understand this declspec. @@ -136,18 +137,18 @@ For more information, see [Microsoft C/C++ language conformance](./visual-cpp-la ##### Visual Studio 2017 version 15.3 -- Several additional C++17 features have been implemented. For more information, see [Microsoft C++ language conformance table](cpp-conformance-improvements-2017.md#improvements_153). +- Several other C++17 features have been implemented. For more information, see [Microsoft C++ language conformance table](cpp-conformance-improvements-2017.md#improvements_153). - Implemented P0602R0 "variant and optional should propagate copy/move triviality". - The standard library now officially tolerates dynamic RTTI being disabled via the [/GR-](../build/reference/gr-enable-run-time-type-information.md) option. Both `dynamic_pointer_cast()` and `rethrow_if_nested()` inherently require **`dynamic_cast`**, so the standard library now marks them as `=delete` under **`/GR-`**. -- Even when dynamic RTTI has been disabled via **`/GR-`**, "static RTTI" in the form of `typeid(SomeType)` is still available, and powers several standard library components. The standard library now supports disabling this feature too, via **`/D_HAS_STATIC_RTTI=0`**. This flag also disables `std::any`, the `target()` and `target_type()` member functions of `std::function`, and the `get_deleter()` friend member function of `std::shared_ptr` and `std::weak_ptr`. +- Even when dynamic RTTI is disabled via **`/GR-`**, "static RTTI" in the form of `typeid(SomeType)` is still available, and powers several standard library components. The standard library now supports disabling this feature too, via **`/D_HAS_STATIC_RTTI=0`**. This flag also disables `std::any`, the `target()` and `target_type()` member functions of `std::function`, and the `get_deleter()` friend member function of `std::shared_ptr` and `std::weak_ptr`. - The standard library now uses C++14 **`constexpr`** unconditionally, instead of conditionally defined macros. - The standard library now uses alias templates internally. -- The standard library now uses **`nullptr`** internally, instead of `nullptr_t{}`. (Internal usage of NULL has been eradicated. Internal usage of 0-as-null is being cleaned up gradually.) +- The standard library now uses **`nullptr`** internally, instead of `nullptr_t{}`. (Internal usage of NULL is eradicated. Internal usage of 0-as-null is being cleaned up gradually.) - The standard library now uses `std::move()` internally, instead of stylistically misusing `std::forward()`. - Changed `static_assert(false, "message")` to `#error message`. This change improves compiler diagnostics because `#error` immediately stops compilation. - The standard library no longer marks functions as `__declspec(dllimport)`. Modern linker technology no longer requires it. - Extracted SFINAE to default template arguments, which reduced clutter compared to return types and function argument types. -- Debug checks in \ now use the standard library's usual machinery, instead of the internal function `_Rng_abort()`, which called `fputs()` to `stderr`. This function's implementation has been kept for binary compatibility. We'll remove it in the next binary-incompatible version of the standard library. +- Debug checks in \ now use the standard library's usual machinery, instead of the internal function `_Rng_abort()`, which called `fputs()` to `stderr`. This function's implementation is kept for binary compatibility. We'll remove it in the next binary-incompatible version of the standard library. ##### Visual Studio 2017 version 15.5 @@ -201,7 +202,7 @@ For more information, see [Microsoft C/C++ language conformance](./visual-cpp-la - Made `basic_string::find(char)` overloads only call `traits::find` once. Previously, it was implemented as a general string search for a string of length 1. - `basic_string::operator==` now checks the string's size before comparing the strings' contents. - Removed control coupling in `basic_string`, which was difficult for the compiler optimizer to analyze. For all short strings, calling `reserve` still has a nonzero cost to do nothing. -- `std::vector` has been overhauled for correctness and performance: aliasing during insert and emplace operations is now correctly handled as required by the Standard, the strong exception guarantee is now provided when required by the Standard via `move_if_noexcept()` and other logic, and insert and emplace do fewer element operations. +- `std::vector` was overhauled for correctness and performance: aliasing during insert and emplace operations is now correctly handled as required by the Standard, the strong exception guarantee is now provided when required by the Standard via `move_if_noexcept()` and other logic, and insert and emplace do fewer element operations. - The C++ standard library now avoids dereferencing null fancy pointers. - Improved `weak_ptr::lock()` performance. - To increase compiler throughput, C++ standard library headers now avoid including declarations for unnecessary compiler intrinsics. @@ -239,7 +240,7 @@ For more information, see [Microsoft C/C++ language conformance](./visual-cpp-la - `std::inplace_merge` now skips over elements that are already in position. - Constructing `std::random_device` no longer constructs and then destroys a `std::string`. - `std::equal` and `std::partition` had a jump-threading optimization pass that saves an iterator comparison. -- When `std::reverse` is passed pointers to trivially copyable `T`, it will now dispatch to a handwritten vectorized implementation. +- When `std::reverse` is passed pointers to trivially copyable `T`, it now dispatches to a handwritten vectorized implementation. - `std::fill`, `std::equal`, and `std::lexicographical_compare` were taught how to dispatch to `memset` and `memcmp` for `std::byte` and `gsl::byte` (and other char-like enums and enum classes). Since `std::copy` dispatches using `is_trivially_copyable`, it didn't need any changes. - The standard library no longer contains empty-braces destructors whose only behavior was to make types non-trivially-destructible. @@ -247,20 +248,20 @@ For more information, see [Microsoft C/C++ language conformance](./visual-cpp-la ### Open-source library support -**Vcpkg** is an open-source command-line tool that greatly simplifies the process of acquiring and building open-source C++ static libs and DLLS in Visual Studio. For more information, see [vcpkg](https://vcpkg.io/). +**Vcpkg** is an open-source command-line tool that greatly simplifies the process of acquiring and building open-source C++ static libs and DLLS in Visual Studio. For more information, see [vcpkg](/vcpkg/). ### CPPRest SDK 2.9.0 ##### Visual Studio 2017 version 15.5 -The CPPRestSDK, a cross-platform web API for C++, has been updated to version 2.9.0. For more information, see [CppRestSDK 2.9.0 is available on GitHub](https://devblogs.microsoft.com/cppblog/cpprestsdk-2-9-0-is-available-on-github/). +The CPPRestSDK, a cross-platform web API for C++, is updated to version 2.9.0. For more information, see [CppRestSDK 2.9.0 is available on GitHub](https://devblogs.microsoft.com/cppblog/cpprestsdk-2-9-0-is-available-on-github/). ### ATL ##### Visual Studio 2017 version 15.5 - Yet another set of name-lookup conformance fixes -- Existing move constructors and move assignment operators are now properly marked as non-throwing +- Existing move constructors and move assignment operators are now properly marked as nonthrowing - Unsuppress valid warning C4640 about thread safe init of local statics in atlstr.h - Thread-safe initialization of local statics was automatically turned off in the XP toolset when using ATL to build a DLL. Now it's not. You can add **`/Zc:threadSafeInit-`** in your Project settings if you don't want thread-safe initialization. @@ -270,7 +271,7 @@ The CPPRestSDK, a cross-platform web API for C++, has been updated to version 2. ## Visual Studio 2017 C++ IDE -- Configuration change performance is now better for C++ native projects and much better for C++/CLI projects. When a solution configuration is activated for the first time, it will now be faster, and all later activations of this solution configuration will be almost instantaneous. +- Configuration change performance is now better for C++ native projects and much better for C++/CLI projects. When a solution configuration is activated for the first time, it is faster, and all later activations of this solution configuration is almost instantaneous. ##### Visual Studio 2017 version 15.3 @@ -293,11 +294,11 @@ C++ now supports Ctrl+Click **Go To Definition**, making mouse navigation to def ## IntelliSense -- The new SQLite-based database engine is now being used by default. The new engine speeds up database operations like **Go To Definition** and **Find All References**. It significantly improves initial solution parse time. The setting has moved to **Tools > Options > Text Editor > C/C++ > Advanced**. (It was formerly under ...C/C++ > Experimental.) +- The new SQLite-based database engine is now being used by default. The new engine speeds up database operations like **Go To Definition** and **Find All References**. It significantly improves initial solution parse time. The setting moved to **Tools > Options > Text Editor > C/C++ > Advanced**. (It was formerly under ...C/C++ > Experimental.) -- We've improved IntelliSense performance on projects and files not using precompiled headers - an Automatic Precompiled Header will be created for headers in the current file. +- We've improved IntelliSense performance on projects and files not using precompiled headers - an Automatic Precompiled Header is created for headers in the current file. -- We've added error filtering and help for IntelliSense errors in the error list. Clicking on the error column now allows for filtering. Also, clicking on the specific errors or pressing F1 will launch an online search for the error message. +- We've added error filtering and help for IntelliSense errors in the error list. Clicking on the error column now allows for filtering. Also, clicking on the specific errors or pressing F1 launches an online search for the error message. ![Error List.](media/ErrorList1.png "Error List") @@ -309,7 +310,7 @@ C++ now supports Ctrl+Click **Go To Definition**, making mouse navigation to def - Added a new experimental Predictive IntelliSense feature that provides contextually aware filtering of what appears in the Member List. For more information, see [C++ IntelliSense Improvements - Predictive IntelliSense & Filtering](https://devblogs.microsoft.com/cppblog/c-intellisense-improvements-predictive-intellisense-filtering/). - **Find All References** (Shift+F12) now helps you get around easily, even in complex codebases. It provides advanced grouping, filtering, sorting, searching within results, and (for some languages) colorization, so you can get a clear understanding of your references. For C++, the new UI includes information about whether we're reading from or writing to a variable. -- The Dot-to-Arrow IntelliSense feature has been moved from experimental to advanced, and is now enabled by default. The editor features **Expand Scopes** and **Expand Precedence** have also been moved from experimental to advanced. +- The Dot-to-Arrow IntelliSense feature moved from experimental to advanced, and is now enabled by default. The editor features **Expand Scopes** and **Expand Precedence** moved from experimental to advanced. - The experimental refactoring features **Change Signature** and **Extract Function** are now available by default. - Added an experimental 'Faster project load' feature for C++ projects. The next time you open a C++ project it will load faster, and the time after that it will load *much* faster! - Some of these features are common to other languages, and some are specific to C++. For more information about these new features, see [Announcing Visual Studio "15" Preview 5](https://devblogs.microsoft.com/visualstudio/announcing-visual-studio-15-preview-5/). @@ -320,7 +321,7 @@ C++ now supports Ctrl+Click **Go To Definition**, making mouse navigation to def ## Non-MSBuild projects with Open Folder -Visual Studio 2017 introduces the **Open Folder** feature. It enables you to code, build, and debug in a folder containing source code without the need to create any solutions or projects. Now it's much simpler to get started with Visual Studio, even if your project isn't an MSBuild-based project. **Open Folder** gives you access to powerful code understanding, editing, building, and debugging capabilities. They're the same ones that Visual Studio already provides for MSBuild projects. For more information, see [Open Folder projects for C++](../build/open-folder-projects-cpp.md). +Visual Studio 2017 introduces the **Open Folder** feature. It enables you to code, build, and debug in a folder containing source code without the need to create any solutions or projects. Now it's simpler to get started with Visual Studio, even if your project isn't an MSBuild-based project. **Open Folder** gives you access to powerful code understanding, editing, building, and debugging capabilities. They're the same ones that Visual Studio already provides for MSBuild projects. For more information, see [Open Folder projects for C++](../build/open-folder-projects-cpp.md). - Improvements to the Open Folder experience. You can customize the experience through these .json files: - CppProperties.json to customize the IntelliSense and browsing experience. @@ -337,7 +338,7 @@ Visual Studio 2017 introduces the **Open Folder** feature. It enables you to cod Visual Studio 2017 introduces support for using CMake projects without converting to MSBuild project files (.vcxproj). For more information, see [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md). Opening CMake projects with **Open Folder** automatically configures the environment for C++ editing, building, and debugging. -- C++ IntelliSense works without the need to create a CppProperties.json file in the root folder. We've also added a new dropdown to allow users to easily switch between configurations provided by CMake and CppProperties.json files. +- C++ IntelliSense works without the need to create a CppProperties.json file in the root folder. We added a new dropdown to allow users to easily switch between configurations provided by CMake and CppProperties.json files. - Further configuration is supported via a CMakeSettings.json file that sits in the same folder as the CMakeLists.txt file. @@ -357,9 +358,9 @@ Visual Studio 2017 introduces support for using CMake projects without convertin ## Windows desktop development -We now provide a more granular installation experience for installing the original C++ workload. We have added selectable components that enable you to install just the tools that you need. The indicated installation sizes for the components listed in the installer UI are incorrect, and underestimate the total size. +We now provide a more granular installation experience for installing the original C++ workload. We added selectable components that enable you to install just the tools that you need. The indicated installation sizes for the components listed in the installer UI are incorrect, and underestimate the total size. -To successfully create Win32 projects in the C++ desktop workload, you must install both a toolset and a Windows SDK. Install the recommended (selected) components **VC++ 2017 v141 toolset (x86, x64)** and **Windows 10 SDK (10.0.nnnnn)** to make sure it works. If the necessary tools aren't installed, projects won't be created successfully, and the wizard will stop responding. +To successfully create Win32 projects in the C++ desktop workload, you must install both a toolset and a Windows SDK. Install the recommended (selected) components **VC++ 2017 v141 toolset (x86, x64)** and **Windows 10 SDK (10.0.nnnnn)** to make sure it works. If the necessary tools aren't installed, projects won't be created successfully, and the wizard stops responding. ##### Visual Studio 2017 version 15.5 @@ -371,11 +372,11 @@ The popular extension [Visual C++ for Linux Development](https://marketplace.vis ##### Visual Studio 2017 version 15.2 -Improvements have been made in cross-platform code sharing and type visualization. For more information, see [Linux C++ improvements for cross-platform code sharing and type visualization](https://devblogs.microsoft.com/cppblog/linux-cross-platform-and-type-visualization/). +Improvements were made in cross-platform code sharing and type visualization. For more information, see [Linux C++ improvements for cross-platform code sharing and type visualization](https://devblogs.microsoft.com/cppblog/linux-cross-platform-and-type-visualization/). ##### Visual Studio 2017 version 15.5 -- The Linux workload has added support for **rsync** as an alternative to **sftp** for synchronizing files to remote Linux machines. +- The Linux workload added support for **rsync** as an alternative to **sftp** for synchronizing files to remote Linux machines. - Support is added for cross compilation targeting ARM microcontrollers. To enable it in the installation, choose the **Linux development with C++** workload and select the option for **Embedded and IoT Development**. This option adds the ARM GCC cross compilation tools and Make to your installation. For more information, see [ARM GCC Cross Compilation in Visual Studio](https://devblogs.microsoft.com/cppblog/arm-gcc-cross-compilation-in-visual-studio/). - Support added for CMake. You can now work on your existing CMake code base without having to convert it to a Visual Studio project. For more information, see [Configure a Linux CMake Project](../linux/cmake-linux-project.md). - Support added for running remote tasks. This capability allows you to run any command on a remote system that is defined in Visual Studio's Connection Manager. Remote tasks also provide the capability to copy files to the remote system. @@ -419,7 +420,7 @@ The Clang/C2 toolset that ships with Visual Studio 2017 now supports the **`/big The C++ Core Checkers for enforcing the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) are now distributed with Visual Studio. Enable the checkers in the **Code Analysis Extensions** page in the project's property pages. The extensions are then included when you run code analysis. For more information, see [Using the C++ Core Guidelines checkers](../code-quality/using-the-cpp-core-guidelines-checkers.md). -![Screenshot of the Property Pages dialog box showing Configuration Properties > Code Analysis > General selected and a number of Core Checks listed in teh Run this rule set section.](media/CppCoreCheck.png "CppCoreCheck properties page") +![Screenshot of the Property Pages dialog box showing Configuration Properties > Code Analysis > General selected and a number of Core Checks listed in the Run this rule set section.](media/CppCoreCheck.png "CppCoreCheck properties page") ##### Visual Studio 2017 version 15.3 @@ -429,7 +430,7 @@ The C++ Core Checkers for enforcing the [C++ Core Guidelines](https://github.com - New C++ Core Guidelines checks cover smart pointer correctness, correct use of global initializers, and flagging uses of constructs like **`goto`** and bad casts. -- Some warning numbers you may find in 15.3 are no longer available in 15.5. These warnings were replaced with more specific checks. +- Some warning numbers you might find in 15.3 are no longer available in 15.5. These warnings were replaced with more specific checks. ##### Visual Studio 2017 version 15.6 @@ -438,7 +439,7 @@ The C++ Core Checkers for enforcing the [C++ Core Guidelines](https://github.com ##### Visual Studio 2017 version 15.7 - Support added for [`/analyze:ruleset`](../build/reference/analyze-code-analysis.md), which lets you specify the code analysis rules to run. -- Support added for additional C++ Core Guidelines rules. For more information, see [Using the C++ Core Guidelines checkers](../code-quality/using-the-cpp-core-guidelines-checkers.md). +- Support added for more C++ Core Guidelines rules. For more information, see [Using the C++ Core Guidelines checkers](../code-quality/using-the-cpp-core-guidelines-checkers.md). ## Unit testing in Visual Studio 2017 @@ -479,7 +480,7 @@ Visual Studio Graphics Diagnostics tools: You can use them to record and analyze You can capture frames with full call stack capturing enabled. That lets you quickly deduce the context of each change event, and inspect it within your Visual Studio project. Set the full stack capture option in the Visual Studio **Tools > Options** dialog under **Graphics Diagnostics**. -- **API Statistics:** View a high-level summary of API usage in your frame. It's handy for discovering calls you may not realize you're making at all, or calls you're making too often. This window is available via **View > API Statistics** in Visual Studio Graphics Analyzer. +- **API Statistics:** View a high-level summary of API usage in your frame. It's handy for discovering calls you might not realize you're making at all, or calls you're making too often. This window is available via **View > API Statistics** in Visual Studio Graphics Analyzer. ![API stats.](media/api-stats.png) @@ -495,10 +496,10 @@ Visual Studio Graphics Diagnostics tools: You can use them to record and analyze ![Frame analysis.](media/frame-analysis.png) -- **GPU Usage Improvements:** Open traces can be taken via the Visual Studio GPU Usage profiler with either GPU View or the Windows Performance Analyzer (WPA) tool for more detailed analysis. If you have the Windows Performance Toolkit installed, there are two hyperlinks: one for WPA and another for GPU View, at the bottom right of the session overview. +- **GPU Usage Improvements:** Open traces can be taken via the Visual Studio GPU Usage profiler with either GPUView or the Windows Performance Analyzer (WPA) tool for more detailed analysis. If you have the Windows Performance Toolkit installed, there are two hyperlinks: one for WPA and another for GPUView, at the bottom right of the session overview. ![GPU usage.](media/gpu-usage.png) - Traces you open in GPU View via this link support synchronized VS and GPU View timeline zooming and panning. A checkbox in VS controls whether synchronization is enabled or not. + Traces you open in GPUView via this link support synchronized VS and GPUView timeline zooming and panning. A checkbox in VS controls whether synchronization is enabled or not. - ![GPU View.](media/gpu-view.png) + ![GPUView.](media/gpu-view.png) diff --git a/docs/overview/what-s-new-for-cpp-2019.md b/docs/overview/what-s-new-for-cpp-2019.md index 18df33e314..7889048806 100644 --- a/docs/overview/what-s-new-for-cpp-2019.md +++ b/docs/overview/what-s-new-for-cpp-2019.md @@ -2,14 +2,15 @@ title: "What's new for C++ in Visual Studio 2019" description: "The new features and fixes in the Microsoft C/C++ compiler and tools in Visual Studio 2019." ms.date: 10/22/2021 -ms.technology: "cpp-ide" +ms.service: "visual-cpp" +ms.subservice: "ide" ms.custom: intro-whats-new --- # What's new for C++ in Visual Studio 2019 Visual Studio 2019 brings many updates and fixes to the Microsoft C++ environment. We've fixed many bugs and issues in the compiler and tools. Many of these issues were submitted by customers through the [Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio?view=vs-2019&preserve-view=true) and [Provide a Suggestion](https://aka.ms/feedback/suggest?space=62) options under **Send Feedback**. Thank you for reporting bugs! -For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2019](/visualstudio/ide/whats-new-visual-studio-2019). For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For information about what's new in the C++ docs, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). +For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2019](/visualstudio/ide/whats-new-visual-studio-2019). For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For more information, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). ## What's new for C++ in Visual Studio version 16.11 @@ -25,7 +26,7 @@ For a summary of new features and bug fixes in Visual Studio version 16.11, see For a summary of new features and bug fixes in Visual Studio version 16.10, see [What's New in Visual Studio 2019 version 16.10](/visualstudio/releases/2019/release-notes-v16.10). -- All C++20 features are now available under [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). While MSVC’s implementation of the C++20 standards (as currently published by ISO) is feature complete, some key C++20 library features are expected to be amended by upcoming Defect Reports (ISO C++20 bug fixes) that may change them in an ABI-incompatible way. Please see [Microsoft/STL Issue #1814](https://github.com/microsoft/STL/issues/1814) for more details. +- All C++20 features are now available under [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). While MSVC's implementation of the C++20 standards (as currently published by ISO) is feature complete, some key C++20 library features are expected to be amended by upcoming Defect Reports (ISO C++20 bug fixes) that may change them in an ABI-incompatible way. Please see [Microsoft/STL Issue #1814](https://github.com/microsoft/STL/issues/1814) for more details. - C++20 immediate functions & constinit support added in 16.10 - The final pieces of ``: new clocks, leap seconds, time zones, and parsing @@ -309,7 +310,7 @@ The new IntelliCode features (Custom Models, C++ support, and EditorConfig infer #### Quick Info improvements -- The Quick Info tooltip now respects the semantic colorization of your editor. It also has a new **Search Online** link that will search for online docs to learn more about the hovered code construct. The link provided by Quick Info for red-squiggled code will search for the error online. That way you don't need to retype the message into your browser. For more information, see [Quick Info Improvements in Visual Studio 2019: Colorization and Search Online](https://devblogs.microsoft.com/cppblog/quick-info-improvements-in-visual-studio-2019-colorization-and-search-online/). +- The Quick Info tooltip now respects the semantic colorization of your editor. It also has a new **Search Online** link that will search online documentation for information about the hovered code construct. The link provided by Quick Info for red-squiggled code will search for the error online. That way you don't need to retype the message into your browser. For more information, see [Quick Info Improvements in Visual Studio 2019: Colorization and Search Online](https://devblogs.microsoft.com/cppblog/quick-info-improvements-in-visual-studio-2019-colorization-and-search-online/). #### General improvements @@ -504,7 +505,7 @@ IncrediBuild is included as an optional component in the **Desktop development w - MFC class from ActiveX control - MFC class from Type Lib. - Sample code for these technologies is archived at Microsoft Docs and the VCSamples GitHub repository. + Sample code for these technologies is archived in Microsoft Learn and the VCSamples GitHub repository. - The Windows 8.1 Software Development Kit (SDK) is no longer available in the Visual Studio installer. We recommend you upgrade your C++ projects to the latest Windows SDK. If you have a hard dependency on 8.1, you can download it from the Windows SDK archive. diff --git a/docs/overview/what-s-new-for-visual-cpp-in-visual-studio.md b/docs/overview/what-s-new-for-visual-cpp-in-visual-studio.md index 9dcf9edd86..c603b8f916 100644 --- a/docs/overview/what-s-new-for-visual-cpp-in-visual-studio.md +++ b/docs/overview/what-s-new-for-visual-cpp-in-visual-studio.md @@ -1,29 +1,578 @@ --- title: "What's new for C++ in Visual Studio" description: "The new features and fixes in the Microsoft C/C++ compiler and tools in Visual Studio." -ms.date: 11/05/2021 -ms.technology: "cpp-ide" +ms.date: 05/13/2025 +ms.service: "visual-cpp" +ms.subservice: "ide" ms.custom: intro-whats-new +ai-usage: ai-assisted --- + # What's new for C++ in Visual Studio 2022 -Visual Studio 2022 brings many updates and fixes to the Microsoft C++ environment. We've added features and fixed many bugs and issues in the compiler and tools. The Visual Studio IDE also offers significant improvements in performance and productivity, and now runs natively as a 64-bit application. For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2022](/visualstudio/ide/whats-new-visual-studio-2022?view=vs-2022&preserve-view=true). For information about what's new in the C++ docs, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). +Visual Studio 2022 brings many updates and fixes to the Microsoft C++ compiler and tools. The Visual Studio IDE also offers significant improvements in performance and productivity, and now runs natively as a 64-bit application. + +- For more information on what's new in all of Visual Studio, see [What's new in Visual Studio 2022](/visualstudio/ide/whats-new-visual-studio-2022). +- For information about version build dates, see [Visual Studio 2022 Release History](/visualstudio/releases/2022/release-history). + +## What's new for C++ in Visual Studio version 17.14 + +*Released May 2025* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.14](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-14/) | +| Standard Library (STL) merged C++26 and C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.14](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1714) | +| New features in the IDE |[Visual Studio 2022 version 17.14 Release Notes](/visualstudio/releases/2022/release-notes) | +| C++ language updates | [C++ Language Updates in MSVC in Visual Studio 2022 17.14](https://devblogs.microsoft.com/cppblog/c-language-updates-in-msvc-in-visual-studio-2022-17-14/) | +| C++ language conformance improvements | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.14](cpp-conformance-improvements.md#improvements_1714) | + +A quick highlight of some of the new features: + +- C++ Dynamic Debugging allows you to debug optimized code without impacting performance. For more information, see [C++ Dynamic Debugging](/visualstudio/debugger/cpp-dynamic-debugging). +- Implemented C++23 features (requires `/std:c++latest` or `/std:c++23preview`): + - [`static operator()`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1169r4.html) + - [`static operator[]`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2589r1.pdf) + - [`if consteval`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1938r3.html). Allows you to run different code depending on whether the statement is executed at compile time or run time. +- Automatically generate documentation comments with GitHub Copilot. For more information, see [Introducing automatic documentation comment generation in Visual Studio](https://devblogs.microsoft.com/visualstudio/introducing-automatic-documentation-comment-generation-in-visual-studio/). +- Use the Model Picker in Visual Studio to select your AI model for GitHub Copilot. For more information, see [Changing the AI model for Copilot Chat](https://docs.github.com/en/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat). This screenshot shows the Model Picker at the bottom of the GitHub Copilot chat window: + :::image type="complex" source="./media/model-picker.png" alt-text="A screenshot of the GitHub Copilot chat window with the Model Picker dropdown highlighted."::: + The dropdown for the Model Picker is open. The options include: GPT-4o, o3-mini, Claude 3.7 Sonnet Thinking, and others. + :::image-end::: +- Unreal Engine integration improvements: + - The Visual Studio C++ debugger now supports Unreal Engine Blueprints. + - Commands for building files, modules, and plugins are available natively in Visual Studio. +- New compiler flag [/forceInterlockedFunctions](../build/reference/force-interlocked-functions.md) dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 Large System Extension (LSE) atomic instructions based on CPU capability at runtime. +- Added support for IntelliSense-based completions and quick info for CMake modules in Visual Studio. You can view all available CMake modules and when you hover over a referenced CMake module, IntelliSense provides more info about the selected module: + :::image type="complex" source="./media/cmake-module-intellisense.png" alt-text="A screenshot of intellisense explaining C Make Print Helpers."::: + The screenshot is of an edit in the C Make Lists .txt file. The cursor is on include ( CMakePrintHelpers ). Intellisense says: Convenience functions for printing properties and variables, useful for debugging. + :::image-end::: + + When you start typing a CMake module name in your `CMakeLists.txt` or other CMake script files, IntelliSense provides a list of available modules to choose from: + :::image type="complex" source="./media/cmake-intellisense.png" alt-text="A screenshot of intellisense for a include statement."::: + The screenshot is of an edit in the C Make Lists .txt file. The cursor is on include ( C Make. The Intellisense dropdown contains entries for C Make Add Fortran Subdirectory, C Make Dependent Option, and more. + :::image-end::: +- Guidelines Support Library (GSL) 4.2.0: This release includes performance improvements for `gsl::span`, new features, and better alignment with C++ standards. For more information, see [Announcing Guidelines Support Library v4.2.0](https://devblogs.microsoft.com/cppblog/announcing-guidelines-support-library-v4-2-0/). + +## What's new for C++ in Visual Studio version 17.13 + +*Released February 2025* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.13](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-13/) | +| Standard Library (STL) C++26 and C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.13](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1713) | +| New features in the IDE |[Visual Studio 2022 version 17.13 Release Notes](/visualstudio/releases/2022/release-notes) | +| C++ language updates | [MSVC compiler updates in Visual Studio 2022 17.13](https://devblogs.microsoft.com/cppblog/msvc-compiler-updates-in-visual-studio-2022-version-17-13/) | +| C++ language conformance improvements | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.13](cpp-conformance-improvements.md#improvements_1713) | + +A quick highlight of some new features: + +- **C++ language enhancements** + + - Try out C++23 preview features by setting the C++ Language Standard to `/std:c++23preview`. This setting enables the latest C++23 features and bug fixes. For more information, see [/std (Specify Language Standard Version)](../build/reference/std-specify-language-standard-version.md#stdc23preview). + - Support for C++23’s `size_t` literal suffix, which helps avoid truncations or signed comparison mismatches--especially when writing loops. For example: + ```cpp + // Infinite loop if v.size > max unsigned int + for (auto i = 0u; i < v.size(); ++i) + { + ... + } + + // Fixed because of uz literal + for (auto i = 0uz; i < v.size(); ++i) + { + ... + } + ``` + + - Support for vector lengths for code generation on x86 and x64. For more information, see [/vlen](../build/reference/vlen.md). + - Support for Intel Advanced Vector Extensions 10 version 1. For more information about `/arch:AVX10.1`, see [/arch (x64)](../build/reference/arch-x64.md). + +- **Standard Library enhancements** + + - Standard library support for couroutines. In this example from [P2502R2](https://wg21.link/p2502r2), the `fib` function is a coroutine. When the `co_yield` statement is executed, `fib` is suspended and the value is returned to the caller. You can resume the `fib` coroutine later to produce more values without requiring any manual state handling: + + ```cpp + std::generator fib() + { + auto a = 0, b = 1; + + while (true) + { + co_yield std::exchange(a, std::exchange(b, a + b)); + } + } + + int answer_to_the_universe() + { + auto rng = fib() | std::views::drop(6) | std::views::take(3); + return std::ranges::fold_left(std::move(range), 0, std::plus{}); + } + ``` + + - Moved `system_clock`, `high_resolution_clock`, and `chrono_literals` from a commonly included internal header to ``. If you see compiler errors that types like `system_clock` or user-defined literals like `1729ms` aren't recognized, include ``. + - Improved the vectorized implementations of `bitset` constructors from strings, `basic_string::find_last_of()`, `remove()`, `ranges::remove`, and the `minmax_element()` and `minmax()` algorithm families. + - Added vectorized implementations of: + - `find_end()` and `ranges::find_end` for 1-byte and 2-byte elements. + - `basic_string::find()` and `basic_string::rfind()` for a substring. + - `basic_string::rfind()` for a single character. + - Merged C++23 Defect Reports: + - [P3107R5](https://wg21.link/P3107R5) Permit an efficient implementation of ``. + - [P3235R3](https://wg21.link/P3235R3) `std::print` More types faster with less memory. + +- **GitHub Copilot** + + - GitHub Copilot Free is now available. Get 2,000 code completions and 50 chat requests per month at no cost. + - GitHub Copilot code completions provide autocomplete suggestions inline as you code. To enhance the experience of C++ developers, GitHub Copilot includes other relevant files as context. This reduces errors while offering more relevant and accurate suggestions. + - You can now request a code review from GitHub Copilot from the Git Changes window: + :::image type="complex" source="./media/vs2022-copilot-git-changes-review.png" alt-text="A screenshot of the Git Changes window with the GitHub Copilot Review button highlighted."::: + The Git Changes window is open with the GitHub Copilot Review button highlighted. + :::image-end::: + + GitHub Copilot looks for potential issues and creates comments for them: + + :::image type="complex" source="./media/vs2022-copilot-comment-example.png" alt-text="A screenshot of the GitHub Copilot explaining an issue."::: + GitHub Copilot found an issue with the line if ( is_enabled_) new_site.disable(). It says it may be a mistake and should likely be if ( is_enabled_) new_site.enable() because the intention seem to be enabling the new site if the breakpoint is enabled. + :::image-end::: + + To use this feature, ensure the following are turned on: + - **Tools**>**Options**> **Preview Features** > **Pull Request Comments** + - **Tools** >**Options** > **GitHub** > **Copilot** > **Source Control Integration** > **Enable Git preview features**. + + - GitHub Copilot Edits is a new feature that can make changes across multiple files in your project. To start a new Edits session, click **Create new edit session** at the top of the GitHub Copilot Chat window: + + :::image type="content" source="./media/vs2022-copilot-edit-session.png" alt-text="A screenshot of the GitHub Copilot Chat window. The Create new edit session button is highlighted."::: + + Describe the changes you want to make and Copilot suggests relevant edits. You can preview the edits one-by-one and accept the ones you want or make corrections: + + :::image type="complex" source="./media/vs2022-copilot-edit-session-example.png" alt-text="A screenshot of the GitHub Copilot Chat window displaying the files it edited."::: + GitHub Copilot is displaying a summary of the changes it made, such as 1. Create a new subclass range_breakpoint in include/libsdb/breakpoint.hpp" and 2. Implement the range_breakpoint class in src/breakpoint.cpp. An option to accept the changes is displayed. + :::image-end::: + + For more information, see [Iterate across multiple files more efficiently with GitHub Copilot Edits](https://devblogs.microsoft.com/visualstudio/iterate-across-multiple-files-more-efficiently-with-github-copilot-edits-preview/). + +- **CMake** + - Now supports CMake Presets v9. New macro expansions in a preset's include field. For more information, see [Macro expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion) in the official CMake documentation. + +## What's new for C++ in Visual Studio version 17.12 + +*Released November 2024* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.12](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-12/) | +| Standard Library (STL) merged C++26 and C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.12](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1712) | +| New features in the Visual Studio 17.12 IDE |[Visual Studio 2022 version 17.12 Release Notes](/visualstudio/releases/2022/release-notes) | +| C++ language conformance improvements in Visual Studio 2022 17.12 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.12](cpp-conformance-improvements.md#improvements_1712) | + +A quick highlight of some of the new features: + +- **Standard Library Enhancements** + - C++23 Formatting ranges ([P2286R8](https://wg21.link/P2286R8)) implementation complete. Added formatters for the container adaptors `stack`, `queue`, and `priority_queue`. + - Added multidimensional subscript operators, which also support ``. For example: `print("m[{}, {}]: '{}'; ", i, j, m[i, j])`. +- **Game development in C++** + - Directly open Unreal Engine projects in Visual Studio without having to generate a Visual Studio solution file wrapping the Unreal Engine project. For more information, see [Work with Unreal Engine projects in Visual Studio](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-quickstart). + - You can specify the command line arguments to pass when debugging directly from the toolbar. For more information, see [Set command line arguments for Unreal Engine projects](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-quickstart#set-command-line-arguments). + :::image type="content" source="./media/command-line-argument-dropdown.png" alt-text="A screenshot of the command-line argument dropdown. It contains one command line argument: -graphicsadaptor=0."::: +- **Build Insights** + - You can run Build Insights on selected files. Select the files you want in the **Solution Explorer**, right-click, and choose **Run Build Insights on Selected Files**: + :::image type="content" source="./media/build-insights-run-on-selected-files.png" alt-text="A screenshot of files in the Solution Explorer. The context menu is open and the option to Run Build Insights on Selected Files is highlighted."::: + - You can filter Build Insights results by project. Click the filter button on the filter column header and select the projects you want to see results for: + :::image type="content" source="./media/build-insights-filter-by-project.png" alt-text="A screenshot of the Build Insights window with the Included Files tab open. The filter button was selected and a list of projects appears. Checkboxes next to Two projects are checked."::: + - Clicking the question mark icon in the Build Insights window to see a short description for the tabs in the Build Insights window, and a link to the documentation for a detailed explanation: + :::image type="content" source="./media/build-insights-view-explanations.png" alt-text="A screenshot of the Build Insights window with the view explanations button (a question mark in a circle) highlighted."::: +- **GitHub Copilot** + - You can click **Ask Copilot** next to the value of a variable to get AI-driven insights into what led to its current state. For example, the following program has an off-by-one error in its loop condition: + :::image type="complex" source="./media/copilot-smart-variable-inspection.png" alt-text="A screenshot of the Autos window. The variable named it is NULL. The Ask Copilot icon next to it is highlighted."::: + The code that caused this problem is: for (auto it = h.animals_.begin(); it <= h.animals_.end(); it++). + :::image-end::: + If you click Ask Copilot icon for the `it` variable, it tells you why it is ``: + :::image type="complex" source="./media/copilot-smart-variable-explanation.png" alt-text="A screenshot of a GitHub Copilot window."::: + This error is inside a function defined as int calculate_number_of_cats(const house& h). The GitHub Copilot message says: "The value of the expression it is NULL, which means that the iterator is not pointing to any valid element in the vector animals_. In the context of your program, it is supposed to iterate over the animals_ vector in the house object to count the number of cat objects. Why it is null. Based on the locals and call stack context: the house object h has an empty animals_ vector (size=0). The loop condition it <= h.animals_.end() is incorrect. It should be it != h.animals_.end()." + :::image-end::: + - You can click **Ask Copilot** about errors in the Visual Studio **Error List** to get help on the error and a suggested fix. For example: + :::image type="complex" source="./media/copilot-fix-my-code.png" alt-text="A screenshot of the Error List window."::: + The Ask Copilot icon is highlighted next to an error that unique_ptr is attempting to reference a deleted function. + :::image-end::: + If you click Ask Copilot, it tells you about the error: + :::image type="complex" source="./media/copilot-fix-my-code-suggestion.png" alt-text="A screenshot of the GitHub Copilot explanation for the error."::: + The Copilot message says: "The error occurs because the range-based for loop was attempting to copy std::unique_ptr objects, which is not allowed since std::unique_ptr cannot be copied. To fix this, I changed the loop to use a reference to avoid copying the std::unique_ptr objects. This way, the loop iterates over references to the std::unique_ptr objects, which is allowed." + :::image-end::: +- **Debugging** + - New debug visualizers for `mutex`, `recursive_mutex`, and `move_iterator`. + - The debugger now displays return values inline: + :::image type="content" source="./media/debugger-inline-return-values.png" alt-text="A screenshot of a tooltip showing the value 8.25. It's the result of the expression following the return statement that was stepped over."::: + +## What's new for C++ in Visual Studio version 17.11 + +*Released August 2024* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.11](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-11/) | +| Standard Library (STL) merged C++26 and C++23 features, C++20 defect reports, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.11](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1711) | +| New features in the Visual Studio 17.11 IDE |[Visual Studio 2022 version 17.11 Release Notes](/visualstudio/releases/2022/release-notes) | +| C++ language conformance improvements in Visual Studio 2022 17.11 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.11](cpp-conformance-improvements.md#improvements_1711) | + +A partial list of new features: + +- **Standard Library Enhancements** + - The formatted output implementation now includes `std::range_formatter` and formatters for `std::pair` and `std::tuple`. + - Added support for `std::println()` with no arguments. This prints a blank line as proposed in [P3142R0](https://wg21.link/P3142R0). + - Improved vectorization for several algorithms including `replace_copy()`, `replace_copy_if()`, `ranges::replace_copy`, `ranges::replace_copy_if`, `find_first_of()` and `ranges::find_first_of`, for 8-bit and 16-bit elements, `mismatch()`, `ranges::mismatch`, `count()`, `ranges::count`, `find()`, `ranges::find`, `ranges::find_last`, and `ranges::iota`. + +- **Game development in C++** + - You can now add common Unreal Engine class templates, modules, and plugins from within Visual Studio. For more information, see [Add Unreal Engine classes, modules, and plugins in Visual Studio](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-add-class-module-plugin). + - The new Unreal Engine toolbar provides quick access to Unreal Engine related actions from within Visual Studio. The toolbar allows you to quickly attach to Unreal Engine processes, rescan the Blueprints cache, quickly access the Unreal Engine Log, and provides quick access to the Unreal Engine Configuration Page for Visual Studio. For more information, see [Unreal Engine Toolbar](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-quickstart#unreal-engine-toolbar). + - You can now filter trace results by project. Also, results in each row show the relative path and file name instead of the full path. Results grouping in the **Included Files** view is also improved: + :::image type="complex" source="./media/include-diagnostics-improved.png" alt-text="A screenshot of the improved Included Files diagnostics results."::: + The Included Files view has a new column for the project. The Project column is selected and projects such as (Select All), CompilerIdC, OpenAL, common, and so on, are selected. The included files are listed by relative path and file name and grouped together. + :::image-end::: +- **CMake debugging** + - You can now debug your CMake scripts and `CMakeLists.txt` files in the Visual Studio debugger for CMake projects that target Linux via Windows Subsystem for Linux (WSL) or SSH. To start a CMake debugging session in Visual Studio, set a breakpoint in your `CMakeLists.txt` file and then navigate to **Project** > **Configure Cache with CMake Debugging**. +- **GitHub Copilot** + - When you hover over symbols in the code editor, click the Copilot **Tell me more** button in the Quick Info dialog to learn more about a given symbol: + :::image type="complex" source="./media/github-copilot-quick-info.png" alt-text="A screenshot of the Quick Info window."::: + The Quick Info window is shown above a function. The Tell me more link is highlighted. + :::image-end::: + - GitHub Copilot can generate naming suggestions for your identifiers (variables, methods, or classes) based on how your identifier is used and the style of your code. + :::image type="complex" source="./media/copilot-rename.png" alt-text="A screenshot of the GitHub Copilot Rename dialog."::: + The Rename dialog has a New name field with a dropdown list that shows these choices: text_color, font_color, display_color, console_color, and menu_text_color. + :::image-end::: + You need an active [GitHub Copilot subscription](https://visualstudio.microsoft.com/github-copilot/). Right-click the variable you wish to rename, and choose **Rename** (`Ctrl+R`, `Ctrl+R`). Select the GitHub Copilot sparkle icon to generate naming suggestions. + +- **Debugging** + - Conditional breakpoints in C++ are faster. + +- **Diagnostics improvements** + - Improved diagnostics when calling `std::get` on a `std::tuple` that has multiple instances of `T` in its template arguments. MSVC used to report:\ + `error C2338: static_assert failed: 'duplicate type T in get(tuple)'`.\ + Now it reports:\ + `error C2338: static_assert failed: 'get(tuple&) requires T to occur exactly once in Types.(N4971 [tuple.elemm]/5)'` + - Improved diagnostics when `std::ranges::to` is unable to construct the requested result. MSVC used to report:\ + `error C2338: static_assert failed: 'the program is ill-formed per N4950 [range.utility.conv.to]/2.3'`\ + Now it reports:\ + `error C2338: static_assert failed: 'ranges::to requires the result to be constructible from the source range, either by using a suitable constructor, or by inserting each element of the range into the default-constructed object. (N4981 [range.utility.conv.to]/2.1.5)'` + +## What's new for C++ in Visual Studio version 17.10 + +*Released May 2024* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's new for C++ Developers in Visual Studio 2022 17.10](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-10/) | +| Standard Library (STL) merged C++26 and C++23 features, C++20 defect reports, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.10](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1710) | +| New features in the Visual Studio 17.10 IDE |[Visual Studio 2022 version 17.10 Release Notes](/visualstudio/releases/2022/release-notes) | +| C++ language conformance improvements in Visual Studio 2022 17.10 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.10](cpp-conformance-improvements.md#improvements_1710) | + +A partial list of new features: + +- **MSVC Toolset Update**: The MSVC toolset version is updated from 19.39 to 19.40. This may affect projects that have version assumptions. For more information about some ways in which this affects projects that assume that MSVC versions are all 19.3X for Visual Studio 2022 releases, see [MSVC Toolset Minor Version Number 14.40 in VS 2022 v17.10](https://devblogs.microsoft.com/cppblog/msvc-toolset-minor-version-number-14-40-in-vs-2022-v17-10/). +- **Standard Library Enhancements**: The standard library added support for [P2510R3 Formatting Pointers](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2510r3.pdf), which brings the set of format specifiers for pointers when using `std::format` more in line with those that already exist for integers. Improved the vectorized implementations of `std::min_element`, `std::ranges::min`, and friends. +- **Build Insights**: Now provides template instantiation information. See [Templates View for Build Insights in Visual Studio](https://devblogs.microsoft.com/cppblog/templates-view-for-build-insights-in-visual-studio-2/) or the [Pure Virtual C++ - Templates view for Build Insights in Visual Studio](https://youtu.be/68pOEQ5YA5s) recording. +- **Unreal Engine Plugin**: There's a new opt-in feature for the Unreal Engine Plugin to run in the background, reducing startup costs. This is an opt-in feature that is activated via **Tools** > **Options** > **Unreal Engine**. +- **New features for Linux**: See [New Linux Development Features in Visual Studio](https://youtu.be/jZTMRvm8AwY). +- **CMake Targets**: You can now pin targets in the **CMake Targets View**. +- **Connection Manager UX**: The user experience provides a more seamless experience when connecting to remote systems. For more information, see [Usability Improvements in the Visual Studio Connection Manager](https://devblogs.microsoft.com/cppblog/usability-improvements-in-the-visual-studio-connection-manager/). +- **Pull request comments**: You can now view GitHub and Azure DevOps comments directly in your working file. Enable the feature flag, **Pull Request Comments** in **Options** > **Environment** > **Preview Features** and checkout the pull request branch to get started. +- **AI-Generated Content**: GitHub Copilot can now draft pull request descriptions. Requires an active GitHub Copilot subscription. Try it out by clicking the **Add AI Generated Pull Request Description** sparkle pen icon within the **Create a Pull Request** window. +- **Image Preview**: Hover over an image path to see a preview with size details. The size is capped to 500 px wide and high. + :::image type="complex" source="media/hover-preview.png" alt-text="Screenshot of hover preview."::: + The mouse is hovering over the line std::filesystem::path vs_logo_path = "../images/vs_logo.png". Underneath appears a preview of the Visual Studio logo and the information that it's 251 x 500 pixels and 13.65 KB in size. + :::image-end::: +- **Breakpoint/Tracepoint Creation**: You can now create conditional breakpoints or tracepoints directly from expressions in the source code from the right-click menu. This works on property or field names and values from autos, locals, watch windows, or DataTips. +- **Attach to Process Dialog**: The functionality provided by the Attach to Process dialog is more user-friendly. You can now easily switch between tree and list views, organize processes better with collapsible sections, and select code types with a simplified combobox. Also, the "Select/Track Window" feature is now easier to use, allowing two-way tracking: selecting a process highlights its window, and clicking on a window selects its process. +- **GitHub Copilot Integration**: GitHub Copilot and Copilot Chat extensions are now unified and now ship directly in Visual Studio. To install it, install the **GitHub Copilot** component in the **Visual Studio Installer**: + :::image type="complex" source="media/github-copilot-install-option.png" alt-text="Screenshot of the Visual Studio Installer GitHub Copilot installation option." lightbox="media/github-copilot-install-option-expanded.png"::: + The Visual Studio installer is open to the Workloads tab. In the installation details pane, GitHub Copilot is shown as selected. + :::image-end::: + The GitHub Copilot interface is in the top-right corner of Visual Studio. To use it, you need an active GitHub Copilot subscription. + :::image type="complex" source="media/unified-github-copilot-button.png" alt-text="Screenshot of GitHub Copilot button."::: + The GitHub Copilot button is shown in the top-right corner of Visual Studio. It has options to open a chat window, GitHub Copilot settings, learn more, and manage copilot subscription. + :::image-end::: + +## What's new for C++ in Visual Studio version 17.9 + +*Released Feb 2024* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's new for C++ Developers in Visual Studio 2022 17.9](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2022-17-9/) | +| Standard Library (STL) merged C++23 features, performance improvements, enhanced behavior, Language Working Group (LWG) issue resolutions, and fixed bugs | [STL Changelog 17.9](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-179) | +| New features in the Visual Studio 17.9 IDE |[Visual Studio 2022 version 17.9 Release Notes](/visualstudio/releases/2022/release-notes-v17.9) | +| C++ language conformance improvements in Visual Studio 2022 17.9 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_179) | +| Summary of C++ backend updates | [MSVC Backend updates since Visual Studio 2022 version 17.3](https://devblogs.microsoft.com/cppblog/msvc-backend-updates-since-visual-studio-2022-version-17-3/) | + +A partial list of new features: + +- `#include` diagnostics, which provides a detailed analysis of your `#include` directives. Activate this feature by right-clicking an `#include` and choosing **#include directives** > **Turn #include directive diagnostics on**. Above each `#include` is the number of times your code references that `#include` file. Click the **reference** link to navigate to where your code uses something from that header file. To view the build time of your `#include` directives, run Build Insights by navigating to **Build** > **Run Build Insights on Solution** > **Build**. + :::image type="complex" source="media/include-diagnostics.png" alt-text="Screenshot of #include diagnostics."::: + Above the # include is a **reference** link and many of the references to this # include file (in this case 1). The build time is also listed (in this case less than 1/2 a second). + :::image-end::: +- Memory layout visualization, which shows how memory is arranged for your classes, structs, and unions. Hover over a type and choose the **Memory Layout** link in the **Quick Info** to open a dedicated window displaying the memory layout of the selected type. Hovering over individual data types within this window provides detailed information about their size and offset within the type. + :::image type="complex" source="media/memory-layout-window.png" alt-text="Screenshot of the memory layout window"::: + The memory layout window shows the contents of the Snake class. It shows the memory offsets of the various fields of the class such as Point classes for the location of the head and body, the score, and so on. + :::image-end::: +- You can now specify your own custom CMake executable. This feature is useful if you want to use a specific version of CMake that isn't shipped with Visual Studio. Navigate to **Tools** > **Options** and select **CMake** > **General**. Select **Enable custom CMake executable** and specify the directory path of your CMake executable. + :::image type="complex" source="media/custom-cmake-option.png" alt-text="Screenshot of the CMake options dialog"::: + The CMake options dialog with the "Enable custom CMake executable" option and "CMake Executable Directory" field highlighted. + :::image-end::: +- Improved IntelliSense for Unreal Engine projects. +- Improved C++23 support: + `std::format` and `std::span` + `formattable`, `range_format`, `format_kind`, and `set_debug_format()` as part of [P2286R8 Formatting Ranges](https://wg21.link/P2286R8) + `` per [P0009R18](https://wg21.link/P0009R18) and subsequent wording changes that were applied to the C++23 Standard. + Also, `format()` can format pointers per [P2510R3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2510r3.pdf). + +## What's new for C++ in Visual Studio version 17.8 + +*Released Nov 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's new for C++ Developers in Visual Studio 2022 17.8](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2022-17-8/) | +| Standard Library (STL) merged C++26, C++23 features, C++20 extensions, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.8](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-178) | +| New features in the Visual Studio 17.8 IDE |[Visual Studio 2022 version 17.8 Release Notes](/visualstudio/releases/2022/release-notes-v17.8) | +| C++ language conformance improvements in Visual Studio 2022 17.8 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_178) | +| An overview of C++ improvements in Visual Studio, VS Code, and vcpkg during 2023 | [A year of C++ improvements](https://devblogs.microsoft.com/cppblog/a-year-of-cpp-improvements-in-visual-studio-vs-code-and-vcpkg) | + +A partial list of new features: + +- C++ structured diagnostics in the Output window and a new problem details window that provides more information about the error. For more information, see [Structured SARIF Output](../build/reference/sarif-output.md) and [Problem Details Window](/visualstudio/ide/reference/problem-details-window). +- A feature that lets you visualize the size and alignment of your classes, structs, unions, base types, or enums even before the code is compiled. Hover over the identifier and a Quick Info displays the size and alignment information. +- A feature that suggests when to mark member functions `const` because they don't modify the object's state. Hover over a member function and click the light bulb icon to mark the function as `const`. +- Visual Studio now prompts you to mark global functions as static via a screwdriver icon that appears by the function name. Click the screwdriver icon to mark the function as static. +- Unused #include directives are dimmed in the editor. You can hover over a dimmed include and use the light bulb menu to either remove that include or all unused includes. You can also add `#include` directives for entities that are indirectly included via other headers. For more information, see [Clean up C/C++ includes in Visual Studio](../ide/include-cleanup-overview.md). +- More Unreal Engine support: + - Unreal Engine Test Adapter lets you discover, run, manage, and debug your Unreal Engine tests without leaving the Visual Studio IDE. + - With Unreal Engine Code Snippets, you can find common Unreal Engine constructs as snippets in your member list. + - Build Insights is now integrated with Visual Studio 2022 and works with MSBuild and CMake projects using MSVC. You can now see additional information about the compilation of a function such as how long it took to compile and the number of ForceInlines, and the impact of header files on build time. For more information, see [Tutorial: Troubleshoot function inlining on build time](../build-insights/tutorials/build-insights-function-view.md) and [Tutorial: Troubleshoot header file impact on build time](../build-insights/tutorials/build-insights-included-files-view.md). +- Remote Linux unit test support now lets you run your CTest and GTest tests on your remote Linux machines from Visual Studio's Test Explorer, just like your local tests. + +## What's new for C++ in Visual Studio version 17.7 + +*Released Aug 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's new for C++ Developers in Visual Studio 2022 17.7](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-7/) | +| New C++ features specific to game development | [Unleashing the Power of Visual Studio 2022 for C++ Game Development](https://devblogs.microsoft.com/visualstudio/unleashing-the-power-of-visual-studio-2022-for-c-game-development/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.7](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-177) | +| New features in the Visual Studio 17.7 IDE |[Visual Studio 2022 version 17.7 Release Notes](/visualstudio/releases/2022/release-notes-v17.7) | +| C++ language conformance improvements in Visual Studio 2022 17.7 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_177) | + +A partial list of new features: + +* Faster debugging sessions and faster project load times +* Step-by-step visualization of macro expansion +* One-click download for Windows Subsystem for Linux (WSL) +* Improved support for Doxygen comments +* C++ Build Insights for game development +* Added [`/std:clatest`](../build/reference/std-specify-language-standard-version.md) for the C compiler. +* Unreal Engine project improvements such as faster IntelliSense and syntax colorization, the ability to find all Unreal Engine Blueprint references, and more. + +## What's new for C++ in Visual Studio version 17.6 + +*Released May 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.6](https://devblogs.microsoft.com/cppblog/visual-studio-17-6-for-cpp-devs/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.6](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-176) | +| New features in the Visual Studio 17.6 IDE | [Visual Studio 2022 version 17.6 Release Notes](/visualstudio/releases/2022/release-notes-v17.6) | +| C++ language conformance improvements in Visual Studio 2022 17.6 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_176) | + +A partial list of new features includes: +- CMake script debugging +- Built-in support for High Level Shading Language (HLSL) +- Unreal Engine Log viewer +- VCPKG is now added by default +- Initial support for C++20 in C++/CLI projects and some C++23 standard library features for ranges. + +## What's new for C++ in Visual Studio version 17.5 + +*Released Feb 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.5](https://devblogs.microsoft.com/cppblog/visual-studio-17-5-for-cpp-devs/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.5](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-175) | +| New features in the Visual Studio 17.5 IDE | [Visual Studio 2022 version 17.5 Release Notes](/visualstudio/releases/2022/release-notes-v17.5) | + +A partial list of new features includes: + +- `std::move`, `std::forward`, `std::move_if_noexcept`, and `std::forward_like` now don't produce function calls in generated code, even in debug mode. This change avoids named casts causing unnecessary overhead in debug builds. `/permissive-` (or an option that implies it, such as `/std:c++20` or `std:c++latest`) is required. +- Added [`[[msvc::intrinsic]]`](../cpp/attributes.md#msvcintrinsic). You can apply this attribute to nonrecursive functions consisting of a single cast, which take only one parameter. +- Added support for Linux Console in the Integrated Terminal, which allows for terminal I/O. +- Added initial experimental support for C11 atomic primitives (``). You can enable this experimental feature with the `/experimental:c11atomics` option in `/std:c11` mode or later. +- Added a new set of experimental high-confidence checks to the Lifetime Checker for reduced noise. +- A new preview feature, Remote File Explorer, lets you view the file directory on your remote machines within VS, and upload and download files to it. +- Changed versioning of CMake executables shipped with Visual Studio to match Kitware versions. +- Added support for Hot Reload to the CMake Project template. +- Go To Definition for C++ now uses a more subtle indicator of the operation taking more time, replacing the modal dialog from previous versions. +- Started rollout of an experiment providing more smart results in the C++ autocompletion and member list. This functionality was previously known as Predictive IntelliSense but now uses a new presentation method. +- We now ship a native Arm64 Clang toolset with our LLVM workload, allowing native compilation on Arm64 machines. +- Added localization to the [Image Watch Extension](https://marketplace.visualstudio.com/items?itemName=VisualCPPTeam.ImageWatchForVisualStudio2022) (This extension is available in the Marketplace, and isn't bundled through the Visual Studio Installer). +- Added support for opening a Terminal window into the currently running Developer Container. +- Made several improvements to IntelliSense macro expansion. Notably, we enabled recursive expansion in more contexts, and we added options to the pop up to copy the expansion to the clipboard or expand the macro inline. +- Concurrent monitoring is now supported in the Serial Monitor. Concurrent monitoring allows you to monitor multiple ports at the same time side by side. Press the plus button to open another Serial Monitor and get started. +- You can now view properties from base classes modified in an Unreal Blueprint asset without leaving Visual Studio. Double-click in a Blueprint reference for a C++ class or property to open the UE Asset Inspector in Visual Studio. +- Enabled running DevContainers on a remote Linux machine. +- Enabled selection of multiple targets to build in the CMake Targets view. +- Added support for CMakePresets.json version 5. See the [CMake documentation](https://cmake.org/cmake/help/v3.24/manual/cmake-presets.7.html) for information of new features. +- Enabled Test Explorer to build and test multiple CMake targets in parallel. +- Added "Open container in terminal" option to Dev Containers. +- Implemented standard library features: + + - [P2508R1](https://wg21.link/P2508R1) `basic_format_string`, `format_string`, `wformat_string` + - [P2322R6](https://wg21.link/P2322R6) `ranges::fold_left`, `ranges::fold_right`, and so on. + - [P2321R2](https://wg21.link/P2321R2) `views::zip` (doesn't include `zip_transform`, `adjacent`, and `adjacent_transform`) + +## What's new for C++ in Visual Studio version 17.4 + +*Released Nov 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.4](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2022-17-4/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.4](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-174) | +| New features in the Visual Studio 17.4 IDE | [Visual Studio 2022 version 17.4 Release Notes](/visualstudio/releases/2022/release-notes-v17.4) | +| C++ language conformance improvements in Visual Studio 2022 17.4 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_174) | + +A partial list of new features in 17.4: + +- Improved compiler error messages to provide more correct and useful information, especially for concepts. +- Added experimental MSVC option [`/experimental:log`](../build/reference/experimental-log.md) to output [structured SARIF diagnostics](../build/reference/sarif-output.md) to the specified directory. +- Added support for C23 attributes to IntelliSense and continued progress in C++20 modules support. +- Improved indexing performance when opening a new solution. Large projects could see a 20-35% improvement from 17.3. +- Improved Named Return Value Optimization (NRVO): + - NRVO is enabled for cases that involve exception handling or loops. + - NRVO is enabled even under **`/Od`** if the user passes the **`/Zc:nrvo`** option, or **`/std:c++20`** or later, or **`/permissive-`**. + - You can now disable NRVO with the **`/Zc:nrvo-`** option. +- Upgraded the version of LLVM shipped with Visual Studio to 15.0.1. For more information on what is available, see the [LLVM](https://releases.llvm.org/15.0.0/docs/ReleaseNotes.html) and [Clang](https://releases.llvm.org/15.0.0/tools/clang/docs/ReleaseNotes.html) release notes. +- Added support to Visual Studio for vcpkg artifacts with CMake projects. For projects that include a vcpkg manifest, the environment is activated automatically on project open. Learn more about this feature in the [vcpkg environment activation in Visual Studio](https://aka.ms/vsvcpkgenv) blog post. +- You can now use Dev Containers for your C++ projects. Learn more about this feature in our [Dev Containers for C++](https://aka.ms/vscppdevcontainer) blog post. +- IntelliSense now respects the order of preincluded headers when one of them is a PCH. Previously, when a PCH was used via **`/Yu`** and force-included via **`/FI`**, IntelliSense would always process it first, before any other headers included via **`/FI`**. This behavior didn't match the build behavior. With this change, **`/FI`** headers are processed in the order they're specified. +- Removed internal prefixes from CTest names in Test Explorer. +- Updated the version of CMake shipped with Visual Studio to version 3.24.1. For details of what is available, see the [CMake release notes](https://cmake.org/cmake/help/v3.24/release/3.24.html). +- Android SDK update: + - Ant scripts were removed, so users no longer see Ant-based templates in the New Project dialog. For help migrating from Ant templates to Gradle templates, see [Migrating Builds From Apache Ant](https://docs.gradle.org/current/userguide/migrating_from_ant.html) + - Added support for building with NDK 23 and 24 + - Updated NDK component to the LTS version 23 +- Added vectorized implementations of `ranges::min_element()`, `ranges::max_element()`, and `ranges::minmax_element()` +- We continue to track the latest developments in C++ standardization. Support for these C++23 features is available by including [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) in your compiler options: + - [P2302R4](https://wg21.link/p2302r4) `ranges::contains`, `ranges::contains_subrange` + - [P2499R0](https://wg21.link/p2499r0) `string_view` Range Constructor Should Be `explicit` + - [P0849R8](https://wg21.link/p0849r8) `auto(x)`: decay-copy In The Language + + (The compiler part isn't implemented yet. The library part was implemented in C++20 mode when Ranges support was initially implemented.) + - [P0881R7](https://wg21.link/p0881r7) `` + - [P2301R1](https://wg21.link/p2301r1) Add A `pmr` Alias For `std::stacktrace` + - [P1328R1](https://wg21.link/p1328r1) `constexpr type_info::operator==()` + - [P2440R1](https://wg21.link/p2440r1) `ranges::iota`, `ranges::shift_left`, `ranges::shift_right` + - [P2441R2](https://wg21.link/p2441r2) `views::join_with` + +- Added an option "Navigation after Create Declaration/Definition" to allow you to choose the navigation behavior of the Create Declaration/Definition feature. You can select between peeking (the default) or opening the document, or no navigation. +- Arm64 builds of Visual Studio now bundle Arm64 versions of CMake and Ninja. +- Added support for CMake Presets version 4. For details of what is available, see the [CMake release notes](https://cmake.org/cmake/help/v3.23/release/3.23.html#id6). +- Remote system connections using the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md) now support SSH ProxyJump. ProxyJump is used to access an SSH host via another SSH host (for example, to access a host behind a firewall). + +## What's new for C++ in Visual Studio version 17.3 + +*Released Aug 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [C++ improvements in 17.3](https://devblogs.microsoft.com/visualstudio/visual-studio-2022-17-3-is-now-available/#c-improvements) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.3](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-173) | +| New features in the Visual Studio 17.3 IDE | [Visual Studio 2022 version 17.3 Release Notes](/visualstudio/releases/2022/release-notes-v17.3) | +| C++ language conformance improvements in Visual Studio 2022 17.3 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_173) | + +A partial list of new features in 17.3: + +- The Arm64EC toolchain is no longer marked as experimental and is ready for production use. +- The Visual Studio Terminal can now be used as an SSH client with your stored SSH connections. With the C++ for Linux Tools installed, open the Terminal tool window. The Terminal dropdown is populated with your stored connections. When you select a connection, a new Terminal window opens inside Visual Studio that shows a pseudo-terminal on your remote system. Control characters, colors, and cursor positional awareness are all supported. +- Visual Studio can now add Unreal Engine class templates for your UE projects. To try this feature, ensure **IDE support for Unreal Engine** is selected in the **Game development with C++** workload in the Visual Studio Installer. When you're working on a UE project, right-click in the project or a folder/filter and select **Add** > **UE Class**. +- **Go to Definition** now remembers the prior signature and navigates accordingly when a better match isn't available (for example, after you manually change the signature of one of the pair). +The responsiveness of **Go To All** is improved. Previously, results appeared after you stopped typing. In the new experience, results show as you type. +- In contexts requiring `enum` type completion (for example, assignments to `enum` variables, case labels, returning `enum` type, and so on), the autocompletion list is now filtered to just the matching enumerators and related constructs. +- Added NuGet PackageReference support for C++/CLI MSBuild projects targeting .NET Core. This change was made to unblock mixed codebases from being able to adopt .NET Core. This support doesn't work for other C++ project types or any C++ project types targeting .NET Framework. There are no plans to extend PackageReference support to other C++ scenarios. The team is working on separate experiences involving vcpkg for non-MSBuild scenarios and to add greater functionality. +- Added a Serial Monitor window for embedded development, available through **Debug** > **Windows** > **Serial Monitor**. +- Improved C++ indexing by ~66% compared to 17.2. +- Updated the version of CMake shipped with Visual Studio to version 3.23. See the [CMake 3.23 release notes](https://cmake.org/cmake/help/v3.23/release/3.23.html) for details of what is available. +- Upgraded the versions of LLVM tools shipped with Visual Studio to v14. For details of what is available, see the [LLVM](https://releases.llvm.org/14.0.0/docs/ReleaseNotes.html) and [Clang](https://releases.llvm.org/14.0.0/tools/clang/docs/ReleaseNotes.html) release notes. +- Updated the side-by-side Dev 16.11 C++ Toolset to version 14.29.30145.00. The latest version of the Dev 16.11 C++ Toolset contains important bug fixes, including fixing all remaining C++20 defect reports. For more information about bug fixes, including C++20 defect reports in Dev 16.11, see [Visual Studio 2019 version 16.11.14 release notes](/visualstudio/releases/2019/release-notes#16.11.14). +- Made various improvements to the in-editor experience of C++ modules. We're continuously working on improving the quality of the experience but encourage you to try them in 17.3. Report remaining issues through [Developer Community](https://aka.ms/vsfeedback/browsecpp). + +## What's new for C++ in Visual Studio version 17.2 + +*Released May 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [Visual Studio 2022 17.2 is now available](https://devblogs.microsoft.com/visualstudio/visual-studio-2022-17-2-is-now-available/) | +| Standard Library (STL) merged C++20 defect reports, C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.2](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-172) | +| New features in the Visual Studio 17.2 IDE | [Visual Studio 2022 version 17.2 Release Notes](/visualstudio/releases/2022/release-notes-v17.2) | +| C++ language conformance improvements in Visual Studio 2022 17.2 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_172) | + +A partial list of new features in 17.2: + +- Added compiler support for C++23 feature [deducing `this`](https://wg21.link/p0847), available under the **`/std:c++latest`** option. +- Added IntelliSense support for C++23 features [deducing `this`](https://wg21.link/p0847) and [`if consteval`](http://wg21.link/p1938). +- Added inline parameter name and type hint support, toggled by pressing **Alt+F1** or double-tapping **Ctrl**. This behavior can be customized under **Tools > Options > Text Editors > C/C++ > IntelliSense**. +- Added experimental support for C++20 modules in CMake projects. This support is currently only available with the Visual Studio (MSBuild) generator. +- In 17.1, we introduced peripheral register and RTOS views for embedded developers. We continue to improve the capabilities of those views with usability improvements in 17.2: + - The RTOS tool window is now hidden by default. It prevents showing a tool window with error messages that aren't relevant when you're not using an RTOS. + - When you double-click an RTOS object in the tool window, it adds a watch for the object. + - When you select the start and end values for the stack pointer in the RTOS tool window, it opens in the memory window. + - Added thread awareness for device targets to the call stack window. + - Users can now select a pin icon next to peripherals, registers, or fields to pin them the top of the Peripheral View. +- Added implementations of the remaining C++20 defect reports (also known as *backports*). All C++20 features are now available under the **`/std:c++20`** option. For more information about the implemented backports, see the [VS 2022 Changelog](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-172) in the Microsoft/STL GitHub repository and the [MSVC's STL Completes `/std:c++20`](https://devblogs.microsoft.com/cppblog/msvcs-stl-completes-stdc20/) blog post. +- We added various C++23 Library features, available under the **`/std:c++latest`** option. For more information about the new features, see the [STL Repo changelog](https://github.com/microsoft/STL/wiki/Changelog). +- Improved performance of the initial C++ indexing by up to 20%, depending on the depth of the include graph. + +## What's new for C++ in Visual Studio version 17.1 + +*Released Feb 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [Visual Studio 2022 17.1 is now available!](https://devblogs.microsoft.com/visualstudio/visual-studio-2022-17-1-is-now-available/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.1](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-171) | +| New features in the Visual Studio 17.1 IDE | [Visual Studio 2022 version 17.1 Release Notes](/visualstudio/releases/2022/release-notes-v17.1) | +| C++ language conformance improvements in Visual Studio 2022 17.1 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_171) | + +A partial list of new features in 17.1: + +- A new **Configure Preset** template is added to configure and build CMake projects on a remote macOS system with *`CMakePresets.json`*. You can also launch CMake targets on a remote macOS system, and then debug remotely in the Visual Studio debugger backed by GDB or LLDB. +- You can now debug core dumps on a remote macOS system from Visual Studio with LLDB or GDB. +- The versions of [`Clang`](https://releases.llvm.org/13.0.0/tools/clang/docs/ReleaseNotes.html) and [`LLVM`](https://releases.llvm.org/13.0.0/docs/ReleaseNotes.html) shipped with Visual Studio are upgraded to v13. +- Visual Studio's CMake integration is only active when a *`CMakeLists.txt`* is identified at the root of the open workspace. If a *`CMakeLists.txt`* is identified at another level of the workspace, then you're prompted to activate Visual Studio's CMake integration with a notification. +- New views that enable you to inspect and interact with peripheral registers on microcontrollers and real time operating systems (RTOS) objects, available through **Debug** > **Windows** > **Embedded Registers** +- Added a new thread view for RTOS projects, available through **Debug** > **Windows** > **RTOS Objects**. For more information, see [Embedded Software Development in Visual Studio](https://devblogs.microsoft.com/cppblog/visual-studio-embedded-development/). ## What's new for C++ in Visual Studio version 17.0 -For a summary of new features and bug fixes in Visual Studio, see [What's New in Visual Studio 2022 version 17.0](/visualstudio/releases/2022/release-notes). +*Released Nov 2021* -- The Visual Studio IDE, *`devenv.exe`*, is now a native 64-bit application. +| For more information about | See | +|---|---| +| New features in the Visual Studio 17.0 IDE | [Visual Studio 2022 version 17.0 Release Notes](/visualstudio/releases/2022/release-notes-v17.0) | +| Standard Library (STL) merged C++23 and C++26 features, C++20 defect reports, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.0](https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1710) | +| C++ language conformance improvements in Visual Studio 2022 17.0 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022 17.10](cpp-conformance-improvements.md#improvements_170) | -- The MSVC toolset now defaults to SHA-256 source hashing in debug records. Previously, the toolset used MD5 for source hashing by default. +An overview of some of the new features in Visual Studio 2022 version 17.0: +- The Visual Studio IDE, *`devenv.exe`*, is now a native 64-bit application. +- The MSVC toolset now defaults to SHA-256 source hashing in debug records. Previously, the toolset used MD5 for source hashing by default. - The v143 build tools are now available through the Visual Studio installer and in the [standalone build tools](https://aka.ms/vs/17/pre/vs_BuildTools.exe). ### Hot Reload for native C++ - [Hot Reload for C++](https://devblogs.microsoft.com/cppblog/edit-your-c-code-while-debugging-with-hot-reload-in-visual-studio-2022/) makes it possible to make many types of code edits to your running app and apply them without needing to pause app execution with something like a breakpoint. -In Visual Studio 2022, when you start your app in the debugger, you can use the Hot Reload button to modify your application while it's still running. This experience is powered by native Edit and Continue. For more information about supported edits, see [Edot and Continue (C++)](/visualstudio/debugger/edit-and-continue-visual-cpp?view=vs-2022&preserve-view=true). +In Visual Studio 2022, when you start your app in the debugger, you can use the Hot Reload button to modify your application while it's still running. This experience is powered by native Edit and Continue. For more information about supported edits, see [Edit and Continue (C++)](/visualstudio/debugger/edit-and-continue-visual-cpp?view=vs-2022&preserve-view=true). - Hot Reload supports CMake and Open Folder projects. @@ -33,26 +582,22 @@ In Visual Studio 2022, when you start your app in the debugger, you can use the ### Improved CMake support -- We've upgraded the version of CMake shipped with Visual Studio to version 3.21. For more information on what's available in this version, see the [CMake 3.21 release notes](https://cmake.org/cmake/help/latest/release/3.21.html). - -- CMake Overview Pages have been updated to support *`CMakePresets.json`*. +- Upgraded the version of CMake shipped with Visual Studio to version 3.21. For more information on what's available in this version, see the [CMake 3.21 release notes](https://cmake.org/cmake/help/latest/release/3.21.html). +- CMake Overview Pages are updated to support *`CMakePresets.json`*. - You can now configure and build your CMake projects with CMake 3.21 and *`CMakePresets.json`* v3. - - Visual Studio now supports the `buildPresets.targets` option in *`CMakePresets.json`*. This option allows you to build a subset of targets in your CMake project. - -- The Project menu in CMake projects has been streamlined and exposes options to "Delete Cache and Reconfigure" and "View Cache". - -- Implemented the **`/scanDependencies`** compiler option to list C++20 module dependencies for CMake projects, as described in [P1689r3](https://wg21.link/P1689r3). It's a step towards support for building modules-based projects with CMake and we're working on completing this support in later releases. +- The Project menu in CMake projects is streamlined and exposes options to "Delete Cache and Reconfigure" and "View Cache." +- Implemented the **`/scanDependencies`** compiler option to list C++20 module dependencies for CMake projects, as described in [P1689R5](https://wg21.link/P1689r5). It's a step towards support for building modules-based projects with CMake and we're working on completing this support in later releases. ### Standard Library improvements -Select Standard Library (STL) improvements are highlighted here. For a comprehensive list of new functionality, changes, bug fixes, and performance improvements, see the STL team's [Changelog](https://github.com/microsoft/STL/wiki/Changelog#vs-2022). +Select Standard Library (STL) improvements are highlighted here. For a comprehensive list of new functionality, changes, bug fixes, and performance improvements, see the STL team's [Changelog](https://github.com/microsoft/STL/wiki/Changelog). - Added debugging visualizers to improve how the following types are displayed: `source_location`, `bind_front()`, `u8string` (and its iterators), `default_sentinel_t`, `unreachable_sentinel_t`, `ranges::empty_view`, `ranges::single_view`, `ranges::iota_view` (and its iterator/sentinel), `ranges::ref_view`, `thread`, `thread::id`, `jthread`, and `filesystem::path` - Added `[[nodiscard]]` to the `stoi()` family of functions in `` and to various functions in `` such as the `collate` member functions, `has_facet()`, and the `isalnum()` and `tolower()` families. -- [P0980R1](https://wg21.link/P0980R1) Made `std::string` `constexpr` in VS 2019 16.10. Now it's also supported for Clang. -- [P1004R2](https://wg21.link/P1004R2) Made `std::vector` `constexpr`in VS 2019 16.10. Now it's also supported for Clang. +- [P0980R1](https://wg21.link/P0980R1) Made `std::string` `constexpr` in VS 2019 16.10. Now supported for Clang. +- [P1004R2](https://wg21.link/P1004R2) Made `std::vector` `constexpr` in VS 2019 16.10. Now supported for Clang. **Highlighted C++23 features** @@ -61,63 +606,59 @@ Select Standard Library (STL) improvements are highlighted here. For a comprehen - [P1679R3](https://wg21.link/P1679R3) `contains()` For `basic_string` and `basic_string_view` - [P1682R3](https://wg21.link/P1682R3) `to_underlying()` for enumerations - [P2162R2](https://wg21.link/P2162R2) Allow inheriting from `std::variant` -- [P2166R1](https://wg21.link/P2166R1) Prohibit constructing`basic_string` and `basic_string_view` from `nullptr`. This is a source-breaking change. Code that previously had undefined behavior at runtime will now be rejected with compiler errors. -- [P2186R2](https://wg21.link/P2186R2) Removed garbage collection support. This removes `declare_reachable`, `undeclare_reachable`, `declare_no_pointers`, `undeclare_no_pointers`, `get_pointer_safety`. Previously, these functions had no effect. +- [P2166R1](https://wg21.link/P2166R1) Prohibit constructing `basic_string` and `basic_string_view` from `nullptr`. This change is a source-breaking change. Code that previously had undefined behavior at runtime is now rejected with compiler errors. +- [P2186R2](https://wg21.link/P2186R2) Removed garbage collection support. This change removes `declare_reachable`, `undeclare_reachable`, `declare_no_pointers`, `undeclare_no_pointers`, `get_pointer_safety`. Previously, these functions had no effect. **Highlighted performance improvements** - `` now detects when it's writing to a `back_insert_iterator` for a `basic_string` or a `vector`, and makes a faster call to `insert()` at the `end()` of the container. -- Improved the performance of `std::find()` and `std::count()` for `vector` 19x and 26x (times, not percent). -- Improved the performance of `std::count()` for `vector` +- We improved the performance of `std::find()` and `std::count()` for `vector` 19x and 26x (times, not percent). +- We improved the performance of `std::count()` for `vector` - `std::byte` now has the same performance as `unsigned char` in `reverse()` and `variant::swap()` ### Clang and LLVM support -- LLVM tools shipped with Visual Studio have been upgraded to LLVM 12. For more information, see the [LLVM release notes](https://releases.llvm.org/12.0.0/docs/ReleaseNotes.html). +- LLVM tools shipped with Visual Studio are upgraded to LLVM 12. For more information, see the [LLVM release notes](https://releases.llvm.org/12.0.0/docs/ReleaseNotes.html). - Clang-cl support was updated to LLVM 12. - - You can now debug processes running on a remote system from Visual Studio by using LLDB. ### C++ AMP deprecated -- C++ AMP headers are now deprecated. Including `` in a C++ project generates build errors. To silence the errors, define `_SILENCE_AMP_DEPRECATION_WARNINGS`. For more information, see [our AMP Deprecation links](/cpp/parallel/amp/cpp-amp-overview). +- C++ AMP headers are now deprecated. Including `` in a C++ project generates build errors. To silence the errors, define `_SILENCE_AMP_DEPRECATION_WARNINGS`. For more information, see [our AMP Deprecation links](../parallel/amp/cpp-amp-overview.md). ### IntelliSense improvements - We made improvements in C++ IntelliSense when providing navigation and syntax highlighting for types from imported Modules and Header Units. IntelliSense is an active area of investment for us. Help us improve: Share your feedback on Developer Community by using **Help** > **Send Feedback**. - -- Improved C++ IntelliSense performance by optimizing cached header usage and symbol database access, providing improved load times to get into your code. - +- We improved C++ IntelliSense performance by optimizing cached header usage and symbol database access, providing improved load times to get into your code. - The IntelliSense Code Linter for C++ is now on by default, providing instant as-you-type suggestions and fix suggestions for common code defects. - - C++ IntelliSense for CMake projects now works when using a preset with a display name. ### C++ Workload updates - Updated to NDK r21 LTS in the **C++ Mobile Development** workload. - -- The **Game development with C++** workload now installs the latest Unreal Engine with support with for Visual Studio 2022. +- The **Game development with C++** workload now installs the latest Unreal Engine with support for Visual Studio 2022. ### Code analysis improvements - Code analysis now enforces that return values of functions annotated with `_Check_return_` or `_Must_inspect_result_` must be checked. - -- We've improved null pointer dereference detection in our code analysis tooling. - +- Null pointer dereference detection is improved in our code analysis tooling. - Added support for `gsl::not_null` to code analysis. - - Support for Libfuzzer under the **`/fsanitize=fuzzer`** compiler option. ## Release notes for older versions -Release notes for older C++ versions are also available. For information on what's new for C++ in Visual Studio 2019, see [What's new for C++ in Visual Studio 2019.](what-s-new-for-cpp-2019.md) For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017.](what-s-new-for-cpp-2017.md) For information on what's new in earlier versions, see [Visual C++ What's New 2003 through 2015.](../porting/visual-cpp-what-s-new-2003-through-2015.md) +Release notes for older C++ versions are also available: + +- For information on what's new for C++ in Visual Studio 2019, see [What's new for C++ in Visual Studio 2019](what-s-new-for-cpp-2019.md). +- For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). +- For information on what's new in earlier versions, see [Visual C++ What's new 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). ## Known issues **C++ IntelliSense** -- [When importing a C++20 module or header unit, IntelliSense may stop working or 'There are too many errors' error is shown](https://aka.ms/vcmoduleintellisenseinfo). +- [`When importing a C++20 module or header unit, IntelliSense may stop working or 'There are too many errors' error is shown`](https://aka.ms/vcmoduleintellisenseinfo). For more information on other open issues and available workarounds for C++ in Visual Studio 2022, see the C++ Developer Community [issues list](https://developercommunity.visualstudio.com/search?space=62&stateGroup=active&ftype=problem&sort=votes&q=2022). @@ -127,4 +668,4 @@ We'd love to hear from you! You can [Report a Problem or Suggest a Feature](/vis ## Blogs -Take advantage of the insights and recommendations available in the [Microsoft Developer Blogs](https://devblogs.microsoft.com/) site. They'll keep you up to date on all new releases. The blogs include deep dive posts on a broad range of features. You'll find the [C++ Team Blog](https://devblogs.microsoft.com/cppblog) and the [Visual Studio Blog](https://devblogs.microsoft.com/visualstudio) of particular interest. \ No newline at end of file +Take advantage of the insights and recommendations available in the [Microsoft Developer Blogs](https://devblogs.microsoft.com/) site to stay up to date on all new releases. The blogs include deep dive posts on a broad range of features. The [C++ Team Blog](https://devblogs.microsoft.com/cppblog) and the [Visual Studio Blog](https://devblogs.microsoft.com/visualstudio) are of particular interest. diff --git a/docs/overview/whats-new-cpp-docs.md b/docs/overview/whats-new-cpp-docs.md deleted file mode 100644 index f86ed5a392..0000000000 --- a/docs/overview/whats-new-cpp-docs.md +++ /dev/null @@ -1,580 +0,0 @@ ---- -title: "What's new for the C++ docs" -ms.date: "11/5/2021" -description: "The new docs and doc updates for the Microsoft C/C++ compiler, ATL/MFC, C runtime, and standard library docs." -ms.custom: intro-whats-new ---- - -# Microsoft C++ docs: What's new for October 2021 - -This article lists major changes to the Microsoft C++ docs July 2021 through October 2021. - -- For what was new in the docs in previous months, see [What's new history](#whats-new-history). -- For what's new related to C++ in Visual Studio, see [What's new for C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md). -- For the latest C and C++ conformance with ISO standards status, see [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md). - -## Active Template Library (ATL), Microsoft Foundation Classes (MFC) - -### Updated articles - -- [`CSimpleStringT` Class](../atl-mfc-shared/reference/csimplestringt-class.md) - updated code examples and added code example output -- [MFC class hierarchy chart](../mfc/hierarchy-chart.md) - Update MFC hierarchy chart - -## C language - -### New articles - -- [Generic selection (C11)](../c-language/generic-selection.md) - -### Updated articles - -- [`register` storage-class specifier](../c-language/register-storage-class-specifier.md) - Add C5033 warning -- [C Pragmas](../c-language/c-pragmas.md) - Add system_header pragma documentation -- [C Bit Fields](../c-language/c-bit-fields.md) - Clarify int main(void) example & document MSVC doesn't straddle bit-fields - -## C runtime library - -### Updated articles - -- [CRT Initialization](../c-runtime-library/crt-initialization.md) - Add 16.11 Compiler warnings C5247 and C5248 -- [`rand`](../c-runtime-library/reference/rand.md) - Update code example -- [`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md) - Update code example -- [_get_errno](../c-runtime-library/reference/get-errno.md) - Update code example - -## C/C++ compiler and tools errors and warnings - -### New articles - -- [Command-line error D8049](../error-messages/tool-errors/command-line-error-d8049.md) -- [Compiler Warning C5243](../error-messages/compiler-warnings/c5243.md) -- [Compiler Warning C5247](../error-messages/compiler-warnings/c5247.md) -- [Compiler Warning C5248](../error-messages/compiler-warnings/c5248.md) -- [Compiler Warning (level 1) C5033](../error-messages/compiler-warnings/c5033.md) - -### Updated articles - -- [Command-line errors and warnings](../error-messages/tool-errors/command-line-errors-d8000-through-d9999.md) - new error messages -- [Compiler Warning (level 4) C4710](../error-messages/compiler-warnings/compiler-warning-level-4-c4710.md) - Add C5033 warning -- [Compiler Warnings C4800 through C5999](../error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md) - Add compiler warning C5033, C5243, C5249, C5250, C5247, and C5248. -- [Compiler Error C2666](../error-messages/compiler-errors-2/compiler-error-c2666.md) - Update 16.1 conformance -- [Compiler Warning (level 4) C4702](../error-messages/compiler-warnings/compiler-warning-level-4-c4702.md) - Update warning C4702 -- [Compiler Error C2440](../error-messages/compiler-errors-1/compiler-error-c2440.md) - Add `/Zc:char8_t` compiler option -- [Compiler Error C2760](../error-messages/compiler-errors-2/compiler-error-c2760.md) - New `/Zc:lambda` info -- [Compiler Error C2259](../error-messages/compiler-errors-1/compiler-error-c2259.md) - Update code example - -## C/C++ compiler intrinsics and assembly language - -### New articles - -- [MASM instruction format](../assembler/masm/instruction-format.md) -- [OPTION AVXENCODING](../assembler/masm/option-avxencoding-masm.md) -- [OPTION LANGUAGE](../assembler/masm/option-language-masm.md) - -### Updated articles - -- [MASM for x64 (ml64.exe)](../assembler/masm/masm-for-x64-ml64-exe.md) - Document MASM instruction format including prefixes and option avxencoding -- [Microsoft Macro Assembler reference](../assembler/masm/microsoft-macro-assembler-reference.md) - Document MASM instruction format including prefixes and option avxencoding -- [`OPTION`](../assembler/masm/option-masm.md) - Document MASM instruction format including prefixes and option avxencoding -- [_InterlockedCompareExchange intrinsic functions](../intrinsics/interlockedcompareexchange-intrinsic-functions.md) - Adding missing interlocked intrinsic and fixing another interlock intrinsic return type - -## C/C++ in Visual Studio overview - -### New articles - -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2019](../overview/cpp-conformance-improvements-2019.md) -- [What's new for C++ in Visual Studio 2019](../overview/what-s-new-for-cpp-2019.md) - -### Updated articles - -- [Overview of C++ development in Visual Studio](../overview/overview-of-cpp-development.md) - Visual Studio 2022 related updates. -- [Install C11 and C17 support in Visual Studio](../overview/install-c17-support.md) - Visual Studio 2022 related updates, C17 updates -- [C++ Tools and Features in Visual Studio Editions](../overview/visual-cpp-tools-and-features-in-visual-studio-editions.md) - Visual Studio 2022 related updates, C17 updates -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](../overview/cpp-conformance-improvements.md) - Visual Studio 2022 and 16.1 conformance updates -- [Microsoft C/C++ language conformance by Visual Studio version](../overview/visual-cpp-language-conformance.md) - Visual Studio 2022 related updates -- [C and C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md) - Add missing redist content - -## C/C++ preprocessor reference - -### New articles - -- [`system_header` pragma](../preprocessor/system-header-pragma.md) - -### Updated articles - -- [`fenv_access` pragma](../preprocessor/fenv-access.md) - Add floating-point *contractions* info -- [`float_control` pragma](../preprocessor/float-control.md) - Add floating-point *contractions* info -- [`fp_contract` pragma](../preprocessor/fp-contract.md) - Add floating-point *contractions* info -- [Predefined macros](../preprocessor/predefined-macros.md) - Add `__SANITIZE_ADDRESS__` and `_M_FP_CONTRACT` -- [Compiler warnings that are off by default](../preprocessor/compiler-warnings-that-are-off-by-default.md) - Add compiler warning C5243, C5249, C5250, C5247, and C5248 - -## C/C++ projects and build systems - -### New articles - -- [`/Zc:char8_t` (Enable C++20 char8_t type)](../build/reference/zc-char8-t.md) -- [`/Zc:lambda` (Enable updated lambda processor)](../build/reference/zc-lambda.md) -- [`/fsanitize-coverage` (Configure sanitizer coverage)](../build/reference/fsanitize-coverage.md) -- [`abspath` NMAKE function](../build/reference/nmake-function-abspath.md) -- [`basename` NMAKE function](../build/reference/nmake-function-basename.md) -- [`filter`, `filteri` NMAKE functions](../build/reference/nmake-function-filter.md) -- [`filterout`, `filterouti` NMAKE functions](../build/reference/nmake-function-filterout.md) -- [`findstring`, `findstringi` NMAKE functions](../build/reference/nmake-function-findstring.md) -- [`patsubst`, `patsubsti` NMAKE functions](../build/reference/nmake-function-patsubst.md) -- [`strip` NMAKE function](../build/reference/nmake-function-strip.md) -- [`subst`, `substi` NMAKE functions](../build/reference/nmake-function-subst.md) -- [Walkthrough: Build and debug C++ with WSL 2 and Visual Studio 2022](../build/walkthrough-build-debug-wsl2.md) - -### Updated articles - -- [Configure and build with CMake Presets in Visual Studio](../build/cmake-presets-vs.md) - Fix inconsistencies and add documentation about the "unspecified" architecture feature -- [Clang/LLVM support in Visual Studio CMake projects](../build/clang-support-cmake.md) - Clarified version-specific installation -- [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md) - Fix inconsistencies in CMake docs and add docs on using existing cache without cmake-server -- [/fp (Specify floating-point behavior)](../build/reference/fp-specify-floating-point-behavior.md) - Fix `/fp` sample code -- [`/Og` (Global Optimizations)](../build/reference/og-global-optimizations.md) - Clarify when the **`register`** keyword is ignored -- [`/PROFILE` (Performance Tools Profiler)](../build/reference/profile-performance-tools-profiler.md) - Address `/profile` issues -- [Use the Microsoft C++ toolset from the command line](../build/building-on-the-command-line.md) - Fix MSBuild recommendation & update C/C++ workload name -- [Use an NMAKE macro](../build/reference/using-an-nmake-macro.md) - Add documentation for the new NMAKE functions -- [Commands in a makefile](../build/reference/commands-in-a-makefile.md) - Combine and update NMAKE docs -- [NMAKE makefile contents and features](../build/reference/contents-of-a-makefile.md) - Combine and update NMAKE docs -- [Create a C++ makefile project](../build/reference/creating-a-makefile-project.md) - Combine and update NMAKE docs -- [Define an NMAKE macro](../build/reference/defining-an-nmake-macro.md) - Combine and update NMAKE docs -- [Dot directives](../build/reference/dot-directives.md) - Combine and update NMAKE docs -- [Inference rules](../build/reference/inference-rules.md) - Combine and update NMAKE docs -- [Inline files in a makefile](../build/reference/inline-files-in-a-makefile.md) - Combine and update NMAKE docs -- [Makefile Preprocessing](../build/reference/makefile-preprocessing.md) - Combine and update NMAKE docs -- [NMAKE Reference](../build/reference/nmake-reference.md) - Combine and update NMAKE docs -- [Running NMAKE](../build/reference/running-nmake.md) - Combine and update NMAKE docs -- [Sample Makefile](../build/reference/sample-makefile.md) - Combine and update NMAKE docs -- [Special NMAKE macros](../build/reference/special-nmake-macros.md) - Combine and update NMAKE docs -- [Configuring Programs for Windows XP](../build/configuring-programs-for-windows-xp.md) - Link updates for new redist article -- [`/Zc` (Conformance)](../build/reference/zc-conformance.md) - New `/Zc:lambda` information -- [`/Zc:__cplusplus` (Enable updated `__cplusplus` macro)](../build/reference/zc-cplusplus.md) - New `/Zc:lambda` information -- [CMake predefined build configurations](../build/cmake-predefined-configuration-reference.md) - Fix inconsistencies in CMake docs -- [`CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps](../build/cmake-presets-json-reference.md) - Fix inconsistencies in CMake docs -- [Tutorial: Debug a CMake project on a remote Windows machine](../build/cmake-remote-debugging.md) - Fix inconsistencies in CMake docs -- [`CMakeSettings.json` schema reference](../build/cmakesettings-reference.md) - Fix inconsistencies in CMake docs -- [`launch.vs.json` schema reference (C++)](../build/launch-vs-schema-reference-cpp.md) - add debugInfo macro definitions -- [`/external` (External headers diagnostics)](../build/reference/external-external-headers-diagnostics.md) - Add `system_header` pragma doc -- [DUMPBIN Reference](../build/reference/dumpbin-reference.md) - Setting `PATH` allows `DUMPBIN` to be executed from the command prompt -- [/Qspectre](../build/reference/qspectre.md) - Clarified `/Qspectre` Required Libraries section - -## C++ in Visual Studio - -### Updated articles - -- [Storage classes](../cpp/storage-classes-cpp.md) - Add C5033 warning -- [void (C++)](../cpp/void-cpp.md) - Clarify overall article -- [Labeled statements](../cpp/labeled-statements.md) - Correct labeled statements -- [Brace initialization](../cpp/initializing-classes-and-structs-without-constructors-cpp.md) - Address sanitizer comment location -- [Member Access Control (C++)](../cpp/member-access-control-cpp.md) - Update static member access in example -- [String and character literals (C++)](../cpp/string-and-character-literals-cpp.md) - Updates for C++20 portable **`char8_t`**. -- [Declarations and definitions (C++)](../cpp/declarations-and-definitions-cpp.md) - fix code sample -- [Template Specialization (C++)](../cpp/template-specialization-cpp.md) - update code example - -## C++ in Visual Studio tutorials - -### Updated articles - -- [Create a console calculator in C++](../get-started/tutorial-console-cpp.md) - add Git source control info to the tutorial - -## C++ porting and upgrade guide - -### Updated articles - -- [C++ binary compatibility between Visual Studio versions](../porting/binary-compat-2015-2017.md) - Update version info - -## C++ Standard Library (STL) - -### New articles - -- [`ambiguous_local_time` class](../standard-library/ambiguous-local-time.md) -- [`choose` enum](../standard-library/choose-enum.md) -- [`clock_time_conversion` struct](../standard-library/clock-time-conversion-struct.md) -- [`file_clock` class](../standard-library/file-clock-class.md) -- [`gps_clock` class](../standard-library/gps-clock-class.md) -- [`is_clock` structure](../standard-library/is-clock-struct.md) -- [`last_spec` struct](../standard-library/last-spec-struct.md) -- [`local_info` struct](../standard-library/local-info-struct.md) -- [`local_t` struct](../standard-library/local_t.md) -- [`nonexistent_local_time` class](../standard-library/nonexistent-local-time.md) -- [`sys_info` struct](../standard-library/sys-info-struct.md) -- [`tai_clock` class](../standard-library/tai-clock-class.md) -- [`time_zone_link` class](../standard-library/time-zone-link-class.md) -- [`tzdb_list` class](../standard-library/tzdb-list-class.md) -- [`tzdb` struct](../standard-library/tzdb-struct.md) -- [`utc_clock` class](../standard-library/utc-clock-class.md) -- [`zoned_time` class](../standard-library/zoned-time-class.md) -- [`zoned_traits` struct](../standard-library/zoned-traits-struct.md) - -### Updated articles - -- [`` functions](../standard-library/chrono-functions.md) - added new `` functions -- [``](../standard-library/chrono.md) - added new `` types -- [`duration` class](../standard-library/duration-class.md) - overall article update and linking to related non-member functions -- [Using Insertion Operators and Controlling Format](../standard-library/using-insertion-operators-and-controlling-format.md) - fix `setw` code example -- [`` operators](../standard-library/chrono-operators.md) - Added new C++20 chrono operators -- [`local_info` struct](../standard-library/local-info-struct.md) - updated descriptions for errors -- [`time_zone` class](../standard-library/time-zone-class.md) - article clarifications -- [`any` class](../standard-library/any-class.md) - Added requirements section -- [`` functions](../standard-library/any-functions.md) - Added requirements section -- [`bad_any_cast` class](../standard-library/bad-any-cast-class.md) - Added requirements section -- [domain_error Class](../standard-library/domain-error-class.md) - Improve `` documentation and examples -- [invalid_argument Class](../standard-library/invalid-argument-class.md) - Improve `` documentation and examples -- [length_error Class](../standard-library/length-error-class.md) - Improve `` documentation and examples -- [logic_error Class](../standard-library/logic-error-class.md) - Improve `` documentation and examples -- [out_of_range Class](../standard-library/out-of-range-class.md) - Improve `` documentation and examples -- [overflow_error Class](../standard-library/overflow-error-class.md) - Improve `` documentation and examples -- [range_error Class](../standard-library/range-error-class.md) - Improve `` documentation and examples -- [runtime_error Class](../standard-library/runtime-error-class.md) - Improve `` documentation and examples -- [underflow_error Class](../standard-library/underflow-error-class.md) - Improve `` documentation and examples -- [`filesystem`](../standard-library/filesystem.md) - `` no longer includes `` -- [Output File Stream Member Functions](../standard-library/output-file-stream-member-functions.md) - fixed code example -- [`` functions](../standard-library/bit-functions.md) - Fixed code example -- [``](../standard-library/execution.md) - Mention limits of concurrency -- [`` functions](../standard-library/future-functions.md) - Mention limits of concurrency -- [`thread` Class](../standard-library/thread-class.md) - Mention limits of concurrency - -## Overview of Windows programming in C++ - -### New articles - -- [Microsoft Visual C++ Redistributable Latest Supported Downloads](../windows/latest-supported-vc-redist.md) - -### Updated articles - -- [Walkthrough: Create a traditional Windows Desktop application (C++)](../windows/walkthrough-creating-windows-desktop-applications-cpp.md) - updated examples - -## Read and write code using C++ in Visual Studio - -### New articles - -- [IntelliSense code linter for C++ overview](../ide/cpp-linter-overview.md) -- [`lnt-assignment-equality`](../ide/lnt-assignment-equality.md) -- [`lnt-integer-float-division`](../ide/lnt-integer-float-division.md) -- [`lnt-accidental-copy`](../ide/lnt-accidental-copy.md) -- [`lnt-arithmetic-overflow`](../ide/lnt-arithmetic-overflow.md) -- [`lnt-logical-bitwise-mismatch`](../ide/lnt-logical-bitwise-mismatch.md) -- [`lnt-uninitialized-local`](../ide/lnt-uninitialized-local.md) - -### Updated articles - -- [`lnt-integer-float-division`](../ide/lnt-integer-float-division.md) - Add Visual Studio 2022 specific config information - -## STL/CLR library reference - -### Updated articles - -- [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md) - updated instructions for Visual Studio version UI differences - -## Community contributors - -The following people contributed to the C++, C, and Assembler docs during this period. Thank you! See [Microsoft Docs contributor guide overview](/contribute/) if you'd like to learn how to contribute. - -- [mohammad-ghasemi-2549](https://github.com/mohammad-ghasemi-2549) (5) -- [Jaiganeshkumaran](https://github.com/Jaiganeshkumaran) - Jaiganesh Kumaran (2) -- [workingjubilee](https://github.com/workingjubilee) - Jubilee (2) -- [adr26](https://github.com/adr26) (1) -- [AlexGuteniev](https://github.com/AlexGuteniev) - Alex Guteniev (1) -- [AzAgarampur](https://github.com/AzAgarampur) - Arush Agarampur (1) -- [d-c-d](https://github.com/d-c-d) - David Dyck (1) -- [onihusube](https://github.com/onihusube) (1) -- [rayz-bee](https://github.com/rayz-bee) - rayz-bee (1) -- [redteamrover](https://github.com/redteamrover) (1) -- [RibShark](https://github.com/RibShark) (1) -- [sauparna](https://github.com/sauparna) - Sauparna Palchowdhury (1) -- [sudoerChris](https://github.com/sudoerChris) - Chris Ho (1) -- [thispsj](https://github.com/thispsj) - PSJ (1) -- [Veverke](https://github.com/Veverke) - Avraham (1) -- [weijiechai](https://github.com/weijiechai) - Chai Wei Jie (1) -- [wmcnamara](https://github.com/wmcnamara) - Weston McNamara (1) -- [ystamant](https://github.com/ystamant) (1) - -## What's new history - -The following section provides the previous update of what's new in the Visual Studio docs. - -### June 2021 - -#### Build insights - -**New articles** - -- [HeaderUnit class](../build-insights/reference/sdk/cpp-event-data-types/header-unit.md) -- [Module class](../build-insights/reference/sdk/cpp-event-data-types/module.md) -- [PrecompiledHeader class](../build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md) -- [TRANSLATION_UNIT_TYPE enum](../build-insights/reference/sdk/c-event-data-types/translation-unit-type.md) -- [TRANSLATION_UNIT_TYPE_DATA enum](../build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md) -- [TranslationUnitType class](../build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md) - -**Updated articles** - -- [C++ Build Insights SDK: event table](../build-insights/reference/sdk/event-table.md) - add new C++ Build Insights events -- [Get started with C++ Build Insights](../build-insights/get-started-with-cpp-build-insights.md) - add new C++ Build Insights events - -#### C language - -**Updated articles** - -- [`_Static_assert` keyword and `static_assert` macro (C11)](../c-language/static-assert-c.md) - update the SDK to use -- [Alignment (C11)](../c-language/alignment-c.md) - update the SDK to use -- [Generic selection (C11)](../c-language/generic-selection.md) - update the SDK to use - -#### C runtime library - -**Updated articles** - -Many articles were updated to prevent the machine translation of code elements. - -- [`_cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l`](../c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md) - `printf()` rounding behavior change -- [`_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l`](../c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) - `printf()` rounding behavior change -- [`_cprintf, _cprintf_l, _cwprintf, _cwprintf_l`](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) - `printf()` rounding behavior change -- [`_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l`](../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md) - `printf()` rounding behavior change -- [`_get_printf_count_output`](../c-runtime-library/reference/get-printf-count-output.md) - `printf()` rounding behavior change -- [`_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l`](../c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) - `printf()` rounding behavior change -- [`_scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l`](../c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md) - `printf()` rounding behavior change -- [`_scprintf, _scprintf_l, _scwprintf, _scwprintf_l`](../c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md) - `printf()` rounding behavior change -- [`_vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l`](../c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md) - `printf()` rounding behavior change -- [`_vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l`](../c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md) - `printf()` rounding behavior change -- [`_vscprintf, _vscprintf_l, _vscwprintf, _vscwprintf_l`](../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) - `printf()` rounding behavior change -- [`_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l`](../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md) - `printf()` rounding behavior change -- [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) - `printf()` rounding behavior change -- [`errno` constants](../c-runtime-library/errno-constants.md) - improve readability -- [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) - `printf()` rounding behavior change -- [`freopen_s`, `_wfreopen_s`](../c-runtime-library/reference/freopen-s-wfreopen-s.md) - new C11 flags -- [`freopen`, `_wfreopen`](../c-runtime-library/reference/freopen-wfreopen.md) - added C11 flags -- [`pow`, `powf`, `powl`](../c-runtime-library/reference/pow-powf-powl.md) - note change to `pow(T,int)` starting in VS 2015 update 1 -- [`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) - `printf()` rounding behavior change -- [`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md) - clarified UTF-8 string mode -- [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) - `printf()` rounding behavior change -- [`cprintf`](../c-runtime-library/reference/cprintf.md) - `printf()` rounding behavior change -- [`fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l`](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) - `printf()` rounding behavior change -- [`sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) - `printf()` rounding behavior change -- [`strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l`](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md) - fixed code examples -- [`strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l`](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) - `printf()` rounding behavior change -- [Type-generic math](../c-runtime-library/tgmath.md) - updated the SDK version to use -- [`vprintf, _vprintf_l, vwprintf, _vwprintf_l`](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) - `printf()` rounding behavior change -- [`vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l`](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) - `printf()` rounding behavior change - -#### C++ in Visual Studio - -**Updated articles** - -- [`_variant_t::operator=`](../cpp/variant-t-operator-equal.md) - add remarks for `operator=` and make the article easier to read. -- [Abstract classes (C++)](../cpp/abstract-classes-cpp.md) - add Microsoft-specific extension information for inline pure virtual destructor -- [Attributes in C++](../cpp/attributes.md) - add missing errors and warnings: C7000-C7999, C4834 -- [char, wchar_t, char8_t, char16_t, char32_t](../cpp/char-wchar-t-char16-t-char32-t.md) - clarified whether char is signed or unsigned - -#### C++ porting and upgrade guide - -**Updated articles** - -- [Introduction to Microsoft C++ for UNIX Users](../porting/introduction-to-visual-cpp-for-unix-users.md) - Visual Studio 16.10 updates to C17 conformance -- [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md) - note change to `pow(T,int)` starting in VS 2015 update 1 - -#### C/C++ compiler and tools errors and warnings - -**New articles** - -- [Command-line error D8048](../error-messages/tool-errors/command-line-error-d8048.md) -- [Compiler Error C7510](../error-messages/compiler-errors-2/compiler-error-c7510.md) -- [Compiler Error C7536](../error-messages/compiler-errors-2/compiler-error-c7536.md) -- [Compiler errors C7000 through C7499](../error-messages/compiler-errors-2/compiler-errors-c7000-through-c7499.md) -- [Compiler errors C7500 through C7999](../error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md) -- [Compiler Warning (error) C4597](../error-messages/compiler-warnings/c4597.md) -- [Compiler warning (level 1) C4834](../error-messages/compiler-warnings/c4834.md) -- [Compiler Warning (level 1) C5050](../error-messages/compiler-warnings/c5050.md) -- [Compiler warning (level 3) C4698](../error-messages/compiler-warnings/c4698.md) -- [Compiler Warning (level 3) C4768](../error-messages/compiler-warnings/c4768.md) -- [Compiler Warning (level 4) C4841](../error-messages/compiler-warnings/c4841.md) -- [Compiler Warning (level 4) C4843](../error-messages/compiler-warnings/c4843.md) -- [Compiler warning C5037](../error-messages/compiler-warnings/c5037.md) -- [Fatal Error C1090](../error-messages/compiler-errors-1/fatal-error-c1090.md) - -**Updated articles** - -- [Compiler Error C2139](../error-messages/compiler-errors-1/compiler-error-c2139.md) - added some version 2017 diagnostics -- [Compiler Error C2201](../error-messages/compiler-errors-1/compiler-error-c2201.md) - added some version 2017 diagnostics -- [Compiler Error C2276](../error-messages/compiler-errors-1/compiler-error-c2276.md) - update C2276 -- [Compiler Error C2668](../error-messages/compiler-errors-2/compiler-error-c2668.md) - added some version 2017 diagnostics -- [Compiler Error C2855](../error-messages/compiler-errors-2/compiler-error-c2855.md) - add remarks about how to resolve this error -- [Compiler errors C2000 - C3999, C7000 - C7999](../error-messages/compiler-errors-1/compiler-errors-c2000-c3999.md) - add missing errors and warnings: C7000-C7999, C4834 -- [Compiler errors C7500 through C7999](../error-messages/compiler-errors-2/compiler-errors-c7500-through-c7999.md) - added some version 2017 diagnostics; add error C7510; add missing errors and warnings: C7000-C7999, C4834 -- [Compiler Warning (level 1) C4179](../error-messages/compiler-warnings/compiler-warning-level-1-c4179.md) - added some version 2017 diagnostics -- [Compiler Warning (level 1) C5208 and Error C7626](../error-messages/compiler-warnings/c5208.md) - add missing errors and warnings: C7000-C7999, C4834 -- [Compiler Warning (level 4) C4189](../error-messages/compiler-warnings/compiler-warning-level-4-c4189.md) - added some version 2017 diagnostics -- [Compiler Warning C5038](../error-messages/compiler-warnings/c5038.md) - added some version 2017 diagnostics -- [Compiler warnings by compiler version](../error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md) - update Visual Studio 16.10 conformance improvements and new warnings; Add new 16.10 warnings, version info; update version strings for Visual Studio 16.8, 16.9, and 16.10 -- [Compiler warnings C4400 Through C4599](../error-messages/compiler-warnings/compiler-warnings-c4400-through-c4599.md) - added some Visual Studio version 2017 diagnostics -- [Compiler warnings C4800 through C5999](../error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md) - update Visual Studio 16.10 conformance improvements and new warnings; add new 16.10 warnings, version info; added some version 2017 diagnostics; add missing errors and warnings: C7000 - C7999, C4834 -- [Vectorizer and parallelizer messages](../error-messages/tool-errors/vectorizer-and-parallelizer-messages.md) - add vectorizer failure reason 505; add 1204 reason code - -#### C/C++ compiler intrinsics and assembly language - -**Updated articles** - -- [Microsoft Macro Assembler BNF Grammar](../assembler/masm/masm-bnf-grammar.md) - cleanup formatting and machine translation issues - -#### C/C++ in Visual Studio overview - -**New articles** - -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2017](../overview/cpp-conformance-improvements-2017.md) -- [Microsoft C++ docs: What's new for Visual Studio 16.8](../overview/whats-new-cpp-docs.md) -- [What's new for C++ in Visual Studio 2017](../overview/what-s-new-for-cpp-2017.md) - -**Updated articles** - -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2017](../overview/cpp-conformance-improvements-2017.md) - added version 2017 diagnostics -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2019](../overview/cpp-conformance-improvements.md) - Visual Studio 16.10 updates to C17 conformance; update 16.10 conformance improvements and new warnings; add error C7510; add missing errors and warnings: C7000 - C7999, C4834; update conformance docs for 16.9 -- [C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md) - Visual Studio 16.10 updates to C17 conformance -- [Install C11 and C17 support in Visual Studio](../overview/install-c17-support.md) - Visual Studio 16.10 updates to C17 conformance -- [Microsoft C/C++ language conformance by Visual Studio version](../overview/visual-cpp-language-conformance.md) - Visual Studio 16.10 updates to C17 conformance; update conformance table for Visual Studio 16.10 and Visual Studio 16.9 -- [Microsoft C++ docs: What's new for Visual Studio 16.8](../overview/whats-new-cpp-docs.md) - Visual Studio 16.10 updates to C17 conformance -- [What's new for C++ in Visual Studio 2017](../overview/what-s-new-for-cpp-2017.md) - Visual Studio 16.10 updates to C17 conformance; update Visual Studio 16.9 release conformance docs - -#### C/C++ preprocessor reference - -**Updated articles** - -- [Compiler warnings that are off by default](../preprocessor/compiler-warnings-that-are-off-by-default.md) - update Visual Studio 16.10 conformance improvements and new warnings; added some version 2017 diagnostics -- [Predefined macros](../preprocessor/predefined-macros.md) - add new Visual Studio 16.10 warnings, version info; update version strings for Visual Studio 16.8, 16.9, and 16.10 - -#### C/C++ projects and build systems - -**New articles** - -- [`/external` (External headers diagnostics)](../build/reference/external-external-headers-diagnostics.md) -- [`/headerName` (Build a header unit from the specified header)](../build/reference/headername.md) -- [`/sourceDependencies:directives` (List module and header unit dependencies)](../build/reference/sourcedependencies-directives.md) -- [`CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps](../build/cmake-presets-json-reference.md) -- [Configure and build with CMake Presets in Visual Studio](../build/cmake-presets-vs.md) -- [HeaderUnit class](../build-insights/reference/sdk/cpp-event-data-types/header-unit.md) -- [Module class](../build-insights/reference/sdk/cpp-event-data-types/module.md) -- [PrecompiledHeader class](../build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md) -- [TRANSLATION_UNIT_TYPE enum](../build-insights/reference/sdk/c-event-data-types/translation-unit-type.md) -- [TRANSLATION_UNIT_TYPE_DATA enum](../build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md) -- [TranslationUnitType class](../build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md) -- [Walkthrough: Build and import header units in Microsoft Visual C++](../build/walkthrough-header-units.md) -- [Walkthrough: Import STL libraries as header units](../build/walkthrough-import-stl-header-units.md) - -**Updated articles** - -- [/experimental:module (Enable module support)](../build/reference/experimental-module.md) - new content for header-units -- [/Qspectre](../build/reference/qspectre.md) - update for VS 2019 -- [/Y (precompiled headers)](../build/reference/y-precompiled-headers.md) - new content for header-units -- [`/analyze` (Code analysis)](../build/reference/analyze-code-analysis.md) - update with up-to-date options list, add more information, and restructure for better organization of related options -- [`/await` (Enable coroutine support)](../build/reference/await-enable-coroutine-support.md) - add `/await:strict` for Visual Studio 16.10 -- [`/clr` (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) - include version for support of `/clr:netcore` option -- [`/exportHeader` (Create header units)](../build/reference/module-exportheader.md) - add new content related to header-units -- [`/external` (External headers diagnostics)](../build/reference/external-external-headers-diagnostics.md) - `/external` not experimental in Visual Studio 16.10 -- [`/F` (Set Stack Size)](../build/reference/f-set-stack-size.md) - update for VS 2019 -- [`/FC` (Full path of source code file in diagnostics)](../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md) - Classify behavior by version. -- [`/GL` (Whole program optimization)](../build/reference/gl-whole-program-optimization.md) - fix loc issue in /GL docs -- [`/headerUnit` (Use header unit IFC)](../build/reference/headerunit.md) - new content for header-units -- [`/INTEGRITYCHECK` (Require signature check)](../build/reference/integritycheck-require-signature-check.md) - updated signing guidance for `integritycheck` binaries -- [`/openmp` (Enable OpenMP Support)](../build/reference/openmp-enable-openmp-2-0-support.md) - add /openmp:llvm compiler switch docs -- [`/reference` (Use named module IFC)](../build/reference/module-reference.md) - new content for header-units -- [`/sourceDependencies` (List all source-level dependencies)](../build/reference/sourcedependencies.md) - new content for header-units -- [`/std` (Specify Language Standard Version)](../build/reference/std-specify-language-standard-version.md) - Visual Studio 16.10 updates to C17 conformance -- [`/translateInclude` (Translate include directives into import directives)](../build/reference/translateinclude.md) - new content for header-units -- [Advanced Property Page](../build/reference/advanced-property-page.md) - add Windows Desktop Compatible property for Visual Studio 16.10; Add LLVM toolset version option for Visual Studio 16.9 -- [ARM Exception Handling](../build/arm-exception-handling.md) - fix `ComputeXdataSize` samples for ARM/ARM64 -- [ARM64 exception handling](../build/arm64-exception-handling.md) - fix `ComputeXdataSize` samples for ARM/ARM64 -- [C++ Build Insights SDK: event table](../build-insights/reference/sdk/event-table.md) - add New C++ Build Insights Events to documentation -- [Clang/LLVM support in Visual Studio projects](../build/clang-support-msbuild.md) - add LLVM toolset version option for Visual Studio 16.9; update clang-support-msbuild.md -- [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md) - add advanced details about using CMake file-api -- [Compiler options listed alphabetically](../build/reference/compiler-options-listed-alphabetically.md) - new content for header-units -- [Compiler options listed by category](../build/reference/compiler-options-listed-by-category.md) - new content for header-units -- [Configure and build with CMake Presets in Visual Studio](../build/cmake-presets-vs.md) - improve readability -- [General Property Page (Project)](../build/reference/general-property-page-project.md) - add Windows Desktop Compatible property for Visual Studio 16.10 -- [Get started with C++ Build Insights](../build-insights/get-started-with-cpp-build-insights.md) - add New C++ Build Insights Events to documentation -- [How to: Modify the Target Framework and Platform Toolset](../build/how-to-modify-the-target-framework-and-platform-toolset.md) - improve readability -- [Open Folder support for C++ build systems in Visual Studio](../build/open-folder-projects-cpp.md) - fix CppProperties.json MinGW-w64 contents -- [Unicode support in the compiler and linker](../build/reference/unicode-support-in-the-compiler-and-linker.md) - add info about how to save using a different encoding -- [Use the Microsoft C++ toolset from the command line](../build/building-on-the-command-line.md) - updated for VS 2019 -- [Walkthrough: Compile a C program on the command line](../build/walkthrough-compile-a-c-program-on-the-command-line.md) - Visual Studio 16.10 updates to C17 conformance -- [Walkthrough: Compiling a Native C++ Program on the Command Line](../build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md) - clarified notepad behavior when opening source file - -#### C++ Standard Library (STL) reference - -**New articles** - -- [``](../standard-library/ranges.md) -- [`day` class](../standard-library/day-class.md) -- [`month_day_last` class](../standard-library/month-day-last-class.md) -- [`month_day` class](../standard-library/month-day-class.md) -- [`month_weekday_last` class](../standard-library/month-weekday-last-class.md) -- [`month_weekday` class](../standard-library/month-weekday-class.md) -- [`year_month` class](../standard-library/year-month-class.md) - -**Updated articles** - -- [`bitset` class](../standard-library/bitset-class.md) - improve readability -- [`vector` class](../standard-library/vector-class.md) - fix typo in code sample - -#### Code quality - -**New articles** - -- [C6389: MARK_INTERNAL_OR_MISSING_COMMON_DECL](../code-quality/c6389.md) - -**Updated articles** - -- [C6031](../code-quality/c6031.md) - add note about ignoring a function's return value -- [C26432 DEFINE_OR_DELETE_SPECIAL_OPS](../code-quality/c26432.md) - update code examples -- [C26497 USE_CONSTEXPR_FOR_FUNCTION](../code-quality/c26497.md) - add note about when warning won't be issued - -#### Linux with C++ in Visual Studio - -**Updated articles** - -- [Connect to your target Linux system in Visual Studio](../linux/connect-to-your-remote-linux-computer.md) - add section about host key verification -- [ConnectionManager reference](../linux/connectionmanager-reference.md) - add note about host key fingerprint flags added in Visual Studio 16.10. - -#### Overview of Windows programming in C++ - -**Updated articles** - -- [Determining Which DLLs to Redistribute](../windows/determining-which-dlls-to-redistribute.md) - updated for Visual Studio 2019 - -#### Parallel programming in C++ in Visual Studio - -**Updated articles** - -- [C++ AMP Overview](../parallel/amp/cpp-amp-overview.md) - add note about C++ AMP library deprecation -- [Walkthrough: Debugging a C++ AMP application](../parallel/amp/walkthrough-debugging-a-cpp-amp-application.md) - fixed code sample - -#### Community contributors - -The following people contributed to the C++, C, and Assembler docs during this period. Thank you! See [Microsoft Docs contributor guide overview](/contribute/) if you'd like to learn how to contribute. - -- [0xbadfca11](https://github.com/0xbadfca11) (1) -- [bclehmann](https://github.com/bclehmann) - Benjamin Lehmann (1) -- [Brian-Taylor8](https://github.com/Brian-Taylor8) (1) -- [cartwrightluke](https://github.com/cartwrightluke) (2) -- [ccawley2011](https://github.com/ccawley2011) - Cameron Cawley (1) -- [EddieBreeveld](https://github.com/EddieBreeveld) - Edward Breeveld (1) -- [FrankAtHexagon](https://github.com/FrankAtHexagon) - Frank Edwards (1) -- [fsb4000](https://github.com/fsb4000) - Igor Zhukov (1) -- [Jaiganeshkumaran](https://github.com/Jaiganeshkumaran) - Jaiganesh Kumaran (2) -- [jayvient](https://github.com/jayvient) - Jayvien (1) -- [KishkinJ10](https://github.com/KishkinJ10) (1) -- [kokosxD](https://github.com/kokosxD) - kokos (1) -- [langemol](https://github.com/langemol) - Jacco Mol (1) -- [MUzairS15](https://github.com/MUzairS15) (1) -- [nadavsu](https://github.com/nadavsu) - Nadav (1) -- [NegiAkash890](https://github.com/NegiAkash890) - Akash Negi (1) -- [pjessesco](https://github.com/pjessesco) - Jino Park (1) -- [pramodkirchki](https://github.com/pramodkirchki) (1) -- [Radfordhound](https://github.com/Radfordhound) - Graham Scott (1) -- [sapant-msft](https://github.com/sapant-msft) (1) -- [sebgod](https://github.com/sebgod) - Sebastian Godelet (1) -- [seedkar1](https://github.com/seedkar1) (1) -- [ShamanCoder](https://github.com/ShamanCoder) (1) -- [sheila-stewart](https://github.com/sheila-stewart) (1) -- [softmac](https://github.com/softmac) (1) -- [Thieum](https://github.com/Thieum) - Matthieu Penant (2) -- [tjs137](https://github.com/tjs137) (1) -- [urmyfaith](https://github.com/urmyfaith) - zx (1) -- [ValZapod](https://github.com/ValZapod) - Valerii Zapodovnikov (1) -- [westinn](https://github.com/westinn) - Nicolas Westin (1) \ No newline at end of file diff --git a/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md b/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md index 10d5f9f5a2..d4b2d50056 100644 --- a/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md +++ b/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md @@ -3,12 +3,15 @@ description: "Learn more about: C++ AMP (C++ Accelerated Massive Parallelism)" title: "C++ AMP (C++ Accelerated Massive Parallelism)" ms.date: "11/04/2016" helpviewer_keywords: ["C++ AMP (see C++ Accelerated Massive Parallelism)", "C++ Accelerated Massive Parallelism, getting started"] -ms.assetid: e27824cb-3167-409b-8c3f-a0e476d8f349 --- # C++ AMP (C++ Accelerated Massive Parallelism) C++ AMP (C++ Accelerated Massive Parallelism) accelerates the execution of your C++ code by taking advantage of the data-parallel hardware that's commonly present as a graphics processing unit (GPU) on a discrete graphics card. The C++ AMP programming model includes support for multidimensional arrays, indexing, memory transfer, and tiling. It also includes a mathematical function library. You can use C++ AMP language extensions to control how data is moved from the CPU to the GPU and back. +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. + ## Related Topics |Title|Description| diff --git a/docs/parallel/amp/cpp-amp-overview.md b/docs/parallel/amp/cpp-amp-overview.md index 0591dea93e..c6d4d0fb20 100644 --- a/docs/parallel/amp/cpp-amp-overview.md +++ b/docs/parallel/amp/cpp-amp-overview.md @@ -3,12 +3,11 @@ description: "Learn more about: C++ AMP Overview" title: "C++ AMP Overview" ms.date: "11/19/2018" helpviewer_keywords: ["C++ Accelerated Massive Parallelism, requirements", "C++ Accelerated Massive Parallelism, architecture", "C++ AMP", "C++ Accelerated Massive Parallelism, overview", "C++ Accelerated Massive Parallelism"] -ms.assetid: 9e593b06-6e3c-43e9-8bae-6d89efdd39fc --- # C++ AMP Overview > [!NOTE] -> C++ AMP headers are deprecated, starting with Visual Studio 2022 version 17.0. +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. > Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. C++ Accelerated Massive Parallelism (C++ AMP) accelerates execution of C++ code by taking advantage of data-parallel hardware such as a graphics processing unit (GPU) on a discrete graphics card. By using C++ AMP, you can code multi-dimensional data algorithms so that execution can be accelerated by using parallelism on heterogeneous hardware. The C++ AMP programming model includes multidimensional arrays, indexing, memory transfer, tiling, and a mathematical function library. You can use C++ AMP language extensions to control how data is moved from the CPU to the GPU and back, so that you can improve performance. @@ -17,7 +16,7 @@ C++ Accelerated Massive Parallelism (C++ AMP) accelerates execution of C++ code - Windows 7 or later -- Windows Server 2008 R2 or later +- Windows Server 2008 R2 through Visual Studio 2019. - DirectX 11 Feature Level 11.0 or later hardware @@ -232,9 +231,9 @@ The following table summarizes the similarities and differences between the `arr Shared memory is memory that can be accessed by both the CPU and the accelerator. The use of shared memory eliminates or significantly reduces the overhead of copying data between the CPU and the accelerator. Although the memory is shared, it cannot be accessed concurrently by both the CPU and the accelerator, and doing so causes undefined behavior. -`array` objects can be used to specify fine-grained control over the use of shared memory if the associated accelerator supports it. Whether an accelerator supports shared memory is determined by the accelerator’s [supports_cpu_shared_memory](reference/accelerator-class.md#supports_cpu_shared_memory) property, which returns **`true`** when shared memory is supported. If shared memory is supported, the default [access_type Enumeration](reference/concurrency-namespace-enums-amp.md#access_type) for memory allocations on the accelerator is determined by the `default_cpu_access_type` property. By default, `array` and `array_view` objects take on the same `access_type` as the primary associated `accelerator`. +`array` objects can be used to specify fine-grained control over the use of shared memory if the associated accelerator supports it. Whether an accelerator supports shared memory is determined by the accelerator's [supports_cpu_shared_memory](reference/accelerator-class.md#supports_cpu_shared_memory) property, which returns **`true`** when shared memory is supported. If shared memory is supported, the default [access_type Enumeration](reference/concurrency-namespace-enums-amp.md#access_type) for memory allocations on the accelerator is determined by the `default_cpu_access_type` property. By default, `array` and `array_view` objects take on the same `access_type` as the primary associated `accelerator`. -By setting the [array::cpu_access_type Data Member](reference/array-class.md#cpu_access_type) property of an `array` explicitly, you can exercise fine-grained control over how shared memory is used, so that you can optimize the app for the hardware’s performance characteristics, based on the memory access patterns of its computation kernels. An `array_view` reflects the same `cpu_access_type` as the `array` that it’s associated with; or, if the array_view is constructed without a data source, its `access_type` reflects the environment that first causes it to allocate storage. That is, if it’s first accessed by the host (CPU), then it behaves as if it were created over a CPU data source and shares the `access_type` of the `accelerator_view` associated by capture; however, if it's first accessed by an `accelerator_view`, then it behaves as if it were created over an `array` created on that `accelerator_view` and shares the `array`’s `access_type`. +By setting the [array::cpu_access_type Data Member](reference/array-class.md#cpu_access_type) property of an `array` explicitly, you can exercise fine-grained control over how shared memory is used, so that you can optimize the app for the hardware's performance characteristics, based on the memory access patterns of its computation kernels. An `array_view` reflects the same `cpu_access_type` as the `array` that it's associated with; or, if the array_view is constructed without a data source, its `access_type` reflects the environment that first causes it to allocate storage. That is, if it's first accessed by the host (CPU), then it behaves as if it were created over a CPU data source and shares the `access_type` of the `accelerator_view` associated by capture; however, if it's first accessed by an `accelerator_view`, then it behaves as if it were created over an `array` created on that `accelerator_view` and shares the `array`'s `access_type`. The following code example shows how to determine whether the default accelerator supports shared memory, and then creates several arrays that have different cpu_access_type configurations. @@ -248,7 +247,7 @@ int main() { accelerator acc = accelerator(accelerator::default_accelerator); - // Early out if the default accelerator doesn’t support shared memory. + // Early out if the default accelerator doesn't support shared memory. if (!acc.supports_cpu_shared_memory) { std::cout << "The default accelerator does not support shared memory" << std::endl; @@ -425,7 +424,7 @@ for (int i = 0; i <4; i++) { ## Math Libraries -C++ AMP includes two math libraries. The double-precision library in the [Concurrency::precise_math Namespace](../../parallel/amp/reference/concurrency-precise-math-namespace.md) provides support for double-precision functions. It also provides support for single-precision functions, although double-precision support on the hardware is still required. It conforms to the [C99 Specification (ISO/IEC 9899)](https://go.microsoft.com/fwlink/p/?linkid=225887). The accelerator must support full double precision. You can determine whether it does by checking the value of the [accelerator::supports_double_precision Data Member](reference/accelerator-class.md#supports_double_precision). The fast math library, in the [Concurrency::fast_math Namespace](../../parallel/amp/reference/concurrency-fast-math-namespace.md), contains another set of math functions. These functions, which support only **`float`** operands, execute more quickly but aren’t as precise as those in the double-precision math library. The functions are contained in the \ header file and all are declared with `restrict(amp)`. The functions in the \ header file are imported into both the `fast_math` and `precise_math` namespaces. The **`restrict`** keyword is used to distinguish the \ version and the C++ AMP version. The following code calculates the base-10 logarithm, using the fast method, of each value that is in the compute domain. +C++ AMP includes two math libraries. The double-precision library in the [Concurrency::precise_math Namespace](../../parallel/amp/reference/concurrency-precise-math-namespace.md) provides support for double-precision functions. It also provides support for single-precision functions, although double-precision support on the hardware is still required. It conforms to the [C99 Specification (ISO/IEC 9899)](https://go.microsoft.com/fwlink/p/?linkid=225887). The accelerator must support full double precision. You can determine whether it does by checking the value of the [accelerator::supports_double_precision Data Member](reference/accelerator-class.md#supports_double_precision). The fast math library, in the [Concurrency::fast_math Namespace](../../parallel/amp/reference/concurrency-fast-math-namespace.md), contains another set of math functions. These functions, which support only **`float`** operands, execute more quickly but aren't as precise as those in the double-precision math library. The functions are contained in the \ header file and all are declared with `restrict(amp)`. The functions in the \ header file are imported into both the `fast_math` and `precise_math` namespaces. The **`restrict`** keyword is used to distinguish the \ version and the C++ AMP version. The following code calculates the base-10 logarithm, using the fast method, of each value that is in the compute domain. ```cpp #include diff --git a/docs/parallel/amp/graphics-cpp-amp.md b/docs/parallel/amp/graphics-cpp-amp.md index c0740ec892..2de8ab623c 100644 --- a/docs/parallel/amp/graphics-cpp-amp.md +++ b/docs/parallel/amp/graphics-cpp-amp.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Graphics (C++ AMP)" title: "Graphics (C++ AMP)" -ms.date: "11/04/2016" -ms.assetid: 190a98a4-5f7d-442e-866b-b374ca74c16f +description: "Learn more about: Graphics (C++ AMP)" +ms.date: 11/04/2016 --- # Graphics (C++ AMP) -C++ AMP contains several APIs in the [Concurrency::graphics](../../parallel/amp/reference/concurrency-graphics-namespace.md) namespace that you can use to access the texture support on GPUs. Some common scenarios are: +C++ AMP contains several APIs in the [`Concurrency::graphics`](../../parallel/amp/reference/concurrency-graphics-namespace.md) namespace that you can use to access the texture support on GPUs. Some common scenarios are: -- You can use the [texture](../../parallel/amp/reference/texture-class.md) class as a data container for computation and exploit the *spatial locality* of the texture cache and layouts of GPU hardware. Spatial locality is the property of data elements being physically close to each other. +- You can use the [`texture`](../../parallel/amp/reference/texture-class.md) class as a data container for computation and exploit the *spatial locality* of the texture cache and layouts of GPU hardware. Spatial locality is the property of data elements being physically close to each other. - The runtime provides efficient interoperability with non-compute shaders. Pixel, vertex, tessellation, and hull shaders frequently consume or produce textures that you can use in your C++ AMP computations. - The graphics APIs in C++ AMP provide alternative ways to access sub-word packed buffers. Textures that have formats that represent *texels* (texture elements) that are composed of 8-bit or 16-bit scalars allow access to such packed data storage. +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. + ## The norm and unorm Types -The `norm` and `unorm` types are scalar types that limit the range of **`float`** values; this is known as *clamping*. These types can be explicitly constructed from other scalar types. In casting, the value is first cast to **`float`** and then clamped to the respective region that's allowed by norm [-1.0, 1.0] or unorm [0.0, 1.0]. Casting from +/- infinity returns +/-1. Casting from NaN is undefined. A norm can be implicitly constructed from a unorm and there is no loss of data. The implicit conversion operator to float is defined on these types. Binary operators are defined between these types and other built-in scalar types such as **`float`** and **`int`**: +, -, \*, /, ==, !=, >, \<, >=, <=. The compound assignment operators are also supported: +=, -=, \*=, /=. The unary negation operator (-) is defined for norm types. +The `norm` and `unorm` types are scalar types that limit the range of **`float`** values; this is known as *clamping*. These types can be explicitly constructed from other scalar types. In casting, the value is first cast to **`float`** and then clamped to the respective region that's allowed by `norm [-1.0, 1.0]` or `unorm [0.0, 1.0]`. Casting from +/- infinity returns +/-1. Casting from NaN is undefined. A `norm` can be implicitly constructed from a `unorm` and there is no loss of data. The implicit conversion operator to **`float`** is defined on these types. Binary operators are defined between these types and other built-in scalar types such as **`float`** and **`int`**: `+`, `-`, `*`, `/`, `==`, `!=`, `>`, `<`, `>=`, `<=`. The compound assignment operators are also supported: `+=`, `-=`, `*=`, `/=`. The unary negation operator (`-`) is defined for `norm` types. ## Short Vector Library @@ -35,20 +38,20 @@ The Short Vector Library provides some of the functionality of the [Vector Type] If an operator is defined between two short vectors, then it is also defined between a short vector and a scalar. Also, one of these must be true: -- The scalar’s type must be the same as the short vector’s element type. +- The scalar's type must be the same as the short vector's element type. -- The scalar’s type can be implicitly converted to the vector’s element type by using only one user-defined conversion. +- The scalar's type can be implicitly converted to the vector's element type by using only one user-defined conversion. The operation is carried component-wise between each component of the short vector and the scalar. Here are the valid operators: |Operator type|Valid types| |-------------------|-----------------| -|Binary operators|Valid on all types: +, -, \*, /,

Valid on integer types: %, ^, |, &, <\<, >>

The two vectors must have the same size, and the result is a vector of the same size.| -|Relational operators|Valid on all types: == and !=| -|Compound assignment operator|Valid on all types: +=, -=, \*=, /=

Valid on integer types: %=, ^=, |=, &=, <\<=, >>=| -|Increment and decrement operators|Valid on all types: ++, --

Both prefix and postfix are valid.| -|Bitwise NOT operator (~)|Valid on integer types.| -|Unary - operator|Valid on all types except `unorm` and `uint`.| +|Binary operators|Valid on all types: `+`, `-`, `*`, `/`,

Valid on integer types: `%`, `^`, `|`, `&`, `<<`, `>>`

The two vectors must have the same size, and the result is a vector of the same size.| +|Relational operators|Valid on all types: `==` and `!=`| +|Compound assignment operator|Valid on all types: `+=`, `-=`, `*=`, `/=`

Valid on integer types: `%=`, `^=`, `|=`, `&=`, `<<=`, `>>=`| +|Increment and decrement operators|Valid on all types: `++`, `--`

Both prefix and postfix are valid.| +|Bitwise NOT operator (`~`)|Valid on integer types.| +|Unary `-` operator|Valid on all types except `unorm` and `uint`.| ### Swizzling Expressions @@ -56,7 +59,7 @@ The Short Vector Library supports the `vector_type.identifier` accessor construc ## Texture Classes -Many GPUs have hardware and caches that are optimized to fetch pixels and texels and to render images and textures. The [texture\](../../parallel/amp/reference/texture-class.md) class, which is a container class for texel objects, exposes the texture functionality of these GPUs. A texel can be: +Many GPUs have hardware and caches that are optimized to fetch pixels and texels and to render images and textures. The [`texture`](../../parallel/amp/reference/texture-class.md) class, which is a container class for texel objects, exposes the texture functionality of these GPUs. A texel can be: - An **`int`**, `uint`, **`float`**, **`double`**, `norm`, or `unorm` scalar. @@ -136,7 +139,7 @@ There are limits on the size of each dimension of the `texture` object, as shown ### Reading from Texture Objects -You can read from a `texture` object by using [texture::operator\[\]](reference/texture-class.md#operator_at), [texture::operator() Operator](reference/texture-class.md#operator_call), or [texture::get Method](reference/texture-class.md#get). The two operators return a value, not a reference. Therefore, you cannot write to a `texture` object by using `texture::operator\[\]`. +You can read from a `texture` object by using [texture::operator\[\]](reference/texture-class.md#operator_at), [texture::operator() Operator](reference/texture-class.md#operator_call), or [texture::get Method](reference/texture-class.md#get). The two operators return a value, not a reference. Therefore, you cannot write to a `texture` object by using `texture::operator[]`. ```cpp void readTexture() { diff --git a/docs/parallel/amp/reference/accelerator-class.md b/docs/parallel/amp/reference/accelerator-class.md index 02b879fba9..e5f08b9b8a 100644 --- a/docs/parallel/amp/reference/accelerator-class.md +++ b/docs/parallel/amp/reference/accelerator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: accelerator Class" title: "accelerator Class" -ms.date: "11/04/2016" +description: "Learn more about: accelerator Class" +ms.date: 11/04/2016 f1_keywords: ["AMPRT/accelerator", "AMPRT/Concurrency::accelerator::accelerator", "AMPRT/Concurrency::accelerator::create_view", "AMPRT/Concurrency::accelerator::get_all", "AMPRT/Concurrency::accelerator::get_auto_selection_view", "AMPRT/Concurrency::accelerator::get_dedicated_memory", "AMPRT/Concurrency::accelerator::get_default_cpu_access_type", "AMPRT/Concurrency::accelerator::get_default_view", "AMPRT/Concurrency::accelerator::get_description", "AMPRT/Concurrency::accelerator::get_device_path", "AMPRT/Concurrency::accelerator::get_has_display", "AMPRT/Concurrency::accelerator::get_is_debug", "AMPRT/Concurrency::accelerator::get_is_emulated", "AMPRT/Concurrency::accelerator::get_supports_cpu_shared_memory", "AMPRT/Concurrency::accelerator::get_supports_double_precision", "AMPRT/Concurrency::accelerator::get_supports_limited_double_precision", "AMPRT/Concurrency::accelerator::get_version", "AMPRT/Concurrency::accelerator::set_default", "AMPRT/Concurrency::accelerator::set_default_cpu_access_type", "AMPRT/Concurrency::accelerator::cpu_accelerator", "AMPRT/Concurrency::accelerator::dedicated_memory", "AMPRT/Concurrency::accelerator::default_accelerator", "AMPRT/Concurrency::accelerator::default_cpu_access_type", "AMPRT/Concurrency::accelerator::default_view", "AMPRT/Concurrency::accelerator::description", "AMPRT/Concurrency::accelerator::device_path", "AMPRT/Concurrency::accelerator::direct3d_ref", "AMPRT/Concurrency::accelerator::direct3d_warp", "AMPRT/Concurrency::accelerator::has_display", "AMPRT/Concurrency::accelerator::is_debug", "AMPRT/Concurrency::accelerator::is_emulated", "AMPRT/Concurrency::accelerator::supports_cpu_shared_memory", "AMPRT/Concurrency::accelerator::supports_double_precision", "AMPRT/Concurrency::accelerator::supports_limited_double_precision", "AMPRT/Concurrency::accelerator::version"] helpviewer_keywords: ["accelerator class"] -ms.assetid: 37eed593-cf87-4611-9cdc-e98df6c2377a --- # accelerator Class @@ -45,7 +44,7 @@ class accelerator; |[get_supports_limited_double_precision](#get_supports_limited_double_precision)|Determines whether the `accelerator` has limited support for double-precision math.| |[get_version](#get_version)|Returns the version of the `accelerator`.| |[set_default](#set_default)|Returns the path of the default accelerator.| -|[set_default_cpu_access_type](#set_default_cpu_access_type)|Sets the default CPU [access_type](concurrency-namespace-enums-amp.md#access_type)for arrays and implicit memory allocations made on this `accelerator`.| +|[set_default_cpu_access_type](#set_default_cpu_access_type)|Sets the default CPU [access_type](concurrency-namespace-enums-amp.md#access_type) for arrays and implicit memory allocations made on this `accelerator`.| ### Public Operators @@ -62,7 +61,7 @@ class accelerator; |[cpu_accelerator](#cpu_accelerator)|Gets a string constant for the CPU `accelerator`.| |[dedicated_memory](#dedicated_memory)|Gets the dedicated memory for the `accelerator`, in kilobytes.| |[default_accelerator](#default_accelerator)|Gets a string constant for the default `accelerator`.| -|[default_cpu_access_type](#default_cpu_access_type)|Gets or sets the default CPU [access_type](concurrency-namespace-enums-amp.md#access_type)for arrays and implicit memory allocations made on this `accelerator`.| +|[default_cpu_access_type](#default_cpu_access_type)|Gets or sets the default CPU [access_type](concurrency-namespace-enums-amp.md#access_type) for arrays and implicit memory allocations made on this `accelerator`.| |[default_view](#default_view)|Gets the default `accelerator_view` object that is associated with the `accelerator`.| |[description](#description)|Gets a short description of the `accelerator` device.| |[device_path](#device_path)|Gets the path of the device.| @@ -165,7 +164,7 @@ static const wchar_t default_accelerator[]; ## default_cpu_access_type -The default cpu [access_type](concurrency-namespace-enums-amp.md#access_type)for arrays and implicit memory allocations made on this `accelerator`. +The default cpu [access_type](concurrency-namespace-enums-amp.md#access_type) for arrays and implicit memory allocations made on this `accelerator`. ```cpp __declspec(property(get= get_default_cpu_access_type)) access_type default_cpu_access_type; diff --git a/docs/parallel/amp/reference/array-view-class.md b/docs/parallel/amp/reference/array-view-class.md index 212c17cdea..26700c4f97 100644 --- a/docs/parallel/amp/reference/array-view-class.md +++ b/docs/parallel/amp/reference/array-view-class.md @@ -60,7 +60,7 @@ The rank of the `array_view` object. |[synchronize_async](#synchronize_async)|Asynchronously synchronizes any modifications made to the `array_view` object back to its source data.| |[synchronize_to](#synchronize_to)|Synchronizes any modifications made to the `array_view` object to the specified [accelerator_view](accelerator-view-class.md).| |[synchronize_to_async](#synchronize_to_async)|Asynchronously synchronizes any modifications made to the `array_view` object to the specified [accelerator_view](accelerator-view-class.md).| -|[view_as](#view_as)|Produces an `array_view` object of a different rank using this `array_view` object’s data.| +|[view_as](#view_as)|Produces an `array_view` object of a different rank using this `array_view` object's data.| ### Public Operators diff --git a/docs/parallel/amp/reference/completion-future-class.md b/docs/parallel/amp/reference/completion-future-class.md index e1f8fc6879..7441757f11 100644 --- a/docs/parallel/amp/reference/completion-future-class.md +++ b/docs/parallel/amp/reference/completion-future-class.md @@ -247,7 +247,7 @@ std::future_status::future_status wait_until( The clock on which this time point is measured. *_Duration*
-The time interval since the start of `_Clock`’s epoch, after which the function will time out. +The time interval since the start of `_Clock`'s epoch, after which the function will time out. *_Abs_time*
The point in time after which the function will time out. diff --git a/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md b/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md index b524d406b8..d0a6ddd7c4 100644 --- a/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md +++ b/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Concurrency::direct3d namespace functions (AMP)" title: "Concurrency::direct3d namespace functions (AMP)" +description: "Learn more about: Concurrency::direct3d namespace functions (AMP)" ms.date: "08/31/2018" f1_keywords: ["amp/Concurrency::direct3d::abs", "amp/Concurrency::direct3d::countbits", "amp/Concurrency::direct3d::create_accelerator_view", "amp/Concurrency::direct3d::d3d_access_lock", "amp/Concurrency::direct3d::d3d_access_unlock", "amp/Concurrency::direct3d::firstbithigh", "amp/Concurrency::direct3d::get_buffer", "amp/Concurrency::direct3d::get_device", "amp/Concurrency::direct3d::imax", "amp/Concurrency::direct3d::is_timeout_disabled", "amp/Concurrency::direct3d::mad", "amp/Concurrency::direct3d::noise", "amp/Concurrency::direct3d::radians", "amp/Concurrency::direct3d::reversebits", "amp/Concurrency::direct3d::saturate", "amp/Concurrency::direct3d::smoothstep", "amp/Concurrency::direct3d::step", "amp/Concurrency::direct3d::umin"] -ms.assetid: 28943b62-52c9-42dc-baf1-ca7b095c1a19 --- # Concurrency::direct3d namespace functions (AMP) @@ -47,11 +46,12 @@ ms.assetid: 28943b62-52c9-42dc-baf1-ca7b095c1a19 ## Requirements **Header:** amp.h + **Namespace:** Concurrency ## abs -Returns the absolute value of the argument +Returns the absolute value of the argument. ```cpp inline int abs(int _X) restrict(amp); @@ -59,7 +59,7 @@ inline int abs(int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Integer value ### Return Value @@ -84,13 +84,13 @@ inline int clamp( ### Parameters -*_X*
-The value to be clamped +*_X*\ +The value to be clamped. -*_Min*
+*_Min*\ The lower bound of the clamping range. -*_Max*
+*_Max*\ The upper bound of the clamping range. ### Return Value @@ -99,7 +99,7 @@ The clamped value of `_X`. ## countbits -Counts the number of set bits in _X +Counts the number of set bits in `_X`. ```cpp inline unsigned int countbits(unsigned int _X) restrict(amp); @@ -107,12 +107,12 @@ inline unsigned int countbits(unsigned int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Unsigned integer value ### Return Value -Returns the number of set bits in _X +Returns the number of set bits in `_X`. ## create_accelerator_view @@ -122,27 +122,27 @@ Creates an [accelerator_view](accelerator-view-class.md) object from a pointer t ```cpp accelerator_view create_accelerator_view( - IUnknown * _D3D_device + IUnknown * _D3D_device, queuing_mode _Qmode = queuing_mode_automatic); accelerator_view create_accelerator_view( accelerator& _Accelerator, - bool _Disable_timeout + bool _Disable_timeout, queuing_mode _Qmode = queuing_mode_automatic); ``` ### Parameters -*_Accelerator*
+*_Accelerator*\ The accelerator on which the new accelerator_view is to be created. -*_D3D_device*
+*_D3D_device*\ The pointer to the Direct3D device interface. -*_Disable_timeout*
+*_Disable_timeout*\ A Boolean parameter that specifies whether timeout should be disabled for the newly created accelerator_view. This corresponds to the D3D11_CREATE_DEVICE_DISABLE_GPU_TIMEOUT flag for Direct3D device creation and is used to indicate if the operating system should allow workloads that take more than 2 seconds to execute without resetting the device per the Windows timeout detection and recovery mechanism. Use of this flag is recommended if you need to perform time consuming tasks on the accelerator_view. -*_Qmode*
+*_Qmode*\ The [queuing_mode](concurrency-namespace-enums-amp.md#queuing_mode) to be used for the newly created accelerator_view. This parameter has a default value of `queuing_mode_automatic`. ## Return Value @@ -167,7 +167,7 @@ void __cdecl d3d_access_lock(accelerator_view& _Av); ### Parameters -*_Av*
+*_Av*\ The accelerator_view to lock. ## d3d_access_try_lock @@ -180,7 +180,7 @@ bool __cdecl d3d_access_try_lock(accelerator_view& _Av); ### Parameters -*_Av*
+*_Av*\ The accelerator_view to lock. ### Return Value @@ -197,12 +197,12 @@ void __cdecl d3d_access_unlock(accelerator_view& _Av); ### Parameters -*_Av*
+*_Av*\ The accelerator_view for which the lock is to be released. ## firstbithigh -Gets the location of the first set bit in _X, beginning with the highest-order bit and moving towards the lowest-order bit. +Gets the location of the first set bit in `_X`, beginning with the highest-order bit and moving towards the lowest-order bit. ```cpp inline int firstbithigh(int _X) restrict(amp); @@ -210,16 +210,16 @@ inline int firstbithigh(int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Integer value ### Return Value -The location of the first set bit +The location of the first set bit. ## firstbitlow -Gets the location of the first set bit in _X, beginning with the lowest-order bit and working toward the highest-order bit. +Gets the location of the first set bit in `_X`, beginning with the lowest-order bit and working toward the highest-order bit. ```cpp inline int firstbitlow(int _X) restrict(amp); @@ -227,12 +227,12 @@ inline int firstbitlow(int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Integer value ### Return Value -Returns The location of the first set bit +Returns The location of the first set bit. ## get_buffer @@ -244,25 +244,25 @@ template< int _Rank > IUnknown *get_buffer( - const array& _Array) ; + const array& _Array); ``` ### Parameters -*value_type*
+*value_type*\ The type of elements in the array. -*_Rank*
+*_Rank*\ The rank of the array. -*_Array*
+*_Array*\ An array on a Direct3D accelerator_view for which the underlying Direct3D buffer interface is returned. ### Return Value The IUnknown interface pointer corresponding to the Direct3D buffer underlying the array. -## get_device +## get_device Get the D3D device interface underlying a accelerator_view. @@ -272,7 +272,7 @@ IUnknown* get_device(const accelerator_view Av); ### Parameters -*Av*
+*Av*\ The D3D accelerator_view for which the underlying D3D device interface is returned. ### Return value @@ -281,7 +281,7 @@ The `IUnknown` interface pointer of the D3D device underlying the accelerator_vi ## imax -Determine the maximum numeric value of the arguments +Determine the maximum numeric value of the arguments. ```cpp inline int imax( @@ -291,19 +291,19 @@ inline int imax( ### Parameters -*_X*
+*_X*\ Integer value -*_Y*
+*_Y*\ Integer value ### Return Value -Return the maximum numeric value of the arguments +Return the maximum numeric value of the arguments. ## imin -Determine the minimum numeric value of the arguments +Determine the minimum numeric value of the arguments. ```cpp inline int imin( @@ -313,15 +313,15 @@ inline int imin( ### Parameters -*_X*
+*_X*\ Integer value -*_Y*
+*_Y*\ Integer value ### Return Value -Return the minimum numeric value of the arguments +Return the minimum numeric value of the arguments. ## is_timeout_disabled @@ -333,7 +333,7 @@ bool __cdecl is_timeout_disabled(const accelerator_view& _Accelerator_view); ### Parameters -*_Accelerator_view*
+*_Accelerator_view*\ The accelerator_view for which the timeout disabled setting is to be queried. ### Return Value @@ -368,13 +368,13 @@ inline unsigned int mad( ### Parameters -*_X*
+*_X*\ The first specified argument. -*_Y*
+*_Y*\ The second specified argument. -*_Z*
+*_Z*\ The third specified argument. ### Return Value @@ -393,24 +393,24 @@ template< array make_array( const extent<_Rank>& _Extent, const Concurrency::accelerator_view& _Rv, - IUnknown* _D3D_buffer) ; + IUnknown* _D3D_buffer); ``` ### Parameters -*value_type*
+*value_type*\ The element type of the array to be created. -*_Rank*
+*_Rank*\ The rank of the array to be created. -*_Extent*
+*_Extent*\ An extent that describes the shape of the array aggregate. -*_Rv*
+*_Rv*\ A D3D accelerator view on which the array is to be created. -*_D3D_buffer*
+*_D3D_buffer*\ IUnknown interface pointer of the D3D buffer to create the array from. ### Return Value @@ -419,7 +419,7 @@ An array created using the provided Direct3D buffer. ## noise -Generates a random value using the Perlin noise algorithm +Generates a random value using the Perlin noise algorithm. ```cpp inline float noise(float _X) restrict(amp); @@ -427,16 +427,16 @@ inline float noise(float _X) restrict(amp); ### Parameters -*_X*
-Floating-point value from which to generate Perlin noise +*_X*\ +Floating-point value from which to generate Perlin noise. ### Return Value -Returns The Perlin noise value within a range between -1 and 1 +Returns the Perlin noise value within a range between -1 and 1. ## radians -Converts _X from degrees to radians +Converts `_X` from degrees to radians. ```cpp inline float radians(float _X) restrict(amp); @@ -444,12 +444,12 @@ inline float radians(float _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Floating-point value ### Return Value -Returns _X converted from degrees to radians +Returns `_X` converted from degrees to radians. ## rcp @@ -463,7 +463,7 @@ inline double rcp(double _X) restrict(amp); ### Parameters -*_X*
+*_X*\ The value for which to compute the reciprocal. ### Return Value @@ -472,7 +472,7 @@ The reciprocal of the specified argument. ## reversebits -Reverses the order of the bits in _X +Reverses the order of the bits in `_X`. ```cpp inline unsigned int reversebits(unsigned int _X) restrict(amp); @@ -480,16 +480,16 @@ inline unsigned int reversebits(unsigned int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Unsigned integer value ### Return Value -Returns the value with the bit order reversed in _X +Returns the value with the bit order reversed in `_X`. ## saturate -Clamps _X within the range of 0 to 1 +Clamps `_X` within the range of 0 to 1. ```cpp inline float saturate(float _X) restrict(amp); @@ -497,12 +497,12 @@ inline float saturate(float _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Floating-point value ### Return Value -Returns _X clamped within the range of 0 to 1 +Returns `_X` clamped within the range of 0 to 1. ## sign @@ -514,7 +514,7 @@ inline int sign(int _X) restrict(amp); ### Parameters -*_X*
+*_X*\ Integer value ### Return Value @@ -523,7 +523,7 @@ The sign of the argument. ## smoothstep -Returns a smooth Hermite interpolation between 0 and 1, if _X is in the range [_Min, _Max]. +Returns a smooth Hermite interpolation between 0 and 1, if `_X` is in the range [_Min, _Max]. ```cpp inline float smoothstep( @@ -534,22 +534,22 @@ inline float smoothstep( ### Parameters -*_Min*
+*_Min*\ Floating-point value -*_Max*
+*_Max*\ Floating-point value -*_X*
+*_X*\ Floating-point value ### Return Value -Returns 0 if _X is less than _Min; 1 if _X is greater than _Max; otherwise, a value between 0 and 1 if _X is in the range [_Min, _Max] +Returns 0 if `_X` is less than _Min; 1 if `_X` is greater than _Max; otherwise, a value between 0 and 1 if `_X` is in the range [_Min, _Max]. ## step -Compares two values, returning 0 or 1 based on which value is greater +Compares two values, returning 0 or 1 based on which value is greater. ```cpp inline float step( @@ -559,19 +559,19 @@ inline float step( ### Parameters -*_Y*
+*_Y*\ Floating-point value -*_X*
+*_X*\ Floating-point value ### Return Value -Returns 1 if the _X is greater than or equal to _Y; otherwise, 0 +Returns 1 if the `_X` is greater than or equal to `_Y`; otherwise, 0. ## umax -Determine the maximum numeric value of the arguments +Determine the maximum numeric value of the arguments. ```cpp inline unsigned int umax( @@ -581,19 +581,19 @@ inline unsigned int umax( ### Parameters -*_X*
+*_X*\ Integer value -*_Y*
+*_Y*\ Integer value ### Return Value -Return the maximum numeric value of the arguments +Return the maximum numeric value of the arguments. ## umin -Determine the minimum numeric value of the arguments +Determine the minimum numeric value of the arguments. ```cpp inline unsigned int umin( @@ -603,15 +603,15 @@ inline unsigned int umin( ### Parameters -*_X*
+*_X*\ Integer value -*_Y*
+*_Y*\ Integer value ### Return Value -Return the minimum numeric value of the arguments +Return the minimum numeric value of the arguments. ## See also diff --git a/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md b/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md index ac0f29d676..e9e8eef189 100644 --- a/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md +++ b/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: Concurrency::graphics namespace functions" title: "Concurrency::graphics namespace functions" -ms.date: "11/04/2016" +description: "Learn more about: Concurrency::graphics namespace functions" +ms.date: 11/04/2016 f1_keywords: ["amp_graphics/Concurrency::fast_math::copy_async", "amp_graphics/Concurrency::fast_math::copy"] -ms.assetid: ace01cd5-29d3-4356-930e-c81a61c5f934 --- # Concurrency::graphics namespace functions -[copy](#copy)\ -[copy_async](#copy_async) +The following functions are available in the `Concurrency::graphics` namespace: ## copy Function (Concurrency::graphics Namespace) diff --git a/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md b/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md index b3e6db41fd..a03bea4d1a 100644 --- a/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md +++ b/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md @@ -1,16 +1,14 @@ --- -description: "Learn more about: Concurrency namespace constants (AMP)" title: "Concurrency namespace constants (AMP)" -ms.date: "11/04/2016" +description: "Learn more about: Concurrency namespace constants (AMP)" +ms.date: 11/04/2016 f1_keywords: ["amp/Concurrency::HLSL_MAX_NUM_BUFFERS", "amp/Concurrency::MODULENAME_MAX_LENGTH"] -ms.assetid: 13a8e8cd-2eec-4e60-a91d-5d271072747b --- # Concurrency namespace constants (AMP) -[HLSL_MAX_NUM_BUFFERS](#hlsl_max_num_buffers)\ -[MODULENAME_MAX_LENGTH](#modulename_max_length) +The following constants are defined in the `Concurrency` namespace (AMP): -## HLSL_MAX_NUM_BUFFERS Constant +## `HLSL_MAX_NUM_BUFFERS` Constant The maximum number of buffers allowed by DirectX. @@ -18,9 +16,9 @@ The maximum number of buffers allowed by DirectX. static const UINT HLSL_MAX_NUM_BUFFERS = 64 + 128; ``` -## MODULENAME_MAX_LENGTH Constant +## `MODULENAME_MAX_LENGTH` constant -Stores the maximum length of the module name. This value must be the same on the compiler and runtime. +Stores the maximum length of the module name. This value must be the same at compile time and runtime. ```cpp static const UINT MODULENAME_MAX_LENGTH = 1024; diff --git a/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md b/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md index 55a34e9c71..feef3abec3 100644 --- a/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md +++ b/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md @@ -1,18 +1,14 @@ --- -description: "Learn more about: Concurrency namespace enums (AMP)" title: "Concurrency namespace enums (AMP)" -ms.date: "11/04/2016" +description: "Learn more about: Concurrency namespace enums (AMP)" +ms.date: 11/04/2016 f1_keywords: ["amp/Concurrency::access_type", "amp/Concurrency::queuing_mode"] -ms.assetid: 4c87457e-184f-4992-81ab-ca75e7d524ab --- -# Concurrency namespace enums (AMP) - -[access_type Enumeration](#access_type)\ -[queuing_mode Enumeration](#queuing_mode) +# `Concurrency` namespace enums (AMP) -## access_type Enumeration +The following enumerations are available in the `Concurrency` namespace: -Enumeration type used to denote the various types of access to data. +## `access_type` enumeration ```cpp enum access_type; @@ -28,7 +24,7 @@ enum access_type; |`access_type_read_write`|Shared. The allocation is accessible on the accelerator and is writable on the CPU.| |`access_type_write`|Shared. The allocation is accessible on the accelerator and is both readable and writable on the CPU.| -## queuing_mode Enumeration +## `queuing_mode` enumeration Specifies the queuing modes that are supported on the accelerator. diff --git a/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md b/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md index 0df3345b35..a7908a8b41 100644 --- a/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md +++ b/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Concurrency::precise_math namespace functions" title: "Concurrency::precise_math namespace functions" +description: "Learn more about: Concurrency::precise_math namespace functions" ms.date: "11/04/2016" f1_keywords: ["amp_math/Concurrency::precise_math::acos", "amp_math/Concurrency::precise_math::acosh", "amp_math/Concurrency::precise_math::acoshf", "amp_math/Concurrency::precise_math::asinf", "amp_math/Concurrency::precise_math::asinh", "amp_math/Concurrency::precise_math::atan", "amp_math/Concurrency::precise_math::atan2", "amp_math/Concurrency::precise_math::atanf", "amp_math/Concurrency::precise_math::atanh", "amp_math/Concurrency::precise_math::cbrt", "amp_math/Concurrency::precise_math::cbrtf", "amp_math/Concurrency::precise_math::ceilf", "amp_math/Concurrency::precise_math::copysign", "amp_math/Concurrency::precise_math::cos", "amp_math/Concurrency::precise_math::cosf", "amp_math/Concurrency::precise_math::coshf", "amp_math/Concurrency::precise_math::cospi", "amp_math/Concurrency::precise_math::erf", "amp_math/Concurrency::precise_math::erfc", "amp_math/Concurrency::precise_math::erfcinv", "amp_math/Concurrency::precise_math::erfcinvf", "amp_math/Concurrency::precise_math::erfinv", "amp_math/Concurrency::precise_math::erfinvf", "amp_math/Concurrency::precise_math::exp10", "amp_math/Concurrency::precise_math::exp10f", "amp_math/Concurrency::precise_math::exp2f", "amp_math/Concurrency::precise_math::expf", "amp_math/Concurrency::precise_math::expm1f", "amp_math/Concurrency::precise_math::fabs", "amp_math/Concurrency::precise_math::floor", "amp_math/Concurrency::precise_math::fdim", "amp_math/Concurrency::precise_math::floorf", "amp_math/Concurrency::precise_math::fmaf", "amp_math/Concurrency::precise_math::fmaxf", "amp_math/Concurrency::precise_math::fmin", "amp_math/Concurrency::precise_math::fmod", "amp_math/Concurrency::precise_math::fmodf", "amp_math/Concurrency::precise_math::frexp", "amp_math/Concurrency::precise_math::frexpf", "amp_math/Concurrency::precise_math::hypotf", "amp_math/Concurrency::precise_math::ilogb", "amp_math/Concurrency::precise_math::isfinite", "amp_math/Concurrency::precise_math::isinf", "amp_math/Concurrency::precise_math::isnormal", "amp_math/Concurrency::precise_math::ldexp", "amp_math/Concurrency::precise_math::lgamma", "amp_math/Concurrency::precise_math::lgammaf", "amp_math/Concurrency::precise_math::log10", "amp_math/Concurrency::precise_math::log10f", "amp_math/Concurrency::precise_math::log1pf", "amp_math/Concurrency::precise_math::log2", "amp_math/Concurrency::precise_math::logb", "amp_math/Concurrency::precise_math::logbf", "amp_math/Concurrency::precise_math::modf", "amp_math/Concurrency::precise_math::modff", "amp_math/Concurrency::precise_math::nanf", "amp_math/Concurrency::precise_math::nearbyint", "amp_math/Concurrency::precise_math::nextafter", "amp_math/Concurrency::precise_math::nextafterf", "amp_math/Concurrency::precise_math::phif", "amp_math/Concurrency::precise_math::pow", "amp_math/Concurrency::precise_math::probit", "amp_math/Concurrency::precise_math::probitf", "amp_math/Concurrency::precise_math::rcbrtf", "amp_math/Concurrency::precise_math::remainder", "amp_math/Concurrency::precise_math::remquo", "amp_math/Concurrency::precise_math::remquof", "amp_math/Concurrency::precise_math::roundf", "amp_math/Concurrency::precise_math::rsqrt", "amp_math/Concurrency::precise_math::scalb", "amp_math/Concurrency::precise_math::scalbf", "amp_math/Concurrency::precise_math::scalbnf", "amp_math/Concurrency::precise_math::signbit", "amp_math/Concurrency::precise_math::sin", "amp_math/Concurrency::precise_math::sincos", "amp_math/Concurrency::precise_math::sinf", "amp_math/Concurrency::precise_math::sinh", "amp_math/Concurrency::precise_math::sinpi", "amp_math/Concurrency::precise_math::sinpif", "amp_math/Concurrency::precise_math::sqrtf", "amp_math/Concurrency::precise_math::tan", "amp_math/Concurrency::precise_math::tanh", "amp_math/Concurrency::precise_math::tanhf", "amp_math/Concurrency::precise_math::tanpif", "amp_math/Concurrency::precise_math::tgamma", "amp_math/Concurrency::precise_math::trunc", "amp_math/Concurrency::precise_math::truncf"] -ms.assetid: fae53ab4-d1c5-45bb-a6a0-a74258e9aea3 --- # Concurrency::precise_math namespace functions @@ -1049,7 +1048,7 @@ Floating-point value Returns the floor of the argument -## fma +## fma Computes the product of the first and second specified arguments, then adds the third specified argument to the result; the entire computation is performed as a single operation. @@ -2143,7 +2142,7 @@ The first floating-point argument. The second floating-point argument. *_Quo*
-[out] The address of an integer that’s used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. +[out] The address of an integer that's used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. ### Return Value @@ -2169,7 +2168,7 @@ The first floating-point argument. The second floating-point argument. *_Quo*
-[out] The address of an integer that’s used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. +[out] The address of an integer that's used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. ### Return Value diff --git a/docs/parallel/amp/reference/index-class.md b/docs/parallel/amp/reference/index-class.md index d4982c4fcc..7e4fe7573d 100644 --- a/docs/parallel/amp/reference/index-class.md +++ b/docs/parallel/amp/reference/index-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: index Class" title: "index Class" -ms.date: "03/27/2019" +ms.date: 06/21/2022 f1_keywords: ["AMP/index", "AMP/Concurrency::index::index", "AMP/Concurrency::index::rank"] helpviewer_keywords: ["index structure"] ms.assetid: cbe79b08-0ba7-474c-9828-f1a71da39eb3 +ms.custom: devdivchpfy22 --- + # index Class Defines an *N*-dimensional index vector. @@ -129,7 +131,7 @@ index operator--( ### Return values -For the prefix operator, the index object (*this). For the suffix operator, a new index object. +For the prefix operator, the index object (`*this`). For the suffix operator, a new index object. ## operator%= @@ -229,7 +231,7 @@ index<_Rank> operator++( ### Return Value -For the prefix operator, the index object (*this). For the suffix operator, a new index object. +For the prefix operator, the index object (`*this`). For the suffix operator, a new index object. ## operator+= diff --git a/docs/parallel/amp/reference/int-2-class.md b/docs/parallel/amp/reference/int-2-class.md index 0c2ba40993..6b5e99b222 100644 --- a/docs/parallel/amp/reference/int-2-class.md +++ b/docs/parallel/amp/reference/int-2-class.md @@ -57,7 +57,7 @@ class int_2; |int_2::operator*=|| |int_2::operator/=|| |int_2::operator^=|| -|int_2::operator|=|| +|int_2::operator\|=|| |int_2::operator~|| |int_2::operator++|| |int_2::operator+=|| diff --git a/docs/parallel/amp/reference/int-3-class.md b/docs/parallel/amp/reference/int-3-class.md index 8bc5602d4c..460a6983ff 100644 --- a/docs/parallel/amp/reference/int-3-class.md +++ b/docs/parallel/amp/reference/int-3-class.md @@ -81,7 +81,7 @@ class int_3; |int_3::operator*=|| |int_3::operator/=|| |int_3::operator^=|| -|int_3::operator|=|| +|int_3::operator\|=|| |int_3::operator~|| |int_3::operator++|| |int_3::operator+=|| diff --git a/docs/parallel/amp/reference/int-4-class.md b/docs/parallel/amp/reference/int-4-class.md index 05f5d25072..ad9e159065 100644 --- a/docs/parallel/amp/reference/int-4-class.md +++ b/docs/parallel/amp/reference/int-4-class.md @@ -181,7 +181,7 @@ class int_4; |int_4::operator*=|| |int_4::operator/=|| |int_4::operator^=|| -|int_4::operator|=|| +|int_4::operator\|=|| |int_4::operator~|| |int_4::operator++|| |int_4::operator+=|| diff --git a/docs/parallel/amp/reference/norm-3-class.md b/docs/parallel/amp/reference/norm-3-class.md index 336f4b5e08..a0e3841d4d 100644 --- a/docs/parallel/amp/reference/norm-3-class.md +++ b/docs/parallel/amp/reference/norm-3-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: norm_3 Class" title: "norm_3 Class" +description: "Learn more about: norm_3 Class" ms.date: "11/04/2016" f1_keywords: ["amp_short_vectors/Concurrency::graphics::norm_3::get_z", "amp_short_vectors/Concurrency::graphics::norm_3::operator=", "amp_short_vectors/Concurrency::graphics::norm_3::r", "amp_short_vectors/Concurrency::graphics::norm_3::set_zyx", "amp_short_vectors/Concurrency::graphics::norm_3::xyz", "amp_short_vectors/Concurrency::graphics::norm_3::operator/=", "amp_short_vectors/Concurrency::graphics::norm_3::yz", "amp_short_vectors/Concurrency::graphics::norm_3::get_xyz", "amp_short_vectors/Concurrency::graphics::norm_3::br", "amp_short_vectors/Concurrency::graphics::norm_3::xy", "amp_short_vectors/Concurrency::graphics::norm_3::get_yzx", "amp_short_vectors/Concurrency::graphics::norm_3::set_xyz", "amp_short_vectors/Concurrency::graphics::norm_3::gr", "amp_short_vectors/Concurrency::graphics::norm_3::g", "amp_short_vectors/Concurrency::graphics::norm_3::set_yxz", "amp_short_vectors/Concurrency::graphics::norm_3::get_zyx", "amp_short_vectors/Concurrency::graphics::norm_3::get_y", "amp_short_vectors/Concurrency::graphics::norm_3::zx", "amp_short_vectors/Concurrency::graphics::norm_3::yzx", "amp_short_vectors/Concurrency::graphics::norm_3::gb", "amp_short_vectors/Concurrency::graphics::norm_3::xzy", "amp_short_vectors/Concurrency::graphics::norm_3::xz", "amp_short_vectors/Concurrency::graphics::norm_3::rb", "amp_short_vectors/Concurrency::graphics::norm_3::rgb", "amp_short_vectors/Concurrency::graphics::norm_3::b", "amp_short_vectors/Concurrency::graphics::norm_3::z", "amp_short_vectors/Concurrency::graphics::norm_3::operator*=", "amp_short_vectors/Concurrency::graphics::norm_3::operator+=", "amp_short_vectors/Concurrency::graphics::norm_3::get_zy", "amp_short_vectors/Concurrency::graphics::norm_3::get_xz", "amp_short_vectors/Concurrency::graphics::norm_3::gbr", "amp_short_vectors/Concurrency::graphics::norm_3::get_yz", "amp_short_vectors/Concurrency::graphics::norm_3::get_zx", "amp_short_vectors/Concurrency::graphics::norm_3::get_xzy", "amp_short_vectors/Concurrency::graphics::norm_3::set_xz", "amp_short_vectors/Concurrency::graphics::norm_3::set_xzy", "amp_short_vectors/Concurrency::graphics::norm_3::set_zy", "amp_short_vectors/Concurrency::graphics::norm_3::get_xy", "amp_short_vectors/Concurrency::graphics::norm_3::y", "amp_short_vectors/Concurrency::graphics::norm_3::yx", "amp_short_vectors/Concurrency::graphics::norm_3::rbg", "amp_short_vectors/Concurrency::graphics::norm_3::zxy", "amp_short_vectors/Concurrency::graphics::norm_3", "amp_short_vectors/Concurrency::graphics::norm_3::set_yz", "amp_short_vectors/Concurrency::graphics::norm_3::brg", "amp_short_vectors/Concurrency::graphics::norm_3::operator--", "amp_short_vectors/Concurrency::graphics::norm_3::yxz", "amp_short_vectors/Concurrency::graphics::norm_3::x", "amp_short_vectors/Concurrency::graphics::norm_3::set_x", "amp_short_vectors/Concurrency::graphics::norm_3::get_x", "amp_short_vectors/Concurrency::graphics::norm_3::get_yxz", "amp_short_vectors/Concurrency::graphics::norm_3::grb", "amp_short_vectors/Concurrency::graphics::norm_3::get_yx", "amp_short_vectors/Concurrency::graphics::norm_3::zy", "amp_short_vectors/Concurrency::graphics::norm_3::rg", "amp_short_vectors/Concurrency::graphics::norm_3::set_yzx", "amp_short_vectors/Concurrency::graphics::norm_3::operator-=", "amp_short_vectors/Concurrency::graphics::norm_3::bg", "amp_short_vectors/Concurrency::graphics::norm_3::operator++", "amp_short_vectors/Concurrency::graphics::norm_3::set_y", "amp_short_vectors/Concurrency::graphics::norm_3::zyx", "amp_short_vectors/Concurrency::graphics::norm_3::set_z", "amp_short_vectors/Concurrency::graphics::norm_3::operator-", "amp_short_vectors/Concurrency::graphics::norm_3::get_zxy", "amp_short_vectors/Concurrency::graphics::norm_3::set_xy", "amp_short_vectors/Concurrency::graphics::norm_3::set_zxy", "amp_short_vectors/Concurrency::graphics::norm_3::set_yx", "amp_short_vectors/Concurrency::graphics::norm_3::set_zx", "amp_short_vectors/Concurrency::graphics::norm_3::bgr"] -ms.assetid: 17081060-14ce-477e-a71a-9801b0f1d9e4 --- # norm_3 Class @@ -200,7 +199,7 @@ The value for initialization. *_Other*
The object used to initialize. -## size Constant +## size Constant ### Syntax diff --git a/docs/parallel/amp/reference/sampler-class.md b/docs/parallel/amp/reference/sampler-class.md index ade1f10b70..5542115588 100644 --- a/docs/parallel/amp/reference/sampler-class.md +++ b/docs/parallel/amp/reference/sampler-class.md @@ -27,9 +27,9 @@ class sampler; |Name|Description| |----------|-----------------| -|[get_address_mode](#get_address_mode)|Returns the `address_mode` that’s associated with the sampler object.| -|[get_border_color](#get_border_color)|Returns the border color that’s associated with the sampler object.| -|[get_filter_mode](#get_filter_mode)|Returns the `filter_mode` that’s associated with the sampler object.| +|[get_address_mode](#get_address_mode)|Returns the `address_mode` that's associated with the sampler object.| +|[get_border_color](#get_border_color)|Returns the border color that's associated with the sampler object.| +|[get_filter_mode](#get_filter_mode)|Returns the `filter_mode` that's associated with the sampler object.| ### Public Operators @@ -133,7 +133,7 @@ __declspec(property(get= get_filter_mode)) Concurrency::graphics::filter_mode fi ## get_address_mode -Returns the filter mode that’s configured for this `sampler`. +Returns the filter mode that's configured for this `sampler`. ```cpp Concurrency::graphics::address_mode get_address_mode() const __GPU; @@ -141,11 +141,11 @@ Concurrency::graphics::address_mode get_address_mode() const __GPU; ### Return Value -The address mode that’s configured for the sampler. +The address mode that's configured for the sampler. ## get_border_color -Returns the border color that’s configured for this `sampler`. +Returns the border color that's configured for this `sampler`. ```cpp Concurrency::graphics::float_4 get_border_color() const restrict(amp, cpu); @@ -157,7 +157,7 @@ A float_4 that contains the border color. ## get_filter_mode -Returns the filter mode that’s configured for this `sampler`. +Returns the filter mode that's configured for this `sampler`. ```cpp Concurrency::graphics::filter_mode get_filter_mode() const restrict(amp, cpu); @@ -165,7 +165,7 @@ Concurrency::graphics::filter_mode get_filter_mode() const restrict(amp, cpu); ### Return Value -The filter mode that’s configured for the sampler. +The filter mode that's configured for the sampler. ## operator= diff --git a/docs/parallel/amp/reference/texture-class.md b/docs/parallel/amp/reference/texture-class.md index f99e078681..67d5044bae 100644 --- a/docs/parallel/amp/reference/texture-class.md +++ b/docs/parallel/amp/reference/texture-class.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: texture Class" title: "texture Class" -ms.date: "11/04/2016" +description: "Learn more about: texture Class" +ms.date: 11/04/2016 f1_keywords: ["texture", "AMP_GRAPHICS/texture", "AMP_GRAPHICS/concurrency::graphics::texture::texture", "AMP_GRAPHICS/concurrency::graphics::texture::copy_to", "AMP_GRAPHICS/concurrency::graphics::texture::data", "AMP_GRAPHICS/concurrency::graphics::texture::get", "AMP_GRAPHICS/concurrency::graphics::texture::get_associated_accelerator_view", "AMP_GRAPHICS/concurrency::graphics::texture::get_depth_pitch", "AMP_GRAPHICS/concurrency::graphics::texture::get_row_pitch", "AMP_GRAPHICS/concurrency::graphics::texture::set", "AMP_GRAPHICS/concurrency::graphics::texture::rank", "AMP_GRAPHICS/concurrency::graphics::texture::associated_accelerator_view", "AMP_GRAPHICS/concurrency::graphics::texture::depth_pitch", "AMP_GRAPHICS/concurrency::graphics::texture::row_pitch"] -ms.assetid: 16e85d4d-e80a-474a-995d-8bf63fbdf34c --- # texture Class -A texture is a data aggregate on an `accelerator_view` in the extent domain. It is a collection of variables, one for each element in an extent domain. Each variable holds a value corresponding to C++ primitive type ( **`unsigned int`**, **`int`**, **`float`**, **`double`**), a scalar type ( `norm`, or `unorm`), or a short vector type. +A texture is a data aggregate on an `accelerator_view` in the extent domain. It is a collection of variables, one for each element in an extent domain. Each variable holds a value corresponding to C++ primitive type ( **`unsigned int`**, **`int`**, **`float`**, **`double`**), a scalar type (`norm`, or `unorm`), or a short vector type. ## Syntax diff --git a/docs/parallel/amp/reference/texture-view-class.md b/docs/parallel/amp/reference/texture-view-class.md index 610f6fedf5..2ab64c9f96 100644 --- a/docs/parallel/amp/reference/texture-view-class.md +++ b/docs/parallel/amp/reference/texture-view-class.md @@ -40,7 +40,7 @@ The rank of the `texture_view`. |----------|-----------------| |`value_type`|The type of the elements in the texture aggregates.| |`coordinates_type`|The type of the coordinate used to specify a texel in the `texture_view`—that is, a `short_vector` that has the same rank as the associated texture that has a value type of **`float`**.| -|`gather_return_type`|The return type used for gather operations—that is, a rank 4 `short_vector` that holds the four homogenous color components gathered from the four texel values sampled.| +|`gather_return_type`|The return type used for gather operations—that is, a rank 4 `short_vector` that holds the four homogeneous color components gathered from the four texel values sampled.| ### Public Constructors diff --git a/docs/parallel/amp/reference/tile-barrier-class.md b/docs/parallel/amp/reference/tile-barrier-class.md index 95119110e9..d9c181b68b 100644 --- a/docs/parallel/amp/reference/tile-barrier-class.md +++ b/docs/parallel/amp/reference/tile-barrier-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: tile_barrier Class" title: "tile_barrier Class" +description: "Learn more about: tile_barrier Class" ms.date: "03/27/2019" f1_keywords: ["tile_barrier", "AMP/tile_barrier", "AMP/Concurrency::tile_barrier::tile_barrier::tile_barrier", "AMP/Concurrency::tile_barrier::tile_barrier::wait", "AMP/Concurrency::tile_barrier::tile_barrier::wait_with_all_memory_fence", "AMP/Concurrency::tile_barrier::tile_barrier::wait_with_global_memory_fence", "AMP/Concurrency::tile_barrier::tile_barrier::wait_with_tile_static_memory_fence"] helpviewer_keywords: ["tile_barrier class"] -ms.assetid: b4ccdccb-0032-4e11-b7bd-dc9d43445dee --- # tile_barrier Class @@ -79,7 +78,7 @@ Blocks execution of all threads in a tile until all threads in a tile have reach void wait_with_all_memory_fence() const restrict(amp); ``` -## wait_with_global_memory_fence +## wait_with_global_memory_fence Blocks execution of all threads in a tile until all threads in a tile have reached this call. This ensures that all global memory accesses are visible to other threads in the thread tile, and have been executed in program order. @@ -89,7 +88,7 @@ Blocks execution of all threads in a tile until all threads in a tile have reach void wait_with_global_memory_fence() const restrict(amp); ``` -## wait_with_tile_static_memory_fence +## wait_with_tile_static_memory_fence Blocks execution of all threads in a tile until all threads in a tile have reached this call. This ensures that `tile_static` memory accesses are visible to other threads in the thread tile, and have been executed in program order. diff --git a/docs/parallel/amp/reference/uint-2-class.md b/docs/parallel/amp/reference/uint-2-class.md index 68d194c309..b94c30a56f 100644 --- a/docs/parallel/amp/reference/uint-2-class.md +++ b/docs/parallel/amp/reference/uint-2-class.md @@ -56,7 +56,7 @@ class uint_2; |uint_2::operator*=|| |uint_2::operator/=|| |uint_2::operator^=|| -|uint_2::operator|=|| +|uint_2::operator\|=|| |uint_2::operator~|| |uint_2::operator++|| |uint_2::operator+=|| diff --git a/docs/parallel/amp/reference/uint-3-class.md b/docs/parallel/amp/reference/uint-3-class.md index 6f0e5836d6..f6eba19713 100644 --- a/docs/parallel/amp/reference/uint-3-class.md +++ b/docs/parallel/amp/reference/uint-3-class.md @@ -80,7 +80,7 @@ class uint_3; |uint_3::operator*=|| |uint_3::operator/=|| |uint_3::operator^=|| -|uint_3::operator|=|| +|uint_3::operator\|=|| |uint_3::operator~|| |uint_3::operator++|| |uint_3::operator+=|| diff --git a/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md b/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md index 7561a885f8..fb4f51eb4c 100644 --- a/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md +++ b/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md @@ -1,12 +1,15 @@ --- -description: "Learn more about: Using accelerator and accelerator_view Objects" title: "Using accelerator and accelerator_view Objects" +description: "Learn more about: Using accelerator and accelerator_view Objects" ms.date: "11/04/2016" -ms.assetid: 18f0dc66-8236-4420-9f46-1a14f2c3fba1 --- # Using accelerator and accelerator_view Objects -You can use the [accelerator](../../parallel/amp/reference/accelerator-class.md) and [accelerator_view](../../parallel/amp/reference/accelerator-view-class.md) classes to specify the device or emulator to run your C++ AMP code on. A system might have several devices or emulators that differ by amount of memory, shared memory support, debugging support, or double-precision support. C++ Accelerated Massive Parallelism (C++ AMP) provides APIs that you can use to examine the available accelerators, set one as the default, specify multiple accelerator_views for multiple calls to parallel_for_each, and perform special debugging tasks. +You can use the [accelerator](reference/accelerator-class.md) and [accelerator_view](reference/accelerator-view-class.md) classes to specify the device or emulator to run your C++ AMP code on. A system might have several devices or emulators that differ by amount of memory, shared memory support, debugging support, or double-precision support. C++ Accelerated Massive Parallelism (C++ AMP) provides APIs that you can use to examine the available accelerators, set one as the default, specify multiple accelerator_views for multiple calls to parallel_for_each, and perform special debugging tasks. + +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. ## Using the Default Accelerator @@ -14,7 +17,7 @@ The C++ AMP runtime picks a default accelerator, unless you write code to pick a 1. If the app is running in debug mode, an accelerator that supports debugging. -2. Otherwise, the accelerator that's specified by the CPPAMP_DEFAULT_ACCELERATOR environment variable, if it's set. +2. Otherwise, the accelerator that's specified by the `CPPAMP_DEFAULT_ACCELERATOR` environment variable, if it's set. 3. Otherwise, a non-emulated device. @@ -22,7 +25,7 @@ The C++ AMP runtime picks a default accelerator, unless you write code to pick a 5. Otherwise, a device that's not attached to the display. -Additionally, the runtime specifies an `access_type` of `access_type_auto` for the default accelerator. This means that the default accelerator uses shared memory if it’s supported and if its performance characteristics (bandwidth and latency) are known to be the same as dedicated (non-shared) memory. +Additionally, the runtime specifies an `access_type` of `access_type_auto` for the default accelerator. This means that the default accelerator uses shared memory if it's supported and if its performance characteristics (bandwidth and latency) are known to be the same as dedicated (non-shared) memory. You can determine the properties of the default accelerator by constructing the default accelerator and examining its properties. The following code example prints the path, amount of accelerator memory, shared memory support, double-precision support, and limited double-precision support of the default accelerator. @@ -42,7 +45,7 @@ void default_properties() { ### CPPAMP_DEFAULT_ACCELERATOR Environment Variable -You can set the CPPAMP_DEFAULT_ACCELERATOR environment variable to specify the `accelerator::device_path` of the default accelerator. The path is hardware-dependent. The following code uses the `accelerator::get_all` function to retrieve a list of the available accelerators and then displays the path and characteristics of each accelerator. +You can set the `CPPAMP_DEFAULT_ACCELERATOR` environment variable to specify the `accelerator::device_path` of the default accelerator. The path is hardware-dependent. The following code uses the `accelerator::get_all` function to retrieve a list of the available accelerators and then displays the path and characteristics of each accelerator. ```cpp void list_all_accelerators() @@ -105,7 +108,7 @@ int main() { accelerator acc = accelerator(accelerator::default_accelerator); - // Early out if the default accelerator doesn’t support shared memory. + // Early out if the default accelerator doesn't support shared memory. if (!acc.supports_cpu_shared_memory) { std::cout << "The default accelerator does not support shared memory" << std::endl; @@ -117,12 +120,12 @@ int main() // Create an accelerator_view from the default accelerator. The // accelerator_view reflects the default_cpu_access_type of the - // accelerator it’s associated with. + // accelerator it's associated with. accelerator_view acc_v = acc.default_view; } ``` -An `accelerator_view` always reflects the `default_cpu_access_type` of the `accelerator` it’s associated with, and it provides no interface to override or change its `access_type`. +An `accelerator_view` always reflects the `default_cpu_access_type` of the `accelerator` it's associated with, and it provides no interface to override or change its `access_type`. ## Changing the Default Accelerator @@ -157,7 +160,7 @@ There are two ways to use multiple accelerators in your app: - You can pass `accelerator_view` objects to the calls to the [parallel_for_each](reference/concurrency-namespace-functions-amp.md#parallel_for_each) method. -- You can construct an **array** object using a specific `accelerator_view` object. The C+AMP runtime will pick up the `accelerator_view` object from the captured **array** object in the lambda expression. +- You can construct an **array** object using a specific `accelerator_view` object. The C++ AMP runtime will pick up the `accelerator_view` object from the captured **array** object in the lambda expression. ## Special Accelerators @@ -175,6 +178,6 @@ The C++ AMP runtime supports interoperability between the `accelerator_view` cla ## See also -[C++ AMP (C++ Accelerated Massive Parallelism)](../../parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md)
-[Debugging GPU Code](/visualstudio/debugger/debugging-gpu-code)
-[accelerator_view Class](../../parallel/amp/reference/accelerator-view-class.md) +[C++ AMP (C++ Accelerated Massive Parallelism)](cpp-amp-cpp-accelerated-massive-parallelism.md)\ +[Debugging GPU Code](/visualstudio/debugger/debugging-gpu-code)\ +[accelerator_view Class](reference/accelerator-view-class.md) diff --git a/docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md b/docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md index 6737d1ba3a..7068a8bd01 100644 --- a/docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md +++ b/docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md @@ -2,17 +2,20 @@ description: "Learn more about: Using C++ AMP in UWP Apps" title: "Using C++ AMP in UWP Apps" ms.date: "11/04/2016" -ms.assetid: 85577298-2c28-4209-9470-eb21048615db --- # Using C++ AMP in UWP Apps You can use C++ AMP (C++ Accelerated Massive Parallelism) in your Universal Windows Platform (UWP) app to perform calculations on the GPU (Graphics Processing Unit) or other computational accelerators. However, C++ AMP doesn't provide APIs for working directly with Windows Runtime types, and the Windows Runtime doesn't provide a wrapper for C++ AMP. When you use Windows Runtime types in your code—including those that you've created yourself—you must convert them to types that are compatible with C++ AMP. +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. + ## Performance considerations -If you're using Visual C++ component extensions C++/CX to create your Universal Windows Platform (UWP) app, we recommend that you use plain-old-data (POD) types together with contiguous storage—for example, `std::vector` or C-style arrays—for data that will be used with C++ AMP. This can help you achieve higher performance than by using non-POD types or Windows RT containers because no marshaling has to occur. +If you're using Visual C++ component extensions C++/CX to create your Universal Windows Platform (UWP) app, we recommend that you use plain-old-data (POD) types together with contiguous storage—for example, `std::vector` or C-style arrays—for data that will be used with C++ AMP. This can help you achieve higher performance than by using non-POD types or Windows Runtime containers because no marshaling has to occur. -In a C++ AMP kernel, to access data that’s stored in this way, just wrap the `std::vector` or array storage in a `concurrency::array_view` and then use the array view in a `concurrency::parallel_for_each` loop: +In a C++ AMP kernel, to access data that's stored in this way, just wrap the `std::vector` or array storage in a `concurrency::array_view` and then use the array view in a `concurrency::parallel_for_each` loop: ```cpp // simple vector addition example diff --git a/docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md b/docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md index a8e3b67b6a..8daf318892 100644 --- a/docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md +++ b/docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md @@ -2,11 +2,10 @@ description: "Learn more about: Using Lambdas, Function Objects, and Restricted Functions" title: "Using Lambdas, Function Objects, and Restricted Functions" ms.date: "11/04/2016" -ms.assetid: 25346cc9-869d-4ada-aad3-e2228cad3d6c --- # Using Lambdas, Function Objects, and Restricted Functions -The C++ AMP code that you want to run on the accelerator is specified as an argument in a call to the [parallel_for_each](reference/concurrency-namespace-functions-amp.md#parallel_for_each) method. You can provide either a lambda expression or a function object (functor) as that argument. Additionally, the lambda expression or function object can call a C++ AMP-restricted function. This topic uses an array addition algorithm to demonstrate lambdas, function objects, and restricted functions. The following example shows the algorithm without C++ AMP code. Two 1-dimensional arrays of equal length are created. The corresponding integer elements are added and stored in a third 1-dimensional array. C++ AMP is not used. +The C++ AMP code that you want to run on the accelerator is specified as an argument in a call to the [`parallel_for_each`](reference/concurrency-namespace-functions-amp.md#parallel_for_each) method. You can provide either a lambda expression or a function object (functor) as that argument. Additionally, the lambda expression or function object can call a C++ AMP-restricted function. This topic uses an array addition algorithm to demonstrate lambdas, function objects, and restricted functions. The following example shows the algorithm without C++ AMP code. Two 1-dimensional arrays of equal length are created. The corresponding integer elements are added and stored in a third 1-dimensional array. C++ AMP is not used. ```cpp void CpuMethod() { diff --git a/docs/parallel/amp/using-tiles.md b/docs/parallel/amp/using-tiles.md index f315d7bc8c..a68f6a66b8 100644 --- a/docs/parallel/amp/using-tiles.md +++ b/docs/parallel/amp/using-tiles.md @@ -2,7 +2,6 @@ description: "Learn more about: Using Tiles" title: "Using Tiles" ms.date: "11/19/2018" -ms.assetid: acb86a86-2b7f-43f1-8fcf-bcc79b21d9a8 --- # Using Tiles @@ -20,6 +19,10 @@ To take advantage of tiling, your algorithm must partition the compute domain in ## Example of Global, Tile, and Local Indices +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. + The following diagram represents an 8x9 matrix of data that is arranged in 2x3 tiles. ![Diagram of an 8 by 9 matrix divided into 2 by 3 tiles.](../../parallel/amp/media/usingtilesmatrix.png) diff --git a/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md b/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md index ea0a3d6bc9..d9c3ddfd4e 100644 --- a/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md +++ b/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md @@ -9,25 +9,22 @@ helpviewer_keywords: ["debugging, C++ Accelerated Massive Parallelism", "C++ AMP This article demonstrates how to debug an application that uses C++ Accelerated Massive Parallelism (C++ AMP) to take advantage of the graphics processing unit (GPU). It uses a parallel-reduction program that sums up a large array of integers. This walkthrough illustrates the following tasks: - Launching the GPU debugger. - - Inspecting GPU threads in the GPU Threads window. - - Using the **Parallel Stacks** window to simultaneously observe the call stacks of multiple GPU threads. - - Using the **Parallel Watch** window to inspect values of a single expression across multiple threads at the same time. - - Flagging, freezing, thawing, and grouping GPU threads. - - Executing all the threads of a tile to a specific location in code. ## Prerequisites Before you start this walkthrough: -- Read [C++ AMP Overview](../../parallel/amp/cpp-amp-overview.md). +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. +- Read [C++ AMP Overview](../../parallel/amp/cpp-amp-overview.md). - Make sure that line numbers are displayed in the text editor. For more information, see [How to: Display line numbers in the editor](/visualstudio/ide/reference/how-to-display-line-numbers-in-the-editor). - - Make sure you're running at least Windows 8 or Windows Server 2012 to support debugging on the software emulator. [!INCLUDE[note_settings_general](../../mfc/includes/note_settings_general_md.md)] diff --git a/docs/parallel/amp/walkthrough-matrix-multiplication.md b/docs/parallel/amp/walkthrough-matrix-multiplication.md index 731c343fa8..b3dbcffba1 100644 --- a/docs/parallel/amp/walkthrough-matrix-multiplication.md +++ b/docs/parallel/amp/walkthrough-matrix-multiplication.md @@ -2,7 +2,6 @@ description: "Learn more about: Walkthrough: Matrix Multiplication" title: "Walkthrough: Matrix Multiplication" ms.date: 10/27/2021 -ms.assetid: 61172e8b-da71-4200-a462-ff3a908ab0cf --- # Walkthrough: Matrix Multiplication @@ -13,11 +12,13 @@ This step-by-step walkthrough demonstrates how to use C++ AMP to accelerate the Before you start: - Read [C++ AMP Overview](../../parallel/amp/cpp-amp-overview.md). - - Read [Using Tiles](../../parallel/amp/using-tiles.md). - - Make sure that you are running at least Windows 7, or Windows Server 2008 R2. +> [!NOTE] +> C++ AMP headers are deprecated starting with Visual Studio 2022 version 17.0. +> Including any AMP headers will generate build errors. Define `_SILENCE_AMP_DEPRECATION_WARNINGS` before including any AMP headers to silence the warnings. + ### To create the project Instructions for creating a new project vary depending on which version of Visual Studio you have installed. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. diff --git a/docs/parallel/auto-parallelization-and-auto-vectorization.md b/docs/parallel/auto-parallelization-and-auto-vectorization.md index b6239866e8..47ed363f7b 100644 --- a/docs/parallel/auto-parallelization-and-auto-vectorization.md +++ b/docs/parallel/auto-parallelization-and-auto-vectorization.md @@ -19,7 +19,7 @@ void loop_test(int u) { } ``` -Because `u` could be a small value, the compiler won’t automatically parallelize this loop. However, you might still want it parallelized because you know that `u` will always be large. To enable the auto-parallelization, specify [#pragma loop(hint_parallel(n))](../preprocessor/loop.md), where `n` is the number of threads to parallelize across. In the following example, the compiler will attempt to parallelize the loop across 8 threads. +Because `u` could be a small value, the compiler won't automatically parallelize this loop. However, you might still want it parallelized because you know that `u` will always be large. To enable the auto-parallelization, specify [#pragma loop(hint_parallel(n))](../preprocessor/loop.md), where `n` is the number of threads to parallelize across. In the following example, the compiler will attempt to parallelize the loop across 8 threads. ```cpp void loop_test(int u) { @@ -31,7 +31,7 @@ void loop_test(int u) { As with all [pragma directives](../preprocessor/pragma-directives-and-the-pragma-keyword.md), the alternate pragma syntax `__pragma(loop(hint_parallel(n)))` is also supported. -There are some loops that the compiler can’t parallelize even if you want it to. Here's an example: +There are some loops that the compiler can't parallelize even if you want it to. Here's an example: ```cpp #pragma loop(hint_parallel(8)) @@ -39,7 +39,7 @@ for (int i=0; i __int64 time_call(Function&& f) { - __int64 begin = GetTickCount(); - f(); - return GetTickCount() - begin; + __int64 begin = GetTickCount(); + f(); + return GetTickCount() - begin; } -// Determines whether the input value is prime. +// Determines whether the input is a prime. bool is_prime(int n) { - if (n < 2) - return false; - for (int i = 2; i < n; ++i) - { - if ((n % i) == 0) - return false; - } - return true; + if (n < 2) + { + return false; + } + + for (int i = 2; i < int(std::sqrt(n)) + 1; ++i) + { + if (n % i == 0) + { + return false; + } + } + return true; } int wmain() { - // Create an array object that contains 200000 integers. - array a; + // Create an array object that contains 200000 integers. + array a; - // Initialize the array such that a[i] == i. - int n = 0; - generate(begin(a), end(a), [&] { - return n++; - }); + // Initialize the array such that a[i] == i. + int n = 0; + generate(begin(a), end(a), [&] + { + return n++; + }); - LONG prime_count; - __int64 elapsed; + // Use the for_each algorithm to count, serially, the number + // of prime numbers in the array. + LONG prime_count = 0L; + __int64 elapsed = time_call([&] + { + for_each(begin(a), end(a), [&](int n) + { + if (is_prime(n)) + { + ++prime_count; + } + }); + }); + + wcout << L"serial version: " << endl + << L"found " << prime_count << L" prime numbers" << endl + << L"took " << elapsed << L" ms" << endl << endl; - // Use the for_each algorithm to count the number of prime numbers - // in the array serially. - prime_count = 0L; - elapsed = time_call([&] { - for_each (begin(a), end(a), [&](int n ) { - if (is_prime(n)) - ++prime_count; - }); - }); - wcout << L"serial version: " << endl - << L"found " << prime_count << L" prime numbers" << endl - << L"took " << elapsed << L" ms" << endl << endl; + // Use the parallel_for_each algorithm to count, in parallel, the number + // of prime numbers in the array. + prime_count = 0L; + elapsed = time_call([&] + { + parallel_for_each(begin(a), end(a), [&](int n) + { + if (is_prime(n)) + { + InterlockedIncrement(&prime_count); + } + }); + }); - // Use the parallel_for_each algorithm to count the number of prime numbers - // in the array in parallel. - prime_count = 0L; - elapsed = time_call([&] { - parallel_for_each (begin(a), end(a), [&](int n ) { - if (is_prime(n)) - InterlockedIncrement(&prime_count); - }); - }); - wcout << L"parallel version: " << endl - << L"found " << prime_count << L" prime numbers" << endl - << L"took " << elapsed << L" ms" << endl << endl; + wcout << L"parallel version: " << endl + << L"found " << prime_count << L" prime numbers" << endl + << L"took " << elapsed << L" ms" << endl << endl; } \ No newline at end of file diff --git a/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp b/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp index 3e692feda1..d5c65363dd 100644 --- a/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp @@ -5,7 +5,6 @@ void run() size_t negative_count = 0; size_t positive_count = 0; - // Write the counts to the message buffers. send(_negatives, negative_count); send(_positives, positive_count); diff --git a/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md b/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md index e364db3f15..222c1f490b 100644 --- a/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md +++ b/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md @@ -53,7 +53,7 @@ A task-based continuation enables you to handle any exception that is thrown by We recommend that you use task-based continuations to catch exceptions that you are able to handle. Because task-based continuations always run, consider whether to add a task-based continuation at the end of your continuation chain. This can help guarantee that your code observes all exceptions. The following example shows a basic value-based continuation chain. The third task in the chain throws, and therefore any value-based continuations that follow it are not run. However, the final continuation is task-based, and therefore always runs. This final continuation handles the exception that is thrown by the third task. -We recommend that you catch the most specific exceptions that you can. You can omit this final task-based continuation if you don’t have specific exceptions to catch. Any exception will remain unhandled and can terminate the app. +We recommend that you catch the most specific exceptions that you can. You can omit this final task-based continuation if you don't have specific exceptions to catch. Any exception will remain unhandled and can terminate the app. [!code-cpp[concrt-eh-task-chain#1](../../parallel/concrt/codesnippet/cpp/exception-handling-in-the-concurrency-runtime_3.cpp)] diff --git a/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md b/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md index 403e3bf2d7..78bf360135 100644 --- a/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md +++ b/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md @@ -38,27 +38,27 @@ This section describes how to use the `parallel_invoke` algorithm to perform the 1. Add a `#include` directive for the header file ppl.h. -[!code-cpp[concrt-parallel-bitonic-sort#10](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_2.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#10](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_2.cpp)] 1. Add a **`using`** directive for the `concurrency` namespace. -[!code-cpp[concrt-parallel-bitonic-sort#11](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_3.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#11](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_3.cpp)] 1. Create a new function, called `parallel_bitonic_mege`, which uses the `parallel_invoke` algorithm to merge the sequences in parallel if there is sufficient amount of work to do. Otherwise, call `bitonic_merge` to merge the sequences serially. -[!code-cpp[concrt-parallel-bitonic-sort#2](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_4.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#2](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_4.cpp)] 1. Perform a process that resembles the one in the previous step, but for the `bitonic_sort` function. -[!code-cpp[concrt-parallel-bitonic-sort#3](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_5.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#3](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_5.cpp)] 1. Create an overloaded version of the `parallel_bitonic_sort` function that sorts the array in increasing order. -[!code-cpp[concrt-parallel-bitonic-sort#4](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_6.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#4](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_6.cpp)] -The `parallel_invoke` algorithm reduces overhead by performing the last of the series of tasks on the calling context. For example, in the `parallel_bitonic_sort` function, the first task runs on a separate context, and the second task runs on the calling context. + The `parallel_invoke` algorithm reduces overhead by performing the last of the series of tasks on the calling context. For example, in the `parallel_bitonic_sort` function, the first task runs on a separate context, and the second task runs on the calling context. -[!code-cpp[concrt-parallel-bitonic-sort#5](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_7.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#5](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_7.cpp)] The following complete example performs both the serial and the parallel versions of the bitonic sort algorithm. The example also prints to the console the time that is required to perform each computation. diff --git a/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md b/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md index d7a5805ed7..3351136b79 100644 --- a/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md +++ b/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: How to: Write a parallel_for_each Loop" -title: "How to: Write a parallel_for_each Loop" -ms.date: "11/04/2016" +description: "Learn more about how to write a parallel_for_each Loop" +title: "How to: write a parallel_for_each Loop" +ms.date: 09/12/2022 helpviewer_keywords: ["writing a parallel_for_each loop [Concurrency Runtime]", "parallel_for_each function, example"] -ms.assetid: fa9c0ba6-ace0-4f88-8681-c7c1f52aff20 --- -# How to: Write a parallel_for_each Loop +# How to: Write a `parallel_for_each` Loop -This example shows how to use the [concurrency::parallel_for_each](reference/concurrency-namespace-functions.md#parallel_for_each) algorithm to compute the count of prime numbers in a [std::array](../../standard-library/array-class-stl.md) object in parallel. +This example shows how to use the [`concurrency::parallel_for_each`](reference/concurrency-namespace-functions.md#parallel_for_each) algorithm to compute the count of prime numbers in a [`std::array`](../../standard-library/array-class-stl.md) object in parallel. ## Example -The following example computes the count of prime numbers in an array two times. The example first uses the [std::for_each](../../standard-library/algorithm-functions.md#for_each) algorithm to compute the count serially. The example then uses the `parallel_for_each` algorithm to perform the same task in parallel. The example also prints to the console the time that is required to perform both computations. +The following example computes the count of prime numbers in an array two times. The example first uses the [`std::for_each`](../../standard-library/algorithm-functions.md#for_each) algorithm to compute the count serially. The example then uses the `parallel_for_each` algorithm to perform the same task in parallel. The example also prints to the console the time that is required to perform both computations. [!code-cpp[concrt-parallel-count-primes#1](../../parallel/concrt/codesnippet/cpp/how-to-write-a-parallel-for-each-loop_1.cpp)] -The following sample output is for a computer that has four processors. +The following sample output is for a computer that has four cores. ```Output serial version: found 17984 prime numbers -took 6115 ms +took 125 ms parallel version: found 17984 prime numbers -took 1653 ms +took 63 ms ``` ## Compiling the Code @@ -35,9 +34,9 @@ To compile the code, copy it and then paste it in a Visual Studio project, or pa ## Robust Programming -The lambda expression that the example passes to the `parallel_for_each` algorithm uses the `InterlockedIncrement` function to enable parallel iterations of the loop to increment the counter simultaneously. If you use functions such as `InterlockedIncrement` to synchronize access to shared resources, you can present performance bottlenecks in your code. You can use a lock-free synchronization mechanism, for example, the [concurrency::combinable](../../parallel/concrt/reference/combinable-class.md) class, to eliminate simultaneous access to shared resources. For an example that uses the `combinable` class in this manner, see [How to: Use combinable to Improve Performance](../../parallel/concrt/how-to-use-combinable-to-improve-performance.md). +The lambda expression that the example passes to the `parallel_for_each` algorithm uses the `InterlockedIncrement` function to enable parallel iterations of the loop to increment the counter simultaneously. If you use functions such as `InterlockedIncrement` to synchronize access to shared resources, you can present performance bottlenecks in your code. You can use a lock-free synchronization mechanism, for example, the [`concurrency::combinable`](../../parallel/concrt/reference/combinable-class.md) class, to eliminate simultaneous access to shared resources. For an example that uses the `combinable` class in this manner, see [How to: Use combinable to improve performance](../../parallel/concrt/how-to-use-combinable-to-improve-performance.md). ## See also -[Parallel Algorithms](../../parallel/concrt/parallel-algorithms.md)
-[parallel_for_each Function](reference/concurrency-namespace-functions.md#parallel_for_each) +[Parallel algorithms](../../parallel/concrt/parallel-algorithms.md)\ +[`parallel_for_each` Function](reference/concurrency-namespace-functions.md#parallel_for_each) diff --git a/docs/parallel/concrt/parallel-algorithms.md b/docs/parallel/concrt/parallel-algorithms.md index d6513e3a85..b9f60473e1 100644 --- a/docs/parallel/concrt/parallel-algorithms.md +++ b/docs/parallel/concrt/parallel-algorithms.md @@ -265,7 +265,7 @@ For illustration, this example uses a relatively small data set. You can increas This example uses a lambda expression as the hash function. You can also use one of the built-in implementations of the std::[hash class](../../standard-library/hash-class.md) or define your own specialization. You can also use a custom hash function object, as shown in this example: [!code-cpp[concrt-parallel-sort-points#2](../../parallel/concrt/codesnippet/cpp/parallel-algorithms_13.cpp)] - +  [!code-cpp[concrt-parallel-sort-points#3](../../parallel/concrt/codesnippet/cpp/parallel-algorithms_14.cpp)] The hash function must return an integral type ([std::is_integral::value](../../standard-library/is-integral-class.md) must be **`true`**). This integral type must be convertible to type `size_t`. diff --git a/docs/parallel/concrt/reference/concurrency-namespace-functions.md b/docs/parallel/concrt/reference/concurrency-namespace-functions.md index f1aea9adb8..10f4a1627f 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-functions.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: concurrency namespace functions" title: "concurrency namespace functions" -ms.date: "11/04/2016" +description: "Learn more about: concurrency namespace functions" +ms.date: 11/04/2016 f1_keywords: ["concrt/concurrency::Alloc", "concrt/concurrency::DisableTracing", "concrt/concurrency::EnableTracing", "concrtrm/concurrency::GetExecutionContextId", "concrtrm/concurrency::GetOSVersion", "concrtrm/concurrency::GetProcessorNodeCount", "concrtrm/concurrency::GetSchedulerId", "agents/concurrency::asend", "ppltasks/concurrency::cancel_current_task", "ppltasks/concurrency::create_async", "ppltasks/concurrency::create_task", "concurrent_vector/concurrency::internal_assign_iterators", "ppl/concurrency::interruption_point", "agents/concurrency::make_choice", "agents/concurrency::make_greedy_join", "ppl/concurrency::make_task", "ppl/concurrency::parallel_buffered_sort", "ppl/concurrency::parallel_for_each", "ppl/concurrency::parallel_invoke", "ppl/concurrency::parallel_reduce", "ppl/concurrency::parallel_sort", "agents/concurrency::receive", "ppl/concurrency::run_with_cancellation_token", "pplconcrt/concurrency::set_ambient_scheduler", "concrt/concurrency::set_task_execution_resources", "ppltasks/concurrency::task_from_exception", "ppltasks/concurrency::task_from_result", "concrt/concurrency::wait", "ppltasks/concurrency::when_all", "ppltasks/concurrency::when_any"] -ms.assetid: 520a6dff-9324-4df2-990d-302e3050af6a --- # concurrency namespace functions @@ -175,7 +174,7 @@ The lambda may take either zero, one or two arguments. The valid arguments are ` If the body of the lambda or function object returns a result (and not a task\), the lamdba will be executed asynchronously within the process MTA in the context of a task the Runtime implicitly creates for it. The `IAsyncInfo::Cancel` method will cause cancellation of the implicit task. -If the body of the lambda returns a task, the lamba executes inline, and by declaring the lambda to take an argument of type `cancellation_token` you can trigger cancellation of any tasks you create within the lambda by passing that token in when you create them. You may also use the `register_callback` method on the token to cause the Runtime to invoke a callback when you call `IAsyncInfo::Cancel` on the async operation or action produced.. +If the body of the lambda returns a task, the lambda executes inline, and by declaring the lambda to take an argument of type `cancellation_token` you can trigger cancellation of any tasks you create within the lambda by passing that token in when you create them. You may also use the `register_callback` method on the token to cause the Runtime to invoke a callback when you call `IAsyncInfo::Cancel` on the async operation or action produced. This function is only available to Windows Runtime apps. @@ -1532,7 +1531,7 @@ The concurrent vector providing the elements to be swapped, or the vector whose ### Remarks -The template function is an algorithm specialized on the container class `concurrent_vector` to execute the member function `_A`. [concurrent_vector::swap](concurrent-vector-class.md#swap)( `_B`). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, `template void swap(T&, T&)`, in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class `concurrent_vector` to execute the member function `_A`. [concurrent_vector::swap](concurrent-vector-class.md#swap)(`_B`). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, `template void swap(T&, T&)`, in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. This method is not concurrency-safe. You must ensure that no other threads are performing operations on either of the concurrent vectors when you call this method. diff --git a/docs/parallel/concrt/reference/concurrency-namespace.md b/docs/parallel/concrt/reference/concurrency-namespace.md index 0a1a9c5e11..a336049731 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace.md +++ b/docs/parallel/concrt/reference/concurrency-namespace.md @@ -203,7 +203,7 @@ namespace concurrency; |----------|-----------------| |[operator!=](concurrency-namespace-operators.md#operator_neq)|Tests if the `concurrent_vector` object on the left side of the operator is not equal to the `concurrent_vector` object on the right side.| |[operator&&](concurrency-namespace-operators.md#operator_amp_amp)|Overloaded. Creates a task that will complete successfully when both of the tasks supplied as arguments complete successfully.| -|[operator||](concurrency-namespace-operators.md#operator_lor)|Overloaded. Creates a task that will complete successfully when either of the tasks supplied as arguments completes successfully.| +|[`operator||`](concurrency-namespace-operators.md#operator_lor)|Overloaded. Creates a task that will complete successfully when either of the tasks supplied as arguments completes successfully.| |[operator<](concurrency-namespace-operators.md#operator_lt)|Tests if the `concurrent_vector` object on the left side of the operator is less than the `concurrent_vector` object on the right side.| |[operator<=](concurrency-namespace-operators.md#operator_lt_eq)|Tests if the `concurrent_vector` object on the left side of the operator is less than or equal to the `concurrent_vector` object on the right side.| |[operator==](concurrency-namespace-operators.md#operator_eq_eq)|Tests if the `concurrent_vector` object on the left side of the operator is equal to the `concurrent_vector` object on the right side.| diff --git a/docs/parallel/concrt/reference/concurrent-priority-queue-class.md b/docs/parallel/concrt/reference/concurrent-priority-queue-class.md index 8e190a3606..5a6ba9ae4e 100644 --- a/docs/parallel/concrt/reference/concurrent-priority-queue-class.md +++ b/docs/parallel/concrt/reference/concurrent-priority-queue-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_priority_queue Class" title: "concurrent_priority_queue Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_priority_queue Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_priority_queue", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::concurrent_priority_queue", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::clear", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::empty", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::get_allocator", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::push", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::size", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::swap", "CONCURRENT_PRIORITY_QUEUE/concurrency::concurrent_priority_queue::try_pop"] helpviewer_keywords: ["concurrent_priority_queue class"] -ms.assetid: 3e740381-0f4e-41fc-8b66-ad0bb55f17a3 --- # concurrent_priority_queue Class @@ -14,10 +13,9 @@ The `concurrent_priority_queue` class is a container that allows multiple thread ```cpp template , - typename _Ax = std::allocator ->, - typename _Ax = std::allocator> class concurrent_priority_queue; + typename _Compare = std::less, + typename _Ax = std::allocator> +class concurrent_priority_queue; ``` ### Parameters diff --git a/docs/parallel/concrt/reference/concurrent-unordered-map-class.md b/docs/parallel/concrt/reference/concurrent-unordered-map-class.md index c9e47fc292..b777495b54 100644 --- a/docs/parallel/concrt/reference/concurrent-unordered-map-class.md +++ b/docs/parallel/concrt/reference/concurrent-unordered-map-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_unordered_map Class" title: "concurrent_unordered_map Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_unordered_map Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_unordered_map", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::concurrent_unordered_map", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::at", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::hash_function", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::insert", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::key_eq", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::swap", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_map::unsafe_erase"] helpviewer_keywords: ["concurrent_unordered_map class"] -ms.assetid: b2d879dd-87ef-4af9-a266-a5443fd538b8 --- # concurrent_unordered_map Class @@ -17,18 +16,8 @@ template , typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator> ->, -typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator>> class concurrent_unordered_map : public details::_Concurrent_hash, - _Allocator_type, -false>>; + typename _Allocator_type = std::allocator>> +class concurrent_unordered_map : public details::_Concurrent_hash, _Allocator_type, false>>; ``` ### Parameters @@ -81,7 +70,7 @@ The type that represents the stored allocator object that encapsulates details a |Name|Description| |----------|-----------------| -|[at](#at)|Overloaded. Finds an element in a `concurrent_unordered_map` with a specified key value.. This method is concurrency-safe.| +|[at](#at)|Overloaded. Finds an element in a `concurrent_unordered_map` with a specified key value. This method is concurrency-safe.| |[hash_function](#hash_function)|Gets the stored hash function object.| |[insert](#insert)|Overloaded. Adds elements to the `concurrent_unordered_map` object.| |[key_eq](#key_eq)|Gets the stored equality comparison function object.| @@ -115,7 +104,7 @@ For detailed information on the `concurrent_unordered_map` class, see [Parallel ## at -Finds an element in a `concurrent_unordered_map` with a specified key value.. This method is concurrency-safe. +Finds an element in a `concurrent_unordered_map` with a specified key value. This method is concurrency-safe. ```cpp mapped_type& at(const key_type& KVal); @@ -430,7 +419,7 @@ A pair that contains an iterator and a boolean value. See the Remarks section fo The first member function determines whether an element X exists in the sequence whose key has equivalent ordering to that of `value`. If not, it creates such an element X and initializes it with `value`. The function then determines the iterator `where` that designates X. If an insertion occurred, the function returns `std::pair(where, true)`. Otherwise, it returns `std::pair(where, false)`. -The second member function returns insert( `value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. +The second member function returns insert(`value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. The third member function inserts the sequence of element values from the range [ `first`, `last`). @@ -476,7 +465,7 @@ void max_load_factor(float _Newmax); ### Return Value -The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid.. +The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid. ## max_size @@ -766,5 +755,5 @@ The maximum number of buckets in this container. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [Parallel Containers and Objects](../../../parallel/concrt/parallel-containers-and-objects.md) diff --git a/docs/parallel/concrt/reference/concurrent-unordered-multimap-class.md b/docs/parallel/concrt/reference/concurrent-unordered-multimap-class.md index 9ede5be1d2..a28357a21e 100644 --- a/docs/parallel/concrt/reference/concurrent-unordered-multimap-class.md +++ b/docs/parallel/concrt/reference/concurrent-unordered-multimap-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_unordered_multimap Class" title: "concurrent_unordered_multimap Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_unordered_multimap Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_unordered_multimap", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::concurrent_unordered_multimap", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::hash_function", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::insert", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::key_eq", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::swap", "CONCURRENT_UNORDERED_MAP/concurrency::concurrent_unordered_multimap::unsafe_erase"] helpviewer_keywords: ["concurrent_unordered_multimap class"] -ms.assetid: 4dada5d7-15df-4382-b9c9-348e75b2f3c1 --- # concurrent_unordered_multimap Class @@ -17,18 +16,8 @@ template , typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator> ->, -typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator>> class concurrent_unordered_multimap : public details::_Concurrent_hash, - _Allocator_type, -true>>; + typename _Allocator_type = std::allocator>> +class concurrent_unordered_multimap : public details::_Concurrent_hash, _Allocator_type, true>>; ``` ### Parameters @@ -403,7 +392,7 @@ An iterator pointing to the insertion location. The first member function inserts the element `value` in the controlled sequence, then returns the iterator that designates the inserted element. -The second member function returns insert( `value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. +The second member function returns insert(`value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. The third member function inserts the sequence of element values from the range [ `first`, `last`). @@ -449,7 +438,7 @@ void max_load_factor(float _Newmax); ### Return Value -The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid.. +The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid. ## max_size @@ -708,5 +697,5 @@ The maximum number of buckets in this container. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [Parallel Containers and Objects](../../../parallel/concrt/parallel-containers-and-objects.md) diff --git a/docs/parallel/concrt/reference/concurrent-unordered-multiset-class.md b/docs/parallel/concrt/reference/concurrent-unordered-multiset-class.md index 3684631591..487bba1780 100644 --- a/docs/parallel/concrt/reference/concurrent-unordered-multiset-class.md +++ b/docs/parallel/concrt/reference/concurrent-unordered-multiset-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_unordered_multiset Class" title: "concurrent_unordered_multiset Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_unordered_multiset Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_unordered_multiset", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::concurrent_unordered_multiset", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::hash_function", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::insert", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::key_eq", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::swap", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_multiset::unsafe_erase"] helpviewer_keywords: ["concurrent_unordered_multiset class"] -ms.assetid: 219d7d67-1ff0-45f4-9400-e9cc272991a4 --- # concurrent_unordered_multiset Class @@ -16,15 +15,8 @@ The `concurrent_unordered_multiset` class is an concurrency-safe container that template , typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator ->, - typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator> class concurrent_unordered_multiset : public details::_Concurrent_hash, -_Allocator_type, - true>>; + typename _Allocator_type = std::allocator> +class concurrent_unordered_multiset : public details::_Concurrent_hash, _Allocator_type, true>>; ``` ### Parameters @@ -391,7 +383,7 @@ An iterator pointing to the insertion location. The first member function inserts the element `value` in the controlled sequence, then returns the iterator that designates the inserted element. -The second member function returns insert( `value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. +The second member function returns insert(`value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. The third member function inserts the sequence of element values from the range [ `first`, `last`). @@ -437,7 +429,7 @@ void max_load_factor(float _Newmax); ### Return Value -The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid.. +The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid. ## max_size @@ -694,5 +686,5 @@ The maximum number of buckets in this container. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [Parallel Containers and Objects](../../../parallel/concrt/parallel-containers-and-objects.md) diff --git a/docs/parallel/concrt/reference/concurrent-unordered-set-class.md b/docs/parallel/concrt/reference/concurrent-unordered-set-class.md index 52f91b4cfa..5265d958e5 100644 --- a/docs/parallel/concrt/reference/concurrent-unordered-set-class.md +++ b/docs/parallel/concrt/reference/concurrent-unordered-set-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_unordered_set Class" title: "concurrent_unordered_set Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_unordered_set Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_unordered_set", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::concurrent_unordered_set", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::hash_function", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::insert", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::key_eq", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::swap", "CONCURRENT_UNORDERED_SET/concurrency::concurrent_unordered_set::unsafe_erase"] helpviewer_keywords: ["concurrent_unordered_set class"] -ms.assetid: c61f9a9a-4fd9-491a-9251-e300737ecf4b --- # concurrent_unordered_set Class @@ -16,15 +15,8 @@ The `concurrent_unordered_set` class is an concurrency-safe container that contr template , typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator ->, - typename key_equality = std::equal_to, - typename _Allocator_type = std::allocator> class concurrent_unordered_set : public details::_Concurrent_hash, -_Allocator_type, - false>>; + typename _Allocator_type = std::allocator> +class concurrent_unordered_set : public details::_Concurrent_hash, _Allocator_type, false>>; ``` ### Parameters @@ -393,7 +385,7 @@ A pair that contains an iterator and a boolean value. See the Remarks section fo The first member function determines whether an element X exists in the sequence whose key has equivalent ordering to that of `value`. If not, it creates such an element X and initializes it with `value`. The function then determines the iterator `where` that designates X. If an insertion occurred, the function returns `std::pair(where, true)`. Otherwise, it returns `std::pair(where, false)`. -The second member function returns insert( `value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. +The second member function returns insert(`value`), using `_Where` as a starting place within the controlled sequence to search for the insertion point. The third member function inserts the sequence of element values from the range [ `first`, `last`). @@ -439,7 +431,7 @@ void max_load_factor(float _Newmax); ### Return Value -The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid.. +The first member function returns the stored maximum load factor. The second member function does not return a value but throws an [out_of_range](../../../standard-library/out-of-range-class.md) exception if the supplied load factor is invalid. ## max_size @@ -698,5 +690,5 @@ The maximum number of buckets in this container. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [Parallel Containers and Objects](../../../parallel/concrt/parallel-containers-and-objects.md) diff --git a/docs/parallel/concrt/reference/concurrent-vector-class.md b/docs/parallel/concrt/reference/concurrent-vector-class.md index af0edeecb8..1bdeb6f2c0 100644 --- a/docs/parallel/concrt/reference/concurrent-vector-class.md +++ b/docs/parallel/concrt/reference/concurrent-vector-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrent_vector Class" title: "concurrent_vector Class" -ms.date: "11/04/2016" +description: "Learn more about: concurrent_vector Class" +ms.date: 11/04/2016 f1_keywords: ["concurrent_vector", "CONCURRENT_VECTOR/concurrency::concurrent_vector", "CONCURRENT_VECTOR/concurrency::concurrent_vector::concurrent_vector", "CONCURRENT_VECTOR/concurrency::concurrent_vector::assign", "CONCURRENT_VECTOR/concurrency::concurrent_vector::at", "CONCURRENT_VECTOR/concurrency::concurrent_vector::back", "CONCURRENT_VECTOR/concurrency::concurrent_vector::begin", "CONCURRENT_VECTOR/concurrency::concurrent_vector::capacity", "CONCURRENT_VECTOR/concurrency::concurrent_vector::cbegin", "CONCURRENT_VECTOR/concurrency::concurrent_vector::cend", "CONCURRENT_VECTOR/concurrency::concurrent_vector::clear", "CONCURRENT_VECTOR/concurrency::concurrent_vector::crbegin", "CONCURRENT_VECTOR/concurrency::concurrent_vector::crend", "CONCURRENT_VECTOR/concurrency::concurrent_vector::empty", "CONCURRENT_VECTOR/concurrency::concurrent_vector::end", "CONCURRENT_VECTOR/concurrency::concurrent_vector::front", "CONCURRENT_VECTOR/concurrency::concurrent_vector::get_allocator", "CONCURRENT_VECTOR/concurrency::concurrent_vector::grow_by", "CONCURRENT_VECTOR/concurrency::concurrent_vector::grow_to_at_least", "CONCURRENT_VECTOR/concurrency::concurrent_vector::max_size", "CONCURRENT_VECTOR/concurrency::concurrent_vector::push_back", "CONCURRENT_VECTOR/concurrency::concurrent_vector::rbegin", "CONCURRENT_VECTOR/concurrency::concurrent_vector::rend", "CONCURRENT_VECTOR/concurrency::concurrent_vector::reserve", "CONCURRENT_VECTOR/concurrency::concurrent_vector::resize", "CONCURRENT_VECTOR/concurrency::concurrent_vector::shrink_to_fit", "CONCURRENT_VECTOR/concurrency::concurrent_vector::size", "CONCURRENT_VECTOR/concurrency::concurrent_vector::swap"] helpviewer_keywords: ["concurrent_vector class"] -ms.assetid: a217b4ac-af2b-4d41-94eb-09a75ee28622 --- # concurrent_vector Class @@ -318,9 +317,9 @@ The second and third constructors specify a copy of the concurrent vector `_Vect The fourth constructor specifies a move of the concurrent vector `_Vector`. -The fifth constructor specifies a repetition of a specified number ( `_N`) of elements of the default value for class `T`. +The fifth constructor specifies a repetition of a specified number (`_N`) of elements of the default value for class `T`. -The sixth constructor specifies a repetition of ( `_N`) elements of value `_Item`. +The sixth constructor specifies a repetition of (`_N`) elements of value `_Item`. The last constructor specifies values supplied by the iterator range [ `_Begin`, `_End`). diff --git a/docs/parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md b/docs/parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md index b88cbe2494..eb5b16e095 100644 --- a/docs/parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md +++ b/docs/parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: invalid_scheduler_policy_thread_specification Class" title: "invalid_scheduler_policy_thread_specification Class" +description: "Learn more about: invalid_scheduler_policy_thread_specification Class" ms.date: "11/04/2016" f1_keywords: ["concrt/concurrency::invalid_scheduler_policy_thread_specification"] helpviewer_keywords: ["invalid_scheduler_policy_thread_specification class"] -ms.assetid: 2d0fafb2-18f8-4284-8040-3db640d33303 --- # invalid_scheduler_policy_thread_specification Class @@ -22,7 +21,7 @@ class invalid_scheduler_policy_thread_specification : public std::exception; |Name|Description| |----------|-----------------| -|[invalid_scheduler_policy_thread_specification](invalid-scheduler-policy-value-class.md#ctor|Overloaded. Constructs an `invalid_scheduler_policy_value` object.| +|[invalid_scheduler_policy_thread_specification](#ctor)|Overloaded. Constructs an `invalid_scheduler_policy_thread_specification` object.| ## Inheritance Hierarchy @@ -48,10 +47,10 @@ invalid_scheduler_policy_thread_specification() throw(); ### Parameters -*_Message*
+*_Message*\ A descriptive message of the error. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [SchedulerPolicy Class](schedulerpolicy-class.md) diff --git a/docs/parallel/concrt/reference/invalid-scheduler-policy-value-class.md b/docs/parallel/concrt/reference/invalid-scheduler-policy-value-class.md index 111cc7fea2..8fbbc42ddf 100644 --- a/docs/parallel/concrt/reference/invalid-scheduler-policy-value-class.md +++ b/docs/parallel/concrt/reference/invalid-scheduler-policy-value-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: invalid_scheduler_policy_value Class" title: "invalid_scheduler_policy_value Class" +description: "Learn more about: invalid_scheduler_policy_value Class" ms.date: "11/04/2016" f1_keywords: ["concrt/concurrency::invalid_scheduler_policy_value"] helpviewer_keywords: ["invalid_scheduler_policy_value class"] -ms.assetid: 8c533e3f-2774-4192-8616-b2313b859bf7 --- # invalid_scheduler_policy_value Class @@ -22,7 +21,7 @@ class invalid_scheduler_policy_value : public std::exception; |Name|Description| |----------|-----------------| -|[invalid_scheduler_policy_value](invalid-scheduler-policy-thread-specification-class.md#ctor|Overloaded. Constructs an `invalid_scheduler_policy_value` object.| +|[invalid_scheduler_policy_value](#ctor)|Overloaded. Constructs an `invalid_scheduler_policy_value` object.| ## Inheritance Hierarchy @@ -48,10 +47,10 @@ invalid_scheduler_policy_value() throw(); ### Parameters -*_Message*
+*_Message*\ A descriptive message of the error. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [SchedulerPolicy Class](schedulerpolicy-class.md) diff --git a/docs/parallel/concrt/reference/reader-writer-lock-class.md b/docs/parallel/concrt/reference/reader-writer-lock-class.md index eba54f6f74..ef5263b57d 100644 --- a/docs/parallel/concrt/reference/reader-writer-lock-class.md +++ b/docs/parallel/concrt/reference/reader-writer-lock-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: reader_writer_lock Class" title: "reader_writer_lock Class" +description: "Learn more about: reader_writer_lock Class" ms.date: "11/04/2016" f1_keywords: ["reader_writer_lock", "CONCRT/concurrency::reader_writer_lock", "CONCRT/concurrency::reader_writer_lock::scoped_lock", "CONCRT/concurrency::reader_writer_lock::scoped_lock_read", "CONCRT/concurrency::reader_writer_lock::reader_writer_lock", "CONCRT/concurrency::reader_writer_lock::lock", "CONCRT/concurrency::reader_writer_lock::lock_read", "CONCRT/concurrency::reader_writer_lock::try_lock", "CONCRT/concurrency::reader_writer_lock::try_lock_read", "CONCRT/concurrency::reader_writer_lock::unlock"] helpviewer_keywords: ["reader_writer_lock class"] -ms.assetid: 91a59cd2-ca05-4b74-8398-d826d9f86736 --- # reader_writer_lock Class @@ -158,7 +157,7 @@ explicit _CRTIMP scoped_lock_read(reader_writer_lock& _Reader_writer_lock); *_Reader_writer_lock*
The `reader_writer_lock` object to acquire as a reader. -## reader_writer_lock::scoped_lock_read::~scoped_lock_read Destructor +## reader_writer_lock::scoped_lock_read::~scoped_lock_read Destructor Destroys a `scoped_lock_read` object and releases the lock supplied in its constructor. @@ -206,5 +205,5 @@ If there are writers waiting on the lock, the release of the lock will always go ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [critical_section Class](critical-section-class.md) diff --git a/docs/parallel/concrt/reference/source-link-manager-class.md b/docs/parallel/concrt/reference/source-link-manager-class.md index d3ab18135c..ce7031d816 100644 --- a/docs/parallel/concrt/reference/source-link-manager-class.md +++ b/docs/parallel/concrt/reference/source-link-manager-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: source_link_manager Class" title: "source_link_manager Class" +description: "Learn more about: source_link_manager Class" ms.date: "11/04/2016" f1_keywords: ["source_link_manager", "AGENTS/concurrency::source_link_manager", "AGENTS/concurrency::source_link_manager::source_link_manager", "AGENTS/concurrency::source_link_manager::add", "AGENTS/concurrency::source_link_manager::begin", "AGENTS/concurrency::source_link_manager::contains", "AGENTS/concurrency::source_link_manager::count", "AGENTS/concurrency::source_link_manager::reference", "AGENTS/concurrency::source_link_manager::register_target_block", "AGENTS/concurrency::source_link_manager::release", "AGENTS/concurrency::source_link_manager::remove", "AGENTS/concurrency::source_link_manager::set_bound"] helpviewer_keywords: ["source_link_manager class"] -ms.assetid: 287487cf-e0fe-4c35-aa3c-24f081d1ddae --- # source_link_manager Class @@ -56,7 +55,7 @@ The network link registry. ## Remarks -Currently, the source blocks are reference counted. This is a wrapper on a `network_link_registry` object that allows concurrent access to the links and provides the ability to reference the links through callbacks. Message blocks ( `target_block`s or `propagator_block`s) should use this class for their source links. +Currently, the source blocks are reference counted. This is a wrapper on a `network_link_registry` object that allows concurrent access to the links and provides the ability to reference the links through callbacks. Message blocks (`target_block`s or `propagator_block`s) should use this class for their source links. ## Inheritance Hierarchy @@ -203,6 +202,6 @@ Destroys the `source_link_manager` object. ## See also -[concurrency Namespace](concurrency-namespace.md)
-[single_link_registry Class](single-link-registry-class.md)
+[concurrency Namespace](concurrency-namespace.md)\ +[single_link_registry Class](single-link-registry-class.md)\ [multi_link_registry Class](multi-link-registry-class.md) diff --git a/docs/parallel/concrt/reference/task-class.md b/docs/parallel/concrt/reference/task-class.md index 5f90e1fb29..18fabb896c 100644 --- a/docs/parallel/concrt/reference/task-class.md +++ b/docs/parallel/concrt/reference/task-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: task Class (Concurrency Runtime)" title: "task Class (Concurrency Runtime)" -ms.date: "07/30/2019" +description: "Learn more about: task Class (Concurrency Runtime)" +ms.date: 07/30/2019 f1_keywords: ["task", "PPLTASKS/concurrency::task", "PPLTASKS/concurrency::task::task", "PPLTASKS/concurrency::task::get", "PPLTASKS/concurrency::task::is_apartment_aware", "PPLTASKS/concurrency::task::is_done", "PPLTASKS/concurrency::task::scheduler", "PPLTASKS/concurrency::task::then", "PPLTASKS/concurrency::task::wait"] helpviewer_keywords: ["task class"] -ms.assetid: cdc3a8c0-5cbe-45a0-b5d5-e9f81d94df1a --- # task Class (Concurrency Runtime) -The Parallel Patterns Library (PPL) `task` class. A `task` object represents work that can be executed asynchronously and concurrently with other tasks and parallel work produced by parallel algorithms in the Concurrency Runtime. It produces a result of type `_ResultType` on successful completion. Tasks of type `task` produce no result. A task can be waited upon and canceled independently of other tasks. It can also be composed with other tasks using continuations( `then`), and join( `when_all`) and choice( `when_any`) patterns. When a task object is assigned to a new variable, the behavior is that of `std::shared_ptr`; in other words, both objects represent the same underlying task. +The Parallel Patterns Library (PPL) `task` class. A `task` object represents work that can be executed asynchronously and concurrently with other tasks and parallel work produced by parallel algorithms in the Concurrency Runtime. It produces a result of type `_ResultType` on successful completion. Tasks of type `task` produce no result. A task can be waited upon and canceled independently of other tasks. It can also be composed with other tasks using continuations(`then`), and join(`when_all`) and choice(`when_any`) patterns. When a task object is assigned to a new variable, the behavior is that of `std::shared_ptr`; in other words, both objects represent the same underlying task. ## Syntax @@ -91,7 +90,7 @@ The result of the task. If the task is canceled, a call to `get` will throw a [task_canceled](task-canceled-class.md) exception. If the task encountered an different exception or an exception was propagated to it from an antecedent task, a call to `get` will throw that exception. > [!IMPORTANT] -> In a Universal Windows Platform (UWP) app, do not call [concurrency::task::wait](#wait) or `get` ( `wait` calls `get`) in code that runs on the user-interface thread. Otherwise, the runtime throws [concurrency::invalid_operation](invalid-operation-class.md) because these methods block the current thread and can cause the app to become unresponsive. However, you can call the `get` method to receive the result of the antecedent task in a task-based continuation because the result is immediately available. +> In a Universal Windows Platform (UWP) app, do not call [concurrency::task::wait](#wait) or `get` (`wait` calls `get`) in code that runs on the user-interface thread. Otherwise, the runtime throws [concurrency::invalid_operation](invalid-operation-class.md) because these methods block the current thread and can cause the app to become unresponsive. However, you can call the `get` method to receive the result of the antecedent task in a task-based continuation because the result is immediately available. ## is_apartment_aware diff --git a/docs/parallel/concrt/reference/transformer-class.md b/docs/parallel/concrt/reference/transformer-class.md index b5e9aa9241..f5674f3eea 100644 --- a/docs/parallel/concrt/reference/transformer-class.md +++ b/docs/parallel/concrt/reference/transformer-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: transformer Class" title: "transformer Class" +description: "Learn more about: transformer Class" ms.date: "11/04/2016" f1_keywords: ["transformer", "AGENTS/concurrency::transformer", "AGENTS/concurrency::transformer::transformer", "AGENTS/concurrency::transformer::accept_message", "AGENTS/concurrency::transformer::consume_message", "AGENTS/concurrency::transformer::link_target_notification", "AGENTS/concurrency::transformer::propagate_message", "AGENTS/concurrency::transformer::propagate_to_any_targets", "AGENTS/concurrency::transformer::release_message", "AGENTS/concurrency::transformer::reserve_message", "AGENTS/concurrency::transformer::resume_propagation", "AGENTS/concurrency::transformer::send_message", "AGENTS/concurrency::transformer::supports_anonymous_source"] helpviewer_keywords: ["transformer class"] -ms.assetid: eea71925-7043-4a92-bfd4-dbc0ece5d081 --- # transformer Class @@ -13,17 +12,17 @@ A `transformer` messaging block is a single-target, multi-source, ordered `propa ## Syntax ```cpp -template +template class transformer : public propagator_block>, multi_link_registry>>; ``` ### Parameters -*_Input*
+*`_Input`*\ The payload type of the messages accepted by the buffer. -*_Output*
+*`_Output`*\ The payload type of the messages stored and propagated out by the buffer. ## Members @@ -32,27 +31,27 @@ The payload type of the messages stored and propagated out by the buffer. |Name|Description| |----------|-----------------| -|[transformer](#ctor)|Overloaded. Constructs a `transformer` messaging block.| -|[~transformer Destructor](#dtor)|Destroys the `transformer` messaging block.| +|[`transformer`](#ctor)|Overloaded. Constructs a `transformer` messaging block.| +|[`~transformer`](#dtor)|Destroys the `transformer` messaging block.| ### Protected Methods |Name|Description| |----------|-----------------| -|[accept_message](#accept_message)|Accepts a message that was offered by this `transformer` messaging block, transferring ownership to the caller.| -|[consume_message](#consume_message)|Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller.| -|[link_target_notification](#link_target_notification)|A callback that notifies that a new target has been linked to this `transformer` messaging block.| -|[propagate_message](#propagate_message)|Asynchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `propagate` method, when called by a source block.| -|[propagate_to_any_targets](#propagate_to_any_targets)|Executes the transformer function on the input messages.| -|[release_message](#release_message)|Releases a previous message reservation. (Overrides [source_block::release_message](source-block-class.md#release_message).)| -|[reserve_message](#reserve_message)|Reserves a message previously offered by this `transformer` messaging block. (Overrides [source_block::reserve_message](source-block-class.md#reserve_message).)| -|[resume_propagation](#resume_propagation)|Resumes propagation after a reservation has been released. (Overrides [source_block::resume_propagation](source-block-class.md#resume_propagation).)| -|[send_message](#send_message)|Synchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `send` method, when called by a source block.| -|[supports_anonymous_source](#supports_anonymous_source)|Overrides the `supports_anonymous_source` method to indicate that this block can accept messages offered to it by a source that is not linked. (Overrides [ITarget::supports_anonymous_source](itarget-class.md#supports_anonymous_source).)| +|[`accept_message`](#accept_message)|Accepts a message that was offered by this `transformer` messaging block, transferring ownership to the caller.| +|[`consume_message`](#consume_message)|Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller.| +|[`link_target_notification`](#link_target_notification)|A callback that notifies that a new target has been linked to this `transformer` messaging block.| +|[`propagate_message`](#propagate_message)|Asynchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `propagate` method, when called by a source block.| +|[`propagate_to_any_targets`](#propagate_to_any_targets)|Executes the transformer function on the input messages.| +|[`release_message`](#release_message)|Releases a previous message reservation. (Overrides [`source_block::release_message`](source-block-class.md#release_message).)| +|[`reserve_message`](#reserve_message)|Reserves a message previously offered by this `transformer` messaging block. (Overrides [`source_block::reserve_message`](source-block-class.md#reserve_message).)| +|[`resume_propagation`](#resume_propagation)|Resumes propagation after a reservation has been released. (Overrides [`source_block::resume_propagation`](source-block-class.md#resume_propagation).)| +|[`send_message`](#send_message)|Synchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `send` method, when called by a source block.| +|[`supports_anonymous_source`](#supports_anonymous_source)|Overrides the `supports_anonymous_source` method to indicate that this block can accept messages offered to it by a source that is not linked. (Overrides [`ITarget::supports_anonymous_source`](itarget-class.md#supports_anonymous_source).)| ## Remarks -For more information, see [Asynchronous Message Blocks](../../../parallel/concrt/asynchronous-message-blocks.md). +For more information, see [Asynchronous Message Blocks](../asynchronous-message-blocks.md). ## Inheritance Hierarchy @@ -72,7 +71,7 @@ For more information, see [Asynchronous Message Blocks](../../../parallel/concrt **Namespace:** concurrency -## accept_message +## `accept_message` Accepts a message that was offered by this `transformer` messaging block, transferring ownership to the caller. @@ -82,14 +81,14 @@ virtual message<_Output>* accept_message(runtime_object_identity _MsgId); ### Parameters -*_MsgId*
+*`_MsgId`*\ The `runtime_object_identity` of the offered `message` object. ### Return Value A pointer to the `message` object that the caller now has ownership of. -## consume_message +## `consume_message` Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller. @@ -99,7 +98,7 @@ virtual message<_Output>* consume_message(runtime_object_identity _MsgId); ### Parameters -*_MsgId*
+*`_MsgId`*\ The `runtime_object_identity` of the `message` object being consumed. ### Return Value @@ -110,7 +109,7 @@ A pointer to the `message` object that the caller now has ownership of. Similar to `accept`, but is always preceded by a call to `reserve`. -## link_target_notification +## `link_target_notification` A callback that notifies that a new target has been linked to this `transformer` messaging block. @@ -118,7 +117,7 @@ A callback that notifies that a new target has been linked to this `transformer` virtual void link_target_notification(_Inout_ ITarget<_Output> *); ``` -## propagate_message +## `propagate_message` Asynchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `propagate` method, when called by a source block. @@ -130,17 +129,17 @@ virtual message_status propagate_message( ### Parameters -*_PMessage*
+*`_PMessage`*\ A pointer to the `message` object. -*_PSource*
+*`_PSource`*\ A pointer to the source block offering the message. ### Return Value A [message_status](concurrency-namespace-enums.md) indication of what the target decided to do with the message. -## propagate_to_any_targets +## `propagate_to_any_targets` Executes the transformer function on the input messages. @@ -148,7 +147,7 @@ Executes the transformer function on the input messages. virtual void propagate_to_any_targets(_Inout_opt_ message<_Output> *); ``` -## release_message +## `release_message` Releases a previous message reservation. @@ -158,10 +157,10 @@ virtual void release_message(runtime_object_identity _MsgId); ### Parameters -*_MsgId*
+*`_MsgId`*\ The `runtime_object_identity` of the `message` object being released. -## reserve_message +## `reserve_message` Reserves a message previously offered by this `transformer` messaging block. @@ -171,7 +170,7 @@ virtual bool reserve_message(runtime_object_identity _MsgId); ### Parameters -*_MsgId*
+*`_MsgId`*\ The `runtime_object_identity` of the `message` object being reserved. ### Return Value @@ -182,7 +181,7 @@ The `runtime_object_identity` of the `message` object being reserved. After `reserve` is called, if it returns **`true`**, either `consume` or `release` must be called to either take or release ownership of the message. -## resume_propagation +## `resume_propagation` Resumes propagation after a reservation has been released. @@ -190,7 +189,7 @@ Resumes propagation after a reservation has been released. virtual void resume_propagation(); ``` -## send_message +## `send_message` Synchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `send` method, when called by a source block. @@ -202,17 +201,17 @@ virtual message_status send_message( ### Parameters -*_PMessage*
+*`_PMessage`*\ A pointer to the `message` object. -*_PSource*
+*`_PSource`*\ A pointer to the source block offering the message. ### Return Value A [message_status](concurrency-namespace-enums.md) indication of what the target decided to do with the message. -## supports_anonymous_source +## `supports_anonymous_source` Overrides the `supports_anonymous_source` method to indicate that this block can accept messages offered to it by a source that is not linked. @@ -224,7 +223,7 @@ virtual bool supports_anonymous_source(); **`true`** because the block does not postpone offered messages. -## transformer +## `transformer` Constructs a `transformer` messaging block. @@ -263,19 +262,19 @@ transformer( ### Parameters -*_Func*
+*`_Func`*\ A function that will be invoked for each accepted message. -*_PTarget*
+*`_PTarget`*\ A pointer to a target block to link with the transformer. -*_Filter*
+*`_Filter`*\ A filter function which determines whether offered messages should be accepted. -*_PScheduler*
+*`_PScheduler`*\ The `Scheduler` object within which the propagation task for the `transformer` messaging block is scheduled. -*_PScheduleGroup*
+*`_PScheduleGroup`*\ The `ScheduleGroup` object within which the propagation task for the `transformer` messaging block is scheduled. The `Scheduler` object used is implied by the schedule group. ### Remarks @@ -286,7 +285,7 @@ The type `_Transform_method` is a functor with signature `_Output (_Input const The type `filter_method` is a functor with signature `bool (_Input const &)` which is invoked by this `transformer` messaging block to determine whether or not it should accept an offered message. -## ~transformer +## `~transformer` Destroys the `transformer` messaging block. @@ -296,5 +295,5 @@ Destroys the `transformer` messaging block. ## See also -[concurrency Namespace](concurrency-namespace.md)
+[concurrency Namespace](concurrency-namespace.md)\ [call Class](call-class.md) diff --git a/docs/parallel/concrt/task-scheduler-concurrency-runtime.md b/docs/parallel/concrt/task-scheduler-concurrency-runtime.md index 4d42336b9f..d2ebbf48db 100644 --- a/docs/parallel/concrt/task-scheduler-concurrency-runtime.md +++ b/docs/parallel/concrt/task-scheduler-concurrency-runtime.md @@ -7,7 +7,7 @@ ms.assetid: 9aba278c-e0c9-4ede-b7c6-fedf7a365d90 --- # Task Scheduler (Concurrency Runtime) -The topics in this part of the documentation describe the important features of the Concurrency Runtime Task Scheduler. The Task Scheduler is useful when you want fine-tune the performance of your existing code that uses the Concurrency Runtime. +The topics in this part of the documentation describe the important features of the Concurrency Runtime Task Scheduler. The Task Scheduler is useful when you want to fine-tune the performance of your existing code that uses the Concurrency Runtime. > [!IMPORTANT] > The Task Scheduler is not available from a Universal Windows Platform (UWP) app. For more information, see [Creating Asynchronous Operations in C++ for UWP Apps](../../parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md). diff --git a/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md b/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md index 480505f81e..1ff8dab877 100644 --- a/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md +++ b/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md @@ -29,7 +29,7 @@ UWP support is optional in Visual Studio 2017 and later. To install it, open the When you use the `IXMLHTTPRequest2` interface to create web requests over HTTP, you implement the `IXMLHTTPRequest2Callback` interface to receive the server response and react to other events. This example defines the `HttpRequest` class to create web requests, and the `HttpRequestBuffersCallback` and `HttpRequestStringCallback` classes to process responses. The `HttpRequestBuffersCallback` and `HttpRequestStringCallback` classes support the `HttpRequest` class; you work only with the `HttpRequest` class from application code. -The `GetAsync`, `PostAsync` methods of the `HttpRequest` class enable you to start HTTP GET and POST operations, respectively. These methods use the `HttpRequestStringCallback` class to read the server response as a string. The `SendAsync` and `ReadAsync` methods enable you to stream large content in chunks. These methods each return [concurrency::task](../../parallel/concrt/reference/task-class.md) to represent the operation. The `GetAsync` and `PostAsync` methods produce `task` value, where the `wstring` part represents the server’s response. The `SendAsync` and `ReadAsync` methods produce `task` values; these tasks complete when the send and read operations complete. +The `GetAsync`, `PostAsync` methods of the `HttpRequest` class enable you to start HTTP GET and POST operations, respectively. These methods use the `HttpRequestStringCallback` class to read the server response as a string. The `SendAsync` and `ReadAsync` methods enable you to stream large content in chunks. These methods each return [concurrency::task](../../parallel/concrt/reference/task-class.md) to represent the operation. The `GetAsync` and `PostAsync` methods produce `task` value, where the `wstring` part represents the server's response. The `SendAsync` and `ReadAsync` methods produce `task` values; these tasks complete when the send and read operations complete. Because the `IXMLHTTPRequest2` interfaces act asynchronously, this example uses [concurrency::task_completion_event](../../parallel/concrt/reference/task-completion-event-class.md) to create a task that completes after the callback object completes or cancels the download operation. The `HttpRequest` class creates a task-based continuation from this task to set the final result. The `HttpRequest` class uses a task-based continuation to ensure that the continuation task runs even if the previous task produces an error or is canceled. For more information about task-based continuations, see [Task Parallelism](../../parallel/concrt/task-parallelism-concurrency-runtime.md) diff --git a/docs/parallel/multithreading-and-locales.md b/docs/parallel/multithreading-and-locales.md index 9c370107b0..8df3ba928e 100644 --- a/docs/parallel/multithreading-and-locales.md +++ b/docs/parallel/multithreading-and-locales.md @@ -13,20 +13,20 @@ Both the C Runtime Library and the C++ Standard Library provide support for chan With the C Runtime Library, you can create multithreaded applications using the `_beginthread` and `_beginthreadex` functions. This topic only covers multithreaded applications created using these functions. For more information, see [_beginthread, _beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md). -To change the locale using the C Runtime Library, use the [setlocale](../preprocessor/setlocale.md) function. In previous versions of Visual C++, this function would always modify the locale throughout the entire application. There is now support for setting the locale on a per-thread basis. This is done using the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function. To specify that [setlocale](../preprocessor/setlocale.md) should only change the locale in the current thread, call `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)` in that thread. Conversely, calling `_configthreadlocale(_DISABLE_PER_THREAD_LOCALE)` will cause that thread to use the global locale, and any call to [setlocale](../preprocessor/setlocale.md) in that thread will change the locale in all threads that have not explicitly enabled per-thread locale. +To change the locale using the C Runtime Library, use the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function. In previous versions of Visual C++, this function would always modify the locale throughout the entire application. There is now support for setting the locale on a per-thread basis. This is done using the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function. To specify that [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) should only change the locale in the current thread, call `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)` in that thread. Conversely, calling `_configthreadlocale(_DISABLE_PER_THREAD_LOCALE)` will cause that thread to use the global locale, and any call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) in that thread will change the locale in all threads that have not explicitly enabled per-thread locale. To change the locale using the C++ Runtime Library, use the [locale Class](../standard-library/locale-class.md). By calling the [locale::global](../standard-library/locale-class.md#global) method, you change the locale in every thread that has not explicitly enabled per-thread locale. To change the locale in a single thread or portion of an application, simply create an instance of a `locale` object in that thread or portion of code. > [!NOTE] -> Calling [locale::global](../standard-library/locale-class.md#global) changes the locale for both the C++ Standard Library and the C Runtime Library. However, calling [setlocale](../preprocessor/setlocale.md) only changes the locale for the C Runtime Library; the C++ Standard Library is not affected. +> Calling [locale::global](../standard-library/locale-class.md#global) changes the locale for both the C++ Standard Library and the C Runtime Library. However, calling [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) only changes the locale for the C Runtime Library; the C++ Standard Library is not affected. -The following examples show how to use the [setlocale](../preprocessor/setlocale.md) function, the [locale Class](../standard-library/locale-class.md), and the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function to change the locale of an application in several different scenarios. +The following examples show how to use the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function, the [locale Class](../standard-library/locale-class.md), and the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function to change the locale of an application in several different scenarios. ## Example: Change locale with per-thread locale enabled -In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread A then proceeds to change the locale using the [setlocale](../preprocessor/setlocale.md) function of the C Runtime Library. +In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread A then proceeds to change the locale using the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function of the C Runtime Library. -Since Thread A has per-thread locale enabled, only the C Runtime Library functions in Thread A start using the "french" locale. The C Runtime Library functions in Thread B and in the main thread continue to use the "C" locale. Also, since [setlocale](../preprocessor/setlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. +Since Thread A has per-thread locale enabled, only the C Runtime Library functions in Thread A start using the "french" locale. The C Runtime Library functions in Thread B and in the main thread continue to use the "C" locale. Also, since [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. ```cpp // multithread_locale_1.cpp @@ -222,9 +222,9 @@ unsigned __stdcall RunThreadB(void *params) ## Example: Change locale without per-thread locale enabled -In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread B then proceeds to change the locale using the [setlocale](../preprocessor/setlocale.md) function of the C Runtime Library. +In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread B then proceeds to change the locale using the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function of the C Runtime Library. -Since Thread B does not have per-thread locale enabled, the C Runtime Library functions in Thread B and in the main thread start using the "french" locale. The C Runtime Library functions in Thread A continue to use the "C" locale because Thread A has per-thread locale enabled. Also, since [setlocale](../preprocessor/setlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. +Since Thread B does not have per-thread locale enabled, the C Runtime Library functions in Thread B and in the main thread start using the "french" locale. The C Runtime Library functions in Thread A continue to use the "C" locale because Thread A has per-thread locale enabled. Also, since [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. ```cpp // multithread_locale_3.cpp @@ -431,7 +431,7 @@ unsigned __stdcall RunThreadB(void *params) [Multithreading Support for Older Code (Visual C++)](multithreading-support-for-older-code-visual-cpp.md)
[_beginthread, _beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md)
[_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md)
-[setlocale](../preprocessor/setlocale.md)
+[setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
[Internationalization](../c-runtime-library/internationalization.md)
[Locale](../c-runtime-library/locale.md)
[\](../standard-library/clocale.md)
diff --git a/docs/parallel/openmp/2-directives.md b/docs/parallel/openmp/2-directives.md index b949f5b496..6ff80f4fbb 100644 --- a/docs/parallel/openmp/2-directives.md +++ b/docs/parallel/openmp/2-directives.md @@ -798,7 +798,6 @@ The restrictions to the `reduction` clause are as follows: The `copyin` clause provides a mechanism to assign the same value to `threadprivate` variables for each thread in the team executing the parallel region. For each variable specified in a `copyin` clause, the value of the variable in the master thread of the team is copied, as if by assignment, to the thread-private copies at the beginning of the parallel region. The syntax of the `copyin` clause is as follows: ```cpp - copyin( variable-list ) @@ -817,7 +816,6 @@ The `copyprivate` clause provides a mechanism to use a private variable to broad The syntax of the `copyprivate` clause is as follows: ```cpp - copyprivate( variable-list ) diff --git a/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md b/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md index 6221091b69..3e5249b640 100644 --- a/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md +++ b/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md @@ -1,15 +1,13 @@ --- -description: "Learn more about: C. OpenMP C and C++ grammar" title: "C. OpenMP C and C++ grammar" -ms.date: "01/16/2019" -ms.assetid: 97a878ce-1533-47f7-a134-66fcbff48524 +description: "Learn more about: C. OpenMP C and C++ grammar" +ms.date: 01/16/2019 --- # C. OpenMP C and C++ grammar -[C.1 Notation](#c1-notation)
-[C.2 Rules](#c2-rules) +Learn about the grammar rules and syntax extensions in C and C++ for OpenMP, a parallel programming framework. -## C.1 Notation +## C.1 notation The grammar rules consist of the name for a non-terminal, followed by a colon, followed by replacement alternatives on separate lines. @@ -18,214 +16,214 @@ The syntactic expression termopt indicates that the term is optional The syntactic expression *term*optseq is equivalent to *term-seq*opt with the following additional rules: *term-seq*: -    *term*
-    *term-seq* *term*
-    *term-seq* `,` *term* + *term*\ + *term-seq* *term*\ + *term-seq* `,` *term* -## C.2 Rules +## C.2 rules The notation is described in section 6.1 of the C standard. This grammar appendix shows the extensions to the base language grammar for the OpenMP C and C++ directives. **/\* in C++ (ISO/IEC 14882:1998) \*/** -*statement-seq*:
-    *statement*
-    *openmp-directive*
-    *statement-seq statement*
-    *statement-seq openmp-directive* +*statement-seq*:\ + *statement*\ + *openmp-directive*\ + *statement-seq statement*\ + *statement-seq openmp-directive* **/\* in C90 (ISO/IEC 9899:1990) \*/** -*statement-list*:
-    *statement*
-    *openmp-directive*
-    *statement-list statement*
-    *statement-list openmp-directive* +*statement-list*:\ + *statement*\ + *openmp-directive*\ + *statement-list statement*\ + *statement-list openmp-directive* **/\* in C99 (ISO/IEC 9899:1999) \*/** -*block-item*:
-    *declaration*
-    *statement*
-    *openmp-directive* +*block-item*:\ + *declaration*\ + *statement*\ + *openmp-directive* **/\* standard statements \*/** -*statement*:
-    *openmp-construct* +*statement*:\ + *openmp-construct* -*openmp-construct*:
-    *parallel-construct*
-    *for-construct*
-    *sections-construct*
-    *single-construct*
-    *parallel-for-construct*
-    *parallel-sections-construct*
-    *master-construct*
-    *critical-construct*
-    *atomic-construct*
-    *ordered-construct* +*openmp-construct*:\ + *parallel-construct*\ + *for-construct*\ + *sections-construct*\ + *single-construct*\ + *parallel-for-construct*\ + *parallel-sections-construct*\ + *master-construct*\ + *critical-construct*\ + *atomic-construct*\ + *ordered-construct* -*openmp-directive*:
-    *barrier-directive*
-    *flush-directive* +*openmp-directive*:\ + *barrier-directive*\ + *flush-directive* -*structured-block*:
-    *statement* +*structured-block*:\ + *statement* -*parallel-construct*:
-    *parallel-directive structured-block* +*parallel-construct*:\ + *parallel-directive structured-block* -*parallel-directive*:
-     `# pragma omp parallel` *parallel-clause*optseq *new-line* +*parallel-directive*:\ +  `# pragma omp parallel` *parallel-clause*optseq *new-line* -*parallel-clause*:
-    *unique-parallel-clause*
-    *data-clause* +*parallel-clause*:\ + *unique-parallel-clause*\ + *data-clause* -*unique-parallel-clause*:
-     `if (` *expression* `)`
-     `num_threads (` *expression* `)` +*unique-parallel-clause*:\ +  `if (` *expression* `)`\ +  `num_threads (` *expression* `)` -*for-construct*:
-    *for-directive iteration-statement* +*for-construct*:\ + *for-directive iteration-statement* -*for-directive*:
-     `# pragma omp for` *for-clause*optseq *new-line* +*for-directive*:\ +  `# pragma omp for` *for-clause*optseq *new-line* -*for-clause*:
-    *unique-for-clause*
-    *data-clause*
-     `nowait` +*for-clause*:\ + *unique-for-clause*\ + *data-clause*\ +  `nowait` -*unique-for-clause*:
-     `ordered`
-     `schedule (` *schedule-kind* `)`
-     `schedule (` *schedule-kind* `,` *expression* `)` +*unique-for-clause*:\ +  `ordered`\ +  `schedule (` *schedule-kind* `)`\ +  `schedule (` *schedule-kind* `,` *expression* `)` -*schedule-kind*:
-     `static`
-     `dynamic`
-     `guided`
-     `runtime` +*schedule-kind*:\ +  `static`\ +  `dynamic`\ +  `guided`\ +  `runtime` -*sections-construct*:
-    *sections-directive section-scope* +*sections-construct*:\ + *sections-directive section-scope* -*sections-directive*:
-     `# pragma omp sections` *sections-clause*optseq *new-line* +*sections-directive*:\ +  `# pragma omp sections` *sections-clause*optseq *new-line* -*sections-clause*:
-    *data-clause*
-     `nowait` +*sections-clause*:\ + *data-clause*\ +  `nowait` -*section-scope*:
-    *{ section-sequence }* +*section-scope*:\ + *{ section-sequence }* -*section-sequence*:
-    *section-directive*opt *structured-block*
-    *section-sequence section-directive structured-block* +*section-sequence*:\ + *section-directive*opt *structured-block*\ + *section-sequence section-directive structured-block* -*section-directive*:
-     `# pragma omp section` *new-line* +*section-directive*:\ +  `# pragma omp section` *new-line* -*single-construct*:
-    *single-directive structured-block* +*single-construct*:\ + *single-directive structured-block* -*single-directive*:
-     `# pragma omp single` *single-clause*optseq *new-line* +*single-directive*:\ +  `# pragma omp single` *single-clause*optseq *new-line* -*single-clause*:
-    *data-clause*
-     `nowait` +*single-clause*:\ + *data-clause*\ +  `nowait` -*parallel-for-construct*:
-    *parallel-for-directive iteration-statement* +*parallel-for-construct*:\ + *parallel-for-directive iteration-statement* -*parallel-for-directive*:
-     `# pragma omp parallel for` *parallel-for-clause*optseq *new-line* +*parallel-for-directive*:\ +  `# pragma omp parallel for` *parallel-for-clause*optseq *new-line* -*parallel-for-clause*:
-    *unique-parallel-clause*
-    *unique-for-clause*
-    *data-clause* +*parallel-for-clause*:\ + *unique-parallel-clause*\ + *unique-for-clause*\ + *data-clause* -*parallel-sections-construct*:
-    *parallel-sections-directive section-scope* +*parallel-sections-construct*:\ + *parallel-sections-directive section-scope* -*parallel-sections-directive*:
-     `# pragma omp parallel sections` *parallel-sections-clause*optseq *new-line* +*parallel-sections-directive*:\ +  `# pragma omp parallel sections` *parallel-sections-clause*optseq *new-line* -*parallel-sections-clause*:
-    *unique-parallel-clause*
-    *data-clause* +*parallel-sections-clause*:\ + *unique-parallel-clause*\ + *data-clause* -*master-construct*:
-    *master-directive structured-block* +*master-construct*:\ + *master-directive structured-block* -*master-directive*:
-     `# pragma omp master` *new-line* +*master-directive*:\ +  `# pragma omp master` *new-line* -*critical-construct*:
-    *critical-directive structured-block* +*critical-construct*:\ + *critical-directive structured-block* -*critical-directive*:
-     `# pragma omp critical` *region-phrase*opt *new-line* +*critical-directive*:\ +  `# pragma omp critical` *region-phrase*opt *new-line* -*region-phrase*:
-    *(identifier)* +*region-phrase*:\ + *(identifier)* -*barrier-directive*:
-     `# pragma omp barrier` *new-line* +*barrier-directive*:\ +  `# pragma omp barrier` *new-line* -*atomic-construct*:
-    *atomic-directive expression-statement* +*atomic-construct*:\ + *atomic-directive expression-statement* -*atomic-directive*:
-     `# pragma omp atomic` *new-line* +*atomic-directive*:\ +  `# pragma omp atomic` *new-line* -*flush-directive*:
-     `# pragma omp flush` *flush-vars*opt *new-line* +*flush-directive*:\ +  `# pragma omp flush` *flush-vars*opt *new-line* -*flush-vars*:
-    *(variable-list)* +*flush-vars*:\ + *(variable-list)* -*ordered-construct*:
-    *ordered-directive structured-block* +*ordered-construct*:\ + *ordered-directive structured-block* -*ordered-directive*:
-     `# pragma omp ordered` *new-line* +*ordered-directive*:\ +  `# pragma omp ordered` *new-line* **/\* standard declarations \*/** -*declaration*:
-    *threadprivate-directive* +*declaration*:\ + *threadprivate-directive* -*threadprivate-directive*:
-     `# pragma omp threadprivate (` *variable-list* `)` *new-line* +*threadprivate-directive*:\ +  `# pragma omp threadprivate (` *variable-list* `)` *new-line* -*data-clause*:
-     `private (` *variable-list* `)`
-     `copyprivate (` *variable-list* `)`
-     `firstprivate (` *variable-list* `)`
-     `lastprivate (` *variable-list* `)`
-     `shared (` *variable-list* `)`
-     `default ( shared )`
-     `default ( none )`
-     `reduction (` *reduction-operator* `:` *variable-list* `)`
-     `copyin (` *variable-list* `)` +*data-clause*:\ +  `private (` *variable-list* `)`\ +  `copyprivate (` *variable-list* `)`\ +  `firstprivate (` *variable-list* `)`\ +  `lastprivate (` *variable-list* `)`\ +  `shared (` *variable-list* `)`\ +  `default ( shared )`\ +  `default ( none )`\ +  `reduction (` *reduction-operator* `:` *variable-list* `)`\ +  `copyin (` *variable-list* `)` -*reduction-operator*:
-    One of: `+ \* - & ^ | && ||` +*reduction-operator*:\ + One of: `+ \* - & ^ | && ||` **/\* in C \*/** -*variable-list*:
-    *identifier*
-    *variable-list* `,` *identifier* +*variable-list*:\ + *identifier*\ + *variable-list* `,` *identifier* **/\* in C++ \*/** -*variable-list*:
-    *id-expression*
-    *variable-list* `,` *id-expression* +*variable-list*:\ + *id-expression*\ + *variable-list* `,` *id-expression* diff --git a/docs/parallel/openmp/openmp-simd.md b/docs/parallel/openmp/openmp-simd.md index 23675f53b6..e263b9427e 100644 --- a/docs/parallel/openmp/openmp-simd.md +++ b/docs/parallel/openmp/openmp-simd.md @@ -17,7 +17,7 @@ For more information, see [SIMD Extension to C++ OpenMP in Visual Studio](https: ## OpenMP SIMD in Visual C++ -OpenMP SIMD, introduced in the OpenMP 4.0 standard, targets making vector-friendly loops. By using the `simd` directive before a loop, the compiler can ignore vector dependencies, make the loop as vector-friendly as possible, and respect the users’ intention to have multiple loop iterations executed simultaneously. +OpenMP SIMD, introduced in the OpenMP 4.0 standard, targets making vector-friendly loops. By using the `simd` directive before a loop, the compiler can ignore vector dependencies, make the loop as vector-friendly as possible, and respect the users' intention to have multiple loop iterations executed simultaneously. ```c #pragma omp simd diff --git a/docs/parallel/openmp/reference/openmp-clauses.md b/docs/parallel/openmp/reference/openmp-clauses.md index 4e819f98c9..3fdbd0f6a7 100644 --- a/docs/parallel/openmp/reference/openmp-clauses.md +++ b/docs/parallel/openmp/reference/openmp-clauses.md @@ -32,12 +32,12 @@ For data-sharing attributes: |[shared](#shared-openmp)|Specifies that one or more variables should be shared among all threads.| |[default](#default-openmp)|Specifies the behavior of unscoped variables in a parallel region.| |[reduction](#reduction)|Specifies that one or more variables that are private to each thread are the subject of a reduction operation at the end of the parallel region.| -|[copyin](#copyin)|Allows threads to access the master thread's value, for a [threadprivate](openmp-directives.md#threadprivate) variable.| +|[copyin](#copyin)|Allows threads to access the main thread's value, for a [threadprivate](openmp-directives.md#threadprivate) variable.| |[copyprivate](#copyprivate)|Specifies that one or more variables should be shared among all threads.| ## copyin -Allows threads to access the master thread's value, for a [threadprivate](openmp-directives.md#threadprivate) variable. +Allows threads to access the main thread's value, for a [threadprivate](openmp-directives.md#threadprivate) variable. ```cpp copyin(var) @@ -46,7 +46,7 @@ copyin(var) ### Parameters *var*
-The `threadprivate` variable that will be initialized with the variable's value in the master thread, as it exists before the parallel construct. +The `threadprivate` variable that will be initialized with the variable's value in the main thread, as it exists before the parallel construct. ### Remarks @@ -513,7 +513,7 @@ int main() { printf_s("These are the variables after exit from " "the parallel region.\n"); printf_s("nThreadPrivate = %d (The last value in the " - "master thread)\n", nThreadPrivate); + "main thread)\n", nThreadPrivate); printf_s(" nPrivate = %d (The value prior to " "entering parallel region)\n", nPrivate); printf_s(" nFirstPrivate = %d (The value prior to " @@ -591,7 +591,7 @@ nFirstPrivate = 3 nShared = 3 These are the variables after exit from the parallel region. -nThreadPrivate = 0 (The last value in the master thread) +nThreadPrivate = 0 (The last value in the main thread) nPrivate = 4 (The value prior to entering parallel region) nFirstPrivate = 4 (The value prior to entering parallel region) nLastPrivate = 3 (The value from the last iteration of the loop) diff --git a/docs/parallel/openmp/reference/openmp-directives.md b/docs/parallel/openmp/reference/openmp-directives.md index 859e008ea3..2e841d2138 100644 --- a/docs/parallel/openmp/reference/openmp-directives.md +++ b/docs/parallel/openmp/reference/openmp-directives.md @@ -19,13 +19,13 @@ For parallel work-sharing: |[parallel](#parallel)|Defines a parallel region, which is code that will be executed by multiple threads in parallel.| |[for](#for-openmp)|Causes the work done in a `for` loop inside a parallel region to be divided among threads.| |[sections](#sections-openmp)|Identifies code sections to be divided among all threads.| -|[single](#single)|Lets you specify that a section of code should be executed on a single thread, not necessarily the master thread.| +|[single](#single)|Lets you specify that a section of code should be executed on a single thread, not necessarily the main thread.| -For master and synchronization: +For main thread and synchronization: |Directive|Description| |---------|-----------| -|[master](#master)|Specifies that only the master thread should execute a section of the program.| +|[master](#master)|Specifies that only the main thread should execute a section of the program.| |[critical](#critical)|Specifies that code is only executed on one thread at a time.| |[barrier](#barrier)|Synchronizes all threads in a team; all threads pause at the barrier, until all threads execute the barrier.| |[atomic](#atomic)|Specifies that a memory location that will be updated atomically.| @@ -356,7 +356,7 @@ The sum of 1 through 10 is 55 ## master -Specifies that only the master thread should execute a section of the program. +Specifies that only the main thread should execute a section of the program. ```cpp #pragma omp master @@ -369,14 +369,13 @@ Specifies that only the master thread should execute a section of the program. The `master` directive supports no clauses. -The [single](#single) directive lets you specify that a section of code should be executed on a single thread, not necessarily the master thread. - For more information, see [2.6.1 master construct](../2-directives.md#261-master-construct). +To specify that a section of code should be executed on a single thread, not necessarily the main thread, use the [single](#single) directive instead. + ### Example ```cpp -// omp_master.cpp // compile with: /openmp #include #include @@ -606,7 +605,7 @@ Hello from thread 0 ## single -Lets you specify that a section of code should be executed on a single thread, not necessarily the master thread. +Lets you specify that a section of code should be executed on a single thread, not necessarily the main thread. ```cpp #pragma omp single [clauses] @@ -629,10 +628,10 @@ The `single` directive supports the following clauses: - [copyprivate](openmp-clauses.md#copyprivate) - [nowait](openmp-clauses.md#nowait) -The [master](#master) directive lets you specify that a section of code should be executed only on the master thread. - For more information, see [2.4.3 single construct](../2-directives.md#243-single-construct). +To specify that a section of code should only be executed on the main thread, use the [master](#master) directive instead. + ### Example ```cpp diff --git a/docs/parallel/openmp/reference/openmp-environment-variables.md b/docs/parallel/openmp/reference/openmp-environment-variables.md index ca39f87f85..087091f4d3 100644 --- a/docs/parallel/openmp/reference/openmp-environment-variables.md +++ b/docs/parallel/openmp/reference/openmp-environment-variables.md @@ -61,7 +61,7 @@ set OMP_NESTED[=TRUE | =FALSE] The `OMP_NESTED` environment variable can be overridden by the [omp_set_nested](openmp-functions.md#omp-set-nested) function. -The default value in the Visual C++ implementation of the OpenMP standard is `OMP_DYNAMIC=FALSE`. +The default value in the Visual C++ implementation of the OpenMP standard is `OMP_NESTED=FALSE`. For more information, see [4.4 OMP_NESTED](../4-environment-variables.md#44-omp_nested). diff --git a/docs/parallel/sample-multithread-c-program.md b/docs/parallel/sample-multithread-c-program.md index ae54ff2267..f76e104bd1 100644 --- a/docs/parallel/sample-multithread-c-program.md +++ b/docs/parallel/sample-multithread-c-program.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Sample Multithread C Program" title: "Sample Multithread C Program" -ms.date: "08/09/2019" -ms.assetid: 4706f6cd-ff9c-4dbf-99a2-1c999b568f17 +ms.date: 04/07/2022 --- # Sample Multithread C Program @@ -45,11 +44,14 @@ Programs are compiled as multithreaded by default. 1. On the **Build** menu, build the project by choosing the **Build Solution** command. 1. Press **F5** to start the program in the debugger. +1. Press **a** to create a new thread. Each thread bounces a character of a different color around the screen. +1. Press **q** to quit. ::: moniker-end ### To compile and link the multithread program Bounce.c from the command line +1. Open a Visual Studio tools command prompt. This ensures the path is set to include the compiler. 1. Compile and link the program: ```cmd @@ -86,7 +88,7 @@ To build on the command line, copy and save this sample in a source file with a int main(void); // Thread 1: main void KbdFunc(void); // Keyboard input, thread dispatch -void BounceProc(void* MyID); // Threads 2 to n: display +void BounceProc(void* pMyID); // Threads 2 to n: display void ClearScreen(void); // Screen clear void ShutDown(void); // Program shutdown void WriteTitle(int ThreadNum); // Display title bar information @@ -94,12 +96,14 @@ void WriteTitle(int ThreadNum); // Display title bar information HANDLE hConsoleOut; // Handle to the console HANDLE hRunMutex; // "Keep Running" mutex HANDLE hScreenMutex; // "Screen update" mutex -int ThreadNr; // Number of threads started +int ThreadNr = 0; // Number of threads started CONSOLE_SCREEN_BUFFER_INFO csbiInfo; // Console information COORD consoleSize; -BOOL bTrails; +BOOL bTrails = FALSE; -int main() // Thread One +HANDLE hThreads[MAX_THREADS] = { NULL }; // Handles for created threads + +int main(void) // Thread One { // Get display screen information & clear the screen. hConsoleOut = GetStdHandle(STD_OUTPUT_HANDLE); @@ -112,8 +116,6 @@ int main() // Thread One // Create the mutexes and reset thread count. hScreenMutex = CreateMutexW(NULL, FALSE, NULL); // Cleared hRunMutex = CreateMutexW(NULL, TRUE, NULL); // Set - ThreadNr = 0; - bTrails = FALSE; // Start waiting for keyboard input to dispatch threads or exit. KbdFunc(); @@ -126,11 +128,13 @@ int main() // Thread One void ShutDown(void) // Shut down threads { + // Tell all threads to die + ReleaseMutex(hRunMutex); + while (ThreadNr > 0) { - // Tell thread to die and record its death. - ReleaseMutex(hRunMutex); - ThreadNr--; + // Wait for each thread to complete + WaitForSingleObject(hThreads[--ThreadNr], INFINITE); } // Clean up display when done @@ -148,10 +152,12 @@ void KbdFunc(void) // Dispatch and count threads. if (tolower(KeyInfo) == 'a' && ThreadNr < MAX_THREADS) { - ThreadNr++; - _beginthread(BounceProc, 0, &ThreadNr); + ++ThreadNr; + hThreads[ThreadNr] = + (HANDLE)_beginthread(BounceProc, 0, (void*)(uintptr_t)ThreadNr); WriteTitle(ThreadNr); } + if (tolower(KeyInfo) == 't') { bTrails = !bTrails; @@ -169,11 +175,11 @@ void BounceProc(void* pMyID) COORD Coords, Delta; COORD Old = { 0,0 }; DWORD Dummy; - char* MyID = (char*)pMyID; + int MyID = (int)(uintptr_t)pMyID; // Generate update increments and initial // display coordinates. - srand((unsigned int)* MyID * 3); + srand(MyID * 3); Coords.X = getrandom(0, consoleSize.X - 1); Coords.Y = getrandom(0, consoleSize.Y - 1); @@ -182,11 +188,11 @@ void BounceProc(void* pMyID) // Set up character & generate color // attribute from thread number. - if (*MyID > 16) - MyCell = 0x60 + *MyID - 16; // lower case + if (MyID > 16) + MyCell = (wchar_t)(0x60 + MyID - 16); // lower case else - MyCell = 0x40 + *MyID; // upper case - MyAttrib = *MyID & 0x0f; // force black background + MyCell = (wchar_t)(0x40 + MyID); // upper case + MyAttrib = MyID & 0x0f; // force black background do { diff --git a/docs/parallel/toc.yml b/docs/parallel/toc.yml index 98a9fd0393..d8a0ae9283 100644 --- a/docs/parallel/toc.yml +++ b/docs/parallel/toc.yml @@ -167,7 +167,7 @@ items: href: ../parallel/amp/reference/concurrency-precise-math-namespace.md - name: "Concurrency::precise_math namespace functions" href: ../parallel/amp/reference/concurrency-precise-math-namespace-functions.md -- name: Concurrency Runtime (ConCRT) +- name: Concurrency Runtime (ConcRT) expanded: false items: - name: Concurrency Runtime diff --git a/docs/porting/binary-compat-2015-2017.md b/docs/porting/binary-compat-2015-2017.md index 636e0f31f9..86ad895775 100644 --- a/docs/porting/binary-compat-2015-2017.md +++ b/docs/porting/binary-compat-2015-2017.md @@ -1,7 +1,7 @@ --- title: "C++ binary compatibility 2015-2022" description: "Describes how binary compatibility works between compiled C++ files in Visual Studio 2015, 2017, 2019, and 2022. One Microsoft Visual C++ Redistributable package works for all three versions." -ms.date: 10/22/2021 +ms.date: 03/07/2024 helpviewer_keywords: ["binary compatibility, Visual C++"] --- # C++ binary compatibility between Visual Studio versions @@ -14,10 +14,11 @@ We've changed this behavior in Visual Studio 2015 and later versions. The runtim There are three important restrictions on binary compatibility between the v140, v141, v142, and v143 toolsets and minor numbered version updates: -- You can mix binaries built by different versions of the v140, v141, v142, and v143 toolsets. However, you must link by using a toolset at least as recent as the most recent binary in your app. Here's an example: you can link an app compiled using any 2017 toolset (v141, versions 15.0 through 15.9) to a static library compiled using, say, Visual Studio 2019 version 16.2 (v142). You just have to link them by using a version 16.2 or later toolset. You can link a version 16.2 library to a version 16.4 app as long as you use a 16.4 or later toolset. - +- Binaries created with different versions of the v140, v141, v142, and v143 toolsets can be combined. The key rule is that the linker should only work with inputs built by a toolset that is the same version (or earlier) as itself. This applies to apps, import libraries, static libraries, and other files as described in [LINK input files](../build/reference/link-input-files.md). In some cases, an import library for an [implicitly linked](../build/linking-an-executable-to-a-dll.md#implicit-linking) DLL built by a later version of the toolset can be linked using an earlier version of the toolset--especially if the import library strictly uses `extern "C"` for the imports/exports. Here are some examples of what this all means: + - An app compiled with a 2017 toolset (v141, versions 15.0 to 15.9) can be linked to a static library compiled with Visual Studio 2022 version 17.8 (v143), but the linking must be done using a version 17.8 or later toolset. + - Apps and libraries built using VS 2015, 2017, 2019, or 2022 can be linked together, but the linking must be done using a version of the toolset that is as recent as, or more recent than, the most recent toolset used to build any of the binaries you pass to the linker. For example, given three binaries built with toolsets from VS 2015 version 14.3, VS 2017 version 15.9, and VS 2019 version 16.11, you can link them using any toolset version that is 16.11 or later. + - If a DLL is built with a newer toolset, the import library can sometimes be used with older toolsets if all of the exports follow the C language calling convention (`extern "C"`). However, the only officially supported case is consuming a newer windows SDK with an older toolset. - The Redistributable your app uses has a similar binary-compatibility restriction. When you mix binaries built by different supported versions of the toolset, the Redistributable version must be at least as new as the latest toolset used by any app component. - - Static libraries or object files compiled using the [`/GL` (Whole program optimization)](../build/reference/gl-whole-program-optimization.md) compiler switch or linked using [`/LTCG` (Link-time code generation)](../build/reference/ltcg-link-time-code-generation.md) *aren't* binary-compatible across versions, including minor version updates. All object files and libraries compiled using **`/GL`** and **`/LTCG`** must use exactly the same toolset for the compile and the final link. For example, code built by using **`/GL`** in the Visual Studio 2019 version 16.7 toolset can't be linked to code built by using **`/GL`** in the Visual Studio 2019 version 16.8 toolset. The compiler emits [Fatal error C1047](../error-messages/compiler-errors-1/fatal-error-c1047.md). ## Upgrade the Microsoft Visual C++ Redistributable from Visual Studio 2015 and later @@ -38,4 +39,6 @@ This error is by design. We recommend you keep the newest version installed. Mak ## See also [Visual C++ change history](../porting/visual-cpp-change-history-2003-2015.md)\ -[The latest supported Visual C++ Redistributable downloads](../windows/latest-supported-vc-redist.md) +[The latest supported Visual C++ Redistributable downloads](../windows/latest-supported-vc-redist.md)\ +[How to audit Visual C++ Runtime version usage](../windows/redist-version-auditing.md)\ +[Lifecycle FAQ - Visual C++ Redistributable and runtime libraries](/lifecycle/faq/visual-c-faq) diff --git a/docs/porting/build-system-changes.md b/docs/porting/build-system-changes.md index 257ad65325..bcd58b4a3d 100644 --- a/docs/porting/build-system-changes.md +++ b/docs/porting/build-system-changes.md @@ -1,6 +1,6 @@ --- title: "VCBuild vs. MSBuild" -description: "The VIsual Studio C++ build system changed from VCBuild to MSBuild in Visual Studio 2010." +description: "The Visual Studio C++ build system changed from VCBuild to MSBuild in Visual Studio 2010." ms.date: "10/25/2019" helpviewer_keywords: ["Build system changes, project file (.vcxprog)", "Build system changes, custom build rules", "Build system changes, MSBuild", "MSBuild, build system changes", "Build system changes, .vsprops", "Build system changes, $(Inherit)", "Build system changes, $(NoInherit)"] ms.assetid: e564d95f-a6cc-4d97-b57e-1a71daf66f4a diff --git a/docs/porting/features-deprecated-in-visual-studio.md b/docs/porting/features-deprecated-in-visual-studio.md index b7329bdf9a..71383dbc03 100644 --- a/docs/porting/features-deprecated-in-visual-studio.md +++ b/docs/porting/features-deprecated-in-visual-studio.md @@ -1,11 +1,21 @@ --- -description: "Learn more about: C++ features deprecated in Visual Studio 2019" -title: "C++ features deprecated in Visual Studio 2019" -ms.date: "07/30/2019" -helpviewer_keywords: ["Features deprecated in Visual Studio 2019"] +description: "Learn more about: C++ features deprecated in Visual Studio" +title: "C++ features deprecated in Visual Studio" +ms.date: 04/07/2022 +helpviewer_keywords: ["Features deprecated in Visual Studio"] --- -# C++ features deprecated in Visual Studio 2019 +# C++ features deprecated in Visual Studio + +This article is a non-exhaustive list of C++ features deprecated in Visual Studio 2019 and 2022. For information on breaking changes and conformance improvements for C++ in the latest version of Visual Studio, see [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md). + +## Deprecated in Visual Studio 2019 - Support for Windows XP development - Visual Studio 2019 and later does not include support for creating code for Windows XP by using the v142 toolset. Support for Windows XP development by using the v141 toolset that shipped in Visual Studio 2017 is available as an optional component in the Visual Studio Installer. For information on how to install the v141 Windows XP platform toolset, see [Configuring programs for Windows XP](../build/configuring-programs-for-windows-xp.md). + Visual Studio 2019 and later versions don't include current toolset support for creating code for Windows XP. Support for Windows XP development by using the v141_xp toolset that shipped in Visual Studio 2017 is still available as an optional component in the Visual Studio Installer. For information on how to install the v141_xp Windows XP platform toolset, see [Configuring programs for Windows XP](../build/configuring-programs-for-windows-xp.md). + +## Deprecated in Visual Studio 2022 + +- Support for project upgrade from Visual C++ 6 + + Visual Studio 2022 and later versions don't support upgrades from Visual C++ 6 Workspace (*`.dsw`*) and Project (*`.dsp`*) files. Visual Studio no longer registers the *`.dsw`* and *`.dsp`* file extensions as Visual Studio file types. To upgrade a project with these extensions, first use Visual Studio 2019 to upgrade the project to modern Solution (*`.sln`*) and C++ Project (*`.vcxproj`*) files. Then use the current version of Visual Studio to upgrade the project again. diff --git a/docs/porting/porting-third-party-libraries.md b/docs/porting/porting-third-party-libraries.md index 35c6bb0682..db6afa9358 100644 --- a/docs/porting/porting-third-party-libraries.md +++ b/docs/porting/porting-third-party-libraries.md @@ -13,7 +13,7 @@ When you upgrade an application from Visual Studio 2015 or later, it isn't neces ## Use vcpkg for open-source libraries -In the past, finding and upgrading third-party libraries was sometimes a non-trivial task. To make it easier to acquire and rebuild C++ third-party open-source libraries, the Visual C++ team has created a command-line tool called the **VC++ Packaging Tool** or **vcpkg**. Vcpkg has a searchable catalog of many popular C++ open-source libraries. You can install any library in the catalog directly from the vcpkg command line. When you install a library, Vcpkg creates a directory tree on your machine and adds the *`.h`* files, the *`.lib`* files, and binaries in this folder. You can use this folder in your compilation command line, or integrate it into Visual Studio 2015 or later by using the `vcpkg integrate install` command. After you integrate a library location, Visual Studio can find it and add it to any new project that you create. To use a library, just `#include` it. Visual Studio will automatically add the library path to your project settings and copy the DLL to your solution folder. For more information, see [vcpkg](https://vcpkg.io/). +In the past, finding and upgrading third-party libraries was sometimes a non-trivial task. To make it easier to acquire and rebuild C++ third-party open-source libraries, the Visual C++ team has created a command-line tool called the **VC++ Packaging Tool** or **vcpkg**. Vcpkg has a searchable catalog of many popular C++ open-source libraries. You can install any library in the catalog directly from the vcpkg command line. When you install a library, Vcpkg creates a directory tree on your machine and adds the *`.h`* files, the *`.lib`* files, and binaries in this folder. You can use this folder in your compilation command line, or integrate it into Visual Studio 2015 or later by using the `vcpkg integrate install` command. After you integrate a library location, Visual Studio can find it and add it to any new project that you create. To use a library, just `#include` it. Visual Studio will automatically add the library path to your project settings and copy the DLL to your solution folder. For more information, see [vcpkg](/vcpkg/). ## Reporting issues diff --git a/docs/porting/upgrade-your-code-to-the-universal-crt.md b/docs/porting/upgrade-your-code-to-the-universal-crt.md index 8348c6374e..03e27d4e2a 100644 --- a/docs/porting/upgrade-your-code-to-the-universal-crt.md +++ b/docs/porting/upgrade-your-code-to-the-universal-crt.md @@ -1,47 +1,55 @@ --- description: "Learn more about: Upgrade your code to the Universal CRT" title: "Upgrade your code to the Universal CRT" -ms.date: "03/31/2017" +ms.date: 06/28/2022 ms.assetid: eaf34c1b-da98-4058-a059-a10db693a5ce --- # Upgrade your code to the Universal CRT -In Visual Studio 2015, the Microsoft C Runtime Library (CRT) was refactored. The Standard C Library, POSIX extensions and Microsoft-specific functions, macros, and global variables were moved into a new library, the Universal C Runtime Library (Universal CRT or UCRT). The compiler-specific components of the CRT were moved into a new vcruntime library. +The Microsoft C Runtime Library (CRT) was refactored in Visual Studio 2015. The Standard C Library, POSIX extensions and Microsoft-specific functions, macros, and global variables were moved into a new library, the Universal C Runtime Library (Universal CRT or UCRT). The compiler-specific components of the CRT were moved into a new vcruntime library. -The UCRT is now a Windows component, and ships as part of Windows 10 and later. The UCRT supports a stable ABI based on C calling conventions, and it conforms closely to the ISO C99 standard, with only a few exceptions. It is no longer tied to a specific version of the compiler. You can use the UCRT on any version of Windows supported by Visual Studio 2015 or Visual Studio 2017. The benefit is that you no longer need to update your builds to target a new version of the CRT with every upgrade of Visual Studio. +The UCRT is now a Windows component, and ships as part of Windows 10 and later. The UCRT supports a stable ABI based on C calling conventions, and it conforms closely to the ISO C99 standard, with only a few exceptions. It's no longer tied to a specific version of the compiler. You can use the UCRT on any version of Windows supported by Visual Studio 2015 or Visual Studio 2017. The benefit is that you no longer need to update your builds to target a new version of the CRT with every upgrade of Visual Studio. -With this refactoring, the names or locations of many CRT header files, library files, and redistributables, and the deployment methods required for your code have changed. In addition, many functions and macros in the UCRT were added or changed to improve standards conformance. To take advantage of these changes, your existing code and project build systems must be updated. +This refactoring has changed the names or locations of many CRT header files, library files, and Redistributable files, and the deployment methods required for your code. Many functions and macros in the UCRT were also added or changed to improve standards conformance. To take advantage of these changes, you must update your existing code and project build systems. ## Where to find the Universal CRT files -As a Windows component, the UCRT library files and headers are now part of the Windows software development kit (SDK). When you install Visual Studio, the parts of the Windows SDK required to use the UCRT are also installed. The Visual Studio installer adds the locations of the UCRT headers, libraries and DLL files to the default paths used by the Visual Studio project build system. When you update your Visual Studio C++ projects, if they use the default project settings, the IDE automatically finds the new locations for header files, and the linker automatically uses the new default UCRT and vcruntime libraries. Similarly, if you use a Developer command prompt to do command-line builds, the environment variables that contain paths for headers and libraries are updated and work automatically as well. +As a Windows component, the UCRT library files and headers are now part of the Windows software development kit (SDK). When you install Visual Studio, the parts of the Windows SDK required to use the UCRT are also installed. The Visual Studio installer adds the locations of the UCRT headers, libraries and DLL files to the default paths used by the Visual Studio project build system. When you update your Visual Studio C++ projects, if they use the default project settings, the IDE automatically finds the new locations for header files. And, the linker automatically uses the new default UCRT and vcruntime libraries. Similarly, if you use a Developer command prompt to do command-line builds, the environment variables that contain paths for headers and libraries are updated and work automatically as well. -The Standard C Library header files are now found in the Windows SDK in an include folder in an SDK version-specific directory. A typical location for the header files is in the Program Files or Program Files (x86) directory under Windows Kits\\10\\Include\\_sdk-version_\\ucrt, where _sdk-version_ corresponds to a Windows version or update, for example, 10.0.14393.0 for the Anniversary Update of Windows 10. +The Standard C Library header files are now found in the Windows SDK in an include folder in an SDK version-specific directory. A typical location for the header files is in the *Program Files* or *Program Files (x86)* directory under `Windows Kits\10\Include\[sdk-version]\ucrt`, where `[sdk-version]` corresponds to a Windows version or update, for example, 10.0.14393.0 for the Anniversary Update of Windows 10. -The UCRT static libraries and dynamic link stub libraries are found in the Program Files or Program Files (x86) directory under Windows Kits\\10\\Lib\\_sdk-version_\\ucrt\\_architecture_, where _architecture_ is ARM, x86, or X64. The retail and debug static libraries are libucrt.lib and libucrtd.lib, and the libraries for the UCRT DLLs are ucrt.lib and ucrtd.lib. +The UCRT static libraries and dynamic link stub libraries are found in the *Program Files* or *Program Files (x86)* directory under `Windows Kits\10\Lib\[sdk-version]\ucrt\[architecture]`, where `architecture` is ARM64, x86, or X64. The retail and debug static libraries are `libucrt.lib` and `libucrtd.lib`, and the libraries for the UCRT DLLs are `ucrt.lib` and `ucrtd.lib`. -The retail and debug UCRT DLLs are found in separate locations. The retail DLLs are redistributable, and can be found in the Program Files or Program Files (x86) directory under Windows Kits\\10\\Redist\\ucrt\\DLLs\\_architecture_\. Debug UCRT libraries are not redistributable, and can be found in the Program Files or Program Files (x86) directory under Windows Kits\\10\\bin\\_architecture_\\ucrt folder. +The retail and debug UCRT DLLs are found in separate locations. The retail DLLs are Redistributable files, and can be found in the *Program Files* or *Program Files (x86)* directory under `Windows Kits\10\Redist\ucrt\DLLs\[architecture]\`. Debug UCRT libraries aren't Redistributable files, and can be found in the *Program Files* or *Program Files (x86)* directory under `Windows Kits\10\bin\[architecture]\ucrt` folder. -The C and C++ compiler-specific runtime support library, **vcruntime**, contains the code required to support program startup and features such as exception handling and intrinsics. The library and its header files are still found in the version-specific Microsoft Visual Studio folder in your Program Files or Program files (x86) directory. In Visual Studio 2017, the headers are found under Microsoft Visual Studio\\2017\\_edition_\\VC\\Tools\\MSVC\\_lib-version_\\include and the link libraries are found under Microsoft Visual Studio\\2017\\_edition_\\VC\\Tools\\MSVC\\_lib-version_\\lib\\_architecture_, where _edition_ is the edition of Visual Studio installed, _lib-version_ is the version of the libraries, and _architecture_ is the processor architecture. Link libraries for OneCore and Store are also found in the libraries folder. The retail and debug versions of the static library are libvcruntime.lib and libvcruntimed.lib. The dynamic link retail and debug stub libraries are vcruntime.lib and vcruntimed.lib, respectively. +## Where to find the standard libraries and headers -When you update your Visual Studio C++ projects, if you have set the project's **Linker** property **Ignore All Default Libraries** to **Yes** or if you use the `/NODEFAULTLIB` linker option on the command line, then you must update your list of libraries to include the new, refactored libraries. Replace the old CRT library, for example, libcmt.lib, libcmtd.lib, msvcrt.lib, or msvcrtd.lib, with the equivalent refactored libraries. For information on the specific libraries to use, see [CRT Library Features](../c-runtime-library/crt-library-features.md). +The C and C++ compiler-specific runtime support library, `vcruntime`, contains the code required to support program startup and features such as exception handling and intrinsics. The library and its header files are still found in the version-specific Microsoft Visual Studio folder in your *Program Files* or *Program files (x86)* directory. + +In Visual Studio 2017, 2019, and 2022, the header files are found under `Microsoft Visual Studio\[year]\[edition]\VC\Tools\MSVC\[lib-version]\include`. Here, `[year]` is the version of Visual Studio, `[edition]` is the edition or nickname for Visual Studio, and `[lib-version]` is the build version of the libraries. + +The link libraries are found under `Microsoft Visual Studio\[year]\[edition]\VC\Tools\MSVC\[lib-version]\lib\[architecture]`, where `[year]` is the version of Visual Studio, `[edition]` is the edition or nickname for Visual Studio, `[lib-version]` is the build version of the libraries, and `[architecture]` is the target processor architecture. Link libraries for OneCore and Store are also found in the libraries folder. + +The retail and debug versions of the static library are `libvcruntime.lib` and `libvcruntimed.lib`. The dynamic link retail and debug stub libraries are `vcruntime.lib` and `vcruntimed.lib`, respectively. + +When you update your Visual Studio C++ projects, if you have set the project's **Linker** property **Ignore All Default Libraries** to **Yes**, or if you use the `/NODEFAULTLIB` linker option on the command line, then you must update your list of libraries to include the new, refactored libraries. Replace the old CRT library, for example, `libcmt.lib`, `libcmtd.lib`, `msvcrt.lib`, or `msvcrtd.lib`, with the equivalent refactored libraries. For information on the specific libraries to use, see [CRT library features](../c-runtime-library/crt-library-features.md). ## Deployment and redistribution of the Universal CRT -Because the UCRT is now a Microsoft Windows operating system component, it is included as part of the operating system in Windows 10 and later. It's available through Windows Update for older operating systems, Windows Vista through Windows 8.1. A redistributable version is available for Windows XP. As an operating system component, UCRT updates and servicing are managed by Windows Update independently of Visual Studio and Microsoft C++ compiler versions. Because the UCRT is a Windows component, for security and ease of updates, and a smaller image size, we strongly recommend central deployment of the UCRT for your app. +Because the UCRT is now a Microsoft Windows operating system component, it's included as part of the operating system in Windows 10 and later. It's available through Windows Update for older operating systems, Windows Vista through Windows 8.1. A Redistributable version is available for Windows XP. As an operating system component, UCRT updates and servicing are managed by Windows Update independently of Visual Studio and Microsoft C++ compiler versions. Because the UCRT is a Windows component, for security and ease of updates, and a smaller image size, we strongly recommend you use the Redistributable package to do central deployment of the UCRT for your app. -You can use the UCRT on any version of Windows supported by Visual Studio 2015 or later. You can redistribute it using a vcredist package for supported versions of Windows before Windows 10. The vcredist packages include the UCRT components and automatically install them on Windows operating systems that do not have them installed by default. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). +You can use the UCRT on any version of Windows supported by Visual Studio 2015 or later. You can redistribute it using a `vcredist` package for supported versions of Windows before Windows 10. The `vcredist` packages include the UCRT components and automatically install them on Windows operating systems that don't have them installed by default. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). -App-local deployment of the UCRT is supported, though not recommended for both performance and security reasons. The DLLs for app-local deployment are included as part of the Windows SDK, under the **redist** subdirectory. The DLLs required include ucrtbase.dll and a set of **APISet forwarder** DLLs named api-ms-win-_subset_.dll. The set of DLLs required on each operating system varies, so we recommended that you include all of the DLLs when you use app-local deployment. For additional details and caveats about app-local deployment, see [Deployment in Visual C++](../windows/deployment-in-visual-cpp.md). +App-local deployment of the UCRT is supported, though not recommended for both performance and security reasons. The DLLs for app-local deployment of the UCRT are included as part of the Windows SDK, under the *`redist`* subdirectory. The DLLs required include `ucrtbase.dll` and a set of **APISet forwarder** DLLs named `api-ms-win-[subset].dll`. The set of DLLs required on each operating system varies, so we recommended that you include all of the DLLs when you use app-local deployment. For more information and recommendations about app-local deployment, see [Deployment in Visual C++](../windows/deployment-in-visual-cpp.md). ## Changes to the Universal CRT functions and macros -Many functions were added or updated in the UCRT to improve ISO C99 conformance, and to address code quality and security issues. In some cases, this required breaking changes to the library. If your code compiled cleanly when using an older version of the CRT but breaks when compiled using the UCRT, you must change your code to take advantage of these updates and features. For a detailed listing of the breaking changes and updates to the CRT found in the Universal CRT, see the [C Runtime Library (CRT)](visual-cpp-change-history-2003-2015.md#BK_CRT) section of the Visual C++ change history. It includes a list of affected headers and functions that you can use to identify the changes needed in your code. +Many functions were added or updated in the UCRT to improve ISO C99 conformance, and to address code quality and security issues. In some cases, this required breaking changes to the library. Your code that compiled cleanly when using an older version of the CRT may break when you compile it using the UCRT. If so, you must change your code to take advantage of UCRT updates and features. For a detailed listing of the breaking changes and updates to the CRT found in the Universal CRT, see the [C Runtime Library (CRT)](visual-cpp-change-history-2003-2015.md#BK_CRT) section of the Visual C++ change history. It includes a list of affected headers and functions that you can use to identify the changes needed in your code. ## See also -[Visual C++ Porting and Upgrading Guide](visual-cpp-porting-and-upgrading-guide.md)
-[Overview of potential upgrade issues (Visual C++)](overview-of-potential-upgrade-issues-visual-cpp.md)
-[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)
-[Visual C++ change history 2003 - 2015](visual-cpp-change-history-2003-2015.md)
+[Visual C++ porting and upgrading guide](visual-cpp-porting-and-upgrading-guide.md)\ +[Overview of potential upgrade issues (Visual C++)](overview-of-potential-upgrade-issues-visual-cpp.md)\ +[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ +[Visual C++ change history 2003 - 2015](visual-cpp-change-history-2003-2015.md)\ [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) diff --git a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md index 6c48291655..53b9ef1a06 100644 --- a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md +++ b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md @@ -1,7 +1,7 @@ --- title: "Upgrade C++ projects from earlier versions of Visual Studio" description: "How to upgrade Microsoft C++ projects from older versions of Visual Studio." -ms.date: "01/21/2020" +ms.date: 04/07/2022 helpviewer_keywords: ["32-bit code porting", "upgrading Visual C++ applications, 32-bit code"] ms.assetid: 18cdacaa-4742-43db-9e4c-2d9e73d8cc84 --- @@ -13,6 +13,9 @@ If you choose **No**, the project doesn't get upgraded. For projects created in If you choose **Yes**, then the project gets upgraded in place. It can't be converted back to the earlier version. In upgrade scenarios, that's why it's good practice to make a backup copy of the existing project and solution files. +> [!NOTE] +> Visual Studio 2022 has deprecated support for the upgrade of project types that have *`.dsw`* or *`.dsp`* extensions. You can use an earlier version of Visual Studio, such as Visual Studio 2019, to upgrade these projects, then upgrade them in Visual Studio 2022 to use the latest tools and features of Visual Studio. + ## Upgrade reports When you upgrade a project, you get an upgrade report. The report is also saved in your project folder as UpgradeLog.htm. The upgrade report shows a summary of what problems were found during conversion. It lists some information about changes that were made, including: @@ -53,7 +56,7 @@ Some upgraded projects and solutions can be built successfully without modificat 1. Consider other opportunities for modernizing the code. For example, replace custom data structures and algorithms with ones from the C++ standard library, or the Boost open-source library. By using standard features, you make it easier for others to maintain the code. You can be confident that this code has been well-tested and reviewed by many experts on the standards committee and the broader C++ community. -For hard-to-fix errors, you can search for solutions or post a question on [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html). For problems in the C++ compiler and tools, try the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) website. +For hard-to-fix errors, you can search for solutions or post a question on [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html). For problems in the C++ compiler and tools, try the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) website. ## In this section @@ -62,7 +65,7 @@ For hard-to-fix errors, you can search for solutions or post a question on [Micr [Update WINVER and _WIN32_WINNT](modifying-winver-and-win32-winnt.md)\ [Fix your dependencies on library internals](fix-your-dependencies-on-library-internals.md)\ [Floating-point migration issues](floating-point-migration-issues.md)\ -[C++ features deprecated in Visual Studio 2019](features-deprecated-in-visual-studio.md)\ +[C++ features deprecated in Visual Studio](features-deprecated-in-visual-studio.md)\ [VCBuild vs. MSBuild](build-system-changes.md)\ [Port 3rd-party libraries](porting-third-party-libraries.md) diff --git a/docs/porting/use-native-multi-targeting.md b/docs/porting/use-native-multi-targeting.md index f2cad7558e..280f53a6c8 100644 --- a/docs/porting/use-native-multi-targeting.md +++ b/docs/porting/use-native-multi-targeting.md @@ -1,15 +1,15 @@ --- description: "Learn more about: Use native multi-targeting in Visual Studio to build old projects" title: "Use native multi-targeting in Visual Studio to build old projects" -ms.date: "10/25/2019" +ms.date: 02/22/2022 helpviewer_keywords: ["C++ native multi-targeting", "upgrading Visual C++ applications, retargeting"] ms.assetid: b115aabe-a9dc-4525-90d3-367d97ea20c9 --- # Use native multi-targeting in Visual Studio to build old projects -Normally, we recommend that you update your projects when you install the latest version of Visual Studio. The cost of updating your projects and code is usually more than offset by the benefits of the new IDE, compiler, libraries, and tools. However, we know that you may not be able to update some projects. You may have binaries that are tied to older libraries or platforms that for maintenance reasons you can't upgrade. Your code may use non-standard language constructs that would break if you moved to a more recent compiler. Your code might rely on 3rd party libraries compiled for a specific version of Visual C++. Or you may produce libraries for others that must target a specific older version of Visual C++. +Normally, we recommend that you update your projects when you install the latest version of Visual Studio. The cost of updating your projects and code is often more than offset by the benefits of the new IDE, compiler, libraries, and tools. However, we know that you may not be able to update some projects. You may have binaries that are tied to older libraries or platforms that for maintenance reasons you can't upgrade. Your code may use non-standard language constructs that would break if you moved to a more recent compiler. Your code might rely on third-party libraries compiled for a specific version of Visual C++. Or you may produce libraries for others that must target a specific older version of Visual C++. -Fortunately, you can use Visual Studio 2017 and Visual Studio 2015 to build projects that target older compiler toolsets and libraries. You don't have to upgrade a Visual Studio 2010, Visual Studio 2012, Visual Studio 2013, or Visual Studio 2015 project to take advantage of new features in the IDE: +Fortunately, you can use Visual Studio to build projects that target older compiler toolsets and libraries. If you still have the original tools installed, you don't have to upgrade a project from as far back as Visual Studio 2010 to take advantage of new features in the IDE: - New C++ refactoring capabilities and editor experimental features - New Diagnostics tools debugger window and Error List window @@ -27,40 +27,40 @@ When you use an older toolset, you can take advantage of many of the latest IDE Once you have installed Visual Studio side-by-side with your older version, open your existing project in the new version of Visual Studio. When the project is loaded, Visual Studio asks you whether you want to upgrade it to use the latest C++ compiler and libraries. Since you want the project to keep the older compiler and libraries, choose the **Cancel** button. -Visual Studio is persistent about upgrading your project. To avoid seeing the upgrade dialog every time you load the project, you can define the following property in your projects, or in the .props or .targets files they import: +Visual Studio is persistent about upgrading your project. To avoid seeing the upgrade dialog every time you load the project, you can define the following property in your projects, or in the *`.props`* or *`.targets`* files they import: `NoUpgrade` You must remove this property when you want to upgrade your projects. -If you choose not to upgrade, Visual Studio makes no changes to your solution or project files. When you build the project, the generated binaries are fully compatible with the ones you built with the older version of Visual Studio. This is because Visual Studio uses the same C++ compiler and links the same libraries that your older IDE shipped with. That is also why the upgrade dialog warns you to keep the older Visual Studio version installed if you choose **Cancel**. +If you choose not to upgrade, Visual Studio makes no changes to your solution or project files. When you build the project, the generated binaries are fully compatible with the ones you built with the older version of Visual Studio, because Visual Studio uses the same C++ compiler and links the same libraries that your older IDE shipped with. It's also why the upgrade dialog warns you to keep the older Visual Studio version installed if you choose **Cancel**. ## Instructions for Visual Studio 2008 -Visual Studio 2008 had its own dedicated build system for C++ called **VCBuild**. Starting in Visual Studio 2010, Visual Studio C++ projects were changed to use **MSBuild**. This means that whether upgrading permanently or multi-targeting you must go through an update step to build your Visual Studio 2008 projects in the latest version of Visual Studio. Your updated project still generates binaries that are fully compatible with binaries created using the Visual Studio 2008 IDE. +Visual Studio 2008 had its own dedicated build system for C++ called **VCBuild**. In Visual Studio 2010, Visual Studio C++ projects were changed to use **MSBuild**. Whether upgrading permanently or multi-targeting, you must go through an update step to build your Visual Studio 2008 projects in the latest version of Visual Studio. Your updated project still generates binaries that are fully compatible with binaries created using the Visual Studio 2008 IDE. First, in addition to the current version of Visual Studio, you must install Visual Studio 2010 on the same computer as Visual Studio 2008. Only Visual Studio 2010 installs the **MSBuild** scripts that are required to target Visual Studio 2008 projects. -Next, you must update your Visual Studio 2008 solution and projects to the current version of Visual Studio. We recommend you create a backup of your projects and solution files before the upgrade. To start the upgrade process, open the solution in the current version of Visual Studio. When you get the upgrade prompt, review the information presented, and then choose **OK** to start the upgrade. If you have more than one project in the solution, you must update The wizard creates new .vcxproj project files side-by-side with the existing .vcproj files. As long as you also have a copy of the original .sln file, the upgrade has no other impact on your existing Visual Studio 2008 projects. +Next, you must update your Visual Studio 2008 solution and projects to the current version of Visual Studio. We recommend you create a backup of your projects and solution files before the upgrade. To start the upgrade process, open the solution in the current version of Visual Studio. When you get the upgrade prompt, review the information presented, and then choose **OK** to start the upgrade. If the solution has more than one project, you must update each project. The wizard creates new *`.vcxproj`* project files side-by-side with the existing *`.vcproj`* files. As long as you also have a copy of the original *`.sln`* file, the upgrade has no other effect on your existing Visual Studio 2008 projects. > [!NOTE] -> The following steps apply to multi-targeting scenarios only. If you intend to permanently upgrade the project to a later toolset, then your next step is to save the project, open it in Visual Studio 2019, and address the build issues that appear there. +> The following steps apply to multi-targeting scenarios only. If you intend to permanently upgrade the project to a later toolset, then your next step is to save the project, open it in the latest version of Visual Studio, and address the build issues that appear there. -When the upgrade completes, if the log report has errors or warnings for any of your projects, review them carefully. The conversion from **VCBuild** to **MSBuild** can cause issues. Make sure you understand and implement any action items listed in the report. For more information on the upgrade log report and issues that may occur when converting **VCBuild** to **MSBuild**, see this [C++ Native Multi-Targeting](https://devblogs.microsoft.com/cppblog/c-native-multi-targeting/) blog post. +When the upgrade completes, if the log report has errors or warnings for any of your projects, review them carefully. The conversion from **VCBuild** to **MSBuild** can cause issues. Make sure you understand and implement any action items listed in the report. For more information on the upgrade log report and issues that may occur when converting **VCBuild** to **MSBuild**, see the [C++ Native Multi-Targeting](https://devblogs.microsoft.com/cppblog/c-native-multi-targeting/) blog post. -When the project upgrade is completed, and you have corrected any issues in the log file, your solution actually targets the latest toolset. As the final step, change the properties for each project in the solution to use the Visual Studio 2008 toolset. With the solution loaded in the current version of Visual Studio, for each project in the solution, open the Project **Property Pages** dialog box: Right-click on the project in **Solution Explorer** and then select **Properties**. In the **Property Pages** dialog box, change the **Configuration** drop-down value to **All Configurations**. In **Configuration Properties**, select **General**, and then change **Platform Toolset** to **Visual Studio 2008 (v90)**. +When the upgrade is complete and you've fixed any issues in the log file, your solution now targets the latest toolset. As the final step, change the properties for each project in the solution to use the Visual Studio 2008 toolset. With the solution loaded in the current version of Visual Studio, for each project in the solution, open the Project **Property Pages** dialog box: Right-click on the project in **Solution Explorer** and then select **Properties**. In the **Property Pages** dialog box, change the **Configuration** drop-down value to **All Configurations**. In **Configuration Properties**, select **General**, and then change **Platform Toolset** to **Visual Studio 2008 (v90)**. After this change, the Visual Studio 2008 compiler and libraries are used to generate project binaries when you build the solution in the current version of Visual Studio. ## Install an older Visual Studio toolset -You may have an old Visual Studio C++ project that you can't or don't want to upgrade, but not the platform toolset version that matches your project. In this case, to get the toolset, you can install the free Visual Studio Community or Express edition of the version you need. Every version of Visual Studio from Visual Studio 2008 on can install the compiler, tools, and libraries you need to target that version from the current Visual Studio. Search the Microsoft Download Center to find and download a particular version of Visual Studio. Make sure you choose the C++ installation options during setup. After setup completes, run that version of Visual Studio to install any updates. Also check for any Windows Update changes that might be required. This update check process may need to be repeated more than once to get every update. +You may have an old Visual Studio C++ project that you can't or don't want to upgrade. To build it, you need the platform toolset version that matches your project. To get the toolset, you can install the free Visual Studio Community or Express edition of the version you need. Every version of Visual Studio from Visual Studio 2008 on can install the compiler, tools, and libraries you need to target that version from the current Visual Studio. Search the Microsoft Download Center to find and download a particular version of Visual Studio. Make sure you choose the C++ installation options during setup. After setup completes, run that version of Visual Studio to install any updates. Also check for any Windows Update changes that might be required. This update check process may need to be repeated more than once to get every update. For the currently available downloads, see [Download older Visual Studio software](https://visualstudio.microsoft.com/vs/older-downloads/). -When these products are installed, the **Platform Toolset** property drop-down in the **Property Pages** dialog box is automatically updated to show the available toolsets. You can now use the latest version of Visual Studio to build projects for those older versions of the toolset without converting or upgrading them. +When these products are installed, the **Platform Toolset** property drop-down in the **Property Pages** dialog box is automatically updated to show the available toolsets. You can now use the latest version of Visual Studio to build projects that use an older version of the toolset: no conversion or upgrade required. ## See also -[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)
+[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) diff --git a/docs/porting/visual-cpp-change-history-2003-2015.md b/docs/porting/visual-cpp-change-history-2003-2015.md index 41bf40e21d..cb872ffdf6 100644 --- a/docs/porting/visual-cpp-change-history-2003-2015.md +++ b/docs/porting/visual-cpp-change-history-2003-2015.md @@ -1,9 +1,8 @@ --- title: "Microsoft C/C++ change history 2003 - 2015" description: "Find all the breaking changes in Microsoft C/C++ from Visual Studio 2003 through Visual Studio 2015 here." -ms.date: "10/21/2019" +ms.date: 5/25/2023 helpviewer_keywords: ["breaking changes [C++]"] -ms.assetid: b38385a9-a483-4de9-99a6-797488bc5110 --- # Microsoft C/C++ change history 2003 - 2015 @@ -38,37 +37,35 @@ Additionally, ongoing improvements to compiler conformance can sometimes change - **Refactored binaries** - The CRT Library has been refactored into a two different binaries: a Universal CRT (ucrtbase), which contains most of the standard functionality, and a VC Runtime Library (vcruntime). The vcruntime library contains the compiler-related functionality such as exception handling, and intrinsics. If you are using the default project settings, then this change doesn't impact you since the linker will use the new default libraries automatically. If you've set the project's **Linker** property **Ignore All Default Libraries** to **Yes** or you are using the `/NODEFAULTLIB` linker option on the command line, then you must update your list of libraries (in the **Additional Dependencies** property) to include the new, refactored libraries. Replace the old CRT library (libcmt.lib, libcmtd.lib, msvcrt.lib, msvcrtd.lib) with the equivalent refactored libraries. For each of the two refactored libraries, there are static (.lib) and dynamic (.dll) versions, and release (with no suffix) and debug versions (with the "d" suffix). The dynamic versions have an import library that you link with. The two refactored libraries are Universal CRT, specifically ucrtbase.dll or ucrtbase.lib, ucrtbased.dll or ucrtbased.lib, and the VC runtime library, libvcruntime.lib, vcruntime*version*.dll, libvcruntimed.lib, and vcruntimed*version*.dll. The *version* in both Visual Studio 2015 and Visual Studio 2017 is 140. See [CRT Library Features](../c-runtime-library/crt-library-features.md). + The CRT Library has been refactored into a two different binaries: a Universal CRT (ucrtbase), which contains most of the standard functionality, and a VC Runtime Library (vcruntime). The vcruntime library contains the compiler-related functionality such as exception handling, and intrinsics. If you are using the default project settings, then this change doesn't impact you since the linker uses the new default libraries automatically. If you've set the project's **Linker** property **Ignore All Default Libraries** to **Yes** or you are using the `/NODEFAULTLIB` linker option on the command line, then you must update your list of libraries (in the **Additional Dependencies** property) to include the new, refactored libraries. Replace the old CRT library (`libcmt.lib`, `libcmtd.lib`, `msvcrt.lib`, `msvcrtd.lib`) with the equivalent refactored libraries. For each of the two refactored libraries, there are static (.lib) and dynamic (.dll) versions, and release (with no suffix) and debug versions (with the "d" suffix). The dynamic versions have an import library that you link with. The two refactored libraries are Universal CRT, specifically ucrtbase.dll or ucrtbase.lib, ucrtbased.dll or ucrtbased.lib, and the VC runtime library, `libvcruntime.lib`, vcruntime*version*.dll, `libvcruntimed.lib`, and vcruntimed*version*.dll. The *version* in both Visual Studio 2015 and Visual Studio 2017 is 140. See [CRT Library Features](../c-runtime-library/crt-library-features.md). -#### \ +#### `` -- **localeconv** +- **`localeconv`** - The [localeconv](../c-runtime-library/reference/localeconv.md) function declared in locale.h now works correctly when [per-thread locale](../parallel/multithreading-and-locales.md) is enabled. In previous versions of the library, this function would return the `lconv` data for the global locale, not the thread's locale. + The [`localeconv`](../c-runtime-library/reference/localeconv.md) function declared in locale.h now works correctly when [per-thread locale](../parallel/multithreading-and-locales.md) is enabled. In previous versions of the library, this function would return the `lconv` data for the global locale, not the thread's locale. If you use per-thread locales, you should check your use of `localeconv`. If your code assumes that the `lconv` data returned is for the global locale, you should correct it. -#### \ +#### `` - **C++ overloads of math library functions** - In previous versions, \ defined some, but not all, of the C++ overloads for the math library functions. The rest of the overloads were in the \ header. Code that only included \ could have problems with function overload resolution. Now the C++ overloads have been removed from \ and are only found in \. + In previous versions, `` defined some, but not all, of the C++ overloads for the math library functions. The rest of the overloads were in the `` header. Code that only included `` could have problems with function overload resolution. Now the C++ overloads have been removed from `` and are only found in ``. - To resolve errors, include \ to get the declarations of the functions that were removed from \. These functions were moved: + To resolve errors, include `` to get the declarations of the functions that were removed from ``. These functions were moved: - `double abs(double)` and `float abs(float)` - - `double pow(double, int)`, `float pow(float, float)`, `float pow(float, int)`, `long double pow(long double, long double)`, `long double pow(long double, int)` - - **`float`** and **`long double`** versions of floating point functions `acos`, `acosh`, `asin`, `asinh`, `atan`, `atanh`, `atan2`, `cbrt`, `ceil`, `copysign`, `cos`, `cosh`, `erf`, `erfc`, `exp`, `exp2`, `expm1`, `fabs`, `fdim`, `floor`, `fma`, `fmax`, `fmin`, `fmod`, `frexp`, `hypot`, `ilogb`, `ldexp`, `lgamma`, `llrint`, `llround`, `log`, `log10`, `log1p`, `log2`, `lrint`, `lround`, `modf`, `nearbyint`, `nextafter`, `nexttoward`, `remainder`, `remquo`, `rint`, `round`, `scalbln`, `scalbn`, `sin`, `sinh`, `sqrt`, `tan`, `tanh`, `tgamma`, and `trunc` - If you have code that uses `abs` with a floating point type that only includes the \ header, the floating point versions will no longer be available. The call now resolves to `abs(int)`, even with a floating point argument, which produces the error: + If you have code that uses `abs` with a floating point type that only includes the `` header, the floating point versions will no longer be available. The call now resolves to `abs(int)`, even with a floating point argument, which produces the error: ```Output warning C4244: 'argument' : conversion from 'float' to 'int', possible loss of data ``` - The fix for this warning is to replace the call to `abs` with a floating point version of `abs`, such as `fabs` for a double argument or `fabsf` for a float argument, or include the \ header and continue to use `abs`. + The fix for this warning is to replace the call to `abs` with a floating point version of `abs`, such as `fabs` for a double argument or `fabsf` for a float argument, or include the `` header and continue to use `abs`. - **Floating point conformance** @@ -80,40 +77,40 @@ Additionally, ongoing improvements to compiler conformance can sometimes change In Visual Studio 2013, the FLT_ROUNDS macro expanded to a constant expression, which was incorrect because the rounding mode is configurable at runtime, for example, by calling fesetround. The FLT_ROUNDS macro is now dynamic and correctly reflects the current rounding mode. -#### \ and \ +#### `` and `` -- **new and delete** +- **`new` and `delete`** In previous versions of the library, the implementation-defined operator new and delete functions were exported from the runtime library DLL (for example, msvcr120.dll). These operator functions are now always statically linked into your binaries, even when using the runtime library DLLs. This isn't a breaking change for native or mixed code (`/clr`), however for code compiled as [/clr:pure](../build/reference/clr-common-language-runtime-compilation.md), this change might cause your code to fail to compile. If you compile code as `/clr:pure`, you may need to add `#include ` or `#include ` to work around build errors due to this change. The`/clr:pure` option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Code that needs to be "pure" should be ported to C#. -#### \ +#### `` -- **_beginthread and _beginthreadex** +- **`_beginthread` and `_beginthreadex`** - The [_beginthread](../c-runtime-library/reference/beginthread-beginthreadex.md) and [_beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md) functions now hold a reference to the module in which the thread procedure is defined for the duration of the thread. This helps to ensure that modules aren't unloaded until a thread has run to completion. + The [`_beginthread`](../c-runtime-library/reference/beginthread-beginthreadex.md) and [`_beginthreadex`](../c-runtime-library/reference/beginthread-beginthreadex.md) functions now hold a reference to the module in which the thread procedure is defined for the duration of the thread. This helps to ensure that modules aren't unloaded until a thread has run to completion. -#### \ +#### `` -- **va_start and reference types** +- **`va_start` and reference types** - When compiling C++ code, [va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) now validates at compile-time that the argument passed to it isn't of reference type. Reference-type arguments are prohibited by the C++ Standard. + When compiling C++ code, [`va_start`](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) now validates at compile-time that the argument passed to it isn't of reference type. Reference-type arguments are prohibited by the C++ Standard. -#### \ and \ +#### `` and `` - **The printf and scanf family of functions are now defined inline.** - The definitions of all of the `printf` and `scanf` functions have been moved inline into \, \, and other CRT headers. This breaking change leads to a linker error (LNK2019, unresolved external symbol) for any programs that declared these functions locally without including the appropriate CRT headers. If possible, you should update the code to include the CRT headers (that is, add `#include `) and the inline functions, but if you do not want to modify your code to include these header files, an alternative solution is to add an additional library to your linker input, legacy_stdio_definitions.lib. + The definitions of all of the `printf` and `scanf` functions have been moved inline into ``, ``, and other CRT headers. This breaking change leads to a linker error (LNK2019, unresolved external symbol) for any programs that declared these functions locally without including the appropriate CRT headers. If possible, you should update the code to include the CRT headers (that is, add `#include `) and the inline functions, but if you do not want to modify your code to include these header files, an alternative solution is to add `legacy_stdio_definitions.lib` to your linker input. To add this library to your linker input in the IDE, open the context menu for the project node, choose **Properties**, then in the **Project Properties** dialog box, choose **Linker**, and edit the **Linker Input** to add `legacy_stdio_definitions.lib` to the semi-colon-separated list. - If your project links with static libraries that were compiled with a release of Visual Studio earlier than 2015, the linker might report an unresolved external symbol. These errors might reference internal definitions for `_iob`, `_iob_func`, or related imports for certain \ functions in the form of _imp_\*. Microsoft recommends that you recompile all static libraries with the latest version of the C++ compiler and libraries when you upgrade a project. If the library is a third-party library for which source isn't available, you should either request an updated binary from the third party or encapsulate your usage of that library into a separate DLL that you compile with the older version of the compiler and libraries. + If your project links with static libraries that were compiled with a release of Visual Studio earlier than 2015, the linker might report an unresolved external symbol. These errors might reference internal definitions for `_iob`, `_iob_func`, or related imports for certain `` functions in the form of _imp_\*. Microsoft recommends that you recompile all static libraries with the latest version of the C++ compiler and libraries when you upgrade a project. If the library is a third-party library for which source isn't available, you should either request an updated binary from the third party or encapsulate your usage of that library into a separate DLL that you compile with the older version of the compiler and libraries. > [!WARNING] > If you are linking with Windows SDK 8.1 or earlier, you might encounter these unresolved external symbol errors. In that case, you should resolve the error by adding legacy_stdio_definitions.lib to the linker input as described previously. - To troubleshoot unresolved symbol errors, you can try using [dumpbin.exe](../build/reference/dumpbin-reference.md) to examine the symbols defined in a binary. Try the following command line to view symbols defined in a library. + To troubleshoot unresolved symbol errors, you can try using [`dumpbin.exe`](../build/reference/dumpbin-reference.md) to examine the symbols defined in a binary. Try the following command line to view symbols defined in a library. ```cpp dumpbin.exe /LINKERMEMBER somelibrary.lib @@ -155,7 +152,7 @@ Additionally, ongoing improvements to compiler conformance can sometimes change - **Floating point formatting and parsing** - New floating point formatting and parsing algorithms have been introduced to improve correctness. This change affects the [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) and [scanf](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) families of functions, as well as functions like [strtod](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md). + New floating point formatting and parsing algorithms have been introduced to improve correctness. This change affects the [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) and [scanf](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) families of functions, and functions like [strtod](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md). The old formatting algorithms would generate only a limited number of digits, then would fill the remaining decimal places with zero. They could usually generate strings that would round-trip back to the original floating point value, but weren't great if you wanted the exact value (or the closest decimal representation thereof). The new formatting algorithms generate as many digits as are required to represent the value (or to fill the specified precision). As an example of the improvement; consider the results when printing a large power of two: @@ -219,7 +216,7 @@ Additionally, ongoing improvements to compiler conformance can sometimes change - **snprintf and vsnprintf** - The [snprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) and [vsnprintf](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) functions are now implemented. Older code often provided definitions macro versions of these functions because they were not implemented by the CRT library, but they're no longer needed in newer versions. If [snprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) or [vsnprintf](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) is defined as a macro before including \, compilation now fails with an error that indicates where the macro was defined. + The [snprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) and [vsnprintf](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) functions are now implemented. Older code often provided definitions macro versions of these functions because they were not implemented by the CRT library, but they're no longer needed in newer versions. If [snprintf](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) or [vsnprintf](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) is defined as a macro before including ``, compilation now fails with an error that indicates where the macro was defined. Normally, the fix to this problem is to delete any declarations of `snprintf` or `vsnprintf` in user code. @@ -229,13 +226,13 @@ Additionally, ongoing improvements to compiler conformance can sometimes change - **FILE Encapsulation** - In previous versions, the complete FILE type was defined publicly in \, so it was possible for user code to reach into a FILE and modify its internals. The library has been changed to hide implementation details. As part of this change, FILE as defined in \ is now an opaque type and its members are inaccessible from outside of the CRT itself. + In previous versions, the complete FILE type was defined publicly in ``, so it was possible for user code to reach into a FILE and modify its internals. The library has been changed to hide implementation details. As part of this change, FILE as defined in `` is now an opaque type and its members are inaccessible from outside of the CRT itself. - **_outp and _inp** The functions [_outp](../c-runtime-library/outp-outpw-outpd.md), [_outpw](../c-runtime-library/outp-outpw-outpd.md), [_outpd](../c-runtime-library/outp-outpw-outpd.md), [_inp](../c-runtime-library/inp-inpw-inpd.md), [_inpw](../c-runtime-library/inp-inpw-inpd.md), and [_inpd](../c-runtime-library/inp-inpw-inpd.md) have been removed. -#### \, \, and \ +#### ``, ``, and `` - **strtof and wcstof** @@ -253,9 +250,13 @@ Additionally, ongoing improvements to compiler conformance can sometimes change The `smallheap` link option has been removed. See [Link Options](../c-runtime-library/link-options.md). -#### \ +- **_stat** + + The [`_stat`](../c-runtime-library/reference/stat-functions.md) family of functions use `CreateFile` in Visual Studio 2015, instead of `FindFirstFile` as in Visual Studio 2013 and earlier. This means that `_stat` on a path ending with a slash succeeds if the path refers to a directory, as opposed to before when the function would error with `errno` set to `ENOENT`. -- **wcstok** +#### `` + +- **`wcstok`** The signature of the `wcstok` function has been changed to match what is required by the C Standard. In previous versions of the library, the signature of this function was: @@ -267,21 +268,21 @@ Additionally, ongoing improvements to compiler conformance can sometimes change A new `_wcstok` function has been added with the old signature to ease porting. When compiling C++ code, there is also an inline overload of `wcstok` that has the old signature. This overload is declared as deprecated. In C code, you may define_CRT_NON_CONFORMING_WCSTOK to cause `_wcstok` to be used in place of `wcstok`. -#### \ +#### `` - **clock** - In previous versions, the [clock](../c-runtime-library/reference/clock.md) function was implemented using the Windows API [GetSystemTimeAsFileTime](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime). With this implementation, the clock function was sensitive to the system time, and was thus not necessarily monotonic. The clock function has been reimplemented in terms of [QueryPerformanceCounter](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) and is now monotonic. + In previous versions, the [`clock`](../c-runtime-library/reference/clock.md) function was implemented using the Windows API [`GetSystemTimeAsFileTime`](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime). With this implementation, the clock function was sensitive to the system time, and was thus not necessarily monotonic. The clock function has been reimplemented in terms of [`QueryPerformanceCounter`](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) and is now monotonic. - **fstat and _utime** - In previous versions, the [_stat](../c-runtime-library/reference/stat-functions.md), [fstat](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md), and [_utime](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) functions handle daylight savings time incorrectly. Prior to Visual Studio 2013, all of these functions incorrectly adjusted standard time times as if they were in daylight time. + In previous versions, the [`_stat`](../c-runtime-library/reference/stat-functions.md), [`fstat`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md), and [`_utime`](../c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md) functions handle daylight savings time incorrectly. Prior to Visual Studio 2013, all of these functions incorrectly adjusted standard time times as if they were in daylight time. - In Visual Studio 2013, the problem was fixed in the **_stat** family of functions, but the similar problems in the **fstat** and **_utime** families of functions were not fixed. This partial fix led to problems due to the inconsistency between the functions. The **fstat** and **_utime** families of functions have now been fixed, so all of these functions now handle daylight savings time correctly and consistently. + In Visual Studio 2013, the problem was fixed in the **`_stat`** family of functions, but the similar problems in the **`fstat`** and **`_utime`** families of functions were not fixed. This partial fix led to problems due to the inconsistency between the functions. The **`fstat`** and **`_utime`** families of functions have now been fixed, so all of these functions now handle daylight savings time correctly and consistently. - **asctime** - In previous versions, the [asctime](../c-runtime-library/reference/asctime-wasctime.md) function would pad single-digit days with a leading zero, for example: `Fri Jun 06 08:00:00 2014`. The specification requires that such days be padded with a leading space, as in `Fri Jun 6 08:00:00 2014`. This issue has been fixed. + In previous versions, the [`asctime`](../c-runtime-library/reference/asctime-wasctime.md) function would pad single-digit days with a leading zero, for example: `Fri Jun 06 08:00:00 2014`. The specification requires that such days be padded with a leading space, as in `Fri Jun 6 08:00:00 2014`. This issue has been fixed. - **strftime and wcsftime** @@ -291,7 +292,7 @@ Additionally, ongoing improvements to compiler conformance can sometimes change - **timespec and TIME_UTC** - The \ header now defines the `timespec` type and the `timespec_get` function from the C11 Standard. In addition, the TIME_UTC macro, for use with the `timespec_get` function, is now defined. This update is a breaking change for code that has a conflicting definition for any of these identifiers. + The `` header now defines the `timespec` type and the `timespec_get` function from the C11 Standard. In addition, the TIME_UTC macro, for use with the `timespec_get` function, is now defined. This update is a breaking change for code that has a conflicting definition for any of these identifiers. - **CLOCKS_PER_SEC** @@ -303,11 +304,11 @@ To enable new optimizations and debugging checks, the Visual Studio implementati - **C++ Standard Library include files** - Some changes have been made to the include structure in the C++ Standard Library headers. C++ Standard Library headers are allowed to include each other in unspecified ways. In general, you should write your code so that it carefully includes all of the headers that it needs according to the C++ standard, and doesn't rely on which C++ Standard Library headers include which other C++ Standard Library headers. This makes code portable across versions and platforms. At least two header changes in Visual Studio 2015 affect user code. First, \ no longer includes \. Second, \ now declares `std::array` without including all of \, which can break code through the following combination of code constructs: your code has a variable named "array", and you have a using-directive "using namespace std;", and you include a C++ Standard Library header (such as \) that includes \, which now declares `std::array`. + Some changes have been made to the include structure in the C++ Standard Library headers. C++ Standard Library headers are allowed to include each other in unspecified ways. In general, you should write your code so that it carefully includes all of the headers that it needs according to the C++ standard, and doesn't rely on which C++ Standard Library headers include which other C++ Standard Library headers. This makes code portable across versions and platforms. At least two header changes in Visual Studio 2015 affect user code. First, `` no longer includes ``. Second, `` now declares `std::array` without including all of ``, which can break code through the following combination of code constructs: your code has a variable named "array", and you have a using-directive "using namespace std;", and you include a C++ Standard Library header (such as ``) that includes ``, which now declares `std::array`. - **steady_clock** - The \ implementation of [steady_clock](../standard-library/steady-clock-struct.md) has changed to meet the C++ Standard requirements for steadiness and monotonicity. `steady_clock` is now based on [QueryPerformanceCounter](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) and `high_resolution_clock` is now a typedef for `steady_clock`. As a result, in Visual Studio `steady_clock::time_point` is now a typedef for `chrono::time_point`; however, this isn't necessarily the case for other implementations. + The `` implementation of [`steady_clock`](../standard-library/steady-clock-struct.md) has changed to meet the C++ Standard requirements for steadiness and monotonicity. `steady_clock` is now based on [`QueryPerformanceCounter`](/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter) and `high_resolution_clock` is now a typedef for `steady_clock`. As a result, in Visual Studio `steady_clock::time_point` is now a typedef for `chrono::time_point`; however, this isn't necessarily the case for other implementations. - **allocators and const** @@ -325,19 +326,19 @@ To enable new optimizations and debugging checks, the Visual Studio implementati - **const elements** - The C++ standard has always forbidden containers of const elements (such as vector\ or set\). Visual Studio 2013 and earlier accepted such containers. In the current version, such containers fail to compile. + The C++ standard has always forbidden containers of const elements (such as `vector` or `set`). Visual Studio 2013 and earlier accepted such containers. In the current version, such containers fail to compile. - **std::allocator::deallocate** - In Visual Studio 2013 and earlier, `std::allocator::deallocate(p, n)` ignored the argument passed in for *n*. The C++ standard has always required that *n* must be equal to the value passed as the first argument to the invocation of `allocate` which returned *p*. However, in the current version, the value of *n* is inspected. Code that passes arguments for *n* that differ from what the standard requires might crash at runtime. + In Visual Studio 2013 and earlier, `std::allocator::deallocate(p, n)` ignored the argument passed in for *n*. The C++ standard has always required that *n* must be equal to the value passed as the first argument to the invocation of `allocate`, which returned *p*. However, in the current version, the value of *n* is inspected. Code that passes arguments for *n* that differ from what the standard requires might crash at runtime. - **hash_map and hash_set** - The non-standard header files \ and \ are deprecated in Visual Studio 2015 and will be removed in a future release. Use \ and \ instead. + The non-standard header files `` and `` are deprecated in Visual Studio 2015 and will be removed in a future release. Use `` and `` instead. - **comparators and operator()** - Associative containers (the \ family) now require their comparators to have const-callable function call operators. The following code in a comparator class declaration now fails to compile: + Associative containers (the `` family) now require their comparators to have const-callable function call operators. The following code in a comparator class declaration now fails to compile: ```cpp bool operator()(const X& a, const X& b) @@ -621,7 +622,7 @@ Although these differences can affect your source code or other build artifacts, - **Adjacent string literals** - Similarly to the previous, due to related changes in string parsing, adjacent string literals (either wide or narrow character string literals) without any whitespace were interpreted as a single concatenated string in previous releases of Visaul C++. In Visual Studio 2015, you must now add whitespace between the two strings. For example, the following code must be changed: + Similarly to the previous, due to related changes in string parsing, adjacent string literals (either wide or narrow character string literals) without any whitespace were interpreted as a single concatenated string in previous releases of Visual C++. In Visual Studio 2015, you must now add whitespace between the two strings. For example, the following code must be changed: ```cpp char * str = "abc""def"; @@ -1649,10 +1650,10 @@ Although these differences can affect your source code or other build artifacts, //b.cpp // compile with cl.exe /nologo /LD /EHsc /Osx b.cpp - #pragma comment(lib, "A") + #pragma comment(lib, "A") class __declspec(dllimport) A { - public: A(); + public: A(); A(const A&); virtual ~A(); private: @@ -1666,7 +1667,7 @@ Although these differences can affect your source code or other build artifacts, //c.cpp #pragma comment(lib, "A") - #pragma comment(lib, "B") + #pragma comment(lib, "B") class __declspec(dllimport) A { public: @@ -2936,7 +2937,7 @@ The C++ compiler in Visual Studio 2013 detects mismatches in _ITERATOR_DEBUG_LEV - `reference_wrapper`, `ref()`, and `cref()` now forbid binding to temporary objects. -- \ now strictly enforces its compile-time preconditions. +- `` now strictly enforces its compile-time preconditions. - Various C++ Standard Library type traits have the precondition "T shall be a complete type". Although the compiler now enforces this precondition more strictly, it may not enforce it in all situations. (Because C++ Standard Library precondition violations trigger undefined behavior, the Standard doesn't guarantee enforcement.) @@ -2946,7 +2947,7 @@ The C++ compiler in Visual Studio 2013 detects mismatches in _ITERATOR_DEBUG_LEV As a side-effect of this change, the identity case no longer works (`common_type` doesn't always result in type `T`). This behavior conforms to the Proposed Resolution, but it breaks any code that relied on the previous behavior. - If you require an identity type trait, don't use the non-standard `std::identity` that's defined in \ because it won't work for \. Instead, implement your own identity type trait to suit your needs. Here's an example: + If you require an identity type trait, don't use the non-standard `std::identity` that's defined in `` because it won't work for ``. Instead, implement your own identity type trait to suit your needs. Here's an example: ```cpp template < typename T> struct Identity { @@ -3062,7 +3063,7 @@ The `SchedulerType` enumeration of `UmsThreadDefault` is deprecated. Specificati ### MFC and ATL -- Removed Fusion support (afxcomctl32.h); therefore, all methods that are defined in \ have been removed. Header files \ and \ have been deleted. +- Removed Fusion support (afxcomctl32.h); therefore, all methods that are defined in `` have been removed. Header files `` and `` have been deleted. - Changed the name of `CDockablePane::RemoveFromDefaultPaneDividier` to `CDockablePane::RemoveFromDefaultPaneDivider`. @@ -3272,9 +3273,9 @@ The `SchedulerType` enumeration of `UmsThreadDefault` is deprecated. Specificati ### Standard Library -- The \ header is no longer included automatically by many other header files. Instead, include that header explicitly if you require support for the standalone iterators defined in the header. An existing project is affected if it depends on the previous build tool, VCBUILD.exe, or project file suffix, .vcproj.iterator. +- The `` header is no longer included automatically by many other header files. Instead, include that header explicitly if you require support for the standalone iterators defined in the header. An existing project is affected if it depends on the previous build tool, VCBUILD.exe, or project file suffix, .vcproj.iterator. -- In the \ header, the checked_* and unchecked_\* functions are removed. And in the \> header, the `checked_iterator` class is removed, and the `unchecked_array_iterator` class has been added. +- In the `` header, the `checked_*` and `unchecked_*` functions are removed. And in the ``> header, the `checked_iterator` class is removed, and the `unchecked_array_iterator` class has been added. - The `CComPtr::CComPtr(int)` constructor is removed. That constructor allowed a `CComPtr` object to be constructed from the NULL macro, but was unnecessary and allowed nonsensical constructions from non-zero integers. @@ -3364,7 +3365,7 @@ The `SchedulerType` enumeration of `UmsThreadDefault` is deprecated. Specificati - The syntax for SAL Annotations has changed. For more information, see [SAL Annotations](../c-runtime-library/sal-annotations.md). -- The IEEE filter now supports the SSE 4.1 instruction set. For more information, see [_fpieee_flt](../c-runtime-library/reference/fpieee-flt.md)_fpieee_flt. +- The IEEE filter now supports the SSE 4.1 instruction set. For more information, see [`_fpieee_flt`](../c-runtime-library/reference/fpieee-flt.md). - The C Run-Time Libraries that ship with Visual Studio are no longer dependent on the system DLL msvcrt.dll. @@ -3460,11 +3461,11 @@ The `SchedulerType` enumeration of `UmsThreadDefault` is deprecated. Specificati ### Standard Library (2005) -- The exception class (located in the \ header) has been moved to the `std` namespace. In previous versions, this class was in the global namespace. To resolve any errors indicating that the exception class can't be found, add the following using statement to your code: `using namespace std;` +- The exception class (located in the `` header) has been moved to the `std` namespace. In previous versions, this class was in the global namespace. To resolve any errors indicating that the exception class can't be found, add the following using statement to your code: `using namespace std;` - When calling `valarray::resize()`, the contents of the `valarray` will be lost and will be replaced by default values. The `resize()` method is intended to reinitialize the `valarray` rather than grow it dynamically like a vector. -- Debug Iterators: Applications built with a debug version of the C-Runtime Library and which use iterators incorrectly might begin to see asserts at runtime. To disable these asserts, you must define _HAS_ITERATOR_DEBUGGING (superseded by [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) after Visual Studio 2010) to 0. For more information, see [Debug Iterator Support](../standard-library/debug-iterator-support.md) +- Debug Iterators: Applications built with a debug version of the C-Runtime Library and which use iterators incorrectly might begin to see asserts at runtime. To disable these asserts, you must define _HAS_ITERATOR_DEBUGGING (superseded by [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) after Visual Studio 2010) to 0. For more information, see [Debug Iterator Support](../standard-library/debug-iterator-support.md) ## Visual C++ .NET 2003 Breaking Changes diff --git a/docs/porting/visual-cpp-what-s-new-2003-through-2015.md b/docs/porting/visual-cpp-what-s-new-2003-through-2015.md index e1f77ffdff..e2a8e80cb9 100644 --- a/docs/porting/visual-cpp-what-s-new-2003-through-2015.md +++ b/docs/porting/visual-cpp-what-s-new-2003-through-2015.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: Visual C++ What's New 2003 through 2015" title: "Visual C++ What's New 2003 through 2015" -ms.date: "07/02/2019" -ms.assetid: c4afde6f-3d75-40bf-986f-be57e3818e26 +description: "Learn more about: Visual C++ What's New 2003 through 2015" +ms.date: 07/02/2019 --- # Visual C++ What's New 2003 through 2015 @@ -227,14 +226,13 @@ Although these differences can affect your source code or other build artifacts, ```cpp error C3688: invalid literal suffix '_x'; literal operator or literal operator template 'operator ""_x' not found note: Did you forget a space between the string literal and the prefix of the following string literal? - ``` To fix this problem, add a space between the string literal and the macro. - **Adjacent string literals** - Similarly to the previous, due to related changes in string parsing, adjacent string literals (either wide or narrow character string literals) without any whitespace were interpreted as a single concatenated string in previous releases of Visaul C++. In Visual Studio 2015, you must now add whitespace between the two strings. For example, the following code must be changed: + Similarly to the previous, due to related changes in string parsing, adjacent string literals (either wide or narrow character string literals) without any whitespace were interpreted as a single concatenated string in previous releases of Visual C++. In Visual Studio 2015, you must now add whitespace between the two strings. For example, the following code must be changed: ```cpp char * str = "abc""def"; @@ -2206,7 +2204,7 @@ The compiler has breaking changes in this release. - In each function topic, a section on .NET Framework equivalents has been added. - Several string functions now have the option of truncating strings rather than failing when output buffers are too small; see **_TRUNCATE**. - `_set_se_translator` now requires the use of the `/EHa` compiler option. -- `fpos_t` is now **`__int64`** under `/Za` (for C code) and when __STDC__ is set manually (for C++ code). It used to be a **`struct`**. +- `fpos_t` is now **`__int64`** under `/Za` (for C code) and when `__STDC__` is set manually (for C++ code). It used to be a **`struct`**. - _CRT_DISABLE_PERFCRIT_LOCKS can improve the I/O performance of single-threaded programs. - POSIX names have been deprecated in favor of ISO C++ conformant names (for example, use `_getch` rather than `getch`). - New link options .obj files are available for pure mode diff --git a/docs/preprocessor/check-stack.md b/docs/preprocessor/check-stack.md index 33cf7b507f..546130842e 100644 --- a/docs/preprocessor/check-stack.md +++ b/docs/preprocessor/check-stack.md @@ -1,9 +1,9 @@ --- description: "Learn more about the check_stack pragma directive in Microsoft C/C++" title: "check_stack pragma" -ms.date: 01/22/2021 +ms.date: 2/7/2025 f1_keywords: ["vc-pragma.check_stack", "check_stack_CPP"] -helpviewer_keywords: ["check_stack pragma", "pragma, check_stack", "pragma, check_stack usage table"] +helpviewer_keywords: ["check_stack pragma", "pragma, check_stack"] no-loc: ["pragma"] --- # `check_stack` pragma @@ -12,24 +12,24 @@ Instructs the compiler to turn off stack probes if **`off`** (or **`-`**) is spe ## Syntax -> **`#pragma check_stack(`** [{ **`on`** | **`off`** }] **`)`**\ +> **`#pragma check_stack(`** { **`on`** | **`off`** } **`)`**\ > **`#pragma check_stack`** { **`+`** | **`-`** } ## Remarks -This pragma takes effect at the first function defined after the pragma is seen. Stack probes are neither a part of macros nor of functions that are generated inline. +This pragma only applies to 32-bit platforms (x86, ARM32). It has no effect on 64-bit platforms. -If you don't give an argument for the **`check_stack`** pragma, stack checking reverts to the behavior specified on the command line. For more information, see [Compiler options](../build/reference/compiler-options.md). The interaction of the `#pragma check_stack` and the [`/Gs`](../build/reference/gs-control-stack-checking-calls.md) option is summarized in the following table. +This pragma takes effect at the first function defined after the pragma is seen. Stack probes are not inserted for macros or functions that are generated inline. -### Using the check_stack Pragma +`#pragma check_stack(off)` / `#pragma Check_stack-` is ignored if the size of the function locals is larger than 4096 or the value specified by `/Gs`. -| Syntax | Compiled with

`/Gs` option? | Action | -|--|--|--| -| `#pragma check_stack( )` or

`#pragma check_stack` | Yes | Turns off stack checking for functions that follow | -| `#pragma check_stack( )` or

`#pragma check_stack` | No | Turns on stack checking for functions that follow | -| `#pragma check_stack(on)`

or `#pragma check_stack +` | Yes or No | Turns on stack checking for functions that follow | -| `#pragma check_stack(off)`

or `#pragma check_stack -` | Yes or No | Turns off stack checking for functions that follow | +The default behavior of the compiler is to insert stack probes at the beginning of each function if the size of the locals exceeds 4096 or the value specified by `/Gs`. + +Use [/Gs (Control stack checking calls)](../build/reference/gs-control-stack-checking-calls.md) to change the threshold of the locals that trigger stack probes. Use with caution. + +Using `#pragma check_stack()` without arguments is deprecated. ## See also +[Compiler options](../build/reference/compiler-options.md)\ [Pragma directives and the `__pragma` and `_Pragma` keywords](./pragma-directives-and-the-pragma-keyword.md) diff --git a/docs/preprocessor/compiler-warnings-that-are-off-by-default.md b/docs/preprocessor/compiler-warnings-that-are-off-by-default.md index b38e8a2497..da2758a0ba 100644 --- a/docs/preprocessor/compiler-warnings-that-are-off-by-default.md +++ b/docs/preprocessor/compiler-warnings-that-are-off-by-default.md @@ -1,9 +1,8 @@ --- description: "Learn more about: Compiler warnings that are off by default" title: "Compiler warnings that are off by default" -ms.date: 12/01/2021 +ms.date: 01/18/2024 helpviewer_keywords: ["warnings, compiler", "cl.exe compiler, setting options"] -ms.assetid: 69809cfb-a38a-4035-b154-283a61938df8 --- # Compiler warnings that are off by default @@ -31,12 +30,14 @@ You can enable warnings that are normally off by default by using one of the fol ## Warnings that are off by default +### Visual Studio 2015 and later versions + The following warnings are turned off by default in Visual Studio 2015 and later versions: | Warning | Message | |--|--| -| [C4061](../error-messages/compiler-warnings/compiler-warning-level-4-c4061.md) (level 4) | enumerator '*identifier*' in a switch of enum '*enumeration*' is not explicitly handled by a case label | -| [C4062](../error-messages/compiler-warnings/compiler-warning-level-4-c4062.md) (level 4) | enumerator '*identifier*' in a switch of enum '*enumeration*' is not handled | +| [C4061](../error-messages/compiler-warnings/compiler-warning-level-4-c4061.md) (level 4) | enumerator '*identifier*' in a switch of enum '*enumeration*' is not explicitly handled by a case label. | +| [C4062](../error-messages/compiler-warnings/compiler-warning-level-4-c4062.md) (level 4) | enumerator '*identifier*' in a switch of enum '*enumeration*' is not handled. | | [C4165](../error-messages/compiler-warnings/compiler-warning-level-1-c4165.md) (level 1) | 'HRESULT' is being converted to 'bool'; are you sure this is what you want? | | [C4191](../error-messages/compiler-warnings/compiler-warning-level-3-c4191.md) (level 3) | '*operator*': unsafe conversion from '*type_of_expression*' to '*type_required*' | | [C4242](../error-messages/compiler-warnings/compiler-warning-level-4-c4242.md) (level 4) | '*identifier*': conversion from '*type1*' to '*type2*', possible loss of data | @@ -55,13 +56,13 @@ The following warnings are turned off by default in Visual Studio 2015 and later | [C4355](../error-messages/compiler-warnings/compiler-warning-c4355.md) | 'this' : used in base member initializer list | | [C4365](../error-messages/compiler-warnings/compiler-warning-level-4-c4365.md) (level 4) | '*action*': conversion from '*type_1*' to '*type_2*', signed/unsigned mismatch | | C4370 (level 3) | layout of class has changed from a previous version of the compiler due to better packing | -| [C4371](../error-messages/compiler-warnings/c4371.md) (level 3) | '*classname*': layout of class may have changed from a previous version of the compiler due to better packing of member '*member*' | +| [C4371](../error-messages/compiler-warnings/c4371.md) (level 3) | '*class-name*': layout of class may have changed from a previous version of the compiler due to better packing of member '*member*' | | [C4388](../error-messages/compiler-warnings/c4388.md) (level 4) | signed/unsigned mismatch | | [C4412](../error-messages/compiler-warnings/compiler-warning-level-2-c4412.md) (level 2) | '*function*': function signature contains type '*type*'; C++ objects are unsafe to pass between pure code and mixed or native | | C4426 (level 1) | optimization flags changed after including header, may be due to #pragma optimize() 14.1 | -| [C4435](../error-messages/compiler-warnings/compiler-warning-level-4-c4435.md) (level 4) | '*class1*' : Object layout under /vd2 will change due to virtual base '*class2*' | -| [C4437](../error-messages/compiler-warnings/compiler-warning-level-4-c4437.md) (level 4) | dynamic_cast from virtual base '*class1*' to '*class2*' could fail in some contexts | -| C4444 (level 3) | top level '__unaligned' is not implemented in this context | +| [C4435](../error-messages/compiler-warnings/compiler-warning-level-4-c4435.md) (level 4) | '*class1*' : Object layout under /vd2 will change due to virtual base '*class2*'. | +| [C4437](../error-messages/compiler-warnings/compiler-warning-level-4-c4437.md) (level 4) | dynamic_cast from virtual base '*class1*' to '*class2*' could fail in some contexts. | +| C4444 (level 3) | top level '__unaligned' is not implemented in this context. | | [C4464](../error-messages/compiler-warnings/compiler-warning-level-4-c4464.md) (level 4) | relative include path contains '..' | | [C4471](../error-messages/compiler-warnings/compiler-warning-level-4-c4471.md) (level 4) | a forward declaration of an unscoped enumeration must have an underlying type (int assumed) Perm | | C4472 (level 1) | '*identifier*' is a native enum: add an access specifier (private/public) to declare a managed enum | @@ -83,7 +84,7 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C4588 (level 1) | '*anonymous_structure*': behavior change: destructor is no longer implicitly called | | [C4596](../error-messages/compiler-warnings/c4596.md) (level 4) | '*identifier*': illegal qualified name in member declaration 14.3 Perm | | C4598 (level 1 and level 3) | '#include "*header*"': header number *header-number* in the precompiled header does not match current compilation at that position 14.3 | -| C4599 (level 3) | '*option* *path*': command-line argument number *number* does not match pre-compiled header 14.3 | +| C4599 (level 3) | '*option* *path*': command-line argument number *arg_number* does not match pre-compiled header 14.3 | | C4605 (level 1) | '/D*macro*' specified on current command line, but was not specified when precompiled header was built | | [C4608](../error-messages/compiler-warnings/compiler-warning-level-3-c4608.md) (level 3) | '*union_member*' has already been initialized by another union member in the initializer list, '*union_member*' Perm | | [C4619](../error-messages/compiler-warnings/compiler-warning-level-3-c4619.md) (level 3) | #pragma warning: there is no warning number '*number*' | @@ -96,12 +97,12 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C4647 (level 3) | behavior change: __is_pod(*type*) has different value in previous versions | | C4654 (level 4) | Code placed before include of precompiled header line will be ignored. Add code to precompiled header. 14.1 | | [C4668](../error-messages/compiler-warnings/compiler-warning-level-4-c4668.md) (level 4) | '*symbol*' is not defined as a preprocessor macro, replacing with '0' for '*directives*' | -| [C4682](../error-messages/compiler-warnings/compiler-warning-level-4-c4682.md) (level 4) | '*symbol*' : no directional parameter attribute specified, defaulting to [in] | +| [C4682](../error-messages/compiler-warnings/compiler-warning-level-4-c4682.md) (level 4) | '*symbol*' : no directional parameter attribute specified, defaulting to \[in] | | [C4686](../error-messages/compiler-warnings/compiler-warning-level-3-c4686.md) (level 3) | '*user-defined type*': possible change in behavior, change in UDT return calling convention | | [C4692](../error-messages/compiler-warnings/compiler-warning-level-1-c4692.md) (level 1) | '*function*': signature of non-private member contains assembly private native type '*native_type*' | | [C4710](../error-messages/compiler-warnings/compiler-warning-level-4-c4710.md) (level 4) | '*function*': function not inlined | | [C4738](../error-messages/compiler-warnings/compiler-warning-level-3-c4738.md) (level 3) | storing 32-bit float result in memory, possible loss of performance | -| [C4746](../error-messages/compiler-warnings/compiler-warning-c4746.md) | volatile access of '*expression*' is subject to /volatile:\ setting; consider using __iso_volatile_load/store intrinsic functions | +| [C4746](../error-messages/compiler-warnings/compiler-warning-c4746.md) | volatile access of '*expression*' is subject to /volatile:\ setting; consider using __iso_volatile_load/store intrinsic functions | | C4749 (level 4) | conditionally supported: offsetof applied to non-standard-layout type '*type*' | | C4767 (level 4) | section name '*symbol*' is longer than 8 characters and will be truncated by the linker | | C4774 (level 4) | '*string*' : format string expected in argument *number* is not a string literal | @@ -111,11 +112,11 @@ The following warnings are turned off by default in Visual Studio 2015 and later | [C4820](../error-messages/compiler-warnings/compiler-warning-level-4-c4820.md) (level 4) | '*bytes*' bytes padding added after construct '*member_name*' | | [C4822](../error-messages/compiler-warnings/compiler-warning-level-1-c4822.md) (level 1) | '*member*': local class member function does not have a body | | C4826 (level 2) | Conversion from '*type1*' to '*type2*' is sign-extended. This may cause unexpected runtime behavior. | -| C4837 (level 4) | trigraph detected: '??*character*' replaced by '*character*' | +| C4837 (level 4) | trigraph detected: '`??`*character*' replaced by '*character*' | | [C4841](../error-messages/compiler-warnings/c4841.md) (level 4) | non-standard extension used: compound member designator used in offsetof | | C4842 (level 4) | the result of 'offsetof' applied to a type using multiple inheritance is not guaranteed to be consistent between compiler releases | | [C4866](../error-messages/compiler-warnings/c4866.md) (level 4) | '*file*(*line-number*)' compiler may not enforce left-to-right evaluation order for call to *operator* | -| [C4868](../error-messages/compiler-warnings/compiler-warning-c4868.md) (level 4) | '_file_(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| [C4868](../error-messages/compiler-warnings/compiler-warning-c4868.md) (level 4) | '*file*(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | | [C4905](../error-messages/compiler-warnings/compiler-warning-level-1-c4905.md) (level 1) | wide string literal cast to 'LPSTR' | | [C4906](../error-messages/compiler-warnings/compiler-warning-level-1-c4906.md) (level 1) | string literal cast to 'LPWSTR' | | [C4917](../error-messages/compiler-warnings/compiler-warning-level-1-c4917.md) (level 1) | '*declarator*': a GUID can only be associated with a class, interface, or namespace | @@ -135,15 +136,29 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C5029 (level 4) | nonstandard extension used: alignment attributes in C++ apply to variables, data members and tag types only | | C5031 (level 4) | #pragma warning(pop): likely mismatch, popping warning state pushed in different file 14.1 | | C5032 (level 4) | detected #pragma warning(push) with no corresponding #pragma warning(pop) 14.1 | + +### Visual Studio 2017 and later versions + +The following warnings are turned off by default in Visual Studio 2017 and later versions: + +| Warning | Message | +|--|--| | C5034 | use of intrinsic '*intrinsic*' causes function *function-name* to be compiled as guest code 15.3 | | C5035 | use of feature '*feature*' causes function *function-name* to be compiled as guest code 15.3 | | C5036 (level 1) | varargs function pointer conversion when compiling with /hybrid:x86arm64 '*type1*' to '*type2*' 15.3 | | [C5038](../error-messages/compiler-warnings/c5038.md) (level 4) | data member '*member1*' will be initialized after data member '*member2*' 15.3 | -| C5039 (level 4) | '*function*': pointer or reference to potentially throwing function passed to extern C function under -EHc. Undefined behavior may occur if this function throws an exception. 15.5 | +| C5039 (level 4) | '*function*': pointer or reference to potentially throwing function passed to extern C function under `-EHc`. Undefined behavior may occur if this function throws an exception. 15.5 | | C5041 (level 4) | '*member-name*': out-of-line definition for constexpr static data member is not needed and is deprecated in C++17. 15.2 | | C5042 (level 3) | '*function*': function declarations at block scope cannot be specified 'inline' in standard C++; remove 'inline' specifier 15.5 | | [C5045](../error-messages/compiler-warnings/c5045.md) | Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified 15.7 | -| C5052 (level 3) | Keyword '*keyword-name*' was introduced in C++*version* and requires use of the '*option*' command-line option` 16.1 | + +### Visual Studio 2019 and later versions + +The following warnings are turned off by default in Visual Studio 2019 and later versions: + +| Warning | Message | +|--|--| +| C5052 (level 3) | Keyword '*keyword-name*' was introduced in C++ *version* and requires use of the '*option*' command-line option` 16.1 | | C5204 (level 3) | A class with virtual functions has non-virtual trivial destructor. 16.5 | | C5214 (level 4) | applying '*keyword*' to an operand with a volatile qualified type is deprecated in C++20 16.7 | | C5215 (level 4) | '*function-parameter*' a function parameter with a volatile qualified type is deprecated in C++20 16.7 | @@ -152,16 +167,31 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C5219 (level 2) | implicit conversion from '*type-1*' to '*type-2*', possible loss of data 16.7 | | C5220 (level 4) | '*member*': a non-static data member with a volatile qualified type no longer implies that
compiler generated copy/move constructors and copy/move assignment operators are not trivial 16.7 | | C5233 (level 4) | explicit lambda capture '*identifier*' is not used 16.10 | -| C5240 (level 4) | '*attribute-name*': attribute is ignored in this syntactic position 16.10 | +| [C5240 (level 4)](../error-messages/compiler-warnings/c5240.md) | '*attribute-name*': attribute is ignored in this syntactic position 16.10 | | [C5243 (level 1)](../error-messages/compiler-warnings/c5247.md) | '*type-name*': using incomplete class '*class-name*' can cause potential one definition rule violation due to ABI limitation 16.10 | | C5245 (level 4) | '*function*': unreferenced function with internal linkage has been removed | | C5246 (level 1) | '*member*': the initialization of a subobject should be wrapped in braces 16.10 | | [C5247 (level 1)](../error-messages/compiler-warnings/c5247.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior 16.11 | | [C5248 (level 1)](../error-messages/compiler-warnings/c5248.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Variable manually put into the section may be optimized out and its order relative to compiler generated dynamic initializers is unspecified 16.11 | + +### Visual Studio 2022 and later versions + +The following warnings are turned off by default in Visual Studio 2022 and later versions: + +| Warning | Message | +|--|--| | C5249 (level 1) | '*bitfield*' of type '*enumeration_name*' has named enumerators with values that cannot be represented in the given bit field width of '*bitfield_width*'. 17.0 | | C5250 (level 3) | '*function_name*': intrinsic function not declared. 17.0 | | C5251 (level 4) | *segment-name* changed after including header 17.1 | | C5254 (level 4) | language feature 'terse static assert' requires compiler flag '/std:c++17' 17.1 | +| C5256 (level 1) | '*enumeration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration 17.2 | +| C5258 (level 4) | explicit capture of '*symbol*' is not required for this use 17.2 | +| C5259 (level 4) | '*specialized-type*': explicit specialization requires '`template <>`' 17.3 | +| [C5262](../error-messages/compiler-warnings/c5262.md) (level 1, error) | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases 17.4 | +| C5263 (level 4) | calling '`std::move`' on a temporary object prevents copy elision 17.4 | +| C5264 (level 4) | '*variable-name*': 'const' variable is not used 17.4 | +| [C5266 (level 4)](../error-messages/compiler-warnings/compiler-warning-level-4-c5266.md) | 'const' qualifier on return type has no effect 17.6 | +| [C5267](../error-messages/compiler-warnings/c5267.md) (level 4) | definition of implicit copy constructor/assignment operator for '*type*' is deprecated because it has a user-provided assignment operator/copy constructor 17.7 | 14.1 This warning is available starting in Visual Studio 2015 Update 1.\ 14.3 This warning is available starting in Visual Studio 2015 Update 3.\ @@ -177,6 +207,12 @@ The following warnings are turned off by default in Visual Studio 2015 and later 16.11 This warning is available starting in Visual Studio 2019 version 16.11.\ 17.0 This warning is available starting in Visual Studio 2022 version 17.0.\ 17.1 This warning is available starting in Visual Studio 2022 version 17.1.\ +17.2 This warning is available starting in Visual Studio 2022 version 17.2.\ +17.3 This warning is available starting in Visual Studio 2022 version 17.3.\ +17.4 This warning is available starting in Visual Studio 2022 version 17.4.\ +17.5 This warning is available starting in Visual Studio 2022 version 17.5.\ +17.6 This warning is available starting in Visual Studio 2022 version 17.6.\ +17.7 This warning is available starting in Visual Studio 2022 version 17.7.\ Perm This warning is off unless the [`/permissive-`](../build/reference/permissive-standards-conformance.md) compiler option is set. ## Warnings off by default in earlier versions diff --git a/docs/preprocessor/execution-character-set.md b/docs/preprocessor/execution-character-set.md index be36d8c4bc..404d492526 100644 --- a/docs/preprocessor/execution-character-set.md +++ b/docs/preprocessor/execution-character-set.md @@ -12,25 +12,25 @@ Specifies the execution character set used for string and character literals. Th ## Syntax -> **`#pragma execution_character_set(`** "*target*" **`)`** +> **`#pragma execution_character_set(`** "*`target`*" **`)`** ### Parameters -*target*\ -Specifies the target execution character set. Currently the only target execution set supported is "utf-8". +*`target`*\ +Specifies the target execution character set. Currently the only target execution set supported is `"utf-8"`. ## Remarks -This compiler directive is obsolete starting in Visual Studio 2015 Update 2. We recommend that you use the **`/execution-charset:utf-8`** or **`/utf-8`** compiler options together with using the `u8` prefix on narrow character and string literals that contain extended characters. For more information about the `u8` prefix, see [String and character literals](../cpp/string-and-character-literals-cpp.md). For more information about the compiler options, see [`/execution-charset` (Set execution character set)](../build/reference/execution-charset-set-execution-character-set.md) and [`/utf-8` (Set source and executable character sets to UTF-8)](../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md). +This compiler directive is obsolete in Visual Studio 2015 Update 2 and later versions. We recommend that you use the **`/execution-charset:utf-8`** or **`/utf-8`** compiler options together with the `u8` prefix on narrow character and string literals that contain extended characters. For more information about the `u8` prefix, see [String and character literals](../cpp/string-and-character-literals-cpp.md). For more information about the compiler options, see [`/execution-charset` (Set execution character set)](../build/reference/execution-charset-set-execution-character-set.md) and [`/utf-8` (Set source and execution character sets to UTF-8)](../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md). -The `#pragma execution_character_set("utf-8")` directive tells the compiler to encode narrow character and narrow string literals in your source code as UTF-8 in the executable. This output encoding is independent of the source file encoding used. +The `#pragma execution_character_set("utf-8")` directive tells the compiler to encode narrow character and narrow string literals in your source code as UTF-8 in the executable. This output encoding is independent of how the source file is encoded. -By default, the compiler encodes narrow characters and narrow strings by using the current code page as the execution character set. It means that Unicode or DBCS characters outside the range of the current code page get converted to the default replacement character in the output. Unicode and DBCS characters are truncated to their low-order byte, which is almost never what you intend. You can specify UTF-8 encoding for literals in the source file by using a `u8` prefix. The compiler passes these UTF-8 encoded strings to the output unchanged. Narrow character literals prefixed by using u8 must fit in a byte, or they're truncated on output. +By default, when the compiler encodes narrow characters and narrow strings, it uses the current code page as the execution character set. Unicode or DBCS characters outside the range of the current code page get converted to the default replacement character in the output. Unicode and DBCS characters are truncated to their low-order byte, which is almost never what you intend. To specify the UTF-8 encoding for literals in the source file, use a `u8` prefix. The compiler passes these UTF-8 encoded strings to the output unchanged. Narrow character literals prefixed by `u8` must fit in a byte, or they're truncated on output. -By default, Visual Studio uses the current code page as the source character set used to interpret your source code for output. When a file is read in, Visual Studio interprets it according to the current code page unless the file code page was set, or unless a byte-order mark (BOM) or UTF-16 characters are detected at the beginning of the file. You can't set UTF-8 as the current code page in some versions of Windows. When the automatic detection finds source files encoded as UTF-8 without a BOM in those versions, Visual Studio assumes they're encoded by using the current code page. Characters in the source file that are outside the range of the specified or automatically detected code page can cause compiler warnings and errors. +By default, Visual Studio uses the current code page as the source character set used to interpret your source code for output. When a file is read in, Visual Studio interprets it according to the current code page unless the file has a code page set. Or, unless a byte-order mark (BOM) or UTF-16 characters are detected at the beginning of the file. You can't set UTF-8 as the current code page in some versions of Windows. When the automatic detection finds UTF-8 encoded source files without a BOM in those versions, Visual Studio assumes they're encoded in the current code page. Characters in the source file that are outside the range of the specified or automatically detected code page can cause compiler warnings and errors. ## See also [Pragma directives and the `__pragma` and `_Pragma` keywords](./pragma-directives-and-the-pragma-keyword.md)\ [`/execution-charset` (Set execution character set)](../build/reference/execution-charset-set-execution-character-set.md)\ -[`/utf-8` (Set source and executable character sets to UTF-8)](../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md) +[`/utf-8` (Set source and execution character sets to UTF-8)](../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md) diff --git a/docs/preprocessor/fp-contract.md b/docs/preprocessor/fp-contract.md index bc28e550f3..48bbc44700 100644 --- a/docs/preprocessor/fp-contract.md +++ b/docs/preprocessor/fp-contract.md @@ -1,7 +1,7 @@ --- description: "Learn more about the fp_contract pragma directive in Microsoft C/C++" title: "fp_contract pragma" -ms.date: 08/10/2021 +ms.date: 03/22/2022 f1_keywords: ["vc-pragma.fp_contract", "fp_contract_CPP"] helpviewer_keywords: ["pragma, fp_contract", "fp_contract pragma"] no-loc: ["pragma"] @@ -18,17 +18,15 @@ Determines whether floating-point contraction takes place. A floating-point cont ::: moniker range=">msvc-160" -By default, **`fp_contract`** is **`off`**, which tells the compiler to preserve individual floating-point instructions. Set **`fp_contract`** to **`on`** to use floating-point contraction instructions where possible. This behavior is new in Visual Studio 2022. In previous compiler versions **`fp_contract`** defaulted to **`on`**. +When you use the default compiler options, **`fp_contract`** is **`off`**, which tells the compiler to preserve individual floating-point instructions. Set **`fp_contract`** to **`on`** to use floating-point contraction instructions where possible. This behavior is new in Visual Studio 2022 version 17.0. In previous compiler versions, **`fp_contract`** defaulted to **`on`**. ::: moniker-end ::: moniker range="<=msvc-160" -By default, **`fp_contract`** is **`on`**. This tells the compiler to use floating-point contraction instructions where possible. Set **`fp_contract`** to **`off`** to preserve individual floating-point instructions. +When you use the default compiler options, **`fp_contract`** is **`on`**. This setting tells the compiler to use floating-point contraction instructions where possible. Set **`fp_contract`** to **`off`** to preserve individual floating-point instructions. In Visual Studio 2022 version 17.0 and later, **`fp_contract`** defaults to **`off`**. ::: moniker-end -By default, **`fp_contract`** is **`off`**. This tells the compiler to preserve individual floating-point instructions. Set **`fp_contract`** to **`on`** to use floating-point contraction instructions where possible. - For more information on floating-point behavior, see [`/fp` (Specify floating-point behavior)](../build/reference/fp-specify-floating-point-behavior.md). Other floating-point pragma directives include: @@ -39,12 +37,11 @@ Other floating-point pragma directives include: ## Example -The code generated from this sample does not use a fused-multiply-add instruction even when it is available on the target processor. If you comment out `#pragma fp_contract (off)`, the generated code may use a fused-multiply-add instruction if it is available. +The **`/fp:fast`** compiler option enables contractions by default, but the `#pragma fp_contract (off)` directive in this example turns them off. The code generated from this sample won't use a fused-multiply-add instruction even when it's available on the target processor. If you comment out `#pragma fp_contract (off)`, the generated code may use a fused-multiply-add instruction if it's available. ```cpp // pragma_directive_fp_contract.cpp -// on x86 and x64 compile with: /O2 /fp:fast /arch:AVX2 -// other platforms compile with: /O2 +// On x86 and x64 compile with: /O2 /fp:fast /arch:AVX2 #include diff --git a/docs/preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md b/docs/preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md index 894ce0562f..f05009b7f6 100644 --- a/docs/preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md +++ b/docs/preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md @@ -13,31 +13,31 @@ The **#if** directive, with the **#elif**, **#else**, and **#endif** directives, ## Grammar *conditional* :\ -    *if-part elif-parts*opt *else-part*opt *endif-line* + *if-part elif-parts*opt *else-part*opt *endif-line* *if-part* :\ -    *if-line text* + *if-line text* *if-line* :\ -    **#if** *constant-expression*\ -    **#ifdef** *identifier*\ -    **#ifndef** *identifier* + **#if** *constant-expression*\ + **#ifdef** *identifier*\ + **#ifndef** *identifier* *elif-parts* :\ -    *elif-line text*\ -    *elif-parts elif-line text* + *elif-line text*\ + *elif-parts elif-line text* *elif-line* :\ -    **#elif** *constant-expression* + **#elif** *constant-expression* *else-part* :\ -    *else-line text* + *else-line text* *else-line* :\ -    **#else** + **#else** *endif-line* :\ -    **#endif** + **#endif** ## Remarks diff --git a/docs/preprocessor/hash-import-directive-cpp.md b/docs/preprocessor/hash-import-directive-cpp.md index 82e8088116..83b1bc8afb 100644 --- a/docs/preprocessor/hash-import-directive-cpp.md +++ b/docs/preprocessor/hash-import-directive-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: #import directive (C++)" title: "#import directive (C++)" +description: "Learn more about: #import directive (C++)" ms.date: "08/29/2019" f1_keywords: ["#import"] helpviewer_keywords: [".tlh files", "#import directive", "import directive (#import)", "tlh files", "tlbid switch", "preprocessor, directives", "COM, type library header file"] -ms.assetid: 787d1112-e543-40d7-ab15-a63d43f4030a --- # #import directive (C++) @@ -130,7 +129,7 @@ The primary type library header file consists of seven sections: Type `IMyInterfacePtr` can then be used in place of the raw interface pointer `IMyInterface*`. Consequently, there's no need to call the various `IUnknown` member functions -- Typeinfo declarations: Primarily consists of class definitions and other items exposing the individual typeinfo items returned by `ITypeLib:GetTypeInfo`. In this section, each typeinfo from the type library is reflected in the header in a form dependent on the `TYPEKIND` information. +- Typeinfo declarations: Primarily consists of class definitions and other items exposing the individual typeinfo items returned by `ITypeLib::GetTypeInfo`. In this section, each typeinfo from the type library is reflected in the header in a form dependent on the `TYPEKIND` information. - Optional old-style GUID definition: Contains initializations of the named GUID constants. These names have the form `CLSID_CoClass` and `IID_Interface`, similar to the ones generated by the MIDL compiler. diff --git a/docs/preprocessor/hash-include-directive-c-cpp.md b/docs/preprocessor/hash-include-directive-c-cpp.md index 8e27ea2305..f448f61110 100644 --- a/docs/preprocessor/hash-include-directive-c-cpp.md +++ b/docs/preprocessor/hash-include-directive-c-cpp.md @@ -37,7 +37,7 @@ Include files can be *nested*: An **`#include`** directive can appear in a file When include files are nested and when compiling occurs on the command line, directory searching begins in the directory of the parent file. Then it proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source that's currently being processed. If the file isn't found, the search moves to directories that are specified by the [`/I` (Additional include directories)](../build/reference/i-additional-include-directories.md) compiler option. Finally, the directories that are specified by the `INCLUDE` environment variable are searched. -Within the Visual Studio development environment, the `INCLUDE` environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see [Include Directories](../build/reference/vcpp-directories-property-page.md#directory-types) and [Additional Include Directories](../build/reference/c-cpp-prop-page.md#additional-include-directories). +Within the Visual Studio development environment, the `INCLUDE` environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see [Include Directories](../build/reference/vcpp-directories-property-page.md#general) and [Additional Include Directories](../build/reference/c-cpp-prop-page.md#additional-include-directories). This example shows file inclusion by using angle brackets: diff --git a/docs/preprocessor/hash-line-directive-c-cpp.md b/docs/preprocessor/hash-line-directive-c-cpp.md index 7af5a02129..4e1a8b2256 100644 --- a/docs/preprocessor/hash-line-directive-c-cpp.md +++ b/docs/preprocessor/hash-line-directive-c-cpp.md @@ -18,7 +18,7 @@ The **#line** directive tells the preprocessor to set the compiler's reported va The compiler uses the line number and optional filename to refer to errors that it finds during compilation. The line number usually refers to the current input line, and the filename refers to the current input file. The line number is incremented after each line is processed. -The *digit-sequence* value can be any integer constant. Macro replacement can be used on the preprocessing tokens, but the result must evaluate to the correct syntax. The *filename* can be any combination of characters and must be enclosed in double quotation marks (`" "`). If *filename* is omitted, the previous filename remains unchanged. +The *digit-sequence* value can be any integer constant within the range from 0 to 2147483647, inclusive. Macro replacement can be used on the preprocessing tokens, but the result must evaluate to the correct syntax. The *filename* can be any combination of characters and must be enclosed in double quotation marks (`" "`). If *filename* is omitted, the previous filename remains unchanged. You can alter the source line number and filename by writing a **`#line`** directive. The **`#line`** directive sets the value for the line that immediately follows the directive in the source file. The translator uses the line number and filename to determine the values of the predefined macros `__FILE__` and `__LINE__`. You can use these macros to insert self-descriptive error messages into the program text. For more information on these predefined macros, see [Predefined macros](../preprocessor/predefined-macros.md). diff --git a/docs/preprocessor/hash-using-directive-cpp.md b/docs/preprocessor/hash-using-directive-cpp.md index 0100dd18c8..a417e3cdc8 100644 --- a/docs/preprocessor/hash-using-directive-cpp.md +++ b/docs/preprocessor/hash-using-directive-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: #using directive (C++/CLI)" title: "#using directive (C++/CLI)" -ms.date: "08/29/2019" +ms.date: 06/29/2022 f1_keywords: ["friend_as_cpp", "#using", "friend_as", "#using_cpp"] helpviewer_keywords: ["using directive (#using)", "#using directive", "LIBPATH environment variable", "preprocessor, directives"] ms.assetid: 870b15e5-f361-40a8-ba1c-c57d75c8809a @@ -63,12 +63,16 @@ The compiler searches for references along the following path: You can build an assembly that references a second assembly that itself references a third assembly. You only have to explicitly reference the third assembly from the first one if you explicitly use one of its types. +Source file `using_assembly_A.cpp`: + ```cpp // using_assembly_A.cpp // compile with: /clr /LD public ref class A {}; ``` +Source file `using_assembly_B.cpp`: + ```cpp // using_assembly_B.cpp // compile with: /clr /LD @@ -80,7 +84,7 @@ public: }; ``` -In the following sample, there's the compiler doesn't report an error about referencing *using_assembly_A.dll*, because the program doesn't use any of the types defined in *using_assembly_A.cpp*. +In the following sample, the compiler doesn't report an error about referencing *using_assembly_A.dll*, because the program doesn't use any of the types defined in *using_assembly_A.cpp*. ```cpp // using_assembly_C.cpp diff --git a/docs/preprocessor/intrinsic.md b/docs/preprocessor/intrinsic.md index f03f0cc815..8e5aa4f007 100644 --- a/docs/preprocessor/intrinsic.md +++ b/docs/preprocessor/intrinsic.md @@ -29,28 +29,28 @@ The following functions have intrinsic forms, and the intrinsic forms are used w [`_enable`](../intrinsics/enable.md)\ [`fabs`](../c-runtime-library/reference/fabs-fabsf-fabsl.md)\ [`_inp`](../c-runtime-library/inp-inpw-inpd.md)\ - [`_inpw`](../c-runtime-library/inp-inpw-inpd.md)\ + [`_inpw`](../c-runtime-library/inp-inpw-inpd.md) :::column-end::: :::column span=""::: [`labs`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)\ [`_lrotl`](../c-runtime-library/reference/lrotl-lrotr.md)\ [`_lrotr`](../c-runtime-library/reference/lrotl-lrotr.md)\ [`memcmp`](../c-runtime-library/reference/memcmp-wmemcmp.md)\ - [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md)\ + [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) :::column-end::: :::column span=""::: [`memset`](../c-runtime-library/reference/memset-wmemset.md)\ [`_outp`](../c-runtime-library/outp-outpw-outpd.md)\ [`_outpw`](../c-runtime-library/outp-outpw-outpd.md)\ [`_rotl`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)\ - [`_rotr`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)\ + [`_rotr`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md) :::column-end::: :::column span=""::: [`strcat`](../c-runtime-library/reference/strcat-wcscat-mbscat.md)\ [`strcmp`](../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md)\ [`strcpy`](../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md)\ [`strlen`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)\ - [`_strset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ + [`_strset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) :::column-end::: :::row-end::: @@ -84,18 +84,18 @@ These floating-point functions don't have true intrinsic forms. Instead, they ha :::row::: :::column span=""::: [`acos`](../c-runtime-library/reference/acos-acosf-acosl.md)\ - [`asin`](../c-runtime-library/reference/asin-asinf-asinl.md)\ + [`asin`](../c-runtime-library/reference/asin-asinf-asinl.md) :::column-end::: :::column span=""::: [`cosh`](../c-runtime-library/reference/cosh-coshf-coshl.md)\ - [`fmod`](../c-runtime-library/reference/fmod-fmodf.md)\ + [`fmod`](../c-runtime-library/reference/fmod-fmodf.md) :::column-end::: :::column span=""::: [`pow`](../c-runtime-library/reference/pow-powf-powl.md)\ - [`sinh`](../c-runtime-library/reference/sinh-sinhf-sinhl.md)\ + [`sinh`](../c-runtime-library/reference/sinh-sinhf-sinhl.md) :::column-end::: :::column span=""::: - [`tanh`](../c-runtime-library/reference/tanh-tanhf-tanhl.md)\ + [`tanh`](../c-runtime-library/reference/tanh-tanhf-tanhl.md) :::column-end::: :::row-end::: @@ -105,19 +105,19 @@ These floating-point functions have true intrinsic forms when you specify [`/Oi` :::column span=""::: [`atan`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`atan2`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ - [`cos`](../c-runtime-library/reference/cos-cosf-cosl.md)\ + [`cos`](../c-runtime-library/reference/cos-cosf-cosl.md) :::column-end::: :::column span=""::: [`exp`](../c-runtime-library/reference/exp-expf.md)\ - [`log`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ + [`log`](../c-runtime-library/reference/log-logf-log10-log10f.md) :::column-end::: :::column span=""::: [`log10`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ - [`sin`](../c-runtime-library/reference/sin-sinf-sinl.md)\ + [`sin`](../c-runtime-library/reference/sin-sinf-sinl.md) :::column-end::: :::column span=""::: [`sqrt`](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md)\ - [`tan`](../c-runtime-library/reference/tan-tanf-tanl.md)\ + [`tan`](../c-runtime-library/reference/tan-tanf-tanl.md) :::column-end::: :::row-end::: diff --git a/docs/preprocessor/message.md b/docs/preprocessor/message.md index 038997d72b..1eec0299a7 100644 --- a/docs/preprocessor/message.md +++ b/docs/preprocessor/message.md @@ -42,7 +42,7 @@ The following code fragment uses the **`message`** pragma to display messages du #define STRING2(x) #x #define STRING(x) STRING2(x) -#pragma message (__FILE__ "[" STRING(__LINE__) "]: test") +#pragma message (__FILE__ "(" STRING(__LINE__) "): test") #pragma message("") ``` diff --git a/docs/preprocessor/optimize.md b/docs/preprocessor/optimize.md index e51a40ac1f..ddcd04b833 100644 --- a/docs/preprocessor/optimize.md +++ b/docs/preprocessor/optimize.md @@ -24,7 +24,7 @@ The *optimization-list* can be zero or more of the parameters shown in the follo | Parameter(s) | Type of optimization | |--------------------|--------------------------| -| **`g`** | Enable global optimizations. | +| **`g`** | Enable global optimizations. Deprecated. For more information, see [`/Og` (Global optimizations)](../build/reference/og-global-optimizations.md). | | **`s`** or **`t`** | Specify short or fast sequences of machine code. | | **`y`** | Generate frame pointers on the program stack. | diff --git a/docs/preprocessor/pack.md b/docs/preprocessor/pack.md index e748047b17..6c153a8191 100644 --- a/docs/preprocessor/pack.md +++ b/docs/preprocessor/pack.md @@ -38,7 +38,7 @@ The statement `#pragma pack (pop, r1, 2)` is equivalent to `#pragma pack (pop, r ## Remarks -To *pack* a class is to place its members directly after each other in memory. It can mean that some or all members can be aligned on a boundary smaller than the default alignment of the target architecture. **`pack`** gives control at the data-declaration level. It differs from compiler option [`/Zp`](../build/reference/zp-struct-member-alignment.md), which only provides module-level control. **pack** takes effect at the first **`struct`**, **`union`**, or **`class`** declaration after the pragma is seen. **`pack`** has no effect on definitions. Calling **`pack`** with no arguments sets *`n`* to the value set in the compiler option **`/Zp`**. If the compiler option isn't set, the default value is 8 for x86, ARM, and ARM64. The default is 16 for x64 native. +To *pack* a class is to place its members directly after each other in memory. It can mean that some or all members can be aligned on a boundary smaller than the default alignment of the target architecture. **`pack`** gives control at the data-declaration level. It differs from compiler option [`/Zp`](../build/reference/zp-struct-member-alignment.md), which only provides module-level control. **pack** takes effect at the first **`struct`**, **`union`**, or **`class`** declaration after the pragma is seen. **`pack`** has no effect on definitions. Calling **`pack`** with no arguments sets *`n`* to the value set in the compiler option **`/Zp`**. If the compiler option isn't set, the default value is 8 for x86, ARM, and ARM64. The default is 16 for x64 native and ARM64EC. If you change the alignment of a structure, it may not use as much space in memory. However, you may see a loss of performance or even get a hardware-generated exception for unaligned access. You can modify this exception behavior by using [`SetErrorMode`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode). @@ -50,7 +50,7 @@ For more information about how to modify alignment, see these articles: - [`__unaligned`](../cpp/unaligned.md) -- [Examples of structure alignment](../build/x64-software-conventions.md#examples-of-structure-alignment) (x64 specific) +- [x64 structure alignment examples](../build/x64-software-conventions.md#x64-structure-alignment-examples) > [!WARNING] > In Visual Studio 2015 and later you can use the standard **`alignas`** and **`alignof`** operators, which unlike **`__alignof`** and **`__declspec( align )`** are portable across compilers. The C++ standard doesn't address packing, so you must still use **`pack`** (or the corresponding extension on other compilers) to specify alignments smaller than the target architecture's word size. diff --git a/docs/preprocessor/pragma-directives-and-the-pragma-keyword.md b/docs/preprocessor/pragma-directives-and-the-pragma-keyword.md index d8332a3d26..23875dffa5 100644 --- a/docs/preprocessor/pragma-directives-and-the-pragma-keyword.md +++ b/docs/preprocessor/pragma-directives-and-the-pragma-keyword.md @@ -1,19 +1,19 @@ --- title: "Pragma directives and the __pragma and _Pragma keywords" description: "Describes the pragma directives available in Microsoft Visual C and C++ (MSVC)" -ms.date: "01/19/2021" +ms.date: 03/22/2022 f1_keywords: ["#pragma", "_Pragma", "__pragma"] helpviewer_keywords: ["#pragma directives, C/C++", "__pragma keyword", "_Pragma keyword", "pragma directives, C/C++", "pragmas, C/C++", "preprocessor", "pragmas", "preprocessor, pragmas", "pragma directives (#pragma)"] no-loc: ["pragma"] --- # Pragma directives and the `__pragma` and `_Pragma` keywords -Pragma directives specify machine-specific or operating system-specific compiler features. The **`__pragma`** keyword, which is specific to the Microsoft compiler, enables you to code pragma directives within macro definitions. The standard **`_Pragma`** preprocessor operator was introduced in C99 and adopted by C++11. +Pragma directives specify machine-specific or operating system-specific compiler features. A line that starts with `#pragma` specifies a pragma directive. The Microsoft-specific **`__pragma`** keyword enables you to code pragma directives within macro definitions. The standard **`_Pragma`** preprocessor operator, introduced in C99 and adopted by C++11, is similar. ## Syntax > **`#pragma`** *token-string*\ -> **`__pragma(`** *token-string* **`)`** // two leading underscores - Microsoft specific extension\ +> **`__pragma(`** *token-string* **`)`** // two leading underscores - Microsoft-specific extension\ > **`_Pragma(`** *string-literal* **`)`** // C99 ## Remarks @@ -142,7 +142,7 @@ Quotation marks and back-slashes should be escaped, as shown above. A pragma str The following code example demonstrates how the **`_Pragma`** keyword could be used in an assert-like macro. It creates a pragma directive that suppresses a warning when the condition expression happens to be constant. -The macro definition uses the `do`-`while(0)` idiom for multi-statement macros so that it can be used as though it were one statement. For more information, see [C multi-line macro](https://stackoverflow.com/questions/1067226/c-multi-line-macro-do-while0-vs-scope-block) on Stack Overflow. The **`_Pragma`** statement only applies to the line of code that follows it. +The macro definition uses the `do ... while(0)` idiom for multi-statement macros so that it can be used as though it were one statement. For more information, see [C multi-line macro](https://stackoverflow.com/questions/1067226/c-multi-line-macro-do-while0-vs-scope-block) on Stack Overflow. The **`_Pragma`** statement in the example only applies to the line of code that follows it. ```C // Compile with /W4 diff --git a/docs/preprocessor/predefined-macros.md b/docs/preprocessor/predefined-macros.md index 90c6fd4b34..40cceea515 100644 --- a/docs/preprocessor/predefined-macros.md +++ b/docs/preprocessor/predefined-macros.md @@ -2,17 +2,19 @@ title: "Predefined macros" description: "Lists and describes the Microsoft C++ compiler predefined preprocessor macros." ms.custom: "update_every_version" -ms.date: 12/09/2021 -f1_keywords: ["_ATL_VER", "__ATOM__", "__AVX__", "__AVX2__", "__AVX512BW__", "__AVX512CD__", "__AVX512DQ__", "__AVX512F__", "__AVX512VL__", "_CHAR_UNSIGNED", "__CLR_VER", "_CONTROL_FLOW_GUARD", "__COUNTER__", "__cplusplus", "__cplusplus_cli", "__cplusplus_winrt", "_CPPRTTI", "_CPPUNWIND", "__DATE__", "_DEBUG", "_DLL", "__FILE__", "__FUNCDNAME__", "__FUNCSIG__", "__FUNCTION__", "_INTEGRAL_MAX_BITS", "_ISO_VOLATILE", "_KERNEL_MODE", "__LINE__", "_M_AMD64", "_M_ARM", "_M_ARM_ARMV7VE", "_M_ARM_FP", "_M_ARM64", "_M_CEE", "_M_CEE_PURE", "_M_CEE_SAFE", "_M_FP_EXCEPT", "_M_FP_FAST", "_M_FP_PRECISE", "_M_FP_STRICT", "_M_IX86", "_M_IX86_FP", "_M_X64", "_MANAGED", "_MFC_VER", "_MSC_BUILD", "_MSC_EXTENSIONS", "_MSC_FULL_VER", "_MSC_VER", "_MSVC_LANG", "__MSVC_RUNTIME_CHECKS", "_MT", "_NATIVE_WCHAR_T_DEFINED", "_NO_SIZED_DEALLOCATION", "_OPENMP", "_PREFAST_", "_RESUMABLE_FUNCTIONS_SUPPORTED", "_RTC_CONVERSION_CHECKS_ENABLED", "__SANITIZE_ADDRESS__", "__STDC__", "__STDC_HOSTED__", "__STDC_NO_ATOMICS__", "__STDC_NO_COMPLEX__", "__STDC_NO_THREADS__", "__STDC_NO_VLA__", "__STDC_VERSION__", "__STDCPP_THREADS__", "__TIME__", "__TIMESTAMP__", "__VA_ARGS__", "_VC_NODEFAULTLIB", "_WCHAR_T_DEFINED", "_WIN32", "_WIN64", "_WINRT_DLL"] -helpviewer_keywords: ["timestamps, preprocessor macro", "cl.exe compiler, version number", "version numbers, C/C++ compiler (cl.exe)", "macros, predefined C++", "preprocessor, macros", "predefined macros", "_ATL_VER macro", "__ATOM__ macro", "__AVX__ macro", "__AVX2__ macro", "__AVX512BW__ macro", "__AVX512CD__ macro", "__AVX512DQ__ macro", "__AVX512F__ macro", "__AVX512VL__ macro", "_CHAR_UNSIGNED macro", "__CLR_VER macro", "_CONTROL_FLOW_GUARD macro", "__COUNTER__ macro", "__cplusplus macro", "__cplusplus_cli macro", "__cplusplus_winrt macro", "_CPPRTTI macro", "_CPPUNWIND macro", "__DATE__ macro", "_DEBUG macro", "_DLL macro", "__FILE__ macro", "__FUNCDNAME__ macro", "__FUNCSIG__ macro", "__FUNCTION__ macro", "_INTEGRAL_MAX_BITS macro", "_ISO_VOLATILE macro", "_KERNEL_MODE macro", "__LINE__ macro", "_M_AMD64 macro", "_M_ARM macro", "_M_ARM_ARMV7VE macro", "_M_ARM_FP macro", "_M_ARM64 macro", "_M_CEE macro", "_M_CEE_PURE macro", "_M_CEE_SAFE macro", "_M_FP_EXCEPT macro", "_M_FP_FAST macro", "_M_FP_PRECISE macro", "_M_FP_STRICT macro", "_M_IX86 macro", "_M_IX86_FP macro", "_M_X64 macro", "_MANAGED macro", "_MFC_VER macro", "_MSC_BUILD macro", "_MSC_EXTENSIONS macro", "_MSC_FULL_VER macro", "_MSC_VER macro", "_MSVC_LANG macro", "__MSVC_RUNTIME_CHECKS macro", "_MT macro", "_NATIVE_WCHAR_T_DEFINED macro", "_NO_SIZED_DEALLOCATION macro", "_OPENMP macro", "_PREFAST_ macro", "_RESUMABLE_FUNCTIONS_SUPPORTED macro", "_RTC_CONVERSION_CHECKS_ENABLED macro", "__SANITIZE_ADDRESS__ macro", "__STDC__ macro", "__STDC_HOSTED__ macro", "__STDC_NO_ATOMICS__ macro", "__STDC_NO_COMPLEX__ macro", "__STDC_NO_THREADS__ macro", "__STDC_NO_VLA__ macro", "__STDC_VERSION__ macro", "__STDCPP_THREADS__ macro", "__TIME__ macro", "__TIMESTAMP__ macro", "__VA_ARGS__ macro", "_VC_NODEFAULTLIB macro", "_WCHAR_T_DEFINED macro", "_WIN32 macro", "_WIN64 macro", "_WINRT_DLL macro", "__func__ identifier"] +ms.date: 06/11/2024 +f1_keywords: ["__ARM_ARCH", "_ATL_VER", "__ATOM__", "__AVX__", "__AVX2__", "__AVX512BW__", "__AVX512CD__", "__AVX512DQ__", "__AVX512F__", "__AVX512VL__", "_CHAR_UNSIGNED", "__CLR_VER", "_CONTROL_FLOW_GUARD", "__COUNTER__", "__cplusplus", "__cplusplus_cli", "__cplusplus_winrt", "_CPPRTTI", "_CPPUNWIND", "__DATE__", "_DEBUG", "_DLL", "__FILE__", "__FUNCDNAME__", "__FUNCSIG__", "__FUNCTION__", "_INTEGRAL_MAX_BITS", "_ISO_VOLATILE", "_KERNEL_MODE", "__LINE__", "_M_AMD64", "_M_ARM", "_M_ARM_ARMV7VE", "_M_ARM_FP", "_M_ARM64", "_M_CEE", "_M_CEE_PURE", "_M_CEE_SAFE", "_M_FP_EXCEPT", "_M_FP_FAST", "_M_FP_PRECISE", "_M_FP_STRICT", "_M_IX86", "_M_IX86_FP", "_M_X64", "_MANAGED", "_MFC_VER", "_MSC_BUILD", "_MSC_EXTENSIONS", "_MSC_FULL_VER", "_MSC_VER", "_MSVC_LANG", "__MSVC_RUNTIME_CHECKS", "_MT", "_NATIVE_WCHAR_T_DEFINED", "_NO_SIZED_DEALLOCATION", "_OPENMP", "_PREFAST_", "_RESUMABLE_FUNCTIONS_SUPPORTED", "_RTC_CONVERSION_CHECKS_ENABLED", "__SANITIZE_ADDRESS__", "__STDC__", "__STDC_HOSTED__", "__STDC_NO_ATOMICS__", "__STDC_NO_COMPLEX__", "__STDC_NO_THREADS__", "__STDC_NO_VLA__", "__STDC_VERSION__", "__STDCPP_DEFAULT_NEW_ALIGNMENT__", "__STDCPP_THREADS__", "__TIME__", "__TIMESTAMP__", "__VA_ARGS__", "_VC_NODEFAULTLIB", "_WCHAR_T_DEFINED", "_WIN32", "_WIN64", "_WINRT_DLL"] +helpviewer_keywords: ["__ARM_ARCH macro", "timestamps, preprocessor macro", "cl.exe compiler, version number", "version numbers, C/C++ compiler (cl.exe)", "macros, predefined C++", "preprocessor, macros", "predefined macros", "_ATL_VER macro", "__ATOM__ macro", "__AVX__ macro", "__AVX2__ macro", "__AVX512BW__ macro", "__AVX512CD__ macro", "__AVX512DQ__ macro", "__AVX512F__ macro", "__AVX512VL__ macro", "_CHAR_UNSIGNED macro", "__CLR_VER macro", "_CONTROL_FLOW_GUARD macro", "__COUNTER__ macro", "__cplusplus macro", "__cplusplus_cli macro", "__cplusplus_winrt macro", "_CPPRTTI macro", "_CPPUNWIND macro", "__DATE__ macro", "_DEBUG macro", "_DLL macro", "__FILE__ macro", "__FUNCDNAME__ macro", "__FUNCSIG__ macro", "__FUNCTION__ macro", "_INTEGRAL_MAX_BITS macro", "_ISO_VOLATILE macro", "_KERNEL_MODE macro", "__LINE__ macro", "_M_AMD64 macro", "_M_ARM macro", "_M_ARM_ARMV7VE macro", "_M_ARM_FP macro", "_M_ARM64 macro", "_M_ARM64EC macro", "_M_CEE macro", "_M_CEE_PURE macro", "_M_CEE_SAFE macro", "_M_FP_EXCEPT macro", "_M_FP_FAST macro", "_M_FP_PRECISE macro", "_M_FP_STRICT macro", "_M_IX86 macro", "_M_IX86_FP macro", "_M_X64 macro", "_MANAGED macro", "_MFC_VER macro", "_MSC_BUILD macro", "_MSC_EXTENSIONS macro", "_MSC_FULL_VER macro", "_MSC_VER macro", "_MSVC_LANG macro", "__MSVC_RUNTIME_CHECKS macro", "_MT macro", "_NATIVE_WCHAR_T_DEFINED macro", "_NO_SIZED_DEALLOCATION macro", "_OPENMP macro", "_PREFAST_ macro", "_RESUMABLE_FUNCTIONS_SUPPORTED macro", "_RTC_CONVERSION_CHECKS_ENABLED macro", "__SANITIZE_ADDRESS__ macro", "__STDC__ macro", "__STDC_HOSTED__ macro", "__STDC_NO_ATOMICS__ macro", "__STDC_NO_COMPLEX__ macro", "__STDC_NO_THREADS__ macro", "__STDC_NO_VLA__ macro", "__STDC_VERSION__ macro", "__STDCPP_DEFAULT_NEW_ALIGNMENT__", "__STDCPP_THREADS__ macro", "__TIME__ macro", "__TIMESTAMP__ macro", "__VA_ARGS__ macro", "_VC_NODEFAULTLIB macro", "_WCHAR_T_DEFINED macro", "_WIN32 macro", "_WIN64 macro", "_WINRT_DLL macro", "__func__ identifier"] ms.assetid: 1cc5f70a-a225-469c-aed0-fe766238e23f -no-loc: [_ATL_VER, __ATOM__, __AVX__, __AVX2__, __AVX512BW__, __AVX512CD__, __AVX512DQ__, __AVX512F__, __AVX512VL__, _CHAR_UNSIGNED, __CLR_VER, _CONTROL_FLOW_GUARD, __COUNTER__, __cplusplus, __cplusplus_cli, __cplusplus_winrt, _CPPRTTI, _CPPUNWIND, __DATE__, _DEBUG, _DLL, __FILE__, __FUNCDNAME__, __FUNCSIG__, __FUNCTION__, _INTEGRAL_MAX_BITS, _ISO_VOLATILE, _KERNEL_MODE, __LINE__, _M_AMD64, _M_ARM, _M_ARM_ARMV7VE, _M_ARM_FP, _M_ARM64, _M_CEE, _M_CEE_PURE, _M_CEE_SAFE, _M_FP_EXCEPT, _M_FP_FAST, _M_FP_PRECISE, _M_FP_STRICT, _M_IX86, _M_IX86_FP, _M_X64, _MANAGED, _MFC_VER, _MSC_BUILD, _MSC_EXTENSIONS, _MSC_FULL_VER, _MSC_VER, _MSVC_LANG, __MSVC_RUNTIME_CHECKS, _MT, _NATIVE_WCHAR_T_DEFINED, _NO_SIZED_DEALLOCATION, _OPENMP, _PREFAST_, _RESUMABLE_FUNCTIONS_SUPPORTED, _RTC_CONVERSION_CHECKS_ENABLED, __SANITIZE_ADDRESS__, __STDC__, __STDC_HOSTED__, __STDC_NO_ATOMICS__, __STDC_NO_COMPLEX__, __STDC_NO_THREADS__, __STDC_NO_VLA__, __STDC_VERSION__, __STDCPP_THREADS__, __TIME__, __TIMESTAMP__, __VA_ARGS__, _VC_NODEFAULTLIB, _WCHAR_T_DEFINED, _WIN32, _WIN64, _WINRT_DLL, __func__] +no-loc: [_ATL_VER, __ATOM__, __AVX__, __AVX2__, __AVX512BW__, __AVX512CD__, __AVX512DQ__, __AVX512F__, __AVX512VL__, _CHAR_UNSIGNED, __CLR_VER, _CONTROL_FLOW_GUARD, __COUNTER__, __cplusplus, __cplusplus_cli, __cplusplus_winrt, _CPPRTTI, _CPPUNWIND, __DATE__, _DEBUG, _DLL, __FILE__, __FUNCDNAME__, __FUNCSIG__, __FUNCTION__, _INTEGRAL_MAX_BITS, _ISO_VOLATILE, _KERNEL_MODE, __LINE__, _M_AMD64, _M_ARM, _M_ARM_ARMV7VE, _M_ARM_FP, _M_ARM64, _M_ARM64EC, _M_CEE, _M_CEE_PURE, _M_CEE_SAFE, _M_FP_EXCEPT, _M_FP_FAST, _M_FP_PRECISE, _M_FP_STRICT, _M_IX86, _M_IX86_FP, _M_X64, _MANAGED, _MFC_VER, _MSC_BUILD, _MSC_EXTENSIONS, _MSC_FULL_VER, _MSC_VER, _MSVC_LANG, __MSVC_RUNTIME_CHECKS, _MT, _NATIVE_WCHAR_T_DEFINED, _NO_SIZED_DEALLOCATION, _OPENMP, _PREFAST_, _RESUMABLE_FUNCTIONS_SUPPORTED, _RTC_CONVERSION_CHECKS_ENABLED, __SANITIZE_ADDRESS__, __STDC__, __STDC_HOSTED__, __STDC_NO_ATOMICS__, __STDC_NO_COMPLEX__, __STDC_NO_THREADS__, __STDC_NO_VLA__, __STDC_VERSION__, __STDCPP_DEFAULT_NEW_ALIGNMENT__, __STDCPP_THREADS__, __TIME__, __TIMESTAMP__, __VA_ARGS__, _VC_NODEFAULTLIB, _WCHAR_T_DEFINED, _WIN32, _WIN64, _WINRT_DLL, __func__] --- # Predefined macros -The Microsoft C/C++ compiler (MSVC) predefines certain preprocessor macros, depending on the language (C or C++), the compilation target, and the chosen compiler options. +The Microsoft C/C++ compiler (MSVC) predefines certain preprocessor macros depending on the language (C or C++), the compilation target, and the chosen compiler options. -MSVC supports the predefined preprocessor macros required by the ANSI/ISO C99, C11, and C17 standards, and the ISO C++14 and C++17 standards. The implementation also supports several more Microsoft-specific preprocessor macros. Some macros are defined only for specific build environments or compiler options. Except where noted, the macros are defined throughout a translation unit as if they were specified as **`/D`** compiler option arguments. When defined, the macros are expanded to the specified values by the preprocessor before compilation. The predefined macros take no arguments and can't be redefined. +MSVC supports the predefined preprocessor macros required by the ANSI/ISO C99, C11, and C17 standards, and the ISO C++14, C++17, and C++20 standards. The implementation also supports several more Microsoft-specific preprocessor macros. + +Some macros are defined only for specific build environments or compiler options. Except where noted, the macros are defined throughout a translation unit as if they were specified as **`/D`** compiler option arguments. When defined, the preprocessor expands macros their specified values before compilation. The predefined macros take no arguments and can't be redefined. ## Standard predefined identifier @@ -21,7 +23,8 @@ The compiler supports this predefined identifier specified by ISO C99 and ISO C+ - `__func__` The unqualified and unadorned name of the enclosing function as a function-local **static const** array of **`char`**. ```cpp - void example(){ + void example() + { printf("%s\n", __func__); } // prints "example" ``` @@ -36,9 +39,9 @@ The compiler supports these predefined macros specified by the ISO C99, C11, C17 - `__FILE__` The name of the current source file. `__FILE__` expands to a character string literal. To ensure that the full path to the file is displayed, use [**`/FC`** (Full Path of Source Code File in Diagnostics)](../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md). This macro is always defined. -- `__LINE__` Defined as the integer line number in the current source file. The value of the `__LINE__` macro can be changed by using a `#line` directive. The integral type of the value of `__LINE__` can vary depending on context. This macro is always defined. +- `__LINE__` Defined as the integer line number in the current source file. The value of this macro can be changed by using a `#line` directive. The integral type of the value of `__LINE__` can vary depending on context. This macro is always defined. -- `__STDC__` Defined as 1 only when compiled as C and if the [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is specified. Otherwise, undefined. +- `__STDC__` Defined as 1 when compiled as C and if the [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is specified. Starting in Visual Studio 2022 version 17.2, it's defined as 1 when compiled as C and if the [`/std:c11`](../build/reference/std-specify-language-standard-version.md) or [`/std:c17`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. Otherwise, undefined. - `__STDC_HOSTED__` Defined as 1 if the implementation is a *hosted implementation*, one that supports the entire required standard library. Otherwise, defined as 0. @@ -52,29 +55,35 @@ The compiler supports these predefined macros specified by the ISO C99, C11, C17 - `__STDC_VERSION__` Defined when compiled as C and one of the **`/std`** C11 or C17 options is specified. It expands to `201112L` for [`/std:c11`](../build/reference/std-specify-language-standard-version.md), and `201710L` for [`/std:c17`](../build/reference/std-specify-language-standard-version.md). +- `__STDCPP_DEFAULT_NEW_ALIGNMENT__` When [`/std:c17`](../build/reference/std-specify-language-standard-version.md) or later is specified, this macro expands to a `size_t` literal that has the value of the alignment guaranteed by a call to alignment-unaware `operator new`. Larger alignments are passed to an alignment-aware overload, such as `operator new(std::size_t, std::align_val_t)`. For more information, see [`/Zc:alignedNew` (C++17 over-aligned allocation)](../build/reference/zc-alignednew.md). + - `__STDCPP_THREADS__` Defined as 1 if and only if a program can have more than one thread of execution, and compiled as C++. Otherwise, undefined. - `__TIME__` The time of translation of the preprocessed translation unit. The time is a character string literal of the form *hh:mm:ss*, the same as the time returned by the CRT [asctime](../c-runtime-library/reference/asctime-wasctime.md) function. This macro is always defined. ## Microsoft-specific predefined macros -MSVC supports these additional predefined macros. +MSVC supports other predefined macros: + +- `__ARM_ARCH` Defined as an integer literal that represents the ARM architecture version. The value is defined as 8 for the Armv8-A architecture. For 8.1 and onwards, the value is scaled for minor versions, such as X.Y, by using the formula X * 100 + Y as defined by the ARM C language extension. For example, for Armv8.1, `__ARM_ARCH` is 8 * 100 + 1 or 801. To set the ARM architecture version, see [`/arch (ARM64)`](../build/reference/arch-arm64.md). This macro was introduced in Visual Studio 2022 version 17.10. - `__ATOM__` Defined as 1 when the [`/favor:ATOM`](../build/reference/favor-optimize-for-architecture-specifics.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX__` Defined as 1 when the [`/arch:AVX`](../build/reference/arch-x86.md), [`/arch:AVX2`](../build/reference/arch-x86.md), or [`/arch:AVX512`](../build/reference/arch-x86.md) compiler options are set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX__` Defined as 1 when the [`/arch:AVX`](../build/reference/arch-x86.md), [`/arch:AVX2`](../build/reference/arch-x86.md), [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler options are set and the compiler target is x86 or x64. Otherwise, undefined. + +- `__AVX2__` Defined as 1 when the [`/arch:AVX2`](../build/reference/arch-x86.md), [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX2__` Defined as 1 when the [`/arch:AVX2`](../build/reference/arch-x86.md) or [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX512BW__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX512BW__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX512CD__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX512CD__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX512DQ__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX512DQ__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX512F__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX512F__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX512VL__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) or [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. -- `__AVX512VL__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. +- `__AVX10_VER__` Defined as an integer that represents version of AVX10 when the [`/arch:AVX10.1`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. - `_CHAR_UNSIGNED` Defined as 1 if the default **`char`** type is unsigned. This value is defined when the [**`/J`** (Default char type is unsigned)](../build/reference/j-default-char-type-is-unsigned.md) compiler option is set. Otherwise, undefined. @@ -91,7 +100,7 @@ MSVC supports these additional predefined macros. - `_CONTROL_FLOW_GUARD` Defined as 1 when the [**`/guard:cf`** (Enable Control Flow Guard)](../build/reference/guard-enable-control-flow-guard.md) compiler option is set. Otherwise, undefined. -- `__COUNTER__` Expands to an integer literal that starts at 0. The value is incremented by 1 every time it's used in a source file, or in included headers of the source file. `__COUNTER__` remembers its state when you use precompiled headers. This macro is always defined. +- `__COUNTER__` Expands to an integer literal that starts at 0. The value increments by 1 every time it's used in a source file, or in included headers of the source file. `__COUNTER__` remembers its state when you use precompiled headers. This macro is always defined. This example uses `__COUNTER__` to assign unique identifiers to three different objects of the same type. The `exampleClass` constructor takes an integer as a parameter. In `main`, the application declares three objects of type `exampleClass`, using `__COUNTER__` as the unique identifier parameter: @@ -186,9 +195,9 @@ MSVC supports these additional predefined macros. - `_KERNEL_MODE` Defined as 1 if the [**`/kernel`** (Create Kernel Mode Binary)](../build/reference/kernel-create-kernel-mode-binary.md) compiler option is set. Otherwise, undefined. -- `_M_AMD64` Defined as the integer literal value 100 for compilations that target x64 processors. Otherwise, undefined. +- `_M_AMD64` Defined as the integer literal value 100 for compilations that target x64 processors or ARM64EC. Otherwise, undefined. -- `_M_ARM` Defined as the integer literal value 7 for compilations that target ARM processors. Otherwise, undefined. +- `_M_ARM` Defined as the integer literal value 7 for compilations that target ARM processors. Undefined for ARM64, ARM64EC, and other targets. - `_M_ARM_ARMV7VE` Defined as 1 when the [`/arch:ARMv7VE`](../build/reference/arch-arm.md) compiler option is set for compilations that target ARM processors. Otherwise, undefined. @@ -200,7 +209,9 @@ MSVC supports these additional predefined macros. - For more information, see [**`/arch`** (ARM)](../build/reference/arch-arm.md). -- `_M_ARM64` Defined as 1 for compilations that target 64-bit ARM processors. Otherwise, undefined. +- `_M_ARM64` Defined as 1 for compilations that target ARM64. Otherwise, undefined. + +- `_M_ARM64EC` Defined as 1 for compilations that target ARM64EC. Otherwise, undefined. - `_M_CEE` Defined as 001 if any [**`/clr`** (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) compiler option is set. Otherwise, undefined. @@ -226,53 +237,25 @@ MSVC supports these additional predefined macros. - 1 if the `/arch:SSE` compiler option was set. - - 2 if the `/arch:SSE2`, `/arch:AVX`, `/arch:AVX2`, or `/arch:AVX512` compiler option was set. This value is the default if an `/arch` compiler option wasn't specified. When `/arch:AVX` is specified, the macro `__AVX__` is also defined. When `/arch:AVX2` is specified, both `__AVX__` and `__AVX2__` are also defined. When `/arch:AVX512` is specified, `__AVX__`, `__AVX2__`, `__AVX512BW__`, `__AVX512CD__`, `__AVX512DQ__`, `__AVX512F__`, and `__AVX512VL__` are also defined. + - 2 if the `/arch:SSE2`, `/arch:AVX`, `/arch:AVX2`, `/arch:AVX512` or `/arch:AVX10.1` compiler option was set. This value is the default if an `/arch` compiler option wasn't specified. When `/arch:AVX` is specified, the macro `__AVX__` is also defined. When `/arch:AVX2` is specified, both `__AVX__` and `__AVX2__` are also defined. When `/arch:AVX512` is specified, `__AVX__`, `__AVX2__`, `__AVX512BW__`, `__AVX512CD__`, `__AVX512DQ__`, `__AVX512F__`, and `__AVX512VL__` are also defined. When `/arch:AVX10.1` is specified, `__AVX__`, `__AVX2__`, `__AVX512BW__`, `__AVX512CD__`, `__AVX512DQ__`, `__AVX512F__`, `__AVX512VL__` and `__AVX10_VER__` are also defined. - For more information, see [**`/arch`** (x86)](../build/reference/arch-x86.md). -- `_M_X64` Defined as the integer literal value 100 for compilations that target x64 processors. Otherwise, undefined. +- `_M_X64` Defined as the integer literal value 100 for compilations that target x64 processors or ARM64EC. Otherwise, undefined. - `_MANAGED` Defined as 1 when the [`/clr`](../build/reference/clr-common-language-runtime-compilation.md) compiler option is set. Otherwise, undefined. -- `_MSC_BUILD` Defined as an integer literal that contains the revision number element of the compiler's version number. The revision number is the fourth element of the period-delimited version number. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_BUILD` macro evaluates to 1. This macro is always defined. +- `_MSC_BUILD` Defined as an integer literal that contains the revision number element of the compiler's version number. The revision number is the last element of the period-delimited version number. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_BUILD` macro is 1. This macro is always defined. - `_MSC_EXTENSIONS` Defined as 1 if the on-by-default [**`/Ze`** (Enable Language Extensions)](../build/reference/za-ze-disable-language-extensions.md) compiler option is set. Otherwise, undefined. -- `_MSC_FULL_VER` Defined as an integer literal that encodes the major, minor, and build number elements of the compiler's version number. The major number is the first element of the period-delimited version number, the minor number is the second element, and the build number is the third element. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_FULL_VER` macro evaluates to 150020706. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. - -- `_MSC_VER` Defined as an integer literal that encodes the major and minor number elements of the compiler's version number. The major number is the first element of the period-delimited version number and the minor number is the second element. For example, if the version number of the Microsoft C/C++ compiler is 17.00.51106.1, the `_MSC_VER` macro evaluates to 1700. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. - - | Visual Studio version | `_MSC_VER` | - |--|--| - | Visual Studio 6.0 | 1200 | - | Visual Studio .NET 2002 (7.0) | 1300 | - | Visual Studio .NET 2003 (7.1) | 1310 | - | Visual Studio 2005 (8.0) | 1400 | - | Visual Studio 2008 (9.0) | 1500 | - | Visual Studio 2010 (10.0) | 1600 | - | Visual Studio 2012 (11.0) | 1700 | - | Visual Studio 2013 (12.0) | 1800 | - | Visual Studio 2015 (14.0) | 1900 | - | Visual Studio 2017 RTW (15.0) | 1910 | - | Visual Studio 2017 version 15.3 | 1911 | - | Visual Studio 2017 version 15.5 | 1912 | - | Visual Studio 2017 version 15.6 | 1913 | - | Visual Studio 2017 version 15.7 | 1914 | - | Visual Studio 2017 version 15.8 | 1915 | - | Visual Studio 2017 version 15.9 | 1916 | - | Visual Studio 2019 RTW (16.0) | 1920 | - | Visual Studio 2019 version 16.1 | 1921 | - | Visual Studio 2019 version 16.2 | 1922 | - | Visual Studio 2019 version 16.3 | 1923 | - | Visual Studio 2019 version 16.4 | 1924 | - | Visual Studio 2019 version 16.5 | 1925 | - | Visual Studio 2019 version 16.6 | 1926 | - | Visual Studio 2019 version 16.7 | 1927 | - | Visual Studio 2019 version 16.8, 16.9 | 1928 | - | Visual Studio 2019 version 16.10, 16.11 | 1929 | - | Visual Studio 2022 RTW (17.0) | 1930 | - - To test for compiler releases or updates in a given version of Visual Studio or after, use the `>=` operator. You can use it in a conditional directive to compare `_MSC_VER` against that known version. If you have several mutually exclusive versions to compare, order your comparisons in descending order of version number. For example, this code checks for compilers released in Visual Studio 2017 and later. Next, it checks for compilers released in or after Visual Studio 2015. Then it checks for all compilers released before Visual Studio 2015: +- `_MSC_FULL_VER` Defined as an integer literal that encodes the major, minor, and build number elements of the compiler's version number. The major number is the first element of the period-delimited version number, the minor number is the second element, and the build number is the third element. + + For example, if the Microsoft C/C++ compiler version is 19.39.33519, `_MSC_FULL_VER` is 193933519. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. For more information about compiler versioning, see [C++ compiler versioning](../overview/compiler-versions.md) and specifically [Service releases starting with Visual Studio 2017](../overview/compiler-versions.md#service-releases-starting-with-visual-studio-2017) for more information about Visual Studio 2019 16.8, 16.9, 16.10 and 16.11, which require `_MSC_FULL_VER` to tell them apart. + +- `_MSC_VER` Defined as an integer literal that encodes the major and minor number elements of the compiler's version number. The major number is the first element of the period-delimited version number and the minor number is the second element. For example, if the version number of the Microsoft C/C++ compiler is 17.00.51106.1, the value of `_MSC_VER` is 1700. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. + + To test for compiler releases or updates in a given version of Visual Studio or later, use the `>=` operator. You can use it in a conditional directive to compare `_MSC_VER` against that known version. If you have several mutually exclusive versions to compare, order your comparisons in descending order of version number. For example, this code checks for compilers released in Visual Studio 2017 and later. Next, it checks for compilers released in or after Visual Studio 2015. Then it checks for all compilers released before Visual Studio 2015: ```cpp #if _MSC_VER >= 1910 @@ -284,11 +267,11 @@ MSVC supports these additional predefined macros. #endif ``` - To test for compiler versions that share major and minor numbers, use the major, minor, and build numbers in `_MSC_FULL_VER` for comparisons. The compilers in Visual Studio 2019 version 16.9 have an `_MSC_FULL_VER` value of 192829500 or greater. The compilers in Visual Studio 2019 version 16.11 have an `_MSC_FULL_VER` value of 192930100 or greater. + For more information about Visual Studio 2019 16.8 and 16.9, and 16.10 and 16.11, which share the same major and minor versions (and so have the same value for `_MSC_VER`), see [Service releases starting with Visual Studio 2017](../overview/compiler-versions.md#service-releases-starting-with-visual-studio-2017). - For more information, see [Visual C++ Compiler Version](https://devblogs.microsoft.com/cppblog/visual-c-compiler-version/) in the Microsoft C++ Team Blog. + For more information about the history of compiler versioning, and compiler version numbers and the Visual Studio versions they correspond to, see [C++ compiler versioning](../overview/compiler-versions.md). Also, [Visual C++ Compiler Version](https://devblogs.microsoft.com/cppblog/visual-c-compiler-version/) on the Microsoft C++ team blog. -- `_MSVC_LANG` Defined as an integer literal that specifies the C++ language standard targeted by the compiler. It's set only in code compiled as C++. The macro is the integer literal value `201402L` by default, or when the [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. The macro is set to `201703L` if the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. The macro is set to `202002L` if the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. It's set to a higher, unspecified value when the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) option is specified. Otherwise, the macro is undefined. The `_MSVC_LANG` macro and [`/std` (Specify language standard version)](../build/reference/std-specify-language-standard-version.md) compiler options are available beginning in Visual Studio 2015 Update 3. +- `_MSVC_LANG` Defined as an integer literal that specifies the C++ language standard targeted by the compiler. Only code compiled as C++ sets it. The macro is the integer literal value `201402L` by default, or when the [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. The macro is set to `201703L` if the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. The macro is set to `202002L` if the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) compiler option is specified. It's set to a higher, unspecified value when the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) option is specified. Otherwise, the macro is undefined. The `_MSVC_LANG` macro and [`/std` (Specify language standard version)](../build/reference/std-specify-language-standard-version.md) compiler options are available beginning in Visual Studio 2015 Update 3. - `__MSVC_RUNTIME_CHECKS` Defined as 1 when one of the [`/RTC`](../build/reference/rtc-run-time-error-checks.md) compiler options is set. Otherwise, undefined. @@ -297,7 +280,7 @@ MSVC supports these additional predefined macros. - Available beginning with Visual Studio 2019 version 16.5: Defined as 0 when the preprocessor conformance mode [`/Zc:preprocessor`](../build/reference/zc-preprocessor.md) compiler option is set. Defined as 1 by default, or when the `/Zc:preprocessor-` compiler option is set, to indicate the traditional preprocessor is in use (essentially, `/Zc:preprocessor` replaces the deprecated `/experimental:preprocessor`). ```cpp - #if defined(_MSVC_TRADITIONAL) && _MSVC_TRADITIONAL + #if !defined(_MSVC_TRADITIONAL) || _MSVC_TRADITIONAL // Logic using the traditional preprocessor #else // Logic using cross-platform compatible preprocessor @@ -337,9 +320,9 @@ MSVC supports these additional predefined macros. No preprocessor macros that identify the ATL or MFC library version are predefined by the compiler. ATL and MFC library headers define these version macros internally. They're undefined in preprocessor directives made before the required header is included. -- `_ATL_VER` Defined in \ as an integer literal that encodes the ATL version number. +- `_ATL_VER` Defined in `` as an integer literal that encodes the ATL version number. -- `_MFC_VER` Defined in \ as an integer literal that encodes the MFC version number. +- `_MFC_VER` Defined in `` as an integer literal that encodes the MFC version number. ## See also diff --git a/docs/preprocessor/preprocessor-experimental-overview.md b/docs/preprocessor/preprocessor-experimental-overview.md index f505d902e8..7f29b6890e 100644 --- a/docs/preprocessor/preprocessor-experimental-overview.md +++ b/docs/preprocessor/preprocessor-experimental-overview.md @@ -23,7 +23,7 @@ Starting in Visual Studio 2019 version 16.5, preprocessor support for the C++20 You can detect which preprocessor is in use at compile time. Check the value of the predefined macro [`_MSVC_TRADITIONAL`](predefined-macros.md) to tell if the traditional preprocessor is in use. This macro is set unconditionally by versions of the compiler that support it, independent of which preprocessor is invoked. Its value is 1 for the traditional preprocessor. It's 0 for the conforming preprocessor. ```cpp -#if defined(_MSVC_TRADITIONAL) && _MSVC_TRADITIONAL +#if !defined(_MSVC_TRADITIONAL) || _MSVC_TRADITIONAL // Logic using the traditional preprocessor #else // Logic using cross-platform compatible preprocessor @@ -64,7 +64,7 @@ int myVal; The traditional preprocessor incorrectly combines a string prefix to the result of the [stringizing operator (#)](stringizing-operator-hash.md) operator: ```cpp - #define DEBUG_INFO(val) L"debug prefix:" L#val +#define DEBUG_INFO(val) L"debug prefix:" L#val // ^ // this prefix diff --git a/docs/preprocessor/setlocale.md b/docs/preprocessor/setlocale.md index 05ec71345c..b77c44ff44 100644 --- a/docs/preprocessor/setlocale.md +++ b/docs/preprocessor/setlocale.md @@ -8,7 +8,7 @@ no-loc: ["pragma"] --- # `setlocale` pragma -Defines the *locale*, the country, region, and language to use when translating wide-character constants and string literals. +Defines the *locale*, the country/region and language to use when translating wide-character constants and string literals. ## Syntax diff --git a/docs/preprocessor/warning.md b/docs/preprocessor/warning.md index a76695c968..8d6d994f0a 100644 --- a/docs/preprocessor/warning.md +++ b/docs/preprocessor/warning.md @@ -1,7 +1,7 @@ --- title: "warning pragma" description: "Learn more about the warning pragma in Microsoft C/C++" -ms.date: 01/22/2021 +ms.date: 4/30/2025 f1_keywords: ["warning_CPP", "vc-pragma.warning"] helpviewer_keywords: ["pragma, warning", "push pragma warning", "pop warning pragma", "warning pragma"] no-loc: ["pragma"] @@ -13,8 +13,8 @@ Enables selective modification of the behavior of compiler warning messages. ## Syntax > **`#pragma warning(`**\ ->     *`warning-specifier`* **`:`** *`warning-number-list`*\ ->     [**`;`** *`warning-specifier`* **`:`** *`warning-number-list`* ... ] **`)`**\ +>  *`warning-specifier`* **`:`** *`warning-number-list`* [ **`,`** **`justification`** **`:`** *`string-literal`*]\ +>  [**`;`** *`warning-specifier`* **`:`** *`warning-number-list`* ... ] **`)`**\ > **`#pragma warning( push`** [ **`,`** *n* ] **`)`**\ > **`#pragma warning( pop )`** @@ -24,30 +24,39 @@ The following warning-specifier parameters are available. | warning-specifier | Meaning | |--|--| -| `1`, `2`, `3`, `4` | Apply the given level to the specified warnings. Also turns on a specified warning that is off by default. | +| `1`, `2`, `3`, `4` | Apply the given level to the specified warnings. For example: `#pragma warning (3 : 5033)` turns off warning 5033 (normally a level 1 warning) unless the warning level is set to `/w3` or higher. Also can be used to turn on a specified warning that is off by default. | | `default` | Reset warning behavior to its default value. Also turns on a specified warning that is off by default. The warning will be generated at its default, documented, level.

For more information, see [Compiler warnings that are off by default](../preprocessor/compiler-warnings-that-are-off-by-default.md). | -| `disable` | Don't issue the specified warning messages. | +| `disable` | Don't issue the specified warning messages. The optional **`justification`** property is allowed. | | `error` | Report the specified warnings as errors. | | `once` | Display the specified message(s) only one time. | -| `suppress` | Pushes the current state of the pragma on the stack, disables the specified warning for the next line, and then pops the warning stack so that the pragma state is reset. | +| `suppress` | Pushes the current state of the pragma on the stack, disables the specified warning for the next line, and then pops the warning stack so that the pragma state is reset. The optional **`justification`** property is allowed. | The following code statement illustrates that a *`warning-number-list`* parameter can contain multiple warning numbers, and that multiple *`warning-specifier`* parameters can be specified in the same pragma directive. ```cpp -#pragma warning( disable : 4507 34; once : 4385; error : 164 ) +#pragma warning( disable : 4507 4034; once : 4385; error : 164 ) ``` +However, when the **`justification`** field is present, only one warning number can be specified. The following code statement illustrates the use of the **`justification`** field. + +```cpp +#pragma warning( disable : 4507, justification : "This warning is disabled" ) +``` + +The **`justification`** fields allows you to explain why a warning is being disable or +suppressed. The **`justification`** field is only supported for the **`disable`** and **`suppress`** *`warning-specifier`*. This value will appear in the SARIF output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal. + This directive is functionally equivalent to the following code: ```cpp // Disable warning messages 4507 and 4034. -#pragma warning( disable : 4507 34 ) +#pragma warning(disable : 4507 4034) // Issue warning C4385 only once. -#pragma warning( once : 4385 ) +#pragma warning(once : 4385) // Report warning C4164 as an error. -#pragma warning( error : 164 ) +#pragma warning(error : 164) ``` The compiler adds 4000 to any warning number that is between 0 and 999. @@ -58,15 +67,17 @@ Warning numbers in the range 4700-4999 are associated with code generation. For // pragma_warning.cpp // compile with: /W1 #pragma warning(disable:4700) -void Test() { +void Test() +{ int x; - int y = x; // no C4700 here - #pragma warning(default:4700) // C4700 enabled after Test ends + int y = x; // no C4700 here + #pragma warning(default:4700) // C4700 enabled after compiling Test() } -int main() { +int main() +{ int x; - int y = x; // C4700 + int y = x; // C4700 } ``` diff --git a/docs/safeint/safeint-class.md b/docs/safeint/safeint-class.md index 288f91995c..b2f07081df 100644 --- a/docs/safeint/safeint-class.md +++ b/docs/safeint/safeint-class.md @@ -152,11 +152,11 @@ The type of integer or Boolean parameter for the secondary operand. | ^= | `SafeInt& operator^= (SafeInt rhs) throw()` | | ^= | `template`

`SafeInt& operator^= (U rhs) throw()` | | ^= | `template`

`SafeInt& operator^= (SafeInt rhs) throw()` | -| | | `SafeInt operator| (SafeInt rhs) const throw()` | -| | | `template`

`SafeInt operator| (U rhs) const throw()` | -| |= | `SafeInt& operator|= (SafeInt rhs) throw()` | -| |= | `template`

`SafeInt& operator|= (U rhs) throw()` | -| |= | `template`

`SafeInt& operator|= (SafeInt rhs) throw()` | +| \| | `SafeInt operator| (SafeInt rhs) const throw()` | +| \| | `template`

`SafeInt operator| (U rhs) const throw()` | +| \|= | `SafeInt& operator|= (SafeInt rhs) throw()` | +| \|= | `template`

`SafeInt& operator|= (U rhs) throw()` | +| \|= | `template`

`SafeInt& operator|= (SafeInt rhs) throw()` | ## Remarks @@ -224,7 +224,7 @@ There are two options to customize the error policy. The first option is to set **Header:** SafeInt.hpp > [!NOTE] > The latest version of this library is located at [https://github.com/dcleblanc/SafeInt](https://github.com/dcleblanc/SafeInt). Clone the library and include SafeInt.hpp to use the SafeInt library. -> Prefer this github repo to . it's a modern version of that includes a small number of bug fixes, uses modern features of C++ resulting in more efficient code, and is portable to any platform using gcc, clang, or Intel compilers. +> Prefer this GitHub repo to . it's a modern version of that includes a small number of bug fixes, uses modern features of C++ resulting in more efficient code, and is portable to any platform using gcc, clang, or Intel compilers. ### Example diff --git a/docs/sanitizers/asan-building.md b/docs/sanitizers/asan-building.md index 805a889550..003492cbbb 100644 --- a/docs/sanitizers/asan-building.md +++ b/docs/sanitizers/asan-building.md @@ -1,15 +1,15 @@ --- title: "AddressSanitizer language, build, and debugging reference" description: "Technical description of building for the AddressSanitizer" -ms.date: 09/15/2021 +ms.date: 02/05/2024 f1_keywords: ["__SANITIZE_ADDRESS__", "ASAN_VCASAN_DEBUGGING"] helpviewer_keywords: ["ASan reference", "AddressSanitizer reference", "Address Sanitizer reference"] --- # AddressSanitizer language, build, and debugging reference -The sections in this article describe the AddressSanitizer language specification, compiler options, and linker options. They also describe the options that control Visual Studio debugger integration specific to the AddressSanitizer. +This article describes the AddressSanitizer language specification, compiler options, linker options, and the options that control Visual Studio debugger integration specific to the AddressSanitizer. -For more information on the AddressSanitizer runtime, see the [runtime reference](./asan-runtime.md). It includes information on intercepted functions and how to hook custom allocators. For more information on saving crash dumps from AddressSanitizer failures, see the [crash dump reference](./asan-offline-crash-dumps.md). +For more information on the AddressSanitizer runtime, see the [runtime reference](asan-runtime.md). It includes information on intercepted functions and how to hook custom allocators. For more information on saving crash dumps from AddressSanitizer failures, see the [crash dump reference](asan-offline-crash-dumps.md). ## Language specification @@ -56,9 +56,9 @@ void test3() { ### `/fsanitize=address` compiler option -The [**`/fsanitize=address`**](../build/reference/fsanitize.md) compiler option instruments memory references in your code to catch memory safety errors at runtime. The instrumentation hooks loads, stores, scopes, `alloca`, and CRT functions. It can detect hidden bugs such as out-of-bounds, use-after-free, use-after-scope, and so on. For a non-exhaustive list of errors detected at runtime, see [AddressSanitizer error examples](./asan-error-examples.md). +The [**`/fsanitize=address`**](../build/reference/fsanitize.md) compiler option instruments memory references in your code to catch memory safety errors at runtime. The instrumentation hooks loads, stores, scopes, `alloca`, and CRT functions. It can detect hidden bugs such as out-of-bounds, use-after-free, use-after-scope, and so on. For a nonexhaustive list of errors detected at runtime, see [AddressSanitizer error examples](asan-error-examples.md). -**`/fsanitize=address`** is compatible with all existing C++ or C optimization levels (for example, **`/Od`**, **`/O1`**, **`/O2`**, **`/O2 /GL`**, and profile guided optimization). The code produced with this option works with static and dynamic CRTs (for example, **`/MD`**, **`/MDd`**, **`/MT`**, and **`/MTd`**). This compiler option can be used to create an .EXE or .DLL targeting x86 or x64. Debug information is required for optimal formatting of call stacks. +**`/fsanitize=address`** is compatible with all existing C++ or C optimization levels (for example, **`/Od`**, **`/O1`**, **`/O2`**, and **`/O2 /GL`**). The code produced with this option works with static and dynamic CRTs (for example, **`/MD`**, **`/MDd`**, **`/MT`**, and **`/MTd`**). This compiler option can be used to create an .EXE or .DLL targeting x86 or x64. Debug information is required for optimal formatting of call stacks. This compiler option isn't supported with profile guided optimization. For examples of code that demonstrates several kinds of error detection, see [AddressSanitizer error examples](asan-error-examples.md). @@ -82,7 +82,7 @@ These libraries are added to the default library list when you specify **`/fsani | **`/MTd`** | *`clang_rt.fuzzer_MTd-{arch}`* | | **`/MDd`** | *`clang_rt.fuzzer_MDd-{arch}`* | -LibFuzzer libraries that omit the **`main`** function are also available. It's your responsibility to define **`main`** and to call **`LLVMFuzzerInitialize`** and **`LLVMFuzzerTestOneInput`** when you use these libraries. To use one of these libraries, specify [`/NODEFAULTLIB`](../build/reference/nodefaultlib-ignore-libraries.md) and explicitly link with the library below that corresponds to your runtime and architecture: +LibFuzzer libraries that omit the **`main`** function are also available. It's your responsibility to define **`main`** and to call **`LLVMFuzzerInitialize`** and **`LLVMFuzzerTestOneInput`** when you use these libraries. To use one of these libraries, specify [`/NODEFAULTLIB`](../build/reference/nodefaultlib-ignore-libraries.md) and explicitly link with the following library that corresponds to your runtime and architecture: | Runtime option | LibFuzzer no_main library | |--|--| @@ -100,34 +100,58 @@ By default, the MSVC compiler (unlike Clang) doesn't generate code to allocate f 1. Compile using the [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md) option. 2. Before executing your program, run `set ASAN_OPTIONS=detect_stack_use_after_return=1` to set the runtime check option. -The **`/fsanitize-address-use-after-return`** option causes the compiler to generate code to use a dual stack frame in the heap when locals are considered "address taken". This code is *much slower* than just using **`/fsanitize=address`** alone. For more information and an example, see [Error: `stack-use-after-return`](error-stack-use-after-return.md). +The **`/fsanitize-address-use-after-return`** option causes the compiler to generate code to use a dual stack frame in the heap when locals are considered "address taken." This code is *much slower* than just using **`/fsanitize=address`** alone. For more information and an example, see [Error: `stack-use-after-return`](error-stack-use-after-return.md). The dual stack frame in the heap remains after the return from the function that created it. Consider an example where the address of a local, allocated to a slot in the heap, is used after the return. The shadow bytes associated with the fake heap frame contain the value 0xF9. That 0xF9 means a stack-use-after-return error when the runtime reports the error. Stack frames are allocated in the heap and remain after functions return. The runtime uses garbage collection to asynchronously free these fake call-frame objects, after a certain time interval. Addresses of locals get transferred to persistent frames in the heap. It's how the system can detect when any locals get used after the defining function returns. For more information, see the [algorithm for stack use after return](https://github.com/google/sanitizers/wiki/AddressSanitizerUseAfterReturn) as documented by Google. +### ASan intrinsic compatibility library + +When building with ASan, the compiler replaces intrinsic functions (like `memset`) with function calls provided by the ASan runtime library (like `__asan_memset`) that complete the same operation but also provide memory safety checks. For user-mode ASan, the compiler and runtime are updated together because Visual Studio provides both. [Kernel-mode ASan (KASan)](/windows-hardware/drivers/devtest/kasan) is part of the Windows OS, so it updates on a different cadence than the compiler. To avoid issues with a new compiler using new intrinsics that the installed version of KASan doesn't support, link the compatibility library (`asan_compat.lib`) to avoid link-time issues. When using `asan_compat.lib`, the program behaves as though the unsupported ASan intrinsics aren't used. Linking with a newer runtime library that supports the new ASan intrinsics supersedes the versions provided by `asan_compat.lib`. This decision is made at link time, so it's imperative to link with the KASan library provided by the Windows SDK that matches the OS version you're targeting. + +The following options are supported in Visual Studio 2022 17.14 Preview 2 and later: +- To include this compatibility library as a default library, use the **`/fsanitize-address-asan-compat-lib`** compiler option. This option is automatically enabled when using **`/fsanitize=kernel-address`**. +- To opt-out of this compatibility library, use the **`/fno-sanitize-address-asan-compat-lib`** compiler option. + +Using **`/fsanitize-address-asan-compat-lib`** to link a newer compiler with an older user-mode ASan runtime isn't currently supported. + ## Linker ### `/INFERASANLIBS[:NO]` linker option -The **`/fsanitize=address`** compiler option marks objects to specify the AddressSanitizer library to link into your executable. The libraries have names that begin with *`clang_rt.asan*`*. The [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) linker option (on by default) links these libraries from their default locations automatically. Here are the libraries chosen and automatically linked in: +The **`/fsanitize=address`** compiler option marks objects to specify which AddressSanitizer library to link into your executable. The libraries have names that begin with *`clang_rt.asan*`*. The [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) linker option (on by default) links these libraries from their default locations automatically. Here are the libraries chosen and automatically linked in. + +> [!NOTE] +> In the following table, *`{arch}`* is either *`i386`* or *`x86_64`*. +> These libraries use Clang conventions for architecture names. MSVC conventions are normally `x86` and `x64` rather than `i386` and `x86_64`. They refer to the same architectures. + +| CRT option | AddressSanitizer runtime library (.lib) | Address runtime binary (.dll) +|--|--|--| +| `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_static_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* +| `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* + +The linker option [`/INFERASANLIBS:NO`](../build/reference/inferasanlibs.md) prevents the linker from linking a *`clang_rt.asan*`* library file from the default location. Add the library path in your build scripts if you use this option. Otherwise, the linker reports an unresolved external symbol error. + +**Previous Versions** + +Prior to Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`**) builds didn't use a DLL dependency. Instead, the AddressSanitizer runtime was statically linked into the user's EXE. DLL projects would then load exports from the user's EXE to access ASan functionality. Also, dynamically linked projects (**`/MD`** or **`/MTd`**) used different libraries and DLLs depending on whether the project was configured for debug or release. For more information about these changes and their motivations, see [MSVC Address Sanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/). -| Runtime option | DLL or EXE | AddressSanitizer runtime libraries | + +| CRT runtime option | DLL or EXE | AddressSanitizer runtime libraries | |--|--|--| | **`/MT`** | EXE | *`clang_rt.asan-{arch}`*, *`clang_rt.asan_cxx-{arch}`* | | **`/MT`** | DLL | *`clang_rt.asan_dll_thunk-{arch}`* | -| **`/MD`** | EITHER | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | +| **`/MD`** | Either | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | | **`/MTd`** | EXE | *`clang_rt.asan_dbg-{arch}`*, *`clang_rt.asan_dbg_cxx-{arch}`* | | **`/MTd`** | DLL | *`clang_rt.asan_dbg_dll_thunk-{arch}`* | -| **`/MDd`** | EITHER | *`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`* | - -The linker option [`/INFERASANLIBS:NO`](../build/reference/inferasanlibs.md) prevents the linker from linking a *`clang_rt.asan*`* library file from the default location. Add the library path in your build scripts if you use this option. Otherwise, the linker reports an unresolved external symbol error. +| **`/MDd`** | Either | *`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`* | ## Visual Studio integration ### `/fno-sanitize-address-vcasan-lib` compiler option -The **`/fsanitize=address`** option links in extra libraries for an improved Visual Studio debugging experience when an AddressSanitizer exception is thrown. These libraries are called **VCAsan**. The libraries enable Visual Studio to display AddressSanitizer errors on your source code. They also enable the executable to generate crash dumps when an AddressSanitizer error report is created. For more information, see [Visual Studio AddressSanitizer extended functionality library](./asan-debugger-integration.md). +The **`/fsanitize=address`** option links in extra libraries for an improved Visual Studio debugging experience when an AddressSanitizer exception is thrown. These libraries are called **VCAsan**. The libraries enable Visual Studio to display AddressSanitizer errors on your source code. They also enable the executable to generate crash dumps when an AddressSanitizer error report is created. For more information, see [Visual Studio AddressSanitizer extended functionality library](asan-debugger-integration.md). The library chosen depends on the compiler options, and is automatically linked in. @@ -138,7 +162,7 @@ The library chosen depends on the compiler options, and is automatically linked | **`/MTd`** | *`libvcasand.lib`* | | **`/MDd`** | *`vcasand.lib`* | -However, if you compile using **`/Zl`** (Omit default library name), you'll need to manually specify the library. If you don't, you'll get an unresolved external symbol link error. Here are some typical examples: +However, if you compile using **`/Zl`** (Omit default library name), you must manually specify the library. If you don't, you get an unresolved external symbol link error. Here are some typical examples: ```Output error LNK2001: unresolved external symbol __you_must_link_with_VCAsan_lib @@ -155,10 +179,10 @@ To enable this behavior, run the command `set ASAN_VCASAN_DEBUGGING=1` before yo ## See also -[AddressSanitizer overview](./asan.md)\ -[AddressSanitizer known issues](./asan-known-issues.md)\ -[AddressSanitizer runtime reference](./asan-runtime.md)\ -[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ -[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ -[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ -[AddressSanitizer error examples](./asan-error-examples.md) +[AddressSanitizer overview](asan.md)\ +[AddressSanitizer known issues](asan-known-issues.md)\ +[AddressSanitizer runtime reference](asan-runtime.md)\ +[AddressSanitizer shadow bytes](asan-shadow-bytes.md)\ +[AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\ +[AddressSanitizer debugger integration](asan-debugger-integration.md)\ +[AddressSanitizer error examples](asan-error-examples.md) diff --git a/docs/sanitizers/asan-continue-on-error.md b/docs/sanitizers/asan-continue-on-error.md new file mode 100644 index 0000000000..9d820f863e --- /dev/null +++ b/docs/sanitizers/asan-continue-on-error.md @@ -0,0 +1,354 @@ +--- +title: "Walkthrough: Use Address Sanitizer Continue On Error to find memory safety issues" +description: "Learn how to use Address Sanitizer continue on error to find memory safety errors in your app." +ms.date: 07/31/2023 +f1_keywords: ["AddressSanitizer", "Continue On Error"] +helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compiling for AddressSanitizer", "Continue On Error", "ASAN continue on error", "Address Sanitizer continue on error"] +--- + +# Walkthrough: Use Address Sanitizer Continue On Error to find memory safety issues + +In this walkthrough, create checked builds that find and report memory safety errors. + +Memory safety errors like out-of-bounds memory reads and writes, using memory after it has been freed, `NULL` pointer dereferences, and so on, are a top concern for C/C++ code. Address Sanitizer (ASAN) is a compiler and runtime technology that exposes these kinds of hard-to-find bugs, and does it with zero false positives. For an overview of ASAN, see [AddressSanitizer](asan.md). + +Continue On Error (COE) is a new ASAN feature that automatically diagnoses and reports memory safety errors as your app runs. When your program exits, a summary of unique memory safety errors is output to `stdout`, `stderr`, or to a log file of your choice. When you create a standard C++ checked build with `-fsanitizer=address`, calls to allocators, deallocators such as `free`, `memcpy`, `memset`, and so on, are forwarded to the ASAN runtime. The ASAN runtime provides the same semantics for these functions, but monitors what happens with the memory. ASAN diagnoses and reports hidden memory safety errors, with zero false positives, as your app runs. + +A significant advantage of COE is that, unlike the previous ASAN behavior, your program doesn't stop running when the first memory error is found. Instead, ASAN notes the error, and your app continues to run. After your app exits, a summary of all the memory issues is output. + +It's a good practice to create a checked build of your C or C++ app with ASAN turned on, and then run your app in your test harness. As your tests exercise the code paths in your app looking for bugs, you'll also find out if those code paths harbor memory safety issues without interfering with the tests. + +When your app finishes, you get a summary of the memory issues. With COE, you can compile and deploy an existing application into limited production to find memory safety issues. You can run the checked build for days to fully exercise the code, although the app will run slower due to the ASAN instrumentation. + +You can use this feature to create a new shipping gate. If all your existing tests pass, but COE reports a memory safety error or a leak, don't ship the new code or integrate it into a parent branch. + +Don't deploy a build with COE enabled into production! COE is intended to be used in testing and development environments only. You shouldn't use an ASAN enabled build in production because of the performance impact of the instrumentation added to detect memory errors, the risk of exposing the internal implementation if errors are reported, and to avoid increasing the surface area of possible security exploits by shipping the library functions that ASAN substitutes for memory allocation, freeing, and so on. + +In the following examples, you create checked builds and set an environment variable to output the address sanitizer information to `stdout` to see the memory safety errors that ASAN reports. + +## Prerequisites + +To complete this walkthrough, you need Visual Studio 2022 17.6 or later with the *Desktop development with C++ workload* installed. + +## Double free example + +In this example, you create a build with ASAN enabled to test what happens when memory is double freed. ASAN detects this error and reports it. In this example, the program continues to run after the error is detected, which leads to a second error--using memory that's been freed. A summary of the errors is output to `stdout` when the program exits. + +Create the example: + +1. Open a developer command prompt: Open the **Start** menu, type *Developer*, and select the latest command prompt such as **Developer Command Prompt for VS 2022** from the list of matches. +1. Create a directory on your machine to run this example. For example, `%USERPROFILE%\Desktop\COE`. +1. In that directory, create an empty source file. For example, `doublefree.cpp` +1. Paste the following code into the file: + + ```cpp + #include + #include + + void BadFunction(int *pointer) + { + free(pointer); + free(pointer); // double-free! + } + + int main(int argc, const char *argv[]) + { + int *pointer = static_cast(malloc(4)); + BadFunction(pointer); + + // Normally we'd crash before this, but with COE we can see heap-use-after-free error as well + printf("\n\n******* Pointer value: %d\n", *pointer); + + return 1; + } + ``` + +In the preceding code, `pointer` is freed twice. This is a contrived example, but double frees are an easy mistake to make in more complex C++ code. + +Create a build of the preceding code with COE turned on with the following steps: + +1. Compile the code in the developer command prompt you opened earlier: `cl -fsanitize=address -Zi doublefree.cpp`. The `-fsanitize=address` switch turns on ASAN, and `-Zi` creates a separate PDB file that address sanitizer uses to display memory error location information. +1. Send ASAN output to `stdout` by setting the `ASAN_OPTIONS` environment variable in the developer command prompt as follows: `set ASAN_OPTIONS=continue_on_error=1` +1. Run the test code with: `doublefree.exe` + +The output shows that there was a double free error and the call stack where it happened. The report starts out with a call stack that shows the error happened in `BadFunction`: + +```cmd +==22976==ERROR: AddressSanitizer: attempting double-free on 0x01e03550 in thread T0: + #0 free D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp(69) + #1 BadFunction C:\Users\xxx\Desktop\COE\doublefree.cpp(8) + #2 main C:\Users\xxx\Desktop\COE\doublefree.cpp(14) + #3 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #4 BaseThreadInitThunk Windows + #5 RtlInitializeExceptionChain Windows +``` + +Next, there's information about the freed memory and a call stack for where the memory was allocated: + +```cmd +0x01e03550 is located 0 bytes inside of 4-byte region [0x01e03550,0x01e03554) +freed by thread T0 here: + #0 free D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp(69) + #1 BadFunction C:\Users\xxx\Desktop\COE\doublefree.cpp(7) + #2 main C:\Users\xxx\Desktop\COE\doublefree.cpp(14) + #3 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #4 BaseThreadInitThunk Windows + #5 RtlInitializeExceptionChain Windows + +previously allocated by thread T0 here: + #0 malloc D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp(85) + #1 main C:\Users\xxx\Desktop\COE\doublefree.cpp(13) + #2 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #3 BaseThreadInitThunk Windows + #4 RtlInitializeExceptionChain Windows +``` + +Then there's information about the heap-use-after-free error. This refers to using `*pointer` in the `printf()` call because the memory `pointer` refers to was freed earlier. The call stack where the error occurs is listed, as are the call stacks where this memory was allocated and freed: + +```cmd +==35680==ERROR: AddressSanitizer: heap-use-after-free on address 0x02a03550 at pc 0x00e91097 bp 0x012ffc64 sp 0x012ffc58READ of size 4 at 0x02a03550 thread T0 + #0 main C:\Users\xxx\Desktop\Projects\ASAN\doublefree.cpp(18) + #1 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #2 BaseThreadInitThunk Windows + #3 RtlInitializeExceptionChain Windows + +0x02a03550 is located 0 bytes inside of 4-byte region [0x02a03550,0x02a03554) +freed by thread T0 here: + #0 free D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp(69) + #1 BadFunction C:\Users\xxx\Desktop\Projects\ASAN\doublefree.cpp(7) + #2 main C:\Users\xxx\Desktop\Projects\ASAN\doublefree.cpp(14) + #3 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #4 BaseThreadInitThunk Windows + #5 RtlInitializeExceptionChain Windows + +previously allocated by thread T0 here: + #0 malloc D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp(85) + #1 main C:\Users\xxx\Desktop\Projects\ASAN\doublefree.cpp(13) + #2 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #3 BaseThreadInitThunk Windows + #4 RtlInitializeExceptionChain Windows +``` + +Next, there's information about the shadow bytes in the vicinity of the buffer overflow. For more information about shadow bytes, see [AddressSanitizer shadow bytes](asan-shadow-bytes.md). + +Following the shadow byte information, you'll see the output from the program, which indicates that it continued running after ASAN detected the error: + +```cmd +******* Pointer value: xxx +``` + +Then there's a summary of the source files where the memory error happened. It's sorted by the unique call stacks for the memory errors in that file. A unique call stack is determined by the type of error and the call stack where the error occurred. + +This sorting prioritizes memory safety issues that may be the most concerning. For example, five unique call stacks leading to different memory safety errors in the same file is potentially more worrisome than one error that hits many times. The summary looks like this: + +```cmd +=== Files in priority order === + +File: D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp Unique call stacks: 1 +File: C:\Users\xxx\Desktop\COE\doublefree.cpp Unique call stacks: 1 +``` + +Finally, the report contains a summary of where the memory errors occurred: + +```cmd +=== Source Code Details: Unique errors caught at instruction offset from source line number, in functions, in the same file. === + +File: D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp + Func: free() + Line: 69 Unique call stacks (paths) leading to error at line 69 : 1 + Bug: double-free at instr 19 bytes from start of line +File: C:\Users\xxx\Desktop\COE\doublefree.cpp + Func: main() + Line: 18 Unique call stacks (paths) leading to error at line 18 : 1 + Bug: heap-use-after-free at instr 55 bytes from start of line + +>>>Total: 2 Unique Memory Safety Issues (based on call stacks not source position) <<< + +#0 C:\Users\xxx\Desktop\COE\doublefree.cpp Function: main(Line:18) + Raw HitCnt: 1 On Reference: 4-byte-read-heap-use-after-free +#1 D:\a\_work\1\s\src\vctools\asan\llvm\compiler-rt\lib\asan\asan_malloc_win_thunk.cpp Function: free(Line:69) + Raw HitCnt: 1 +``` + +## Out of bounds memory access example + +In this example, you create a build with ASAN enabled to test what happens when an app access memory that is out-of-bounds. ASAN detects this error and reports a summary of the errors to `stdout` when the program exits. + +Create the example: + +1. Open a developer command prompt: open the **Start** menu, type *Developer*, and select the latest command prompt such as **Developer Command Prompt for VS 2022** from the list of matches. +1. Create a directory on your machine to run this example. For example, `%USERPROFILE%\Desktop\COE`. +1. In that directory, create a source file, for example, `coe.cpp`, and paste the following code: + + ```cpp + #include + + char* func(char* buf, size_t sz) + { + char* local = (char*)malloc(sz); + for (auto ii = 0; ii <= sz; ii++) // bad loop exit test + { + local[ii] = ~buf[ii]; // Two memory safety errors + } + + return local; + } + + char buffer[10] = {0,1,2,3,4,5,6,7,8,9}; + + int main() + { + char* inverted_buf= func(buffer, 10); + } + ``` + +In the preceding code, the parameter `sz` is 10 and the original buffer is 10 bytes. There are two memory safety errors: + +- an out-of-bounds load from `buf` in the `for` loop +- an out-of-bounds store to `local` in the `for` loop + +The buffer overflow is due to the loop exit test `<=sz`. When this example runs, it's *secure by coincidence*. That's because of the over-allocation and alignment done by most C++ runtime implementations. When `sz % 16 == 0`, the final write to `local[ii]` corrupts memory. Other cases only read/write to the "malloc slop," which is extra memory allocated due to the way the C Runtime (CRT) pads allocations to a 0 mod 16 boundary. + +Errors are only observable if the page following the allocation is unmapped, or upon use of corrupted data. All other cases are silent in this example. With Continue On Error, the errors are made visible in the summary after the program runs to completion. + +Create a build of the preceding code with COE turned on: + +1. Compile the code with `cl -fsanitize=address -Zi coe.cpp`. The `-fsanitize=address` switch turns on ASAN, and `-Zi` creates a separate PDB file that address sanitizer uses to display memory error location information. +1. Send ASAN output to `stdout` by setting the `ASAN_OPTIONS` environment variable in the developer command prompt as follows: `set ASAN_OPTIONS=continue_on_error=1` +1. Run the test code with: `coe.exe` + +The output shows that there were two memory buffer overflow errors and provides the call stack for where they happened. The report starts out like this: + +```cmd +==9776==ERROR: AddressSanitizer: global-buffer-overflow on address 0x0047b08a at pc 0x003c121b bp 0x012ffaec sp 0x012ffae0 +READ of size 1 at 0x0047b08a thread T0 + #0 func C:\Users\xxx\Desktop\COE\coe.cpp(8) + #1 main C:\Users\xxx\Desktop\COE\coe.cpp(18) + #2 __scrt_common_main_seh D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288) + #3 BaseThreadInitThunk Windows + #4 RtlInitializeExceptionChain Windows +``` + +Next, there's information about the shadow bytes in the vicinity of the buffer overflow. For more information about shadow bytes, see [AddressSanitizer shadow bytes](asan-shadow-bytes.md). + +Following the shadow byte report, there's a summary of the source files where the memory errors happened. It's sorted by the unique call stacks for the memory errors in that file. A unique call stack is determined by the type of error and the call stack where the error occurred. + +This sorting prioritizes memory safety issues that may be the most concerning. For example, five unique call stacks leading to different memory safety errors in the same file is potentially more worrisome than one error that hits many times. + +The summary looks like this: + +```cmd +=== Files in priority order === + +File: C:\Users\xxx\Desktop\COE\coe.cpp Unique call stacks: 2 +``` + +Finally, the report contains a summary of where the memory errors occurred. Continue On Error reports two distinct errors that occur on the same source line. The first error reads memory at a global address in the `.data` section, and the other writes to memory allocated from the heap. + +The report looks like this: + +```cmd +=== Source Code Details: Unique errors caught at instruction offset from source line number, in functions, in the same file. === + +File: C:\Users\xxx\Desktop\COE\coe.cpp + Func: func() + Line: 8 Unique call stacks (paths) leading to error at line 8 : 2 + Bug: heap-buffer-overflow at instr 124 bytes from start of line + +>>>Total: 2 Unique Memory Safety Issues (based on call stacks not source position) <<< + +#0 C:\Users\xxx\Desktop\COE\coe.cpp Function: func(Line:8) + Raw HitCnt: 1 On Reference: 1-byte-read-global-buffer-overflow +#1 C:\Users\xxx\Desktop\COE\coe.cpp Function: func(Line:8) + Raw HitCnt: 1 On Reference: 1-byte-write-heap-buffer-overflow +``` + +The default Address Sanitizer runtime behavior terminates the app after reporting the first error it finds. It doesn't allow the "bad" machine instruction to execute. The new Address Sanitizer runtime diagnoses and reports errors, but then executes subsequent instructions. + +COE tries to automatically return control back to the application after reporting each memory safety error. There are situations when it can't, such as when there's a memory access violation (AV) or a failed memory allocation. COE doesn't continue after access violations that the program's structured exception handling doesn't catch. If COE can't return execution to the app, a `CONTINUE CANCELLED - Deadly Signal. Shutting down.` message is output. + +## Select where to send ASAN output + +Use the `ASAN_OPTIONS` environment variable to determine where to send ASAN output as follows: + +- Output to stdout: `set ASAN_OPTIONS=continue_on_error=1` +- Output to stderr: `set ASAN_OPTIONS=continue_on_error=2` +- Output to a log file of your choice: `set COE_LOG_FILE=yourfile.log` + +## Handling undefined behavior + +The ASAN runtime doesn't mimic all of the undefined behaviors of the C and C++ allocation/deallocation functions. The following example demonstrates how the ASAN version of **_alloca** differs from the C runtime version: + +```cpp +#include +#include +#include +#include +#include + +#define RET_FINISH 0 +#define RET_STACK_EXCEPTION 1 +#define RET_OTHER_EXCEPTION 2 + +int foo_redundant(unsigned long arg_var) +{ + char *a; + int ret = -1; + + __try + { + if ((arg_var+3) > arg_var) + { + // Call to _alloca using parameter from main + a = (char *) _alloca(arg_var); + memset(a, 0, 10); + } + ret = RET_FINISH; + } + __except(1) + { + ret = RET_OTHER_EXCEPTION; + int i = GetExceptionCode(); + if (i == EXCEPTION_STACK_OVERFLOW) + { + ret = RET_STACK_EXCEPTION; + } + } + return ret; +} + +int main() +{ + int cnt = 0; + + if (foo_redundant(0xfffffff0) == RET_STACK_EXCEPTION) + { + cnt++; + } + + if (cnt == 1) + { + printf("pass\n"); + } + else + { + printf("fail\n"); + } +} +``` + +In `main()` a large number is passed to `foo_redundant`, which is ultimately passed to `_alloca()`, which causes `_alloca()` to fail. + +This example outputs `pass` when compiled without ASAN (that is, no `-fsanitize=address` switch) but outputs `fail` when compiled with ASAN turned on (that is, with the `-fsanitize=address` switch). That's because without ASAN, the exception code matches `RET_STACK_EXCEPTION` so `cnt` is set to 1. It behaves differently when compiled with ASAN on because the thrown exception is an Address Sanitizer error instead: dynamic-stack-buffer-overflow. That means the code returns `RET_OTHER_EXCEPTION` instead of `RET_STACK_EXCEPTION` so `cnt` isn't set to 1. + +## Other benefits + +With the new ASAN runtime, no extra binaries need to be deployed with your app. This makes it even easier to use ASAN with your normal test harness because you don't have to manage extra binaries. + +## See also + +[AddressSanitizer Continue on Error blog post](https://devblogs.microsoft.com/cppblog/addresssanitizer-continue_on_error)\ +[Example memory safety errors](asan.md#error-types)\ +[-Zi compiler flag](../build/reference/z7-zi-zi-debug-information-format.md#zi)\ +[-fsanitize=address compiler flag](../build/reference/fsanitize.md)\ +[Top 25 most dangerous software weaknesses](https://cwe.mitre.org/top25/archive/2021/2021_cwe_top25.html) diff --git a/docs/sanitizers/asan-debugger-integration.md b/docs/sanitizers/asan-debugger-integration.md index f75d648ac4..8232ebff54 100644 --- a/docs/sanitizers/asan-debugger-integration.md +++ b/docs/sanitizers/asan-debugger-integration.md @@ -34,10 +34,21 @@ When you link the VCAsan library to your executable, users can enable it to gene `set ASAN_SAVE_DUMPS=MyFileName.dmp` -The file must have a .dmp suffix to follow the Visual Studio IDE conventions. +The file must have a `.dmp` extension to follow the Visual Studio IDE conventions. (Prior to 17.7) Here's what happens when a dump file is specified for `ASAN_SAVE_DUMPS`: If an error gets caught by the AddressSanitizer runtime, it saves a crash dump file that has the metadata associated with the error. The debugger in Visual Studio version 16.9 and later can parse the metadata that's saved in the dump file. You can set `ASAN_SAVE_DUMPS` on a per-test basis, store these binary artifacts, and then view them in the IDE with proper source indexing. +Visual Studio version 17.7 and later supports the following: + +* Quoted strings are now handled correctly. In previous versions, for environments inside of Visual Studio or when using PowerShell, setting the environment variable to contain quotes or spaces would fail to create the expected dump file. + +* When the `.dmp` extension is explicitly specified (for example, `set ASAN_SAVE_DUMPS=MyDmp.dmp`), VCAsan uses it explicitly, and will not add an associated process ID to the dump file name. + +* If a `.dmp` file already exists with the same name specified from the environment variable, VCAsan modifies the file name as follows: + * Appends a number to the filename in parentheses. For example, `Myfile (1).dmp`. + * If after several attempts appending a number in parentheses fails to generate a unique name, the file is saved to an `%APPLOCAL%` temporary path that VCAsan will print. For example, `C:\Users\~\AppData\Local\Temp\Dump.dmp`. + * If saving to a temporary path fails, a diagnostic error is displayed. + ## See also [AddressSanitizer overview](./asan.md)\ @@ -47,3 +58,4 @@ Here's what happens when a dump file is specified for `ASAN_SAVE_DUMPS`: If an e [AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ [AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ [AddressSanitizer error examples](./asan-error-examples.md) + diff --git a/docs/sanitizers/asan-error-examples.md b/docs/sanitizers/asan-error-examples.md index 9eecb62b0d..4ad5aca856 100644 --- a/docs/sanitizers/asan-error-examples.md +++ b/docs/sanitizers/asan-error-examples.md @@ -20,6 +20,8 @@ Each error example provides source code and compilation instructions for a comma - [Error: `calloc-overflow`](./error-calloc-overflow.md) +- [Error: `container-overflow`](./error-container-overflow.md) + - [Error: `double-free`](./error-double-free.md) - [Error: `dynamic-stack-buffer-overflow`](./error-dynamic-stack-buffer-overflow.md) diff --git a/docs/sanitizers/asan-known-issues.md b/docs/sanitizers/asan-known-issues.md index f22b867712..6bcd8df0ea 100644 --- a/docs/sanitizers/asan-known-issues.md +++ b/docs/sanitizers/asan-known-issues.md @@ -1,18 +1,18 @@ --- -title: "AddressSanitizer known issues" +title: "AddressSanitizer known issues and limitations" description: "Technical description of the AddressSanitizer for Microsoft C/C++ known issues." -ms.date: 03/02/2021 +ms.date: 5/21/2025 helpviewer_keywords: ["AddressSanitizer known issues"] --- -# AddressSanitizer known issues +# AddressSanitizer known issues and limitations > [!NOTE] > Send us [feedback](https://aka.ms/vsfeedback/browsecpp) on what you'd like to see in future releases, and [report bugs](https://aka.ms/feedback/report?space=62) if you run into issues. ## Incompatible options and functionality -These options and functionality are incompatible with [`/fsanitize=address`](../build/reference/fsanitize.md) and should be disabled or avoided. +The following options and functionality are incompatible with [`/fsanitize=address`](../build/reference/fsanitize.md) and should be disabled or avoided. - The [`/RTC`](../build/reference/rtc-run-time-error-checks.md) options are incompatible with AddressSanitizer and should be disabled. - [Incremental linking](../build/reference/incremental-link-incrementally.md) is unsupported, and should be disabled. @@ -26,9 +26,11 @@ These options and functionality are incompatible with [`/fsanitize=address`](../ ## Standard library support -The MSVC standard library (STL) isn't enlightened to understand the AddressSanitizer. AddressSanitizer exceptions raised in STL code do identify true bugs. However, they aren't as precise as they could be. +The MSVC standard library (STL) makes partial use of the AddressSanitizer and provides other code safety checks. For more information, see [container-overflow error](./error-container-overflow.md). -This example demonstrates the lack of precision: +When annotations are disabled, or in versions of the Standard Library that don't support them, AddressSanitizer exceptions raised in STL code still identify real bugs. However, they are more precise if annotations are enabled and you use a version of the Standard Library that supports them. + +This example demonstrates the lack of precision and the benefits of enabling annotations: ```cpp // Compile with: cl /fsanitize=address /Zi @@ -39,41 +41,58 @@ int main() { std::vector v(10); v.reserve(20); - // Currently, MSVC ASan does NOT raise an exception here. + // In versions prior to 17.2, MSVC ASan does NOT raise an exception here. // While this is an out-of-bounds write to 'v', MSVC ASan // ensures the write is within the heap allocation size (20). + // With 17.2 and later, MSVC ASan will raise a 'container-overflow' exception: + // ==18364==ERROR: AddressSanitizer: container-overflow on address 0x1263cb8a0048 at pc 0x7ff6466411ab bp 0x005cf81ef7b0 sp 0x005cf81ef7b8 v[10] = 1; - // MSVC ASan DOES raise an exception here, as this write + // Regardless of version, MSVC ASan DOES raise an exception here, as this write // is out of bounds from the heap allocation. v[20] = 1; } ``` -## Windows versions +## Overriding operator new and delete + +AddressSanitizer (ASAN) uses a custom version of `operator new` and `operator delete` to find allocation errors like [`alloc_dealloc_mismatch`](error-alloc-dealloc-mismatch.md). Running the linker with [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) ensures that ASAN's `new`/`delete` override has low precedence, so that the linker chooses any `operator new` or `operator delete` overrides in other libraries over ASAN's custom versions. When this happens, ASAN may not be able to catch some errors that rely on its custom `operator new` and `operator delete`. + +[MFC](../mfc/mfc-concepts.md) includes custom overrides for `operator new` and `operator delete` and might miss errors like [`alloc_dealloc_mismatch`](error-alloc-dealloc-mismatch.md). -As there are dependencies with specific Windows versions, support is focused on Windows 10. MSVC AddressSanitizer was tested on 10.0.14393 (RS1), and 10.0.21323 (pre-release insider build). [Report a bug](https://aka.ms/feedback/report?space=62) if you run into issues. ## Memory usage -The AddressSanitizer runtime doesn't release memory back to the OS during execution. From the OS's point of view, it may look like there's a memory leak. This design decision is intentional, so as not to allocate all the required memory up front. +The AddressSanitizer runtime doesn't release memory back to the OS during execution. From the OS's point of view, it may look like there's a memory leak. This is intentional so that the memory isn't all allocated up front. ## AddressSanitizer runtime DLL locations -The *`clang_rt.asan*.dll`* runtime files are installed next to the compilers in *`%VSINSTALLDIR%\VC\Tools\MSVC\\bin\\\`*. These locations are on the path in debugging sessions, and in Visual Studio developer command prompts. These files are never placed in *`C:\Windows\System32`* or *`C:\Windows\SysWOW64`*. +The *`clang_rt.asan*.dll`* runtime files are installed next to the compilers in *`%VSINSTALLDIR%\VC\Tools\MSVC\\bin\\\`*. These locations are on the path in debugging sessions and in Visual Studio developer command prompts. These files are never placed in *`C:\Windows\System32`* or *`C:\Windows\SysWOW64`*. ## Custom property sheet support -The Property Manager window in the Visual Studio IDE allows you to add custom *`.props`* files to your projects. Even though the **Enable Address Sanitizer** property (``) is shown, it's not honored by the build. That's because the custom *`.props`* files get included after *`Microsoft.cpp.props`*, which uses the `` value to set other properties. +The Visual Studio Property Manager window allows you to add custom *`.props`* files to your projects. Even though the **Enable Address Sanitizer** property (``) is shown, the build doesn't honor it. That's because the custom *`.props`* files are included after *`Microsoft.cpp.props`*, which uses the `` value to set other properties. + +As a workaround, create a *`Directory.Build.props`* file in the root of your project to define the `` property. For more information, see [Customize C++ builds](/visualstudio/msbuild/customize-your-build#customize-c-builds). + +## Thread local variables + +Thread local variables (global variables declared with `__declspec(thread)` or `thread_local`) aren't protected by AddressSanitizer. This limitation isn't specific to Windows or Microsoft Visual C++, but is a general limitation. + +## Issues with partially sanitized executables + +If all of the code in a process isn't compiled with `/fsanitize=address`, ASan may not be able to diagnose all memory safety errors. The most common example is when a DLL is compiled with ASan but is loaded into a process that contains code that wasn't compiled with ASan. In this case, ASan attempts to categorize allocations that took place prior to ASan initialization. Once those allocations are reallocated, ASan tries to own and monitor the lifetime of the memory. + +If all of the DLLs that were compiled with ASan are unloaded from the process before the process ends, there may be crashes due to dangling references to intercepted functions such as `memcmp`, `memcpy`, `memmove`, and so on. For the best results, compile all modules under test with `/fsanitize=address`, or do not unload modules compiled with ASan after they enter the process. -As a workaround, you can create a *`Directory.Build.props`* file in the root of your project to define the `` property. For more information, see [Customize C++ builds](/visualstudio/msbuild/customize-your-build#customize-c-builds). +Please report any bugs to our [Developer Community](https://aka.ms/feedback/report?space=62). ## See also -[AddressSanitizer overview](./asan.md)\ -[AddressSanitizer build and language reference](./asan-building.md)\ -[AddressSanitizer runtime reference](./asan-runtime.md)\ -[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ -[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ -[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ -[AddressSanitizer error examples](./asan-error-examples.md) +[AddressSanitizer overview](asan.md)\ +[AddressSanitizer build and language reference](asan-building.md)\ +[AddressSanitizer runtime reference](asan-runtime.md)\ +[AddressSanitizer shadow bytes](asan-shadow-bytes.md)\ +[AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\ +[AddressSanitizer debugger integration](asan-debugger-integration.md)\ +[AddressSanitizer error examples](asan-error-examples.md) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 9e5242c605..88d62f6be7 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -1,7 +1,7 @@ --- title: "AddressSanitizer runtime" description: "Technical description of the AddressSanitizer runtime for Microsoft C/C++." -ms.date: 03/02/2021 +ms.date: 02/05/2024 helpviewer_keywords: ["AddressSanitizer runtime", "Address Sanitizer runtime", "clang_rt.asan", "Clang runtime", "ASan runtime"] --- @@ -9,25 +9,59 @@ helpviewer_keywords: ["AddressSanitizer runtime", "Address Sanitizer runtime", " The AddressSanitizer runtime library intercepts common memory allocation functions and operations to enable inspection of memory accesses. There are several different runtime libraries that support the various types of executables the compiler may generate. The compiler and linker automatically link the appropriate runtime libraries, as long as you pass the [`/fsanitize=address`](../build/reference/fsanitize.md) option at compile time. You can override the default behavior by using the **`/NODEFAULTLIB`** option at link time. For more information, see the section on [linking](./asan-building.md#linker) in the [AddressSanitizer language, build, and debugging reference](./asan-building.md). -Below is an inventory of runtime libraries for linking to the AddressSanitizer runtime, where *`{arch}`* is either *`i386`* or *`x86_64`*. +When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check [shadow bytes](./asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time. + +The list of runtime libraries for linking to the AddressSanitizer runtime, as of Visual Studio 17.7 Preview 3, follows. For more information about the `/MT` (statically link the runtime) and `/MD` (dynamically link the redist at runtime) options, see [/MD, /MT, /LD (Use Run-Time Library)](../build/reference/md-mt-ld-use-run-time-library.md). > [!NOTE] -> These libraries keep the Clang conventions for architecture names. The MSVC conventions are normally x86 and x64 rather than i386 and x86_64. They refer to the same architectures. +> In the following table, *`{arch}`* is either *`i386`* or *`x86_64`*. +> These libraries use Clang conventions for architecture names. MSVC conventions are normally `x86` and `x64` rather than `i386` and `x86_64`, but they refer to the same architectures. + +| CRT option | AddressSanitizer runtime library (.lib) | Address runtime binary (.dll) +|--|--|--| +| `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_static_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* +| `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* + +The following diagram shows how the language runtime libraries are linked for the `/MT`, `/MTd`, `/MD`, and `/MDd` compiler options: + +:::image type="complex" source="media/runtime-configurations.png" alt-text="Diagram of how the runtime libraries are linked for various compiler options." +The image shows three scenarios for linking the runtime library. The first is /MT or /MTd. My_exe.exe and my_dll.dll are both shown with their own copies of the statically linked VCRuntime, Universal CRT, and C++ runtimes. The scenarios show /MD in which both my_exe.exe and my_dll.dll share vcruntime140.dll, ucrtbase.dll, and msvcp140.dll. The last scenario shows /MDd in which both my_exe.exe and my_dll.dll share the debug versions of the runtimes: vcruntime140d.dll, ucrtbased.dll, and msvcp140d.dll +:::image-end::: + +The following diagram shows how the ASan library is linked for various compiler options: + +:::image type="complex" source="media/asan-one-dll.png" alt-text="Diagram of how the ASan runtime dll is linked." +The image shows four scenarios for linking the ASan runtime library. The scenarios are for /MT (statically link the runtime), /MTd (statically link the debug runtime), /MD (dynamically link the redist at runtime), /MDd (dynamically link the debug redist at runtime). In all cases, my_exe.exe links and its associates my_dll.dll link to a single instance of clang-rt.asan-dynamix-x86_64.dll. +:::image-end::: + +Even when statically linking, the ASan runtime DLL must be present at runtime--unlike other C Runtime components. + +### Previous versions -| CRT option | DLL or EXE | DEBUG? | AddressSanitizer runtime binaries libraries | -|--|--|--|--| -| MT | EXE | NO | *`clang_rt.asan-{arch}`*, *`clang_rt.asan_cxx-{arch}`* | -| MT | DLL | NO | *`clang_rt.asan_dll_thunk-{arch}`* | -| MD | EITHER | NO | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | -| MT | EXE | YES | *`clang_rt.asan_dbg-{arch}`*, *`clang_rt.asan_dbg_cxx-{arch}`* | -| MT | DLL | YES | *`clang_rt.asan_dbg_dll_thunk-{arch}`* | -| MD | EITHER | YES | *`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`* | +Before Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`**) builds didn't use a DLL dependency. Instead, the AddressSanitizer runtime was statically linked into the user's EXE. DLL projects would then load exports from the user's EXE to access ASan functionality. -When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check the [shadow bytes](./asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time. +Dynamically linked projects (**`/MD`** or **`/MDd`**) used different libraries and DLLs depending on whether the project was configured for debug or release. For more information about these changes and their motivations, see [MSVC Address Sanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/). + +The following table describes the previous behavior of the AddressSanitizer runtime library linking, before Visual Studio 17.7 Preview 3: + +| CRT option | DLL or EXE | DEBUG? | ASan library (`.lib`) | ASan runtime binary (`.dll`) | +|--|--|--|--|--| +| `/MT` | EXE | No | *`clang_rt.asan-{arch}`*, *`clang_rt.asan_cxx-{arch}`* | None +| `/MT` | DLL | No | *`clang_rt.asan_dll_thunk-{arch}`* | None +| `/MD` | Either | No | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* +| `/MT` | EXE | Yes | *`clang_rt.asan_dbg-{arch}`*, *`clang_rt.asan_dbg_cxx-{arch}`* | None +| `/MT` | DLL | Yes | *`clang_rt.asan_dbg_dll_thunk-{arch}`* | None +| `/MD` | Either | Yes | *`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`* | *`clang_rt.asan_dbg_dynamic-{arch}`* + +The following diagram shows how the ASan library was linked for various compiler options before Visual Studio 2022 17.7 Preview 3: + +:::image type="complex" source="media/asan-library-linking-previous-versions.png" alt-text="Diagram of how the ASan runtime dll was linked prior to Visual Studio 2022 Preview 3." +The image shows four scenarios for linking the ASan runtime library. The scenarios are for /MT (statically link the runtime), /MTd (statically link the debug runtime), /MD (dynamically link the redist at runtime), /MDd (dynamically link the debug redist at runtime). For /MT, my_exe.exe has a statically linked copy of the ASan runtime. my_dll.dll links to the ASan runtime in my_exe.exe. For /MTd, the diagram is the same except it uses the debug statically linked ASan runtime. For /MD, both my_exe.exe and my_dll.dll link to the dynamically linked ASan runtime named clang_rt.asan_dynamic-x86_64.dll. For /MDd, the diagram is the same except my_exe.exe and my_dll.dll link to the debug ASan runtime named clang_rt.asan_dbg_dynamic-x86_64.dll. +:::image-end::: ## Function interception -The AddressSanitizer achieves function interception through many hot-patching techniques. These techniques are [best documented within the source code itself](https://github.com/llvm/llvm-project/blob/1a2eaebc09c6a200f93b8beb37130c8b8aab3934/compiler-rt/lib/interception/interception_win.cpp#L11). +The AddressSanitizer achieves function interception through many hotpatching techniques. These techniques are [best documented within the source code itself](https://github.com/llvm/llvm-project/blob/1a2eaebc09c6a200f93b8beb37130c8b8aab3934/compiler-rt/lib/interception/interception_win.cpp#L11). The runtime libraries intercept many common memory management and memory manipulation functions. For a list, see [AddressSanitizer list of intercepted functions](#intercepted_functions). The allocation interceptors manage metadata and shadow bytes related to each allocation call. Every time a CRT function such as `malloc` or `delete` is called, the interceptors set specific values in the AddressSanitizer shadow-memory region to indicate whether those heap locations are currently accessible and what the bounds of the allocation are. These shadow bytes allow the compiler-generated checks of the [shadow bytes](./asan-shadow-bytes.md) to determine whether a load or store is valid. @@ -74,21 +108,33 @@ Microsoft C/C++ (MSVC) uses a runtime based on the [Clang AddressSanitizer runti > [!NOTE] > The AddressSanitizer runtime option `halt_on_error` doesn't function the way you might expect. In both the Clang and the MSVC runtime libraries, many error types are considered **non-continuable**, including most memory corruption errors. -For more information, see the [Differences with Clang 12.0](./asan.md#differences) section. +For more information, see the [Differences with Clang 12.0](asan.md#differences) section. ### MSVC-specific AddressSanitizer runtime options - `windows_hook_legacy_allocators` - Boolean, set to `true` to enable interception of [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) and [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) allocators. + Boolean, set to `false` to disable interception of [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) and [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) allocators. -> [!NOTE] -> The option `windows_hook_legacy_allocators` wasn't available in the public llvm-project runtime when this article was written. The option may eventually be contributed back to the public project; however, it's dependent on code review and community acceptance. -> -> The option `windows_hook_rtl_allocators`, previously an opt-in feature while AddressSanitizer was experimental, is now enabled by default. + > [!NOTE] + > The option `windows_hook_legacy_allocators` wasn't available in the public llvm-project runtime when this article was written. The option may eventually be contributed back to the public project; however, it's dependent on code review and community acceptance. + > + > The option `windows_hook_rtl_allocators`, previously an opt-in feature while AddressSanitizer was experimental, is now enabled by default. In versions before Visual Studio 2022 version 17.4.6, the default option value is `false`. In Visual Studio 2022 version 17.4.6 and later versions, the option `windows_hook_rtl_allocators` defaults to `true`. + +- `iat_overwrite` + String, set to `"error"` by default. Other possible values are `"protect"` and `"ignore"`. Some modules may overwrite the [`import address table`](/windows/win32/debug/pe-format#import-address-table) of other modules to customize implementations of certain functions. For example, drivers commonly provide custom implementations for specific hardware. The `iat_overwrite` option manages the AddressSanitizer runtime's protection against overwrites for specific [`memoryapi.h`](/windows/win32/api/memoryapi/) functions. The runtime currently tracks the [`VirtualAlloc`](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc), [`VirtualProtect`](/windows/win32/api/memoryapi/nf-memoryapi-virtualprotect), and [`VirtualQuery`](/windows/win32/api/memoryapi/nf-memoryapi-virtualquery) functions for protection. This option is available in Visual Studio 2022 version 17.5 Preview 1 and later versions. The following `iat_overwrite` values control how the runtime reacts when protected functions are overwritten: + + - If set to `"error"` (the default), the runtime reports an error whenever an overwrite is detected. + - If set to `"protect"`, the runtime attempts to avoid using the overwritten definition and proceeds. Effectively, the original `memoryapi` definition of the function is used from inside the runtime to avoid infinite recursion. Other modules in the process still use the overwritten definition. + - If set to `"ignore"`, the runtime doesn't attempt to correct any overwritten functions and proceeds with execution. + +- `windows_fast_fail_on_error` +Boolean (false by default), set to `true` to enable the process to terminate with a __fastfail(71) after printing the error report. +>[!NOTE] +>When abort_on_error value is set to true, on Windows the program terminates with an exit(3). In order to not change current behavior we decided to introduce this new option instead. If both abort_on_error and windows_fast_fail_on_error are true, the program will exit with the __fastfail. ## AddressSanitizer list of intercepted functions (Windows) -The AddressSanitizer runtime hot-patches many functions to enable memory safety checks at runtime. Here's a non-exhaustive list of the functions that the AddressSanitizer runtime monitors. +The AddressSanitizer runtime hotpatches many functions to enable memory safety checks at runtime. Here's a non-exhaustive list of the functions that the AddressSanitizer runtime monitors. ### Default interceptors @@ -165,8 +211,8 @@ The AddressSanitizer runtime hot-patches many functions to enable memory safety ### Optional interceptors -The interceptors listed here are only installed when an AddressSanitizer runtime option is enabled. Set `windows_hook_legacy_allocators` to `true` to enable legacy allocator interception. -`set ASAN_OPTIONS=windows_hook_legacy_allocators=true` +The interceptors listed here are only installed when an AddressSanitizer runtime option is enabled. Set `windows_hook_legacy_allocators` to `false` to disable legacy allocator interception. +`set ASAN_OPTIONS=windows_hook_legacy_allocators=false` - [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) - [`GlobalFree`](/windows/win32/api/winbase/nf-winbase-GlobalFree) diff --git a/docs/sanitizers/asan-shadow-bytes.md b/docs/sanitizers/asan-shadow-bytes.md index 6d53b91270..9b6b747e24 100644 --- a/docs/sanitizers/asan-shadow-bytes.md +++ b/docs/sanitizers/asan-shadow-bytes.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["Shadow bytes", "AddressSanitizer shadow bytes","Address S # AddressSanitizer shadow bytes -We briefly summarize the concept of shadow bytes and how they can be used by the runtime implementation of [`/fsanitize=address`](../build/reference/fsanitize.md). For further details, we refer you to the [seminal paper](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) and the [AddressSanitizer algorithm](https://github.com/google/sanitizers/wiki/AddressSanitizerAlgorithm). +We briefly summarize the concept of shadow bytes and how they can be used by the runtime implementation of [`/fsanitize=address`](../build/reference/fsanitize.md). For further details, we refer you to the initial research [AddressSanitizer - Serebryany, et al](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) and the [current AddressSanitizer algorithm documentation](https://github.com/google/sanitizers/wiki/AddressSanitizerAlgorithm). ## Core concept diff --git a/docs/sanitizers/asan.md b/docs/sanitizers/asan.md index 01e13bfd87..2868186341 100644 --- a/docs/sanitizers/asan.md +++ b/docs/sanitizers/asan.md @@ -1,7 +1,7 @@ --- title: "AddressSanitizer" description: "Top-level description of the AddressSanitizer feature for Microsoft C/C++." -ms.date: 03/05/2021 +ms.date: 09/06/2024 f1_keywords: ["AddressSanitizer"] helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compiling for AddressSanitizer"] --- @@ -10,7 +10,7 @@ helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compilin ## Overview -The C & C++ languages are powerful, but can suffer from a class of bugs that affect program correctness and program security. Starting in Visual Studio 2019 version 16.9, the Microsoft C/C++ compiler (MSVC) and IDE supports the *AddressSanitizer*. AddressSanitizer (ASan) is a compiler and runtime technology that exposes many hard-to-find bugs with **zero** false positives: +The C & C++ languages are powerful, but can suffer from a class of bugs that affect program correctness and program security. Starting in Visual Studio 2019 version 16.9, the Microsoft C/C++ compiler (MSVC) and IDE supports the *AddressSanitizer* sanitizer. AddressSanitizer (ASan) is a compiler and runtime technology that exposes many hard-to-find bugs with **zero** false positives: - [Alloc/dealloc mismatches](error-alloc-dealloc-mismatch.md) and [`new`/`delete` type mismatches](error-new-delete-type-mismatch.md) - [Allocations too large for the heap](error-allocation-size-too-big.md) @@ -32,30 +32,28 @@ Use AddressSanitizer to reduce your time spent on: - Stress testing - Integrating new code -AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), is a powerful alternative to both [`/RTC` (Runtime error checks)](../build/reference/rtc-run-time-error-checks.md) and [`/analyze` (Static analysis)](../build/reference/analyze-code-analysis.md). It provides run-time bug-finding technologies that use your existing build systems and existing test assets directly. +AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), provides runtime bug-finding technologies that use your existing build systems and existing test assets directly. -AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: **`/fsanitize=address`**. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it's incompatible with [edit-and-continue](/visualstudio/debugger/edit-and-continue-visual-cpp), [incremental linking](../build/reference/incremental-link-incrementally.md), and [`/RTC`](../build/reference/rtc-run-time-error-checks.md). +AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: **`/fsanitize=address`**. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it isn't compatible with [edit-and-continue](/visualstudio/debugger/edit-and-continue-visual-cpp), [incremental linking](../build/reference/incremental-link-incrementally.md), and [`/RTC`](../build/reference/rtc-run-time-error-checks.md). -Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file gets created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of the AddressSanitizer easier for: +Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file is created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of AddressSanitizer easier for: -- Local machine testing, -- On-premise distributed testing, and -- Cloud-based workflows for testing. +- Local machine testing +- On-premises distributed testing +- Cloud-based workflows for testing -### Install the AddressSanitizer +### Install AddressSanitizer -The AddressSanitizer IDE integration and libraries get installed by default with C++ workloads in the Visual Studio Installer. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade: +C++ workloads in the Visual Studio Installer install the AddressSanitizer libraries and IDE integration by default. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade. You can open the installer from the Visual Studio main menu via **Tools** > **Get Tools and Features...** Choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the following screen. -:::image type="content" source="media/asan-installer-option.png" alt-text="Visual Studio Installer screenshot highlighting the C++ AddressSanitizer component"::: - -You can choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the screen above. +:::image type="content" source="media/asan-installer-option.png" alt-text="Screenshot of the Visual Studio Installer. The C++ AddressSanitizer component, under the Optional section, is highlighted."::: > [!NOTE] > If you run Visual Studio on the new update but haven't installed ASan, you'll get an error when you run your code: > > LNK1356: cannot find library 'clang_rt.asan_dynamic-i386.lib' -### Use the AddressSanitizer +### Use AddressSanitizer Start building your executables with the **`/fsanitize=address`** compiler option using any of these common development methods: @@ -65,7 +63,7 @@ Start building your executables with the **`/fsanitize=address`** compiler optio Recompile, then run your program normally. This code generation exposes [many types of precisely diagnosed bugs](#error-types). These errors get reported in three ways: in the debugger IDE, on the command line, or stored in a [new type of dump file](#crash-dumps) for precise off-line processing. -Microsoft recommends using the AddressSanitizer in these three standard workflows: +Microsoft recommends you use AddressSanitizer in these three standard workflows: - **Developer inner loop** - Visual Studio - [Command line](#command-prompt) @@ -79,16 +77,19 @@ Microsoft recommends using the AddressSanitizer in these three standard workflow - [Azure OneFuzz](https://www.microsoft.com/security/blog/2020/09/15/microsoft-onefuzz-framework-open-source-developer-tool-fix-bugs/) - Local Machine -This article covers the information you require to enable the three workflows listed above. The information is specific to the **platform-dependent** Windows 10 implementation of the AddressSanitizer. This documentation supplements the excellent documentation from [Google, Apple, and GCC](#external-docs) already published. +This article covers the information you require to enable the three workflows listed previously. The information is specific to the **platform-dependent** Windows 10 (and later) implementation of AddressSanitizer. This documentation supplements the excellent documentation from [Google, Apple, and GCC](#external-docs) already published. > [!NOTE] -> Current support is limited to x86 and x64 on Windows 10. [Send us feedback](https://aka.ms/vsfeedback/browsecpp) on what you'd like to see in future releases. Your feedback helps us prioritize other sanitizers for the future, such as **`/fsanitize=thread`**, **`/fsanitize=leak`**, **`/fsanitize=memory`**, **`/fsanitize=undefined`**, or **`/fsanitize=hwaddress`**. You can [report bugs here](https://aka.ms/feedback/report?space=62) if you run into issues. +> Support is limited to x86 and x64 on Windows 10 and later. [Send us feedback](https://aka.ms/vsfeedback/browsecpp) on what you'd like to see in future releases. Your feedback helps us prioritize other sanitizers for the future, such as **`/fsanitize=thread`**, **`/fsanitize=leak`**, **`/fsanitize=memory`**, **`/fsanitize=undefined`**, or **`/fsanitize=hwaddress`**. You can [report bugs here](https://aka.ms/feedback/report?space=62) if you run into issues. + +## Use AddressSanitizer from a developer command prompt -## Use the AddressSanitizer from a developer command prompt +Use the **`/fsanitize=address`** compiler option in a [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts) to enable compiling for the AddressSanitizer runtime. The **`/fsanitize=address`** option is compatible with existing C++ or C optimization levels (for example, `/Od`, `/O1`, `/O2`, and `/O2 /GL`). The option works with static and dynamic CRTs (for example, `/MD`, `/MDd`, `/MT`, and `/MTd`). It works whether you create an EXE or a DLL. Debug information is required for optimal formatting of call stacks. In the following example, `cl /fsanitize=address /Zi` is passed on the command line. -Use the **`/fsanitize=address`** compiler option in a [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts) to enable compiling for the AddressSanitizer runtime. The **`/fsanitize=address`** option is compatible with all existing C++ or C optimization levels (for example, `/Od`, `/O1`, `/O2`, `/O2 /GL`, and `PGO`). The option works with static and dynamic CRTs (for example, `/MD`, `/MDd`, `/MT`, and `/MTd`). It works whether you create an EXE or a DLL. Debug information is required for optimal formatting of call stacks. In the example below, `cl /fsanitize=address /Zi` is passed on the command line. +> [!NOTE] +> AddressSanitizer doesn't support Profile-guided optimization (PGO). AddressSanitizer shouldn't be used in production. -The AddressSanitizer libraries (.lib files) get linked for you automatically. For more information, see [AddressSanitizer language, build, and debugging reference](asan-building.md). +The AddressSanitizer libraries (.lib files) are linked for you automatically. For more information, see [AddressSanitizer language, build, and debugging reference](asan-building.md). ### Example - basic global buffer overflow @@ -105,13 +106,15 @@ int main() { Using a developer command prompt for Visual Studio 2019, compile *`main.cpp`* using `/fsanitize=address /Zi` -:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options."::: +:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options. The command is: `cl main.cpp -faanitize-address /Zi`."::: -When you run the resulting *`main.exe`* at the command line, it creates the formatted error report seen below. +When you run the resulting *`main.exe`* at the command line, it creates the formatted error report that follows. Consider the overlaid, red boxes that highlight seven key pieces of information: -:::image type="content" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error."::: +:::image type="complex" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error."::: +There are seven red highlights identifying key pieces of information in the error report. They map to the numbered list that follows this screenshot. The numbered boxes highlight the following text: 1) global-buffer-overflow 2) WRITE of size 4 3) basic-global-overflow.cpp 7 4) to the right of global variable 'x' defined in 'basic-global-overflow.cpp:3:8' 5) of size 400 6) 00 00[f9]f9 f9 7) Box is in the shadow byte legend area and contains Global redzone: f9 +:::image-end::: ### Red highlights, from top to bottom @@ -126,9 +129,9 @@ Consider the overlaid, red boxes that highlight seven key pieces of information: > [!NOTE] > The function names in the call stack are produced through the [LLVM symbolizer](https://llvm.org/docs/CommandGuide/llvm-symbolizer.html) that's invoked by the runtime upon error. -## Use the AddressSanitizer in Visual Studio +## Use AddressSanitizer in Visual Studio -AddressSanitizer is integrated with the Visual Studio IDE. To turn on the AddressSanitizer for an MSBuild project, right-click on the project in Solution Explorer and choose **Properties**. In the **Property Pages** dialog, select **Configuration Properties** > **C/C++** > **General**, then modify the **Enable AddressSanitizer** property. Choose **OK** to save your changes. +AddressSanitizer is integrated with the Visual Studio IDE. To turn on AddressSanitizer for an MSBuild project, right-click on the project in Solution Explorer and choose **Properties**. In the **Property Pages** dialog, select **Configuration Properties** > **C/C++** > **General**, then modify the **Enable AddressSanitizer** property. Choose **OK** to save your changes. :::image type="content" source="media/asan-project-system-dialog.png" alt-text="Screenshot of the Property Pages dialog showing the Enable AddressSanitizer property."::: @@ -138,37 +141,91 @@ To build from the IDE, opt out of any [incompatible options](./asan-known-issues - Turn off [`/RTC1` (runtime checks)](../build/reference/rtc-run-time-error-checks.md) - Turn off [`/INCREMENTAL` (incremental linking)](../build/reference/incremental-link-incrementally.md) -To build and run the debugger, enter **F5**. You'll see this window in Visual Studio: +To build and run the debugger, press **F5**. An **Exception Thrown** window appears in Visual Studio: :::image type="content" source="media/asan-global-buffer-overflow-F5.png" alt-text="Screenshot of the debugger showing a global buffer overflow error."::: -## Using the AddressSanitizer from Visual Studio: CMake +## Use AddressSanitizer from Visual Studio: CMake -To enable the AddressSanitizer for [a CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), take these steps: +To enable AddressSanitizer for a [CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), follow these steps: 1. Open the **Configurations** dropdown in the toolbar at the top of the IDE and select **Manage Configurations**. - :::image type="content" source="media/asan-cmake-configuration-dropdown.png" alt-text="Screenshot of the CMake configuration dropdown."::: + :::image type="content" source="media/asan-cmake-configuration-drop-down.png" alt-text="Screenshot of the CMake configuration dropdown. It displays options like x64 Debug, x64 Release, and so on. At the bottom of the list, Manage Configurations... is highlighted."::: - That selection opens the CMake Project Settings editor, which is saved in a CMakeSettings.json file. + That opens the CMake Project Settings editor, which reflects the contents of your project's `CMakeSettings.json` file. 1. Choose the **Edit JSON** link in the editor. This selection switches the view to raw JSON. -1. Add the property: **“addressSanitizerEnabled”: true** - - This image is of CMakeSettings.json after that change: - - :::image type="content" source="media/asan-cmake-json.png" alt-text="Screenshot of the text editor view of CMakeSettings.json."::: - -1. Enter **Ctrl+S** to save this JSON file, then enter **F5** to recompile and run under the debugger. - -This screenshot captures the error from the CMake build. - -:::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of the CMake build error message."::: - +1. Add the following snippet to the `"windows-base"` preset, inside `"configurePresets":` to turn on Address Sanitizer: + + ```json + "environment": { + "CFLAGS": "/fsanitize=address", + "CXXFLAGS": "/fsanitize=address" + } + ``` + + `"configurePresets"` looks something like this, afterwards: + + ```json + "configurePresets": [ + { + "name": "windows-base", + "hidden": true, + "generator": "Ninja", + "binaryDir": "${sourceDir}/out/build/${presetName}", + "installDir": "${sourceDir}/out/install/${presetName}", + "cacheVariables": { + "CMAKE_C_COMPILER": "cl.exe", + "CMAKE_CXX_COMPILER": "cl.exe" + }, + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + }, + "environment": { + "CFLAGS": "/fsanitize=address", + "CXXFLAGS": "/fsanitize=address" + } + }, + ``` + +1. Address sanitizer doesn't work if edit-and-continue is specified (`/ZI`), which is enabled by default for new CMake projects. In `CMakeLists.txt`, comment out (prefix with `#`) the line that starts with `set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT"`. That line looks something like this, afterwards: + + ```json + # set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$,$>,$<$:EditAndContinue>,$<$:ProgramDatabase>>") + ``` + +1. Enter **Ctrl+S** to save this JSON file +1. Clear your CMake cache directory and reconfigure by choosing from the Visual Studio menu: **Project** > **Delete cache and Reconfigure**. Choose **Yes** when the prompt appears to clear your cache directory and reconfigure. +1. Replace the contents of the source file (for example, `CMakeProject1.cpp`) with the following: + + ```cpp + // CMakeProject1.cpp : Defines the entry point for the application + + #include + + int x[100]; + + int main() + { + printf("Hello!\n"); + x[100] = 5; // Boom! + return 0; + } + ``` + +1. Choose **F5** to recompile and run under the debugger. + + This screenshot captures the error from the CMake build. + + :::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of an exception that says: Address Sanitizer Error: Global buffer overflow. In the background, address sanitizer output is visible in command window."::: + ## AddressSanitizer crash dumps -We introduced new functionality in the AddressSanitizer for use with cloud and distributed workflows. This functionality allows offline viewing of an AddressSanitizer error in the IDE. The error gets overlaid on top of your source, just as you would experience in a live debug session. +We introduced new functionality in AddressSanitizer for use with cloud and distributed workflows. This functionality allows offline viewing of an AddressSanitizer error in the IDE. The error gets overlaid on top of your source, just as you would experience in a live debug session. These new dump files can lead to efficiencies when analyzing a bug. You don't need to rerun, or find remote data or look for a machine that went off-line. @@ -222,7 +279,7 @@ Features that could lead to false positives in Visual Studio 2019 16.9 weren't i - [Container Overflow](https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow) - [Pointer Subtraction/Comparison](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) -For more information, see [Building for the AddressSanitizer with MSVC](./asan-building.md). +For more information, see [Building for AddressSanitizer with MSVC](./asan-building.md). ## Existing industry documentation @@ -232,7 +289,7 @@ Extensive documentation already exists for these language and platform-dependent - [Apple](https://developer.apple.com/documentation/xcode/diagnosing_memory_thread_and_crash_issues_early) - [GCC](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) -This seminal paper on the [AddressSanitizer](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation. +This seminal paper on the [AddressSanitizer (external)](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation. ## See also diff --git a/docs/sanitizers/error-alloc-dealloc-mismatch.md b/docs/sanitizers/error-alloc-dealloc-mismatch.md index 906017a981..22cf7f620f 100644 --- a/docs/sanitizers/error-alloc-dealloc-mismatch.md +++ b/docs/sanitizers/error-alloc-dealloc-mismatch.md @@ -1,7 +1,7 @@ --- title: "Error: alloc-dealloc-mismatch" -description: "Source examples and live debug screenshots for alloc-dealloc-mismatch errors." -ms.date: 03/02/2021 +description: "Learn about the alloc-dealloc-mismatch Address Sanitizer error." +ms.date: 05/28/2025 f1_keywords: ["alloc-dealloc-mismatch"] helpviewer_keywords: ["alloc-dealloc-mismatch error", "AddressSanitizer error alloc-dealloc-mismatch"] --- @@ -9,38 +9,42 @@ helpviewer_keywords: ["alloc-dealloc-mismatch error", "AddressSanitizer error al > Address Sanitizer Error: Mismatch between allocation and deallocation APIs -The `alloc`/`dealloc` mismatch functionality in AddressSanitizer is off by default for Windows. To enable it, run `set ASAN_OPTIONS=alloc_dealloc_mismatch=1` before running the program. This environment variable is checked at runtime to report errors on `malloc`/`delete`, `new`/`free`, and `new`/`delete[]`. +Enables runtime detection of mismatched memory operations that may lead to undefined behavior, such as: +- `malloc` must be paired with `free`, not `delete` or `delete[]`. +- `new` must be paired with `delete`, not `free` or `delete[]`. +- `new[]` must be paired with `delete[]`, not `delete` or `free`. + +In Windows, `alloc-dealloc-mismatch` error detection is off by default. To enable it, set the environment variable `set ASAN_OPTIONS=alloc_dealloc_mismatch=1` before running your program. ## Example ```cpp // example1.cpp -// alloc-dealloc-mismatch error +// Demonstrate alloc-dealloc-mismatch error #include #include -int main(int argc, char* argv[]) { - +int main(int argc, char* argv[]) +{ if (argc != 2) return -1; - switch (atoi(argv[1])) { - - case 1: - delete[](new int[10]); - break; - case 2: - delete (new int[10]); // Boom! - break; - default: - printf("arguments: 1: no error 2: runtime error\n"); - return -1; + switch (atoi(argv[1])) + { + case 1: + delete[](new int[10]); + break; + case 2: + delete (new int[10]); // Boom! + break; + default: + printf("arguments: 1: no error 2: runtime error\n"); + return -1; } - return 0; } ``` -To build and test this example, run these commands in a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts): +In a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts), run the following commands to see an exampe of `alloc_dealloc_mismatch`: ```cmd cl example1.cpp /fsanitize=address /Zi @@ -48,17 +52,17 @@ set ASAN_OPTIONS=alloc_dealloc_mismatch=1 devenv /debugexe example1.exe 2 ``` -### Resulting error +### Output -:::image type="content" source="media/alloc-dealloc-mismatch-example-1.png" alt-text="Screenshot of debugger displaying alloc-dealloc-mismatch error in example 1."::: +:::image type="content" source="media/alloc-dealloc-mismatch-example-1.png" alt-text="Screenshot of debugger displaying alloc-dealloc-mismatch error in example 1." lightbox="media/alloc-dealloc-mismatch-example-1.png"::: ## See also -[AddressSanitizer overview](./asan.md)\ -[AddressSanitizer known issues](./asan-known-issues.md)\ -[AddressSanitizer build and language reference](./asan-building.md)\ -[AddressSanitizer runtime reference](./asan-runtime.md)\ -[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ -[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ -[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ -[AddressSanitizer error examples](./asan-error-examples.md) +[AddressSanitizer overview](asan.md)\ +[AddressSanitizer known issues](asan-known-issues.md)\ +[AddressSanitizer build and language reference](asan-building.md)\ +[AddressSanitizer runtime reference](asan-runtime.md)\ +[AddressSanitizer shadow bytes](asan-shadow-bytes.md)\ +[AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\ +[AddressSanitizer debugger integration](asan-debugger-integration.md)\ +[AddressSanitizer error examples](asan-error-examples.md) diff --git a/docs/sanitizers/error-allocation-size-too-big.md b/docs/sanitizers/error-allocation-size-too-big.md index 9e5e7a02d2..80638c6880 100644 --- a/docs/sanitizers/error-allocation-size-too-big.md +++ b/docs/sanitizers/error-allocation-size-too-big.md @@ -1,6 +1,6 @@ --- title: "Error: allocation-size-too-big" -description: "Source examples and live debug screenshots for allocation-size-too-big errors." +description: "Learn about the allocation-size-too-big Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["allocation-size-too-big"] helpviewer_keywords: ["allocation-size-too-big error", "AddressSanitizer error allocation-size-too-big"] diff --git a/docs/sanitizers/error-calloc-overflow.md b/docs/sanitizers/error-calloc-overflow.md index 5c7ee45059..5b944307d8 100644 --- a/docs/sanitizers/error-calloc-overflow.md +++ b/docs/sanitizers/error-calloc-overflow.md @@ -1,6 +1,6 @@ --- title: "Error: calloc-overflow" -description: "Source examples and live debug screenshots for calloc overflow errors." +description: "Learn about the calloc-overflow Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["calloc-overflow"] helpviewer_keywords: ["calloc-overflow error", "AddressSanitizer error calloc-overflow"] diff --git a/docs/sanitizers/error-container-overflow.md b/docs/sanitizers/error-container-overflow.md new file mode 100644 index 0000000000..b4c1e4c783 --- /dev/null +++ b/docs/sanitizers/error-container-overflow.md @@ -0,0 +1,100 @@ +--- +title: "Error: container-overflow" +description: "Learn about the container-overflow Address Sanitizer error." +ms.date: 06/30/2023 +f1_keywords: ["container-overflow", "mismatch detected for 'annotate_vector'", "_DISABLE_VECTOR_ANNOTATION"] +helpviewer_keywords: ["container-overflow error", "AddressSanitizer error container-overflow", "mismatch detected for 'annotate_vector'", "_DISABLE_VECTOR_ANNOTATION"] +--- + +# Error: `container-overflow` + +> Address Sanitizer Error: Container overflow + +In Visual Studio 2022 version 17.2 and later, the Microsoft Visual C++ standard library (STL) is partially enlightened to work with the AddressSanitizer. The following container types have annotations to detect memory access issues: + +| Standard container type | Disable annotations macro | Supported in version | +|--|--|--| +| `std::vector` | `_DISABLE_VECTOR_ANNOTATION` | Visual Studio 2022 17.2 | +| `std::string` | `_DISABLE_STRING_ANNOTATION` | Visual Studio 2022 17.6 | + +There are checks to ensure that there are no one-definition-rule (ODR) violations. An ODR violation occurs when one translation unit annotates a standard type, such as `vector`, with ASan annotations, but another translation unit doesn't. In this example, the linker might simultaneously see one declaration of `vector::push_back` that has address sanitizer annotations, and another declaration of `vector::push_back` that doesn't. To avoid this problem, each static library and object used to link the binary must also enable ASan annotations. Effectively, you must build those static libraries and objects with AddressSanitizer enabled. Mixing code with different annotation settings causes an error: + +```Output +my_static.lib(my_code.obj) : error LNK2038: mismatch detected for 'annotate_vector': value '0' doesn't match value '1' in main.obj +``` + +To resolve this error, either disable annotations in all projects that use the corresponding macro, or build each project using **`/fsanitize=address`** and annotations enabled. (Annotations are enabled by default.) + +## Example: Access reserved memory in a `std::vector` + +```cpp +// Compile with: cl /EHsc /fsanitize=address /Zi +#include + +int main() { + // Create a vector of size 10, but with a capacity of 20. + std::vector v(10); + v.reserve(20); + + // In versions prior to 17.2, MSVC ASan does NOT raise an exception here. + // While this is an out-of-bounds write to 'v', MSVC ASan + // ensures the write is within the heap allocation size (20). + // With 17.2 and later, MSVC ASan will raise a 'container-overflow' exception: + // ==18364==ERROR: AddressSanitizer: container-overflow on address 0x1263cb8a0048 at pc 0x7ff6466411ab bp 0x005cf81ef7b0 sp 0x005cf81ef7b8 + v[10] = 1; + + // Regardless of version, MSVC ASan DOES raise an exception here, as this write + // is out of bounds from the heap allocation. + v[20] = 1; +} +``` + +To build and test this example, run the following commands in a Visual Studio 2022 version 17.2, or later [Developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts) window: + +```cmd +cl /EHsc example1.cpp /fsanitize=address /Zi +devenv /debugexe example1.exe +``` + +### Error result of reserved memory access in a `std::vector` + +:::image type="content" source="media/container-overflow-example-1.png" alt-text="Screenshot of debugger displaying container-overflow error in example 1." lightbox="media/container-overflow-example-1.png"::: + +## Custom allocators and container overflow + +Address Sanitizer container overflow checks support non-`std::allocator` allocators. However, because AddressSanitizer doesn't know whether a custom allocator conforms to AddressSanitizer requirements such as aligning allocations on 8-byte boundaries, or not putting data between the end of the allocation and the next 8-byte boundary, it may not always be able to check that accesses on the latter end of an allocation are correct. + +AddressSanitizer marks blocks of memory in 8-byte chunks. It can't place inaccessible bytes before accessible bytes in a single chunk. It's valid to have 8 accessible bytes in a chunk, or 4 accessible bytes followed by 4 inaccessible bytes. Four inaccessible bytes can't be followed by 4 accessible bytes. + +If the end of an allocation from a custom allocator doesn't strictly align with the end of an 8-byte chunk, AddressSanitizer must assume that the allocator makes the bytes between the end of the allocation and the end of the chunk available to the allocator or the user to write to. Therefore, it can't mark the bytes in the final 8-byte chunk as inaccessible. In the following example of a `vector` that allocates memory using a custom allocator, '?' refers to uninitialized data and '-' refers to memory that is inaccessible. + +```cpp +std::vector> v; +v.reserve(20); +v.assign({0, 1, 2, 3}); +// the buffer of `v` is as follows: +// | v.data() +// | | v.data() + v.size() +// | | | v.data() + v.capacity() +// [ 0 1 2 3 ? ? ? ? ][ ? ? ? ? ? ? ? ? ][ ? ? ? ? - - - - ] +// chunk 1 chunk 2 chunk 3 +``` + +In the previous example, chunk 3 has 4 bytes of memory that are assumed to be inaccessible because they fall between the end of the allocation of the 20 bytes that were reserved (`v.reserve(20)`) and the end of the third logical grouping of 8 bytes (remember that AddressSanitizer marks blocks of memory in 8-byte chunks). + +Ideally, we'd mark the shadow memory, which Address Sanitizer sets aside for every 8-byte block of memory to track which bytes in that 8-byte block are valid and which are invalid (and why), such that `v.data() + [0, v.size())` are accessible, and `v.data() + [v.size(), v.capacity())` are inaccessible. Note the use of interval notation here: '[' means inclusive of, and ')' means exclusive of. If the user is using a custom allocator, we don't know whether the memory after `v.data() + v.capacity()` is accessible or not. We must assume that it is. We'd prefer to mark those bytes as inaccessible in the shadow memory, but we must mark them as accessible so that it remains possible to access those bytes after the allocation. + +`std::allocator` uses the `_Minimum_asan_allocation_alignment` static member variable to tell `vector` and `string` that they can trust the allocator not to put data right after the allocation. This ensures that the allocator won't use the memory between the end of the allocation and end of the chunk. Thus that part of the chunk can be marked inaccessible by the Address Sanitizer to catch overruns. + +If you want the implementation to trust that your custom allocator is handling the memory between the end of the allocation and the end of the chunk so that it can mark that memory as inaccessible and catch overruns, set `_Minimum_asan_allocation_alignment` to your actual minimum alignment. For AddressSanitizer to work correctly, the alignment must be at least 8. + +## See also + +[AddressSanitizer overview](./asan.md)\ +[AddressSanitizer known issues](./asan-known-issues.md)\ +[AddressSanitizer build and language reference](./asan-building.md)\ +[AddressSanitizer runtime reference](./asan-runtime.md)\ +[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ +[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ +[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ +[AddressSanitizer error examples](./asan-error-examples.md) diff --git a/docs/sanitizers/error-double-free.md b/docs/sanitizers/error-double-free.md index c60b825c64..099c9706ec 100644 --- a/docs/sanitizers/error-double-free.md +++ b/docs/sanitizers/error-double-free.md @@ -1,6 +1,6 @@ --- title: "Error: double-free" -description: "Source examples and live debug screenshots for double free errors." +description: "Learn about the double-free Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["double-free"] helpviewer_keywords: ["double-free error", "AddressSanitizer error double-free"] diff --git a/docs/sanitizers/error-dynamic-stack-buffer-overflow.md b/docs/sanitizers/error-dynamic-stack-buffer-overflow.md index 980851d524..4b0da9350d 100644 --- a/docs/sanitizers/error-dynamic-stack-buffer-overflow.md +++ b/docs/sanitizers/error-dynamic-stack-buffer-overflow.md @@ -1,6 +1,6 @@ --- title: "Error: dynamic-stack-buffer-overflow" -description: "Source examples and live debug screenshots for alloca errors." +description: "Learn about the dynamic-stack-buffer-overflow Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["dynamic-stack-buffer-overflow"] helpviewer_keywords: ["dynamic-stack-buffer-overflow error", "AddressSanitizer error dynamic-stack-buffer-overflow"] diff --git a/docs/sanitizers/error-global-buffer-overflow.md b/docs/sanitizers/error-global-buffer-overflow.md index 0ac93be56a..1f7885ddf8 100644 --- a/docs/sanitizers/error-global-buffer-overflow.md +++ b/docs/sanitizers/error-global-buffer-overflow.md @@ -1,6 +1,6 @@ --- title: "Error: global-buffer-overflow" -description: "Source examples and live debug screenshots for global variable overflow errors." +description: "Learn about the global-buffer-overflow Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["global-buffer-overflow"] helpviewer_keywords: ["global-buffer-overflow error", "AddressSanitizer error global-buffer-overflow"] @@ -126,9 +126,10 @@ int main(int argc, char **argv) { case 'g': return global[one * 11]; //Boom! simple global case 'c': return C::array[one * 11]; //Boom! class static case 'f': - static int array[10]; - memset(array, 0, 10); + { + static int array[10] = {}; return array[one * 11]; //Boom! function static + } case 'l': // literal global ptr created by compiler const char *str = "0123456789"; diff --git a/docs/sanitizers/error-heap-buffer-overflow.md b/docs/sanitizers/error-heap-buffer-overflow.md index 10600d8807..497f9847db 100644 --- a/docs/sanitizers/error-heap-buffer-overflow.md +++ b/docs/sanitizers/error-heap-buffer-overflow.md @@ -1,6 +1,6 @@ --- title: "Error: heap-buffer-overflow" -description: "Source examples and live debug screenshots for heap variable overflow errors." +description: "Learn about the heap-buffer-overflow Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["heap-buffer-overflow"] helpviewer_keywords: ["heap-buffer-overflow error", "AddressSanitizer error heap-buffer-overflow"] diff --git a/docs/sanitizers/error-heap-use-after-free.md b/docs/sanitizers/error-heap-use-after-free.md index 03b4b0fef3..f0c827d5d2 100644 --- a/docs/sanitizers/error-heap-use-after-free.md +++ b/docs/sanitizers/error-heap-use-after-free.md @@ -1,7 +1,7 @@ --- title: "Error: heap-use-after-free" -description: "Source examples and live debug screenshots for heap use after free errors." -ms.date: 03/02/2021 +description: "Learn about the heap-use-after-free Address Sanitizer error." +ms.date: 04/06/2023 f1_keywords: ["heap-use-after-free"] helpviewer_keywords: ["heap-use-after-free error", "AddressSanitizer error heap-use-after-free"] --- @@ -35,9 +35,13 @@ cl example1.cpp /fsanitize=address /Zi devenv /debugexe example1.exe ``` +When Visual Studio appears, press `F5` to run example 1. + ### Resulting error -:::image type="content" source="media/heap-use-after-free-example-1.png" alt-text="Screenshot of debugger displaying heap-use-after-free error in example 1."::: +:::image type="complex" source="media/heap-use-after-free-example-1.png" alt-text="Screenshot of the debugger displaying use of deallocated memory error for example 1." border="true"::: +The exception thrown dialog points to line 11, return x [ 5 ], and says: Address Sanitizer Error Use of deallocated memory. Not shown in the screenshot is the output in the console window that shows memory addresses, and a key to identify addressable bytes, partially addressable bytes, freed heap regions, and heap left red zone bytes in the area of the error. +:::image-end::: ## Example - `operator new` @@ -64,9 +68,13 @@ cl example2.cpp /fsanitize=address /Zi devenv /debugexe example2.exe ``` +When Visual Studio appears, press `F5` to run example 2. + ### Resulting error - operator new -:::image type="content" source="media/heap-use-after-free-example-2.png" alt-text="Screenshot of debugger displaying heap-use-after-free error in example 2."::: +:::image type="complex" source="media/heap-use-after-free-example-2.png" alt-text="Screenshot of the debugger displaying use of deallocated memory error in example 2." border="true"::: +The exception thrown dialog points to line 11, buffer[0] = 42, and says: Address Sanitizer Error: Use of deallocated memory. Not shown in the screenshot is the output in the console window that shows memory addresses, and a key to identify addressable bytes, partially addressable bytes, freed heap regions, and heap left alloca red zone bytes in the area of the error. +:::image-end::: ## Example - `realloc` @@ -93,9 +101,13 @@ cl example3.cpp /fsanitize=address /Zi devenv /debugexe example3.exe ``` +When Visual Studio appears, press `F5` to run example 3. + ### Resulting error - realloc -:::image type="content" source="media/heap-use-after-free-example-3.png" alt-text="Screenshot of debugger displaying heap-use-after-free error in example 3."::: +:::image type="complex" source="media/heap-use-after-free-example-3.png" alt-text="Screenshot of the debugger displaying use of deallocated memory error in example 3." border="true"::: +The exception thrown dialog points to line 11, buffer[0] = 42, and says: Address Sanitizer Error: Use of deallocated memory. Not shown in the screenshot is the output in the console window that shows memory addresses, and a key to identify addressable bytes, partially addressable bytes, freed heap regions, and heap left red zone bytes in the area of the error. +:::image-end::: ## Example - volatile @@ -122,9 +134,13 @@ cl example4.cpp /fsanitize=address /Zi devenv /debugexe example4.exe ``` +When Visual Studio appears, press `F5` to run example 4. + ### Resulting error - volatile -:::image type="content" source="media/heap-use-after-free-example-4.png" alt-text="Screenshot of debugger displaying error in example 4."::: +:::image type="complex" source="media/heap-use-after-free-example-4.png" alt-text="Screenshot of the debugger displaying a use of deallocated memory error in example 4." border="true"::: +The exception thrown dialog points to line 12, *x = 42, and says: Address Sanitizer Error: Use of deallocated memory. Not shown in the screenshot is the output in the console window that shows memory addresses, and a key to identify addressable bytes, heap left red zone bytes, and some addressable and partially addressable bytes in the area of the error. +:::image-end::: ## See also diff --git a/docs/sanitizers/error-invalid-allocation-alignment.md b/docs/sanitizers/error-invalid-allocation-alignment.md index 2197383c97..87b091b869 100644 --- a/docs/sanitizers/error-invalid-allocation-alignment.md +++ b/docs/sanitizers/error-invalid-allocation-alignment.md @@ -1,6 +1,6 @@ --- title: "Error: invalid-allocation-alignment" -description: "Source examples and live debug screenshots for invalid _aligned_malloc errors." +description: "Learn about the invalid-allocation-alignment Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["invalid-allocation-alignment"] helpviewer_keywords: ["invalid-allocation-alignment error", "AddressSanitizer error invalid-allocation-alignment"] diff --git a/docs/sanitizers/error-memcpy-param-overlap.md b/docs/sanitizers/error-memcpy-param-overlap.md index 9d9d475d2a..49ded7146c 100644 --- a/docs/sanitizers/error-memcpy-param-overlap.md +++ b/docs/sanitizers/error-memcpy-param-overlap.md @@ -1,6 +1,6 @@ --- title: "Error: memcpy-param-overlap" -description: "Source examples and live debug screenshots for memcpy parameter overlap errors." +description: "Learn about the memcpy-param-overlap Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["memcpy-param-overlap"] helpviewer_keywords: ["memcpy-param-overlap error", "AddressSanitizer error memcpy-param-overlap"] @@ -35,10 +35,12 @@ int main(int argc, char **argv) { To build and test this example, run these commands in a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts): ```cmd -cl example1.cpp /fsanitize=address /Zi +cl example1.cpp /fsanitize=address /Zi /Oi devenv /debugexe example1.exe ``` +The [/Oi flag](../build/reference/oi-generate-intrinsic-functions.md) tells the compiler to treat `memcpy` and `memmove` as intrinsic functions. This is necessary because some versions of the standard library implement `memcpy` and `memmove` in the same way. Because ASAN is a dynamic analysis tool, it only detects errors with an observable runtime effect. + ### Resulting error :::image type="content" source="media/memcpy-param-overlap-example-1.png" alt-text="Screenshot of debugger displaying memcpy-param-overlap error in example 1."::: diff --git a/docs/sanitizers/error-new-delete-type-mismatch.md b/docs/sanitizers/error-new-delete-type-mismatch.md index 5a72252cec..2c19b710af 100644 --- a/docs/sanitizers/error-new-delete-type-mismatch.md +++ b/docs/sanitizers/error-new-delete-type-mismatch.md @@ -1,6 +1,6 @@ --- title: "Error: new-delete-type-mismatch" -description: "Source examples and live debug screenshots for new delete type mismatch errors." +description: "Learn about the new-delete-type-mismatch Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["new-delete-type-mismatch"] helpviewer_keywords: ["new-delete-type-mismatch error", "AddressSanitizer error new-delete-type-mismatch"] diff --git a/docs/sanitizers/error-stack-buffer-overflow.md b/docs/sanitizers/error-stack-buffer-overflow.md index 10246dc07c..c02011aaef 100644 --- a/docs/sanitizers/error-stack-buffer-overflow.md +++ b/docs/sanitizers/error-stack-buffer-overflow.md @@ -1,6 +1,6 @@ --- title: "Error: stack-buffer-overflow" -description: "Source examples and live debug screenshots for Stack buffer overflow errors." +description: "Learn about the stack-buffer-overflow Address Sanitizer error." ms.date: 09/29/2021 f1_keywords: ["stack-buffer-overflow"] helpviewer_keywords: ["stack-buffer-overflow error", "AddressSanitizer error stack-buffer-overflow"] @@ -86,7 +86,7 @@ public: class Child : public Parent { public: - int extra_field; + volatile int extra_field; }; int main(void) { @@ -95,7 +95,7 @@ int main(void) { Child *c = (Child*)&p; c->extra_field = 42; // Boom ! - return 0; + return (c->extra_field == 42); } ``` diff --git a/docs/sanitizers/error-stack-buffer-underflow.md b/docs/sanitizers/error-stack-buffer-underflow.md index 79971d52a5..03d148c2e7 100644 --- a/docs/sanitizers/error-stack-buffer-underflow.md +++ b/docs/sanitizers/error-stack-buffer-underflow.md @@ -1,6 +1,6 @@ --- title: "Error: stack-buffer-underflow" -description: "Source examples and live debug screenshots for Stack buffer underflow errors." +description: "Learn about the stack-buffer-underflow Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["stack-buffer-underflow"] helpviewer_keywords: ["stack-buffer-underflow error", "AddressSanitizer error stack-buffer-underflow"] @@ -31,10 +31,12 @@ int main() { To build and test this example, run these commands in a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts): ```cmd -cl example1.cpp /fsanitize=address /Zi +cl example1.cpp /fsanitize=address /Zi /Od devenv /debugexe example1.exe ``` +ASAN is a form of dynamic analysis, which means it can only detect bad code that is actually executed. An optimizer will remove the assignment to `buffer[subscript]` because `buffer[subscript]` is never read from. As a result, this example requires the `/Od` flag. + ### Resulting error :::image type="content" source="media/stack-buffer-underflow-example-1.png" alt-text="Screenshot of debugger displaying stack-buffer-underflow error in example 1."::: diff --git a/docs/sanitizers/error-stack-use-after-return.md b/docs/sanitizers/error-stack-use-after-return.md index fa5fa70635..5f6154e217 100644 --- a/docs/sanitizers/error-stack-use-after-return.md +++ b/docs/sanitizers/error-stack-use-after-return.md @@ -1,6 +1,6 @@ --- title: "Error: stack-use-after-return" -description: "Source examples and live debug screenshots for Stack Use After Return errors." +description: "Learn about the stack-use-after-return Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["stack-use-after-return"] helpviewer_keywords: ["stack-use-after-return error", "AddressSanitizer error stack-use-after-return"] @@ -21,7 +21,7 @@ This check can slow your application down substantially. Consider the [Clang sum ```cpp // example1.cpp // stack-use-after-return error -char* x; +volatile char* x; void foo() { char stack_buffer[42]; @@ -33,7 +33,7 @@ int main() { foo(); *x = 42; // Boom! - return 0; + return (*x == 42); } ``` @@ -96,11 +96,13 @@ int main(int argc, char* argv[]) { To build and test this example, run these commands in a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts): ```cmd -cl example2.cpp /fsanitize=address /fsanitize-address-use-after-return /Zi +cl example2.cpp /fsanitize=address /fsanitize-address-use-after-return /Zi /Od set ASAN_OPTIONS=detect_stack_use_after_return=1 devenv /debugexe example2.exe 1 ``` +ASAN is a form of dynamic analysis, which means it can only detect bad code that is actually executed. An optimizer may determine that the value of `t[100 + Idx]` or `sink` is never used and elide the assignment. As a result, this example requires the `/Od` flag. + ### Resulting error - C++ and templates :::image type="content" source="media/stack-use-after-return-example-2.png" alt-text="Screenshot of debugger displaying stack-use-after-return error in example 2."::: diff --git a/docs/sanitizers/error-stack-use-after-scope.md b/docs/sanitizers/error-stack-use-after-scope.md index 597d31a11d..fb2ff6df9c 100644 --- a/docs/sanitizers/error-stack-use-after-scope.md +++ b/docs/sanitizers/error-stack-use-after-scope.md @@ -1,6 +1,6 @@ --- title: "Error: stack-use-after-scope" -description: "Source examples and live debug screenshots for stack use after scope errors." +description: "Learn about the stack-use-after-scope Address Sanitizer error." ms.date: 02/05/2021 f1_keywords: ["stack-use-after-scope"] helpviewer_keywords: ["stack-use-after-scope error", "AddressSanitizer error stack-use-after-scope"] @@ -80,7 +80,7 @@ devenv /debugexe example2.exe struct IntHolder { explicit IntHolder(int* val = 0) : val_(val) { } ~IntHolder() { - printf("Value: %d\n", *val_); // Bom! + printf("Value: %d\n", *val_); // Boom! } void set(int* val) { val_ = val; } int* get() { return val_; } @@ -138,7 +138,7 @@ void temp_from_conversion() { a.print(); } -void main() { +int main() { explicit_temp(); temp_from_conversion(); } @@ -147,10 +147,12 @@ void main() { To build and test this example, run these commands in a Visual Studio 2019 version 16.9 or later [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts): ```cmd -cl example4.cpp /EHsc /fsanitize=address /Zi +cl example4.cpp /EHsc /fsanitize=address /Zi /Od devenv /debugexe example4.exe ``` +ASAN is a form of dynamic analysis, which means it can only detect bad code that is actually executed. An optimizer may propagate the value of `v` in these cases instead of reading from the address stored in `p`. As a result, this example requires the `/Od` flag. + ### Resulting error - temporaries :::image type="content" source="media/stack-use-after-scope-example-4.png" alt-text="Screenshot of debugger displaying stack-use-after-scope error in example 4."::: diff --git a/docs/sanitizers/error-strncat-param-overlap.md b/docs/sanitizers/error-strncat-param-overlap.md index 3e18395678..52c5f31142 100644 --- a/docs/sanitizers/error-strncat-param-overlap.md +++ b/docs/sanitizers/error-strncat-param-overlap.md @@ -1,6 +1,6 @@ --- title: "Error: strncat-param-overlap" -description: "Source examples and live debug screenshots for strcat parameter overlap errors." +description: "Learn about the strncat-param-overlap Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["strncat-param-overlap"] helpviewer_keywords: ["strncat-param-overlap error", "AddressSanitizer error strcat-param-overlap"] diff --git a/docs/sanitizers/error-use-after-poison.md b/docs/sanitizers/error-use-after-poison.md index 9ef09bd0dc..f6c58a8601 100644 --- a/docs/sanitizers/error-use-after-poison.md +++ b/docs/sanitizers/error-use-after-poison.md @@ -1,6 +1,6 @@ --- title: "Error: use-after-poison" -description: "Source examples and live debug screenshots for use after poison errors." +description: "Learn about the use-after-poison Address Sanitizer error." ms.date: 03/02/2021 f1_keywords: ["use-after-poison"] helpviewer_keywords: ["use-after-poison error", "AddressSanitizer error use-after-poison"] diff --git a/docs/sanitizers/index.yml b/docs/sanitizers/index.yml index e5db71f5df..8e8e85e21f 100644 --- a/docs/sanitizers/index.yml +++ b/docs/sanitizers/index.yml @@ -6,8 +6,8 @@ metadata: title: C/C++ Sanitizers description: Learn how to use sanitizers for defect reporting, analysis, and prevention. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 02/26/2021 ms.custom: intro-landing-hub @@ -41,7 +41,7 @@ landingContent: url: ./asan-runtime.md - text: AddressSanitizer error examples url: ./asan-error-examples.md - - text: AddressSanitizer known issues + - text: AddressSanitizer known issues and limitations url: ./asan-known-issues.md # Card diff --git a/docs/sanitizers/media/asan-basic-global-overflow.png b/docs/sanitizers/media/asan-basic-global-overflow.png index 9fcfed8576..3c87f05a03 100644 Binary files a/docs/sanitizers/media/asan-basic-global-overflow.png and b/docs/sanitizers/media/asan-basic-global-overflow.png differ diff --git a/docs/sanitizers/media/asan-cmake-configuration-drop-down.png b/docs/sanitizers/media/asan-cmake-configuration-drop-down.png new file mode 100644 index 0000000000..dea084d705 Binary files /dev/null and b/docs/sanitizers/media/asan-cmake-configuration-drop-down.png differ diff --git a/docs/sanitizers/media/asan-cmake-configuration-dropdown.png b/docs/sanitizers/media/asan-cmake-configuration-dropdown.png deleted file mode 100644 index 78f93cca0a..0000000000 Binary files a/docs/sanitizers/media/asan-cmake-configuration-dropdown.png and /dev/null differ diff --git a/docs/sanitizers/media/asan-cmake-error-f5.png b/docs/sanitizers/media/asan-cmake-error-f5.png index abdba93bdc..c82b594749 100644 Binary files a/docs/sanitizers/media/asan-cmake-error-f5.png and b/docs/sanitizers/media/asan-cmake-error-f5.png differ diff --git a/docs/sanitizers/media/asan-cmake-json.png b/docs/sanitizers/media/asan-cmake-json.png deleted file mode 100644 index fefbc2ca27..0000000000 Binary files a/docs/sanitizers/media/asan-cmake-json.png and /dev/null differ diff --git a/docs/sanitizers/media/asan-global-buffer-overflow-f5.png b/docs/sanitizers/media/asan-global-buffer-overflow-f5.png index 442f84c23d..6aa808aa5a 100644 Binary files a/docs/sanitizers/media/asan-global-buffer-overflow-f5.png and b/docs/sanitizers/media/asan-global-buffer-overflow-f5.png differ diff --git a/docs/sanitizers/media/asan-library-linking-previous-versions.png b/docs/sanitizers/media/asan-library-linking-previous-versions.png new file mode 100644 index 0000000000..1186091bbc Binary files /dev/null and b/docs/sanitizers/media/asan-library-linking-previous-versions.png differ diff --git a/docs/sanitizers/media/asan-one-dll.png b/docs/sanitizers/media/asan-one-dll.png new file mode 100644 index 0000000000..7601d818ec Binary files /dev/null and b/docs/sanitizers/media/asan-one-dll.png differ diff --git a/docs/sanitizers/media/asan-project-system-dialog.png b/docs/sanitizers/media/asan-project-system-dialog.png index 08c82d9d2d..61d01b04fd 100644 Binary files a/docs/sanitizers/media/asan-project-system-dialog.png and b/docs/sanitizers/media/asan-project-system-dialog.png differ diff --git a/docs/sanitizers/media/container-overflow-example-1.png b/docs/sanitizers/media/container-overflow-example-1.png new file mode 100644 index 0000000000..38db10e07d Binary files /dev/null and b/docs/sanitizers/media/container-overflow-example-1.png differ diff --git a/docs/sanitizers/media/heap-use-after-free-example-1.png b/docs/sanitizers/media/heap-use-after-free-example-1.png index 29f4d3ef61..da37249486 100644 Binary files a/docs/sanitizers/media/heap-use-after-free-example-1.png and b/docs/sanitizers/media/heap-use-after-free-example-1.png differ diff --git a/docs/sanitizers/media/heap-use-after-free-example-2.png b/docs/sanitizers/media/heap-use-after-free-example-2.png index 9b0c33f9ba..898bef6cf7 100644 Binary files a/docs/sanitizers/media/heap-use-after-free-example-2.png and b/docs/sanitizers/media/heap-use-after-free-example-2.png differ diff --git a/docs/sanitizers/media/heap-use-after-free-example-3.png b/docs/sanitizers/media/heap-use-after-free-example-3.png index a1cafb8e9a..f6251f889d 100644 Binary files a/docs/sanitizers/media/heap-use-after-free-example-3.png and b/docs/sanitizers/media/heap-use-after-free-example-3.png differ diff --git a/docs/sanitizers/media/heap-use-after-free-example-4.png b/docs/sanitizers/media/heap-use-after-free-example-4.png index 75e93087fa..0db8ff36f6 100644 Binary files a/docs/sanitizers/media/heap-use-after-free-example-4.png and b/docs/sanitizers/media/heap-use-after-free-example-4.png differ diff --git a/docs/sanitizers/media/runtime-configurations.png b/docs/sanitizers/media/runtime-configurations.png new file mode 100644 index 0000000000..3298a14be9 Binary files /dev/null and b/docs/sanitizers/media/runtime-configurations.png differ diff --git a/docs/sanitizers/toc.yml b/docs/sanitizers/toc.yml index 6ca9012f81..f46431207c 100644 --- a/docs/sanitizers/toc.yml +++ b/docs/sanitizers/toc.yml @@ -6,6 +6,8 @@ items: items: - name: "AddressSanitizer overview" href: ../sanitizers/asan.md + - name: Continue on error walkthrough + href: ../sanitizers/asan-continue-on-error.md - name: "Build and language reference" href: ../sanitizers/asan-building.md - name: "Runtime reference" @@ -27,6 +29,8 @@ items: href: ../sanitizers/error-allocation-size-too-big.md - name: "calloc-overflow error" href: ../sanitizers/error-calloc-overflow.md + - name: "container-overflow error" + href: ../sanitizers/error-container-overflow.md - name: "double-free error" href: ../sanitizers/error-double-free.md - name: "dynamic-stack-buffer-overflow error" @@ -55,5 +59,5 @@ items: href: ../sanitizers/error-strncat-param-overlap.md - name: "use-after-poison error" href: ../sanitizers/error-use-after-poison.md - - name: "Known issues" + - name: "Known issues and limitations" href: ../sanitizers/asan-known-issues.md diff --git a/docs/security/security-best-practices-for-cpp.md b/docs/security/security-best-practices-for-cpp.md index 3774d17083..c895388f5f 100644 --- a/docs/security/security-best-practices-for-cpp.md +++ b/docs/security/security-best-practices-for-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Security Best Practices for C++" title: "Security Best Practices for C++" -ms.date: "05/08/2018" +description: "Learn more about: Security Best Practices for C++" +ms.date: 05/08/2018 f1_keywords: ["securitybestpracticesVC"] helpviewer_keywords: ["Visual C++, security", "security [C++]", "security [C++], best practices"] -ms.assetid: 86acaccf-cdb4-4517-bd58-553618e3ec42 --- # Security Best Practices for C++ @@ -14,22 +13,22 @@ This article contains information about security tools and practices. Using them These security features are built into the Microsoft C++ compiler and linker: -[`/guard` (Enable Control Flow Guard)](../build/reference/guard-enable-control-flow-guard.md)
+[`/guard` (Enable Control Flow Guard)](../build/reference/guard-enable-control-flow-guard.md)\ Causes the compiler to analyze control flow for indirect call targets at compile time, and then to insert code to verify the targets at runtime. -[`/GS` (Buffer Security Check)](../build/reference/gs-buffer-security-check.md)
+[`/GS` (Buffer Security Check)](../build/reference/gs-buffer-security-check.md)\ Instructs the compiler to insert overrun detection code into functions that are at risk of being exploited. When an overrun is detected, execution is stopped. By default, this option is on. -[`/SAFESEH` (Image has Safe Exception Handlers)](../build/reference/safeseh-image-has-safe-exception-handlers.md)
+[`/SAFESEH` (Image has Safe Exception Handlers)](../build/reference/safeseh-image-has-safe-exception-handlers.md)\ Instructs the linker to include in the output image a table that contains the address of each exception handler. At run time, the operating system uses this table to make sure that only legitimate exception handlers are executed. This helps prevent the execution of exception handlers that are introduced by a malicious attack at run time. By default, this option is off. -[`/NXCOMPAT`](../build/reference/nxcompat.md), [`/NXCOMPAT` (Compatible with Data Execution Prevention)](../build/reference/nxcompat-compatible-with-data-execution-prevention.md) +[`/NXCOMPAT`](../build/reference/nxcompat.md), [`/NXCOMPAT` (Compatible with Data Execution Prevention)](../build/reference/nxcompat-compatible-with-data-execution-prevention.md)\ These compiler and linker options enable Data Execution Prevention (DEP) compatibility. DEP guards the CPU against the execution of non-code pages. -[`/analyze` (Code Analysis)](../build/reference/analyze-code-analysis.md)
+[`/analyze` (Code Analysis)](../build/reference/analyze-code-analysis.md)\ This compiler option activates code analysis that reports potential security issues such as buffer overrun, un-initialized memory, null pointer dereferencing, and memory leaks. By default, this option is off. For more information, see [Code Analysis for C/C++ Overview](../code-quality/code-analysis-for-c-cpp-overview.md). -[`/DYNAMICBASE` (Use address space layout randomization)](../build/reference/dynamicbase-use-address-space-layout-randomization.md)
+[`/DYNAMICBASE` (Use address space layout randomization)](../build/reference/dynamicbase-use-address-space-layout-randomization.md)\ This linker option enables the building of an executable image that can be loaded at different locations in memory at the beginning of execution. This option also makes the stack location in memory much less predictable. ## Security-Enhanced CRT @@ -86,6 +85,6 @@ For information about how to indentify and mitigate against speculative executio ## See also -
-[Security](/dotnet/standard/security/index)
+\ +[Security in .NET](/dotnet/standard/security/index)\ [How User Account Control (UAC) Affects Your Application](how-user-account-control-uac-affects-your-application.md) diff --git a/docs/standard-library/algorithm-functions.md b/docs/standard-library/algorithm-functions.md index 47e5f5f3a0..2e049415f2 100644 --- a/docs/standard-library/algorithm-functions.md +++ b/docs/standard-library/algorithm-functions.md @@ -1,9 +1,10 @@ --- description: "Learn more about: functions" title: " functions" -ms.date: "09/09/2021" +ms.date: 06/07/2022 f1_keywords: ["algorithm/std::adjacent_find", "algorithm/std::all_of", "algorithm/std::any_of", "algorithm/std::binary_search", "algorithm/std::copy", "algorithm/std::copy_backward", "algorithm/std::copy_if", "algorithm/std::copy_n", "algorithm/std::equal", "algorithm/std::equal_range", "algorithm/std::fill", "algorithm/std::fill_n", "algorithm/std::find", "algorithm/std::find_end", "algorithm/std::find_first_of", "algorithm/std::find_if", "algorithm/std::find_if_not", "algorithm/std::for_each", "algorithm/std::generate", "algorithm/std::generate_n", "algorithm/std::includes", "algorithm/std::inplace_merge", "algorithm/std::is_heap", "algorithm/std::is_heap_until", "algorithm/std::is_partitioned", "algorithm/std::is_permutation", "algorithm/std::is_sorted", "algorithm/std::is_sorted_until", "algorithm/std::iter_swap", "algorithm/std::lexicographical_compare", "algorithm/std::lower_bound", "algorithm/std::make_heap", "algorithm/std::max", "algorithm/std::max_element", "algorithm/std::merge", "algorithm/std::min", "algorithm/std::minmax", "algorithm/std::minmax_element", "algorithm/std::min_element", "algorithm/std::mismatch", "algorithm/std::move", "algorithm/std::move_backward", "algorithm/std::next_permutation", "algorithm/std::none_of", "algorithm/std::nth_element", "algorithm/std::partial_sort", "algorithm/std::partial_sort_copy", "algorithm/std::partition", "algorithm/std::partition_point", "algorithm/std::pop_heap", "algorithm/std::prev_permutation", "algorithm/std::push_heap", "algorithm/std::random_shuffle", "algorithm/std::remove", "algorithm/std::remove_copy", "algorithm/std::remove_copy_if", "algorithm/std::remove_if", "algorithm/std::replace", "algorithm/std::replace_copy", "algorithm/std::replace_copy_if", "algorithm/std::replace_if", "algorithm/std::reverse", "algorithm/std::reverse_copy", "algorithm/std::rotate", "algorithm/std::rotate_copy", "algorithm/std::search", "algorithm/std::search_n", "algorithm/std::set_difference", "algorithm/std::set_intersection", "algorithm/std::set_symmetric_difference", "algorithm/std::set_union", "algorithm/std::shuffle", "algorithm/std::sort", "algorithm/std::sort_heap", "algorithm/std::stable_partition", "algorithm/std::stable_sort", "algorithm/std::swap_ranges", "algorithm/std::transform", "algorithm/std::unique", "algorithm/std::unique_copy", "algorithm/std::upper_bound", "xutility/std::copy", "xutility/std::copy_backward", "xutility/std::copy_n", "xutility/std::count", "xutility/std::equal", "xutility/std::fill", "xutility/std::fill_n", "xutility/std::find", "xutility/std::is_permutation", "xutility/std::lexicographical_compare", "xutility/std::move", "xutility/std::move_backward", "xutility/std::reverse", "xutility/std::rotate", "algorithm/std::count_if", "algorithm/std::partition_copy", "algorithm/std::swap"] helpviewer_keywords: ["std::adjacent_find [C++]", "std::all_of [C++]", "std::any_of [C++]", "std::binary_search [C++]", "std::copy [C++]", "std::copy_backward [C++]", "std::copy_if [C++]", "std::copy_n [C++]", "std::equal [C++]", "std::equal_range [C++]", "std::fill [C++]", "std::fill_n [C++]", "std::find [C++]", "std::find_end [C++]", "std::find_first_of [C++]", "std::find_if [C++]", "std::find_if_not [C++]", "std::for_each [C++]", "std::generate [C++]", "std::generate_n [C++]", "std::includes [C++]", "std::inplace_merge [C++]", "std::is_heap [C++]", "std::is_heap_until [C++]", "std::is_partitioned [C++]", "std::is_permutation [C++]", "std::is_sorted [C++]", "std::is_sorted_until [C++]", "std::iter_swap [C++]", "std::lexicographical_compare [C++]", "std::lower_bound [C++]", "std::make_heap [C++]", "std::max [C++]", "std::max_element [C++]", "std::merge [C++]", "std::min [C++]", "std::minmax [C++]", "std::minmax_element [C++]", "std::min_element [C++]", "std::mismatch [C++]", "std::move [C++]", "std::move_backward [C++]", "std::next_permutation [C++]", "std::none_of [C++]", "std::nth_element [C++]", "std::partial_sort [C++]", "std::partial_sort_copy [C++]", "std::partition [C++]", "std::partition_point [C++]", "std::pop_heap [C++]", "std::prev_permutation [C++]", "std::push_heap [C++]", "std::random_shuffle [C++]", "std::remove [C++]", "std::remove_copy [C++]", "std::remove_copy_if [C++]", "std::remove_if [C++]", "std::replace [C++]", "std::replace_copy [C++]", "std::replace_copy_if [C++]", "std::replace_if [C++]", "std::reverse [C++]", "std::reverse_copy [C++]", "std::rotate [C++]", "std::rotate_copy [C++]", "std::search [C++]", "std::search_n [C++]", "std::set_difference [C++]", "std::set_intersection [C++]", "std::set_symmetric_difference [C++]", "std::set_union [C++]", "std::shuffle [C++]", "std::sort [C++]", "std::sort_heap [C++]", "std::stable_partition [C++]", "std::stable_sort [C++]", "std::swap_ranges [C++]", "std::transform [C++]", "std::unique [C++]", "std::unique_copy [C++]", "std::upper_bound [C++]", "std::copy [C++]", "std::copy_backward [C++]", "std::copy_n [C++]", "std::count [C++]", "std::equal [C++]", "std::fill [C++]", "std::fill_n [C++]", "std::find [C++]", "std::is_permutation [C++]", "std::lexicographical_compare [C++]", "std::move [C++]", "std::move_backward [C++]", "std::reverse [C++]", "std::rotate [C++]", "std::count_if [C++]", "std::partition_copy [C++]", "std::swap [C++]"] +ms.custom: devdivchpfy22 --- # `` functions @@ -43,10 +44,10 @@ ForwardIterator adjacent_find( The execution policy to use. *`first`*\ -A forward iterator addressing the position of the first element in the range to be searched. +A forward iterator at the position of the first element in the range to be searched. *`last`*\ -A forward iterator addressing the position one past the final element in the range to be searched. +A forward iterator at the position one past the final element in the range to be searched. *`pred`*\ The binary predicate giving the condition to be satisfied by the values of the adjacent elements in the range being searched. @@ -57,7 +58,7 @@ A forward iterator to the first of the adjacent elements that are either equal t ### Remarks -The `adjacent_find` algorithm is a nonmutating sequence algorithm. The range to be searched must be valid; all pointers must be dereferenceable and the last position is reachable from the first by incrementation. The time complexity of the algorithm is linear in the number of elements contained in the range. +The `adjacent_find` algorithm is a nonmutating sequence algorithm. The range to be searched must be valid. All pointers must be dereferenceable, and the last position must be reachable from the first by incrementation. The time complexity of the algorithm is linear in the number of elements contained in the range. The `operator==` used to determine the match between elements must impose an equivalence relation between its operands. @@ -156,7 +157,7 @@ An input iterator that indicates where to start to check for a condition. The it An input iterator that indicates the end of the range of elements to check for a condition. *`pred`*\ -A condition to test for. This is a user-defined predicate function object that defines the condition to be satisfied by an element being checked. A unary predicate takes a single argument and returns **`true`** or **`false`**. +A condition to test for. *`pred`* is a user-defined unary predicate function object that defines the condition to be satisfied by an element being checked. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Return value @@ -232,7 +233,7 @@ An input iterator that indicates where to start checking a range of elements for An input iterator that indicates the end of the range of elements to check for a condition. *`pred`*\ -A condition to test for. This is provided by a user-defined predicate function object. The predicate defines the condition to be satisfied by the element being tested. A unary predicate takes a single argument and returns **`true`** or **`false`**. +A condition to test for. This test is provided by a user-defined predicate function object. The predicate defines the condition to be satisfied by the element being tested. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Return value @@ -264,7 +265,7 @@ int main() cout << el << " "; cout << ")" << endl; - // Check if there is an even elememt in li. + // Check if there's an even element in li. auto is_even = [](int const elem){ return !(elem % 2); }; if (any_of(li.begin(), li.end(), is_even)) cout << "There's an even element in li.\n"; @@ -280,7 +281,7 @@ There's an even element in li. ## `binary_search` -Tests whether there is an element in a sorted range that is equal to a specified value or that is equivalent to it in a sense specified by a binary predicate. +Tests whether there's an element in a sorted range that is equal to a specified value or that is equivalent to it in a sense specified by a binary predicate. ```cpp template @@ -321,11 +322,11 @@ The sorted source range referenced must be valid; all pointers must be dereferen The sorted range must each be arranged as a precondition to the application of the `binary_search` algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The source ranges are not modified by `binary_search`. +The source ranges aren't modified by `binary_search`. -The value types of the forward iterators need to be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements +The value types of the forward iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. -The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last` - `first`). +The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last-first`). ### Example @@ -419,7 +420,7 @@ There is an element with a value equivalent to -3 under mod_lesser. ## `clamp` -Compares a value to an upper and lower bound, and returns a reference to the value if it is between the bounds, or a reference to the upper or lower bound if the value is above or below them, respectively. +Compares a value to an upper and lower bound, and returns a reference to the value if it's between the bounds, or a reference to the upper or lower bound if the value is above or below them, respectively. ```cpp template @@ -499,9 +500,9 @@ An output iterator addressing the position that is one past the final element in The source range must be valid and there must be sufficient space at the destination to hold all the elements being copied. -Because the algorithm copies the source elements in order beginning with the first element, the destination range can overlap with the source range provided the *`last`* position of the source range is not contained in the destination range. `copy` can be used to shift elements to the left but not the right, unless there is no overlap between the source and destination ranges. To shift to the right any number of positions, use the [`copy_backward`](algorithm-functions.md#copy_backward) algorithm. +Because the algorithm copies the source elements in order beginning with the first element, the destination range can overlap with the source range provided the *`last`* position of the source range isn't contained in the destination range. `copy` can be used to shift elements to the left but not the right, unless there's no overlap between the source and destination ranges. To shift to the right any number of positions, use the [`copy_backward`](algorithm-functions.md#copy_backward) algorithm. -The `copy` algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It cannot be used to create new elements and cannot insert elements into an empty container directly. +The `copy` algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It can't be used to create new elements and can't insert elements into an empty container directly. ### Example @@ -596,9 +597,9 @@ The `copy_backward` algorithm imposes more stringent requirements than that the The `copy_backward` and [`move_backward`](algorithm-functions.md#move_backward) algorithms are the only C++ Standard Library algorithms designating the output range with an iterator pointing to the end of the destination range. -Because the algorithm copies the source elements in order beginning with the last element, the destination range can overlap with the source range provided the *`first`* position of the source range is not contained in the destination range. `copy_backward` can be used to shift elements to the right but not the left, unless there is no overlap between the source and destination ranges. To shift to the left any number of positions, use the [`copy`](algorithm-functions.md#copy) algorithm. +Because the algorithm copies the source elements in order beginning with the last element, the destination range can overlap with the source range provided the *`first`* position of the source range isn't contained in the destination range. `copy_backward` can be used to shift elements to the right but not the left, unless there's no overlap between the source and destination ranges. To shift to the left any number of positions, use the [`copy`](algorithm-functions.md#copy) algorithm. -The `copy_backward` algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It cannot be used to create new elements and cannot insert elements into an empty container directly. +The `copy_backward` algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It can't be used to create new elements and can't insert elements into an empty container directly. ### Example @@ -798,7 +799,7 @@ An output iterator that indicates where to copy elements to. ### Return value -Returns an output iterator where elements have been copied to. It is the same as the returned value of the *`dest`* parameter. +Returns an output iterator where elements have been copied to. It's the same as the returned value of the *`dest`* parameter. ### Remarks @@ -1005,7 +1006,7 @@ Compares two ranges element by element for equality or equivalence in a sense sp Use `std::equal` when comparing elements in different container types (for example `vector` and `list`) or when comparing different element types, or when you need to compare subranges of containers. Otherwise, when comparing elements of the same type in the same container type, use the non-member `operator==` that is provided for each container. -Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range. +Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range won't detect differences if the second range is longer than the first range. These overloads will result in undefined behavior if the second range is shorter than the first range. ```cpp template @@ -1099,7 +1100,7 @@ The range to be searched must be valid; all iterators must be dereferenceable an If the two ranges are equal length, then the time complexity of the algorithm is linear in the number of elements contained in the range. Otherwise the function immediately returns **`false`**. -Neither the `operator==` nor the user-defined predicate is required to impose an equivalence relation that symmetric, reflexive, and transitive between its operands. +You don't need either `operator==` or the user-defined predicate to impose an equivalence relation that's symmetric, reflexive, and transitive between its operands. ### Example @@ -1134,6 +1135,12 @@ int main() } ``` +```Output +v1 and v2 are equal: 1 +v1 and v3 are equal: 1 +v1 and v3 are equal with dual-range overload: 0 +``` + ## `equal_range` Given an ordered range, finds the subrange in which all elements are equivalent to a given value. @@ -1177,7 +1184,7 @@ If no elements in the range are equivalent to *`value`*, the forward iterators i The first iterator of the pair returned by the algorithm is [`lower_bound`](algorithm-functions.md#lower_bound), and the second iterator is [`upper_bound`](algorithm-functions.md#upper_bound). -The range must be sorted according to the predicate provided to `equal_range`. For example, if you are going to use the greater-than predicate, the range must be sorted in descending order. +The range must be sorted according to the predicate provided to `equal_range`. For example, if you're going to use the greater-than predicate, the range must be sorted in descending order. Elements in the possibly empty subrange defined by the pair of iterators returned by `equal_range` will be equivalent to *value* in the sense defined by the predicate used. @@ -1221,13 +1228,13 @@ template void equal_range_demo( const vector& original_vector, T val sort( v.begin(), v.end() ); cout << "Vector sorted by the default binary predicate <:" << endl << '\t'; - for ( vector::const_iterator i = v.begin(); i != v.end(); ++i ) + for ( typename vector::const_iterator i = v.begin(); i != v.end(); ++i ) { cout << *i << " "; } cout << endl << endl; - pair::iterator, vector::iterator> result + pair::iterator, typename vector::iterator> result = equal_range( v.begin(), v.end(), value ); cout << "Result of equal_range with value = " << value << ":" << endl << '\t'; @@ -1300,6 +1307,38 @@ int main() } ``` +```Output +Vector sorted by the default binary predicate <: + -3 -2 -1 -1 0 0 1 2 3 4 + +Result of equal_range with value = 3: + -3 -2 -1 -1 0 0 1 2 [ 3 ] 4 + +Vector sorted by the binary predicate greater: + 4 3 2 1 0 0 -1 -1 -2 -3 + +Result of equal_range with value = 3: + 4 [ 3 ] 2 1 0 0 -1 -1 -2 -3 + +Vector sorted by the binary predicate abs_lesser: + 0 0 -1 1 -1 2 -2 3 -3 4 + +Result of equal_range with value = 3: + 0 0 -1 1 -1 2 -2 [ 3 -3 ] 4 + +Vector sorted by the default binary predicate <: + blah cute fluffy fun kittens meowmeowmeow + +Result of equal_range with value = fred: + blah cute fluffy [ ] fun kittens meowmeowmeow + +Vector sorted by the binary predicate shorter_than: + fun cute blah fluffy kittens meowmeowmeow + +Result of equal_range with value = fred: + fun [ cute blah ] fluffy kittens meowmeowmeow +``` + ## `fill` Assigns the same new value to every element in a specified range. @@ -1436,7 +1475,7 @@ int main() for ( auto i = 0 ; i < 9 ; ++i ) v.push_back( 0 ); - cout << " vector v = ( " ; + cout << "vector v = ( " ; for ( const auto &w : v ) cout << w << " "; cout << ")" << endl; @@ -1467,6 +1506,13 @@ int main() } ``` +```Output +vector v = ( 0 0 0 0 0 0 0 0 0 ) +modified v = ( 1 1 1 0 0 0 0 0 0 ) +modified v = ( 1 1 1 2 2 2 0 0 0 ) +modified v = ( 1 1 1 2 2 2 3 3 3 ) +``` + ## `find` Locates the position of the first occurrence of an element in a range that has a specified value. @@ -1676,7 +1722,7 @@ in v2 under the binary predicate twice and that begins at position 8. ## `find_first_of` -Searches for the first occurrence of any of several values within a target range or for the first occurrence of any of several elements that are equivalent in a sense specified by a binary predicate to a specified set of the elements. +Searches for the first occurrence of any of several values within a target range. Or, searches for the first occurrence of any of several elements that are equivalent in a sense specified by a binary predicate to a specified set of the elements. ```cpp template @@ -1868,7 +1914,7 @@ An input iterator addressing the position of the first element in the range to b An input iterator addressing the position one past the final element in the range to be searched. *`pred`*\ -User-defined predicate function object or [lambda expression](../cpp/lambda-expressions-in-cpp.md) that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** if satisfied, or **`false`** if not satisfied. The signature of *`pred`* must effectively be `bool pred(const T& arg);`, where `T` is a type to which `InputIterator` can be implicitly converted when dereferenced. The **`const`** keyword is shown only to illustrate that the function object or lambda should not modify the argument. +User-defined predicate function object or [lambda expression](../cpp/lambda-expressions-in-cpp.md) that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** if satisfied, or **`false`** if not satisfied. The signature of *`pred`* must effectively be `bool pred(const T& arg);`, where `T` is a type to which `InputIterator` can be implicitly converted when dereferenced. The **`const`** keyword is shown only to illustrate that the function object or lambda shouldn't modify the argument. ### Return value @@ -1876,7 +1922,7 @@ An input iterator that refers to the first element in the range that satisfies t ### Remarks -This template function is a generalization of the algorithm [`find`](algorithm-functions.md#find), replacing the predicate "equals a specific value" with any predicate. For the logical opposite (find the first element that does not satisfy the predicate), see [`find_if_not`](algorithm-functions.md#find_if_not). +This template function is a generalization of the algorithm [`find`](algorithm-functions.md#find), replacing the predicate "equals a specific value" with any predicate. For the logical opposite (find the first element that doesn't satisfy the predicate), see [`find_if_not`](algorithm-functions.md#find_if_not). ### Example @@ -1963,9 +2009,27 @@ int main() } ``` +```Output +array x[] contents: (1) (2) (3) (4) (5) (6) (7) (8) (9) (10) +Test std::find() with array... +value 10 found. +value 42 not found. +Test std::find_if() with array... +first odd integer found: 1 +first even integer found: 2 + +vector v contents: (10) (20) (30) (40) (50) (60) (70) (80) (90) (100) +Test std::find() with vector... +value 20 found. +value 12 not found. +Test std::find_if() with vector... +odd integer not found. +first even integer found: 10 +``` + ## `find_if_not` -Returns the first element in the indicated range that does not satisfy a condition. +Returns the first element in the indicated range that doesn't satisfy a condition. ```cpp template @@ -1990,11 +2054,11 @@ An input iterator addressing the position of the first element in the range to b An input iterator addressing the position one past the final element in the range to be searched. *`pred`*\ -User-defined predicate function object or [lambda expression](../cpp/lambda-expressions-in-cpp.md) that defines the condition to be not satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** if satisfied, or **`false`** if not satisfied. The signature of *`pred`* must effectively be `bool pred(const T& arg);`, where `T` is a type to which `InputIterator` can be implicitly converted when dereferenced. The **`const`** keyword is shown only to illustrate that the function object or lambda should not modify the argument. +User-defined predicate function object or [lambda expression](../cpp/lambda-expressions-in-cpp.md) that defines the condition to be not satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** if satisfied, or **`false`** if not satisfied. The signature of *`pred`* must effectively be `bool pred(const T& arg);`, where `T` is a type to which `InputIterator` can be implicitly converted when dereferenced. The **`const`** keyword is shown only to illustrate that the function object or lambda shouldn't modify the argument. ### Return value -An input iterator that refers to the first element in the range that does not satisfy the condition specified by the predicate (the predicate results in **`false`**). If all elements satisfy the predicate (the predicate results in **`true`** for every element), returns *`last`*. +An input iterator that refers to the first element in the range that doesn't satisfy the condition specified by the predicate (the predicate results in **`false`**). If all elements satisfy the predicate (the predicate results in **`true`** for every element), returns *`last`*. ### Remarks @@ -2024,7 +2088,7 @@ void for_each( ### Parameters *`first`*\ -An input iterator addressing the position of the first element in the range to be operated on. +An input iterator addressing the position of the first element in the range to operate on. *`last`*\ An input iterator addressing the position one past the final element in the range operated on. @@ -2038,7 +2102,7 @@ A copy of the function object after it has been applied to all of the elements i ### Remarks -The algorithm `for_each` is very flexible, allowing the modification of each element within a range in different, user-specified ways. Templatized functions may be reused in a modified form by passing different parameters. User-defined functions may accumulate information within an internal state that the algorithm may return after processing all of the elements in the range. +The algorithm `for_each` is flexible, allowing the modification of each element within a range in different, user-specified ways. Templatized functions may be reused in a modified form by passing different parameters. User-defined functions may accumulate information within an internal state that the algorithm may return after processing all of the elements in the range. The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation. @@ -2127,7 +2191,7 @@ int main() // The function object is templatized and so can be // used again on the elements with a different Factor - for_each (v1.begin( ), v1.end( ), MultValue (5 ) ); + for_each ( v1.begin( ), v1.end( ), MultValue ( 5 ) ); cout << "Multiplying the elements of the vector v1mod\n " << "by the factor 5 gives:\n v1mod2 = ( " ; @@ -2159,19 +2223,127 @@ Average ( v1mod2 ) = 10. ## `for_each_n` +Applies a specified function object to a specified number of elements in a range beginning with a particular element. + ```cpp template InputIterator for_each_n( InputIterator first, - Size n, - Function f); + Size count, + Function func); template ForwardIterator for_each_n( ExecutionPolicy&& exec, ForwardIterator first, - Size n, - Function f); + Size count, + Function func); +``` + +### Parameters + +*`exec`*\ +The execution policy to use. + +*`first`*\ +An input iterator at the position of the first element in the range to operate on. + +*`count`*\ +The number of elements to operate on. + +*`func`*\ +A user-defined function object to apply to each element in the range [`first`, `first` + `count`). + +### Return value + +An iterator to the element that follows the last element processed if *`count`* > zero, +otherwise the first element. + +### Remarks + +*`count`* must be non-negative, and there must be at least *`count`* elements in the range starting from *`first`*. + +### Example + +This example defines a function object class. Production code often uses a [`lambda`](../cpp/lambda-expressions-in-cpp.md) to achieve the same result with less code. + +```cpp +// alg_for_each_n.cpp +// compile with /EHsc and /std:c++17 (or higher) +#include +#include +#include + +// The function object multiplies an element by a Factor +template class MultValue +{ +private: + Type Factor; // The value to multiply each element by +public: + // Constructor initializes the value to multiply by + MultValue(const Type &value) : Factor(value) {} + + // The function call for the element to be multiplied + void operator()(Type &elem) const + { + elem *= Factor; + } +}; + +// Utility to display the contents of a vector +template void print_vector(const std::vector &vec) +{ + std::cout << "( "; + + for (auto iter = vec.begin(); iter != vec.end(); iter++) + { + std::cout << *iter << ' '; + } + + std::cout << ").\n"; +} + +int main() +{ + std::vector v; + + // Construct vector with the elements -4...2 + for (int i = -4; i <= 2; i++) + { + v.push_back(i); + } + + std::cout << "Original vector v = "; + print_vector(v); + + // Use for_each_n to multiply the first 3 elements by a Factor, + // saving the position in the vector after the first 3 elements + auto pos = for_each_n(v.begin(), 3, MultValue(-2)); + + std::cout << "Multiplying the first 3 elements of the vector v\n " + << "by the factor -2 gives:\n vmod1 = "; + print_vector(v); + + // Using for_each_n to multiply the next 4 elements by a Factor, + // starting at the position saved by the previous for_each_n + for_each_n(pos, 4, MultValue(-3)); + + std::cout << "Multiplying the next 4 elements of the vector v\n " + << "by the factor -3 gives:\n vmod2 = "; + print_vector(v); + + return 0; +} +``` + +```Output +Original vector v = ( -4 -3 -2 -1 0 1 2 ). +Multiplying the first 3 elements of the vector v + by the factor -2 gives: + vmod1 = ( 8 6 4 -1 0 1 2 ). +Multiplying the next 4 elements of the vector v + by the factor -3 gives: + vmod2 = ( 8 6 4 3 0 -3 -6 ). ``` ## `generate` @@ -2195,21 +2367,21 @@ void generate( ### Parameters *`first`*\ -A forward iterator addressing the position of the first element in the range to which values are to be assigned. +A forward iterator at the position of the first element in the range to which values are to be assigned. *`last`*\ -A forward iterator addressing the position one past the final element in the range to which values are to be assigned. +A forward iterator at the position one past the final element in the range to which values are to be assigned. *`gen`*\ -A function object that is called with no arguments that is used to generate the values to be assigned to each of the elements in the range. +A function object that is called with no arguments to generate the values to be assigned to each of the elements in the range. ### Remarks -The function object is invoked for each element in the range and does not need to return the same value each time it is called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterators for the range. +The function object is invoked for each element in the range and doesn't need to return the same value each time it's called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterator for the range. -The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation. +The range referenced must be valid. All pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation. -The complexity is linear, with exactly ( `last` - `first`) calls to the generator being required. +The complexity is linear, with exactly `last - first` calls made to the generator. ### Example @@ -2256,7 +2428,7 @@ Deque deq1 is ( 15724 11478 29358 26962 24464 ). ## `generate_n` -Assigns the values generated by a function object to a specified number of elements in a range and returns to the position one past the last assigned value. +Assigns the values generated by a function object to a specified number of elements in a range. Returns the position one past the last assigned value. ```cpp template @@ -2289,7 +2461,7 @@ A function object that is called with no arguments that is used to generate the ### Remarks -The function object is invoked for each element in the range and does not need to return the same value each time it is called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterators for the range. +The function object is invoked for each element in the range and doesn't need to return the same value each time it's called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterators for the range. The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation. @@ -2340,6 +2512,11 @@ int main() } ``` +```Output +vector v is: 5 8 2 -9 6 +deque dq is: 7 6 9 3 4 +``` + ## `includes` Tests whether one sorted range contains all the elements contained in a second sorted range, where the ordering or equivalence criterion between elements may be specified by a binary predicate. @@ -2408,11 +2585,11 @@ Another way to think of this test is that it determined whether the second sourc The sorted source ranges referenced must be valid; all pointers must be dereferenceable and, within each sequence, the last position must be reachable from the first by incrementation. -The sorted source ranges must each be arranged as a precondition to the application of the algorithm includes in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. +As a precondition to the application of the algorithm `includes`, the sorted source ranges must each be arranged with the same ordering that's used by the algorithm to sort the combined ranges. -The source ranges are not modified by the algorithm `merge`. +The source ranges aren't modified by the algorithm `merge`. -The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. More precisely, the algorithm tests whether all the elements in the first sorted range under a specified binary predicate have equivalent ordering to those in the second sorted range. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. More precisely, the algorithm tests whether all the elements in the first sorted range under a specified binary predicate have equivalent ordering to the ones in the second sorted range. The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1` comparisons for nonempty source ranges. @@ -2781,7 +2958,7 @@ A condition to test to order elements. A comparison predicate takes two argument ### Return value -Returns **`true`** if the elements in the specified range form a heap, **`false`** if they do not. +Returns **`true`** if the elements in the specified range form a heap, **`false`** if they don't. ### Remarks @@ -2793,7 +2970,7 @@ The second template function returns ## is_heap_until -Returns an iterator positioned at the first element in the range [ `first`, `last`) that does not satisfy the heap ordering condition, or *`end`* if the range forms a heap. +Returns an iterator positioned at the first element in the range [ `first`, `last`) that doesn't satisfy the heap ordering condition, or *`end`* if the range forms a heap. ```cpp template @@ -2837,7 +3014,7 @@ A binary predicate that specifies the strict weak ordering condition that define ### Return value -Returns *`last`* if the specified range forms a heap or contains one or fewer elements. Otherwise, returns an iterator for the first element found that does not satisfy the heap condition. +Returns *`last`* if the specified range forms a heap or contains one or fewer elements. Otherwise, returns an iterator for the first element found that doesn't satisfy the heap condition. ### Remarks @@ -2876,7 +3053,7 @@ An input iterator that indicates where a range starts to check for a condition. An input iterator that indicates the end of a range. *`pred`*\ -The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** or **`false`**. +The condition to test for. This test is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Return value @@ -2888,7 +3065,7 @@ The template function returns **`true`** only if all elements in `[first, last)` ## `is_permutation` -Returns true if both ranges contain the same elements, whether or not the elements are in the same order. Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range. +Returns `true` if both ranges contain the same elements, whether or not the elements are in the same order. Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range won't detect differences if the second range is longer than the first range. These overloads will result in undefined behavior if the second range is shorter than the first range. ```cpp template @@ -2946,7 +3123,7 @@ A predicate that tests for equivalence and returns a **`bool`**. `is_permutation` has quadratic complexity in the worst case. -The first template function assumes that there are as many elements in the range beginning at *first2* as there are in the range designated by `[first1, last1)`. If there are more elements in the second range, they are ignored; if there are less, undefined behavior will occur. The third template function (C++14 and later) does not make this assumption. Both return **`true`** only if, for each element X in the range designated by `[first1, last1)` there are as many elements Y in the same range for which X == Y as there are in the range beginning at *`first2`* or `[first2, last2)`. Here, `operator==` must perform a pairwise comparison between its operands. +The first template function assumes that there are as many elements in the range beginning at *`first2`* as there are in the range designated by `[first1, last1)`. If there are more elements in the second range, they're ignored; if there are less, undefined behavior will occur. The third template function (C++14 and later) doesn't make this assumption. Both return **`true`** only if, for each element `X` in the range designated by `[first1, last1)` there are as many elements `Y` in the same range for which `X == Y` as there are in the range beginning at *`first2`* or `[first2, last2)`. Here, `operator==` must perform a pairwise comparison between its operands. The second and fourth template functions behave the same, except that they replace `operator==(X, Y)` with `Pred(X, Y)`. To behave correctly, the predicate must be symmetric, reflexive, and transitive. @@ -2998,14 +3175,17 @@ int main() cout << "animals_2 is a permutation of animals_1: " << is_perm << endl; // true - cout << "Press a letter" << endl; - char c; - cin >> c; - return 0; } ``` +```Output +(1) Compare using built-in == operator: true +(2) Compare after modifying vec_2: false +(3) vec_3 is a permutation of vec_4: true +animals_2 is a permutation of animals_1: true +``` + ## `is_sorted` Returns **`true`** if the elements in the specified range are in sorted order. @@ -3048,7 +3228,7 @@ A forward iterator that indicates where the range to check begins. A forward iterator that indicates the end of a range. *`pred`*\ -The condition to test to determine an order between two elements. A comparison predicate takes two arguments and returns **`true`** or **`false`**. This performs the same task as `operator<`. +The condition to test to determine an order between two elements. A comparison predicate takes two arguments and returns **`true`** or **`false`**. This predicate performs the same task as `operator<`. ### Remarks @@ -3437,7 +3617,7 @@ Vector v1 is not lexicographically_less than v2 under twice. ## `lower_bound` -Finds the position of the first element in an ordered range that has a value greater than or equivalent to a specified value, where the ordering criterion may be specified by a binary predicate. +Finds the position of the first element in an ordered range that has a value greater than or equivalent to a specified value. The ordering criterion may be specified by a binary predicate. ```cpp template @@ -3470,7 +3650,7 @@ User-defined predicate function object that defines sense in which one element i ### Return value -A forward iterator at the position of the first element in an ordered range with a value that is greater than or equivalent to a specified value, where the equivalence is specified with a binary predicate. +A forward iterator at the position of the first element in an ordered range with a value that is greater than or equivalent to a specified value. The equivalence may be specified with a binary predicate. ### Remarks @@ -3478,9 +3658,9 @@ The sorted source range referenced must be valid; all iterators must be derefere A sorted range is a precondition of using `lower_bound` and where the ordering is the same as specified by with binary predicate. -The range is not modified by the algorithm `lower_bound`. +The range isn't modified by the algorithm `lower_bound`. -The value types of the forward iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements +The value types of the forward iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last - first`). @@ -3574,6 +3754,19 @@ int main() } ``` +```Output +Starting vector v1 = ( -1 0 1 2 3 4 -3 -2 -1 0 ). +Original vector v1 with range sorted by the + binary predicate less than is v1 = ( -3 -2 -1 -1 0 0 1 2 3 4 ). +Original vector v2 with range sorted by the + binary predicate greater is v2 = ( 4 3 2 1 0 0 -1 -1 -2 -3 ). +Original vector v3 with range sorted by the + binary predicate mod_lesser is v3 = ( 0 0 -1 -1 1 -2 2 -3 3 4 ). +The lower_bound in v1 for the element with a value of 3 is: 3. +The lower_bound in v2 for the element with a value of 3 is: 3. +The lower_bound in v3 for the element with a value of 3 is: -3. +``` + ## `make_heap` Converts elements from a specified range into a heap in which the first element is the largest and for which a sorting criterion may be specified with a binary predicate. @@ -3610,7 +3803,7 @@ Heaps have two properties: - Elements may be added or removed in logarithmic time. -Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). +Heaps are an ideal way to implement priority queues and they're used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). The complexity is linear, requiring `3 * (last - first)` comparisons. @@ -3656,6 +3849,12 @@ int main() { } ``` +```Output +Vector v1 is ( 4 3 7 8 0 5 2 1 6 9 ). +The heaped version of vector v1 is ( 9 8 7 6 3 5 2 1 4 0 ). +The greater-than heaped version of v1 is ( 0 1 2 4 3 5 7 6 9 8 ). +``` + ## `max` Compares two objects and returns the larger of the two, where the ordering criterion may be specified by a binary predicate. @@ -3695,7 +3894,7 @@ The initializer list that contains the objects to be compared. ### Return value -The greater of the two objects, unless neither is greater; in that case, it returns the first of the two objects. In the case of an `initializer_list`, it returns the greatest of the objects in the list. +The greater of the two objects, unless neither is greater; in that case, it returns the first of the two objects. When an `initializer_list` is specified, it returns the greatest of the objects in the list. ### Remarks @@ -3857,7 +4056,9 @@ int main() Using integers 6 and -7... The integer with the greater absolute value is: -7 The integer with the greater value is: 6. -Comparing the members of an initializer_list...The member with the greater value is: 6The integer with the greater absolute value is: -7 +Comparing the members of an initializer_list... +The member with the greater value is: 6 +The integer with the greater absolute value is: -7 s1 = ( CInt( 1 ), CInt( 2 ) ). s2 = ( CInt( 2 ), CInt( 3 ) ). s3 = max ( s1, s2 ) = ( CInt( 2 ), CInt( 3 ) ). @@ -4023,6 +4224,16 @@ int main() } ``` +```Output +s1 = ( CInt( -3 ), CInt( 1 ), CInt( 2 ) ). +The largest element in s1 is: CInt( 2 ) + +Vector v1 is ( 0 1 2 3 -2 -4 -6 -8 ). +The largest element in v1 is: 3 +The largest element in v1 under the mod_lesser + binary predicate is: -8 +``` + ## `merge` Combines all of the elements from two sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate. @@ -4096,13 +4307,13 @@ An output iterator addressing the position one past the last element in the sort The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The destination range should not overlap either of the source ranges and should be large enough to contain the destination range. +The destination range shouldn't overlap either of the source ranges and should be large enough to contain the destination range. The sorted source ranges must each be arranged as a precondition to the application of the `merge` algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm `merge`. +The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges aren't modified by the algorithm `merge`. -The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. The complexity of the algorithm is linear with at most `(last1 - first1) - (last2 - first2) - 1` comparisons. @@ -4218,6 +4429,27 @@ int main() { } ``` +```Output +Original vector v1a with range sorted by the + binary predicate less than is v1a = ( 0 1 2 3 4 5 ). +Original vector v1b with range sorted by the + binary predicate less than is v1b = ( -5 -4 -3 -2 -1 0 ). +Original vector v2a with range sorted by the + binary predicate greater is v2a = ( 5 4 3 2 1 0 ). +Original vector v2b with range sorted by the + binary predicate greater is v2b = ( 0 -1 -2 -3 -4 -5 ). +Original vector v3a with range sorted by the + binary predicate mod_lesser is v3a = ( 0 1 2 3 4 5 ). +Original vector v3b with range sorted by the + binary predicate mod_lesser is v3b = ( 0 -1 -2 -3 -4 -5 ). +Merged inplace with default order, + vector v1mod = ( -5 -4 -3 -2 -1 0 0 1 2 3 4 5 ). +Merged inplace with binary predicate greater specified, + vector v2mod = ( 5 4 3 2 1 0 0 -1 -2 -3 -4 -5 ). +Merged inplace with binary predicate mod_lesser specified, + vector v3mod = ( 0 0 1 -1 2 -2 3 -3 4 -4 5 -5 ). +``` + ## `min` Compares two objects and returns the lesser of the two, where the ordering criterion may be specified by a binary predicate. @@ -4260,7 +4492,7 @@ The `initializer_list` that contains the members to be compared. ### Return value -The lesser of the two objects, unless neither is lesser; in that case, it returns the first of the two objects. In the case of an `initializer_list`, it returns the least of the objects in the list. +The lesser of the two objects, unless neither is lesser; in that case, it returns the first of the two objects. When an `initializer_list` is specified, it returns the least of the objects in the list. ### Remarks @@ -4711,7 +4943,7 @@ The function performs exactly one comparison. Compares two ranges element by element and locates the first position where a difference occurs. -Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range. +Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range won't detect differences if the second range is longer than the first range. These overloads will result in undefined behavior if the second range is shorter than the first range. ```cpp template @@ -4801,21 +5033,21 @@ An input iterator addressing the position of the first element in the second ran An input iterator addressing the position of one past the last element in the second range to be tested. *`pred`*\ -User-defined predicate function object that compares the current elements in each range and determines whether they are equivalent. It returns **`true`** when satisfied and **`false`** when not satisfied. +User-defined predicate function object that compares the current elements in each range and determines whether they're equivalent. It returns **`true`** when satisfied and **`false`** when not satisfied. ### Return value -A pair of iterators addressing the positions of the mismatch in the two ranges, the first component iterator to the position in the first range and the second component iterator to the position in the second range. If there is no difference between the elements in the ranges compared or if the binary predicate in the second version is satisfied by all element pairs from the two ranges, then the first component iterator points to the position one past the final element in the first range and the second component iterator to position one past the final element tested in the second range. +Returns a pair of iterators addressing the positions of the mismatch in the two ranges. The first component iterator points to the position in the first range. The second component iterator points to the position in the second range. If there's no difference between the elements in the ranges compared or if the binary predicate in the second version is satisfied by all element pairs from the two ranges, then the first component iterator points to the position one past the final element in the first range and the second component iterator points to a position one past the final element tested in the second range. ### Remarks -The first template function assumes that there are as many elements in the range beginning at first2 as there are in the range designated by [first1, last1). If there are more in the second range, they are ignored; if there are less, then undefined behavior will result. +The first template function assumes that there are as many elements in the range beginning at first2 as there are in the range designated by [first1, last1). If there are more in the second range, they're ignored; if there are less, then undefined behavior will result. The range to be searched must be valid; all iterators must be dereferenceable and the last position is reachable from the first by incrementation. The time complexity of the algorithm is linear in the number of elements contained in the shorter range. -The user-defined predicate is not required to impose an equivalence relation that symmetric, reflexive, and transitive between its operands. +The user-defined predicate isn't required to impose an equivalence relation that symmetric, reflexive, and transitive between its operands. ### Example @@ -4832,8 +5064,8 @@ The following example demonstrates how to use mismatch. The C++03 overload is sh using namespace std; // Return whether first element is twice the second -// Note that this is not a symmetric, reflexive, and transitive equivalence. -// mismatch and equal accept such predicates, but is_permutation does not. +// Note that this isn't a symmetric, reflexive, and transitive equivalence. +// mismatch and equal accept such predicates, but is_permutation doesn't. bool twice(int elem1, int elem2) { return elem1 == elem2 * 2; @@ -4859,7 +5091,6 @@ void PrintResult(const string& msg, const pair::iterator, vector vec_1{ 0, 5, 10, 15, 20, 25 }; vector vec_2{ 0, 5, 10, 15, 20, 25, 30 }; @@ -4967,7 +5198,7 @@ BidirectionalIterator2 move_backward( An iterator that indicates the start of a range to move elements from. *`last`*\ -An iterator that indicates the end of a range to move elements from. This element is not moved. +An iterator that indicates the end of a range to move elements from. This element isn't moved. *`destEnd`*\ A bidirectional iterator addressing the position of one past the final element in the destination range. @@ -4980,7 +5211,7 @@ The template function evaluates `*(destEnd - N - 1) = move(*(last - N - 1))` onc ## `next_permutation` -Reorders the elements in a range so that the original ordering is replaced by the lexicographically next greater permutation if it exists, where the sense of next may be specified with a binary predicate. +Reorders the elements in a range so that the original ordering is replaced by the lexicographically next greater permutation if it exists. The sense of lexicographically next may be specified with a binary predicate. ```cpp template @@ -5014,7 +5245,7 @@ User-defined predicate function object that defines the comparison criterion to The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -The default binary predicate is less than and the elements in the range must be less than comparable to insure that the next permutation is well defined. +The default binary predicate is less than and the elements in the range must be less than comparable to ensure that the next permutation is well defined. The complexity is linear with at most `(last - first) / 2` swaps. @@ -5159,7 +5390,7 @@ v1 = ( -3 -2 -1 1 0 2 3 ). ## `nth_element` -Partitions a range of elements, correctly locating the *n*th element of the sequence in the range so that all the elements in front of it are less than or equal to it and all the elements that follow it in the sequence are greater than or equal to it. +Partitions a range of elements, correctly locating the *n*th element of the sequence in the range that meets these criteria: All the elements in front of it are less than or equal to it, and all the elements that follow it are greater than or equal to it. ```cpp template @@ -5212,7 +5443,7 @@ User-defined predicate function object that defines the comparison criterion to The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -The `nth_element` algorithm does not guarantee that elements in the subranges either side of the *n*th element are sorted. It thus makes fewer guarantees than `partial_sort`, which orders the elements in the range below some chosen element, and may be used as a faster alternative to `partial_sort` when the ordering of the lower range is not required. +The `nth_element` algorithm doesn't guarantee that elements in the subranges either side of the *n*th element are sorted. It thus makes fewer guarantees than `partial_sort`, which orders the elements in the range below some chosen element, and may be used as a faster alternative to `partial_sort` when the ordering of the lower range isn't required. Elements are equivalent, but not necessarily equal, if neither is less than the other. @@ -5284,6 +5515,18 @@ int main() { } ``` +```Output + v1 = ( 0 3 6 9 12 15 1 4 7 10 13 16 2 5 8 11 14 17 ) +Position 3 partitioned vector: + v1 = ( 1 0 2 3 8 5 9 4 7 6 10 16 13 15 12 11 14 17 ) +Position 4 partitioned (greater) vector: + v1 = ( 16 17 14 15 13 12 11 9 7 8 10 6 1 4 5 3 2 0 ) +Shuffled vector: + v1 = ( 13 10 6 3 5 2 0 17 11 8 15 9 7 14 16 1 12 4 ) +Position 5 partitioned (UDgreater) vector: + v1 = ( 14 17 15 16 13 12 10 11 9 8 0 2 7 5 3 1 6 4 ) +``` + ## `none_of` Returns **`true`** when a condition is never present among elements in the given range. @@ -5315,11 +5558,11 @@ An input iterator that indicates where to start to check a range of elements for An input iterator that indicates the end of a range of elements. *`pred`*\ -The condition to test for. This is provided by a user-defined predicate function object that defines the condition. A unary predicate takes a single argument and returns **`true`** or **`false`**. +The condition to test for. This test is provided by a user-defined predicate function object that defines the condition. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Return value -Returns **`true`** if the condition is not detected at least once in the indicated range, and **`false`** if the condition is detected. +Returns **`true`** if the condition isn't detected at least once in the indicated range, and **`false`** if the condition is detected. ### Remarks @@ -5327,7 +5570,7 @@ The template function returns **`true`** only if, for some `N` in the range `[0, ## `partial_sort` -Arranges a specified number of the smaller elements in a range into a nondescending order or according to an ordering criterion specified by a binary predicate. +Arranges a specified number of the smaller elements in a range into a nondescending order. A binary predicate may supply an ordering criterion. ```cpp template @@ -5380,7 +5623,7 @@ User-defined predicate function object that defines the comparison criterion to The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort` algorithm is not stable and does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort` does preserve this original ordering. +Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort` algorithm isn't stable and doesn't guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort` does preserve this original ordering. The average partial sort complexity is *O*((`last`- `first`) log (`sortEnd`- `first`)). @@ -5522,7 +5765,7 @@ A random-access iterator addressing the element in the destination range one pos The source and destination ranges must not overlap and must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The binary predicate must provide a strict weak ordering so that elements that are not equivalent are ordered, but elements that are equivalent are not. Two elements are equivalent under less than, but not necessarily equal, if neither is less than the other. +The binary predicate must provide a strict weak ordering so that elements that aren't equivalent are ordered, but elements that are equivalent aren't. Two elements are equivalent under less than, but not necessarily equal, if neither is less than the other. ### Example @@ -5600,9 +5843,20 @@ int main() { } ``` +```Output +Vector v1 = ( 4 3 7 8 0 5 2 1 6 9 ) +List list1 = ( 60 50 20 30 40 10 ) +List list1 Vector v1 = ( 10 20 30 8 0 5 2 1 6 9 ) +The first v1 element one position beyond + the last L 1 element inserted was 8. +List list1 into Vector v2 = ( 10 20 30 40 50 60 9 6 7 8 ) +The first v2 element one position beyond + the last L 1 element inserted was 9. +``` + ## `partition` -Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding those that fail to satisfy it. +Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding the ones that fail to satisfy it. ```cpp template @@ -5641,7 +5895,7 @@ A bidirectional iterator addressing the position of the first element in the ran The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -Elements *`a`* and *`b`* are equivalent, but not necessarily equal, if both `pred( a, b )` is false and `pred( b, a )` is false, where *`pred`* is the parameter-specified predicate. The `partition` algorithm is not stable and does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_partition` does preserve this original ordering. +Elements *`a`* and *`b`* are equivalent, but not necessarily equal, if both `pred( a, b )` is false and `pred( b, a )` is false, where *`pred`* is the parameter-specified predicate. The `partition` algorithm isn't stable and doesn't guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_partition` does preserve this original ordering. The complexity is linear: there are `(last - first)` applications of *`pred`* and at most `(last - first)/2` swaps. @@ -5686,6 +5940,11 @@ int main() } ``` +```Output +Vector v1 is ( 4 10 7 8 0 5 2 1 6 9 3 ). +The partitioned set of elements in v1 is: ( 9 10 7 8 6 5 2 1 0 4 3 ). +``` + ## `partition_copy` Copies elements for which a condition is **`true`** to one destination, and for which the condition is **`false`** to another. The elements must come from a specified range. @@ -5727,7 +5986,7 @@ An output iterator used to copy elements that return true for a condition tested An output iterator used to copy elements that return false for a condition tested by using *`pred`*. *`pred`*\ -The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be tested. A unary predicate takes a single argument and returns **`true`** or **`false`**. +The condition to test for. The test is provided by a user-defined predicate function object that defines the condition to be tested. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Remarks @@ -5735,7 +5994,7 @@ The template function copies each element `X` in `[first,last)` to `*dest1++` if ## `partition_point` -Returns the first element in the given range that does not satisfy the condition. The elements are sorted so that those that satisfy the condition come before those that do not. +Returns the first element in the given range that doesn't satisfy the condition. The elements are sorted so that the ones that satisfy the condition come before the ones that don't. ```cpp template @@ -5754,11 +6013,11 @@ A `ForwardIterator` that indicates the start of a range to check for a condition A `ForwardIterator` that indicates the end of a range. *`pred`*\ -The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** or **`false`**. +The condition to test for. The test is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **`true`** or **`false`**. ### Return value -Returns a `ForwardIterator` that refers to the first element that does not fulfill the condition tested for by *`pred`*, or returns *`last`* if one is not found. +Returns a `ForwardIterator` that refers to the first element that doesn't fulfill the condition tested for by *`pred`*, or returns *`last`* if one isn't found. ### Remarks @@ -5802,7 +6061,7 @@ Heaps have two properties: - Elements may be added or removed in logarithmic time. -Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). +Heaps are an ideal way to implement priority queues and they're used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. @@ -5873,9 +6132,20 @@ int main() } ``` +```Output +The heaped version of vector v1 is ( 9 7 8 5 1 6 3 2 4 ). +The reheaped v1 with 10 added is ( 10 9 8 5 7 6 3 2 4 1 ). +The heap v1 with 10 removed is ( 9 7 8 5 1 6 3 2 4 10 ). + +The 'greater than' reheaped v1 puts the smallest element first: + ( 0 1 3 4 2 6 8 5 9 10 7 ). +The 'greater than' heaped v1 with the smallest element + removed from the heap is: ( 1 2 3 4 7 6 8 5 9 10 0 ). +``` + ## `prev_permutation` -Reorders the elements in a range so that the original ordering is replaced by the lexicographically previous greater permutation if it exists, where the sense of previous may be specified with a binary predicate. +Reorders the elements in a range so that the original ordering is replaced by the lexicographically previous greater permutation if it exists. A binary predicate may specify the sense of lexicographically previous. ```cpp template @@ -6086,7 +6356,7 @@ Heaps have two properties: - Elements may be added or removed in logarithmic time. -Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). +Heaps are an ideal way to implement priority queues and they're used in the implementation of the C++ Standard Library container adaptor [priority_queue Class](priority-queue-class.md). The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. @@ -6161,13 +6431,27 @@ int main() { } ``` +```Output +Vector v1 is ( 5 4 8 9 1 6 3 2 7 ). +The heaped version of vector v1 is ( 9 7 8 5 1 6 3 2 4 ). +The heap v1 with 10 pushed back is ( 9 7 8 5 1 6 3 2 4 10 ). +The reheaped v1 with 10 added is ( 10 9 8 5 7 6 3 2 4 1 ). + +The greater-than heaped version of v1 is + ( 1 2 3 4 7 6 8 5 10 9 ). +The greater-than heap v1 with 11 pushed back is + ( 1 2 3 4 7 6 8 5 10 9 0 ). +The greater than reheaped v1 with 11 added is + ( 0 1 3 4 2 6 8 5 10 9 7 ). +``` + ## `random_shuffle` The `std::random_shuffle()` function is deprecated, replaced by [`std::shuffle`](algorithm-functions.md#shuffle). For a code example and more information, see [``](random.md) and the Stack Overflow post [Why are `std::random_shuffle` methods being deprecated in C++14?](https://go.microsoft.com/fwlink/p/?linkid=397954). ## `remove` -Eliminates a specified value from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value. +Eliminates a specified value from a given range without disturbing the order of the remaining elements. Returns the end of a new range free of the specified value. ```cpp template @@ -6210,7 +6494,7 @@ The order of the elements not removed remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear; there are (`last` - `first`) comparisons for equality. +The complexity is linear. It makes (`last` - `first`) comparisons for equality. The [`list` class](list-class.md) has a more efficient member function version of `remove`, which also relinks pointers. @@ -6261,9 +6545,15 @@ int main() } ``` +```Output +Vector v1 is ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +Vector v1 with value 7 removed is ( 4 0 5 1 6 9 3 8 2 9 3 7 8 2 ). +Vector v1 resized with value 7 removed is ( 4 0 5 1 6 9 3 8 2 ). +``` + ## `remove_copy` -Copies elements from a source range to a destination range, except that elements of a specified value are not copied, without disturbing the order of the remaining elements and returning the end of a new destination range. +Copies elements from a source range to a destination range, except that elements of a specified value aren't copied, without disturbing the order of the remaining elements. Returns the end of a new destination range. ```cpp template @@ -6313,7 +6603,7 @@ The order of the elements not removed remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear; there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments. +The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments. ### Example @@ -6359,6 +6649,13 @@ int main() } ``` +```Output +The original vector v1 is: ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +Vector v1 is left unchanged as ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +Vector v2 is a copy of v1 with the value 7 removed: + ( 4 0 5 1 6 9 3 8 2 0 ). +``` + ## `remove_copy_if` Copies elements from a source range to a destination range, except for elements that satisfy a predicate. Elements are copied without disturbing the order of the remaining elements. Returns the end of a new destination range. @@ -6411,7 +6708,7 @@ The order of the elements not removed remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear: there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments. +The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments. For information on how these functions behave, see [Checked Iterators](checked-iterators.md). @@ -6466,9 +6763,17 @@ int main() } ``` +```Output +The original vector v1 is: ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +After the appliation of remove_copy_if to v1, + vector v1 is left unchanged as ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +Vector v2 is a copy of v1 with values greater than 6 removed: + ( 4 0 5 1 6 3 2 ). +``` + ## `remove_if` -Eliminates elements that satisfy a predicate from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value. +Eliminates elements that satisfy a predicate from a given range without disturbing the order of the remaining elements. Returns the end of a new range free of the specified value. ```cpp template @@ -6511,7 +6816,7 @@ The order of the elements not removed remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear: there are (`last` - `first`) comparisons for equality. +The complexity is linear. It makes (`last` - `first`) comparisons for equality. List has a more efficient member function version of remove which relinks pointers. @@ -6567,6 +6872,14 @@ int main() } ``` +```Output +Vector v1 is ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +Vector v1 with elements satisfying greater6 removed is + ( 4 0 5 1 6 3 2 1 6 9 3 7 8 2 ). +Vector v1 resized elements satisfying greater6 removed is + ( 4 0 5 1 6 3 2 ). +``` + ## `replace` Examines each element in a range and replaces it if it matches a specified value. @@ -6613,7 +6926,7 @@ The order of the elements not replaced remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear; there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. +The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. ### Example @@ -6626,34 +6939,44 @@ The complexity is linear; there are (`last` - `first`) comparisons for equality int main() { - using namespace std; - vector v1; - vector::iterator Iter1; + std::vector v; - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); + for (int i = 0; i < 10; i++) + { + v.push_back(i); + } - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i < 3; i++) + { + v.push_back(7); + } - random_shuffle (v1.begin( ), v1.end( ) ); - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + std::cout << "The original vector v is:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + std::cout << *iter << " "; + } + std::cout << ")." << std::endl; // Replace elements with a value of 7 with a value of 700 - replace (v1.begin( ), v1.end( ), 7 , 700); + replace(v.begin(), v.end(), 7, 700); - cout << "The vector v1 with a value 700 replacing that of 7 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + std::cout << "The vector v with 7s replaced with 700s:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + std::cout << *iter << " "; + } + std::cout << ")." << std::endl; } ``` +```Output +The original vector v is: + ( 0 1 2 3 4 5 6 7 8 9 7 7 7 ). +The vector v with 7s replaced with 700s: + ( 0 1 2 3 4 5 6 700 8 9 700 700 700 ). +``` + ## `replace_copy` Examines each element in a source range and replaces it if it matches a specified value while copying the result into a new destination range. @@ -6709,7 +7032,7 @@ The order of the elements not replaced remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear: there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. +The complexity is linear. It makes (`last - first`) comparisons for equality and at most (`last - first`) assignments of new values. ### Example @@ -6724,51 +7047,67 @@ The complexity is linear: there are (`last` - `first`) comparisons for equality int main() { using namespace std; - vector v1; - list L1 (15); - vector::iterator Iter1; - list::iterator L_Iter1; - - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); + vector theVector; + list theList(15); - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i <= 9; i++) + { + theVector.push_back(i); + } - random_shuffle ( v1.begin( ), v1.end( ) ); + for (int i = 0; i <= 3; i++) + { + theVector.push_back(7); + } - int iii; - for ( iii = 0 ; iii <= 15 ; iii++ ) - v1.push_back( 1 ); + random_shuffle(theVector.begin(), theVector.end()); + + for (int i = 0; i <= 15; i++) + { + theVector.push_back(1); + } - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The shuffled vector:\n ( "; + for (auto iter = theVector.begin(); iter != theVector.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; - // Replace elements in one part of a vector with a value of 7 - // with a value of 70 and copy into another part of the vector - replace_copy ( v1.begin( ), v1.begin( ) + 14,v1.end( ) -15, 7 , 70); + // Replace the 7s in part of the vector with 70s + // and copy into another part of the vector + replace_copy(theVector.begin(), theVector.begin() + 14, theVector.end() - 15, 7, 70); - cout << "The vector v1 with a value 70 replacing that of 7 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The vector with instances of 7 replaced with 70 starting at position 14:\n ( "; + for (auto iter = theVector.begin(); iter != theVector.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; - // Replace elements in a vector with a value of 70 - // with a value of 1 and copy into a list - replace_copy ( v1.begin( ), v1.begin( ) + 14,L1.begin( ), 7 , 1); + // Replace 7s found in the first 14 positions in the vector with 1s and then copy the result into a list + replace_copy(theVector.begin(), theVector.begin() + 14, theList.begin(), 7, 1); - cout << "The list copy L1 of v1 with the value 0 replacing " - << "that of 7 is:\n ( " ; - for ( L_Iter1 = L1.begin( ) ; L_Iter1 != L1.end( ) ; L_Iter1++ ) - cout << *L_Iter1 << " "; + cout << "List containing the contents of the vector but 7s replaced with 1s.\n ( "; + for (auto iter = theList.begin(); iter != theList.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; } ``` +Because of the `random_shuffle()` call in the preceding code, your output may be different. + +```Output +The shuffled vector: + ( 7 1 9 2 0 7 7 3 4 6 8 5 7 7 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 ). +The vector with instances of 7 replaced with 70 starting at position 14: + ( 7 1 9 2 0 7 7 3 4 6 8 5 7 7 1 70 1 9 2 0 70 70 3 4 6 8 5 70 70 1 ). +List containing the contents of the vector but 7s replaced with 1s. + ( 1 1 9 2 0 1 1 3 4 6 8 5 1 1 0 ). +``` + ## `replace_copy_if` Examines each element in a source range and replaces it if it satisfies a specified predicate while copying the result into a new destination range. @@ -6824,7 +7163,7 @@ The order of the elements not replaced remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear; there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. +The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. ### Example @@ -6892,6 +7231,17 @@ int main() } ``` +```Output +The original vector v1 is: + ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +The vector v1 with values of 70 replacing those greater + than 6 in the 1st half & copied into the 2nd half is: + ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +A list copy of vector v1 with the value -1 + replacing those greater than 6 is: + ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). +``` + ## `replace_if` Examines each element in a range and replaces it if it satisfies a specified predicate. @@ -6940,7 +7290,7 @@ The algorithm `replace_if` is a generalization of the algorithm `replace`, allow The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear: there are (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. +The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. ### Example @@ -6951,7 +7301,7 @@ The complexity is linear: there are (`last` - `first`) comparisons for equality #include #include -bool greater6 ( int value ) +bool greater6(int value) { return value > 6; } @@ -6959,35 +7309,42 @@ bool greater6 ( int value ) int main() { using namespace std; - vector v1; - vector::iterator Iter1; - - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); + vector v; - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i <= 10; i++) + { + v.push_back(i); + } - random_shuffle ( v1.begin( ), v1.end( ) ); - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The original vector v:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; // Replace elements satisfying the predicate greater6 // with a value of 70 - replace_if ( v1.begin( ), v1.end( ), greater6 , 70); + replace_if(v.begin(), v.end(), greater6, 70); - cout << "The vector v1 with a value 70 replacing those\n " - << "elements satisfying the greater6 predicate is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + cout << "The vector v with a value 70 replacing those\n " + << "elements satisfying the greater6 predicate is:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + cout << *iter << " "; + } + cout << ")."; } ``` +```Output +The original vector v: + ( 0 1 2 3 4 5 6 7 8 9 10 ). +The vector v with a value 70 replacing those + elements satisfying the greater6 predicate is: + ( 0 1 2 3 4 5 6 70 70 70 70 ). +``` + ## `reverse` Reverses the order of the elements within a range. @@ -7145,6 +7502,15 @@ int main() } ``` +```Output +The original vector v1 is: + ( 0 1 2 3 4 5 6 7 8 9 ). +The copy v2 of the reversed vector v1 is: + ( 9 8 7 6 5 4 3 2 1 0 ). +The original vector v1 remains unmodified as: + ( 0 1 2 3 4 5 6 7 8 9 ). +``` + ## `rotate` Exchanges the elements in two adjacent ranges. @@ -7173,7 +7539,7 @@ The execution policy to use. A forward iterator addressing the position of the first element in the range to be rotated. *`middle`*\ -A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with those in the first part of the range. +A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with the ones in the first part of the range. *`last`*\ A forward iterator addressing the position one past the final element in the range to be rotated. @@ -7182,7 +7548,7 @@ A forward iterator addressing the position one past the final element in the ran The ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -The complexity is linear with at most (`last` - `first`) swaps. +The complexity is linear. It makes at most (`last` - `first`) swaps. ### Example @@ -7289,7 +7655,7 @@ The execution policy to use. A forward iterator addressing the position of the first element in the range to be rotated. *`middle`*\ -A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with those in the first part of the range. +A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with the ones in the first part of the range. *`last`*\ A forward iterator addressing the position one past the final element in the range to be rotated. @@ -7305,7 +7671,7 @@ An output iterator addressing the position one past the final element in the des The ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -The complexity is linear with at most (`last` - `first`) swaps. +The complexity is linear. It makes at most (`last` - `first`) swaps. ### Example @@ -7367,6 +7733,27 @@ int main() } ``` +```Output +Vector v1 is ( -3 -2 -1 0 1 2 3 4 5 ). +After rotating, the vector v1 remains unchanged as: + v1 = ( -3 -2 -1 0 1 2 3 4 5 ). +After rotating, the copy of vector v1 in v2 is: + v2 = ( 0 1 2 3 4 5 -3 -2 -1 ). +The original deque d1 is ( 0 1 2 3 4 5 ). +After the rotation of a single deque element to the back, + d2 is ( 1 2 3 4 5 0 ). +After the rotation of a single deque element to the back, + d2 is ( 2 3 4 5 0 1 ). +After the rotation of a single deque element to the back, + d2 is ( 3 4 5 0 1 2 ). +After the rotation of a single deque element to the back, + d2 is ( 4 5 0 1 2 3 ). +After the rotation of a single deque element to the back, + d2 is ( 5 0 1 2 3 4 ). +After the rotation of a single deque element to the back, + d2 is ( 0 1 2 3 4 5 ). +``` + ## `sample` ```cpp @@ -7381,7 +7768,7 @@ SampleIterator sample( ## `search` -Searches for the first occurrence of a sequence within a target range whose elements are equal to those in a given sequence of elements or whose elements are equivalent in a sense specified by a binary predicate to the elements in the given sequence. +Searches for the first occurrence of a sequence within a target range whose elements are equal to the ones in a given sequence of elements or whose elements are equivalent in a sense specified by a binary predicate to the elements in the given sequence. ```cpp template @@ -7456,7 +7843,7 @@ The `operator==` used to determine the match between an element and the specifie The ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation. -Average complexity is linear with respect to the size of the searched range, and worst case complexity is also linear with respect to the size of the sequence being searched for. +Average complexity is linear with respect to the size of the searched range. Worst case complexity is also linear with respect to the size of the sequence being searched for. ### Example @@ -7712,7 +8099,7 @@ predicate one_half in v1 and the first one begins at position 15. ## `set_difference` -Unites all of the elements that belong to one sorted source range, but not to a second sorted source range, into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate. +Unites all of the elements that belong to one sorted source range, but not to a second sorted source range, into a single, sorted destination range. A binary predicate may specify the ordering criterion. ```cpp template @@ -7783,13 +8170,13 @@ An output iterator addressing the position one past the last element in the sort The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The destination range should not overlap either of the source ranges and should be large enough to contain the first source range. +The destination range shouldn't overlap either of the source ranges and should be large enough to contain the first source range. The sorted source ranges must each be arranged as a precondition to the application of the `set_difference` algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm merge. +The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges aren't modified by the algorithm merge. -The value types of the input iterators need to be less-than-comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element such that there are more in the first source range than in the second, then the destination range will contain the number by which the occurrences of those elements in the first source range exceed the occurrences of those elements in the second source range. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element such that there are more in the first source range than in the second, then the destination range will contain the number by which the occurrences of those elements in the first source range exceed the occurrences of those elements in the second source range. The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1` comparisons for nonempty source ranges. @@ -7912,6 +8299,27 @@ int main() } ``` +```Output +Original vector v1a with range sorted by the + binary predicate less than is v1a = ( -1 0 1 2 3 4 ). +Original vector v1b with range sorted by the + binary predicate less than is v1b = ( -3 -2 -1 0 ). +Original vector v2a with range sorted by the + binary predicate greater is v2a = ( 4 3 2 1 0 -1 ). +Original vector v2b with range sorted by the + binary predicate greater is v2b = ( 0 -1 -2 -3 ). +Original vector v3a with range sorted by the + binary predicate mod_lesser is v3a = ( 0 -1 1 2 3 4 ). +Original vector v3b with range sorted by the + binary predicate mod_lesser is v3b = ( 0 -1 -2 -3 ). +Set_difference of source ranges with default order, + vector v1mod = ( 1 2 3 4 ). +Set_difference of source ranges with binarypredicate greater specified, + vector v2mod = ( 4 3 2 1 ). +Set_difference of source ranges with binary predicate mod_lesser specified, + vector v3mod = ( 1 4 ). +``` + ## `set_intersection` Unites all of the elements that belong to both sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate. @@ -7985,13 +8393,13 @@ An output iterator addressing the position one past the last element in the sort The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The destination range should not overlap either of the source ranges and should be large enough to contain the destination range. +The destination range shouldn't overlap either of the source ranges and should be large enough to contain the destination range. The sorted source ranges must each be arranged as a precondition to the application of the merge algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm. +The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges aren't modified by the algorithm. -The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges. The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1` comparisons for nonempty source ranges. @@ -8110,9 +8518,30 @@ int main() } ``` +```Output +Original vector v1a with range sorted by the + binary predicate less than is v1a = ( -1 0 1 2 3 ). +Original vector v1b with range sorted by the + binary predicate less than is v1b = ( -3 -2 -1 0 1 ). +Original vector v2a with range sorted by the + binary predicate greater is v2a = ( 3 2 1 0 -1 ). +Original vector v2b with range sorted by the + binary predicate greater is v2b = ( 1 0 -1 -2 -3 ). +Original vector v3a with range sorted by the + binary predicate mod_lesser is v3a = ( 0 -1 1 2 3 ). +Original vector v3b with range sorted by the + binary predicate mod_lesser is v3b = ( 0 -1 1 -2 -3 ). +Intersection of source ranges with default order, + vector v1mod = ( -1 0 1 ). +Intersection of source ranges with binary predicate greater specified, + vector v2mod = ( 1 0 -1 ). +Intersection of source ranges with binary predicate mod_lesser specified, + vector v3mod = ( 0 -1 1 2 3 ). +``` + ## `set_symmetric_difference` -Unites all of the elements that belong to one, but not both, of the sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate. +Unites all of the elements that belong to one, but not both, of the sorted source ranges into a single, sorted destination range. A binary predicate may specify the ordering criterion. ```cpp template @@ -8183,13 +8612,13 @@ An output iterator addressing the position one past the last element in the sort The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The destination range should not overlap either of the source ranges and should be large enough to contain the destination range. +The destination range shouldn't overlap either of the source ranges and should be large enough to contain the destination range. The sorted source ranges must each be arranged as a precondition to the application of the `merge*` algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm merge. +The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges aren't modified by the algorithm merge. -The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the absolute value of the number by which the occurrences of those elements in the one of the source ranges exceeds the occurrences of those elements in the second source range. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the absolute value of the number by which the occurrences of those elements in the one of the source ranges exceeds the occurrences of those elements in the second source range. The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1` comparisons for nonempty source ranges. @@ -8312,9 +8741,30 @@ int main() } ``` +```Output +Original vector v1a with range sorted by the + binary predicate less than is v1a = ( -1 0 1 2 3 4 ). +Original vector v1b with range sorted by the + binary predicate less than is v1b = ( -3 -2 -1 0 ). +Original vector v2a with range sorted by the + binary predicate greater is v2a = ( 4 3 2 1 0 -1 ). +Original vector v2b with range sorted by the + binary predicate greater is v2b = ( 0 -1 -2 -3 ). +Original vector v3a with range sorted by the + binary predicate mod_lesser is v3a = ( 0 -1 1 2 3 4 ). +Original vector v3b with range sorted by the + binary predicate mod_lesser is v3b = ( 0 -1 -2 -3 ). +Set_symmetric_difference of source ranges with default order, + vector v1mod = ( -3 -2 1 2 3 4 ). +Set_symmetric_difference of source ranges with binarypredicate greater specified, + vector v2mod = ( 4 3 2 1 -2 -3 ). +Set_symmetric_difference of source ranges with binary predicate mod_lesser specified, + vector v3mod = ( 1 4 ). +``` + ## `set_union` -Unites all of the elements that belong to at least one of two sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate. +Unites all of the elements that belong to at least one of two sorted source ranges into a single, sorted destination range. A binary predicate may specify the ordering criterion. ```cpp template @@ -8385,13 +8835,13 @@ An output iterator addressing the position one past the last element in the sort The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. -The destination range should not overlap either of the source ranges and should be large enough to contain the destination range. +The destination range shouldn't overlap either of the source ranges and should be large enough to contain the destination range. The sorted source ranges must each be arranged as a precondition to the application of the `merge` algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. -The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm `merge`. +The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges aren't modified by the algorithm `merge`. -The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges. +The value types of the input iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges. The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1` comparisons. @@ -8514,6 +8964,27 @@ int main() } ``` +```Output +Original vector v1a with range sorted by the + binary predicate less than is v1a = ( -1 0 1 2 3 ). +Original vector v1b with range sorted by the + binary predicate less than is v1b = ( -3 -2 -1 0 1 ). +Original vector v2a with range sorted by the + binary predicate greater is v2a = ( 3 2 1 0 -1 ). +Original vector v2b with range sorted by the + binary predicate greater is v2b = ( 1 0 -1 -2 -3 ). +Original vector v3a with range sorted by the + binary predicate mod_lesser is v3a = ( 0 -1 1 2 3 ). +Original vector v3b with range sorted by the + binary predicate mod_lesser is v3b = ( 0 -1 1 -2 -3 ). +Union of source ranges with default order, + vector v1mod = ( -3 -2 -1 0 1 2 3 ). +Union of source ranges with binary predicate greater specified, + vector v2mod = ( 3 2 1 0 -1 -2 -3 ). +Union of source ranges with binary predicate mod_lesser specified, + vector v3mod = ( 0 -1 1 2 3 ). +``` + ## `shuffle` Shuffles (rearranges) elements for a given range by using a random number generator. @@ -8589,7 +9060,7 @@ User-defined predicate function object that defines the comparison criterion to The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort` algorithm is not stable and so does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort` does preserve this original ordering. +Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort` algorithm isn't stable and so doesn't guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort` does preserve this original ordering. The average of a sort complexity is `O( N log N )`, where *N* = *`last`* - *`first`*. @@ -8699,9 +9170,9 @@ Heaps have two properties: After the application if this algorithm, the range it was applied to is no longer a heap. -This is not a stable sort because the relative order of equivalent elements is not necessarily preserved. +`sort_heap` isn't a stable sort because the relative order of equivalent elements isn't necessarily preserved. -Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor [`priority_queue` Class](priority-queue-class.md). +Heaps are an ideal way to implement priority queues and they're used in the implementation of the C++ Standard Library container adaptor [`priority_queue` Class](priority-queue-class.md). The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. @@ -8761,9 +9232,19 @@ int main() } ``` +```Output +Initially: ( 1 2 3 4 5 6 7 8 9 ) +After random_shuffle: ( 5 4 8 9 1 6 3 2 7 ) + After make_heap: ( 9 7 8 5 1 6 3 2 4 ) + After sort_heap: ( 1 2 3 4 5 6 7 8 9 ) + After random_shuffle: ( 1 3 6 8 9 5 4 2 7 ) +After make_heap with greater: ( 1 2 4 3 9 5 6 8 7 ) +After sort_heap with greater: ( 9 8 7 6 5 4 3 2 1 ) +``` + ## `stable_partition` -Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding those that fail to satisfy it, preserving the relative order of equivalent elements. +Classifies elements in a range into two disjoint sets, with the elements that satisfy a unary predicate preceding the ones that fail to satisfy it, preserving the relative order of equivalent elements. ```cpp template @@ -8802,7 +9283,7 @@ A bidirectional iterator addressing the position of the first element in the ran The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. -Elements *a* and *b* are equivalent, but not necessarily equal, if both `pred( a, b )` is false and `pred( b, a )` is false, where *`pred`* is the parameter-specified predicate. The `stable_partition` algorithm is stable and guarantees that the relative ordering of equivalent elements will be preserved. The algorithm `partition` does not necessarily preserve this original ordering. +Elements *a* and *b* are equivalent, but not necessarily equal, if both `pred( a, b )` is false and `pred( b, a )` is false, where *`pred`* is the parameter-specified predicate. The `stable_partition` algorithm is stable and guarantees that the relative ordering of equivalent elements will be preserved. The algorithm `partition` doesn't necessarily preserve this original ordering. ### Example @@ -8851,9 +9332,17 @@ int main() } ``` +```Output +Vector v1 is ( 4 10 5 5 5 5 5 1 6 9 3 7 8 2 0 5 ). +The partitioned set of elements in v1 is: + ( 10 6 9 7 8 4 5 5 5 5 5 1 3 2 0 5 ). +The first element in v1 to fail to satisfy the + predicate greater5 is: 4. +``` + ## `stable_sort` -Arranges the elements in a specified range into a nondescending order or according to an ordering criterion specified by a binary predicate and preserves the relative ordering of equivalent elements. +Arranges the elements in a specified range into a nondescending order or according to an ordering criterion specified by a binary predicate. It preserves the relative ordering of equivalent elements. ```cpp template @@ -8901,7 +9390,7 @@ The range referenced must be valid; all pointers must be dereferenceable and wit Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort` algorithm is stable and guarantees that the relative ordering of equivalent elements will be preserved. -The run-time complexity of `stable_sort` depends on the amount of memory available, but the best case (given sufficient memory) is `O(N log N)` and the worst case is `O(N (log N)^2)`, where *N* = *`last`* - *`first`*. Usually, the `sort` algorithm is significantly faster than `stable_sort`. +The run-time complexity of `stable_sort` depends on the amount of memory available, but the best case (given sufficient memory) is `O(N log N)` and the worst case is `O(N (log N)^2)`, where *N* = *`last`* - *`first`*. Usually, the `sort` algorithm is faster than `stable_sort`. ### Example @@ -9159,7 +9648,7 @@ After the swap_range deque d1 is ( 0 1 2 3 4 5 ). ## `transform` -Applies a specified function object to each element in a source range or to a pair of elements from two source ranges and copies the return values of the function object into a destination range. +Applies a specified function object to each element in a source range or to a pair of elements from two source ranges. Then, it copies the return values of the function object into a destination range. ```cpp template @@ -9201,19 +9690,19 @@ ForwardIterator transform( The execution policy to use. *`first1`*\ -An input iterator addressing the position of the first element in the first source range to be operated on. +An input iterator addressing the position of the first element in the first source range to operate on. *`last1`*\ -An input iterator addressing the position one past the final element in the first source range operated on. +An input iterator addressing the position one past the final element in the first source range to operate on. *`first2`*\ -An input iterator addressing the position of the first element in the second source range to be operated on. +An input iterator addressing the position of the first element in the second source range to operate on. *`result`*\ An output iterator addressing the position of the first element in the destination range. *`func`*\ -User-defined unary function object used in the first version of the algorithm that is applied to each element in the first source range or A user-defined (UD) binary function object used in the second version of the algorithm that is applied pairwise, in a forward order, to the two source ranges. +User-defined unary function object used in the first version of the algorithm to apply to each element in the first source range or a user-defined (UD) binary function object used in the second version of the algorithm that is applied pairwise, in a forward order, to the two source ranges. ### Return value @@ -9225,7 +9714,7 @@ The ranges referenced must be valid; all pointers must be dereferenceable and wi If *result* is set equal to *`first1`* in the first version of the algorithm, then the source and destination ranges will be the same and the sequence will be modified in place. But the *`result`* may not address a position within the range [`first1` + 1, `last1`). -The complexity is linear with at most (`last1` - `first1`) comparisons. +The complexity is linear. It makes at most (`last1` - `first1`) comparisons. ### Example @@ -9315,7 +9804,7 @@ v3 = ( 320 180 80 20 0 20 80 ). ## `unique` -Removes duplicate elements that are adjacent to each other in a specified range. +Removes duplicate elements that are next to each other in a specified range. ```cpp template @@ -9365,15 +9854,15 @@ A forward iterator to the new end of the modified sequence that contains no cons Both forms of the algorithm remove the second duplicate of a consecutive pair of equal elements. -The operation of the algorithm is stable so that the relative order of the undeleted elements is not changed. +The operation of the algorithm is stable so that the relative order of the undeleted elements isn't changed. -The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. The number of elements in the sequence is not changed by the algorithm `unique` and the elements beyond the end of the modified sequence are dereferenceable but not specified. +The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. The number of elements in the sequence isn't changed by the algorithm `unique` and the elements beyond the end of the modified sequence are dereferenceable but not specified. The complexity is linear, requiring `(last - first) - 1` comparisons. List provides a more efficient member function "unique", which may perform better. -These algorithms cannot be used on an associative container. +These algorithms can't be used on an associative container. ### Example @@ -9464,7 +9953,7 @@ Removing adjacent elements satisfying the binary ## `unique_copy` -Copies elements from a source range into a destination range except for the duplicate elements that are adjacent to each other. +Copies elements from a source range into a destination range except for the duplicate elements that are next to each other. ```cpp template @@ -9521,7 +10010,7 @@ An output iterator addressing the position one past the final element in the des Both forms of the algorithm remove the second duplicate of a consecutive pair of equal elements. -The operation of the algorithm is stable so that the relative order of the undeleted elements is not changed. +The operation of the algorithm is stable so that the relative order of the undeleted elements isn't changed. The ranges referenced must be valid; all pointers must be dereferenceable and within a sequence the last position is reachable from the first by incrementation. @@ -9599,9 +10088,20 @@ int main() { } ``` +```Output +Vector v1 is + ( 5 -5 5 -5 4 4 4 7 10 10 10 10 10 10 ). +Copying the first half of the vector to the second half + while removing adjacent duplicates gives + ( 5 -5 5 -5 4 4 4 7 5 -5 5 -5 4 7 ). +Copying the first half of the vector to the second half + removing adjacent duplicates under mod_equals gives + ( 5 -5 5 -5 4 4 4 7 5 -5 5 -5 4 7 5 4 7 5 4 7 ). +``` + ## `upper_bound` -Finds the position of the first element in an ordered range that has a value that is greater than a specified value, where the ordering criterion may be specified by a binary predicate. +Finds the position of the first element in an ordered range that has a value that's greater than a specified value. A binary predicate specifies the ordering criterion. ```cpp template @@ -9642,9 +10142,9 @@ The sorted source range referenced must be valid; all iterators must be derefere A sorted range is a precondition of the use of `upper_bound` and where the ordering criterion is the same as specified by the comparison predicate. -The range is not modified by `upper_bound`. +The range isn't modified by `upper_bound`. -The value types of the forward iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements +The value types of the forward iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last - first`). @@ -9737,3 +10237,16 @@ int main() << *Result << "." << endl; } ``` + +```Output +Starting vector v1 = ( -1 0 1 2 3 4 -3 -2 -1 0 ). +Original vector v1 with range sorted by the + binary predicate less than is v1 = ( -3 -2 -1 -1 0 0 1 2 3 4 ). +Original vector v2 with range sorted by the + binary predicate greater is v2 = ( 4 3 2 1 0 0 -1 -1 -2 -3 ). +Original vector v3 with range sorted by the + binary predicate mod_lesser is v3 = ( 0 0 -1 -1 1 -2 2 -3 3 4 ). +The upper_bound in v1 for the element with a value of 3 is: 4. +The upper_bound in v2 for the element with a value of 3 is: 2. +The upper_bound in v3 for the element with a value of 3 is: 4. +``` diff --git a/docs/standard-library/algorithm.md b/docs/standard-library/algorithm.md index 8ab79fbea5..7db53924b1 100644 --- a/docs/standard-library/algorithm.md +++ b/docs/standard-library/algorithm.md @@ -1,10 +1,9 @@ --- description: "Learn more about: " title: "" -ms.date: "11/04/2016" +ms.date: 01/27/2023 f1_keywords: [""] helpviewer_keywords: ["algorithm header [C++]", "C++ Standard Library, algorithms", " header"] -ms.assetid: 19f97711-7a67-4a65-8fd1-9a2bd3ca327d --- # `` @@ -13,7 +12,7 @@ Defines C++ Standard Library container template functions that perform algorithm ## Syntax ```cpp -(see relevant links below for specific algorithm syntax) +(see links below for specific algorithm syntax) ``` > [!NOTE] @@ -21,21 +20,23 @@ Defines C++ Standard Library container template functions that perform algorithm ## Remarks -The C++ Standard Library algorithms are generic because they can operate on a variety of data structures. The data structures that they can operate on include not only the C++ Standard Library container classes such as `vector` and `list`, but also program-defined data structures and arrays of elements that satisfy the requirements of a particular algorithm. C++ Standard Library algorithms achieve this level of generality by accessing and traversing the elements of a container indirectly through iterators. +The C++ Standard Library algorithms can operate on various data structures. The data structures that they can operate on include not only the C++ Standard Library container classes such as `vector` and `list`, but also user-defined data structures and arrays of elements, as long as they satisfy the requirements of a particular algorithm. C++ Standard Library algorithms achieve this level of generality by accessing and traversing the elements of a container indirectly through iterators. -C++ Standard Library algorithms process iterator ranges that are typically specified by their beginning or ending positions. The ranges referred to must be valid in the sense that all pointers in the ranges must be dereferenceable and, within the sequences of each range, the last position must be reachable from the first by incrementation. +C++ Standard Library algorithms process iterator ranges that are typically specified by their beginning or ending positions. The ranges referred to must be valid in the sense that all iterators in the ranges must be dereferenceable and, within the sequences of each range, the last position must be reachable from the first by incrementing the iterator. -The C++ Standard Library algorithms extend the actions supported by the operations and member functions of each C++ Standard Library container and allow working, for example, with different types of container objects at the same time. Two suffixes have been used to convey information about the purpose of the algorithms. +Starting in C++20, most of the algorithms defined in [``](algorithm.md) are also available in a form that takes a `range`. For example, rather than call `sort(v1.begin(), v1.end(), greater());`, you can call `ranges::sort(v1, greater());` -- The `_if` suffix indicates that the algorithm is used with function objects operating on the values of the elements rather than on the elements themselves. The `find_if` algorithm looks for elements whose values satisfy the criterion specified by a function object, and the `find` algorithm searches for a particular value. +The C++ Standard Library algorithms can work with different types of container objects at the same time. Two suffixes have been used to convey information about the purpose of the algorithms: -- The _copy suffix indicates that the algorithm not only manipulates the values of the elements but also copies the modified values into a destination range. The `reverse` algorithm reverses the order of the elements within a range, and the `reverse_copy` algorithm also copies the result into a destination range. +- The `_if` suffix indicates that the algorithm is used with function objects that operate on the values of the elements rather than on the elements themselves. For example, the `find_if` algorithm looks for elements whose values satisfy the criterion specified by a function object, whereas the `find` algorithm searches for a particular value. -C++ Standard Library algorithms are often classified into groups that indicate something about their purpose or requirements. These include modifying algorithms that change the value of elements as compared with non-modifying algorithms that do not. Mutating algorithms change the order of elements, but not the values of their elements. Removing algorithms can eliminate elements from a range or a copy of a range. Sorting algorithms reorder the elements in a range in various ways and sorted range algorithms only act on ranges whose elements have been sorted in a particular way. +- The `_copy` suffix indicates that the algorithm generally modifies copied values rather than copy modified values. In other words, they don't modify the source range's elements but put the results into an output range/iterator. For example, the `reverse` algorithm reverses the order of the elements within a range, whereas the `reverse_copy` algorithm copies the reversed result into a destination range. -The C++ Standard Library numeric algorithms that are provided for numerical processing have their own header file [``](numeric.md), and function objects and adaptors are defined in the header [``](functional.md) Function objects that return Boolean values are known as predicates. The default binary predicate is the comparison `operator<`. In general, the elements being ordered need to be less than comparable so that, given any two elements, it can be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering among the nonequivalent elements. +C++ Standard Library algorithms are often classified into groups to indicate their purpose or requirements. These include modifying algorithms that change the value of elements as compared with non-modifying algorithms that don't. Mutating algorithms change the order of elements, but not the values of their elements. Removing algorithms can eliminate elements from a range or a copy of a range. Sorting algorithms reorder the elements in a range in various ways and sorted range algorithms only act on ranges whose elements have been sorted in a particular way. -### Function templates +The C++ Standard Library numeric algorithms that are provided for numerical processing have their own header file [``](numeric.md), and function objects and adaptors are defined in the header [``](functional.md). Function objects that return Boolean values are known as predicates. The default binary predicate is the comparison `operator<`. In general, the elements being ordered need to be less than comparable so that, given any two elements, it can be determined either that they're equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering among the nonequivalent elements. + +### Algorithms |Name|Description| |-|-| @@ -58,11 +59,11 @@ The C++ Standard Library numeric algorithms that are provided for numerical proc |[`find_end`](algorithm-functions.md#find_end)|Looks in a range for the last subsequence that is identical to a specified sequence or that is equivalent in a sense specified by a binary predicate.| |[`find_first_of`](algorithm-functions.md#find_first_of)|Searches for the first occurrence of any of several values within a target range or for the first occurrence of any of several elements that are equivalent in a sense specified by a binary predicate to a specified set of the elements.| |[`find_if`](algorithm-functions.md#find_if)|Locates the position of the first occurrence of an element in a range that satisfies a specified condition.| -|[`find_if_not`](algorithm-functions.md#find_if_not)|Returns the first element in the indicated range that does not satisfy a condition.| +|[`find_if_not`](algorithm-functions.md#find_if_not)|Returns the first element in the indicated range that doesn't satisfy a condition.| |[`for_each`](algorithm-functions.md#for_each)|Applies a specified function object to each element in a forward order within a range and returns the function object.| |[`for_each_n`](algorithm-functions.md#for_each_n)|| |[`generate`](algorithm-functions.md#generate)|Assigns the values generated by a function object to each element in a range.| -|[`generate_n`](algorithm-functions.md#generate_n)|Assigns the values generated by a function object to a specified number of element is a range and returns to the position one past the last assigned value.| +|[`generate_n`](algorithm-functions.md#generate_n)|Assigns the values generated by a function object to a specified number of elements in a range and returns to the position one past the last assigned value.| |[`includes`](algorithm-functions.md#includes)|Tests whether one sorted range contains all the elements contained in a second sorted range, where the ordering or equivalence criterion between elements may be specified by a binary predicate.| |[`inplace_merge`](algorithm-functions.md#inplace_merge)|Combines the elements from two consecutive sorted ranges into a single sorted range, where the ordering criterion may be specified by a binary predicate.| |[`is_heap`](algorithm-functions.md#is_heap)|Returns **`true`** if the elements in the specified range form a heap.| @@ -92,14 +93,14 @@ The C++ Standard Library numeric algorithms that are provided for numerical proc |[`partial_sort_copy`](algorithm-functions.md#partial_sort_copy)|Copies elements from a source range into a destination range where the source elements are ordered by either less than or another specified binary predicate.| |[`partition`](algorithm-functions.md#partition)|Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding those that fail to satisfy it.| |[`partition_copy`](algorithm-functions.md#partition_copy)|Copies elements for which a condition is **`true`** to one destination, and for which the condition is **`false`** to another. The elements must come from a specified range.| -|[`partition_point`](algorithm-functions.md#partition_point)|Returns the first element in the given range that does not satisfy the condition. The elements are sorted so that those that satisfy the condition come before those that do not.| +|[`partition_point`](algorithm-functions.md#partition_point)|Returns the first element in the given range that doesn't satisfy the condition. The elements are sorted so that those that satisfy the condition come before those that don't.| |[`pop_heap`](algorithm-functions.md#pop_heap)|Removes the largest element from the front of a heap to the next-to-last position in the range and then forms a new heap from the remaining elements.| |[`prev_permutation`](algorithm-functions.md#prev_permutation)|Reorders the elements in a range so that the original ordering is replaced by the lexicographically next greater permutation if it exists, where the sense of next may be specified with a binary predicate.| |[`push_heap`](algorithm-functions.md#push_heap)|Adds an element that is at the end of a range to an existing heap consisting of the prior elements in the range.| |[`random_shuffle`](algorithm-functions.md#random_shuffle)|Rearranges a sequence of *N* elements in a range into one of *N*! possible arrangements selected at random.| |[`remove`](algorithm-functions.md#remove)|Eliminates a specified value from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value.| -|[`remove_copy`](algorithm-functions.md#remove_copy)|Copies elements from a source range to a destination range, except that elements of a specified value are not copied, without disturbing the order of the remaining elements and returning the end of a new destination range.| -|[`remove_copy_if`](algorithm-functions.md#remove_copy_if)|Copies elements from a source range to a destination range, except that satisfying a predicate are not copied, without disturbing the order of the remaining elements and returning the end of a new destination range.| +|[`remove_copy`](algorithm-functions.md#remove_copy)|Copies elements from a source range to a destination range, except that elements of a specified value aren't copied, without disturbing the order of the remaining elements and returning the end of a new destination range.| +|[`remove_copy_if`](algorithm-functions.md#remove_copy_if)|Copies elements from a source range to a destination range, except that satisfying a predicate aren't copied, without disturbing the order of the remaining elements and returning the end of a new destination range.| |[`remove_if`](algorithm-functions.md#remove_if)|Eliminates elements that satisfy a predicate from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value.| |[`replace`](algorithm-functions.md#replace)|Examines each element in a range and replaces it if it matches a specified value.| |[`replace_copy`](algorithm-functions.md#replace_copy)|Examines each element in a source range and replaces it if it matches a specified value while copying the result into a new destination range.| @@ -124,8 +125,8 @@ The C++ Standard Library numeric algorithms that are provided for numerical proc |[`swap`](algorithm-functions.md#swap)|Exchanges the values of the elements between two types of objects, assigning the contents of the first object to the second object and the contents of the second to the first.| |[`swap_ranges`](algorithm-functions.md#swap_ranges)|Exchanges the elements of one range with the elements of another, equal sized range.| |[`transform`](algorithm-functions.md#transform)|Applies a specified function object to each element in a source range or to a pair of elements from two source ranges and copies the return values of the function object into a destination range.| -|[`unique`](algorithm-functions.md#unique)|Removes duplicate elements that are adjacent to each other in a specified range.| -|[`unique_copy`](algorithm-functions.md#unique_copy)|Copies elements from a source range into a destination range except for the duplicate elements that are adjacent to each other.| +|[`unique`](algorithm-functions.md#unique)|Removes duplicate elements that are next to each other in a specified range.| +|[`unique_copy`](algorithm-functions.md#unique_copy)|Copies elements from a source range into a destination range except for the duplicate elements that are next to each other.| |[`upper_bound`](algorithm-functions.md#upper_bound)|Finds the position of the first element in an ordered range that has a value that is greater than a specified value, where the ordering criterion may be specified by a binary predicate.| ## See also diff --git a/docs/standard-library/algorithms.md b/docs/standard-library/algorithms.md index 99abb8354b..b79a77b3b3 100644 --- a/docs/standard-library/algorithms.md +++ b/docs/standard-library/algorithms.md @@ -1,43 +1,42 @@ --- description: "Learn more about: Algorithms" title: "Algorithms" -ms.date: "10/18/2018" +ms.date: 01/27/2023 helpviewer_keywords: ["libraries [C++], C++ algorithm conventions", "algorithms [C++], C++", "C++ Standard Library, algorithms", "algorithm template function C++ library conventions", "conventions [C++], C++ algorithm"] -ms.assetid: dec9b373-7d5c-46cc-b7d2-21a938ecd0a6 --- # Algorithms -Algorithms are a fundamental part of the C++ Standard Library. Algorithms do not work with containers themselves but rather with iterators. Therefore, the same algorithm can be used by most if not all of the C++ Standard Library containers. This section discusses the conventions and terminology of the C++ Standard Library algorithms. +Algorithms are a fundamental part of the C++ Standard Library. Algorithms don't work with containers themselves but rather with iterators. Therefore, the same algorithm can be used by most if not all of the C++ Standard Library containers. This section discusses the conventions and terminology of the C++ Standard Library algorithms. ## Remarks -The descriptions of the algorithm template functions employ several shorthand phrases: +The descriptions of the algorithm function templates employ several shorthand phrases: -- The phrase "in the range \[*A*, *B*)" means the sequence of zero or more discrete values beginning with *A* up to but not including *B*. A range is valid only if *B* is reachable from *A;* you can store *A* in an object *N* (*N* = *A*), increment the object zero or more times (++*N*), and have the object compare equal to *B* after a finite number of increments (*N* == *B*). +- The phrase "in the range \[*A*, *B*)" means the sequence of zero or more discrete values beginning with *A* up to but not including *B*. A range is valid only if *B* is reachable from *A*, you can store *A* in an object *N* (*N* = *A*), you can increment the object zero or more times (++*N*), and have the object compare equal to *B* after a finite number of increments (*N* == *B*). -- The phrase "each *N* in the range \[*A*, *B*)" means that *N* begins with the value *A* and is incremented zero or more times until it equals the value *B*. The case *N* == *B* is not in the range. +- The phrase "each *N* in the range \[*A*, *B*)" means that *N* begins with the value *A* and is incremented zero or more times until it equals the value *B*. The case *N* == *B* isn't in the range. - The phrase "the lowest value of *N* in the range \[*A*, *B*) such that *X*" means that the condition *X* is determined for each *N* in the range \[*A*, *B*) until the condition *X* is met. -- The phrase "the highest value of *N* in the range \[*A*, *B*) such that *X* means that *X* is determined for each *N* in the range \[*A*, *B*). The function stores in *K* a copy of *N* each time the condition *X* is met. If any such store occurs, the function replaces the final value of *N*, which equals *B*, with the value of *K*. For a bidirectional or random-access iterator, however, it can also mean that *N* begins with the highest value in the range and is decremented over the range until the condition *X* is met. +- The phrase "the highest value of *N* in the range \[*A*, *B*) such that *X*" means that *X* is determined for each *N* in the range \[*A*, *B*). The function stores in *K* a copy of *N* each time the condition *X* is met. If any such store occurs, the function replaces the final value of *N*, which equals *B*, with the value of *K*. For a bidirectional or random-access iterator, however, it can also mean that *N* begins with the highest value in the range and is decremented over the range until the condition *X* is met. -- Expressions such as *X* - *Y*, where *X* and *Y* can be iterators other than random-access iterators, are intended in the mathematical sense. The function does not necessarily evaluate operator **-** if it must determine such a value. The same is also true for expressions such as *X* + *N* and *X* - *N*, where *N* is an integer type. +- Expressions such as *X* - *Y*, where *X* and *Y* can be iterators other than random-access iterators, are intended in the mathematical sense. The function doesn't necessarily evaluate operator **-** if it must determine such a value. The same is also true for expressions such as *X* + *N* and *X* - *N*, where *N* is an integer type. -Several algorithms make use of a predicate that performs a pairwise comparison, such as with `operator==`, to yield a **`bool`** result. The predicate function `operator==`, or any replacement for it, must not alter either of its operands. It must yield the same **`bool`** result every time it is evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. +Several algorithms make use of a predicate that performs a pairwise comparison, such as with `operator==`, to yield a **`bool`** result. The predicate function `operator==`, or any replacement for it, must not alter either of its operands. It must yield the same **`bool`** result every time it's evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. Several algorithms make use of a predicate that must impose a strict weak ordering on pairs of elements from a sequence. For the predicate *pred*(*X*, *Y*): - Strict means that *pred*(*X*, *X*) is false. -- Weak means that *X* and *Y* have an equivalent ordering if \!*pred*(*X*, *Y*) && \!*pred*(*Y*, *X*) (*X* == *Y* does not need to be defined). +- Weak means that *X* and *Y* have an equivalent ordering if \!*pred*(*X*, *Y*) && \!*pred*(*Y*, *X*) (*X* == *Y* doesn't need to be defined). - Ordering means that *pred*(*X*, *Y*) && *pred*(*Y*, *Z*) implies *pred*(*X*, *Z*). -Some of these algorithms implicitly use the predicate *X* \< *Y*. Other predicates that typically satisfy the strict weak ordering requirement are *X* > *Y*, `less`(*X*, *Y*), and `greater`(*X*, *Y*). Note, however, that predicates such as *X* \<= *Y* and *X* >= *Y* do not satisfy this requirement. +Some of these algorithms implicitly use the predicate *X* \< *Y*. Other predicates that typically satisfy the strict weak ordering requirement are *X* > *Y*, `less`(*X*, *Y*), and `greater`(*X*, *Y*). Note, however, that predicates such as *X* \<= *Y* and *X* >= *Y* don't satisfy this requirement. -A sequence of elements designated by iterators in the range \[*`First`*, *`Last`*) is a sequence ordered by operator **`<`** if, for each *N* in the range \[0, *`Last`* - *`First`*) and for each *M* in the range (*N*, *`Last`* - *`First`*) the predicate \!(\*(*`First`* + *M*) < \*(*`First`* + *N*)) is true. (Note that the elements are sorted in ascending order.) The predicate function `operator<`, or any replacement for it, must not alter either of its operands. It must yield the same **`bool`** result every time it is evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. Moreover, it must impose a strict weak ordering on the operands it compares. +A sequence of elements designated by iterators in the range \[*`First`*, *`Last`*) is a sequence ordered by operator **`<`** if, for each *N* in the range \[0, *`Last`* - *`First`*) and for each *M* in the range (*N*, *`Last`* - *`First`*) the predicate \!(\*(*`First`* + *M*) < \*(*`First`* + *N*)) is true. (Note that the elements are sorted in ascending order.) The predicate function `operator<`, or any replacement for it, must not alter either of its operands. It must yield the same **`bool`** result every time it's evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. Moreover, it must impose a strict weak ordering on the operands it compares. -A sequence of elements designated by iterators in the range \[`First`, `Last`) is a heap ordered by `operator<` if, for each *N* in the range \[1, *`Last`* - *`First`*) the predicate \!(\*_First_ < \*(*`First`* + *N*)) is true. (The first element is the largest.) Its internal structure is otherwise known only to the template functions [`make_heap`](algorithm-functions.md#make_heap), [`pop_heap`](algorithm-functions.md#pop_heap), and [`push_heap`](algorithm-functions.md#push_heap). As with an ordered sequence, the predicate function `operator<`, or any replacement for it, must not alter either of its operands, and it must impose a strict weak ordering on the operands it compares. It must yield the same **`bool`** result every time it is evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. +A sequence of elements designated by iterators in the range \[`First`, `Last`) is a heap ordered by `operator<` if, for each *N* in the range \[1, *`Last`* - *`First`*) the predicate \!(\*_First_ < \*(*`First`* + *N*)) is true. (The first element is the largest.) Its internal structure is otherwise known only to the template functions [`make_heap`](algorithm-functions.md#make_heap), [`pop_heap`](algorithm-functions.md#pop_heap), and [`push_heap`](algorithm-functions.md#push_heap). As with an ordered sequence, the predicate function `operator<`, or any replacement for it, must not alter either of its operands, and it must impose a strict weak ordering on the operands it compares. It must yield the same **`bool`** result every time it's evaluated, and it must yield the same result if a copy of either operand is substituted for the operand. The C++ Standard Library algorithms are located in the [``](algorithm.md) and [``](numeric.md) header files. diff --git a/docs/standard-library/allocator-base-class.md b/docs/standard-library/allocator-base-class.md index 4a88c1deca..024eeeff0c 100644 --- a/docs/standard-library/allocator-base-class.md +++ b/docs/standard-library/allocator-base-class.md @@ -1,10 +1,11 @@ --- description: "Learn more about: allocator_base Class" title: "allocator_base Class" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["allocators/stdext::allocator_base", "allocators/stdext::allocators::allocator_base", "allocators/stdext::allocator_base::const_pointer", "allocators/stdext::allocator_base::const_reference", "allocators/stdext::allocator_base::difference_type", "allocators/stdext::allocator_base::pointer", "allocators/stdext::allocator_base::reference", "allocators/stdext::allocator_base::size_type", "allocators/stdext::allocator_base::value_type", "allocators/stdext::allocator_base::_Charalloc", "allocators/stdext::allocator_base::_Chardealloc", "allocators/stdext::allocator_base::address", "allocators/stdext::allocator_base::allocate", "allocators/stdext::allocator_base::construct", "allocators/stdext::allocator_base::deallocate", "allocators/stdext::allocator_base::destroy", "allocators/stdext::allocator_base::max_size"] helpviewer_keywords: ["stdext::allocator_base [C++]", "stdext::allocators [C++], allocator_base", "stdext::allocator_base [C++], const_pointer", "stdext::allocator_base [C++], const_reference", "stdext::allocator_base [C++], difference_type", "stdext::allocator_base [C++], pointer", "stdext::allocator_base [C++], reference", "stdext::allocator_base [C++], size_type", "stdext::allocator_base [C++], value_type", "stdext::allocator_base [C++], _Charalloc", "stdext::allocator_base [C++], _Chardealloc", "stdext::allocator_base [C++], address", "stdext::allocator_base [C++], allocate", "stdext::allocator_base [C++], construct", "stdext::allocator_base [C++], deallocate", "stdext::allocator_base [C++], destroy", "stdext::allocator_base [C++], max_size"] ms.assetid: f920b45f-2a88-4bb0-8ead-b6126b426ed4 +ms.custom: devdivchpfy22 --- # allocator_base Class @@ -81,7 +82,7 @@ A pointer to the allocated object. ### Remarks -This member function is used by containers when compiled with a compiler that cannot compile rebind. It implements `_Charalloc` for the user-defined allocator by returning the result of a call to the `allocate` function of the synchronization filter. +This member function is used by containers when compiled with a compiler that can't compile rebind. It implements `_Charalloc` for the user-defined allocator by returning the result of a call to the `allocate` function of the synchronization filter. ## allocator_base::_Chardealloc @@ -101,7 +102,7 @@ The number of objects to be deallocated from storage. ### Remarks -This member function is used by containers when compiled with a compiler that cannot compile rebind. It implements `_Chardealloc` for the user-defined allocator by calling the `deallocate` function of the synchronization filter. The pointer ptr must have been earlier returned by a call to `_Charalloc` for an allocator object that compares equal to **`*this`**, allocating an array object of the same size and type. `_Chardealloc` never throws an exception. +This member function is used by containers when compiled with a compiler that can't compile rebind. It implements `_Chardealloc` for the user-defined allocator by calling the `deallocate` function of the synchronization filter. The pointer ptr must have been earlier returned by a call to `_Charalloc` for an allocator object that compares equal to **`*this`**, allocating an array object of the same size and type. `_Chardealloc` never throws an exception. ## allocator_base::address diff --git a/docs/standard-library/allocators.md b/docs/standard-library/allocators.md index 4098745171..350d07257c 100644 --- a/docs/standard-library/allocators.md +++ b/docs/standard-library/allocators.md @@ -3,11 +3,10 @@ description: "Learn more about: Allocators" title: "Allocators" ms.date: "11/04/2016" helpviewer_keywords: ["allocators", "C++ Standard Library, allocators"] -ms.assetid: ac95023b-9e7d-49f5-861a-bf7a9a340746 --- # Allocators -Allocators are used by the C++ Standard Library to handle the allocation and deallocation of elements stored in containers. All C++ Standard Library containers except std::array have a template parameter of type `allocator`, where `Type` represents the type of the container element. For example, the vector class is declared as follows: +Allocators are used by the C++ Standard Library to handle the allocation and deallocation of elements stored in containers. All C++ Standard Library containers except `std::array` have a template parameter of type `allocator`, where `Type` represents the type of the container element. For example, the `vector` class is declared as follows: ```cpp template < @@ -17,28 +16,28 @@ template < class vector ``` -The C++ Standard Library provides a default implementation for an allocator. In C++11 and later, the default allocator is updated to expose a smaller interface; the new allocator is called a *minimal allocator*. In particular, the minimal allocator's `construct()` member supports move semantics, which can greatly improve performance. In most cases, this default allocator should be sufficient. In C++11 all the Standard Library types and functions that take an allocator type parameter support the minimal allocator interface, including `std::function`, `shared_ptr, allocate_shared()`, and `basic_string`. For more information on the default allocator, see [allocator Class](allocator-class.md). +The C++ Standard Library provides a default implementation for an allocator. In C++11 and later, the default allocator is updated to expose a smaller interface; the new allocator is called a *minimal allocator*. In particular, the minimal allocator's `construct()` member supports move semantics, which can greatly improve performance. In most cases, this default allocator should be sufficient. In C++11 all the Standard Library types and functions that take an allocator type parameter support the minimal allocator interface, including `std::function`, `shared_ptr, allocate_shared()`, and `basic_string`. For more information on the default allocator, see [`allocator` Class](allocator-class.md). ## Writing Your Own Allocator (C++11) The default allocator uses **`new`** and **`delete`** to allocate and deallocate memory. If you want to use a different method of memory allocation, such as using shared memory, then you must create your own allocator. If you are targeting C++11 and you need to write a new custom allocator, make it a minimal allocator if possible. Even if you have already implemented an old-style allocator, consider modifying it to be a *minimal allocator* in order to take advantage of the more efficient `construct()` method that will be provided for you automatically. -A minimal allocator requires much less boilerplate and enable you to focus on the `allocate` and `deallocate` member functions which do all of the work. When creating a minimal allocator, do not implement any members except the ones shown in the example below: +A minimal allocator requires much less boilerplate and enables you to focus on the `allocate` and `deallocate` member functions, which do all of the work. When creating a minimal allocator, do not implement any members except the ones shown in the example below: 1. a converting copy constructor (see example) -1. operator== +1. `operator==` -1. operator!= +1. `operator!=` -1. allocate +1. `allocate` -1. deallocate +1. `deallocate` The C++11 default `construct()` member that will be provided for you does perfect forwarding and enables move semantics; it is much more efficient in many cases than the older version. > [!WARNING] -> At compile time, the C++ Standard Library uses the allocator_traits class to detect which members you have explicitly provided and provides a default implementation for any members that are not present. Do not interfere with this mechanism by providing a specialization of allocator_traits for your allocator! +> At compile time, the C++ Standard Library uses the `allocator_traits` class to detect which members you have explicitly provided and provides a default implementation for any members that are not present. Do not interfere with this mechanism by providing a specialization of `allocator_traits` for your allocator! The following example shows a minimal implementation of an allocator that uses `malloc` and `free`. Note the use of the new exception type `std::bad_array_new_length` which is thrown if the array size is less than zero or greater than the maximum allowed size. @@ -137,7 +136,7 @@ In addition, any allocator used with C++ Standard Library containers must implem :::column-end::: :::row-end::: -For more information on these type definitions and methods, see [allocator Class](allocator-class.md). +For more information on these type definitions and methods, see [`allocator` Class](allocator-class.md). ## See also diff --git a/docs/standard-library/ambiguous-local-time.md b/docs/standard-library/ambiguous-local-time.md index 42978b8423..72dba2eb71 100644 --- a/docs/standard-library/ambiguous-local-time.md +++ b/docs/standard-library/ambiguous-local-time.md @@ -4,6 +4,7 @@ title: "ambiguous_local_time class" ms.date: 10/08/2021 f1_keywords: ["chrono/std::chrono::ambiguous_local_time", "chrono/std::chrono::ambiguous_local_time::what"] helpviewer_keywords: ["std::chrono [C++], ambiguous_local_time"] +dev_langs: ["C++"] --- # `ambiguous_local_time` class @@ -13,7 +14,7 @@ This exception is thrown when attempting to convert a `local_time` to a `sys_tim ## Syntax ```cpp -class ambiguous_local_time : public runtime_error; // C++ 20 +class ambiguous_local_time : public runtime_error; // C++20 ``` ## Remarks @@ -97,7 +98,7 @@ You typically won't create this exception. It's thrown by functions that convert Gets a string describing the details of the ambiguity. ```cpp -[nodiscard] virtual const char* what() const noexcept; +[[nodiscard]] virtual const char* what() const noexcept; ``` ### Return value diff --git a/docs/standard-library/any.md b/docs/standard-library/any.md index d1302376e5..752a8bda88 100644 --- a/docs/standard-library/any.md +++ b/docs/standard-library/any.md @@ -6,7 +6,7 @@ f1_keywords: [""] helpviewer_keywords: [""] no-loc: ["any", "std", "class"] --- -# ``; +# `` Defines the class `std::any` and several supporting functions and classes. diff --git a/docs/standard-library/array-class-stl.md b/docs/standard-library/array-class-stl.md index 0e8c6678d6..29f281de65 100644 --- a/docs/standard-library/array-class-stl.md +++ b/docs/standard-library/array-class-stl.md @@ -1,10 +1,11 @@ --- description: "Learn more about: array Class (C++ Standard Library)" -title: "array Class (C++ Standard Library)| Microsoft Docs" -ms.date: "11/13/2019" +title: array Class (C++ Standard Library) +ms.date: 06/07/2022 f1_keywords: ["array/std::array", "array/std::array::const_iterator", "array/std::array::const_pointer", "array/std::array::const_reference", "array/std::array::const_reverse_iterator", "array/std::array::difference_type", "array/std::array::iterator", "array/std::array::pointer", "array/std::array::reference", "array/std::array::reverse_iterator", "array/std::array::size_type", "array/std::array::value_type", "array/std::array::assign", "array/std::array::at", "array/std::array::back", "array/std::array::begin", "array/std::array::cbegin", "array/std::array::cend", "array/std::array::crbegin", "array/std::array::crend", "array/std::array::data", "array/std::array::empty", "array/std::array::end", "array/std::array::fill", "array/std::array::front", "array/std::array::max_size", "array/std::array::rbegin", "array/std::array::rend", "array/std::array::size", "array/std::array::swap", "array/std::array::operator=", "array/std::array::operator[]"] helpviewer_keywords: ["std::array [C++]", "std::array [C++], const_iterator", "std::array [C++], const_pointer", "std::array [C++], const_reference", "std::array [C++], const_reverse_iterator", "std::array [C++], difference_type", "std::array [C++], iterator", "std::array [C++], pointer", "std::array [C++], reference", "std::array [C++], reverse_iterator", "std::array [C++], size_type", "std::array [C++], value_type", "std::array [C++], assign", "std::array [C++], at", "std::array [C++], back", "std::array [C++], begin", "std::array [C++], cbegin", "std::array [C++], cend", "std::array [C++], crbegin", "std::array [C++], crend", "std::array [C++], data", "std::array [C++], empty", "std::array [C++], end", "std::array [C++], fill", "std::array [C++], front", "std::array [C++], max_size", "std::array [C++], rbegin", "std::array [C++], rend", "std::array [C++], size", "std::array [C++], swap", ", ", "std::array [C++], const_iterator", "std::array [C++], const_pointer", "std::array [C++], const_reference", "std::array [C++], const_reverse_iterator", "std::array [C++], difference_type", "std::array [C++], iterator", "std::array [C++], pointer", "std::array [C++], reference", "std::array [C++], reverse_iterator", "std::array [C++], size_type", "std::array [C++], value_type", "std::array [C++], assign", "std::array [C++], at", "std::array [C++], back", "std::array [C++], begin", "std::array [C++], cbegin", "std::array [C++], cend", "std::array [C++], crbegin", "std::array [C++], crend", "std::array [C++], data", "std::array [C++], empty", "std::array [C++], end", "std::array [C++], fill", "std::array [C++], front", "std::array [C++], max_size", "std::array [C++], rbegin", "std::array [C++], rend", "std::array [C++], size", "std::array [C++], swap"] ms.assetid: fdfd43a5-b2b5-4b9e-991f-93bf10fb4293 +ms.custom: devdivchpfy22 --- # `array` Class (C++ Standard Library) @@ -114,8 +115,6 @@ The copy constructor `array(const array& right)` initializes the controlled sequ typedef std::array Myarray; int main() { - typedef std::array Myarray; - Myarray c0 = { 0, 1, 2, 3 }; // display contents " 0 1 2 3" @@ -297,9 +296,9 @@ A **`const`** random-access iterator that points at the first element of the ran ### Remarks -With the return value of `cbegin`, the elements in the range cannot be modified. +With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -325,7 +324,7 @@ A random-access iterator that points just beyond the end of the range. `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -335,7 +334,7 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -The value returned by `cend` should not be dereferenced. +The value returned by `cend` shouldn't be dereferenced. ## `array::const_iterator` @@ -531,7 +530,7 @@ A const reverse random-access iterator addressing the first element in a reverse ### Remarks -With the return value of `crbegin`, the array object cannot be modified. +With the return value of `crbegin`, the array object can't be modified. ### Example @@ -575,13 +574,13 @@ A const reverse random-access iterator that addresses the location succeeding th ### Remarks -`crend` is used with a reversed array just as [`array::cend`](#cend) is used with a array. +`crend` is used with a reversed array just as [`array::cend`](#cend) is used with an array. -With the return value of `crend` (suitably decremented), the array object cannot be modified. +With the return value of `crend` (suitably decremented), the array object can't be modified. `crend` can be used to test to whether a reverse iterator has reached the end of its array. -The value returned by `crend` should not be dereferenced. +The value returned by `crend` shouldn't be dereferenced. ### Example @@ -661,7 +660,7 @@ typedef std::ptrdiff_t difference_type; ### Remarks -The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It is a synonym for the type `std::ptrdiff_t`. +The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It's a synonym for the type `std::ptrdiff_t`. ### Example @@ -793,7 +792,7 @@ int main() ## `array::fill` -Erases a array and copies the specified elements to the empty array. +Erases an array and copies the specified elements to the empty array. ```cpp void fill(const Type& val); @@ -992,7 +991,7 @@ Position of element to access. The member functions return a reference to the element of the controlled sequence at position *`off`*. If that position is invalid, the behavior is undefined. -There is also a non-member [`get`](array-functions.md#get) function available to get a reference to an element of an **`array`**. +There's also a non-member [`get`](array-functions.md#get) function available to get a reference to an element of an **`array`**. ### Example @@ -1348,7 +1347,7 @@ int main() ## `array::size_type` -The type of an unsigned distance between two element. +The type of an unsigned distance between two elements. ```cpp typedef std::size_t size_type; @@ -1356,7 +1355,7 @@ typedef std::size_t size_type; ### Remarks -The unsigned integer type describes an object that can represent the length of any controlled sequence. It is a synonym for the type `std::size_t`. +The unsigned integer type describes an object that can represent the length of any controlled sequence. It's a synonym for the type `std::size_t`. ### Example @@ -1405,9 +1404,9 @@ Array to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`*this`** and *right*. It performs a number of element assignments and constructor calls proportional to `N`. +The member function swaps the controlled sequences between **`*this`** and *right*. It performs element assignments and constructor calls proportional to `N`. -There is also a non-member [`swap`](array-functions.md#swap) function available to swap two **`array`** instances. +There's also a non-member [`swap`](array-functions.md#swap) function available to swap two **`array`** instances. ### Example diff --git a/docs/standard-library/array-operators.md b/docs/standard-library/array-operators.md index 866d09f22e..56925a09ca 100644 --- a/docs/standard-library/array-operators.md +++ b/docs/standard-library/array-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["array/std::array::operator!=", "array/std::array::operator<", "array/std::array::operator<=", "array/std::array::operator>", "array/std::array::operator>=", "array/std::array::operator=="] -ms.assetid: c8f46282-f179-4909-9a01-639cb8e18c27 --- # `` operators @@ -116,7 +115,7 @@ Right container to compare. ### Remarks -The template function overloads `operator<` to compare two objects of class template [array Class](../standard-library/array-class-stl.md). The function returns `lexicographical_compare(left.begin(), left.end(), right.begin())`. +The template function overloads `operator<` to compare two objects of class template [`array`](../standard-library/array-class-stl.md). The function returns `lexicographical_compare(left.begin(), left.end(), right.begin())`. ### Example @@ -262,7 +261,7 @@ Right container to compare. ### Remarks -The template function overloads `operator==` to compare two objects of class template [array Class](../standard-library/array-class-stl.md). The function returns `equal(left.begin(), left.end(), right.begin())`. +The template function overloads `operator==` to compare two objects of class template [`array`](../standard-library/array-class-stl.md). The function returns `equal(left.begin(), left.end(), right.begin())`. ### Example diff --git a/docs/standard-library/array.md b/docs/standard-library/array.md index 07fc0bfe58..85273440ba 100644 --- a/docs/standard-library/array.md +++ b/docs/standard-library/array.md @@ -4,7 +4,6 @@ title: "" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: ["array header"] -ms.assetid: 084147c1-e805-478e-8201-76846020f187 --- # `` diff --git a/docs/standard-library/atomic-flag-structure.md b/docs/standard-library/atomic-flag-structure.md index 68669e510c..4c872e719c 100644 --- a/docs/standard-library/atomic-flag-structure.md +++ b/docs/standard-library/atomic-flag-structure.md @@ -1,9 +1,10 @@ --- description: "Learn more about: atomic_flag Structure" title: "atomic_flag Structure" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["atomic/std::atomic_flag", "atomic/std::atomic_flag::clear", "atomic/std::atomic_flag::test_and_set"] ms.assetid: 17f0c2f5-fd39-4a44-873a-b569720a670e +ms.custom: devdivchpfy22 --- # atomic_flag Structure diff --git a/docs/standard-library/atomic-functions.md b/docs/standard-library/atomic-functions.md index a8a8db35d4..9dcd5b5bae 100644 --- a/docs/standard-library/atomic-functions.md +++ b/docs/standard-library/atomic-functions.md @@ -1,41 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "07/11/2018" +description: "Learn more about: functions" +ms.date: 07/11/2018 f1_keywords: ["atomic/std::atomic_compare_exchange_strong", "atomic/std::atomic_compare_exchange_strong_explicit", "atomic/std::atomic_compare_exchange_weak", "atomic/std::atomic_compare_exchange_weak_explicit", "atomic/std::atomic_exchange", "atomic/std::atomic_exchange_explicit", "atomic/std::atomic_fetch_add", "atomic/std::atomic_fetch_add_explicit", "atomic/std::atomic_fetch_and", "atomic/std::atomic_fetch_and_explicit", "atomic/std::atomic_fetch_or", "atomic/std::atomic_fetch_or_explicit", "atomic/std::atomic_fetch_sub", "atomic/std::atomic_fetch_sub_explicit", "atomic/std::atomic_fetch_xor", "atomic/std::atomic_fetch_xor_explicit", "atomic/std::atomic_flag_clear", "atomic/std::atomic_flag_clear_explicit", "atomic/std::atomic_flag_test_and_set", "atomic/std::atomic_flag_test_and_set_explicit", "atomic/std::atomic_init", "atomic/std::atomic_is_lock_free", "atomic/std::atomic_load", "atomic/std::atomic_load_explicit", "atomic/std::atomic_signal_fence", "atomic/std::atomic_store", "atomic/std::atomic_store_explicit", "atomic/std::atomic_thread_fence", "atomic/std::kill_dependency"] helpviewer_keywords: ["std::atomic_compare_exchange_strong [C++]", "std::atomic_compare_exchange_strong_explicit [C++]", "std::atomic_compare_exchange_weak [C++]", "std::atomic_compare_exchange_weak_explicit [C++]", "std::atomic_exchange [C++]", "std::atomic_exchange_explicit [C++]", "std::atomic_fetch_add [C++]", "std::atomic_fetch_add_explicit [C++]", "std::atomic_fetch_and [C++]", "std::atomic_fetch_and_explicit [C++]", "std::atomic_fetch_or [C++]", "std::atomic_fetch_or_explicit [C++]", "std::atomic_fetch_sub [C++]", "std::atomic_fetch_sub_explicit [C++]", "std::atomic_fetch_xor [C++]", "std::atomic_fetch_xor_explicit [C++]", "std::atomic_flag_clear [C++]", "std::atomic_flag_clear_explicit [C++]", "std::atomic_flag_test_and_set [C++]", "std::atomic_flag_test_and_set_explicit [C++]", "std::atomic_init [C++]", "std::atomic_is_lock_free [C++]", "std::atomic_load [C++]", "std::atomic_load_explicit [C++]", "std::atomic_signal_fence [C++]", "std::atomic_store [C++]", "std::atomic_store_explicit [C++]", "std::atomic_thread_fence [C++]", "std::kill_dependency [C++]"] --- # `` functions -[atomic_compare_exchange_strong](#atomic_compare_exchange_strong)\ -[atomic_compare_exchange_strong_explicit](#atomic_compare_exchange_strong_explicit)\ -[atomic_compare_exchange_weak](#atomic_compare_exchange_weak)\ -[atomic_compare_exchange_weak_explicit](#atomic_compare_exchange_weak_explicit)\ -[atomic_exchange](#atomic_exchange)\ -[atomic_exchange_explicit](#atomic_exchange_explicit)\ -[atomic_fetch_add](#atomic_fetch_add)\ -[atomic_fetch_add_explicit](#atomic_fetch_add_explicit)\ -[atomic_fetch_and](#atomic_fetch_and)\ -[atomic_fetch_and_explicit](#atomic_fetch_and_explicit)\ -[atomic_fetch_or](#atomic_fetch_or)\ -[atomic_fetch_or_explicit](#atomic_fetch_or_explicit)\ -[atomic_fetch_sub](#atomic_fetch_sub)\ -[atomic_fetch_sub_explicit](#atomic_fetch_sub_explicit)\ -[atomic_fetch_xor](#atomic_fetch_xor)\ -[atomic_fetch_xor_explicit](#atomic_fetch_xor_explicit)\ -[atomic_flag_clear](#atomic_flag_clear)\ -[atomic_flag_clear_explicit](#atomic_flag_clear_explicit)\ -[atomic_flag_test_and_set](#atomic_flag_test_and_set)\ -[atomic_flag_test_and_set_explicit](#atomic_flag_test_and_set_explicit)\ -[atomic_init](#atomic_init)\ -[atomic_is_lock_free](#atomic_is_lock_free)\ -[atomic_load](#atomic_load)\ -[atomic_load_explicit](#atomic_load_explicit)\ -[atomic_signal_fence](#atomic_signal_fence)\ -[atomic_store](#atomic_store)\ -[atomic_store_explicit](#atomic_store_explicit)\ -[atomic_thread_fence](#atomic_thread_fence)\ -[kill_dependency](#kill_dependency) +The `` header provides the following functions: ## `atomic_compare_exchange_strong` @@ -676,8 +648,8 @@ A [`memory_order`](../standard-library/atomic-enums.md#memory_order_enum). Sets the **`bool`** flag in an [`atomic_flag`](../standard-library/atomic-flag-structure.md) object to **`true`**, within the constraints of the [`memory_order.memory_order_seq_cst`](../standard-library/atomic-enums.md#memory_order_enum). ```cpp -inline bool atomic_flag_test_and_set(volatile atomic_flag* Flag,) noexcept; -inline bool atomic_flag_test_and_set(atomic_flag* Flag,) noexcept; +inline bool atomic_flag_test_and_set(volatile atomic_flag* Flag) noexcept; +inline bool atomic_flag_test_and_set(atomic_flag* Flag) noexcept; ``` ### Parameters diff --git a/docs/standard-library/atomic-structure.md b/docs/standard-library/atomic-structure.md index b7e3efd3e2..9ee633323f 100644 --- a/docs/standard-library/atomic-structure.md +++ b/docs/standard-library/atomic-structure.md @@ -1,13 +1,13 @@ --- description: "Learn more about: atomic Structure" title: "atomic Structure" -ms.date: "04/20/2018" +ms.date: 06/07/2022 f1_keywords: ["atomic/std::atomic"] -ms.assetid: 261628ed-7049-41ac-99b9-cfe49f696b44 +ms.custom: devdivchpfy22 --- -# atomic Structure +# `atomic` Structure -Describes an object that performs atomic operations on a stored value of type *Ty*. +Describes an object that performs `atomic` operations on a stored value of type *`Ty`*. ## Syntax @@ -21,34 +21,34 @@ struct atomic; |Member|Description| |----------|-----------------| |**Constructor**|| -|[atomic](#atomic)|Constructs an atomic object.| +|[`atomic`](#atomic)|Constructs an atomic object.| |**Operators**|| -|[atomic::operator Ty](#op_ty)|Reads and returns the stored value. ([atomic::load](#load))| -|[atomic::operator=](#op_eq)|Uses a specified value to replace the stored value. ([atomic::store](#store))| -|[atomic::operator++](#op_inc)|Increments the stored value. Used only by integral and pointer specializations.| -|[atomic::operator+=](#op_add_eq)|Adds a specified value to the stored value. Used only by integral and pointer specializations.| -|[atomic::operator--](#op_dec)|Decrements the stored value. Used only by integral and pointer specializations.| -|[atomic::operator-=](#op_sub_eq)|Subtracts a specified value from the stored value. Used only by integral and pointer specializations.| -|[atomic::operator&=](#op_and_eq)|Performs a bitwise and on a specified value and the stored value. Used only by integral specializations.| -|[atomic::operator|=](#op_or_eq)|Performs a bitwise or on a specified value and the stored value. Used only by integral specializations.| -|[atomic::operator^=](#op_xor_eq)|Performs a bitwise exclusive or on a specified value and the stored value. Used only by integral specializations.| +|[`atomic::operator Ty`](#op_ty)|Reads and returns the stored value. ([`atomic::load`](#load))| +|[`atomic::operator=`](#op_eq)|Uses a specified value to replace the stored value. ([`atomic::store`](#store))| +|[`atomic::operator++`](#op_inc)|Increments the stored value. Used only by integral and pointer specializations.| +|[`atomic::operator+=`](#op_add_eq)|Adds a specified value to the stored value. Used only by integral and pointer specializations.| +|[`atomic::operator--`](#op_dec)|Decrements the stored value. Used only by integral and pointer specializations.| +|[`atomic::operator-=`](#op_sub_eq)|Subtracts a specified value from the stored value. Used only by integral and pointer specializations.| +|[`atomic::operator&=`](#op_and_eq)|Performs a bitwise "and" (`&`) on a specified value and the stored value. Used only by integral specializations.| +|[`atomic::operator|=`](#op_or_eq)|Performs a bitwise "or" (`|`) on a specified value and the stored value. Used only by integral specializations.| +|[`atomic::operator^=`](#op_xor_eq)|Performs a bitwise "exclusive or" (`^`) on a specified value and the stored value. Used only by integral specializations.| |**Functions**|| -|[compare_exchange_strong](#compare_exchange_strong)|Performs an *atomic_compare_and_exchange* operation on **`this`** and returns the result.| -|[compare_exchange_weak](#compare_exchange_weak)|Performs a *weak_atomic_compare_and_exchange* operation on **`this`** and returns the result.| -|[fetch_add](#fetch_add)|Adds a specified value to the stored value.| -|[fetch_and](#fetch_and)|Performs a bitwise and on a specified value and the stored value.| -|[fetch_or](#fetch_or)|Performs a bitwise or on a specified value and the stored value.| -|[fetch_sub](#fetch_sub)|Subtracts a specified value from the stored value.| -|[fetch_xor](#fetch_xor)|Performs a bitwise exclusive or on a specified value and the stored value.| -|[is_lock_free](#is_lock_free)|Specifies whether atomic operations on **`this`** are *lock free*. An atomic type is *lock free* if no atomic operations on that type use locks.| -|[load](#load)|Reads and returns the stored value.| -|[store](#store)|Uses a specified value to replace the stored value.| +|[`compare_exchange_strong`](#compare_exchange_strong)|Performs an *`atomic_compare_and_exchange`* operation on **`this`** and returns the result.| +|[`compare_exchange_weak`](#compare_exchange_weak)|Performs a *`weak_atomic_compare_and_exchange`* operation on **`this`** and returns the result.| +|[`fetch_add`](#fetch_add)|Adds a specified value to the stored value.| +|[`fetch_and`](#fetch_and)|Performs a bitwise "and" (`&`) on a specified value and the stored value.| +|[`fetch_or`](#fetch_or)|Performs a bitwise "or" (`|`) on a specified value and the stored value.| +|[`fetch_sub`](#fetch_sub)|Subtracts a specified value from the stored value.| +|[`fetch_xor`](#fetch_xor)|Performs a bitwise "exclusive or" (`^`) on a specified value and the stored value.| +|[`is_lock_free`](#is_lock_free)|Specifies whether `atomic` operations on **`this`** are *lock free*. An `atomic` type is *lock free* if no `atomic` operations on that type use locks.| +|[`load`](#load)|Reads and returns the stored value.| +|[`store`](#store)|Uses a specified value to replace the stored value.| ## Remarks -The type *Ty* must be *trivially copyable*. That is, using [memcpy](../c-runtime-library/reference/memcpy-wmemcpy.md) to copy its bytes must produce a valid *Ty* object that compares equal to the original object. The [compare_exchange_weak](#compare_exchange_weak) and [compare_exchange_strong](#compare_exchange_strong) member functions use [memcmp](../c-runtime-library/reference/memcmp-wmemcmp.md) to determine whether two *Ty* values are equal. These functions will not use a *Ty*-defined `operator==`. The member functions of `atomic` use `memcpy` to copy values of type *Ty*. +The type *`Ty`* must be *trivially copyable*. That is, using [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) to copy its bytes must produce a valid *`Ty`* object that compares equal to the original object. The [`compare_exchange_weak`](#compare_exchange_weak) and [`compare_exchange_strong`](#compare_exchange_strong) member functions use [`memcmp`](../c-runtime-library/reference/memcmp-wmemcmp.md) to determine whether two *`Ty`* values are equal. These functions won't use a *`Ty`*-defined `operator==`. The member functions of `atomic` use `memcpy` to copy values of type *`Ty`*. -A partial specialization, `atomic`, exists for all pointer types. The specialization enables the addition of an offset to the managed pointer value or the subtraction of an offset from it. The arithmetic operations take an argument of type `ptrdiff_t` and adjust that argument according to the size of *Ty* to be consistent with ordinary address arithmetic. +A partial specialization, `atomic`, exists for all pointer types. The specialization enables the addition of an offset to the managed pointer value or the subtraction of an offset from it. The arithmetic operations take an argument of type `ptrdiff_t` and adjust that argument according to the size of *`Ty`* to be consistent with ordinary address arithmetic. A specialization exists for every integral type except **`bool`**. Each specialization provides a rich set of methods for atomic arithmetic and logical operations. @@ -77,11 +77,11 @@ Integral specializations are derived from corresponding `atomic_integral` types. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## atomic::atomic +## `atomic::atomic` Constructs an atomic object. @@ -93,23 +93,23 @@ atomic( Ty Value ) noexcept; ### Parameters -*Value*\ +*`Value`*\ Initialization value. ### Remarks -Atomic objects cannot be copied or moved. +Atomic objects can't be copied or moved. -Objects that are instantiations of atomic\<*Ty*> can be initialized only by the constructor that takes an argument of type *Ty* and not by using aggregate initialization. However, atomic_integral objects can be initialized only by using aggregate initialization. +Objects that are instantiations of `atomic` can be initialized only by the constructor that takes an argument of type *`Ty`* and not by using aggregate initialization. However, `atomic_integral` objects can be initialized only by using aggregate initialization. ```cpp atomic ai0 = ATOMIC_VAR_INIT(0); atomic ai1(0); ``` -## atomic::operator *Ty* +## `atomic::operator Ty` -The operator for the type specified to the template, atomic\<*Ty*>. Retrieves the stored value in **\*this**. +The operator for the type specified to the template, `atomic`. Retrieves the stored value in **`*this`**. ```cpp atomic::operator Ty() const volatile noexcept; @@ -118,9 +118,9 @@ atomic::operator Ty() const noexcept; ### Remarks -This operator applies the `memory_order_seq_cst` [memory_order](atomic-enums.md). +This operator applies the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator= +## `atomic::operator=` Stores a specified value. @@ -135,14 +135,14 @@ Ty operator=( ### Parameters -*Value*\ -A *Ty* object. +*`Value`*\ +A *`Ty`* object. ### Return Value -Returns *Value*. +Returns *`Value`*. -## atomic::operator++ +## `atomic::operator++` Increments the stored value. Used only by integral and pointer specializations. @@ -155,9 +155,9 @@ Ty atomic::operator++() noexcept; ### Return Value -The first two operators return the incremented value; the last two operators return the value before the increment. The operators use the `memory_order_seq_cst` [memory_order](atomic-enums.md). +The first two operators return the incremented value; the last two operators return the value before the increment. The operators use the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator+= +## `atomic::operator+=` Adds a specified value to the stored value. Used only by integral and pointer specializations. @@ -172,18 +172,18 @@ Ty atomic::operator+=( ### Parameters -*Value*\ +*`Value`*\ An integral or pointer value. ### Return Value -A *Ty* object that contains the result of the addition. +A *`Ty`* object that contains the result of the addition. ### Remarks -This operator uses the `memory_order_seq_cst` [memory_order](atomic-enums.md). +This operator uses the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator-- +## `atomic::operator--` Decrements the stored value. Used only by integral and pointer specializations. @@ -196,9 +196,9 @@ Ty atomic::operator--() noexcept; ### Return Value -The first two operators return the decremented value; the last two operators return the value before the decrement. The operators use the `memory_order_seq_cst` [memory_order](atomic-enums.md). +The first two operators return the decremented value; the last two operators return the value before the decrement. The operators use the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator-= +## `atomic::operator-=` Subtracts a specified value from the stored value. Used only by integral and pointer specializations. @@ -213,20 +213,20 @@ Ty atomic::operator-=( ### Parameters -*Value*\ +*`Value`*\ An integral or pointer value. ### Return Value -A *Ty* object that contains the result of the subtraction. +A *`Ty`* object that contains the result of the subtraction. ### Remarks -This operator uses the `memory_order_seq_cst` [memory_order](atomic-enums.md). +This operator uses the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator&= +## `atomic::operator&=` -Performs a bitwise and on a specified value and the stored value of **\*this**. Used only by integral specializations. +Performs a bitwise "and" (`&`) on a specified value and the stored value of **`*this`**. Used only by integral specializations. ```cpp atomic::operator&= ( @@ -239,20 +239,20 @@ atomic::operator&= ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. ### Return Value -The result of the bitwise and. +The result of the bitwise "and" (`&`). ### Remarks -This operator performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise and of *Value* and the current value that is stored in **\*this**, within the constraints of the `memory_order_seq_cst` [memory_order](atomic-enums.md). +This operator performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "and" (`&`) of *`Value`* and the current value that is stored in **`*this`**, within the constraints of the `memory_order_seq_cst` [`memory_order`](atomic-enums.md). -## atomic::operator|= +## `atomic::operator|=` -Performs a bitwise or on a specified value and the stored value of **\*this**. Used only by integral specializations. +Performs a bitwise "or" (`|`) on a specified value and the stored value of **`*this`**. Used only by integral specializations. ```cpp atomic::operator|= ( @@ -265,20 +265,20 @@ atomic::operator|= ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. ### Return Value -The result of the bitwise or. +The result of the bitwise "or" (`|`). ### Remarks -This operator performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise or of *Value* and the current value that is stored in **\*this**, within the constraints of the `memory_order_seq_cst` [memory_order](atomic-enums.md) constraints. +This operator performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "or" (`|`) of *`Value`* and the current value that is stored in **`*this`**, within the constraints of the `memory_order_seq_cst` [`memory_order`](atomic-enums.md) constraints. -## atomic::operator^= +## `atomic::operator^=` -Performs a bitwise exclusive or on a specified value and the stored value of **\*this**. Used only by integral specializations. +Performs a bitwise "exclusive or" (`^`) on a specified value and the stored value of **`*this`**. Used only by integral specializations. ```cpp atomic::operator^= ( @@ -291,20 +291,20 @@ atomic::operator^= ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. ### Return Value -The result of the bitwise exclusive or. +The result of the bitwise "exclusive or" (`^`). ### Remarks -This operator performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise exclusive or of *Value* and the current value that is stored in **\*this**, within the constraints of the `memory_order_seq_cst` [memory_order](atomic-enums.md) constraints. +This operator performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "exclusive or" (`^`) of *`Value`* and the current value that is stored in **`*this`**, within the constraints of the `memory_order_seq_cst` [`memory_order`](atomic-enums.md) constraints. -## atomic::compare_exchange_strong +## `atomic::compare_exchange_strong` -Performs an atomic compare and exchange operation on **\*this**. +Performs an atomic compare and exchange operation on **`*this`**. ```cpp bool compare_exchange_strong( @@ -333,16 +333,16 @@ bool compare_exchange_strong( ### Parameters -*Exp*\ -A value of type *Ty*. +*`Exp`*\ +A value of type *`Ty`*. -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order1*\ +*`Order1`*\ First `memory_order` argument. -*Order2*\ +*`Order2`*\ Second `memory_order` argument. ### Return Value @@ -351,15 +351,15 @@ A **`bool`** that indicates the result of the value comparison. ### Remarks -This atomic compare and exchange operation compares the value that is stored in **\*this** with *Exp*. If the values are equal, the operation replaces the value that is stored in **\*this** with *Value* by using a read-modify-write operation and applying the memory order constraints that are specified by *Order1*. If the values are not equal, the operation uses the value that is stored in **\*this** to replace *Exp* and applies the memory order constraints that are specified by *Order2*. +This atomic compare and exchange operation compares the value that is stored in **`*this`** with *`Exp`*. If the values are equal, the operation replaces the value that is stored in **`*this`** with *`Value`* by using a read-modify-write operation and applying the memory order constraints that are specified by *`Order1`*. If the values aren't equal, the operation uses the value that is stored in **`*this`** to replace *`Exp`* and applies the memory order constraints that are specified by *`Order2`*. -Overloads that do not have a second `memory_order` use an implicit *Order2* that is based on the value of *Order1*. If *Order1* is `memory_order_acq_rel`, *Order2* is `memory_order_acquire`. If *Order1* is `memory_order_release`, *Order2* is `memory_order_relaxed`. In all other cases, *Order2* is equal to *Order1*. +Overloads that don't have a second `memory_order` use an implicit *`Order2`* that is based on the value of *`Order1`*. If *`Order1`* is `memory_order_acq_rel`, *`Order2`* is `memory_order_acquire`. If *`Order1`* is `memory_order_release`, *`Order2`* is `memory_order_relaxed`. In all other cases, *`Order2`* is equal to *`Order1`*. -For overloads that take two `memory_order` parameters, the value of *Order2* must not be `memory_order_release` or `memory_order_acq_rel`, and must not be stronger than the value of *Order1*. +For overloads that take two `memory_order` parameters, the value of *`Order2`* must not be `memory_order_release` or `memory_order_acq_rel`, and must not be stronger than the value of *`Order1`*. -## atomic::compare_exchange_weak +## `atomic::compare_exchange_weak` -Performs a weak atomic compare and exchange operation on **\*this**. +Performs a weak atomic compare and exchange operation on **`*this`**. ```cpp bool compare_exchange_weak( @@ -388,16 +388,16 @@ bool compare_exchange_weak( ### Parameters -*Exp*\ -A value of type *Ty*. +*`Exp`*\ +A value of type *`Ty`*. -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order1*\ +*`Order1`*\ First `memory_order` argument. -*Order2*\ +*`Order2`*\ Second `memory_order` argument. ### Return Value @@ -406,17 +406,17 @@ A **`bool`** that indicates the result of the value comparison. ### Remarks -This atomic compare and exchange operation compares the value that is stored in **\*this** with *Exp*. If the values are equal, the operation replaces the value that is stored in **\*this** with*Value* by using a read-modify-write operation and applying the memory order constraints that are specified by *Order1*. If the values are not equal, the operation uses the value that is stored in **\*this** to replace *Exp* and applies the memory order constraints that are specified by *Order2*. +This atomic compare and exchange operation compares the value that is stored in **`*this`** with *`Exp`*. If the values are equal, the operation replaces the value that is stored in **`*this`** with *`Value`* by using a read-modify-write operation and applying the memory order constraints that are specified by *`Order1`*. If the values aren't equal, the operation uses the value that is stored in **`*this`** to replace *`Exp`* and applies the memory order constraints that are specified by *`Order2`*. -A weak atomic compare and exchange operation performs an exchange if the compared values are equal. If the values are not equal, the operation is not guaranteed to perform an exchange. +A weak atomic compare and exchange operation performs an exchange if the compared values are equal. If the values aren't equal, the operation isn't guaranteed to perform an exchange. -Overloads that do not have a second `memory_order` use an implicit *Order2* that is based on the value of *Order1*. If *Order1* is `memory_order_acq_rel`, *Order2* is `memory_order_acquire`. If *Order1* is `memory_order_release`, *Order2* is `memory_order_relaxed`. In all other cases, *Order2* is equal to *Order1*. +Overloads that don't have a second `memory_order` use an implicit *`Order2`* that is based on the value of *`Order1`*. If *`Order1`* is `memory_order_acq_rel`, *`Order2`* is `memory_order_acquire`. If *`Order1`* is `memory_order_release`, *`Order2`* is `memory_order_relaxed`. In all other cases, *`Order2`* is equal to *`Order1`*. -For overloads that take two `memory_order` parameters, the value of *Order2* must not be `memory_order_release` or `memory_order_acq_rel`, and must not be stronger than the value of *Order1*. +For overloads that take two `memory_order` parameters, the value of *`Order2`* must not be `memory_order_release` or `memory_order_acq_rel`, and must not be stronger than the value of *`Order1`*. -## atomic::exchange +## `atomic::exchange` -Uses a specified value to replace the stored value of **\*this**. +Uses a specified value to replace the stored value of **`*this`**. ```cpp Ty atomic::exchange( @@ -431,23 +431,23 @@ Ty atomic::exchange( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -The stored value of **\*this** before the exchange. +The stored value of **`*this`** before the exchange. ### Remarks -This operation performs a read-modify-write operation to use *Value* to replace the value that is stored in **\*this**, within the memory constraints that are specified by *Order*. +This operation performs a read-modify-write operation to use *`Value`* to replace the value that is stored in **`*this`**, within the memory constraints that are specified by *`Order`*. -## atomic::fetch_add +## `atomic::fetch_add` -Fetches the value stored in **\*this**, and then adds a specified value to the stored value. +Fetches the value stored in **`*this`**, and then adds a specified value to the stored value. ```cpp Ty atomic::fetch_add ( @@ -462,23 +462,23 @@ Ty atomic::fetch_add ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -A *Ty* object that contains the value stored in **\*this** prior to the addition. +A *`Ty`* object that contains the value stored in **`*this`** prior to the addition. ### Remarks -The `fetch_add` method performs a read-modify-write operation to atomically add *Value* to the stored value in **\*this**, and applies the memory constraints that are specified by *Order*. +The `fetch_add` method performs a read-modify-write operation to atomically add *`Value`* to the stored value in **`*this`**, and applies the memory constraints that are specified by *`Order`*. -## atomic::fetch_and +## `atomic::fetch_and` -Performs a bitwise and on a value and an existing value that is stored in **\*this**. +Performs a bitwise "and" (`&`) on a value and an existing value that is stored in **`*this`**. ```cpp Ty atomic::fetch_and ( @@ -493,23 +493,23 @@ Ty atomic::fetch_and ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -A *Ty* object that contains the result of the bitwise and. +A *`Ty`* object that contains the result of the bitwise "and" (`&`). ### Remarks -The `fetch_and` method performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise and of *Value* and the current value that is stored in **\*this**, within the memory constraints that are specified by *Order*. +The `fetch_and` method performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "and" (`&`) of *`Value`* and the current value that is stored in **`*this`**, within the memory constraints that are specified by *`Order`*. -## atomic::fetch_or +## `atomic::fetch_or` -Performs a bitwise or on a value and an existing value that is stored in **\*this**. +Performs a bitwise "or" (`|`) on a value and an existing value that is stored in **`*this`**. ```cpp Ty atomic::fetch_or ( @@ -524,21 +524,21 @@ Ty atomic::fetch_or ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -A *Ty* object that contains the result of the bitwise or. +A *`Ty`* object that contains the result of the bitwise "or" (`|`). ### Remarks -The `fetch_or` method performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise or of *Value* and the current value that is stored in **\*this**, within the memory constraints that are specified by *Order*. +The `fetch_or` method performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "or" (`|`) of *`Value`* and the current value that is stored in **`*this`**, within the memory constraints that are specified by *`Order`*. -## atomic::fetch_sub +## `atomic::fetch_sub` Subtracts a specified value from the stored value. @@ -555,23 +555,23 @@ Ty atomic::fetch_sub ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -A *Ty* object that contains the result of the subtraction. +A *`Ty`* object that contains the result of the subtraction. ### Remarks -The `fetch_sub` method performs a read-modify-write operation to atomically subtract *Value* from the stored value in **\*this**, within the memory constraints that are specified by *Order*. +The `fetch_sub` method performs a read-modify-write operation to atomically subtract *`Value`* from the stored value in **`*this`**, within the memory constraints that are specified by *`Order`*. -## atomic::fetch_xor +## `atomic::fetch_xor` -Performs a bitwise exclusive or on a value and an existing value that is stored in **\*this**. +Performs a bitwise "exclusive or" (`^`) on a value and an existing value that is stored in **`*this`**. ```cpp Ty atomic::fetch_xor ( @@ -586,23 +586,23 @@ Ty atomic::fetch_xor ( ### Parameters -*Value*\ -A value of type *Ty*. +*`Value`*\ +A value of type *`Ty`*. -*Order*\ +*`Order`*\ A `memory_order`. ### Return Value -A *Ty* object that contains the result of the bitwise exclusive or. +A *`Ty`* object that contains the result of the bitwise "exclusive or" (`^`). ### Remarks -The `fetch_xor` method performs a read-modify-write operation to replace the stored value of **\*this** with a bitwise exclusive or of *Value* and the current value that is stored in **\*this**, and applies the memory constraints that are specified by *Order*. +The `fetch_xor` method performs a read-modify-write operation to replace the stored value of **`*this`** with a bitwise "exclusive or" (`^`) of *`Value`* and the current value that is stored in **`*this`**, and applies the memory constraints that are specified by *`Order`*. -## atomic::is_lock_free +## `atomic::is_lock_free` -Specifies whether atomic operations on **\*this** are lock free. +Specifies whether `atomic` operations on **`*this`** are lock free. ```cpp bool is_lock_free() const volatile noexcept; @@ -610,15 +610,15 @@ bool is_lock_free() const volatile noexcept; ### Return Value -true if atomic operations on **\*this** are lock free; otherwise, false. +`true` if `atomic` operations on **`*this`** are lock free; otherwise, `false`. ### Remarks -An atomic type is lock free if no atomic operations on that type use locks. +An `atomic` type is lock free if no `atomic` operations on that type use locks. -## atomic::load +## `atomic::load` -Retrieves the stored value in **\*this**, within the specified memory constraints. +Retrieves the stored value in **`*this`**, within the specified memory constraints. ```cpp Ty atomic::load( @@ -631,14 +631,14 @@ Ty atomic::load( ### Parameters -*Order*\ -A `memory_order`. *Order* must not be `memory_order_release` or `memory_order_acq_rel`. +*`Order`*\ +A `memory_order`. *`Order`* must not be `memory_order_release` or `memory_order_acq_rel`. ### Return Value -The retrieved value that is stored in **\*this**. +The retrieved value that is stored in **`*this`**. -## atomic::store +## `atomic::store` Stores a specified value. @@ -655,17 +655,17 @@ void atomic::store( ### Parameters -*Value*\ -A *Ty* object. +*`Value`*\ +A *`Ty`* object. -*Order*\ +*`Order`*\ A `memory_order` constraint. ### Remarks -This member function atomically stores *Value* in **`*this`**, within the memory constraints that are specified by *Order*. +This member function atomically stores *`Value`* in **`*this`**, within the memory constraints that are specified by *`Order`*. ## See also -[\](../standard-library/atomic.md)\ +[``](../standard-library/atomic.md)\ [Header Files Reference](../standard-library/cpp-standard-library-header-files.md) diff --git a/docs/standard-library/atomic.md b/docs/standard-library/atomic.md index 36a61701d3..e070924144 100644 --- a/docs/standard-library/atomic.md +++ b/docs/standard-library/atomic.md @@ -3,7 +3,6 @@ title: "" description: "Describes the types and functions available in the atomic header of the Standard C++ library." ms.date: "12/06/2019" f1_keywords: ["", "atomic/std::atomic_int_least32_t", "atomic/std::atomic_ullong", "atomic/std::atomic_ptrdiff_t", "atomic/std::atomic_char16_t", "atomic/std::atomic_schar", "atomic/std::atomic_ulong", "atomic/std::atomic_uint_fast32_t", "atomic/std::atomic_uint8_t", "atomic/std::atomic_int32_t", "atomic/std::atomic_uint_fast64_t", "atomic/std::atomic_uint32_t", "atomic/std::atomic_int16_t", "atomic/std::atomic_uintmax_t", "atomic/std::atomic_intmax_t", "atomic/std::atomic_long", "atomic/std::atomic_int", "atomic/std::atomic_uint_least8_t", "atomic/std::atomic_size_t", "atomic/std::atomic_uint_fast16_t", "atomic/std::atomic_wchar_t", "atomic/std::atomic_int_fast64_t", "atomic/std::atomic_uint_fast8_t", "atomic/std::atomic_int_fast8_t", "atomic/std::atomic_intptr_t", "atomic/std::atomic_uint", "atomic/std::atomic_uint16_t", "atomic/std::atomic_char32_t", "atomic/std::atomic_uint64_t", "atomic/std::atomic_ushort", "atomic/std::atomic_int_least16_t", "atomic/std::atomic_char", "atomic/std::atomic_uint_least32_t", "atomic/std::atomic_uintptr_t", "atomic/std::atomic_short", "atomic/std::atomic_llong", "atomic/std::atomic_uint_least16_t", "atomic/std::atomic_int_fast16_t", "atomic/std::atomic_int_least8_t", "atomic/std::atomic_int_least64_t", "atomic/std::atomic_int_fast32_t", "atomic/std::atomic_uchar", "atomic/std::atomic_int8_t", "atomic/std::atomic_int64_t", "atomic/std::atomic_uint_least64_t"] -ms.assetid: e79a6b9f-52ff-48da-9554-654c4e1999f6 --- # `` @@ -18,21 +17,21 @@ Defines classes and class templates to use to create types that support atomic o ## Remarks > [!NOTE] -> In code that's compiled by using [/clr:pure](../build/reference/clr-common-language-runtime-compilation.md), this header is blocked. Both **/clr:pure** and **/clr:safe** are deprecated in Visual Studio 2017 and later versions. +> In code that's compiled by using [`/clr:pure`](../build/reference/clr-common-language-runtime-compilation.md), this header is blocked. Both **`/clr:pure`** and **`/clr:safe`** are deprecated in Visual Studio 2017 and later versions. -An atomic operation has two key properties that help you use multiple threads to correctly manipulate an object without using mutex locks. +An atomic operation has two key properties that help you use multiple threads to correctly manipulate an object without using `mutex` locks. - Because an atomic operation is indivisible, a second atomic operation on the same object from a different thread can obtain the object's state only before or after the first atomic operation. -- Based on its [memory_order](../standard-library/atomic-enums.md#memory_order_enum) argument, an atomic operation establishes ordering requirements for the visibility of the effects of other atomic operations in the same thread. Consequently, it inhibits compiler optimizations that violate the ordering requirements. +- Based on its [`memory_order`](../standard-library/atomic-enums.md#memory_order_enum) argument, an atomic operation establishes ordering requirements for the visibility of the effects of other atomic operations in the same thread. Consequently, it inhibits compiler optimizations that violate the ordering requirements. -On some platforms, it might not be possible to efficiently implement atomic operations for some types without using `mutex` locks. An atomic type is *lock-free* if no atomic operations on that type use locks. +On some platforms, it might not be possible to efficiently implement atomic operations for some types without using `mutex` locks. An atomic type is *`lock-free`* if no atomic operations on that type use locks. -**C++11**: In signal-handlers, you can perform atomic operations on an object `obj` if `obj.is_lock_free()` or `atomic_is_lock_free(x)` are true. +**`C++11`**: In signal-handlers, you can perform atomic operations on an object `obj` if `obj.is_lock_free()` or `atomic_is_lock_free(x)` are `true`. -The class [atomic_flag](../standard-library/atomic-flag-structure.md) provides a minimal atomic type that holds a **`bool`** flag. Its operations are always lock-free. +The class [`atomic_flag`](../standard-library/atomic-flag-structure.md) provides a minimal atomic type that holds a **`bool`** flag. Its operations are always lock-free. -The class template `atomic` stores an object of its argument type `T` and provides atomic access to that stored value. You can instantiate it by using any type that can be copied by using [memcpy](../c-runtime-library/reference/memcpy-wmemcpy.md) and tested for equality by using [memcmp](../c-runtime-library/reference/memcmp-wmemcmp.md). In particular, you can use it with user-defined types that meet these requirements and, in many cases, with floating-point types. +The class template `atomic` stores an object of its argument type `T` and provides atomic access to that stored value. You can instantiate it by using any type that can be copied by using [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) and tested for equality by using [`memcmp`](../c-runtime-library/reference/memcmp-wmemcmp.md). In particular, you can use it with user-defined types that meet these requirements and, in many cases, with floating-point types. The template also has a set of specializations for integral types and a partial specialization for pointers. These specializations provide additional operations that aren't available through the primary template. @@ -50,24 +49,24 @@ For each of the integral types, there's a corresponding named atomic type that m |`atomic_integral` Type|Integral Type|`atomic_is_lock_free` Macro| |----------------------------|-------------------|---------------------------------| -|`atomic_char`|**`char`**|ATOMIC_CHAR_LOCK_FREE| -|`atomic_schar`|**`signed char`**|ATOMIC_CHAR_LOCK_FREE| -|`atomic_uchar`|**`unsigned char`**|ATOMIC_CHAR_LOCK_FREE| -|`atomic_char16_t`|**`char16_t`**|ATOMIC_CHAR16_T_LOCK_FREE| -|`atomic_char32_t`|**`char32_t`**|ATOMIC_CHAR32_T_LOCK_FREE| -|`atomic_wchar_t`|**`wchar_t`**|ATOMIC_WCHAR_T_LOCK_FREE| -|`atomic_short`|**`short`**|ATOMIC_SHORT_LOCK_FREE| -|`atomic_ushort`|**`unsigned short`**|ATOMIC_SHORT_LOCK_FREE| -|`atomic_int`|**`int`**|ATOMIC_INT_LOCK_FREE| -|`atomic_uint`|**`unsigned int`**|ATOMIC_INT_LOCK_FREE| -|`atomic_long`|**`long`**|ATOMIC_LONG_LOCK_FREE| -|`atomic_ulong`|**`unsigned long`**|ATOMIC_LONG_LOCK_FREE| -|`atomic_llong`|**`long long`**|ATOMIC_LLONG_LOCK_FREE| -|`atomic_ullong`|**`unsigned long long`**|ATOMIC_LLONG_LOCK_FREE| - -Typedef names exist for specializations of the atomic template for some of the types that are defined in the header \. - -|Atomic Type|Typedef Name| +|`atomic_char`|**`char`**|`ATOMIC_CHAR_LOCK_FREE`| +|`atomic_schar`|**`signed char`**|`ATOMIC_CHAR_LOCK_FREE`| +|`atomic_uchar`|**`unsigned char`**|`ATOMIC_CHAR_LOCK_FREE`| +|`atomic_char16_t`|**`char16_t`**|`ATOMIC_CHAR16_T_LOCK_FREE`| +|`atomic_char32_t`|**`char32_t`**|`ATOMIC_CHAR32_T_LOCK_FREE`| +|`atomic_wchar_t`|**`wchar_t`**|`ATOMIC_WCHAR_T_LOCK_FREE`| +|`atomic_short`|**`short`**|`ATOMIC_SHORT_LOCK_FREE`| +|`atomic_ushort`|**`unsigned short`**|`ATOMIC_SHORT_LOCK_FREE`| +|`atomic_int`|**`int`**|`ATOMIC_INT_LOCK_FREE`| +|`atomic_uint`|**`unsigned int`**|`ATOMIC_INT_LOCK_FREE`| +|`atomic_long`|**`long`**|`ATOMIC_LONG_LOCK_FREE`| +|`atomic_ulong`|**`unsigned long`**|`ATOMIC_LONG_LOCK_FREE`| +|`atomic_llong`|**`long long`**|`ATOMIC_LLONG_LOCK_FREE`| +|`atomic_ullong`|**`unsigned long long`**|`ATOMIC_LLONG_LOCK_FREE`| + +`Typedef` names exist for specializations of the atomic template for some of the types that are defined in the header ``. + +|Atomic Type|`Typedef` Name| |-----------------|------------------| |`atomic_int8_t`|`atomic`| |`atomic_uint8_t`|`atomic`| @@ -104,50 +103,50 @@ Typedef names exist for specializations of the atomic template for some of the t |Name|Description| |----------|-----------------| -|[atomic Structure](../standard-library/atomic-structure.md)|Describes an object that performs atomic operations on a stored value.| -|[atomic_flag Structure](../standard-library/atomic-flag-structure.md)|Describes an object that atomically sets and clears a **`bool`** flag.| +|[`atomic` Structure](../standard-library/atomic-structure.md)|Describes an object that performs `atomic` operations on a stored value.| +|[`atomic_flag` Structure](../standard-library/atomic-flag-structure.md)|Describes an object that atomically sets and clears a **`bool`** flag.| ## Enums |Name|Description| |----------|-----------------| -|[memory_order Enum](../standard-library/atomic-enums.md#memory_order_enum)|Supplies symbolic names for synchronization operations on memory locations. These operations affect how assignments in one thread become visible in another.| +|[`memory_order` Enum](../standard-library/atomic-enums.md#memory_order_enum)|Supplies symbolic names for synchronization operations on memory locations. These operations affect how assignments in one thread become visible in another.| ## Functions -In the following list, the functions that don't end in `_explicit` have the semantics of the corresponding `_explicit`, except that they have the implicit [memory_order](../standard-library/atomic-enums.md#memory_order_enum) arguments of `memory_order_seq_cst`. +In the following list, the functions that don't end in `_explicit` have the semantics of the corresponding `_explicit`, except that they have the implicit [`memory_order`](../standard-library/atomic-enums.md#memory_order_enum) arguments of `memory_order_seq_cst`. |Name|Description| |----------|-----------------| -|[atomic_compare_exchange_strong](../standard-library/atomic-functions.md#atomic_compare_exchange_strong)|Performs an *atomic compare and exchange* operation.| -|[atomic_compare_exchange_strong_explicit](../standard-library/atomic-functions.md#atomic_compare_exchange_strong_explicit)|Performs an *atomic compare and exchange* operation.| -|[atomic_compare_exchange_weak](../standard-library/atomic-functions.md#atomic_compare_exchange_weak)|Performs a *weak atomic compare and exchange* operation.| -|[atomic_compare_exchange_weak_explicit](../standard-library/atomic-functions.md#atomic_compare_exchange_weak_explicit)|Performs a *weak atomic compare and exchange* operation.| -|[atomic_exchange](../standard-library/atomic-functions.md#atomic_exchange)|Replaces a stored value.| -|[atomic_exchange_explicit](../standard-library/atomic-functions.md#atomic_exchange_explicit)|Replaces a stored value.| -|[atomic_fetch_add](../standard-library/atomic-functions.md#atomic_fetch_add)|Adds a specified value to an existing stored value.| -|[atomic_fetch_add_explicit](../standard-library/atomic-functions.md#atomic_fetch_add_explicit)|Adds a specified value to an existing stored value.| -|[atomic_fetch_and](../standard-library/atomic-functions.md#atomic_fetch_and)|Performs a bitwise `and` on a specified value and an existing stored value.| -|[atomic_fetch_and_explicit](../standard-library/atomic-functions.md#atomic_fetch_and_explicit)|Performs a bitwise `and` on a specified value and an existing stored value.| -|[atomic_fetch_or](../standard-library/atomic-functions.md#atomic_fetch_or)|Performs a bitwise `or` on a specified value and an existing stored value.| -|[atomic_fetch_or_explicit](../standard-library/atomic-functions.md#atomic_fetch_or_explicit)|Performs a bitwise `or` on a specified value and an existing stored value.| -|[atomic_fetch_sub](../standard-library/atomic-functions.md#atomic_fetch_sub)|Subtracts a specified value from an existing stored value.| -|[atomic_fetch_sub_explicit](../standard-library/atomic-functions.md#atomic_fetch_sub_explicit)|Subtracts a specified value from an existing stored value.| -|[atomic_fetch_xor](../standard-library/atomic-functions.md#atomic_fetch_xor)|Performs a bitwise `exclusive or` on a specified value and an existing stored value.| -|[atomic_fetch_xor_explicit](../standard-library/atomic-functions.md#atomic_fetch_xor_explicit)|Performs a bitwise `exclusive or` on a specified value and an existing stored value.| -|[atomic_flag_clear](../standard-library/atomic-functions.md#atomic_flag_clear)|Sets the flag in an `atomic_flag` object to **`false`**.| -|[atomic_flag_clear_explicit](../standard-library/atomic-functions.md#atomic_flag_clear_explicit)|Sets the flag in an `atomic_flag` object to **`false`**.| -|[atomic_flag_test_and_set](../standard-library/atomic-functions.md#atomic_flag_test_and_set)|Sets the flag in an `atomic_flag` object to **`true`**.| -|[atomic_flag_test_and_set_explicit](../standard-library/atomic-functions.md#atomic_flag_test_and_set_explicit)|Sets the flag in an `atomic_flag` object to **`true`**.| -|[atomic_init](../standard-library/atomic-functions.md#atomic_init)|Sets the stored value in an `atomic` object.| -|[atomic_is_lock_free](../standard-library/atomic-functions.md#atomic_is_lock_free)|Specifies whether atomic operations on a specified object are lock-free.| -|[atomic_load](../standard-library/atomic-functions.md#atomic_load)|Atomically retrieves a value.| -|[atomic_load_explicit](../standard-library/atomic-functions.md#atomic_load_explicit)|Atomically retrieves a value.| -|[atomic_signal_fence](../standard-library/atomic-functions.md#atomic_signal_fence)|Acts as a *fence* that establishes memory ordering requirements between fences in a calling thread that has signal handlers executed in the same thread.| -|[atomic_store](../standard-library/atomic-functions.md#atomic_store)|Atomically stores a value.| -|[atomic_store_explicit](../standard-library/atomic-functions.md#atomic_store_explicit)|Atomically stores a value.| -|[atomic_thread_fence](../standard-library/atomic-functions.md#atomic_thread_fence)|Acts as a *fence* that establishes memory ordering requirements with respect to other fences.| -|[kill_dependency](../standard-library/atomic-functions.md#kill_dependency)|Breaks a possible dependency chain.| +|[`atomic_compare_exchange_strong`](../standard-library/atomic-functions.md#atomic_compare_exchange_strong)|Performs an *`atomic compare and exchange`* operation.| +|[`atomic_compare_exchange_strong_explicit`](../standard-library/atomic-functions.md#atomic_compare_exchange_strong_explicit)|Performs an *`atomic compare and exchange`* operation.| +|[`atomic_compare_exchange_weak`](../standard-library/atomic-functions.md#atomic_compare_exchange_weak)|Performs a *`weak atomic compare and exchange`* operation.| +|[`atomic_compare_exchange_weak_explicit`](../standard-library/atomic-functions.md#atomic_compare_exchange_weak_explicit)|Performs a *`weak atomic compare and exchange`* operation.| +|[`atomic_exchange`](../standard-library/atomic-functions.md#atomic_exchange)|Replaces a stored value.| +|[`atomic_exchange_explicit`](../standard-library/atomic-functions.md#atomic_exchange_explicit)|Replaces a stored value.| +|[`atomic_fetch_add`](../standard-library/atomic-functions.md#atomic_fetch_add)|Adds a specified value to an existing stored value.| +|[`atomic_fetch_add_explicit`](../standard-library/atomic-functions.md#atomic_fetch_add_explicit)|Adds a specified value to an existing stored value.| +|[`atomic_fetch_and`](../standard-library/atomic-functions.md#atomic_fetch_and)|Performs a bitwise "and" (`&`) on a specified value and an existing stored value.| +|[`atomic_fetch_and_explicit`](../standard-library/atomic-functions.md#atomic_fetch_and_explicit)|Performs a bitwise "and" (`&`) on a specified value and an existing stored value.| +|[`atomic_fetch_or`](../standard-library/atomic-functions.md#atomic_fetch_or)|Performs a bitwise "or" (`|`) on a specified value and an existing stored value.| +|[`atomic_fetch_or_explicit`](../standard-library/atomic-functions.md#atomic_fetch_or_explicit)|Performs a bitwise "or" (`|`) on a specified value and an existing stored value.| +|[`atomic_fetch_sub`](../standard-library/atomic-functions.md#atomic_fetch_sub)|Subtracts a specified value from an existing stored value.| +|[`atomic_fetch_sub_explicit`](../standard-library/atomic-functions.md#atomic_fetch_sub_explicit)|Subtracts a specified value from an existing stored value.| +|[`atomic_fetch_xor`](../standard-library/atomic-functions.md#atomic_fetch_xor)|Performs a bitwise "exclusive or" (`^`) on a specified value and an existing stored value.| +|[`atomic_fetch_xor_explicit`](../standard-library/atomic-functions.md#atomic_fetch_xor_explicit)|Performs a bitwise "exclusive or" (`^`) on a specified value and an existing stored value.| +|[`atomic_flag_clear`](../standard-library/atomic-functions.md#atomic_flag_clear)|Sets the flag in an `atomic_flag` object to **`false`**.| +|[`atomic_flag_clear_explicit`](../standard-library/atomic-functions.md#atomic_flag_clear_explicit)|Sets the flag in an `atomic_flag` object to **`false`**.| +|[`atomic_flag_test_and_set`](../standard-library/atomic-functions.md#atomic_flag_test_and_set)|Sets the flag in an `atomic_flag` object to **`true`**.| +|[`atomic_flag_test_and_set_explicit`](../standard-library/atomic-functions.md#atomic_flag_test_and_set_explicit)|Sets the flag in an `atomic_flag` object to **`true`**.| +|[`atomic_init`](../standard-library/atomic-functions.md#atomic_init)|Sets the stored value in an `atomic` object.| +|[`atomic_is_lock_free`](../standard-library/atomic-functions.md#atomic_is_lock_free)|Specifies whether atomic operations on a specified object are lock-free.| +|[`atomic_load`](../standard-library/atomic-functions.md#atomic_load)|Atomically retrieves a value.| +|[`atomic_load_explicit`](../standard-library/atomic-functions.md#atomic_load_explicit)|Atomically retrieves a value.| +|[`atomic_signal_fence`](../standard-library/atomic-functions.md#atomic_signal_fence)|Acts as a *`fence`* that establishes memory ordering requirements between fences in a calling thread that has signal handlers executed in the same thread.| +|[`atomic_store`](../standard-library/atomic-functions.md#atomic_store)|Atomically stores a value.| +|[`atomic_store_explicit`](../standard-library/atomic-functions.md#atomic_store_explicit)|Atomically stores a value.| +|[`atomic_thread_fence`](../standard-library/atomic-functions.md#atomic_thread_fence)|Acts as a *`fence`* that establishes memory ordering requirements with respect to other fences.| +|[`kill_dependency`](../standard-library/atomic-functions.md#kill_dependency)|Breaks a possible dependency chain.| ## See also diff --git a/docs/standard-library/auto-ptr-class.md b/docs/standard-library/auto-ptr-class.md index c8ffc2ed11..69bdeb67bf 100644 --- a/docs/standard-library/auto-ptr-class.md +++ b/docs/standard-library/auto-ptr-class.md @@ -1,16 +1,16 @@ --- -description: "Learn more about: auto_ptr Class" title: "auto_ptr Class" -ms.date: "11/04/2016" +description: "Learn more about: auto_ptr Class" +ms.date: 11/1/2023 f1_keywords: ["memory/std::auto_ptr", "memory/std::auto_ptr::element_type", "memory/std::auto_ptr::get", "memory/std::auto_ptr::release", "memory/std::auto_ptr::reset"] helpviewer_keywords: ["std::auto_ptr [C++]", "std::auto_ptr [C++], element_type", "std::auto_ptr [C++], get", "std::auto_ptr [C++], release", "std::auto_ptr [C++], reset"] -ms.assetid: 7f9108b6-9eb3-4634-b615-cf7aa814f23b +ms.custom: devdivchpfy22 --- -# auto_ptr Class +# auto_ptr class Wraps a smart pointer around a resource that ensures the resource is destroyed automatically when control leaves a block. -The more capable `unique_ptr` class supersedes `auto_ptr`. For more information, see [unique_ptr Class](../standard-library/unique-ptr-class.md). +Starting in C++11, use `unique_ptr` instead of `auto_ptr`. For more information, see [`unique_ptr` class](../standard-library/unique-ptr-class.md). `auto_ptr` was deprecated in C++11 and removed in C++17. For more information about `throw()` and exception handling, see [Exception Specifications (throw)](../cpp/exception-specifications-throw-cpp.md). @@ -40,17 +40,17 @@ class auto_ptr { ### Parameters -*right*\ +*`right`*\ The `auto_ptr` from which to get an existing resource. -*ptr*\ +*`ptr`*\ The pointer specified to replace the stored pointer. ## Remarks -The class template describes a smart pointer, called an `auto_ptr`, to an allocated object. The pointer must be either null or designate an object allocated by **`new`**. The `auto_ptr` transfers ownership if its stored value is assigned to another object. (It replaces the stored value after a transfer with a null pointer.) The destructor for `auto_ptr` deletes the allocated object. The `auto_ptr` ensures that an allocated object is automatically deleted when control leaves a block, even through a thrown exception. You should not construct two `auto_ptr` objects that own the same object. +The class template describes a smart pointer, called an `auto_ptr`, to an allocated object. The pointer must be either null or designate an object allocated by **`new`**. The `auto_ptr` transfers ownership if its stored value is assigned to another object. (It replaces the stored value after a transfer with a null pointer.) The destructor for `auto_ptr` deletes the allocated object. The `auto_ptr` ensures that an allocated object is automatically deleted when control leaves a block, even through a thrown exception. You shouldn't construct two `auto_ptr` objects that own the same object. -You can pass an `auto_ptr` object by value as an argument to a function call. An `auto_ptr` cannot be an element of any Standard Library container. You cannot reliably manage a sequence of `auto_ptr` objects with a C++ Standard Library container. +You can pass an `auto_ptr` object by value as an argument to a function call. An `auto_ptr` can't be an element of any Standard Library container. You can't reliably manage a sequence of `auto_ptr` objects with a C++ Standard Library container. ## Members @@ -58,31 +58,31 @@ You can pass an `auto_ptr` object by value as an argument to a function ca |Name|Description| |-|-| -|[auto_ptr](#auto_ptr)|The constructor for objects of type `auto_ptr`.| +|[`auto_ptr`](#auto_ptr)|The constructor for objects of type `auto_ptr`.| ### Typedefs |Name|Description| |-|-| -|[element_type](#element_type)|The type is a synonym for the template parameter `Type`.| +|[`element_type`](#element_type)|The type is a synonym for the template parameter `Type`.| ### Functions |Name|Description| |-|-| -|[get](#get)|The member function returns the stored pointer `myptr`.| -|[release](#release)|The member replaces the stored pointer `myptr` with a null pointer and returns the previously stored pointer.| -|[reset](#reset)|The member function evaluates the expression `delete myptr`, but only if the stored pointer value `myptr` changes as a result of function call. It then replaces the stored pointer with *ptr*.| +|[`get`](#get)|The member function returns the stored pointer `myptr`.| +|[`release`](#release)|The member replaces the stored pointer `myptr` with a null pointer and returns the previously stored pointer.| +|[`reset`](#reset)|The member function evaluates the expression `delete myptr`, but only if the stored pointer value `myptr` changes as a result of function call. It then replaces the stored pointer with *`ptr`*.| ### Operators |Name|Description| |-|-| -|[operator=](#op_eq)|An assignment operator that transfers ownership from one `auto_ptr` object to another.| -|[operator*](#op_star)|The dereferencing operator for objects of type `auto_ptr`.| -|[operator->](#op_arrow)|The operator for allowing member access.| -|[operator auto_ptr\](#op_auto_ptr_lt_other_gt)|Casts from one kind of `auto_ptr` to another kind of `auto_ptr`.| -|[operator auto_ptr_ref\](#op_auto_ptr_ref_lt_other_gt)|Casts from an `auto_ptr` to an `auto_ptr_ref`.| +|[`operator=`](#op_eq)|An assignment operator that transfers ownership from one `auto_ptr` object to another.| +|[`operator*`](#op_star)|The dereferencing operator for objects of type `auto_ptr`.| +|[`operator->`](#op_arrow)|The operator for allowing member access.| +|[`operator auto_ptr`](#op_auto_ptr_lt_other_gt)|Casts from one kind of `auto_ptr` to another kind of `auto_ptr`.| +|[`operator auto_ptr_ref`](#op_auto_ptr_ref_lt_other_gt)|Casts from an `auto_ptr` to an `auto_ptr_ref`.| ### auto_ptr @@ -101,19 +101,19 @@ auto _ptr(auto _ptr& right) throw(); #### Parameters -*ptr*\ +*`ptr`*\ The pointer to the object that `auto_ptr` encapsulates. -*right*\ +*`right`*\ The `auto_ptr` object to be copied by the constructor. #### Remarks -The first constructor stores *ptr* in `myptr`, the stored pointer to the allocated object. The second constructor transfers ownership of the pointer stored in *right*, by storing *right*. [release](#release) in `myptr`. +The first constructor stores *`ptr`* in `myptr`, the stored pointer to the allocated object. The second constructor transfers ownership of the pointer stored in *`right`*, by storing *`right`*. [release](#release) in `myptr`. The third constructor behaves the same as the second, except that it stores `right`. `ref`. `release` in `myptr`, where `ref` is the reference stored in `right`. -The template constructor behaves the same as the second constructor, provided that a pointer to `Other` can be implicitly converted to a pointer to `Type`. +The template constructor behaves the same as the second constructor, if a pointer to `Other` can be implicitly converted to a pointer to `Type`. #### Example @@ -134,17 +134,17 @@ public: cout << "Constructing " << ( void* )this << endl; x = i; bIsConstructed = true; - }; + } ~Int( ) { cout << "Destructing " << ( void* )this << endl; bIsConstructed = false; - }; + } Int &operator++( ) { x++; return *this; - }; + } int x; private: bool bIsConstructed; @@ -211,11 +211,11 @@ public: { x = i; cout << "Constructing " << ( void* )this << " Value: " << x << endl; - }; + } ~Int( ) { cout << "Destructing " << ( void* )this << " Value: " << x << endl; - }; + } int x; @@ -241,7 +241,7 @@ pi2 == pi3 Destructing 00311B88 Value: 6 ``` -### operator= +### `operator=` An assignment operator that transfers ownership from one `auto_ptr` object to another. @@ -254,7 +254,7 @@ auto_ptr& operator=(auto_ptr_ref right) throw(); #### Parameters -*right*\ +*`right`*\ An object of type `auto_ptr`. #### Return Value @@ -263,13 +263,13 @@ A reference to an object of type `auto_ptr`. #### Remarks -The assignment evaluates the expression `delete myptr`, but only if the stored pointer `myptr` changes as a result of the assignment. It then transfers ownership of the pointer stored in *right*, by storing *right*.[release](#release) in `myptr`. The function returns __\*this__. +The assignment evaluates the expression `delete myptr`, but only if the stored pointer `myptr` changes as a result of the assignment. It then transfers ownership of the pointer stored in *right*, by storing *right*.[`release`](#release) in `myptr`. The function returns `*this`. #### Example -For an example of the use of the member operator, see [auto_ptr](#auto_ptr). +For an example of the use of the member operator, see [`auto_ptr`](#auto_ptr). -### operator* +### `operator*` The dereferencing operator for objects of type `auto_ptr`. @@ -283,11 +283,11 @@ A reference to an object of type `Type` that the pointer owns. #### Remarks -The indirection operator returns `*`[get](#get). Hence, the stored pointer must not be null. +The indirection operator returns `*`[`get`](#get). Hence, the stored pointer must not be null. #### Example -For an example of how to use the member function, see [auto_ptr](#auto_ptr). +For an example of how to use the member function, see [`auto_ptr`](#auto_ptr). ### `operator->` @@ -303,11 +303,11 @@ A member of the object that `auto_ptr` owns. #### Remarks -The selection operator returns [get](#get)`( )`, so that the expression *ap*-> **member** behaves the same as ( *ap*. **get**( ) )-> **member**, where *ap* is an object of class `auto_ptr`\< **Type**>. Hence, the stored pointer must not be null, and `Type` must be a class, struct, or union type with a `member` member. +The selection operator returns [`get`](#get)`( )`, so that the expression *`ap`*-> **`member`** behaves the same as ( *`ap`*. **`get`**() )-> **`member`**, where *`ap`* is an object of class `auto_ptr<`**`Type`**>. Hence, the stored pointer must not be null, and `Type` must be a class, struct, or union type with a `member` member. #### Example -For an example of how to use the member function, see [auto_ptr](#auto_ptr). +For an example of how to use the member function, see [`auto_ptr`](#auto_ptr). ### `operator auto_ptr` @@ -320,7 +320,7 @@ operator auto _ptr() throw(); #### Return Value -The type cast operator returns `auto_ptr` \< **Other**>( **\*this**). +The type cast operator returns `auto_ptr<`**Other**`>(*this)`. #### Example @@ -350,7 +350,7 @@ operator auto _ptr _ref() throw(); #### Return Value -The type cast operator returns **auto_ptr_ref**\< **Other**>( **\*this**). +The type cast operator returns **auto_ptr_ref**`<`**`Other`**`>(*this)`. #### Example @@ -377,7 +377,7 @@ public: int m_i; }; void f(auto_ptr arg) { -}; +} int main() { const auto_ptr ciap(new C(1)); @@ -400,7 +400,7 @@ main exiting ~C: 1 ``` -### release +### `release` The member replaces the stored pointer `myptr` with a null pointer and returns the previously stored pointer. @@ -433,10 +433,10 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; @@ -462,7 +462,7 @@ pi2 == pi3 Destructing 00311B88 Value: 6 ``` -### reset +### `reset` The member function evaluates the expression `delete myptr`, but only if the stored pointer value `myptr` changes as a result of a function call. It then replaces the stored pointer with `ptr`. @@ -472,7 +472,7 @@ void reset(Type* ptr = 0); #### Parameters -*ptr*\ +*`ptr`*\ The pointer specified to replace the stored pointer `myptr`. #### Example @@ -493,11 +493,11 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; }; @@ -524,4 +524,4 @@ Destructing 00311B88 Value: 6 ## See also -[unique_ptr Class](../standard-library/unique-ptr-class.md) +[`unique_ptr Class`](../standard-library/unique-ptr-class.md) diff --git a/docs/standard-library/back-insert-iterator-class.md b/docs/standard-library/back-insert-iterator-class.md index be9dc5074b..41038cc72e 100644 --- a/docs/standard-library/back-insert-iterator-class.md +++ b/docs/standard-library/back-insert-iterator-class.md @@ -1,10 +1,11 @@ --- description: "Learn more about: back_insert_iterator Class" title: "back_insert_iterator Class" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["iterator/std::back_insert_iterator", "iterator/std::back_insert_iterator::container_type", "iterator/std::back_insert_iterator::reference"] helpviewer_keywords: ["std::back_insert_iterator [C++]", "std::back_insert_iterator [C++], container_type", "std::back_insert_iterator [C++], reference"] ms.assetid: a1ee07f2-cf9f-46a1-8608-cfaf207f9713 +ms.custom: devdivchpfy22 --- # back_insert_iterator Class @@ -24,7 +25,7 @@ The type of container into the back of which elements are to be inserted by a `b ## Remarks -The container must satisfy the requirements for a back insertion sequence where is it possible to insert elements at the end of the sequence in amortized constant time. C++ Standard Library sequence containers defined by the [deque Class](../standard-library/deque-class.md), [list Class](../standard-library/list-class.md) and [vector Class](../standard-library/vector-class.md) provide the needed `push_back` member function and satisfy these requirements. These three containers as well as strings may each be adapted to use with `back_insert_iterator`s. A `back_insert_iterator` must always be initialized with its container. +The container must satisfy the requirements for a back insertion sequence where is it possible to insert elements at the end of the sequence in amortized constant time. C++ Standard Library sequence containers defined by the [deque Class](../standard-library/deque-class.md), [list Class](../standard-library/list-class.md) and [vector Class](../standard-library/vector-class.md) provide the needed `push_back` member function and satisfy these requirements. These three containers and strings may each be adapted to use with `back_insert_iterator`s. A `back_insert_iterator` must always be initialized with its container. ### Constructors @@ -186,7 +187,7 @@ A reference to the element inserted at the back of the container. ### Remarks -Used to implement the output iterator expression **\*Iter** = **value**. If **Iter** is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and does not change the total number of elements in the sequence. +Used to implement the output iterator expression **\*Iter** = **value**. If **Iter** is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and doesn't change the total number of elements in the sequence. ### Example diff --git a/docs/standard-library/bad-alloc-class.md b/docs/standard-library/bad-alloc-class.md index 9cd3cc8bd8..f18b4ca87e 100644 --- a/docs/standard-library/bad-alloc-class.md +++ b/docs/standard-library/bad-alloc-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: bad_alloc Class" title: "bad_alloc Class" +description: "Learn more about: bad_alloc Class" ms.date: "11/04/2016" f1_keywords: ["new/std::bad_alloc"] helpviewer_keywords: ["bad_alloc class"] -ms.assetid: 6429a8e6-5a49-4907-8d56-f4a4ec8131d0 --- # bad_alloc Class @@ -31,8 +30,8 @@ The value returned by `what` is an implementation-defined C string. None of the ```cpp // bad_alloc.cpp // compile with: /EHsc -#include -#include +#include +#include using namespace std; int main() { diff --git a/docs/standard-library/basic-filebuf-class.md b/docs/standard-library/basic-filebuf-class.md index 2893fddffc..39fe9a6ebb 100644 --- a/docs/standard-library/basic-filebuf-class.md +++ b/docs/standard-library/basic-filebuf-class.md @@ -1,10 +1,11 @@ --- description: "Learn more about: basic_filebuf Class" title: "basic_filebuf Class" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["fstream/std::basic_filebuf", "fstream/std::basic_filebuf::char_type", "fstream/std::basic_filebuf::int_type", "fstream/std::basic_filebuf::off_type", "fstream/std::basic_filebuf::pos_type", "fstream/std::basic_filebuf::traits_type", "fstream/std::basic_filebuf::close", "fstream/std::basic_filebuf::is_open", "fstream/std::basic_filebuf::open", "fstream/std::basic_filebuf::overflow", "fstream/std::basic_filebuf::pbackfail", "fstream/std::basic_filebuf::seekoff", "fstream/std::basic_filebuf::seekpos", "fstream/std::basic_filebuf::setbuf", "fstream/std::basic_filebuf::Swap", "fstream/std::basic_filebuf::sync", "fstream/std::basic_filebuf::uflow", "fstream/std::basic_filebuf::underflow"] helpviewer_keywords: ["std::basic_filebuf [C++]", "std::basic_filebuf [C++], char_type", "std::basic_filebuf [C++], int_type", "std::basic_filebuf [C++], off_type", "std::basic_filebuf [C++], pos_type", "std::basic_filebuf [C++], traits_type", "std::basic_filebuf [C++], close", "std::basic_filebuf [C++], is_open", "std::basic_filebuf [C++], open", "std::basic_filebuf [C++], overflow", "std::basic_filebuf [C++], pbackfail", "std::basic_filebuf [C++], seekoff", "std::basic_filebuf [C++], seekpos", "std::basic_filebuf [C++], setbuf", "std::basic_filebuf [C++], Swap", "std::basic_filebuf [C++], sync", "std::basic_filebuf [C++], uflow", "std::basic_filebuf [C++], underflow"] ms.assetid: 3196ba5c-bf38-41bd-9a95-70323ddfca1a +ms.custom: devdivchpfy22 --- # basic_filebuf Class @@ -206,7 +207,7 @@ basic_filebuf(basic_filebuf&& right); The first constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores a null pointer in the file pointer. -The second constructor initializes the object with the contents of *right*, treated as an rvalue reference. +The second constructor initializes the object with the contents of `right`, treated as an rvalue reference. ## basic_filebuf::char_type @@ -232,7 +233,7 @@ The member function returns a null pointer if the file pointer is a null pointer `close` calls `fclose(fp)`. If that function returns a nonzero value, the function returns a null pointer. Otherwise, it returns **`this`** to indicate that the file was successfully closed. -For a wide stream, if any insertions have occurred since the stream was opened, or since the last call to `streampos`, the function calls [`overflow`](#overflow). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet `fac` to call `fac.unshift` as needed. Each produced element `byte` of type **`char`** is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(byte, fp)`. If the call to `fac.unshift` or any write fails, the function does not succeed. +For a wide stream, if any insertions have occurred since the stream was opened, or since the last call to `streampos`, the function calls [`overflow`](#overflow). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet `fac` to call `fac.unshift` as needed. Each produced element `byte` of type **`char`** is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(byte, fp)`. If the call to `fac.unshift` or any write fails, the function doesn't succeed. ### Example @@ -386,11 +387,11 @@ This function uses a `FILE *` to back the `basic_filebuf` as though you had call - `ios_base::in | ios_base::out | ios_base::app` becomes `"a+"` (open existing file for reading and for appending all writes). If `mode & ios_base::binary` is nonzero, the function appends `b` to `strmode` to open a binary stream instead of a text stream. -If `mode & ios_base::ate` is nonzero and the file was succesfully opened, the current location in the stream is positioned at the end of file. If that fails, the file is closed. +If `mode & ios_base::ate` is nonzero and the file was successfully opened, the current location in the stream is positioned at the end of file. If that fails, the file is closed. If the above operations completed successfully, the file conversion facet is determined: `use_facet >(`[`getloc`](../standard-library/basic-streambuf-class.md#getloc)`)`, for use by [underflow](#underflow) and [overflow](#overflow). -If the file could not be succesfully opened, null is returned. +If the file couldn't be successfully opened, `nullptr` is returned. ### Example @@ -411,11 +412,11 @@ An rvalue reference to a [basic_filebuf](../standard-library/basic-filebuf-class ### Return Value -Returns __*this__. +Returns `*this`. ### Remarks -The member operator replaces the contents of the object by using the contents of *right*, treated as an rvalue reference. For more information, see [Rvalue reference declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +The member operator replaces the contents of the object by using the contents of `right`, treated as an rvalue reference. For more information, see [Rvalue reference declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). ## basic_filebuf::overflow @@ -442,7 +443,7 @@ If `_Meta != traits_type::`[`eof`](../standard-library/char-traits-struct.md#eof - It can make a write position available by allocating new or additional storage for the output buffer. -- It can convert any pending output in the output buffer, followed by `ch`, by using the file conversion facet `fac` to call `fac.out` as needed. Each produced element `ch` of type *char* is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(ch, fp)`. If any conversion or write fails, the function does not succeed. +- It can convert any pending output in the output buffer, followed by `ch`, by using the file conversion facet `fac` to call `fac.out` as needed. Each produced element `ch` of type *char* is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(ch, fp)`. If any conversion or write fails, the function doesn't succeed. ## basic_filebuf::pbackfail @@ -541,7 +542,7 @@ The protected virtual member function attempts to alter the current positions fo For a file opened for both reading and writing, both the input and output streams are positioned in tandem. To switch between inserting and extracting, you must call either [`pubseekoff`](../standard-library/basic-streambuf-class.md#pubseekoff) or [`pubseekpos`](../standard-library/basic-streambuf-class.md#pubseekpos). Calls to `pubseekoff` (and to `seekoff`) have various limitations for text streams, binary streams, and wide streams. -For a wide stream, if any insertions have occurred since the stream was opened, or since the last call to `streampos`, the function calls [overflow](#overflow). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet `fac` to call `fac.unshift` as needed. Each produced element `byte` of type **`char`** is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(byte, fp)`. If the call to `fac.unshift` or any write fails, the function does not succeed. +For a wide stream, if any insertions have occurred since the stream was opened, or since the last call to `streampos`, the function calls [`overflow`](#overflow). It also inserts any sequence needed to restore the initial conversion state, by using the file conversion facet `fac` to call `fac.unshift` as needed. Each produced element `byte` of type **`char`** is written to the associated stream designated by the file pointer `fp` as if by successive calls of the form `fputc(byte, fp)`. If the call to `fac.unshift` or any write fails, the function doesn't succeed. ## basic_filebuf::setbuf @@ -620,7 +621,7 @@ The protected virtual member function attempts to extract the current element `c - If a read position is available, it takes `ch` as the element stored in the read position and advances the next pointer for the input buffer. -- It can read one or more elements of type **`char`**, as if by successive calls of the form `fgetc(fp)`, and convert them to an element `ch` of type `Char_T` by using the file conversion facet `fac` to call `fac.in` as needed. If any read or conversion fails, the function does not succeed. +- It can read one or more elements of type **`char`**, as if by successive calls of the form `fgetc(fp)`, and convert them to an element `ch` of type `Char_T` by using the file conversion facet `fac` to call `fac.in` as needed. If any read or conversion fails, the function doesn't succeed. ## See also diff --git a/docs/standard-library/basic-fstream-class.md b/docs/standard-library/basic-fstream-class.md index 7ddc445a51..3a9f9883a8 100644 --- a/docs/standard-library/basic-fstream-class.md +++ b/docs/standard-library/basic-fstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_fstream Class" title: "basic_fstream Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_fstream Class" +ms.date: 11/04/2016 f1_keywords: ["fstream/std::basic_fstream", "fstream/std::basic_fstream::close", "fstream/std::basic_fstream::is_open", "fstream/std::basic_fstream::open", "fstream/std::basic_fstream::rdbuf", "fstream/std::basic_fstream::swap"] helpviewer_keywords: ["std::basic_fstream [C++]", "std::basic_fstream [C++], close", "std::basic_fstream [C++], is_open", "std::basic_fstream [C++], open", "std::basic_fstream [C++], rdbuf", "std::basic_fstream [C++], swap"] -ms.assetid: 8473817e-42a4-430b-82b8-b476c86bcf8a --- # basic_fstream Class @@ -204,7 +203,7 @@ The default file opening protection, equivalent to the *shflag* parameter in [_f ### Remarks -The member function calls [rdbuf](#rdbuf) **->** [open](../standard-library/basic-filebuf-class.md#open)(_ *Filename*, `_Mode`). If that function returns a null pointer, the function calls [setstate](../standard-library/basic-ios-class.md#setstate)( `failbit`). +The member function calls [rdbuf](#rdbuf) **->** [open](../standard-library/basic-filebuf-class.md#open)(_ *Filename*, `_Mode`). If that function returns a null pointer, the function calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`). ### Example diff --git a/docs/standard-library/basic-ifstream-class.md b/docs/standard-library/basic-ifstream-class.md index 89ac551724..2054c8ce2a 100644 --- a/docs/standard-library/basic-ifstream-class.md +++ b/docs/standard-library/basic-ifstream-class.md @@ -1,14 +1,16 @@ --- description: "Learn more about: basic_ifstream Class" title: "basic_ifstream Class" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["fstream/std::basic_ifstream", "fstream/std::basic_ifstream::close", "fstream/std::basic_ifstream::is_open", "fstream/std::basic_ifstream::open", "fstream/std::basic_ifstream::rdbuf", "fstream/std::basic_ifstream::swap"] helpviewer_keywords: ["std::basic_ifstream [C++]", "std::basic_ifstream [C++], close", "std::basic_ifstream [C++], is_open", "std::basic_ifstream [C++], open", "std::basic_ifstream [C++], rdbuf", "std::basic_ifstream [C++], swap"] -ms.assetid: 366cd9a7-efc4-4b7f-ba10-c8271e47ffcf +ms.custom: devdivchpfy22 --- -# basic_ifstream Class +# `basic_ifstream` Class -Describes an object that controls extraction of elements and encoded objects from a stream buffer of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>, with elements of type `Elem`, whose character traits are determined by the class `Tr`. +Describes an object that controls extraction of elements and encoded objects from a stream buffer of class `basic_filebuf`, with elements of type `Elem`, whose character traits are determined by the class `Tr`. + +For more information, see [`basic_filebuf`](../standard-library/basic-filebuf-class.md). ## Syntax @@ -19,15 +21,15 @@ class basic_ifstream : public basic_istream ### Parameters -*Elem*\ +*`Elem`*\ The basic element of the file buffer. -*Tr*\ -The traits of the basic element of the file buffer (usually `char_traits`< `Elem`>). +*`Tr`*\ +The traits of the basic element of the file buffer (usually `char_traits`). ## Remarks -The object stores an object of class `basic_filebuf`< `Elem`, `Tr`>. +The object stores an object of class `basic_filebuf`. ## Example @@ -54,7 +56,7 @@ int main(int argc, char **argv) } ``` -## Input: basic_ifstream_class.txt +## Input: `basic_ifstream_class.txt` ```cpp This is the contents of basic_ifstream_class.txt. @@ -70,31 +72,31 @@ This is the contents of basic_ifstream_class.txt. |Constructor|Description| |-|-| -|[basic_ifstream](#basic_ifstream)|Initializes a new instance of a `basic_ifstream` object.| +|[`basic_ifstream`](#basic_ifstream)|Initializes a new instance of a `basic_ifstream` object.| ### Member functions |Member function|Description| |-|-| -|[close](#close)|Closes a file.| -|[is_open](#is_open)|Determines if a file is open.| -|[open](#open)|Opens a file.| -|[rdbuf](#rdbuf)|Returns the address of the stored stream buffer.| -|[swap](#swap)|Exchanges the content of this `basic_ifstream` for the content of the provided `basic_ifstream`.| +|[`close`](#close)|Closes a file.| +|[`is_open`](#is_open)|Determines if a file is open.| +|[`open`](#open)|Opens a file.| +|[`rdbuf`](#rdbuf)|Returns the address of the stored stream buffer.| +|[`swap`](#swap)|Exchanges the content of this `basic_ifstream` for the content of the provided `basic_ifstream`.| ### Operators |Operator|Description| |-|-| -|[operator=](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue` that does not leave a copy behind.| +|[`operator=`](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue` that doesn't leave a copy behind.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_ifstream::basic_ifstream +## `basic_ifstream::basic_ifstream` Constructs an object of type `basic_ifstream`. @@ -116,26 +118,28 @@ basic_ifstream(basic_ifstream&& right); ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). ### Remarks -The first constructor initializes the base class by calling [basic_istream](../standard-library/basic-istream-class.md)( `sb`), where `sb` is the stored object of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`>. +The first constructor initializes the base class by calling `basic_istream(sb)`, where `sb` is the stored object of class `basic_filebuf`. It also initializes `sb` by calling `basic_filebuf`. + +The second and third constructors initialize the base class by calling `basic_istream(sb)`. It also initializes `sb` by calling `basic_filebuf`, then `sb.open(_Filename, _Mode | ios_base::in)`. If the latter function returns a null pointer, the constructor calls `setstate(failbit)`. -The second and third constructors initializes the base class by calling `basic_istream`( `sb`). It also initializes `sb` by calling [basic_filebuf](../standard-library/basic-filebuf-class.md#basic_filebuf)< `Elem`, `Tr`>, then `sb`. [open](../standard-library/basic-filebuf-class.md#open)( `_Filename`, `_Mode` | `ios_base::in`). If the latter function returns a null pointer, the constructor calls **setstate**( `failbit`). +The fourth constructor initializes the object with the contents of `right`, treated as an `rvalue` reference. -The fourth constructor initializes the object with the contents of `right`, treated as an rvalue reference. +For more information, see [`basic_istream`](../standard-library/basic-istream-class.md), [`basic_filebuf`](../standard-library/basic-filebuf-class.md#basic_filebuf), [`setstate`](../standard-library/basic-ios-class.md#setstate), and [`open`](../standard-library/basic-filebuf-class.md#open). ### Example -The following example shows how to read in text from a file. To create the file, see the example for [basic_ofstream::basic_ofstream](../standard-library/basic-ofstream-class.md#basic_ofstream). +The following example shows how to read in text from a file. To create the file, see the example for [`basic_ofstream::basic_ofstream`](../standard-library/basic-ofstream-class.md#basic_ofstream). ```cpp // basic_ifstream_ctor.cpp @@ -158,7 +162,7 @@ int main(int argc, char **argv) } ``` -## basic_ifstream::close +## `basic_ifstream::close` Closes a file. @@ -168,13 +172,13 @@ void close(); ### Remarks -The member function calls [rdbuf](#rdbuf) **->** [close](../standard-library/basic-filebuf-class.md#close). +The member function calls [`rdbuf`](#rdbuf) **->** [`close`](../standard-library/basic-filebuf-class.md#close). ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. -## basic_ifstream::is_open +## `basic_ifstream::is_open` Determines if a file is open. @@ -188,13 +192,13 @@ bool is_open() const; ### Remarks -The member function returns [rdbuf](#rdbuf) **->** [is_open](../standard-library/basic-filebuf-class.md#is_open). +The member function returns [`rdbuf`](#rdbuf) **->** [`is_open`](../standard-library/basic-filebuf-class.md#is_open). ### Example -See [basic_filebuf::is_open](../standard-library/basic-filebuf-class.md#is_open) for an example that uses `is_open`. +See [`basic_filebuf::is_open`](../standard-library/basic-filebuf-class.md#is_open) for an example that uses `is_open`. -## basic_ifstream::open +## `basic_ifstream::open` Opens a file. @@ -220,26 +224,26 @@ void open( ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). ### Remarks -The member function calls [rdbuf](#rdbuf) **->** [open](../standard-library/basic-filebuf-class.md#open)(_ *Filename*, `_Mode` | **ios_base::in**). If open fails, the function calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`), which may throw an ios_base::failure exception. +The member function calls `rdbuf->open(_Filename, _Mode | ios_base::in)`. For more information, see [`rdbuf`](#rdbuf) and [`basic_filebuf::open`](../standard-library/basic-filebuf-class.md#open). If open fails, the function calls `setstate(failbit)`, which may throw an `ios_base::failure` exception. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example -See [basic_filebuf::open](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. +See [`basic_filebuf::open`](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. -## basic_ifstream::operator= +## `basic_ifstream::operator=` -Assigns the content of this stream object. This is a move assignment involving an rvalue that does not leave a copy behind. +Assigns the content of this stream object. This is a move assignment involving an `rvalue` that doesn't leave a copy behind. ```cpp basic_ifstream& operator=(basic_ifstream&& right); @@ -247,8 +251,8 @@ basic_ifstream& operator=(basic_ifstream&& right); ### Parameters -*right*\ -An rvalue reference to a `basic_ifstream` object. +*`right`*\ +An `rvalue` reference to a `basic_ifstream` object. ### Return Value @@ -256,9 +260,9 @@ Returns **`*this`**. ### Remarks -The member operator replaces the contents of the object by using the contents of *right*, treated as an rvalue reference. For more information, see [Lvalues and Rvalues](../cpp/lvalues-and-rvalues-visual-cpp.md). +The member operator replaces the contents of the object by using the contents of *`right`*, treated as an `rvalue` reference. For more information, see [`Lvalues` and `Rvalues`](../cpp/lvalues-and-rvalues-visual-cpp.md). -## basic_ifstream::rdbuf +## `basic_ifstream::rdbuf` Returns the address of the stored stream buffer. @@ -268,13 +272,13 @@ basic_filebuf *rdbuf() const ### Return Value -A pointer to a [basic_filebuf](../standard-library/basic-filebuf-class.md) object representing the stored stream buffer. +A pointer to a [`basic_filebuf`](../standard-library/basic-filebuf-class.md) object representing the stored stream buffer. ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. -## basic_ifstream::swap +## `basic_ifstream::swap` Exchanges the contents of two `basic_ifstream` objects. @@ -284,15 +288,15 @@ void swap(basic_ifstream& right); ### Parameters -*right*\ +*`right`*\ A reference to another stream buffer. ### Remarks -The member function exchanges the contents of this object for the contents of *right*. +The member function exchanges the contents of this object for the contents of *`right`*. ## See also [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/basic-ios-class.md b/docs/standard-library/basic-ios-class.md index 186bc54fca..28cdc9a600 100644 --- a/docs/standard-library/basic-ios-class.md +++ b/docs/standard-library/basic-ios-class.md @@ -1,100 +1,101 @@ --- description: "Learn more about: basic_ios Class" title: "basic_ios Class" -ms.date: "11/04/2016" +ms.date: 06/07/2022 f1_keywords: ["ios/std::basic_ios", "ios/std::basic_ios::char_type", "ios/std::basic_ios::int_type", "ios/std::basic_ios::off_type", "ios/std::basic_ios::pos_type", "ios/std::basic_ios::traits_type", "ios/std::basic_ios::bad", "ios/std::basic_ios::clear", "ios/std::basic_ios::copyfmt", "ios/std::basic_ios::eof", "ios/std::basic_ios::exceptions", "ios/std::basic_ios::fail", "ios/std::basic_ios::fill", "ios/std::basic_ios::good", "ios/std::basic_ios::imbue", "ios/std::basic_ios::init", "ios/std::basic_ios::move", "ios/std::basic_ios::narrow", "ios/std::basic_ios::rdbuf", "ios/std::basic_ios::rdstate", "ios/std::basic_ios::set_rdbuf", "ios/std::basic_ios::setstate", "ios/std::basic_ios::swap", "ios/std::basic_ios::tie", "ios/std::basic_ios::widen", "ios/std::basic_ios::explicit operator bool"] helpviewer_keywords: ["std::basic_ios [C++]", "std::basic_ios [C++], char_type", "std::basic_ios [C++], int_type", "std::basic_ios [C++], off_type", "std::basic_ios [C++], pos_type", "std::basic_ios [C++], traits_type", "std::basic_ios [C++], bad", "std::basic_ios [C++], clear", "std::basic_ios [C++], copyfmt", "std::basic_ios [C++], eof", "std::basic_ios [C++], exceptions", "std::basic_ios [C++], fail", "std::basic_ios [C++], fill", "std::basic_ios [C++], good", "std::basic_ios [C++], imbue", "std::basic_ios [C++], init", "std::basic_ios [C++], move", "std::basic_ios [C++], narrow", "std::basic_ios [C++], rdbuf", "std::basic_ios [C++], rdstate", "std::basic_ios [C++], set_rdbuf", "std::basic_ios [C++], setstate", "std::basic_ios [C++], swap", "std::basic_ios [C++], tie", "std::basic_ios [C++], widen"] -ms.assetid: 4fdcd8e1-62d2-4611-8a70-1e4f58434007 +ms.custom: devdivchpfy22 --- -# basic_ios Class +# `basic_ios` Class -The class template describes the storage and member functions common to both input streams (of class template [basic_istream](../standard-library/basic-istream-class.md)) and output streams (of class template [basic_ostream](../standard-library/basic-ostream-class.md)) that depend on the template parameters. (The class [ios_base](../standard-library/ios-base-class.md) describes what is common and not dependent on template parameters.) An object of class **basic_ios\** helps control a stream with elements of type `Elem`, whose character traits are determined by the class `Traits`. +The class template describes the storage and member functions common to both input streams (of class template [`basic_istream`](../standard-library/basic-istream-class.md)) and output streams (of class template [`basic_ostream`](../standard-library/basic-ostream-class.md)) that depend on the template parameters. (The class [`ios_base`](../standard-library/ios-base-class.md) describes what is common and not dependent on template parameters.) An object of class `basic_ios` helps control a stream with elements of type `Elem`, whose character traits are determined by the class `Traits`. ## Syntax ```cpp - template class basic_ios : public ios_base ``` ### Parameters -*Elem*\ +*`Elem`*\ A character type. -*Traits*\ +*`Traits`*\ A type providing information about the character type, defaults to `char_traits < Elem >`. ## Remarks -An object of class **basic_ios\** stores: +An object of class `basic_ios` stores: -- A tie pointer to an object of type [basic_istream](../standard-library/basic-istream-class.md)**\**. +- A tie pointer to an object of type `basic_istream`. -- A stream buffer pointer to an object of type [basic_streambuf](../standard-library/basic-streambuf-class.md)**\**. +- A stream buffer pointer to an object of type `basic_streambuf`. - [Formatting information](../standard-library/ios-base-class.md). -- [Stream state information](../standard-library/ios-base-class.md) in a base object of type [ios_base](../standard-library/ios-base-class.md). +- [Stream state information](../standard-library/ios-base-class.md) in a base object of type [`ios_base`](../standard-library/ios-base-class.md). - A fill character in an object of type `char_type`. +For more information, see [`basic_istream`](../standard-library/basic-istream-class.md) and [`basic_streambuf`](../standard-library/basic-streambuf-class.md). + ### Constructors |Constructor|Description| |-|-| -|[basic_ios](#basic_ios)|Constructs the `basic_ios` class.| +|[`basic_ios`](#basic_ios)|Constructs the `basic_ios` class.| ### Typedefs |Type name|Description| |-|-| -|[char_type](#char_type)|A synonym for the template parameter `Elem`.| -|[int_type](#int_type)|A synonym for `Traits::int_type`.| -|[off_type](#off_type)|A synonym for `Traits::off_type`.| -|[pos_type](#pos_type)|A synonym for `Traits::pos_type`.| -|[traits_type](#traits_type)|A synonym for the template parameter `Traits`.| +|[`char_type`](#char_type)|A synonym for the template parameter `Elem`.| +|[`int_type`](#int_type)|A synonym for `Traits::int_type`.| +|[`off_type`](#off_type)|A synonym for `Traits::off_type`.| +|[`pos_type`](#pos_type)|A synonym for `Traits::pos_type`.| +|[`traits_type`](#traits_type)|A synonym for the template parameter `Traits`.| ### Member functions |Member function|Description| |-|-| -|[bad](#bad)|Indicates a loss of integrity of the stream buffer.| -|[clear](#clear)|Clears all error flags.| -|[copyfmt](#copyfmt)|Copies flags from one stream to another.| -|[eof](#eof)|Indicates if the end of a stream has been reached.| -|[exceptions](#exceptions)|Indicates which exceptions will be thrown by the stream.| -|[fail](#fail)|Indicates failure to extract a valid field from a stream.| -|[fill](#fill)|Specifies or returns the character that will be used when the text is not as wide as the stream.| -|[good](#good)|Indicates the stream is in good condition.| -|[imbue](#imbue)|Changes the locale.| -|[init](#init)|Called by `basic_ios` constructors.| -|[move](#move)|Moves all values, except the pointer to the stream buffer, from the parameter to the current object.| -|[narrow](#narrow)|Finds the equivalent char to a given `char_type`.| -|[rdbuf](#rdbuf)|Routes stream to specified buffer.| -|[rdstate](#rdstate)|Reads the state of bits for flags.| -|[set_rdbuf](#set_rdbuf)|Assigns a stream buffer to be the read buffer for this stream object.| -|[setstate](#setstate)|Sets additional flags.| -|[swap](#swap)|Exchanges the values in this `basic_ios` object for those of another `basic_ios` object. The pointers to the stream buffers are not swapped.| -|[tie](#tie)|Ensures that one stream is processed before another stream.| -|[widen](#widen)|Finds the equivalent `char_type` to a given char.| +|[`bad`](#bad)|Indicates a loss of integrity of the stream buffer.| +|[`clear`](#clear)|Clears all error flags.| +|[`copyfmt`](#copyfmt)|Copies flags from one stream to another.| +|[`eof`](#eof)|Indicates if the end of a stream has been reached.| +|[`exceptions`](#exceptions)|Indicates which exceptions will be thrown by the stream.| +|[`fail`](#fail)|Indicates failure to extract a valid field from a stream.| +|[`fill`](#fill)|Specifies or returns the character that will be used when the text isn't as wide as the stream.| +|[`good`](#good)|Indicates the stream is in good condition.| +|[`imbue`](#imbue)|Changes the locale.| +|[`init`](#init)|Called by `basic_ios` constructors.| +|[`move`](#move)|Moves all values, except the pointer to the stream buffer, from the parameter to the current object.| +|[`narrow`](#narrow)|Finds the equivalent char to a given `char_type`.| +|[`rdbuf`](#rdbuf)|Routes stream to specified buffer.| +|[`rdstate`](#rdstate)|Reads the state of bits for flags.| +|[`set_rdbuf`](#set_rdbuf)|Assigns a stream buffer to be the read buffer for this stream object.| +|[`setstate`](#setstate)|Sets additional flags.| +|[`swap`](#swap)|Exchanges the values in this `basic_ios` object for those of another `basic_ios` object. The pointers to the stream buffers aren't swapped.| +|[`tie`](#tie)|Ensures that one stream is processed before another stream.| +|[`widen`](#widen)|Finds the equivalent `char_type` to a given char.| ### Operators |Operator|Description| |-|-| -|[explicit operator bool](#op_bool)|Allows use of a `basic_ios` object as a **`bool`**. Automatic type conversion is disabled to prevent common, unintended side effects.| -|[operator void *](#op_void_star)|Indicates if the stream is still good.| -|[operator!](#op_not)|Indicates if the stream is not bad.| +|[`explicit operator bool`](#op_bool)|Allows use of a `basic_ios` object as a **`bool`**. Automatic type conversion is disabled to prevent common, unintended side effects.| +|[`operator void *`](#op_void_star)|Indicates if the stream is still good.| +|[`operator!`](#op_not)|Indicates if the stream isn't bad.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_ios::bad +## `basic_ios::bad` Indicates a loss of integrity of the stream buffer @@ -106,7 +107,7 @@ bool bad() const; **`true`** if `rdstate & badbit` is nonzero; otherwise **`false`**. -For more information on `badbit`, see [ios_base::iostate](../standard-library/ios-base-class.md#iostate). +For more information on `badbit`, see [`ios_base::iostate`](../standard-library/ios-base-class.md#iostate). ### Example @@ -127,9 +128,9 @@ int main( void ) } ``` -## basic_ios::basic_ios +## `basic_ios::basic_ios` -Constructs the basic_ios class. +Constructs the `basic_ios` class. ```cpp explicit basic_ios(basic_streambuf* sb); @@ -138,14 +139,14 @@ basic_ios(); ### Parameters -*sb*\ +*`sb`*\ Standard buffer to store input or output elements. ### Remarks -The first constructor initializes its member objects by calling [init](#init)(_ *Sb*). The second (protected) constructor leaves its member objects uninitialized. A later call to `init` must initialize the object before it can be safely destroyed. +The first constructor initializes its member objects by calling `init(_ Sb)`. The second (protected) constructor leaves its member objects uninitialized. A later call to [`init`](#init) must initialize the object before it can be safely destroyed. -## basic_ios::char_type +## `basic_ios::char_type` A synonym for the template parameter `Elem`. @@ -153,7 +154,7 @@ A synonym for the template parameter `Elem`. typedef Elem char_type; ``` -## basic_ios::clear +## `basic_ios::clear` Clears all error flags. @@ -164,27 +165,29 @@ void clear(io_state state); ### Parameters -*state*\ +*`state`*\ (Optional) The flags you want to set after clearing all flags. Defaults to `goodbit`. -*reraise*\ -(Optional) Specifies whether the exception should be re-raised. Defaults to **`false`** (will not re-raise the exception). +*`reraise`*\ +(Optional) Specifies whether the exception should be re-raised. Defaults to **`false`** (won't re-raise the exception). ### Remarks -The flags are `goodbit`, `failbit`, `eofbit`, and `badbit`. Test for these flags with [good](#good), [bad](#bad), [eof](#eof), and [fail](#fail) +The flags are `goodbit`, `failbit`, `eofbit`, and `badbit`. Test for these flags with [`good`](#good), [`bad`](#bad), [`eof`](#eof), and [`fail`](#fail) The member function replaces the stored stream state information with: -`state` | `(`[rdbuf](#rdbuf) != 0 **goodbit** : **badbit**) +`state | (rdbuf != 0 goodbit : badbit)` + +If `state&exceptions` is nonzero, it then throws an object of class [`failure`](../standard-library/ios-base-class.md#failure). -If `state`**&**[exceptions](#exceptions) is nonzero, it then throws an object of class [failure](../standard-library/ios-base-class.md#failure). +For more information, see [`rdbuf`](#rdbuf) and [`exceptions`](#exceptions). ### Example -See [rdstate](#rdstate) and [getline](../standard-library/string-functions.md#getline) for examples using `clear`. +See [`rdstate`](#rdstate) and [`getline`](../standard-library/string-functions.md#getline) for examples using `clear`. -## basic_ios::copyfmt +## `basic_ios::copyfmt` Copies flags from one stream to another. @@ -195,16 +198,16 @@ const basic_ios& right); ### Parameters -*right*\ +*`right`*\ The stream whose flags you want to copy. ### Return Value -The **`this`** object for the stream to which you are copying the flags. +The **`this`** object for the stream to which you're copying the flags. ### Remarks -The member function reports the callback event **erase\_event**. It then copies from *right* into **\*this** the fill character, the tie pointer, and the formatting information. Before altering the exception mask, it reports the callback event `copyfmt_event`. If, after the copy is complete, **state &**[exceptions](#exceptions) is nonzero, the function effectively calls [clear](#clear) with the argument [rdstate](#rdstate). It returns **\*this**. +The member function reports the callback event **`erase_event`**. It then copies from *`right`* into **`*this`** the fill character, the tie pointer, and the formatting information. Before altering the exception mask, it reports the callback event `copyfmt_event`. If after the copy is complete, `state&exceptions` is nonzero, the function effectively calls [`clear`](#clear) with the argument [`rdstate`](#rdstate). It returns **`*this`**. ### Example @@ -227,7 +230,7 @@ int main( ) } ``` -## basic_ios::eof +## `basic_ios::eof` Indicates if the end of a stream has been reached. @@ -241,7 +244,7 @@ bool eof() const; ### Remarks -The member function returns **`true`** if [rdstate](#rdstate) `& eofbit` is nonzero. For more information on `eofbit`, see [ios_base::iostate](../standard-library/ios-base-class.md#iostate). +The member function returns **`true`** if [`rdstate`](#rdstate) `& eofbit` is nonzero. For more information on `eofbit`, see [`ios_base::iostate`](../standard-library/ios-base-class.md#iostate). ### Example @@ -265,7 +268,7 @@ int main( int argc, char* argv[] ) } ``` -## basic_ios::exceptions +## `basic_ios::exceptions` Indicates which exceptions will be thrown by the stream. @@ -277,16 +280,16 @@ void exceptions(io_state Newexcept); ### Parameters -*Newexcept*\ +*`Newexcept`*\ The flags that you want to throw an exception. ### Return Value -The flags that are currently specified to thrown an exception for the stream. +The flags that are currently specified to throw an exception for the stream. ### Remarks -The first member function returns the stored exception mask. The second member function stores *_Except* in the exception mask and returns its previous stored value. Note that storing a new exception mask can throw an exception just like the call [clear](#clear)( [rdstate](#rdstate) ). +The first member function returns the stored exception mask. The second member function stores *`_Except`* in the exception mask and returns its previous stored value. Storing a new exception mask can throw an exception just like the call [`clear`](#clear)( [`rdstate`](#rdstate) ). ### Example @@ -324,7 +327,7 @@ Exception class: class std::ios_base::failure Exception description: ios_base::eofbit set ``` -## basic_ios::fail +## `basic_ios::fail` Indicates failure to extract a valid field from a stream. @@ -334,9 +337,9 @@ bool fail() const; ### Return Value -**`true`** if [rdstate](#rdstate) `& (badbit|failbit)` is nonzero, otherwise **`false`**. +**`true`** if `rdstate & (badbit|failbit)` is nonzero, otherwise **`false`**. -For more information on `failbit`, see [ios_base::iostate](../standard-library/ios-base-class.md#iostate). +For more information on `failbit`, see [`ios_base::iostate`](../standard-library/ios-base-class.md#iostate). ### Example @@ -354,9 +357,9 @@ int main( void ) } ``` -## basic_ios::fill +## `basic_ios::fill` -Specifies or returns the character that will be used when the text is not as wide as the stream. +Specifies or returns the character that will be used when the text isn't as wide as the stream. ```cpp char_type fill() const; @@ -365,7 +368,7 @@ char_type fill(char_type Char); ### Parameters -*Char*\ +*`Char`*\ The character you want as the fill character. ### Return Value @@ -374,7 +377,7 @@ The current fill character. ### Remarks -The first member function returns the stored fill character. The second member function stores *Char* in the fill character and returns its previous stored value. +The first member function returns the stored fill character. The second member function stores *`Char`* in the fill character and returns its previous stored value. ### Example @@ -401,7 +404,7 @@ xxxxa x ``` -## basic_ios::good +## `basic_ios::good` Indicates the stream is in good condition. @@ -411,15 +414,15 @@ bool good() const; ### Return Value -**`true`** if [rdstate](#rdstate) `== goodbit` (no state flags are set), otherwise, **`false`**. +**`true`** if `rdstate == goodbit` (no state flags are set), otherwise, **`false`**. -For more information on `goodbit`, see [ios_base::iostate](../standard-library/ios-base-class.md#iostate). +For more information on `goodbit`, see [`ios_base::iostate`](../standard-library/ios-base-class.md#iostate). ### Example -See [basic_ios::bad](#bad) for an example of using `good`. +See [`basic_ios::bad`](#bad) for an example of using `good`. -## basic_ios::imbue +## `basic_ios::imbue` Changes the locale. @@ -429,7 +432,7 @@ locale imbue(const locale& Loc); ### Parameters -*Loc*\ +*`Loc`*\ A locale string. ### Return Value @@ -438,11 +441,13 @@ The previous locale. ### Remarks -If [rdbuf](#rdbuf) is not a null pointer, the member function calls +If [`rdbuf`](#rdbuf) isn't a `NULL` pointer, the member function calls -`rdbuf`-> [pubimbue](../standard-library/basic-streambuf-class.md#pubimbue)(_ *Loc*) +`rdbuf-> pubimbue(_ Loc)` -In any case, it returns [ios_base::imbue](../standard-library/ios-base-class.md#imbue)(_ *Loc*). +In any case, it returns `ios_base::imbue(_ Loc)`. + +For more information, see [`pubimbue`](../standard-library/basic-streambuf-class.md#pubimbue) and [`ios_base::imbue`](../standard-library/ios-base-class.md#imbue). ### Example @@ -462,9 +467,9 @@ int main( ) } ``` -## basic_ios::init +## `basic_ios::init` -Called by basic_ios constructors. +Called by `basic_ios` constructors. ```cpp void init(basic_streambuf* _Sb, bool _Isstd = false); @@ -472,37 +477,37 @@ void init(basic_streambuf* _Sb, bool _Isstd = false); ### Parameters -*_Sb*\ +*`_Sb`*\ Standard buffer to store input or output elements. -*_Isstd*\ +*`_Isstd`*\ Specifies whether this is a standard stream. ### Remarks The member function stores values in all member objects, so that: -- [rdbuf](#rdbuf) returns *_Sb.* +- [`rdbuf`](#rdbuf) returns *`_Sb`*. -- [tie](#tie) returns a null pointer. +- [`tie`](#tie) returns a `NULL` pointer. -- [rdstate](#rdstate) returns [goodbit](../standard-library/ios-base-class.md#iostate) if *_Sb* is nonzero; otherwise, it returns [badbit](../standard-library/ios-base-class.md#iostate). +- [`rdstate`](#rdstate) returns [`goodbit`](../standard-library/ios-base-class.md#iostate) if *`_Sb`* is nonzero; otherwise, it returns [`badbit`](../standard-library/ios-base-class.md#iostate). -- [exceptions](#exceptions) returns `goodbit`. +- [`exceptions`](#exceptions) returns `goodbit`. -- [flags](../standard-library/ios-base-class.md#flags) returns [skipws](../standard-library/ios-base-class.md#fmtflags) | [dec](../standard-library/ios-base-class.md#fmtflags). +- [`flags`](../standard-library/ios-base-class.md#flags) returns `skipws | dec`. For more information, see [`skipws`](../standard-library/ios-base-class.md#fmtflags) and [`dec`](../standard-library/ios-base-class.md#fmtflags). -- [width](../standard-library/ios-base-class.md#width) returns 0. +- [`width`](../standard-library/ios-base-class.md#width) returns 0. -- [precision](../standard-library/ios-base-class.md#precision) returns 6. +- [`precision`](../standard-library/ios-base-class.md#precision) returns 6. -- [fill](#fill) returns the space character. +- [`fill`](#fill) returns the space character. -- [getloc](../standard-library/ios-base-class.md#getloc) returns `locale::classic`. +- [`getloc`](../standard-library/ios-base-class.md#getloc) returns `locale::classic`. -- [iword](../standard-library/ios-base-class.md#iword) returns zero, and [pword](../standard-library/ios-base-class.md#pword) returns a null pointer for all argument values. +- [`iword`](../standard-library/ios-base-class.md#iword) returns zero, and [`pword`](../standard-library/ios-base-class.md#pword) returns a `NULL` pointer for all argument values. -## basic_ios::int_type +## `basic_ios::int_type` A synonym for `traits_type::int_type`. @@ -510,7 +515,7 @@ A synonym for `traits_type::int_type`. typedef typename traits_type::int_type int_type; ``` -## basic_ios::move +## `basic_ios::move` Moves all values, except the pointer to the stream buffer, from the parameter to the current object. @@ -520,14 +525,14 @@ void move(basic_ios&& right); ### Parameters -*right*\ +*`right`*\ The `ios_base` object to move values from. ### Remarks -The protected member function moves all the values stored in *right* to **`*this`** except the stored `stream buffer pointer`, which is unchanged in *right* and set to a null pointer in **`*this`**. The stored `tie pointer` is set to a null pointer in *right*. +The protected member function moves all the values stored in *`right`* to **`*this`** except the stored `stream buffer pointer`, which is unchanged in *`right`* and set to a `NULL` pointer in **`*this`**. The stored `tie pointer` is set to a `NULL` pointer in *`right`*. -## basic_ios::narrow +## `basic_ios::narrow` Finds the equivalent char to a given `char_type`. @@ -537,10 +542,10 @@ char narrow(char_type Char, char Default = '\0') const; ### Parameters -*Char*\ +*`Char`*\ The **`char`** to convert. -*Default*\ +*`Default`*\ The **`char`** that you want returned if no equivalent is found. ### Return Value @@ -549,7 +554,10 @@ The equivalent **`char`** to a given `char_type`. ### Remarks -The member function returns [use_facet](../standard-library/basic-filebuf-class.md#open)\ >( [getloc](../standard-library/ios-base-class.md#getloc)( ) ).`narrow`( `Char`, `Default`). +The member function returns `use_facet>(getloc()).narrow(Char, Default)`. + +For more information, see [`use_facet`](../standard-library/basic-filebuf-class.md#open) and [`getloc`](../standard-library/ios-base-class.md#getloc). + ### Example @@ -572,7 +580,7 @@ int main( ) } ``` -## basic_ios::off_type +## `basic_ios::off_type` A synonym for `traits_type::off_type`. @@ -580,7 +588,7 @@ A synonym for `traits_type::off_type`. typedef typename traits_type::off_type off_type; ``` -## basic_ios::operator void * +## `basic_ios::operator void *` Indicates if the stream is still good. @@ -590,7 +598,7 @@ operator void *() const; ### Return Value -The operator returns a null pointer only if [fail](#fail). +The operator returns a `NULL` pointer only if [`fail`](#fail). ### Example @@ -610,9 +618,9 @@ int main( ) 1 ``` -## basic_ios::operator! +## `basic_ios::operator!` -Indicates if the stream is not bad. +Indicates if the stream isn't bad. ```cpp bool operator!() const; @@ -620,7 +628,7 @@ bool operator!() const; ### Return Value -Returns [fail](#fail). +Returns the same as calling [`basic_ios::fail`](#fail) ### Example @@ -640,7 +648,7 @@ int main( ) 0 ``` -## basic_ios::operator bool +## `basic_ios::operator bool` Allows use of a `basic_ios` object as a **`bool`**. Automatic type conversion is disabled to prevent common, unintended side effects. @@ -650,9 +658,9 @@ explicit operator bool() const; ### Remarks -The operator returns a value convertible to **`false`** only if `fail()`. The return type is convertible only to **`bool`**, not to `void *` or other known scalar type. +Returns `true` if the stream has no errors; otherwise `false`. -## basic_ios::pos_type +## `basic_ios::pos_type` A synonym for `traits_type::pos_type`. @@ -660,7 +668,7 @@ A synonym for `traits_type::pos_type`. typedef typename traits_type::pos_type pos_type; ``` -## basic_ios::rdbuf +## `basic_ios::rdbuf` Routes stream to specified buffer. @@ -672,14 +680,14 @@ basic_streambuf* _Sb); ### Parameters -*_Sb*\ +*`_Sb`*\ A stream. ### Remarks The first member function returns the stored stream buffer pointer. -The second member function stores *_Sb* in the stored stream buffer pointer and returns the previously stored value. +The second member function stores *`_Sb`* in the stored stream buffer pointer and returns the previously stored value. ### Example @@ -705,9 +713,9 @@ int main( ) test2 ``` -## basic_ios::rdstate +## `basic_ios::rdstate` -Reads the state of bits for flags. +Reads the stream error state. ```cpp iostate rdstate() const; @@ -754,9 +762,16 @@ int main( ) 1 ``` -## basic_ios::setstate +## `basic_ios::setstate` + +Sets the specified stream error flags (currently set stream error state flags remain unchanged): -Sets additional flags. +| flag | Description | +| ---- | ----------- | +| [`goodbit`](../standard-library/ios-base-class.md#iostate) | No error | +| [`badbit`](../standard-library/ios-base-class.md#iostate) | Unrecoverable error | +| [`failbit`](../standard-library/ios-base-class.md#iostate) | I/O operation failed, such as a formatting or extraction error | +| [`eofbit`](../standard-library/ios-base-class.md#iostate) | Stream has reached the end of the file | ```cpp void setstate(iostate _State); @@ -764,12 +779,14 @@ void setstate(iostate _State); ### Parameters -*_State*\ +*`_State`*\ Additional flags to set. ### Remarks -The member function effectively calls [clear](#clear)(_ *State* | [rdstate](#rdstate)). +The member function essentially calls `clear(_ state | rdstate)`. + +For more information, see [`clear`](#clear) and [`rdstate`](#rdstate). ### Example @@ -803,7 +820,7 @@ int main( ) 1 ``` -## basic_ios::set_rdbuf +## `basic_ios::set_rdbuf` Assigns a stream buffer to be the read buffer for this stream object. @@ -814,14 +831,14 @@ basic_streambuf* strbuf) ### Parameters -*strbuf*\ +*`strbuf`*\ The stream buffer to become the read buffer. ### Remarks -The protected member function stores *strbuf* in the `stream buffer pointer`.It does not call `clear`. +The protected member function stores *`strbuf`* in the stream buffer pointer. It doesn't call `clear`. -## basic_ios::tie +## `basic_ios::tie` Ensures that one stream is processed before another stream. @@ -833,12 +850,12 @@ basic_ostream* str); ### Parameters -*str*\ +*`str`*\ A stream. ### Return Value -The first member function returns the stored tie pointer. The second member function stores *str* in the tie pointer and returns its previous stored value. +The first member function returns the stored tie pointer. The second member function stores *`str`* in the tie pointer and returns its previous stored value. ### Remarks @@ -846,7 +863,7 @@ The first member function returns the stored tie pointer. The second member func ### Example -In this example, by tying cin to cout, it is guaranteed that the "Enter a number:" string will go to the console before the number itself is extracted from cin. This eliminates the possibility that the "Enter a number:" string is still sitting in the buffer when the number is read, so that we are certain that the user actually has some prompt to respond to. By default, cin and cout are tied. +In the following example, by tying `cin` to `cout`, it's guaranteed that the `Enter a number:` string will go to the console before the number itself is extracted from `cin`. This eliminates the possibility that the "Enter a number:" string is still sitting in the buffer when the number is read, so that we're certain that the user actually has some prompt to respond to. By default, `cin` and `cout` are tied. ```cpp #include @@ -862,7 +879,7 @@ int main( ) } ``` -## basic_ios::traits_type +## `basic_ios::traits_type` A synonym for the template parameter `Traits`. @@ -870,7 +887,7 @@ A synonym for the template parameter `Traits`. typedef Traits traits_type; ``` -## basic_ios::widen +## `basic_ios::widen` Finds the equivalent `char_type` to a given **`char`**. @@ -880,7 +897,7 @@ char_type widen(char Char) const; ### Parameters -*Char*\ +*`Char`*\ The character to convert. ### Return Value @@ -889,7 +906,9 @@ Finds the equivalent `char_type` to a given **`char`**. ### Remarks -The member function returns [use_facet](../standard-library/basic-filebuf-class.md#open)< **ctype**\< **E**> >( [getloc](../standard-library/ios-base-class.md#getloc)). `widen`( `Char`). +The member function returns `use_facet>(getloc).widen(Char)`. + +For more information, see [`use_facet`](../standard-library/basic-filebuf-class.md#open) and [`getloc`](../standard-library/ios-base-class.md#getloc). ### Example @@ -911,9 +930,9 @@ int main( ) } ``` -## basic_ios::swap +## `basic_ios::swap` -Exchanges the values in this `basic_ios` object for those of another `basic_ios` object. However, the pointers to the stream buffers are not swapped. +Exchanges the values in this `basic_ios` object for those of another `basic_ios` object. However, the pointers to the stream buffers aren't swapped. ```cpp void swap(basic_ios&& right); @@ -921,15 +940,15 @@ void swap(basic_ios&& right); ### Parameters -*right*\ +*`right`*\ The `basic_ios` object that is used to exchange values. ### Remarks -The protected member function exchanges all the values stored in *right* with **`*this`** except the stored `stream buffer pointer`. +The protected member function exchanges all the values stored in *`right`* with **`*this`** except the stored `stream buffer pointer`. ## See also [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/basic-istream-class.md b/docs/standard-library/basic-istream-class.md index b049608c13..a5ebefecce 100644 --- a/docs/standard-library/basic-istream-class.md +++ b/docs/standard-library/basic-istream-class.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: basic_istream Class" title: "basic_istream Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_istream Class" +ms.date: 06/10/2022 f1_keywords: ["istream/std::basic_istream", "istream/std::basic_istream::gcount", "istream/std::basic_istream::get", "istream/std::basic_istream::getline", "istream/std::basic_istream::", "istream/std::basic_istream::peek", "istream/std::basic_istream::putback", "istream/std::basic_istream::read", "istream/std::basic_istream::readsome", "istream/std::basic_istream::seekg", "istream/std::basic_istream::sentry", "istream/std::basic_istream::swap", "istream/std::basic_istream::sync", "istream/std::basic_istream::tellg", "istream/std::basic_istream::unget"] helpviewer_keywords: ["std::basic_istream [C++]", "std::basic_istream [C++], gcount", "std::basic_istream [C++], get", "std::basic_istream [C++], getline", "std::basic_istream [C++], OVERWRITE", "std::basic_istream [C++], peek", "std::basic_istream [C++], putback", "std::basic_istream [C++], read", "std::basic_istream [C++], readsome", "std::basic_istream [C++], seekg", "std::basic_istream [C++], sentry", "std::basic_istream [C++], swap", "std::basic_istream [C++], sync", "std::basic_istream [C++], tellg", "std::basic_istream [C++], unget"] -ms.assetid: c7c27111-de6d-42b4-95a3-a7e65259bf17 +ms.custom: devdivchpfy22 --- -# basic_istream Class +# `basic_istream` Class -Describes an object that controls extraction of elements and encoded objects from a stream buffer with elements of type `Char_T`, also known as [char_type](../standard-library/basic-ios-class.md#char_type), whose character traits are determined by the class *Tr*, also known as [traits_type](../standard-library/basic-ios-class.md#traits_type). +Describes an object that controls extraction of elements and encoded objects from a stream buffer with elements of type `Char_T`, also known as [`char_type`](../standard-library/basic-ios-class.md#char_type), whose character traits are determined by the class *`Tr`*, also known as [`traits_type`](../standard-library/basic-ios-class.md#traits_type). ## Syntax @@ -19,7 +19,7 @@ class basic_istream : virtual public basic_ios ## Remarks -Most of the member functions that overload [operator>>](#op_gt_gt) are formatted input functions. They follow the pattern: +Most of the member functions that overload [`operator>>`](#op_gt_gt) are formatted input functions. They follow the pattern: ```cpp iostate state = goodbit; @@ -84,57 +84,57 @@ if (ok) setstate(state); ``` -Both groups of functions call [`setstate`](../standard-library/basic-ios-class.md#setstate)`(eofbit)` if they encounter end of file while extracting elements. +Both groups of functions call `setstate(eofbit)` if they encounter end of file while extracting elements. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). An object of class `basic_istream` stores: -- A virtual public base object of class [`basic_ios`](../standard-library/basic-ios-class.md)``. +- A virtual public base object of class `basic_ios`. For more information, see [`basic_ios`](../standard-library/basic-ios-class.md). - An extraction count for the last unformatted input operation (called `count` in the previous code). ## Example -See the example for [basic_ifstream Class](../standard-library/basic-ifstream-class.md) to learn more about input streams. +See the example for [`basic_ifstream` Class](../standard-library/basic-ifstream-class.md) to learn more about input streams. ### Constructors |Constructor|Description| |-|-| -|[basic_istream](#basic_istream)|Constructs an object of type `basic_istream`.| +|[`basic_istream`](#basic_istream)|Constructs an object of type `basic_istream`.| ### Member functions |Member function|Description| |-|-| -|[gcount](#gcount)|Returns the number of characters read during the last unformatted input.| -|[get](#get)|Reads one or more characters from the input stream.| -|[getline](#getline)|Reads a line from the input stream.| -|[ignore](#ignore)|Causes a number of elements to be skipped from the current read position.| -|[peek](#peek)|Returns the next character to be read.| -|[putback](#putback)|Puts a specified character into the stream.| -|[read](#read)|Reads a specified number of characters from the stream and stores them in an array.| -|[readsome](#readsome)|Read from buffer only.| -|[seekg](#seekg)|Moves the read position in a stream.| -|[sentry](#sentry)|The nested class describes an object whose declaration structures the formatted input functions and the unformatted input functions.| -|[swap](#swap)|Exchanges this `basic_istream` object for the provided `basic_istream` object parameter.| -|[sync](#sync)|Synchronizes the stream's associated input device with the stream's buffer.| -|[tellg](#tellg)|Reports the current read position in the stream.| -|[unget](#unget)|Puts the most recently read character back into the stream.| +|[`gcount`](#gcount)|Returns the number of characters read during the last unformatted input.| +|[`get`](#get)|Reads one or more characters from the input stream.| +|[`getline`](#getline)|Reads a line from the input stream.| +|[`ignore`](#ignore)|Causes a number of elements to be skipped from the current read position.| +|[`peek`](#peek)|Returns the next character to be read.| +|[`putback`](#putback)|Puts a specified character into the stream.| +|[`read`](#read)|Reads a specified number of characters from the stream and stores them in an array.| +|[`readsome`](#readsome)|Read from buffer only.| +|[`seekg`](#seekg)|Moves the read position in a stream.| +|[`sentry`](#sentry)|The nested class describes an object whose declaration structures the formatted input functions and the unformatted input functions.| +|[`swap`](#swap)|Exchanges this `basic_istream` object for the provided `basic_istream` object parameter.| +|[`sync`](#sync)|Synchronizes the stream's associated input device with the stream's buffer.| +|[`tellg`](#tellg)|Reports the current read position in the stream.| +|[`unget`](#unget)|Puts the most recently read character back into the stream.| ### Operators |Operator|Description| |-|-| -|[operator>>](#op_gt_gt)|Calls a function on the input stream or reads formatted data from the input stream.| -|[operator=](#op_eq)|Assigns the `basic_istream` on the right side of the operator to this object. It's a move assignment involving an `rvalue` reference that doesn't leave a copy behind.| +|[`operator>>`](#op_gt_gt)|Calls a function on the input stream or reads formatted data from the input stream.| +|[`operator=`](#op_eq)|Assigns the `basic_istream` on the right side of the operator to this object. It's a move assignment involving an `rvalue` reference that doesn't leave a copy behind.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_istream::basic_istream +## `basic_istream::basic_istream` Constructs an object of type `basic_istream`. @@ -148,26 +148,26 @@ basic_istream(basic_istream&& right); ### Parameters -*strbuf*\ +*`strbuf`*\ An object of type [basic_streambuf](../standard-library/basic-streambuf-class.md). -*_Isstd*\ +*`_Isstd`*\ **`true`** if it's a standard stream; otherwise, **`false`**. -*right*\ +*`right`*\ A `basic_istream` object to copy. ### Remarks -The first constructor initializes the base class by calling [`init`](../standard-library/basic-ios-class.md#init)`(strbuf)`. It also stores zero in the extraction count. For more information about this extraction count, see the Remarks section of the [basic_istream Class](../standard-library/basic-istream-class.md) overview. +The first constructor initializes the base class by calling `init(strbuf)`. It also stores zero in the extraction count. For more information, see [`init`](../standard-library/basic-ios-class.md#init). And for more information about this extraction count, see the Remarks section of the [`basic_istream` Class](../standard-library/basic-istream-class.md) overview. -The second constructor initializes the base class by calling `move(right)`. It also stores `right.gcount()` in the extraction count and stores zero in the extraction count for *right**. +The second constructor initializes the base class by calling `move(right)`. It also stores `right.gcount()` in the extraction count and stores zero in the extraction count for *`right`*. ### Example -See the example for [basic_ifstream::basic_ifstream](../standard-library/basic-ifstream-class.md#basic_ifstream) to learn more about input streams. +See the example for [`basic_ifstream::basic_ifstream`](../standard-library/basic-ifstream-class.md#basic_ifstream) to learn more about input streams. -## basic_istream::gcount +## `basic_istream::gcount` Returns the number of characters read during the last unformatted input. @@ -181,7 +181,7 @@ The extraction count. ### Remarks -Use [basic_istream::get](#get) to read unformatted characters. +Use [`basic_istream::get`](#get) to read unformatted characters. ### Example @@ -214,7 +214,7 @@ Type the letter 'a': a 1 ``` -## basic_istream::get +## `basic_istream::get` Reads one or more characters from the input stream. @@ -231,46 +231,46 @@ basic_istream& get(basic_streambuf& strbuf, Char_T delim ### Parameters -*count*\ -The number of characters to read from *strbuf*. +*`count`*\ +The number of characters to read from *`strbuf`*. -*delimiter*\ -The character that should terminate the read if it's encountered before *count*. +*`delimiter`*\ +The character that should terminate the read if it's encountered before *`count`*. -*str*\ +*`str`*\ A string in which to write. -*Ch*\ +*`Ch`*\ A character to get. -*strbuf*\ +*`strbuf`*\ A buffer in which to write. ### Return Value -The parameterless form of get returns the element read as an integer or end of file. The remaining forms return the stream (* **`this`**). +The parameterless form of `get` returns the element read as an integer or end of file. The remaining forms return the stream (**`*this`**). ### Remarks -The first unformatted input function extracts an element, if possible, as if by returning `rdbuf->sbumpc`. Otherwise, it returns `traits_type::`[`eof`](../standard-library/char-traits-struct.md#eof). If the function extracts no element, it calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. +The first unformatted input function extracts an element, if possible, as if by returning `rdbuf->sbumpc`. Otherwise, it returns `traits_type::`[`eof`](../standard-library/char-traits-struct.md#eof). If the function extracts no element, it calls `setstate(failbit)`. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). -The second function extracts the [int_type](../standard-library/basic-ios-class.md#int_type) element `meta` the same way. If `meta` compares equal to `traits_type::eof`, the function calls `setstate(failbit)`. Otherwise, it stores `traits_type::`[`to_char_type`](../standard-library/char-traits-struct.md#to_char_type)`(meta)` in *Ch*. The function returns __*this__. +The second function extracts the [`int_type`](../standard-library/basic-ios-class.md#int_type) element `meta` the same way. If `meta` compares equal to `traits_type::eof`, the function calls `setstate(failbit)`. Otherwise, it stores `traits_type::to_char_type(meta)` in *`Ch`*. The function returns `*this`. For more information, see [`to_char_type`](../standard-library/char-traits-struct.md#to_char_type). The third function returns `get(str, count, widen('\n'))`. -The fourth function extracts up to `count - 1` elements and stores them in the array beginning at *str*. It always stores `char_type` after any extracted elements it stores. In order of testing, extraction stops: +The fourth function extracts up to `count - 1` elements and stores them in the array beginning at *`str`*. It always stores `char_type` after any extracted elements it stores. In order of testing, extraction stops: - At end of file. -- After the function extracts an element that compares equal to *delimiter*. In this case, the element is put back to the controlled sequence. +- After the function extracts an element that compares equal to *`delimiter`*. In this case, the element is put back to the controlled sequence. - After the function extracts `count - 1` elements. -If the function extracts no elements, it calls `setstate(failbit)`. In any case, it returns __*this__. +If the function extracts no elements, it calls `setstate(failbit)`. In any case, it returns `*this`. The fifth function returns `get(strbuf, widen('\n'))`. -The sixth function extracts elements and inserts them in *strbuf*. Extraction stops on end-of-file or on an element that compares equal to *delimiter*, which is not extracted. It also stops, without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls `setstate(failbit)`. In any case, the function returns __*this__. +The sixth function extracts elements and inserts them in *`strbuf`*. Extraction stops on end-of-file or on an element that compares equal to *`delimiter`*, which isn't extracted. It also stops, without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls `setstate(failbit)`. In any case, the function returns `*this`. ### Example @@ -297,7 +297,7 @@ int main( ) 1111 ``` -## basic_istream::getline +## `basic_istream::getline` Gets a line from the input stream. @@ -314,32 +314,32 @@ basic_istream& getline( ### Parameters -*count*\ -The number of characters to read from *strbuf*. +*`count`*\ +The number of characters to read from *`strbuf`*. -*delimiter*\ -The character that should terminate the read if it's encountered before *count*. +*`delimiter`*\ +The character that should terminate the read if it's encountered before *`count`*. -*str*\ +*`str`*\ A string in which to write. ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks The first of these unformatted input functions returns `getline(str, count, widen('\n'))`. -The second function extracts up to `count - 1` elements and stores them in the array beginning at *str*. It always stores the string termination character after any extracted elements it stores. In order of testing, extraction stops: +The second function extracts up to `count - 1` elements and stores them in the array beginning at *`str`*. It always stores the string termination character after any extracted elements it stores. In order of testing, extraction stops: - At end of file. -- After the function extracts an element that compares equal to *delimiter*. In this case, the element isn't put back, and it's not appended to the controlled sequence. +- After the function extracts an element that compares equal to *`delimiter`*. In this case, the element isn't put back, and it's not appended to the controlled sequence. - After the function extracts `count - 1` elements. -If the function extracts no elements or `count - 1` elements, it calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. In any case, it returns __*this__. +If the function extracts no elements or `count - 1` elements, it calls `setstate(failbit)`. In any case, it returns `*this`. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -362,7 +362,7 @@ int main( ) 121 ``` -## basic_istream::ignore +## `basic_istream::ignore` Causes a number of elements to be skipped from the current read position. @@ -374,19 +374,19 @@ basic_istream& ignore( ### Parameters -*count*\ +*`count`*\ The number of elements to skip from the current read position. -*delimiter*\ -The element that, if encountered before count, causes `ignore` to return and allowing all elements after *delimiter* to be read. +*`delimiter`*\ +The element that, if encountered before count, causes `ignore` to return and allowing all elements after *`delimiter`* to be read. ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks -The unformatted input function extracts up to *count* elements and discards them. If *count* equals `numeric_limits::max`, however, it's taken as arbitrarily large. Extraction stops early on end of file or on an element `Ch` such that `traits_type::`[`to_int_type`](../standard-library/char-traits-struct.md#to_int_type)`(Ch)` compares equal to *delimiter* (which is also extracted). The function returns __*this__. +The unformatted input function extracts up to *`count`* elements and discards them. If *`count`* equals `numeric_limits::max`, however, it's taken as arbitrarily large. Extraction stops early on end of file or on an element `Ch` such that `traits_type::to_int_type(Ch)` compares equal to *`delimiter`* (which is also extracted). The function returns `*this`. For more information, see [`to_int_type`](../standard-library/char-traits-struct.md#to_int_type). ### Example @@ -410,7 +410,7 @@ Type 'abcdef': abcdef def ``` -## basic\_istream::operator>> +## `basic_istream::operator>>` Calls a function on the input stream or reads formatted data from the input stream. @@ -436,24 +436,26 @@ basic_istream& operator>>(long double& val); ### Parameters -*Pfn*\ +*`Pfn`*\ A function pointer. -*strbuf*\ +*`strbuf`*\ An object of type `stream_buf`. -*val*\ +*`val`*\ The value to read from the stream. ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks -The \ header also defines several global extraction operators. For more information, see [operator>> (\)](../standard-library/istream-operators.md#op_gt_gt). +The `` header also defines several global extraction operators. For more information, see [`operator>> ()`](../standard-library/istream-operators.md#op_gt_gt). -The first member function ensures that an expression of the form `istr >> ws` calls [`ws`](../standard-library/istream-functions.md#ws)`(istr)`, and then returns __*this__. The second and third functions ensure that other manipulators, such as [`hex`](../standard-library/ios-functions.md#hex), behave similarly. The remaining functions are the formatted input functions. +The first member function ensures that an expression of the form `istr >> ws` calls `ws(istr)`, and then returns `*this`. For more information, see [`ws`](../standard-library/istream-functions.md#ws). + +The second and third functions ensure that other manipulators, such as [`hex`](../standard-library/ios-functions.md#hex), behave similarly. The remaining functions are the formatted input functions. The function: @@ -462,7 +464,7 @@ basic_istream& operator>>( basic_streambuf* strbuf); ``` -extracts elements, if *strbuf* isn't a null pointer, and inserts them in *strbuf*. Extraction stops on end of file. It also stops without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. In any case, the function returns __*this__. +extracts elements, if *`strbuf`* isn't a null pointer, and inserts them in *`strbuf`*. Extraction stops on end of file. It also stops without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls `setstate(failbit)`. In any case, the function returns `*this`. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). The function: @@ -470,7 +472,9 @@ The function: basic_istream& operator>>(bool& val); ``` -extracts a field and converts it to a Boolean value by calling [`use_facet`](../standard-library/basic-filebuf-class.md#open)`< num_get(`[`getloc`](../standard-library/ios-base-class.md#getloc)`).`[`get`](../standard-library/ios-base-class.md#getloc)`( InIt(`[`rdbuf`](../standard-library/basic-ios-class.md#rdbuf)`), Init(0), *this, getloc, val)`. Here, `InIt` is defined as [`istreambuf_iterator`](../standard-library/istreambuf-iterator-class.md)``. The function returns __*this__. +extracts a field and converts it to a Boolean value by calling `use_facet< num_get(getloc).get( InIt(rdbuf), Init(0), *this, getloc, val)`. Here, `InIt` is defined as `istreambuf_iterator`. The function returns `*this`. + +For more information, see [`use_facet`](../standard-library/basic-filebuf-class.md#open), [`getloc`](../standard-library/ios-base-class.md#getloc), [`get`](#get), [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf), and [`istreambuf_iterator`](../standard-library/istreambuf-iterator-class.md). Each of the functions: @@ -486,9 +490,9 @@ basic_istream& operator>>(unsigned long long& val); basic_istream& operator>>(void *& val); ``` -extract a field and convert it to a numeric value by calling `use_facet(getloc).`[`get`](#get)`(InIt(rdbuf), Init(0), *this, getloc, val)`. Here, `InIt` is defined as `istreambuf_iterator`, and *val* has type **`long`**, **`unsigned long`**, or **`void`** \* as needed. +extract a field and convert it to a numeric value by calling `use_facet(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val)`. Here, `InIt` is defined as `istreambuf_iterator`, and *`val`* has type **`long`**, **`unsigned long`**, or **`void *`** as needed. -If the converted value can't be represented as the type of *val*, the function calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. In any case, the function returns __*this__. +If the converted value can't be represented as the type of *`val`*, the function calls `setstate(failbit)`. In any case, the function returns `*this`. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). Each of the functions: @@ -498,9 +502,9 @@ basic_istream& operator>>(double& val); basic_istream& operator>>(long double& val); ``` -extract a field and convert it to a numeric value by calling `use_facet(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val)`. Here, `InIt` is defined as `istreambuf_iterator`, and *val* has type **`double`** or **`long double`** as needed. +extract a field and convert it to a numeric value by calling `use_facet(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val)`. Here, `InIt` is defined as `istreambuf_iterator`, and *`val`* has type **`double`** or **`long double`** as needed. -If the converted value can't be represented as the type of *val*, the function calls `setstate(failbit)`. In any case, it returns __*this__. +If the converted value can't be represented as the type of *`val`*, the function calls `setstate(failbit)`. In any case, it returns `*this`. ### Example @@ -539,7 +543,7 @@ int main( ) } ``` -## basic_istream::operator= +## `basic_istream::operator=` Assigns the `basic_istream` on the right side of the operator to this object. It's a move assignment involving an `rvalue` reference that doesn't leave a copy behind. @@ -549,18 +553,18 @@ basic_istream& operator=(basic_istream&& right); ### Parameters -*right*\ +*`right`*\ An `rvalue` reference to a `basic_ifstream` object. ### Return Value -Returns __*this__. +Returns `*this`. ### Remarks The member operator calls `swap(right)`. -## basic_istream::peek +## `basic_istream::peek` Returns the next character to be read. @@ -574,7 +578,7 @@ The next character that will be read. ### Remarks -The unformatted input function extracts an element, if possible, as if by returning `rdbuf->`[`sgetc`](../standard-library/basic-streambuf-class.md#sgetc). Otherwise, it returns `traits_type::`[`eof`](../standard-library/char-traits-struct.md#eof). +The unformatted input function extracts an element, if possible, as if by returning `rdbuf->sgetc`. Otherwise, it returns `traits_type::eof`. For more information, see [`sgetc`](../standard-library/basic-streambuf-class.md#sgetc) and [`eof`](../standard-library/char-traits-struct.md#eof). ### Example @@ -605,7 +609,7 @@ Type 'abcde': abcde a abcde ``` -## basic_istream::putback +## `basic_istream::putback` Puts a specified character into the stream. @@ -616,16 +620,18 @@ basic_istream& putback( ### Parameters -*Ch*\ +*`Ch`*\ A character to put back into the stream. ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks -The [unformatted input function](../standard-library/basic-istream-class.md) puts back *Ch*, if possible, as if by calling [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf)`->`[`sputbackc`](../standard-library/basic-streambuf-class.md#sputbackc). If `rdbuf` is a null pointer, or if the call to `sputbackc` returns `traits_type::`[`eof`](../standard-library/char-traits-struct.md#eof), the function calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(badbit)`. In any case, it returns __*this__. +The [unformatted input function](../standard-library/basic-istream-class.md) puts back *`Ch`*, if possible, as if by calling `rdbuf->sputbackc`. If `rdbuf` is a null pointer, or if the call to `sputbackc` returns `traits_type::eof`, the function calls `setstate(badbit)`. In any case, it returns `*this`. + +For more information, see [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf), [`sputbackc`](../standard-library/basic-streambuf-class.md#sputbackc), [`eof`](../standard-library/char-traits-struct.md#eof), and [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -651,7 +657,7 @@ int main( ) qwq ``` -## basic_istream::read +## `basic_istream::read` Reads a specified number of characters from the stream and stores them in an array. @@ -665,10 +671,10 @@ basic_istream& read( ### Parameters -*str*\ +*`str`*\ The array in which to read the characters. -*count*\ +*`count`*\ The number of characters to read. ### Return Value @@ -677,7 +683,7 @@ The stream ( **`*this`**). ### Remarks -The unformatted input function extracts up to *count* elements and stores them in the array beginning at *str*. Extraction stops early on end of file, in which case the function calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. In any case, it returns __*this__. +The unformatted input function extracts up to *`count`* elements and stores them in the array beginning at *`str`*. Extraction stops early on end of file, in which case the function calls `setstate(failbit)`. In any case, it returns `*this`. For more information, see [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -712,7 +718,7 @@ Type 'abcde': abcde abcde ``` -## basic_istream::readsome +## `basic_istream::readsome` Reads the specified number of character values. @@ -726,10 +732,10 @@ streamsize readsome( ### Parameters -*str*\ +*`str`*\ The array in which `readsome` stores the characters it reads. -*count*\ +*`count`*\ The number of characters to read. ### Return Value @@ -738,9 +744,9 @@ The number of characters actually read, [`gcount`](#gcount). ### Remarks -This unformatted input function extracts up to *count* elements from the input stream and stores them in the array *str*. +This unformatted input function extracts up to *`count`* elements from the input stream and stores them in the array *`str`*. -This function does not wait for input. It reads whatever data is available. +This function doesn't wait for input. It reads whatever data is available. ### Example @@ -771,7 +777,7 @@ int main( ) } ``` -## basic_istream::seekg +## `basic_istream::seekg` Moves the read position in a stream. @@ -783,18 +789,18 @@ basic_istream& seekg(off_type off, ios_base::seekdir way); ### Parameters -*pos*\ +*`pos`*\ The absolute position in which to move the read pointer. -*off*\ -An offset to move the read pointer relative to *way*. +*`off`*\ +An offset to move the read pointer relative to *`way`*. -*way*\ -One of the [ios_base::seekdir](../standard-library/ios-base-class.md#seekdir) enumerations. +*`way`*\ +One of the [`ios_base::seekdir`](../standard-library/ios-base-class.md#seekdir) enumerations. ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks @@ -803,9 +809,11 @@ The first member function performs an absolute seek, the second member function > [!NOTE] > Do not use the second member function with text files, because Standard C++ does not support relative seeks in text files. -If [`fail`](../standard-library/basic-ios-class.md#fail) is false, the first member function calls `newpos =` [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf)`->`[`pubseekpos`](../standard-library/basic-streambuf-class.md#pubseekpos)`(pos)`, for some `pos_type` temporary object `newpos`. If `fail` is false, the second function calls `newpos = rdbuf->`[`pubseekoff`](../standard-library/basic-streambuf-class.md#pubseekoff)`( off, way)`. In either case, if `(off_type)newpos == (off_type)(-1)` (the positioning operation fails), the function calls `istr.`[`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. Both functions return __*this__. +If [`fail`](../standard-library/basic-ios-class.md#fail) is `false`, the first member function calls `newpos = rdbuf->pubseekpos(pos)`, for some `pos_type` temporary object `newpos`. If `fail` is `false`, the second function calls `newpos = rdbuf->pubseekoff( off, way)`. In either case, if `(off_type)newpos == (off_type)(-1)` (the positioning operation fails), the function calls `istr.setstate(failbit)`. Both functions return `*this`. + +If [`fail`](../standard-library/basic-ios-class.md#fail) is `true`, the member functions do nothing. -If [`fail`](../standard-library/basic-ios-class.md#fail) is true, the member functions do nothing. +For more information, see [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf), [`pubseekpos`](../standard-library/basic-streambuf-class.md#pubseekpos), [`pubseekoff`](../standard-library/basic-streambuf-class.md#pubseekoff), and [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -828,7 +836,7 @@ int main ( ) } ``` -## basic_istream::sentry +## `basic_istream::sentry` The nested class describes an object whose declaration structures the formatted and unformatted input functions. @@ -844,15 +852,17 @@ class sentry { ### Remarks -If `_Istr.`[`good`](../standard-library/basic-ios-class.md#good) is true, the constructor: +If `_Istr.good` is `true`, the constructor: + +- Calls `_Istr.tie->flush` if `_Istr.tie` isn't a null pointer. -- Calls `_Istr.`[`tie`](../standard-library/basic-ios-class.md#tie)`->`[`flush`](../standard-library/basic-ostream-class.md#flush) if `_Istr.tie` is not a null pointer. +- Effectively calls `ws(_Istr)` if `_Istr.flags & skipws` is nonzero. -- Effectively calls [`ws`](../standard-library/istream-functions.md#ws)`(_Istr)` if `_Istr.`[`flags`](../standard-library/ios-base-class.md#flags) `&` [`skipws`](../standard-library/ios-functions.md#skipws) is nonzero. +If after any such preparation, `_Istr.good` is `false`, the constructor calls `_Istr.setstate(failbit)`. In any case, the constructor stores the value returned by `_Istr.good` in `status`. A later call to `operator bool` delivers this stored value. -If after any such preparation, `_Istr.good` is false, the constructor calls `_Istr.`[`setstate`](../standard-library/basic-ios-class.md#setstate)`(failbit)`. In any case, the constructor stores the value returned by `_Istr.good` in `status`. A later call to `operator bool` delivers this stored value. +For more information, see [`good`](../standard-library/basic-ios-class.md#good), [`tie`](../standard-library/basic-ios-class.md#tie), [`flush`](../standard-library/basic-ostream-class.md#flush), [`ws`](../standard-library/istream-functions.md#ws), [`flags`](../standard-library/ios-base-class.md#flags), [`skipws`](../standard-library/ios-functions.md#skipws), and [`setstate`](../standard-library/basic-ios-class.md#setstate). -## basic_istream::swap +## `basic_istream::swap` Exchanges the contents of two `basic_istream` objects. @@ -862,14 +872,14 @@ void swap(basic_istream& right); ### Parameters -*right*\ -An lvalue reference to a `basic_istream` object. +*`right`*\ +An `lvalue` reference to a `basic_istream` object. ### Remarks -The member function calls [`basic_ios::swap`](../standard-library/basic-ios-class.md#swap)`(right)`. It also exchanges the extraction count with the extraction count for *right*. +The member function calls `basic_ios::swap(right)`. It also exchanges the extraction count with the extraction count for *`right`*. For more information, see [`basic_ios::swap`](../standard-library/basic-ios-class.md#swap). -## basic_istream::sync +## `basic_istream::sync` Synchronizes the stream's associated input device with the stream's buffer. @@ -879,9 +889,9 @@ int sync(); ### Return Value -If [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf) is a null pointer, the function returns -1. Otherwise, it calls `rdbuf->`[`pubsync`](../standard-library/basic-streambuf-class.md#pubsync). If that call returns -1, the function calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(badbit)` and returns -1. Otherwise, the function returns zero. +If [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf) is a null pointer, the function returns -1. Otherwise, it calls `rdbuf->pubsync`. If that call returns -1, the function calls `setstate(badbit)` and returns -1. Otherwise, the function returns zero. For more information, see [`pubsync`](../standard-library/basic-streambuf-class.md#pubsync) and [`setstate`](../standard-library/basic-ios-class.md#setstate). -## basic_istream::tellg +## `basic_istream::tellg` Reports the current read position in the stream. @@ -895,7 +905,7 @@ The current position in the stream. ### Remarks -If [`fail`](../standard-library/basic-ios-class.md#fail) is false, the member function returns [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf)`->`[`pubseekoff`](../standard-library/basic-streambuf-class.md#pubseekoff)`(0, cur, in)`. Otherwise, it returns `pos_type(-1)`. +If [`fail`](../standard-library/basic-ios-class.md#fail) is `false`, the member function returns `rdbuf->pubseekoff(0, cur, in)`. Otherwise, it returns `pos_type(-1)`. For more information, see [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf) and [`pubseekoff`](../standard-library/basic-streambuf-class.md#pubseekoff). ### Example @@ -923,7 +933,7 @@ int main() } ``` -## basic_istream::unget +## `basic_istream::unget` Puts the most recently read character back into the stream. @@ -933,13 +943,13 @@ basic_istream& unget(); ### Return Value -The stream (__*this__). +The stream (`*this`). ### Remarks -The [unformatted input function](../standard-library/basic-istream-class.md) puts back the previous element in the stream, if possible, as if by calling `rdbuf->`[`sungetc`](../standard-library/basic-streambuf-class.md#sungetc). If [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf) is a null pointer, or if the call to `sungetc` returns `traits_type::`[`eof`](../standard-library/basic-ios-class.md#eof), the function calls [`setstate`](../standard-library/basic-ios-class.md#setstate)`(badbit)`. In any case, it returns __*this__. +The [unformatted input function](../standard-library/basic-istream-class.md) puts back the previous element in the stream, if possible, as if by calling `rdbuf->sungetc` If [`rdbuf`](../standard-library/basic-ios-class.md#rdbuf) is a null pointer, or if the call to `sungetc` returns `traits_type::eof`, the function calls `setstate(badbit)`. In any case, it returns `*this`. -For information on how `unget` might fail, see [`basic_streambuf::sungetc`](../standard-library/basic-streambuf-class.md#sungetc). +For more information, see [`sungetc`](../standard-library/basic-streambuf-class.md#sungetc), [`eof`](../standard-library/basic-ios-class.md#eof), and [`setstate`](../standard-library/basic-ios-class.md#setstate). And for information on how `unget` might fail, see [`basic_streambuf::sungetc`](../standard-library/basic-streambuf-class.md#sungetc). ### Example @@ -973,5 +983,5 @@ abc ## See also [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/basic-istream-view-class.md b/docs/standard-library/basic-istream-view-class.md new file mode 100644 index 0000000000..bac05a4dd9 --- /dev/null +++ b/docs/standard-library/basic-istream-view-class.md @@ -0,0 +1,214 @@ +--- +title: basic_istream_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) basic_istream_view class, which reads (using operator>>) successive elements from an input stream. Also includes the istream_view and wistream_view specializations." +ms.date: 11/07/2022 +f1_keywords: ["ranges/std::basic_istream_view", "ranges/std::istream_view", "ranges/std::wistream_view", "ranges/std::basic_istream_view::begin", "ranges/std::basic_istream_view::end", "ranges/std::istream_view::begin", "ranges/std::istream_view::end", "ranges/std::wistream_view::begin", "ranges/std::wistream_view::end"] +helpviewer_keywords: ["std::ranges::basic_istream_view [C++]", "std::ranges::istream_view [C++]", "std::ranges::wistream_view [C++]", "std::ranges::basic_istream_view::base [C++]", "std::ranges::basic_istream_view::begin [C++]", "std::ranges::basic_istream_view::end [C++]", ] +dev_langs: ["C++"] +--- +# `basic_istream_view` class (C++ Standard Library) + +A view of successive elements from an input stream. + +## Syntax + +```cpp +template + requires default_initializable && + stream_extractable +class basic_istream_view : public view_interface>; +``` + +### Template parameters + +*`CharT`*\ +The character type of the stream. + +*`Traits`*\ +Optional. Provides details about the character type of the stream regarding comparing characters, determining the length of a string made up of that character type, and so on. An example trait is [`char_traits`](char-traits-wchar-t-struct.md). If not specified, defaults to `char_traits`. + +*`Val`*\ +The type of the elements to extract. For example, `double` given a stream of: `"1.1 2.2 3.3"` + +`stream_extractable` refers to the requirement (concept) that the type `Val` can be extracted from a stream using the `operator>>` function. It's equivalent to: + +```cpp +template +concept stream_extractable = + requires(std::basic_istream& is, Val& t) { + is >> t; + }; +``` + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`istream`](range-adaptors.md#istream) | +| **Underlying range** | None | +| **Element type** |The same as `Val` | +| **View iterator category** | [`input_range`](range-concepts.md#input_range) | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | No | +| **Borrowed range** | No | + +## Specializations:`istream_view` and `wistream_view` + +Convenience alias templates are provided for `char` and `wchar_t` streams, as follows: + +```cpp +1) template +using istream_view = ranges::basic_istream_view; + +2) template +using wistream_view = ranges::basic_istream_view; +``` + +1\) Reads elements from an input stream composed of `char` characters.\ +2\) Reads elements from an input stream composed of `wchar_t` characters. + +For 1) and 2), `Val` refers to the type of the elements to extract. For example, `Val` is `double` given a stream of: `"1.1 2.2 3.3"` + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `basic_istream_view`. | +| [`begin`](#begin)C++20 | Read the first value and get an iterator for the view. | +| [`end`](#end)C++20 | Returns `std::default_sentinel` | + +No member functions are inherited from `view_interface`. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `basic_istream_view`. + +```cpp +constexpr explicit +basic_istream_view(std::basic_istream& stream); +``` + +### Parameters + +*`stream`*\ +The stream to read from. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `basic_istream_view` instance. The `basic_istream_view` internal stream pointer is initialized to `addressof(stream)`. + +### Remarks + +The best way to create a `basic_istream_view` is by using the [`views::istream`](range-adaptors.md#istream) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +### Example: `basic_istream_view`, `istream_view`, and `wistream_view` + +```cpp +// requires /std:c++20, or later +#include +#include +#include + +int main() +{ + // range adaptor + std::istringstream streamOfdoubles{ "1.1 2.2 3.3 4.4 5.5" }; + for (const auto& elem : std::views::istream(streamOfdoubles)) + { + std::cout << elem << ' '; // 1.1 2.2 3.3 4.4 5.5 + } + std::cout << '\n'; + + // range adaptor - create a wistream_view + std::wistringstream streamOfInts{ L"1 2 3 4 5" }; + for (const auto& elem : std::views::istream(streamOfInts)) + { + std::cout << elem << ' '; // 1 2 3 4 5 + } + std::cout << '\n'; + + // istream_view alias + std::istringstream cpu1{ "8 0 8 0" }; + // equivalent std::ranges::istream_view + for (const auto& elem : std::ranges::istream_view{cpu1}) + { + std::cout << elem; // 8080 + } + std::cout << '\n'; + + // wistream_view alias + std::wistringstream cpu2{ L"6 5 0 2" }; + // equivalent std::ranges::istream_view + for (const auto& elem : std::ranges::wistream_view{cpu2}) + { + std::cout << elem; // 6502 + } + std::cout << '\n'; + + // specify all template arguments + std::wistringstream misc(L"S T L"); + std::ranges::basic_istream_view> basic{misc}; + for (const auto& elem : basic) + { + std::wcout << elem << ' '; // S T L + } +} +``` + +```output +1.1 2.2 3.3 4.4 5.5 +1 2 3 4 5 +8080 +6502 +S T L +``` + +## `begin` + +Read the first value and get an iterator to the view. + +```cpp +constexpr auto begin(); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `basic_istream_view`. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr std::default_sentinel_t end() const noexcept; +``` + +### Parameters + +None. + +### Return value + +`default_sentinel_t` + +## See also + +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/basic-istringstream-class.md b/docs/standard-library/basic-istringstream-class.md index 170980afac..18872277c2 100644 --- a/docs/standard-library/basic-istringstream-class.md +++ b/docs/standard-library/basic-istringstream-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: basic_istringstream Class" title: "basic_istringstream Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_istringstream Class" +ms.date: 06/10/2022 f1_keywords: ["sstream/std::basic_istringstream", "sstream/std::basic_istringstream::allocator_type", "sstream/std::basic_istringstream::rdbuf", "sstream/std::basic_istringstream::str", "sstream/std::basic_istringstream::swap"] helpviewer_keywords: ["std::basic_istringstream [C++]", "std::basic_istringstream [C++], allocator_type", "std::basic_istringstream [C++], rdbuf", "std::basic_istringstream [C++], str", "std::basic_istringstream [C++], swap"] -ms.assetid: 1d5bb4b5-793d-4833-98e5-14676c451915 +ms.custom: devdivchpfy22 --- + # basic_istringstream Class Describes an object that controls extraction of elements and encoded objects from a stream buffer of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. @@ -50,7 +51,7 @@ The class template describes an object that controls extraction of elements and |-|-| |[rdbuf](#rdbuf)|Returns the address of the stored stream buffer of type `pointer` to [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< `Elem`, `Tr`, `Alloc`>.| |[str](#str)|Sets or gets the text in a string buffer without changing the write position.| -|[swap](#swap)|Exchanges the values in this `basic_istringstream` object for those of the provided object.| +|[swap](#swap)|Exchanges the values in this `basic_istringstream` object for the provided object.| ### Operators @@ -101,9 +102,9 @@ An rvalue reference of a `basic_istringstream` object. ### Remarks -The first constructor initializes the base class by calling [basic_istream](../standard-library/basic-istream-class.md)(`sb`), where `sb` is the stored object of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< `Elem`, `Tr`, `Alloc`>. It also initializes `sb` by calling `basic_stringbuf`< `Elem`, `Tr`, `Alloc`>( `_Mode` | `ios_base::in`). +The first constructor initializes the base class by calling `basic_istream]( sb )`, where `sb` is the stored object of class `basic_stringbuf< Elem, Tr, Alloc>`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( _Mode | ios_base::in )`. For more information, see [`basic_istream`](../standard-library/basic-istream-class.md) and [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md). -The second constructor initializes the base class by calling `basic_istream(sb)`. It also initializes `sb` by calling `basic_stringbuf`< `Elem`, `Tr`, `Alloc`>( `str`, `_Mode` | `ios_base::in`). +The second constructor initializes the base class by calling `basic_istream( sb )`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( str, _Mode | ios_base::in )`. The third constructor initializes the object with the contents of *right*, treated as an rvalue reference. @@ -158,11 +159,11 @@ The new string. ### Return Value -Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by **\*this**. +Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by `*this`. ### Remarks -The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**( `_Newstr`). +The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**(`_Newstr`). ### Example diff --git a/docs/standard-library/basic-ofstream-class.md b/docs/standard-library/basic-ofstream-class.md index 131bb5f0bc..c25617fa4e 100644 --- a/docs/standard-library/basic-ofstream-class.md +++ b/docs/standard-library/basic-ofstream-class.md @@ -1,14 +1,15 @@ --- description: "Learn more about: basic_ofstream Class" title: "basic_ofstream Class" -ms.date: "11/04/2016" +ms.date: 06/10/2022 f1_keywords: ["fstream/std::basic_ofstream", "fstream/std::basic_ofstream::close", "fstream/std::basic_ofstream::is_open", "fstream/std::basic_ofstream::open", "fstream/std::basic_ofstream::rdbuf", "fstream/std::basic_ofstream::swap"] helpviewer_keywords: ["std::basic_ofstream [C++]", "std::basic_ofstream [C++], close", "std::basic_ofstream [C++], is_open", "std::basic_ofstream [C++], open", "std::basic_ofstream [C++], rdbuf", "std::basic_ofstream [C++], swap"] -ms.assetid: 3bcc9c51-6dfc-4844-8fcc-22ef57c9dff1 +ms.custom: devdivchpfy22 --- -# basic_ofstream Class -Describes an object that controls insertion of elements and encoded objects into a stream buffer of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>, with elements of type `Elem`, whose character traits are determined by the class `Tr`. +# `basic_ofstream` Class + +Describes an object that controls insertion of elements and encoded objects into a stream buffer of class `basic_filebuf< Elem, Tr>`, with elements of type `Elem`, whose character traits are determined by the class `Tr`. For more information, see [`basic_filebuf`](../standard-library/basic-filebuf-class.md). ## Syntax @@ -19,17 +20,17 @@ class basic_ofstream : public basic_ostream ### Parameters -*Elem*\ +*`Elem`*\ The basic element of the file buffer. -*Tr*\ -The traits of the basic element of the file buffer (usually `char_traits`< `Elem`>). +*`Tr`*\ +The traits of the basic element of the file buffer (usually `char_traits`). ## Remarks -When the **`wchar_t`** specialization of `basic_ofstream` writes to the file, if the file is opened in text mode it will write a MBCS sequence. The internal representation will use a buffer of **`wchar_t`** characters. +When the **`wchar_t`** specialization of `basic_ofstream` writes to the file, if the file is opened in text mode it will write an MBCS sequence. The internal representation will use a buffer of **`wchar_t`** characters. -The object stores an object of class `basic_filebuf`< `Elem`, `Tr`>. +The object stores an object of class `basic_filebuf< Elem, Tr>`. ## Example @@ -57,31 +58,31 @@ int main(int argc, char **argv) |Constructor|Description| |-|-| -|[basic_ofstream](#basic_ofstream)|Creates an object of type `basic_ofstream`.| +|[`basic_ofstream`](#basic_ofstream)|Creates an object of type `basic_ofstream`.| ### Member functions |Member function|Description| |-|-| -|[close](#close)|Closes a file.| -|[is_open](#is_open)|Determines if a file is open.| -|[open](#open)|Opens a file.| -|[rdbuf](#rdbuf)|Returns the address of the stored stream buffer.| -|[swap](#swap)|Exchange the contents of this `basic_ofstream` for the contents of the provided `basic_ofstream`.| +|[`close`](#close)|Closes a file.| +|[`is_open`](#is_open)|Determines if a file is open.| +|[`open`](#open)|Opens a file.| +|[`rdbuf`](#rdbuf)|Returns the address of the stored stream buffer.| +|[`swap`](#swap)|Exchange the contents of this `basic_ofstream` for the contents of the provided `basic_ofstream`.| ### Operators |Operator|Description| |-|-| -|[operator=](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that does not leave a copy behind.| +|[`operator=`](#op_eq)|Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that doesn't leave a copy behind.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_ofstream::basic_ofstream +## `basic_ofstream::basic_ofstream` Creates an object of type `basic_ofstream`. @@ -104,25 +105,27 @@ basic_ofstream( ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). -*right*\ +*`right`*\ The rvalue reference to the `basic_ofstream` object being used to initialize this `basic_ofstream` object. ### Remarks -The first constructor initializes the base class by calling [basic_ostream](../standard-library/basic-ostream-class.md)(`sb`), where `sb` is the stored object of class [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`>. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`>. +The first constructor initializes the base class by calling `basic_ostream(sb)`, where `sb` is the stored object of class `basic_filebuf< Elem, Tr>`. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`>. + +The second and third constructors initialize the base class by calling `basic_ostream( sb)`. It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`> and then `sb.open( _Filename, _Mode | ios_base::out)`. If the latter function returns a `NULL` pointer, the constructor calls `setstate(failbit)`. -The second and third constructors initializes the base class by calling `basic_ostream`( **sb**). It also initializes `sb` by calling `basic_filebuf`< `Elem`, `Tr`> and then `sb`. [open](../standard-library/basic-filebuf-class.md#open)( `_Filename`, `_Mode` | `ios_base::out`). If the latter function returns a null pointer, the constructor calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`). +The fourth constructor is a copy function. It initializes the object with the contents of *`right`*, treated as an rvalue reference. -The fourth constructor is a copy function. It initializes the object with the contents of *right*, treated as an rvalue reference. +For more information, see [`basic_ostream`](../standard-library/basic-ostream-class.md), [`open`](../standard-library/basic-filebuf-class.md#open), and [`setstate`](../standard-library/basic-ios-class.md#setstate). ### Example @@ -146,7 +149,7 @@ int main(int argc, char **argv) } ``` -## basic_ofstream::close +## `basic_ofstream::close` Closes a file. @@ -156,13 +159,13 @@ void close(); ### Remarks -The member function calls [rdbuf](../standard-library/basic-ifstream-class.md#rdbuf)**->**[close](../standard-library/basic-filebuf-class.md#close). +The member function calls `rdbuf->close`. For more information, see [`rdbuf`](../standard-library/basic-ifstream-class.md#rdbuf) and [`close`](../standard-library/basic-filebuf-class.md#close). ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `close`. -## basic_ofstream::is_open +## `basic_ofstream::is_open` Indicates whether a file is open. @@ -176,7 +179,7 @@ bool is_open() const; ### Remarks -The member function returns [rdbuf](#rdbuf) **->** [is_open](../standard-library/basic-filebuf-class.md#is_open). +The member function returns `rdbuf->is_open`. For more information, see [`rdbuf`](#rdbuf) and [`is_open`](../standard-library/basic-filebuf-class.md#is_open). ### Example @@ -200,7 +203,7 @@ int main( ) } ``` -## basic_ofstream::open +## `basic_ofstream::open` Opens a file. @@ -226,26 +229,29 @@ void open( ### Parameters -*_Filename*\ +*`_Filename`*\ The name of the file to open. -*_Mode*\ -One of the enumerations in [ios_base::openmode](../standard-library/ios-base-class.md#openmode). +*`_Mode`*\ +One of the enumerations in [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). -*_Prot*\ -The default file opening protection, equivalent to the `shflag` parameter in [_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md). +*`_Prot`*\ +The default file opening protection, equivalent to the `shflag` parameter in [`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md). ### Remarks -The member function calls [rdbuf](#rdbuf) **->** [open](../standard-library/basic-filebuf-class.md#open)(_ *Filename*, `_Mode` | `ios_base::out`). If that function returns a null pointer, the function calls [setstate](../standard-library/basic-ios-class.md#setstate)(`failbit`). +The member function calls `rdbuf -> open(_ Filename, _Mode | ios_base::out)`. If that function returns a `NULL` pointer, the function calls `setstate(failbit)`. + +For more information, see [`rdbuf`](#rdbuf), [`open`](../standard-library/basic-filebuf-class.md#open), and [`setstate`](../standard-library/basic-ios-class.md#setstate). + ### Example -See [basic_filebuf::open](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. +See [`basic_filebuf::open`](../standard-library/basic-filebuf-class.md#open) for an example that uses `open`. -## basic_ofstream::operator= +## `basic_ofstream::operator=` -Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that does not leave a copy behind. +Assigns the content of this stream object. This is a move assignment involving an `rvalue reference` that doesn't leave a copy behind. ```cpp basic_ofstream& operator=(basic_ofstream&& right); @@ -253,7 +259,7 @@ basic_ofstream& operator=(basic_ofstream&& right); ### Parameters -*right*\ +*`right`*\ An rvalue reference to a `basic_ofstream` object. ### Return Value @@ -262,9 +268,9 @@ Returns **`*this`**. ### Remarks -The member operator replaces the contents of the object by using the contents of *right*, treated as an rvalue reference. +The member operator replaces the contents of the object by using the contents of *`right`*, treated as an rvalue reference. -## basic_ofstream::rdbuf +## `basic_ofstream::rdbuf` Returns the address of the stored stream buffer. @@ -278,9 +284,9 @@ Returns the address of the stored stream buffer. ### Example -See [basic_filebuf::close](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. +See [`basic_filebuf::close`](../standard-library/basic-filebuf-class.md#close) for an example that uses `rdbuf`. -## basic_ofstream::swap +## `basic_ofstream::swap` Exchanges the contents of two `basic_ofstream` objects. @@ -290,16 +296,16 @@ void swap(basic_ofstream& right); ### Parameters -*right*\ +*`right`*\ An `lvalue` reference to another `basic_ofstream` object. ### Remarks -The member function exchanges the contents of this object for the contents of *right*. +The member function exchanges the contents of this object for the contents of *`right`*. ## See also -[basic_ostream Class](../standard-library/basic-ostream-class.md)\ +[`basic_ostream` Class](../standard-library/basic-ostream-class.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/basic-ostream-class.md b/docs/standard-library/basic-ostream-class.md index 6365780620..a2b1b7e652 100644 --- a/docs/standard-library/basic-ostream-class.md +++ b/docs/standard-library/basic-ostream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_ostream Class" title: "basic_ostream Class" -ms.date: "03/27/2019" +description: "Learn more about: basic_ostream Class" +ms.date: 03/27/2019 f1_keywords: ["ostream/std::basic_ostream", "ostream/std::basic_ostream::flush", "ostream/std::basic_ostream::put", "ostream/std::basic_ostream::seekp", "ostream/std::basic_ostream::sentry", "ostream/std::basic_ostream::swap", "ostream/std::basic_ostream::tellp", "ostream/std::basic_ostream::write"] helpviewer_keywords: ["std::basic_ostream [C++]", "std::basic_ostream [C++], flush", "std::basic_ostream [C++], put", "std::basic_ostream [C++], seekp", "std::basic_ostream [C++], sentry", "std::basic_ostream [C++], swap", "std::basic_ostream [C++], tellp", "std::basic_ostream [C++], write"] -ms.assetid: 5baadc65-b662-4fab-8c9f-94457c58cda1 --- # basic_ostream Class @@ -449,12 +448,15 @@ int main() The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions. -class sentry { - public: - explicit sentry(basic_ostream\& _Ostr); - operator bool() const; - ~sentry(); - }; +```cpp +class sentry +{ +public: + explicit sentry(basic_ostream& _Ostr); + operator bool() const; + ~sentry(); +}; +``` ### Remarks diff --git a/docs/standard-library/basic-ostringstream-class.md b/docs/standard-library/basic-ostringstream-class.md index 78e7b21fb5..29ff6874a7 100644 --- a/docs/standard-library/basic-ostringstream-class.md +++ b/docs/standard-library/basic-ostringstream-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: basic_ostringstream Class" title: "basic_ostringstream Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_ostringstream Class" +ms.date: 06/10/2022 f1_keywords: ["sstream/std::basic_ostringstream", "sstream/std::basic_ostringstream::allocator_type", "sstream/std::basic_ostringstream::rdbuf", "sstream/std::basic_ostringstream::str"] helpviewer_keywords: ["std::basic_ostringstream [C++]", "std::basic_ostringstream [C++], allocator_type", "std::basic_ostringstream [C++], rdbuf", "std::basic_ostringstream [C++], str"] -ms.assetid: aea699f7-350f-432a-acca-adbae7b483fb +ms.custom: devdivchpfy22 --- + # basic_ostringstream Class Describes an object that controls insertion of elements and encoded objects into a stream buffer of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. @@ -85,9 +86,9 @@ An object of type `basic_string`. ### Remarks -The first constructor initializes the base class by calling [basic_ostream](../standard-library/basic-ostream-class.md)( **sb**), where `sb` is the stored object of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. It also initializes **sb** by calling basic_stringbuf< **Elem**, **Tr**, `Alloc`>( `_Mode` | `ios_base::out`). +The first constructor initializes the base class by calling `basic_ostream( sb )`, where `sb` is the stored object of class `basic_stringbuf< Elem, Tr, Alloc>`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc>( _Mode | ios_base::out )`. For more information, see [`basic_ostream`](../standard-library/basic-ostream-class.md) and [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md). -The second constructor initializes the base class by calling basic_ostream( **sb**). It also initializes `sb` by calling basic_stringbuf< **Elem**, **Tr**, `Alloc`>(_ *Str*, `_Mode` | `ios_base::out`). +The second constructor initializes the base class by calling `basic_ostream( sb )`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( str, _Mode | ios_base::out )`. ## basic_ostringstream::rdbuf @@ -127,11 +128,11 @@ The new string. ### Return Value -Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by **\*this**. +Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by `*this`. ### Remarks -The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**( `_Newstr`). +The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**(`_Newstr`). ### Example diff --git a/docs/standard-library/basic-regex-class.md b/docs/standard-library/basic-regex-class.md index 8648291bcf..2586536d01 100644 --- a/docs/standard-library/basic-regex-class.md +++ b/docs/standard-library/basic-regex-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: basic_regex Class" title: "basic_regex Class" -ms.date: "03/27/2019" +ms.date: 06/10/2022 f1_keywords: ["regex/std::basic_regex"] helpviewer_keywords: ["basic_regex class"] ms.assetid: 8a18c6b4-f22a-4cfd-bc16-b4267867ebc3 +ms.custom: devdivchpfy22 --- + # basic_regex Class Wraps a regular expression. @@ -27,23 +29,23 @@ Traits class for elements. ## Remarks -The class template describes an object that holds a regular expression. Objects of this class template can be passed to the template functions [regex_match](../standard-library/regex-functions.md#regex_match), [regex_search](../standard-library/regex-functions.md#regex_search), and [regex_replace](../standard-library/regex-functions.md#regex_replace), along with suitable text string arguments, to search for text that matches the regular expression. There are two specializations of this class template, with the type definitions [regex](../standard-library/regex-typedefs.md#regex) for elements of type **`char`**, and [wregex](../standard-library/regex-typedefs.md#wregex) for elements of type **`wchar_t`**. +The class template describes an object that holds a regular expression. Objects of this class template can be passed to the template functions [regex_match](../standard-library/regex-functions.md#regex_match), [regex_search](../standard-library/regex-functions.md#regex_search), and [regex_replace](../standard-library/regex-functions.md#regex_replace). It also passes the suitable text string arguments, to search for text that matches the regular expression. There are two specializations of this class template, with the type definitions [regex](../standard-library/regex-typedefs.md#regex) for elements of type **`char`**, and [wregex](../standard-library/regex-typedefs.md#wregex) for elements of type **`wchar_t`**. The template argument *RXtraits* describes various important properties of the syntax of the regular expressions that the class template supports. A class that specifies these regular expression traits must have the same external interface as an object of type [regex_traits Class](../standard-library/regex-traits-class.md). Some functions take an operand sequence that defines a regular expression. You can specify such an operand sequence several ways: -`ptr` -- a null-terminated sequence (such as a C string, for *Elem* of type **`char`**) beginning at `ptr` (which must not be a null pointer), where the terminating element is the value `value_type()` and is not part of the operand sequence +`ptr`: a null-terminated sequence (such as a C string, for *Elem* of type **`char`**) beginning at `ptr` (which must not be a null pointer), where the terminating element is the value `value_type()` and isn't part of the operand sequence -`ptr`, `count` -- a sequence of `count` elements beginning at `ptr` (which must not be a null pointer) +`ptr`, `count`: a sequence of `count` elements beginning at `ptr` (which must not be a null pointer) -`str` -- the sequence specified by the `basic_string` object `str` +`str`: the sequence specified by the `basic_string` object `str` -`first`, `last` -- a sequence of elements delimited by the iterators `first` and `last`, in the range `[first, last)` +`first`, `last`: a sequence of elements delimited by the iterators `first` and `last`, in the range `[first, last)` -`right` -- the `basic_regex` object `right` +`right`: the `basic_regex` object `right` -These member functions also take an argument `flags` that specifies various options for the interpretation of the regular expression in addition to those described by the *RXtraits* type. +The above member functions also take an argument `flags` that specifies various options for the interpretation of the regular expression in addition to options described by the *RXtraits* type. ### Members @@ -336,7 +338,7 @@ All constructors store a default-constructed object of type `RXtraits`. The first constructor constructs an empty `basic_regex` object. The other constructors construct a `basic_regex` object that holds the regular expression described by the operand sequence. -An empty `basic_regex` object does not match any character sequence when passed to [regex_match](../standard-library/regex-functions.md#regex_match), [regex_search](../standard-library/regex-functions.md#regex_search), or [regex_replace](../standard-library/regex-functions.md#regex_replace). +An empty `basic_regex` object doesn't match any character sequence when passed to [regex_match](../standard-library/regex-functions.md#regex_match), [regex_search](../standard-library/regex-functions.md#regex_search), or [regex_replace](../standard-library/regex-functions.md#regex_replace). ## basic_regex::flag_type diff --git a/docs/standard-library/basic-streambuf-class.md b/docs/standard-library/basic-streambuf-class.md index 12d4e20133..4a543f3fef 100644 --- a/docs/standard-library/basic-streambuf-class.md +++ b/docs/standard-library/basic-streambuf-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: basic_streambuf Class" title: "basic_streambuf Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_streambuf Class" +ms.date: 06/10/2022 f1_keywords: ["streambuf/std::basic_streambuf", "streambuf/std::basic_streambuf::char_type", "streambuf/std::basic_streambuf::int_type", "streambuf/std::basic_streambuf::off_type", "streambuf/std::basic_streambuf::pos_type", "streambuf/std::basic_streambuf::traits_type", "streambuf/std::basic_streambuf::eback", "streambuf/std::basic_streambuf::egptr", "streambuf/std::basic_streambuf::epptr", "streambuf/std::basic_streambuf::gbump", "streambuf/std::basic_streambuf::getloc", "streambuf/std::basic_streambuf::gptr", "streambuf/std::basic_streambuf::imbue", "streambuf/std::basic_streambuf::in_avail", "streambuf/std::basic_streambuf::overflow", "streambuf/std::basic_streambuf::pbackfail", "streambuf/std::basic_streambuf::pbase", "streambuf/std::basic_streambuf::pbump", "streambuf/std::basic_streambuf::pptr", "streambuf/std::basic_streambuf::pubimbue", "streambuf/std::basic_streambuf::pubseekoff", "streambuf/std::basic_streambuf::pubseekpos", "streambuf/std::basic_streambuf::pubsetbuf", "streambuf/std::basic_streambuf::pubsync", "streambuf/std::basic_streambuf::sbumpc", "streambuf/std::basic_streambuf::seekoff", "streambuf/std::basic_streambuf::seekpos", "streambuf/std::basic_streambuf::setbuf", "streambuf/std::basic_streambuf::setg", "streambuf/std::basic_streambuf::setp", "streambuf/std::basic_streambuf::sgetc", "streambuf/std::basic_streambuf::sgetn", "streambuf/std::basic_streambuf::showmanyc", "streambuf/std::basic_streambuf::snextc", "streambuf/std::basic_streambuf::sputbackc", "streambuf/std::basic_streambuf::sputc", "streambuf/std::basic_streambuf::sputn", "streambuf/std::basic_streambuf::stossc", "streambuf/std::basic_streambuf::sungetc", "streambuf/std::basic_streambuf::swap", "streambuf/std::basic_streambuf::sync", "streambuf/std::basic_streambuf::uflow", "streambuf/std::basic_streambuf::underflow", "streambuf/std::basic_streambuf::xsgetn", "streambuf/std::basic_streambuf::xsputn"] helpviewer_keywords: ["std::basic_streambuf [C++]", "std::basic_streambuf [C++], char_type", "std::basic_streambuf [C++], int_type", "std::basic_streambuf [C++], off_type", "std::basic_streambuf [C++], pos_type", "std::basic_streambuf [C++], traits_type", "std::basic_streambuf [C++], eback", "std::basic_streambuf [C++], egptr", "std::basic_streambuf [C++], epptr", "std::basic_streambuf [C++], gbump", "std::basic_streambuf [C++], getloc", "std::basic_streambuf [C++], gptr", "std::basic_streambuf [C++], imbue", "std::basic_streambuf [C++], in_avail", "std::basic_streambuf [C++], overflow", "std::basic_streambuf [C++], pbackfail", "std::basic_streambuf [C++], pbase", "std::basic_streambuf [C++], pbump", "std::basic_streambuf [C++], pptr", "std::basic_streambuf [C++], pubimbue", "std::basic_streambuf [C++], pubseekoff", "std::basic_streambuf [C++], pubseekpos", "std::basic_streambuf [C++], pubsetbuf", "std::basic_streambuf [C++], pubsync", "std::basic_streambuf [C++], sbumpc", "std::basic_streambuf [C++], seekoff", "std::basic_streambuf [C++], seekpos", "std::basic_streambuf [C++], setbuf", "std::basic_streambuf [C++], setg", "std::basic_streambuf [C++], setp", "std::basic_streambuf [C++], sgetc", "std::basic_streambuf [C++], sgetn", "std::basic_streambuf [C++], showmanyc", "std::basic_streambuf [C++], snextc", "std::basic_streambuf [C++], sputbackc", "std::basic_streambuf [C++], sputc", "std::basic_streambuf [C++], sputn", "std::basic_streambuf [C++], stossc", "std::basic_streambuf [C++], sungetc", "std::basic_streambuf [C++], swap", "std::basic_streambuf [C++], sync", "std::basic_streambuf [C++], uflow", "std::basic_streambuf [C++], underflow", "std::basic_streambuf [C++], xsgetn", "std::basic_streambuf [C++], xsputn"] -ms.assetid: 136af6c3-13bf-4501-9288-b93da26efac7 +ms.custom: devdivchpfy22 --- + # basic_streambuf Class Describes an abstract base class for deriving a stream buffer, which controls the transmission of elements to and from a specific representation of a stream. @@ -31,7 +32,7 @@ The class template describes an abstract base class for deriving a stream buffer Every stream buffer conceptually controls two independent streams: one for extractions (input) and one for insertions (output). A specific representation may, however, make either or both of these streams inaccessible. It typically maintains some relationship between the two streams. What you insert into the output stream of a [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< `Elem`, `Tr`> object, for example, is what you later extract from its input stream. When you position one stream of a [basic_filebuf](../standard-library/basic-filebuf-class.md)< `Elem`, `Tr`> object, you position the other stream in tandem. -The public interface to class template `basic_streambuf` supplies the operations that are common to all stream buffers, however specialized. The protected interface supplies the operations needed for a specific representation of a stream to do its work. The protected virtual member functions let you tailor the behavior of a derived stream buffer for a specific representation of a stream. Each derived stream buffer in this library describes how it specializes the behavior of its protected virtual member functions. The default behavior for the base class, which is often to do nothing, is described in this topic. +The public interface to class template `basic_streambuf` supplies the operations that are common to all stream buffers, however specialized. The protected interface supplies the operations needed for a specific representation of a stream to do its work. The protected virtual member functions let you tailor the behavior of a derived stream buffer for a specific representation of a stream. Each derived stream buffer in this library describes how it specializes the behavior of its protected virtual member functions. The default behavior for the base class, which is often to do nothing, is described in this article. The remaining protected member functions control copying to and from any storage supplied to buffer transmissions to and from streams. An input buffer, for example, is characterized by: @@ -39,7 +40,7 @@ The remaining protected member functions control copying to and from any storage - [gptr](#gptr), a pointer to the next element to read. -- [egptr](#egptr), a pointer just past the end of the buffer. +- [egptr](#egptr), a pointer past the end of the buffer. Similarly, an output buffer is characterized by: @@ -47,7 +48,7 @@ Similarly, an output buffer is characterized by: - [pptr](#pptr), a pointer to the next element to write. -- [epptr](#epptr), a pointer just past the end of the buffer. +- [epptr](#epptr), a pointer past the end of the buffer. For any buffer, the following protocol is used: @@ -84,8 +85,8 @@ An object of class `basic_streambuf`< `Elem`, `Tr`> stores the six pointers prev |Member function|Description| |-|-| |[eback](#eback)|A protected function that returns a pointer to the beginning of the input buffer.| -|[egptr](#egptr)|A protected function that returns a pointer just past the end of the input buffer.| -|[epptr](#epptr)|A protected function that returns a pointer just past the end of the output buffer.| +|[egptr](#egptr)|A protected function that returns a pointer past the end of the input buffer.| +|[epptr](#epptr)|A protected function that returns a pointer past the end of the output buffer.| |[gbump](#gbump)|A protected function that adds `count` to the next pointer for the input buffer.| |[getloc](#getloc)|Gets the `basic_streambuf` object's locale.| |[gptr](#gptr)|A protected function that returns a pointer to the next element of the input buffer.| @@ -109,7 +110,7 @@ An object of class `basic_streambuf`< `Elem`, `Tr`> stores the six pointers prev |[setp](#setp)|A protected function that stores `_Pbeg` in the beginning pointer and `_Pend` in the end pointer for the output buffer.| |[sgetc](#sgetc)|Returns current element without changing position in the stream.| |[sgetn](#sgetn)|Returns the number of elements read.| -|[showmanyc](#showmanyc)|Protected virtual member function that returns a count of the number of characters that can be extracted from the input stream and ensure that the program will not be subject to an indefinite wait.| +|[showmanyc](#showmanyc)|Protected virtual member function that returns a count of the number of characters that can be extracted from the input stream. It also ensures that the program won't be subject to an indefinite wait.| |[snextc](#snextc)|Reads the current element and returns the following element.| |[sputbackc](#sputbackc)|Puts a `char_type` in the stream.| |[sputc](#sputc)|Puts a character into the stream.| @@ -178,7 +179,7 @@ A pointer to the beginning of the input buffer. ## basic_streambuf::egptr -A protected function that returns a pointer just past the end of the input buffer. +A protected function that returns a pointer past the end of the input buffer. ```cpp char_type *egptr() const; @@ -186,11 +187,11 @@ char_type *egptr() const; ### Return Value -A pointer just past the end of the input buffer. +A pointer past the end of the input buffer. ## basic_streambuf::epptr -A protected function that returns a pointer just past the end of the output buffer. +A protected function that returns a pointer past the end of the output buffer. ```cpp char_type *epptr() const; @@ -198,7 +199,7 @@ char_type *epptr() const; ### Return Value -A pointer just past the end of the output buffer. +A pointer past the end of the output buffer. ## basic_streambuf::gbump @@ -358,11 +359,11 @@ The character to insert into the buffer, or **traits_type::**[eof](../standard-l ### Return Value -If the function cannot succeed, it returns **traits_type::eof** or throws an exception. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). The default behavior is to return **traits_type::eof**. +If the function can't succeed, it returns **traits_type::eof** or throws an exception. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). The default behavior is to return **traits_type::eof**. ### Remarks -If *\_Meta* does not compare equal to **traits_type::eof**, the protected virtual member function endeavors to insert the element **traits_type::**[to_char_type](../standard-library/char-traits-struct.md#to_char_type)(*\_Meta*) into the output stream. It can do so in various ways: +If *\_Meta* doesn't compare equal to **traits_type::eof**, the protected virtual member function endeavors to insert the element **traits_type::**[to_char_type](../standard-library/char-traits-struct.md#to_char_type)(*\_Meta*) into the output stream. It can do so in various ways: - If a `write position` is available, it can store the element into the write position and increment the next pointer for the output buffer. @@ -374,7 +375,7 @@ The virtual overflow function, together with the [sync](#sync) and [underflow](# The `overflow` function is most frequently called by public `streambuf` functions like `sputc` and `sputn` when the put area is full, but other classes, including the stream classes, can call `overflow` anytime. -The function consumes the characters in the put area between the `pbase` and `pptr` pointers and then reinitializes the put area. The `overflow` function must also consume `nCh` (if `nCh` is not `EOF`), or it might choose to put that character in the new put area so that it will be consumed on the next call. +The function consumes the characters in the put area between the `pbase` and `pptr` pointers and then reinitializes the put area. The `overflow` function must also consume `nCh` (if `nCh` isn't `EOF`), or it might choose to put that character in the new put area so that it will be consumed on the next call. The definition of consume varies among derived classes. For example, the `filebuf` class writes its characters to a file, while the `strstreambuf` class keeps them in its buffer and (if the buffer is designated as dynamic) expands the buffer in response to a call to overflow. This expansion is achieved by freeing the old buffer and replacing it with a new, larger one. The pointers are adjusted as necessary. @@ -393,7 +394,7 @@ The character to insert into the buffer, or **traits_type::**[eof](../standard-l ### Return Value -If the function cannot succeed, it returns **traits_type::eof** or throws an exception. Otherwise, it returns some other value. The default behavior is to return **traits_type::eof**. +If the function can't succeed, it returns **traits_type::eof** or throws an exception. Otherwise, it returns some other value. The default behavior is to return **traits_type::eof**. ### Remarks @@ -498,7 +499,7 @@ Specifies the mode for the pointer position. The default is to allow you to modi ### Return Value -Returns the new position or an invalid stream position ( [seekoff](#seekoff)(_ *Off*, `_Way`, `_Which`) ). +Returns the new position or an invalid stream position ([seekoff](#seekoff)(_ *Off*, `_Way`, `_Which`)). ### Remarks @@ -548,7 +549,7 @@ The size of the buffer. ### Return Value -Returns [setbuf](#setbuf)( `_Buffer`, `count`). +Returns [setbuf](#setbuf)(`_Buffer`, `count`). ## basic_streambuf::pubsync @@ -576,7 +577,7 @@ The current element. ### Remarks -If a read position is available, the member function returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( \*[gptr](#gptr)) and increments the next pointer for the input buffer. Otherwise, it returns [uflow](#uflow). +If a read position is available, the member function returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)(\*[gptr](#gptr)) and increments the next pointer for the input buffer. Otherwise, it returns [uflow](#uflow). ### Example @@ -627,7 +628,7 @@ Specifies the mode for the pointer position. The default is to allow you to modi ### Return Value -Returns the new position or an invalid stream position ( `seekoff` (_ *Off*, `_Way`, `_Which`) ). +Returns the new position or an invalid stream position (`seekoff` (_ *Off*, `_Way`, `_Which`)). ### Remarks @@ -748,7 +749,7 @@ The current element. ### Remarks -If a read position is available, the member function returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( `*`[gptr](#gptr)). Otherwise, it returns [underflow](#underflow). +If a read position is available, the member function returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)(`*`[gptr](#gptr)). Otherwise, it returns [underflow](#underflow). ### Example @@ -792,11 +793,11 @@ The number of elements to read. ### Return Value -The number of elements read. See [streamsize](../standard-library/ios-typedefs.md#streamsize) for more information. +The number of elements read. For more information, see [streamsize](../standard-library/ios-typedefs.md#streamsize) for more information. ### Remarks -The member function returns [xsgetn](#xsgetn)( `ptr`, `count`). +The member function returns [xsgetn](#xsgetn)(`ptr`, `count`). ### Example @@ -827,7 +828,7 @@ int main() ## basic_streambuf::showmanyc -A protected virtual member function that returns a count of the number of characters that can be extracted from the input stream and ensure that the program will not be subject to an indefinite wait. +A protected virtual member function that returns a count of the number of characters that can be extracted from the input stream and ensure that the program won't be subject to an indefinite wait. ```cpp virtual streamsize showmanyc(); @@ -896,7 +897,7 @@ Returns the character or failure. ### Remarks -If a putback position is available and *_Ch* compares equal to the character stored in that position, the member function decrements the next pointer for the input buffer and returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( `_Ch`). Otherwise, it returns [pbackfail](#pbackfail)( `_Ch`). +If a putback position is available and *_Ch* compares equal to the character stored in that position, the member function decrements the next pointer for the input buffer and returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)(`_Ch`). Otherwise, it returns [pbackfail](#pbackfail)(`_Ch`). ### Example @@ -944,7 +945,7 @@ Returns the character, if successful. ### Remarks -If a `write position` is available, the member function stores *_Ch* in the write position, increments the next pointer for the output buffer, and returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( `_Ch`). Otherwise, it returns [overflow](#overflow)( `_Ch`). +If a `write position` is available, the member function stores *_Ch* in the write position, increments the next pointer for the output buffer, and returns **traits_type::**[to_int_type](../standard-library/char-traits-struct.md#to_int_type)(`_Ch`). Otherwise, it returns [overflow](#overflow)(`_Ch`). ### Example @@ -986,11 +987,11 @@ The count of characters. ### Return Value -The number of characters actually inserted into the stream. +The number of characters inserted into the stream. ### Remarks -The member function returns [xsputn](#xsputn)( `ptr`, `count`). See the Remarks section of this member for more information. +The member function returns [xsputn](#xsputn)(`ptr`, `count`). For more information, see the Remarks section of this member for more information. ### Example @@ -1024,7 +1025,7 @@ void stossc(); ### Remarks -The member function calls [sbumpc](#sbumpc). Note that an implementation is not required to supply this member function. +The member function calls [sbumpc](#sbumpc). An implementation isn't required to supply this member function. ### Example @@ -1059,7 +1060,7 @@ Returns either the character or failure. ### Remarks -If a putback position is available, the member function decrements the next pointer for the input buffer and returns `traits_type::`[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( `*`[gptr](#gptr)). However, it is not always possible to determine the last character read so that it can be captured in the state of the current buffer. If this is true, then the function returns [pbackfail](#pbackfail). To avoid this situation, keep track of the character to put back and call `sputbackc(ch)`, which will not fail provided you don't call it at the beginning of the stream and you don't try to put back more than one character. +If a putback position is available, the member function decrements the next pointer for the input buffer and returns `traits_type::`[to_int_type](../standard-library/char-traits-struct.md#to_int_type)(`*`[gptr](#gptr)). However, it isn't always possible to determine the last character read so that it can be captured in the state of the current buffer. If this is true, then the function returns [pbackfail](#pbackfail). To avoid this situation, keep track of the character to put back and call `sputbackc(ch)`, which won't fail provided you don't call it at the beginning of the stream and you don't try to put back more than one character. ### Example @@ -1122,11 +1123,11 @@ virtual int sync(); ### Return Value -If the function cannot succeed, it returns -1. The default behavior is to return zero. +If the function can't succeed, it returns -1. The default behavior is to return zero. ### Remarks -`sync` involves writing out any elements between the beginning and next pointers for the output buffer. It does not involve putting back any elements between the next and end pointers for the input buffer. +`sync` involves writing out any elements between the beginning and next pointers for the output buffer. It doesn't involve putting back any elements between the next and end pointers for the input buffer. ## basic_streambuf::traits_type @@ -1158,7 +1159,7 @@ The protected virtual member function tries to extract the current element **ch* - For a stream buffer with common input and output streams, it can make a read position available by writing out, to some external destination, some or all of the elements between the beginning and next pointers for the output buffer. Or it can allocate new or additional storage for the input buffer. The function then reads in, from some external source, one or more elements. -If the function cannot succeed, it returns **traits_type::**[eof](../standard-library/char-traits-struct.md#eof), or throws an exception. Otherwise, it returns the current element `ch` in the input stream, converted as described above, and advances the next pointer for the input buffer. The default behavior is to call [underflow](#underflow) and, if that function returns **traits_type::eof**, to return **traits_type::eof**. Otherwise, the function returns the current element **ch** in the input stream, converted as previously described, and advances the next pointer for the input buffer. +If the function can't succeed, it returns **traits_type::**[eof](../standard-library/char-traits-struct.md#eof), or throws an exception. Otherwise, it returns the current element `ch` in the input stream, converted as described above, and advances the next pointer for the input buffer. The default behavior is to call [underflow](#underflow) and, if that function returns **traits_type::eof**, to return **traits_type::eof**. Otherwise, the function returns the current element **ch** in the input stream, converted as previously described, and advances the next pointer for the input buffer. ## basic_streambuf::underflow @@ -1176,11 +1177,11 @@ The current element. The protected virtual member function endeavors to extract the current element **ch** from the input stream, without advancing the current stream position, and return it as `traits_type::`[to_int_type](../standard-library/char-traits-struct.md#to_int_type)( **ch**). It can do so in various ways: -- If a read position is available, **ch** is the element stored in the read position. For more information on this, see the Remarks section of the [basic_streambuf Class](../standard-library/basic-streambuf-class.md). +- If a read position is available, **ch** is the element stored in the read position. For more information, see the Remarks section of the [basic_streambuf Class](../standard-library/basic-streambuf-class.md). -- It can make a read position available by allocating new or additional storage for the input buffer, then reading in, from some external source, one or more elements. For more information on this, see the Remarks section of the [basic_streambuf Class](../standard-library/basic-streambuf-class.md). +- It can make a read position available by allocating new or additional storage for the input buffer, then reading in, from some external source, one or more elements. For more information, see the Remarks section of the [basic_streambuf Class](../standard-library/basic-streambuf-class.md). -If the function cannot succeed, it returns `traits_type::`[eof](../standard-library/char-traits-struct.md#eof)`()` or throws an exception. Otherwise, it returns the current element in the input stream, converted as previously described. The default behavior is to return `traits_type::eof()`. +If the function can't succeed, it returns `traits_type::`[eof](../standard-library/char-traits-struct.md#eof)`()` or throws an exception. Otherwise, it returns the current element in the input stream, converted as previously described. The default behavior is to return `traits_type::eof()`. The virtual `underflow` function, with the [sync](#sync) and [overflow](#overflow) functions, defines the characteristics of the `streambuf`-derived class. Each derived class might implement `underflow` differently, but the interface with the calling stream class is the same. @@ -1216,7 +1217,7 @@ The number of elements extracted. ### Remarks -The protected virtual member function extracts up to *count* elements from the input stream, as if by repeated calls to [sbumpc](#sbumpc), and stores them in the array beginning at *ptr*. It returns the number of elements actually extracted. +The protected virtual member function extracts up to *count* elements from the input stream, as if by repeated calls to [sbumpc](#sbumpc), and stores them in the array beginning at *ptr*. It returns the number of elements extracted. ## basic_streambuf::xsputn @@ -1236,11 +1237,11 @@ Number of elements to insert. ### Return Value -The number of elements actually inserted into the stream. +The number of elements inserted into the stream. ### Remarks -The protected virtual member function inserts up to *count* elements into the output stream, as if by repeated calls to [sputc](#sputc), from the array beginning at *ptr*. The insertion of characters into the output stream stops once all *count* characters have been written, or if calling `sputc( count)` would return `traits::eof()`. It returns the number of elements actually inserted. +The protected virtual member function inserts up to *count* elements into the output stream, as if by repeated calls to [sputc](#sputc), from the array beginning at *ptr*. The insertion of characters into the output stream stops once all *count* characters have been written, or if calling `sputc( count)` would return `traits::eof()`. It returns the number of elements inserted. ## See also diff --git a/docs/standard-library/basic-string-class.md b/docs/standard-library/basic-string-class.md index 9a1aa00c65..554d5ba8d8 100644 --- a/docs/standard-library/basic-string-class.md +++ b/docs/standard-library/basic-string-class.md @@ -1,13 +1,15 @@ --- title: "basic_string Class" description: "API reference for the Standard C++ string class, `basic_string`." -ms.date: "01/15/2021" +ms.date: 07/11/2023 f1_keywords: ["xstring/std::basic_string", "xstring/std::basic_string::allocator_type", "xstring/std::basic_string::const_iterator", "xstring/std::basic_string::const_pointer", "xstring/std::basic_string::const_reference", "xstring/std::basic_string::const_reverse_iterator", "xstring/std::basic_string::difference_type", "xstring/std::basic_string::iterator", "xstring/std::basic_string::npos", "xstring/std::basic_string::pointer", "xstring/std::basic_string::reference", "xstring/std::basic_string::reverse_iterator", "xstring/std::basic_string::size_type", "xstring/std::basic_string::traits_type", "xstring/std::basic_string::value_type", "xstring/std::basic_string::append", "xstring/std::basic_string::assign", "xstring/std::basic_string::at", "xstring/std::basic_string::back", "xstring/std::basic_string::begin", "xstring/std::basic_string::c_str", "xstring/std::basic_string::capacity", "xstring/std::basic_string::cbegin", "xstring/std::basic_string::cend", "xstring/std::basic_string::clear", "xstring/std::basic_string::compare", "xstring/std::basic_string::copy", "xstring/std::basic_string::crbegin", "xstring/std::basic_string::crend", "xstring/std::basic_string::_Copy_s", "xstring/std::basic_string::data", "xstring/std::basic_string::empty", "xstring/std::basic_string::end", "xstring/std::basic_string::erase", "xstring/std::basic_string::find", "xstring/std::basic_string::find_first_not_of", "xstring/std::basic_string::find_first_of", "xstring/std::basic_string::find_last_not_of", "xstring/std::basic_string::find_last_of", "xstring/std::basic_string::front", "xstring/std::basic_string::get_allocator", "xstring/std::basic_string::insert", "xstring/std::basic_string::length", "xstring/std::basic_string::max_size", "xstring/std::basic_string::pop_back", "xstring/std::basic_string::push_back", "xstring/std::basic_string::rbegin", "xstring/std::basic_string::rend", "xstring/std::basic_string::replace", "xstring/std::basic_string::reserve", "xstring/std::basic_string::resize", "xstring/std::basic_string::rfind", "xstring/std::basic_string::shrink_to_fit", "xstring/std::basic_string::size", "xstring/std::basic_string::substr", "xstring/std::basic_string::ends_with", "xstring/std::basic_string::starts_with", "xstring/std::basic_string::swap", 'xstring/std::literals::string_literals', 'std::literals::string_literals', 'string_literals', 'xstring/std::literals::string_literals::operator "s', 'std::literals::string_literals::operator s'] helpviewer_keywords: ["std::basic_string [C++]", "std::basic_string [C++], allocator_type", "std::basic_string [C++], const_iterator", "std::basic_string [C++], const_pointer", "std::basic_string [C++], const_reference", "std::basic_string [C++], const_reverse_iterator", "std::basic_string [C++], difference_type", "std::basic_string [C++], iterator", "std::basic_string [C++], npos", "std::basic_string [C++], pointer", "std::basic_string [C++], reference", "std::basic_string [C++], reverse_iterator", "std::basic_string [C++], size_type", "std::basic_string [C++], traits_type", "std::basic_string [C++], value_type", "std::basic_string [C++], append", "std::basic_string [C++], assign", "std::basic_string [C++], at", "std::basic_string [C++], back", "std::basic_string [C++], begin", "std::basic_string [C++], c_str", "std::basic_string [C++], capacity", "std::basic_string [C++], cbegin", "std::basic_string [C++], cend", "std::basic_string [C++], clear", "std::basic_string [C++], compare", "std::basic_string [C++], copy", "std::basic_string [C++], crbegin", "std::basic_string [C++], crend", "std::basic_string [C++], _Copy_s", "std::basic_string [C++], data", "std::basic_string [C++], empty", "std::basic_string [C++], end", "std::basic_string [C++], erase", "std::basic_string [C++], find", "std::basic_string [C++], find_first_not_of", "std::basic_string [C++], find_first_of", "std::basic_string [C++], find_last_not_of", "std::basic_string [C++], find_last_of", "std::basic_string [C++], front", "std::basic_string [C++], get_allocator", "std::basic_string [C++], insert", "std::basic_string [C++], length", "std::basic_string [C++], max_size", "std::basic_string [C++], pop_back", "std::basic_string [C++], push_back", "std::basic_string [C++], rbegin", "std::basic_string [C++], rend", "std::basic_string [C++], replace", "std::basic_string [C++], reserve", "std::basic_string [C++], resize", "std::basic_string [C++], rfind", "std::basic_string [C++], shrink_to_fit", "std::basic_string [C++], size", "std::basic_string [C++], starts_with", "std::basic_string [C++], ends_with","std::basic_string [C++], substr", "std::basic_string [C++], swap"] +ms.custom: devdivchpfy22 --- + # `basic_string` Class -The sequences controlled by an object of type `basic_string` are the Standard C++ string class and are usually referred to as strings, but they shouldn't be confused with the null-terminated C-style strings used throughout the C++ Standard Library. The Standard C++ string is a container that enables the use of strings as normal types, such as comparison and concatenation operations, iterators, C++ Standard Library algorithms, and copying and assigning with class allocator-managed memory. If you need to convert a Standard C++ string to a null-terminated C-style string, use the [`basic_string::c_str`](#c_str) member. +The sequences controlled by an object of type `basic_string` are the Standard C++ string class and are referred to as strings, but they shouldn't be confused with the null-terminated C-style strings used throughout the C++ Standard Library. The Standard C++ string is a container that enables the use of strings as normal types, such as comparison and concatenation operations, iterators, C++ Standard Library algorithms, and copying and assigning with class allocator-managed memory. If you need to convert a Standard C++ string to a null-terminated C-style string, use the [`basic_string::c_str`](#c_str) member. ## Syntax @@ -59,7 +61,7 @@ The type that represents the stored allocator object that encapsulates details a |[`append`](#append)|Adds characters to the end of a string.| |[`assign`](#assign)|Assigns new character values to the contents of a string.| |[`at`](#at)|Returns a reference to the element at a specified location in the string.| -|[`back`](#back)|| +|[`back`](#back)|Returns a reference to the last element in the string.| |[`begin`](#begin)|Returns an iterator addressing the first element in the string.| |[`c_str`](#c_str)|Converts the contents of a string as a C-style, null-terminated, string.| |[`capacity`](#capacity)|Returns the largest number of elements that could be stored in a string without increasing the memory allocation of the string.| @@ -70,7 +72,7 @@ The type that represents the stored allocator object that encapsulates details a |[`copy`](#copy)|Copies at most a specified number of characters from an indexed position in a source string to a target character array. Deprecated. Use [`basic_string::_Copy_s`](#copy_s) instead.| |[`crbegin`](#crbegin)|Returns a const iterator that addresses the first element in a reversed string.| |[`crend`](#crend)|Returns a const iterator that addresses the location succeeding the last element in a reversed string.| -|[`_Copy_s`](#copy_s)|Copies at most a specified number of characters from an indexed position in a source string to a target character array.| +|[`_Copy_s`](#copy_s)|**Microsoft Specific**: Copies at most a specified number of characters from an indexed position in a source string to a target character array.| |[`data`](#data)|Converts the contents of a string into an array of characters.| |[`empty`](#empty)|Tests whether the string contains characters.| |[`end`](#end)|Returns an iterator that addresses the location succeeding the last element in a string.| @@ -282,7 +284,7 @@ int main( ) cout << "The appended string str1d is: " << str1d << "." << endl; str1d += str3d; - cout << "The doubly appended strig str1 is: " + cout << "The doubly appended string str1 is: " << str1d << "." << endl << endl; // The fifth member function @@ -316,7 +318,7 @@ The appended string str1 is: Hello World. The string str2d is: Wide The appended string str1d is: Hello Wide . -The doubly appended strig str1 is: Hello Wide World . +The doubly appended string str1 is: Hello Wide World . The string str1 appended with exclamations is: Hello !!!! @@ -1501,11 +1503,12 @@ The beginning position in the source string from which copies are to be made. ### Return value -The number of characters actually copied. +The number of characters copied. ### Remarks A null character isn't appended to the end of the copy. +This function is Microsoft specific. ### Example @@ -2956,12 +2959,10 @@ basic_string& insert( size_type count, value_type char_value); -iterator insert( - iterator iter); - iterator insert( iterator iter, - value_type char_value)l + value_type char_value); + template void insert( iterator iter, @@ -3015,7 +3016,10 @@ An input iterator, `const_pointer`, or `const_iterator` addressing the position ### Return value -Either a reference to the string object that gets assigned new characters by the member function or, in the case of individual character insertions, an iterator addressing the position of the character inserted, or none, depending on the particular member function. +The functions that return a value return either: + +- A reference to the `basic_string` that contains the original string plus the new characters. +- An iterator at the start of the inserted character(s). ### Example @@ -3346,7 +3350,7 @@ int main( ) cout << "The appended string str1d is: " << str1d << "." << endl; str1d += str3d; - cout << "The doubly appended strig str1 is: " + cout << "The doubly appended string str1 is: " << str1d << "." << endl << endl; } ``` @@ -3360,7 +3364,7 @@ Appending the C-string cstr1b to string str1 gives: Hello Out There. The string str2d is: Wide The appended string str1d is: Hello Wide . -The doubly appended strig str1 is: Hello Wide World. +The doubly appended string str1 is: Hello Wide World. ``` ## `basic_string::operator=` @@ -4197,7 +4201,7 @@ Specifies a new size for a string, appending or erasing elements as required. ```cpp void resize( - size_type count,); + size_type count); void resize( size_type count, diff --git a/docs/standard-library/basic-string-view-class.md b/docs/standard-library/basic-string-view-class.md index 6d7f39b552..fda26ef3f8 100644 --- a/docs/standard-library/basic-string-view-class.md +++ b/docs/standard-library/basic-string-view-class.md @@ -1,14 +1,13 @@ --- title: "basic_string_view Class" -description: "API reference for `basic_string_view` which refers to a constant contiguous sequence of char-like objects." +description: "API reference for `basic_string_view`, which refers to a constant contiguous sequence of char-like objects." ms.date: "9/8/2020" f1_keywords: ["xstring/std::basic_string_view", "xstring/std::basic_string_view::allocator_type", "xstring/std::basic_string_view::const_iterator", "xstring/std::basic_string_view::const_pointer", "xstring/std::basic_string_view::const_reference", "xstring/std::basic_string_view::const_reverse_iterator", "xstring/std::basic_string_view::difference_type", "xstring/std::basic_string_view::ends_with", "xstring/std::basic_string_view::starts_with", "xstring/std::basic_string_view::iterator", "xstring/std::basic_string_view::npos", "xstring/std::basic_string_view::pointer", "xstring/std::basic_string_view::reference", "xstring/std::basic_string_view::reverse_iterator", "xstring/std::basic_string_view::size_type", "xstring/std::basic_string_view::traits_type", "xstring/std::basic_string_view::value_type", "xstring/std::basic_string_view::append", "xstring/std::basic_string_view::assign", "xstring/std::basic_string_view::at", "xstring/std::basic_string_view::back", "xstring/std::basic_string_view::begin", "xstring/std::basic_string_view::c_str", "xstring/std::basic_string_view::capacity", "xstring/std::basic_string_view::cbegin", "xstring/std::basic_string_view::cend", "xstring/std::basic_string_view::clear", "xstring/std::basic_string_view::compare", "xstring/std::basic_string_view::copy", "xstring/std::basic_string_view::_Copy_s", "xstring/std::basic_string_view::crbegin", "xstring/std::basic_string_view::crend", "xstring/std::basic_string_view::data", "xstring/std::basic_string_view::empty", "xstring/std::basic_string_view::end", "xstring/std::basic_string_view::erase", "xstring/std::basic_string_view::find", "xstring/std::basic_string_view::find_first_not_of", "xstring/std::basic_string_view::find_first_of", "xstring/std::basic_string_view::find_last_not_of", "xstring/std::basic_string_view::find_last_of", "xstring/std::basic_string_view::front", "xstring/std::basic_string_view::get_allocator", "xstring/std::basic_string_view::insert", "xstring/std::basic_string_view::length", "xstring/std::basic_string_view::max_size", "xstring/std::basic_string_view::pop_back", "xstring/std::basic_string_view::push_back", "xstring/std::basic_string_view::rbegin", "xstring/std::basic_string_view::rend", "xstring/std::basic_string_view::remove_prefix","xstring/std::basic_string_view::remove_suffix", "xstring/std::basic_string_view::replace", "xstring/std::basic_string_view::reserve", "xstring/std::basic_string_view::resize", "xstring/std::basic_string_view::rfind", "xstring/std::basic_string_view::shrink_to_fit", "xstring/std::basic_string_view::size", "xstring/std::basic_string_view::substr", "xstring/std::basic_string_view::swap"] helpviewer_keywords: ["std::basic_string_view", "std::basic_string_view, allocator_type", "std::basic_string_view, const_iterator", "std::basic_string_view, const_pointer", "std::basic_string_view, const_reference", "std::basic_string_view, const_reverse_iterator", "std::basic_string_view, difference_type", "std::basic_string_view, iterator", "std::basic_string_view, npos", "std::basic_string_view, pointer", "std::basic_string_view, reference", "std::basic_string_view, reverse_iterator", "std::basic_string_view, size_type", "std::basic_string_view, traits_type", "std::basic_string_view, value_type", "std::basic_string_view, append", "std::basic_string_view, assign", "std::basic_string_view, at", "std::basic_string_view, back", "std::basic_string_view, begin", "std::basic_string_view, c_str", "std::basic_string_view, capacity", "std::basic_string_view, cbegin", "std::basic_string_view, cend", "std::basic_string_view, clear", "std::basic_string_view, compare", "std::basic_string_view, copy", "std::basic_string_view, crbegin", "std::basic_string_view, crend", "std::basic_string_view, data", "std::basic_string_view, empty", "std::basic_string_view, end", "std::basic_string_view, ends_with", "std::basic_string_view, erase", "std::basic_string_view, find", "std::basic_string_view, find_first_not_of", "std::basic_string_view, find_first_of", "std::basic_string_view, find_last_not_of", "std::basic_string_view, find_last_of", "std::basic_string_view, front", "std::basic_string_view, get_allocator", "std::basic_string_view, insert", "std::basic_string_view, length", "std::basic_string_view, max_size", "std::basic_string_view, pop_back", "std::basic_string_view, push_back", "std::basic_string_view, rbegin", "std::basic_string_view, rend", "std::basic_string_view, remove_prefix","std::basic_string_view, remove_suffix","std::basic_string_view, replace", "std::basic_string_view, reserve", "std::basic_string_view, resize", "std::basic_string_view, rfind", "std::basic_string_view, shrink_to_fit", "std::basic_string_view, size", "std::basic_string_view, starts_with", "std::basic_string_view, substr", "std::basic_string_view, swap"] -ms.assetid: a9c3e0a2-39bf-4c8a-b093-9abe30839591 --- -# basic_string_view Class +# `basic_string_view` class -The class template `basic_string_view` was added in C++17 to serve as a safe and efficient way for a function to accept various unrelated string types without the function having to be templatized on those types. The class holds a non-owning pointer to a contiguous sequence of character data, and a length that specifies the number of characters in the sequence. No assumption is made with respect to whether the sequence is null-terminated. +The class template `basic_string_view` was added in C++17 to serve as a safe and efficient way for a function to accept various unrelated string types without the function having to be templatized on those types. The class holds a non-owning pointer to a contiguous sequence of character data, and a length that specifies the number of characters in the sequence. No assumption is made about whether the sequence is null-terminated. The standard library defines several specializations based on the type of the elements: @@ -17,11 +16,9 @@ The standard library defines several specializations based on the type of the el - `u16string_view` - `u32string_view` -In this document, the term "string_view" refers generally to any of these typedefs. +A `basic_string_view` describes the minimum common interface necessary to read string data. It provides const access to the underlying data; it makes no copies (except for the `copy` function). The data may or may not contain null values (`\0`) at any position. A `basic_string_view` has no control over the object's lifetime. It's the caller's responsibility to ensure that the underlying string data is valid. -A string_view describes the minimum common interface necessary to read string data. It provides const access to the underlying data; it makes no copies (except for the `copy` function). The data may or may not contain null values ('\0') at any position. A string_view has no control over the object's lifetime. It's the caller's responsibility to ensure that the underlying string data is valid. - -A function that accepts a parameter of type string_view can be made to work with any string-like type, without making the function into a template, or constraining the function to a particular subset of string types. The only requirement is that an implicit conversion exists from the string type to string_view. All the standard string types are implicitly convertible to a string_view that contains the same element type. In other words, a `std::string` is convertible to a `string_view` but not to a `wstring_view`. +A function that accepts a parameter of type `string_view` can be made to work with any string-like type, without making the function into a template, or constraining the function to a particular subset of string types. The only requirement is that an implicit conversion exists from the string type to `string_view`. All the standard string types are implicitly convertible to a `string_view` that contains the same element type. In other words, a `std::string` is convertible to a `string_view` but not to a `wstring_view`. The following example shows a non-template function `f` that takes a parameter of type `wstring_view`. It can be called with arguments of type `std::wstring`, `wchar_t*`, and `winrt::hstring`. @@ -57,99 +54,99 @@ class basic_string_view; ### Parameters -*CharType*\ -The type of the characters that are stored in the string_view. The C++ Standard Library provides the following typedefs for specializations of this template. +*`CharType`*\ +The type of the characters that are stored in the `basic_string_view`. The C++ Standard Library provides the following typedefs for specializations of this template. -- [string_view](../standard-library/string-view-typedefs.md#string_view) for elements of type **`char`** -- [wstring_view](../standard-library/string-view-typedefs.md#wstring_view), for **`wchar_t`** -- [u16string_view](../standard-library/string-view-typedefs.md#u16string_view) for **`char16_t`** -- [u32string_view](../standard-library/string-view-typedefs.md#u32string_view) for **`char32_t`**. +- [`string_view`](../standard-library/string-view-typedefs.md#string_view) for elements of type **`char`** +- [`wstring_view`](../standard-library/string-view-typedefs.md#wstring_view), for **`wchar_t`** +- [`u16string_view`](../standard-library/string-view-typedefs.md#u16string_view) for **`char16_t`** +- [`u32string_view`](../standard-library/string-view-typedefs.md#u32string_view) for **`char32_t`**. -*Traits*\ -Defaults to [char_traits](char-traits-struct.md)<*CharType*>. +*`Traits`*\ +Defaults to [`char_traits`](char-traits-struct.md)<*`CharType`*>. ### Constructors |Constructor|Description| |-|-| -|[basic_string_view](#basic_string_view)|Constructs a string_view that is empty or else points to all or part of some other string object's data, or to a C-style character array.| +|[`basic_string_view`](#basic_string_view)|Constructs a `basic_string_view` that is empty or else points to all or part of some other string object's data, or to a C-style character array.| ### Typedefs |Type name|Description| |-|-| -|**const_iterator**|Random-access iterator that can read **`const`** elements.| -|**const_pointer**|`using const_pointer = const value_type*;`| -|**const_reference**|`using const_reference = const value_type&;`| -|**const_reverse_iterator**|`using const_reverse_iterator = std::reverse_iterator;`| -|**difference_type**|`using difference_type = ptrdiff_t;`| -|**iterator**|`using iterator = const_iterator;`| -|**npos**|`static constexpr size_type npos = size_type(-1);`| -|**pointer**|`using pointer = value_type*;`| -|**reference**|`using reference = value_type&;`| -|**reverse_iterator**|`using reverse_iterator = const_reverse_iterator;`| -|**size_type**|`using size_type = size_t;`| -|**traits_type**|`using traits_type = Traits;`| -|**value_type**|`using value_type = CharType;`| +|**`const_iterator`**|Random-access iterator that can read **`const`** elements.| +|**`const_pointer`**|`using const_pointer = const value_type*;`| +|**`const_reference`**|`using const_reference = const value_type&;`| +|**`const_reverse_iterator`**|`using const_reverse_iterator = std::reverse_iterator;`| +|**`difference_type`**|`using difference_type = ptrdiff_t;`| +|**`iterator`**|`using iterator = const_iterator;`| +|**`npos`**|`static constexpr size_type npos = size_type(-1);`| +|**`pointer`**|`using pointer = value_type*;`| +|**`reference`**|`using reference = value_type&;`| +|**`reverse_iterator`**|`using reverse_iterator = const_reverse_iterator;`| +|**`size_type`**|`using size_type = size_t;`| +|**`traits_type`**|`using traits_type = Traits;`| +|**`value_type`**|`using value_type = CharType;`| ### Member operators |Operator|Description| |-|-| -|[operator=](#op_eq)|Assigns a string_view or convertible string object to another string_view.| -|[operator\[\]](#op_at)|Returns the element at the specified index.| +|[`operator=`](#op_eq)|Assigns a `basic_string_view` or convertible string object to another `basic_string_view`.| +|[`operator[]`](#op_at)|Returns the element at the specified index.| ### Member functions |Member function|Description| |-|-| -|[at](#at)|Returns a const_reference to the element at a specified location.| -|[back](#back)|Returns a const_reference to the last element.| -|[begin](#begin)|Returns a const iterator addressing the first element. (string_views are immutable.)| -|[cbegin](#cbegin)|Same as [begin](#begin).| -|[cend](#cend)|Returns a const iterator that points to one past the last element.| -|[copy](#copy)|Copies at most a specified number of characters from an indexed position in a source string_view to a target character array. (Not recommended. Use _Copy_s instead.)| -|[_Copy_s](#_copy_s)|Secure CRT copy function.| -|[compare](#compare)|Compares a string_view with a specified string_view to determine if they're equal or if one is lexicographically less than the other.| -|[crbegin](#crbegin)|Same as [rbegin](#rbegin).| -|[crend](#crend)|Same as [rend](#rend).| -|[data](#data)|Returns a raw non-owning pointer to the character sequence.| -|[empty](#empty)|Tests whether the string_view contains characters.| -|[end](#end)|Same as [cend](#cend).| -|[ends_with](#ends_with)C++20|Check whether a string view ends with a specified suffix.| -|[find](#find)|Searches in a forward direction for the first occurrence of a substring that matches a specified sequence of characters.| -|[find_first_not_of](#find_first_not_of)|Searches for the first character that is not any element of a specified string_view or convertible string object.| -|[find_first_of](#find_first_of)|Searches for the first character that matches any element of a specified string_view or convertible string object.| -|[find_last_not_of](#find_last_not_of)|Searches for the last character that is not any element of a specified string_view or convertible string object.| -|[find_last_of](#find_last_of)|Searches for the last character that is an element of a specified string_view or convertible string object.| -|[front](#front)|Returns a const_reference to the first element.| -|[length](#length)|Returns the current number of elements.| -|[max_size](#max_size)|Returns the maximum number of characters a string_view could contain.| -|[rbegin](#rbegin)|Returns a const iterator that addresses the first element in a reversed string_view.| -|[remove_prefix](#remove_prefix)|Moves the pointer forward by the specified number of elements.| -|[remove_suffix](#remove_suffix)|Reduces the size of the view by the specified number of elements starting from the back.| -|[rend](#rend)|Returns a const iterator that points to one past the last element in a reversed string_view.| -|[rfind](#rfind)|Searches a string_view in reverse for the first occurrence of a substring that matches a specified sequence of characters.| -|[size](#size)|Returns the current number of elements.| -|[starts_with](#starts_with)C++20|Check whether a string view starts with a given prefix.| -|[substr](#substr)|Returns a substring of a specified length starting at a specified index.| -|[swap](#swap)|Exchange the contents of two string_views.| +|[`at`](#at)|Returns a `const_reference` to the element at a specified location.| +|[`back`](#back)|Returns a `const_reference` to the last element.| +|[`begin`](#begin)|Returns a `const` iterator addressing the first element. (`basic_string_view`s are immutable.)| +|[`cbegin`](#cbegin)|Same as [`begin`](#begin).| +|[`cend`](#cend)|Returns a `const` iterator that points to one past the last element.| +|[`copy`](#copy)|Copies at most a specified number of characters from an indexed position in a source `basic_string_view` to a target character array. (Not recommended. Use `_Copy_s` instead.)| +|[`_Copy_s`](#_copy_s)|Secure CRT copy function.| +|[`compare`](#compare)|Compares a `basic_string_view` with a specified `basic_string_view` to determine if they're equal or if one is lexicographically less than the other.| +|[`crbegin`](#crbegin)|Same as [`rbegin`](#rbegin).| +|[`crend`](#crend)|Same as [`rend`](#rend).| +|[`data`](#data)|Returns a raw non-owning pointer to the character sequence.| +|[`empty`](#empty)|Tests whether the `basic_string_view` contains characters.| +|[`end`](#end)|Same as [`cend`](#cend).| +|[`ends_with`](#ends_with)C++20|Check whether a string view ends with a specified suffix.| +|[`find`](#find)|Searches in a forward direction for the first occurrence of a substring that matches a specified sequence of characters.| +|[`find_first_not_of`](#find_first_not_of)|Searches for the first character that isn't any element of a specified `basic_string_view` or convertible string object.| +|[`find_first_of`](#find_first_of)|Searches for the first character that matches any element of a specified `basic_string_view` or convertible string object.| +|[`find_last_not_of`](#find_last_not_of)|Searches for the last character that isn't any element of a specified `basic_string_view` or convertible string object.| +|[`find_last_of`](#find_last_of)|Searches for the last character that is an element of a specified `basic_string_view` or convertible string object.| +|[`front`](#front)|Returns a `const_reference` to the first element.| +|[`length`](#length)|Returns the current number of elements.| +|[`max_size`](#max_size)|Returns the maximum number of characters a `basic_string_view` could contain.| +|[`rbegin`](#rbegin)|Returns a `const` iterator that addresses the first element in a reversed `basic_string_view`.| +|[`remove_prefix`](#remove_prefix)|Moves the pointer forward by the specified number of elements.| +|[`remove_suffix`](#remove_suffix)|Reduces the size of the view by the specified number of elements starting from the back.| +|[`rend`](#rend)|Returns a `const` iterator that points to one past the last element in a reversed `basic_string_view`.| +|[`rfind`](#rfind)|Searches a `basic_string_view` in reverse for the first occurrence of a substring that matches a specified sequence of characters.| +|[`size`](#size)|Returns the current number of elements.| +|[`starts_with`](#starts_with)C++20|Check whether a string view starts with a given prefix.| +|[`substr`](#substr)|Returns a substring of a specified length starting at a specified index.| +|[`swap`](#swap)|Exchange the contents of two `basic_string_view` objects.| ## Remarks -If a function is asked to generate a sequence longer than [max_size](#max_size) elements, the function reports a length error by throwing an object of type [length_error](../standard-library/length-error-class.md). +If a function is asked to generate a sequence longer than [`max_size`](#max_size) elements, the function reports a length error by throwing an object of type [`length_error`](../standard-library/length-error-class.md). ## Requirements [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_string_view::at +## `basic_string_view::at` -Returns a const_reference to the character at the specified 0-based index. +Returns a `const_reference` to the character at the specified zero-based index. ```cpp constexpr const_reference at(size_type offset) const; @@ -157,20 +154,20 @@ constexpr const_reference at(size_type offset) const; ### Parameters -*offset*\ +*`offset`*\ The index of the element to be referenced. -### Return Value +### Return value -A const_reference to the character at the position specified by the parameter index. +A `const_reference` to the character at the position specified by the parameter index. ### Remarks -The first element has an index of zero and the following elements are indexed consecutively by the positive integers, so that a string_view of length *n* has an *n*th element indexed by the number *n -* 1. **at** throws an exception for invalid indices, unlike [operator\[\]](#op_at). +The first element has an index of zero and the following elements are indexed consecutively by the positive integers, so that a `basic_string_view` of length *`n`* has an *`n`*th element indexed by the number `n - 1`. **`at`** throws an exception for invalid indices, unlike [`operator[]`](#op_at). -In general, we recommend that **at** for sequences such as `std::vector` and string_view should never be used. An invalid index passed to a sequence is a logic error that should be discovered and fixed during development. If a program isn't certain that its indices are valid, it should test them, not call at() and rely on exceptions to defend against careless programming. +In general, we recommend that **`at`** for sequences such as `std::vector` and `basic_string_view` should never be used. An invalid index passed to a sequence is a logic error that should be discovered and fixed during development. If a program isn't certain that its indices are valid, it should test them, not call `at()` and rely on exceptions to defend against careless programming. -See [basic_string_view::operator\[\]](#op_at) for more information. +For more information, see [`basic_string_view::operator[]`](#op_at). ### Example @@ -189,27 +186,27 @@ int main() } ``` -## basic_string_view::back +## `basic_string_view::back` -Returns a const_reference to the last element. +Returns a `const_reference` to the last element. ```cpp constexpr const_reference back() const; ``` -### Return Value +### Return value -A const_reference to the last element in the string_view. +A `const_reference` to the last element in the `basic_string_view`. ### Remarks -Throws an exception if the string_view is empty. +Throws an exception if the `basic_string_view` is empty. -Keep in mind that after a string_view is modified, for example by calling `remove_suffix`, then the element returned by this function is no longer the last element in the underlying data. +Keep in mind that after a `basic_string_view` is modified, for example by calling `remove_suffix`, then the element returned by this function is no longer the last element in the underlying data. ### Example -A `string_view` that is constructed with a C string literal does not include the terminating null. So in the following example, `back` returns `'p'` and not `'\0'`. +A `string_view` that is constructed with a C string literal doesn't include the terminating null. So in the following example, `back` returns `'p'` and not `'\0'`. ```cpp char c[] = "Help"; // char[5] @@ -225,9 +222,9 @@ string_view e = "embedded\0nulls"sv; cout << boolalpha << (e.back() == 's'); // true ``` -## basic_string_view::basic_string_view +## `basic_string_view::basic_string_view` -Constructs a string_view. +Constructs a `basic_string_view`. ```cpp constexpr basic_string_view() noexcept; @@ -238,51 +235,51 @@ constexpr basic_string_view(const charT* str, size_type len); ### Parameters -*str*\ +*`str`*\ The pointer to the character values. -*len*\ +*`len`*\ The number of characters to include in the view. ### Remarks -The constructors with a charT* parameter assume that the input is null-terminated, but the terminating null is not included in the string_view. +The constructors with a `charT*` parameter assume that the input is null-terminated, but the terminating null isn't included in the `basic_string_view`. -You can also construct a string_view with a literal. See [operator""sv](string-view-operators.md#op_sv). +You can also construct a `basic_string_view` with a literal. See [`operator"" sv`](string-view-operators.md#op_sv). -## basic_string_view::begin +## `basic_string_view::begin` -Same as [cbegin](#cbegin). +Same as [`cbegin`](#cbegin). ```cpp constexpr const_iterator begin() const noexcept; ``` -### Return Value +### Return value -Returns a const_iterator addressing the first element. +Returns a `const_iterator` addressing the first element. -## basic_string_view::cbegin +## `basic_string_view::cbegin` -Returns a const_iterator that addresses the first element in the range. +Returns a `const_iterator` that addresses the first element in the range. ```cpp constexpr const_iterator cbegin() const noexcept; ``` -### Return Value +### Return value A **`const`** random-access iterator that points at the first element of the range, or the location just beyond the end of an empty range (for an empty range, `cbegin() == cend()`). -## basic_string_view::cend +## `basic_string_view::cend` -Returns a const_iterator that addresses the location just beyond the last element in a range. +Returns a `const_iterator` that addresses the location just beyond the last element in a range. ```cpp constexpr const_iterator cend() const noexcept; ``` -### Return Value +### Return value A **`const`** random-access iterator that points just beyond the end of the range. @@ -290,9 +287,9 @@ A **`const`** random-access iterator that points just beyond the end of the rang The value returned by `cend` shouldn't be dereferenced. -## basic_string_view::compare +## `basic_string_view::compare` -Does a case-sensitive comparison with a specified string_view (or a convertible string type) to determine if the two objects are equal or if one is lexicographically less than the other. The [\ operators](string-view-operators.md) use this member function to do comparisons. +Does a case-sensitive comparison with a specified `basic_string_view` (or a convertible string type) to determine if the two objects are equal or if one is lexicographically less than the other. The [`` operators](string-view-operators.md) use this member function to do comparisons. ```cpp constexpr int compare(basic_string_view strv) const noexcept; @@ -305,29 +302,29 @@ constexpr int compare(size_type pos, size_type num, const charT* ptr, size_type ### Parameters -*strv*\ -The string_view that is to be compared to this string_view. +*`strv`*\ +The `basic_string_view` that is to be compared to this `basic_string_view`. -*pos*\ -The index of this string_view at which the comparison begins. +*`pos`*\ +The index of this `basic_string_view` at which the comparison begins. -*num*\ -The maximum number of characters from this string_view to be compared. +*`num`*\ +The maximum number of characters from this `basic_string_view` to be compared. -*num2*\ -The maximum number of characters from *strv* to be compared. +*`num2`*\ +The maximum number of characters from *`strv`* to be compared. -*offset*\ -The index of *strv* at which the comparison begins. +*`offset`*\ +The index of *`strv`* at which the comparison begins. -*ptr*\ -The C string to be compared to this string_view. +*`ptr`*\ +The C string to be compared to this `basic_string_view`. -### Return Value +### Return value -- A negative value if this `string_view` is less than *strv* or *ptr* +- A negative value if this `basic_string_view` is less than *`strv`* or *`ptr`* - Zero if the two character sequences are equal -- A positive value if this `string_view` is greater than *strv* or *ptr* +- A positive value if this `basic_string_view` is greater than *`strv`* or *`ptr`* ### Remarks @@ -441,9 +438,9 @@ cs_C: ACAB The 3 characters from position 1 of sv_I are equal to the first 3 characters of cs_C. ``` -## basic_string_view::copy +## `basic_string_view::copy` -Copies at most a specified number of characters from an indexed position in a source string_view to a target character array. We recommend that you use the secure function [basic_string_view::_Copy_s](#_copy_s) instead. +Copies at most a specified number of characters from an indexed position in a source `basic_string_view` to a target character array. We recommend that you use the secure function [`basic_string_view::_Copy_s`](#_copy_s) instead. ```cpp size_type copy(charT* ptr, size_type count, size_type offset = 0) const; @@ -451,26 +448,26 @@ size_type copy(charT* ptr, size_type count, size_type offset = 0) const; ### Parameters -*ptr*\ +*`ptr`*\ The target character array to which the elements are to be copied. -*count*\ -The number of characters to be copied, at most, from the source string_view. +*`count`*\ +The number of characters to be copied, at most, from the source `basic_string_view`. -*offset*\ -The beginning position in the source string_view from which copies are to be made. +*`offset`*\ +The beginning position in the source `basic_string_view` from which copies are to be made. -### Return Value +### Return value The number of characters copied. ### Remarks -A null character is not appended to the end of the copy. +A null character isn't appended to the end of the copy. -## basic_string_view::_Copy_s +## `basic_string_view::_Copy_s` -Secure CRT copy function to be used instead of [copy](#copy). +Secure CRT copy function to be used instead of [`copy`](#copy). ```cpp size_type _Copy_s( @@ -482,103 +479,103 @@ size_type _Copy_s( ### Parameters -*dest*\ +*`dest`*\ The target character array to which the elements are to be copied. -*dest_size*\ -The size of *dest*. +*`dest_size`*\ +The size of *`dest`*. -_ *Count* +*`count`* The number of characters to be copied, at most, from the source string. -*_Off*\ +*`_Off`*\ The beginning position in the source string from which copies are to be made. -### Return Value +### Return value The number of characters copied. ### Remarks -A null character is not appended to the end of the copy. +A null character isn't appended to the end of the copy. For more information, see [c-runtime-library/security-features-in-the-crt](../c-runtime-library/security-features-in-the-crt.md). -## basic_string_view::crbegin +## `basic_string_view::crbegin` -Returns a const_reverse_iterator that addresses the first element in a reversed string_view. +Returns a `const_reverse_iterator` that addresses the first element in a reversed `basic_string_view`. ```cpp constexpr const_reverse_iterator crbegin() const noexcept; ``` -### Return Value +### Return value -A const_reverse_iterator that addresses the first element in a reversed string_view. +A `const_reverse_iterator` that addresses the first element in a reversed `basic_string_view`. -## basic_string_view::crend +## `basic_string_view::crend` -Same as [rend](#rend). +Same as [`rend`](#rend). ```cpp constexpr const_reverse_iterator crend() const noexcept; ``` -### Return Value +### Return value -Returns a const_reverse_iterator that addresses one past the end of a reversed string_view. +Returns a `const_reverse_iterator` that addresses one past the end of a reversed `basic_string_view`. -## basic_string_view::data +## `basic_string_view::data` -Returns a raw non-owning pointer to the const character sequence of the object that was used to construct the string_view. +Returns a raw non-owning pointer to the const character sequence of the object that was used to construct the `basic_string_view`. ```cpp constexpr value_type *data() const noexcept; ``` -### Return Value +### Return value A pointer-to-const to the first element of the character sequence. ### Remarks -The pointer cannot modify the characters. +The pointer can't modify the characters. -A sequence of string_view characters is not necessarily null-terminated. The return type for `data` is not a valid C string, because no null character gets appended. The null character '\0' has no special meaning in an object of type string_view and may be a part of the string_view object just like any other character. +A sequence of `basic_string_view` characters isn't necessarily null-terminated. The return type for `data` isn't a valid C string, because no null character gets appended. The null character `\0` has no special meaning in an object of type `basic_string_view` and may be a part of the `basic_string_view` object just like any other character. -## basic_string_view::empty +## `basic_string_view::empty` -Tests whether the string_view contains characters or not. +Tests whether the `basic_string_view` contains characters or not. ```cpp constexpr bool empty() const noexcept; ``` -### Return Value +### Return value -**`true`** if the string_view object contains no characters; **`false`** if it has at least one character. +**`true`** if the `basic_string_view` object contains no characters; **`false`** if it has at least one character. ### Remarks -The member function is equivalent to [size](#size)() == 0. +The member function is equivalent to [`size`](#size)() == 0. -## basic_string_view::end +## `basic_string_view::end` -Returns a random-access const_iterator that points to one past the last element. +Returns a random-access `const_iterator` that points to one past the last element. ```cpp constexpr const_iterator end() const noexcept; ``` -### Return Value +### Return value -Returns a random-access const_iterator that points to one past the last element. +Returns a random-access `const_iterator` that points to one past the last element. ### Remarks -`end` is used to test whether a const_iterator has reached the end of its string_view. The value returned by `end` shouldn't be dereferenced. +`end` is used to test whether a `const_iterator` has reached the end of its `basic_string_view`. The value returned by `end` shouldn't be dereferenced. -## basic_string_view::ends_with +## `basic_string_view::ends_with` Check whether the string view ends with the specified suffix. @@ -590,17 +587,17 @@ bool ends_with(const basic_string_view sv) const noexcept; ### Parameters -*c*\ +*`c`*\ The single character suffix to look for. -*sv*\ +*`sv`*\ A string view containing the suffix to look for.\ -You can pass a `std::basic_string`, which converts to a string view. +You can pass a `std::basic_string`, which converts to a `basic_string_view`. -*x*\ +*`x`*\ Null-terminated character string containing the suffix to look for. -### Return Value +### Return value `true` if the string view ends with the specified suffix; `false` otherwise. @@ -608,7 +605,7 @@ Null-terminated character string containing the suffix to look for. `ends_with()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -See [starts_with](#starts_with) to check if a string view starts with the specified prefix. +See [`starts_with`](#starts_with) to check if a string view starts with the specified prefix. ### Example @@ -636,9 +633,9 @@ false true ``` -## basic_string_view::find +## `basic_string_view::find` -Searches a `string_view` in a forward direction for the first occurrence of a character or substring that matches a specified sequence of character(s). +Searches a `basic_string_view` in a forward direction for the first occurrence of a character or substring that matches a specified sequence of character(s). ```cpp constexpr size_type find(basic_string_view str, size_type offset = 0) const noexcept; @@ -649,28 +646,28 @@ constexpr size_type find(const charT* ptr, size_type offset = 0) const; ### Parameters -*str*\ -The `string_view` for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ -The number of characters in *ptr*, counting forward from the first character. +*`count`*\ +The number of characters in *`ptr`*, counting forward from the first character. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_first_not_of +## `basic_string_view::find_first_not_of` -Searches for the first character that is not an element of a specified string_view or convertible string object. +Searches for the first character that isn't an element of a specified `basic_string_view` or convertible string object. ```cpp constexpr size_type find_first_not_of(basic_string_view str, size_type offset = 0) const noexcept; @@ -681,28 +678,28 @@ constexpr size_type find_first_not_of(const charT* ptr, size_type offset = 0) co ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_first_of +## `basic_string_view::find_first_of` -Searches for the first character that matches any element of a specified string_view. +Searches for the first character that matches any element of a specified `basic_string_view`. ```cpp constexpr size_type find_first_of(basic_string_view str, size_type offset = 0) const noexcept; @@ -713,28 +710,28 @@ constexpr size_type find_first_of(const charT* str, size_type offset = 0) const; ### Parameters -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_last_not_of +## `basic_string_view::find_last_not_of` -Searches for the last character that is not any element of a specified string_view. +Searches for the last character that isn't any element of a specified `basic_string_view`. ```cpp constexpr size_type find_last_not_of(basic_string_view str, size_type offset = npos) const noexcept; @@ -745,28 +742,28 @@ constexpr size_type find_last_not_of(const charT* ptr, size_type offset = npos) ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to finish. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ -The number of characters, counting forward from the first character, in *ptr*. +*`count`*\ +The number of characters, counting forward from the first character, in *`ptr`*. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `string_view::npos`. -## basic_string_view::find_last_of +## `basic_string_view::find_last_of` -Searches for the last character that matches any element of a specified string_view. +Searches for the last character that matches any element of a specified `basic_string_view`. ```cpp constexpr size_type find_last_of(basic_string_view str, size_type offset = npos) const noexcept; @@ -777,42 +774,42 @@ constexpr size_type find_last_of(const charT* ptr, size_type offset = npos) cons ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to finish. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -### Return Value +### Return value The index of the last character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::front +## `basic_string_view::front` -Returns a const_reference to the first element. +Returns a `const_reference` to the first element. ```cpp constexpr const_reference front() const; ``` -### Return Value +### Return value -A const_reference to the first element. +A `const_reference` to the first element. ### Remarks -Throws an exception if the string_view is empty. +Throws an exception if the `basic_string_view` is empty. -## basic_string_view::length +## `basic_string_view::length` Returns the current number of elements. @@ -822,27 +819,27 @@ constexpr size_type length() const noexcept; ### Remarks -The member function is the same as [size](#size). +The member function is the same as [`size`](#size). -## basic_string_view::max_size +## `basic_string_view::max_size` -Returns the maximum number of characters a string_view can contain. +Returns the maximum number of characters a `basic_string_view` can contain. ```cpp constexpr size_type max_size() const noexcept; ``` -### Return Value +### Return value -The maximum number of characters a string_view can contain. +The maximum number of characters a `basic_string_view` can contain. ### Remarks -An exception of type [length_error](../standard-library/length-error-class.md) is thrown when an operation produces a string_view with a length greater than `max_size()`. +An exception of type [`length_error`](../standard-library/length-error-class.md) is thrown when an operation produces a `basic_string_view` with a length greater than `max_size()`. -## basic_string_view::operator= +## `basic_string_view::operator=` -Assigns a string_view or convertible string object to another string_view. +Assigns a `basic_string_view` or convertible string object to another `basic_string_view`. ```cpp constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default; @@ -855,9 +852,9 @@ constexpr basic_string_view& operator=(const basic_string_view&) noexcept = defa string_view s2 = s; ``` -## basic_string_view::operator[] +## `basic_string_view::operator[]` -Provides a const_reference to the character with a specified index. +Provides a `const_reference` to the character with a specified index. ```cpp constexpr const_reference operator[](size_type offset) const; @@ -865,42 +862,42 @@ constexpr const_reference operator[](size_type offset) const; ### Parameters -*offset*\ +*`offset`*\ The index of the element to be referenced. -### Return Value +### Return value -A const_reference to the character at the position specified by the parameter index. +A `const_reference` to the character at the position specified by the parameter index. ### Remarks -The first element has an index of zero, and the following elements are indexed consecutively by the positive integers, so that a string_view of length *n* has an *n*th element indexed by the number *n* - 1. +The first element has an index of zero, and the following elements are indexed consecutively by the positive integers, so that a `basic_string_view` of length *`n`* has an *`n`*th element indexed by the number `n-1`. -`operator[]` is faster than the member function [at](#at) for providing read access to the elements of a string_view. +`operator[]` is faster than the member function [`at`](#at) for providing read access to the elements of a `basic_string_view`. -`operator[]` does not check whether the index passed as an argument is valid. An invalid index passed to `operator[]` results in undefined behavior. +`operator[]` doesn't check whether the index passed as an argument is valid. An invalid index passed to `operator[]` results in undefined behavior. The reference returned may be invalidated if the underlying string data is modified or deleted by the owning object. -When compiling with [\_ITERATOR\_DEBUG\_LEVEL](../standard-library/iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the string_view. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). +When compiling with [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the `basic_string_view`. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). -## basic_string_view::rbegin +## `basic_string_view::rbegin` -Returns a const iterator to the first element in a reversed string_view. +Returns a `const` iterator to the first element in a reversed `basic_string_view`. ```cpp constexpr const_reverse_iterator rbegin() const noexcept; ``` -### Return Value +### Return value -Returns a random-access iterator to the first element in a reversed string_view, addressing what would be the last element in the corresponding unreversed string_view. +Returns a random-access iterator to the first element in a reversed `basic_string_view`, addressing what would be the last element in the corresponding unreversed `basic_string_view`. ### Remarks -`rbegin` is used with a reversed string_view just as [begin](#begin) is used with a string_view. `rbegin` can be used to initialize an iteration backwards. +`rbegin` is used with a reversed `basic_string_view` just as [`begin`](#begin) is used with a `basic_string_view`. `rbegin` can be used to initialize an iteration backwards. -## basic_string_view::remove_prefix +## `basic_string_view::remove_prefix` Moves the pointer forward by the specified number of elements. @@ -910,9 +907,9 @@ constexpr void remove_prefix(size_type n); ### Remarks -Leaves the underlying data unchanged. Moves the string_view pointer forward by n elements and sets the private `size` data member to size - n. +Leaves the underlying data unchanged. Moves the `basic_string_view` pointer forward by `n` elements and sets the private `size` data member to `size - n`. -## basic_string_view::remove_suffix +## `basic_string_view::remove_suffix` Reduces the size of the view by the specified number of elements starting from the back. @@ -922,27 +919,27 @@ constexpr void remove_suffix(size_type n); ### Remarks -Leaves the underlying data and the pointer to it unchanged. Sets the private `size` data member to size - n. +Leaves the underlying data and the pointer to it unchanged. Sets the private `size` data member to `size - n`. -## basic_string_view::rend +## `basic_string_view::rend` -Returns a const iterator that points to one past the last element in a reversed string_view. +Returns a `const` iterator that points to one past the last element in a reversed `basic_string_view`. ```cpp constexpr reverse_iterator rend() const noexcept; ``` -### Return Value +### Return value -A const reverse random-access iterator that points to one past the last element in a reversed string_view. +A `const` reverse random-access iterator that points to one past the last element in a reversed `basic_string_view`. ### Remarks -`rend` is used with a reversed string_view just as [end](#end) is used with a string_view. `rend` can be used to test whether a reverse iterator has reached the end of its string_view. The value returned by `rend` shouldn't be dereferenced. +`rend` is used with a reversed `basic_string_view` just as [`end`](#end) is used with a `basic_string_view`. `rend` can be used to test whether a reverse iterator has reached the end of its `basic_string_view`. The value returned by `rend` shouldn't be dereferenced. -## basic_string_view::rfind +## `basic_string_view::rfind` -Searches a string_view in reverse for a substring that matches a specified sequence of characters. +Searches a `basic_string_view` in reverse for a substring that matches a specified sequence of characters. ```cpp constexpr size_type rfind(basic_string_view str, size_type offset = npos) const noexcept; @@ -953,42 +950,42 @@ constexpr size_type rfind(const charT* ptr, size_type offset = npos) const; ### Parameters -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring when successful; otherwise `npos`. -## basic_string_view::size +## `basic_string_view::size` -Returns the number of elements in the string_view. +Returns the number of elements in the `basic_string_view`. ```cpp constexpr size_type size() const noexcept; ``` -### Return Value +### Return value -The length of the string_view. +The length of the `basic_string_view`. ### Remarks -A string_view can modify its length, for example by `remove_prefix` and `remove_suffix`. Because this does not modify the underlying string data, the size of a string_view is not necessarily the size of the underlying data. +A `basic_string_view` can modify its length, for example by `remove_prefix` and `remove_suffix`. Because this doesn't modify the underlying string data, the size of a `basic_string_view` isn't necessarily the size of the underlying data. -## basic_string_view::starts_with +## `basic_string_view::starts_with` Check whether the string view starts with the specified prefix. @@ -1000,25 +997,25 @@ bool starts_with(const basic_string_view sv) const noexcept; ### Parameters -*c*\ +*`c`*\ The single character prefix to look for. -*sv*\ +*`sv`*\ A string view containing the prefix to look for.\ You can pass a `std::basic_string`, which converts to a string view. -*x*\ +*`x`*\ Null-terminated character string containing the prefix to look for. -### Return Value +### Return value `true` if the string starts with the specified prefix; `false` otherwise. ### Remarks -`starts_with()` is new in C++20. To use it, specify the [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later compiler option. +`starts_with()` is new in C++20. To use it, specify the [`std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -See [ends_with](#ends_with) to see if a string ends with a suffix. +See [`ends_with`](#ends_with) to see if a string ends with a suffix. ### Example @@ -1046,9 +1043,9 @@ false true ``` -## basic_string_view::substr +## `basic_string_view::substr` -Returns a string_view that represents (at most) the specified number of characters from a specified position. +Returns a `basic_string_view` that represents (at most) the specified number of characters from a specified position. ```cpp constexpr basic_string_view substr(size_type offset = 0, size_type count = npos) const; @@ -1056,19 +1053,19 @@ constexpr basic_string_view substr(size_type offset = 0, size_type count = npos) ### Parameters -*offset*\ +*`offset`*\ An index locating the element at the position from which the copy is made, with a default value of 0. -*count*\ +*`count`*\ The number of characters to include in the substring, if they're present. -### Return Value +### Return value -A string_view object that represents the specified subsequence of elements. +A `basic_string_view` object that represents the specified subsequence of elements. -## basic_string_view::swap +## `basic_string_view::swap` -Exchanges two string_views, in other words the pointers to the underlying string data, and the size values. +Exchanges two `basic_string_view`s, in other words the pointers to the underlying string data, and the size values. ```cpp constexpr void swap(basic_string_view& sv) noexcept; @@ -1076,10 +1073,10 @@ constexpr void swap(basic_string_view& sv) noexcept; ### Parameters -*sv*\ -The source string_view whose pointer and size values are to be exchanged with that of the destination string_view. +*`sv`*\ +The source `basic_string_view` whose pointer and size values are to be exchanged with that of the destination `basic_string_view`. ## See also -[\](../standard-library/string-view.md)\ +[``](../standard-library/string-view.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/basic-stringbuf-class.md b/docs/standard-library/basic-stringbuf-class.md index 81146d1a38..465e997c4f 100644 --- a/docs/standard-library/basic-stringbuf-class.md +++ b/docs/standard-library/basic-stringbuf-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: basic_stringbuf Class" title: "basic_stringbuf Class" -ms.date: "11/04/2016" +ms.date: 06/10/2022 f1_keywords: ["sstream/std::basic_stringbuf", "sstream/std::basic_stringbuf::allocator_type", "sstream/std::basic_stringbuf::char_type", "sstream/std::basic_stringbuf::int_type", "sstream/std::basic_stringbuf::off_type", "sstream/std::basic_stringbuf::pos_type", "sstream/std::basic_stringbuf::traits_type", "sstream/std::basic_stringbuf::overflow", "sstream/std::basic_stringbuf::pbackfail", "sstream/std::basic_stringbuf::seekoff", "sstream/std::basic_stringbuf::seekpos", "sstream/std::basic_stringbuf::str", "sstream/std::basic_stringbuf::underflow"] helpviewer_keywords: ["std::basic_stringbuf [C++]", "std::basic_stringbuf [C++], allocator_type", "std::basic_stringbuf [C++], char_type", "std::basic_stringbuf [C++], int_type", "std::basic_stringbuf [C++], off_type", "std::basic_stringbuf [C++], pos_type", "std::basic_stringbuf [C++], traits_type", "std::basic_stringbuf [C++], overflow", "std::basic_stringbuf [C++], pbackfail", "std::basic_stringbuf [C++], seekoff", "std::basic_stringbuf [C++], seekpos", "std::basic_stringbuf [C++], str", "std::basic_stringbuf [C++], underflow"] ms.assetid: 40c85f9e-42a5-4a65-af5c-23c8e3bf8113 +ms.custom: devdivchpfy22 --- + # basic_stringbuf Class Describes a stream buffer that controls the transmission of elements of type `Elem`, whose character traits are determined by the class `Tr`, to and from a sequence of elements stored in an array object. @@ -148,11 +150,11 @@ The character to insert into the buffer, or `traits_type::eof`. ### Return Value -If the function cannot succeed, it returns `traits_type::eof`. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). +If the function can't succeed, it returns `traits_type::eof`. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). ### Remarks -If *\_Meta* does not compare equal to **traits_type::**[eof](../standard-library/char-traits-struct.md#eof), the protected virtual member function tries to insert the element **traits_type::**[to_char_type](../standard-library/char-traits-struct.md#to_char_type)(*\_Meta*) into the output buffer. It can do so in various ways: +If *\_Meta* doesn't compare equal to **traits_type::**[eof](../standard-library/char-traits-struct.md#eof), the protected virtual member function tries to insert the element **traits_type::**[to_char_type](../standard-library/char-traits-struct.md#to_char_type)(*\_Meta*) into the output buffer. It can do so in various ways: - If a write position is available, it can store the element into the write position and increment the next pointer for the output buffer. @@ -173,7 +175,7 @@ The character to insert into the buffer, or `traits_type::eof`. ### Return Value -If the function cannot succeed, it returns `traits_type::eof`. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). +If the function can't succeed, it returns `traits_type::eof`. Otherwise, it returns **traits_type::**[not_eof](../standard-library/char-traits-struct.md#not_eof)(_ *Meta*). ### Remarks @@ -276,11 +278,11 @@ The new string. ### Return Value -Returns an object of class [basic_string](../standard-library/basic-string-class.md)\< **Elem**, **Tr**, Alloc **>,** whose controlled sequence is a copy of the sequence controlled by **\*this**. +Returns an object of class [basic_string](../standard-library/basic-string-class.md)\< **Elem**, **Tr**, Alloc **>,** whose controlled sequence is a copy of the sequence controlled by `*this`. ### Remarks -The first member function returns an object of class basic_string< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by **\*this**. The sequence copied depends on the stored stringbuf mode: +The first member function returns an object of class basic_string< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by `*this`. The sequence copied depends on the stored stringbuf mode: - If **mode & ios_base::out** is nonzero and an output buffer exists, the sequence is the entire output buffer ( [epptr](../standard-library/basic-streambuf-class.md#epptr) - [pbase](../standard-library/basic-streambuf-class.md#pbase) elements beginning with `pbase`). @@ -288,7 +290,7 @@ The first member function returns an object of class basic_string< **Elem**, **T - Otherwise, the copied sequence is empty. -The second member function deallocates any sequence currently controlled by **\*this**. It then allocates a copy of the sequence controlled by *_Newstr*. If **mode & ios_base::in** is nonzero, it sets the input buffer to start reading at the beginning of the sequence. If **mode & ios_base::out** is nonzero, it sets the output buffer to start writing at the beginning of the sequence. +The second member function deallocates any sequence currently controlled by `*this`. It then allocates a copy of the sequence controlled by *_Newstr*. If **mode & ios_base::in** is nonzero, it sets the input buffer to start reading at the beginning of the sequence. If **mode & ios_base::out** is nonzero, it sets the output buffer to start writing at the beginning of the sequence. ### Example @@ -344,7 +346,7 @@ virtual int_type underflow(); ### Return Value -If the function cannot succeed, it returns **traits_type::**[eof](../standard-library/char-traits-struct.md#eof). Otherwise, it returns the current element in the input stream, which are converted. +If the function can't succeed, it returns **traits_type::**[eof](../standard-library/char-traits-struct.md#eof). Otherwise, it returns the current element in the input stream, which is converted. ### Remarks diff --git a/docs/standard-library/basic-stringstream-class.md b/docs/standard-library/basic-stringstream-class.md index 959d0f0437..6b834225d7 100644 --- a/docs/standard-library/basic-stringstream-class.md +++ b/docs/standard-library/basic-stringstream-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: basic_stringstream Class" title: "basic_stringstream Class" -ms.date: "11/04/2016" +description: "Learn more about: basic_stringstream Class" +ms.date: 06/10/2022 f1_keywords: ["sstream/std::basic_stringstream", "sstream/std::basic_stringstream::allocator_type", "sstream/std::basic_stringstream::rdbuf", "sstream/std::basic_stringstream::str"] helpviewer_keywords: ["std::basic_stringstream [C++]", "std::basic_stringstream [C++], allocator_type", "std::basic_stringstream [C++], rdbuf", "std::basic_stringstream [C++], str"] -ms.assetid: 49629814-ca37-45c5-931b-4ff894e6ebd2 +ms.custom: devdivchpfy22 --- + # basic_stringstream Class Describes an object that controls insertion and extraction of elements and encoded objects using a stream buffer of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. @@ -85,7 +86,7 @@ An object of type `basic_string`. ### Remarks -The first constructor initializes the base class by calling [basic_iostream](../standard-library/basic-iostream-class.md)( **sb**), where `sb` is the stored object of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. It also initializes `sb` by calling basic_stringbuf< **Elem**, **Tr**, `Alloc`>( `_Mode`). +The first constructor initializes the base class by calling [basic_iostream](../standard-library/basic-iostream-class.md)( **sb**), where `sb` is the stored object of class [basic_stringbuf](../standard-library/basic-stringbuf-class.md)< **Elem**, **Tr**, `Alloc`>. It also initializes `sb` by calling basic_stringbuf< **Elem**, **Tr**, `Alloc`>(`_Mode`). The second constructor initializes the base class by calling basic_iostream( **sb**). It also initializes `sb` by calling basic_stringbuf< **Elem**, **Tr**, `Alloc`>(_ *Str*, `_Mode`). @@ -123,11 +124,11 @@ The new string. ### Return Value -Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by **\*this**. +Returns an object of class [basic_string](../standard-library/basic-string-class.md)< **Elem**, **Tr**, `Alloc`>, whose controlled sequence is a copy of the sequence controlled by `*this`. ### Remarks -The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**( `_Newstr`). +The first member function returns [rdbuf](#rdbuf) -> [str](../standard-library/basic-stringbuf-class.md#str). The second member function calls `rdbuf` -> **str**(`_Newstr`). ### Example diff --git a/docs/standard-library/bernoulli-distribution-class.md b/docs/standard-library/bernoulli-distribution-class.md index 0737a964d0..bd94744c71 100644 --- a/docs/standard-library/bernoulli-distribution-class.md +++ b/docs/standard-library/bernoulli-distribution-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: bernoulli_distribution Class" title: "bernoulli_distribution Class" -ms.date: "11/04/2016" +description: "Learn more about: bernoulli_distribution Class" +ms.date: 11/04/2016 f1_keywords: ["random/std::bernoulli_distribution", "random/std::bernoulli_distribution::reset", "random/std::bernoulli_distribution::p", "random/std::bernoulli_distribution::param", "random/std::bernoulli_distribution::min", "random/std::bernoulli_distribution::max", "random/std::bernoulli_distribution::operator()", "random/std::bernoulli_distribution::param_type", "random/std::bernoulli_distribution::param_type::p", "random/std::bernoulli_distribution::param_type::operator==", "random/std::bernoulli_distribution::param_type::operator!="] helpviewer_keywords: ["std::bernoulli_distribution [C++]", "std::bernoulli_distribution [C++], reset", "std::bernoulli_distribution [C++], p", "std::bernoulli_distribution [C++], param", "std::bernoulli_distribution [C++], min", "std::bernoulli_distribution [C++], max", "std::bernoulli_distribution [C++], param_type", "std::bernoulli_distribution [C++], param_type"] -ms.assetid: 586bcde1-95ca-411a-bf17-4aaf19482f34 --- # bernoulli_distribution Class @@ -14,30 +13,30 @@ Generates a Bernoulli distribution. ```cpp class bernoulli_distribution - { +{ public: - // types - typedef bool result_type; - struct param_type; - - // constructors and reset functions - explicit bernoulli_distribution(double p = 0.5); - explicit bernoulli_distribution(const param_type& parm); - void reset(); - - // generating functions - template - result_type operator()(URNG& gen); - template - result_type operator()(URNG& gen, const param_type& parm); - - // property functions - double p() const; - param_type param() const; - void param(const param_type& parm); - result_type min() const; - result_type max() const; - }; + // types + typedef bool result_type; + struct param_type; + + // constructors and reset functions + explicit bernoulli_distribution(double p = 0.5); + explicit bernoulli_distribution(const param_type& parm); + void reset(); + + // generating functions + template + result_type operator()(URNG& gen); + template + result_type operator()(URNG& gen, const param_type& parm); + + // property functions + double p() const; + param_type param() const; + void param(const param_type& parm); + result_type min() const; + result_type max() const; +}; ``` ### Parameters @@ -161,6 +160,7 @@ The second constructor constructs an object whose stored parameters are initiali Contains the parameters of the distribution. +```cpp struct param_type { typedef bernoulli_distribution distribution_type; param_type(double p = 0.5); @@ -169,6 +169,7 @@ struct param_type { bool operator==(const param_type& right) const; bool operator!=(const param_type& right) const; }; +``` ### Parameters diff --git a/docs/standard-library/bitset-class.md b/docs/standard-library/bitset-class.md index d57bcdecef..a70a5b0f93 100644 --- a/docs/standard-library/bitset-class.md +++ b/docs/standard-library/bitset-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: bitset Class" title: "bitset Class" -ms.date: "6/8/2021" +description: "Learn more about: bitset Class" +ms.date: 06/10/2022 f1_keywords: ["bitset/std::bitset", "bitset/std::bitset::element_type", "bitset/std::bitset::all", "bitset/std::bitset::any", "bitset/std::bitset::count", "bitset/std::bitset::flip", "bitset/std::bitset::none", "bitset/std::bitset::reset", "bitset/std::bitset::set", "bitset/std::bitset::size", "bitset/std::bitset::test", "bitset/std::bitset::to_string", "bitset/std::bitset::to_ullong", "bitset/std::bitset::to_ulong", "bitset/std::bitset::reference"] helpviewer_keywords: ["std::bitset [C++]", "std::bitset [C++], element_type", "std::bitset [C++], all", "std::bitset [C++], any", "std::bitset [C++], count", "std::bitset [C++], flip", "std::bitset [C++], none", "std::bitset [C++], reset", "std::bitset [C++], set", "std::bitset [C++], size", "std::bitset [C++], test", "std::bitset [C++], to_string", "std::bitset [C++], to_ullong", "std::bitset [C++], to_ulong", "std::bitset [C++], reference"] +ms.custom: devdivchpfy22 --- # `bitset` class @@ -69,15 +70,15 @@ A bit is set if its value is 1 and reset if its value is 0. To flip or invert a |Name|Description| |-|-| |[`operator!=`](#op_neq)|Tests a target `bitset` for inequality with a specified `bitset`.| -|[`operator&=`](#op_and_eq)|Does a bitwise combination of bitsets with the bitwise `AND` operation.| +|[`operator&=`](#op_and_eq)|Does a bitwise combination of bitsets with the bitwise "and" (`&`) operation.| |[`operator<<`](#op_lshift)|Shifts the bits in a `bitset` to the left a specified number of positions and returns the result to a new `bitset`.| |[`operator<<=`](#op_lshift_eq)|Shifts the bits in a `bitset` to the left a specified number of positions and returns the result to the targeted `bitset`.| |[`operator==`](#op_eq_eq)|Tests a target `bitset` for equality with a specified `bitset`.| |[`operator>>`](#op_rshift)|Shifts the bits in a `bitset` to the right a specified number of positions and returns the result to a new `bitset`.| |[`operator>>=`](#op_rshift_eq)|Shifts the bits in a `bitset` to the right a specified number of positions and returns the result to the targeted `bitset`.| |[`operator[]`](#op_at)|Returns a reference to a bit at a specified position in a `bitset` if the `bitset` is modifiable; otherwise, it returns the value of the bit at that position.| -|[operator^=](#op_xor_eq)|Does a bitwise combination of bitsets with the bitwise **XOR** (`^`) operation.| -|[`operator|=`](#op_or_eq)|Does a bitwise combination of bitsets with the bitwise **OR** (`|`) operation.| +|[operator^=](#op_xor_eq)|Does a bitwise combination of bitsets with the bitwise "xor" (`^`) operation.| +|[`operator|=`](#op_or_eq)|Does a bitwise combination of bitsets with the bitwise "or" (`|`) operation.| |[`operator~`](#op_not)|Inverts all the bits in a target `bitset` and returns the result.| ### Structures @@ -219,7 +220,7 @@ The character that is used to represent a one. The default is '1'. `4)` Constructs an object of class `bitset` and initializes bits from the characters provided in a string of zeros and ones. If any characters of the string are other than 0 or 1, the constructor throws an object of class [`invalid argument`](../standard-library/invalid-argument-class.md). If the position specified (*`pos`*) is beyond the length of the string, then the constructor throws an object of class [`out_of_range`](../standard-library/out-of-range-class.md). The constructor sets only those bits at position *j* in the `bitset` for which the character in the string at position `pos + j` is 1. By default, *`pos`* is 0. -`5)` Similar to `4)` but includes an another parameter, *`count`*, that specifies the number of bits to initialize. It has two optional parameters, *`_Zero`* and *`_One`*, which indicate what character in *`str`* should be interpreted to mean a 0 bit and a 1 bit, respectively. +`5)` Similar to `4)` but includes another parameter, *`count`*, that specifies the number of bits to initialize. It has two optional parameters, *`_Zero`* and *`_One`*, which indicate what character in *`str`* should be interpreted to mean a 0 bit and a 1 bit, respectively. `6)` Constructs an object of class `bitset`, initializing the N bits to values that correspond to the characters provided in a C-style character string of zeros and ones. You call the constructor without casting the string into a string type, for example: `bitset<5> b5("01011");` @@ -244,9 +245,9 @@ int main( ) cout << "The set of bits in bitset<5> b1( 6 ) is: ( " << b1 << " )." << endl; - // The template parameter N can be an expresssion + // The template parameter N can be an expression bitset< 2 * sizeof ( int ) > b2; - cout << "The set of bits in bitset<2 * sizeof ( int ) > b2 is: ( " + cout << "The set of bits in bitset< 2 * sizeof ( int ) > b2 is: ( " << b2 << " )." << endl; // The base two representation will be truncated @@ -555,12 +556,12 @@ bool operator!=(const bitset& right) const; #### Parameters -*right*\ +*`right`*\ The `bitset` that is to be compared to the target bitset for inequality. #### Return Value -**`true`** if the `bitset`s are different; **`false`** if they're the same. +**`true`** if the bitsets are different; **`false`** if they're the same. #### Remarks @@ -609,7 +610,7 @@ Bitset b1 is different from bitset b3. ### `operator&=` -Does a bitwise combination of bitsets with the bitwise `AND` (`&`) operation. +Does a bitwise combination of bitsets with the bitwise "and" (`&`) operation. ```cpp bitset& operator&=(const bitset& right); @@ -622,13 +623,13 @@ The `bitset` that is to be combined bitwise with the target bitset. #### Return Value -The modified target bitset that results from the bitwise `AND` operation with the `bitset` specified as a parameter. +The modified target bitset that results from the bitwise "and" (`&`) operation with the `bitset` specified as a parameter. #### Remarks Two bits combined by the `AND` operator return **`true`** if each bit is true; otherwise, their combination returns **`false`**. -The two `bitset`s must be the same size. +The two bitsets must be the same size. #### Example @@ -788,7 +789,7 @@ The `bitset` that is to be compared to the target bitset for equality. #### Return Value -**`true`** if the `bitset`s are the same; **`false`** if they're different. +**`true`** if the bitsets are the same; **`false`** if they're different. #### Remarks @@ -951,7 +952,7 @@ The position locating the bit within the `bitset`. #### Remarks -When you define [\_ITERATOR\_DEBUG\_LEVEL](../standard-library/iterator-debug-level.md) as 1 or 2 in your build, a runtime error will occur in your executable if you attempt to access an element outside the bounds of the `bitset`. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). +When you define [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) as 1 or 2 in your build, a runtime error will occur in your executable if you attempt to access an element outside the bounds of the `bitset`. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). #### Example @@ -981,7 +982,7 @@ int main( ) ### `operator^=` -Does a bitwise combination of bitsets with the bitwise **XOR* (`^`) operation. +Does a bitwise combination of bitsets with the bitwise "xor" (`^`) operation. ```cpp bitset& operator^=(const bitset& right); @@ -994,11 +995,11 @@ The `bitset` that is to be combined bitwise with the target bitset. #### Return Value -The modified target bitset that results from the bitwise **XOR** (`^`) operation with the `bitset` specified as a parameter. +The modified target bitset that results from the bitwise "xor" (`^`) operation with the `bitset` specified as a parameter. #### Remarks -Two bits combined by the bitwise **XOR** operator (`^`) return **`true`** if at least one, but not both, of the bits is **`true`**; otherwise, their combination returns **`false`**. +Two bits combined by the bitwise "xor" operator (`^`) return **`true`** if at least one, but not both, of the bits are **`true`**; otherwise, their combination returns **`false`**. Bitsets must be the same size. @@ -1047,7 +1048,7 @@ The parameter bitset b2 remains: ( 01011 ). ### `operator|=` -Combines two bitsets using the bitwise `OR` (`|`) operation. +Combines two bitsets using the bitwise "or" (`|`) operation. ```cpp bitset& operator|=(const bitset& right); @@ -1060,7 +1061,7 @@ The `bitset` that is to be combined bitwise with the target `bitset`. #### Return Value -The modified target bitset that results from the bitwise `OR` (`|`) operation with the `bitset` specified as a parameter. +The modified target bitset that results from the bitwise "or" (`|`) operation with the `bitset` specified as a parameter. #### Remarks @@ -1179,7 +1180,7 @@ public: The value of the object of type **`bool`** to be assigned to a bit in a `bitset`. *`bitref`*\ -A reference of the form *x [ i ]* to the bit at position *i* in `bitset` *x*. +A reference of the form *`x [ i ]`* to the bit at position *`i`* in `bitset` *`x`*. #### Return Value @@ -1187,15 +1188,15 @@ A reference to the bit in the `bitset` specified by the argument position for th #### Remarks -The class `reference` exists only as a helper class for the `bitset` `operator[]`. The member class describes an object that can access an individual bit within a `bitset`. Let *b* be an object of type **`bool`**, *x* and *y* objects of type **`bitset`**, and *i* and *j* valid positions within such an object. The notation *x [i]* references the bit at position *i* in bitset *x*. The member functions of class `reference` provide, in order, the following operations: +The class `reference` exists only as a helper class for the `bitset` `operator[]`. The member class describes an object that can access an individual bit within a `bitset`. Let *`b`* be an object of type **`bool`**, *`x`* and *`y`* objects of type **`bitset`**, and *`i`* and *`j`* valid positions within such an object. The notation *`x [i]`* references the bit at position *`i`* in bitset *`x`*. The member functions of class `reference` provide, in order, the following operations: |Operation|Definition| |---------------|----------------| -|*x*[*i*] = *b*|Stores **`bool`** value *b* at bit position *i* in bitset *x*.| -|*x*[*i*] = *y*[*j*]|Stores the value of the bit *y*[ *j*] at bit position *i* in bitset *x*.| -|*b* = ~ *x*[*i*]|Stores the flipped value of the bit *x*[ *i*] in **`bool`** *b*.| -|*b* = *x*[*i*]|Stores the value of the bit *x*[ *i*] in **`bool`** *b*.| -|*x*[*i*]. `flip`( )|Stores the flipped value of the bit *x*[ *i*] back at bit position *i* in *x*.| +|*`x`*[*`i`*] = *`b`*|Stores **`bool`** value *`b`* at bit position *`i`* in bitset *`x`*.| +|*`x`*[*`i`*] = *`y`*[*`j`*]|Stores the value of the bit *`y`*[ *`j`*] at bit position *`i`* in bitset *`x`*.| +|*`b`* = ~ *`x`*[*`i`*]|Stores the flipped value of the bit *`x`*[ *`i`*] in **`bool`** *`b`*.| +|*`b`* = *`x`*[*`i`*]|Stores the value of the bit *`x`*[ *`i`*] in **`bool`** *`b`*.| +|*`x`*[*`i`*]. `flip`( )|Stores the flipped value of the bit *`x`*[ *`i`*] back at bit position *`i`* in *`x`*.| #### Example @@ -1319,7 +1320,7 @@ int main( ) bitset<5> b1r3; b1r3 = b1.reset( 2 ); - cout << "The collecion of bits obtained from resetting the\n" + cout << "The collection of bits obtained from resetting the\n" << "third bit of bitset b1 is: ( "<< b1r3 << " )" << endl; @@ -1466,7 +1467,7 @@ The position of the bit in the `bitset` to be tested for its value. #### Remarks -The member function throws an [out_of_range](../standard-library/out-of-range-class.md) +The member function throws an [`out_of_range`](../standard-library/out-of-range-class.md) ### `to_string` @@ -1530,7 +1531,7 @@ Returns the sum of the bit values that are in the bit sequence as an **`unsigned #### Exceptions -Throws an [`overflow_error`](overflow-error-class.md) object if any bit in the bit sequence has a bit value that cannot be represented as a value of type **`unsigned long long`**. +Throws an [`overflow_error`](overflow-error-class.md) object if any bit in the bit sequence has a bit value that can't be represented as a value of type **`unsigned long long`**. #### Remarks @@ -1552,7 +1553,7 @@ An integer that would generate the bits in a `bitset` if used in the initializat Applying the member function would return the integer that has the same sequence of 1 and 0 digits as is found in sequence of bits contained in the `bitset`. -The member function throws an [`overflow_error`](overflow-error-class.md) object if any bit in the bit sequence has a bit value that cannot be represented as a value of type **`unsigned long`**. +The member function throws an [`overflow_error`](overflow-error-class.md) object if any bit in the bit sequence has a bit value that can't be represented as a value of type **`unsigned long`**. #### Example diff --git a/docs/standard-library/bitset-operators.md b/docs/standard-library/bitset-operators.md index bc525ab716..b042e2cccc 100644 --- a/docs/standard-library/bitset-operators.md +++ b/docs/standard-library/bitset-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" +description: "Learn more about: operators" ms.date: "11/04/2016" f1_keywords: ["bitset/std::operator&", "bitset/std::operator>>", "bitset/std::operator<<", "bitset/std::operator^", "bitset/std::operator|"] -ms.assetid: 84fe6a13-6f6e-4cdc-bf8f-6f65ab1134d4 helpviewer_keywords: ["std::operator& (bitset)", "std::operator>> (bitset)", "std::operator<< (bitset)"] --- # `` operators @@ -107,7 +106,7 @@ int main( ) << b1 << " )" << endl; // Compare converting bitset to a string before - // inserting it into the output steam + // inserting it into the output stream string s1; s1 = b1.template to_string, allocator >( ); @@ -162,7 +161,6 @@ The template function extracts elements from *i_str* and inserts them into the b using namespace std; int main() { - bitset<5> b1; cout << "Enter string of (0 or 1) bits for input into bitset<5>.\n" << "Try bit string of length less than or equal to 5,\n" @@ -253,9 +251,9 @@ bitset 2: 0011 bitset 3: 0110 ``` -## operator| +## `operator|` -Performs a bitwise `OR` between two bitsets. +Performs a bitwise OR between two `bitset` objects. ```cpp template diff --git a/docs/standard-library/bitset.md b/docs/standard-library/bitset.md index c984cbdb34..4a0138a9a5 100644 --- a/docs/standard-library/bitset.md +++ b/docs/standard-library/bitset.md @@ -26,7 +26,7 @@ Defines the class template bitset and two supporting template functions for repr |[operator<\<](../standard-library/bitset-operators.md#op_lt_lt)|Inserts a text representation of the bit sequence into the standard output stream.| |[operator>>](../standard-library/bitset-operators.md#op_gt_gt)|Inserts a text representation of the bit sequence into the standard input stream.| |[operator^](../standard-library/bitset-operators.md#op_xor)|Performs a bitwise EXCLUSIVE-OR between two bitsets.| -|[operator|](../standard-library/bitset-operators.md#op_or)|Performs a bitwise OR between two bitsets.| +|[`operator|`](../standard-library/bitset-operators.md#op_or)|Performs a bitwise OR between two bitsets.| ### Classes diff --git a/docs/standard-library/boyer-moore-horspool-searcher-class.md b/docs/standard-library/boyer-moore-horspool-searcher-class.md index 626ebc3ef1..85c81a6e6c 100644 --- a/docs/standard-library/boyer-moore-horspool-searcher-class.md +++ b/docs/standard-library/boyer-moore-horspool-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::boyer_moore_horspool_searcher [C++]"] --- # boyer_moore_horspool_searcher class -The `boyer_moore_horspool_searcher` class is a function object type that uses the Boyer-Moore-Horspool algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). +The `boyer_moore_horspool_searcher` class is a function object type that uses the Boyer-Moore-Horspool algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). ## Syntax diff --git a/docs/standard-library/boyer-moore-searcher-class.md b/docs/standard-library/boyer-moore-searcher-class.md index 60f0320639..aa23e6cb1b 100644 --- a/docs/standard-library/boyer-moore-searcher-class.md +++ b/docs/standard-library/boyer-moore-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::boyer_moore_searcher [C++]"] --- # boyer_moore_searcher class -The `boyer_moore_searcher` class is a function object type that uses the Boyer-Moore algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). +The `boyer_moore_searcher` class is a function object type that uses the Boyer-Moore algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). ## Syntax diff --git a/docs/standard-library/char-traits-char-struct.md b/docs/standard-library/char-traits-char-struct.md index 22aa1ee35d..fbdc3d0c80 100644 --- a/docs/standard-library/char-traits-char-struct.md +++ b/docs/standard-library/char-traits-char-struct.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: char_traits Struct" title: "char_traits Struct" -ms.date: "11/04/2016" +description: "Learn more about: char_traits Struct" +ms.date: 11/04/2016 f1_keywords: ["iosfwd/std::char_traits", "char_traits"] helpviewer_keywords: ["char_traits class"] -ms.assetid: abd9373a-77db-4031-bf4b-f8ac15087581 --- # `char_traits` Struct @@ -23,4 +22,4 @@ Specialization allows the struct to take advantage of library functions that man ## Example -See the typedefs and member functions of the class template [char_traits Class](../standard-library/char-traits-struct.md) +See the typedefs and member functions of the class template [`char_traits`](../standard-library/char-traits-struct.md) diff --git a/docs/standard-library/char-traits-struct.md b/docs/standard-library/char-traits-struct.md index dcbd8702db..065c8cf7d2 100644 --- a/docs/standard-library/char-traits-struct.md +++ b/docs/standard-library/char-traits-struct.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: char_traits Struct" title: "char_traits Struct" -ms.date: "05/07/2019" +description: "Learn more about: char_traits Struct" +ms.date: 05/07/2019 f1_keywords: ["iosfwd/std::char_traits", "iosfwd/std::char_traits::char_type", "iosfwd/std::char_traits::int_type", "iosfwd/std::char_traits::off_type", "iosfwd/std::char_traits::pos_type", "iosfwd/std::char_traits::state_type", "iosfwd/std::char_traits::assign", "iosfwd/std::char_traits::compare", "iosfwd/std::char_traits::copy", "iosfwd/std::char_traits::_Copy_s", "iosfwd/std::char_traits::eof", "iosfwd/std::char_traits::eq", "iosfwd/std::char_traits::eq_int_type", "iosfwd/std::char_traits::find", "iosfwd/std::char_traits::length", "iosfwd/std::char_traits::lt", "iosfwd/std::char_traits::move", "iosfwd/std::char_traits::_Move_s", "iosfwd/std::char_traits::not_eof", "iosfwd/std::char_traits::to_char_type", "iosfwd/std::char_traits::to_int_type"] helpviewer_keywords: ["char_traits struct", "char_traits class"] -ms.assetid: 568e59f0-4521-4207-9223-9dcf6a16d620 --- # char_traits Struct @@ -1010,11 +1009,11 @@ A value of *_Ch* that cannot be represented as such yields an unspecified result The conversion operations [to_int_type](#to_int_type) and `to_char_type` are inverse to each other, so that: -`to_int_type` ( `to_char_type` ( *x* ) ) == *x* +`to_int_type`(`to_char_type`(*x*)) == *x* for any `int_type` *x* and -`to_char_type` ( `to_int_type` ( *x* ) ) == *x* +`to_char_type`(`to_int_type`(*x*)) == *x* for any `char_type` *x*. @@ -1114,11 +1113,11 @@ The `int_type` character corresponding to the `char_type` character. The conversion operations `to_int_type` and [to_char_type](#to_char_type) are inverse to each other, so that: -`to_int_type` ( `to_char_type` ( *x* ) ) == *x* +`to_int_type`(`to_char_type`(*x*)) == *x* for any `int_type` *x*, and -`to_char_type` ( `to_int_type` ( *x* ) ) == *x* +`to_char_type`(`to_int_type`(*x*)) == *x* for any `char_type` *x*. diff --git a/docs/standard-library/charconv-functions.md b/docs/standard-library/charconv-functions.md index 296364799d..8f601eef05 100644 --- a/docs/standard-library/charconv-functions.md +++ b/docs/standard-library/charconv-functions.md @@ -236,6 +236,6 @@ int main() ## See also -[\](charconv.md) -[The shortest decimal string that round-trips](https://www.exploringbinary.com/the-shortest-decimal-string-that-round-trips-examples/) +[\](charconv.md)\ +[The shortest decimal string that round-trips](https://www.exploringbinary.com/the-shortest-decimal-string-that-round-trips-examples/)\ [printf() format specifiers](..\c-runtime-library\format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/standard-library/choose-enum.md b/docs/standard-library/choose-enum.md index c0306545e3..3a4c9f7b2a 100644 --- a/docs/standard-library/choose-enum.md +++ b/docs/standard-library/choose-enum.md @@ -2,8 +2,9 @@ title: "choose enum" description: "enum used to specify how to handle ambiguous or nonexistent local times when resolving a time in a time zone" ms.date: 10/08/2021 -f1_keywords: ["chrono/std::choose"] -helpviewer_keywords: ["std::choose"] +f1_keywords: ["chrono/std::chrono::choose"] +helpviewer_keywords: ["std::chrono [C++], choose"] +dev_langs: ["C++"] --- # `choose` enum @@ -13,7 +14,7 @@ Used with [`time_zone`](time-zone-class.md) and [`zoned_time`](zoned-time-class. ## Syntax ```cpp -enum class choose { // C++ 20 +enum class choose { // C++20 earliest, latest }; diff --git a/docs/standard-library/chrono-functions.md b/docs/standard-library/chrono-functions.md index 52f3dcb0d5..e1812b1d34 100644 --- a/docs/standard-library/chrono-functions.md +++ b/docs/standard-library/chrono-functions.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: 10/15/2021 f1_keywords: ["chrono/std::duration_cast", "chrono/std::time_point_cast", "chrono/std::chrono::clock_cast", "chrono/std::chrono::duration_cast", "chrono/std::chrono::time_point_cast", "chrono/std::chrono::from_stream", "chrono/std::chrono::abs", "chrono/std::chrono::floor", "chrono/std::chrono::ceil", "chrono/std::chrono::round", "chrono/std::chrono::is_am", "chrono/std::chrono::is_pm", "chrono/std::chrono::make12", "chrono/std::chrono::make24", "chrono/std::chrono::get_leap_second_info", "chrono/std::chrono::get_tzdb", "chrono/std::chrono::get_tzdb_list", "chrono/std::chrono::locate_zone", "chrono/std::chrono::current_zone", "chrono/std::chrono::reload_tzdb", "chrono/std::chrono::remote_version"] helpviewer_keywords: ["std::duration_cast function", "std::time_point_cast function", "std::chrono::clock_cast", "std::chrono::duration_cast function", "std::chrono::time_point_cast function", "std::chrono::from_stream function", "std::chrono::floor function", "std::chrono::ceil function", "std::chrono::round function", "std::chrono::is_am function", "std::chrono::is_pm function", "std::chrono::make12 function", "std::chrono::make24 function", "std::chrono::get_leap_second_info function", "std::chrono::get_tzdb function", "std::chrono::get_tzdb_list function", "std::chrono::locate_zone function", "std::chrono::current_zone function", "std::chrono::reload_tzdb function", "std::chrono::remote_version function"] @@ -128,7 +128,7 @@ Converts a [`time_point`](time-point-class.md) for one clock to an equivalent `t ```cpp template -auto clock_cast(const time_point& t); // C++ 20 +auto clock_cast(const time_point& t); // C++20 ``` ### Parameters @@ -563,7 +563,7 @@ int main() ### Remarks -**7)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev `if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. +**7)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev` if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. **12)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev` if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. @@ -577,21 +577,21 @@ The format may be one of these strings: |--|--| | `%D` | Equivalent to `%m/%d/%y` | | `%F`
`%`*N*`F` | Equivalent to `%Y-%m-%d`. If modified with a width `N`, the width is applied to only `%Y`. | -| `%x`
`%Ex` | The locale’s date representation.
`%Ex` parses the locale’s alternate date representation.[1](#notice) | +| `%x`
`%Ex` | The locale's date representation.
`%Ex` parses the locale's alternate date representation.[1](#notice) | #### Day | Specifier | Description | |--|--| -| `%d`
`%Od`
`%`*N*`d`
`%e`
`%Oe`
`%`*N*`e` | The day of the month as a decimal number.
`%`*N*`d` specifies the maximum number of characters to read, for example `%1d`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Od` (letter `O`, not zero) interprets the locale’s alternative representation of the day of the month.[1](#notice)
`%e` is equivalent to `%d` and can be modified like `%d`.[1](#notice) | +| `%d`
`%Od`
`%`*N*`d`
`%e`
`%Oe`
`%`*N*`e` | The day of the month as a decimal number.
`%`*N*`d` specifies the maximum number of characters to read, for example `%1d`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Od` (letter `O`, not zero) interprets the locale's alternative representation of the day of the month.[1](#notice)
`%e` is equivalent to `%d` and can be modified like `%d`.[1](#notice) | #### Day of the week | Specifier | Description | |--|--| -| `%a`
`%A` | The locale’s full or abbreviated case-insensitive weekday name.
`%A` is equivalent to `%a` | +| `%a`
`%A` | The locale's full or abbreviated case-insensitive weekday name.
`%A` is equivalent to `%a` | | `%u`
`%`*N*`u` | The ISO weekday as a decimal number (1-7), where Monday is 1.
`%`*N*`u` specifies the maximum number of characters to read, for example `%2u`. If *N* isn't specified, the default is 1. Leading zeros are permitted but not required. | -| `%w`
`%`*N*`w`
`%Ow` | The weekday as a decimal number (0-6), where Sunday is 0.
`%`*N*`w` specifies the maximum number of characters to read, for example `%2w`. If *N* isn't specified, the default is 1.
Leading zeroes are permitted but not required.
`%Ow` (letter `O`, not zero) interprets the locale’s alternative representation.[1](#notice) | +| `%w`
`%`*N*`w`
`%Ow` | The weekday as a decimal number (0-6), where Sunday is 0.
`%`*N*`w` specifies the maximum number of characters to read, for example `%2w`. If *N* isn't specified, the default is 1.
Leading zeroes are permitted but not required.
`%Ow` (letter `O`, not zero) interprets the locale's alternative representation.[1](#notice) | #### Week/day of the year @@ -605,30 +605,30 @@ The format may be one of these strings: | Specifier | Description | |--|--| -| `%H`
`%`*N*`H`
`%OH` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it's prefixed with a `0` (zero).
`%`*N*`H` specifies the maximum number of characters to read, for example, `%1H`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OH` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%I`
`%`*N*`I`
`%OI` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`I` specifies the maximum number of characters to read, for example, `%1I`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OI` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%M`
`%`*N*`M`
`%OM` | The minutes as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`M` specifies the maximum number of characters to read, for example `%3M`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OM` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -|`%S`
`%`*N*`S`
`%OS` | Seconds as a decimal number. If the number of seconds is less than 10, the result is prefixed with `0` (zero). If the precision of the input can't be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format. It has a microseconds precision if the function can't convert the floating-point decimal seconds within 18 fractional digits. Otherwise, its precision matches the precision of the input. The character for the decimal point is localized according to the locale.
`%`*N*`S` specifies the maximum number of characters to read, for example `%3S`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OS` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%p` | The locale’s equivalent of the AM/PM designations associated with a 12-hour clock. | -| `%r` | The locale’s 12-hour clock time. | +| `%H`
`%`*N*`H`
`%OH` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it's prefixed with a `0` (zero).
`%`*N*`H` specifies the maximum number of characters to read, for example, `%1H`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OH` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%I`
`%`*N*`I`
`%OI` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`I` specifies the maximum number of characters to read, for example, `%1I`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OI` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%M`
`%`*N*`M`
`%OM` | The minutes as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`M` specifies the maximum number of characters to read, for example `%3M`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OM` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +|`%S`
`%`*N*`S`
`%OS` | Seconds as a decimal number. If the number of seconds is less than 10, the result is prefixed with `0` (zero). If the precision of the input can't be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format. It has a microseconds precision if the function can't convert the floating-point decimal seconds within 18 fractional digits. Otherwise, its precision matches the precision of the input. The character for the decimal point is localized according to the locale.
`%`*N*`S` specifies the maximum number of characters to read, for example `%3S`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OS` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%p` | The locale's equivalent of the AM/PM designations associated with a 12-hour clock. | +| `%r` | The locale's 12-hour clock time. | | `%R` | Equivalent to `%H:%M`. | | `%T`| Equivalent to `"%H:%M:%S"`. | -| `%X`, `%EX` | The locale’s time representation.
`%EX` parses the alternate locale’s time representation.[1](#notice) | +| `%X`, `%EX` | The locale's time representation.
`%EX` parses the alternate locale's time representation.[1](#notice) | #### Month | Specifier | Description | |--|--| -|`%b`, `%B`, `%h`| The locale’s full or abbreviated month name. If the value doesn't contain a valid month, a `format_error` exception is thrown.
`%h` is equivalent to `%b`. | -| `%m`, `%`*N*`m`, `%Om` | The month as a decimal number. Jan is 1.
`%`*N*`m` specifies the maximum number of characters to read, for example, `%3m`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Om` (letter `O`, not zero) interprets the locale’s alternative representation.[1](#notice) | +|`%b`, `%B`, `%h`| The locale's full or abbreviated month name. If the value doesn't contain a valid month, a `format_error` exception is thrown.
`%h` is equivalent to `%b`. | +| `%m`, `%`*N*`m`, `%Om` | The month as a decimal number. Jan is 1.
`%`*N*`m` specifies the maximum number of characters to read, for example, `%3m`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Om` (letter `O`, not zero) interprets the locale's alternative representation.[1](#notice) | #### Year | Specifier | Description | |--|--| -|`%C`, `%`*N*`C`, `%EC`| The century as a decimal number.
`%`*N*`C` specifies the maximum number of characters to read, for example, `%1N`. If *N* isn't specified, the default is 2. Leading zeroes are permitted but not required.
`%EC` interprets the locale’s alternative representation of the century. | -|`%y`, `%`*N*`y`, `%Ey`, `%Oy` | The last two decimal digits of the year. If the century isn't otherwise specified (for example, by using `%C`), values in the range `[69, 99]` are presumed to refer to the years 1969 to 1999, and values in the range `[00, 68]` are presumed to refer to the years 2000 to 2068.
`%`*N*`y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Ey` and `%Oy` (letter `O`, not zero) interpret the locale’s alternative representation.[1](#notice) | -| `%Y`, `%`*N*`Y`, `%EY`, | The year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits.
`%`*N*`Y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 4.
`%EY` parses the locale’s alternative full year representation.[1](#notice) | +|`%C`, `%`*N*`C`, `%EC`| The century as a decimal number.
`%`*N*`C` specifies the maximum number of characters to read, for example, `%1N`. If *N* isn't specified, the default is 2. Leading zeroes are permitted but not required.
`%EC` interprets the locale's alternative representation of the century. | +|`%y`, `%`*N*`y`, `%Ey`, `%Oy` | The last two decimal digits of the year. If the century isn't otherwise specified (for example, by using `%C`), values in the range `[69, 99]` are presumed to refer to the years 1969 to 1999, and values in the range `[00, 68]` are presumed to refer to the years 2000 to 2068.
`%`*N*`y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Ey` and `%Oy` (letter `O`, not zero) interpret the locale's alternative representation.[1](#notice) | +| `%Y`, `%`*N*`Y`, `%EY`, | The year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits.
`%`*N*`Y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 4.
`%EY` parses the locale's alternative full year representation.[1](#notice) | #### ISO 8601 week-based year @@ -638,18 +638,18 @@ In ISO 8601, weeks begin with Monday. The first week of the year must include Ja |:---------:|:------------------------------------------| | `%g`
`%`*N*`g`| The last two decimal digits of the ISO week-based year. If the result is a single digit, is prefixed by `0` (zero). `%`*N*`g` specifies the maximum number of characters to read, for example, `%1g`. If *N* isn't specified, the default is 2 | | `%G`
`%`*N*`G`| The ISO week-based year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits. `%`*N*`G` specifies the maximum number of characters to read, for example, `%1G`. If *N* isn't specified, the default is 4| -| `%V`
`%OV`
`%`*N*`V`| The ISO week-based week number as a decimal number. If the result is a single digit, it's prefixed with `0` (zero). `%`*N*`V` specifies the maximum number of characters to read, for example, `%1V`. If *N* isn't specified, the default is 2
`%OV` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | +| `%V`
`%OV`
`%`*N*`V`| The ISO week-based week number as a decimal number. If the result is a single digit, it's prefixed with `0` (zero). `%`*N*`V` specifies the maximum number of characters to read, for example, `%1V`. If *N* isn't specified, the default is 2
`%OV` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | #### General | Specifier | Replacement | |:-:|:-| | `%%` | Matches the % character | -| `%c`
`%Ec`| The locale’s date and time representation.
`%Ec` interprets the locale’s alternate date and time representation.[1](#notice) | +| `%c`
`%Ec`| The locale's date and time representation.
`%Ec` interprets the locale's alternate date and time representation.[1](#notice) | | `%n` | Matches a new-line character | | `%t` | Matches zero or one whitespace character | | `%z`
`%Ez`
`%Oz` | The offset from UTC in the format `[+|-]hh[mm]`. For example, `-0430` refers to 4 hours 30 minutes behind UTC, and `04` refers to 4 hours ahead of UTC.
`%Ez` and `%Oz` (letter `O`, not zero) parse a `:` between the hours and minutes and render leading zeroes on the hour field optional[1](#notice): `[+|-]h[h][:mm]`. For example, `-04:30` refers to 4 hours 30 minutes behind UTC, and 4 refers to 4 hours ahead of UTC. | -| `%Z` | The time zone abbreviation or name. A single word is parsed. This word can only contain alphanumeric characters from the basic source character set, or one of `_`, `/`, `-’`, or `+`. +| `%Z` | The time zone abbreviation or name. A single word is parsed. This word can only contain alphanumeric characters from the basic source character set, or one of `_`, `/`, `-`, or `+`. #### Flags by type @@ -674,7 +674,7 @@ In ISO 8601, weeks begin with Monday. The first week of the year must include Ja | `utc_time` | Z, z, c, x, X, D, F, g, G, j, U, V, W, Y, y, C, b, h, B, m, d, e, a, A, u, w, H, I, M, S, r, R, T, p | | [`weekday`](weekday-class.md) | a, A, u, w | | [`weekday_indexed`](weekdayindexed-class.md) | a, A, u, w | -| [`weekday_last`]() | a, A, u, w | +| [`weekday_last`](weekdaylast-class.md) | a, A, u, w | | [`year`](year-class.md) | Y, y, C | | `year_month` | Y, y, B, g, G, h, C, b, m | | `year_month_day` | D, F, g, G, j, U, V, W, Y, y, C, b, h, B, m, d, e, a, A, u, w | @@ -704,7 +704,7 @@ The source `utc_time` to get the `leap_second_info` for. ### Return value -Returns a `leap_second_info` whose member `is_leap_second` is **`true`** if *`ut`* is during a positive leap second insertion; otherwise, **`false`**. The `elapsed` member holds the sum of leap seconds between the epoch date `1970-01-01`and *`ut`*. If `is_leap_second` is **`true`**, the leap second referred to by *`ut`* is included in the `elapsed` sum. +Returns a `leap_second_info` whose member `is_leap_second` is **`true`** if *`ut`* is during a positive leap second insertion; otherwise, **`false`**. The `elapsed` member holds the sum of leap seconds between the epoch date `1970-01-01` and *`ut`*. If `is_leap_second` is **`true`**, the leap second referred to by *`ut`* is included in the `elapsed` sum. ## `get_tzdb` @@ -987,4 +987,4 @@ Unless `ToDuration` is a specialization of [`duration`](../standard-library/dura [`chrono` operators](./chrono-operators.md)\ [`duration` class](./duration-class.md)\ [`time_point` class](./time-point-class.md)\ -[`time_zone` class](./time-zone-class.md) \ No newline at end of file +[`time_zone` class](./time-zone-class.md) diff --git a/docs/standard-library/chrono-literals.md b/docs/standard-library/chrono-literals.md index 532aa1c115..3bea9a5b93 100644 --- a/docs/standard-library/chrono-literals.md +++ b/docs/standard-library/chrono-literals.md @@ -53,7 +53,7 @@ inline namespace literals { constexpr chrono::duration operator"" ns(long double Val); // return integral year - constexpr chrono::year operator""y(unsigned long long y) noexcept; // C++ 20 + constexpr chrono::year operator""y(unsigned long long y) noexcept; // C++20 } // inline namespace chrono_literals } // inline namespace literals ``` diff --git a/docs/standard-library/chrono-operators.md b/docs/standard-library/chrono-operators.md index 666a207afe..64931b7607 100644 --- a/docs/standard-library/chrono-operators.md +++ b/docs/standard-library/chrono-operators.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: operators" title: " operators" +description: "Learn more about: operators" ms.date: 09/17/2021 f1_keywords: ["chrono/std::operator modulo", "chrono/std::operator+", "chrono/std::chrono::day::operator+", "chrono/std::chrono::duration::operator+", "chrono/std::chrono::month::operator+", "chrono/std::chrono::time_point::operator+", "chrono/std::chrono::weekday::operator+", "chrono/std::chrono::year_month::operator+", "chrono/std::chrono::year::operator+", "chrono/std::chrono::year_month_day::operator+", "chrono/std::chrono::year_month_day_last::operator+", "chrono/std::chrono::year_month_weekday::operator+", "chrono/std::chrono::year_month_weekday_last::operator+", "chrono/std::operator!=", "chrono/std::operator*", "chrono/std::operator/", "chrono/std::operator-", "chrono/std::operator<", "chrono/std::operator<=", "chrono/std::operator<", "chrono/std::operator==", "chrono/std::operator>>", "chrono/std::operator<=>", "chrono/std::chrono::day::operator<=>", "chrono/std::chrono::month::operator<=>", "chrono/std::chrono::year::operator<=>", "chrono/std::chrono::year_month::operator<=>", "chrono/std::chrono::time_point::operator<=>", "chrono/std::chrono::time_zone_link::operator<=>", "chrono/std::chrono::time_zone_link::operator==", "chrono/std::chrono::duration::operator<=>", "chrono/std::chrono::month_day_last::operator<=>", "chrono/std::chrono::year_month_day_last::operator<=>", "chrono/std::operator==", "chrono/std::chrono::year::operator<==>", "chrono/std::chrono::day::operator==", "chrono/std::chrono::duration::operator==", "chrono/std::chrono::month::operator==", "chrono/std::chrono::month_day::operator==", "chrono/std::chrono::month_day_last::operator==", "chrono/std::chrono::month_weekday::operator==", "chrono/std::chrono::month_weekday_last::operator==", "chrono/std::chrono::time_point::operator==", "chrono/std::chrono::weekday::operator==", "chrono/std::chrono::year_month::operator==", "chrono/std::chrono::year::operator==", "chrono/std::chrono::year_month_day::operator==", "chrono/std::chrono::year_month_day_last::operator==", "chrono/std::chrono::year_month_weekday_last::operator==", "chrono/std::chrono::year_month_weekday::operator==", "chrono/std::chrono::month_weekday_last::operator==", "chrono/std::chrono::weekday::operator==", "chrono/std::chrono::weekday_last::operator==", "chrono/std::chrono::year_month_weekday_indexed::operator==", "chrono/std::chrono::year_month_weekday_last::operator==", "chrono/std::chrono::year::operator==", "chrono/std::chrono::year_month::operator==", "chrono/std::chrono::year_month_day::operator==", "chrono/std::chrono::year_month_day_last::operator==", "chrono/std::chrono::zoned_time::operator==", "chrono/std::operator-", "chrono/std::chrono::day::operator-", "chrono/std::chrono::duration::operator-", "chrono/std::chrono::month::operator-", "chrono/std::chrono::time_point::operator-", "chrono/std::chrono::weekday::operator-", "chrono/std::chrono::year_month::operator-", "chrono/std::chrono::year::operator-", "chrono/std::chrono::year_month_day::operator-", "chrono/std::chrono::year_month_day_last::operator-", "chrono/std::chrono::year_month_weekday::operator-", "chrono/std::chrono::year_month_weekday_last::operator-", "chrono/std::chrono::day::operator<<", "chrono/std::chrono::hh_mm_ss::operator<<", "chrono/std::chrono::month_day::operator<<", "chrono/std::chrono::month_day_last::operator<<", "chrono/std::chrono::month_weekday::operator<<", "chrono/std::chrono::month_weekday_last::operator<<", "chrono/std::chrono::weekday::operator<<", "chrono/std::chrono::weekday_indexed::operator<<", "chrono/std::chrono::weekday_last::operator<<", "chrono/std::chrono::year::operator<<", "chrono/std::chrono::year_month_day::operator<<", "chrono/std::chrono::year_month_day_last::operator<<", "chrono/std::chrono::year_month_weekday::operator<<", "chrono/std::chrono::utc_time::operator<<", "chrono/std::chrono::tai_time::operator<<", "chrono/std::chrono::gps_time::operator<<", "chrono/std::chrono::local_time::operator<<", "chrono/std::chrono::file_time::operator<<", "chrono/std::chrono::sys_info::operator<<", "chrono/std::chrono::local_info::operator<<", "chrono/std::chrono::zoned_time::operator<<"] --- @@ -45,60 +45,60 @@ time_point, Durati const time_point& Time); 4) -constexpr day operator+(const day& d, const days& ds) noexcept; // C++ 20 -constexpr day operator+(const days& ds, const day& d) noexcept; // C++ 20 +constexpr day operator+(const day& d, const days& ds) noexcept; // C++20 +constexpr day operator+(const days& ds, const day& d) noexcept; // C++20 5) -constexpr month operator+(const month& m, const months& ms) noexcept; // C++ 20 -constexpr month operator+(const months& ms, const month& m) noexcept; // C++ 20 +constexpr month operator+(const month& m, const months& ms) noexcept; // C++20 +constexpr month operator+(const months& ms, const month& m) noexcept; // C++20 6) -constexpr weekday operator+(const weekday& wd, const days& wds) noexcept // C++ 20 -constexpr weekday operator+(const days& ds, const weekday& wd) noexcept; // C++ 20 +constexpr weekday operator+(const weekday& wd, const days& wds) noexcept // C++20 +constexpr weekday operator+(const days& ds, const weekday& wd) noexcept; // C++20 7) -constexpr year operator+(const year& y, const years& ys) noexcept; // C++ 20 -constexpr year operator+(const years& ys, const year& y) noexcept; // C++ 20 +constexpr year operator+(const year& y, const years& ys) noexcept; // C++20 +constexpr year operator+(const years& ys, const year& y) noexcept; // C++20 8) -constexpr year_month operator+(const year_month& ym, const months& dm) noexcept; // C++ 20 -constexpr year_month operator+(const months& dm, const year_month& ym) noexcept; // C++ 20 -constexpr year_month operator+(const year_month& ym, const years& dy) noexcept; // C++ 20 -constexpr year_month operator+(const years& dy, const year_month& ym) noexcept; // C++ 20 +constexpr year_month operator+(const year_month& ym, const months& dm) noexcept; // C++20 +constexpr year_month operator+(const months& dm, const year_month& ym) noexcept; // C++20 +constexpr year_month operator+(const year_month& ym, const years& dy) noexcept; // C++20 +constexpr year_month operator+(const years& dy, const year_month& ym) noexcept; // C++20 9) -constexpr year_month_day operator+(const year_month_day& ymd, const months& dm) noexcept; // C++ 20 -constexpr year_month_day operator+(const months& dm, const year_month_day& ymd) noexcept; // C++ 20 -constexpr year_month_day operator+(const year_month_day& ymd, const years& dy) noexcept; // C++ 20 -constexpr year_month_day operator+(const years& dy, const year_month_day& ymd) noexcept; // C++ 20 +constexpr year_month_day operator+(const year_month_day& ymd, const months& dm) noexcept; // C++20 +constexpr year_month_day operator+(const months& dm, const year_month_day& ymd) noexcept; // C++20 +constexpr year_month_day operator+(const year_month_day& ymd, const years& dy) noexcept; // C++20 +constexpr year_month_day operator+(const years& dy, const year_month_day& ymd) noexcept; // C++20 10) -constexpr year_month_day_last operator+(const year_month_day_last& ymdl, const months& dm) noexcept; // C++ 20 +constexpr year_month_day_last operator+(const year_month_day_last& ymdl, const months& dm) noexcept; // C++20 11) -constexpr year_month_day_last operator+(const months& dm, const year_month_day_last& ymdl) noexcept; // C++ 20 +constexpr year_month_day_last operator+(const months& dm, const year_month_day_last& ymdl) noexcept; // C++20 12) -constexpr year_month_day_last operator+(const year_month_day_last& ymdl, const years& dy) noexcept; // C++ 20 -constexpr year_month_day_last operator+(const years& dy, const year_month_day_last& ymdl) noexcept; // C++ 20 +constexpr year_month_day_last operator+(const year_month_day_last& ymdl, const years& dy) noexcept; // C++20 +constexpr year_month_day_last operator+(const years& dy, const year_month_day_last& ymdl) noexcept; // C++20 13) -constexpr year_month_weekday operator+(const year_month_weekday& ymwd, const months& dm) noexcept; // C++ 20 -constexpr year_month_weekday operator+(const months& dm, const year_month_weekday& ymwd) noexcept; // C++ 20 +constexpr year_month_weekday operator+(const year_month_weekday& ymwd, const months& dm) noexcept; // C++20 +constexpr year_month_weekday operator+(const months& dm, const year_month_weekday& ymwd) noexcept; // C++20 14) -constexpr year_month_weekday operator+(const year_month_weekday& ymwd, const years& dy) noexcept; // C++ 20 +constexpr year_month_weekday operator+(const year_month_weekday& ymwd, const years& dy) noexcept; // C++20 15) -constexpr year_month_weekday operator+(const years& dy, const year_month_weekday& ymwd) noexcept; // C++ 20 +constexpr year_month_weekday operator+(const years& dy, const year_month_weekday& ymwd) noexcept; // C++20 16) -constexpr year_month_weekday_last operator+(const year_month_weekday_last& ymwdl, const months& dm) noexcept; // C++ 20 -constexpr year_month_weekday_last operator+(const months& dm, const year_month_weekday_last& ymwdl) noexcept; // C++ 20 +constexpr year_month_weekday_last operator+(const year_month_weekday_last& ymwdl, const months& dm) noexcept; // C++20 +constexpr year_month_weekday_last operator+(const months& dm, const year_month_weekday_last& ymwdl) noexcept; // C++20 17) -constexpr year_month_weekday_last operator+(const year_month_weekday_last& ymwdl, const years& dy) noexcept; // C++ 20 -constexpr year_month_weekday_last operator+(const years& dy, const year_month_weekday_last& ymwdl) noexcept; // C++ 20 +constexpr year_month_weekday_last operator+(const year_month_weekday_last& ymwdl, const years& dy) noexcept; // C++20 +constexpr year_month_weekday_last operator+(const years& dy, const year_month_weekday_last& ymwdl) noexcept; // C++20 ``` ### Return value @@ -193,7 +193,7 @@ Apply unary plus to the following types: ```cpp // duration -constexpr common_type_t operator+() const // C++ 20 +constexpr common_type_t operator+() const // C++20 ``` ### Return value @@ -236,53 +236,53 @@ constexpr typename common_type::type const time_point& Left, const time_point& Right); 4) -constexpr day operator-(const day& d, days& ds) noexcept; // C++ 20 -constexpr day operator-(const day& d, const day& d) noexcept; // C++ 20 +constexpr day operator-(const day& d, days& ds) noexcept; // C++20 +constexpr day operator-(const day& d, const day& d) noexcept; // C++20 5) -constexpr month operator-(const month& m, const months& ms) noexcept; // C++ 20 -constexpr month operator-(const month& m, const month& ms) noexcept; // C++ 20 +constexpr month operator-(const month& m, const months& ms) noexcept; // C++20 +constexpr month operator-(const month& m, const month& ms) noexcept; // C++20 6) -constexpr months operator-(const year_month& Left, const year_month& Right) noexcept; // C++ 20 +constexpr months operator-(const year_month& Left, const year_month& Right) noexcept; // C++20 7) -constexpr weekday operator-(const weekday& Left, const days& Right) noexcept; // C++ 20 +constexpr weekday operator-(const weekday& Left, const days& Right) noexcept; // C++20 8) -constexpr days operator-(const weekday& Left, const weekday& Right) noexcept; // C++ 20 +constexpr days operator-(const weekday& Left, const weekday& Right) noexcept; // C++20 9) -constexpr year operator-(const year& y, const years& ys) noexcept; // C++ 20 +constexpr year operator-(const year& y, const years& ys) noexcept; // C++20 10) -constexpr years operator-(const year& y, const year& y2) noexcept; // C++ 20 +constexpr years operator-(const year& y, const year& y2) noexcept; // C++20 11) -constexpr year_month operator-(const year_month& ym, const months& dm) noexcept; // C++ 20 -constexpr year_month operator-(const year_month& ym, const years& dy) noexcept; // C++ 20 +constexpr year_month operator-(const year_month& ym, const months& dm) noexcept; // C++20 +constexpr year_month operator-(const year_month& ym, const years& dy) noexcept; // C++20 12) -constexpr year_month_day operator-(const year_month_day& ymd, const months& dm) noexcept; // C++ 20 -constexpr year_month_day operator-(const year_month_day& ymd, const years& dy) noexcept; // C++ 20 +constexpr year_month_day operator-(const year_month_day& ymd, const months& dm) noexcept; // C++20 +constexpr year_month_day operator-(const year_month_day& ymd, const years& dy) noexcept; // C++20 13) -constexpr year_month_day_last operator-(const year_month_day_last& ymdl, const months& dm) noexcept; // C++ 20 +constexpr year_month_day_last operator-(const year_month_day_last& ymdl, const months& dm) noexcept; // C++20 14) -constexpr year_month_day_last operator-(const year_month_day_last& ymdl, const years& dy) noexcept; // C++ 20 +constexpr year_month_day_last operator-(const year_month_day_last& ymdl, const years& dy) noexcept; // C++20 15) -constexpr year_month_weekday operator-(const year_month_weekday& ymwd, const months& dm) noexcept; // C++ 20 +constexpr year_month_weekday operator-(const year_month_weekday& ymwd, const months& dm) noexcept; // C++20 16) -constexpr year_month_weekday operator-(const year_month_weekday& ymwd, const years& dy) noexcept; // C++ 20 +constexpr year_month_weekday operator-(const year_month_weekday& ymwd, const years& dy) noexcept; // C++20 17) -constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl, const months& dm) noexcept; // C++ 20 +constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl, const months& dm) noexcept; // C++20 18) -constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl, const years& dy) noexcept; // C++ 20 +constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl, const years& dy) noexcept; // C++20 ``` ### Return value @@ -431,7 +431,7 @@ int main() Determines whether: 1\) Two [`duration`](duration-class.md) objects don't represent the same number of ticks.\ -2\) Two [`time_point`](time-point-class.md) objects don't represent the same point in time.\ +2\) Two [`time_point`](time-point-class.md) objects don't represent the same point in time. ```cpp 1) @@ -458,7 +458,7 @@ The right `duration` or `time_point` object. ### Return value 1\) Returns **`true`** if the number of ticks for the type common to *`Left`* and *`Right`* aren't equal. Otherwise, returns **`false`**.\ -2\) Returns **`true`** if the two [`time_point`](time-point-class.md) objects don't represent the same point in time. Otherwise, returns **`false`**.\ +2\) Returns **`true`** if the two [`time_point`](time-point-class.md) objects don't represent the same point in time. Otherwise, returns **`false`**. ## `operator*` @@ -603,56 +603,56 @@ constexpr bool operator==( const time_point& Right); // 3) day -constexpr bool operator==(const day& Left, const day& Right) noexcept; // C++ 20 +constexpr bool operator==(const day& Left, const day& Right) noexcept; // C++20 // 4) month -constexpr bool operator==(const month& Left, const month& Right) noexcept; // C++ 20 +constexpr bool operator==(const month& Left, const month& Right) noexcept; // C++20 // 5) month_day -constexpr bool operator==(const month_day& Left, const month_day& Right) noexcept; // C++ 20 +constexpr bool operator==(const month_day& Left, const month_day& Right) noexcept; // C++20 // 6) month_day_last -constexpr bool operator==(const month_day_last& Left, const month_day_last& Right) noexcept; // C++ 20 +constexpr bool operator==(const month_day_last& Left, const month_day_last& Right) noexcept; // C++20 // 7) month_weekday -constexpr bool operator==(const month_weekday& Left, const month_weekday& Right) noexcept; // C++ 20 +constexpr bool operator==(const month_weekday& Left, const month_weekday& Right) noexcept; // C++20 // 8) month_weekday_last -constexpr bool operator==(const month_weekday_last& Left, const month_weekday_last& Right) noexcept; // C++ 20 +constexpr bool operator==(const month_weekday_last& Left, const month_weekday_last& Right) noexcept; // C++20 // 9) weekday -constexpr bool operator==(const weekday& Left, const weekday& Right) noexcept; // C++ 20 +constexpr bool operator==(const weekday& Left, const weekday& Right) noexcept; // C++20 // 10) weekday_last -constexpr bool operator==(const weekday_last& Left, const weekday_last& Right) noexcept; // C++ 20 +constexpr bool operator==(const weekday_last& Left, const weekday_last& Right) noexcept; // C++20 // 11) weekday_indexed -constexpr bool operator==(const weekday_indexed& x, const weekday_indexed& y) noexcept; // C++ 20 +constexpr bool operator==(const weekday_indexed& x, const weekday_indexed& y) noexcept; // C++20 // 12) year -constexpr bool operator==(const year& Left, const year& y ) noexcept; // C++ 20 +constexpr bool operator==(const year& Left, const year& y ) noexcept; // C++20 // 13) year_month -constexpr bool operator==(const year_month& Left, const year_month& Right) noexcept; // C++ 20 +constexpr bool operator==(const year_month& Left, const year_month& Right) noexcept; // C++20 // 14) year_month_day -constexpr bool operator==(const year_month_day& Left, const year_month_day& Right) noexcept; // C++ 20 +constexpr bool operator==(const year_month_day& Left, const year_month_day& Right) noexcept; // C++20 // 15) year_month_day_last -constexpr bool operator==(const year_month_day_last& Left, const year_month_day_last& Right) noexcept; // C++ 20 +constexpr bool operator==(const year_month_day_last& Left, const year_month_day_last& Right) noexcept; // C++20 // 16) year_month_weekday -constexpr bool operator==(const year_month_weekday& Left, const year_month_weekday& Right) noexcept; // C++ 20 +constexpr bool operator==(const year_month_weekday& Left, const year_month_weekday& Right) noexcept; // C++20 // 17) year_month_weekday_last -constexpr bool operator==(const year_month_weekday_last& Left, const year_month_weekday_last& Right) noexcept; // C++ 20 +constexpr bool operator==(const year_month_weekday_last& Left, const year_month_weekday_last& Right) noexcept; // C++20 // 18) time_zone_link -bool operator==(const time_zone_link& Left, const time_zone_link& Right) noexcept; +bool operator==(const time_zone_link& Left, const time_zone_link& Right) noexcept; // C++20 // 19) zoned_time template -bool operator==(const zoned_time& Left, const zoned_time& Right); // C++ 20 +bool operator==(const zoned_time& Left, const zoned_time& Right); // C++20 ``` ### Parameters @@ -668,7 +668,7 @@ The right object to compare. 1\) Returns **`true`** if the number of ticks for the type common to *`Left`* and *`Right`* are equal. Otherwise, returns **`false`**.\ 2\) Returns **`true`** if *`Left`* and *`Right`* represent the same point in time. Otherwise, returns **`false`**.\ 3-17\) Returns **`true`** if *`Left`* and *`Right`* have the same value. Otherwise, returns **`false`**.\ -18\) Returns **`true`** if `Left.name() == Right.name()`. Otherwise, returns `*false*`.\ +18\) Returns **`true`** if `Left.name() == Right.name()`. Otherwise, returns **`false`**.\ 19\) Returns **`true`** if `Left.get_time_zone() == _Right.get_time_zone() && Left.get_sys_time() == Right.get_sys_time();` ## `operator>` @@ -756,18 +756,18 @@ The spaceship operator, with `operator==`, synthesizes operators for `<`, `<=`, ```cpp 1) -constexpr bool operator<=>(const day& Left, const day& Right) noexcept; // C++ 20 +constexpr bool operator<=>(const day& Left, const day& Right) noexcept; // C++20 -constexpr std::strong_ordering operator<=>(const month& Left, const month& Right) noexcept; // C++ 20 +constexpr std::strong_ordering operator<=>(const month& Left, const month& Right) noexcept; // C++20 -constexpr strong_ordering operator<=>(const month_day& Left, const month_day& Right) noexcept; // C++ 20 +constexpr strong_ordering operator<=>(const month_day& Left, const month_day& Right) noexcept; // C++20 -constexpr std::strong_ordering operator<=>(const year& Left, const year& Right ) noexcept; // C++ 20 +constexpr std::strong_ordering operator<=>(const year& Left, const year& Right ) noexcept; // C++20 -constexpr strong_ordering operator<=>(const year_month& Left, const year_month& Right) noexcept; // C++ 20 +constexpr strong_ordering operator<=>(const year_month& Left, const year_month& Right) noexcept; // C++20 template Duration2> - constexpr auto operator<=>(const time_point& Left, const time_point& Right); // C++ 20 + constexpr auto operator<=>(const time_point& Left, const time_point& Right); // C++20 template requires three_­way_­comparable @@ -883,102 +883,102 @@ Output the following types to a stream: // 1) day template std::basic_ostream& -operator<<(std::basic_ostream& os, const day& d); // C++ 20 +operator<<(std::basic_ostream& os, const day& d); // C++20 // 2) hh_mm_ss template basic_ostream& -operator<<(basic_ostream& os, const hh_mm_ss& hms); // C++ 20 +operator<<(basic_ostream& os, const hh_mm_ss& hms); // C++20 // 3) month template basic_ostream& -operator<<(basic_ostream& os, const month& m); // C++ 20 +operator<<(basic_ostream& os, const month& m); // C++20 // 4) month_day template basic_ostream& -operator<<(basic_ostream& os, const month_day& md); // C++ 20 +operator<<(basic_ostream& os, const month_day& md); // C++20 // 5) month_day_last template basic_ostream& -operator<<(basic_ostream& os, const month_day_last& mdl); // C++ 20 +operator<<(basic_ostream& os, const month_day_last& mdl); // C++20 // 6) month_weekday template basic_ostream& -operator<<(basic_ostream& os, const month_weekday& mwd); // C++ 20 +operator<<(basic_ostream& os, const month_weekday& mwd); // C++20 // 7) month_weekday_last template basic_ostream& -operator<<(basic_ostream& os, const month_weekday_last& mwdl); // C++ 20 +operator<<(basic_ostream& os, const month_weekday_last& mwdl); // C++20 // 8) weekday template basic_ostream& -operator<<(basic_ostream& os, const weekday& wd); // C++ 20 +operator<<(basic_ostream& os, const weekday& wd); // C++20 // 9) weekday_indexed template basic_ostream& -operator<<(basic_ostream& os, const weekday_indexed& wdi); // C++ 20 +operator<<(basic_ostream& os, const weekday_indexed& wdi); // C++20 // 10) weekday_last template basic_ostream& -operator<<(basic_ostream& os, const weekday_last& wdl); // C++ 20 +operator<<(basic_ostream& os, const weekday_last& wdl); // C++20 // 11) year template std::basic_ostream& -operator<<(basic_ostream& os, const year& y); // C++ 20 +operator<<(basic_ostream& os, const year& y); // C++20 // 12) year_month template basic_ostream& -operator<<(basic_ostream& os, const year_month& ym); // C++ 20 +operator<<(basic_ostream& os, const year_month& ym); // C++20 // 13) year_month_day template basic_ostream& -operator<<(basic_ostream& os, const year_month_day& ymd); // C++ 20 +operator<<(basic_ostream& os, const year_month_day& ymd); // C++20 // 14) year_month_day_last template basic_ostream& -operator<<(basic_ostream& os, const year_month_day_last& ymdl); // C++ 20 +operator<<(basic_ostream& os, const year_month_day_last& ymdl); // C++20 // 15) year_month_weekday template basic_ostream& -operator<<(basic_ostream& os, const year_month_weekday& ymwd); // C++ 20 +operator<<(basic_ostream& os, const year_month_weekday& ymwd); // C++20 // 16) year_month_weekday_last template basic_ostream& -operator<<(basic_ostream& os, const year_month_weekday_last& ymwdl); // C++ 20 +operator<<(basic_ostream& os, const year_month_weekday_last& ymwdl); // C++20 // 17) tai_time template basic_ostream& -operator<<(basic_ostream& os, const tai_time& t); // C++ 20 +operator<<(basic_ostream& os, const tai_time& t); // C++20 // 18) utc_time template basic_ostream& -operator<<(basic_ostream& os, const utc_time& t); // C++ 20 +operator<<(basic_ostream& os, const utc_time& t); // C++20 // 19) gps_time template basic_ostream& -operator<<(basic_ostream& os, const gps_time& t); // C++ 20 +operator<<(basic_ostream& os, const gps_time& t); // C++20 // 20) local_time template basic_ostream& -operator<<(basic_ostream& os, const local_time& t); // C++ 20 +operator<<(basic_ostream& os, const local_time& t); // C++20 // 21) sys_info template @@ -1257,179 +1257,179 @@ Integers can be used as long as the interpretation isn't ambiguous. // 1 constexpr year_month -operator/(const year& y, const month& m) noexcept; // C++ 20 +operator/(const year& y, const month& m) noexcept; // C++20 // 2 constexpr year_month -operator/(const year& y, int m) noexcept; // C++ 20 +operator/(const year& y, int m) noexcept; // C++20 ///////// returns month_day // 3 constexpr month_day -operator/(const month& m, const day& d) noexcept; // C++ 20 +operator/(const month& m, const day& d) noexcept; // C++20 // 4 constexpr month_day -operator/(const month& m, int d) noexcept; // C++ 20 +operator/(const month& m, int d) noexcept; // C++20 // 5 constexpr month_day -operator/(int m, const day& d) noexcept; // C++ 20 +operator/(int m, const day& d) noexcept; // C++20 // 6 constexpr month_day -operator/(const day& d, const month& m) noexcept; // C++ 20 +operator/(const day& d, const month& m) noexcept; // C++20 // 7 constexpr month_day -operator/(const day& d, int m) noexcept; // C++ 20 +operator/(const day& d, int m) noexcept; // C++20 ///////// returns month_day_last // 8 constexpr month_day_last -operator/(const month& m, last_spec) noexcept; // C++ 20 +operator/(const month& m, last_spec) noexcept; // C++20 // 9 constexpr month_day_last -operator/(int m, last_spec) noexcept; // C++ 20 +operator/(int m, last_spec) noexcept; // C++20 // 10 constexpr month_day_last -operator/(last_spec, const month& m) noexcept; // C++ 20 +operator/(last_spec, const month& m) noexcept; // C++20 // 11 constexpr month_day_last -operator/(last_spec, int m) noexcept; // C++ 20 +operator/(last_spec, int m) noexcept; // C++20 ///////// returns month_weekday // 12 constexpr month_weekday -operator/(const month& m, const weekday_indexed& wdi) noexcept; // C++ 20 +operator/(const month& m, const weekday_indexed& wdi) noexcept; // C++20 // 13 constexpr month_weekday -operator/(int m, const weekday_indexed& wdi) noexcept; // C++ 20 +operator/(int m, const weekday_indexed& wdi) noexcept; // C++20 // 14 constexpr month_weekday -operator/(const weekday_indexed& wdi, const month& m) noexcept; // C++ 20 +operator/(const weekday_indexed& wdi, const month& m) noexcept; // C++20 // 15 constexpr month_weekday -operator/(const weekday_indexed& wdi, int m) noexcept; // C++ 20 +operator/(const weekday_indexed& wdi, int m) noexcept; // C++20 ///////// returns month_weekday_last // 16 constexpr month_weekday_last -operator/(const month& m, const weekday_last& wdl) noexcept; // C++ 20 +operator/(const month& m, const weekday_last& wdl) noexcept; // C++20 // 17 constexpr month_weekday_last -operator/(int m, const weekday_last& wdl) noexcept; // C++ 20 +operator/(int m, const weekday_last& wdl) noexcept; // C++20 // 18 constexpr month_weekday_last -operator/(const weekday_last& wdl, const month& m) noexcept; // C++ 20 +operator/(const weekday_last& wdl, const month& m) noexcept; // C++20 // 19 constexpr month_weekday_last -operator/(const weekday_last& wdl, int m) noexcept; // C++ 20 +operator/(const weekday_last& wdl, int m) noexcept; // C++20 ///////// returns year_month_day // 20 constexpr year_month_day -operator/(const year_month& ym, const day& d) noexcept; // C++ 20 +operator/(const year_month& ym, const day& d) noexcept; // C++20 // 21 constexpr year_month_day -operator/(const year_month& ym, int d) noexcept; // C++ 20 +operator/(const year_month& ym, int d) noexcept; // C++20 // 22 constexpr year_month_day -operator/(const year& y, const month_day& md) noexcept; // C++ 20 +operator/(const year& y, const month_day& md) noexcept; // C++20 // 23 constexpr year_month_day -operator/(int y, const month_day& md) noexcept; // C++ 20 +operator/(int y, const month_day& md) noexcept; // C++20 // 24 constexpr year_month_day -operator/(const month_day& md, const year& y) noexcept; // C++ 20 +operator/(const month_day& md, const year& y) noexcept; // C++20 // 25 constexpr year_month_day -operator/(const month_day& md, int y) noexcept; // C++ 20 +operator/(const month_day& md, int y) noexcept; // C++20 ///////// returns year_month_day_last // 26 constexpr year_month_day_last -operator/(const year_month& ym, last_spec) noexcept; // C++ 20 +operator/(const year_month& ym, last_spec) noexcept; // C++20 // 27 constexpr year_month_day_last -operator/(const year& y, const month_day_last& mdl) noexcept; // C++ 20 +operator/(const year& y, const month_day_last& mdl) noexcept; // C++20 // 28 constexpr year_month_day_last -operator/(int y, const month_day_last& mdl) noexcept; // C++ 20 +operator/(int y, const month_day_last& mdl) noexcept; // C++20 // 29 constexpr year_month_day_last -operator/(const month_day_last& mdl, const year& y) noexcept; // C++ 20 +operator/(const month_day_last& mdl, const year& y) noexcept; // C++20 // 30 constexpr year_month_day_last -operator/(const month_day_last& mdl, int y) noexcept; // C++ 20 +operator/(const month_day_last& mdl, int y) noexcept; // C++20 ///////// returns year_month_weekday // 31 constexpr year_month_weekday -operator/(const year_month& ym, const weekday_indexed& wdi) noexcept; // C++ 20 +operator/(const year_month& ym, const weekday_indexed& wdi) noexcept; // C++20 // 32 constexpr year_month_weekday -operator/(const year& y, const month_weekday& mwd) noexcept; // C++ 20 +operator/(const year& y, const month_weekday& mwd) noexcept; // C++20 // 33 constexpr year_month_weekday -operator/(int y, const month_weekday& mwd) noexcept; // C++ 20 +operator/(int y, const month_weekday& mwd) noexcept; // C++20 // 34 constexpr year_month_weekday -operator/(const month_weekday& mwd, const year& y) noexcept; // C++ 20 +operator/(const month_weekday& mwd, const year& y) noexcept; // C++20 // 35 constexpr year_month_weekday -operator/(const month_weekday& mwd, int y) noexcept; // C++ 20 +operator/(const month_weekday& mwd, int y) noexcept; // C++20 ///////// returns year_month_weekday_last // 36 constexpr year_month_weekday_last -operator/(const year_month& ym, const weekday_last& wdl) noexcept; // C++ 20 +operator/(const year_month& ym, const weekday_last& wdl) noexcept; // C++20 // 37 constexpr year_month_weekday_last -operator/(const year& y, const month_weekday_last& mwdl) noexcept; // C++ 20 +operator/(const year& y, const month_weekday_last& mwdl) noexcept; // C++20 // 38 constexpr year_month_weekday_last -operator/(int y, const month_weekday_last& mwdl) noexcept; // C++ 20 +operator/(int y, const month_weekday_last& mwdl) noexcept; // C++20 // 39 constexpr year_month_weekday_last -operator/(const month_weekday_last& mwdl, const year& y) noexcept; // C++ 20 +operator/(const month_weekday_last& mwdl, const year& y) noexcept; // C++20 // 40 constexpr year_month_weekday_last -operator/(const month_weekday_last& mwdl, int y) noexcept; // C++ 20 +operator/(const month_weekday_last& mwdl, int y) noexcept; // C++20 ``` ### Parameters @@ -1504,9 +1504,9 @@ The year and month. 33\) `year_month_weekday(year(y), mwd.month(), mwd.weekday_indexed())`\ 34\) `year_month_weekday(y, mwd.month(), mwd.weekday_indexed())`\ 35\) `year_month_weekday(year(y), mwd.month(), mwd.weekday_indexed())`\ -36) `year_month_weekday_last(ym.year(), ym.month(), wdl)`\ +36\) `year_month_weekday_last(ym.year(), ym.month(), wdl)`\ 37\) `year_month_weekday_last(y, mwdl.month(), mwdl.weekday_last())`\ -38) `year_month_weekday_last(year(y), mwdl.month(), mwdl.weekday_last())`\ +38\) `year_month_weekday_last(year(y), mwdl.month(), mwdl.weekday_last())`\ 39\) `year_month_weekday_last(y, mwdl.month(), mwdl.weekday_last())`\ 40\) `year_month_weekday_last(year(y), mwdl.month(), mwdl.weekday_last())` diff --git a/docs/standard-library/chrono.md b/docs/standard-library/chrono.md index 26b5c0e830..82bc6ae824 100644 --- a/docs/standard-library/chrono.md +++ b/docs/standard-library/chrono.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: " title: "" -ms.date: 10/13/2021 +description: "Learn more about: " +ms.date: 05/31/2022 f1_keywords: ["", "chrono/std::chrono::nanoseconds", "chrono/std::chrono::minutes", "chrono/std::chrono::seconds", "chrono/std::chrono::hours", "chrono/std::chrono::milliseconds", "chrono/std::chrono::microseconds"] --- @@ -18,6 +18,15 @@ In the Microsoft C++ implementation, `steady_clock::time_point` is now a `typede **Header:** `` +Regional legislatures occasionally make changes to time zones, and an international standards body specifies when new leap seconds should be accounted for. A database of these changes was added to Windows 10. Specifically: + +| Feature | Client version | Server version | +|--|--|--| +| Leap second database updates | Windows 10 version 1809 or later | Windows Server 2019 or later | +| Time zone support | Windows 10 version 1903/19H1 or later | Windows Server 2022 or later | + +Using the time-zone facilities on older versions of Windows results in a runtime error. + **Namespace:** `std` ## Calendrical types @@ -161,7 +170,7 @@ For more information about ratio types that are used in the following typedefs, | `tai_seconds` | A synonym for `tai_time`. A count of seconds, represented by a `time_point` that is associated with a [`tai_clock`](tai-clock-class.md). | | `tai_time` | A synonym for `time_point`. You provide the `Duration`, for example, `tai_time tt;`. Represents a `time_point` for a [`tai_clock`](tai-clock-class.md). | | `utc_seconds` | A synonym for `utc_time;` | -| `utc_time` | A synonym for `time_point`. You provide the `Duration`, for example, `utc_time ut;`. Represents a `time_point`for a [`utc_clock`](utc-clock-class.md). | +| `utc_time` | A synonym for `time_point`. You provide the `Duration`, for example, `utc_time ut;`. Represents a `time_point` for a [`utc_clock`](utc-clock-class.md). | ## Type traits diff --git a/docs/standard-library/clock-time-conversion-struct.md b/docs/standard-library/clock-time-conversion-struct.md index ac13ace42c..865849283d 100644 --- a/docs/standard-library/clock-time-conversion-struct.md +++ b/docs/standard-library/clock-time-conversion-struct.md @@ -1,9 +1,10 @@ --- -description: "Learn more about clock_conversion trait" title: "clock_conversion struct" +description: "Learn more about clock_conversion trait" ms.date: 10/12/2021 -f1_keywords: ["chrono/std::clock_conversion"] -helpviewer_keywords: ["std::chrono [C++], clock_conversion"] +f1_keywords: ["chrono/std::chrono::clock_time_conversion"] +helpviewer_keywords: ["std::chrono [C++], clock_time_conversion"] +dev_langs: ["C++"] --- # `clock_time_conversion` struct @@ -43,7 +44,7 @@ The traits provide the following conversions: 2-4\) Identity conversions. Returns the same clock you pass in.\ 5-6\) Converting between `sys_time` and `utc_time` calls `utc_clock::to_sys` or `utc_clock::from_sys` depending on the direction of the conversion.\ 7-8\) Converting between `sys_time` and the specified clock, when the specified clock supports `to_sys` and `from_sys`, results in a call to `Clock::to_sys` or `Clock::from_sys`, depending on the direction of the conversion.\ -9-10\) Converting between `utc_time`and the specified clock, when the specified clock supports `from_utc` and `to_sys`, results in a call to `Clock::to_utc` or `Clock::from_utc`, depending on the direction of the conversion. +9-10\) Converting between `utc_time` and the specified clock, when the specified clock supports `from_utc` and `to_sys`, results in a call to `Clock::to_utc` or `Clock::from_utc`, depending on the direction of the conversion. ## Members @@ -59,7 +60,7 @@ You usually won't use this trait directly in your code. It's used by the [`clock **Header:** \<`chrono`> -**Namespace:** `std` +**Namespace:** `std::chrono` **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) @@ -100,7 +101,7 @@ The `time_point` to convert. 1-3\) Identity conversions. No conversion. Returns `t` without any changes.\ 4\) Returns `utc_clock::to_sys(t)`.\ -5\) Returns` utc_clock::from_sys(t)`. +5\) Returns `utc_clock::from_sys(t)`. ### Deduction guides diff --git a/docs/standard-library/codecvt-byname-class.md b/docs/standard-library/codecvt-byname-class.md index c21db36b33..e527843ab4 100644 --- a/docs/standard-library/codecvt-byname-class.md +++ b/docs/standard-library/codecvt-byname-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: codecvt_byname Class" -title: "codecvt_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: codecvt_byname class" +title: "codecvt_byname class" +ms.date: 06/29/2022 f1_keywords: ["xlocale/std::codecvt_byname"] helpviewer_keywords: ["codecvt_byname class"] ms.assetid: b63b6c04-f60c-47b9-8e30-a933f24a8ffb --- -# codecvt_byname Class +# `codecvt_byname` class A derived class template that describes an object that can serve as a collate facet of a given locale, enabling the retrieval of information specific to a cultural area concerning conversions. @@ -17,17 +17,13 @@ template class codecvt_byname: public codecvt { public: explicit codecvt_byname( - const char* _Locname, - size_t _Refs = 0); -``` + const char* locale_name, + size_t ref_count = 0); -```cpp explicit codecvt_byname( - const string& _Locname, - size_t _Refs = 0); -``` + const string& locale_name, + size_t ref_count = 0); -```cpp protected: virtual ~codecvt_byname(); @@ -36,17 +32,17 @@ protected: ### Parameters -*_Locname*\ +*`locale_name`*\ A named locale. -*_Refs*\ +*`ref_count`*\ An initial reference count. ## Remarks -Byname facets are automatically created when a named locale is constructed. +`byname` facets are automatically created when a named locale is constructed. -Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [codecvt](../standard-library/codecvt-class.md)\( `_Refs`). +Its behavior is determined by the named locale *`locale_name`*. Each constructor initializes its base object by using `codecvt( ref_count )`. For more information, see [`codecvt`](../standard-library/codecvt-class.md). ## Requirements diff --git a/docs/standard-library/codecvt-class.md b/docs/standard-library/codecvt-class.md index 72eeb2d1cb..43d007c8bb 100644 --- a/docs/standard-library/codecvt-class.md +++ b/docs/standard-library/codecvt-class.md @@ -4,7 +4,6 @@ description: "describes the Microsoft C runtime `codecvt` class API" ms.date: "11/09/2020" f1_keywords: ["xlocale/std::codecvt", "xlocale/std::codecvt::extern_type", "xlocale/std::codecvt::intern_type", "xlocale/std::codecvt::state_type", "xlocale/std::codecvt::always_noconv", "xlocale/std::codecvt::do_always_noconv", "xlocale/std::codecvt::do_encoding", "xlocale/std::codecvt::do_in", "xlocale/std::codecvt::do_length", "xlocale/std::codecvt::do_max_length", "xlocale/std::codecvt::do_out", "xlocale/std::codecvt::do_unshift", "xlocale/std::codecvt::encoding", "xlocale/std::codecvt::in", "xlocale/std::codecvt::length", "xlocale/std::codecvt::max_length", "xlocale/std::codecvt::out", "xlocale/std::codecvt::unshift"] helpviewer_keywords: ["std::codecvt [C++]", "std::codecvt [C++], extern_type", "std::codecvt [C++], intern_type", "std::codecvt [C++], state_type", "std::codecvt [C++], always_noconv", "std::codecvt [C++], do_always_noconv", "std::codecvt [C++], do_encoding", "std::codecvt [C++], do_in", "std::codecvt [C++], do_length", "std::codecvt [C++], do_max_length", "std::codecvt [C++], do_out", "std::codecvt [C++], do_unshift", "std::codecvt [C++], encoding", "std::codecvt [C++], in", "std::codecvt [C++], length", "std::codecvt [C++], max_length", "std::codecvt [C++], out", "std::codecvt [C++], unshift"] -ms.assetid: 37d3efa1-2b7f-42b6-b04f-7a972c8c2c86 --- # `codecvt` Class @@ -228,7 +227,7 @@ virtual result do_in( const Byte*& next1, CharType* first2, CharType* last2, - CharType*& next2,) const; + CharType*& next2) const; ``` ### Parameters @@ -517,7 +516,7 @@ result in( const Byte*& next1, CharType* first2, CharType* last2, - CharType*& next2,) const; + CharType*& next2) const; ``` ### Parameters diff --git a/docs/standard-library/collate-byname-class.md b/docs/standard-library/collate-byname-class.md index 3c79d0aaad..c63a9c2526 100644 --- a/docs/standard-library/collate-byname-class.md +++ b/docs/standard-library/collate-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: collate_byname Class" title: "collate_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: collate_byname Class" +ms.date: 11/04/2016 f1_keywords: ["locale/std::collate_byname"] helpviewer_keywords: ["collate_byname class"] -ms.assetid: 3dc380df-867c-4763-b60e-ba62a8e63ca7 --- # collate_byname Class @@ -40,7 +39,7 @@ An initial reference count. ## Remarks -The class template describes an object that can serve as a [locale facet](../standard-library/locale-class.md#facet_class) of type [collate](../standard-library/collate-class.md#collate)\. Its behavior is determined by the [named](../standard-library/locale-class.md#name) locale *_Locname*. Each constructor initializes its base object with [collate](../standard-library/collate-class.md#collate)\( `_Refs`). +The class template describes an object that can serve as a [locale facet](../standard-library/locale-class.md#facet_class) of type [collate](../standard-library/collate-class.md#collate)\. Its behavior is determined by the [named](../standard-library/locale-class.md#name) locale *_Locname*. Each constructor initializes its base object with [collate](../standard-library/collate-class.md#collate)\(`_Refs`). ## Requirements diff --git a/docs/standard-library/collate-class.md b/docs/standard-library/collate-class.md index fd516200e4..b391fc83bc 100644 --- a/docs/standard-library/collate-class.md +++ b/docs/standard-library/collate-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: collate Class" title: "collate Class" -ms.date: "11/04/2016" +description: "Learn more about: collate Class" +ms.date: 11/04/2016 f1_keywords: ["locale/std::collate", "locale/std::collate::char_type", "locale/std::collate::string_type", "locale/std::collate::compare", "locale/std::collate::do_compare", "locale/std::collate::do_hash", "locale/std::collate::do_transform", "locale/std::collate::hash", "locale/std::collate::transform"] helpviewer_keywords: ["std::collate [C++]", "std::collate [C++], char_type", "std::collate [C++], string_type", "std::collate [C++], compare", "std::collate [C++], do_compare", "std::collate [C++], do_hash", "std::collate [C++], do_transform", "std::collate [C++], hash", "std::collate [C++], transform"] -ms.assetid: 92168798-9628-4a2e-be6e-fa62dcd4d6a6 --- # collate Class @@ -142,7 +141,7 @@ The member function returns: The first sequence compares less if it has the smaller element in the earliest unequal pair in the sequences, or, if no unequal pairs exist, but the first sequence is shorter. -The member function returns [do_compare](#do_compare)( `first1`, `last1`, `first2`, `last2`). +The member function returns [do_compare](#do_compare)(`first1`, `last1`, `first2`, `last2`). ### Example @@ -290,7 +289,7 @@ A hash value of type **`long`** for the sequence. ### Remarks -The member function returns [do_hash](#do_hash)( `first`, `last`). +The member function returns [do_hash](#do_hash)(`first`, `last`). A hash value can be useful, for example, in distributing sequences pseudo-randomly across an array of lists. diff --git a/docs/standard-library/common-type-structure.md b/docs/standard-library/common-type-structure.md index 8262ee434f..2da555a646 100644 --- a/docs/standard-library/common-type-structure.md +++ b/docs/standard-library/common-type-structure.md @@ -2,12 +2,13 @@ description: "Learn more about: common_type Structure" title: "common_type Structure" ms.date: "11/04/2016" -f1_keywords: ["chrono/std::common_type"] -ms.assetid: 2b42722c-c3dc-4d62-8613-0271e52b6f00 +f1_keywords: ["std::common_type"] +helpviewer_keywords: ["std [C++], common_type"] +dev_langs: ["C++"] --- -# common_type Structure +# `common_type` Structure -Describes specializations of class template [common_type](../standard-library/common-type-class.md) for instantiations of [duration](../standard-library/duration-class.md) and [time_point](../standard-library/time-point-class.md). +Describes specializations of class template [`common_type`](../standard-library/common-type-class.md) for instantiations of [`duration`](../standard-library/duration-class.md) and [`time_point`](../standard-library/time-point-class.md). ## Syntax @@ -29,7 +30,7 @@ chrono::time_point>; **Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also diff --git a/docs/standard-library/common-view-class.md b/docs/standard-library/common-view-class.md new file mode 100644 index 0000000000..1480712afd --- /dev/null +++ b/docs/standard-library/common-view-class.md @@ -0,0 +1,156 @@ +--- +title: common_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) common_view class, which takes a view that has different iterator and sentinel types and creates a view that has the same iterator and sentinel type." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::common_view", "ranges/std::common_view::base", "ranges/std::common_view::begin", "ranges/std::common_view::end", "ranges/std::common_view::size", "ranges/std::common_view::empty", "ranges/std::common_view::operator bool", "ranges/std::common_view::data", "ranges/std::common_view::back", "ranges/std::common_view::front", "ranges/std::common_view::operator[]"] +helpviewer_keywords: ["std::ranges::common_view [C++]", "std::ranges::common_view [C++], base", "std::ranges::common_view [C++], begin", "std::ranges::common_view [C++], end", "std::ranges::common_view [C++], size", "std::ranges::common_view [C++], data", "std::ranges::common_view [C++], empty", "std::ranges::common_view [C++], operator bool", "std::ranges::common_view [C++], front", "std::ranges::common_view [C++], back", "std::ranges::common_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `common_view` class (C++ Standard Library) + +Take a range that may have different iterator and sentinel types and create a view that has the same iterator and sentinel type. This is useful for calling STL algorithms that accept ranges specified by iterator pairs. + +## Syntax + +```cpp +template + requires (!ranges::common_range && std::copyable>) +class common_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::common`](range-adaptors.md#common) | +| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `forward_range` or [`random_access_range`](range-concepts.md#random_access_range) when the underlying range satisfies `random_access_range` and [`sized_range`](range-concepts.md#sized_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Yes | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `common_view`. | +| [`base`](#base)C++20 | Get the underlying view. | +| [`begin`](#begin) C++20| Get an iterator to the first element in the view. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create a `common_view` is by using the [`views::common`](range-adaptors.md#common) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +This view is useful for passing a range that has different iterator/sentinel types to a legacy algorithm that expects them to be the same. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `common_view`. + +```cpp +1) common_view() = default; +2) constexpr explicit common_view(V v); +``` + +### Parameters + +*`v`*\ + The underlying view. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Default constructs the `common_view`.\ +2\) Constructs a `common_view` from the underlying view using `std::move(v)`. An error will result if `V` is a common range to avoid misuse that would negatively impact performance. + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +## `begin` + +Get an iterator to the first element. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires range; +``` + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end(); +constexpr auto end() const requires ranges::range; +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## See also + +[``](ranges.md)\ +[`common` range adaptor](range-adaptors.md#common)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/complex-class.md b/docs/standard-library/complex-class.md index 7df8b7f00b..182fbf276c 100644 --- a/docs/standard-library/complex-class.md +++ b/docs/standard-library/complex-class.md @@ -4,9 +4,8 @@ title: "complex Class" ms.date: "03/27/2019" f1_keywords: ["complex/std::complex::value_type", "complex/std::complex::imag", "complex/std::complex::real"] helpviewer_keywords: ["std::complex [C++], value_type", "std::complex [C++], imag", "std::complex [C++], real"] -ms.assetid: d6492e1c-5eba-4bc5-835b-2a88001a5868 --- -# complex Class +# `complex` Class The class template describes an object that stores two objects of type `Type`, one that represents the real part of a complex number and one that represents the imaginary part. @@ -29,7 +28,7 @@ An object of class `Type`: In particular, no subtle differences may exist between copy construction and default construction followed by assignment. None of the operations on objects of class `Type` may throw exceptions. -Explicit specializations of class template complex exist for the three floating-point types. In this implementation, a value of any other type `Type` is typecast to **`double`** for actual calculations, with the **`double`** result assigned back to the stored object of type `Type`. +Explicit specializations of class template `complex` exist for the three floating-point types. In this implementation, a value of any other type `Type` is typecast to **`double`** for actual calculations, with the **`double`** result assigned back to the stored object of type `Type`. ## Members @@ -37,32 +36,32 @@ Explicit specializations of class template complex exist for the three floating- |Name|Description| |-|-| -|[complex](#complex)|Constructs a complex number with specified real and imaginary parts or as a copy of some other complex number.| +|[`complex`](#complex)|Constructs a complex number with specified real and imaginary parts or as a copy of some other complex number.| ### Typedefs |Name|Description| |-|-| -|[value_type](#value_type)|A type that represents the data type used to represent the real and imaginary parts of a complex number.| +|[`value_type`](#value_type)|A type that represents the data type used to represent the real and imaginary parts of a complex number.| ### Functions |Name|Description| |-|-| -|[imag](#imag)|Extracts the imaginary component of a complex number.| -|[real](#real)|Extracts the real component of a complex number.| +|[`imag`](#imag)|Extracts the imaginary component of a complex number.| +|[`real`](#real)|Extracts the real component of a complex number.| ### Operators |Name|Description| |-|-| -|[operator*=](#op_star_eq)|Multiplies a target complex number by a factor, which may be complex or be the same type as are the real and imaginary parts of the complex number.| -|[operator+=](#op_add_eq)|Adds a number to a target complex number, where the number added may be complex or of the same type as are the real and imaginary parts of the complex number to which it is added.| -|[operator-=](#operator-_eq)|Subtracts a number from a target complex number, where the number subtracted may be complex or of the same type as are the real and imaginary parts of the complex number to which it is added.| -|[operator/=](#op_div_eq)|Divides a target complex number by a divisor, which may be complex or be the same type as are the real and imaginary parts of the complex number.| -|[operator=](#op_eq)|Assigns a number to a target complex number, where the number assigned may be complex or of the same type as are the real and imaginary parts of the complex number to which it is being assigned.| +|[`operator*=`](#op_star_eq)|Multiplies a target complex number by a factor, which may be complex or be the same type as are the real and imaginary parts of the complex number.| +|[`operator+=`](#op_add_eq)|Adds a number to a target complex number, where the number added may be complex or of the same type as are the real and imaginary parts of the complex number to which it's added.| +|[`operator-=`](#operator-_eq)|Subtracts a number from a target complex number, where the number subtracted may be complex or of the same type as are the real and imaginary parts of the complex number to which it's added.| +|[`operator/=`](#op_div_eq)|Divides a target complex number by a divisor, which may be complex or be the same type as are the real and imaginary parts of the complex number.| +|[`operator=`](#op_eq)|Assigns a number to a target complex number, where the number assigned may be complex or of the same type as are the real and imaginary parts of the complex number to which it's being assigned.| -## complex +## `complex` Constructs a complex number with specified real and imaginary parts or as a copy of some other complex number. @@ -78,20 +77,20 @@ constexpr complex( ### Parameters -*_RealVal*\ +*`_RealVal`*\ The value of the real part used to initialize the complex number being constructed. -*_ImagVal*\ +*`_ImagVal`*\ The value of the imaginary part used to initialize the complex number being constructed. -*complexNum*\ +*`complexNum`*\ The complex number whose real and imaginary parts are used to initialize the complex number being constructed. ### Remarks -The first constructor initializes the stored real part to *\_RealVal* and the stored imaginary part to *\_Imagval*. The second constructor initializes the stored real part to `complexNum.real()` and the stored imaginary part to `complexNum.imag()`. +The first constructor initializes the stored real part to *`_RealVal`* and the stored imaginary part to *`_Imagval`*. The second constructor initializes the stored real part to `complexNum.real()` and the stored imaginary part to `complexNum.imag()`. -In this implementation, if a translator does not support member template functions, the template: +In this implementation, if a translator doesn't support member template functions, the template: ```cpp template @@ -146,7 +145,7 @@ int main( ) } ``` -## imag +## `imag` Extracts the imaginary component of a complex number. @@ -158,7 +157,7 @@ T imag(const T& right); ### Parameters -*right*\ +*`right`*\ A complex number whose imaginary value is to be extracted. ### Return Value @@ -200,7 +199,7 @@ The real part of c1 is c1.real() = 4. The imaginary part of c1 is c1.imag() = 3. ``` -## operator*= +## `operator*=` Multiplies a target complex number by a factor, which may be complex or be the same type as are the real and imaginary parts of the complex number. @@ -215,7 +214,7 @@ complex& operator*=(const complex& right); ### Parameters -*right*\ +*`right`*\ A complex number or a number that is of the same type as the parameter of the target complex number. ### Return Value @@ -285,9 +284,9 @@ int main() } ``` -## operator+= +## `operator+=` -Adds a number to a target complex number, where the number added may be complex or of the same type as are the real and imaginary parts of the complex number to which it is added. +Adds a number to a target complex number, where the number added may be complex or of the same type as are the real and imaginary parts of the complex number to which it's added. ```cpp template @@ -300,7 +299,7 @@ complex& operator+=(const complex& right); ### Parameters -*right*\ +*`right`*\ A complex number or a number that is of the same type as the parameter of the target complex number. ### Return Value @@ -388,9 +387,9 @@ The modulus of cl2 is: 5 The argument of cl2 is: 0.927295 radians, which is 53.1301 degrees. ``` -## operator-= +## `operator-=` -Subtracts a number from a target complex number, where the number subtracted may be complex or of the same type as are the real and imaginary parts of the complex number to which it is added. +Subtracts a number from a target complex number, where the number subtracted may be complex or of the same type as are the real and imaginary parts of the complex number to which it's added. ```cpp template @@ -403,10 +402,10 @@ complex& operator-=(const complex& complexNum); ### Parameters -*complexNum*\ +*`complexNum`*\ A complex number to be subtracted from the target complex number. -*_RealPart*\ +*`_RealPart`*\ A real number to be subtracted from the target complex number. ### Return Value @@ -496,7 +495,7 @@ The modulus of cl2 is: 5 The argument of cl2 is: 2.2143 radians, which is 126.87 degrees. ``` -## operator/= +## `operator/=` Divides a target complex number by a divisor, which may be complex or be the same type as are the real and imaginary parts of the complex number. @@ -511,10 +510,10 @@ complex& operator/=(const complex& complexNum); ### Parameters -*complexNum*\ +*`complexNum`*\ A complex number to be subtracted from the target complex number. -*_RealPart*\ +*`_RealPart`*\ A real number to be subtracted from the target complex number. ### Return Value @@ -600,9 +599,9 @@ The modulus of cl2 is: 0.6 The argument of cl2 is: 0.523599 radians, which is 30 degrees. ``` -## operator= +## `operator=` -Assigns a number to a target complex number, where the number assigned may be complex or of the same type as are the real and imaginary parts of the complex number to which it is being assigned. +Assigns a number to a target complex number, where the number assigned may be complex or of the same type as are the real and imaginary parts of the complex number to which it's being assigned. ```cpp template @@ -613,7 +612,7 @@ complex& operator=(const Type& right); ### Parameters -*right*\ +*`right`*\ A complex number or a number that is of the same type as the parameter of the target complex number. ### Return Value @@ -678,9 +677,9 @@ The complex number (3, 4) assigned to the complex number cl2 is: cl2 = (3,4) ``` -## real +## `real` -Gets or sets the real component of a complex number. +Gets or sets the `real` component of a complex number. ```cpp constexpr T real() const; @@ -690,16 +689,16 @@ T real(const T& right); ### Parameters -*right*\ -A complex number whose real value is to be extracted. +*`right`*\ +A complex number whose `real` value is to be extracted. ### Return Value -The real part of the complex number. +The `real` part of the complex number. ### Remarks -For a complex number *a + bi*, the real part or component is *Re(a + bi) = a*. +For a complex number *a + bi*, the `real` part or component is *Re(a + bi) = a*. ### Example @@ -732,7 +731,7 @@ The real part of c1 is c1.real() = 4. The imaginary part of c1 is c1.imag() = 3. ``` -## value_type +## `value_type` A type that represents the data type used to represent the real and imaginary parts of a complex number. diff --git a/docs/standard-library/complex-functions.md b/docs/standard-library/complex-functions.md index 657cd55597..82bd707427 100644 --- a/docs/standard-library/complex-functions.md +++ b/docs/standard-library/complex-functions.md @@ -28,7 +28,7 @@ The modulus of a complex number. ### Remarks -The *modulus* of a complex number is a measure of the length of the vector representing the complex number. The modulus of a complex number a + bi is sqrt (a2 + b2), written |a + bi|. The *norm* of a complex number a + bi is (a2 + b2), so the modulus of a complex number is the square root of its norm. +The *modulus* of a complex number is a measure of the length of the vector representing the complex number. The modulus of a complex number *a + bi* is the square root of (*a*2 + *b*2), written \|*a + bi*\|. The *norm* of a complex number *a + bi* is (*a*2 + *b*2). The norm of a complex number is the square of its modulus. ### Example @@ -758,8 +758,7 @@ The norm of a complex number. ### Remarks -The norm of a complex number *a + bi* is *(a*2 *+ b*2*).* The norm of a complex number is the square of its modulus. The modulus of a complex number is a measure of the length of the vector representing the complex number. The modulus of a complex number *a + bi* is `sqrt`*(a*2 *+ b*2*),* written *|a + bi|.* - +The *norm* of a complex number *a + bi* is (*a*2 + *b*2). The norm of a complex number is the square of its modulus. The *modulus* of a complex number is a measure of the length of the vector representing the complex number. The modulus of a complex number *a + bi* is the square root of (*a*2 + *b*2), written \|*a + bi*\|. ### Example ```cpp diff --git a/docs/standard-library/condition-variable-enums.md b/docs/standard-library/condition-variable-enums.md index 2f2e3e650b..23501c7ec3 100644 --- a/docs/standard-library/condition-variable-enums.md +++ b/docs/standard-library/condition-variable-enums.md @@ -1,17 +1,21 @@ --- -description: "Learn more about: enums" title: " enums" -ms.date: "11/04/2016" +description: "Learn more about: enums" +ms.date: 11/04/2016 f1_keywords: ["condition_variable/std::cv_status"] -ms.assetid: f261ad79-e25b-4afa-9f8a-909ce697e0d8 --- # `` enums -## cv_status +The `` header provides the following enums: + +## `cv_status` -Supplies symbolic names for the return values of the methods of class template [condition_variable](../standard-library/condition-variable-class.md). +Supplies symbolic names for the return values of the methods of class template [`condition_variable`](condition-variable-class.md). -class cv_status { - no_timeout - timeout +```cpp +enum class cv_status +{ + no_timeout, + timeout }; +``` diff --git a/docs/standard-library/container-class-swap.md b/docs/standard-library/container-class-swap.md index b318c86669..1e976af371 100644 --- a/docs/standard-library/container-class-swap.md +++ b/docs/standard-library/container-class-swap.md @@ -1,16 +1,18 @@ --- description: "Learn more about: Container Class::swap" title: "Container Class::swap" -ms.date: "11/04/2016" +ms.date: 06/10/2022 helpviewer_keywords: ["swap method"] ms.assetid: 898c219c-bc8e-4d14-a149-6240426c693f +ms.custom: devdivchpfy22 --- + # Container Class::swap > [!NOTE] > This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). -Swaps the controlled sequences between **\*this** and its argument. +Swaps the controlled sequences between `*this` and its argument. ## Syntax @@ -20,7 +22,7 @@ void swap(Container& right); ## Remarks -If **\*this.get\_allocator ==** _right_**.get_allocator**, it does a swap in constant time. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. +If `*this.get_allocator == right.get_allocator`, it does a swap in constant time. Otherwise, it performs element assignments and constructor calls proportional to the number of elements in the two controlled sequences. ## See also diff --git a/docs/standard-library/cpp-standard-library-header-files.md b/docs/standard-library/cpp-standard-library-header-files.md index 42ef673a99..a0eaf3e463 100644 --- a/docs/standard-library/cpp-standard-library-header-files.md +++ b/docs/standard-library/cpp-standard-library-header-files.md @@ -1,9 +1,8 @@ --- title: "C++ standard library header files" description: "C++ standard library header files, categorized" -ms.date: "08/31/2020" +ms.date: 08/31/2020 helpviewer_keywords: ["header files, C++ Standard Library", "C++ Standard Library, header files"] -ms.assetid: e7bf497a-0f63-48d0-9b54-cb0eef4073c4 --- # C++ standard library header files @@ -15,26 +14,26 @@ Header files for the C++ standard library and extensions, by category. | Category | Headers | | - | - | -| [Algorithms](./algorithms.md) | [``](algorithm.md), [``](cstdlib.md), [``](numeric.md) | +| [Algorithms](algorithms.md) | [``](algorithm.md), [``](cstdlib.md), [``](numeric.md) | | Atomic operations | [``](atomic.md)11 | | C library wrappers | [``](cassert.md), [``](ccomplex.md)11 a b, [``](cctype.md), [``](cerrno.md), [``](cfenv.md)11, [``](cfloat.md), [``](cinttypes.md)11, [``](ciso646.md)b, [``](climits.md), [``](clocale.md), [``](cmath.md), [``](csetjmp.md), [``](csignal.md), [``](cstdalign.md)11 a b, [``](cstdarg.md), [``](cstdbool.md)11 a b, [``](cstddef.md), [``](cstdint.md)11, [``](cstdio.md), [``](cstdlib.md), [``](cstring.md), [``](ctgmath.md)11 a b, [``](ctime.md), [``](cuchar.md)11, [``](cwchar.md), [``](cwctype.md) | | Concepts | ``20 | -| [Containers](./stl-containers.md) | | +| [Containers](stl-containers.md) | | | Sequence containers | [``](array.md)11, [``](deque.md), [``](forward-list.md)11, [``](list.md), [``](vector.md) | | Ordered associative containers| [``](map.md), [``](set.md) | | Unordered associative containers | [``](unordered-map.md)11, [``](unordered-set.md)11 | | Container adaptors | [``](queue.md), [``](stack.md) | | Container views | [``](span.md)20 | | [Errors and exception handling](../cpp/errors-and-exception-handling-modern-cpp.md) | [``](cassert.md), [``](exception.md), [``](stdexcept.md), [``](system-error.md)11 | -| General utilities | ``17, [``](bit.md)20, [``](bitset.md), [``](cstdlib.md), ``17, [``](functional.md), [``](memory.md), ``17, ``17, [``](ratio.md)11, [``](scoped-allocator.md)11, [``](tuple.md)11, [``](type-traits.md)11, [``](typeindex.md)11, [``](utility.md), ``17 | +| General utilities | [``](any.md)17, [``](bit.md)20, [``](bitset.md), [``](cstdlib.md), [``](execution.md)17, [``](functional.md), [``](memory.md), [``](memory-resource.md)17, [``](optional.md)17, [``](ratio.md)11, [``](scoped-allocator.md)11, [``](tuple.md)11, [``](type-traits.md)11, [``](typeindex.md)11, [``](utility.md), [``](variant.md)17 | | [I/O and formatting](../text/string-and-i-o-formatting-modern-cpp.md) | [``](cinttypes.md)11, [``](cstdio.md), [``](filesystem.md)17, [``](fstream.md), [``](iomanip.md), [``](ios.md), [``](iosfwd.md), [``](iostream.md), [``](istream.md), [``](ostream.md), [``](sstream.md), [``](streambuf.md), [``](strstream.md)c, ``20 | | Iterators | [``](iterator.md) | | Language support | [``](cfloat.md), [``](climits.md), [``](codecvt.md)11 a, ``20, ``20, ``20, [``](csetjmp.md), [``](csignal.md), [``](cstdarg.md), [``](cstddef.md), [``](cstdint.md)11, [``](cstdlib.md), [``](exception.md), [``](initializer-list.md)11, [``](limits.md), [``](new.md), [``](typeinfo.md), ``20 | | Localization | [``](clocale.md), [``](codecvt.md)11 a, [``](cvt-wbuffer.md), [``](cvt-wstring.md), [``](locale.md) | -| Math and numerics | ``20, [``](cfenv.md)11, [``](cmath.md), [``](complex.md), [``](cstdlib.md), [``](limits.md), [``](numeric.md), [``](random.md)11, [``](ratio.md)11, [``](valarray.md) | -| [Memory management](../cpp/smart-pointers-modern-cpp.md) | [``](allocators-header.md), [``](memory.md), ``17, [``](new.md), [``](scoped-allocator.md)11 | +| Math and numerics | [``](bit.md)20, [``](cfenv.md)11, [``](cmath.md), [``](complex.md), [``](cstdlib.md), [``](limits.md), [``](numeric.md), [``](random.md)11, [``](ratio.md)11, [``](valarray.md) | +| [Memory management](../cpp/smart-pointers-modern-cpp.md) | [``](allocators-header.md), [``](memory.md), [``](memory-resource.md)17, [``](new.md), [``](scoped-allocator.md)11 | | Multithreading | [``](atomic.md)11, [``](condition-variable.md)11, [``](future.md)11, [``](mutex.md)11, [``](shared-mutex.md)14, [``](thread.md)11 | -| Ranges | ``20 | +| Ranges | [``](ranges.md)20 | | Regular expressions | [``](regex.md)11 | | Strings and character data | [``](charconv.md)17, [``](cctype.md), [``](cstdlib.md), [``](cstring.md), [``](cuchar.md)11, [``](cwchar.md), [``](cwctype.md), [``](regex.md)11, [``](string.md), [``](string-view.md)17 | | Time | [``](chrono.md)11, [``](ctime.md) | @@ -53,9 +52,9 @@ Header files for the C++ standard library and extensions, by category. |Category|Headers| |-|-| -|[Algorithms](./algorithms.md)|[``](algorithm.md)| +|[Algorithms](algorithms.md)|[``](algorithm.md)| |C library wrappers|[``](cassert.md), [``](cctype.md), [``](cerrno.md), [``](cfenv.md), [``](cfloat.md), [``](cinttypes.md), [``](ciso646.md), [``](climits.md), [``](clocale.md), [``](cmath.md), [``](csetjmp.md), [``](csignal.md), [``](cstdarg.md), [``](cstdbool.md), [``](cstddef.md), [``](cstdint.md), [``](cstdio.md), [``](cstdlib.md), [``](cstring.md), [``](ctgmath.md), [``](ctime.md), [``](cwchar.md), [``](cwctype.md)| -|[Containers](./stl-containers.md)|| +|[Containers](stl-containers.md)|| |Sequence containers|[``](array.md), [``](deque.md), [``](forward-list.md), [``](list.md), [``](vector.md)| |Ordered associative containers| [``](map.md), [``](set.md)| |Unordered associative containers|[``](unordered-map.md), [``](unordered-set.md)| diff --git a/docs/standard-library/cpp-standard-library-overview.md b/docs/standard-library/cpp-standard-library-overview.md index d973bef5be..f32d101959 100644 --- a/docs/standard-library/cpp-standard-library-overview.md +++ b/docs/standard-library/cpp-standard-library-overview.md @@ -1,55 +1,74 @@ --- -description: "Learn more about: C++ Standard Library Overview" -title: "C++ Standard Library Overview" -ms.date: "11/04/2016" -helpviewer_keywords: ["headers, C++ library", "C++ Standard Library", "libraries, Standard C++", "C++ Standard Library, headers"] -ms.assetid: 7acb83a4-da73-4ad3-bc30-a71289db7f60 +description: "Learn more about: C++ Standard Library (STL) Overview" +title: "C++ Standard Library Overview (STL)" +ms.date: "08/18/2022" +helpviewer_keywords: ["headers, C++ library", "C++ Standard Library", "libraries, Standard C++", "C++ Standard Library, headers", "STL", "Standard template library, headers"] --- -# C++ Standard Library Overview +# C++ Standard Library (STL) overview -All C++ library entities are declared or defined in one or more standard headers. This implementation includes two additional headers, `` and ``, that are not required by the C++ Standard. For a complete list of headers that this implementation supports, see [Header Files Reference](../standard-library/cpp-standard-library-header-files.md). +All C++ library entities are declared or defined in one or more standard headers. This implementation includes two other headers, `` and ``, that aren't required by the C++ Standard. For a complete list of headers that this implementation supports, see [Header files reference](../standard-library/cpp-standard-library-header-files.md). -A freestanding implementation of the C++ library provides only a subset of these headers: +The C++ standard defines two kinds of conforming libraries: +- A *hosted implementation*, which supports all of the required standard library headers described by the C++ ISO standard. +- A *freestanding implementation*, which requires only a subset of the standard library headers. The required subset is: -[``](../standard-library/cstdarg.md)\ -[``](../standard-library/cstddef.md)\ -[``](../standard-library/cstdlib.md) (declaring at least the functions `abort`, `atexit`, and `exit`)\ -[``](../standard-library/exception.md)\ -[``](../standard-library/limits.md)\ -[``](../standard-library/new.md) +| Freestanding header subset |   |   | +|--|--|--| +| [``](../standard-library/atomic.md) (declaring at least `atomic_signed_lock_free` and `atomic_unsigned_lock_free`) | [``](../standard-library/cstdint.md) | [``](../standard-library/ranges.md) | +| [``](../standard-library/bit.md) | [``](../standard-library/cstdlib.md) (declaring at least `abort`, `atexit`, `at_quick_exit`, `exit`, `quick_exit`) | [``](../standard-library/ratio.md) | +| [``](../standard-library/cfloat.md) | [``](../standard-library/exception.md) | [``](../standard-library/tuple.md) | +| [``](../standard-library/climits.md) | [``](../standard-library/functional.md) | [``](../standard-library/typeinfo.md) | +| `` | [``](../standard-library/initializer-list.md) | `` | +| `` | [``](../standard-library/iterator.md) | [``](../standard-library/type-traits.md) | +| `` | [``](../standard-library/limits.md) | [``](../standard-library/utility.md) | +| [``](../standard-library/cstdarg.md) | [``](../standard-library/memory.md) | `` | +| [``](../standard-library/cstddef.md) | [``](../standard-library/new.md) | | + +The following headers are deprecated since C++11: [``](../standard-library/ciso646.md), [``](../standard-library/cstdalign.md), and [``](../standard-library/cstdbool.md). + +Other differences between freestanding and hosted implementations are: + +- Hosted implementations require a global function named `main`. A freestanding implementation can define its own startup and termination functions. +- Hosted implementations must support more than one thread running at the same time. Implementors of freestanding implementations decide whether their library supports concurrent threads. + +The Microsoft C++ standard library satisfies both freestanding and hosted requirements. The C++ library headers have two broader subdivisions: - [iostreams](../standard-library/iostreams-conventions.md) conventions. -- [C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) conventions. +- [C++ Standard library (STL) reference](../standard-library/cpp-standard-library-reference.md) conventions. This section contains the following sections: -- [Using C++ Library Headers](../standard-library/using-cpp-library-headers.md) +- [Using C++ library headers](../standard-library/using-cpp-library-headers.md) -- [C++ Library Conventions](../standard-library/cpp-library-conventions.md) +- [C++ library conventions](../standard-library/cpp-library-conventions.md) - [iostreams Conventions](../standard-library/iostreams-conventions.md) -- [C++ Program Startup and Termination](../standard-library/cpp-program-startup-and-termination.md) +- [C++ program startup and termination](../standard-library/cpp-program-startup-and-termination.md) -- [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md) +- [Safe libraries: C++ standard library](../standard-library/safe-libraries-cpp-standard-library.md) -- [Checked Iterators](../standard-library/checked-iterators.md) +- [Checked iterators](../standard-library/checked-iterators.md) -- [Debug Iterator Support](../standard-library/debug-iterator-support.md) +- [Debug iterator support](../standard-library/debug-iterator-support.md) -- [C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) +- [C++ standard library (STL) reference](../standard-library/cpp-standard-library-reference.md) -- [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +- [Thread safety in the C++ standard library](../standard-library/thread-safety-in-the-cpp-standard-library.md) -- [stdext Namespace](../standard-library/stdext-namespace.md) +- [stdext namespace](../standard-library/stdext-namespace.md) -- [Regular Expressions (C++)](../standard-library/regular-expressions-cpp.md) +- [Regular expressions (C++)](../standard-library/regular-expressions-cpp.md) For more information about Visual C++ run-time libraries, see [CRT Library Features](../c-runtime-library/crt-library-features.md). +> [!NOTE] +> Microsoft's implementation of the C++ Standard Library is often referred to as the *STL* or *Standard Template Library*. Although *C++ Standard Library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ Standard Library, along with the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is also used to refer to the containers and algorithms parts of the C++ Standard Library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ Standard Library as a whole. + ## See also [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/standard-library/cpp-standard-library-reference.md b/docs/standard-library/cpp-standard-library-reference.md index 2066af8094..6ae574d37e 100644 --- a/docs/standard-library/cpp-standard-library-reference.md +++ b/docs/standard-library/cpp-standard-library-reference.md @@ -1,23 +1,28 @@ --- -description: "Learn more about: C++ Standard Library Reference" title: "C++ Standard Library Reference" -ms.date: "3/5/2021" -helpviewer_keywords: ["C++ Standard Library, reference", "C++ Standard Library", "template libraries", "libraries, Standard C++"] +description: "Learn more about: C++ Standard Library Reference (STL)" +ms.date: 3/5/2021 +helpviewer_keywords: ["C++ Standard Library, reference", "C++ Standard Library", "template libraries", "libraries, Standard C++", "Microsoft standard template library, reference", "Microsoft STL, reference"] --- -# C++ Standard Library reference +# C++ Standard Library reference (STL) A C++ program can call on a large number of functions from this conforming implementation of the C++ Standard Library. These functions perform services such as input and output and provide efficient implementations of frequently used operations. For more information about linking with the appropriate Visual C++ runtime `.lib` file, see [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md). +> [!NOTE] +> Microsoft's implementation of the C++ Standard Library is often referred to as the *STL* or *Standard Template Library*. Although *C++ Standard Library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. + +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ Standard Library, along with the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ Standard Library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ Standard Library as a whole. + ## In this section -[C++ Standard Library overview](../standard-library/cpp-standard-library-overview.md)\ +[C++ Standard Library overview](cpp-standard-library-overview.md)\ Provides an overview of the Microsoft implementation of the C++ Standard Library. -[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostream` programming](iostream-programming.md)\ Provides an overview of `iostream` programming. -[Header files reference](../standard-library/cpp-standard-library-header-files.md)\ +[Header files reference](cpp-standard-library-header-files.md)\ Provides links to reference topics about the C++ Standard Library header files, with code examples. diff --git a/docs/standard-library/cstdlib.md b/docs/standard-library/cstdlib.md index b0137c6548..23ba4ea2b1 100644 --- a/docs/standard-library/cstdlib.md +++ b/docs/standard-library/cstdlib.md @@ -4,20 +4,19 @@ title: "" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: ["cstdlib header"] -ms.assetid: 0a6aaebf-84e9-4b60-ae90-17e11981cf54 --- # `` -Includes the C Standard library header \ and adds the associated names to the `std` namespace. Including this header ensures that the names declared using external linkage in the C standard library header are declared in the `std` namespace. +Includes the C Standard library header `` and adds the associated names to the `std` namespace. Including this header ensures that the names declared using external linkage in the C standard library header are declared in the `std` namespace. > [!NOTE] -> \ doesn't include the type **`wchar_t`**. +> `` doesn't include the type **`wchar_t`**. ## Requirements -**Header**: \ +**Header**: `` -**Namespace:** std +**Namespace:** `std` ## Namespace and Macros @@ -49,16 +48,16 @@ extern "C++" using compare-pred = int(const void*, const void*); |Function|Description| |-|-| -|[_Exit](#_exit)|Terminates program without using destructors or registered functions.| -|[abort](#abort)|Terminates program without using destructors.| -|[atexit](#atexit)|Registers function for program termination.| -|[exit](#exit)|Destroys objects with thread and static storage, then returns control.| -|[at_quick_exit](#at_quick_exit)|Registers function without arguments for program termination.| -|[quick_exit](#quick_exit)|Registers function with preserved objects for program termination.| -|[getenv](#getenv)|See C standard library reference.| -|[system](#system)|See C standard library reference.| +|[`_Exit`](#_exit)|Terminates program without using destructors or registered functions.| +|[`abort`](#abort)|Terminates program without using destructors.| +|[`atexit`](#atexit)|Registers function for program termination.| +|[`exit`](#exit)|Destroys objects with thread and static storage, then returns control.| +|[`at_quick_exit`](#at_quick_exit)|Registers function without arguments for program termination.| +|[`quick_exit`](#quick_exit)|Registers function with preserved objects for program termination.| +|[`getenv`](#getenv)|See C standard library reference.| +|[`system`](#system)|See C standard library reference.| -### _Exit +### `_Exit` ```cpp [[noreturn]] void _Exit(int status) noexcept; @@ -68,7 +67,7 @@ extern "C++" using compare-pred = int(const void*, const void*); The program is terminated without executing destructors for objects of automatic, thread, or static storage duration and without calling functions passed to `atexit()`. The function `_Exit` is signal-safe. -### abort +### `abort` ```cpp [[noreturn]] void abort() noexcept; @@ -78,7 +77,7 @@ The program is terminated without executing destructors for objects of automatic The program is terminated without executing destructors for objects of automatic, thread, or static storage duration and without calling functions passed to `atexit()`. The function `abort` is signal-safe. -### at_quick_exit +### `at_quick_exit` ```cpp int at_quick_exit(c-atexit-handler * func) noexcept; @@ -91,9 +90,9 @@ Zero if the registration succeeds, non-zero if it fails. #### Remarks -The `at_quick_exit()` functions register a function *func*, which is called without arguments when `quick_exit` is called. A call to `at_quick_exit()` that doesn't happen before all calls to `quick_exit` may not succeed. The `at_quick_exit()` functions don't introduce a data race. The order of registration may be indeterminate if `at_quick_exit` was called from more than one thread. Since `at_quick_exit` registrations are distinct from the `atexit` registrations, applications may need to call both registration functions using the same argument. MSVC supports the registration of at least 32 functions. +The `at_quick_exit()` functions register a function *`func`*, which is called without arguments when `quick_exit()` is called. A call to `at_quick_exit()` that doesn't happen before all calls to `quick_exit()` may not succeed. The `at_quick_exit()` functions don't introduce a data race. The order of registration may be indeterminate if `at_quick_exit()` was called from more than one thread. Since `at_quick_exit()` registrations are distinct from the `atexit()` registrations, applications may need to call both registration functions using the same argument. MSVC supports the registration of at least 32 functions. -### atexit +### `atexit` ```cpp int atexit(c-atexit-handler * func) noexcept; @@ -102,13 +101,13 @@ int atexit(atexit-handler * func) noexcept; #### Remarks -The `atexit()` functions register the function pointed to by *func* to be called without arguments at normal program termination. A call to `atexit()` that doesn't happen before a call to `exit()` may not succeed. The `atexit()` functions don't introduce a data race. +The `atexit()` functions register the function pointed to by *`func`* to be called without arguments at normal program termination. A call to `atexit()` that doesn't happen before a call to `exit()` may not succeed. The `atexit()` functions don't introduce a data race. #### Return Value Returns zero if the registration succeeds, nonzero if it fails. -### exit +### `exit` ```cpp [[noreturn]] void exit(int status); @@ -118,19 +117,19 @@ Returns zero if the registration succeeds, nonzero if it fails. First, objects with thread storage duration and associated with the current thread are destroyed. -Next, objects with static storage duration are destroyed and functions registered by calling `atexit` are called. Automatic objects aren't destroyed when `exit()` is called. If control leaves a registered function called by `exit` because the function doesn't provide a handler for a thrown exception, `std::terminate()` is called. A function is called once for every time it's registered. Objects with automatic storage duration are all destroyed in a program whose `main` function contains no automatic objects and executes the call to `exit()`. Control can be transferred directly to such a `main` function by throwing an exception that's caught in `main`. +Next, objects with static storage duration are destroyed and functions registered by calling `atexit()` are called. Automatic objects aren't destroyed when `exit()` is called. If control leaves a registered function called by `exit()` because the function doesn't provide a handler for a thrown exception, `std::terminate()` is called. A function is called once for every time it's registered. Objects with automatic storage duration are all destroyed in a program whose `main` function contains no automatic objects and executes the call to `exit()`. Control can be transferred directly to such a `main` function by throwing an exception that's caught in `main`. -Next, all open C streams (as mediated by the function signatures declared in \) with unwritten buffered data are flushed, all open C streams are closed, and all files created by calling `tmpfile()` are removed. +Next, all open C streams (as mediated by the function signatures declared in ``) with unwritten buffered data are flushed, all open C streams are closed, and all files created by calling `tmpfile()` are removed. -Finally, control is returned to the host environment. When *status* is zero or EXIT_SUCCESS, an implementation-defined form of the status successful termination is returned. MSVC returns a value of zero. If *status* is EXIT_FAILURE, MSVC returns a value of 3. Otherwise, MSVC returns the *status* parameter value. +Finally, control is returned to the host environment. When *`status`* is zero or `EXIT_SUCCESS`, an implementation-defined form of the status successful termination is returned. MSVC returns a value of zero. If *`status`* is `EXIT_FAILURE`, MSVC returns a value of 3. Otherwise, MSVC returns the *`status`* parameter value. -### getenv +### `getenv` ```cpp char* getenv(const char* name); ``` -### quick_exit +### `quick_exit` ```cpp [[noreturn]] void quick_exit(int status) noexcept; @@ -138,9 +137,9 @@ char* getenv(const char* name); #### Remarks -Generally, functions registered by calls to `at_quick_exit` are called in the reverse order of their registration. This order doesn't apply to functions registered after other registered functions have already been called. No objects are destroyed when `quick_exit` is called. If control leaves a registered function called by `quick_exit` because the function doesn't provide a handler for a thrown exception, `std::terminate()` is called. A function registered via `at_quick_exit` is invoked by the thread that calls `quick_exit`, which can be a different thread than the one that registered it. That means registered functions shouldn't rely on the identity of objects that have thread storage duration. After calling registered functions, `quick_exit` calls `_Exit(status)`. The standard file buffers aren't flushed. The function `quick_exit` is signal-safe when the functions registered with `at_quick_exit` are. +Generally, functions registered by calls to `at_quick_exit()` are called in the reverse order of their registration. This order doesn't apply to functions registered after other registered functions have already been called. No objects are destroyed when `quick_exit()` is called. If control leaves a registered function called by `quick_exit()` because the function doesn't provide a handler for a thrown exception, `std::terminate()` is called. A function registered via `at_quick_exit()` is invoked by the thread that calls `quick_exit()`, which can be a different thread than the one that registered it. That means registered functions shouldn't rely on the identity of objects that have thread storage duration. After calling registered functions, `quick_exit()` calls `_Exit(status)`. The standard file buffers aren't flushed. The function `quick_exit()` is signal-safe when the functions registered with `at_quick_exit()` are. -### system +### `system` ```cpp int system(const char* string); diff --git a/docs/standard-library/ctgmath.md b/docs/standard-library/ctgmath.md index 52245a16f9..3a56279315 100644 --- a/docs/standard-library/ctgmath.md +++ b/docs/standard-library/ctgmath.md @@ -5,7 +5,7 @@ ms.date: "6/28/2021" f1_keywords: [""] helpviewer_keywords: ["ctgmath header"] --- -# ``; +# `` In effect, includes the C++ standard library headers `` and ``, which provide type-generic math macros equivalent to ``. diff --git a/docs/standard-library/ctype-base-class.md b/docs/standard-library/ctype-base-class.md index e09adff985..f42c4ab52c 100644 --- a/docs/standard-library/ctype-base-class.md +++ b/docs/standard-library/ctype-base-class.md @@ -62,7 +62,7 @@ It defines an enumeration mask. Each enumeration constant characterizes a differ - **graph** (function [isgraph](../standard-library/locale-functions.md#isgraph)) -You can characterize a combination of classifications by ORing these constants. In particular, it is always true that **alnum** == ( **alpha** | **digit**\) and **graph** \=\= \( **alnum** | **punct**). +You can characterize a combination of classifications by a bitwise OR of these constants. In particular, it's always true that **alnum** == ( **alpha** \| **digit** ) and **graph** == ( **alnum** \| **punct** ). ## Requirements diff --git a/docs/standard-library/ctype-byname-class.md b/docs/standard-library/ctype-byname-class.md index f8c4a59667..b959d0f601 100644 --- a/docs/standard-library/ctype-byname-class.md +++ b/docs/standard-library/ctype-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: ctype_byname Class" title: "ctype_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: ctype_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xlocale/std::ctype_byname"] helpviewer_keywords: ["ctype_byname class"] -ms.assetid: a5cec021-a1f8-425f-8757-08e6f064b604 --- # ctype_byname Class @@ -33,7 +32,7 @@ protected: ## Remarks -Its behavior is determined by the named locale `_Locname`. Each constructor initializes its base object with [ctype](../standard-library/ctype-class.md)\( `_Refs`) or the equivalent for base class `ctype`. +Its behavior is determined by the named locale `_Locname`. Each constructor initializes its base object with [ctype](../standard-library/ctype-class.md)\(`_Refs`) or the equivalent for base class `ctype`. ## Requirements diff --git a/docs/standard-library/ctype-char-class.md b/docs/standard-library/ctype-char-class.md index 32beff1c35..d56cfcc811 100644 --- a/docs/standard-library/ctype-char-class.md +++ b/docs/standard-library/ctype-char-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: ctype Class" title: "ctype Class" -ms.date: "11/04/2016" +description: "Learn more about: ctype Class" +ms.date: 11/04/2016 f1_keywords: ["ctype", "locale/std::ctype"] helpviewer_keywords: ["ctype class"] -ms.assetid: ee30acb4-a743-405e-b3d4-13602092da84 --- # `ctype` Class -The class is an explicit specialization of class template `ctype\` to type **`char`**, describing an object that can serve as a locale facet to characterize various properties of a character of type **`char`**. +The class is an explicit specialization of class template `ctype` to type **`char`**, describing an object that can serve as a locale facet to characterize various properties of a character of type **`char`**. ## Syntax diff --git a/docs/standard-library/ctype-class.md b/docs/standard-library/ctype-class.md index 3d1e8a56ab..1836e4e654 100644 --- a/docs/standard-library/ctype-class.md +++ b/docs/standard-library/ctype-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: ctype Class" title: "ctype Class" -ms.date: "11/04/2016" +description: "Learn more about: ctype Class" +ms.date: 11/04/2016 f1_keywords: ["xlocale/std::ctype", "xlocale/std::ctype::char_type", "xlocale/std::ctype::do_is", "xlocale/std::ctype::do_narrow", "xlocale/std::ctype::do_scan_is", "xlocale/std::ctype::do_scan_not", "xlocale/std::ctype::do_tolower", "xlocale/std::ctype::do_toupper", "xlocale/std::ctype::do_widen", "xlocale/std::ctype::is", "xlocale/std::ctype::narrow", "xlocale/std::ctype::scan_is", "xlocale/std::ctype::scan_not", "xlocale/std::ctype::tolower", "xlocale/std::ctype::toupper", "xlocale/std::ctype::widen"] helpviewer_keywords: ["std::ctype [C++]", "std::ctype [C++], char_type", "std::ctype [C++], do_is", "std::ctype [C++], do_narrow", "std::ctype [C++], do_scan_is", "std::ctype [C++], do_scan_not", "std::ctype [C++], do_tolower", "std::ctype [C++], do_toupper", "std::ctype [C++], do_widen", "std::ctype [C++], is", "std::ctype [C++], narrow", "std::ctype [C++], scan_is", "std::ctype [C++], scan_not", "std::ctype [C++], tolower", "std::ctype [C++], toupper", "std::ctype [C++], widen"] -ms.assetid: 3627154c-49d9-47b5-b28f-5bbedee38e3b --- # ctype Class @@ -118,7 +117,7 @@ The possible values for the *_Refs* parameter and their significance are: No direct examples are possible, because the destructor is protected. -The constructor initializes its `locale::facet` base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)( `_Refs`). +The constructor initializes its `locale::facet` base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)(`_Refs`). ## ctype::do_is @@ -160,7 +159,7 @@ The second member function returns an array containing the mask values character ### Remarks -The mask values classifying the attributes of the characters are provided by the class [ctype_base](../standard-library/ctype-base-class.md), from which ctype derives. The first member function can accept expressions for its first parameter referred to as bitmasks and formed from the combination of mask values by the logical bitwise operators (| , & , ^ , ~). +The mask values classifying the attributes of the characters are provided by the class [ctype_base](../standard-library/ctype-base-class.md), from which ctype derives. The first member function can accept expressions for its first parameter referred to as bitmasks and formed from the combination of mask values by the bitwise operators (`|`, `&`, `^`, `~`). ### Example @@ -207,7 +206,7 @@ The second protected member function returns a pointer to the destination range ### Remarks -The second protected member template function stores in `dest`[ `I`] the value `do_narrow`( `first` [ `I`], `default`), for `I` in the interval [0, `last` - `first`). +The second protected member template function stores in `dest`[ `I`] the value `do_narrow`(`first` [ `I`], `default`), for `I` in the interval [0, `last` - `first`). ### Example @@ -241,7 +240,7 @@ A pointer to the first character in a range that does match a specified mask. If ### Remarks -The protected member function returns the smallest pointer `ptr` in the range [ `first`, `last`) for which [do_is](#do_is)( `maskVal`, \* `ptr`) is true. +The protected member function returns the smallest pointer `ptr` in the range [ `first`, `last`) for which [do_is](#do_is)(`maskVal`, \* `ptr`) is true. ### Example @@ -275,7 +274,7 @@ A pointer to the first character in a range that doesn't match a specified mask. ### Remarks -The protected member function returns the smallest pointer `ptr` in the range [ `first`, `last`) for which [do_is](#do_is)( `maskVal`, \* `ptr`) is false. +The protected member function returns the smallest pointer `ptr` in the range [ `first`, `last`) for which [do_is](#do_is)(`maskVal`, \* `ptr`) is false. ### Example @@ -310,7 +309,7 @@ The first protected member function returns the lowercase form of the parameter ### Remarks -The second protected member template function replaces each element `first` [ `I`], for `I` in the interval [0, `last` - `first`), with `do_tolower`( `first` [ `I`]). +The second protected member template function replaces each element `first` [ `I`], for `I` in the interval [0, `last` - `first`), with `do_tolower`(`first` [ `I`]). ### Example @@ -345,7 +344,7 @@ The first protected member function returns the uppercase form of the parameter ### Remarks -The second protected member template function replaces each element `first` [ `I`], for `I` in the interval [0, `last` - `first`), with `do_toupper`( `first` [ `I`]). +The second protected member template function replaces each element `first` [ `I`], for `I` in the interval [0, `last` - `first`), with `do_toupper`(`first` [ `I`]). ### Example @@ -386,7 +385,7 @@ The second protected member function returns a pointer to the destination range ### Remarks -The second protected member template function stores in `dest`[ `I`] the value `do_widen`( `first`[ `I`]), for `I` in the interval [0, `last` - `first`). +The second protected member template function stores in `dest`[ `I`] the value `do_widen`(`first`[ `I`]), for `I` in the interval [0, `last` - `first`). ### Example @@ -430,7 +429,7 @@ The second member function returns a pointer to the last character in the range ### Remarks -The mask values classifying the attributes of the characters are provided by the class [ctype_base Class](../standard-library/ctype-base-class.md), from which ctype derives. The first member function can accept expressions for its first parameter referred to as bitmasks and formed from the combination of mask values by the logical bitwise operators (| , & , ^ , ~). +The mask values classifying the attributes of the characters are provided by the class [ctype_base Class](../standard-library/ctype-base-class.md), from which ctype derives. The first member function can accept expressions for its first parameter referred to as bitmasks and formed from the combination of mask values by the bitwise operators (`|`, `&`, `^`, `~`). ### Example @@ -466,7 +465,7 @@ int main() { cout << string[i] << ": " << (maskarray[i] & ctype_base::alpha "alpha" : "not alpha") - << endl;; + << endl; }; } ``` @@ -734,7 +733,7 @@ The second member function returns *last*. ### Remarks -The first member function returns [do_toupper](#do_toupper)(`ch`). The second member function returns [do_toupper](#do_toupper)( `first`, `last`). +The first member function returns [do_toupper](#do_toupper)(`ch`). The second member function returns [do_toupper](#do_toupper)(`first`, `last`). ### Example diff --git a/docs/standard-library/cvt-wbuffer.md b/docs/standard-library/cvt-wbuffer.md index 58d5cc7cc3..09f8a4bcb6 100644 --- a/docs/standard-library/cvt-wbuffer.md +++ b/docs/standard-library/cvt-wbuffer.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: ["stdext.cvt.", "stdext::cvt::", ""] helpviewer_keywords: ["cvt/wbuffer header"] -ms.assetid: 6e6eb44c-1bc4-4d8c-a4bd-b39c753ce725 --- # `` -The header `` in previous versions of Visual Studio defined the class template [wbuffer_convert Class](../standard-library/wbuffer-convert-class.md) in the stdext::cvt namespace. The header is maintained for backward compatibility. New code should use the version of the class that is defined in [\](../standard-library/locale.md) in the `std` namespace +The header `` in previous versions of Visual Studio defined the class template [`wbuffer_convert`](../standard-library/wbuffer-convert-class.md) in the stdext::cvt namespace. The header is maintained for backward compatibility. New code should use the version of the class that is defined in [\](../standard-library/locale.md) in the `std` namespace ## Syntax diff --git a/docs/standard-library/cvt-wstring.md b/docs/standard-library/cvt-wstring.md index 3ce22b8c32..c2ca25ac7e 100644 --- a/docs/standard-library/cvt-wstring.md +++ b/docs/standard-library/cvt-wstring.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: ["stdext.cvt.", "", "stdext::cvt::"] helpviewer_keywords: ["cvt/wstring header"] -ms.assetid: d78b04bb-9ac0-4adb-8ffe-3aefb9b14c2d --- # `` -The header `` in previous versions of Visual Studio defined the class template [wstring_convert Class](../standard-library/wstring-convert-class.md) in the stdext::cvt namespace. The header is maintained for backward compatibility. New code should use the version of the class that is defined in [\](../standard-library/locale.md) in the `std` namespace +The header `` in previous versions of Visual Studio defined the class template [`wstring_convert`](wstring-convert-class.md) in the `stdext::cvt` namespace. The header is maintained for backward compatibility. New code should use the version of the class that is defined in [``](locale.md) in the `std` namespace. ## Syntax @@ -16,8 +15,6 @@ The header `` in previous versions of Visual Studio defined the cla #include ``` -## Requirements - ## See also [Header Files Reference](../standard-library/cpp-standard-library-header-files.md) diff --git a/docs/standard-library/day-class.md b/docs/standard-library/day-class.md index 26120059e6..5501b49af9 100644 --- a/docs/standard-library/day-class.md +++ b/docs/standard-library/day-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: day Class" title: "day class" +description: "Learn more about: day Class" ms.date: 09/07/2021 -f1_keywords: ["chrono/std::chrono::day", "chrono/std::chrono::day::ok", "chrono/std::chrono::day:operator++", "chrono/std::chrono::day::operator--", "chrono/std::chrono::day::operator unsigned"] +f1_keywords: ["chrono/std::chrono::day", "chrono/std::chrono::day::ok", "chrono/std::chrono::day::operator++", "chrono/std::chrono::day::operator--", "chrono/std::chrono::day::operator unsigned"] helpviewer_keywords: ["std::chrono [C++], day"] +dev_langs: ["C++"] --- # `day` class @@ -12,7 +13,7 @@ Represents a day of the month. For example, the 25th day of the month. ## Syntax ```cpp -class day; // C++ 20 +class day; // C++20 ``` ## Remarks @@ -269,4 +270,4 @@ int main() [`month_day_last` class](month-day-last-class.md)\ [`year_month_day`](year-month-day-class.md)\ [`year_month_day_last`](year-month-day-last-class.md)\ -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) \ No newline at end of file +[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) diff --git a/docs/standard-library/debug-iterator-support.md b/docs/standard-library/debug-iterator-support.md index 66a3ccf04d..fa3a18b7bc 100644 --- a/docs/standard-library/debug-iterator-support.md +++ b/docs/standard-library/debug-iterator-support.md @@ -3,7 +3,6 @@ description: "Learn more about: Debug Iterator Support" title: "Debug Iterator Support" ms.date: "09/13/2018" helpviewer_keywords: ["Safe Libraries", "Safe Libraries, C++ Standard Library", "Safe C++ Standard Library", "C++ Standard Library, debug iterator support", "iterators, debug iterator support", "iterators, incompatible", "incompatible iterators", "debug iterator support"] -ms.assetid: f3f5bd15-4be8-4d64-a4d0-8bc0761c68b6 --- # Debug Iterator Support @@ -43,7 +42,7 @@ int main() { ## Using _ITERATOR_DEBUG_LEVEL -You can use the preprocessor macro [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) to turn off the iterator debugging feature in a debug build. This program does not assert, but still triggers undefined behavior. +You can use the preprocessor macro [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) to turn off the iterator debugging feature in a debug build. This program doesn't assert, but still triggers undefined behavior. ```cpp // iterator_debugging_1.cpp @@ -74,9 +73,9 @@ int main() { -572662307 ``` -## Unitialized iterators +## Uninitialized iterators -An assert also occurs if you attempt to use an iterator before it is initialized, as shown here: +An assert also occurs if you attempt to use an iterator before it's initialized, as shown here: ```cpp // iterator_debugging_2.cpp @@ -113,7 +112,7 @@ int main() } ``` -Notice that this example uses the lambda expression `[] (int& elem) { elem *= 2; }` instead of a functor. Although this choice has no bearing on the assert failure—a similar functor would cause the same failure—lambdas are a very useful way to accomplish compact function object tasks. For more information about lambda expressions, see [Lambda Expressions](../cpp/lambda-expressions-in-cpp.md). +Notice that this example uses the lambda expression `[] (int& elem) { elem *= 2; }` instead of a functor. Although this choice has no bearing on the assert failure—a similar functor would cause the same failure—lambdas are a way to write a short block of code. For more information about lambda expressions, see [Lambda expressions](../cpp/lambda-expressions-in-cpp.md). ## Iterators going out of scope @@ -135,7 +134,7 @@ int main() { ## Destructors for debug iterators -Debug iterators have non-trivial destructors. If a destructor does not run but the object's memory is freed, access violations and data corruption might occur. Consider this example: +Debug iterators have non-trivial destructors. If a destructor doesn't run but the object's memory is freed, access violations and data corruption might occur. Consider this example: ```cpp // iterator_debugging_5.cpp diff --git a/docs/standard-library/default-searcher-class.md b/docs/standard-library/default-searcher-class.md index c73289aaea..0507263186 100644 --- a/docs/standard-library/default-searcher-class.md +++ b/docs/standard-library/default-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::default_searcher [C++]"] --- # default_searcher Class -A `default_searcher` is a function object type for operations that search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. The `default_searcher` invokes [std::search](algorithm-functions.md#search) to perform the search. +A `default_searcher` is a function object type for operations that search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. The `default_searcher` invokes [std::search](algorithm-functions.md#search) to perform the search. ## Syntax diff --git a/docs/standard-library/deque-class.md b/docs/standard-library/deque-class.md index fca63e048b..8e82314f40 100644 --- a/docs/standard-library/deque-class.md +++ b/docs/standard-library/deque-class.md @@ -1,45 +1,44 @@ --- -description: "Learn more about: deque Class" title: "deque Class" +description: "Learn more about: deque Class" ms.date: "11/04/2016" f1_keywords: ["deque/std::deque", "deque/std::deque::allocator_type", "deque/std::deque::const_iterator", "deque/std::deque::const_pointer", "deque/std::deque::const_reference", "deque/std::deque::const_reverse_iterator", "deque/std::deque::difference_type", "deque/std::deque::iterator", "deque/std::deque::pointer", "deque/std::deque::reference", "deque/std::deque::reverse_iterator", "deque/std::deque::size_type", "deque/std::deque::value_type", "deque/std::deque::assign", "deque/std::deque::at", "deque/std::deque::back", "deque/std::deque::begin", "deque/std::deque::cbegin", "deque/std::deque::cend", "deque/std::deque::clear", "deque/std::deque::crbegin", "deque/std::deque::crend", "deque/std::deque::emplace", "deque/std::deque::emplace_back", "deque/std::deque::emplace_front", "deque/std::deque::empty", "deque/std::deque::end", "deque/std::deque::erase", "deque/std::deque::front", "deque/std::deque::get_allocator", "deque/std::deque::insert", "deque/std::deque::max_size", "deque/std::deque::pop_back", "deque/std::deque::pop_front", "deque/std::deque::push_back", "deque/std::deque::push_front", "deque/std::deque::rbegin", "deque/std::deque::rend", "deque/std::deque::resize", "deque/std::deque::shrink_to_fit", "deque/std::deque::size", "deque/std::deque::swap"] helpviewer_keywords: ["std::deque [C++]", "std::deque [C++], allocator_type", "std::deque [C++], const_iterator", "std::deque [C++], const_pointer", "std::deque [C++], const_reference", "std::deque [C++], const_reverse_iterator", "std::deque [C++], difference_type", "std::deque [C++], iterator", "std::deque [C++], pointer", "std::deque [C++], reference", "std::deque [C++], reverse_iterator", "std::deque [C++], size_type", "std::deque [C++], value_type", "std::deque [C++], assign", "std::deque [C++], at", "std::deque [C++], back", "std::deque [C++], begin", "std::deque [C++], cbegin", "std::deque [C++], cend", "std::deque [C++], clear", "std::deque [C++], crbegin", "std::deque [C++], crend", "std::deque [C++], emplace", "std::deque [C++], emplace_back", "std::deque [C++], emplace_front", "std::deque [C++], empty", "std::deque [C++], end", "std::deque [C++], erase", "std::deque [C++], front", "std::deque [C++], get_allocator", "std::deque [C++], insert", "std::deque [C++], max_size", "std::deque [C++], pop_back", "std::deque [C++], pop_front", "std::deque [C++], push_back", "std::deque [C++], push_front", "std::deque [C++], rbegin", "std::deque [C++], rend", "std::deque [C++], resize", "std::deque [C++], shrink_to_fit", "std::deque [C++], size", "std::deque [C++], swap"] -ms.assetid: 64842ee5-057a-4063-8c16-4267a0332584 --- -# deque Class +# `deque` Class Arranges elements of a given type in a linear arrangement and, like a vector, enables fast random access to any element, and efficient insertion and deletion at the back of the container. However, unlike a vector, the `deque` class also supports efficient insertion and deletion at the front of the container. ## Syntax -```unstlib -template > -class deque +```cpp +template > +class deque; ``` ### Parameters -*Type*\ -The element data type to be stored in the deque. +*`Type`*\ +The element data type to be stored in the `deque`. -*Allocator*\ -The type that represents the stored allocator object that encapsulates details about the deque's allocation and deallocation of memory. This argument is optional, and the default value is **allocator\**. +*`Allocator`*\ +The type that represents the stored allocator object that encapsulates details about the `deque`'s allocation and deallocation of memory. This argument is optional, and the default value is **`allocator`**. ## Remarks -The choice of container type should be based in general on the type of searching and inserting required by the application. [Vectors](../standard-library/vector-class.md) should be the preferred container for managing a sequence when random access to any element is at a premium and insertions or deletions of elements are only required at the end of a sequence. The performance of the list container is superior when efficient insertions and deletions (in constant time) at any location within the sequence is at a premium. Such operations in the middle of the sequence require element copies and assignments proportional to the number of elements in the sequence (linear time). +The choice of container type should be based in general on the type of searching and inserting required by the application. [`Vectors`](../standard-library/vector-class.md) should be the preferred container for managing a sequence when random access to any element is at a premium and insertions or deletions of elements are only required at the end of a sequence. The performance of the list container is superior when efficient insertions and deletions (in constant time) at any location within the sequence is at a premium. Such operations in the middle of the sequence require element copies and assignments proportional to the number of elements in the sequence (linear time). -Deque reallocation occurs when a member function must insert or erase elements of the sequence: +`Deque` reallocation occurs when a member function must insert or erase elements of the sequence: -- If an element is inserted into an empty sequence, or if an element is erased to leave an empty sequence, then iterators earlier returned by [begin](#begin) and [end](#end) become invalid. +- If an element is inserted into an empty sequence, or if an element is erased to leave an empty sequence, then iterators earlier returned by [`begin`](#begin) and [`end`](#end) become invalid. -- If an element is inserted at the first position of the deque, then all iterators, but no references, that designate existing elements become invalid. +- If an element is inserted at the first position of the `deque`, then all iterators, but no references, that designate existing elements become invalid. -- If an element is inserted at the end of the deque, then [end](#end) and all iterators, but no references, that designate existing elements become invalid. +- If an element is inserted at the end of the `deque`, then [`end`](#end) and all iterators, but no references, that designate existing elements become invalid. -- If an element is erased at the front of the deque, only that iterator and references to the erased element become invalid. +- If an element is erased at the front of the `deque`, only that iterator and references to the erased element become invalid. -- If the last element is erased from the end of the deque, only that iterator to the final element and references to the erased element become invalid. +- If the last element is erased from the end of the `deque`, only that iterator to the final element and references to the erased element become invalid. Otherwise, inserting or erasing an element invalidates all iterators and references. @@ -49,69 +48,69 @@ Otherwise, inserting or erasing an element invalidates all iterators and referen |Name|Description| |-|-| -|[deque](#deque)|Constructs a `deque`. Several constructors are provided to set up the contents of the new `deque` in different ways: empty; loaded with a specified number of empty elements; contents moved or copied from another `deque`; contents copied or moved by using an iterator; and one element copied into the `deque` `count` times. Some of the constructors enable using a custom `allocator` to create elements.| +|[`deque`](#deque)|Constructs a `deque`. Several constructors are provided to set up the contents of the new `deque` in different ways: empty; loaded with a specified number of empty elements; contents moved or copied from another `deque`; contents copied or moved by using an iterator; and one element copied into the `deque` `count` times. Some of the constructors enable using a custom `allocator` to create elements.| ### Typedefs |Name|Description| |-|-| -|[allocator_type](#allocator_type)|A type that represents the `allocator` class for the `deque` object.| -|[const_iterator](#const_iterator)|A type that provides a random-access iterator that can access and read elements in the `deque` as **`const`**| -|[const_pointer](#const_pointer)|A type that provides a pointer to an element in a `deque` as a `const.`| -|[const_reference](#const_reference)|A type that provides a reference to an element in a `deque` for reading and other operations as a `const.`| -|[const_reverse_iterator](#const_reverse_iterator)|A type that provides a random-access iterator that can access and read elements in the `deque` as **`const`**. The deque is viewed in reverse. For more information, see [reverse_iterator Class](../standard-library/reverse-iterator-class.md)| -|[difference_type](#difference_type)|A type that provides the difference between two random-access iterators that refer to elements in the same `deque`.| -|[iterator](#iterator)|A type that provides a random-access iterator that can read or modify any element in a `deque`.| -|[pointer](#pointer)|A type that provides a pointer to an element in a `deque`.| -|[reference](#reference)|A type that provides a reference to an element stored in a `deque`.| -|[reverse_iterator](#reverse_iterator)|A type that provides a random-access iterator that can read or modify an element in a `deque`. The deque is viewed in reverse order.| -|[size_type](#size_type)|A type that counts the number of elements in a `deque`.| -|[value_type](#value_type)|A type that represents the data type stored in a `deque`.| +|[`allocator_type`](#allocator_type)|A type that represents the `allocator` class for the `deque` object.| +|[`const_iterator`](#const_iterator)|A type that provides a random-access iterator that can access and read elements in the `deque` as **`const`**| +|[`const_pointer`](#const_pointer)|A type that provides a pointer to an element in a `deque` as **`const`**.| +|[`const_reference`](#const_reference)|A type that provides a reference to an element in a `deque` for reading and other operations as **`const`**.| +|[`const_reverse_iterator`](#const_reverse_iterator)|A type that provides a random-access iterator that can access and read elements in the `deque` as **`const`**. The `deque` is viewed in reverse. For more information, see [`reverse_iterator` Class](../standard-library/reverse-iterator-class.md)| +|[`difference_type`](#difference_type)|A type that provides the difference between two random-access iterators that refer to elements in the same `deque`.| +|[`iterator`](#iterator)|A type that provides a random-access iterator that can read or modify any element in a `deque`.| +|[`pointer`](#pointer)|A type that provides a pointer to an element in a `deque`.| +|[`reference`](#reference)|A type that provides a reference to an element stored in a `deque`.| +|[`reverse_iterator`](#reverse_iterator)|A type that provides a random-access iterator that can read or modify an element in a `deque`. The `deque` is viewed in reverse order.| +|[`size_type`](#size_type)|A type that counts the number of elements in a `deque`.| +|[`value_type`](#value_type)|A type that represents the data type stored in a `deque`.| ### Functions |Name|Description| |-|-| -|[assign](#assign)|Erases elements from a `deque` and copies a new sequence of elements to the target `deque`.| -|[at](#at)|Returns a reference to the element at a specified location in the `deque`.| -|[back](#back)|Returns a reference to the last element of the `deque`.| -|[begin](#begin)|Returns a random-access iterator addressing the first element in the `deque`.| -|[cbegin](#cbegin)|Returns a const iterator to the first element in the `deque`.| -|[cend](#cend)|Returns a random-access **`const`** iterator that points just beyond the end of the `deque`.| -|[clear](#clear)|Erases all the elements of a `deque`.| -|[crbegin](#crbegin)|Returns a random-access const iterator to the first element in a `deque` viewed in reverse order.| -|[crend](#crend)|Returns a random-access const iterator to the first element in a `deque` viewed in reverse order.| -|[emplace](#emplace)|Inserts an element constructed in place into the `deque` at a specified position.| -|[emplace_back](#emplace_back)|Adds an element constructed in place to the end of the `deque`.| -|[emplace_front](#emplace_front)|Adds an element constructed in place to the start of the `deque`.| -|[empty](#empty)|Returns **`true`** if the `deque` contains zero elements, and **`false`** if it contains one or more elements.| -|[end](#end)|Returns a random-access iterator that points just beyond the end of the `deque`.| -|[erase](#erase)|Removes an element or a range of elements in a `deque` from specified positions.| -|[front](#front)|Returns a reference to the first element in a `deque`.| -|[get_allocator](#get_allocator)|Returns a copy of the `allocator` object that is used to construct the `deque`.| -|[insert](#insert)|Inserts an element, several elements, or a range of elements into the `deque` at a specified position.| -|[max_size](#max_size)|Returns the maximum possible length of the `deque`.| -|[pop_back](#pop_back)|Erases the element at the end of the `deque`.| -|[pop_front](#pop_front)|Erases the element at the start of the `deque`.| -|[push_back](#push_back)|Adds an element to the end of the `deque`.| -|[push_front](#push_front)|Adds an element to the start of the `deque`.| -|[rbegin](#rbegin)|Returns a random-access iterator to the first element in a reversed `deque`.| -|[rend](#rend)|Returns a random-access iterator that points just beyond the last element in a reversed `deque`.| -|[resize](#resize)|Specifies a new size for a `deque`.| -|[shrink_to_fit](#shrink_to_fit)|Discards excess capacity.| -|[size](#size)|Returns the number of elements in the `deque`.| -|[swap](#swap)|Exchanges the elements of two `deque`s.| +|[`assign`](#assign)|Erases elements from a `deque` and copies a new sequence of elements to the target `deque`.| +|[`at`](#at)|Returns a reference to the element at a specified location in the `deque`.| +|[`back`](#back)|Returns a reference to the last element of the `deque`.| +|[`begin`](#begin)|Returns a random-access iterator addressing the first element in the `deque`.| +|[`cbegin`](#cbegin)|Returns a `const` iterator to the first element in the `deque`.| +|[`cend`](#cend)|Returns a random-access **`const`** iterator that points just beyond the end of the `deque`.| +|[`clear`](#clear)|Erases all the elements of a `deque`.| +|[`crbegin`](#crbegin)|Returns a random-access `const` iterator to the first element in a `deque` viewed in reverse order.| +|[`crend`](#crend)|Returns a random-access `const` iterator to the first element in a `deque` viewed in reverse order.| +|[`emplace`](#emplace)|Inserts an element constructed in place into the `deque` at a specified position.| +|[`emplace_back`](#emplace_back)|Adds an element constructed in place to the end of the `deque`.| +|[`emplace_front`](#emplace_front)|Adds an element constructed in place to the start of the `deque`.| +|[`empty`](#empty)|Returns **`true`** if the `deque` contains zero elements, and **`false`** if it contains one or more elements.| +|[`end`](#end)|Returns a random-access iterator that points just beyond the end of the `deque`.| +|[`erase`](#erase)|Removes an element or a range of elements in a `deque` from specified positions.| +|[`front`](#front)|Returns a reference to the first element in a `deque`.| +|[`get_allocator`](#get_allocator)|Returns a copy of the `allocator` object that is used to construct the `deque`.| +|[`insert`](#insert)|Inserts an element, several elements, or a range of elements into the `deque` at a specified position.| +|[`max_size`](#max_size)|Returns the maximum possible length of the `deque`.| +|[`pop_back`](#pop_back)|Erases the element at the end of the `deque`.| +|[`pop_front`](#pop_front)|Erases the element at the start of the `deque`.| +|[`push_back`](#push_back)|Adds an element to the end of the `deque`.| +|[`push_front`](#push_front)|Adds an element to the start of the `deque`.| +|[`rbegin`](#rbegin)|Returns a random-access iterator to the first element in a reversed `deque`.| +|[`rend`](#rend)|Returns a random-access iterator that points just beyond the last element in a reversed `deque`.| +|[`resize`](#resize)|Specifies a new size for a `deque`.| +|[`shrink_to_fit`](#shrink_to_fit)|Discards excess capacity.| +|[`size`](#size)|Returns the number of elements in the `deque`.| +|[`swap`](#swap)|Exchanges the elements of two `deque`s.| ### Operators |Name|Description| |-|-| |[`operator[]`](#op_at)|Returns a reference to the `deque` element at a specified position.| -|[operator=](#op_eq)|Replaces the elements of the `deque` with a copy of another `deque`.| +|[`operator=`](#op_eq)|Replaces the elements of the `deque` with a copy of another `deque`.| -## allocator_type +## `allocator_type` -A type that represents the allocator class for the deque object. +A type that represents the allocator class for the `deque` object. ```cpp typedef Allocator allocator_type; @@ -123,11 +122,11 @@ typedef Allocator allocator_type; ### Example -See the example for [get_allocator](#get_allocator). +See the example for [`get_allocator`](#get_allocator). -## assign +## `assign` -Erases elements from a deque and copies a new set of elements to the target deque. +Erases elements from a `deque` and copies a new set of elements to the target `deque`. ```cpp template @@ -144,24 +143,24 @@ void assign(initializer_list IList); ### Parameters -*First*\ -Position of the first element in the range of elements to be copied from the argument deque. +*`First`*\ +Position of the first element in the range of elements to be copied from the argument `deque`. -*Last*\ -Position of the first element beyond the range of elements to be copied from the argument deque. +*`Last`*\ +Position of the first element beyond the range of elements to be copied from the argument `deque`. -*Count*\ -The number of copies of an element being inserted into the deque. +*`Count`*\ +The number of copies of an element being inserted into the `deque`. -*Val*\ -The value of the element being inserted into the deque. +*`Val`*\ +The value of the element being inserted into the `deque`. -*IList*\ -The initializer_list being inserted into the deque. +*`IList`*\ +The `initializer_list` being inserted into the `deque`. ### Remarks -After any existing elements in the target deque are erased, `assign` either inserts a specified range of elements from the original deque or from some other deque into the target deque, or inserts copies of a new element of a specified value into the target deque. +After any existing elements in the target `deque` are erased, `assign` either inserts a specified range of elements from the original `deque` or from some other `deque` into the target `deque`, or inserts copies of a new element of a specified value into the target `deque`. ### Example @@ -217,9 +216,9 @@ int main() d1 = 5678c1 =102030c1 =5060c1 =4444444 ``` -## at +## `at` -Returns a reference to the element at a specified location in the deque. +Returns a reference to the element at a specified location in the `deque`. ```cpp reference at(size_type pos); @@ -229,16 +228,16 @@ const_reference at(size_type pos) const; ### Parameters -*pos*\ -The subscript (or position number) of the element to reference in the deque. +*`pos`*\ +The subscript (or position number) of the element to reference in the `deque`. ### Return Value -If *pos* is greater than the size of the deque, `at` throws an exception. +If *`pos`* is greater than the size of the `deque`, `at` throws an exception. ### Remarks -If the return value of `at` is assigned to a `const_reference`, the deque object cannot be modified. If the return value of `at` is assigned to a `reference`, the deque object can be modified. +If the return value of `at` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `at` is assigned to a `reference`, the `deque` object can be modified. ### Example @@ -268,9 +267,9 @@ The first element is 10 The second element is 20 ``` -## back +## `back` -Returns a reference to the last element of the deque. +Returns a reference to the last element of the `deque`. ```cpp reference back(); @@ -279,13 +278,13 @@ const_reference back() const; ### Return Value -The last element of the deque. If the deque is empty, the return value is undefined. +The last element of the `deque`. If the `deque` is empty, the return value is undefined. ### Remarks -If the return value of `back` is assigned to a `const_reference`, the deque object cannot be modified. If the return value of `back` is assigned to a `reference`, the deque object can be modified. +If the return value of `back` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `back` is assigned to a `reference`, the `deque` object can be modified. -When compiled by using [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty deque. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. +When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. ### Example @@ -317,9 +316,9 @@ The last integer of c1 is 11 The next-to-last integer of c1 is 10 ``` -## begin +## `begin` -Returns an iterator addressing the first element in the deque. +Returns an iterator addressing the first element in the `deque`. ```cpp const_iterator begin() const; @@ -328,11 +327,11 @@ iterator begin(); ### Return Value -A random-access iterator addressing the first element in the deque or to the location succeeding an empty deque. +A random-access iterator addressing the first element in the `deque` or to the location succeeding an empty `deque`. ### Remarks -If the return value of `begin` is assigned to a `const_iterator`, the deque object cannot be modified. If the return value of `begin` is assigned to an `iterator`, the deque object can be modified. +If the return value of `begin` is assigned to a `const_iterator`, the `deque` object can't be modified. If the return value of `begin` is assigned to an `iterator`, the `deque` object can be modified. ### Example @@ -369,7 +368,7 @@ The first element of c1 is 1 The first element of c1 is now 20 ``` -## cbegin +## `cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -383,9 +382,9 @@ A **`const`** random-access iterator that points at the first element of the ran ### Remarks -With the return value of `cbegin`, the elements in the range cannot be modified. +With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -395,7 +394,7 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## cend +## `cend` Returns a **`const`** iterator that addresses the location just beyond the last element in a range. @@ -411,7 +410,7 @@ A random-access iterator that points just beyond the end of the range. `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -421,11 +420,11 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -The value returned by `cend` should not be dereferenced. +The value returned by `cend` shouldn't be dereferenced. -## clear +## `clear` -Erases all the elements of a deque. +Erases all the elements of a `deque`. ```cpp void clear(); @@ -459,9 +458,9 @@ The size of the deque is initially 3 The size of the deque after clearing is 0 ``` -## const_iterator +## `const_iterator` -A type that provides a random-access iterator that can access and read a **`const`** element in the deque. +A type that provides a random-access iterator that can access and read a **`const`** element in the `deque`. ```cpp typedef implementation-defined const_iterator; @@ -469,15 +468,15 @@ typedef implementation-defined const_iterator; ### Remarks -A type `const_iterator` cannot be used to modify the value of an element. +A type `const_iterator` can't be used to modify the value of an element. ### Example -See the example for [back](#back). +See the example for [`back`](#back). -## const_pointer +## `const_pointer` -Provides a pointer to a **`const`** element in a deque. +Provides a pointer to a **`const`** element in a `deque`. ```cpp typedef typename Allocator::const_pointer const_pointer; @@ -485,11 +484,11 @@ typedef typename Allocator::const_pointer const_pointer; ### Remarks -A type `const_pointer` cannot be used to modify the value of an element. An [iterator](#iterator) is more commonly used to access a deque element. +A type `const_pointer` can't be used to modify the value of an element. An [`iterator`](#iterator) is more commonly used to access a `deque` element. -## const_reference +## `const_reference` -A type that provides a reference to a **`const`** element stored in a deque for reading and performing **`const`** operations. +A type that provides a reference to a **`const`** element stored in a `deque` for reading and performing **`const`** operations. ```cpp typedef typename Allocator::const_reference const_reference; @@ -497,7 +496,7 @@ typedef typename Allocator::const_reference const_reference; ### Remarks -A type `const_reference` cannot be used to modify the value of an element. +A type `const_reference` can't be used to modify the value of an element. ### Example @@ -531,9 +530,9 @@ The first element is 10 The second element is 20 ``` -## const_reverse_iterator +## `const_reverse_iterator` -A type that provides a random-access iterator that can read any **`const`** element in the deque. +A type that provides a random-access iterator that can read any **`const`** element in the `deque`. ```cpp typedef std::reverse_iterator const_reverse_iterator; @@ -541,15 +540,15 @@ typedef std::reverse_iterator const_reverse_iterator; ### Remarks -A type `const_reverse_iterator` cannot modify the value of an element and is used to iterate through the deque in reverse. +A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the `deque` in reverse. ### Example -See the example for [rbegin](#rbegin) for an example of how to declare and use an iterator. +See the example for [`rbegin`](#rbegin) for an example of how to declare and use an iterator. -## crbegin +## `crbegin` -Returns a const iterator to the first element in a reversed deque. +Returns a `const` iterator to the first element in a reversed `deque`. ```cpp const_reverse_iterator crbegin() const; @@ -557,11 +556,11 @@ const_reverse_iterator crbegin() const; ### Return Value -A const reverse random-access iterator addressing the first element in a reversed [deque](../standard-library/deque-class.md) or addressing what had been the last element in the unreversed `deque`. +A `const` reverse random-access iterator addressing the first element in a reversed [`deque`](../standard-library/deque-class.md) or addressing what had been the last element in the unreversed `deque`. ### Remarks -With the return value of `crbegin`, the `deque` object cannot be modified. +With the return value of `crbegin`, the `deque` object can't be modified. ### Example @@ -596,9 +595,9 @@ The first element of deque is 1. The first element of the reversed deque is 2. ``` -## crend +## `crend` -Returns a const iterator that addresses the location succeeding the last element in a reversed deque. +Returns a `const` iterator that addresses the location succeeding the last element in a reversed `deque`. ```cpp const_reverse_iterator crend() const; @@ -606,17 +605,17 @@ const_reverse_iterator crend() const; ### Return Value -A const reverse random-access iterator that addresses the location succeeding the last element in a reversed [deque](../standard-library/deque-class.md) (the location that had preceded the first element in the unreversed deque). +A `const` reverse random-access iterator that addresses the location succeeding the last element in a reversed [`deque`](../standard-library/deque-class.md) (the location that had preceded the first element in the unreversed `deque`). ### Remarks -`crend` is used with a reversed `deque` just as [array::cend](../standard-library/array-class-stl.md#cend) is used with a `deque`. +`crend` is used with a reversed `deque` just as [`array::cend`](../standard-library/array-class-stl.md#cend) is used with a `deque`. -With the return value of `crend` (suitably decremented), the `deque` object cannot be modified. +With the return value of `crend` (suitably decremented), the `deque` object can't be modified. -`crend` can be used to test to whether a reverse iterator has reached the end of its deque. +`crend` can be used to test to whether a reverse iterator has reached the end of its `deque`. -The value returned by `crend` should not be dereferenced. +The value returned by `crend` shouldn't be dereferenced. ### Example @@ -645,9 +644,9 @@ int main( ) 1 ``` -## deque +## `deque` -Constructs a deque of a specific size, or with elements of a specific value, or with a specific allocator, or as a copy of all or part of some other deque. +Constructs a `deque` of a specific size, or with elements of a specific value, or with a specific allocator, or as a copy of all or part of some other `deque`. ```cpp deque(); @@ -677,51 +676,51 @@ deque(initializer_list IList, const Allocator& Al); ### Parameters -*Al*\ +*`Al`*\ The allocator class to use with this object. -*Count*\ -The number of elements in the constructed deque. +*`Count`*\ +The number of elements in the constructed `deque`. -*Val*\ -The value of the elements in the constructed deque. +*`Val`*\ +The value of the elements in the constructed `deque`. -*Right*\ -The deque of which the constructed deque is to be a copy. +*`Right`*\ +The `deque` of which the constructed `deque` is to be a copy. -*First*\ +*`First`*\ Position of the first element in the range of elements to be copied. -*Last*\ +*`Last`*\ Position of the first element beyond the range of elements to be copied. -*IList*\ -The initializer_list to be copied. +*`IList`*\ +The `initializer_list` to be copied. ### Remarks -All constructors store an allocator object (*Al*) and initialize the deque. +All constructors store an allocator object (*`Al`*) and initialize the `deque`. -The first two constructors specify an empty initial deque; the second one also specifies the allocator type (`_Al`) to be used. +The first two constructors specify an empty initial `deque`; the second one also specifies the allocator type (`_Al`) to be used. The third constructor specifies a repetition of a specified number (`count`) of elements of the default value for class `Type`. -The fourth and fifth constructors specify a repetition of (*Count*) elements of value `val`. +The fourth and fifth constructors specify a repetition of (*`Count`*) elements of value `val`. -The sixth constructor specifies a copy of the deque *Right*. +The sixth constructor specifies a copy of the `deque` *`Right`*. -The seventh and eighth constructors copy the range `[First, Last)` of a deque. +The seventh and eighth constructors copy the range `[First, Last)` of a `deque`. -The seventh constructor moves the deque *Right*. +The seventh constructor moves the `deque` *`Right`*. -The eighth constructor copies the contents of an initializer_list. +The eighth constructor copies the contents of an `initializer_list`. None of the constructors perform any interim reallocations. ### Example ```cpp -/ compile with: /EHsc +// compile with: /EHsc #include #include #include @@ -922,9 +921,9 @@ int main( ) } ``` -## difference_type +## `difference_type` -A type that provides the difference between two iterators that refer to elements within the same deque. +A type that provides the difference between two iterators that refer to elements within the same `deque`. ```cpp typedef typename Allocator::difference_type difference_type; @@ -977,9 +976,9 @@ The number '20' is in c1 collection 2 times. The number '30' is in c1 collection 3 times. ``` -## emplace +## `emplace` -Inserts an element constructed in place into the deque at a specified position. +Inserts an element constructed in place into the `deque` at a specified position. ```cpp iterator emplace( @@ -989,15 +988,15 @@ iterator emplace( ### Parameters -*_Where*\ -The position in the [deque](../standard-library/deque-class.md) where the first element is inserted. +*`_Where`*\ +The position in the [`deque`](../standard-library/deque-class.md) where the first element is inserted. -*val*\ +*`val`*\ The value of the element being inserted into the `deque`. ### Return Value -The function returns an iterator that points to the position where the new element was inserted into the deque. +The function returns an iterator that points to the position where the new element was inserted into the `deque`. ### Remarks @@ -1045,9 +1044,9 @@ v1 = 10 20 30 vv1[0] = 10 20 30 ``` -## emplace_back +## `emplace_back` -Adds an element constructed in place to the end of the deque. +Adds an element constructed in place to the end of the `deque`. ```cpp void emplace_back(Type&& val); @@ -1055,8 +1054,8 @@ void emplace_back(Type&& val); ### Parameters -*val*\ -The element added to the end of the [deque](../standard-library/deque-class.md). +*`val`*\ +The element added to the end of the [`deque`](../standard-library/deque-class.md). ### Example @@ -1094,9 +1093,9 @@ New last element: 2 Moved last element: 2 ``` -## emplace_front +## `emplace_front` -Adds an element constructed in place to the end of the deque. +Adds an element constructed in place to the end of the `deque`. ```cpp void emplace_front(Type&& val); @@ -1104,8 +1103,8 @@ void emplace_front(Type&& val); ### Parameters -*val*\ -The element added to the beginning of the [deque](../standard-library/deque-class.md). +*`val`*\ +The element added to the beginning of the [`deque`](../standard-library/deque-class.md). ### Example @@ -1143,9 +1142,9 @@ New last element: 2 Moved last element: 2 ``` -## empty +## `empty` -Tests if a deque is empty. +Tests if a `deque` is empty. ```cpp bool empty() const; @@ -1153,7 +1152,7 @@ bool empty() const; ### Return Value -**`true`** if the deque is empty; **`false`** if the deque is not empty. +**`true`** if the `deque` is empty; **`false`** if the `deque` isn't empty. ### Example @@ -1180,9 +1179,9 @@ int main( ) The deque is not empty. ``` -## end +## `end` -Returns an iterator that addresses the location succeeding the last element in a deque. +Returns an iterator that addresses the location succeeding the last element in a `deque`. ```cpp const_iterator end() const; @@ -1192,11 +1191,11 @@ iterator end(); ### Return Value -A random-access iterator that addresses the location succeeding the last element in a deque. If the deque is empty, then deque::end == deque::begin. +A random-access iterator that addresses the location succeeding the last element in a `deque`. If the `deque` is empty, then `deque::end == deque::begin`. ### Remarks -`end` is used to test whether an iterator has reached the end of its deque. +`end` is used to test whether an iterator has reached the end of its `deque`. ### Example @@ -1240,9 +1239,9 @@ The new next-to-last integer of c1 is 400 The deque is now: 10 400 30 ``` -## erase +## `erase` -Removes an element or a range of elements in a deque from specified positions. +Removes an element or a range of elements in a `deque` from specified positions. ```cpp iterator erase(iterator _Where); @@ -1252,18 +1251,18 @@ iterator erase(iterator first, iterator last); ### Parameters -*_Where*\ -Position of the element to be removed from the deque. +*`_Where`*\ +Position of the element to be removed from the `deque`. -*first*\ -Position of the first element removed from the deque. +*`first`*\ +Position of the first element removed from the `deque`. -*last*\ -Position just beyond the last element removed from the deque. +*`last`*\ +Position just beyond the last element removed from the `deque`. ### Return Value -A random-access iterator that designates the first element remaining beyond any elements removed, or a pointer to the end of the deque if no such element exists. +A random-access iterator that designates the first element remaining beyond any elements removed, or a pointer to the end of the `deque` if no such element exists. ### Remarks @@ -1313,9 +1312,9 @@ After erasing the first element, the deque becomes: 20 30 40 50 After erasing all elements but the first, deque becomes: 20 ``` -## front +## `front` -Returns a reference to the first element in a deque. +Returns a reference to the first element in a `deque`. ```cpp reference front(); @@ -1325,13 +1324,13 @@ const_reference front() const; ### Return Value -If the deque is empty, the return is undefined. +If the `deque` is empty, the return is undefined. ### Remarks -If the return value of `front` is assigned to a `const_reference`, the deque object cannot be modified. If the return value of `front` is assigned to a `reference`, the deque object can be modified. +If the return value of `front` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `front` is assigned to a `reference`, the `deque` object can be modified. -When compiled by using [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty deque. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. +When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. ### Example @@ -1363,9 +1362,9 @@ The first integer of c1 is 10 The second integer of c1 is 11 ``` -## get_allocator +## `get_allocator` -Returns a copy of the allocator object used to construct the deque. +Returns a copy of the allocator object used to construct the `deque`. ```cpp Allocator get_allocator() const; @@ -1373,11 +1372,11 @@ Allocator get_allocator() const; ### Return Value -The allocator used by the deque. +The allocator used by the `deque`. ### Remarks -Allocators for the deque class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. +Allocators for the `deque` class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. ### Example @@ -1402,9 +1401,9 @@ int main( ) } ``` -## insert +## `insert` -Inserts an element or a number of elements or a range of elements into the deque at a specified position. +Inserts an element or a number of elements or a range of elements into the `deque` at a specified position. ```cpp iterator insert( @@ -1433,35 +1432,35 @@ IList); ### Parameters -*Where*\ -The position in the target deque where the first element is inserted. +*`Where`*\ +The position in the target `deque` where the first element is inserted. -*Val*\ -The value of the element being inserted into the deque. +*`Val`*\ +The value of the element being inserted into the `deque`. -*Count*\ -The number of elements being inserted into the deque. +*`Count`*\ +The number of elements being inserted into the `deque`. -*First*\ -The position of the first element in the range of elements in the argument deque to be copied. +*`First`*\ +The position of the first element in the range of elements in the argument `deque` to be copied. -*Last*\ -The position of the first element beyond the range of elements in the argument deque to be copied. +*`Last`*\ +The position of the first element beyond the range of elements in the argument `deque` to be copied. -*IList*\ -The initializer_list of elements to insert. +*`IList`*\ +The `initializer_list` of elements to insert. ### Return Value -The first two insert functions return an iterator that points to the position where the new element was inserted into the deque. +The first two insert functions return an iterator that points to the position where the new element was inserted into the `deque`. ### Remarks Any insertion operation can be expensive. -## iterator +## `iterator` -A type that provides a random-access iterator that can read or modify any element in a deque. +A type that provides a random-access iterator that can read or modify any element in a `deque`. ```cpp typedef implementation-defined iterator; @@ -1473,11 +1472,11 @@ A type `iterator` can be used to modify the value of an element. ### Example -See the example for [begin](#begin). +See the example for [`begin`](#begin). -## max_size +## `max_size` -Returns the maximum length of the deque. +Returns the maximum length of the `deque`. ```cpp size_type max_size() const; @@ -1485,7 +1484,7 @@ size_type max_size() const; ### Return Value -The maximum possible length of the deque. +The maximum possible length of the `deque`. ### Example @@ -1506,9 +1505,9 @@ int main( ) } ``` -## operator[] +## `operator[]` -Returns a reference to the deque element at a specified position. +Returns a reference to the `deque` element at a specified position. ```cpp reference operator[](size_type pos); @@ -1518,18 +1517,18 @@ const_reference operator[](size_type pos) const; ### Parameters -*pos*\ -The position of the deque element to be referenced. +*`pos`*\ +The position of the `deque` element to be referenced. ### Return Value -A reference to the element whose position is specified in the argument. If the position specified is greater than the size of the deque, the result is undefined. +A reference to the element whose position is specified in the argument. If the position specified is greater than the size of the `deque`, the result is undefined. ### Remarks -If the return value of `operator[]` is assigned to a `const_reference`, the deque object cannot be modified. If the return value of `operator[]` is assigned to a `reference`, the deque object can be modified. +If the return value of `operator[]` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `operator[]` is assigned to a `reference`, the `deque` object can be modified. -When compiled by using [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the deque. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. +When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. ### Example @@ -1557,9 +1556,9 @@ The first integer of c1 is 10 The second integer of c1 is 20 ``` -## operator= +## `operator=` -Replaces the elements of this deque using the elements from another deque. +Replaces the elements of this `deque` using the elements from another `deque`. ```cpp deque& operator=(const deque& right); @@ -1569,14 +1568,14 @@ deque& operator=(deque&& right); ### Parameters -*right*\ -The deque that provides the new content. +*`right`*\ +The `deque` that provides the new content. ### Remarks -The first override copies elements to this deque from *right*, the source of the assignment. The second override moves elements to this deque from *right*. +The first override copies elements to this `deque` from *`right`*, the source of the assignment. The second override moves elements to this `deque` from *`right`*. -Elements that are contained in this deque before the operator executes are removed. +Elements that are contained in this `deque` before the operator executes are removed. ### Example @@ -1631,21 +1630,21 @@ int main( ) } ``` -## pointer +## `pointer` -Provides a pointer to an element in a [deque](../standard-library/deque-class.md). +Provides a pointer to an element in a [`deque`](../standard-library/deque-class.md). -```unstlib +```cpp typedef typename Allocator::pointer pointer; ``` ### Remarks -A type `pointer` can be used to modify the value of an element. An [iterator](#iterator) is more commonly used to access a deque element. +A type `pointer` can be used to modify the value of an element. An [`iterator`](#iterator) is more commonly used to access a `deque` element. -## pop_back +## `pop_back` -Deletes the element at the end of the deque. +Deletes the element at the end of the `deque`. ```cpp void pop_back(); @@ -1685,9 +1684,9 @@ The last element is: 2 After deleting the element at the end of the deque, the last element is: 1 ``` -## pop_front +## `pop_front` -Deletes the element at the beginning of the deque. +Deletes the element at the beginning of the `deque`. ```cpp void pop_front(); @@ -1724,12 +1723,12 @@ int main( ) ```Output The first element is: 1 The second element is: 2 -After deleting the element at the beginning of the deque, the first element is: 2 +After deleting the element at the beginning of the `deque`, the first element is: 2 ``` -## push_back +## `push_back` -Adds an element to the end of the deque. +Adds an element to the end of the `deque`. ```cpp void push_back(const Type& val); @@ -1739,16 +1738,16 @@ void push_back(Type&& val); ### Parameters -*val*\ -The element added to the end of the deque. +*`val`*\ +The element added to the end of the `deque`. ### Remarks -If an exception is thrown, the deque is left unaltered and the exception is rethrown. +If an exception is thrown, the `deque` is left unaltered and the exception is rethrown. -## push_front +## `push_front` -Adds an element to the beginning of the deque. +Adds an element to the beginning of the `deque`. ```cpp void push_front(const Type& val); @@ -1757,12 +1756,12 @@ void push_front(Type&& val); ### Parameters -*val*\ -The element added to the beginning of the deque. +*`val`*\ +The element added to the beginning of the `deque`. ### Remarks -If an exception is thrown, the deque is left unaltered and the exception is rethrown. +If an exception is thrown, the `deque` is left unaltered and the exception is rethrown. ### Example @@ -1801,9 +1800,9 @@ New first element: 2 Moved first element: a ``` -## rbegin +## `rbegin` -Returns an iterator to the first element in a reversed deque. +Returns an iterator to the first element in a reversed `deque`. ```cpp const_reverse_iterator rbegin() const; @@ -1813,15 +1812,15 @@ reverse_iterator rbegin(); ### Return Value -A reverse random-access iterator addressing the first element in a reversed deque or addressing what had been the last element in the unreversed deque. +A reverse random-access iterator addressing the first element in a reversed `deque` or addressing what had been the last element in the unreversed `deque`. ### Remarks -`rbegin` is used with a reversed deque just as [begin](#begin) is used with a deque. +`rbegin` is used with a reversed `deque` just as [`begin`](#begin) is used with a `deque`. -If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the deque object cannot be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, the deque object can be modified. +If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the `deque` object can't be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, the `deque` object can be modified. -`rbegin` can be used to iterate through a deque backwards. +`rbegin` can be used to iterate through a `deque` backwards. ### Example @@ -1877,9 +1876,9 @@ The reversed deque is: 30 20 10 Last element in deque is now 40. ``` -## reference +## `reference` -A type that provides a reference to an element stored in a deque. +A type that provides a reference to an element stored in a `deque`. ```cpp typedef typename Allocator::reference reference; @@ -1913,9 +1912,9 @@ The first element is 10 The second element is 20 ``` -## rend +## `rend` -Returns an iterator that addresses the location succeeding the last element in a reversed deque. +Returns an iterator that addresses the location succeeding the last element in a reversed `deque`. ```cpp const_reverse_iterator rend() const; @@ -1925,17 +1924,17 @@ reverse_iterator rend(); ### Return Value -A reverse random-access iterator that addresses the location succeeding the last element in a reversed deque (the location that had preceded the first element in the unreversed deque). +A reverse random-access iterator that addresses the location succeeding the last element in a reversed `deque` (the location that had preceded the first element in the unreversed `deque`). ### Remarks -`rend` is used with a reversed deque just as [end](#end) is used with a deque. +`rend` is used with a reversed `deque` just as [`end`](#end) is used with a `deque`. -If the return value of `rend` is assigned to a `const_reverse_iterator`, the deque object cannot be modified. If the return value of `rend` is assigned to a `reverse_iterator`, the deque object can be modified. +If the return value of `rend` is assigned to a `const_reverse_iterator`, the `deque` object can't be modified. If the return value of `rend` is assigned to a `reverse_iterator`, the `deque` object can be modified. -`rend` can be used to test whether a reverse iterator has reached the end of its deque. +`rend` can be used to test whether a reverse iterator has reached the end of its `deque`. -The value returned by `rend` should not be dereferenced. +The value returned by `rend` shouldn't be dereferenced. ### Example @@ -1998,9 +1997,9 @@ The reversed deque is: 30 20 10 The modified reversed deque is: 30 20 40 ``` -## resize +## `resize` -Specifies a new size for a deque. +Specifies a new size for a `deque`. ```cpp void resize(size_type _Newsize); @@ -2010,21 +2009,21 @@ void resize(size_type _Newsize, Type val); ### Parameters -*_Newsize*\ -The new size of the deque. +*`_Newsize`*\ +The new size of the `deque`. -*val*\ -The value of the new elements to be added to the deque if the new size is larger that the original size. If the value is omitted, the new elements are assigned the default value for the class. +*`val`*\ +The value of the new elements to be added to the `deque` if the new size is larger that the original size. If the value is omitted, the new elements are assigned the default value for the class. ### Remarks -If the deque's size is less than the requested size, *_Newsize*, elements are added to the deque until it reaches the requested size. +If the `deque`'s `size` is less than *`_Newsize`*, elements are added to the `deque` until it reaches the size *`_Newsize`*. -If the deque's size is larger than the requested size, the elements closest to the end of the deque are deleted until the deque reaches the size *_Newsize*. +If the `deque`'s `size` is larger than *`_Newsize`*, the elements closest to the end of the `deque` are deleted until the `deque` reaches the size *`_Newsize`*. -If the present size of the deque is the same as the requested size, no action is taken. +If the present size of the `deque` is the same as *`_Newsize`*, no action is taken. -[size](#size) reflects the current size of the deque. +[`size`](#size) reflects the current size of the `deque`. ### Example @@ -2066,9 +2065,9 @@ The reduced size of c1 is: 2 The value of the last element is now 20 ``` -## reverse_iterator +## `reverse_iterator` -A type that provides a random-access iterator that can read or modify an element in a reversed deque. +A type that provides a random-access iterator that can read or modify an element in a reversed `deque`. ```cpp typedef std::reverse_iterator reverse_iterator; @@ -2076,13 +2075,13 @@ typedef std::reverse_iterator reverse_iterator; ### Remarks -A type `reverse_iterator` is use to iterate through the deque. +A type `reverse_iterator` is used to iterate through the `deque`. ### Example See the example for rbegin. -## shrink_to_fit +## `shrink_to_fit` Discards excess capacity. @@ -2092,7 +2091,7 @@ void shrink_to_fit(); ### Remarks -There is no portable way to determine if `shrink_to_fit` reduces the storage used by a [deque](../standard-library/deque-class.md). +There's no portable way to determine if `shrink_to_fit` reduces the storage used by a [`deque`](../standard-library/deque-class.md). ### Example @@ -2123,9 +2122,9 @@ Current size of v1 = 1 Current size of v1 = 1 ``` -## size +## `size` -Returns the number of elements in the deque. +Returns the number of elements in the `deque`. ```cpp size_type size() const; @@ -2133,7 +2132,7 @@ size_type size() const; ### Return Value -The current length of the deque. +The current length of the `deque`. ### Example @@ -2164,9 +2163,9 @@ The deque length is 1. The deque length is now 2. ``` -## size_type +## `size_type` -A type that counts the number of elements in a deque. +A type that counts the number of elements in a `deque`. ```cpp typedef typename Allocator::size_type size_type; @@ -2174,9 +2173,9 @@ typedef typename Allocator::size_type size_type; ### Example -See the example for [size](#size). +See the example for [`size`](#size). -## swap +## `swap` Exchanges the elements of two deques. @@ -2189,11 +2188,11 @@ void swap(deque& left, deque& right); ### Parameters -*right*\ -The deque providing the elements to be swapped, or the deque whose elements are to be exchanged with those of the deque `left`. +*`right`*\ +The `deque` providing the elements to be swapped, or the `deque` whose elements are to be exchanged with those of the `deque` *`left`*. -*left*\ -A deque whose elements are to be exchanged with those of the deque *right*. +*`left`*\ +A `deque` whose elements are to be exchanged with those of the `deque` *`right`*. ### Example @@ -2250,9 +2249,9 @@ After swapping with c3, deque c1 is: 100 After swapping with c2, deque c1 is: 1 2 3 ``` -## value_type +## `value_type` -A type that represents the data type stored in a deque. +A type that represents the data type stored in a `deque`. ```cpp typedef typename Allocator::value_type value_type; diff --git a/docs/standard-library/deque-functions.md b/docs/standard-library/deque-functions.md index db96fab993..ed6244dc98 100644 --- a/docs/standard-library/deque-functions.md +++ b/docs/standard-library/deque-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "11/04/2016" f1_keywords: ["deque/std::swap"] -ms.assetid: 1d14be53-b0b7-4f66-90cc-65bdeac563fd --- # `` functions @@ -14,7 +13,7 @@ Exchanges the elements of two deques. ```cpp void swap( deque& left, - deque& right,); + deque& right); ``` ### Parameters diff --git a/docs/standard-library/directory-entry-class.md b/docs/standard-library/directory-entry-class.md index 5b215a3007..872cabb4b9 100644 --- a/docs/standard-library/directory-entry-class.md +++ b/docs/standard-library/directory-entry-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: directory_entry Class" title: "directory_entry Class" -ms.date: "09/10/2018" +ms.date: 06/10/2022 f1_keywords: ["filesystem/std::experimental::filesystem::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "filesystem/std::experimental::filesystem::directory_entry::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator=", "filesystem/std::experimental::filesystem::directory_entry::assign", "filesystem/std::experimental::filesystem::directory_entry::replace_filename", "filesystem/std::experimental::filesystem::directory_entry::path", "filesystem/std::experimental::filesystem::directory_entry::status", "filesystem/std::experimental::filesystem::directory_entry::symlink_status", "filesystem/std::experimental::filesystem::directory_entry::operator<", "filesystem/std::experimental::filesystem::directory_entry::operator==", "filesystem/std::experimental::filesystem::directory_entry::operator!=", "filesystem/std::experimental::filesystem::directory_entry::operator<=", "filesystem/std::experimental::filesystem::directory_entry::operator>", "filesystem/std::experimental::filesystem::directory_entry::operator>="] ms.assetid: 1827c67b-4137-4548-adb0-f955f7acaf08 helpviewer_keywords: ["std::experimental::filesystem::directory_entry", "std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "std::experimental::filesystem::directory_entry::directory_entry", "std::experimental::filesystem::directory_entry::operator=", "std::experimental::filesystem::directory_entry::assign", "std::experimental::filesystem::directory_entry::replace_filename", "std::experimental::filesystem::directory_entry::path", "std::experimental::filesystem::directory_entry::status", "std::experimental::filesystem::directory_entry::symlink_status", "std::experimental::filesystem::directory_entry::operator<", "std::experimental::filesystem::directory_entry::operator==", "std::experimental::filesystem::directory_entry::operator!=", "std::experimental::filesystem::directory_entry::operator<=", "std::experimental::filesystem::directory_entry::operator>", "std::experimental::filesystem::directory_entry::operator>="] +ms.custom: devdivchpfy22 --- + # directory_entry Class Describes an object that is returned by `*X`, where *X* is a [directory_iterator](../standard-library/directory-iterator-class.md) or a [recursive_directory_iterator](../standard-library/recursive-directory-iterator-class.md). @@ -18,7 +20,7 @@ class directory_entry; ## Remarks -The class stores an object of type [path](../standard-library/path-class.md). The stored `path` can be an instance of the [path Class](../standard-library/path-class.md) or of a type that is derived from `path`. It also stores two [file_type](../standard-library/filesystem-enumerations.md#file_type) values; one that represents what is known about the status of the stored file name, and another that represents what is known about the symbolic link status of the file name. +The class stores an object of type [path](../standard-library/path-class.md). The stored `path` can be an instance of the [path Class](../standard-library/path-class.md) or of a type that is derived from `path`. It also stores two [file_type](../standard-library/filesystem-enumerations.md#file_type) values. One value represents the status of the stored file name. The other represents the symbolic link status of the file name. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). diff --git a/docs/standard-library/directory-iterator-class.md b/docs/standard-library/directory-iterator-class.md index f69c0b7a84..b377693eee 100644 --- a/docs/standard-library/directory-iterator-class.md +++ b/docs/standard-library/directory-iterator-class.md @@ -1,12 +1,14 @@ --- description: "Learn more about: directory_iterator Class" title: "directory_iterator Class" -ms.date: "09/10/2018" -f1_keywords: ["filesystem/std::experimental::filesystem::directory_iterator", "filesystem/std::experimental::filesystem::_Directory_iterator::_Directory_iterator", "filesystem/std::experimental::filesystem::directory_iterator::directory_iterator", "filesystem/std::experimental::filesystem::directory_iterator::increment", "filesystem/std::experimental::filesystem::directory_iterator::operator=", "filesystem/std::experimental::filesystem::directory_iterator::operator==", "filesystem/std::experimental::filesystem::directory_iterator::operator!=", "filesystem/std::experimental::filesystem::directory_iterator::operator*", "filesystem/std::experimental::filesystem::directory_iterator::operator->", "filesystem/std::experimental::filesystem::directory_iterator::operator++"] +ms.date: 04/28/2023 +f1_keywords: ["filesystem/std::filesystem::directory_iterator", "filesystem/std::filesystem::_Directory_iterator::_Directory_iterator", "filesystem/std::filesystem::directory_iterator::directory_iterator", "filesystem/std::filesystem::directory_iterator::increment", "filesystem/std::filesystem::directory_iterator::operator=", "filesystem/std::filesystem::directory_iterator::operator==", "filesystem/std::filesystem::directory_iterator::operator!=", "filesystem/std::filesystem::directory_iterator::operator*", "filesystem/std::filesystem::directory_iterator::operator->", "filesystem/std::filesystem::directory_iterator::operator++"] ms.assetid: dca2ecf8-3e69-4644-a83d-705061e10cc8 -helpviewer_keywords: ["std::experimental::filesystem::directory_iterator", "std::experimental::filesystem::_Directory_iterator::_Directory_iterator", "std::experimental::filesystem::directory_iterator", "std::experimental::filesystem::directory_iterator::directory_iterator", "std::experimental::filesystem::directory_iterator::increment", "std::experimental::filesystem::directory_iterator::operator=", "std::experimental::filesystem::directory_iterator::operator==", "std::experimental::filesystem::directory_iterator::operator!=", "std::experimental::filesystem::directory_iterator::operator*", "std::experimental::filesystem::directory_iterator::operator->", "std::experimental::filesystem::directory_iterator::operator++"] +helpviewer_keywords: ["std::filesystem::directory_iterator", "std::filesystem::_Directory_iterator::_Directory_iterator", "std::filesystem::directory_iterator", "std::filesystem::directory_iterator::directory_iterator", "std::filesystem::directory_iterator::increment", "std::filesystem::directory_iterator::operator=", "std::filesystem::directory_iterator::operator==", "std::filesystem::directory_iterator::operator!=", "std::filesystem::directory_iterator::operator*", "std::filesystem::directory_iterator::operator->", "std::filesystem::directory_iterator::operator++"] +ms.custom: devdivchpfy22 --- -# directory_iterator Class + +# `directory_iterator` class Describes an input iterator that sequences through the filenames in a directory. For an iterator `X`, the expression `*X` evaluates to an object of class `directory_entry` that wraps the filename and anything known about its status. @@ -14,9 +16,9 @@ The class stores an object of type `path`, called `mydir` here for the purposes For example, given the directory `abc` with entries `def` and `ghi`, the code: -`for (directory_iterator next(path("abc")), end; next != end; ++next) visit(next->path());` +`for (directory_iterator next(path("abc")), end; next != end; ++next) visit(next->path());` -will call `visit` with the arguments `path("abc/def")` and `path("abc/ghi")`. +calls `visit` with the arguments `path("abc/def")` and `path("abc/ghi")`. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). @@ -30,36 +32,36 @@ class directory_iterator; |Constructor|Description| |-|-| -|[directory_iterator](#directory_iterator)|Constructs an input iterator that sequences through the filenames in a directory.| +|[`directory_iterator`](#directory_iterator)|Constructs an input iterator that sequences through the filenames in a directory.| ### Member functions |Member function|Description| |-|-| -|[increment](#increment)|Attempts to advance to the next filename in the directory.| +|[`increment`](#increment)|Attempts to advance to the next filename in the directory.| ### Operators |Operator|Description| |-|-| -|[operator!=](#op_neq)|Returns `!(*this == right)`.| -|[operator=](#op_as)|The defaulted member assignment operators behave as expected.| -|[operator==](#op_eq)|Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both are not end-of-sequence-iterators.| -|[operator*](#op_star)|Returns `myentry`.| -|[operator->](#op_cast)|Returns `&**this`.| -|[operator++](#op_increment)|Calls `increment()`, then returns **`*this`**, or makes a copy of the object, calls `increment()`, then returns the copy.| +|[`operator!=`](#op_neq)|Returns `!(*this == right)`.| +|[`operator=`](#op_as)|The defaulted member assignment operators behave as expected.| +|[`operator==`](#op_eq)|Returns **`true`** only if both **`*this`** and *`right`* are end-of-sequence iterators or both aren't end-of-sequence-iterators.| +|[`operator*`](#op_star)|Returns `myentry`.| +|[`operator->`](#op_cast)|Returns `&**this`.| +|[`operator++`](#op_increment)|Calls `increment()`, then returns **`*this`**, or makes a copy of the object, calls `increment()`, then returns the copy.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std::experimental::filesystem +**Namespace:** `std::filesystem` -## directory_iterator::directory_iterator +## `directory_iterator::directory_iterator` -The first constructor produces an end-of-sequence iterator. The second and third constructors store *pval* in `mydir`, then attempt to open and read `mydir` as a directory. If successful, they store the first filename in the directory in `myentry`; otherwise they produce an end-of-sequence iterator. +The first constructor produces an end-of-sequence iterator. The second and third constructors store *`pval`* in `mydir`, then attempt to open and read `mydir` as a directory. If successful, they store the first filename in the directory in `myentry`; otherwise they produce an end-of-sequence iterator. -The defaulted construtors behave as expected. +The default constructor behaves as expected. ```cpp directory_iterator() noexcept; @@ -72,16 +74,16 @@ directory_iterator(directory_iterator&&) noexcept = default; ### Parameters -*pval*\ +*`pval`*\ The stored file name path. -*ec*\ +*`ec`*\ The status error code. -*directory_iterator*\ +*`directory_iterator`*\ The stored object. -## directory_iterator::increment +## `directory_iterator::increment` The function attempts to advance to the next filename in the directory. If successful, it stores that filename in `myentry`; otherwise it produces an end-of-sequence iterator. @@ -89,7 +91,7 @@ The function attempts to advance to the next filename in the directory. If succe directory_iterator& increment(error_code& ec) noexcept; ``` -## directory_iterator::operator!= +## `directory_iterator::operator!=` The member operator returns `!(*this == right)`. @@ -99,10 +101,10 @@ bool operator!=(const directory_iterator& right) const; ### Parameters -*right*\ -The [directory_iterator](../standard-library/directory-iterator-class.md) being compared to the `directory_iterator`. +*`right`*\ +The [`directory_iterator`](../standard-library/directory-iterator-class.md) being compared to the `directory_iterator`. -## directory_iterator::operator= +## `directory_iterator::operator=` The defaulted member assignment operators behave as expected. @@ -113,12 +115,12 @@ directory_iterator& operator=(directory_iterator&&) noexcept = default; ### Parameters -*right*\ -The [directory_iterator](../standard-library/directory-iterator-class.md) being copied into the `directory_iterator`. +*`right`*\ +The [`directory_iterator`](../standard-library/directory-iterator-class.md) being copied into the `directory_iterator`. -## directory_iterator::operator== +## `directory_iterator::operator==` -The member operator returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both are not end-of-sequence-iterators. +The member operator returns **`true`** only if both **`*this`** and *`right`* are end-of-sequence iterators or both aren't end-of-sequence-iterators. ```cpp bool operator==(const directory_iterator& right) const; @@ -126,10 +128,10 @@ bool operator==(const directory_iterator& right) const; ### Parameters -*right*\ +*`right`*\ The [directory_iterator](../standard-library/directory-iterator-class.md) being compared to the `directory_iterator`. -## directory_iterator::operator* +## `directory_iterator::operator*` The member operator returns `myentry`. @@ -137,7 +139,7 @@ The member operator returns `myentry`. const directory_entry& operator*() const; ``` -## directory_iterator::operator-> +## `directory_iterator::operator->` The member function returns `&**this`. @@ -145,7 +147,7 @@ The member function returns `&**this`. const directory_entry * operator->() const; ``` -## directory_iterator::operator++ +## `directory_iterator::operator++` The first member function calls `increment()`, then returns **`*this`**. The second member function makes a copy of the object, calls `increment()`, then returns the copy. @@ -156,11 +158,11 @@ directory_iterator& operator++(int); ### Parameters -*int*\ +*`int`*\ The number of increments. ## See also +[``](../standard-library/filesystem.md)\ [Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ -[\](../standard-library/filesystem.md)\ [File System Navigation (C++)](../standard-library/file-system-navigation.md) diff --git a/docs/standard-library/drop-view-class.md b/docs/standard-library/drop-view-class.md new file mode 100644 index 0000000000..84984d30b4 --- /dev/null +++ b/docs/standard-library/drop-view-class.md @@ -0,0 +1,207 @@ +--- +title: drop_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) drop_view class, which creates a view from another view, skipping the first count elements." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::drop_view", "ranges/std::drop_view::base", "ranges/std::drop_view::begin", "ranges/std::drop_view::data", "ranges/std::drop_view::empty", "ranges/std::drop_view::end", "ranges/std::drop_view::size", "ranges/std::drop_view::operator bool", "ranges/std::drop_view::back", "ranges/std::drop_view::front", "ranges/std::drop_view::operator[]"] +helpviewer_keywords: ["std::ranges::drop_view [C++]", "std::ranges::drop_view::base [C++]", "std::ranges::drop_view::begin [C++]", "std::ranges::drop_view::data [C++]", "std::ranges::drop_view::empty [C++]", "std::ranges::drop_view::end [C++]", "std::ranges::drop_view::size [C++]", "std::ranges::drop_view::back [C++]", "std::ranges::drop_view::front [C++]", "std::ranges::drop_view::operator[] [C++]", "std::ranges::drop_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `drop_view` class (C++ Standard Library) + +Create a view that excludes the first *N* elements of a range. + +## Syntax + +```cpp +template +class drop_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::drop`](range-adaptors.md#drop) | +| **Underlying range** | Must satisfy [`output_range`](range-concepts.md#output_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and satisfies [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range) | +| **Common range** | Only if the underlying range is a [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `drop_view`. | +| [`base`](#base)C++20 | Get the underlying view. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in this view. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `drop_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `drop_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `drop_view` + +```cpp +template +class drop_view : public ranges::view_interface> +``` + +### Template parameters + +*`V`*\ +The type of the underlying view. + +### Return value + +A view of the underlying range, excluding the specified number of elements from the front.\ +If you specify more elements to drop than exist in the underlying range, then an `empty_view` is returned. + +### Remarks + +The best way to create a `drop_view` is by using the [`views::drop`](range-adaptors.md#drop) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +### Example: `drop_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 1, 2, 3, 4, 5 }; + auto newView = std::views::drop(v, 3); + for (auto e : newView) // outputs 4 5 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + auto numbers = std::views::iota(0) | std::views::take(10); // generate a view of 10 integers + for (auto i : numbers | std::views::drop(5)) // use the '|' syntax to create a drop_view + { + std::cout << i << ' '; // outputs 5 6 7 8 9 + } +} +``` + +```output +4 5 +5 6 7 8 9 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `drop_view`. + +```cpp +constexpr auto begin() + requires (!(Simple_view && ranges::random_access_range && ranges::sized_range)); + +constexpr auto begin() const + requires ranges::random_access_range && ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `drop_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `drop_view` + +```cpp +constexpr auto end() requires (!Simple_view); +constexpr auto end() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `drop_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the `drop_view`. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `drop_view`. + +### Remarks + +The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). + +## See also + +[``](ranges.md)\ +[`drop` range adaptor](range-adaptors.md#drop)\ +[`take_while()`](range-adaptors.md#take_while)\ +[`take_while_view`](take-while-view-class.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/drop-while-view-class.md b/docs/standard-library/drop-while-view-class.md new file mode 100644 index 0000000000..be9e17fff8 --- /dev/null +++ b/docs/standard-library/drop-while-view-class.md @@ -0,0 +1,231 @@ +--- +title: drop_while_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) drop_while_view class, which is a view that contains those elements of a range that remain once the leading elements that match a predicate are dropped." +ms.date: 08/04/2022 +f1_keywords: ["ranges/std::drop_while_view", "ranges/std::drop_while_view::base", "ranges/std::drop_while_view::begin", "ranges/std::drop_while_view::data", "ranges/std::drop_while_view::empty", "ranges/std::drop_while_view::end", "ranges/std::drop_while_view::size", "ranges/std::drop_while_view::operator bool", "ranges/std::drop_while_view::pred", "ranges/std::drop_while_view::back", "ranges/std::drop_while_view::front", "ranges/std::drop_while_view::operator[]"] +helpviewer_keywords: ["std::ranges::drop_while_view [C++]", "std::ranges::drop_while_view::base [C++]", "std::ranges::drop_while_view::begin [C++]", "std::ranges::drop_while_view::data [C++]", "std::ranges::drop_while_view::empty [C++]", "std::ranges::drop_while_view::size [C++]", "std::ranges::drop_while_view::end [C++]", +"std::ranges::drop_while_view::pred [C++]", "std::ranges::drop_while_view::back [C++]", "std::ranges::drop_while_view::front [C++]", "std::ranges::drop_while_view::operator[] [C++]", "std::ranges::drop_while_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `drop_while_view` class (C++ Standard Library) + +A view that contains the elements of a range that remain once the leading elements that match a predicate are dropped. + +## Syntax + +```cpp +template + requires ranges::input_range && + std::is_object_v

&& + std::indirect_unary_predicate> +class drop_while_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying view. + +*`P`*\ +The type of the predicate that determines the leading elements to drop. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::drop_while`](range-adaptors.md#drop_while) | +| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher and the underlying range's iterators must model [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for) | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`random_access_range`](range-concepts.md#random_access_range) | +| **Is `const`-iterable** | No | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base) | Get the underlying view. | +| [`begin`](#begin) | Get an iterator to the first element. | +| [`end`](#end) | Get the sentinel at the end of the view. | +| [`pred`](#pred) | Get a reference to the predicate that determines which elements to drop. | +| **Inherited from [view_interface](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | +| [`size`](view-interface.md#size) | Get the number of elements in the view. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `drop_while_view`. + +```cpp +1) constexpr drop_while_view(V base, P pred); +2) drop_while_view() requires default_initializable && default_initializable

= default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +*`pred`*\ +The predicate that determines the leading elements to drop. + +For information about the template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `drop_while_view` instance. + +### Remarks + +The best way to create a `drop_while_view` is by using the [`views::drop_while`](range-adaptors.md#drop_while) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Move constructs the `drop_while_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`.\ +2\) Default-constructs a `drop_while_view`. + +### Example: `drop_while_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto v) +{ + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::drop_while( + v, + [](int i) {return i >= 0; }); + print(myView); // -4 5 6 + + auto myView2 = v | std::views::drop_while( + [](int i) {return i < 5; }); + print(myView2); // 5 6 +} +``` + +```output +-4 5 6 +5 6 +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `pred` + +Get a reference to the predicate that determines which leading elements to drop. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + + A reference to the predicate. + +### Remarks + +If the view doesn't store a predicate, the behavior is undefined. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto mv = v | std::views::drop_while( + [](int i) {return i < 5; }); // drop the leading elements < 5 + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs "false" because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +```Output +false +``` + +## See also + +[``](ranges.md)\ +[`drop_while` range adaptor](range-adaptors.md#drop_while)\ +[`take_while` range adaptor](range-adaptors.md#take_while)\ +[`take_while_view`](take-while-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/duration-class.md b/docs/standard-library/duration-class.md index fa37f8951e..d0fa6d8e03 100644 --- a/docs/standard-library/duration-class.md +++ b/docs/standard-library/duration-class.md @@ -2,8 +2,9 @@ description: "Learn more about: duration class" title: "duration Class" ms.date: 01/05/2022 -f1_keywords: ["chrono/std::chrono::duration", "chrono/std::chrono::duration::duration", "chrono/std::chrono::duration::count", "chrono/std::chrono::duration::max", "chrono/std::chrono::duration::min", "chrono/std::chrono::duration::zero"] +f1_keywords: ["chrono/std::chrono::duration", "chrono/std::chrono::duration::duration", "chrono/std::chrono::duration::count", "chrono/std::chrono::duration::max", "chrono/std::chrono::duration::min", "chrono/std::chrono::duration::zero","chrono/std::chrono::duration::operator-", "chrono/std::chrono::duration::operator--", "chrono/std::chrono::duration::operator%=", "chrono/std::chrono::duration::operator*=", "chrono/std::chrono::duration::operator+", "chrono/std::chrono::duration::operator++", "chrono/std::chrono::duration::operator+=", "chrono/std::chrono::duration::operator-=", "chrono/std::chrono::duration::operator="] helpviewer_keywords: ["std::chrono [C++], duration"] +dev_langs: ["C++"] --- # `duration` class diff --git a/docs/standard-library/duration-values-structure.md b/docs/standard-library/duration-values-structure.md index 3677d3b97e..07fb92463a 100644 --- a/docs/standard-library/duration-values-structure.md +++ b/docs/standard-library/duration-values-structure.md @@ -3,6 +3,7 @@ description: "Learn more about: duration_values Structure" title: "duration_values Structure" ms.date: 01/05/2022 f1_keywords: ["chrono/std::chrono::duration_values", "chrono/std::chrono::duration_values::max", "chrono/std::chrono::duration_values::min", "chrono/std::chrono::duration_values::zero"] +dev_langs: ["C++"] --- # `duration_values` structure diff --git a/docs/standard-library/elements-view-class.md b/docs/standard-library/elements-view-class.md new file mode 100644 index 0000000000..4197bcf215 --- /dev/null +++ b/docs/standard-library/elements-view-class.md @@ -0,0 +1,263 @@ +--- +title: elements_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) elements_view class, which provides a view over the selected index into each tuple-like value in a range." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::elements_view", "ranges/std::elements_view::base", "ranges/std::elements_view::begin", "ranges/std::elements_view::empty", "ranges/std::elements_view::end", "ranges/std::elements_view::size", "ranges/std::elements_view::operator bool", "ranges/std::elements_view::back", "ranges/std::elements_view::front", "ranges/std::elements_view::operator[]"] +helpviewer_keywords: ["std::ranges::elements_view [C++]", "std::ranges::elements_view::base [C++]", "std::ranges::elements_view::begin [C++]", "std::ranges::elements_view::empty [C++]", "std::ranges::elements_view::end [C++]", "std::ranges::elements_view::size [C++]", "std::ranges::elements_view::back [C++]", "std::ranges::elements_view::front [C++]", "std::ranges::elements_view::operator[] [C++]", "std::ranges::elements_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `elements_view` class (C++ Standard Library) + +A view over the elements at a selected index in each tuple-like value in a range. For example, given a range of `std::tuple`, create a view consisting of the `string` elements from each tuple. + +## Syntax + +```cpp +template +class elements_view : public view_interface>; +``` + +### Template parameters + +*`N`*\ +The index of the element to select for the view. + +*`V`*\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::elements`](range-adaptors.md#elements) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the type of the indexed tuple element | +| **View iterator category** | [`forward_range`](range-concepts.md#forward_range), [`bidirectional_range`](range-concepts.md#bidirectional_range), or [`random_access_range`](range-concepts.md#random_access_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `elements_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in this view. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `elements_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `elements_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +The tuple-like types that you can use with `elements_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `elements_view`. + +```cpp +1) constexpr elements_view(V base); +2) elements_view() requires std::default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +An `elements_view` instance. + +### Remarks + +The best way to create an `elements_view` is by using the [`elements`](range-adaptors.md#elements) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create an `elements_view` from the specified view.\ +2\) Default construct an `elements_view`. + +### Example: `elements_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // create an elements_view of all the string elements (<1>) from each tuple + for (int const year : std::views::elements<1>(cpp_standards)) + { + std::cout << year << ' '; // 2003 2011 2014 2017 1988 2020 + } + + std::cout << '\n'; + + // Another way to call the range adaptor using pipe (|) syntax + for (auto&& name : cpp_standards | std::views::elements<0>) + { + std::cout << name << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== working with arrays + + std::array, 3> arr = { {{0,1,2,3}, {4,5,6,7}, {8,9,10,11}} }; + for (int& fourth : arr | std::views::elements<3>) + { + std::cout << fourth << ' '; // 3 7 11 + } + std::cout << '\n'; + + // ========== work with a std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 98", 1998}, + {"Windows 2000", 2000} + }; + + for (int year : std::views::elements<1>(windows)) + { + std::cout << year << ' '; // 1985 1987 1990 1992 1993 1995 1996 1998 2000 + } +} +``` + +```output +2003 2011 2014 2017 1988 2020 +C++03 C++11 C++14 C++17 C++98 c++20 +3 7 11 +1985 1987 1990 1992 1993 1995 1996 1998 2000 +``` + +## `base` + +Gets a copy of the underlying range. + +```cpp +// Uses a copy constructor to return the underlying range +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying range +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying range. + +## `begin` + +Get an iterator to the first element in the `elements_view`. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `elements_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `elements_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `elements_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires sized_range; +constexpr auto size() const requires sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `elements_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`keys_view`](keys-view-class.md)\ +[`values_view`](values-view-class.md)\ +[View classes](view-classes.md)\ +[``](ranges.md) diff --git a/docs/standard-library/empty-view-class.md b/docs/standard-library/empty-view-class.md new file mode 100644 index 0000000000..6d64eedb50 --- /dev/null +++ b/docs/standard-library/empty-view-class.md @@ -0,0 +1,303 @@ +--- +title: empty_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) empty_view class, which is a view that has no elements. This view is useful for test purposes such as calling code that needs to be provided with a view but doesn't need to access its underlying data." +ms.date: 10/18/2022 +f1_keywords: ["ranges/std::empty_view", "ranges/std::empty_view::base", "ranges/std::empty_view::begin", "ranges/std::empty_view::end", "ranges/std::empty_view::size", "ranges/std::empty_view::empty", "ranges/std::empty_view::operator bool", "ranges/std::empty_view::data", "ranges/std::empty_view::back", "ranges/std::empty_view::front", "ranges/std::empty_view::operator[]"] +helpviewer_keywords: ["std::ranges::empty_view [C++]", "std::ranges::empty_view [C++], base", "std::ranges::empty_view [C++], begin", "std::ranges::empty_view [C++], end", "std::ranges::empty_view [C++], size", "std::ranges::empty_view [C++], data", "std::ranges::empty_view [C++], empty", "std::ranges::empty_view [C++], operator bool", "std::ranges::empty_view [C++], front", "std::ranges::empty_view [C++], back", "std::ranges::empty_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `empty_view` class (C++ Standard Library) + +A view with no elements. This view is useful for test purposes such as calling code that needs to be provided with a view but doesn't need to access its underlying data. + +## Syntax + +```cpp +template + requires std::is_object_v +class empty_view : public ranges::view_interface>; +``` + +### Template parameters + +*`T`*\ +The type of the element. Even though there are no elements in an `empty_view`, all ranges are homogeneous. That is, they have elements of a particular type. So even though an `empty_view` has no elements, it still has a type, such as an `empty_view` of `int`, or `strings`, etc. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::empty`](range-adaptors.md#empty) | +| **Underlying range** | None | +| **Element type** | As specified when the `empty_view` is created | +| **View iterator category** | `contiguous_range` | +| **Sized** | Yes. Always returns 0 | +| **Is `const`-iterable** | Yes | +| **Common range** | Yes | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct an `empty_view`. | +| [`begin`](#begin) C++20| Returns `nullptr`. | +| [`end`](#end)C++20 | Returns `nullptr`. | +| [`size`](#size)C++20 | Returns 0 | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](#back)C++20 | Results in undefined behavior. | +| [`data`](#data)C++20 | Returns `nullptr`. | +| [`empty`](#empty)C++20 | Returns `true`. | +| [`front`](#front)C++20 | Results in undefined behavior. | +| [`operator[]`](#op_at)C++20 | Results in undefined behavior. | +| [`operator bool`](#op_bool)C++20 | Returns `false`. | + +## Remarks + +The best way to create a `empty_view` is by using the [`empty`](range-adaptors.md#empty) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +Because there can never be any elements in an `empty_view`, certain compiler optimizations are possible. For example, the compiler will eliminate `for (auto e : std::views::empty) {...}` because it knows that there's nothing to iterate over. + +Another use for `empty_view` is splitting a [`split_view`](split-view-class.md) with an `empty_view` delimiter, which results in a range of single element ranges. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `empty_view`. + +```cpp +template +inline constexpr empty_view empty{}; +``` + +### Parameters + +*`T`*\ + The type of the underlying element, of which there is none. + +### Remarks + +The best way to create a `empty_view` is by using the [`empty`](range-adaptors.md#empty) range adaptor. + +### Example `empty_view` + +```cpp +// requires /std:c++20 or higher +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + bool isNotEmpty = (bool)anEmptyView; + std::cout << std::boolalpha << isNotEmpty << "\n"; // false + std::cout << std::boolalpha << anEmptyView.empty(); // true +} +``` + +```output +false +true +``` + +## `back` + +Results in undefined behavior. + +```cpp +constexpr auto back() + requires ranges::bidirectional_range && ranges::common_range; + +constexpr auto back() const + requires ranges::bidirectional_range && ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that the function has been called on an empty `view_interface`. + +## `begin` + +Returns `nullptr` because there isn't a first element in the view. + +```cpp +static constexpr T* begin() noexcept +``` + +### Return value + +`nullptr` + +## `data` + +Returns `nullptr` because there isn't a first element in the view to get a pointer to. + +```cpp +static constexpr T* data() noexcept +``` + +### Return value + +`nullptr`. + +## `empty` + +Test whether the derived view is empty. + +```cpp +static constexpr bool empty() noexcept +``` + +### Parameters + +None. + +### Return value + +Returns `true`. + +## `end` + +Returns `nullptr` because there aren't any elements in the view. + +```cpp +static constexpr T* end() noexcept +``` + +### Return value + +`nullptr`. + +## `front` + +Results in undefined behavior. + +```cpp +constexpr auto front() + requires ranges::forward_range; +constexpr auto front() const + requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that the function has been called on an empty `view_interface`. + +## `operator[]` + +Results in undefined behavior. + +```cpp +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos); + +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos) const; +``` + +### Parameters + +*`pos`*\ +The position, relative to the beginning iterator, of the element to return. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that index is out of range for `view_interface`. + +## `operator bool` + +Test whether the derived view isn't empty. + +```cpp +constexpr explicit operator bool() +requires requires { ranges::empty(T ()); }; + +constexpr explicit operator bool() const +requires requires { ranges::empty(T ()); }; +``` + +### Parameters + +None. + +### Return value + +Returns `false`. + +### Example `(bool)` + +```cpp +// requires /std:c++20 or higher +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + + if (anEmptyView) // check if anEmptyView isn't empty + { + std::cout << "Error: why does an empty_view have elements?\n"; + } + else + { + std::cout << "Correct: an empty_view is not not empty\n"; + } +} +``` + +```output +Correct: an empty_view is not not empty +``` + +## `size` + +Get the number of elements in the view, which will always be 0. + +```cpp +static constexpr size_t size() +``` + +### Parameters + +None. + +### Return value + +`0`. + +## See also + +[``](ranges.md)\ +[`empty` range adaptor](range-adaptors.md#common)\ +[`single_view`](single-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/enable-if-class.md b/docs/standard-library/enable-if-class.md index 6ee6be7208..7d612d187b 100644 --- a/docs/standard-library/enable-if-class.md +++ b/docs/standard-library/enable-if-class.md @@ -4,9 +4,8 @@ title: "enable_if Class" ms.date: "11/04/2016" f1_keywords: ["type_traits/std::enable_if"] helpviewer_keywords: ["enable_if class", "enable_if"] -ms.assetid: c6b8d41c-a18f-4e30-a39e-b3aa0e8fd926 --- -# enable_if Class +# `enable_if` Class Conditionally makes an instance of a type for SFINAE overload resolution. The nested typedef `enable_if::type` exists—and is a synonym for `Type`—if and only if `Condition` is **`true`**. @@ -19,17 +18,17 @@ struct enable_if; ### Parameters -*B*\ +*`B`*\ The value that determines the existence of the resulting type. -*T*\ -The type to instantiate if *B* is true. +*`T`*\ +The type to instantiate if *`B`* is `true`. ## Remarks -If *B* is true, `enable_if` has a nested typedef named "type" that's a synonym for *T*. +If *`B`* is `true`, `enable_if` has a nested typedef named "type" that's a synonym for *`T`*. -If *B* is false, `enable_if` doesn't have a nested typedef named "type". +If *`B`* is `false`, `enable_if` doesn't have a nested typedef named "type". This alias template is provided: @@ -38,7 +37,7 @@ template using enable_if_t = typename enable_if::type; ``` -In C++, substitution failure of template parameters is not an error in itself—this is referred to as *SFINAE* (substitution failure is not an error). Typically, `enable_if` is used to remove candidates from overload resolution—that is, it culls the overload set—so that one definition can be rejected in favor of another. This conforms to SFINAE behavior. For more information about SFINAE, see [Substitution failure is not an error](https://go.microsoft.com/fwlink/p/?linkid=394798) on Wikipedia. +In C++, substitution failure of template parameters isn't an error in itself—this is referred to as *SFINAE* (substitution failure isn't an error). Typically, `enable_if` is used to remove candidates from overload resolution—that is, it culls the overload set—so that one definition can be rejected in favor of another. This conforms to SFINAE behavior. For more information about SFINAE, see [Substitution failure isn't an error](https://go.microsoft.com/fwlink/p/?linkid=394798) on Wikipedia. Here are four example scenarios: @@ -93,23 +92,23 @@ yourfunction(args, typename enable_if::type = nullptr) } ``` -Scenario 2 also works for ordinary constructors. However, it doesn't work for conversion operators because they can't take extra parameters. It also doesn't work for [variadic](../cpp/ellipses-and-variadic-templates.md) constructors because adding extra parameters makes the function parameter pack a non-deduced context and thereby defeats the purpose of `enable_if`. +Scenario 2 also works for ordinary constructors. However, it doesn't work for conversion operators because they can't take extra parameters. It also doesn't work for [`variadic`](../cpp/ellipses-and-variadic-templates.md) constructors because adding extra parameters makes the function parameter pack a non-deduced context and thereby defeats the purpose of `enable_if`. -Scenario 3 uses the name `Dummy`, but it's optional. Just " `typename = typename`" would work, but if you think that looks weird, you can use a "dummy" name—just don't use one that might also be used in the function definition. If you don't give a type to `enable_if`, it defaults to void, and that's perfectly reasonable because you don't care what `Dummy` is. This works for everything, including conversion operators and [variadic](../cpp/ellipses-and-variadic-templates.md) constructors. +Scenario 3 uses the name `Dummy`, but it's optional. Just " `typename = typename`" would work, but if you think that looks weird, you can use a "dummy" name—just don't use one that might also be used in the function definition. If you don't give a type to `enable_if`, it defaults to void, and that's perfectly reasonable because you don't care what `Dummy` is. This works for everything, including conversion operators and [`variadic`](../cpp/ellipses-and-variadic-templates.md) constructors. Scenario 4 works in constructors that don't have return types, and thereby solves the wrapping limitation of Scenario 1. However, Scenario 4 is limited to non-templated function arguments, which aren't always available. (Using Scenario 4 on a templated function argument prevents template argument deduction from working on it.) `enable_if` is powerful, but also dangerous if it's misused. Because its purpose is to make candidates vanish before overload resolution, when it's misused, its effects can be very confusing. Here are some recommendations: -- Do not use `enable_if` to select between implementations at compile-time. Don't ever write one `enable_if` for `CONDITION` and another for `!CONDITION`. Instead, use a *tag dispatch* pattern—for example, an algorithm that selects implementations depending on the strengths of the iterators they're given. +- Don't use `enable_if` to select between implementations at compile-time. Don't ever write one `enable_if` for `CONDITION` and another for `!CONDITION`. Instead, use a *tag dispatch* pattern—for example, an algorithm that selects implementations depending on the strengths of the iterators they're given. -- Do not use `enable_if` to enforce requirements. If you want to validate template parameters, and if the validation fails, cause an error instead of selecting another implementation, use [static_assert](../cpp/static-assert.md). +- Don't use `enable_if` to enforce requirements. If you want to validate template parameters, and if the validation fails, cause an error instead of selecting another implementation, use [`static_assert`](../cpp/static-assert.md). - Use `enable_if` when you have an overload set that makes otherwise good code ambiguous. Most often, this occurs in implicitly converting constructors. ## Example -This example explains how the C++ Standard Library template function [std::make_pair()](../standard-library/utility-functions.md#make_pair) takes advantage of `enable_if`. +This example explains how the C++ Standard Library template function [`std::make_pair()`](../standard-library/utility-functions.md#make_pair) takes advantage of `enable_if`. ```cpp void func(const pair&); @@ -121,14 +120,14 @@ func(make_pair("foo", "bar")); In this example, `make_pair("foo", "bar")` returns `pair`. Overload resolution has to determine which `func()` you want. `pair` has an implicitly converting constructor from `pair`. This isn't new—it was in C++98. However, in C++98/03, the implicitly converting constructor's signature always exists, even if it's `pair(const pair&)`. Overload resolution doesn't care that an attempt to instantiate that constructor explodes horribly because `const char *` isn't implicitly convertible to **`int`**; it's only looking at signatures, before function definitions are instantiated. Therefore, the example code is ambiguous, because signatures exist to convert `pair` to both `pair` and `pair`. -C++11 solved this ambiguity by using `enable_if` to make sure `pair(const pair&)` exists **only** when `const X&` is implicitly convertible to `A` and `const Y&` is implicitly convertible to `B`. This allows overload resolution to determine that `pair` is not convertible to `pair` and that the overload that takes `pair` is viable. +C++11 solved this ambiguity by using `enable_if` to make sure `pair(const pair&)` exists **only** when `const X&` is implicitly convertible to `A` and `const Y&` is implicitly convertible to `B`. This allows overload resolution to determine that `pair` isn't convertible to `pair` and that the overload that takes `pair` is viable. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[](../standard-library/type-traits.md) +[``](../standard-library/type-traits.md) diff --git a/docs/standard-library/error-category-class.md b/docs/standard-library/error-category-class.md index 3b83caf1ae..953f7753f9 100644 --- a/docs/standard-library/error-category-class.md +++ b/docs/standard-library/error-category-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: error_category Class" title: "error_category Class" -ms.date: "11/04/2016" +ms.date: 06/15/2022 f1_keywords: ["system_error/std::error_category", "system_error/std::error_category::value_type", "system_error/std::error_category::default_error_condition", "system_error/std::error_category::equivalent", "system_error/std::error_category::message", "system_error/std::error_category::name"] helpviewer_keywords: ["std::error_category", "std::error_category::value_type", "std::error_category::default_error_condition", "std::error_category::equivalent", "std::error_category::message", "std::error_category::name"] ms.assetid: e0a71e14-852d-4905-acd6-5f8ed426706d +ms.custom: devdivchpfy22 --- + # error_category Class Represents the abstract, common base for objects that describes a category of error codes. @@ -162,7 +164,7 @@ The object to be tested for equality. #### Return Value -**`true`** if the objects are equal; **`false`** if the objects are not equal. +**`true`** if the objects are equal; **`false`** if the objects aren't equal. #### Remarks @@ -183,7 +185,7 @@ The object to be tested for inequality. #### Return Value -**`true`** if the `error_category` object is not equal to the `error_category` object passed in *right*; otherwise **`false`**. +**`true`** if the `error_category` object isn't equal to the `error_category` object passed in *right*; otherwise **`false`**. #### Remarks diff --git a/docs/standard-library/error-condition-class.md b/docs/standard-library/error-condition-class.md index 71767a0471..41b06861bb 100644 --- a/docs/standard-library/error-condition-class.md +++ b/docs/standard-library/error-condition-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: error_condition Class" title: "error_condition Class" -ms.date: "11/04/2016" +description: "Learn more about: error_condition Class" +ms.date: 11/04/2016 f1_keywords: ["system_error/std::error_condition", "system_error/std::error_condition::value_type", "system_error/std::error_condition::assign", "system_error/std::error_condition::category", "system_error/std::error_condition::clear", "system_error/std::error_condition::message", "system_error/std::error_condition::operator bool"] helpviewer_keywords: ["std::error_condition", "std::error_condition::value_type", "std::error_condition::assign", "std::error_condition::category", "std::error_condition::clear", "std::error_condition::message"] -ms.assetid: 6690f481-97c9-4554-a0ff-851dc96b7a06 --- # error_condition Class @@ -160,7 +159,7 @@ bool operator==(const error_condition& right) const; #### Parameters *right*\ -The ojbect to be tested for equality. +The object to be tested for equality. #### Return Value diff --git a/docs/standard-library/exception-class.md b/docs/standard-library/exception-class.md index e0feb8f2ce..bfeb8f0d2f 100644 --- a/docs/standard-library/exception-class.md +++ b/docs/standard-library/exception-class.md @@ -4,9 +4,8 @@ title: "exception Class" ms.date: "11/04/2016" f1_keywords: ["exception/std::exception"] helpviewer_keywords: ["exception class"] -ms.assetid: 4f181f67-5888-4b50-89a6-745091ffb2fe --- -# exception Class +# `exception` Class The class serves as the base class for all exceptions thrown by certain expressions and by the C++ Standard Library. @@ -27,7 +26,7 @@ class exception { ## Remarks -Specifically, this base class is the root of the standard exception classes defined in [\](../standard-library/stdexcept.md). The C string value returned by `what` is left unspecified by the default constructor, but may be defined by the constructors for certain derived classes as an implementation-defined C string. None of the member functions throw any exceptions. +Specifically, this base class is the root of the standard exception classes defined in [``](../standard-library/stdexcept.md). The C string value returned by `what` is left unspecified by the default constructor, but may be defined by the constructors for certain derived classes as an implementation-defined C string. None of the member functions throw any exceptions. The **`int`** parameter allows you to specify that no memory should be allocated. The value of the **`int`** is ignored. @@ -36,4 +35,4 @@ The **`int`** parameter allows you to specify that no memory should be allocated ## Example -For examples of the use of the standard exception classes that inherit from the `exception` class, see any of the classes defined in [\](../standard-library/stdexcept.md). +For examples of the use of the standard exception classes that inherit from the `exception` class, see any of the classes defined in [``](../standard-library/stdexcept.md). diff --git a/docs/standard-library/exception-typedefs.md b/docs/standard-library/exception-typedefs.md index 2385a80355..f25b44b6dd 100644 --- a/docs/standard-library/exception-typedefs.md +++ b/docs/standard-library/exception-typedefs.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["exception/std::exception_ptr", "exception/std::terminate_handler", "exception/std::unexpected_handler"] -ms.assetid: 2a338480-35e2-46f7-b223-52d4e84a5768 --- # `` typedefs @@ -25,11 +24,11 @@ When you declare an `exception_ptr` variable, the variable is not associated wit Use the `current_exception` or `make_exception_ptr` function to assign an exception to an `exception_ptr` object. When you assign an exception to an `exception_ptr` variable, the variable's exception reference field points to a copy of the exception. If there is insufficient memory to copy the exception, the exception reference field points to a copy of a [std::bad_alloc](../standard-library/bad-alloc-class.md) exception. If the `current_exception` or `make_exception_ptr` function cannot copy the exception for any other reason, the function calls the `terminate` CRT function to exit the current process. -Despite its name, an `exception_ptr` object is not itself a pointer. It does not obey pointer semantics and cannot be used with the pointer member access ( `->`) or indirection (*) operators. The `exception_ptr` object has no public data members or member functions. +Despite its name, an `exception_ptr` object is not itself a pointer. It does not obey pointer semantics and cannot be used with the pointer member access (`->`) or indirection (*) operators. The `exception_ptr` object has no public data members or member functions. **Comparisons:** -You can use the equal ( `==`) and not-equal ( `!=`) operators to compare two `exception_ptr` objects. The operators do not compare the binary value (bit pattern) of the `EXCEPTION_RECORD` structures that represent the exceptions. Instead, the operators compare the addresses in the exception reference field of the `exception_ptr` objects. Consequently, a null `exception_ptr` and the NULL value compare as equal. +You can use the equal (`==`) and not-equal (`!=`) operators to compare two `exception_ptr` objects. The operators do not compare the binary value (bit pattern) of the `EXCEPTION_RECORD` structures that represent the exceptions. Instead, the operators compare the addresses in the exception reference field of the `exception_ptr` objects. Consequently, a null `exception_ptr` and the NULL value compare as equal. ## terminate_handler diff --git a/docs/standard-library/execution.md b/docs/standard-library/execution.md index 28b59cda44..ced783fe12 100644 --- a/docs/standard-library/execution.md +++ b/docs/standard-library/execution.md @@ -1,7 +1,7 @@ --- description: "Learn more about: " title: "" -ms.date: "08/17/2021" +ms.date: 09/11/2024 f1_keywords: ["", "execution/std::execution", "std::execution"] helpviewer_keywords: ["execution header"] --- @@ -22,24 +22,30 @@ namespace std::execution { } ``` -### Classes and Structs +### Classes and structs |Name|Description| |-|-| |[`is_execution_policy` Struct](is-execution-policy-struct.md)|Detects execution policies to exclude certain function signatures from otherwise ambiguous overload resolution participation.| -|[`parallel_policy` Class](parallel-policy-class.md)|Used as a unique type to disambiguate parallel algorithm overloading. Indicates that a parallel algorithm’s execution may be parallelized.| -|[`parallel_unsequenced_policy` Class](parallel-unsequenced-policy-class.md)|Used as a unique type to disambiguate parallel algorithm overloading. Indicates that a parallel algorithm’s execution may be parallelized and vectorized.| -|[`sequenced_policy` Class](sequenced-policy-class.md)|Used as a unique type to disambiguate parallel algorithm overloading. Specifies that a parallel algorithm’s execution may not be parallelized.| +|[`parallel_policy` class](parallel-policy-class.md)|Used to disambiguate parallel algorithm overloading. Indicates that a parallel algorithm's execution may be parallelized.| +|[`parallel_unsequenced_policy` class](parallel-unsequenced-policy-class.md)|Used as a unique type to disambiguate parallel algorithm overloading. Indicates that a parallel algorithm's execution may be parallelized and vectorized.| +|[`sequenced_policy` class](sequenced-policy-class.md)|Used as a unique type to disambiguate parallel algorithm overloading. Specifies that a parallel algorithm's execution may not be parallelized.| -### Microsoft Specific - -When `parallel_policy` or `parallel_unsequenced_policy` cause the algorithm to be parallelized, the parallel execution uses Windows Thread Pool; see [Thread Pools](/windows/win32/procthread/thread-pools). The number of concurrent threads is limited to the thread pool default (currently 500). The number of threads concurrently executing on hardware is currently limited by the number of logical processors in the current process's processor group, so it is effectively limited to 64; see [Processor Groups](/windows/win32/procthread/processor-groups). The maximum number of chunks for data partitioning is also currently based on the number of logical processors in the current process's processor group. +### Microsoft specific + +Parallel algorithms execute on an unspecified number of threads and divide the work into an unspecified number of data partitioning "chunks." The Windows thread pool manages the number of threads. The implementation tries to make use of the available logical processors, which corresponds to the number of hardware threads that can execute simultaneously. + +Specifying `parallel_policy` or `parallel_unsequenced_policy` causes standard library algorithms to run in parallel using the Windows Thread Pool. The number of concurrent threads, and thus the number of "chunks" for data partitioning, is limited to 500 threads because that's the default number of thread pool threads. For more information, see [Thread Pools](/windows/win32/procthread/thread-pools). + +Before Windows 11 and Windows Server 2022, applications were limited by default to a single processor group having at most 64 logical processors. This limited the number of concurrently executing threads to 64. For more information, see [Processor Groups](/windows/win32/procthread/processor-groups). + +Starting with Windows 11 and Windows Server 2022, processes and their threads have processor affinities that by default span all processors in the system and across multiple groups on machines with more than 64 processors. The limit on the number of concurrent threads is now the total number of logical processors in the system. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also diff --git a/docs/standard-library/file-clock-class.md b/docs/standard-library/file-clock-class.md index ebb53bbfff..fe87f0ce9e 100644 --- a/docs/standard-library/file-clock-class.md +++ b/docs/standard-library/file-clock-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: file_clock class" title: "file_clock class" -ms.date: 08/19/2021 +ms.date: 3/8/2024 f1_keywords: ["chrono/std::chrono::file_clock", "chrono/std::chrono::file_clock::now", "chrono/std::chrono::file_clock::to_utc", "chrono/std::chrono::file_clock::from_utc", "chrono/std::chrono::file_clock::is_steady Constant"] --- @@ -12,7 +12,7 @@ This clock can represent the range and resolution of file time values used in th ## Syntax ```cpp -using file_clock = std::filesystem::_File_time_clock. // C++20 +using file_clock = std::filesystem::_File_time_clock; // C++20 ``` ## Remarks diff --git a/docs/standard-library/filesystem-functions.md b/docs/standard-library/filesystem-functions.md index 97df23344c..2c642f3180 100644 --- a/docs/standard-library/filesystem-functions.md +++ b/docs/standard-library/filesystem-functions.md @@ -1,32 +1,31 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "03/27/2019" f1_keywords: ["FILESYSTEM/std::experimental::filesystem::absolute", "FILESYSTEM/std::experimental::filesystem::canonical", "FILESYSTEM/std::experimental::filesystem::copy", "FILESYSTEM/std::experimental::filesystem::copy_file", "FILESYSTEM/std::experimental::filesystem::copy_symlink", "FILESYSTEM/std::experimental::filesystem::create_directories", "FILESYSTEM/std::experimental::filesystem::create_directory", "FILESYSTEM/std::experimental::filesystem::create_directory_symlink", "FILESYSTEM/std::experimental::filesystem::create_hard_link", "FILESYSTEM/std::experimental::filesystem::create_symlink", "FILESYSTEM/std::experimental::filesystem::current_path", "FILESYSTEM/std::experimental::filesystem::equivalent", "FILESYSTEM/std::experimental::filesystem::exists", "FILESYSTEM/std::experimental::filesystem::file_size", "FILESYSTEM/std::experimental::filesystem::hard_link_count", "FILESYSTEM/std::experimental::filesystem::hash_value", "FILESYSTEM/std::experimental::filesystem::is_block_file", "FILESYSTEM/std::experimental::filesystem::is_character_file", "FILESYSTEM/std::experimental::filesystem::is_directory", "FILESYSTEM/std::experimental::filesystem::is_empty", "FILESYSTEM/std::experimental::filesystem::is_fifo", "FILESYSTEM/std::experimental::filesystem::is_other", "FILESYSTEM/std::experimental::filesystem::is_regular_file", "FILESYSTEM/std::experimental::filesystem::is_socket", "FILESYSTEM/std::experimental::filesystem::is_symlink", "FILESYSTEM/std::experimental::filesystem::last_write_time", "FILESYSTEM/std::experimental::filesystem::permissions", "FILESYSTEM/std::experimental::filesystem::read_symlink", "FILESYSTEM/std::experimental::filesystem::remove", "FILESYSTEM/std::experimental::filesystem::remove_all", "FILESYSTEM/std::experimental::filesystem::rename", "FILESYSTEM/std::experimental::filesystem::resize_file", "FILESYSTEM/std::experimental::filesystem::space", "FILESYSTEM/std::experimental::filesystem::status", "FILESYSTEM/std::experimental::filesystem::status_known", "FILESYSTEM/std::experimental::filesystem::swap", "FILESYSTEM/std::experimental::filesystem::symlink_status", "FILESYSTEM/std::experimental::filesystem::system_complete", "FILESYSTEM/std::experimental::filesystem::temp_directory_path", "FILESYSTEM/std::experimental::filesystem::u8path"] -ms.assetid: be3cb821-4728-4d47-ab78-858fa8aa5045 helpviewer_keywords: ["std::experimental::filesystem::absolute", "std::experimental::filesystem::canonical", "std::experimental::filesystem::copy", "std::experimental::filesystem::copy_file", "std::experimental::filesystem::copy_symlink", "std::experimental::filesystem::create_directories", "std::experimental::filesystem::create_directory", "std::experimental::filesystem::create_directory_symlink", "std::experimental::filesystem::create_hard_link", "std::experimental::filesystem::create_symlink", "std::experimental::filesystem::current_path", "std::experimental::filesystem::equivalent", "std::experimental::filesystem::exists", "std::experimental::filesystem::file_size", "std::experimental::filesystem::hard_link_count", "std::experimental::filesystem::hash_value", "std::experimental::filesystem::is_block_file", "std::experimental::filesystem::is_character_file", "std::experimental::filesystem::is_directory", "std::experimental::filesystem::is_empty", "std::experimental::filesystem::is_fifo", "std::experimental::filesystem::is_other", "std::experimental::filesystem::is_regular_file", "std::experimental::filesystem::is_socket", "std::experimental::filesystem::is_symlink", "std::experimental::filesystem::last_write_time", "std::experimental::filesystem::permissions", "std::experimental::filesystem::read_symlink", "std::experimental::filesystem::remove", "std::experimental::filesystem::remove_all", "std::experimental::filesystem::rename", "std::experimental::filesystem::resize_file", "std::experimental::filesystem::space", "std::experimental::filesystem::status", "std::experimental::filesystem::status_known", "std::experimental::filesystem::swap", "std::experimental::filesystem::symlink_status", "std::experimental::filesystem::system_complete", "std::experimental::filesystem::temp_directory_path", "std::experimental::filesystem::u8path"] --- # `` functions -These free functions in the [\](../standard-library/filesystem.md) header do modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). +These free functions in the [``](../standard-library/filesystem.md) header do modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). -## absolute +## `absolute` ```cpp path absolute(const path& pval, const path& base = current_path()); ``` -The function returns the absolute pathname corresponding to *pval* relative to the pathname `base`: +The function returns the absolute pathname corresponding to *`pval`* relative to the pathname `base`: -1. If `pval.has_root_name() && pval.has_root_directory()` the function returns *pval*. +1. If `pval.has_root_name() && pval.has_root_directory()` the function returns *`pval`*. 1. If `pval.has_root_name() && !pval.has_root_directory()` the function returns `pval.root_name()` / `absolute(base).root_directory()` / `absolute(base).relative_path()` / `pval.relative_path()`. -1. If `!pval.has_root_name() && pval.has_root_directory()` the function returns `absolute(base).root_name()` / *pval*. +1. If `!pval.has_root_name() && pval.has_root_directory()` the function returns `absolute(base).root_name()` / *`pval`*. -1. If `!pval.has_root_name() && !pval.has_root_directory()` the function returns `absolute(base)` / *pval*. +1. If `!pval.has_root_name() && !pval.has_root_directory()` the function returns `absolute(base)` / *`pval`*. -## begin +## `begin` ```cpp const directory_iterator& begin(const directory_iterator& iter) noexcept; @@ -34,9 +33,9 @@ const recursive_directory_iterator& begin(const recursive_directory_iterator& iter) noexcept; ``` -Both functions return *iter*. +Both functions return *`iter`*. -## canonical +## `canonical` ```cpp path canonical(const path& pval, const path& base = current_path()); @@ -54,7 +53,7 @@ The functions all form an absolute pathname `pabs = absolute(pval, base)` (or `p The function then returns `pabs`. -## copy +## `copy` ```cpp void copy(const path& from, const path& to); @@ -63,7 +62,7 @@ void copy(const path& from, const path& to, copy_options opts); void copy(const path& from, const path& to, copy_options opts, error_code& ec) noexcept; ``` -The functions all possibly copy or link one or more files at *from* to *to* under control of *opts*, which is taken as `copy_options::none` for the overloads with no *opts* parameter. *opts* shall contain at most one of: +The functions all possibly copy or link one or more files at *from* to *to* under control of *`opts`*, which is taken as `copy_options::none` for the overloads with no *`opts`* parameter. *`opts`* shall contain at most one of: - `skip_existing`, `overwrite_existing`, or `update_existing` @@ -117,7 +116,7 @@ if (!exists(t)) Otherwise, do nothing. -## copy_file +## `copy_file` ```cpp bool copy_file(const path& from, const path& to); @@ -126,15 +125,15 @@ bool copy_file(const path& from, const path& to, copy_options opts); bool copy_file(const path& from, const path& to, copy_options opts, error_code& ec) noexcept; ``` -The functions all possibly copy the file at *from* to *to* under control of *opts*, which is taken as `copy_options::none` for the overloads with no *opts* parameter. *opts* shall contain at most one of `skip_existing`, `overwrite_existing`, or `update_existing`. +The functions all possibly copy the file at *from* to *to* under control of *`opts`*, which is taken as `copy_options::none` for the overloads with no *`opts`* parameter. *`opts`* shall contain at most one of `skip_existing`, `overwrite_existing`, or `update_existing`. If `exists(to) && !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))`, then report as an error that the file already exists. -Otherwise, if `!exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options:update_existing))`, then attempt to copy the contents and attributes of the file *from* to the file *to*. Report as an error if the copy attempt fails. +Otherwise, if `!exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))`, then attempt to copy the contents and attributes of the file *from* to the file *to*. Report as an error if the copy attempt fails. The functions return **`true`** if the copy is attempted and succeeds, otherwise **`false`**. -## copy_symlink +## `copy_symlink` ```cpp void copy_symlink(const path& from, const path& to); @@ -143,16 +142,16 @@ void copy_symlink(const path& from, const path& to, error_code& ec) noexcept; If `is_directory(from)`, the function calls `create_directory_symlink(from, to)`. Otherwise, it calls `create_symlink(from, to)`. -## create_directories +## `create_directories` ```cpp bool create_directories(const path& pval); bool create_directories(const path& pval, error_code& ec) noexcept; ``` -For a pathname such as a\/b\/c, the function creates directories a and a\/b as needed so that it can create the directory a\/b\/c as needed. It returns **`true`** only if it actually creates the directory *pval*. +For a pathname such as `a\/b\/c`, the function creates directories `a` and `a\/b` as needed so that it can create the directory `a\/b\/c` as needed. It returns **`true`** only if it actually creates the directory *`pval`*. -## create_directory +## `create_directory` ```cpp bool create_directory(const path& pval); @@ -162,9 +161,9 @@ bool create_directory(const path& pval, const path& attr); bool create_directory(const path& pval, const path& attr, error_code& ec) noexcept; ``` -The function creates the directory *pval* as needed. It returns true only if it actually creates the directory *pval*, in which case it copies permissions from the existing file *attr*, or uses `perms::all` for the overloads with no *attr* parameter. +The function creates the directory *`pval`* as needed. It returns `true` only if it actually creates the directory *`pval`*, in which case it copies permissions from the existing file *`attr`*, or uses `perms::all` for the overloads with no *`attr`* parameter. -## create_directory_symlink +## `create_directory_symlink` ```cpp void create_directory_symlink(const path& to, const path& link); @@ -173,7 +172,7 @@ void create_directory_symlink(const path& to, const path& link, error_code& ec) The function creates link as a symlink to the directory *to*. -## create_hard_link +## `create_hard_link` ```cpp void create_hard_link(const path& to, const path& link); @@ -182,7 +181,7 @@ void create_hard_link(const path& to, const path& link, error_code& ec) noexcept The function creates link as a hard link to the directory or file *to*. -## create_symlink +## `create_symlink` ```cpp void create_symlink(const path& to, const path& link); @@ -190,9 +189,9 @@ void create_symlink(const path& to, const path& link); void create_symlink(const path& to, const path& link, error_code& ec) noexcept; ``` -The function creates *link* as a symlink to the file *to*. +The function creates *`link`* as a symlink to the file *to*. -## current_path +## `current_path` ```cpp path current_path(); @@ -201,9 +200,9 @@ void current_path(const path& pval); void current_path(const path& pval, error_code& ec) noexcept; ``` -The functions with no parameter *pval* return the pathname for the current directory. The remaining functions set the current directory to *pval*. +The functions with no parameter *`pval`* return the pathname for the current directory. The remaining functions set the current directory to *`pval`*. -## end +## `end` ```cpp directory_iterator& end(const directory_iterator& iter) noexcept; @@ -212,7 +211,7 @@ recursive_directory_iterator& end(const recursive_directory_iterator& iter) noex The first function returns `directory_iterator()` and the second function returns `recursive_directory_iterator()` -## equivalent +## `equivalent` ```cpp bool equivalent(const path& left, const path& right); @@ -221,7 +220,7 @@ bool equivalent(const path& left, const path& right, error_code& ec) noexcept; The functions return **`true`** only if *left* and *right* choose the same filesystem entity. -## exists +## `exists` ```cpp bool exists(file_status stat) noexcept; @@ -231,25 +230,25 @@ bool exists(const path& pval, error_code& ec) noexcept; The first function returns `status_known && stat.type() != file_not_found`. The second and third functions return `exists(status(pval))`. -## file_size +## `file_size` ```cpp uintmax_t file_size(const path& pval); uintmax_t file_size(const path& pval, error_code& ec) noexcept; ``` -The functions return the size in bytes of the file chosen by *pval*, if `exists(pval) && is_regular_file(pval)` and the file size can be determined. Otherwise they report an error and return `uintmax_t(-1)`. +The functions return the size in bytes of the file chosen by *`pval`*, if `exists(pval) && is_regular_file(pval)` and the file size can be determined. Otherwise they report an error and return `uintmax_t(-1)`. -## hard_link_count +## `hard_link_count` ```cpp uintmax_t hard_link_count(const path& pval); uintmax_t hard_link_count(const path& pval, error_code& ec) noexcept; ``` -The function returns the number of hard links for *pval*, or \-1 if an error occurs. +The function returns the number of hard links for *`pval`*, or \-1 if an error occurs. -## hash_value +## `hash_value` ```cpp size_t hash_value(const path& pval) noexcept; @@ -257,7 +256,7 @@ size_t hash_value(const path& pval) noexcept; The function returns a hash value for `pval.native()`. -## is_block_file +## `is_block_file` ```cpp bool is_block_file(file_status stat) noexcept; @@ -267,7 +266,7 @@ bool is_block_file(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::block`. The remaining functions return `is_block_file(status(pval))`. -## is_character_file +## `is_character_file` ```cpp bool is_character_file(file_status stat) noexcept; @@ -277,7 +276,7 @@ bool is_character_file(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::character`. The remaining functions return `is_character_file(status(pval))`. -## is_directory +## `is_directory` ```cpp bool is_directory(file_status stat) noexcept; @@ -287,7 +286,7 @@ bool is_directory(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::directory`. The remaining functions return `is_directory_file(status(pval))`. -## is_empty +## `is_empty` ```cpp bool is_empty(file_status stat) noexcept; @@ -297,7 +296,7 @@ bool is_empty(const path& pval, error_code& ec) noexcept; If `is_directory(pval)`, then the function returns `directory_iterator(pval) == directory_iterator()`; otherwise it returns `file_size(pval) == 0`. -## is_fifo +## `is_fifo` ```cpp bool is_fifo(file_status stat) noexcept; @@ -307,7 +306,7 @@ bool is_fifo(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::fifo`. The remaining functions return `is_fifo(status(pval))`. -## is_other +## `is_other` ```cpp bool is_other(file_status stat) noexcept; @@ -317,7 +316,7 @@ bool is_other(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::other`. The remaining functions return `is_other(status(pval))`. -## is_regular_file +## `is_regular_file` ```cpp bool is_regular_file(file_status stat) noexcept; @@ -327,7 +326,7 @@ bool is_regular_file(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::regular`. The remaining functions return `is_regular_file(status(pval))`. -## is_socket +## `is_socket` ```cpp bool is_socket(file_status stat) noexcept; @@ -337,7 +336,7 @@ bool is_socket(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::socket`. The remaining functions return `is_socket(status(pval))`. -## is_symlink +## `is_symlink` ```cpp bool is_symlink(file_status stat) noexcept; @@ -347,7 +346,7 @@ bool is_symlink(const path& pval, error_code& ec) noexcept; The first function returns `stat.type() == file_type::symlink`. The remaining functions return `is_symlink(status(pval))`. -## last_write_time +## `last_write_time` ```cpp file_time_type last_write_time(const path& pval); @@ -356,20 +355,20 @@ void last_write_time(const path& pval, file_time_type new_time); void last_write_time(const path& pval, file_time_type new_time, error_code& ec) noexcept; ``` -The first two functions return the time of last data modification for *pval*, or `file_time_type(-1)` if an error occurs. The last two functions set the time of last data modification for *pval* to *new_time*. +The first two functions return the time of last data modification for *`pval`*, or `file_time_type(-1)` if an error occurs. The last two functions set the time of last data modification for *`pval`* to *`new_time`*. -## permissions +## `permissions` ```cpp void permissions(const path& pval, perms mask); void permissions(const path& pval, perms mask, error_code& ec) noexcept; ``` -The functions set the permissions for the pathname chosen by *pval* to `mask & perms::mask` under control of `perms & (perms::add_perms | perms::remove_perms)`. *mask* shall contain at most one of `perms::add_perms` and `perms::remove_perms`. +The functions set the permissions for the pathname chosen by *`pval`* to `mask & perms::mask` under control of `perms & (perms::add_perms | perms::remove_perms)`. *`mask`* shall contain at most one of `perms::add_perms` and `perms::remove_perms`. If `mask & perms::add_perms`, the functions set the permissions to `status(pval).permissions() | mask & perms::mask`. Otherwise, if `mask & perms::remove_perms`, the functions set the permissions to `status(pval).permissions() & ~(mask & perms::mask)`. Otherwise, the functions set the permissions to `mask & perms::mask`. -## proximate +## `proximate` ```cpp path proximate(const path& p, error_code& ec); @@ -377,7 +376,7 @@ path proximate(const path& p, const path& base = current_path()); path proximate(const path& p, const path& base, error_code& ec); ``` -## read_symlink +## `read_symlink` ```cpp path read_symlink(const path& pval); @@ -386,7 +385,7 @@ path read_symlink(const path& pval, error_code& ec); The functions report an error and return `path()` if `!is_symlink(pval)`. Otherwise, the functions return an object of type `path` containing the symbolic link. -## relative +## `relative` ```cpp path relative(const path& p, error_code& ec); @@ -394,7 +393,7 @@ path relative(const path& p, const path& base = current_path()); path relative(const path& p, const path& base, error_code& ec); ``` -## remove +## `remove` ```cpp bool remove(const path& pval); @@ -403,16 +402,16 @@ bool remove(const path& pval, error_code& ec) noexcept; The functions return **`true`** only if `exists(symlink_status(pval))` and the file is successfully removed. A symlink is itself removed, not the file it chooses. -## remove_all +## `remove_all` ```cpp uintmax_t remove_all(const path& pval); uintmax_t remove_all(const path& pval, error_code& ec) noexcept; ``` -If *pval* is a directory, the functions recursively remove all directory entries, then the entry itself. Otherwise, the functions call `remove`. They return a count of all elements successfully removed. +If *`pval`* is a directory, the functions recursively remove all directory entries, then the entry itself. Otherwise, the functions call `remove`. They return a count of all elements successfully removed. -## rename +## `rename` ```cpp void rename(const path& from, const path& to); @@ -421,7 +420,7 @@ void rename(const path& from, const path& to, error_code& ec) noexcept; The functions rename *from* to *to*. A symlink is itself renamed, not the file it chooses. -## resize_file +## `resize_file` ```cpp void resize(const path& pval, uintmax_t size); @@ -430,25 +429,25 @@ void resize(const path& pval, uintmax_t size, error_code& ec) noexcept; The functions alter the size of a file such that `file_size(pval) == size` -## space +## `space` ```cpp space_info space(const path& pval); space_info space(const path& pval, error_code& ec) noexcept; ``` -The function returns information about the volume chosen by *pval*, in a structure of type `space_info`. The structure contains `uintmax_t(-1)` for any value that can't be determined. +The function returns information about the volume chosen by *`pval`*, in a structure of type `space_info`. The structure contains `uintmax_t(-1)` for any value that can't be determined. -## status +## `status` ```cpp file_status status(const path& pval); file_status status(const path& pval, error_code& ec) noexcept; ``` -The functions return the pathname status, the file type, and permissions, associated with *pval*. A symlink is itself not tested, but the file it chooses. +The functions return the pathname status, the file type, and permissions, associated with *`pval`*. A symlink is itself not tested, but the file it chooses. -## status_known +## `status_known` ```cpp bool status_known(file_status stat) noexcept; @@ -456,7 +455,7 @@ bool status_known(file_status stat) noexcept; The function returns `stat.type() != file_type::none` -## swap +## `swap` ```cpp void swap(path& left, path& right) noexcept; @@ -464,25 +463,25 @@ void swap(path& left, path& right) noexcept; The function exchanges the contents of *left* and *right*. -## symlink_status +## `symlink_status` ```cpp file_status symlink_status(const path& pval); file_status symlink_status(const path& pval, error_code& ec) noexcept; ``` -The functions return the pathname symlink status, the file type, and permissions, associated with *pval*. The functions behave the same as `status(pval)` except that a symlink is itself tested, not the file it chooses. +The functions return the pathname symlink status, the file type, and permissions, associated with *`pval`*. The functions behave the same as `status(pval)` except that a symlink is itself tested, not the file it chooses. -## system_complete +## `system_complete` ```cpp path system_complete(const path& pval); path system_complete(const path& pval, error_code& ec); ``` -The functions return an absolute pathname that takes into account, as necessary, the current directory associated with its root name. \(For POSIX, the functions return `absolute(pval)`.\) +The functions return an absolute pathname that takes into account, as necessary, the current directory associated with its root name. (For POSIX, the functions return `absolute(pval)`). -## temp_directory_path +## `temp_directory_path` ```cpp path temp_directory_path(); @@ -491,7 +490,7 @@ path temp_directory_path(error_code& ec); The functions return a pathname for a directory suitable for containing temporary files. -## u8path +## `u8path` ```cpp template @@ -503,7 +502,7 @@ path u8path(InIt first, InIt last); The first function behaves the same as `path(source)` and the second function behaves the same as `path(first, last)` except that the chosen source in each case is taken as a sequence of char elements encoded as UTF-8, whatever the filesystem. -## weakly_canonical +## `weakly_canonical` ```cpp path weakly_canonical(const path& p); diff --git a/docs/standard-library/filter-view-class.md b/docs/standard-library/filter-view-class.md new file mode 100644 index 0000000000..f99b3791bb --- /dev/null +++ b/docs/standard-library/filter-view-class.md @@ -0,0 +1,219 @@ +--- +title: filter_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) filter_view class, which is a view that filters out elements of a range that don't match a predicate." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::filter_view", "ranges/std::filter_view::base", "ranges/std::filter_view::begin", "ranges/std::filter_view::empty", "ranges/std::filter_view::end", "ranges/std::filter_view::operator bool", "ranges/std::filter_view::pred", "ranges/std::filter_view::back", "ranges/std::filter_view::front"] +helpviewer_keywords: ["std::ranges::filter_view [C++]", "std::ranges::filter_view::base [C++]", "std::ranges::filter_view::begin [C++]", "std::ranges::filter_view::empty [C++]", "std::ranges::filter_view::end [C++]", "std::ranges::filter_view::pred [C++]", "std::ranges::filter_view::back [C++]", "std::ranges::filter_view::front [C++]", "std::ranges::filter_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `filter_view` class (C++ Standard Library) + +A view that filters out the elements of a range that don't match the predicate. + +## Syntax + +```cpp +template> Pred> + requires view && is_object_v +class filter_view : public view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying range. + +*`Pred`*\ +The type of the predicate that determines which elements to keep. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::filter`](range-adaptors.md#filter) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `input_range`, [`forward_range`](range-concepts.md#forward_range), or [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`pred`](#pred)C++20| Get a reference to the predicate that determines which elements to drop. | +| **Inherited from [view_interface](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `filter_view` + +```cpp +1) constexpr filter_view(V base, P pred); +2) filter_view() requires default_initializable && default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`pred`*\ +The predicate that determines which elements to keep from the underlying view. + +For information about the template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `filter_view` instance. + +### Remarks + +The best way to create a `filter_view` is by using the [`views::filter`](range-adaptors.md#filter) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a value-initialized `filter_view`. The predicate and the underlying view must be default-initializable.\ +2\) Move constructs the `filter_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`. + +### Example: `filter_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto v) +{ + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, -2, 3, -4, -5, 6}; + auto myView = std::views::filter(v, [](int i) {return i > 0; }); + print(myView); // outputs 1 3 6 + + auto myView2 = v | std::views::filter([](int i) {return i < 3; }); + print(myView2); // outputs 0 1 -2 -4 -5 +} +``` + +```output +1 3 6 +0 1 -2 -4 -5 +``` + +## `base` + +Gets the underlying range. + +```cpp +// Uses a copy constructor to return the underlying range +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying range +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `pred` + +Get a reference to the predicate that determines which leading elements to drop. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + + A reference to the predicate. + +### Remarks + +If the class doesn't store a predicate, the behavior is undefined. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto mv = v | std::views::filter( + [](int i) {return i < 5; }); // keep the elements < 5 + + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs "false" because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +## See also + +[``](ranges.md)\ +[`filter` range adaptor](range-adaptors.md#filter)\ +[`drop_while()`](range-adaptors.md#drop_while)\ +[`take_while()`](range-adaptors.md#take_while)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/forward-list-class.md b/docs/standard-library/forward-list-class.md index 8c056582bb..5e8e0a35bd 100644 --- a/docs/standard-library/forward-list-class.md +++ b/docs/standard-library/forward-list-class.md @@ -1,11 +1,13 @@ --- -description: "Learn more about: forward_list Class" title: "forward_list Class" -ms.date: "11/04/2016" +description: "Learn more about: forward_list Class" +ms.date: 06/15/2022 f1_keywords: ["forward_list/std::forward_list", "forward_list/std::forward_list::allocator_type", "forward_list/std::forward_list::const_iterator", "forward_list/std::forward_list::const_pointer", "forward_list/std::forward_list::const_reference", "forward_list/std::forward_list::difference_type", "forward_list/std::forward_list::iterator", "forward_list/std::forward_list::pointer", "forward_list/std::forward_list::reference", "forward_list/std::forward_list::size_type", "forward_list/std::forward_list::value_type", "forward_list/std::forward_list::assign", "forward_list/std::forward_list::before_begin", "forward_list/std::forward_list::begin", "forward_list/std::forward_list::cbefore_begin", "forward_list/std::forward_list::cbegin", "forward_list/std::forward_list::cend", "forward_list/std::forward_list::clear", "forward_list/std::forward_list::emplace_after", "forward_list/std::forward_list::emplace_front", "forward_list/std::forward_list::empty", "forward_list/std::forward_list::end", "forward_list/std::forward_list::erase_after", "forward_list/std::forward_list::front", "forward_list/std::forward_list::get_allocator", "forward_list/std::forward_list::insert_after", "forward_list/std::forward_list::max_size", "forward_list/std::forward_list::merge", "forward_list/std::forward_list::pop_front", "forward_list/std::forward_list::push_front", "forward_list/std::forward_list::remove", "forward_list/std::forward_list::remove_if", "forward_list/std::forward_list::resize", "forward_list/std::forward_list::reverse", "forward_list/std::forward_list::sort", "forward_list/std::forward_list::splice_after", "forward_list/std::forward_list::swap", "forward_list/std::forward_list::unique"] helpviewer_keywords: ["std::forward_list", "std::forward_list::allocator_type", "std::forward_list::const_iterator", "std::forward_list::const_pointer", "std::forward_list::const_reference", "std::forward_list::difference_type", "std::forward_list::iterator", "std::forward_list::pointer", "std::forward_list::reference", "std::forward_list::size_type", "std::forward_list::value_type", "std::forward_list::assign", "std::forward_list::before_begin", "std::forward_list::begin", "std::forward_list::cbefore_begin", "std::forward_list::cbegin", "std::forward_list::cend", "std::forward_list::clear", "std::forward_list::emplace_after", "std::forward_list::emplace_front", "std::forward_list::empty", "std::forward_list::end", "std::forward_list::erase_after", "std::forward_list::front", "std::forward_list::get_allocator", "std::forward_list::insert_after", "std::forward_list::max_size", "std::forward_list::merge", "std::forward_list::pop_front", "std::forward_list::push_front", "std::forward_list::remove", "std::forward_list::remove_if", "std::forward_list::resize", "std::forward_list::reverse", "std::forward_list::sort", "std::forward_list::splice_after", "std::forward_list::swap", "std::forward_list::unique"] +ms.custom: devdivchpfy22 --- -# forward_list Class + +# `forward_list` Class Describes an object that controls a varying-length sequence of elements. The sequence is stored as a singly-linked list of nodes, each containing a member of type `Type`. @@ -19,22 +21,22 @@ class forward_list ### Parameters -Type*\ -The element data type to be stored in the forward_list. +*`Type`*\ +The element data type to be stored in the `forward_list`. -*Allocator*\ -The stored allocator object that encapsulates details about the forward_list allocation and deallocation of memory. This parameter is optional. The default value is allocator<`Type`>. +*`Allocator`*\ +The stored allocator object that encapsulates details about the `forward_list` allocation and deallocation of memory. This parameter is optional. The default value is allocator<`Type`>. ## Remarks -A `forward_list` object allocates and frees storage for the sequence it controls through a stored object of class *Allocator* that is based on [allocator Class](../standard-library/allocator-class.md) (commonly known as `std::allocator)`. For more information, see [Allocators](../standard-library/allocators.md). An allocator object must have the same external interface as an object of type `allocator`. +A `forward_list` object allocates and frees storage for the sequence it controls through a stored object of class *`Allocator`* that is based on [`allocator` Class](../standard-library/allocator-class.md) (commonly known as `std::allocator`). For more information, see [Allocators](../standard-library/allocators.md). An allocator object must have the same external interface as an object of type `allocator`. > [!NOTE] > The stored allocator object is not copied when the container object is assigned. -Iterators, pointers and references might become invalid when elements of their controlled sequence are erased through `forward_list`. Insertions and splices performed on the controlled sequence through `forward_list` do not invalidate iterators. +Iterators, pointers and references might become invalid when elements of their controlled sequence are erased through `forward_list`. Insertions and splices performed on the controlled sequence through `forward_list` don't invalidate iterators. -Additions to the controlled sequence might occur by calls to [forward_list::insert_after](#insert_after), which is the only member function that calls the constructor `Type(const T&)`. `forward_list` might also call move constructors. If such an expression throws an exception, the container object inserts no new elements and rethrows the exception. Thus, an object of type `forward_list` is left in a known state when such exceptions occur. +Additions to the controlled sequence might occur by calls to [`forward_list::insert_after`](#insert_after), which is the only member function that calls the constructor `Type(const T&)`. `forward_list` might also call move constructors. If such an expression throws an exception, the container object inserts no new elements and rethrows the exception. Thus, an object of type `forward_list` is left in a known state when such exceptions occur. ## Members @@ -42,62 +44,62 @@ Additions to the controlled sequence might occur by calls to [forward_list::inse |Name|Description| |-|-| -|[forward_list](#forward_list)|Constructs an object of type `forward_list`.| +|[`forward_list`](#forward_list)|Constructs an object of type `forward_list`.| ### Typedefs |Name|Description| |-|-| -|[allocator_type](#allocator_type)|A type that represents the allocator class for a forward list object.| -|[const_iterator](#const_iterator)|A type that provides a constant iterator for the forward list.| -|[const_pointer](#const_pointer)|A type that provides a pointer to a **`const`** element in a forward list.| -|[const_reference](#const_reference)|A type that provides a constant reference to an element in the forward list.| -|[difference_type](#difference_type)|A signed integer type that can be used to represent the number of elements of a forward list in a range between elements pointed to by iterators.| -|[iterator](#iterator)|A type that provides an iterator for the forward list.| -|[pointer](#pointer)|A type that provides a pointer to an element in the forward list.| -|[reference](#reference)|A type that provides a reference to an element in the forward list.| -|[size_type](#size_type)|A type that represents the unsigned distance between two elements.| -|[value_type](#value_type)|A type that represents the type of element stored in a forward list.| +|[`allocator_type`](#allocator_type)|A type that represents the allocator class for a forward list object.| +|[`const_iterator`](#const_iterator)|A type that provides a constant iterator for the forward list.| +|[`const_pointer`](#const_pointer)|A type that provides a pointer to a **`const`** element in a forward list.| +|[`const_reference`](#const_reference)|A type that provides a constant reference to an element in the forward list.| +|[`difference_type`](#difference_type)|A signed integer type that can be used to represent the number of elements of a forward list in a range between elements pointed to by iterators.| +|[`iterator`](#iterator)|A type that provides an iterator for the forward list.| +|[`pointer`](#pointer)|A type that provides a pointer to an element in the forward list.| +|[`reference`](#reference)|A type that provides a reference to an element in the forward list.| +|[`size_type`](#size_type)|A type that represents the unsigned distance between two elements.| +|[`value_type`](#value_type)|A type that represents the type of element stored in a forward list.| ### Functions |Name|Description| |-|-| -|[assign](#assign)|Erases elements from a forward list and copies a new set of elements to a target forward list.| -|[before_begin](#before_begin)|Returns an iterator addressing the position before the first element in a forward list.| -|[begin](#begin)|Returns an iterator addressing the first element in a forward list.| -|[cbefore_begin](#cbefore_begin)|Returns a const iterator addressing the position before the first element in a forward list.| -|[cbegin](#cbegin)|Returns a const iterator addressing the first element in a forward list.| -|[cend](#cend)|Returns a const iterator that addresses the location succeeding the last element in a forward list.| -|[clear](#clear)|Erases all the elements of a forward list.| -|[emplace_after](#emplace_after)|Move constructs a new element after a specified position.| -|[emplace_front](#emplace_front)|Adds an element constructed in place to the beginning of the list.| -|[empty](#empty)|Tests whether a forward list is empty.| -|[end](#end)|Returns an iterator that addresses the location succeeding the last element in a forward list.| -|[erase_after](#erase_after)|Removes elements from the forward list after a specified position.| -|[front](#front)|Returns a reference to the first element in a forward list.| -|[get_allocator](#get_allocator)|Returns a copy of the allocator object used to construct a forward list.| -|[insert_after](#insert_after)|Adds elements to the forward list after a specified position.| -|[max_size](#max_size)|Returns the maximum length of a forward list.| -|[merge](#merge)|Removes the elements from the argument list, inserts them into the target forward list, and orders the new, combined set of elements in ascending order or in some other specified order.| -|[pop_front](#pop_front)|Deletes the element at the beginning of a forward list.| -|[push_front](#push_front)|Adds an element to the beginning of a forward list.| -|[remove](#remove)|Erases elements in a forward list that matches a specified value.| -|[remove_if](#remove_if)|Erases elements from a forward list for which a specified predicate is satisfied.| -|[resize](#resize)|Specifies a new size for a forward list.| -|[reverse](#reverse)|Reverses the order in which the elements occur in a forward list.| -|[sort](#sort)|Arranges the elements in ascending order or with an order specified by a predicate.| -|[splice_after](#splice_after)|Restitches links between nodes.| -|[swap](#swap)|Exchanges the elements of two forward lists.| -|[unique](#unique)|Removes adjacent elements that pass a specified test.| +|[`assign`](#assign)|Erases elements from a forward list and copies a new set of elements to a target forward list.| +|[`before_begin`](#before_begin)|Returns an iterator addressing the position before the first element in a forward list.| +|[`begin`](#begin)|Returns an iterator addressing the first element in a forward list.| +|[`cbefore_begin`](#cbefore_begin)|Returns a const iterator addressing the position before the first element in a forward list.| +|[`cbegin`](#cbegin)|Returns a const iterator addressing the first element in a forward list.| +|[`cend`](#cend)|Returns a const iterator that addresses the location succeeding the last element in a forward list.| +|[`clear`](#clear)|Erases all the elements of a forward list.| +|[`emplace_after`](#emplace_after)|Move constructs a new element after a specified position.| +|[`emplace_front`](#emplace_front)|Adds an element constructed in place to the beginning of the list.| +|[`empty`](#empty)|Tests whether a forward list is empty.| +|[`end`](#end)|Returns an iterator that addresses the location succeeding the last element in a forward list.| +|[`erase_after`](#erase_after)|Removes elements from the forward list after a specified position.| +|[`front`](#front)|Returns a reference to the first element in a forward list.| +|[`get_allocator`](#get_allocator)|Returns a copy of the allocator object used to construct a forward list.| +|[`insert_after`](#insert_after)|Adds elements to the forward list after a specified position.| +|[`max_size`](#max_size)|Returns the maximum length of a forward list.| +|[`merge`](#merge)|Removes the elements from the argument list, inserts them into the target forward list, and orders the new, combined set of elements in ascending order or in some other specified order.| +|[`pop_front`](#pop_front)|Deletes the element at the beginning of a forward list.| +|[`push_front`](#push_front)|Adds an element to the beginning of a forward list.| +|[`remove`](#remove)|Erases elements in a forward list that matches a specified value.| +|[`remove_if`](#remove_if)|Erases elements from a forward list for which a specified predicate is satisfied.| +|[`resize`](#resize)|Specifies a new size for a forward list.| +|[`reverse`](#reverse)|Reverses the order in which the elements occur in a forward list.| +|[`sort`](#sort)|Arranges the elements in ascending order or with an order specified by a predicate.| +|[`splice_after`](#splice_after)|Restitches links between nodes.| +|[`swap`](#swap)|Exchanges the elements of two forward lists.| +|[`unique`](#unique)|Removes adjacent elements that pass a specified test.| ### Operators |Name|Description| |-|-| -|[operator=](#op_eq)|Replaces the elements of the forward list with a copy of another forward list.| +|[`operator=`](#op_eq)|Replaces the elements of the forward list with a copy of another forward list.| -## allocator_type +## `allocator_type` A type that represents the allocator class for a forward list object. @@ -107,9 +109,9 @@ typedef Allocator allocator_type; ### Remarks -`allocator_type` is a synonym for the template parameter Allocator. +`allocator_type` is a synonym for the template parameter `Allocator`. -## assign +## `assign` Erases elements from a forward list and copies a new set of elements to a target forward list. @@ -127,33 +129,33 @@ void assign(InputIterator First, InputIterator Last); ### Parameters -*first*\ +*`first`*\ The beginning of the replacement range. -*last*\ +*`last`*\ The end of the replacement range. -*count*\ +*`count`*\ The number of elements to assign. -*val*\ +*`val`*\ The value to assign each element. -*Type*\ +*`Type`*\ The type of the value. -*IList*\ -The initializer_list to copy. +*`IList`*\ +The `initializer_list` to copy. ### Remarks -If the forward_list is an integer type, the first member function behaves the same as `assign((size_type)First, (Type)Last)`. Otherwise, the first member function replaces the sequence controlled by **`*this`** with the sequence [ `First, Last)`, which must not overlap the initial controlled sequence. +If the `forward_list` is an integer type, the first member function behaves the same as `assign((size_type)First, (Type)Last)`. Otherwise, the first member function replaces the sequence controlled by **`*this`** with the sequence [ `First, Last)`, which must not overlap the initial controlled sequence. The second member function replaces the sequence controlled by **`*this`** with a repetition of `Count` elements of value `Val`. -The third member function copies the elements of the initializer_list into the forward_list. +The third member function copies the elements of the `initializer_list` into the `forward_list`. -## before_begin +## `before_begin` Returns an iterator addressing the position before the first element in a forward list. @@ -168,7 +170,7 @@ A forward iterator that points just before the first element of the sequence (or ### Remarks -## begin +## `begin` Returns an iterator addressing the first element in a forward list. @@ -183,7 +185,7 @@ A forward iterator that points at the first element of the sequence (or just bey ### Remarks -## cbefore_begin +## `cbefore_begin` Returns a const iterator addressing the position before the first element in a forward list. @@ -197,7 +199,7 @@ A forward iterator that points just before the first element of the sequence (or ### Remarks -## cbegin +## `cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -211,9 +213,9 @@ A **`const`** forward-access iterator that points at the first element of the ra ### Remarks -With the return value of `cbegin`, the elements in the range cannot be modified. +With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -222,7 +224,7 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## cend +## `cend` Returns a **`const`** iterator that addresses the location just beyond the last element in a range. @@ -238,7 +240,7 @@ A forward-access iterator that points just beyond the end of the range. `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -248,9 +250,9 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -The value returned by `cend` should not be dereferenced. +The value returned by `cend` shouldn't be dereferenced. -## clear +## `clear` Erases all the elements of a forward list. @@ -260,9 +262,9 @@ void clear(); ### Remarks -This member function calls `erase_after(before_begin(), end()).` +This member function calls `erase_after(before_begin(), end())`. -## const_iterator +## `const_iterator` A type that provides a constant iterator for the forward list. @@ -272,9 +274,9 @@ typedef implementation-defined const_iterator; ### Remarks -`const_iterator` describes an object that can serve as a constant forward iterator for the controlled sequence. It is described here as a synonym for an implementation-defined type. +`const_iterator` describes an object that can serve as a constant forward iterator for the controlled sequence. It's described here as a synonym for an implementation-defined type. -## const_pointer +## `const_pointer` A type that provides a pointer to a **`const`** element in a forward list. @@ -285,7 +287,7 @@ typedef typename Allocator::const_pointer ### Remarks -## const_reference +## `const_reference` A type that provides a constant reference to an element in the forward list. @@ -295,7 +297,7 @@ typedef typename Allocator::const_reference const_reference; ### Remarks -## difference_type +## `difference_type` A signed integer type that can be used to represent the number of elements of a forward list in a range between elements pointed to by iterators. @@ -307,7 +309,7 @@ typedef typename Allocator::difference_type difference_type; `difference_type` describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. -## emplace_after +## `emplace_after` Move constructs a new element after a specified position. @@ -318,10 +320,10 @@ iterator emplace_after(const_iterator Where, Type&& val); ### Parameters -*Where*\ +*`Where`*\ The position in the target forward list where the new element is constructed. -*val*\ +*`val`*\ The constructor argument. ### Return Value @@ -330,9 +332,9 @@ An iterator that designates the newly inserted element. ### Remarks -This member function inserts an element with the constructor arguments *val* just after the element pointed to by *Where* in the controlled sequence. Its behavior is otherwise the same as [forward_list::insert_after](#insert_after). +This member function inserts an element with the constructor arguments *`val`* just after the element pointed to by *`Where`* in the controlled sequence. Its behavior is otherwise the same as [`forward_list::insert_after`](#insert_after). -## emplace_front +## `emplace_front` Adds an element constructed in place to the beginning of the list. @@ -343,16 +345,16 @@ template ### Parameters -*val*\ +*`val`*\ The element added to the beginning of the forward list. ### Remarks -This member function inserts an element with the constructor arguments `_ val` at the end of the controlled sequence. +This member function inserts an element with the constructor arguments `val` at the beginning of the controlled sequence. If an exception is thrown, the container is left unaltered and the exception is rethrown. -## empty +## `empty` Tests whether a forward list is empty. @@ -364,7 +366,7 @@ bool empty() const; **`true`** if the forward list is empty; otherwise, **`false`**. -## end +## `end` Returns an iterator that addresses the location succeeding the last element in a forward list. @@ -377,7 +379,7 @@ iterator end(); A forward iterator that points just beyond the end of the sequence. -## erase_after +## `erase_after` Removes elements from the forward list after a specified position. @@ -388,22 +390,22 @@ iterator erase_after(const_iterator first, const_iterator last); ### Parameters -*Where*\ +*`Where`*\ The position in the target forward list where the element is erased. -*first*\ +*`first`*\ The beginning of the range to erase. -*last*\ +*`last`*\ The end of the range to erase. ### Return Value -An iterator that designates the first element remaining beyond any elements removed, or [forward_list::end](#end) if no such element exists. +An iterator that designates the first element remaining beyond any elements removed, or [`forward_list::end`](#end) if no such element exists. ### Remarks -The first member function removes the element of the controlled sequence just after *Where*. +The first member function removes the element of the controlled sequence just after *`Where`*. The second member function removes the elements of the controlled sequence in the range `( first, last)` (neither end point is included). @@ -411,7 +413,7 @@ Erasing `N` elements causes `N` destructor calls. [Reallocation](../standard-lib The member functions never throw an exception. -## forward_list +## `forward_list` Constructs an object of type `forward_list`. @@ -434,36 +436,36 @@ forward_list(InputIterator First, InputIterator Last, const Allocator& Al); ### Parameters -*Al*\ +*`Al`*\ The allocator class to use with this object. -*Count*\ +*`Count`*\ The number of elements in the list constructed. -*Val*\ +*`Val`*\ The value of the elements in the list constructed. -*Right*\ +*`Right`*\ The list of which the constructed list is to be a copy. -*First*\ +*`First`*\ The position of the first element in the range of elements to be copied. -*Last*\ +*`Last`*\ The position of the first element beyond the range of elements to be copied. -*IList*\ -The initializer_list to copy. +*`IList`*\ +The `initializer_list` to copy. ### Remarks -All constructors store an [allocator](../standard-library/allocator-class.md) and initialize the controlled sequence. The allocator object is the argument *Al*, if present. For the copy constructor, it is `right.get_allocator()`. Otherwise, it is `Allocator()`. +All constructors store an [`allocator`](../standard-library/allocator-class.md) and initialize the controlled sequence. The allocator object is the argument *`Al`*, if present. For the copy constructor, it's `right.get_allocator()`. Otherwise, it's `Allocator()`. The first two constructors specify an empty initial controlled sequence. -The third constructor specifies a repetition of *Count* elements of value `Type()`. +The third constructor specifies a repetition of *`Count`* elements of value `Type()`. -The fourth and fifth constructors specify a repetition of *Count* elements of value *Val*. +The fourth and fifth constructors specify a repetition of *`Count`* elements of value *`Val`*. The sixth constructor specifies a copy of the sequence controlled by *Right*. If `InputIterator` is an integer type, the next two constructors specify a repetition of `(size_type)First` elements of value `(Type)Last`. Otherwise, the next two constructors specify the sequence `[First, Last)`. @@ -471,7 +473,7 @@ The ninth and tenth constructors are the same as the sixth, but with an [rvalue] The last constructor specifies the initial controlled sequence with an object of class `initializer_list`. -## front +## `front` Returns a reference to the first element in a forward list. @@ -484,7 +486,7 @@ const_reference front() const; A reference to the first element of the controlled sequence, which must be non-empty. -## get_allocator +## `get_allocator` Returns a copy of the allocator object used to construct a forward list. @@ -494,9 +496,9 @@ allocator_type get_allocator() const; ### Return Value -The stored [allocator](../standard-library/allocator-class.md) object. +The stored [`allocator`](../standard-library/allocator-class.md) object. -## insert_after +## `insert_after` Adds elements to the forward list after a specified position. @@ -511,23 +513,23 @@ template ### Parameters -*Where*\ +*`Where`*\ The position in the target forward list where the first element is inserted. -*Count*\ +*`Count`*\ The number of elements to insert. -*First*\ +*`First`*\ The beginning of the insertion range. -*Last*\ +*`Last`*\ The end of the insertion range. -*Val*\ +*`Val`*\ The element added to the forward list. -*IList*\ -The initializer_list to insert. +*`IList`*\ +The `initializer_list` to insert. ### Return Value @@ -535,11 +537,11 @@ An iterator that designates the newly inserted element (first and last member fu ### Remarks -Each of the member functions inserts—just after the element pointed to by *Where* in the controlled sequence—a sequence that' specified by the remaining operands. +Each of the member functions inserts—just after the element pointed to by *`Where`* in the controlled sequence—a sequence that' specified by the remaining operands. -The first member function inserts an element that has value *Val* and returns an iterator that designates the newly inserted element. +The first member function inserts an element that has value *`Val`* and returns an iterator that designates the newly inserted element. -The second member function inserts a repetition of *Count* elements of value *Val*. +The second member function inserts a repetition of *`Count`* elements of value *`Val`*. If `InputIterator` is an integer type, the third member function behaves the same as `insert(it, (size_type)First, (Type)Last)`. Otherwise, it inserts the sequence `[First, Last)`, which must not overlap the initial controlled sequence. @@ -551,7 +553,7 @@ Inserting `N` elements causes `N` constructor calls. [Reallocation](../standard- If an exception is thrown during the insertion of one or more elements, the container is left unaltered and the exception is rethrown. -## iterator +## `iterator` A type that provides an iterator for the forward list. @@ -561,9 +563,9 @@ typedef implementation-defined iterator; ### Remarks -`iterator` describes an object that can serve as a forward iterator for the controlled sequence. It is described here as a synonym for an implementation-defined type. +`iterator` describes an object that can serve as a forward iterator for the controlled sequence. It's described here as a synonym for an implementation-defined type. -## max_size +## `max_size` Returns the maximum length of a forward list. @@ -577,7 +579,7 @@ The length of the longest sequence that the object can control. ### Remarks -## merge +## `merge` Combines two sorted sequences into a single sorted sequence in linear time. Removes the elements from the argument list, and inserts them into this `forward_list`. The two lists should be sorted by the same compare function object before the call to `merge`. The combined list will be sorted by that compare function object. @@ -589,10 +591,10 @@ template ### Parameters -*right*\ +*`right`*\ The forward list to merge from. -*comp*\ +*`comp`*\ The compare function object that is used to sort elements. ### Remarks @@ -601,11 +603,11 @@ The compare function object that is used to sort elements. For the iterators `Pi` and `Pj` designating elements at positions `i` and `j`, the first member function imposes the order `!(*Pj < *Pi)` whenever `i < j`. (The elements are sorted in `ascending` order.) The second member function imposes the order `! comp(*Pj, *Pi)` whenever `i < j`. -No pairs of elements in the original controlled sequence are reversed in the resulting controlled sequence. If a pair of elements in the resulting controlled sequence compares equal ( `!(*Pi < *Pj) && !(*Pj < *Pi)`), an element from the original controlled sequence appears before an element from the sequence controlled by `right`. +No pairs of elements in the original controlled sequence are reversed in the resulting controlled sequence. If a pair of elements in the resulting controlled sequence compares equal (`!(*Pi < *Pj) && !(*Pj < *Pi)`), an element from the original controlled sequence appears before an element from the sequence controlled by `right`. An exception occurs only if `comp` throws an exception. In that case, the controlled sequence is left in unspecified order and the exception is rethrown. -## operator= +## `operator=` Replaces the elements of the forward list with a copy of another forward list. @@ -617,21 +619,21 @@ forward_list& operator=(forward_list&& right); ### Parameters -*right*\ +*`right`*\ The forward list being copied into the forward list. -*IList*\ +*`IList`*\ A brace-enclosed initializer list, which behaves just like a sequence of elements of type `Type`. ### Remarks -The first member operator replaces the controlled sequence with a copy of the sequence controlled by *right*. +The first member operator replaces the controlled sequence with a copy of the sequence controlled by *`right`*. The second member operator replaces the controlled sequence from an object of class `initializer_list`. The third member operator is the same as the first, but with an [rvalue](../cpp/rvalue-reference-declarator-amp-amp.md) reference. -## pointer +## `pointer` A type that provides a pointer to an element in the forward list. @@ -639,7 +641,7 @@ A type that provides a pointer to an element in the forward list. typedef typename Allocator::pointer pointer; ``` -## pop_front +## `pop_front` Deletes the element at the beginning of a forward list. @@ -653,7 +655,7 @@ The first element of the forward list must be non-empty. The member function never throws an exception. -## push_front +## `push_front` Adds an element to the beginning of a forward list. @@ -664,14 +666,14 @@ void push_front(Type&& val); ### Parameters -*val*\ +*`val`*\ The element added to the beginning of the forward list. ### Remarks If an exception is thrown, the container is left unaltered and the exception is rethrown. -## reference +## `reference` A type that provides a reference to an element in the forward list. @@ -679,7 +681,7 @@ A type that provides a reference to an element in the forward list. typedef typename Allocator::reference reference; ``` -## remove +## `remove` Erases elements in a forward list that matches a specified value. @@ -689,7 +691,7 @@ void remove(const Type& val); ### Parameters -*val*\ +*`val`*\ The value which, if held by an element, will result in that element's removal from the list. ### Remarks @@ -698,7 +700,7 @@ The member function removes from the controlled sequence all elements, designate The member function never throws an exception. -## remove_if +## `remove_if` Erases elements from a forward list for which a specified predicate is satisfied. @@ -709,16 +711,16 @@ template ### Parameters -*pred*\ +*`pred`*\ The unary predicate which, if satisfied by an element, results in the deletion of that element from the list. ### Remarks The member function removes from the controlled sequence all elements, designated by the iterator `P`, for which `pred(*P)` is true. -An exception occurs only if *pred* throws an exception. In that case, the controlled sequence is left in an unspecified state and the exception is rethrown. +An exception occurs only if *`pred`* throws an exception. In that case, the controlled sequence is left in an unspecified state and the exception is rethrown. -## resize +## `resize` Specifies a new size for a forward list. @@ -729,17 +731,17 @@ void resize(size_type _Newsize, const Type& val); ### Parameters -*_Newsize*\ +*`_Newsize`*\ The number of elements in the resized forward list. -*val*\ +*`val`*\ The value to use for padding. ### Remarks -The member functions both ensure that the number of elements in the list henceforth is *_Newsize*. If it must make the controlled sequence longer, the first member function appends elements with value `Type()`, while the second member function appends elements with value *val*. To make the controlled sequence shorter, both member functions effectively call `erase_after(begin() + _Newsize - 1, end())`. +The member functions both ensure that the number of elements in the list henceforth is *`_Newsize`*. If it must make the controlled sequence longer, the first member function appends elements with value `Type()`, while the second member function appends elements with value *`val`*. To make the controlled sequence shorter, both member functions effectively call `erase_after(begin() + _Newsize - 1, end())`. -## reverse +## `reverse` Reverses the order in which the elements occur in a forward list. @@ -747,7 +749,7 @@ Reverses the order in which the elements occur in a forward list. void reverse(); ``` -## size_type +## `size_type` A type that represents the unsigned distance between two elements. @@ -759,7 +761,7 @@ typedef typename Allocator::size_type size_type; The unsigned integer type describes an object that can represent the length of any controlled sequence. -## sort +## `sort` Arranges the elements in ascending order or with an order specified by a predicate. @@ -771,7 +773,7 @@ void sort(Predicate pred); ### Parameters -*pred*\ +*`pred`*\ The ordering predicate. ### Remarks @@ -780,11 +782,11 @@ Both member functions order the elements in the controlled sequence by a predica For the iterators `Pi` and `Pj` designating elements at positions `i` and `j`, the first member function imposes the order `!(*Pj < *Pi)` whenever `i < j`. (The elements are sorted in `ascending` order.) The member template function imposes the order `! pred(*Pj, *Pi)` whenever `i < j`. No ordered pairs of elements in the original controlled sequence are reversed in the resulting controlled sequence. (The sort is stable.) -An exception occurs only if *pred* throws an exception. In that case, the controlled sequence is left in unspecified order and the exception is rethrown. +An exception occurs only if *`pred`* throws an exception. In that case, the controlled sequence is left in unspecified order and the exception is rethrown. -## splice_after +## `splice_after` -Removes elements from a source forward_list and inserts them into a destination forward_list. +Removes elements from a source `forward_list` and inserts them into a destination `forward_list`. ```cpp // insert the entire source forward_list @@ -811,30 +813,30 @@ void splice_after( ### Parameters -*Where*\ -The position in the destination forward_list after which to insert. +*`Where`*\ +The position in the destination `forward_list` after which to insert. -*Source*\ -The source forward_list that is to be inserted into the destination forward_list. +*`Source`*\ +The source `forward_list` that is to be inserted into the destination `forward_list`. -*Iter*\ -The element to be inserted from the source forward_list. +*`Iter`*\ +The element to be inserted from the source `forward_list`. -*First*\ -The first element in the range to be inserted from source forward_list. +*`First`*\ +The first element in the range to be inserted from source `forward_list`. -*Last*\ -The first position beyond the range to be inserted from the source forward_list. +*`Last`*\ +The first position beyond the range to be inserted from the source `forward_list`. ### Remarks -The first pair of member functions inserts the sequence controlled by *Source* just after the element in the controlled sequence pointed to by *Where*. It also removes all elements from *Source*. (`&Source` must not equal **`this`**.) +The first pair of member functions inserts the sequence controlled by *`Source`* just after the element in the controlled sequence pointed to by *`Where`*. It also removes all elements from *`Source`*. (`&Source` must not equal **`this`**.) -The second pair of member functions removes the element just after *Iter* in the sequence controlled by *Source* and inserts it just after the element in the controlled sequence pointed to by *Where*. (If `Where == Iter || Where == ++Iter`, no change occurs.) +The second pair of member functions removes the element just after *`Iter`* in the sequence controlled by *`Source`* and inserts it just after the element in the controlled sequence pointed to by *`Where`*. (If `Where == Iter || Where == ++Iter`, no change occurs.) -The third pair of member functions (ranged splice) inserts the subrange designated by `(First, Last)` from the sequence controlled by *Source* just after the element in the controlled sequence pointed to by *Where*. It also removes the original subrange from the sequence controlled by *Source*. (If `&Source == this`, the range `(First, Last)` must not include the element pointed to by *Where*.) +The third pair of member functions (ranged splice) inserts the subrange designated by `(First, Last)` from the sequence controlled by *`Source`* just after the element in the controlled sequence pointed to by *`Where`*. It also removes the original subrange from the sequence controlled by *`Source`*. (If `&Source == this`, the range `(First, Last)` must not include the element pointed to by *`Where`*.) -If the ranged splice inserts `N` elements, and `&Source != this`, an object of class [iterator](#iterator) is incremented `N` times. +If the ranged splice inserts `N` elements, and `&Source != this`, an object of class [`iterator`](#iterator) is incremented `N` times. No iterators, pointers, or references that designate spliced elements become invalid. @@ -911,7 +913,7 @@ int main() Beginning state of lists:c1 = (10) (11)c2 = (20) (21) (22)c3 = (30) (31)c4 = (40) (41) (42) (43)After splicing c1 into c2:c1 =c2 = (20) (21) (10) (11) (22)After splicing the first element of c3 into c2:c3 = (30)c2 = (20) (21) (31) (10) (11) (22)After splicing a range of c4 into c2:c4 = (40) (41)c2 = (20) (21) (42) (43) (31) (10) (11) (22) ``` -## swap +## `swap` Exchanges the elements of two forward lists. @@ -921,14 +923,14 @@ void swap(forward_list& right); ### Parameters -*right*\ +*`right`*\ The forward list providing the elements to be exchanged. ### Remarks -The member function swaps the controlled sequences between **`*this`** and *right*. If `get_allocator() == right.get_allocator()`, it does so in constant time, it throws no exceptions, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. +The member function swaps the controlled sequences between **`*this`** and *`right`*. If `get_allocator() == right.get_allocator()`, it does so in constant time, it throws no exceptions, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs element assignments and constructor calls proportional to the number of elements in the two controlled sequences. -## unique +## `unique` Eliminates all but the first element from every consecutive group of equal elements. @@ -940,7 +942,7 @@ void unique(BinaryPredicate comp); ### Parameters -*comp*\ +*`comp`*\ The binary predicate used to compare successive elements. ### Remarks @@ -953,7 +955,7 @@ For a controlled sequence of length `N` (> 0), the predicate `comp(*Pi, *Pj)` is An exception occurs only if `comp` throws an exception. In that case, the controlled sequence is left in an unspecified state and the exception is rethrown. -## value_type +## `value_type` A type that represents the type of element stored in a forward list. diff --git a/docs/standard-library/forward-list-operators.md b/docs/standard-library/forward-list-operators.md index 333f3280e6..f221e37576 100644 --- a/docs/standard-library/forward-list-operators.md +++ b/docs/standard-library/forward-list-operators.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" -f1_keywords: ["forward_list/std::operator!=", "forward_list/std::operator==", "forward_list/std::operator>", "forward_list/std::operator>=;", "forward_list/std::operator<", "forward_list/std::operator<="] -ms.assetid: 57492e09-3836-4dbc-9ae5-78ecf506c190 -helpviewer_keywords: ["std::operator!= (forward_list)", "std::operator== (forward_list)", "std::operator> (forward_list)", "std::operator>=; (forward_list)", "std::operator< (forward_list)", "std::operator<= (forward_list)"] +description: "Learn more about: operators" +ms.date: 11/04/2016 +f1_keywords: ["forward_list/std::operator!=", "forward_list/std::operator==", "forward_list/std::operator>", "forward_list/std::operator>=;", "forward_list/std::operator<", "forward_list/std::operator<="] +helpviewer_keywords: ["std::operator!= (forward_list)", "std::operator== (forward_list)", "std::operator> (forward_list)", "std::operator>=; (forward_list)", "std::operator< (forward_list)", "std::operator<= (forward_list)"] --- # `` operators diff --git a/docs/standard-library/fpos-class.md b/docs/standard-library/fpos-class.md index d394182344..0c13af2dad 100644 --- a/docs/standard-library/fpos-class.md +++ b/docs/standard-library/fpos-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: fpos Class" title: "fpos Class" -ms.date: "03/27/2019" +ms.date: 06/15/2022 f1_keywords: ["iosfwd/std::fpos", "iosfwd/std::fpos::seekpos", "iosfwd/std::fpos::state", "iosfwd/std::fpos::operator streamoff"] helpviewer_keywords: ["std::fpos [C++]", "std::fpos [C++], seekpos", "std::fpos [C++], state"] ms.assetid: ffd0827c-fa34-47f4-b10e-5cb707fcde47 +ms.custom: devdivchpfy22 --- + # fpos Class The class template describes an object that can store all the information needed to restore an arbitrary file-position indicator within any stream. An object of class fpos\< **St**> effectively stores at least two member objects: @@ -38,7 +40,7 @@ State information. |Member function|Description| |-|-| -|[seekpos](#seekpos)|Used internally by the C++ Standard Library only. Do not call this method from your code.| +|[seekpos](#seekpos)|Used internally by the C++ Standard Library only. Don't call this method from your code.| |[state](#state)|Sets or returns the conversion state.| ### Operators @@ -82,7 +84,7 @@ The offset into the stream. ### Remarks -The first constructor stores the offset *_Off*, relative to the beginning of file and in the initial conversion state (if that matters). If *_Off* is -1, the resulting object represents an invalid stream position. +The first constructor stores the offset *_Off*, relative to the beginning of file and in the initial conversion state. If *_Off* is -1, the resulting object represents an invalid stream position. The second constructor stores a zero offset and the object *_State*. @@ -101,7 +103,7 @@ The file-position indicator against which to compare. ### Return Value -**`true`** if the file-position indicators are not equal, otherwise **`false`**. +**`true`** if the file-position indicators aren't equal, otherwise **`false`**. ### Remarks @@ -178,7 +180,7 @@ The position in the file. ### Remarks -The member function returns **fpos(\*this) +=** `_Off`. +The member function returns **`fpos(*this) +=_Off`**. ### Example @@ -203,7 +205,7 @@ The position in the file. ### Remarks -The member function adds *_Off* to the stored offset member object and then returns **\*this**. For positioning within a file, the result is generally valid only for binary streams that do not have a state-dependent encoding. +The member function adds *_Off* to the stored offset member object and then returns **`*this`**. When working with files, the result is valid only for binary streams that don't have a state-dependent encoding. ### Example @@ -254,7 +256,7 @@ The member function returns `fpos(*this) -= _Off`. ### Remarks -For positioning within a file, the result is generally valid only for binary streams that do not have a state-dependent encoding. +When working with files, the result is valid only for binary streams that don't have a state-dependent encoding. ### Example @@ -326,7 +328,7 @@ int main( ) ## fpos::seekpos -This method is used internally by the C++ Standard Library only. Do not call this method from your code. +This method is used internally by the C++ Standard Library only. Don't call this method from your code. ```cpp fpos_t seekpos() const; diff --git a/docs/standard-library/front-insert-iterator-class.md b/docs/standard-library/front-insert-iterator-class.md index 24a5423d20..3ca56a1eb3 100644 --- a/docs/standard-library/front-insert-iterator-class.md +++ b/docs/standard-library/front-insert-iterator-class.md @@ -1,14 +1,16 @@ --- description: "Learn more about: front_insert_iterator Class" title: "front_insert_iterator Class" -ms.date: "11/04/2016" +ms.date: 06/15/2022 f1_keywords: ["iterator/std::front_insert_iterator", "iterator/std::front_insert_iterator::container_type", "iterator/std::front_insert_iterator::reference"] helpviewer_keywords: ["std::front_insert_iterator [C++]", "std::front_insert_iterator [C++], container_type", "std::front_insert_iterator [C++], reference"] ms.assetid: a9a9c075-136a-4419-928b-c4871afa033c +ms.custom: devdivchpfy22 --- + # front_insert_iterator Class -Describes an iterator adaptor that satisfies the requirements of an output iterator. It inserts, rather than overwrites, elements into the front of a sequence and thus provides semantics that are different from the overwrite semantics provided by the iterators of the C++ sequence containers. The `front_insert_iterator` class is templatized on the type of container. +Describes an iterator adaptor that satisfies the requirements of an output iterator. It inserts, rather than overwrites, elements into the front of a sequence. Thus it provides semantics that are different from the overwrite semantics provided by the iterators of the C++ sequence containers. The `front_insert_iterator` class is templatized on the type of container. ## Syntax @@ -24,7 +26,7 @@ The type of container into the front of which elements are to be inserted by a ` ## Remarks -The container must satisfy the requirements for a front insertion sequence where is it possible to insert elements at the beginning of the sequence in amortized constant time. The C++ Standard Library sequence containers defined by the [deque Class](../standard-library/deque-class.md) and [list Class](../standard-library/list-class.md) provide the needed `push_front` member function and satisfy these requirements. By contrast, sequence containers defined by the [vector Class](../standard-library/vector-class.md) do not satisfy these requirements and cannot be adapted to use with `front_insert_iterator`s. A `front_insert_iterator` must always be initialized with its container. +The container must satisfy the requirements for a front insertion sequence where is it possible to insert elements at the beginning of the sequence in amortized constant time. The C++ Standard Library sequence containers defined by the [deque Class](../standard-library/deque-class.md) and [list Class](../standard-library/list-class.md) provide the needed `push_front` member function and satisfy these requirements. By contrast, sequence containers defined by the [vector Class](../standard-library/vector-class.md) don't satisfy these requirements and can't be adapted to use with `front_insert_iterator`s. A `front_insert_iterator` must always be initialized with its container. ### Constructors @@ -172,7 +174,7 @@ The member function returns the value of the element addressed. ### Remarks -Used to implement the output iterator expression **\*Iter** = **value**. If `Iter` is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and does not change the total number of elements in the sequence. +Used to implement the output iterator expression **\*Iter** = **value**. If `Iter` is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and doesn't change the total number of elements in the sequence. ### Example diff --git a/docs/standard-library/fstream-typedefs.md b/docs/standard-library/fstream-typedefs.md index 0676590e45..4006ded8a5 100644 --- a/docs/standard-library/fstream-typedefs.md +++ b/docs/standard-library/fstream-typedefs.md @@ -1,20 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["fstream/std::filebuf", "fstream/std::fstream", "fstream/std::ifstream", "fstream/std::ofstream", "fstream/std::wfilebuf", "fstream/std::wfstream", "fstream/std::wifstream", "fstream/std::wofstream"] -ms.assetid: 8dddef2d-7f17-42a6-ba08-6f6f20597d23 --- # `` typedefs -[`filebuf`](#filebuf)\ -[`fstream`](#fstream)\ -[`ifstream`](#ifstream)\ -[`ofstream`](#ofstream)\ -[`wfilebuf`](#wfilebuf)\ -[`wfstream`](#wfstream)\ -[`wifstream`](#wifstream)\ -[`wofstream`](#wofstream) +The `` header provides the following typedefs: ## `filebuf` diff --git a/docs/standard-library/function-class.md b/docs/standard-library/function-class.md index 83a21048af..3bb0409659 100644 --- a/docs/standard-library/function-class.md +++ b/docs/standard-library/function-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: function Class" title: "function Class" -ms.date: "11/04/2016" +ms.date: 06/15/2022 f1_keywords: ["functional/std::function", "functional/std::function::result_type", "functional/std::function::assign", "functional/std::function::swap", "functional/std::function::target", "functional/std::function::target_type", "functional/std::function::operator unspecified", "functional/std::function::operator()"] helpviewer_keywords: ["std::function [C++]", "std::function [C++], result_type", "std::function [C++], assign", "std::function [C++], swap", "std::function [C++], target", "std::function [C++], target_type"] ms.assetid: 7b5ca76b-9ca3-4d89-8fcf-cad70a4aeae6 +ms.custom: devdivchpfy22 --- + # function Class Wrapper for a callable object. @@ -68,21 +70,21 @@ The allocator function. ## Remarks -The class template is a call wrapper whose call signature is `Ret(T1, T2, ..., TN)`. You use it to enclose a variety of callable objects in a uniform wrapper. +The class template is a call wrapper whose call signature is `Ret(T1, T2, ..., TN)`. You use it to enclose various callable objects in a uniform wrapper. Some member functions take an operand that names the desired target object. You can specify such an operand in several ways: -`fn` -- the callable object `fn`; after the call the `function` object holds a copy of `fn` +`fn`: The callable object `fn`; after the call the `function` object holds a copy of `fn` -`fnref` -- the callable object named by `fnref.get()`; after the call the `function` object holds a reference to `fnref.get()` +`fnref`: The callable object named by `fnref.get()`; after the call the `function` object holds a reference to `fnref.get()` -`right` -- the callable object, if any, held by the `function` object `right` +`right`: The callable object, if any, held by the `function` object `right` -`npc` -- a null pointer; after the call the `function` object is empty +`npc`: A null pointer; after the call the `function` object is empty -In all cases, `INVOKE(f, t1, t2, ..., tN)`, where `f` is the callable object and `t1, t2, ..., tN` are lvalues of types `T1, T2, ..., TN` respectively, must be well-formed and, if `Ret` is not void, convertible to `Ret`. +In all cases, `INVOKE(f, t1, t2, ..., tN)`, where `f` is the callable object and `t1, t2, ..., tN` are lvalues of types `T1, T2, ..., TN` respectively, must be well-formed and, if `Ret` isn't void, convertible to `Ret`. -An empty `function` object does not hold a callable object or a reference to a callable object. +An empty `function` object doesn't hold a callable object or a reference to a callable object. ## Members @@ -223,7 +225,6 @@ private: int main() { - typedef std::vector< std::function > vf_t; vf_t v; @@ -273,7 +274,7 @@ operator unspecified(); ### Remarks -The operator returns a value that is convertible to **`bool`** with a true value only if the object is not empty. You use it to test whether the object is empty. +The operator returns a value that is convertible to **`bool`** with a true value only if the object isn't empty. You use it to test whether the object is empty. ### Example @@ -559,7 +560,7 @@ The target callable object type to test. The type *Fty2* must be callable for the argument types `T1, T2, ..., TN` and the return type `Ret`. If `target_type() == typeid(Fty2)`, the member template function returns the address of the target object; otherwise, it returns 0. -A type *Fty2* is callable for the argument types `T1, T2, ..., TN` and the return type `Ret` if, for lvalues `fn, t1, t2, ..., tN` of types `Fty2, T1, T2, ..., TN`, respectively, `INVOKE(fn, t1, t2, ..., tN)` is well-formed and, if `Ret` is not **`void`**, convertible to `Ret`. +A type *Fty2* is callable for the argument types `T1, T2, ..., TN` and the return type `Ret` if, for lvalues `fn, t1, t2, ..., tN` of types `Fty2, T1, T2, ..., TN`, respectively, `INVOKE(fn, t1, t2, ..., tN)` is well-formed and, if `Ret` isn't **`void`**, convertible to `Ret`. ### Example diff --git a/docs/standard-library/functional.md b/docs/standard-library/functional.md index 19e84df8d1..6a8aa9bfbc 100644 --- a/docs/standard-library/functional.md +++ b/docs/standard-library/functional.md @@ -20,7 +20,7 @@ Defines C++ Standard Library functions that help construct *function objects*, a Algorithms require two types of function objects: *unary* and *binary*. Unary function objects require one argument, and binary function objects require two arguments. A function object and function pointers can be passed as a predicate to an algorithm, but function objects are also adaptable and increase the scope, flexibility, and efficiency of the C++ Standard Library. If, for example, a value needed to be bound to a function before being passed to an algorithm, then a function pointer could not be used. Function adaptors convert function pointers into adaptable function objects that can be bound to a value. The header \ also contains member function adaptors that allow member functions to be called as adaptable function objects. Functions are adaptable if they have nested type declarations specifying their argument and return types. Function objects and their adaptors allow the C++ Standard Library to upgrade existing applications and help integrate the library into the C++ programming environment. -The implementation of the function objects in \ includes *transparent operator functors*. which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less())`. +The implementation of the function objects in \ includes *transparent operator functors*, which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less())`. The following features are added in C++11, C++14 and C++17: @@ -99,10 +99,10 @@ Every call wrapper has a move constructor and a copy constructor. A *simple call |[bind](../standard-library/functional-functions.md#bind)|Binds arguments to a callable object.| |[bind1st](../standard-library/functional-functions.md#bind1st)|A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the first argument of the binary function to a specified value.
(Deprecated in C++11, removed in C++17.) | |[bind2nd](../standard-library/functional-functions.md#bind2nd)|A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the second argument of the binary function to a specified value.
(Deprecated in C++11, removed in C++17.) | -|[bit_and](../standard-library/functional-functions.md#bit_and)|Returns the bitwise logical AND (binary operator&) of the two parameters.| -|[bit_not](../standard-library/functional-functions.md#bit_not)|Returns the bitwise logical complement (operator~) of the parameter.
(Added in C++14.) | -|[bit_or](../standard-library/functional-functions.md#bit_or)|Returns the bitwise logical OR (operator|) of the two parameters.| -|[bit_xor](../standard-library/functional-functions.md#bit_xor)|Returns the bitwise logical XOR (operator^) of the two parameters.| +|[bit_and](../standard-library/functional-functions.md#bit_and)|Returns the bitwise AND (binary `operator&`) of the two parameters.| +|[bit_not](../standard-library/functional-functions.md#bit_not)|Returns the bitwise complement (`operator~`) of the parameter.
(Added in C++14.) | +|[bit_or](../standard-library/functional-functions.md#bit_or)|Returns the bitwise OR (`operator|`) of the two parameters.| +|[bit_xor](../standard-library/functional-functions.md#bit_xor)|Returns the bitwise XOR (`operator^`) of the two parameters.| |[cref](../standard-library/functional-functions.md#cref)|Constructs a const `reference_wrapper` from an argument.| |[invoke](../standard-library/functional-functions.md#invoke)|| |[mem_fn](../standard-library/functional-functions.md#mem_fn)|Generates a simple call wrapper.| diff --git a/docs/standard-library/future-class.md b/docs/standard-library/future-class.md index aeb6eb8036..5a5eaa4eb6 100644 --- a/docs/standard-library/future-class.md +++ b/docs/standard-library/future-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: future Class" title: "future Class" -ms.date: "11/04/2016" +ms.date: 06/15/2022 f1_keywords: ["future/std::future", "future/std::future::future", "future/std::future::get", "future/std::future::share", "future/std::future::valid", "future/std::future::wait", "future/std::future::wait_for", "future/std::future::wait_until"] ms.assetid: 495e82c3-5341-4e37-87dd-b40107fbdfb6 helpviewer_keywords: ["std::future [C++]", "std::future [C++], future", "std::future [C++], get", "std::future [C++], share", "std::future [C++], valid", "std::future [C++], wait", "std::future [C++], wait_for", "std::future [C++], wait_until"] +ms.custom: devdivchpfy22 --- + # `future` Class Describes an *asynchronous return object*. @@ -19,7 +21,7 @@ class future; ## Remarks -Each standard *asynchronous provider* returns an object whose type is an instantiation of this template. A `future` object provides the only access to the asynchronous provider that it is associated with. If you need multiple asynchronous return objects that are associated with the same asynchronous provider, copy the `future` object to a [`shared_future`](shared-future-class.md) object. +Each standard *asynchronous provider* returns an object whose type is an instantiation of this template. A `future` object provides the only access to the asynchronous provider that it's associated with. If you need multiple asynchronous return objects that are associated with the same asynchronous provider, copy the `future` object to a [`shared_future`](shared-future-class.md) object. ## Members @@ -35,7 +37,7 @@ Each standard *asynchronous provider* returns an object whose type is an instant |----------|-----------------| |[`get`](#get)|Retrieves the result that is stored in the associated asynchronous state.| |[`share`](#share)|Converts the object to a `shared_future`.| -|[`valid`](#valid)|Specifies whether the object is not empty.| +|[`valid`](#valid)|Specifies whether the object isn't empty.| |[`wait`](#wait)|Blocks the current thread until the associated asynchronous state is ready.| |[`wait_for`](#wait_for)|Blocks until the associated asynchronous state is ready or until the specified time has elapsed.| |[`wait_until`](#wait_until)|Blocks until the associated asynchronous state is ready or until a specified point in time.| diff --git a/docs/standard-library/future-enums.md b/docs/standard-library/future-enums.md index 087f829180..565311c064 100644 --- a/docs/standard-library/future-enums.md +++ b/docs/standard-library/future-enums.md @@ -1,19 +1,16 @@ --- -description: "Learn more about: enums" title: " enums" -ms.date: "11/04/2016" +description: "Learn more about: enums" +ms.date: 11/04/2016 f1_keywords: ["future/std::future_errc", "future/std::future_status", "future/std::launch"] -ms.assetid: 8c675645-db47-4cab-bc0e-7b87f8a302df --- # `` enums -[future_errc](#future_errc)\ -[future_status](#future_status)\ -[launch](#launch) +The `` header provides the following enums: -## future_errc Enumeration +## `future_errc` enumeration -Supplies symbolic names for all of the errors that are reported by the [future_error](../standard-library/future-error-class.md) class. +Supplies symbolic names for all of the errors that are reported by the [`future_error`](../standard-library/future-error-class.md) class. ```cpp class future_errc { @@ -24,7 +21,7 @@ class future_errc { }; ``` -## future_status Enumeration +## `future_status` enumeration Supplies symbolic names for the reasons that a timed wait function can return. @@ -36,9 +33,9 @@ enum future_status{ }; ``` -## launch Enumeration +## `launch` enumeration -Represents a bitmask type that describes the possible modes for the template function [async](../standard-library/future-functions.md#async). +Represents a bitmask type that describes the possible modes for the template function [`async`](../standard-library/future-functions.md#async). ```cpp class launch{ @@ -49,4 +46,4 @@ class launch{ ## See also -[\](../standard-library/future.md) +[\](future.md) diff --git a/docs/standard-library/future-functions.md b/docs/standard-library/future-functions.md index c40c313f2d..24e91bd0bf 100644 --- a/docs/standard-library/future-functions.md +++ b/docs/standard-library/future-functions.md @@ -1,17 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "08/17/2021" +description: "Learn more about: functions" +ms.date: 09/11/2024 f1_keywords: ["future/std::async", "future/std::future_category", "future/std::make_error_code", "future/std::make_error_condition", "future/std::swap"] helpviewer_keywords: ["std::async [C++]", "std::future_category [C++]", "std::make_error_code [C++]", "std::make_error_condition [C++]", "std::swap [C++]"] --- # `` functions -[`async`](#async)\ -[`future_category`](#future_category)\ -[`make_error_code`](#make_error_code)\ -[`make_error_condition`](#make_error_condition)\ -[`swap`](#swap)| +The `` header provides the following functions: ## `async` @@ -29,7 +25,7 @@ future::type> ### Parameters -*policy*\ +*`policy`*\ A [`launch`](../standard-library/future-enums.md#launch) value. ### Remarks @@ -48,24 +44,28 @@ The second function returns a `future` object whose *associated asynchronous Unless `decay::type` is a type other than launch, the second function doesn't participate in overload resolution. -The C++ standard states that if policy is launch::async, the function creates a new thread. However the Microsoft implementation is currently non-conforming. It obtains its threads from the Windows ThreadPool, which in some cases may provide a recycled thread rather than a new one. This means that the `launch::async` policy is implemented as `launch::async|launch::deferred`. Another implication of the ThreadPool-based implementation is that there's no guarantee that thread-local variables will be destroyed when the thread completes. If the thread is recycled and provided to a new call to `async`, the old variables will still exist. We recommend that you don't use thread-local variables with `async`. +The C++ standard states that if the policy is `launch::async`, the function behaves as if it invokes the callable object in a new thread. This means that while it typically results in creating a new thread, the implementation may use other mechanisms to achieve equivalent behavior. However, the Microsoft implementation currently doesn't conform strictly to this behavior. It obtains threads from the Windows ThreadPool, which may provide a recycled thread rather than a new one. This means that the `launch::async` policy is effectively implemented as `launch::async|launch::deferred`. Another implication of the ThreadPool-based implementation is that there's no guarantee that thread-local variables are destroyed when the thread completes. If the thread is recycled and provided to a new call to `async`, the old variables still exist. We recommend that you avoid using thread-local variables with `async`. -If *policy* is `launch::deferred`, the function marks its associated asynchronous state as holding a *deferred function* and returns. The first call to any non-timed function that waits for the associated asynchronous state to be ready in effect calls the deferred function by evaluating `INVOKE(dfn, dargs..., Ty)`. +If *`policy`* is `launch::deferred`, the function marks its associated asynchronous state as holding a *deferred function* and returns. The first call to any nontimed function that waits for the associated asynchronous state to be ready in effect calls the deferred function by evaluating `INVOKE(dfn, dargs..., Ty)`. -In all cases, the associated asynchronous state of the `future` object isn't set to *ready* until the evaluation of `INVOKE(dfn, dargs..., Ty)` completes, either by throwing an exception or by returning normally. The result of the associated asynchronous state is an exception if one was thrown, or any value that's returned by the evaluation. +In all cases, the associated asynchronous state of the `future` object isn't set to *ready* until the evaluation of `INVOKE(dfn, dargs..., Ty)` completes, either by throwing an exception or by returning normally. The result of the associated asynchronous state is an exception if one was thrown, or the value the evaluation returns. > [!NOTE] > For a `future`—or the last [`shared_future`](../standard-library/shared-future-class.md)—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. If a `future` obtained from `std::async` is moved outside the local scope, other code that uses it must be aware that its destructor may block for the shared state to become ready. The pseudo-function `INVOKE` is defined in [``](../standard-library/functional.md). -### Microsoft Specific +**Microsoft specific** + +When the passed function is executed asynchronously, it executes on the Windows Thread Pool. For more information, see [Thread Pools](/windows/win32/procthread/thread-pools). The number of concurrent threads is limited to the thread pool default, which is 500 threads. + +Before Windows 11 and Windows Server 2022, applications were limited by default to a single processor group having at most 64 logical processors. This limited the number of concurrently executing threads to 64. For more information, see [Processor Groups](/windows/win32/procthread/processor-groups). -When the passed function is executed asynchronously, it's executed on Windows Thread Pool; see [Thread Pools](/windows/win32/procthread/thread-pools). The number of concurrent threads is limited to the thread pool default (currently 500). The number of threads concurrently executing on hardware is currently limited by the number of logical processor in the process's processor group, so it's effectively limited to 64; see [Processor Groups](/windows/win32/procthread/processor-groups). +Starting with Windows 11 and Windows Server 2022, processes and their threads have processor affinities that by default span all processors in the system and across multiple groups on machines with more than 64 processors. The limit on the number of concurrent threads is now the total number of logical processors in the system. ## `future_category` -Returns a reference to the [error_category](../standard-library/error-category-class.md) object that characterizes errors that are associated with `future` objects. +Returns a reference to the [`error_category`](../standard-library/error-category-class.md) object that characterizes errors that are associated with `future` objects. ```cpp const error_category& future_category() noexcept; @@ -82,7 +82,7 @@ inline error_code make_error_code(future_errc Errno) noexcept; ### Parameters *`Errno`*\ -A [future_errc](../standard-library/future-enums.md#future_errc) value that identifies the reported error. +A [`future_errc`](../standard-library/future-enums.md#future_errc) value that identifies the reported error. ### Return Value @@ -90,7 +90,7 @@ A [future_errc](../standard-library/future-enums.md#future_errc) value that iden ## `make_error_condition` -Creates an [error_condition](../standard-library/error-condition-class.md) together with the [error_category](../standard-library/error-category-class.md) object that characterizes [future](../standard-library/future-class.md) errors. +Creates an [`error_condition`](../standard-library/error-condition-class.md) together with the [`error_category`](../standard-library/error-category-class.md) object that characterizes [`future`](../standard-library/future-class.md) errors. ```cpp inline error_condition make_error_condition(future_errc Errno) noexcept; @@ -99,7 +99,7 @@ inline error_condition make_error_condition(future_errc Errno) noexcept; ### Parameters *`Errno`*\ -A [future_errc](../standard-library/future-enums.md#future_errc) value that identifies the reported error. +A [`future_errc`](../standard-library/future-enums.md#future_errc) value that identifies the reported error. ### Return Value diff --git a/docs/standard-library/future.md b/docs/standard-library/future.md index 5eccafbbea..80e8f7c790 100644 --- a/docs/standard-library/future.md +++ b/docs/standard-library/future.md @@ -34,7 +34,7 @@ The template function `async` and the class templates `promise` and `packaged_ta Each of the class templates `promise`, `future`, and `shared_future` has a specialization for the type **`void`** and a partial specialization for storing and retrieving a value by reference. These specializations differ from the primary template only in the signatures and semantics of the functions that store and retrieve the returned value. -The class templates `future` and `shared_future` never block in their destructors, except in one case that's preserved for backward compatibility: Unlike all other futures, for a `future`—or the last `shared_future`—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. The following usability note has been added to the description of `std::async` in the draft standard: "[Note: If a future obtained from std::async is moved outside the local scope, other code that uses the future must be aware that the future’s destructor may block for the shared state to become ready.—end note]" In all other cases, `future` and `shared_future` destructors are required and are guaranteed to never block. +The class templates `future` and `shared_future` never block in their destructors, except in one case that's preserved for backward compatibility: Unlike all other futures, for a `future`—or the last `shared_future`—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. The following usability note has been added to the description of `std::async` in the draft standard: "[Note: If a future obtained from std::async is moved outside the local scope, other code that uses the future must be aware that the future's destructor may block for the shared state to become ready.—end note]" In all other cases, `future` and `shared_future` destructors are required and are guaranteed to never block. ## Members diff --git a/docs/standard-library/gps-clock-class.md b/docs/standard-library/gps-clock-class.md index 141db8e288..80d625f319 100644 --- a/docs/standard-library/gps-clock-class.md +++ b/docs/standard-library/gps-clock-class.md @@ -3,6 +3,8 @@ description: "Learn more about: gps_clock class" title: "gps_clock class" ms.date: 08/17/2021 f1_keywords: ["chrono/std::chrono::gps_clock", "chrono/std::chrono::gps_clock::now", "chrono/std::chrono::gps_clock::to_utc", "chrono/std::chrono::gps_clock::from_utc", "chrono/std::chrono::gps_clock::is_steady constant"] +helpviewer_keywords: ["std::chrono [C++], gps_clock"] +dev_langs: ["C++"] --- # `gps_clock` class diff --git a/docs/standard-library/greater-equal-struct.md b/docs/standard-library/greater-equal-struct.md index cf301ae814..dd3921c876 100644 --- a/docs/standard-library/greater-equal-struct.md +++ b/docs/standard-library/greater-equal-struct.md @@ -24,7 +24,7 @@ template <> struct greater_equal { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left)>= std::forward(Right)); }; ``` diff --git a/docs/standard-library/gslice-array-class.md b/docs/standard-library/gslice-array-class.md index 98d8d9464c..727afddc3f 100644 --- a/docs/standard-library/gslice-array-class.md +++ b/docs/standard-library/gslice-array-class.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: gslice_array Class" -title: "gslice_array Class" -ms.date: "11/04/2016" +description: "Learn more about: gslice_array class" +title: "gslice_array class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::gslice_array"] helpviewer_keywords: ["gslice_array class"] ms.assetid: ad1b4514-b14a-4baf-a293-d5a8e8674c75 --- -# gslice_array Class +# `gslice_array` class -An internal, auxiliary class template that supports general slice objects by providing operations between subset arrays defined by the general slice of a valarray. +An internal, auxiliary class template that supports general slice objects by providing operations between subset arrays defined by the general slice of a `valarray`. ## Syntax @@ -47,15 +47,15 @@ public: ## Remarks -The class describes an object that stores a reference to an object `va` of class [valarray](../standard-library/valarray-class.md)**\**, along with an object `gs` of class [gslice](../standard-library/gslice-class.md) which describes the sequence of elements to select from the `valarray` object. +The class describes an object that stores a reference to an object `va` of class [`valarray`](../standard-library/valarray-class.md), along with an object `gs` of class [`gslice`](../standard-library/gslice-class.md), which describes the sequence of elements to select from the `valarray` object. -You construct a `gslice_array` object only by writing an expression of the form [`va[gs]`](../standard-library/valarray-class.md#op_at). The member functions of class gslice_array then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. +You construct a `gslice_array` object only by writing an expression of the form [`va[gs]`](../standard-library/valarray-class.md#op_at). The member functions of class `gslice_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. -The class template is created indirectly by certain valarray operations and cannot be used directly in the program. An internal auxiliary class template instead is used by the slice subscript operator: +The class template is created indirectly by certain `valarray` operations and can't be used directly in the program. An internal auxiliary class template instead is used by the `slice` subscript operator: `gslice_array valarray::operator[]( const gslice& )`. -You construct a `gslice_array` object only by writing an expression of the form `va[gsl]`, for a slice `gsl` of valarray `va`. The member functions of class gslice_array then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. The sequence controlled by the gslice_array is defined by the three parameters of the slice constructor, the index of the first element in the first slice, the number of elements in each slice, and the distance between the elements in each slice. +You construct a `gslice_array` object only by writing an expression of the form `va[gsl]`, for a `slice` `gsl` of `valarray` `va`. The member functions of class `gslice_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. The sequence controlled by the `gslice_array` is defined by the three parameters of the `slice` constructor, the index of the first element in the first `slice`, the number of elements in each `slice`, and the distance between the elements in each `slice`. In the following example: @@ -72,14 +72,14 @@ The indices must be valid for the procedure to be valid. ## Example -See the example for [gslice::gslice](../standard-library/gslice-class.md#gslice) for an example of how to declare and use a slice_array. +See the example for [`gslice::gslice`](../standard-library/gslice-class.md#gslice) for an example of how to declare and use a slice_array. ## Requirements **Header:** \ -**Namespace:** std +**Namespace:** `std` ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/gslice-class.md b/docs/standard-library/gslice-class.md index a70fef1eb2..f001992928 100644 --- a/docs/standard-library/gslice-class.md +++ b/docs/standard-library/gslice-class.md @@ -1,18 +1,18 @@ --- description: "Learn more about: gslice Class" -title: "gslice Class" -ms.date: "11/04/2016" +title: "gslice class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::gslice", "valarray/std::gslice::size", "valarray/std::gslice::start", "valarray/std::gslice::stride"] helpviewer_keywords: ["std::gslice [C++]", "std::gslice [C++], size", "std::gslice [C++], start", "std::gslice [C++], stride"] ms.assetid: f47cffd0-ea59-4b13-848b-7a5ce1d7e2a3 --- -# gslice Class +# `gslice` class -A utility class to valarray that is used to define multidimensional subsets of a valarray. If a valarray is regarded as a multidimensional matrix with all elements in an array, then the slice extracts a vector out of the multidimensional array. +A utility class to `valarray` that is used to define multidimensional subsets of a `valarray`. If a `valarray` is regarded as a multidimensional matrix with all elements in an array, then the `gslice` extracts a vector out of the multidimensional array. ## Remarks -The class stores the parameters that characterize an object of type [gslice_array](../standard-library/gslice-array-class.md). The subset of a valarray is indirectly constructed when an object of class gslice appears as an argument for an object of class [valarray](../standard-library/valarray-class.md#op_at)**\**. The stored values that specify the subset selected from the parent valarray include: +The class stores the parameters that characterize an object of type [`gslice_array`](../standard-library/gslice-array-class.md). The subset of a `valarray` is indirectly constructed when an object of class `gslice` appears as an argument for an object of class [`valarray`](../standard-library/valarray-class.md#op_at). The stored values that specify the subset selected from the parent `valarray` include: - A starting index. @@ -22,23 +22,23 @@ The class stores the parameters that characterize an object of type [gslice_arra The two vectors must have the same length. -If the set defined by a gslice is the subset of a constant valarray, then the gslice is a new valarray. If the set defined by a gslice is the subset of a nonconstant valarray, then the gslice has reference semantics to the original valarray. The evaluation mechanism for nonconstant valarrays saves time and memory. +If the set defined by a `gslice` is the subset of a constant `valarray`, then the `gslice` is a new `valarray`. If the set defined by a `gslice` is the subset of a nonconstant `valarray`, then the `gslice` has reference semantics to the original `valarray`. The evaluation mechanism for nonconstant `valarray` objects saves time and memory. -Operations on valarrays are guaranteed only if the source and destination subsets defined by the gslices are distinct and all indices are valid. +Operations on `valarray` objects are guaranteed only if the source and destination subsets defined by the `gslice` objects are distinct and all indices are valid. ### Constructors -|Constructor|Description| -|-|-| -|[gslice](#gslice)|Defines a subset of a `valarray` that consists of multiple slices of the `valarray` that all start at a specified element.| +| Constructor | Description | +|--|--| +| [`gslice`](#gslice) | Defines a subset of a `valarray` that consists of multiple slices of the `valarray` that all start at a specified element. | ### Member functions -|Member function|Description| -|-|-| -|[size](#size)|Finds the array values specifying the numbers of elements in a general slice of a `valarray`.| -|[start](#start)|Finds the starting index of a general slice of a `valarray`.| -|[stride](#stride)|Finds the distance between elements in a general slice of a `valarray`.| +| Member function | Description | +|--|--| +| [`size`](#size) | Finds the array values specifying the numbers of elements in a general slice of a `valarray`. | +| [`start`](#start) | Finds the starting index of a general slice of a `valarray`. | +| [`stride`](#stride) | Finds the distance between elements in a general slice of a `valarray`. | ## Requirements @@ -46,9 +46,9 @@ Operations on valarrays are guaranteed only if the source and destination subset **Namespace:** std -## gslice::gslice +## `gslice::gslice` -A utility class to valarray that is used to define multi-dimensional slices of a valarray. +A utility class to `valarray` that is used to define multi-dimensional slices of a `valarray`. ```cpp gslice(); @@ -61,22 +61,22 @@ gslice( ### Parameters -*_StartIndex*\ -The valarray index of the first element in the subset. +*`_StartIndex`*\ +The `valarray` index of the first element in the subset. -*_LenArray*\ -An array specifying the number of elements in each slice. +*`_LenArray`*\ +A `valarray` specifying the number of elements in each `gslice`. -*_IncArray*\ -An array specifying the stride in each slice. +*`_IncArray`*\ +A `valarray` specifying the stride in each `gslice`. -### Return Value +### Return value -The default constructor stores zero for the starting index, and zero-length vectors for the length and stride vectors. The second constructor stores *_StartIndex* for the starting index, *_LenArray* for the length array, and *_IncArray* for the stride array. +The default constructor stores zero for the starting index, and zero-length vectors for the length and stride vectors. The second constructor stores *`_StartIndex`* for the starting index, *`_LenArray`* for the length array, and *`_IncArray`* for the stride array. ### Remarks -**gslice** defines a subset of a valarray that consists of multiple slices of the valarray that each start at the same specified element. The ability to use arrays to define multiple slices is the only difference between `gslice` and [slice::slice](../standard-library/slice-class.md#slice). The first slice has a first element with an index of *_StartIndex*, a number of elements specified by the first element of *_LenArray*, and a stride given by the first element of *_IncArray*. The next set of orthogonal slices has first elements given by the first slice. The second element of *_LenArray* specifies the number of elements. The stride is given by the second element of *_IncArray*. A third dimension of slices would take the elements of the two-dimensional array as the starting elements and proceed analogously +`gslice` defines a subset of a `valarray` that consists of multiple slices of the `valarray` that each start at the same specified element. The ability to use arrays to define multiple slices is the only difference between `gslice` and [`slice::slice`](../standard-library/slice-class.md#slice). The first slice has a first element with an index of *`_StartIndex`*, a count of elements specified by the first element of *`_LenArray`*, and a stride given by the first element of *`_IncArray`*. The next set of orthogonal slices has first elements given by the first slice. The second element of *`_LenArray`* specifies the number of elements. The stride is given by the second element of *`_IncArray`*. A third dimension of slices would take the elements of the two-dimensional array as the starting elements and continue analogously. ### Example @@ -125,17 +125,17 @@ The valarray for vaGSlice is vaResult: va[vaGSlice] = ( 0 4 8 12 7 11 15 19) ``` -## gslice::size +## `gslice::size` -Finds the array values specifying the numbers of elements in a general slice of a valarray. +Finds the array values specifying the numbers of elements in a general slice of a `valarray`. ```cpp valarray size() const; ``` -### Return Value +### Return value -A valarray specifying the number of elements in each slice of a general slice of a valarray. +A `valarray` specifying the number of elements in each slice of a general slice of a `valarray`. ### Remarks @@ -203,17 +203,17 @@ The size of vaResult is: vaGSlice.size ( ) = ( 4 4 ). ``` -## gslice::start +## `gslice::start` -Finds the starting index of a general slice of a valarray. +Finds the starting index of a general slice of a `valarray`. ```cpp size_t start() const; ``` -### Return Value +### Return value -The starting index of a general slice of a valarray. +The starting index of a general slice of a `valarray`. ### Example @@ -266,17 +266,17 @@ va[vaGSlice] = ( 0 4 8 12 7 11 15 19 ). The index of the first element of vaResult is: 0. ``` -## gslice::stride +## `gslice::stride` -Finds the distance between elements in a general slice of a valarray. +Finds the distance between elements in a general slice of a `valarray`. ```cpp valarray stride() const; ``` -### Return Value +### Return value -A valarray specifying the distances between elements in each slice of a general slice of a valarray. +A `valarray` specifying the distances between elements in each slice of a general slice of a `valarray`. ### Example @@ -336,4 +336,4 @@ vaGSlice.stride ( ) = ( 7 4 ). ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/hash-compare-class.md b/docs/standard-library/hash-compare-class.md index 35008b665d..dde3f260d6 100644 --- a/docs/standard-library/hash-compare-class.md +++ b/docs/standard-library/hash-compare-class.md @@ -12,8 +12,9 @@ The class template describes an object that can be used by any of the hash assoc ## Syntax +```cpp class hash_compare - { +{ Traits comp; public: const size_t bucket_size = 4; @@ -24,7 +25,8 @@ class hash_compare bool operator()( const Key& key1, const Key& key2) const; - }; +}; +``` ## Remarks diff --git a/docs/standard-library/hash-map-class.md b/docs/standard-library/hash-map-class.md index 08190869e1..61f681bca0 100644 --- a/docs/standard-library/hash-map-class.md +++ b/docs/standard-library/hash-map-class.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: hash_map Class" title: "hash_map Class" -ms.date: "11/04/2016" +description: "Learn more about: hash_map Class" +ms.date: 11/04/2016 f1_keywords: ["hash_map/stdext::hash_map", "hash_map/stdext::hash_map::allocator_type", "hash_map/stdext::hash_map::const_iterator", "hash_map/stdext::hash_map::const_pointer", "hash_map/stdext::hash_map::const_reference", "hash_map/stdext::hash_map::const_reverse_iterator", "hash_map/stdext::hash_map::difference_type", "hash_map/stdext::hash_map::iterator", "hash_map/stdext::hash_map::key_compare", "hash_map/stdext::hash_map::key_type", "hash_map/stdext::hash_map::mapped_type", "hash_map/stdext::hash_map::pointer", "hash_map/stdext::hash_map::reference", "hash_map/stdext::hash_map::reverse_iterator", "hash_map/stdext::hash_map::size_type", "hash_map/stdext::hash_map::value_type", "hash_map/stdext::hash_map::at", "hash_map/stdext::hash_map::begin", "hash_map/stdext::hash_map::cbegin", "hash_map/stdext::hash_map::cend", "hash_map/stdext::hash_map::clear", "hash_map/stdext::hash_map::count", "hash_map/stdext::hash_map::crbegin", "hash_map/stdext::hash_map::crend", "hash_map/stdext::hash_map::emplace", "hash_map/stdext::hash_map::emplace_hint", "hash_map/stdext::hash_map::empty", "hash_map/stdext::hash_map::end", "hash_map/stdext::hash_map::equal_range", "hash_map/stdext::hash_map::erase", "hash_map/stdext::hash_map::find", "hash_map/stdext::hash_map::get_allocator", "hash_map/stdext::hash_map::insert", "hash_map/stdext::hash_map::key_comp", "hash_map/stdext::hash_map::lower_bound", "hash_map/stdext::hash_map::max_size", "hash_map/stdext::hash_map::rbegin", "hash_map/stdext::hash_map::rend", "hash_map/stdext::hash_map::size", "hash_map/stdext::hash_map::swap", "hash_map/stdext::hash_map::upper_bound", "hash_map/stdext::hash_map::value_comp"] helpviewer_keywords: ["stdext::hash_map", "stdext::hash_map::allocator_type", "stdext::hash_map::const_iterator", "stdext::hash_map::const_pointer", "stdext::hash_map::const_reference", "stdext::hash_map::const_reverse_iterator", "stdext::hash_map::difference_type", "stdext::hash_map::iterator", "stdext::hash_map::key_compare", "stdext::hash_map::key_type", "stdext::hash_map::mapped_type", "stdext::hash_map::pointer", "stdext::hash_map::reference", "stdext::hash_map::reverse_iterator", "stdext::hash_map::size_type", "stdext::hash_map::value_type", "stdext::hash_map::at", "stdext::hash_map::begin", "stdext::hash_map::cbegin", "stdext::hash_map::cend", "stdext::hash_map::clear", "stdext::hash_map::count", "stdext::hash_map::crbegin", "stdext::hash_map::crend", "stdext::hash_map::emplace", "stdext::hash_map::emplace_hint", "stdext::hash_map::empty", "stdext::hash_map::end", "stdext::hash_map::equal_range", "stdext::hash_map::erase", "stdext::hash_map::find", "stdext::hash_map::get_allocator", "stdext::hash_map::insert", "stdext::hash_map::key_comp", "stdext::hash_map::lower_bound", "stdext::hash_map::max_size", "stdext::hash_map::rbegin", "stdext::hash_map::rend", "stdext::hash_map::size", "stdext::hash_map::swap", "stdext::hash_map::upper_bound", "stdext::hash_map::value_comp"] -ms.assetid: 40879dfc-51ba-4a59-9f9e-26208de568a8 --- -# hash_map Class +# `hash_map` Class > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). Stores and retrieves data quickly from a collection in which each element is a pair that has a sort key whose value is unique and an associated data value. @@ -25,21 +24,21 @@ class hash_map ### Parameters -*Key*\ -The key data type to be stored in the hash_map. +*`Key`*\ +The key data type to be stored in the `hash_map`. -*Type*\ -The element data type to be stored in the hash_map. +*`Type`*\ +The element data type to be stored in the `hash_map`. -*Traits*\ -The type which includes two function objects, one of class compare able to compare two element values as sort keys to determine their relative order and a hash function that is a unary predicate mapping key values of the elements to unsigned integers of type `size_t`. This argument is optional, and hash_compare<`Key`, less<`Key`> > is the default value. +*`Traits`*\ +The type that includes two function objects, one of class compare able to compare two element values as sort keys to determine their relative order and a hash function that is a unary predicate mapping key values of the elements to unsigned integers of type `size_t`. This argument is optional, and `hash_compare>` is the default value. -*Allocator*\ -The type that represents the stored allocator object that encapsulates details about the hash_map's allocation and deallocation of memory. This argument is optional, and the default value is allocator\>. +*`Allocator`*\ +The type that represents the stored allocator object that encapsulates details about the `hash_map`'s allocation and deallocation of memory. This argument is optional, and the default value is `allocator>`. ## Remarks -The hash_map is: +The `hash_map` is: - An associative container, which a variable size container that supports the efficient retrieval of element values based on an associated key value. @@ -53,94 +52,94 @@ The hash_map is: - A class template, because the functionality it provides is generic and so independent of the specific type of data contained as elements or keys. The data types to be used for elements and keys are, instead, specified as parameters in the class template along with the comparison function and allocator. -The main advantage of hashing over sorting is greater efficiency; a successful hashing performs insertions, deletions, and finds in constant average time as compared with a time proportional to the logarithm of the number of elements in the container for sorting techniques. The value of an element in a hash_map, but not its associated key value, may be changed directly. Instead, key values associated with old elements must be deleted and new key values associated with new elements inserted. +The main advantage of hashing over sorting is greater efficiency; a successful hashing performs insertions, deletions, and finds in constant average time as compared with a time proportional to the logarithm of the number of elements in the container for sorting techniques. The value of an element in a `hash_map`, but not its associated key value, may be changed directly. Instead, key values associated with old elements must be deleted and new key values associated with new elements inserted. The choice of container type should be based in general on the type of searching and inserting required by the application. Hashed associative containers are optimized for the operations of lookup, insertion and removal. The member functions that explicitly support these operations are efficient when used with a well-designed hash function, performing them in a time that is on average constant and not dependent on the number of elements in the container. A well-designed hash function produces a uniform distribution of hashed values and minimizes the number of collisions, where a collision is said to occur when distinct key values are mapped into the same hashed value. In the worst case, with the worst possible hash function, the number of operations is proportional to the number of elements in the sequence (linear time). -The hash_map should be the associative container of choice when the conditions associating the values with their keys are satisfied by the application. A model for this type of structure is an ordered list of uniquely occurring keywords with associated string values providing, say, definitions. If, instead, the words had more than one correct definition, so that keys were not unique, then a hash_multimap would be the container of choice. If, on the other hand, just the list of words were being stored, then a hash_set would be the correct container. If multiple occurrences of the words were allowed, then a hash_multiset would be the appropriate container structure. +The `hash_map` should be the associative container of choice when the conditions associating the values with their keys are satisfied by the application. A model for this type of structure is an ordered list of uniquely occurring keywords with associated string values providing, say, definitions. If, instead, the words had more than one correct definition, so that keys weren't unique, then a `hash_multimap` would be the container of choice. If, on the other hand, just the list of words were being stored, then a `hash_set` would be the correct container. If multiple occurrences of the words were allowed, then a `hash_multiset` would be the appropriate container structure. -The hash_map orders the sequence it controls by calling a stored hash *Traits* object of class [value_compare](../standard-library/value-compare-class.md). This stored object may be accessed by calling the member function [key_comp](#key_comp). Such a function object must behave the same as an object of class [hash_compare](../standard-library/hash-compare-class.md)>. Specifically, for all values *Key* of type *Key*, the call `Traits`( `Key` ) yields a distribution of values of type `size_t`. +The `hash_map` orders the sequence it controls by calling a stored hash *`Traits`* object of class [`value_compare`](../standard-library/value-compare-class.md). This stored object may be accessed by calling the member function [`key_comp`](#key_comp). Such a function object must behave the same as an object of class `hash_compare>`. Specifically, for all values *`Key`* of type *`Key`*, the call `Traits`(`Key`) yields a distribution of values of type `size_t`. For more information, see [`hash_compare`](../standard-library/hash-compare-class.md). -In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate f(x y) is a function object that has two argument objects `x` and `y` and a return value of **`true`** or **`false`**. An ordering imposed on a hash_map is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects x and y are defined to be equivalent when both f(x, y) and f(y, x) are false. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. +In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they're equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate f(x y) is a function object that has two argument objects `x` and `y` and a return value of **`true`** or **`false`**. An ordering imposed on a `hash_map` is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects `x` and `y` are defined to be equivalent when both f(x, y) and f(y, x) are `false`. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. -The actual order of elements in the controlled sequence depends on the hash function, the ordering function, and the current size of the hash table stored in the container object. You cannot determine the current size of the hash table, so you cannot in general predict the order of elements in the controlled sequence. Inserting elements invalidates no iterators, and removing elements invalidates only those iterators that had specifically pointed at the removed elements. +The actual order of elements in the controlled sequence depends on the hash function, the ordering function, and the current size of the hash table stored in the container object. You can't determine the current size of the hash table, so you can't in general predict the order of elements in the controlled sequence. Inserting elements invalidates no iterators, and removing elements invalidates only those iterators that had specifically pointed at the removed elements. -The iterator provided by the hash_map class is a bidirectional iterator, but the class member functions [insert](#insert) and [hash_map](#hash_map) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements, and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it is enough to be able to talk meaningfully about a range of iterators `[First, Last)` in the context of the class member functions. +The iterator provided by the `hash_map` class is a bidirectional iterator, but the class member functions [`insert`](#insert) and [`hash_map`](#hash_map) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements, and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it's enough to be able to talk meaningfully about a range of iterators `[First, Last)` in the context of the class member functions. ### Constructors |Constructor|Description| |-|-| -|[hash_map](#hash_map)|Constructs a `hash_map` that is empty or that is a copy of all or part of some other `hash_map`.| +|[`hash_map`](#hash_map)|Constructs a `hash_map` that is empty or that is a copy of all or part of some other `hash_map`.| ### Typedefs |Type name|Description| |-|-| -|[allocator_type](#allocator_type)|A type that represents the `allocator` class for the `hash_map` object.| -|[const_iterator](#const_iterator)|A type that provides a bidirectional iterator that can read a **`const`** element in the `hash_map`.| -|[const_pointer](#const_pointer)|A type that provides a pointer to a **`const`** element in a `hash_map`.| -|[const_reference](#const_reference)|A type that provides a reference to a **`const`** element stored in a `hash_map` for reading and performing **`const`** operations.| -|[const_reverse_iterator](#const_reverse_iterator)|A type that provides a bidirectional iterator that can read any **`const`** element in the `hash_map`.| -|[difference_type](#difference_type)|A signed integer type that can be used to represent the number of elements of a `hash_map` in a range between elements pointed to by iterators.| -|[iterator](#iterator)|A type that provides a bidirectional iterator that can read or modify any element in a `hash_map`.| -|[key_compare](#key_compare)|A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the `hash_map`.| -|[key_type](#key_type)|A type describes the sort key object that constitutes each element of the `hash_map`.| -|[mapped_type](#mapped_type)|A type that represents the data type stored in a `hash_map`.| -|[pointer](#pointer)|A type that provides a pointer to an element in a `hash_map`.| -|[reference](#reference)|A type that provides a reference to an element stored in a `hash_map`.| -|[reverse_iterator](#reverse_iterator)|A type that provides a bidirectional iterator that can read or modify an element in a reversed `hash_map`.| -|[size_type](#size_type)|An unsigned integer type that can represent the number of elements in a `hash_map`.| -|[value_type](#value_type)|A type that provides a function object that can compare two elements as sort keys to determine their relative order in the `hash_map`.| +|[`allocator_type`](#allocator_type)|A type that represents the `allocator` class for the `hash_map` object.| +|[`const_iterator`](#const_iterator)|A type that provides a bidirectional iterator that can read a **`const`** element in the `hash_map`.| +|[`const_pointer`](#const_pointer)|A type that provides a pointer to a **`const`** element in a `hash_map`.| +|[`const_reference`](#const_reference)|A type that provides a reference to a **`const`** element stored in a `hash_map` for reading and performing **`const`** operations.| +|[`const_reverse_iterator`](#const_reverse_iterator)|A type that provides a bidirectional iterator that can read any **`const`** element in the `hash_map`.| +|[`difference_type`](#difference_type)|A signed integer type that can be used to represent the number of elements of a `hash_map` in a range between elements pointed to by iterators.| +|[`iterator`](#iterator)|A type that provides a bidirectional iterator that can read or modify any element in a `hash_map`.| +|[`key_compare`](#key_compare)|A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the `hash_map`.| +|[`key_type`](#key_type)|A type describes the sort key object that constitutes each element of the `hash_map`.| +|[`mapped_type`](#mapped_type)|A type that represents the data type stored in a `hash_map`.| +|[`pointer`](#pointer)|A type that provides a pointer to an element in a `hash_map`.| +|[`reference`](#reference)|A type that provides a reference to an element stored in a `hash_map`.| +|[`reverse_iterator`](#reverse_iterator)|A type that provides a bidirectional iterator that can read or modify an element in a reversed `hash_map`.| +|[`size_type`](#size_type)|An unsigned integer type that can represent the number of elements in a `hash_map`.| +|[`value_type`](#value_type)|A type that provides a function object that can compare two elements as sort keys to determine their relative order in the `hash_map`.| ### Member functions |Member function|Description| |-|-| -|[at](#at)|Finds an element in a `hash_map` with a specified key value.| -|[begin](#begin)|Returns an iterator addressing the first element in the `hash_map`.| -|[cbegin](#cbegin)|Returns a const iterator addressing the first element in the `hash_map`.| -|[cend](#cend)|Returns a const iterator that addresses the location succeeding the last element in a `hash_map`.| -|[clear](#clear)|Erases all the elements of a `hash_map`.| -|[count](#count)|Returns the number of elements in a `hash_map` whose key matches a parameter-specified key.| -|[crbegin](#crbegin)|Returns a const iterator addressing the first element in a reversed `hash_map`.| -|[crend](#crend)|Returns a const iterator that addresses the location succeeding the last element in a reversed `hash_map`.| -|[emplace](#emplace)|Inserts an element constructed in place into a `hash_map`.| -|[emplace_hint](#emplace_hint)|Inserts an element constructed in place into a `hash_map`, with a placement hint.| -|[empty](#empty)|Tests if a `hash_map` is empty.| -|[end](#end)|Returns an iterator that addresses the location succeeding the last element in a `hash_map`.| -|[equal_range](#equal_range)|Returns a pair of iterators, respectively, to the first element in a `hash_map` with a key that is greater than a specified key and to the first element in the `hash_map` with a key that is equal to or greater than the key.| -|[erase](#erase)|Removes an element or a range of elements in a `hash_map` from specified positions| -|[find](#find)|Returns an iterator addressing the location of an element in a `hash_map` that has a key equivalent to a specified key.| -|[get_allocator](#get_allocator)|Returns a copy of the `allocator` object used to construct the `hash_map`.| -|[insert](#insert)|Inserts an element or a range of elements into a `hash_map`.| -|[key_comp](#key_comp)|Returns an iterator to the first element in a `hash_map` with a key value that is equal to or greater than that of a specified key.| -|[lower_bound](#lower_bound)|Returns an iterator to the first element in a `hash_map` with a key value that is equal to or greater than that of a specified key.| -|[max_size](#max_size)|Returns the maximum length of the `hash_map`.| -|[rbegin](#rbegin)|Returns an iterator addressing the first element in a reversed `hash_map`.| -|[rend](#rend)|Returns an iterator that addresses the location succeeding the last element in a reversed `hash_map`.| -|[size](#size)|Returns the number of elements in the `hash_map`.| -|[swap](#swap)|Exchanges the elements of two `hash_map`s.| -|[upper_bound](#upper_bound)|Returns an iterator to the first element in a `hash_map` that with a key value that is greater than that of a specified key.| -|[value_comp](#value_comp)|Retrieves a copy of the comparison object used to order element values in a `hash_map`.| +|[`at`](#at)|Finds an element in a `hash_map` with a specified key value.| +|[`begin`](#begin)|Returns an iterator addressing the first element in the `hash_map`.| +|[`cbegin`](#cbegin)|Returns a const iterator addressing the first element in the `hash_map`.| +|[`cend`](#cend)|Returns a const iterator that addresses the location succeeding the last element in a `hash_map`.| +|[`clear`](#clear)|Erases all the elements of a `hash_map`.| +|[`count`](#count)|Returns the number of elements in a `hash_map` whose key matches a parameter-specified key.| +|[`crbegin`](#crbegin)|Returns a `const` iterator addressing the first element in a reversed `hash_map`.| +|[`crend`](#crend)|Returns a `const` iterator that addresses the location succeeding the last element in a reversed `hash_map`.| +|[`emplace`](#emplace)|Inserts an element constructed in place into a `hash_map`.| +|[`emplace_hint`](#emplace_hint)|Inserts an element constructed in place into a `hash_map`, with a placement hint.| +|[`empty`](#empty)|Tests if a `hash_map` is empty.| +|[`end`](#end)|Returns an iterator that addresses the location succeeding the last element in a `hash_map`.| +|[`equal_range`](#equal_range)|Returns a pair of iterators, respectively, to the first element in a `hash_map` with a key that is greater than a specified key and to the first element in the `hash_map` with a key that is equal to or greater than the key.| +|[`erase`](#erase)|Removes an element or a range of elements in a `hash_map` from specified positions| +|[`find`](#find)|Returns an iterator addressing the location of an element in a `hash_map` that has a key equivalent to a specified key.| +|[`get_allocator`](#get_allocator)|Returns a copy of the `allocator` object used to construct the `hash_map`.| +|[`insert`](#insert)|Inserts an element or a range of elements into a `hash_map`.| +|[`key_comp`](#key_comp)|Returns an iterator to the first element in a `hash_map` with a key value that is equal to or greater than that of a specified key.| +|[`lower_bound`](#lower_bound)|Returns an iterator to the first element in a `hash_map` with a key value that is equal to or greater than that of a specified key.| +|[`max_size`](#max_size)|Returns the maximum length of the `hash_map`.| +|[`rbegin`](#rbegin)|Returns an iterator addressing the first element in a reversed `hash_map`.| +|[`rend`](#rend)|Returns an iterator that addresses the location succeeding the last element in a reversed `hash_map`.| +|[`size`](#size)|Returns the number of elements in the `hash_map`.| +|[`swap`](#swap)|Exchanges the elements of two `hash_map`s.| +|[`upper_bound`](#upper_bound)|Returns an iterator to the first element in a `hash_map` that with a key value that is greater than that of a specified key.| +|[`value_comp`](#value_comp)|Retrieves a copy of the comparison object used to order element values in a `hash_map`.| ### Operators |Operator|Description| |-|-| |[`operator[]`](#op_at)|Inserts an element into a `hash_map` with a specified key value.| -|[hash_map::operator=](#op_eq)|Replaces the elements of a `hash_map` with a copy of another `hash_map`.| +|[`hash_map::operator=`](#op_eq)|Replaces the elements of a `hash_map` with a copy of another `hash_map`.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** stdext +**Namespace:** `stdext` -## hash_map::allocator_type +## `hash_map::allocator_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). A type that represents the allocator class for the hash_map object. @@ -150,14 +149,14 @@ typedef list::allo ### Example -See example for [get_allocator](#get_allocator) for an example using `allocator_type`. +See example for [`get_allocator`](#get_allocator) for an example using `allocator_type`. -## hash_map::at +## `hash_map::at` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Finds an element in a hash_map with a specified key value. +Finds an element in a `hash_map` with a specified key value. ```cpp Type& at(const Key& key); @@ -167,7 +166,7 @@ const Type& at(const Key& key) const; ### Parameters -*key*\ +*`key`*\ The key value of the element that is to be found. ### Return Value @@ -176,7 +175,7 @@ A reference to the data value of the element found. ### Remarks -If the argument key value is not found, then the function throws an object of class [out_of_range Class](../standard-library/out-of-range-class.md). +If the argument key value isn't found, then the function throws an object of class [`out_of_range` Class](../standard-library/out-of-range-class.md). ### Example @@ -205,12 +204,12 @@ int main( ) } ``` -## hash_map::begin +## `hash_map::begin` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator addressing the first element in the hash_map. +Returns an iterator addressing the first element in the `hash_map`. ```cpp const_iterator begin() const; @@ -220,7 +219,7 @@ iterator begin(); ### Return Value -A bidirectional iterator addressing the first element in the hash_map or the location succeeding an empty hash_map. +A bidirectional iterator addressing the first element in the `hash_map` or the location succeeding an empty `hash_map`. ### Example @@ -266,12 +265,12 @@ The first element of hm1 is 0. The first element of hm1 is now 1. ``` -## hash_map::cbegin +## `hash_map::cbegin` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a const iterator addressing the first element in the hash_map. +Returns a const iterator addressing the first element in the `hash_map`. ```cpp const_iterator cbegin() const; @@ -279,7 +278,7 @@ const_iterator cbegin() const; ### Return Value -A const bidirectional iterator addressing the first element in the [hash_map](../standard-library/hash-map-class.md) or the location succeeding an empty `hash_map`. +A const bidirectional iterator addressing the first element in the [`hash_map`](../standard-library/hash-map-class.md) or the location succeeding an empty `hash_map`. ### Example @@ -310,12 +309,12 @@ int main( ) The first element of hm1 is 2. ``` -## hash_map::cend +## `hash_map::cend` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a const iterator that addresses the location succeeding the last element in a hash_map. +Returns a const iterator that addresses the location succeeding the last element in a `hash_map`. ```cpp const_iterator cend() const; @@ -323,13 +322,13 @@ const_iterator cend() const; ### Return Value -A const bidirectional iterator that addresses the location succeeding the last element in a [hash_map](../standard-library/hash-map-class.md). If the `hash_map` is empty, then `hash_map::cend == hash_map::begin`. +A const bidirectional iterator that addresses the location succeeding the last element in a [`hash_map`](../standard-library/hash-map-class.md). If the `hash_map` is empty, then `hash_map::cend == hash_map::begin`. ### Remarks `cend` is used to test whether an iterator has reached the end of its `hash_map`. -The value returned by `cend` should not be dereferenced. +The value returned by `cend` shouldn't be dereferenced. ### Example @@ -361,12 +360,12 @@ int main( ) The value of last element of hm1 is 30. ``` -## hash_map::clear +## `hash_map::clear` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Erases all the elements of a hash_map. +Erases all the elements of a `hash_map`. ```cpp void clear(); @@ -376,7 +375,7 @@ void clear(); ### Example -The following example demonstrates the use of the hash_map::clear member function. +The following example demonstrates the use of the `hash_map::clear` member function. ```cpp // hash_map_clear.cpp @@ -411,12 +410,12 @@ The size of the hash_map is initially 2. The size of the hash_map after clearing is 0. ``` -## hash_map::const_iterator +## `hash_map::const_iterator` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a bidirectional iterator that can read a **`const`** element in the hash_map. +A type that provides a bidirectional iterator that can read a **`const`** element in the `hash_map`. ```cpp typedef list::const_iterator const_iterator; @@ -424,24 +423,24 @@ typedef list::cons ### Remarks -A type `const_iterator` cannot be used to modify the value of an element. +A type `const_iterator` can't be used to modify the value of an element. -The `const_iterator` defined by hash_map points to elements that are objects of [value_type](#value_type), that is of type `pair< const Key, Type >`, whose first member is the key to the element and whose second member is the mapped datum held by the element. +The `const_iterator` defined by `hash_map` points to elements that are objects of [`value_type`](#value_type), that is of type `pair< const Key, Type >`, whose first member is the key to the element and whose second member is the mapped datum held by the element. -To dereference a `const_iterator` `cIter` pointing to an element in a hash_map, use the `->` operator. +To dereference a `const_iterator` `cIter` pointing to an element in a `hash_map`, use the `->` operator. To access the value of the key for the element, use `cIter->first`, which is equivalent to `(*cIter).first`. To access the value of the mapped datum for the element, use `cIter->second`, which is equivalent to `(*cIter).second`. ### Example -See example for [begin](#begin) for an example using `const_iterator`. +See example for [`begin`](#begin) for an example using `const_iterator`. -## hash_map::const_pointer +## `hash_map::const_pointer` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a pointer to a **`const`** element in a hash_map. +A type that provides a pointer to a **`const`** element in a `hash_map`. ```cpp typedef list::const_pointer const_pointer; @@ -449,16 +448,16 @@ typedef list::co ### Remarks -A type `const_pointer` cannot be used to modify the value of an element. +A type `const_pointer` can't be used to modify the value of an element. -In most cases, an [iterator](#iterator) should be used to access the elements in a hash_map object. +In most cases, an [`iterator`](#iterator) should be used to access the elements in a `hash_map` object. -## hash_map::const_reference +## `hash_map::const_reference` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a reference to a **`const`** element stored in a hash_map for reading and performing **`const`** operations. +A type that provides a reference to a **`const`** element stored in a `hash_map` for reading and performing **`const`** operations. ```cpp typedef list::const_reference const_reference; @@ -509,37 +508,38 @@ The key of the first element in the hash_map is 1. The data value of the first element in the hash_map is 10. ``` -## hash_map::const_reverse_iterator +## `hash_map::const_reverse_iterator` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a bidirectional iterator that can read any **`const`** element in the hash_map. +A type that provides a bidirectional iterator that can read any **`const`** element in the `hash_map`. ```cpp -typedef list::const_reverse)iterator const_reverse_iterator; +typedef list::const_reverse_iterator const_reverse_iterator; ``` ### Remarks -A type `const_reverse_iterator` cannot modify the value of an element and is use to iterate through the hash_map in reverse. +A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the `hash_map` in reverse. + +The `const_reverse_iterator` defined by `hash_map` points to elements that are objects of [`value_type`](#value_type), that is of type `pair< const Key, Type >`, whose first member is the key to the element and whose second member is the mapped datum held by the element. -The `const_reverse_iterator` defined by hash_map points to elements that are objects of [value_type](#value_type), that is of type `pair`\< **const Key, Type**>, whose first member is the key to the element and whose second member is the mapped datum held by the element. +To dereference a `const_reverse_iterator` `crIter` pointing to an element in a `hash_map`, use the `->` operator. -To dereference a `const_reverse_iterator` `crIter` pointing to an element in a hash_map, use the **->** operator. +To access the value of the key for the element, use `crIter->first`, which is equivalent to `(*crIter).first`. To access the value of the mapped datum for the element, use `crIter->second`, which is equivalent to `(*crIter).first`. -To access the value of the key for the element, use `crIter` -> **first**, which is equivalent to (\* `crIter`) **.first**. To access the value of the mapped datum for the element, use `crIter` -> **second**, which is equivalent to (\* `crIter`). **first**. ### Example -See the example for [rend](#rend) for an example of how to declare and use the `const_reverse_iterator`. +See the example for [`rend`](#rend) for an example of how to declare and use the `const_reverse_iterator`. -## hash_map::count +## `hash_map::count` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns the number of elements in a hash_map whose key matches a parameter-specified key. +Returns the number of elements in a `hash_map` whose key matches a parameter-specified key. ```cpp size_type count(const Key& key) const; @@ -547,24 +547,24 @@ size_type count(const Key& key) const; ### Parameters -*key*\ -The key value of the elements to be matched from the hash_map. +*`key`*\ +The key value of the elements to be matched from the `hash_map`. ### Return Value -1 if the hash_map contains an element whose sort key matches the parameter key; 0 if the hash_map doesn't contain an element with a matching key. +1 if the `hash_map` contains an element whose sort key matches the parameter key; 0 if the `hash_map` doesn't contain an element with a matching key. ### Remarks -The member function returns the number of elements *x* in the range +The member function returns the number of elements *`x`* in the range -\[ lower_bound(*key*), upper_bound(*key*) ) +[`lower_bound(key)`](#lower_bound), [`upper_bound(key)`](#upper_bound) -which is 0 or 1 in the case of hash_map, which is a unique associative container. +which is 0 or 1 in the case of `hash_map`, which is a unique associative container. ### Example -The following example demonstrates the use of the hash_map::count member function. +The following example demonstrates the use of the `hash_map::count` member function. ```cpp // hash_map_count.cpp @@ -606,12 +606,12 @@ The number of elements in hm1 with a sort key of 2 is: 1. The number of elements in hm1 with a sort key of 3 is: 0. ``` -## hash_map::crbegin +## `hash_map::crbegin` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a const iterator addressing the first element in a reversed hash_map. +Returns a `const` iterator addressing the first element in a reversed `hash_map`. ```cpp const_reverse_iterator crbegin() const; @@ -619,13 +619,13 @@ const_reverse_iterator crbegin() const; ### Return Value -A const reverse bidirectional iterator addressing the first element in a reversed [hash_map](../standard-library/hash-map-class.md) or addressing what had been the last element in the unreversed `hash_map`. +A `const` reverse bidirectional iterator addressing the first element in a reversed [`hash_map`](../standard-library/hash-map-class.md) or addressing what had been the last element in the unreversed `hash_map`. ### Remarks -`crbegin` is used with a reversed hash_map just as [begin](#begin) is used with a `hash_map`. +`crbegin` is used with a reversed `hash_map` just as [`begin`](#begin) is used with a `hash_map`. -With the return value of `crbegin`, the `hash_map` object cannot be modified. +With the return value of `crbegin`, the `hash_map` object can't be modified. `crbegin` can be used to iterate through a `hash_map` backwards. @@ -658,12 +658,12 @@ int main( ) The first element of the reversed hash_map hm1 is 3. ``` -## hash_map::crend +## `hash_map::crend` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a const iterator that addresses the location succeeding the last element in a reversed hash_map. +Returns a `const` iterator that addresses the location succeeding the last element in a reversed `hash_map`. ```cpp const_reverse_iterator crend() const; @@ -671,17 +671,17 @@ const_reverse_iterator crend() const; ### Return Value -A const reverse bidirectional iterator that addresses the location succeeding the last element in a reversed [hash_map](../standard-library/hash-map-class.md) (the location that had preceded the first element in the unreversed `hash_map`). +A `const` reverse bidirectional iterator that addresses the location succeeding the last element in a reversed [`hash_map`](../standard-library/hash-map-class.md) (the location that had preceded the first element in the unreversed `hash_map`). ### Remarks -`crend` is used with a reversed `hash_map` just as [hash_map::end](#end) is used with a `hash_map`. +`crend` is used with a reversed `hash_map` just as [`hash_map::end`](#end) is used with a `hash_map`. -With the return value of `crend`, the `hash_map` object cannot be modified. +With the return value of `crend`, the `hash_map` object can't be modified. `crend` can be used to test to whether a reverse iterator has reached the end of its `hash_map`. -The value returned by `crend` should not be dereferenced. +The value returned by `crend` shouldn't be dereferenced. ### Example @@ -713,12 +713,12 @@ int main( ) The last element of the reversed hash_map hm1 is 3. ``` -## hash_map::difference_type +## `hash_map::difference_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A signed integer type that can be used to represent the number of elements of a hash_map in a range between elements pointed to by iterators. +A signed integer type that can be used to represent the number of elements of a `hash_map` in a range between elements pointed to by iterators. ```cpp typedef list::difference_type difference_type; @@ -783,12 +783,12 @@ The keys of the mapped elements are: 1 2 3. The values of the mapped elements are: 10 20 20. ``` -## hash_map::emplace +## `hash_map::emplace` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Inserts an element constructed in place into a hash_map. +Inserts an element constructed in place into a `hash_map`. ```cpp template @@ -799,26 +799,26 @@ emplace( ### Parameters -*val*\ -The value used to move construct an element to be inserted into the [hash_map](../standard-library/hash-map-class.md) unless the `hash_map` already contains that element (or, more generally, an element whose key is equivalently ordered). +*`val`*\ +The value used to move construct an element to be inserted into the [`hash_map`](../standard-library/hash-map-class.md) unless the `hash_map` already contains that element (or, more generally, an element whose key is equivalently ordered). ### Return Value -The `emplace` member function returns a pair whose bool component returns true if an insertion was made and false if the `hash_map` already contained an element whose key had an equivalent value in the ordering, and whose iterator component returns the address where a new element was inserted or where the element was already located. +The `emplace` member function returns a pair whose `bool` component returns `true` if an insertion was made and `false` if the `hash_map` already contained an element whose key had an equivalent value in the ordering, and whose `iterator` component returns the address where a new element was inserted or where the element was already located. -To access the iterator component of a pair `pr` returned by this member function, use `pr.first`, and to dereference it, use `*(pr.first)`. To access the **`bool`** component of a pair `pr` returned by this member function, use `pr.second`, and to dereference it, use `*(pr.second)`. +To access the `iterator` component of a pair `pr` returned by this member function, use `pr.first`, and to dereference it, use `*(pr.first)`. To access the **`bool`** component of a pair `pr` returned by this member function, use `pr.second`, and to dereference it, use `*(pr.second)`. ### Remarks -The [hash_map::value_type](#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. +The [`hash_map::value_type`](#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. ### Example ```cpp // hash_map_emplace.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -841,12 +841,12 @@ After the emplace insertion, hm1 contains: 1 => a ``` -## hash_map::emplace_hint +## `hash_map::emplace_hint` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Inserts an element constructed in place into a hash_map, with a placement hint. +Inserts an element constructed in place into a `hash_map`, with a placement hint. ```cpp template @@ -857,29 +857,29 @@ iterator emplace_hint( ### Parameters -*val*\ -The value used to move construct an element to be inserted into the [hash_map](../standard-library/hash-map-class.md) unless the `hash_map` already contains that element (or, more generally, an element whose key is equivalently ordered). +*`val`*\ +The value used to move construct an element to be inserted into the [`hash_map`](../standard-library/hash-map-class.md) unless the `hash_map` already contains that element (or, more generally, an element whose key is equivalently ordered). -*_Where*\ +*`c`*\ A hint regarding the place to start searching for the correct point of insertion. ### Return Value -The [hash_multimap::emplace](../standard-library/hash-multimap-class.md#emplace) member function returns an iterator that points to the position where the new element was inserted into the `hash_map`, or where the existing element with equivalent ordering is located. +The [`hash_multimap::emplace`](../standard-library/hash-multimap-class.md#emplace) member function returns an iterator that points to the position where the new element was inserted into the `hash_map`, or where the existing element with equivalent ordering is located. ### Remarks -The [hash_map::value_type](#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. +The [`hash_map::value_type`](#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. -Insertion can occur in amortized constant time, instead of logarithmic time, if the insertion point immediately follows *_Where*. +Insertion can occur in amortized constant time, instead of logarithmic time, if the insertion point immediately follows *`_Where`*. ### Example ```cpp // hash_map_emplace_hint.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -902,12 +902,12 @@ After the emplace insertion, hm1 contains: 1 => a ``` -## hash_map::empty +## `hash_map::empty` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Tests if a hash_map is empty. +Tests if a `hash_map` is empty. ```cpp bool empty() const; @@ -915,7 +915,7 @@ bool empty() const; ### Return Value -**`true`** if the hash_map is empty; **`false`** if the hash_map is nonempty. +**`true`** if the `hash_map` is empty; **`false`** if the `hash_map` is nonempty. ### Remarks @@ -953,12 +953,12 @@ The hash_map hm1 is not empty. The hash_map hm2 is empty. ``` -## hash_map::end +## `hash_map::end` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator that addresses the location succeeding the last element in a hash_map. +Returns an iterator that addresses the location succeeding the last element in a `hash_map`. ```cpp const_iterator end() const; @@ -968,13 +968,13 @@ iterator end(); ### Return Value -A bidirectional iterator that addresses the location succeeding the last element in a hash_map. If the hash_map is empty, then hash_map::end == hash_map::begin. +A bidirectional iterator that addresses the location succeeding the last element in a `hash_map`. If the `hash_map` is empty, then `hash_map::end == hash_map::begin`. ### Remarks -`end` is used to test whether an iterator has reached the end of its hash_map. +`end` is used to test whether an iterator has reached the end of its `hash_map`. -The value returned by `end` should not be dereferenced. +The value returned by `end` shouldn't be dereferenced. ### Example @@ -1024,12 +1024,12 @@ The value of last element of hm1 is 30. The value of last element of hm1 is now 20. ``` -## hash_map::equal_range +## `hash_map::equal_range` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a pair of iterators respectively to the first element in a hash_map with a key that is greater than a specified key and to the first element in the hash_map with a key that is equal to or greater than the key. +Returns a pair of iterators respectively to the first element in a `hash_map` with a key that is greater than a specified key and to the first element in the `hash_map` with a key that is equal to or greater than the key. ```cpp pair equal_range (const Key& key) const; @@ -1039,14 +1039,14 @@ pair equal_range (const Key& key); ### Parameters -*key*\ -The argument key value to be compared with the sort key of an element from the hash_map being searched. +*`key`*\ +The argument key value to be compared with the sort key of an element from the `hash_map` being searched. ### Return Value -A pair of iterators such that the first is the [lower_bound](#lower_bound) of the key and the second is the [upper_bound](#upper_bound) of the key. +A pair of iterators such that the first is the [`lower_bound`](#lower_bound) of the key and the second is the [`upper_bound`](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr.first` and to dereference the lower bound iterator, use `*(pr.first)`. To access the second iterator of a pair `pr` returned by the member function, use `pr.second` and to dereference the upper bound iterator, use `*(pr.second)`. ### Remarks @@ -1111,12 +1111,12 @@ matching the 2nd element of the pair returned by equal_range( 2 ). The hash_map hm1 doesn't have an element with a key less than 40. ``` -## hash_map::erase +## `hash_map::erase` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Removes an element or a range of elements in a hash_map from specified positions or removes elements that match a specified key. +Removes an element or a range of elements in a `hash_map` from specified positions or removes elements that match a specified key. ```cpp iterator erase(iterator _Where); @@ -1128,23 +1128,23 @@ size_type erase(const key_type& key); ### Parameters -*_Where*\ -Position of the element to be removed from the hash_map. +*`_Where`*\ +Position of the element to be removed from the `hash_map`. -*first*\ -Position of the first element removed from the hash_map. +*`first`*\ +Position of the first element removed from the `hash_map`. -*last*\ -Position just beyond the last element removed from the hash_map. +*`last`*\ +Position just beyond the last element removed from the `hash_map`. -*key*\ -The key value of the elements to be removed from the hash_map. +*`key`*\ +The key value of the elements to be removed from the `hash_map`. ### Return Value -For the first two member functions, a bidirectional iterator that designates the first element remaining beyond any elements removed, or a pointer to the end of the hash_map if no such element exists. +For the first two member functions, a bidirectional iterator that designates the first element remaining beyond any elements removed, or a pointer to the end of the `hash_map` if no such element exists. -For the third member function, returns the number of elements that have been removed from the hash_map. +For the third member function, returns the number of elements that have been removed from the `hash_map`. ### Remarks @@ -1152,7 +1152,7 @@ The member functions never throw an exception. ### Example -The following example demonstrates the use of the hash_map::erase member function. +The following example demonstrates the use of the `hash_map::erase` member function. ```cpp // hash_map_erase.cpp @@ -1235,12 +1235,12 @@ After another element with a key equal to that of the 2nd element is deleted, the hash_map hm3 is: 0 3. ``` -## hash_map::find +## `hash_map::find` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator addressing the location of an element in a hash_map that has a key equivalent to a specified key. +Returns an iterator addressing the location of an element in a `hash_map` that has a key equivalent to a specified key. ```cpp iterator find(const Key& key); @@ -1250,18 +1250,18 @@ const_iterator find(const Key& key) const; ### Parameters -*key*\ -The key value to be matched by the sort key of an element from the hash_map being searched. +*`key`*\ +The key value to be matched by the sort key of an element from the `hash_map` being searched. ### Return Value -An iterator that addresses the location of an element with a specified key, or the location succeeding the last element in the hash_map if no match is found for the key. +An iterator that addresses the location of an element with a specified key, or the location succeeding the last element in the `hash_map` if no match is found for the key. ### Remarks -`find` returns an iterator that addresses an element in the hash_map whose sort key is equivalent to the argument key under a binary predicate that induces an ordering based on a less than comparability relation. +`find` returns an iterator that addresses an element in the `hash_map` whose sort key is equivalent to the argument key under a binary predicate that induces an ordering based on a less than comparability relation. -If the return value of `find` is assigned to a [const_iterator](#const_iterator), the hash_map object cannot be modified. If the return value of `find` is assigned to an [iterator](#iterator), the hash_map object can be modified +If the return value of `find` is assigned to a [`const_iterator`](#const_iterator), the `hash_map` object can't be modified. If the return value of `find` is assigned to an [`iterator`](#iterator), the `hash_map` object can be modified ### Example @@ -1314,12 +1314,12 @@ The hash_map hm1 doesn't have an element with a key of 4. The element of hm1 with a key matching that of the last element is: 30. ``` -## hash_map::get_allocator +## `hash_map::get_allocator` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a copy of the allocator object used to construct the hash_map. +Returns a copy of the allocator object used to construct the `hash_map`. ```cpp Allocator get_allocator() const; @@ -1327,11 +1327,11 @@ Allocator get_allocator() const; ### Return Value -The allocator used by the hash_map. +The allocator used by the `hash_map`. ### Remarks -Allocators for the hash_map class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. +Allocators for the `hash_map` class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. ### Example @@ -1390,12 +1390,12 @@ int main( ) } ``` -## hash_map::hash_map +## `hash_map::hash_map` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Constructs a hash_map that is empty or is a copy of all or part of some other hash_map. +Constructs a `hash_map` that is empty or is a copy of all or part of some other `hash_map`. ```cpp hash_map(); @@ -1443,46 +1443,46 @@ hash_map( ### Parameters -*Al*\ -The storage allocator class to be used for this hash_map object, which defaults to `Allocator`. +*`Al`*\ +The storage allocator class to be used for this `hash_map` object, which defaults to `Allocator`. -*Comp*\ -The comparison function of type const `Traits` used to order the elements in the hash_map, which defaults to `hash_compare`. +*`Comp`*\ +The comparison function of type const `Traits` used to order the elements in the `hash_map`, which defaults to `hash_compare`. -*Right*\ -The hash_map of which the constructed map is to be a copy. +*`Right`*\ +The `hash_map` of which the constructed map is to be a copy. -*First*\ +*`First`*\ The position of the first element in the range of elements to be copied. -*Last*\ +*`Last`*\ The position of the first element beyond the range of elements to be copied. -*IList*\ -The initializer_list +*`IList`*\ +The `initializer_list` ### Remarks -All constructors store a type of allocator object that manages memory storage for the hash_map and can later be returned by calling [get_allocator](#get_allocator). The allocator parameter is often omitted in the class declarations and preprocessing macros used to substitute alternative allocators. +All constructors store a type of allocator object that manages memory storage for the `hash_map` and can later be returned by calling [`get_allocator`](#get_allocator). The allocator parameter is often omitted in the class declarations and preprocessing macros used to substitute alternative allocators. -All constructors initialize their hash_map. +All constructors initialize their `hash_map`. -All constructors store a function object of type `Traits` that is used to establish an order among the keys of the hash_map and that can later be returned by calling [key_comp](#key_comp). +All constructors store a function object of type `Traits` that is used to establish an order among the keys of the `hash_map` and that can later be returned by calling [`key_comp`](#key_comp). -The first three constructors specify an empty initial hash_map, in addition, the second specifies the type of comparison function (*Comp*) to be used in establishing the order of the elements and the third explicitly specifies the allocator type (*Al*) to be used. The keyword **`explicit`** suppresses certain kinds of automatic type conversion. +The first three constructors specify an empty initial `hash_map`, in addition, the second specifies the type of comparison function (*`Comp`*) to be used in establishing the order of the elements and the third explicitly specifies the allocator type (*`Al`*) to be used. The keyword **`explicit`** suppresses certain kinds of automatic type conversion. -The fourth constructor specifies a copy of the hash_map *Right*. +The fourth constructor specifies a copy of the `hash_map` *`Right`*. -The next three constructors copy the range `[First, Last)` of a hash_map with increasing explicitness in specifying the type of comparison function of class `Traits` and allocator. +The next three constructors copy the range `[First, Last)` of a `hash_map` with increasing explicitness in specifying the type of comparison function of class `Traits` and allocator. -The last constructor moves the hash_map *Right*. +The last constructor moves the `hash_map` *`Right`*. -## hash_map::insert +## `hash_map::insert` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Inserts an element or a range of elements into a hash_map. +Inserts an element or a range of elements into a `hash_map`. ```cpp pair insert( @@ -1510,43 +1510,43 @@ iterator insert( ### Parameters -*val*\ -The value of an element to be inserted into the hash_map unless the hash_map already contains that element (or, more generally, an element whose key is equivalently ordered). +*`val`*\ +The value of an element to be inserted into the `hash_map` unless the `hash_map` already contains that element (or, more generally, an element whose key is equivalently ordered). -*_Where*\ +*`_Where`*\ A hint regarding the place to start searching for the correct point of insertion. -*first*\ -The position of the first element to be copied from a hash_map. +*`first`*\ +The position of the first element to be copied from a `hash_map`. -*last*\ -The position just beyond the last element to be copied from a hash_map. +*`last`*\ +The position just beyond the last element to be copied from a `hash_map`. ### Return Value -The first `insert` member function returns a pair whose bool component returns true if an insertion was made and false if the hash_map already contained an element whose key had an equivalent value in the ordering, and whose iterator component returns the address where a new element was inserted or where the element was already located. +The first `insert` member function returns a pair whose `bool` component returns `true` if an insertion was made and `false` if the `hash_map` already contained an element whose key had an equivalent value in the ordering, and whose iterator component returns the address where a new element was inserted or where the element was already located. -To access the iterator component of a pair `pr` returned by this member function, use `pr`. **first**, and to dereference it, use \*( `pr`. **first**). To access the **`bool`** component of a pair `pr` returned by this member function, use `pr`. **second**, and to dereference it, use \*( `pr`. **second**). +To access the iterator component of a pair `pr` returned by this member function, use `pr.first`, and to dereference it, use `(pr.first)`. To access the **`bool`** component of a pair `pr` returned by this member function, use `pr.second`, and to dereference it, use `(pr.second)`. -The second `insert` member function, the hint version, returns an iterator that points to the position where the new element was inserted into the hash_map. +The second `insert` member function, the hint version, returns an iterator that points to the position where the new element was inserted into the `hash_map`. The last two `insert` member functions behave the same as the first two, except that they move construct the inserted value. ### Remarks -The [value_type](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. +The [`value_type`](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. -Insertion can occur in amortized constant time for the hint version of insert, instead of logarithmic time, if the insertion point immediately follows *_Where*. +Insertion can occur in amortized constant time for the hint version of insert, instead of logarithmic time, if the insertion point immediately follows *`_Where`*. -The third member function inserts the sequence of element values into a hash_map corresponding to each element addressed by an iterator of in the range *[First, Last)* of a specified set. +The third member function inserts the sequence of element values into a `hash_map` corresponding to each element addressed by an iterator of in the range `*[First, Last)*` of a specified set. ### Example ```cpp // hash_map_insert.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -1648,12 +1648,12 @@ After the move insertion, hm4 contains: 2 => b ``` -## hash_map::iterator +## `hash_map::iterator` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a bidirectional iterator that can read or modify any element in a hash_map. +A type that provides a bidirectional iterator that can read or modify any element in a `hash_map`. ```cpp typedef list::iterator iterator; @@ -1661,7 +1661,7 @@ typedef list::iter ### Remarks -The `iterator` defined by hash_map points to elements that are objects of [value_type](#value_type), that is of type `pair`, whose first member is the key to the element and whose second member is the mapped datum held by the element. +The `iterator` defined by `hash_map` points to elements that are objects of [`value_type`](#value_type), that is of type `pair`, whose first member is the key to the element and whose second member is the mapped datum held by the element. To dereference an iterator named `Iter` pointing to an element in a multimap, use the `->` operator. @@ -1671,14 +1671,14 @@ A type `iterator` can be used to modify the value of an element. ### Example -See example for [begin](#begin) for an example of how to declare and use the `iterator`. +See example for [`begin`](#begin) for an example of how to declare and use the `iterator`. -## hash_map::key_comp +## `hash_map::key_comp` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Retrieves a copy of the comparison object used to order keys in a hash_map. +Retrieves a copy of the comparison object used to order keys in a `hash_map`. ```cpp key_compare key_comp() const; @@ -1686,7 +1686,7 @@ key_compare key_comp() const; ### Return Value -Returns the function object that a hash_map uses to order its elements. +Returns the function object that a `hash_map` uses to order its elements. ### Remarks @@ -1694,7 +1694,7 @@ The stored object defines the member function `bool operator( const Key& left, const Key&right );` -that returns **`true`** if `left` precedes and is not equal to `right` in the sort order. +that returns **`true`** if `left` precedes and isn't equal to `right` in the sort order. ### Example @@ -1749,10 +1749,10 @@ int main( ) } ``` -## hash_map::key_compare +## `hash_map::key_compare` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the map. @@ -1764,18 +1764,18 @@ typedef Traits key_compare; `key_compare` is a synonym for the template parameter `Traits`. -For more information on `Traits` see the [hash_map Class](../standard-library/hash-map-class.md) topic. +For more information on `Traits` see the [`hash_map` Class](../standard-library/hash-map-class.md) topic. ### Example -See example for [key_comp](#key_comp) for an example of how to declare and use `key_compare`. +See example for [`key_comp`](#key_comp) for an example of how to declare and use `key_compare`. -## hash_map::key_type +## `hash_map::key_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type describes the sort key object that constitutes each element of the hash_map. +A type describes the sort key object that constitutes each element of the `hash_map`. ```cpp typedef Key key_type; @@ -1785,18 +1785,18 @@ typedef Key key_type; `key_type` is a synonym for the template parameter `Key`. -For more information on `Key`, see the Remarks section of the [hash_map Class](../standard-library/hash-map-class.md) topic. +For more information on `Key`, see the Remarks section of the [`hash_map` Class](../standard-library/hash-map-class.md) topic. ### Example -See example for [value_type](#value_type) for an example of how to declare and use `key_type`. +See example for [`value_type`](#value_type) for an example of how to declare and use `key_type`. -## hash_map::lower_bound +## `hash_map::lower_bound` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator to the first element in a hash_map with a key value that is equal to or greater than that of a specified key. +Returns an iterator to the first element in a `hash_map` with a key value that is equal to or greater than that of a specified key. ```cpp iterator lower_bound(const Key& key); @@ -1806,14 +1806,14 @@ const_iterator lower_bound(const Key& key) const; ### Parameters -*key*\ -The argument key value to be compared with the sort key of an element from the hash_map being searched. +*`key`*\ +The argument key value to be compared with the sort key of an element from the `hash_map` being searched. ### Return Value -An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the location of an element in a hash_map that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the hash_map if no match is found for the key. +An [`iterator`](#iterator) or [`const_iterator`](#const_iterator) that addresses the location of an element in a `hash_map` that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the `hash_map` if no match is found for the key. -If the return value of `lower_bound` is assigned to a `const_iterator`, the hash_map object cannot be modified. If the return value of `lower_bound` is assigned to a `iterator`, the hash_map object can be modified. +If the return value of `lower_bound` is assigned to a `const_iterator`, the `hash_map` object can't be modified. If the return value of `lower_bound` is assigned to a `iterator`, the `hash_map` object can be modified. ### Remarks @@ -1868,12 +1868,12 @@ The hash_map hm1 doesn't have an element with a key of 4. The element of hm1 with a key matching that of the last element is: 30. ``` -## hash_map::mapped_type +## `hash_map::mapped_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that represents the data type stored in a hash_map. +A type that represents the data type stored in a `hash_map`. ```cpp typedef Type mapped_type; @@ -1883,18 +1883,18 @@ typedef Type mapped_type; The type `mapped_type` is a synonym for the template parameter `Type`. -For more information on `Type` see the [hash_map Class](../standard-library/hash-map-class.md) topic. +For more information on `Type` see the [`hash_map` Class](../standard-library/hash-map-class.md) topic. ### Example -See example for [value_type](#value_type) for an example of how to declare and use `key_type`. +See example for [`value_type`](#value_type) for an example of how to declare and use `key_type`. -## hash_map::max_size +## `hash_map::max_size` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns the maximum length of the hash_map. +Returns the maximum length of the `hash_map`. ```cpp size_type max_size() const; @@ -1902,7 +1902,7 @@ size_type max_size() const; ### Return Value -The maximum possible length of the hash_map. +The maximum possible length of the `hash_map`. ### Remarks @@ -1928,10 +1928,10 @@ int main( ) } ``` -## hash_map::operator[] +## `hash_map::operator[]` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). Inserts an element into a `hash_map` with a specified key value. @@ -1943,7 +1943,7 @@ Type& operator[](Key&& key); ### Parameters -*key*\ +*`key`*\ The key value of the element that is to be inserted. ### Return Value @@ -1952,15 +1952,15 @@ A reference to the data value of the inserted element. ### Remarks -If the argument key value is not found, then it is inserted along with the default value of the data type. +If the argument key value isn't found, then it's inserted along with the default value of the data type. `operator[]` may be used to insert elements into a `hash_map m` using `m[ key] = DataValue`; -where DataValue is the value of the `mapped_type` of the element with a key value of *key*. +where DataValue is the value of the `mapped_type` of the element with a key value of *`key`*. -When using `operator[]` to insert elements, the returned reference does not indicate whether an insertion is changing a preexisting element or creating a new one. The member functions [find](../standard-library/map-class.md#find) and [insert](../standard-library/map-class.md#insert) can be used to determine whether an element with a specified key is already present before an insertion. +When using `operator[]` to insert elements, the returned reference doesn't indicate whether an insertion is changing a pre-existing element or creating a new one. The member functions [`find`](../standard-library/map-class.md#find) and [`insert`](../standard-library/map-class.md#insert) can be used to determine whether an element with a specified key is already present before an insertion. ### Example @@ -2024,12 +2024,12 @@ int main( ) } ``` -## hash_map::operator= +## `hash_map::operator=` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Replaces the elements of the hash_map with a copy of another hash_map. +Replaces the elements of the `hash_map` with a copy of another `hash_map`. ```cpp hash_map& operator=(const hash_map& right); @@ -2039,12 +2039,12 @@ hash_map& operator=(hash_map&& right); ### Parameters -*right*\ -The [hash_map Class](../standard-library/hash-map-class.md) being copied into the `hash_map`. +*`right`*\ +The [`right` Class](../standard-library/hash-map-class.md) being copied into the `hash_map`. ### Remarks -After erasing any existing elements in a `hash_map`, `operator=` either copies or moves the contents of *right* into the `hash_map`. +After erasing any existing elements in a `hash_map`, `operator=` either copies or moves the contents of *`right`* into the `hash_map`. ### Example @@ -2084,12 +2084,12 @@ int main( ) } ``` -## hash_map::pointer +## `hash_map::pointer` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a pointer to an element in a hash_map. +A type that provides a pointer to an element in a `hash_map`. ```cpp typedef list::pointer pointer; @@ -2099,14 +2099,14 @@ typedef list::po A type `pointer` can be used to modify the value of an element. -In most cases, an [iterator](#iterator) should be used to access the elements in a hash_map object. +In most cases, an [`iterator`](#iterator) should be used to access the elements in a `hash_map` object. -## hash_map::rbegin +## `hash_map::rbegin` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator addressing the first element in a reversed hash_map. +Returns an iterator addressing the first element in a reversed `hash_map`. ```cpp const_reverse_iterator rbegin() const; @@ -2116,15 +2116,15 @@ reverse_iterator rbegin(); ### Return Value -A reverse bidirectional iterator addressing the first element in a reversed hash_map or addressing what had been the last element in the unreversed hash_map. +A reverse bidirectional iterator addressing the first element in a reversed `hash_map` or addressing what had been the last element in the unreversed `hash_map`. ### Remarks -`rbegin` is used with a reversed hash_map just as [begin](#begin) is used with a hash_map. +`rbegin` is used with a reversed `hash_map` just as [`begin`](#begin) is used with a `hash_map`. -If the return value of `rbegin` is assigned to a [const_reverse_iterator](#const_reverse_iterator), then the hash_map object cannot be modified. If the return value of `rbegin` is assigned to a [reverse_iterator](#reverse_iterator), then the hash_map object can be modified. +If the return value of `rbegin` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can't be modified. If the return value of `rbegin` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. -`rbegin` can be used to iterate through a hash_map backwards. +`rbegin` can be used to iterate through a `hash_map` backwards. ### Example @@ -2185,12 +2185,12 @@ The reversed hash_map is: 3 2 1 . After the erasure, the first element in the reversed hash_map is 2. ``` -## hash_map::reference +## `hash_map::reference` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a reference to an element stored in a hash_map. +A type that provides a reference to an element stored in a `hash_map`. ```cpp typedef list::reference reference; @@ -2248,12 +2248,12 @@ The data value of first element in the hash_map is 10. The modified data value of first element is 15. ``` -## hash_map::rend +## `hash_map::rend` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator that addresses the location succeeding the last element in a reversed hash_map. +Returns an iterator that addresses the location succeeding the last element in a reversed `hash_map`. ```cpp const_reverse_iterator rend() const; @@ -2263,17 +2263,17 @@ reverse_iterator rend(); ### Return Value -A reverse bidirectional iterator that addresses the location succeeding the last element in a reversed hash_map (the location that had preceded the first element in the unreversed hash_map). +A reverse bidirectional iterator that addresses the location succeeding the last element in a reversed `hash_map` (the location that had preceded the first element in the unreversed `hash_map`). ### Remarks -`rend` is used with a reversed hash_map just as [end](#end) is used with a hash_map. +`rend` is used with a reversed `hash_map` just as [`end`](#end) is used with a `hash_map`. -If the return value of `rend` is assigned to a [const_reverse_iterator](#const_reverse_iterator), then the hash_map object cannot be modified. If the return value of `rend` is assigned to a [reverse_iterator](#reverse_iterator), then the hash_map object can be modified. +If the return value of `rend` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can't be modified. If the return value of `rend` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. -`rend` can be used to test to whether a reverse iterator has reached the end of its hash_map. +`rend` can be used to test to whether a reverse iterator has reached the end of its `hash_map`. -The value returned by `rend` should not be dereferenced. +The value returned by `rend` shouldn't be dereferenced. ### Example @@ -2338,12 +2338,12 @@ The reversed hash_map is: 3 2 1 . After the erasure, the last element in the reversed hash_map is 2. ``` -## hash_map::reverse_iterator +## `hash_map::reverse_iterator` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that provides a bidirectional iterator that can read or modify an element in a reversed hash_map. +A type that provides a bidirectional iterator that can read or modify an element in a reversed `hash_map`. ```cpp typedef list::reverse_iterator reverse_iterator; @@ -2351,24 +2351,24 @@ typedef list::reve ### Remarks -A type `reverse_iterator` cannot modify the value of an element and is use to iterate through the hash_map in reverse. +A type `reverse_iterator` can't modify the value of an element and is used to iterate through the `hash_map` in reverse. -The `reverse_iterator` defined by hash_map points to elements that are objects of [value_type](#value_type), that is of type **pair\**, whose first member is the key to the element and whose second member is the mapped datum held by the element. +The `reverse_iterator` defined by `hash_map` points to elements that are objects of [value_type](#value_type), that is of type `pair`, whose first member is the key to the element and whose second member is the mapped datum held by the element. -To dereference a `reverse_iterator` `rIter` pointing to an element in a hash_map, use the -> operator. +To dereference a `reverse_iterator` `rIter` pointing to an element in a `hash_map`, use the `->` operator. -To access the value of the key for the element, use `rIter` -> **first**, which is equivalent to (\* `rIter`). **first**. To access the value of the mapped datum for the element, use `rIter` -> **second**, which is equivalent to (\* `rIter`). **first**. +To access the value of the key for the element, use `rIter->first`, which is equivalent to `(*rIter).first`. To access the value of the mapped datum for the element, use `rIter->second`, which is equivalent to `(*rIter).first`. ### Example -See example for [rbegin](#rbegin) for an example of how to declare and use `reverse_iterator`. +See example for [`rbegin`](#rbegin) for an example of how to declare and use `reverse_iterator`. -## hash_map::size +## `hash_map::size` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns the number of elements in the hash_map. +Returns the number of elements in the `hash_map`. ```cpp size_type size() const; @@ -2376,13 +2376,13 @@ size_type size() const; ### Return Value -The current length of the hash_map. +The current length of the `hash_map`. ### Remarks ### Example -The following example demonstrates the use of the hash_map::size member function. +The following example demonstrates the use of the `hash_map::size` member function. ```cpp // hash_map_size.cpp @@ -2413,12 +2413,12 @@ The hash_map length is 1. The hash_map length is now 2. ``` -## hash_map::size_type +## `hash_map::size_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -An unsigned integer type that can represent the number of elements in a hash_map. +An unsigned integer type that can represent the number of elements in a `hash_map`. ```cpp typedef list::size_type size_type; @@ -2428,14 +2428,14 @@ typedef list::si ### Example -See example for [size](#size) for an example of how to declare and use `size_type` +See example for [`size`](#size) for an example of how to declare and use `size_type` -## hash_map::swap +## `hash_map::swap` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Exchanges the elements of two hash_maps. +Exchanges the elements of two `hash_map`s. ```cpp void swap(hash_map& right); @@ -2443,12 +2443,12 @@ void swap(hash_map& right); ### Parameters -*right*\ -The argument hash_map providing the elements to be swapped with the target hash_map. +*`right`*\ +The argument `hash_map` providing the elements to be swapped with the target `hash_map`. ### Remarks -The member function invalidates no references, pointers, or iterators that designate elements in the two hash_maps whose elements are being exchanged. +The member function invalidates no references, pointers, or iterators that designate elements in the two `hash_map`s whose elements are being exchanged. ### Example @@ -2504,12 +2504,12 @@ After swapping with hm2, hash_map hm1 is: 100 200. After swapping with hm3, hash_map hm1 is: 300. ``` -## hash_map::upper_bound +## `hash_map::upper_bound` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns an iterator to the first element in a hash_map that with a key having a value that is greater than that of a specified key. +Returns an iterator to the first element in a `hash_map` that with a key having a value that is greater than that of a specified key. ```cpp iterator upper_bound(const Key& key); @@ -2519,14 +2519,14 @@ const_iterator upper_bound(const Key& key) const; ### Parameters -*key*\ -The argument key value to be compared with the sort key value of an element from the hash_map being searched. +*`key`*\ +The argument key value to be compared with the sort key value of an element from the `hash_map` being searched. ### Return Value -An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the location of an element in a hash_map that with a key that is greater than the argument key, or that addresses the location succeeding the last element in the hash_map if no match is found for the key. +An [`iterator`](#iterator) or [`const_iterator`](#const_iterator) that addresses the location of an element in a `hash_map` that with a key that is greater than the argument key, or that addresses the location succeeding the last element in the `hash_map` if no match is found for the key. -If the return value is assigned to a `const_iterator`, the hash_map object cannot be modified. If the return value is assigned to an `iterator`, the hash_map object can be modified. +If the return value is assigned to a `const_iterator`, the `hash_map` object can't be modified. If the return value is assigned to an `iterator`, the `hash_map` object can be modified. ### Remarks @@ -2582,12 +2582,12 @@ The 1st element of hm1 with a key greater than that of the initial element of hm1 is: 20. ``` -## hash_map::value_comp +## `hash_map::value_comp` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -Returns a function object that determines the order of elements in a hash_map by comparing their key values. +Returns a function object that determines the order of elements in a `hash_map` by comparing their key values. ```cpp value_compare value_comp() const; @@ -2595,15 +2595,15 @@ value_compare value_comp() const; ### Return Value -Returns the comparison function object that a hash_map uses to order its elements. +Returns the comparison function object that a `hash_map` uses to order its elements. ### Remarks -For a hash_map *m*, if two elements *e1* (*k1*, *d1*) and *e2* (*k2*, *d2*) are objects of type [value_type](#value_type), where *k1* and *k2* are their keys of type [key_type](#key_type) and *d1* and *d2* are their data of type [mapped_type](#mapped_type), then `m.value_comp()(e1, e2)` is equivalent to `m.key_comp()(k1, k2)`. A stored object defines the member function +For a `hash_map` *`m`*, if two elements *`e1`* (*`k1`*, *`d1`*) and *`e2`* (*`k2`*, *`d2`*) are objects of type [`value_type`](#value_type), where *`k1`* and *`k2`* are their keys of type [`key_type`](#key_type) and *`d1`* and *`d2`* are their data of type [`mapped_type`](#mapped_type), then `m.value_comp()(e1, e2)` is equivalent to `m.key_comp()(k1, k2)`. A stored object defines the member function `bool operator(value_type& left, value_type& right);` -which returns **`true`** if the key value of `left` precedes and is not equal to the key value of `right` in the sort order. +which returns **`true`** if the key value of `left` precedes and isn't equal to the key value of `right` in the sort order. ### Example @@ -2650,12 +2650,12 @@ int main( ) } ``` -## hash_map::value_type +## `hash_map::value_type` > [!NOTE] -> This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). +> This API is obsolete. The alternative is [`unordered_map` Class](../standard-library/unordered-map-class.md). -A type that represents the type of object stored in a hash_map. +A type that represents the type of object stored in a `hash_map`. ```cpp typedef pair value_type; diff --git a/docs/standard-library/hash-map-functions.md b/docs/standard-library/hash-map-functions.md index 8cfca3016b..023610dd7e 100644 --- a/docs/standard-library/hash-map-functions.md +++ b/docs/standard-library/hash-map-functions.md @@ -1,16 +1,14 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["hash_map/std::swap", "hash_map/std::swap (hash_map)"] -ms.assetid: 28748cd0-71f7-41b9-b068-579183645fba --- # `` functions -[swap](#swap)\ -[swap (hash_map)](#swap_hash_map) +The `` header provides the following functions: -## swap (hash_map) +## `swap` (`hash_map`) > [!NOTE] > This API is obsolete. The alternative is [unordered_map Class](../standard-library/unordered-map-class.md). @@ -19,23 +17,23 @@ Exchanges the elements of two hash_maps. ```cpp void swap( - hash_map & left, + hash_map & left, hash_map & right); ``` ### Parameters -*right*\ -The hash_map whose elements are to be exchanged with those of the map *left*. +*`right`*\ +The hash_map whose elements are to be exchanged with those of the map *`left`*. -*left*\ -The hash_map whose elements are to be exchanged with those of the map *right*. +*`left`*\ +The hash_map whose elements are to be exchanged with those of the map *`right`*. ### Remarks -The template function is an algorithm specialized on the container class hash_map to execute the member function `left.`[swap](../standard-library/basic-ios-class.md#swap)*(right*). This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **template \ void swap(T&, T&)**, in the algorithm header file works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class hash_map to execute the member function `left.`[`swap`](../standard-library/basic-ios-class.md#swap)(`right`). This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template void swap(T&, T&)`**, in the algorithm header file works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. -## swap +## `swap` > [!NOTE] > This API is obsolete. The alternative is [unordered_multimap Class](../standard-library/unordered-multimap-class.md). @@ -44,22 +42,22 @@ Exchanges the elements of two hash_multimaps. ```cpp void swap( - hash_multimap & left, + hash_multimap & left, hash_multimap & right); ``` ### Parameters -*right*\ -The hash_multimap whose elements are to be exchanged with those of the map *left*. +*`right`*\ +The `hash_multimap` whose elements are to be exchanged with those of the map *`left`*. -*left*\ -The hash_multimap whose elements are to be exchanged with those of the map *right*. +*`left`*\ +The `hash_multimap` whose elements are to be exchanged with those of the map *`right`*. ### Remarks -The template function is an algorithm specialized on the container class hash_multimap to execute the member function `left.`[swap](../standard-library/hash-multimap-class.md#swap)*(right*`)`. This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **template \ void swap(T&, T&)**, in the algorithm header file works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class hash_multimap to execute the member function `left.`[`swap`](../standard-library/hash-multimap-class.md#swap)(`right`). This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template void swap(T&, T&)`**, in the algorithm header file works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. ## See also -[](../standard-library/hash-map.md) +[``](../standard-library/hash-map.md) diff --git a/docs/standard-library/hash-map-operators.md b/docs/standard-library/hash-map-operators.md index 4367ddecbe..1fc15813e1 100644 --- a/docs/standard-library/hash-map-operators.md +++ b/docs/standard-library/hash-map-operators.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["hash_map/std::operator!=", "hash_map/std::operator=="] -ms.assetid: 24b9bb9e-e983-4060-bce5-2c7c8161ee61 --- # `` operators -[operator!=](#op_neq)\ -[operator!= (multimap)](#op_neq_mm)\ -[operator==](#op_eq_eq)\ -[operator== (multimap)](#op_eq_eq_mm) +The `` header provides the following operators: ## operator!= diff --git a/docs/standard-library/hash-multimap-class.md b/docs/standard-library/hash-multimap-class.md index ca2f5e5b1f..3884eb36cf 100644 --- a/docs/standard-library/hash-multimap-class.md +++ b/docs/standard-library/hash-multimap-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: hash_multimap Class" title: "hash_multimap Class" -ms.date: "10/18/2018" +description: "Learn more about: hash_multimap Class" +ms.date: 10/18/2018 f1_keywords: ["hash_map/stdext::hash_multimap", "hash_map/stdext::hash_multimap::allocator_type", "hash_map/stdext::hash_multimap::const_iterator", "hash_map/stdext::hash_multimap::const_pointer", "hash_map/stdext::hash_multimap::const_reference", "hash_map/stdext::hash_multimap::const_reverse_iterator", "hash_map/stdext::hash_multimap::difference_type", "hash_map/stdext::hash_multimap::iterator", "hash_map/stdext::hash_multimap::key_compare", "hash_map/stdext::hash_multimap::key_type", "hash_map/stdext::hash_multimap::mapped_type", "hash_map/stdext::hash_multimap::pointer", "hash_map/stdext::hash_multimap::reference", "hash_map/stdext::hash_multimap::reverse_iterator", "hash_map/stdext::hash_multimap::size_type", "hash_map/stdext::hash_multimap::value_type", "hash_map/stdext::hash_multimap::begin", "hash_map/stdext::hash_multimap::cbegin", "hash_map/stdext::hash_multimap::cend", "hash_map/stdext::hash_multimap::clear", "hash_map/stdext::hash_multimap::count", "hash_map/stdext::hash_multimap::crbegin", "hash_map/stdext::hash_multimap::crend", "hash_map/stdext::hash_multimap::emplace", "hash_map/stdext::hash_multimap::emplace_hint", "hash_map/stdext::hash_multimap::empty", "hash_map/stdext::hash_multimap::end", "hash_map/stdext::hash_multimap::equal_range", "hash_map/stdext::hash_multimap::erase", "hash_map/stdext::hash_multimap::find", "hash_map/stdext::hash_multimap::get_allocator", "hash_map/stdext::hash_multimap::insert", "hash_map/stdext::hash_multimap::key_comp", "hash_map/stdext::hash_multimap::lower_bound", "hash_map/stdext::hash_multimap::max_size", "hash_map/stdext::hash_multimap::rbegin", "hash_map/stdext::hash_multimap::rend", "hash_map/stdext::hash_multimap::size", "hash_map/stdext::hash_multimap::swap", "hash_map/stdext::hash_multimap::upper_bound", "hash_map/stdext::hash_multimap::value_comp"] helpviewer_keywords: ["stdext::hash_multimap", "stdext::hash_multimap::allocator_type", "stdext::hash_multimap::const_iterator", "stdext::hash_multimap::const_pointer", "stdext::hash_multimap::const_reference", "stdext::hash_multimap::const_reverse_iterator", "stdext::hash_multimap::difference_type", "stdext::hash_multimap::iterator", "stdext::hash_multimap::key_compare", "stdext::hash_multimap::key_type", "stdext::hash_multimap::mapped_type", "stdext::hash_multimap::pointer", "stdext::hash_multimap::reference", "stdext::hash_multimap::reverse_iterator", "stdext::hash_multimap::size_type", "stdext::hash_multimap::value_type", "stdext::hash_multimap::begin", "stdext::hash_multimap::cbegin", "stdext::hash_multimap::cend", "stdext::hash_multimap::clear", "stdext::hash_multimap::count", "stdext::hash_multimap::crbegin", "stdext::hash_multimap::crend", "stdext::hash_multimap::emplace", "stdext::hash_multimap::emplace_hint", "stdext::hash_multimap::empty", "stdext::hash_multimap::end", "stdext::hash_multimap::equal_range", "stdext::hash_multimap::erase", "stdext::hash_multimap::find", "stdext::hash_multimap::get_allocator", "stdext::hash_multimap::insert", "stdext::hash_multimap::key_comp", "stdext::hash_multimap::lower_bound", "stdext::hash_multimap::max_size", "stdext::hash_multimap::rbegin", "stdext::hash_multimap::rend", "stdext::hash_multimap::size", "stdext::hash_multimap::swap", "stdext::hash_multimap::upper_bound", "stdext::hash_multimap::value_comp"] -ms.assetid: f41a6db9-67aa-43a3-a3c5-dbfe9ec3ae7d --- # hash_multimap Class @@ -776,8 +775,8 @@ The [hash_multimap::value_type](#value_type) of an element is a pair, so that th ```cpp // hash_multimap_emplace.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -837,8 +836,8 @@ Insertion can occur in amortized constant time, instead of logarithmic time, if ```cpp // hash_multimap_emplace_hint.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -1005,7 +1004,7 @@ The argument key to be compared with the sort key of an element from the hash_mu A pair of iterators such that the first is the [lower_bound](#lower_bound) of the key and the second is the [upper_bound](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*(`pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*(`pr`. **second**). ### Remarks diff --git a/docs/standard-library/hash-multiset-class.md b/docs/standard-library/hash-multiset-class.md index 4c18f9e9e5..7b40ba2623 100644 --- a/docs/standard-library/hash-multiset-class.md +++ b/docs/standard-library/hash-multiset-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: hash_multiset Class" title: "hash_multiset Class" -ms.date: "11/04/2016" +description: "Learn more about: hash_multiset Class" +ms.date: 11/04/2016 f1_keywords: ["hash_set/stdext::hash_multiset", "hash_set/stdext::hash_multiset::allocator_type", "hash_set/stdext::hash_multiset::const_iterator", "hash_set/stdext::hash_multiset::const_pointer", "hash_set/stdext::hash_multiset::const_reference", "hash_set/stdext::hash_multiset::const_reverse_iterator", "hash_set/stdext::hash_multiset::difference_type", "hash_set/stdext::hash_multiset::iterator", "hash_set/stdext::hash_multiset::key_compare", "hash_set/stdext::hash_multiset::key_type", "hash_set/stdext::hash_multiset::pointer", "hash_set/stdext::hash_multiset::reference", "hash_set/stdext::hash_multiset::reverse_iterator", "hash_set/stdext::hash_multiset::size_type", "hash_set/stdext::hash_multiset::value_compare", "hash_set/stdext::hash_multiset::value_type", "hash_set/stdext::hash_multiset::begin", "hash_set/stdext::hash_multiset::cbegin", "hash_set/stdext::hash_multiset::cend", "hash_set/stdext::hash_multiset::clear", "hash_set/stdext::hash_multiset::count", "hash_set/stdext::hash_multiset::crbegin", "hash_set/stdext::hash_multiset::crend", "hash_set/stdext::hash_multiset::emplace", "hash_set/stdext::hash_multiset::emplace_hint", "hash_set/stdext::hash_multiset::empty", "hash_set/stdext::hash_multiset::end", "hash_set/stdext::hash_multiset::equal_range", "hash_set/stdext::hash_multiset::erase", "hash_set/stdext::hash_multiset::find", "hash_set/stdext::hash_multiset::get_allocator", "hash_set/stdext::hash_multiset::insert", "hash_set/stdext::hash_multiset::key_comp", "hash_set/stdext::hash_multiset::lower_bound", "hash_set/stdext::hash_multiset::max_size", "hash_set/stdext::hash_multiset::rbegin", "hash_set/stdext::hash_multiset::rend", "hash_set/stdext::hash_multiset::size", "hash_set/stdext::hash_multiset::swap", "hash_set/stdext::hash_multiset::upper_bound", "hash_set/stdext::hash_multiset::value_comp"] helpviewer_keywords: ["stdext::hash_multiset", "stdext::hash_multiset::allocator_type", "stdext::hash_multiset::const_iterator", "stdext::hash_multiset::const_pointer", "stdext::hash_multiset::const_reference", "stdext::hash_multiset::const_reverse_iterator", "stdext::hash_multiset::difference_type", "stdext::hash_multiset::iterator", "stdext::hash_multiset::key_compare", "stdext::hash_multiset::key_type", "stdext::hash_multiset::pointer", "stdext::hash_multiset::reference", "stdext::hash_multiset::reverse_iterator", "stdext::hash_multiset::size_type", "stdext::hash_multiset::value_compare", "stdext::hash_multiset::value_type", "stdext::hash_multiset::begin", "stdext::hash_multiset::cbegin", "stdext::hash_multiset::cend", "stdext::hash_multiset::clear", "stdext::hash_multiset::count", "stdext::hash_multiset::crbegin", "stdext::hash_multiset::crend", "stdext::hash_multiset::emplace", "stdext::hash_multiset::emplace_hint", "stdext::hash_multiset::empty", "stdext::hash_multiset::end", "stdext::hash_multiset::equal_range", "stdext::hash_multiset::erase", "stdext::hash_multiset::find", "stdext::hash_multiset::get_allocator", "stdext::hash_multiset::insert", "stdext::hash_multiset::key_comp", "stdext::hash_multiset::lower_bound", "stdext::hash_multiset::max_size", "stdext::hash_multiset::rbegin", "stdext::hash_multiset::rend", "stdext::hash_multiset::size", "stdext::hash_multiset::swap", "stdext::hash_multiset::upper_bound", "stdext::hash_multiset::value_comp"] -ms.assetid: 0580397a-a76e-40ad-aea2-5c6f3a9d0a21 --- # hash_multiset Class @@ -931,7 +930,7 @@ The argument key to be compared with the sort key of an element from the hash_mu A pair of iterators where the first is the [lower_bound](#lower_bound) of the key and the second is the [upper_bound](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*(`pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*(`pr`. **second**). ### Example @@ -1295,11 +1294,11 @@ hash_multiset( hash_multiset( hash_multiset&& Right -}; +); hash_multiset (initializer_list IList); hash_multiset( - initializer_list IList, const Compare& Comp): + initializer_list IList, const Compare& Comp): hash_multiset( initializer_list IList, const Compare& Comp, const Allocator& Al); diff --git a/docs/standard-library/hash-set-class.md b/docs/standard-library/hash-set-class.md index 703cd2f9c4..89d2607646 100644 --- a/docs/standard-library/hash-set-class.md +++ b/docs/standard-library/hash-set-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: hash_set Class" title: "hash_set Class" -ms.date: "11/04/2016" +description: "Learn more about: hash_set Class" +ms.date: 11/04/2016 f1_keywords: ["hash_set/stdext::hash_set", "hash_set/stdext::hash_set::allocator_type", "hash_set/stdext::hash_set::const_iterator", "hash_set/stdext::hash_set::const_pointer", "hash_set/stdext::hash_set::const_reference", "hash_set/stdext::hash_set::const_reverse_iterator", "hash_set/stdext::hash_set::difference_type", "hash_set/stdext::hash_set::iterator", "hash_set/stdext::hash_set::key_compare", "hash_set/stdext::hash_set::key_type", "hash_set/stdext::hash_set::pointer", "hash_set/stdext::hash_set::reference", "hash_set/stdext::hash_set::reverse_iterator", "hash_set/stdext::hash_set::size_type", "hash_set/stdext::hash_set::value_compare", "hash_set/stdext::hash_set::value_type", "hash_set/stdext::hash_set::begin", "hash_set/stdext::hash_set::cbegin", "hash_set/stdext::hash_set::cend", "hash_set/stdext::hash_set::clear", "hash_set/stdext::hash_set::count", "hash_set/stdext::hash_set::crbegin", "hash_set/stdext::hash_set::crend", "hash_set/stdext::hash_set::emplace", "hash_set/stdext::hash_set::emplace_hint", "hash_set/stdext::hash_set::empty", "hash_set/stdext::hash_set::end", "hash_set/stdext::hash_set::equal_range", "hash_set/stdext::hash_set::erase", "hash_set/stdext::hash_set::find", "hash_set/stdext::hash_set::get_allocator", "hash_set/stdext::hash_set::insert", "hash_set/stdext::hash_set::key_comp", "hash_set/stdext::hash_set::lower_bound", "hash_set/stdext::hash_set::max_size", "hash_set/stdext::hash_set::rbegin", "hash_set/stdext::hash_set::rend", "hash_set/stdext::hash_set::size", "hash_set/stdext::hash_set::swap", "hash_set/stdext::hash_set::upper_bound", "hash_set/stdext::hash_set::value_comp"] helpviewer_keywords: ["stdext::hash_set", "stdext::hash_set::allocator_type", "stdext::hash_set::const_iterator", "stdext::hash_set::const_pointer", "stdext::hash_set::const_reference", "stdext::hash_set::const_reverse_iterator", "stdext::hash_set::difference_type", "stdext::hash_set::iterator", "stdext::hash_set::key_compare", "stdext::hash_set::key_type", "stdext::hash_set::pointer", "stdext::hash_set::reference", "stdext::hash_set::reverse_iterator", "stdext::hash_set::size_type", "stdext::hash_set::value_compare", "stdext::hash_set::value_type", "stdext::hash_set::begin", "stdext::hash_set::cbegin", "stdext::hash_set::cend", "stdext::hash_set::clear", "stdext::hash_set::count", "stdext::hash_set::crbegin", "stdext::hash_set::crend", "stdext::hash_set::emplace", "stdext::hash_set::emplace_hint", "stdext::hash_set::empty", "stdext::hash_set::end", "stdext::hash_set::equal_range", "stdext::hash_set::erase", "stdext::hash_set::find", "stdext::hash_set::get_allocator", "stdext::hash_set::insert", "stdext::hash_set::key_comp", "stdext::hash_set::lower_bound", "stdext::hash_set::max_size", "stdext::hash_set::rbegin", "stdext::hash_set::rend", "stdext::hash_set::size", "stdext::hash_set::swap", "stdext::hash_set::upper_bound", "stdext::hash_set::value_comp"] -ms.assetid: c765c06e-cbb6-48c2-93ca-d15468eb28d7 --- # hash_set Class @@ -939,7 +938,7 @@ The argument key to be compared with the sort key of an element from the hash_se A pair of iterators where the first is the [lower_bound](../standard-library/set-class.md#lower_bound) of the key and the second is the [upper_bound](../standard-library/set-class.md#upper_bound) of the key. -To access the first iterator of a pair pr returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair pr returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*(`pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*(`pr`. **second**). ### Remarks @@ -1355,7 +1354,7 @@ All constructors initialize their hash_sets. All constructors store a function object of type `Traits` that is used to establish an order among the keys of the `hash_set` and that can later be returned by calling [hash_set::key_comp](#key_comp). For more information on `Traits` see the [hash_set Class](../standard-library/hash-set-class.md) topic. -The first constructor creates an empty initial `hash_set` The second specifies the type of comparison function ( `Comp`) to be used in establishing the order of the elements, and the third explicitly specifies the allocator type ( `Al`) to be used. The key word **`explicit`** suppresses certain kinds of automatic type conversion. +The first constructor creates an empty initial `hash_set` The second specifies the type of comparison function (`Comp`) to be used in establishing the order of the elements, and the third explicitly specifies the allocator type (`Al`) to be used. The key word **`explicit`** suppresses certain kinds of automatic type conversion. The fourth and fifth constructors specify a copy of the `hash_set` `Right`. diff --git a/docs/standard-library/hash-set-functions.md b/docs/standard-library/hash-set-functions.md index 2dd96536c7..43faa5b306 100644 --- a/docs/standard-library/hash-set-functions.md +++ b/docs/standard-library/hash-set-functions.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["hash_set/std::swap", "hash_set/std::swap (hash_multiset)"] -ms.assetid: 557a0162-3728-4537-97dc-f9f6cc7ece94 --- # `` functions -[swap](#swap)\ -[swap (hash_multiset)](#swap_hash_multiset) +The `` header provides the following functions: ## swap diff --git a/docs/standard-library/hash-set-operators.md b/docs/standard-library/hash-set-operators.md index dc6d86cb06..3ed14584a2 100644 --- a/docs/standard-library/hash-set-operators.md +++ b/docs/standard-library/hash-set-operators.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "03/27/2019" +description: "Learn more about: operators" +ms.date: 03/27/2019 f1_keywords: ["hash_set/std::operator!=", "hash_set/std::operator=="] -ms.assetid: 403d8e4e-0b3f-43fb-bc5a-8100c4f331c5 --- # `` operators -[operator!=](#op_neq)\ -[operator!= (hash_multiset)](#op_neq_hash_multiset)\ -[operator==](#op_eq_eq)\ -[operator== (hash_multiset)](#op_eq_eq_hash_multiset) +The `` header provides the following operators: ## operator!= diff --git a/docs/standard-library/hash-structure-stl.md b/docs/standard-library/hash-structure-stl.md index 979d001806..38eea051e4 100644 --- a/docs/standard-library/hash-structure-stl.md +++ b/docs/standard-library/hash-structure-stl.md @@ -1,6 +1,6 @@ --- description: "Learn more about: hash Structure (C++ Standard Library)" -title: "hash Structure (C++ Standard Library)| Microsoft Docs" +title: hash Structure (C++ Standard Library) ms.date: "11/04/2016" f1_keywords: ["thread/std::hash"] ms.assetid: 4a8bf5bc-4334-4070-936b-98585f8a073b diff --git a/docs/standard-library/hhmmss-class.md b/docs/standard-library/hhmmss-class.md index a947317913..1bc61c75f9 100644 --- a/docs/standard-library/hhmmss-class.md +++ b/docs/standard-library/hhmmss-class.md @@ -4,6 +4,7 @@ title: "hh_mm_ss class" ms.date: "06/07/2021" f1_keywords: ["chrono/std::chrono::hh_mm_ss", "chrono/std::chrono::hh_mm_ss::hh_mm_ss", "chrono/std::chrono::hh_mm_ss::is_negative", "chrono/std::chrono::hh_mm_ss::hours", "chrono/std::chrono::hh_mm_ss::minutes", "chrono/std::chrono::hh_mm_ss::seconds", "chrono/std::chrono::hh_mm_ss::subseconds", "chrono/std::chrono::hh_mm_ss::operator precision", "chrono/std::chrono::hh_mm_ss::to_duration"] helpviewer_keywords: ["std::chrono [C++], hh_mm_ss"] +dev_langs: ["C++"] --- # hh_mm_ss class diff --git a/docs/standard-library/high-resolution-clock-struct.md b/docs/standard-library/high-resolution-clock-struct.md index e4777f83e9..702f8d536f 100644 --- a/docs/standard-library/high-resolution-clock-struct.md +++ b/docs/standard-library/high-resolution-clock-struct.md @@ -1,14 +1,13 @@ --- description: "Learn more about: high_resolution_clock struct" -title: "high_resolution_clock struct | Microsoft Docs" +title: high_resolution_clock struct ms.custom: "" ms.date: 08/19/2021 -ms.technology: "cpp-standard-libraries" ms.topic: "reference" f1_keywords: ["chrono/std::chrono::high_resolution_clock", chrono/std::chrono::high_resolution_clock::now", "chrono/std::chrono::high_resolution_clock::is_steady constant"] +helpviewer_keywords: ["std::chrono [C++], high_resolution_clock"] dev_langs: ["C++"] -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" ms.workload: ["cplusplus"] --- # `high_resolution_clock` struct @@ -56,4 +55,4 @@ using high_resolution_clock = steady_clock; [`system_clock` struct](system-clock-structure.md)\ [`tai_clock` class](tai-clock-class.md)\ [`utc_clock` class](utc-clock-class.md)\ -[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/in-place-t-struct.md b/docs/standard-library/in-place-t-struct.md index 4e2312570f..b7c4cecc59 100644 --- a/docs/standard-library/in-place-t-struct.md +++ b/docs/standard-library/in-place-t-struct.md @@ -1,32 +1,108 @@ --- -description: "Learn more about: in_place_t Struct" -title: "in_place_t Struct" -ms.date: "11/04/2016" -f1_keywords: ["utility", "utility/std::in_place_t"] -helpviewer_keywords: ["utility struct"] +description: "Learn more about: in_place_t, in_place_type_t, in_place_index_t" +title: "in_place_t, in_place_type_t, in_place_index_t" +ms.date: 11/14/2024 +f1_keywords: ["utility/utility", "utility/std::in_place_t", "utility/utility", "utility/std::in_place_type_t", "utility", "utility/std::in_place_index_t"] +helpviewer_keywords: ["utility struct", "utility struct", "utility::in_place_type_t struct", "utility struct", "utility::in_place_index_t struct"] --- -# in_place_t Struct +# `in_place_t`, `in_place_type_t`, `in_place_index_t` struct + +Introduced in C++17. + +The `in_place_t`, `in_place_type_t`, and `in_place_index_t` tag types are used to select the overloaded constructor that creates the object in place in the desired way. For the types that use these tag types, they can also help avoid temporary copy or move operations. ## Syntax ```cpp -struct in_place_t { +struct in_place_t +{ explicit in_place_t() = default; }; inline constexpr in_place_t in_place{}; template - struct in_place_type_t { - explicit in_place_type_t() = default; - }; +struct in_place_type_t +{ + explicit in_place_type_t() = default; +}; -template inline constexpr in_place_type_t in_place_type{}; +template +constexpr in_place_type_t in_place_type{}; template - struct in_place_index_t { - explicit in_place_index_t() = default; - }; +struct in_place_index_t +{ + explicit in_place_index_t() = default; +}; -template inline constexpr in_place_index_t in_place_index{}; +template +constexpr in_place_index_t in_place_index{}; ``` + +## Parameters + +*`I`*\ +The index where the object is created in place. + +*`T`*\ +The type of object to create. + +## Remarks + +- `in_place_t` indicates in-place construction of an object. Used to create objects in place inside a `std::optional`. +- `in_place_type_t` indicates in-place construction of an object of a specific type. It's useful with `std::any` because `std::any` can hold any kind of type, so we need to specify the type it holds. +- `in_place_index_t` indicates in-place construction of an object at a specific index. Use with `std::variant` to specify the index where the object is created. + +The following class types use these structs in their constructors: `expected`, [`optional`](optional-class.md), [`single_view`](single-view-class.md), [`any`](any-class.md) or [`variant`](variant-class.md). + +## Example + +```cpp +#include +#include +#include +#include + +// compile with /std:c++17 + +struct MyStruct +{ + double value; + MyStruct(double v0, double v1 = 0) : value(v0 + v1) {} +}; + +int main() +{ + // Construct a MyStruct directly inside opt + std::optional opt(std::in_place, 29.0, 13.0); + + // Construct a MyStruct object inside an any object + std::any a(std::in_place_type, 3.14); + + // Construct a MyStruct object inside a vector at index 0 + std::variant v(std::in_place_index<0>, 2.718); + + if (opt) + { + std::cout << opt->value << ", "; + } + + std::cout << std::any_cast(a).value << ", " + << std::get<0>(v).value; + + return 0; +} +``` + +```output +42, 3.14, 2.718 +``` + +## Requirements + +**Header:** `` + +**Namespace:** `std` + +**Compiler Option:** [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. \ No newline at end of file diff --git a/docs/standard-library/indirect-array-class.md b/docs/standard-library/indirect-array-class.md index dc92e21250..90054b40f0 100644 --- a/docs/standard-library/indirect-array-class.md +++ b/docs/standard-library/indirect-array-class.md @@ -1,24 +1,24 @@ --- -description: "Learn more about: indirect_array Class" -title: "indirect_array Class" -ms.date: "11/04/2016" +description: "Learn more about: indirect_array class" +title: "indirect_array class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::indirect_array"] helpviewer_keywords: ["indirect_array class"] ms.assetid: 10e1eaea-ba5a-405c-a25e-7bdd3eee7fc7 --- -# indirect_array Class +# `indirect_array` class -An internal, auxiliary class template that supports objects that are subsets of valarrays by providing operations between subset arrays defined by specifying a subset of indices of a parent valarray. +An internal, auxiliary class template that supports objects that are subsets of `valarray` objects by providing operations between subset arrays defined by specifying a subset of indices of a parent `valarray`. ## Syntax ## Remarks -The class describes an object that stores a reference to an object `va` of class [valarray](../standard-library/valarray-class.md)**\**, along with an object `xa` of class `valarray`, which describes the sequence of elements to select from the `valarray` object. +The class describes an object that stores a reference to an object `va` of class [`valarray`](../standard-library/valarray-class.md), along with an object `xa` of class `valarray`, which describes the sequence of elements to select from the `valarray` object. -You construct an `indirect_array` object only by writing an expression of the form `va[xa]`. The member functions of class indirect_array then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. +You construct an `indirect_array` object only by writing an expression of the form `va[xa]`. The member functions of class `indirect_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. -The sequence consists of **xa.**[size](../standard-library/valarray-class.md#size) elements, where element `I` becomes the index **xa**[ `I`] within `va`. +The sequence consists of [`xa.size`](../standard-library/valarray-class.md#size) elements, where element `I` becomes the index `xa[I]` within `va`. ## Example: @@ -70,8 +70,8 @@ The modified operand valarray is: (0 -1 10 -1 10 -1 10 -1 8 -1). **Header:** \ -**Namespace:** std +**Namespace:** `std` ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/input-iterator-tag-struct.md b/docs/standard-library/input-iterator-tag-struct.md index 8e903ec94b..b83a8863af 100644 --- a/docs/standard-library/input-iterator-tag-struct.md +++ b/docs/standard-library/input-iterator-tag-struct.md @@ -12,7 +12,9 @@ A class that provides a return type for `iterator_category` function that repres ## Syntax +```cpp struct input_iterator_tag {}; +``` ## Remarks diff --git a/docs/standard-library/input-stream-member-functions.md b/docs/standard-library/input-stream-member-functions.md index fa9ec25dab..83c0ff0d4b 100644 --- a/docs/standard-library/input-stream-member-functions.md +++ b/docs/standard-library/input-stream-member-functions.md @@ -3,17 +3,16 @@ description: "Learn more about: Input Stream Member Functions" title: "Input Stream Member Functions" ms.date: "07/19/2019" helpviewer_keywords: ["input stream objects", "input streams, member functions"] -ms.assetid: b4b9465d-0da9-4ccf-859d-72a68418982e --- # Input Stream Member Functions Input stream member functions are used for disk input. -## open +## `open` -If you are using an input file stream (`ifstream`), you must associate that stream with a specific disk file. You can do this in the constructor, or you can use the `open` function. In either case, the arguments are the same. +If you're using an input file stream (`ifstream`), you must associate that stream with a specific disk file. You can do this in the constructor, or you can use the `open` function. In either case, the arguments are the same. -You generally specify an [ios_base::openmode](../standard-library/ios-base-class.md#openmode) flag when you open the file associated with an input stream (the default mode is `ios::in`). For a list of the `openmode` flags, see [ios_base::openmode](../standard-library/ios-base-class.md#openmode). The flags can be combined with the bitwise OR ( | ) operator. +You generally specify an [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode) flag when you open the file associated with an input stream (the default mode is `ios::in`). For a list of the `openmode` flags, see [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode). The flags can be combined with the bitwise "or" (`|`) operator. To read a file, first use the `fail` member function to determine whether it exists: @@ -24,7 +23,7 @@ if (ifile.fail()) // The file does not exist ... ``` -## get +## `get` The unformatted `get` member function works like the `>>` operator with two exceptions. First, the `get` function includes white-space characters, whereas the extractor excludes white space when the `skipws` flag is set (the default). Second, the `get` function is less likely to cause a tied output stream (`cout`, for example) to be flushed. @@ -59,7 +58,7 @@ int main() 1234 ``` -## getline +## `getline` The `getline` member function is similar to the `get` function. Both functions allow a third argument that specifies the terminating character for input. The default value is the newline character. Both functions reserve one character for the required terminating character. However, `get` leaves the terminating character in the stream and `getline` removes the terminating character. @@ -86,9 +85,9 @@ int main( ) test ``` -## read +## `read` -The `read` member function reads bytes from a file to a specified area of memory. The length argument determines the number of bytes read. If you do not include that argument, reading stops when the physical end of file is reached or, in the case of a text-mode file, when an embedded `EOF` character is read. +The `read` member function reads bytes from a file to a specified area of memory. The length argument determines the number of bytes read. If you don't include that argument, reading stops when the physical end of file is reached or, in the case of a text-mode file, when an embedded `EOF` character is read. This example reads a binary record from a payroll file into a structure: @@ -118,7 +117,7 @@ int main() The program assumes that the data records are formatted exactly as specified by the structure with no terminating carriage return or line feed characters. -## seekg and tellg +## `seekg` and `tellg` Input file streams keep an internal pointer to the position in the file where data is to be read next. You set this pointer with the `seekg` function, as shown here: @@ -148,7 +147,7 @@ int main( ) To use `seekg` to implement record-oriented data management systems, multiply the fixed-length record size by the record number to obtain the byte position relative to the end of the file, and then use the `get` object to read the record. -The `tellg` member function returns the current file position for reading. This value is of type `streampos`, a **`typedef`** defined in \. The following example reads a file and displays messages showing the positions of spaces. +The `tellg` member function returns the current file position for reading. This value is of type `streampos`, a **`typedef`** defined in ``. The following example reads a file and displays messages showing the positions of spaces. ```cpp #include @@ -173,7 +172,7 @@ int main( ) } ``` -## close +## `close` The `close` member function closes the disk file associated with an input file stream and frees the operating system file handle. The [`ifstream`](../standard-library/basic-ifstream-class.md) destructor closes the file for you, but you can use the `close` function if you need to open another file for the same stream object. diff --git a/docs/standard-library/input-streams.md b/docs/standard-library/input-streams.md index 2b4cc5fb3c..94d5134d6f 100644 --- a/docs/standard-library/input-streams.md +++ b/docs/standard-library/input-streams.md @@ -3,17 +3,16 @@ description: "Learn more about: Input Streams" title: "Input Streams" ms.date: "11/04/2016" helpviewer_keywords: ["reading data [C++], from input streams", "data [C++], reading from input stream", "input streams", "input stream objects"] -ms.assetid: f14d8954-8f8c-4c3c-8b99-14ddb3683f94 --- # Input Streams -An input stream object is a source of bytes. The three most important input stream classes are [istream](../standard-library/basic-istream-class.md), [ifstream](../standard-library/basic-ifstream-class.md), and [istringstream](../standard-library/basic-istringstream-class.md). +An input stream object is a source of bytes. The three most important input stream classes are [`istream`](../standard-library/basic-istream-class.md), [`ifstream`](../standard-library/basic-ifstream-class.md), and [`istringstream`](../standard-library/basic-istringstream-class.md). -The `istream` class is best used for sequential text-mode input. You can configure objects of class `istream` for buffered or unbuffered operation. All functionality of the base class, `ios`, is included in `istream`. You will rarely construct objects from class `istream`. Instead, you will generally use the predefined `cin` object, which is actually an object of class [ostream](../standard-library/basic-ostream-class.md). In some cases, you can assign `cin` to other stream objects after program startup. +The `istream` class is best used for sequential text-mode input. You can configure objects of class `istream` for buffered or unbuffered operation. All functionality of the base class, `ios`, is included in `istream`. You'll rarely construct objects from class `istream`. Instead, you'll generally use the predefined `cin` object, which is actually an object of class [`ostream`](../standard-library/basic-ostream-class.md). In some cases, you can assign `cin` to other stream objects after program startup. The `ifstream` class supports disk file input. If you need an input-only disk file, construct an object of class `ifstream`. You can specify binary or text-mode data. If you specify a filename in the constructor, the file is automatically opened when the object is constructed. Otherwise, you can use the `open` function after invoking the default constructor. Many formatting options and member functions apply to `ifstream` objects. All functionality of the base classes `ios` and `istream` is included in `ifstream`. -Like the library function `sscanf_s`, the `istringstream` class supports input from in-memory strings. To extract data from a character array that has a null terminator, allocate and initialize the string, then construct an object of class `istringstream`. +Like the library function `sscanf_s`, the `istringstream` class supports input from in-memory strings. To extract data from a character array that has a `NULL` terminator, allocate and initialize the string, then construct an object of class `istringstream`. ## In This Section @@ -27,8 +26,8 @@ Like the library function `sscanf_s`, the `istringstream` class supports input f [Input Stream Member Functions](../standard-library/input-stream-member-functions.md) -[Overloading the >> Operator for Your Own Classes](../standard-library/overloading-the-input-operator-for-your-own-classes.md) +[Overloading the `>>` Operator for Your Own Classes](../standard-library/overloading-the-input-operator-for-your-own-classes.md) ## See also -[iostream Programming](../standard-library/iostream-programming.md) +[`iostream` Programming](../standard-library/iostream-programming.md) diff --git a/docs/standard-library/insert-iterator-class.md b/docs/standard-library/insert-iterator-class.md index 524331cb75..6932e17a30 100644 --- a/docs/standard-library/insert-iterator-class.md +++ b/docs/standard-library/insert-iterator-class.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: insert_iterator Class" title: "insert_iterator Class" -ms.date: "11/04/2016" +description: "Learn more about: insert_iterator Class" +ms.date: 06/15/2022 f1_keywords: ["iterator/std::insert_iterator", "iterator/std::insert_iterator::container_type", "iterator/std::insert_iterator::reference"] helpviewer_keywords: ["std::insert_iterator [C++]", "std::insert_iterator [C++], container_type", "std::insert_iterator [C++], reference"] -ms.assetid: d5d86405-872e-4e3b-9e68-c69a2b7e8221 +ms.custom: devdivchpfy22 --- + # insert_iterator Class -Describes an iterator adaptor that satisfies the requirements of an output iterator. It inserts, rather than overwrites, elements into a sequence and thus provides semantics that are different from the overwrite semantics provided by the iterators of the C++ sequence and associative containers. The `insert_iterator` class is templatized on the type of container being adapted. +Describes an iterator adaptor that satisfies the requirements of an output iterator. It inserts, rather than overwrites, elements into a sequence. Thus it provides semantics that are different from the overwrite semantics provided by the iterators of the C++ sequence and associative containers. The `insert_iterator` class is templatized on the type of container being adapted. ## Syntax @@ -175,7 +176,7 @@ The member function returns the value of the element addressed. ### Remarks -Used to implement the output iterator expression **\*Iter** = **value**. If `Iter` is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and does not change the total number of elements in the sequence. +Used to implement the output iterator expression **\*Iter** = **value**. If `Iter` is an iterator that addresses an element in a sequence, then **\*Iter** = **value** replaces that element with value and doesn't change the total number of elements in the sequence. ### Example @@ -291,7 +292,7 @@ Inserts a value into the container and returns the iterator updated to point to ```cpp insert_iterator& operator=( - typename Container::const_reference val,); + typename Container::const_reference val); insert_iterator& operator=( typename Container::value_type&& val); diff --git a/docs/standard-library/integer-sequence-class.md b/docs/standard-library/integer-sequence-class.md index ef27dfffbe..acd72f0396 100644 --- a/docs/standard-library/integer-sequence-class.md +++ b/docs/standard-library/integer-sequence-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: integer_sequence Class" title: "integer_sequence Class" +description: "Learn more about: integer_sequence Class" ms.date: "11/04/2016" f1_keywords: ["type_traits/std::index_sequence", "type_traits/std::make_index_sequence", "type_traits/std::integer_sequence", "type_traits/std::make_integer_sequence", "type_traits/std::index_sequence_for"] helpviewer_keywords: ["std::index_sequence", "std::make_index_sequence", "std::integer_sequence", "std::make_integer_sequence", "std::index_sequence_for"] -ms.assetid: 2cfdddee-819d-478e-bb78-c8a9c2696803 --- # integer_sequence Class @@ -40,7 +39,7 @@ A parameter pack that is passed directly to a function can be unpacked without a The following example is based on the original proposal [N3658](https://wg21.link/n3658). It shows how to use an `integer_sequence` to create a `std::tuple` from a `std::array`, and how to use an `integer_sequence` to get at the tuple members. -In the `a2t` function, an `index_sequence` is an alias of `integer_sequence` based on the `size_t` integral type. `make_index_sequence` is an alias that at compile time creates a zero-based `index_sequence` with the same number of elements as the array that is passed in by the caller. `a2t` passes the `index_sequence` by value to `a2t_` , where the expression `a[I]...` unpacks `I`, and then the elements are being fed to `make_tuple` which consumes them as individual arguments. For example, if the sequence contains three elements, then `make_tuple` is called as make_tuple(a[0], a[1], a[2]). The array elements themselves can of course be any type. +In the `a2t` function, an `index_sequence` is an alias of `integer_sequence` based on the `size_t` integral type. `make_index_sequence` is an alias that at compile time creates a zero-based `index_sequence` with the same number of elements as the array that is passed in by the caller. `a2t` passes the `index_sequence` by value to `a2t_`, where the expression `a[I]...` unpacks `I`, and then the elements are being fed to `make_tuple` which consumes them as individual arguments. For example, if the sequence contains three elements, then `make_tuple` is called as make_tuple(a[0], a[1], a[2]). The array elements themselves can of course be any type. The apply function accepts a [std::tuple](../standard-library/tuple-class.md), and produces an `integer_sequence` by using the `tuple_size` helper class. Note that [std::decay_t](../standard-library/decay-class.md) is necessary because [tuple_size](../standard-library/tuple-size-class-tuple.md) does not work with reference types. The `apply_` function unpacks the tuple members and forwards them as separate arguments to a function call. In this example the function is a simple lambda expression that prints out the values. @@ -106,7 +105,7 @@ To make an `index_sequence` for a parameter pack, use `index_sequence_for`\ -Namepace: std +Namespace: `std` ## See also diff --git a/docs/standard-library/iomanip-functions.md b/docs/standard-library/iomanip-functions.md index 3c821d8b77..64bf5ddc61 100644 --- a/docs/standard-library/iomanip-functions.md +++ b/docs/standard-library/iomanip-functions.md @@ -1,23 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: 11/19/2021 f1_keywords: ["iomanip/std::get_money", "iomanip/std::get_time", "iomanip/std::put_money", "iomanip/std::put_time", "iomanip/std::quoted", "iomanip/std::resetiosflags", "iomanip/std::setbase", "iomanip/std::setfill", "iomanip/std::setiosflags", "iomanip/std::setprecision", "iomanip/std::setw"] helpviewer_keywords: ["std::get_money [C++]", "std::get_time [C++]", "std::put_money [C++]", "std::put_time [C++]", "std::quoted [C++]", "std::resetiosflags [C++]", "std::setbase [C++]", "std::setfill [C++]", "std::setiosflags [C++]", "std::setprecision [C++]", "std::setw [C++]"] --- # `` functions -[`get_money`](#iomanip_get_money)\ -[`get_time`](#iomanip_get_time)\ -[`put_money`](#iomanip_put_money)\ -[`put_time`](#iomanip_put_time)\ -[`quoted`](#quoted)\ -[`resetiosflags`](#resetiosflags)\ -[`setbase`](#setbase)\ -[`setfill`](#setfill)\ -[`setiosflags`](#setiosflags)\ -[`setprecision`](#setprecision)\ -[`setw`](#setw) +The `` header provides the following functions: ## `get_money` @@ -648,4 +638,4 @@ l5 = 65536 ## See also -[``](../standard-library/iomanip.md) \ No newline at end of file +[``](../standard-library/iomanip.md) diff --git a/docs/standard-library/iomanip.md b/docs/standard-library/iomanip.md index e2b75574bf..dc50b77980 100644 --- a/docs/standard-library/iomanip.md +++ b/docs/standard-library/iomanip.md @@ -4,11 +4,10 @@ title: "" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: ["iomanip header"] -ms.assetid: 3681c346-4763-4037-bba4-cf0dc3447974 --- # `` -Include the `iostreams` standard header \ to define several manipulators that each take a single argument. +Include the `iostreams` standard header `` to define several manipulators that each take a single argument. ## Syntax @@ -18,27 +17,27 @@ Include the `iostreams` standard header \ to define several manipulator ## Remarks -Each of these manipulators returns an unspecified type, called `T1` through `T10`, that overloads both `basic_istream`\<**Elem**, **Tr**>`::`[operator>>](../standard-library/istream-operators.md#op_gt_gt) and `basic_ostream`\<**Elem**, **Tr**>`::`[operator<<](../standard-library/ostream-operators.md#op_lt_lt). +Each of these manipulators returns an unspecified type, called `T1` through `T10`, that overloads both `basic_istream::operator>>` and `basic_ostream::operator<<`. For more information, see [`operator>>`](../standard-library/istream-operators.md#op_gt_gt) and [`operator<<`](../standard-library/ostream-operators.md#op_lt_lt). ### Manipulators |Name|Description| |-|-| -|[get_money](../standard-library/iomanip-functions.md#iomanip_get_money)|Obtains a monetary amount, optionally in international format.| -|[get_time](../standard-library/iomanip-functions.md#iomanip_get_time)|Obtains a time in a time structure by using a specified format.| -|[put_money](../standard-library/iomanip-functions.md#iomanip_put_money)|Provides a monetary amount, optionally in international format.| -|[put_time](../standard-library/iomanip-functions.md#iomanip_put_time)|Provides a time in a time structure and a format string to use.| -|[quoted](../standard-library/iomanip-functions.md#quoted)|Enables convenient round-tripping of strings with insertion and extraction operators.| -|[resetiosflags](../standard-library/iomanip-functions.md#resetiosflags)|Clears the specified flags.| -|[setbase](../standard-library/iomanip-functions.md#setbase)|Set base for integers.| -|[setfill](../standard-library/iomanip-functions.md#setfill)|Sets the character that will be used to fill spaces in a right-justified display.| -|[setiosflags](../standard-library/iomanip-functions.md#setiosflags)|Sets the specified flags.| -|[setprecision](../standard-library/iomanip-functions.md#setprecision)|Sets the precision for floating-point values.| -|[setw](../standard-library/iomanip-functions.md#setw)|Specifies the width of the display field.| +|[`get_money`](../standard-library/iomanip-functions.md#iomanip_get_money)|Obtains a monetary amount, optionally in international format.| +|[`get_time`](../standard-library/iomanip-functions.md#iomanip_get_time)|Obtains a time in a time structure by using a specified format.| +|[`put_money`](../standard-library/iomanip-functions.md#iomanip_put_money)|Provides a monetary amount, optionally in international format.| +|[`put_time`](../standard-library/iomanip-functions.md#iomanip_put_time)|Provides a time in a time structure and a format string to use.| +|[`quoted`](../standard-library/iomanip-functions.md#quoted)|Enables convenient round-tripping of strings with insertion and extraction operators.| +|[`resetiosflags`](../standard-library/iomanip-functions.md#resetiosflags)|Clears the specified flags.| +|[`setbase`](../standard-library/iomanip-functions.md#setbase)|Set base for integers.| +|[`setfill`](../standard-library/iomanip-functions.md#setfill)|Sets the character that will be used to fill spaces in a right-justified display.| +|[`setiosflags`](../standard-library/iomanip-functions.md#setiosflags)|Sets the specified flags.| +|[`setprecision`](../standard-library/iomanip-functions.md#setprecision)|Sets the precision for floating-point values.| +|[`setw`](../standard-library/iomanip-functions.md#setw)|Specifies the width of the display field.| ## See also [Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[iostreams Conventions](../standard-library/iostreams-conventions.md) +[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostreams` Conventions](../standard-library/iostreams-conventions.md) diff --git a/docs/standard-library/ios-base-class.md b/docs/standard-library/ios-base-class.md index 02770ce61a..c8e5762d83 100644 --- a/docs/standard-library/ios-base-class.md +++ b/docs/standard-library/ios-base-class.md @@ -1,13 +1,15 @@ --- title: "ios_base Class" description: "API reference for the Microsoft Visual C++ standard library `ios_base` class" -ms.date: "10/23/2020" +ms.date: 06/15/2022 f1_keywords: ["xiosbase/std::ios_base", "ios/std::ios_base::event_callback", "xiosbase/std::ios_base::fmtflags", "xiosbase/std::ios_base::iostate", "xiosbase/std::ios_base::openmode", "xiosbase/std::ios_base::seekdir", "xiosbase/std::ios_base::event", "xiosbase/std::ios_base::adjustfield", "xiosbase/std::ios_base::app", "xiosbase/std::ios_base::ate", "xiosbase/std::ios_base::badbit", "xiosbase/std::ios_base::basefield", "xiosbase/std::ios_base::beg", "xiosbase/std::ios_base::binary", "xiosbase/std::ios_base::boolalpha", "xiosbase/std::ios_base::cur", "xiosbase/std::ios_base::dec", "xiosbase/std::ios_base::end", "xiosbase/std::ios_base::eofbit", "xiosbase/std::ios_base::failbit", "xiosbase/std::ios_base::fixed", "xiosbase/std::ios_base::floatfield", "xiosbase/std::ios_base::goodbit", "xiosbase/std::ios_base::hex", "xiosbase/std::ios_base::in", "xiosbase/std::ios_base::internal", "xiosbase/std::ios_base::left", "xiosbase/std::ios_base::oct", "xiosbase/std::ios_base::out", "xiosbase/std::ios_base::right", "xiosbase/std::ios_base::scientific", "xiosbase/std::ios_base::showbase", "xiosbase/std::ios_base::showpoint", "xiosbase/std::ios_base::showpos", "xiosbase/std::ios_base::skipws", "xiosbase/std::ios_base::trunc", "xiosbase/std::ios_base::unitbuf", "xiosbase/std::ios_base::uppercase", "xiosbase/std::ios_base::failure", "xiosbase/std::ios_base::flags", "xiosbase/std::ios_base::getloc", "xiosbase/std::ios_base::imbue", "xiosbase/std::ios_base::Init", "xiosbase/std::ios_base::iword", "xiosbase/std::ios_base::precision", "xiosbase/std::ios_base::pword", "ios/std::ios_base::register_callback", "xiosbase/std::ios_base::setf", "xiosbase/std::ios_base::sync_with_stdio", "xiosbase/std::ios_base::unsetf", "xiosbase/std::ios_base::width", "xiosbase/std::ios_base::xalloc"] helpviewer_keywords: ["std::ios_base [C++]", "std::ios_base [C++], event_callback", "std::ios_base [C++], fmtflags", "std::ios_base [C++], iostate", "std::ios_base [C++], openmode", "std::ios_base [C++], seekdir", "std::ios_base [C++], event", "std::ios_base [C++], adjustfield", "std::ios_base [C++], app", "std::ios_base [C++], ate", "std::ios_base [C++], badbit", "std::ios_base [C++], basefield", "std::ios_base [C++], beg", "std::ios_base [C++], binary", "std::ios_base [C++], boolalpha", "std::ios_base [C++], cur", "std::ios_base [C++], dec", "std::ios_base [C++], end", "std::ios_base [C++], eofbit", "std::ios_base [C++], failbit", "std::ios_base [C++], fixed", "std::ios_base [C++], floatfield", "std::ios_base [C++], goodbit", "std::ios_base [C++], hex", "std::ios_base [C++], in", "std::ios_base [C++], internal", "std::ios_base [C++], left", "std::ios_base [C++], oct", "std::ios_base [C++], out", "std::ios_base [C++], right", "std::ios_base [C++], scientific", "std::ios_base [C++], showbase", "std::ios_base [C++], showpoint", "std::ios_base [C++], showpos", "std::ios_base [C++], skipws", "std::ios_base [C++], trunc", "std::ios_base [C++], unitbuf", "std::ios_base [C++], uppercase", "std::ios_base [C++], failure", "std::ios_base [C++], flags", "std::ios_base [C++], getloc", "std::ios_base [C++], imbue", "std::ios_base [C++], Init", "std::ios_base [C++], iword", "std::ios_base [C++], precision", "std::ios_base [C++], pword", "std::ios_base [C++], register_callback", "std::ios_base [C++], setf", "std::ios_base [C++], sync_with_stdio", "std::ios_base [C++], unsetf", "std::ios_base [C++], width", "std::ios_base [C++], xalloc"] +ms.custom: devdivchpfy22 --- + # `ios_base` Class -The class describes the storage and member functions common to both input and output streams that do not depend on the template parameters. (The class template [`basic_ios`](../standard-library/basic-ios-class.md) describes what is common and is dependent on template parameters.) +The class describes the storage and member functions common to both input and output streams that don't depend on the template parameters. (The class template [`basic_ios`](../standard-library/basic-ios-class.md) describes what is common and is dependent on template parameters.) An object of class `ios_base` stores formatting information, which consists of: @@ -192,7 +194,7 @@ namespace std { ### Remarks -The value returned by `what()` is a copy of `_Message`, possibly augmented with a test based on `_Code`. If `_Code` is not specified, the default value is `make_error_code(io_errc::stream)`. +The value returned by `what()` is a copy of `_Message`, possibly augmented with a test based on `_Code`. If `_Code` isn't specified, the default value is `make_error_code(io_errc::stream)`. ### Example @@ -543,7 +545,7 @@ The object being assigned to. ### Remarks -The operator copies the stored formatting information, making a new copy of any extensible arrays. It then returns `*this`. Note that the callback stack is not copied. +The operator copies the stored formatting information, making a new copy of any extensible arrays. It then returns `*this`. The callback stack isn't copied. This operator is only used by classes derived from `ios_base`. @@ -853,11 +855,11 @@ Previous setting for this function. ### Remarks -The static member function stores a `stdio` sync flag, which is initially `true`. When `true`, this flag ensures that operations on the same file are properly synchronized between the [`iostreams`](../standard-library/iostreams-conventions.md) functions and those defined in the C++ Standard Library. Otherwise, synchronization may or may not be guaranteed, but performance may be improved. The function stores *`_Sync`* in the `stdio` sync flag and returns its previous stored value. You can call it reliably only before performing any operations on the standard streams. +The static member function stores a `stdio` sync flag, which is initially `true`. When `true`, this flag ensures that operations on the same file are properly synchronized between the [`iostreams`](../standard-library/iostreams-conventions.md) functions and functions defined in the C++ Standard Library. Otherwise, synchronization may or may not be guaranteed, but performance may be improved. The function stores *`_Sync`* in the `stdio` sync flag and returns its previous stored value. You can call it reliably only before performing any operations on the standard streams. ## `unsetf` -Turns the specified flags off. +Turns off the specified flags. ```cpp void unsetf( diff --git a/docs/standard-library/ios-functions.md b/docs/standard-library/ios-functions.md index 2b635a8726..458210579a 100644 --- a/docs/standard-library/ios-functions.md +++ b/docs/standard-library/ios-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["xiosbase/std::defaultfloat", "xiosbase/std::boolalpha", "xiosbase/std::dec", "ios/std::fixed", "ios/std::hex", "ios/std::internal", "ios/std::left", "ios/std::noboolalpha", "ios/std::noshowbase", "ios/std::noshowpoint", "ios/std::noshowpos", "ios/std::noskipws", "ios/std::nounitbuf", "ios/std::nouppercase", "ios/std::oct", "ios/std::right", "ios/std::scientific", "ios/std::showbase", "ios/std::showpoint", "ios/std::showpos", "ios/std::skipws", "ios/std::unitbuf", "ios/std::uppercase"] -ms.assetid: 1382d53f-e531-4b41-adf6-6a1543512e51 helpviewer_keywords: ["std::defaultfloat [C++]", "std::boolalpha [C++]", "std::dec [C++]", "std::fixed [C++]", "std::hex [C++]", "std::hexfloat [C++]", "std::io_errc [C++]", "std::internal [C++]", "std::iostream_category [C++]", "std::is_error_code_enum [C++]", "std::left [C++]", "std::make_error_code [C++]", "std::make_error_condition [C++]", "std::noboolalpha [C++]", "std::noshowbase [C++]", "std::noshowpoint [C++]", "std::noshowpos [C++]", "std::noskipws [C++]", "std::nounitbuf [C++]", "std::nouppercase [C++]", "std::oct [C++]", "std::right [C++]", "std::scientific [C++]", "std::showbase [C++]", "std::showpoint [C++]", "std::showpos [C++]", "std::skipws [C++]", "std::unitbuf [C++]", "std::uppercase [C++]"] --- # `` functions @@ -29,7 +28,7 @@ A reference to the object from which *str* is derived. By default, variables of type **`bool`** are displayed as 1 or 0. -`boolalpha` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)( `ios_base::boolalpha`), and then returns *str*. +`boolalpha` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)(`ios_base::boolalpha`), and then returns *str*. [noboolalpha](../standard-library/ios-functions.md#noboolalpha) reverses the effect of `boolalpha`. @@ -81,7 +80,7 @@ A reference to the object from which *str* is derived. By default, integer variables are displayed in base 10. -`dec` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)( `ios_base::dec`, `ios_base::basefield`), and then returns *str*. +`dec` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)(`ios_base::dec`, `ios_base::basefield`), and then returns *str*. ### Example @@ -151,7 +150,7 @@ A reference to the object from which *str* is derived. `fixed` is the default display notation for floating-point numbers. [scientific](../standard-library/ios-functions.md#scientific) causes floating-point numbers to be displayed using scientific notation. -The manipulator effectively calls *str*.[setf](../standard-library/ios-base-class.md#setf)( `ios_base::fixed`, `ios_base::floatfield` ), and then returns *str*. +The manipulator effectively calls *str*.[setf](../standard-library/ios-base-class.md#setf)(`ios_base::fixed`, `ios_base::floatfield`), and then returns *str*. ### Example @@ -199,7 +198,7 @@ A reference to the object from which *str* is derived. By default, integer variables are displayed in base 10 notation. [dec](../standard-library/ios-functions.md#dec) and [oct](../standard-library/ios-functions.md#oct) also change the way integer variables appear. -The manipulator effectively calls `str`**.**[setf](../standard-library/ios-base-class.md#setf)( `ios_base::hex`, `ios_base::basefield`), and then returns *str*. +The manipulator effectively calls `str`**.**[setf](../standard-library/ios-base-class.md#setf)(`ios_base::hex`, `ios_base::basefield`), and then returns *str*. ### Example @@ -456,7 +455,7 @@ A reference to the object from which *str* is derived. `noshowpos` is on by default. -The manipulator effectively calls `str.`[unsetf](../standard-library/ios-base-class.md#unsetf)`(ios_base::showps)`, then returns *str*. +The manipulator effectively calls `str.`[unsetf](../standard-library/ios-base-class.md#unsetf)`(ios_base::showpos)`, then returns *str*. ### Example diff --git a/docs/standard-library/iota-view-class.md b/docs/standard-library/iota-view-class.md new file mode 100644 index 0000000000..ecc936307c --- /dev/null +++ b/docs/standard-library/iota-view-class.md @@ -0,0 +1,204 @@ +--- +title: iota_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) iota_view class: a factory that generates a view from a bounded or unbounded series of repeatedly incrementing values." +ms.date: 11/04/2022 +f1_keywords: ["ranges/std::iota_view", "ranges/std::iota_view::base", "ranges/std::iota_view::begin", "ranges/std::iota_view::end", "ranges/std::iota_view::size", "ranges/std::iota_view::empty", "ranges/std::iota_view::operator bool", "ranges/std::iota_view::back", "ranges/std::iota_view::front", "ranges/std::iota_view::operator[]"] +helpviewer_keywords: ["std::ranges::iota_view [C++]", "std::ranges::iota_view [C++], base", "std::ranges::iota_view [C++], begin", "std::ranges::iota_view [C++], end", "std::ranges::iota_view [C++], size", "std::ranges::iota_view [C++], empty", "std::ranges::iota_view [C++], operator bool", "std::ranges::iota_view [C++], front", "std::ranges::iota_view [C++], back", "std::ranges::iota_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `iota_view` class (C++ Standard Library) + +Generates a view of a sequence of elements by repeatedly incrementing an initial value. The sequence can be bounded or unbounded. + +## Syntax + +```cpp +template + requires __WeaklyEqualityComparableWith && std::copyable +class iota_view : public ranges::view_interface>; +``` + +### Template parameters + +*`W`*\ + The type of the values in the sequence. The specified type must support `operator++`. + +*`Bound`*\ +The type of the end value. If *`Bound`* is `std::unreachable_sentinel_t` (the default value), then the view is unbounded. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::iota`](range-adaptors.md#iota) | +| **Underlying range** | Not applicable because this view generates its members | +| **Element type** | Same as the template parameter `W` | +| **View iterator category** | Supports [`input_range`](range-concepts.md#input_range) up to [`random_access_range`](range-concepts.md#random_access_range), depending on the type of `W` | +| **Sized** | Only if the range has an end value, that is, it isn't an infinite series | +| **Is `const`-iterable** | Yes | +| **Common range** | Only if `Bound` is the same type as `W` | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) C++20| Construct the view. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +A good way to create a `iota_view` is by using the [`iota`](range-adaptors.md#iota) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +The sequence of values can be integral values such as 1,2,3 or 'a', 'b', 'c' or consecutive elements from a range. + +This view is typically used to iterate over a series of values. For example: + +```cpp +for (int i : iota_view{1, 10}) // iterate over a view of the integers 1 through 9 +{ + std::cout << i << ' '; // 1 2 3 4 5 6 7 8 9 +} +``` + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of an `iota_view`. + +```cpp +1) iota_view() requires std::default_initializable = default; +2) constexpr explicit iota_view(W value); +3) constexpr iota_view(std::type_identity_t value, std::type_identity_t bound); +4) constexpr iota_view( /*iterator*/ first, /*sentinel*/ last ); +``` + +### Parameters + +*`value`*\ +The starting value for the series. + +*`bound`*\ +The bound of the series. It's one greater than the last value in the series. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Create an `iota_view` with a starting and ending value determined by the default-initialized template type `W`.\ +2\) Create an `iota_view` with the specified starting value and ending value determined by the value-initialized type `W`.\ +3\) Create a bounded `iota_view` with the specified starting value and ending value. The ending value is one less than the last value specified.\ +4\) Used to create subviews. For example, `std::ranges::iota_view(start, end);` where `start` and `end` are iterators to the start and end of the subview. + +Rather than create this class directly, an easy way to create a `iota_view` is by using the [`iota`](range-adaptors.md#iota) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +If the bound's type is `unreachable_sentinel_t`, the resulting view is bounded. + +When you use one of the constructors that value-initializes the bound, the bound will be the default-initialized value for that type. For example, `iota_view{}` is an empty range of `int` since the default-constructed int value and bound are both `0`. Also, `iota_view{-4}` is `-4, -3, -2, -1` because the default-constructed `int` bound is `0`. + +## `iota_view` constructor example + +```cpp +// requires /std:c++20, or later +#include +#include +#include + +int main() +{ + std::ranges::iota_view iv; // create an iota_view with an unbounded range, starting at 0 + std::ranges::iota_view iv2(5); // create an iota_view with an unbounded range, starting at 5. + std::ranges::iota_view iv3{5, 10}; // create an iota_view with a bounded range, starting at 5 and ending at 9 + + std::vector v{10, 20, 35, 45, 50, 66, 77, 82, 90, 100}; + auto start = std::ranges::find(v, 35); + auto end = std::ranges::find(v, 82); + for (auto &&val : std::ranges::iota_view(start, end)) + { + std::cout << *val << ' '; // outputs 35 45 50 66 77 + } +} +``` + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +## `end` + +Get the end sentinel at the end of the view. + +```cpp +constexpr auto end(); +constexpr auto end() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +If the `iota_view` is unbounded, returns `std::unreachable_sentinel`. + +If the `iota_view` is bounded, returns an iterator pointing at the sentinel past the last value in the sequence. + +## `size` + +Get the number of elements in the view. The `iota_view` must be bounded. + +```cpp +constexpr auto size() requires + (same_as && advanceable ) || + (integral && integral) || + sized_sentinel_for; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `iota_view`. + +### Remarks + +You can't call `size()` on an unbounded `iota_view`. + +## See also + +[``](ranges.md)\ +[`iota()` range adaptor](range-adaptors.md#iota)\ +[`std::numerics::iota`](numeric-functions.md#iota)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/is-clock-struct.md b/docs/standard-library/is-clock-struct.md index f4f99edaf5..86d02a8daa 100644 --- a/docs/standard-library/is-clock-struct.md +++ b/docs/standard-library/is-clock-struct.md @@ -2,8 +2,9 @@ description: "Learn more about is_clock struct" title: "is_clock class" ms.date: 07/19/2021 -f1_keywords: ["chrono/std::is_clock"] +f1_keywords: ["chrono/std::is_clock", "std::chrono::is_clock::operator()", "std::chrono::is_clock::operator bool", "std::chrono::value"] helpviewer_keywords: ["std::chrono [C++], is_clock"] +dev_langs: ["C++"] --- # `is_clock` structure @@ -13,13 +14,13 @@ A type trait that determines whether the specified type meets the requirements t ## Syntax ```cpp -template struct is_clock; // c++ 20 +template struct is_clock; // C++20 ``` **Helper variable template** ```cpp - template inline constexpr bool is_clock_v = is_clock::value; // c++ 20 + template inline constexpr bool is_clock_v = is_clock::value; // C++20 ``` ### Parameters @@ -56,7 +57,6 @@ int main() is_clock ic; std::cout << std::boolalpha << ic.value << ", " << ic() << ", " << (bool)ic; - return 0; } ``` @@ -66,9 +66,9 @@ true, true, true ## Requirements -**Header:** \<`chrono`> +**Header:** `` -**Namespace:** `std` +**Namespace:** `std::chrono` **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/standard-library/is-error-code-enum-class.md b/docs/standard-library/is-error-code-enum-class.md index 320d487d28..68b900c9dd 100644 --- a/docs/standard-library/is-error-code-enum-class.md +++ b/docs/standard-library/is-error-code-enum-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: is_error_code_enum Class" title: "is_error_code_enum Class" +description: "Learn more about: is_error_code_enum Class" ms.date: "11/04/2016" f1_keywords: ["system_error/std::is_error_code_enum"] helpviewer_keywords: ["is_error_code_enum class"] -ms.assetid: cee5be2d-7c20-4cec-a352-1ab8b7d32601 --- # is_error_code_enum Class @@ -13,8 +12,8 @@ Represents a type predicate that tests for the [error_code](../standard-library/ ## Syntax ```cpp -template <_Enum> - class is_error_code_enum; +template +struct is_error_code_enum; ``` ## Remarks diff --git a/docs/standard-library/is-error-condition-enum-class.md b/docs/standard-library/is-error-condition-enum-class.md index cf277036fe..f5599c93e1 100644 --- a/docs/standard-library/is-error-condition-enum-class.md +++ b/docs/standard-library/is-error-condition-enum-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: is_error_condition_enum Class" title: "is_error_condition_enum Class" +description: "Learn more about: is_error_condition_enum Class" ms.date: "11/04/2016" f1_keywords: ["system_error/std::is_error_condition_enum"] helpviewer_keywords: ["is_error_condition_enum class"] -ms.assetid: 752bb87a-c61c-4304-9254-5aaf228b59c0 --- # is_error_condition_enum Class @@ -13,8 +12,8 @@ Represents a type predicate that tests for the [error_condition](../standard-lib ## Syntax ```cpp -template <_Enum> - class is_error_condition_enum; +template +struct is_error_condition_enum; ``` ## Remarks diff --git a/docs/standard-library/is-placeholder-class.md b/docs/standard-library/is-placeholder-class.md index 847f67bb93..b5e7684077 100644 --- a/docs/standard-library/is-placeholder-class.md +++ b/docs/standard-library/is-placeholder-class.md @@ -12,9 +12,11 @@ Tests if type is a placeholder. ## Syntax +```cpp struct is_placeholder { static const int value; }; +``` ## Remarks diff --git a/docs/standard-library/istream-functions.md b/docs/standard-library/istream-functions.md index 5393a82b01..8c6d33665e 100644 --- a/docs/standard-library/istream-functions.md +++ b/docs/standard-library/istream-functions.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["istream/std::swap", "istream/std::ws"] -ms.assetid: 0301ea0d-4ded-4841-83dd-4253b55b3188 --- # `` functions -[swap](#istream_swap)\ -[ws](#ws) +The `` header provides the following functions: ## swap diff --git a/docs/standard-library/istream-iterator-class.md b/docs/standard-library/istream-iterator-class.md index b90ca6e6dc..4961861016 100644 --- a/docs/standard-library/istream-iterator-class.md +++ b/docs/standard-library/istream-iterator-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: istream_iterator Class" title: "istream_iterator Class" -ms.date: "11/04/2016" +description: "Learn more about: istream_iterator Class" +ms.date: 06/15/2022 f1_keywords: ["iterator/std::istream_iterator", "iterator/std::istream_iterator::char_type", "iterator/std::istream_iterator::istream_type", "iterator/std::istream_iterator::traits_type"] helpviewer_keywords: ["std::istream_iterator [C++]", "std::istream_iterator [C++], char_type", "std::istream_iterator [C++], istream_type", "std::istream_iterator [C++], traits_type"] -ms.assetid: fb52a8cd-7f71-48d1-b73e-4b064e2a8d16 +ms.custom: devdivchpfy22 --- + # istream_iterator Class Describes an input iterator object. It extracts objects of class `Type` from an input stream, which it accesses through an object it stores, of type `pointer` to `basic_istream`< `CharType`, `Traits`>. @@ -13,7 +14,7 @@ Describes an input iterator object. It extracts objects of class `Type` from an ## Syntax ```cpp -template , class Distance = ptrdiff_t,> +template , class Distance = ptrdiff_t> class istream_iterator : public iterator< input_iterator_tag, Type, Distance, @@ -132,7 +133,7 @@ The input stream to be read use to initialize the `istream_iterator`. The First constructor initializes the input stream pointer with a null pointer and creates an end-of-stream iterator. The second constructor initializes the input stream pointer with *&_Istr*, then attempts to extract and store an object of type `Type`. -The end-of-stream iterator can be use to test whether an `istream_iterator` has reached the end of a stream. +The end-of-stream iterator can be used to test whether an `istream_iterator` has reached the end of a stream. ### Example @@ -158,7 +159,7 @@ int main( ) istream_iterator intvecRead ( cin ); // Default constructor will test equal to end of stream - // for delimiting source range of vecor + // for delimiting source range of vector copy ( intvecRead , istream_iterator( ) , vec.begin ( ) ); cin.clear ( ); diff --git a/docs/standard-library/istream-typedefs.md b/docs/standard-library/istream-typedefs.md index 2fb9ef751e..9d43bdeaa1 100644 --- a/docs/standard-library/istream-typedefs.md +++ b/docs/standard-library/istream-typedefs.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["istream/std::iostream", "istream/std::istream", "istream/std::wiostream", "istream/std::wistream"] -ms.assetid: 55bc1f84-53a7-46ca-a36f-ac6ef75d0374 --- # `` typedefs -[iostream](#iostream)\ -[istream](#istream)\ -[wiostream](#wiostream)\ -[wistream](#wistream) +The `` header provides the following typedefs: ## iostream diff --git a/docs/standard-library/istreambuf-iterator-class.md b/docs/standard-library/istreambuf-iterator-class.md index 69f13f72c9..9b05304ed1 100644 --- a/docs/standard-library/istreambuf-iterator-class.md +++ b/docs/standard-library/istreambuf-iterator-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: istreambuf_iterator Class" title: "istreambuf_iterator Class" -ms.date: "11/04/2016" +ms.date: 06/15/2022 f1_keywords: ["streambuf/std::istreambuf_iterator", "iterator/std::istreambuf_iterator::char_type", "iterator/std::istreambuf_iterator::int_type", "iterator/std::istreambuf_iterator::istream_type", "iterator/std::istreambuf_iterator::streambuf_type", "iterator/std::istreambuf_iterator::traits_type", "iterator/std::istreambuf_iterator::equal"] helpviewer_keywords: ["std::istreambuf_iterator [C++]", "std::istreambuf_iterator [C++], char_type", "std::istreambuf_iterator [C++], int_type", "std::istreambuf_iterator [C++], istream_type", "std::istreambuf_iterator [C++], streambuf_type", "std::istreambuf_iterator [C++], traits_type", "std::istreambuf_iterator [C++], equal"] ms.assetid: 39002da2-61a6-48a5-9d0c-5df8271f6038 +ms.custom: devdivchpfy22 --- + # istreambuf_iterator Class The class template istreambuf_iterator describes an input iterator object that extracts character elements from an input stream buffer, which it accesses through an object it stores, of type pointer to `basic_streambuf`\< **CharType**, **Traits**>. @@ -30,7 +32,7 @@ The type that represents the character type for the istreambuf_iterator. This ar The istreambuf_iterator class must satisfy the requirements for an input iterator. -After constructing or incrementing an object of class istreambuf_iterator with a non-null stored pointer, the object effectively attempts to extract and store an object of type *CharType* from the associated input stream. The extraction may be delayed, however, until the object is actually dereferenced or copied. If the extraction fails, the object effectively replaces the stored pointer with a null pointer, thus making an end-of-sequence indicator. +After constructing or incrementing an object of class istreambuf_iterator with a non-null stored pointer, the object effectively attempts to extract and store an object of type *CharType* from the associated input stream. The extraction may be delayed, however, until the object is dereferenced or copied. If the extraction fails, the object effectively replaces the stored pointer with a null pointer, thus making an end-of-sequence indicator. ### Constructors @@ -60,7 +62,6 @@ After constructing or incrementing an object of class istreambuf_iterator with a |-|-| |[operator*](#op_star)|The dereferencing operator returns the next character in the stream.| |[operator++](#op_add_add)|Either returns the next character from the input stream or copies the object before incrementing it and returns the copy.| -|[operator->](#op_arrow)|Returns the value of a member, if any.| ## Requirements @@ -132,7 +133,7 @@ The iterator for which to check for equality. ### Remarks -A range is defined by the `istreambuf_iterator` to the current position and the end-of-stream iterator, but since all non-end-of stream iterators are equivalent under the `equal` member function, it is not possible to define any subranges using `istreambuf_iterator`s. The `==` and `!=` operators have the same semantics. +A range is defined by the `istreambuf_iterator` to the current position and the end-of-stream iterator, but since all non-end-of stream iterators are equivalent under the `equal` member function, it isn't possible to define any subranges using `istreambuf_iterator`s. The `==` and `!=` operators have the same semantics. ### Example @@ -347,18 +348,6 @@ int main( ) } ``` -## `istreambuf_iterator::operator->` - -Returns the value of a member, if any. - -```cpp -const Elem* operator->() const; -``` - -### Return Value - -The operator returns **&\*\*this**. - ## istreambuf_iterator::streambuf_type A type that provides for the stream type of the istreambuf_iterator. diff --git a/docs/standard-library/iterator-concepts.md b/docs/standard-library/iterator-concepts.md new file mode 100644 index 0000000000..027dd4b630 --- /dev/null +++ b/docs/standard-library/iterator-concepts.md @@ -0,0 +1,484 @@ +--- +title: "Iterator concepts" +description: "Learn more about iterator concepts." +ms.date: 12/16/2022 +f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_iterator", "ranges/std::ranges::borrowed_iterator", "ranges/std::ranges::common_iterator", "ranges/std::ranges::contiguous_iterator", "ranges/std::ranges::forward_iterator", "ranges/std::ranges::input_iterator", "ranges/std::ranges::output_iterator", "ranges/std::ranges::random_access_iterator", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_iterator", "ranges/std::ranges::view", "ranges/std::ranges::viewable_iterator"] +helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_iterator", "std::ranges [C++], ranges::borrowed_iterator", "std::ranges [C++], ranges::common_iterator", "std::ranges [C++], ranges::contiguous_iterator", "std::ranges [C++], ranges::forward_iterator", "std::ranges [C++], ranges::input_iterator", "std::ranges [C++], ranges::output_iterator", "std::ranges [C++], ranges::random_access_iterator", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_iterator", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_iterator"] +--- +# Iterator concepts + +Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiation, specify template argument requirements in a readable form, and provide more succinct template related compiler errors. + +Consider the following example, which defines a concept to prevent instantiating the template with a type that doesn't support division: + +```cpp +// requires /std:c++20 or later +#include + +// Definition of dividable concept which requires +// that arguments a & b of type T support division +template +concept dividable = requires (T a, T b) +{ + a / b; +}; + +// Apply the concept to a template. +// The template will only be instantiated if argument T supports division. +// This prevents the template from being instantiated with types that don't support division. +// This could have been applied to the parameter of a template function, but because +// most of the concepts in the library are applied to classes, this form is demonstrated. +template requires dividable +class DivideEmUp +{ +public: + T Divide(T x, T y) + { + return x / y; + } +}; + +int main() +{ + DivideEmUp dividerOfInts; + std::cout << dividerOfInts.Divide(6, 3); // outputs 2 + // The following line will not compile because the template can't be instantiated + // with char* because char* can be divided + DivideEmUp dividerOfCharPtrs; // compiler error: cannot deduce template arguments +} +``` + +When you pass the compiler switch `/diagnostics:caret` to Visual Studio 2022 version 17.4 preview 4 or later, the error that concept `dividable` evaluated to false will point directly to the expression requirement `(a / b)` that failed. + +Iterator concepts are defined in the `std` namespace, and are declared in the `` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on. + +There are six categories of iterators. They're directly related to the categories of ranges listed under [Range concepts](ranges.md#range-concepts). + +The following iterator concepts are listed in order of increasing capability. `input_or_output_iterator` is at the low end of the capability hierarchy, and `contiguous_iterator` is at the high end. Iterators higher in the hierarchy can generally be used in place of those that are lower, but not vice-versa. For example, a `random_access_iterator` iterator can be used in place of a `forward_iterator`, but not the other way around. An exception is `input_iterator`, which can't be used in place of `output_iterator` because it can't write. + +:::image type="content" source="media/iterator-hiearchy.svg" alt-text="Diagram of the iterator hierarchy. input_or_output_iterator is the base. input_iterator and output_iterator are shown as refining input_or_output_iterator. forward_iterator is next and refines both input_iterator and output_iterator. bidirectional_iterator refines forward_iterator. random_access_iterator refines bidirectional_iterator. Finally, contiguous_iterator refines random_access_iterator"::: + +In the following table, "Multi-pass" refers to whether the iterator can revisit the same element more than once. For example, `vector::iterator` is a multi-pass iterator because you can make a copy of the iterator, read the elements in the collection, and then restore the iterator to the value in the copy, and revisit the same elements again. If an iterator is single-pass, you can only visit the elements in the collection once. + +In the following table, "Example types" refers to collections/iterators that satisfy the concept. + +| Iterator concept | Description | Direction | Read/write | Multi-pass | Example types | +|--|--|--|--|--|--| +| [`input_or_output_iterator`](#input_or_output_iterator)C++20 | The basis of the iterator concept taxonomy. | Forward | Read/write | no | `istream_iterator`, `ostream_iterator` | +| [`output_iterator`](#output_iterator)C++20 | Specifies an iterator that you can write to. | Forward | Write | no | `ostream`, `inserter` | +| [`input_iterator`](#input_iterator)C++20 | Specifies an iterator that you can read from once. | Forward | Read | no | `istream`, `istreambuf_iterator` | +| [`forward_iterator`](#forward_iterator)C++20 | Specifies an iterator that can read (and possibly write) multiple times. | Forward | Read/write | yes | `vector`, `list` | +| [`bidirectional_iterator`](#bidirectional_iterator)C++20 | Specifies an iterator that you can read and write both forwards and backwards. | Forward or backward | Read/write | yes | `list`, `set`, `multiset`, `map`, and `multimap`. | +| [`random_access_iterator`](#random_access_iterator)C++20 | Specifies an iterator that you can read and write by index. | Forward or backward | Read/write | yes | `vector`, `array`, `deque` | +| [`contiguous_iterator`](#contiguous_iterator)C++20 | Specifies an iterator whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. | Forward or backward | Read/write | yes | `array`, `vector`, `string`.| + +Other iterator concepts include: + +| Iterator concept | Description | +|--|--| +| [`sentinel_for`](#sentinel_for)C++20 | Specifies that a type is a sentinel for an iterator type. | +| [`sized_sentinel_for`](#sized_sentinel_for)C++20 | Specifies that an iterator and its sentinel can be subtracted (using `-`) to find their difference in constant time. | + +## `bidirectional_iterator` + +A `bidirectional_iterator` supports reading and writing forwards and backwards. + +```cpp +template +concept bidirectional_iterator = + forward_iterator && + derived_from && + requires(I i) { + {--i} -> same_as; + {i--} -> same_as; +}; +``` + +### Parameters + +*`I`*\ +The iterator to test to see if it's a `bidirectional_iterator`. + +### Remarks + +A `bidirectional_iterator` has the capabilities of a `forward_iterator`, but can also iterate backwards. + +Some examples of containers that can be used with a `bidirectional_iterator` are `set`, `multiset`, `map`, `multimap`, `vector`, and `list`. + +### Example: `bidirectional_iterator` + +The following example uses the `bidirectional_iterator` concept to show that `vector` has a `bidirectional_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::cout << std::boolalpha << std::bidirectional_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::contiguous_iterator; // outputs true +} +``` + +## `contiguous_iterator` + +Specifies an iterator whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. + +```cpp +template + concept contiguous_iterator = + random_access_iterator && + derived_from && + is_lvalue_reference_v> && + same_as, remove_cvref_t>> && + requires(const I& i) { + { to_address(i) } -> same_as>>; + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's a `contiguous_iterator`. + +### Remarks + +A `contiguous_iterator` can be accessed by pointer arithmetic because the elements are laid out sequentially in memory and are the same size. Some examples of a `contiguous_iterator` are `array`, `vector`, and `string`. + +### Example: `contiguous_iterator` + +The following example uses the `contiguous_iterator` concept to show that a `vector` has a `contiguous_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a contiguous_iterator + std::cout << std::boolalpha << std::contiguous_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::contiguous_iterator; // outputs true +} +``` + +## `forward_iterator` + +Has the capabilities of an `input_iterator` and an `output_iterator`. Supports iterating over a collection multiple times. + +```cpp +template + concept forward_iterator = + input_iterator && + derived_from && + incrementable && + sentinel_for; +``` + +### Parameters + +*`I`*\ +The iterator to test to see if it's a `forward_iterator`. + +### Remarks + +A `forward_iterator` can only move forward. + +Some examples of containers that can be used with a `forward_iterator` are `vector`, `list`, `unordered_set`, `unordered_multiset`, `unordered_map`, and `unordered_multimap`. + +### Example: `forward_iterator` + +The following example uses the `forward_iterator` concept to show that a `vector` has a `forward_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a forward_iterator + std::cout << std::boolalpha << std::forward_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::forward_iterator; // outputs true +} +``` + +## `input_iterator` + +An `input_iterator` is an iterator that you can read from at least once. + +```cpp +template +concept input_iterator = + input_or_output_iterator && + indirectly_readable && + requires { typename ITER_CONCEPT(I); } && + derived_from; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `input_iterator`. + +### Remarks + +Calling `begin()` on an `input_iterator` more than once results in undefined behavior. A type that only models `input_iterator` isn't multi-pass. Consider reading from standard input (`cin`) for example. In this case, you can only read the current element once and you can't re-read characters you've already read. An `input_iterator` only reads forward, not backwards. + +### Example: `input_iterator` + +The following example uses the `input_iterator` concept to show that an `istream_iterator` has an `input_iterator`: + +```cpp +// requires /std:c++20 or later +#include + +int main() +{ + // Show that a istream_iterator has an input_iterator + std::cout << std::boolalpha << std::input_iterator>; // outputs true +} +``` + +## `input_or_output_iterator` + +An `input_or_output_iterator` is the basis of the iterator concept taxonomy. It supports dereferencing and incrementing +an iterator. Every iterator models `input_or_output_iterator`. + +```cpp +template +concept input_or_output_iterator = + requires(I i) { + { *i } -> can-reference; + } && + weakly_incrementable; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `input_or_output_iterator`. + +### Remarks + +The concept `can-reference` means that the type `I` is a reference, a pointer, or a type that can be implicitly converted to a reference. + +### Example: `input_or_output_iterator` + +The following example uses the `input_or_output_iterator` concept to show that `vector` has an `input_or_output_iterator`: + +```cpp +// requires /std:c++20 or later +#include + +int main() +{ + // Show that a vector has an input_or_output_iterator + std::cout << std::boolalpha << std::input_or_output_iterator::iterator> << '\n'; // outputs true + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::input_or_output_iterator; // outputs true +} +``` + +## `output_iterator` + +An `output_iterator` is an iterator that you can write to. + +```cpp +template +concept output_iterator = + input_or_output_iterator && + indirectly_writable && + requires(I i, T&& t) { + *i++ = std::forward(t); + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `output_iterator`. + +*`T`*\ +The type of the values to write. + +### Remarks + +An `output_iterator` is single pass. That is, it can only write to the same element once. + +### Example: `output_iterator` + +The following example uses the `output_iterator` concept to show that `vector` has an `output_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has an output_iterator + std::cout << std::boolalpha << std::output_iterator::iterator, int> << "\n"; // outputs "true" + + // another way to test + std::vector v = {0,1,2,3,4,5}; + std::cout << std::boolalpha << std::output_iterator; // outputs true +} +``` + +## `random_access_iterator` + +A `random_access_iterator` can read or write by index. + +```cpp +template +concept random_access_iterator = + bidirectional_iterator && + derived_from && + totally_ordered && + sized_sentinel_for && + requires(I i, const I j, const iter_difference_t n) { + { i += n } -> same_as; + { j + n } -> same_as; + { n + j } -> same_as; + { i -= n } -> same_as; + { j - n } -> same_as; + { j[n] } -> same_as>; + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's a `random_access_iterator`. + +### Remarks + +A `random_access_iterator` has the capabilities of an `input_iterator`, `output_iterator`, `forward_iterator`, and `bidirectional_iterator`. + +Some examples of a `random_access_iterator` are `vector`, `array`, and `deque`. + +### Example: `random_access_iterator` + +The following example shows that a `vector` has a `random_access_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a random_access_iterator + std::cout << std::boolalpha << std::random_access_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::random_access_iterator; // outputs true +} +``` + +## `sentinel_for` + +Specifies that a type is a sentinel for an iterator. + +```cpp +template +concept sentinel_for = + semiregular && + input_or_output_iterator && + weakly-equality-comparable-with ; +``` + +### Parameters + +*`I`*\ +The iterator type. + +*`S`*\ +The type to test to see if it's a sentinel for `I`. + +### Remarks + +A sentinel is a type that can be compared to an iterator to determine if the iterator has reached the end. This concept determines if a type is a sentinel for one of the `input_or_output_iterator` types, which includes `input_iterator`, `output_iterator`, `forward_iterator`, `bidirectional_iterator`, `random_access_iterator`, and `contiguous_iterator`. + +### Example: `sentinel_for` + +The following example uses the `sentinel_for` concept to show that `vector::iterator` is a sentinel for `vector`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::vector v = {0, 1, 2}; + std::vector::iterator i = v.begin(); + // show that vector::iterator is a sentinel for vector + std::cout << std::boolalpha << std::sentinel_for::iterator, decltype(i)>; // outputs true +} +``` + +## `sized_sentinel_for` + +Test that an iterator and its sentinel can be subtracted using `-` to find the difference, in constant time. + +```cpp +template +concept sized_sentinel_for = + sentinel_for && + !disable_sized_sentinel_for, remove_cv_t> && + requires(const I& i, const S& s) { + {s - i} -> same_as>; + {i - s} -> same_as>; + }; +``` + +### Parameters + +*`I`*\ +The iterator type. + +*`S`*\ +The sentinel type to test. + +### Remarks + +### Example: `sized_sentinel_for` + +The following example uses the `sized_sentinel_for` concept to verify that the sentinel for a `vector` can be subtracted from the vectors iterator in constant time: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::vector v = { 1, 2, 3 }; + std::vector::iterator i = v.begin(); + std::vector::iterator end = v.end(); + // use the sized_sentinel_for concept to verify that i can be subtracted from end in constant time + std::cout << std::boolalpha << std::sized_sentinel_for << "\n"; // outputs true + std::cout << end - i; // outputs 3 +} +``` + +## See also + +[Range concepts](range-concepts.md)\ +[Range adaptors](range-adaptors.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/iterator-functions.md b/docs/standard-library/iterator-functions.md index feb86fe2e2..99b7df088f 100644 --- a/docs/standard-library/iterator-functions.md +++ b/docs/standard-library/iterator-functions.md @@ -1,35 +1,34 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "11/04/2016" f1_keywords: ["xutility/std::advance", "xutility/std::back_inserter", "xutility/std::begin", "xutility/std::cbegin", "xutility/std::cend", "xutility/std::distance", "xutility/std::end", "xutility/std::front_inserter", "xutility/std::inserter", "xutility/std::make_checked_array_iterator", "xutility/std::make_move_iterator", "xutility/std::make_unchecked_array_iterator", "xutility/std::next", "xutility/std::prev"] -ms.assetid: 4a57c9a3-7e36-411f-8655-e0be2eec88e7 helpviewer_keywords: ["std::advance [C++]", "std::back_inserter [C++]", "std::begin [C++]", "std::cbegin [C++]", "std::cend [C++]", "std::distance [C++]", "std::end [C++]", "std::front_inserter [C++]", "std::inserter [C++]", "std::make_checked_array_iterator [C++]", "std::make_move_iterator [C++]", "std::make_unchecked_array_iterator [C++]", "std::next [C++]", "std::prev [C++]"] --- # `` functions -## advance +## `advance` Increments an iterator by a specified number of positions. ```cpp template - void advance(InputIterator& InIt, Distance Off); +void advance(InputIterator& InIt, Distance Off); ``` ### Parameters -*InIt*\ +*`InIt`*\ The iterator that is to be incremented and that must satisfy the requirements for an input iterator. -*Off*\ +*`Off`*\ An integral type that is convertible to the iterator's difference type and that specifies the number of increments the position of the iterator is to be advanced. ### Remarks -The range advanced through must be nonsingular, where the iterators must be dereferenceable or past the end. +The range must be nonsingular, where the iterators must be dereferenceable or past the end. -If the `InputIterator` satisfies the requirements for a bidirectional iterator type, then *Off* may be negative. If `InputIterator` is an input or forward iterator type, *Off* must be nonnegative. +If the `InputIterator` satisfies the requirements for a bidirectional iterator type, then *`Off`* may be negative. If `InputIterator` is an input or forward iterator type, *`Off`* must be nonnegative. The advance function has constant complexity when `InputIterator` satisfies the requirements for a random-access iterator; otherwise, it has linear complexity and so is potentially expensive. @@ -42,33 +41,34 @@ The advance function has constant complexity when `InputIterator` satisfies the #include #include -int main( ) +int main() { - using namespace std; - int i; - - list L; - for ( i = 1 ; i < 9 ; ++i ) - { - L.push_back ( i ); - } - list ::iterator L_Iter, LPOS = L.begin ( ); - - cout << "The list L is: ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; - - cout << "The iterator LPOS initially points to the first element: " + using namespace std; + + list L; + for (int i = 1; i < 9; ++i) + { + L.push_back(i); + } + list::iterator LPOS = L.begin(); + + cout << "The list L is: ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + cout << "The iterator LPOS initially points to the first element: " << *LPOS << "." << endl; - advance ( LPOS , 4 ); - cout << "LPOS is advanced 4 steps forward to point" + advance(LPOS, 4); + cout << "LPOS is advanced 4 steps forward to point" << " to the fifth element: " << *LPOS << "." << endl; - advance ( LPOS , -3 ); - cout << "LPOS is moved 3 steps back to point to the " + advance(LPOS, -3); + cout << "LPOS is moved 3 steps back to point to the " << "2nd element: " << *LPOS << "." << endl; } ``` @@ -80,27 +80,27 @@ LPOS is advanced 4 steps forward to point to the fifth element: 5. LPOS is moved 3 steps back to point to the 2nd element: 2. ``` -## back_inserter +## `back_inserter` Creates an iterator that can insert elements at the back of a specified container. ```cpp template -back_insert_iterator back_inserter(Container& _Cont); +back_insert_iterator back_inserter(Container& Cont); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container into which the back insertion is to be executed. ### Return Value -A `back_insert_iterator` associated with the container object *_Cont*. +A `back_insert_iterator` associated with the container object *`Cont`*. ### Remarks -Within the C++ Standard Library, the argument must refer to one of the three sequence containers that have the member function `push_back`: [deque Class](../standard-library/deque-class.md), [list Class](../standard-library/list-class.md), or [vector Class](../standard-library/vector-class.md). +Within the C++ Standard Library, the argument must refer to one of the three sequence containers that have the member function `push_back`: [`deque` Class](../standard-library/deque-class.md), [`list` Class](../standard-library/list-class.md), or [`vector` Class](../standard-library/vector-class.md). ### Example @@ -111,38 +111,40 @@ Within the C++ Standard Library, the argument must refer to one of the three seq #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 0 ; i < 3 ; ++i ) - { - vec.push_back ( i ); - } - - vector ::iterator vIter; - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Insertions can be done with template function - back_insert_iterator > backiter ( vec ); -*backiter = 30; - backiter++; -*backiter = 40; - - // Alternatively, insertions can be done with the - // back_insert_iterator member function - back_inserter ( vec ) = 500; - back_inserter ( vec ) = 600; - - cout << "After the insertions, the vector vec is: ( "; - for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ ) - cout << *vIter << " "; - cout << ")." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 3; ++i) + { + vec.push_back(i); + } + + cout << "The initial vector vec is: ( "; + for (auto vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Insertions can be done with template function + back_insert_iterator > backiter(vec); + *backiter = 30; + backiter++; + *backiter = 40; + + // Alternatively, insertions can be done with the + // back_insert_iterator member function + back_inserter(vec) = 500; + back_inserter(vec) = 600; + + cout << "After the insertions, the vector vec is: ( "; + for (auto vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; } ``` @@ -151,7 +153,7 @@ The initial vector vec is: ( 0 1 2 ). After the insertions, the vector vec is: ( 0 1 2 30 40 500 600 ). ``` -## begin +## `begin` Retrieves an iterator to the first element in a specified container. @@ -170,17 +172,17 @@ Ty *begin(Ty (& array)[Size]); ### Parameters -*cont*\ +*`cont`*\ A container. -*array*\ +*`array`*\ An array of objects of type `Ty`. ### Return Value The first two template functions return `cont.begin()`. The first function is non-constant; the second one is constant. -The third template function returns *array*. +The third template function returns *`array`*. ### Example @@ -194,22 +196,22 @@ We recommend that you use this template function in place of container member `b #include #include -template void reverse_sort(C& c) { - using std::begin; - using std::end; - - std::sort(begin(c), end(c), std::greater<>()); +template void reverse_sort(C& c) +{ + std::sort(std::begin(c), std::end(c), std::greater<>()); } -template void print(const C& c) { - for (const auto& e : c) { +template void print(const C& c) +{ + for (const auto& e : c) + { std::cout << e << " "; } - std::cout << "\n"; } -int main() { +int main() +{ std::vector v = { 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1 }; print(v); @@ -234,7 +236,7 @@ int main() { 160 106 80 70 53 40 35 23 20 16 10 8 5 4 2 1 ``` -The function `reverse_sort` supports containers of any kind, in addition to regular arrays, because it calls the non-member version of `begin()`. If `reverse_sort` were coded to use the container member `begin()`: +The function `reverse_sort` supports containers of any kind, in addition to regular arrays, because it calls the non-member version of `begin()`. Coding `reverse_sort` to use the container member `begin()`: ```cpp template @@ -247,15 +249,15 @@ void reverse_sort(C& c) { } ``` -Then sending an array to it would cause this compiler error: +Then sending an array to it, causes this compiler error: ```Output error C2228: left of '.begin' must have class/struct/union ``` -## cbegin +## `cbegin` -Retrieves a const iterator to the first element in a specified container. +Retrieves a const (read-only) iterator to the first element in a specified container. ```cpp template @@ -265,8 +267,8 @@ auto cbegin(const Container& cont) ### Parameters -*cont*\ -A container or initializer_list. +*`cont`*\ +A container or `initializer_list`. ### Return Value @@ -274,9 +276,9 @@ A constant `cont.begin()`. ### Remarks -This function works with all C++ Standard Library containers and with [initializer_list](../standard-library/initializer-list-class.md). +This function works with all C++ Standard Library containers and with [`initializer_list`](../standard-library/initializer-list-class.md). -You can use this member function in place of the `begin()` template function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` template function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -286,9 +288,9 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## cend +## `cend` -Retrieves a const iterator to the element that follows the last element in the specified container. +Retrieves a const (read-only) iterator to the element that follows the last element in the specified container. ```cpp template @@ -298,8 +300,8 @@ auto cend(const Container& cont) ### Parameters -*cont*\ -A container or initializer_list. +*`cont`*\ +A container or `initializer_list`. ### Return Value @@ -307,9 +309,9 @@ A constant `cont.end()`. ### Remarks -This function works with all C++ Standard Library containers and with [initializer_list](../standard-library/initializer-list-class.md). +This function works with all C++ Standard Library containers and with [`initializer_list`](../standard-library/initializer-list-class.md). -You can use this member function in place of the [end()](../standard-library/iterator-functions.md#end) template function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `end()` and `cend()`. +You can use this member function in place of the [`end()`](../standard-library/iterator-functions.md#end) template function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -319,28 +321,152 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -## crbegin +## `crbegin` + +Get a reverse read-only iterator to the elements of the container, starting at the end of the container. ```cpp template constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c)); ``` -## crend +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +This iterator returns the elements of the container in reverse order, starting at the end of the container. + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +### Example: `crbegin` + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + for (auto i = std::crbegin(v); i != std::crend(v); ++i) + { + std::cout << *i << ' '; // outputs 30 20 10 + } + // v[1] = 100; // error because the iterator is const +} +``` + +```output +30 20 10 +``` + +## `crend` + +Get the sentinel at the end of a read-only reversed sequence of elements. ```cpp template constexpr auto crend(const C& c) -> decltype(std::rend(c)); ``` -## data +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +The sentinel follows the last element in a reversed view of the container. + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +### `crend` example ```cpp -template constexpr auto data(C& c) -> decltype(c.data()); -template constexpr auto data(const C& c) -> decltype(c.data()); -template constexpr T* data(T (&array)[N]) noexcept; -template constexpr const E* data(initializer_list il) noexcept; +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::crend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 + // vi[0] = 300; // error because the iterator is const +} +``` + +```output +10 +``` + +## `data` + +Get a pointer to the first element in the container. + +```cpp +1) template constexpr auto data(C& c) -> decltype(c.data()); +2) template constexpr auto data(const C& c) -> decltype(c.data()); +3) template constexpr T* data(T (&array)[N]) noexcept; +4) template constexpr const E* data(initializer_list il) noexcept; +``` + +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`E`*\ +The element type of the initializer list. + +*`il`*\ +An initializer list. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +1, 2\) A pointer, based on the type of the container, to the first element. For example, if the container is a vector of integers, the type of the return value is an `int *`. + +3\) A pointer to the first element as an array. + +4\) A pointer to the first element of the initializer list. + +### Example `data` + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + std::string src{ "a string" }; + + const char *charPtr = std::data(src); + int* intPtr = std::data(v); + std::cout << charPtr << ", " << *intPtr << '\n'; // a string, 10 +} ``` -## distance +```output +a string, 10 +``` + +## `distance` Determines the number of increments between the positions addressed by two iterators. @@ -351,15 +477,15 @@ typename iterator_traits::difference_type distance(InputIterator ### Parameters -*first*\ +*`first`*\ The first iterator whose distance from the second is to be determined. -*last*\ +*`last`*\ The second iterator whose distance from the first is to be determined. ### Return Value -The number of times that *first* must be incremented until it equal *last*. +The number of times that *`first`* must be incremented until it equals *`last`*. ### Remarks @@ -374,34 +500,35 @@ The distance function has constant complexity when `InputIterator` satisfies the #include #include -int main( ) +int main() { - using namespace std; - int i; - - list L; - for ( i = -1 ; i < 9 ; ++i ) - { - L.push_back ( 2 * i ); - } - list ::iterator L_Iter, LPOS = L.begin ( ); - - cout << "The list L is: ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ ) - cout << *L_Iter << " "; - cout << ")." << endl; - - cout << "The iterator LPOS initially points to the first element: " - << *LPOS << "." << endl; + using namespace std; + + list L; + for (int i = -1; i < 9; ++i) + { + L.push_back(2 * i); + } + list ::iterator L_Iter, LPOS = L.begin(); + + cout << "The list L is: ( "; + for (L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + cout << "The iterator LPOS initially points to the first element: " + << *LPOS << "." << endl; - advance ( LPOS , 7 ); - cout << "LPOS is advanced 7 steps forward to point " + advance(LPOS, 7); + cout << "LPOS is advanced 7 steps forward to point " << " to the eighth element: " << *LPOS << "." << endl; - list::difference_type Ldiff ; - Ldiff = distance ( L.begin ( ) , LPOS ); - cout << "The distance from L.begin( ) to LPOS is: " + list::difference_type Ldiff; + Ldiff = distance(L.begin(), LPOS); + cout << "The distance from L.begin( ) to LPOS is: " << Ldiff << "." << endl; } ``` @@ -413,7 +540,7 @@ LPOS is advanced 7 steps forward to point to the eighth element: 12. The distance from L.begin( ) to LPOS is: 7. ``` -## empty +## `empty` ```cpp template constexpr auto empty(const C& c) -> decltype(c.empty()); @@ -421,7 +548,51 @@ template constexpr bool empty(const T (&array)[N]) noexcept; template constexpr bool empty(initializer_list il) noexcept; ``` -## end +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`E`*\ +The element type of the initializer list. + +*`il`*\ +An initializer list. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +Returns `true` if the container has no elements; otherwise `false`. + +### Example + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10,20,30 }; + std::vector v2; + + std::cout << std::boolalpha << std::empty(v); // outputs false + std::cout << std::boolalpha << ", " << std::empty(v2); // outputs true +} +``` + +```output +false, true +``` + +## `end` Retrieves an iterator to the element that follows the last element in the specified container. @@ -440,10 +611,10 @@ Ty *end(Ty (& array)[Size]); ### Parameters -*cont*\ +*`cont`*\ A container. -*array*\ +*`array`*\ An array of objects of type `Ty`. ### Return Value @@ -454,25 +625,25 @@ The third template function returns `array + Size`. ### Remarks -For a code example, see [begin](../standard-library/iterator-functions.md#begin). +For a code example, see [`begin`](../standard-library/iterator-functions.md#begin). -## front_inserter +## `front_inserter` Creates an iterator that can insert elements at the front of a specified container. ```cpp template -front_insert_iterator front_inserter(Container& _Cont); +front_insert_iterator front_inserter(Container& Cont); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container object whose front is having an element inserted. ### Return Value -A `front_insert_iterator` associated with the container object *_Cont*. +A `front_insert_iterator` associated with the container object *`Cont`*. ### Remarks @@ -489,34 +660,36 @@ Within the C++ Standard Library, the argument must refer to one of the two seque #include #include -int main( ) +int main() { - using namespace std; - int i; - list ::iterator L_Iter; - - list L; - for ( i = -1 ; i < 9 ; ++i ) - { - L.push_back ( i ); - } - - cout << "The list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; - - // Using the template function to insert an element - front_insert_iterator< list < int> > Iter(L); -*Iter = 100; - - // Alternatively, you may use the front_insert member function - front_inserter ( L ) = 200; - - cout << "After the front insertions, the list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; + using namespace std; + + list L; + for (int i = -1; i < 9; ++i) + { + L.push_back(i); + } + + cout << "The list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + // Using the template function to insert an element + front_insert_iterator> Iter(L); + *Iter = 100; + + // Alternatively, you may use the front_insert member function + front_inserter(L) = 200; + + cout << "After the front insertions, the list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; } ``` @@ -527,29 +700,29 @@ After the front insertions, the list L is: ( 200 100 -1 0 1 2 3 4 5 6 7 8 ). ``` -## inserter +## `inserter` -A helper template function that lets you use `inserter(_Cont, _Where)` instead of `insert_iterator(_Cont, _Where)`. +A helper template function that lets you use `inserter(Cont, Where)` instead of `insert_iterator(Cont, Where)`. ```cpp template insert_iterator inserter( - Container& _Cont, - typename Container::iterator _Where); + Container& Cont, + typename Container::iterator Where); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container to which new elements are to be added. -*_Where*\ +*`Where`*\ An iterator locating the point of insertion. ### Remarks -The template function returns [insert_iterator](../standard-library/insert-iterator-class.md#insert_iterator)`(_Cont, _Where)`. +The template function returns [`insert_iterator`](../standard-library/insert-iterator-class.md#insert_iterator)`(Cont, Where)`. ### Example @@ -560,34 +733,36 @@ The template function returns [insert_iterator](../standard-library/insert-itera #include #include -int main( ) +int main() { - using namespace std; - int i; - list ::iterator L_Iter; - - list L; - for (i = 2 ; i < 5 ; ++i ) - { - L.push_back ( 10 * i ); - } - - cout << "The list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ ) - cout << *L_Iter << " "; - cout << ")." << endl; - - // Using the template version to insert an element - insert_iterator > Iter( L, L.begin ( ) ); -*Iter = 1; - - // Alternatively, using the member function to insert an element - inserter ( L, L.end ( ) ) = 500; - - cout << "After the insertions, the list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; + using namespace std; + + list L; + for (int i = 2; i < 5; ++i) + { + L.push_back(10 * i); + } + + cout << "The list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + // Using the template version to insert an element + insert_iterator> Iter(L, L.begin()); + *Iter = 1; + + // Alternatively, using the member function to insert an element + inserter(L, L.end()) = 500; + + cout << "After the insertions, the list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; } ``` @@ -598,7 +773,7 @@ After the insertions, the list L is: ( 1 20 30 40 500 ). ``` -## make_checked_array_iterator +## `make_checked_array_iterator` Creates a [checked_array_iterator](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. @@ -616,13 +791,13 @@ Iter Ptr, ### Parameters -*Ptr*\ +*`Ptr`*\ A pointer to the destination array. -*Size*\ +*`Size`*\ The size of the destination array. -*Index*\ +*`Index`*\ Optional index into the array. ### Return Value @@ -652,10 +827,12 @@ In the following example, a [vector](../standard-library/vector-class.md) is cre using namespace std; -template void print(const string& s, const C& c) { +template void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } @@ -672,7 +849,8 @@ int main() vector v; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { v.push_back(i); } print("vector v: ", v); @@ -680,38 +858,40 @@ int main() copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size)); cout << "int array dest: "; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { cout << dest[i] << " "; } cout << endl; // Add another element to the vector to force an overrun. v.push_back(10); - // The next line causes a debug assertion when it executes. + + // ! The next line causes a debug assertion when it executes. copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size)); } ``` -## make_move_iterator +## `make_move_iterator` Creates a `move iterator` that contains the provided iterator as the `stored` iterator. ```cpp template move_iterator -make_move_iterator(const Iterator& _It); +make_move_iterator(const Iterator& It); ``` ### Parameters -*_It*\ +*`It`*\ The iterator stored in the new move iterator. ### Remarks The template function returns `move_iterator` `(_It)`. -## make_unchecked_array_iterator +## `make_unchecked_array_iterator` Creates an [unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. @@ -726,7 +906,7 @@ unchecked_array_iterator ### Parameters -*Ptr*\ +*`Ptr`*\ A pointer to the destination array. ### Return Value @@ -755,10 +935,12 @@ In the following example, a [vector](../standard-library/vector-class.md) is cre using namespace std; -template void print(const string& s, const C& c) { +template void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } @@ -768,10 +950,11 @@ template void print(const string& s, const C& c) { int main() { const size_t dest_size = 10; - int *dest = new int[dest_size]; + int* dest = new int[dest_size]; vector v; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { v.push_back(i); } print("vector v: ", v); @@ -781,7 +964,8 @@ int main() copy(v.begin(), v.end(), stdext::make_unchecked_array_iterator(dest)); cout << "int array dest: "; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { cout << dest[i] << " "; } cout << endl; @@ -790,7 +974,12 @@ int main() } ``` -## next +```output +vector v: 0 1 2 3 4 5 6 7 8 9 +int array dest: 0 1 2 3 4 5 6 7 8 9 +``` + +## `next` Iterates a specified number of times and returns the new iterator position. @@ -798,26 +987,26 @@ Iterates a specified number of times and returns the new iterator position. template InputIterator next( InputIterator first, - typename iterator_traits::difference_type _Off = 1); + typename iterator_traits::difference_type off = 1); ``` ### Parameters -*first*\ +*`first`*\ The current position. -*_Off*\ +*`off`*\ The number of times to iterate. ### Return Value -Returns the new iterator position after iterating *_Off* times. +Returns the new iterator position after iterating *`off`* times. ### Remarks -The template function returns `next` incremented *_Off* times +The template function returns `next` incremented *`off`* times -## prev +## `prev` Iterates in reverse a specified number of times and returns the new iterator position. @@ -825,38 +1014,147 @@ Iterates in reverse a specified number of times and returns the new iterator pos template BidirectionalIterator prev( BidirectionalIterator first, - typename iterator_traits::difference_type _Off = 1); + typename iterator_traits::difference_type off = 1); ``` ### Parameters -*first*\ +*`first`*\ The current position. -*_Off*\ +*`off`*\ The number of times to iterate. ### Remarks The template function returns `next` decremented `off` times. -## rbegin +## `rbegin` + +Get an iterator, which returns the elements of the container in reverse order. ```cpp template constexpr auto rbegin(C& c) -> decltype(c.rbegin()); template constexpr auto rbegin(const C& c) -> decltype(c.rbegin()); ``` -## rend +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +The returned iterator presents the elements of the container in reverse order, starting at the end of the reversed range. + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +### Example `rbegin` ```cpp -template constexpr auto rend(C& c) -> decltype(c.rend()); +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + + for (auto e = std::rbegin(v); e != std::rend(v); ++e) + { + std::cout << *e << ' '; // outputs 30 20 10 + } +} +``` + +```output +30 20 10 +``` + +## `rend` + +Get the sentinel at the end of a reversed sequence of elements. + +```cpp +template constexpr auto rend(C& c)-> decltype(c.rend()); template constexpr auto rend(const C& c) -> decltype(c.rend()); ``` -## size +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +A reverse iterator to the sentinel at the end of the container. The sentinel follows the last element in the reversed view of the container: + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +### `rend` example + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::rend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 +} +``` + +```output +10 +``` + +## `size` ```cpp -template constexpr auto size(const C& c) -> decltype(c.size()); +template constexpr auto size(const C& c) + -> decltype(c.size()); template constexpr size_t size(const T (&array)[N]) noexcept; ``` + +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +The number of elements in the container as an unsigned integer-like value. + +### Example `size` + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + size_t s = std::size(v); + std::cout << s; // outputs 3 +} +``` + +```output +3 +``` \ No newline at end of file diff --git a/docs/standard-library/iterator-operators.md b/docs/standard-library/iterator-operators.md index 800e404386..27086c18f8 100644 --- a/docs/standard-library/iterator-operators.md +++ b/docs/standard-library/iterator-operators.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 09/30/2022 f1_keywords: ["xutility/std::operator!=", "xutility/std::operator>", "xutility/std::operator>=", "xutility/std::operator<", "xutility/std::operator<=", "xutility/std::operator+", "xutility/std::operator-", "xutility/std::operator=="] -ms.assetid: b7c664f0-49d4-4993-b5d1-9ac4859fdddc helpviewer_keywords: ["std::operator!= (iterator)", "std::operator> (iterator)", "std::operator>= (iterator)", "std::operator< (iterator)", "std::operator<= (iterator), std::operator== (iterator)"] --- # `` operators -## operator!= +## `operator!=` -Tests if the iterator object on the left side of the operator is not equal to the iterator object on the right side. +Tests if the iterator object on the left side of the operator isn't equal to the iterator object on the right side. ```cpp template @@ -25,69 +24,76 @@ bool operator!=(const istreambuf_iterator& left, const istream ### Parameters -*left*\ +*`left`*\ An object of type `iterator`. -*right*\ +*`right`*\ An object of type `iterator`. ### Return Value -**`true`** if the iterator objects are not equal; **`false`** if the iterator objects are equal. +**`true`** if the iterator objects aren't equal; **`false`** if the iterator objects are equal. ### Remarks -One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal. +One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they aren't equal. ### Example ```cpp -// iterator_op_ne.cpp +/// iterator_op_ne.cpp // compile with: /EHsc #include #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 1 ; i < 9 ; ++i ) - { - vec.push_back ( i ); - } - - vector ::iterator vIter; - - cout << "The vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++ ) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the first " + using namespace std; + + vector vec; + for (int i = 1; i < 9; ++i) + { + vec.push_back(i); + } + + cout << "The vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the first " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 != rVPOS2 ) - cout << "The iterators are not equal." << endl; - else - cout << "The iterators are equal." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " + if (rVPOS1 != rVPOS2) + { + cout << "The iterators are not equal." << endl; + } + else + { + cout << "The iterators are equal." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 != rVPOS2 ) - cout << "The iterators are not equal." << endl; - else - cout << "The iterators are equal." << endl; + if (rVPOS1 != rVPOS2) + { + cout << "The iterators are not equal." << endl; + } + else + { + cout << "The iterators are equal." << endl; + } } ``` @@ -101,7 +107,7 @@ in the reversed sequence: 7. The iterators are not equal. ``` -## operator== +## `operator==` Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side. @@ -129,21 +135,21 @@ bool operator==( ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator objects are equal; **`false`** if the iterator objects are not equal. +**`true`** if the iterator objects are equal; **`false`** if the iterator objects aren't equal. ### Remarks -One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal. +One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they aren't equal. -The first two template operators return true only if both *left* and *right* store the same iterator. The third template operator returns true only if both *left* and *right* store the same stream pointer. The fourth template operator returns `left.equal (right)`. +The first two template operators return true only if both *`left`* and *`right`* store the same iterator. The third template operator returns true only if both *`left`* and *`right`* store the same stream pointer. The fourth template operator returns `left.equal (right)`. ### Example @@ -154,46 +160,53 @@ The first two template operators return true only if both *left* and *right* sto #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 1 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the first " + using namespace std; + + vector vec; + for (int i = 1; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the first " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 == rVPOS2 ) - cout << "The iterators are equal." << endl; - else - cout << "The iterators are not equal." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " + if (rVPOS1 == rVPOS2) + { + cout << "The iterators are equal." << endl; + } + else + { + cout << "The iterators are not equal." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 == rVPOS2 ) - cout << "The iterators are equal." << endl; - else - cout << "The iterators are not equal." << endl; + if (rVPOS1 == rVPOS2) + { + cout << "The iterators are equal." << endl; + } + else + { + cout << "The iterators are not equal." << endl; + } } ``` @@ -218,19 +231,19 @@ bool operator<(const reverse_iterator& left, const reverse_itera ### Parameters -*left*\ +*`left`*\ An object of type `iterator`. -*right*\ +*`right`*\ An object of type `iterator`. ### Return Value -**`true`** if the iterator on the left side of the expression is less than the iterator on the right side of the expression; **`false`** if it is greater than or equal to the iterator on the right. +**`true`** if the iterator on the left side of the expression is less than the iterator on the right side of the expression; **`false`** if it's greater than or equal to the iterator on the right. ### Remarks -One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object is not less than another if it addresses either the same element as the other iterator object or an element that occurs later in the container than the element addressed by the other iterator object. +One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object isn't less than another if it addresses either the same element as the other iterator object or an element that occurs later in the container than the element addressed by the other iterator object. ### Example @@ -241,50 +254,57 @@ One iterator object is less than another if it addresses an element that occurs #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 0 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterators rVPOS1& rVPOS2 initially point to the " - << "first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 < rVPOS2 ) - cout << "The iterator rVPOS1 is less than" - << " the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is not less than" - << " the iterator rVPOS2." << endl; - - rVPOS2++; - cout << "The iterator rVPOS2 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 < rVPOS2 ) - cout << "The iterator rVPOS1 is less than" - << " the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is not less than" - << " the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterators rVPOS1& rVPOS2 initially point to the " + << "first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 < rVPOS2) + { + cout << "The iterator rVPOS1 is less than" + << " the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is not less than" + << " the iterator rVPOS2." << endl; + + rVPOS2++; + cout << "The iterator rVPOS2 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 < rVPOS2) + { + cout << "The iterator rVPOS1 is less than" + << " the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is not less than" + << " the iterator rVPOS2." << endl; + } + } } ``` @@ -309,15 +329,15 @@ bool operator<=(const reverse_iterator& left, const reverse_iter ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is less than or equal to the iterator on the right side of the expression; **`false`** if it is greater than the iterator on the right. +**`true`** if the iterator on the left side of the expression is less than or equal to the iterator on the right side of the expression; **`false`** if it's greater than the iterator on the right. ### Remarks @@ -332,52 +352,60 @@ One iterator object is less than or equal to another if it addresses the same el #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ) + 1, - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the " - << "second element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - cout << "The iterator rVPOS2 initially points to the " - << "first element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 <= rVPOS2 ) - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - - rVPOS2++; - cout << "The iterator rVPOS2 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 <= rVPOS2 ) - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin() + 1, + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the " + << "second element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + cout << "The iterator rVPOS2 initially points to the " + << "first element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 <= rVPOS2) + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + + rVPOS2++; + cout << "The iterator rVPOS2 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 <= rVPOS2) + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } } ``` @@ -404,19 +432,19 @@ bool operator>(const reverse_iterator& left, const reverse_itera ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is greater than the iterator on the right side of the expression; **`false`** if it is less than or equal to the iterator on the right. +**`true`** if the iterator on the left side of the expression is greater than the iterator on the right side of the expression; **`false`** if it's less than or equal to the iterator on the right. ### Remarks -One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object. One iterator object is not greater than another if it addresses either the same element as the other iterator object or an element that occurs earlier in the container than the element addressed by the other iterator object. +One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object. One iterator object isn't greater than another if it addresses either the same element as the other iterator object or an element that occurs earlier in the container than the element addressed by the other iterator object. ### Example @@ -427,48 +455,55 @@ One iterator object is greater than another if it addresses an element that occu #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterators rVPOS1 & rVPOS2 initially point to " - << "the first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 > rVPOS2 ) - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 > rVPOS2 ) - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterators rVPOS1 & rVPOS2 initially point to " + << "the first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 > rVPOS2) + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 > rVPOS2) + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } } ``` @@ -493,15 +528,15 @@ bool operator>=(const reverse_iterator& left, const reverse_iter ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is greater than or equal to the iterator on the right side of the expression; **`false`** if it is less than the iterator on the right. +**`true`** if the iterator on the left side of the expression is greater than or equal to the iterator on the right side of the expression; **`false`** if it's less than the iterator on the right. ### Remarks @@ -516,52 +551,59 @@ One iterator object is greater than or equal to another if it addresses the same #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ) + 1; - - cout << "The iterator rVPOS1 initially points to the " - << "first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - cout << "The iterator rVPOS2 initially points to the " - << "second element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 >= rVPOS2 ) - cout << "The iterator rVPOS1 is greater than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than " - << "the iterator rVPOS2." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 >= rVPOS2 ) - cout << "The iterator rVPOS1 is greater than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than " - << "the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin() + 1; + + cout << "The iterator rVPOS1 initially points to the " + << "first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + cout << "The iterator rVPOS2 initially points to the " + << "second element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 >= rVPOS2) + { + cout << "The iterator rVPOS1 is greater than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than " + << "the iterator rVPOS2." << endl; + } + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 >= rVPOS2) + { + cout << "The iterator rVPOS1 is greater than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than " + << "the iterator rVPOS2." << endl; + } } ``` @@ -577,7 +619,7 @@ in the reversed sequence: 8. The iterator rVPOS1 is greater than or equal to the iterator rVPOS2. ``` -## operator+ +## `operator+` Adds an offset to an iterator and returns a `move_iterator` or a `reverse_iterator` addressing the inserted element at the new offset position. @@ -597,15 +639,15 @@ operator+( ### Parameters -*_Off*\ +*`Off`*\ The number of positions the const move_iterator or const reverse_iterator is to be offset. -*right*\ +*`right`*\ The iterator to be offset. ### Return Value -Returns the sum *right* + *_Off*. +Returns the sum *`right`* + *`Off`*. ### Example @@ -616,35 +658,35 @@ Returns the sum *right* + *_Off*. #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to " - << "the first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to " + << "the first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; - vector::difference_type diff = 4; - rVPOS1 = diff +rVPOS1; + vector::difference_type diff = 4; + rVPOS1 = diff + rVPOS1; - cout << "The iterator rVPOS1 now points to the fifth " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; + cout << "The iterator rVPOS1 now points to the fifth " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; } ``` @@ -656,7 +698,7 @@ The iterator rVPOS1 now points to the fifth element in the reversed sequence: 2. ``` -## operator- +## `operator-` Subtracts one iterator from another and returns the difference. @@ -674,15 +716,15 @@ Tdiff operator-( ### Parameters -*left*\ +*`left`*\ An iterator. -*right*\ +*`right`*\ An iterator. ### Return Value -The difference between two iterators `.` +The difference between two iterators. ### Remarks @@ -690,7 +732,7 @@ The first template operator returns `left.base() - right.base()`. The second template operator returns `right.current - left.current`. -`Tdiff` is determined by the type of the returned expression. Otherwise, it is `RandomIterator1::difference_type`. +`Tdiff` is determined by the type of the returned expression. Otherwise, it's `RandomIterator1::difference_type`. ### Example @@ -701,41 +743,41 @@ The second template operator returns `right.current - left.current`. #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } + using namespace std; - vector ::iterator vIter; + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); - cout << "The iterators rVPOS1 & rVPOS2 initially point to " + cout << "The iterators rVPOS1 & rVPOS2 initially point to " << "the first element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - for (i = 1; i < 5; ++i) - { - rVPOS2++; - } - cout << "The iterator rVPOS2 now points to the fifth " + for (int i = 1; i < 5; ++i) + { + rVPOS2++; + } + + cout << "The iterator rVPOS2 now points to the fifth " << "element\n in the reversed sequence: " << *rVPOS2 << "." << endl; - vector::difference_type diff = rVPOS2 - rVPOS1; - cout << "The difference: rVPOS2 - rVPOS1= " + vector::difference_type diff = rVPOS2 - rVPOS1; + cout << "The difference: rVPOS2 - rVPOS1= " << diff << "." << endl; } ``` diff --git a/docs/standard-library/iterator-traits-struct.md b/docs/standard-library/iterator-traits-struct.md index 7e027f479c..4ad621f774 100644 --- a/docs/standard-library/iterator-traits-struct.md +++ b/docs/standard-library/iterator-traits-struct.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: iterator_traits Struct" title: "iterator_traits Struct" +description: "Learn more about: iterator_traits Struct" ms.date: "11/04/2016" f1_keywords: ["xutility/std::iterator_traits"] helpviewer_keywords: ["iterator_traits struct", "iterator_traits class"] -ms.assetid: 8b92c2c5-f658-402f-8ca1-e7ae301b8514 --- # iterator_traits Struct @@ -33,7 +32,7 @@ The template struct defines the member types - `difference_type`: a synonym for `Iterator::difference_type`. -- `distance_type`: a synonym for `Iterator::difference_type.` +- `distance_type`: a synonym for `Iterator::difference_type`. - `pointer`: a synonym for `Iterator::pointer`. diff --git a/docs/standard-library/iterator.md b/docs/standard-library/iterator.md index 6c368dae39..4c87768cbf 100644 --- a/docs/standard-library/iterator.md +++ b/docs/standard-library/iterator.md @@ -1,38 +1,27 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 12/14/2022 f1_keywords: [""] helpviewer_keywords: ["iterator header"] -ms.assetid: c61a3962-f3ed-411a-b5a3-e8b3c2b500bd --- # `` -Defines the iterator primitives, predefined iterators and stream iterators, as well as several supporting templates. The predefined iterators include insert and reverse adaptors. There are three classes of insert iterator adaptors: front, back, and general. They provide insert semantics rather than the overwrite semantics that the container member function iterators provide. +Defines predefined iterators and stream iterators, iterator primitives, and supporting templates. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Remarks -Iterators are a generalization of pointers, abstracting from their requirements in a way that allows a C++ program to work with different data structures in a uniform manner. Iterators act as intermediaries between containers and generic algorithms. Instead of operating on specific data types, algorithms are defined to operate on a range specified by a type of iterator. Any data structure that satisfies the requirements of the iterator may then be operated on by the algorithm. There are five types or categories of iterator, each with its own set of requirements and resulting functionality: - -- Output: forward moving, may store but not retrieve values, provided by ostream and inserter. - -- Input: forward moving, may retrieve but not store values, provided by istream. - -- Forward: forward moving, may store and retrieve values. - -- Bidirectional: forward and backward moving, may store and retrieve values, provided by list, set, multiset, map, and multimap. - -- Random access: elements accessed in any order, may store and retrieve values, provided by vector, deque, string, and array. +Iterators are a generalization of pointers that allow a C++ program to work with different data structures in a uniform way. Instead of operating on specific data types, algorithms operate on a range of values as specified by a kind of iterator. Algorithms can operate on any data structure that satisfies the requirements of the iterator. -Iterators that have greater requirements and so more powerful access to elements may be used in place of iterators with fewer requirements. For example, if a forward iterator is called for, then a random-access iterator may used instead. +In C++20, there are six categories of iterators. Iterators are arranged in a hierarchy of capability. Their capabilities are specified by C++20 concepts. For a description of the various iterators and their capabilities, see [Iterator concepts](iterator-concepts.md) -Visual Studio has added extensions to C++ Standard Library iterators to support a variety of debug mode situations for checked and unchecked iterators. For more information, see [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md). +Visual Studio has added extensions to C++ Standard Library iterators to support debugging for checked and unchecked iterators. For more information, see [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md). ## Members @@ -40,63 +29,79 @@ Visual Studio has added extensions to C++ Standard Library iterators to support |Name|Description| |-|-| -|[advance](../standard-library/iterator-functions.md#advance)|Increments an iterator by a specified number of positions.| -|[back_inserter](../standard-library/iterator-functions.md#back_inserter)|Creates an iterator that can insert elements at the back of a specified container.| -|[begin](../standard-library/iterator-functions.md#begin)|Retrieves an iterator to the first element in a specified container.| -|[cbegin](../standard-library/iterator-functions.md#cbegin)|Retrieves a constant iterator to the first element in a specified container.| -|[cend](../standard-library/iterator-functions.md#cend)|Retrieves a constant iterator to the element that follows the last element in the specified container.| -|[crbegin](../standard-library/iterator-functions.md#crbegin)|| -|[crend](../standard-library/iterator-functions.md#crend)|| -|[data](../standard-library/iterator-functions.md#data)|| -|[distance](../standard-library/iterator-functions.md#distance)|Determines the number of increments between the positions addressed by two iterators.| -|[end](../standard-library/iterator-functions.md#end)|Retrieves an iterator to the element that follows the last element in the specified container.| -|[empty](../standard-library/iterator-functions.md#empty)|| -|[front_inserter](../standard-library/iterator-functions.md#front_inserter)|Creates an iterator that can insert elements at the front of a specified container.| -|[inserter](../standard-library/iterator-functions.md#inserter)|An iterator adaptor that adds a new element to a container at a specified point of insertion.| -|[make_checked_array_iterator](../standard-library/iterator-functions.md#make_checked_array_iterator)|Creates a [checked_array_iterator](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[make_move_iterator](../standard-library/iterator-functions.md#make_move_iterator)|Returns a move iterator containing the provided iterator as its stored base iterator.| -|[make_unchecked_array_iterator](../standard-library/iterator-functions.md#make_unchecked_array_iterator)|Creates an [unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[next](../standard-library/iterator-functions.md#next)|Iterates a specified number of times and returns the new iterator position.| -|[prev](../standard-library/iterator-functions.md#prev)|Iterates in reverse a specified number of times and returns the new iterator position.| -|[rbegin](../standard-library/iterator-functions.md#rbegin)|| -|[rend](../standard-library/iterator-functions.md#rend)|| -|[size](../standard-library/iterator-functions.md#size)|| +|[`advance`](../standard-library/iterator-functions.md#advance)|Increments an iterator by a specified number of positions.| +|[`back_inserter`](../standard-library/iterator-functions.md#back_inserter)|Creates an iterator that can insert elements at the back of a specified container.| +|[`begin`](../standard-library/iterator-functions.md#begin)|Retrieves an iterator to the first element in a specified container.| +|[`cbegin`](../standard-library/iterator-functions.md#cbegin)|Retrieves a read-only iterator to the first element in a specified container.| +|[`cend`](../standard-library/iterator-functions.md#cend)|Retrieves a read-only iterator to the element that follows the last element in the specified container.| +|[`crbegin`](../standard-library/iterator-functions.md#crbegin)| Get a reverse read-only iterator to the beginning of the specified container.| +|[`crend`](../standard-library/iterator-functions.md#crend)| Get the sentinel at the end of what `crbegin()` returns.| +|[`data`](../standard-library/iterator-functions.md#data)| Get a pointer to the first element in the specified container.| +|[`distance`](../standard-library/iterator-functions.md#distance)|Determines the number of increments between the positions addressed by two iterators.| +|[`end`](../standard-library/iterator-functions.md#end)|Retrieves an iterator to the element that follows the last element in the specified container.| +|[`empty`](../standard-library/iterator-functions.md#empty)| Test if the specified container is empty.| +|[`front_inserter`](../standard-library/iterator-functions.md#front_inserter)|Creates an iterator that can insert elements at the front of a specified container.| +|[`inserter`](../standard-library/iterator-functions.md#inserter)|An iterator adaptor that adds a new element to a container at a specified point of insertion.| +|[`make_checked_array_iterator`](../standard-library/iterator-functions.md#make_checked_array_iterator)|Creates a [`checked_array_iterator`](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`make_move_iterator`](../standard-library/iterator-functions.md#make_move_iterator)|Returns a move iterator containing the provided iterator as its stored base iterator.| +|[`make_unchecked_array_iterator`](../standard-library/iterator-functions.md#make_unchecked_array_iterator)|Creates an [`unchecked_array_iterator`](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`next`](../standard-library/iterator-functions.md#next)|Iterates a specified number of times and returns the new iterator position.| +|[`prev`](../standard-library/iterator-functions.md#prev)|Iterates in reverse a specified number of times and returns the new iterator position.| +|[`rbegin`](../standard-library/iterator-functions.md#rbegin)|Get a reverse iterator to the beginning of the specified container. | +|[`rend`](../standard-library/iterator-functions.md#rend)| Get a reverse iterator to the sentinel at the end of the specified container.| +|[`size`](../standard-library/iterator-functions.md#size)| Get the number of elements.| ### Operators |Name|Description| |-|-| -|[operator!=](../standard-library/iterator-operators.md#op_neq)|Tests if the iterator object on the left side of the operator is not equal to the iterator object on the right side.| -|[operator==](../standard-library/iterator-operators.md#op_eq_eq)|Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.| -|[operator<](../standard-library/iterator-operators.md#op_lt)|Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.| -|[operator\<=](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.| -|[operator>](../standard-library/iterator-operators.md#op_gt)|Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.| -|[operator>=](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.| -|[operator+](../standard-library/iterator-operators.md#op_add)|Adds an offset to an iterator and returns the new `reverse_iterator` addressing the inserted element at the new offset position.| -|[operator-](../standard-library/iterator-operators.md#operator-)|Subtracts one iterator from another and returns the difference.| +|[`operator!=`](../standard-library/iterator-operators.md#op_neq)|Tests if the iterator object on the left side of the operator isn't equal to the iterator object on the right side.| +|[`operator==`](../standard-library/iterator-operators.md#op_eq_eq)|Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.| +|[`operator<`](../standard-library/iterator-operators.md#op_lt)|Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.| +|[`operator<=`](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.| +|[`operator>`](../standard-library/iterator-operators.md#op_gt)|Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.| +|[`operator>=`](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.| +|[`operator+`](../standard-library/iterator-operators.md#op_add)|Adds an offset to an iterator and returns the new `reverse_iterator` addressing the inserted element at the new offset position.| +|[`operator-`](../standard-library/iterator-operators.md#operator-)|Subtracts one iterator from another and returns the difference.| ### Classes |Name|Description| |-|-| -|[back_insert_iterator](../standard-library/back-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| -|[bidirectional_iterator_tag](../standard-library/bidirectional-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a bidirectional iterator.| -|[checked_array_iterator](../standard-library/checked-array-iterator-class.md)|A class that accesses an array using a random access, checked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[forward_iterator_tag](../standard-library/forward-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a forward iterator.| -|[front_insert_iterator](../standard-library/front-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| -|[input_iterator_tag](../standard-library/input-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents an input iterator.| -|[insert_iterator](../standard-library/insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container. It also stores the protected `iterator` object, of class `Container::iterator`, called `iter`.| -|[istream_iterator](../standard-library/istream-iterator-class.md)|The class template describes an input iterator object. It extracts objects of class `Ty` from an input stream, which it accesses through an object it stores, of type pointer to `basic_istream`\<**Elem**, **Tr**>.| -|[istreambuf_iterator](../standard-library/istreambuf-iterator-class.md)|The class template describes an input iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type `pointer` to `basic_streambuf`\<**Elem**, **Tr**>.| -|[iterator](../standard-library/iterator-struct.md)|The class template is used as a base type for all iterators.| -|[iterator_traits](../standard-library/iterator-traits-struct.md)|A template helper class providing critical types that are associated with different iterator types so that they can be referred to in the same way.| -|[move_iterator](../standard-library/move-iterator-class.md)|A `move_iterator` object stores a random-access iterator of type `RandomIterator`. It behaves like a random-access iterator, except when dereferenced. The result of `operator*` is implicitly cast to `value_type&&:` to make an `rvalue reference`.| -|[ostream_iterator](../standard-library/ostream-iterator-class.md)|The class template describes an output iterator object. It inserts objects of class `Type` into an output stream, which it accesses through an object it stores, of type `pointer` to `basic_ostream`\<**Elem**, **Tr**>.| -|[ostreambuf_iterator Class](../standard-library/ostreambuf-iterator-class.md)|The class template describes an output iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type pointer to `basic_streambuf`\<**Elem**, **Tr**>.| -|[output_iterator_tag](../standard-library/output-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents an output iterator.| -|[random_access_iterator_tag](../standard-library/random-access-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents a random-access iterator.| -|[reverse_iterator](../standard-library/reverse-iterator-class.md)|The class template describes an object that behaves like a random-access iterator, only in reverse.| -|[unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md)|A class that accesses an array using a random access, unchecked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| +|[`back_insert_iterator`](../standard-library/back-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| +|[`bidirectional_iterator_tag`](../standard-library/bidirectional-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a bidirectional iterator.| +|[`checked_array_iterator`](../standard-library/checked-array-iterator-class.md)|A class that accesses an array using a random access, checked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`forward_iterator_tag`](../standard-library/forward-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a forward iterator.| +|[`front_insert_iterator`](../standard-library/front-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| +|[`input_iterator_tag`](../standard-library/input-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents an input iterator.| +|[`insert_iterator`](../standard-library/insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container. It also stores the protected `iterator` object, of class `Container::iterator`, called `iter`.| +|[`istream_iterator`](../standard-library/istream-iterator-class.md)|The class template describes an input iterator object. It extracts objects of class `Ty` from an input stream, which it accesses through an object it stores, of type pointer to `basic_istream`.| +|[`istreambuf_iterator`](../standard-library/istreambuf-iterator-class.md)|The class template describes an input iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type `pointer` to `basic_streambuf`.| +|[`iterator`](../standard-library/iterator-struct.md)|The class template is used as a base type for all iterators.| +|[`iterator_traits`](../standard-library/iterator-traits-struct.md)|A template helper class providing critical types that are associated with different iterator types so that they can be referred to in the same way.| +|[`move_iterator`](../standard-library/move-iterator-class.md)|A `move_iterator` object stores a random-access iterator of type `RandomIterator`. It behaves like a random-access iterator, except when dereferenced. The result of `operator*` is implicitly cast to `value_type&&:` to make an `rvalue reference`.| +|[`ostream_iterator`](../standard-library/ostream-iterator-class.md)|The class template describes an output iterator object. It inserts objects of class `Type` into an output stream, which it accesses through an object it stores, of type `pointer` to `basic_ostream`.| +|[`ostreambuf_iterator`](../standard-library/ostreambuf-iterator-class.md)|The class template describes an output iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type pointer to `basic_streambuf`.| +|[`output_iterator_tag`](../standard-library/output-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents an output iterator.| +|[`random_access_iterator_tag`](../standard-library/random-access-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents a random-access iterator.| +|[`reverse_iterator`](../standard-library/reverse-iterator-class.md)|The class template describes an object that behaves like a random-access iterator, only in reverse.| +|[`unchecked_array_iterator`](../standard-library/unchecked-array-iterator-class.md)|A class that accesses an array using a random access, unchecked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| + +## Concepts + +The following concepts are defined in the `std` namespace. They apply to iterators, and are also related to the iterator categories for ranges described in [`` concepts](range-concepts.md). + +| Iterator concept | Description | +|--|--| +| [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator)C++20 | Specifies an iterator that can read and write both forwards and backwards. | +| [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator)C++20 | Specifies an iterator whose elements are sequential in memory, the same size, and can be accessed using pointer arithmetic. | +| [`forward_iterator`](iterator-concepts.md#forward_iterator)C++20 | Specifies an iterator that can read (and possibly write) multiple times. | +| [`input_iterator`](iterator-concepts.md#input_iterator)C++20 | Specifies an iterator that you can read from at least once. | +| [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator)C++20 | The basis of the iterator concept taxonomy. | +| [`output_iterator`](iterator-concepts.md#output_iterator) | Specifies an iterator that you can write to. | +| [`random_access_iterator`](iterator-concepts.md#random_access_iterator)C++20 | Specifies an iterator that you can read and write by index. | +| [`sentinel_for`](iterator-concepts.md#sentinel_for)C++20 | Specifies a sentinel for an iterator type. | +| [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for)C++20 | Specifies that an iterator and its sentinel can be subtracted (using `-`) to find their difference in constant time. | ## See also diff --git a/docs/standard-library/join-view-class.md b/docs/standard-library/join-view-class.md new file mode 100644 index 0000000000..aef74d56cf --- /dev/null +++ b/docs/standard-library/join-view-class.md @@ -0,0 +1,182 @@ +--- +title: join_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) join_view class, which combines the elements of multiple ranges into a single view." +ms.date: 09/28/2022 +f1_keywords: ["ranges/std::join_view", "ranges/std::join_view::base", "ranges/std::join_view::begin", "ranges/std::join_view::end", "ranges/std::join_view::empty", "ranges/std::join_view::operator bool", "ranges/std::join_view::back", "ranges/std::join_view::front"] +helpviewer_keywords: ["std::ranges::join_view [C++]", "std::ranges::join_view [C++], base", "std::ranges::join_view [C++], begin", "std::ranges::join_view [C++], end", "std::ranges::join_view [C++], empty", "std::ranges::join_view [C++], operator bool", "std::ranges::join_view [C++], front", "std::ranges::join_view [C++], back"] +dev_langs: ["C++"] +--- +# `join_view` class (C++ Standard Library) + +Combines the elements of a range of ranges into a single view. + +## Syntax + +```cpp +template requires view && input_range> && + (is_reference_v> || view>) +class join_view : public view_interface>; +``` + +### Template parameters + +*`R`*\ +The type of the underlying range. Must satisfy [`input_range`](range-concepts.md#input_range) or higher. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::join`](range-adaptors.md#join) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `input_range` up to [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range being iterated | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct an `join_view`. | +| [`base`](#base)C++20 | Get a reference to the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create a `join_view` is by using the [`views::join`](range-adaptors.md#join) range adaptor. Range adaptors are the intended way to access view classes. The view types are exposed in case you want to create your own custom view type. + +This view is useful when you want to combine multiple ranges into a single view. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `join_view`. + +```cpp +1) join_view() = default; +2) constexpr explicit join_view(R base) +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Default-constructs a `join_view`.\ +2\) Constructs the `join_view` from *`base`*. + +### Example: `join_view` + +```cpp +// requires /std:c++20, or later +#include +#include +#include + +int main() +{ + std::vector rg1{1, 2, 3, 4}; + std::vector rg2{5, 6, 7}; + std::vector rg3{8, 9, 10, 11, 12, 13}; + std::vector rangeOfRanges[] {rg1, rg2, rg3}; + + auto jv = std::ranges::join_view(rangeOfRanges); + + for (auto& e : jv) + { + std::cout << e << " "; + } +} +``` + +```output +1 2 3 4 5 6 7 8 9 10 11 12 13 +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +1) The returned view is copy constructed. +2) The returned view is move constructed. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const + requires ranges::input_range && std::is_reference_v>; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr sentinel_t end(); +constexpr auto end() const requires range +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## See also + +[`join` range adaptor](range-adaptors.md#join)\ +[``](ranges.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/keys-view-class.md b/docs/standard-library/keys-view-class.md new file mode 100644 index 0000000000..4b9d1e47be --- /dev/null +++ b/docs/standard-library/keys-view-class.md @@ -0,0 +1,247 @@ +--- +title: keys_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) keys_view class, which provides a view over the first index into each tuple-like value in a collection. It's useful for extracting keys from associative containers." +ms.date: 09/28/2022 +f1_keywords: ["ranges/std::keys_view", "ranges/std::keys_view::base", "ranges/std::keys_view::begin", "ranges/std::keys_view::empty", "ranges/std::keys_view::end", "ranges/std::keys_view::size", "ranges/std::keys_view::operator bool", "ranges/std::keys_view::back", "ranges/std::keys_view::front", "ranges/std::keys_view::operator[]"] +helpviewer_keywords: ["std::ranges::keys_view [C++]", "std::ranges::keys_view::base [C++]", "std::ranges::keys_view::begin [C++]", "std::ranges::keys_view::empty [C++]", "std::ranges::keys_view::end [C++]", "std::ranges::keys_view::size [C++]", "std::ranges::keys_view::back [C++]", "std::ranges::keys_view::front [C++]", "std::ranges::keys_view::operator[] [C++]", "std::ranges::keys_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `keys_view` class (C++ Standard Library) + +A view over the first index into each tuple-like value in a collection. For example, given a range of `std::tuple`, create a view consisting of all the `string` elements from each tuple. + +`keys_view` is an alias for [`elements_view`](elements-view-class.md) and is useful for making of view of the keys from associative containers like [`std::map`](map.md) or [`std::unordered_map`](unordered-map-class.md). + +## Syntax + +```cpp +template +using keys_view = ranges::elements_view; +``` + +### Template parameters + +`R`\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::keys`](range-adaptors.md#keys) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the type of the first tuple element of the underlying range | +| **View iterator category** | [`random_access_range`](range-concepts.md#random_access_range) if the underlying range is contiguous, otherwise the same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +The following list of member functions refers to the `keys_view` class. Recall that this is an alias for an [`element_view`](elements-view-class.md) class template instantiation. + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `keys_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `keys_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `keys_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +The tuple-like types that you can use with `keys_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `keys_view`. + +```cpp +1) constexpr keys_view(V base); +2) keys_view() requires std::default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `keys_view` instance. + +### Remarks + +The best way to create an `keys_view` is by using the [`keys`](range-adaptors.md#keys) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a `keys_view` from the specified view.\ +2\) The default constructor creates an empty `keys_view`. + +### Example: `keys_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the keys from the map + for (const std::string& standards : std::views::keys(cpp_standards)) + { + std::cout << standards << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== work with a range of std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor using '|': create an keys_view from each pair + for (const std::string& version : windows | std::views::keys) + { + std::cout << version << ' '; // Windows 1.0 Windows 2.0 Windows 3.0 ... + } +} +``` + +```output +C++03 C++11 C++14 C++17 C++98 c++20 +Windows 1.0 Windows 2.0 Windows 3.0 Windows 3.1 Windows NT 3.1 Windows 95 Windows NT 4.0 Windows 95 Windows 98 Windows 1.0 Windows 2000 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `keys_view`. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires (Simple_view) // or put another way, requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `keys_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `keys_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `keys_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `keys_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`elements_view`](elements-view-class.md)\ +[`values_view`](values-view-class.md)\ +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/last-spec-struct.md b/docs/standard-library/last-spec-struct.md index e469b938aa..64ef8fbb27 100644 --- a/docs/standard-library/last-spec-struct.md +++ b/docs/standard-library/last-spec-struct.md @@ -3,6 +3,8 @@ description: "Learn more about: last_spec struct" title: "last_spec struct" ms.date: 09/15/2021 f1_keywords: ["chrono/std::chrono::last_spec"] +helpviewer_keywords: ["std::chrono [C++], last_spec"] +dev_langs: ["C++"] --- # `last_spec` struct diff --git a/docs/standard-library/lazy-split-view-class.md b/docs/standard-library/lazy-split-view-class.md new file mode 100644 index 0000000000..1736de4824 --- /dev/null +++ b/docs/standard-library/lazy-split-view-class.md @@ -0,0 +1,241 @@ +--- +title: lazy_split_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) lazy_split_view class. Splits a view into subranges based on a delimiter." +ms.date: 10/18/2022 +f1_keywords: ["ranges/std::lazy_split_view", "ranges/std::lazy_split_view::base", "ranges/std::lazy_split_view::begin", "ranges/std::lazy_split_view::data", "ranges/std::lazy_split_view::empty", "ranges/std::lazy_split_view::end", "ranges/std::lazy_split_view::size", "ranges/std::lazy_split_view::operator bool", "ranges/std::lazy_split_view::back", "ranges/std::lazy_split_view::front", "ranges/std::lazy_split_view::operator[]"] +helpviewer_keywords: ["std::ranges::lazy_split_view [C++]", "std::ranges::lazy_split_view::base [C++]", "std::ranges::lazy_split_view::begin [C++]", "std::ranges::lazy_split_view::data [C++]", "std::ranges::lazy_split_view::empty [C++]", "std::ranges::lazy_split_view::size [C++]", "std::ranges::lazy_split_view::end [C++]", +"std::ranges::lazy_split_view::back [C++]", "std::ranges::lazy_split_view::front [C++]", "std::ranges::lazy_split_view::operator[] [C++]", "std::ranges::lazy_split_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `lazy_split_view` class (C++ Standard Library) + +Splits a range into subranges based on a delimiter. The delimiter can be a single element or a view of elements. The delimiter isn't part of the resulting subranges. + +The primary differences between a [`split_view`](split-view-class.md) and a `lazy_split_view` are: + +| **View** | **Can split a `const` range** | **range type** | +|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher. | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher. | + +What makes a `lazy_split_view` "lazy" is that it doesn't lookahead for the next delimiter. That means it can support [`input_range`](range-concepts.md#input_range) whereas `split_view` requires at least `forward_range`. This is because `input_range` is single-pass whereas `forward_range` allows multi-pass iteration. + +Prefer `split_view` because it's more efficient--unless you must split a range that is `const`. Regarding performance, `split_view` is more efficient. + +A `lazy_split_view` has less efficient iterator increment and comparison than `split_view`, but is still O(1). A `split_view` has better performance when the distance between delimiters is small enough for subranges to fit in the CPU cache, in which case the delimiter lookahead effectively pre-caches the next subrange. + +## Syntax + +```cpp +template + requires view && view && + indirectly_comparable, iterator_t, ranges::equal_to> && + (forward_range || tiny_range) +class lazy_split_view : public view_interface> +``` + +### Template parameters + +*`Pattern`*\ +The type of the view that specifies a delimiter sequence.\ +The `(forward_range || tiny-range )` requirement means that when the underlying range isn't [`forward_range`](range-concepts.md#forward_range), the delimiter must be a `tiny_range`. A `tiny_range` is a range with static extent whose size is 0 or 1. `tiny_range` requires `sized_range`, and `T::size()` must be a constant-expression that's less than or equal to 1. + +*`V`*\ + The type of the underlying view. + +## Characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +**Range adaptor:** [`lazy_split`](range-adaptors.md#lazy_split) +**Underlying range:** must satisfy [`input_range`](range-concepts.md#input_range) or higher +**View iterator category:** same as the underlying range +**Element type:** collection of `range_reference_t` +**Sized:** no +**Common range:** Yes when the underlying range is both [`forward_range`](range-concepts.md#forward_range) and `common`. +**Borrowed range:** no +**Is `const`-iterable:** only if the underlying range satisfies `forward_range` and is `const`-iterable + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element in the view. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `lazy_split_view` + +```cpp +1) lazy_split_view() = default; +2) constexpr lazy_split_view(V base, Pattern pattern); +3) template requires constructible_from> && + constructible_from>> + constexpr lazy_split_view(R&& rg, range_value_t e); +``` + +### Template parameters + +*`Pattern`*\ +The type of the delimiter. + +*`R`*\ +The type of the range. + +*`V`*\ +The type of the underlying view. + +### Parameters + +*`e`* +A single element that identifies where to split the view. The element isn't part of the resulting subranges. + +*`base`*\ +The underlying view. + +*`pattern`*\ +The view of elements that identifies where to split the view. The view of elements isn't part of the resulting subranges. + +*`rg`*\ +The range to split. + +### Return value + +A `lazy_split_view` instance that contains one or more `subrange`s. + +### Remarks + +The best way to create a `lazy_split_view` is by using the [`views::lazy_split`](range-adaptors.md#lazy_split) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `lazy_split_view` that has no elements. The underlying view is default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `lazy_split_view` by splitting the view using a delimiter sequence.\ +3\) Create a `lazy_split_view` by splitting the view using a delimiter element. + +### Example: `lazy_split_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // pipe syntax using range adaptor + for (const auto& subrange : rg | std::views::split(3)) + { + // Outputs: + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : subrange) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + int delimiters[] = {2, 3}; + for (auto splitRange : std::views::split(rg, delimiters)) // ctor syntax + { + // outputs 1 1 4 5 6 + for (auto& i : splitRange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires forward_range && forward_range +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() const; +2) constexpr auto end() requires forward_range && common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +2\) The `forward_range` requirement means that the view *`V`* has at least a forward iterator. For more information about range iterators, see [View class characteristics](view-classes.md#view-classes-characteristics). The `common_range` requirement means that the view *`V`* has identical iterator and sentinel types. + +## See also + +[``](ranges.md)\ +[`lazy_split` range adaptor](range-adaptors.md#lazy_split)\ +[`split_view` class](split-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/leap-second-class.md b/docs/standard-library/leap-second-class.md index 21a6b81a5e..e06d7d555e 100644 --- a/docs/standard-library/leap-second-class.md +++ b/docs/standard-library/leap-second-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: leap_second class" title: "leap_second class" -ms.date: 06/7/2021 +ms.date: 05/31/2022 f1_keywords: ["chrono/std::chrono::leap_second", "chrono/std::chrono::leap_second::date", "chrono/std::chrono::leap_second::value"] helpviewer_keywords: ["std::chrono [C++], leap_second class", "std::chrono::leap_second::date function", "std::chrono::leap_second::value function"] --- @@ -9,8 +9,6 @@ helpviewer_keywords: ["std::chrono [C++], leap_second class", "std::chrono::leap A `leap_second` represents a date and a value for an inserted leap second. The library creates `leap_second` objects as part of its time zone database initialization. It provides **`const`** access to the created objects. You can't construct or copy a `leap_second` object, and use of the default move constructor or default move assignment operator results in undefined behavior. -Microsoft C++ supports the `leap_second` class starting in Visual Studio 2019 version 16.10. The `leap_second` class is a C++20 feature. The [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option is required. - ## Syntax ```cpp @@ -29,6 +27,10 @@ class leap_second // Since C++20 **Header:** `` +Microsoft C++ supports the `leap_second` class starting in Visual Studio 2019 version 16.10. The `leap_second` class is a C++20 feature. The [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option is required. + +An international standards body specifies when new leap seconds should be accounted for. A database of these changes was added starting in Windows 10 version 1809 and later, and Windows Server 2019 and later. + **Namespace:** `std::chrono` **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/standard-library/leap-second-info-struct.md b/docs/standard-library/leap-second-info-struct.md index 0cfbf3d660..fe7095c841 100644 --- a/docs/standard-library/leap-second-info-struct.md +++ b/docs/standard-library/leap-second-info-struct.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: leap_second_info struct" title: "leap_second_info struct" -ms.date: 06/07/2021 +description: "Learn more about: leap_second_info struct" +ms.date: 05/31/2022 f1_keywords: ["chrono/std::chrono::leap_second_info", "chrono/std::chrono::leap_second_info::is_leap_second", "chrono/std::chrono::leap_second_info::elapsed"] helpviewer_keywords: ["std::chrono [C++], leap_second_info struct", "std::chrono::leap_second_info::date function", "std::chrono::leap_second_info::value function"] --- @@ -9,8 +9,6 @@ helpviewer_keywords: ["std::chrono [C++], leap_second_info struct", "std::chrono Call [`get_leap_second_info`](./chrono-functions.md#std-chrono-get-leap-second-info) to get a `leap_second_info`. This type only has public data members. It doesn't have base classes or members other than the ones specified. -Microsoft C++ supports the `leap_second_info` struct starting in Visual Studio 2019 version 16.10. The `leap_second_info` struct is a C++20 feature. The [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option is required. - ## Syntax ```cpp @@ -22,12 +20,16 @@ struct leap_second_info; // C++20 | Name | Description | |--|--| | `is_leap_second` | The `is_leap_second` member is **`true`** only if the specified time point occurs during the insertion of a positive leap second. | -| `elapsed` | The `elapsed` member holds the sum of all the leap seconds between the epoch date (the starting date from which the clock measures time) `1970-01-01`and the specified time. If `is_leap_second` is **`true`**, the leap second referred to by the specified time is included in the `elapsed` sum. | +| `elapsed` | The `elapsed` member holds the sum of all the leap seconds between the epoch date (the starting date from which the clock measures time) `1970-01-01` and the specified time. If `is_leap_second` is **`true`**, the leap second referred to by the specified time is included in the `elapsed` sum. | ## Requirements **Header:** `` +Microsoft C++ supports the `leap_second` class starting in Visual Studio 2019 version 16.10. The `leap_second` class is a C++20 feature. The [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option is required. + +An international standards body specifies when new leap seconds should be accounted for. A database of these changes is available for Windows 10 version 1809 and later, and Windows Server 2019 and later. + **Namespace:** `std::chrono` ## See also diff --git a/docs/standard-library/limits-enums.md b/docs/standard-library/limits-enums.md index b94c4afc32..791135fc34 100644 --- a/docs/standard-library/limits-enums.md +++ b/docs/standard-library/limits-enums.md @@ -1,21 +1,24 @@ --- -description: "Learn more about: enums" title: " enums" -ms.date: "11/04/2016" +description: "Learn more about: enums" +ms.date: 11/04/2016 f1_keywords: ["limits/std::float_denorm_style", "limits/std::float_round_style"] -ms.assetid: c86680a2-ba97-4ed9-8c20-a448857d7dc5 --- # `` enums -## float_denorm_style +The `` header provides the following enums: + +## `float_denorm_style` The enumeration describes the various methods that an implementation can choose for representing a denormalized floating-point value — one too small to represent as a normalized value: ```cpp -enum float_denorm_style { +enum float_denorm_style +{ denorm_indeterminate = -1, denorm_absent = 0, - denorm_present = 1 }; + denorm_present = 1 +}; ``` ### Return Value @@ -23,26 +26,26 @@ enum float_denorm_style { The enumeration returns: - `denorm_indeterminate` if the presence or absence of denormalized forms cannot be determined at translation time. - - `denorm_absent` if denormalized forms are absent. - - `denorm_present` if denormalized forms are present. ### Example -See [numeric_limits::has_denorm](../standard-library/numeric-limits-class.md#has_denorm) for an example in which the values of this enumeration may be accessed. +See [`numeric_limits::has_denorm`](numeric-limits-class.md#has_denorm) for an example in which the values of this enumeration may be accessed. -## float_round_style +## `float_round_style` The enumeration describes the various methods that an implementation can choose for rounding a floating-point value to an integer value. ```cpp -enum float_round_style { +enum float_round_style +{ round_indeterminate = -1, round_toward_zero = 0, round_to_nearest = 1, round_toward_infinity = 2, - round_toward_neg_infinity = 3 }; + round_toward_neg_infinity = 3 +}; ``` ### Return Value @@ -50,15 +53,11 @@ enum float_round_style { The enumeration returns: - `round_indeterminate` if the rounding method cannot be determined. - - `round_toward_zero` if the round toward zero. - - `round_to_nearest` if the round to nearest integer. - - `round_toward_infinity` if the round away from zero. - - `round_toward_neg_infinity` if the round to more negative integer. ### Example -See [numeric_limits::round_style](../standard-library/numeric-limits-class.md#round_style) for an example in which the values of this enumeration may be accessed. +See [`numeric_limits::round_style`](numeric-limits-class.md#round_style) for an example in which the values of this enumeration may be accessed. diff --git a/docs/standard-library/list-functions.md b/docs/standard-library/list-functions.md index 8f55935efc..7047605aa7 100644 --- a/docs/standard-library/list-functions.md +++ b/docs/standard-library/list-functions.md @@ -1,6 +1,6 @@ --- description: "Learn more about: functions" -title: " functions | Microsoft Docs" +title: functions ms.custom: "" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/standard-library/local_t.md b/docs/standard-library/local_t.md index 4fae2d5d72..b4d78f004b 100644 --- a/docs/standard-library/local_t.md +++ b/docs/standard-library/local_t.md @@ -1,8 +1,10 @@ --- -description: "Learn more about: local_t struct" title: "local_t struct" +description: "Learn more about: local_t struct" ms.date: 09/02/2021 -f1_keywords: ["chrono/std::chrono::local_t"] +f1_keywords: ["chrono/std::chrono::local_t", chrono/std::chrono::local_time", "chrono/std::chrono::local_days", "chrono/std::chrono::local_seconds"] +helpviewer_keywords: ["std::chrono [C++], local_t"] +dev_langs: ["C++"] --- # `local_t` struct @@ -32,9 +34,9 @@ As an example of how `local_t` is used, consider the declaration `local_days ld{ |Name|Description| |----------|-----------------| -|`local_time`|A synonym for `template using local_time = time_point`. Useful for representing a `time_point` for a local time. You specify the `Duration`. Defined in `std::chrono`.| +|`local_days`|A synonym for `local_time`. Defined in `std::chrono`.| |`local_seconds`|A synonym for `local_time`. Defined in `std::chrono`.| -|`local_days`|A synonym for l`local_time`. Defined in `std::chrono`.| +|`local_time`|A synonym for `template using local_time = time_point`. Useful for representing a `time_point` for a local time. You specify the `Duration`. Defined in `std::chrono`.| ## Requirements diff --git a/docs/standard-library/locale-class.md b/docs/standard-library/locale-class.md index 79d509ca84..b627b01ac3 100644 --- a/docs/standard-library/locale-class.md +++ b/docs/standard-library/locale-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: locale Class" title: "locale Class" -ms.date: "07/20/2020" +ms.date: 06/15/2022 f1_keywords: ["xlocale/std::locale", "xlocale/std::locale::category", "xlocale/std::locale::combine", "xlocale/std::locale::name", "xlocale/std::locale::classic", "xlocale/std::locale::global", "xlocale/std::locale::operator( )", "xlocale/std::locale::facet", "xlocale/std::locale::id"] helpviewer_keywords: ["std::locale [C++]", "std::locale [C++], category", "std::locale [C++], combine", "std::locale [C++], name", "std::locale [C++], classic", "std::locale [C++], global", "std::locale [C++], facet", "std::locale [C++], id"] ms.assetid: 7dd6d271-472d-4750-8fb5-ea8f55fbef62 +ms.custom: devdivchpfy22 --- + # locale Class The class that describes a locale object that encapsulates culture-specific information as a set of facets that collectively define a specific localized environment. @@ -202,7 +204,7 @@ Two more useful values are: - `all`, corresponding to the C union of all categories LC_ALL -You can represent an arbitrary group of categories by using `OR` with these constants, as in `monetary` | `time`. +You can represent an arbitrary group of categories by using a bitwise-OR with these constants, as in `monetary | time`. ## locale::classic @@ -275,7 +277,7 @@ The locale containing the facet to be inserted into the target locale. ### Return Value -The member function returns a locale object that replaces in or adds to **\*this** the facet `Facet` listed in *source_locale*. +The member function returns a locale object that replaces in or adds to **`*this`** the facet `Facet` listed in *source_locale*. ### Example @@ -326,7 +328,7 @@ private: You can't copy or assign an object of class `facet`. You can construct and destroy objects derived from class `locale::facet` but not objects of the base class proper. Typically, you construct an object `_Myfac` derived from `facet` when you construct a `locale`, as in `locale loc(locale::classic(), new _Myfac);` -In such cases, the constructor for the base class `facet` should have a zero *references* argument. When the object is no longer needed, it's deleted, so you supply a nonzero *references* argument only in those rare cases where you take responsibility for the lifetime of the object. +In such cases, the constructor for the base class `facet` should have a zero *references* argument. When the object is no longer needed, it's deleted. Supply a nonzero *references* argument only in those rare cases where you take responsibility for the lifetime of the object. ## locale::global diff --git a/docs/standard-library/locale-functions.md b/docs/standard-library/locale-functions.md index cf168fad5d..98ff04ced7 100644 --- a/docs/standard-library/locale-functions.md +++ b/docs/standard-library/locale-functions.md @@ -1,28 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["locale/std::has_facet", "locale/std::isalnum", "locale/std::isalpha", "locale/std::iscntrl", "locale/std::isdigit", "locale/std::isgraph", "locale/std::islower", "locale/std::isprint", "locale/std::ispunct", "locale/std::isspace", "locale/std::isupper", "locale/std::isxdigit", "locale/std::tolower", "locale/std::toupper", "locale/std::use_facet"] -ms.assetid: b06c1ceb-33a7-48d3-8d4b-2714bbb27f14 helpviewer_keywords: ["std::has_facet [C++]", "std::isalnum [C++]", "std::isalpha [C++]", "std::iscntrl [C++]", "std::isdigit [C++]", "std::isgraph [C++]", "std::islower [C++]", "std::isprint [C++]", "std::ispunct [C++]", "std::isspace [C++]", "std::isupper [C++]", "std::isxdigit [C++]", "std::tolower [C++]", "std::toupper [C++]", "std::use_facet [C++]"] --- # `` functions -[has_facet](#has_facet)\ -[isalnum](#isalnum)\ -[isalpha](#isalpha)\ -[iscntrl](#iscntrl)\ -[isdigit](#isdigit)\ -[isgraph](#isgraph)\ -[islower](#islower)\ -[isprint](#isprint)\ -[ispunct](#ispunct)\ -[isspace](#isspace)\ -[isupper](#isupper)\ -[isxdigit](#isxdigit)\ -[tolower](#tolower)\ -[toupper](#toupper)\ -[use_facet](#use_facet) +The `` header provides the following functions: ## has_facet @@ -157,7 +142,7 @@ The locale containing the alphabetic element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **alpha**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **alpha**, `Ch`). ### Example @@ -222,7 +207,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **cntrl**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **cntrl**, `Ch`). ### Example @@ -287,7 +272,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **digit**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **digit**, `Ch`). ### Example @@ -352,7 +337,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **graph**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **graph**, `Ch`). ### Example @@ -417,7 +402,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **lower**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **lower**, `Ch`). ### Example @@ -482,7 +467,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **print**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **print**, `Ch`). ### Example @@ -546,7 +531,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)`<`[ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **punct**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)`<`[ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **punct**, `Ch`). ### Example @@ -611,7 +596,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **space**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **space**, `Ch`). ### Example @@ -676,7 +661,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **upper**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **upper**, `Ch`). ### Example @@ -741,7 +726,7 @@ The locale containing the element to be tested. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **xdigit**, `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [is](../standard-library/ctype-class.md#is)( **ctype**\< **CharType**>:: **xdigit**, `Ch`). Hexadecimal digits use base 16 to represent numbers, using the numbers 0 through 9 plus case-insensitive letters A through F to represent the decimal numbers 0 through 15. @@ -808,7 +793,7 @@ The character converted to lower case. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [tolower](../standard-library/ctype-class.md#tolower)( `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [tolower](../standard-library/ctype-class.md#tolower)(`Ch`). ### Example @@ -857,7 +842,7 @@ The character converted to upper case. ### Remarks -The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >( `Loc`). [toupper](../standard-library/ctype-class.md#toupper)( `Ch`). +The template function returns [use_facet](../standard-library/locale-functions.md#use_facet)< [ctype](../standard-library/ctype-class.md)\< **CharType**> >(`Loc`). [toupper](../standard-library/ctype-class.md#toupper)(`Ch`). ### Example diff --git a/docs/standard-library/logical-and-struct.md b/docs/standard-library/logical-and-struct.md index b3db5ad28e..9cc55e98ba 100644 --- a/docs/standard-library/logical-and-struct.md +++ b/docs/standard-library/logical-and-struct.md @@ -24,7 +24,7 @@ template <> struct logical_and { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) && std::forward(Right)); }; ``` diff --git a/docs/standard-library/logical-not-struct.md b/docs/standard-library/logical-not-struct.md index 4bd846b9b4..88ae5469ff 100644 --- a/docs/standard-library/logical-not-struct.md +++ b/docs/standard-library/logical-not-struct.md @@ -12,7 +12,7 @@ A predefined function object that performs the logical not operation (`operator! ## Syntax -``` +```cpp template struct logical_not : public unary_function { @@ -24,7 +24,7 @@ template <> struct logical_not { template - auto operator()(Type&& Left) const` + auto operator()(Type&& Left) const -> decltype(!std::forward(Left)); }; ``` diff --git a/docs/standard-library/logical-or-struct.md b/docs/standard-library/logical-or-struct.md index 96c90c4fc5..47d9f120cb 100644 --- a/docs/standard-library/logical-or-struct.md +++ b/docs/standard-library/logical-or-struct.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: logical_or Struct" title: "logical_or Struct" -ms.date: "11/04/2016" +description: "Learn more about: logical_or Struct" +ms.date: 11/04/2016 f1_keywords: ["functional/std::logical_or"] helpviewer_keywords: ["logical_or class", "logical_or struct"] -ms.assetid: ec8143f8-5755-4e7b-8025-507fb6bf6911 --- # logical_or Struct -A predefined function object that performs the logical disjunction operation ( `operator||`) on its arguments. +A predefined function object that performs the logical disjunction operation (`operator||`) on its arguments. ## Syntax -``` +```cpp template struct logical_or : public binary_function { @@ -24,7 +23,7 @@ template <> struct logical_or { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) || std::forward(Right)); }; ``` diff --git a/docs/standard-library/map-class.md b/docs/standard-library/map-class.md index 1a115a74e0..c630e1c415 100644 --- a/docs/standard-library/map-class.md +++ b/docs/standard-library/map-class.md @@ -1,7 +1,7 @@ --- title: "map Class" description: "API reference for the C++ Standard Template Library (STL) `map` class, which is used for the storage and retrieval of data from a collection in which each element is a pair that has both a data value and a sort key." -ms.date: "9/10/2020" +ms.date: 9/10/2020 f1_keywords: ["map/std::map", "map/std::map::allocator_type", "map/std::map::const_iterator", "map/std::map::const_pointer", "map/std::map::const_reference", "map/std::map::const_reverse_iterator", "map/std::map::difference_type", "map/std::map::iterator", "map/std::map::key_compare", "map/std::map::key_type", "map/std::map::mapped_type", "map/std::map::pointer", "map/std::map::reference", "map/std::map::reverse_iterator", "map/std::map::size_type", "map/std::map::value_type", "map/std::map::at", "map/std::map::begin", "map/std::map::cbegin", "map/std::map::cend", "map/std::map::clear", "map/std::map::count", "map/std::map::contains", "map/std::map::crbegin", "map/std::map::crend", "map/std::map::emplace", "map/std::map::emplace_hint", "map/std::map::empty", "map/std::map::end", "map/std::map::equal_range", "map/std::map::erase", "map/std::map::find", "map/std::map::get_allocator", "map/std::map::insert", "map/std::map::key_comp", "map/std::map::lower_bound", "map/std::map::max_size", "map/std::map::rbegin", "map/std::map::rend", "map/std::map::size", "map/std::map::swap", "map/std::map::upper_bound", "map/std::map::value_comp"] helpviewer_keywords: ["std::map [C++]", "std::map [C++], allocator_type", "std::map [C++], const_iterator", "std::map [C++], const_pointer", "std::map [C++], const_reference", "std::map [C++], const_reverse_iterator", "std::map [C++], difference_type", "std::map [C++], iterator", "std::map [C++], key_compare", "std::map [C++], key_type", "std::map [C++], mapped_type", "std::map [C++], pointer", "std::map [C++], reference", "std::map [C++], reverse_iterator", "std::map [C++], size_type", "std::map [C++], value_type", "std::map [C++], at", "std::map [C++], begin", "std::map [C++], cbegin", "std::map [C++], cend", "std::map [C++], clear", "std::map [C++], count", "std::map [C++], contains", "std::map [C++], crbegin", "std::map [C++], crend", "std::map [C++], emplace", "std::map [C++], emplace_hint", "std::map [C++], empty", "std::map [C++], end", "std::map [C++], equal_range", "std::map [C++], erase", "std::map [C++], find", "std::map [C++], get_allocator", "std::map [C++], insert", "std::map [C++], key_comp", "std::map [C++], lower_bound", "std::map [C++], max_size", "std::map [C++], rbegin", "std::map [C++], rend", "std::map [C++], size", "std::map [C++], swap", "std::map [C++], upper_bound", "std::map [C++], value_comp"] --- @@ -32,7 +32,7 @@ The element data type to be stored in the `map`. *`Traits`*\ The type that provides a function object that can compare two element values as sort keys to determine their relative order in the `map`. This argument is optional and the binary predicate `less` is the default value. -In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the map's allocation and deallocation of memory. This argument is optional and the default value is `allocator >`. @@ -64,7 +64,7 @@ The map orders the elements it controls by calling a stored function object of t > [!NOTE] > The comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate f(x,y) is a function object that has two argument objects x and y, and a return value of **`true`** or **`false`**. An ordering imposed on a set is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive, and if equivalence is transitive, where two objects x and y are defined to be equivalent when both f(x,y) and f(y,x) are **`false`**. If the stronger condition of equality between keys replaces that of equivalence, the ordering becomes total (in the sense that all the elements are ordered with regard to one other), and the keys matched will be indiscernible from one other. > -> In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +> In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ## Members @@ -552,7 +552,7 @@ The element's key value to look for. `contains()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](./stl-containers.md#heterogeneous-lookup-in-associative-containers-c14) for more information. +`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ### Example @@ -991,7 +991,7 @@ The argument key value to be compared with the sort key of an element from the m ### Return Value -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*(`pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*(`pr`. **second**). ### Example @@ -1434,7 +1434,6 @@ template void print(const M& m) { int main() { - // insert single values map m1; // call insert(const value_type&) version diff --git a/docs/standard-library/map-functions.md b/docs/standard-library/map-functions.md index 29e85f2cf3..6567b76e85 100644 --- a/docs/standard-library/map-functions.md +++ b/docs/standard-library/map-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["map/std::swap (map)", "map/std::swap (multimap)"] -ms.assetid: 7cb3d1a5-7add-4726-a73f-61927eafd466 --- # `` functions @@ -14,8 +13,8 @@ Exchanges the elements of two maps. ```cpp template void swap( - map& left, - map& right); + map& left, + map& right); ``` ### Parameters @@ -28,7 +27,7 @@ The map whose elements are to be exchanged with those of the map *right*. ### Remarks -The template function is an algorithm specialized on the container class map to execute the member function `left`.[swap](../standard-library/map-class.md#swap)( `right`). This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template`** \< **class T**> **void swap**( **T&**, **T&**), in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class map to execute the member function `left`.[swap](../standard-library/map-class.md#swap)(`right`). This is an instance of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template`** \< **class T**> **void swap**( **T&**, **T&**), in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. ### Example @@ -41,8 +40,8 @@ Exchanges the elements of two multimaps. ```cpp template void swap( - multimap& left, - multimap& right); + multimap& left, + multimap& right); ``` ### Parameters diff --git a/docs/standard-library/mask-array-class.md b/docs/standard-library/mask-array-class.md index 84c07ed89f..91320271bd 100644 --- a/docs/standard-library/mask-array-class.md +++ b/docs/standard-library/mask-array-class.md @@ -1,24 +1,22 @@ --- -description: "Learn more about: mask_array Class" -title: "mask_array Class" -ms.date: "11/04/2016" +description: "Learn more about: mask_array class" +title: "mask_array class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::mask_array"] helpviewer_keywords: ["mask_array class"] ms.assetid: c49bed6a-3000-4f39-bff6-cb9a453acb0b --- -# mask_array Class +# `mask_array` class -An internal, auxiliary class template that supports objects that are subsets of parent valarrays, specified with a Boolean expression, by providing operations between the subset arrays. - -## Syntax +An internal, auxiliary class template that supports objects that are subsets of parent `valarray` objects, specified with a Boolean expression, by providing operations between the subset arrays. ## Remarks -The class describes an object that stores a reference to an object `va` of class [valarray](../standard-library/valarray-class.md)**\**, along with an object `ba` of class [valarray\](../standard-library/valarray-bool-class.md), which describes the sequence of elements to select from the `valarray` object. +The class describes an object that stores a reference to an object `va` of class [`valarray`](../standard-library/valarray-class.md), along with an object `ba` of class [`valarray`](../standard-library/valarray-bool-class.md), which describes the sequence of elements to select from the `valarray` object. -You construct a `mask_array` object only by writing an expression of the form [`va[ba]`](../standard-library/valarray-class.md#op_at). The member functions of class mask_array then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. +You construct a `mask_array` object only by writing an expression of the form [`va[ba]`](../standard-library/valarray-class.md#op_at). The member functions of class `mask_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. -The sequence consists of at most `ba.size` elements. An element *J* is included only if **ba**[ *J*] is true. Thus, there are as many elements in the sequence as there are true elements in `ba`. If `I` is the index of the lowest true element in `ba`, then **va**[ `I`] is element zero in the selected sequence. +The sequence consists of at most `ba.size` elements. An element *`J`* is included only if `ba[J]` is `true`. There are as many elements in the sequence as there are `true` elements in `ba`. If `I` is the index of the lowest true element in `ba`, then `va[I]` is element zero in the selected sequence. ## Example @@ -65,7 +63,7 @@ The modified operand valarray is: (0 -1 2 -1 10 -1 10 -1 10 -1). **Header:** \ -**Namespace:** std +**Namespace:** `std` ## See also diff --git a/docs/standard-library/match-results-class.md b/docs/standard-library/match-results-class.md index 7e9db7e089..a9c8eee29f 100644 --- a/docs/standard-library/match-results-class.md +++ b/docs/standard-library/match-results-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: match_results Class" title: "match_results Class" -ms.date: "09/10/2018" +ms.date: 06/17/2022 f1_keywords: ["regex/std::match_results"] helpviewer_keywords: ["match_results class"] ms.assetid: b504fdca-e5dd-429d-9960-6e27c9167fa6 +ms.custom: devdivchpfy22 --- + # match_results Class Holds a sequence of submatches. @@ -416,7 +418,7 @@ Index of the submatch. ### Remarks -The member function returns a reference to element *n* of the controlled sequence, or a reference to an empty `sub_match` object if `size() <= n` or if capture group *n* was not part of the match. +The member function returns a reference to element *n* of the controlled sequence, or a reference to an empty `sub_match` object if `size() <= n` or if capture group *n* wasn't part of the match. ## match_results::position @@ -539,7 +541,7 @@ The match_results object to swap with. ### Remarks -The member function swaps the contents of **`*this`** and *right* in constant time and does not throw exceptions. +The member function swaps the contents of **`*this`** and *right* in constant time and doesn't throw exceptions. ## match_results::value_type diff --git a/docs/standard-library/media/begin-end-sentinel.png b/docs/standard-library/media/begin-end-sentinel.png new file mode 100644 index 0000000000..7ead7b7cb3 Binary files /dev/null and b/docs/standard-library/media/begin-end-sentinel.png differ diff --git a/docs/standard-library/media/cbegin-cend-sentinel.png b/docs/standard-library/media/cbegin-cend-sentinel.png new file mode 100644 index 0000000000..cbd0853d24 Binary files /dev/null and b/docs/standard-library/media/cbegin-cend-sentinel.png differ diff --git a/docs/standard-library/media/crbegin-crend-sentinel.png b/docs/standard-library/media/crbegin-crend-sentinel.png new file mode 100644 index 0000000000..fe39122d53 Binary files /dev/null and b/docs/standard-library/media/crbegin-crend-sentinel.png differ diff --git a/docs/standard-library/media/iterator-hiearchy.svg b/docs/standard-library/media/iterator-hiearchy.svg new file mode 100644 index 0000000000..b843e51f95 --- /dev/null +++ b/docs/standard-library/media/iterator-hiearchy.svg @@ -0,0 +1,185 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.1 + input_or_output_iterator + + + + + + + input_or_output_iterator + + Rectangle.3 + input_iterator + + + + + + + input_iterator + + Rectangle.4 + output_iterator + + + + + + + output_iterator + + Rectangle.5 + forward_iterator + + + + + + + forward_iterator + + Rectangle.6 + contiguous_iterator + + + + + + + contiguous_iterator + + Rectangle.7 + random_access_iterator + + + + + + + random_access_iterator + + Rectangle.8 + bidirectional_iterator + + + + + + + bidirectional_iterator + + Line Arrow.17 + + + + + + + + + + + Line Arrow.18 + + + + + + + + + + + Line Arrow.21 + + + + + + + + + + + Line Arrow.22 + + + + + + + + + + + Line Arrow.23 + + + + + + + + + + + Line Arrow.24 + + + + + + + + + + + Line Arrow.25 + + + + + + + + + + + diff --git a/docs/standard-library/media/ranges-iterator-hiearchy.svg b/docs/standard-library/media/ranges-iterator-hiearchy.svg new file mode 100644 index 0000000000..f16fab6d54 --- /dev/null +++ b/docs/standard-library/media/ranges-iterator-hiearchy.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.3 + input_range + + + + + + + input_range + + Rectangle.4 + output_range + + + + + + + output_range + + Rectangle.5 + forward_range + + + + + + + forward_range + + Rectangle.6 + contiguous_range + + + + + + + contiguous_range + + Rectangle.7 + random_access_range + + + + + + + random_access_range + + Rectangle.8 + bidirectional_range + + + + + + + bidirectional_range + + Line Arrow.17 + + + + + + + + + + + Line Arrow.18 + + + + + + + + + + + Line Arrow.21 + + + + + + + + + + + Line Arrow.22 + + + + + + + + + + + Line Arrow.23 + + + + + + + + + + + diff --git a/docs/standard-library/media/rbegin-rend-sentinel.png b/docs/standard-library/media/rbegin-rend-sentinel.png new file mode 100644 index 0000000000..5d3f63bd12 Binary files /dev/null and b/docs/standard-library/media/rbegin-rend-sentinel.png differ diff --git a/docs/standard-library/media/src/begin-end-sentinel.pdn b/docs/standard-library/media/src/begin-end-sentinel.pdn new file mode 100644 index 0000000000..21c4ab3fd1 Binary files /dev/null and b/docs/standard-library/media/src/begin-end-sentinel.pdn differ diff --git a/docs/standard-library/media/src/cbegin-cend-sentinel.pdn b/docs/standard-library/media/src/cbegin-cend-sentinel.pdn new file mode 100644 index 0000000000..0353247c67 Binary files /dev/null and b/docs/standard-library/media/src/cbegin-cend-sentinel.pdn differ diff --git a/docs/standard-library/media/src/crbegin-crend-sentinel.pdn b/docs/standard-library/media/src/crbegin-crend-sentinel.pdn new file mode 100644 index 0000000000..805891d0de Binary files /dev/null and b/docs/standard-library/media/src/crbegin-crend-sentinel.pdn differ diff --git a/docs/standard-library/media/src/iterator-hiearchy.vsdx b/docs/standard-library/media/src/iterator-hiearchy.vsdx new file mode 100644 index 0000000000..2b4b1e2237 Binary files /dev/null and b/docs/standard-library/media/src/iterator-hiearchy.vsdx differ diff --git a/docs/standard-library/media/src/range-iterator-hiearchy.vsdx b/docs/standard-library/media/src/range-iterator-hiearchy.vsdx new file mode 100644 index 0000000000..c37b38a7e5 Binary files /dev/null and b/docs/standard-library/media/src/range-iterator-hiearchy.vsdx differ diff --git a/docs/standard-library/media/src/rbegin-rend-sentinel.pdn b/docs/standard-library/media/src/rbegin-rend-sentinel.pdn new file mode 100644 index 0000000000..c34cd89ea5 Binary files /dev/null and b/docs/standard-library/media/src/rbegin-rend-sentinel.pdn differ diff --git a/docs/standard-library/memory-functions.md b/docs/standard-library/memory-functions.md index 084121f88e..5163c789b0 100644 --- a/docs/standard-library/memory-functions.md +++ b/docs/standard-library/memory-functions.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "08/05/2019" +description: "Learn more about: functions" +ms.date: 08/05/2019 f1_keywords: ["memory/std::addressof", "memory/std::align", "memory/std::allocate_shared", "memory/std::const_pointer_cast", "memory/std::declare_no_pointers", "memory/std::declare_reachable", "memory/std::dynamic_pointer_cast", "memory/std::get_deleter", "memory/std::get_pointer_safety", "memory/std::get_temporary_buffer", "xmemory/std::get_temporary_buffer", "memory/std::make_shared", "memory/std::make_unique", "memory/std::owner_less", "memory/std::reinterpret_pointer_cast", "memory/std::return_temporary_buffer", "xmemory/std::return_temporary_buffer", "memory/std::static_pointer_cast", "memory/std::swap", "memory/std::undeclare_no_pointers", "memory/std::undeclare_reachable", "memory/std::uninitialized_copy", "memory/std::uninitialized_copy_n", "memory/std::uninitialized_fill", "memory/std::uninitialized_fill_n"] -ms.assetid: 3e1898c2-44b7-4626-87ce-84962e4c6f1a helpviewer_keywords: ["std::addressof [C++]", "std::align [C++]", "std::allocate_shared [C++]", "std::const_pointer_cast [C++]", "std::declare_no_pointers [C++]", "std::declare_reachable [C++]", "std::default_delete [C++]", "std::dynamic_pointer_cast [C++]", "std::get_deleter [C++]", "std::get_pointer_safety [C++]", "std::get_temporary_buffer [C++]", "std::make_shared [C++]", "std::make_unique [C++]", "std::owner_less [C++]", "std::return_temporary_buffer [C++]", "std::static_pointer_cast [C++]", "std::swap [C++]", "std::undeclare_no_pointers [C++]", "std::undeclare_reachable [C++]", "std::uninitialized_copy [C++]", "std::uninitialized_copy_n [C++]", "std::uninitialized_fill [C++]", "std::uninitialized_fill_n [C++]", "std::addressof [C++]", "std::align [C++]", "std::allocate_shared [C++]", "std::const_pointer_cast [C++]", "std::declare_no_pointers [C++]", "std::declare_reachable [C++]", "std::default_delete [C++]", "std::dynamic_pointer_cast [C++]", "std::get_deleter [C++]", "std::get_pointer_safety [C++]", "std::get_temporary_buffer [C++]", "std::make_shared [C++]", "std::make_unique [C++]", "std::owner_less [C++]", "std::return_temporary_buffer [C++]", "std::static_pointer_cast [C++]", "std::undeclare_no_pointers [C++]", "std::undeclare_reachable [C++]", "std::uninitialized_copy [C++]", "std::uninitialized_copy_n [C++]", "std::uninitialized_fill [C++]", "std::uninitialized_fill_n [C++]"] --- # `` functions +The `` header provides the following functions: + ## `addressof` Gets the true address of an object. @@ -768,6 +769,7 @@ struct owner_less> template struct owner_less> +{ bool operator()( const weak_ptr& left, const weak_ptr& right) const noexcept; @@ -982,7 +984,6 @@ template void swap( weak_ptr& left, weak_ptr& right) noexcept; - ``` ### Parameters diff --git a/docs/standard-library/memory-operators.md b/docs/standard-library/memory-operators.md index 0ae10aa886..6fb628d3e2 100644 --- a/docs/standard-library/memory-operators.md +++ b/docs/standard-library/memory-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["memory/std::operator!=", "memory/std::operator>", "memory/std::operator>=", "memory/std::operator<", "memory/std::operator<=", "memory/std::operator<<", "memory/std::operator=="] -ms.assetid: 257e3ba9-c4c2-4ae8-9b11-b156ba9c28de --- # `` operators @@ -127,7 +126,7 @@ bool operator==( template bool operator==( - const shared_ptr& left;, + const shared_ptr& left, const shared_ptr& right); ``` @@ -330,7 +329,7 @@ Tests for one object being greater than a second object. template bool operator>( const unique_ptr& left, - const unique_ptr& right); template bool operator>( diff --git a/docs/standard-library/messages-byname-class.md b/docs/standard-library/messages-byname-class.md index cf22a906dd..fe6b2c1f59 100644 --- a/docs/standard-library/messages-byname-class.md +++ b/docs/standard-library/messages-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: messages_byname Class" title: "messages_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: messages_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xlocmes/std::messages_byname"] helpviewer_keywords: ["messages_byname class"] -ms.assetid: c6c64841-3e80-43c8-b54c-fed41833ad6b --- # messages_byname Class @@ -40,7 +39,7 @@ An initial reference count. ## Remarks -Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [messages](../standard-library/messages-class.md#messages)\( `_Refs`). +Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [messages](../standard-library/messages-class.md#messages)\(`_Refs`). ## Requirements diff --git a/docs/standard-library/messages-class.md b/docs/standard-library/messages-class.md index 7468f6fb3c..4797d927f9 100644 --- a/docs/standard-library/messages-class.md +++ b/docs/standard-library/messages-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: messages Class" title: "messages Class" -ms.date: "11/04/2016" +description: "Learn more about: messages Class" +ms.date: 11/04/2016 f1_keywords: ["xlocmes/std::messages", "xlocmes/std::messages::char_type", "xlocmes/std::messages::string_type", "xlocmes/std::messages::close", "xlocmes/std::messages::do_close", "xlocmes/std::messages::do_get", "xlocmes/std::messages::do_open", "xlocmes/std::messages::get", "xlocmes/std::messages::open"] helpviewer_keywords: ["std::messages [C++]", "std::messages [C++], char_type", "std::messages [C++], string_type", "std::messages [C++], close", "std::messages [C++], do_close", "std::messages [C++], do_get", "std::messages [C++], do_open", "std::messages [C++], get", "std::messages [C++], open"] -ms.assetid: c4c71f40-4f24-48ab-9f7c-daccd8d5bd83 --- # messages Class @@ -214,7 +213,7 @@ It returns a copy of *_Dfault* on failure. Otherwise, it returns a copy of the s ### Remarks -The member function returns [do_get](#do_get)( `_Catval`, `_Set`, `_Message`, `_Dfault`). +The member function returns [do_get](#do_get)(`_Catval`, `_Set`, `_Message`, `_Dfault`). ## messages::messages @@ -249,7 +248,7 @@ The possible values for the *_Refs* parameter and their significance are: No direct examples are possible, because the destructor is protected. -The constructor initializes its base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)( `_Refs`). +The constructor initializes its base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)(`_Refs`). ## messages::open @@ -275,7 +274,7 @@ It returns a value that compares less than zero on failure. Otherwise, the retur ### Remarks -The member function returns [do_open](#do_open)( `_Catname`, `_Loc`). +The member function returns [do_open](#do_open)(`_Catname`, `_Loc`). ## messages::string_type diff --git a/docs/standard-library/minus-struct.md b/docs/standard-library/minus-struct.md index 17bbcfff3e..2651c1f981 100644 --- a/docs/standard-library/minus-struct.md +++ b/docs/standard-library/minus-struct.md @@ -12,7 +12,7 @@ A predefined function object that performs the subtraction operation (binary `op ## Syntax -``` +```cpp template struct minus : public binary_function { @@ -24,7 +24,7 @@ template <> struct minus { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) - std::forward(Right)); }; ``` diff --git a/docs/standard-library/modulus-struct.md b/docs/standard-library/modulus-struct.md index 82b6ce9572..1697f2a73a 100644 --- a/docs/standard-library/modulus-struct.md +++ b/docs/standard-library/modulus-struct.md @@ -12,7 +12,7 @@ A predefined function object that performs the modulus division operation (`oper ## Syntax -``` +```cpp template struct modulus : public binary_function { @@ -24,7 +24,7 @@ template <> struct modulus { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) % std::forward(Right)); }; ``` diff --git a/docs/standard-library/money-get-class.md b/docs/standard-library/money-get-class.md index 3adbf050df..275a645404 100644 --- a/docs/standard-library/money-get-class.md +++ b/docs/standard-library/money-get-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: money_get Class" title: "money_get Class" -ms.date: "11/04/2016" +description: "Learn more about: money_get Class" +ms.date: 11/04/2016 f1_keywords: ["xlocmon/std::money_get", "xlocmon/std::money_get::char_type", "xlocmon/std::money_get::iter_type", "xlocmon/std::money_get::string_type", "xlocmon/std::money_get::do_get", "xlocmon/std::money_get::get"] helpviewer_keywords: ["std::money_get [C++]", "std::money_get [C++], char_type", "std::money_get [C++], iter_type", "std::money_get [C++], string_type", "std::money_get [C++], do_get", "std::money_get [C++], get"] -ms.assetid: 692d3374-3fe7-4b46-8aeb-f8d91ed66b2e --- # money_get Class @@ -112,7 +111,7 @@ An input iterator addressing the first element beyond the monetary input field. ### Remarks -The first virtual protected member function tries to match sequential elements beginning at first in the sequence [ `first`, `last`) until it has recognized a complete, nonempty monetary input field. If successful, it converts this field to a sequence of one or more decimal digits, optionally preceded by a minus sign ( `-`), to represent the amount and stores the result in the [string_type](#string_type) object *val*. It returns an iterator designating the first element beyond the monetary input field. Otherwise, the function stores an empty sequence in *val* and sets `ios_base::failbit` in *State*. It returns an iterator designating the first element beyond any prefix of a valid monetary input field. In either case, if the return value equals `last`, the function sets `ios_base::eofbit` in `State`. +The first virtual protected member function tries to match sequential elements beginning at first in the sequence [ `first`, `last`) until it has recognized a complete, nonempty monetary input field. If successful, it converts this field to a sequence of one or more decimal digits, optionally preceded by a minus sign (`-`), to represent the amount and stores the result in the [string_type](#string_type) object *val*. It returns an iterator designating the first element beyond the monetary input field. Otherwise, the function stores an empty sequence in *val* and sets `ios_base::failbit` in *State*. It returns an iterator designating the first element beyond any prefix of a valid monetary input field. In either case, if the return value equals `last`, the function sets `ios_base::eofbit` in `State`. The second virtual protected member function behaves the same as the first, except that if successful it converts the optionally signed digit sequence to a value of type **`long double`** and stores that value in *val*. @@ -242,7 +241,7 @@ int main( ) else cout << "money_get(" << psz2.str( ) << ", intl = 0) = " << fVal/100.0 << endl; -}; +} ``` ## money_get::iter_type diff --git a/docs/standard-library/money-put-class.md b/docs/standard-library/money-put-class.md index b613399484..af0388fc0b 100644 --- a/docs/standard-library/money-put-class.md +++ b/docs/standard-library/money-put-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: money_put Class" title: "money_put Class" -ms.date: "11/01/2018" +description: "Learn more about: money_put Class" +ms.date: 11/01/2018 f1_keywords: ["xlocmon/std::money_put", "xlocmon/std::money_put::char_type", "xlocmon/std::money_put::iter_type", "xlocmon/std::money_put::string_type", "xlocmon/std::money_put::do_put", "xlocmon/std::money_put::put"] helpviewer_keywords: ["std::money_put [C++]", "std::money_put [C++], char_type", "std::money_put [C++], iter_type", "std::money_put [C++], string_type", "std::money_put [C++], do_put", "std::money_put [C++], put"] -ms.assetid: f439fd56-c9b1-414c-95e1-66c918c6eee6 --- # money_put Class @@ -189,7 +188,7 @@ The possible values for the *_Refs* parameter and their significance are: No direct examples are possible, because the destructor is protected. -The constructor initializes its base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)( `_Refs`). +The constructor initializes its base object with **locale::**[facet](../standard-library/locale-class.md#facet_class)(`_Refs`). ## money_put::put @@ -234,7 +233,7 @@ An output iterator the addresses the position one beyond the last element produc ### Remarks -Both member functions return [do_put](#do_put)( `next`, `_Intl`, `_Iosbase`, `_Fill`, `val`). +Both member functions return [do_put](#do_put)(`next`, `_Intl`, `_Iosbase`, `_Fill`, `val`). ### Example diff --git a/docs/standard-library/moneypunct-byname-class.md b/docs/standard-library/moneypunct-byname-class.md index 701923e297..9fb1ed976d 100644 --- a/docs/standard-library/moneypunct-byname-class.md +++ b/docs/standard-library/moneypunct-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: moneypunct_byname Class" title: "moneypunct_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: moneypunct_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xlocmon/std::moneypunct_byname"] helpviewer_keywords: ["moneypunct_byname class"] -ms.assetid: e8a544d2-6aee-420d-b513-deb385c9b416 --- # moneypunct_byname Class @@ -33,7 +32,7 @@ protected: ## Remarks -Its behavior is determined by the named locale `_Locname`. Each constructor initializes its base object with [moneypunct](../standard-library/moneypunct-class.md#moneypunct)\( `_Refs`). +Its behavior is determined by the named locale `_Locname`. Each constructor initializes its base object with [moneypunct](../standard-library/moneypunct-class.md#moneypunct)\(`_Refs`). ## Requirements diff --git a/docs/standard-library/moneypunct-class.md b/docs/standard-library/moneypunct-class.md index 04d7631261..2e5d396250 100644 --- a/docs/standard-library/moneypunct-class.md +++ b/docs/standard-library/moneypunct-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: moneypunct Class" title: "moneypunct Class" -ms.date: "11/04/2016" +description: "Learn more about: moneypunct Class" +ms.date: 11/04/2016 f1_keywords: ["xlocmon/std::moneypunct", "xlocmon/std::moneypunct::char_type", "xlocmon/std::moneypunct::string_type", "xlocmon/std::moneypunct::curr_symbol", "xlocmon/std::moneypunct::decimal_point", "xlocmon/std::moneypunct::do_curr_symbol", "xlocmon/std::moneypunct::do_decimal_point", "xlocmon/std::moneypunct::do_frac_digits", "xlocmon/std::moneypunct::do_grouping", "xlocmon/std::moneypunct::do_neg_format", "xlocmon/std::moneypunct::do_negative_sign", "xlocmon/std::moneypunct::do_pos_format", "xlocmon/std::moneypunct::do_positive_sign", "xlocmon/std::moneypunct::do_thousands_sep", "xlocmon/std::moneypunct::frac_digits", "xlocmon/std::moneypunct::grouping", "xlocmon/std::moneypunct::neg_format", "xlocmon/std::moneypunct::negative_sign", "xlocmon/std::moneypunct::pos_format", "xlocmon/std::moneypunct::positive_sign", "xlocmon/std::moneypunct::thousands_sep"] helpviewer_keywords: ["std::moneypunct [C++]", "std::moneypunct [C++], char_type", "std::moneypunct [C++], string_type", "std::moneypunct [C++], curr_symbol", "std::moneypunct [C++], decimal_point", "std::moneypunct [C++], do_curr_symbol", "std::moneypunct [C++], do_decimal_point", "std::moneypunct [C++], do_frac_digits", "std::moneypunct [C++], do_grouping", "std::moneypunct [C++], do_neg_format", "std::moneypunct [C++], do_negative_sign", "std::moneypunct [C++], do_pos_format", "std::moneypunct [C++], do_positive_sign", "std::moneypunct [C++], do_thousands_sep", "std::moneypunct [C++], frac_digits", "std::moneypunct [C++], grouping", "std::moneypunct [C++], neg_format", "std::moneypunct [C++], negative_sign", "std::moneypunct [C++], pos_format", "std::moneypunct [C++], positive_sign", "std::moneypunct [C++], thousands_sep"] -ms.assetid: cf2650da-3e6f-491c-95d5-23e57f582ee6 --- # moneypunct Class @@ -119,7 +118,7 @@ int main( ) const moneypunct < char, false> &mpunct2 = use_facet < moneypunct < char, false> >(loc); cout << loc.name( ) << " domestic currency symbol "<< mpunct2.curr_symbol( ) << endl; -}; +} ``` ## moneypunct::decimal_point @@ -593,7 +592,7 @@ int main( ) use_facet >(loc2); cout << loc2.name( ) << " domestic negative sign: " << mpunct4.negative_sign( ) << endl; -}; +} ``` ```Output @@ -703,7 +702,7 @@ int main( ) use_facet >(loc2); cout << loc2.name( ) << " domestic positive sign:" << mpunct4.positive_sign( ) << endl; -}; +} ``` ```Output diff --git a/docs/standard-library/month-class.md b/docs/standard-library/month-class.md index 0b3fe5d94b..047db99cf2 100644 --- a/docs/standard-library/month-class.md +++ b/docs/standard-library/month-class.md @@ -4,6 +4,7 @@ title: "month class" ms.date: "6/25/2021" f1_keywords: ["chrono/std::chrono::month", "chrono/std::chrono::month::January", "chrono/std::chrono::month::February", "chrono/std::chrono::month::March","chrono/std::chrono::month::April","chrono/std::chrono::month::May","chrono/std::chrono::month::June","chrono/std::chrono::month::July","chrono/std::chrono::month::August","chrono/std::chrono::month::September","chrono/std::chrono::month::October","chrono/std::chrono::month::November","chrono/std::chrono::month::December","chrono/std::chrono::month::operator++", "chrono/std::chrono::month::operator--", "chrono/std::chrono::month::operator unsigned", "chrono/std::chrono::month::ok"] helpviewer_keywords: ["std::chrono [C++], month"] +dev_langs: ["C++"] --- # `month` class @@ -12,7 +13,7 @@ Represents a month of a year. For example, July. ## Syntax ```cpp -class month; // C++ 20 +class month; // C++20 ``` ## Remarks @@ -25,7 +26,7 @@ See [Month constants](#month-constants), below, for constants that you can use w |Name|Description| |----------|-----------------| | [Constructors](#month) | Construct a `month`. | -| [`ok`](#ok) | Verify that the month value is in the valid range [1,31]. | +| [`ok`](#ok) | Verify that the month value is in the valid range [1,12]. | | [`operator++`](#op_++) | Increment the `month`. | | [`operator+=`](#op_+=) | Add the specified number of months to this `month`. | | [`operator--`](#op_--) | Decrement this `month`. | @@ -271,4 +272,4 @@ inline constexpr month December{12}; [`month_day` Class](month-day-class.md)\ [`month_day_last` Class](month-day-last-class.md)\ [`month_weekday` Class](month-weekday-class.md)\ -[`month_weekday_last` class](month-weekday-last-class.md) \ No newline at end of file +[`month_weekday_last` class](month-weekday-last-class.md) diff --git a/docs/standard-library/month-day-class.md b/docs/standard-library/month-day-class.md index 7cf0ca6720..a84c17ac08 100644 --- a/docs/standard-library/month-day-class.md +++ b/docs/standard-library/month-day-class.md @@ -4,6 +4,7 @@ title: "month_day class" ms.date: "6/28/2021" f1_keywords: ["chrono/std::chrono::month_day", "chrono/std::chrono::month_day::day", "chrono/std::chrono::month_day::month", "chrono/std::chrono::month_day::ok"] helpviewer_keywords: ["std::chrono [C++], month_day"] +dev_langs: ["C++"] --- # `month_day` class @@ -64,7 +65,7 @@ Construct a `month_day` with a month value of *`m`*. 1\) The default constructor doesn't initialize the month or day values.\ 2\) Construct a `month_day` with the month value initialized to `m` and the day value initialized to `d`. -For information about C++ 20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `month_day` diff --git a/docs/standard-library/month-day-last-class.md b/docs/standard-library/month-day-last-class.md index 3fa95000d9..7b7780dfbe 100644 --- a/docs/standard-library/month-day-last-class.md +++ b/docs/standard-library/month-day-last-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: month_day_last Class" title: "month_day_last class" +description: "Learn more about: month_day_last Class" ms.date: "06/28/2021" f1_keywords: ["chrono/std::chrono::month_day_last", "chrono/std::chrono::month_day_last::month", "chrono/std::chrono::month_day_last::ok"] helpviewer_keywords: ["std::chrono [C++], month_day_last"] +dev_langs: ["C++"] --- # `month_day_last` class @@ -13,7 +14,7 @@ helpviewer_keywords: ["std::chrono [C++], month_day_last"] ## Syntax ```cpp -class month_day_last; // C++ 20 +class month_day_last; // C++20 ``` ## Members @@ -55,7 +56,7 @@ Construct a `month_day_last` for the month specified by *`m`*. ## Remarks -For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `month_day_last` @@ -110,5 +111,5 @@ constexpr bool ok() const noexcept; [`month_day_last` class](month-day-last-class.md)\ [`month_weekday` class](month-weekday-class.md)\ [`month_weekday_last` class](month-weekday-last-class.md)\ -[`operator/`](chrono-operators.md#op_/) -[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file +[`operator/`](chrono-operators.md#op_/)\ +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/month-weekday-class.md b/docs/standard-library/month-weekday-class.md index 8419f52f23..0156b70386 100644 --- a/docs/standard-library/month-weekday-class.md +++ b/docs/standard-library/month-weekday-class.md @@ -4,16 +4,17 @@ title: "month_weekday class" ms.date: "06/28/2021" f1_keywords: ["chrono/std::chrono::month_weekday", "chrono/std::chrono::month_weekday::weekday", "chrono/std::chrono::month_weekday::month", "chrono/std::chrono::month_weekday::ok", "chrono/std::chrono::month_weekday::weekday_indexed"] helpviewer_keywords: ["std::chrono [C++], month_weekday"] +dev_langs: ["C++"] --- # `month_weekday` class -Represents the nth weekday of a specific month. +Represents the nth weekday of a specific month. ## Syntax ```cpp -class month_weekday; // C++ 20 +class month_weekday; // C++20 ``` ## Remarks @@ -63,7 +64,7 @@ Construct a `month_weekday` with a weekday value of *`wdi`*. ### Remarks: Constructor -For information about C++ 20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `month_weekday` diff --git a/docs/standard-library/month-weekday-last-class.md b/docs/standard-library/month-weekday-last-class.md index fe6b308d99..34770527f7 100644 --- a/docs/standard-library/month-weekday-last-class.md +++ b/docs/standard-library/month-weekday-last-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: month_weekday_last Class" title: "month_weekday_last class" +description: "Learn more about: month_weekday_last Class" ms.date: "6/28/2021" f1_keywords: ["chrono/std::chrono::month_weekday_last", "chrono/std::chrono::month_weekday_last::ok", "std::chrono::month_weekday_last::month_weekday_last", "chrono/std::chrono::month_weekday_last::ok", "chrono/std::chrono::month_weekday_last::month"] helpviewer_keywords: ["std::chrono [C++], month_weekday_last"] +dev_langs: ["C++"] --- # `month_weekday_last` class @@ -38,7 +39,7 @@ The year is unspecified.\ ## Requirements -**Header:** `` Since C++ 20 +**Header:** `` Since C++20 **Namespace:** `std::chrono` @@ -58,11 +59,11 @@ constexpr month_weekday_last(const month& m, const weekday_last& wdl) noexcept; The `month` value for the created `month_weekday_last` class. *`wdl`*\ -The` weekday_last` value for the created `month_weekday_last` class. +The `weekday_last` value for the created `month_weekday_last` class. ## Remarks: Constructor -For information about C++ 20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `month_weekday_last` diff --git a/docs/standard-library/move-iterator-class.md b/docs/standard-library/move-iterator-class.md index f3f3f41755..ca1f45c906 100644 --- a/docs/standard-library/move-iterator-class.md +++ b/docs/standard-library/move-iterator-class.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: move_iterator Class" title: "move_iterator Class" -ms.date: "03/27/2019" +description: "Learn more about: move_iterator Class" +ms.date: 06/17/2022 f1_keywords: ["iterator/std::move_iterator", "iterator/std::move_iterator::iterator_type", "iterator/std::move_iterator::iterator_category", "iterator/std::move_iterator::value_type", "iterator/std::move_iterator::difference_type", "iterator/std::move_iterator::pointer", "iterator/std::move_iterator::reference", "iterator/std::move_iterator::base"] helpviewer_keywords: ["std::move_iterator [C++]", "std::move_iterator [C++], iterator_type", "std::move_iterator [C++], iterator_category", "std::move_iterator [C++], value_type", "std::move_iterator [C++], difference_type", "std::move_iterator [C++], pointer", "std::move_iterator [C++], reference", "std::move_iterator [C++], base"] -ms.assetid: a5e5cdd8-a264-4c6b-9f9c-68b0e8edaab7 +ms.custom: devdivchpfy22 --- + # move_iterator Class -Class template `move_iterator` is a wrapper for an iterator. The move_iterator provides the same behavior as the iterator it wraps (stores), except it turns the stored iterator’s dereference operator into an rvalue reference, turning a copy into a move. For more information about rvalues, see [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +Class template `move_iterator` is a wrapper for an iterator. The move_iterator provides the same behavior as the iterator it wraps (stores), except it turns the stored iterator's dereference operator into an rvalue reference, turning a copy into a move. For more information about rvalues, see [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). ## Syntax @@ -20,7 +21,7 @@ class move_iterator; The class template describes an object that behaves like an iterator except when dereferenced. It stores a random-access iterator of type `Iterator`, accessed by way of the member function `base()`. All operations on a `move_iterator` are performed directly on the stored iterator, except that the result of `operator*` is implicitly cast to `value_type&&` to make an rvalue reference. -A `move_iterator` might be capable of operations that are not defined by the wrapped iterator. These operations should not be used. +A `move_iterator` might be capable of operations that aren't defined by the wrapped iterator. These operations shouldn't be used. ### Constructors @@ -49,9 +50,9 @@ A `move_iterator` might be capable of operations that are not defined by the wra |Operator|Description| |-|-| -|[move_iterator::operator*](#op_star)|Returns `(reference)*base().`| -|[move_iterator::operator++](#op_add_add)|Increments the stored iterator. Exact behavior depends on whether it is a preincrement or a postincrement operation.| -|[move_iterator::operator--](#operator--)|Decrements the stored iterator. Exact behavior depends on whether it is a predecrement or a postdecrement operation.| +|[move_iterator::operator*](#op_star)|Returns `(reference)*base()`.| +|[move_iterator::operator++](#op_add_add)|Increments the stored iterator. Exact behavior depends on whether it's a preincrement or a postincrement operation.| +|[move_iterator::operator--](#operator--)|Decrements the stored iterator. Exact behavior depends on whether it's a predecrement or a postdecrement operation.| |[`move_iterator::operator->`](#op_arrow)|Returns `&**this`.| |[move_iterator::operator-](#operator-)|Returns `move_iterator(*this) -=` by first subtracting the right-hand value from the current position.| |[move_iterator::operator[]](#op_at)|Returns `(reference)*(*this + off)`. Allows you to specify an offset from the current base to obtain the value at that location.| @@ -170,7 +171,7 @@ The operator evaluates `*this += -_Off`. Then returns **`*this`**. ## move_iterator::operator++ -Increments the stored iterator that belongs to this `move_iterator.` The current element is accessed by the postincrement operator. The next element is accessed by the preincrement operator. +Increments the stored iterator that belongs to this `move_iterator`. The current element is accessed by the postincrement operator. The next element is accessed by the preincrement operator. ```cpp move_iterator& operator++(); diff --git a/docs/standard-library/multimap-class.md b/docs/standard-library/multimap-class.md index 79e31bfef8..fd24a711eb 100644 --- a/docs/standard-library/multimap-class.md +++ b/docs/standard-library/multimap-class.md @@ -21,18 +21,18 @@ class multimap; ### Parameters -*Key*\ +*`Key`*\ The key data type to be stored in the multimap. -*Type*\ +*`Type`*\ The element data type to be stored in the multimap. -*Traits*\ +*`Traits`*\ The type that provides a function object that can compare two element values as sort keys to determine their relative order in the multimap. The binary predicate `less` is the default value. -In C++14 you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. For more information, see [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#heterogeneous-lookup-in-associative-containers-c14) +In C++14 you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. For more information, see [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) -*Allocator*\ +*`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the map's allocation and deallocation of memory. This argument is optional and the default value is `allocator >`. ## Remarks @@ -51,15 +51,15 @@ The C++ Standard Library multimap class is - A class template, because the functionality it provides is generic and so independent of the specific type of data contained as elements or keys. The data types to be used for elements and keys are, instead, specified as parameters in the class template along with the comparison function and allocator. -The iterator provided by the map class is a bidirectional iterator, but the class member functions [insert](#insert) and [multimap](#multimap) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it is enough to be able to talk meaningfully about a range of iterators `[First, Last)` in the context of the class's member functions. +The iterator provided by the map class is a bidirectional iterator, but the class member functions [`insert`](#insert) and [`multimap`](#multimap) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it is enough to be able to talk meaningfully about a range of iterators `[First, Last)` in the context of the class's member functions. The choice of container type should be based in general on the type of searching and inserting required by the application. Associative containers are optimized for the operations of lookup, insertion, and removal. The member functions that explicitly support these operations are efficient, performing them in a time that is on average proportional to the logarithm of the number of elements in the container. Inserting elements invalidates no iterators, and removing elements invalidates only those iterators that had pointed at the removed elements. -The multimap should be the associative container of choice when the conditions associating the values with their keys are satisfied by the application. A model for this type of structure is an ordered list of key words with associated string values providing, say, definitions, where the words weren't always uniquely defined. If, instead, the key words were uniquely defined so that keys were unique, then a map would be the container of choice. If, on the other hand, just the list of words were being stored, then a set would be the correct container. If multiple occurrences of the words were allowed, then a `multiset` would be the appropriate container structure. +The `multimap` should be the associative container of choice when the conditions associating the values with their keys are satisfied by the application. A model for this type of structure is an ordered list of key words with associated string values providing, say, definitions, where the words weren't always uniquely defined. If, instead, the key words were uniquely defined so that keys were unique, then a map would be the container of choice. If, on the other hand, just the list of words were being stored, then a set would be the correct container. If multiple occurrences of the words were allowed, then a `multiset` would be the appropriate container structure. -The multimap orders the sequence it controls by calling a stored function object of type [key_compare](#key_compare). This stored object is a comparison function that may be accessed by calling the member function [key_comp](#key_comp). In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate `f(x,y)` is a function object that has two argument objects `x` and `y` and a return value of true or false. An ordering imposed on a set is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects `x` and `y` are defined to be equivalent when both `f(x,y)` and `f(y,x)` are false. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. +The `multimap` orders the sequence it controls by calling a stored function object of type [`key_compare`](#key_compare). This stored object is a comparison function that may be accessed by calling the member function [`key_comp`](#key_comp). In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate `f(x,y)` is a function object that has two argument objects `x` and `y` and a return value of `true` or `false`. An ordering imposed on a set is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects `x` and `y` are defined to be equivalent when both `f(x,y)` and `f(y,x)` are `false`. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. -In C++14 you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14 you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ## Members @@ -67,74 +67,74 @@ In C++14 you can enable heterogeneous lookup by specifying the `std::less<>` or |Constructor|Description| |-|-| -|[multimap](#multimap)|Constructs a `multimap` that is empty or that is a copy of all or part of some other `multimap`.| +|[`multimap`](#multimap)|Constructs a `multimap` that is empty or that is a copy of all or part of some other `multimap`.| ### Typedefs |Type name|Description| |-|-| -|[allocator_type](#allocator_type)|A type that represents the `allocator` class for the `multimap` object.| -|[const_iterator](#const_iterator)|A type that provides a bidirectional iterator that can read a **`const`** element in the `multimap`.| -|[const_pointer](#const_pointer)|A type that provides a pointer to a **`const`** element in a `multimap`.| -|[const_reference](#const_reference)|A type that provides a reference to a **`const`** element stored in a `multimap` for reading and performing **`const`** operations.| -|[const_reverse_iterator](#const_reverse_iterator)|A type that provides a bidirectional iterator that can read any **`const`** element in the `multimap`.| -|[difference_type](#difference_type)|A signed integer type that can be used to represent the number of elements of a `multimap` in a range between elements pointed to by iterators.| -|[iterator](#iterator)|A type that provides the difference between two iterators that refer to elements within the same `multimap`.| -|[key_compare](#key_compare)|A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the `multimap`.| -|[key_type](#key_type)|A type that describes the sort key object that makes up each element of the `multimap`.| -|[mapped_type](#mapped_type)|A type that represents the data type stored in a `multimap`.| -|[pointer](#pointer)|A type that provides a pointer to a **`const`** element in a `multimap`.| -|[reference](#reference)|A type that provides a reference to an element stored in a `multimap`.| -|[reverse_iterator](#reverse_iterator)|A type that provides a bidirectional iterator that can read or modify an element in a reversed `multimap`.| -|[size_type](#size_type)|An unsigned integer type that provides a pointer to a **`const`** element in a `multimap`.| -|[value_type](#value_type)|A type that provides a function object that can compare two elements as sort keys to determine their relative order in the `multimap`.| +|[`allocator_type`](#allocator_type)|A type that represents the `allocator` class for the `multimap` object.| +|[`const_iterator`](#const_iterator)|A type that provides a bidirectional iterator that can read a **`const`** element in the `multimap`.| +|[`const_pointer`](#const_pointer)|A type that provides a pointer to a **`const`** element in a `multimap`.| +|[`const_reference`](#const_reference)|A type that provides a reference to a **`const`** element stored in a `multimap` for reading and performing **`const`** operations.| +|[`const_reverse_iterator`](#const_reverse_iterator)|A type that provides a bidirectional iterator that can read any **`const`** element in the `multimap`.| +|[`difference_type`](#difference_type)|A signed integer type that can be used to represent the number of elements of a `multimap` in a range between elements pointed to by iterators.| +|[`iterator`](#iterator)|A type that provides the difference between two iterators that refer to elements within the same `multimap`.| +|[`key_compare`](#key_compare)|A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the `multimap`.| +|[`key_type`](#key_type)|A type that describes the sort key object that makes up each element of the `multimap`.| +|[`mapped_type`](#mapped_type)|A type that represents the data type stored in a `multimap`.| +|[`pointer`](#pointer)|A type that provides a pointer to a **`const`** element in a `multimap`.| +|[`reference`](#reference)|A type that provides a reference to an element stored in a `multimap`.| +|[`reverse_iterator`](#reverse_iterator)|A type that provides a bidirectional iterator that can read or modify an element in a reversed `multimap`.| +|[`size_type`](#size_type)|An unsigned integer type that provides a pointer to a **`const`** element in a `multimap`.| +|[`value_type`](#value_type)|A type that provides a function object that can compare two elements as sort keys to determine their relative order in the `multimap`.| ### Member functions |Member function|Description| |-|-| -|[begin](#begin)|Returns an iterator addressing the first element in the `multimap`.| -|[cbegin](#cbegin)|Returns a const iterator addressing the first element in the `multimap`.| -|[cend](#cend)|Returns a const iterator that addresses the location succeeding the last element in a `multimap`.| -|[clear](#clear)|Erases all the elements of a `multimap`.| -|[contains](#contains)C++20|Checks if there is an element with the specified key in the `multimap`.| -|[count](#count)|Returns the number of elements in a `multimap` whose key matches a parameter-specified key.| -|[crbegin](#crbegin)|Returns a const iterator addressing the first element in a reversed `multimap`.| -|[crend](#crend)|Returns a const iterator that addresses the location succeeding the last element in a reversed `multimap`.| -|[emplace](#emplace)|Inserts an element constructed in place into a `multimap`.| -|[emplace_hint](#emplace_hint)|Inserts an element constructed in place into a `multimap`, with a placement hint| -|[empty](#empty)|Tests if a `multimap` is empty.| -|[end](#end)|Returns an iterator that addresses the location succeeding the last element in a `multimap`.| -|[equal_range](#equal_range)|Finds the range of elements where the key of the element matches a specified value.| -|[erase](#erase)|Removes an element or a range of elements in a `multimap` from specified positions or removes elements that match a specified key.| -|[find](#find)|Returns an iterator addressing the first location of an element in a `multimap` that has a key equivalent to a specified key.| -|[get_allocator](#get_allocator)|Returns a copy of the `allocator` object used to construct the `multimap`.| -|[insert](#insert)|Inserts an element or a range of elements into a `multimap`.| -|[key_comp](#key_comp)|Retrieves a copy of the comparison object used to order keys in a `multimap`.| -|[lower_bound](#lower_bound)|Returns an iterator to the first element in a `multimap` that with a key that is equal to or greater than a specified key.| -|[max_size](#max_size)|Returns the maximum length of the `multimap`.| -|[rbegin](#rbegin)|Returns an iterator addressing the first element in a reversed `multimap`.| -|[rend](#rend)|Returns an iterator that addresses the location succeeding the last element in a reversed `multimap`.| -|[size](#size)|Returns the number of elements in the `multimap`.| -|[swap](#swap)|Exchanges the elements of two `multimap`s.| -|[upper_bound](#upper_bound)|Returns an iterator to the first element in a `multimap` that with a key that is greater than a specified key.| -|[value_comp](#value_comp)|The member function returns a function object that determines the order of elements in a `multimap` by comparing their key values.| +|[`begin`](#begin)|Returns an iterator addressing the first element in the `multimap`.| +|[`cbegin`](#cbegin)|Returns a `const` iterator addressing the first element in the `multimap`.| +|[`cend`](#cend)|Returns a `const` iterator that addresses the location succeeding the last element in a `multimap`.| +|[`clear`](#clear)|Erases all the elements of a `multimap`.| +|[`contains`](#contains)C++20|Checks if there is an element with the specified key in the `multimap`.| +|[`count`](#count)|Returns the number of elements in a `multimap` whose key matches a parameter-specified key.| +|[`crbegin`](#crbegin)|Returns a `const` iterator addressing the first element in a reversed `multimap`.| +|[`crend`](#crend)|Returns a `const` iterator that addresses the location succeeding the last element in a reversed `multimap`.| +|[`emplace`](#emplace)|Inserts an element constructed in place into a `multimap`.| +|[`emplace_hint`](#emplace_hint)|Inserts an element constructed in place into a `multimap`, with a placement hint| +|[`empty`](#empty)|Tests if a `multimap` is empty.| +|[`end`](#end)|Returns an iterator that addresses the location succeeding the last element in a `multimap`.| +|[`equal_range`](#equal_range)|Finds the range of elements where the key of the element matches a specified value.| +|[`erase`](#erase)|Removes an element or a range of elements in a `multimap` from specified positions or removes elements that match a specified key.| +|[`find`](#find)|Returns an iterator addressing the first location of an element in a `multimap` that has a key equivalent to a specified key.| +|[`get_allocator`](#get_allocator)|Returns a copy of the `allocator` object used to construct the `multimap`.| +|[`insert`](#insert)|Inserts an element or a range of elements into a `multimap`.| +|[`key_comp`](#key_comp)|Retrieves a copy of the comparison object used to order keys in a `multimap`.| +|[`lower_bound`](#lower_bound)|Returns an iterator to the first element in a `multimap` that with a key that is equal to or greater than a specified key.| +|[`max_size`](#max_size)|Returns the maximum length of the `multimap`.| +|[`rbegin`](#rbegin)|Returns an iterator addressing the first element in a reversed `multimap`.| +|[`rend`](#rend)|Returns an iterator that addresses the location succeeding the last element in a reversed `multimap`.| +|[`size`](#size)|Returns the number of elements in the `multimap`.| +|[`swap`](#swap)|Exchanges the elements of two `multimap`s.| +|[`upper_bound`](#upper_bound)|Returns an iterator to the first element in a `multimap` that with a key that is greater than a specified key.| +|[`value_comp`](#value_comp)|The member function returns a function object that determines the order of elements in a `multimap` by comparing their key values.| |Operator|Description| |-|-| -|[operator=](#op_eq)|Replaces the elements of a `multimap` with a copy of another `multimap`.| +|[`operator=`](#op_eq)|Replaces the elements of a `multimap` with a copy of another `multimap`.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -The ( **key**, **value**) pairs are stored in a multimap as objects of type `pair`. The pair class requires the header \, which is automatically included by \. +The ( **key**, **value**) pairs are stored in a `multimap` as objects of type `pair`. The pair class requires the header ``, which is automatically included by ``. -## multimap::allocator_type +## `multimap::allocator_type` -A type that represents the allocator class for the multimap object. +A type that represents the allocator class for the `multimap` object. ```cpp typedef Allocator allocator_type; @@ -142,11 +142,11 @@ typedef Allocator allocator_type; ### Example -See the example for [get_allocator](#get_allocator) for an example using `allocator_type`. +See the example for [`get_allocator`](#get_allocator) for an example using `allocator_type`. -## multimap::begin +## `multimap::begin` -Returns an iterator addressing the first element in the multimap. +Returns an iterator addressing the first element in the `multimap`. ```cpp const_iterator begin() const; @@ -156,7 +156,7 @@ iterator begin(); ### Return Value -A bidirectional iterator addressing the first element in the multimap or the location succeeding an empty multimap. +A bidirectional iterator addressing the first element in the `multimap` or the location succeeding an empty `multimap`. ### Example @@ -199,7 +199,7 @@ The first element of m1 is 0 First element of m1 is now 1 ``` -## multimap::cbegin +## `multimap::cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -215,7 +215,7 @@ A **`const`** bidirectional-access iterator that points at the first element of With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -225,7 +225,7 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## multimap::cend +## `multimap::cend` Returns a **`const`** iterator that addresses the location just beyond the last element in a range. @@ -241,7 +241,7 @@ A **`const`** bidirectional-access iterator that points just beyond the end of t `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -253,9 +253,9 @@ auto i2 = Container.cend(); The value returned by `cend` shouldn't be dereferenced. -## multimap::clear +## `multimap::clear` -Erases all the elements of a multimap. +Erases all the elements of a `multimap`. ```cpp void clear(); @@ -263,7 +263,7 @@ void clear(); ### Example -The following example demonstrates the use of the multimap::clear member function. +The following example demonstrates the use of the `multimap::clear` member function. ```cpp // multimap_clear.cpp @@ -297,9 +297,9 @@ The size of the multimap is initially 2. The size of the multimap after clearing is 0. ``` -## multimap::const_iterator +## `multimap::const_iterator` -A type that provides a bidirectional iterator that can read a **`const`** element in the multimap. +A type that provides a bidirectional iterator that can read a **`const`** element in the `multimap`. ```cpp typedef implementation-defined const_iterator; @@ -309,19 +309,19 @@ typedef implementation-defined const_iterator; A type `const_iterator` can't be used to modify the value of an element. -The `const_iterator` defined by multimap points to objects of [value_type](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. +The `const_iterator` defined by `multimap` points to objects of [`value_type`](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. -To dereference a `const_iterator` *cIter* pointing to an element in a multimap, use the **->** operator. +To dereference a `const_iterator` *`cIter`* pointing to an element in a `multimap`, use the **`->`** operator. To access the value of the key for the element, use `cIter->first`, which is equivalent to `(*cIter).first`. To access the value of the mapped datum for the element, use `cIter->second`, which is equivalent to `(*cIter).second`. ### Example -See the example for [begin](#begin) for an example using `const_iterator`. +See the example for [`begin`](#begin) for an example using `const_iterator`. -## multimap::const_pointer +## `multimap::const_pointer` -A type that provides a pointer to a **`const`** element in a multimap. +A type that provides a pointer to a **`const`** element in a `multimap`. ```cpp typedef typename allocator_type::const_pointer const_pointer; @@ -331,11 +331,11 @@ typedef typename allocator_type::const_pointer const_pointer; A type `const_pointer` can't be used to modify the value of an element. -In most cases, an [iterator](#iterator) should be used to access the elements in a multimap object. +In most cases, an [`iterator`](#iterator) should be used to access the elements in a `multimap` object. -## multimap::const_reference +## `multimap::const_reference` -A type that provides a reference to a **`const`** element stored in a multimap for reading and performing **`const`** operations. +A type that provides a reference to a **`const`** element stored in a `multimap` for reading and performing **`const`** operations. ```cpp typedef typename allocator_type::const_reference const_reference; @@ -383,9 +383,9 @@ The key of the first element in the multimap is 1. The data value of the first element in the multimap is 10. ``` -## multimap::const_reverse_iterator +## `multimap::const_reverse_iterator` -A type that provides a bidirectional iterator that can read any **`const`** element in the multimap. +A type that provides a bidirectional iterator that can read any **`const`** element in the `multimap`. ```cpp typedef std::reverse_iterator const_reverse_iterator; @@ -393,19 +393,19 @@ typedef std::reverse_iterator const_reverse_iterator; ### Remarks -A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the multimap in reverse. +A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the `multimap` in reverse. -The `const_reverse_iterator` defined by multimap points to objects of [value_type](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. +The `const_reverse_iterator` defined by `multimap` points to objects of [`value_type`](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. -To dereference a `const_reverse_iterator` *crIter* pointing to an element in a multimap, use the **->** operator. +To dereference a `const_reverse_iterator` *`crIter`* pointing to an element in a multimap, use the **`->`** operator. To access the value of the key for the element, use `crIter->first`, which is equivalent to `(*crIter).first`. To access the value of the mapped datum for the element, use `crIter->second`, which is equivalent to `(*crIter).first`. ### Example -See the example for [rend](#rend) for an example of how to declare and use `const_reverse_iterator`. +See the example for [`rend`](#rend) for an example of how to declare and use `const_reverse_iterator`. -## multimap::contains +## `multimap::contains` Check if there is an element with the specified key in the `multimap`. @@ -416,10 +416,10 @@ template bool contains(const K& key) const; ### Parameters -*K*\ +*`K`*\ The type of the key. -*key*\ +*`key`*\ The element's key value to look for. ### Return Value @@ -428,9 +428,9 @@ The element's key value to look for. ### Remarks -`contains()` is new in C++20. To use it, specify the [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later compiler option. +`contains()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](./stl-containers.md#heterogeneous-lookup-in-associative-containers-c14) for more information. +`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ### Example @@ -463,9 +463,9 @@ false true ``` -## multimap::count +## `multimap::count` -Returns the number of elements in a multimap whose keys match a parameter-specified key. +Returns the number of elements in a `multimap` whose keys match a parameter-specified key. ```cpp size_type count(const Key& key) const; @@ -473,7 +473,7 @@ size_type count(const Key& key) const; ### Parameters -*key*\ +*`key`*\ The key of the elements to be matched from the multimap. ### Return Value @@ -484,9 +484,9 @@ The number of elements whose sort keys match the parameter key; 0 if the multima The member function returns the number of elements in the range -\[ lower_bound(*key*), upper_bound(*key*) ) +[`lower_bound(key)`](#lower_bound), [`upper_bound(key)`](#upper_bound) -that have a key value *key*. +that have a key value *`key`*. ### Example @@ -532,9 +532,9 @@ The number of elements in m1 with a sort key of 2 is: 2. The number of elements in m1 with a sort key of 3 is: 0. ``` -## multimap::crbegin +## `multimap::crbegin` -Returns a const iterator addressing the first element in a reversed multimap. +Returns a `const` iterator addressing the first element in a reversed `multimap`. ```cpp const_reverse_iterator crbegin() const; @@ -542,11 +542,11 @@ const_reverse_iterator crbegin() const; ### Return Value -A const reverse bidirectional iterator addressing the first element in a reversed [multimap](../standard-library/multimap-class.md) or addressing what had been the last element in the unreversed `multimap`. +A `const` reverse bidirectional iterator addressing the first element in a reversed [`multimap`](../standard-library/multimap-class.md) or addressing what had been the last element in the unreversed `multimap`. ### Remarks -`crbegin` is used with a reversed `multimap` just as [begin](#begin) is used with a `multimap`. +`crbegin` is used with a reversed `multimap` just as [`begin`](#begin) is used with a `multimap`. With the return value of `crbegin`, the `multimap` object can't be modified. @@ -582,9 +582,9 @@ int main( ) The first element of the reversed multimap m1 is 3. ``` -## multimap::crend +## `multimap::crend` -Returns a const iterator that addresses the location succeeding the last element in a reversed multimap. +Returns a `const` iterator that addresses the location succeeding the last element in a reversed `multimap`. ```cpp const_reverse_iterator crend() const; @@ -592,11 +592,11 @@ const_reverse_iterator crend() const; ### Return Value -A const reverse bidirectional iterator that addresses the location succeeding the last element in a reversed [multimap](../standard-library/multimap-class.md) (the location that had preceded the first element in the unreversed `multimap`). +A `const` reverse bidirectional iterator that addresses the location succeeding the last element in a reversed [`multimap`](../standard-library/multimap-class.md) (the location that had preceded the first element in the unreversed `multimap`). ### Remarks -`crend` is used with a reversed `multimap` just as [multimap::end](#end) is used with a `multimap`. +`crend` is used with a reversed `multimap` just as [`multimap::end`](#end) is used with a `multimap`. With the return value of `crend`, the `multimap` object can't be modified. @@ -635,9 +635,9 @@ int main( ) The last element of the reversed multimap m1 is 1. ``` -## multimap::difference_type +## `multimap::difference_type` -A signed integer type that can be used to represent the number of elements of a multimap in a range between elements pointed to by iterators. +A signed integer type that can be used to represent the number of elements of a `multimap` in a range between elements pointed to by iterators. ```cpp typedef typename allocator_type::difference_type difference_type; @@ -645,7 +645,7 @@ typedef typename allocator_type::difference_type difference_type; ### Remarks -The `difference_type` is the type returned when subtracting or incrementing through iterators of the container. The `difference_type` is typically used to represent the number of elements in the range [*first*, *last*) between the iterators `first` and `last`, includes the element pointed to by `first` and the range of elements up to, but not including, the element pointed to by `last`. +The `difference_type` is the type returned when subtracting or incrementing through iterators of the container. The `difference_type` is typically used to represent the number of elements in the range [*`first`*, *`last`*) between the iterators `first` and `last`, includes the element pointed to by `first` and the range of elements up to, but not including, the element pointed to by `last`. Although `difference_type` is available for all iterators that satisfy the requirements of an input iterator, which includes the class of bidirectional iterators supported by reversible containers such as set, subtraction between iterators is only supported by random-access iterators provided by a random-access container such as vector. @@ -693,7 +693,7 @@ int main( ) The number of elements in the multimap m1 is: 4. ``` -## multimap::emplace +## `multimap::emplace` Inserts an element constructed in place (no copy or move operations are performed). @@ -704,8 +704,8 @@ iterator emplace(Args&&... args); ### Parameters -*args*\ -The arguments forwarded to construct an element to be inserted into the multimap. +*`args`*\ +The arguments forwarded to construct an element to be inserted into the `multimap`. ### Return Value @@ -717,7 +717,7 @@ No references to container elements are invalidated by this function, but it may If an exception is thrown during the insertion, the container is left unaltered and the exception is rethrown. -The [value_type](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. +The [`value_type`](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. ### Example @@ -760,7 +760,7 @@ int main() } ``` -## multimap::emplace_hint +## `multimap::emplace_hint` Inserts an element constructed in place (no copy or move operations are performed), with a placement hint. @@ -773,11 +773,11 @@ iterator emplace_hint( ### Parameters -*args*\ -The arguments forwarded to construct an element to be inserted into the multimap. +*`args`*\ +The arguments forwarded to construct an element to be inserted into the `multimap`. -*where*\ -The place to start searching for the correct point of insertion. (If that point immediately precedes *where*, insertion can occur in amortized constant time instead of logarithmic time.) +*`where`*\ +The place to start searching for the correct point of insertion. (If that point immediately precedes *`where`*, insertion can occur in amortized constant time instead of logarithmic time.) ### Return Value @@ -789,13 +789,13 @@ No references to container elements are invalidated by this function, but it may During emplacement, if an exception is thrown, the container's state is not modified. -The [value_type](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. +The [`value_type`](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. -For a code example, see [map::emplace_hint](../standard-library/map-class.md#emplace_hint). +For a code example, see [`map::emplace_hint`](../standard-library/map-class.md#emplace_hint). -## multimap::empty +## `multimap::empty` -Tests if a multimap is empty. +Tests if a `multimap` is empty. ```cpp bool empty() const; @@ -803,7 +803,7 @@ bool empty() const; ### Return Value -**`true`** if the multimap is empty; **`false`** if the multimap is nonempty. +**`true`** if the `multimap` is empty; **`false`** if the `multimap` is nonempty. ### Example @@ -838,7 +838,7 @@ The multimap m1 is not empty. The multimap m2 is empty. ``` -## multimap::end +## `multimap::end` Returns the past-the-end iterator. @@ -850,17 +850,17 @@ iterator end(); ### Return Value -The past-the-end iterator. If the multimap is empty, then `multimap::end() == multimap::begin()`. +The past-the-end iterator. If the `multimap` is empty, then `multimap::end() == multimap::begin()`. ### Remarks -**end** is used to test whether an iterator has passed the end of its multimap. +**`end`** is used to test whether an iterator has passed the end of its `multimap`. -The value returned by **end** shouldn't be dereferenced. +The value returned by **`end`** shouldn't be dereferenced. -For a code example, see [multimap::find](#find). +For a code example, see [`multimap::find`](#find). -## multimap::equal_range +## `multimap::equal_range` Finds the range of elements where the key of the element matches a specified value. @@ -872,14 +872,14 @@ pair equal_range (const Key& key); ### Parameters -*key*\ -The argument key to be compared with the sort key of an element from the multimap being searched. +*`key`*\ +The argument key to be compared with the sort key of an element from the `multimap` being searched. ### Return Value -A pair of iterators such that the first is the [lower_bound](#lower_bound) of the key and the second is the [upper_bound](#upper_bound) of the key. +A pair of iterators such that the first is the [`lower_bound`](#lower_bound) of the key and the second is the [`upper_bound`](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first** and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second** and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr.first` and to dereference the lower bound iterator, use `*(pr.first)`. To access the second iterator of a pair `pr` returned by the member function, use `pr.second` and to dereference the upper bound iterator, use `*(pr.second)`. ### Example @@ -941,9 +941,9 @@ matching the 2nd element of the pair returned by equal_range( 2 ). The multimap m1 doesn't have an element with a key less than 4. ``` -## multimap::erase +## `multimap::erase` -Removes an element or a range of elements in a multimap from specified positions or removes elements that match a specified key. +Removes an element or a range of elements in a `multimap` from specified positions or removes elements that match a specified key. ```cpp iterator erase( @@ -959,31 +959,31 @@ size_type erase( ### Parameters -*Where*\ +*`Where`*\ Position of the element to be removed. -*First*\ +*`First`*\ Position of the first element to be removed. -*Last*\ +*`Last`*\ Position just beyond the last element to be removed. -*Key*\ +*`Key`*\ The key of the elements to be removed. ### Return Value For the first two member functions, a bidirectional iterator that designates the first element remaining beyond any elements removed, or an element that is the end of the map if no such element exists. -For the third member function, returns the number of elements that have been removed from the multimap. +For the third member function, returns the number of elements that have been removed from the `multimap`. ### Remarks -For a code example, see [map::erase](../standard-library/map-class.md#erase). +For a code example, see [`map::erase`](../standard-library/map-class.md#erase). -## multimap::find +## `multimap::find` -Returns an iterator that refers to the first location of an element in a multimap that has a key equivalent to a specified key. +Returns an iterator that refers to the first location of an element in a `multimap` that has a key equivalent to a specified key. ```cpp iterator find(const Key& key); @@ -993,18 +993,18 @@ const_iterator find(const Key& key) const; ### Parameters -*key*\ -The key value to be matched by the sort key of an element from the multimap being searched. +*`key`*\ +The key value to be matched by the sort key of an element from the `multimap` being searched. ### Return Value -An iterator that refers to the location of an element with a specified key, or the location succeeding the last element in the multimap (`multimap::end()`) if no match is found for the key. +An iterator that refers to the location of an element with a specified key, or the location succeeding the last element in the `multimap` (`multimap::end()`) if no match is found for the key. ### Remarks -The member function returns an iterator that refers to an element in the multimap whose sort key is equivalent to the argument key under a binary predicate that induces an ordering based on a less than comparability relation. +The member function returns an iterator that refers to an element in the `multimap` whose sort key is equivalent to the argument key under a binary predicate that induces an ordering based on a less than comparability relation. -If the return value of `find` is assigned to a `const_iterator`, the multimap object can't be modified. If the return value of `find` is assigned to an `iterator`, the multimap object can be modified. +If the return value of `find` is assigned to a `const_iterator`, the `multimap` object can't be modified. If the return value of `find` is assigned to an `iterator`, the `multimap` object can be modified. ### Example @@ -1068,9 +1068,9 @@ int main() } ``` -## multimap::get_allocator +## `multimap::get_allocator` -Returns a copy of the allocator object used to construct the multimap. +Returns a copy of the allocator object used to construct the `multimap`. ```cpp allocator_type get_allocator() const; @@ -1078,11 +1078,11 @@ allocator_type get_allocator() const; ### Return Value -The allocator used by the multimap. +The allocator used by the `multimap`. ### Remarks -Allocators for the multimap class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. +Allocators for the `multimap` class specify how the class manages storage. The default allocators supplied with C++ Standard Library container classes are sufficient for most programming needs. Writing and using your own allocator class is an advanced C++ topic. ### Example @@ -1140,9 +1140,9 @@ int main( ) } ``` -## multimap::insert +## `multimap::insert` -Inserts an element or a range of elements into a multimap. +Inserts an element or a range of elements into a `multimap`. ```cpp // (1) single element @@ -1180,32 +1180,32 @@ IList); ### Parameters -*Val*\ -The value of an element to be inserted into the multimap. +*`Val`*\ +The value of an element to be inserted into the `multimap`. -*Where*\ -The place to start searching for the correct point of insertion. (If that point immediately precedes *Where*, insertion can occur in amortized constant time instead of logarithmic time.) +*`Where`*\ +The place to start searching for the correct point of insertion. (If that point immediately precedes *`Where`*, insertion can occur in amortized constant time instead of logarithmic time.) -*ValTy*\ -Template parameter that specifies the argument type that the map can use to construct an element of [value_type](../standard-library/map-class.md#value_type), and perfect-forwards *Val* as an argument. +*`ValTy`*\ +Template parameter that specifies the argument type that the map can use to construct an element of [`value_type`](../standard-library/map-class.md#value_type), and perfect-forwards *`Val`* as an argument. -*First*\ +*`First`*\ The position of the first element to be copied. -*Last*\ +*`Last`*\ The position just beyond the last element to be copied. -*InputIterator*\ -Template function argument that meets the requirements of an [input iterator](../standard-library/input-iterator-tag-struct.md) that points to elements of a type that can be used to construct [value_type](../standard-library/map-class.md#value_type) objects. +*`InputIterator`*\ +Template function argument that meets the requirements of an [`input` iterator](../standard-library/input-iterator-tag-struct.md) that points to elements of a type that can be used to construct [`value_type`](../standard-library/map-class.md#value_type) objects. -*IList*\ -The [initializer_list](../standard-library/initializer-list.md) from which to copy the elements. +*`IList`*\ +The [`initializer_list`](../standard-library/initializer-list.md) from which to copy the elements. ### Return Value -The single-element-insert member functions, (1) and (2), return an iterator to the position where the new element was inserted into the multimap. +The single-element-insert member functions, (1) and (2), return an iterator to the position where the new element was inserted into the `multimap`. -The single-element-with-hint member functions, (3) and (4), return an iterator that points to the position where the new element was inserted into the multimap. +The single-element-with-hint member functions, (3) and (4), return an iterator that points to the position where the new element was inserted into the `multimap`. ### Remarks @@ -1213,13 +1213,13 @@ No pointers or references are invalidated by this function, but it may invalidat During the insertion of just one element, if an exception is thrown, the container's state is not modified. During the insertion of multiple elements, if an exception is thrown, the container is left in an unspecified but valid state. -The [value_type](../standard-library/map-class.md#value_type) of a container is a typedef that belongs to the container, and for map, `multimap::value_type` is `pair`. The value of an element is an ordered pair in which the first component is equal to the key value and the second component is equal to the data value of the element. +The [`value_type`](../standard-library/map-class.md#value_type) of a container is a typedef that belongs to the container, and for map, `multimap::value_type` is `pair`. The value of an element is an ordered pair in which the first component is equal to the key value and the second component is equal to the data value of the element. -The range member function (5) inserts the sequence of element values into a multimap that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, *Last* doesn't get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `m.insert(v.begin(), v.end());` inserts all elements of `v` into `m`. +The range member function (5) inserts the sequence of element values into a `multimap` that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, *`Last`* doesn't get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `m.insert(v.begin(), v.end());` inserts all elements of `v` into `m`. -The initializer list member function (6) uses an [initializer_list](../standard-library/initializer-list.md) to copy elements into the map. +The initializer list member function (6) uses an [`initializer_list`](../standard-library/initializer-list.md) to copy elements into the map. -For insertion of an element constructed in place—that is, no copy or move operations are performed—see [multimap::emplace](#emplace) and [multimap::emplace_hint](#emplace_hint). +For insertion of an element constructed in place—that is, no copy or move operations are performed—see [`multimap::emplace`](#emplace) and [`multimap::emplace_hint`](#emplace_hint). ### Example @@ -1246,7 +1246,6 @@ template void print(const M& m) { int main() { - // insert single values multimap m1; // call insert(const value_type&) version @@ -1311,9 +1310,9 @@ int main() } ``` -## multimap::iterator +## `multimap::iterator` -A type that provides a bidirectional iterator that can read or modify any element in a multimap. +A type that provides a bidirectional iterator that can read or modify any element in a `multimap`. ```cpp typedef implementation-defined iterator; @@ -1321,9 +1320,9 @@ typedef implementation-defined iterator; ### Remarks -The `iterator` defined by multimap points to objects of [value_type](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. +The `iterator` defined by `multimap` points to objects of [`value_type`](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. -To dereference an `iterator` *Iter* pointing to an element in a multimap, use the **->** operator. +To dereference an `iterator` *`Iter`* pointing to an element in a `multimap`, use the **`->`** operator. To access the value of the key for the element, use `Iter->first`, which is equivalent to `(*Iter).first`. To access the value of the mapped datum for the element, use `Iter->second`, which is equivalent to `(*Iter).second`. @@ -1331,11 +1330,11 @@ A type `iterator` can be used to modify the value of an element. ### Example -See the example for [begin](#begin) for an example of how to declare and use `iterator`. +See the example for [`begin`](#begin) for an example of how to declare and use `iterator`. -## multimap::key_comp +## `multimap::key_comp` -Retrieves a copy of the comparison object used to order keys in a multimap. +Retrieves a copy of the comparison object used to order keys in a `multimap`. ```cpp key_compare key_comp() const; @@ -1343,7 +1342,7 @@ key_compare key_comp() const; ### Return Value -Returns the function object that a multimap uses to order its elements. +Returns the function object that a `multimap` uses to order its elements. ### Remarks @@ -1351,7 +1350,7 @@ The stored object defines the member function `bool operator( const Key& x, const Key& y);` -which returns true if *x* strictly precedes *y* in the sort order. +which returns true if *`x`* strictly precedes *`y`* in the sort order. ### Example @@ -1404,9 +1403,9 @@ kc1( 2,3 ) returns value of true, where kc1 is the function object of m1. kc2( 2,3 ) returns value of false, where kc2 is the function object of m2. ``` -## multimap::key_compare +## `multimap::key_compare` -A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the multimap. +A type that provides a function object that can compare two sort keys to determine the relative order of two elements in the `multimap`. ```cpp typedef Traits key_compare; @@ -1416,15 +1415,15 @@ typedef Traits key_compare; `key_compare` is a synonym for the template parameter `Traits`. -For more information on `Traits`, see the [multimap Class](../standard-library/multimap-class.md) topic. +For more information on `Traits`, see the [`multimap` Class](../standard-library/multimap-class.md) topic. ### Example -See the example for [key_comp](#key_comp) for an example of how to declare and use `key_compare`. +See the example for [`key_comp`](#key_comp) for an example of how to declare and use `key_compare`. -## multimap::key_type +## `multimap::key_type` -A type that describes the sort key object that constitutes each element of the multimap. +A type that describes the sort key object that constitutes each element of the `multimap`. ```cpp typedef Key key_type; @@ -1434,15 +1433,15 @@ typedef Key key_type; `key_type` is a synonym for the template parameter `Key`. -For more information on `Key`, see the Remarks section of the [multimap Class](../standard-library/multimap-class.md) topic. +For more information on `Key`, see the Remarks section of the [`multimap` Class](../standard-library/multimap-class.md) topic. ### Example -See the example for [value_type](#value_type) for an example of how to declare and use `key_type`. +See the example for [`value_type`](#value_type) for an example of how to declare and use `key_type`. -## multimap::lower_bound +## `multimap::lower_bound` -Returns an iterator to the first element in a multimap that with a key that is equal to or greater than a specified key. +Returns an iterator to the first element in a `multimap` that with a key that is equal to or greater than a specified key. ```cpp iterator lower_bound(const Key& key); @@ -1452,14 +1451,14 @@ const_iterator lower_bound(const Key& key) const; ### Parameters -*key*\ -The argument key to be compared with the sort key of an element from the multimap being searched. +*`key`*\ +The argument key to be compared with the sort key of an element from the `multimap` being searched. ### Return Value -An iterator or `const_iterator` that addresses the location of an element in a multimap that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the multimap if no match is found for the key. +An iterator or `const_iterator` that addresses the location of an element in a `multimap` that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the `multimap` if no match is found for the key. -If the return value of `lower_bound` is assigned to a `const_iterator`, the multimap object can't be modified. If the return value of `lower_bound` is assigned to an **iterator**, the multimap object can be modified. +If the return value of `lower_bound` is assigned to a `const_iterator`, the `multimap` object can't be modified. If the return value of `lower_bound` is assigned to an **iterator**, the `multimap` object can be modified. ### Example @@ -1528,9 +1527,9 @@ that of the last element is: 20. This is not the last element of multimap m1. ``` -## multimap::mapped_type +## `multimap::mapped_type` -A type that represents the data type stored in a multimap. +A type that represents the data type stored in a `multimap`. ```cpp typedef Type mapped_type; @@ -1540,15 +1539,15 @@ typedef Type mapped_type; `mapped_type` is a synonym for the template parameter `Type`. -For more information on `Type`, see the [multimap Class](../standard-library/multimap-class.md) topic. +For more information on `Type`, see the [`multimap` Class](../standard-library/multimap-class.md) topic. ### Example -See the example for [value_type](#value_type) for an example of how to declare and use `key_type`. +See the example for [`value_type`](#value_type) for an example of how to declare and use `key_type`. -## multimap::max_size +## `multimap::max_size` -Returns the maximum length of the multimap. +Returns the maximum length of the `multimap`. ```cpp size_type max_size() const; @@ -1556,7 +1555,7 @@ size_type max_size() const; ### Return Value -The maximum possible length of the multimap. +The maximum possible length of the `multimap`. ### Example @@ -1578,9 +1577,9 @@ int main( ) } ``` -## multimap::multimap +## `multimap::multimap` -Constructs a multimap that is empty or that is a copy of all or part of some other multimap. +Constructs a `multimap` that is empty or that is a copy of all or part of some other `multimap`. ```cpp multimap(); @@ -1631,39 +1630,39 @@ multimap( ### Parameters -*Al*\ +*`Al`*\ The storage allocator class to be used for this multimap object, which defaults to Allocator. -*Comp*\ +*`Comp`*\ The comparison function of type `constTraits` used to order the elements in the map, which defaults to `Traits`. -*Right*\ +*`Right`*\ The map of which the constructed set is to be a copy. -*First*\ +*`First`*\ The position of the first element in the range of elements to be copied. -*Last*\ +*`Last`*\ The position of the first element beyond the range of elements to be copied. -*IList*\ +*`IList`*\ The initializer_list from which to copy the elements. ### Remarks -All constructors store a type of allocator object that manages memory storage for the multimap and that can later be returned by calling [get_allocator](#get_allocator). The allocator parameter is often omitted in the class declarations and preprocessing macros used to substitute alternative allocators. +All constructors store a type of allocator object that manages memory storage for the `multimap` and that can later be returned by calling [`get_allocator`](#get_allocator). The allocator parameter is often omitted in the class declarations and preprocessing macros used to substitute alternative allocators. -All constructors initialize their multimap. +All constructors initialize their `multimap`. -All constructors store a function object of type `Traits` that is used to establish an order among the keys of the multimap and that can later be returned by calling [key_comp](#key_comp). +All constructors store a function object of type `Traits` that is used to establish an order among the keys of the `multimap` and that can later be returned by calling [`key_comp`](#key_comp). -The first three constructors specify an empty initial multimap, the second specifying the type of comparison function (*Comp*) to be used in establishing the order of the elements and the third explicitly specifying the allocator type (*Al*) to be used. The key word **`explicit`** suppresses certain kinds of automatic type conversion. +The first three constructors specify an empty initial `multimap`, the second specifying the type of comparison function (*`Comp`*) to be used in establishing the order of the elements and the third explicitly specifying the allocator type (*`Al`*) to be used. The key word **`explicit`** suppresses certain kinds of automatic type conversion. -The fourth constructor specifies a copy of the multimap *Right*. +The fourth constructor specifies a copy of the `multimap` *`Right`*. -The fifth constructor specifies a copy of the multimap by moving *Right*. +The fifth constructor specifies a copy of the `multimap` by moving *Right*. -The 6th, 7th, and 8th constructors copy the members of an initializer_list. +The 6th, 7th, and 8th constructors copy the members of an `initializer_list`. The next three constructors copy the range `[First, Last)` of a map with increasing explicitness in specifying the type of comparison function of class `Traits` and allocator. @@ -1775,9 +1774,9 @@ int main() } ``` -## multimap::operator= +## `multimap::operator=` -Replaces the elements of a multimap with a copy of another multimap. +Replaces the elements of a `multimap` with a copy of another `multimap`. ```cpp multimap& operator=(const multimap& right); @@ -1787,12 +1786,12 @@ multimap& operator=(multimap&& right); ### Parameters -*right*\ -The [multimap](../standard-library/multimap-class.md) being copied into the `multimap`. +*`right`*\ +The [`multimap`](../standard-library/multimap-class.md) being copied into the `multimap`. ### Remarks -After erasing any existing elements in a `multimap`, `operator=` either copies or moves the contents of *right* into the `multimap`. +After erasing any existing elements in a `multimap`, `operator=` either copies or moves the contents of *`right`* into the `multimap`. ### Example @@ -1831,9 +1830,9 @@ int main( ) } ``` -## multimap::pointer +## `multimap::pointer` -A type that provides a pointer to an element in a multimap. +A type that provides a pointer to an element in a `multimap`. ```cpp typedef typename allocator_type::pointer pointer; @@ -1843,11 +1842,11 @@ typedef typename allocator_type::pointer pointer; A type `pointer` can be used to modify the value of an element. -In most cases, an [iterator](#iterator) should be used to access the elements in a multimap object. +In most cases, an [`iterator`](#iterator) should be used to access the elements in a `multimap` object. -## multimap::rbegin +## `multimap::rbegin` -Returns an iterator addressing the first element in a reversed multimap. +Returns an iterator addressing the first element in a reversed `multimap`. ```cpp const_reverse_iterator rbegin() const; @@ -1857,15 +1856,15 @@ reverse_iterator rbegin(); ### Return Value -A reverse bidirectional iterator addressing the first element in a reversed multimap or addressing what had been the last element in the unreversed multimap. +A reverse bidirectional iterator addressing the first element in a reversed `multimap` or addressing what had been the last element in the unreversed `multimap`. ### Remarks -`rbegin` is used with a reversed multimap just as [begin](#begin) is used with a multimap. +`rbegin` is used with a reversed `multimap` just as [`begin`](#begin) is used with a `multimap`. -If the return value of `rbegin` is assigned to a `const_reverse_iterator`, then the multimap object can't be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, then the multimap object can be modified. +If the return value of `rbegin` is assigned to a `const_reverse_iterator`, then the `multimap` object can't be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, then the `multimap` object can be modified. -`rbegin` can be used to iterate through a multimap backwards. +`rbegin` can be used to iterate through a `multimap` backwards. ### Example @@ -1925,9 +1924,9 @@ The reversed multimap is: 3 2 1 . After the erasure, the first element in the reversed multimap is 2. ``` -## multimap::reference +## `multimap::reference` -A type that provides a reference to an element stored in a multimap. +A type that provides a reference to an element stored in a `multimap`. ```cpp typedef typename allocator_type::reference reference; @@ -1982,9 +1981,9 @@ The data value of first element in the multimap is 10. The modified data value of first element is 15. ``` -## multimap::rend +## `multimap::rend` -Returns an iterator that addresses the location succeeding the last element in a reversed multimap. +Returns an iterator that addresses the location succeeding the last element in a reversed `multimap`. ```cpp const_reverse_iterator rend() const; @@ -1994,15 +1993,15 @@ reverse_iterator rend(); ### Return Value -A reverse bidirectional iterator that addresses the location succeeding the last element in a reversed multimap (the location that had preceded the first element in the unreversed multimap). +A reverse bidirectional iterator that addresses the location succeeding the last element in a reversed `multimap` (the location that had preceded the first element in the unreversed `multimap`). ### Remarks -`rend` is used with a reversed multimap just as [end](../standard-library/map-class.md#end) is used with a multimap. +`rend` is used with a reversed `multimap` just as [`end`](../standard-library/map-class.md#end) is used with a `multimap`. -If the return value of `rend` is assigned to a `const_reverse_iterator`, then the multimap object can't be modified. If the return value of `rend` is assigned to a `reverse_iterator`, then the multimap object can be modified. +If the return value of `rend` is assigned to a `const_reverse_iterator`, then the `multimap` object can't be modified. If the return value of `rend` is assigned to a `reverse_iterator`, then the `multimap` object can be modified. -`rend` can be used to test to whether a reverse iterator has reached the end of its multimap. +`rend` can be used to test whether a reverse iterator has reached the end of its `multimap`. The value returned by `rend` shouldn't be dereferenced. @@ -2066,9 +2065,9 @@ The reversed multimap is: 3 2 1 . After the erasure, the last element in the reversed multimap is 2. ``` -## multimap::reverse_iterator +## `multimap::reverse_iterator` -A type that provides a bidirectional iterator that can read or modify an element in a reversed multimap. +A type that provides a bidirectional iterator that can read or modify an element in a reversed `multimap`. ```cpp typedef std::reverse_iterator reverse_iterator; @@ -2076,21 +2075,21 @@ typedef std::reverse_iterator reverse_iterator; ### Remarks -A type `reverse_iterator` is used to iterate through the multimap in reverse. +A type `reverse_iterator` is used to iterate through the `multimap` in reverse. -The `reverse_iterator` defined by multimap points to objects of [value_type](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. +The `reverse_iterator` defined by `multimap` points to objects of [`value_type`](#value_type), which are of type `pair`. The value of the key is available through the first member pair and the value of the mapped element is available through the second member of the pair. -To dereference a `reverse_iterator` *rIter* pointing to an element in a multimap, use the **->** operator. +To dereference a `reverse_iterator` *`rIter`* pointing to an element in a `multimap`, use the **`->`** operator. To access the value of the key for the element, use `rIter->first`, which is equivalent to `(*rIter).first`. To access the value of the mapped datum for the element, use `rIter->second`, which is equivalent to `(*rIter).second`. ### Example -See the example for [rbegin](#rbegin) for an example of how to declare and use `reverse_iterator`. +See the example for [`rbegin`](#rbegin) for an example of how to declare and use `reverse_iterator`. -## multimap::size +## `multimap::size` -Returns the number of elements in the multimap. +Returns the number of elements in the `multimap`. ```cpp size_type size() const; @@ -2098,11 +2097,11 @@ size_type size() const; ### Return Value -The current length of the multimap. +The current length of the `multimap`. ### Example -The following example demonstrates the use of the multimap::size member function. +The following example demonstrates the use of the `multimap::size` member function. ```cpp // multimap_size.cpp @@ -2132,9 +2131,9 @@ The multimap length is 1. The multimap length is now 2. ``` -## multimap::size_type +## `multimap::size_type` -An unsigned integer type that counts the number of elements in a multimap. +An unsigned integer type that counts the number of elements in a `multimap`. ```cpp typedef typename allocator_type::size_type size_type; @@ -2142,11 +2141,11 @@ typedef typename allocator_type::size_type size_type; ### Example -See the example for [size](#size) for an example of how to declare and use `size_type` +See the example for [`size`](#size) for an example of how to declare and use `size_type` -## multimap::swap +## `multimap::swap` -Exchanges the elements of two multimaps. +Exchanges the elements of two `multimap`s. ```cpp void swap( @@ -2155,12 +2154,12 @@ void swap( ### Parameters -*right*\ -The multimap providing the elements to be swapped, or the multimap whose elements are to be exchanged with those of the multimap `left`. +*`right`*\ +The `multimap` providing the elements to be swapped, or the `multimap` whose elements are to be exchanged with those of the `multimap` `left`. ### Remarks -The member function invalidates no references, pointers, or iterators that designate elements in the two multimaps whose elements are being exchanged. +The member function invalidates no references, pointers, or iterators that designate elements in the two `multimap`s whose elements are being exchanged. ### Example @@ -2213,9 +2212,9 @@ After swapping with m2, multimap m1 is: 100 200. After swapping with m3, multimap m1 is: 300. ``` -## multimap::upper_bound +## `multimap::upper_bound` -Returns an iterator to the first element in a multimap that with a key that is greater than a specified key. +Returns an `iterator` to the first element in a `multimap` that with a key that is greater than a specified key. ```cpp iterator upper_bound(const Key& key); @@ -2225,14 +2224,14 @@ const_iterator upper_bound(const Key& key) const; ### Parameters -*key*\ -The argument key to be compared with the sort key of an element from the multimap being searched. +*`key`*\ +The argument key to be compared with the sort key of an element from the `multimap` being searched. ### Return Value -An iterator or `const_iterator` that addresses the location of an element in a multimap that with a key that is greater than the argument key, or that addresses the location succeeding the last element in the multimap if no match is found for the key. +An `iterator` or `const_iterator` that addresses the location of an element in a `multimap` that with a key that is greater than the argument key, or that addresses the location succeeding the last element in the `multimap` if no match is found for the key. -If the return value is assigned to a `const_iterator`, the multimap object can't be modified. If the return value is assigned to a `iterator`, the multimap object can be modified. +If the return value is assigned to a `const_iterator`, the `multimap` object can't be modified. If the return value is assigned to a `iterator`, the `multimap` object can be modified. ### Example @@ -2292,9 +2291,9 @@ The first element of m1 with a key greater than that of the initial element of m1 is: 20. ``` -## multimap::value_comp +## `multimap::value_comp` -The member function returns a function object that determines the order of elements in a multimap by comparing their key values. +The member function returns a function object that determines the order of elements in a `multimap` by comparing their key values. ```cpp value_compare value_comp() const; @@ -2302,11 +2301,11 @@ value_compare value_comp() const; ### Return Value -Returns the comparison function object that a multimap uses to order its elements. +Returns the comparison function object that a `multimap` uses to order its elements. ### Remarks -For a multimap *m*, if two elements *e1*(*k1*, *d1*) and *e2*(*k2*, *d2*) are objects of type `value_type`, where *k1* and *k2* are their keys of type `key_type` and *d1* and *d2* are their data of type `mapped_type`, then `m.value_comp(e1, e2)` is equivalent to `m.key_comp(k1, k2)`. +For a `multimap` *`m`*, if two elements `e1(k1, d1)` and `e2(k2, d2)` are objects of type `value_type`, where *`k1`* and *`k2`* are their keys of type `key_type` and *`d1`* and *`d2`* are their data of type `mapped_type`, then `m.value_comp(e1, e2)` is equivalent to `m.key_comp(k1, k2)`. ### Example @@ -2358,7 +2357,7 @@ The element ( 1,10 ) precedes the element ( 2,5 ). The element ( 2,5 ) does not precede the element ( 1,10 ). ``` -## multimap::value_type +## `multimap::value_type` A type that represents the type of object stored as an element in a map. diff --git a/docs/standard-library/multiplies-struct.md b/docs/standard-library/multiplies-struct.md index cb110701b8..927e7f2403 100644 --- a/docs/standard-library/multiplies-struct.md +++ b/docs/standard-library/multiplies-struct.md @@ -12,7 +12,7 @@ A predefined function object that performs the multiplication operation (binary ## Syntax -``` +```cpp template struct multiplies : public binary_function { @@ -24,7 +24,7 @@ template <> struct multiplies { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) * std::forward(Right)); }; ``` diff --git a/docs/standard-library/multiset-class.md b/docs/standard-library/multiset-class.md index 36de619fe1..0fbaa07850 100644 --- a/docs/standard-library/multiset-class.md +++ b/docs/standard-library/multiset-class.md @@ -1,7 +1,7 @@ --- title: "multiset Class" description: "API reference for the C++ Standard Template Library (STL) `multiset` class, which is used for the storage and retrieval of data from a collection in which the values of the elements contained need not be unique and in which they serve as the key values according to which the data is automatically ordered." -ms.date: "9/9/2020" +ms.date: 9/9/2020 f1_keywords: ["set/std::multiset", "set/std::multiset::allocator_type", "set/std::multiset::const_iterator", "set/std::multiset::const_pointer", "set/std::multiset::const_reference", "set/std::multiset::const_reverse_iterator", "set/std::multiset::difference_type", "set/std::multiset::iterator", "set/std::multiset::key_compare", "set/std::multiset::key_type", "set/std::multiset::pointer", "set/std::multiset::reference", "set/std::multiset::reverse_iterator", "set/std::multiset::size_type", "set/std::multiset::value_compare", "set/std::multiset::value_type", "set/std::multiset::begin", "set/std::multiset::cbegin", "set/std::multiset::cend", "set/std::multiset::clear", "set/std::multiset::contains", "set/std::multiset::count", "set/std::multiset::crbegin", "set/std::multiset::crend", "set/std::multiset::emplace", "set/std::multiset::emplace_hint", "set/std::multiset::empty", "set/std::multiset::end", "set/std::multiset::equal_range", "set/std::multiset::erase", "set/std::multiset::find", "set/std::multiset::get_allocator", "set/std::multiset::insert", "set/std::multiset::key_comp", "set/std::multiset::lower_bound", "set/std::multiset::max_size", "set/std::multiset::rbegin", "set/std::multiset::rend", "set/std::multiset::size", "set/std::multiset::swap", "set/std::multiset::upper_bound", "set/std::multiset::value_comp"] helpviewer_keywords: ["std::multiset [C++]", "std::multiset [C++], allocator_type", "std::multiset [C++], const_iterator", "std::multiset [C++], const_pointer", "std::multiset [C++], const_reference", "std::multiset [C++], const_reverse_iterator", "std::multiset [C++], difference_type", "std::multiset [C++], iterator", "std::multiset [C++], key_compare", "std::multiset [C++], key_type", "std::multiset [C++], pointer", "std::multiset [C++], reference", "std::multiset [C++], reverse_iterator", "std::multiset [C++], size_type", "std::multiset [C++], value_compare", "std::multiset [C++], value_type", "std::multiset [C++], begin", "std::multiset [C++], cbegin", "std::multiset [C++], cend", "std::multiset [C++], clear", "std::multiset [C++], contains", "std::multiset [C++], count", "std::multiset [C++], crbegin", "std::multiset [C++], crend", "std::multiset [C++], emplace", "std::multiset [C++], emplace_hint", "std::multiset [C++], empty", "std::multiset [C++], end", "std::multiset [C++], equal_range", "std::multiset [C++], erase", "std::multiset [C++], find", "std::multiset [C++], get_allocator", "std::multiset [C++], insert", "std::multiset [C++], key_comp", "std::multiset [C++], lower_bound", "std::multiset [C++], max_size", "std::multiset [C++], rbegin", "std::multiset [C++], rend", "std::multiset [C++], size", "std::multiset [C++], swap", "std::multiset [C++], upper_bound", "std::multiset [C++], value_comp"] --- @@ -24,7 +24,7 @@ The element data type to be stored in the `multiset`. *`Compare`*\ The type that provides a function object that can compare two element values as sort keys to determine their relative order in the `multiset`. The binary predicate **less**\ is the default value. -In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the `multiset`'s allocation and deallocation of memory. The default value is `allocator`. @@ -53,7 +53,7 @@ The `multiset` should be the associative container of choice when the conditions The `multiset` orders the sequence it controls by calling a stored function object of type *`Compare`*. This stored object is a comparison function that may be accessed by calling the member function [`key_comp`](#key_comp). In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they're equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate *f*(*x*, *y*) is a function object that has two argument objects *x* and *y* and a return value of **`true`** or **`false`**. An ordering imposed on a set is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects x and y are defined to be equivalent when both *f*(*x,y*) and *f*(*y,x*) are false. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. -In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ### Constructors @@ -399,7 +399,7 @@ The element's key value to look for. `contains()` is new in C++20. To use it, specify the [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later compiler option. -`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](./stl-containers.md#heterogeneous-lookup-in-associative-containers-c14) for more information. +`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ### Example @@ -836,7 +836,7 @@ The argument key to be compared with the sort key of an element from the `multis A pair of iterators such that the first is the [`lower_bound`](#lower_bound) of the key and the second is the [`upper_bound`](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **`first`**, and to dereference the lower bound iterator, use \*( `pr`. **`first`**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **`second`**, and to dereference the upper bound iterator, use \*( `pr`. **`second`**). +To access the first iterator of a pair `pr` returned by the member function, use `pr`. **`first`**, and to dereference the lower bound iterator, use \*(`pr`. **`first`**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **`second`**, and to dereference the upper bound iterator, use \*(`pr`. **`second`**). ### Example @@ -953,7 +953,7 @@ The key value to be matched by the sort key of an element from the `multiset` be ### Return Value -An iterator that refers to the location of an element with a specified key, or the location succeeding the last element in the `multiset` ( `multiset::end()`) if no match is found for the key. +An iterator that refers to the location of an element with a specified key, or the location succeeding the last element in the `multiset`(`multiset::end()`) if no match is found for the key. ### Remarks @@ -1195,7 +1195,6 @@ template void print(const S& s) { int main() { - // insert single values multiset s1; // call insert(const value_type&) version @@ -1295,7 +1294,7 @@ The stored object defines the member function: which returns true if *x* strictly precedes *y* in the sort order. -Both [`key_compare`](#key_compare) and [`value_compare`](#value_compare) are synonyms for the template parameter ``Compare``. Both types are provided for the classes set and multiset, where they're identical, for compatibility with the classes map and multimap, where they're distinct. +Both [`key_compare`](#key_compare) and [`value_compare`](#value_compare) are synonyms for the template parameter `Compare`. Both types are provided for the classes set and multiset, where they're identical, for compatibility with the classes map and multimap, where they're distinct. ### Example @@ -1382,7 +1381,7 @@ For more information on `Key`, see the Remarks section of the [`multiset` Class] ### Example -See the example for [`value_type`](#value_type) for an example of how to declare and use ``key_type``. +See the example for [`value_type`](#value_type) for an example of how to declare and use `key_type`. ## `multiset::lower_bound` diff --git a/docs/standard-library/mutex-class-stl.md b/docs/standard-library/mutex-class-stl.md index f28baee7ec..aa07a6867d 100644 --- a/docs/standard-library/mutex-class-stl.md +++ b/docs/standard-library/mutex-class-stl.md @@ -1,6 +1,6 @@ --- description: "Learn more about: mutex Class (C++ Standard Library)" -title: "mutex Class (C++ Standard Library)| Microsoft Docs" +title: mutex Class (C++ Standard Library) ms.date: 10/22/2021 f1_keywords: ["mutex/std::mutex", "mutex/std::mutex::mutex", "mutex/std::mutex::lock", "mutex/std::mutex::native_handle", "mutex/std::mutex::try_lock", "mutex/std::mutex::unlock"] helpviewer_keywords: ["std::mutex [C++]", "std::mutex [C++], mutex", "std::mutex [C++], lock", "std::mutex [C++], native_handle", "std::mutex [C++], try_lock", "std::mutex [C++], unlock"] @@ -54,7 +54,7 @@ If the calling thread already owns the `mutex`, the behavior is undefined. ## Constructor Constructs a `mutex` object that isn't locked.\ -Microsoft's implementation of this constructor is not `constexpr`. +Before Visual Studio 2022 17.10, Microsoft's implementation of this constructor wasn't `constexpr`. Now it's `constexpr`. ```cpp mutex() noexcept; @@ -82,7 +82,7 @@ native_handle_type native_handle(); ### Return Value -`native_handle_type` is defined as a `Concurrency::critical_section *` that's cast as `void *`. +`native_handle_type` is defined as a `Concurrency::critical_section *`. It's cast as `void *`. ## `try_lock` diff --git a/docs/standard-library/mutex.md b/docs/standard-library/mutex.md index 785bc69c18..704a624610 100644 --- a/docs/standard-library/mutex.md +++ b/docs/standard-library/mutex.md @@ -3,27 +3,26 @@ description: "Learn more about: " title: "" ms.date: "11/04/2016" f1_keywords: [""] -ms.assetid: efb60c89-687a-4e38-8fe4-694e11c4e8a3 --- # `` -Include the standard header \ to define the classes `mutex`, `recursive_mutex`, `timed_mutex`, and `recursive_timed_mutex`; the templates `lock_guard` and `unique_lock`; and supporting types and functions that define mutual-exclusion code regions. +Include the standard header `` to define the classes `mutex`, `recursive_mutex`, `timed_mutex`, and `recursive_timed_mutex`; the templates `lock_guard` and `unique_lock`; and supporting types and functions that define mutual-exclusion code regions. > [!WARNING] -> Beginning in Visual Studio 2015, the C++ Standard Library synchronization types are based on Windows synchronization primitives and no longer use ConcRT (except when the target platform is Windows XP). The types defined in \ should not be used with any ConcRT types or functions. +> Beginning in Visual Studio 2015, the C++ Standard Library synchronization types are based on Windows synchronization primitives and no longer use ConcRT (except when the target platform is Windows XP). The types defined in `` should not be used with any ConcRT types or functions. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Remarks > [!NOTE] -> In code that is compiled by using **/clr**, this header is blocked. +> In code that is compiled by using **`/clr`**, this header is blocked. -The classes `mutex` and `recursive_mutex` are *mutex types*. A mutex type has a default constructor and a destructor that does not throw exceptions. These objects have methods that provide mutual exclusion when multiple threads try to lock the same object. Specifically, a mutex type contains the methods `lock`, `try_lock`, and `unlock`: +The classes `mutex` and `recursive_mutex` are *mutex types*. A mutex type has a default constructor and a destructor that doesn't throw exceptions. These objects have methods that provide mutual exclusion when multiple threads try to lock the same object. Specifically, a mutex type contains the methods `lock`, `try_lock`, and `unlock`: - The `lock` method blocks the calling thread until the thread obtains ownership of the mutex. Its return value is ignored. @@ -31,15 +30,15 @@ The classes `mutex` and `recursive_mutex` are *mutex types*. A mutex type has a - The `unlock` method releases the ownership of the mutex from the calling thread. -You can use mutex types as type arguments to instantiate the templates `lock_guard` and `unique_lock`. You can use objects of these types as the `Lock` argument to the wait member functions in the template [condition_variable_any](../standard-library/condition-variable-any-class.md). +You can use mutex types as type arguments to instantiate the templates `lock_guard` and `unique_lock`. You can use objects of these types as the `Lock` argument to the wait member functions in the template [`condition_variable_any`](../standard-library/condition-variable-any-class.md). A *timed mutex type* satisfies the requirements for a mutex type. In addition, it has the `try_lock_for` and `try_lock_until` methods that must be callable by using one argument and must return a type that is convertible to **`bool`**. A timed mutex type can define these functions by using additional arguments, provided that those additional arguments all have default values. -- The `try_lock_for` method must be callable by using one argument, `Rel_time`, whose type is an instantiation of [chrono::duration](../standard-library/duration-class.md). The method tries to obtain ownership of the mutex, but returns within the time that is designated by `Rel_time`, regardless of success. The return value converts to **`true`** if the method obtains ownership; otherwise, the return value converts to **`false`**. +- The `try_lock_for` method must be callable by using one argument, `Rel_time`, whose type is an instantiation of [`chrono::duration`](../standard-library/duration-class.md). The method tries to obtain ownership of the mutex, but returns within the time that is designated by `Rel_time`, regardless of success. The return value converts to **`true`** if the method obtains ownership; otherwise, the return value converts to **`false`**. -- The `try_lock_until` method must be callable by using one argument, `Abs_time`, whose type is an instantiation of [chrono::time_point](../standard-library/time-point-class.md). The method tries to obtain ownership of the mutex, but returns no later than the time that is designated by `Abs_time`, regardless of success. The return value converts to **`true`** if the method obtains ownership; otherwise, the return value converts to **`false`**. +- The `try_lock_until` method must be callable by using one argument, `Abs_time`, whose type is an instantiation of [`chrono::time_point`](../standard-library/time-point-class.md). The method tries to obtain ownership of the mutex, but returns no later than the time that is designated by `Abs_time`, regardless of success. The return value converts to **`true`** if the method obtains ownership; otherwise, the return value converts to **`false`**. -A mutex type is also known as a *lockable type*. If it does not provide the member function `try_lock`, it is a *basic lockable type*. A timed mutex type is also known as a *timed lockable type*. +A mutex type is also known as a *lockable type*. If it doesn't provide the member function `try_lock`, it's a *basic lockable type*. A timed mutex type is known as a *timed lockable type*. A *timed lockable type* blocks for a specified amount of time, or until a lock on the mutex is acquired. ## Members @@ -47,39 +46,39 @@ A mutex type is also known as a *lockable type*. If it does not provide the memb |Name|Description| |-|-| -|[lock_guard Class](../standard-library/lock-guard-class.md)|Represents a template that can be instantiated to create an object whose destructor unlocks a `mutex`.| -|[mutex Class (C++ Standard Library)](../standard-library/mutex-class-stl.md)|Represents a mutex type. Use objects of this type to enforce mutual exclusion within a program.| -|[recursive_mutex Class](../standard-library/recursive-mutex-class.md)|Represents a mutex type. In constrast to the `mutex` class, the behavior of calling locking methods for objects that are already locked is well-defined.| -|[recursive_timed_mutex Class](../standard-library/recursive-timed-mutex-class.md)|Represents a timed mutex type. Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program. Unlike objects of type `timed_mutex`, the effect of calling locking methods for `recursive_timed_mutex` objects is well-defined.| -|[scoped_lock Class](../standard-library/scoped-lock-class.md)|| -|[timed_mutex Class](../standard-library/timed-mutex-class.md)|Represents a timed mutex type. Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program.| -|[unique_lock Class](../standard-library/unique-lock-class.md)|Represents a template that can be instantiated to create objects that manage the locking and unlocking of a `mutex`.| +|[`lock_guard` Class](../standard-library/lock-guard-class.md)|Represents a template that can be instantiated to create an object whose destructor unlocks a mutex.| +|[`mutex` Class (C++ Standard Library)](../standard-library/mutex-class-stl.md)|Represents a mutex type. Use objects of this type to enforce mutual exclusion within a program.| +|[`recursive_mutex` Class](../standard-library/recursive-mutex-class.md)|Represents a mutex type. In contrast to the `mutex` class, the behavior of calling locking methods for objects that are already locked is well-defined.| +|[`recursive_timed_mutex` Class](../standard-library/recursive-timed-mutex-class.md)| Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program. Unlike `timed_mutex`, the effect of calling locking methods for `recursive_timed_mutex` objects is well-defined.| +|[`scoped_lock` Class](../standard-library/scoped-lock-class.md)|| +|[`timed_mutex` Class](../standard-library/timed-mutex-class.md)| Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program.| +|[`unique_lock` Class](../standard-library/unique-lock-class.md)|Represents a template that can be instantiated to create objects that manage the locking and unlocking of a mutex.| ### Functions |Name|Description| |-|-| -|[call_once](../standard-library/mutex-functions.md#call_once)|Provides a mechanism for calling a specified callable object exactly once during execution.| -|[lock](../standard-library/mutex-functions.md#lock)|Attempts to lock all arguments without deadlock.| -|[swap](../standard-library/mutex-functions.md#swap)|| -|[try_lock](../standard-library/mutex-functions.md#try_lock)|| +|[`call_once`](../standard-library/mutex-functions.md#call_once)|Provides a mechanism for calling a specified callable object exactly once during execution.| +|[`lock`](../standard-library/mutex-functions.md#lock)|Attempts to lock all arguments without deadlock.| +|[`swap`](../standard-library/mutex-functions.md#swap)|Tries to exchange the internal states of two `mutex` objects, `x` and `y`.| +|[`try_lock`](../standard-library/mutex-functions.md#try_lock)|Tries to lock the lockable object. Returns immediately.| ### Structs |Name|Description| |-|-| -|[adopt_lock_t Structure](../standard-library/adopt-lock-t-structure.md)|Represents a type that is used to define an `adopt_lock`.| -|[defer_lock_t Structure](../standard-library/defer-lock-t-structure.md)|Represents a type that defines a `defer_lock` object that is used to select one of the overloaded constructors of `unique_lock`.| -|[once_flag Structure](../standard-library/once-flag-structure.md)|Represents a **`struct`** that is used with the template function `call_once` to ensure that initialization code is called only once, even in the presence of multiple threads of execution.| -|[try_to_lock_t Structure](../standard-library/try-to-lock-t-structure.md)|Represents a **`struct`** that defines a `try_to_lock` object and is used to select one of the overloaded constructors of `unique_lock`.| +|[`adopt_lock_t` Structure](../standard-library/adopt-lock-t-structure.md)|Represents a type that is used to define an `adopt_lock`.| +|[`defer_lock_t` Structure](../standard-library/defer-lock-t-structure.md)|Represents a type that defines a `defer_lock` object that is used to select one of the overloaded constructors of `unique_lock`.| +|[`once_flag` Structure](../standard-library/once-flag-structure.md)|Represents a **`struct`** that is used with the template function `call_once` to ensure that initialization code is called only once, even in the presence of multiple threads of execution.| +|[`try_to_lock_t` Structure](../standard-library/try-to-lock-t-structure.md)|Represents a **`struct`** that defines a `try_to_lock` object and is used to select one of the overloaded constructors of `unique_lock`.| ### Variables |Name|Description| |-|-| -|[adopt_lock](../standard-library/mutex-functions.md#adopt_lock)|Represents an object that can be passed to constructors for `lock_guard` and `unique_lock` to indicate that the mutex object that is also being passed to the constructor is locked.| -|[defer_lock](../standard-library/mutex-functions.md#defer_lock)|Represents an object that can be passed to the constructor for `unique_lock`, to indicate that the constructor should not lock the mutex object that is also being passed to it.| -|[try_to_lock](../standard-library/mutex-functions.md#try_to_lock)|Represents an object that can be passed to the constructor for `unique_lock` to indicate that the constructor should try to unlock the `mutex` that is also being passed to it without blocking.| +|[`adopt_lock`](../standard-library/mutex-functions.md#adopt_lock)|Represents an object that can be passed to constructors for `lock_guard` and `unique_lock` to indicate that the `mutex` object that is also being passed to the constructor is locked.| +|[`defer_lock`](../standard-library/mutex-functions.md#defer_lock)|Represents an object that can be passed to the constructor for `unique_lock`, to indicate that the constructor shouldn't lock the `mutex` object that is also being passed to it.| +|[`try_to_lock`](../standard-library/mutex-functions.md#try_to_lock)|Represents an object that can be passed to the constructor for `unique_lock` to indicate that the constructor should try to unlock the `mutex` object that is also being passed to it without blocking.| ## See also diff --git a/docs/standard-library/negate-struct.md b/docs/standard-library/negate-struct.md index 3e8d9f950e..f0f71b2e53 100644 --- a/docs/standard-library/negate-struct.md +++ b/docs/standard-library/negate-struct.md @@ -12,7 +12,7 @@ A predefined function object that performs the arithmetic negation operation (un ## Syntax -``` +```cpp template struct negate : public unary_function { @@ -24,7 +24,7 @@ template <> struct negate { template - auto operator()(Type&& Left) const` + auto operator()(Type&& Left) const -> decltype(-std::forward(Left)); }; ``` diff --git a/docs/standard-library/negative-binomial-distribution-class.md b/docs/standard-library/negative-binomial-distribution-class.md index bc3cbae3a8..ce20bc942e 100644 --- a/docs/standard-library/negative-binomial-distribution-class.md +++ b/docs/standard-library/negative-binomial-distribution-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: negative_binomial_distribution Class" title: "negative_binomial_distribution Class" -ms.date: "11/04/2016" +description: "Learn more about: negative_binomial_distribution Class" +ms.date: 11/04/2016 f1_keywords: ["random/std::negative_binomial_distribution", "random/std::negative_binomial_distribution::reset", "random/std::negative_binomial_distribution::k", "random/std::negative_binomial_distribution::p", "random/std::negative_binomial_distribution::param", "random/std::negative_binomial_distribution::min", "random/std::negative_binomial_distribution::max", "random/std::negative_binomial_distribution::operator()", "random/std::negative_binomial_distribution::param_type", "random/std::negative_binomial_distribution::param_type::k", "random/std::negative_binomial_distribution::param_type::p", "random/std::negative_binomial_distribution::param_type::operator==", "random/std::negative_binomial_distribution::param_type::operator!="] helpviewer_keywords: ["std::negative_binomial_distribution [C++]", "std::negative_binomial_distribution [C++], reset", "std::negative_binomial_distribution [C++], k", "std::negative_binomial_distribution [C++], p", "std::negative_binomial_distribution [C++], param", "std::negative_binomial_distribution [C++], min", "std::negative_binomial_distribution [C++], max", "std::negative_binomial_distribution [C++], param_type", "std::negative_binomial_distribution [C++], param_type"] -ms.assetid: 7f5f0967-7fdd-4578-99d4-88f292b4fe9c --- # negative_binomial_distribution Class @@ -12,7 +11,7 @@ Generates a negative binomial distribution. ## Syntax -``` +```cpp template class negative_binomial_distribution { @@ -224,15 +223,18 @@ The second constructor constructs an object whose stored parameters are initiali Stores the parameters of the distribution. -struct param_type { - typedef negative_binomial_distribution`<`result_type> distribution_type; - param_type(result_type k = 1, double p = 0.5); - result_type k() const; - double p() const; +```cpp +struct param_type +{ + typedef negative_binomial_distribution distribution_type; + param_type(result_type k = 1, double p = 0.5); + result_type k() const; + double p() const; - bool operator==(const param_type& right) const; - bool operator!=(const param_type& right) const; - }; + bool operator==(const param_type& right) const; + bool operator!=(const param_type& right) const; +}; +``` ### Parameters diff --git a/docs/standard-library/nested-exception-class.md b/docs/standard-library/nested-exception-class.md index ef2467f977..920f179057 100644 --- a/docs/standard-library/nested-exception-class.md +++ b/docs/standard-library/nested-exception-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: nested_exception Class" title: "nested_exception Class" -ms.date: "11/04/2016" +ms.date: 06/17/2022 f1_keywords: ["exception/std::nested_exception"] helpviewer_keywords: ["nested_exception class"] ms.assetid: 5ae2c4ef-c7ad-4469-8a9e-a773e86bb000 +ms.custom: devdivchpfy22 --- + # nested_exception Class The class describes an exception for use with multiple inheritance. It captures the currently handled exception and stores it for later use. diff --git a/docs/standard-library/new-functions.md b/docs/standard-library/new-functions.md index 7bcc74e888..4a7901ce9d 100644 --- a/docs/standard-library/new-functions.md +++ b/docs/standard-library/new-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "11/04/2016" f1_keywords: ["new/std::get_new_handler", "new/std::nothrow", "new/std::set_new_handler"] -ms.assetid: e250f06a-b025-4509-ae7a-5356d56aad7d --- # `` functions @@ -93,8 +92,8 @@ The function stores *`Pnew`* in a static [`new` handler](../standard-library/new ```cpp // new_set_new_handler.cpp // compile with: /EHsc -#include -#include +#include +#include using namespace std; void __cdecl newhandler( ) diff --git a/docs/standard-library/new-operators.md b/docs/standard-library/new-operators.md index ddd7a0a929..49e1184de8 100644 --- a/docs/standard-library/new-operators.md +++ b/docs/standard-library/new-operators.md @@ -1,105 +1,104 @@ --- -description: "Learn more about: operators and enums" title: " operators and enums" -ms.date: "11/04/2016" +description: "Learn more about: operators and enums" +ms.date: 05/21/2022 f1_keywords: ["new/std::operator delete", "new/std::operator new"] -ms.assetid: d1af4b56-9a95-4c65-ab01-bf43e982c7bd --- # `` operators and enums -## enum align_val_t +## `enum align_val_t` ```cpp enum class align_val_t : size_t {}; ``` -## operator delete +## `operator delete` -The function called by a delete expression to de-allocate storage for individual of objects. +The function called by a `delete` expression to deallocate storage for individual objects. ```cpp -void operator delete(void* ptr) throw(); -void operator delete(void *, void*) throw(); -void operator delete(void* ptr, const std::nothrow_t&) throw(); +void operator delete(void* ptr) noexcept; +void operator delete(void *, void*) noexcept; +void operator delete(void* ptr, const std::nothrow_t&) noexcept; ``` ### Parameters -*ptr*\ +*`ptr`*\ The pointer whose value is to be rendered invalid by the deletion. ### Remarks -The first function is called by a delete expression to render the value of *ptr* invalid. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *ptr* that is null or that was returned by an earlier call to [operator new](../standard-library/new-operators.md#op_new)(**size_t**). +The first function is called by a `delete` expression to render the value of *`ptr`* invalid. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *`ptr`* that's `nullptr` or that was returned by an earlier call to [`operator new`](../standard-library/new-operators.md#op_new). -The default behavior for a null value of *ptr* is to do nothing. Any other value of *ptr* must be a value returned earlier by a call as previously described. The default behavior for such a nonnull value of *ptr* is to reclaim storage allocated by the earlier call. It is unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to `operator new`(**size_t**), or to any of `calloc`( **size_t**), `malloc`( **size_t**), or `realloc`( **`void`**\*, **size_t**). +The default behavior for a `nullptr` value in *`ptr`* is to do nothing. Any other value of *`ptr`* must be a value returned earlier by a `new` call as previously described. The default behavior for a non-null value of *`ptr`* is to reclaim storage allocated by the earlier call. It's unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to `operator new`, or to any of the `calloc`, `malloc`, or `realloc` functions. -The second function is called by a placement delete expression corresponding to a new expression of the form **`new`**( **std::size_t**). It does nothing. +The second function is called by a placement `delete` expression corresponding to a `new` expression of the form `new( std::size_t )`. It does nothing. -The third function is called by a placement delete expression corresponding to a new expression of the form **`new`**( **std::size_t**, **conststd::nothrow_t&**). The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of `ptr` that is null or that was returned by an earlier call to `operator new`( **size_t**). The default behavior is to evaluate **`delete`**(`ptr`). +The third function is called by a placement `delete` expression corresponding to a `new` expression of the form `new( std::size_t, const std::nothrow_t& )`. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of `ptr` that is `nullptr` or that was returned by an earlier call to `operator new`. The default behavior is to evaluate `delete( ptr )`. ### Example -See [operator new](../standard-library/new-operators.md#op_new) for an example that use **operator delete**. +See [`operator new`](../standard-library/new-operators.md#op_new) for an example that uses `operator delete`. -## operator delete[] +## `operator delete[]` -The function called by a delete expression to deallocate storage for an array of objects. +The function called by a `delete` expression to deallocate storage for an array of objects. ```cpp -void operator delete[](void* ptr) throw(); -void operator delete[](void *, void*) throw(); -void operator delete[](void* ptr, const std::nothrow_t&) throw(); +void operator delete[](void* ptr) noexcept; +void operator delete[](void *, void*) noexcept; +void operator delete[](void* ptr, const std::nothrow_t&) noexcept; ``` ### Parameters -*ptr*\ +*`ptr`*\ The pointer whose value is to be rendered invalid by the deletion. ### Remarks -The first function is called by an `delete[]` expression to render the value of *ptr* invalid. The function is replaceable because the program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *ptr* that is null or that was returned by an earlier call to [`operator new[]`](../standard-library/new-operators.md#op_new_arr)(**size_t**). The default behavior for a null value of *ptr* is to do nothing. Any other value of *ptr* must be a value returned earlier by a call as previously described. The default behavior for such a non-null value of *ptr* is to reclaim storage allocated by the earlier call. It is unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to [operator new](../standard-library/new-operators.md#op_new)(**size_t**), or to any of `calloc`(**size_t**), `malloc`(**size_t**), or `realloc`( **`void`**\*, **size_t**). +The first function is called by an `delete[]` expression to render the value of *`ptr`* invalid. The function is replaceable because the program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *`ptr`* that is `nullptr` or that was returned by an earlier call to [`operator new[]`](../standard-library/new-operators.md#op_new_arr). The default behavior for a null value of *`ptr`* is to do nothing. Any other value of *`ptr`* must be a value returned earlier by a call as previously described. The default behavior for such a non-null value of *`ptr`* is to reclaim storage allocated by the earlier call. It's unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to [`operator new`](../standard-library/new-operators.md#op_new), or to any of the `calloc`, `malloc`, or `realloc` functions. -The second function is called by a placement `delete[]` expression corresponding to a `new[]` expression of the form `new[]`(**std::size_t**). It does nothing. +The second function is called by a placement `delete[]` expression corresponding to a `new[]` expression of the form `new[]( std::size_t )`. It does nothing. -The third function is called by a placement delete expression corresponding to a `new[]` expression of the form `new[]`( **std::size_t**, **const std::nothrow_t&**). The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *ptr* that is null or that was returned by an earlier call to operator `new[]`(**size_t**). The default behavior is to evaluate `delete[]`( `ptr`). +The third function is called by a placement `delete[]` expression corresponding to a `new[]` expression of the form `new[]( std::size_t, const std::nothrow_t& )`. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is to accept a value of *`ptr`* that is `nullptr` or that was returned by an earlier call to operator `new[]`. The default behavior is to evaluate `delete[]( ptr )`. ### Example See [`operator new[]`](../standard-library/new-operators.md#op_new_arr) for examples of the use of `operator delete[]`. -## operator new +## `operator new` The function called by a new-expression to allocate storage for individual objects. ```cpp -void* operator new(std::size_t count) throw(bad_alloc); -void* operator new(std::size_t count, const std::nothrow_t&) throw(); -void* operator new(std::size_t count, void* ptr) throw(); +void* operator new(std::size_t count); +void* operator new(std::size_t count, const std::nothrow_t&) noexcept; +void* operator new(std::size_t count, void* ptr) noexcept; ``` ### Parameters -*count*\ +*`count`*\ The number of bytes of storage to be allocated. -*ptr*\ +*`ptr`*\ The pointer to be returned. -### Return Value +### Return value -A pointer to the lowest byte address of the newly-allocated storage. Or *ptr*. +A pointer to the lowest byte address of the newly allocated storage. Or *`ptr`*, if using the third form of the function. ### Remarks -The first function is called by a new expression to allocate `count` bytes of storage suitably aligned to represent any object of that size. The program can define an alternate function with this function signature that replaces the default version defined by the C++ Standard Library and so is replaceable. +The first function is called by a `new` expression to allocate `count` bytes of storage suitably aligned to represent any object of that size. This function is *replaceable*. It means the program can define an alternate function with this function signature that replaces the default version defined by the C++ Standard Library. -The required behavior is to return a non-null pointer only if storage can be allocated as requested. Each such allocation yields a pointer to storage disjoint from any other allocated storage. The order and contiguity of storage allocated by successive calls is unspecified. The initial stored value is unspecified. The returned pointer points to the start (lowest byte address) of the allocated storage. If count is zero, the value returned does not compare equal to any other value returned by the function. +The required behavior is to return a non-null pointer only if storage can be allocated as requested. Each such allocation yields a pointer to storage disjoint from any other allocated storage. The order and contiguity of storage allocated by successive calls is unspecified. The initial stored value is unspecified. The returned pointer points to the start (the lowest byte address) of the allocated storage. If *`count`* is zero, the value returned doesn't compare equal to any other value returned by the function. -The default behavior is to execute a loop. Within the loop, the function first attempts to allocate the requested storage. Whether the attempt involves a call to `malloc`( **size_t**) is unspecified. If the attempt is successful, the function returns a pointer to the allocated storage. Otherwise, the function calls the designated [new handler](../standard-library/new-typedefs.md#new_handler). If the called function returns, the loop repeats. The loop terminates when an attempt to allocate the requested storage is successful or when a called function does not return. +The default behavior is to execute a loop. Within the loop, the function first attempts to allocate the requested storage. Whether the attempt involves a call to `malloc` is unspecified. If the allocation attempt is successful, the function returns a pointer to the allocated storage. Otherwise, the function calls the designated function of type [`new_handler`](../standard-library/new-typedefs.md#new_handler). If the called function returns, the loop repeats. The loop terminates when an attempt to allocate the requested storage is successful or when a called function doesn't return. -The required behavior of a new handler is to perform one of the following operations: +The required behavior of a function of type `new_handler` is to perform one of the following operations: - Make more storage available for allocation and then return. @@ -107,101 +106,99 @@ The required behavior of a new handler is to perform one of the following operat - Throw an object of type `bad_alloc`. -The default behavior of a [new handler](../standard-library/new-typedefs.md#new_handler) is to throw an object of type `bad_alloc`. A null pointer designates the default new handler. +The default behavior of a [`new_handler`](../standard-library/new-typedefs.md#new_handler) function is to throw an object of type `bad_alloc`. A `nullptr` value designates the default `new_handler` function. + +The order and contiguity of storage allocated by successive calls to `operator new` is unspecified, as are the initial values stored there. + +To free storage allocated by the first form of `operator new`, call [`operator delete`](../standard-library/new-operators.md#op_delete). -The order and contiguity of storage allocated by successive calls to `operator new`(**size_t**) is unspecified, as are the initial values stored there. +The second function is called by a placement `new` expression to allocate *`count`* bytes of storage suitably aligned to represent any object of that size. This function is *replaceable*. It means the program can define an alternate function with this function signature that replaces the default version defined by the C++ Standard Library. -The second function is called by a placement new expression to allocate `count` bytes of storage suitably aligned to represent any object of that size. The program can define an alternate function with this function signature that replaces the default version defined by the C++ Standard Library and so is replaceable. +The default behavior is to return `operator new( count )` if that function succeeds. Otherwise, it returns `nullptr`. -The default behavior is to return `operator new`(`count`) if that function succeeds. Otherwise, it returns a null pointer. +To free storage allocated by the second form of `operator new` (that is, if it didn't return `nullptr`), call [`operator delete`](../standard-library/new-operators.md#op_delete). -The third function is called by a placement **`new`** expression, of the form `new ( args ) T`. Here, *args* consists of a single object pointer. This can be useful for constructing an object at a known address. The function returns *ptr*. +The third function is called by a non-allocating placement `new` expression, of the form `new ( ptr ) T`. Here, *`ptr`* consists of a single object pointer. It can be useful for constructing an object at a known address. The function returns *`ptr`*. You must call the destructor explicitly on this object. -To free storage allocated by **operator new**, call [operator delete](../standard-library/new-operators.md#op_delete). +If you call non-allocating placement `new`, don't call `delete`. Instead, call the deallocator for the memory you provided, if necessary, after you call the destructor for the object. -For information on throwing or non-throwing behavior of new, see [The new and delete Operators](../cpp/new-and-delete-operators.md). +For information on throwing or non-throwing behavior of `new`, see [The `new` and `delete` operators](../cpp/new-and-delete-operators.md). ### Example ```cpp // new_op_new.cpp // compile with: /EHsc -#include -#include +#include +#include using namespace std; -class MyClass -{ +class MyClass { + int member{ 0 }; public: - MyClass( ) - { - cout << "Construction MyClass." << this << endl; - }; - - ~MyClass( ) - { - imember = 0; cout << "Destructing MyClass." << this << endl; - }; - int imember; + MyClass() { + cout << "MyClass at 0x" << this << " constructed.\n"; + }; + + ~MyClass() { + cout << "MyClass at 0x" << this << " destroyed.\n"; + }; }; int main( ) { - // The first form of new delete - MyClass* fPtr = new MyClass; - delete fPtr; - - // The second form of new delete - MyClass* fPtr2 = new( nothrow ) MyClass; - delete fPtr2; - - // The third form of new delete - char x[sizeof( MyClass )]; - MyClass* fPtr3 = new( &x[0] ) MyClass; - fPtr3 -> ~MyClass(); - cout << "The address of x[0] is : " << ( void* )&x[0] << endl; + // The first form of new / delete + MyClass* fPtr1 = new MyClass; + delete fPtr1; + + // The second form (fail returns nullptr) of new / delete + MyClass* fPtr2 = new(nothrow) MyClass[2]; + if (fPtr2) + delete fPtr2; + + // The third form (non-allocating placement) of new / delete + char x[sizeof(MyClass)]; // x is automatic + MyClass* fPtr3 = new(&x[0]) MyClass; + fPtr3->~MyClass(); // Requires explicit destructor call + // no delete because x is on the stack } ``` -## operator new[] +## `operator new[]` The allocation function called by a new expression to allocate storage for an array of objects. ```cpp -void* operator new[](std::size_t count) throw(std::bad_alloc); -void* operator new[](std::size_t count, const std::nothrow_t&) throw(); -void* operator new[](std::size_t count, void* ptr) throw(); +void* operator new[](std::size_t count); +void* operator new[](std::size_t count, const std::nothrow_t&) noexcept; +void* operator new[](std::size_t count, void* ptr) noexcept; ``` ### Parameters -*count*\ +*`count`*\ The number of bytes of storage to be allocated for the array object. -*ptr*\ +*`ptr`*\ The pointer to be returned. -### Return Value +### Return value -A pointer to the lowest byte address of the newly-allocated storage. Or *ptr*. +A pointer to the lowest byte address of the newly allocated storage. Or *`ptr`*, when the third form is used. ### Remarks -The first function is called by a `new[]` expression to allocate `count` bytes of storage suitably aligned to represent any array object of that size or smaller. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is the same as for [operator new](../standard-library/new-operators.md#op_new)(**size_t**). The default behavior is to return `operator new`( `count`). - -The second function is called by a placement `new[]` expression to allocate `count` bytes of storage suitably aligned to represent any array object of that size. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The default behavior is to return **operatornew**(`count`) if that function succeeds. Otherwise, it returns a null pointer. +The first function is called by a `new[]` expression to allocate *`count`* bytes of storage suitably aligned to represent any array object of that size or smaller. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The required behavior is the same as for [`operator new`](../standard-library/new-operators.md#op_new). The default behavior is to return `operator new( count )` if it succeeds. Otherwise, it throws a `std::bad_alloc` exception (or an exception derived from `std::bad_alloc`). To free storage allocated by this form of `operator new[]`, call [`operator delete[]`](../standard-library/new-operators.md#op_delete_arr). -The third function is called by a placement `new[]` expression, of the form **`new`** ( *args*) **T**[ **N**]. Here, *args* consists of a single object pointer. The function returns `ptr`. +The second function is called by a placement `new[]` expression to allocate *`count`* bytes of storage suitably aligned to represent any array object of that size. The program can define a function with this function signature that replaces the default version defined by the C++ Standard Library. The default behavior is to return `operator new( count )` if that function succeeds. Otherwise, it returns `nullptr`. To free storage allocated by this form of `operator new[]`, call `operator delete[]`. For more information on the throwing or non-throwing behavior of `new`, see [The `new` and `delete` operators](../cpp/new-and-delete-operators.md). -To free storage allocated by `operator new[]`, call [`operator delete[]`](../standard-library/new-operators.md#op_delete_arr). - -For information on throwing or nonthrowing behavior of new, see [The new and delete Operators](../cpp/new-and-delete-operators.md). +The third function is called by a non-allocating placement `new[]` expression, of the form `new( ptr ) T[ N ]`. This form doesn't allocate memory. It constructs the objects in the memory passed in through the *`ptr`* parameter. The function returns *`ptr`*. You must call the destructor explicitly for each object created. You're responsible for providing sufficient memory for *`ptr`*. Don't invoke `delete[]` on the value returned by the `new` expression. Instead, deallocate *`ptr`*, if necessary, after you call the destructors. ### Example ```cpp -// new_op_alloc.cpp +// new_op_array.cpp // compile with: /EHsc #include #include @@ -209,32 +206,34 @@ For information on throwing or nonthrowing behavior of new, see [The new and del using namespace std; class MyClass { + int member{ 0 }; public: - MyClass() { - cout << "Construction MyClass." << this << endl; - }; - - ~MyClass() { - imember = 0; cout << "Destructing MyClass." << this << endl; - }; - int imember; + MyClass() { + cout << "MyClass at 0x" << this << " constructed.\n"; + }; + + ~MyClass() { + cout << "MyClass at 0x" << this << " destroyed.\n"; + }; }; int main() { - // The first form of new delete - MyClass* fPtr = new MyClass[2]; - delete[ ] fPtr; - - // The second form of new delete - char x[2 * sizeof( MyClass ) + sizeof(int)]; - - MyClass* fPtr2 = new( &x[0] ) MyClass[2]; - fPtr2[1].~MyClass(); - fPtr2[0].~MyClass(); - cout << "The address of x[0] is : " << ( void* )&x[0] << endl; - - // The third form of new delete - MyClass* fPtr3 = new( nothrow ) MyClass[2]; - delete[ ] fPtr3; + // The first form of array new / delete + MyClass* fPtr1 = new MyClass[2]; + delete[] fPtr1; + + // The second form (fail returns nullptr) of array new / delete + MyClass* fPtr2 = new(nothrow) MyClass[2]; + if (fPtr2) + delete[] fPtr2; + + // The third form (non-allocating placement) of array new / delete + char x[2 * sizeof(MyClass) + sizeof(int)]; // x is automatic + + MyClass* fPtr3 = new(&x[0]) MyClass[2]; + fPtr3[1].~MyClass(); // Requires explicit destructor calls + fPtr3[0].~MyClass(); // Recommended in reverse construction order + // Don't delete[] fPtr3 here. + // delete[] &x[0] not required because x is on the stack } ``` diff --git a/docs/standard-library/new-typedefs.md b/docs/standard-library/new-typedefs.md index 255ce65355..6dd94c3407 100644 --- a/docs/standard-library/new-typedefs.md +++ b/docs/standard-library/new-typedefs.md @@ -1,13 +1,13 @@ --- description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +ms.date: 05/27/2022 f1_keywords: ["new/std::new_handler"] ms.assetid: aef01de1-06b5-4b6c-aebc-2c9f423d7e47 --- # `` typedefs -## hardware_constructive_interference_size +## `hardware_constructive_interference_size` ```cpp inline constexpr size_t hardware_constructive_interference_size = implementation-defined; @@ -15,7 +15,7 @@ inline constexpr size_t hardware_constructive_interference_size = implementation ### Remarks -This number is the maximum recommended size of contiguous memory occupied by two objects accessed with temporal locality by concurrent threads. It shall be at least `alignof(max_align_t)`. +This number is the maximum recommended size of contiguous memory occupied by two objects accessed with temporal locality by concurrent threads. It must be at least `alignof(max_align_t)`. ### Example @@ -34,7 +34,7 @@ struct kennel { static_assert(sizeof(together) <= hardware_constructive_interference_size); ``` -## hardware_destructive_interference_size +## `hardware_destructive_interference_size` ```cpp inline constexpr size_t hardware_destructive_interference_size = implementation-defined; @@ -42,7 +42,7 @@ inline constexpr size_t hardware_destructive_interference_size = implementation- ### Remarks -This number is the minimum recommended offset between two concurrently-accessed objects to avoid additional performance degradation due to contention introduced by the implementation. It shall be at least `alignof(max_align_t)`. +This number is the minimum recommended offset between two concurrently accessed objects to avoid performance degradation due to contention introduced by the implementation. It must be at least `alignof(max_align_t)`. ### Example @@ -53,9 +53,9 @@ struct keep_apart { }; ``` -## new_handler +## `new_handler` -The type points to a function suitable for use as a new handler. +The `new_handler` type points to a function suitable for use as a *`new handler`*, a function that can reclaim or release memory. ```cpp typedef void (*new_handler)(); @@ -63,8 +63,8 @@ typedef void (*new_handler)(); ### Remarks -This type of handler function is called by **operator new** or `operator new[]` when they cannot satisfy a request for additional storage. +When of function of this type is set by [`std::set_new_handler`](../standard-library/new-functions.md#set_new_handler), the function is called by `operator new` or `operator new[]` when they can't satisfy a request for more storage. ### Example -See [set_new_handler](../standard-library/new-functions.md#set_new_handler) for an example using `new_handler` as a return value. +For an example that uses `new_handler` as a return value, see [`set_new_handler`](../standard-library/new-functions.md#set_new_handler). diff --git a/docs/standard-library/nonexistent-local-time.md b/docs/standard-library/nonexistent-local-time.md index 526f4e4558..45529f5820 100644 --- a/docs/standard-library/nonexistent-local-time.md +++ b/docs/standard-library/nonexistent-local-time.md @@ -4,6 +4,7 @@ title: "nonexistent_local_time class" ms.date: 10/08/2021 f1_keywords: ["chrono/std::chrono::nonexistent_local_time", "chrono/std::chrono::nonexistent_local_time::what"] helpviewer_keywords: ["std::chrono [C++], nonexistent_local_time"] +dev_langs: ["C++"] --- # `nonexistent_local_time` class @@ -13,7 +14,7 @@ This exception is thrown when attempting to convert a `local_time` to a non-exis ## Syntax ```cpp -class nonexistent_local_time : public runtime_error; // c++ 20 +class nonexistent_local_time : public runtime_error; // C++20 ``` ## Remarks @@ -93,7 +94,7 @@ You typically won't create this exception. It's thrown by functions that convert Gets a string describing why the time is non-existent. ```cpp -[nodiscard] virtual const char* what() const noexcept; +[[nodiscard]] virtual const char* what() const noexcept; ``` ### Return value diff --git a/docs/standard-library/not-equal-to-struct.md b/docs/standard-library/not-equal-to-struct.md index c749d9e060..6324e21944 100644 --- a/docs/standard-library/not-equal-to-struct.md +++ b/docs/standard-library/not-equal-to-struct.md @@ -12,7 +12,7 @@ A binary predicate that performs the inequality operation (`operator!=`) on its ## Syntax -``` +```cpp template struct not_equal_to : public binary_function { @@ -24,7 +24,7 @@ template <> struct not_equal_to { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) != std::forward(Right)); }; ``` @@ -93,7 +93,7 @@ int main( ) transform ( v1.begin( ), v1.end( ), v2.begin( ), v3.begin ( ), not_equal_to( ) ); - cout << "The result of the element-wise not_equal_to comparsion\n" + cout << "The result of the element-wise not_equal_to comparison\n" << "between v1 & v2 is: ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ ) cout << *Iter3 << " "; @@ -104,6 +104,6 @@ int main( ) ```Output The vector v1 = ( 0 1 4 5 8 9 ) The vector v2 = ( -0 1 -4 5 -8 9 ) -The result of the element-wise not_equal_to comparsion +The result of the element-wise not_equal_to comparison between v1 & v2 is: ( 0 0 1 0 1 0 ) ``` diff --git a/docs/standard-library/num-put-class.md b/docs/standard-library/num-put-class.md index 2fecf24e5f..1a9729edc9 100644 --- a/docs/standard-library/num-put-class.md +++ b/docs/standard-library/num-put-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: num_put Class" title: "num_put Class" -ms.date: "11/04/2016" +description: "Learn more about: num_put Class" +ms.date: 11/04/2016 f1_keywords: ["xlocnum/std::num_put", "locale/std::num_put::char_type", "locale/std::num_put::iter_type", "locale/std::num_put::do_put", "locale/std::num_put::put"] helpviewer_keywords: ["std::num_put [C++]", "std::num_put [C++], char_type", "std::num_put [C++], iter_type", "std::num_put [C++], do_put", "std::num_put [C++], put"] -ms.assetid: 36c5bffc-8283-4201-8ed4-78c4d81f8a17 --- # num_put Class @@ -384,7 +383,7 @@ An output iterator the addresses the position one beyond the last element produc ### Remarks -All member functions return [do_put](#do_put)( `next`, `_Iosbase`, `_Fill`, `val`). +All member functions return [do_put](#do_put)(`next`, `_Iosbase`, `_Fill`, `val`). ### Example diff --git a/docs/standard-library/numpunct-byname-class.md b/docs/standard-library/numpunct-byname-class.md index 7ab66566f4..5d4feb1798 100644 --- a/docs/standard-library/numpunct-byname-class.md +++ b/docs/standard-library/numpunct-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: numpunct_byname Class" title: "numpunct_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: numpunct_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xlocnum/std::numpunct_byname"] helpviewer_keywords: ["numpunct_byname class"] -ms.assetid: 18412924-e085-4771-b5e9-7a200cbdd7c0 --- # numpunct_byname Class @@ -32,7 +31,7 @@ protected: ## Remarks -Its behavior is determined by the [named](../standard-library/locale-class.md#name) locale `_Locname`. The constructor initializes its base object with [numpunct](../standard-library/numpunct-class.md#numpunct)\( `_Refs`). +Its behavior is determined by the [named](../standard-library/locale-class.md#name) locale `_Locname`. The constructor initializes its base object with [numpunct](../standard-library/numpunct-class.md#numpunct)\(`_Refs`). ## Requirements diff --git a/docs/standard-library/numpunct-class.md b/docs/standard-library/numpunct-class.md index d56d1c0b9b..a0c85da261 100644 --- a/docs/standard-library/numpunct-class.md +++ b/docs/standard-library/numpunct-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: numpunct Class" title: "numpunct Class" -ms.date: "11/04/2016" +description: "Learn more about: numpunct Class" +ms.date: 11/04/2016 f1_keywords: ["xlocnum/std::numpunct", "xlocnum/std::numpunct::char_type", "xlocnum/std::numpunct::string_type", "xlocnum/std::numpunct::decimal_point", "xlocnum/std::numpunct::do_decimal_point", "xlocnum/std::numpunct::do_falsename", "xlocnum/std::numpunct::do_grouping", "xlocnum/std::numpunct::do_thousands_sep", "xlocnum/std::numpunct::do_truename", "xlocnum/std::numpunct::falsename", "xlocnum/std::numpunct::grouping", "xlocnum/std::numpunct::thousands_sep", "xlocnum/std::numpunct::truename"] helpviewer_keywords: ["std::numpunct [C++]", "std::numpunct [C++], char_type", "std::numpunct [C++], string_type", "std::numpunct [C++], decimal_point", "std::numpunct [C++], do_decimal_point", "std::numpunct [C++], do_falsename", "std::numpunct [C++], do_grouping", "std::numpunct [C++], do_thousands_sep", "std::numpunct [C++], do_truename", "std::numpunct [C++], falsename", "std::numpunct [C++], grouping", "std::numpunct [C++], thousands_sep", "std::numpunct [C++], truename"] -ms.assetid: 73fb93cc-ac11-4c98-987c-bfa6267df596 --- # numpunct Class @@ -107,7 +106,7 @@ int main( ) npunct.decimal_point( ) << endl; cout << loc.name( ) << " thousands separator " << npunct.thousands_sep( ) << endl; -}; +} ``` ```Output @@ -378,7 +377,7 @@ int main( ) npunct.decimal_point( ) << endl; cout << loc.name( ) << " thousands separator " << npunct.thousands_sep( ) << endl; -}; +} ``` ```Output diff --git a/docs/standard-library/once-flag-structure.md b/docs/standard-library/once-flag-structure.md index e9ec7b1fef..1ea1eac40b 100644 --- a/docs/standard-library/once-flag-structure.md +++ b/docs/standard-library/once-flag-structure.md @@ -11,10 +11,12 @@ Represents a **`struct`** that is used with the template function [call_once](.. ## Syntax +```cpp struct once_flag - { +{ constexpr once_flag() noexcept; - }; +}; +``` ## Remarks diff --git a/docs/standard-library/operator-greater-than-sample-container.md b/docs/standard-library/operator-greater-than-sample-container.md index b35284c659..a6bf41df1d 100644 --- a/docs/standard-library/operator-greater-than-sample-container.md +++ b/docs/standard-library/operator-greater-than-sample-container.md @@ -17,7 +17,7 @@ Overloads **operator>** to compare two objects of class template [Container](../ ```cpp template -bool operator*gt;( +bool operator*gt( const Container & left, const Container & right); ``` diff --git a/docs/standard-library/optional-class.md b/docs/standard-library/optional-class.md index 91889ce7f7..4df0c70b5a 100644 --- a/docs/standard-library/optional-class.md +++ b/docs/standard-library/optional-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: optional Class" title: "optional Class" -ms.date: "11/04/2016" +ms.date: 11/14/2024 f1_keywords: ["optional/std::optional", "optional/std::optional::has_value", "optional/std::optional::reset", "optional/std::optional::value", "optional/std::optional::value_or"] helpviewer_keywords: ["optional/std::optional", "optional/std::optional::has_value", "optional/std::optional::reset", "optional/std::optional::value", "optional/std::optional::value_or"] --- @@ -11,7 +11,7 @@ The class template `optional` describes an object that may or may not contain When an instance of `optional` contains a value, the contained value is allocated within the storage of the `optional` object, in a region suitably aligned for type `T`. When an `optional` is converted to **`bool`**, the result is **`true`** if the object contains a value; otherwise, it's **`false`**. -The contained object type `T` must not be [in_place_t](in-place-t-struct.md) or [nullopt_t](nullopt-t-structure.md). `T` must be *destructible*, that is, its destructor must reclaim all owned resources, and may throw no exceptions. +The contained object type `T` must not be [`in_place_t`](in-place-t-struct.md) or [`nullopt_t`](nullopt-t-structure.md). `T` must be *destructible*, that is, its destructor must reclaim all owned resources, and may throw no exceptions. The `optional` class is new in C++17. @@ -123,7 +123,7 @@ If *rhs* contains a value, direct initializes the contained value as if using `s ## ~optional destructor -Destroys any non-trivially destructible contained value, if one is present, by invoking its destructor. +Destroys the contained value, if one is present. ```cpp ~optional(); diff --git a/docs/standard-library/optional-operators.md b/docs/standard-library/optional-operators.md index 839624fd2d..99a367665f 100644 --- a/docs/standard-library/optional-operators.md +++ b/docs/standard-library/optional-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" -f1_keywords: ["optional/std::operator!=", "optional/std::operator==", "optional/std::operator>", "optional/std::operator>=;", "optional/std::operator<", "optional/std::operator<="] -ms.assetid: 57492e09-3836-4dbc-9ae5-78ecf506c190 +description: "Learn more about: operators" +ms.date: 11/04/2016 +f1_keywords: ["optional/std::operator!=", "optional/std::operator==", "optional/std::operator>", "optional/std::operator>=;", "optional/std::operator<", "optional/std::operator<="] helpviewer_keywords: ["std::operator!= (optional)", "std::operator== (optional)", "std::operator> (optional)", "std::operator>= (optional)", "std::operator< (optional)", "std::`operator<=` (optional)"] --- # `` operators diff --git a/docs/standard-library/ostream-iterator-class.md b/docs/standard-library/ostream-iterator-class.md index dadabfcbf2..de3f56cd39 100644 --- a/docs/standard-library/ostream-iterator-class.md +++ b/docs/standard-library/ostream-iterator-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: ostream_iterator Class" title: "ostream_iterator Class" -ms.date: "11/04/2016" +ms.date: 06/17/2022 f1_keywords: ["iterator/std::ostream_iterator", "iterator/std::ostream_iterator::char_type", "iterator/std::ostream_iterator::ostream_type", "iterator/std::ostream_iterator::traits_type"] helpviewer_keywords: ["std::ostream_iterator [C++]", "std::ostream_iterator [C++], char_type", "std::ostream_iterator [C++], ostream_type", "std::ostream_iterator [C++], traits_type"] ms.assetid: 24d842d3-9f45-4bf6-a697-62f5968f5a03 +ms.custom: devdivchpfy22 --- + # ostream_iterator Class The class template ostream_iterator describes an output iterator object that writes successive elements onto the output stream with the extraction `operator <<`. @@ -121,7 +123,7 @@ A reference to the `ostream_iterator`. ### Remarks -The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression \* *ii* = *t* be valid and says nothing about the **`operator`** or the `operator=` on their own. The member operator in this implementation returns **\*this**. +The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression \* *ii* = *t* be valid and says nothing about the **`operator`** or the `operator=` on their own. The member operator in this implementation returns **`*this`**. ### Example @@ -171,7 +173,7 @@ A reference to the `ostream_iterator`. ### Remarks -These member operators both return **\*this**. +These member operators both return **`*this`**. ### Example diff --git a/docs/standard-library/ostream-operators.md b/docs/standard-library/ostream-operators.md index 6b1d575283..566531288c 100644 --- a/docs/standard-library/ostream-operators.md +++ b/docs/standard-library/ostream-operators.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["ostream/std::operator<<"] -ms.assetid: 9282a62e-a3d1-4371-a284-fbc9515bb9a2 --- # `` operators -[`operator<<`](#op_lt_lt) +The `` header provides the following operators: ## `operator<<` diff --git a/docs/standard-library/ostream-typedefs.md b/docs/standard-library/ostream-typedefs.md index fd4844f2c2..7ace186c98 100644 --- a/docs/standard-library/ostream-typedefs.md +++ b/docs/standard-library/ostream-typedefs.md @@ -1,18 +1,16 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["iosfwd/std::ostream", "iosfwd/std::wostream"] -ms.assetid: 2ec4dc52-a01f-4654-bd65-dd5288777c48 --- # `` typedefs -[ostream](#ostream)\ -[wostream](#wostream) +The `` header provides the following typedefs: -## ostream +## `ostream` -Creates a type from basic_ostream that is specialized on **`char`** and `char_traits` specialized on **`char`**. +Creates a type from `basic_ostream` that is specialized on **`char`** and `char_traits` specialized on **`char`**. ```cpp typedef basic_ostream> ostream; @@ -20,7 +18,7 @@ typedef basic_ostream> ostream; ### Remarks -The type is a synonym for class template [basic_ostream](../standard-library/basic-ostream-class.md), specialized for elements of type **`char`** with default character traits. +The type is a synonym for class template [`basic_ostream`](../standard-library/basic-ostream-class.md), specialized for elements of type **`char`** with default character traits. ## wostream @@ -32,7 +30,7 @@ typedef basic_ostream> wostream; ### Remarks -The type is a synonym for class template [basic_ostream](../standard-library/basic-ostream-class.md), specialized for elements of type **`wchar_t`** with default character traits. +The type is a synonym for class template [`basic_ostream`](../standard-library/basic-ostream-class.md), specialized for elements of type **`wchar_t`** with default character traits. ## See also diff --git a/docs/standard-library/ostrstream-class.md b/docs/standard-library/ostrstream-class.md index c9b7a0acaf..567245feb6 100644 --- a/docs/standard-library/ostrstream-class.md +++ b/docs/standard-library/ostrstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: ostrstream Class" title: "ostrstream Class" -ms.date: "11/04/2016" +description: "Learn more about: ostrstream Class" +ms.date: 11/04/2016 f1_keywords: ["strstream/std::ostrstream::freeze", "strstream/std::ostrstream::pcount", "strstream/std::ostrstream::rdbuf", "strstream/std::ostrstream::str"] helpviewer_keywords: ["std::ostrstream [C++], freeze", "std::ostrstream [C++], pcount", "std::ostrstream [C++], rdbuf", "std::ostrstream [C++], str"] -ms.assetid: e2e34679-b266-4728-a8e1-8eda5d400e46 --- # ostrstream Class @@ -94,7 +93,7 @@ Both constructors initialize the base class by calling [ostream](../standard-lib - If `_Mode` & **ios_base::app**== 0, then `ptr` must designate the first element of an array of `count` elements, and the constructor calls `strstreambuf`(`ptr`, `count`, `ptr`). -- Otherwise, `ptr` must designate the first element of an array of count elements that contains a C string whose first element is designated by `ptr`, and the constructor calls `strstreambuf`(`ptr`, `count`, `ptr` + `strlen`( `ptr`) ). +- Otherwise, `ptr` must designate the first element of an array of count elements that contains a C string whose first element is designated by `ptr`, and the constructor calls `strstreambuf`(`ptr`, `count`, `ptr` + `strlen`(`ptr`)). ## ostrstream::pcount diff --git a/docs/standard-library/output-file-stream-member-functions.md b/docs/standard-library/output-file-stream-member-functions.md index 5bced7ef89..6c7902a624 100644 --- a/docs/standard-library/output-file-stream-member-functions.md +++ b/docs/standard-library/output-file-stream-member-functions.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Output File Stream Member Functions" title: "Output File Stream Member Functions" -ms.date: "08/25/2021" +description: "Learn more about: Output File Stream Member Functions" +ms.date: 08/25/2021 helpviewer_keywords: ["output streams [C++], member functions"] --- # Output File Stream Member Functions @@ -12,7 +12,7 @@ Output stream member functions have three types: those that are equivalent to ma To use an output file stream ([`ofstream`](../standard-library/basic-ofstream-class.md)), you must associate that stream with a specific disk file in the constructor or the `open` function. If you use the `open` function, you can reuse the same stream object with a series of files. In either case, the arguments describing the file are the same. -When you open the file associated with an output stream, you generally specify an `open_mode` flag. You can combine these flags, which are defined as enumerators in the `ios` class, with the bitwise OR ( `|` ) operator. See [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode) for a list of the enumerators. +When you open the file associated with an output stream, you generally specify an `open_mode` flag. You can combine these flags, which are defined as enumerators in the `ios` class, with the bitwise OR (`|`) operator. See [`ios_base::openmode`](../standard-library/ios-base-class.md#openmode) for a list of the enumerators. Three common output stream situations involve mode options: @@ -26,7 +26,7 @@ Three common output stream situations involve mode options: // Equivalent to above ``` -- Appending records to an existing file or creating one if it does not exist. +- Appending records to an existing file or creating one if it doesn't exist. ```cpp ofstream ofile("FILENAME", ios::app); @@ -79,11 +79,11 @@ int main( ) } ``` -The `write` function does not stop when it reaches a null character, so the complete class structure is written. The function takes two arguments: a **`char`** pointer and a count of characters to write. Note the required cast to **`char *`** before the address of the structure object. +The `write` function doesn't stop when it reaches a `NULL` character, so the complete class structure is written. The function takes two arguments: a **`char`** pointer and a count of characters to write. Note the required cast to **`char *`** before the address of the structure object. ## The seekp and tellp Functions -An output file stream keeps an internal pointer that points to the position where data is to be written next. The `seekp` member function sets this pointer and thus provides random-access disk file output. The `tellp` member function returns the file position. For examples that use the input stream equivalents to `seekp` and `tellp`, see [The seekg and tellg Functions](../standard-library/input-stream-member-functions.md). +An output file stream keeps an internal pointer that points to the position where data is to be written next. The `seekp` member function sets this pointer and thus provides random-access disk file output. The `tellp` member function returns the file position. For examples that use the input stream equivalents to `seekp` and `tellp`, see [The `seekg` and `tellg` Functions](../standard-library/input-stream-member-functions.md). ## The close Function for Output Streams @@ -97,14 +97,14 @@ Use these member functions to test for errors while writing to a stream: |Function|Return value| |--------------|------------------| -|[`bad`](basic-ios-class.md#bad)|Returns **`true`** if there is an unrecoverable error.| -|[`fail`](basic-ios-class.md#fail)|Returns **`true`** if there is an unrecoverable error or an "expected" condition, such as a conversion error, or if the file is not found. Processing can often resume after a call to `clear` with a zero argument.| -|[`good`](basic-ios-class.md#good)|Returns **`true`** if there is no error condition (unrecoverable or otherwise) and the end-of-file flag is not set.| +|[`bad`](basic-ios-class.md#bad)|Returns **`true`** if there's an unrecoverable error.| +|[`fail`](basic-ios-class.md#fail)|Returns **`true`** if there's an unrecoverable error or an "expected" condition, such as a conversion error, or if the file isn't found. Processing can often resume after a call to `clear` with a zero argument.| +|[`good`](basic-ios-class.md#good)|Returns **`true`** if there's no error condition (unrecoverable or otherwise) and the end-of-file flag isn't set.| |[`eof`](basic-ios-class.md#eof)|Returns **`true`** on the end-of-file condition.| |[`clear`](basic-ios-class.md#clear)|Sets the internal error state. If called with the default arguments, it clears all error bits.| -|[`rdstate`](basic-ios-class.md#rdstate|Returns the current error state.| +|[`rdstate`](basic-ios-class.md#rdstate)|Returns the current error state.| -The **!** operator is overloaded to perform the same function as the `fail` function. Thus the expression: +The **`!`** operator is overloaded to perform the same function as the `fail` function. Thus the expression: ```cpp if(!cout)... @@ -128,7 +128,7 @@ is equal to: if(!cout.fail())... ``` -The **`void*()`** operator is not equivalent to `good` because it does not test for the end of file. +The **`void*()`** operator isn't equivalent to `good` because it doesn't test for the end of file. ## See also diff --git a/docs/standard-library/output-iterator-tag-struct.md b/docs/standard-library/output-iterator-tag-struct.md index a6e926d4bd..c4dae468e4 100644 --- a/docs/standard-library/output-iterator-tag-struct.md +++ b/docs/standard-library/output-iterator-tag-struct.md @@ -12,7 +12,9 @@ A class that provides a return type for `iterator_category` function that repres ## Syntax +```cpp struct output_iterator_tag {}; +``` ## Remarks diff --git a/docs/standard-library/output-streams.md b/docs/standard-library/output-streams.md index 11612df48c..5534eed2ec 100644 --- a/docs/standard-library/output-streams.md +++ b/docs/standard-library/output-streams.md @@ -3,7 +3,6 @@ description: "Learn more about: Output Streams" title: "Output Streams" ms.date: "11/04/2016" helpviewer_keywords: ["output streams"] -ms.assetid: b49410e3-5caa-4153-9d0d-c4266408dc83 --- # Output Streams @@ -43,6 +42,6 @@ Like the run-time function `sprintf_s`, the `ostringstream` class supports outpu ## See also -[ofstream](../standard-library/basic-ofstream-class.md)\ -[ostringstream](../standard-library/basic-ostringstream-class.md)\ -[iostream Programming](../standard-library/iostream-programming.md) +[`ofstream`](../standard-library/basic-ofstream-class.md)\ +[`ostringstream`](../standard-library/basic-ostringstream-class.md)\ +[`iostream` Programming](../standard-library/iostream-programming.md) diff --git a/docs/standard-library/owning-view-class.md b/docs/standard-library/owning-view-class.md new file mode 100644 index 0000000000..fec32d4b6b --- /dev/null +++ b/docs/standard-library/owning-view-class.md @@ -0,0 +1,309 @@ +--- +title: owning_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) owning_view class, which takes ownership of the elements in a range." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::owning_view", "ranges/std::owning_view::base", "ranges/std::owning_view::begin", "ranges/std::owning_view::end", "ranges/std::owning_view::size", "ranges/std::owning_view::empty", "ranges/std::owning_view::operator bool", "ranges/std::owning_view::data", "ranges/std::owning_view::back", "ranges/std::owning_view::front", "ranges/std::owning_view::operator[]", "ranges/std::owning_view::operator="] +helpviewer_keywords: ["std::ranges::owning_view [C++]", "std::ranges::owning_view [C++], base", "std::ranges::owning_view [C++], begin", "std::ranges::owning_view [C++], end", "std::ranges::owning_view [C++], size", "std::ranges::owning_view [C++], data", "std::ranges::owning_view [C++], empty", "std::ranges::owning_view [C++], operator bool", "std::ranges::owning_view [C++], front", "std::ranges::owning_view [C++], back", "std::ranges::owning_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `owning_view` class (C++ Standard Library) + +A view that takes ownership of the elements in another range. + +## Syntax + +```cpp +template + requires std::movable && (!is-initializer-list) +class owning_view : public ranges::view_interface>; +``` + +### Template parameters + +*`R`*\ +The type of the underlying range. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::all`](range-adaptors.md#all) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct an `owning_view`. | +| [`base`](#base)C++20 | Get a reference to the owned range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`data`](#data)C++20 | Get a pointer to the first element. | +| [`empty`](#empty)C++20 | Test whether the view is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. | +| [`operator=`](#assignment_operator) | Assign (move) the contents from another `owning_view` to this one. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create an `owning_view` is by using the [`views::all`](range-adaptors.md#all) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +Even though this class owns its elements, it's not expensive to construct because the underlying range is moved using `std::move()`. + +This view is useful when you want a range that doesn't depend on the lifetime of the container providing the elements. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `owning_view`. + +```cpp +1) owning_view() requires default_initializable = default; +2) constexpr owning_view(R&& rg); +3) owning_view(const owning_view& v) = delete; // no copy constructor +4) owning_view(const owning_view&& v) = default; // move constructor +``` + +### Parameters + +*`rg`*\ +The range to move to the `owning_view`. + +*`v`*\ +The `owning_view` to move to the new `owning_view`. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Remarks + +1\) The default constructor creates a default-initialized `owning_view`.\ +2\) Move constructs the `owning_view` from *`rg`*.\ +3\) An `owning_view` can't be copied, only moved.\ +4\) Construct the `owning_view` from another `owning_view`. + +### Example: `owning_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myOwningView = std::views::all(std::move(v)); // create an owning_view from a moved vector + std::cout << v.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << myOwningView.size() << '\n'; // outputs 10 + + std::vector v2 = {1,2,3,4,5}; + std::ranges::owning_view> ov2{std::move(v2)}; + std::cout << v2.size() << '\n'; // outputs 0 because ov2 now owns the elements + std::cout << ov2.size() << '\n'; // outputs 5 +} +``` + +```output +0 +10 +0 +5 +``` + +## `base` + +Gets a reference to the underlying range. + +```cpp +1) constexpr R& base() & noexcept { return r_; } +2) constexpr const R& base() const & noexcept { return r_; } +3) constexpr R&& base() && noexcept { return std::move(r_); } +4) constexpr const R&& base() const && noexcept { return std::move(r_); } +``` + +### Parameters + +None. + +### Return value + +A reference to the underlying range, call it *`rg`*.\ +For 1 & 2, the underlying range is returned via `return rg;`\ +For 3 & 4, the underlying range is returned via `std::move(rg);` + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr iterator_t begin(); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `data` + +Get a pointer to the first element in the view. + +```cpp +constexpr auto data() + requires std::contiguous_iterator>; +constexpr auto data() const + requires std::contiguous_iterator>; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element in the view. + +### Remarks + +The underlying owned range must satisfy `contiguous_range`. + +## `empty` + +Test whether the view is empty. + +```cpp +constexpr bool empty(); +constexpr bool empty() const; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the underlying range has no elements. Otherwise, returns `false`. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr sentinel_t end(); +constexpr auto end() const requires range +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## `operator=` + +Assign (move) the contents from another `owning_view` to this one. + +```cpp +owning_view& operator=(owning_view&&) = default; +``` + +### Parameters + +The `owning_view` to assign (move) to this one. + +### Return value + +`*this` + +### Remarks + +An `owning_view` can't be copied, only moved. + +### Example: `operator=` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v1 = {1,2,3}; + std::ranges::owning_view> ov1{std::move(v1)}; + + std::vector v2 = {4,5,6}; + std::ranges::owning_view> ov2{std::move(v2)}; + + // operator= + ov2 = std::move(ov1); + + // ov1 took ownership of v1, so v1 is empty + // ov2 took ownership of v2, so v2 is empty + // ov2 then took ownership of ov1, so ov1 is empty + // ov2 now owns the elements 1, 2, 3 + + std::cout << std::boolalpha << "v1.empty():" << v1.empty() << " ov1.empty():" << ov1.empty() << '\n'; // v1.empty():true ov1.empty():true + std::cout << "v2.empty():" << v2.empty() << " ov2.size():" << ov2.size() << '\n'; // v2.empty():true ov2.size():3 + + for (auto e : ov2) + { + std::cout << e << ' '; // 1 2 3 + } +} +``` + +```output +v1.empty():true ov1.empty():true +v2.empty():true ov2.size():3 +1 2 3 +``` + +## See also + +[``](ranges.md)\ +[`all` range adaptor](range-adaptors.md#all)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/packaged-task-class.md b/docs/standard-library/packaged-task-class.md index 10af973785..4c989a67dc 100644 --- a/docs/standard-library/packaged-task-class.md +++ b/docs/standard-library/packaged-task-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: packaged_task Class" title: "packaged_task Class" -ms.date: "11/04/2016" +ms.date: 06/17/2022 f1_keywords: ["future/std::packaged_task", "future/std::packaged_task::packaged_task", "future/std::packaged_task::get_future", "future/std::packaged_task::make_ready_at_thread_exit", "future/std::packaged_task::reset", "future/std::packaged_task::swap", "future/std::packaged_task::valid", "future/std::packaged_task::operator()", "future/std::packaged_task::operator bool"] ms.assetid: 0a72cbe3-f22a-4bfe-8e50-dcb268c98780 helpviewer_keywords: ["std::packaged_task [C++]", "std::packaged_task [C++], packaged_task", "std::packaged_task [C++], get_future", "std::packaged_task [C++], make_ready_at_thread_exit", "std::packaged_task [C++], reset", "std::packaged_task [C++], swap", "std::packaged_task [C++], valid"] +ms.custom: devdivchpfy22 --- + # packaged_task Class Describes an *asynchronous provider* that is a call wrapper whose call signature is `Ty(ArgTypes...)`. Its *associated asynchronous state* holds a copy of its callable object in addition to the potential result. @@ -33,7 +35,7 @@ class packaged_task; |[get_future](#get_future)|Returns a [future](../standard-library/future-class.md) object that has the same associated asynchronous state.| |[make_ready_at_thread_exit](#make_ready_at_thread_exit)|Calls the callable object that's stored in the associated asynchronous state and atomically stores the returned value.| |[reset](#reset)|Replaces the associated asynchronous state.| -|[swap](#swap)|Exchanges the associated asynchronous state with that of a specified object.| +|[swap](#swap)|Exchanges the associated asynchronous state with a specified object.| |[valid](#valid)|Specifies whether the object has an associated asynchronous state.| ### Public Operators @@ -60,7 +62,7 @@ future get_future(); ### Remarks -If the `packaged_task` object does not have an associated asynchronous state, this method throws a [future_error](../standard-library/future-error-class.md) that has an error code of `no_state`. +If the `packaged_task` object doesn't have an associated asynchronous state, this method throws a [future_error](../standard-library/future-error-class.md) that has an error code of `no_state`. If this method has already been called for a `packaged_task` object that has the same associated asynchronous state, the method throws a `future_error` that has an error code of `future_already_retrieved`. @@ -80,7 +82,7 @@ If this method or [make_ready_at_thread_exit](#make_ready_at_thread_exit) has al Otherwise, this operator calls `INVOKE(fn, args..., Ty)`, where *fn* is the callable object that's stored in the associated asynchronous state. Any returned value is stored atomically as the returned result of the associated asynchronous state. -In contrast to [packaged_task::operator()](#op_call), the associated asynchronous state is not set to `ready` until after all thread-local objects in the calling thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state are not unblocked until the calling thread exits. +In contrast to [packaged_task::operator()](#op_call), the associated asynchronous state isn't set to `ready` until after all thread-local objects in the calling thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state aren't unblocked until the calling thread exits. ## packaged_task::operator= @@ -177,7 +179,7 @@ Destroys a `packaged_task` object. ### Remarks -If the *associated asynchronous state* is not *ready*, the destructor stores a [future_error](../standard-library/future-error-class.md) exception that has an error code of `broken_promise` as the result in the associated asynchronous state, and any threads that are blocked on the associated asynchronous state become unblocked. +If the *associated asynchronous state* isn't *ready*, the destructor stores a [future_error](../standard-library/future-error-class.md) exception that has an error code of `broken_promise` as the result in the associated asynchronous state, and any threads that are blocked on the associated asynchronous state become unblocked. ## packaged_task::reset @@ -189,11 +191,11 @@ void reset(); ### Remarks -In effect, this method executes `*this = packaged_task(move(fn))`, where *fn* is the function object that's stored in the associated asynchronous state for this object. Therefore, the state of the object is cleared, and [get_future](#get_future), [operator()](#op_call), and [make_ready_at_thread_exit](#make_ready_at_thread_exit) can be called as if on a newly-constructed object. +In effect, this method executes `*this = packaged_task(move(fn))`, where *fn* is the function object that's stored in the associated asynchronous state for this object. Therefore, the state of the object is cleared, and [get_future](#get_future), [operator()](#op_call), and [make_ready_at_thread_exit](#make_ready_at_thread_exit) can be called as if on a newly constructed object. ## packaged_task::swap -Exchanges the associated asynchronous state with that of a specified object. +Exchanges the associated asynchronous state with a specified object. ```cpp void swap(packaged_task& Right) noexcept; diff --git a/docs/standard-library/parallel-policy-class.md b/docs/standard-library/parallel-policy-class.md index 1e5a6cd9cd..892f8f12a1 100644 --- a/docs/standard-library/parallel-policy-class.md +++ b/docs/standard-library/parallel-policy-class.md @@ -6,7 +6,7 @@ f1_keywords: ["execution/std::execution::parallel_policy"] --- # parallel_policy Class -Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized. +Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be parallelized. ## Syntax diff --git a/docs/standard-library/parallel-unsequenced-policy-class.md b/docs/standard-library/parallel-unsequenced-policy-class.md index 53ca538f2e..d9b3d3d14a 100644 --- a/docs/standard-library/parallel-unsequenced-policy-class.md +++ b/docs/standard-library/parallel-unsequenced-policy-class.md @@ -6,7 +6,7 @@ f1_keywords: ["execution/std::execution::parallel_unsequenced_policy"] --- # parallel_unsequenced_policy Class -Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized and vectorized. +Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be parallelized and vectorized. ## Syntax diff --git a/docs/standard-library/path-class.md b/docs/standard-library/path-class.md index ee34037fe6..6e5499a467 100644 --- a/docs/standard-library/path-class.md +++ b/docs/standard-library/path-class.md @@ -1,13 +1,13 @@ --- description: "Learn more about: path Class" title: "path Class" -ms.date: "09/27/2018" +ms.date: 06/17/2022 f1_keywords: ["filesystem/std::experimental::filesystem::path"] -ms.assetid: 8a1227ca-aeb2-4e0e-84aa-86e34e4f4fe8 --- -# path Class -The **path** class stores an object of type `string_type`, called `myname` here for the purposes of exposition, suitable for use as a pathname. `string_type` is a synonym for `basic_string`, where `value_type` is a synonym for **`wchar_t`** on Windows or **`char`** on POSIX. +# `path` Class + +The **`path`** class stores an object of type `string_type`, called `myname` here for the purposes of exposition, suitable for use as a pathname. `string_type` is a synonym for `basic_string`, where `value_type` is a synonym for **`wchar_t`** on Windows or **`char`** on POSIX. For more information, and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). @@ -21,82 +21,82 @@ class path; |Constructor|Description| |-|-| -|[path](#path)|Constructs a `path`.| +|[`path`](#path)|Constructs a `path`.| ### Typedefs |Type name|Description| |-|-| -|[const_iterator](#const_iterator)|A synonym for `iterator`.| -|[iterator](#iterator)|A bidirectional constant iterator that designates the `path` components of `myname`.| -|[string_type](#string_type)|The type is a synonym for `basic_string`.| +|[`const_iterator`](#const_iterator)|A synonym for `iterator`.| +|[`iterator`](#iterator)|A bidirectional constant iterator that designates the `path` components of `myname`.| +|[`string_type`](#string_type)|The type is a synonym for `basic_string`.| ### Member functions |Member function|Description| |-|-| -|[append](#append)|Appends the specified sequence to `mypath`, converted and inserting a preferred_separator as needed.| -|[assign](#assign)|Replaces `mypath` with the specified sequence, converted as needed.| -|[begin](#begin)|Returns a `path::iterator` designating the first path element in the pathname, if present.| -|[c_str](#c_str)|Returns a pointer to the first character in `mypath`.| -|[clear](#clear)|Executes `mypath.clear()`.| -|[compare](#compare)|Returns comparison values.| -|[concat](#compare)|Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed.| -|[empty](#empty)|Returns `mypath.empty()`.| -|[end](#end)|Returns an end-of-sequence iterator of type `iterator`.| -|[extension](#extension)|Returns the suffix of `filename()`.| -|[filename](#filename)|Returns the root directory component of myname, specifically `empty() ? path() : *--end()`. The component may be empty.| -|[generic_string](#generic_string)|Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash.| -|[generic_u16string](#generic_u16string)|Returns `u16string()` with (under Windows) any backslash converted to a forward slash.| -|[generic_u32string](#generic_u32string)|Returns `u32string()` with (under Windows) any backslash converted to a forward slash.| -|[generic_u8string](#generic_u8string)|Returns `u8string()` with (under Windows) any backslash converted to a forward slash.| -|[generic_wstring](#generic_wstring)|Returns `wstring()` with (under Windows) any backslash converted to a forward slash.| -|[has_extension](#has_extension)|Returns `!extension().empty()`.| -|[has_filename](#has_filename)|Returns `!filename().empty()`.| -|[has_parent_path](#has_parent_path)|Returns `!parent_path().empty()`.| -|[has_relative_path](#has_relative_path)|Returns `!relative_path().empty()`.| -|[has_root_directory](#has_root_directory)|Returns `!root_directory().empty()`.| -|[has_root_name](#has_root_name)|Returns `!root_name().empty()`.| -|[has_root_path](#has_root_path)|Returns `!root_path().empty()`.| -|[has_stem](#has_stem)|Returns `!stem().empty()`.| -|[is_absolute](#is_absolute)|For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`.| -|[is_relative](#is_relative)|Returns `!is_absolute()`.| -|[make_preferred](#make_preferred)|Converts each separator to a preferred_separator as needed.| -|[native](#native)|Returns `myname`.| -|[parent_path](#parent_path)|Returns the parent path component of `myname`.| -|[preferred_separator](#preferred_separator)|The constant object gives the preferred character for separating path components, depending on the host operating system. | -|[relative_path](#relative_path)|Returns the relative path component of `myname`. | -|[remove_filename](#remove_filename)|Removes the filename.| -|[replace_extension](#replace_extension)|Replaces the extension of `myname`. | -|[replace_filename](#replace_filename)|RReplaces the filename.| -|[root_directory](#root_directory)|Returns the root directory component of `myname`. | -|[root_name](#root_name)|Returns the root name component of `myname`. | -|[root_path](#root_path)|Returns the root path component of `myname`.| -|[stem](#stem)|Returns the `stem` component of `myname`.| -|[string](#string)|Converts the sequence stored in `mypath`.| -|[swap](#swap)|Executes `swap(mypath, right.mypath)`.| -|[u16string](#u16string)|Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an object of type `u16string`.| -|[u32string](#u32string)|Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an object of type `u32string`.| -|[u8string](#u8string)|Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an object of type `u8string`.| -|[value_type](#value_type)|The type describes the path elements favored by the host operating system.| -|[wstring](#wstring)|Converts the sequence stored in `mypath` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`.| +|[`append`](#append)|Appends the specified sequence to `mypath`, converted and inserting a preferred_separator as needed.| +|[`assign`](#assign)|Replaces `mypath` with the specified sequence, converted as needed.| +|[`begin`](#begin)|Returns a `path::iterator` designating the first path element in the pathname, if present.| +|[`c_str`](#c_str)|Returns a pointer to the first character in `mypath`.| +|[`clear`](#clear)|Executes `mypath.clear()`.| +|[`compare`](#compare)|Returns comparison values.| +|[`concat`](#compare)|Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed.| +|[`empty`](#empty)|Returns `mypath.empty()`.| +|[`end`](#end)|Returns an end-of-sequence iterator of type `iterator`.| +|[`extension`](#extension)|Returns the suffix of `filename()`.| +|[`filename`](#filename)|Returns the root directory component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty.| +|[`generic_string`](#generic_string)|Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash.| +|[`generic_u16string`](#generic_u16string)|Returns `u16string()` with (under Windows) any backslash converted to a forward slash.| +|[`generic_u32string`](#generic_u32string)|Returns `u32string()` with (under Windows) any backslash converted to a forward slash.| +|[`generic_u8string`](#generic_u8string)|Returns `u8string()` with (under Windows) any backslash converted to a forward slash.| +|[`generic_wstring`](#generic_wstring)|Returns `wstring()` with (under Windows) any backslash converted to a forward slash.| +|[`has_extension`](#has_extension)|Returns `!extension().empty()`.| +|[`has_filename`](#has_filename)|Returns `!filename().empty()`.| +|[`has_parent_path`](#has_parent_path)|Returns `!parent_path().empty()`.| +|[`has_relative_path`](#has_relative_path)|Returns `!relative_path().empty()`.| +|[`has_root_directory`](#has_root_directory)|Returns `!root_directory().empty()`.| +|[`has_root_name`](#has_root_name)|Returns `!root_name().empty()`.| +|[`has_root_path`](#has_root_path)|Returns `!root_path().empty()`.| +|[`has_stem`](#has_stem)|Returns `!stem().empty()`.| +|[`is_absolute`](#is_absolute)|For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`.| +|[`is_relative`](#is_relative)|Returns `!is_absolute()`.| +|[`make_preferred`](#make_preferred)|Converts each separator to a `preferred_separator` as needed.| +|[`native`](#native)|Returns the native representation of the path.| +|[`parent_path`](#parent_path)|Returns the parent path component of `myname`.| +|[`preferred_separator`](#preferred_separator)|The constant object gives the preferred character for separating path components, depending on the host operating system. | +|[`relative_path`](#relative_path)|Returns the relative path component of `myname`. | +|[`remove_filename`](#remove_filename)|Removes the filename.| +|[`replace_extension`](#replace_extension)|Replaces the extension of `myname`. | +|[`replace_filename`](#replace_filename)|Replaces the filename.| +|[`root_directory`](#root_directory)|Returns the root directory component of `myname`. | +|[`root_name`](#root_name)|Returns the root name component of `myname`. | +|[`root_path`](#root_path)|Returns the root path component of `myname`.| +|[`stem`](#stem)|Returns the `stem` component of `myname`.| +|[`string`](#string)|Converts the sequence stored in `mypath`.| +|[`swap`](#swap)|Executes `swap(mypath, right.mypath)`.| +|[`u16string`](#u16string)|Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an object of type `u16string`.| +|[`u32string`](#u32string)|Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an object of type `u32string`.| +|[`u8string`](#u8string)|Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an object of type `u8string`.| +|[`value_type`](#value_type)|The type describes the path elements favored by the host operating system.| +|[`wstring`](#wstring)|Converts the sequence stored in `mypath` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`.| ### Operators |Operator|Description| |-|-| -|[operator=](#op_as)|Replaces the elements of the path with a copy of another path.| -|[operator+=](#op_add)|Various `concat` expressions.| -|[operator/=](#op_divide)|Various `append` expressions.| -|[operator string_type](#op_string)|Returns `myname`.| +|[`operator=`](#op_as)|Replaces the elements of the path with a copy of another path.| +|[`operator+=`](#op_add)|Various `concat` expressions.| +|[`operator/=`](#op_divide)|Various `append` expressions.| +|[`operator string_type`](#op_string)|Returns `myname`.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std::experimental::filesystem +**Namespace:** `std::experimental::filesystem` -## path::append +## `path::append` Appends the specified sequence to `mypath`, converted and inserting a `preferred_separator` as needed. @@ -110,16 +110,16 @@ path& append(InIt first, InIt last); ### Parameters -*source*\ +*`source`*\ Specified sequence. -*first*\ +*`first`*\ Start of specified sequence. -*last*\ +*`last`*\ End of specified sequence. -## path::assign +## `path::assign` Replaces `mypath` with the specified sequence, converted as needed. @@ -133,16 +133,16 @@ path& assign(InIt first, InIt last); ### Parameters -*source*\ +*`source`*\ Specified sequence. -*first*\ +*`first`*\ Start of specified sequence. -*last*\ +*`last`*\ End of specified sequence. -## path::begin +## `path::begin` Returns a `path::iterator` designating the first path element in the pathname, if present. @@ -150,7 +150,7 @@ Returns a `path::iterator` designating the first path element in the pathname, i iterator begin() const; ``` -## path::c_str +## `path::c_str` Returns a pointer to the first character in `mypath`. @@ -158,7 +158,7 @@ Returns a pointer to the first character in `mypath`. const value_type& *c_str() const noexcept; ``` -## path::clear +## `path::clear` Executes `mypath.clear()`. @@ -166,7 +166,7 @@ Executes `mypath.clear()`. void clear() noexcept; ``` -## path::compare +## `path::compare` The first function returns `mypath.compare(pval.native())`. The second function returns `mypath.compare(str)`. The third function returns `mypath.compare(ptr)`. @@ -178,16 +178,16 @@ int compare(const value_type *ptr) const; ### Parameters -*pval*\ +*`pval`*\ Path to compare. -*str*\ +*`str`*\ String to compare. -*ptr*\ +*`ptr`*\ Pointer to compare. -## path::concat +## `path::concat` Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed. @@ -201,16 +201,16 @@ path& concat(InIt first, InIt last); ### Parameters -*source*\ +*`source`*\ Specified sequence. -*first*\ +*`first`*\ Start of specified sequence. -*last*\ +*`last`*\ End of specified sequence. -## path::const_iterator +## `path::const_iterator` A synonym for `iterator`. @@ -218,7 +218,7 @@ A synonym for `iterator`. typedef iterator const_iterator; ``` -## path::empty +## `path::empty` Returns `mypath.empty()`. @@ -226,7 +226,7 @@ Returns `mypath.empty()`. bool empty() const noexcept; ``` -## path::end +## `path::end` Returns an end-of-sequence iterator of type `iterator`. @@ -234,7 +234,7 @@ Returns an end-of-sequence iterator of type `iterator`. iterator end() const; ``` -## path::extension +## `path::extension` Returns the suffix of `filename()`. @@ -250,15 +250,15 @@ If `X == path(".") || X == path("..")` or if `X` contains no dot, the suffix is Otherwise, the suffix begins with (and includes) the rightmost dot. -## path::filename +## `path::filename` -Returns the root directory component of myname, specifically `empty() path() : *--end()`. The component may be empty. +Returns the root directory component of `myname`, specifically `empty() path() : *--end()`. The component may be empty. ```cpp path filename() const; ``` -## path::generic_string +## `path::generic_string` Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash. @@ -272,7 +272,7 @@ template path::generic_u16string +## `path::generic_u16string` Returns `u16string()` with (under Windows) any backslash converted to a forward slash. @@ -280,7 +280,7 @@ Returns `u16string()` with (under Windows) any backslash converted to a forward u16string generic_u16string() const; ``` -## path::generic_u32string +## `path::generic_u32string` Returns `u32string()` with (under Windows) any backslash converted to a forward slash. @@ -288,7 +288,7 @@ Returns `u32string()` with (under Windows) any backslash converted to a forward u32string generic_u32string() const; ``` -## path::generic_u8string +## `path::generic_u8string` Returns `u8string()` with (under Windows) any backslash converted to a forward slash. @@ -296,7 +296,7 @@ Returns `u8string()` with (under Windows) any backslash converted to a forward s string generic_u8string() const; ``` -## path::generic_wstring +## `path::generic_wstring` Returns `wstring()` with (under Windows) any backslash converted to a forward slash. @@ -304,7 +304,7 @@ Returns `wstring()` with (under Windows) any backslash converted to a forward sl wstring generic_wstring() const; ``` -## path::has_extension +## `path::has_extension` Returns `!extension().empty()`. @@ -312,7 +312,7 @@ Returns `!extension().empty()`. bool has_extension() const; ``` -## path::has_filename +## `path::has_filename` Returns `!filename().empty()`. @@ -320,7 +320,7 @@ Returns `!filename().empty()`. bool has_filename() const; ``` -## path::has_parent_path +## `path::has_parent_path` Returns `!parent_path().empty()`. @@ -328,7 +328,7 @@ Returns `!parent_path().empty()`. bool has_parent_path() const; ``` -## path::has_relative_path +## `path::has_relative_path` Returns `!relative_path().empty()`. @@ -336,7 +336,7 @@ Returns `!relative_path().empty()`. bool has_relative_path() const; ``` -## path::has_root_directory +## `path::has_root_directory` Returns `!root_directory().empty()`. @@ -344,7 +344,7 @@ Returns `!root_directory().empty()`. bool has_root_directory() const; ``` -## path::has_root_name +## `path::has_root_name` Returns `!root_name().empty()`. @@ -352,7 +352,7 @@ Returns `!root_name().empty()`. bool has_root_name() const; ``` -## path::has_root_path +## `path::has_root_path` Returns `!root_path().empty()`. @@ -360,7 +360,7 @@ Returns `!root_path().empty()`. bool has_root_path() const; ``` -## path::has_stem +## `path::has_stem` Returns `!stem().empty()`. @@ -368,7 +368,7 @@ Returns `!stem().empty()`. bool has_stem() const; ``` -## path::is_absolute +## `path::is_absolute` For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`. @@ -376,7 +376,7 @@ For Windows, the function returns `has_root_name() && has_root_directory()`. For bool is_absolute() const; ``` -## path::is_relative +## `path::is_relative` Returns `!is_absolute()`. @@ -384,7 +384,7 @@ Returns `!is_absolute()`. bool is_relative() const; ``` -## path::iterator +## `path::iterator` A bidirectional constant iterator that designates the path components of `myname`. @@ -415,7 +415,7 @@ For `pval` an object of type `path`: 1. `path::iterator X = pval.begin()` designates the first `path` element in the pathname, if present. -1. `X == pval.end()` is true when `X` points just past the end of the sequence of components. +1. `X == pval.end()` is `true` when `X` points just past the end of the sequence of components. 1. `*X` returns a string that matches the current component @@ -425,7 +425,7 @@ For `pval` an object of type `path`: 1. Altering `myname` invalidates all iterators designating elements in `myname`. -## path::make_preferred +## `path::make_preferred` Converts each separator to a `preferred_separator` as needed. @@ -433,15 +433,33 @@ Converts each separator to a `preferred_separator` as needed. path& make_preferred(); ``` -## path::native +## `path::native` -Returns `myname`. +Get the native string representation of the path. ```cpp const string_type& native() const noexcept; ``` -## path::operator= +### Remarks + +The path is available in a portable generic format (see [`generic_string()`](#generic_string)) or the native format of the path. This function returns the native string. On a POSIX system, the generic format and the native format are the same. + +In the following example running on Windows 11, the generic path string is `c:/t/temp/temp.txt` and the native string is `c:\\t\\temp.txt` + +```cpp +// Compile with /std:c++17 or higher +#include + +int main() +{ + std::filesystem::path p(R"(c:\t\temp.txt)"); + auto native = p.native(); // Windows: L"c:\\t\temp.txt" + auto generic = p.generic_string(); // Windows: "c:/t/temp.txt" +} +``` + +## `path::operator=` Replaces the elements of the path with a copy of another path. @@ -455,17 +473,17 @@ path& operator=(const Source& source); ### Parameters -*right*\ -The [path](../standard-library/path-class.md) being copied into the `path`. +*`right`*\ +The [`path`](../standard-library/path-class.md) being copied into the `path`. -*source*\ -The source path. +*`source`*\ +The source `path`. ### Remarks The first member operator copies `right.myname` to `myname`. The second member operator moves `right.myname` to `myname`. The third member operator behaves the same as `*this = path(source)`. -## path::operator+= +## `path::operator+=` Various `concat` expressions. @@ -484,19 +502,19 @@ path& operator+=(Elem elem); ### Parameters -*right*\ +*`right`*\ The added path. -*str*\ +*`str`*\ The added string. -*ptr*\ +*`ptr`*\ The added pointer. -*elem*\ +*`elem`*\ The added `value_type` or `Elem`. -*source*\ +*`source`*\ The added source. ### Remarks @@ -515,7 +533,7 @@ The member functions behave the same as the following corresponding expressions: 1. `concat(path(basic_string(1, elem)));` -## path::operator/= +## `path::operator/=` Various `append` expressions. @@ -528,10 +546,10 @@ path& operator/=(const Source& source); ### Parameters -*right*\ +*`right`*\ The added path. -*source*\ +*`source`*\ The added source. ### Remarks @@ -542,7 +560,7 @@ The member functions behave the same as the following corresponding expressions: 1. `append(source);` -## path::operator string_type +## `path::operator string_type` Returns `myname`. @@ -550,7 +568,7 @@ Returns `myname`. operator string_type() const; ``` -## path::parent_path +## `path::parent_path` Returns the parent path component of `myname`. @@ -560,9 +578,9 @@ path parent_path() const; ### Remarks -Returns the parent path component of `myname`, specifically the prefix of `myname` after removing `filename().native()` and any immediately preceding directory separators. (Equally, if `begin() != end()`, it is the combining of all elements in the range `[begin(), --end())` by successively applying `operator/=`.) The component may be empty. +Returns the parent path component of `myname`, specifically the prefix of `myname` after removing `filename().native()` and any immediately preceding directory separators. (Equally, if `begin() != end()`, it's the combining of all elements in the range `[begin(), --end())` by successively applying `operator/=`.) The component may be empty. -## path::path +## `path::path` Constructs a `path` in various ways. @@ -587,40 +605,40 @@ path(InIt first, InIt last, const locale& loc); ### Parameters -*right*\ +*`right`*\ The path of which the constructed path is to be a copy. -*source*\ +*`source`*\ The source of which the constructed path is to be a copy. -*loc*\ +*`loc`*\ The specified locale. -*first*\ +*`first`*\ The position of the first element to be copied. -*last*\ +*`last`*\ The position of the last element to be copied. ### Remarks The constructors all construct `myname` in various ways: -For `path()` it is `myname()`. +For `path()` it's `myname()`. -For `path(const path& right`) it is `myname(right.myname)`. +For `path(const path& right`) it's `myname(right.myname)`. -For `path(path&& right)` it is `myname(right.myname)`. +For `path(path&& right)` it's `myname(right.myname)`. -For `template path(const Source& source)` it is `myname(source)`. +For `template path(const Source& source)` it's `myname(source)`. -For `template path(const Source& source, const locale& loc)` it is `myname(source)`, obtaining any needed codecvt facets from `loc`. +For `template path(const Source& source, const locale& loc)` it's `myname(source)`, obtaining any needed `codecvt` facets from `loc`. -For `template path(InIt first, InIt last)` it is `myname(first, last)`. +For `template path(InIt first, InIt last)` it's `myname(first, last)`. -For `template path(InIt first, InIt last, const locale& loc)` it is `myname(first, last)`, obtaining any needed codecvt facets from `loc`. +For `template path(InIt first, InIt last, const locale& loc)` it's `myname(first, last)`, obtaining any needed `codecvt` facets from `loc`. -## path::preferred_separator +## `path::preferred_separator` The constant object gives the preferred character for separating path components, depending on the host operating system. @@ -634,9 +652,9 @@ static constexpr value_type preferred_separator == '/'; ### Remarks -Note that it is equally permissible in most contexts under Windows to use L'/' in its place. +It's equally permissible in most contexts under Windows to use `L'/'` in its place. -## path::relative_path +## `path::relative_path` Returns the relative path component of `myname`. @@ -648,7 +666,7 @@ path relative_path() const; Returns the relative path component of `myname`, specifically the suffix of `myname` after removing `root_path().native()` and any immediately subsequent redundant directory separators. The component may be empty. -## path::remove_filename +## `path::remove_filename` Removes the filename. @@ -656,7 +674,7 @@ Removes the filename. path& remove_filename(); ``` -## path::replace_extension +## `path::replace_extension` Replaces the extension of `myname`. @@ -666,14 +684,14 @@ path& replace_extension(const path& newext = path()); ### Parameters -*newext*\ +*`newext`*\ The new extension. ### Remarks -First removes the suffix `extension().native()` from `myname`. Then if `!newext.empty() && newext[0] != dot` (where `dot` is `*path(".").c_str()`), then `dot` is appended to `myname`. Then *newext* is appended to `myname`. +First removes the suffix `extension().native()` from `myname`. Then if `!newext.empty() && newext[0] != dot` (where *dot* is `*path(".").c_str()`), then *dot* is appended to `myname`. Then *`newext`* is appended to `myname`. -## path::replace_filename +## `path::replace_filename` Replaces the filename. @@ -683,7 +701,7 @@ path& replace_filename(const path& pval); ### Parameters -*pval*\ +*`pval`*\ The path of the filename. ### Remarks @@ -697,7 +715,7 @@ remove_filename(); return (*this); ``` -## path::root_directory +## `path::root_directory` Returns the root directory component of `myname`. @@ -709,7 +727,7 @@ path root_directory() const; The component may be empty. -## path::root_name +## `path::root_name` Returns the root name component of `myname`. @@ -721,7 +739,7 @@ path root_name() const; The component may be empty. -## path::root_path +## `path::root_path` Returns the root path component of `myname`. @@ -733,7 +751,7 @@ path root_path() const; Returns the root path component of `myname`, specifically `root_name()` / `root_directory`. The component may be empty. -## path::stem +## `path::stem` Returns the `stem` component of `myname`. @@ -745,7 +763,7 @@ path stem() const; Returns the `stem` component of `myname`, specifically `filename().native()` with any trailing `extension().native()` removed. The component may be empty. -## path::string +## `path::string` Converts the sequence stored in `mypath`. @@ -769,7 +787,7 @@ The first (template) member function converts the sequence stored in `mypath` th The second member function converts the sequence stored in `mypath` to the encoding favored by the host system for a **`char`** sequence and returns it stored in an object of type `string`. -## path::string_type +## `path::string_type` The type is a synonym for `basic_string`. @@ -777,7 +795,7 @@ The type is a synonym for `basic_string`. typedef basic_string string_type; ``` -## path::swap +## `path::swap` Executes `swap(mypath, right.mypath)`. @@ -785,7 +803,7 @@ Executes `swap(mypath, right.mypath)`. void swap(path& right) noexcept; ``` -## path::u16string +## `path::u16string` Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an object of type `u16string`. @@ -793,7 +811,7 @@ Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an o u16string u16string() const; ``` -## path::u32string +## `path::u32string` Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an object of type `u32string`. @@ -801,7 +819,7 @@ Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an o u32string u32string() const; ``` -## path::u8string +## `path::u8string` Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an object of type `u8string`. @@ -809,7 +827,7 @@ Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an ob string u8string() const; ``` -## path::value_type +## `path::value_type` The type describes the `path` elements favored by the host operating system. @@ -821,7 +839,7 @@ typedef char value_type; #endif // filesystem model now defined ``` -## path::wstring +## `path::wstring` Converts the sequence stored in `mypath` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`. diff --git a/docs/standard-library/plus-struct.md b/docs/standard-library/plus-struct.md index 0d6c8c3b36..2224d1cae1 100644 --- a/docs/standard-library/plus-struct.md +++ b/docs/standard-library/plus-struct.md @@ -24,7 +24,7 @@ template <> struct plus { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) + std::forward(Right)); }; ``` diff --git a/docs/standard-library/priority-queue-class.md b/docs/standard-library/priority-queue-class.md index c57b2f7f52..8e22659fb4 100644 --- a/docs/standard-library/priority-queue-class.md +++ b/docs/standard-library/priority-queue-class.md @@ -4,11 +4,10 @@ title: "priority_queue Class" ms.date: "11/04/2016" f1_keywords: ["queue/std::priority_queue::container_type", "queue/std::priority_queue::size_type", "queue/std::priority_queue::value_type", "queue/std::priority_queue::empty", "queue/std::priority_queue::pop", "queue/std::priority_queue::push", "queue/std::priority_queue::size", "queue/std::priority_queue::top"] helpviewer_keywords: ["std::priority_queue [C++], container_type", "std::priority_queue [C++], size_type", "std::priority_queue [C++], value_type", "std::priority_queue [C++], empty", "std::priority_queue [C++], pop", "std::priority_queue [C++], push", "std::priority_queue [C++], size", "std::priority_queue [C++], top"] -ms.assetid: 69fca9cc-a449-4be4-97b7-02ca5db9cbb2 --- -# priority_queue Class +# `priority_queue` Class -A template container adaptor class that provides a restriction of functionality limiting access to the top element of some underlying container type, which is always the largest or of the highest priority. New elements can be added to the priority_queue and the top element of the priority_queue can be inspected or removed. +A template container adaptor class that provides a restriction of functionality limiting access to the top element of some underlying container type, which is always the largest or of the highest priority. New elements can be added to the `priority_queue` and the top element of the `priority_queue` can be inspected or removed. ## Syntax @@ -19,64 +18,64 @@ class priority_queue ### Parameters -*Type*\ -The element data type to be stored in the priority_queue. +*`Type`*\ +The element data type to be stored in the `priority_queue`. -*Container*\ -The type of the underlying container used to implement the priority_queue. +*`Container`*\ +The type of the underlying container used to implement the `priority_queue`. -*Compare*\ -The type that provides a function object that can compare two element values as sort keys to determine their relative order in the priority_queue. This argument is optional and the binary predicate `less` is the default value. +*`Compare`*\ +The type that provides a function object that can compare two element values as sort keys to determine their relative order in the `priority_queue`. This argument is optional and the binary predicate `less` is the default value. ## Remarks -The elements of class `Type` stipulated in the first template parameter of a queue object are synonymous with [value_type](#value_type) and must match the type of element in the underlying container class `Container` stipulated by the second template parameter. The `Type` must be assignable, so that it is possible to copy objects of that type and to assign values to variables of that type. +The elements of class `Type` stipulated in the first template parameter of a queue object are synonymous with [`value_type`](#value_type) and must match the type of element in the underlying container class `Container` stipulated by the second template parameter. The `Type` must be assignable, so that it's possible to copy objects of that type and to assign values to variables of that type. -The priority_queue orders the sequence it controls by calling a stored function object of class `Traits`. In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. +The `priority_queue` orders the sequence it controls by calling a stored function object of class `Traits`. In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they're equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. -Suitable underlying container classes for priority_queue include [deque Class](../standard-library/deque-class.md) and the default [vector Class](../standard-library/vector-class.md) or any other sequence container that supports the operations of `front`, `push_back`, and `pop_back` and a random-access iterator. The underlying container class is encapsulated within the container adaptor, which exposes only the limited set of the sequence container member functions as a public interface. +Suitable underlying container classes for `priority_queue` include [`deque` Class](../standard-library/deque-class.md) and the default [`vector` Class](../standard-library/vector-class.md) or any other sequence container that supports the operations of `front`, `push_back`, and `pop_back` and a random-access iterator. The underlying container class is encapsulated within the container adaptor, which exposes only the limited set of the sequence container member functions as a public interface. Adding elements to and removing elements from a `priority_queue` both have logarithmic complexity. Accessing elements in a `priority_queue` has constant complexity. -There are three types of container adaptors defined by the C++ Standard Library: stack, queue, and priority_queue. Each restricts the functionality of some underlying container class to provide a precisely controlled interface to a standard data structure. +There are three types of container adaptors defined by the C++ Standard Library: `stack`, `queue`, and `priority_queue`. Each restricts the functionality of some underlying container class to provide a precisely controlled interface to a standard data structure. -- The [stack Class](../standard-library/stack-class.md) supports a last-in, first-out (LIFO) data structure. A good analogue to keep in mind would be a stack of plates. Elements (plates) may be inserted, inspected, or removed only from the top of the stack, which is the last element at the end of the base container. The restriction to accessing only the top element is the reason for using the stack class. +- The [`stack` Class](../standard-library/stack-class.md) supports a last-in, first-out (LIFO) data structure. A good analogue to keep in mind would be a stack of plates. Elements (plates) may be inserted, inspected, or removed only from the top of the stack, which is the last element at the end of the base container. The restriction to accessing only the top element is the reason for using the `stack` class. -- The [queue Class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. A good analogue to keep in mind would be people lining up for a bank teller. Elements (people) may be added to the back of the line and are removed from the front of the line. Both the front and the back of a line may be inspected. The restriction to accessing only the front and back elements in this way is the reason for using the queue class. +- The [`queue` Class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. A good analogue to keep in mind would be people lining up for a bank teller. Elements (people) may be added to the back of the line and are removed from the front of the line. Both the front and the back of a line may be inspected. The restriction to accessing only the front and back elements in this way is the reason for using the `queue` class. -- The priority_queue class orders its elements so that the largest element is always at the top position. It supports insertion of an element and the inspection and removal of the top element. A good analogue to keep in mind would be people lining up where they are arranged by age, height, or some other criterion. +- The `priority_queue` class orders its elements so that the largest element is always at the top position. It supports insertion of an element and the inspection and removal of the top element. A good analogue to keep in mind would be people lining up where they're arranged by age, height, or some other criterion. ### Constructors |Constructor|Description| |-|-| -|[priority_queue](#priority_queue)|Constructs a `priority_queue` that is empty or that is a copy of a range of a base container object or of other `priority_queue`.| +|[`priority_queue`](#priority_queue)|Constructs a `priority_queue` that is empty or that is a copy of a range of a base container object or of other `priority_queue`.| ### Typedefs |Type name|Description| |-|-| -|[container_type](#container_type)|A type that provides the base container to be adapted by a `priority_queue`.| -|[size_type](#size_type)|An unsigned integer type that can represent the number of elements in a `priority_queue`.| -|[value_type](#value_type)|A type that represents the type of object stored as an element in a `priority_queue`.| +|[`container_type`](#container_type)|A type that provides the base container to be adapted by a `priority_queue`.| +|[`size_type`](#size_type)|An unsigned integer type that can represent the number of elements in a `priority_queue`.| +|[`value_type`](#value_type)|A type that represents the type of object stored as an element in a `priority_queue`.| ### Member functions |Member function|Description| |-|-| -|[empty](#empty)|Tests if the `priority_queue` is empty.| -|[pop](#pop)|Removes the largest element of the `priority_queue` from the top position.| -|[push](#push)|Adds an element to the priority queue based on the priority of the element from operator<.| -|[size](#size)|Returns the number of elements in the `priority_queue`.| -|[top](#top)|Returns a const reference to the largest element at the top of the `priority_queue`.| +|[`empty`](#empty)|Tests if the `priority_queue` is empty.| +|[`pop`](#pop)|Removes the largest element of the `priority_queue` from the top position.| +|[`push`](#push)|Adds an element to the priority queue based on the priority of the element from `operator<`.| +|[`size`](#size)|Returns the number of elements in the `priority_queue`.| +|[`top`](#top)|Returns a const reference to the largest element at the top of the `priority_queue`.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## priority_queue::container_type +## `priority_queue::container_type` A type that provides the base container to be adapted. @@ -86,17 +85,17 @@ typedef Container container_type; ### Remarks -The type is a synonym for the template parameter `Container`. The C++ Standard Library sequence container class `deque` and the default class `vector` meet the requirements to be used as the base container for a priority_queue object. User-defined types satisfying the requirements may also be used. +The type is a synonym for the template parameter `Container`. The C++ Standard Library sequence container class `deque` and the default class `vector` meet the requirements to be used as the base container for a `priority_queue` object. User-defined types satisfying the requirements may also be used. -For more information on `Container`, see the Remarks section of the [priority_queue Class](../standard-library/priority-queue-class.md) topic. +For more information on `Container`, see the Remarks section of the [`priority_queue` Class](../standard-library/priority-queue-class.md) topic. ### Example -See the example for [priority_queue](#priority_queue) for an example of how to declare and use `container_type`. +See the example for [`priority_queue`](#priority_queue) for an example of how to declare and use `container_type`. -## priority_queue::empty +## `priority_queue::empty` -Tests if a priority_queue is empty. +Tests if a `priority_queue` is empty. ```cpp bool empty() const; @@ -104,7 +103,7 @@ bool empty() const; ### Return Value -**`true`** if the priority_queue is empty; **`false`** if the priority_queue is nonempty. +**`true`** if the `priority_queue` is empty; **`false`** if the `priority_queue` is nonempty. ### Example @@ -140,9 +139,9 @@ The priority_queue q1 is not empty. The priority_queue s2 is empty. ``` -## priority_queue::pop +## `priority_queue::pop` -Removes the largest element of the priority_queue from the top position. +Removes the largest element of the `priority_queue` from the top position. ```cpp void pop(); @@ -150,7 +149,7 @@ void pop(); ### Remarks -The priority_queue must be nonempty to apply the member function. The top of the priority_queue is always occupied by the largest element in the container. +The `priority_queue` must be nonempty to apply the member function. The top of the `priority_queue` is always occupied by the largest element in the container. ### Example @@ -196,9 +195,9 @@ After a pop, the priority_queue length is 2. After a pop, the element at the top of the priority_queue is 20. ``` -## priority_queue::priority_queue +## `priority_queue::priority_queue` -Constructs a priority_queue that is empty or that is a copy of a range of a base container object or of another priority_queue. +Constructs a `priority_queue` that is empty or that is a copy of a range of a base container object or of another `priority_queue`. ```cpp priority_queue(); @@ -221,28 +220,28 @@ priority_queue(InputIterator first, InputIterator last, const Traits& _comp, con ### Parameters -*_comp*\ -The comparison function of type **constTraits** used to order the elements in the priority_queue, which defaults to compare function of the base container. +*`_comp`*\ +The comparison function of type **`constTraits`** used to order the elements in the `priority_queue`, which defaults to compare function of the base container. -*_Cont*\ -The base container of which the constructed priority_queue is to be a copy. +*`_Cont`*\ +The base container of which the constructed `priority_queue` is to be a copy. -*right*\ -The priority_queue of which the constructed set is to be a copy. +*`right`*\ +The `priority_queue` of which the constructed set is to be a copy. -*first*\ +*`first`*\ The position of the first element in the range of elements to be copied. -*last*\ +*`last`*\ The position of the first element beyond the range of elements to be copied. ### Remarks -Each of the first three constructors specifies an empty initial priority_queue, the second also specifying the type of comparison function (`comp`) to be used in establishing the order of the elements and the third explicitly specifying the `container_type` (`_Cont`) to be used. The keyword **`explicit`** suppresses certain kinds of automatic type conversion. +Each of the first three constructors specifies an empty initial `priority_queue`, the second also specifying the type of comparison function (`comp`) to be used in establishing the order of the elements and the third explicitly specifying the `container_type` (`_Cont`) to be used. The keyword **`explicit`** suppresses certain kinds of automatic type conversion. -The fourth constructor specifies a copy of the priority_queue *right*. +The fourth constructor specifies a copy of the `priority_queue right`. -The last three constructors copy the range \[*first*, *last*) of some container and use the values to initialize a priority_queue with increasing explicitness in specifying the type of comparison function of class `Traits` and `container_type`. +The last three constructors copy the range `[first, last)` of some container and use the values to initialize a `priority_queue` with increasing explicitness in specifying the type of comparison function of class `Traits` and `container_type`. ### Example @@ -355,9 +354,9 @@ int main( ) } ``` -## priority_queue::push +## `priority_queue::push` -Adds an element to the priority queue based on the priority of the element from operator<. +Adds an element to the priority queue based on the priority of the element from `operator<`. ```cpp void push(const Type& val); @@ -365,12 +364,12 @@ void push(const Type& val); ### Parameters -*val*\ -The element added to the top of the priority_queue. +*`val`*\ +The element added to the top of the `priority_queue`. ### Remarks -The top of the priority_queue is the position occupied by the largest element in the container. +The top of the `priority_queue` is the position occupied by the largest element in the container. ### Example @@ -404,9 +403,9 @@ The priority_queue length is 3. The element at the top of the priority_queue is 30. ``` -## priority_queue::size +## `priority_queue::size` -Returns the number of elements in the priority_queue. +Returns the number of elements in the `priority_queue`. ```cpp size_type size() const; @@ -414,7 +413,7 @@ size_type size() const; ### Return Value -The current length of the priority_queue. +The current length of the `priority_queue`. ### Example @@ -445,9 +444,9 @@ The priority_queue length is 1. The priority_queue length is now 2. ``` -## priority_queue::size_type +## `priority_queue::size_type` -An unsigned integer type that can represent the number of elements in a priority_queue. +An unsigned integer type that can represent the number of elements in a `priority_queue`. ```cpp typedef typename Container::size_type size_type; @@ -455,15 +454,15 @@ typedef typename Container::size_type size_type; ### Remarks -The type is a synonym for the `size_type` of the base container adapted by the priority_queue. +The type is a synonym for the `size_type` of the base container adapted by the `priority_queue`. ### Example -See the example for [size](#size) for an example of how to declare and use `size_type`. +See the example for [`size`](#size) for an example of how to declare and use `size_type`. -## priority_queue::top +## `priority_queue::top` -Returns a const reference to the largest element at the top of the priority_queue. +Returns a const reference to the largest element at the top of the `priority_queue`. ```cpp const_reference top() const; @@ -471,11 +470,11 @@ const_reference top() const; ### Return Value -A reference to the largest element, as determined by the `Traits` function, object of the priority_queue. +A reference to the largest element, as determined by the `Traits` function, object of the `priority_queue`. ### Remarks -The priority_queue must be nonempty to apply the member function. +The `priority_queue` must be nonempty to apply the member function. ### Example @@ -509,9 +508,9 @@ The priority_queue length is 3. The element at the top of the priority_queue is 30. ``` -## priority_queue::value_type +## `priority_queue::value_type` -A type that represents the type of object stored as an element in a priority_queue. +A type that represents the type of object stored as an element in a `priority_queue`. ```cpp typedef typename Container::value_type value_type; @@ -519,7 +518,7 @@ typedef typename Container::value_type value_type; ### Remarks -The type is a synonym for the `value_type` of the base container adapted by the priority_queue. +The type is a synonym for the `value_type` of the base container adapted by the `priority_queue`. ### Example diff --git a/docs/standard-library/promise-class.md b/docs/standard-library/promise-class.md index 79b78942f9..1d8b2c7b97 100644 --- a/docs/standard-library/promise-class.md +++ b/docs/standard-library/promise-class.md @@ -1,10 +1,11 @@ --- description: "Learn more about: promise Class" title: "promise Class" -ms.date: "10/18/2018" +ms.date: 06/17/2022 f1_keywords: ["future/std::promise", "future/std::promise::promise", "future/std::promise::get_future", "future/std::promise::set_exception", "future/std::promise::set_exception_at_thread_exit", "future/std::promise::set_value", "future/std::promise::set_value_at_thread_exit", "future/std::promise::swap"] ms.assetid: 2931558c-d94a-4ba1-ac4f-20bf7b6e23f9 helpviewer_keywords: ["std::promise [C++]", "std::promise [C++], promise", "std::promise [C++], get_future", "std::promise [C++], set_exception", "std::promise [C++], set_exception_at_thread_exit", "std::promise [C++], set_value", "std::promise [C++], set_value_at_thread_exit", "std::promise [C++], swap"] +ms.custom: devdivchpfy22 --- # promise Class @@ -101,7 +102,7 @@ promise(promise&& Other) noexcept; ### Parameters *Al*\ -A memory allocator. See [\](../standard-library/allocators-header.md) for more information. +A memory allocator. For more information about allocators, see [\](../standard-library/allocators-header.md). *Other*\ A `promise` object. @@ -154,7 +155,7 @@ If the promise object has no *associated asynchronous state*, this method throws If [set_exception](#set_exception), `set_exception_at_thread_exit`, [set_value](#set_value), or [set_value_at_thread_exit](#set_value_at_thread_exit) has already been called for a `promise` object that has the same associated asynchronous state, this method throws a `future_error` that has an error code of `promise_already_satisfied`. -In contrast to [set_exception](#set_exception), this method does not set the associated asynchronous state to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state are not unblocked until the current thread exits. +In contrast to [set_exception](#set_exception), this method doesn't set the associated asynchronous state to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state aren't unblocked until the current thread exits. ## promise::set_value @@ -180,9 +181,9 @@ If [set_exception](#set_exception), [set_exception_at_thread_exit](#set_exceptio As a result of this method, any threads that are blocked on the associated asynchronous state become unblocked. -The first method also throws any exception that is thrown when *Val* is copied into the associated asynchronous state. In this situation, the associated asynchronous state is not set to ready. +The first method also throws any exception that is thrown when *Val* is copied into the associated asynchronous state. In this situation, the associated asynchronous state isn't set to ready. -The second method also throws any exception that is thrown when *Val* is moved into the associated asynchronous state. In this situation, the associated asynchronous state is not set to ready. +The second method also throws any exception that is thrown when *Val* is moved into the associated asynchronous state. In this situation, the associated asynchronous state isn't set to ready. For the partial specialization `promise`, the stored value is in effect a reference to *Val*. @@ -210,7 +211,7 @@ If the promise object has no *associated asynchronous state*, this method throws If [set_exception](#set_exception), [set_exception_at_thread_exit](#set_exception_at_thread_exit), [set_value](#set_value), or `set_value_at_thread_exit` has already been called for a `promise` object that has the same associated asynchronous state, this method throws a `future_error` that has an error code of `promise_already_satisfied`. -In contrast to `set_value`, the associated asynchronous state is not set to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state are not unblocked until the current thread exits. +In contrast to `set_value`, the associated asynchronous state isn't set to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state aren't unblocked until the current thread exits. The first method also throws any exception that is thrown when *Val* is copied into the associated asynchronous state. diff --git a/docs/standard-library/queue-operators.md b/docs/standard-library/queue-operators.md index 51f688e876..9f4929c4a9 100644 --- a/docs/standard-library/queue-operators.md +++ b/docs/standard-library/queue-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" +description: "Learn more about: operators" ms.date: "11/04/2016" f1_keywords: ["queue/std::operator!=", "queue/std::operator>", "queue/std::operator>=", "queue/std::operator<", "queue/std::operator<=", "queue/std::operator=="] -ms.assetid: 7c435b48-175c-45b0-88eb-24561044019c helpviewer_keywords: ["std::operator!= (queue)", "std::operator> (queue)", "std::operator>= (queue)", "std::operator< (queue)", "std::operator<= (queue)", "std::operator== (queue)"] --- # `` operators @@ -13,7 +12,7 @@ helpviewer_keywords: ["std::operator!= (queue)", "std::operator> (queue)", "std: Tests if the queue object on the left side of the operator is not equal to the queue object on the right side. ```cpp -bool operator!=(const queue & left, const queue & right,); +bool operator!=(const queue & left, const queue & right); ``` ### Parameters @@ -80,7 +79,7 @@ The queues q1 and q3 are equal. Tests if the queue object on the left side of the operator is less than the queue object on the right side. ```cpp -bool operator<(const queue & left, const queue & right,); +bool operator<(const queue & left, const queue & right); ``` ### Parameters @@ -143,7 +142,7 @@ The queue q1 is not less than the queue q3. Tests if the queue object on the left side of the operator is less than or equal to the queue object on the right side. ```cpp -bool operator<=(const queue & left, const queue & right,); +bool operator<=(const queue & left, const queue & right); ``` ### Parameters @@ -208,7 +207,7 @@ The queue q1 is less than or equal to the queue q3. Tests if the queue object on the left side of the operator is equal to queue object on the right side. ```cpp -bool operator==(const queue & left, const queue & right,); +bool operator==(const queue & left, const queue & right); ``` ### Parameters @@ -274,7 +273,7 @@ The queues q1 and q3 are equal. Tests if the queue object on the left side of the operator is greater than the queue object on the right side. ```cpp -bool operator>(const queue & left, const queue & right,); +bool operator>(const queue & left, const queue & right); ``` ### Parameters @@ -340,7 +339,7 @@ The queue q1 is greater than the queue q3. Tests if the queue object on the left side of the operator is greater than or equal to the queue object on the right side. ```cpp -bool operator>=(const queue & left, const queue & right,); +bool operator>=(const queue & left, const queue & right); ``` ### Parameters diff --git a/docs/standard-library/random.md b/docs/standard-library/random.md index 52724b3986..11b4b91e2b 100644 --- a/docs/standard-library/random.md +++ b/docs/standard-library/random.md @@ -45,7 +45,7 @@ Here are some tips to keep in mind when using ``: - The most useful pairing for most applications is the `mt19937` engine with `uniform_int_distribution`, as shown in the [code example](#code) later in this article. -There are many options to choose from in the `` header, and any of them is preferable to the outdated C Runtime function `rand()`. For information about what's wrong with `rand()` and how `` addresses these shortcomings, see [this video](https://go.microsoft.com/fwlink/p/?linkid=397615). +There are many options to choose from in the `` header, and any of them is preferable to the outdated C Runtime function `rand()`. For information about what's wrong with `rand()` and how `` addresses these shortcomings, see [this video](/events/goingnative-2013/rand-considered-harmful). ## Examples diff --git a/docs/standard-library/range-adaptors.md b/docs/standard-library/range-adaptors.md new file mode 100644 index 0000000000..7fca2c03e4 --- /dev/null +++ b/docs/standard-library/range-adaptors.md @@ -0,0 +1,1509 @@ +--- +title: "Range adaptors" +description: "Learn more about range adaptors, which create views on ranges." +ms.date: 11/3/2022 +f1_keywords: ["ranges/std::all", "ranges/std::all_t", "ranges/std::common", "ranges/std::counted", "ranges/std::drop", "ranges/std::drop_while", "ranges/std::elements", "ranges/std::empty", "ranges/std::filter", "ranges/std::iota", "ranges/std::istream", "ranges/std::join", "ranges/std::keys", "ranges/std::lazy_split", "ranges/std::reverse", "ranges/std::single", "ranges/std::split", "ranges/std::subrange", "ranges/std::take", "ranges/std::take_while", "ranges/std::transform", "ranges/std::values"] +helpviewer_keywords: ["std::ranges [C++], all", "std::ranges [C++], all_t", "std::ranges [C++], common", "std::ranges [C++], counted", "std::ranges [C++], drop", "std::ranges [C++], drop_while", "std::ranges [C++], elements", "std::ranges [C++], empty", "std::ranges [C++], filter", "std::ranges [C++], iota", "std::ranges [C++], istream", "std::ranges [C++], join", "std::ranges [C++], keys", "std::ranges [C++], lazy_split", "std::ranges [C++], reverse", "std::ranges [C++], single", "std::ranges [C++], split", "std::ranges [C++], subrange", "std::ranges [C++], take", "std::ranges [C++], take_while", "std::ranges [C++], transform", "std::ranges [C++], values"] +--- +# Range adaptors + +Range adaptors create a *view* (one of the [View classes](view-classes.md) in the `std::views` namespace) from a range. We recommend that you use an adaptor to create views instead of creating the view types directly. The adaptors are the intended way to access views. They're easier to use, and in some cases more efficient, than creating instances of the view types directly. + +A view is a lightweight object that refers to elements from a range. A view can: + +- Consist of only certain elements from a range. +- Represent a transformation of elements from a range. +- Be the reverse of, or only the first `n` elements of, a range. +- Be a combination of the preceding things. + +A view is cheap, `O(1)`, to copy, assign, and destroy--no matter how many elements are involved. Consider the following example: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto divisible_by_three = [](const int n) {return n % 3 == 0;}; + auto square = [](const int n) {return n * n;}; + + auto x = input | std::views::filter(divisible_by_three) + | std::views::transform(square); + + for (int i : x) + { + std::cout << i << ' '; + } +} +``` + +```output +0 9 36 81 +``` + +The first range adaptor, [`filter`](filter-view-class.md), provides a view that contains the elements from `input` that are divisible by three. The other range adaptor, [`transform`](transform-view-class.md), takes the view that contains the elements divisible by three and provides a view of the square of those elements. + +When a range adaptor produces a view, it doesn't incur the cost of transforming every element in the range to produce that view. The cost to process an element in the view is paid only when you access that element. + +Creating a view is preparation to do work in the future. In the previous example, creating the view doesn't result in finding all the elements divisible by three or squaring those elements. Work happens only when you access an element in the view. + +Elements of a view are usually the actual elements of the range used to create the view. The view usually doesn't own the elements; it just refers to them, with the exception of [`owning_view`](owning-view-class.md). Changing an element changes that element in the range that the view was created from. The following example shows this behavior: + +```cpp +#include +#include +#include + +int main() +{ + int input[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto even = [](const int n) { return n % 2 == 0; }; + auto x = input | std::views::filter(even); // create a view of the even elements from input + + for (int &i : x) + { + std::cout << i << ' '; // 0 2 4 6 8 10 + } + std::cout << '\n'; + + std::ranges::fill(x, 42); // changes the evens from input[] to 42 + for (int &i : input) // demonstrates that the even elements in the range are modified + { + std::cout << i << ' '; // // 42 1 42 3 42 5 42 7 42 9 42 + } +} +``` + +Range adaptors come in many forms. For example, there are range adaptors that allow you to produce a view by: + +- Filtering another range based on a predicate ([`filter`](filter-view-class.md)). +- Transforming the elements in a range ([`transform`](transform-view-class.md)). +- Splitting a range ([`split`](split-view-class.md)). + +Range adaptors can be chained together (composed). That's where the power and flexibility of ranges are most apparent. Composing range adaptors allows you to overcome a core problem with the previous Standard Template Library (STL) algorithms, which is that they aren't easy to chain together. + +The following range adaptors are available in the `std::views` namespace. The `std::views` namespace is a convenience alias for `std::ranges::views`. + +| Range adaptor | Description | +|--|--| +| [`all`](#all)C++20 | Create a view that refers to a range and its elements. | +| [`common`](#common)C++20 | Create a view that has the same iterator and sentinel types from a range that doesn't. | +| [`counted`](#counted)C++20 | Create a view of the first *n* elements of a range, starting from the specified location. | +| [`drop`](#drop)C++20 | Create a view from another view, skipping the specified number of elements from the front. | +| [`drop_while`](#drop_while)C++20 | Create a view that contains the elements of a range that remain after the leading elements that match the specified condition are dropped. | +| [`elements`](#elements)C++20 | Create a view of the selected index into each tuple-like value in a range. | +| [`empty`](#empty)C++20 | Create a view that has no elements. | +| [`filter`](#filter)C++20 | Create a view that contains the elements of a range that match the specified condition. | +| [`iota`](#iota)C++20 | Create a view that contains a sequence of increasing values. | +| [`istream`](#istream)C++20 | Create a view over the elements of a stream. | +| [`join`](#join)C++20 | Create a view that combines all the elements of multiple ranges into a single view. | +| [`keys`](#keys)C++20 | Create a view of the first index into each tuple-like value in a collection. | +| [`lazy_split`](#lazy_split)C++20 | Split a view into subranges based on a delimiter. | +| [`reverse`](#reverse)C++20 | Create a view of the elements of a range in reverse order. | +| [`single`](#single)C++20 | Create a view that contains one element. | +| [`split`](#split)C++20 | Split a view into subranges based on a delimiter. | +| [`take`](#take)C++20 | Create a view of the first *n* elements from another view. | +| [`take_while`](#take_while)C++20 | Create a view that contains the leading elements of a range that match the specified condition. | +| [`transform`](#transform)C++20 | Create a view of transformed elements from another view. | +| [`values`](#values)C++20 | Create a view of the second index into each tuple-like value in a collection. | + +In the previous table, a range adaptor is typically described as taking a range and producing a view. To be precise, range adaptors have a range argument that accepts one of the following: + +- The `cv-unqualified` type models [`view`](range-concepts.md#view), and the argument is an rvalue or is copyable. +- When you pass the argument as an lvalue, it must model [`range`](range-concepts.md#range) and live as long as the view. +- When you pass the argument as an rvalue, such as when calling [`owning_view`](owning-view-class.md), it must model `range` and `movable`. + +Range adaptor functions are typically [function objects](https://eel.is/c++draft/function.objects), which look like function calls and enforce constraints on the types that can be passed. + +You can pass range adaptors and the result of pipe operations (`|`) to code that expects function objects. In the following example, the view that the `split` range adaptor creates is passed to the `transform` range adaptor as if by a function call, because the `transform` range adaptor is a function object. + +```cpp +std::map x = {{0, "Hello, world"}, {42, "Goodbye, world"}}; +auto y = x | views::values | views::transform(views::split(' ')); +// y is a range whose elements are ranges of whitespace-delimited strings from each value in x: +// {{"Hello", "world"}, {"Goodbye", "world"}} +``` + +## `all` + +Create a view of all the elements in a range. + +```cpp +template +constexpr ranges::view auto all(R&& rg) const noexcept; +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +- If `rg` is already a view, a copy of `rg`. +- If `rg` is a non-view lvalue, a [`ref_view`](ref-view-class.md) that refers to `rg`. (The lifetime of the view is tied to the lifetime of `rg`.) +- If `rg` is a non-view rvalue such as a temporary object, or is the result of passing the range to `std::move`, an [`owning_view`](owning-view-class.md). + +Use `std::views::all_t` to get the type of the returned view. + +### Remarks + +This range adaptor is the best way to convert a range into a view. One reason to create a view from a range is to pass it by value at low cost, if passing the range by value could be expensive. + +Getting a view for a range is a useful alternative to passing a heavyweight range by value because views are inexpensive to create, copy, and destroy. A possible exception is `owning_view`, which is a view that owns the underlying range. + +In general, the worst-case scenario for destroying a view has `O(N)` complexity for the number of elements in the range. Even if you destroy `K` copies of view with `N` elements, the total complexity is still `O(N)` because the underlying range is destroyed only once. + +### Example: `all` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myRefView = std::views::all(v); // create a ref_view of the vector + std::cout << myRefView.size() << '\n'; // 10 + + auto myOwningView = std::views::all(std::move(v)); // create an owning_view from a moved vector + std::cout << myRefView.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << v.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << myOwningView.size(); // 10 +} +``` + +```output +10 +0 +0 +10 +``` + +## `common` + +Create a view that has the same begin iterator and sentinel type from a range that might not. + +```cpp +template +constexpr ranges::view auto common(R&& rg) const noexcept; +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +- `views::all(rg)` if `rg` is a range with the same iterator and sentinel type. +- [`common_view(views::all(rg))`](common-view-class.md) if `rg` has different iterator and sentinel types. + +### Remarks + +When an API requires the begin iterator and end sentinel to have the same type, and the view that you're using doesn't meet that requirement (or you don't know if it does), use this range adaptor to create a `common_view`. It guarantees that the type of the begin iterator and the type of the end sentinel are the same. + +### Example: `common` + +```cpp +// requires /std:c++20 or higher +#include +#include +#include +#include + +int main() +{ + std::list lst{1, 2, 3, 4, 5, 6, 7, 8, 9}; + + auto firstFive = std::views::take(lst, 5); + // firstFive.begin(), firstFive.end() have different types: counted_iterator versus default_sentinel + // auto r = std::accumulate(firstFive.begin(), firstFive.end(), 0); // Error: accumulate() requires firstFive.begin() and firstFive.end() types to be the same. + + auto common = std::views::common(firstFive); // create a common_view that has the same begin/end iterator types + std::cout << std::accumulate(common.begin(), common.end(), 0); // Now you can call the API because the iterator types are the same. Outputs 15 (1+2+3+4+5) +} +``` + +```output +15 +``` + +## `counted` + +Create a view of the first `count` elements of a range, starting from the specified location. + +```cpp +template +constexpr auto counted(Iterator&& it, iter_difference_t count); +``` + +### Parameters + +`DifferenceType`\ +The type of the count. + +`Iterator`\ +The type of the iterator. + +`count`\ +The number of elements to include in the view. Must be non-negative. + +- If `count == 0`, an empty [`span`](span-class.md) is returned. +- If `count` is greater than the number of elements in the range, the behavior is undefined. + +`it`\ +An iterator to the element in the range to start with. The element that the iterator points to is included in the created view. + +### Return value + +A [`span`](span-class.md) is returned if `it` is a [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator) for arrays, vectors, and other containers that store their elements contiguously. Otherwise, a [`subrange`](subrange-class.md) is returned. + +### Remarks + +The included elements are `[it, count)`. + +After the view is created, the number of elements in the view stays the same, even if the range that it was created from changes. However, if the underlying range changes, accessing elements from the view might result in undefined behavior. + +### Example: `counted` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto pos5 = std::ranges::find(v, 5); + auto countedView = std::views::counted(pos5, 5); + for (auto e : countedView) // outputs 5 6 7 8 9 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // You can pass the range directly if it supports input_or_output_iterator, in which case + // the count starts from the first element + const char chars[] = { 'H','i',' ','t','h','e','r','e' }; + for (char c : std::views::counted(chars, 2)) + { + std::cout << c; // outputs Hi + } +} +``` + +```output +5 6 7 8 9 +Hi +``` + +## `drop` + +Create a view that excludes the first *n* elements of a range. + +```cpp +1) template +constexpr ranges::view auto drop(R&& rg, ranges::range_difference_t count); + +2) template +constexpr /* range closure object */ drop(DifferenceType&& count); +``` + +### Parameters + +`DifferenceType`\ +The type that describes the number of elements to skip. + +`count`\ +The number of elements to drop from the front of `rg`. Must be non-negative. +- If `count == 0`, all the elements in `rg` are returned. +- If `count` is greater than the number of elements in `rg`, an empty view is returned. + +`R`\ +The type of the range. + +`rg`\ +The range that's used to create the view. + +### Return value + +A view of the underlying range, with the specified number of elements dropped from the front. + +If you specify more elements to drop than exist in the underlying range, an [`empty_view`](empty-view-class.md) is returned. + +The returned view is typically, but not always, a specialization of [`drop_view`](drop-view-class.md). That is: + +- If `V` is a specialization of [`empty_view`](empty-view-class.md), or is a specialization of [`span`](span-class.md), [`basic_string_view`](basic-string-view-class.md), [`iota_view`](iota-view-class.md), or [`subrange`](subrange-class.md) that is both [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range), the result is a specialization of `V`. +- Otherwise, the result is a [`drop_view`](drop-view-class.md). + +### Remarks + +After it's created, the number of elements in the view stays the same even if the view that it was created from changes. However, if the underlying view changes, accessing elements in the returned view might result in undefined behavior. + +`drop` is the opposite of [`take`](#take). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | drop(5)`. Or it can be used with function call syntax: `drop(collection, 5)` or `drop(5)(collection)`. + +### Example: `drop` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + auto newView = std::views::drop(v, 3); + for (auto e : newView) // 4 5 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + auto numbers = std::views::iota(0) | std::views::take(10); // build a view of 10 integers + auto latterHalf = numbers | std::views::drop(5); + for (auto i : latterHalf) + { + std::cout << i << ' '; // 5 6 7 8 9 + } +} +``` + +```output +4 5 +5 6 7 8 9 +``` + +## `drop_while` + +Create a view that contains the elements of a range that remain after the leading elements that match the specified condition are dropped. + +```cpp +1) template +constexpr ranges::view auto drop_while(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ drop_while(P&& predicate); +``` + +### Parameters + +`R`\ +The type of the range. + +`predicate`\ +The conditions that determine which leading elements to drop from the range. + +`rg`\ +The underlying range to create the view from. + +### Return value + +A [`drop_while_view`](drop-while-view-class.md) that consists of the elements that remain when the leading elements that match the predicate are dropped. + +### Remarks + +Stops dropping elements from `rg` as soon as the predicate returns `false`. + +`drop_while` is the opposite of [`take_while`](#take_while). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | drop_while(predicate)`. Or it can be used with function call syntax: `drop_while(collection, predicate)` or `drop_while(predicate)(collection)`. + +### Example: `drop_while` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::drop_while( + v, + [](int i) {return i >= 0; }); + print(myView); // -4 5 6 + + auto myView2 = v | std::views::drop_while( + [](int i) {return i < 5; }); + print(myView2); // 5 6 +} +``` + +```output +-4 5 6 +5 6 +``` + +## `elements` + +Create an [`elements_view`](elements-view-class.md), which is a view of the selected index into each tuple-like value in a range. For example, given a range of `std::tuple` values, create an `elements_view` of all the `string` elements from each tuple. + +```cpp +template +constexpr ranges::view auto elements(R&& rg); +``` + +### Parameters + +`N`\ +The index of the element to select from each tuple-like value to include in the view. + +`R`\ +The type of the underlying range. + +`rg`\ +The range of tuple-like values to create the view from. + +### Return value + +An [`elements_view`](elements-view-class.md) that consists of the selected index into each tuple-like value in a collection. + +### Example: `elements` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Create an elements_view of all the string elements from each tuple + for (int const year : std::views::elements<1>(cpp_standards)) + { + std::cout << year << ' '; // 2003 2011 2014 2017 1998 2020 + } + std::cout << '\n'; + + // Another way, using |: create an elements_view of all the int elements from each tuple + for (auto&& name : cpp_standards | std::views::elements<0>) + { + std::cout << name << ' '; // C++03 C++11 C++14 C++17 C++98 c++20 + } +} +``` + +```output +2003 2011 2014 2017 1998 2020 +C++03 C++11 C++14 C++17 C++98 c++20 +``` + +## `empty` + +Create an `empty_view`, which is a view that has no elements. + +```cpp +template +inline constexpr empty_view empty{}; +``` + +### Parameters + +`T`\ +The type of the elements in the view. The view needs an element type, even though there are no elements. + +### Return value + +An [`empty_view`](empty-view-class.md). + +### Remarks + +An `empty_view` can be useful when you're calling code that requires a view but doesn't need to process any of its elements. + +### Example: `empty` + +```cpp +// requires /std:c++20 or higher +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + bool isNotEmpty = (bool)anEmptyView; + std::cout << boolalpha << isNotEmpty << "\n"; // false +} +``` + +```output +false +``` + +## `filter` + +Create a view that contains the elements of a range that match the specified condition. + +```cpp +1) template + requires {filter_view(forward(rg), forward

(predicate));} +constexpr ranges::view auto filter(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ filter(P&& predicate); +``` + +### Parameters + +`P`\ +The type of the predicate. + +`predicate`\ +The conditions that determine which elements to keep in the range. + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`filter_view`](filter-view-class.md) that contains the elements of a range that match the predicate. + +### Remarks + +For efficiency's sake, when you use `filter` and `transform` together with a pipe `|`, do the `filter` first so that you `transform` only the elements that you intend to keep. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | filter(predicate)`. Or it can be used with function call syntax: `filter(collection, predicate)` or `filter(predicate)(collection)`. + +### Example: `filter` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto myView = std::views::filter(v, [](int i) {return i < 5; }); + print(myView); // 0 1 2 3 -4 + + auto myView2 = v | std::views::filter([](int i) {return i < 5; }); // pipe syntax + print(myView2); // 0 1 2 3 -4 +} +``` + +```output +0 1 2 3 -4 +0 1 2 3 -4 +``` + +## `iota` + +Create a view that contains a sequence of increasing values. The sequence can be bounded or not. + +```cpp +template +constexpr ranges::view auto iota(V&& startValue); // create an unbounded sequence of incrementing values + +template +constexpr ranges::view auto iota(V&& startValue, E&& endValue); // create a bounded sequence of incrementing values +``` + +### Parameters + +`E`\ +The type of the end value. + +`S`\ +The type of the start value. + +`startValue`\ +The first value in the sequence. + +`endValue`\ +This value is one past the last value that will be in the sequence. For example, `std::views::iota(0, 5)` generates a view that has the values `0,1,2,3,4`. + +### Return value + +An [`iota_view`](iota-view-class.md) of a sequence of increasing values. + +### Remarks + +For an unbounded sequence, the behavior is undefined after the maximum value of its datatype is reached. + +### Example: `iota` + +```cpp +// requires /std:c++20 or later +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + // create an iota view with its range adaptor (preferred) + print(std::views::iota(0, 5)); // outputs 0 1 2 3 4 + + // create an iota_view class directly + std::ranges::iota_view letters{'a', 'f'}; + print(letters); // a b c d e +} +``` + +```output +0 1 2 3 4 +a b c d e +``` + +## `istream` + +Create a view over the elements of a stream. + +```cpp +template +views::istream(str); +``` + +### Parameters + +`str`\ +A stream object. Its type is derived from a specialization of `std::basic_istream`. + +`Val`\ +The type of the elements to extract from the stream. + +### Return value + +A [`basic_istream_view`](basic-istream-view-class.md). + +This range adaptor is equivalent to `ranges::basic_istream_view(str)`, where `U` is the type of `str`. + +### Example: `istream` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::istringstream doubles{"1.1 2.2 3.3 4.4 5.5"}; + for (const auto& elem : std::views::istream(doubles)) + { + std::cout << elem << ' '; // 1.1 2.2 3.3 4.4 5.5 + } +} +``` + +```output +1.1 2.2 3.3 4.4 5.5 +``` + +## `join` + +Create a view that combines all the elements of multiple ranges into a single view. + +```cpp +1) template +[[nodiscard]] constexpr ranges::view auto join(R&& rg) const noexcept; + +2) inline constexpr /*range adaptor closure*/ join(); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`join_view`](join-view-class.md) that contains the elements of all the ranges in the underlying range. + +### Example: `join` + +```cpp +#include +#include +#include +#include + +int main() +{ + // a range of two ranges + std::vector rangeOfRanges[2]{{"C++20", "contains:"}, {"ranges", "modules", "concepts & more."}}; + + for (const auto& elem : std::views::join(rangeOfRanges)) + { + std::cout << elem << ' '; + } +} +``` + +```output +C++20 contains: ranges modules concepts & more. +``` + +### Remarks + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | join`. Or it can be used with function call syntax: `join(collection)`. + +## `keys` + +Create a [`keys_view`](keys-view-class.md) of the first index into each tuple-like value in a collection. This is useful for extracting keys from associative containers. For example, given a range of `std::tuple`, create a view that consists of all the `string` elements from each tuple. + +```cpp +template +constexpr auto keys(R&& rg); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +### Return value + +A [`keys_view`](keys-view-class.md) that consists of the first index into each tuple-like value in the range. + +### Example: `keys` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include + +int main() +{ + // ========== extract keys from a map + + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the keys from the map + for (std::string standards : std::views::keys(cpp_standards)) + { + std::cout << standards << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== Extract keys from a pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor is by using '|' + for (std::string version : windows | std::views::keys) + { + std::cout << version << ' '; // Windows 1.0 Windows 2.0 Windows 3.0 ... + } +} +``` + +```output +C++03 C++11 C++14 C++17 C++98 C++20 +Windows 1.0 Windows 2.0 Windows 3.0 Windows 3.1 Windows NT 3.1 Windows 95 Windows NT 4.0 Windows 95 Windows 98 Windows 1.0 Windows 2000 +``` + +## `lazy_split` + +Split a range into subranges based on a delimiter. The delimiter can be a single element or a view of elements. + +```cpp +1) template +constexpr view auto lazy_split(R&& rg, Pattern&& delimiter); + +2) template +constexpr /*range adaptor closure*/ lazy_split(Pattern&& delimiter); +``` + +### Parameters + +`delimiter`\ +A single value, or a sequence of values that specify where to split the range. + +`Pattern`\ +The type of the delimiter. + +`R`\ +The type of the range to split. + +`rg`\ +The range to split. + +### Return value + +A [`lazy_split_view`](lazy-split-view-class.md) that contains one or more subranges and is the result of splitting the original range on `delimiter`. + +### Remarks + +The delimiter isn't part of the result. For example, if you split the range `1,2,3` on the value `2`, you get two subranges: `1` and `3`. + +A related adaptor is [`split`](#split). The primary differences between [`split_view`](split-view-class.md) and `lazy_split_view` are: + +| View | Can split a `const` range | Range iterator | +|--|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher | +| `lazy_split_view` | yes | [`input_range`](range-concepts.md#input_range) or higher | + +Prefer `split_view` because it's more efficient, unless you must split a range that is `const`. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | lazy_split(delimiter)`. Or it can be used with function call syntax: `lazy_split(collection, delimiter)` or `lazy_split(delimiter)(collection)`. + +### Example: `lazy_split` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{1, 2, 3, 1, 2, 3, 4, 5, 6}; + + // split on a single element + for (const auto& sub : rg | std::views::split(3)) + { + // outputs: + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : sub) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + // split on a sequence of elements + int delimiters[] = {2, 3}; + for (const auto& subrange : std::views::split(rg, delimiters)) + { + // outputs 1 1 4 5 6 + for (auto& i : subrange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `reverse` + +Create a view of the elements of a range in reverse order. + +```cpp +1) template +constexpr ranges::view auto reverse(R&& rg); + +2) inline constexpr /*range adaptor closure*/ reverse(); +``` + +### Parameters + +`R`\ +The type of the underlying range to reverse. + +`rg`\ +The range to reverse. + +### Return value + +A view that presents the elements of the underlying range in reverse order. The returned view is typically, but not always, a specialization of [`reverse_view`](reverse-view-class.md). That is: + +- If `V` is a specialization of `reverse_view`, the result is the argument's underlying view. A double-reverse is a no-op (no operation). +- If `V` has the form `subrange, reverse_iterator>`, the result is a [`subrange`](subrange-class.md) of the unwrapped iterators. A double-reverse is a no-op. +- Otherwise, the result is a [`reverse_view`](reverse-view-class.md). + +### Remarks + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | reverse`. Or it can be used with function call syntax: `reverse(collection)`. + +### Example: `reverse` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto rv = v | std::views::reverse; // using the pipe syntax + + for (auto &&e : rv) // outputs 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // using the range adaptor without using the pipe syntax + auto rv2 = std::views::reverse(v); + for (auto &&e : rv2) // outputs 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } +} +``` + +```output +6 5 -4 3 2 1 0 +6 5 -4 3 2 1 0 +``` + +## `single` + +Create a `single_view`, which is a view that contains one element. + +```cpp +template +constexpr ranges::view auto single(T&& t); +``` + +### Parameters + +`T`\ +The type of the element in the view. + +`t`\ +The value of the element to store in the view. + +### Return value + +An [`single_view`](single-view-class.md) that contains `t`. + +### Remarks + +This view is useful for test purposes, for calling code that needs to be provided with a view that has at least one element in it. + +### Example: `single` + +```cpp +// requires /std:c++20 or higher +#include +#include +#include +#include + +int main() +{ + auto sv = std::views::single(7); + std::cout << sv.front() << " " << *sv.data() << "\n"; // 7 7 + + auto sv2 = std::views::single({6502, "8-bit"}); + std::cout << std::get<0>(sv2[0]) << " " << std::get<1>(sv2[0]) << "\n"; // 6502 8-bit +} +``` + +```output +7 7 +6502 8-bit +``` + +## `split` + +Split a view into subranges based on a delimiter. The delimiter can be a single element or a sequence of elements. + +```cpp +1) template +constexpr view auto split(R&& rg, Pattern&& delimiter); + +2) template +constexpr /*range adaptor closure*/ split(Pattern&& delimiter); +``` + +### Parameters + +`delimiter`\ +A single value, or a sequence of values that specify where to split the range. + +`Pattern`\ +The type of the delimiter. + +`R`\ +The type of the underlying range to split. + +`rg`\ +The range to split. + +### Return value + +A [`split_view`](split-view-class.md) that contains one or more subranges. + +### Remarks + +The delimiter isn't part of the result. For example, if you split the range `1,2,3` on the value `2`, you get two subranges: `1` and `3`. + +A related adaptor is [`lazy_split`](#lazy_split). The primary differences between `split_view` and `lazy_split_view` are: + +| View | Can split a `const` range | Range type | +|---|---|---| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher | + +Prefer `split_view` because it's more efficient, unless you must split a range that is `const`. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | split(delimiter)`. Or it can be used with function call syntax: `split(collection, 5)` or `split(5)(collection)`. + +### Example: `split` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // split on a single element, 3 + for (const auto& sub : rg | std::views::split(3)) + { + // This prints out: + // 1,2 + // 4,5,6 + for (const auto& elem : sub) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + // split on a sequence of elements, 2,3 + int delimiters[] = {2, 3}; + for (const auto& subrange : std::views::split(rg, delimiters)) + { + // outputs 1 1 4 5 6 + for (auto& i : subrange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `take` + +Create a view that contains the specified number of elements taken from the front of a range. + +```cpp +1) template +constexpr ranges::view auto take(R&& rg, ranges::range_difference_type count); + +2) template +constexpr /*range adaptor closure*/ take(DifferenceType&& count); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +`count`\ +The number of elements to take from the front of `rg`. + +### Return value + +The returned view is typically, but not always, a specialization of [`take_view`](take-view-class.md). Specifically: + +- If `V` is a specialization of [`empty_view`](empty-view-class.md), or is a specialization of [`span`](span-class.md), [`basic_string_view`](basic-string-view-class.md), [`iota_view`](iota-view-class.md), or [`subrange`](subrange-class.md) that is both [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range), the result is a specialization of `V`. +- Otherwise, the result is a [`take_view`](take-view-class.md). + +### Remarks + +If you specify more elements to take than exist in `rg`, all of the elements are taken. + +`take` is the opposite of [`drop`](#drop). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | take(5)`. Or it can be used with function call syntax: `take(5, collection)` or `take(5)(collection)`. + +### Example: `take` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::string s{ "abcdefg" }; + auto myView = std::views::take(s, 3); + for (auto c : myView) + { + std::cout << c << ' '; // a b c + } + + std::cout << std::endl; + + for (auto c : s | std::views::take(3)) // pipe syntax + { + std::cout << c << ' '; // a b c + } +} +``` + +```output +a b c +a b c +``` + +## `take_while` + +Create a view that contains the leading elements of a range that match the specified condition. + +```cpp +1) template +constexpr ranges::view auto take_while(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ take_while(P&& predicate); +``` + +### Parameters + +`P`\ +The type of the predicate. + +`predicate`\ +The conditions that determine which leading elements to copy from the range. + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`take_while_view`](take-while-view-class.md) that consists of the first `count` elements that meet the specified criteria in the range. + +### Remarks + +Stops taking elements from `rg` after the predicate returns `false` or the range runs out of elements. + +`take_while` is the opposite of [`drop_while`](#drop_while). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | take_while(pred)`. Or it can be used with function call syntax: `take_while(collection, pred)` or `take_while(pred)(collection)`. + +### Example: `take_while` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::take_while( + v, [](int i) {return i >= 0; }); + print(myView); // 0 1 2 3 + + print(v | std::views::take_while( // 0 1 2 3 -4 + [](int i) {return i < 5; })); // pipe syntax +} +``` + +```output +0 1 2 3 +0 1 2 3 -4 +``` + +## `transform` + +Create a view of elements, each of which is a transformation of an element in the specified range. + +```cpp +1) template +constexpr ranges::view auto transform(R&& rg, F&& fun); + +2) template +constexpr /*range adaptor closure*/ transform(F&& fun); +``` + +### Parameters + +`F`\ +The type of the function object to transform the elements. + +`R`\ +The type of the underlying range. + +`fun`\ +The function that transforms the elements. + +`rg`\ +The range to create the view from. + +### Return value + +A [`transform_view`](transform-view-class.md) that contains the transformed elements of `rg`. + +### Remarks + +For efficiency's sake, when you compose `filter` and `transform`, do the `filter` first so that you `transform` only the elements that you intend to keep. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | transform(fun)`. Or it can be used with function call syntax: `transform(collection, fun)` or `transform(fun)(collection)`. + +### Example: `transform` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto myView = std::views::transform(v, [](int i) {return i * 2; }); + print(myView); // 0 2 4 6 -8 10 12 + + print(v | std::views::transform( // 0 2 4 6 -8 10 12 + [](int i) {return i * 2; })); // pipe syntax +} +``` + +```output +0 2 4 6 -8 10 12 +0 2 4 6 -8 10 12 +``` + +## `values` + +Create a [`values_view`](values-view-class.md) that consists of the second index into each tuple-like value in a collection. This is useful for making a view of the values in an associative container. For example, given a range of `std::tuple` values, create a view that consists of all the `int` elements from each tuple. + +```cpp +template +constexpr ranges::view auto values(R&& rg); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The underlying range of tuple-like values. + +### Return value + +A [`values_view`](values-view-class.md) built from the second index into each tuple-like value in the range. + +### Example: `values` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include + +int main() +{ + // ========== working with a map + + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the years from the map + for (int years : std::views::values(cpp_standards)) + { + std::cout << years << ' '; // 2003 2011 2014 2017 1998 2020 + } + std::cout << '\n'; + + // ========== working with pairs + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor by using '|' + // Create a values_view that contains the year from each pair + for (int years : windows | std::views::values) + { + std::cout << years << ' '; // 1985 1987 1990 1992 ... + } +} +``` + +```output +2003 2011 2014 2017 1998 2020 +1985 1987 1990 1992 1993 1995 1996 1995 1998 1985 2000 +``` + +## Range adaptor type aliases + +### `all_t` + +Provides the type of the view that [`all`](#all) returns. + +```cpp +template +using all_t = decltype(views::all(std::declval())); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +### Return value + +The type of the view that `all` returns: `decltype(views::all(std::declval()))`. + +### Example: `all_t` + +```cpp +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myView = std::views::all(v); + std::views::all_t &viewType = myView; +} +``` + +## See also + +[``](ranges.md)\ +[`` concepts](range-concepts.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/range-concepts.md b/docs/standard-library/range-concepts.md new file mode 100644 index 0000000000..a00aec4ef2 --- /dev/null +++ b/docs/standard-library/range-concepts.md @@ -0,0 +1,424 @@ +--- +description: "Learn more about range concepts." +title: " concepts" +ms.date: 12/16/2022 +f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_range", "ranges/std::ranges::borrowed_range", "ranges/std::ranges::common_range", "ranges/std::ranges::contiguous_range", "ranges/std::ranges::forward_range", "ranges/std::ranges::input_range", "ranges/std::ranges::output_range", "ranges/std::ranges::random_access_range", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_range", "ranges/std::ranges::view", "ranges/std::ranges::viewable_range"] +helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_range", "std::ranges [C++], ranges::borrowed_range", "std::ranges [C++], ranges::common_range", "std::ranges [C++], ranges::contiguous_range", "std::ranges [C++], ranges::forward_range", "std::ranges [C++], ranges::input_range", "std::ranges [C++], ranges::output_range", "std::ranges [C++], ranges::random_access_range", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_range", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_range"] +--- +# `` concepts + +Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiation, specify template argument requirements in a readable form, and provide more succinct template related compiler errors. + +Consider the following example, which defines a concept to prevent instantiating a template with a type that doesn't support division: + +```cpp +// requires /std:c++20 or later +#include + +// Definition of dividable concept which requires +// that arguments a & b of type T support division +template +concept dividable = requires (T a, T b) +{ + a / b; +}; + +// Apply the concept to a template. +// The template will only be instantiated if argument T supports division. +// This prevents the template from being instantiated with types that don't support division. +// This could have been applied to the parameter of a template function, but because +// most of the concepts in the library are applied to classes, this form is demonstrated. +template requires dividable +class DivideEmUp +{ +public: + T Divide(T x, T y) + { + return x / y; + } +}; + +int main() +{ + DivideEmUp dividerOfInts; + std::cout << dividerOfInts.Divide(6, 3); // outputs 2 + // The following line will not compile because the template can't be instantiated + // with char* because char* can be divided + DivideEmUp dividerOfCharPtrs; // compiler error: cannot deduce template arguments +} +``` + +When you pass the compiler switch `/diagnostics:caret` to Visual Studio 2022 version 17.4 preview 4, or later, the error that concept `dividable` evaluated to false will point directly to the expression requirement `(a / b)` that failed. + +Range concepts are defined in the `std::ranges` namespace, and declared in the `` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on. + +There are six categories of ranges. They're related to the categories of iterators listed in [`` concepts](iterator-concepts.md). In order of increasing capability, the categories are: + +| Range concept | Description | +|--|--| +| [`output_range`](#output_range)
[`input_range`](#input_range) | Specifies a range that you can write to.
Specifies a range that you can read from once. | +| [`forward_range`](#forward_range) | Specifies a range that you can read (and possibly write) multiple times. | +| [`bidirectional_range`](#bidirectional_range) | Specifies a range that you can read and write both forwards and backwards. | +| [`random_access_range`](#random_access_range) | Specifies a range that you can read and write by index. | +| [`contiguous_range`](#contiguous_range) | Specifies a range whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. | + +In the preceding table, concepts are listed in order of increasing capability. A range that meets the requirements of a concept generally meets the requirements of the concepts in the rows that precede it. For example, a `random_access_range` has the capability of a `bidirectional_range`, `forward_range`, `input_range`, and `output_range`. The exception is `input_range`, which can't be written to, so it doesn't have the capabilities of `output_range`. + +:::image type="content" source="media/ranges-iterator-hiearchy.svg" alt-text="Diagram of the ranges iterator hierarchy. input_range and output_range are the most basic iterators. forward_range is next and refines both input_range and output_range. bidirectional_range refines forward_range. random_access_range refines bidirectional_range. Finally, contiguous_range refines random_access_range"::: + +Other range concepts include: + +| Range concept | Description | +|--|--| +| [`range`](#range)C++20 | Specifies a type that provides an iterator and a sentinel. | +| [`borrowed_range`](#borrowed_range)C++20 | Specifies that the lifetime of the range's iterators aren't tied to the range's lifetime. | +| [`common_range`](#common_range)C++20 | Specifies that the type of the range's iterator and the type of the range's sentinel are the same. | +| [`Simple_View`](#simple_view)C++20 | Not an official concept defined as part of the standard library, but used as a helper concept on some interfaces. | +| [`sized_range`](#sized_range)C++20 | Specifies a range that can provide its number of elements efficiently. | +| [`view`](#view)C++20 | Specifies a type that has efficient (constant time) move construction, assignment, and destruction. | +| [`viewable_range`](#viewable_range)C++20 | Specifies a type that either is a view or can be converted to one. | + +## `bidirectional_range` + +A `bidirectional_range` supports reading and writing the range forwards and backwards. + +```cpp +template +concept bidirectional_range = + forward_range && bidirectional_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `bidirectional_range`. + +### Remarks + +This kind of range supports [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator) or greater. +A `bidirectional_iterator` has the capabilities of a [`forward_iterator`](iterator-concepts.md#forward_iterator), but can also iterate backwards. + +Some examples of a `bidirectional_range` are `std::set`, `std::vector`, and `std::list`. + +## `borrowed_range` + +A type models `borrowed_range` if the validity of iterators you get from the object can outlive the lifetime of the object. That is, the iterators for a range can be used even when the range no longer exists. + +```cpp +template +concept borrowed_range = + range && + (is_lvalue_reference_v || enable_borrowed_range>); +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `borrowed_range`. + +### Remarks + +The lifetime of an rvalue range can end following a function call whether the range models `borrowed_range` or not. If it's a `borrowed_range`, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends. + +Cases where this isn't true are, for example, for containers like `vector` or `list` because when the container's lifetime ends, the iterators would refer to elements that have been destroyed. + +You can continue to use the iterators for a `borrowed_range`, for example, for a `view` like `iota_view{0, 42}` whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand. + +## `common_range` + +The type of the iterator for a `common_range` is the same as the type of the sentinel. That is, `begin()` and `end()` return the same type. + +```cpp +template +concept common_range = + ranges::range && std::same_as, ranges::sentinel_t>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `common_range`. + +### Remarks + +Getting the type from `std::ranges::begin()` and `std::ranges::end()` is important for algorithms that calculate the distance between two iterators, and for algorithms that accept ranges denoted by iterator pairs. + +The standard containers (for example, `vector`) meet the requirements of `common_range`. + +## `contiguous_range` + +The elements of a `contiguous_range` are stored sequentially in memory and can be accessed using pointer arithmetic. For example, an array is a `contiguous_range`. + +```cpp +template +concept contiguous_range = + random_access_range && contiguous_iterator> && + requires(T& t) {{ ranges::data(t) } -> same_as>>;}; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `contiguous_range`. + +### Remarks + +A `contiguous_range` can be accessed by pointer arithmetic because the elements are laid out sequentially in memory and are the same size. This kind of range supports [`continguous_iterator`](iterator-concepts.md#contiguous_iterator), which is the most flexible of all the iterators. + +Some examples of a `contiguous_range` are `std::array`, `std::vector`, and `std::string`. + +### Example: `contiguous_range` + +The following example shows using pointer arithmetic to access a `contiguous_range`: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + // Show that vector is a contiguous_range + std::vector v = {0,1,2,3,4,5}; + std::cout << std::boolalpha << std::ranges::contiguous_range << '\n'; // outputs true + + // Show that pointer arithmetic can be used to access the elements of a contiguous_range + auto ptr = v.data(); + ptr += 2; + std::cout << *ptr << '\n'; // outputs 2 +} +``` + +```output +true +2 +``` + +## `forward_range` + +A `forward_range` supports reading (and possibly writing) the range multiple times. + +```cpp +template +concept forward_range = input_range && forward_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `forward_range`. + +### Remarks + +This kind of range supports [`forward_iterator`](iterator-concepts.md#forward_iterator) or greater. A `forward_iterator` can iterate over a range multiple times. + +## `input_range` + +An `input_range` is a range that can be read from once. + +```cpp +template +concept input_range = range && input_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's an `input_range`. + +### Remarks + +When a type meets the requirements of `input_range`: + +- The `ranges::begin()` function returns an [`input_iterator`](iterator-concepts.md#input_iterator). Calling `begin()` more than once on an `input_range` results in undefined behavior. +- You can dereference an `input_iterator` repeatedly, which yields the same value each time. An `input_range` isn't multi-pass. Incrementing an iterator invalidates any copies. +- It can be used with `ranges::for_each`. +- It supports `input_iterator` or greater. + +## `output_range` + +An `output_range` is a range that you can write to. + +```cpp +template +concept output_range = range && output_iterator, T>; +``` + +### Parameters + +*`R`*\ +The type of the range. + +*`T`*\ +The type of the data to write to the range. + +### Remarks + +The meaning of `output_iterator, T>` is that the type provides an iterator that can write values of type `T` to a range of type `R`. In other words, it supports [`output_iterator`](iterator-concepts.md#output_iterator) or greater. + +## `random_access_range` + +A `random_access_range` can read or write a range by index. + +```cpp +template +concept random_access_range = +bidirectional_range && random_access_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `sized_range`. + +### Remarks + +This kind of range supports [`random_access_iterator`](iterator-concepts.md#random_access_iterator) or greater. A `random_access_range` has the capabilities of an `input_range`, `output_range`, `forward_range`, and `bidirectional_range`. A `random_access_range` is sortable. + +Some examples of a `random_access_range` are `std::vector`, `std::array`, and `std::deque`. + +## `range` + +Defines the requirements a type must meet to be a `range`. A `range` provides an iterator and a sentinel, so that you can iterate over its elements. + +```cpp +template +concept range = requires(T& rg) +{ + ranges::begin(rg); + ranges::end(rg); +}; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `range`. + +### Remarks + +The requirements of a `range` are: +- It can be iterated using `std::ranges::begin()` and `std::ranges::end()` +- `ranges::begin()` and `ranges::end()` run in amortized constant time and don't modify the `range`. Amortized constant time doesn't mean O(1), but that the average cost over a series of calls, even in the worst case, is O(n) rather than O(n^2) or worse. +- `[ranges::begin(), ranges::end())` denotes a valid range. + +## `Simple_View` + +A `Simple_View` is an exposition-only concept used on some `ranges` interfaces. It isn't defined in the library. It's only used in the specification to help describe the behavior of some range adaptors. + +```cpp +template + concept Simple_View = // exposition only + ranges::view && ranges::range && + std::same_as, std::ranges::iterator_t> && + std::same_as, std::ranges::sentinel_t>; +``` + +### Parameters + +*`V`*\ +The type to test to see if it's a `Simple_View`. + +### Remarks + +A view `V` is a [`Simple_View`](#simple_view) if all of the following are true: +- `V` is a view +- `const V` is a range +- Both `v` and `const V` have the same iterator and sentinel types. + +## `sized_range` + +A `sized_range` provides the number of elements in the range in amortized constant time. + +```cpp +template + concept sized_range = range && + requires(T& t) { ranges::size(t); }; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `sized_range`. + +### Remarks + +The requirements of a `sized_range` are that calling `ranges::size` on it: + +- Doesn't modify the range. +- Returns the number of elements in amortized constant time. Amortized constant time doesn't mean O(1), but that the average cost over a series of calls, even in the worst case, is O(n) rather than O(n^2) or worse. + +Some examples of a `sized_range` are `std::list` and `std::vector`. + +### Example: `sized_range` + +The following example shows that a `vector` of `int` is a `sized_range`: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::cout << std::boolalpha << std::ranges::sized_range> << '\n'; // outputs "true" +} +``` + +## `view` + +A `view` has constant time move construction, assignment, and destruction operations--regardless of the number of elements it has. Views don't need to be copy constructible or copy assignable, but if they are, those operations must also run in constant time. + +Because of the constant time requirement, you can efficiently compose views. For example, given a vector of `int` called `input`, a function that determines if a number is divisible by three, and a function that squares a number, the statement `auto x = input | std::views::filter(divisible_by_three) | std::views::transform(square);` efficiently produces a view that contains the squares of the numbers in input that are divisible by three. Connecting views together with `|` is referred to as composing the views. If a type satisfies the [`view`](range-concepts.md#view) concept, then it can be composed efficiently. + +```cpp +template +concept view = ranges::range && std::movable && ranges::enable_view; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a view. + +### Remarks + +The essential requirement that makes a view composable is that it's cheap to move/copy. This is because the view is moved/copied when it's composed with another view. It must be a movable range. + +`ranges::enable_view` is a trait used to claim conformance to the semantic requirements of the `view` concept. A type can opt in by: +- publicly and unambiguously deriving from a specialization of `ranges::view_interface` +- publicly and unambiguously deriving from the empty class `ranges::view_base`, or +- specializing `ranges::enable_view` to `true` + +Option 1 is preferred because `view_interface` also provides default implementation that saves some boilerplate code you have to write. + +Failing that, option 2 is a little simpler than option 3. + +The advantage of option 3 is that it's possible without changing the definition of the type. + +## `viewable_range` + +A `viewable_range` is a type that either is a view or can be converted to one. + +```cpp +template + concept viewable_range = + range && (borrowed_range || view>); +``` + +### Parameters + +*`T`*\ +The type to test to see if it either is a view or can be converted to one. + +### Remarks + +Use `std::ranges::views::all()` to convert a range to a view. + +## See also + +[``](ranges.md)\ +[Range adaptors](range-adaptors.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/range-functions.md b/docs/standard-library/range-functions.md new file mode 100644 index 0000000000..359201dcd0 --- /dev/null +++ b/docs/standard-library/range-functions.md @@ -0,0 +1,618 @@ +--- +title: " helper functions" +description: "Learn more about: helper functions" +ms.date: 06/16/2022 +f1_keywords: ["ranges/std::ranges::begin", "ranges/std::ranges::end", "ranges/std::ranges::cbegin", "ranges/std::ranges::cend", "ranges/std::ranges::rbegin", "ranges/std::ranges::rend", "ranges/std::ranges::crbegin", "ranges/std::ranges::crend", "ranges/std::ranges::size","ranges/std::ranges::ssize","ranges/std::ranges::empty","ranges/std::ranges::data","ranges/std::ranges::cdata"] +helpviewer_keywords: ["std::ranges [C++], ranges::begin", "std::ranges [C++], ranges::end", "std::ranges [C++], ranges::cbegin", "std::ranges [C++], ranges::cend", "std::ranges [C++], ranges::rbegin", "std::ranges [C++], ranges::rend", "std::ranges [C++], ranges::crbegin", "std::ranges [C++], ranges::crend", "std::ranges [C++], ranges::size","std::ranges [C++], ranges::ssize","std::ranges [C++], ranges::empty","std::ranges [C++], ranges::data","std::ranges [C++], ranges::cdata"] +dev_langs: ["C++"] +--- +# `` functions + +The ``C++20 header includes the following non-member helper functions. + +| **Non-member functions** | **Description** | +|--|--| +| [`begin`](#begin)C++20 | Get an iterator to the first element in the range. | +| [`cbegin`](#cbegin)C++20 | Get a `const` iterator to the first element in the range. | +| [`cend`](#cend)C++20 | Get the sentinel at the end of the `const`-qualified range. | +| [`cdata`](#cdata)C++20 | Get a `const` pointer to the first element in the contiguous range. | +| [`crbegin`](#crbegin)C++20 | Get a reverse `const` iterator to the beginning of the range. | +| [`crend`](#crend)C++20 | Get the sentinel at the end of what `crbegin()` returns. | +| [`data`](#data)C++20 | Get a pointer to the first element in the contiguous range. | +| [`empty`](#empty)C++20 | Test if the range is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of the range. | +| [`rbegin`](#rbegin)C++20 | Get a reverse iterator to the beginning of the range. | +| [`rend`](#rend)C++20 | Get a reverse iterator to the sentinel at the end of the range. | +| [`size`](#size)C++20 | Get the size of the range as an unsigned value. | +| [`ssize`](#ssize)C++20 | Get the size of the range as a signed value. | + +Many of these 'functions' are implemented as [customization point objects](https://eel.is/c++draft/customization.point.object). A customization point object is a [function object](https://eel.is/c++draft/function.objects) that can be overloaded on user-defined types, while also enforcing constraints on which kinds of types can be passed to the function object. The net effect is that the compiler figures out if there's a valid customized function to call for the passed in type, or if the default implementation should be used, or if the call is ill-formed. + +Many of these functions have corresponding functions in the `std` namespace. But when working with ranges, use these helper functions instead. These functions use C++20 concepts, which provide better compile time errors. Because they're implemented as customization points, problems related to argument dependent lookup (ADL) and const correctness are avoided. + +## `begin` + +Get an iterator to the first element in the range. + +```cpp +template +constexpr std::input_or_output_iterator auto begin(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +An iterator to the first element in the range: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'begin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +If the range is an array, returns the equivalent of `rg + 0`. +If `auto(rg.begin())` yields an iterator, returns the equivalent of `auto(rg.begin())`. If that expression is ill-formed, `auto(begin(rg))` is used if that expression yields an iterator. + +### Remarks + +`ranges::begin()` works on all ranges, whereas `std::begin()` may not. + +### Example: `begin` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {10, 20, 30}; + auto vi = std::ranges::begin(v); + std::cout << *vi << ' ' << *++vi; // outputs 10 20 +} +``` + +## `cbegin` + +Get a `const` iterator to the first element in a range. +The iterator can access the elements in the range, but can't modify them. + +```cpp +template +constexpr std::input_or_output_iterator auto cbegin(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A `const` iterator to the first element in the range: + +:::image type="content" source="media/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'cbegin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: + +If the range is an array, returns the equivalent of `rg + 0`. +If `auto(rg.cbegin())` yields an iterator, returns the equivalent of `auto(rg.cbegin())`. If that expression is ill-formed, `auto(cbegin(rg))` is used if that expression yields an iterator. + +### Remarks + +`ranges::cbegin()` works on all ranges, whereas `std::cbegin()` may not. + +### Example: `cbegin` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {10, 20, 30}; + auto vi = std::ranges::cbegin(v); + std::cout << *vi; // outputs 10 + // *vi = 100; // error because the iterator is const +} +``` + +## `cdata` + +Get a `const` pointer to the first element in the contiguous range. + +```cpp +template +constexpr std::add_pointer_t> cdata(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A `const` pointer, based on the type of the range, to the first element data in the contiguous range. For example, if the range is a vector of integers, the type of the return value is a `const int *`. + +### Example: `cdata` + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + std::string src{ "a string" }; + + auto c_charPtr = std::ranges::cdata(src); // ptr is a const char * + auto c_intPtr = std::ranges::cdata(v); // ptr2 is a const int * + std::cout << c_charPtr << ", " << *c_intPtr << '\n'; // outputs a string, 10 + + // *c_intPtr = 100; // error - cannot assign to a const pointer + // *charPtr = 'A'; // error - cannot assign to a const pointer +} +``` + +## `cend` + +Get the sentinel at the end of the `const`-qualified range. +The iterator can access the elements in the range, but can't modify them. + +```cpp +template +constexpr std::sentinel_for()))> auto cend(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +The sentinel that follows the last element in the `const`-qualified range: + +:::image type="content" source="media/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled cbegin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: + +### Remarks + +`ranges::cend()` works on all ranges, whereas `std::cend()` may not. + +### Example: `cend` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {10, 20, 30}; + auto i = std::ranges::cend(v); + --i; // get off the sentinel and onto the last element in the range + std::cout << *i; // outputs 30 + // *i = 300 // error because the iterator is const +} +``` + +## `crbegin` + +Get a reverse `const` iterator to the first element in a reversed range. +A reverse iterator returns the elements of the range in reverse order. +The range itself isn't reversed; access to it is. + +```cpp +template +constexpr std::input_or_output_iterator auto crbegin(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A reverse `const` iterator to the first element in the range. This iterator returns the elements of the range in reverse order, starting at the end of the range: + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +If the range is an array, returns the equivalent of `reverse_iterator{rg + n}` where `n` is the number of elements in the array. +If `auto(rg.crbegin())` yields an iterator, returns the equivalent of `auto(rg.crbegin())`. If that expression is ill-formed, `auto(crbegin(rg))` is used if that expression yields an iterator. + +### Remarks + +`ranges::crbegin()` works on all bidirectional ranges, whereas `std::crbegin()` may not. + +### Example: `crbegin` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::ranges::crbegin(v); + std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10 + // vi[1] = 100; // error because the iterator is const +} +``` + +## `crend` + +Get the sentinel at the end of what `crbegin()` returns. +A reverse iterator returns the elements of the range in reverse order. +The range itself isn't reversed; access to it is. + +```cpp +template +std::sentinel_for()))> auto crend(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +The sentinel at the end of what `cbegin()` returns. The sentinel follows the last element in a reversed view of the range: + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +### Remarks + +`ranges::crend()` works on all bidirectional ranges, whereas `std::crend()` may not. + +### `crend` example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::ranges::crend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 + // vi[0] = 300; // error because the iterator is const + std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30 +} +``` + +## `data` + +Get a pointer to the first element in a contiguous range. + +```cpp +template +constexpr std::add_pointer_t> data(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A pointer, based on the type of the range, to the first element in the contiguous range. For example, if the range is a vector of integers, the type of the return value is an `int *`. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + std::string src{ "a string" }; + + auto charPtr = std::ranges::data(src); // charPtr is a char * + auto intPtr = std::ranges::data(v); // intPtr is an int * + std::cout << charPtr << ", " << *intPtr << '\n'; // outputs a string, 10 + *intPtr = 100; + *charPtr = 'A'; + std::cout << charPtr << ", " << *intPtr; // outputs A string, 100 +} +``` + +## `empty` + +Test if the range is empty. + +```cpp +template +constexpr bool empty(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +Returns `true` if the range has no elements; otherwise `false`. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10,20,30}; + std::vector v2; + + std::cout << std::boolalpha << std::ranges::empty(v); // outputs false + std::cout << std::boolalpha << ", " << std::ranges::empty(v2); // outputs true +} +``` + +## `end` + +Get the sentinel at the end of the range. + +```cpp +template +std::sentinel_for> auto end(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +The sentinel that follows the last element in the range: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +`ranges::end()` works on all ranges, whereas `std::end()` may not. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {10, 20, 30}; + auto i = std::ranges::end(v); + --i; // get off the sentinel and onto the last element in the range + std::cout << *i; // outputs 30 +} +``` + +## `rbegin` + +Get a reverse iterator to the first element in a reversed range. +A reverse iterator returns the elements of the range in reverse order. +The range itself isn't reversed; access to it is. + +```cpp +template +constexpr std::input_or_output_iterator auto rbegin(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A reverse iterator to the first element in the range. This iterator returns the elements of the range in reverse order, starting at the end of the reversed range: + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +If the range is an array, returns the equivalent of `reverse_iterator{rg + n}` where `n` is the number of elements in the array. +If `auto(rg.rbegin())` yields an iterator, returns the equivalent of `auto(rg.rbegin())`. If that expression is ill-formed, `auto(rbegin(rg))` is used if that expression yields an iterator. + +### Remarks + +`ranges::rbegin()` works on all bidirectional ranges, whereas `std::rbegin()` may not. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::ranges::rbegin(v); + std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10 +} +``` + +## `rend` + +Get a reverse iterator to the sentinel at the end of a reversed view of the range. +A reverse iterator returns the elements of the range in reverse order. +The range itself isn't reversed; access to it is. + +```cpp +template +constexpr +std::sentinel_for()))> auto rend(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A reverse iterator to the sentinel at the end of the range. The sentinel follows the last element in a reversed view of the range: + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +### Remarks + +`ranges::rend()` works on all bidirectional ranges, whereas `std::rend()` may not. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::ranges::rend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 + std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30 +} +``` + +## `size` + +Get the number of elements in the range as an unsigned value. + +```cpp +template +constexpr /*unsigned integer-like type */ size(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +The number of elements in the range as an unsigned integer-like value. + +### Remarks + +This function executes in constant time. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto s = std::ranges::size(v); // s is a size_t + std::cout << s; // outputs 3 +} +``` + +## `ssize` + +Get the size of the range as a signed value. + +```cpp +template +constexpr /* signed-integer-like type */ ssize(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +The number of elements in the range as a signed integer-like value. + +### Remarks + +This function executes in constant time. + +### Example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto s = std::ranges::ssize(v); + std::cout << s; // outputs 3 +} +``` + +## See also + +[``](ranges.md)\ +[What are customization objects](https://stackoverflow.com/questions/53495848/what-are-customization-point-objects-and-how-to-use-them) diff --git a/docs/standard-library/ranges-alias-templates.md b/docs/standard-library/ranges-alias-templates.md new file mode 100644 index 0000000000..2014917533 --- /dev/null +++ b/docs/standard-library/ranges-alias-templates.md @@ -0,0 +1,563 @@ +--- +description: "Learn more about ranges alias templates." +title: " alias templates" +ms.date: 01/28/2023 +f1_keywords: ["ranges/std::ranges::borrowed_iterator_t", "ranges/std::ranges::borrowed_subrange_t", "ranges/std::ranges::dangling", "ranges/std::ranges::iterator_t", "ranges/std::ranges::range_difference_t", "ranges/std::ranges::range_reference_t", "ranges/std::ranges::range_rvalue_reference_t", "ranges/std::ranges::range_size_t", "ranges/std::ranges::range_value_t", "ranges/std::ranges::sentinel_t"] +helpviewer_keywords: ["std::ranges [C++], ranges::borrowed_iterator_t", "std::ranges [C++], ranges::borrowed_subrange_t", "std::ranges [C++], ranges::dangling", "std::ranges [C++], ranges::iterator_t", "std::ranges [C++], ranges::range_difference_t", "std::ranges [C++], ranges::range_reference_t", "std::ranges [C++], ranges::range_rvalue_reference_t", "std::ranges [C++], ranges::range_size_t", "std::ranges [C++], ranges::range_value_t", "std::ranges [C++], ranges::sentinel_t"] +--- +# `` alias templates + +An alias template is an alias for another type, which can make code more readable. For example, the following alias, `conditional_t`, is an alias for either `borrowed_range` or `dangling` range, depending on the kind of `range` that's passed in: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include +#include +#include +#include + +using namespace std; + +// Define an alias template called my_iterator_t +// If the provided range R is a borrowed_range, then the +// returned type is iterator_t; otherwise, ranges::dangling +template +using my_iterator_t = conditional_t< + ranges::borrowed_range, + ranges::iterator_t, ranges::dangling>; + +int main() +{ + my_iterator_t> aDanglingRange; // list<> isn't a borrowed_range + constexpr bool same = same_as< + decltype(aDanglingRange), + ranges::dangling>; // true + + my_iterator_t> anIterator_t; // span<> is a borrowed_range + constexpr bool same2 = same_as< + decltype(anIterator_t), + ranges::iterator_t>>; // true + + cout << boolalpha << same << "," << same2; // outputs true, true +} +``` + +For more information about alias templates, see [Aliases and typedefs](../cpp/aliases-and-typedefs-cpp.md). + +The `` header defines the following alias templates that determine the types of iterators and sentinels for a `range`: + +| Alias template | Description | +|--|--| +| [`borrowed_iterator_t`](#borrowed_iterator_t)C++20 | Determine if an iterator returned for a `range` refers to a range whose lifetime has ended. | +| [`borrowed_subrange_t`](#borrowed_subrange_t)C++20 | Determine if a `subrange` returned for a `range` refers to a range whose lifetime has ended.| +| [`dangling`](#dangling)C++20 | Indicates that the returned iterator of a `range`/`subrange` outlives the lifetime of the `range`/`subrange` it refers to. | +| [`iterator_t`](#iterator_t)C++20 | Returns the iterator type for the specified range. | +| [`range_difference_t`](#range_difference_t)C++20 | Returns the difference type for the specified range's iterator. | +| [`range_reference_t`](#range_reference_t)C++20 | Returns the reference type for the specified range's iterator. | +| [`range_rvalue_reference_t`](#range_rvalue_reference_t)C++20 | Returns the rvalue reference type for the specified range's iterator. In other words, the rvalue reference type of the range's elements. | +| [`range_size_t`](#range_size_t)C++20 | Returns the type used to report the specified range's `size`. | +| [`range_value_t`](#range_value_t)C++20 | Returns the value type of specified range's iterator. Or in other words, the type of the elements in the range. | +| [`sentinel_t`](#sentinel_t)C++20 | Returns the sentinel type for the specified range. | + +## `borrowed_iterator_t` + +When an algorithm function that returns an iterator is called with an rvalue `range` argument, the range's lifetime could end following the call. That means the returned iterator could refer to elements whose lifetimes have ended. Using a dangling iterator results in undefined behavior. + +This template alias returns `ranges::dangling` to indicate that this is the situation for the given range argument, or `std::ranges::iterator_t` to indicate that it's safe to use the returned iterator because the range it refers to models `borrowed_range` or the range was passed as an lvalue. + +```cpp +template +using borrowed_iterator_t = conditional_t, + ranges::iterator_t, ranges::dangling>; +``` + +### Parameters + +*`R`*\ +The range to test. + +### Remarks + +The lifetime of an rvalue range can end following a function call whether the range models `borrowed_range` or not. If it's a `borrowed_range`, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends. + +Cases where this isn't true are, for example, for containers like `vector` or `list` because when the container's lifetime ends, the iterators would refer to elements that have been destroyed. + +You can continue to use the iterators for a `borrowed_range`, for example, for a `view` like `iota_view{0, 42}` whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand. + +If an algorithm function is passed a range whose iterators depend on its lifetime, `ranges::dangling` is returned instead of an iterator or subrange, so potential misuse is detected at compile time. + +### Example: `borrowed_iterator_t` + +The following example shows how `borrowed_iterator_t` detects a dangling iterator. The function `ranges::max_element()` uses this template alias to determine the return type: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include +#include +#include + +using namespace std; + +int main() +{ + // Not dangling ------------------ + + int a[] = {0,1,2,3}; + + // not dangling even though an rvalue because span models ranges::borrowed + auto result1 = ranges::max_element(span{a}); + cout << boolalpha << ranges::borrowed_range << endl; // outputs true because the temporary models ranges::borrowed + cout << same_as << endl; // outputs false because the result isn't dangling + + vector v{0,1,2,3}; // doesn't model ranges::borrowed + auto result2 = ranges::max_element(v); // Yet not dangling because passed as an lvalue + cout << same_as << endl; // outputs false because the result isn't dangling + + // Dangling ------------------ + + auto result3 = ranges::max_element(vector{0,1,2,3}); // dangling because vector doesn't model ranges::borrowed and is passed as an rvalue + cout << same_as; // outputs true because the result is dangling +} +``` + +```output +true +false +false +true +``` + +## `borrowed_subrange_t` + +When an algorithm function that returns a `subrange` is called with an rvalue `range` argument, the range's lifetime could end following the call. That means the returned `subrange` could refer to elements whose lifetimes have ended. Using a dangling `subrange` results in undefined behavior. + +This template alias either returns `ranges::dangling` to indicate that this could be the situation for the given range argument, or `subrange>` to indicate that it's safe to use the returned subrange because either the range whose elements it refers to models `borrowed_range` or the range was passed as an lvalue. + +```cpp +template +using borrowed_subrange_t = conditional_t, + ranges::subrange>, ranges::dangling>; +``` + +### Parameters + +*`R`*\ +The range to test. + +### Remarks + +The lifetime of an rvalue range can end following a function call whether the range models `borrowed_range` or not. If it's a `borrowed_range`, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends. + +Cases where this isn't true are, for example, for containers like `vector` or `list` because when the container's lifetime ends, the iterators would refer to elements that have been destroyed. + +You can continue to use the iterators for a `borrowed_range`, for example, for a `view` like `iota_view{0, 42}` whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand. + +If an algorithm function is passed a range whose iterators depend on its lifetime, `ranges::dangling` is returned instead of a subrange so that potential misuse is detected at compile time. + +### Example: `borrowed_subrange_t` + +The following example shows how `borrowed_subrange_t` detects a dangling iterator because `equal_range()` and `max_element` use this template alias to determine the return type: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include +#include +#include + +int main() +{ + using namespace std; + + // Not dangling ------------------ + + vector vec{0, 1, 1, 2}; + + auto result1 = ranges::equal_range(span{vec}, 1); // not dangling even though passing as an rvalue because span models borrowed_range + cout << boolalpha << ranges::borrowed_range << endl; // true because the temporary is a borrowed range + cout << boolalpha << same_as << endl; // false because the result isn't dangling + + // result2 isn't dangling even though vec doesn't model ranges::borrowed because it's an lvalue + auto result2 = ranges::max_element(vec); + cout << boolalpha << ranges::borrowed_range << endl; // false because vector isn't a borrowed_range + cout << boolalpha << same_as << endl; // false because the result isn't dangling + + // Dangling ----------------------- + + // result3 is dangling because the temporary is an rvalue that doesn't model borrowed_range + auto result3 = ranges::max_element(vector{0,1,1,2}); + cout << boolalpha << same_as << endl; // true because the result is dangling +} +``` + +```output +true +false +false +false +true +``` + +## `dangling` + +If an algorithm function that returns an iterator or a `subrange` is called with an rvalue `range` argument, the range argument's lifetime could end following the call. That means the returned iterator or `subrange` could refer to elements whose lifetimes have ended. Using a dangling iterator or `subrange` results in undefined behavior. + +If an algorithm function is passed a range whose iterators depend on its lifetime, `ranges::dangling` is returned instead of an iterator or subrange so that potential misuse is detected at compile time. + +```cpp +1) constexpr dangling() noexcept = default; +2) template +constexpr dangling(Args&&...) noexcept {} +``` + +### Parameters + +*`Args`*\ +A variable number of non-`void` types. They have no effect. The arguments are a convenience so that you don't need different code paths to handle constructing the iterator type versus the `dangling` type. This is useful when the passed in value indicates that `dangling` should be returned instead of an iterator. + +### Example: `dangling` + +The following example shows how `max_element` detects a dangling iterator. + +```cpp +// requires /std:c++20, or later + +#include +#include +#include +#include + +using namespace std; + +int main() +{ + auto result1 = ranges::max_element(vector{1,2,3}); // dangling because vector doesn't model ranges::borrowed and is passed as an rvalue + cout << boolalpha << same_as << endl; // outputs true because the result is dangling + + vector v{3,4,5}; + auto result2 = ranges::max_element(v); // Not dangling because passed as an lvalue + cout << same_as; // outputs false because the result isn't dangling +} +``` + +```output +true +false +``` + +## `iterator_t` + +This template alias returns the iterator type used to iterate over the provided range type. + +```cpp +template +using iterator_t = decltype(ranges::begin(declval())); +``` + +### Parameters + +*`T`*\ +The range type to get the iterator type for. + +### Example: `iterator_t` + +The following example shows how `iterator_t` can be used to declare an iterator for a vector: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + + ranges::iterator_t it = v.begin(); + cout << *it << "\n"; // outputs 1 + cout << typeid(it).name(); // outputs class _Vector_iterator>> +} +``` + +```output +1 +class std::_Vector_iterator > > +``` + +## `range_difference_t` + +Returns the difference type for the specified range's iterator. + +```cpp +template +using range_difference_t = iter_difference_t>; +``` + +### Parameters + +*`R`*\ +The range whose iterator will provide the difference type. + +### Example: `range_difference_t` + +The following example shows how `range_difference_t` is used to hold the distance between elements in a range: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + + auto findIt = ranges::find(v, 2); + // type of distance is ptrdiff_t + ranges::range_difference_t distance = ranges::distance(v.begin(), findIt); + cout << distance << endl; // outputs 1 +} +``` + +```output +1 +``` + +## `range_reference_t` + +Returns the reference type for the specified range's iterator. In other words, the reference type of the range's elements. + +```cpp +template +using range_reference_t = iter_reference_t>; +``` + +### Parameters + +*`R`*\ +The range for which the reference type of its iterator type is returned. + +### Example: `range_reference_t` + +The following example shows `range_reference_t` referring to the type of the elements in a range: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + + ranges::range_reference_t ref = v[0]; + + cout << ref << endl; // outputs 1 + cout << typeid(ref).name() << endl; // outputs int +} +``` + +```output +1 +int +``` + +## `range_rvalue_reference_t` + +Returns the rvalue reference type for the specified range's iterator. In other words, the rvalue reference type of the range's elements. + +```cpp +template +using range_rvalue_reference_t = iter_reference_t>; +``` + +### Parameters + +*`R`*\ +The range to get the rvalue reference type to its iterator type. + +### Example: `range_rvalue_reference_t` + +The following example shows `range_rvalue_reference_t` referring to a rvalue type of the elements in a range: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + + ranges::range_rvalue_reference_t elementRvalueType = v[0] * 10; // elementRvalueType is int&& + + cout << elementRvalueType << endl; // outputs 10 + cout << typeid(elementRvalueType).name() << endl; // outputs int +} +``` + +```output +10 +int +``` + +## `range_size_t` + +Returns the type of the `size` function for the specified [`sized_range`](range-concepts.md#sized_range). + +```cpp +template +using range_size_t = iter_reference_t>; +``` + +### Parameters + +*`R`*\ +The range to get the type of its `size` function. + +### Example: `range_size_t` + +The following example shows `range_size_t` referring to the number of elements in a range: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + + ranges::range_size_t size = v.size(); + cout << size << endl; // outputs 3 + cout << typeid(size).name(); // outputs unsigned __int64 +} +``` + +```output +3 +unsigned __int64 +``` + +## `range_value_t` + +Returns the value type of specified range's iterator. Or in other words, the type of the elements in the range. + +```cpp +template +using range_value_t = iter_value_t>; +``` + +### Parameters + +*`R`*\ +The range to get the value type of its iterator. + +### Example: `range_value_t` + +The following example shows how `range_value_t` refers to the type of elements in a range: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + vector v{1,2,3}; + ranges::range_value_t elementType = v[2]; // elementType is an int + + cout << elementType << endl; // outputs 3 + cout << typeid(elementType).name() << endl; // outputs int +} +``` + +```output +3 +unsigned int +``` + +## `sentinel_t` + +Returns the sentinel type for the specified range. + +```cpp +template +using sentinel_t = decltype(ranges::end(declval())); +``` + +### Parameters + +*`R`*\ +The range to get the sentinel type for. + +### Example: `sentinel_t` + +The following example shows using `sentinel_t` to determine whether the iterator type and sentinel type are the same: + +```cpp +// requires /std:c++20, or later + +#include +#include +#include + +int main() +{ + using namespace std; + + list myList{1, 2, 3}; + ranges::subrange count = std::views::counted(myList.begin(), myList.size()); + + ranges::iterator_t first; + ranges::sentinel_t last; + + // The iterator type and the sentinel type of a subrange + // obtained from views::counted are not the same + cout << boolalpha << is_same::value << endl; // outputs false + cout << "iter: " << typeid(first).name() << "\n\n end: " << typeid(last).name() << endl; +} +``` + +```output +false +iter: class std::counted_iterator > > > + + end: struct std::default_sentinel_t +``` + +## See also + +[``](ranges.md)\ +[Range adaptors](range-adaptors.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/ranges.md b/docs/standard-library/ranges.md index 9dfccf42ec..68d5e60304 100644 --- a/docs/standard-library/ranges.md +++ b/docs/standard-library/ranges.md @@ -1,24 +1,24 @@ --- title: "" -description: "Overview of the Standard Template Library (STL) ranges library" -ms.date: "04/14/2021" +description: "Get an overview of the Standard Template Library (STL) ranges." +ms.date: 01/27/2023 f1_keywords: [""] helpviewer_keywords: ["ranges"] --- # `` -At a high level, a range is something you can iterate over. A range abstracts iterators in a way that simplifies and amplifies your ability to use the Standard Template Library (STL). +At a high level, a *range* is something that you can iterate over. A range is represented by an iterator that marks the beginning of the range and a sentinel that marks the end of the range. The sentinel may be the same type as the begin iterator, or it may be different. The containers, such as `vector` and `list`, in the C++ Standard Library are ranges. A range abstracts iterators in a way that simplifies and amplifies your ability to use the Standard Template Library (STL). -STL algorithms usually take iterators that point to the portion of the collection they should operate on. Consider how you sort a `vector` today. To call `std::sort()`, you pass two iterators the mark the beginning and end of the `vector`. That provides flexibility, but passing the iterators to the algorithm is extra noise since most of the time you just want to sort the whole thing. +STL algorithms usually take iterators that point to the portion of the collection that they should operate on. For example, consider how you sort a `vector` by using `std::sort()`. You pass two iterators that mark the beginning and end of the `vector`. That provides flexibility, but passing the iterators to the algorithm is extra work because you probably just want to sort the whole thing. -With ranges, you can simply call `std::ranges::sort(myVector);` which is treated as if you had called `std::sort(myVector.begin(), myVector.end());` In range libraries, algorithms take ranges as parameters (although they can also take iterators, if you want). Examples of range algorithms available in `` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, and `none_of`, `find`, `find_if`, and `find_if_not`, `count` and `count_if`, `for_each` and `for_each_n`, `equal` and `mismatch`. +With ranges, you can call `std::ranges::sort(myVector);`, which is treated as if you called `std::sort(myVector.begin(), myVector.end());`. In range libraries, algorithms take ranges as parameters (although they can also take iterators, if you want). They can operate directly on collections. Examples of range algorithms available in `` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, `none_of`, `find`, `find_if`, `find_if_not`, `count`, `count_if`, `for_each`, `for_each_n`, `equal`, and `mismatch`. -Code that is easier to write and more readable is great, but the benefits of ranges go further than that. They also make it easier to filter and transform collections of data in part by allowing you to compose STL algorithms more easily. +But perhaps the most important benefit of ranges is that you can compose STL algorithms that operate on ranges in a style that's reminiscent of functional programming. ## A ranges example -Before ranges, if you wanted to transform only the elements of a collection that meet a certain criteria, you'd need to introduce an intermediate step to hold the results between operations. For example, let's say you want to build a vector of squares from only the elements in another vector that are divisible by 3. You'd write something like: +Before ranges, if you wanted to transform the elements of a collection that met a certain criterion, you needed to introduce an intermediate step to hold the results between operations. For example, if you wanted to build a vector of squares from the elements in another vector that are divisible by three, you could write something like: ```cpp std::vector input = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; @@ -31,33 +31,34 @@ std::transform(intermediate.begin(), intermediate.end(), std::back_inserter(outp With ranges, you can accomplish the same thing without needing the `intermediate` vector: ```cpp -// requires /std:c++latest -std::vector input = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; - -auto output = input | std::views::filter([](const int n) {return n % 3 == 0; }) | std::views::transform([](const int n) {return n * n; }); -``` +// requires /std:c++20 +std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; -Besides being easier to read, it avoids the memory allocation required for the `intermediate` vector and its contents, while also allowing you to compose two operations. +auto output = input + | std::views::filter([](const int n) {return n % 3 == 0; }) + | std::views::transform([](const int n) {return n * n; }); +``` -In the code above, each element that is divisible by three is combined with an operation to square that element. The '`|`' symbol chains the operations together, and is read left to right. +Besides being easier to read, this code avoids the memory allocation that's required for the `intermediate` vector and its contents. It also allows you to compose two operations. -The result, `output`, is itself a type of range called a view, which is discussed next. +In the preceding code, each element that's divisible by three is combined with an operation to square that element. The pipe (`|`) symbol chains the operations together and is read left to right. -> [!NOTE] -> The ranges examples require the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Because post-release updates to `` in the C++20 Standard are a work in progress, the features that require `std::views` aren't enabled yet under **`/std:c++20`**. +The result, `output`, is itself a kind of range called a *view*. ## Views -A view is a range with the added requirement that all view operations (default construction, move construction/assignment, copy construction/assignment (if present), destruction, begin and end) happen in constant time regardless of the number of elements in the view. +A view is a lightweight range. View operations--such as default construction, move construction/assignment, copy construction/assignment (if present), destruction, begin, and end--all happen in constant time regardless of the number of elements in the view. -How the elements in the view appear depends on the algorithm or operation that you specify for the view. In the example above, a view takes a range and returns a view of only those elements that are divisible by three. The underlying range is unchanged. +Views are created by range adaptors, which are discussed in the following section. For more information about the classes that implement various views, see [View classes](view-classes.md). -Views are composable. In the example above, the view of vector elements that are divisible by three is combined with the view that squares those elements. +How the elements in the view appear depends on the range adaptor that you use to create the view. In the previous example, a range adaptor takes a range and returns a view of the elements divisible by three. The underlying range is unchanged. -The elements of a view are evaluated lazily. That is, the transformations you apply to yield the elements in a view aren't evaluated until you ask for an element. For example, if you run the following code in a debugger, and put a breakpoint on the lines `auto divisible_by_three = ...` and `auto square = ...`, you'll see that you hit the `divisible_by_three` lambda breakpoint as each element in `input` is tested for divisibility by three. The `square` lambda breakpoint will be hit as the elements that are divisible by three are squared. +Views are composable, which is powerful. In the previous example, the view of vector elements that are divisible by three is combined with the view that squares those elements. + +The elements of a view are evaluated lazily. That is, the transformations that you apply to each element in a view aren't evaluated until you ask for the element. For example, if you run the following code in a debugger and put a breakpoint on the lines `auto divisible_by_three = ...` and `auto square = ...`, you'll see that you hit the `divisible_by_three` lambda breakpoint as each element in `input` is tested for divisibility by three. The `square` lambda breakpoint will be hit as the elements that are divisible by three are squared. ```cpp -// requires /std:c++latest +// requires /std:c++20 #include #include #include @@ -79,44 +80,87 @@ int main() } ``` -## View adaptors +For more information about views, see [`` view classes](view-classes.md). + +## Range adaptors -A view adaptor produces a view over a range. The range being viewed remains unchanged. A view doesn't own any elements. It allows you to iterate over the underlying range using customized behavior that you specify. +Range adaptors take a range and produce a view. Range adaptors produce lazily evaluated views. That is, you don't incur the cost of transforming every element in the range to produce the view. You only pay the cost to process an element in the view when you access that element. -In the example above, the first view provides the elements of `input` that are divisible by three. The other view takes the elements divisible by three, and provides the element's square. +In the previous example, the `filter` range adaptor creates a view named `input` that contains the elements that are divisible by three. The `transform` range adaptor takes the view of elements divisible by three and creates a view of those elements squared. -The `` library provides many kinds of view adaptors. Besides the filter and transform views, there are views that take or skip the first N elements of a range, reverse the order of a range, join ranges, skip elements of a range until a condition is met, transform the elements of a range, and more. +Range adaptors can be chained together (composed), which is the heart of the power and flexibility of ranges. Composing range adaptors allows you to overcome the problem that the previous STL algorithms aren't easily composable. -## Range adaptors +For more information about creating views, see [Range adaptors](range-adaptors.md). -A range adaptor produces a new range from an existing range and transforms how its elements are accessed. For example, a range adaptor might take a range and produce a new one that presents the elements from the original range in reverse order. Views, discussed earlier, are a common kind of range adaptor. +## Range algorithms -Range adaptors produce lazily evaluated ranges. That is, you don't incur the cost of transforming every element in the range--only the ones that you access, and at the time that you access them. +Some range algorithms take a range argument. An example is `std::ranges::sort(myVector);`. -Range adaptors come in many forms. For example, there are range adaptors that allow you to filter another range based on a predicate (`view::filter`), transform the elements in a range (`view::transform`), split a range (`view::split()`), and more. +The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace. The difference is that they have [concept-enforced constraints](range-concepts.md), and they accept either range arguments or more iterator-sentinel argument pairs. They can work directly on a container and can be easily chained together. -Range adaptors can be chained or composed--which is where the power and flexibility of ranges is most apparent. +## `` functions -## Range algorithms +The following functions are used to create iterators and sentinels for ranges, and to get the size of a range. + +| Function | Description | +|--|--| +| [`begin`](range-functions.md#begin)C++20 | Get an iterator to the first element in the range. | +| [`cbegin`](range-functions.md#cbegin)C++20 | Get a `const` iterator to the first element in the range. | +| [`cend`](range-functions.md#cend)C++20 | Get the sentinel at the end of the `const`-qualified range. | +| [`cdata`](range-functions.md#cdata)C++20 | Get a `const` pointer to the first element in the contiguous range. | +| [`crbegin`](range-functions.md#crbegin)C++20 | Get a reverse `const` iterator to the beginning of the range. | +| [`crend`](range-functions.md#crend)C++20 | Get the sentinel at the end of what `crbegin()` returns. | +| [`data`](range-functions.md#data)C++20 | Get a pointer to the first element in the contiguous range. | +| [`empty`](range-functions.md#empty)C++20 | Determine if the range is empty. | +| [`end`](range-functions.md#end)C++20 | Get the sentinel at the end of the range. | +| [`rbegin`](range-functions.md#rbegin)C++20 | Get a reverse iterator to the beginning of the range. | +| [`rend`](range-functions.md#rend)C++20 | Get a reverse iterator to the sentinel at the end of the range. | +| [`size`](range-functions.md#size)C++20 | Get the size of the range as an unsigned value. | +| [`ssize`](range-functions.md#ssize)C++20 | Get the size of the range as a signed value. | -Range algorithms have been created that take a range argument. For example, `std::ranges::sort(myVector);` +For more information, see [`` functions](range-functions.md). -The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace, except that they have concept-enforced constraints and accept range arguments or more general iterator-sentinel argument pairs. They can work directly on a container, and can be easily chained together. +## Range concepts -## Types of ranges +How you iterate over the elements of a range depends on its underlying iterator type. Ranges use C++ concepts that specify which iterator they support. -What you can do with a range depends on the underlying iterator type of the range. Range concepts are refinements of the `range` concept. In C++ 20, to say that concept X refines concept Y means that everything that satisfies Y also satisfies X--though not necessarily the other way around. For example, car, bus, and truck all refine vehicle. +In C++20, to say that concept *X* refines concept *Y* means that everything that satisfies concept *Y* also satisfies concept *X*. For example: *car*, *bus*, and *truck* all refine *vehicle*. -The range concepts mirror the hierarchy of iterator categories. This table lists various range concepts, along with the type of container they can be applied to: +Some range concepts mirror the hierarchy of iterator categories. The following table lists the range concepts, along with the types of containers that they can be applied to. | Range concept | Description | Supported containers | |--|--|--| -| `std::ranges::input_range` | Can iterate from beginning to end at least once | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset`
`basic_istream_view` | -| `std::ranges::forward_range` | Can iterate from beginning to end more than once) | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset` | -| `std::ranges::bidirectional_range` | Can iterate forward and backward more than once | `std::list`
`std::map`
`std::multimap`
`std::multiset`
`std::set`| -| `std::ranges::random_access_range` | Can access an arbitrary element (in constant time) using the `[]` operator) | `std::deque` | -| `std::ranges::contiguous_range` | The elements are stored in memory consecutively | `std::array`
`std::string`
`std::vector` | +| [`std::ranges::output_range`](range-concepts.md#output_range) | Can iterate forward. || +| [`std::ranges::input_range`](range-concepts.md#input_range) | Can iterate from beginning to end at least once. | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset`
`basic_istream_view`| +| [`std::ranges::forward_range`](range-concepts.md#forward_range) | Can iterate from beginning to end more than once. | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset` | +| [`std::ranges::bidirectional_range`](range-concepts.md#bidirectional_range) | Can iterate forward and backward more than once. | `std::list`
`std::map`
`std::multimap`
`std::multiset`
`std::set`| +| [`std::ranges::random_access_range`](range-concepts.md#random_access_range) | Can access an arbitrary element (in constant time) by using the `[]` operator. | `std::deque` | +| [`std::ranges::contiguous_range`](range-concepts.md#contiguous_range) | The elements are stored in memory consecutively. | `std::array`
`std::string`
`std::vector` | + +See [`` concepts](range-concepts.md) for more information about these concepts. + +## `` alias templates + +The following alias templates determine the types of iterators and sentinels for a range: + +| Alias template | Description | +|--|--| +| [`borrowed_iterator_t`](ranges-alias-templates.md#borrowed_iterator_t)C++20 | Determine if an iterator returned for a `range` refers to a range whose lifetime has ended. | +| [`borrowed_subrange_t`](ranges-alias-templates.md#borrowed_subrange_t)C++20 | Determine if an iterator returned for a `subrange` refers to a subrange whose lifetime has ended.| +| [`dangling`](ranges-alias-templates.md#dangling)C++20 | Indicates that the returned iterator of a `range`/`subrange` outlives the lifetime of the `range`/`subrange` it refers to. | +| [`iterator_t`](ranges-alias-templates.md#iterator_t)C++20 | Returns the iterator type of the specified range type. | +| [`range_difference_t`](ranges-alias-templates.md#range_difference_t)C++20 | Returns the difference type of the specified range's iterator type. | +| [`range_reference_t`](ranges-alias-templates.md#range_reference_t)C++20 | Returns the reference type of the specified range's iterator type. | +| [`range_rvalue_reference_t`](ranges-alias-templates.md#range_rvalue_reference_t)C++20 | Returns the rvalue reference type for the specified range's iterator type. In other words, the rvalue reference type of the range's elements. | +| [`range_size_t`](ranges-alias-templates.md#range_size_t)C++20 | Returns the type used to report the specified range's size. | +| [`range_value_t`](ranges-alias-templates.md#range_value_t)C++20 | Returns the value type of the specified range's iterator type. Or in other words, the type of the elements in the range. | +| [`sentinel_t`](ranges-alias-templates.md#sentinel_t)C++20 | Returns the sentinel type of the specified range. | + +For more information about these alias templates, see [`` alias templates](ranges-alias-templates.md). ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) +[`` functions](range-functions.md)\ +[`` concepts](range-concepts.md)\ +[Range adaptors](range-adaptors.md)\ +[Header files reference](../standard-library/cpp-standard-library-header-files.md) \ No newline at end of file diff --git a/docs/standard-library/raw-storage-iterator-class.md b/docs/standard-library/raw-storage-iterator-class.md index 4a41772f09..0e625fb1ed 100644 --- a/docs/standard-library/raw-storage-iterator-class.md +++ b/docs/standard-library/raw-storage-iterator-class.md @@ -1,10 +1,10 @@ --- -description: "Learn more about: raw_storage_iterator Class" title: "raw_storage_iterator Class" -ms.date: "11/04/2016" +description: "Learn more about: raw_storage_iterator Class" +ms.date: 06/17/2022 f1_keywords: ["memory/std::raw_storage_iterator", "memory/std::raw_storage_iterator::element_type", "memory/std::raw_storage_iterator::iter_type"] helpviewer_keywords: ["std::raw_storage_iterator [C++]", "std::raw_storage_iterator [C++], element_type", "std::raw_storage_iterator [C++], iter_type"] -ms.assetid: 6f033f15-f48e-452a-a326-647ea2cf346f +ms.custom: devdivchpfy22 --- # raw_storage_iterator Class @@ -29,7 +29,7 @@ The type of object for which storage is being allocated. The class describes an output iterator that constructs objects of type `Type` in the sequence it generates. An object of class `raw_storage_iterator`\< **ForwardIterator**, **Type**> accesses storage through a forward iterator object, of class `ForwardIterator`, that you specify when you construct the object. For an object first of class `ForwardIterator`, the expression **&\*first** must designate unconstructed storage for the next object (of type `Type`) in the generated sequence. -This adaptor class is used when it is necessary to separate memory allocation and object construction. The `raw_storage_iterator` can be used to copy objects into uninitialized storage, such as memory allocated using the `malloc` function. +This adaptor class is used when it's necessary to separate memory allocation and object construction. The `raw_storage_iterator` can be used to copy objects into uninitialized storage, such as memory allocated using the `malloc` function. ## Members @@ -92,7 +92,7 @@ A reference to the raw storage iterator #### Remarks -The requirements for a `ForwardIterator` are that the raw storage iterator must satisfy require only the expression \* *ii* = *t* be valid and that it says nothing about the **`operator`** or the `operator=` on their own. The member operators in this implementation returns **\*this**, so that [operator=](#op_eq)(**constType**&) can perform the actual store in an expression, such as \* *ptr* = `val`. +The requirements for a `ForwardIterator` are that the raw storage iterator must satisfy, require only the expression \* *ii* = *t* be valid and that it says nothing about the **`operator`** or the `operator=` on their own. The member operators in this implementation, returns **`*this`**, so that [operator=](#op_eq)(**constType**&) can perform the actual store in an expression, such as \* *ptr* = `val`. #### Example @@ -113,7 +113,7 @@ public: cout << "Constructing " << i << endl; x = i; bIsConstructed = true; - }; + } Int &operator=(int i) { @@ -122,7 +122,7 @@ public: cout << "Copying " << i << endl; x = i; return *this; - }; + } int x; @@ -166,7 +166,7 @@ The operator inserts `val` into memory, and then returns a reference to the raw #### Remarks -The requirements for a `ForwardIterator` state that the raw storage iterator must satisfy require only the expression \* *ii* = *t* be valid, and that it says nothing about the **`operator`** or the `operator=` on their own. These member operators return **`*this`**. +The requirements for a `ForwardIterator` state that the raw storage iterator must satisfy, require only the expression \* *ii* = *t* be valid, and that it says nothing about the **`operator`** or the `operator=` on their own. These member operators return **`*this`**. The assignment operator constructs the next object in the output sequence using the stored iterator value `first`, by evaluating the placement new expression `new ( (void*) & *first ) Type( val )`. @@ -189,14 +189,14 @@ public: cout << "Constructing " << i << endl; x = i; bIsConstructed = true; - }; + } Int &operator=( int i ) { if ( !bIsConstructed ) cout << "Not constructed.\n"; cout << "Copying " << i << endl; x = i; return *this; - }; + } int x; private: bool bIsConstructed; @@ -232,15 +232,15 @@ raw_storage_iterator operator++(int); #### Return Value -An raw storage iterator or a reference to an raw storage iterator. +A raw storage iterator or a reference to a raw storage iterator. #### Remarks The first operator eventually attempts to extract and store an object of type `CharType` from the associated input stream. The second operator makes a copy of the object, increments the object, and then returns the copy. -The first preincrement operator increments the stored output iterator object, and then returns **\*this**. +The first preincrement operator increments the stored output iterator object, and then returns **`*this`**. -The second postincrement operator makes a copy of **\*this**, increments the stored output iterator object, and then returns the copy. +The second postincrement operator makes a copy of **`*this`**, increments the stored output iterator object, and then returns the copy. The constructor stores `first` as the output iterator object. @@ -263,7 +263,7 @@ int main( void ) *it = 2 * i; }; - for ( int i = 0; i < 5; i++ ) cout << "array " << i << " = " << pInt[i] << endl;; + for ( int i = 0; i < 5; i++ ) cout << "array " << i << " = " << pInt[i] << endl; delete[] pInt; } @@ -309,13 +309,13 @@ public: cout << "Constructing " << i << endl; x = i; bIsConstructed = true; - }; + } Int &operator=( int i ) { if (!bIsConstructed) cout << "Error! I'm not constructed!\n"; cout << "Copying " << i << endl; x = i; return *this; - }; + } int x; bool bIsConstructed; }; @@ -334,7 +334,7 @@ int main( void ) std::copy( l.begin( ), l.end( ), pInt ); // C4996 for (unsigned int i = 0; i < l.size( ); i++) - cout << "array " << i << " = " << pInt[i].x << endl;; + cout << "array " << i << " = " << pInt[i].x << endl; memset (pInt, 0, sizeof(Int)*l.size( )); // hack: make sure bIsConstructed is false diff --git a/docs/standard-library/recursive-directory-iterator-class.md b/docs/standard-library/recursive-directory-iterator-class.md index 96ae72e4d3..12ce5fff52 100644 --- a/docs/standard-library/recursive-directory-iterator-class.md +++ b/docs/standard-library/recursive-directory-iterator-class.md @@ -1,10 +1,12 @@ --- description: "Learn more about: recursive_directory_iterator Class" title: "recursive_directory_iterator Class" -ms.date: "09/10/2018" +ms.date: 06/17/2022 f1_keywords: ["filesystem/std::tr2::sys::recursive_directory_iterator"] ms.assetid: 79a061bd-5b64-404c-97e8-749c888c2ced +ms.custom: devdivchpfy22 --- + # recursive_directory_iterator Class Describes an input iterator that sequences through the filenames in a directory, possibly descending into subdirectories recursively. For an iterator `X`, the expression `*X` evaluates to an object of class `directory_entry` that wraps the filename and anything known about its status. @@ -40,7 +42,7 @@ will call visit with the arguments `path("abc/def/ghi")` and `path("abc/jkl")`. 1. A directory symlink will be scanned only if you construct a `recursive_directory_iterator` with a `directory_options` argument whose value is `directory_options::follow_directory_symlink`. -1. If you call `disable_recursion_pending` then a subsequent directory encountered during an increment will not be recursively scanned. +1. If you call `disable_recursion_pending`, a subsequent directory encountered during an increment won't be recursively scanned. ### Constructors @@ -65,7 +67,7 @@ will call visit with the arguments `path("abc/def/ghi")` and `path("abc/jkl")`. |-|-| |[operator!=](#op_neq)|Returns `!(*this == right)`.| |[operator=](#op_as)|The defaulted member assignment operators behave as expected.| -|[operator==](#op_eq)|Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both are not end-of-sequence-iterators.| +|[operator==](#op_eq)|Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both aren't end-of-sequence-iterators.| |[operator*](#op_multiply)|Returns `myentry`.| |[operator->](#op_cast)|Returns `&**this`.| |[operator++](#op_increment)|Increments the `recursive_directory_iterator`.| @@ -138,7 +140,7 @@ The [recursive_directory_iterator](../standard-library/recursive-directory-itera ## recursive_directory_iterator::operator== -Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both are not end-of-sequence-iterators. +Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both aren't end-of-sequence-iterators. ```cpp bool operator==(const recursive_directory_iterator& right) const; @@ -250,7 +252,7 @@ The `recursive_directory_iterator` of which the constructed `recursive_directory The first constructor produces an end-of-sequence iterator. The second and third constructors store **`false`** in `no_push` and `directory_options::none` in `myoptions`, then attempt to open and read *pval* as a directory. If successful, they initialize `mystack` and `myentry` to designate the first non-directory filename in the nested sequence; otherwise they produce an end-of-sequence iterator. -The fourth and fifth constructors behave the same as the second and third, except that they first store *opts* in `myoptions`. The defaulted construtors behave as expected. +The fourth and fifth constructors behave the same as the second and third, except that they first store *opts* in `myoptions`. The default constructor behaves as expected. ## See also diff --git a/docs/standard-library/ref-view-class.md b/docs/standard-library/ref-view-class.md new file mode 100644 index 0000000000..179d45ce0f --- /dev/null +++ b/docs/standard-library/ref-view-class.md @@ -0,0 +1,216 @@ +--- +title: ref_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) ref_view class, which is a view that references the elements of another range. It's essentially a view of the elements of another range." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::ref_view", "ranges/std::ref_view::base", "ranges/std::ref_view::begin", "ranges/std::ref_view::data", "ranges/std::ref_view::empty", "ranges/std::ref_view::end", "ranges/std::ref_view::size", "ranges/std::ref_view::operator bool", "ranges/std::ref_view::back", "ranges/std::ref_view::front", "ranges/std::ref_view::operator[]"] +helpviewer_keywords: ["std::ranges::ref_view [C++]", "std::ranges::ref_view::base [C++]", "std::ranges::ref_view::begin [C++]", "std::ranges::ref_view::data [C++]", "std::ranges::ref_view::empty [C++]", "std::ranges::ref_view::end [C++]", "std::ranges::ref_view::size [C++]", "std::ranges::ref_view::operator bool [C++]", "std::ranges::ref_view::back [C++]", "std::ranges::ref_view::front [C++]", "std::ranges::ref_view::operator[] [C++]"] +dev_langs: ["C++"] +--- +# `ref_view` class (C++ Standard Library) + + A view that references the elements that belong to another range. + +## Syntax + +```cpp +template + requires std::is_object_v +class ref_view : public ranges::view_interface>; +``` + +### Template parameters + +*`R`*\ + The range to reference. + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `ref_view`. | +| [`base`](#base)C++20 | Get a reference to the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element in the referenced range. | +| [`empty`](#empty)C++20 | Test whether this `ref_view` is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of this `ref_view`. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether this `ref_view` isn't empty. | + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::all`](range-adaptors.md#all) or [`views::common`](range-adaptors.md#common) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Yes | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Yes | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `ref_view` + +```cpp +// construct a ref_view from a range +template R> +constexpr ref_view(R&& rg); +``` + +### Parameters + +*`rg`*\ +The range to reference. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `ref_view` instance. + +### Remarks + +The best way to create a `ref_view` is by using the [`views::all`](range-adaptors.md#all) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +A `ref_view` is useful for converting a container to a view. For example, you can use `ref_view` to convert a `vector` to a view, which makes it inexpensive to pass the elements of the vector around. + +### Example: `ref_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3}; + auto refView = std::views::all(v); + std::cout << &refView[1] << " : " << &v[1]; // outputs two identical memory addresses, e.g. 00000239AFAFDF90 : 00000239AFAFDF90 + refView[0] = 10; // modifies v[0] + std::cout << "\n" << v[0]; // 10 +} +``` + +```output +00000239AFAFDF90 : 00000239AFAFDF90 +10 +``` + +## `base` + +Gets a copy of the underlying range. + +```cpp +constexpr R& base() const; +``` + +### Parameters + +None. + +### Return value + +The underlying range. + +## `begin` + +Get an iterator to the first element in the `ref_view`. + +```cpp +constexpr iterator_t begin() const; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in this `ref_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `data` + +Get a pointer to the first element in this `ref_view`. The elements in the range must be contiguous. + +```cpp +constexpr auto data() const requires contiguous_range; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element. + +## `empty` + +Test whether this `ref_view` is empty. + +```cpp +constexpr bool empty() const +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the `ref_view` contains no elements. Otherwise, `false`. + +## `end` + +Get the sentinel at the end of this `ref_view`. + +```cpp +constexpr sentinel_t end() const +``` + +### Return value + +The sentinel that follows the last element in this `ref_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `ref_view`. + +## See also + +[``](ranges.md)\ +[`all` range adaptor](range-adaptors.md#all)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/regex-functions.md b/docs/standard-library/regex-functions.md index c30112961b..912335daf9 100644 --- a/docs/standard-library/regex-functions.md +++ b/docs/standard-library/regex-functions.md @@ -3,19 +3,18 @@ description: "Learn more about: functions" title: " functions" ms.date: "09/10/2018" f1_keywords: ["regex/std::regex_match", "regex/std::regex_replace", "regex/std::regex_search", "regex/std::swap"] -ms.assetid: 91a8314b-6f7c-4e33-b7d6-d8583dd75585 helpviewer_keywords: ["std::regex_match [C++]", "std::regex_replace [C++]", "std::regex_search [C++]", "std::swap [C++]", "std::swap [C++]"] --- # `` functions |Name|Description| |-|-| -|[regex_match](#regex_match)|Tests whether a regular expression matches the entire target string.| -|[regex_replace](#regex_replace)|Replaces matched regular expressions.| -|[regex_search](#regex_search)|Searches for a regular expression match.| -|[swap](#swap)|Swaps two `basic_regex` or `match_results` objects.| +|[`regex_match`](#regex_match)|Tests whether a regular expression matches the entire target string.| +|[`regex_replace`](#regex_replace)|Replaces matched regular expressions.| +|[`regex_search`](#regex_search)|Searches for a regular expression match.| +|[`swap`](#swap)|Swaps two `basic_regex` or `match_results` objects.| -## regex_match +## `regex_match` Tests whether a regular expression matches the entire target string. @@ -70,51 +69,51 @@ bool regex_match( ### Parameters -*BidIt*\ +*`BidIt`*\ The iterator type for submatches. For common cases this one of `string::const_iterator`, `wstring::const_iterator`, `const char*` or `const wchar_t*`. -*Alloc*\ +*`Alloc`*\ The match results allocator class. -*Elem*\ +*`Elem`*\ The type of elements to match. For common cases this is `string`, `wstring`, `char*` or `wchar_t*`. -*RXtraits*\ +*`RXtraits`*\ Traits class for elements. -*Alloc2*\ +*`Alloc2`*\ The regular expression allocator class. -*IOtraits*\ +*`IOtraits`*\ The string traits class. -*IOalloc*\ +*`IOalloc`*\ The string allocator class. -*flags*\ +*`flags`*\ Flags for matches. -*first*\ +*`first`*\ Beginning of sequence to match. -*last*\ +*`last`*\ End of sequence to match. -*match*\ -The match results. Corresponds to Elem type: [smatch](../standard-library/regex-typedefs.md#smatch) for `string`, [wsmatch](../standard-library/regex-typedefs.md#wsmatch) for `wstring`, [cmatch](../standard-library/regex-typedefs.md#cmatch) for `char*` or [wcmatch](../standard-library/regex-typedefs.md#wcmatch) for `wchar_t*`. +*`match`*\ +The match results. Corresponds to Elem type: [`smatch`](../standard-library/regex-typedefs.md#smatch) for `string`, [`wsmatch`](../standard-library/regex-typedefs.md#wsmatch) for `wstring`, [`cmatch`](../standard-library/regex-typedefs.md#cmatch) for `char*` or [`wcmatch`](../standard-library/regex-typedefs.md#wcmatch) for `wchar_t*`. -*ptr*\ -Pointer to beginning of sequence to match. If *ptr* is `char*`, then use `cmatch` and `regex`. If *ptr* is `wchar_t*` then use `wcmatch` and `wregex`. +*`ptr`*\ +Pointer to beginning of sequence to match. If *`ptr`* is `char*`, then use `cmatch` and `regex`. If *`ptr`* is `wchar_t*` then use `wcmatch` and `wregex`. -*re*\ +*`re`*\ The regular expression to match. Type `regex` for `string` and `char*`, or `wregex` for `wstring` and `wchar_t*`. -*str*\ -String to match. Corresponds to the type of *Elem*. +*`str`*\ +String to match. Corresponds to the type of *`Elem`*. ### Remarks -Each template function returns true only if the entire operand sequence *str* exactly matches the regular expression argument *re*. Use [regex_search](../standard-library/regex-functions.md#regex_search) to match a substring within a target sequence and `regex_iterator` to find multiple matches. The functions that take a `match_results` object set its members to reflect whether the match succeeded and if so what the various capture groups in the regular expression captured. +Each template function returns true only if the entire operand sequence *`str`* exactly matches the regular expression argument *`re`*. Use [`regex_search`](../standard-library/regex-functions.md#regex_search) to match a substring within a target sequence and `regex_iterator` to find multiple matches. The functions that take a `match_results` object set its members to reflect whether the match succeeded and if so what the various capture groups in the regular expression captured. The functions that take a `match_results` object set its members to reflect whether the match succeeded and if so what the various capture groups in the regular expression captured. @@ -182,7 +181,7 @@ Regex found in Drizzle The matching text is: 2014-04-02 ``` -## regex_replace +## `regex_replace` Replaces matched regular expressions. @@ -206,45 +205,45 @@ basic_string regex_replace( ### Parameters -*OutIt*\ +*`OutIt`*\ The iterator type for replacements. -*BidIt*\ +*`BidIt`*\ The iterator type for submatches. -*RXtraits*\ +*`RXtraits`*\ Traits class for elements. -*Alloc*\ +*`Alloc`*\ The regular expression allocator class. -*Elem*\ +*`Elem`*\ The type of elements to match. -*flags*\ +*`flags`*\ Flags for matches. -*first*\ +*`first`*\ Beginning of sequence to match. -*fmt*\ +*`fmt`*\ The format for replacements. -*last*\ +*`last`*\ End of sequence to match. -*out*\ +*`out`*\ The output iterator. -*re*\ +*`re`*\ The regular expression to match. -*str*\ +*`str`*\ String to match. ### Remarks -The first function constructs a [regex_iterator Class](../standard-library/regex-iterator-class.md) object `iter(first, last, re, flags)` and uses it to split its input range `[first, last)` into a series of subsequences `T0 M0 T1 M1...TN-1 MN-1 TN`, where `Mn` is the nth match detected by the iterator. If no matches are found, `T0` is the entire input range and `N` is zero. If `(flags & format_first_only) != 0` only the first match is used, `T1` is all of the input text that follows the match, and `N` is 1. For each `i` in the range `[0, N)`, if `(flags & format_no_copy) == 0` it copies the text in the range `Ti` to the iterator *out*. It then calls `m.format(out, fmt, flags)`, where `m` is the `match_results` object returned by the iterator object `iter` for the subsequence `Mi`. Finally, if `(flags & format_no_copy) == 0` it copies the text in the range `TN` to the iterator *out*. The function returns *out*. +The first function constructs a [`regex_iterator` Class](../standard-library/regex-iterator-class.md) object `iter(first, last, re, flags)` and uses it to split its input range `[first, last)` into a series of subsequences `T0 M0 T1 M1...TN-1 MN-1 TN`, where `Mn` is the nth match detected by the iterator. If no matches are found, `T0` is the entire input range and `N` is zero. If `(flags & format_first_only) != 0` only the first match is used, `T1` is all of the input text that follows the match, and `N` is 1. For each `i` in the range `[0, N)`, if `(flags & format_no_copy) == 0` it copies the text in the range `Ti` to the iterator *`out`*. It then calls `m.format(out, fmt, flags)`, where `m` is the `match_results` object returned by the iterator object `iter` for the subsequence `Mi`. Finally, if `(flags & format_no_copy) == 0` it copies the text in the range `TN` to the iterator *`out`*. The function returns *`out`*. The second function constructs a local variable `result` of type `basic_string` and calls `regex_replace(back_inserter(result), str.begin(), str.end(), re, fmt, flags)`. It returns `result`. @@ -290,7 +289,7 @@ replacement == AdAeAf replacement == Adaeaf ``` -## regex_search +## `regex_search` Searches for a regular expression match. @@ -339,51 +338,51 @@ bool regex_search( ### Parameters -*BidIt*\ +*`BidIt`*\ The iterator type for submatches. -*Alloc*\ +*`Alloc`*\ The match results allocator class. -*Elem*\ +*`Elem`*\ The type of elements to match. -*RXtraits*\ +*`RXtraits`*\ Traits class for elements. -*Alloc2*\ +*`Alloc2`*\ The regular expression allocator class. -*IOtraits*\ +*`IOtraits`*\ The string traits class. -*IOalloc*\ +*`IOalloc`*\ The string allocator class. -*flags*\ +*`flags`*\ Flags for matches. -*first*\ +*`first`*\ Beginning of sequence to match. -*last*\ +*`last`*\ End of sequence to match. -*match*\ +*`match`*\ The match results. -*ptr*\ +*`ptr`*\ Pointer to beginning of sequence to match. -*re*\ +*`re`*\ The regular expression to match. -*str*\ +*`str`*\ String to match. ### Remarks -Each template function returns true only if a search for its regular expression argument *re* in its operand sequence succeeds. The functions that take a `match_results` object set its members to reflect whether the search succeeded and if so what the various capture groups in the regular expression captured. +Each template function returns true only if a search for its regular expression argument *`re`* in its operand sequence succeeds. The functions that take a `match_results` object set its members to reflect whether the search succeeded and if so what the various capture groups in the regular expression captured. ### Example @@ -441,7 +440,7 @@ search(string, "abc") == true matched: "abc" ``` -## swap +## `swap` Swaps two `basic_regex` or `match_results` objects. @@ -459,15 +458,15 @@ void swap( ### Parameters -*Elem*\ +*`Elem`*\ The type of elements to match. -*RXtraits*\ +*`RXtraits`*\ Traits class for elements. ### Remarks -The template functions swap the contents of their respective arguments in constant time and do not throw exceptions. +The template functions swap the contents of their respective arguments in constant time and don't throw exceptions. ### Example @@ -506,11 +505,11 @@ string == aaa ## See also -[\](../standard-library/regex.md)\ -[regex_constants Class](../standard-library/regex-constants-class.md)\ -[regex_error Class](../standard-library/regex-error-class.md)\ -[regex_iterator Class](../standard-library/regex-iterator-class.md)\ -[\ operators](../standard-library/regex-operators.md)\ -[regex_token_iterator Class](../standard-library/regex-token-iterator-class.md)\ -[regex_traits Class](../standard-library/regex-traits-class.md)\ -[\ typedefs](../standard-library/regex-typedefs.md) +[``](../standard-library/regex.md)\ +[`regex_constants` Class](../standard-library/regex-constants-class.md)\ +[`regex_error` Class](../standard-library/regex-error-class.md)\ +[`regex_iterator` Class](../standard-library/regex-iterator-class.md)\ +[`` operators](../standard-library/regex-operators.md)\ +[`regex_token_iterator` Class](../standard-library/regex-token-iterator-class.md)\ +[`regex_traits` Class](../standard-library/regex-traits-class.md)\ +[`` typedefs](../standard-library/regex-typedefs.md) diff --git a/docs/standard-library/regex-iterator-class.md b/docs/standard-library/regex-iterator-class.md index 89b384547a..4858e1d933 100644 --- a/docs/standard-library/regex-iterator-class.md +++ b/docs/standard-library/regex-iterator-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: regex_iterator Class" title: "regex_iterator Class" -ms.date: "09/10/2018" +ms.date: 06/17/2022 f1_keywords: ["regex/std::regex_iterator", "regex/std::regex_iterator::operator==", "regex/std::regex_iterator::operator!=", "regex/std::regex_iterator::operator*", "regex/std::regex_iterator::operator->", "regex/std::regex_iterator::operator++"] helpviewer_keywords: ["std::regex_iterator", "std::regex_iterator::operator==", "std::regex_iterator::operator!=", "std::regex_iterator::operator*", "std::regex_iterator::operator->", "std::regex_iterator::operator++"] ms.assetid: 0cfd8fd0-5a95-4f3c-bf8e-6ef028c423d3 +ms.custom: devdivchpfy22 --- + # regex_iterator Class Iterator class for matches. @@ -69,7 +71,7 @@ The class template describes a constant forward iterator object. It extracts obj ## Examples -See the following topics for examples on regular expressions: +See the following articles for examples on regular expressions: - [regex_match](../standard-library/regex-functions.md#regex_match) @@ -184,7 +186,7 @@ regex_iterator& operator++(int); ### Remarks -If the current match has no characters the first operator calls `regex_search(begin, end, match, *pregex, flags | regex_constants::match_prev_avail | regex_constants::match_not_null)`; otherwise it advances the stored value `begin` to point to the first character after the current match then calls `regex_search(begin, end, match, *pregex, flags | regex_constants::match_prev_avail)`. In either case, if the search fails the operator sets the object to an end-of-sequence iterator. The operator returns the object. +If the current match has no characters, the first operator calls `regex_search(begin, end, match, *pregex, flags | regex_constants::match_prev_avail | regex_constants::match_not_null)`; otherwise it advances the stored value `begin` to point to the first character after the current match then calls `regex_search(begin, end, match, *pregex, flags | regex_constants::match_prev_avail)`. In either case, if the search fails the operator sets the object to an end-of-sequence iterator. The operator returns the object. The second operator makes a copy of the object, increments the object, then returns the copy. diff --git a/docs/standard-library/regex-operators.md b/docs/standard-library/regex-operators.md index 093cb93bd7..f062a76a49 100644 --- a/docs/standard-library/regex-operators.md +++ b/docs/standard-library/regex-operators.md @@ -1,19 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["regex/std::operator!=", "regex/std::operator>", "regex/std::operator>=", "regex/std::operator<", "regex/std::operator<=", "regex/std::operator==", "regex/std::operator<<"] -ms.assetid: ec623e65-c186-491f-aa18-6b12b47e1127 --- # `` operators -[operator!=](#op_neq)\ -[`operator>`](#op_gt)\ -[`operator>=`](#op_gt_eq)\ -[`operator<`](#op_lt)\ -[`operator<<`](#op_lt_lt)\ -[`operator<=`](#op_lt_eq)\ -[operator==](#op_eq_eq) +The `` header provides the following operators: ## operator!= diff --git a/docs/standard-library/regex-traits-class.md b/docs/standard-library/regex-traits-class.md index 512a4b7093..95fd141c40 100644 --- a/docs/standard-library/regex-traits-class.md +++ b/docs/standard-library/regex-traits-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: regex_traits Class" title: "regex_traits Class" -ms.date: "09/10/2018" +description: "Learn more about: regex_traits Class" +ms.date: 09/10/2018 f1_keywords: ["regex/std::regex_traits", "regex/std::regex_traits::char_type", "regex/std::regex_traits::size_type", "regex/std::regex_traits::string_type", "regex/std::regex_traits::locale_type", "regex/std::regex_traits::char_class_type", "regex/std::regex_traits::length", "regex/std::regex_traits::translate", "regex/std::regex_traits::translate_nocase", "regex/std::regex_traits::transform", "regex/std::regex_traits::transform_primary", "regex/std::regex_traits::lookup_classname", "regex/std::regex_traits::lookup_collatename", "regex/std::regex_traits::isctype", "regex/std::regex_traits::value", "regex/std::regex_traits::imbue", "regex/std::regex_traits::getloc"] helpviewer_keywords: ["std::regex_traits [C++]", "std::regex_traits [C++], char_type", "std::regex_traits [C++], size_type", "std::regex_traits [C++], string_type", "std::regex_traits [C++], locale_type", "std::regex_traits [C++], char_class_type", "std::regex_traits [C++], length", "std::regex_traits [C++], translate", "std::regex_traits [C++], translate_nocase", "std::regex_traits [C++], transform", "std::regex_traits [C++], transform_primary", "std::regex_traits [C++], lookup_classname", "std::regex_traits [C++], lookup_collatename", "std::regex_traits [C++], isctype", "std::regex_traits [C++], value", "std::regex_traits [C++], imbue", "std::regex_traits [C++], getloc"] -ms.assetid: bc5a5eed-32fc-4eb7-913d-71c42e729e81 --- # regex_traits Class @@ -24,7 +23,7 @@ The character element type to describe. ## Remarks -The class template describes various regular expression traits for type *Elem*. The class template [basic_regex Class](../standard-library/basic-regex-class.md) uses this information to manipulate elements of type *Elem*. +The class template describes various regular expression traits for type *Elem*. The class template [`basic_regex`](../standard-library/basic-regex-class.md) uses this information to manipulate elements of type *Elem*. Each `regex_traits` object holds an object of type `regex_traits::locale` which is used by some of its member functions. The default locale is a copy of `regex_traits::locale()`. The member function `imbue` replaces the locale object, and the member function `getloc` returns a copy of the locale object. diff --git a/docs/standard-library/regex-typedefs.md b/docs/standard-library/regex-typedefs.md index d9d1058fe1..4c7f083ccd 100644 --- a/docs/standard-library/regex-typedefs.md +++ b/docs/standard-library/regex-typedefs.md @@ -1,30 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["regex/std::cmatch", "regex/std::cregex_iterator", "regex/std::cregex_token_iterator", "regex/std::csub_match", "regex/std::regex", "regex/std::smatch", "regex/std::sregex_iterator", "regex/std::sregex_token_iterator", "regex/std::ssub_match", "regex/std::wcmatch", "regex/std::wcregex_iterator", "regex/std::wcregex_token_iterator", "regex/std::wcsub_match", "regex/std::wregex", "regex/std::wsmatch", "regex/std::wsregex_iterator", "regex/std::wsregex_token_iterator", "regex/std::wssub_match"] -ms.assetid: e6a69067-106c-4a24-9e08-7c867a3a2260 --- # `` typedefs -[cmatch](#cmatch)\ -[cregex_iterator](#cregex_iterator)\ -[cregex_token_iterator](#cregex_token_iterator)\ -[csub_match](#csub_match)\ -[regex](#regex)\ -[smatch](#smatch)\ -[sregex_iterator](#sregex_iterator)\ -[sregex_token_iterator](#sregex_token_iterator)\ -[ssub_match](#ssub_match)\ -[wcmatch](#wcmatch)\ -[wcregex_iterator](#wcregex_iterator)\ -[wcregex_token_iterator](#wcregex_token_iterator)\ -[wcsub_match](#wcsub_match)\ -[wregex](#wregex)\ -[wsmatch](#wsmatch)\ -[wsregex_iterator](#wsregex_iterator)\ -[wsregex_token_iterator](#wsregex_token_iterator)\ -[wssub_match](#wssub_match) +The `` header provides the following typedefs: ## cmatch Typedef @@ -36,7 +18,7 @@ typedef match_results cmatch; ### Remarks -The type describes a specialization of class template [match_results Class](../standard-library/match-results-class.md) for iterators of type `const char*`. +The type describes a specialization of class template [`match_results`](../standard-library/match-results-class.md) for iterators of type `const char*`. ## cregex_iterator Typedef @@ -48,7 +30,7 @@ typedef regex_iterator cregex_iterator; ### Remarks -The type describes a specialization of class template [regex_iterator Class](../standard-library/regex-iterator-class.md) for iterators of type `const char*`. +The type describes a specialization of class template [`regex_iterator`](../standard-library/regex-iterator-class.md) for iterators of type `const char*`. ## cregex_token_iterator Typedef @@ -60,7 +42,7 @@ typedef regex_token_iterator cregex_token_iterator; ### Remarks -The type describes a specialization of class template [regex_token_iterator Class](../standard-library/regex-token-iterator-class.md) for iterators of type `const char*`. +The type describes a specialization of class template [`regex_token_iterator`](../standard-library/regex-token-iterator-class.md) for iterators of type `const char*`. ## csub_match Typedef @@ -72,7 +54,7 @@ typedef sub_match csub_match; ### Remarks -The type describes a specialization of class template [sub_match Class](../standard-library/sub-match-class.md) for iterators of type `const char*`. +The type describes a specialization of class template [`sub_match`](../standard-library/sub-match-class.md) for iterators of type `const char*`. ## regex Typedef @@ -84,7 +66,7 @@ typedef basic_regex regex; ### Remarks -The type describes a specialization of class template [basic_regex Class](../standard-library/basic-regex-class.md) for elements of type **`char`**. +The type describes a specialization of class template [`basic_regex`](../standard-library/basic-regex-class.md) for elements of type **`char`**. > [!NOTE] > High-bit characters will have unpredictable results with `regex`. Values outside the range of 0 to 127 may result in undefined behavior. @@ -99,7 +81,7 @@ typedef match_results smatch; ### Remarks -The type describes a specialization of class template [match_results Class](../standard-library/match-results-class.md) for iterators of type `string::const_iterator`. +The type describes a specialization of class template [`match_results`](../standard-library/match-results-class.md) for iterators of type `string::const_iterator`. ## sregex_iterator Typedef @@ -111,7 +93,7 @@ typedef regex_iterator sregex_iterator; ### Remarks -The type describes a specialization of class template [regex_iterator Class](../standard-library/regex-iterator-class.md) for iterators of type `string::const_iterator`. +The type describes a specialization of class template [`regex_iterator`](../standard-library/regex-iterator-class.md) for iterators of type `string::const_iterator`. ## sregex_token_iterator Typedef @@ -123,7 +105,7 @@ typedef regex_token_iterator sregex_token_iterator; ### Remarks -The type describes a specialization of class template [regex_token_iterator Class](../standard-library/regex-token-iterator-class.md) for iterators of type `string::const_iterator`. +The type describes a specialization of class template [`regex_token_iterator`](../standard-library/regex-token-iterator-class.md) for iterators of type `string::const_iterator`. ## ssub_match Typedef @@ -135,7 +117,7 @@ typedef sub_match ssub_match; ### Remarks -The type describes a specialization of class template [sub_match Class](../standard-library/sub-match-class.md) for iterators of type `string::const_iterator`. +The type describes a specialization of class template [`sub_match`](../standard-library/sub-match-class.md) for iterators of type `string::const_iterator`. ## wcmatch Typedef @@ -147,7 +129,7 @@ typedef match_results wcmatch; ### Remarks -The type describes a specialization of class template [match_results Class](../standard-library/match-results-class.md) for iterators of type `const wchar_t*`. +The type describes a specialization of class template [`match_results`](../standard-library/match-results-class.md) for iterators of type `const wchar_t*`. ## wcregex_iterator Typedef @@ -159,7 +141,7 @@ typedef regex_iterator wcregex_iterator; ### Remarks -The type describes a specialization of class template [regex_iterator Class](../standard-library/regex-iterator-class.md) for iterators of type `const wchar_t*`. +The type describes a specialization of class template [`regex_iterator`](../standard-library/regex-iterator-class.md) for iterators of type `const wchar_t*`. ## wcregex_token_iterator Typedef @@ -171,7 +153,7 @@ typedef regex_token_iterator wcregex_token_iterator; ### Remarks -The type describes a specialization of class template [regex_token_iterator Class](../standard-library/regex-token-iterator-class.md) for iterators of type `const wchar_t*`. +The type describes a specialization of class template [`regex_token_iterator`](../standard-library/regex-token-iterator-class.md) for iterators of type `const wchar_t*`. ## wcsub_match Typedef @@ -183,7 +165,7 @@ typedef sub_match wcsub_match; ### Remarks -The type describes a specialization of class template [sub_match Class](../standard-library/sub-match-class.md) for iterators of type `const wchar_t*`. +The type describes a specialization of class template [`sub_match`](../standard-library/sub-match-class.md) for iterators of type `const wchar_t*`. ## wregex Typedef @@ -195,7 +177,7 @@ typedef basic_regex wregex; ### Remarks -The type describes a specialization of class template [basic_regex Class](../standard-library/basic-regex-class.md) for elements of type **`wchar_t`**. +The type describes a specialization of class template [`basic_regex`](../standard-library/basic-regex-class.md) for elements of type **`wchar_t`**. ## wsmatch Typedef @@ -207,7 +189,7 @@ typedef match_results wsmatch; ### Remarks -The type describes a specialization of class template [match_results Class](../standard-library/match-results-class.md) for iterators of type `wstring::const_iterator`. +The type describes a specialization of class template [`match_results`](../standard-library/match-results-class.md) for iterators of type `wstring::const_iterator`. ## wsregex_iterator Typedef @@ -219,7 +201,7 @@ typedef regex_iterator wsregex_iterator; ### Remarks -The type describes a specialization of class template [regex_iterator Class](../standard-library/regex-iterator-class.md) for iterators of type `wstring::const_iterator`. +The type describes a specialization of class template [`regex_iterator`](../standard-library/regex-iterator-class.md) for iterators of type `wstring::const_iterator`. ## wsregex_token_iterator Typedef @@ -231,7 +213,7 @@ typedef regex_token_iterator wsregex_token_iterator; ### Remarks -The type describes a specialization of class template [regex_token_iterator Class](../standard-library/regex-token-iterator-class.md) for iterators of type `wstring::const_iterator`. +The type describes a specialization of class template [`regex_token_iterator`](../standard-library/regex-token-iterator-class.md) for iterators of type `wstring::const_iterator`. ## wssub_match Typedef @@ -243,7 +225,7 @@ typedef sub_match wssub_match; ### Remarks -The type describes a specialization of class template [sub_match Class](../standard-library/sub-match-class.md) for iterators of type `wstring::const_iterator`. +The type describes a specialization of class template [`sub_match`](../standard-library/sub-match-class.md) for iterators of type `wstring::const_iterator`. ## See also diff --git a/docs/standard-library/regex.md b/docs/standard-library/regex.md index 5a95a3aa66..afa6499a17 100644 --- a/docs/standard-library/regex.md +++ b/docs/standard-library/regex.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["regex header"] -ms.assetid: 5dd4ef74-6063-4dbc-b692-1960bb736f0b --- # `` @@ -18,13 +17,13 @@ Defines a class template to parse [Regular Expressions (C++)](../standard-librar ## Remarks -To create a regular expression object, use the class template [basic_regex Class](../standard-library/basic-regex-class.md) or one of its specializations, [regex](../standard-library/regex-typedefs.md#regex) and [wregex](../standard-library/regex-typedefs.md#wregex), together with the syntax flags of type [regex_constants::syntax_option_type](../standard-library/regex-constants-class.md#syntax_option_type). +To create a regular expression object, use the class template [`basic_regex`](../standard-library/basic-regex-class.md) or one of its specializations, [`regex`](../standard-library/regex-typedefs.md#regex) and [`wregex`](../standard-library/regex-typedefs.md#wregex), together with the syntax flags of type [`regex_constants::syntax_option_type`](../standard-library/regex-constants-class.md#syntax_option_type). -To search text for matches to a regular expression object, use the template functions [regex_match](../standard-library/regex-functions.md#regex_match) and [regex_search](../standard-library/regex-functions.md#regex_search), together with the match flags of type [regex_constants::match_flag_type](../standard-library/regex-constants-class.md#match_flag_type). These functions return results by using the class template [match_results Class](../standard-library/match-results-class.md) and its specializations, [cmatch](../standard-library/regex-typedefs.md#cmatch), [wcmatch](../standard-library/regex-typedefs.md#wcmatch), [smatch](../standard-library/regex-typedefs.md#smatch), and [wsmatch](../standard-library/regex-typedefs.md#wsmatch), together with the class template [sub_match Class](../standard-library/sub-match-class.md) and its specializations, [csub_match](../standard-library/regex-typedefs.md#csub_match), [wcsub_match](../standard-library/regex-typedefs.md#wcsub_match), [ssub_match](../standard-library/regex-typedefs.md#ssub_match), and [wssub_match](../standard-library/regex-typedefs.md#wssub_match). +To search text for matches to a regular expression object, use the template functions [`regex_match`](../standard-library/regex-functions.md#regex_match) and [`regex_search`](../standard-library/regex-functions.md#regex_search), together with the match flags of type [`regex_constants::match_flag_type`](../standard-library/regex-constants-class.md#match_flag_type). These functions return results by using the class template [`match_results`](../standard-library/match-results-class.md) and its specializations, [`cmatch`](../standard-library/regex-typedefs.md#cmatch), [`wcmatch`](../standard-library/regex-typedefs.md#wcmatch), [`smatch`](../standard-library/regex-typedefs.md#smatch), and [`wsmatch`](../standard-library/regex-typedefs.md#wsmatch), together with the class template [`sub_match`](../standard-library/sub-match-class.md) and its specializations, [`csub_match`](../standard-library/regex-typedefs.md#csub_match), [`wcsub_match`](../standard-library/regex-typedefs.md#wcsub_match), [`ssub_match`](../standard-library/regex-typedefs.md#ssub_match), and [`wssub_match`](../standard-library/regex-typedefs.md#wssub_match). -To replace text that matches a regular expression object, use the template function [regex_replace](../standard-library/regex-functions.md#regex_replace), together with the match flags of type [regex_constants::match_flag_type](../standard-library/regex-constants-class.md#match_flag_type). +To replace text that matches a regular expression object, use the template function [`regex_replace`](../standard-library/regex-functions.md#regex_replace), together with the match flags of type [`regex_constants::match_flag_type`](../standard-library/regex-constants-class.md#match_flag_type). -To iterate through multiple matches of a regular expression object, use the class templates [regex_iterator Class](../standard-library/regex-iterator-class.md) and [regex_token_iterator Class](../standard-library/regex-token-iterator-class.md) or one of their specializations, [cregex_iterator](../standard-library/regex-typedefs.md#cregex_iterator), [sregex_iterator](../standard-library/regex-typedefs.md#sregex_iterator), [wcregex_iterator](../standard-library/regex-typedefs.md#wcregex_iterator), [wsregex_iterator](../standard-library/regex-typedefs.md#wsregex_iterator), [cregex_token_iterator](../standard-library/regex-typedefs.md#cregex_token_iterator), [sregex_token_iterator](../standard-library/regex-typedefs.md#sregex_token_iterator), [wcregex_token_iterator](../standard-library/regex-typedefs.md#wcregex_token_iterator), or [wsregex_token_iterator](../standard-library/regex-typedefs.md#wsregex_token_iterator), together with the match flags of type [regex_constants::match_flag_type](../standard-library/regex-constants-class.md#match_flag_type). +To iterate through multiple matches of a regular expression object, use the class templates [`regex_iterator` Class](../standard-library/regex-iterator-class.md) and [`regex_token_iterator` Class](../standard-library/regex-token-iterator-class.md) or one of their specializations, [`cregex_iterator`](../standard-library/regex-typedefs.md#cregex_iterator), [`sregex_iterator`](../standard-library/regex-typedefs.md#sregex_iterator), [`wcregex_iterator`](../standard-library/regex-typedefs.md#wcregex_iterator), [`wsregex_iterator`](../standard-library/regex-typedefs.md#wsregex_iterator), [`cregex_token_iterator`](../standard-library/regex-typedefs.md#cregex_token_iterator), [`sregex_token_iterator`](../standard-library/regex-typedefs.md#sregex_token_iterator), [`wcregex_token_iterator`](../standard-library/regex-typedefs.md#wcregex_token_iterator), or [`wsregex_token_iterator`](../standard-library/regex-typedefs.md#wsregex_token_iterator), together with the match flags of type [`regex_constants::match_flag_type`](../standard-library/regex-constants-class.md#match_flag_type). To modify the details of the grammar of regular expressions, write a class that implements the regular expression traits. @@ -32,69 +31,69 @@ To modify the details of the grammar of regular expressions, write a class that |Class|Description| |-|-| -|[basic_regex](../standard-library/basic-regex-class.md)|Wraps a regular expression.| -|[match_results](../standard-library/match-results-class.md)|Holds a sequence of submatches.| -|[regex_constants](../standard-library/regex-constants-class.md)|Holds assorted constants.| -|[regex_error](../standard-library/regex-error-class.md)|Reports a bad regular expression.| -|[regex_iterator](../standard-library/regex-iterator-class.md)|Iterates through match results.| -|[regex_traits](../standard-library/regex-traits-class.md)|Describes characteristics of elements for matching.| -|[regex_traits\](../standard-library/regex-traits-char-class.md)|Describes characteristics of **`char`** for matching.| -|[regex_traits](../standard-library/regex-traits-wchar-t-class.md)|Describes characteristics of **`wchar_t`** for matching.| -|[regex_token_iterator](../standard-library/regex-token-iterator-class.md)|Iterates through submatches.| -|[sub_match](../standard-library/sub-match-class.md)|Describes a submatch.| +|[`basic_regex`](../standard-library/basic-regex-class.md)|Wraps a regular expression.| +|[`match_results`](../standard-library/match-results-class.md)|Holds a sequence of submatches.| +|[`regex_constants`](../standard-library/regex-constants-class.md)|Holds assorted constants.| +|[`regex_error`](../standard-library/regex-error-class.md)|Reports a bad regular expression.| +|[`regex_iterator`](../standard-library/regex-iterator-class.md)|Iterates through match results.| +|[`regex_traits`](../standard-library/regex-traits-class.md)|Describes characteristics of elements for matching.| +|[`regex_traits`](../standard-library/regex-traits-char-class.md)|Describes characteristics of **`char`** for matching.| +|[`regex_traits`](../standard-library/regex-traits-wchar-t-class.md)|Describes characteristics of **`wchar_t`** for matching.| +|[`regex_token_iterator`](../standard-library/regex-token-iterator-class.md)|Iterates through submatches.| +|[`sub_match`](../standard-library/sub-match-class.md)|Describes a submatch.| ### Type Definitions |Name|Description| |-|-| -|[cmatch](../standard-library/regex-typedefs.md#cmatch)|Type definition for **`char`** `match_results`.| -|[cregex_iterator](../standard-library/regex-typedefs.md#cregex_iterator)|Type definition for **`char`** `regex_iterator`.| -|[cregex_token_iterator](../standard-library/regex-typedefs.md#cregex_token_iterator)|Type definition for **`char`** `regex_token_iterator`.| -|[csub_match](../standard-library/regex-typedefs.md#csub_match)|Type definition for **`char`** `sub_match`.| -|[regex](../standard-library/regex-typedefs.md#regex)|Type definition for **`char`** `basic_regex`.| -|[smatch](../standard-library/regex-typedefs.md#smatch)|Type definition for `string` `match_results`.| -|[sregex_iterator](../standard-library/regex-typedefs.md#sregex_iterator)|Type definition for `string` `regex_iterator`.| -|[sregex_token_iterator](../standard-library/regex-typedefs.md#sregex_token_iterator)|Type definition for `string` `regex_token_iterator`.| -|[ssub_match](../standard-library/regex-typedefs.md#ssub_match)|Type definition for `string` `sub_match`.| -|[wcmatch](../standard-library/regex-typedefs.md#wcmatch)|Type definition for **`wchar_t`** `match_results`.| -|[wcregex_iterator](../standard-library/regex-typedefs.md#wcregex_iterator)|Type definition for **`wchar_t`** `regex_iterator`.| -|[wcregex_token_iterator](../standard-library/regex-typedefs.md#wcregex_token_iterator)|Type definition for **`wchar_t`** `regex_token_iterator`.| -|[wcsub_match](../standard-library/regex-typedefs.md#wcsub_match)|Type definition for **`wchar_t`** `sub_match`.| -|[wregex](../standard-library/regex-typedefs.md#wregex)|Type definition for **`wchar_t`** `basic_regex`.| -|[wsmatch](../standard-library/regex-typedefs.md#wsmatch)|Type definition for `wstring` `match_results`.| -|[wsregex_iterator](../standard-library/regex-typedefs.md#wsregex_iterator)|Type definition for `wstring` `regex_iterator`.| -|[wsregex_token_iterator](../standard-library/regex-typedefs.md#wsregex_token_iterator)|Type definition for `wstring` `regex_token_iterator`.| -|[wssub_match](../standard-library/regex-typedefs.md#wssub_match)|Type definition for `wstring` `sub_match`.| +|[`cmatch`](../standard-library/regex-typedefs.md#cmatch)|Type definition for **`char`** `match_results`.| +|[`cregex_iterator`](../standard-library/regex-typedefs.md#cregex_iterator)|Type definition for **`char`** `regex_iterator`.| +|[`cregex_token_iterator`](../standard-library/regex-typedefs.md#cregex_token_iterator)|Type definition for **`char`** `regex_token_iterator`.| +|[`csub_match`](../standard-library/regex-typedefs.md#csub_match)|Type definition for **`char`** `sub_match`.| +|[`regex`](../standard-library/regex-typedefs.md#regex)|Type definition for **`char`** `basic_regex`.| +|[`smatch`](../standard-library/regex-typedefs.md#smatch)|Type definition for `string` `match_results`.| +|[`sregex_iterator`](../standard-library/regex-typedefs.md#sregex_iterator)|Type definition for `string` `regex_iterator`.| +|[`sregex_token_iterator`](../standard-library/regex-typedefs.md#sregex_token_iterator)|Type definition for `string` `regex_token_iterator`.| +|[`ssub_match`](../standard-library/regex-typedefs.md#ssub_match)|Type definition for `string` `sub_match`.| +|[`wcmatch`](../standard-library/regex-typedefs.md#wcmatch)|Type definition for **`wchar_t`** `match_results`.| +|[`wcregex_iterator`](../standard-library/regex-typedefs.md#wcregex_iterator)|Type definition for **`wchar_t`** `regex_iterator`.| +|[`wcregex_token_iterator`](../standard-library/regex-typedefs.md#wcregex_token_iterator)|Type definition for **`wchar_t`** `regex_token_iterator`.| +|[`wcsub_match`](../standard-library/regex-typedefs.md#wcsub_match)|Type definition for **`wchar_t`** `sub_match`.| +|[`wregex`](../standard-library/regex-typedefs.md#wregex)|Type definition for **`wchar_t`** `basic_regex`.| +|[`wsmatch`](../standard-library/regex-typedefs.md#wsmatch)|Type definition for `wstring` `match_results`.| +|[`wsregex_iterator`](../standard-library/regex-typedefs.md#wsregex_iterator)|Type definition for `wstring` `regex_iterator`.| +|[`wsregex_token_iterator`](../standard-library/regex-typedefs.md#wsregex_token_iterator)|Type definition for `wstring` `regex_token_iterator`.| +|[`wssub_match`](../standard-library/regex-typedefs.md#wssub_match)|Type definition for `wstring` `sub_match`.| ### Functions |Function|Description| |-|-| -|[regex_match](../standard-library/regex-functions.md#regex_match)|Exactly matches a regular expression.| -|[regex_replace](../standard-library/regex-functions.md#regex_replace)|Replaces matched regular expressions.| -|[regex_search](../standard-library/regex-functions.md#regex_search)|Searches for a regular expression match.| -|[swap](../standard-library/regex-functions.md#swap)|Swaps `basic_regex` or `match_results` objects.| +|[`regex_match`](../standard-library/regex-functions.md#regex_match)|Exactly matches a regular expression.| +|[`regex_replace`](../standard-library/regex-functions.md#regex_replace)|Replaces matched regular expressions.| +|[`regex_search`](../standard-library/regex-functions.md#regex_search)|Searches for a regular expression match.| +|[`swap`](../standard-library/regex-functions.md#swap)|Swaps `basic_regex` or `match_results` objects.| ### Operators |Operator|Description| |-|-| -|[operator==](../standard-library/regex-operators.md#op_eq_eq)|Comparison of various objects, equal.| -|[operator!=](../standard-library/regex-operators.md#op_neq)|Comparison of various objects, not equal.| -|[operator<](../standard-library/regex-operators.md#op_lt)|Comparison of various objects, less than.| -|[operator\<=](../standard-library/regex-operators.md#op_gt_eq)|Comparison of various objects, less than or equal.| -|[operator>](../standard-library/regex-operators.md#op_gt)|Comparison of various objects, greater than.| -|[operator>=](../standard-library/regex-operators.md#op_gt_eq)|Comparison of various objects, greater than or equal.| -|[operator<<](../standard-library/regex-operators.md#op_lt_lt)|Inserts a `sub_match` in a stream.| +|[`operator==`](../standard-library/regex-operators.md#op_eq_eq)|Comparison of various objects, equal.| +|[`operator!=`](../standard-library/regex-operators.md#op_neq)|Comparison of various objects, not equal.| +|[`operator<`](../standard-library/regex-operators.md#op_lt)|Comparison of various objects, less than.| +|[`operator<=`](../standard-library/regex-operators.md#op_gt_eq)|Comparison of various objects, less than or equal.| +|[`operator>`](../standard-library/regex-operators.md#op_gt)|Comparison of various objects, greater than.| +|[`operator>=`](../standard-library/regex-operators.md#op_gt_eq)|Comparison of various objects, greater than or equal.| +|[`operator<<`](../standard-library/regex-operators.md#op_lt_lt)|Inserts a `sub_match` in a stream.| ## See also [Regular Expressions (C++)](../standard-library/regular-expressions-cpp.md)\ -[regex_constants Class](../standard-library/regex-constants-class.md)\ -[regex_error Class](../standard-library/regex-error-class.md)\ -[\ functions](../standard-library/regex-functions.md)\ -[regex_iterator Class](../standard-library/regex-iterator-class.md)\ -[\ operators](../standard-library/regex-operators.md)\ -[regex_token_iterator Class](../standard-library/regex-token-iterator-class.md)\ -[regex_traits Class](../standard-library/regex-traits-class.md)\ -[\ typedefs](../standard-library/regex-typedefs.md) +[`regex_constants` Class](../standard-library/regex-constants-class.md)\ +[`regex_error` Class](../standard-library/regex-error-class.md)\ +[`` functions](../standard-library/regex-functions.md)\ +[`regex_iterator` Class](../standard-library/regex-iterator-class.md)\ +[`` operators](../standard-library/regex-operators.md)\ +[`regex_token_iterator` Class](../standard-library/regex-token-iterator-class.md)\ +[`regex_traits` Class](../standard-library/regex-traits-class.md)\ +[`` typedefs](../standard-library/regex-typedefs.md) diff --git a/docs/standard-library/remove-const-class.md b/docs/standard-library/remove-const-class.md index 7e94d5d1eb..ed3b8d1585 100644 --- a/docs/standard-library/remove-const-class.md +++ b/docs/standard-library/remove-const-class.md @@ -1,35 +1,33 @@ --- -description: "Learn more about: remove_const Class" -title: "remove_const Class" -ms.date: "11/04/2016" +description: "Learn more about: remove_const class" +title: "remove_const class" +ms.date: 06/29/2022 f1_keywords: ["type_traits/std::remove_const"] helpviewer_keywords: ["remove_const class", "remove_const"] ms.assetid: feb76fb3-9228-41d6-80f6-2fbb04daec43 --- -# remove_const Class +# `remove_const` class -Makes a non const type from type. +Makes a non-`const` type from a type. ## Syntax ```cpp template struct remove_const; -``` -```cpp template using remove_const_t = typename remove_const::type; ``` ### Parameters -*T*\ +*`T`*\ The type to modify. ## Remarks -An instance of `remove_const` holds a modified-type that is `T1` when *T* is of the form `const T1`, otherwise *T*. +An instance of `remove_const` holds a modified-type that is `T1` when *`T`* is of the form `const T1`, otherwise *`T`*. ## Example @@ -55,12 +53,12 @@ remove_const_t == int ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[](../standard-library/type-traits.md)\ -[add_const Class](../standard-library/add-const-class.md)\ -[remove_cv Class](../standard-library/remove-cv-class.md) +[``](../standard-library/type-traits.md)\ +[`add_const` class](../standard-library/add-const-class.md)\ +[`remove_cv` class](../standard-library/remove-cv-class.md) diff --git a/docs/standard-library/reverse-iterator-class.md b/docs/standard-library/reverse-iterator-class.md index 2fee0545f7..06893a627e 100644 --- a/docs/standard-library/reverse-iterator-class.md +++ b/docs/standard-library/reverse-iterator-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: reverse_iterator Class" title: "reverse_iterator Class" -ms.date: "03/27/2019" +ms.date: 06/17/2022 f1_keywords: ["xutility/std::reverse_iterator", "iterator/std::reverse_iterator::difference_type", "iterator/std::reverse_iterator::iterator_type", "iterator/std::reverse_iterator::pointer", "iterator/std::reverse_iterator::reference", "iterator/std::reverse_iterator::base", "iterator/std::reverse_iterator::operator_star"] helpviewer_keywords: ["std::reverse_iterator [C++]", "std::reverse_iterator [C++], difference_type", "std::reverse_iterator [C++], iterator_type", "std::reverse_iterator [C++], pointer", "std::reverse_iterator [C++], reference", "std::reverse_iterator [C++], base", "std::reverse_iterator [C++], operator_star"] ms.assetid: c0b34d04-ae9a-4999-9aff-28b313897ffa +ms.custom: devdivchpfy22 --- + # reverse_iterator Class The class template is an iterator adaptor that describes a reverse iterator object that behaves like a random-access or bidirectional iterator, only in reverse. It enables the backward traversal of a range. @@ -28,9 +30,9 @@ Existing C++ Standard Library containers also define `reverse_iterator` and `con The `reverse_iterator` that requires a bidirectional iterator must not call any of the member functions `operator+=`, `operator+`, `operator-=`, `operator-`, or `operator[]`, which may only be used with random-access iterators. -The range of an iterator is [*first*, *last*), where the square bracket on the left indicates the inclusion of *first* and the parenthesis on the right indicates the inclusion of elements up to but excluding *last* itself. The same elements are included in the reversed sequence [ **rev** - *first*, **rev** - *last*) so that if *last* is the one-past-the-end element in a sequence, then the first element **rev** - *first* in the reversed sequence points to \*(*last* - 1). The identity which relates all reverse iterators to their underlying iterators is: +The range of an iterator is [*first*, *last*), where the square bracket on the left indicates the inclusion of *first* and the parenthesis on the right indicates the inclusion of elements up to but excluding *last*. The same elements are included in the reversed sequence [ **rev** - *first*, **rev** - *last*) so that if *last* is the one-past-the-end element in a sequence, then the first element **rev** - *first* in the reversed sequence points to \*(*last* - 1). The identity that relates all reverse iterators to their underlying iterators is: -&\*( **reverse_iterator** ( *i* ) ) == &\*( *i* - 1 ). +&\*(**reverse_iterator** (*i*)) == &\*(*i* - 1). In practice, this means that in the reversed sequence the reverse_iterator will refer to the element one position beyond (to the right of) the element that the iterator had referred to in the original sequence. So if an iterator addressed the element 6 in the sequence (2, 4, 6, 8), then the `reverse_iterator` will address the element 4 in the reversed sequence (8, 6, 4, 2). @@ -91,7 +93,7 @@ The iterator underlying the `reverse_iterator`. The identity that relates all reverse iterators to their underlying iterators is: -&\*( `reverse_iterator` ( *i* ) ) == &\*( *i* - 1 ). +&\*(`reverse_iterator` (*i*)) == &\*(*i* - 1). In practice, this means that in the reversed sequence the `reverse_iterator` will refer to the element one position beyond (to the right of) the element that the iterator had referred to in the original sequence. So if an iterator addressed the element 6 in the sequence (2, 4, 6, 8), then the `reverse_iterator` will address the element 4 in the reversed sequence (8, 6, 4, 2). @@ -156,7 +158,7 @@ typedef typename iterator_traits::difference_type difference_ty The `reverse_iterator` difference type is the same as the iterator difference type. -The type is a synonym for the iterator trait typename `iterator_traits`\< **RandomIterator**> **::pointer**. +The type is a synonym for the iterator trait typename `iterator_traits`\<**RandomIterator**> **::pointer**. ### Example @@ -626,7 +628,7 @@ The offset to be subtracted from the `reverse_iterator`. This member function may only be used if the `reverse_iterator` satisfies the requirements for a random-access iterator. -The operator evaluates **current** + *Off* then returns **\*this**. +The operator evaluates **current** + *Off* then returns **`*this`**. ### Example @@ -698,7 +700,7 @@ A pointer to the element addressed by the `reverse_iterator`. ### Remarks -The operator returns **&\*\*this**. +The operator returns **`&**this`**. ### Example @@ -782,7 +784,7 @@ The reference to the element offset. ### Remarks -The operator returns \*( **\*this** + `Off`). +The operator returns \*( **`*this`** + `Off`). ### Example @@ -851,7 +853,7 @@ typedef typename iterator_traits::pointer pointer; ### Remarks -The type is a synonym for the iterator trait typename `iterator_traits`\< *RandomIterator*> **::pointer**. +The type is a synonym for the iterator trait typename `iterator_traits`\<*RandomIterator*> **::pointer**. ### Example @@ -923,7 +925,7 @@ typedef typename iterator_traits::reference reference; ### Remarks -The type is a synonym for the iterator trait typename `iterator_traits`\< *RandomIterator*> **::reference**. +The type is a synonym for the iterator trait typename `iterator_traits::reference`. ### Example @@ -952,9 +954,9 @@ A default `reverse_iterator` or a `reverse_iterator` adapting an underlying iter ### Remarks -The identity which relates all reverse iterators to their underlying iterators is: +The identity that relates all reverse iterators to their underlying iterators is: -&\*( `reverse_iterator` ( *i* ) ) == &\*( *i* - 1 ). +`&*(reverse_iterator (i)) == &*(i-1)`. In practice, this means that in the reversed sequence the reverse_iterator will refer to the element one position beyond (to the right of) the element that the iterator had referred to in the original sequence. So if an iterator addressed the element 6 in the sequence (2, 4, 6, 8), then the `reverse_iterator` will address the element 4 in the reversed sequence (8, 6, 4, 2). diff --git a/docs/standard-library/reverse-view-class.md b/docs/standard-library/reverse-view-class.md new file mode 100644 index 0000000000..e344fe82ba --- /dev/null +++ b/docs/standard-library/reverse-view-class.md @@ -0,0 +1,212 @@ +--- +title: reverse_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) reverse_view class, which returns the elements of a range in reverse order." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::reverse_view", "ranges/std::reverse_view::base", "ranges/std::reverse_view::begin", "ranges/std::reverse_view::empty", "ranges/std::reverse_view::end", "ranges/std::reverse_view::size", "ranges/std::reverse_view::operator bool", "ranges/std::reverse_view::back", "ranges/std::reverse_view::front", "ranges/std::reverse_view::operator[]"] +helpviewer_keywords: ["std::ranges::reverse_view [C++]", "std::ranges::reverse_view::base [C++]", "std::ranges::reverse_view::begin [C++]", "std::ranges::reverse_view::empty [C++]", "std::ranges::reverse_view::end [C++]", "std::ranges::reverse_view::size [C++]", "std::ranges::reverse_view::back [C++]", "std::ranges::reverse_view::front [C++]", "std::ranges::reverse_view::operator[] [C++]", "std::ranges::reverse_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `reverse_view` class (C++ Standard Library) + +A view of the elements of a range in reverse order. + +## Syntax + +```cpp +template +requires ranges::bidirectional_range +class reverse_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ +The type of the underlying view.\ +This type must satisfy `ranges::bidirectional_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::reverse`](range-adaptors.md#reverse) | +| **Underlying range** | Must satisfy [`bidirectional_range`](range-concepts.md#bidirectional_range) up to [`random_access_range`](range-concepts.md#random_access_range) | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is a [`common_view`](common-view-class.md) and satisfies `const-iterable` | +| **Common range** | Yes | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `reverse_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `reverse_view`. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `reverse_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `reverse_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `reverse_view` from a bidirectional view. + +```cpp +1) reverse_view() requires default_initializable = default; // default-constructs the underlying view +2) constexpr explicit reverse_view(V rg); // initializes the underlying view via std::move(r) +``` + +### Parameters + +*`rg`*\ +The view to provide a reversed view of. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A view of the underlying range, in reverse order. + +### Remarks + +The best way to create a `reverse_view` is by using the [`views::reverse`](range-adaptors.md#reverse) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) The default constructor default-initializes a `reverse_view`.\ +2\) Create a `reverse_view` from the specified view. + +### Example: `reverse_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto rv = v | std::views::reverse; + + for (auto e : rv) // 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } +} +``` + +```output +6 5 -4 3 2 1 0 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `reverse_view`. + +```cpp +1) constexpr reverse_iterator> begin(); +2) constexpr reverse_iterator> begin() requires common_range; +3) constexpr auto begin() const requires common_range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `reverse_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +After the first call to `begin()`, subsequent calls run in constant time, O(1), no matter how many elements are in the `reverse_view`. This has implications because `reverse_view` caches the value of `last` so it can return it repeatedly from `begin`. This means you shouldn't reuse a view after the underlying container is modified. If the underlying range is modified, generate a new view, which is inexpensive. + +2\) The underlying view must satisfy [`common_range`](range-concepts.md#common_range), which means that the underlying view must have the same begin and end iterator type.\ +3\) The underlying view must satisfy `common_range` for a const view to iterate over a `const reverse_view`. + +## `end` + +Get the sentinel at the end of the `reverse_view` + +```cpp +1) constexpr reverse_iterator> end(); +2) constexpr auto end() const requires common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `reverse_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 2, the underlying view must satisfy [`common_range`](range-concepts.md#common_range) for a const view, which means that the underlying view must have the same begin and end iterator type. + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `reverse_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[``](ranges.md)\ +[`reverse` range adaptor](range-adaptors.md#reverse)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/scoped-allocator-adaptor-class.md b/docs/standard-library/scoped-allocator-adaptor-class.md index e3b2bf8658..b2b7ae1f19 100644 --- a/docs/standard-library/scoped-allocator-adaptor-class.md +++ b/docs/standard-library/scoped-allocator-adaptor-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: scoped_allocator_adaptor Class" title: "scoped_allocator_adaptor Class" -ms.date: "11/04/2016" +description: "Learn more about: scoped_allocator_adaptor Class" +ms.date: 06/20/2022 f1_keywords: ["scoped_allocator/std::scoped_allocator_adaptor", "scoped_allocator/std::scoped_allocator_adaptor::rebind Struct", "scoped_allocator/std::scoped_allocator_adaptor::allocate", "scoped_allocator/std::scoped_allocator_adaptor::construct", "scoped_allocator/std::scoped_allocator_adaptor::deallocate", "scoped_allocator/std::scoped_allocator_adaptor::destroy", "scoped_allocator/std::scoped_allocator_adaptor::inner_allocator", "scoped_allocator/std::scoped_allocator_adaptor::max_size", "scoped_allocator/std::scoped_allocator_adaptor::outer_allocator", "scoped_allocator/std::scoped_allocator_adaptor::select_on_container_copy_construction"] helpviewer_keywords: ["std::scoped_allocator_adaptor", "std::scoped_allocator_adaptor::allocate", "std::scoped_allocator_adaptor::construct", "std::scoped_allocator_adaptor::deallocate", "std::scoped_allocator_adaptor::destroy", "std::scoped_allocator_adaptor::inner_allocator", "std::scoped_allocator_adaptor::max_size", "std::scoped_allocator_adaptor::outer_allocator", "std::scoped_allocator_adaptor::select_on_container_copy_construction"] -ms.assetid: 0d9b06a1-9a4a-4669-9470-8805cae48e89 +ms.custom: devdivchpfy22 --- + # scoped_allocator_adaptor Class Represents a nest of allocators. @@ -21,11 +22,11 @@ class scoped_allocator_adaptor; The class template encapsulates a nest of one or more allocators. Each such class has an outermost allocator of type `outer_allocator_type`, a synonym for `Outer`, which is a public base of the `scoped_allocator_adaptor` object. `Outer` is used to allocate memory to be used by a container. You can obtain a reference to this allocator base object by calling `outer_allocator`. -The remainder of the nest has type `inner_allocator_type`. An inner allocator is used to allocate memory for elements within a container. You can obtain a reference to the stored object of this type by calling `inner_allocator`. If `Inner...` is not empty, `inner_allocator_type` has type `scoped_allocator_adaptor`, and `inner_allocator` designates a member object. Otherwise, `inner_allocator_type` has type `scoped_allocator_adaptor`, and `inner_allocator` designates the entire object. +The remainder of the nest has type `inner_allocator_type`. An inner allocator is used to allocate memory for elements within a container. You can obtain a reference to the stored object of this type by calling `inner_allocator`. If `Inner...` isn't empty, `inner_allocator_type` has type `scoped_allocator_adaptor`, and `inner_allocator` designates a member object. Otherwise, `inner_allocator_type` has type `scoped_allocator_adaptor`, and `inner_allocator` designates the entire object. The nest behaves as if it has arbitrary depth, replicating its innermost encapsulated allocator as needed. -Several concepts that are not a part of the visible interface aid in describing the behavior of this class template. An *outermost allocator* mediates all calls to the construct and destroy methods. It is effectively defined by the recursive function `OUTERMOST(X)`, where `OUTERMOST(X)` is one of the following. +Several concepts that aren't a part of the visible interface aid in describing the behavior of this class template. An *outermost allocator* mediates all calls to the construct and destroy methods. It's effectively defined by the recursive function `OUTERMOST(X)`, where `OUTERMOST(X)` is one of the following. - If `X.outer_allocator()` is well formed, then `OUTERMOST(X)` is `OUTERMOST(X.outer_allocator())`. @@ -66,7 +67,7 @@ Three types are defined for the sake of exposition: |Name|Description| |----------|-----------------| -|[scoped_allocator_adaptor::rebind Struct](#rebind_struct)|Defines the type `Outer::rebind\::other` as a synonym for `scoped_allocator_adaptor\`.| +|[scoped_allocator_adaptor::rebind Struct](#rebind_struct)|Defines the type `Outer::rebind::other` as a synonym for `scoped_allocator_adaptor`.| ### Methods @@ -238,14 +239,14 @@ size_type max_size(); `Outer_traits::max_size(outer_allocator())` -## scoped_allocator_adaptor::operator= +## scoped_allocator_adaptor::operator= ```cpp scoped_allocator_adaptor& operator=(const scoped_allocator_adaptor&) = default; scoped_allocator_adaptor& operator=(scoped_allocator_adaptor&&) = default; ``` -## scoped_allocator_adaptor::operator== +## scoped_allocator_adaptor::operator== ```cpp template @@ -253,7 +254,7 @@ bool operator==(const scoped_allocator_adaptor& a, const scoped_allocator_adaptor& b) noexcept; ``` -## scoped_allocator_adaptor::operator!= +## scoped_allocator_adaptor::operator!= ```cpp template @@ -276,7 +277,7 @@ A reference to the stored object of type `outer_allocator_type`. ## scoped_allocator_adaptor::rebind Struct -Defines the type `Outer::rebind\::other` as a synonym for `scoped_allocator_adaptor\`. +Defines the type `Outer::rebind::other` as a synonym for `scoped_allocator_adaptor`. struct rebind{ typedef Other_traits::rebind\ diff --git a/docs/standard-library/scoped-allocator-operators.md b/docs/standard-library/scoped-allocator-operators.md index 9798211db1..9e8b9098d2 100644 --- a/docs/standard-library/scoped-allocator-operators.md +++ b/docs/standard-library/scoped-allocator-operators.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["scoped_allocator/std::operator!=", "scoped_allocator/std::operator=="] -ms.assetid: 4dfe0805-cc6e-479f-887f-a1c164f73837 --- # `` operators -[operator!=](#op_neq)\ -[operator==](#op_eq_eq) +The `` header provides the following operators: ## operator!= diff --git a/docs/standard-library/set-class.md b/docs/standard-library/set-class.md index 13b3f06764..17de564011 100644 --- a/docs/standard-library/set-class.md +++ b/docs/standard-library/set-class.md @@ -1,10 +1,9 @@ --- title: "set Class" description: "API reference for the C++ Standard Library container class `set`, which is used to store and retrieve data from a collection." -ms.date: "9/9/2020" +ms.date: 9/9/2020 f1_keywords: ["set/std::set", "set/std::set::allocator_type", "set/std::set::const_iterator", "set/std::set::const_pointer", "set/std::set::const_reference", "set/std::set::const_reverse_iterator", "set/std::set::difference_type", "set/std::set::iterator", "set/std::set::key_compare", "set/std::set::key_type", "set/std::set::pointer", "set/std::set::reference", "set/std::set::reverse_iterator", "set/std::set::size_type", "set/std::set::value_compare", "set/std::set::value_type", "set/std::set::begin", "set/std::set::cbegin", "set/std::set::cend", "set/std::set::clear", "set/std::set::contains", "set/std::set::count", "set/std::set::crbegin", "set/std::set::crend", "set/std::set::emplace", "set/std::set::emplace_hint", "set/std::set::empty", "set/std::set::end", "set/std::set::equal_range", "set/std::set::erase", "set/std::set::find", "set/std::set::get_allocator", "set/std::set::insert", "set/std::set::key_comp", "set/std::set::lower_bound", "set/std::set::max_size", "set/std::set::rbegin", "set/std::set::rend", "set/std::set::size", "set/std::set::swap", "set/std::set::upper_bound", "set/std::set::value_comp"] helpviewer_keywords: ["std::set [C++]", "std::set [C++], allocator_type", "std::set [C++], const_iterator", "std::set [C++], const_pointer", "std::set [C++], const_reference", "std::set [C++], const_reverse_iterator", "std::set [C++], difference_type", "std::set [C++], iterator", "std::set [C++], key_compare", "std::set [C++], key_type", "std::set [C++], pointer", "std::set [C++], reference", "std::set [C++], reverse_iterator", "std::set [C++], size_type", "std::set [C++], value_compare", "std::set [C++], value_type", "std::set [C++], begin", "std::set [C++], cbegin", "std::set [C++], cend", "std::set [C++], clear", "std::set [C++], contains", "std::set [C++], count", "std::set [C++], crbegin", "std::set [C++], crend", "std::set [C++], emplace", "std::set [C++], emplace_hint", "std::set [C++], empty", "std::set [C++], end", "std::set [C++], equal_range", "std::set [C++], erase", "std::set [C++], find", "std::set [C++], get_allocator", "std::set [C++], insert", "std::set [C++], key_comp", "std::set [C++], lower_bound", "std::set [C++], max_size", "std::set [C++], rbegin", "std::set [C++], rend", "std::set [C++], size", "std::set [C++], swap", "std::set [C++], upper_bound", "std::set [C++], value_comp"] -ms.assetid: 8991f9aa-5509-4440-adc1-371512d32018 --- # `set` Class @@ -27,7 +26,7 @@ The element data type to be stored in the set. *`Traits`*\ The type that provides a function object that can compare two element values as sort keys to determine their relative order in the set. This argument is optional, and the binary predicate `less ` is the default value. -In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the set's allocation and deallocation of memory. This argument is optional, and the default value is `allocator`. @@ -52,7 +51,7 @@ The set should be the associative container of choice when the conditions associ The set orders the sequence it controls by calling a stored function object of type [`key_compare`](#key_compare). This stored object is a comparison function that may be accessed by calling the member function [`key_comp`](#key_comp). In general, the elements need to be merely less than comparable to establish this order so that, given any two elements, it may be determined either that they're equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. On a more technical note, the comparison function is a binary predicate that induces a strict weak ordering in the standard mathematical sense. A binary predicate *f*(*x,y*) is a function object that has two argument objects *x* and *y* and a return value of **`true`** or **`false`**. An ordering imposed on a set is a strict weak ordering if the binary predicate is irreflexive, antisymmetric, and transitive and if equivalence is transitive, where two objects *x* and *y* are defined to be equivalent when both *f* *x,y*) and *f*(*y,x*) are false. If the stronger condition of equality between keys replaces that of equivalence, then the ordering becomes total (in the sense that all the elements are ordered with respect to each other) and the keys matched will be indiscernible from each other. -In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](../standard-library/stl-containers.md#sequence_containers) for more information. +In C++14, you can enable heterogeneous lookup by specifying the `std::less<>` or `std::greater<>` predicate that has no type parameters. See [Heterogeneous Lookup in Associative Containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. The iterator provided by the set class is a bidirectional iterator, but the class member functions [`insert`](#insert) and [`set`](#set) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements, and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it's enough to be able to talk meaningfully about a range of iterators [ `First`, `Last`) in the context of the class's member functions. @@ -400,7 +399,7 @@ The element's key value to look for. `contains()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](./stl-containers.md#heterogeneous-lookup-in-associative-containers-c14) for more information. +`template bool contains(const K& key) const` only participates in overload resolution if `key_compare` is transparent. See [Heterogeneous lookup in associative containers](stl-containers.md#heterogeneous-lookup-in-associative-containers) for more information. ### Example @@ -886,7 +885,7 @@ The argument key to be compared with the sort key of an element from the set bei A pair of iterators where the first is the [`lower_bound`](#lower_bound) of the key and the second is the [`upper_bound`](#upper_bound) of the key. -To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*( `pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*( `pr`. **second**). +To access the first iterator of a pair `pr` returned by the member function, use `pr`. **first**, and to dereference the lower bound iterator, use \*(`pr`. **first**). To access the second iterator of a pair `pr` returned by the member function, use `pr`. **second**, and to dereference the upper bound iterator, use \*(`pr`. **second**). ### Example @@ -1327,7 +1326,6 @@ template void print(const S& s) { int main() { - // insert single values set s1; // call insert(const value_type&) version diff --git a/docs/standard-library/set-functions.md b/docs/standard-library/set-functions.md index ccd5724302..76fb181cf4 100644 --- a/docs/standard-library/set-functions.md +++ b/docs/standard-library/set-functions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["set/std::swap (map)", "set/std::swap (multiset)"] -ms.assetid: d1277d14-8502-46c0-b820-bcda820f9406 --- # `` functions -## swap (map) +## swap (set) Exchanges the elements of two sets. @@ -63,4 +62,4 @@ in the algorithm class works by assignment and is a slow operation. The speciali ### Example -See the code example for the member class [multiset::swap](../standard-library/multiset-class.md#swap)for an example of the use of the template version of `swap`. +See the code example for the member class [multiset::swap](../standard-library/multiset-class.md#swap) for an example of the use of the template version of `swap`. diff --git a/docs/standard-library/shared-future-class.md b/docs/standard-library/shared-future-class.md index b54d633cbf..a1c8887c16 100644 --- a/docs/standard-library/shared-future-class.md +++ b/docs/standard-library/shared-future-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: shared_future Class" title: "shared_future Class" -ms.date: "11/04/2016" +ms.date: 06/20/2022 f1_keywords: ["future/std::shared_future", "future/std::shared_future::shared_future", "future/std::shared_future::get", "future/std::shared_future::valid", "future/std::shared_future::wait", "future/std::shared_future::wait_for", "future/std::shared_future::wait_until"] ms.assetid: 454ebedd-f42b-405f-99a5-a25cc9ad7c90 helpviewer_keywords: ["std::shared_future [C++]", "std::shared_future [C++], shared_future", "std::shared_future [C++], get", "std::shared_future [C++], valid", "std::shared_future [C++], wait", "std::shared_future [C++], wait_for", "std::shared_future [C++], wait_until"] +ms.custom: devdivchpfy22 --- + # shared_future Class Describes an *asynchronous return object*. In contrast with a [future](../standard-library/future-class.md) object, an *asynchronous provider* can be associated with any number of `shared_future` objects. @@ -19,9 +21,9 @@ class shared_future; ## Remarks -Do not call any methods other than `valid`, `operator=`, and the destructor on a `shared_future` object that's *empty*. +Don't call any methods other than `valid`, `operator=`, and the destructor on a `shared_future` object that's *empty*. -`shared_future` objects are not synchronized. Calling methods on the same object from multiple threads introduces a data race that has unpredictable results. +`shared_future` objects aren't synchronized. Calling methods on the same object from multiple threads introduces a data race that has unpredictable results. ## Members @@ -36,7 +38,7 @@ Do not call any methods other than `valid`, `operator=`, and the destructor on a |Name|Description| |----------|-----------------| |[get](#get)|Retrieves the result that's stored in the *associated asynchronous state*.| -|[valid](#valid)|Specifies whether the object is not empty.| +|[valid](#valid)|Specifies whether the object isn't empty.| |[wait](#wait)|Blocks the current thread until the associated asynchronous state is ready.| |[wait_for](#wait_for)|Blocks until the associated asynchronous state is ready or until the specified time has elapsed.| |[wait_until](#wait_until)|Blocks until the associated asynchronous state is ready or until a specified point in time.| diff --git a/docs/standard-library/shared-ptr-class.md b/docs/standard-library/shared-ptr-class.md index 4d83bf685a..53198c33ba 100644 --- a/docs/standard-library/shared-ptr-class.md +++ b/docs/standard-library/shared-ptr-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: shared_ptr class" title: "shared_ptr class" -ms.date: "07/29/2019" +ms.date: 06/20/2022 f1_keywords: ["memory/std::shared_ptr", "memory/std::shared_ptr::element_type", "memory/std::shared_ptr::get", "memory/std::shared_ptr::owner_before", "memory/std::shared_ptr::reset", "memory/std::shared_ptr::swap", "memory/std::shared_ptr::unique", "memory/std::shared_ptr::use_count", "memory/std::shared_ptr::operator boolean-type", "memory/std::shared_ptr::operator*", "memory/std::shared_ptr::operator=", "memory/std::shared_ptr::operator->"] helpviewer_keywords: ["std::shared_ptr [C++]", "std::shared_ptr [C++], element_type", "std::shared_ptr [C++], get", "std::shared_ptr [C++], owner_before", "std::shared_ptr [C++], reset", "std::shared_ptr [C++], swap", "std::shared_ptr [C++], unique", "std::shared_ptr [C++], use_count", "std::shared_ptr [C++], element_type", "std::shared_ptr [C++], get", "std::shared_ptr [C++], owner_before", "std::shared_ptr [C++], reset", "std::shared_ptr [C++], swap", "std::shared_ptr [C++], unique", "std::shared_ptr [C++], use_count"] ms.assetid: 1469fc51-c658-43f1-886c-f4530dd84860 +ms.custom: devdivchpfy22 --- + # `shared_ptr` class Wraps a reference-counted smart pointer around a dynamically allocated object. @@ -25,7 +27,7 @@ A `shared_ptr` stops owning a resource when it's reassigned or reset. The template argument `T` might be an incomplete type except as noted for certain member functions. -When a `shared_ptr` object is constructed from a resource pointer of type `G*` or from a `shared_ptr`, the pointer type `G*` must be convertible to `T*`. If it's not convertible, the code will not compile. For example: +When a `shared_ptr` object is constructed from a resource pointer of type `G*` or from a `shared_ptr`, the pointer type `G*` must be convertible to `T*`. If it's not convertible, the code won't compile. For example: ```cpp #include @@ -63,29 +65,29 @@ The `shared_ptr` objects that own a resource share a control block. The control - the custom allocator for the control block if it has one. -A `shared_ptr` object that is initialized by using a null pointer has a control block and is not empty. After a `shared_ptr` object releases a resource, it no longer owns that resource. After a `weak_ptr` object releases a resource, it no longer points to that resource. +A `shared_ptr` object that is initialized by using a null pointer has a control block and isn't empty. After a `shared_ptr` object releases a resource, it no longer owns that resource. After a `weak_ptr` object releases a resource, it no longer points to that resource. When the number of `shared_ptr` objects that own a resource becomes zero, the resource is freed, either by deleting it or by passing its address to a deleter, depending on how ownership of the resource was originally created. When the number of `shared_ptr` objects that own a resource is zero, and the number of `weak_ptr` objects that point to that resource is zero, the control block is freed, using the custom allocator for the control block if it has one. -An empty `shared_ptr` object does not own any resources and has no control block. +An empty `shared_ptr` object doesn't own any resources and has no control block. A deleter is a function object that has a member function `operator()`. Its type must be copy constructible, and its copy constructor and destructor must not throw exceptions. It accepts one parameter, the object to be deleted. Some functions take an argument list that defines properties of the resulting `shared_ptr` or `weak_ptr` object. You can specify such an argument list in several ways: -no arguments -- the resulting object is an empty `shared_ptr` object or an empty `weak_ptr` object. +no arguments: The resulting object is an empty `shared_ptr` object or an empty `weak_ptr` object. -`ptr` -- a pointer of type `Other*` to the resource to be managed. `T` must be a complete type. If the function fails (because the control block can't be allocated), it evaluates the expression `delete ptr`. +`ptr`: A pointer of type `Other*` to the resource to be managed. `T` must be a complete type. If the function fails (because the control block can't be allocated), it evaluates the expression `delete ptr`. -`ptr, deleter` -- a pointer of type `Other*` to the resource to be managed and a deleter for that resource. If the function fails (because the control block can't be allocated), it calls `deleter(ptr)`, which must be well-defined. +`ptr, deleter`: A pointer of type `Other*` to the resource to be managed and a deleter for that resource. If the function fails (because the control block can't be allocated), it calls `deleter(ptr)`, which must be well-defined. -`ptr, deleter, alloc` -- a pointer of type `Other*` to the resource to be managed, a deleter for that resource, and an allocator to manage any storage that must be allocated and freed. If the function fails (because the control block can't be allocated), it calls `deleter(ptr)`, which must be well-defined. +`ptr, deleter, alloc`: A pointer of type `Other*` to the resource to be managed, a deleter for that resource, and an allocator to manage any storage that must be allocated and freed. If the function fails (because the control block can't be allocated), it calls `deleter(ptr)`, which must be well-defined. -`sp` -- a `shared_ptr` object that owns the resource to be managed. +`sp`: A `shared_ptr` object that owns the resource to be managed. -`wp` -- a `weak_ptr` object that points to the resource to be managed. +`wp`: A `weak_ptr` object that points to the resource to be managed. -`ap` -- an `auto_ptr` object that holds a pointer to the resource to be managed. If the function succeeds, it calls `ap.release()`; otherwise it leaves `ap` unchanged. +`ap`: An `auto_ptr` object that holds a pointer to the resource to be managed. If the function succeeds, it calls `ap.release()`; otherwise it leaves `ap` unchanged. In all cases, the pointer type `Other*` must be convertible to `T*`. @@ -162,7 +164,7 @@ element_type* get() const noexcept; ### Remarks -The member function returns the address of the owned resource. If the object does not own a resource, it returns 0. +The member function returns the address of the owned resource. If the object doesn't own a resource, it returns 0. ### Example @@ -705,7 +707,7 @@ The shared pointer to swap with. ### Remarks -The member function leaves the resource originally owned by **`*this`** subsequently owned by *`sp`*, and the resource originally owned by *`sp`* subsequently owned by **`*this`**. The function does not change the reference counts for the two resources and it does not throw any exceptions. +The member function leaves the resource originally owned by **`*this`** subsequently owned by *`sp`*, and the resource originally owned by *`sp`* subsequently owned by **`*this`**. The function doesn't change the reference counts for the two resources and it doesn't throw any exceptions. ### Example diff --git a/docs/standard-library/single-view-class.md b/docs/standard-library/single-view-class.md new file mode 100644 index 0000000000..7a42d4dfcc --- /dev/null +++ b/docs/standard-library/single-view-class.md @@ -0,0 +1,196 @@ +--- +title: single_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) single_view class, which is a view that has only one element." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::single_view", "ranges/std::single_view::base", "ranges/std::single_view::begin", "ranges/std::single_view::end", "ranges/std::single_view::size", "ranges/std::single_view::empty", "ranges/std::single_view::operator bool", "ranges/std::single_view::data", "ranges/std::single_view::back", "ranges/std::single_view::front", "ranges/std::single_view::operator[]"] +helpviewer_keywords: ["std::ranges::single_view [C++]", "std::ranges::single_view [C++], base", "std::ranges::single_view [C++], begin", "std::ranges::single_view [C++], end", "std::ranges::single_view [C++], size", "std::ranges::single_view [C++], data", "std::ranges::single_view [C++], empty", "std::ranges::single_view [C++], operator bool", "std::ranges::single_view [C++], front", "std::ranges::single_view [C++], back", "std::ranges::single_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `single_view` class (C++ Standard Library) + +A view that has only one element. This view is useful for test purposes for calling code that needs to be provided with a view with at least one element in it. + +## Syntax + +```cpp +template + requires std::is_object_v +class single_view : public ranges::view_interface> +``` + +### Template parameters + +*`T`*\ +The type of the element. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::single`](range-adaptors.md#single) | +| **Underlying range** | None | +| **Element type** | Specified when the `single_view` is created | +| **View iterator category** | `contiguous_range` | +| **Sized** | Always returns 1 | +| **Is `const`-iterable** | Yes | +| **Common range** | Yes | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `single_view`. | +| [`begin`](#begin) C++20| Get an iterator to the element. | +| [`data`](#data)C++20 | Get a pointer to the element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. Always returns `1`. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty (always returns `false`). | +| [`front`](view-interface.md#front)C++20 | Get the element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position (only position 0 is valid). | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty (always returns `false`). | + +## Remarks + +The best way to create a `single_view` is by using the [`views::single`](range-adaptors.md#single) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +The value in the `single_view` can be modified unless the template value is `const`. For example: `single_view sv{3.14} // this value can't be modified because it's const`. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `single_view`. + +```cpp +1) single_view() = default; +2) constexpr explicit single_view(const T& t); +3) constexpr explicit single_view(T&& t); +4) template + requires constructible_from + constexpr single_view(in_place_t, Args&&... args); +``` + +### Parameters + +*`t`*\ +The element value. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +The best way to create a `single_view` is by using the [`views::single`](range-adaptors.md#single) range adaptor. + +1\) Create a `single_view` with a single element of the specified type that is default constructed. For example, `single_view sv{}` creates a `single_view` with a single element of type `float` that is default constructed to `0.0`.\ +2\) Create a `single_view` with a single element of the specified type that is copy-initialized from the specified argument. For example, `single_view sv{myObject}` creates a `single_view` with a single element of type `myObjectType` that is copy-initialized from the argument.\ +3\) Create a `single_view` with a single element of the specified type that is move-initialized from the argument.\ +4\) Create a `single_view` with a single element of the specified type initialized with `(std::forward(args)...)`. + +### Example `single_view` + +```cpp +/// requires /std:c++20 or higher +#include +#include +#include +#include + +int main() +{ + std::ranges::single_view sv{7}; + std::cout << sv.front() << " " << *sv.data() << "\n"; // 7 7 + + std::ranges::single_view> sv2{{6502, "8-bit"}}; + std::cout << std::get<0>(sv2[0]) << " " << std::get<1>(sv2[0]) << "\n"; // 6502 8-bit +} +``` + +```output +7 7 +6502 8-bit +``` + +## `begin` + +Get a pointer to the single element in the view. + +```cpp +constexpr T* begin() noexcept; +constexpr const T* begin() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the single element inside the `single_view`. + +## `data` + +Get a pointer to the single element in the `single_view`. + +```cpp +constexpr T* data() noexcept; +constexpr const T* data() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the element in the `single_view`. + +## `end` + +Gets a pointer to the sentinel after the element. + +```cpp +constexpr T* end() noexcept; +constexpr const T* end() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the sentinel that follows the element. + +## `size` + +Get the number of elements in the view. Always returns `1`. + +```cpp +static constexpr size_t size() noexcept; +``` + +### Parameters + +None. + +### Return value + +`1` + +## See also + +[``](ranges.md)\ +[`single` range adaptor](range-adaptors.md#single)\ +[`empty_view`](empty-view-class.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/slice-array-class.md b/docs/standard-library/slice-array-class.md index 7a870a33bd..6bcfaec534 100644 --- a/docs/standard-library/slice-array-class.md +++ b/docs/standard-library/slice-array-class.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: slice_array Class" -title: "slice_array Class" -ms.date: "11/04/2016" +description: "Learn more about: slice_array class" +title: "slice_array class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::slice_array"] helpviewer_keywords: ["slice_array class"] ms.assetid: a182d5f7-f35c-4e76-86f2-b5ac64ddc846 --- -# slice_array Class +# `slice_array` class -An internal, auxiliary class template that supports slice objects by providing operations between subset arrays defined by the slice of a valarray. +An internal, auxiliary class template that supports `slice` objects by providing operations between subset arrays defined by the slice of a `valarray`. ## Syntax @@ -35,24 +35,24 @@ public: ## Remarks -The class describes an object that stores a reference to an object of class [valarray](../standard-library/valarray-class.md)**\**, along with an object of class [slice](../standard-library/slice-class.md), which describes the sequence of elements to select from the **valarray\** object. +The class describes an object that stores a reference to an object of class [`valarray`](../standard-library/valarray-class.md), along with an object of class [`slice`](../standard-library/slice-class.md), which describes the sequence of elements to select from the `valarray` object. -The class template is created indirectly by certain valarray operations and cannot be used directly in the program. An internal, auxiliary class template that is used by the slice subscript operator: +The class template is created indirectly by certain `valarray` operations and can't be used directly in the program. An internal, auxiliary class template that is used by the `slice` subscript operator: `slice_array valarray::operator[]( slice )`. -You construct a `slice_array` object only by writing an expression of the form [`va[sl]`](../standard-library/valarray-class.md#op_at), for a slice `sl` of valarray `va`. The member functions of class `slice_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. The sequence controlled by the `slice_array` is defined by the three parameters of the slice constructor, the index of the first element in the slice, the number of elements, and the distance between the elements. A slice_array cut from valarray `va` declared by **va**[ `slice`(2, 5, 3)] selects elements with indices 2, 5, 8, 11, and 14 from `va`. The indices must be valid for the procedure to be valid. +You construct a `slice_array` object only by writing an expression of the form [`va[sl]`](../standard-library/valarray-class.md#op_at), for a slice `sl` of valarray `va`. The member functions of class `slice_array` then behave like the corresponding function signatures defined for `valarray`, except that only the sequence of selected elements is affected. The sequence controlled by the `slice_array` is defined by the three parameters of the `slice` constructor, the index of the first element in the `slice`, the number of elements, and the distance between the elements. A `slice_array` cut from `valarray` `va` declared by `va[slice(2, 5, 3)]` selects elements with indices 2, 5, 8, 11, and 14 from `va`. The indices must be valid for the procedure to be valid. ## Example -See the example for [slice::slice](../standard-library/slice-class.md#slice) for an example of how to declare and use a slice_array. +See the example for [`slice::slice`](../standard-library/slice-class.md#slice) for an example of how to declare and use a `slice_array`. ## Requirements **Header:** \ -**Namespace:** std +**Namespace:** `std` ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/slice-class.md b/docs/standard-library/slice-class.md index 264e3ad14a..cd43c67bdf 100644 --- a/docs/standard-library/slice-class.md +++ b/docs/standard-library/slice-class.md @@ -1,60 +1,60 @@ --- -description: "Learn more about: slice Class" -title: "slice Class" -ms.date: "11/04/2016" +description: "Learn more about: slice class" +title: "slice class" +ms.date: 01/12/2022 f1_keywords: ["valarray/std::slice", "valarray/std::slice::size", "valarray/std::slice::start", "valarray/std::slice::stride"] helpviewer_keywords: ["std::slice [C++]", "std::slice [C++], size", "std::slice [C++], start", "std::slice [C++], stride"] ms.assetid: 00f0b03d-d657-4b81-ba53-5a9034bb2bf2 --- -# slice Class +# `slice` class -A utility class to valarray that is used to define one-dimensional subsets of a parent valarray. If a valarray is regarded as a two-dimensional matrix with all elements in an array, then the slice extracts a vector in one dimension out of the two-dimensional array. +A utility class to `valarray` that's used to define one-dimensional subsets of a parent `valarray`. If a `valarray` is regarded as a two-dimensional matrix with all elements in an array, then the `slice` extracts a vector in one dimension out of the two-dimensional array. ## Remarks -The class stores the parameters that characterize an object of type [slice_array](../standard-library/slice-array-class.md) The subset of a valarray is indirectly constructed when an object of class slice appears as an argument for an object of class [valarray](../standard-library/valarray-class.md#op_at)**\**. The stored values that specify the subset selected from the parent valarray include: +The class stores the parameters that characterize an object of type [`slice_array`](../standard-library/slice-array-class.md). The subset of a `valarray` is indirectly constructed when an object of class `slice` appears as an argument for an object of class [`valarray`](../standard-library/valarray-class.md#op_at). The stored values that specify the subset selected from the parent `valarray` include: -- A starting index in the valarray. +- A starting index in the `valarray`. -- A total length, or number of elements in the slice. +- A total length, or number of elements in the `slice`. -- A stride, or distance between subsequent indices of elements in the valarray. +- A stride, or distance between the indices of elements in the `valarray`. -If the set defined by a slice is the subset of a constant valarray, then the slice is a new valarray. If the set defined by a slice is the subset of a nonconstant valarray, then the slice has reference semantics to the original valarray. The evaluation mechanism for nonconstant valarrays saves time and memory. +If the set defined by a `slice` is the subset of a constant `valarray`, then the `slice` is a new `valarray`. If the set defined by a `slice` is the subset of a nonconstant `valarray`, then the `slice` has reference semantics to the original `valarray`. The evaluation mechanism for nonconstant `valarray` objects saves time and memory. -Operations on valarrays are guaranteed only if the source and destination subsets defined by the slices are distinct and all indices are valid. +Operations on `valarray` objects are guaranteed only if the source and destination subsets defined by the `slice` objects are distinct and all indices are valid. ### Constructors -|Constructor|Description| -|-|-| -|[slice](#slice)|Defines a subset of a `valarray` that consists of a number of elements that are an equal distance apart and that start at a specified element.| +| Constructor | Description | +|--|--| +| [`slice`](#slice) | Defines a subset of a `valarray` that consists of a collection of elements that are an equal distance apart and that start at a specified element. | ### Member functions -|Member function|Description| -|-|-| -|[size](#size)|Finds the number of elements in a slice of a `valarray`.| -|[start](#start)|Finds the starting index of a slice of a `valarray`.| -|[stride](#stride)|Finds the distance between elements in a slice of a `valarray`.| +| Member function | Description | +|--|--| +| [`size`](#size) | Finds the number of elements in a `slice` of a `valarray`. | +| [`start`](#start) | Finds the starting index of a `slice` of a `valarray`. | +| [`stride`](#stride) | Finds the distance between elements in a `slice` of a `valarray`. | ## Requirements **Header:** \ -**Namespace:** std +**Namespace:** `std` -## slice::size +## `slice::size` -Finds the number of elements in a slice of a valarray. +Finds the number of elements in a `slice` of a `valarray`. ```cpp size_t size() const; ``` -### Return Value +### Return value -The number of elements in a slice of a valarray. +The number of elements in a `slice` of a `valarray`. ### Example @@ -108,9 +108,9 @@ The slice of valarray va is vaResult = va[slice( 3, 6, 3)] = The size of slice vaSlice is: 6. ``` -## slice::slice +## `slice::slice` -Defines a subset of a valarray that consists of a number of elements that are an equal distance apart and that start at a specified element. +Defines a subset of a `valarray` that consists of a collection of elements that are an equal distance apart and that start at a specified element. ```cpp slice(); @@ -123,22 +123,22 @@ slice( ### Parameters -*_StartIndex*\ -The valarray index of the first element in the subset. +*`_StartIndex`*\ +The `valarray` index of the first element in the subset. -*_Len*\ +*`_Len`*\ The number of elements in the subset. -*stride*\ +*`stride`*\ The distance between elements in the subset. -### Return Value +### Return value -The default constructor stores zeros for the starting index, total length, and stride. The second constructor stores *_StartIndex* for the starting index, *_Len* for the total length, and *stride* for the stride. +The default constructor stores zeros for the starting index, total length, and stride. The second constructor stores *`_StartIndex`* for the starting index, *`_Len`* for the total length, and *`stride`* for the stride. ### Remarks -The stride may be negative. +The *`stride`* value may be negative. ### Example @@ -181,17 +181,17 @@ The slice of valarray va is vaResult: va[slice( 1, 7, 3)] = ( 4 10 16 22 28 34 40 ). ``` -## slice::start +## `slice::start` -Finds the starting index of a slice of a valarray. +Finds the starting index of a `slice` of a `valarray`. ```cpp size_t start() const; ``` -### Return Value +### Return value -The starting index of a slice of a valarray. +The starting index of a `slice` of a `valarray`. ### Example @@ -239,17 +239,17 @@ The slice of valarray va is vaResult = va[slice( 3, 6, 3)] = The start index of slice vaSlice is: 3. ``` -## slice::stride +## `slice::stride` -Finds the distance between elements in a slice of a valarray. +Finds the distance between elements in a `slice` of a `valarray`. ```cpp size_t stride() const; ``` -### Return Value +### Return value -The distance between elements in a slice of a valarray. +The distance between elements in a `slice` of a `valarray`. ### Example @@ -299,4 +299,4 @@ The stride of slice vaSlice is: 3. ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/span-class.md b/docs/standard-library/span-class.md index 1b4f27bef0..010b8fef93 100644 --- a/docs/standard-library/span-class.md +++ b/docs/standard-library/span-class.md @@ -1,14 +1,15 @@ --- -title: "span class (C++ Standard Library)| Microsoft Docs" +title: span class (C++ Standard Library) description: "API reference for the Standard Template Library (STL) span class, which provides a lightweight view over a contiguous sequence of objects." ms.date: "05/28/2020" f1_keywords: ["span/std::span", "span/std::span::const_pointer", "span/std::span::const_reference", "span/std::span::difference_type", "span/std::span::element_type", "span/std::span::iterator", "span/std::span::pointer", "span/std::span::reference", "span/std::span::reverse_iterator", "span/std::span::size_type", "span/std::span::value_type", "span/std::span::at", "span/std::span::assign", "span/std::span::back", "span/std::span::begin", "span/std::span::data", "span/std::span::empty", "span/std::span::end", "span/std::span::front", "span/std::span::rbegin", "span/std::span::rend", "span/std::span::size", "span/std::span::size_bytes", "span/std::span::operator=", "span/std::span::operator[]"] helpviewer_keywords: ["std::span [C++]", "std::span [C++], const_pointer", "std::span [C++], const_reference", "std::span [C++], difference_type", "std::span [C++], element_type", "std::span [C++], iterator", "std::span [C++], pointer", "std::span [C++], reference", "std::span [C++], reverse_iterator", "std::span [C++], size_type", "std::span [C++], value_type", "std::span [C++], assign", "std::span [C++], at", "std::span [C++], back", "std::span [C++], begin", "std::span [C++], data", "std::span [C++], empty", "std::span [C++], end", "std::span [C++], front", "std::span [C++], rbegin", "std::span [C++], rend", "std::span [C++], size", "std::span [C++], size_bytes"] +dev_langs: ["C++"] --- -# span class (C++ Standard Library) +# `span` class (C++ Standard Library) -Provides a lightweight view over a contiguous sequence of objects. A span provides a safe way to iterate over, and index into, objects that are arranged back-to-back in memory such as objects stored in a built-in array, `std::array`, or `std::vector`. +Provides a lightweight view over a contiguous sequence of objects. A `span` provides a safe way to iterate over and index into objects that are arranged back-to-back in memory. Such as objects stored in a built-in array, `std::array`, or `std::vector`. If you typically access a sequence of back-to-back objects using a pointer and an index, a `span` is a safer, lightweight alternative. @@ -24,10 +25,10 @@ class span; ### Template parameters `T`\ - The type of the elements in the span. + The type of the elements in the `span`. `Extent`\ - The number of elements in the span if specified at compile time. Otherwise `std::dynamic_extent` if the number of elements will be specified at run-time. + The number of elements in the `span` if specified at compile time. Otherwise `std::dynamic_extent` if the number of elements will be specified at run-time. [Deduction guide](#deduction_guides) @@ -35,57 +36,57 @@ class span; | **Type Definitions** | **Description** | |-|-| -| [const_pointer](#pointer) | The type of a pointer to a **`const`** element. | -| [const_reference](#reference) | The type of a reference to a **`const`** element. | -| [difference_type](#difference_type) | The type of a signed distance between two elements. | -| [element_type](#element_type) | The type of a span element. | -| [iterator](#iterator) | The type of an iterator for a span. | -| [pointer](#pointer) | The type of a pointer to an element. | -| [reference](#reference) | The type of a reference to an element. | -| [reverse_iterator](#reverse_iterator) | The type of a reverse iterator for a span. | -| [size_type](#size_type) | The type for the result of the unsigned distance between two elements in the span. | -| [value_type](#value_type) | The type of an element, without **`const`** or **`volatile`** qualifications. | +| [`const_pointer`](#pointer) | The type of a pointer to a **`const`** element. | +| [`const_reference`](#reference) | The type of a reference to a **`const`** element. | +| [`difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`element_type`](#element_type) | The type of a `span` element. | +| [`iterator`](#iterator) | The type of an iterator for a `span`. | +| [`pointer`](#pointer) | The type of a pointer to an element. | +| [`reference`](#reference) | The type of a reference to an element. | +| [`reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for a `span`. | +| [`size_type`](#size_type) | The type for the result of the unsigned distance between two elements in the `span`. | +| [`value_type`](#value_type) | The type of an element, without **`const`** or **`volatile`** qualifications. | | **Constructor** | **Description** | -|[span](#span)| Construct a `span`.| +|[`span`](#span)| Construct a `span`.| | **Iterator support** | **Description** | -|[begin](#begin) | Get an iterator pointing to the first element in the span.| -|[end](#end) | Get an iterator pointing to the end of the span. | -|[rbegin](#rbegin) | Get a reverse iterator pointing to the last element of the span; that is, the beginning of the reversed span.| -|[rend](#rend) | Get a reverse iterator pointing to the front of the span; that is, the end of the reversed span.| +|[`begin`](#begin) | Get an iterator pointing to the first element in the `span`.| +|[`end`](#end) | Get an iterator pointing to the end of the `span`. | +|[`rbegin`](#rbegin) | Get a reverse iterator pointing to the last element of the `span`; that is, the beginning of the reversed `span`.| +|[`rend`](#rend) | Get a reverse iterator pointing to the front of the `span`; that is, the end of the reversed `span`.| | **Access elements**| **Description** | -|[back](#back) | Get the last element in the span.| -|[data](#data) | Get the address of the first element in the span.| -|[front](#front) | Get the first element in the span.| -|[operator\[\]](#op_at) | Access an element at a specified position.| +|[`back`](#back) | Get the last element in the `span`.| +|[`data`](#data) | Get the address of the first element in the `span`.| +|[`front`](#front) | Get the first element in the `span`.| +|[`operator[]`](#op_at) | Access an element at a specified position.| | **Observers** | **Description** | -|[empty](#empty)| Test whether the span is empty.| -|[size](#size) | Get the number of elements in the span.| -|[size_bytes](#size_bytes) | Get the size of the span in bytes.| +|[`empty`](#empty)| Test whether the `span` is empty.| +|[`size`](#size) | Get the number of elements in the `span`.| +|[`size_bytes`](#size_bytes) | Get the size of the `span` in bytes.| | **Subviews** | **Description**| -| [first](#first_view) | Get a subspan from the front of the span.| -| [last](#last_view) | Get a subspan from the back of the span.| -| [subspan](#sub_view) | Get a subspan from anywhere in the span.| +| [`first`](#first_view) | Get a subspan from the front of the `span`.| +| [`last`](#last_view) | Get a subspan from the back of the `span`.| +| [`subspan`](#sub_view) | Get a subspan from anywhere in the `span`.| | **Operators** | **Description** | -|[span::operator=](#op_eq)| Replace the span.| -|[span::operator\[\]](#op_at)| Get the element at the specified position. | +|[`span::operator=`](#op_eq)| Replace the `span`.| +|[`span::operator[]`](#op_at)| Get the element at the specified position. | ## Remarks All `span` member functions have constant time complexity. -Unlike `array` or `vector`, a span doesn't "own" the elements inside it. A span doesn't free any storage for the items inside it because it doesn't own the storage for those objects. +Unlike `array` or `vector`, a `span` doesn't "own" the elements inside it. A `span` doesn't free any storage for the items inside it because it doesn't own the storage for those objects. ## Requirements -**Header:** \ (since C++ 20) +**Header:** `` (since C++20) -**Namespace:** std +**Namespace:** `std` **Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. ## `span::back` -Get the last element in the span. +Get the last element in the `span`. ```cpp constexpr reference back() const noexcept; @@ -93,7 +94,7 @@ constexpr reference back() const noexcept; ### Return value -A reference to the last element in the span. +A reference to the last element in the `span`. ### Example @@ -118,7 +119,7 @@ int main() ## `span::begin` -Get an iterator pointing at the first element in the span. +Get an iterator pointing at the first element in the `span`. ```cpp constexpr iterator begin() const noexcept; @@ -126,7 +127,7 @@ constexpr iterator begin() const noexcept; ### Return value -An iterator pointing at the first element in the span. +An iterator pointing at the first element in the `span`. ### Example @@ -152,7 +153,7 @@ int main() ## `span::data` -Get a pointer to the beginning of the span data. +Get a pointer to the beginning of the `span` data. ```cpp constexpr pointer data() const noexcept; @@ -160,7 +161,7 @@ constexpr pointer data() const noexcept; ### Return value -A pointer to the first item stored in the span. +A pointer to the first item stored in the `span`. ### Example @@ -185,7 +186,7 @@ int main() ## `span::difference_type` -The number of elements between two elements in a span. +The number of elements between two elements in a `span`. ```cpp using difference_type = std::ptrdiff_t; @@ -213,7 +214,7 @@ int main() ## `span::element_type` -The type of the elements in the span. +The type of the elements in the `span`. ```cpp using element_type = T; @@ -221,7 +222,7 @@ using element_type = T; ### Remarks -The type is taken from the template parameter `T` when a span is created. +The type is taken from the template parameter `T` when a `span` is created. ### Example @@ -247,7 +248,7 @@ int main() ## `span::empty` -Whether the span contains elements. +Whether the `span` contains elements. ```cpp constexpr bool empty() const noexcept; @@ -275,7 +276,7 @@ int main() ## `span::end` -Get an iterator to the end of the span. +Get an iterator to the end of the `span`. ```cpp constexpr iterator end() const noexcept; @@ -283,13 +284,13 @@ constexpr iterator end() const noexcept; ### Return value -An iterator pointing just beyond the end of the span. +An iterator pointing just beyond the end of the `span`. ### Remarks `end` is used to test whether an iterator has passed the end of its range. -Don't dereference the value returned by this iterator. Use it to identify whether the iterator has reached beyond the last element in the span. +Don't dereference the value returned by this iterator. Use it to identify whether the iterator has reached beyond the last element in the `span`. ### Example @@ -303,7 +304,7 @@ for (auto it = s1.begin(); it != s1.end(); ++it) ## `span::first` -Get a subspan, taken from the front of this span. +Get a subspan, taken from the front of this `span`. ```cpp constexpr auto first(size_type count) const noexcept; @@ -312,17 +313,17 @@ template constexpr auto first() const noexcept; ### Parameters -*count*\ -The number of elements from the front of this span to put in the subspan. +*`count`*\ +The number of elements from the front of this `span` to put in the subspan. The number of elements is specified as a parameter to the template, or to the function, as illustrated below. ### Return value -A span that contains `count` elements from the front of this span. +A `span` that contains `count` elements from the front of this `span`. ### Remarks -Use the template version of this function when possible to validate the `count` at compile time, and to preserve info about the span since it returns a span of fixed extent. +Use the template version of this function when possible to validate the `count` at compile time, and to preserve info about the `span` since it returns a `span` of fixed extent. ### Example @@ -360,7 +361,7 @@ mySpan.first<2>: 01 ## `span::front` -Get the first element in the span. +Get the first element in the `span`. ```cpp constexpr reference front() const noexcept; @@ -368,7 +369,7 @@ constexpr reference front() const noexcept; ### Return value -A reference to the first element in the span. +A reference to the first element in the `span`. ### Example @@ -394,7 +395,7 @@ int main() ## `span::iterator` -The type of an iterator over span elements. +The type of an `iterator` over `span` elements. ```cpp using iterator = implementation-defined-iterator-type; @@ -402,7 +403,7 @@ using iterator = implementation-defined-iterator-type; ### Remarks -This type serves as an iterator over the elements in a span. +This type serves as an `iterator` over the elements in a `span`. ### Example @@ -428,7 +429,7 @@ int main() ## `span::last` -Get a subspan, taken from the end of this span. +Get a subspan, taken from the end of this `span`. ```cpp constexpr span last(const size_type count) const noexcept; @@ -437,17 +438,17 @@ template constexpr span last() const noexcep ### Parameters -*count*\ -The number of elements from the end this span to put in the subspan. +*`count`*\ +The number of elements from the end this `span` to put in the subspan. The number can be specified as a parameter to the template, or to the function, as illustrated below. ### Return value -A span containing the last `count` elements from this span. +A `span` containing the last `count` elements from this `span`. ### Remarks -Use the template version of this function when possible to validate the `count` at compile time, and to preserve info about the span since it returns a span of fixed extent. +Use the template version of this function when possible to validate the `count` at compile time, and to preserve info about the `span` since it returns a `span` of fixed extent. ### Example @@ -485,7 +486,7 @@ mySpan.last<2>: 12 ## `span::operator[]` -Get the element in the span at a specified position. +Get the element in the `span` at a specified position. ```cpp constexpr reference operator[](size_type offset) const; @@ -493,12 +494,12 @@ constexpr reference operator[](size_type offset) const; ### Parameters -*offset*\ -Zero-based element in the span to access. +*`offset`*\ +Zero-based element in the `span` to access. ### Return value -A reference to the element at position *offset*. If the position is invalid, the behavior is undefined. +A reference to the element at position *`offset`*. If the position is invalid, the behavior is undefined. ### Example @@ -522,7 +523,7 @@ int main() ## `span::operator=` -Assign another span to this one. +Assign another `span` to this one. ```cpp constexpr span& operator=(const span& other) noexcept = default; @@ -530,8 +531,8 @@ constexpr span& operator=(const span& other) noexcept = default; ### Parameters -*other*\ -The span to assign to this one. +*`other`*\ +The `span` to assign to this one. ### Return value @@ -568,7 +569,7 @@ int main() ## `span::pointer` -The types for a pointer, and **`const`** pointer, to a span element. +The types for a pointer, and **`const`** pointer, to a `span` element. ```cpp using pointer = T*; @@ -606,7 +607,7 @@ int main() ## `span::rbegin` -Get a reverse iterator pointing to the last element of this span. +Get a reverse iterator pointing to the last element of this `span`. ```cpp constexpr reverse_iterator rbegin() const noexcept; @@ -614,7 +615,7 @@ constexpr reverse_iterator rbegin() const noexcept; ### Return value -An iterator pointing to the beginning of the reversed span. +An iterator pointing to the beginning of the reversed `span`. ### Example @@ -642,7 +643,7 @@ int main() ## `span::reference` -The types for a reference, and a **`const`** reference, to a span element. +The types for a reference, and a **`const`** reference, to a `span` element. ```cpp using reference = T&; @@ -679,7 +680,7 @@ int main() ## `span::rend` -Get a random-access iterator that points just beyond the end of the reversed span. +Get a random-access iterator that points just beyond the end of the reversed `span`. ```cpp constexpr reverse_iterator rend() const noexcept; @@ -687,11 +688,11 @@ constexpr reverse_iterator rend() const noexcept; ### Return value -A reverse iterator to the placeholder following the last element in the reversed span; that is, the placeholder before the first element in the unreversed span. +A reverse iterator to the placeholder following the last element in the reversed `span`; that is, the placeholder before the first element in the unreversed `span`. ### Remarks -`rend` is used with a reversed span just as [span::end](#end) is used with a span. Use it to test to whether a reverse iterator has reached the end of its span. +`rend` is used with a reversed `span` just as [`span::end`](#end) is used with a `span`. Use it to test to whether a reverse iterator has reached the end of its `span`. The value returned by `rend` shouldn't be dereferenced. @@ -717,7 +718,7 @@ int main() ## `span::reverse_iterator` -The type of a reverse iterator for a span. +The type of a reverse iterator for a `span`. ```cpp using reverse_iterator = std::reverse_iterator; @@ -745,7 +746,7 @@ int main() ## `span::size` -Get the number of elements in the span. +Get the number of elements in the `span`. ```cpp constexpr size_t size() const noexcept; @@ -753,7 +754,7 @@ constexpr size_t size() const noexcept; ### Return value -The number of elements in the span. +The number of elements in the `span`. ### Example @@ -777,7 +778,7 @@ int main() ## `span::size_bytes` -Get the size of the elements in the span in bytes. +Get the size of the elements in the `span` in bytes. ```cpp constexpr size_type size_bytes() const noexcept; @@ -785,7 +786,7 @@ constexpr size_type size_bytes() const noexcept; ### Return value -The number of bytes that all of the elements in the span occupy; that is, `sizeof(element_type)` multiplied by the number of elements in the span. +The number of bytes that all of the elements in the `span` occupy; that is, `sizeof(element_type)` multiplied by the number of elements in the `span`. ### Example @@ -809,7 +810,7 @@ int main() ## `span::size_type` -An unsigned type, suitable for storing the number of elements in a span. +An unsigned type, suitable for storing the number of elements in a `span`. ```cpp using size_type = size_t; @@ -882,25 +883,25 @@ span(const span& other) noexcept ### Parameters -*arr*\ +*`arr`*\ Construct a `span` from an array. -*count*\ +*`count`*\ Number of elements that will be in the `span`. -*first*\ +*`first`*\ Iterator to the first element in the `span`. -*last*\ +*`last`*\ Iterator to just past the last element in the `span`. -*N*\ +*`N`*\ The number of elements that will be in the `span`. -*other*\ +*`other`*\ Make a copy of this `span`. -*r*\ +*`r`*\ Construct a `span` from the range `R`. ### Remarks @@ -909,13 +910,13 @@ A `span` doesn't free storage for items in the `span` because it doesn't own the |Constructor | Description | |---------|---------| -|`span()` | Construct an empty span. Only considered during overload resolution when the template parameter `Extent` is `0` or `dynamic_extent`.| -|`span(It first, size_type count)` | Construct a span from the first `count` elements from iterator `first`. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. | -|`span(It first, End last)` | Construct a span from the elements in iterator `first` until the end `last` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a `contiguous_iterator`. | -|`span(array& arr) noexcept;`

`span(const array& arr) noexcept;`

`span(type_identity_t (&arr)[N]) noexcept;` | Construct a span from `N` elements of the specified array. Only considered during overload resolution when template parameter `Extent` is `dynamic_extent` or equals `N`. | -|`span(R&& r)` | Construct a span from a range. Only participates in overload resolution if template parameter `Extent` isn't `dynamic_extent`.| -|`span(const span& other)` | The compiler-generated copy constructor. A shallow copy of the data pointer is safe because the span doesn't allocate the memory to hold the elements. | -|`span(const span& s) noexcept;` | Converting constructor: construct a span from another span. Only participates in overload resolution if template parameter `Extent` is `dynamic_extent`, or `N` is `dynamic_extent` or equals `Extent`.| +|`span()` | Construct an empty `span`. Only considered during overload resolution when the template parameter `Extent` is `0` or `dynamic_extent`.| +|`span(It first, size_type count)` | Construct a `span` from the first `count` elements from iterator `first`. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. | +|`span(It first, End last)` | Construct a `span` from the elements in iterator `first` until the end `last` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator). | +|`span(array& arr) noexcept;`

`span(const array& arr) noexcept;`

`span(type_identity_t (&arr)[N]) noexcept;` | Construct a `span` from `N` elements of the specified array. Only considered during overload resolution when template parameter `Extent` is `dynamic_extent` or equals `N`. | +|`span(R&& r)` | Construct a `span` from a range. Only participates in overload resolution if template parameter `Extent` isn't `dynamic_extent`.| +|`span(const span& other)` | The compiler-generated copy constructor. A shallow copy of the data pointer is safe because the `span` doesn't allocate the memory to hold the elements. | +|`span(const span& s) noexcept;` | Converting constructor: construct a `span` from another `span`. Only participates in overload resolution if template parameter `Extent` is `dynamic_extent`, or `N` is `dynamic_extent` or equals `Extent`.| ### Example @@ -943,7 +944,7 @@ int main() ## `span::subspan` -Get a subspan of this span. +Get a subspan of this `span`. ```cpp constexpr auto subspan(size_type offset, size_type count = dynamic_extent) const noexcept; @@ -954,19 +955,19 @@ constexpr auto subspan() const noexcept ### Parameters -*count*\ -The number of elements to put in the subspan. If `count` is `dynamic_extent` (the default value), then the subspan is taken from `offset` to the end of this span. +*`count`*\ +The number of elements to put in the subspan. If `count` is `dynamic_extent` (the default value), then the subspan is taken from `offset` to the end of this `span`. -*offset*\ -The location in this span to start the subspan. +*`offset`*\ +The location in this `span` to start the subspan. ### Return value -A span starting at `offset` in this span. Contains `count` elements. +A `span` starting at `offset` in this `span`. Contains `count` elements. ### Remarks -A template version of this function is available that checks the count at compile time, which preserves information about the span by returning a span of fixed extent. +A template version of this function is available that checks the count at compile time, which preserves information about the `span` by returning a `span` of fixed extent. ### Example @@ -1007,7 +1008,7 @@ mySpan.subspan<1>: 12 ## `span::value_type` -The type of the element in the span, without **`const`** or **`volatile`** qualifications. +The type of the element in the `span`, without **`const`** or **`volatile`** qualifications. ```cpp using value_type = std::remove_cv_t; @@ -1037,7 +1038,7 @@ int main() ## Deduction guides -The following deduction guides are provided for span. +The following deduction guides are provided for `span`. ```cpp // Allows the extent to be deduced from std::array and C++ built-in arrays @@ -1066,5 +1067,5 @@ span(Rng &&) -> span>>; ## See also -[\](../standard-library/span.md) +[``](../standard-library/span.md)\ [How to use class template argument deduction](https://devblogs.microsoft.com/cppblog/how-to-use-class-template-argument-deduction/) diff --git a/docs/standard-library/span-functions.md b/docs/standard-library/span-functions.md index 21e42c4871..4c92144c44 100644 --- a/docs/standard-library/span-functions.md +++ b/docs/standard-library/span-functions.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "05/28/2020" f1_keywords: ["span/std::span::as_bytes", "span/std::as_writable_bytes"] helpviewer_keywords: ["std::span [C++], as_writable_bytes", "std::as_bytes [C++]"] +dev_langs: ["C++"] --- # `` functions -The \ header includes the following non-member functions that operate on **span** objects. +The `` header includes the following non-member functions that operate on `span` objects. | **Non-member functions** | **Description** | |-|-| -|[as_bytes](#as_bytes) | Get a read-only view of the object representation of the elements in the span. | -|[as_writable_bytes](#as_writable_bytes) | Get a read/write view of the object representation of the elements in the span. | +|[`as_bytes`](#as_bytes) | Get a read-only view of the object representation of the elements in the span. | +|[`as_writable_bytes`](#as_writable_bytes) | Get a read/write view of the object representation of the elements in the span. | ## `as_bytes` @@ -25,13 +26,13 @@ auto as_bytes(span s) noexcept; ### Parameters -*T*\ +*`T`*\ The type of the elements in the span. -*Extent*\ +*`Extent`*\ The number of elements in the span (if known at compile time), otherwise `dynamic_extent` indicating that the number of elements isn't known until runtime. -*s*\ +*`s`*\ The span to get the raw representation of. ### Return Value @@ -46,7 +47,7 @@ A `span` to the first item stored in the span where `S` is `{rein using namespace std; -void main() +int main() { int a[] = { 0,1,2 }; span mySpan(a); @@ -65,13 +66,13 @@ auto as_writable_bytes(span s) noexcept; ### Parameters -*T*\ +*`T`*\ The type of the elements in the span. -*Extent*\ +*`Extent`*\ The number of elements in the span (if known at compile time), otherwise `dynamic_extent` indicating that the number of elements isn't known until runtime. -*s*\ +*`s`*\ The span to get the raw representation of. ### Return Value @@ -86,7 +87,7 @@ A `span` to the first item stored in the span where `S` is `{reinterpre using namespace std; -void main() +int main() { int a[] = { 0,1,2 }; span mySpan(a); @@ -96,4 +97,4 @@ void main() ## See also -[\](span.md) +[``](span.md) diff --git a/docs/standard-library/span.md b/docs/standard-library/span.md index d104ebf72e..30efd03eac 100644 --- a/docs/standard-library/span.md +++ b/docs/standard-library/span.md @@ -4,13 +4,14 @@ description: "API reference for the Standard Template Library (STL) span namespa ms.date: "05/28/2020" f1_keywords: [""] helpviewer_keywords: ["span header"] +dev_langs: ["C++"] --- # `` -A `span` is a view over a contiguous sequence of objects. It provides fast and bounds-safe access. Unlike `vector` or `array`, it doesn't "own" the elements it provides access to. +A `span` is a view over a contiguous sequence of objects. It provides fast and bounds-safe access. Unlike `vector` or `array`, it doesn't "own" the elements. -See [span class](span-class.md) for detailed information. Here's an example of how a span can be used: +See [`span` class](span-class.md) for detailed information. Here's an example of how to use a `span`: ```cpp #include @@ -40,40 +41,39 @@ int main() ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` **Compiler option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. - ## Members ### Classes |Name|Description| |-|:-| -|[span](span-class.md)| Provides a view over a contiguous sequence of objects. | +|[`span`](span-class.md)| Provides a view over a contiguous sequence of objects. | ### Operators |Name|Description| |-|:-| -|[operator=](span-class.md#op_eq)| Span assignment | -|[operator\[\]](span-class.md#op_at)| Element access | +|[`operator=`](span-class.md#op_eq)| Span assignment | +|[`operator[]`](span-class.md#op_at)| Element access | ### Functions |Name|Description| |-|:-| -| [as_bytes](span-functions.md#as_bytes)| Get the underlying read-only bytes of the span. | -| [as_writable_bytes](span-functions.md#as_writable_bytes) | Get the underlying bytes of the span. | +| [`as_bytes`](span-functions.md#as_bytes)| Get the underlying read-only bytes of the span. | +| [`as_writable_bytes`](span-functions.md#as_writable_bytes) | Get the underlying bytes of the span. | ### Constants |Name|Description| |-|:-| -| **dynamic_extent** | Indicates that the span size is determined at runtime rather than compile time. When the number of elements in the span is known at compile time, it's specified as the `Extent` template parameter. When the number isn't known until runtime, specify `dynamic_extent` instead. | +| **`dynamic_extent`** | Indicates that the span size is determined at runtime rather than compile time. When the number of elements in the span is known at compile time, it's specified as the `Extent` template parameter. When the number isn't known until runtime, specify `dynamic_extent` instead. | ## See also diff --git a/docs/standard-library/split-view-class.md b/docs/standard-library/split-view-class.md new file mode 100644 index 0000000000..70a26bd73e --- /dev/null +++ b/docs/standard-library/split-view-class.md @@ -0,0 +1,221 @@ +--- +title: split_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) split_view class. Splits a view into subranges based on a delimiter. The delimiter can be a single element or a view of elements." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::split_view", "ranges/std::split_view::base", "ranges/std::split_view::begin", "ranges/std::split_view::data", "ranges/std::split_view::empty", "ranges/std::split_view::end", "ranges/std::split_view::size", "ranges/std::split_view::operator bool", "ranges/std::split_view::back", "ranges/std::split_view::front", "ranges/std::split_view::operator[]"] +helpviewer_keywords: ["std::ranges::split_view [C++]", "std::ranges::split_view::base [C++]", "std::ranges::split_view::begin [C++]", "std::ranges::split_view::data [C++]", "std::ranges::split_view::empty [C++]", "std::ranges::split_view::size [C++]", "std::ranges::split_view::end [C++]", +"std::ranges::split_view::back [C++]", "std::ranges::split_view::front [C++]", "std::ranges::split_view::operator[] [C++]", "std::ranges::split_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `split_view` class (C++ Standard Library) + +Splits a view into subranges based on a delimiter. The delimiter can be a single element or a view of elements. The delimiter isn't part of the resulting `split_view`. + +A related view is the [`lazy_split_view`](lazy-split-view-class.md) class. The primary differences between `split_view` and `lazy_split_view` are: + +| **View** | **Can split a `const` range**| **range type** | +|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher. | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher. | + +Prefer `split_view` because it's more efficient unless you must split a range that is `const`. + +## Syntax + +```cpp +template + requires view && view && + indirectly_comparable, iterator_t, ranges::equal_to> +class split_view : public view_interface>; +``` + +### Template parameters + +*`Pattern`*\ + The type of the view that specifies the delimiter sequence. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::split`](range-adaptors.md#split) | +| **Underlying range** | Same as underlying range | +| **Element type** | `range_reference_t` | +| **View iterator category** | Satisfies [`forward_range`](range-concepts.md#forward_range) | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `split_view` + +```cpp +1) split_view() requires default_initializable && default_initializable = default; +2) constexpr split_view(V base, Pattern pattern); +3) template requires constructible_from> && + constructible_from>> + constexpr split_view(R&& rg, range_value_t e); +``` + +### Parameters + +*`e`*\ +A single element that identifies where to split the view. The element isn't part of the resulting view. + +*`base`*\ +The underlying view. + +*`pattern`*\ +The view of elements that identifies where to split the view. The view of elements isn't part of the resulting view. + +*`rg`*\ +The range to split. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `split_view` instance that contains one or more subranges. + +### Remarks + +The best way to create a `split_view` is by using the [`views::split`](range-adaptors.md#split) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `split_view` that is default constructed. The underlying view and `pattern` are default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `split_view` by splitting the view using a sequence of delimiters.\ +3\) Create a `split_view` by splitting the view using a single delimiter. + +### Example `split_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // pipe syntax using range adaptor + for (const auto& subrange : rg | std::views::split(3)) + { + // outputs + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : subrange) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + int delimiters[] = {2, 3}; + for (auto splitRange : std::views::split(rg, delimiters)) // ctor syntax + { + for (auto& i : splitRange) + { + std::cout << i << " "; // 1 1 4 5 6 + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end(); +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## See also + +[``](ranges.md)\ +[`split_view` range adaptor](range-adaptors.md#split)\ +[`lazy_split_view` class](lazy-split-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/sstream-functions.md b/docs/standard-library/sstream-functions.md index 80c3aab153..4c47dc0b0f 100644 --- a/docs/standard-library/sstream-functions.md +++ b/docs/standard-library/sstream-functions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["sstream/std::swap"] -ms.assetid: bc9607e8-7c6b-44ef-949b-19e917b450ad --- # `` functions -[swap](#sstream_swap) +The `` header provides the following functions: ## swap diff --git a/docs/standard-library/sstream-typedefs.md b/docs/standard-library/sstream-typedefs.md index 1acbf2dc19..0a392e94bb 100644 --- a/docs/standard-library/sstream-typedefs.md +++ b/docs/standard-library/sstream-typedefs.md @@ -1,22 +1,14 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["iosfwd/std::istringstream", "iosfwd/std::ostringstream", "iosfwd/std::stringbuf", "iosfwd/std::stringstream", "iosfwd/std::wistringstream", "iosfwd/std::wostringstream", "iosfwd/std::wstringbuf", "iosfwd/std::wstringstream"] -ms.assetid: d102edd2-ecea-4a35-a398-cf96e58dd422 --- # `` typedefs -[istringstream](#istringstream)\ -[ostringstream](#ostringstream)\ -[stringbuf](#stringbuf)\ -[stringstream](#stringstream)\ -[wistringstream](#wistringstream)\ -[wostringstream](#wostringstream)\ -[wstringbuf](#wstringbuf)\ -[wstringstream](#wstringstream) +The `` header provides the following typedefs: -## istringstream +## `istringstream` Creates a type `basic_istringstream` specialized on a **`char`** template parameter. @@ -26,9 +18,9 @@ typedef basic_istringstream istringstream; ### Remarks -The type is a synonym for class template [basic_istringstream](../standard-library/basic-istringstream-class.md), specialized for elements of type **`char`**. +The type is a synonym for class template [`basic_istringstream`](../standard-library/basic-istringstream-class.md), specialized for elements of type **`char`**. -## ostringstream +## `ostringstream` Creates a type `basic_ostringstream` specialized on a **`char`** template parameter. @@ -38,9 +30,9 @@ typedef basic_ostringstream ostringstream; ### Remarks -The type is a synonym for class template [basic_ostringstream](../standard-library/basic-ostringstream-class.md), specialized for elements of type **`char`**. +The type is a synonym for class template [`basic_ostringstream`](../standard-library/basic-ostringstream-class.md), specialized for elements of type **`char`**. -## stringbuf +## `stringbuf` Creates a type `basic_stringbuf` specialized on a **`char`** template parameter. @@ -50,9 +42,9 @@ typedef basic_stringbuf stringbuf; ### Remarks -The type is a synonym for class template [basic_stringbuf](../standard-library/basic-stringbuf-class.md), specialized for elements of type **`char`**. +The type is a synonym for class template [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md), specialized for elements of type **`char`**. -## stringstream +## `stringstream` Creates a type `basic_stringstream` specialized on a **`char`** template parameter. @@ -62,9 +54,9 @@ typedef basic_stringstream stringstream; ### Remarks -The type is a synonym for class template [basic_stringstream](../standard-library/basic-stringstream-class.md), specialized for elements of type **`char`**. +The type is a synonym for class template [`basic_stringstream`](../standard-library/basic-stringstream-class.md), specialized for elements of type **`char`**. -## wistringstream +## `wistringstream` Creates a type `basic_istringstream` specialized on a **`wchar_t`** template parameter. @@ -74,9 +66,9 @@ typedef basic_istringstream wistringstream; ### Remarks -The type is a synonym for class template [basic_istringstream](../standard-library/basic-istringstream-class.md), specialized for elements of type **`wchar_t`**. +The type is a synonym for class template [`basic_istringstream`](../standard-library/basic-istringstream-class.md), specialized for elements of type **`wchar_t`**. -## wostringstream +## `wostringstream` Creates a type `basic_ostringstream` specialized on a **`wchar_t`** template parameter. @@ -86,9 +78,9 @@ typedef basic_ostringstream wostringstream; ### Remarks -The type is a synonym for class template [basic_ostringstream](../standard-library/basic-ostringstream-class.md), specialized for elements of type **`wchar_t`**. +The type is a synonym for class template [`basic_ostringstream`](../standard-library/basic-ostringstream-class.md), specialized for elements of type **`wchar_t`**. -## wstringbuf +## `wstringbuf` Creates a type `basic_stringbuf` specialized on a **`wchar_t`** template parameter. @@ -98,9 +90,9 @@ typedef basic_stringbuf wstringbuf; ### Remarks -The type is a synonym for class template [basic_stringbuf](../standard-library/basic-stringbuf-class.md), specialized for elements of type **`wchar_t`**. +The type is a synonym for class template [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md), specialized for elements of type **`wchar_t`**. -## wstringstream +## `wstringstream` Creates a type `basic_stringstream` specialized on a **`wchar_t`** template parameter. @@ -110,8 +102,8 @@ typedef basic_stringstream wstringstream; ### Remarks -The type is a synonym for class template [basic_stringstream](../standard-library/basic-stringstream-class.md), specialized for elements of type **`wchar_t`**. +The type is a synonym for class template [`basic_stringstream`](../standard-library/basic-stringstream-class.md), specialized for elements of type **`wchar_t`**. ## See also -[\](../standard-library/sstream.md) +[``](../standard-library/sstream.md) diff --git a/docs/standard-library/stack-class.md b/docs/standard-library/stack-class.md index edfba57c4b..12a610f22e 100644 --- a/docs/standard-library/stack-class.md +++ b/docs/standard-library/stack-class.md @@ -4,11 +4,10 @@ title: "stack Class" ms.date: "11/04/2016" f1_keywords: ["stack/std::stack::container_type", "stack/std::stack::size_type", "stack/std::stack::value_type", "stack/std::stack::empty", "stack/std::stack::pop", "stack/std::stack::push", "stack/std::stack::size", "stack/std::stack::top"] helpviewer_keywords: ["std::stack [C++], container_type", "std::stack [C++], size_type", "std::stack [C++], value_type", "std::stack [C++], empty", "std::stack [C++], pop", "std::stack [C++], push", "std::stack [C++], size", "std::stack [C++], top"] -ms.assetid: 02151c1e-eab0-41b8-be94-a839ead78ecf --- -# stack Class +# `stack` Class -A template container adaptor class that provides a restriction of functionality limiting access to the element most recently added to some underlying container type. The stack class is used when it is important to be clear that only stack operations are being performed on the container. +A template container adaptor class that provides a restriction of functionality limiting access to the element most recently added to some underlying container type. The `stack` class is used when it is important to be clear that only `stack` operations are being performed on the container. ## Syntax @@ -19,25 +18,25 @@ class stack ### Parameters -*Type*\ +*`Type`*\ The element data type to be stored in the stack. -*Container*\ -The type of the underlying container used to implement the stack. The default value is the class `deque`*\*. +*`Container`*\ +The type of the underlying container used to implement the stack. The default value is the class `deque`. ## Remarks -The elements of class `Type` stipulated in the first template parameter of a stack object are synonymous with [value_type](#value_type) and must match the type of element in the underlying container class `Container` stipulated by the second template parameter. The `Type` must be assignable, so that it is possible to copy objects of that type and to assign values to variables of that type. +The elements of class `Type` stipulated in the first template parameter of a stack object are synonymous with [`value_type`](#value_type) and must match the type of element in the underlying container class `Container` stipulated by the second template parameter. The `Type` must be assignable, so that it is possible to copy objects of that type and to assign values to variables of that type. -Suitable underlying container classes for stack include [deque](../standard-library/deque-class.md), [list class](../standard-library/list-class.md), and [vector class](../standard-library/vector-class.md), or any other sequence container that supports the operations of `back`, `push_back`, and `pop_back`. The underlying container class is encapsulated within the container adaptor, which exposes only the limited set of the sequence container member functions as a public interface. +Suitable underlying container classes for stack include [`deque`](../standard-library/deque-class.md), [`list` class](../standard-library/list-class.md), and [`vector` class](../standard-library/vector-class.md), or any other sequence container that supports the operations of `back`, `push_back`, and `pop_back`. The underlying container class is encapsulated within the container adaptor, which exposes only the limited set of the sequence container member functions as a public interface. -The stack objects are equality comparable if and only if the elements of class `Type` are equality comparable and are less-than comparable if and only if the elements of class `Type` are less-than comparable. +The `stack` objects are equality comparable if and only if the elements of class `Type` are equality comparable and are less-than comparable if and only if the elements of class `Type` are less-than comparable. -- The stack class supports a last-in, first-out (LIFO) data structure. A good analogue to keep in mind would be a stack of plates. Elements (plates) may be inserted, inspected, or removed only from the top of the stack, which is the last element at the end of the base container. The restriction to accessing only the top element is the reason for using the stack class. +- The `stack` class supports a last-in, first-out (LIFO) data structure. A good analogue to keep in mind would be a stack of plates. Elements (plates) may be inserted, inspected, or removed only from the top of the stack, which is the last element at the end of the base container. The restriction to accessing only the top element is the reason for using the `stack` class. -- The [queue class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. A good analogue to keep in mind would be people lining up for a bank teller. Elements (people) may be added to the back of the line and are removed from the front of the line. Both the front and the back of a line may be inspected. The restriction to accessing only the front and back elements in this way is the reason fur using the queue class. +- The [`queue` class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. A good analogue to keep in mind would be people lining up for a bank teller. Elements (people) may be added to the back of the line and are removed from the front of the line. Both the front and the back of a line may be inspected. The restriction to accessing only the front and back elements in this way is the reason fur using the `queue` class. -- The [priority_queue class](../standard-library/priority-queue-class.md) orders its elements so that the largest element is always at the top position. It supports insertion of an element and the inspection and removal of the top element. A good analogue to keep in mind would be people lining up where they are arranged by age, height, or some other criterion. +- The [`priority_queue` class](../standard-library/priority-queue-class.md) orders its elements so that the largest element is always at the top position. It supports insertion of an element and the inspection and removal of the top element. A good analogue to keep in mind would be people lining up where they are arranged by age, height, or some other criterion. ## Members @@ -45,27 +44,27 @@ The stack objects are equality comparable if and only if the elements of class ` |Name|Description| |-|-| -|[stack](#stack)|Constructs a `stack` that is empty or that is a copy of a base container object.| +|[`stack`](#stack)|Constructs a `stack` that is empty or that is a copy of a base container object.| ### Typedefs |Name|Description| |-|-| -|[container_type](#container_type)|A type that provides the base container to be adapted by a `stack`.| -|[size_type](#size_type)|An unsigned integer type that can represent the number of elements in a `stack`.| -|[value_type](#value_type)|A type that represents the type of object stored as an element in a `stack`.| +|[`container_type`](#container_type)|A type that provides the base container to be adapted by a `stack`.| +|[`size_type`](#size_type)|An unsigned integer type that can represent the number of elements in a `stack`.| +|[`value_type`](#value_type)|A type that represents the type of object stored as an element in a `stack`.| ### Functions |Name|Description| |-|-| -|[empty](#empty)|Tests if the `stack` is empty.| -|[pop](#pop)|Removes the element from the top of the `stack`.| -|[push](#push)|Adds an element to the top of the `stack`.| -|[size](#size)|Returns the number of elements in the `stack`.| -|[top](#top)|Returns a reference to an element at the top of the `stack`.| +|[`empty`](#empty)|Tests if the `stack` is empty.| +|[`pop`](#pop)|Removes the element from the top of the `stack`.| +|[`push`](#push)|Adds an element to the top of the `stack`.| +|[`size`](#size)|Returns the number of elements in the `stack`.| +|[`top`](#top)|Returns a reference to an element at the top of the `stack`.| -## container_type +## `container_type` A type that provides the base container to be adapted. @@ -75,15 +74,15 @@ typedef Container container_type; ### Remarks -The type is a synonym for the template parameter `Container`. All three C++ Standard Library sequence container classes — the vector class, list class, and the default class deque — meet the requirements to be used as the base container for a stack object. User-defined types satisfying these requirements may also be used. +The type is a synonym for the template parameter `Container`. All three C++ Standard Library sequence container classes — the `vector` class, `list` class, and the default class `deque` — meet the requirements to be used as the base container for a `stack` object. User-defined types satisfying these requirements may also be used. -For more information on `Container`, see the Remarks section of the [stack Class](../standard-library/stack-class.md) topic. +For more information on `Container`, see the Remarks section of the [`stack` Class](../standard-library/stack-class.md) topic. ### Example -See the example for [stack::stack](#stack) for an example of how to declare and use `container_type`. +See the example for [`stack::stack`](#stack) for an example of how to declare and use `container_type`. -## empty +## `empty` Tests if a stack is empty. @@ -128,7 +127,7 @@ The stack s1 is not empty. The stack s2 is empty. ``` -## pop +## `pop` Removes the element from the top of the stack. @@ -184,7 +183,7 @@ After a pop, the stack length is 2. After a pop, the element at the top of the stack is 20. ``` -## push +## `push` Adds an element to the top of the stack. @@ -194,7 +193,7 @@ void push(const Type& val); ### Parameters -*val*\ +*`val`*\ The element added to the top of the stack. ### Remarks @@ -233,7 +232,7 @@ The stack length is 3. The element at the top of the stack is 30. ``` -## size +## `size` Returns the number of elements in the stack. @@ -274,7 +273,7 @@ The stack length is 1. The stack length is now 2. ``` -## size_type +## `size_type` An unsigned integer type that can represent the number of elements in a stack. @@ -288,9 +287,9 @@ The type is a synonym for `size_type` of the base container adapted by the stack ### Example -See the example for [size](#size) for an example of how to declare and use `size_type`. +See the example for [`size`](#size) for an example of how to declare and use `size_type`. -## stack +## `stack` Constructs a stack that is empty or that is a copy of a base container class. @@ -302,7 +301,7 @@ explicit stack(const container_type& right); ### Parameters -*right*\ +*`right`*\ The container of which the constructed stack is to be a copy. ### Example @@ -344,7 +343,7 @@ int main( ) The element at the top of stack vsi2 is 1. ``` -## top +## `top` Returns a reference to an element at the top of the stack. @@ -362,7 +361,7 @@ A reference to the last element in the container at the top of the stack. The stack must be nonempty to apply the member function. The top of the stack is the position occupied by the most recently added element and is the last element at the end of the container. -If the return value of `top` is assigned to a `const_reference`, the stack object cannot be modified. If the return value of `top` is assigned to a `reference`, the stack object can be modified. +If the return value of `top` is assigned to a `const_reference`, the `stack` object cannot be modified. If the return value of `top` is assigned to a `reference`, the `stack` object can be modified. ### Example @@ -395,7 +394,7 @@ The top integer of the stack s1 is 2. The next integer down is 1. ``` -## value_type +## `value_type` A type that represents the type of object stored as an element in a stack. diff --git a/docs/standard-library/stack-operators.md b/docs/standard-library/stack-operators.md index a8b308ae8a..9722dbc4ea 100644 --- a/docs/standard-library/stack-operators.md +++ b/docs/standard-library/stack-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators" title: " operators" +description: "Learn more about: operators" ms.date: "11/04/2016" f1_keywords: ["stack/std::operator!=", "stack/std::operator>", "stack/std::operator>=", "stack/std::operator<", "stack/std::operator<=", "stack/std::operator=="] -ms.assetid: 9c1fc282-2f61-4727-9e80-84ea5d4934a2 helpviewer_keywords: ["std::operator!= (stack)", "std::operator> (stack)", "std::operator>= (stack)", "std::operator< (stack)", "std::operator<= (stack)", "std::operator== (stack)"] --- # `` operators @@ -13,7 +12,7 @@ helpviewer_keywords: ["std::operator!= (stack)", "std::operator> (stack)", "std: Tests if the stack object on the left side of the operator is not equal to stack object on the right side. ```cpp -bool operator!=(const stack & left, const stack & right,); +bool operator!=(const stack & left, const stack & right); ``` ### Parameters diff --git a/docs/standard-library/steady-clock-struct.md b/docs/standard-library/steady-clock-struct.md index 13a31fd923..27c5ae83a4 100644 --- a/docs/standard-library/steady-clock-struct.md +++ b/docs/standard-library/steady-clock-struct.md @@ -1,8 +1,10 @@ --- -description: "Learn more about: steady_clock struct" title: "steady_clock struct" -ms.date: 08/19/2021 -f1_keywords: ["chrono/std::chrono::steady_clock"] +description: "Learn more about: steady_clock struct" +ms.date: 04/14/2022 +f1_keywords: ["chrono/std::chrono::steady_clock", "chrono/std::chrono::steady_clock::now", "chrono/std::chrono::steady_clock::is_steady"] +helpviewer_keywords: ["std::chrono [C++], steady_clock"] +dev_langs: ["C++"] --- # `steady_clock` struct @@ -16,12 +18,54 @@ struct steady_clock; ## Remarks -A `steady_clock` is a monotonic clock, which means that time only moves forward. A `steady_clock` ensures that the time between clicks doesn't vary, making it better for measuring intervals than using a system clock that provides wall-clock time. The problem with using wall-clock time to measure elapsed time is that the wall-clock time may get modified while measuring an interval. It could be modified by synchronizing with another clock over the network, adjusting the time for daylight savings time, and so on. A `steady_clock` isn't subject to these adjustments, making it the preferred way to keep track of elapsed time. +A `steady_clock` is a monotonic clock, which means that the time it reports only moves forward. The value returned by a call to `now` is always less than or equal to the value that is returned by the next call to `now`. -The value that is returned by a first call to `now` is always less than or equal to the value that is returned by the next call to `now`. +A `steady_clock` ensures that the time between ticks is constant, making it better for measuring intervals than using a system clock. The system clock provides wall-clock time. The problem with using wall-clock time to measure elapsed time is that wall-clock time may get modified while measuring a time interval. It could be modified by synchronizing with another clock over the network, by a transition to daylight savings time, and so on. A `steady_clock` isn't subject to these adjustments, making it the preferred way to keep track of elapsed time. `high_resolution_clock` is a typedef for `steady_clock`. On Windows, `steady_clock` wraps the `QueryPerformanceCounter` function. +## Example + +```cpp +#include +#include +#include + +using namespace std::chrono; + +int main() +{ + auto begin = steady_clock::now(); + std::this_thread::sleep_for(std::chrono::seconds(1)); + auto end = steady_clock::now(); + + std::cout << "Elapsed seconds: " + << duration_cast(end - begin).count() + << "s\n"; + + std::cout << "Elapsed milliseconds: " + << duration_cast(end - begin).count() + << "ms\n"; + + std::cout << "Elapsed microseconds: " + << duration_cast(end - begin).count() + << "us\n"; + + std::cout << "Elapsed nanoseconds: " + << duration_cast(end - begin).count() + << " ns\n"; + + return 0; +} +``` + +```Output +Elapsed seconds: 1s +Elapsed milliseconds: 1007ms +Elapsed microseconds: 1007266us +Elapsed nanoseconds: 1007266700 ns +``` + ### Convenience type aliases |Name|Description| @@ -58,4 +102,4 @@ The value that is returned by a first call to `now` is always less than or equal [`system_clock` struct](system-clock-structure.md)\ [`tai_clock` class](tai-clock-class.md)\ [`utc_clock` class](utc-clock-class.md)\ -[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/stl-containers.md b/docs/standard-library/stl-containers.md index e682064b54..0b8ce54931 100644 --- a/docs/standard-library/stl-containers.md +++ b/docs/standard-library/stl-containers.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: C++ Standard Library Containers" title: "C++ Standard Library Containers" -ms.date: "11/04/2016" +description: "Learn more about: C++ Standard Library Containers" +ms.date: 11/04/2016 helpviewer_keywords: ["C++ Standard Library, class template containers", "containers, C++ Standard Library"] -ms.assetid: 8e915ca1-19ba-4f0d-93c8-e2c3bfd638eb --- # C++ Standard Library Containers @@ -39,11 +38,11 @@ Both `map` and `set` only allow one instance of a key or element to be inserted Ordered maps and sets support bi-directional iterators, and their unordered counterparts support forward iterators. For more information, see [Iterators](../standard-library/iterators.md). -### Heterogeneous Lookup in Associative Containers (C++14) +### Heterogeneous Lookup in Associative Containers (C++14) The ordered associative containers (map, multimap, set, and multiset) now support heterogeneous lookup, which means that you're no longer required to pass the exact same object type as the key or element in member functions such as `find()` and `lower_bound()`. Instead, you can pass any type for which an overloaded `operator<` is defined that enables comparison to the key type. -Heterogenous lookup is enabled on an opt-in basis when you specify the `std::less<>` or `std::greater<>` "diamond functor" comparator when declaring the container variable, as shown here: +Heterogeneous lookup is enabled on an opt-in basis when you specify the `std::less<>` or `std::greater<>` "diamond functor" comparator when declaring the container variable, as shown here: ```cpp std::set> myNewSet; @@ -142,7 +141,7 @@ In general, elements inserted into a C++ Standard Library container can be of ju The destructor isn't permitted to throw an exception. -Ordered associative containers—described earlier in this article—must have a public comparison operator defined. (By default, the operator is `operator<`, but even types that don't work with `operator<` are supported. +Ordered associative containers—described earlier in this article—must have a public comparison operator defined. By default, the operator is `operator<`, but even types that don't work with `operator<` are supported. Some operations on containers might also require a public default constructor and a public equivalence operator. For example, the unordered associative containers require support for equality and hashing. diff --git a/docs/standard-library/streambuf-typedefs.md b/docs/standard-library/streambuf-typedefs.md index 842403c4f0..ab98660169 100644 --- a/docs/standard-library/streambuf-typedefs.md +++ b/docs/standard-library/streambuf-typedefs.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["iosfwd/std::streambuf", "iosfwd/std::wstreambuf"] -ms.assetid: 2678e18f-f0f0-4995-bc53-f1bc7dfc4ec6 --- # `` typedefs -[streambuf](#streambuf)\ -[wstreambuf](#wstreambuf) +The `` header provides the following typedefs: ## streambuf diff --git a/docs/standard-library/string-functions.md b/docs/standard-library/string-functions.md index ec9262a46f..4639cb1764 100644 --- a/docs/standard-library/string-functions.md +++ b/docs/standard-library/string-functions.md @@ -1,25 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["string/std::getline", "string/std::stod", "string/std::stof", "string/std::stoi", "string/std::stol", "string/std::stold", "string/std::stoll", "string/std::stoul", "string/std::stoull", "string/std::swap", "string/std::to_string", "string/std::to_wstring"] -ms.assetid: 1a4ffd11-dce5-4cc6-a043-b95de034c7c4 helpviewer_keywords: ["std::getline [C++]", "std::stod [C++]", "std::stof [C++]", "std::stoi [C++]", "std::stol [C++]", "std::stold [C++]", "std::stoll [C++]", "std::stoul [C++]", "std::stoull [C++]", "std::swap [C++]", "std::to_string [C++]", "std::to_wstring [C++]"] --- # `` functions -[`getline`](#getline)\ -[`stod`](#stod)\ -[`stof`](#stof)\ -[`stoi`](#stoi)\ -[`stol`](#stol)\ -[`stold`](#stold)\ -[`stoll`](#stoll)\ -[`stoul`](#stoul)\ -[`stoull`](#stoull)\ -[`swap`](#swap)\ -[`to_string`](#to_string)\ -[`to_wstring`](#to_wstring) +The `` header provides the following functions: ## `getline` @@ -144,8 +132,7 @@ double stod( double stod( const wstring& str, - size_t* idx = 0 -; + size_t* idx = 0); ``` ### Parameters diff --git a/docs/standard-library/string-operators.md b/docs/standard-library/string-operators.md index 337f916ab3..692a728f2d 100644 --- a/docs/standard-library/string-operators.md +++ b/docs/standard-library/string-operators.md @@ -1,22 +1,13 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["string/std::operator!=", "string/std::operator>", "string/std::operator>>", "string/std::operator>=", "string/std::operator<", "string/std::operator<<", "string/std::operator<=", "string/std::operator+", "string/std::operator=="] -ms.assetid: 33ce8f05-06c7-45d3-a0cb-bcd27cf93910 helpviewer_keywords: ["std::operator!= (string)", "std::operator> (string)", "std::operator>> (string)", "std::operator>= (string)", "std::operator< (string)", "std::operator<< (string)", "std::operator<= (string), std::operator== (string)"] --- # `` operators -[operator!=](#op_neq)\ -[`operator>`](#op_gt)\ -[`operator>>`](#op_gt_gt)\ -[`operator>=`](#op_gt_eq)\ -[`operator<`](#op_lt)\ -[`operator<<`](#op_lt_lt)\ -[`operator<=`](#op_lt_eq)\ -[operator+](#op_add)\ -[operator==](#op_eq_eq) +The `` header provides the following operators: ## operator+ @@ -98,7 +89,7 @@ The string that is the concatenation of the input strings. ### Remarks -The functions each overload `operator+` to concatenate two objects of class template [basic_string Class](../standard-library/basic-string-class.md). All effectively return `basic_string< CharType, Traits, Allocator>(Left).append(right)`. For more information, see [append](../standard-library/basic-string-class.md#append). +The functions each overload `operator+` to concatenate two objects of class template [`basic_string`](../standard-library/basic-string-class.md). All effectively return `basic_string< CharType, Traits, Allocator>(Left).append(right)`. For more information, see [append](../standard-library/basic-string-class.md#append). ### Example @@ -801,7 +792,7 @@ The template function overloads **operator>>** to replace the sequence controlle After the function extracts `_Istr`. [max_size](../standard-library/basic-string-class.md#max_size) elements. -- After the function extracts an element *ch* for which [use_facet](../standard-library/basic-filebuf-class.md#open)< **ctype**\< **CharType**> >( `getloc`). **is**( **ctype**\< **CharType**>:: **space**, *ch*) is true, in which case the character is put back. +- After the function extracts an element *ch* for which [use_facet](../standard-library/basic-filebuf-class.md#open)< **ctype**\< **CharType**> >(`getloc`). **is**( **ctype**\< **CharType**>:: **space**, *ch*) is true, in which case the character is put back. If the function extracts no elements, it calls [setstate](../standard-library/basic-ios-class.md#setstate)(`ios_base::failbit`). In any case, it calls **istr**. **width**(0) and returns \* **`this`**. diff --git a/docs/standard-library/string-typedefs.md b/docs/standard-library/string-typedefs.md index 8f4f7bfa12..23ba6e7b50 100644 --- a/docs/standard-library/string-typedefs.md +++ b/docs/standard-library/string-typedefs.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["string/std::string", "string/std::u16string", "string/std::u32string", "string/std::wstring"] -ms.assetid: fdca01e9-f2f1-4b59-abda-0093d760b3cc --- # `` typedefs -[`string`](#string)\ -[`u16string`](#u16string)\ -[`u32string`](#u32string)\ -[`wstring`](#wstring) +The `` header provides the following typedefs: ## `string` diff --git a/docs/standard-library/string-view-operators.md b/docs/standard-library/string-view-operators.md index ee8386d9e7..cc6f5a702b 100644 --- a/docs/standard-library/string-view-operators.md +++ b/docs/standard-library/string-view-operators.md @@ -301,7 +301,6 @@ Constructs a `string_view` from a string literal. Requires namespace `std::liter ### Example ```cpp - using namespace std; using namespace literals::string_view_literals; diff --git a/docs/standard-library/string-view-typedefs.md b/docs/standard-library/string-view-typedefs.md index 618b7ffee3..083d68db24 100644 --- a/docs/standard-library/string-view-typedefs.md +++ b/docs/standard-library/string-view-typedefs.md @@ -1,15 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "04/19/2019" +description: "Learn more about: typedefs" +ms.date: 04/19/2019 f1_keywords: ["xstring/std::string_view", "xstring/std::u16string_view", "xstring/std::u32string_view", "xstring/std::wstring_view"] --- # `` typedefs -[string_view](#string_view)\ -[u16string_view](#u16string_view)\ -[u32string_view](#u32string_view)\ -[wstring_view](#wstring_view) +The `` header provides the following typedefs: ## string_view diff --git a/docs/standard-library/string-view.md b/docs/standard-library/string-view.md index 5960b48d7d..7582ab417c 100644 --- a/docs/standard-library/string-view.md +++ b/docs/standard-library/string-view.md @@ -1,13 +1,12 @@ --- title: "" -description: "Overview of `basic_string_view` which refers to a constant contiguous sequence of char-like objects." -ms.date: "9/4/2020" +description: "Overview of `basic_string_view`, which refers to a constant contiguous sequence of char-like objects." +ms.date: 9/4/2020 helpviewer_keywords: ["string_view header"] -ms.assetid: a2fb9d00-d7ae-4170-bfea-2dc337aa37cf --- # `` -Defines the class template `basic_string_view` and related types and operators. (Requires compiler option [std:c++17](../build/reference/std-specify-language-standard-version.md) or later.) +Defines the class template `basic_string_view` and related types and operators. (Requires compiler option [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later.) ## Syntax @@ -17,51 +16,51 @@ Defines the class template `basic_string_view` and related types and operators. ## Remarks -The `string_view` family of template specializations provides an efficient way to pass a read-only, exception-safe, non-owning handle to the character data of any string-like objects with the first element of the sequence at position zero. A function parameter of type `string_view` (which is a typedef for `basic_string_view`) can accept arguments such as `std::string`, `char*`, or any other string-like class of narrow characters for which an implicit conversion to `string_view` is defined. Similarly, a parameter of `wstring_view`, `u16string_view` or `u32string_view` can accept any string type for which an implicit conversion is defined. For more information, see [basic_string_view Class](../standard-library/basic-string-view-class.md). +The `string_view` family of template specializations provides an efficient way to pass a read-only, exception-safe, non-owning handle to the character data of any string-like objects with the first element of the sequence at position zero. A function parameter of type `string_view` (which is a typedef for `basic_string_view`) can accept arguments such as `std::string`, `char*`, or any other string-like class of narrow characters for which an implicit conversion to `string_view` is defined. Similarly, a parameter of `wstring_view`, `u16string_view` or `u32string_view` can accept any string type for which an implicit conversion is defined. For more information, see [`basic_string_view` Class](../standard-library/basic-string-view-class.md). ### Typedefs |Type name|Description| |-|-| -|[string_view](../standard-library/string-view-typedefs.md#string_view)|A specialization of the class template `basic_string_view` with elements of type **`char`**.| -|[wstring_view](../standard-library/string-view-typedefs.md#wstring_view)|A specialization of the class template `basic_string_view` with elements of type **`wchar_t`**.| -|[u16string_view](../standard-library/string-view-typedefs.md#u16string_view)|A specialization of the class template `basic_string_view` with elements of type **`char16_t`**.| -|[u32string_view](../standard-library/string-view-typedefs.md#u32string_view)|A specialization of the class template `basic_string_view` with elements of type **`char32_t`**.| +|[`string_view`](../standard-library/string-view-typedefs.md#string_view)|A specialization of the class template `basic_string_view` with elements of type **`char`**.| +|[`wstring_view`](../standard-library/string-view-typedefs.md#wstring_view)|A specialization of the class template `basic_string_view` with elements of type **`wchar_t`**.| +|[`u16string_view`](../standard-library/string-view-typedefs.md#u16string_view)|A specialization of the class template `basic_string_view` with elements of type **`char16_t`**.| +|[`u32string_view`](../standard-library/string-view-typedefs.md#u32string_view)|A specialization of the class template `basic_string_view` with elements of type **`char32_t`**.| ### Operators -The \ operators can compare `string_view` objects to objects of any convertible string types. +The `` operators can compare `string_view` objects to objects of any convertible string types. |Operator|Description| |-|-| -|[operator!=](../standard-library/string-view-operators.md#op_neq)|Tests if the object on the left side of the operator is not equal to the object on the right side.| -|[operator==](../standard-library/string-view-operators.md#op_eq_eq)|Tests if the object on the left side of the operator is equal to the object on the right side.| -|[operator<](../standard-library/string-view-operators.md#op_lt)|Tests if the object on the left side of the operator is less than to the object on the right side.| -|[operator<=](../standard-library/string-view-operators.md#op_lt_eq)|Tests if the object on the left side of the operator is less than or equal to the object on the right side.| -|[operator<\<](../standard-library/string-view-operators.md#op_lt_lt)|A template function that inserts a `string_view` into an output stream.| -|[operator>](../standard-library/string-view-operators.md#op_gt)|Tests if the object on the left side of the operator is greater than to the object on the right side.| -|[operator>=](../standard-library/string-view-operators.md#op_gt_eq)|Tests if the object on the left side of the operator is greater than or equal to the object on the right side.| +|[`operator!=`](../standard-library/string-view-operators.md#op_neq)|Tests if the object on the left side of the operator isn't equal to the object on the right side.| +|[`operator==`](../standard-library/string-view-operators.md#op_eq_eq)|Tests if the object on the left side of the operator is equal to the object on the right side.| +|[`operator<`](../standard-library/string-view-operators.md#op_lt)|Tests if the object on the left side of the operator is less than to the object on the right side.| +|[`operator<=`](../standard-library/string-view-operators.md#op_lt_eq)|Tests if the object on the left side of the operator is less than or equal to the object on the right side.| +|[`operator<<`](../standard-library/string-view-operators.md#op_lt_lt)|A template function that inserts a `string_view` into an output stream.| +|[`operator>`](../standard-library/string-view-operators.md#op_gt)|Tests if the object on the left side of the operator is greater than to the object on the right side.| +|[`operator>=`](../standard-library/string-view-operators.md#op_gt_eq)|Tests if the object on the left side of the operator is greater than or equal to the object on the right side.| ### Literals |Operator|Description| |-|-| -|[sv](../standard-library/string-view-operators.md#op_sv)|Constructs a `string_view`, `wstring_view`, `u16string_view`, or `u32string_view` depending on the type of the string literal to which it is appended.| +|[`sv`](../standard-library/string-view-operators.md#op_sv)|Constructs a `string_view`, `wstring_view`, `u16string_view`, or `u32string_view` depending on the type of the string literal to which it's appended.| ### Classes |Class|Description| |-|-| -|[basic_string_view Class](../standard-library/basic-string-view-class.md)|A class template that provides a read-only view into a sequence of arbitrary character-like objects.| -|[hash](string-view-hash.md)|Function object that produces a hash value for a string_view.| +|[`basic_string_view` Class](../standard-library/basic-string-view-class.md)|A class template that provides a read-only view into a sequence of arbitrary character-like objects.| +|[`hash`](string-view-hash.md)|Function object that produces a hash value for a `string_view`.| ## Requirements -- **Header:** \ +- **Header:** `` -- **Namespace:** std +- **Namespace:** `std` -- **Compiler Option:** [std:c++17](../build/reference/std-specify-language-standard-version.md) or later. +- **Compiler Option:** [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. ## See also diff --git a/docs/standard-library/strstream-class.md b/docs/standard-library/strstream-class.md index 3efda849d7..0a4c9c3d6b 100644 --- a/docs/standard-library/strstream-class.md +++ b/docs/standard-library/strstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: strstream Class" title: "strstream Class" -ms.date: "11/04/2016" +description: "Learn more about: strstream Class" +ms.date: 11/04/2016 f1_keywords: ["strstream/std::strstream::freeze", "strstream/std::strstream::pcount", "strstream/std::strstream::rdbuf", "strstream/std::strstream::str"] helpviewer_keywords: ["std::strstream [C++], freeze", "std::strstream [C++], pcount", "std::strstream [C++], rdbuf", "std::strstream [C++], str"] -ms.assetid: 63f3be31-9e36-42b1-9715-a474a5997e2a --- # strstream Class @@ -152,9 +151,9 @@ The buffer. Both constructors initialize the base class by calling [streambuf](../standard-library/streambuf-typedefs.md#streambuf)( **sb**), where `sb` is the stored object of class [strstreambuf](../standard-library/strstreambuf-class.md). The first constructor also initializes `sb` by calling [strstreambuf](../standard-library/strstreambuf-class.md#strstreambuf). The second constructor initializes the base class one of two ways: -- If `_Mode` & **ios_base::app**== 0, then *ptr* must designate the first element of an array of `count` elements, and the constructor calls `strstreambuf`( `ptr`, `count`, `ptr`). +- If `_Mode` & **ios_base::app**== 0, then *ptr* must designate the first element of an array of `count` elements, and the constructor calls `strstreambuf`(`ptr`, `count`, `ptr`). -- Otherwise, *ptr* must designate the first element of an array of count elements that contains a C string whose first element is designated by *ptr*, and the constructor calls `strstreambuf`( `ptr`, `count`, `ptr` + `strlen`( `ptr`) ). +- Otherwise, *ptr* must designate the first element of an array of count elements that contains a C string whose first element is designated by *ptr*, and the constructor calls `strstreambuf`(`ptr`, `count`, `ptr` + `strlen`(`ptr`)). ## See also diff --git a/docs/standard-library/sub-match-class.md b/docs/standard-library/sub-match-class.md index 1916f28655..664e1f0867 100644 --- a/docs/standard-library/sub-match-class.md +++ b/docs/standard-library/sub-match-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: sub_match Class" title: "sub_match Class" -ms.date: "09/10/2018" +ms.date: 06/20/2022 f1_keywords: ["regex/std::sub_match", "regex/std::sub_match::matched", "regex/std::sub_match::compare", "regex/std::sub_match::length", "regex/std::sub_match::str", "regex/std::sub_match::difference_type", "regex/std::sub_match::iterator", "regex/std::sub_match::value_type"] helpviewer_keywords: ["std::sub_match [C++]", "std::sub_match [C++], matched", "std::sub_match [C++], compare", "std::sub_match [C++], length", "std::sub_match [C++], str", "std::sub_match [C++], difference_type", "std::sub_match [C++], iterator", "std::sub_match [C++], value_type"] ms.assetid: 804e2b9e-d16a-4c4c-ac60-024e0b2dd0e8 +ms.custom: devdivchpfy22 --- + # sub_match Class Describes a submatch. @@ -27,7 +29,7 @@ The iterator type for submatches. The class template describes an object that designates a sequence of characters that matched a capture group in a call to [regex_match](../standard-library/regex-functions.md#regex_match) or to [regex_search](../standard-library/regex-functions.md#regex_search). Objects of type [match_results Class](../standard-library/match-results-class.md) hold an array of these objects, one for each capture group in the regular expression that was used in the search. -If the capture group was not matched the object's data member `matched` holds false, and the two iterators `first` and `second` (inherited from the base `std::pair`) are equal. If the capture group was matched, `matched` holds true, the iterator `first` points to the first character in the target sequence that matched the capture group, and the iterator `second` points one position past the last character in the target sequence that matched the capture group. Note that for a zero-length match the member `matched` holds true, the two iterators will be equal, and both will point to the position of the match. +If the capture group wasn't matched the object's data member `matched` holds false, and the two iterators `first` and `second` (inherited from the base `std::pair`) are equal. If the capture group was matched, `matched` holds true, the iterator `first` points to the first character in the target sequence that matched the capture group, and the iterator `second` points one position past the last character in the target sequence that matched the capture group. For a zero-length match, the member `matched` holds true, the two iterators will be equal, and both will point to the position of the match. A zero-length match can occur when a capture group consists solely of an assertion, or of a repetition that allows zero repeats. For example: diff --git a/docs/standard-library/subrange-class.md b/docs/standard-library/subrange-class.md new file mode 100644 index 0000000000..7f269483d0 --- /dev/null +++ b/docs/standard-library/subrange-class.md @@ -0,0 +1,542 @@ +--- +title: subrange class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) subrange class, which is a view of the elements of a range as defined by a begin iterator and a sentinel." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::subrange", "ranges/std::subrange::begin", "ranges/std::subrange::data", "ranges/std::subrange::empty", "ranges/std::subrange::end", "ranges/std::subrange::get", "ranges/std::subrange::size", "ranges/std::subrange::operator bool", "ranges/std::subrange::operator PairLike", "ranges/std::subrange::back", "ranges/std::subrange::front", "ranges/std::subrange::operator[]", "ranges/std::subrange::advance", "ranges/std::subrange::prev", "ranges/std::subrange::next"] +helpviewer_keywords: ["std::ranges::subrange [C++]", "std::ranges::subrange::begin [C++]", "std::ranges::subrange::data [C++]", "std::ranges::subrange::empty [C++]", "std::ranges::subrange::end [C++]", "std::ranges::subrange::size [C++]", "std::ranges::subrange::back [C++]", "std::ranges::subrange::front [C++]", "std::ranges::subrange::advance [C++]", "std::ranges::subrange::prev [C++]", "std::ranges::subrange::next [C++]", "std::ranges::subrange::get [C++]", "std::ranges::subrange::operator[] [C++]", "std::ranges::subrange::operator bool [C++]", "std::ranges::subrange::operator PairLike [C++]"] +dev_langs: ["C++"] +--- +# `subrange` class (C++ Standard Library) + +Provides a view of part of the elements of a range as defined by a begin iterator and sentinel. + +## Syntax + +```cpp +template S, subrange_kind K> + requires (K == subrange_kind::sized || !sized_sentinel_for) +class subrange : public view_interface> +``` + +### Template parameters + +*`I`*\ + The begin iterator type. The [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator) concept ensures that *`I`* is an iterator that can read all of the elements. + +*`K`*\ +The kind of subrange: Use `subrange_kind::sized` to specify a sized subrange. Use `sized_sentinel_for` if the iterator and sentinel can be subtracted to yield the size. The requirement `subrange_kind::sized || !sized_sentinel_for` stores the size locally in the subrange object, and requires that you construct the subrange either using the constructor that takes a [`sized_range`](range-concepts.md#sized_range) (for which you would specify `subrange_kind::sized` here) or via the constructor that takes an `iterator`, `sentinel`, and `size` (so you would specify `sized_sentinel_for` here). + +*`S`*\ + The end iterator type. The [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for) concept ensures that *`S`* can be used as a sentinel for *`I`* and that it's possible to compute the distance between the sentinel and the current iterator position in *`I`* in constant time. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::counted`](range-adaptors.md#counted) | +| **Underlying range** | Any range | +| **Element type** | `iter_reference_t` | +| **View iterator category** | Same as *`I`s* category | +| **Sized** | If *`K`* is `subrange::sized` | +| **Is `const`-iterable** | If *`I`* is copyable | +| **Common range** | If *`I`* and *`S`* are the same type. | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `subrange`. | +| [`operator PairLike`](#op_pairlike)C++20 | Convert a `subrange` to a pair-like type. | +| [`advance`](#advance)C++20 | Move the iterator a specified distance. | +| [`begin`](#begin) | Get an iterator to the first element. | +| [`empty`](#empty)C++20 | Test whether the `subrange` is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `subrange`. | +| [`next`](#next)C++20 | Creates a copy of this `subrange` but with the stored iterator moved forward the specified distance. | +| [`prev`](#prev)C++20 | Creates a copy of this `subrange` but with the stored iterator moved back the specified distance. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `subrange` is empty. | + +## Remarks + +A `subrange` is useful when you have a begin and end iterator, but you want to pass a single object instead. For example, if you wanted to call a range adaptor but had begin and end iterators, you could use a `subrange` to wrap them and pass the `subrange` to the range adaptor. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create a `subrange`. + +```cpp +1) subrange() requires default_initializable = default; +2) template It> + constexpr subrange(It begin, S end) requires (!Store_size); +3) template It> + constexpr subrange(It begin, S end, const Size_type size) requires (K == subrange_kind::sized); +4) template rg> + requires borrowed_range + && Convertible_to_non_slicing, I> + && convertible_to, S> + constexpr subrange(rg&& r) requires (!_Store_size || sized_range); +5) template + requires Convertible_to_non_slicing, I> && convertible_to, S> + constexpr subrange(rg&& r, const _Size_type sizeHint) requires (K == subrange_kind::sized) +``` + +### Parameters + +*`begin`*\ +Iterator that points to the first element in the subrange. + +*`end`*\ +Sentinel that points to the end of the subrange. The element it points to isn't included in the subrange. + +*`sizeHint`*\ +The size of the range in elements. This is used to optimize the `size` member function and is necessary if you want to make a sized `subrange` from an iterator and sentinel whose types don't model [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for). + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `subrange` instance. + +### Remarks + +1\) Default constructs the stored iterator and sentinel. The size hint is set to 0.\ +2\) Uses `std::move()` to move the `begin` iterator and `end` sentinel to the stored iterator and sentinel.\ +3\) Initializes the stored iterator with `std::move(begin)`, the stored sentinel with `std::move(end)`, and the stored size hint with `size`, which should equal the distance between the first and second arguments.\ +4\) Construct a `subrange` from a range.\ +5\) The behavior isn't defined if `szHint != ranges::distance(rg)`. + +The [`counted`](range-adaptors.md#counted) range adaptor can create a `subrange`. That adaptor takes a begin iterator and a count. + +### Example: `counted` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto pos5 = std::ranges::find(v, 5); + auto countedView = std::views::counted(pos5, 5); + for (auto e : countedView) // outputs 5 6 7 8 9 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // You can pass the range directly if it supports input_or_output_iterator, in which case, the + // count starts from the first element + const char chars[] = { 'H','i',' ','t','h','e','r','e' }; + for (char c : std::views::counted(chars, 2)) + { + std::cout << c; // outputs Hi + } +} +``` + +```output +5 6 7 8 9 +Hi +``` + +## `operator PairLike` + +Convert a `subrange` to a type that models `pair-like`. + +```cpp +template PairLike> +requires pair-like-convertible-from +constexpr operator PairLike() const; +``` + +### Parameters + +None. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `PairLike` value that is direct-initialized with the stored iterator and sentinel. +The last value in the pair will be the sentinel. + +Remember that the sentinel is *past* the last element in the subrange, as shown in the example below. + +### Remarks + +This conversion is useful with older `Boost::Ranges` code that accepts (first, last) pairs to denote a range.\ +This conversion is useful for converting a subrange to a `pair` or `tuple` or other type that models `pair_like`. Some examples of `pair_like` types are: + +```cpp +std::array +std::pair +std::ranges::subrange +std::tuple +``` + +### Example: `operator PairLike()` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + constexpr int a[] = {0, 1, 2, 3, 4, 5}; + std::ranges::subrange rg(a); + rg.advance(2); + const std::pair p = rg; + for (auto e : rg) + { + std::cout << e << ' '; + } + + // because the sentinel points after the last element, subtract one to get the last element + std::cout << '\n' << *p.first << ':' << *(p.second - 1) << '\n'; // outputs 2:5 + } +``` + +```output +2 3 4 5 +2:5 +``` + +## `advance` + +Adjust the iterator for this `subrange` by *`n`* elements. + +```cpp +constexpr subrange& advance(const iter_difference_t n); +``` + +### Parameters + +*`n`*\ +How many elements to adjust the iterator. *`n`* can be positive (move forward) or, if *`I`* is bidirectional, negative (move backward). + +### Remarks + +This function modifies the current state of the iterator in the `subrange`. + +If you advance past the end of the `subrange`, the iterator is set to the sentinel at the end of the `subrange`.\ +If you advance past the beginning of the `subrange` (using a negative `n`), you'll get an invalid parameter exception if the range you made the `subrange` from doesn't have an element in the place. + +### Example `advance` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; + print("Original vector: ", v); // outputs 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange 3 4 5 6 + std::ranges::subrange theSubrange{ std::ranges::find(v,3), std::ranges::find(v, 7) }; + print("The subrange: ", theSubrange); // outputs 3 4 5 6 + + auto sr = theSubrange.advance(2); // get a subrange 2 positions to the right of the current iterator location + print("theSubrange.advance(2): ", sr); // outputs 5 6 + print("Note that subrange's iterator moved during advance(): ", sr); // outputs 5 6 + sr = theSubrange.advance(-3); // Moving before the subrange, but onto a valid element in the original range + print("theSubrange.advance(-3): ", sr); // outputs 2 3 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +3 4 5 6 +theSubrange.advance(2): +5 6 +Note that subrange's iterator moved during advance(): +5 6 +theSubrange.advance(-3): +2 3 4 5 6 +``` + +## `begin` + +Get an iterator to the first element in the `subrange`. + +```cpp +1) constexpr I begin() const requires copyable; +2) [[nodiscard]] constexpr I begin() requires (!std::copyable); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `subrange`. +If the iterator isn't copyable, it's returned with `std::move()`. If the iterator is moved, the state of the stored iterator depends on the implementation of the move constructor for *`I`*. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `empty` + +Test whether the `subrange` is empty. + +```cpp +constexpr bool empty() const; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the `subrange` has no elements. Otherwise, returns `false`. + +## `end` + +Get the sentinel at the end of the `subrange` + +```cpp +[[nodiscard]] constexpr S end() const; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `subrange`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +The sentinel is copy-constructed from the stored sentinel. + +## `next` + +Creates a copy of this `subrange` but with the stored iterator moved forward the specified distance. + +```cpp +1) [[nodiscard]] constexpr subrange next(iter_difference_t n = 1) const & requires forward_iterator; +2) [[nodiscard]] constexpr subrange next(iter_difference_t n = 1) &&; +``` + +### Parameters + +*`n`*\ +How many elements to move the iterator forward. Defaults to 1. Must be positive. + +### Return value + +Returns a copy of the `subrange` starting at the *`n`*th element. + +### Remarks + +Unlike `advance()`, `next()` doesn't change the location of the iterator stored in the original `subrange`. +The returned `subrange` has all the elements that the original subrange has, but the iterator is in a different location. + +1\) The return value is the same as: + +```cpp +auto tmp = *this; +tmp.advance(n); +return tmp; +``` + +2\) The return value is the same as: + +```cpp +advance(n); +return std::move(*this); +``` + +### Example: `next` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; + print("Original vector:", v); // 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange from the front of v up to (but not including) the element 7 + std::ranges::subrange theSubrange{ std::ranges::find(v,1), std::ranges::find(v, 7) }; + print("The subrange:", theSubrange); // 1 2 3 4 5 6 + + auto forward = theSubrange.advance(3); // get a subrange 3 positions to the right of the current iterator location + print("theSubrange.advance(3):", forward); // 4 5 6 + + // prev() + auto previous = theSubrange.prev(2); // move back 2 + print("theSubrange.prev(2):", previous); // 2 3 4 5 6 + print("Note that the subrange's iterator did *not* move during prev():", theSubrange); // 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +1 2 3 4 5 6 +theSubrange.next(3): +4 5 6 +Note that the original subrange's iterator did *not* move during next(): +1 2 3 4 5 6 +``` + +## `prev` + +Creates a copy of this `subrange`, but with the stored iterator moved back the specified distance. + +```cpp +[[nodiscard]] constexpr subrange prev(std::iter_difference_t n = 1 ) const + requires std::bidirectional_iterator; +``` + +### Parameters + +*`n`*\ +How many elements to move the iterator back. Defaults to 1. Must be positive. + +### Return value + +Returns a copy of the `subrange` but with the iterator moved back *`n`* elements. + +### Remarks + +Unlike `advance()`, `prev()` doesn't change the location of the iterator stored in the original `subrange`.\ +The returned `subrange` has all the elements that the original subrange has, but the iterator is just in a different location. You can think of the return value as: + +```cpp +auto tmp = *this; +tmp.advance(-n); +return tmp; +``` + +### Example `prev` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + print("Original vector:", v); // 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange from the front of v up to (but not including) the element 7 + std::ranges::subrange theSubrange{std::ranges::find(v,1), std::ranges::find(v, 7)}; + print("The subrange: ", theSubrange); // 1 2 3 4 5 6 + + auto forward = theSubrange.advance(3); // get a subrange 3 positions to the right of the current iterator location + print("theSubrange.advance(3):", forward); // 4 5 6 + + // prev() + auto previous = theSubrange.prev(2); // move back 2 + print("theSubrange.prev(2):", previous); // 2 3 4 5 6 + print("Note that the subrange's iterator did *not* move during prev():", theSubrange); // 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +1 2 3 4 5 6 +theSubrange.advance(3): +4 5 6 +theSubrange.prev(2): +2 3 4 5 6 +Note that the subrange's iterator did *not* move during prev(): +4 5 6 +``` + +## `size` + +Get the number of elements in the `subrange`. + +```cpp +constexpr size() const + requires (K == ranges::subrange_kind::sized); +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `subrange`. + +If the size isn't stored, which is the case when the `subrange` is created with `K == ranges::subrange_kind::sized` specified and `std::sized_sentinel_for` isn't satisfied, then the size is returned as the distance between the begin and end iterators. + +Changing the position of the `begin` iterator, with `advance`, for example, changes the reported size. + +## See also + +[``](ranges.md)\ +[`counted`](range-adaptors.md#counted)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/subtract-with-carry-engine-class.md b/docs/standard-library/subtract-with-carry-engine-class.md index 4e2f83f4eb..4fdbbc4149 100644 --- a/docs/standard-library/subtract-with-carry-engine-class.md +++ b/docs/standard-library/subtract-with-carry-engine-class.md @@ -60,7 +60,7 @@ Although you can construct a generator from this engine directly, you can also u `ranlux48_base`: Used as a base for `ranlux48`. `typedef subtract_with_carry_engine ranlux48_base;` -For detailed information about the subract with carry engine algorithm, see the Wikipedia article [Lagged Fibonacci generator](https://en.wikipedia.org/wiki/Lagged_Fibonacci_generator). +For detailed information about the subtract with carry engine algorithm, see the Wikipedia article [Lagged Fibonacci generator](https://en.wikipedia.org/wiki/Lagged_Fibonacci_generator). ## Requirements diff --git a/docs/standard-library/sys-info-struct.md b/docs/standard-library/sys-info-struct.md index 7206b7775e..761b5e488a 100644 --- a/docs/standard-library/sys-info-struct.md +++ b/docs/standard-library/sys-info-struct.md @@ -1,8 +1,10 @@ --- -description: "Learn more about: sys_info struct" title: "sys_info struct" +description: "Learn more about: sys_info struct" ms.date: 09/08/2021 f1_keywords: ["chrono/std::chrono::sys_info"] +helpviewer_keywords: ["std::chrono [C++], sys_info"] +dev_langs: ["C++"] --- # `sys_info` struct @@ -22,9 +24,9 @@ Provides a low-level interface to time zone information about the result of conv |Function|Description| |---------|-------------| -|[`abbrev`](#abbrev)|The abbreviation used for the associated `time_zone` and `time_point.`| +|[`abbrev`](#abbrev)|The abbreviation used for the associated `time_zone` and `time_point`.| |[`begin`, `end`](#beginend)|The range that the `offset` and `abbrev` apply to for the associated time zone.| -|[`offset`](#offset)|The Universal Time Coordinated (UTC) offset in effect for the associated `time_zone` and `time_point.`| +|[`offset`](#offset)|The Universal Time Coordinated (UTC) offset in effect for the associated `time_zone` and `time_point`.| |[`save`](#save)|Daylight savings time adjustment offset.| ## Non-members diff --git a/docs/standard-library/system-clock-structure.md b/docs/standard-library/system-clock-structure.md index 13108583ab..d8bff11b41 100644 --- a/docs/standard-library/system-clock-structure.md +++ b/docs/standard-library/system-clock-structure.md @@ -3,6 +3,8 @@ description: "Learn more about: system_clock Structure" title: "system_clock Structure" ms.date: 07/26/2021 f1_keywords: ["chrono/std::chrono::system_clock", "chrono/std::chrono::system_clock::from_time_t", "chrono/std::chrono::system_clock::now", "chrono/std::chrono::system_clock::to_time_t", "chrono/std::chrono::system_clock::is_steady constant"] +helpviewer_keywords: ["std::chrono [C++], system_clock"] +dev_langs: ["C++"] --- # `system_clock` structure @@ -116,7 +118,7 @@ static time_t to_time_t(const time_point& Time) noexcept; ### Parameters *`Time`*\ -A [time_point](../standard-library/time-point-class.md) object. +A [`time_point`](../standard-library/time-point-class.md) object. ## See also diff --git a/docs/standard-library/system-error-functions.md b/docs/standard-library/system-error-functions.md index af053fb4cb..6de6c2d6a2 100644 --- a/docs/standard-library/system-error-functions.md +++ b/docs/standard-library/system-error-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: "03/15/2019" f1_keywords: ["system_error/std::generic_category", "system_error/std::make_error_code", "system_error/std::make_error_condition", "system_error/std::system_category"] -ms.assetid: 57d6f15f-f0b7-4e2f-80fe-31d3c320ee33 helpviewer_keywords: ["std::generic_category", "std::make_error_code", "std::make_error_condition", "std::system_category"] --- # `` functions @@ -18,20 +17,24 @@ const error_category& generic_category() noexcept; ### Remarks -The `generic_category` object is an implementation of [error_category](../standard-library/error-category-class.md). +The `generic_category` object is an implementation of [error_category](error-category-class.md). ## is_error_code_enum_v +A helper variable template for the [`is_error_code_enum`](is-error-code-enum-class.md) value. + ```cpp template - inline constexpr bool is_error_code_enum_v = is_error_code_enum::value; +constexpr bool is_error_code_enum_v = is_error_code_enum::value; ``` ## is_error_condition_enum_v +A helper variable template for the [`is_error_condition_enum`](is-error-condition-enum-class.md) value. + ```cpp template - inline constexpr bool is_error_condition_enum_v = is_error_condition_enum::value; +constexpr bool is_error_condition_enum_v = is_error_condition_enum::value; ``` ## make_error_code @@ -51,8 +54,6 @@ The `std::errc` enumeration value to store in the error code object. The error code object. -### Remarks - ## make_error_condition Creates an error condition object. @@ -64,17 +65,15 @@ error_condition make_error_condition(std::errc error) noexcept; ### Parameters *error*\ -The `std::errc` enumeration value to store in the error code object. +The `std::errc` enumeration value to store in the error condition object. ### Return Value The error condition object. -### Remarks - ## system_category -Represents the category for errors caused by low-level system overflows. +Represents the category for operating system errors. ```cpp const error_category& system_category() noexcept; @@ -82,4 +81,4 @@ const error_category& system_category() noexcept; ### Remarks -The `system_category` object is an implementation of [error_category](../standard-library/error-category-class.md). +The `system_category` object is an implementation of [error_category](error-category-class.md). diff --git a/docs/standard-library/system-error-operators.md b/docs/standard-library/system-error-operators.md index ad43985bc5..58a4e804c3 100644 --- a/docs/standard-library/system-error-operators.md +++ b/docs/standard-library/system-error-operators.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: "3/17/2025" f1_keywords: ["system_error/std::operator!=", "system_error/std::operator=="] -ms.assetid: c14edefb-bd8a-4e90-88d3-c59c98e6f73c --- # `` operators -## operator== +## `operator==` Tests if the object on the left side of the operator is equal to the object on the right side. @@ -24,11 +23,11 @@ bool operator==(const error_condition& left, ### Parameters -*left*\ -The object to be tested for equality. +*`left`*\ +The object to test for equality. -*right*\ -The object to be tested for equality. +*`right`*\ +The object to test for equality. ### Return Value @@ -38,7 +37,7 @@ The object to be tested for equality. This function returns `left.category() == right.category() && left.value() == right.value()`. -## operator!= +## `operator!=` Tests if the object on the left side of the operator is not equal to the object on the right side. @@ -51,15 +50,15 @@ bool operator!=(const error_condition& left, const error_condition& right); ### Parameters -*left*\ -The object to be tested for inequality. +*`left`*\ +The object to test for inequality. -*right*\ -The object to be tested for inequality. +*`right`*\ +The object to test for inequality. ### Return Value -**`true`** if the object passed in *left* is not equal to the object passed in *right*; otherwise **`false`**. +**`true`** if the object passed in *left* is not equal to the object passed in *`right`*; otherwise **`false`**. ### Remarks @@ -95,15 +94,15 @@ inline bool operator<( ### Parameters -*left*\ -The object to be compared. +*`left`*\ +The object to compare. -*right*\ -The object to be compared. +*`right`*\ +The object to compare. ### Return Value -**`true`** if the object passed in *left* is less than the object passed in *right*; Otherwise, **`false`**. +**`true`** if the object passed in *`left`* is less than the object passed in *`right`*; Otherwise, **`false`**. ### Remarks @@ -111,7 +110,42 @@ This function tests the error order. ## `operator<<` +Inserts an [`error_code`](error-code-class.md) object into the output stream. + ```cpp template - basic_ostream& operator<<(basic_ostream& os, const error_code& ec); +basic_ostream& operator<<(basic_ostream& os, const error_code& ec); +``` + +### Parameters + +*`os`*\ +The target output stream. + +*`ec`*\ +The `error_code` object to output. + +### Return Value + +A reference to the modified output stream. + +### Remarks + +This operator does the equivalent of `os << ec.category().name() << ':' << ec.value()`. + +### Example + +```cpp +#include +#include + +int main() +{ + std::error_code ec(1234, std::generic_category()); + std::cout << ec; +} +``` + +```Output +generic:1234 ``` diff --git a/docs/standard-library/tai-clock-class.md b/docs/standard-library/tai-clock-class.md index c3d27b345d..46030e9f9b 100644 --- a/docs/standard-library/tai-clock-class.md +++ b/docs/standard-library/tai-clock-class.md @@ -3,6 +3,8 @@ description: "Learn more about: tai_clock class" title: "tai_clock class" ms.date: 08/19/2021 f1_keywords: ["chrono/std::chrono::tai_clock", "chrono/std::chrono::tai_clock::now", "chrono/std::chrono::tai_clock::to_utc", "chrono/std::chrono::tai_clock::from_utc", "chrono/std::chrono::tai_clock::is_steady Constant", "std::chrono::tai_clock::get_leap_second_info"] +helpviewer_keywords: ["std::chrono [C++], tai_clock"] +dev_langs: ["C++"] --- # `tai_clock` class @@ -125,7 +127,7 @@ static time_point now() noexcept; ### Return Value -A [time_point](../standard-library/time-point-class.md) object that represents the current time. The returned time point is effectively `from_utc(utc_clock::now())`. +A [`time_point`](../standard-library/time-point-class.md) object that represents the current time. The returned time point is effectively `from_utc(utc_clock::now())`. ## See also diff --git a/docs/standard-library/take-view-class.md b/docs/standard-library/take-view-class.md new file mode 100644 index 0000000000..a6902be087 --- /dev/null +++ b/docs/standard-library/take-view-class.md @@ -0,0 +1,223 @@ +--- +title: take_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) take_view class. It's a view that contains the specified number of elements taken from the front of another view." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::take_view", "ranges/std::take_view::base", "ranges/std::take_view::begin", "ranges/std::take_view::data", "ranges/std::take_view::empty", "ranges/std::take_view::end", "ranges/std::take_view::size", "ranges/std::take_view::operator bool", "ranges/std::take_view::back", "ranges/std::take_view::front", "ranges/std::take_view::operator[]"] +helpviewer_keywords: ["std::ranges::take_view [C++]", "std::ranges::take_view::base [C++]", "std::ranges::take_view::begin [C++]", "std::ranges::take_view::data [C++]", "std::ranges::take_view::empty [C++]", "std::ranges::take_view::size [C++]", "std::ranges::take_view::end [C++]", +"std::ranges::take_view::back [C++]", "std::ranges::take_view::front [C++]", "std::ranges::take_view::operator[] [C++]", "std::ranges::take_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `take_view` class (C++ Standard Library) + +A view of the first *N* elements from another view. + +## Syntax + +```cpp +template +class take_view : public view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying range. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::take`](range-adaptors.md#take) | +| **Underlying range** | Any range | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Only if the underlying range satisfies [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range) | +| **Borrowed range** | Only if the underlying range is [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `take_view` + +```cpp +1) take_view() requires default_initializable = default; +2) constexpr take_view(V base, range_difference_t count); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`count`*\ +The number of elements to take from the front of the underlying view. If *`count`* is more than the number of elements in the underlying view, the view will contain all the elements in the underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `take_view`, which is a view of the first *N* elements from another view. If you specify more elements to drop than exist in the underlying range, an `empty_view` is returned. + +### Remarks + +The best way to create a `take_view` is by using the [`views::take`](range-adaptors.md#take) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `take_view` that has no elements. The underlying view is default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `take_view` from a *`base`* and a count. *`base`* is moved via `std::move()`. + +If *`count`* is less than the number of elements in the underlying range, then `count` determines the size of the `take_view`.\ +If *`count`* is greater than the number of elements in the underlying range, then the `take_view` includes all of the elements in the underlying range. + +### Example: `take_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6}; + + auto newView = std::views::take(v, 3); + + for (auto& e : newView) + { + std::cout << e << ' '; // 0 1 2 + } + std::cout << '\n'; + + // Use the '|' operator to create a take_view + for (auto i : v | std::views::take(3)) + { + std::cout << i << ' '; // 0 1 2 + } +} +``` + +```output +0 1 2 +0 1 2 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin() requires (!Simple_view); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the `Simple_view` requirement means that the view `V` and `const V` must have the same iterator and sentinel types. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() requires !(Simple_view); +2) constexpr auto end() const requires range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the `Simple_view` requirement means that the view `V` and `const V` must have the same iterator and sentinel types. + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range; +constexpr auto size() const requires sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `take_view`.\ +If the `take_view` was constructed with an explicit *`count`*: + +- if *`count`* is less than the number of elements in the underlying range, it's returned as the size of the view. +- if *`count`* is greater than the number of elements in the underlying range, then the size of the view is `ranges::size(base)`. + +## See also + +[``](ranges.md)\ +[`take` range adaptor](range-adaptors.md#take)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/take-while-view-class.md b/docs/standard-library/take-while-view-class.md new file mode 100644 index 0000000000..cfbf93e15b --- /dev/null +++ b/docs/standard-library/take-while-view-class.md @@ -0,0 +1,242 @@ +--- +title: take_while_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) take_while_view class, which is a view that contains the leading elements of a range that match a predicate." +ms.date: 08/04/2022 +f1_keywords: ["ranges/std::take_while_view", "ranges/std::take_while_view::base", "ranges/std::take_while_view::begin", "ranges/std::take_while_view::data", "ranges/std::take_while_view::empty", "ranges/std::take_while_view::end", "ranges/std::take_while_view::size", "ranges/std::take_while_view::operator bool", "ranges/std::take_while_view::pred", "ranges/std::take_while_view::back", "ranges/std::take_while_view::front", "ranges/std::take_while_view::operator[]"] +helpviewer_keywords: ["std::ranges::take_while_view [C++]", "std::ranges::take_while_view::base [C++]", "std::ranges::take_while_view::begin [C++]", "std::ranges::take_while_view::data [C++]", "std::ranges::take_while_view::empty [C++]", "std::ranges::take_while_view::size [C++]", "std::ranges::take_while_view::end [C++]", +"std::ranges::take_while_view::pred [C++]", "std::ranges::take_while_view::back [C++]", "std::ranges::take_while_view::front [C++]", "std::ranges::take_while_view::operator[] [C++]", "std::ranges::take_while_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `take_while_view` class (C++ Standard Library) + +A view that contains the leading elements of a range that match a predicate. + +## Syntax + +```cpp +template requires + input_range && is_object_v && + indirect_unary_predicate> +class take_while_view : public view_interface>; +``` + +### Template parameters + +*`Pred`*\ +The type of the predicate that determines the leading elements to put in the view. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::take_while`](range-adaptors.md#take_while) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and the predicate can work with `const` references. | +| **Common range** | No | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`pred`](#pred)C++20 | Get a reference to the predicate that determines which elements to take. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | +| [`size`](view-interface.md#size) | Get the number of elements in the view. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `take_while_view` + +```cpp +1) take_while_view() requires + default_initializable && + default_initializable = default; + +2) constexpr take_while_view(V base, Pred pred); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`pred`*\ +The predicate that determines the leading elements to put in the view. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `take_while_view` object. + +### Remarks + +The best way to create a `take_while_view` is by using the [`views::take_while`](range-adaptors.md#take_while) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Move constructs the `take_while_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`.\ +2\) Constructs an empty `take_while_view`. The underlying view and predicate are default constructed. + +### Example: `take_while_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto twv = std::views::take_while(v, [](int i) {return i >= 0; }); + + for (auto& e : twv) + { + std::cout << e << ' '; // 0 1 2 3 + } + std::cout << '\n'; + + // Using the '|' operator to create a take_view + for (auto i : v | std::views::take_while([](int i) {return i < 5; })) + { + std::cout << i << ' '; // 0 1 2 3 -4 + } +} +``` + +```output +0 1 2 3 +0 1 2 3 -4 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +A copy of the underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires + range && + indirect_unary_predicate> +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the [`Simple_view`](range-concepts.md#simple_view) requirement means that a view *`V`* and `const V` have the same iterator and sentinel types. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() requires (!Simple_view); +2) constexpr auto end() const requires + range && + indirect_unary_predicate +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the [`Simple_view`](range-concepts.md#simple_view) requirement means that a view *`V`* and `const V` have the same iterator and sentinel types. + +## `pred` + +Get a reference to the predicate used to select which leading elements will go in the view. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + +A reference to the predicate used to select the leading elements to put in the view. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto mv = v | std::views::take_while( + [](int i) {return i < 5; }); + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs false because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +## See also + +[``](ranges.md)\ +[`take_view`](take-view-class.md)\ +[`take_while` range adaptor](range-adaptors.md#take_while)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/thread-class.md b/docs/standard-library/thread-class.md index a6bfa2c531..e16b853338 100644 --- a/docs/standard-library/thread-class.md +++ b/docs/standard-library/thread-class.md @@ -1,10 +1,12 @@ --- description: "Learn more about: thread Class" title: "thread Class" -ms.date: "08/17/2021" +ms.date: 09/11/2024 f1_keywords: ["thread/std::thread", "thread/std::thread::id Class", "thread/std::thread::thread", "thread/std::thread::detach", "thread/std::thread::get_id", "thread/std::thread::hardware_concurrency", "thread/std::thread::join", "thread/std::thread::joinable", "thread/std::thread::native_handle", "thread/std::thread::swap"] helpviewer_keywords: ["std::thread [C++]", "std::thread [C++], thread", "std::thread [C++], detach", "std::thread [C++], get_id", "std::thread [C++], hardware_concurrency", "std::thread [C++], join", "std::thread [C++], joinable", "std::thread [C++], native_handle", "std::thread [C++], swap"] +ms.custom: devdivchpfy22 --- + # `thread` Class Defines an object that's used to observe and manage a thread of execution within an application. @@ -17,7 +19,7 @@ class thread; ## Remarks -You can use a `thread` object to observe and manage a thread of execution within an application. A `thread` object that's created by using the default constructor isn't associated with any thread of execution. A `thread` object that's constructed by using a callable object creates a new thread of execution and calls the callable object in that `thread`. `Thread` objects can be moved but not copied. Which is why a thread of execution can be associated with only one `thread` object. +You can use a `thread` object to observe and manage a thread of execution within an application. A `thread` object that's created by using the default constructor isn't associated with any thread of execution. A `thread` object that's constructed by using a callable object creates a new thread of execution and calls the callable object in that `thread`. `Thread` objects can be moved but not copied, which is why a thread of execution can be associated with only one `thread` object. Every thread of execution has a unique identifier of type `thread::id`. The function `this_thread::get_id` returns the identifier of the calling thread. The member function `thread::get_id` returns the identifier of the thread that's managed by a `thread` object. For a default-constructed `thread` object, the `thread::get_id` method returns an object that has a value that's the same for all default-constructed `thread` objects and different from the value that's returned by `this_thread::get_id` for any thread of execution that could be joined at the time of the call. @@ -71,9 +73,9 @@ void detach(); After a call to `detach`, subsequent calls to [`get_id`](#get_id) return [`id`](#id_class). -If the thread that's associated with the calling object isn't joinable, the function throws a [`system_error`](../standard-library/system-error-class.md) that has an error code of `invalid_argument`. +If the thread associated with the calling object isn't joinable, the function throws a [`system_error`](../standard-library/system-error-class.md) that has an error code of `invalid_argument`. -If the thread that's associated with the calling object is invalid, the function throws a `system_error` that has an error code of `no_such_process`. +If the thread associated with the calling object is invalid, the function throws a `system_error` that has an error code of `no_such_process`. ## `get_id` @@ -83,9 +85,9 @@ Returns a unique identifier for the associated thread. id get_id() const noexcept; ``` -### Return Value +### Return value -A [`id`](#id_class) object that uniquely identifies the associated thread, or `id()` if no thread is associated with the object. +An [`id`](#id_class) object that uniquely identifies the associated thread, or `id()` if no thread is associated with the object. ## `hardware_concurrency` @@ -95,15 +97,17 @@ Static method that returns an estimate of the number of hardware thread contexts static unsigned int hardware_concurrency() noexcept; ``` -### Return Value +### Return value + +An estimate of the number of hardware thread contexts. If the value can't be computed or isn't well defined, this method returns 0. + +**Microsoft specific** -An estimate of the number of hardware thread contexts. If the value cannot be computed or isn't well defined, this method returns 0. +`hardware_concurrency` returns the number of logical processors, which corresponds to the number of hardware threads that can execute simultaneously. It takes into account the number of physical processors, the number of cores in each physical processor, and simultaneous multithreading on each single core. -### Microsoft Specific +Before Windows 11 and Windows Server 2022, applications were limited by default to a single processor group, having at most 64 logical processors. This limited the number of concurrently executing threads to 64. For more information, see [Processor Groups](/windows/win32/procthread/processor-groups). -`hardware_concurrency` is currently defined to return the number of logical processors, which corresponds to the number of hardware threads that can execute simultaneously. It takes into account the number of physical processors, the number of cores in each physical processor, and simultaneous multithreading on each single core. - -However, on systems with more than 64 logical processors this number is capped by the number of logical processors in a single group; see [Processor Groups](/windows/win32/procthread/processor-groups). +Starting with Windows 11 and Windows Server 2022, processes and their threads have processor affinities that by default span all processors in the system and across multiple groups on machines with more than 64 processors. The limit on the number of concurrent threads is now the total number of logical processors in the system. ## `id` class @@ -123,7 +127,7 @@ All default-constructed `thread::id` objects compare equal. ## `join` -Blocks until the thread of execution that's associated with the calling object completes. +Blocks until the thread of execution associated with the calling object completes. ```cpp void join(); @@ -141,7 +145,7 @@ Specifies whether the associated thread is joinable. bool joinable() const noexcept; ``` -### Return Value +### Return value **`true`** if the associated thread is joinable; otherwise, **`false`**. @@ -157,9 +161,9 @@ Returns the implementation-specific type that represents the thread handle. The native_handle_type native_handle(); ``` -### Return Value +### Return value -`native_handle_type` is defined as a Win32 `HANDLE` that's cast as `void *`. +`native_handle_type` is defined as a Win32 `HANDLE` cast as `void *`. ## `thread::operator=` @@ -174,7 +178,7 @@ thread& operator=(thread&& Other) noexcept; *`Other`*\ A `thread` object. -### Return Value +### Return value `*this` @@ -212,7 +216,7 @@ thread(thread&& Other) noexcept; ### Parameters *`F`*\ -An application-defined function to be executed by the thread. +An application-defined function to execute on the thread. *`A`*\ A list of arguments to be passed to *`F`*. @@ -222,9 +226,9 @@ An existing `thread` object. ### Remarks -The first constructor constructs an object that's not associated with a thread of execution. The value that's returned by a call to `get_id` for the constructed object is `thread::id()`. +The first constructor constructs an object that's not associated with a thread of execution. The value returned by `get_id` for the constructed object is `thread::id()`. -The second constructor constructs an object that's associated with a new thread of execution and executes the pseudo-function `INVOKE` that's defined in [``](../standard-library/functional.md). If not enough resources are available to start a new thread, the function throws a [`system_error`](../standard-library/system-error-class.md) object that has an error code of `resource_unavailable_try_again`. If the call to *`F`* terminates with an uncaught exception, [`terminate`](../standard-library/exception-functions.md#terminate) is called. +The second constructor constructs an object that's associated with a new thread of execution. It executes the pseudo-function `INVOKE` defined in [``](../standard-library/functional.md). If not enough resources are available to start a new thread, the function throws a [`system_error`](../standard-library/system-error-class.md) object that has an error code of `resource_unavailable_try_again`. If the call to *`F`* terminates with an uncaught exception, [`terminate`](../standard-library/exception-functions.md#terminate) is called. The call to *`F`* must not cause the thread to exit prematurely, such as by calling `ExitThread` or `_endthreadex`. The third constructor constructs an object that's associated with the thread that's associated with `Other`. `Other` is then set to a default-constructed state. diff --git a/docs/standard-library/thread-functions.md b/docs/standard-library/thread-functions.md index 8f7e9b2362..eea1f7215e 100644 --- a/docs/standard-library/thread-functions.md +++ b/docs/standard-library/thread-functions.md @@ -8,12 +8,6 @@ helpviewer_keywords: ["std::get_id [C++]", "std::sleep_for [C++]", "std::sleep_u --- # `` functions -[get_id](#get_id)\ -[sleep_for](#sleep_for)\ -[sleep_until](#sleep_until)\ -[swap](#swap)\ -[yield](#yield) - ## get_id Uniquely identifies the current thread of execution. diff --git a/docs/standard-library/thread-operators.md b/docs/standard-library/thread-operators.md index ad1f33155d..485cbf10b5 100644 --- a/docs/standard-library/thread-operators.md +++ b/docs/standard-library/thread-operators.md @@ -1,20 +1,13 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["thread/std::operator!=", "thread/std::operator>", "thread/std::operator>=", "thread/std::operator<", "thread/std::operator<<", "thread/std::operator<=", "thread/std::operator=="] -ms.assetid: e6bb6c0f-64f9-4cb2-9ff2-05b88a6ba7ac helpviewer_keywords: ["std::operator!= (thread)", "std::operator> (thread)", "std::operator>= (thread)", "std::operator< (thread)", "std::operator<< (thread)", "std::operator<= (thread)", "std::operator== (thread)"] --- # `` operators -[operator!=](#op_neq)\ -[`operator>`](#op_gt)\ -[`operator>=`](#op_gt_eq)\ -[`operator<`](#op_lt)\ -[`operator<<`](#op_lt_lt)\ -[`operator<=`](#op_lt_eq)\ -[operator==](#op_eq_eq) +The `` header provides the following operators: ## `operator>=` diff --git a/docs/standard-library/time-get-byname-class.md b/docs/standard-library/time-get-byname-class.md index 25750ba601..abd437c52b 100644 --- a/docs/standard-library/time-get-byname-class.md +++ b/docs/standard-library/time-get-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: time_get_byname Class" title: "time_get_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: time_get_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xloctime/std::time_get_byname"] helpviewer_keywords: ["time_get_byname class"] -ms.assetid: 6e54153e-da40-4bb9-a942-1a6ce57b30c9 --- # time_get_byname Class @@ -41,7 +40,7 @@ An initial reference count. ## Requirements -Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [time_get](../standard-library/time-get-class.md#time_get)\( `_Refs`). +Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [time_get](../standard-library/time-get-class.md#time_get)\(`_Refs`). **Header:** \ diff --git a/docs/standard-library/time-point-class.md b/docs/standard-library/time-point-class.md index 52cc91381e..b5b9baf42b 100644 --- a/docs/standard-library/time-point-class.md +++ b/docs/standard-library/time-point-class.md @@ -2,8 +2,9 @@ description: "Learn more about: time_point Class" title: "time_point Class" ms.date: 01/05/2022 -f1_keywords: ["chrono/std::chrono::time_point", "chrono/std::chrono::time_point::time_point", "chrono/std::chrono::time_point::max", "chrono/std::chrono::time_point::min", "chrono/std::chrono::time_point::time_since_epoch"] +f1_keywords: ["chrono/std::chrono::time_point", "chrono/std::chrono::time_point::operator +=", "chrono/std::chrono::time_point::operator -=", "chrono/std::chrono::time_point::max", "chrono/std::chrono::time_point::min", "chrono/std::chrono::time_point::time_since_epoch"] helpviewer_keywords: ["std::chrono [C++], time_point"] +dev_langs: ["C++"] --- # `time_point` class diff --git a/docs/standard-library/time-put-class.md b/docs/standard-library/time-put-class.md index 60255f4f25..7792d1448d 100644 --- a/docs/standard-library/time-put-class.md +++ b/docs/standard-library/time-put-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: time_put Class" title: "time_put Class" -ms.date: "11/04/2016" +description: "Learn more about: time_put Class" +ms.date: 11/04/2016 f1_keywords: ["xloctime/std::time_put", "locale/std::time_put::char_type", "locale/std::time_put::iter_type", "locale/std::time_put::do_put", "locale/std::time_put::put"] helpviewer_keywords: ["std::time_put [C++]", "std::time_put [C++], char_type", "std::time_put [C++], iter_type", "std::time_put [C++], do_put", "std::time_put [C++], put"] -ms.assetid: df79493e-3331-48d2-97c3-ac3a745f0791 --- # time_put Class @@ -176,7 +175,7 @@ An iterator to the first position after the last element inserted. ### Remarks -The first member function returns [do_put](#do_put)(`next`, `_Iosbase`, `_Fill`, `_Pt`, `_Fmt`, `_Mod`). The second member function copies to \* `next` ++ any element in the interval [ `first`, `last`) other than a percent (%). For a percent followed by a character *C* in the interval [ `first`, `last`), the function instead evaluates `next` = `do_put`( `next`, `_Iosbase`, `_Fill`, `_Pt`, *C*, 0) and skips past *C*. If, however, *C* is a qualifier character from the set EOQ#, followed by a character `C2` in the interval [ `first`, `last`), the function instead evaluates `next` = `do_put`( `next`, `_Iosbase`, `_Fill`, `_Pt`, `C2`, *C*) and skips past `C2`. +The first member function returns [do_put](#do_put)(`next`, `_Iosbase`, `_Fill`, `_Pt`, `_Fmt`, `_Mod`). The second member function copies to \* `next` ++ any element in the interval [ `first`, `last`) other than a percent (%). For a percent followed by a character *C* in the interval [ `first`, `last`), the function instead evaluates `next` = `do_put`(`next`, `_Iosbase`, `_Fill`, `_Pt`, *C*, 0) and skips past *C*. If, however, *C* is a qualifier character from the set EOQ#, followed by a character `C2` in the interval [ `first`, `last`), the function instead evaluates `next` = `do_put`(`next`, `_Iosbase`, `_Fill`, `_Pt`, `C2`, *C*) and skips past `C2`. ### Example diff --git a/docs/standard-library/time-zone-class.md b/docs/standard-library/time-zone-class.md index 23085ae06a..bfe3dc1723 100644 --- a/docs/standard-library/time-zone-class.md +++ b/docs/standard-library/time-zone-class.md @@ -1,9 +1,10 @@ --- description: "Learn more about: time_zone class" title: "time_zone class" -ms.date: 09/30/2021 +ms.date: 05/31/2022 f1_keywords: ["chrono/std::chrono::time_zone::name", "chrono/std::chrono::time_zone::get_info", "chrono/std::chrono::time_zone::to_sys", "chrono/std::chrono::time_zone::to_local"] helpviewer_keywords: ["std::chrono [C++], time_zone class", "std::chrono::time_zone::name function", "std::chrono::time_zone::get_info function", "std::chrono::time_zone::to_sys function", "std::chrono::time_zone::to_local function"] +dev_langs: ["C++"] --- # `time_zone` class @@ -45,6 +46,8 @@ Microsoft C++ supports the `time_zone` class starting in Visual Studio 2019 vers **Header:** `` +Time-zone data is only available for Windows 10 version 1903/19H1 and later, and Windows Server 2022 and later. + **Namespace:** `std::chrono` ## `get_info` diff --git a/docs/standard-library/time-zone-link-class.md b/docs/standard-library/time-zone-link-class.md index 12c68d494c..acde293758 100644 --- a/docs/standard-library/time-zone-link-class.md +++ b/docs/standard-library/time-zone-link-class.md @@ -1,9 +1,10 @@ --- description: "Learn more about: time_zone_link class" title: "time_zone_link class" -ms.date: 9/15/2021 +ms.date: 05/31/2022 f1_keywords: ["chrono/std::chrono::time_zone_link::name", "chrono/std::chrono::time_zone_link::target"] helpviewer_keywords: ["std::chrono [C++], time_zone_link class", "std::chrono::time_zone_link::name function", "std::chrono::time_zone_link::target function"] +dev_langs: ["C++"] --- # `time_zone_link` class @@ -23,10 +24,7 @@ Although this type has a default move constructor and move assignment operator, **Differences with IANA database** -In Microsoft's implementation, time zone data can differ in some cases from the Internet Assigned Numbers Authority (IANA) time zone database. For example, `"America/Nuuk"` is returned instead of `"America/Godthab"` (`"America/Nuuk"` was renamed `"America/Godthab"` in April 2020). We don't supply the `"Eastern War Time EWT"` time zone at this time. See [Issue #1786](https://github.com/microsoft/STL/issues/1786) on the Microsoft STL GitHub repo for more details. - -> [!NOTE] -> At this time, time-zone data is only available on Windows version 19H1, and later. If you’re running on a version earlier than 19H1, you’ll get an exception: "The specified module could not be found". +In Microsoft's implementation, time zone data can differ in some cases from the Internet Assigned Numbers Authority (IANA) time zone database. For example, `"America/Nuuk"` is returned instead of `"America/Godthab"` (`"America/Nuuk"` was renamed `"America/Godthab"` in April 2020). We don't supply the `"Eastern War Time EWT"` time zone at this time. For more information, see [Issue #1786](https://github.com/microsoft/STL/issues/1786) on the Microsoft STL GitHub repo. ## Members @@ -48,6 +46,8 @@ In Microsoft's implementation, time zone data can differ in some cases from the **Header:** `` +Time-zone data is only available for Windows 10 version 1903/19H1 and later, and Windows Server 2022 and later. + **Namespace:** `std::chrono` **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) diff --git a/docs/standard-library/toc.yml b/docs/standard-library/toc.yml index ce3cb76ff5..da06070882 100644 --- a/docs/standard-library/toc.yml +++ b/docs/standard-library/toc.yml @@ -592,6 +592,8 @@ items: items: - name: href: iterator.md + - name: concepts + href: iterator-concepts.md - name: functions href: iterator-functions.md - name: operators @@ -795,6 +797,8 @@ items: href: recursive-mutex-class.md - name: recursive_timed_mutex class href: recursive-timed-mutex-class.md + - name: scoped_lock class + href: scoped-lock-class.md - name: timed_mutex class href: timed-mutex-class.md - name: try_to_lock_t struct @@ -926,6 +930,62 @@ items: items: - name: href: ranges.md + - name: concepts + href: range-concepts.md + - name: functions + href: range-functions.md + - name: view classes + href: view-classes.md + expanded: false + items: + - name: basic_istream_view class + href: basic-istream-view-class.md + - name: common_view class + href: common-view-class.md + - name: drop_view class + href: drop-view-class.md + - name: drop_while_view class + href: drop-while-view-class.md + - name: elements_view class + href: elements-view-class.md + - name: empty_view class + href: empty-view-class.md + - name: filter_view class + href: filter-view-class.md + - name: iota_view class + href: iota-view-class.md + - name: join_view class + href: join-view-class.md + - name: keys_view class + href: keys-view-class.md + - name: lazy_split_view class + href: lazy-split-view-class.md + - name: owning_view class + href: owning-view-class.md + - name: ref_view class + href: ref-view-class.md + - name: reverse_view class + href: reverse-view-class.md + - name: single_view class + href: single-view-class.md + - name: split_view class + href: split-view-class.md + - name: subrange class + href: subrange-class.md + - name: take_view class + href: take-view-class.md + - name: take_while_view class + href: take-while-view-class.md + - name: transform_view class + href: transform-view-class.md + - name: values_view class + href: values-view-class.md + - name: view_interface + href: view-interface.md + - name: alias templates + href: ranges-alias-templates.md + - name: Range adaptors + href: range-adaptors.md - name: href: ratio.md - name: @@ -1389,6 +1449,8 @@ items: href: utility-operators.md - name: identity struct href: identity-structure.md + - name: in_place_t, in_place_type_t, in_place_index_t struct + href: in-place-t-struct.md - name: pair struct href: pair-structure.md - name: diff --git a/docs/standard-library/transform-view-class.md b/docs/standard-library/transform-view-class.md new file mode 100644 index 0000000000..287645db34 --- /dev/null +++ b/docs/standard-library/transform-view-class.md @@ -0,0 +1,250 @@ +--- +title: transform_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) transform_view class, which is a view of an underlying sequence after applying a transformation function to each element." +ms.date: 12/14/2022 +f1_keywords: ["ranges/std::transform_view", "ranges/std::transform_view::base", "ranges/std::transform_view::begin", "ranges/std::transform_view::empty", "ranges/std::transform_view::end", "ranges/std::transform_view::operator bool", "ranges/std::transform_view::back", "ranges/std::transform_view::front", "ranges/std::transform_view::operator[]"] +helpviewer_keywords: ["std::ranges::transform_view [C++]", "std::ranges::transform_view::base [C++]", "std::ranges::transform_view::begin [C++]", "std::ranges::transform_view::empty [C++]", "std::ranges::transform_view::end [C++]", "std::ranges::transform_view::back [C++]", "std::ranges::transform_view::front [C++]", "std::ranges::transform_view::operator bool [C++]", "std::ranges::transform_view::operator[] [C++]"] +dev_langs: ["C++"] +--- +# `transform_view` class (C++ Standard Library) + +A view of elements, each of which is a transformation of an element in the specified range. + +## Syntax + +```cpp +template + requires view && is_object_v && + regular_invocable> && + can-reference>> +class transform_view : public view_interface>; +``` + +### Template parameters + +*`F`*\ +The type of the function object that transforms the elements. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::transform`](range-adaptors.md#transform) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the transformation function's return type. | +| **View iterator category** | Supports [`input_range`](range-concepts.md#input_range) up to [`random_access_range`](range-concepts.md#random_access_range), depending on the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and the transformation works on `const` references. | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `transform_view` + +```cpp +1) transform_view() requires default_initializable + && default_initializable = default; +2) constexpr transform_view(V base, F func); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`func`*\ +The function that transforms each element. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `transform_view` instance. + +### Remarks + +The best way to create a `transform_view` is by using the [`views::transform`](range-adaptors.md#transform) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a value-initialized `transform_view`. The transformation function and the underlying view must be default-initializable.\ +2\) Move construct the `transform_view` from a *`base`* view and a transformation function *`func`*. Both *`base`* and *`func`* are moved via `std::move()`. + +### Example: `transform_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +using namespace std; +using namespace chrono; + +void print(auto v) +{ + for (auto x : v) + { + cout << x << ' '; + } + cout << '\n'; +} + +struct classes +{ + string className; + weekday startDay; +}; + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + + // outputs 0 2 4 6 -8 10 12 + print(v | std::views::transform([](int i) {return i * 2; })); + + // ---- Modify the elements in the collection by returning a reference to the element to transform + + std::vector theClasses = { + {"Math", Monday}, + {"English", Wednesday}, + {"History", Monday}, + {"Science", Wednesday}, + {"Art", Friday}, + {"Music", Thursday} + }; + + // lambda to get a reference to the day of the week for a class + auto getDay = [](classes& c) -> weekday& + { + return c.startDay; + }; + + // If a class starts on Monday, change it to Tuesday + for (auto&& startDay : theClasses | std::views::transform(getDay)) + { + // modify the startDay in the collection + if (startDay == Monday) + { + startDay = Tuesday; + } + } + + // output classes and start times + for (auto c : theClasses) + { + std::cout << c.className << " : " << c.startDay << '\n'; + } +} +``` + +```output +0 2 4 6 -8 10 12 +Math : Tue +English : Wed +History : Tue +Science : Wed +Art : Fri +Music : Thu +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## See also + +[``](ranges.md)\ +[`filter` range adaptor](range-adaptors.md#filter)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/treat-as-floating-point-structure.md b/docs/standard-library/treat-as-floating-point-structure.md index 17acbdc445..4dbd2818c3 100644 --- a/docs/standard-library/treat-as-floating-point-structure.md +++ b/docs/standard-library/treat-as-floating-point-structure.md @@ -1,8 +1,10 @@ --- -description: "Learn more about: treat_as_floating_point structure" title: "treat_as_floating_point Structure" +description: "Learn more about: treat_as_floating_point structure" ms.date: 07/16/2021 f1_keywords: ["chrono/std::chrono::treat_as_floating_point"] +helpviewer_keywords: ["std::chrono [C++], treat_as_floating_point"] +dev_langs: ["C++"] --- # `treat_as_floating_point` structure diff --git a/docs/standard-library/tuple-class.md b/docs/standard-library/tuple-class.md index dbb5511039..d4480af806 100644 --- a/docs/standard-library/tuple-class.md +++ b/docs/standard-library/tuple-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: tuple Class" title: "tuple Class" -ms.date: "11/04/2016" +ms.date: 06/20/2022 f1_keywords: ["tuple/std::tuple", "tuple/std::tuple::operator="] helpviewer_keywords: ["tuple class"] ms.assetid: c38749be-ae4d-41f3-98ea-6aa3250de9a3 +ms.custom: devdivchpfy22 --- + # tuple Class Wraps a fixed-length sequence of elements. diff --git a/docs/standard-library/tuple-size-class-tuple.md b/docs/standard-library/tuple-size-class-tuple.md index d69e3c9f2d..43ca9b50ea 100644 --- a/docs/standard-library/tuple-size-class-tuple.md +++ b/docs/standard-library/tuple-size-class-tuple.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: tuple_size Class;" -title: "tuple_size Class;" -ms.date: "11/04/2016" +title: "tuple_size class" +description: "Learn more about: tuple_size class" +ms.date: 06/29/2022 f1_keywords: ["tuple_size", "std::tuple_size", "utility/std::tuple_size"] helpviewer_keywords: ["std::tuple_size"] -ms.assetid: 73852fc5-eb68-41f1-8379-465cedc2314a --- -# tuple_size Class; +# `tuple_size` class Reports the number of elements that a `tuple` contains. @@ -43,37 +42,35 @@ template // size of const volatile tuple template struct tuple_size; -``` -```cpp template inline constexpr size_t tuple_size_v = tuple_size::value; ``` ### Parameters -*Tuple*\ +*`Tuple`*\ The type of the tuple. -*Elem*\ +*`Elem`*\ The type of the array elements. -*Size*\ +*`Size`*\ The size of the array. -*T1*\ +*`T1`*\ The type of the first member of the pair. -*T2*\ +*`T2`*\ The type of the second member of the pair. -*Types*\ +*`Types`*\ The types of the tuple elements. ## Remarks -The class template has a member `value` that is an integral constant expression whose value is the extent of the tuple type *Tuple*. +The class template has a member `value` that is an integral constant expression whose value is the extent of the tuple type *`Tuple`*. -The template specialization for arrays has a member `value` that is an integral constant expression whose value is *Size*, which is the size of the array. +The template specialization for arrays has a member `value` that is an integral constant expression whose value is *`Size`*, which is the size of the array. The template specialization for pair has a member `value` that is an integral constant expression whose value is 2. @@ -108,10 +105,10 @@ int main() ## Requirements -**Header:** \ +**Header:** `` -**Header:** \ (for array specialization) +**Header:** `` (for array specialization) -**Header:** \ (for pair specialization) +**Header:** `` (for pair specialization) -**Namespace:** std +**Namespace:** `std` diff --git a/docs/standard-library/type-index-class.md b/docs/standard-library/type-index-class.md index e02827ef04..1d79412bc5 100644 --- a/docs/standard-library/type-index-class.md +++ b/docs/standard-library/type-index-class.md @@ -1,11 +1,12 @@ --- -description: "Learn more about: type_index Class" title: "type_index Class" -ms.date: "11/04/2016" +description: "Learn more about: type_index Class" +ms.date: 06/20/2022 f1_keywords: ["typeindex/std::type_index"] helpviewer_keywords: ["type_index class"] -ms.assetid: db366119-74cb-43e8-aacf-9679e561fa2f +ms.custom: devdivchpfy22 --- + # type_index Class The `type_index` class wraps a pointer to [type_info Class](../cpp/type-info-class.md) to assist in indexing by such objects. @@ -27,7 +28,7 @@ The constructor initializes `ptr` to `&tinfo`. `name` returns `ptr->name()`. -`hash_code` returns `ptr->hash_code().` +`hash_code` returns `ptr->hash_code()`. `operator==` returns `*ptr == right.ptr`. @@ -35,7 +36,7 @@ The constructor initializes `ptr` to `&tinfo`. `operator<` returns `*ptr->before(*right.ptr)`. -`operator<=` returns `!(right < *this).` +`operator<=` returns `!(right < *this)`. `operator>` returns `right < *this`. diff --git a/docs/standard-library/type-traits-functions.md b/docs/standard-library/type-traits-functions.md index 4bf7fc0c66..1cf5eab06c 100644 --- a/docs/standard-library/type-traits-functions.md +++ b/docs/standard-library/type-traits-functions.md @@ -1,26 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" -ms.assetid: dce4492f-f3e4-4d5e-bdb4-5875321254ec +description: "Learn more about: functions" +ms.date: 11/04/2016 helpviewer_keywords: ["std::is_assignable", "std::is_copy_assignable", "std::is_copy_constructible", "std::is_default_constructible", "std::is_move_assignable", "std::is_move_constructible", "std::is_nothrow_move_assignable", "std::is_trivially_copy_assignable", "std::is_trivially_move_assignable", "std::is_trivially_move_constructible"] --- # `` functions -[is_assignable](#is_assignable)\ -[is_copy_assignable](#is_copy_assignable)\ -[is_copy_constructible](#is_copy_constructible)\ -[is_default_constructible](#is_default_constructible)\ -[is_move_assignable](#is_move_assignable)\ -[is_move_constructible](#is_move_constructible)\ -[is_nothrow_move_assignable](#is_nothrow_move_assignable)\ -[is_nothrow_swappable](#is_nothrow_swappable)\ -[is_nothrow_swappable_with](#is_nothrow_swappable_with)\ -[is_swappable](#is_swappable)\ -[is_swappable_with](#is_swappable_with)\ -[is_trivially_copy_assignable](#is_trivially_copy_assignable)\ -[is_trivially_move_assignable](#is_trivially_move_assignable)\ -[is_trivially_move_constructible](#is_trivially_move_constructible) +The `` header provides the following functions: ## is_assignable diff --git a/docs/standard-library/type-traits-typedefs.md b/docs/standard-library/type-traits-typedefs.md index b1df31e15f..95eaa6fc7b 100644 --- a/docs/standard-library/type-traits-typedefs.md +++ b/docs/standard-library/type-traits-typedefs.md @@ -1,14 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["type_traits/std::false_type", "xtr1common/std::false_type", "type_traits/std::true_type", "xtr1common/std::true_type"] -ms.assetid: 8ac040ca-ed2d-4570-adc9-cb5626530053 --- # `` typedefs -[false_type](#false_type)\ -[true_type](#true_type) +The `` header provides the following typedefs: ## false_type Typedef diff --git a/docs/standard-library/tzdb-list-class.md b/docs/standard-library/tzdb-list-class.md index c980ebaee9..b43b5a4bae 100644 --- a/docs/standard-library/tzdb-list-class.md +++ b/docs/standard-library/tzdb-list-class.md @@ -3,6 +3,8 @@ description: "Learn more about: tzdb_list class" title: "tzdb_list struct" ms.date: 10/13/2021 f1_keywords: ["chrono/std::chrono::tzdb_list", "chrono/std::chrono::tzdb_list::front", "chrono/std::chrono::tzdb_list::erase_after", "chrono/std::chrono::tzdb_list::begin", "chrono/std::chrono::tzdb_list::cbegin", "chrono/std::chrono::tzdb_list::end", "chrono/std::chrono::tzdb_list::cend"] +helpviewer_keywords: ["std::chrono [C++], tzdb_list"] +dev_langs: ["C++"] --- # `tzdb_list` class @@ -11,7 +13,7 @@ A list of time zone databases. ## Syntax ```cpp -class tzdb_list; // C++ 20 +class tzdb_list; // C++20 ``` ## Remarks diff --git a/docs/standard-library/tzdb-struct.md b/docs/standard-library/tzdb-struct.md index 76617218c7..071c37fda0 100644 --- a/docs/standard-library/tzdb-struct.md +++ b/docs/standard-library/tzdb-struct.md @@ -4,7 +4,7 @@ title: "tzdb struct" ms.date: 10/15/2021 f1_keywords: ["chrono/std::chrono::tzdb", "chrono/std::chrono::tzdb::leap_seconds", "chrono/std::chrono::tzdb::links", "chrono/std::chrono::tzdb::version", "chrono/std::chrono::tzdb::zones"] helpviewer_keywords: ["std::chrono [C++], tzdb"] - +dev_langs: ["C++"] --- # `tzdb` struct @@ -13,7 +13,7 @@ Represents a copy of the time zone database. ## Syntax ```cpp -struct tzdb; // C++ 20 +struct tzdb; // C++20 ``` ## Remarks diff --git a/docs/standard-library/unique-lock-class.md b/docs/standard-library/unique-lock-class.md index df637b7405..612058f1d8 100644 --- a/docs/standard-library/unique-lock-class.md +++ b/docs/standard-library/unique-lock-class.md @@ -1,10 +1,12 @@ --- description: "Learn more about: unique_lock Class" title: "unique_lock Class" -ms.date: "11/04/2016" +ms.date: 06/20/2022 f1_keywords: ["mutex/std::unique_lock"] ms.assetid: f4ed8ba9-c8af-446f-8ef0-0b356bad14bd +ms.custom: devdivchpfy22 --- + # unique_lock Class Represents a template that can be instantiated to create objects that manage the locking and unlocking of a `mutex`. diff --git a/docs/standard-library/unique-ptr-class.md b/docs/standard-library/unique-ptr-class.md index 307826a119..67e377b9d0 100644 --- a/docs/standard-library/unique-ptr-class.md +++ b/docs/standard-library/unique-ptr-class.md @@ -1,11 +1,13 @@ --- description: "Learn more about: unique_ptr Class" title: "unique_ptr Class" -ms.date: "11/04/2016" +ms.date: 06/20/2022 f1_keywords: ["memory/std::unique_ptr", "memory/std::unique_ptr::deleter_type", "memory/std::unique_ptr::element_type", "memory/std::unique_ptr::pointer", "memory/std::unique_ptr::get", "memory/std::unique_ptr::get_deleter", "memory/std::unique_ptr::release", "memory/std::unique_ptr::reset", "memory/std::unique_ptr::swap"] helpviewer_keywords: ["std::unique_ptr [C++]", "std::unique_ptr [C++], deleter_type", "std::unique_ptr [C++], element_type", "std::unique_ptr [C++], pointer", "std::unique_ptr [C++], get", "std::unique_ptr [C++], get_deleter", "std::unique_ptr [C++], release", "std::unique_ptr [C++], reset", "std::unique_ptr [C++], swap"] ms.assetid: acdf046b-831e-4a4a-83aa-6d4ee467db9a +ms.custom: devdivchpfy22 --- + # `unique_ptr` Class Stores a pointer to an owned object or array. The object/array is owned by no other `unique_ptr`. The object/array is destroyed when the `unique_ptr` is destroyed. @@ -96,7 +98,7 @@ Use the [`make_unique`](../standard-library/memory-functions.md#make_unique) hel The resource is freed by calling a stored `deleter` object of type `Del` that knows how resources are allocated for a particular `unique_ptr`. The default `deleter` `default_delete` assumes that the resource pointed to by `ptr` is allocated with **`new`**, and that it can be freed by calling `delete _Ptr`. (A partial specialization `unique_ptr`manages array objects allocated with `new[]`, and has the default `deleter` `default_delete`, specialized to call `delete[] ptr`.) -The stored pointer to an owned resource, `stored_ptr` has type `pointer`. It is `Del::pointer` if defined, and `T *` if not. The stored `deleter` object `stored_deleter` occupies no space in the object if the `deleter` is stateless. Note that `Del` can be a reference type. +The stored pointer to an owned resource, `stored_ptr` has type `pointer`. It's `Del::pointer` if defined, and `T *` if not. The stored `deleter` object `stored_deleter` occupies no space in the object if the `deleter` is stateless. Note that `Del` can be a reference type. ## Members @@ -290,9 +292,9 @@ A pointer to the resource to take ownership of. #### Remarks -Use `reset` to change the stored [`pointer`](#pointer) owned by the `unique_ptr` to *ptr* and then delete the original stored pointer. If the `unique_ptr` was not empty, `reset` invokes the deleter function returned by [`get_deleter`](#get_deleter) on the original stored pointer. +Use `reset` to change the stored [`pointer`](#pointer) owned by the `unique_ptr` to *ptr* and then delete the original stored pointer. If the `unique_ptr` wasn't empty, `reset` invokes the deleter function returned by [`get_deleter`](#get_deleter) on the original stored pointer. -Because `reset` first stores the new pointer *`ptr`*, and then deletes the original stored pointer, it's possible for `reset` to immediately delete *`ptr`* if it is the same as the original stored pointer. +Because `reset` first stores the new pointer *`ptr`*, and then deletes the original stored pointer, it's possible for `reset` to immediately delete *`ptr`* if it's the same as the original stored pointer. ### `swap` diff --git a/docs/standard-library/unordered-map-class.md b/docs/standard-library/unordered-map-class.md index 1fcf633569..6c477c968a 100644 --- a/docs/standard-library/unordered-map-class.md +++ b/docs/standard-library/unordered-map-class.md @@ -1,14 +1,15 @@ --- title: "unordered_map Class" description: "API reference for the C++ Standard Library container class `unordered_map`, which controls a varying-length sequence of elements." -ms.date: "9/9/2020" +ms.date: 06/20/2022 f1_keywords: ["unordered_map/std::unordered_map", "unordered_map/std::unordered_map::allocator_type", "unordered_map/std::unordered_map::const_iterator", "unordered_map/std::unordered_map::const_local_iterator", "unordered_map/std::unordered_map::const_pointer", "unordered_map/std::unordered_map::const_reference", "unordered_map/std::unordered_map::difference_type", "unordered_map/std::unordered_map::hasher", "unordered_map/std::unordered_map::iterator", "unordered_map/std::unordered_map::key_equal", "unordered_map/std::unordered_map::key_type", "unordered_map/std::unordered_map::local_iterator", "unordered_map/std::unordered_map::mapped_type", "unordered_map/std::unordered_map::pointer", "unordered_map/std::unordered_map::reference", "unordered_map/std::unordered_map::size_type", "unordered_map/std::unordered_map::value_type", "unordered_map/std::unordered_map::at", "unordered_map/std::unordered_map::begin", "unordered_map/std::unordered_map::bucket", "unordered_map/std::unordered_map::bucket_count", "unordered_map/std::unordered_map::bucket_size", "unordered_map/std::unordered_map::cbegin", "unordered_map/std::unordered_map::cend", "unordered_map/std::unordered_map::clear", "unordered_map/std::unordered_map::contains", "unordered_map/std::unordered_map::count", "unordered_map/std::unordered_map::emplace", "unordered_map/std::unordered_map::emplace_hint", "unordered_map/std::unordered_map::empty", "unordered_map/std::unordered_map::end", "unordered_map/std::unordered_map::equal_range", "unordered_map/std::unordered_map::erase", "unordered_map/std::unordered_map::find", "unordered_map/std::unordered_map::get_allocator", "unordered_map/std::unordered_map::hash", "unordered_map/std::unordered_map::insert", "unordered_map/std::unordered_map::key_eq", "unordered_map/std::unordered_map::load_factor", "unordered_map/std::unordered_map::max_bucket_count", "unordered_map/std::unordered_map::max_load_factor", "unordered_map/std::unordered_map::max_size", "unordered_map/std::unordered_map::rehash", "unordered_map/std::unordered_map::size", "unordered_map/std::unordered_map::swap", "unordered_map/std::unordered_map::unordered_map", "unordered_map/std::unordered_map::hash_function"] helpviewer_keywords: ["std::unordered_map", "std::unordered_map::allocator_type", "std::unordered_map::const_iterator", "std::unordered_map::const_local_iterator", "std::unordered_map::const_pointer", "std::unordered_map::const_reference", "std::unordered_map::difference_type", "std::unordered_map::hasher", "std::unordered_map::iterator", "std::unordered_map::key_equal", "std::unordered_map::key_type", "std::unordered_map::local_iterator", "std::unordered_map::mapped_type", "std::unordered_map::pointer", "std::unordered_map::reference", "std::unordered_map::size_type", "std::unordered_map::value_type", "std::unordered_map::at", "std::unordered_map::begin", "std::unordered_map::bucket", "std::unordered_map::bucket_count", "std::unordered_map::bucket_size", "std::unordered_map::cbegin", "std::unordered_map::cend", "std::unordered_map::clear", "std::unordered_map::contains", "std::unordered_map::count", "std::unordered_map::emplace", "std::unordered_map::emplace_hint", "std::unordered_map::empty", "std::unordered_map::end", "std::unordered_map::equal_range", "std::unordered_map::erase", "std::unordered_map::find", "std::unordered_map::get_allocator", "std::unordered_map::hash", "std::unordered_map::insert", "std::unordered_map::key_eq", "std::unordered_map::load_factor", "std::unordered_map::max_bucket_count", "std::unordered_map::max_load_factor", "std::unordered_map::max_size", "std::unordered_map::rehash", "std::unordered_map::size", "std::unordered_map::swap", "std::unordered_map::unordered_map", "std::unordered_map::allocator_type", "std::unordered_map::const_iterator", "std::unordered_map::const_local_iterator", "std::unordered_map::const_pointer", "std::unordered_map::const_reference", "std::unordered_map::difference_type", "std::unordered_map::hasher", "std::unordered_map::iterator", "std::unordered_map::key_equal", "std::unordered_map::key_type", "std::unordered_map::local_iterator", "std::unordered_map::mapped_type", "std::unordered_map::pointer", "std::unordered_map::reference", "std::unordered_map::size_type", "std::unordered_map::value_type", "std::unordered_map::at", "std::unordered_map::begin", "std::unordered_map::bucket", "std::unordered_map::bucket_count", "std::unordered_map::bucket_size", "std::unordered_map::cbegin", "std::unordered_map::cend", "std::unordered_map::clear", "std::unordered_map::count", "std::unordered_map::emplace", "std::unordered_map::emplace_hint", "std::unordered_map::empty", "std::unordered_map::end", "std::unordered_map::equal_range", "std::unordered_map::erase", "std::unordered_map::find", "std::unordered_map::get_allocator", "std::unordered_map::hash_function", "std::unordered_map::insert", "std::unordered_map::key_eq", "std::unordered_map::load_factor", "std::unordered_map::max_bucket_count", "std::unordered_map::max_load_factor", "std::unordered_map::max_size", "std::unordered_map::rehash", "std::unordered_map::size", "std::unordered_map::swap"] -ms.assetid: 7cf7cfa1-16e7-461c-a9b2-3b8d8ec24e0d +ms.custom: devdivchpfy22 --- + # `unordered_map` Class -The class template describes an object that controls a varying-length sequence of elements of type `std::pair`. The sequence is weakly ordered by a hash function, which partitions the sequence into an ordered set of subsequences called buckets. Within each bucket a comparison function determines whether any pair of elements has equivalent ordering. Each element stores two objects, a sort key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that can be independent of the number of elements in the sequence (constant time), at least when all buckets are of roughly equal length. In the worst case, when all of the elements are in one bucket, the number of operations is proportional to the number of elements in the sequence (linear time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +The class template describes an object that controls a varying-length sequence of elements of type `std::pair`. The sequence is weakly ordered by a hash function, which partitions the sequence into an ordered set of subsequences called buckets. Within each bucket, a comparison function determines whether any pair of elements has equivalent ordering. Each element stores two objects, a sort key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with operations that can be independent of the number of elements in the sequence (constant time), at least when all buckets are of roughly equal length. In the worst case, when all of the elements are in one bucket, the number of operations is proportional to the number of elements in the sequence (linear time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. ## Syntax @@ -70,7 +71,7 @@ The allocator class. |[`cend`](#cend)|Designates the end of the controlled sequence.| |[`clear`](#clear)|Removes all elements.| |[`count`](#count)|Finds the number of elements matching a specified key.| -|[`contains`](#contains)C++20|Check if there is an element with the specified key in the `unordered_map`.| +|[`contains`](#contains)C++20|Check if there's an element with the specified key in the `unordered_map`.| |[`emplace`](#emplace)|Adds an element constructed in place.| |[`emplace_hint`](#emplace_hint)|Adds an element constructed in place, with hint.| |[`empty`](#empty)|Tests whether no elements are present.| @@ -98,13 +99,13 @@ The allocator class. ## Remarks -The object orders the sequence it controls by calling two stored objects, a comparison function object of type [`unordered_map::key_equal`](#key_equal) and a hash function object of type [`unordered_map::hasher`](#hasher). You access the first stored object by calling the member function [`unordered_map::key_eq`](#key_eq)`()`; and you access the second stored object by calling the member function [`unordered_map::hash_function`](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [`unordered_multimap` Class](../standard-library/unordered-multimap-class.md), an object of type `unordered_map` ensures that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys are unique.) +The object orders the sequence it controls by calling two stored objects, a comparison function object of type [`unordered_map::key_equal`](#key_equal) and a hash function object of type [`unordered_map::hasher`](#hasher). You access the first stored object by calling the member function [`unordered_map::key_eq`](#key_eq)`()`; and you access the second stored object by calling the member function [`unordered_map::hash_function`](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [`unordered_multimap`](../standard-library/unordered-multimap-class.md), an object of type `unordered_map` ensures that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys are unique.) The object also stores a maximum load factor, which specifies the maximum desired average number of elements per bucket. If inserting an element causes [`unordered_map::load_factor`](#load_factor)`()` to exceed the maximum load factor, the container increases the number of buckets and rebuilds the hash table as needed. -The actual order of elements in the controlled sequence depends on the hash function, the comparison function, the order of insertion, the maximum load factor, and the current number of buckets. You cannot in general predict the order of elements in the controlled sequence. You can always be assured, however, that any subset of elements that have equivalent ordering are adjacent in the controlled sequence. +The actual order of elements in the controlled sequence depends on the hash function, the comparison function, the order of insertion, the maximum load factor, and the current number of buckets. You can't in general predict the order of elements in the controlled sequence. You can always be assured, however, that any subset of elements that have equivalent ordering are adjacent in the controlled sequence. -The object allocates and frees storage for the sequence it controls through a stored allocator object of type [`unordered_map::allocator_type`](#allocator_type). Such an allocator object must have the same external interface as an object of type `allocator`. Note that the stored allocator object is not copied when the container object is assigned. +The object allocates and frees storage for the sequence it controls through a stored allocator object of type [`unordered_map::allocator_type`](#allocator_type). Such an allocator object must have the same external interface as an object of type `allocator`. The stored allocator object isn't copied when the container object is assigned. ## Requirements @@ -170,7 +171,7 @@ A reference to the data value of the element found. ### Remarks -If the argument key value is not found, then the function throws an object of class `out_of_range`. +If the argument key value isn't found, then the function throws an object of class `out_of_range`. ### Example @@ -419,7 +420,7 @@ The bucket number. ### Remarks -The member functions returns the size of bucket number *`nbucket`*. +The member functions return the size of bucket number *`nbucket`*. ### Example @@ -474,9 +475,9 @@ A **`const`** forward-access iterator that points at the first element of the ra ### Remarks -With the return value of `cbegin`, the elements in the range cannot be modified. +With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -502,7 +503,7 @@ A **`const`** forward-access iterator that points just beyond the end of the ran `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -511,7 +512,7 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -The value returned by `cend` should not be dereferenced. +The value returned by `cend` shouldn't be dereferenced. ## `unordered_map::clear` @@ -590,7 +591,7 @@ typedef T1 const_iterator; ### Remarks -The type describes an object that can serve as a constant forward iterator for the controlled sequence. It is described here as a synonym for the implementation-defined type `T1`. +The type describes an object that can serve as a constant forward iterator for the controlled sequence. It's described here as a synonym for the implementation-defined type `T1`. ### Example @@ -633,7 +634,7 @@ typedef T5 const_local_iterator; ### Remarks -The type describes an object that can serve as a constant forward iterator for a bucket. It is described here as a synonym for the implementation-defined type `T5`. +The type describes an object that can serve as a constant forward iterator for a bucket. It's described here as a synonym for the implementation-defined type `T5`. ### Example @@ -765,7 +766,7 @@ int main() ## `unordered_map::contains` -Checks if there is an element in the `unordered_map` with the specified key. +Checks if there's an element in the `unordered_map` with the specified key. Introduced in C++20. ```cpp @@ -880,7 +881,7 @@ typedef T3 difference_type; ### Remarks -The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It is described here as a synonym for the implementation-defined type `T3`. +The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It's described here as a synonym for the implementation-defined type `T3`. ### Example @@ -953,7 +954,7 @@ To access the iterator component of a pair `pr` returned by this member function No iterators or references are invalidated by this function. -During the insertion, if an exception is thrown but does not occur in the container's hash function, the container is not modified. If the exception is thrown in the hash function, the result is undefined. +During the insertion, if an exception is thrown but doesn't occur in the container's hash function, the container isn't modified. If the exception is thrown in the hash function, the result is undefined. For a code example, see [`map::emplace`](../standard-library/map-class.md#emplace). @@ -984,7 +985,7 @@ If the insertion failed because the element already exists, returns an iterator No references are invalidated by this function. -During the insertion, if an exception is thrown but does not occur in the container's hash function, the container is not modified. If the exception is thrown in the hash function, the result is undefined. +During the insertion, if an exception is thrown but doesn't occur in the container's hash function, the container isn't modified. If the exception is thrown in the hash function, the result is undefined. The [`value_type`](../standard-library/map-class.md#value_type) of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element. @@ -1418,13 +1419,13 @@ The single-element-with-hint member functions, (3) and (4), return an iterator t No iterators, pointers, or references are invalidated by this function. -During the insertion of just one element, if an exception is thrown but does not occur in the container's hash function, the container's state is not modified. If the exception is thrown in the hash function, the result is undefined. During the insertion of multiple elements, if an exception is thrown, the container is left in an unspecified but valid state. +During the insertion of just one element, if an exception is thrown but doesn't occur in the container's hash function, the container's state isn't modified. If the exception is thrown in the hash function, the result is undefined. During the insertion of multiple elements, if an exception is thrown, the container is left in an unspecified but valid state. To access the iterator component of a `pair` `pr` that's returned by the single-element member functions, use `pr.first`; to dereference the iterator within the returned pair, use `*pr.first`, giving you an element. To access the **`bool`** component, use `pr.second`. For an example, see the sample code later in this article. The [`value_type`](../standard-library/map-class.md#value_type) of a container is a typedef that belongs to the container, and for map, `map::value_type` is `pair`. The value of an element is an ordered pair in which the first component is equal to the key value and the second component is equal to the data value of the element. -The range member function (5) inserts the sequence of element values into an unordered_map that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, `Last` does not get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `m.insert(v.begin(), v.end());` attempts to insert all elements of `v` into `m`. Only elements that have unique values in the range are inserted; duplicates are ignored. To observe which elements are rejected, use the single-element versions of `insert`. +The range member function (5) inserts the sequence of element values into an unordered_map that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, `Last` doesn't get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `m.insert(v.begin(), v.end());` attempts to insert all elements of `v` into `m`. Only elements that have unique values in the range are inserted; duplicates are ignored. To observe which elements are rejected, use the single-element versions of `insert`. The initializer list member function (6) uses an [`initializer_list`](../standard-library/initializer-list.md) to copy elements into the unordered_map. @@ -1442,7 +1443,7 @@ typedef T0 iterator; ### Remarks -The type describes an object that can serve as a forward iterator for the controlled sequence. It is described here as a synonym for the implementation-defined type `T0`. +The type describes an object that can serve as a forward iterator for the controlled sequence. It's described here as a synonym for the implementation-defined type `T0`. ### Example @@ -1706,7 +1707,7 @@ typedef T4 local_iterator; ### Remarks -The type describes an object that can serve as a forward iterator for a bucket. It is described here as a synonym for the implementation-defined type `T4`. +The type describes an object that can serve as a forward iterator for a bucket. It's described here as a synonym for the implementation-defined type `T4`. ### Example @@ -2034,13 +2035,13 @@ A reference to the data value of the inserted element. ### Remarks -If the argument key value is not found, then it is inserted along with the default value of the data type. +If the argument key value isn't found, then it's inserted along with the default value of the data type. `operator[]` may be used to insert elements into a map *`m`* using *`m[Key] = DataValue;`* where *`DataValue`* is the value of the `mapped_type` of the element with a key value of *`Key`*. The member function determines the iterator `where` as the return value of `unordered_map::insert(unordered_map::value_type(keyval, Ty())`. For more information, see [`unordered_map::insert`](#insert) and [`unordered_map::value_type`](#value_type). (It inserts an element with the specified key if no such element exists.) It then returns a reference to `(*where).second`. -When using `operator[]` to insert elements, the returned reference does not indicate whether an insertion is changing a pre-existing element or creating a new one. The member functions [`find`](../standard-library/map-class.md#find) and [`insert`](../standard-library/map-class.md#insert) can be used to determine whether an element with a specified key is already present before an insertion. +When using `operator[]` to insert elements, the returned reference doesn't indicate whether an insertion is changing a pre-existing element or creating a new one. The member functions [`find`](../standard-library/map-class.md#find) and [`insert`](../standard-library/map-class.md#insert) can be used to determine whether an element with a specified key is already present before an insertion. ### Example @@ -2404,7 +2405,7 @@ typedef T2 size_type; ### Remarks -The unsigned integer type describes an object that can represent the length of any controlled sequence. It is described here as a synonym for the implementation-defined type `T2`. +The unsigned integer type describes an object that can represent the length of any controlled sequence. It's described here as a synonym for the implementation-defined type `T2`. ### Example @@ -2445,7 +2446,7 @@ The container to swap with. ### Remarks -The member function swaps the controlled sequences between **`*this`** and *`right`*. If `unordered_map::get_allocator() == right.get_allocator()`, see [`unordered_map::get_allocator`](#get_allocator), it does so in constant time, it throws an exception only as a result of copying the stored traits object of type `Tr`, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. +The member function swaps the controlled sequences between **`*this`** and *`right`*. If `unordered_map::get_allocator() == right.get_allocator()`, see [`unordered_map::get_allocator`](#get_allocator), it does so in constant time, it throws an exception only as a result of copying the stored traits object of type `Tr`, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs element assignments and constructor calls proportional to the number of elements in the two controlled sequences. ### Example @@ -2579,13 +2580,13 @@ The first constructor specifies a copy of the sequence controlled by `right`. Th All constructors also initialize several stored values. For the copy constructor, the values are obtained from *`Right`*. Otherwise: -the minimum number of buckets is the argument *`Bucket_count`*, if present; otherwise it is a default value described here as the implementation-defined value `N0`. +the minimum number of buckets is the argument *`Bucket_count`*, if present; otherwise it's a default value described here as the implementation-defined value `N0`. -the hash function object is the argument *`Hash`*, if present; otherwise it is `Hash()`. +the hash function object is the argument *`Hash`*, if present; otherwise it's `Hash()`. -The comparison function object is the argument *`Comp`*, if present; otherwise it is `Pred()`. +The comparison function object is the argument *`Comp`*, if present; otherwise it's `Pred()`. -The allocator object is the argument *`Al`*, if present; otherwise, it is `Alloc()`. +The allocator object is the argument *`Al`*, if present; otherwise, it's `Alloc()`. ### Example @@ -2779,4 +2780,4 @@ int main() ## See also [``](../standard-library/unordered-map.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ +[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/unordered-map-functions.md b/docs/standard-library/unordered-map-functions.md index 36f731bacf..20e3941dff 100644 --- a/docs/standard-library/unordered-map-functions.md +++ b/docs/standard-library/unordered-map-functions.md @@ -1,15 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["unordered_map/std::swap", "unordered_map/std::swap (unordered_map)", "unordered_map/std::swap (unordered_multimap)"] -ms.assetid: cf2e4115-f205-4a0e-90be-a143ffcc1f44 helpviewer_keywords: ["std::swap (unordered_map/multimap)"] --- # `` functions -[swap (unordered_map)](#swap) -[swap (unordered_multimap)](#swap_function_multimap) +The `` header provides the following functions: ## swap (unordered_map) diff --git a/docs/standard-library/unordered-map-operators.md b/docs/standard-library/unordered-map-operators.md index 1e4e87c66d..5913612c65 100644 --- a/docs/standard-library/unordered-map-operators.md +++ b/docs/standard-library/unordered-map-operators.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["unordered_map/std::operator!=", "unordered_map/std::operator=="] -ms.assetid: 9d5add0b-84bd-4a79-bd82-3f58b55145ed --- # `` operators -[unordered_map::operator!=](#op_neq)\ -[unordered_map::operator==](#op_eq_eq)\ -[unordered_multimap::operator!=](#op_neq_multimap)\ -[unordered_multimap::operator==](#op_eq_eq_multimap) +The `` header provides the following operators: ## operator!= diff --git a/docs/standard-library/unordered-multimap-class.md b/docs/standard-library/unordered-multimap-class.md index 0f61a2cac0..aa702c0206 100644 --- a/docs/standard-library/unordered-multimap-class.md +++ b/docs/standard-library/unordered-multimap-class.md @@ -1,13 +1,12 @@ --- title: "unordered_multimap Class" description: "API overview for the C++ Standard Library container class `unordered_multimap`." -ms.date: "9/9/2020" +ms.date: 9/9/2020 f1_keywords: ["unordered_map/std::unordered_multimap", "unordered_map/std::unordered_multimap::allocator_type", "unordered_map/std::unordered_multimap::const_iterator", "unordered_map/std::unordered_multimap::const_local_iterator", "unordered_map/std::unordered_multimap::const_pointer", "unordered_map/std::unordered_multimap::const_reference", "unordered_map/std::unordered_multimap::difference_type", "unordered_map/std::unordered_multimap::hasher", "unordered_map/std::unordered_multimap::iterator", "unordered_map/std::unordered_multimap::key_equal", "unordered_map/std::unordered_multimap::key_type", "unordered_map/std::unordered_multimap::local_iterator", "unordered_map/std::unordered_multimap::mapped_type", "unordered_map/std::unordered_multimap::pointer", "unordered_map/std::unordered_multimap::reference", "unordered_map/std::unordered_multimap::size_type", "unordered_map/std::unordered_multimap::value_type", "unordered_map/std::unordered_multimap::begin", "unordered_map/std::unordered_multimap::bucket", "unordered_map/std::unordered_multimap::bucket_count", "unordered_map/std::unordered_multimap::bucket_size", "unordered_map/std::unordered_multimap::cbegin", "unordered_map/std::unordered_multimap::cend", "unordered_map/std::unordered_multimap::clear", "unordered_map/std::unordered_multimap::contains", "unordered_map/std::unordered_multimap::count", "unordered_map/std::unordered_multimap::emplace", "unordered_map/std::unordered_multimap::emplace_hint", "unordered_map/std::unordered_multimap::empty", "unordered_map/std::unordered_multimap::end", "unordered_map/std::unordered_multimap::equal_range", "unordered_map/std::unordered_multimap::erase", "unordered_map/std::unordered_multimap::find", "unordered_map/std::unordered_multimap::get_allocator", "unordered_map/std::unordered_multimap::hash", "unordered_map/std::unordered_multimap::insert", "unordered_map/std::unordered_multimap::key_eq", "unordered_map/std::unordered_multimap::load_factor", "unordered_map/std::unordered_multimap::max_bucket_count", "unordered_map/std::unordered_multimap::max_load_factor", "unordered_map/std::unordered_multimap::max_size", "unordered_map/std::unordered_multimap::rehash", "unordered_map/std::unordered_multimap::size", "unordered_map/std::unordered_multimap::swap", "unordered_map/std::unordered_multimap::unordered_multimap", "unordered_map/std::unordered_multimap::operator=", "unordered_map/std::unordered_multimap::hash_function"] helpviewer_keywords: ["std::unordered_multimap", "std::unordered_multimap::allocator_type", "std::unordered_multimap::const_iterator", "std::unordered_multimap::const_local_iterator", "std::unordered_multimap::const_pointer", "std::unordered_multimap::const_reference", "std::unordered_multimap::difference_type", "std::unordered_multimap::hasher", "std::unordered_multimap::iterator", "std::unordered_multimap::key_equal", "std::unordered_multimap::key_type", "std::unordered_multimap::local_iterator", "std::unordered_multimap::mapped_type", "std::unordered_multimap::pointer", "std::unordered_multimap::reference", "std::unordered_multimap::size_type", "std::unordered_multimap::value_type", "std::unordered_multimap::begin", "std::unordered_multimap::bucket", "std::unordered_multimap::bucket_count", "std::unordered_multimap::bucket_size", "std::unordered_multimap::cbegin", "std::unordered_multimap::cend", "std::unordered_multimap::clear", "std::unordered_multimap::contains", "std::unordered_multimap::count", "std::unordered_multimap::emplace", "std::unordered_multimap::emplace_hint", "std::unordered_multimap::empty", "std::unordered_multimap::end", "std::unordered_multimap::equal_range", "std::unordered_multimap::erase", "std::unordered_multimap::find", "std::unordered_multimap::get_allocator", "std::unordered_multimap::hash", "std::unordered_multimap::insert", "std::unordered_multimap::key_eq", "std::unordered_multimap::load_factor", "std::unordered_multimap::max_bucket_count", "std::unordered_multimap::max_load_factor", "std::unordered_multimap::max_size", "std::unordered_multimap::rehash", "std::unordered_multimap::size", "std::unordered_multimap::swap", "std::unordered_multimap::unordered_multimap", "std::unordered_multimap::operator=", "std::unordered_multimap::allocator_type", "std::unordered_multimap::const_iterator", "std::unordered_multimap::const_local_iterator", "std::unordered_multimap::const_pointer", "std::unordered_multimap::const_reference", "std::unordered_multimap::difference_type", "std::unordered_multimap::hasher", "std::unordered_multimap::iterator", "std::unordered_multimap::key_equal", "std::unordered_multimap::key_type", "std::unordered_multimap::local_iterator", "std::unordered_multimap::mapped_type", "std::unordered_multimap::pointer", "std::unordered_multimap::reference", "std::unordered_multimap::size_type", "std::unordered_multimap::value_type", "std::unordered_multimap::begin", "std::unordered_multimap::bucket", "std::unordered_multimap::bucket_count", "std::unordered_multimap::bucket_size", "std::unordered_multimap::cbegin", "std::unordered_multimap::cend", "std::unordered_multimap::clear", "std::unordered_multimap::count", "std::unordered_multimap::emplace", "std::unordered_multimap::emplace_hint", "std::unordered_multimap::empty", "std::unordered_multimap::end", "std::unordered_multimap::equal_range", "std::unordered_multimap::erase", "std::unordered_multimap::find", "std::unordered_multimap::get_allocator", "std::unordered_multimap::hash_function", "std::unordered_multimap::insert", "std::unordered_multimap::key_eq", "std::unordered_multimap::load_factor", "std::unordered_multimap::max_bucket_count", "std::unordered_multimap::max_load_factor", "std::unordered_multimap::max_size", "std::unordered_multimap::rehash", "std::unordered_multimap::size", "std::unordered_multimap::swap"] -ms.assetid: 4baead6c-5870-4b85-940f-a47d6b891c27 --- # unordered_multimap Class @@ -99,7 +98,7 @@ The allocator class. ## Remarks -The object orders the sequence it controls by calling two stored objects, a comparison function object of type [unordered_multimap::key_equal](#key_equal) and a hash function object of type [unordered_multimap::hasher](#hasher). You access the first stored object by calling the member function [unordered_multimap::key_eq](#key_eq)`()`; and you access the second stored object by calling the member function [unordered_multimap::hash_function](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [unordered_map Class](../standard-library/unordered-map-class.md), an object of type `unordered_multimap` does not ensure that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys need not be unique.) +The object orders the sequence it controls by calling two stored objects, a comparison function object of type [unordered_multimap::key_equal](#key_equal) and a hash function object of type [unordered_multimap::hasher](#hasher). You access the first stored object by calling the member function [unordered_multimap::key_eq](#key_eq)`()`; and you access the second stored object by calling the member function [unordered_multimap::hash_function](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [`unordered_map`](../standard-library/unordered-map-class.md), an object of type `unordered_multimap` does not ensure that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys need not be unique.) The object also stores a maximum load factor, which specifies the maximum desired average number of elements per bucket. If inserting an element causes [unordered_multimap::load_factor](#load_factor)`()` to exceed the maximum load factor, the container increases the number of buckets and rebuilds the hash table as needed. diff --git a/docs/standard-library/unordered-multiset-class.md b/docs/standard-library/unordered-multiset-class.md index 1a08ac38ec..711f79b9ed 100644 --- a/docs/standard-library/unordered-multiset-class.md +++ b/docs/standard-library/unordered-multiset-class.md @@ -1,10 +1,9 @@ --- title: "unordered_multiset Class" description: "API reference for the C++ Standard Library container class `unordered_multiset`, which describes an object used for the storage and retrieval of data from a collection in which the values of the elements contained need not be unique and in which they serve as the key values. The data isn't automatically ordered." -ms.date: "9/10/2020" +ms.date: 9/10/2020 f1_keywords: ["unordered_set/std::unordered_multiset", "unordered_set/std::unordered_multiset::allocator_type", "unordered_set/std::unordered_multiset::const_iterator", "unordered_set/std::unordered_multiset::const_local_iterator", "unordered_set/std::unordered_multiset::const_pointer", "unordered_set/std::unordered_multiset::const_reference", "unordered_set/std::unordered_multiset::difference_type", "unordered_set/std::unordered_multiset::hasher", "unordered_set/std::unordered_multiset::iterator", "unordered_set/std::unordered_multiset::key_equal", "unordered_set/std::unordered_multiset::key_type", "unordered_set/std::unordered_multiset::local_iterator", "unordered_set/std::unordered_multiset::pointer", "unordered_set/std::unordered_multiset::reference", "unordered_set/std::unordered_multiset::size_type", "unordered_set/std::unordered_multiset::value_type", "unordered_set/std::unordered_multiset::begin", "unordered_set/std::unordered_multiset::bucket", "unordered_set/std::unordered_multiset::bucket_count", "unordered_set/std::unordered_multiset::bucket_size", "unordered_set/std::unordered_multiset::cbegin", "unordered_set/std::unordered_multiset::cend", "unordered_set/std::unordered_multiset::clear", "unordered_set/std::unordered_multiset::contains", "unordered_set/std::unordered_multiset::count", "unordered_set/std::unordered_multiset::emplace", "unordered_set/std::unordered_multiset::emplace_hint", "unordered_set/std::unordered_multiset::empty", "unordered_set/std::unordered_multiset::end", "unordered_set/std::unordered_multiset::equal_range", "unordered_set/std::unordered_multiset::erase", "unordered_set/std::unordered_multiset::find", "unordered_set/std::unordered_multiset::get_allocator", "unordered_set/std::unordered_multiset::hash", "unordered_set/std::unordered_multiset::insert", "unordered_set/std::unordered_multiset::key_eq", "unordered_set/std::unordered_multiset::load_factor", "unordered_set/std::unordered_multiset::max_bucket_count", "unordered_set/std::unordered_multiset::max_load_factor", "unordered_set/std::unordered_multiset::max_size", "unordered_set/std::unordered_multiset::rehash", "unordered_set/std::unordered_multiset::size", "unordered_set/std::unordered_multiset::swap", "unordered_set/std::unordered_multiset::unordered_multiset", "unordered_set/std::unordered_multiset::operator=", "unordered_set/std::unordered_multiset::hash_function"] helpviewer_keywords: ["std::unordered_multiset", "std::unordered_multiset::allocator_type", "std::unordered_multiset::const_iterator", "std::unordered_multiset::const_local_iterator", "std::unordered_multiset::const_pointer", "std::unordered_multiset::const_reference", "std::unordered_multiset::difference_type", "std::unordered_multiset::hasher", "std::unordered_multiset::iterator", "std::unordered_multiset::key_equal", "std::unordered_multiset::key_type", "std::unordered_multiset::local_iterator", "std::unordered_multiset::pointer", "std::unordered_multiset::reference", "std::unordered_multiset::size_type", "std::unordered_multiset::value_type", "std::unordered_multiset::begin", "std::unordered_multiset::bucket", "std::unordered_multiset::bucket_count", "std::unordered_multiset::bucket_size", "std::unordered_multiset::cbegin", "std::unordered_multiset::cend", "std::unordered_multiset::clear", "std::unordered_multiset::contains", "std::unordered_multiset::count", "std::unordered_multiset::emplace", "std::unordered_multiset::emplace_hint", "std::unordered_multiset::empty", "std::unordered_multiset::end", "std::unordered_multiset::equal_range", "std::unordered_multiset::erase", "std::unordered_multiset::find", "std::unordered_multiset::get_allocator", "std::unordered_multiset::hash", "std::unordered_multiset::insert", "std::unordered_multiset::key_eq", "std::unordered_multiset::load_factor", "std::unordered_multiset::max_bucket_count", "std::unordered_multiset::max_load_factor", "std::unordered_multiset::max_size", "std::unordered_multiset::rehash", "std::unordered_multiset::size", "std::unordered_multiset::swap", "std::unordered_multiset::unordered_multiset", "std::unordered_multiset::operator=", "std::unordered_multiset::allocator_type", "std::unordered_multiset::const_iterator", "std::unordered_multiset::const_local_iterator", "std::unordered_multiset::const_pointer", "std::unordered_multiset::const_reference", "std::unordered_multiset::difference_type", "std::unordered_multiset::hasher", "std::unordered_multiset::iterator", "std::unordered_multiset::key_equal", "std::unordered_multiset::key_type", "std::unordered_multiset::local_iterator", "std::unordered_multiset::pointer", "std::unordered_multiset::reference", "std::unordered_multiset::size_type", "std::unordered_multiset::value_type", "std::unordered_multiset::begin", "std::unordered_multiset::bucket", "std::unordered_multiset::bucket_count", "std::unordered_multiset::bucket_size", "std::unordered_multiset::cbegin", "std::unordered_multiset::cend", "std::unordered_multiset::clear", "std::unordered_multiset::count", "std::unordered_multiset::emplace", "std::unordered_multiset::emplace_hint", "std::unordered_multiset::empty", "std::unordered_multiset::end", "std::unordered_multiset::equal_range", "std::unordered_multiset::erase", "std::unordered_multiset::find", "std::unordered_multiset::get_allocator", "std::unordered_multiset::hash_function", "std::unordered_multiset::insert", "std::unordered_multiset::key_eq", "std::unordered_multiset::load_factor", "std::unordered_multiset::max_bucket_count", "std::unordered_multiset::max_load_factor", "std::unordered_multiset::max_size", "std::unordered_multiset::rehash", "std::unordered_multiset::size", "std::unordered_multiset::swap"] -ms.assetid: 70c8dfc5-492a-4af2-84f5-1aa9cb04b71c --- # unordered_multiset Class @@ -91,7 +90,7 @@ The allocator class. ## Remarks -The object orders the sequence it controls by calling two stored objects, a comparison function object of type [unordered_multiset::key_equal](#key_equal) and a hash function object of type [unordered_multiset::hasher](#hasher). You access the first stored object by calling the member function [unordered_multiset::key_eq](#key_eq)`()`; and you access the second stored object by calling the member function [unordered_multiset::hash_function](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [unordered_set Class](../standard-library/unordered-set-class.md), an object of type `unordered_multiset` does not ensure that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys need not be unique.) +The object orders the sequence it controls by calling two stored objects, a comparison function object of type [unordered_multiset::key_equal](#key_equal) and a hash function object of type [unordered_multiset::hasher](#hasher). You access the first stored object by calling the member function [unordered_multiset::key_eq](#key_eq)`()`; and you access the second stored object by calling the member function [unordered_multiset::hash_function](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [`unordered_set`](../standard-library/unordered-set-class.md), an object of type `unordered_multiset` does not ensure that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys need not be unique.) The object also stores a maximum load factor, which specifies the maximum desired average number of elements per bucket. If inserting an element causes [unordered_multiset::load_factor](#load_factor)`()` to exceed the maximum load factor, the container increases the number of buckets and rebuilds the hash table as needed. diff --git a/docs/standard-library/unordered-set-class.md b/docs/standard-library/unordered-set-class.md index 90b38ea7b0..1085adc704 100644 --- a/docs/standard-library/unordered-set-class.md +++ b/docs/standard-library/unordered-set-class.md @@ -1,14 +1,13 @@ --- title: "unordered_set Class" description: "API reference for the C++ Standard Library container class `unordered_set`, which is used to store and retrieve data from an unordered collection." -ms.date: "9/9/2020" +ms.date: 9/9/2020 f1_keywords: ["unordered_set/std::unordered_set", "unordered_set/std::unordered_set::allocator_type", "unordered_set/std::unordered_set::const_iterator", "unordered_set/std::unordered_set::const_local_iterator", "unordered_set/std::unordered_set::const_pointer", "unordered_set/std::unordered_set::const_reference", "unordered_set/std::unordered_set::difference_type", "unordered_set/std::unordered_set::hasher", "unordered_set/std::unordered_set::iterator", "unordered_set/std::unordered_set::key_equal", "unordered_set/std::unordered_set::key_type", "unordered_set/std::unordered_set::local_iterator", "unordered_set/std::unordered_set::pointer", "unordered_set/std::unordered_set::reference", "unordered_set/std::unordered_set::size_type", "unordered_set/std::unordered_set::value_type", "unordered_set/std::unordered_set::begin", "unordered_set/std::unordered_set::bucket", "unordered_set/std::unordered_set::bucket_count", "unordered_set/std::unordered_set::bucket_size", "unordered_set/std::unordered_set::cbegin", "unordered_set/std::unordered_set::cend", "unordered_set/std::unordered_set::clear", "unordered_set/std::unordered_set::count", "unordered_set/std::unordered_set::contains", "unordered_set/std::unordered_set::emplace", "unordered_set/std::unordered_set::emplace_hint", "unordered_set/std::unordered_set::empty", "unordered_set/std::unordered_set::end", "unordered_set/std::unordered_set::equal_range", "unordered_set/std::unordered_set::erase", "unordered_set/std::unordered_set::find", "unordered_set/std::unordered_set::get_allocator", "unordered_set/std::unordered_set::hash", "unordered_set/std::unordered_set::insert", "unordered_set/std::unordered_set::key_eq", "unordered_set/std::unordered_set::load_factor", "unordered_set/std::unordered_set::max_bucket_count", "unordered_set/std::unordered_set::max_load_factor", "unordered_set/std::unordered_set::max_size", "unordered_set/std::unordered_set::rehash", "unordered_set/std::unordered_set::size", "unordered_set/std::unordered_set::swap", "unordered_set/std::unordered_set::unordered_set", "unordered_set/std::unordered_set::operator=", "unordered_set/std::unordered_set::hash_function"] helpviewer_keywords: ["std::unordered_set", "std::unordered_set::allocator_type", "std::unordered_set::const_iterator", "std::unordered_set::const_local_iterator", "std::unordered_set::const_pointer", "std::unordered_set::const_reference", "std::unordered_set::difference_type", "std::unordered_set::hasher", "std::unordered_set::iterator", "std::unordered_set::key_equal", "std::unordered_set::key_type", "std::unordered_set::local_iterator", "std::unordered_set::pointer", "std::unordered_set::reference", "std::unordered_set::size_type", "std::unordered_set::value_type", "std::unordered_set::begin", "std::unordered_set::bucket", "std::unordered_set::bucket_count", "std::unordered_set::bucket_size", "std::unordered_set::cbegin", "std::unordered_set::cend", "std::unordered_set::clear", "std::unordered_set::contains", "std::unordered_set::count", "std::unordered_set::emplace", "std::unordered_set::emplace_hint", "std::unordered_set::empty", "std::unordered_set::end", "std::unordered_set::equal_range", "std::unordered_set::erase", "std::unordered_set::find", "std::unordered_set::get_allocator", "std::unordered_set::hash", "std::unordered_set::insert", "std::unordered_set::key_eq", "std::unordered_set::load_factor", "std::unordered_set::max_bucket_count", "std::unordered_set::max_load_factor", "std::unordered_set::max_size", "std::unordered_set::rehash", "std::unordered_set::size", "std::unordered_set::swap", "std::unordered_set::unordered_set", "std::unordered_set::operator=", "std::unordered_set::allocator_type", "std::unordered_set::const_iterator", "std::unordered_set::const_local_iterator", "std::unordered_set::const_pointer", "std::unordered_set::const_reference", "std::unordered_set::difference_type", "std::unordered_set::hasher", "std::unordered_set::iterator", "std::unordered_set::key_equal", "std::unordered_set::key_type", "std::unordered_set::local_iterator", "std::unordered_set::pointer", "std::unordered_set::reference", "std::unordered_set::size_type", "std::unordered_set::value_type", "std::unordered_set::begin", "std::unordered_set::bucket", "std::unordered_set::bucket_count", "std::unordered_set::bucket_size", "std::unordered_set::cbegin", "std::unordered_set::cend", "std::unordered_set::clear", "std::unordered_set::count", "std::unordered_set::emplace", "std::unordered_set::emplace_hint", "std::unordered_set::empty", "std::unordered_set::end", "std::unordered_set::equal_range", "std::unordered_set::erase", "std::unordered_set::find", "std::unordered_set::get_allocator", "std::unordered_set::hash_function", "std::unordered_set::insert", "std::unordered_set::key_eq", "std::unordered_set::load_factor", "std::unordered_set::max_bucket_count", "std::unordered_set::max_load_factor", "std::unordered_set::max_size", "std::unordered_set::rehash", "std::unordered_set::size", "std::unordered_set::swap"] -ms.assetid: ac08084e-05a7-48c0-9ae4-d40c529922dd --- -# unordered_set Class +# `unordered_set` Class -The class template describes an object that controls a varying-length sequence of elements of type `const Key`. The sequence is weakly ordered by a hash function, which partitions the sequence into an ordered set of subsequences called buckets. Within each bucket, a comparison function determines whether any pair of elements has equivalent ordering. Each element serves as both a sort key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that can be independent of the number of elements in the sequence (constant time), at least when all buckets are of roughly equal length. In the worst case, when all of the elements are in one bucket, the number of operations is proportional to the number of elements in the sequence (linear time). Inserting an element invalidates no iterators, and removing an element invalidates only those iterators, which point at the removed element. +The class template describes an object that controls a varying-length sequence of elements of type `const Key`. The sequence is weakly ordered by a hash function, which partitions the sequence into an ordered set of subsequences called buckets. Within each bucket, a comparison function determines whether any pair of elements has equivalent ordering. Each element serves as both a sort key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that can be independent of the number of elements in the sequence (constant time), at least when all buckets are of roughly equal length. In the worst case, when all of the elements are in one bucket, the number of operations is proportional to the number of elements in the sequence (linear time). Inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. ## Syntax @@ -23,16 +22,16 @@ class unordered_set; ### Parameters -*Key*\ +*`Key`*\ The key type. -*Hash*\ +*`Hash`*\ The hash function object type. -*Pred*\ +*`Pred`*\ The equality comparison function object type. -*Alloc*\ +*`Alloc`*\ The allocator class. ## Members @@ -41,72 +40,72 @@ The allocator class. |Name|Description| |-|-| -|[allocator_type](#allocator_type)|The type of an allocator for managing storage.| -|[const_iterator](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[const_local_iterator](#const_local_iterator)|The type of a constant bucket iterator for the controlled sequence.| -|[const_pointer](#const_pointer)|The type of a constant pointer to an element.| -|[const_reference](#const_reference)|The type of a constant reference to an element.| -|[difference_type](#difference_type)|The type of a signed distance between two elements.| -|[hasher](#hasher)|The type of the hash function.| -|[iterator](#iterator)|The type of an iterator for the controlled sequence.| -|[key_equal](#key_equal)|The type of the comparison function.| -|[key_type](#key_type)|The type of an ordering key.| -|[local_iterator](#local_iterator)|The type of a bucket iterator for the controlled sequence.| -|[pointer](#pointer)|The type of a pointer to an element.| -|[reference](#reference)|The type of a reference to an element.| -|[size_type](#size_type)|The type of an unsigned distance between two elements.| -|[value_type](#value_type)|The type of an element.| +|[`allocator_type`](#allocator_type)|The type of an allocator for managing storage.| +|[`const_iterator`](#const_iterator)|The type of a constant iterator for the controlled sequence.| +|[`const_local_iterator`](#const_local_iterator)|The type of a constant bucket iterator for the controlled sequence.| +|[`const_pointer`](#const_pointer)|The type of a constant pointer to an element.| +|[`const_reference`](#const_reference)|The type of a constant reference to an element.| +|[`difference_type`](#difference_type)|The type of a signed distance between two elements.| +|[`hasher`](#hasher)|The type of the hash function.| +|[`iterator`](#iterator)|The type of an iterator for the controlled sequence.| +|[`key_equal`](#key_equal)|The type of the comparison function.| +|[`key_type`](#key_type)|The type of an ordering key.| +|[`local_iterator`](#local_iterator)|The type of a bucket iterator for the controlled sequence.| +|[`pointer`](#pointer)|The type of a pointer to an element.| +|[`reference`](#reference)|The type of a reference to an element.| +|[`size_type`](#size_type)|The type of an unsigned distance between two elements.| +|[`value_type`](#value_type)|The type of an element.| ### Functions |Name|Description| |-|-| -|[begin](#begin)|Designates the beginning of the controlled sequence.| -|[bucket](#bucket)|Gets the bucket number for a key value.| -|[bucket_count](#bucket_count)|Gets the number of buckets.| -|[bucket_size](#bucket_size)|Gets the size of a bucket.| -|[cbegin](#cbegin)|Designates the beginning of the controlled sequence.| -|[cend](#cend)|Designates the end of the controlled sequence.| -|[clear](#clear)|Removes all elements.| -|[contains](#contains)C++20|Check if there's an element with the specified key in the `unordered_set`.| -|[count](#count)|Finds the number of elements matching a specified key.| -|[emplace](#emplace)|Adds an element constructed in place.| -|[emplace_hint](#emplace_hint)|Adds an element constructed in place, with hint.| -|[empty](#empty)|Tests whether no elements are present.| -|[end](#end)|Designates the end of the controlled sequence.| -|[equal_range](#equal_range)|Finds range that matches a specified key.| -|[erase](#erase)|Removes elements at specified positions.| -|[find](#find)|Finds an element that matches a specified key.| -|[get_allocator](#get_allocator)|Gets the stored allocator object.| -|[hash_function](#hash)|Gets the stored hash function object.| -|[insert](#insert)|Adds elements.| -|[key_eq](#key_eq)|Gets the stored comparison function object.| -|[load_factor](#load_factor)|Counts the average elements per bucket.| -|[max_bucket_count](#max_bucket_count)|Gets the maximum number of buckets.| -|[max_load_factor](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[max_size](#max_size)|Gets the maximum size of the controlled sequence.| -|[rehash](#rehash)|Rebuilds the hash table.| -|[size](#size)|Counts the number of elements.| -|[swap](#swap)|Swaps the contents of two containers.| -|[unordered_set](#unordered_set)|Constructs a container object.| +|[`begin`](#begin)|Designates the beginning of the controlled sequence.| +|[`bucket`](#bucket)|Gets the bucket number for a key value.| +|[`bucket_count`](#bucket_count)|Gets the number of buckets.| +|[`bucket_size`](#bucket_size)|Gets the size of a bucket.| +|[`cbegin`](#cbegin)|Designates the beginning of the controlled sequence.| +|[`cend`](#cend)|Designates the end of the controlled sequence.| +|[`clear`](#clear)|Removes all elements.| +|[`contains`](#contains)C++20|Check if there's an element with the specified key in the `unordered_set`.| +|[`count`](#count)|Finds the number of elements matching a specified key.| +|[`emplace`](#emplace)|Adds an element constructed in place.| +|[`emplace_hint`](#emplace_hint)|Adds an element constructed in place, with hint.| +|[`empty`](#empty)|Tests whether no elements are present.| +|[`end`](#end)|Designates the end of the controlled sequence.| +|[`equal_range`](#equal_range)|Finds range that matches a specified key.| +|[`erase`](#erase)|Removes elements at specified positions.| +|[`find`](#find)|Finds an element that matches a specified key.| +|[`get_allocator`](#get_allocator)|Gets the stored allocator object.| +|[`hash_function`](#hash)|Gets the stored hash function object.| +|[`insert`](#insert)|Adds elements.| +|[`key_eq`](#key_eq)|Gets the stored comparison function object.| +|[`load_factor`](#load_factor)|Counts the average elements per bucket.| +|[`max_bucket_count`](#max_bucket_count)|Gets the maximum number of buckets.| +|[`max_load_factor`](#max_load_factor)|Gets or sets the maximum elements per bucket.| +|[`max_size`](#max_size)|Gets the maximum size of the controlled sequence.| +|[`rehash`](#rehash)|Rebuilds the hash table.| +|[`size`](#size)|Counts the number of elements.| +|[`swap`](#swap)|Swaps the contents of two containers.| +|[`unordered_set`](#unordered_set)|Constructs a container object.| ### Operators |Name|Description| |-|-| -|[unordered_set::operator=](#op_eq)|Copies a hash table.| +|[`unordered_set::operator=`](#op_eq)|Copies a hash table.| ## Remarks -The object orders the sequence it controls by calling two stored objects, a comparison function object of type [unordered_set::key_equal](#key_equal) and a hash function object of type [unordered_set::hasher](#hasher). You access the first stored object by calling the member function [unordered_set::key_eq](#key_eq)`()`; and you access the second stored object by calling the member function [unordered_set::hash_function](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [unordered_multiset Class](../standard-library/unordered-multiset-class.md), an object of type `unordered_set` ensures that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys are unique.) +The object orders the sequence it controls by calling two stored objects, a comparison function object of type [`unordered_set::key_equal`](#key_equal) and a hash function object of type [`unordered_set::hasher`](#hasher). You access the first stored object by calling the member function [`unordered_set::key_eq`](#key_eq)`()`; and you access the second stored object by calling the member function [`unordered_set::hash_function`](#hash)`()`. Specifically, for all values `X` and `Y` of type `Key`, the call `key_eq()(X, Y)` returns true only if the two argument values have equivalent ordering; the call `hash_function()(keyval)` yields a distribution of values of type `size_t`. Unlike class template [`unordered_multiset`](../standard-library/unordered-multiset-class.md), an object of type `unordered_set` ensures that `key_eq()(X, Y)` is always false for any two elements of the controlled sequence. (Keys are unique.) -The object also stores a maximum load factor, which specifies the maximum desired average number of elements per bucket. If inserting an element causes [unordered_set::load_factor](#load_factor)`()` to exceed the maximum load factor, the container increases the number of buckets and rebuilds the hash table as needed. +The object also stores a maximum load factor, which specifies the maximum desired average number of elements per bucket. If inserting an element causes [`unordered_set::load_factor`](#load_factor)`()` to exceed the maximum load factor, the container increases the number of buckets and rebuilds the hash table as needed. The actual order of elements in the controlled sequence depends on the hash function, the comparison function, the order of insertion, the maximum load factor, and the current number of buckets. You can't in general predict the order of elements in the controlled sequence. You can always be assured, however, that any subset of elements that have equivalent ordering are adjacent in the controlled sequence. -The object allocates and frees storage for the sequence it controls through a stored allocator object of type [unordered_set::allocator_type](#allocator_type). Such an allocator object must have the same external interface as an object of type `allocator`. The stored allocator object isn't copied when the container object is assigned. +The object allocates and frees storage for the sequence it controls through a stored allocator object of type [`unordered_set::allocator_type`](#allocator_type). Such an allocator object must have the same external interface as an object of type `allocator`. The stored allocator object isn't copied when the container object is assigned. -## unordered_set::allocator_type +## `unordered_set::allocator_type` The type of an allocator for managing storage. @@ -144,7 +143,7 @@ int main() al == std::allocator() is true ``` -## begin +## `begin` Designates the beginning of the controlled sequence or a bucket. @@ -160,12 +159,12 @@ const_local_iterator begin(size_type nbucket) const; ### Parameters -*nbucket*\ +*`nbucket`*\ The bucket number. ### Remarks -The first two member functions return a forward iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). The last two member functions return a forward iterator that points at the first element of bucket *nbucket* (or just beyond the end of an empty bucket). +The first two member functions return a forward iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). The last two member functions return a forward iterator that points at the first element of bucket *`nbucket`* (or just beyond the end of an empty bucket). ### Example @@ -223,7 +222,7 @@ int main() [a] ``` -## bucket +## `bucket` Gets the bucket number for a key value. @@ -233,12 +232,12 @@ size_type bucket(const Key& keyval) const; ### Parameters -*keyval*\ +*`keyval`*\ The key value to map. ### Remarks -The member function returns the bucket number currently corresponding to the key value *keyval*. +The member function returns the bucket number currently corresponding to the key value *`keyval`*. ### Example @@ -278,7 +277,7 @@ bucket('a') == 7 bucket_size(7) == 1 ``` -## bucket_count +## `bucket_count` Gets the number of buckets. @@ -363,7 +362,7 @@ max_bucket_count() == 128 max_load_factor() == 0.1 ``` -## bucket_size +## `bucket_size` Gets the size of a bucket @@ -373,12 +372,12 @@ size_type bucket_size(size_type nbucket) const; ### Parameters -*nbucket*\ +*`nbucket`*\ The bucket number. ### Remarks -The member functions returns the size of bucket number *nbucket*. +The member functions returns the size of bucket number *`nbucket`*. ### Example @@ -418,7 +417,7 @@ bucket('a') == 7 bucket_size(7) == 1 ``` -## cbegin +## `cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -434,7 +433,7 @@ A **`const`** forward-access iterator that points at the first element of the ra With the return value of `cbegin`, the elements in the range can't be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -444,7 +443,7 @@ auto i2 = Container.cbegin(); // i2 isContainer::const_iterator ``` -## cend +## `cend` Returns a **`const`** iterator that addresses the location just beyond the last element in a range. @@ -460,7 +459,7 @@ A **`const`** forward-access iterator that points just beyond the end of the ran `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -472,7 +471,7 @@ auto i2 = Container.cend(); The value returned by `cend` shouldn't be dereferenced. -## clear +## `clear` Removes all elements. @@ -482,7 +481,7 @@ void clear(); ### Remarks -The member function calls [unordered_set::erase](#erase)`(` [unordered_set::begin](#begin)`(),` [unordered_set::end](#end)`())`. +The member function calls `unordered_set::erase( unordered_set::begin()`, `unordered_set::end())`. For more information, see [`unordered_set::erase`](#erase), [`unordered_set::begin`](#begin), and [`unordered_set::end`](#end). ### Example @@ -536,7 +535,7 @@ size == 2 empty() == false ``` -## const_iterator +## `const_iterator` The type of a constant iterator for the controlled sequence. @@ -578,7 +577,7 @@ int main() [c] [b] [a] ``` -## const_local_iterator +## `const_local_iterator` The type of a constant bucket iterator for the controlled sequence. @@ -625,7 +624,7 @@ int main() [a] ``` -## const_pointer +## `const_pointer` The type of a constant pointer to an element. @@ -670,7 +669,7 @@ int main() [c] [b] [a] ``` -## const_reference +## `const_reference` The type of a constant reference to an element. @@ -715,7 +714,7 @@ int main() [c] [b] [a] ``` -## contains +## `contains` Checks if there's an element with the specified key in the `unordered_set`. @@ -726,10 +725,10 @@ template bool contains(const K& key) const; ### Parameters -*K*\ +*`K`*\ The type of the key. -*key*\ +*`Key`*\ The element's key value to look for. ### Return Value @@ -766,7 +765,7 @@ true false ``` -## count +## `count` Finds the number of elements matching a specified key. @@ -776,12 +775,12 @@ size_type count(const Key& keyval) const; ### Parameters -*keyval*\ +*`keyval`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the range delimited by [unordered_set::equal_range](#equal_range)`(keyval)`. +The member function returns the number of elements in the range delimited by [`unordered_set::equal_range`](#equal_range)`(keyval)`. ### Example @@ -820,7 +819,7 @@ count('b') == 1 count('C') == 0 ``` -## difference_type +## `difference_type` The type of a signed distance between two elements. @@ -876,7 +875,7 @@ end()-begin() == 3 begin()-end() == -3 ``` -## emplace +## `emplace` Inserts an element constructed in place (no copy or move operations are performed). @@ -889,8 +888,8 @@ Args&&... args); ### Parameters -*args*\ -The arguments forwarded to construct an element to be inserted into the unordered_set unless it already contains an element whose value is equivalently ordered. +*`args`*\ +The arguments forwarded to construct an element to be inserted into the `unordered_set` unless it already contains an element whose value is equivalently ordered. ### Return Value @@ -904,9 +903,9 @@ No iterators or references are invalidated by this function. During the insertion, if an exception is thrown but doesn't occur in the container's hash function, the container isn't modified. If the exception is thrown in the hash function, the result is undefined. -For a code example, see [set::emplace](../standard-library/set-class.md#emplace). +For a code example, see [`set::emplace`](../standard-library/set-class.md#emplace). -## emplace_hint +## `emplace_hint` Inserts an element constructed in place (no copy or move operations are performed), with a placement hint. @@ -919,10 +918,10 @@ Args&&... args); ### Parameters -*args*\ -The arguments forwarded to construct an element to be inserted into the unordered_set unless the unordered_set already contains that element or, more generally, unless it already contains an element whose key is equivalently ordered. +*`args`*\ +The arguments forwarded to construct an element to be inserted into the `unordered_set` unless the `unordered_set` already contains that element or, more generally, unless it already contains an element whose key is equivalently ordered. -*where*\ +*`where`*\ A hint about the place to start searching for the correct point of insertion. ### Return Value @@ -937,9 +936,9 @@ No iterators or references are invalidated by this function. During the insertion, if an exception is thrown but doesn't occur in the container's hash function, the container isn't modified. If the exception is thrown in the hash function, the result is undefined. -For a code example, see [set::emplace_hint](../standard-library/set-class.md#emplace_hint). +For a code example, see [`set::emplace_hint`](../standard-library/set-class.md#emplace_hint). -## empty +## `empty` Tests whether no elements are present. @@ -1003,7 +1002,7 @@ size == 2 empty() == false ``` -## end +## `end` Designates the end of the controlled sequence. @@ -1019,12 +1018,12 @@ const_local_iterator end(size_type nbucket) const; ### Parameters -*nbucket*\ +*`nbucket`*\ The bucket number. ### Remarks -The first two member functions return a forward iterator that points just beyond the end of the sequence. The last two member functions return a forward iterator that points just beyond the end of bucket *nbucket*. +The first two member functions return a forward iterator that points just beyond the end of the sequence. The last two member functions return a forward iterator that points just beyond the end of bucket *`nbucket`*. ### Example @@ -1071,7 +1070,7 @@ int main() [a] ``` -## equal_range +## `equal_range` Finds range that matches a specified key. @@ -1085,12 +1084,12 @@ equal_range(const Key& keyval) const; ### Parameters -*keyval*\ +*`keyval`*\ Key value to search for. ### Remarks -The member function returns a pair of iterators `X` such that`[X.first, X.second)` delimits just those elements of the controlled sequence that have equivalent ordering with *keyval*. If no such elements exist, both iterators are `end()`. +The member function returns a pair of iterators `X` such that`[X.first, X.second)` delimits just those elements of the controlled sequence that have equivalent ordering with *`keyval`*. If no such elements exist, both iterators are `end()`. ### Example @@ -1139,9 +1138,9 @@ equal_range('x'): equal_range('b'): [b] ``` -## erase +## `erase` -Removes an element or a range of elements in a unordered_set from specified positions or removes elements that match a specified key. +Removes an element or a range of elements in a `unordered_set` from specified positions or removes elements that match a specified key. ```cpp iterator erase(const_iterator Where); @@ -1153,29 +1152,29 @@ size_type erase(const key_type& Key); ### Parameters -*Where*\ +*`Where`*\ Position of the element to be removed. -*First*\ +*`First`*\ Position of the first element to be removed. -*Last*\ +*`Last`*\ Position just beyond the last element to be removed. -*Key*\ +*`Key`*\ The key value of the elements to be removed. ### Return Value -For the first two member functions, a bidirectional iterator that designates the first element remaining beyond any elements removed, or an element that is the end of the unordered_set if no such element exists. +For the first two member functions, a bidirectional iterator that designates the first element remaining beyond any elements removed, or an element that is the end of the `unordered_set` if no such element exists. -For the third member function, returns the number of elements that have been removed from the unordered_set. +For the third member function, returns the number of elements that have been removed from the `unordered_set`. ### Remarks For a code example, see [set::erase](../standard-library/set-class.md#erase). -## find +## `find` Finds an element that matches a specified key. @@ -1185,12 +1184,12 @@ const_iterator find(const Key& keyval) const; ### Parameters -*keyval*\ +*`keyval`*\ Key value to search for. ### Remarks -The member function returns [unordered_set::equal_range](#equal_range)`(keyval).first`. +The member function returns [`unordered_set::equal_range`](#equal_range)`(keyval).first`. ### Example @@ -1234,7 +1233,7 @@ find('A') == false find('b') == true: [b] ``` -## get_allocator +## `get_allocator` Gets the stored allocator object. @@ -1272,7 +1271,7 @@ int main() al == std::allocator() is true ``` -## hash_function +## `hash_function` Gets the stored hash function object. @@ -1310,7 +1309,7 @@ hfn('a') == 1630279 hfn('b') == 1647086 ``` -## hasher +## `hasher` The type of the hash function. @@ -1348,9 +1347,9 @@ hfn('a') == 1630279 hfn('b') == 1647086 ``` -## insert +## `insert` -Inserts an element or a range of elements into an unordered_set. +Inserts an element or a range of elements into an `unordered_set`. ```cpp // (1) single element @@ -1377,32 +1376,32 @@ void insert(initializer_list IList); ### Parameters -*Val*\ -The value of an element to be inserted into the unordered_set unless it already contains an element whose key is equivalently ordered. +*`Val`*\ +The value of an element to be inserted into the `unordered_set` unless it already contains an element whose key is equivalently ordered. -*Where*\ +*`Where`*\ The place to start searching for the correct point of insertion. -*ValTy*\ -Template parameter that specifies the argument type that the unordered_set can use to construct an element of [value_type](../standard-library/map-class.md#value_type), and perfect-forwards *Val* as an argument. +*`ValTy`*\ +Template parameter that specifies the argument type that the `unordered_set` can use to construct an element of [`value_type`](../standard-library/map-class.md#value_type), and perfect-forwards *`Val`* as an argument. -*First*\ +*`First`*\ The position of the first element to be copied. -*Last*\ +*`Last`*\ The position just beyond the last element to be copied. -*InputIterator*\ -Template function argument that meets the requirements of an [input iterator](../standard-library/input-iterator-tag-struct.md) that points to elements of a type that can be used to construct [value_type](../standard-library/map-class.md#value_type) objects. +*`InputIterator`*\ +Template function argument that meets the requirements of an [input iterator](../standard-library/input-iterator-tag-struct.md) that points to elements of a type that can be used to construct [`value_type`](../standard-library/map-class.md#value_type) objects. -*IList*\ -The [initializer_list](../standard-library/initializer-list.md) from which to copy the elements. +*`IList`*\ +The [`initializer_list`](../standard-library/initializer-list.md) from which to copy the elements. ### Return Value -The single-element member functions, (1) and (2), return a [pair](../standard-library/pair-structure.md) whose **`bool`** component is true if an insertion was made, and false if the unordered_set already contained an element whose key had an equivalent value in the ordering. The iterator component of the return-value pair points to the newly inserted element if the **`bool`** component is true, or to the existing element if the **`bool`** component is false. +The single-element member functions, (1) and (2), return a [`pair`](../standard-library/pair-structure.md) whose **`bool`** component is true if an insertion was made, and false if the `unordered_set` already contained an element whose key had an equivalent value in the ordering. The iterator component of the return-value pair points to the newly inserted element if the **`bool`** component is `true`, or to the existing element if the **`bool`** component is `false`. -The single-element-with-hint member functions, (3) and (4), return an iterator that points to the position where the new element was inserted into the unordered_set or, if an element with an equivalent key already exists, to the existing element. +The single-element-with-hint member functions, (3) and (4), return an iterator that points to the position where the new element was inserted into the `unordered_set` or, if an element with an equivalent key already exists, to the existing element. ### Remarks @@ -1412,17 +1411,17 @@ During the insertion of just one element, if an exception is thrown but doesn't To access the iterator component of a `pair` `pr` that's returned by the single-element member functions, use `pr.first`; to dereference the iterator within the returned pair, use`*pr.first`, giving you an element. To access the **`bool`** component, use `pr.second`. For an example, see the sample code later in this article. -The [value_type](../standard-library/map-class.md#value_type) of a container is a typedef that belongs to the container, and, for set, `unordered_set::value_type` is type `const V`. +The [`value_type`](../standard-library/map-class.md#value_type) of a container is a typedef that belongs to the container, and, for set, `unordered_set::value_type` is type `const V`. -The range member function (5) inserts the sequence of element values into an unordered_set that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, *Last* doesn't get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `s.insert(v.begin(), v.end());` attempts to insert all elements of `v` into `s`. Only elements that have unique values in the range are inserted; duplicates are ignored. To observe which elements are rejected, use the single-element versions of `insert`. +The range member function (5) inserts the sequence of element values into an `unordered_set` that corresponds to each element addressed by an iterator in the range `[First, Last)`; therefore, *`Last`* doesn't get inserted. The container member function `end()` refers to the position just after the last element in the container—for example, the statement `s.insert(v.begin(), v.end());` attempts to insert all elements of `v` into `s`. Only elements that have unique values in the range are inserted; duplicates are ignored. To observe which elements are rejected, use the single-element versions of `insert`. -The initializer list member function (6) uses an [initializer_list](../standard-library/initializer-list.md) to copy elements into the unordered_set. +The initializer list member function (6) uses an [`initializer_list`](../standard-library/initializer-list.md) to copy elements into the `unordered_set`. -For insertion of an element constructed in place—that is, no copy or move operations are performed—see [set::emplace](../standard-library/set-class.md#emplace) and [set::emplace_hint](../standard-library/set-class.md#emplace_hint). +For insertion of an element constructed in place—that is, no copy or move operations are performed—see [`set::emplace`](../standard-library/set-class.md#emplace) and [`set::emplace_hint`](../standard-library/set-class.md#emplace_hint). -For a code example, see [set::insert](../standard-library/set-class.md#insert). +For a code example, see [`set::insert`](../standard-library/set-class.md#insert). -## iterator +## `iterator` A type that provides a constant [forward iterator](../standard-library/forward-iterator-tag-struct.md) that can read elements in an unordered_set. @@ -1432,9 +1431,9 @@ typedef implementation-defined iterator; ### Example -See the example for [begin](../standard-library/set-class.md#begin) for an example of how to declare and use an**iterator**. +See the example for [`begin`](../standard-library/set-class.md#begin) for an example of how to declare and use an **iterator**. -## key_eq +## `key_eq` Gets the stored comparison function object. @@ -1474,7 +1473,7 @@ cmpfn('a', 'a') == true cmpfn('a', 'b') == false ``` -## key_equal +## `key_equal` The type of the comparison function. @@ -1514,7 +1513,7 @@ cmpfn('a', 'a') == true cmpfn('a', 'b') == false ``` -## key_type +## `key_type` The type of an ordering key. @@ -1566,7 +1565,7 @@ int main() [d] [c] [b] [a] ``` -## load_factor +## `load_factor` Counts the average elements per bucket. @@ -1651,7 +1650,7 @@ max_bucket_count() == 128 max_load_factor() == 0.1 ``` -## local_iterator +## `local_iterator` The type of a bucket iterator. @@ -1698,7 +1697,7 @@ int main() [a] ``` -## max_bucket_count +## `max_bucket_count` Gets the maximum number of buckets. @@ -1783,7 +1782,7 @@ max_bucket_count() == 128 max_load_factor() == 0.1 ``` -## max_load_factor +## `max_load_factor` Gets or sets the maximum elements per bucket. @@ -1795,12 +1794,12 @@ void max_load_factor(float factor); ### Parameters -*factor*\ +*`factor`*\ The new maximum load factor. ### Remarks -The first member function returns the stored maximum load factor. The second member function replaces the stored maximum load factor with *factor*. +The first member function returns the stored maximum load factor. The second member function replaces the stored maximum load factor with *`factor`*. ### Example @@ -1875,7 +1874,7 @@ max_bucket_count() == 128 max_load_factor() == 0.1 ``` -## max_size +## `max_size` Gets the maximum size of the controlled sequence. @@ -1910,7 +1909,7 @@ int main() max_size() == 4294967295 ``` -## operator= +## `operator=` Copies a hash table. @@ -1922,12 +1921,12 @@ unordered_set& operator=(unordered_set&& right); ### Parameters -*right*\ -The [unordered_set](../standard-library/unordered-set-class.md) being copied into the `unordered_set`. +*`right`*\ +The [`unordered_set`](../standard-library/unordered-set-class.md) being copied into the `unordered_set`. ### Remarks -After erasing any existing elements in an `unordered_set`, `operator=` either copies or moves the contents of *right* into the `unordered_set`. +After erasing any existing elements in an `unordered_set`, `operator=` either copies or moves the contents of *`right`* into the `unordered_set`. ### Example @@ -1966,7 +1965,7 @@ int main( ) } ``` -## pointer +## `pointer` The type of a pointer to an element. @@ -2012,7 +2011,7 @@ int main() [c] [b] [a] ``` -## reference +## `reference` The type of a reference to an element. @@ -2058,7 +2057,7 @@ int main() [c] [b] [a] ``` -## rehash +## `rehash` Rebuilds the hash table. @@ -2068,12 +2067,12 @@ void rehash(size_type nbuckets); ### Parameters -*nbuckets*\ +*`nbuckets`*\ The requested number of buckets. ### Remarks -The member function alters the number of buckets to be at least *nbuckets* and rebuilds the hash table as needed. +The member function alters the number of buckets to be at least *`nbuckets`* and rebuilds the hash table as needed. ### Example @@ -2135,7 +2134,7 @@ load_factor() == 0.0234375 max_load_factor() == 0.1 ``` -## size +## `size` Counts the number of elements. @@ -2200,7 +2199,7 @@ size == 2 empty() == false ``` -## size_type +## `size_type` The type of an unsigned distance between two elements. @@ -2236,7 +2235,7 @@ int main() size == 0 ``` -## swap +## `swap` Swaps the contents of two containers. @@ -2246,12 +2245,12 @@ void swap(unordered_set& right); ### Parameters -*right*\ +*`right`*\ The container to swap with. ### Remarks -The member function swaps the controlled sequences between **`*this`** and *right*. If [unordered_set::get_allocator](#get_allocator)`() == right.get_allocator()`, it does so in constant time, it throws an exception only as a result of copying the stored traits object of type `Tr`, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. +The member function swaps the controlled sequences between **`*this`** and *`right`*. If [`unordered_set::get_allocator`](#get_allocator)`() == right.get_allocator()`, it does so in constant time, it throws an exception only as a result of copying the stored traits object of type `Tr`, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. ### Example @@ -2305,7 +2304,7 @@ int main() [c] [b] [a] ``` -## unordered_set +## `unordered_set` Constructs a container object. @@ -2354,42 +2353,42 @@ unordered_set( ### Parameters -*InputIterator*\ +*`InputIterator`*\ The iterator type. -*Al*\ +*`Al`*\ The allocator object to store. -*Comp*\ +*`Comp`*\ The comparison function object to store. -*Hash*\ +*`Hash`*\ The hash function object to store. -*bucket_count*\ +*`bucket_count`*\ The minimum number of buckets. -*Right*\ +*`Right`*\ The container to copy. -*IList*\ -The initializer_list containing the elements to copy. +*`IList`*\ +The `initializer_list` containing the elements to copy. ### Remarks -The first constructor specifies a copy of the sequence controlled by *Right*. The second constructor specifies an empty controlled sequence. The third constructor specifies a copy of the sequence by moving *Right* The fourth through eighth constructors use an initializer_list to specify the elements to copy. The ninth constructor inserts the sequence of element values`[first, last)`. +The first constructor specifies a copy of the sequence controlled by *`Right`*. The second constructor specifies an empty controlled sequence. The third constructor specifies a copy of the sequence by moving *`Right`* The fourth through eighth constructors use an `initializer_list` to specify the elements to copy. The ninth constructor inserts the sequence of element values`[first, last)`. -All constructors also initialize several stored values. For the copy constructor, the values are obtained from *Right*. Otherwise: +All constructors also initialize several stored values. For the copy constructor, the values are obtained from *`Right`*. Otherwise: -The minimum number of buckets is the argument *bucket_count*, if present; otherwise it's a default value described here as the implementation-defined value `N0`. +The minimum number of buckets is the argument *`bucket_count`*, if present; otherwise it's a default value described here as the implementation-defined value `N0`. -The hash function object is the argument *Hash*, if present; otherwise it's `Hash()`. +The hash function object is the argument *`Hash`*, if present; otherwise it's `Hash()`. -The comparison function object is the argument *Comp*, if present; otherwise it's `Comp()`. +The comparison function object is the argument *`Comp`*, if present; otherwise it's `Comp()`. -The allocator object is the argument *Al*, if present; otherwise, it's `Alloc()`. +The allocator object is the argument *`Al`*, if present; otherwise, it's `Alloc()`. -## value_type +## `value_type` The type of an element. diff --git a/docs/standard-library/using-cpp-library-headers.md b/docs/standard-library/using-cpp-library-headers.md index 7a77e857bf..7e05e13cf0 100644 --- a/docs/standard-library/using-cpp-library-headers.md +++ b/docs/standard-library/using-cpp-library-headers.md @@ -3,7 +3,6 @@ description: "Learn more about: Using C++ Library Headers" title: "Using C++ Library Headers" ms.date: "11/04/2016" helpviewer_keywords: ["headers, naming in C++ include directive", "standard header in C++", "headers", "INCLUDE directive", "headers, C++ Standard Library", "library headers", "C++ Standard Library, headers"] -ms.assetid: a36e889e-1af2-4cd9-a211-bfc7a3fd8e85 --- # Using C++ Library Headers @@ -13,23 +12,23 @@ You include the contents of a standard header by naming it in an include directi #include // include I/O facilities ``` -You can include the standard headers in any order, a standard header more than once, or two or more standard headers that define the same macro or the same type. Do not include a standard header within a declaration. Do not define macros that have the same names as keywords before you include a standard header. +You can include the standard headers in any order, a standard header more than once, or two or more standard headers that define the same macro or the same type. Don't include a standard header within a declaration. Don't define macros that have the same names as keywords before you include a standard header. A C++ library header includes any other C++ library headers it needs to define needed types. (Always include explicitly any C++ library headers needed in a translation unit, however, lest you guess wrong about its actual dependencies.) A Standard C header never includes another standard header. A standard header declares or defines only the entities described for it in this document. Every function in the library is declared in a standard header. Unlike in Standard C, the standard header never provides a masking macro with the same name as the function that masks the function declaration and achieves the same effect. For more information on masking macros, see [C++ Library Conventions](../standard-library/cpp-library-conventions.md). -All names other than **operator delete** and **operator new** in the C++ library headers are defined in the `std` namespace, or in a namespace nested within the `std` namespace. You refer to the name `cin`, for example, as `std::cin`. Note, however, that macro names are not subject to namespace qualification, so you always write `__STD_COMPLEX` without a namespace qualifier. +All names other than **`operator delete`** and **`operator new`** in the C++ library headers are defined in the `std` namespace, or in a namespace nested within the `std` namespace. You refer to the name `cin`, for example, as `std::cin`. Note, however, that macro names aren't subject to namespace qualification, so you always write `__STD_COMPLEX` without a namespace qualifier. -In some translation environments, including a C++ library header may hoist external names declared in the `std` namespace into the global namespace as well, with individual **`using`** declarations for each of the names. Otherwise, the header does *not* introduce any library names into the current namespace. +In some translation environments, including a C++ library header may hoist external names declared in the `std` namespace into the global namespace as well, with individual **`using`** declarations for each of the names. Otherwise, the header doesn't* introduce any library names into the current namespace. The C++ Standard requires that the C Standard headers declare all external names in namespace `std`, then hoist them into the global namespace with individual **`using`** declarations for each of the names. But in some translation environments the C Standard headers include no namespace declarations, declaring all names directly in the global namespace. Thus, the most portable way to deal with namespaces is to follow two rules: -- To assuredly declare in namespace `std` an external name that is traditionally declared in \, for example, include the header \. Know that the name might also be declared in the global namespace. +- To assuredly declare in namespace `std` an external name that is traditionally declared in ``, for example, include the header ``. Know that the name might also be declared in the global namespace. -- To assuredly declare in the global namespace an external name declared in \, include the header \ directly. Know that the name might also be declared in namespace `std`. +- To assuredly declare in the global namespace an external name declared in ``, include the header `` directly. Know that the name might also be declared in namespace `std`. -Thus, if you want to call `std::abort` to cause abnormal termination, you should include \. If you want to call `abort`, you should include \. +Thus, if you want to call `std::abort` to cause abnormal termination, you should include ``. If you want to call `abort`, you should include ``. Alternatively, you can write the declaration: diff --git a/docs/standard-library/using-extraction-operators.md b/docs/standard-library/using-extraction-operators.md index 5e767754c2..61adbbbf98 100644 --- a/docs/standard-library/using-extraction-operators.md +++ b/docs/standard-library/using-extraction-operators.md @@ -3,13 +3,12 @@ description: "Learn more about: Using Extraction Operators" title: "Using Extraction Operators" ms.date: "11/04/2016" helpviewer_keywords: ["extraction operators [C++]", ">> operator [C++], extraction operators", "operators [C++], extraction"] -ms.assetid: a961e1a9-4897-41de-b210-89d5b2d051ae --- # Using Extraction Operators The extraction operator (`>>`), which is preprogrammed for all standard C++ data types, is the easiest way to get bytes from an input stream object. -Formatted text input extraction operators depend on white space to separate incoming data values. This is inconvenient when a text field contains multiple words or when commas separate numbers. In such a case, one alternative is to use the unformatted input member function [istream::getline](../standard-library/basic-istream-class.md#getline) to read a block of text with white space included, then parse the block with special functions. Another method is to derive an input stream class with a member function such as `GetNextToken`, which can call istream members to extract and format character data. +Formatted text input extraction operators depend on white space to separate incoming data values. This is inconvenient when a text field contains multiple words or when commas separate numbers. In such a case, one alternative is to use the unformatted input member function [`istream::getline`](../standard-library/basic-istream-class.md#getline) to read a block of text with white space included, then parse the block with special functions. Another method is to derive an input stream class with a member function such as `GetNextToken`, which can call `istream` members to extract and format character data. ## See also diff --git a/docs/standard-library/using-insertion-operators-and-controlling-format.md b/docs/standard-library/using-insertion-operators-and-controlling-format.md index 561261d466..e61172bb4d 100644 --- a/docs/standard-library/using-insertion-operators-and-controlling-format.md +++ b/docs/standard-library/using-insertion-operators-and-controlling-format.md @@ -87,7 +87,7 @@ int main( ) } ``` -The `width` member function is declared in ``. If you use `setw` or any other manipulator with arguments, you must include ``. In the output, strings print in a field of width 6 and integers in a field of width 10: +The `width` member function is declared in ``. If you use `setw` or any other manipulator with arguments, you must include ``. In the output, strings print in a field of width 7 and integers in a field of width 10: ```Output Zoot 1.23 diff --git a/docs/standard-library/utc-clock-class.md b/docs/standard-library/utc-clock-class.md index eab611188e..1521bfbe8e 100644 --- a/docs/standard-library/utc-clock-class.md +++ b/docs/standard-library/utc-clock-class.md @@ -1,8 +1,10 @@ --- -description: "Learn more about: utc_clock class" title: "utc_clock class" +description: "Learn more about: utc_clock class" ms.date: 07/27/2021 f1_keywords: ["chrono/std::chrono::utc_clock", "chrono/std::chrono::utc_clock::now", "chrono/std::chrono::utc_clock::to_sys", "chrono/std::chrono::utc_clock::from_sys", "chrono/std::chrono::utc_clock::is_steady Constant"] +helpviewer_keywords: ["std::chrono [C++], utc_clock"] +dev_langs: ["C++"] --- # `utc_clock` class @@ -63,7 +65,7 @@ UTC time, by definition, starts out 10 seconds behind TAI (atomic time). 10 seco |Name|Description| |----------|-----------------| -|[`utc_clock::is_steady constant]`(#is_steady_constant)|Indicates whether the clock type is steady. Its value is `false`.| +|[`utc_clock::is_steady` constant](#is_steady_constant)|Indicates whether the clock type is steady. Its value is `false`.| ## Requirements @@ -119,7 +121,7 @@ Static value that specifies whether the clock type is *steady*. In Microsoft's i static const bool is_steady = false; ``` -## now +## `now` Static method that returns the current UTC time. The returned time includes leap seconds. diff --git a/docs/standard-library/utility-functions.md b/docs/standard-library/utility-functions.md index f0db979dc4..649d493934 100644 --- a/docs/standard-library/utility-functions.md +++ b/docs/standard-library/utility-functions.md @@ -3,12 +3,11 @@ description: "Learn more about: functions" title: " functions" ms.date: "11/04/2016" f1_keywords: ["utility/std::exchange", "utility/std::forward", "utility/std::make_pair", "utility/std::move", "utility/std::swap"] -ms.assetid: b1df38cd-3a59-4098-9c81-83342eb719a4 helpviewer_keywords: ["std::exchange [C++]", "std::forward [C++]", "std::make_pair [C++]", "std::move [C++]", "std::swap [C++]"] --- # `` functions -## as_const +## `as_const` ```cpp template constexpr add_const_t& as_const(T& t) noexcept; @@ -17,17 +16,17 @@ template void as_const(const T&&) = delete; ### Return Value -Returns *T*. +Returns *`T`*. -## declval +## `declval` ```cpp template add_rvalue_reference_t declval() noexcept; // as unevaluated operand ``` -## exchange +## `exchange` -**(C++14)** Assigns a new value to an object and returns its old value. +**`(C++14)`** Assigns a new value to an object and returns its old value. ```cpp template @@ -36,15 +35,15 @@ template ### Parameters -*val*\ -The object that will receive the value of new_val. +*`val`*\ +The object that will receive the value of `new_val`. -*new_val*\ -The object whose value is copied or moved into val. +*`new_val`*\ +The object whose value is copied or moved into `val`. ### Remarks -For complex types, `exchange` avoids copying the old value when a move constructor is available, avoids copying the new value if it’s a temporary object or is moved, and accepts any type as the new value, using any available converting assignment operator. The exchange function is different from [std::swap](../standard-library/algorithm-functions.md#swap) in that the left argument isn't moved or copied to the right argument. +For complex types, `exchange` avoids copying the old value when a move constructor is available, avoids copying the new value if it's a temporary object or is moved, and accepts any type as the new value, using any available converting assignment operator. The exchange function is different from [`std::swap`](../standard-library/algorithm-functions.md#swap) in that the left argument isn't moved or copied to the right argument. ### Example @@ -80,7 +79,7 @@ The old value of c1 is: 1 The new value of c1 after exchange is: 2 ``` -## forward +## `forward` Conditionally casts its argument to an rvalue reference if the argument is an rvalue or rvalue reference. This restores the rvalue-ness of an argument to the forwarding function in support of perfect forwarding. @@ -94,15 +93,15 @@ template // accepts everything else ### Parameters -*Type*\ -The type of the value passed in *Arg*, which might be different than the type of *Arg*. Typically determined by a template argument of the forwarding function. +*`Type`*\ +The type of the value passed in *`Arg`*, which might be different than the type of *`Arg`*. Typically determined by a template argument of the forwarding function. -*Arg*\ +*`Arg`*\ The argument to cast. ### Return Value -Returns an rvalue reference to *Arg* if the value passed in *Arg* was originally an rvalue or a reference to an rvalue; otherwise, returns *Arg* without modifying its type. +Returns an rvalue reference to *`Arg`* if the value passed in *`Arg`* was originally an rvalue or a reference to an rvalue; otherwise, returns *`Arg`* without modifying its type. ### Remarks @@ -124,7 +123,7 @@ from_chars_result from_chars(const char* first, const char* last, double& value, from_chars_result from_chars(const char* first, const char* last, long double& value, chars_format fmt = chars_format::general); ``` -## get +## `get` Gets an element from a `pair` object by index position, or by type. @@ -171,25 +170,25 @@ template ### Parameters -*Index*\ +*`Index`*\ The 0-based index of the chosen element. -*T1*\ +*`T1`*\ The type of the first pair element. -*T2*\ +*`T2`*\ The type of the second pair element. -*pr*\ +*`pr`*\ The pair to select from. ### Remarks The template functions each return a reference to an element of its `pair` argument. -For the indexed overloads, if the value of *Index* is 0 the functions return `pr.first` and if the value of *Index* is 1 the functions return `pr.second`. The type `RI` is the type of the returned element. +For the indexed overloads, if the value of *`Index`* is 0 the functions return `pr.first` and if the value of *`Index`* is 1 the functions return `pr.second`. The type `RI` is the type of the returned element. -For the overloads that don't have an Index parameter, the element to return is deduced by the type argument. Calling `get(Tuple)` will produce a compiler error if *pr* contains more or less than one element of type T. +For the overloads that don't have an `Index` parameter, the element to return is deduced by the type argument. Calling `get(Tuple)` will produce a compiler error if *`pr`* contains more or less than one element of type `T`. ### Example @@ -199,7 +198,6 @@ For the overloads that don't have an Index parameter, the element to return is d using namespace std; int main() { - typedef pair MyPair; MyPair c0(9, 3.14); @@ -220,35 +218,35 @@ int main() 1 0.27 ``` -## index_sequence +## `index_sequence` ```cpp template using index_sequence = integer_sequence; ``` -## index_sequence_for +## `index_sequence_for` ```cpp template using index_sequence_for = make_index_sequence; ``` -## make_index_sequence +## `make_index_sequence` ```cpp template using make_index_sequence = make_integer_sequence; ``` -## make_integer_sequence +## `make_integer_sequence` ```cpp template using make_integer_sequence = integer_sequence; ``` -## make_pair +## `make_pair` A template function that you can use to construct objects of type `pair`, where the component types are automatically chosen based on the data types that are passed as parameters. @@ -268,10 +266,10 @@ template ### Parameters -*Val1*\ +*`Val1`*\ Value that initializes the first element of `pair`. -*Val2*\ +*`Val2`*\ Value that initializes the second element of `pair`. ### Return Value @@ -280,13 +278,13 @@ The pair object that's constructed: `pair`<`T`,`U`>(`Val1`, `Val2`). ### Remarks -`make_pair` converts object of type [reference_wrapper Class](../standard-library/reference-wrapper-class.md) to reference types and converts decaying arrays and functions to pointers. +`make_pair` converts object of type [`reference_wrapper` Class](../standard-library/reference-wrapper-class.md) to reference types and converts decaying arrays and functions to pointers. In the returned `pair` object, `T` is determined as follows: - If the input type `T` is `reference_wrapper`, the returned type `T` is `X&`. -- Otherwise, the returned type `T` is `decay::type`. If [decay Class](../standard-library/decay-class.md) isn't supported, the returned type `T` is the same as the input type `T`. +- Otherwise, the returned type `T` is `decay::type`. If [`decay` Class](../standard-library/decay-class.md) isn't supported, the returned type `T` is the same as the input type `T`. The returned type `U` is similarly determined from the input type `U`. @@ -296,9 +294,9 @@ The `make_pair` helper function also makes it possible to pass two values to a f ### Example -For an example about how to use the helper function `make_pair` to declare and initialize a pair, see [pair Structure](../standard-library/pair-structure.md). +For an example about how to use the helper function `make_pair` to declare and initialize a pair, see [`pair` Structure](../standard-library/pair-structure.md). -## move +## `move` Unconditionally casts its argument to an rvalue reference, and thereby signals that it can be moved if its type is move-enabled. @@ -309,11 +307,11 @@ template ### Parameters -*Type*\ -A type deduced from the type of the argument passed in *Arg*, together with the reference collapsing rules. +*`Type`*\ +A type deduced from the type of the argument passed in *`Arg`*, together with the reference collapsing rules. -*Arg*\ -The argument to cast. Although the type of *Arg* appears to be specified as an rvalue reference, `move` also accepts lvalue arguments because lvalue references can bind to rvalue references. +*`Arg`*\ +The argument to cast. Although the type of *`Arg`* appears to be specified as an rvalue reference, `move` also accepts lvalue arguments because lvalue references can bind to rvalue references. ### Return Value @@ -321,21 +319,21 @@ The argument to cast. Although the type of *Arg* appears to be specified as an r ### Remarks -The template argument *Type* isn't intended to be specified explicitly, but to be deduced from the type of the value passed in *Arg*. The type of *Type* is further adjusted according to the reference collapsing rules. +The template argument *`Type`* isn't intended to be specified explicitly, but to be deduced from the type of the value passed in *`Arg`*. The type of *`Type`* is further adjusted according to the reference collapsing rules. -`move` doesn't move its argument. Instead, by unconditionally casting its argument—which might be an lvalue—to an rvalue reference, it enables the compiler to subsequently move, rather than copy, the value passed in *Arg* if its type is move-enabled. If its type isn't move-enabled, it's copied instead. +`move` doesn't move its argument. Instead, by unconditionally casting its argument—which might be an lvalue—to an rvalue reference, it enables the compiler to subsequently move, rather than copy, the value passed in *`Arg`* if its type is move-enabled. If its type isn't move-enabled, it's copied instead. -If the value passed in *Arg* is an lvalue—that is, it has a name or its address can be taken—it's invalidated when the move occurs. Don't refer to the value passed in *Arg* by its name or address after it's been moved. +If the value passed in *`Arg`* is an lvalue—that is, it has a name or its address can be taken—it's invalidated when the move occurs. Don't refer to the value passed in *`Arg`* by its name or address after it's been moved. -## move_if_noexcept +## `move_if_noexcept` ```cpp template constexpr conditional_t< !is_nothrow_move_constructible_v && is_copy_constructible_v, const T&, T&&> move_if_noexcept(T& x) noexcept; ``` -## swap +## `swap` -Exchanges the elements of two type or [pair Structure](../standard-library/pair-structure.md) objects. +Exchanges the elements of two type or [`pair` Structure](../standard-library/pair-structure.md) objects. ```cpp template @@ -348,17 +346,17 @@ template ### Parameters -*left*\ +*`left`*\ An object of type or type `pair`. -*right*\ +*`right`*\ An object of type or type `pair`. ### Remarks One advantage of `swap` is that the types of objects that are being stored are determined automatically by the compiler and don't have to be explicitly specified. Don't use explicit template arguments such as `swap(1, 2)` when you use `swap` because it's verbose and adds complex rvalue reference problems that might cause compilation failure. -## to_chars +## `to_chars` ```cpp to_chars_result to_chars(char* first, char* last, see below value, int base = 10); diff --git a/docs/standard-library/utility.md b/docs/standard-library/utility.md index 253764a553..266e984099 100644 --- a/docs/standard-library/utility.md +++ b/docs/standard-library/utility.md @@ -1,27 +1,23 @@ --- description: "Learn more about: " title: "" -ms.date: "11/04/2016" +ms.date: 11/14/2024 f1_keywords: [""] helpviewer_keywords: ["utility header"] -ms.assetid: c4491103-5da9-47a1-9c2b-ed8bc64b0599 --- # `` -Defines C++ Standard Library types, functions, and operators that help to construct and manage pairs of objects, which are useful whenever two objects need to be treated as if they were one. +Defines C++ Standard Library types, functions, and operators that help to construct and manage pairs of objects, which are useful whenever two objects should be treated as if they were one. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Remarks -Pairs are widely used in the C++ Standard Library. They are required both as the arguments and return values for various functions and as element types for containers such as [map class](../standard-library/map-class.md) and [multimap class](../standard-library/multimap-class.md). The \ header is automatically included by \ to assist in managing their key/value pair type elements. - -> [!NOTE] -> The \ header uses the statement `#include `. It also refers to `class tuple` as defined in \. +Pairs are widely used in the C++ Standard Library. They're required both as the arguments and return values for various functions and as element types for associative containers like [`map`](../standard-library/map-class.md) and [`multimap`](../standard-library/multimap-class.md). ## Members @@ -29,57 +25,57 @@ Pairs are widely used in the C++ Standard Library. They are required both as the |Type|Description| |-|-| -|[chars_format](../standard-library/chars-format-class.md)|Floating-point format for primitive numerical conversion.| -|[tuple_element](../standard-library/tuple-element-class-tuple.md)|A class that wraps the type of a `pair` element.| -|[tuple_size](../standard-library/tuple-size-class-tuple.md)|A class that wraps `pair` element count.| +|[`chars_format`](../standard-library/chars-format-class.md)|Floating-point format for primitive numerical conversion.| +|[`tuple_element`](../standard-library/tuple-element-class-tuple.md)|Wraps the type of a `pair` element.| +|[`tuple_size`](../standard-library/tuple-size-class-tuple.md)|Wraps a `pair` element count.| ### Objects |Template|Description| |-|-| -|[index_sequence](../standard-library/utility-functions.md#index_sequence)|An alias template defined for the common case where `T` is `std::size_t` | -|[index_sequence_for](../standard-library/utility-functions.md#index_sequence_for)|Helper alias template to convert any type parameter pack into an index sequence of the same length| -|[make_index_sequence](../standard-library/utility-functions.md#make_index_sequence)| Helper alias template to simplify the creation of a `std::index_sequence` type. | -|[make_integer_sequence](../standard-library/utility-functions.md#make_integer_sequence)|Helper alias template to simplify the creation of a `std::integer_sequence` type.| +|[`index_sequence`](../standard-library/utility-functions.md#index_sequence)|An alias template defined for the common case where `T` is `std::size_t` | +|[`index_sequence_for`](../standard-library/utility-functions.md#index_sequence_for)|Helper alias template to convert any type parameter pack into an index sequence of the same length| +|[`make_index_sequence`](../standard-library/utility-functions.md#make_index_sequence)| Helper alias template to simplify the creation of a `std::index_sequence` type. | +|[`make_integer_sequence`](../standard-library/utility-functions.md#make_integer_sequence)|Helper alias template to simplify the creation of a `std::integer_sequence` type.| ### Functions |Function|Description| |-|-| -|[as_const](../standard-library/utility-functions.md#asconst)|Returns type.| -|[declval](../standard-library/utility-functions.md#declval)|Shorthand expression evaluation.| -|[exchange](../standard-library/utility-functions.md#exchange)|Assigns a new value to an object and returns its old value.| -|[forward](../standard-library/utility-functions.md#forward)|Preserves the reference type (either `lvalue` or `rvalue`) of the argument from being obscured by perfect forwarding.| -|[from_chars](../standard-library/utility-functions.md#from_chars)|| -|[get](../standard-library/utility-functions.md#get)|A function that gets an element from a `pair` object.| -|[make_pair](../standard-library/utility-functions.md#make_pair)|A template helper function used to construct objects of type `pair`, where the component types are based on the data types passed as parameters.| -|[move](../standard-library/utility-functions.md#move)|Returns the passed in argument as an `rvalue` reference.| -|[move_if_noexcept](../standard-library/utility-functions.md#moveif)|| -|[swap](../standard-library/utility-functions.md#swap)|Exchanges the elements of two `pair` objects.| -|[to_chars](../standard-library/utility-functions.md#to_chars)|Converts value into a character string.| +|[`as_const`](../standard-library/utility-functions.md#asconst)|Returns type.| +|[`declval`](../standard-library/utility-functions.md#declval)|Shorthand expression evaluation.| +|[`exchange`](../standard-library/utility-functions.md#exchange)|Assigns a new value to an object and returns its old value.| +|[`forward`](../standard-library/utility-functions.md#forward)|Preserves the reference type (either `lvalue` or `rvalue`) of the argument from being obscured by perfect forwarding.| +|[`from_chars`](../standard-library/utility-functions.md#from_chars)|| +|[`get`](../standard-library/utility-functions.md#get)|A function that gets an element from a `pair` object.| +|[`make_pair`](../standard-library/utility-functions.md#make_pair)|A template helper function used to construct objects of type `pair`, where the component types are based on the data types passed as parameters.| +|[`move`](../standard-library/utility-functions.md#move)|Returns the passed in argument as an `rvalue` reference.| +|[`move_if_noexcept`](../standard-library/utility-functions.md#moveif)|| +|[`swap`](../standard-library/utility-functions.md#swap)|Exchanges the elements of two `pair` objects.| +|[`to_chars`](../standard-library/utility-functions.md#to_chars)|Converts value into a character string.| ### Operators |Operator|Description| |-|-| -|[operator!=](../standard-library/utility-operators.md#op_neq)|Tests if the pair object on the left side of the operator is not equal to the pair object on the right side.| -|[operator==](../standard-library/utility-operators.md#op_eq_eq)|Tests if the pair object on the left side of the operator is equal to the pair object on the right side.| -|[operator\<](../standard-library/utility-operators.md#op_lt)|Tests if the pair object on the left side of the operator is less than the pair object on the right side.| -|[operator\<=](../standard-library/utility-operators.md#op_gt_eq)|Tests if the pair object on the left side of the operator is less than or equal to the pair object on the right side.| -|[operator>](../standard-library/utility-operators.md#op_gt)|Tests if the pair object on the left side of the operator is greater than the pair object on the right side.| -|[operator>=](../standard-library/utility-operators.md#op_gt_eq)|Tests if the pair object on the left side of the operator is greater than or equal to the pair object on the right side.| +|[`operator!=`](../standard-library/utility-operators.md#op_neq)|Tests if the pair object on the left side of the operator isn't equal to the pair object on the right side.| +|[`operator==`](../standard-library/utility-operators.md#op_eq_eq)|Tests if the pair object on the left side of the operator is equal to the pair object on the right side.| +|[`operator<`](../standard-library/utility-operators.md#op_lt)|Tests if the pair object on the left side of the operator is less than the pair object on the right side.| +|[`operator<=`](../standard-library/utility-operators.md#op_gt_eq)|Tests if the pair object on the left side of the operator is less than or equal to the pair object on the right side.| +|[`operator>`](../standard-library/utility-operators.md#op_gt)|Tests if the pair object on the left side of the operator is greater than the pair object on the right side.| +|[`operator>=`](../standard-library/utility-operators.md#op_gt_eq)|Tests if the pair object on the left side of the operator is greater than or equal to the pair object on the right side.| ### Structs |Struct|Description| |-|-| -|[from_chars_result](../standard-library/from-chars-result-structure.md)|A struct used for `from_chars`.| -|[identity](../standard-library/identity-structure.md)|A struct that provides a type definition as the template parameter.| -|[in_place_t](../standard-library/in-place-t-struct.md)|Also includes structs `in_place_type_t` and `in_place_index_t`.| -|[integer_sequence](../standard-library/integer-sequence-class.md)|Represents an integer sequence.| -|[pair](../standard-library/pair-structure.md)|A type that provides for the ability to treat two objects as a single object.| -|[piecewise_construct_t](../standard-library/piecewise-construct-t-structure.md)|A type used to keep separate constructor and function overloading.| -|[to_chars_result](../standard-library/to-chars-result-structure.md)|A struct used for `to_chars`.| +|[`from_chars_result`](../standard-library/from-chars-result-structure.md)|A struct used for `from_chars`.| +|[`identity`](../standard-library/identity-structure.md)|A struct that provides a type definition as the template parameter.| +|[`in_place_t`, `in_place_type_t`, `in_place_index_t`](../standard-library/in-place-t-struct.md)| Indicates how to create an object in place.| +|[`integer_sequence`](../standard-library/integer-sequence-class.md)|Represents an integer sequence.| +|[`pair`](../standard-library/pair-structure.md)|A type that provides for the ability to treat two objects as a single object.| +|[`piecewise_construct_t`](../standard-library/piecewise-construct-t-structure.md)|A type used to keep separate constructor and function overloading.| +|[`to_chars_result`](../standard-library/to-chars-result-structure.md)|A struct used for `to_chars`.| ## See also diff --git a/docs/standard-library/valarray-class.md b/docs/standard-library/valarray-class.md index c2d9b62f28..1cc5c5087a 100644 --- a/docs/standard-library/valarray-class.md +++ b/docs/standard-library/valarray-class.md @@ -1,22 +1,24 @@ --- description: "Learn more about: valarray Class" -title: "valarray Class" -ms.date: "03/27/2019" +title: "valarray class" +ms.date: 06/20/2022 f1_keywords: ["valarray/std::valarray", "valarray/std::valarray::value_type", "valarray/std::valarray::apply", "valarray/std::valarray::cshift", "valarray/std::valarray::free", "valarray/std::valarray::max", "valarray/std::valarray::min", "valarray/std::valarray::resize", "valarray/std::valarray::shift", "valarray/std::valarray::size", "valarray/std::valarray::sum", "valarray/std::valarray::swap"] helpviewer_keywords: ["std::valarray [C++]", "std::valarray [C++], value_type", "std::valarray [C++], apply", "std::valarray [C++], cshift", "std::valarray [C++], free", "std::valarray [C++], max", "std::valarray [C++], min", "std::valarray [C++], resize", "std::valarray [C++], shift", "std::valarray [C++], size", "std::valarray [C++], sum", "std::valarray [C++], swap"] ms.assetid: 19b862f9-5d09-4003-8844-6ddd02c1a3a7 +ms.custom: devdivchpfy22 --- -# valarray Class -The class template describes an object that controls a sequence of elements of type `Type` that are stored as an array, designed for performing high-speed mathematical operations, and optimized for computational performance. +# `valarray` class + +The class template `valarray` describes an object that controls a sequence of elements of type `Type` that are stored as an array, designed for high-speed mathematical operations, and optimized for computational performance. ## Remarks -The class is a representation of the mathematical concept of an ordered set of values and the elements are numbered sequentially from zero. The class is described as a near container because it supports some, but not all, of the capabilities that first-class sequence containers, such as [vector](../standard-library/vector-class.md), support. It differs from class template vector in two important ways: +The class is a representation of the mathematical concept of an ordered set of values. Its elements are numbered sequentially from zero. The class is described as a *near container* because it supports some, but not all, of the capabilities that first-class sequence containers, such as [`vector`](../standard-library/vector-class.md), support. It differs from class template `vector` in two important ways: -- It defines numerous arithmetic operations between corresponding elements of `valarray` objects of the same type and length, such as *xarr* = cos( *yarr*) + sin( *zarr*). +- It defines many arithmetic operations between corresponding elements of `valarray` objects of the same type and length, such as `varr_x* = cos(varr_y) + sin(varr_z)`. -- It defines a variety of interesting ways to subscript a `valarray` object, by overloading [`operator[]`](#op_at). +- It defines various interesting ways to subscript a `valarray` object, by overloading [`operator[]`](#op_at). An object of class `Type`: @@ -30,77 +32,77 @@ In particular, no subtle differences may exist between copy construction and def ### Constructors -|Name|Description| -|-|-| -|[valarray](#valarray)|Constructs a `valarray` of a specific size or with elements of a specific value or as a copy of another `valarray` or subset of another `valarray`.| +| Name | Description | +|--|--| +| [`valarray`](#valarray) | Constructs a `valarray` of a specific size or with elements of a specific value or as a copy of another `valarray` or subset of another `valarray`. | ### Typedefs -|Name|Description| -|-|-| -|[value_type](#value_type)|A type that represents the type of element stored in a `valarray`.| +| Name | Description | +|--|--| +| [`value_type`](#value_type) | A type that represents the type of element stored in a `valarray`. | ### Functions -|Name|Description| -|-|-| -|[apply](#apply)|Applies a specified function to each element of a `valarray`.| -|[cshift](#cshift)|Cyclically shifts all the elements in a `valarray` by a specified number of positions.| -|[free](#free)|Frees the memory used by the `valarray`.| -|[max](#max)|Finds the largest element in a `valarray`.| -|[min](#min)|Finds the smallest element in a `valarray`.| -|[resize](#resize)|Changes the number of elements in a `valarray` to a specified number, adding or removing elements as required.| -|[shift](#shift)|Shifts all the elements in a `valarray` by a specified number of positions.| -|[size](#size)|Finds the number of elements in a `valarray`.| -|[sum](#sum)|Determines the sum of all the elements in a `valarray` of nonzero length.| -|[swap](#swap)|| +| Name | Description | +|--|--| +| [`apply`](#apply) | Applies a specified function to each element of a `valarray`. | +| [`cshift`](#cshift) | Cyclically shifts all the elements in a `valarray` by a specified number of positions. | +| [`free`](#free) | Frees the memory used by the `valarray`. | +| [`max`](#max) | Finds the largest element in a `valarray`. | +| [`min`](#min) | Finds the smallest element in a `valarray`. | +| [`resize`](#resize) | Changes the number of elements in a `valarray` to a specified number, adding or removing elements as required. | +| [`shift`](#shift) | Shifts all the elements in a `valarray` by a specified number of positions. | +| [`size`](#size) | Finds the number of elements in a `valarray`. | +| [`sum`](#sum) | Determines the sum of all the elements in a `valarray` of nonzero length. | +| [`swap`](#swap) | | ### Operators -|Name|Description| -|-|-| -|[operator!](#op_not)|A unary operator that obtains the logical `NOT` values of each element in a `valarray`.| -|[operator%=](#op_mod_eq)|Obtains the remainder of dividing the elements of an array element-wise either by a specified `valarray` or by a value of the element type.| -|[operator&=](#op_and_eq)|Obtains the bitwise `AND` of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type.| -|[operator>>=](#op_gt_gt_eq)|Right-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`.| -|[operator<<=](#op_lt_lt_eq)|Left-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`.| -|[operator*=](#op_star_eq)|Multiplies the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`.| -|[operator+](#op_add)|A unary operator that applies a plus to each element in a `valarray`.| -|[operator+=](#op_add_eq)|Adds the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`.| -|[operator-](#operator-)|A unary operator that applies a minus to each element in a `valarray`.| -|[operator-=](#operator-_eq)|Subtracts the elements of a specified `valarray` or a value of the element type, element-wise, from an operand `valarray`.| -|[operator/=](#op_div_eq)|Divides an operand `valarray` element-wise by the elements of a specified `valarray` or a value of the element type.| -|[operator=](#op_eq)|Assigns elements to a `valarray` whose values are specified either directly or as part of some other `valarray` or by a `slice_array`, `gslice_array`, `mask_array`, or `indirect_array`.| -|[`operator[]`](#op_at)|Returns a reference to an element or its value at specified index or a specified subset.| -|[operator^=](#op_xor_eq)|Obtains the element-wise exclusive logical or operator ( `XOR`) of an array with either a specified valarray or a value of the element type.| -|[`operator|=`](#op_or_eq)|Obtains the bitwise `OR` of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type.| -|[operator~](#op_dtor)|A unary operator that obtains the bitwise `NOT` values of each element in a `valarray`.| - -## apply - -Applies a specified function to each element of a valarray. +| Name | Description | +|--|--| +| [`operator!`](#op_not) | A unary operator that obtains the logical NOT (**`!`**) values of each element in a `valarray`. | +| [`operator%=`](#op_mod_eq) | Obtains the remainder of dividing the elements of an array element-wise either by a specified `valarray` or by a value of the element type. | +| [`operator&=`](#op_and_eq) | Obtains the bitwise AND (**`&`**) of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type. | +| [`operator>>=`](#op_gt_gt_eq) | Right-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`. | +| [`operator<<=`](#op_lt_lt_eq) | Left-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`. | +| [`operator*=`](#op_star_eq) | Multiplies the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`. | +| [`operator+`](#op_add) | A unary operator that applies a plus to each element in a `valarray`. On normal arithmetic types, this operator has no effect. | +| [`operator+=`](#op_add_eq) | Adds the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`. | +| [`operator-`](#operator-) | A unary operator that applies an arithmetic negation to each element in a `valarray`. | +| [`operator-=`](#operator-_eq) | Subtracts the elements of a specified `valarray` or a value of the element type, element-wise, from an operand `valarray`. | +| [`operator/=`](#op_div_eq) | Divides an operand `valarray` element-wise by the elements of a specified `valarray` or a value of the element type. | +| [`operator=`](#op_eq) | Assigns elements to a `valarray` whose values are specified either directly or as part of some other `valarray` or by a `slice_array`, `gslice_array`, `mask_array`, or `indirect_array`. | +| [`operator[]`](#op_at) | Returns a reference to an element or its value at specified index or a specified subset. | +| [`operator^=`](#op_xor_eq) | Obtains the bitwise exclusive or (**`^`**) of a `valarray` with either a specified `valarray` or a value of the element type. | +| [`operator|=`](#op_or_eq) | Obtains the bitwise OR (**`|`**) of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type. | +| [`operator~`](#op_dtor) | A unary operator that obtains the bitwise complement (**`~`**) values of each element in a `valarray`. | + +## `apply` + +Applies a specified function to each element of a `valarray`. ```cpp -valarray apply(Type _Func(Type)) const; +valarray apply(Type function_object(Type)) const; -valarray apply(Type _Func(constType&)) const; +valarray apply(Type function_object(const Type&)) const; ``` ### Parameters -*_Func(Type)*\ -The function object to be applied to each element of the operand valarray. +*`function_object(Type)`*\ +The function object to be applied to each element of the operand `valarray`. -*_Func(const Type&)*\ -The function object for const to be applied to each element of the operand valarray. +*`function_object(const Type&)`*\ +The function object for `const` elements to be applied to each element of the operand `valarray`. -### Return Value +### Return value -A valarray whose elements have had `_Func` applied element-wise to the elements of the operand valarray. +A `valarray` whose elements have had `function_object` applied element-wise to the elements of the operand `valarray`. ### Remarks -The member function returns an object of class [valarray](../standard-library/valarray-class.md)**\**, of length [size](#size), each of whose elements *I* is `_Func((*this)[I])`. +The member function returns an object of class [`valarray`](../standard-library/valarray-class.md), of length [`size`](#size), each of whose elements `elem` is the result of `function_object((*this)[elem])`. ### Example @@ -152,9 +154,9 @@ The element-by-element result of applying MyApplyFunc to vaR is the valarray: ( 0 0 -4 6 0 -10 12 0 -16 18 ) ``` -## cshift +## `cshift` -Cyclically shifts all the elements in a valarray by a specified number of positions. +Cyclically shifts all the elements in a `valarray` by a specified number of positions. ```cpp valarray cshift(int count) const; @@ -162,18 +164,18 @@ valarray cshift(int count) const; ### Parameters -*count*\ +*`count`*\ The number of places the elements are to be shifted forward. -### Return Value +### Return value -A new valarray in which all the elements have been moved *count* positions cyclically toward the front of the valarray, left with respect to their positions in the operand valarray. +A new `valarray` in which all the elements have been moved *`count`* positions cyclically toward the front of the `valarray`, or leftward compared to their positions in the operand `valarray`. ### Remarks -A positive value of *count* shifts the elements cyclically left *count* places. +A positive value of *`count`* shifts the elements cyclically left *`count`* places. -A negative value of *count* shifts the elements cyclically right *count* places. +A negative value of *`count`* shifts the elements cyclically right *`count`* places. ### Example @@ -230,9 +232,9 @@ The cyclically shifted valarray va2 is: va2.shift (-4) = ( 4 3 2 1 10 9 8 7 6 5) ``` -## free +## `free` -Frees the memory used by the valarray. +Frees the memory used by the `valarray`. ```cpp void free(); @@ -240,7 +242,7 @@ void free(); ### Remarks -This nonstandard function is equivalent to assigning an empty valarray. For example: +This nonstandard function is equivalent to assigning an empty `valarray`. For example: ```cpp valarray v; @@ -249,17 +251,17 @@ v = valarray(); // equivalent to v.free() ``` -## max +## `max` -Finds the largest element in a valarray. +Finds the largest element in a `valarray`. ```cpp Type max() const; ``` -### Return Value +### Return value -The maximum value of the elements in the operand valarray. +The maximum value of the elements in the operand `valarray`. ### Remarks @@ -302,17 +304,17 @@ The operand valarray is: ( 0 1 8 3 7 5 6 13 2 9 ). The largest element in the valarray is: 13. ``` -## min +## `min` -Finds the smallest element in a valarray. +Finds the smallest element in a `valarray`. ```cpp Type min() const; ``` -### Return Value +### Return value -The minimum value of the elements in the operand valarray. +The minimum value of the elements in the operand `valarray`. ### Remarks @@ -354,23 +356,21 @@ The smallest element in the valarray is: -9. */ ``` -## operator! +## `operator!` -A unary operator that obtains the logical **NOT** values of each element in a valarray. +A unary operator that obtains the logical NOT (**`!`**) values of each element in a `valarray`. ```cpp valarray operator!() const; ``` -### Return Value +### Return value -The valarray of Boolean values that are the negation of the element values of the operand valarray. +The `valarray` of Boolean values that are the logical negation of the element values of the operand `valarray`. ### Remarks -The logical operation **NOT** negates the elements because it converts all zeros into ones and regards all nonzero values as ones and converts them into zeros. The returned valarray of Boolean values is of the same size as the operand valarray. - -There is also a bitwise **NOT**[valarray::operator~](#op_dtor) that negates on the level of individual bits within the binary representation of **`char`** and **`int`** elements of a valarray. +The logical operation NOT, denoted by **`!`**, logically negates the elements because it converts all zero values into **`true`** and all non-zero values into **`false`**. The returned `valarray` of Boolean values is of the same size as the operand `valarray`. ### Example @@ -413,9 +413,9 @@ The element-by-element result of the logical NOT operator! is the valarray: ( 1 1 1 0 1 0 1 0 1 0 ). ``` -## operator%= +## `operator%=` -Obtains the remainder of dividing the elements of an array element-wise either by a specified valarray or by a value of the element type. +Obtains the remainder of dividing the elements of an array element-wise either by a specified `valarray` or by a value of the element type. ```cpp valarray& operator%=(const valarray& right); @@ -425,12 +425,12 @@ valarray& operator%=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to divide, element-wise, the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to divide, element-wise, the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the remainder from the element-wise division of the operand valarray by *right* +A `valarray` whose elements are the remainder from the element-wise division of the operand `valarray` by *`right`*. ### Example @@ -480,9 +480,9 @@ The remainders from the element-by-element division is the valarray: ( 0 -3 4 -7 1 -3 ). ``` -## operator&= +## `operator&=` -Obtains the bitwise **AND** of elements in an array either with the corresponding elements in a specified valarray or with a value of the element type. +Obtains the bitwise AND (**`&`**) of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type. ```cpp valarray& operator&=(const valarray& right); @@ -492,18 +492,18 @@ valarray& operator&=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be combined, element-wise, by the logical `AND` with the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be combined, element-wise, by the bitwise AND (**`&`**) with the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise logical `AND` of the operand valarray by *right* +A `valarray` whose elements are the bitwise AND (**`&`**) of the operand `valarray` by *`right`* ### Remarks -A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **longdouble**, **`void`**, **`bool`**, or other, more complex data types. +A bitwise operation can only be used to manipulate bits in integral data types, such as **`char`** and **`int`**. It doesn't work on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`**, or other, more complex data types. -The bitwise AND has the same truth table as the logical `AND` but applies to the data type on the level of the individual bits. Given bits *b*1 and *b*2, *b*1 `AND` *b*2 is **`true`** if both bits are true; **`false`** if at least one is false. +The bitwise AND (**`&`**) applies to the data type on the level of the individual bits. Given bits `b1` and `b2`, `b1 & b2` is 1 if both bits are 1; 0 if at least one bit is 0. ### Example @@ -538,7 +538,7 @@ int main( ) vaL &= vaR; cout << "The element-by-element result of " - << "the logical AND operator&= is the" + << "the bitwise AND operator&= is the" << endl << "valarray: ( "; for ( i = 0 ; i < 10 ; i++ ) cout << vaL [ i ] << " "; @@ -549,13 +549,13 @@ int main( ) ```Output The initial valarray is: ( 0 0 0 2 0 4 0 6 0 8 ). The initial Right valarray is: ( 0 1 2 3 4 5 6 7 8 9 ). -The element-by-element result of the logical AND operator&= is the +The element-by-element result of the bitwise AND operator&= is the valarray: ( 0 0 0 2 0 4 0 6 0 8 ). ``` ## `operator>>=` -Right-shifts the bits for each element of a valarray operand a specified number of positions or by an element-wise amount specified by a second valarray. +Right-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`. ```cpp valarray& operator>>=(const valarray& right); @@ -565,12 +565,12 @@ valarray& operator>>=(const Type& right); ### Parameters -*right*\ -The value indicating the amount of right shift or valarray whose elements indicate the element-wise amount of right shift. +*`right`*\ +The value indicating the amount of right shift or a `valarray` whose elements indicate the element-wise amount of right shift. -### Return Value +### Return value -A valarray whose elements have been shifted right the amount specified in *right*. +A `valarray` whose elements have been shifted right the amount specified in *`right`*. ### Remarks @@ -626,7 +626,7 @@ valarray: ( 64 -32 16 -8 4 -2 1 -1 ). ## `operator<<=` -Left-shifts the bits for each element of a valarray operand a specified number of positions or by an element-wise amount specified by a second valarray. +Left-shifts the bits for each element of a `valarray` operand a specified number of positions or by an element-wise amount specified by a second `valarray`. ```cpp valarray& operator<<=(const valarray& right); @@ -636,12 +636,12 @@ valarray& operator<<=(const Type& right); ### Parameters -*right*\ -The value indicating the amount of left shift or valarray whose elements indicate the element-wise amount of left shift. +*`right`*\ +The value indicating the amount of left shift or `valarray` whose elements indicate the element-wise amount of left shift. -### Return Value +### Return value -A valarray whose elements have been shifted left the amount specified in *right*. +A `valarray` whose elements have been shifted left the amount specified in *`right`*. ### Remarks @@ -697,9 +697,9 @@ on the operand array is the valarray: ( 1 -2 4 -8 16 -32 64 -128 ). ``` -## operator*= +## `operator*=` -Multiplies the elements of a specified valarray or a value of the element type, element-wise, to an operand valarray. +Multiplies the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`. ```cpp valarray& operator*=(const valarray& right); @@ -709,12 +709,12 @@ valarray& operator*=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to multiply, element-wise, the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to multiply, element-wise, the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise product of the operand valarray and *right*. +A `valarray` whose elements are the element-wise product of the operand `valarray` and *`right`*. ### Example @@ -763,17 +763,17 @@ valarray: ( 0 -1 4 -3 8 -5 12 -7 ). */ ``` -## operator+ +## `operator+` -A unary operator that applies a plus to each element in a valarray. +A unary operator that applies a plus to each element in a `valarray`. For normal arithmetic values, this operation has no effect. ```cpp valarray operator+() const; ``` -### Return Value +### Return value -A valarray whose elements are plus those of the operand array. +A `valarray` whose elements are the unary plus result of the operand array. ### Example @@ -816,9 +816,9 @@ The element-by-element result of the operator+ is the valarray: ( 0 0 -2 2 -4 4 -6 6 -8 8 ). ``` -## operator+= +## `operator+=` -Adds the elements of a specified valarray or a value of the element type, element-wise, to an operand valarray. +Adds the elements of a specified `valarray` or a value of the element type, element-wise, to an operand `valarray`. ```cpp valarray& operator+=(const valarray& right); @@ -828,12 +828,12 @@ valarray& operator+=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be added, element-wise, to the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be added, element-wise, to the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise sum of the operand valarray and *right*. +A `valarray` whose elements are the element-wise sum of the operand `valarray` and *`right`*. ### Example @@ -883,17 +883,17 @@ The element-by-element result of the sum is the valarray: ( 2 0 4 2 6 4 8 6 ). ``` -## operator- +## `operator-` -A unary operator that applies a minus to each element in a valarray. +A unary operator that applies an arithmetic negation to each element in a `valarray`. ```cpp valarray operator-() const; ``` -### Return Value +### Return value -A valarray whose elements are minus those of the operand array. +A `valarray` whose elements are arithmetically negated from the elements of the operand `valarray`. ### Example @@ -922,7 +922,7 @@ int main( ) vaMINUS = -vaL; cout << "The element-by-element result of " - << "the operator+ is the" + << "the operator- is the" << endl << "valarray: ( "; for ( i = 0 ; i < 10 ; i++ ) cout << vaMINUS [ i ] << " "; @@ -932,13 +932,13 @@ int main( ) ```Output The initial valarray is: ( 0 0 -2 2 -4 4 -6 6 -8 8 ). -The element-by-element result of the operator+ is the +The element-by-element result of the operator- is the valarray: ( 0 0 2 -2 4 -4 6 -6 8 -8 ). ``` -## operator-= +## `operator-=` -Subtracts the elements of a specified valarray or a value of the element type, element-wise, from an operand valarray. +Subtracts the elements of a specified `valarray` or a value of the element type, element-wise, from an operand `valarray`. ```cpp valarray& operator-=(const valarray& right); @@ -948,12 +948,12 @@ valarray& operator-=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be subtracted, element-wise, from the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be subtracted, element-wise, from the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise difference of the operand valarray and *right*. +A `valarray` whose elements are the element-wise difference of the operand `valarray` and *`right`*. ### Example @@ -1003,9 +1003,9 @@ The element-by-element result of the difference is the valarray: ( 10 -1 8 -3 6 -5 4 -7 ). ``` -## operator/= +## `operator/=` -Divides an operand valarray element-wise by the elements of a specified valarray or a value of the element type. +Divides an operand `valarray` element-wise by the elements of a specified `valarray` or a value of the element type. ```cpp valarray& operator/=(const valarray& right); @@ -1015,12 +1015,12 @@ valarray& operator/=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be divided, element-wise, into the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be divided, element-wise, into the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise quotient of the operand valarray divided by *right*. +A `valarray` whose elements are the element-wise quotient of the operand `valarray` divided by *`right`*. ### Example @@ -1070,9 +1070,9 @@ The element-by-element result of the quotient is the valarray: ( inf -50 25 -16.6667 12.5 -10 ). ``` -## operator= +## `operator=` -Assigns elements to a valarray whose values are specified either directly or as part of some other valarray or by a slice_array, gslice_array, mask_array, or indirect_array. +Assigns elements to a `valarray` whose values are specified either directly or as part of some other `valarray` or by a `slice_array`, `gslice_array`, `mask_array`, or `indirect_array`. ```cpp valarray& operator=(const valarray& right); @@ -1081,40 +1081,40 @@ valarray& operator=(valarray&& right); valarray& operator=(const Type& val); -valarray& operator=(const slice_array& _Slicearray); +valarray& operator=(const slice_array& slicearray); -valarray& operator=(const gslice_array& _Gslicearray); +valarray& operator=(const gslice_array& gslicearray); -valarray& operator=(const mask_array& _Maskarray); +valarray& operator=(const mask_array& maskarray); -valarray& operator=(const indirect_array& _Indarray); +valarray& operator=(const indirect_array& indarray); ``` ### Parameters -*right*\ -The valarray to be copied into the operand valarray. +*`right`*\ +The `valarray` to be copied into the operand `valarray`. -*val*\ -The value to be assigned to the elements of the operand valarray. +*`val`*\ +The value to be assigned to the elements of the operand `valarray`. -*_Slicearray*\ -The slice_array to be copied into the operand valarray. +*`slicearray`*\ +The `slice_array` to be copied into the operand `valarray`. -*_Gslicearray*\ -The gslice_array to be copied into the operand valarray. +*`gslicearray`*\ +The `gslice_array` to be copied into the operand `valarray`. -*_Maskarray*\ -The mask_array to be copied into the operand valarray. +*`maskarray`*\ +The `mask_array` to be copied into the operand `valarray`. -*_Indarray*\ -The indirect_array to be copied into the operand valarray. +*`indarray`*\ +The `indirect_array` to be copied into the operand `valarray`. -### Return Value +### Return value -The first member operator replaces the controlled sequence with a copy of the sequence controlled by *right*. +The first member operator replaces the controlled sequence with a copy of the sequence controlled by *`right`*. -The second member operator is the same as the first, but with an [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +The second member operator is the same as the first, but with an [Rvalue reference declarator: `&&`](../cpp/rvalue-reference-declarator-amp-amp.md). The third member operator replaces each element of the controlled sequence with a copy of *val*. @@ -1124,7 +1124,7 @@ If the value of a member in the replacement controlled sequence depends on a mem ### Remarks -If the length of the controlled sequence changes, the result is generally undefined. In this implementation, however, the effect is merely to invalidate any pointers or references to elements in the controlled sequence. +If the length of the controlled sequence changes, normally the result is undefined. In this implementation, however, the effect is merely to invalidate any pointers or references to elements in the controlled sequence. ### Example @@ -1155,7 +1155,7 @@ int main( ) cout << " " << vaR [ i ]; cout << endl; - // Assigning vaR to va with the first member functon + // Assigning vaR to va with the first member function va = vaR; cout << "The reassigned valarray va is:"; for ( i = 0 ; i < 10 ; i++ ) @@ -1163,7 +1163,7 @@ int main( ) cout << endl; // Assigning elements of value 10 to va - // with the second member functon + // with the second member function va = 10; cout << "The reassigned valarray va is:"; for ( i = 0 ; i < 10 ; i++ ) @@ -1177,88 +1177,87 @@ The operand valarray va is: 0 1 2 3 4 5 6 7 8 9 The operand valarray vaR is: 10 9 8 7 6 5 4 3 2 1 The reassigned valarray va is: 10 9 8 7 6 5 4 3 2 1 The reassigned valarray va is: 10 10 10 10 10 10 10 10 10 10 - ``` -## operator[] +## `operator[]` Returns a reference to an element or its value at specified index or a specified subset. ```cpp -Type& operator[](size_t _Off); +Type& operator[](size_t index); -slice_array operator[](slice _Slicearray); +slice_array operator[](slice slicearray); -gslice_array operator[](const gslice& _Gslicearray); +gslice_array operator[](const gslice& gslicearray); -mask_array operator[](const valarray& _Boolarray); +mask_array operator[](const valarray& boolarray); -indirect_array operator[](const valarray& _Indarray); +indirect_array operator[](const valarray& indarray); -Type operator[](size_t _Off) const; +Type operator[](size_t index) const; -valarray operator[](slice _Slice) const; +valarray operator[](slice slicearray) const; -valarray operator[](const gslice& _Gslicearray) const; +valarray operator[](const gslice& gslicearray) const; -valarray operator[](const valarray& _Boolarray) const; +valarray operator[](const valarray& boolarray) const; -valarray operator[](const valarray& _Indarray) const; +valarray operator[](const valarray& indarray) const; ``` ### Parameters -*_Off*\ +*`index`*\ The index of the element to be assigned a value. -*_Slicearray*\ -A slice_array of a valarray that specifies a subset to be selected or returned to a new valarray. +*`slicearray`*\ +A `slice_array` of a `valarray` that specifies a subset to be selected or returned to a new `valarray`. -*_Gslicearray*\ -A gslice_array of a valarray that specifies a subset to be selected or returned to a new valarray. +*`gslicearray`*\ +A `gslice_array` of a `valarray` that specifies a subset to be selected or returned to a new `valarray`. -*_Boolarray*\ -A bool_array of a valarray that specifies a subset to be selected or returned to a new valarray. +*`boolarray`*\ +A `bool_array` of a `valarray` that specifies a subset to be selected or returned to a new `valarray`. -*_Indarray*\ -An indirect_array of a valarray that specifies a subset to be selected or returned to a new valarray. +*`indarray`*\ +An `indirect_array` of a `valarray` that specifies a subset to be selected or returned to a new `valarray`. -### Return Value +### Return value A reference to an element or its value at specified index or a specified subset. ### Remarks -The member operator is overloaded to provide several ways to select sequences of elements from among those controlled by \*this. The first group of five member operators work in conjunction with various overloads of [operator=](#op_eq) (and other assigning operators) to allow selective replacement (slicing) of the controlled sequence. The selected elements must exist. +The member operator is overloaded to provide several ways to select sequences of elements from among the ones controlled by `*this`. The first group of five member operators work together with various overloads of [`operator=`](#op_eq) (and other assigning operators) to allow selective replacement (*slicing*) of the controlled sequence. The selected elements must exist. -When compiled by using [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error occurs if you attempt to access an element outside the bounds of the valarray. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. +When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error occurs if you attempt to access an element outside the bounds of the `valarray`. For more information, see [Checked iterators](../standard-library/checked-iterators.md). ### Example -See the examples for [slice::slice](../standard-library/slice-class.md#slice) and [gslice::gslice](../standard-library/gslice-class.md#gslice) for an example of how to declare and use the operator. +See the examples for [`slice::slice`](../standard-library/slice-class.md#slice) and [`gslice::gslice`](../standard-library/gslice-class.md#gslice) for an example of how to declare and use `operator[]`. -## operator^= +## `operator^=` -Obtains the element-wise exclusive logical or operator ( **XOR**) of an array with either a specified valarray or a value of the element type. +Obtains the bitwise exclusive or (**`^`**) of a `valarray` with either a specified `valarray` or a value of the element type. ```cpp -valarray& operator|=(const valarray& right); +valarray& operator^=(const valarray& right); -valarray& operator|=(const Type& right); +valarray& operator^=(const Type& right); ``` ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be combined, element-wise, by the exclusive logical **XOR** with the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be combined by the bitwise exclusive or (XOR) operator (**`^`**) with the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise, exclusive logical **XOR** of the operand valarray and *right*. +A `valarray` whose elements are the bitwise exclusive or (XOR) of the operand `valarray` and *`right`*. ### Remarks -The exclusive logical or, referred to as **XOR**, has the following semantics: Given elements *e*1 and *e*2, *e*1 **XOR** *e*2 is **`true`** if exactly one of the elements is true; **`false`** if both elements are false or if both elements are true. +The bitwise exclusive or, referred to as XOR and denoted by operator **`^`**, has the following semantics: Given bits `b1` and `b2`, `b1 ^ b2` is 1 if exactly one of the elements is 1, and 0 if both elements are 0 or 1. ### Example @@ -1312,9 +1311,9 @@ The element-by-element result of the bitwise XOR operator^= is the valarray: ( 1 0 0 3 2 4 7 6 6 9 ). ``` -## operator|= +## `operator|=` -Obtains the bitwise `OR` of elements in an array either with the corresponding elements in a specified valarray or with a value of the element type. +Obtains the bitwise OR (**`|`**) of elements in an array either with the corresponding elements in a specified `valarray` or with a value of the element type. ```cpp valarray& operator|=(const valarray& right); @@ -1324,18 +1323,18 @@ valarray& operator|=(const Type& right); ### Parameters -*right*\ -The valarray or value of an element type identical to that of the operand valarray that is to be combined, element-wise, by the bitwise `OR` with the operand valarray. +*`right`*\ +The `valarray` or value of an element type identical to that of the operand `valarray` that is to be combined, element-wise, by the bitwise OR (**`|`**) with the operand `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise bitwise `OR` of the operand valarray by *right*. +A `valarray` whose elements are the element-wise bitwise OR (**`|`**) of the operand `valarray` by *`right`*. ### Remarks -A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **longdouble**, **`void`**, **`bool`**, or other, more complex data types. +A bitwise operation can only be used to manipulate bits in integral data types such as **`char`** and **`int`**. It doesn't work on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`**, or other, more complex data types. -The bitwise `OR` has the same truth table as the logical `OR` but applies to the data type on the level of the individual bits. Given bits *b*1 and *b*2, *b*1 `OR` *b*2 is **`true`** if at least one of the bits is true; **`false`** if both bits are false. +The bitwise OR (**`|`**) applies to the data type on the level of the individual bits. Given bits `b1` and `b2`, `b1 | b2` is 1 if at least one of the bits is 1; 0 if both bits are 0. ### Example @@ -1376,7 +1375,7 @@ int main( ) vaL |= vaR; cout << "The element-by-element result of " - << "the logical OR" + << "the bitwise OR" << endl << "operator|= is the valarray:" << endl << "( "; for (i = 0 ; i < 10 ; i++ ) @@ -1390,28 +1389,28 @@ The initial operand valarray is: ( 1 0 1 0 1 0 1 0 1 0 ). The right valarray is: ( 0 0 1 3 3 4 6 6 7 9 ). -The element-by-element result of the logical OR +The element-by-element result of the bitwise OR operator|= is the valarray: ( 1 0 1 3 3 4 7 6 7 9 ). ``` -## operator~ +## `operator~` -A unary operator that obtains the bitwise `NOT` values of each element in a valarray. +A unary operator that obtains the bitwise complement of values of each element in a `valarray`. ```cpp valarray operator~() const; ``` -### Return Value +### Return value -The valarray of Boolean values that are the bitwise `NOT` of the element values of the operand valarray. +The `valarray` of values that are the unary bitwise complement of the element values of the operand `valarray`. ### Remarks -A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **longdouble**, **`void`**, **`bool`** or other, more complex data types. +A bitwise operation can only manipulate bits in integral types, such as **`char`** and **`int`**. It doesn't work on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`**, or other, more complex data types. -The bitwise `NOT` has the same truth table as the logical `NOT` but applies to the data type on the level of the individual bits. Given bit *b*, ~ *b* is true if *b* is false and false if *b* is true. The logical **NOT**[operator!](#op_not) applies on an element level, counting all nonzero values as **`true`**, and the result is a valarray of Boolean values. The bitwise `NOToperator~`, by contrast, can result in a valarray of values other than 0 or 1, depending on outcome of the bitwise operation. +The unary bitwise complement operator **`~`** applies to the data type at the level of the individual bits. Given bit `b`, `~b` is 1 if `b` is 0 and 0 if `b` is 1. ### Example @@ -1494,26 +1493,26 @@ is the negative of the original elements the valarray: ( 0 2 -2 6 -4 10 -6 14 -8 18 ). ``` -## resize +## `resize` -Changes the number of elements in a valarray to a specified number. +Changes the number of elements in a `valarray` to a specified number. ```cpp void resize( - size_t _Newsize); + size_t new_size); void resize( - size_t _Newsize, + size_t new_size, const Type val); ``` ### Parameters -*_Newsize*\ -The number of elements in the resized valarray. +*`new_size`*\ +The number of elements in the resized `valarray`. -*val*\ -The value to be given to the elements of the resized valarray. +*`val`*\ +The value to be given to the elements of the resized `valarray`. ### Remarks @@ -1523,7 +1522,7 @@ Any pointers or references to elements in the controlled sequence are invalidate ### Example -The following example demonstrates the use of the valarray::resize member function. +The following example demonstrates the use of the `valarray::resize` member function. ```cpp // valarray_resize.cpp @@ -1570,9 +1569,9 @@ The valarray contains ( 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 ). The number of elements in the resized valarray is: 15. ``` -## shift +## `shift` -Shifts all the elements in a valarray by a specified number of places. +Shifts all the elements in a `valarray` by a specified number of places. ```cpp valarray shift(int count) const; @@ -1580,18 +1579,18 @@ valarray shift(int count) const; ### Parameters -*count*\ +*`count`*\ The number of places the elements are to be shifted forward. -### Return Value +### Return value -A new valarray in which all the elements have been moved *count* positions toward the front of the valarray, left with respect to their positions in the operand valarray. +A new `valarray` in which all the elements have been moved *`count`* positions toward the front of the `valarray`, or leftward when compared to their positions in the operand `valarray`. ### Remarks -A positive value of *count* shifts the elements left *count* places, with zero fill. +A positive value of *`count`* shifts the elements left *`count`* places, with zero fill. -A negative value of *count* shifts the elements right *count* places, with zero fill. +A negative value of *`count`* shifts the elements right *`count`* places, with zero fill. ### Example @@ -1645,21 +1644,21 @@ The operand valarray va2(10) is: ( 10 9 8 7 6 5 4 3 2 1 ). The shifted valarray va2 is: va2.shift (-4) = ( 0 0 0 0 10 9 8 7 6 5 ). ``` -## size +## `size` -Finds the number of elements in a valarray. +Finds the number of elements in a `valarray`. ```cpp size_t size() const; ``` -### Return Value +### Return value -The number of elements in the operand valarray. +The number of elements in the operand `valarray`. ### Example -The following example demonstrates the use of the valarray::size member function. +The following example demonstrates the use of the `valarray::size` member function. ```cpp // valarray_size.cpp @@ -1722,21 +1721,21 @@ the operand valarray va2(12) is now: ( 0 1 2 3 4 5 6 7 8 9 10 11 ). The number of elements in the valarray va2 is still: 12. ``` -## sum +## `sum` -Determines the sum of all the elements in a valarray of nonzero length. +Determines the sum of all the elements in a `valarray` of nonzero length. ```cpp Type sum() const; ``` -### Return Value +### Return value -The sum of the elements of the operand valarray. +The sum of the elements of the operand `valarray`. ### Remarks -If the length is greater than one, the member function adds values to the sum by applying `operator+=` between pairs of elements of class `Type`, which operator, consequently, needs be provided for elements of type `Type`. +If the length is greater than one, the member function adds values to the sum by applying `operator+=` between pairs of elements of class `Type`. It means the operator needs be provided for elements of type `Type`. ### Example @@ -1772,9 +1771,9 @@ The operand valarray va (10) is: ( 0 1 2 3 4 5 6 7 8 9 ). The sum of elements in the valarray is: 45. ``` -## swap +## `swap` -Exchanges the elements of two `valarray`s. +Exchanges the elements of two `valarray` objects. ```cpp void swap(valarray& right); @@ -1782,95 +1781,95 @@ void swap(valarray& right); ### Parameters -*right*\ +*`right`*\ A `valarray` providing the elements to be swapped. ### Remarks -The member function swaps the controlled sequences between **`*this`** and *right*. It does so in constant time, it throws no exceptions, and it invalidates no references, pointers, or iterators that designate elements in the two controlled sequences. +The member function swaps the controlled sequences between **`*this`** and *`right`*. It does so in constant time, it throws no exceptions, and it invalidates no references, pointers, or iterators to elements in the two controlled sequences. -## valarray +## `valarray` -Constructs a valarray of a specific size or with elements of a specific value or as a copy of another valarray or subset of another valarray. +Constructs a `valarray` of a specific size or with elements of a specific value or as a copy of another `valarray` or subset of another `valarray`. ```cpp valarray(); explicit valarray( - size_t Count); + size_t count); valarray( - const Type& Val, - size_t Count); + const Type& val, + size_t count); valarray( - const Type* Ptr, - size_t Count); + const Type* ptr, + size_t count); valarray( - const valarray& Right); + const valarray& right); valarray( - const slice_array& SliceArray); + const slice_array& sliceArray); valarray( - const gslice_array& GsliceArray); + const gslice_array& gsliceArray); valarray( - const mask_array& MaskArray); + const mask_array& maskArray); valarray( - const indirect_array& IndArray); + const indirect_array& indArray); valarray( - valarray&& Right); + valarray&& tight); valarray( - initializer_list IList); + initializer_list iList); ``` ### Parameters -*Count*\ -The number of elements to be in the valarray. +*`count`*\ +The number of elements to be in the `valarray`. -*Val*\ -The value to be used in initializing the elements in the valarray. +*`val`*\ +The value to be used in initializing the elements in the `valarray`. -*Ptr*\ -Pointer to the values to be used to initialize the elements in the valarray. +*`ptr`*\ +Pointer to the values to be used to initialize the elements in the `valarray`. -*Right*\ -An existing valarray to initialize the new valarray. +*`right`*\ +An existing `valarray` to initialize the new `valarray`. -*SliceArray*\ -A slice_array whose element values are to be used in initializing the elements of the valarray being constructed. +*`sliceArray`*\ +A `slice_array` whose element values are to be used in initializing the elements of the `valarray` being constructed. -*GsliceArray*\ -A gslice_array whose element values are to be used in initializing the elements of the valarray being constructed. +*`gsliceArray`*\ +A `gslice_array` whose element values are to be used in initializing the elements of the `valarray` being constructed. -*MaskArray*\ -A mask_array whose element values are to be used in initializing the elements of the valarray being constructed. +*`maskArray`*\ +A `mask_array` whose element values are to be used in initializing the elements of the `valarray` being constructed. -*IndArray*\ -A indirect_array whose element values are to be used in initializing the elements of the valarray being constructed. +*`indArray`*\ +A `indirect_array` whose element values are to be used in initializing the elements of the `valarray` being constructed. -*IList*\ -The initializer_list containing the elements to copy. +*`iList`*\ +The `initializer_list` containing the elements to copy. ### Remarks -The first (default) constructor initializes the object to an empty array. The next three constructors each initialize the object to an array of *Count* elements as follows: +The first (default) constructor initializes the object to an empty `valarray`. The next three constructors each initialize the object to a `valarray` of *`count`* elements as follows: -- For explicit `valarray(size_t Count)`, each element is initialized with the default constructor. +- For explicit `valarray(size_t count)`, each element is initialized with the default constructor. -- For `valarray(const Type& Val, Count)`, each element is initialized with *Val*. +- For `valarray(const Type& val, count)`, each element is initialized with *`val`*. -- For `valarray(const Type* Ptr, Count)`, the element at position `I` is initialized with `Ptr`[ `I`]. +- For `valarray(const Type* ptr, count)`, the element at position `I` is initialized with `ptr[I]`. -Each remaining constructor initializes the object to a valarray\ object determined by the subset specified in the argument. +Each remaining constructor initializes the object to a `valarray` object determined by the subset specified in the argument. -The last constructor is the same as the next to last, but with an [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +The last constructor is the same as the next to last, but with an [Rvalue reference declarator: `&&`](../cpp/rvalue-reference-declarator-amp-amp.md). ### Example @@ -1925,9 +1924,9 @@ va[slice( 2, 4, 3)] = ( 0 0 0 ) 1 2 3 4 ``` -## value_type +## `value_type` -A type that represents the type of element stored in a valarray. +A type that represents the type of element stored in a `valarray`. ```cpp typedef Type value_type; @@ -1963,7 +1962,7 @@ int main( ) // value_type declaration and initialization: valarray::value_type Right = 10; - cout << "The decalared value_type Right is: " + cout << "The declared value_type Right is: " << Right << endl; va *= Right; cout << "The resulting valarray is: ( "; @@ -1975,10 +1974,10 @@ int main( ) ```Output The initial operand valarray is: ( 0 -1 2 -1 4 -1 6 -1 8 -1 ). -The decalared value_type Right is: 10 +The declared value_type Right is: 10 The resulting valarray is: ( 0 -10 20 -10 40 -10 60 -10 80 -10 ). ``` ## See also -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/valarray-operators.md b/docs/standard-library/valarray-operators.md index 2a8aadd144..47dbac6e27 100644 --- a/docs/standard-library/valarray-operators.md +++ b/docs/standard-library/valarray-operators.md @@ -8,9 +8,9 @@ helpviewer_keywords: ["std::operator!= (valarray), std::operator& (valarray)", " --- # `` operators -## operator!= +## `operator!=` -Tests whether the corresponding elements of two equally sized valarrays are unequal or whether all the elements of a valarray are unequal a specified value. +Tests whether the corresponding elements of two equally sized `valarray` objects are unequal, or whether all the elements of a `valarray` are unequal to a specified value. ```cpp template @@ -34,27 +34,27 @@ operator!=( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be tested for inequality. +*`left`*\ +A `valarray` object whose elements are to be tested for inequality against another `valarray` object, or a value of element type to compare against each element in a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be tested for inequality. +*`right`*\ +A `valarray` object whose elements are to be tested for inequality against another `valarray` object, or a value of element type to compare against each element in a `valarray`. -### Return Value +### Return value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: - **`true`** if the corresponding elements are unequal. -- **`false`** if the corresponding elements are not unequal. +- **`false`** if the corresponding elements are equal. ### Remarks -The first template operator returns an object of class [valarray\](../standard-library/valarray-bool-class.md), each of whose elements `I` is `left[I] != right[I]`. +The first template operator returns an object of class [`valarray`](../standard-library/valarray-bool-class.md), each of whose elements `I` is `left[I] != right[I]`. -The second template operator stores in element `I` `left[I] != right`. +The second template operator stores `left[I] != right` in element `I`. -The third template operator stores in element `I` `left != right[I]`. +The third template operator stores `left != right[I]` in element `I`. ### Example @@ -105,9 +105,9 @@ The element-by-element result of the not equal comparison test is the valarray: ( 0 0 1 0 1 0 1 0 1 0 ). ``` -## operator% +## `operator%` -Obtains the remainder of dividing the corresponding elements of two equally sized valarrays or of dividing a valarray by a specified value or of dividing a specified value by a valarray. +Obtains the remainder of dividing the corresponding elements of two equally sized `valarray` objects, or of dividing a `valarray` by a specified value, or of dividing a specified value by a `valarray`. ```cpp template @@ -131,15 +131,15 @@ operator%( ### Parameters -*left*\ -A value or valarray that serves as the dividend into which another value or valarray is to be divided. +*`left`*\ +A value or `valarray` that serves as the dividend into which another value or `valarray` is to be divided. -*right*\ -A value or valarray that serves as the divisor and that divides another value or valarray. +*`right`*\ +A value or `valarray` that serves as the divisor and that divides another value or `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise remainders of *left* divided by *right*. +A `valarray` whose elements are the element-wise remainders of *`left`* divided by *`right`*. ### Example @@ -190,9 +190,9 @@ The remainders from the element-by-element division is the valarray: ( 0 -3 4 -7 1 -3 ). ``` -## operator& +## `operator&` -Obtains the bitwise **AND** between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type. +Obtains the bitwise AND between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value of the element type. ```cpp template @@ -216,21 +216,21 @@ operator&( ### Parameters -*left*\ -The first of the two valarrays whose respective elements are to be combined with the bitwise `AND` or a specified value of the element type to be combined bitwise with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose respective elements are to be combined with the bitwise AND, or a specified value of the element type to be combined by bitwise AND with each element of a `valarray`. -*right*\ -The second of the two valarrays whose respective elements are to be combined with the bitwise `AND` or a specified value of the element type to be combined bitwise with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose respective elements are to be combined with the bitwise AND, or a specified value of the element type to be combined by bitwise AND with each element of a `valarray`. ### Return Value -A valarray whose elements are the element-wise combination of the bitwise AND operation of *left* and *right*. +A `valarray` whose elements are the element-wise combination of the bitwise AND operation of *`left`* and *`right`*. ### Remarks -A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **longdouble**, **`void`**, **`bool`** or other, more complex data types. +A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`** or other, more complex data types. -The bitwise `AND` has the same truth table as the logical `AND` but applies to the data type on the level of the individual bits. The [operator&&](#op_amp_amp) applies on an element level, counting all nonzero values as true, and the result is a valarray of Boolean values. The bitwise `AND` [operator&](#op_amp), by contrast, can result in a valarray of values other than 0 or 1, depending on outcome of the bitwise operation. +The bitwise AND has the same truth table as the logical AND but applies to the data type on the level of the individual bits. The [`operator&&`](#op_amp_amp) applies on an element level, counting all nonzero values as `true`, and the result is a `valarray` of Boolean values. The bitwise AND [`operator&`](#op_amp), by contrast, can result in a `valarray` of values other than 0 or 1, depending on the outcome of the bitwise operation. ### Example @@ -281,9 +281,9 @@ The element-by-element result of the bitwise operator & is the valarray: ( 0 0 0 0 0 4 0 0 0 8 ). ``` -## operator&& +## `operator&&` -Obtains the logical **AND** between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the valarray's element type. +Obtains the logical AND between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value of the `valarray` element type. ```cpp template @@ -307,19 +307,19 @@ operator&&( ### Parameters -*left*\ -The first of the two valarrays whose respective elements are to be combined with the logical `AND` or a specified value of the element type to be combined with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose respective elements are to be combined with the logical AND, or a specified value of the element type to be combined with each element of a `valarray`. *right*\ -The second of the two valarrays whose respective elements are to be combined with the logical `AND` or a specified value of the element type to be combined with each element of a valarray. +The second of the two `valarray` objects whose respective elements are to be combined with the logical AND, or a specified value of the element type to be combined with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are of type bool and are the element-wise combination of the logical `AND` operation of *left* and *right*. +A `valarray` whose elements are of type `bool` and are the element-wise combination of the logical AND operation of *`left`* and *`right`*. ### Remarks -The logical `ANDoperator&&` applies on an element level, counting all nonzero values as true, and the result is a valarray of Boolean values. The bitwise version of `AND`, [operator&,](#op_amp), by contrast, can result in a valarray of values other than 0 or 1, depending on the outcome of the bitwise operation. +The logical AND `operator&&` applies on an element level, counting all nonzero values as `true`, and the result is a `valarray` of Boolean values. The bitwise version of AND, [`operator&`](#op_amp), by contrast, can result in a `valarray` of values other than 0 or 1, depending on the outcome of the bitwise operation. ### Example @@ -372,7 +372,7 @@ valarray: ( 0 0 0 1 0 1 0 1 0 1 ). ## `operator>` -Tests whether the elements of one valarray are greater than the elements of an equally sized valarray or whether all the elements of a valarray are greater or less than a specified value. +Tests whether the elements of one `valarray` are greater than the elements of an equally sized `valarray`, or whether all the elements of a `valarray` are greater or less than a specified value. ```cpp template @@ -396,23 +396,23 @@ operator>( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -### Return Value +### Return value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: -- **`true`** if the *left* element or value is greater than the corresponding *right* element or value. +- **`true`** if the *`left`* element or value is greater than the corresponding *`right`* element or value. -- **`false`** if the *left* element or value is not greater than the corresponding *right* element or value. +- **`false`** if the *`left`* element or value isn't greater than the corresponding *`right`* element or value. ### Remarks -If the number of elements in two valarrays is not equal, the result is undefined. +If the number of elements in the two `valarray` objects isn't equal, the result is undefined. ### Example @@ -465,7 +465,7 @@ valarray: ( 1 1 0 1 0 1 0 1 0 1 ). ## `operator>=` -Tests whether the elements of one valarray are greater than or equal to the elements of an equally sized valarray or whether all the elements of a valarray are greater than or equal to or less than or equal to a specified value. +Tests whether the elements of one `valarray` are greater than or equal to the elements of an equally sized `valarray`, or whether all the elements of a `valarray` are greater than or equal to or less than or equal to a specified value. ```cpp template @@ -489,23 +489,23 @@ operator>=( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -### Return Value +### Return value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: -- **`true`** if the *left* element or value is greater than or equal to the corresponding *right* element or value. +- **`true`** if the *`left`* element or value is greater than or equal to the corresponding *`right`* element or value. -- **`false`** if the *left* element or value is less than the corresponding *right* element or value. +- **`false`** if the *`left`* element or value is less than the corresponding *`right`* element or value. ### Remarks -If the number of elements in two valarrays is not equal, the result is undefined. +If the number of elements in two `valarray` objects isn't equal, the result is undefined. ### Example @@ -558,7 +558,7 @@ valarray: ( 1 1 0 1 0 1 0 1 0 1 ). ## `operator>>` -Right-shifts the bits for each element of a valarray a specified number of positions or by an element-wise amount specified by a second valarray. +Right-shifts the bits for each element of a `valarray` a specified number of positions, or by an element-wise amount specified by a second `valarray`. ```cpp template @@ -582,15 +582,15 @@ operator>>( ### Parameters -*left*\ -The value to be shifted or the valarray whose elements are to be shifted. +*`left`*\ +The value to be shifted, or the `valarray` whose elements are to be shifted. -*right*\ -The value indicating the amount of right shift or valarray whose elements indicate the element-wise amount of right shift. +*`right`*\ +The value indicating the amount of right shift, or a `valarray` whose elements indicate the element-wise amount of right shift. -### Return Value +### Return value -A valarray whose elements have been shifted right by the specified amount. +A `valarray` whose elements have been shifted right by the specified amount. ### Remarks @@ -647,7 +647,7 @@ valarray: ( 64 -32 16 -8 4 -2 1 -1 ). ## `operator<` -Tests whether the elements of one valarray are less than the elements of an equally sized valarray or whether all the elements of a valarray are greater or less than a specified value. +Tests whether the elements of one `valarray` are less than the elements of an equally sized `valarray`, or whether all the elements of a `valarray` are greater or less than a specified value. ```cpp template @@ -671,23 +671,23 @@ operator<( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -### Return Value +### Return value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: -- **`true`** if the *left* element or value is less than the corresponding *right* element or value. +- **`true`** if the *`left`* element or value is less than the corresponding *`right`* element or value. -- **`false`** if the *left* element or value is not less than the corresponding *right* element or value. +- **`false`** if the *`left`* element or value isn't less than the corresponding *`right`* element or value. ### Remarks -If the number of elements two valarrays is not equal, the result is undefined. +If the number of elements in two `valarray` objects isn't equal, the result is undefined. ### Example @@ -723,7 +723,7 @@ int main( ) vaNE = ( vaL < vaR ); cout << "The element-by-element result of " - << "the less-than comparson test is the\n" + << "the less-than comparison test is the\n" << "valarray: ( "; for (i = 0 ; i < 10 ; i++ ) cout << vaNE [ i ] << " "; @@ -734,13 +734,13 @@ int main( ) ```Output The initial Left valarray is: ( 0 1 -2 3 -4 5 -6 7 -8 9 ). The initial Right valarray is: ( 0 1 2 3 4 5 6 7 8 9 ). -The element-by-element result of the less-than comparson test is the +The element-by-element result of the less-than comparison test is the valarray: ( 0 0 1 0 1 0 1 0 1 0 ). ``` ## `operator<=` -Tests whether the elements of one valarray are less than or equal to the elements of an equally sized valarray or whether all the elements of a valarray are greater than or equal to or less than or equal to a specified value. +Tests whether the elements of one `valarray` are less than or equal to the elements of an equally sized `valarray`, or whether all the elements of a `valarray` are greater than or equal to or less than or equal to a specified value. ```cpp template @@ -764,23 +764,23 @@ operator<=( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be compared or a specified value to be compared with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be compared, or a specified value to be compared with each element of a `valarray`. -### Return Value +### Return value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: -- **`true`** if the *left* element or value is less than or equal to the corresponding *right* element or value. +- **`true`** if the *`left`* element or value is less than or equal to the corresponding *`right`* element or value. -- **`false`** if the *left* element or value is greater than the corresponding *right* element or value. +- **`false`** if the *`left`* element or value is greater than the corresponding *`right`* element or value. ### Remarks -If the number of elements two valarrays is not equal, the result is undefined. +If the number of elements in two `valarray` objects isn't equal, the result is undefined. ### Example @@ -833,7 +833,7 @@ valarray: ( 0 0 1 0 1 0 1 0 1 0 ). ## `operator<<` -Left shifts the bits for each element of a valarray a specified number of positions or by an element-wise amount specified by a second valarray. +Left shifts the bits for each element of a `valarray` a specified number of positions, or by an element-wise amount specified by a second `valarray`. ```cpp template @@ -857,15 +857,15 @@ operator<<( ### Parameters -*left*\ -The value to be shifted or the valarray whose elements are to be shifted. +*`left`*\ +The value to be shifted, or the `valarray` whose elements are to be shifted. -*right*\ -The value indicating the amount of left shift or valarray whose elements indicate the element-wise amount of left shift. +*`right`*\ +The value indicating the amount of left shift, or a `valarray` whose elements indicate the element-wise amount of left shift. -### Return Value +### Return value -A valarray whose elements have been shifted left by the specified amount. +A `valarray` whose elements have been shifted left by the specified amount. ### Remarks @@ -920,9 +920,9 @@ The element-by-element result of the left shift is the valarray: ( 1 -2 4 -8 16 -32 64 -128 ). ``` -## operator* +## `operator*` -Obtains the element-wise product between corresponding elements of two equally sized valarrays or of between a valarray a specified value. +Obtains the element-wise product between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value. ```cpp template @@ -946,15 +946,15 @@ operator*( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be multiplied or a specified value to be multiplied with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be multiplied, or a specified value to be multiplied with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be multiplied or a specified value to be multiplied with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be multiplied, or a specified value to be multiplied with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise product of *left* and *right*. +A `valarray` whose elements are the element-wise product of *`left`* and *`right`*. ### Example @@ -1005,9 +1005,9 @@ The element-by-element result of the multiplication is the valarray: ( 0 -1 4 -3 8 -5 12 -7 ). ``` -## operator+ +## `operator+` -Obtains the element-wise sum between corresponding elements of two equally sized valarrays or of between a valarray a specified value. +Obtains the element-wise sum between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value. ```cpp template @@ -1031,15 +1031,15 @@ operator+( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be added or a specified value to be added with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose elements are to be added, or a specified value to be added with each element of a `valarray`. -*right*\ -The second of the two valarrays whose elements are to be added or a specified value to be added with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose elements are to be added, or a specified value to be added with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise sum of *left* and *right*. +A `valarray` whose elements are the element-wise sum of *`left`* and *`right`*. ### Example @@ -1090,9 +1090,9 @@ The element-by-element result of the sum is the valarray: ( 2 0 4 2 6 4 8 6 ). ``` -## operator- +## `operator-` -Obtains the element-wise difference between corresponding elements of two equally sized valarrays or of between a valarray a specified value. +Obtains the element-wise difference between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value. ```cpp template @@ -1116,15 +1116,15 @@ operator-( ### Parameters -*left*\ -A value or valarray that serves as the minuend from which other values or valarrays are to be subtracted in forming the difference. +*`left`*\ +A value or `valarray` that serves as the *minuend*, the value from which other values or `valarray` objects are to be subtracted in forming the difference. -*right*\ -A value or valarray that serves as the subtrahend that is to be subtracted from other values or valarrays in forming the difference. +*`right`*\ +A value or `valarray` that serves as the *subtrahend*, the value that is to be subtracted from other values or `valarray` objects in forming the difference. -### Return Value +### Return value -A valarray whose elements are the element-wise difference of *left* and *right*. +A `valarray` whose elements are the element-wise difference of *`left`* and *`right`*. ### Remarks @@ -1181,9 +1181,9 @@ The element-by-element result of the difference is the valarray: ( 10 -1 8 -3 6 -5 4 -7 ). ``` -## operator/ +## `operator/` -Obtains the element-wise quotient between corresponding elements of two equally sized valarrays or of between a valarray a specified value. +Obtains the element-wise quotient between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value. ```cpp template @@ -1207,15 +1207,15 @@ operator/( ### Parameters -*left*\ -A value or valarray that serves as the dividend into which another value or valarray is to be divided in forming the quotient. +*`left`*\ +A value or `valarray` that serves as the *dividend* into which another value or `valarray` is to be divided in forming the quotient. -*right*\ -A value or valarray that serves as the divisor and that divides another value or valarray in forming the quotient. +*`right`*\ +A value or `valarray` that serves as the *divisor*, and that divides another value or `valarray` in forming the quotient. -### Return Value +### Return value -A valarray whose elements are the element-wise quotient of *left* divided by *right*. +A `valarray` whose elements are the element-wise quotient of *`left`* divided by *`right`*. ### Remarks @@ -1272,9 +1272,9 @@ The element-by-element result of the quotient is the valarray: ( inf -50 25 -16.6667 12.5 -10 ). ``` -## operator== +## `operator==` -Tests whether the corresponding elements of two equally sized valarrays are equal or whether all the elements of a valarray are equal a specified value. +Tests whether the corresponding elements of two equally sized `valarray` objects are equal, or whether all the elements of a `valarray` are equal to a specified value. ```cpp template @@ -1298,23 +1298,23 @@ operator==( ### Parameters -*left*\ -The first of the two valarrays whose elements are to be tested for equality. +*`left`*\ +The first of the two `valarray` objects whose elements are to be tested for equality, or a specified value to compare with each `valarray` element. -*right*\ -The second of the two valarrays whose elements are to be tested for equality. +*`right`*\ +The second of the two `valarray` objects whose elements are to be tested for equality, or a specified value to compare with each `valarray` element. ### Return Value -A valarray of Boolean values, each of which is: +A `valarray` of Boolean values, each of which is: - **`true`** if the corresponding elements are equal. -- **`false`** if the corresponding elements are not equal. +- **`false`** if the corresponding elements aren't equal. ### Remarks -The first template operator returns an object of class [valarray\](../standard-library/valarray-bool-class.md), each of whose elements `I` is `left[I] == right[I]`. The second template operator stores in element `I` `left[I] == right`. The third template operator stores in element `I` `left == right[I]`. +The first template operator returns an object of class [`valarray`](../standard-library/valarray-bool-class.md), each of whose elements `I` is `left[I] == right[I]`. The second template operator stores `left[I] == right` in element `I`. The third template operator stores `left == right[I]` in element `I`. ### Example @@ -1365,9 +1365,9 @@ The element-by-element result of the equality comparison test is the valarray: ( 1 1 0 1 0 1 0 1 0 1 ). ``` -## operator^ +## `operator^` -Obtains the bitwise exclusive `OR` ( **XOR**) between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type. +Obtains the bitwise exclusive OR (XOR) between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value of the element type. ```cpp template @@ -1391,21 +1391,21 @@ operator^( ### Parameters -*left*\ -The first of the two valarrays whose respective elements are to be combined with the bitwise **XOR** or a specified value of the element type to be combined bitwise with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose respective elements are to be combined with the bitwise XOR, or a specified value of the element type to be combined by a bitwise XOR with each element of a `valarray`. -*right*\ -The second of the two valarrays whose respective elements are to be combined with the bitwise **XOR** or a specified value of the element type to be combined bitwise with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose respective elements are to be combined with the bitwise XOR, or a specified value of the element type to be combined by a bitwise XOR with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise combination of the bitwise **XOR** operation of *left* and *right*. +A `valarray` whose elements are the element-wise combination of the bitwise XOR operation of *`left`* and *`right`*. ### Remarks A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`** or other, more complex data types. -The bitwise exclusive `OR` ( **XOR**) has the following semantics: Given bits *b*1 and *b*2, *b*1 **XOR** *b*2 is **`true`** if exactly one of the bits is true; **`false`** if both bits are false or if both bits are true. +The bitwise exclusive OR (XOR) has the following semantics: Given bits *b*1 and *b*2, *b*1 XOR *b*2 is 1 if exactly one of the bits is 1; 0 if both bits are 0 or if both bits are 1. ### Example @@ -1460,9 +1460,9 @@ The element-by-element result of the bitwise XOR operator^ is the valarray: ( 1 0 0 3 2 4 7 6 6 9 ). ``` -## operator| +## `operator|` -Obtains the bitwise `OR` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type. +Obtains the bitwise OR between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the element type. ```cpp template @@ -1486,21 +1486,21 @@ operator|( ### Parameters -*left*\ -The first of the two valarrays whose respective elements are to be combined with the bitwise `OR` or a specified value of the element type to be combined bitwise with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose respective elements are to be combined with the bitwise OR, or a specified value of the element type to be combined by bitwise OR with each element of a `valarray`. -*right*\ -The second of the two valarrays whose respective elements are to be combined with the bitwise `OR` or a specified value of the element type to be combined bitwise with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose respective elements are to be combined with the bitwise OR, or a specified value of the element type to be combined by bitwise OR with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are the element-wise combination of the bitwise `OR` operation of *left* and *right*. +A `valarray` whose elements are the element-wise combination of the bitwise OR operation of *`left`* and *`right`*. ### Remarks -A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **longdouble**, **`void`**, **`bool`** or other, more complex data types. +A bitwise operation can only be used to manipulate bits in **`char`** and **`int`** data types and variants and not on **`float`**, **`double`**, **`long double`**, **`void`**, **`bool`** or other, more complex data types. -The bitwise OR has the same truth table as the logical `OR`, but applies to the data type on the level of the individual bits. Given bits *b*1 and *b*2, *b*1 `OR` *b*2 is **`true`** if at least one of the bits is true or **`false`** if both bits are false. The logical `OR`[operator||](../standard-library/valarray-operators.md#op_lor) applies on an element level, counting all nonzero values as **`true`**, and the result is a valarray of Boolean values. The bitwise OR `operator|`, by contrast, can result in a valarray of values other than 0 or 1, depending on the outcome of the bitwise operation. +The bitwise OR has the same truth table as the logical OR, but applies to the data type on the level of the individual bits. Given bits *b*1 and *b*2, *b*1 OR *b*2 is 1 if at least one of the bits is 1, or 0 if both bits are 0. The logical OR [`operator||`](../standard-library/valarray-operators.md#op_lor) applies on an element level, counting all nonzero values as **`true`**, and the result is a `valarray` of Boolean values. The bitwise OR `operator|`, by contrast, can result in a `valarray` of values other than 0 or 1, depending on the outcome of the bitwise operation. ### Example @@ -1555,9 +1555,9 @@ The element-by-element result of the bitwise OR operator| is the valarray: ( 1 0 1 3 3 4 7 6 7 9 ). ``` -## operator|| +## `operator||` -Obtains the logical `OR` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the valarray element type. +Obtains the logical OR between corresponding elements of two equally sized `valarray` objects, or between a `valarray` and a specified value of the `valarray` element type. ```cpp template @@ -1581,19 +1581,19 @@ operator||( ### Parameters -*left*\ -The first of the two valarrays whose respective elements are to be combined with the logical `OR` or a specified value of the element type to be combined with each element of a valarray. +*`left`*\ +The first of the two `valarray` objects whose respective elements are to be combined with the logical OR, or a specified value of the element type to be combined with each element of a `valarray`. -*right*\ -The second of the two valarrays whose respective elements are to be combined with the logical `OR` or a specified value of the element type to be combined with each element of a valarray. +*`right`*\ +The second of the two `valarray` objects whose respective elements are to be combined with the logical OR, or a specified value of the element type to be combined with each element of a `valarray`. -### Return Value +### Return value -A valarray whose elements are of type **`bool`** and are the element-wise combination of the logical OR operation of *left* and *right*. +A `valarray` whose elements are of type **`bool`** and are the element-wise combination of the logical OR operation of *`left`* and *`right`*. ### Remarks -The logical `OR` `operator||` applies on an element level, counting all nonzero values as **`true`**, and the result is a valarray of Boolean values. The bitwise version of `OR`, [operator|](../standard-library/valarray-operators.md#op_or) by contrast, can result in a valarray of values other than 0 or 1, depending on outcome of the bitwise operation. +The logical OR `operator||` applies on an element level, counting all nonzero values as **`true`**, and the result is a `valarray` of Boolean values. The bitwise version of OR, [`operator|`](../standard-library/valarray-operators.md#op_or), by contrast, can result in a `valarray` of values other than 0 or 1, depending on the outcome of the bitwise operation. ### Example diff --git a/docs/standard-library/valarray.md b/docs/standard-library/valarray.md index a9cc962518..7daf458d63 100644 --- a/docs/standard-library/valarray.md +++ b/docs/standard-library/valarray.md @@ -1,14 +1,13 @@ --- description: "Learn more about: " title: "" -ms.date: "11/04/2016" +ms.date: 01/12/2022 f1_keywords: [""] helpviewer_keywords: ["valarray header"] -ms.assetid: 30835415-21c1-4801-8f24-6bbef7dd8ecd --- # `` -Defines the class template valarray and numerous supporting class templates and functions. +Defines the class template `valarray` and several supporting class templates and functions. ## Requirements @@ -21,76 +20,76 @@ Defines the class template valarray and numerous supporting class templates and ## Remarks -These class templates and functions are permitted unusual latitude in the interest of improved performance. Specifically, any function returning type `valarray` may return an object of some other type T2. In that case, any function that accepts one or more arguments of type `valarray` must have overloads that accept arbitrary combinations of those arguments, each replaced with an argument of type T2. +These class templates and functions are permitted unusual latitude in the interest of improved performance. Specifically, any function that returns type `valarray` may return an object of some other type `T2`. In that case, any function that accepts one or more arguments of type `valarray` must have overloads that accept arbitrary combinations of those arguments, each replaced with an argument of type `T2`. ## Members ### Functions -|Name|Description| -|-|-| -|[abs](../standard-library/valarray-functions.md#abs)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the absolute value of the elements of the input valarray.| -|[acos](../standard-library/valarray-functions.md#acos)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the arccosine of the elements of the input valarray.| -|[asin](../standard-library/valarray-functions.md#asin)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the arcsine of the elements of the input valarray.| -|[atan](../standard-library/valarray-functions.md#atan)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the principal value of the arctangent of the elements of the input valarray.| -|[atan2](../standard-library/valarray-functions.md#atan2)|Returns a valarray whose elements are equal to the arctangent of the Cartesian components specified by a combination of constants and elements of valarrays.| -|[begin](../standard-library/valarray-functions.md#begin)|| -|[cos](../standard-library/valarray-functions.md#cos)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the cosine of the elements of the input valarray.| -|[cosh](../standard-library/valarray-functions.md#cosh)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the hyperbolic cosine of the elements of the input valarray.| -|[end](../standard-library/valarray-functions.md#end)|| -|[exp](../standard-library/valarray-functions.md#exp)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the natural exponential of the elements of the input valarray.| -|[log](../standard-library/valarray-functions.md#log)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the natural logarithm of the elements of the input valarray.| -|[log10](../standard-library/valarray-functions.md#log10)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the base 10 or common logarithm of the elements of the input valarray.| -|[pow](../standard-library/valarray-functions.md#pow)|Operates on the elements of input valarrays and constants, returning a valarray whose elements are equal to a base specified either by the elements of an input valarray or a constant raised to an exponent specified either by the elements of an input valarray or a constant.| -|[sin](../standard-library/valarray-functions.md#sin)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the sine of the elements of the input valarray.| -|[sinh](../standard-library/valarray-functions.md#sinh)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the hyperbolic sine of the elements of the input valarray.| -|[sqrt](../standard-library/valarray-functions.md#sqrt)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the square root of the elements of the input valarray.| -|[swap](../standard-library/valarray-functions.md#swap)|| -|[tan](../standard-library/valarray-functions.md#tan)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the tangent of the elements of the input valarray.| -|[tanh](../standard-library/valarray-functions.md#tanh)|Operates on the elements of an input valarray, returning a valarray whose elements are equal to the hyperbolic tangent of the elements of the input valarray.| +| Name | Description | +|--|--| +| [`abs`](../standard-library/valarray-functions.md#abs) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the absolute value of the elements of the input `valarray`. | +| [`acos`](../standard-library/valarray-functions.md#acos) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the arccosine of the elements of the input `valarray`. | +| [`asin`](../standard-library/valarray-functions.md#asin) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the arcsine of the elements of the input `valarray`. | +| [`atan`](../standard-library/valarray-functions.md#atan) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the principal value of the arctangent of the elements of the input `valarray`. | +| [`atan2`](../standard-library/valarray-functions.md#atan2) | Returns a `valarray` whose elements are equal to the arctangent of the Cartesian components specified by a combination of constants and elements of `valarray` inputs. | +| [`begin`](../standard-library/valarray-functions.md#begin) | | +| [`cos`](../standard-library/valarray-functions.md#cos) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the cosine of the elements of the input `valarray`. | +| [`cosh`](../standard-library/valarray-functions.md#cosh) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the hyperbolic cosine of the elements of the input `valarray`. | +| [`end`](../standard-library/valarray-functions.md#end) | | +| [`exp`](../standard-library/valarray-functions.md#exp) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the natural exponential of the elements of the input `valarray`. | +| [`log`](../standard-library/valarray-functions.md#log) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the natural logarithm of the elements of the input `valarray`. | +| [`log10`](../standard-library/valarray-functions.md#log10) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the base 10 or common logarithm of the elements of the input `valarray`. | +| [`pow`](../standard-library/valarray-functions.md#pow) | Operates on the elements of any input `valarray` and constants, returning a `valarray` whose elements are equal to a base specified either by the elements of an input `valarray` or a constant raised to an exponent specified either by the elements of an input `valarray` or a constant. | +| [`sin`](../standard-library/valarray-functions.md#sin) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the sine of the elements of the input `valarray`. | +| [`sinh`](../standard-library/valarray-functions.md#sinh) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the hyperbolic sine of the elements of the input `valarray`. | +| [`sqrt`](../standard-library/valarray-functions.md#sqrt) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the square root of the elements of the input `valarray`. | +| [`swap`](../standard-library/valarray-functions.md#swap) | | +| [`tan`](../standard-library/valarray-functions.md#tan) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the tangent of the elements of the input `valarray`. | +| [`tanh`](../standard-library/valarray-functions.md#tanh) | Operates on the elements of an input `valarray`, returning a `valarray` whose elements are equal to the hyperbolic tangent of the elements of the input `valarray`. | ### Operators -|Name|Description| -|-|-| -|[operator!=](../standard-library/valarray-operators.md#op_neq)|Tests whether the corresponding elements of two equally sized valarrays are unequal or whether all the elements of a valarray are unequal a specified value of the valarray's element type.| -|[operator%](../standard-library/valarray-operators.md#op_mod)|Obtains the remainder of dividing the corresponding elements of two equally sized valarrays or of dividing a valarray by a specified value of the valarray's element type or of dividing a specified value by a valarray.| -|[operator&](../standard-library/valarray-operators.md#op_amp)|Obtains the bitwise `AND` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type.| -|[operator&&](../standard-library/valarray-operators.md#op_amp_amp)|Obtains the logical `AND` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the valarray's element type.| -|[operator>](../standard-library/valarray-operators.md#op_gt)|Tests whether the elements of one valarray are greater than the elements of an equally sized valarray or whether all the elements of a valarray are greater or less than a specified value of the valarray's element type.| -|[operator>=](../standard-library/valarray-operators.md#op_gt_eq)|Tests whether the elements of one valarray are greater than or equal to the elements of an equally sized valarray or whether all the elements of a valarray are greater than or equal to or less than or equal to a specified value.| -|[operator>>](../standard-library/valarray-operators.md#op_gt_gt)|Right-shifts the bits for each element of a valarray a specified number of positions or by an element-wise amount specified by a second valarray.| -|[operator<](../standard-library/valarray-operators.md#op_lt)|Tests whether the elements of one valarray are less than the elements of an equally sized valarray or whether all the elements of a valarray are greater or less than a specified value.| -|[operator<=](../standard-library/valarray-operators.md#op_lt_eq)|Tests whether the elements of one valarray are less than or equal to the elements of an equally sized valarray or whether all the elements of a valarray are greater than or equal to or less than or equal to a specified value.| -|[operator<<](../standard-library/valarray-operators.md#op_lt_lt)|Left shifts the bits for each element of a valarray a specified number of positions or by an element-wise amount specified by a second valarray.| -|[operator*](../standard-library/valarray-operators.md#op_star)|Obtains the element-wise product between corresponding elements of two equally sized valarrays or of between a valarray a specified value of the valarray's element type.| -|[operator+](../standard-library/valarray-operators.md#op_add)|Obtains the element-wise sum between corresponding elements of two equally sized valarrays or of between a valarray a specified value of the valarray's element type.| -|[operator-](../standard-library/valarray-operators.md#operator-)|Obtains the element-wise difference between corresponding elements of two equally sized valarrays or of between a valarray a specified value of the valarray's element type.| -|[operator/](../standard-library/valarray-operators.md#op_div)|Obtains the element-wise quotient between corresponding elements of two equally sized valarrays or of between a valarray a specified value of the valarray's element type.| -|[operator==](../standard-library/valarray-operators.md#op_eq_eq)|Tests whether the corresponding elements of two equally sized valarrays are equal or whether all the elements of a valarray are equal a specified value of the valarray's element type.| -|[operator^](../standard-library/valarray-operators.md#op_xor)|Obtains the bitwise exclusive `OR` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type.| -|[operator|](../standard-library/valarray-operators.md#op_or)|Obtains the bitwise `OR` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the element type.| -|[operator||](../standard-library/valarray-operators.md#op_lor)|Obtains the logical `OR` between corresponding elements of two equally sized valarrays or between a valarray and a specified value of the valarray's element type.| +| Name | Description | +|--|--| +| [`operator!=`](../standard-library/valarray-operators.md#op_neq) | Tests whether the corresponding elements of two equally sized `valarray` objects are unequal or whether all the elements of a `valarray` are unequal to a specified value of the `valarray` object's element type. | +| [`operator%`](../standard-library/valarray-operators.md#op_mod) | Obtains the remainder of dividing the corresponding elements of two equally sized `valarray` objects or of dividing a `valarray` by a specified value of the `valarray` object's element type or of dividing a specified value by a `valarray`. | +| [`operator&`](../standard-library/valarray-operators.md#op_amp) | Obtains the bitwise AND between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the element type. | +| [`operator&&`](../standard-library/valarray-operators.md#op_amp_amp) | Obtains the logical AND between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the `valarray` object's element type. | +| [`operator>`](../standard-library/valarray-operators.md#op_gt) | Tests whether the elements of one `valarray` are greater than the elements of an equally sized `valarray` or whether all the elements of a `valarray` are greater or less than a specified value of the `valarray` object's element type. | +| [`operator>=`](../standard-library/valarray-operators.md#op_gt_eq) | Tests whether the elements of one `valarray` are greater than or equal to the elements of an equally sized `valarray` or whether all the elements of a `valarray` are greater than or equal to or less than or equal to a specified value. | +| [`operator>>`](../standard-library/valarray-operators.md#op_gt_gt) | Right-shifts the bits for each element of a `valarray` a specified number of positions or by an element-wise amount specified by a second `valarray`. | +| [`operator<`](../standard-library/valarray-operators.md#op_lt) | Tests whether the elements of one `valarray` are less than the elements of an equally sized `valarray` or whether all the elements of a `valarray` are greater or less than a specified value. | +| [`operator<=`](../standard-library/valarray-operators.md#op_lt_eq) | Tests whether the elements of one `valarray` are less than or equal to the elements of an equally sized `valarray` or whether all the elements of a `valarray` are greater than or equal to or less than or equal to a specified value. | +| [`operator<<`](../standard-library/valarray-operators.md#op_lt_lt) | Left shifts the bits for each element of a `valarray` a specified number of positions or by an element-wise amount specified by a second `valarray`. | +| [`operator*`](../standard-library/valarray-operators.md#op_star) | Obtains the element-wise product between corresponding elements of two equally sized `valarray` objects or of between a `valarray` a specified value of the `valarray` object's element type. | +| [`operator+`](../standard-library/valarray-operators.md#op_add) | Obtains the element-wise sum between corresponding elements of two equally sized `valarray` objects or of between a `valarray` a specified value of the `valarray` object's element type. | +| [`operator-`](../standard-library/valarray-operators.md#operator-) | Obtains the element-wise difference between corresponding elements of two equally sized `valarray` objects or of between a `valarray` a specified value of the `valarray` object's element type. | +| [`operator/`](../standard-library/valarray-operators.md#op_div) | Obtains the element-wise quotient between corresponding elements of two equally sized `valarray` objects or of between a `valarray` a specified value of the `valarray` object's element type. | +| [`operator==`](../standard-library/valarray-operators.md#op_eq_eq) | Tests whether the corresponding elements of two equally sized `valarray` objects are equal or whether all the elements of a `valarray` are equal a specified value of the `valarray` object's element type. | +| [`operator^`](../standard-library/valarray-operators.md#op_xor) | Obtains the bitwise exclusive OR between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the element type. | +| [`operator|`](../standard-library/valarray-operators.md#op_or) | Obtains the bitwise OR between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the element type. | +| [`operator||`](../standard-library/valarray-operators.md#op_lor) | Obtains the logical OR between corresponding elements of two equally sized `valarray` objects or between a `valarray` and a specified value of the `valarray` object's element type. | ### Classes -|Name|Description| -|-|-| -|[gslice Class](../standard-library/gslice-class.md)|A utility class to valarray that is used to define multi-dimensional slices of a valarray.| -|[gslice_array Class](../standard-library/gslice-array-class.md)|An internal, auxiliary class template that supports general slice objects by providing operations between subset arrays defined by the general slice of a valarray.| -|[indirect_array Class](../standard-library/indirect-array-class.md)|An internal, auxiliary class template that supports objects that are subsets of valarrays by providing operations between subset arrays defined by specifying a subset of indices of a parent valarray.| -|[mask_array Class](../standard-library/mask-array-class.md)|An internal, auxiliary class template that supports objects that are subsets of parent valarrays, specified with a Boolean expression, by providing operations between the subset arrays.| -|[slice Class](../standard-library/slice-class.md)|A utility class to valarray that is used to define one-dimensional, vector-like subsets of a valarray.| -|[slice_array Class](../standard-library/slice-array-class.md)|An internal, auxiliary class template that supports slice objects by providing operations between subset arrays defined by the slice of a valarray.| -|[valarray Class](../standard-library/valarray-class.md)|The class template describes an object that controls a sequence of elements of type `Type` that are stored as an array and designed for performing high-speed mathematical operations, optimized for computational performance.| +| Name | Description | +|--|--| +| [`gslice` class](../standard-library/gslice-class.md) | A utility class to `valarray` that is used to define multi-dimensional slices of a `valarray`. | +| [`gslice_array` class](../standard-library/gslice-array-class.md) | An internal, auxiliary class template that supports general slice objects by providing operations between subset arrays defined by the general slice of a `valarray`. | +| [`indirect_array` class](../standard-library/indirect-array-class.md) | An internal, auxiliary class template that supports objects that are subsets of `valarray` objects by providing operations between subset arrays defined by specifying a subset of indices of a parent `valarray`. | +| [`mask_array` class](../standard-library/mask-array-class.md) | An internal, auxiliary class template that supports objects that are subsets of parent `valarray` objects, specified with a Boolean expression, by providing operations between the subset arrays. | +| [`slice` class](../standard-library/slice-class.md) | A utility class to `valarray` that is used to define one-dimensional, vector-like subsets of a `valarray`. | +| [`slice_array` class](../standard-library/slice-array-class.md) | An internal, auxiliary class template that supports `slice` objects by providing operations between subset arrays defined by the slice of a `valarray`. | +| [`valarray` class](../standard-library/valarray-class.md) | The class template describes an object that controls a sequence of elements of type `Type` that are stored as an array and designed for high-speed mathematical operations, optimized for computational performance. | ### Specializations -|Name|Description| -|-|-| -|[valarray\ Class](../standard-library/valarray-bool-class.md)|A specialized version of the class template valarray\<**Type**> to elements of type **`bool`**.| +| Name | Description | +|--|--| +| [`valarray` class](../standard-library/valarray-bool-class.md) | A specialized version of the class template `valarray` for elements of type **`bool`**. | ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Header files reference](../standard-library/cpp-standard-library-header-files.md)\ +[Thread safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/values-view-class.md b/docs/standard-library/values-view-class.md new file mode 100644 index 0000000000..d069ff09e6 --- /dev/null +++ b/docs/standard-library/values-view-class.md @@ -0,0 +1,248 @@ +--- +title: values_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) values_view class, which provides a view over the second index into each tuple-like value in a collection. It's useful for extracting values from associative containers." +ms.date: 10/07/2022 +f1_keywords: ["ranges/std::values_view", "ranges/std::values_view::base", "ranges/std::values_view::begin", "ranges/std::values_view::empty", "ranges/std::values_view::end", "ranges/std::values_view::size", "ranges/std::values_view::operator bool", "ranges/std::values_view::back", "ranges/std::values_view::front", "ranges/std::values_view::operator[]"] +helpviewer_keywords: ["std::ranges::values_view [C++]", "std::ranges::values_view::base [C++]", "std::ranges::values_view::begin [C++]", "std::ranges::values_view::empty [C++]", "std::ranges::values_view::end [C++]", "std::ranges::values_view::size [C++]", "std::ranges::values_view::back [C++]", "std::ranges::values_view::front [C++]", "std::ranges::values_view::operator[] [C++]", "std::ranges::values_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `values_view` class (C++ Standard Library) + +A view consisting of the second index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view consisting of all the `int` elements from each tuple. + +`values_view` is an alias for `elements_view` and is useful for creating a view of the values in associative containers such as [`std::unordered_map`](unordered-map-class.md). + +## Syntax + +```cpp +template +using values_view = ranges::elements_view; +``` + +### Template parameters + +`R`\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::values`](range-adaptors.md#values) | +| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher | +| **Element type** | Same as the type of the second tuple element | +| **View iterator category** | `forward_range`, [`bidirectional_range`](range-concepts.md#bidirectional_range), or [`random_access_range`](range-concepts.md#random_access_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `values_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `values_view`. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `values_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `values_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +Tuple-like types that you can use with `values_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `values_view`. + +```cpp +1) constexpr values_view(R base); +2) values_view() requires default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range of tuple-like types. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +An `values_view` instance. + +### Remarks + +The best way to create an `values_view` is by using the [`values`](range-adaptors.md#values) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1) Create an `values_view` from the specified view. +2) The default constructor creates a default-constructed `values_view`. + +### Example: `values_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the values from the map + for (int years : std::views::values(cpp_standards)) + { + std::cout << years << ' '; // 2003 2011 2014 2017 1988 2020 + } + std::cout << '\n'; + + // ========== work with a std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor using '|': create a keys_view from each pair + for (int years : windows | std::views::values) + { + std::cout << years << ' '; // 1985 1987 1990 1992 ... + } +} +``` + +```output +2003 2011 2014 2017 1988 2020 +1985 1987 1990 1992 1993 1995 1996 1995 1998 1985 2000 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `values_view`. + +```cpp +// returns a non-const iterator +1) constexpr auto begin() requires (!Simple_view); + +// returns a const iterator +2) constexpr auto begin() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `values_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `values_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `values_view` + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `values_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`elements_view`](elements-view-class.md)\ +[`keys_view`](keys-view-class.md)\ +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/variant.md b/docs/standard-library/variant.md index a95acb0e76..9be7549e0e 100644 --- a/docs/standard-library/variant.md +++ b/docs/standard-library/variant.md @@ -7,7 +7,7 @@ helpviewer_keywords: [""] --- # `` -A variant object holds and manages a value. If the variant holds a value, that value’s type has to be one of the template argument types given to variant. These template arguments are called alternatives. +A variant object holds and manages a value. If the variant holds a value, that value's type has to be one of the template argument types given to variant. These template arguments are called alternatives. ## Requirements diff --git a/docs/standard-library/vector-bool-class.md b/docs/standard-library/vector-bool-class.md index ca5114a238..8756473a9e 100644 --- a/docs/standard-library/vector-bool-class.md +++ b/docs/standard-library/vector-bool-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: vector Class" title: "vector Class" -ms.date: "11/04/2016" +description: "Learn more about: vector Class" +ms.date: 11/04/2016 f1_keywords: ["vector", "vector/std::vector::flip"] helpviewer_keywords: ["std::vector [C++], const_pointer", "std::vector [C++], const_reference", "std::vector [C++], pointer", "std::vector [C++], flip", "std::vector [C++], swap"] -ms.assetid: 8028c8ed-ac9c-4f06-aba1-5de45c00aafb --- # `vector` Class -The `vector` class is a partial specialization of [vector](../standard-library/vector-class.md) for elements of type **`bool`**. It has an allocator for the underlying type that's used by the specialization, which provides space optimization by storing one **`bool`** value per bit. +The `vector` class is a partial specialization of [`vector`](../standard-library/vector-class.md) for elements of type **`bool`**. It has an allocator for the underlying type that's used by the specialization, which provides space optimization by storing one **`bool`** value per bit. ## Syntax @@ -19,42 +18,42 @@ class vector ## Remarks -This class template specialization behaves like vector, except for the differences explained in this article. +This class template specialization behaves like `vector`, except for the differences explained in this article. -Operations that deal with the **`bool`** type correspond to values in the container storage. `allocator_traits::construct` is not used to construct these values. +Operations that deal with the **`bool`** type correspond to values in the container storage. `allocator_traits::construct` isn't used to construct these values. ### Typedefs |Type name|Description| |-|-| -|[const_pointer](#const_pointer)|A typedef to a `const_iterator` that can serve as a constant pointer to a Boolean element of the `vector`.| -|[const_reference](#const_reference)|A typedef for **`bool`**. After initialization, it does not observe updates to the original value.| -|[pointer](#pointer)|A typedef to an `iterator` that can serve as a pointer to a Boolean element of the `vector`.| +|[`const_pointer`](#const_pointer)|A typedef to a `const_iterator` that can serve as a constant pointer to a Boolean element of the `vector`.| +|[`const_reference`](#const_reference)|A typedef for **`bool`**. After initialization, it doesn't observe updates to the original value.| +|[`pointer`](#pointer)|A typedef to an `iterator` that can serve as a pointer to a Boolean element of the `vector`.| ### Member functions |Member function|Description| |-|-| -|[flip](#flip)|Reverses all bits in the `vector`.| -|[swap](#swap)|Exchanges the elements of two `vector`s.| +|[`flip`](#flip)|Reverses all bits in the `vector`.| +|[`swap`](#swap)|Exchanges the elements of two `vector`s.| |[`operator[]`](#op_at)|Returns a simulated reference to the `vector` element at a specified position.| -|`at`|Functions the same as the unspecialized [vector](../standard-library/vector-class.md)::at function, except that it uses the proxy class [vector\::reference](#reference_class). Also see [`operator[]`](#op_at).| -|`front`|Functions the same as the unspecialized [vector](../standard-library/vector-class.md)::front function, except that it uses the proxy class [vector\::reference](#reference_class). Also see [`operator[]`](#op_at).| -|`back`|Functions the same as the unspecialized [vector](../standard-library/vector-class.md)::back function, except that it uses the proxy class [vector\::reference](#reference_class). Also see [`operator[]`](#op_at).| +|`at`|Functions the same as the unspecialized [`vector`](../standard-library/vector-class.md)::at function, except that it uses the proxy class [`vector::reference`](#reference_class). Also see [`operator[]`](#op_at).| +|`front`|Functions the same as the unspecialized [`vector`](../standard-library/vector-class.md)::front function, except that it uses the proxy class [`vector::reference`](#reference_class). Also see [`operator[]`](#op_at).| +|`back`|Functions the same as the unspecialized [`vector`](../standard-library/vector-class.md)::back function, except that it uses the proxy class [`vector::reference`](#reference_class). Also see [`operator[]`](#op_at).| ### Proxy Class |Name|Description| |-|-| -|[vector\ reference Class](#reference_class)|A class that acts as a proxy to simulate `bool&` behavior, and whose objects can provide references to elements (single bits) within a `vector` object.| +|[`vector::reference` Class](#reference_class)|A class that acts as a proxy to simulate `bool&` behavior, and whose objects can provide references to elements (single bits) within a `vector` object.| ## Requirements -**Header**: \ +**Header**: `` -**Namespace:** std +**Namespace:** `std` -## vector\::const_pointer +## `vector::const_pointer` A type that describes an object that can serve as a constant pointer to a Boolean element of the sequence contained by the `vector` object. @@ -62,7 +61,7 @@ A type that describes an object that can serve as a constant pointer to a Boolea typedef const_iterator const_pointer; ``` -## vector\::const_reference +## `vector::const_reference` A type that describes an object that can serve as a constant reference to a Boolean element of the sequence contained by the `vector` object. @@ -74,7 +73,7 @@ typedef bool const_reference; For more information and code examples, see [`vector::reference::operator=`](#reference_operator_eq). -## vector\::flip +## `vector::flip` Reverses all bits in a `vector`. @@ -112,7 +111,7 @@ int main() } ``` -## vector\::operator[] +## `vector::operator[]` Returns a simulated reference to the `vector` element at a specified position. @@ -124,22 +123,22 @@ vector&::const_reference operator[](size_type Pos) const; ### Parameters -*Pos*\ +*`Pos`*\ The position of the `vector` element. ### Return Value -A [vector\::reference](#reference_class) or [vector\::const_reference](#const_reference) object that contains the value of the indexed element. +A [`vector::reference`](#reference_class) or [`vector::const_reference`](#const_reference) object that contains the value of the indexed element. If the position specified is greater than or equal to the size of the container, the result is undefined. ### Remarks -If you compile with _ITERATOR_DEBUG_LEVEL set, a run-time error occurs if you attempt to access an element outside the bounds of the vector. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). +If you compile with `_ITERATOR_DEBUG_LEVEL` set, a run-time error occurs if you attempt to access an element outside the bounds of the vector. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). ### Example -This code example shows the correct use of `vector::operator[]` and two common coding mistakes, which are commented out. These mistakes cause errors because the address of the `vector::reference` object that `vector::operator[]` returns cannot be taken. +This code example shows the correct use of `vector::operator[]` and two common coding mistakes, which are commented out. These mistakes cause errors because the address of the `vector::reference` object that `vector::operator[]` returns can't be taken. ```cpp // cl.exe /EHsc /nologo /W4 /MTd @@ -168,7 +167,14 @@ int main() } ``` -## vector\::pointer +```Output +The second element of vb is false +The held value from the second element of vb is false +The second element of vb is true +The held value from the second element of vb is false +``` + +## `vector::pointer` A type that describes an object that can serve as a pointer to a Boolean element of the sequence contained by the `vector` object. @@ -176,13 +182,13 @@ A type that describes an object that can serve as a pointer to a Boolean element typedef iterator pointer; ``` -## vector\::reference Class +## `vector::reference` Class -The `vector::reference` class is a proxy class provided by the [vector\ Class](../standard-library/vector-bool-class.md) to simulate `bool&`. +The `vector::reference` class is a proxy class provided by the [`vector` Class](../standard-library/vector-bool-class.md) to simulate `bool&`. ### Remarks -A simulated reference is required because C++ does not natively allow direct references to bits. `vector` uses only one bit per element, which can be referenced by using this proxy class. However, the reference simulation is not complete because certain assignments are not valid. For example, because the address of the `vector::reference` object cannot be taken, the following code that uses [`vector::operator[]`](#op_at) is not correct: +A simulated reference is required because C++ doesn't natively allow direct references to bits. `vector` uses only one bit per element, which can be referenced by using this proxy class. However, the reference simulation isn't complete because certain assignments aren't valid. For example, because the address of the `vector::reference` object can't be taken, the following code that uses [`vector::operator[]`](#op_at) isn't correct: ```cpp vector vb; @@ -191,9 +197,9 @@ bool* pb = &vb[1]; // conversion error - do not use bool& refb = vb[1]; // conversion error - do not use ``` -### vector\::reference::flip +### `vector::reference::flip` -Inverts the Boolean value of a referenced [vector\](../standard-library/vector-bool-class.md) element. +Inverts the Boolean value of a referenced [`vector`](../standard-library/vector-bool-class.md) element. ```cpp void flip(); @@ -238,7 +244,7 @@ The vector with first element flipped is: false false false true true ``` -### vector\::reference::operator bool +### `vector::reference::operator bool` Provides an implicit conversion from `vector::reference` to **`bool`**. @@ -248,13 +254,13 @@ operator bool() const; #### Return Value -The Boolean value of the element of the vector\ object. +The Boolean value of the element of the `vector` object. #### Remarks -The `vector` object cannot be modified by this operator. +The `vector` object can't be modified by this operator. -### vector\::reference::operator= +### `vector::reference::operator=` Assigns a Boolean value to a bit, or the value held by a referenced element to a bit. @@ -265,10 +271,10 @@ reference& operator=(bool Val); ### Parameters -*Right*\ +*`Right`*\ The element reference whose value is to be assigned to the bit. -*Val*\ +*`Val`*\ The Boolean value to be assigned to the bit. #### Example @@ -342,9 +348,9 @@ The original value of the 2nd element still stored in a bool: false The original value of the 3rd element still stored in a bool: false ``` -## vector\::swap +## `vector::swap` -Static member function that exchanges two elements of Boolean vectors ( `vector`) by using the proxy class [vector\::reference](#reference_class). +Static member function that exchanges two elements of Boolean vectors (`vector`) by using the proxy class [`vector::reference`](#reference_class). ```cpp static void swap( @@ -354,15 +360,15 @@ static void swap( ### Parameters -*Left*\ -The element to be exchanged with the *Right* element. +*`Left`*\ +The element to be exchanged with the *`Right`* element. -*Right*\ -The element to be exchanged with the *Left* element. +*`Right`*\ +The element to be exchanged with the *`Left`* element. ### Remarks -This overload supports the special proxy requirements of `vector`. [vector](../standard-library/vector-class.md)::swap has the same functionality as the single-argument overload of `vector::swap()`. +This overload supports the special proxy requirements of `vector`. [`vector`](../standard-library/vector-class.md)::swap has the same functionality as the single-argument overload of `vector::swap()`. ## See also diff --git a/docs/standard-library/vector-class.md b/docs/standard-library/vector-class.md index 94f797a361..e715fe2ee4 100644 --- a/docs/standard-library/vector-class.md +++ b/docs/standard-library/vector-class.md @@ -1,7 +1,7 @@ --- title: "vector class" description: "Reference for Microsoft C++ Standard library implementation of class vector." -ms.date: "02/23/2021" +ms.date: "08/25/2023" f1_keywords: ["vector/std::vector::allocator_type", "vector/std::vector::const_iterator", "vector/std::vector::const_pointer", "vector/std::vector::const_reference", "vector/std::vector::const_reverse_iterator", "vector/std::vector::difference_type", "vector/std::vector::iterator", "vector/std::vector::pointer", "vector/std::vector::reference", "vector/std::vector::reverse_iterator", "vector/std::vector::size_type", "vector/std::vector::value_type", "vector/std::vector::assign", "vector/std::vector::at", "vector/std::vector::back", "vector/std::vector::begin", "vector/std::vector::capacity", "vector/std::vector::cbegin", "vector/std::vector::cend", "vector/std::vector::crbegin", "vector/std::vector::crend", "vector/std::vector::clear", "vector/std::vector::data", "vector/std::vector::emplace", "vector/std::vector::emplace_back", "vector/std::vector::empty", "vector/std::vector::end", "vector/std::vector::erase", "vector/std::vector::front", "vector/std::vector::get_allocator", "vector/std::vector::insert", "vector/std::vector::max_size", "vector/std::vector::pop_back", "vector/std::vector::push_back", "vector/std::vector::rbegin", "vector/std::vector::rend", "vector/std::vector::reserve", "vector/std::vector::resize", "vector/std::vector::shrink_to_fit", "vector/std::vector::size", "vector/std::vector::swap"] helpviewer_keywords: ["std::vector [C++], allocator_type", "std::vector [C++], const_iterator", "std::vector [C++], const_pointer", "std::vector [C++], const_reference", "std::vector [C++], const_reverse_iterator", "std::vector [C++], difference_type", "std::vector [C++], iterator", "std::vector [C++], pointer", "std::vector [C++], reference", "std::vector [C++], reverse_iterator", "std::vector [C++], size_type", "std::vector [C++], value_type", "std::vector [C++], assign", "std::vector [C++], at", "std::vector [C++], back", "std::vector [C++], begin", "std::vector [C++], capacity", "std::vector [C++], cbegin", "std::vector [C++], cend", "std::vector [C++], crbegin", "std::vector [C++], crend", "std::vector [C++], clear", "std::vector [C++], data", "std::vector [C++], emplace", "std::vector [C++], emplace_back", "std::vector [C++], empty", "std::vector [C++], end", "std::vector [C++], erase", "std::vector [C++], front", "std::vector [C++], get_allocator", "std::vector [C++], insert", "std::vector [C++], max_size", "std::vector [C++], pop_back", "std::vector [C++], push_back", "std::vector [C++], rbegin", "std::vector [C++], rend", "std::vector [C++], reserve", "std::vector [C++], resize", "std::vector [C++], shrink_to_fit", "std::vector [C++], size", "std::vector [C++], swap"] --- @@ -13,13 +13,13 @@ The C++ Standard Library vector class is a class template for sequence container ```cpp template > -class vector +class vector; ``` ### Parameters *`Type`*\ -The element data type to be stored in the vector +The element data type to be stored in the vector. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the vector's allocation and deallocation of memory. This argument is optional and the default value is `allocator`. @@ -46,7 +46,7 @@ The [`vector` reference class](../standard-library/vector-bool-class.md#re |Name|Description| |-|-| -|`[allocator_type]`(#allocator_type)|A type that represents the `allocator` class for the vector object.| +|[`allocator_type`](#allocator_type)|A type that represents the `allocator` class for the vector object.| |[`const_iterator`](#const_iterator)|A type that provides a random-access iterator that can read a **`const`** element in a vector.| |[`const_pointer`](#const_pointer)|A type that provides a pointer to a **`const`** element in a vector.| |[`const_reference`](#const_reference)|A type that provides a reference to a **`const`** element stored in a vector. It's used for reading and doing **`const`** operations.| @@ -114,7 +114,7 @@ typedef Allocator allocator_type; ### Example -See the example for [get_allocator](#get_allocator) for an example that uses `allocator_type`. +See the example for [`get_allocator`](#get_allocator) for an example that uses `allocator_type`. ## `assign` @@ -152,7 +152,7 @@ First, `assign` erases any existing elements in a vector. Then, `assign` either ### Example ```cpp -/ vector_assign.cpp +// vector_assign.cpp // compile with: /EHsc #include #include @@ -169,33 +169,45 @@ int main() v1.push_back(50); cout << "v1 = "; - for (auto& v : v1){ + for (auto& v : v1) + { cout << v << " "; } cout << endl; v2.assign(v1.begin(), v1.end()); cout << "v2 = "; - for (auto& v : v2){ + for (auto& v : v2) + { cout << v << " "; } cout << endl; v3.assign(7, 4); cout << "v3 = "; - for (auto& v : v3){ + for (auto& v : v3) + { cout << v << " "; } cout << endl; v3.assign({ 5, 6, 7 }); - for (auto& v : v3){ + cout << "v3 = "; + for (auto& v : v3) + { cout << v << " "; } cout << endl; } ``` +```Output +v1 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +v3 = 4 4 4 4 4 4 4 +v3 = 5 6 7 +``` + ## `at` Returns a reference to the element at a specified location in the vector. @@ -227,18 +239,18 @@ If the return value of `at` is assigned to a `const_reference`, the vector objec #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - const int &i = v1.at( 0 ); - int &j = v1.at( 1 ); - cout << "The first element is " << i << endl; - cout << "The second element is " << j << endl; + const int &i = v1.at(0); + int &j = v1.at(1); + cout << "The first element is " << i << endl; + cout << "The second element is " << j << endl; } ``` @@ -275,22 +287,28 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main() { - using namespace std; - vector v1; +int main() +{ + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 11 ); + v1.push_back(10); + v1.push_back(11); - int& i = v1.back( ); - const int& ii = v1.front( ); + int& i = v1.back(); + const int& ii = v1.front(); - cout << "The last integer of v1 is " << i << endl; - i--; - cout << "The next-to-last integer of v1 is "<< ii << endl; + cout << "The last integer of v1 is " << i << endl; + i--; + cout << "The next-to-last integer of v1 is " << ii << endl; } ``` +```Output +The last integer of v1 is 11 +The next-to-last integer of v1 is 10 +``` + ## `begin` Returns a random-access iterator to the first element in the vector. @@ -378,18 +396,18 @@ The member function [`resize`](#resize) will be more efficient if sufficient mem #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 1 ); - cout << "The length of storage allocated is " - << v1.capacity( ) << "." << endl; + v1.push_back(1); + cout << "The length of storage allocated is " + << v1.capacity() << "." << endl; - v1.push_back( 2 ); - cout << "The length of storage allocated is now " - << v1.capacity( ) << "." << endl; + v1.push_back(2); + cout << "The length of storage allocated is now " + << v1.capacity() << "." << endl; } ``` @@ -419,8 +437,8 @@ You can use this member function in place of the `begin()` member function to gu ```cpp auto i1 = Container.begin(); // i1 is Container::iterator -auto i2 = Container.cbegin(); +auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` @@ -445,8 +463,8 @@ You can use this member function in place of the `end()` member function to guar ```cpp auto i1 = Container.end(); // i1 is Container::iterator -auto i2 = Container.cend(); +auto i2 = Container.cend(); // i2 is Container::const_iterator ``` @@ -468,18 +486,18 @@ void clear(); #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); - cout << "The size of v1 is " << v1.size( ) << endl; - v1.clear( ); - cout << "The size of v1 after clearing is " << v1.size( ) << endl; + cout << "The size of v1 is " << v1.size() << endl; + v1.clear(); + cout << "The size of v1 after clearing is " << v1.size() << endl; } ``` @@ -538,22 +556,22 @@ A type `const_reference` can't be used to modify the value of an element. #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - const vector v2 = v1; - const int &i = v2.front( ); - const int &j = v2.back( ); - cout << "The first element is " << i << endl; - cout << "The second element is " << j << endl; + const vector v2 = v1; + const int& i = v2.front(); + const int& j = v2.back(); + cout << "The first element is " << i << endl; + cout << "The second element is " << j << endl; - // The following line would cause an error as v2 is const - // v2.push_back( 30 ); + // The following line would cause an error as v2 is const + // v2.push_back(30); } ``` @@ -602,22 +620,22 @@ With the return value of `crbegin`, the `vector` object can't be modified. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; - vector ::const_reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::iterator v1_Iter; + vector::const_reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - v1_Iter = v1.begin( ); - cout << "The first element of vector is " + v1_Iter = v1.begin(); + cout << "The first element of vector is " << *v1_Iter << "." << endl; - v1_rIter = v1.crbegin( ); - cout << "The first element of the reversed vector is " + v1_rIter = v1.crbegin(); + cout << "The first element of the reversed vector is " << *v1_rIter << "." << endl; } ``` @@ -657,17 +675,17 @@ The value returned by `crend` shouldn't be dereferenced. Only use it for compari #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::const_reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::const_reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_rIter = v1.rbegin( ) ; v1_rIter != v1.rend( ) ; v1_rIter++ ) - cout << *v1_rIter << endl; + for (v1_rIter = v1.rbegin(); v1_rIter != v1.rend(); v1_rIter++) + cout << *v1_rIter << endl; } ``` @@ -755,31 +773,31 @@ An [iterator](#iterator) is more commonly used to access a vector element. #include #include -int main( ) +int main() { - using namespace std; + using namespace std; - vector c1; - vector ::iterator c1_Iter, c2_Iter; + vector c1; + vector::iterator c1_Iter, c2_Iter; - c1.push_back( 30 ); - c1.push_back( 20 ); - c1.push_back( 30 ); - c1.push_back( 10 ); - c1.push_back( 30 ); - c1.push_back( 20 ); + c1.push_back(30); + c1.push_back(20); + c1.push_back(30); + c1.push_back(10); + c1.push_back(30); + c1.push_back(20); - c1_Iter = c1.begin( ); - c2_Iter = c1.end( ); + c1_Iter = c1.begin(); + c2_Iter = c1.end(); - vector ::difference_type df_typ1, df_typ2, df_typ3; + vector::difference_type df_typ1, df_typ2, df_typ3; - df_typ1 = count( c1_Iter, c2_Iter, 10 ); - df_typ2 = count( c1_Iter, c2_Iter, 20 ); - df_typ3 = count( c1_Iter, c2_Iter, 30 ); - cout << "The number '10' is in c1 collection " << df_typ1 << " times.\n"; - cout << "The number '20' is in c1 collection " << df_typ2 << " times.\n"; - cout << "The number '30' is in c1 collection " << df_typ3 << " times.\n"; + df_typ1 = count(c1_Iter, c2_Iter, 10); + df_typ2 = count(c1_Iter, c2_Iter, 20); + df_typ3 = count(c1_Iter, c2_Iter, 30); + cout << "The number '10' is in c1 collection " << df_typ1 << " times.\n"; + cout << "The number '20' is in c1 collection " << df_typ2 << " times.\n"; + cout << "The number '30' is in c1 collection " << df_typ3 << " times.\n"; } ``` @@ -824,32 +842,32 @@ Any insertion operation can be expensive, see [`vector` class](../standard-libra #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - -// initialize a vector of vectors by moving v1 - vector < vector > vv1; - - vv1.emplace( vv1.begin(), move( v1 ) ); - if ( vv1.size( ) != 0 && vv1[0].size( ) != 0 ) - { - cout << "vv1[0] ="; - for (Iter = vv1[0].begin( ); Iter != vv1[0].end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - } + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + // initialize a vector of vectors by moving v1 + vector> vv1; + + vv1.emplace(vv1.begin(), move(v1)); + if (vv1.size() != 0 && vv1[0].size() != 0) + { + cout << "vv1[0] ="; + for (Iter = vv1[0].begin(); Iter != vv1[0].end(); Iter++) + cout << " " << *Iter; + cout << endl; + } } ``` @@ -876,15 +894,16 @@ Constructor arguments. The function infers which constructor overload to invoke ```cpp #include + struct obj { - obj(int, double) {} + obj(int, double) {} }; int main() { - std::vector v; - v.emplace_back(1, 3.14); // obj in created in place in the vector + std::vector v; + v.emplace_back(1, 3.14); // obj in created in place in the vector } ``` @@ -908,17 +927,17 @@ bool empty() const; #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); + v1.push_back(10); - if ( v1.empty( ) ) - cout << "The vector is empty." << endl; - else - cout << "The vector is not empty." << endl; + if (v1.empty()) + cout << "The vector is empty." << endl; + else + cout << "The vector is not empty." << endl; } ``` @@ -951,17 +970,18 @@ If the return value of `end` is assigned to a variable of type `const_iterator`, // compile with: /EHsc #include #include -int main( ) + +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; + using namespace std; + vector v1; + vector::iterator v1_Iter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_Iter = v1.begin( ) ; v1_Iter != v1.end( ) ; v1_Iter++ ) - cout << *v1_Iter << endl; + for (v1_Iter = v1.begin(); v1_Iter != v1.end(); v1_Iter++) + cout << *v1_Iter << endl; } ``` @@ -1006,34 +1026,34 @@ An iterator that designates the first element remaining beyond any elements remo #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - v1.push_back( 40 ); - v1.push_back( 50 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.erase( v1.begin( ) ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.erase( v1.begin( ) + 1, v1.begin( ) + 3 ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + v1.push_back(40); + v1.push_back(50); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.erase(v1.begin()); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.erase(v1.begin() + 1, v1.begin() + 3); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; } ``` @@ -1071,24 +1091,28 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 11 ); + v1.push_back(10); + v1.push_back(11); - int& i = v1.front( ); - const int& ii = v1.front( ); + int& i = v1.front(); - cout << "The first integer of v1 is "<< i << endl; - // by incrementing i, we move the front reference to the second element - i++; - cout << "Now, the first integer of v1 is "<< i << endl; + cout << "The first integer of v1 is " << i << endl; + // by incrementing i, we move the front reference to the second element + i++; + cout << "Now, the first integer of v1 is " << i << endl; } ``` +```Output +The first integer of v1 is 10 +Now, the first integer of v1 is 11 +``` + ## `get_allocator` Returns a copy of the allocator object used to construct the vector. @@ -1111,20 +1135,19 @@ Allocators for the vector class specify how the class manages storage. The defau // vector_get_allocator.cpp // compile with: /EHsc #include -#include -int main( ) +int main() { - using namespace std; - // The following lines declare objects that use the default allocator. - vector v1; - vector > v2 = vector >(allocator( )) ; + using namespace std; + // The following lines declare objects that use the default allocator. + vector v1; + vector> v2 = vector>(allocator()); - // v3 will use the same allocator class as v1 - vector v3( v1.get_allocator( ) ); + // v3 will use the same allocator class as v1 + vector v3(v1.get_allocator()); - vector::allocator_type xvec = v3.get_allocator( ); - // You can now call functions on the allocator class used by vec + vector::allocator_type xvec = v3.get_allocator(); + // You can now call functions on the allocator class used by vec } ``` @@ -1186,51 +1209,51 @@ As a precondition, *`first`* and *`last`* must not be iterators into the vector, #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.insert( v1.begin( ) + 1, 40 ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - v1.insert( v1.begin( ) + 2, 4, 50 ); - - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - const auto v2 = v1; - v1.insert( v1.begin( )+1, v2.begin( )+2, v2.begin( )+4 ); - cout << "v1 ="; - for (Iter = v1.begin( ); Iter != v1.end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - -// initialize a vector of vectors by moving v1 - vector < vector > vv1; - - vv1.insert( vv1.begin(), move( v1 ) ); - if ( vv1.size( ) != 0 && vv1[0].size( ) != 0 ) - { - cout << "vv1[0] ="; - for (Iter = vv1[0].begin( ); Iter != vv1[0].end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - } + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.insert(v1.begin() + 1, 40); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + v1.insert(v1.begin() + 2, 4, 50); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + const auto v2 = v1; + v1.insert(v1.begin() + 1, v2.begin() + 2, v2.begin() + 4); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + // initialize a vector of vectors by moving v1 + vector> vv1; + + vv1.insert(vv1.begin(), move(v1)); + if (vv1.size() != 0 && vv1[0].size() != 0) + { + cout << "vv1[0] ="; + for (Iter = vv1[0].begin(); Iter != vv1[0].end(); Iter++) + cout << " " << *Iter; + cout << endl; + } } ``` @@ -1278,17 +1301,21 @@ The maximum possible length of the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::size_type i; + using namespace std; + vector v1; + vector::size_type i; - i = v1.max_size( ); - cout << "The maximum possible length of the vector is " << i << "." << endl; + i = v1.max_size(); + cout << "The maximum possible length of the vector is " << i << "." << endl; } ``` +```Output +The maximum possible length of the vector is 4611686018427387903. +``` + ## `operator[]` Returns a reference to the vector element at a specified position. @@ -1322,19 +1349,23 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - int& i = v1[1]; - cout << "The second integer of v1 is " << i << endl; + int& i = v1[1]; + cout << "The second integer of v1 is " << i << endl; } ``` +```Output +The second integer of v1 is 20 +``` + ## `operator=` Replaces the elements of the vector with a copy of another vector. @@ -1362,39 +1393,45 @@ After erasing any existing elements in a `vector`, `operator=` either copies or #include #include -int main( ) +int main() { - using namespace std; - vector v1, v2, v3; - vector::iterator iter; - - v1.push_back(10); - v1.push_back(20); - v1.push_back(30); - v1.push_back(40); - v1.push_back(50); - - cout << "v1 = " ; - for (iter = v1.begin(); iter != v1.end(); iter++) - cout << *iter << " "; - cout << endl; - - v2 = v1; - cout << "v2 = "; - for (iter = v2.begin(); iter != v2.end(); iter++) - cout << *iter << " "; - cout << endl; - -// move v1 into v2 - v2.clear(); - v2 = move(v1); - cout << "v2 = "; - for (iter = v2.begin(); iter != v2.end(); iter++) - cout << *iter << " "; - cout << endl; + using namespace std; + vector v1, v2, v3; + vector::iterator iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + v1.push_back(40); + v1.push_back(50); + + cout << "v1 = "; + for (iter = v1.begin(); iter != v1.end(); iter++) + cout << *iter << " "; + cout << endl; + + v2 = v1; + cout << "v2 = "; + for (iter = v2.begin(); iter != v2.end(); iter++) + cout << *iter << " "; + cout << endl; + + // move v1 into v2 + v2.clear(); + v2 = move(v1); + cout << "v2 = "; + for (iter = v2.begin(); iter != v2.end(); iter++) + cout << *iter << " "; + cout << endl; } ``` +```Output +v1 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +``` + ## `pointer` A type that provides a pointer to an element in a vector. @@ -1415,12 +1452,12 @@ A type **`pointer`** can be used to modify the value of an element. #include #include -int main( ) +int main() { using namespace std; vector v; - v.push_back( 11 ); - v.push_back( 22 ); + v.push_back(11); + v.push_back(22); vector::pointer ptr = &v[0]; cout << *ptr << endl; @@ -1473,14 +1510,19 @@ The value to assign to the element added to the end of the vector. using namespace std; -template void print_elem(const T& t) { +template +void print_elem(const T& t) +{ cout << "(" << t << ") "; } -template void print_collection(const T& t) { +template +void print_collection(const T& t) +{ cout << " " << t.size() << " elements: "; - for (const auto& p : t) { + for (const auto& p : t) + { print_elem(p); } cout << endl; @@ -1489,7 +1531,8 @@ template void print_collection(const T& t) { int main() { vector v; - for (int i = 0; i < 10; ++i) { + for (int i = 0; i < 10; ++i) + { v.push_back(10 + i); } @@ -1497,13 +1540,31 @@ int main() print_collection(v); // pop_back() until it's empty, printing the last element as we go - while (v.begin() != v.end()) { - cout << "v.back(): "; print_elem(v.back()); cout << endl; + while (v.begin() != v.end()) + { + cout << "v.back(): "; + print_elem(v.back()); + cout << endl; v.pop_back(); } } ``` +```Output +vector data: + 10 elements: (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) +v.back(): (19) +v.back(): (18) +v.back(): (17) +v.back(): (16) +v.back(): (15) +v.back(): (14) +v.back(): (13) +v.back(): (12) +v.back(): (11) +v.back(): (10) +``` + ## `rbegin` Returns an iterator to the first element in a reversed vector. @@ -1529,22 +1590,22 @@ If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the v #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; - vector ::reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::iterator v1_Iter; + vector::reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - v1_Iter = v1.begin( ); - cout << "The first element of vector is " + v1_Iter = v1.begin(); + cout << "The first element of vector is " << *v1_Iter << "." << endl; - v1_rIter = v1.rbegin( ); - cout << "The first element of the reversed vector is " + v1_rIter = v1.rbegin(); + cout << "The first element of the reversed vector is " << *v1_rIter << "." << endl; } ``` @@ -1597,17 +1658,17 @@ The value returned by `rend` shouldn't be dereferenced. Only use it for comparis #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_rIter = v1.rbegin( ) ; v1_rIter != v1.rend( ) ; v1_rIter++ ) - cout << *v1_rIter << endl; + for (v1_rIter = v1.rbegin(); v1_rIter != v1.rend(); v1_rIter++) + cout << *v1_rIter << endl; } ``` @@ -1637,18 +1698,17 @@ The minimum length of storage to be allocated for the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - //vector ::iterator Iter; - - v1.push_back( 1 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.reserve( 20 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; + using namespace std; + vector v1; + + v1.push_back(1); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.reserve(20); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; } ``` @@ -1721,16 +1781,20 @@ If the container's size is less than the requested size, *`new_size`*, `resize` using namespace std; -template void print(const string& s, const C& c) { +template +void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } cout << endl; } -void printvstats(const vector& v) { +void printvstats(const vector& v) +{ cout << " the vector's size is: " << v.size() << endl; cout << " the vector's capacity is: " << v.capacity() << endl; cout << " the vector's maximum size is: " << v.max_size() << endl; @@ -1742,7 +1806,7 @@ int main() vector v; // Show statistics about vector. - cout << endl << "After declaring an empty vector:" << endl; + cout << "After declaring an empty vector:" << endl; printvstats(v); print(" the vector's contents: ", v); @@ -1752,7 +1816,8 @@ int main() printvstats(v); print(" the vector's contents: ", v); - for (int i = 1; i < 10; ++i) { + for (int i = 1; i < 10; ++i) + { v.push_back(i); } cout << endl << "After adding 10 elements:" << endl; @@ -1786,6 +1851,54 @@ int main() } ``` +```Output +After declaring an empty vector: + the vector's size is: 0 + the vector's capacity is: 0 + the vector's maximum size is: 4611686018427387903 + the vector's contents: + +After adding an element: + the vector's size is: 1 + the vector's capacity is: 1 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 + +After adding 10 elements: + the vector's size is: 10 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 6 7 8 9 + +After resizing to 6 elements without an initialization value: + the vector's size is: 6 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 + +After resizing to 9 elements with an initialization value of 999: + the vector's size is: 9 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 999 999 999 + +After resizing to 12 elements without an initialization value: + the vector's size is: 12 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 999 999 999 0 0 0 + +After vector::reserve(1000): + the vector's size is: 12 + the vector's capacity is: 1000 + the vector's maximum size is: 4611686018427387903 + +After vector::resize(2000): + the vector's size is: 2000 + the vector's capacity is: 2000 + the vector's maximum size is: 4611686018427387903 +``` + ## `reverse_iterator` A type that provides a random-access iterator that can read or modify any element in a reversed vector. @@ -1818,21 +1931,20 @@ void shrink_to_fit(); #include #include -int main( ) +int main() { - using namespace std; - vector v1; - //vector ::iterator Iter; - - v1.push_back( 1 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.reserve( 20 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.shrink_to_fit(); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; + using namespace std; + vector v1; + + v1.push_back(1); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.reserve(20); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.shrink_to_fit(); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; } ``` @@ -1862,19 +1974,19 @@ The current length of the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::size_type i; + using namespace std; + vector v1; + vector::size_type i; - v1.push_back( 1 ); - i = v1.size( ); - cout << "Vector length is " << i << "." << endl; + v1.push_back(1); + i = v1.size(); + cout << "Vector length is " << i << "." << endl; - v1.push_back( 2 ); - i = v1.size( ); - cout << "Vector length is now " << i << "." << endl; + v1.push_back(2); + i = v1.size(); + cout << "Vector length is now " << i << "." << endl; } ``` @@ -1924,26 +2036,26 @@ A vector whose elements are to be exchanged with the elements in the vector *`ri #include #include -int main( ) +int main() { - using namespace std; - vector v1, v2; + using namespace std; + vector v1, v2; - v1.push_back( 1 ); - v1.push_back( 2 ); - v1.push_back( 3 ); + v1.push_back(1); + v1.push_back(2); + v1.push_back(3); - v2.push_back( 10 ); - v2.push_back( 20 ); + v2.push_back(10); + v2.push_back(20); - cout << "The number of elements in v1 = " << v1.size( ) << endl; - cout << "The number of elements in v2 = " << v2.size( ) << endl; - cout << endl; + cout << "The number of elements in v1 = " << v1.size() << endl; + cout << "The number of elements in v2 = " << v2.size() << endl; + cout << endl; - v1.swap( v2 ); + v1.swap(v2); - cout << "The number of elements in v1 = " << v1.size( ) << endl; - cout << "The number of elements in v2 = " << v2.size( ) << endl; + cout << "The number of elements in v1 = " << v1.size() << endl; + cout << "The number of elements in v2 = " << v2.size() << endl; } ``` @@ -1975,12 +2087,12 @@ typedef typename Allocator::value_type value_type; #include #include -int main( ) +int main() { - using namespace std; - vector::value_type AnInt; - AnInt = 44; - cout << AnInt << endl; + using namespace std; + vector::value_type AnInt; + AnInt = 44; + cout << AnInt << endl; } ``` @@ -2061,88 +2173,106 @@ The ninth and tenth constructors copy the range [`first`, `last`) of a vector. int main() { using namespace std; - vector ::iterator v1_Iter, v2_Iter, v3_Iter, v4_Iter, v5_Iter, v6_Iter; + vector::iterator v1_Iter, v2_Iter, v3_Iter, v4_Iter, v5_Iter, v6_Iter; // Create an empty vector v0 - vector v0; + vector v0; // Create a vector v1 with 3 elements of default value 0 - vector v1(3); + vector v1(3); // Create a vector v2 with 5 elements of value 2 - vector v2(5, 2); + vector v2(5, 2); // Create a vector v3 with 3 elements of value 1 and with the allocator // of vector v2 - vector v3(3, 1, v2.get_allocator()); + vector v3(3, 1, v2.get_allocator()); // Create a copy, vector v4, of vector v2 - vector v4(v2); + vector v4(v2); // Create a new temporary vector for demonstrating copying ranges - vector v5(5); - for (auto i : v5) { + vector v5(5); + for (auto i : v5) + { v5[i] = i; } // Create a vector v6 by copying the range v5[ first, last) - vector v6(v5.begin() + 1, v5.begin() + 3); + vector v6(v5.begin() + 1, v5.begin() + 3); cout << "v1 ="; - for (auto& v : v1){ + for (auto& v : v1) + { cout << " " << v; } cout << endl; cout << "v2 ="; - for (auto& v : v2){ + for (auto& v : v2) + { cout << " " << v; } cout << endl; cout << "v3 ="; - for (auto& v : v3){ + for (auto& v : v3) + { cout << " " << v; } cout << endl; + cout << "v4 ="; - for (auto& v : v4){ + for (auto& v : v4) + { cout << " " << v; } cout << endl; cout << "v5 ="; - for (auto& v : v5){ + for (auto& v : v5) + { cout << " " << v; } cout << endl; cout << "v6 ="; - for (auto& v : v6){ + for (auto& v : v6) + { cout << " " << v; } cout << endl; // Move vector v2 to vector v7 - vector v7(move(v2)); - vector ::iterator v7_Iter; + vector v7(move(v2)); + vector::iterator v7_Iter; cout << "v7 ="; - for (auto& v : v7){ + for (auto& v : v7) + { cout << " " << v; } cout << endl; + cout << "v8 ="; vector v8{ { 1, 2, 3, 4 } }; - for (auto& v : v8){ - cout << " " << v ; + for (auto& v : v8) + { + cout << " " << v; } cout << endl; } ``` ```Output -v1 = 0 0 0v2 = 2 2 2 2 2v3 = 1 1 1v4 = 2 2 2 2 2v5 = 0 1 2 3 4v6 = 1 2v7 = 2 2 2 2 21 2 3 4 +v1 = 0 0 0 +v2 = 2 2 2 2 2 +v3 = 1 1 1 +v4 = 2 2 2 2 2 +v5 = 0 0 0 0 0 +v6 = 0 0 +v7 = 2 2 2 2 2 +v8 = 1 2 3 4 ``` ## See also diff --git a/docs/standard-library/vector-functions.md b/docs/standard-library/vector-functions.md index 3401380cf3..f2bac12974 100644 --- a/docs/standard-library/vector-functions.md +++ b/docs/standard-library/vector-functions.md @@ -3,12 +3,11 @@ description: "Learn more about: functions" title: " functions" ms.date: "11/04/2016" f1_keywords: ["vector/std::swap"] -ms.assetid: 6cdcf043-eef6-4330-83f0-4596fb9f968a helpviewer_keywords: ["std::swap [vector]"] --- # `` functions -## swap +## `swap` Exchanges the elements of two vectors. @@ -19,16 +18,16 @@ void swap(vector& left, vector& right); ### Parameters -*right*\ -The vector providing the elements to be swapped, or the vector whose elements are to be exchanged with those of the vector *left*. +*`right`*\ +The vector providing the elements to be swapped, or the vector whose elements are to be exchanged with those of the vector *`left`*. -*left*\ -The vector whose elements are to be exchanged with those of the vector *right*. +*`left`*\ +The vector whose elements are to be exchanged with those of the vector *`right`*. ### Remarks -The template function is an algorithm specialized on the container class vector to execute the member function `left`. [vector::swap](../standard-library/vector-class.md) *( right*). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template`** \< **class T**> **void swap**( **T&**, **T&**), in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class vector to execute the member function `left. vector::swap (right)`. These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call isn't unique, then the compiler will select the most specialized version of the template function. The general version of the template function, **`template void swap(T&, T&)`**, in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. ### Example -See the code example for member function [vector::swap](../standard-library/vector-class.md) for an example that uses the template version of `swap`. +See the code example for member function [`vector::swap`](../standard-library/vector-class.md) for an example that uses the template version of `swap`. diff --git a/docs/standard-library/vector.md b/docs/standard-library/vector.md index 53f1298f8f..f9dd7af32e 100644 --- a/docs/standard-library/vector.md +++ b/docs/standard-library/vector.md @@ -14,7 +14,7 @@ The `vector` is a container that organizes elements of a given type in a linear > [!NOTE] > The `` library also uses the `#include ` statement. -For more information about the class `vector`, see [`vector` Class](../standard-library/vector-class.md). For information about the specialization `vector`, see [`vector\` Class](../standard-library/vector-bool-class.md). +For more information about the class `vector`, see [`vector` Class](../standard-library/vector-class.md). For information about the specialization `vector`, see [`vector` class](../standard-library/vector-bool-class.md). ## Syntax @@ -87,9 +87,9 @@ The second (right) vector in a compare operation. |Name|Description| |-|-| -|[`operator! =`](../standard-library/vector-operators.md#op_neq)|Tests if the `vector` object on the left side of the operator is not equal to the `vector` object on the right side.| +|[`operator! =`](../standard-library/vector-operators.md#op_neq)|Tests if the `vector` object on the left side of the operator isn't equal to the `vector` object on the right side.| |[`operator<`](../standard-library/vector-operators.md#op_lt)|Tests if the `vector` object on the left side of the operator is less than the `vector` object on the right side.| -|[`operator\<=`](../standard-library/vector-operators.md#op_gt_eq)|Tests if the `vector` object on the left side of the operator is less than or equal to the `vector` object on the right side.| +|[`operator<=`](../standard-library/vector-operators.md#op_gt_eq)|Tests if the `vector` object on the left side of the operator is less than or equal to the `vector` object on the right side.| |[`operator==`](../standard-library/vector-operators.md#op_eq_eq)|Tests if the `vector` object on the left side of the operator is equal to the `vector` object on the right side.| |[`operator>`](../standard-library/vector-operators.md#op_gt)|Tests if the `vector` object on the left side of the operator is greater than the `vector` object on the right side.| |[`operator>=`](../standard-library/vector-operators.md#op_gt_eq)|Tests if the `vector` object on the left side of the operator is greater than or equal to the `vector` object on the right side.| @@ -98,14 +98,14 @@ The second (right) vector in a compare operation. |Name|Description| |-|-| -|[`vector Class`](../standard-library/vector-class.md)|A class template of sequence containers that arrange elements of a given type in a linear arrangement and allow fast random access to any element.| +|[`vector` class](../standard-library/vector-class.md)|A class template of sequence containers that arrange elements of a given type in a linear arrangement and allow fast random access to any element.| ### Specializations |Name|Description| |-|-| |hash|Returns a hash of the vector.| -|[`vector\ Class`](../standard-library/vector-bool-class.md)|A full specialization of the class template vector for elements of type **`bool`** with an allocator for the underlying type used by the specialization.| +|[`vector` class](../standard-library/vector-bool-class.md)|A full specialization of the class template vector for elements of type **`bool`** with an allocator for the underlying type used by the specialization.| ## Requirements diff --git a/docs/standard-library/view-classes.md b/docs/standard-library/view-classes.md new file mode 100644 index 0000000000..a7c6a10b81 --- /dev/null +++ b/docs/standard-library/view-classes.md @@ -0,0 +1,169 @@ +--- +title: "View classes" +description: "Learn more about the ranges view classes, which allow you to inexpensively transform ranges." +ms.date: 12/20/2022 +f1_keywords: ["RANGES/std::ranges::views", "RANGES/std::views"] +helpviewer_keywords: ["RANGES/VIEWS/std", "VIEWS/std"] +--- +# `` view classes + +A *view* is a lightweight range that refers to elements that it doesn't own (except [`owning_view`](owning-view-class.md)). A view is typically based on another range and provides a different way of looking at it, whether by transforming or filtering it. For example, [`std::views::filter`](filter-view-class.md) is a view that uses the criteria that you specify to select elements from another range. + +When you access the elements in a view, it's done "lazily" so that work is done only when you get an element. This makes it possible to combine, or *compose*, views without a performance penalty. + +For example, you could create a view that provides only the even elements from a range and then transform them by squaring them. The work to do the filtering and transformation is done only for the elements that you access, and only when you access them. + +A view can be copied, assigned, and destroyed in constant time no matter how many elements it contains. This is because a view doesn't own the elements that it refers to, so it doesn't need to make a copy. This is why you can compose views without a performance penalty. + +You typically create a view by using a [range adaptor](range-adaptors.md). Range adaptors are the intended way to create a view, are easier to use than instantiating the view classes directly, and are sometimes more efficient than instantiating the view classes directly. The view classes are exposed directly in case you need to create your own custom view type based on an existing view type. + +Here's a brief example of creating a view of the squares of the elements that are divisible by three in a vector: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto divisible_by_three = [](const int n) {return n % 3 == 0;}; + auto square = [](const int n) {return n * n;}; + + auto x = input + | std::views::filter(divisible_by_three) + | std::views::transform(square); + + for (int i : x) + { + std::cout << i << ' '; // 0 9 36 81 + } +} +``` + +```output +0 9 36 81 +``` + +Using a view after the range that it's based on is modified can lead to undefined behavior. For example, a [`reverse_view`](reverse-view-class.md) based on a vector shouldn't be reused if you add or remove elements from the underlying vector. Modifying the underlying vector invalidates the container's `end` iterator--including the copy of the iterator that the view might have made. + +Because views are cheap to create, you should generally re-create a view if you modify the underlying range. The following example demonstrates how to store a view pipeline in a variable so that you can reuse it. + +```cpp +// requires /std:c++20, or later +#include +#include +#include +#include +#include +#include + +template +void show(std::string_view msg, rangeType r) +{ + std::cout << msg; + std::ranges::for_each(r, + [](auto e) + { + std::cout << e << ' '; + }); + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 1, 2, 3, 4 }; + show("v: ", v); + + // You can save a view pipeline + auto rev3 = std::views::take(3) | std::views::reverse; + + show("v | rev3: ", v | rev3); // 3 2 1 + + v.insert(v.begin(), 0); // v = 0 1 2 3 4 + show("v: ", v); + + // Because modifying the vector invalidates its iterators, rebuild the view. + // We are reusing the view pipeline we saved earlier + show("v | rev3(v): ", rev3(v)); +} +``` + +```output +v: 1 2 3 4 +v | rev3: 3 2 1 +v: 0 1 2 3 4 +v | rev3(v): 2 1 0 +``` + +The following view classes are defined in the `std::ranges` namespace. + +| View | Description | +|--|--| +| [`basic_istream_view`](basic-istream-view-class.md)C++20 | A view of successive elements from an input stream. Specializations include `istream_view` and `wistream_view`. | +| [`common_view`](common-view-class.md)C++20 | Adapts a view that has different iterator/sentinel types into a view with the same iterator/sentinel types. | +| [`drop_view`](drop-view-class.md)C++20 | Created from another view, skipping the first `count` elements. | +| [`drop_while_view`](drop-while-view-class.md)C++20 | Created from another view, skipping leading elements as long as a predicate holds. | +| [`elements_view`](elements-view-class.md)C++20 | A view over the selected index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of all the `string` elements from each tuple. | +| [`empty_view`](empty-view-class.md)C++20 | A view with no elements. | +| [`filter_view`](filter-view-class.md)C++20 | Filters out elements of a range that don't match a predicate. | +| [`iota_view`](iota-view-class.md)C++20 | A generated view that contains a sequence of incrementing values. | +| [`join_view`](join-view-class.md)C++20 | Combines all the elements of multiple ranges into a single view. | +| [`keys_view`](keys-view-class.md)C++20 | A view over the first index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of the `string` elements from each tuple. | +| [`lazy_split_view`](lazy-split-view-class.md)C++20 | Splits a view into subranges based on a delimiter. | +| [`owning_view`](owning-view-class.md)C++20 | Takes ownership of the elements from another range. | +| [`ref_view`](ref-view-class.md)C++20 | A view that references the elements that belong to another range. | +| [`reverse_view`](reverse-view-class.md)C++20 | Presents the elements of a range in reverse order. | +| [`single_view`](single-view-class.md)C++20 | A view that contains only one element. | +| [`split_view`](split-view-class.md)C++20 | Splits a view into subranges based on a delimiter. | +| [`subrange`](subrange-class.md)C++20 | A view of part of the elements of a range, as defined by a begin iterator and a sentinel. | +| [`take_view`](take-view-class.md)C++20 | Contains the specified number of elements taken from the front of a range. | +| [`take_while_view`](take-while-view-class.md)C++20 | Contains the leading elements of a range that match the given predicate. | +| [`transform_view`](transform-view-class.md)C++20 | A view of an underlying sequence after a transformation function is applied to each element. | +| [`values_view`](values-view-class.md)C++20 | A view over the second index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of the `int` elements from each tuple. | + +Many of these classes have corresponding [range adaptors](range-adaptors.md) in the `std::views` namespace that creates instances of them. Prefer using an adaptor to create a view instead of creating view classes directly. The range adaptors are the intended way to create views, are easier to use, and in some cases are more efficient. + +## View classes characteristics + +Each view class topic has a **Characteristics** section after the syntax section. The **Characteristics** section has the following entries: + +* **Range adaptor**: A link to the range adaptor that creates the view. You typically use a range adaptor to create a view rather than create a view class directly, so it's listed here for convenience. +* **Underlying range**: Views have different iterator requirements for the kind of underlying range that they can use. See [ranges iterator hierarchy](#ranges-iterator-hierarchy) for more information about the kinds of iterators. +* **View iterator category**: The iterator category of the view. When a view adapts a range, the iterator type for the view is typically the same as the iterator type of the underlying range. However, it might be different for some views. For example, `reverse_view` has a [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator), even if the underlying range has a [`random_access_iterator`](iterator-concepts.md#random_access_iterator). +* **Element type**: The type of the elements that the view's iterator returns. +* **Sized**: Whether the view can return the number of elements that it refers to. Not all views can. +* **Common range**: Specifies whether the view is a [`common_range`](range-concepts.md#common_range), which means that the begin iterator and sentinel types are the same. Common ranges are useful for pre-range code that works with iterator pairs. An example is iterator pair constructors for a sequence container, like `vector(ranges::begin(x), ranges::end(x))`. +* **Borrowed range**: Specifies whether the view is a borrowed range. `borrowed_range` means you can use iterators for `T` after `T` is destroyed. + + No standard container is a borrowed range, because destroying the container frees the elements and invalidates any iterators. In that case, we say that the iterators are left "dangling" after destruction. + + For example, `std::ranges::find()` typically returns an iterator to the found element in the range argument. If the range argument is a temporary (rvalue) container, it's a mistake to store the returned iterator and use it later because it's "dangling." + + Range algorithms that return iterators (or subranges) do so only when their arguments are lvalues (non-temporaries) or borrowed ranges. Otherwise, they return a `std::dangling` object, which provides a hint in error messages about what went wrong if you tried to use it like an iterator. +* **Is `const` iterable**: Indicates whether you can iterate over a `const` instance of the view. Not all `const` views can be iterated. If a view isn't `const` iterable, you can't iterate with `for (const auto& element : as_const(theView))` or pass it to a function that takes a `const` reference to the view and then tries to iterate over it. + +### Ranges iterator hierarchy + +In the **Characteristics** section of each view class topic, the iterator category in **Underlying range** and **View iterator category** refers to the kind of iterator that the range/view supports. There are six categories of Ranges iterators, which are identified by C++20 concepts. The hierarchy of range iterators, in increasing order of capability, is: + +| Range iterator concept | Description | +|--|--| +| [`output_range`](range-concepts.md#output_range) | Write-only, only moves forward; single-pass. | +| [`input_range`](range-concepts.md#input_range) | Read-only, only moves forward; single-pass. | +| [`forward_range`](range-concepts.md#forward_range) | Only moves forward; multi-pass. | +| [`bidirectional_range`](range-concepts.md#bidirectional_range) | Can move forward and backward; multi-pass. | +| [`random_access_range`](range-concepts.md#random_access_range) | Can access the collection with an index; multi-pass. | +| [`contiguous_range`](range-concepts.md#contiguous_range) | Can access the collection with an index, and elements are stored contiguously in memory. | + +Generally speaking, an iterator has the capability of the iterators that precede it in the table. For example, [`bidirectional_range`](range-concepts.md#bidirectional_range) has the capabilities of [`forward_range`](range-concepts.md#forward_range), but not vice versa. Except `input_range`, which doesn't have the capability of `output_range` because you can't write to an `input_range`. + +The statement "requires `input_range` or higher" means that the view can be used with an `input_range`, `forward_range`, `bidirectional_range`, `random_access_range`, or `contiguous_range` iterator, because they're all as capable as `input_range`. + +The ranges iterator hierarchy is directly related to the iterator hierarchy. For more information, see [Iterator concepts](iterator-concepts.md). + +## See also + +[``](ranges.md)\ +[Range adaptors](range-adaptors.md) diff --git a/docs/standard-library/view-interface.md b/docs/standard-library/view-interface.md new file mode 100644 index 0000000000..67bf457cb5 --- /dev/null +++ b/docs/standard-library/view-interface.md @@ -0,0 +1,275 @@ +--- +title: view_interface class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) view_interface class, which is the base class for the ranges view classes." +ms.date: 10/07/2022 +f1_keywords: ["ranges/std::view_interface::back", "ranges/std::view_interface::data","ranges/std::view_interface::empty", "ranges/std::view_interface::front", "ranges/std::view_interface::size", "ranges/std::view_interface::operator[]", "ranges/std::view_interface::operator bool"] +helpviewer_keywords: ["std::ranges::view_interface [C++]", "std::ranges::view_interface [C++], back", "std::ranges::view_interface [C++], data", "std::ranges::view_interface [C++], empty", "std::ranges::view_interface [C++], front", "std::ranges::view_interface [C++], size", "std::ranges::view_interface [C++], operator[]", "std::ranges::view_interface [C++], operator bool"] +dev_langs: ["C++"] +--- +# `view_interface` class (C++ Standard Library) + +The base class for the [view classes](view-classes.md) in the `std::ranges` namespace. This class implements some of the interface for derived view types. Use this as the base class for your own view types to reduce the boilerplate you need to write. + +## Syntax + +```cpp +template + requires std::is_class_v && + std::same_as> +class view_interface; +``` + +### Template parameters + +*`Derived`*\ + The type of the class that is deriving from this base class. + +## Members + +| **Member functions** | **Description** | +|--|--| +| [`back`](#back)C++20 | Get the last element in the derived view. | +| [`data`](#data)C++20 | Get a pointer to the first element in the derived view. | +| [`empty`](#empty)C++20 | Test whether the derived view is empty. | +| [`front`](#front)C++20 | Get the first element in the derived view. | +| [`size`](#size)C++20 | Get the number of elements in the derived view. | +| **Operators** | **Description** | +| [`operator[]`](#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](#op_bool)C++20 | Test whether the derived view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## `back` + +Get the last element in the derived view. + +```cpp +constexpr auto back() + requires ranges::bidirectional_range && + ranges::common_range; + +constexpr auto back() const + requires ranges::bidirectional_range && + ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The last element in the derived view. + +### Remarks + +The derived view must satisfy [`bidirectional_range`](range-concepts.md#bidirectional_range) and [`common_range`](range-concepts.md#common_range).\ +The behavior of `back()` and `front()` are undefined for any empty view. + +## `data` + +Get a pointer to the first element in the derived view. + +```cpp +constexpr auto data() + requires std::contiguous_iterator>; +constexpr auto data() const + requires ranges::range && + std::contiguous_iterator>; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element in the derived view. + +### Remarks + +The iterator for the derived view must satisfy [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator). + +## `empty` + +Test whether the derived view is empty. + +```cpp +1) constexpr bool empty() requires ranges::forward_range; +2) constexpr bool empty() const requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the derived view has no elements. Otherwise, returns `false`. + +### Remarks + +The derived view must satisfy `std::ranges::forward_range`. + +## `front` + +Get the first element in the derived view. + +```cpp +constexpr auto front() + requires ranges::forward_range; +constexpr auto front() const + requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +The last element in the derived view. + +### Remarks + +The derived view must satisfy [`forward_range`](range-concepts.md#forward_range).\ +The behavior of `front()` is undefined for `std::ranges::empty_view`. + +## `size` + +Get the number of elements in the derived view. + +```cpp +constexpr auto size() requires ranges::forward_range && + std::sized_sentinel_for, + ranges::iterator_t>; +constexpr auto size() const requires ranges::forward_range && + std::sized_sentinel_for, + ranges::iterator_t>; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the derived view. + +### Remarks + +The iterator for the derived view must satisfy [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for). + +## `operator[]` + +Get the element at the specified position. + +```cpp +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos); + +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos) const; +``` + +### Parameters + +*`pos`*\ +The position, relative to the beginning iterator, of the element to return. + +### Return value + +The element at the specified position relative to the beginning iterator. + +### Remarks + +The derived view must satisfy [`random_access_range`](range-concepts.md#random_access_range).\ +The behavior of this operator is undefined for `std::ranges::empty_view`. + +### Example: `operator[]` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + std::ranges::drop_view dv = std::views::drop(v, 2); + + for (auto e : dv) + { + std::cout << e << ' '; // 3 4 5 + } + + std::cout << "\ndv[1] = " << dv[1]; +} +``` + +```output +3 4 5 +dv[1] = 4 +``` + +## `view_interface::operator bool` + +Test whether the derived view isn't empty. + +```cpp +explicit constexpr operator bool(); +explicit constexpr operator bool() const; +``` + +### Parameters + +None. + +### Return value + +Returns `false` if the derived view has no elements (the view is empty). Otherwise, returns `true` (the view isn't empty). + +### Remarks + +The iterator for the derived view must satisfy `std::ranges::forward_iterator`.\ +This operator is equivalent to `!empty()`. This makes it convenient to write `if (someRange) {...}` to test whether there's something in the range to operate on.\ +The behavior of this operator is undefined for `std::ranges::empty_view`. + +### Example: `operator bool` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + std::ranges::filter_view fv = std::views::filter(v, [](int e) { return e > 3; }); + + bool isNotEmpty = static_cast(fv); + std::cout << "Has elements greater than 3: " << std::boolalpha << isNotEmpty << '\n' >>; +} +``` + +```output +Has elements greater than 3: true +``` + +## See also + +[``](ranges.md)\ +[`ranges::begin()`](range-functions.md#begin)\ +[`ranges::data()`](range-functions.md#data)\ +[`ranges::end()`](range-functions.md#end)\ +[`ranges::empty()`](range-functions.md#empty)\ +[`ranges::size()`](range-functions.md#size)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/wbuffer-convert-class.md b/docs/standard-library/wbuffer-convert-class.md index b70a646411..060e7db84f 100644 --- a/docs/standard-library/wbuffer-convert-class.md +++ b/docs/standard-library/wbuffer-convert-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: wbuffer_convert class" title: "wbuffer_convert class" +description: "Learn more about: wbuffer_convert class" ms.date: "11/29/2021" f1_keywords: ["xlocmon/stdext::cvt::wbuffer_convert"] helpviewer_keywords: ["wbuffer_convert class"] @@ -20,7 +20,7 @@ class wbuffer_convert ### Parameters *`Codecvt`*\ -The [`locale`](../standard-library/locale-class.md) facet that represents the conversion object. +The [`locale`](locale-class.md) facet that represents the conversion object. *`Elem`*\ The wide-character element type. @@ -36,5 +36,5 @@ Conversion between a sequence of `Elem` values and multibyte sequences is perfor An object of this class template stores: -- A pointer to its underlying byte stream buffer.\ -- A pointer to an allocated conversion facet object, which is freed when the `wbuffer_convert`is destroyed. +- A pointer to its underlying byte stream buffer. +- A pointer to an allocated conversion facet object, which is freed when the `wbuffer_convert` is destroyed. diff --git a/docs/standard-library/weak-ptr-class.md b/docs/standard-library/weak-ptr-class.md index c574d7ab02..03329b747d 100644 --- a/docs/standard-library/weak-ptr-class.md +++ b/docs/standard-library/weak-ptr-class.md @@ -1,12 +1,13 @@ --- description: "Learn more about: weak_ptr Class" title: "weak_ptr Class" -ms.date: "07/29/2019" +ms.date: 06/21/2022 f1_keywords: ["memory/std::weak_ptr", "memory/std::weak_ptr::element_type", "memory/std::weak_ptr::expired", "memory/std::weak_ptr::lock", "memory/std::weak_ptr::owner_before", "memory/std::weak_ptr::reset", "memory/std::weak_ptr::swap", "memory/std::weak_ptr::use_count", "memory/std::weak_ptr::operator="] helpviewer_keywords: ["std::weak_ptr [C++]", "std::weak_ptr [C++], element_type", "std::weak_ptr [C++], expired", "std::weak_ptr [C++], lock", "std::weak_ptr [C++], owner_before", "std::weak_ptr [C++], reset", "std::weak_ptr [C++], swap", "std::weak_ptr [C++], use_count", "std::weak_ptr [C++], element_type", "std::weak_ptr [C++], expired", "std::weak_ptr [C++], lock", "std::weak_ptr [C++], owner_before", "std::weak_ptr [C++], reset", "std::weak_ptr [C++], swap", "std::weak_ptr [C++], use_count"] -ms.assetid: 2db4afb2-c7be-46fc-9c20-34ec2f8cc7c2 +ms.custom: devdivchpfy22 --- -# weak_ptr Class + +# `weak_ptr` Class Wraps a weakly linked pointer. @@ -18,16 +19,16 @@ template class weak_ptr; ### Parameters -*T*\ +*`T`*\ The type controlled by the weak pointer. ## Remarks -The class template describes an object that points to a resource that is managed by one or more [shared_ptr](shared-ptr-class.md) objects. The `weak_ptr` objects that point to a resource don't affect the resource's reference count. When the last `shared_ptr` object that manages that resource is destroyed, the resource will be freed, even if there are `weak_ptr` objects pointing to that resource. This behavior is essential for avoiding cycles in data structures. +The class template describes an object that points to a resource that is managed by one or more [`shared_ptr`](shared-ptr-class.md) objects. The `weak_ptr` objects that point to a resource don't affect the resource's reference count. When the last `shared_ptr` object that manages that resource is destroyed, the resource will be freed, even if there are `weak_ptr` objects pointing to that resource. This behavior is essential for avoiding cycles in data structures. -A `weak_ptr` object points to a resource if it was constructed from a `shared_ptr` object that owns that resource, if it was constructed from a `weak_ptr` object that points to that resource, or if that resource was assigned to it with [operator=](#op_eq). A `weak_ptr` object doesn't provide direct access to the resource that it points to. Code that needs to use the resource does so through a `shared_ptr` object that owns that resource, created by calling the member function [lock](#lock). A `weak_ptr` object has expired when the resource that it points at has been freed because all of the `shared_ptr` objects that own the resource have been destroyed. Calling `lock` on a `weak_ptr` object that has expired creates an empty shared_ptr object. +A `weak_ptr` object points to a resource if it was constructed from a `shared_ptr` object that owns that resource, if it was constructed from a `weak_ptr` object that points to that resource, or if that resource was assigned to it with [`operator=`](#op_eq). A `weak_ptr` object doesn't provide direct access to the resource that it points to. Code that needs to use the resource does so through a `shared_ptr` object that owns that resource, created by calling the member function [`lock`](#lock). A `weak_ptr` object has expired when the resource that it points at has been freed because all of the `shared_ptr` objects that own the resource have been destroyed. Calling `lock` on a `weak_ptr` object that has expired creates an empty `shared_ptr` object. -An empty weak_ptr object doesn't point to any resources and has no control block. Its member function `lock` returns an empty shared_ptr object. +An empty `weak_ptr` object doesn't point to any resources and has no control block. Its member function `lock` returns an empty `shared_ptr` object. A cycle occurs when two or more resources controlled by `shared_ptr` objects hold mutually referencing `shared_ptr` objects. For example, a circular linked list with three elements has a head node `N0`; that node holds a `shared_ptr` object that owns the next node, `N1`; that node holds a `shared_ptr` object that owns the next node, `N2`; that node, in turn, holds a `shared_ptr` object that owns the head node, `N0`, closing the cycle. In this situation, the reference counts never become zero, and the nodes in the cycle are never freed. To eliminate the cycle, the last node `N2` should hold a `weak_ptr` object pointing to `N0` instead of a `shared_ptr` object. Since the `weak_ptr` object doesn't own `N0` it doesn't affect `N0`'s reference count, and when the program's last reference to the head node is destroyed the nodes in the list will also be destroyed. @@ -36,22 +37,22 @@ A cycle occurs when two or more resources controlled by `shared_ptr` objects hol |Name|Description| |-|-| | **Constructors** | | -|[weak_ptr](#weak_ptr)|Constructs a `weak_ptr`.| +|[`weak_ptr`](#weak_ptr)|Constructs a `weak_ptr`.| | **Destructors** | | -|[~weak_ptr](#tilde-weak_ptr)|Constructs a `weak_ptr`.| +|[`~weak_ptr`](#tilde-weak_ptr)|Destroys a `weak_ptr`.| | **Typedefs** | | -|[element_type](#element_type)|The type of the element.| +|[`element_type`](#element_type)|The type of the element.| | **Member functions** | | -|[expired](#expired)|Tests if ownership has expired.| -|[lock](#lock)|Obtains exclusive ownership of a resource.| -|[owner_before](#owner_before)|Returns **`true`** if this `weak_ptr` is ordered before (or less than) the provided pointer.| -|[reset](#reset)|Releases owned resource.| -|[swap](#swap)|Swaps two `weak_ptr` objects.| -|[use_count](#use_count)|Counts number of `shared_ptr` objects.| +|[`expired`](#expired)|Tests if ownership has expired.| +|[`lock`](#lock)|Obtains exclusive ownership of a resource.| +|[`owner_before`](#owner_before)|Returns **`true`** if this `weak_ptr` is ordered before (or less than) the provided pointer.| +|[`reset`](#reset)|Releases owned resource.| +|[`swap`](#swap)|Swaps two `weak_ptr` objects.| +|[`use_count`](#use_count)|Counts number of `shared_ptr` objects.| | **Operators** | | -|[operator=](#op_eq)|Replaces owned resource.| +|[`operator=`](#op_eq)|Replaces owned resource.| -## element_type +## `element_type` The type of the element. @@ -88,7 +89,7 @@ int main() *wp0.lock() == 5 ``` -## expired +## `expired` Tests if ownership has expired, that is, the referenced object has been deleted. @@ -137,7 +138,7 @@ wp.expired() == true (bool)wp.lock() == false ``` -## lock +## `lock` Obtains a `shared_ptr` that shares ownership of a resource. @@ -147,7 +148,7 @@ shared_ptr lock() const noexcept; ### Remarks -The member function returns an empty [shared_ptr](shared-ptr-class.md) object if **`*this`** has expired; otherwise it returns a `shared_ptr` object that owns the resource that **`*this`** points to. Returns a value equivalent to the atomic execution of `expired() ? shared_ptr() : shared_ptr(*this)`. +The member function returns an empty [`shared_ptr`](shared-ptr-class.md) object if **`*this`** has expired; otherwise it returns a `shared_ptr` object that owns the resource that **`*this`** points to. Returns a value equivalent to the atomic execution of `expired() ? shared_ptr() : shared_ptr(*this)`. ### Example @@ -186,7 +187,7 @@ wp.expired() == true (bool)wp.lock() == false ``` -## operator= +## `operator=` Replaces owned resource. @@ -202,15 +203,15 @@ weak_ptr& operator=(const shared_ptr& ptr) noexcept; ### Parameters -*Other*\ +*`Other`*\ The type controlled by the argument shared or weak pointer. -*ptr*\ +*`ptr`*\ The weak pointer or shared pointer to copy. ### Remarks -The operators all release the resource currently pointed to by **`*this`** and assign ownership of the resource named by *ptr* to **`*this`**. If an operator fails, it leaves **`*this`** unchanged. Each operator has an effect equivalent to `weak_ptr(ptr).swap(*this)`. +The operators all release the resource currently pointed to by **`*this`** and assign ownership of the resource named by *`ptr`* to **`*this`**. If an operator fails, it leaves **`*this`** unchanged. Each operator has an effect equivalent to `weak_ptr(ptr).swap(*this)`. ### Example @@ -244,7 +245,7 @@ int main() *wp1.lock() == 10 ``` -## owner_before +## `owner_before` Returns **`true`** if this `weak_ptr` is ordered before (or less than) the provided pointer. @@ -258,14 +259,14 @@ bool owner_before(const weak_ptr& ptr) const noexcept; ### Parameters -*ptr*\ -An lvalue reference to either a `shared_ptr` or a `weak_ptr`. +*`ptr`*\ +An `lvalue` reference to either a `shared_ptr` or a `weak_ptr`. ### Remarks -The template member function returns **`true`** if **`*this`** is ordered before *ptr*. +The template member function returns **`true`** if **`*this`** is ordered before *`ptr`*. -## reset +## `reset` Releases the owned resource. @@ -307,7 +308,7 @@ wp.expired() == false wp.expired() == true ``` -## swap +## `swap` Swaps two `weak_ptr` objects. @@ -324,12 +325,12 @@ void swap(weak_ptr& a, weak_ptr& b) noexcept; ### Parameters -*wp*\ +*`wp`*\ The weak pointer to swap with. ### Remarks -After a `swap`, the resource originally pointed to by **`*this`** is pointed to by *wp*, and the resource originally pointed to by *wp* is pointed to by **`*this`**. The function doesn't change the reference counts for the two resources and it doesn't throw any exceptions. The effect of the template specialization is the equivalent of `a.swap(b)`. +After a `swap`, the resource originally pointed to by **`*this`** is pointed to by *`wp`*, and the resource originally pointed to by *`wp`* is pointed to by **`*this`**. The function doesn't change the reference counts for the two resources and it doesn't throw any exceptions. The effect of the template specialization is the equivalent of `a.swap(b)`. ### Example @@ -376,7 +377,7 @@ int main() *wp1 == 5 ``` -## use_count +## `use_count` Counts the number of `shared_ptr` objects that own the shared resource. @@ -416,7 +417,7 @@ wp.use_count() == 1 wp.use_count() == 2 ``` -## weak_ptr +## `weak_ptr` Constructs a `weak_ptr`. @@ -439,13 +440,13 @@ weak_ptr(const shared_ptr& sp) noexcept; ### Parameters -*Other*\ -The type controlled by the argument shared/weak pointer. These constructors don't participate in overload resolution unless _Other\*_ is compatible with `element_type*`. +*`Other`*\ +The type controlled by the argument shared/weak pointer. These constructors don't participate in overload resolution unless `Other*` is compatible with `element_type*`. -*wp*\ +*`wp`*\ The weak pointer to copy. -*sp*\ +*`sp`*\ The shared pointer to copy. ### Remarks @@ -485,7 +486,7 @@ wp0.expired() == true *wp2.lock() == 5 ``` -## ~weak_ptr +## `~weak_ptr` Destroys a `weak_ptr`. @@ -500,5 +501,5 @@ The destructor destroys this `weak_ptr` but has no effect on the reference count ## See also [Header Files Reference](cpp-standard-library-header-files.md)\ -[\](memory.md)\ -[shared_ptr class](shared-ptr-class.md) +[``](memory.md)\ +[`shared_ptr` class](shared-ptr-class.md) diff --git a/docs/standard-library/weekday-class.md b/docs/standard-library/weekday-class.md index 14a8ecbe02..dc7d918278 100644 --- a/docs/standard-library/weekday-class.md +++ b/docs/standard-library/weekday-class.md @@ -46,7 +46,7 @@ See [Weekday constants](#weekday-constants), below, for constants that you can u ## Requirements -**Header:** `` Since C++ 20 +**Header:** `` Since C++20 **Namespace:** `std::chrono` @@ -267,8 +267,8 @@ The value of `*this - d`. The result will be modulo 7, in the range \[0, 6]. Create a [weekday_indexed](weekdayindexed-class.md) or [weekday_last](weekdaylast-class.md) from this `weekday`. ```cpp -1) std::chrono::weekday_indexed(*this, index) // C++ 20 -2) std::chrono::weekday_last(*this) // C++ 20 +1) std::chrono::weekday_indexed(*this, index) // C++20 +2) std::chrono::weekday_last(*this) // C++20 ``` ### Return value diff --git a/docs/standard-library/weekdayindexed-class.md b/docs/standard-library/weekdayindexed-class.md index 43e6c4bf22..9a16b9c3f5 100644 --- a/docs/standard-library/weekdayindexed-class.md +++ b/docs/standard-library/weekdayindexed-class.md @@ -36,7 +36,7 @@ class weekday_indexed; // C++20 ## Requirements -**Header:** `` Since C++ 20 +**Header:** `` Since C++20 **Namespace:** `std::chrono` diff --git a/docs/standard-library/weekdaylast-class.md b/docs/standard-library/weekdaylast-class.md index 543bb54688..477069cd66 100644 --- a/docs/standard-library/weekdaylast-class.md +++ b/docs/standard-library/weekdaylast-class.md @@ -44,7 +44,7 @@ class weekday_last; // C++20 ## Requirements -**Header:** `` Since C++ 20 +**Header:** `` Since C++20 **Namespace:** `std::chrono` diff --git a/docs/standard-library/what-a-stream-is.md b/docs/standard-library/what-a-stream-is.md index df43dfbff1..44ba77d224 100644 --- a/docs/standard-library/what-a-stream-is.md +++ b/docs/standard-library/what-a-stream-is.md @@ -3,13 +3,12 @@ description: "Learn more about: What a Stream Is" title: "What a Stream Is" ms.date: "11/04/2016" helpviewer_keywords: ["reading data [C++], iostream programming", "data [C++], reading", "streams [C++], in iostream classes", "streams [C++]"] -ms.assetid: a7e661e9-6cd1-4543-a9a4-c58ee9fd32f3 --- # What a Stream Is -Like C, C++ does not have built-in input/output capability. All C++ compilers, however, come bundled with a systematic, object-oriented I/O package, known as the iostream classes. The stream is the central concept of the iostream classes. You can think of a stream object as a smart file that acts as a source and destination for bytes. A stream's characteristics are determined by its class and by customized insertion and extraction operators. +Like C, C++ doesn't have built-in input/output capability. All C++ compilers, however, come bundled with a systematic, object-oriented I/O package, known as the `iostream` classes. The stream is the central concept of the `iostream` classes. You can think of a stream object as a smart file that acts as a source and destination for bytes. A stream's characteristics are determined by its class and by customized insertion and extraction operators. -Through device drivers, the disk operating system deals with the keyboard, screen, printer, and communication ports as extended files. The iostream classes interact with these extended files. Built-in classes support reading from and writing to memory with syntax identical to that for disk I/O, which makes it easy to derive stream classes. +Through device drivers, the disk operating system deals with the keyboard, screen, printer, and communication ports as extended files. The `iostream` classes interact with these extended files. Built-in classes support reading from and writing to memory with syntax identical to that for disk I/O, which makes it easy to derive stream classes. ## In This Section @@ -17,4 +16,4 @@ Through device drivers, the disk operating system deals with the keyboard, scree ## See also -[iostream Programming](../standard-library/iostream-programming.md) +[`iostream` Programming](../standard-library/iostream-programming.md) diff --git a/docs/standard-library/writing-your-own-manipulators-without-arguments.md b/docs/standard-library/writing-your-own-manipulators-without-arguments.md index 9793f6db77..7a29f2a12b 100644 --- a/docs/standard-library/writing-your-own-manipulators-without-arguments.md +++ b/docs/standard-library/writing-your-own-manipulators-without-arguments.md @@ -1,13 +1,15 @@ --- description: "Learn more about: Writing Your Own Manipulators Without Arguments" title: "Writing Your Own Manipulators Without Arguments" -ms.date: "11/04/2016" +ms.date: 06/21/2022 helpviewer_keywords: ["manipulators"] ms.assetid: 2dc62d09-45b7-454d-bd9d-55f3c72c206d +ms.custom: devdivchpfy22 --- + # Writing Your Own Manipulators Without Arguments -Writing manipulators that do not use arguments requires neither class derivation nor use of complex macros. Suppose your printer requires the pair \[ to enter bold mode. You can insert this pair directly into the stream: +Writing manipulators that don't use arguments requires neither class derivation nor use of complex macros. Suppose your printer requires the pair \[ to enter bold mode. You can insert this pair directly into the stream: ```cpp cout << "regular " << '\033' << '[' << "boldface" << endl; @@ -22,7 +24,7 @@ ostream& bold(ostream& os) { cout << "regular " << bold << "boldface" << endl; ``` -The globally defined `bold` function takes an `ostream` reference argument and returns the `ostream` reference. It is not a member function or a friend because it does not need access to any private class elements. The `bold` function connects to the stream because the stream's `<<` operator is overloaded to accept that type of function, using a declaration that looks something like this: +The globally defined `bold` function takes an `ostream` reference argument and returns the `ostream` reference. It isn't a member function or a friend because it doesn't need access to any private class elements. The `bold` function connects to the stream because the stream's `<<` operator is overloaded to accept that type of function, using a declaration that looks something like this: ```cpp _Myt& operator<<(ios_base& (__cdecl *_Pfn)(ios_base&)) @@ -34,7 +36,7 @@ _Myt& operator<<(ios_base& (__cdecl *_Pfn)(ios_base&)) } ``` -You can use this feature to extend other overloaded operators. In this case, it is incidental that `bold` inserts characters into the stream. The function is called when it is inserted into the stream, not necessarily when the adjacent characters are printed. Thus, printing could be delayed because of the stream's buffering. +You can use this feature to extend other overloaded operators. In this case, it's incidental that `bold` inserts characters into the stream. The function is called when it's inserted into the stream, not necessarily when the adjacent characters are printed. Thus, printing could be delayed because of the stream's buffering. ## See also diff --git a/docs/standard-library/year-class.md b/docs/standard-library/year-class.md index 09d57af2b1..7d3f7d181c 100644 --- a/docs/standard-library/year-class.md +++ b/docs/standard-library/year-class.md @@ -230,7 +230,7 @@ If the incremented result exceeds 32767, it overflows to -32768 Unary minus. Negate the `year`. ```cpp -constexpr year operator-() const noexcept; // C++ 20 +constexpr year operator-() const noexcept; // C++20 ``` ### Return value diff --git a/docs/standard-library/year-month-class.md b/docs/standard-library/year-month-class.md index 3c85fe5c01..88e5800a28 100644 --- a/docs/standard-library/year-month-class.md +++ b/docs/standard-library/year-month-class.md @@ -2,8 +2,9 @@ description: "Learn more about: year_month class" title: "year_month class" ms.date: "06/28/2021" -f1_keywords: ["chrono/std::chrono::year_month", "chrono/std::chrono::year::operator+=", "chrono/std::chrono::year::operator-=", "chrono/std::chrono::year::ok"] +f1_keywords: ["chrono/std::chrono::year_month", "chrono/std::chrono::year_month::operator+=", "chrono/std::chrono::year_month::operator-=", "chrono/std::chrono::year_month::ok"] helpviewer_keywords: ["std::chrono [C++], year_month"] +dev_langs: ["C++"] --- # `year_month` class @@ -67,7 +68,7 @@ The [`month`](month-class.md) value. 1\) The default constructor doesn't initialize the `year` or `month` value.\ 2\) Construct a `year_month` with the specified values. -For information about C++ 20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `year_month` diff --git a/docs/standard-library/year-month-day-class.md b/docs/standard-library/year-month-day-class.md index 438dfc8fbe..e153349e08 100644 --- a/docs/standard-library/year-month-day-class.md +++ b/docs/standard-library/year-month-day-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: year_month_day class" title: "year_month_day class" +description: "Learn more about: year_month_day class" ms.date: "06/28/2021" f1_keywords: ["chrono/std::chrono::year_month_day", "chrono/std::chrono::year::operator+=", "chrono/std::chrono::year::operator-=", "chrono/std::chrono::year::sysdays", "chrono/std::chrono::year::localdays", "chrono/std::chrono::year::ok"] helpviewer_keywords: ["std::chrono [C++], year_month_day"] @@ -13,7 +13,7 @@ Represents a month, year, and day. ## Syntax ```cpp -class year_month_day; // C++ 20 +class year_month_day; // C++20 ``` ## Members @@ -43,7 +43,7 @@ class year_month_day; // C++ 20 ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::chrono` @@ -81,12 +81,12 @@ A `year_month_day_last` value. ### Remarks 1\) The default constructor doesn't initialize the month or day.\ -2\) Constructs a `year_month_day`with the specified year, month, and day.\ -3\) Constructs a `year_month_day`with the specified year, month, and day from *`ymdl`*\ -4\) Constructs a `year_month_day`with the same date as *`dp`*.\ -5\) Constructs a `year_month_day`with the same date as *`dp`* but as though constructed by `year_month_day(sys_days(dp.time_since_epoch()))`. +2\) Constructs a `year_month_day` with the specified year, month, and day.\ +3\) Constructs a `year_month_day` with the specified year, month, and day from *`ymdl`*\ +4\) Constructs a `year_month_day` with the same date as *`dp`*.\ +5\) Constructs a `year_month_day` with the same date as *`dp`* but as though constructed by `year_month_day(sys_days(dp.time_since_epoch()))`. -For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `year_month_day` diff --git a/docs/standard-library/year-month-day-last-class.md b/docs/standard-library/year-month-day-last-class.md index 59207f663a..2427f36c40 100644 --- a/docs/standard-library/year-month-day-last-class.md +++ b/docs/standard-library/year-month-day-last-class.md @@ -2,8 +2,9 @@ description: "Learn more about: year_month_day_last class" title: "year_month_day_last class" ms.date: "06/28/2021" -f1_keywords: ["chrono/std::chrono::year_month_day_last", "chrono/std::chrono::year_month_day_last::operator+=", "chrono/std::chrono::year_month_day_last::operator-=", "chrono/std::chrono::year_month_day_last::sysdays", "chrono/std::chrono::year_month_day_last::localdays", "chrono/std::chrono::year_month_day_last::day", "chrono/std::chrono::year_month_day_last::year", "chrono/std::chrono::year_month_day_last::ok"] +f1_keywords: ["chrono/std::chrono::year_month_day_last", "chrono/std::chrono::year_month_day_last::operator+=", "chrono/std::chrono::year_month_day_last::operator-=", "chrono/std::chrono::year_month_day_last::sysdays", "chrono/std::chrono::year_month_day_last::local_days", "chrono/std::chrono::year_month_day_last::day", "chrono/std::chrono::year_month_day_last::year", "chrono/std::chrono::year_month_day_last::ok"] helpviewer_keywords: ["std::chrono [C++], year_month_day_last"] +dev_langs: ["C++"] --- # `year_month_day_last` class @@ -69,7 +70,7 @@ The [`year`](year-class.md) value is stored in the constructed `year_month_day_l ## Remarks -For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `year_month_day_last` diff --git a/docs/standard-library/year-month-weekday-class.md b/docs/standard-library/year-month-weekday-class.md index 79c78f2f90..58e7723486 100644 --- a/docs/standard-library/year-month-weekday-class.md +++ b/docs/standard-library/year-month-weekday-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: year_month_weekday class" title: "year_month_weekday class" +description: "Learn more about: year_month_weekday class" ms.date: "06/30/2021" -f1_keywords: ["chrono/std::chrono::year_month_weekday", "chrono/std::chrono::year_month_weekday::weekday", "chrono/std::chrono::year_month_weekday::month", "chrono/std::chrono::year_month_weekday::index", "chrono/std::chrono::year_month_weekday::year", "chrono/std::chrono::year_month_weekday::weekday_indexed", "chrono/std::chrono::year_month_weekday::sys_days", "chrono/std::chrono::year_month_weekday::local_days", "chrono/std::chrono::year_month_weekday::ok", "chrono/std::chrono::year_month_weekday::operator+=", "chrono/std::chrono::year_month_weekday::operator-="] +f1_keywords: ["chrono/std::chrono::year_month_weekday", "chrono/std::chrono::year_month_weekday::weekday", "chrono/std::chrono::year_month_weekday::month", "chrono/std::chrono::year_month_weekday::index", "chrono/std::chrono::year_month_weekday::year", "chrono/std::chrono::year_month_weekday::weekday", "chrono/std::chrono::year_month_weekday::weekday_indexed", "chrono/std::chrono::year_month_weekday::sys_days", "chrono/std::chrono::year_month_weekday::local_days", "chrono/std::chrono::year_month_weekday::ok", "chrono/std::chrono::year_month_weekday::operator+=", "chrono/std::chrono::year_month_weekday::operator-=", "chrono/std::chrono::year_month_weekday::operator local_days", "chrono/std::chrono::year_month_weekday::operator sys_days"] helpviewer_keywords: ["std::chrono [C++], year_month_weekday"] +dev_langs: ["C++"] --- # `year_month_weekday` class @@ -13,7 +14,7 @@ Represents a specific year, month, and nth weekday of the month. ## Syntax ```cpp -class year_month_weekday; // C++ 20 +class year_month_weekday; // C++20 ``` ## Remarks @@ -97,7 +98,7 @@ The [`year`](year-class.md) value. 4\) Constructs a `year_month_weekday` that corresponds to the date represented by *`dp`*. For any `year_month_weekday` (ymdl) for which `ok()` is `true`, comparison with `operator==` to `year_month_weekday{sys_days{ymdl}}` will be `true`. -For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `year_month_weekday` @@ -324,5 +325,5 @@ The [`year`](year-class.md) value. [`year_month_day`](year-month-day-class.md)\ [`year_month_day_last`](year-month-day-last-class.md)\ [`year_month_weekday_last`](year-month-weekday-last-class.md)\ -[`operator/`](chrono-operators.md#op_/) -[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file +[`operator/`](chrono-operators.md#op_/)\ +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/year-month-weekday-last-class.md b/docs/standard-library/year-month-weekday-last-class.md index 724a93b2ed..8cac30f7d4 100644 --- a/docs/standard-library/year-month-weekday-last-class.md +++ b/docs/standard-library/year-month-weekday-last-class.md @@ -2,8 +2,9 @@ description: "Learn more about: year_month_weekday_last class" title: "year_month_weekday_last class" ms.date: "06/30/2021" -f1_keywords: ["chrono/std::chrono::year_month_weekday_last", "chrono/std::chrono::year_month_weekday_last::month", "chrono/std::chrono::year_month_weekday_last::year", "chrono/std::chrono::year_month_weekday_last::weekday_last", "chrono/std::chrono::year_month_weekday_last::sys_days", "chrono/std::chrono::year_month_weekday_last::local_days", "chrono/std::chrono::year_month_weekday_last::ok", "chrono/std::chrono::year_month_weekday_last::operator+=", "chrono/std::chrono::year_month_weekday_last::operator-="] +f1_keywords: ["chrono/std::chrono::year_month_weekday_last", "chrono/std::chrono::year_month_weekday_last::month", "chrono/std::chrono::year_month_weekday_last::year", "chrono/std::chrono::year_month_weekday_last::weekday", "chrono/std::chrono::year_month_weekday_last::weekday_last", "chrono/std::chrono::year_month_weekday_last::sys_days", "chrono/std::chrono::year_month_weekday_last::local_days", "chrono/std::chrono::year_month_weekday_last::ok", "chrono/std::chrono::year_month_weekday_last::operator+=", "chrono/std::chrono::year_month_weekday_last::operator-=", "chrono/std::chrono::year_month_weekday_last::operator local_days", "chrono/std::chrono::year_month_weekday_last::operator sys_days"] helpviewer_keywords: ["std::chrono [C++], year_month_weekday_last"] +dev_langs: ["C++"] --- # `year_month_weekday_last` class @@ -13,7 +14,7 @@ A specific year, month, and last weekday of the month. ## Syntax ```cpp -class year_month_weekday_last; // C++ 20 +class year_month_weekday_last; // C++20 ``` ## Remarks @@ -73,7 +74,7 @@ The [`weekday_last`](weekdaylast-class.md) value. *`y`*\ The [`year`](year-class.md) value. -For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) +For information about C++20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/) ### Example: Create a `year_month_weekday_last` diff --git a/docs/standard-library/zoned-time-class.md b/docs/standard-library/zoned-time-class.md index d20840fdb0..3817f02d55 100644 --- a/docs/standard-library/zoned-time-class.md +++ b/docs/standard-library/zoned-time-class.md @@ -1,9 +1,10 @@ --- -description: "Learn more about: zoned_time class" title: "zoned_time class" -ms.date: 10/11/2021 -f1_keywords: ["chrono/std::chrono::zoned_time::get_info", "chrono/std::chrono::zoned_time::get_local_time", "chrono/std::chrono::zoned_time::get_sys_time", "chrono/std::chrono::zoned_time::get_time_zone","chrono/std::chrono::zoned_time:operator=", "chrono/std::chrono::zoned_time:operator local_time", "chrono/std::chrono::zoned_time:operator sys_time"] +description: "Learn more about: zoned_time class" +ms.date: 05/31/2022 +f1_keywords: ["chrono/std::chrono::zoned_time::get_info", "chrono/std::chrono::zoned_time::get_local_time", "chrono/std::chrono::zoned_time::get_sys_time", "chrono/std::chrono::zoned_time::get_time_zone","chrono/std::chrono::zoned_time::operator=", "chrono/std::chrono::zoned_time::operator local_time", "chrono/std::chrono::zoned_time::operator sys_time"] helpviewer_keywords: ["std::chrono [C++], zoned_time class", "std::chrono::zoned_time::get_info function", "std::chrono::zoned_time::get_local_time function", "std::chrono::zoned_time::get_sys_time function", "std::chrono::zoned_time::get_time_zone function"] +dev_langs: ["C++"] --- # `zoned_time` class @@ -21,8 +22,6 @@ class zoned_time ; // C++20 A `zoned_time` always refers to a valid time zone and represents a point in time that exists and isn't ambiguous in that time zone. -Microsoft C++ supports the `zoned_time` class starting in Visual Studio 2019 version 16.10. - ## Members |Name|Description| @@ -54,6 +53,10 @@ Microsoft C++ supports the `zoned_time` class starting in Visual Studio 2019 ver **Header:** `` +Microsoft C++ supports the `zoned_time` class starting in Visual Studio 2019 version 16.10. + +Time-zone data is only available for Windows 10 version 1903/19H1 and later, and Windows Server 2022 and later. + **Namespace:** `std::chrono` **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) @@ -128,7 +131,7 @@ A `zoned_time` pointer that is `std::move(zt)`'d into the constructed `zoned_tim ### Example: construct a `zoned_time` -The following shows how to create a `zoned_time` instance for the time zone `"Antartica/Casey"`, on 9/15/2021 at 4:45pm: +The following shows how to create a `zoned_time` instance for the time zone `"Antarctica/Casey"`, on 9/15/2021 at 4:45pm: ```cpp // compile using: /std:c++latest @@ -420,4 +423,4 @@ int main() [`time_point`](time-point-class.md)\ [`time_zone`](time-zone-class.md)\ [`zoned_traits` struct](zoned-traits-struct.md)\ -[Header files reference](./cpp-standard-library-header-files.md) \ No newline at end of file +[Header files reference](./cpp-standard-library-header-files.md) diff --git a/docs/standard-library/zoned-traits-struct.md b/docs/standard-library/zoned-traits-struct.md index 0b64e15f37..0cea1af001 100644 --- a/docs/standard-library/zoned-traits-struct.md +++ b/docs/standard-library/zoned-traits-struct.md @@ -1,9 +1,10 @@ --- description: "Learn more about: zoned_traits struct" title: "zoned_traits struct" -ms.date: 10/15/2021 +ms.date: 05/31/2022 f1_keywords: ["chrono/std::chrono::zoned_traits::get_info", "chrono/std::chrono::zoned_traits::default_zone", "chrono/std::chrono::zoned_traits::locate_zone"] helpviewer_keywords: ["std::chrono [C++], zoned_traits struct", "std::chrono::zoned_traits::default_zone function", "std::chrono::zoned_traits::locate_zone function"] +dev_lang: ["C++"] --- # `zoned_traits` struct @@ -31,8 +32,6 @@ struct zoned_traits; // C++20 The pointer to the type that you supply doesn't have to provide the static functions `default_zone()` or `locate_zone()`. But if it doesn't, the `zoned_time` constructors won't be considered during overload resolution. -Microsoft C++ supports `zoned_traits` starting in Visual Studio 2019 version 16.10. - ## Members |Name|Description| @@ -48,6 +47,10 @@ Microsoft C++ supports `zoned_traits` starting in Visual Studio 2019 version 16. **Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) +Microsoft C++ supports `zoned_traits` class starting in Visual Studio 2019 version 16.10. + +Time-zone data is only available for Windows 10 version 1903/19H1 and later, and Windows Server 2022 and later. + ## `default_zone` Gets the [`time_zone`](time-zone-class.md) for the default time zone. For more information about how this works, see the code [example](#example-zoned_traits) at the end of this topic. diff --git a/docs/text/how-to-convert-between-various-string-types.md b/docs/text/how-to-convert-between-various-string-types.md index 8fa2f317de..1f9286f0c4 100644 --- a/docs/text/how-to-convert-between-various-string-types.md +++ b/docs/text/how-to-convert-between-various-string-types.md @@ -2,25 +2,53 @@ description: "Learn more about: How to: Convert Between Various String Types" title: "How to: Convert Between Various String Types" ms.custom: "get-started-article" -ms.date: "11/04/2016" +ms.date: 09/29/2022 helpviewer_keywords: ["converting string types", "string conversion [C++]", "strings [C++], converting"] -ms.assetid: e7e4f741-3c82-45f0-b8c0-1e1e343b0e77 --- -# How to: Convert Between Various String Types +# How to: Convert between various string types -This topic demonstrates how to convert various Visual C++ string types into other strings. The strings types that are covered include `char *`, `wchar_t*`, [_bstr_t](../cpp/bstr-t-class.md), [CComBSTR](../atl/reference/ccombstr-class.md), [CString](../atl-mfc-shared/using-cstring.md), [basic_string](../standard-library/basic-string-class.md), and . In all cases, a copy of the string is made when converted to the new type. Any changes made to the new string will not affect the original string, and vice versa. +This article shows how to convert various Visual C++ string types into other strings. -## Example: Convert from char * +The strings types that are covered include `char *`, `wchar_t*`, [`_bstr_t`](../cpp/bstr-t-class.md), [`CComBSTR`](../atl/reference/ccombstr-class.md), [`CString`](../atl-mfc-shared/using-cstring.md), [`basic_string`](../standard-library/basic-string-class.md), and . + +In all cases, a copy of the string is made when converted to the new type. Any changes made to the new string won't affect the original string, and vice versa. + +For more background information about converting narrow and wide strings, see [Converting between narrow strings and wide strings](#converting-between-narrow-and-wide-strings). + +## Run the examples + +To run the examples in Visual Studio 2022, you can create a new C++ Windows Console App. Or, if you've installed C++/CLI support, you can create a CLR Console App (.NET Framework). + +If you create a CLR Console App, you don't have to make the following changes to the compiler and debugger settings. However, you'll need to add `#include "pch.h"` to the top of each example. + +Either way, add `comsuppw.lib` to **Project Properties** > **Linker** > **Input** > **Additional Dependencies**. + +If you create a new C++ Windows Console app to run the examples, make the following project changes: + +- Add the `/clr` and `/Zc:twoPhase-` command line arguments to **Project Properties** > **C++** > **Command Line** > **Additional Options**. + +The `/clr` switch conflicts with some compiler switches that are set when you create a C++ Windows Console App project. The following links provide instructions for where in the IDE you can turn off the conflicting switches: + +- Turn off [`/RTC1` (Set Basic Runtime Checks to Default)](../build/reference/rtc-run-time-error-checks.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Basic Runtime Checks** > **Default** +- Turn off [`/EHs` (Exception handling model)](../build/reference/eh-exception-handling-model.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Enable C++ Exceptions** > **No** +- Exchange [`/Zi` (Debug information format)](../build/reference/z7-zi-zi-debug-information-format.md#to-set-this-compiler-option-in-the-visual-studio-development-environment) for [`/Z7`](../build/reference/z7-zi-zi-debug-information-format.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Debug Information Format** > **C7 compatible** +- Turn off [`/JMC` (Just My Code debugging)](../build/reference/jmc.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Support Just My Code Debugging** > **No** +- Set the debugger type to mixed: **Project Properties** > **Debugging** > **Debugger Type** > **Mixed (.NET framework)** +- Turn on [`/ASSEMBLYDEBUG`](../build/reference/assemblydebug-add-debuggableattribute.md#to-set-this-linker-option-in-the-visual-studio-development-environment): **Project properties** > **Linker** > **Debugging** > **Debuggable Assembly** > **Yes (ASSEMBLYDEBUG)** + +## Example: Convert from `char *` ### Description -This example demonstrates how to convert from a `char *` to the other string types listed above. A `char *` string (also known as a C style string) uses a null character to indicate the end of the string. C style strings usually require one byte per character, but can also use two bytes. In the examples below, `char *` strings are sometimes referred to as multibyte character strings because of the string data that results from converting from Unicode strings. Single byte and multibyte character (`MBCS`) functions can operate on `char *` strings. +This example demonstrates how to convert from a `char *` to the string types listed above. A `char *` string (also known as a C-style string) uses a terminating null to indicate the end of the string. C-style strings usually require 1 byte per character, but can also use 2 bytes. In the examples below, `char *` strings are sometimes referred to as multibyte character strings because of the string data that results from converting from wide Unicode strings. Single byte and multibyte character (`MBCS`) functions can operate on `char *` strings. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_char.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -35,9 +63,9 @@ using namespace System; int main() { - // Create and display a C style string, and then use it + // Create and display a C-style string, and then use it // to create different kinds of strings. - char *orig = "Hello, World!"; + const char* orig = "Hello, World!"; cout << orig << " (char *)" << endl; // newsize describes the length of the @@ -50,48 +78,49 @@ int main() // in the new format. If you want to add more characters // to the end of the string, increase the value of newsize // to increase the size of the buffer. - wchar_t * wcstring = new wchar_t[newsize]; + wchar_t* wcstring = new wchar_t[newsize]; // Convert char* string to a wchar_t* string. size_t convertedChars = 0; mbstowcs_s(&convertedChars, wcstring, newsize, orig, _TRUNCATE); // Display the result and indicate the type of string that it is. - wcout << wcstring << _T(" (wchar_t *)") << endl; + wcout << wcstring << L" (wchar_t *)" << endl; + delete []wcstring; - // Convert the C style string to a _bstr_t string. + // Convert the C-style string to a _bstr_t string. _bstr_t bstrt(orig); // Append the type of string to the new string // and then display the result. bstrt += " (_bstr_t)"; cout << bstrt << endl; - // Convert the C style string to a CComBSTR string. + // Convert the C-style string to a CComBSTR string. CComBSTR ccombstr(orig); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { CW2A printstr(ccombstr); cout << printstr << endl; } - // Convert the C style string to a CStringA and display it. + // Convert the C-style string to a CStringA and display it. CStringA cstringa(orig); cstringa += " (CStringA)"; cout << cstringa << endl; - // Convert the C style string to a CStringW and display it. + // Convert the C-style string to a CStringW and display it. CStringW cstring(orig); cstring += " (CStringW)"; // To display a CStringW correctly, use wcout and cast cstring // to (LPCTSTR). wcout << (LPCTSTR)cstring << endl; - // Convert the C style string to a basic_string and display it. + // Convert the C-style string to a basic_string and display it. string basicstring(orig); basicstring += " (basic_string)"; cout << basicstring << endl; - // Convert the C style string to a System::String and display it. - String ^systemstring = gcnew String(orig); + // Convert the C-style string to a System::String and display it. + String^ systemstring = gcnew String(orig); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; @@ -109,17 +138,19 @@ Hello, World! (basic_string) Hello, World! (System::String) ``` -## Example: Convert from wchar_t * +## Example: Convert from `wchar_t *` ### Description -This example demonstrates how to convert from a `wchar_t *` to the other string types listed above. Several string types, including `wchar_t *`, implement wide character formats. To convert a string between a multibyte and a wide character format, you can use a single function call like `mbstowcs_s` or a constructor invocation for a class like `CStringA`. +This example demonstrates how to convert from a `wchar_t *` to other string types. Several string types, including `wchar_t *`, implement wide character formats. To convert a string between a multibyte and a wide character format, you can use a single function call like `mbstowcs_s` or a constructor invocation for a class like `CStringA`. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_wchar_t.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -136,8 +167,8 @@ int main() { // Create a string of wide characters, display it, and then // use this string to create other types of strings. - wchar_t *orig = _T("Hello, World!"); - wcout << orig << _T(" (wchar_t *)") << endl; + const wchar_t* orig = L"Hello, World!"; + wcout << orig << L" (wchar_t *)" << endl; // Convert the wchar_t string to a char* string. Record // the length of the original string and add 1 to it to @@ -148,25 +179,26 @@ int main() // Use a multibyte string to append the type of string // to the new string before displaying the result. char strConcat[] = " (char *)"; - size_t strConcatsize = (strlen( strConcat ) + 1)*2; + size_t strConcatsize = (strlen(strConcat) + 1) * 2; // Allocate two bytes in the multibyte output string for every wide // character in the input string (including a wide character // null). Because a multibyte character can be one or two bytes, // you should allot two bytes for each character. Having extra - // space for the new string is not an error, but having + // space for the new string isn't an error, but having // insufficient space is a potential security problem. - const size_t newsize = origsize*2; + const size_t newsize = origsize * 2; // The new string will contain a converted copy of the original // string plus the type of string appended to it. - char *nstring = new char[newsize+strConcatsize]; + char* nstring = new char[newsize + strConcatsize]; // Put a copy of the converted string into nstring wcstombs_s(&convertedChars, nstring, newsize, orig, _TRUNCATE); // append the type of string to the new string. - _mbscat_s((unsigned char*)nstring, newsize+strConcatsize, (unsigned char*)strConcat); + _mbscat_s((unsigned char*)nstring, newsize + strConcatsize, (unsigned char*)strConcat); // Display the result. cout << nstring << endl; + delete []nstring; // Convert a wchar_t to a _bstr_t string and display it. _bstr_t bstrt(orig); @@ -178,7 +210,7 @@ int main() // Then display the result. CComBSTR ccombstr(orig); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { // CW2A converts the string in ccombstr to a multibyte // string in printstr, used here for display output. @@ -186,7 +218,7 @@ int main() cout << printstr << endl; // The following line of code is an easier way to // display wide character strings: - wcout << (LPCTSTR) ccombstr << endl; + wcout << (LPCTSTR)ccombstr << endl; } // Convert a wide wchar_t string to a multibyte CStringA, @@ -207,13 +239,13 @@ int main() // basic_string, append the type of string to it, and // display the result. wstring basicstring(orig); - basicstring += _T(" (basic_string)"); + basicstring += L" (basic_string)"; wcout << basicstring << endl; // Convert a wide character wchar_t string to a // System::String string, append the type of string to it, // and display the result. - String ^systemstring = gcnew String(orig); + String^ systemstring = gcnew String(orig); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; @@ -231,17 +263,19 @@ Hello, World! (basic_string) Hello, World! (System::String) ``` -## Example: Convert from _bstr_t +## Example: Convert from `_bstr_t` ### Description -This example demonstrates how to convert from a `_bstr_t` to the other string types listed above. The `_bstr_t` object is a way to encapsulate wide character `BSTR` strings. A BSTR string has a length value and does not use a null character to terminate the string, but the string type you convert to may require a terminating null. +This example demonstrates how to convert from a `_bstr_t` to other string types. The `_bstr_t` object encapsulates wide character `BSTR` strings. A `BSTR` string has a length value and doesn't use a null character to terminate the string, but the string type you convert to may require a terminating null character. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_bstr_t.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -261,33 +295,35 @@ int main() _bstr_t orig("Hello, World!"); wcout << orig << " (_bstr_t)" << endl; - // Convert the wide character _bstr_t string to a C style + // Convert the wide character _bstr_t string to a C-style // string. To be safe, allocate two bytes for each character // in the char* string, including the terminating null. - const size_t newsize = (orig.length()+1)*2; - char *nstring = new char[newsize]; + const size_t newsize = (orig.length() + 1) * 2; + char* nstring = new char[newsize]; // Uses the _bstr_t operator (char *) to obtain a null // terminated string from the _bstr_t object for // nstring. - strcpy_s(nstring, newsize, (char *)orig); + strcpy_s(nstring, newsize, (char*)orig); strcat_s(nstring, newsize, " (char *)"); cout << nstring << endl; + delete []nstring; // Prepare the type of string to append to the result. - wchar_t strConcat[] = _T(" (wchar_t *)"); + wchar_t strConcat[] = L" (wchar_t *)"; size_t strConcatLen = wcslen(strConcat) + 1; // Convert a _bstr_t to a wchar_t* string. - const size_t widesize = orig.length()+ strConcatLen; - wchar_t *wcstring = new wchar_t[newsize]; - wcscpy_s(wcstring, widesize, (wchar_t *)orig); + const size_t widesize = orig.length() + strConcatLen; + wchar_t* wcstring = new wchar_t[newsize]; + wcscpy_s(wcstring, widesize, (wchar_t*)orig); wcscat_s(wcstring, widesize, strConcat); wcout << wcstring << endl; + delete []wcstring; // Convert a _bstr_t string to a CComBSTR string. - CComBSTR ccombstr((char *)orig); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + CComBSTR ccombstr((char*)orig); + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { CW2A printstr(ccombstr); cout << printstr << endl; @@ -306,12 +342,12 @@ int main() wcout << (LPCTSTR)cstring << endl; // Convert the _bstr_t to a basic_string. - string basicstring((char *)orig); + string basicstring((char*)orig); basicstring += " (basic_string)"; cout << basicstring << endl; // Convert the _bstr_t to a System::String. - String ^systemstring = gcnew String((char *)orig); + String^ systemstring = gcnew String((char*)orig); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; @@ -329,17 +365,19 @@ Hello, World! (basic_string) Hello, World! (System::String) ``` -## Example: Convert from CComBSTR +## Example: Convert from `CComBSTR` ### Description -This example demonstrates how to convert from a `CComBSTR` to the other string types listed above. Like _bstr_t, a `CComBSTR` object is a way to encapsulate wide character BSTR strings. A BSTR string has a length value and does not use a null character to terminate the string, but the string type you convert to may require a terminating null. +This example demonstrates how to convert from a `CComBSTR` to other string types. Like `_bstr_t`, a `CComBSTR` object encapsulates wide character `BSTR` strings. A `BSTR` string has a length value and doesn't use a null character to terminate the string, but the string type you convert to may require a terminating null. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_ccombstr.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -367,31 +405,33 @@ int main() // regular multibyte char* string. Allocate enough space // in the new string for the largest possible result, // including space for a terminating null. - const size_t newsize = (orig.Length()+1)*2; - char *nstring = new char[newsize]; + const size_t newsize = (orig.Length() + 1) * 2; + char* nstring = new char[newsize]; // Create a string conversion object, copy the result to // the new char* string, and display the result. CW2A tmpstr1(orig); strcpy_s(nstring, newsize, tmpstr1); cout << nstring << " (char *)" << endl; + delete []nstring; // Prepare the type of string to append to the result. - wchar_t strConcat[] = _T(" (wchar_t *)"); + wchar_t strConcat[] = L" (wchar_t *)"; size_t strConcatLen = wcslen(strConcat) + 1; // Convert a wide character CComBSTR string to a wchar_t*. // The code first determines the length of the converted string // plus the length of the appended type of string, then // prepares the final wchar_t string for display. - const size_t widesize = orig.Length()+ strConcatLen; - wchar_t *wcstring = new wchar_t[widesize]; + const size_t widesize = orig.Length() + strConcatLen; + wchar_t* wcstring = new wchar_t[widesize]; wcscpy_s(wcstring, widesize, orig); wcscat_s(wcstring, widesize, strConcat); - // Display the result. Unlike CStringW, a wchar_t does not need + // Display the result. Unlike CStringW, a wchar_t doesn't need // a cast to (LPCTSTR) with wcout. wcout << wcstring << endl; + delete []wcstring; // Convert a wide character CComBSTR to a wide character _bstr_t, // append the type of string to it, and display the result. @@ -415,11 +455,11 @@ int main() // Convert a wide character CComBSTR to a wide character // basic_string. wstring basicstring(orig); - basicstring += _T(" (basic_string)"); + basicstring += L" (basic_string)"; wcout << basicstring << endl; // Convert a wide character CComBSTR to a System::String. - String ^systemstring = gcnew String(orig); + String^ systemstring = gcnew String(orig); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; @@ -437,19 +477,21 @@ Hello, World! (basic_string) Hello, World! (System::String) ``` -## Example: Convert from CString +## Example: Convert from `CString` ### Description -This example demonstrates how to convert from a `CString` to the other string types listed above. `CString` is based on the TCHAR data type, which in turn depends on whether the symbol `_UNICODE` is defined. If `_UNICODE` is not defined, `TCHAR` is defined to be char and `CString` contains a multibyte character string; if `_UNICODE` is defined, `TCHAR` is defined to be **`wchar_t`** and `CString` contains a wide character string. +This example demonstrates how to convert from a `CString` to other string types. `CString` is based on the `TCHAR` data type, which in turn depends on whether the symbol `_UNICODE` is defined. If `_UNICODE` isn't defined, `TCHAR` is defined to be `char` and `CString` contains a multibyte character string; if `_UNICODE` is defined, `TCHAR` is defined to be **`wchar_t`** and `CString` contains a wide character string. + +`CStringA` contains the `char` type and supports single-byte or multibyte strings. `CStringW` is the wide character version. `CStringA` and `CStringW` don't use `_UNICODE` to determine how they should compile. `CStringA` and `CStringW` are used in this example to clarify minor differences in buffer size allocation and output handling. -`CStringA` is the multibyte string always version of `CString`, `CStringW` is the wide character string only version. Neither `CStringA` nor `CStringW` use `_UNICODE` to determine how they should compile. `CStringA` and `CStringW` are used in this example to clarify minor differences in buffer size allocation and output handling. +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_cstring.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -470,41 +512,45 @@ int main() // Set up a wide character CStringW string. CStringW origw("Hello, World!"); - wcout << (LPCTSTR)origw << _T(" (CStringW)") << endl; + wcout << (LPCTSTR)origw << L" (CStringW)" << endl; // Convert to a char* string from CStringA string // and display the result. - const size_t newsizea = (origa.GetLength() + 1); - char *nstringa = new char[newsizea]; + const size_t newsizea = origa.GetLength() + 1; + char* nstringa = new char[newsizea]; strcpy_s(nstringa, newsizea, origa); cout << nstringa << " (char *)" << endl; + delete []nstringa; // Convert to a char* string from a wide character // CStringW string. To be safe, we allocate two bytes for each // character in the original string, including the terminating // null. - const size_t newsizew = (origw.GetLength() + 1)*2; - char *nstringw = new char[newsizew]; + const size_t newsizew = (origw.GetLength() + 1) * 2; + char* nstringw = new char[newsizew]; size_t convertedCharsw = 0; - wcstombs_s(&convertedCharsw, nstringw, newsizew, origw, _TRUNCATE ); + wcstombs_s(&convertedCharsw, nstringw, newsizew, origw, _TRUNCATE); cout << nstringw << " (char *)" << endl; + delete []nstringw; // Convert to a wchar_t* from CStringA size_t convertedCharsa = 0; - wchar_t *wcstring = new wchar_t[newsizea]; + wchar_t* wcstring = new wchar_t[newsizea]; mbstowcs_s(&convertedCharsa, wcstring, newsizea, origa, _TRUNCATE); - wcout << wcstring << _T(" (wchar_t *)") << endl; + wcout << wcstring << L" (wchar_t *)" << endl; + delete []wcstring; // Convert to a wide character wchar_t* string from // a wide character CStringW string. - wchar_t *n2stringw = new wchar_t[newsizew]; - wcscpy_s( n2stringw, newsizew, origw ); - wcout << n2stringw << _T(" (wchar_t *)") << endl; + wchar_t* n2stringw = new wchar_t[newsizew]; + wcscpy_s(n2stringw, newsizew, origw); + wcout << n2stringw << L" (wchar_t *)" << endl; + delete []n2stringw; // Convert to a wide character _bstr_t string from // a multibyte CStringA string. _bstr_t bstrt(origa); - bstrt += _T(" (_bstr_t)"); + bstrt += L" (_bstr_t)"; wcout << bstrt << endl; // Convert to a wide character _bstr_t string from @@ -516,7 +562,7 @@ int main() // Convert to a wide character CComBSTR string from // a multibyte character CStringA string. CComBSTR ccombstr(origa); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { // Convert the wide character string to multibyte // for printing. @@ -529,7 +575,7 @@ int main() CComBSTR ccombstrw(origw); // Append the type of string to it, and display the result. - if (ccombstrw.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstrw.Append(L" (CComBSTR)") == S_OK) { CW2A printstrw(ccombstrw); wcout << printstrw << endl; @@ -545,19 +591,19 @@ int main() // wide character version of a basic_string // string. wstring basicstringw(origw); - basicstringw += _T(" (basic_string)"); + basicstringw += L" (basic_string)"; wcout << basicstringw << endl; // Convert a multibyte character CStringA to a // System::String. - String ^systemstring = gcnew String(origa); + String^ systemstring = gcnew String(origa); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; // Convert a wide character CStringW to a // System::String. - String ^systemstringw = gcnew String(origw); + String^ systemstringw = gcnew String(origw); systemstringw += " (System::String)"; Console::WriteLine("{0}", systemstringw); delete systemstringw; @@ -579,17 +625,19 @@ Hello, World! (basic_string) Hello, World! (System::String) ``` -## Example: Convert from basic_string +## Example: Convert from `basic_string` ### Description -This example demonstrates how to convert from a `basic_string` to the other string types listed above. +This example demonstrates how to convert from a `basic_string` to other string types. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_basic_string.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -611,30 +659,33 @@ int main() // Convert a wide character basic_string string to a multibyte char* // string. To be safe, we allocate two bytes for each character // in the original string, including the terminating null. - const size_t newsize = (strlen(orig.c_str()) + 1)*2; - char *nstring = new char[newsize]; + const size_t newsize = (orig.size() + 1) * 2; + + char* nstring = new char[newsize]; strcpy_s(nstring, newsize, orig.c_str()); cout << nstring << " (char *)" << endl; + delete []nstring; // Convert a basic_string string to a wide character // wchar_t* string. You must first convert to a char* // for this to work. - const size_t newsizew = strlen(orig.c_str()) + 1; + const size_t newsizew = orig.size() + 1; size_t convertedChars = 0; - wchar_t *wcstring = new wchar_t[newsizew]; + wchar_t* wcstring = new wchar_t[newsizew]; mbstowcs_s(&convertedChars, wcstring, newsizew, orig.c_str(), _TRUNCATE); - wcout << wcstring << _T(" (wchar_t *)") << endl; + wcout << wcstring << L" (wchar_t *)" << endl; + delete []wcstring; // Convert a basic_string string to a wide character // _bstr_t string. _bstr_t bstrt(orig.c_str()); - bstrt += _T(" (_bstr_t)"); + bstrt += L" (_bstr_t)"; wcout << bstrt << endl; // Convert a basic_string string to a wide character // CComBSTR string. CComBSTR ccombstr(orig.c_str()); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { // Make a multibyte version of the CComBSTR string // and display the result. @@ -651,11 +702,11 @@ int main() // Convert a basic_string string into a wide // character CStringW string. CStringW cstringw(orig.c_str()); - cstringw += _T(" (CStringW)"); + cstringw += L" (CStringW)"; wcout << (LPCTSTR)cstringw << endl; // Convert a basic_string string to a System::String - String ^systemstring = gcnew String(orig.c_str()); + String^ systemstring = gcnew String(orig.c_str()); systemstring += " (System::String)"; Console::WriteLine("{0}", systemstring); delete systemstring; @@ -673,17 +724,19 @@ Hello, World! (CStringW) Hello, World! (System::String) ``` -## Example: Convert from System::String +## Example: Convert from `System::String` ### Description -This example demonstrates how to convert from a wide character (Unicode) [System::String](/dotnet/api/system.string) to the other string types listed above. +This example demonstrates how to convert from a wide character [System::String](/dotnet/api/system.string) to other string types. + +For information about running and debugging this example, see [Run the examples](#run-the-examples). ### Code ```cpp // convert_from_system_string.cpp -// compile with: /clr /link comsuppw.lib +// compile with: /clr /Zc:twoPhase- /link comsuppw.lib #include #include @@ -701,7 +754,7 @@ using namespace System::Runtime::InteropServices; int main() { // Set up a System::String and display the result. - String ^orig = gcnew String("Hello, World!"); + String^ orig = gcnew String("Hello, World!"); Console::WriteLine("{0} (System::String)", orig); // Obtain a pointer to the System::String in order to @@ -715,18 +768,20 @@ int main() // output string for every wide character in the input // string, including space for a terminating null. size_t origsize = wcslen(wch) + 1; - const size_t newsize = origsize*2; + const size_t newsize = origsize * 2; size_t convertedChars = 0; - char *nstring = new char[newsize]; + char* nstring = new char[newsize]; wcstombs_s(&convertedChars, nstring, newsize, wch, _TRUNCATE); cout << nstring << " (char *)" << endl; + delete []nstring; // Convert a wide character System::String to a // wide character wchar_t* string. const size_t newsizew = origsize; - wchar_t *wcstring = new wchar_t[newsizew]; + wchar_t* wcstring = new wchar_t[newsizew]; wcscpy_s(wcstring, newsizew, wch); - wcout << wcstring << _T(" (wchar_t *)") << endl; + wcout << wcstring << L" (wchar_t *)" << endl; + delete []wcstring; // Convert a wide character System::String to a // wide character _bstr_t string. @@ -737,7 +792,7 @@ int main() // Convert a wide character System::String // to a wide character CComBSTR string. CComBSTR ccombstr(wch); - if (ccombstr.Append(_T(" (CComBSTR)")) == S_OK) + if (ccombstr.Append(L" (CComBSTR)") == S_OK) { // Make a multibyte copy of the CComBSTR string // and display the result. @@ -760,7 +815,7 @@ int main() // Convert a wide character System::String to // a wide character basic_string. wstring basicstring(wch); - basicstring += _T(" (basic_string)"); + basicstring += L" (basic_string)"; wcout << basicstring << endl; delete orig; @@ -778,16 +833,32 @@ Hello, World! (CStringW) Hello, World! (basic_string) ``` +## Converting between narrow and wide strings + +Legacy C and Windows apps use code pages rather than Unicode encodings when handling narrow strings and wide strings. + +.NET strings are UTF-16, but ATL's `CStringA` is a narrow string, and the conversion from wide to narrow is performed by the [`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) Win32 function. When converting a C-style `CHAR*` (a C-style `CHAR*` is a .NET `byte*`) to a string, the opposite Win32 function, [`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) is called. + +Both functions rely on the Windows concept of a code page; not the .NET concept of a culture. To change the system code page, use the region setting using **Control Panel** > enter `Region` into the search box > **Region (change date, time, or number formats)** > **Administrative** > **Change system locale**. + +On an `en-US` language version of Windows, the code page defaults to 1033. If you install a different language of Windows, it will have a different code page. You can change it using the control panel. + +There's a mismatch in the way that `CStringA` performs a wide to narrow conversion and the way that `gcnew string(CHAR*)` performs a narrow to wide conversion. `CStringA` passes `CP_THREAD_ACP`, which means to use the current *thread* code page, to the narrowing conversion method. But `string.ctor(sbyte*)` passes `CP_ACP`, which means to use the current *system* code page, to the widening conversion method. If the system and thread code pages don't match, it can cause round-trip data corruption. + +To reconcile this difference, use the constant `_CONVERSION_DONT_USE_THREAD_LOCALE`) to get the conversion to use `CP_ACP` (like .NET) instead of `CP_THREAD_ACP`. For more information, see [`_CONVERSION_DONT_USE_THREAD_LOCALE`](https://social.msdn.microsoft.com/Forums/vstudio/en-US/f3820781-c418-40bf-8c4f-7250001e5b68/visual-studio-2015-update-1-implicit-string-narrow-wide-conversion-and). + +Another approach is to use [`pinvoke`](/dotnet/standard/native-interop/pinvoke) to call [`GetThreadLocale`](/windows/win32/api/winnls/nf-winnls-getthreadlocale). Use the returned `LCID` to create a [`CultureInfo`](/dotnet/api/system.globalization.cultureinfo). Then use `CultureInfo.TextInfo` to get the code page to use in the conversion. + ## See also -[ATL and MFC String Conversion Macros](../atl/reference/string-conversion-macros.md)
-[CString Operations Relating to C-Style Strings](../atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md)
-[How to: Convert Standard String to System::String](../dotnet/how-to-convert-standard-string-to-system-string.md)
-[How to: Convert System::String to Standard String](../dotnet/how-to-convert-system-string-to-standard-string.md)
-[How to: Convert System::String to wchar_t* or char\*](../dotnet/how-to-convert-system-string-to-wchar-t-star-or-char-star.md)
-[Programming with CComBSTR](../atl/programming-with-ccombstr-atl.md)
-[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)
-[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)
-[strcpy_s, wcscpy_s, _mbscpy_s](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)
-[strcat_s, wcscat_s, _mbscat_s](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)
-[pin_ptr (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) +[ATL and MFC string conversion macros](../atl/reference/string-conversion-macros.md)\ +[`CString` operations relating to C-style strings](../atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md)\ +[How to: convert standard `String` to `System::String`](../dotnet/how-to-convert-standard-string-to-system-string.md)\ +[How to: convert `System::String` to standard `String`](../dotnet/how-to-convert-system-string-to-standard-string.md)\ +[How to: convert `System::String` to `wchar_t*` or `char*`](../dotnet/how-to-convert-system-string-to-wchar-t-star-or-char-star.md)\ +[Programming with `CComBSTR`](../atl/programming-with-ccombstr-atl.md)\ +[`mbstowcs_s`, `_mbstowcs_s_l`](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)\ +[`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)\ +[`strcat_s`, `wcscat_s`, `_mbscat_s`](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)\ +[`pin_ptr` (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) diff --git a/docs/text/support-for-multibyte-character-sets-mbcss.md b/docs/text/support-for-multibyte-character-sets-mbcss.md index 5b1d9cd4de..2520d3d343 100644 --- a/docs/text/support-for-multibyte-character-sets-mbcss.md +++ b/docs/text/support-for-multibyte-character-sets-mbcss.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Support for Multibyte Character Sets (MBCSs)" title: "Support for Multibyte Character Sets (MBCSs)" +description: "Learn more about: Support for Multibyte Character Sets (MBCSs)" ms.date: "11/04/2016" helpviewer_keywords: ["MBCS [C++], about MBCS", "character sets [C++], multibyte", "multibyte characters [C++]", "MBCS [C++]"] -ms.assetid: b498733c-a1e1-45e3-8f26-d6da3cb5f2dd --- # Support for Multibyte Character Sets (MBCSs) @@ -36,7 +35,7 @@ The C run-time library and MFC support single-byte, MBCS, and Unicode programmin ### MBCS/Unicode portability -Using the tchar.h header file, you can build single-byte, MBCS, and Unicode applications from the same sources. Tchar.h defines macros prefixed with *_tcs* , which map to `str`, `_mbs`, or `wcs` functions, as appropriate. To build MBCS, define the symbol `_MBCS`. To build Unicode, define the symbol `_UNICODE`. By default, `_UNICODE` is defined for MFC applications. For more information, see [Generic-Text Mappings in tchar.h](../text/generic-text-mappings-in-tchar-h.md). +Using the tchar.h header file, you can build single-byte, MBCS, and Unicode applications from the same sources. Tchar.h defines macros prefixed with *_tcs*, which map to `str`, `_mbs`, or `wcs` functions, as appropriate. To build MBCS, define the symbol `_MBCS`. To build Unicode, define the symbol `_UNICODE`. By default, `_UNICODE` is defined for MFC applications. For more information, see [Generic-Text Mappings in tchar.h](../text/generic-text-mappings-in-tchar-h.md). > [!NOTE] > Behavior is undefined if you define both `_UNICODE` and `_MBCS`. @@ -59,5 +58,5 @@ For international portability, code your program with [Unicode](../text/support- ## See also -[Text and Strings](../text/text-and-strings-in-visual-cpp.md)
+[Text and Strings](../text/text-and-strings-in-visual-cpp.md)\ [MBCS Support in Visual C++](../text/mbcs-support-in-visual-cpp.md) diff --git a/docs/windows/adding-editing-or-deleting-controls.md b/docs/windows/adding-editing-or-deleting-controls.md index e068e19ef6..92993bd1f9 100644 --- a/docs/windows/adding-editing-or-deleting-controls.md +++ b/docs/windows/adding-editing-or-deleting-controls.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How To: Add, Edit, or Delete Controls (C++)" title: "How To: Add, Edit, or Delete Controls (C++)" +description: "Learn more about: How To: Add, Edit, or Delete Controls (C++)" ms.date: "02/15/2019" f1_keywords: ["vc.controls.activex", "vc.editors.dialog.insertActiveXControls"] helpviewer_keywords: ["Dialog Editor [C++], creating controls", "dialog boxes [C++], adding controls to", "Toolbox [C++], Dialog Editor tab", "controls [C++], types", "syslink controls in dialog boxes", "custom controls [C++], dialog boxes", "controls [C++], standard", "Dialog Editor [C++], creating controls", "controls [C++], adding to dialog boxes", "controls [C++], adding multiple", "dialog box controls [C++], size", "controls [C++], sizing", "dialog boxes [C++], adding ActiveX controls", "ActiveX controls [C++], adding to dialog boxes", "Insert ActiveX Control dialog box [C++]", "controls [C++], editing properties", "ActiveX controls [C++], properties", "controls [C++], undoing changes", "controls [C++], editing properties", "dialog box controls [C++], editing properties", "dialog box controls [C++], deleting", "controls [C++], deleting", "Dialog Editor [C++], default control events", "controls [C++], default control events", "events [C++], controls", "dialog box controls [C++], events", "member variables, defining for controls", "variables, dialog box control member variables", "controls [C++], member variables", "Dialog Editor [C++], defining member variables for controls", "controls [C++], troubleshooting", "Dialog Editor [C++], troubleshooting", "dialog boxes [C++], troubleshooting", "InitCommonControls", "RichEdit 1.0 control", "rich edit controls [C++], RichEdit 1.0"] -ms.assetid: 73cef03f-5c8c-456a-87d1-1458dff185cf --- # How To: Add, Edit, or Delete Controls (C++) @@ -204,17 +203,17 @@ Win32 ## See also -[Manage Dialog Box Controls](controls-in-dialog-boxes.md)
-[How To: Layout Controls](arrangement-of-controls-on-dialog-boxes.md)
+[Manage Dialog Box Controls](controls-in-dialog-boxes.md)\ +[How To: Layout Controls](arrangement-of-controls-on-dialog-boxes.md)\ [How to: Define Control Access and Values](defining-mnemonics-access-keys.md) diff --git a/docs/windows/arrangement-of-controls-on-dialog-boxes.md b/docs/windows/arrangement-of-controls-on-dialog-boxes.md index 7bdc8e9945..7dbf3020fe 100644 --- a/docs/windows/arrangement-of-controls-on-dialog-boxes.md +++ b/docs/windows/arrangement-of-controls-on-dialog-boxes.md @@ -1,6 +1,6 @@ --- description: "Learn more about: How To: Layout Controls (C++)" -title: "How To: Layout Controls (C++)| Microsoft Docs" +title: "How To: Layout Controls (C++)" ms.date: "02/15/2019" f1_keywords: ["vc.editors.dialog.grouping", "vc.editors.dialog.combo"] helpviewer_keywords: ["controls [C++], positioning", "dialog box controls [C++], placement", "Dialog Editor [C++], arranging controls", "Dialog Editor [C++], guides and margins", "guides, clearing", "guides", "dialog box controls [C++], placement", "controls [C++], guides and margins", "guides, creating", "guides, moving", "margins, moving", "DLUs (dialog units)", "controls [C++], aligning", "Dialog Editor [C++], snap to guides", "guides, tick mark interval", "dialog box controls [C++], placement", "guides, aligning controls", "dialog units (DLUs)", "snap to guides (Dialog editor)", "controls [C++], sizing", "tick mark interval in Dialog editor", "controls [C++], snap to guides/grid", "guides, disabling snapping", "controls [C++], snap to guides/grid", "controls [C++], layout grid", "snap to layout grid", "grids, turning on or off", "layout grid in Dialog Editor", "grids, changing size", "grid spacing", "guides, settings", "layout grid in Dialog Editor", "controls [C++], snap to guides/grid", "Guide Settings dialog box (Dialog editor)", "controls [C++], aligning", "controls [C++], positioning", "Space Evenly command", "dialog box controls [C++], placement", "Center in Dialog command", "Arrange Buttons command", "buttons, arranging push buttons in dialog boxes", "push buttons", "member variables, adding to radio button groups", "variables, dialog box control member variables", "dialog box controls [C++], grouping radio buttons", "grouping controls", "radio buttons [C++], grouping on dialog boxes", "controls [C++], tab order", "focus, tab order", "tab controls [C++], tab order", "Tabstop property for controls", "controls [C++], focus", "dialog box controls [C++], tab order", "Dialog Editor [C++], selecting controls", "dominant controls", "dialog box controls [C++], selecting in editor", "controls [C++], selecting", "size, controls", "controls [C++], dominant", "controls [C++], removing from groups", "Dialog Editor [C++], dominant control", "Size to Content command", "size, controls", "text, autosizing controls to fit text", "controls [C++], sizing", "Make Same Size command", "combo boxes, sizing", "list controls [C++], scroll bar width", "CListBox::SetHorizontalExtent", "controls [C++], scroll bar", "scroll bars [C++], displaying in controls", "horizontal scroll bar width", "CListBox class, scroll bar width", "scroll bars [C++], width"] diff --git a/docs/windows/attributes/attribute-programming-faq.yml b/docs/windows/attributes/attribute-programming-faq.yml index c6189a529d..2ab4aebf24 100644 --- a/docs/windows/attributes/attribute-programming-faq.yml +++ b/docs/windows/attributes/attribute-programming-faq.yml @@ -3,10 +3,9 @@ metadata: description: "Learn more about: Attribute programming FAQ" title: "Attribute Programming FAQ" ms.date: "10/02/2018" - ms.topic: "conceptual" + ms.topic: faq helpviewer_keywords: ["attributed programming", "attributes [C++/CLI], frequently asked questions", "FAQs (frequently asked questions), attributed programming [C++]"] ms.assetid: a1b8349f-7f51-43c4-95ea-4edb6e5f243f - title: Attribute programming FAQ summary: | diff --git a/docs/windows/attributes/cpp-attributes-com-net.md b/docs/windows/attributes/cpp-attributes-com-net.md index 822412ed44..830c975df1 100644 --- a/docs/windows/attributes/cpp-attributes-com-net.md +++ b/docs/windows/attributes/cpp-attributes-com-net.md @@ -52,7 +52,7 @@ The following figure demonstrates the relationship between the compiler and the ![Diagram showing component attribute communication.](../media/vccompattrcomm.gif "Component attribute communication") > [!NOTE] -> Attribute usage does not alter the contents of the source file. The only time the generated attribute code is visible is during debugging sessions. In addition, for each source file in the project, you can generate a text file that displays the results of the attribute substitution. For more information on this procedure, see [/Fx (Merge Injected Code)](../../build/reference/fx-merge-injected-code.md) and [Debugging Injected Code](/visualstudio/debugger/how-to-debug-injected-code). +> Attribute usage does not alter the contents of the source file. The only time the generated attribute code is visible is during debugging sessions. In addition, for each source file in the project, you can generate a text file that displays the results of the attribute substitution. For more information on this procedure, see [`/Fx` (Merge Injected Code)](../../build/reference/fx-merge-injected-code.md) and [Debug injected code](#debug-injected-code). Like most C++ constructs, attributes have a set of characteristics that defines their proper usage. This is referred to as the context of the attribute and is addressed in the attribute context table for each attribute reference topic. For example, the [coclass](coclass.md) attribute can only be applied to an existing class or structure, as opposed to the [cpp_quote](cpp-quote.md) attribute, which can be inserted anywhere within a C++ source file. @@ -94,6 +94,38 @@ This field lists other attributes that need to be present (that is, applied to t This field lists other attributes that are incompatible with the specified attribute. It is uncommon for an attribute to have any entries for this field. +## Debug injected code + +Using attributes can greatly simplify C++ programming. For more information, see [Concepts](/cpp/windows/attributed-programming-concepts). Some attributes are interpreted directly by the compiler. Other attributes inject code into the program source, which the compiler then compiles. This injected code makes programming easier by reducing the amount of code you have to write. Sometimes, however, a bug may cause your application to fail while it is executing injected code. When this happens, you will probably want to look at the injected code. Visual Studio provides two ways for you to see injected code: + +- You can view injected code in the **Disassembly** window. + +- Using [/Fx](/cpp/build/reference/fx-merge-injected-code), you can create a merged source file that contains original and injected code. + +The **Disassembly** window shows assembly-language instructions that correspond to the source code and the code injected by attributes. In addition, the **Disassembly** window can show the source-code annotation. + +### To turn on Source Annotation + +- Right-click the **Disassembly** window, and choose **Show Source Code** from the shortcut menu. + + If you know the location of an attribute in a source window, you can use the shortcut menu to find the injected code in the **Disassembly** window. + +### To view injected code + +1. The debugger must be in break mode. + +2. In a source code window, place the cursor in front of the attribute whose injected code you want to view. + +3. Right-click, and select **Go To Disassembly** from the shortcut menu. + + If the attribute location is near the current execution point, you can select the **Disassembly** window from the **Debug** menu. + +### To view the disassembly code at the current execution point + +1. The debugger must be in break mode. + +2. From the **Debug** menu, choose **Windows**, and click **Disassembly**. + ## In This Section [Attribute Programming FAQ](attribute-programming-faq.yml)
diff --git a/docs/windows/attributes/db-command.md b/docs/windows/attributes/db-command.md index e2ae846c99..0ed4d8afc7 100644 --- a/docs/windows/attributes/db-command.md +++ b/docs/windows/attributes/db-command.md @@ -1,32 +1,31 @@ --- description: "Learn more about: db_command" title: "db_command (C++ COM Attribute)" -ms.date: "07/10/2018" +ms.date: 06/29/2022 f1_keywords: ["vc-attr.db_command"] helpviewer_keywords: ["db_command attribute"] ms.assetid: 714c3e15-85d7-408b-9a7c-88505c3e5d24 --- -# db_command +# `db_command` Creates an OLE DB command. ## Syntax ```cpp -[ db_command(command, name, source_name, hresult, bindings, bulk_fetch) -] +[ db_command(command, name, source_name, hresult, bindings, bulk_fetch) ] ``` ### Parameters -*command*
+*`command`*\ A command string containing the text of an OLE DB command. A simple example is: ```cpp [ db_command ( command = "Select * from Products" ) ] ``` -The *command* syntax is as follows: +The *`command`* syntax is as follows: > binding parameter block 1\ >   OLE DB command\ @@ -37,36 +36,36 @@ The *command* syntax is as follows: A *binding parameter block* is defined as follows: -> **(\[** *bindtype* **]** *szVar1* \[, *szVar2* \[, *nVar3* \[, ...]]] **)** +> **`(`** *`bindtype`* *szVar1* \[**`,`** *szVar2* \[**`,`** *nVar3* \[**`,`** ...]]] **`)`** where: -- **(** marks the start of the data binding block. +- **`(`** marks the start of the data binding block. -- **\[** *bindtype* **]** is one of the following case-insensitive strings: +- *`bindtype`* is one of the following case-insensitive strings: - - **\[db_column]** binds each of the member variables to a column in a rowset. + - **`[db_column]`** binds each of the member variables to a column in a rowset. - - **\[bindto]** (same as **\[db_column]**). + - **`[bindto]`** (same as **`[db_column]`**). - - **\[in]** binds member variables as input parameters. + - **`[in]`** binds member variables as input parameters. - - **\[out]** binds member variables as output parameters. + - **`[out]`** binds member variables as output parameters. - - **\[in,out]** binds member variables as input/output parameters. + - **`[in,out]`** binds member variables as input/output parameters. -- *szVarX*, *nVarX* resolves to a member variable within the current scope. +- *szVarN*, *nVarN* resolve to member variables within the current scope. -- **)** marks the end of the data binding block. +- **`)`** marks the end of the data binding block. -If the command string contains one or more specifiers such as \[in], \[out], or \[in/out], **db_command** builds a parameter map. +If the command string contains one or more specifiers such as `[in]`, `[out]`, or `[in/out]`, **`db_command`** builds a parameter map. -If the command string contains one or more parameters such as \[db_column] or \[bindto], **db_command** generates a rowset and an accessor map to service these bound variables. See [db_accessor](db-accessor.md) for more information. +If the command string contains one or more parameters such as `[db_column]` or `[bindto]`, then **`db_command`** generates both a rowset and an accessor map to service these bound variables. For more information, see [`db_accessor`](db-accessor.md). > [!NOTE] -> \[*bindtype*] syntax and the *bindings* parameter are not valid when using **db_command** at the class level. +> *`bindtype`* syntax and the *`bindings`* parameter are not valid when using **`db_command`** at the class level. -Here are some examples of binding parameter blocks. The following example binds the `m_au_fname` and `m_au_lname` data members to the `au_fname` and `au_lname` columns, respectively, of the authors table in the pubs database: +Here are some examples of binding parameter blocks. The following example binds the `m_au_fname` and `m_au_lname` data members to the `au_fname` and `au_lname` columns, respectively, of the authors table in the `pubs` database: ```cpp TCHAR m_au_fname[21]; @@ -79,48 +78,50 @@ TCHAR m_state[3] = 'CA'; ] ``` -*name*
-(Optional) The name of the handle you use to work with the rowset. If you specify *name*, **db_command** generates a class with the specified *name*, which can be used to traverse the rowset or to execute multiple action queries. If you do not specify *name*, it will not be possible to return more than one row of results to the user. +*`name`*\ +(Optional) The name of the handle you use to work with the rowset. If you specify *`name`*, **`db_command`** generates a class with the specified *`name`*, which can be used to traverse the rowset or to execute multiple action queries. If you don't specify *`name`*, it will not be possible to return more than one row of results to the user. -*source_name*
-(Optional) The `CSession` variable or instance of a class that has the `db_source` attribute applied to it on which the command executes. See [db_source](db-source.md). +*`source_name`*\ +(Optional) The `CSession` variable or instance of a class that has the `db_source` attribute applied to it on which the command executes. See [`db_source`](db-source.md). -**db_command** checks to ensure that the variable used for *source_name* is valid, so the specified variable should be in function or global scope. +**`db_command`** checks to ensure that the variable used for *`source_name`* is valid, so the specified variable should be in function or global scope. -*hresult*
-(Optional) Identifies the variable that will receive the HRESULT of this database command. If the variable does not exist, it will be automatically injected by the attribute. +*`hresult`*\ +(Optional) Identifies the variable that will receive the HRESULT of this database command. If the variable doesn't exist, it will be automatically injected by the attribute. -*bindings*
+*`bindings`*\ (Optional) Allows you to separate the binding parameters from the OLE DB command. -If you specify a value for *bindings*, **db_command** will parse the associated value and will not parse the \[*bindtype*] parameter. This usage allows you to use OLE DB provider syntax. To disable parsing, without binding parameters, specify `Bindings=""`. +If you specify a value for *`bindings`*, **`db_command`** parses the associated value and doesn't parse the *`bindtype`* parameter. This usage allows you to use OLE DB provider syntax. To disable parsing without binding parameters, specify `Bindings=""`. -If you do not specify a value for *bindings*, **db_command** will parse the binding parameter block, looking for '**(**', followed by **\[**_bindtype_**]** in brackets, followed by one or more previously declared C++ member variables, followed by '**)**'. All text between the parentheses will be stripped from the resulting command, and these parameters will be used to construct column and parameter bindings for this command. +If you don't specify a value for *`bindings`*, **`db_command`** parses the binding parameter block. It looks for '**`(`**', followed by a *`bindtype`* in brackets, followed by one or more previously declared C++ member variables, followed by '**`)`**'. It strips all text between the parentheses from the resulting command. These parameters are used to construct column and parameter bindings for this command. -*bulk_fetch*
+*`bulk_fetch`*\ (Optional) An integer value that specifies the number of rows to fetch. -The default value is 1, which specifies single row fetching (the rowset will be of type [CRowset](../../data/oledb/crowset-class.md)). +The default value is 1, which specifies single row fetching (the rowset will be of type [`CRowset`](../../data/oledb/crowset-class.md)). -A value greater than 1 specifies bulk row fetching. Bulk row fetching refers to the ability of bulk rowsets to fetch multiple row handles (the rowset will be of type [CBulkRowset](../../data/oledb/cbulkrowset-class.md) and will call `SetRows` with the specified number of rows). +A value greater than 1 specifies bulk row fetching. Bulk row fetching refers to the ability of bulk rowsets to fetch multiple row handles (the rowset will be of type [`CBulkRowset`](../../data/oledb/cbulkrowset-class.md) and will call `SetRows` with the specified number of rows). -If *bulk_fetch* is less than one, `SetRows` will return zero. +If *`bulk_fetch`* is less than one, `SetRows` will return zero. ## Remarks -**db_command** creates a [CCommand](../../data/oledb/ccommand-class.md) object, which is used by an OLE DB consumer to execute a command. +**`db_command`** creates a [`CCommand`](../../data/oledb/ccommand-class.md) object, which is used by an OLE DB consumer to execute a command. -You can use **db_command** with either class or function scope; the main difference is the scope of the `CCommand` object. With function scope, data such as bindings terminate at function end. Both class and function scope usages involve the OLE DB Consumer Template class `CCommand<>`, but the template arguments differ for the function and class cases. In the function case, bindings will be made to an `Accessor` that comprises local variables, while the class usage will infer a `CAccessor`-derived class as the argument. When used as a class attribute, **db_command** works in conjunction with **db_column**. +You can use **`db_command`** with either class or function scope; the main difference is the scope of the `CCommand` object. With function scope, data such as bindings terminate at function end. Both class and function scope usages involve the OLE DB Consumer Template class `CCommand<>`, but the template arguments differ for the function and class cases. In the function case, bindings will be made to an `Accessor` that comprises local variables, while the class usage will infer a `CAccessor`-derived class as the argument. When used as a class attribute, **`db_command`** works together with **`db_column`**. -**db_command** can be used to execute commands that do not return a result set. +**`db_command`** can be used to execute commands that don't return a result set. -When the consumer attribute provider applies this attribute to a class, the compiler will rename the class to \_*YourClassName*Accessor, where *YourClassName* is the name you gave the class, and the compiler will also create a class called *YourClassName*, which derives from \_*YourClassName*Accessor. In Class View, you will see both classes. +When the consumer attribute provider applies this attribute to a class, the compiler renames the class to `_[YourClassName]Accessor`, where `[YourClassName]` is the name you gave the class. The compiler also creates a class called `[YourClassName]`, which derives from `_[YourClassName]Accessor`. In Class View, you'll see both classes. ## Examples -This sample defines a command that selects the first and last names from a table where the state column matches 'CA'. **db_command** creates and reads a rowset on which you can call wizard-generated functions such as [OpenAll and CloseAll](../../data/oledb/consumer-wizard-generated-methods.md), as well as `CRowset` member functions such as [MoveNext](../../data/oledb/crowset-class.md#movenext). +This sample defines a command that selects the first and last names from a table where the state column matches 'CA'. **`db_command`** creates and reads a rowset on which you can call wizard-generated functions such as [`OpenAll` and `CloseAll`](../../data/oledb/consumer-wizard-generated-methods.md), as well as `CRowset` member functions such as [`MoveNext`](../../data/oledb/crowset-class.md#movenext). + +This code requires you to provide your own connection string that connects to the `pubs` database. For information on how to provide a connection string in the development environment, see [How to: Connect to a database and browse existing objects](/sql/ssdt/how-to-connect-to-a-database-and-browse-existing-objects) and [Add new connections](/visualstudio/data-tools/add-new-connections). -Note that this code requires you to provide your own connection string that connects to the pubs database. For information on how to do this in the development environment, see [How to: Connect to a Database and Browse Existing Objects](/sql/ssdt/how-to-connect-to-a-database-and-browse-existing-objects) and [Add new connections](/visualstudio/data-tools/add-new-connections). +Source file `db_command.h`: ```cpp // db_command.h @@ -156,6 +157,8 @@ struct CAuthors { }; ``` +Source file `db_command.cpp`: + ```cpp // db_command.cpp // compile with: /c @@ -228,15 +231,15 @@ int main() { ## Requirements | Attribute context | Value | -|-|-| -|**Applies to**|**`class`**, **`struct`**, member, method, local| -|**Repeatable**|No| -|**Required attributes**|None| -|**Invalid attributes**|None| +|--|--| +| **Applies to** | **`class`**, **`struct`**, member, method, local | +| **Repeatable** | No | +| **Required attributes** | None | +| **Invalid attributes** | None | -For more information about the attribute contexts, see [Attribute Contexts](cpp-attributes-com-net.md#contexts). +For more information about the attribute contexts, see [Attribute contexts](cpp-attributes-com-net.md#contexts). ## See also -[OLE DB Consumer Attributes](ole-db-consumer-attributes.md)
-[Stand-Alone Attributes](stand-alone-attributes.md) +[OLE DB consumer attributes](ole-db-consumer-attributes.md)\ +[Stand-alone attributes](stand-alone-attributes.md) diff --git a/docs/windows/attributes/module-cpp.md b/docs/windows/attributes/module-cpp.md index 5f6b6ff712..70f4175240 100644 --- a/docs/windows/attributes/module-cpp.md +++ b/docs/windows/attributes/module-cpp.md @@ -21,7 +21,7 @@ Defines the library block in the .idl file. *type*
(Optional) Can be one of the following: -- `dll` Adds functions and classes that allow the resulting DLL to function as a in-process COM server. This is the default value. +- `dll` Adds functions and classes that allow the resulting DLL to function as an in-process COM server. This is the default value. - `exe` Adds functions and classes that allow the resulting executable to function as a out of process COM server. diff --git a/docs/windows/binary-editor.md b/docs/windows/binary-editor.md index 5229957fbb..768618d831 100644 --- a/docs/windows/binary-editor.md +++ b/docs/windows/binary-editor.md @@ -11,14 +11,16 @@ ms.assetid: 2483c48b-1252-4dbc-826b-82e6c1a0e9cb > [!CAUTION] > Editing resources such as dialog boxes, images, or menus in the **Binary Editor** is dangerous. Incorrect editing could corrupt the resource, making it unreadable in its native editor. -The **Binary Editor** allows you to edit any resource at the binary level in either hexadecimal or ASCII format. You can also use the [Find command](/visualstudio/ide/reference/find-command) to search for either ASCII strings or hexadecimal bytes. Use the **Binary Editor** only when you need to view or make minor changes to custom resources or resource types not supported by the Visual Studio environment. The **Binary Editor** is not available in Express editions. +The **Binary Editor** allows you to edit any resource at the binary level in either hexadecimal or ASCII format. You can also use the [Find command](/visualstudio/ide/reference/find-command) to search for either ASCII strings or hexadecimal bytes. Use the **Binary Editor** only when you need to view or make minor changes to custom resources or resource types not supported by the Visual Studio environment. The **Binary Editor** isn't available in Express editions. - To open the **Binary Editor** on a new file, go to menu **File** > **New** > **File**, select the type of file you want to edit, then select the drop arrow next to the **Open** button, and choose **Open With** > **Binary Editor**. The dropdown selection in the New file dialog isn't available in Visual Studio 2019, but is available in Visual Studio 2022. - To open the **Binary Editor** on an existing file, go to menu **File** > **Open** > **File**, select the file you want to edit, then select the drop arrow next to the **Open** button, and choose **Open With** > **Binary Editor**. - ![Binary Editor.](../mfc/media/vcbinaryeditor2.gif "vcBinaryEditor2")
- Binary data for a dialog box displayed in the **Binary Editor** + :::image type="complex" source="../mfc/media/vcbinaryeditor2.gif" alt-text="Screenshot of the Binary Editor."::: + The binary editor is open on a file called Scribble.rc. mydata.rc. The file is split into three sections. The left section shows the address from the start of the file. The middle section shows columns of hexadecimal values from the file. The right section shows the ASCII characters that correspond to the hexadecimal values. + :::image-end::: + Binary data for a dialog box displayed in the **Binary Editor** Only certain ASCII values are represented in the **Binary Editor** (0x20 through 0x7E). Extended characters are displayed as periods in the right panel ASCII value section of the **Binary Editor**. The printable characters are ASCII values 32 through 126. @@ -80,7 +82,7 @@ You can create a new custom or data resource by placing the resource in a separa 1. [Create a .rc file](how-to-create-a-resource-script-file.md) that contains the custom or data resource. - You can type custom data in a .rc file as null-terminated quoted strings, or as integers in decimal, hexadecimal, or octal format. + You can type custom data in an `.rc` file as null-terminated quoted strings, or as integers in decimal, hexadecimal, or octal format. 1. In **Solution Explorer**, right-click your project's .rc file and select **Resource Includes**. diff --git a/docs/windows/choosing-a-deployment-method.md b/docs/windows/choosing-a-deployment-method.md index 6f7e86aad0..81d7305b19 100644 --- a/docs/windows/choosing-a-deployment-method.md +++ b/docs/windows/choosing-a-deployment-method.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: Choosing a Deployment Method" -title: "Choosing a Deployment Method" -ms.date: "03/14/2019" +description: "Learn more about: Choosing a deployment method" +title: "Choose a deployment method" +ms.date: 06/28/2022 helpviewer_keywords: ["redistributing DLLs", "manifests [C++]", "DLLs [C++], redistributing", "side-by-side assemblies [C++]", "dynamic linking [C++]", "application deployment [C++], methods", "deploying applications [C++], methods", "static linking [C++]", "libraries [C++], application deployment issues"] ms.assetid: fd8eb956-f4a0-4ffb-b401-328c73e66986 --- -# Choosing a Deployment Method +# Choose a deployment method -Unless your Visual C++ application is self-contained and can be deployed by using a copy command, we recommend that you use Windows Installer for deployment. Windows Installer supports installation, repair, and uninstallation, and also supports atomic updating of application files, dependencies, and registry entries. +We recommend that you use Windows Installer for deployment. Windows Installer supports installation, repair, and uninstallation, and also supports atomic updating of application files, dependencies, and registry entries. Unless your Visual C++ application is self-contained and can be deployed by using a copy command, use Windows Installer. > [!NOTE] -> Although [ClickOnce](/visualstudio/deployment/clickonce-security-and-deployment) deployment for Visual C++ native applications is possible in Visual Studio, it requires extra steps. For more information, see [ClickOnce Deployment for Visual C++ Applications](clickonce-deployment-for-visual-cpp-applications.md). +> Although [ClickOnce](/visualstudio/deployment/clickonce-security-and-deployment) deployment for Visual C++ native applications is possible in Visual Studio, it requires extra steps. For more information, see [ClickOnce deployment for Visual C++ applications](clickonce-deployment-for-visual-cpp-applications.md). -## Visual C++ Libraries are Shared DLLs +## Visual C++ libraries are shared DLLs -Because Visual C++ libraries are installed in the %windir%\system32\ directory by the Visual Studio installer, when you develop a Visual C++ application that depends on them, it will run as expected. However, to deploy the application to computers that may not have Visual Studio, we recommend that you ensure that the libraries are installed on those computers together with the application. +Because Visual C++ libraries are installed in the *`%windir%\system32\`* directory by the Visual Studio installer, when you develop a Visual C++ application that depends on them, it will run as expected. However, most computers don't have Visual Studio installed. To deploy the application to these computers, we recommend that you ensure that the libraries are installed together with your application. -## Redistributing Visual C++ Libraries +## Redistributable Visual C++ libraries In your deployments, you can redistribute any version of a Visual C++ library that's licensed for redistribution. Here are three ways to deploy them: -- Central deployment by using redistributable packages, which installs Visual C++ libraries as shared DLLs in %windir%\system32\\. (Installation in this folder requires administrator rights.) You can create a script or setup program that runs the redistributable package before installing your application on the target computer. Redistributable packages are available for the x86, x64, and ARM platforms (VCRedist_x86.exe, VCRedist_x64.exe, or VCRedist_arm.exe). Visual Studio includes these packages in %ProgramFiles(x86)%\Microsoft Visual Studio `version`\VC\Redist\\`locale ID`\\. You can also download them from the [Microsoft Download Center](https://www.microsoft.com/download). (Use the search box in the Download Center to search for the "Visual C++ Redistributable Package *Visual Studio version and update*" that matches your application. For example, if you used Visual Studio 2015 update 3 to build your application, then search for "Visual C++ Redistributable Package 2015 update 3".) For information about how to use a redistributable package, see [Walkthrough: Deploying a Visual C++ Application By Using the Visual C++ Redistributable Package](deploying-visual-cpp-application-by-using-the-vcpp-redistributable-package.md). +- Central deployment by using Visual C++ Redistributable packages. This approach is the one we recommend. A Visual C++ Redistributable package is an executable that installs Visual C++ libraries as shared DLLs in *`%windir%\system32\`*. (Installation in this folder requires administrator rights.) You can create a *bootstrapper*, a script or setup program that runs the Redistributable package before installing your application on the target computer. Redistributable packages are available for the x86, x64, ARM64, and ARM platforms. For more information on where to find the package files, see [Locate the Redistributable files](redistributing-visual-cpp-files.md#locate-the-redistributable-files). For information about how to use a Redistributable package, see [Walkthrough: Deploying a Visual C++ Application By Using the Visual C++ Redistributable Package](deploying-visual-cpp-application-by-using-the-vcpp-redistributable-package.md). -- Central deployment by using merge modules, each of which installs a particular Visual C++ library as a shared DLL in %windir%\system32\\. (Installation to this folder requires administrator rights.) Merge modules become part of the .msi installer file for your application. Visual C++ redistributable merge modules are included in Visual Studio, in \Program Files (x86)\Common Files\Merge Modules\\. For more information, see [Redistributing By Using Merge Modules](redistributing-components-by-using-merge-modules.md). +- Central deployment by using merge modules. This method is deprecated because libraries deployed this way can't be updated automatically by Windows Update. You can use merge modules to install a particular Visual C++ library as a shared DLL in *`%windir%\system32\`*. (Installation to this folder requires administrator rights.) Merge modules become part of the *`.msi`* installer file for your application. Because they've been deprecated, Visual C++ Redistributable merge modules are an optional, installable component in Visual Studio 2022 and 2019. They're installed by default in Visual Studio 2017 and 2015. For more information, see [Where to find merge module files](redistributing-components-by-using-merge-modules.md#where-to-find-merge-module-files). -- Local deployment, in which you copy particular Visual C++ DLLs from your Visual Studio installation—typically in \Program Files (x86)\Microsoft Visual Studio `version`\VC\Redist\\`platform`\\`library`\—and install them on target computers in the same folder as the application executable. You can use this deployment method to enable installation by users who don't have administrator rights, or for applications that can be run from a network share. +- Local deployment. Local deployment isn't recommended in most situations. In local deployment, you copy particular Visual C++ DLLs from your Visual Studio installation—typically in *`\%VCINSTALLDIR%Redist\MSVC\\\`*—and install them on target computers in the same folder as the application executable. You can use this deployment method to enable installation by users who don't have administrator rights. Or, for applications that can be run from a thumb drive or a network share. -If a deployment uses redistributable merge modules and an installation is run by a user who does not have administrative rights, the Visual C++ DLLs are not installed and the application will not run. Also, application installers built with merge modules that allow installation on a per-user basis install the libraries in a shared location that impacts all users of the system. You can use local deployment to install the required Visual C++ DLLs in the directory of a particular user's application without affecting other users or requiring administrator rights. Because this can create serviceability issues, we do not recommend local deployment of Visual C++ redistributable DLLs. +If a deployment uses Redistributable merge modules, the user who installs the app must have administrative rights. Otherwise, the Visual C++ DLLs aren't installed and the application might not run. Application installers that allow installation on a per-user basis install the libraries in a shared location that impacts all users of the system. You can use local deployment to install the required Visual C++ DLLs in the directory of a particular user's application. This approach won't affect other users or require administrator rights. Because it can create serviceability issues, we don't recommend local deployment of Visual C++ Redistributable DLLs. -Incorrect deployment of Visual C++ libraries may cause run-time errors during execution of an application that depends on them. When the operating system loads the application, it uses the search order described in [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw). +Incorrect deployment of Visual C++ libraries may cause run-time errors during execution of an application that depends on them. When the operating system loads the application, it uses the search order described in [`LoadLibraryEx`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw). -## Dynamic Linking Is Better than Static Linking +## Dynamic linking is better than static linking -We recommend that you avoid static linking when you redistribute Visual C++ libraries. Although static linking almost never significantly improves application performance, it almost always makes servicing more expensive. For example, consider an application that's statically linked to a library that's been updated with security enhancements—the application cannot benefit unless it is recompiled and redeployed. Instead, we recommend that you dynamically link your applications to the libraries they depend on so that the libraries can be updated wherever they're deployed. +We recommend that you avoid static linking when you redistribute Visual C++ libraries. Although static linking almost never significantly improves application performance, it almost always makes servicing more expensive. For example, consider a statically linked application with a library that's been updated with security enhancements. The application can't benefit unless it's recompiled and redeployed. Instead, we recommend that you dynamically link your applications to the libraries they depend on. Then the libraries can be updated wherever they're deployed. ## See also -[Deploying Desktop Applications](deploying-native-desktop-applications-visual-cpp.md)
-[ClickOnce Security and Deployment](/visualstudio/deployment/clickonce-security-and-deployment)
-[Deployment Examples](deployment-examples.md) +[Deploying desktop applications](deploying-native-desktop-applications-visual-cpp.md)\ +[ClickOnce security and deployment](/visualstudio/deployment/clickonce-security-and-deployment)\ +[Deployment examples](deployment-examples.md) diff --git a/docs/windows/clickonce-deployment-for-visual-cpp-applications.md b/docs/windows/clickonce-deployment-for-visual-cpp-applications.md index 4a36f96cb6..07698cb3de 100644 --- a/docs/windows/clickonce-deployment-for-visual-cpp-applications.md +++ b/docs/windows/clickonce-deployment-for-visual-cpp-applications.md @@ -3,7 +3,6 @@ description: "Learn more about: ClickOnce Deployment for Visual C++ Applications title: "ClickOnce Deployment for Visual C++ Applications" ms.date: "11/04/2016" helpviewer_keywords: ["deploying applications [C++], ClickOnce", "application deployment [C++], ClickOnce", "ClickOnce deployment [C++], C++ applications"] -ms.assetid: 9988c546-0936-452c-932f-9c76daa42157 --- # ClickOnce Deployment for Visual C++ Applications @@ -11,20 +10,18 @@ Visual Studio provides two different technologies for deploying Windows applicat ## ClickOnce Deployment in C++ -The Visual C++ development environment does not directly support deployment of Visual Studio C++ projects with ClickOnce, but tools are available to use it. - > [!NOTE] -> Visual Studio does support ClickOnce in the Visual C# and Visual Basic development environments. If your Visual Studio C++ project is a dependency of a Visual C# project, you can publish the application (including its dependencies) using ClickOnce deployment from the Visual C# development environment. +> ClickOnce does not support deployment of native C++ applications. However, you can use ClickOnce to deploy a Visual C++ application if it is a dependency of a Visual C# or VB.NET project. For example, if you have a Visual C# project that depends on a Visual C++ project, you can publish the application (including its dependencies) using ClickOnce deployment from the Visual C# development environment. If you have a Visual Basic .NET project that depends on a Visual C++ project, you can publish the application (including its dependencies) using ClickOnce deployment from the Visual Basic .NET development environment. To deploy a Visual C++ application using ClickOnce, you first have to build a [ClickOnce Application Manifest](/visualstudio/deployment/clickonce-application-manifest) and a [ClickOnce Deployment Manifest](/visualstudio/deployment/clickonce-deployment-manifest) using the [Mage.exe (Manifest Generation and Editing Tool)](/dotnet/framework/tools/mage-exe-manifest-generation-and-editing-tool) or its graphical user interface version (for information, see [MageUI.exe (Manifest Generation and Editing Tool, Graphical Client)](/dotnet/framework/tools/mageui-exe-manifest-generation-and-editing-tool-graphical-client)). -You first use Mage.exe to build the application manifest; the resulting file will have the extension .manifest. You then use Mage.exe to build the deployment manifest; the resulting file will have the extension .application. You then sign the manifests. +You first use Mage.exe to build the application manifest; the resulting file will have the extension .manifest. You then use Mage.exe to build the deployment manifest; the resulting file will have the extension `.application`. You then sign the manifests. The application manifest must specify the target processor (**x86**, **x64**, or **ARM**). See [Deploying Prerequisites for 64-bit Applications](/visualstudio/deployment/deploying-prerequisites-for-64-bit-applications) for information on these options. Also, the name of the application and deployment manifests must be different from the name of the C++ application. This avoids conflict between the application manifest created by Mage.exe and the external manifest that is part of the C++ application. -Your deployment will need to install any Visual C++ libraries on which your application depends. To determine the dependencies for a particular application, you can use depends.exe or the DUMPBIN utility with the /DEPENDENTS option. For more information on dependencies, see [Understanding the Dependencies of a Visual C++ Application](understanding-the-dependencies-of-a-visual-cpp-application.md). You might need to run VCRedist.exe; this utility installs Visual C++ libraries on the target computer. +Your deployment needs to install any Visual C++ libraries on which your application depends. To determine the dependencies for a particular application, you can use depends.exe or the `DUMPBIN` utility with the `/DEPENDENTS` option. For more information on dependencies, see [Understanding the Dependencies of a Visual C++ Application](understanding-the-dependencies-of-a-visual-cpp-application.md). You might need to run VCRedist.exe; this utility installs Visual C++ libraries on the target computer. You may also need to build a bootstrapper (prerequisites installer) for your application to deploy prerequisite components; for information on the bootstrapper, see [Creating Bootstrapper Packages](/visualstudio/deployment/creating-bootstrapper-packages). diff --git a/docs/windows/controls-in-dialog-boxes.md b/docs/windows/controls-in-dialog-boxes.md index a6c53fd36d..7dd305bb82 100644 --- a/docs/windows/controls-in-dialog-boxes.md +++ b/docs/windows/controls-in-dialog-boxes.md @@ -1,6 +1,6 @@ --- description: "Learn more about: Dialog Box Controls (C++)" -title: "Dialog Box Controls (C++)| Microsoft Docs" +title: Dialog Box Controls (C++) ms.date: "02/15/2019" f1_keywords: ["Custom Control"] helpviewer_keywords: ["controls [C++], dialog boxes", "dialog box controls [C++], about dialog box controls", "dialog box controls", "controls [C++], templates", "custom controls [C++], dialog boxes", "custom controls [C++]", "dialog box controls [C++], custom (user) controls", "Dialog Editor [C++], custom controls"] diff --git a/docs/windows/creating-an-icon-or-other-image-image-editor-for-icons.md b/docs/windows/creating-an-icon-or-other-image-image-editor-for-icons.md index 004896d77c..19767ebd32 100644 --- a/docs/windows/creating-an-icon-or-other-image-image-editor-for-icons.md +++ b/docs/windows/creating-an-icon-or-other-image-image-editor-for-icons.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: How To: Create an Icon or Other Image" -title: "How To: Create an Icon or Other Image" -ms.date: "02/15/2019" +description: "Create an Icon or Other Image" +title: "Learn how to create a new image, bitmap, icon, cursor, or toolbar, and then use the Image Editor to customize its appearance." +ms.date: 03/21/2025 +ms.topic: how-to helpviewer_keywords: ["bitmaps [C++]", "images [C++], creating", "resources [C++], creating images", "bitmaps [C++], creating", "graphics [C++], creating", "Image editor [C++], creating images", "cursors [C++], creating", "image resources [C++], display devices", "icons [C++], creating", "cursors [C++], types", "icons [C++]", "Image editor [C++], icons and cursors", "cursors [C++]", "display devices [C++], creating icons for", "cursors [C++], hot spots", "icons [C++], types", "icons [C++], creating", "display devices [C++], creating image", "images [C++], creating for display devices", "icons [C++], inserting", "New Image Type dialog box [C++]", "Custom Image dialog box [C++]", "Open Image dialog box [C++]", "New Device Image command", "display devices [C++], adding images", "cursors [C++], adding", "icons, adding", "display devices [C++], copying images", "cursors [C++], copying", "icons, copying", "cursors [C++], deleting", "display devices [C++], deleting device image", "icons, erasing", "icons, deleting", "cursors [C++], undoing changes", "icons, undoing changes", "cursors [C++], screen regions", "inverse colors [C++], device images", "transparent regions, device images", "transparency, device images", "Image editor [C++], device images", "inverse regions, device images", "cursors [C++], transparent regions", "screen colors", "regions, transparent", "icons [C++], transparent regions", "display devices [C++], transparent and screen regions", "transparent regions in devices", "regions, inverse", "colors [C++], Image editor", "device projects [C++], transparent images", "icons [C++], screen regions", "256-color palette", "cursors [C++], color", "colors [C++], icons", "colors [C++], cursors", "icons, color", "colors [C++], icons and cursors", "color palettes, 256-color", "palettes, 256-color", "cursors [C++], hot spots", "hot spots", ".gif files [C++], saving bitmaps as", "jpg files [C++], saving bitmaps as", "jpeg files [C++], saving bitmaps as", ".jpg files [C++], saving bitmaps as", "Image editor [C++], converting image formats", "gif files [C++], saving bitmaps as", "bitmaps [C++], converting formats", ".jpeg files [C++], saving bitmaps as", "graphics [C++], converting formats", "images [C++], converting formats", "images [C++], stand-alone editing", "Image editor [C++], converting image formats", "graphics [C++], converting formats", "images [C++], converting formats"] ms.assetid: 66db3fb2-cfc1-48a2-9bdd-53f61eb7ee30 --- -# How To: Create an Icon or Other Image +# Create an icon or other image You can create a new image, bitmap, icon, cursor, or toolbar, and then use the **Image Editor** to customize its appearance. You can also create a new bitmap patterned after a [resource template](./how-to-create-a-resource-script-file.md). -## Icons and Cursors: Image Resources for Display Devices +## Icons and cursors: image resources for display devices -Icons and cursors are graphical resources that can contain multiple images in different sizes and color schemes for different types of display devices. A cursor also has a hot spot, the location Windows uses to track its position. Both icons and cursors are created and edited using the **Image Editor**, as are bitmaps and other images. +Icons and cursors are graphical resources that can contain multiple images in different sizes and color schemes for different types of display devices. A cursor also has a hot spot, which is the location that Windows uses to track its position. Both icons and cursors are created and edited using the **Image Editor**, as are bitmaps and other images. When you create a new icon or cursor, the **Image Editor** first creates an image of a standard type. The image is initially filled with the screen (transparent) color. If the image is a cursor, the hot spot is initially the upper-left corner with coordinates `0,0`. -By default, the **Image Editor** supports the creation of additional images for the devices shown in the following table. You can create images for other devices by typing width, height, and color-count parameters into the **Custom Image** dialog box. +By default, the **Image Editor** supports the creation of new images for the devices shown in the following table. You can create images for other devices by typing width, height, and color-count parameters into the **Custom Image** dialog box. |Color|Width (pixels)|Height (pixels)| -|-----------|----------------------|-----------------------| +|-----|--------------|---------------| |Monochrome|16|16| |Monochrome|32|32| |Monochrome|48|48| @@ -37,12 +38,12 @@ By default, the **Image Editor** supports the creation of additional images for ### Create a device image (icon or cursor) -When you create a new icon or cursor resource, the **Image Editor** first creates an image in a specific style (32 × 32, 16 colors for icons and 32 × 32, Monochrome for cursors). You can then add images in different sizes and styles to the initial icon or cursor and edit each additional image, as needed, for the different display devices. You can also edit an image by using a cut-and-paste operation from an existing image type or from a bitmap created in a graphics program. +When you create a new icon or cursor resource, the **Image Editor** first creates an image in a specific style: 32 × 32 pixels and 16 colors for icons; 32 × 32 pixels and monochrome for cursors. You can then add images in different sizes and styles to the initial icon or cursor, and edit each additional image, as needed, for the different display devices. You can also edit an image by using a cut-and-paste operation from an existing image type or from a bitmap created in a graphics program. When you open the icon or cursor resource in the [Image Editor](../windows/image-editor-for-icons.md), the image most closely matching the current display device is opened by default. > [!NOTE] -> If your project doesn't already contain an .rc file, see [Creating a New Resource Script File](../windows/how-to-create-a-resource-script-file.md). +> If your project doesn't already contain an *`.rc`* file, see [Create Resources (C++)](../windows/how-to-create-a-resource-script-file.md). The **New \ Image Type** dialog box enables you to create a new device image of a specified type. To open the **New \ Image** dialog box, go to menu **Image** > **New Image Type**. The following properties included are **Target Image Type** and **Custom**. @@ -50,40 +51,46 @@ The **Target Image Type** property lists the available image types where you sel :::row::: :::column span=""::: - 16 x 16, 16 colors\ - 32 x 32, 16 colors\ - 48 x 48, 16 colors\ - 64 x 64, 16 colors\ - 96 x 96, 16 colors + 16 x 16, 1 bit (monochrome)\ + 16 x 16, 24 bit (16 million colors)\ + 16 x 16, 4 bit (16 colors)\ + 128 x 128, 1 bit (monochrome)\ + 128 x 128, 24 bit (16 million colors)\ + 128 x 128, 4 bit (16 colors)\ + 128 x 128, 8 bit (256 colors) :::column-end::: :::column span=""::: - 16 x 16, 256 colors\ - 32 x 32, 256 colors\ - 48 x 48, 256 colors\ - 64 x 64, 256 colors\ - 96 x 96, 256 colors + 256 x 256, 1 bit (monochrome)\ + 256 x 256, 24 bit (16 million colors)\ + 256 x 256, 4 bit (16 colors)\ + 256 x 256, 8 bit (256 colors)\ + 32 x 32, 1 bit (monochrome)\ + 32 x 32, 24 bit (16 million colors)\ + 32 x 32, 4 bit (16 colors) :::column-end::: :::column span=""::: - 16 x 16, Monochrome\ - 32 x 32, Monochrome\ - 48 x 48, Monochrome\ - 64 x 64, Monochrome\ - 96 x 96, Monochrome + 48 x 48, 1 bit (monochrome)\ + 48 x 48, 24 bit (16 million colors)\ + 48 x 48, 4 bit (16 colors)\ + 64 x 64, 1 bit (monochrome)\ + 64 x 64, 24 bit (16 million colors)\ + 64 x 64, 4 bit (16 colors)\ + 64 x 64, 8 bit (256 colors) :::column-end::: :::row-end::: > [!NOTE] -> Any existing images will not be displayed in this list. +> Existing images are not displayed in this list. The **Custom** property opens the **Custom Image** dialog box in which you can create a new image with a custom size and number of colors. -The **Custom Image** dialog box enables you to create a new image with a custom size and number of colors. The following properties included are: +The **Custom Image** dialog box allows you to create a new image with a custom size and number of colors. The following properties included are: |Property|Description| |---|---| -|**Width**|Provides a space for you to enter the width of the custom image in pixels (1 - 512, limit of 2048).| -|**Height**|Provides a space for you to enter the height for the custom image in pixels (1 - 512, limit of 2048).| -|**Colors**|Provides a space for you to choose the number of colors for the custom image: 2, 16, or 256.| +|**Width**|Provides a space for you to enter the width of the custom image in pixels (1 - 512, limit of 2048)| +|**Height**|Provides a space for you to enter the height for the custom image in pixels (1 - 512, limit of 2048)| +|**Colors**|Provides a space for you to choose the number of bits for color for the custom image: 1, 4, 8, 24| Use the **Open \ Image** dialog box to open device images in C++ projects. It lists existing device images in the current resource (images that are part of the current resource). The following property included is: @@ -93,9 +100,9 @@ Use the **Open \ Image** dialog box to open device images in C++ project #### To create a new icon or cursor -1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *.rc* file, then choose **Insert Resource**. If you already have an existing image resource in your *.rc* file, such as a cursor, you can right-click the **Cursor** folder and select **Insert Cursor**. +1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *`.rc`* file, then choose **Add Resource**. If you already have an existing image resource in your *`.rc`* file, such as a cursor, you can right-click the **Cursor** folder and select **Insert Cursor**. -1. In the [Insert Resource dialog box](./how-to-create-a-resource-script-file.md), select **Icon** or **Cursor** and choose **New**. For icons, this action creates an icon resource with a 32 × 32, 16-color icon. For cursors, a 32 × 32, Monochrome (2-color) image is created. +1. In the [Add Resource dialog box](./how-to-create-a-resource-script-file.md), select **Icon** or **Cursor** and choose **New**. For icons, this action creates an icon resource with a 32 × 32, 16-color icon. For cursors, a 32 × 32, monochrome image is created. If a plus sign (**+**) appears next to the image resource type in the **Insert Resource** dialog box, it means that toolbar templates are available. Select the plus sign to expand the list of templates, select a template, and choose **New**. @@ -120,11 +127,11 @@ Use the **Open \ Image** dialog box to open device images in C++ project While the icon image is displayed in the **Image Editor**, go to menu **Image** > **Delete Device Image**. When you delete the last icon image in the resource, the resource is also deleted. > [!NOTE] -> When you press the **Del** key, the images and colors you have drawn on an icon are deleted but the icon remains and you can now redesign it. If you press **Del** by mistake, press **Ctrl**+**Z** to undo the action. +> When you press the **Del** key, the images and colors you drew on an icon are deleted but the icon remains and you can now redesign it. If you press **Del** by mistake, press **Ctrl**+**Z** to undo the action. ### To create transparent or inverse regions in device images -In the [Image Editor](../windows/image-editor-for-icons.md), the initial icon or cursor image has a transparent attribute. Although icon and cursor images are rectangular, many don't appear so because parts of the image are transparent and the underlying image on the screen shows through the icon or cursor. When you drag an icon, parts of the image may appear in an inverted color. You create this effect by setting the screen color and inverse color in the [Colors window](./image-editor-for-icons.md). +In the [Image Editor](../windows/image-editor-for-icons.md), the initial icon or cursor image has a transparent attribute. Although icon and cursor images are rectangular, many don't appear so because parts of the image are transparent and the underlying image on the screen shows through the icon or cursor. When you drag an icon, parts of the image might appear in an inverted color. You create this effect by setting the screen color and inverse color in the [Colors window](./image-editor-for-icons.md). The screen and inverse colors you apply to icons and cursors either shape and color the derived image or assign inverse regions. The colors indicate parts of the image that have those attributes. You can change the colors that represent the screen-color and inverse-color attributes in editing. These changes don't affect the appearance of the icon or cursor in your application. @@ -154,9 +161,9 @@ Using the **Image Editor**, icons and cursors can be sized large (64 × 64) with #### To create a 256-color icon or cursor -1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *.rc* file, then choose **Insert Resource**. If you already have an existing image resource in your *.rc* file, such as a cursor, you can right-click the **Cursor** folder and select **Insert Cursor**. +1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *`.rc`* file, then choose **Add Resource**. If you already have an existing image resource in your *`.rc`* file, such as a cursor, you can right-click the **Cursor** folder and select **Insert Cursor**. -1. In the [Insert Resource dialog box](./how-to-create-a-resource-script-file.md), select **Icon** or **Cursor** and choose **New**. +1. In the [Add Resource dialog box](./how-to-create-a-resource-script-file.md), select **Icon** or **Cursor** and choose **New**. 1. Go to menu **Image** > **New Device Image** and select the 256-color image style you want. @@ -168,7 +175,7 @@ To draw with a selection from the 256-color palette, you need to select the colo 1. Choose a color from the 256 colors displayed in the **Colors** palette in the **Colors** window. - The color selected will become the current color in the **Colors** palette in the **Colors** window. + The color selected becomes the current color in the **Colors** palette in the **Colors** window. > [!NOTE] > The initial palette used for 256-color images matches the palette returned by the `CreateHalftonePalette` Windows API. All icons intended for the Windows shell should use this palette to prevent flicker during palette realization. @@ -183,9 +190,9 @@ The hot spot of a cursor is the point to which Windows refers in tracking the cu The **Hotspot** property in the **Properties** window displays the new coordinates. -### To create and save a bitmap as a .gif or .jpeg +### To create and save a bitmap as GIF or JPEG -When you create a bitmap, the image is created in bitmap format (.bmp). You can, however, save the image as a GIF or JPEG or in other graphic formats. +When you create a bitmap, the image is created in bitmap format (*`.bmp`*). You can, however, save the image as a *`.gif`* or *`.jpeg`* or in other graphic formats. > [!NOTE] > This process doesn't apply to icons and cursors. @@ -203,7 +210,7 @@ When you create a bitmap, the image is created in bitmap format (.bmp). You can, 1. In the **Save File As** dialog box, type the name you want to give the file and the extension that denotes the file format you want in the **File Name** box. For example, *myfile.gif*. > [!NOTE] - > You must create or open the bitmap outside of your project in order to save it as another file format. If you create or open it within your project, the **Save As** command will be unavailable. For more information, see [Viewing Resources in a Resource Script File Outside of a Project (Standalone)](./how-to-create-a-resource-script-file.md). + > You must create or open the bitmap outside of your project in order to save it as another file format. If you create or open it within your project, the **Save As** command is unavailable. For more information, see [Viewing Resources in a Resource Script File Outside of a Project (Standalone)](./how-to-create-a-resource-script-file.md). 1. Select **Save**. @@ -221,11 +228,11 @@ You can open GIF or JPEG images in the **Image Editor** and save them as bitmaps ### To add a new image resource to an unmanaged C++ project -1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *.rc* file, then choose **Insert Resource**. If you already have an existing image resource in your *.rc* file, such as a cursor, you can simply right-click the **Cursor** folder and select **Insert Cursor**. +1. In [Resource View](how-to-create-a-resource-script-file.md#create-resources), right-click your *`.rc`* file, then choose **Add Resource**. If you already have an existing image resource in your *`.rc`* file, such as a cursor, you can right-click the **Cursor** folder and select **Insert Cursor**. -1. In the [Insert Resource dialog box](./how-to-create-a-resource-script-file.md), select the type of image resource you'd like to create (**Bitmap**, for example) then choose **New**. +1. In the [Add Resource dialog box](./how-to-create-a-resource-script-file.md), select the type of image resource you'd like to create (**Bitmap**, for example) then choose **New**. - If a plus sign (**+**) appears next to the image resource type in the **Insert Resource** dialog box, it means that toolbar templates are available. Select the plus sign to expand the list of templates, select a template, and choose **New**. + If a plus sign (**+**) appears next to the image resource type in the **Add Resource** dialog box, it means that toolbar templates are available. Select the plus sign to expand the list of templates, select a template, and choose **New**. ### To add a new image resource to a project in a .NET programming language @@ -239,17 +246,13 @@ You can open GIF or JPEG images in the **Image Editor** and save them as bitmaps The resource is added to your project in **Solution Explorer** and the resource opens in the [Image Editor](../windows/image-editor-for-icons.md). You can now use all the tools available in the **Image Editor** to modify your image. For more information on adding images to a managed project, see [Loading a Picture at Design Time](/dotnet/framework/winforms/controls/how-to-load-a-picture-using-the-designer-windows-forms). -## Requirements - -None - ## See also -[Image Editor for Icons](../windows/image-editor-for-icons.md)
-[How to: Edit an Image](../windows/selecting-an-area-of-an-image-image-editor-for-icons.md)
-[How to: Use a Drawing Tool](../windows/using-a-drawing-tool-image-editor-for-icons.md)
-[How to: Work with Color](../windows/working-with-color-image-editor-for-icons.md)
-[Accelerator Keys](../windows/accelerator-keys-image-editor-for-icons.md)
+- [Image Editor for Icons](../windows/image-editor-for-icons.md) +- [How to: Edit an Image](../windows/selecting-an-area-of-an-image-image-editor-for-icons.md) +- [How to: Use a Drawing Tool](../windows/using-a-drawing-tool-image-editor-for-icons.md) +- [How to: Work with Color](../windows/working-with-color-image-editor-for-icons.md) +- [Accelerator Keys](../windows/accelerator-keys-image-editor-for-icons.md)